From 7cfc04c24de26e8b8bab4ac6873c1fd74ee149c6 Mon Sep 17 00:00:00 2001 From: Packit Date: Oct 07 2020 19:42:01 +0000 Subject: man-pages-4.15 base --- diff --git a/Changes b/Changes new file mode 100644 index 0000000..61b339c --- /dev/null +++ b/Changes @@ -0,0 +1,289 @@ +==================== Changes in man-pages-4.15 ==================== + +Released: 2018-02-02, Palo Alto + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Adam Liddell +Andrea Parri +Andries E. Brouwer +Elie Roudninski +Eric Benton +Florian Weimer +G. Branden Robinson +Jakub Wilk +Joel Williamson +John Hubbard +Jorgen Hansen +Keno Fischer +Michael Kerrisk +Michal Hocko +NeilBrown +Nikola Forró +Nikolay Borisov +Pradeep Kumar +QingFeng Hao +Ricardo Biehl Pasquali +roblabla +Roman Gushchin +Shawn Landden +Stefan Hajnoczi +Stefan Raspl +Tejun Heo + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +s390_sthyi.2 + QingFeng Hao [Michael Kerrisk] + New page for s390-specific s390_sthyi(2) + +network_namespaces.7 + Michael Kerrisk + New page describing network namespaces + Based on content moved from namespaces(7) + Michael Kerrisk + Reorganize text + No content changes... + Michael Kerrisk + When a NW namespace is freed, veth devices are destroyed + +vsock.7 + Stefan Hajnoczi [Jorgen Hansen, Michael Kerrisk] + Document the VSOCK socket address family + + +Newly documented interfaces in existing pages +--------------------------------------------- + +cgroups.7 + Michael Kerrisk [Tejun Heo] + Document cgroups v2 "thread mode" + Michael Kerrisk [Tejun Heo] + Document cgroup v2 delegation via the 'nsdelegate' mount option + Michael Kerrisk + Document the cgroup.max.depth and cgroup.max.descendants files + Michael Kerrisk + Document 'release_agent' mount option + Michael Kerrisk [Roman Gushchin] + Document /sys/kernel/cgroup/delegate + Michael Kerrisk [Roman Gushchin] + Document /sys/kernel/cgroup/features + Michael Kerrisk [Roman Gushchin] + Document cgroups v2 cgroup.stat file + + +Global changes +-------------- + +Various pages + G. Branden Robinson + Standardize on "nonzero" + Also add this term to the style guide in man-pages(7). + + +Changes to individual pages +--------------------------- + +bpf.2 + Nikolay Borisov + Sync list of supported map types with 4.14 kernel + +copy_file_range.2 + Michael Kerrisk + Library support was added in glibc 2.27 + Shawn Landden + glibc provides a user-space emulation where the system call is absent + Florian Weimer + EFBIG errors are possible, similar to write(2) + Michael Kerrisk + ERRORS: add EISDIR + Michael Kerrisk + Order ERRORS alphabetically + Michael Kerrisk + Add comment to code example explaining use of syscall(2) + +fcntl.2 +read.2 +write.2 + NeilBrown + Document "Lost locks" as cause for EIO. + If an advisory lock is lost, then read/write requests on any + affected file descriptor can return EIO - for NFSv4 at least. + +memfd_create.2 + Michael Kerrisk + glibc support for memfd_create() was added in version 2.27 + +mlock.2 + Michael Kerrisk + Make details for MLOCK_ONFAULT a little more explicit + Michael Kerrisk + glibc support for mlock2() is added in version 2.27 + +mmap.2 + John Hubbard [Michael Hocko] + MAP_FIXED is no longer discouraged + MAP_FIXED has been widely used for a very long time, yet the man + page still claims that "the use of this option is discouraged". + John Hubbard + MAP_FIXED updated documentation + -- Expand the documentation to discuss the hazards in + enough detail to allow avoiding them. + + -- Mention the upcoming MAP_FIXED_SAFE flag. + + -- Enhance the alignment requirement slightly. + +mount.2 + Keno Fischer [Michael Kerrisk] + Add EINVAL error condition when MS_BINDing MNT_LOCKED submounts + +mprotect.2 +pkey_alloc.2 + Michael Kerrisk + Glibc support for memory protection keys was added in version 2.27 + +perf_event_open.2 + Michael Kerrisk + SEE ALSO: add perf(1) + +pkey_alloc.2 + Michael Kerrisk + Clarify description of pkey_alloc() 'flags' argument + +prctl.2 + Michael Kerrisk + Defer to capabilities(7) for discussion of the "keep capabilities" flag + +recvmmsg.2 +sendmmsg.2 + Nikola Forró + Point out that error handling is unreliable + +seccomp.2 + Michael Kerrisk + Clarify that SECCOMP_RET_TRAP SIGSYS signal is thread-directed + +syscalls.2 + Michael Kerrisk + Add s390-specific s390_sthyi(2) to syscall list + +unshare.2 + Michael Kerrisk + Clarify the EUSERS occurred only until kernel 4.8 + +errno.3 + Michael Kerrisk + 'errno -s' can be used to search for errors by string in description + Michael Kerrisk + Add Linux error text corresponding to ENOMEM + +fgetpwent.3 + Michael Kerrisk + Add missing ATTRIBUTES preamble + +fts.3 + Michael Kerrisk [Pradeep Kumar] + fts_pathlen = strlen(fts_path) + strlen(fts_name) + +fuse.4 + Michael Kerrisk + Places errors in alphabetical order (no content changes) + +veth.4 + Michael Kerrisk + Add network_namespaces(7) + +sysfs.5 + Michael Kerrisk + Refer to cgroups(7) for information about files in /sys/kernel/cgroup + +capabilities.7 + Michael Kerrisk + Note which capability sets are affected by SECBIT_NO_SETUID_FIXUP + Note explicitly that SECBIT_NO_SETUID_FIXUP is relevant for + the permitted, effective, and ambient capability sets. + Michael Kerrisk + Deemphasize the ancient prctl(2) PR_SET_KEEPCAPS command + The modern approach is SECBITS_KEEP_CAPS. + Michael Kerrisk + Clarify effect of CAP_SETFCAP + Make it clear that CAP_SETFCAP allows setting arbitrary + capabilities on a file. + Michael Kerrisk + Clarify which capability sets are effected by SECBIT_KEEP_CAPS + This flag has relevance only for the process permitted and + effective sets. + Michael Kerrisk + Rephrase CAP_SETPCAP description + * Mention kernel versions. + * Place current kernel behavior first + Michael Kerrisk + SECBIT_KEEP_CAPS is ignored if SECBIT_NO_SETUID_FIXUP is set + Michael Kerrisk + Ambient set is also cleared when UIDs are set to nonzero value + +cgroups.7 + Michael Kerrisk + Add a more complete description of cgroup v1 named hierarchies + Michael Kerrisk + Add a section on unmounting cgroup v1 filesystems + Michael Kerrisk + Add subsection describing cgroups v2 subtree delegation + Michael Kerrisk + Mention ENOENT error that can occur when writing to subtree_control file + Michael Kerrisk + Add list of currently available version 2 controllers + Nikolay Borisov + Add information about RDMA controller + Michael Kerrisk + Rewrite the description of cgroup v2 subtree control + Michael Kerrisk [Tejun Heo] + Note Linux 4.11 changes to cgroup v2 delegation containment rules + Michael Kerrisk + systemd(1) nowadays automatically mounts the cgroup2 filesystem + Michael Kerrisk + Clarify that cgroup.controllers is read-only + Michael Kerrisk + Elaborate a little on problems of splitting threads across cgroups in v1 + Michael Kerrisk [Tejun Heo] + Tweak the description of delegation of cgroup.subtree_control + +ip.7 + Ricardo Biehl Pasquali + INADDR_* values cannot be assigned directly to 's_addr' + Michael Kerrisk + s/INADDR_ANY/INADDR_LOOPBACK/ in discussion of htonl() + INADDR_LOOPBACK is a better example, since it is not + byte-order neutral. + +namespaces.7 +network_namespaces.7 + Michael Kerrisk + Move content from namespaces(7) to network_namespaces(7) + +pid_namespaces.7 + Michael Kerrisk + SEE ALSO: add mount_namespaces(7) + +sched.7 + Michael Kerrisk [Andrea Parri] + Correctly describe effect of priority changes for RT threads + The placement of a thread in the run queue for its new + priority depends on the direction of movement in priority. + (This appears to contradict POSIX, except in the case of + pthread_setschedprio().) + +user_namespaces.7 + Michael Kerrisk + Mention NS_GET_OWNER_UID ioctl() operation diff --git a/Changes.old b/Changes.old new file mode 100644 index 0000000..3256cd9 --- /dev/null +++ b/Changes.old @@ -0,0 +1,47220 @@ +==================== Changes in man-pages-2.00 ==================== + +Released: 2004-12-16 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alberto Bertogli +Anand Kumria +Andrey Kiselev +Andries Brouwer +Chris Green +Branden Robinson +Emmanuel Colbus +Enrico Zini +Eric Estievenart +Fabian Kreutz +Florian Weimer +Jan Kuznik +Joey (Martin) Schulze +Johannes Berg +John V. Belmonte +Karel Kulhavy +Luis Javier Merino Morán +Martin Pool +Richard Kreckel +Vasya Pupkin + +Apologies if I missed anyone! + +Global changes +-------------- + +Various pages + Fabian Kreutz + Many math pages had their synopses compressed, as per suggestion + from Fabian Kreutz. + +Various pages + Fabian Kreutz / aeb + Many minor content and formatting bug fixes were made to the math + pages, following suggestions from Fabian Kreutz (who recently + translated many of the 1.70 math pages into German) and + Andries Brouwer. + +Various pages + mtk + For consistency, all instances of "super-user" were changed + to the more common "superuser". + +Various pages + Vasya Pupkin / mtk + After a note from Vasya Pupkin, I added to the SYNOPSIS + of several Section 2 pages using the _syscallN() macros. + + In addition: + -- erroneous semicolons at the end of _syscallN() were removed + on various pages. + + -- types such as "uint" in syscallN() declarations were changed + to "unsigned int", etc. + + -- various other minor breakages in the synopses were fixed. + + The affected pages are: + + getdents.2 + gettid.2 + llseek.2 + mmap2.2 + modify_ldt.2 + pivot_root.2 + quotactl.2 + readdir.2 + sysctl.2 + syslog.2 + tkill.2 + +Typographical or grammatical errors have been corrected in several +other places. + +Changes to individual pages +--------------------------- + +bind.2 + Florian Weimer + Added 'const' to declaration of 'my_addr' in prototype. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=239762. + +fcntl.2 + Martin Pool + Added O_NOATIME to list of flags that can be changed via F_SETFL. + mtk/aeb + Noted F_GETOWN bug after suggestion from aeb. + See also: + http://marc.theaimsgroup.com/?l=linux-kernel&m=108380640603164&w=2 + +getrlimit.2 + mtk + Material on getrusage.2 has been separated out into its own page. + Rewrote discussion on RLIMIT_MEMLOCK to incorporate kernel + 2.6.9 changes. + Added note on RLIMIT_CPU error in older kernels. + Added RLIMIT_SIGPENDING. + Also made a few other minor changes. + +getrusage.2 + mtk + This page is new(ish) -- it was created by splitting + getrlimit.2. + + Repaired note on SIGCHLD behavior to note that the + POSIX non-conformance has been fixed in 2.6.9. + +kill.2 + Modified after suggestion from Emmanuel Colbus + Changed wording of sentence under NOTES describing + when signals can be sent to init(1). + +mlock.2 +munlock.2 +mlockall.2 +munlockall.2 + These have been consolidated into a single mlock.2 page. + In the process, much duplication was eliminated + and new information was added about RLIMIT_MEMLOCK + and the changes in memory locking in kernel 2.6.9, + +mmap.2 + mtk + Added cross-ref to setrlimit(2) concerning memory locking limits. + Eric Estievenart + Note that MAP_FIXED replaces existing mappings + +msgctl.2 + mtk + Substantial language and formatting clean-ups. + Added msqid_ds and ipc_perm structure definitions. + +msgget.2 + mtk + Substantial language and formatting clean-ups. + Added notes on /proc files. + +msgop.2 + mtk + Substantial language and formatting clean-ups. + Added notes on /proc files. + +open.2 + Martin Pool + Added O_NOATIME (new in Linux 2.6.8) + mtk + Reordered list of 'flags' description alphabetically + +personality.2 + 2004-11-03 applied patch from Martin Schulze + +semctl.2 + mtk + Substantial language and formatting clean-ups. + Rewrote semun text. + Added semid_ds and ipc_perm structure definitions. + +semget.2 + mtk + Substantial language and formatting clean-ups. + Added notes on /proc files. + Rewrote BUGS note about semget()'s failure to initialize + semaphore values. + +semop.2 + mtk + Substantial language and formatting clean-ups. + Added notes on /proc files. + +shmctl.2 + mtk + Substantial language and formatting clean-ups. + Updated shmid_ds structure definitions. + Added information on SHM_DEST and SHM_LOCKED flags. + Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK + since kernel 2.6.9. + Added notes on 2.6.9 RLIMIT_MEMLOCK changes. + Added RLIMIT_SIGPENDING (new in Linux 2.6.8) + +shmget.2 + mtk + Substantial language and formatting clean-ups. + Added notes on /proc files. + +shmop.2 + mtk + Substantial language and formatting clean-ups. + Changed wording and placement of sentence regarding attachment + of segments marked for destruction. + +sigaction.2 + mtk + Added mention of SIGCONT under SA_NOCLDSTOP. + Added SA_NOCLDWAIT. + Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags. + Noted that CLD_CONTINUED is supported since Linux 2.6.9. + Added SI_TKILL (new in Linux 2.4.19). + Other minor changes. + +signal.2 + mtk + Removed text on ignoring SIGCHLD; replaced with pointer + to sigaction.2. + +sigwaitinfo.2 + After bug report from Andrey Kiselev + Fixed prototype: "timeout" --> "*timeout" + as per: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=222145 + +stat.2 + Enrico Zini + Added text to clarify that S_IS*() macros should be applied to + st_mode field. + as per: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=249698 + +swapon.2 + After Debian bug report from Anand Kumria + Added "no swap space signature" to EINVAL error. + mtk + Added EINVAL error for swapoff() ("not currently a swap area"). + Added EBUSY error for swapon(). + A few formatting fixes. + +times.2 + mtk + In Linux 2.6, the return value of times changed; it is no + longer time since boot, but rather: + + boot_time + 2^32 / HZ - 300 + + Repaired note on SIGCHLD behavior to note that the + POSIX non-conformance has been fixed in 2.6.9. + Some formatting fixes. + +undocumented.2 + After bug report from Johannes Berg + Changed + .TH UNIMPLEMENTED + to: + .TH UNDOCUMENTED + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=220741 + +wait.2 + mtk + Added waitid(2). + Added WCONTINUED and WIFCONTINUED (new in 2.6.10). + Added text on SA_NOCLDSTOP. + Updated discussion of SA_NOCLDWAIT to reflect 2.6 behavior. + Much other text rewritten. + +wait4.2 + mtk + Rewrote this page, removing much duplicated information, + and replacing with pointers to wait.2. + Luis Javier Merino Morán / mtk + CONFORMING TO said "SVr4, POSIX". Changed to "4.3BSD" + +waitid.2 + mtk + New link to wait.2 + +assert.3 + After bug report from Branden Robinson + The assert() failure message goes to stderr not stdout. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=284814 + +ctime.3 + mtk + Noted that 0 in tm_mday is interpreted to mean the last day + of the preceding month. + +getnameinfo.3 + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=229618 + getnameinfo() does not set errno, it returns a non-zero + value indicating the error. + mtk + added EAI_OVERFLOW error + +killpg.3 + mtk + Minor changes to SEE ALSO and CONFORMING TO. + +lseek64.3 + aeb + New page by Andries Brouwer + +tzset.3 + Richard Kreckel + Change "NULL" to "empty" when talking about the value of TZ. + http://sources.redhat.com/bugzilla/show_bug.cgi?id=601 + +printf.3 + After bug report from Jan Kuznik + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=205736 + Fixed bad realloc() use in snprintf() example + +realpath.3 + mtk + Added discussion of resolved_path == NULL. + +random.4 + After bug report from John V. Belmonte + Updated init and quit scripts to reflect kernel 2.4/2.6 reality + (Scripts taken from drivers/char/random.c) + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=247779 + +proc.5 + mtk + Updated description of /proc/loadavg to include + nr_running(), nr_threads, last_pid. + + rtsig-max and rtsig-nr went away in 2.6.8 + + updated statm, and fixed error in order of list + +boot.7 + applied patch from Martin Schulze + +capabilities.7 + mtk + Added O_NOATIME for CAP_FOWNER + +netdevice.7 + Karel Kulhavy and AEB + Formatting fix after note from Karel Kulhavy and AEB, plus a + few wording fixes. + +signal.7 + mtk + /proc/sys/kernel/rtsig-* were superseded by RLIMIT_SIGPENDING + in kernel 2.6.8. + +tcp.7 + mtk/aeb + Updated details of interaction of TCP_CORK and TCP_NODELAY. + +==================== Changes in man-pages-2.01 ==================== + +Released: 2004-12-20 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Carsten Hey +Johannes Berg +Joshua Kwan +Marek Habersack +Martin Schulze +Matthew Dempsky +Matthew Gregan +Pedro Zorzenon Neto +Tony Crawford + +Apologies if I missed anyone! + +Global changes +-------------- + +accept.2 +close.2 +send.2 +setsid.2 +socket.2 +closedir.3 +initgroups.3 +mkstemp.3 +opendir.3 +readdir.3 +telldir.3 + Matthew Dempsky, mtk + triggered by http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=283179 + The wording describing how errno is set was fixed up in these pages. + +Typographical or grammatical errors have been corrected in several +other places. + +Changes to individual pages +--------------------------- + +sendfile.2 + mtk + Adjusted descriptions of argument file types to be closer to + 2.6 reality. + Wording and formatting changes. + +ctan.3 +ctanh.3 + Tony Crawford + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=270817 + Formulae on the pages should be T = S / C not T = C / S. + +errno.3 + Martin Schulze, mtk + Removed errno declaration from prototype, added notes + on historical need for this declaration. + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=174175 + +aio_return.3 + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=224953 + Changed erroneous "aio_return(2)" to "aio_return(3)". + +posix_openpt.3 + mtk + New by mtk + +ptsname.3 + mtk + Added description of ptsname_r(). + Added ERRORS. + +ptsname_r.3 + mtk + New link to ptsname.3. + +shm_open.3 + Matthew Gregan + add to synopsis + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=271243 + +strcasecmp.3 + Marek Habersack + .SH "CONFORMING TO" + -BSD 4.4 + +BSD 4.4, SUSv3 + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=234443 + +strfry.3 + Joshua Kwan + Added _GNU_SOURCE to prototype + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=213538 + +strftime.3 + Cartsen Hey + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=276248 + + Changed range for "%S" from 0..61 to 0..60. + + SUSv3 says 0..60. I think the manual page probably says + 0..61, because that's what SUSv2 said. + (Some other implementations' man pages also say 0..61 -- + e.g., Solaris 8 & 9, Tru64 5.1B; FreeBSD 5.1 says 0..60.) + + The glibc manual currently says 0..60. + + Given that SUSv3 says 0..60, I've changed the + manual page to also say this: + + -The second as a decimal number (range 00 to 61). + +The second as a decimal number (range 00 to 60). + +(The range is up to 60 to allow for occasional leap seconds.) + +sysconf.3 + Johannes Berg + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=226974 + -.BR POSIX2_FORT_RUN " - " _SC_2_FORT_DEV + +.BR POSIX2_FORT_DEV " - " _SC_2_FORT_DEV + +system.3 + Pedro Zorzenon + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=242638 + Noted use of _XOPEN_SOURCE to get macros from + for wait(2). + + mtk + Changed name of argument from 'string' to 'command' (like POSIX). + + Noted that glibc does nowadays explicitly check for the existence + of the shell if 'command' is NULL, rather than the older behavior + of assuming the shell exists and always returning 1 if + 'command' is NULL. + + Other wording and formatting clean-ups. + +undocumented.3 + Remove some functions names that *are* documented. + + +==================== Changes in man-pages-2.02 ==================== + +Released: 2005-04-14 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Branden Robinson +Colin Watson +David Lloyd +Gordon Jin +Heikki Orsila +Jamie Lokier +Johan Walles +Kai Makisara +Marko Kohtala +Martin Pool +Martin (Joey) Schulze +Matthias Lang +Michael Haardt +Michael Mühlebach +Mike Frysinger +Sasa Stevanovic +Serguei Leontiev + +Apologies if I missed anyone! + +Global changes +-------------- + +ctime.3 +tzselect.8 +zdump.8 +zic.8 + Martin (Joey) Schulze + Removed SEE ALSO reference to nonexistent newctime(3). + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=236884 + +Typographical or grammatical errors have been corrected in several +other places. + +Changes to individual pages +--------------------------- + +clone.2 + mtk + Noted the PID caching behavior of NPTL's getpid() + wrapper under BUGS. + + Added futex(2), set_thread_area(2), set_tid_address(2), + tkill(2) under SEE ALSO. + +epoll_ctl.2 +epoll_create.2 + Marko Kohtala / mtk + Improved various error descriptions. + +epoll_wait.2 + David Lloyd / Mike Frysinger, Marko Kohtala + Added EINTR to errors. + +fcntl.2 + Jamie Lokier / mtk + Improved discussion of F_SETOWN and F_SETSIG with respect to + multi-threaded programs. + Generally cleaned up the discussion of F_SETOWN. + + Updated CONFORMING TO to note that F_GETOWN and F_SETOWN are + now in POSIX. + +link.2 + mtk + Noted discrepancy between Linux and POSIX.1 when oldpath + is a symbolic link. + See: http://bugs.linuxbase.org/show_bug.cgi?id=367 + and: http://www.opengroup.org/austin/mailarchives/ag/msg08152.html + + Michael Haardt / mtk + Clarified EXDEV error description: it isn't possible to link + across mount points, even if the mount points refer to the same + file system. + +mincore.2 + mtk, after note from Gordon Jin + Updated ERRORS. + +pipe.2 + As per message from Serguei Leontiev + Removed SVr2, AT&T, and BSD from CONFORMING TO, since + a pipe on those systems is actually bidirectional. + (Pipes are implemented as STREAMS on the former, and + sockets on the latter.) + +posix_fadvise.2 + mtk + Noted kernel version where posix_fadvise() appeared and + noted bug in handling of 'len' in kernels < 2.6.6. + +rename.2 + Michael Haardt + Clarified EXDEV error description: it isn't possible to rename + a file across mount points, even if the mount points refer to + the same file system. + +semop.2 + mtk + Noted kernel version numbers for semtimedop(). + +setitimer.2 + Matthias Lang, mtk + Noted MAX_SEC_IN_JIFFIES ceiling. + Added note about treatment of out-of-range tv_usec values. + +sigqueue.2 + Johan Walles, Martin (Joey) Schulze + Added sigqueue.2 to SEE ALSO. + +times.2 + mtk + Added notes on non-standard behavior: Linux allows 'buf' to + be NULL, but POSIX.1 doesn't specify this and it's non-portable. + +uselib.2 + Andries Brouwer + Improved DESCRIPTION; clarified distinction between + EACCES and ENOEXEC. + +bcopy.3 + Heikki Orsila + bcopy() handles overlapping case, but memcpy() does not, + so for consistency memmove() should be also mentioned. + +getmntent_r.3 + Martin (Joey) Schulze + New link to man3/getmntent.3. + +memcpy.3 + Small wording change after suggestion from Sasa Stevanovic. + +strcasestr.3 + mtk + Created as link to strstr.3. + +strftime.3 + mtk + Noted that SUSv2 allowed a range of 00 to 61 for %S specifier. + +strstr.3 + mtk + Added description of strcasestr(). + +random.4 + aeb + Improved description of read from /dev/urandom. + +st.4 + Kai Makisara + Substantial updates. + +man.7 + Martin Schulze + Branden Robinson + Colin Watson + Mention the .URL macro more verbosely. + + +==================== Changes in man-pages-2.03 ==================== + +Released: 2005-06-02 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Joey (Martin) Schulze +Johannes Nicolai +Justin Pryzby +Klaus Ethgen +Pavel Heimlich +Ross Boylan +Vincent Fourmond + +Apologies if I missed anyone! + +Global changes +-------------- + +console.4 +console_ioctl.4 +mouse.4 +tty.4 +vcs.4 + Pavel Heimlich + Change `ttys(4)' to `ttyS(4)'. + +Typographical or grammatical errors have been corrected in several +places. + +Changes to individual pages +--------------------------- + +clone.2 + mtk + Substantially enhanced discussion of CLONE_THREAD. + + Added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED. + + Other minor fixes. + +execve.2 + aeb + Noted effect of ptracing when execing a set-UID program. + +fcntl.2 + Johannes Nicolai / mtk + Noted F_SETOWN bug for socket file descriptor in Linux 2.4 + and earlier. + + Added text on permissions required to send signal to owner. + +flock.2 + mtk + Noted that lock conversions are not atomic. + +getrusage.2 + mtk + ru_nswap has never contained useful information. + Kernel 2.6.6 clarified that with a patch + ("[PATCH] eliminate nswap and cnswap"). See also: + http://www.ussg.iu.edu/hypermail/linux/kernel/0404.1/0720.html + +kill.2 + mtk + Clarified wording of the 'pid == -1' case. + +mount.2 + mtk + Added MNT_EXPIRE, plus a few other tidy-ups. + +sched_setaffinity.2 + mtk + Added text to note that sched_setaffinity() will migrate the + affected process to one of the specified CPUs if necessary. + + Added a NOTE to point out that the affinity mask is actually a + per-thread attribute that can be adjusted independently for + each thread in a thread group. + +shmctl.2 + mtk + Noted aberrant Linux behavior with respect to new attaches to a + segment that has already been marked for deletion. + + Noted changes in permissions required for SHM_LOCK/SHM_UNLOCK. + +wait.2 + mtk + Noted that the __W* flags can't be used with waitid(). + +confstr.3 + mtk + Added _CS_GNU_LIBC_VERSION and _CS_GNU_LIBPTHREAD_VERSION. + +hosts.5 + Ross Boylan / Martin Schulze + various changes as per + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=304242 + +proc.5 + mtk + Minor changes to discussion of /proc/PID/stat signal fields. + Added 'rt_priority' and 'policy' to /proc/PID/stat. + +capabilities.7 + mtk + 1,$s/inherited/inheritable/g + +regex.7 + Vincent Fourmond / Joey (Martin) Schulze + Removed discussion of `[[:<:]]' and `[[:>:]]' since they do + not seem to be in the glibc implementation. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 + +tzselect.8 + Joey (Martin) Schulze / Klaus Ethgen + The default zoneinfo directory is now /usr/share/zoneinfo. + (was: /usr/local/etc/zoneinfo) + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=267471 + + +==================== Changes in man-pages-2.04 ==================== + +Released: 2005-06-21 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Baurjan Ismagulov +Dave Love +Dieter Brueggemann +Geoff Clare +Guido Trotter +kabloom +Kevin Ryde +Justin Pryzby +Mike Furr +Olivier Croquette +Olivier Guilyardi +Peter Cordes +Philipp Spitzer +Tanaka Akira +Thierry Excoffier +Thomas Hood +Vincent Lefevre +Walter Harms + +Apologies if I missed anyone! + +Global changes +-------------- + +Various pages + mtk + For consistency across pages: + + 1,$s/nonzero/non-zero/g + +Typographical or grammatical errors have been corrected in several +places. + + +New pages +--------- + +pthreads.7 + mtk + An overview of the Linux implementations of POSIX threads. + + +Changes to individual pages +--------------------------- + +_exit.2 + mtk + Various minor changes. + +epoll_ctl.2 + Mike Furr + BUGS: In kernels < 2.6.9, EPOLL_CTL_DEL required a non-NULL + 'event', even though this argument is ignored. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306517 + +flock.2 + mtk / Kevin Ryde + Clarified semantics of relationship between flock() locks + and open file entries and file descriptors. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=291121 + +getitimer.2 + Olivier Croquette, Thierry Excoffier + Noted the existence of the short sleep bug (up to 1 jiffy). + +getrlimit.2 + mtk + RLIMIT_RSS only has affect "in 2.4.x", not "in 2.4 and later". + +getrusage.2 + Geoff Clare + Since Linux 2.6, the ru_nvcsw and ru_nivcsw fields are used. + +nice.2 + mtk / Guido Trotter + Rewrote description of return value. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=296183 + +open.2 + Walter Harms + O_DIRECT needs _GNU_SOURCE. + mtk + O_ASYNC works for pipes and FIFOs in Linux 2.6. + Various minor fixes. + +atexit.3 + mtk + Various minor changes. + +exit.3 + mtk + Various minor changes. + +getopt.3 + mtk / Philipp Spitzer + Fix description of return value. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=308359 + +hsearch.3 + mtk + Changed (char *) to (void *) in example. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=313607 + +log1p.3 + Justin Pryzby + Make log(3) SEE ALSO log1p(3), + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=309578 + +makecontext.3 + Tanaka Akira + Fix description of RETURN VALUE for makecontext(), + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=311800 + +on_exit.3 + mtk + Various minor changes. + +rand.3 + kabloom + Small fix to a code example, + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=194842 + +realpath.3 + mtk / Thomas Hood + When specifying resolved_path as NULL, realpath() + will (still) only allocate up to PATH_MAX bytes. + Plus other minor changes. + See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=239424 + +rcmd.3 + Dave Love + The required header file for these functions on Linux is , + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=311680 + +scanf.3 + Olivier Guilyardi + Arg for %p is a pointer to _a pointer to_ void, + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=263109 + +stdin.3 + Vincent Lefevre + freopen() can change the descriptors associated with + stdin/stdout/stderr, as per + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295859 + +strerror.3 + Baurjan Ismagulov + strerror_r(3) requires #define _XOPEN_SOURCE 600, + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=290880 + +sysconf.3 + Peter Cordes / mtk + Fix typo: "_SC_2_DEV" should be "_SC_2_C_DEV". + +proc.5 + mtk + Added pointers under /proc/sys/net to tcp.7 and ip.7. + +ip.7 + mtk + Various wording and formatting fixes. + Reordered /proc/sys/net/ipv4/ip_* file descriptions alphabetically. + +tcp.7 + Dieter Brueggemann / mtk + Fixes to the discussion of SIOCATMARK and tcp_stdurg. + mtk + Various wording and formatting fixes. + Incorporated some new /proc/sys/net/ipv4/tcp_* file descriptions + from the 2.6.12 source file Documentation/networking/ip-sysctl.txt. + + +==================== Changes in man-pages-2.05 ==================== + +Released: 2005-06-27 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +A Costa +Andries Brouwer +Bas Zoetekouw +Dan Jacobson +Delian Krustev +Dora Anna Volgyesi +Martin (Joey) Schulze +Ove Kaaven + +Apologies if I missed anyone! + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. (Special thanks to A Costa.) + + +Changes to individual pages +--------------------------- + +_exit.2 + mtk / aeb + Reversed 2.04 introduction of the term "process termination + function". + +close.2 + mtk + Clarified what type of lock close() affects. + Minor formatting changes. + +dup.2 + mtk + Consistent use of terms "open file description", + "file status flags", and "file descriptor flags". + Removed mention of lock sharing -- it was not accurate. + Minor formatting fixes. + +fcntl.2 + mtk + Consistent use of terms "open file description", + "file status flags", and "file descriptor flags". + Some rewriting of discussion of file descriptor flags + Under F_DUPFD, replaced some text duplicated in dup.2 + with a cross ref to dup.2 + Minor wording and formatting fixes. + +fpclassify.3 + mtk / Martin (Joey) Schulze / Bas Zoetekouw + The return value of isinf() changed in glibc 2.02 + to differentiate positive and negative infinity. + See: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=285765 + +getgid.2 +getuid.2 + Delian Krustev + Remove confusing text describing real and effective IDs. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=285852 + +getitimer.2 + mtk + The short sleep bug (up to 1 jiffy) that was newly noted in + man-pages-2.04 has just been fixed in 2.6.12. + +getpriority.2 + mtk + Changed range documented in main text from -20..20 to -20..19. + Noted that the range is -20..20 on some systems. + +open.2 + mtk / aeb + Clarification of term "open file description" along with + explanation of what information it maintains. + Other wording improvements. + Various minor wording changes. + +atexit.3 + mtk / aeb + Reversed 2.04 introduction of the term "process termination + function". + mtk + Noted use of atexit() for establishing function to be invoked on + shared library unload. + Noted that atexit()-registered functions are not invoked on + abnormal termination. + Formatting fixes. + +exit.3 + mtk / aeb + Reversed 2.04 introduction of the term "process termination + function". + mtk + Minor rewording and formatting changes. + +getloadavg.3 + mtk + Added #define _BSD_SOURCE to prototype. + +log2.3 + Martin (Joey) Schulze + Add ERANGE error. + +readdir.3 + mtk + Added definition of Linux dirent structure. + Some formatting cleanups. + +strtod.3 + Dora Anna Volgyesi / mtk + strtold() and strtof() need _ISOC99_SOURCE or _XOPEN_SOURCE=600 + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=246668 + +tdestroy.3 + mtk + New link to tsearch.3. + +tsearch.3 + mtk + Added tdestroy to .TH line. + +mem.4 + mtk + Change "chown root:mem /dev/mem" to "chown root:kmem /dev/mem". + +null.4 + mtk + Change "chown root:mem /dev/null /dev/zero" to + "chown root:root /dev/null /dev/zero". + +vcs.4 + Dan Jacobson / Martin (Joey) Schulze + Replaced "selection(1)" by "gpm(8)" under SEE ALSO + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=253515 + +signal.7 + Ove Kaaven + SA_SIGACTION should be SA_SIGINFO + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=305369 + +urn.7 + mtk + New link to uri.7 + + +==================== Changes in man-pages-2.06 ==================== + +Released: 2005-07-15 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andries Brouwer +Bhavesh P Davda +Clau Weber +Dov Murik +David Lloyd +Frederik Deweerdt +Justin Pryzby +Lars Wirzenius +Martin Pool +Mike Frysinger +Petter Reinholdtsen +Steven Murdoch +Walter Harms + +Apologies if I missed anyone! + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + +Many uses of hyphens and dashes were corrected. + + +New pages +--------- + +canonicalize_file_name.3 + Walter Harms / mtk + +Removed Pages +------------- + +sstk.2 + mtk + AFAIK, this system call has never actually done anything (other + than be a stub) on any Unix. + +Changes to individual pages +--------------------------- + +accept.2 + mtk + Various wording and formatting fixes. + +bind.2 + mtk + Minor formatting changes + +clone.2 + mtk + Various minor wording improvements; some formatting fixes + +connect.2 + mtk + Various wording and formatting fixes. + +epoll_create.2 + Bhavesh P Davda + s/positive/non-negative/ [for file descriptor] + +getrlimit.2 + mtk + Documented RLIMIT_MSGQUEUE limit. + RLIMIT_RSS ceased to have any effect in 2.4 in kernel 2.4.30. + (It already didn't have any effect in 2.2.x and 2.6.x.) + s/MADVISE_WILLNEED/MADV_WILLNEED/ + +listen.2 + mtk + Removed historic comment on BSD backlog ceiling. + Minor wording and formatting changes. + +semop.2 + mtk + Added BUG: in some circumstances, a process that is + waiting for a semaphore to become zero is not woken + up when the value does actually reach zero. + http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2 + http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2 + +socket.2 + mtk + Various minor wording improvements + +umask.2 + mtk + Added mkdir(2) to discussion, made term "file mode creation + mask" clearer. + Various, mostly small, wording changes + +errno.3 + Martin Pool + Change description for ESTALE + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=237344 + +fgetgrent.3 +getgrent.3 +getgrent_r.3 + David Lloyd + Added SEE ALSO putgrent(3) + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=211336 + +getgrent.3 +getgrnam.3 +getpwent.3 +getpwnam.3 + Lars Wirzenius / mtk + Replace mention of /etc/{passwd,group} by references to + "passwd/group database", and LDAP and NIS. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=316117 + mtk + Miscellaneous wording improvements + Consistent DESCRIPTION and ERRORS wording across these pages. + +getnameinfo.3 + mtk + Relocate misplaced text describing gai_strerror(). + +getnetent.3 + Petter Reinholdtsen + s/endservent/endnetent/ + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=316517 + +getspnam.3 + Lars Wirzenius / mtk + Replace mention of /etc/shadow by references to + "shadow password database", and LDAP and NIS. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=316117 + mtk, Claus Weber + Miscellaneous wording improvements + Consistent DESCRIPTION wording vis-a-vis getpwnam.3 etc. + +hsearch.3 + Frederik Deweerdt + Fix hsearch_r() prototype + +scanf.3 + Justin Pryzby / mtk + Fix description of RETURN VALUE + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=317037 + mtk + various parts substantially rewritten; added description of + %n$ form; various text incorporated from the GNU C library + documentation ((C) The Free Software Foundation). + +shm_open.3 + mtk + Modified details of how user and group ownership of a new + object are set. + Various minor wording and formatting cleanups. + +elf.5 + Mike Frysinger + tweaked the short description to include definition of 'ELF' + add ELFOSABI_NONE to the ELFOSABI_ list + tweak/add more machines to EM_ list for ehdr->e_machine + fix indenting to be consistent + tweak the display of the ELF_ST_* macros + document the Elf_Dyn structure + +proc.5 + mtk + Updated discussion of /proc/stat. + Added text on the /proc/sys/fs/mqueue/* files. + +ip.7 + Steven Murdoch + Change protocol in UDP prototype. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=182635 + +tcp.7 + Dov Murik + The first sentence under NOTES about SO_KEEPALIVE and SIGPIPE + makes no grammatical sense (and possibly also no technical sense). + It has been removed. + + +==================== Changes in man-pages-2.07 ==================== + +Released: 2005-07-19 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Mike Frysinger + +Apologies if I missed anyone! + +Global changes +-------------- + +Various pages + mtk + The terms "set-user-ID" and "set-group-ID" are now used + consistently (no abbreviations) across all manual pages. + +Various pages + mtk + Consistent use of "saved set-user-ID" and "saved set-group-ID" + (no more "saved user ID", "saved effective UID", + saved group ID", etc.) + +Various pages + mtk + Global fixes in textual descriptions: + + uid --> UID + gid --> GID + pid --> PID + id --> ID + +Various pages + mtk + Consistent use of st_atime, st_ctime, st_mtime, with + explanatory text, instead of atime/ctime/mtime. + +Various pages + mtk + Classical BSD versions are now always named x.yBSD (formerly + there was a mix of x.yBSD and BSD x.y). + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +setresuid.2 + mtk + Some rewording. + +stat.2 + Mike Frysinger + Improve description of st_dev and st_rdev. + mtk + Various wording and formatting improvements. + +truncate.2 + mtk + Some formatting fixes + + +==================== Changes in man-pages-2.08 ==================== + +Released: 2005-09-21 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Adrian Bunk +Alain PORTAL +Andrew Pimlott +Andries Brouwer +Baurzhan Ismagulov +Bernhard R. Link +Bodo Stroesser +David N. Welton +Dov Murik +Heikki Orsila +Hasso Tepper +Hrvoje Niksic +Justin Pryzby +Ludovic Courtes +Mike Frysinger +Nicolas François +Norbert Buchmuller +Paul Brook +Ramiro Aceves +Tommy Pettersson +Walter Harms + +Apologies if I missed anyone! + +Global changes +-------------- + +Various pages + mtk + RFC references are now always written as "RFC\ nnn" + (not "RFC nnn" or "RFCnnn"). + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +du.1 + Mike Frysinger + To get an effect like "-h", BLOCKSIZE must start with "human", + not "HUMAN". + +time.1 + Mike Frysinger + s/standard output/standard error/ + +clone.2 + Paul Brook / mtk + Fix small error in description of CLONE_PARENT_SETTID + +connect.2 + Heikki Orsila + Add EINTR error + See http://lkml.org/lkml/2005/7/12/254 + +getpriority.2 + mtk + Expanded discussion of relationship between user and kernel + representations of the nice value. + + Added discussion of RLIMIT_NICE and a cross reference to + getrlimit.2 under the description of the EACCES error. + + Noted 2.6.12 change in credentials checking for setpriority(). + +getrlimit.2 + mtk + Added description of RLIMIT_RTPRIO + + Added description of RLIMIT_NICE + +mmap.2 + mtk + Noted bug in MAP_POPULATE for kernels before 2.6.7. + +mremap.2 + mtk + Added _GNU_SOURCE to prototype. + Rewrote description of MREMAP_MAYMOVE. + Rewrote description of EAGAIN error. + Added discussion of resizing of memory locks. + Added entries to SEE ALSO. + Some formatting fixes. + +msgctl.2 + mtk + Added IPC_INFO, MSG_INFO, MSG_STAT descriptions. + +nanosleep.2 + Baurzhan Ismagulov + Add to prototype: define _POSIX_C_SOURCE 199309 + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=314435 + +nice.2 + mtk + Added sentence noting that range of the nice value is described + in getpriority.2. + Added cross-reference to setrlimit(2) for discussion on + RLIMIT_NICE. + +outb.2 + David N. Welton / Justin Pryzby / mtk + Clarified the order of value and port arguments; + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=263756 + +pause.2 + mtk + Added SEE ALSO for sigsuspend.2 + Some formatting fixes. + +poll.2 + Tommy Pettersson + nfds should be prototyped as nfds_t + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=322934 + + mtk + Some wording and formatting improvements. + +prctl.2 + mtk + Since kernel 2.6.13 PR_SET_DUMPABLE can also have the value 2. + +rand.3 + Hrvoje Niksic / mtk + Remove misleading text describing FreeBSD's sranddev() function. + As per debian bug 328629 + +readv.2 + mtk / Walter harms + Added LINUX NOTES on trickery performed by glibc when + vector size exceeds IOV_MAX. + + Formatting clean-ups. + +remap_file_pages.2 + mtk + Added text to note that start and size are both rounded downward. + +sched_setparam.2 + mtk + Modified discussion of privileges; added pointer to + sched_setscheduler.2 for a discussion of privileges and + resource limits. + +sched_setscheduler.2 + mtk + Modified discussion of privileges; added discussion of RLIMIT_RTPRIO. + +semctl.2 + mtk + Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. + +shmctl.2 + mtk + Added IPC_INFO, SHM_INFO, SHM_STAT descriptions. + +sigaction.2 + mtk + Split sigpending(), sigprocmask(), and sigsuspend() out + into separate new pages. + + Other minor changes + + mtk + NOTES: described SA_NODEFER / sa_mask bug which was present in + all kernels up to and including 2.6.13. + See http://marc.theaimsgroup.com/?l=linux-kernel&m=112360948603171&w=2 + and http://marc.theaimsgroup.com/?l=linux-kernel&m=112362164911432&w=2 + List: linux-kernel + Subject: Signal handling possibly wrong + From: Bodo Stroesser + Date: 2005-08-09 17:44:06 + +signal.2 + mtk + Updated SEE ALSO to reflect splitting of sigaction.2 into + sigaction.2, sigsuspend.2, sigpending.2, sigprocmask.2 + +sigpending.2 + mtk + New page created by splitting out from sigaction.2 + Changed CONFORMING TO. + +sigprocmask.2 + mtk + New page created by splitting out from sigaction.2 + Added text on effect of NULL for 'set' argument. + Added text noting effect of ignoring SIGBUS, SIGFPE, SIGILL, + and SIGSEGV. + Noted that sigprocmask() can't be used in multithreaded process. + Fixed EINVAL error diagnostic. + Changed CONFORMING TO. + +sigsuspend.2 + mtk + New page created by splitting out from sigaction.2 + Added NOTES on usage. + Added new text to DESCRIPTION. + Changed CONFORMING TO. + +stat.2 + Mike Frysinger + Improve st_blocks description. + +carg.3 + Ramiro Aceves / aeb + Change: + One has carg(z) = atan(creal(z) / cimag(z)) + to: + One has tan(carg(z)) = cimag(z) / creal(z) + + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=326720 + +cmsg.3 + mtk + s/SOL_TCP/IPPROTO_TCP/ (POSIX standard name) + +dlopen.3 + Alain Portal + s/-nostartupfiles/-nostartfiles/ + +getaddrinfo.3 + mtk + Nowadays (since 2.3.4) glibc only sets the first ai_canonname + field if AI_CANONNAME was specified (the current behavior + is all that SUSv3 requires). + + 1,$s/PF_/AF_/g + + Added descriptions of AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED, + and AI_NUMERICSERV. + + Some wording and formatting fixes. + +getpwnam.3 + Bernhard R. Link / mtk + Add NOTES text describing relationship of pw_dir and HOME and + pointing out that applications should preferentially inspect HOME. + +inet.3 + Mike Frysinger + Mention "little endian" and "big endian". + Added note about octal and hex interpretation of + numbers-and-dots notation. + +rpc.3 + mtk / Ludovic Courtes + Commented out references to rpc_secure(3) -- we don't currently + have such a page in the man-pages set. + In response to http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=325115 + +setenv.3 + mtk + glibc 2.3.4 fixed the "name contains '='" bug. + +strnlen.3 + Mike Frysinger + Added "#define _GNU_SOURCE" to prototype. + +initrd.4 + Norbert Buchmuller / mtk + Added text noting that the use or real-root-dev for changing + the root device is obsolete, in favor of pivot root. + (However, the page still needs to be rewritten to actually + describe the pivot_root method...) + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=323621 + +proc.5 + mtk + Improve text describing /proc/sys/fs/mqueue/* files. + + Describe /proc/sys/fs/suid_dumpable (new in 2.6.13). + + Added placeholder mention of /proc/zoneinfo (new in 2.6.13). + More needs to be said about this file. + + Repaired earlier cut and paste mistake which resulted + in part of the text of this page being duplicated. + +utmp.5 + Mike Frysinger + Added text on biarch details for ut_session and ut_tv. + +capabilities.7 + mtk + Added CAP_AUDIT_CONTROL and CAP_AUDIT_WRITE. + +ip.7 + mtk / Andrew Pimlott + Add a couple of words to make it clear that port is a 16-bit number. + Reformat long source lines (no text changed). + + s/SOL_IP/IPPROTO_IP/ (POSIX standard name) + + Hasso Tepper + Fix discussion of IPC_RECVTTL / IP_TTL. + +signal.7 + mtk + Updated SEE ALSO to reflect splitting of sigaction.2 into + sigaction.2, sigsuspend.2, sigpending.2, sigprocmask.2. + +socket.7 + mtk + Clarified details of use of SO_PEERCRED. + +tcp.7 + mtk + s/SOL_TCP/IPPROTO_TCP/ (POSIX standard name) + s/SOL_IP/IPPROTO_IP/ (POSIX standard name) + +udp.7 + mtk + Added description of UDP_CORK socket option. + + s/SOL_UDP/IPPROTO_UDP/ (POSIX standard name) + s/SOL_IP/IPPROTO_IP/ (POSIX standard name) + + +==================== Changes in man-pages-2.09 ==================== + +Released: 2005-10-13 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Justin Pryzby +Peter Chubb +Samuel Thibault +Tomas Pospisek +Trond Myklebust + +Apologies if I missed anyone! + +Global changes +-------------- + +ptsname.3 +getpt.3 +unlockpt.3 +openpty.3 +posix_openpt.3 +grantpt.3 +pts.4 +tty_ioctl.4 + mtk + Added SEE ALSO for new pty.7 page. + +Typographical or grammatical errors have been corrected in several +places. + + +New pages +--------- + +pty.7 + mtk + Overview of Unix 98 and BSD pseudo-terminals. + + +Changes to individual pages +--------------------------- + +ldd.1 + mtk + Remove "-V" option (fix from Fedora man-pages-2.07-7). + +fcntl.2 + Peter Chubb / Trond Myklebust / mtk + Since kernel 2.6.10, a read lease can only be placed on a + file descriptor that is opened read-only. + See the following LKML thread of Aug 2005 + ("fcntl(F GETLEASE) semantics??"): + http://marc.theaimsgroup.com/?l=linux-kernel&m=112371777712197&w=2 + http://marc.theaimsgroup.com/?l=linux-kernel&m=112374818213000&w=2 + http://marc.theaimsgroup.com/?l=linux-kernel&m=112376335305284&w=2 + http://marc.theaimsgroup.com/?l=linux-kernel&m=112377294030092&w=2 + +mprotect.2 + mtk + Add new text to ENOMEM error. + +mremap.2 + mtk + Added description of MREMAP_FIXED and 'new_address' argument + under NOTES. + Revised text of EINVAL error. + +read.2 + Samuel Thibault / mtk + read() can fail with EINVAL when using O_DIRECT + mtk + Added open(2) to SEE ALSO. + +shmget.2 + mtk + s/int/size_t/ for type of 'size' argument (fix from + Fedora man-pages-2.07-7). + +write.2 + Samuel Thibault / mtk + write() can fail with EINVAL when using O_DIRECT + +atanh.3 + mtk + Fix: s/acosh/atanh/ (fix from Fedora man-pages-2.07-7). + +fopen.3 + mtk + Improved "a+" description (fix from Fedora man-pages-2.07-7). + +getrpcent.3 + mtk + s/getrpcent/setrpcent/ (fix from Fedora man-pages-2.07-7). + +stdio.3 + mtk / Justin Pryzby + Removed references to fropen() and fwopen(), which are + BSDisms that don't appear in glibc. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=331174 + +strftime.3 + mtk + Typo fix: %Ry ==> %Ey [SUSv3 mentions...] (fix from + Fedora man-pages-2.07-7). + +nsswitch.conf.5 + mtk + s/network/networks/ (fix from Fedora man-pages-2.07-7). + +proc.5 + mtk + Added description of /proc/sys/vm/legacy_va_layout. + +socket.7 + mtk + Update description of SO_RCVLOWAT and SO_SNDLOWAT. + (fix derived from Fedora man-pages-2.07-7). + + +==================== Changes in man-pages-2.10 ==================== + +Released: 2005-10-19 + +Global changes +-------------- + +The changes in this release consist *solely* of formatting fixes, with +the aim bringing greater consistency to the manual pages according to +the following rules: + +-- Function name references should *always* be followed by + parentheses, "()" (possibly containing a manual page section + number). + +-- The parentheses following a function name should *not* be + formatted. Thus, for example, instead of: + + .B name() + + one should write: + + .BR name () + +Much of the change was automated using two scripts: +add_parens_for_own_funcs.sh and unformat_parens.sh. +For the (possible) benefit of downstream manual page maintainers and +translators, I have placed these scripts in a new subdirectory 'scripts'. + +NOTE THE FOLLOWING POINTS WELL: + +-- These scripts provide a computer-assisted solution to the above + two goals. However, they are not perfect, and their output should + be scanned by a human. (To see what changes the two scripts + *would* make, without making them, use the "-n" command line option.) + +-- The scripts do not fix all instances that violate the above rules: + some manual fixes are required. Two further scripts are provided + to help find remaining instances of function names without + following "()": find_dots_no_parens.sh and find_slashes_no_parens.sh. + +The following changes were made: + +-- add_parens_for_own_funcs.sh was applied to the pages in Sections + 2 and 3. + +-- unformat_parens.sh was applied to pages in Sections 2, 3, 4, and 7 + (the only sections where such changes were required). + +-- further changes (not so very many) were performed by hand. + (found places to fix with the assistance of find_dots_no_parens.sh + and find_slashes_no_parens.sh). + + +==================== Changes in man-pages-2.11 ==================== + +Released: 2005-10-24 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain PORTAL + +Apologies if I missed anyone! + +Global changes +-------------- + +Various pages + mtk + Most instances of the constant "NULL" are not formatted (bolded) in + man pages, but a few are. For consistency, formatting on "NULL" has + been removed where it occurred. + + Many minor formatting fixes were made. + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +getrlimit.2 + mtk + Added EINVAL error for rlim_cur > rlim_max when calling setrlimit(). + +path_resolution.2 + mtk + Repaired discussion of capabilities and file system UID, which + mistakenly had involved exec() in the discussion. + +prctl.2 + mtk + Removed text saying there is no library interface. There + is nowadays. + +mkfifo.3 + mtk + Minor change to RETURN VALUE text. + +sk98lin.4 + Alain Portal + Formatting fixes. + +capabilities.7 + mtk + Minor changes. + + +==================== Changes in man-pages-2.12 ==================== + +Released: 2005-10-31 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Akihiro MOTOKI +Andries Brouwer +Brian M. Carlson +herbert +Martin Landers +Michael Benedict + +Apologies if I missed anyone! + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +mlock.2 + mtk + Reworded text around PAGESIZE, noting also that + sysconf(_SC_PAGESIZE) can be used. + +path_resolution.2 + mtk / aeb + Removed words "as well" (added in 2.11) from the phrase + "and it gets these last five capabilities if its fsuid is 0 as well" + since there are (unusual) situations in which fsuid can be 0 while + the effective UID is not. + + Reworked (cut down) discussion of capabilities, moving part of + it into capabilities.7 + +setresuid.2 + mtk + Add text to note that setresuid() always modifies the file + system UID, and setresgid() likewise always modifies the file + system GID. + +shmget.2 + mtk + Added (brief) description of SHM_HUGETLB. + +sigaltstack.2 + mtk / Martin Landers + Noted that ss_sp is automatically aligned by the kernel. + +byteorder.3 + Brian M. Carlson / herbert + Change to in prototype; add text + explaining that some systems need the former header. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=265244 + +capabilities.7 + mtk + Reworked part of the discussion of exec() and capabilities. + Added sub-section "Effect of User ID Changes on Capabilities". + Reworked discussion of CAP_SYS_ADMIN and file-max. + + +==================== Changes in man-pages-2.13 ==================== + +Released: 2005-11-03 + +This release consists entirely of formatting and typographical fixes. + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + +Various pages + mtk + Function and page cross references that were italicized were + made bold (which is how the majority of function and page + cross references were already done). + +Various pages + mtk + Instances of things like "NULL-terminated string" were changed to + "null-terminated string". + +Various pages + mtk + Pathnames, structures, arguments, and that were + bold were changed to italics. + +Various pages + mtk + Instances of the constant "NULL" that were bold-faced were made + unformatted (which is how most instances of "NULL" were already + formatted.) + + +==================== Changes in man-pages-2.14 ==================== + +Released: 2005-11-17 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Angelo +Avery Pennarun +Justin Pryzby +Martin (Joey) Schulze +Stefan Brüns +Volker Reichelt + +Apologies if I missed anyone! + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + +New pages +--------- + +rexec.3 + mtk / Justin Pryzby + This page is taken as is from the FreeBSD 5.4 distribution. + (Not checked against Linux reality, but likely things are + the same.) + See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=336875 + +Changes to individual pages +--------------------------- + +arch_prctl.2 + mtk + Updated discussion about lack of prototype in glibc. + +execve.2 + mtk + Improved description of E2BIG error: it relates to the sum + of the bytes in both environment and argument list. + +fcntl.2 + mtk + Clarified parts of the discussion of file leases, + noting effect of open(O_NONBLOCK), interruption + by signal handler, or termination by signal in + lease breaker. In response to + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=339037 + +stat.2 + mtk / Stefan Brüns + Added LINUX NOTES describing nanosecond timestamps. + +frexp.3 + Volker Reichelt / mtk + Fixed to point out that frexp() returns a number whose + *absolute* value is >= 0.5 and < 1. Amended the example + program to demonstrate this. + +open.2 + mtk / Avery Pennarun + Add EWOULDBLOCK error for file leases. + In response to + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=339037 + +putenv.3 + mtk + Although the glibc implementation returns -1 on error (and some + other man pages (e.g., the BSDs) also document that value for + error returns), SUSv3 merely says "non-zero" (and this is + what manual pages on many implementations also say). + +posix_memalign.3 + mtk + Formerly, the page said that all systems declare memalign() in + . In fact, many declare it in . + +strtok.3 + mtk + Almost a complete rewrite after Angelo pointed out + that the existing page was deficient. + +sd.4 + Martin Schulze + Remove SEE ALSO for nonexistent scsi.4. + +proc.5 + mtk + Updated discussion of /proc/sys/kernel/pid_max. + +signal.7 + mtk + Added pthreads.7 to SEE ALSO. + +ld.so.8 + mtk + Fix typo: s/LD_DEBUG_OUTPUT/LD_PROFILE_OUTPUT/ + + +==================== Changes in man-pages-2.15 ==================== + +Released: 2005-11-30 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +James Vega +Malcolm Scott +Senthil Kumar + +Apologies if I missed anyone! + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + +New pages +--------- + +sigvec.3 -- for details, see below. + +sigset.3 -- for details, see below. + +Changes to individual pages +--------------------------- + +kill.2 + mtk + Added text describing the 2.6.[0-7] EPERM bug that occurred + when sending signals to a process group. + +sigaction.2 + mtk + Noted that si_signo is unused on Linux. + +sigpending.2 + mtk + Added BUGS noting wrapper function problem that existed + in glibc versions <= 2.2.1. + +sigpause.2 + mtk + Moved to section 3; see also sigpause.3 below. + +sigsetops.3 + mtk + Added a GLIBC NOTES section describing sigisemptyset(), + sigandset(), and sigorset(). + +sigvec.2 +sigblock.2 + mtk + These pages have been deleted, and replaced by a new sigvec.3 + man page that more fully describes the BSD signal API. + +siggetmask.2 +sigmask.2 +sigsetmask.2 + mtk + These links to the now-deleted sigblock.2 have been also been + deleted. They are replaced by corresponding links in Section 3: + sigmask.3, sigsetmask.3, siggetmask.3. + +sigvec.3 + mtk + This new page is provides a fuller description of the + BSD signal API than was provided in the now-deleted sigvec.2 + and sigblock.2. + +sigblock.3 +siggetmask.3 +sigmask.3 +sigsetmask.3 + mtk + Created as links to sigvec.3. + +sigpause.3 + mtk + Moved here from Section 2. + + Some minor wording fixes; clarified System V origins of + X/Open flavor of this function. + +sigset.3 + mtk + New page describing the System V signal API: sigset(), sighold(), + sigrelse(), sigignore(). + +strftime.3 + James Vega + Add further text clarifying that %+ specifier is not supported in + glibc2. + mtk + Added GLIBC NOTES section describing optional 'flag' and 'width' + components of conversion specifiers. + Some wording changes to bring terminology closer to SUSv3. + Added an example program. + +vm86old.2 + mtk / aeb + Add as new link to vm86.2. + +intro.7 + mtk + Added a few words to reflect the fact that several of the section + 7 pages provide overviews of various topics. + +signal.7 + mtk + Added some SEE ALSO entries. + +socket.7 + Senthil Kumar / mtk + Added text noting that select()/poll() do not respect SO_RCVLOWAT. + +udp.7 + Malcolm Scott + s/tcp_socket/udp_socket/ in example + Fixes http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=340927 + + +==================== Changes in man-pages-2.16 ==================== + +Released: 2005-12-02 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alan Stern +Andries Brouwer +Urs Thuermann + +Apologies if I missed anyone! + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +HOWTOHELP + Urs Thuermann + Added instructions for finding maintainer in Debian package. + +poll.2 + mtk + Added NOTES about INFTIM constant provided on some other + implementations. + +shmop.2 + Alan Stern + The -1 error return of shmat() should be cast "(void *)". + +strftime.3 + aeb + Remove junk text (actually intended as source code comment + in page). + +ip.7 + Urs Thuermann + Fix a typo: s/SOCK_RAW/SOCK_PACKET/ + +packet.7 + Urs Thuermann + Clarification: s%SOCK_PACKET%PF_INET/SOCK_PACKET% + + +==================== Changes in man-pages-2.17 ==================== + +Released: 2005-12-13 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Justin Pryzby +Michael Haardt +Urs Thuermann +Walter Harms + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +New pages +--------- + +fmemopen.3 + Walter Harms / mtk + New documentation for the glibc-specific fmemopen() and + open_memstream(). Based on glibc info page. + +pipe.7 + mtk (with prompting and suggestions for improvements by + Michael Haardt) + New page providing overview of pipes and FIFOs. + + +Changes to individual pages +--------------------------- + +HOWTOHELP + mtk + Added notes on how to write example programs for manual pages. + +fork.2 + mtk + Added pointers to examples of fork() in wait.2 and pipe.2. + +pipe.2 + mtk + Added an example program. + Added SEE ALSO for new pipe.7 page. + +wait.2 + mtk + Added example program demonstrating use of fork() and waitpid(). + +carg.3 + Justin Pryzby + Delete line that should have been deleted when applying + 2.08 fix for this page. + +getaddrinfo.3 + mtk + Rearranged EAI_* list alphabetically. + +inet.3 + mtk + Added GLIBC NOTES describing feature test macros required + to expose declaration of inet_aton(). + +open_memstream.3 + mtk + New link to new fmemopen.3. + +fifo.4 + mtk + Added SEE ALSO for new pipe.7 page. + +environ.5 + mtk + Removed BROWSER, since it seems not in fact to be common. + +socket.7 + Urs Thuermann + Added documentation of SO_TIMESTAMP. + +tcp.7 + mtk + Noted 200 millisecond ceiling imposed on TCP_CORK. + +udp.7 + mtk + Rearranged options into something approximating alphabetical order. + + +==================== Changes in man-pages-2.18 ==================== + +Released: 2005-12-15 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Justin Pryzby +Karsten Sperling +Martin (Joey) Schulze +Mike Frysinger +Stefan Puiu + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +bind.2 + mtk + Added mention of AF_INET6 address family. + Added discussion of sockaddr structure and an example in the + Unix domain. + +recv.2 + mtk + Put 'flags' list in alphabetical order. + +send.2 + mtk + Added cross-reference from discussion of MSG_MORE to UDP_CORK + in udp(7). + + Put 'flags' list in alphabetical order. + +err.3 + mtk + Added CONFORMING TO section noting that these are + non-standard BSDisms. + +errno.3 + Justin Pryzby + Added SEE ALSO for err.3. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306867 + +gethostbyname.3 + Martin (Joey) Schulze / mtk + Added references to nsswitch.conf(5); remove cross references + to resolv+(8). + See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=308397 + +perror.3 + Justin Pryzby + Added SEE ALSO for err.3 . + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306867 + +resolver.3 + mtk / Martin (Joey) Schulze + Remove cross references to resolv+(8); add cross references to + resolv.conf(5). + See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=214892 + + Added SEE ALSO entry for resolver(5); + see http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=251122 + +strerror.3 + mtk / Stefan Puiu + Rewrote and extended the discussion of the two flavors of + strerror_r(), and added some additional information on + strerror(). + Justin Pryzby + Added SEE ALSO for err.3, as per + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306867 + + +elf.5 + Mike Frysinger + Fix three typos in identifier names. + +operator.7 + Karsten Sperling + The + operator should be in the list of unary operators. + +raw.7 + mtk + Small wording changes around discussion of SO_BSDCOMPAT. + Fixed a couple of wording errors elsewhere. + Reformatted some long lines. + +socket.7 + mtk, after a note by Stefan Puiu + Updated discussion of SO_BSDCOMPAT. + + Reformatted some long lines. + + Noted the Linux-specific feature whereby setsockopt() doubles + the value given for SO_SNDBUF and SO_RCVBUF. + + Noted kernel-imposed minimum values for SO_SNDBUF and SO_RCVBUF. + +udp.7 + mtk, after a note by Stefan Puiu + Updated discussion of SO_BSDCOMPAT. + +unix.7 + mtk + Added new (UN)SUPPORTED FEATURES section in which it is noted + that Unix domain sockets do not support MSG_OOB or MSG_MORE. + + Noted details of SO_SNBUF and SO_RCVBUF support for + Unix domain sockets. + + +==================== Changes in man-pages-2.19 ==================== + +Released: 2005-12-23 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Walter Harms +Stefan Puiu + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +HOWTOHELP + mtk + Minor changes. + +bind.2 + Stefan Puiu / mtk + Remove text under EINVAL error: "This may change in the future: + see linux/unix/sock.c for details." This behavior has been + unchanged for a long time, and seems unlikely to change. + + Add EADDRINUSE to errors. + +send.2 + aeb + Add cmsg(3) to SEE ALSO. + +fopen.3 + Walter Harms / mtk + Added description of 'x' mode character (exclusive open). + +pipe.7 + mtk / aeb + Some wording changes to description of pipes. + + +==================== Changes in man-pages-2.20 ==================== + +Released: 2006-01-03 + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +sigaltstack.2 + mtk + Added some text to explain the usual scenario in which + sigaltstack() is employed. + +getloadavg.3 + mtk + Noted that this function is available since glibc 2.2. + +strcpy.3 + mtk + s/nulls/null bytes/ + +capabilities.7 + mtk + Noted that capability bounding set appeared with kernel 2.2.11. + +arp.7 +icmp.7 +ip.7 +ipv6.7 +netdevice.7 +packet.7 +raw.7 +rtnetlink.7 +socket.7 +tcp.7 +unix.7 +udp.7 + mtk + The only changes to these pages have been for formatting: + -- Structure definitions were changed to K&R style + -- Some long source lines were broken to fit into ~70 + character lines. + No changes were made to the content of these pages (yet...). + + +==================== Changes in man-pages-2.21 ==================== + +Released: 2006-01-16 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Falk Hueffner +Mike Frysinger +Senthil Kumar +Stefan Puiu + +Apologies if I missed anyone! + + +Global changes +-------------- + +dd.1 cp.1 +truncate.2 gethostname.2 lseek.2 listxattr.2 readlink.2 +sysfs.2 stat.2 ustat.2 uname.2 getdomainname.2 +argz_add.3 asprintf.3 confstr.3 bstring.3 bzero.3 dlopen.3 fwide.3 +gethostbyname.3 getline.3 getlogin.3 getnameinfo.3 getpass.3 hsearch.3 +perror.3 printf.3 readdir.3 scanf.3 stpcpy.3 strdup.3 strfmon.3 +strftime.3 string.3 strptime.3 sysconf.3 termios.3 ttyname.3 +dsp56k.4 tty_ioctl.4 +elf.5 proc.5 termcap.5 +charsets.7 unix.7 + mtk + Various pages use inconsistent terms for 'null byte' (which + is the C99/SUSv3 term for the '\0' character). + + To rectify this the following changes were made in the above + pages: + + Replace 'zero byte' with 'null byte'. + Replace 'null character' with 'null byte'. + Replace 'nulls' with 'null bytes'. + Replace 'NUL-terminated' by 'null-terminated'. + Replace 'NUL' by 'null byte'. + Replace 'terminating NUL' by 'terminating null byte'. + Replace 'final NUL' by 'terminating null byte'. + Replace 'NUL character' by 'null byte'. + +Various pages + mtk + Replace "SysV"/"SYSV" by "System V". + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +capget.2 + mtk + Noted bug that could wrongly cause EPERM in unprivileged + capset() with 'pid' field == getpid(). + +epoll_ctl.2 + mtk + Noted that EPOLLONESHOT was added in 2.6.2. + +gethostname.2 + mtk + Added GLIBC NOTES describing operation of glibc's + gethostname() wrapper function. + +mmap.2 + mtk / Mike Frysinger + Clarify relationship between mmap2(2) and mmap64(3). + mtk + A few other small rewordings. + +mmap64.3 + Mike Frysinger + New link to mmap.2. + +open.2 + mtk + Added BUG noting that O_ASYNC can't be enabled via + open(): fcntl() must be used for this purpose. + +recv.2 + Stefan Puiu + Relocate misplaced discussion of MSG_DONTWAIT. + +dlopen.3 + mtk + Rewrote discussion of dlopen() 'flag' argument; + added descriptions of RTLD_NOLOAD, RTLD_DELETE, + and RTLD_DEEPBIND. + + Noted use of atexit() to register a function that is + automatically called when a library is unloaded. + +fmemopen.3 + mtk + Rewrote substantial parts of the page, and relicensed under GPL. + +fseeko.3 + Mike Frysinger + Add RETURN VALUE section. + +getopt.3 + mtk + Noted historical use of to declare getopt(). + +qsort.3 + mtk / Falk Hueffner + Clarify how strcmp() should be used as the 'compar' + function by providing an example. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=348072 + +proc.5 + mtk + Noted that /proc/mounts is pollable since kernel 2.6.15. + + Documented /proc/PID/task. + + Noted that the contents of /proc/PID/{cwd,exe,fd,root,task} + are not available if the main thread has terminated. + + Senthil Kumar + Add pointer to random(4) for description of files under + /proc/sys/kernel/random. + +udp.7 + Stefan Puiu / mtk + Small rewording of discussion of SO_BSDCOMPAT + (add cross-ref to socket(7)). + + +==================== Changes in man-pages-2.22 ==================== + +Released: 2006-02-02 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andre Noll +Andries Brouwer +Colin Tuckley +Stefan Puiu +Thomas Hood +Thorsten Kukuk +Walter Harms + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + +Changes to individual pages +--------------------------- + +mmap.2 + aeb / mtk + Noted that portable applications should specify fd as -1 + when using MAP_ANONYMOUS. + Some rewriting of description of MAP_ANONYMOUS. + +rt_sigreturn.2 + Thorsten Kukuk + New link to sigreturn.2. + +rt_sigsuspend.2 + mtk + New link to sigsuspend.2. + +waitid.2 + mtk + Noted that waitid() does not set infop->si_uid field on + most other implementations. + +getopt.3 + Walter harms / mtk + Make clear that when calling getopt_long() and there are no + short options, then 'optstring' should be "", not NULL. + +openpty.3 + Thomas Hood / mtk + In glibc 2.0.92, openpty() was modified to preferably open + Unix 98 ptys instead of BSD ptys. + +qsort.3 + mtk + Small rewording under EXAMPLES. + +strtol.3 +strtoul.3 + Stefan Puiu + s/string must begin/string may begin/ + +proc.5 + mtk + Documented inotify files under /proc/sys/fs/inotify: + max_queued_events, max_user_instances, and max_user_watches. + + +==================== Changes in man-pages-2.23 ==================== + +Released: 2006-02-10 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +Britton Leo Kerin +Dan Jacobson +Justin Pryzby +Luc Van Oostenryck +Kurt Wall +Martin (Joey) Schulze +Matthias Andree +Robert Love +Samuel Thibault +Urs Thuermann + +Apologies if I missed anyone! + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +New pages +--------- + +inotify_init.2 +inotify_add_watch.2 +inotify_rm_watch.2 + Robert Love, with some additions by mtk. + New pages describing the inotify API. + +mbind.2 +get_mempolicy.2 +set_mempolicy.2 + Andi Kleen, with additional work by mtk + New pages describing the NUMA memory allocation policy API. + Drawn from the set at ftp://ftp.suse.com/pub/people/ak/numa. + +rtc.4 + Urs Thuermann, with additional work by mtk + New page describing the real-time clock driver. + +inotify.7 + mtk + Overview of the inotify API. + +Changes to individual pages +--------------------------- + +clone.2 + Andi Kleen + On x86, clone() should not be called through vsyscall, + but directly through "int $0x80". + +fcntl.2 + mtk + Small wording changes. + + Added cross-ref to inotify.7 under the description of dnotify. + +kill.2 + mtk / Britton Leo Kerin + Small wording change under NOTES to clarify + what happens when a process sends a signal to itself. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=350236 + +mlock.2 + mtk / Matthias Andree + Added BUGS txt on interaction between MCL_FUTURE and + RLIMIT_MEMLOCK. + See the following LKML thread: + http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2 + "Rationale for RLIMIT_MEMLOCK" + +msgop.2 + mtk / Samuel Thibault + Rewrote declaration of 'msgp' to be "void *" in response + to http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=350884 + Various other wording fixes. + +open.2 + mtk + Clarify distinction between "file creation flags" and + "file status flags". + +read.2 + Justin Pryzby + Add SEE ALSO for pread(2). + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=351873 + +sched_setaffinity.2 + mtk + Major rewrite. + +select.2 + mtk + Added return types to prototypes for FD_SET(), FD_CLR(), + FD_ZERO, and FD_ISSET(). + Other minor wording changes. + +read.2 + mtk + Add SEE ALSO for pwrite(2). + (Analogous with read.2 change above.) + +errno.3 + Kurt Wall / mtk + Add Linux specific errors to this page. + +localeconv.3 + mtk + Added cross-ref to locale.7 for 'struct lconv' defn. + Other minor wording changes. + Martin (Joey) Schulze + Added SEE ALSO refs for nl_langinfo.3 + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=351831 + +scanf.3 + mtk / Justin Pryzby + Minor formatting & wording fixes. + +setlocale.3 + Martin (Joey) Schulze + Added SEE ALSO refs for nl_langinfo.3 + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=351831 + +proc.5 + mtk + Migrated description of inotify files to the new inotify.7 page. + +ascii.7 + Dan Jacobson / mtk + Add text describing characters 001 to 037. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=342173 + +locale.7 + mtk + Minor wording and formatting changes. + + +==================== Changes in man-pages-2.24 ==================== + +Released: 2006-02-17 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Joerg Habenicht +Luc Van Oostenryck +Mike Frysinger +Samuel Thibault + +Apologies if I missed anyone! + + +New pages +--------- + +get_kernel_syms.2 +create_module.2 +delete_module.2 +init_module.2 +query_module.2 + FSF / mtk (with assistance of Luc Van Oostenryck) + man-pages finally gets pages for these system calls, several + of which are obsolete in Linux 2.6. + Took the old GPLed pages dated 1996 and made a number of + clean-ups and minor additions. + + +Global changes +-------------- + +various pages + mtk + Change "file name" to "filename" + Change "path name" to "pathname" + +stpncpy.3 +strstr.3 +strcmp.3 +toupper.3 +strlen.3 +stpcpy.3 +puts.3 +strdup.3 +strtok.3 +isalpha.3 +strspn.3 +gets.3 +strpbrk.3 + mtk after a suggestion from Samuel Thibault + Added SEE ALSO pointers to wide character equivalent functions + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=351996 + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +clone.2 + mtk + Remove duplicate CLONE_STOPPED text. + Commented out crufty text describing EINVAL error + for the now obsolete CLONE_DETACHED flag. + Under CLONE_SIGHAND, noted that 'flags' must also include + CLONE_VM if CLONE_SIGHAND is specified. + +fcntl.2 + mtk + Under ERRORS: Separate out EAGAIN error for locking mmaped files. + +inotify_add_watch.2 + mtk + Minor wording fix. + +msgop.2 + mtk + Documented the EAGAIN error for msgrcv(). + +fnmatch.3 + Mike Frysinger / mtk + Expand explanation of FNM_PATHNAME. + +lockf.3 + Joerg Habenicht / mtk + Fix up discussion of EAGAIN/EACCESS errors. + + +==================== Changes in man-pages-2.25 ==================== + +Released: 2006-03-02 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +James Peach +Krzysztof Benedyczak +Marten von Gagern +Michael Haardt +Michael Wronksi + +Apologies if I missed anyone! + + +New pages +--------- + +mq_close.3 +mq_getattr.3 +mq_notify.3 +mq_open.3 +mq_receive.3 +mq_send.3 +mq_unlink.3 + mtk + New pages describing POSIX message queue API. + +posix_fallocate.3 + mtk, after a suggestion by James Peach + New page describing posix_fallocate(). + +mq_overview.7 + mtk + New page giving overview of the POSIX message queue API. + + +Changes to individual pages +--------------------------- + +lseek.2 + Michael Haardt + Add a case to the EINVAL error text. + mtk + Various minor wording fixes + Added SEE ALSO referring to new posix_fallocate.3. + +posix_fadvise.2 + mtk + Added "#define _XOPEN_SOURCE 600" to prototype. + Added SEE ALSO referring to new posix_fallocate.3. + +proc.5 + mtk + Migrated information on POSIX message queues to new mqueue.7 page. + +inotify.7 + Marten von Gagern + Fix thinko: s/assuming a non-blocking/assuming a blocking/ + + +==================== Changes in man-pages-2.26 ==================== + +Released: 2006-03-21 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andi Kleen +Andries Brouwer +Christoph Lameter +Hasso Tepper +Justin Pryzby +Martin (Joey) Schulze +Nicolas François +Paul Brook +Siward de Groot +Steve Beattie +Walter Harms + +Apologies if I missed anyone! + +Global changes +-------------- + +clone.2 +getdents.2 +gettid.2 +llseek.2 +mmap2.2 +modify_ldt.2 +pivot_root.2 +quotactl.2 +readdir.2 +sysctl.2 +syslog.2 +tkill.2 + mtk, aeb, Steve Beattie + Added comment in SYNOPSIS to note that syscall(2) may be + preferable over _syscallN (see intro(2)). + +Various minor formatting changes were done on a range of +pages in Section 7. (No content was changed.) + +New pages +--------- + +openat.2 + mtk + New page describing openat(2), added in kernel 2.6.16, + and some notes on rationale for the at*(2) system calls. + +mbind.2 + Andi Kleen, Christoph Lameter, mtk + Added MPOL_MF_MOVE and MPOL_MF_MOVE_ALL descriptions, + from numactl-0.9.2 man page. + Plus a few other smaller fixes. + +fexecve.3 + mtk + New page describing fexecve(3). + +futimes.3 + mtk + New page describing futimes(3). + +Changes to individual pages +--------------------------- + +execve.2 + mtk + Added SEE ALSO pointing to new fexecve.3. + +intro.2 + mtk, aeb, Steve Beattie + Added some notes on syscall(2) versus _syscall. + +msgctl.2 +msgget.2 +msgop.2 + mtk + Added SEE ALSO pointing to mq_overview.7. + +open.2 + mtk + Added SEE ALSO pointing to new openat.2. + + Split out part of the RETURN VALUE text into separate + NOTES section. + + Modified wording referring to raw(8) to + indicate that this interface is deprecated. + +poll.2 + mtk + Added discussion of ppoll(2), which is new in 2.6.16. + +ppoll.2 + mtk + New link to poll.2. + +recvmsg.2 +sendmsg.2 + mtk / Paul Brook + Added text to note that although POSIX says msg_controllen + should be socklen_t, glibc actually uses size_t. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=356502 + and the associated glibc bug report. + http://sourceware.org/bugzilla/show_bug.cgi?id=2448 + mtk + Various formatting fixes. + +select.2 + mtk + Updated to reflect the fact that pselect() has been implemented + in the kernel in 2.6.16; various other minor wording changes. + + pselect() prototype needs "#define _XOPEN_SOURCE 600". + +tempnam.3 + Justin Pryzby + Clean up description of EEXIST error. + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=357893 + +unlink.2 + mtk + Added a little extra text to clarify EISDIR vs EPERM. + +utime.2 + mtk + Added new SEE ALSO entry pointing to new futimes.3 page. + +exec.3 + mtk + Added SEE ALSO pointing to new fexecve.3. + +shm_unlink.3 + mtk + New link to shm_open.3 (should have been made when page + was originally written). + +swab.3 + Walter Harms + Add needed "#define _XOPEN_SOURCE". + +undocumented.3 + mtk + Updated to remove a few function names that are now documented. + +capabilities.7 + mtk + Various changes to bring this page closer to + current kernel versions. + +inotify.7 + mtk + Noted that glibc 2.4 is required to get glibc support + for inotify. + +mq_overview.7 + mtk + Some rewording and added a few words about System V + message queues. + +netlink.7 + Hasso Tepper + Substantial updates to various parts of this page. + mtk, Alain Portal + Minor fixes + +pthreads.7 + mtk + Updated to reflect that the NPTL limitation that only the main + thread could call setsid() and setpgid() was removed in 2.6.16. + +raw.7 + Hasso Tepper + Removed text implying that only in kernel 2.2 does IP_HDRINCL + prevent datagrams from being fragmented. + +socket.7 + mtk + Documented SO_SNDBUFFORCE and SO_RCVBUFFORCE socket options, + new in 2.6.14. + + Placed socket options in alphabetical order. + + +==================== Changes in man-pages-2.27 ==================== + +Released: 2006-03-24 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Charles P. Wright +Christoph Lameter +Chuck Ebbert <76306.1226@compuserve.com> +Daniel Jacobowitz +Ingo Molnar +Heiko Carstens +Janak Desai +Paolo (Blaisorblade) Giarrusso +Stefan Puiu + +Apologies if I missed anyone! + + +Global changes +-------------- + +man7/* + mtk + Various minor formatting changes were done on a range of + pages in Section 7. (No content was changed.) + + +New pages +--------- + +unshare.2 + mtk, with reference to documentation by Janak Desai + New page describing unshare(2), added in kernel 2.6.16. + + +Changes to individual pages +--------------------------- + +clone.2 +fork.2 +vfork.2 + mtk + Added SEE ALSO pointing to new unshare.2. + +mbind.2 + Christoph Lameter + MPOL_MF_MOVE_ALL requires CAP_SYS_NICE not CAP_SYS_RESOURCE. + +mremap.2 + mtk + Clarified the description of MREMAP_FIXED and restructured + the text to reflect the fact that this flag is exposed + by glibc since version 2.4. + +ptrace.2 + Chuck Ebbert, with assistance from Daniel Jacobowitz, + Paolo (Blaisorblade) Giarrusso, and Charles P. Wright; + after a suggestion from Heiko Carstens. + Document the following ptrace requests: + PTRACE_SETOPTIONS (2.4.6) + plus associated flags: + PTRACE_O_TRACESYSGOOD (2.4.6) + PTRACE_O_TRACEFORK (2.5.46) + PTRACE_O_TRACEVFORK (2.5.46) + PTRACE_O_TRACECLONE (2.5.46) + PTRACE_O_TRACEEXEC (2.5.46) + PTRACE_O_TRACEVFORKDONE (2.5.60) + PTRACE_O_TRACEEXIT (2.5.60) + PTRACE_SETSIGINFO (2.3.99-pre6) + PTRACE_GETSIGINFO (2.3.99-pre6) + PTRACE_GETEVENTMSG (2.5.46) + PTRACE_SYSEMU (since Linux 2.6.14) + PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14) + +sched_get_priority_max.2 +sched_setscheduler.2 +sched_setparam.2 + mtk, Ingo Molnar + Modified to document SCHED_BATCH policy, new in kernel 2.6.16. + + Text describing SCHED_BATCH was added to sched_setscheduler.2, + and was drawn in part from Ingo Molnar's description in the + mail message containing the patch that implemented this policy. + + Various other minor rewordings and formatting fixes. + +proc.5 + mtk, using text from Documentation/filesystems/proc.txt + Document /proc/sys/vm/drop_caches, new in kernel 2.6.16. + mtk, using information from ChangeLog-2.6.14. + Document /proc/PID/smaps, new in kernel 2.6.14. + +capabilities.7 + mtk + Noted affect of CAP_SYS_NICE for mbind(MPOL_MF_MOVE_ALL). + +pthreads.7 + mtk + Kernel 2.6.16 eliminated buggy behavior with respect to + the alternate signal stack. + + +==================== Changes in man-pages-2.28 ==================== + +Released: 2006-03-31 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Aleksandr Blokhin +Greg Johnson + +Apologies if I missed anyone! + + +New pages +--------- + +sem_post.3 +sem_getvalue.3 +sem_close.3 +sem_open.3 +sem_destroy.3 +sem_wait.3 +sem_unlink.3 +sem_init.3 +sem_overview.7 + mtk + New pages describing the POSIX semaphores API. + + These pages supersede and provide a superset of the information + in the glibc (3thr) "semaphores(3)" manual page. + + +Changes to individual pages +--------------------------- + +ppoll.2 + Aleksandr Blokhin + Fix broken link. + +ptrace.2 + mtk + Wrapped long lines (no content changes). + +semctl.2 +semget.2 +semop.2 + mtk + Add SEE ALSO pointing to the new sem_overview.7 page. + +elf.5 + Greg Johnson + Removed SEE ALSO reference to nonexistent core(5). + + +==================== Changes in man-pages-2.29 ==================== + +Released: 2006-04-06 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Michael Haardt +Roberto Jimenoca +Stefan Puiu + +Apologies if I missed anyone! + + +Global changes +-------------- + +getrlimit.2 +prctl.2 +sigaction.2 +elf.5 +signal.7 + mtk + Added SEE ALSO entry referring to new core.5 page. + + +New pages +--------- + +mkdirat.2 + mtk + New page describing mkdirat(2), new in 2.6.16. + +mknodat.2 + mtk + New page describing mknodat(2), new in 2.6.16. + +core.5 + mtk + New page describing core dump files. + +mkfifoat.3 + mtk + New page describing mkfifoat(3). + + +Changes to individual pages +--------------------------- + +accept.2 +getpeername.2 +getsockname.2 + Michael Haardt / mtk + Document EINVAL error for 'len' argument < 0. + +fcntl.2 + mtk + Expanded discussion of mandatory locking. + +getrlimit.2 + mtk + Added BUGS text on 2.6.x handling of RLIMIT_CPU limit + of zero seconds. See + http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2 + +mkdir.2 + mtk + Added SEE ALSO entry referring to new mkdirat.2. + +mknod.2 + mtk + Added SEE ALSO entry referring to new mknodat.2. + +open.2 + mtk / Roberto Jimenoca + Clarified discussion of file types affected by O_NONBLOCK. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=360243 + +openat.2 + mtk + Rewrote NOTES describing rationale for openat(). + Various other minor changes. + +recv.2 + Stefan Puiu + Removed a misleading cross-ref to socket.2. + +shmop.2 + mtk + Since 2.6.17-rc1, shmdt() gives the error EINVAL in a further + circumstance: if shmaddr is not aligned on a page boundary. + +unshare.2 + mtk + Remove text saying that specifying invalid flags "is likely + to cause compatibility problems" since the kernel now + (2.6.17-rc1) contains an explicit check for invalid bits + with a consequent EINVAL error. + +mkfifo.3 + mtk + Added SEE ALSO entry referring to new mkfifoat.3. + +proc.5 + mtk + Information on core_pattern and core_uses_pid has + been migrated to the new core.5 page. + +ip.7 + Stefan Puiu + Removed paragraph referring to obsolete ipchains / ipfw(4). + +sem_overview.7 + mtk + Add SEE ALSO entry referring to pthreads.7. + + +==================== Changes in man-pages-2.30 ==================== + +Released: 2006-04-17 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andre Lehovich +Andries Brouwer +Karel Kulhavy +Stefan Puiu + +Apologies if I missed anyone! + + +New pages +--------- + +linkat.2 + mtk + New page describing linkat(), new in kernel 2.6.16 + +renameat.2 + mtk + New page describing renameat(), new in kernel 2.6.16 + +symlinkat.2 + mtk + New page describing symlinkat(), new in kernel 2.6.16 + +unlinkat.2 + mtk + New page describing unlinkat(), new in kernel 2.6.16 + + +Changes to individual pages +--------------------------- + +link.2 + mtk + Added SEE ALSO entry pointing to new linkat.2 page. + +openat.2 + mtk + Added SEE ALSO entries pointing to new *at.2 pages. + +rename.2 + mtk + Added SEE ALSO entry pointing to new renameat.2 page. + +rmdir.2 + mtk + Added SEE ALSO entry pointing to new unlinkat.2 page. + +symlink.2 + mtk + Added SEE ALSO entry pointing to new symlinkat.2 page. + +unlink.2 + mtk + Added SEE ALSO entry pointing to new unlinkat.2 page. + +termios.3 + mtk / Karel Kulhavy + Document the feature test macros required to expose various flags. + Karel Kulhavy + Clarify 'speed' argument for cfsetispeed() text. + Karel Kulhavy / mtk + Note that LOBLK is not implemented on Linux. + mtk + Clarify arguments for cfsetspeed(). + Various formatting changes. + +full.4 + Andre Lehovich + Add a sentence describing the purpose of full(4). + +core.5 + aeb / mtk + Rework text describing circumstances in which + core dump files are not produced. + mtk / Stefan Puiu + A core dump of a multithreaded process always includes the + PID in the core filename. + mtk / Stefan Puiu + Eliminate some accidentally duplicated text. + + +==================== Changes in man-pages-2.31 ==================== + +Released: 2006-05-02 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Joshua Kwan +Justin Pryzby +Karel Kulhavy +Mark Glines +Martin (Joey) Schulze +Nishanth Aravamudan +Reuben Thomas +Ryan S. Arnold +Ulrich Drepper + +Apologies if I missed anyone! + + +Page renamings +-------------- + +The following pages have been relocated into section 7, since +that is their more natural home. SEE ALSO references in various +other pages have been adjusted. + +epoll.4 +fifo.4 +futex.4 +complex.5 +environ.5 + (many pages outside man-pages actually *expect* + 'environ' to be in Section 7.) + +ipc.5 + renamed to svipc.7 + +".so" link files have been created to link the old file locations to the +new file locations. These links are added just to ensure that cross +references from any other (non-man-pages) pages will remain valid; +eventually these links will be removed. + + +New pages +--------- + +fstatat.2 + mtk + New page for fstatat(2), new in 2.6.16. + +adjtime.3 + mtk + New page for adjtime(3). + +error.3 + Justin Pryzby / mtk + New page describing error() and error_at_line() + Fixes http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=186307 + +program_invocation_name.3 + mtk + New page describing program_invocation_name and + program_invocation_short_name variables. + +sockatmark.3 + mtk + New page for sockatmark(3). + +ftm.7 + mtk + New page describing feature test macros. + +time.7 + mtk + New page giving an overview of "time" on Linux systems. + + +Global changes +-------------- + +getgroups.2 +wait4.2 +chown.2 +chdir.2 +gettimeofday.2 +initgroups.3 +dirfd.3 + mtk + Simplified wording around requirement for _BSD_SOURCE + feature test macro. + +times.2 +time.2 +gettimeofday.2 +getitimer.2 +nanosleep.2 +ctime.3 +rtc.4 + mtk + Added SEE ALSO referring to new time.7. + +err.3 +errno.3 +perror.3 +strerror.3 + Justin Pryzby / mtk + Add SEE ALSO referring to new error.3. + +getdate.3 +printf.3 +scanf.3 + mtk + Added SEE ALSO entry referring to setlocale.3. + + +Changes to individual pages +--------------------------- + +accept.2 + Mark Glines + Remove mention of SOCK_RDM from this page, since this socket + type does not support accept()ing connections. + +adjtimex.2 + mtk + Modified text referring to adjtime(); added SEE ALSO for new + adjtime.3 page. + +fsync.2 + mtk, after a note by Karel Kulhavy + Rewrote most of the DESCRIPTION, as well as some other parts + the page, to clarify use and operation of, and rationale for, + fsync(2) and fdatasync(2). + +getitimer.2 + mtk + Updated discussion of maximum timer value to reflect the fact + that the default jiffy is now 4 milliseconds. + + Added text to note that current incorrect behavior of + normalizing tv_usec >= 1000000 will be repaired in a future + kernel; applications should be fixed now. + +gettimeofday.2 + Karel Kulhavy + Point out more explicitly that 'tz' argument should + normally be NULL. + mtk + Various other minor edits and formatting fixes. + +mount.2 + mtk + Since kernel 2.6.16, MS_NOATIME and MS_NODIRATIME are settable + on a per-mount basis. + Detail exactly which mount flags can be changed on MS_REMOUNT. + +nanosleep.2 + mtk / Karel Kulhavy + Clarify RETURN VALUE discussion. + +openat.2 + mtk + Add SEE ALSO reference pointing to new fstatat.2. + +program_invocation_short_name.3 + mtk + New link to new program_invocation_name.3. + +recv.2 + mtk + Added SEE ALSO for new sockatmark.3. + +rmdir.2 + Joshua Kwan / Martin (Joey) Schulze / mtk + Correct wording of EBUSY case. + mtk + Add ".." case to ENOTEMPTY error + +select.2 + Karel Kulhavy + Note more clearly that fd_set arguments can be NULL. + mtk / Karel Kulhavy + Improve opening paragraph describing purpose of select(). + mtk + Various other minor edits and formatting fixes. + +semget.2 + mtk / Nishanth Aravamudan + Add text to noting that the initial values of semaphores + in a new set are indeterminate. + +shmget.2 + mtk + Add text noting that contents of newly created segment are zero + values. + +sigwaitinfo.2 + mtk + Noted that all threads should block signal being waited for. + +stat.2 + Nishanth Aravamudan / mtk + Added NOTE that st_size is always returned as zero for most + /proc files. + mtk + Add SEE ALSO reference pointing to new fstatat.2. + +syscall.2 + Justin Pryzby / mtk + Remove bogus BUGS text. + +utime.2 + mtk + Various minor changes. + +confstr.3 + mtk + Rewrote RETURN VALUE discussion. + Updated CONFORMING TO. + Removed BUGS. + +ctanh.3 + Martin (Joey) Schulze / mtk + Fix errors in DESCRIPTION. + +ctime.3 + mtk + The range of tm_sec is 0..60 (not 0..61). + +error_at_line.3 +error_message_count.3 +error_on_per_line.3 +error_print_progname.3 + mtk + New links to new error.3. + +fmemopen.3 + mtk / Ryan S. Arnold + Add text noting that explicitly controlling output buffering + may be useful to catch errors on output operations on an + fmemopen() stream. + +getline.3 + Justin Pryzby + Add SEE ALSO pointing to getline.3. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=364772 + +strtod.3 +strtoul.3 + mtk + Describe correct handling of errno in order to + distinguish error from success after the call. + + Added EXAMPLE section which points to strtol.3 which provides + an example of the use of the analogous strtol(3). + +strtol.3 + mtk / Justin Pryzby + Add an example program. + mtk + Describe correct handling or errno in order to + distinguish error from success after the call. + +tmpfile.3 + Reuben Thomas + DESCRIPTION does not need to say "temporary file name" + just "temporary file", since the name is in any case + unavailable to the user. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=363518 + mtk + In DESCRIPTION: + Change /automatically deleted when the program terminates normally/ + to /automatically deleted when the program terminates/ + since deletion occurs on both normal and abnormal termination. + +ip.7 + Karel Kulhavy / mtk + Various wording improvements and clarifications. + +signal.7 + mtk / Ulrich Drepper + Add text noting that a signal's disposition is process-wide, + shared by all threads. + mtk + Add text on changing signal dispositions. + Add text on "signal mask and pending signals". + Other minor edits. + +time.7 + mtk + Added SEE ALSO for new adjtime.3. + +ld.so.8 + Justin Pryzby + Remove bogus duplicate line. + + +==================== Changes in man-pages-2.32 ==================== + +Released: 2006-05-13 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Johannes Weiner +Justin Pryzby +Karel Kulhavy +Paul Brook +Pavel Heimlich + +Apologies if I missed anyone! + + +New pages +--------- + +faccessat.2 + mtk + New page for faccessat(2), new in 2.6.16. + +fchmodat.2 + mtk + New page for fchmodat(2), new in 2.6.16. + +fchownat.2 + mtk + New page for fchownat(2), new in 2.6.16. + +futimesat.2 + mtk + New page for futimesat(2), new in 2.6.16. + + +Changes to individual pages +--------------------------- + +access.2 + mtk + Add SEE ALSO reference pointing to new faccessat.2 page. + +capget.2 + mtk + Reworded to reflect that capabilities are per-thread. + +chmod.2 + mtk + Add SEE ALSO reference pointing to new fchmodat.2 page. + +chown.2 + mtk + Add SEE ALSO reference pointing to new fchownat.2 page. + +mmap.2 + mtk + Updated discussion of MAP_NORESERVE since it is no longer + restricted to MAP_PRIVATE mappings. + Add reference to discussion of /proc/sys/vm/overcommit_memory + in proc.5. + +openat.2 + mtk + Add SEE ALSO reference pointing to new faccessat.2, fchmodat.2, + fchownat.2, futimesat.2 pages. + +shmget.2 + mtk + Document SHM_NORESERVE flag, new in 2.6.15. + +truncate.2 + Paul Brook / mtk + Expand text noting that ftruncate()/truncate() may fail if + asked to extend a file beyond its current length. + Add EPERM error. + +utime.2 + mtk + Add SEE ALSO reference pointing to new futimesat.2 page. + +fopen.3 + Justin Pryzby / mtk + Document 'm' (mmap) flag. + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=365754 + mtk + Document 'c' (notcancel) flag. + +futimes.3 + mtk + Add SEE ALSO reference pointing to new futimesat.2 page. + +qsort.3 + Johannes Weiner + Add missing "const" qualifies to cast in EXAMPLE. + mtk + Slight rewording of comments in EXAMPLE. + +termios.3 + Karel Kulhavy + Clarify meaning of IXANY. + Clarify relationship of MIN with VMIN and TIME with VTIME. + mtk + Noted that CIBAUD, OFDEL, and DELECHO are not implemented + on Linux. + Added explanatory paragraph for phrases "not in POSIX" and + "XSI". + +capabilities.7 + mtk + Reworded to reflect that capabilities are per-thread. + Add ioprio_set() to list of operations permitted by + CAP_SYS_NICE. + Add ioprio_set() IOPRIO_CLASS_RT and IOPRIO_CLASS_IDLE + scheduling classes to list of operations permitted by + CAP_SYS_ADMIN. + Note effects of CAP_SYS_NICE for migrate_pages(). + + +==================== Changes in man-pages-2.33 ==================== + +Released: 2006-05-23 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Justin Pryzby +Martin Osvald" +Stefan Puiu + +Apologies if I missed anyone! + + +Page renamings +-------------- + +ftm.7 + mtk / Stefan Puiu + renamed to the more suggestive feature_test_macros.7 + + +New pages +--------- + +mq_getsetattr.2 + mtk + New page briefly describing mq_getsetattr(2), the system + call that underlies mq_setattr(3) and mq_getattr(3). + +rpmatch.3 + Justin Pryzby / mtk + New page for rpmatch(3). + + +Changes to individual pages +--------------------------- + +chmod.2 + mtk + Remove mention of non-standard S_IREAD, S_IWRITE, S_IEXEC. + POSIX does now document ELOOP. + +open.2 + mtk + Remove mention of non-standard S_IREAD, S_IWRITE, S_IEXEC. + +mmap.2 + Justin Pryzby + Add mincore(2) to SEE ALSO. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=367401 + +msync.2 + Justin Pryzby + Note that EINVAL can also be caused by + flags == MS_SYNC | MS_ASYNC. + +sched_setaffinity.2 + mtk + Add CPU_ISSET, CPU_CLR, CPU_SET, CPU_ZERO to NAME section. + +select.2 + mtk + Various minor changes. + +select_tut.2 + mtk + Removed much material that is redundant with select.2. + Various other changes. + +umask.2 + mtk + Substantial rewrite of description of 'mask'. + +CPU_ISSET.3 +CPU_CLR.3 +CPU_SET.3 +CPU_ZERO.3 + mtk + New links to sched_setaffinity.2 + +FD_CLR.3 +FD_ISSET.3 +FD_SET.3 +FD_ZERO.3 + mtk + New links to select.2. + +fts.3 + Justin Pryzby + Add SEE also referring to ftw.3. + +ftw.3 + Justin Pryzby + Add SEE also referring to fts.3. + +getline.3 + Justin Pryzby + Various minor clarifications. + +mkstemp.3 + mtk + Clarify that O_EXCL is an open(2) flag. + +mq_open.3 + Martin Osvald + Fix prototype declaration for 'attr'. + +mq_notify.3 + Martin Osvald + s/sigev_signal/sigev_signo/ + +mq_setattr.3 + mtk + New link to mq_getattr.3. + +mq_timedreceive.3 + mtk + New link to mq_receive.3. + +mq_timedsend.3 + mtk + New link to mq_send.3. + +setlocale.3 + Justin Pryzby + Added SEE ALSO referring to rpmatch.3. + +sigandset.3 +sigisemptyset.3 +sigorset.3 + mtk + New links to sigsetops.3. + +stdio.3 + Justin Pryzby + Added SEE ALSO referring to unlocked_stdio.3 + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=367667 + +strchr.3 + Justin Pryzby + Add description of strchrnul(). + +strchrnul.3 + mtk + New link to strchr.3. + +undocumented.3 + Justin Pryzby / mtk + Updated to remove some functions that don't exist, and + therefore don't need to be documented. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=367671 + +unlocked_stdio.3 + Justin Pryzby + Added SEE ALSO referring to stdio.3 + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=367667 + +mq_overview.7 + mtk + Added section describing relationship between library + interfaces and system calls. + Added SEE ALSO referring to new mq_getsetattr.2. + +feature_test_macros.7 + Stefan Puiu + Fix typo: s/_POSIX_C_SOURCE/_POSIX_SOURCE/ + + +==================== Changes in man-pages-2.34 ==================== + +Released: 2006-06-20 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Aristeu Sergio Rozanski Filho +bert hubert +Chris Curtis +Eduardo Madeira Fleury +Joerg Scheurich +Justin Pryzby +Kenichi Okuyama +Marc Lehmann +Martin (Joey) Schulze +Mats Wichmann +Mike Frysinger +Peter Eiserloh +Stefan Puiu +Thomas Dickey +Walter Harms + +Apologies if I missed anyone! + + +Global changes +-------------- + +tzselect.8 +zdump.8 +zic.8 + mtk, Joey + Added header comment noting that these pages are in the public + domain. + +bindresvport.3 +getrpcent.3 +getrpcport.3 +rpc.3 +xdr.3 +rpc.5 + mtk, aeb, Joey + Added following to top of these pages to clarify origin and + license: + .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) + +New pages +--------- + +ioprio_set.2 + Eduardo Madeira Fleury, with edits by mtk, and review by Jens Axboe + New page for ioprio_get(2) and ioprio_set(2), new in 2.6.13. + +offsetof.3 + Justin Pryzby / mtk + New page describing offsetof() macro. + + +Changes to individual pages +--------------------------- + +_exit.2 + mtk + Add SEE ALSO referring to exit_group.2. + +acct.2 + mtk + Add SEE ALSO referring to acct.5. + +fcntl.2 + mtk + Explicitly mention term "dnotify" in discussion of F_NOTIFY. + +inotify_add_watch.2 + Aristeu Sergio Rozanski Filho / mtk + s/// in prototypes. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369960 + mtk + Renamed argument from 'path' to 'pathname'. + Reword introductory paragraph to clarify that + inotify_add_watch() may also modify an existing watch item. + mtk + The EINVAL error can also occur if 'fd' is not an inotify + file descriptor. + mtk + Moved BUGS section from this page to inotify.7. + +inotify_init.2 + Aristeu Sergio Rozanski Filho / mtk + s/// in prototypes. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369960 + +inotify_rm_watch.2 + Aristeu Sergio Rozanski Filho / mtk + s/// in prototypes. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369960 + mtk + The EINVAL error can also occur if 'fd' is not an inotify + file descriptor. + +ioprio_get.2 + mtk + New link to new ioprio_set.2. + +mmap.2 + mtk + Add SEE ALSO referring to remap_file_pages.2. + +mount.2 + Kenichi Okuyama + s/MNT_FORCE/MNT_EXPIRE/ under EINVAL error. + +mremap.2 + Mike Frysinger + s/unsigned long flags/int flags/ in SYNOPSIS. + +pipe.2 + mtk + Add SEE ALSO referring to popen.3. + +posix_fadvise.2 + mtk + Add SEE ALSO referring to readahead.2. + +read.2 + mtk + SEE ALSO for readv should refer to Section 2, not 3. + +readahead.2 + mtk + Add SEE ALSO referring to posix_fadvise.2. + +send.2 + Peter Eiserloh + Fix missing arguments in statement about equivalent send() + and sendto() calls. + +setsid.2 + mtk + Add SEE ALSO referring to tcgetsid.3. + +shmctl.2 + mtk + Minor wording change at start of DESCRIPTION. + +stat.2 + mtk + Add SEE ALSO referring to access.2. + +statfs.2 + mtk + Relocated "Note" about f_fsid. + +write.2 + mtk + SEE ALSO for writev should refer to Section 2, not 3. + +__setfpucw.3 + mtk, Joey + Added license statement (GPL) after consultation with + Joerg Scheurich. + +assert_perror.3 + Justin Pryzby + Add #define _GNU_SOURCE to prototype + +difftime.3 + Joey + Added note about time_t representation on other systems. + Added CONFORMING TO. + +ftw.3 + Justin Pryzby / mtk + A fairly major revision... + Document FTW_ACTIONRETVAL; include .SH "RETURN VALUE"; + Reorganized and rewrote much of the page + Added an example program. + +inet.3 + Marc Lehmann + Fixed typo in NOTES. + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=370277 + +isalpha.3 + Joey + Updated CONFORMING TO. + +mktemp.3 + mtk + Updated CONFORMING TO. + +printf.3 + Walter Harms + Add documentation of %m. + +readdir.3 + mtk + Added SEE ALSO referring to ftw.3. + +re_comp.3 + mtk + Note that these functions are obsolete in favor of regcomp(3). + Justin Pryzby + Add SEE ALSO referring to regcomp.3 + +scandir.3 + Mats Wichmann + Reworded CONFORMING TO statement on scandir() and alphasort(). + +strchr.3 + Stefan Puiu + Fix prototype for strchrnul(). + +strtoul.3 + Stefan Puiu + Add text clarifying treatment of strings starting with + minus sign. + +tmpnam.3 + mtk, after comments by Justin Pryzby + Add text noting the need to use open(O_EXCL). + mtk + Clarify discussion of use of free(3). + Various other minor changes to text and formatting. + +tmpfile.3 + mtk + Updated CONFORMING TO. + +tmpnam.3 + mtk, after comments by Justin Pryzby + Add text noting the need to use open(O_EXCL). + Updated CONFORMING TO. + +undocumented.3 + mtk + Remove offsetof(), which is now documented. + +null.4 + mtk + Added SEE ALSO referring to full.4. + +console_codes.4 + Thomas Dickey + Various improvements and corrections. + +epoll.7 + mtk + Added CONFORMING TO section mentioning FreeBSD kqueue and + Solaris /dev/poll. + +feature_test_macros.7 + mtk + Added pointer to location of LFS specification. + +futex.7 + mtk, after suggestion by Joey. + Added license statement to page, after discussion with + original author, bert hubert. + mtk + Reformat long lines; no content changes. + +inotify.7 + mtk + 'path' argument renamed to 'pathname'. + A few minor rewordings. + Added BUGS section describing a couple of bugs. + +ip.7 + mtk + Add SEE ALSO referring to byteorder.3. + +man.7 + Justin Pryzby + Add SEE ALSO referring to groff_man(7). + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=369253 + + +==================== Changes in man-pages-2.35 ==================== + +Released: 2006-07-06 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andi Kleen +Andrew Morton +Bauke Jan Douma +Davide Libenzi +Denis Barbier +Horacio Rodriguez Montero +Johan Lithander +Justin Pryzby +Mike Frysinger +Stefan Puiu +Thorsten Kukuk + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + +New pages +--------- + +sync_file_range.2 + Andrew Morton / mtk + New page for sync_file_range(2), new in kernel 2.6.17. + +Changes to individual pages +--------------------------- + +adjtime.3 + mtk + Noted BUG that occurs if 'delta' is specified as NULL. + See http://bugzilla.kernel.org/show_bug.cgi?id=6761 + +bind.2 + Stefan Puiu + Add EADDRNOTAVAIL error. + Stefan Puiu / mtk + Make example code more complete. + +epoll_ctl.2 + mtk / Davide Libenzi + Added EPOLLRDHUP description. + mtk + Added SEE ALSO referring to poll.2. + +poll.2 + mtk / Davide Libenzi + Added POLLRDHUP description. + mtk + The correct header file is , not . + Rewrote and reformatted various other parts. + +readlink.2 + mtk + Nowadays, readlink() returns 'ssize_t', as required in + POSIX.1-2001. + +wavelan.4 + mtk + Added license statement. + +nscd.conf.5 + Thorsten Kukuk + Add documentation for various new fields. + +passwd.5 + Horacio Rodriguez Montero + Add explanation of 'x' character in 'password' field. + mtk + The proper name of "*" is "asterisk" not "star". + +tcp.7 + Johan Lithander + Update RFC reference for ECN. + Andi Kleen + Add sentence on "low memory" limit for tcp_mem on 32-bit systems. + + +==================== Changes in man-pages-2.36 ==================== + +Released: 2006-07-11 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Jens Axboe +Justin Pryzby +Kyle McMartin + +Apologies if I missed anyone! + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + +New pages +--------- + +MAINTAINING + mtk + How to maintain man-pages. + +TODO + mtk + Things that it would be nice to get done for man-pages one day. + +scripts/FIXME_list.sh + mtk + This script, intended for use by manual page maintainers, + displays the FIXMEs in the manual page source files. + +Changes to individual pages +--------------------------- + +fdatasync.2 +fsync.2 + mtk + Added SEE ALSO referring to sync_file_range.2. + +sendfile.2 + mtk / Jens Axboe + Fix description of 'offset' argument to explain the case + where 'offset' is NULL. + +ferror.3 + Justin Pryzby + Add SEE ALSO referring to fdopen.3. + +intro.3 + mtk + Removed information about Section 3 subsections -- it doesn't + reflect current reality, and probably never has. + + Added SEE ALSO referring to intro.2. + +tcp.7 + Kyle McMartin + Correction: tcp_window_scaling is ENabled by default. + + +==================== Changes in man-pages-2.37 ==================== + +Released: 2006-08-02 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Dean Gaudet +Frank van Viegen +Helmut Grohne +Ivana Varekova +Thomas Huriaux +Ville Skyttä + +Apologies if I missed anyone! + +Global changes +-------------- + +Thomas Huriaux / mtk + + Various formatting problems found as a result of reviewing the + following command were fixed. + + for a in $(wc -l man?/*.?| awk '$1 > 2 {print $2}' | grep -v total); do + echo $a; groff -Tascii -wmac -mman $a > /dev/null; + done 2>&1 | less + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=378544 + +Typographical or grammatical errors have been corrected in several +places. + +New pages +--------- + +readlinkat.2 + mtk (after prompting from Ivana Varekova) + New page for readlinkat(2), new in kernel 2.6.16. + +Changes to individual pages +--------------------------- + +ldd.1 + Ville Skyttä + Document "-u" option. + +chdir.2 + mtk + Noted effect of fork() and execve() on current working directory. + +chroot.2 + mtk + Noted effect of fork() and execve() on root directory. + +epoll_ctl.2 + Frank van Viegen / mtk + Fix description of EBADF error. + +exevce.2 + mtk + Add text noting that effective IDs are copied to + saved set-IDs during execve(). + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=379297 + +getitimer.2 + mtk + Noted effect of fork() and execve() on interval timers. + +getrlimit.2 + mtk + Noted effect of fork() and execve() on resource limits. + +getpriority.2 + mtk + Noted effect of fork() and execve(). + +inotify_add_watch.2 + mtk + Some rewording; included text describing required file + permissions. + +intro.2 + mtk + Revised description of standards under CONFORMING TO. + +makecontext.3 + Helmut Grohne / mtk + Point out that args following 'argc' are int. + mtk + Added an example program. + Various minor wording fixes. + +mmap.2 + mtk + Expand description of MAP_POPULATE. + mtk, after prompting by Dean Gaudet + Expand description MAP_NONBLOCK. + mtk + Various minor formatting fixes. + +openat.2 + mtk + Added SEE ALSO linking to readlinkat.2. + +nanosleep.2 + mtk + Noted buggy behavior in Linux 2.4 and earlier when + nanosleep() is restarted after receiving stop+SIGCONT signals. + +nice.2 + mtk + Very minor rewording. + +readlink.2 + mtk + Added SEE ALSO linking to readlinkat.2. + +sched_setscheduler.2 + mtk + Noted preservation of scheduling parameters across execve(). + +setpgid.2 + mtk + Noted effect of fork() and execve() on process group ID. + +setsid.2 + mtk + Noted effect of fork() and execve() on session ID. + +umask.2 + mtk + Noted effect of fork() and execve() on umask. + +atexit.3 + mtk + Noted inheritance of registrations across fork(). + +capabilities.7 + mtk + Added material on privileges required for move_pages(). + CLONE_NEWNS needs CAP_SYS_ADMIN. + keyctl(KEYCTL_CHOWN) and keyctl(KEYCTL_SETPERM) require + CAP_SYS_ADMIN. + + +==================== Changes in man-pages-2.38 ==================== + +Released: 2006-08-03 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal + +Apologies if I missed anyone! + +Global changes +-------------- + +Most pages + mtk + There was a major reworking of the CONFORMING TO sections + in most manual pages. + + * generally try to rationalize the names used for standards. + The preferred names are now documented as the head words + of the list in standards(7). For the future: there is + probably no need to talk about anything more than + C89, C99, POSIX.1-2001 (or later), xBSD, and SVr4. + (In particular, I've eliminated most references to XPG + and SVID, replacing them with references to SUS or SVr4.) + + * eliminate discussion of errors that can occur on other + systems. This information exists only patchily in the + manual pages, is probably of limited use, is hard to maintain, + and was in some cases simply wrong (and probably always was). + + * Tried to ensure that those interfaces specified in C99 or + POSIX.1-2001 are marked as such in their manual pages. + +intro.1 +intro.2 +intro.3 +intro.4 +intro.5 +intro.7 +feature_test_macros.7 + mtk + Added SEE ALSO referring to new standards.7. + +Various pages + mtk + Changed instances of "HP UX" to "HP-UX". + +Various pages + mtk + Changed instances of "DG-UX to "DG/UX" + +Typographical or grammatical errors have been corrected in several +places. + +New pages +--------- + +standards.7 + mtk + Based on material taken from intro.2, but expanded to + include discussion of many additional standards. + +Changes to individual pages +--------------------------- + +bind.2 + mtk + Minor wording change for ENOTSOCK error. + +intro.2 + mtk + Removed information on standards to new standards.7. + + +==================== Changes in man-pages-2.39 ==================== + +Released: 2006-08-05 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal + +Apologies if I missed anyone! + +Global changes +-------------- + +Various pages + mtk + Updated CONFORMING TO and/or standards references + in various pages that were missed for 2.38. + +Typographical or grammatical errors have been corrected in several +places. + +Changes to individual pages +--------------------------- + + +chdir.2 + mtk + _XOPEN_SOURCE=500 also gets fchdir() prototype. + +standards.7 + mtk + Added a few more standards, and expand some explanations. + + +==================== Changes in man-pages-2.40 ==================== + +Released: 2006-09-04 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andi Kleen +Andries Brouwer +Christoph Hellwig +Chuck Ebbert <76306.1226@compuserve.com> +Samuel Thibault +Toralf Förster + +Apologies if I missed anyone! + +Global changes +-------------- + +faccessat.2 +fchmodat.2 +fchownat.2 +fstatat.2 +futimesat.2 +linkat.2 +mkdirat.2 +mknodat.2 +openat.2 +readlinkat.2 +renameat.2 +symlinkat.2 + mtk (after a note by Alain Portal) + Make naming of 'pathname' argument consistent; various + minor rewordings. + +Typographical or grammatical errors have been corrected in several +places. + +Changes to individual pages +--------------------------- + +clone.2 + mtk + Reinstate text on CLONE_DETACHED, and add a few words. + +execve.2 + mtk + Added list of process attributes that are not preserved on exec(). + +fork.2 + mtk, after a suggestion by Christoph Hellwig + Greatly expanded, to describe all attributes that differ + in parent and child. + +linkat.2 + mtk + Document AT_SYMLINK_FOLLOW (new in 2.6.18). + +set_mempolicy.2 + mtk / Andi Kleen + Memory policy is preserved across execve(). + +write.2 + mtk / Alain Portal + SEE ALSO for writev should refer to Section 2, not 3. + (i.e., really make the change that was logged in 2.34) + +getcwd.3 + Samuel Thibault / mtk + Fix SYNOPSIS and CONFORMING TO text for getwd() and + get_current_dir(). + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=381692 + +proc.5 + Chuck Ebbert + Document /proc/PID/auxv. + +capabilities.7 + Alain Portal + Restore text accidentally deleted in 2.39. + +regex.7 + mtk / Alain Portal + Change references to "1003.2" to "POSIX.2". + + +==================== Changes in man-pages-2.41 ==================== + +Released: 2006-10-12 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +Andries Brouwer +Andrew Morton +Britton Leo Kerin +Dan Jacobson +Guillem Jover +Hrvoje Niksic +Jens Axboe +Justin Pryzby +Kevin Ryde +Marcel Holtmann +Senthil Kumar +Stefan Puiu +Stuart MacDonald +Trond Myklebust + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +New pages +--------- + +splice.2 +tee.2 +vmsplice.2 + Jens Axboe / Michael Kerrisk + See also: + http://lwn.net/Articles/118760/ + http://lwn.net/Articles/178199/ + http://lwn.net/Articles/179492/ + http://kerneltrap.org/node/6505 + http://lwn.net/Articles/179434/ + +Changes to individual pages +--------------------------- + +ldd.1 + Stefan Puiu + Note glibc version where "ldd -u" appeared. + +execve.2 + mtk + The PR_SET_NAME setting is not preserved across an execve(). + +fork.2 + mtk + Mappings marked with madvise(MADV_DONTFORK) are not inherited + by child. + +getdtablesize.2 + mtk + Noted that sysconf(_SC_OPEN_MAX) is preferred in portable + applications. + +getpagesize.2 + mtk + Noted that sysconf(_SC_PAGE_SIZE) is preferred in portable + applications. + _SC_PAGE_SIZE is available on most systems. + +madvise.2 + mtk + Document MADV_REMOVE, new in 2.6.16. + Document MADV_DONTFORK / MADV_DOFORK, new in 2.6.16. + +mount.2 + mtk / Trond Myklebust + MNT_FORCE can cause data loss. + +mmap.2 + mtk + Added note on Linux's old (pre-2.6.12) buggy treatment of + length==0. + Justin Pryzby / mtk + Added some EINVAL errors. + +mremap.2 + mtk + Remove superfluous "#include " from SYNOPSIS. + +msync.2 + mtk + Added EBUSY error for case where MS_INVALIDATE is applied to + a locked region. + +posix_fadvise.2 + Andrew Morton + Since 2.6.18, POSIX_FADV_NOREUSE is a no-op. + +prctl.2 + Marcel Holtmann / mtk + Since kernel 2.6.18, setting 2 for PR_SET_DUMPABLE is no longer + possible. + Guillem Jover + Updated Linux versions where the options where introduced. + Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME, + PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU, + PR_SET_FPEXC, PR_GET_FPEXC. + Michael Kerrisk + Document PR_GET_ENDIAN and PR_SET_ENDIAN. + +remap_file_pages.2 + mtk + Add "#define _GNU_SOURCE" to SYNOPSIS. + +sync_file_range.2 + mtk + Noted that sync_file_range() appeared in kernel 2.6.17. + +vfork.2 + mtk + Noted interactions with fork handlers in multithreaded programs. + +wait4.2 + mtk + Added feature test macros to SYNOPSIS. + +clog2.3 + mtk / aeb / Kevin Ryde + Fix broken text in description. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=386214 + +clog10.3 + Kevin Ryde + Fix broken text in description. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=386214 + +mq_receive.3 + Britton Leo Kerin + Fix return type in SYNOPSIS; should be "ssize_t" not "mqd_t". + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=387551 + +qsort.2 + Hrvoje Niksic + Fix wording referring to the use of strcmp() in 'compar' + function. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=391402 + +sendfile.2 + mtk + Added SEE ALSO referring to new splice.2 page. + +termios.3 + mtk + Documented IUTF8 (which was new in kernel 2.6.4). + +tzset.3 + mtk + Added some TZ examples. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=386087 + +proc.5 + mtk + Added delayacct_blkio_ticks (new in 2.6.18) to /proc/PID/statm. + +ip.7 + Stuart MacDonald / Andi Kleen + Fix discussion for TCP error queue /IP_RECVERR on TCP. + +pthreads.7 + mtk + Noted effect of RLIMIT_STACK resource limit for NPTL. + +socket.7 + Senthil Kumar + Place socket options in alphabetical order. + + +==================== Changes in man-pages-2.42 ==================== + +Released: 2006-11-24 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andrew Morton +Chuck Ebbert <76306.1226@compuserve.com> +Doug Goldstein +Eduard Bloch +Evan Teran +Pavel Heimlich +Petr Baudis +Randy Dunlap +Ulrich Drepper + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +brk.2 + Evan Teran / mtk + Add text describing behavior of the Linux brk() system call + and point out that the glibc brk() wrapper provides different + behavior. + mtk + Note that sbrk() is implemented as a library function in glibc + that calls the brk() system call. + +futex.2 + mtk + FUTEX_FD is scheduled for removal in June 2007. + +getaddrinfo.3 +getnameinfo.3 + Ulrich Drepper, with edits by mtk + Add text describing Internationalized Domain Name + extensions. + +open.2 + mtk / Eduard Bloch + Fix description of O_LARGEFILE to mention required feature test + macros. + +ptrace.2 + Chuck Ebbert + Since Linux 2.6.18, the PID of the new process is also available + for PTRACE_EVENT_VFORKDONE. + +syslog.3 + Doug Goldstein + Fix header file required for vsyslog() in SYNOPSIS. + +wcwidth.3 + Petr Baudis + Fix CONFORMING TO. + +core.5 + mtk + Linux 2.4.21 added core_pattern (which was already in 2.6). + Noted a few more reasons why a core dump file might not + be produced. + + +==================== Changes in man-pages-2.43 ==================== + +Released: 2006-11-29 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +David Brownell +Eduard Bloch +Egmont Koblinger +Reuben Thomas + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +ioperm.2 + mtk + Clarify discussion of privilege requirements. + Added ENOMEM to ERRORS. + +open.2 + mtk / Eduard Bloch + Clarify description of O_LARGEFILE. + +crypt.3 + Egmont Koblinger + Make description of MD5 output string less ambiguous. + +strerror.3 + Reuben Thomas + Add C99 to CONFORMING TO; see + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=400634 + +rtc.4 + David Brownell + + Update the RTC man page to reflect the new RTC class framework: + + - Generalize ... it's not just for PC/AT style RTCs, and there + may be more than one RTC per system. + + - Not all RTCs expose the same feature set as PC/AT ones; most + of these ioctls will be rejected by some RTCs. + + - Be explicit about when {A,P}IE_{ON,OFF} calls are needed. + + - Describe the parameter to the get/set epoch request; correct + the description of the get/set frequency parameter. + + - Document RTC_WKALM_{RD,SET}, which don't need AIE_{ON,OFF} and + which support longer alarm periods. + + - Hey, not all system clock implementations count timer irqs any + more now that the new RT-derived clock support is merging. + +proc.5 + mtk + s/fseek(3)/lseek(2)/ under /proc/PID/mem entry. + +feature_test_macros.7 + mtk / Eduard Bloch + The LFS spec is now at http://opengroup.org/platform/lfs.html + +raw.7 +udp.7 + Andi Kleen + Describe the correct default for UDP/RAW path MTU discovery. + + +==================== Changes in man-pages-2.44 ==================== + +Released: 2007-04-04 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andre Majorel +Benjamin Gilbert +Carlo Marcelo Arenas Belon +Chuck Ebbert <76306.1226@compuserve.com> +Ivana Varekova +Jakub Jelinek +John Ward +Jorge Peixoto de Morais Neto +Julien Blache +Julien Cristau +Justin Pryzby +Martín Ferrari +Mike Frysinger +Nick Piggin +Nick Pollitt +Nicolas François +Pádraig Brady +Premysl Hruby +Reuben Thomas +Samuel Thibault +Serge E. Hallyn +Thomas Huriaux +Timo Sirainen +Val Henson + +Apologies if I missed anyone! + + +New pages +--------- + +termio.7 + mtk, after a bit of prodding by Reuben Thomas + A brief discussion of the old System V termio interface, + with pointers to pages that will contain the information + that the reader probably wants. + +scripts/find_repeated_words.sh + mtk + Find consecutive duplicate words in a man page, some of + which may be grammar errors. + +Global changes +-------------- + +Various pages + Justin Pryzby / mtk + Add "#define _ATFILE_SOURCE" to SYNOPSIS in following pages: + faccessat.2 + fchmodat.2 + fchownat.2 + fstatat.2 + futimesat.2 + linkat.2 + mkdirat.2 + mknodat.2 + openat.2 + readlinkat.2 + renameat.2 + symlinkat.2 + unlinkat.2 + mkfifoat.3 + +Various pages + mtk + Various references to "getty" were changed to "mingetty", since + that is the manual page more likely to be found on current systems. + +Various pages + mtk, after a suggestion by Reuben Thomas + Updated various header pages to accurately reflect which functions + are and are not part of C89. Also fixed/improved a few other + CONFORMING TO entries. + +Various pages + mtk + s/Unices/Unix systems/ on the 5 pages where it appears. + +Various pages + mtk + Wrapped long source lines in the following files + getsockopt.2 + mknodat.2 + io_setup.2 + select_tut.2 + select.2 + readlinkat.2 + io_cancel.2 + syslog.2 + wcsncat.3 + getipnodebyname.3 + cmsg.3 + wcpncpy.3 + wcsrtombs.3 + wcstok.3 + fgetwc.3 + wmemcmp.3 + wcsspn.3 + div.3 + modf.3 + stdio_ext.3 + ctermid.3 + des_crypt.3 + wcsncmp.3 + wmemchr.3 + wcsstr.3 + wmemcpy.3 + wprintf.3 + wcsnrtombs.3 + termios.3 + erf.3 + ceil.3 + lround.3 + nextafter.3 + wcsncpy.3 + wmemset.3 + getw.3 + console_ioctl.4 + sk98lin.4 + environ.7 + unix.7 + time.7 + +Various pages + mtk + Added a SEE ALSO reference for feature_test_macros(7) to all + pages where a feature test macro appears in the SYNOPSIS. + +Various pages + mtk + Added SEE ALSO entry pointing to time.7 + alarm.2 + nanosleep.2 + ualarm.3 + usleep.3 + +Various pages + Justin Pryzby / mtk + Fixed consecutive duplicate word typos on a number of pages. + +Typographical or grammatical errors have been corrected in several +places. (Special thanks to Nicolas François!) + + +Changes to individual pages +--------------------------- + +access.2 + mtk + Since 2.6.20, access() honors the MS_NOEXEC mount flag. + Jorge Peixoto de Morais Neto / mtk + Improve ENOENT description. + +clone.2 + mtk + Added some detail to the prototype. + Added some notes on IA-64's clone2(). + +epoll_ctl.2 + mtk + Add text to note that EPOLLRDHUP appeared in kernel 2.6.17. + +faccessat.2 + Justin Pryzby + Various fixes as per + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411177 + * s/effective/real/ in description text. + * added to synopsis. + * various other changes. + +getrlimit.2 + mtk / Fedora downstream patches; thanks to Ivana Varekova + Added a few words to note that RLIMIT_NPROC is really a limit on + threads. + +io_cancel.2 +io_destroy.2 +io_getevents.2 +io_setup.2 +io_submit.2 + Fedora downstream patches; thanks to Ivana Varekova + s%linux/aio.h%libaio.h% in SYNOPSIS. + Changed return type from "long" to "int". + +mbind.2 + Samuel Thibault / mtk + Fix EINVAL description. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411777 + +mincore.2 + Nick Piggin + Kernel 2.6.21 fixes several earlier bugs in mincore(). + Nick Pollitt + Remove words "of a file" -- mincore() is describing + memory residence information, not properties of a file. + mtk + Rewrote various parts to make the page clearer. + +mmap.2 + mtk + Rewrote and reorganized various parts to be clearer. + Taken from Fedora downstream patches; thanks to Ivana Varekova + Removed text stating that mmap() never returns 0; that's + not true. + +mount.2 + mtk / Val Henson + Document MS_RELATIME, new in Linux 2.6.20. + +open.2 + Andre Majorel / mtk + On Linux, the error returned when opening a large file on a + 32-bit system is actually EFBIG, not EOVERFLOW. + +posix_fadvise.2 + Pádraig Brady + Fix RETURN VALUE description: returns error number of failure. + +rename.2 + mtk / Timo Sirainen + Various improvements to DESCRIPTION. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=416012 + +semop.2 + mtk + If sops contains multiple operations, then these are performed + in array order. All Unix systems that I know of do this, + and some Linux applications depend on this behavior. SUSv3 + made no explicit statement here, but SUSv4 will explicitly + require this behavior. + Small rewording of explanation of "atomically". + +signal.2 + Nicolas François + Fix incorrect argument name in DESCRIPTION. + mtk + Small wording improvement. + +socket.2 + Nicolas François + Add reference to ipv6.7 page. + +socketcall.2 + Nicolas François + Fix .TH line. + +splice.2 + Benjamin Gilbert + Fix inconsistent argument names in SYNOPSIS and DESCRIPTION. + +statvfs.2 + mtk + Small wording clarification. + +symlink.2 + mtk / Nicolas François + Removed cryptic text under CONFORMING to referring to + "open(2) and NFS". There is no relevant text in open.2 as + far as I (mtk) can see. + +time.2 + mtk / Reuben Thomas + Remove sentence "gettimeofday() obsoleting time() on 4.3BSD". + This information is old, and probably no longer relevant. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=403888 + +write.2 + mtk, after an idea from a downstream Fedora patch. + Clarified discussion of /count == 0/ case. + +ptrace.2 + Chuck Ebbert + When the parent receives an event with PTRACE_EVENT_* set, + the child is not in the normal signal delivery path. This + means the parent cannot do ptrace(PTRACE_CONT) with a signal + or ptrace(PTRACE_KILL). kill() with a SIGKILL signal can be + used instead to kill the child process after receiving one + of these messages. + +sched_setaffinity.2 + mtk + Fix glibc version number in description of 'cpusetsize' argument. + +vfork.2 + mtk + Stripped some excess/outdated text from the BUGS section. + +basename.3 + mtk / Jorge Peixoto de Morais Neto + Add text to clarify that the pointer returned by these + functions may be into some part of 'path'. + +dlopen.3 + Taken from Fedora downstream patches; thanks to Ivana Varekova + + Carlo Marcelo Arenas Belon + Add "#include " to example program. + +fclose.3 + mtk + Complete rewrite. The existing page was hard to read, + and the RETURN VALUE description seems to be wrong. + +getopt.3 + mtk + Added getopt() example program. + mtk + Add a few words to clarify the operation of the GNU-specific + double-colon feature, which allows options to have optional + arguments. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=352139 + +glob.3 + Nicolas François + Fix PROTOTYPE. + +inet_network.3 + mtk, after an idea from a downstream Fedora patch. + Clarified description of inet_network(). + +log.3 + Nicolas François + Fix .TH line. + +log10.3 + Nicolas François + Fix .TH line. + +malloc.3 + Nicolas François + Small rewording to mention calloc(). + +posix_openpt.3 + Martín Ferrari + Fix return type in SYNOPSIS; as per + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=400971 + Needs _XOPEN_SOURCE == 600; as per + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=400975 + Julien BLACHE + s/ptsname/posix_openpt/ in RETURN VALUE + +re_comp.3 + Taken from Fedora downstream patches; thanks to Ivana Varekova + Add "#define _REGEX_RE_COMP" to SYNOPSIS. + +regex.3 + Nicolas François + Fix .TH line. + +termios.3 + mtk + Added .SS headers to give some structure to this page; and a small + amount of reordering. + mtk + Added a section on canonical and non-canonical mode. + mtk + Enhanced the discussion of "raw" mode for cfmakeraw(). + mtk + Document CMSPAR. + mtk + Make description of PARODD a little clearer. + Reuben Thomas + Add SEE ALSO link to tty_ioctl.4 + mtk + Add SEE ALSO link to console_ioctl.4 + +ualarm.3 + mtk + Removed BSD prototype from synopsis. + Various rewordings. + +usleep.3 + mtk + Removed BSD prototype from synopsis. + Various rewordings. + +termcap.5 + Taken from Fedora downstream patches; thanks to Ivana Varekova + s/curses/ncurses/ under SEE ALSO + +bootparam.7 + Taken from Fedora downstream patches; thanks to Ivana Varekova + Documented "mem=nopentium". + +feature_test_macros.7 + mtk + The default treatment of _POSIX_C_SOURCE changed in glibc 2.4. + mtk, after a suggestion by Justin Pryzby + Added some text warning that the "__" macros that + defines internally should never be + directly defined by programs. + mtk, based on notes by Jakub Jelinek + Document _FORTIFY_SOURCE + (See http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html ) + mtk + Document _REENTRANT and _THREAD_SAFE. + +mdoc.7 + mtk / Nicolas François + Remove CONFIGURATION section, since this does not seem to be + true for Linux. + +svipc.7 + Nicolas François + Fix data types in associated data structures; + remove nonexistent semzcnt and semncnt fields. + +time.7 + mtk + Since kernel 2.6.20, the software clock can also be 300 HZ. + + +==================== Changes in man-pages-2.45 ==================== + +Released: 2007-04-05 + +Global changes +-------------- + +This release consists mainly of formatting fixes (to a large +number of pages) to achieve greater consistency across pages. +With the exception of the few individual changes noted below, +no changes were made to content. + +Changes to individual pages +--------------------------- + +io_destroy.2 +io_getevents.2 +io_setup.2 +io_cancel.2 +io_submit.2 + mtk + Clarified RETURN VALUE text + +bindresvport.3 + mtk + Rewrote prototype using modern C syntax. + + +==================== Changes in man-pages-2.46 ==================== + +Released: 2007-04-06 + +Global changes +-------------- + +This release consists mainly of formatting fixes (to a large +number of pages) to achieve greater consistency across pages: + +* Most instances of two or more consecutive blank lines in man + page output were shrunk to a single line. +* A number of example programs were reformatted + to more closely match K&R style. +* In various places (mainly code examples), the use of tabs was + replaced by spaces + +With the exception of the few individual changes noted below, +no changes were made to content. + + +Changes to individual pages +--------------------------- + +bdflush.2 + mtk + Add header file to SYNOPSIS. + +sched_rr_get_interval.2 + mtk + Moved timespec definition from SYNOPSIS into description. + +select_tut.2 + mtk + Make SYNOPSIS match select.2. + + +==================== Changes in man-pages-2.47 ==================== + +Released: 2007-05-04 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +John Heffner + +Apologies if I missed anyone! + + +Global changes +-------------- + +This release consists mainly of changes to source file layout +(wrapped long lines; stripped trailing white space; started new +sentences on new lines). + +There is very little change to output formatting or content (see the +notes below). + + +Changes to individual pages +--------------------------- + +sched_rr_get_interval.2 + mtk + Remove crufty statement that this system call is not implemented. + The nice interval can be used to control the size of + the round-robin quantum. + Corrected .TH line. + +ip.7 + John Heffner / mtk + Document IP_PMTUDISC_PROBE, which will be in 2.6.22. + + +==================== Changes in man-pages-2.48 ==================== + +Released: 2007-05-04 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Colin Watson +Justin Pryzby + +Apologies if I missed anyone! + + +Global changes +-------------- + +This release consists mainly of changes to source file layout +(wrapped long lines; stripped trailing white space; started new +sentences on new lines). + +There is very little change to output formatting or content (see the +notes below). + +Various pages + mtk + In various places where it occurred, + s/nonnegative/non-negative/ + +Various pages + mtk + s/wide character/wide-character/ when used attributively. + + +Changes to individual pages +--------------------------- + +man.7 + Justin Pryzby / Colin Watson / mtk + .SH doesn't require quotes. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411303 + + +==================== Changes in man-pages-2.49 ==================== + +Released: 2007-05-20 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Akihiro MOTOKI +Bruno Haible +Justin Pryzby + +Apologies if I missed anyone! + + +New pages +--------- + +bsd_signal.3 + mtk + Documentation of bsd_signal(). + +euidaccess.3 + mtk + Manual page for euidaccess() and eaccess(). + +getsubopt.3 + mtk / Justin Pryzby + Documentation of getsubopt(). + +sysv_signal.3 + mtk + Documentation of sysv_signal(). + + +New links +--------- + +epoll_pwait.2 + mtk + New link to epoll_wait.2. + +eaccess.3 + mtk + New link to new euidaccess.3, + +sem_timedwait.3 + mtk + New link to sem_wait.3. + +sem_trywait.3 + mtk + New link to sem_wait.3. + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +access.3 + mtk + Added SEE ALSO ref to new euidaccess.3 page. + +epoll_wait.2 + mtk + Added description of epoll_pwait(), new in kernel 2.6.19. + +execve.2 + mtk + Add text noting that Linux allows 'argv' and 'envp' to be + NULL, but warning that this is non-standard and non-portable, + and should be avoided in portable programs. + Bug filed (http://bugzilla.kernel.org/show_bug.cgi?id=8408) + to get this changed, but maybe that won't be done because it + is an ABI change. + mtk + Added an example program. + mtk + Expanded the discussion of interpreter scripts and the + 'optional-arg' argument of an interpreter script. + For further info, see + http://homepages.cwi.nl/~aeb/std/hashexclam-1.html + http://www.in-ulm.de/~mascheck/various/shebang/ + mtk + Added text noting that FD_CLOEXEC causes record locks to be + released. + mtk + Mention effect of MS_NOSUID mount(2) flag for set-user-ID + programs. + mtk + Expanded description of handling of file descriptors during + execve(), adding text to note that descriptors 0, 1, and 2 + may be treated specially. + +faccessat.3 + mtk + Added SEE ALSO ref to new euidaccess.3 page. + +mmap.2 + mtk + Place MAP_* flags list in alphabetical order. + +readv.2 + mtk + A fairly substantial rewrite, which among other things + fixes the problem reported by Kyle Sluder in + http://bugzilla.kernel.org/show_bug.cgi?id=8399 + And added some example code. + +sigaction.2 + mtk + Added text referring to the discussion of async-signal-safe + functions in signal(7). + A few other minor formatting and wording changes. + +signal.2 + mtk + Moved the discussion of async-signal-safe functions to signal(7). + Added text referring to the discussion of async-signal-safe + functions in signal(7). + Added SEE ALSO entries referring to new bsd_signal.3 and + sysv_signal.3 pages. + +copysign.3 + Bruno Haible + Clarify discussion of negative zero. + +getopt.3 + mtk + Add SEE ALSO ref to new getsubopt.3. + +iconv_open.3 + Bruno Haible + Describe the glibc/libiconv //TRANSLIT and //IGNORE extensions + for 'tocode'. + +iswblank.3 + Bruno Haible + Update CONFORMING TO; iswblank() is in POSIX.1-2001. + +inotify.7 + mtk + Definitions for IN_DONT_FOLLOW, IN_MASK_ADD, and IN_ONLYDIR + were added to glibc in version 2.5. + +signal.7 + mtk + Incorporated (and slightly modified) the text on + async-signal-safe functions that was formerly in signal(2). + Added SEE ALSO entries referring to new bsd_signal.3 and + sysv_signal.3 pages. + + +==================== Changes in man-pages-2.50 ==================== + +Released: 2007-05-21 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andreas Halter +Laird Shaw +Mike Frysinger + +Apologies if I missed anyone! + +Removed pages (!) +----------------- + +Most Section 1 man pages are removed + mtk (with help from Mike Frysinger, Laird Shaw, Andreas Halter) + Once upon time Andries added a number of Section 1 manual pages + to man-pages. However, since that time, those pages have not + seen much maintenance, and are not in fact distributed in most + distributions. Instead most distributions supply the + coreutils versions of these pages, which are currently + maintained. In addition, man-pages provides the 1p pages, + which document the portable subset of functionality of these + commands. Since the man1 pages are mostly unneeded, and + out of date, I'm removing them. The following pages disappear: + + chgrp.1 + chmod.1 + chown.1 + cp.1 + dd.1 + df.1 + diff.1 + dir.1 + dircolors.1 + du.1 + install.1 + ln.1 + ls.1 + mkdir.1 + mkfifo.1 + mknod.1 + mv.1 + rm.1 + rmdir.1 + touch.1 + vdir.1 + + The following Section 1 pages will be kept: + + intro.1 + ldd.1 + time.1 + + +==================== Changes in man-pages-2.51 ==================== + +Released: 2007-05-28 + +Global changes +-------------- + +Various pages + mtk + (Hopefully) all cross references outside a page now include a + section number. This should permit better resulting output + from a man2html-type conversion. + +Various pages + mtk + Convert function formatting of the form "\fBname\fP()" to + ".BR name ()". + + +Changes to individual pages +--------------------------- + +futimesat.2 + mtk + s/futimes/futimesat/ in .SH NAME line. + +msgop.2 + mtk + Put "msgrcv" and "msgsnd" in .SH NAME line. + +mount.2 + mtk + Add "umount2" to .SH NAME line. + +wait.2 + mtk + Add "waitid" to .SH NAME line. + +getopt.3 + mtk + Add "getopt_long" and "getopt_long_only" in .SH NAME line. + +sem_wait.3 + mtk + Add "sem_timedwait" and "sem_trywait" to .SH NAME line. + +stdarg.3 + mtk + Add "va_start", "va_arg", "va_end", "va_copy" to .SH NAME line. + + +==================== Changes in man-pages-2.52 ==================== + +Released: 2007-05-29 + + "A foolish consistency is the hobgoblin of little minds, adored by + little statesmen and philosophers and divines" + + Ralph Waldo Emerson (1803-1882) + + "But damn it, these man pages are a mess!" + + +Global changes +-------------- + +Most of the changes below are about bringing greater consistency +to manual pages, including reducing the wide range of .SH +Section headings. + +Typographical or grammatical errors have been corrected in several +places. + +Various pages + mtk + Make 'manual' component of .TH line into the string + "Linux Programmer's Manual". + Reason: consistency. + +Various pages + mtk + Changed date in .TH line into form YYYY-DD-MM. + Reason: consistency. + +Various pages + mtk + Some .SH header lines were made into .SS lines. (One of the aims + here is to reduce the number of non-standard .SH lines.) + +Various pages + mtk + Change title .SH sections named "NOTE" to "NOTES", in some cases + also changing the location of the section within the page. + Reason: consistency. + +Various pages + mtk + Commented out .SH AUTHOR sections; the right place for + documentation authorship sections is usually comments at the + top of the page source. + +Various pages + mtk + Changed .SH HISTORY to .SH VERSIONS. + Reason: in many cases, HISTORY was being used to describe + Linux/glibc version information, as was already done for + VERSIONS sections in other pages. + +Various pages + mtk + Removed HISTORY section, or moved it as a subsection or paragraphs + under another section e.g., NOTES. + Reason: there are too many arbitrary section (.SH) names, and + a HISTORY section never was consistently used across Linux + manual pages. + +Various pages + mtk + Moved SEE ALSO section to be last section on the page + Reason: consistency -- and this is where SEE ALSO should be! + +Various pages + mtk + Relocated GLIBC NOTES as subsection under NOTES + Reason: reduce number of arbitrary section (.SH) names. + +Various pages + mtk + Relocated LINUX NOTES as subsection under NOTES + Reason: reduce number of arbitrary section (.SH) names. + +Various pages + mtk + Renamed some "AVAILABILITY" sections to "VERSIONS". + Reason: consistency. + +Various pages + mtk + Renamed some "DIAGNOSTICS" sections to "RETURN VALUE". + Reason: consistency. + +getopt.3 +tzselect.8 + mtk + s/\.SH ENVIRONMENT VARIABLES/.SH ENVIRONMENT/ + Reason: consistency. + +intro.2 +select.2 +sysctl.2 +bsearch.3 +dlopen.3 +envz_add.3 +fmtmsg.3 +getgrent_r.3 +getgrouplist.3 +getpwent_r.3 +getutent.3 +hsearch.3 +rtime.3 +strptime.3 +tsearch.3 +vcs.4 +wordexp.3 + mtk + s/return 0/exit(EXIT_FAILURE)/ in main() of function example + program. + Reason: consistency. + +mprotect.2 +select_tut.2 +dlopen.3 +getgrent_r.3 +getopt.3 +getpwent_r.3 +hsearch.3 +select_tut.2 +tsearch.3 + mtk + Use symbolic constants (EXIT_SUCCESS, EXIT_FAILURE) in calls + to exit(). + Reason: consistency. + +access.2 +chown.2 +lseek.2 +open.2 +read.2 +utmp.5 + mtk + Renamed RESTRICTIONS section to NOTES, or moved text in a + RESTRICTIONS section under existing NOTES section. + Reason: consistency, and reduce number of arbitrary section (.SH) + names. + + +Changes to individual pages +--------------------------- + +capget.2 + mtk + s/\.SH FURTHER INFORMATION/.SH NOTES/ + +dup.2 + mtk + s/\.SH WARNING/.SH NOTES/ + +kill.2 + mtk + Renamed LINUX HISTORY section to LINUX NOTES, and relocated + within page. + +select_tut.2 + mtk + Relocated example program and made its .SH title "EXAMPLE". + +sigaltstack.2 + mtk + Move code example into its own EXAMPLE section. + +sigreturn.2 + mtk + s/\.SH WARNING/.SH NOTES/ + +setuid.2 + mtk + s/\.SH "LINUX-SPECIFIC REMARKS"/.SH LINUX NOTES/ + +shmget.2 + mtk + Remove section about effect of fork()/exec()/exit(); shmop.2 + contains the same text, and it only needs to be said once. + +shmop.2 + mtk + Minor rewording under DESCRIPTION. + +daemon.3 + mtk + Minor wording and formatting changes. + +encrypt.3 + mtk + Removed statement that glibc unconditionally exposes declarations + of encrypt() and setkey(), since portable applications must + use and define _XOPEN_SOURCE to obtain the declarations + of setkey() and encrypt(). Adjusted example program accordingly. + +mkstemp.3 + mtk + Slight rewording. + +LDP.7 + mtk + Minor wording and formatting changes. + +man.7 + mtk + Substantial rewrite, revising and extending the discussion + about desired conventions for writing pages. + There will be further updates to this page in the next few + man-pages releases. + + +==================== Changes in man-pages-2.53 ==================== + +Released: 2007-05-30 + + "A foolish consistency is the hobgoblin of little minds, adored by + little statesmen and philosophers and divines" + + Ralph Waldo Emerson (1803-1882) + + "But damn it, these man pages are a mess!" + + +Global changes +-------------- + +Many many pages + mtk + Reordered sections to be more consistent, in some cases renaming + sections or shifting paragraphs between sections. + +man7/* + mtk + In various pages in this section, .SH headings were + converted to .SS. + + +==================== Changes in man-pages-2.54 ==================== + +Released: 2007-06-07 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Emmanuel Mogenet +Michael Berg + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages + mtk + Where there is an instruction in the SYNOPSIS about linking + or compiling with a certain option, the option is now + marked up in italics (e.g., "\fI-lm\fP"). + +Various pages + mtk + Added page numbers to page cross references. + +A few pages + mtk + s/manpage/man page/, for consistency. + +Typographical or grammatical errors have been corrected in several +places. + + +New pages +--------- + +man-pages.7 + mtk + A description of the conventions that should be followed + when writing pages for the man-pages package. + +Removed pages +------------- + +man1/README + mtk + Already deleted most of the man1 pages previously, so + this doesn't need to stay. + +LDP.7 + mtk + Removed this page since it is out of date, and the proper place + to go for up-to-date information is http://www.tldp.org/ + +ksoftirq.9 + mtk + Reason: this was the only Section 9 page, and it is old + (Linux 2.4). The man9 section never took off as an idea, and + I see little point in keeping a Section 9 with just a single + old page. + + +Changes to individual pages +--------------------------- + +HOWTOHELP + mtk + Moved some material out of here into new man-pages.7. + +alloc_hugepages.2 + mtk + Minor rewrites, eliminating some duplication, and removing + some outdated text. + +epoll_pwait.2 + Michael Berg + Fix broken link path; + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=425570 + +fcntl.2 + mtk + Remove misleading text about setting O_ASYNC when calling + open(); one must use fcntl() F_SETFL for this task. + +fdatasync.2 + mtk + Converted outdated BUGS note about fdatasync() being + equivalent to fsync() on Linux 2.2 into a NOTES note + about this historical behavior. + +futex.2 + mtk + Small rewording to fix "fails with the error EWOULDBLOCK" + rather than "returns EWOULDBLOCK". + See Red Hat bug 172828. + +mprotect.2 + mtk, after an observation by Emmanuel Mogenet + A much improved example program. + mtk + Significant rewrites and additions to description. + +mremap.2 + mtk + Remove text about the nonexistent BSD mremap() -- too + much information, in my opinion. + +sched_yield.2 + mtk + Added ERRORS section. + +set_mempolicy.2 + mtk + Moved text for "Versions and Library Support". + +set_tid_address.2 + mtk + Small rewording in RETURN VALUE section. + +sigaction.2 + mtk + Add EXAMPLE section with a pointer to example in mprotect.2. + +sync_file_range.2 + mtk + Fix return type in SYNOPSIS. Add RETURN VALUE section. + +atexit.3 + mtk + Small rearrangement of text under NOTES. + +bindresvport.3 + mtk + Rewrite and substantial additional text. + +exec.3 + mtk + Minor clarifications for text on execlp() and execvp(). Removed + FILES section, since it provides no useful additional info. + +fenv.3 + mtk + Moved link instructions from NOTES to SYNOPSIS. + Added feenableexcept, fedisableexcept, fegetexcept + to .SH NAME list. + +fputwc.3 + mtk + Added 'putwc' to .SH NAME list. + +gethostbyname.3 + mtk + s/int/socklen_t/ for type of gethostbyaddr() 'len' argument, + and add a few more words in NOTES about the type used here. + +login.3 + mtk + Removed remark from NOTES about linking with -lutil; add + text on that point to SYNOPSIS. + +openpty.3 + mtk + Removed redundant remark from NOTES about linking with -lutil + since there is text on that point under SYNOPSIS. + +sysconf.3 + mtk + Added SEE ALSO referring to getconf(1). + +unlocked_stdio.3 + mtk + Revised .SH NAME section. + +ascii.7 + mtk + Minor rearrangement of order of text. + +capabilities.7 + mtk + s/exec()/execve(2)/ in various places. + +complex.7 + mtk + Changed "atan(1)" to "atan(1.0)" to prevent some versions of + man2html(1) from mistaking that string as a page cross reference. + +rtnetlink.7 + mtk + Small restructuring to avoid 'cannot adjust line' from man(1). + +ldconfig.8 + mtk + Removed now very out-of-date sentence about need to link shared + libraries with -lc. + +man.7 + mtk + Various text was moved out of this page into the new man-pages.7. + +mdoc.7 + mtk + Added SEE ALSO referring to new man-pages.7. + +mdoc.samples.7 + mtk + A few changes, hopefully done right, to eliminate some + errors to stderr when rendering with man(1). + +rtnetlink.7 + mtk + Shorten a line in table so it fits in 80 columns. + Minor rewording under BUGS. + +tzselect.8 + mtk + Moved EXIT STATUS section. + + +==================== Changes in man-pages-2.55 ==================== + +Released: 2007-06-10 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alexander Taboriskiy +Joey Hess +John Reiser +Julien Cristau +Justin Pryzby +Martin (Joey) Schulze +Mike Frysinger +Serge van den Boom +Ulrich Drepper +Xose Vazquez Perez + +Apologies if I missed anyone! + + +Global changes +-------------- + +clone.2 +getdents.2 +gettid.2 +ioprio_set.2 +llseek.2 +mmap2.2 +modify_ldt.2 +mq_getsetattr.2 +pivot_root.2 +quotactl.2 +readdir.2 +sysctl.2 +syslog.2 +tkill.2 + mtk, after a note by Mike Frysinger + Updated to reflect the fact that the _syscallN() macros + have gone away, + +Several pages + mtk + Change reference to path_resolution.2 to path_resolution.7. + +Typographical or grammatical errors have been corrected in several +places. + + +Moved pages +----------- + +path_resolution.2 has been moved to section 7, thus path_resolution.7 + mtk + Reason: this is an overview page, not one describing as + a specific system call. + + +Changes to individual pages +--------------------------- + +MAINTAINING + mtk, after a note from Xose Vazquez Perez + Added pointer to Red Hat man-pages bugzilla. + mtk + Added a release philosophy note on separating out big + formatting changes into their own release that contains minimal + content changes. + +accept.2 + mtk + Add new EXAMPLE section with pointer to example in bind.2. + +arch_prctl.2 + mtk + Added RETURN VALUE section. + +bind.2 + mtk + Expand example program, and move it to new EXAMPLE section. + Added text pointing to example in getaddrinfo.3. + +cacheflush.2 + mtk + Convert NOTES section to CONFORMING TO and note that + this call is Linux-specific. + Other minor rewordings. + +connect.2 + mtk + Added new EXAMPLE section pointing to example in getaddrinfo.3. + +create_module.2 + mtk + Add ENOSYS error. + +fcntl.2 +flock.2 + mtk + Small rewrite of SEE ALSO text pointing to Documentation/* in + kernel source. + +get_kernel_syms.2 + mtk + Added ERRORS heading + Add ENOSYS error. + +getdtablesize.2 + mtk + Added an ERRORS section. + +getsid.2 + mtk + Added a RETURN VALUE section. + +getpid.2 + mtk + Added an ERRORS section (stating that the calls are + always successful). + +ioctl_list.2 + mtk + Add SEE ALSO reference to ioctl.2. + +listen.2 + mtk + Add new EXAMPLE section with pointer to example in bind.2. + +query_module.2 + Martin (Joey) Schulze + Add ENOSYS error. + +recv.2 + mtk + Added new EXAMPLE section pointing to example in getaddrinfo.3. + +sched_get_priority_max.2 +sched_rr_get_interval.2 +sched_setscheduler.2 +sched_yield.2 + mtk + Modified .TH line + +send.2 + mtk + Added new EXAMPLE section pointing to example in getaddrinfo.3. + +set_tid_address.2 + mtk + Added an ERRORS section (stating that the call is + always successful). + +signal.2 + mtk, after a note from Alexander Taboriskiy + Strengthen warning against the use of signal(). + Added siginterrupt(3) to SEE ALSO list. + mtk + Rewrote various parts; added an ERRORS section. + +socket.2 + mtk + Added new EXAMPLE section pointing to example in getaddrinfo.3. + +stat.2 + mtk + Added EXAMPLE program. + +syscall.2 + mtk + Converted to -man format; some rewrites; added an EXAMPLE. + +sysctl.2 + mtk + Improved the example program. + +getnameinfo.3 + mtk + Add text pointing to example in getaddrinfo.3. + +getaddrinfo.3 + mtk + Add example programs. + Add getnameinfo() to SEE ALSO list. + +memmove.3 + mtk / Serge van den Boom + Clarify discussion of what happens if 'src' and 'dest' overlap. + +regex.3 + Justin Pryzby + Add grep(1) to SEE ALSO list. + +sigpause.3 + mtk after a note from Ulrich Drepper + Clarify discussion of feature test macros that are needed to + expose System V and BSD versions of this function in glibc. + +undocumented.3 + mtk + Removed some functions that have been documented. + +wprintf.2 + Martin (Joey) Schulze + Remove wscanf.3 from SEE ALSO list, since that page does not exist. + +utmp.5 + Joey Hess + Removed outdated note on xdm. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=418009 + Martin (Joey) Schulze + Removed outdated note about Debian and libc5. + +bootparam.7 + Martin (Joey) Schulze + Fix order of commands listed under 'init='. + +hier.7 + Joey Hess + Add /media, remove /dos. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=418234 + +inotify.7 + mtk + Added text describing what happens when the buffer given to + read(2) is too small to return information about the next event, + and noting the behavior change in 2.6.21. + +man-pages.7 + mtk + Added text to note that ERRORS list should be in alphabetical order. + +mdoc.7 +mdoc.samples.7 + mtk + Added SEE ALSO reference to groff_mdoc(7). + +unix.7 + mtk + Added EXAMPLE section with pointer to bind.2 EXAMPLE. + +ld.so.8 + mtk + Simplify text describing --inhibit-rpath. + mtk, after a note by John Reiser + Describe use of $ORIGIN in rpath. + + +==================== Changes in man-pages-2.56 ==================== + +Released: 2007-06-11 + +Global changes +-------------- + +Many pages + mtk + Removed version numbers in .TH lines. + Reason: these were only arbitrarily updated, and so impart no + useful information. Version information goes into a + VERSIONS section nowadays, and the date in the .TH line should + be updated to reflect the date of the last (significant) + change to the page. + +Typographical or grammatical errors have been corrected in several +places. + + +==================== Changes in man-pages-2.57 ==================== + +Released: 2007-06-17 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Samuel Thibault + +Apologies if I missed anyone! + + +Global changes +-------------- + +Many pages + mtk + Fix section numbers in page cross references. + + +Changes to individual pages +--------------------------- + +access.2 + mtk + Minor wording fixes. + Small clarification of description of 'mode'. + +bind.2 + mtk + Small reworking of EXAMPLE program. + +exit_group.2 + mtk + Minor wording fixes. + +exit.3 + mtk + Added more detail on exit handlers. + Minor wording fixes. + +ioctl.2 + mtk + Remove SEE ALSO reference to nonexistent mt.4. + +modify_ldt.2 + Samuel Thibault / mtk + In Linux 2.6, the 'modify_ldt_ldt_s' structure was renamed + 'user_desc'. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=378668 + mtk + Include definition of 'user_desc' structure. + Minor rewordings. + +mprotect.2 + mtk + Small reworking of EXAMPLE program. + +sigaction.2 + mtk + Removed reference to nonexistent sigsend(2). + +a64l.3 + mtk + Remove SEE ALSO reference to nonexistent itoa.3. + +dysize.3 + mtk + Removed SEE ALSO reference to nonexistent time.3. + +encrypt.3 + mtk + Removed SEE ALSO reference to nonexistent fcrypt.3. + +fmemopen.3 + mtk + Small reworking of EXAMPLE program. + +fpurge.3 + mtk + Remove SEE ALSO reference to nonexistent fclean.3. + +getutent.3 + mtk + s/ttyname(0)/ttyname(STDIN_FILENO)/ in program example. + +vcs.4 + mtk + s/exit(1)/exit(EXIT_FAILURE)/ + +environ.7 + mtk + Correct some section numbers in page cross references. + +man-pages.7 + mtk + Modify requirements for example programs a little. + +uri.7 + mtk + Wrapped long source lines. + + +==================== Changes in man-pages-2.58 ==================== + +Released: 2007-06-24 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Marc Boyer +Mike Frysinger + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages, as detailed below + mtk + Added or updated VERSIONS sections. + +killpg.2 +setuid.2 +faccessat.2 +fork.2 +setfsuid.2 +kill.2 +getsid.2 +wait.2 +execve.2 +getpid.2 +setgid.2 +seteuid.2 +setresuid.2 +setfsgid.2 +access.2 +initgroups.3 +euidaccess.3 +tcgetpgrp.3 +path_resolution.7 +capabilities.7 +unix.7 + mtk + Add SEE ALSO link to new credentials.7. + + +New pages +--------- + +credentials.7 + mtk + An overview of Linux process identifiers (PIDs, PPIDs, + PGIDS, SIDs, UIDs, GIDs). + + +Changes to individual pages +--------------------------- + +bind.2 + mtk + Added some comments to example program. + +getxattr.2 + mtk + VERSIONS: In kernel since 2.4; glibc support since 2.3. + +listen.2 + mtk + Updated discussion of somaxconn limit. + +listxattr.2 + mtk + VERSIONS: In kernel since 2.4; glibc support since 2.3. + +posix_fadvise.2 + mtk + VERSIONS: Glibc support has been provided since version 2.2. + +readahead.2 + mtk + Added VERSIONS section. + +remap_file_pages.2 + mtk + Updated VERSIONS section with text on glibc support. + +removexattr.2 + mtk + VERSIONS: In kernel since 2.4; glibc support since 2.3. + +semop.2 + mtk + Added VERSIONS section with info on semtimedop(). + +setxattr.2 + mtk + VERSIONS: In kernel since 2.4; glibc support since 2.3. + +dl_iterate_phdr.3 + mtk + VERSIONS: Supported since glibc 2.2.4. + +getloadavg.3 + mtk + Added VERSIONS section. + +posix_openpt.3 + mtk + VERSIONS: Supported since glibc 2.2.1. + +printf.3 + mtk after a suggestion by Mike Frysinger + Add text to the introductory part of DESCRIPTION, about the + 'size' argument of snprintf() and vsnprintf(). + +shm_open.3 + mtk + Added VERSIONS section; rewrote info about linking with -lrt. + +strcat.3 + Marc Boyer + Improve the discussion of strncat(). + +strcpy.3 + Marc Boyer + Improve the discussion of strncpy(). + +proc.5 + mtk + Added discussion of /proc/sys/net/core/somaxconn. + + +==================== Changes in man-pages-2.59 ==================== + +Released: 2007-06-25 + +Global changes +-------------- + +Manual pages are now standardized on American spelling. See +http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences +for more information on the differences. Formerly, different pages (and +sometimes even a single page!) employed American and British spelling +conventions; best to standardize on one spelling, and American English +is the standard in Computer Science. + +Changes to individual pages +--------------------------- + +man-pages.7 + mtk + Note that man-pages has now standardized on American spelling + conventions. + +execve.2 +getxattr.2 +listxattr.2 +removexattr.2 +setxattr.2 +signal.2 +syscall.2 +aio_cancel.3 +bindresvport.3 +stdarg.3 +charmap.5 +bootparam.7 +ipv6.7 +man.7 +path_resolution.7 +uri.7 +nscd.8 + mtk + Corrected minor spelling/wording mistakes (i.e., changes + independent of fixes for American spelling). + + +==================== Changes in man-pages-2.60 ==================== + +Released: 2007-06-25 + + +Global changes +-------------- + +Various pages + mtk + Wrapped lines in some files. + +Various pages + mtk + Change "e.g. " to "e.g., ", or in some cases, "for example, ". + +Various pages + mtk + Change "i.e. " to i.e., ", or in some cases, "that is, ". + +Various pages + mtk + Removed AUTHORS section. + +Typographical or grammatical errors have been corrected in several +places. + + +Changes to individual pages +--------------------------- + +vfork.2 + mtk + s/w.r.t/with respect to/ + +man-pages.7 + mtk + Strengthened warning against use of AUTHORS section. + + +==================== Changes in man-pages-2.61 ==================== + +Released: 2007-07-01 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Benno Schulenberg +Florian Ernst +Ivana Varekova +Jeff Schroeder +Joey (Martin) Schulze +Justin Pryzby +Loïc Minier +Michael Gehring +Serge van den Boom +Stefan Puiu +Stepan Kasal + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages + mtk + substitute `\\0' by '\\0'. + +Various pages + mtk + s/`/'/ when the thing being quoted is a character. + +accept.2 +bind.2 +connect.2 +getsockopt.2 +listen.2 +socket.2 +socketpair.2 + mtk after a note by Martin (Joey) Schulze + Add NOTES paragraph noting that isn't required by + POSIX.1-2001 or Linux, but was required on some implementations. + +accept.2 +getsockname.2 +recv.2 +vm86.2 +send.2 +getgrouplist.3 +memmem.3 +nsswitch.conf.5 +putenv.3 +wprintf.3 + mtk + Replace form `...' with \fI...\fP where the enclosed string + is a pathname, type name, or argument name. + +A few files + mtk + s/process' /process's/ + +gets.3 +qsort.3 +getaddrinfo.3 +rpc.3 +ungetwc.3 +wcsnrtombs.3 +capabilities.7 + mtk + Add section number to page cross references. + +time.1 +bind.2 +pivot_root.2 +sysctl.2 + mtk + Reordered .SH sections. + +full.4 +mouse.4 +random.4 +sd.4 + mtk + Made CONFIG/CONFIGURING heading ==> CONFIGURATION + +time.1 +console_codes.4 +random.4 +sk98lin.4 +charmap.5 +ftpusers.5 +bootparam.7 +charsets.7 +glob.7 +mq_overview.7 +unicode.7 +uri.7 +utf-8.7 + mtk + Reformatted headings + + +New pages +--------- + +backtrace.3 + mtk, with input from Justin Pryzby and Stefan Puiu + Documents backtrace(), backtrace_symbols(), and + backtrace_symbols_fd(). + + +New links +--------- + +backtrace_symbols.3 +backtrace_symbols_fd.3 + mtk + Links to backtrace.3. + +__clone.2 + Stepan Kasal + Link to clone.2. + + +Changes to individual pages +--------------------------- + +Makefile + Serge van den Boom + Fix setting of 'prefix' macro. + +eval.1p + Benno Schulenberg + Fix bad text (concatenated line). + +chdir.2 + mtk + Fixed description of EACCES error. + Added sentence defining "current working directory". + Other minor wording changes. + +cfree.3 + mtk + Added SEE ALSO section. + +clone.2 + mtk + s/clone2/__clone2/. + +fdatasync.2 + mtk + Minor wording changes. + +fork.2 + Alain Portal + Fix small wording error. + +gethostid.2 + Stefan Puiu / mtk + Add NOTES on what happens if gethostid() can't open /etc/hostid. + +idle.2 + mtk + Made NOTES text into a VERSIONS section, since that's what it + really describes. + +ioperm.2 + mtk + Minor wording changes. + +intro.2 + mtk + Rewrite to reflect the fact that the _syscallN + macros are no longer available. + +io_cancel.2 + mtk + Add "Link with -laio" to SYNOPSIS. + +io_destroy.2 + mtk + Add "Link with -laio" to SYNOPSIS. + +io_getevents.2 + mtk + Add "Link with -laio" to SYNOPSIS. + +io_setup.2 + mtk + Add "Link with -laio" to SYNOPSIS. + +io_submit.2 + Ivana Varekova + Fix include in SYNOPSIS. + mtk + Add "Link with -laio" to SYNOPSIS. + +ipc.2 + mtk + Add semtimedop() to SEE ALSO. + Note that some architectures don't have ipc(2); instead + real system calls are provided for shmctl(), semctl(), etc. + +killpg.2 + mtk + Minor wording changes. + +listen.2 + mtk + Added to SYNOPSIS. + +sched_setscheduler.2 + mtk + Add NOTES para about permissions required to call + sched_setscheduler() on other systems. + +select.2 + mtk + Noted that 'timeout' can also be changed if select() is + interrupted by a signal. + +setup.2 + mtk + Remove reference to _syscall0() macro. + +shmop.2 + mtk + Changed text for EINVAL error. + +socketcall.2 + mtk + Add recvmsg() and sendmsg() to SEE ALSO. + Note that some architectures don't have socketcall(2); instead + real system calls are provided for socket(), bind(), etc. + +swapon.2 + Ivana Varekova / mtk + Update text for EPERM error describing the maximum number of + swap files. (From downstream Fedora patch.) + +write.2 + mtk + Added details about seekable files and file offset. + Noted that write() may write less than 'count' bytes, and + gave some examples of why this might occur. + Noted what happens if write() is interrupted by a signal. + Minor wording changes. + +__setfpucw.3 + mtk + Added a CONFORMING TO section; other minor edits. + +confstr.3 + mtk + Minor rewrites in code example. + +ctime.3 + Justin Pryzby + Make SEE ALSO refer to timegm.3 + +daemon.3 + mtk + Small wording change. + +dl_iterate_phdr.3 + Michael Gehring + Comment was missing closing "*/". + +dlopen.3 + mtk + Formatting changes, and minor rewordings. + mtk, after a note by Serge van den Boom + Add a comment explaining the need for the rather + strange cast of the return value of dlsym(). + +fpclassify.3 + mtk + Add "isinf" to NAME section. + +getgrouplist.3 + mtk + Minor rewording. + +getline.3 + mtk + Minor rewording, and note that '*n* is ignored + if '*lineptr' is NULL. + +malloc.3 + Ivana Varekova / mtk + Update description of MALLOC_CHECK_ to include description + for value 3. (From downstream Fedora patch.) + +netlink.3 + mtk + Added a CONFORMING TO section; other minor edits. + +openpty.3 + mtk + Minor changes to SYNOPSIS. + +program_invocation_name.3 + mtk + Shortened page title to INVOCATION_NAME. + +rtnetlink.3 + mtk + Added a CONFORMING TO section; other minor edits. + +scanf.3 + Florian Ernst + Fix duplicated word "the". + (Really fix http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=412467 !) + +select_tut.3 + mtk + Small wording change. + +setnetgrent.3 + mtk + Added a CONFORMING TO section. + +sigpause.3 + mtk + Added a CONFORMING TO section. + +strftime.3 + Just Pryzby + Small wording fix. + mtk + Note use of "gcc -Wno-format-y2k" to avoid the "`%c' yields only + last 2 digits of year in some locales" warning. + +strstr.3 + mtk + Add "strcasestr" to NAME section. + +syslog.3 + mtk + Small wording change. + + +termios.3 + mtk + Reformat SYNOPSIS. + Added a CONFORMING TO section. + +timegm.3 + mtk + Small wording changes. + +ulimit.3 + mtk + Remove erroneous text saying that glibc does not provide + ; it does. + +initrd.4 + mtk + Various reformattings. + +core.5 + mtk + Added a sentence noting why core dumps named "core.PID" were useful + with LinuxThreads. + +bootparam.7 + mtk + Fix capitalization in .SS headings. + +epoll.7 + mtk + Language clean ups. + +feature_test_macros.7 + mtk + Added SEE ALSO section. + +mq_overview.7 + mtk + Reformatted headings; minor rewrites. + +sem_overview.7 + mtk + Reformatted headings; minor rewrites. + +socket.7 + Loïc Minier + Document argument type for SO_REUSEADDR. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=255881 + +uri.7 + mtk + Wrap long line in SYNOPSIS. + +ldconfig.8 + mtk + Added SEE ALSO section. + + +==================== Changes in man-pages-2.62 ==================== + +Released: 2007-07-09 + +This release consists solely of formatting fixes. There are no changes +to content. + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Stepan Kasal + +Apologies if I missed anyone! + + +Global changes +-------------- + +Many many pages + mtk + Many many formatting fixes. + +man[013]p/* + Stepan Kasal + Add section number to .TH line for POSIX pages in man[013]p. + + +==================== Changes in man-pages-2.63 ==================== + +Released: 2007-07-16 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Arnd Bergmann +Eduardo M. Fleury +Ivana Varekova +Justin Pryzby +Marc Boyer +Martin (Joey) Schulze +Martin Röhricht +Patrick Mansfield +Pierre Habouzit +Stepan Kasal + +Apologies if I missed anyone! + + +Global changes +-------------- + +gettimeofday.2 +madvise.2 +msgctl.2 +select.2 +semctl.2 +shmctl.2 +syslog.2 +stat.2 +a64l.3 +printf.3 +termios.3 +xdr.3 +sd.4 + mtk + Minor wording changes. + +obsolete.2 +syscall.2 +unimplemented.2 + mtk + Added SEE ALSO reference to syscalls.2. + + +New pages +--------- + +sgetmask.2 + mtk + A real man page for sgetmask(2) and ssetmask(2). + (This page replaces a previous link of the same name, which + linked to signal.2.) + +spu_create.2 + Arnd Bergmann with additional work by Eduardo M. Fleury and mtk + Document the PowerPC SPU spu_create() system call. + (Originally taken from the kernel source file + Documentation/filesystems/spufs.txt.) + +spu_run.2 + Arnd Bergmann with additional work by Eduardo M. Fleury and mtk + Document the PowerPC SPU spu_run() system call. + (Originally taken from the kernel source file + Documentation/filesystems/spufs.txt.) + +spufs.7 + Arnd Bergmann with additional work by Eduardo M. Fleury and mtk + Document the PowerPC SPU file system. + (Originally taken from the kernel source file + Documentation/filesystems/spufs.txt.) + + +Removed Pages +------------- + +__clone.2 + mtk + This file was created by accident in 2.61, as a copy of clone.2. + (it should have been a link to clone.2.) + +obsolete.2 + mtk + Details on this page are covered in syscalls.2 and in + respective syscall man pages (stat.2, uname.2). + +undocumented.2 + mtk + This page is very out of date, and in any case difficult + to maintain. Information about undocumented system calls + is maintained in the HOWTOHELP file, and probably in other + places soon. + +killpg.3 + mtk + This rather incomplete page seems unnecessary since there + is a killpg.2. + + +New links +--------- + +chown32.2 +fchown32.2 +getegid32.2 +geteuid32.2 +getgid32.2 +getgroups32.2 +getresgid32.2 +getresuid32.2 +getuid32.2 +lchown32.2 +setfsgid32.2 +setfsuid32.2 +setgid32.2 +setgroups32.2 +setregid32.2 +setresgid32.2 +setresuid32.2 +setreuid32.2 +setuid32.2 + mtk + Added as link to corresponding page without "32". + +fcntl64.2 +fstat64.2 +fstatat64.2 +fstatfs64.2 +ftruncate64.2 +getdents64.2 +lstat64.2 +pread64.2 +pwrite64.2 +sendfile64.2 +stat64.2 +statfs64.2 +truncate64.2 + mtk + Added as link to corresponding page without "64". + +__clone2.2 +clone2.2 + mtk + Links to clone.2. + +ugetrlimit.2 + mtk + Link to getrlimit.2. + +mq_notify.2 +mq_open.2 +mq_timedreceive.2 +mq_timedsend.2 +mq_unlink.2 + mtk + Added as links to corresponding section 3 pages. + +fadvise64.2 +fadvise64_64.2 + mtk + Links to posix_fadvise.2. + +rt_sigaction.2 +rt_sigpending.2 +rt_sigprocmask.2 +rt_sigtimedwait.2 + mtk + Added as link to corresponding page without "rt_" prefix. + +rt_sigqueueinfo.2 + mtk + Link to sigqueue.2. + +madvise1.2 +tuxcall.2 +vserver.2 + mtk / Ivana Varekova + Link to unimplemented.2. + + +Changes to individual pages +--------------------------- + +access.2 + mtk + Fairly substantial rewrites of various parts, + and a few additions. + +chmod.2 + mtk + Update SYNOPSIS to reflect the fact that fchmod(2) needs + either "#define _XOPEN_SOURCE 500" or "#define _BSD_SOURCE". + +chown.2 + mtk + Update SYNOPSIS to reflect the fact that fchmod(2) and lchown(2) + need either "#define _XOPEN_SOURCE 500" or "#define _BSD_SOURCE". + Added an example program. + +killpg.2 + mtk + Note that killpg() is actually a library function on Linux. + +mmap.2 + mtk + Added note that glibc mmap() wrapper nowadays invokes mmap2(). + +mmap2.2 + Ivana Varekova / mtk + On most platforms the unit for 'offset' is 4096 bytes, not + the system page size. + mtk + Rewrote NOTES to note that glibc mmap() wrapper nowadays + invokes this system call. + mtk + Added an EXAMPLE program. + +oldfstat.2 +oldlstat.2 +oldstat.2 + mtk + Changed link to point to stat.2 (instead of obsolete.2). + +olduname.2 +oldolduname.2 + mtk + Changed link to point to uname.2 (instead of obsolete.2). + +sched_setaffinity.2 + Martin Röhricht + Added _GNU_SOURCE to SYNOPSIS. + +semctl.2 + mtk + Remove reference discussion of ipc(2), since none of the + other System V IPC pages mention ipc(2). + +semop.2 + mtk + Add an example code segment. + +shmctl.2 + mtk + Add svipc(7) to SEE ALSO list. + +sigaction.2 + mtk + Reformatted tables as lists; other minor reformattings and + wording changes. + +sigqueue.2 + mtk + Added info on rt_sigqueueinfo(2). + +sigwaitinfo.2 + mtk + Noted that sigwaitinfo() is a library function implemented on + top of sigtimedwait(). + +ssetmask.2 + mtk + Make this link point to new sgetmask.2 instead of signal.2. + +stat.2 + mtk + Add notes on the different system call interfaces that + have appeared over time. + +syscalls.2 + mtk + A fairly substantial rewrite of this page, + bringing it up to date with the current + kernel version, and listing all system calls + in tabular form. + +uname.2 + mtk + Add notes on the different system call interfaces that + have appeared over time. + +unimplemented.2 + mtk + Add vserver, madvise1 to NAME line. + Removed SEE ALSO reference to obsolete.2. + Ivana Varekova + Add tuxcall to NAME line. + +mktemp.3 + Patrick Mansfield + Fix description of return value. + +strcat.3 + Marc Boyer + Minor fix to example program. + +undocumented.3 + mtk + Add section numbers to function names; remove some functions + since they are documented. + +proc.5 + mtk + Update/correct text on /proc/malloc. + mtk, after a note by Pierre Habouzit, and a few comments by Justin Pryzby + Update description of /proc/PID/stat to match 2.6.21. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=417933 + +inotify.7 + mtk + IN_DONT_FOLLOW and IN_ONLYDIR are only available from 2.6.15. + +signal.7 + Stepan Kasal / mtk + Note SIGRTMIN value depends on glibc. + mtk + Various rewrites and additions to the text in real-time signals. + Add SEE ALSO reference to sgetmask.2. + +svipc.7 + mtk + Add ipc(2) to SEE ALSO. + + +==================== Changes in man-pages-2.64 ==================== + +Released: 2007-07-27 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Aleksandr Koltsoff +Andries Brouwer +Justin Pryzby + +Apologies if I missed anyone! + + +Global changes +-------------- + +INFINITY.3 +_exit.2 +a64l.3 +abs.3 +acct.2 +acosh.3 +addseverity.3 +adjtime.3 +asinh.3 +atanh.3 +atoi.3 +brk.2 +cbrt.3 +cfree.3 +chdir.2 +chmod.2 +chown.2 +clearenv.3 +clock_getres.3 +clone.2 +confstr.3 +copysign.3 +ctermid.3 +ctime.3 +daemon.3 +dirfd.3 +div.3 +drand48.3 +drand48_r.3 +dysize.3 +ecvt.3 +ecvt_r.3 +erf.3 +euidaccess.3 +exp2.3 +expm1.3 +fdatasync.2 +ferror.3 +fexecve.3 +fgetgrent.3 +fgetpwent.3 +finite.3 +flockfile.3 +fopen.3 +fpclassify.3 +fsync.2 +futimes.3 +fwide.3 +gamma.3 +gcvt.3 +getcwd.3 +getdate.3 +getdirentries.3 +getdomainname.2 +getdtablesize.2 +getgrent.3 +getgrent_r.3 +getgrouplist.3 +getgroups.2 +gethostbyname.3 +gethostid.2 +gethostname.2 +getlogin.3 +getmntent.3 +getpagesize.2 +getpw.3 +getpwent.3 +getpwent_r.3 +getpwnam.3 +getsid.2 +getspnam.3 +gettimeofday.2 +getumask.3 +getusershell.3 +gsignal.3 +hypot.3 +inet.3 +initgroups.3 +insque.3 +isalpha.3 +iswblank.3 +j0.3 +kill.2 +killpg.2 +lgamma.3 +lockf.3 +log1p.3 +log2.3 +logb.3 +longjmp.3 +lrint.3 +lround.3 +madvise.2 +mbsnrtowcs.3 +memfrob.3 +mincore.2 +mkdtemp.3 +mknod.2 +mkstemp.3 +mktemp.3 +nan.3 +nanosleep.2 +nextafter.3 +nice.2 +on_exit.3 +perror.3 +posix_memalign.3 +posix_openpt.3 +printf.3 +profil.3 +psignal.3 +putenv.3 +putpwent.3 +qecvt.3 +rand.3 +random.3 +rcmd.3 +readahead.2 +readlink.2 +realpath.3 +remainder.3 +remquo.3 +rexec.3 +rint.3 +round.3 +rpmatch.3 +scalb.3 +scandir.3 +scanf.3 +seekdir.3 +select.2 +sem_wait.3 +semop.2 +setbuf.3 +setenv.3 +seteuid.2 +setjmp.3 +setnetgrent.3 +setpgid.2 +setresuid.2 +setreuid.2 +sigaltstack.2 +siginterrupt.3 +significand.3 +sigqueue.2 +sigvec.3 +sigwaitinfo.2 +sockatmark.3 +stat.2 +stime.2 +strdup.3 +strerror.3 +strsep.3 +strtod.3 +strtok.3 +strtol.3 +strtoul.3 +symlink.2 +sync.2 +syscall.2 +syslog.3 +tcgetsid.3 +telldir.3 +tempnam.3 +termios.3 +tgamma.3 +timegm.3 +toascii.3 +trunc.3 +truncate.2 +ttyslot.3 +tzset.3 +ualarm.3 +unlocked_stdio.3 +unshare.2 +usleep.3 +vfork.2 +vhangup.2 +wait.2 +wait4.2 +wcscasecmp.3 +wcsncasecmp.3 +wcsnlen.3 +wcsnrtombs.3 +wcswidth.3 +wordexp.3 +wprintf.3 + mtk + Added/updated feature test macro requirements for + glibc; see feature_test_macros.7 for details. + +Changes to individual pages +--------------------------- + +mq_notify.2 +mq_open.2 +mq_timedreceive.2 +mq_timedsend.2 +mq_unlink.2 + mtk + Fix broken link + +setpgid.2 + mtk + Fairly substantial changes and corrections, including adding + coverage of all of the interfaces that get/set PGIDs. + +syscalls.2 + mtk / aeb + Various rewordings; clear up some imprecisions. + +lgamma.3 + mtk + Added 'signgam' to SYNOPSIS and NAME line. + +strerror.3 + mtk + Note that the XPG version is provided since glibc 2.3.4. + The page formerly said that the GNU-specific version + is provided by default. That certainly isn't true + nowadays, since _POSIX_C_SOURCE is set to 200112L by + default, so that the XSI-compliant version is supplied + by default. + +man-pages.7 + mtk + Added note pointing to feature_test_macros.7 for a description + of how feature test macro requirements should be specified in + manual pages. Various other minor fixes and changes. + +feature_test_macros.7 + mtk + Added note about how feature test macros are specified + in manual pages. + Many other corrections, improvements, additions, and + details about differences across glibc versions. + + +==================== Changes in man-pages-2.65 ==================== + +Released: 2007-09-17 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Aleksandr Koltsoff +Andi Kleen +Anton Blanchard +Ari Entlich +Carsten Emde +François Diakhate +Geoff Clare +Jon Burgess +Julien Cristau +Lee Schermerhorn +Mats Wichmann +Maxime Bizon +Maxime Vaudequin +Michael Prokop +Mike Frysinger +Nicolas François +Nicolas George +Paul Brook +Reuben Thomas +Sam Varshavchik +Samuel Thibault +Thomas Huriaux +Tolga Dalman +Ulrich Drepper +Vincent Lefevre + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + +Various pages + mtk + Use 'glibc' consistently to refer to GNU C library. + +Various pages + mtk + Order errors under ERRORS alphabetically. + +Various pages + Nicolas François + Spelling and formatting fixes, as per + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=439560 + +intro.2 +select.2 +fmtmsg.3 +getgrent_r.3 +envz_add.3 +rtime.3 +strptime.3 +wordexp.3 + Maxime Vaudequin + Add "#include " (to declare exit(3)) to example program. + + +New pages +--------- + +timeradd.3 + mtk + Description of timeradd(), timersub(), timerclear(), + timerisset(), timercmp() macros for operating on + struct timeval. + + +Removed pages +------------- + +fdatasync.2 + mtk + Somehow, over time, material on fdatasync(2) crept into + fsync.2, and fdatasync also got added to the NAME section + of fsync.2. All of the material in fdatasync.2 that was + not already in fsync.2 has now been moved there, and + the former page has been removed. + In place of the content there, is now a link to fsync.2. + + +New links +--------- + +clock_getres.2 +clock_gettime.2 +clock_settime.2 + mtk + Link to man3/clock_getres.3. + +fdatasync.2 + mtk + Link to fsync.2. + +fdopendir.3 + mtk + Link to opendir.3. + +gethostbyaddr_r.3 + Mats Wichmann + Link to gethostbyaddr.3. + +timerclear.3 +timercmp.3 +timerisset.3 +timersub.3 + mtk + Links to new timeradd.3. + + +Changes to individual pages +--------------------------- + +Makefile + Mike Frysinger + Make the install target of man-pages respect the standard + "DESTDIR" variable as well as check the exit status of the + install command so errors aren't ignored. + +get_mempolicy.2 + Lee Schermerhorn + changed the "policy" parameter to "mode" through out the + descriptions in an attempt to promote the concept that the memory + policy is a tuple consisting of a mode and optional set of nodes. + + added requirement to link '-lnuma' to synopsis + + rewrite portions of description for clarification. + + added all errors currently returned by sys call. + + removed cautionary note that use of MPOL_F_NODE|MPOL_F_ADDR + is not supported. This is no longer true. + + added mmap(2) to SEE ALSO list. + +getitimer.2 + mtk + Since kernel 2.6.22, Linux setitimer() now conforms to POSIX.1, + giving an EINVAL error for a non-canonical tv_usec value. + +gettimeofday.2 + mtk + Replace discussion of timer* macros with a pointer + to new page timeradd.3. + +ioctl_list.2 + Nicolas George + Fixed argument type for BLKGETSIZE. + +mbind.2 + Lee Schermerhorn + + changed the "policy" parameter to "mode" throughout the + descriptions in an attempt to promote the concept that the memory + policy is a tuple consisting of a mode and optional set of nodes. + + rewrite portions of description for clarification. + + clarify interaction of policy with mmap()'d files and shared + memory regions, including SHM_HUGE regions. + + defined how "empty set of nodes" specified and what this + means for MPOL_PREFERRED. + + mention what happens if local/target node contains no + free memory. + + clarify semantics of multiple nodes to BIND policy. + Note: subject to change. We'll fix the man pages when/if + this happens. + + added all errors currently returned by sys call. + + added mmap(2), shmget(2), shmat(2) to SEE ALSO list. + +mmap.2 +mprotect.2 + François Diakhate + Add text noting that PROT_WRITE may (and on x86 does) + imply PROT_READ. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=441387 + +nfsservctl.2 + Aleksandr Koltsoff + Fix prototype. + +oldfstat.2 +oldlstat.2 +oldstat.2 + mtk + Fix broken link + +prctl.2 + mtk + Update arches/kernel versions for PR_SET_UNALAIGN / PR_GET_UNALIGN. + +readahead.2 + mtk + Removed SEE ALSO reference to nonexistent fadvise.2. + +reboot.2 + mtk + Place SYNOPSIS comments inside C comments (/* ... */). + +sched_setaffinity.2 + Samuel Thibault + Note what thread is affected if 'pid' is specified + as 0, or as the value returned by getpid(). + +sched_setscheduler.2 + Carsten Emde + Add text on real-time features of mainline Linux kernel. + +select_tut.2 + mtk + sync SYNOPSIS with select.2 + +set_mempolicy.2 + Lee Schermerhorn + + changed the "policy" parameter to "mode" throughout the + descriptions in an attempt to promote the concept that the memory + policy is a tuple consisting of a mode and optional set of nodes. + + added requirement to link '-lnuma' to synopsis + + rewrite portions of description for clarification. + + clarify interaction of policy with mmap()'d files. + + defined how "empty set of nodes" specified and what this + means for MPOL_PREFERRED. + + mention what happens if local/target node contains no + free memory. + + clarify semantics of multiple nodes to BIND policy. + Note: subject to change. We'll fix the man pages when/if + this happens. + + added all errors currently returned by sys call. + + added mmap(2) to SEE ALSO list. + +sigaction.2 + mtk + s/si_sign/si_errno/ in statement about which field is unused. + Ari Entlich + s/SIGILL/SIGCHLD/ for paragraph describing SIGCHLD. + +stat.2 + mtk + Improve text describing underlying system calls. + +swapon.2 + Michael Prokop + EINVAL also occurs if target path is on tmpfs or similar. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=435885 + +sync.2 + mtk + Incorporated material from now deleted fdatasync.2. + +syscall.2 + mtk + Small fix in example program. + +uname.2 + mtk + Improve text describing underlying system calls. + +utime.2 + Vincent Lefevre / mtk + Clarify utimes() behaviour when 'times' is NULL. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=431480 + mtk + Other minor clarifications of description of utimes(). + +copysign.3 + Vincent Lefevre + s/sign/sign bit/ to remove ambiguity in description. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=435415 + +euidaccess.3 + mtk + Changed NOTES to VERSIONS. + +ffsl.3 + mtk + Add ffsl and ffsll to NAME line. + +fts.3 + mtk + Removed statement that fts functions are expected to appear + soon in POSIX; it's years old and has not yet come to pass. + +ftw.3 + mtk / Geoff Clare + Fixes/improvements for example program. + +getdate.3 + mtk + Add getdate_r to NAME section. + +getaddrinfo.3 + mtk / Geoff Clare + Fixes/improvements for example program. + +gethostbyaddr.3 + Mats Wichmann + Add documentation for gethostbyaddr_r(). + Plus a few other small fixes. + +gethostbyname.3 + mtk + Add gethostbyname2, gethostbyname2_r, gethostbyname_r, + gethostent_r to NAME line. + +getmntent.3 + mtk + Fix misnamed function references. + +getopt.3 + Jon Burgess + Fix small error in example program. + +getrpcent.3 + mtk + Add setrpcent and endrpcent to NAME line. + +gsignal.3 + Aleksandr Koltsoff + Fix gsignal() prototype. + +hsearch.3 + mtk + Add hcreate_r, hdestroy_r, hsearch_r to NAME line. + +inet.3 + Maxime Bizon + Correct definition of "struct in_addr". + +isatty.3 + mtk + Minor wording fix. + +isgreater.3 + mtk + Add islessequal to NAME line. + +lgamma.3 + Vincent Lefevre + Fix CONFORMING TO section. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=417592 + +log1p.3 + mtk + Add log1pf and log1pl to NAME line. + +longjmp.3 + Paul Brook / mtk + After a call to longjmp(), the values of modified, non-volatile + variables in the function that called setjmp() are unspecified. + +makecontext.3 + Aleksandr Koltsoff + Fix makecontext() prototype. + +malloc.3 + mtk / Tolga Dalman + Explain what happens for malloc(0), or calloc() where one of the + arguments is 0. + mtk + Added notes on malloc()'s use of sbrk() and mmap(). + mtk + Add mmap(2), alloca(3) to SEE ALSO. + +mq_close.3 +mq_getattr.3 +mq_notify.3 +mq_open.3 +mq_receive.3 +mq_send.3 +mq_unlink.3 + mtk + Add "Link with -lrt." to SYNOPSIS. + +opendir.3 + Ulrich Drepper; some edits and additional text by mtk + Document fdopendir(). + +readdir.3 + mtk, after a note by Andi Kleen + Document DT_* constants for d_type. + Ulrich Drepper / mtk + Rework discussion of non-standard structure fields. + +sem_wait.3 + mtk + Minor improvements to example program. + +syslog.3 + mtk + Add vsyslog to NAME section. + +termios.3 + Nicolas François + Fix XCASE feature test macro description. + +wcsspn.3 + Aleksandr Koltsoff + Add return type to prototype. + +proc.5 + mtk + Improve description of num_threads field under /proc/PID/stat. + Maxime Vaudequin + Fix path error (s%proc/sys%proc/sys/kernel%) in mentions of + /proc/sys/ostype, /proc/sys/osrelease and proc/sys/version. + Maxime Vaudequin + I noticed things to correct and to clarify in subsection + "/proc/filesystems" of proc.5: + - clarify filesystems listing: not only FS compiled + into the kernel, also FS kernel modules currently loaded + - add a reference to fs(5) + - add an explanation for FS marked with "nodev" + - s/mount(1)/mount(8)/, also corrected in section "SEE ALSO" + - clarify usage by mount: the current wording may lead to + think /proc/filesystems is always used by mount when no FS + is specified. So, usage of "may" which IMHO is more + appropriate + additional explanations + In mount(8) we can see: + + If no -t option is given, or if the auto type is + specified, mount will try to guess the desired type. + If mount was compiled with the blkid library, the + guessing is done by this library. Otherwise, mount + guesses itself by probing the superblock; if that + does not turn up anything that looks familiar, + mount will try to read the file /etc/filesystems, + or, if that does not exist, /proc/filesystems. + All of the filesystem types listed there will be + tried, except for those that are labeled "nodev" + (e.g., devpts, proc and nfs). If /etc/filesystems + ends in a line with a single * only, mount will + read /proc/filesystems afterwards. + Samuel Thibault + Since linux 2.6.11, /proc/stat has an eighth value for cpu + lines: stolen time, which is the time spent in other operating + systems when running in a virtualized environment. + +arp.7 + Updated BUGS text referring to jiffies; refer to time.7 instead. + +credentials.7 + mtk + Add words to note that file system ID is Linux specific. + +hier.7 + Maxime Vaudequin + This is some corrections for hier.7: + - missing period for /media and /mnt + - /mnt description is not totally correct, it is true for some + distributions but in others /mnt is used as a temporary FS + mount point, as it is specified by FHS: + http://www.pathname.com/fhs/pub/fhs-2.3.html#MNTMOUNTPOINTFORATEMPORARILYMOUNT + - s/X-Windows/X-Window/ (3 occurrences) + - section "SEE ALSO": s/mount(1)/mount(8)/ + +man-pages.7 +man.7 +mdoc.7 +mdoc.samples.7 + mtk / Nicolas François + Nowadays tmac.XXX are called XXX.tmac. + +pthreads.7 + mtk + Update text about modern threading implementations + (NPTL vs LinuxThreads). + +socket.7 + mtk, after a note by Andi Kleen + Clarify that SO_SNDTIMEO and SO_RCVTIMEO only have effect for + socket I/O calls; not for multiplexing system calls like + select() and poll(). + +time.7 + mtk + Add SEE ALSO reference to new timeradd.3. + + +==================== Changes in man-pages-2.66 ==================== + +Released: 2007-10-01 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Amit K. Arora +David Chinner +Fredrik Noring +Mats Wichmann +Maxime Vaudequin +Ollie Wild +Ulrich Drepper + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several +places. + + +New pages +--------- + +fallocate.2 + David Chinner, with some input from Amit Amora and mtk + Describes the fallocate() system call, new in 2.6.23. + + +Changes to individual pages +--------------------------- + +close.2 + Fredrik Noring + Add text cautioning about use of close() in + multithreaded programs. + +execve.2 + Ollie Wild / mtk + Add text describing limit on total size of argv + envp, + and changes that occurred with 2.6.23. + mtk + Add getopt(3) to SEE ALSO list. + +open.2 + mtk, Acked by Ulrich Drepper + Added description of O_CLOEXEC (new in 2.6.23) + other + minor fixes for O_DIRECT. + +recv.2 + mtk + Added description of MSG_CMSG_CLOEXEC (new in 2.6.23). + +sysctl.2 + mtk + Strengthened the warning against using this system call + and note that it may disappear in a future kernel version. + +rpc.3 + Mats Wichmann + Fix type definition for 'protocol' in prototypes of pmap_set() + and pmap_getport(). + + +==================== Changes in man-pages-2.67 ==================== + +Released: 2007-10-08 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +Andrew Josey +Maxime Vaudequin + +Apologies if I missed anyone! + + +Global changes +-------------- + +*.1p +*.3p + mtk, after a note by Andi Kleen and consultation with Andrew Josey. + Add a PROLOG section: + This manual page is part of the POSIX Programmer's Manual. + The Linux implementation of this interface may differ + (consult the corresponding Linux manual page for details + of Linux behavior), or the interface may not be implemented + on Linux. + +*.0p +*.1p +*.3p + mtk + Some formatting fixes, mostly to get rid of unwanted + spaces before "," in formatted output. + +* +*/* + mtk + Change all occurrences of my email address in man-pages source + to my new gmail address. + +Many many pages + Maxime Vaudequin + I noticed useless use of macros with alternating formatting + (".IR" instead ".I" which suffices, ".BR" instead ".B", etc.) + because there is only one element. For example in ldconfig.8: + + -.BR /sbin/ldconfig + +.B /sbin/ldconfig + + This is not very important, it only makes the sources more tidy. + To find these I used: + + egrep '^\.(B[RI]|R[IB]|I[RB]) ([^ ]+|\"[^\"]\+\")$' + + And if you want to make these changes, you can use: + + sed 's/^\(\.[BRI]\)[BRI]\( \([^ ]\+\|\"[^\"]\+\"\)\)$/\1\2/g' + + +==================== Changes in man-pages-2.68 ==================== + +Released: 2007-11-19 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +A. Costa +Andrew McDonald +Geoff Clare +Heikki Orsila +Hyokyong Kim +Ivana Varekova +Justin Pryzby +Maxime Vaudequin +Mike Frysinger +Nicolas François +Pádraig Brady +Sam Varshavchik +Timo Juhani Lindfors +Ulrich Drepper + +Apologies if I missed anyone! + + +Global changes +-------------- + +faccessat.2 +fchmodat.2 +fchownat.2 +fstatat.2 +futimesat.2 +linkat.2 +mkdirat.2 +mknodat.2 +readlinkat.2 +renameat.2 +symlinkat.2 +mkfifoat.3 + mtk, after http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=445436 + by Timo Juhani Lindfors + Added to SYNOPSIS. + +Typographical or grammatical errors have been corrected in several places. + + +New pages +--------- + +_syscall.2 + mtk + Created as a new page, by taking the content specific to + the _syscall() macros from intro(2). + + +Changes to individual pages +--------------------------- + +README + mtk + Brought up to date. + +man-pages-*-Announce + mtk + Brought the info in here up to date. + +intro.1 + mtk + Added intro paragraph about section, plus a paragraph + about exit status values. + Move "user intro" text to NOTES. + +get_mempolicy.2 + mtk + Reorder ERRORS sections alphabetically + +intro.2 + mtk + Pretty much a complete rewrite, covering some additional topics. + Moved _syscallN() material to new _syscall(2) page. + +mbind.2 + mtk + Reorder ERRORS sections alphabetically + +mmap.2 + Maxime Vaudequin + Fix syntax error in example program. + +prctl.2 + mtk + Linux 2.6.22 added support on Alpha for PR_SET_UNALIGN. + +ptrace.2 + Nicolas François / mtk + s/PTRACE_POKEUSR/PTRACE_POKEUSER/ + s/PTRACE_PEEKUSR/PTRACE_PEEKUSER/ + +read.2 + mtk / Geoff Clare + Add text describing timerfd EINVAL error for read(2). + +set_mempolicy.2 + mtk + Reorder ERRORS sections alphabetically + +syscall.2 + mtk + Added _syscall(2) and intro(2) to SEE ALSO section. + +syscalls.2 + mtk + Added fallocate(2); removed timerfd(2). + +sysinfo.2 + mtk + Removed reference to example in intro(2). + +dlopen.3 + mtk + Added "Link with -ldl." to SYNOPSIS. + +getaddrinfo.3 + Ulrich Drepper / mtk + Remove references to getipnodebyname.3 and getipnodebyaddr.3. + +gethostbyname.3 + mtk / Ulrich Drepper + Remove SEE ALSO references to getipnodebyname.3 and + getipnodebyaddr.3. + + Pádraig Brady / mtk / Ulrich Drepper + Point out that the functions described on this page + are made obsolete by getaddrinfo(3) and getnameinfo(3). + +getipnodebyname.3 + mtk + Clarify that glibc does not implement these functions. + +glob.3 + Ulrich Drepper / mtk + Fix description of GLOB_ONLYDIR. + mtk + Added description of GLOB_TILDE_NOMATCH. + Expanded the description of various flags. + Various wording fixes.. + +intro.3 + mtk + Pretty much a complete rewrite, covering some additional topics. + +posix_fallocate.3 + mtk + Add SEE ALSO referring to fallocate.2. + +rpc.3 + Sam Varshavchik + Add some arg declarations to prototypes; fix typos. + +setbuf.3 + Mike Frysinger + Fix text in BUGS section. + +sigset.3 + mtk + The sigset() bugs were fixed in glibc 2.5. + See http://sourceware.org/bugzilla/show_bug.cgi?id=1951 + +intro.4 + mtk + Minor rewrites. + +st.4 + Maxime Vaudequin + Various small corrections, formattings and modifications. + +elf.5 + Mike Frysinger + Document: + - new p_flag: PT_GNU_STACK + - new sections: .gnu.version .gnu.version_d .gnu.version_r + .note.GNU-stack + - new structures: ElfN_Verdef ElfN_Verdaux ElfN_Verneed + ElfN_Vernaux + +intro.5 + mtk + Minor rewrites. + +proc.5 + Ivana Varekova / mtk + Add text noting that since kernel 2.6.16, /proc/slabinfo is + only available if CONFIG_SLAB is enabled. + Maxime Vaudequin + Update description of /proc/pci. + Maxime Vaudequin + Give italic formatting to file names in proc.5. + mtk + The display type of the /proc/PID/stat fields changed + %lu to %u in Linux 2.6.22: + flags + rt_priority + policy + +slabinfo.5 + Ivana Varekova / mtk + Add text noting that since kernel 2.6.16, /proc/slabinfo is + only available if CONFIG_SLAB is enabled. + +intro.6 + mtk + Minor rewrites. + +bootparam.7 + Maxime Vaudequin + Update references to files in kernel "Documentation" directory. + +intro.7 + mtk + Minor rewrites. + +ipv6.7 + Andrew McDonald + Fix description of IPV6_ROUTER_ALERT option. + +standards.7 + mtk + Note online location of C99 standard. + +intro.8 + mtk + Some rewrites, plus new paragraph on exit status values. + + +==================== Changes in man-pages-2.69 ==================== + +Released: 2007-12-03 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Adam Borowski +Alain Portal +Andries E. Brouwer +J. Bruce Fields +David Härdeman +Jeremy Kerr +Luke Browning +Mats Wichmann +Maxime Vaudequin +Mike Frysinger +Reuben Thomas +Sam Varshavchik + +Apologies if I missed anyone! + + +Global changes +-------------- + +*.[013]p + mtk + Many whitespace clean-ups in formatted output. + +mprotect.2 +bind.2 +mq_notify.3 +makecontext.3 +fmemopen.3 + David Härdeman / mtk + Rename error handling function in example program + (s/die/handle_error/). + +Typographical or grammatical errors have been corrected in several places. + + +Removed pages +------------- + +HOWTOHELP +MAINTAINING + mtk + The content of these files is now available in HTML format. + +New links +--------- + +cfsetspeed.3 + mtk + Link to termios.3. + + +Changes to individual pages +--------------------------- + +time.1 + Alain Portal + Added "Linux User's Manual" to .TH line. + +_syscall.2 + aeb / mtk + Remove outdated text about pointer blocks for syscalls that have + more than 5 arguments. + +fcntl.2 + J. Bruce Fields + Add warning that mandatory locking is unreliable. + J. Bruce Fields + Clarify details in description of file leases. + J. Bruce Fields / mtk + Minor wording edits. + J. Bruce Fields + Add F_GETLEASE under RETURN VALUE. + +mmap.2 + mtk + Handle errors using a custom handle_error() macro. + +sched_setscheduler.2 + Mats Wichmann + Add BUGS text noting that the return value from Linux + sched_setschuler() does not conform to POSIX. + +spu_create.2 + Jeremy Kerr + Various updates and improvements. + Luke Browning + Refinement of text describing a "gang". + mtk + Minor edits. + +spu_run.2 + Jeremy Kerr + Various updates and improvements. + mtk + Minor edits. + +err.3 + mtk + Remove HISTORY section. + +fopen.3 + Mike Frysinger + Document 'e' (close-on-exec) option, new in glibc 2.7. + +getloadavg.3 + Alain Portal / mtk + Remove HISTORY section. + +printf.3 + Andries E. Brouwer / mtk + Fix the discussion of stdarg macros in the description of + vprintf() description. + +sem_wait.3 + mtk + Handle errors using a custom handle_error() macro. + +sigsetops.3 + Mats Wichmann + Note that sigset_t objects must be initialized + with sigemptyset() or sigfillset() before the other + macros are employed. + +termios.3 + mtk, after a note by Alain Portal + Added cfsetspeed() to SYNOPSIS. Added text under CONFORMING TO + noting that cfsetspeed() is BSD specific. + +ttyslot.3 + Alain Portal + Various references to "getty" were changed to "mingetty", since + that is the manual page more likely to be found on current + systems. (Completes changes that were made in man-pages-2.44.) + +initrd.4 + mtk, after a note by Alain Portal + Move "Configuration" section to top of page (like other + section 4 pages) and make it a .SH section. + +full.4 + mtk + Re-ordered CONFIGURATION section to go before DESCRIPTION. + +sk98lin.4 + Maxime Vaudequin + Fix reference to kernel Documentation file. + +elf.5 + mtk + Renamed HISTORY section to NOTES, and removed BSD specific info. + +proc.5 + Maxime Vaudequin + Mention grub(8) in same sentence as lilo(8). + Maxime Vaudequin + Improve description of /proc/sys/abi and + /proc/sys/kernel/modprobe. + +utmp.5 + Alain Portal + Various references to "getty" were changed to "mingetty", since + that is the manual page more likely to be found on current + systems. (Completes changes that were made in man-pages-2.44.) + +iso_8859-2.7 + Adam Borowski + Reverse the 2.68 change applied by mtk in response to + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=445085 + that replaced "Sorbian" with "Serbian". + (Sorbian is a language of 50000 people in Brandenburg.) + +man-pages.7 + mtk + Added CONFIGURATION to list of "standard" section names. + +spufs.7 + Jeremy Kerr + Various updates and improvements. + mtk + Minor edits. + +tcp.7 + Maxime Vaudequin + Fix reference to kernel Documentation file. + + +==================== Changes in man-pages-2.70 ==================== + +Released: 2007-12-06 + + +Global changes +-------------- + +Many pages + mtk + Remove section numbers for page references where the + reference refers to the page itself. (This stops man2html + producing links from a page back to itself.) + +Typographical or grammatical errors have been corrected in several places. + + +Changes to individual pages +--------------------------- + +get_mempolicy.2 + mtk + Add CONFORMING TO section. + +io_getevents.2 + mtk + Remove redundant SEE ALSO entry. + +mbind.2 + mtk + Add CONFORMING TO section. + +msgop.2 + mtk + Remove redundant SEE ALSO entries. + +sigprocmask.2 + mtk + Remove redundant SEE ALSO entry. + +splice.2 + mtk + Remove redundant SEE ALSO entry. + Add SEE ALSO referring to vmsplice(2). + +csin.3 + mtk + Remove redundant SEE ALSO entry. + Add SEE ALSO referring to ccos(3). + +gethostbyname.3 + mtk + Add gethostbyaddr_r to NAME section. + +rint.3 + mtk + Remove redundant SEE ALSO entry. + +sigsetops.3 + mtk + Minor rewording. + +epoll.7 + mtk + Minor rewording. + + +==================== Changes in man-pages-2.71 ==================== + +Released: 2007-12-14 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +John Sigler +Josh Triplett +Mats Wichmann +Pascal MALAISE +Sam Varshavchik + +Apologies if I missed anyone! + + +Global changes +-------------- + +err.3 +fts.3 +getloadavg.3 +queue.3 +rcmd.3 +rexec.3 +stdin.3 +elf.5 +operator.7 + mtk + Replaced the use of mdoc macros on these pages with man + macros. The only pages in man-pages that still use + mdoc macros are mdoc.7 and mdoc.samples.7. + +Typographical or grammatical errors have been corrected in several places. + + +Deleted pages +------------- + +TODO + mtk + This information is now on the website. + + +Changes to individual pages +--------------------------- + +Changes.old + mtk + Reformat various change log entries to use a consistent format. + Expand Debian bug report numbers to be URLs. + Other minor tidy-ups. + +fcntl.2 + mtk + Document the F_DUPFD_CLOEXEC operation, which is + new in kernel 2.6.24. + +listen.2 + Josh Triplett + Fix incorrect path for somaxconn. + +getpw.3 + Alain PORTAL + Add ENOENT error to ERRORS. + +sysconf.3 + Mats Wichmann + Add documentation of _SC_NPROCESSORS_CONF and _SC_NPROCESSORS_ONLN. + +tty.4 + John Sigler + Add tty_ioctl(4) to SEE ALSO list. + +regex.7 + Pascal MALAISE + Separate text on back references from that describing basic regexps, + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=379829. + mtk + Remove crufty text about word boundaries. + + +==================== Changes in man-pages-2.72 ==================== + +Released: 2007-12-14 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Alex Tuninga +Bert Wesarg +Maxime Vaudequin +Rob Weryk +Sam Varshavchik + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages + Alain PORTAL / mtk + Format include files consistently (".I <.*\.h>"). + +Various pages + Alain PORTAL / mtk + Format pathname in italics (.I). + +dbopen.3 +mpool.3 +recno.3 + Alain PORTAL + Remove brackets ([]) around error names. + +console.4 +tty.4 +ttyS.4 +issue.5 +ttytype.5 +utmp.5 + mtk / Maxime Vaudequin + Some systems have mingetty(8), others have agetty(8), so both + should be mentioned when we are talking about getty-style programs. + + +Typographical or grammatical errors have been corrected in several places. + + +Renamed pages +------------- + +filesystems.5 + mtk / Alain PORTAL + Was previously fs.5 + + +New links +--------- + +argz.3 + Bert Wesarg / mtk + Link to argz_add.3. + +envz.3 + Bert Wesarg / mtk + Link to envz_add.3. + +fs.5 + mtk / Alain PORTAL + Link to filesystems.5. + + +Changes to individual pages +--------------------------- + +readahead.2 + Rob Weryk + Fix declaration of 'offset' in SYNOPSIS. + +seteuid.2 + mtk + s/SETGUID/SETEUID/ in .TH line. + +__setfpucw.3 + mtk + Fixed include files references / formatting. + +abort.3 + mtk, after a note by Alex Tuninga + A fairly significant rewrite to clarify operation of abort(). + +argz_add.3 + Bert Wesarg / mtk + s/envz/envz_add/ in SEE ALSO. + +basename.3 + mtk + s/DIRNAME/BASENAME/ in .TH line, and swap function names + in NAME section. + +envz_add.3 + Bert Wesarg / mtk + s/argz/argz_add/ in SEE ALSO. + +flockfile.3 + mtk + s/LOCKFILE/FLOCKFILE/ in .TH line. + +getgrent_r.3 + mtk + s/GETGRENT/GETGRENT_R/ in .TH line. + +stdio.3 + Sam Varshavchik + Reformat function list at end of page as a proper table. + +ttyslot.3 + Maxime Vaudequin + Revert earlier s/getty/mingetty/. This page talks about + historical behavior, and that means "getty(8)". + +undocumented.3 + mtk + Remove reference to "obstack stuff"; it's not clear what + that is about. + +console_ioctl.4 + mtk + s/CONSOLE_IOCTLS/CONSOLE_IOCTL/ in .TH line. + +proc.5 + mtk + s/fs (5)/filesystems (5)/ + +man-pages.7 + mtk / Alain PORTAL + Improve discussion of formatting of file names. + + +==================== Changes in man-pages-2.73 ==================== + +Released: 2007-12-14 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Pádraig Brady +Reuben Thomas + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages + Alain PORTAL + Formatting fixes. + +Typographical or grammatical errors have been corrected in several places. + + +Changes to individual pages +--------------------------- + +mknod.2 + mtk, after a report by Reuben Thomas + Clarify use of mkfifo() versus mknod(). + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=455825 + +fgetgrent.3 + mtk + Small rewording. + +fgetpwent.3 + mtk + Small rewording. + +rcmd.3 + mtk + Noted feature test macro requirements. + BUGS: noted that iruserok() is not declared in glibc headers. + +filesystems.5 + mtk + Added Reiserfs, XFS, JFS to list of file systems. + + +==================== Changes in man-pages-2.74 ==================== + +Released: 2007-12-20 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andrew Morton +David Brown +Jeremy Kerr +Mats Wichmann +Sam Morris +Sam Varshavchik +Samuel Thibault + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages + Alain PORTAL + Formatting fixes. + +Various pages + mtk / Alain Portal + s/``...''/"..."/ + +Various pages + mtk + s/epoch/Epoch/ + +Various pages + mtk + Make the standard indent for code samples, shell session + logs, etc. to be ".in +4n". + +Typographical or grammatical errors have been corrected in several places. + + +Changes to individual pages +--------------------------- + +_syscall.2 + mtk + Nowadays there is _syscall6() also. + +chroot.2 + mtk + Various minor formatting changes. + +epoll_wait.2 + mtk + Fix types in structs. + Formatting fixes. + +mount.2 + mtk, after a note by Sam Morris + Clarify that MS_NODIRATIME provides a subset of the + functionality provided by MS_NOATIME. + +sched_setaffinity.2 + mtk + Minor rearrangement of text. + +select_tut.2 + mtk + Fix (my) typos in argument names. + Formatting fixes. + +spu_create.2 + Jeremy Kerr + We can use context FDs for the dirfd argument to the *at() syscalls. + +times.2 + mtk, after a note from David Brown and Andrew Morton + http://marc.info/?l=linux-kernel&m=119447727031225&w=2 + Rework the text describing the return value to be closer + to the requirements of POSIX.1; move Linux details + to NOTES and add a warning not to rely on those details. + Add a warning about the -1 to -4095 bug which results + in a 41 second window where the glibc wrapper will wrongly + return -1 indicating an error. + mtk + Remove cruft HZ text. + Clarify text describing return value of clock(3). + +getw.3 + Mats Wichmann + CONFORMING TO: getw() and putw() were in SUSv2, but are not + in POSIX.1-2001. + +hash.3 + mtk / Alain Portal + Minor rewordings + formatting fixes. + +st.4 + Alain Portal / mtk + Many formatting fixes. + mtk + Place ERRORS in alphabetical order. + +vcs.4 + Samuel Thibault + Document VT_GETHIFONTMASK (new in 2.6.18) and add to example program; + attribute/text characters are in the host byte order. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=456437 + mtk + Minor edits. + +bootparam.7 + Alain PORTAL + Formatting fixes. + +inotify.7 + mtk + Minor heading changes and reformattings. + +man-pages.7 + mtk + Note that code segments, structure definitions, shell session + logs, should be indented by 4 spaces. + +spufs.7 + Jeremy Kerr + Add a little information about the differences to mbox. + + +==================== Changes in man-pages-2.75 ==================== + +Released: 2008-01-08 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andi Kleen +Andreas Henriksson +Jeremy Kerr +Justin Pryzby +Phil Endecott +Sam Varshavchik +Thomas Huriaux +Timo Sirainen +Trond Myklebust + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages + mtk + (Grammatical) hyphenation was fixed in many places. + +epoll_wait.2 +mbind.2 +spu_run.2 +ecvt.3 +fmtmsg.3 +getnameinfo.3 +rtc.4 +proc.5 +charsets.7 +ip.7 +ipv6.7 +raw.7 +uri.7 + Justin Pryzby / mtk + Fix incorrect usage of "a" and "an" before following vowel / + consonant, by reviewing the output of the following scripts: + + for a in $(wc */*.? | awk '$1 > 10 {print $4}' | gv total); do + echo $a + MANWIDTH=4000 man -l $a 2>/dev/null | + egrep '(^| )an [^aeiou][a-z]' + done | less + + for a in $(wc */*.? | awk '$1 > 10 {print $4}' | gv total); do + echo $a + MANWIDTH=4000 man -l $a 2>/dev/null | + egrep '(^| )a [aeiou][a-z]' + done| less + +err.3 +fts.3 +queue.3 +rcmd.3 +rexec.3 +stdin.3 +elf.5 + mtk, after a note by Alain Portal + Improve macros used in 2.71 to convert from "mdoc" to "man". + +_exit.2 +chroot.2 +getgid.2 +getpid.2 +getrusage.2 +getsid.2 +gettid.2 +getuid.2 +iopl.2 +kill.2 +personality.2 +pivot_root.2 +ptrace.2 +sched_setparam.2 +sched_setscheduler.2 +sched_yield.2 +seteuid.2 +setgid.2 +setpgid.2 +setresuid.2 +setreuid.2 +setuid.2 +unlink.2 +wait.2 +openpty.3 +raise.3 +setlogmask.3 +sleep.3 +ttyslot.3 +ulimit.3 +tty.4 +tty_ioctl.4 +path_resolution.7 + mtk + s/current process/calling process/ + +cacheflush.2 +clone.2 +fcntl.2 +getitimer.2 +getrlimit.2 +mmap.2 +mprotect.2 +times.2 +adjtime.3 +byteorder.3 +inet.3 +offsetof.3 +rtc.4 +icmp.7 +pipe.7 +time.7 + mtk + s/x86/i386/ since that is the name used in 'arch' directories + in the kernel source, and previously both i386 and x86 were both + used in man pages; also nowadays 'x86' is somewhat ambiguous, + since it is the name of the 'arch' directory for i386 and x86-64. + +conj.3 +cacos.3 +cacosh.3 +cabs.3 +carg.3 +casin.3 +casinh.3 +catan.3 +catanh.3 +ccos.3 +ccosh.3 +cexp.3 +cimag.3 +clog.3 +cosh.3 +creal.3 +csin.3 +csinh.3 +ctan.3 +ctanh.3 +sinh.3 +tanh.3 + mtk + Various reformattings. + +Various pages + Alain Portal + Formatting fixes. + +mlock.2 +mprotect.2 +mpool.3 +offsetof.3 + Alain Portal + Format SYNOPSIS in a manner consistent with other pages. + +Various pages + mtk / Alain Portal + Format casts so that there is a non-breaking space after the + type, and remove unnecessary parentheses around the casted value. + Thus, for example, the following: + + .IR "(size_t) (\-1)" . + + becomes: + + .IR "(size_t)\ \-1" . + +Various pages + mtk / Alain Portal + Replace "-" by "\-" where a real dash is required. + +Various pages + mtk + Make the formatting of instances of '*varname' consistent, changing + instances such as: + + .RI * varname + + to: + + .I *varname + +pciconfig_read.2 +nfsservctl.2 +bstring.3 +cpow.3 +getipnodebyname.3 +getpwnam.3 +getrpcent.3 +lsearch.3 +malloc_hook.3 +mpool.3 +stdin.3 +strtol.3 +strtoul.3 +unlocked_stdio.3 +regex.3 +sd.4 +resolv.conf.5 +utmp.5 +futex.7 + mtk + Format SYNOPSIS consistently. + +drand48.3 +drand48_r.3 +flockfile.3 +erf.3 +sigvec.3 +timeradd.3 +wprintf.3 + mtk, after a note by Alain Portal + Standardize sentence used under "Feature Test Macro Requirements" + when referring to all functions shown in the SYNOPSIS. + +get_kernel_syms.2 +getdents.2 +getitimer.2 +nanosleep.2 +query_module.2 +statvfs.2 +clock_getres.3 +getaddrinfo.3 +getgrent.3 +getipnodebyname.3 +console_ioctl.4 +tty_ioctl.4 +rtnetlink.7 + mtk + Indent structure definitions by +4n. + +recv.2 +btree.3 +dbopen.3 +ether_aton.3 +fts.3 +hash.3 +mpool.3 +profil.3 +rcmd.3 +recno.3 +rpc.3 +xdr.3 +console_ioctl.4 +ddp.7 +ip.7 +ipv6.7 +svipc.7 + mtk + Use C99 standard types in declarations. + s/u_long/unsigned long/ + s/ulong/unsigned long/ + s/u_char/unsigned char/ + s/u_short/unsigned short/ + s/ushort/unsigned short/ + s/u_int8_t/uint8_t/ + s/u_int16_t/uint16_t/ + s/u_int32_t/uint32_t/ + s/u_int/unsigned int/ + +exit_group.2 +fallocate.2 +getdents.2 +ioctl_list.2 +nfsservctl.2 +sched_setaffinity.2 +set_tid_address.2 +ustat.2 +argz_add.3 +confstr.3 +envz_add.3 +getline.3 +getpwnam.3 +gets.3 +getw.3 +inet_ntop.3 +inet_pton.3 +offsetof.3 +console_ioctl.4 +termcap.5 +ascii.7 +feature_test_macros.7 +netlink.7 +operator.7 +svipc.7 + mtk + Fix unbalanced .nf/.fi pairs. + +chmod.2 +getxattr.2 +listxattr.2 +lseek.2 +removexattr.2 +setxattr.2 +stat.2 +feature_test_macros.7 +fpathconf.3 +fopen.3 + + mtk + Rename argument: s/file*des/fd/ , since that is the name most + commonly used on man pages for a file descriptor argument. + +bindresvport.3 +des_crypt.3 +getopt.3 +getrpcent.3 +realpath.3 +rpc.3 +xdr.3 + mtk + Removed .SM macros. + +madvise.2 +getdirentries.3 +printf.3 +sigvec.3 + mtk + Remove extraneous .br macro before/after .SH/.SS. + +_syscall.2 +lookup_dcookie.2 +aio_cancel.3 +aio_error.3 +aio_fsync.3 +aio_read.3 +aio_return.3 +aio_write.3 +canonicalize_file_name.3 +envz_add.3 +getgrouplist.3 +getttyent.3 +key_setsecret.3 +mtrace.3 +tcgetpgrp.3 +tcgetsid.3 +ttyslot.3 +tty_ioctl.4 + mtk + Remove extraneous .sp macros. + +fcntl.2 +outb.2 +send.2 +syscalls.2 +getopt.3 +proc.5 +man-pages.7 +standards.7 +tcp.7 + mtk + Remove/replace extraneous .sp macros. + +Typographical or grammatical errors have been corrected in several places. + + +Changes to individual pages +--------------------------- + +_syscall.2 + mtk + Nowadays there are seven macros (see 2.74 change log also). + +arch_prctl.2 + mtk, Acked by Andi Kleen + Clarify interpretation of 'addr'; plus a few other minor edits + and updates. + +bind.2 + mtk + Minor rewrites. + +close.2 + mtk + Clarify relationship between file descriptor and open file + description. + +connect.2 + mtk, Acked by Andi Kleen + Since kernel 2.2, AF_UNSPEC for unconnecting a connected + socket *is* supported. + +execve.2 + Alain Portal + Minor rewordings. + +futimesat.2 + Alain Portal + Remove duplicate "#include " from SYNOPSIS. + +getgid.2 + mtk + Add getresgid(2) and credentials(7) to SEE ALSO. + +getpagesize.2 + mtk + Small rewording. + +getresuid.2 + mtk + Rewrote various parts. + +getuid.2 + mtk + Add getresuid(2) and credentials(7) to SEE ALSO. + +ioctl_list.2 + Alain Portal + Use proper tables for layout, and various formatting fixes. + mtk + Various formatting fixes. + +listen.2 + mtk + Rewrote various parts. + +mbind.2 + Andi Kleen / mtk / Alain Portal + Modify explanation of EINVAL 'maxnode' error. + +mmap.2 + mtk + Add comma to clarify meaning of a sentence. + +open.2 + mtk + Clarify initial description of O_EXCL. + Clarify description of behaviors of O_CREAT | O_EXCL + for symbolic links. + Clarify text describing use of lockfiles without O_EXCL. + mtk, with input from Timo Sirainen and Trond Myklebust + O_EXCL is supported on NFSv3 and later, with Linux 2.6 and later. + +pipe.2 + mtk + Rename 'filedes' argument 'pipefd'. + +pivot_root.2 + mtk + s/cwd/current working directory/ + +seteuid.2 + mtk + Minor changes. + +setpgid.2 + mtk + Add credentials(7) to SEE ALSO, and updated copyright credits, + to reflect my rewrite of a few months ago. + +setsid.2 + mtk + Add getsid(2) and credentials(7) to SEE ALSO. + +spu_create.2 + Alain Portal / mtk; acked by Jeremy Kerr + Minor formatting/wording changes. + mtk + Put EPERM in right alphabetical position in ERRORS list. + +argz_add.3 + mtk + Formatting fixes. + +atexit.3 + mtk + Minor changes to example program. + +cerf.3 + mtk + These functions are still not present as at glibc 2.7. + +dbopen.3 + Alain Portal / mtk + Various minor spelling and formatting fixes. + +envz_add.3 + mtk + Formatting fixes. + +fexecve.3 + mtk + Fix placement of feature test macro in SYNOPSIS. + +fmax.3 +fmin.3 + mtk + Small rewording. + +getline.3 + mtk + Minor changes to example program. + +getrpcent.3 +getrpcport.3 + mtk + Use modern C prototypes in SYNOPSIS. + +getutent.3 + Alain Portal / mtk + Formatting fixes. + +mbsnrtowcs.3 +mbsrtowcs.3 +mbstowcs.3 + mtk + Use .IP tags to create properly formatted lists. + +rpc.3 + mtk + Convert function declarations to use modern C prototypes. + Add text and start of page describing header files + and types required by functions. + Reformat discussion of request under clnt_control(). + +xdr.3 + mtk + Convert function declarations to use modern C prototypes. + Remove crufty "int empty" from xdrrec_eof() description. + +console_codes.4 + Phil Endecott + Relocate misplaced line: + "and if LF/NL (new line mode) is set also a carriage return;" + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=458338. + +console_ioctl.4 + mtk + Formatting fixes. + +bootparam.7 + mtk, after a note by Alan Portal + Fix reference to kernel documentation source file in the + "The Sound Driver" subsection. + +man-pages.7 + Alain Portal + Move CONFIGURATION description after SYNOPSIS description. + mtk / Alain Portal + Note that header files should be surrounded by angle brackets (<>). + +posixoptions.7 + mtk + Minor formatting and wording fixes. + +rtnetlink.7 + Andreas Henriksson + Fix description of RTM_F_EQUALIZE. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=458325. + +signal.7 + mtk + Minor formatting and wording fixes. + +socket.7 + mtk + Small rewording of discussion of O_ASYNC. + +spufs.7 + mtk / Jeremy Kerr / Alain Portal + s/SPE/SPU/ + + +==================== Changes in man-pages-2.76 ==================== + +Released: 2008-01-14 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Carlo Marcelo Arenas Belon +Jeremy Kerr +Sam Varshavchik +Trond Myklebust + +Apologies if I missed anyone! + + +Global changes +-------------- + +longjmp.3 +printf.3 +scanf.3 +setbuf.3 +setjmp.3 +sk98lin.4 +environ.7 + mtk + Rework/remove use of ".ad" macros. + +ioctl_list.2 +mlock.2 +mprotect.2 +mremap.2 +syslog.2 +cfree.3 +mpool.3 +offsetof.3 +rpc.3 +stdin.3 + mtk + Fix unbalanced quotes in formatting macros. + +ftok.3 + mtk + s/i-node/inode/, for consistency with other pages and POSIX.1-2001. + +Typographical or grammatical errors have been corrected in several places. + + +Changes to individual pages +--------------------------- + +chown.2 + mtk + Minor wording change. + +dup.2 + mtk + Reordered text in DESCRIPTION and added some details for dup2(). + +open.2 + Trond Myklebust / mtk + Minor fix to O_EXCL changes in previous release. + +gettid.2 + mtk + Rewrote DESCRIPTION; noted that thread ID is not the same + thing as a POSIX thread ID. + +pipe.2 + mtk + Rewrote DESCRIPTION; minor additions to EXAMPLE text. + +umask.2 + mtk + A few rewrites and additions. + +strptime.3 + Carlo Marcelo Arenas Belon / mtk + Add "#define _XOPEN_SOURCE" to example program. + +initrd.4 + mtk + Use quotes more consistently in formatting macros. + +random.4 + mtk, after a report by Daniel Kahn Gilmor + Add 2.6 details for /proc/sys/kernel/random/poolsize. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=459232. + +pthreads.7 + mtk + Minor changes. + +spufs.7 + mtk / Jeremy Kerr + Define abbreviation "MSS". + + +==================== Changes in man-pages-2.77 ==================== + +Released: 2008-01-31 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Pavel Heimlich +Phil Endecott +Thomas Huriaux +Vincent Lefevre +WANG Cong + +Apologies if I missed anyone! + + +Global changes +-------------- + +stdarg.3 +bootparam.7 + Thomas Huriaux + Fix broken use of single quotes at start of line, + as per: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=462636 + +Typographical or grammatical errors have been corrected in several places. + +New pages +--------- + +remove_COLOPHON.sh + mtk + Script to remove the COLOPHON section from the man pages provided + as command-line arguments. This is useful to remove the COLOPHON + sections from all of the man pages in two different release trees + in order to do a "diff -ruN" to see the "real" differences + between the trees. + + +Changes to individual pages +--------------------------- + +fcntl.2 + mtk + Replace tables with .TP macros. + +fork.2 + mtk + Added discussion of directory streams. + Removed "#include " from SYNOPSIS. + Changed authorship notice. + +futex.2 + mtk + Add ENOSYS error to errors. + Phil Endecott + Explicitly describe return value in the event of an error. + +inotify_add_watch.2 + mtk + Minor wording changes. + +splice.2 + WANG Cong + Fix types for 2 and 4 arguments in splice prototype. + +wait.2 + Phil Endecott + Clarify description of return value for WNOHANG. + +tkill.2 + mtk + Rewrote DESCRIPTION; emphasized that tkill() is obsoleted by + tgkill(). + +alloca.3 + mtk + Change description in NAME section. + Various rewrites and additions (including notes on longjmp() and + SIGSEGV). + mtk / Vincent Lefevre + Weaken warning against use of alloca(), and + point out some cases where it can be useful; + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=461100. + +bootparam.7 + Pavel Heimlich + Remove junk line. + +inotify.7 + mtk + Replace tables with .TP macros. + s/MultiSource Synchronization/MultiSource Synchronization (MSS)/ + + +==================== Changes in man-pages-2.78 ==================== + +Released: 2008-02-15 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Davide Libenzi +Greg Banks +Michael Tokarev +Phil Endecott + +Apologies if I missed anyone! + + +Global changes +-------------- + +sigaction.2 +signal.2 +sigwaitinfo.2 +signal.7 + mtk + Add SEE ALSO entry referring to new signalfd.2 page. + +Typographical or grammatical errors have been corrected in several places. + + +New pages +--------- + +eventfd.2 + mtk, with input and review from Davide Libenzi + Documents the eventfd() system call, new in 2.6.22. + +signalfd.2 + mtk, with input and review from Davide Libenzi + Documents the signalfd() system call, new in 2.6.22. + +Changes to individual pages +--------------------------- + +futex.2 + mtk / Phil Endecott + Improve wording describing error returns. + +open.2 + Greg Banks + Greatly expand the detail on O_DIRECT. + +reboot.2 + mtk / Michael Tokarev + Fix RETURN VALUE description: in some cases reboot() does not + return. + mtk + Rename the 'flag' argument to 'cmd', since that is more meaningful, + and also what is used in the kernel source. + Other minor wording changes. + + +==================== Changes in man-pages-2.79 ==================== + +Released: 2008-03-07 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries E. Brouwer +Chris Heath +Davide Libenzi +Fernando Luis Vázquez Cao +Heikki Orsila +Jeremy Kerr +Justin Pryzby +Lasse Kärkkäinen +Michael Haardt +Mike Frysinger +Ron Burk +Sam Varshavchik +Samuel Thibault +Walter Harms + +Apologies if I missed anyone! + + +Global changes +-------------- + +Typographical or grammatical errors have been corrected in several places. + + +New pages +--------- + +timerfd_create.2 + mtk, with input and review from Davide Libenzi + Documents the timerfd_create(), timerfd_settime(), and + timerfd_gettime() system calls, which are new in 2.6.25. + + +New links +--------- + +timerfd_gettime.2 +timerfd_settime.2 + mtk + Links to new timerfd_create.2 page. + +eventfd_read.3 +eventfd_write.3 + mtk + Links to eventfd.2. + + +Changes to individual pages +--------------------------- + +Makefile + aeb + Remove code relating to man1/README, which no longer exists. + +execve.2 + mtk + Clarify detail of RLIMIT_STACK/4 limit for argv+environ. + +getitimer.2 + mtk + Added SEE ALSO entry referring to timerfd_create.2. + +getrusage.2 + mtk + Minor rewordings. + +open.2 + Michael Haardt + Move discussion of 'mode' argument under description of O_CREAT. + +signalfd.2 + mtk + Fix type for 'ssi_ptr' field. + See http://sources.redhat.com/ml/libc-hacker/2008-01/msg00002.html. + +syscalls.2 + mtk + Add timerfd_create(), timerfd_settime(), and timerfd_gettime() + to list. + +syslog.2 + Jeremy Kerr + Add info on command type 10. + Add details on types 6, 7, 8, and 9. + Minor grammar fix. + mtk + Update LOG_BUF_LEN details. + Update RETURN VALUE section. + Notes capability requirements under EPERM error. + Minor fix to description of type==3 and type==4. + Other minor edits. + +ctime.3 + Walter Harms + Note that POSIX requires localtime() to act as though tzset() + was called, but localtime_r() does not have the same requirement. + See also http://thread.gmane.org/gmane.comp.time.tz/2034/ + +getaddrinfo.3 + mtk + Clarify discussion of NULL 'hints' argument; other minor rewrites. + mtk / Sam Varshavchik + Remove some duplicated text. + +malloc.3 + Lasse Kärkkäinen / Mike Frysinger / mtk + Clarify description of realloc() behavior for + ((size == 0) && (ptr != NULL)). + +posix_fallocate.3 + Samuel Thibault + s/stdlib.h/fcntl.h/ in SYNOPSIS. + +proc.5 + Fernando Luis Vázquez Cao + Update /proc/[number]/cmdline description. + It used to be true that the command line arguments were + not accessible when the process had been swapped out. + In ancient kernels (circa 2.0.*) the problem was that the + kernel relied on get_phys_addr to access the user space buffer, + which stopped working as soon as the process was swapped out. + Recent kernels use get_user_pages for the same purpose and thus + they should not have that limitation. + +epoll.7 + Davide Libenzi / mtk + Clarify the somewhat unintuitive behavior that occurs if a file + descriptor in an epoll set is closed while other file descriptors + referring to the same underlying open file description remain + open. + See also http://thread.gmane.org/gmane.linux.kernel/596462/. + mtk + Clarify error that occurs if we add an epoll fd to its own set. + mtk + A few minor rewordings. + mtk, after a note by Chris Heath + Rework Q1/A1, describing what happens when adding the same + file descriptor twice to an epoll set, and when adding duplicate + file descriptors to the same epoll set. + Heikki Orsila / mtk / Davide Libenzi + Clarify Q9/A9 to discuss packet/token-oriented files. + mtk, after comments by Davide Libenzi and Chris Heath + Added Q0/A0, making explicit that the key for items in an epoll + set is [file descriptor, open file description]. + mtk, after a note by Ron Burk + Change A3, to note that when events are available, + the epoll file descriptor will indicate as being readable. + mtk + Add some further explanation to Q5/A5 about why an epoll file + descriptor cannot be passed across a Unix domain socket. + +posixoptions.7 + mtk + Add SEE ALSO entry for standards(7). + +regex.7 + mtk + Add grep(1) to SEE ALSO. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=348552. + +standards.7 + mtk + Add SEE ALSO entry for posixoptions(7). + +time.7 + mtk + Added SEE ALSO entry referring to timerfd_create.2. + + +==================== Changes in man-pages-2.80 ==================== + +Released: 2008-06-05 + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Adrian Bunk +Alain Portal +Andreas Herrmann +Andrew Morton +Andries E. Brouwer +Anoop +Aurelien Gerome +Daniel Burr +Davide Libenzi +Felix Kater +Folkert van Heusden +Hamaji Shinichiro +Heikki Orsila +Ingo Molnar +Justin Pryzby +Karsten Weiss +Martin Pitt +Marty Leisner +Nicolas François +Nick Piggin +Petter Reinholdtsen +Reuben Thomas +Sam Varshavchik +Stuart Brady +Theodoros V. Kalamatianos +Thomas Huriaux +Tim Stoakes +Timothy Baldwin +Tolga Dalman + +Apologies if I missed anyone! + + +Global changes +-------------- + +bdflush.2 +inotify_add_watch.2 +mprotect.2 +sigprocmask.2 +ctime.3 +getusershell.3 +setbuf.3 +st.4 +ip.7 +packet.7 + mtk + Replace "(il)legal" by "(not) permitted" or "(in)valid". + +read.2 +utime.2 +filesystems.5 +packet.7 + mtk + s/time stamp/timestamp/, for consistency with majority use + in other pages, and in POSIX.1. + +madvise.2 +mbind.2 +mincore.2 +mmap.2 +mmap2.2 +msync.2 +remap_file_pages.2 + mtk + Change name of 'start' argument to 'addr' for consistency + with: + * other memory-related interfaces + * POSIX specification (for those interfaces in POSIX) + * Linux and glibc source code (in at least some cases) + +Various pages + mtk + s/filesystem/file system/, for consistency with majority use + in other pages, and in POSIX.1. + +Various pages + mtk + s/zeroes/zeros/, for consistency with majority use + in other pages, and in POSIX.1. + +abs.3 +proc.5 + mtk + s/builtin/built-in/, for consistency with majority use + in other pages, and in POSIX.1. + +mknod.2 +ftw.3 + mtk + s/normal file/regular file/ + +Various pages + mtk + s/nonempty/non-empty/ + +Various pages + mtk + s/nonzero/non-zero/ + +Various pages + mtk + s/realtime/real-time/, for consistency with majority usage. + +Various pages + mtk + s/command line/command-line/ when used attributively. + +Various pages + mtk + Use "run time" when non-attributive, "run-time" when attributive. + +Various pages + mtk + Various pages that I wrote carried a slightly modified version + of the "verbatim" license. In the interests of minimizing + license proliferation, I've reverted the modified form + so that the license is exactly the same as on other pages + carrying the verbatim license. + +epoll_ctl.2 +getitimer.2 +getrlimit.2 +unix.7 + mtk + s/since kernel x.y.z/since Linux x.y.z/ + +wait.2 +inotify.7 + mtk + Reformat kernel version information for flags. + +Typographical or grammatical errors have been corrected in several places. +(Special thanks to Nicolas François.) + + +New pages +--------- + +random_r.3 + mtk, after a suggestion by aeb + Documents random_r(3), srandom_r(3), initstate_r(3), and + setstate_r(3), which are the reentrant equivalents of + random(3), srandom(3), initstate(3), and setstate(3). + + +New links +--------- + +lutimes.3 + mtk + Link to futimes.3. + +initstate_r.3 +setstate_r.3 +srandom_r.3 + mtk + Links to random_r.3. + +daylight.3 +timezone.3 +tzname.3 + mtk + Links to tzset.3. + +isnanf.3 +isnanl.3 + mtk + Links to finite.3. + +encrypt_r.3 +setkey_r.3 + mtk + Links to encrypt.3. + + +Changes to individual pages +--------------------------- + +clone.2 + mtk + Added note that CLONE_STOPPED (which no-one uses anyway) is + now deprecated. + +epoll_create.2 + mtk + Add NOTES section pointing out that 'size' argument is unused + since kernel 2.6.8. + +epoll_ctl.2 + mtk + Added portability note to BUGS text for EPOLL_CTL_DEL. + +epoll_wait.2 + mtk + If the 'sigmask' is NULL, then epoll_pwait() is equivalent + to epoll_wait(). + +fork.2 + mtk + NOTES: since glibc 2.3.3, the glibc NPTL fork() wrapper + bypasses the fork() system call to invoke clone() with + flags providing equivalent functionality. + +futex.2 + mtk, after a note from Adrian Bunk + FUTEX_FD has been removed, as of kernel 2.6.26. + +futimesat.2 + mtk + Note that this system call is made obsolete by utimensat(2). + +getgroups.2 + Petter Reinholdtsen + SEE ALSO: Add getgrouplist(3). + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=479284. + mtk + NGROUPS_MAX increased in kernel 2.6.4. + SEE ALSO: Add credentials(7). + mtk + Reformat DESCRIPTION and RETURN VALUE sections to be more + consistent with man-pages style. + Add some more detail to descriptions of system calls. + Clarified what happens if caller of getgroups() is a member of + more than 'size' supplementary groups. + ERRORS: Add ENOMEM. + +getpriority.2 + mtk, after a note from Ingo Molnar + Add text in NOTES about the punchier effect of nice values in + kernel 2.6.23 and later. + Add Documentation/scheduler/sched-nice-design.txt to SEE ALSO list. + +gettid.2 + mtk + Added VERSIONS section noting that this system call first + appeared in 2.4.11. + +kill.2 + Marty Leisner / mtk + Add text explicitly noting that sig==0 can be used to check for + the existence of a PID or PGID. + mtk + A few minor rewordings. + +mbind.2 + mtk + The location of the numactl package has changed. + +mmap.2 + mtk + Added some .SS headings to make structure of page a little + more obvious. + mtk, with input from Nick Piggin + MAP_POPULATE supports both file and anonymous mappings. + Since 2.6.23, MAP_POPULATE supports private mappings. + Since 2.6.23, MAP_NONBLOCK causes MAP_POPULATE to be a no-op. + mtk + NOTES: Added details on mapping address that is selected by + kernel when MAP_FIXED is / isn't specified. + +mount.2 + mtk + The MS_REMOUNT changes in 2.4 were at 2.4.10 (not 2.4). + mtk + Minor wording change. + +msgctl.2 + mtk + Clarify that "unused" fields in msginfo structure are + "unused within the kernel". + msginfo.msgpool is measured in kilobytes, not bytes. + Minor rewordings in comments for msginfo structure. + +msgop.2 + mtk + Various minor rewordings and restructurings for clarity. + mtk, after a note from Reuben Thomas + Remove "msgop" from NAME section. + +mkdir.2 + mtk + Clarify meaning of "BSD group semantics". + SEE ALSO: add chown(2). + +mknod.2 + mtk + SEE ALSO: add chown(2) and chmod(2). + +mmap.2 + mtk + SEE ALSO: add mprotect(2) and shmat(2). + +mprotect.2 + Hamaji Shinichiro + SYNOPSIS: s/size_t \*len/size_t len/ + +open.2 + mtk + Note that O_CLOEXEC should be in the next POSIX.1 revision. + mtk + More than just ext2 supports "mount -o bsdgroups" nowadays, + so make the discussion about group ownership of new files a bit + more generic. + mtk + SEE ALSO: add chown(2) and chmod(2). + +poll.2 + mtk + If the 'sigmask' is NULL, then ppoll() is equivalent to poll() + with respect to signal mask manipulations. + +posix_fadvise.2 + mtk + s/posix_madvise (2)/posix_madvise (3)/; + (The referred-to page still doesn't exist yet, but hopefully + will do sometime soon.) + +ptrace.2 + Anoop, Acked by Roland McGrath. + Re PTRACE_PEEKUSER: the offsets and data returned might not + match with the definition of struct user. + See also http://lkml.org/lkml/2008/5/8/375 + +recv.2 + Felix Kater / mtk + Improve wording for EAGAIN error in discussion of MSG_DONTWAIT. + +rmdir.2 + Martin Pitt + POSIX.1 also allows EEXIST for the ENOTEMPTY error condition. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=467552. + +sched_setscheduler.2 + mtk, with input from Ingo Molnar + Add description of SCHED_IDLE policy (new in 2.6.23). + Tweak description of SCHED_BATCH. + Minor rewordings. + +select_tut.2 + Justin Pryzby + Various wording clean-ups. + +semctl.2 + mtk + Clarify that "unused" fields in seminfo structure are + "unused within the kernel". + Minor rewordings in comments for seminfo structure. + +semop.2 + Aurelien Gerome + Small fix in example code. + +setpgid.2 + mtk / Karsten Weiss + Clarify description of setpgid() a little. + +shmctl.2 + mtk + Clarify that "unused" fields in shminfo structure are + "unused within the kernel". + Minor rewordings in comments for shminfo structure. + +shmop.2 + mtk, after a note from Reuben Thomas + Remove "shmop" from NAME section. + +signalfd.2 + mtk + Added BUGS text noting that before kernel 2.6.25, the ssi_int + and ssi_ptr fields are not set. + Added comments describing fields in signalfd_siginfo structure. + Update field names in example program (s/signo/ssi_signo/). + Various small fixes, and remove duplicated sentence. + Minor edits to structure definition. + +sigqueue.2 + mtk + Added some comments to code in NOTES. + +stat.2 + mtk + Minor wording change. + +symlink.2 + mtk + SEE ALSO: add lchown(2). + +sync_file_range.2 + mtk / Andrew Morton + Remove statement that (SYNC_FILE_RANGE_WAIT_BEFORE | + SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER) is + a traditional fdatasync(2) operation. + See https://bugzilla.mozilla.org/show_bug.cgi?id=421482 + comments 129 to 131. + +syscalls.2 + mtk + This page is now up to date as at kernel 2.6.25. + +syslog.2 + mtk + Small tidy up of language relating to permissions/capabilities. + +timerfd_create.2 + mtk + Minor change to example program. + Minor wording change. + +utime.2 + Reuben Thomas + Remove unnecessary subheading for utimes(). + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=477402. + mtk + Change description in NAME line ("or" is not correct: these calls + always change *both* timestamps). + CONFORMING TO: utimes() is in POSIX.1-2001. + mtk + Rename 'buf' argument of utime() to 'times' (like utimes()). + Clarify explanation of EACCES and EPERM errors. + Remove BUGS section, since it doesn't seem to add useful + information. + Clarified discussion of capabilities, and noted that + CAP_DAC_OVERRIDE also has a role. + Other minor rewordings. + +wait.2 + mtk, after a note by Justin Pryzby + Add a sentence clarifying that even though the default disposition + of SIGCHLD is "ignore", explicitly setting the disposition to + SIG_IGN results in different treatment of zombies. + +aio_cancel.3 +aio_error.3 +aio_fsync.3 +aio_read.3 +aio_return.3 +aio_suspend.3 +aio_write.3 + Kevin O'Gorman + Add "Link with -lrt" to SYNOPSIS. + +backtrace.3 + Nicolas François + s/backtrace_symbols/backtrace_symbols_fd/ in one sentence. + mtk + Fix bogus reference to variable 'strings': should be: + "the array of pointers". + +ctime.3 + mtk + Add warning under NOTES that asctime(), ctime(), gmtime(), and + localtime() may each overwrite the static object returned by any + of the other calls. + Other minor edits. + +dlopen.3 + mtk + Add more detail to the description of the fields in the + structure returned by dladdr(). + +fexecve.3 + mtk + Clean up SYNOPSIS after work by cut-and-paste-Pete: + the necessary header file is not ! + +futimes.3 + mtk + Add documentation of lutimes(), which appeared in glibc 2.6. + mtk + Change description in NAME line ("or" is not correct: these calls + always change *both* timestamps). + CONFORMING TO: futimes() did not come from 4.2BSD. (It came from + FreeBSD; see the FreeBSD man page.) + +getenv.3 + mtk + Noted that caller must not modify returned value string. + Noted that getenv() is not reentrant: the buffer may be statically + allocated and overwritten by later calls to getenv(), putenv(), + setenv(), or unsetenv(). + Other minor rewrites. + +getgrent.3 + Petter Reinholdtsen + SEE ALSO: Add getgrouplist(3). + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=479284. + +gethostbyname.3 + mtk + Add 'h_errno' to NAME list. + +getopt.3 + mtk + Add 'optarg', 'optind', 'opterr', and 'optopt' to NAME section. + Add subheading for getopt_long() and getopt_long_only() + description. + +getpt.3 + mtk + Point out that this function should be avoided in favor of + posix_openpt(). + Add ERRORS section referring to open(2). + +getsubopt.3 + Daniel Burr + SYNOPSIS: Fix declaration of valuep. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=476672. + +malloc.3 + mtk + RETURN VALUE: Note circumstances in which successful malloc() and + calloc() can return NULL. + +mq_open.3 + mtk, after a note by Marty Leisner + Note that is needed for O_* constants and + is needed for 'mode' constants. + +opendir.3 + mtk + Describe treatment of close-on-exec flag by opendir() and + fdopendir(). + +openpty.3 + mtk + SEE ALSO: add ttyname(3). + +raise.3 + mtk / Timothy Baldwin + Clarify semantics of raise() when called from a multithreaded + program. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=476484. + mtk + Rewrites and additions to various parts of the page. + +rand.3 + Tolga Dalman / aeb / mtk + Remove outdated warning in NOTES; encourage the use of + random(3) instead. + Folkert van Heusden + Clarify wording describing range of values returned by rand(). + +random.3 + aeb / mtk / Tolga Dalman + Recommend use or random_r(3) for multithreaded applications + that need independent, reproducible sequences of random numbers. + + Move references to "The Art of Computer Programming" and + "Numerical Recipes", formerly in rand(3), to this page. + + Add drand48(93) to SEE ALSO list. + +regex.3 + Heikki Orsila + Clarify description of 'rm_eo' field. + +sem_open.3 + mtk, after a note by Marty Leisner + Note that is needed for O_* constants and is + needed for 'mode' constants. + +sem_post.3 + mtk + Added pointer to example in sem_wait(3). + +sem_close.3 +sem_destroy.3 +sem_getvalue.3 +sem_init.3 +sem_open.3 +sem_post.3 +sem_unlink.3 +sem_wait.3 + mtk, after a note from Marty Leisner + Add text to SYNOPSIS noting the need to link with "-lrt" or + "-pthread". + +setenv.3 + mtk + setenv() copies 'name' and 'value' (contrast with putenv()). + unsetenv() of a nonexistent variable does nothing and is + considered successful. + Noted that setenv() and unsetenv() need not be reentrant. + +shm_open.3 + mtk, after a note by Marty Leisner + Note that is needed for O_* constants and is + needed for 'mode' constants. + +undocumented.3 + mtk + initstate_r(3), setkey_r(3), setstate_r(3) are now documented. + +utmp.5 + Nicolas François + Small rewording. + +resolv.conf.5 + Nicolas François + gethostname() is in Section 2, not section 3. + +ascii.7 + Stuart Brady + Fix rendering of ' (backtick) and apostrophe (') in tables + +charsets.7 + Nicolas François + s/unicode.com/unicode.org/ + +credentials.7 + mtk + NOTES: Pthreads requires that all threads share the same UIDs and + GIDs. But the Linux kernel maintains separate UIDs and GIDs for + every thread. NPTL does some work to ensure that credential + changes by any thread are carried through to all POSIX threads in + a process. + mtk + sysconf(_SC_NGROUPS_MAX) can be used to determine the number of + supplementary groups that a process may belong to. + Clarify that supplementary group IDs are specified in POSIX.1-2001. + +epoll.7 + mtk, after a note from Sam Varshavchik + For answer A2, change "not recommended" to "careful programming + may be required". + +inotify.7 + mtk + Document SIGIO feature (new in 2.6.25) for inotify file descriptors. + mtk + Note that select()/poll()/epoll_wait() indicate a ready inotify + file descriptor as readable. + mtk + Document IN_ATTRIB in a little more detail. + +pthreads.7 + Justin Pryzby + Grammar fix, plus fix typo in script. + mtk + Add list of thread-safe functions. + +standards.7 + mtk + Add a section on the upcoming POSIX revision. + +ld.so.8 + Justin Pryzby / mtk + Various wording improvements. + + +==================== Changes in man-pages-3.00 ==================== + +Released: 2008-06-12, Konolfingen + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries Brouwer +Stuart Brady + +Apologies if I missed anyone! + + +Global changes +-------------- + +The POSIX.1 man pages (sections 0p, 1p, 3p) have been moved out +of this package into the separate man-pages-posix package. +This made sense because those pages are seldom changed (only formatting +fixes, etc.) so that it was unnecessary to redistribute them with each +man-pages release. + + +console_codes.4 +random.4 +dir_colors.5 +proc.5 +glob.7 + Stuart Brady + s/`/\`/ for backquotes used in command substitution, for + proper rendering in UTF-8. + +Various pages + mtk, after a note from Stuart Brady + Using /'x'/ to denote a character (string) renders poorly in + UTF-8, where the two ' characters render as closing single + quotes. On the other hand, using /`x'/ renders nicely on UTF-8, + where proper opening and closing single quotes are produced by + groff(1), but looks ugly when rendered in ASCII. Using the + sequence /\\aqx\\aq/ produces a reasonable rendering ('\\aq' + is a vertical "apostrophe quote") in both UTF-8 and ASCII. + So that change is made in a number of pages. + See also http://www.cl.cal.ac.uk/~mgk25/ucs/quotes.html. + +Various pages + mtk + Replace form /`string'/ by /"string"/, since the former renders + poorly in ASCII. + +termios.3 +console_codes.4 +tty_ioctl.4 +termcap.5 +charsets.7 + mtk + Control character names (^X) are written boldface, without + quotes. + +printf.3 +scanf.3 +proc.5 +glob.7 +regex.7 + mtk + Various edits to try and bring some consistency to the use of + quotes. + + +Changes to individual pages +--------------------------- + +tty_ioctl.4 + mtk + Small rewordings in description of packet mode. + +locale.7 + mtk + Minor formatting fixes. + + +==================== Changes in man-pages-3.01 ==================== + +Released: 2008-06-25, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andreas Herrmann +Andrew P +Andrew Clayton +Bart Van Assche +Christian Borntraeger +Christoph Hellwig +Daniele Giacomini +Dorin Lazar +George Spelvin +Jason Englander +Jeff Moyer +Laurent Vivier +Masatake YAMOTO +Matt Mackall +Neil Horman +Pavel Machek +Peter Zijlstra +Petr Baudis +Petr Gajdos +Roman Zippel +Sam Varshavchik +Samuel Thibault +Stephane Chazelas +Stuart Cunningham +Thomas Gleixner +Tolga Dalman +Yao Zhao +WANG Cong + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +acct.5 + mtk + A complete rewrite of this page, now with much more detail. + +hostname.7 + mtk + A description of hostname resolution. Taken from FreeBSD 6.2, + and lightly edited for man-pages style. + +symlink.7 + mtk + A description of symbolic links. Taken from FreeBSD 6.2, but + heavily edited for Linux details, improved readability, and + man-pages style. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +getrlimit.2 + mtk / Peter Zijlstra + Add description of RLIMIT_RTTIME limit, new in 2.6.25. + +mkstemp.3 + mtk + Add description of mkostemp(), new in glibc 2.7. + +core.5 + mtk, after a note by Petr Gajdos; review by Neil Horman + Document core_pattern pipe syntax, which appeared in + kernel 2.6.19. + Add an example program demonstrating use of core_pattern + pipe syntax. + mtk + Document /proc/PID/coredump_filter, new in kernel 2.6.23. + Documentation was based on the text in + Documentation/filesystems/proc.txt, plus testing, and + checking the kernel source. + +proc.5 + mtk + Document /proc/PID/oom_score, which was new in kernel 2.6.11. + This file displays the "badness" score of the process, which + provides the basis for OOM-killer decisions. + mtk + Document /proc/PID/oom_adj, which was new in kernel 2.6.11. + This file influences the oom_score of a process. + mtk + Document /proc/PID/limits, which was new in 2.6.24. + This file displays a process's resource limits. + mtk + Document /proc/PID/fdinfo/*, which was new in 2.6.22. + These files display info about each descriptor opened by the + process: the current file offset, and the file access mode + + file status flags as set in open() or fcntl(F_SETFL). + mtk + Document /proc/PID/mountinfo, which was new in 2.6.26. + This file displays information about mount points. + Closely based on text from Documentation/filesystems/proc.txt. + mtk + Document /proc/PID/mountstats, which was new in 2.6.17. + This file displays statistics about mount points. + mtk + Document /proc/PID/status. + Samuel Thibault / mtk, review by Laurent Vivier, + Christian Borntraeger, and Andrew P + Document guest (virtual CPU) time field in /proc/stat. + Document guest (virtual CPU) time fields in /proc/PID/stat. + + +New links +--------- + +mkostemp.3 + mtk + Link to mkstemp.3. + +getcwd.2 + mtk + Link to getcwd.3, which describes several interfaces, among + them getcwd(), which is in fact a system call. + + +Global changes +-------------- + +sched_setaffinity.2 +sched_setscheduler.2 +set_mempolicy.2 +mbind.2 + mtk + SEE ALSO: Add cpuset(7). + +chown.2 +faccessat.2 +fchmodat.2 +fchownat.2 +fstatat.2 +getxattr.2 +link.2 +linkat.2 +listxattr.2 +open.2 +readlink.2 +removexattr.2 +rename.2 +setxattr.2 +stat.2 +symlink.2 +symlinkat.2 +unlink.2 +futimes.3 +remove.3 +path_resolution.7 + mtk + SEE ALSO: Add symlink(7). + +intro.1 +time.1 +fcntl.2 +gethostbyname.3 +ioctl_list.2 + mtk + Wrap source lines so that new sentence starts on new line. + +addseverity.3 +backtrace.3 +dlopen.3 +fmtmsg.3 +getnameinfo.3 +getpt.3 +grantpt.3 +makecontext.3 +ptsname.3 +tcgetsid.3 +unlockpt.3 +wordexp.3 + mtk + Added VERSIONS section. + +msgctl.2 +msgget.2 +semget.2 +semop.2 +pciconfig_read.2 +basename.3 +cmsg.3 +ftok.3 +console_ioctl.4 +tzfile.5 +mq_overview.7 +pty.7 + mtk + For consistency, "fix" cases where argument of .B or .I was + on the following source line. + +adjtimex.2 +getrusage.2 +io_getevents.2 +poll.2 +select.2 +semop.2 +sigwaitinfo.2 +aio_suspend.3 +clock_getres.3 +mq_receive.3 +mq_send.3 +sem_wait.3 +proc.5 + mtk + SEE ALSO: add time(7) + +Typographical or grammatical errors have been corrected in several places. +(Special thanks to Nicolas François and Alain Portal.) + + +Changes to individual pages +--------------------------- + +acct.2 + mtk + Add a few more words to DESCRIPTION. + NOTES: Add pointer to acct(5). + +alarm.2 + Alain Portal + s/process/calling process/ so as to say that the alarm signal is + delivered to the calling process. + +brk.2 + Yao Zhao / mtk + Clarify discussion of return value of sbrk(). + mtk + DESCRIPTION: Add some sentences giving an overview of these + interfaces. + Add note recommending use of malloc(3). + Change name of brk() argument to the simpler 'addr'. + Add "(void *)" cast to "-1" for error return of sbrk(). + Removed some incorrect text about "brk(0)". + Note that SUSv2 specified the return value of sbrk(). + Added a detail on the glibc brk() wrapper. + Remove discussions of old standards (C89 and POSIX.1-1990); + CONFORMING TO already discusses the situation with respect + to more recent standards. + +chmod.2 + mtk + Clarify description of chmod() and fchmod(). + Add further detail on S_ISUID, S_ISGID, and S_ISVTX permissions. + Reformat list of permissions bits. + +chown.2 + mtk + Describe rules governing ownership of new files (bsdgroups + versus sysvgroups, and the effect of the parent directory's + set-group-ID permission bit). + +chroot.2 + Alain Portal + Clarify description a little. + s/changes the root directory/ + changes the root directory of the calling process/ + +execve.2 + mtk + Fix text that warns against use of NULL argv and envp. + Using a NULL envp does in fact seem to be portable (works + on Solaris and FreeBSD), but the Linux semantics for a NULL + argv certainly aren't consistent with other implementations. + See http://bugzilla.kernel.org/show_bug.cgi?id=8408. + +getdents.2 + mtk, after a note from George Spelvin + Document d_type field, present since kernel 2.6.4. + Other minor edits. + +getitimer.2 + mtk + Noted that POSIX.1 leaves interactions with alarm(), sleep(), + and usleep() unspecified. + Linux 2.6.16 removed the MAX_SEC_IN_JIFFIES ceiling on timer + values. + Other minor changes. + +io_cancel.2 +io_destroy.2 +io_getevents.2 +io_setup.2 +io_submit.2 + mtk, after a note by Masatake YAMOTO and input from Jeff Moyer + Describe the unconventional error return provided by the + wrapper function in libaio (and contrast with behavior if + the system call is invoked via syscall(2)). + See http://thread.gmane.org/gmane.linux.ltp/4445/ + Alain Portal / mtk + Re-order ERRORS and SEE ALSO entries to be alphabetical. + +io_getevents.2 + Alain Portal + Small wording fix. + +io_submit.2 + Jeff Moyer + s/AIO request blocks/AIO control blocks/ + +mknod.2 + mtk + Note that EEXIST applies, even if the pathname is a + (possibly dangling) symbolic link. + +nanosleep.2 + mtk, after a report from Stephane Chazelas + Remove crufty discussion of HZ, and replace with a pointer + to time(7). + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=485636 + mtk, after some discussions with Bart Van Assche and Roman Zippel + NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP + See also http://thread.gmane.org/gmane.linux.kernel/696854/ + "nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?" + mtk + Replace mentions of "process' by "thread". + NOTES: describe case where clock_nanosleep() can be preferable. + Some minor rewrites. + +open.2 + mtk, after a note from Christoph Hellwig + NOTES: Note that access mode flags are not single bits, + and document the Linuxism "access mode 3". + See also http://thread.gmane.org/gmane.linux.kernel/653123. + +readdir.2 + mtk + Minor wording fixes. + +recv.2 + Alain Portal + Add comment to 'ee_pad' field in structure definition. + +sched_setscheduler.2 + mtk + Add pointer to discussion of RLIMIT_RTTIME in getrlimit.2. + mtk, after a note by Andrew Clayton + Rewrote and restructured various parts of the page for greater + clarity. + mtk + Add more detail to the rules that are applied when an + unprivileged process with a non-zero RLIMIT_RTPRIO limit + changes policy and priority. + SEE ALSO: Add Documentation/scheduler/sched-rt-group.txt + +sync_file_range.2 + Pavel Machek + SYNC_FILE_RANGE_WRITE can block on writes greater than request + queue size. For some background, see + http://thread.gmane.org/gmane.linux.kernel/687713/focus=688340 + +syscalls.2 + mtk + Added system call history back to version 1.2. + Fix typo on kernel version for pivot_root(). + +syslog.2 + WANG Cong + Document ENOSYS error, which can occur if kernel was built without + CONFIG_PRINTK. + +utime.2 + Nicolas François + Clarify description of 'times' array for utimes(). + +adjtime.3 + mtk + The longstanding bug that if delta was NULL, olddelta + didn't return the outstanding clock adjustment, is now fixed + (since glibc 2.8 + kernel 2.6.26). + http://sourceware.org/bugzilla/show_bug?id=2449 + http://bugzilla.kernel.org/show_bug.cgi?id=6761 + +dprintf.3 + mtk + Note that these functions are included in the next POSIX revision. + Remove editorial discussion about what the functions should have + been named. + +ftime.3 + mtk + Rewrote various pieces, and added some details. + +getaddrinfo.3 + mtk + Improve description or 'hints' and 'res' arguments. + Add details on numeric strings that can be specified for 'node'. + Other fairly major restructurings and rewrites to improve + logical structure and clarity of the page. + SEE ALSO: Add hostname(7). + +gethostbyname.3 + mtk + DESCRIPTION: Add reference to inet_addr(3) for dotted notation. + SEE ALSO: add inet(3). + mtk + Added BUGS section noting that gethostbyname() does not + recognize hexadecimal components in dotted address strings; + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973 + +getmntent.3 + mtk, after Stuart Cunningham pointed out the typo + Remove statement that LSB deprecates the functions + "endmntent(), setmntent() [sic] and setmntent()". + This doesn't seem to be true (I can't find mention of it + being deprecated in any of the LSB specs). Rather, LSB simply + doesn't specify these functions. (LSB 1.3 had a spec of + setmntent(), but not getmntent() or endmntent(), and noted + that having a spec of setmntent() was of little use without + also having a spec of getmntent().) + See also https://lists.linux-foundation.org/pipermail/lsb-discuss/2006-October/003078.html + +getnameinfo.3 + Tolga Dalman + Remove mention of sa_len field from example code. + That field is a BSDism not present on Linux. + mtk + Various minor changes. + +inet.3 + mtk / Stephane Chazelas + inet_aton() is *not* in POSIX.1. + Rewrote discussion of why inet_addr() is disfavored. + SEE ALSO: Add getaddrinfo(3). + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482979. + mtk, after a note by Stephane Chazelas + Describe the various address forms supported by inet_aton(). + mtk + Rewrite description of inet_network(). + Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr(). + Add discussion of Classful Addressing, noting that it is obsolete. + Added an EXAMPLE program. + mtk + Relocate discussion of i386 byte order to NOTES. + Note that inet_aton() returns an address in network byte order. + SEE ALSO: Add byteorder(3) and getnameinfo(3). + +inet_ntop.3 + mtk + Remove unneeded header files from SYNOPSIS. + SEE ALSO: Add inet(3) and getnameinfo(3). + Make NAME line more precise. + Move errors to an ERRORS section. + Add EXAMPLE section pointing to inet_pton(3). + +inet_pton.3 + mtk / Stephane Chazelas + Remove statement that inet_pton() extends inet_ntoa(); + that's not really true, since inet_pton() doesn't support + all of the string forms that are supported by inet_ntoa(). + SEE ALSO: Add getaddrinfo(3). + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482987. + mtk + Describe IPv6 address formats. + Describe dotted decimal format in more detail. + Add an example program. + mtk + Remove unneeded header files from SYNOPSIS. + Make NAME line more precise. + Make description of return value more precise. + SEE ALSO: Add inet(3). + +mkfifo.3 + mtk + Note that EEXIST applies, even if the pathname is a + (possibly dangling) symbolic link. + +mkstemp.3 + mtk + Fix discussion of O_EXCL flag. + These functions may also fail for any of the errors described + in open(2). + Various other rewordings. + +readdir.3 + mtk + Document DT_LNK (symbolic link) for d_type field. + Reorder DT_ entries alphabetically. + +remainder.3 + mtk + Recommend against drem(), in favor of remainder(). + +scanf.3 + mtk, after a note from Stephane Chazelas + Add an ERRORS section documenting at least some of the errors + that may occur for scanf(). + See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=487254. + mtk, after a note from Stephane Chazelas; review by Stephane Chazelas + Document the GNU 'a' modifier for dynamically allocating strings. + See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=487254. + Document the GNU 'm' modifier for dynamically allocating strings. + +strcat.3 + Andreas Herrmann + s/strcat/strncat/ (a typo that changed the semantics in + DESCRIPTION). + +strerror.3 + mtk, after a note from Daniele Giacomini + Modify SYNOPSIS to show prototypes of both versions of strerror_r(), + and make other small clarifications of the description regarding + the two versions. + +random.4 + George Spelvin (taking time out from his busy Broadway schedule), + with some tweaks by Matt Mackall and mtk + Add a Usage subsection that recommends most users to use + /dev/urandom, and emphasizes parsimonious usage of + /dev/random. + +locale.5 + Petr Baudis + LC_TIME: Describe first_weekday and first_workday. + +proc.5 + mtk + The various CPU time fields in /proc/stat and /proc/PID/stat + return time in clock ticks (USER_HZ, cputime_to_clock_t(), + sysconf(_SC_CLK_TCK)). + Updated, clarified and expanded the description several + fields in /proc/[number]/stat. + mtk + Clarified and expanded the description of /proc/[number]/fd. + mtk + Updated and clarified the description of /proc/[number]/statm. + mtk + Updated and clarified the description of /proc/sys/fs/dentry-state. + mtk + Many formatting, wording, and grammar fixes. + +man-pages.7 + mtk + Enhanced description of VERSIONS section. + +mq_overview.7 + mtk + Note that Linux does not currently support ACLs for POSIX + message queues. + +sem_overview.7 + mtk + Note that Linux supports ACLs on POSIX named semaphores + since 2.6.19. + +time.7 + mtk, with some suggestions from Bart Van Assche and Thomas Gleixner + Added some details about where jiffies come into play. + Added section on high-resolution timers. + Mentioned a few other time-related interfaces at various + points in the page. + See http://thread.gmane.org/gmane.linux.kernel/697378. + +unix.7 + mtk, after a note by Samuel Thibault + Provide a clear description of the three types of address that + can appear in the sockaddr_un structure: pathname, unnamed, + and abstract. + + +==================== Changes in man-pages-3.02 ==================== + +Released: 2008-07-02, Konolfingen + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andries Brouwer +Reuben Thomas +Sam Varshavchik +Stephane Chazelas +WANG Cong + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +clock_nanosleep.2 + mtk + A description of the clock_nanosleep() system call, + which was added in kernel 2.6. + +getgrouplist.3 + mtk + A near complete rewrite, including additional information and + a new example program. + +getutmp.3 + mtk + Documents getutmp(3) and getutmpx(3). + +gnu_get_libc_version.3 + mtk + Documents gnu_get_libc_version(3) and gnu_get_libc_release(3). + +sigwait.3 + mtk + Documents sigwait(3). + +shm_overview.7 + mtk + An overview of the POSIX shared memory API. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +updwtmp.3 + mtk + Document updwtmpx(3). + + +New links +--------- + +getutmpx.3 + mtk + Link to getutmp.3. + +gnu_get_libc_release.3 + mtk + Link to gnu_get_libc_version.3 + +updwtmpx.3 + mtk + Link to updwtmp.3 + +utmpxname.3 + mtk + Link to getutent.3. + +utmpx.5 + mtk + Link to utmp.5. + + +Global changes +-------------- + +Various pages + mtk + s/user name/username/ + +Various pages + mtk + s/host name/hostname/ + + +Changes to individual pages +--------------------------- + +fchmodat.2 + Alain Portal + SEE ALSO: add symlink.7. (3.01 changelog wrongly said this + had been done.) + +io_setup.2 + Alain Portal + Remove superfluous text from RETURN VALUE. + +mmap.2 + mtk + SEE ALSO: Add mmap(2), shm_overview(7). + +shmget.2 +shmop.2 + mtk + SEE ALSO: add shm_overview(7). + +sigreturn.2 + mtk + Added a bit more detail on what sigreturn() actually does. + +signalfd.2 +sigsuspend.2 + mtk + SEE ALSO: Add sigwait(3). + +sigwaitinfo.2 + mtk + Describe behavior when multiple threads are blocked in + sigwaitinfo()/sigtimedwait(). + SEE ALSO: Add sigwait(3). + +dirfd.3 + mtk + RETURN VALUE: describe return value on success. + Add an ERRORS section documenting POSIX.1-specified errors. + +getaddrinfo.3 + mtk, after a note by Stephane Chazelas + getaddrinfo() supports specifying IPv6 scope-IDs. + +getlogin.3 + mtk + ERRORS: add ENOTTY. + SEE ALSO: add utmp(5). + +getutent.3 + WANG Cong + utmpname() does return a value. + mtk + Add paragraph to start of DESCRIPTION recommending + use of POSIX.1 "utmpx" functions. + CONFORMING TO: mention utmpxname(). + Add an ERRORS section. + There are no utmpx equivalents of the _r reentrant functions. + Clarify discussion of return values. + Add pointer to definition of utmp structure in utmp(5). + Clarify discussion of utmpx file on other systems (versus + Linux situation). + +getutent.3 + mtk + SEE ALSO: add getutmp(3) + +inet_pton.3 + Stephane Chazelas + Fix error in description of IPv6 presentation format: + s/x.x.x.x.x.x.x.x/x:x:x:x:x:x:x:x/. + +setbuf.3 + Reuben Thomas / mtk + Fix confused wording for return value of setvbuf(). + Fixes http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=488104. + mtk + Other minor rewordings. + +shm_open.3 + mtk + SEE ALSO: add shm_overview(7). + +random.4 + mtk, after a note by Alain Portal + Slight rewording to make life easier for non-native English + speakers. + +utmp.5 + mtk + Add discussion of POSIX.1 utmpx specification. + Provide a little more detail on fields of utmp structure. + Added comments to macros for ut_type field. + Correct the description of the ut_id field. + mtk + Consolidate duplicated information about ut_tv and ut_session + on biarch platforms. + mtk + Move some text from CONFORMING TO to NOTES. + Removed some crufty text. + SEE ALSO: add login(3), logout(3), logwtmp(3). + UT_LINESIZE is 32 (not 12). + mtk + SEE ALSO: add getutmp(3) + +man-pages.7 + mtk + Enhanced the discussion of font conventions. + +signal.7 + mtk + Note that the delivery order of multiple pending standard + signals is unspecified. + SEE ALSO: Add sigwait(3). + + +==================== Changes in man-pages-3.03 ==================== + +Released: 2008-07-08, Konolfingen + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andi Kleen +Hidetoshi Seto +Li Zefan +Paul Jackson +Sam Varshavchik + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +getcpu.2 + Andi Kleen, with some text and edits by mtk + Documents the getcpu(2) system call, introduced in Linux 2.6.19. + +sched_getcpu.3 + mtk + Documents sched_getcpu(3), a wrapper for getcpu(2), provided + since glibc 2.6. + +cpuset.7 + Paul Jackson, with review and editing by mtk, and comments by + Hidetoshi Seto and Li Zefan + A description of the cpuset file system, the mechanism introduced + kernel 2.6.12 for confining processes to designated processors + and nodes. (Becomes the fourth largest page in man-pages!) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +readdir.3 + mtk + Add documentation of readdir_r(). + + +New links +--------- + +updwtmpx.3 + Alain Portal + Link to updwtmp.3 (3.02 changelog wrongly said this had been done). + +readdir_r.3 + mtk + Link to readdir.3. + + +Global changes +-------------- + +get_mempolicy.2 +mbind.2 +sched_setaffinity.2 +set_mempolicy.2 + mtk + SEE ALSO: Add getcpu(2). + +accept.2 +close.2 +connect.2 +dup.2 +epoll_wait.2 +fcntl.2 +flock.2 +futex.2 +msgop.2 +poll.2 +read.2 +recv.2 +select.2 +semop.2 +send.2 +sigwaitinfo.2 +spu_run.2 +wait.2 +write.2 +aio_suspend.3 +mq_receive.3 +mq_send.3 +scanf.3 +sem_wait.3 +usleep.3 +inotify.7 + mtk + ERRORS: Added reference to signal(7) in discussion of EINTR. + +Various pages + mtk + Wrapped very long source lines. + + +Changes to individual pages +--------------------------- + +accept.2 + mtk + Small wording change. + +io_getevents.2 + mtk + ERRORS: Add EINTR error. + +open.2 + mtk + ERRORS: Add EINTR error. + +sigaction.2 + mtk + Note circumstances in which each SA_* flag is meaningful. + mtk + Describe POSIX specification, and Linux semantics for + SA_NOCLDWAIT when establishing a handler for SIGCHLD. + mtk + Add pointer under SA_RESTART to new text in signal(7) + describing system call restarting. + mtk + Other minor edits. + +truncate.2 + mtk + ERRORS: Added EINTR error. + A few minor rewordings. + +wait.2 + mtk + Remove statement that WUNTRACED and WCONTINUED only have effect + if SA_NOCLDSTOP has not been set for SIGCHLD. That's not true. + +errno.3 + mtk + Add a pointer to signal(7) for further explanation of EINTR. + +getgrouplist.3 + mtk + SEE ALSO: Add passwd(5). + +readdir.3 + mtk + Remove from SYNOPSIS; POSIX.1-2001 does not + require it. + Some minor rewordings. + +sleep.3 + mtk + RETURN VALUE: explicitly mention interruption by signal handler. + SEE ALSO: add signal(7). + +usleep.3 + mtk + POSIX.1-2001 also only documents EINVAL. + +group.5 + mtk + SEE ALSO: Add getgrent(3), getgrnam(3). + +passwd.5 + mtk + SEE ALSO: Add getpwent(3), getpwnam(3). + +proc.5 + mtk + Add pointer to description of /proc/PID/cpuset in cpuset(7). + +signal.7 + mtk + Add a section describing system call restarting, and noting + which system calls are affected by SA_RESTART, and which + system calls are never restarted. + mtk + Describe the aberrant Linux behavior whereby a stop signal + plus SIGCONT can interrupt some system calls, even if no + signal handler has been established, and note the system + calls that behave this way. + mtk + Note a few more architectures on which signal numbers are valid. + SEE ALSO: added a number of pages. + mtk + Update async-signal-safe function list for POSIX.1-2004 (which + adds sockatmark()). + + +==================== Changes in man-pages-3.04 ==================== + +Released: 2008-07-15, Konolfingen + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andrea Arcangeli +Andreas Mohr +Andrew Morgan +Erik Bosman +John Brooks +Nikanth Karthikesan +Pavel Heimlich +Petr Gajdos +Sam Varshavchik +Serge Hallyn +Sripathi Kodi +Vincent Lefevre + +Apologies if I missed anyone! + + +Web site +-------- + +licenses.html + mtk + A page describing the preferred licenses for new pages that + are contributed to man-pages. + + +New and rewritten pages +----------------------- + +utimensat.2 + mtk + New page documenting the utimensat() system call, new in 2.6.22, + and futimens() library function. + +end.3 + mtk + Documents etext, edata, and end symbols. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +memchr.3 + mtk + Add description of rawmemchr(). + +proc.5 + mtk + Document /proc/config.gz (new in kernel 2.6). + mtk, based on text from Documentation/vm/sysctl.txt + Document /proc/sys/vm/oom_kill_allocating_task + (new in Linux 2.6.24). + Document /proc/sys/vm/oom_dump_tasks + (new in Linux 2.6.25). + Document /proc/sys/vm/panic_on_oom + (new in Linux 2.6.18). + + +New links +--------- + +edata.3 +etext.3 + mtk + Links to end.3. + +futimens.3 + mtk + Link to new utimensat.2. + +getdate_err.3 + mtk + Link to getdate.3. + +h_errno.3 + mtk + Link to gethostbyname.3. + +optarg.3 +opterr.3 +optind.3 +optopt.3 + mtk + Links to getopt.3. + +rawmemchr.3 + mtk + Link to memchr.3. + +sys_errlist.3 +sys_nerr.3 + mtk + Links to perror.3. + + +Global changes +-------------- + +Various pages + mtk + s/parameter/argument/ when talking about the things given + to a function call, for consistency with majority usage. + +Various pages + mtk + s/UNIX/Unix/, when not used as part of a trademark, + for consistency with majority usage in pages. + +Various pages + mtk, after a note from Alain Portal + Put SEE ALSO entries into alphabetical order. + +Various pages + mtk + Remove period at end of SEE ALSO list. + +Various pages + mtk, after a note by Alain Portal + Even when the CONFORMING TO section is just a list of standards, + they should be terminated by a period. + +getpriority.2 +MB_LEN_MAX.3 +MB_CUR_MAX.3 +fwide.3 +mblen.3 +rtime.3 +st.4 +proc.5 +bootparam.7 +man-pages.7 +utf-8.7 +tcp.5 + mtk / Alain Portal + Small wording fixes -- express <=, <, >=, > in words when in + running text. + +sched_setparam.2 +sched_setscheduler.2 +getgrent_r.3 +hash.3 + mtk + Minor rewording w.r.t. use of the term "parameter". + +Typographical or grammatical errors have been corrected in several +other places. (Many, many thanks to Alain Portal!) + + +Changes to individual pages +--------------------------- + +capget.2 + Andrew Morgan + Update in line with addition of file capabilities and + 64-bit capability sets in kernel 2.6.2[45]. + +clock_nanosleep.2 + mtk + Add "Link with -lrt" to SYNOPSIS. + +getrusage.2 + Sripathi Kodi + Document RUSAGE_THREAD, new in 2.6.26. + mtk + Improve description of RUSAGE_CHILDREN. + Add pointer to /proc/PID/stat in proc(5). + Other minor clean-ups. + +ioprio_set.2 + Nikanth Karthikesan + Since Linux 2.6.25, CAP_SYS_ADMIN is longer required to set + a low priority (IOPRIO_CLASS_IDLE). + +mount.2 + mtk + Since Linux 2.6.26, MS_RDONLY honors bind mounts. + +openat.2 + mtk + SEE ALSO: add utimensat(3). + +prctl.2 + Serge Hallyn, with some edits/input from mtk + Document PR_CAPBSET_READ and PR_CAPBSET_DROP. + Erik Bosman + Document PR_GET_TSC and PR_SET_TSC. + mtk, reviewed by Andrea Arcangeli + Document PR_SET_SECCOMP and PR_GET_SECCOMP. + mtk + PR_SET_KEEPCAPS and PR_GET_KEEPCAPS operate on a per-thread + setting, not a per-process setting. + mtk + Clarify fork(2) details for PR_SET_PDEATHSIG. + mtk + Add description of PR_SET_SECUREBITS and PR_GET_SECUREBITS, + as well as pointer to further info in capabilities(7). + mtk + PR_GET_ENDIAN returns endianness info in location pointed to by + arg2 (not as function result, as was implied by previous text). + mtk + Expand description of PR_SET_NAME and PR_GET_NAME. + mtk + RETURN VALUE: bring up to date for various options. + mtk + Various improvements in ERRORS. + mtk + Note that PR_SET_TIMING setting of PR_TIMING_TIMESTAMP is not + currently implemented. + mtk + Minor changes: + * Clarify wording for PR_GET_UNALIGN, PR_GET_FPEMU, and + PR_GET_FPEXC. + * Some reformatting of kernel version information. + * Reorder PR_GET_ENDIAN and PR_SET_ENDIAN entries. + +readlinkat.2 + John Brooks / mtk + Fix and reword erroneous RETURN VALUE text. + +recv.2 + mtk + Noted which flags appeared in Linux 2.2. + +sched_setaffinity.2 + mtk, after a Fedora downstream patch + Update type used for cpusetsize argument in SYNOPSIS. + +select.2 + Andreas Mohr / mtk + Clarify "zero timeout" case. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=490868. + +send.2 + mtk + Noted which flags appeared in Linux 2.2. + +sigaction.2 + mtk + Document si_overrun and si_tid fields of siginfo structure. + Add some text for si_trapno field. + The si_errno field is *generally* unused. + mtk + Put descriptions of SA_* constants in alphabetical order. + +signal.2 + mtk + Rewrote and expanded portability discussion. + NOTES: Show the raw prototype of signal() (without use of + sighandler_t). + +signalfd.2 + mtk + Modify description of ssi_trapno field. + +swapon.2 + mtk + Fix two version number typos for MAX_SWAPFILES discussion: + s/2.6.10/2.4.10/ + +utime.2 + mtk + SEE ALSO: add utimensat(2), futimens(3). + +dl_iterate_phdr.3 + Alain Portal + SEE ALSO: Add elf(5). + +crypt.3 + mtk, after a Fedora downstream patch + Describe additional encryption algorithms. + See also: https://bugzilla.redhat.com/show_bug.cgi?id=428280. + +errno.3 + mtk + Small rewrites in DESCRIPTION. + +exec.3 + mtk, after a note from Alain Portal + Small rewording. + +exp10.3 + Alain Portal + SEE ALSO: Add log10(3). + +exp2.3 + Alain Portal + Add C99 to CONFORMING TO. + +fgetgrent.3 + Alain Portal + Add references to group(5). + mtk + Minor rewordings. + SEE ALSO: add fopen(3). + +fgetpwent.3 + Alain Portal + Add reference to passwd(5). + mtk + Minor rewordings. + SEE ALSO: add fopen(3). + +frexp.3 + Alain Portal + Add C99 to CONFORMING TO. + +futimes.3 + mtk + SEE ALSO: remove futimesat(2); add utimensat(2). + +getopt.3 + mtk + Add details on initial value of optind, and note that it can + be reset (to 1) to restart scanning of an argument vector. + Add a NOTES section describing the glibc-specific behavior + when optind is reset to 0 (rather than 1). + See http://groups.google.com/group/comp.unix.programmer/browse_thread/thread/be0d0b7a07a165fb + mtk + Note glibc extensions under CONFORMING TO. + +getspnam.3 + mtk + Improve comments on struct spwd. + +getpw.3 + Alain Portal + RETURN VALUE: note that errno is set on error. + mtk + Add EINVAL error. + +insque.3 + mtk / Alain Portal + Minor rewordings. + +log.3 + Alain Portal + Remove unnecessary sentence in ERRORS. + +log10.3 + mtk + SEE ALSO: Add exp10(3). + +offsetof.3 + Alain Portal + Small wording improvement. + +pow.3 + Alain Portal + Remove unnecessary sentence in ERRORS. + +printf.3 + mtk / Alain Portal + Many small formatting fixes. + +proc.5 + mtk + Remove redundant summary list of files in description of + /proc/sys/kernel. + Make kernel version for /proc/sys/kernel/panic_on_oops more precise. + Make kernel version for /proc/sys/kernel/pid_max more precise. + Add Documentation/sysctl/vm.txt to SEE ALSO. + Other minor edits. + +profil.3 + mtk / Alain Portal + Small wording improvement. + +rtime.3 + mtk, after a note by Alain Portal + Clarify meaning of midnight on 1 Jan 1900/1970. + mtk + Remove netdate(1) and rdate(1) from SEE ALSO, since these pages + don't seem to exist on Linux systems. + +scanf.3 + Vincent Lefevre / mtk + Clarify treatment of initial white space by %% conversion + specification. + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=435648. + mtk + Many small formatting fixes. + +stdin.3 + Alain Portal + Rename CONSIDERATIONS section to NOTES, and relocate + to appropriate place on page. + +tmpfile.3 + mtk, after a note by Alain Portal + Prepend "POSIX.1-2001 specifies that: " to the sentence stating + that tmpfile() may write to stdout. (AFAICS, glibc's tmpfile() + does not do this.) + +ttyname.3 + Alain Portal + Remove unnecessary sentence in ERRORS. + +wcsdup.3 + Alain Portal + Make wording more precise: the memory allocated by wcsdup(3) + *should* be freed with free(3). + +wordexp.3 + Alain Portal / mtk + Move example into proper EXAMPLE section. + +tty_ioctl.4 + mtk / Petr Gajdos + The features in the "Get and Set Window Size" subsection + require the inclusion of . + +capabilities.7 + Serge Hallyn, plus a bit of work by mtk + Document file capabilities, per-process capability bounding set, + changed semantics for CAP_SETPCAP, and other changes in 2.6.2[45]. + Add CAP_MAC_ADMIN, CAP_MAC_OVERRIDE, CAP_SETFCAP. + Various smaller fixes. + mtk, plus review by Serge Hallyn and Andrew Morgan + Add text detailing how CAP_SETPCAP (theoretically) permits -- on + pre-2.6.25 kernels, and 2.6.25 and later kernels with file + capabilities disabled -- a thread to change the capability sets + of another thread. + Add section describing rules for programmatically adjusting + thread capability sets. + Add some words describing purpose of inheritable set. + Note existence of CONFIG_SECURITY_CAPABILITIES config option. + Describe rationale for capability bounding set. + Document securebits flags (new in 2.6.26). + Remove obsolete BUGS section. + SEE ALSO: Add getcap(8), setcap(8), and various libcap pages. + mtk + Add text noting that if we set the effective flag for one + file capability, then we must also set the effective flag for all + other capabilities where the permitted or inheritable bit is set. + mtk + Since Linux 2.6.25, CAP_SYS_ADMIN is no longer required for + ioprio_set() to set IOPRIO_CLASS_IDLE class. + mtk + Reword discussion of CAP_LINUX_IMMUTABLE to be file-system neutral. + +man-pages.7 + mtk + A list of standards in the CONFORMING TO list should be + terminated by a period. + The list of pages in a SEE ALSO list should not be + terminated by a period. + +tcp.7 + mtk + Correct a detail for sysctl_tcp_adv_win_scale. + Formatting fixes. + + +==================== Changes in man-pages-3.05 ==================== + +Released: 2008-07-23, Konolfingen + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andries Brouwer +Brian M. Carlson +Fabian Kreutz +Franck Jousseaume +Sam Varshavchik +Uli Schlacter + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +matherr.3 + mtk, with review by Andries Brouwer + A description of the SVID-specified mechanism for reporting + math exceptions. + See http://thread.gmane.org/gmane.linux.man/266. + +math_error.7 + mtk, with review and suggested input from Andries Brouwer + A description of how math functions report errors. + See http://thread.gmane.org/gmane.linux.man/249. + + +Global changes +-------------- + +Various pages + mtk + s/floating point/floating-point/ when used attributively. + +Various pages + mtk + For consistency with majority usage: + s/plus infinity/positive infinity/ + s/minus infinity/negative infinity/ + +Typographical or grammatical errors have been corrected in several +other places. + + +Changes to individual pages +--------------------------- + +brk.2 + mtk + SEE ALSO: add end(3). + +open.2 + Brian M. Carlson / mtk + Remove ambiguity in description of support for O_EXCL on NFS. + As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=491791. + +prctl.2 + mtk + Place options in some semblance of alphabetical order. + (No content or formatting changes were made.) + +cerf.3 + mtk + Bump version number: these functions are still missing in + glibc 2.8. + +fenv.3 + mtk + SEE ALSO: Add math_error(7). + +INFINITY.3 + mtk + SEE ALSO: Add math_error(7). + +nan.3 + mtk + Remove unneeded "Compile with" piece in SYNOPSIS. + SEE ALSO: Add math_error(7). + +rpc.3 + mtk / Franck Jousseaume + Fix errors introduced into a few prototypes when converting + function declarations to use modern C prototypes in man-pages-2.75. + +ipv6.7 + mtk, after a report from Uli Schlacter + Document the IPV6_V6ONLY flag. + + +==================== Changes in man-pages-3.06 ==================== + +Released: 2008-08-05, Konolfingen + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andreas Jaeger +Andries Brouwer +Fabian Kreutz +Gernot Tenchio +Sam Varshavchik +Tolga Dalman + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +erfc.3 + mtk + Created after removing the erfc() material from erf.3. + Documents the complementary error function. + +y0.3 + mtk + Created after removing the y*() material from j0.3. + Documents the Bessel functions of the second kind. + Included ERRORS section; noted that an exception is not + raised on underflow, see also + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6806; + and errno is not set on overflow, see also + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6808; + Included BUGS section noting that errno is incorrectly + set for pole error; see also + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6807. + +scalbln.3 + mtk + Created after removing the scalbln*() and scalbn*() material + from scalb.3. Documents scalbln() and scalbn() functions. + Included ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6803. + + +New and changed links +--------------------- + +erfcf.3 +erfcl.3 + mtk + Changed these links to point to new erfc.3 page. + +scalblnf.3 +scalblnl.3 +scalbn.3 +scalbnf.3 +scalbnl.3 + mtk + Changed these links to point to new scalbln.3 page. + +y0f.3 +y0l.3 +y1.3 +y1f.3 +y1l.3 +yn.3 +ynf.3 +ynl.3 + mtk + Changed these links to point to new y0.3 page. + + +Global changes +-------------- + +Various pages + mtk + s/floating point/floating-point/ when used attributively. + +Typographical or grammatical errors have been corrected in several +other places. + + +Changes to individual pages +--------------------------- + +crypt.3 + mtk + Tweak discuss text describing support for Blowfish. + +ctime.3 + mtk / Gernot Tenchio + Added some words to make clear that the string returned by + ctime() and asctime() is null-terminated. + +math_error.7 + Sam Varshavchik + Reverse order of SYNOPSIS and NAME sections. + mtk + NOTES: Summarize the state of glibc support for exceptions + and errno for error reporting. + + +Changes to individual pages (math functions) +-------------------------------------------- + +Almost all of the changes in this release relate to math man pages. +Very many changes were made to the math pages, including: + +* Fixed feature test macros (FTMs). Often, the FTM requirements + for the "float" and "long double" versions of a math function are + different from the requirements for the "double" version. Each math + page now shows the correct FTM requirements for all three versions + of the function(s) it describes. This may have required either + a change to the existing FTM text (if the requirements for the + "double" function were already described), or the addition of an FTM + description to a SYNOPSIS where one was not previously present + (typically because the "double" version of the function does not + require any FTMs to be defined). +* CONFORMING TO: in many cases, POSIX.1-2001 was not mentioned. + Where a function is specified in POSIX.1-2001, this is now noted. + Also, statements about what other standards a function conforms to + were generally clarified. (The wording about which functions conformed + to C99 was previously often done as an add on sentence; now it is made + part of the first sentence of the CONFORMING TO section, along with + POSIX.1-2001.) +* RETURN VALUE: in many cases, pages lacked descriptions of the return + value when the function arguments are special values such as +0, -0, + NaN (not-a-number), +infinity, -infinity, etc. This has been fixed. + I carried out tests on glibc 2.8 to ensure that all of these + functions match the RETURN VALUE descriptions (and the POSIX.1-2001 + requirements). +* ERRORS: many pages lacked a clear (or indeed any) description of + how errno is set on error and what exception is raised for each error. + This has been fixed. The ERRORS sections are now generally headed up + as per the POSIX.1 way of doing things, describing Pole / Range / + Domain errors, as applicable. + I carried out tests on glibc 2.8 to ensure that all of these + functions match the ERRORS descriptions. Deviations from POSIX.1-2001 + requirements have been filed as glibc bug reports, and noted in the + man pages. (The pages now describe the situation for ERRORS as at glibc + 2.8; I may eventually try and extend the text with descriptions of + changes in older versions of glibc.) + NOTE: one point that has not been covered in any page is the + circumstances that generate inexact (FE_INEXACT) exceptions. + (The details for these exceptions are not specified in POSIX.1-2001, + and I haven't gone looking for the standards that describe the details.) + +acos.3 + mtk + SYNOPSIS: Added feature test macro requirements. + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section. + Updated CONFORMING TO. + +acosh.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + Added RETURN VALUE section. + Rewrote ERRORS section. + Updated CONFORMING TO. + +asin.3 + mtk + SYNOPSIS: Added feature test macro requirements. + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section. + Updated CONFORMING TO. + +asinh.3 + mtk + SYNOPSIS: Added feature test macro requirements. + DESCRIPTION: Some rewording. + RETURN VALUE: Added details for special argument cases. + Added (null) ERRORS section. + Updated CONFORMING TO. + +atan.3 + mtk + SYNOPSIS: Added feature test macro requirements. + DESCRIPTION: Some rewording. + RETURN VALUE: Added details for special argument cases. + Added (null) ERRORS section. + Updated CONFORMING TO. + +atan2.3 + mtk + SYNOPSIS: Added feature test macro requirements. + DESCRIPTION: Some rewording. + RETURN VALUE: Added details for special argument cases. + Added (null) ERRORS section. + Updated CONFORMING TO. + +atanh.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + Added RETURN VALUE section. + Rewrote ERRORS section. + Updated CONFORMING TO. + Added BUGS section noting that pole error sets errno to EDOM, + when it should be ERANGE instead; see also + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6759. + +cbrt.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + Added RETURN VALUE section. + Added (null) ERRORS section. + Updated CONFORMING TO. + +ceil.3 + mtk + SYNOPSIS: Added feature test macro requirements. + DESCRIPTION: Enhanced. + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section. + Updated CONFORMING TO. + NOTES: Added some details. + +copysign.3 + mtk + Added RETURN VALUE section. + Updated CONFORMING TO. + +cos.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Rewrote RETURN VALUE section. + Added ERRORS section; noted errno is not set: + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6780. + Updated CONFORMING TO. + +cosh.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section. + Updated CONFORMING TO. + +erf.3 + mtk + Removed the erfc() material (there is now a new erfc page). + Reason: the functions are logically separate; also their + return values differ, and it would have been confusing + to document them on the same page. + SYNOPSIS: Fixed feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set; see + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6785. + Updated CONFORMING TO. + +exp.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set; see + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6786. + Updated CONFORMING TO. + +exp10.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set for underflow; + see http://sources.redhat.com/bugzilla/show_bug.cgi?id=6787. + +exp2.3 + mtk + Added RETURN VALUE and ERRORS sections. + Updated CONFORMING TO. + +expm1.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set for overflow; + see http://sources.redhat.com/bugzilla/show_bug.cgi?id=6788. + Updated CONFORMING TO. + Added BUGS section, describing bogus underflow exception for -large, + see http://sources.redhat.com/bugzilla/show_bug.cgi?id=6778; + and describing bogus invalid exception for certain +large, + see http://sources.redhat.com/bugzilla/show_bug.cgi?id=6814. + +fabs.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Updated CONFORMING TO. + +fdim.3 + mtk + SYNOPSIS: Added feature test macro requirements. + DESCRIPTION: Some rewording. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6796. + Updated CONFORMING TO. + +fenv.3 + mtk + Make style of writing exception names consistent with other + pages and POSIX.1-2001. + Updated CONFORMING TO. + +finite.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + +floor.3 + mtk + SYNOPSIS: Added feature test macro requirements. + DESCRIPTION: Enhanced. + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section. + Updated CONFORMING TO. + +fma.3 + mtk + SYNOPSIS: Added feature test macro requirements. + DESCRIPTION: Some rewording. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6801. + Updated CONFORMING TO. + +fmax.3 +fmin.3 + mtk + NAME: Make description clearer + SYNOPSIS: Added feature test macro requirements. + SYNOPSIS: Remove unneeded "Compile with" piece. + CONFORMING TO: Added POSIX.1-2001. + Added RETURN VALUE and ERRORS sections. + +fmod.3 + mtk + SYNOPSIS: Added feature test macro requirements. + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section; noted that errno is not always set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783. + Updated CONFORMING TO. + +fpclassify.3 + mtk + Minor wording changes. + CONFORMING TO: Added POSIX.1-2001. + SEE ALSO: Add signbit(3). + +frexp.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added details to RETURN VALUE section. + Added (null) ERRORS section. + CONFORMING TO: Added POSIX.1-2001. + +gamma.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + Added (null) RETURN VALUE section referring to tgamma(3). + Added (null) ERRORS section referring to tgamma(3). + CONFORMING TO: Rewrote. + +hypot.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + DESCRIPTION: note that calculation is done without causing + undue overflow or underflow. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not always set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6795. + Updated CONFORMING TO. + +ilogb.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Rewrote RETURN VALUE section. + Rewrote ERRORS section; noted that errno is not set, and in some + cases an exception is not raised; see also + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6794. + CONFORMING TO: Added POSIX.1-2001. + +isgreater.3 + mtk + NAME: Make description clearer + Improve the description of isunordered(). + Added RETURN VALUE and ERRORS sections. + Formatting fixes. + A few wording improvements. + +j0.3 + mtk + Removed material for the y*() functions to a separate y0.3 page. + Reason: the return values and errors/exceptions differ, and it + would have been confusing to document them on the same page. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6805. + +ldexp.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE and ERRORS sections. + Updated CONFORMING TO. + +lgamma.3 + mtk + Note that these functions are deprecated. + SYNOPSIS: Fixed feature test macro requirements. + Added RETURN VALUE and ERRORS sections referring to lgamma(3). + Added BUGS section noting that pole error sets errno to EDOM, + when it should be ERANGE instead; see also + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6777. + +log.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Rewrote ERRORS section. + Updated CONFORMING TO. + +log10.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Rewrote ERRORS section. + Updated CONFORMING TO. + +log1p.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6792. + Updated CONFORMING TO. + +log2.3 + mtk + Added RETURN VALUE section. + Rewrote ERRORS section. + Updated CONFORMING TO. + +logb.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + DESCRIPTION: added a little detail; some rewordings. + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6793. + CONFORMING TO: Added POSIX.1-2001. + +lrint.3 + mtk + DESCRIPTION: some rewording. + RETURN VALUE: Added details for special argument cases. + Added ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6798. + CONFORMING TO: Added POSIX.1-2001. + +lround.3 + mtk + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6797. + CONFORMING TO: Added POSIX.1-2001. + +modf.3 + mtk + SYNOPSIS: Added feature test macro requirements. + RETURN VALUE: Added details for special argument cases. + Added (null) ERRORS section. + CONFORMING TO: Added POSIX.1-2001. + +nan.3 + mtk + Small wording changes. + CONFORMING TO: Added POSIX.1-2001. + +nextafter.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + RETURN VALUE: Added details for special argument cases. + Added ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6799. + CONFORMING TO: Added POSIX.1-2001. + +pow.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Rewrote ERRORS section. + Updated CONFORMING TO. + Added BUGS section noting that pole error sets errno to EDOM, + when it should be ERANGE instead; see also + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6776. + +remainder.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + DESCRIPTION: added some details. + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section; noted that errno is not always set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783. + Updated CONFORMING TO. + Added BUGS section noting that remainder(nan(""), 0) + wrongly causes a domain error; see + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6779 + +remquo.3 + mtk + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6801. + Updated CONFORMING TO. + +fmax.3 +fmin.3 + mtk + NAME: Make description clearer + SYNOPSIS: Added feature test macro requirements. + SYNOPSIS: Remove unneeded "Compile with" piece. + CONFORMING TO: Added POSIX.1-2001. + Added RETURN VALUE and ERRORS sections. + +fmod.3 + mtk + SYNOPSIS: Added feature test macro requirements. + RETURN VALUE: Added details for special argument cases. + Rewrote ERRORS section; noted that errno is not always set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783. + Updated CONFORMING TO. + +fpclassify.3 + CONFORMING TO: Added POSIX.1-2001. + +rint.3 + mtk + SYNOPSIS: Fixed feature test macro requirements. + DESCRIPTION: added some details. + RETURN VALUE: Added details for special argument cases. + ERRORS: no errors can occur (previous text was misleading). + CONFORMING TO: Added POSIX.1-2001. + NOTES: point out that lrint() may be preferred in some cases. + +round.3 + mtk + DESCRIPTION: added some details. + RETURN VALUE: Added details for special argument cases. + ERRORS: no errors can occur (previous text was misleading). + CONFORMING TO: Added POSIX.1-2001. + NOTES: point out that lround() may be preferred in some cases. + +scalb.3 + mtk + Removed the scalbn() and scalbln() material to a separate + scalbln.3 page. Reason: scalb() is obsolete; also the + exception/error conditions differ somewhat, so that it + would have been confusing to document them on the same page. + SYNOPSIS: Fixed feature test macro requirements. + DESCRIPTION: some rewrites and added details. + Added RETURN VALUE section. + Added ERRORS section; noted that errno is not set; see + also http://sources.redhat.com/bugzilla/show_bug.cgi?id=6803 + and http://sources.redhat.com/bugzilla/show_bug.cgi?id=6804. + CONFORMING TO: Rewrote. + +signbit.3 + mtk + SYNOPSIS: Added feature test macro requirements. + SYNOPSIS: Remove unneeded "Compile with" piece. + Added RETURN VALUE section. + Added (null) ERRORS section. + CONFORMING TO: Added POSIX.1-2001. + +sin.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section; noted errno is not set: + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6781. + Updated CONFORMING TO. + +sincos.3 + mtk + DESCRIPTION: Added details for special argument cases. + Added (null) RETURN VALUE section. + Added ERRORS section. + +sinh.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section. + Updated CONFORMING TO. + +sqrt.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Rewrote ERRORS section. + Updated CONFORMING TO. + +tan.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Added ERRORS section. + Added ERRORS section; noted errno is not set: + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6782. + Updated CONFORMING TO. + +tanh.3 + mtk + SYNOPSIS: Added feature test macro requirements. + Added RETURN VALUE section. + Added (null) ERRORS section. + Updated CONFORMING TO. + +tgamma.3 + mtk + Added RETURN VALUE section. + Rewrote ERRORS section; noted that errno is not set / + incorrectly set in some cases; see also + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6809 + and http://sources.redhat.com/bugzilla/show_bug.cgi?id=6810. + CONFORMING TO: Added POSIX.1-2001. + Added NOTES section to hold text explaining origin of tgamma(). + +trunc.3 + mtk + RETURN VALUE: small rewording. + CONFORMING TO: Added POSIX.1-2001. + Added NOTES section explaining that result may be too large + to store in an integer type. + + +==================== Changes in man-pages-3.07 ==================== + +Released: 2008-08-12, Konolfingen + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alain Portal +Andries Brouwer +Christoph Lameter +Cliff Wickman +Fabian Kreutz +Filippo Santovito +Gerrit Renker +Heikki Orsila +Khalil GHORBAL +Lee Schermerhorn +Maxin John +Reuben Thomas +Samuel Thibault +Sam Varshavchik +Soh Kam Yung +Stephane Chazelas +Pavel Heimlich +Reuben Thomas + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +move_pages.2 + Christoph Lameter, various edits and improvements by mtk + Documentation of the move_pages() system call. + This page was formerly part of the numactl package, but really + belongs in man-pages (since it describes a kernel interface). + +clock_getcpuclockid.3 + mtk + New page documenting the clock_getcpuclockid() library function, + available since glibc 2.2. + +udplite.7 + Gerrit Renker + Document the Linux implementation of the UDP-Lite protocol, + new in Linux 2.6.20. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +proc.5 + Christoph Lameter, minor edits and improvements by mtk + Documentation of the /proc/PID/numa_maps file. + This material was formerly the numa_maps.5 page in the numactl + package, but really belongs in man-pages (since it describes + a kernel interface). + + +Global changes +-------------- + +nanosleep.2 +inet_ntop.3 +inet_pton.3 +scanf.3 +initrd.4 + mtk + Fix mis-ordered (.SH) sections. + +connect.2 +socket.2 +rtnetlink.3 +arp.7 +ddp.7 +ip.7 +ipv6.7 +netlink.7 +packet.7 +raw.7 +rtnetlink.7 +socket.7 +tcp.7 +udp.7 +unix.7 +x25.7 + mtk + s/PF_/AF_/ for socket family constants. Reasons: the AF_ and + PF_ constants have always had the same values; there never has + been a protocol family that had more than one address family, + and POSIX.1-2001 only specifies the AF_* constants. + +Typographical or grammatical errors have been corrected in several +other places. + + +Changes to individual pages +--------------------------- + +execve.2 + mtk + The floating-point environment is reset to the default + during an execve(). + +get_mempolicy.2 + Lee Schermerhorn + Misc cleanup of get_mempolicy(2): + + mention that any mode flags will be saved with mode. + I don't bother to document mode flags here because we + already have a pointer to set_mempolicy(2) for more info + on memory policy. mode flags are discussed there. + + remove some old, obsolete [IMO] NOTES and 'roff comments. + Lee Schermerhorn + Update the get_mempolicy(2) man page to add in the description of + the MPOL_F_MEMS_ALLOWED flag, added in 2.6.23. + mtk + Document additional EINVAL error that occurs is MPOL_F_MEMS_ALLOWED + is specified with either MPOL_F_ADDR or MPOL_F_NODE. + +getitimer.2 + mtk + CONFORMING TO: POSIX.1-2008 marks getitimer() and setitimer() + obsolete. + +mbind.2 + Lee Schermerhorn + Fix error conditions, now that the kernel silently ignores + nodes outside the task's cpuset, as long as one valid node + remains. + + Now that cpuset man page exists, we can refer to it. Remove + stale comment regarding lack thereof. + Lee Schermerhorn + Add brief discussion of mode flags. + Lee Schermerhorn + Attempt to clarify discussion of MPOL_DEFAULT. + mtk + Fix URI reference for libnuma. + +mprotect.2 + mtk / Maxin John + Remove EFAULT from errors. Under ENOMEM error, note that + EFAULT was the error produced in some cases for kernels before + 2.4.19. + +msgctl.2 + mtk, after a note from Filippo Santovito + In the ipc_perm structure definition, some fields were + incorrectly named: s/key/__key/ and s/seq/__seq/. + +set_mempolicy.2 + Lee Schermerhorn + Fix up the error return for nodemask containing nodes disallowed by + the process' current cpuset. Disallowed nodes are now silently ignored, + as long as the nodemask contains at least one node that is on-line, + allowed by the process' cpuset and has memory. + + Now that we have a cpuset man page, we can refer to cpusets directly + in the man page text. + + Lee Schermerhorn + Another attempt to rationalize description of MPOL_DEFAULT. + + Since ~2.6.25, the system default memory policy is "local allocation". + MPOL_DEFAULT itself is a request to remove any non-default policy and + "fall back" to the surrounding context. Try to say that without delving + into implementation details. + + Lee Schermerhorn + Add discussion of mempolicy mode flags to set_mempolicy(2). + This adds another reason for EINVAL. + +setpgid.2 + mtk + CONFORMING TO: POSIX.1-2008 marks setpgrp() obsolete. + +semctl.2 + mtk, after a note from Filippo Santovito + In the ipc_perm structure definition, some fields were + incorrectly named: s/key/__key/ and s/seq/__seq/. + +shmctl.2 + Filippo Santovito / mtk + In the ipc_perm structure definition, some fields were + incorrectly named: s/key/__key/ and s/seq/__seq/. + +utime.2 + mtk + CONFORMING TO: POSIX.1-2008 marks utime() obsolete. + CONFORMING TO: POSIX.1-2008 removes the POSIX.1-2001 LEGACY + marking of utimes(), so mention of this point has been + removed from the page. + +vfork.2 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of vfork(). + +atan2.3 + Fabian Kreutz + SEE ALSO Add carg(3). + +bcmp.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of bcmp(). + +bsd_signal.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification ofcw + bsd_signal(). + +bzero.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of bzero(). + +cexp2.3 + mtk + AVAILABILITY: These functions are still not in glibc + as at version 2.8. + +clock_getres.3 + mtk + SEE ALSO: Add clock_getcpuclockid(3). + +clog2.3 + mtk + AVAILABILITY: These functions are still not in glibc + as at version 2.8. + +ctime.3 + mtk + POSIX.1-2008 marks asctime(), asctime_r(), ctime(), and ctime_r() + as obsolete. + +dprintf.3 + mtk + CONFORMING TO: These functions are nowadays in POSIX.1-2008. + +ecvt.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specifications of + ecvt() and fcvt(). + +ftime.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of ftime(). + +ftw.3 + mtk + CONFORMING TO: POSIX.1-2008 marks ftw() as obsolete. + +gcvt.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of gcvt(). + +getcwd.3 + Reuben Thomas / mtk + Clarify description of getcwd() for buf==NULL case; + CONFORMING TO: According to POSIX.1, the behavior of getcwd() + is unspecified for the buf==NULL case. + mtk + Add an introductory paragraph giving an overview of what these + functions do. + Fix error in description of getwd(): it does not truncate the + pathname; rather, it gives an error if the pathname exceeds + PATH_MAX bytes. + Rewrote RETURN VALUE section. + Add EINVAL ENAMETOOLONG errors for getwd(). + Various other clarifications and wording fixes. + CONFORMING TO: POSIX.1-2001 does not define any errors for + getwd(). + CONFORMING TO: POSIX.1-2008 removes the specification of getwd(). + +gethostbyname.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specifications of + gethostbyname(), gethostbyaddr(), and h_errno. + +gets.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of gets(). + +iconv.3 +iconv_close.3 +iconv_open.3 + mtk + VERSIONS: These functions are available in glibc since version 2.1. + +index.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specifications of + index() and rindex(). + +isalpha.3 + mtk + CONFORMING TO: POSIX.1-2008 marks isalpha() as obsolete. + +makecontext.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specifications of + makecontext() and swapcontext(). + +memchr.3 + mtk + VERSIONS: memrchr() since glibc 2.2; rawmemchr() since glibc 2.1. + +mempcpy.3 + mtk + VERSIONS: mempcpy() since glibc 2.1. + +mktemp.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of mktemp(). + +opendir.3 + mtk + CONFORMING TO: POSIX.1-2008 specifies fdopendir(). + +rand.3 + mtk + CONFORMING TO: POSIX.1-2008 marks rand_r() as obsolete. + +siginterrupt.3 + mtk + CONFORMING TO: POSIX.1-2008 marks siginterrupt() as obsolete. + +sigset.3 + mtk + CONFORMING TO: POSIX.1-2008 marks sighold(), sigignore(), + sigpause(), sigrelse(), and sigset() as obsolete. + +strchr.3 + mtk + VERSIONS: strchrnul() since glibc 2.1.1. + +tempnam.3 + mtk + CONFORMING TO: POSIX.1-2008 marks tempnam() as obsolete. + +tmpnam.3 + mtk + CONFORMING TO: POSIX.1-2008 marks tmpnam() as obsolete. + +toascii.3 + mtk + CONFORMING TO: POSIX.1-2008 marks toascii() as obsolete. + +ualarm.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of ualarm(). + +ulimit.3 + mtk + CONFORMING TO: POSIX.1-2008 marks ulimit() as obsolete. + +usleep.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of usleep(). + +standards.7 + mtk + Updated details for POSIX.1-2008, and noted that if + POSIX.1-2001 is listed in the CONFORMING TO section of a man + page, then the reader can assume that the interface is also + specified in POSIX.1-2008, unless otherwise noted. + +time.7 + mtk + SEE ALSO: Add clock_getcpuclockid(3). + +udp.7 + mtk + SEE ALSO: add udplite(7). + + +Changes to individual pages (math functions) +-------------------------------------------- + +Various changes here following on from the big update to the +math pages in the previous release. Test results going back +glibc 2.3.2 (so far) allowed updates to various pages to note +changes in historical behavior for error reporting by math +functions. Thanks to the following people for providing me +with test results on various distributions and glibc versions: +Alain Portal, Andries Brouwer, Fabian Kreutz, Heikki Orsila, +Khalil GHORBAL, Pavel Heimlich, Reuben Thomas, Samuel Thibault, +Soh Kam Yung, and Stephane Chazelas + +cabs.3 +cacos.3 +cacosh.3 +carg.3 +casin.3 +casinh.3 +catan.3 +catanh.3 +ccos.3 +ccosh.3 +cexp.3 +cimag.3 +clog.3 +clog10.3 +conj.3 +cpow.3 +cproj.3 +creal.3 +csin.3 +csinh.3 +csqrt.3 +ctan.3 +ctanh.3 +exp10.3 +exp2.3 +fdim.3 +fenv.3 +fma.3 +fmax.3 +fmin.3 +log2.3 +lrint.3 +lround.3 +nan.3 +pow10.3 +remquo.3 +round.3 +scalbln.3 +sincos.3 +tgamma.3 +trunc.3 + mtk + Added VERSIONS section noting that these functions first + appeared in glibc in version 2.1. + +cosh.3 + mtk + BUGS: In glibc 2.3.4 and earlier, an FE_OVERFLOW exception is not + raised when an overflow occurs. + +fenv.3 + mtk / Fabian Kreuz + Provide more detail in the description of rounding modes. + Add text describing FLT_ROUNDS (formerly in fma.3). + Add BUGS section pointing out the FLT_ROUNDS does not reflect + changes by fesetround(). + +fma.3 + mtk + Remove text about FLT_ROUNDS, replacing with a cross-reference + to fenv(3). + +fpclassify.3 + mtk + CONFORMING TO: Note that the standards provide a weaker guarantee + for the return value of isinf(). + +log.3 + mtk + BUGS: In glibc 2.5 and earlier, log(nan("")) produces a bogus + FE_INVALID exception. + +lround.3 + mtk + Add reference to fenv(3) for discussion of current rounding mode. + +nextafter.3 + mtk + BUGS: In glibc 2.5 and earlier these functions do not raise an + FE_UNDERFLOW exception on underflow. + +pow.3 + mtk + BUGS: described buggy NaN return when x is negative and y is large. + See also: http://sources.redhat.com/bugzilla/show_bug.cgi?id=3866. + BUGS: Note the bogus FE_INVALID exception that occurred in glibc + 2.3.2 and earlier on overflow and underflow. + +remainder.3 + mtk + Add reference to fenv(3) for discussion of current rounding mode. + +round.3 + mtk + Add reference to fenv(3) for discussion of current rounding mode. + +scalb.3 + mtk + CONFORMING TO: POSIX.1-2008 removes the specification of scalb(). + +tgamma.3 + mtk + BUGS: In glibc 2.3.3, tgamma(+-0) produced a domain error + instead of a pole error. + +y0.3 + mtk + In glibc 2.3.2 and earlier, these functions do not raise an + FE_INVALID exception for a domain error. + +math_error.7 + mtk + Rewrite introductory paragraph. + Point out that a NaN is commonly returned by functions that report + a domain error. + + +==================== Changes in man-pages-3.08 ==================== + +Released: 2008-08-27, Zurich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Gerrit Renker +Li Zefan +Mike Bianchi +Sam Varshavchik +Venkatesh Srinivas +Vijay Kumar + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +getnetent_r.3 + mtk + Documents getnetent_r(), getnetbyname_r(), + and getnetbyaddr_r(), the reentrant equivalents of + getnetent(), getnetbyname(), and getnetbyaddr(). + +getprotoent_r.3 + mtk + Documents getprotoent_r(), getprotobyname_r(), and + getprotobynumber_r(), the reentrant equivalents of + getprotoent(), getprotobyname(), and getprotobynumber(). + +getrpcent_r.3 + mtk + Documents getrpcent_r(), getrpcbyname_r(), and + getrpcbynumber_r(), the reentrant equivalents of + getrpcent(), getrpcbyname(), and getrpcbynumber(). + +getservent_r.3 + mtk + Documents getservent_r(), getservbyname_r(), and + getservbyport_r(), the reentrant equivalents of + getservent(), getservbyname(), and getservbyport(). + +numa.7 + mtk + A new page giving overview details for the Linux NUMA interfaces. + Incorporates some material from mbind.2, and the description + of /proc/PID/numa_maps from proc.5. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +crypt.3 + mtk + Add description of crypt_r(). + + +New and changed links +--------------------- + +crypt.3 + mtk + New link to crypt.3. + +getnetbyname_r.3 +getnetbyaddr_r.3 + mtk + New links to new getnetent_r.3. + +getprotobyname_r.3 +getprotobynumber_r.3 + mtk + New links to new getprotoent_r.3. + +getrpcbyname_r.3 +getrpcbynumber_r.3 + mtk + New links to new getrpcent_r.3. + +getservbyname_r.3 +getservbyport_r.3 + mtk + New links to new getservent_r.3. + +numa_maps.5 + mtk + Link to new numa(7) page, which incorporates the + /proc/PID/numa_maps description. + As part of the numactl() package, the /proc/PID/numa_maps + documentation was in a numa_maps.5 page; this link + ensures that "man 5 numa_maps" still works. + (Eventually, we may want to remove this link.) + + +Global changes +-------------- + +get_mempolicy.2 +mbind.2 +move_pages.2 +set_mempolicy.2 + mtk + Add reference to numa(7) for information on library support. + Added a VERSIONS section. + SEE ALSO: Add numa(7). + +faccessat.2 +fchmodat.2 +fchownat.2 +fstatat.2 +mkdirat.2 +mknodat.2 +linkat.2 +openat.2 +readlinkat.2 +renameat.2 +symlinkat.2 +unlinkat.2 +mkfifoat.3 +psignal.3 +strsignal.3 + mtk + These interfaces are specified in POSIX.1-2008. + + +Changes to individual pages +--------------------------- + +eventfd.2 + Vijay Kumar + When an eventfd overflows, select() indicates the file as both + readable and writable (not as having an exceptional condition). + +fcntl.2 + mtk + F_DUPFD_CLOEXEC is specified in POSIX.1-2008. + +getrlimit.2 + mtk + NOTES: Add text mentioning the shell 'ulimit' (or 'limit') + built-in command for setting resource limits. + +gettimeofday.2 + mtk + CONFORMING TO: POSIX.1-2008 marks gettimeofday() as obsolete. + +link.2 + mtk + Note kernel version where Linux stopped following symbolic + links in 'oldpath'; see also http://lwn.net/Articles/294667. + POSIX.1-2008 makes it implementation-dependent whether or not + 'oldpath' is dereferenced if it is a symbolic link. + Add a reference to linkat(2) for an interface that allows + precise control of the treatment of symbolic links. + +mbind.2 + mtk + Remove material on library support and numactl; that material + is now in numactl.7. + +mmap.2 + mtk + Add kernel version numbers for MAP_32BIT. + Add some details on MAP_32BIT (see http://lwn.net/Articles/294642). + +move_pages.2 + mtk + Added VERSIONS (from kernel 2.6.18) and CONFORMING TO sections. + +open.2 + mtk + O_CLOEXEC is specified in POSIX.1-2008. + +socket.2 + mtk + s/d/domain/ for name of argument. + Add reference to socket(2) for further information on + domain, type, and protocol arguments. + +utimensat.2 + mtk + CONFORMING TO: POSIX.1-2008 specifies utimensat() and futimens(). + +dirfd.3 + mtk + CONFORMING TO: Add POSIX.1-2008; other minor changes. + +exec.3 + mtk + Small rewording: "s/returned/failed with/ [an error]". + +fmemopen.3 + mtk + Since glibc 2.7, it is possible to seek past the end of + a stream created by open_memstream(). Add a BUGS section + describing the bug in earlier glibc versions. + +gethostbyname.3 + mtk + Clarify exactly which functions are obsoleted by getnameinfo() + and getaddrinfo(). + +getnetent.3 + mtk + Rephrase description in terms of a database, rather than a file. + Note that each of the get*() functions opens a connection to + the database if necessary. + The database connection is held open between get*() calls if + 'stayopen' is non-zero (not necessarily 1). + s/zero terminated list/NULL-terminated list/ + mtk + In glibc 2.2, the type of the 'net' argument for getnetbyaddr() + changed from 'long' to 'uint32_t'. + mtk + Note that the gethostbyaddr() 'net' argument is in host byte order. + mtk + RETURN VALUE: emphasize that returned pointer points to a + statically allocated structure. + SEE ALSO: add getnetent_r.3. + +getprotoent.3 + mtk + Rephrase description in terms of a database, rather than a file. + Note that each of the get*() functions opens a connection to + the database if necessary. + The database connection is held open between get*() calls if + 'stayopen' is non-zero (not necessarily 1). + s/zero terminated list/NULL-terminated list/ + mtk + RETURN VALUE: emphasize that returned pointer points to a + statically allocated structure. + SEE ALSO: add getprotoent_r.3. + +getrpcent.3 + mtk + s/rpc/RPC/. + Rephrase description in terms of a database, rather than a file. + Note that each of the get*() functions opens a connection to + the database if necessary. + s/zero terminated list/NULL-terminated list/ + mtk + RETURN VALUE: emphasize that returned pointer points to a + statically allocated structure. + SEE ALSO: add getrpcent_r.3. + +getservent.3 + mtk + Rephrase description in terms of a database, rather than a file. + Note that each of the get*() functions opens a connection to + the database if necessary. + The database connection is held open between get*() calls if + 'stayopen' is non-zero (not necessarily 1). + s/zero terminated list/NULL-terminated list/ + mtk + RETURN VALUE: emphasize that returned pointer points to a + statically allocated structure. + SEE ALSO: add getservent_r.3. + +mkdtemp.3 + mtk + CONFORMING TO: this function is specified in POSIX.1-2008. + +mq_notify.3 + Venkatesh Srinivas + s/sigev_notify_function/sigev_thread_function/ + as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494956. + +realpath.3 + mtk + Relocate text for resolved_path==NULL case to DESCRIPTION. + POSIX.1-2001 leaves the resolved_path==NULL case as + implementation-defined; POSIX.1-2008 specifies the behavior + described in this man page. + +sem_init.3 + mtk + POSIX.1-2008 rectifies the POSIX.1-2001 omission, specifying + that zero is returned by a successful sem_init() call. + +core.5 + Mike Bianchi / mtk + Make the page more helpful to non-programmers by referencing + the documentation of the shell's 'ulimit' command in the + discussion of RLIMIT_CORE and RLIMIT_FSIZE. + SEE ALSO: Add bash(1). + mtk + Note that a core dump file can be used in a debugger. + +proc.5 + mtk + Remove /proc/PID/numa_maps material (it is now in numa(7)). + +cpuset.7 + mtk + SEE ALSO: Add numa(7). + +inotify.7 + mtk / Li Zefan + Explain bug that occurred in coalescing identical events in + kernels before 2.6.25. + (See commit 1c17d18e3775485bf1e0ce79575eb637a94494a2 + "A potential bug in inotify_user.c" in the 2.6.25 Changelog.) + +pthreads.7 + mtk + Update thread-safe functions list with changes in POSIX.1-2008. + SEE ALSO: add proc(5). + +signal.7 + mtk + Update list of async-signal-safe functions for POSIX.1-2008. + + +==================== Changes in man-pages-3.09 ==================== + +Released: 2008-09-10, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Bernd Eckenfels +Bruno Haible +Carsten Emde +Christopher Head +H. Peter Anvin +Jan Engelhardt +Joe Korty +Marko Kreen +Martin (Joey) Schulze +Mats Wichmann +Michael Schurter +Mike Bianchi +Mike Frysinger +Sam Varshavchik +Suka +Timothy S. Nelson +Tolga Dalman +Török Edwin + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +fopencookie.3 + mtk + Document fopencookie(3), a library function that allows + custom implementation of a stdio stream. + +networks.5 + Martin (Joey) Schulze, with a few light edits by mtk + Documents the /etc/networks file. + + +Global changes +-------------- + +Various pages + mtk + s/time zone/timezone/ for consistency across pages and + with POSIX.1. + +kill.2 +sigaction.2 +sigpending.2 +sigprocmask.2 +sigsuspend.2 +confstr.3 +ctermid.3 +ctime.3 +ferror.3 +flockfile.3 +fopen.3 +getaddrinfo.3 +getgrnam.3 +getnameinfo.3 +getopt.3 +getpwnam.3 +longjmp.3 +popen.3 +rand.3 +readdir.3 +setjmp.3 +sigsetops.3 +sigwait.3 +strtok.3 +tzset.3 +unlocked_stdio.3 + mtk + Add/fix feature test macro requirements. + + +Changes to individual pages +--------------------------- + +fcntl.2 + mtk, after a note by Mike Bianchi + More clearly and consistently describe whether + or not the third argument to fcntl() is required, + and what its type should be. + mtk + Move description of negative l_len from NOTES, integrating + it into the discussion of file locking. + Minor rewrites of the text on file locking. + +getrusage.2 + Bernd Eckenfels + SEE ALSO: Add clock(3), clock_gettime(3). + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=353475 + +ioctl_list.2 + mtk + Remove old sentence about where to send updates for this page. + Add more detail on mount options that prevent updates to atime. + +sched_setscheduler.2 + Carsten Emde + Update kernel version numbers relating to real-time support. + +stat.2 + H. Peter Anvin + Note that lstat() will generally not trigger automounter + action, whereas stat() will. + +clock.3 + Bernd Eckenfels + SEE ALSO: Add clock_gettime(3). + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=353475 + +clock_getres.3 + Tolga Dalman / mtk + Add "Link with -lrt" to SYNOPSIS; remove now redundant + sentence mentioning librt from NOTES. + +getdate.3 + mtk + Rewrite description of getdate_r() and integrate into main text + (rather than describing in NOTES). + Other parts rewritten for greater clarity. + Make it clearer in the main text that glibc does not implement %Z; + remove discussion of that point from NOTES. + Added an example program. + +hsearch.3 + mtk + Noted that table size as specified by 'nel' is immutable. + Described differences between hsearch() and hsearch_r(). + Added missing pieces to RETURN VALUE. + Added a number of new entries under ERRORS. + NOTES: added some basic advice on sizing the hash table; + noted that when a table is destroyed, the caller is responsible + for freeing the buffers pointed to by 'key' and 'data' fields. + One of the BUGS was fixed in glibc 2.3. + Rewrote and clarified various other pieces. + Rename arguments for reentrant functions, using same name as + glibc headers: s/ret/retval/; s/tab/htab/. + mtk, after a suggestion by Timothy S. Nelson + Integrate discussion of reentrant functions into main discussion + (rather than as a short paragraph at the end). + +iconv.3 + Bruno Haible + Describe "shift sequence" input. + +ptsname.3 + sukadev + Fix return type of ptsname_r() in SYNOPSIS. + +readdir.3 + H. Peter Anvin + s/stat(2)/lstat(2)/ when discussing d_type (since we + are talking about a case where we might be interested to + whether the file itself is a symbolic link). + +sigsetops.3 + Chris Head, signed-off-by: Mike Frysinger + Fix typo: s/sigdelset/sigorset/ + +proc.5 + Mats Wichmann / mtk + s/\[number]/[pid]/ in file names for /proc/PID files. + And similar changes for task/[tid] sub-directories. + mtk / Mats Wichmann + In the description if /proc/[pid]/environ, remove reference to + lilo(8)/grub(8) since there seems to be nothing in those pages + that related to this /proc file. + Michael Schurter / mtk + Remove sentence wrongly saying that /proc/meminfo reports + info in bytes; + see http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=462969 + mtk + Note that /proc/meminfo reports system-wide memory usage + statistics. + Joe Korty + Document new fields in /proc/interrupts that were added in + Linux 2.6.24. + +unix.7 + Marko Kreen + Since glibc 2.8, _GNU_SOURCE must be defined in order to get + the definition of the ucred structure from . + + +==================== Changes in man-pages-3.10 ==================== + +Released: 2008-09-23, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +André Goddard Rosa +George Spelvin +Pavel Heimlich +Sam Varshavchik +John Reiser + +Apologies if I missed anyone! + + +Global changes +-------------- + +closedir.3 +dirfd.3 +readdir.3 +rewinddir.3 +scandir.3 +seekdir.3 +telldir.3 + mtk + Fix 'dir' argument name: should be 'dirp'. + POSIX.1-2008 and glibc call this argument 'dirp' (consistent + with the fact that it is a *pointer* to a DIR structure). + + +Changes to individual pages +--------------------------- + +clone.2 + mtk, after a comment by John Reiser + Clarify text describing getpid() caching bug for clone() wrapper. + See also: + http://sourceware.org/bugzilla/show_bug.cgi?id=6910 + https://bugzilla.redhat.com/show_bug.cgi?id=417521 + +getpid.2 + mtk, after a comment by John Reiser + Describe getpid()'s PID caching and its consequences. + +timerfd_create.2 + Sam Varshavchik + s/it_interval/it_value/ when talking about TIMERFD_ABSTIME. + +closedir.3 + George Spelvin + Clarify closedir()'s treatment of underlying file descriptor. + +tsearch.3 + André Goddard Rosa + Fix memory leak in example program. + Add use of tdestroy to example program. + mtk + Add "#define _GNU_SOURCE" to example program. + +protocols.5 + mtk, after a note from Pavel Heimlich + Remove SEE ALSO references to nonexistent Guides to Yellow Pages + +services.5 + mtk + Remove some out-of-date bugs. + mtk, after a note from Pavel Heimlich + Remove SEE ALSO references to nonexistent Guides to Yellow Pages + and Bind/Hesiod docs. + mtk + Remove crufty text about use of comma instead of slash to separate + port and protocol. + + +==================== Changes in man-pages-3.11 ==================== + +Released: 2008-10-07, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +André Goddard Rosa +Eugene V. Lyubimkin +Gergely Soos +Kirill A. Shutemov +Marko Kreen +Maxin B. John +Maxin John +Michael Kerrisk +Nicolas François +Pavel Heimlich +Ricardo Catalinas Jiménez +Sam Varshavchik + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +umount.2 + Michael Kerrisk + Create a new page for umount() and umount2() by extracting + existing material from mount.2 page. + + +New and changed links +--------------------- + +umount2.2 + Michael Kerrisk + Change link to point to new umount.2 + The umount2() material migrated from mount.2 to umount.2 + + +Changes to individual pages +--------------------------- + +execve.2 + Michael Kerrisk + _SC_ARG_MAX is no longer necessarily constant + POSIX.1-2001 says that the values returned by sysconf() + are constant for the life of the process. + But the fact that, since Linux 2.6.23, ARG_MAX is settable + via RLIMIT_STACK means _SC_ARG_MAX is no longer constant, + since it can change at each execve(). + Michael Kerrisk + Linux now imposes a floor on the ARG_MAX limit + Starting with Linux 2.6.23, the ARG_MAX limit became + settable via (1/4 of) RLIMIT_STACK. This broke ABI + compatibility if RLIMIT_STACK was set such that ARG_MAX + was < 32 pages. Document the fact that since 2.6.25 + Linux imposes a floor on ARG_MAX, so that the old limit + of 32 pages is guaranteed. + + For some background on the changes to ARG_MAX in + kernels 2.6.23 and 2.6.25, see: + http://sourceware.org/bugzilla/show_bug.cgi?id=5786 + http://bugzilla.kernel.org/show_bug.cgi?id=10095 + http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101, + checked into 2.6.25 as + commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2. + + Also some reordering/rewording of the discussion of ARG_MAX. + +fallocate.2 + Michael Kerrisk + Note lack of glibc wrapper; caller must use syscall(2) + Glibc doesn't (and quite probably won't) include a + wrapper for this system call. Therefore, point out that + potential callers will need to use syscall(2), and rewrite + the RETURN VALUE text to show things as they would be if + syscall() is used. + + Michael Kerrisk + Refer reader to posix_fallocate(3) for portable interface + Add a para to start of page that points out that this is the + low-level, Linux-specific API, and point the reader to + posix_fallocate(3) for the portable API. + +getdents.2 +readdir.3 + Michael Kerrisk + d_type is currently only supported on ext[234] + As at kernel 2.6.27, only ext[234] support d_type. + On other file systems, d_type is always set to DT_UNKNOWN (0). + +getdents.2 + Michael Kerrisk + Add an example program + Michael Kerrisk + comment out linux_dirent fields with varying location + The location of the fields after d_name varies according to + the size of d_name. We can't properly declare them in C; + therefore, put those fields inside a comment. + Michael Kerrisk + The DT_* constants are defined in + Michael Kerrisk + Remove header files from SYNOPSIS + None of the header files provides what is needed. + Calls are made via syscall(2). + Michael Kerrisk + The programmer must define the linux_dirent structure + Point out that this structure is not defined in glibc headers. + Michael Kerrisk + s/dirent/linux_dirent/ + The structure isn't currently defined in glibc headers, + and the kernel name of the structure is 'linux_dirent' (as + was already used in some, but not all, places in this page). + +getrlimit.2 + Michael Kerrisk + Reword/relocate discussion of BSD's historical RLIMIT_OFILE + The old sentence sat on its own in an odd place, and anyway the + modern BSDs use the name RLIMIT_NOFILE. + Michael Kerrisk + Refer to execve(2) for RLIMIT_STACK's effect on ARG_MAX + Refer the reader to new text in execve(2) that describes how + (since Linux 2.6.23) RLIMIT_STACK determines the value of ARG_MAX. + +getrusage.2 + Michael Kerrisk + Rusage measures are preserved across execve(2) + +mlock.2 + Maxin John + Add EAGAIN error. + +move_pages.2 + Nicolas François + Make a detail of EPERM error more precise + +mount.2 + Michael Kerrisk + Add description of per-process namespaces + Describe per-process namespaces, including discussion + of clone() and unshare CLONE_NEWNS, and /proc/PID/mounts. + Michael Kerrisk + List a few other file systems that we may see in /proc/filesystems + Add some modern file systems to that list (xfs, jfs, ext3, + reiserfs). + Michael Kerrisk + Document MS_SILENT (and MS_VERBOSE) + +mount.2 +umount.2 + Michael Kerrisk + Split umount*() out into a separate page + The length of this page means that it's becoming difficult + to parse which info is specific to mount() versus + umount()/umount2(), so split the umount material out into + its own page. + +pause.2 + Michael Kerrisk + Remove mention of words "library function" + This really is a system call. + +readdir.2 + Michael Kerrisk + The programmer must declare the old_linux_dirent structure + Glibc does not provide a definition of this structure. + Michael Kerrisk + s/dirent/old_linux_dirent/ + Nowadays, this is the name of the structure in the + kernel sources. + Michael Kerrisk + Remove words "which may change" + These words are slightly bogus: although the interface + is obsolete, for ABI-compatibility reasons, the kernel folk + should never be changing this interface. + Michael Kerrisk + Remove header files from SYNOPSIS + glibc doesn't provide any support for readdir(2), + so remove these header files (which otherwise suggest + that glibc does provide the required pieces). + +recv.2 + Nicolas François + Move kernel version number to first mention to MSG_ERRQUEUE. + +semop.2 + Kirill A. Shutemov + Fix typo in example + (The '&' before sop in the semop() call is unneeded.) + +send.2 + Michael Kerrisk + Make kernel version for MSG_CONFIRM more precise + s/2.3+ only/Since Linux 2.3.15/ + +sigaction.2 + Michael Kerrisk + Refer reader to signal(7) for an overview of signals + Explain semantics of signal disposition during fork() and execve() + Refer to signal(7) for more details on signal mask. + +sigaltstack.2 + Michael Kerrisk + Explain inheritance of alternate signal stack across fork(2) + +sigwaitinfo.2 + Michael Kerrisk + Distinguish per-thread and process-wide signals + A sentence clarifying that pending signal set is union of + per-thread and process-wide pending signal sets. + + Michael Kerrisk + These interfaces have per-thread semantics + The page was previously fuzzy about whether the these interfaces + have process-wide or per-thread semantics. (E.g., now the + page states that the calling *thread* (not process) is suspended + until the signal is delivered.) + +sigpending.2 + Michael Kerrisk + Explain effect of fork() and execve() for pending signal set + Michael Kerrisk + Explain how thread's pending signal set is defined + The pending set is the union of per-thread pending signals + and process-wide pending signals. + +sigprocmask.2 + Michael Kerrisk + Explain effects of fork() and execve() for signal mask + +splice.2 + Michael Kerrisk + Note that SPLICE_F_MOVE is a no-op since kernel 2.6.21 + +syscall.2 + Michael Kerrisk + Add more detail about wrapper functions + Add a few more details about work generally done by wrapper + functions. Note that syscall(2) performs the same steps. + +tkill.2 + Michael Kerrisk + EINVAL error can also occur for invalid TGID + The EINVAL error on an invalid TGID for tgkill() was + not documented; this change documents it. + +utimensat.2 + Michael Kerrisk + POSIX.1-2008 revision will likely affect FTMs for futimens() + Make it clear that the POSIX.1 revision that is likely + to affect the feature test macro requirements for futimens() + is POSIX.1-2008. + Nicolas François + Make various wordings a little more precise. + The times argument point to *an array of* structures, and the + man-page should say that consistently. + +wait4.2 + Michael Kerrisk + wait3() is a library function layered on wait4(). + On Linux wait3() is a library function implemented on top + of wait4(). (Knowing this is useful when using strace(2), + for example.) + +atan2.3 + Nicolas François + Fix error in description of range or return value + In recent changes to the man page, mtk accidentally changed + the description of the return value range to -pi/2..pi/2; + the correct range is -pi..pi. + +cmsg.3 + Nicolas François + Add parentheses after macro names. + +ctime.3 + Michael Kerrisk + Clarify mktime()'s use of tm_isdst + Describe use of tm_isdst for input to mktime(); + explain how mktime() modifies this field. + (This field is left unchanged in case of error.) + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=500178 + Michael Kerrisk + Clarify wording for ctime_r() and asctime_r() to indicate that + the buffer must be at least 26 *bytes*. + Michael Kerrisk + Minor rewording of mktime() description. + +floor.3 + Nicolas François + floor.3: Fix error in description: s/smallest/largest/ + +hsearch.3 + André Goddard Rosa + Call hdestroy() after using hash table created by hcreate(), + for the sake of completeness + +mq_getattr.3 + Michael Kerrisk + mq_getattr() and mq_setattr() are layered on mq_getsetattr(2) + mq_getattr() and mq_setattr() are library functions layered on + top of the mq_getsetattr(2) system call. + (This is useful info for users of strace(1).) + +mq_receive.3 + Michael Kerrisk + mq_send() is a library function layered on mq_timedreceive() syscall + This info is useful for users of strace(1). + +mq_send.3 + Michael Kerrisk + mq_send() is a library function layered on mq_timedsend() syscall + This info is useful for users of strace(1). + +nextafter.3 + Nicolas François + Make description more precise: s/next/largest/ + +readdir.3 + Michael Kerrisk + SEE ALSO: add getdents(2) + Because readdir() is implemented on top of getdents(2). + +realpath.3 + Michael Kerrisk + Clarify that returned pathname is NULL terminated + Also clarify that null-byte is included in PATH_MAX limit. + +proc.5 + Michael Kerrisk + Rewrite and simplify description of /proc/mounts + Most of the relevant discussion is now under /proc/PID/mounts; + all that needs to be here is a mention of the pre-2.4.19 + system-wide namespace situation, and a reference to the + discussion under /proc/PID/mounts. + Michael Kerrisk + Add description of /proc/PID/mounts + Largely cribbed from existing /proc/mounts discussion, which is + about to be rewritten. + +mq_overview.7 + Michael Kerrisk + Add mq_notify() to list of lib. functions and syscalls in MQ API + +signal.7 + Michael Kerrisk + Improve description in NAME section + Add mention of sigaltstack(2). + Describe syscalls that synchronously wait for a signal, + Give overview of syscalls that block until a signal is caught + Add overview of interfaces for sending signals. + + Michael Kerrisk + Describe semantics w.r.t. fork() and execve() + Include text describing semantics of fork() and execve() for + signal dispositions, signal mask, and pending signal set. + + +==================== Changes in man-pages-3.12 ==================== + +Released: 2008-10-29, Bucaramanga + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Bert Wesarg +Christian Grigis +Christoph Hellwig +Didier +Halesh S +J.H.M. Dassen (Ray) +Jason Spiro +Lefteris Dimitroulakis +Michael B. Trausch +Pierre Cazenave +Stefan Puiu + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pthread_attr_init.3 + Michael Kerrisk + New page for pthread_attr_init(3) and pthread_attr_destroy(3) + +pthread_attr_setdetachstate.3 + Michael Kerrisk + New page for pthread_attr_setdetachstate(3) and + pthread_attr_getdetachstate(3) + +pthread_attr_setguardsize.3 + Michael Kerrisk + New page for pthread_attr_setguardsize(3) and + pthread_attr_getguardsize(3) + +pthread_attr_setscope.3 + Michael Kerrisk + New page for pthread_attr_setscope(3) and pthread_attr_getscope(3) + +pthread_attr_setstack.3 + Michael Kerrisk + New page for pthread_attr_setstack(3) and pthread_attr_getstack(3) + +pthread_attr_setstackaddr.3 + Michael Kerrisk + New page for pthread_attr_setstackaddr(3) and + pthread_attr_getstackaddr(3) + +pthread_attr_setstacksize.3 + Michael Kerrisk + New page for pthread_attr_setstacksize(3) and + pthread_attr_getstacksize(3) + +pthread_create.3 + Michael Kerrisk + New page describing pthread_create(3) + +pthread_detach.3 + Michael Kerrisk + New page for pthread_detach(3) + +pthread_equal.3 + Michael Kerrisk + New page for pthread_equal(3) + +pthread_exit.3 + Michael Kerrisk + New page describing pthread_exit(3) + +pthread_getattr_np.3 + Michael Kerrisk + New page for pthread_getattr_np(3) + +pthread_join.3 + Michael Kerrisk + New page for pthread_join(3) + +pthread_self.3 + Michael Kerrisk + New page for pthread_self(3) + +pthread_tryjoin_np.3 + Michael Kerrisk + New page for pthread_tryjoin_np(3) and pthread_timedjoin_np(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +dup.2 + Michael Kerrisk + Add description of dup3() + dup3() was added in kernel 2.6.27. + +epoll_create.2 + Michael Kerrisk + Add description of new epoll_create1() + The new epoll_create1() system call appeared in Linux 2.6.27. + +eventfd.2 + Michael Kerrisk + Describe eventfd2() and EFD_NONBLOCK and EFD_CLOEXEC + Linux 2.6.27 added eventfd(), which supports a flags argument + that eventfd() did not provide. The flags so far implemented + are EFD_NONBLOCK and EFD_CLOEXEC, + +inotify_init.2 + Michael Kerrisk + Add description of inotify_init1() + The inotify_init1() system call was added in Linux 2.6.27. + +pipe.2 + Michael Kerrisk + Add description of new pipe2() syscall + pipe2() was added in 2.6.27. Describe the O_NONBLOCK and + O_CLOEXEC flags. + +signalfd.2 + Michael Kerrisk + Describe signalfd4() and SFD_NONBLOCK and SFD_CLOEXEC + Linux 2.6.27 added signalfd4(), which supports a flags argument + that signalfd() did not provide. The flags so far implemented + are SFD_NONBLOCK and SFD_CLOEXEC. + + +New and changed links +--------------------- + +dup3.2 + Michael Kerrisk + New link to dup.2 + dup.2 now contains the description of the new dup3() syscall. + +epoll_create1.2 + Michael Kerrisk + New link to epoll_create.2 + epoll_create.2 now includes a description of the new + epoll_create1() system call. + +eventfd2.2 + Michael Kerrisk + New link to eventfd.2 + The eventfd.2 page has some details on the eventfd2() system call, + which was new in Linux 2.6.27. + +inotify_init1.2 + Michael Kerrisk + New link to inotify_init.2 + inotify_init.2 now includes a description of the new + inotify_init1() system call. + +pipe2.2 + Michael Kerrisk + New link to pipe.2 + pipe(2) now contains a description of the new pipe2() syscall. + +pthread_attr_destroy.3 + Michael Kerrisk + New link to new pthread_attr_init.3 + +pthread_attr_getdetachstate.3 + Michael Kerrisk + New link to new pthread_attr_setdetachstate.3 + +pthread_attr_getguardsize.3 + Michael Kerrisk + New link to new pthread_attr_setguardsize.3 + +pthread_attr_getscope.3 + Michael Kerrisk + New link to new pthread_attr_setscope.3 + +pthread_attr_getstack.3 + Michael Kerrisk + New link to new pthread_attr_setstack.3 + +pthread_attr_getstackaddr.3 + Michael Kerrisk + New link to new pthread_attr_setstackaddr.3 + +pthread_attr_getstacksize.3 + Michael Kerrisk + New link to new pthread_attr_setstacksize.3 + +pthread_timedjoin_np.3 + Michael Kerrisk + New link to new pthread_tryjoin_np.3 + +signalfd4.2 + Michael Kerrisk + New link to signalfd.2 + signalfd.2 now includes text describing signalfd4() system call, + new in Linux 2.6.27. + + +Global changes +-------------- + +eventfd.2, getdents.2, mprotect.2, signalfd.2, timerfd_create.2, +wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, +fopencookie.3, getdate.3, getgrouplist.3, getprotoent_r.3, +getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, +makecontext.3, matherr.3, offsetof.3, pthread_attr_init.3, +pthread_create.3, pthread_getattr_np.3, sem_wait.3, strtol.3, core.5 + Michael Kerrisk + Add ".SS Program source" to EXAMPLE + Add ".SS Program source" to clearly distinguish shell session and + descriptive text from actual program code. + +eventfd.2, execve.2, getdents.2, ioprio_set.2, mprotect.2, +signalfd.2, timerfd_create.2, wait.2, backtrace.3, +clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, +getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, +gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, +malloc.3, matherr.3, offsetof.3, pthread_attr_init.3, +pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, +strtok.3, strtol.3, core.5, proc.5, cpuset.7, mq_overview.7 + Michael Kerrisk + Format user input in shell sessions in boldface + +frexp.3, strftime.3, strtok.3 + Michael Kerrisk + Relocate shell session above example program + Move the shell session text that demonstrates the use of + the example program so that it precedes the actual + example program. This makes the page consistent with the + majority of other pages. + + +Changes to individual pages +--------------------------- + +epoll_create.2 + Michael Kerrisk + Say more about unused epoll_create() 'size' arg + Supply a little more explanation about why the 'size' argument + of epoll_create() is nowadays ignored. + +eventfd.2 + Michael Kerrisk + Remove crufty text relating to flags argument + Remove sentence saying that glibc adds a flags argument + to the syscall; that was only relevant for the older + eventfd() system call. +getdents.2 + Christoph Hellwig + Fix text relating to DT_UNKNOWN and 'd_type' support + Some file systems provide partial support for 'dt_type', + returning DT_UNKNOWN for cases they don't support. + Update the discussion of 'd_type' and DT_UNKNOWN to + support this. + +getpeername.2, getsockname.2 + Michael Kerrisk + SEE ALSO: add ip(7) and unix(7) + +getsockopt.2 + Michael Kerrisk + EINVAL can also occur if 'optval' is invalid + In some cases, EINVAL can occur if 'optval' is invalid. + Note this, and point reader to an example in ip(7). + In response to: + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=216092 + +inotify_init.2 +pipe.2 +timerfd_create.2 + Michael Kerrisk + Clarify *_NONBLOCK description + Make it clear that the NONBLOCK flag sets an attribute in the new + open file description. + +sched_yield.2 + Michael Kerrisk + Rewrite description in terms of threads + The text formerly described the operation of sched_yield() in + terms of processes. It should be in terms of threads. + Michael Kerrisk + Add NOTES text on appropriate use of sched_yield() + Strategic calls to sched_yield() can be used to improve + performance, but unnecessary use should be avoided. + +sigaction.2 + Michael Kerrisk + Clarify that sa_mask affects the *per-thread* signal mask + The page didn't previously clearly explain the scope of the + signal mask that is affected by sa_mask. + +signalfd.2 + Michael Kerrisk + Remove crufty text relating to flags argument + Remove sentence saying that glibc adds a flags argument + to the syscall; that was only relevant for the older + signalfd() system call. + +sigprocmask.2 + Michael Kerrisk + Clarify that sigprocmask() operates on a per-thread mask + The first sentence of the page was vague on the scope of the + attribute changed by sigprocmask(). Reword to make this + clearer and add a sentence in NOTES to explicitly state that + the signal mask is a per-thread attribute. + +socket.2 + Michael Kerrisk + Document SOCK_NONBLOCK and SOCK_CLOEXEC flags + These flags, specified in the 'type' argument, are supported + since Linux 2.6.27. + +socketpair.2 + Michael Kerrisk + Refer to socket(2) for SOCK_CLOEXEC and SOCK_NONBLOCK + Refer the reader to socket(2) for a description of the SOCK_CLOEXEC + and SOCK_NONBLOCK flags, which are supported by socketpair() since + Linux 2.6.27. + +syscalls.2 + Michael Kerrisk + Add new 2.6.27 system calls + Add pipe2(), dup3(), epoll_create1(), inotify_init1(), + eventfd2(), signalfd4(). + +timerfd_create.2 + Michael Kerrisk + Document timerfd_create() TFD_CLOEXEC and TFD_NONBLOCK + TFD_CLOEXEC and TFD_NONBLOCK are supported since LInux 2.6.27. + +vfork.2 + Michael Kerrisk + Clarify meaning of "child releases the parent's memory" + The man page was not explicit about how the memory used by + the child is released back to the parent. + +ctime.3 + Michael Kerrisk + ctime_r() and localtime_r() need not set 'timezone' and 'daylight' + The man page already noted that these functions need not set + 'tzname', but things could be clearer: it tzset() is not called, + then the other two variables also are not set. + + Also, clarify that ctime() does set 'timezone' and 'daylight'. + +dlopen.3 + Michael Kerrisk + LD_LIBRARY_PATH is inspected once, at program start-up + Make it clear that LD_LIBRARY_PATH is inspected *once*, at + program start-up. (Verified from source and by experiment.) + +fmemopen.3 + Michael Kerrisk + Document binary mode (mode 'b') + Glibc 2.9 adds support to fmemopen() for binary mode opens. + Binary mode is specified by inclusion of the letter 'b' in + the 'mode' argument. + +getaddrinfo.3 + Michael Kerrisk + Clarify error descriptions with some examples + Clarify the description of some errors by giving examples + that produce the errors. (Text added for EAI_SERVICE and + EAI_SOCKTYPE.) + + Also, add an error case for EAI_BADFLAGS. + +gethostbyname.3 + Michael Kerrisk + Rationalize text on POSIX.1-2001 obsolete interfaces + POSIX.1 marks gethostbyname(), gethostbyaddr(), and 'h_errno' + as obsolete. The man page explained this, but with some + duplication. Remove the duplication, and otherwise tidy up + discussion of this point. + +popen.3 + Michael Kerrisk + Change one-line description in NAME + s%process I/O%pipe stream to or from a process% + Michael Kerrisk + Document 'e' (close-on-exec) flag + glibc 2.9 implements the 'e' flag in 'type', which sets the + close-on-exec flag on the underlying file descriptor. + +raise.3 + Michael Kerrisk + SEE ALSO: add pthread_kill(3) + +readdir.3 + Christoph Hellwig + Fix text relating to DT_UNKNOWN and 'd_type' support + (This mirrors the previous change to getdents.2) + Some file systems provide partial support for 'dt_type', + returning DT_UNKNOWN for cases they don't support. + Update the discussion of 'd_type' and DT_UNKNOWN to + support this. + +strcpy.3 + Jason Spiro + Strengthen warning about checking against buffer overruns + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=413940 + +tty_ioctl.4 + Michael Kerrisk + Explain capability requirements for TIOCCONS + Explain capability requirements for TIOCCONS, and describe + changes in 2.6.10 relating to capabilities. + Michael Kerrisk + Explain capability requirements for various ioctls + For TIOCSLCKTRMIOS, TIOCSCTTY, TIOCEXCL, explain the exact + capability that is required (the text formerly just said "root" + in each case). + +proc.5 + Michael Kerrisk + Document /proc/sys/kernel/threads-max + Defines the system-wide limit on the number of threads (tasks). + +utmp.5 + Pierre Cazenave + It is just "other" who should not have write perms on utmp + The page was vague before, saying that utmp should not be + writable by any user. This isn't true: it can be, and + typically is, writable by user and group. + +epoll.7 + Michael Kerrisk + Mention epoll_create1() as part of epoll API + epoll_create1() was added in Linux 2.6.27, and extends the + functionality of epoll_create(). + +inotify.7 + Michael Kerrisk + Mention inotify_init1() in overview of API + Discuss the new inotify_init1() system call in the overview of + the inotify API. + +ip.7 + Michael Kerrisk + Detail EINVAL error for IP_ADD_MEMBERSHIP socket option + In response to: + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=216092 + +iso_8859-7.7 + Lefteris Dimitroulakis + Add Drachma, Euro, and Greek Ypogegrammeni + Also, amend description of characters 0241 and 0242. + +man-pages.7 + Michael Kerrisk + Example shell sessions should have user input boldfaced + +pthreads.7 + Michael Kerrisk + Describe return value from pthreads functions + Describe the usual success (0) and failure (non-zero) returns, + and note that POSIX.1-2001 specifies that pthreads functions + can never fail with the error EINTR. + +signal.7 + Michael Kerrisk + Timeouts make socket interfaces non-restartable + If setsockopt() is used to set a timeout on a socket(), + then the various socket interfaces are not automatically + restarted, even if SA_RESTART is specified when + establishing the signal handler. Analogous behavior occurs + for the "stop signals" case. + +socket.7 + Michael Kerrisk + SEE ALSO: add unix(7) + +ld.so.8 + Michael Kerrisk + Document LD_USE_LOAD_BIAS + Drawing heavily on Jakub Jelinek's description in + http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html + (Subject: [PATCH] Support LD_USE_LOAD_BIAS) + --inhibit-rpath is ignored for setuid/setgid ld.so + The --inhibit-rpath option is ignored if ld.so is setuid/setgid + (not if the executable is setuid/setgid). + Michael Kerrisk + Since glibc 2.4, setuid/setgid programs ignore LD_ORIGIN_PATH + Michael Kerrisk + Fix description of LD_PROFILE and LD_PROFILE_OUTPUT + Clarify that LD_PROFILE is pathname or a soname, + and identify name of profiling output file. + Fix description of LD_PROFILE_OUTPUT, which wasn't even close to + the truth. (But why did it remain unfixed for so many years?) + Michael Kerrisk + Since glibc 2.3.4, setuid/setgid programs ignore LD_DYNAMIC_WEAK + Michael Kerrisk + Since version 2.3.5, setuid/setgid programs ignore LD_SHOW_AUXV + Michael Kerrisk + Reorder lists of LD_* environment variables alphabetically + Michael Kerrisk + Since glibc 2.3.4, setuid/setgid programs ignore LD_DEBUG + + +==================== Changes in man-pages-3.13 ==================== + +Released: 2008-11-07, Bucaramanga + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Bert Wesarg +Karsten Weiss +Lefteris Dimitroulakis +Olaf van der Spek +Sam Varshavchik +Török Edwin +Ulrich Mueller +Valdis Kletnieks + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pthread_attr_setaffinity_np.3 + Michael Kerrisk + New page for pthread_attr_setaffinity_np(3) and + pthread_attr_getaffinity_np(3) + +pthread_attr_setschedparam.3 + Michael Kerrisk + New page for pthread_attr_setschedparam(3) and + pthread_attr_getschedparam(3) + +pthread_attr_setschedpolicy.3 + Michael Kerrisk + New page for pthread_attr_setschedpolicy(3) and + pthread_attr_getschedpolicy(3) + +pthread_setaffinity_np.3 + Michael Kerrisk + New page for pthread_setaffinity_np(3) and pthread_getaffinity_np(3) + +pthread_setschedparam.3 + Michael Kerrisk + New page for pthread_setschedparam(3) and pthread_getschedparam(3) + +pthread_setschedprio.3 + Michael Kerrisk + New page for pthread_setschedprio(3) + + +New and changed links +--------------------- + +pthread_attr_getaffinity_np.3 + Michael Kerrisk + New link to new pthread_attr_setaffinity_np.3 + +pthread_attr_getschedparam.3 + Michael Kerrisk + New link to new pthread_attr_setschedparam.3 + +pthread_attr_getschedpolicy.3 + Michael Kerrisk + New link to new pthread_attr_setschedpolicy.3 + +pthread_getaffinity_np.3 + Michael Kerrisk + New link to new pthread_setaffinity_np.3 + +pthread_getschedparam.3 + Michael Kerrisk + New link to new pthread_setschedparam.3 + + +Global changes +-------------- + +pthread_attr_setaffinity_np.3 +pthread_getattr_np.3 +pthread_setaffinity_np.3 +pthread_tryjoin_np.3 + Michael Kerrisk + Explain _np suffix + Add text to CONFORMING TO explaining that the "_np" + suffix is because these functions are non-portable. + + +Changes to individual pages +--------------------------- + +sched_setaffinity.2 + Michael Kerrisk + SEE ALSO: add sched_getcpu(3) + +sched_setaffinity.2 + Michael Kerrisk + SEE ALSO: Add pthread_setaffinity_np(3) + +sched_setaffinity.2 + Michael Kerrisk + Clarify EINVAL error for cpusetsize < kernel mask size + For sched_setaffinity(), the EINVAL error that occurs + if 'cpusetsize' is smaller than the kernel CPU set size only + occurs with kernels before 2.6.9. + +vfork.2 + Michael Kerrisk + Child holds parent's memory until execve() or *termination* + The page was phrased in a few places to describe the child as + holding the parent's memory until the child does an execve(2) + or an _exit(2). The latter case should really be the more + general process termination (i.e., either _exit(2) or abnormal + termination). + +clock_getres.3 + Michael Kerrisk + CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID not settable + According to POSIX.1-2001, the CLOCK_PROCESS_CPUTIME_ID and + CLOCK_THREAD_CPUTIME_ID clocks should be settable, but + currently they are not. + +pthread_attr_setstacksize.3 + Michael Kerrisk, after a report by Karsten Weiss + EINVAL occurs on some systems if stacksize != page-size + On MacOS X at least, pthread_attr_setstacksize(3) can fail + with EINVAL if 'stacksize' is not a multiple of the system + page size. Best to mention this so as to aid people writing + portable programs. + +pthread_create.3 + Karsten Weiss + Fix bug in EXAMPLE program + The calloc() line should read like this instead: + + tinfo = calloc(num_threads, sizeof(struct thread_info)); + +pthread_exit.3 + Michael Kerrisk + BUGS: thread group with a dead leader and stop signals + Document the bug that can occur when a stop signal + is sent to a thread group whose leader has terminated. + http://thread.gmane.org/gmane.linux.kernel/611611 + http://marc.info/?l=linux-kernel&m=122525468300823&w=2 + +resolver.3 + Michael Kerrisk + Fix prototype of dn_expand() + The 4th argument is "char *", not "unsigned char *". + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504708 + +epoll.7 + Michael Kerrisk + Fix error handling after accept() in example code + Simply continuing after an error is in most cases wrong, + and can lead to infinite loops (e.g., for EMFILE). + So handle an error by terminating. + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504202 + +epoll.7 + Michael Kerrisk + Add error handling for epoll_wait() call in example code + +epoll.7 + Michael Kerrisk + Improve example code + Fill in some gaps in example code (variable declarations, + adding listening socket to epoll set). + Give variables more meaningful names. + Other minor changes. + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504202 + +iso_8859-7.7 + Lefteris Dimitroulakis + Add characters for Drachma and Greek Ypogegrammeni + Lines for these two characters were added in the previous patch, + but the actual characters were not included in the 4th column + of the table. This fixes that. + +pthreads.7 + Michael Kerrisk + Add a section describing thread IDs + In particular, note that in each pthreads function that takes + a thread ID argument, that ID by definition refers to a thread + in the same process as the caller. + + +==================== Changes in man-pages-3.14 ==================== + +Released: 2008-11-25, Bucaramanga + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andreas Henriksson +Bert Wesarg +Cedric Le Goater +Chris Heath +Eric Biederman +Eugen Dedu +Ivana Varekova +Jen Axboe +Jens Axboe +Loïc Domaigne +Masanari Iida +Paul Evans +Pavel Emelyanov +Pierre-Paul Paquin +Serge E. Hallyn +Stefano Teso +Stew Benedict +Vegard Nossum + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +CPU_SET.3 + Michael Kerrisk + New page documenting CPU_* macros + This page contains material moved out of sched_setscheduler(2). + It overwrites a previously existing link file with the same name. + Michael Kerrisk + Add description of macros for dynamically allocated CPU sets + Add descriptions of CPU_ALLOC(), CPU_ALLOC_SIZE(), CPU_FREE(), + CPU_SET_S(), CPU_CLR_S(), CPU_ISSET_S(), CPU_ZERO_S(), + CPU_COUNT_S(), CPU_AND_S(), CPU_OR_S(), CPU_XOR_S(), and + CPU_EQUAL_S(). + Michael Kerrisk + Add documentation of CPU_COUNT() + Michael Kerrisk + Add description of CPU_AND(), CPU_OR, CPU_XOR(), and CPU_EQUAL() + Plus a few other small clean-ups of the text + Michael Kerrisk + Various improvements in DESCRIPTION + After review comments by Bert Wesarg: + * Explain that cpu_set_t is a bitset, but should be considered + opaque. + * A CPU set can be duplicated with memset(). + * Size of a CPU set is rounded up to size of long. + * CPU_SETSIZE is in bits, but the setsize argument is in bytes. + Michael Kerrisk + Document CPU_ALLOC()/CPU_ALLOC_SIZE() bug + These macros return twice what they should because of thinko + in glibc 2.8 and earlier. The bug is fixed for glibc 2.9. + http://sourceware.org/bugzilla/show_bug.cgi?id=7029 + Michael Kerrisk + NOTES: Discuss use of types in "prototypes" for these macros + The SYNOPSIS shows types for arguments and return values, but + these are really just suggestions: since the interfaces are + macros, the compiler won't catch all violations of + the "type rules". Warn the reader of this. + +pthread_attr_setinheritsched.3 + Michael Kerrisk + New page for pthread_attr_setinheritsched(3) and + pthread_attr_getinheritsched(3) + +pthread_cancel.3 + Michael Kerrisk + New page for pthread_cancel(3) + +pthread_cleanup_push.3 + Michael Kerrisk + New page for pthread_cleanup_push(3) and pthread_cleanup_pop(3) + +pthread_setcancelstate.3 + Michael Kerrisk + New page for pthread_setcancelstate(3) and pthread_setcanceltype(3) + +pthread_testcancel.3 + Michael Kerrisk + New page for pthread_testcancel(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +clone.2 + Jens Axboe + Document CLONE_IO (new in Linux 2.6.25) + Some text also by mtk. + Michael Kerrisk + Document CLONE_NEWNET + Michael Kerrisk + Document CLONE_NEWUTS (new in Linux 2.6.19) + Michael Kerrisk + Document CLONE_NEWIPC flag (new in Linux 2.6.19) + Michael Kerrisk + Document CLONE_NEWPID flag (new in Linux 2.6.24) + +mmap.2 + Michael Kerrisk + Document MAP_STACK flag (new in Linux 2.6.27) + +arp.7 + Michael Kerrisk + Document /proc file retrans_time_ms (new in Linux 2.6.12) + Michael Kerrisk + Document /proc file base_reachable_time_ms (new in Linux 2.6.12) + +icmp.7 + Michael Kerrisk + Document icmp_ignore_bogus_error_responses (new in Linux 2.2) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document icmp_ratelimit and icmp_ratemask (new in Linux 2.4.10) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document icmp_echo_ignore_broadcasts (new in Linux 2.6.12) + Text taken from Documentation/networking/ip-sysctl.txt + +tcp.7 + Michael Kerrisk + Document /proc file tcp_slow_start_after_idle (new in Linux 2.6.18) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_base_mss (new in Linux 2.6.17) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_frto_response (new in Linux 2.6.22) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_moderate_rcvbuf (new in Linux 2.4.17/2.6.7) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_congestion_control (new in Linux 2.4.13) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_no_metrics_save (new in Linux 2.6.6) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_mtu_probing (new in Linux 2.6.17) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_dma_copybreak (new in Linux 2.6.24) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_tso_win_divisor (new in Linux 2.6.9) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_allowed_congestion_control (new in Linux 2.4.20) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_workaround_signed_windows (new in Linux 2.6.26) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_available_congestion_control (new in Linux 2.4.20) + Text taken from Documentation/networking/ip-sysctl.txt + Michael Kerrisk + Document /proc file tcp_abc (new in Linux 2.6.15) + Text taken from Documentation/networking/ip-sysctl.txt + +udp.7 + Michael Kerrisk + Document /proc files udp_mem, udp_rmem_min, and udp_wmem_min + All of these are new in Linux 2.6.25 + + +New and changed links +--------------------- + +CPU_ALLOC.3 +CPU_ALLOC_SIZE.3 +CPU_AND.3 +CPU_AND_S.3 +CPU_CLR_S.3 +CPU_COUNT.3 +CPU_COUNT_S.3 +CPU_EQUAL.3 +CPU_EQUAL_S.3 +CPU_FREE.3 +CPU_ISSET_S.3 +CPU_OR.3 +CPU_OR_S.3 +CPU_SET_S.3 +CPU_XOR.3 +CPU_XOR_S.3 +CPU_ZERO_S.3 + Michael Kerrisk + New link to new CPU_SET.3 + +CPU_CLR.3 +CPU_ISSET.3 +CPU_ZERO.3 + Michael Kerrisk + Update links to point to CPU_SET.3 + The documentation of the CPU_* macros migrated to a new + location: CPU_SET.3. + +pthread_attr_getinheritsched.3 + Michael Kerrisk + New link to new pthread_attr_setinheritsched.3 + +pthread_cleanup_pop.3 + Michael Kerrisk + New link to new pthread_cleanup_push.3 + +pthread_setcanceltype.3 + Michael Kerrisk + New link to new pthread_setcancelstate.3 + + +Global changes +-------------- + +clone.2 +mount.2 +unshare.2 +proc.5 +path_resolution.7 + Michael Kerrisk + Global fix: s/namespace/mount-point namespace/, as appropriate + In recent times, a number of other namespace flags have been + added to clone(2). As such, it is no longer clear to use + the generic term "namespace" to refer to the particular + namespace controlled by CLONE_NEWNS; instead, use the + term "mount-point namespace". + Michael Kerrisk + Global fix: s/mount-point namespace/mount namespace/ + This is more consistent with the term "mounts namespace" + used in the 2008 ACM SIGOPS paper, "Virtual servers + and checkpoint/restart in mainstream Linux". + (I avoided the "s", because using the plural strikes me + as klunky English, and anyway we don't talk about + the "PIDs namespace" or the "networks namespace", etc..) + +connect.2 +listen.2 +send.2 +uname.2 +cmsg.3 +proc.5 +arp.7 +ddp.7 +icmp.7 +ip.7 +raw.7 +socket.7 +tcp.7 +udp.7 + Michael Kerrisk + Global fix: eliminate mention of the obsolete sysctl(2) interface + Many pages still mention use of the obsolete sysctl(2) system + call, or used the term "sysctls"; rewrite these mentions to + instead be in terms of /proc interfaces. + +fcntl.2 +signal.2 +mbsnrtowcs.3 +mbsrtowcs.3 +mbtowc.3 +wcrtomb.3 +wcsnrtombs.3 +wcsrtombs.3 +wctomb.3 + Michael Kerrisk + Global fix: s/multi-thread/multithread/ + +getdents.2 +pthread_attr_init.3 +pthread_create.3 +pthread_getattr_np.3 +pthread_setaffinity_np.3 +pthread_setschedparam.3 +pthread_tryjoin_np.3 + Michael Kerrisk + Use consistent error-handling function names + Many older pages use a handle_error() macro to do simple + error handling from system and library function calls. + Switch these pages to do similar. + + +Changes to individual pages +--------------------------- + +time.1 + Michael Kerrisk + Note that some shells have a 'time' built-in command + Therefore, to access the functionality described on this page, + it may be necessary to specify the full pathname. + +clone.2 + Michael Kerrisk + Place list of CLONE_* flags in alphabetical order + (No content changes.) +fsync.2 + Michael Kerrisk + Update feature test macro requirements for fsync() + Since glibc 2.8, the fsync() declaration is also exposed if + _POSIX_C_SOURCE >= 200112L + +sched_setaffinity.2 + Michael Kerrisk + Add note on system-imposed restrictions on CPUs actually used + After Loïc Domaigne's suggestion for pthread_setaffinity_np(3), add + similar text to this page noting that the system silently + limits the set of CPUs on which the process actually runs to + the set of CPUs physically present and the limits imposed by + cpuset(7). + +sched_setaffinity.2 + Michael Kerrisk + Removed discussion of CPU_* macros() + These macros are now moving to a separate page. + Michael Kerrisk + Refer reader to pthread_setaffinity_np(3) + pthread_setaffinity_np() is preferable for setting + thread CPU affinity if using the POSIX threads API. + +sysctl.2 + Michael Kerrisk + Add prominent warning against using this system call + This was already stated under NOTES, but make it even more + prominent by adding a sentence at the start of the DESCRIPTION. + +uname.2 + Michael Kerrisk + Add C comments describing fields in utsname structure + +atan2.3 + Stefano Teso + Fix description of range of function value return + The range is not [-pi/2, pi/2], but [-pi, pi]. + + (mtk: This error was reported by Nicolas François, and + should have been fixed in 3.11, but somewhere along the way, + the fix got lost.) + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=506299 + +bindresvport.3 + Michael Kerrisk + Since glibc 2.8, EPFNOSUPPORT error is now EAFNOSUPPORT + Glibc switched to using a POSIX-specified error code for + this error case. + + http://bugs.linuxbase.org/show_bug.cgi?id=2375 + +clock_getres.3 + Michael Kerrisk + CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID not settable + According to POSIX.1-2001, the CLOCK_PROCESS_CPUTIME_ID and + CLOCK_THREAD_CPUTIME_ID clocks should be settable, but + currently they are not. + +getgrnam.3 + Michael Kerrisk + Clarify and add more detail in RETURN VALUE description + The page was a bit fuzzy in describing the return values for + various cases. In particular, it needed to be more explicit + in describing what happens for the "not found" case. + + This is an analogous change to the change for + getpwnam.3, made after Andreas Henriksson's report. + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504787 + Michael Kerrisk + Rename arguments to getgrnam_r() and getgrgid_r() + s/gbuf/grp/ and s/gbufp/result/, for consistency + with POSIX.1 argument names. + Michael Kerrisk + Clarify RETURN VALUE description + The page was a bit fuzzy in describing the return values for + various cases. In particular, it needed to be more explicit + in describing what happens for the "not found" case. + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504708 + +getpwnam.3 + Michael Kerrisk + Rename arguments to getpwnam_r() and getpwuid_r() + s/pwbuf/pwd/ and s/pwbufp/result/, for consistency + with POSIX.1 argument names. + Michael Kerrisk + Clarify and add more detail in RETURN VALUE description + The page was a bit fuzzy in describing the return values for + various cases. In particular, it needed to be more explicit + in describing what happens for the "not found" case. + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504787 + Michael Kerrisk + Add an EXAMPLE program for getpwnam_r() + +inet_ntop.3 + Michael Kerrisk + Rename 'cnt' argument to 'size' + This is consistent with POSIX.1, and also a more sensible name. + Michael Kerrisk + Rework text describing 'size' argument + (After a suggestion by Vegard Nossum.) + Also made a few other small rewordings to in the initial + paragraph. + +makecontext.3 + Michael Kerrisk + Add text on use of pointer arguments to makecontext() + Passing pointer arguments to makecontext() is possible, + but only on some architectures, and with no guarantees + of portability. + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504699 + +pthread_attr_setaffinity_np.3 + Michael Kerrisk + Various fixes after review by Loïc Domaigne + Reviewed-by: Loïc Domaigne + +pthread_attr_setaffinity_np.3 +pthread_setaffinity_np.3 + Michael Kerrisk + Update to reflect new location of CPU_*() documentation + The CPU_*() macros are now documented in CPU_SET.3; + update to reflect that fact. + Michael Kerrisk + Remove redundant text relating to CPU sets + Information about CPU_SETSIZE can be found in CPU_SET.3, so + remove discussion of it here. + +pthread_attr_setschedparam.3 +pthread_setschedparam.3 + Michael Kerrisk + Remove text saying that only sched_priority is required by POSIX.1 + Loïc Domaigne points out that if a system implements + SCHED_SPORADIC (which Linux does not), then other + fields are also specified in sched_param. The simple + solution is just to remove that phrase from the man + page. + +pthread_cancel.3 +pthread_detach.3 +pthread_join.3 +pthread_setaffinity_np.3 + Michael Kerrisk + Make text of ESRCH error consistent + +pthread_setaffinity_np.3 + Michael Kerrisk + Add text to EINVAL error mentioning cpuset(7) + Michael Kerrisk + Various improvements after review by Loïc Domaigne + Various fix-ups after Loïc's review. + + Reviewed-by: Loïc Domaigne + +pthread_setschedparam.3 + Michael Kerrisk + PTHREAD_INHERIT_SCHED is default for inherit scheduler attribute + In EXAMPLE, note that PTHREAD_INHERIT_SCHED is the default for + the inherit scheduler attribute. + +syslog.3 + Masanari Iida + LOG_KERN messages can't be generated from user processes + Masanari notes that this is an FAQ for logger(1) and that + Solaris and FreeBSD document this point in syslog(3). + The glibc info page also hides this comment in its source: + + Internally, there is also LOG_KERN, but LOG_KERN == 0, + which means if you try to use it here, just selects default. + +proc.5 + Ivana Varekova + Fix reference to kernel source file + Use relative reference to Documentation/mtrr.txt. + +arp.7 + Michael Kerrisk + Add kernel version numbers for /proc interfaces + +cpuset.7 + Michael Kerrisk + SEE ALSO: add CPU_SET(3) + +epoll.7 + Michael Kerrisk + Note glibc version that added epoll support + +icmp.7 + Michael Kerrisk + Add kernel version numbers to /proc file descriptions + +inotify.7 + Vegard Nossum + Fix description of max_user_watches + It seems that inotify(7) is wrong here: + + "/proc/sys/fs/inotify/max_user_watches + This specifies a limit on the number of watches that can be + associated with each inotify instance." + + On my system, the default value for this variable is 8192. But I + cannot create more than 8192 watches in total for the same UID + even when they are on different inotify instances. So I suggest + to rephrase this as: "This specifies an upper limit on the + number of watches that can be created per real user ID." + +ip.7 + Michael Kerrisk + Reorder socket options alphabetically + Michael Kerrisk + Added kernel version numbers for IP_* socket options + Michael Kerrisk + Relocate kernel version information for IP_PMTUDISC_PROBE + Michael Kerrisk + Add kernel version numbers for /proc/sys/net/ipv4/ip_* files + Michael Kerrisk + Remove mention of kernel header from description of IP_RECVERR + Looks like glibc has had this definition since about version 2.1. + Michael Kerrisk + Relocate kernel version information for ip_mreqn structure + Michael Kerrisk + Relocate info about Linux-specific sockopts to NOTES + Also add some source comments about non-standard Linux-specific + options that are not yet documented. + +netlink.7 + Vegard Nossum + Fix incorrect variable names in example code + s/snl/sa/ * 2 + +pthreads.7 + Michael Kerrisk + Add section on cancellation points + This section includes a list of the functions that must and + may be cancellation points. + Michael Kerrisk + Rework, and fix small error in, thread-safe function list + Integrate the changes that occurred in POSIX.1-2008 into the + main list (to be consistent with the list, elsewhere on this + page, of functions that are cancellation points). + + Also, fix an error that said that strerror() was added to + the list in POSIX.1-2008. It was strsignal() that was + added. (strerror() was already in the list in POSIX.1-2001.) + Michael Kerrisk + Tweak text on sigpause() cancellation point + In POSIX.1-2008, this function moves from the "must be" + to the "may be" list. + Michael Kerrisk + Add ref to signal(7) for further info on use of real-time signals + signal(7) provides some further details on the use of real-time + signals by the two Linux threading implementations. + Michael Kerrisk + SEE ALSO: add pthread_attr_init() and pthread_cancel() + +tcp.7 + Michael Kerrisk + Update description of tcp_rmem defaults for Linux 2.6 + Michael Kerrisk + Add kernel version numbers for TCP_* socket options + Note kernel version were each socket option first appeared. + Michael Kerrisk + The tcp_bic* proc files disappeared in Linux 2.6.13 + Michael Kerrisk + tcp_vegas_cong_avoid disappeared in Linux 2.6.13 + Michael Kerrisk + Add mention of RFC 4138 for 'tcp_frto' /proc file + Michael Kerrisk + Remove mention of /proc in VERSIONS + This information is not indicated for each /proc interface + Michael Kerrisk + Clarify that tcp_mem measures in units of the system page size + Michael Kerrisk + Update tcp_frto description for 2.6.22 changes + Linux 2.6.22 added a mode value 2 ("Enable SACK-enhanced + F-RTO if flow uses SACK"). + Michael Kerrisk + Fix alphabetical order in /proc file list + A few entries were slightly out of order. + Michael Kerrisk + Remove obsolete statement about /proc from VERSIONS + Much of the text has been updated to 2.6.27 or so, + so this statement no longer applies. + Michael Kerrisk + Add kernel version numbers for each /proc interface + Note kernel version where each /proc interface first appeared + Michael Kerrisk + tcp_westwood /proc file disappeared in Linux 2.6.13 + Michael Kerrisk + Update description of tcp_wmem defaults for Linux 2.6 + + +==================== Changes in man-pages-3.15 ==================== + +Released: 2008-12-05, Bucaramanga + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andre Majorel +Andries E. Brouwer +Chris Heath +Drake Wilson +Mats Wichmann +Mel Gorman +Michael Kerrisk +Mike Fedyk +Pavel Machek +Petr Baudis +Phil Endecott +Rob Landley +Sam Varshavchik + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +makedev.3 + Michael Kerrisk + New page for makedev(), major(), and minor() macros + +pthread_cleanup_push_defer_np.3 + Michael Kerrisk + New page for pthread_cleanup_push_defer_np(3) and + pthread_cleanup_pop_restore_np(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +accept.2 + Michael Kerrisk + Document accept4() system call, new in Linux 2.6.28 + +fmemopen.3 + Petr Baudis + Add description of open_wmemstream(3) + +tcp.7 + Michael Kerrisk + Document MSG_TRUNC flag for TCP sockets + +New and changed links +--------------------- + +accept4.2 + Michael Kerrisk + New link to accept.2 + accept.2 now documents the new accept4() system call. + +open_wmemstream.3 + Petr Baudis + New link to fmemopen.3 + fmemopen.3 now documents open_wmemstream(). +pthread_cleanup_pop_restore_np.3 + Michael Kerrisk + New link to new pthread_cleanup_push_defer_np.3 + + +Global changes +-------------- + +accept.2 +listen.2 +recv.2 +getpeername.2 +getsockname.2 +shutdown.2 +socketpair.2 + Michael Kerrisk + Global fix: SEE ALSO: add socket(7) + +bind.2 +rcmd.3 +capabilities.7 +ip.7 + Michael Kerrisk + Global fix: s/reserved port/privileged port/ + Some pages used one term, some pages the other term; + make some consistency. + +connect.2 +getpeername.2 +getsockname.2 + Michael Kerrisk + Use consistent argument names + Most other sockets pages are using the names 'addr' + and 'addrlen'; make these pages do the same. + +getpeername.2 +getsockname.2 +getsockopt.2 +recv.2 +send.2 +shutdown.2 +sockatmark.3 +socket.7 +udplite.7 + Michael Kerrisk + SYNOPSIS: Rename socket file descriptor argument to 'sockfd' + Many sockets man pages use the name 'sockfd' already. + For consistency, changes the others to do so as well. + +gnu_dev_major.3 +gnu_dev_makedev.3 +gnu_dev_minor.3 +major.3 +minor.3 + Michael Kerrisk + New links to new makedev(3) page + + +Changes to individual pages +--------------------------- + +_exit.2 + Michael Kerrisk + Since glibc 2.3, the exit() wrapper function invokes exit_group(2) + This information is useful to users of strace(1). + +accept.2 + Michael Kerrisk + Clarify details when returned address is truncated + If the returned address is truncated, the 'addrlen' argument + indicates the actual size of the address, rather than a count + of the number of bytes in the truncated buffer. + + Also clarify that if 'addr' argument is NULL, then 'addrlen' + should is unused, and should also be NULL. + Michael Kerrisk + Reorder ERRORS list + Some errors were listed under a separate "may" heading. + There's probably no real need to do this; integrate + those errors into the main list. + +exit_group.2 + Michael Kerrisk + Note that since glibc 2.3, exit(2) invokes exit_group() + +futex.2 + Michael Kerrisk + Mention that glibc provides no wrapper function for futex() + +get_thread_area.2 + Michael Kerrisk + Note that glibc provides no wrapper for this system call + +getdomainname.2 + Michael Kerrisk + Substantial rewrite + Expand description of setdomainname() and getdomainname(). + Note that getdomainname() is implemented as a library function + in glibc. + Note limits on size of domain name. + Reorganize ERRORS list. + +gethostname.2 + Michael Kerrisk + Various parts rewritten + Write a paragraph describing sethostname(). + + Clarify differences between glibc's gethostbyname() and + the kernel gethostbyname() system calls. + +gethostname.2 + Michael Kerrisk + Note that HOST_NAME_MAX is 64 on Linux + Also note that in pre-1.0 days, the limit on hostnames + was 8 bytes. + +getpeername.2 + Michael Kerrisk + Note that returned address may be truncated if buffer is too small + +getsid.2 + Michael Kerrisk + Simplified version information and moved to a new VERSIONS section + +getsockname.2 + Michael Kerrisk + Note that returned address is truncated if buffer is too small + +mknod.2 + Michael Kerrisk + Refer reader to makedev(3) to build a device ID + +mmap.2 + Michael Kerrisk + Loosen language around how 'addr' hint is interpreted + Mel Gorman reported that in Linux 2.6.27, 'addr' is rounded + down to a page boundary. + + Before kernel 2.6.26, if 'addr' was taken as a hint, it was + rounded up to the next page boundary. Since Linux 2.6.24, + it is rounded down. Therefore, loosen the description of + this point to say that the address is rounded to "a nearby + page boundary". + +open.2 + Michael Kerrisk + EFBIG error is now EOVERFLOW (since Linux 2.6.24) + When a 32-bit app opens a file whose size is too big to be + represented in 31-bits, POSIX.1 specifies the error EOVERFLOW. + Linux used to give EFBIG for this case, but 2.6.24 fixed this. + + Also, add some text to describe the error scenario in + more detail. + +pread.2 + Michael Kerrisk + Note that glibc emulation for these calls uses lseek(2) + (This makes it clearer that the emulated calls are not atomic.) + +recv.2 +send.2 + Michael Kerrisk + Make names of "address" and "address length" args more consistent + Make the names of these arguments more consistent with other + sockets man pages. + +recv.2 + Michael Kerrisk + Clarify details when returned address is truncated + If the recvfrom() returned address is truncated, the 'fromlen' + argument indicates the actual size of the address, rather than + a count of the number of bytes in the truncated buffer. + + Also clarify that the 'from' argument can be NULL, in which + case 'fromlen' should is unused, and should also be NULL. + Michael Kerrisk + Internet datagram and netlink sockets support MSG_TRUNC for recv(2) + Internet datagram (since Linux 2.4.27/2.6.8), + and netlink (since Linux 2.6.22) sockets support + the MSG_TRUNC flag for recv(2). + +select.2 + Michael Kerrisk + Rewrote text describing feature test macros requirement for pselect() + +select_tut.2 + Michael Kerrisk + Fix SHUT_FD* macros in example program + Add "do {} while (0)" + +set_thread_area.2 + Michael Kerrisk + Note that glibc provides no wrapper for this system call + +setfsgid.2 +setfsuid.2 + Michael Kerrisk + Simplify version information and move to a VERSIONS section + +setsid.2 + Michael Kerrisk + Rework RETURN VALUE section; add an ERRORS section + +setup.2 + Michael Kerrisk + Relocate some CONFORMING TO text to VERSIONS and NOTES + +stat.2 + Michael Kerrisk + Document EOVERFLOW error + Michael Kerrisk + Refer reader to major() and minor() to decompose a device ID + +syscalls.2 + Michael Kerrisk + Fix version numbers for a few system calls + Some 2.6 system calls were wrongly mentioned as also being + backported into a 2.4.x kernel. + +uname.2 + Michael Kerrisk + DESCRIPTION: Point reader at NOTES for further info on field lengths + +atan.3 + Andries E. Brouwer + Fix return value description + The correct range for the return value is [-pi/2,pi/2]. + (mtk's fix in the last change to the return value text was + a botch-up of a (correct) suggestion by Nicolas François.) + +atexit.3 + Michael Kerrisk + atexit() and on_exit(3) register functions on the same list + Michael Kerrisk + Terminating registered function using longjmp() is undefined + According to POSIX.1, using longjmp() to terminate execution of + a function registered using atexit() produces undefined results. + Michael Kerrisk + Calling exit(3) more than once produces undefined results + If an exit handler itself calls exit(3), the results are + undefined (see the POSIX.1-2001 specification of exit(3)). + Michael Kerrisk + The same exit handler may be registered multiple times + Michael Kerrisk + Calling _exit(2) terminates processing of exit handlers + Michael Kerrisk + Terminating registered function using longjmp() is undefined + According to POSIX.1, using longjmp() to terminate execution of + a function registered using atexit() produces undefined results. + +bindresvport.3 + Mats Wichmann + SYNOPSIS: s/\*\*/*/ in prototype + Michael Kerrisk + Fix errors regarding port used, plus other rewrites + Glibc's bindresvport() takes no notice of sin->sin_port: + it always returns an arbitrary reserved port in the + anonymous range (512-1023). (Reported by Mats Wichmann.) + + Also: + * Add EADDRINUSE and EACCES errors. + * Mention use of getsockname(2). + * Other minor rewrites and reorderings of the text. + * Explicitly note that glib's bindresvport() ignores + sin->sin_port. + * Change license There's now virtually no text remaining from + the 1.70 version of this page. + + Reviewed-by: Mats Wichmann + Reviewed-by: Petr Baudis + +dlopen.3 + Petr Baudis + Describe confusing dladdr() behavior + dladdr() will act unexpectedly if called from non-pic code on a + compile-time-generated function pointer. + +fmemopen.3 + Michael Kerrisk + Add VERSIONS section + Petr Baudis + SEE OPEN: Add fopencookie(3) + fopencookie(3) is used to implement fmemopen(). + +fopen.3 + Petr Baudis + SEE ALSO: Add fmemopen(3) and fopencookie(3) + +fopencookie.3 + Petr Baudis + fopencookie() needs _GNU_SOURCE feature test macro + +getaddrinfo.3 + Petr Baudis + Document results ordering and /etc/gai.conf + This patch documents the order of the getaddrinfo(3) results + (RFC 3484), how should the application deal with that, + mentions the extremely common cause of having multiple + results per query (both IPv4 and IPv6 addresses available) + and mentions /etc/gai.conf. + + (mtk: Minor tweaks, and note glibc version for /etc/gai.conf) + +isatty.3 + Michael Kerrisk + Complete rewrite of this page, with rather more detail + +memmem.3 + Michael Kerrisk + Remove sentence saying that libc 5.0.9 is still widely used + That was a *long* time ago. + +on_exit.3 + Michael Kerrisk + Document handling of registrations on fork(2) and execve(2) + Treatment in these cases is the same as for atexit(3). + Michael Kerrisk + Arg given to registered function is status from *last* call to exit() + It's a subtle point, but if a registered function itself + calls exit(3), then subsequent functions that were registered + with on_exit(3) will see the exit status given to the more + recent exit(3) call. + Michael Kerrisk + Note that same function may be registered multiple times + +setlocale.3 +locale.7 + Michael Kerrisk + Clean up the description of LANGUAGE environment variable + Clean up the $LANGUAGE description, by removing bogus comments + from setlocale(3) and expanding the mention in locale(7). + + Maybe you will decide that a more detailed description + should be left to the gettext(3) documentation, but I + actually care about the invisible part of the patch more + since the comments have put me off the track initially + ($LANGUAGE has nothing to do with setlocale(3) and is + completely isolated to gettext, as obvious from the + glibc sources). + +proc.5 + Michael Kerrisk + /proc/stat: s/minor/disk_idx/ in description of /proc/stat + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=225619 + +capabilities.7 + Drake Wilson + Various minor fixes as per Debian bug 471029 + The relevant pieces of + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=471029 are: + + - Delete duplicate subentry for KEYCTL_CHOWN/KEYCTL_SETPERM + operations in the CAP_SYS_ADMIN entry. (It feels like that + capability entry should be converted to a list, but I've + left it in semicolon-delimited form for now.) + + - Remove text about ENFILE from the text about the + /proc/sys/fs/file-max limit in the CAP_SYS_ADMIN entry, since + this is already described in the man pages for the relevant + ofile-creating system calls. + + - Correct or clarify a few other bits of grammar and such; + see the diff file itself for details. + +socket.7 + Michael Kerrisk + SEE ALSO: add tcp(7) and udp(7) + +tcp.7 + Michael Kerrisk + Relocate out-of-band data discussion + Move to a new subsection entitled "Sockets API". + Michael Kerrisk + Note that MSG_PEEK can be used on out-of-band data + +time.7 + Michael Kerrisk + SEE ALSO: add clock_gettime(3) + +unix.7 + Michael Kerrisk + Unix domain sockets don't support the recv() MSG_TRUNC flag + Michael Kerrisk + Retitled subsection "(Un)supported features" to "Sockets API" + This is consistent with the recent change in tcp(7). + + + +==================== Changes in man-pages-3.16 ==================== + +Released: 2009-01-13, Christchurch + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Colin Watson +Florentin Duneau +Petr Baudis + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pthread_getcpuclockid.3 + Michael Kerrisk + New page documenting pthread_getcpuclockid(3) + +libc.7 + Michael Kerrisk + New page giving brief overview of C libraries on Linux + +rtld-audit.7 + Michael Kerrisk + New page documenting dynamic linker auditing API + + +Newly documented interfaces in existing pages +--------------------------------------------- + +ld.so.8 + Petr Baudis + Document LD_AUDIT + Petr Baudis + Document LD_POINTER_GUARD + + +New and changed links +--------------------- + +gethostid.2 + Michael Kerrisk + New link to new page location in Section 3 + +sethostid.2 + Michael Kerrisk + Change link to point to new page location in Section 3 + +sethostid.3 + Michael Kerrisk + New link to relocated page in Section 3 + +glibc.7 + Michael Kerrisk + New link to new libc.7 + + +Global changes +-------------- + +syscalls.2 +feature_test_macros.7 +standards.7 + Michael Kerrisk + SEE ALSO: add libc(7) + +dlopen.3 +ld.so.8 + Michael Kerrisk + SEE ALSO: add rtld-audit(7) + + +Changes to individual pages +--------------------------- + +gethostid.2 + Michael Kerrisk + Move to Section 3 + The interfaces documented in this page are purely glibc. + +syscalls.2 + Michael Kerrisk + Kernel 2.6.28 adds accept4() + +clock_getres.3 + Michael Kerrisk + SEE ALSO: Add pthread_getcpuclockid(3) + +fmemopen.3 + Michael Kerrisk + Fix VERSIONS information + +gethostid.3 + Michael Kerrisk + Before version 2.2, glibc stored the host ID in /var/adm/hostid + Also: rewrite some text describing the /etc/hostid file, so that + this location is referred to just once on the page. + Michael Kerrisk + RETURN VALUE: describe return value of sethostid() + Michael Kerrisk + Added BUGS section noting that ID can't be guaranteed to be unique + Michael Kerrisk + Added ERRORS section describing errors for sethostid() + Michael Kerrisk + Update section number to reflect relocation into Section 3 + +printf.3 + Michael Kerrisk + Source and destination buffers may not overlap for *s*printf() + http://sourceware.org/bugzilla/show_bug.cgi?id=7075 + + Some existing code relies on techniques like the following to + append text to a buffer: + + $ cat s.c + #include + char buf[80] = "not "; + main() + { + sprintf(buf, "%sfail", buf); + puts(buf); + return 0; + } + + $ cc s.c + $ ./a.out + not fail + + However, the standards say the results are undefined if source + and destination buffers overlap, and with suitable compiler + options, recent changes can cause unexpected results: + + $ cc -v 2>&1 | grep gcc + gcc version 4.3.1 20080507 (prerelease) [gcc-4_3-branch revision 135036] (SUSE Linux) + $ cc -D_FORTIFY_SOURCE -O2 s.c + $ ./a.out + fail + +readdir.3 + Michael Kerrisk + Rewrite text describing 'dirent' fields standardized in POSIX.1 + Michael Kerrisk + Clarify text for return value/errno setting for end-of-stream case + +nscd.8 + Petr Baudis + Correct NOTES section on reloading configuration files + It behaved this way at least since + "Sun Oct 18 15:02:11 1998 +0000", + some four months after including the nscd implementation + in glibc. But there does seem to be a short window between + glibc-2.1 and glibc-2.1.3 when nscd -i was not available, + I don't think it's worth muddling the point of the page + with that, though. + + +==================== Changes in man-pages-3.17 ==================== + +Released: 2009-01-19, Hobart + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Adeodato Simó +Bastien ROUCARIES +Davide Libenzi +Lefteris Dimitroulakis +Mads Martin Joergensen +Marc Lehmann +Martin (Joey) Schulze +Michael Kerrisk +Petr Baudis +Sam Varshavchik +Vegard Nossum + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +endian.3 + Michael Kerrisk + New page documenting byte order conversion functions + Document functions (new in glibc 2.9) for conversion between + host byte order and big-/little- endian byte order: + htobe16(), htole16(), be16toh(), le16toh(), + htobe32(), htole32(), be32toh(), le32toh(), + htobe64(), htole64(), be64toh(), le64toh() + +getifaddrs.3 + Petr Baudis + New page documenting getifaddrs(3) and freeifaddrs(3) + Many edits and changes of Petr's initial draft by mtk + +cp1251.7 + Lefteris Dimitroulakis + New page documenting CP 1251 (Windows Cyrillic) character set + +iso-8859-10.7 + Lefteris Dimitroulakis + New page documenting ISO 8859-10 character set + +iso_8859-13.7 + Lefteris Dimitroulakis + New page documenting ISO 8859-13 character set + +iso_8859-14.7 + Lefteris Dimitroulakis + New page documenting ISO 8859-14 character set + +iso_8859-3.7 + Lefteris Dimitroulakis + New page documenting ISO 8859-3 character set + +iso_8859-5.7 + Lefteris Dimitroulakis + New page documenting ISO 8859-5 character set + +iso_8859-8.7 + Lefteris Dimitroulakis + New page documenting ISO 8859-8 character set + +koi8-u.7 + Lefteris Dimitroulakis + New page documenting KOI8-U character set + + +Newly documented interfaces in existing pages +--------------------------------------------- + +epoll.7 + Michael Kerrisk + Document /proc interfaces for limiting kernel memory usage + Document the following /proc files that were added in + Linux 2.6.28: + /proc/sys/fs/epoll/max_user_instances + /proc/sys/fs/epoll/max_user_watches + +netdevice.7 + Michael Kerrisk + Document recently added interface flags + IFF_LOWER_UP (since Linux 2.6.17) + IFF_DORMANT (since Linux 2.6.17) + IFF_ECHO (since Linux 2.6.25) + + Documentation taken from comments in + + +New and changed links +--------------------- + +freeifaddrs.3 + Michael Kerrisk + New link to new getifaddrs.3 + +htobe16.3 +htole16.3 +be16toh.3 +le16toh.3 +htobe32.3 +htole32.3 +be32toh.3 +le32toh.3 +htobe64.3 +htole64.3 +be64toh.3 +le64toh.3 + Michael Kerrisk + New links to new endian.3 + +iso-8859-10.7 +iso_8859_10.7 +latin6.7 + Michael Kerrisk + New links to new iso_8859-10.7 + +iso-8859-13.7 +iso_8859_13.7 +latin7.7 + Michael Kerrisk + New links to new iso_8859-13.7 + +iso-8859-14.7 +iso_8859_14.7 +latin8.7 + Michael Kerrisk + New links to new iso_8859-14.7 + +iso-8859-3.7 +iso_8859_3.7 +latin3.7 + Michael Kerrisk + New links to new iso_8859-3.7 + +iso-8859-5.7 +iso_8859_5.7 + Michael Kerrisk + New links to new iso_8859-5.7 + +iso-8859-8.7 +iso_8859_8.7 + Michael Kerrisk + New links to new iso_8859-8.7 + + +Changes to individual pages +--------------------------- + +bind.2 + Michael Kerrisk + SEE ALSO: Add getifaddrs(3) + +epoll_create.2 + Michael Kerrisk + Document EMFILE error + This error is encountered when the limit imposed by + /proc/sys/fs/epoll/max_user_instances is encountered. + Michael Kerrisk + Clarify distinction between epoll instance and epoll file descriptor + Reword so that the notion of an epoll instance is made clear, + and made distinct from the notion of an epoll file descriptor. + Some other minor rewordings also. + +epoll_ctl.2 + Michael Kerrisk + Reordered parts of the text + Michael Kerrisk + Introduce notion of epoll instance + Introduce notion of epoll instance as distinct from + epoll file descriptor. Plus other wording clean-ups. + Michael Kerrisk + Document ENOSPC error (new in Linux 2.6.28) + This error results when the limit imposed by + /proc/sys/fs/epoll/max_user_watches is encountered. + +epoll_wait.2 + Michael Kerrisk + Introduce the notion of an epoll instance into text + +getdents.2 + Michael Kerrisk + Before kernel < 2.6.4, 'd_type' was effectively always DT_UNKNOWN + +gethostid.2 + Michael Kerrisk + Rename file (was misnamed gethostd.2 in previous release) + +getsockname.2 + Michael Kerrisk + SEE ALSO: Add getifaddrs(3) + +signalfd.2 + Michael Kerrisk + Fix description of fork() semantics + The page text described the semantics of the initial + implementation of signalfd(). These were changed early on, + but the man page wasn't updated. + +byteorder.3 + Michael Kerrisk + SEE ALSO: add endian(3) + +longjmp.3 + Michael Kerrisk + Clarify wording re saving/restoring signal mask + Michael Kerrisk + siglongjmp() restores signal mask iff 'savesigs' was non-zero + Note that siglongjmp() restores signal mask if, and only + if, 'savesigs' argument of sigsetjmp() was non-zero. (Previous + text omitted the "and only if".) + +memccpy.3 + Michael Kerrisk + Fix CONFORMING TO: s/C99/POSIX.1-2001/ + Michael Kerrisk + If the memory areas overlap, the results are undefined + +sethostid.3 + Michael Kerrisk + Rename file (was misnamed sethostd.3 in previous release) + +setjmp.3 + Michael Kerrisk + Clarify wording re saving/restoring signal mask + Michael Kerrisk + Clarify when setjmp() provides BSD vs System V signal mask semantics + +strsep.3 + Michael Kerrisk + BUGS: explicitly list problems afflicting strsep() + Previously, the page said this function suffered the same + problems as strtok(), but in fact strsep() doesn't suffer + from all of the same problems as strtok(), so explicitly + list just the problems of strsep() in the strsep.3 page. + +proc.5 + Michael Kerrisk + Add pointer to epoll(7) for description of epoll /proc files + +epoll.7 + Michael Kerrisk + Various wording changes to improve clarity and consistency + + +==================== Changes in man-pages-3.18 ==================== + +Released: 2009-02-10, Christchurch + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +Bastien ROUCARIES +Christian Siebert +Christopher Head +Florentin Duneau +Guillem Jover +Lefteris Dimitroulakis +Lucio Maciel +Michael Kerrisk +Mike Frysinger +Peter Zijlstra +Petr Baudis +Sam Varshavchik +Satyam Sharma +Sebastian Kienzl +Timo Sirainen +Vegard Nossum + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +armscii-8.7 + Lefteris Dimitroulakis + New page documenting ArmSCII-8 character set + +iso_8859-11.7 + Lefteris Dimitroulakis + New page documenting ISO 8859-11 character set + +iso_8859-4.7 + Lefteris Dimitroulakis + New page documenting ISO 8859-4 character set + +iso_8859-6.7 + Lefteris Dimitroulakis + New page describing ISO 8859-6 character set + +pthread_kill.3 + Michael Kerrisk + New page documenting pthread_kill(3) + +pthread_kill_other_threads_np.3 + Michael Kerrisk + New page documenting pthread_kill_other_threads_np(3) + +pthread_sigmask.3 + Michael Kerrisk + New page documenting pthread_sigmask(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +clock_getres.3 + Michael Kerrisk + Document CLOCK_MONOTONIC_RAW, new in 2.6.28 + + +New and changed links +--------------------- + +clock_gettime.2 +clock_settime.2 +clock_getres.3 +clock_gettime.3 +clock_settime.3 + Michael Kerrisk + Update links to reflect the fact that clock_* pages are now in + Section 2 + +iso-8859-11.7 +iso_8859_11.7 + Michael Kerrisk + New links to new iso_8859-11.7 + +iso-8859-4.7 +iso_8859_4.7 +latin4.7 + Michael Kerrisk + New links to new iso_8859-4.7 + +iso-8859-6.7 +iso_8859_6.7 + Michael Kerrisk + New links to new iso_8859-6.7 + +tis-620.7 + Michael Kerrisk + New link to new iso_8859-11.7 + + +Global changes +-------------- + +clock_nanosleep.2 +getrusage.2 +timerfd_create.2 +clock.3 +clock_getcpuclockid.3 +ftime.3 +pthread_create.3 +pthread_getcpuclockid.3 +pthread_tryjoin_np.3 +sem_wait.3 +time.7 + Michael Kerrisk + Global fix: Fix xrefs to clock_*.? pages to reflect move to section 2 + +clock_nanosleep.2 +execve.2 +fork.2 +nanosleep.2 +sigaction.2 +timerfd_create.2 +pthread_getcpuclockid.3 +ualarm.3 +usleep.3 +pthreads.7 +time.7 + Michael Kerrisk + Global fix: s/(3)/(2)/ in section number xrefs for timer_*() API + The POSIX timers API is implemented (mostly) within the kernel, + so these interfaces are system calls. Although there are as yet + no man pages, when they are added they should be in Section 2, + not 3. Therefore fix those pages that currently refer to these + interfaces as being in Section 3. + + +Changes to individual pages +--------------------------- + +capget.2 + Andi Kleen + Add some details and relocate a paragraph + While writing a little program using capset + I found the capset manpage quite light on crucial + details and I had to resort to RTFS. + + This patch improves the points I found unclear + and also moves one misplaced paragraph around. + +clock_getres.2 + Michael Kerrisk + Move page from Section 3 to Section 2 + +eventfd.2 + Michael Kerrisk + glibc eventfd() supports the use of eventfd2() since version 2.9 + +fork.2 + Michael Kerrisk + SEE ALSO: add daemon(3) + +getdents.2 + Michael Kerrisk + Remove unneeded HAVE_D_TYPE from example program + Since d_type will always just return DT_UNKNOWN before + kernel 2.6.4, we don't need to use a conditional for + determining whether we use this flag. + +nanosleep.2 + Michael Kerrisk + Relocated misplaced BUGS heading + +select_tut.2 + Michael Kerrisk + Clean up error checking in example program (no semantic changes) + Michael Kerrisk + Many parts tidied and rewritten + Remove some redundant text, clarify various pieces, + tidy example code, etc. + Michael Kerrisk + Bug fixes + rewrites in example program + Sebastien pointed out that the first example program + wrongly thinks it can count signals. + Also, some further rewrites by mtk. + +socket.2 + Michael Kerrisk + BUGS: Remove discussion SOCK_UUCP + As time goes on, this sentence becomes less a piece of humor, + and more a puzzle. + +stat.2 + Michael Kerrisk + Note that open(O_NOATIME) also causes st_atime not to be updated + +timerfd_create.2 + Michael Kerrisk + Add BUGS noting that timerfd supports fewer clock types than + timer_create() + +btowc.3 + Michael Kerrisk + SEE ALSO: add wctob(3) + +clock_getcpuclockid.3 + Michael Kerrisk + SEE ALSO: add pthread_getcpuclockid(3) + +cos.3 + Michael Kerrisk + SEE ALSO: add sincos(3) + +fexecve.3 + Timo Sirainen + Note that fexecve() depends on a mounted /proc + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=514043 + Michael Kerrisk + CONFORMING TO: note addition of fexecve() in POSIX.1-2008 + Michael Kerrisk + 'fd' must be opened read-only and refer to a file that is executable + +fmemopen.3 + Michael Kerrisk + CONFORMING TO: note that these functions are in POSIX.1-2008 + +getifaddrs.3 + Lucio Maciel + Fix memory leak in example program + Petr Baudis + Various small fixes + +getpwnam.3 + Michael Kerrisk + SEE ALSO: add getspnam(3) + +getumask.3 + Michael Kerrisk + Updated glibc version number in NOTES + +ilogb.3 + Michael Kerrisk + SEE ALSO: add significand(3) + +intro.3 + Michael Kerrisk + SEE ALSO: add libc(7) + +isalpha.3 + Michael Kerrisk + Fix statement that isalpa() is obsolete; should be isascii() + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=512709 + Michael Kerrisk + SEE ALSO: add toascii(3) + +mq_notify.3 + Michael Kerrisk + Add cross reference to pthread_attr_init(3) + +pthread_attr_setaffinity_np.3 + Michael Kerrisk + SYNOPSIS: Fix declaration of 'attr' + +pthread_getcpuclockid.3 + Michael Kerrisk + SYNOPSIS: fix type of 'thread' + +qsort.3 + Michael Kerrisk + EXAMPLE: remove unnecessary "#include " + +random.3 + Michael Kerrisk + SEE ALSO: add random_r(3) + +remainder.3 + Michael Kerrisk + SEE ALSO: add div(3) + +scandir.3 + Michael Kerrisk + CONFORMING TO: alphasort() and scandir() are added to POSIX.1-2008 + Michael Kerrisk + CONFORMING TO: note that versionsort() was added to glibc in + version 2.1 + +sem_wait.3 + Michael Kerrisk + SEE ALSO: add clock_gettime(2) + +significand.3 + Michael Kerrisk + Add CONFORMING TO noting that this function is unstandardized + +sigwait.3 + Michael Kerrisk + Add EXAMPLES section referring to pthread_sigmask(3) + +sin.3 + Michael Kerrisk + SEE ALSO: add sincos(3) + +stpcpy.3 + Michael Kerrisk + Add BUGS section noting the possibility of buffer overruns + Michael Kerrisk + Add missing pieces/fix various problems in example program + Michael Kerrisk + CONFORMING TO: stpcpy() is nowadays on the BSDs + Michael Kerrisk + SEE ALSO: add stpcpy.3 + +wcscasecmp.3 + Michael Kerrisk + CONFORMING TO: note that this function is added in POSIX.1-2008 + +wcsdup.3 + Michael Kerrisk + CONFORMING TO: note that this function was added in POSIX.1-2008 + +wcsncasecmp.3 + Michael Kerrisk + CONFORMING TO: note that this function is added in POSIX.1-2008 + +wctob.3 + Michael Kerrisk + SEE ALSO: add btowc(3) + +proc.5 + Michael Kerrisk + Remove mention of epoll/max_user_instances + (Since this interface appeared in 2.6.28, and then + disappeared in 2.6.29.) + +ascii.7 + Michael Kerrisk + Update SEE ALSO list to include pages added in 3.17 + Michael Kerrisk + SEE ALSO: add recently added iso_8859-*(7) pages + +epoll.7 + Michael Kerrisk + remove documentation of /proc/sys/fs/epoll/max_user_instances + This /proc interface appeared in 2.6.28. but will be + removed in 2.6.29. + + Also, document change in default value of + /proc/sys/fs/epoll/max_user_watches (was 1/32 of lowmem, + now 1/25 of lowmem). + +koi8-r.7 + Michael Kerrisk + SEE ALSO: add koi8-u(7); remove crufty text + +standards.7 + Michael Kerrisk + Update to note that latest POSIX/SUS was ratified in 2008 + +time.7 + Michael Kerrisk + SEE ALSO: add pthread_getcpuclockid(3) + + +==================== Changes in man-pages-3.19 ==================== + +Released: 2009-02-20, Putaruru + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Christian Siebert +Jan Engelhardt +Jens Thoms Toerring +Kir Kolyshkin +Mark Hills +Michael Kerrisk +Parag Warudkar +Peter Zijlstra +Sami Liedes + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +timer_create.2 + Michael Kerrisk + New page documenting timer_create(2) + +timer_delete.2 + Michael Kerrisk + New page documenting timer_delete(2) + +timer_getoverrun.2 + Michael Kerrisk + New page documenting timer_getoverrun(2) + +timer_settime.2 + Michael Kerrisk + New page documenting timer_settime(2) and timer_gettime(2) + + +New and changed links +--------------------- + +timer_gettime.2 + Michael Kerrisk + New link to new timer_settime.2 + + +Global changes +-------------- + +Various pages + Kir Kolyshkin + Trivial punctuation fixes in SEE ALSO + In SEE ALSO, when a few man pages are referenced, those + are divided by commas. Every reference is on a separate + line, and all lines but the last one should end with + comma. I spotted one place where there is no comma in + between references, and mocked up an awk script to find + similar places: + + for f in man*/*; do + awk ' + /^.SH ["]SEE ALSO["]/ { + sa=1; print "== " FILENAME " =="; print; next + } + /^\.(PP|SH)/ { + sa=0; no=0; next + } + /^\.BR/ { + if (sa==1) { + print; + if (no == 1) + print "Missing comma in " FILENAME " +" FNR-1; no=0 + } + } + /^\.BR .*)$/ { + if (sa==1) + no=1; + next + } + /\.\\"/ {next} + /.*/ { + if (sa==1) { + print; next + } + } + ' $f; + done | fgrep 'Missing comma' + + This patch fixes all the places found by the above script. + + Also, there is an extra dot at the end of uri.7 "SEE ALSO" + section. Removed as per man-pages(7) recommendation. + + +Changes to individual pages +--------------------------- + +getitimer.2 +clock_getcpuclockid.3 +time.7 + Michael Kerrisk + SEE ALSO: add timer_create(2) + +getitimer.2 + Michael Kerrisk + Rename arguments for consistency with other timer pages + Also some other minor wording improvements + +splice.2 + Mark Hills + ERRORS: Add EINVAL case for file opened O_APPEND + Target file cannot be opened in append (O_APPEND) mode + + In kernels prior to v2.6.27 splice() to a file in + append mode is broken, and since that version it is + disallowed. It is possible this behaviour may change + in the future; see the kernel commit message + (efc968d450e013049a662d22727cf132618dcb2f) for more + information. + +syscalls.2 + Michael Kerrisk + Note that getpmsg(2) and putmsg(2) are unimplemented + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=514771 + +timerfd_create.2 + Michael Kerrisk + ERRORS: add EFAULT + +timerfd_create.2 + Michael Kerrisk + Rename timerfd_settime() 'curr_value' arg to 'old_value' + For consistency with related pages. + +vm86.2 + Parag Warudkar + CONFORMING TO: Add 32-bit specific + Note that this call is only on *32-bit* Intel + +mq_open.3 + Michael Kerrisk + ERRORS: add ENOENT error for name == "/" + +mq_open.3 + Michael Kerrisk + ERRORS: Add EACCES error for name containing > 1 slash + +sem_open.3 + Michael Kerrisk + ERRORS: add EINVAL error where name == "/" + +sem_open.3 + Jens Thoms Toerring + Add case of non-well-formed name to ENOENT + +shm_open.3 + Michael Kerrisk + Clarify rules for construction of shared memory object names + +proc.5 + Michael Kerrisk + Add description of /proc/sys/kernel/sysrq + Reported by: Goerghe Cosorea + +proc.5 + Michael Kerrisk + Put /proc/modules entry in correct alphabetical order + +ascii.7 + Kir Kolyshkin + Fix formatting of tables on second page to use monospaced font + +mq_overview.7 + Michael Kerrisk + Clarify construction rules for message queue object names + +sem_overview.7 + Michael Kerrisk + Clarify construction rules for semaphore object names + See also http://groups.google.com/group/comp.os.linux.development.apps/browse_thread/thread/b4a67caa765cb65f + + + +==================== Changes in man-pages-3.20 ==================== + +Released: 2009-03-31, Christchurch + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alan Curry +Américo Wang +Andi Kleen +Carlos O'Donell +Chunming Chang +Colin Watson +Eelco Dolstra +Jan Engelhardt +Jens Thoms Toerring +Johannes Stezenbach +Leandro A. F. Pereira +Martin Gebert +Michael Kerrisk +Mike O'Connor +Mike Frysinger +Nikanth Karthikesan +Reuben Thomas +Reuben Thomas +Roland McGrath +Sam Varshavchik +Simon Gomizelj +Tanaka Akira +Teddy Hogeborn +Walter Jontofsohn + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +cpuid.4 + Andi Kleen + New page for cpuid access device + +msr.4 + Andi Kleen + New page documenting x86 CPU MSR access device + + +Newly documented interfaces in existing pages +--------------------------------------------- + +proc.5 + Américo Wang + Document /proc/sys/vm/swappiness + Michael Kerrisk + Document /proc/sysrq-trigger + + +Global changes +-------------- + +timer_create.2 +timer_delete.2 +timer_getoverrun.2 +timer_settime.2 +numa.7 + Michael Kerrisk + Make source layout of 'Link with' text consistent with other pages + No actual change to formatted output, but this makes the + page sources more consistent for the purpose of grepping, etc. + +mempcpy.3 +signbit.3 +significand.3 + Michael Kerrisk + Global fix: acknowledge FSF in copyright + These pages are heavily based on original material in + glibc info pages, but the comments in the source of the pages + did not acknowledge the FSF copyright on the original material. + Fix that. + +accept.2 +read.2 +recv.2 +send.2 +write.2 + Michael Kerrisk + Fix discussion of EAGAIN/EWOULDBLOCK errors + For a non-blocking socket, POSIX.1-2001/2008 allow either + EAGAIN or EWOULDBLOCK to be returned in cases where a call + would have blocked. Although these constants are defined + with the same value on most Linux architectures (PA-RISC + is the exception), POSIX.1 does not require them to have + the same value. Therefore, a portable application using + the sockets API should test for both errors when checking + this case. + + (NB POSIX.1 only mentions EWOULDBLOCK in the context of + the sockets interfaces.) + + Change made after a note cross-posted on linux-arch@vger, + http://thread.gmane.org/gmane.linux.debian.ports.hppa/5615 + and a suggestion for write(2) from Carlos O'Donell + +basename.3 +getgrent.3 +getgrnam.3 +getpwent.3 +getpwnam.3 +readdir.3 + Michael Kerrisk + Note that returned pointer should not be given to free() + +armscii-8.7 +cp1251.7 +iso_8859-10.7 +iso_8859-11.7 +iso_8859-13.7 +iso_8859-14.7 +iso_8859-15.7 +iso_8859-16.7 +iso_8859-2.7 +iso_8859-3.7 +iso_8859-4.7 +iso_8859-5.7 +iso_8859-6.7 +iso_8859-7.7 +iso_8859-8.7 +iso_8859-9.7 +koi8-r.7 +koi8-u.7 + Michael Kerrisk + Add explicit character set encoding to first line of source + Nowadays mandb has provision to understand a character set + encoding that is explicitly indicated in the first line + of the source. As pointed out by Colin Watson, including + such an explicit indication on pages encoded in anything + other than ISO 8859-1 or UTF-8 is useful for man-pages + that aren't shipped in UTF-8. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519209 + and for some other background (responded to by Colin Watson + in the above report): + http://thread.gmane.org/gmane.comp.internationalization.linux/6040 + ("man page encoding", 5 Jul 2005) + + +Changes to individual pages +--------------------------- + +fallocate.2 + Michael Kerrisk + VERSIONS: glibc support is provided since version 2.10 + +fcntl.2 + Michael Kerrisk + Remove mention of EWOULDBLOCK from discussion of mandatory locking + In the kernel, the error on encountering a mandatory lock is + EAGAIN. Although EAGAIN and EWOULDBLOCK are the same on + most Linux architectures, on some they are not, so don't + mention EWOULDBLOCK as it is misleading. (Mea culpa.) + +getcontext.2 + Michael Kerrisk + Note that POSIX.1-2008 removes the specification of getcontext() + +getitimer.2 + Michael Kerrisk + Note that POSIX.1-2008 recommends POSIX timers API instead of this API + +gettimeofday.2 + Michael Kerrisk + Note that POSIX.1-2008 recommends clock_gettime() instead of this API + +ptrace.2 + Michael Kerrisk + Note use of 'data' for PTRACE_SYS{CALL,EMU} and PTRACE_*_SINGLESTEP + These operations use the 'data' argument as a signal number, + like PTRACE_CONT. + +ptrace.2 + Mike Frysinger + only reference + The kernel no longer installs linux/user.h, so update + references to sys/user.h. + +recv.2 + Michael Kerrisk + Add 'iovec' defn to defn of 'msghdr' structure + The 'msghdr' structure includes a field of type 'iovec', + so show the definition of that structure in this page. + +rename.2 + Michael Kerrisk + Make ENOENT description consistent with POSIX.1-2008 + +timerfd_create.2 + Michael Kerrisk + ERRORS: add EINVAL for invalid 'flags' for timer_settime() + +truncate.2 + Michael Kerrisk + SYNOPSIS: Fix description of feature test macro requirements + After a report by Arvid Norlander. + +bcopy.3 + Michael Kerrisk + Note that POSIX.1-2008 removes specification of bcopy() + +bsd_signal.3 + Michael Kerrisk + Note that POSIX.1-2008 recommends sigaction(2) instead of this API + +ctime.3 + Michael Kerrisk + Note that POSIX.1-2008 recommends strftime(3) instead of these functions + +ecvt.3 + Michael Kerrisk + Note that POSIX.1-2008 recommends sprintf(3) instead of these functions + +gcvt.3 + Michael Kerrisk + Note that POSIX.1-2008 recommends sprintf(3) instead of this function + +getcwd.3 + Michael Kerrisk + Note that getcwd() should be used instead of the obsolete getwd() + +getgrent.3 + Michael Kerrisk + Returned buffer may be statically allocated and overwritten by + later calls + +gethostbyname.3 + Michael Kerrisk + POSIX.1-2008 recommends getaddrinfo(3) and getnameinfo(3) instead + +getnetent_r.3 + Michael Kerrisk + Fix function name in text: s/getnetbynumber_r/getnetbyaddr_r/ + The SYNOPSIS showed the right function name (getnetbyaddr_r), + but the text repeatedly used the wrong name (getnetbynumber_r). + Probably, this was a cut-and-paste error. + +getpwent.3 + Michael Kerrisk + Returned buffer may be statically allocated and overwritten by + later calls + +index.3 + Michael Kerrisk + Note that POSIX.1-2008 recommends strchr(3) and strrchr(3) instead + +isalpha.3 + Michael Kerrisk + Explain why POSIX.1-2008 marks isascii(3) obsolete + +lockf.3 + Nikanth Karthikesan + Update pointer to documentation in kernel source + +makecontext.3 + Michael Kerrisk + Note that POSIX.1-2008 recommends the use of POSIX threads instead + +mq_notify.3 + Michael Kerrisk + Document the POSIX.1-2008 optional EINVAL error + POSIX.1-2008 allows an optional EINVAL error if + notification==NULL and the caller is not currently + registered to receive notifications. + +posix_fallocate.3 + Michael Kerrisk + Clarify that EINVAL also occurs of 'len' *equals* zero + See http://bugzilla.kernel.org/show_bug.cgi?id=12919 + +posix_fallocate.3 + Michael Kerrisk + Document POSIX.1-2001 and POSIX.1-2008 specifications for EINVAL error + See http://bugzilla.kernel.org/show_bug.cgi?id=12919 + +posix_memalign.3 + Michael Kerrisk + Document handling of size==0 case for posix_memalign() + +pthread_exit.3 + Michael Kerrisk + Fix error in DESCRIPTION: s/pthread_create/pthread_exit/ + +realpath.3 + Michael Kerrisk + Rework resolved_path==NULL discussion w.r.t. POSIX.1-200[18] + Although the page already mentioned the resolved_path==NULL + feature, and that this feature was added in POSIX.1-2008, there + was still some crufty text in BUGS that hadn't been updated to + reflect the POSIX.1-2008 changes. + + Also, some other minor wording and grammar fixes. + +scalb.3 + Michael Kerrisk + Note that POSIX.1-2008 recommends scalbln*(3) instead + +seekdir.3 + Michael Kerrisk + SYNOPSIS: Fix type of 'offset' argument: s/off_t/long/ + And add a NOTES section pointing out that 'off_t' + was indeed used in glibc 2.1.1 and earlier. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519230 + +sem_post.3 + Michael Kerrisk + Document EOVERFLOW error + +shm_open.3 + Michael Kerrisk + Recast discussion on name length to exclude terminating NULL byte + Probably it's clearer to describe the length of the IPC object + name as a count that excludes the null terminator. + +siginterrupt.3 + Michael Kerrisk + Note that POSIX.1-2008 recommends sigaction() instead + +sigset.3 + Michael Kerrisk + Note APIs that POSIX.1-2008 recommends instead of these obsolete APIs + +strftime.3 + Michael Kerrisk + Small fix to description of %G + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=516677 + +strftime.3 + Michael Kerrisk + Add details on ISO 8601 week-based dates + ISO 8602 week-based dates are relevant for %G, %g, and %V, + and the existing details on these dates are a little thin. + +strftime.3 + Michael Kerrisk + Remove mention of year from ISO 8601 standard + The text mentioned the 1988 8601 standard, but there have + already been two revisions of the standard since then, so + simply remove mention of the year. + +telldir.3 + Michael Kerrisk + SYNOPSIS: Fix return type: s/off_t/long/ + And add a NOTES section pointing out that 'off_t' + was indeed used in glibc 2.1.1 and earlier. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519230 + +timeradd.3 + Michael Kerrisk + Note that on some systems, <=, >=, == don't work for timercmp() + +timeradd.3 + Michael Kerrisk + SYNOPSIS: Fix return types of timerisset() and timercmp() + +toascii.3 + Michael Kerrisk + Note why POSIX.1-2008 marks this function obsolete + +console_ioctl.4 + Alan Curry + Fix 'argp' type for KDGETLED description + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=517485 + +group.5 + Michael Kerrisk + Various minor rewordings and improvements + +resolv.conf.5 + Michael Kerrisk + Document 'ip6-bytestring' option + +resolv.conf.5 + Michael Kerrisk + Document 'edns0' option + +resolv.conf.5 + Michael Kerrisk + Document 'ip6-dotint' / 'no-ip6-dotint' option + +resolv.conf.5 + Michael Kerrisk + Note that maximum value of 'ndots' option is capped to 15 + +resolv.conf.5 + Michael Kerrisk + Note that maximum value of 'timeout' option is capped to 30 + +hier.7 + Michael Kerrisk + Add description of /srv + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=520904 + +ip.7 + Michael Kerrisk + Fix type used to declare sin6_port + The page should use the type specified by POSIX, + rather than the (equivalent) type used in the kernel + +ipv6.7 + Teddy Hogeborn + Fix types used to declare sin6_family and sin6_port + The page should use the types specified by POSIX, + rather than the (equivalent) types used in the kernel. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=517074 + +mq_overview.7 + Michael Kerrisk + Recast discussion on name length to exclude terminating NULL byte + Probably it's clearer to describe the length of the IPC object + name as a count that excludes the null terminator. + +rtld-audit.7 + Michael Kerrisk + Note that multiple libraries in LD_AUDIT doesn't work + This is reportedly fixed in glibc 2.10. + See http://sourceware.org/bugzilla/show_bug.cgi?id=9733 + +sem_overview.7 + Michael Kerrisk + Fix discussion of length of semaphore names + Because of the "sem." prefix added by glibc to a semaphore + name, the limit on the length of the name (excluding the + terminating null byte) is 251 characters. + + +==================== Changes in man-pages-3.21 ==================== + +Released: 2009-04-15, Los Gatos + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Frank Dana +Michael Kerrisk +Roman Byshko + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pthread_setconcurrency.3 + Michael Kerrisk + New page documenting pthread_setconcurrency(3) and + pthread_getconcurrency(3) + +pthread_yield.3 + Michael Kerrisk + New page documenting pthread_yield(3) + + +New and changed links +--------------------- + +pthread_getconcurrency.3 + Michael Kerrisk + New link to new pthread_setconcurrency(3) + +Changes to individual pages +--------------------------- + +initrd.4 + Michael Kerrisk + Various minor wording improvements + +initrd.4 + Frank Dana + Add missing word in description + +feature_test_macros.7 + Michael Kerrisk + Update for glibc 2.10 changes to + From glibc 2.10, understands the values 200809 + for _POSIX_C_SOURCE and 700 for _XOPEN_SOURCE, and makes + corresponding changes to defaults for other feature test macros. + Michael Kerrisk + Add an example program + This example program makes it possible to explore what + feature test macros are set depending on the glibc version + and the macros that are explicitly set. + +ldconfig.8 + Michael Kerrisk + /etc/ld.so.conf also include libraries found in /lib and /usr/lib + + +==================== Changes in man-pages-3.22 ==================== + +Released: 2009-07-25, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Adrian Dewhurst +Alexander Lamaison +Bryan Østergaard +Christopher Head +Doug Goldstein +Florentin Duneau +Gokdeniz Karadag +Jeff Moyer +KOSAKI Motohiro +Lucian Adrian Grijincu +Mark Hills +Michael Kerrisk +Mike Frysinger +Petr Baudis +Reimar Döffinger +Ricardo Garcia +Rui Rlex +Shachar Shemesh +Tolga Dalman +ku roi +sobtwmxt + +Apologies if I missed anyone! + + +Changes to individual pages +--------------------------- + +clone.2 + Michael Kerrisk + Rewrite crufty text about number of args in older version of clone() + Some bit rot had crept in regarding the discussion of the + number of arguments in older versions of this syscall. + Simplify the text to just say that Linux 2.4 and earlier + didn't have ptid, tls, and ctid arguments. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=533868 + Michael Kerrisk + Fix version number for CLONE_NEWIPC + It's 2.6.19, not 2.4.19. + Michael Kerrisk + Fix errors in argument names in text (ptid, ctd) + +execve.2 + Mike Frysinger + Remove erroneous statement that pending signal set is cleared + on execve(2). + +fcntl.2 + Michael Kerrisk + The kernel source file mandatory.txt is now mandatory-locking.txt + Michael Kerrisk + The Documentation/* files are now in Documentation/filesystems + +flock.2 + Michael Kerrisk + Remove unneeded reference to Documentation/mandatory.txt + Mandatory locks are only implemented by fcntl() locking + Michael Kerrisk + The Documentation/* files are now in Documentation/filesystems + +fork.2 + Jeff Moyer + Document fork() behaviour for the Linux native AIO io_context + It was noted on lkml that the fork behaviour is documented + for the POSIX AIO calls, but not for the Linux native calls. + Here is a patch which adds a small blurb that folks will + hopefully find useful. + + Upon fork(), the child process does not inherit the + io_context_t data structures returned by io_setup, + and thus cannot submit further asynchronous I/O or + reap event completions for said contexts. + +getdents.2 + Michael Kerrisk + The d_type field is fully supported on Btrfs + +mount.2 + Michael Kerrisk + Document MS_STRICTATIME, update description of MS_RELATIME + Starting with Linux 2.6.30, the MS_RELATIME behavior became + the default, and MS_STRICTATIME is required to obtain the + traditional semantics. + +poll.2 + Michael Kerrisk + Remove EBADF error from ERRORS + As reported by Motohiro: + + "man poll" describe this error code. + + >ERRORS + > EBADF An invalid file descriptor was given in one of the sets. + + but current kernel implementation ignore invalid file descriptor, + not return EBADF. + ... + + In the other hand, SUSv3 talk about + + > POLLNVAL + > The specified fd value is invalid. This flag is only valid in the + > revents member; it shall ignored in the events member. + + and + + > If the value of fd is less than 0, events shall be ignored, and + > ireevents shall be set to 0 in that entry on return from poll(). + + but, no desribe EBADF. + (see http://www.opengroup.org/onlinepubs/009695399/functions/poll.html) + + So, I think the implementation is correct. + + Why don't we remove EBADF description? + +sigaction.2 + Michael Kerrisk + Expand description of si_utime and si_stime fields of siginfo_t + +stat.2 + Michael Kerrisk + Improve wording of ENOTDIR error + +syscalls.2 + Michael Kerrisk + Add preadv() and pwritev(), new in kernel 2.6.30 + +wait.2 + Gokdeniz Karadag + Document CLD_DUMPED and CLD_TRAPPED si_code values + +daemon.3 + Michael Kerrisk + Clarify discussion of 'noclose' and 'nochdir' arguments + +ffs.3 + Petr Baudis + SEE ALSO: add memchr(3) + +fmemopen.3 + Petr Baudis + Relocate BUGS section to correct position + Petr Baudis + NOTES: there is no file descriptor associated with the returned stream + Alexander Lamaison pointed out that this is not obvious + from the documentation, citing an example with passing the + FILE * handle to a function that tries to fstat() its + fileno() in order to determine the buffer size. + Michael Kerrisk + CONFORMING TO: remove note that these functions are GNU extensions + That sentence is now redundant, since these functions + are added in POSIX.1-2008. + +lockf.3 + Michael Kerrisk + Clarify relationship between fcntl() and lockf() locking + +memchr.3 + Petr Baudis + SEE ALSO: add ffs(3) + +readdir.3 + Michael Kerrisk + The d_type field is fully supported on Btrfs + +setjmp.3 + Mike Frysinger + Fix typo and clarify RETURN description + The word "signal" was duplicated in NOTES, and the RETURN + section refers to setjmp() and sigsetjmp(), and mentions + longjmp(), but not siglongjmp(). + +strcmp.3 + Petr Baudis + SEE ALSO: add strverscmp(3) + +strcpy.3 + Mark Hills + SEE ALSO: Add strdup(3) + +complex.7 + Michael Kerrisk + Add missing header file for example program + Reimar Döffinger + Fix type used in example code + man complex (from release 3.18) contains the following code: + complex z = cexp(I * pi); + Reading the C99 standard, "complex" is not a valid type, + and several compilers (Intel ICC, ARM RVCT) will refuse to compile. + It should be + double complex z = cexp(I * pi); instead. + +environ.7 + Michael Kerrisk + Note that last element in environ array is NULL + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=528628 + Michael Kerrisk + Wording fixes + +mq_overview.7 + Michael Kerrisk + Note that mkdir and mount commands here need superuser privilege + Michael Kerrisk + Fix example showing contents of /dev/mqueue file + +standards.7 + Michael Kerrisk + Remove references to dated books + Gallmeister and Lewine are rather old books. Probably, + there are better books to consult nowadays, and anyway, + this man page isn't intended to be a bibliography. + + +==================== Changes in man-pages-3.23 ==================== + +Released: 2009-09-30, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Aaron Gardner +Andrey Vihrov +Christoph Hellwig +Georg Sauthoff +Leslie P. Polzer +Marc Lehmann +Mark Hills +Michael Kerrisk +Mike Frysinger +Nicolas François +Serge Hallyn +Siward de Groot +rui rlex + +Apologies if I missed anyone! + + +Changes to individual pages +--------------------------- + +execve.2 +pipe.2 +tee.2 +fmemopen.3 +mq_notify.3 +qsort.3 + Michael Kerrisk + Replace use of assert() by code that checks argc + See http://bugzilla.kernel.org/show_bug.cgi?id=13569 + + As noted by Andrey: + The purpose of the assert macro, defined in , + is to provide a tool to check for programming mistakes + or program logic errors. However, the assert macro must + never be used to perform checks for run time errors, + since, with the NDEBUG macro defined, expressions within + the assert macro invocations are not evaluated/checked + for, resulting in behavior that was not originally intended. + ... + The pages affected in the core package are + + execve(2) + pipe(2) + tee(2) + fmemopen(3) + mq_notify(3) + qsort(3) + +getrusage.2 + Michael Kerrisk + ru_inblock and ru_oublock are now implemented + These fields of the rusage structure are filled in since + Linux 2.6.22. + +mmap.2 + Michael Kerrisk + Add brief documentation of MAP_HUGETLB + This flag is new in 2.6.32, and serves a similar + purpose to the shmget() SHM_HUGETLB flag. + +open.2 + Christoph Hellwig + add some comments on O_SYNC and friends + +poll.2 + Michael Kerrisk + Clarify wording describing of 'nfds' argument. + reported by: rui rlex + +semctl.2 + Nicolas François + Remove some redundant words + +setpgid.2 + Michael Kerrisk + Add an explanation of orphaned process groups + +splice.2 +tee.2 +vmsplice.2 + Mark Hills + Fix return type + Since glibc 2.7, the return type for these functions + is ssize_t (formerly it was long). + +stat.2 + Nicolas François + Fix small bug in example program + Since it is a failure, EXIT_FAILURE looks more appropriate + than EXIT_SUCCESS. + +umount.2 + Michael Kerrisk + glibc only exposes MNT_DETACH and MNT_EXPIRE since version 2.11 + See http://sourceware.org/bugzilla/show_bug.cgi?id=10092 + +exit.3 + Michael Kerrisk + Add a pointer to explanation of orphaned process groups in setpgid(2) + +fflush.3 + Michael Kerrisk + fflush() discards buffered input + +ffs.3 + Michael Kerrisk + Clarify that ffsl() and ffsll() are GNU extensions + +getaddrinfo.3 + Michael Kerrisk + Note nonstandard assumed hints.ai_flags value when hints is NULL + When hints is NULL, glibc assumes hints.ai_flags is + AI_V4MAPPED|AI_ADDRCONFIG whereas POSIX says 0. + According to Ulrich Drepper, glibc's behavior is better. + +getmntent.3 + Mike Frysinger + setmntent() argument is 'filename' not 'fp' + The description of setmntent() formerly used the wrong + argument name. + +posix_fallocate.3 + Nicolas François + Fix reference to POSIX.1-2008 + The sentence mentions twice POSIX.1-2001. + I guess the second one should be POSIX.1-2008. + This should be checked in the standard. + +setenv.3 + Michael Kerrisk + Improve ERRORS section + Add ENOMEM error; improve EINVAL description. Also, make + RETURN VALUE section a little more accurate in its mention + of errno. + +strftime.3 + Nicolas François + Fix error in description: s/Monday/Thursday/ + +proc.5 + Nicolas François + Fix page cross reference + max_user_watches is better explained in epoll(7) than inotify(7). + +proc.5 + Michael Kerrisk + dmesg is in section 1, not section 8 + +capabilities.7 + Michael Kerrisk + FS UID manipulations affect CAP_LINUX_IMMUTABLE and CAP_MKNOD + Nowadays, file system UID manipulations also affect + CAP_LINUX_IMMUTABLE (since 2.6.3) and CAP_MKNOD (since 2.6.29). + +capabilities.7 + Michael Kerrisk + Fix version number for CAP_MKNOD in FS UID manipulations + A recent patch said "since 2.6.29". It should have + been "since 2.6.30". + +capabilities.7 + Nicolas François + Reword a bad sentence in description of capability bounding set. + +mq_overview.7 + Michael Kerrisk + Change documented ranges for msg_max and msgsize_max + Linux 2.6.28 changed the permissible ranges for + these /proc files. + +tcp.7 +udp.7 + Nicolas François + Replace references to syctl interfaces with /proc + + +==================== Changes in man-pages-3.24 ==================== + +Released: 2010-02-25, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +Andries E. Brouwer +Ansgar Burchardt +Bela Lubkin +Bill O. Gallmeister +Christoph Hellwig +Colin Watson +Dan Jacobson +David Howells +Denis Barbier +Doug Manley +Edward Welbourne +Fang Wenqi +Frédéric Brière +Garrett Cooper +Ihar Hrachyshka +Jann Poppinga +Jason Goldfine-Middleton +Jason Noakes +Jonathan Nieder +Kevin +Mark Hills +Markus Peuhkuri +Michael Kerrisk +Michael Witten +Mike Frysinger +Sam Liao +Samy Al Bahra +Stuart Kemp +sunjiangangok +Tobias Stoeckmann +Vlastimil Babka +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +add_key.2 + David Howells + New page documenting add_key(2) + Taken from keyutils-1.1 package. + +keyctl.2 + David Howells + New page documenting keyctl(2) + Taken from keyutils-1.1 package. + +request_key.2 + David Howells + New page documenting request_key(2) + Taken from keyutils-1.1 package. + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix: s/non-root/unprivileged/ + +Various pages + Michael Kerrisk + Global fix: s/non-privileged/unprivileged/ + +Various pages + Michael Kerrisk + Global fix: /non-superuser/unprivileged user/ + +Various pages + Michael Kerrisk + s/non-/non/ + The tendency in English, as prescribed in style guides like + Chicago MoS, is toward removing hyphens after prefixes + like "non-" etc. + +Various pages + Michael Kerrisk + Global fix: s/re-/re/ + The tendency in English, as prescribed in style guides like + Chicago MoS, is toward removing hyphens after prefixes + like "re-" etc. + +Various pages + Michael Kerrisk + Global fix: s/multi-/multi/ + The tendency in English, as prescribed in style guides like + Chicago MoS, is toward removing hyphens after prefixes + like "multi-" etc. + +Various pages + Michael Kerrisk + Global fix: s/pre-/pre/ + The tendency in English, as prescribed in style guides like + Chicago MoS, is toward removing hyphens after prefixes + like "pre-" etc. + +Various pages + Michael Kerrisk + Global fix: s/sub-/sub/ + The tendency in English, as prescribed in style guides like + Chicago MoS, is toward removing hyphens after prefixes + like "sub-" etc. + +stime.2 +time.2 +utimensat.2 +ctime.3 +difftime.3 +ftime.3 +getspnam.3 +mq_receive.3 +mq_send.3 +rtime.3 +sem_wait.3 +strftime.3 +strptime.3 +timeradd.3 +rtc.4 +core.5 +proc.5 +icmp.7 +time.7 + Michael Witten + Global fix: Consistently define the Epoch + All definitions of the Epoch have been refactored to the following: + + 1970-01-01 00:00:00 +0000 (UTC) + + That form is more consistent, logical, precise, and internationally + recognizable than the other variants. + + Also, some wording has been altered as well. + +spu_create.2 +getopt.3 +passwd.5 + Michael Kerrisk + Global fix: s/non-existing/nonexistent/ + +faccessat.2 +fchmodat.2 +fchownat.2 +fstatat.2 +futimesat.2 +linkat.2 +mkdirat.2 +mknodat.2 +openat.2 +readlinkat.2 +renameat.2 +symlinkat.2 +unlinkat.2 +utimensat.2 +mkfifoat.3 + Michael Kerrisk + Update feature test macro requirements + Starting in glibc 2.10, defining _XOPEN_SOURCE >= 700, + or _POSIX_C_SOURCE >= 200809 exposes the declarations of + these functions. + + +Changes to individual pages +--------------------------- + +clock_getres.2 + Michael Kerrisk + Update text on nonsetabble CLOCK_*_CPUTIME_ID clocks + SUSv3 permits, but does not require CLOCK_THREAD_CPUTIME_ID and + CLOCK_PROCESS_CPUTIME_ID to be settable. + See http://bugzilla.kernel.org/show_bug.cgi?id=11972. + +execve.2 + Colin Watson + Fix description of treatment of caught signals + Caught signals reset to their default on an execve() (not + to being ignored). + +fcntl.2 + Michael Kerrisk + s/F_OWNER_GID/F_OWNER_PGRP/ + Peter Zijlstra took the name change I suggested. + Michael Kerrisk + Document F_[SG]ETOWN_EX; update details on F_SETOWN + Linux 2.6.32 adds F_SETOWN_EX and F_GETOWN_EX. + Linux 2.6.12 changed (broke) the former behavior of + F_SETOWN with respect to threads. + +intro.2 +intro.3 + Michael Kerrisk + Make subsection heading consistent with other intro.? pages + These pages used "Copyright Terms"; the other intro.? pages + used "Copyright Conditions". Make these pages like the others. + +sendfile.2 + Michael Kerrisk + Clarify behavior when 'offset' is NULL + +seteuid.2 + Michael Kerrisk + Note unstandardized behavior for effective ID + POSIX.1 doesn't require that the effective ID can be changed + to the same value it currently has (a no-op). The man page + should note this, since some other implementations + don't permit it. + +setgid.2 + Michael Kerrisk + Fix EPERM error description + s/effective group ID/real group ID/ + This bug lived in man pages for 15 years before Jason + spotted it! I checked back in Linux 1.0, and the behavior + was as the fixed man page describes. + +setreuid.2 + Michael Kerrisk + Add more detail on POSIX.1 specification for these syscalls + +setuid.2 + Michael Kerrisk + Remove crufty statement that seteuid() is not in POSIX + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=569812 + +stime.2 +strftime.3 +tzset.3 +zic.8 + Michael Witten + GMT -> UTC (where appropriate) + +sync_file_range.2 + Christoph Hellwig + Add some big warnings re data integrity + This system call is by design completely unsuitable for any data + integrity operations. Make that very clear in the manpage. + +CPU_SET.3 + Vlastimil Babka + SYNOPSIS: Fix return types for CPU_COUNT_*() + These functions return 'int' not void'. + +confstr.3 + Michael Kerrisk + Fix feature test macro requirements + +daemon.3 + Michael Kerrisk + Fix description of 'nochdir' argument. + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=554819 + +gethostbyname.3 + Michael Kerrisk + Document feature test macro requirements for herror() and hstrerror() + Since glibc 2.8, one of _BSD_SOURCE, _SVID_SOURCE, + or _GNU_SOURCE is required. + +getline.3 + Michael Kerrisk + Update to reflect that these functions were standardized in POSIX.1-2008 + +getnameinfo.3 + Michael Kerrisk + Document feature test macros requirements for NI_MAXHOST and NI_MAXSERV + Since glibc 2.8, one of _BSD_SOURCE, _SVID_SOURCE, or _GNU_SOURCE + must be defined to obtain these definitions. + +getopt.3 + Jonathan Nieder + Fix feature test macro requirements + +memchr.3 + Michael Kerrisk + Add feature text macro requirements for memrchr() + +nextafter.3 + Michael Kerrisk + Fix notable error in DESCRIPTION. + "less than y" should be "less than x". + +popen.3 + Michael Kerrisk + Fix feature test macro requirements + +pthread_attr_setdetachstate.3 +pthread_attr_setschedparam.3 +pthread_attr_setschedpolicy.3 + Denis Barbier + Argument name is 'attr' not 'thread' + The function argument was misnamed in the DESCRIPTION on these + three pages. + +rtnetlink.3 + Michael Kerrisk + Various fixes in example code + Edward reported a problem in the example code, where a variable + seems to be misnamed. Upon inspection, there seem to be a few + such instances, and this patch is my best guess at how things + should look. + +sched_getcpu.3 + Michael Kerrisk + Place correct header file in SYNOPSIS + +sleep.3 + Bill O. Gallmeister + sleep() puts calling *thread* to sleep (not calling *process*) + +sleep.3 + Bill O. Gallmeister + Add nanosleep(2) to SEE ALSO + +strftime.3 + Michael Kerrisk + %z is defined in SUSv3 + So, substitute "GNU" tag in man page by "SU". + +strftime.3 + Michael Witten + Move 822-compliant date format example to EXAMPLES section + The RFC 822-compliant date format given in the description + of `%z' is now moved to the `EXAMPLES' section (note: `EXAMPLE' + has been renamed `EXAMPLES'). + + Furthermore, that format example is now actually + RFC 822-compliant (using `%y' instead of `%Y') and has been + qualified as being correct only when in the context of at least + an English locale. Also, `%T' is used in place of `%H:%M:%S'. + + For completeness, an RFC 2822-compliant format example has been + similarly added. + +strftime.3 + Michael Witten + Expand introductory text + +strftime.3 + Michael Witten + Clarification of %z specifier + +string.3 + Mark Hills + Add stpcpy() to this list of string functions + +strptime.3 + Michael Kerrisk + Initialize tm structure in example program + +undocumented.3 + Michael Kerrisk + Remove pages now documented + By now, the following are documented: + + fopencookie(3) + freeifaddrs(3) + rawmemchr(3) + readdir_r(3) + getutmp(3) + getutmpx(3) + utmpxname(3) + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=554819 + +group.5 + Michael Kerrisk + s/passwd/password/ + The page inconsistently used "passwd" and "password" + to refer to the same field. + +capabilities.7 + Michael Kerrisk + Update securebits discussion to use SECBIT_* flags + +feature_test_macros.7 + Michael Kerrisk + _POSIX_C_SOURCE >= 200808 defines _ATFILE_SOURCE + Since glibc 2.10, _POSIX_C_SOURCE >= 200808 defines _ATFILE_SOURCE + +path_resolution.7 + Michael Kerrisk + Add readlink(2) to SEE ALSO + Michael Kerrisk + Fix NAME line + The poorly constructed part preceding "\-" causes apropos + not to be able to find the subject. + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=558300 + +signal.7 + Michael Kerrisk + Fix discussion of SIGUNUSED + Clarify that this signal really is synonymous with SIGSYS. + See http://bugzilla.kernel.org/show_bug.cgi?id=14449 + + +==================== Changes in man-pages-3.25 ==================== + +Released: 2010-06-20, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alexander E. Patrakov +Andi Kleen +Andrew Klossner +André Goddard Rosa +Bo Borgerson +Christian Franke +Daisuke HATAYAMA +David Sommerseth +Denis Barbier +Eric Blake +Fang Wenqi +Francesco Cosoleto +Gernot Tenchio +Hugh Dickins +Ivana Hutarova Varekova +Jan Blunck +Jan Engelhardt +Jan Kara +Jeff Barry +Manfred Schwarb +Mark Hills +Martin (Joey) Schulze +Michael Kerrisk +Mihai Paraschivescu +Mike Frysinger +Miklos Szeredi +Petr Baudis +Petr Gajdos +Petr Uzel +Pierre Habouzit +Reuben Thomas +Rob Landley +Robert Wohlrab +Serge E. Hallyn +Tolga Dalman +Tom Swigg +Walter Harms +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +migrate_pages.2 + Andi Kleen + New page documenting migrate_pages(2). + Andi's text based on the move_pages.2 page; + additional edits by mtk. + migrate_pages(2) was new in Linux 2.6.16. + +quotactl.2 + Jan Kara + Major updates + Update the page to consolidate information from the + outdated man-pages quotactl.2 page and the quotactl.2 + page in the "quota-tools" package. The page in "quota-tools" + has now been dropped by Jan Kara, so that there is just one + canonical quotactl.2 page (in pan-pages). + Michael Kerrisk + Various other pieces added to the page by mtk. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fcntl.2 + Michael Kerrisk + Document F_SETPIPE_SZ and F_GETPIPE_SZ + These commands, new in kernel 2.6.35, set and get the capacity + of pipes. + +madvise.2 + Andi Kleen + Document MADV_HWPOISON + Michael Kerrisk + Added documentation of MADV_MERGEABLE and MADV_UNMERGEABLE + These flags (used for Kernel Samepage Merging, KSM) + are new in 2.6.32. + Andi Kleen + Document MADV_SOFT_OFFLINE + This operation was added in Linux 2.6.33. + +mmap.2 + Michael Kerrisk + Document MAP_UNINITIALIZED flag + New in Linux 2.6.33. + +prctl.2 + Andi Kleen + Document the hwpoison prctls in 2.6.32 + +sched_setscheduler.2 + Michael Kerrisk + Document SCHED_RESET_ON_FORK + New in Linux 2.6.32 + +umount.2 + Michael Kerrisk + Document UMOUNT_NOFOLLOW + New in Linux 2.6.34. + +mkstemp.3 + Michael Kerrisk + Document mkstemps() and mkostemps() + These functions are new in glibc 2.11. They allow the template + string to include a suffix after the "XXXXXX" string. + +proc.5 + Michael Kerrisk + Document /proc/sys/vm/memory_failure_early_kill + New in 2.6.32. Description based on the text in + Documentation/sysctl/vm.txt. + Michael Kerrisk + Document /proc/sys/vm/memory_failure_recovery + New in Linux 2.6.32. Description based on the text in + Documentation/sysctl/vm.txt. + Michael Kerrisk + Document /proc/sys/fs/pipe-max-size + +socket.7 + Jan Engelhardt + Document SO_DOMAIN and SO_PROTOCOL + These read-only socket options were new in Linux 2.6.32. + + +New and changed links +--------------------- + +fstatvfs.2 + Michael Kerrisk + Adjust link to point to Section 3 + +fstatvfs.3 +statvfs.2 + Michael Kerrisk + New link to page relocated to Section 3 + +mkstemps.3 +mkostemps.3 + Michael Kerrisk + New links to mkstemp.3 + mkstemp.3 now describes mkstemps(3) and mkostemps(3). + +timer_create.2 +timer_delete.2 +timer_getoverrun.2 +timer_settime.2 +getline.3 + Michael Kerrisk + Add 'L' to constants in feature test macro specifications + Be consistent with POSIX, which uses constants such as 200809L. + + +Global changes +-------------- + +open.2 +sync_file_range.2 +umount.2 + Michael Kerrisk + Global fix: s/filesystem/file system/ + + +Changes to individual pages +--------------------------- + +fcntl.2 + Michael Kerrisk + Note that glibc 2.11 papers over the kernel F_GETOWN bug + Since version 2.11, glibc works around the kernel limitation for + process groups IDs < 4096 by implementing F_GETOWN via F_GETOWN_EX. + +futex.2 + Michael Kerrisk + Various fixes in SEE ALSO + +getpriority.2 +nice.2 + Francesco Cosoleto + Move renice from section 8 to section 1 + +getrusage.2 + Mark Hills + Add ru_maxrss + See kernel commit 1f10206. + Mark Hills + Description of maintained fields + These descriptions are taken from NetBSD 5.0's getrusage(2). + Michael Kerrisk + Enhanced description of various fields + +mlock.2 + Michael Kerrisk + /proc/PID/status VmLck shows how much memory a process has locked + After a note from Tom Swigg, it seems sensible mention VmLck here. + +mount.2 + Petr Uzel + Fix incorrect path + +move_pages.2 + Andi Kleen + Clarify includes/libraries + +mremap.2 + Michael Kerrisk + Clarify existence of fifth argument. + +msgctl.2 +semctl.2 +shmctl.2 + Francesco Cosoleto + Move ipcs from section 8 to section 1 + +open.2 + Michael Kerrisk + Remove ambiguity in text on NFS and O_EXCL. + +poll.2 + Michael Kerrisk + Fix discussion of ppoll() timeout argument + 1. Rename ppoll)(_ argument to "timeout_ts" to distinguish it + from the poll() argument in the text. + 2. More accurately describe the poll() call that is equivalent + to ppoll(). + +posix_fadvise.2 + Michael Kerrisk + Add sync_file_range(2) under SEE ALSO + +prctl.2 + Michael Kerrisk + Correct PR_SET_KEEPCAPS description + The "keep capabilities" flag only affects the treatment of + permitted capabilities, not effective capabilities. + Also: other improvements to make the PR_SET_KEEPCAPS text clearer. + +select_tut.2 + Michael Kerrisk + Fix bug in example program + +sigaction.2 + Michael Kerrisk + Add TRAP_BRANCH and TRAP_HWBKPT to si_code values for SIGTRAP + Michael Kerrisk + Rearrange text describing fields set by sigqueue(2) + Michael Kerrisk + Add details for signals sent by POSIX message queue notifications + Michael Kerrisk + Improve description of various siginfo_t fields + Michael Kerrisk + Add some details for SIGTRAP and si_trapno + Andi Kleen + Document hwpoison signal extensions + +statfs.2 + Michael Kerrisk + Bring statfs struct type declarations closer to glibc reality + Fang Wenqi + Add definition EXT4_SUPER_MAGIC = 0xEF53 + Michael Kerrisk + Document f_frsize field. + +statvfs.2 + Michael Kerrisk + Move this page to section 3 (since it's a library call) + +swapon.2 + Ivana Hutarova Varekova + Note effect of CONFIG_MEMORY_FAILURE on MAX_SWAPFILES + From 2.6.32, MAX_SWAPFILES is decreased by 1 if the kernel is + built with CONFIG_MEMORY_FAILURE. + +syscalls.2 + Michael Kerrisk + Bring system call list up to date with Linux 2.6.33 + Michael Kerrisk + Fix kernel version number for utimes() + +cproj.3 + Michael Kerrisk + Note fix for C99 conformance in glibc 2.12. + +crypt.3 + Petr Baudis + Correct note on key portion significance + As Marcel Moreaux notes: + + The Linux manpage for crypt()[1] contains the following + statement as the last sentence of the NOTES section: + + In the SHA implementation the entire key is significant + (instead of only the first 8 bytes in MD5). + + It should probably say "DES" where it says "MD5" (and maybe + "MD5/SHA" where it says "SHA"), because in MD5 password hashing, + the entire key is significant, not just the first 8 bytes. + + This patch fixes the wording. + +fmemopen.3 + Michael Kerrisk + Bug fix in example program + +ftw.3 + Michael Kerrisk + Note that if 'fn' changes CWD, the results are undefined + Michael Kerrisk + Clarify description of fpath argument + As reported by Pierre Habouzit, 'fpath' is not relative + to 'dirpath'. It is either relative to the calling process's + current working directory (if 'dirpath' was relative), or it + is absolute (if 'dirpath' was absolute). + +getaddrinfo.3 + Christian Franke + Fix a field name mixup: s/ai_family/ai_flags/ + +getline.3 + Robert Wohlrab + Remove unneeded check before free() + The manpage of getline shows an example with an extra NULL pointer + check before it calls free. This is unneeded according to free(3): + + If ptr is NULL, no operation is performed. + + This patch removes the "if" check. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=572508 + +log.3 +log10.3 +log2.3 + Jan Engelhardt + Add cross-references to other-base logarithmic functions + +opendir.3 + Petr Baudis + Specify feature test macro requirements for fdopendir(3) + Currently, there is no note on the fact that fdopendir() is + POSIX.2008-only. + +openpty.3 + Eric Blake + Use const as appropriate + Michael Kerrisk + Note glibc version that added "const" to function arguments + Michael Kerrisk + Explicitly note that these functions are not in POSIX + +resolver.3 + Michael Kerrisk + Fix declaration of dn_comp() in SYNOPSIS + Remove the second 'exp_dn' from the calling signature. + +termios.3 + Michael Kerrisk + Change NOFLSH text to speak of characters, not signals + +core.5 + Michael Kerrisk + Update description of coredump_filter + Kernel 2.6.24 added MMF_DUMP_ELF_HEADERS. + Kernel 2.6.28 added MMF_DUMP_HUGETLB_PRIVATE and + MMF_DUMP_HUGETLB_SHARED. + +elf.5 + Daisuke HATAYAMA + Document PN_XNUM extension + In linux-2.6.34-rc1, an ELF core extension was added; user-land + tools manipulating ELF core dump such as gdb and binutils has + already been modified before; so elf.5 needs to be modified + accordingly. + + You can follow information on the ELF extension via the LKML post: + http://lkml.org/lkml/2010/1/3/103 + Date Mon, 04 Jan 2010 10:06:07 +0900 (JST) + Subject ... elf coredump: Add extended numbering support + + This Linux-specific extension was added in kernel 2.6.34. + + Reviewed-by: Petr Baudis + + Michael Kerrisk + Remove EI_BRAND + As reported by Yuri Kozlov and confirmed by Mike Frysinger, + EI_BRAND is not in GABI + (http://www.sco.com/developers/gabi/latest/ch4.eheader.html) + It looks to be a BSDism + Michael Kerrisk + Remove words under '.note': "described below" + The existing text is broken, because there is + no '"Note Section" format' describe below. Simplest + solution is to remove the words "described below". + +filesystems.5 + Jeff Barry + Add discussion of ntfs and ext4 + +proc.5 + Michael Kerrisk + Simplify description of /proc/sys and /proc/sys/fs + In the description of these directories, there's no need + to list all the files and subdirectories that they contain; + that information is provided by the entries that follow. + +services.5 + Yuri Kozlov + Remove crufty reference to nonexistent BUGS section + +capabilities.7 + Michael Kerrisk + Document CAP_SYS_RESOURCE and F_SETPIPE_SZ + With CAP_SYS_RESOURCE, a process can increase pipe capacity above + /proc/sys/ps/pipe-max-size. + Michael Kerrisk + Add get_robust_list() info under CAP_SYS_PTRACE + Michael Kerrisk + Add MADV_HWPOISON under CAP_SYS_ADMIN + +signal.7 + Michael Kerrisk + Make a clearer statement about nonportable aspect of signal(2) + Make a clearer statement that signal(2) is less portable for + establishing a signal handler. + +socket.7 + Michael Kerrisk + Use consistent language to describe read-only socket options + +udp.7 + Michael Kerrisk + Add FIONREAD warning. + Warn that FIONREAD can't distinguish case of a zero-length + datagram from the case where no datagrams are available. + + +==================== Changes in man-pages-3.26 ==================== + +Released: 2010-09-04, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Alexander Shishkin +Brian Sutin +Denis Barbier +Guillem Jover +Jianhua Li +Linus Nilsson +Lenaic Huard +Mac +Martin Schulze +Maxin John +Michael Kerrisk +Nicholas Hunt +Peng Haitao +Peter Stuge +Przemyslaw Szczepaniak +Scott Walls +TAN Yee Fan +Wu Fengguang +Yitzchak Gale +Yuri Kozlov + +Apologies if I missed anyone! + +Newly documented interfaces in existing pages +--------------------------------------------- + +eventfd.2 + Michael Kerrisk + Document EFD_SEMAPHORE + Document the EFD_SEMAPHORE flag, added in kernel 2.6.30. + Also restructured some parts of the text to fit with the + addition of the EFD_SEMAPHORE text. + + +Global changes +-------------- + +getaddrinfo.3 +getipnodebyname.3 +st.4 + Michael Kerrisk + s/logical OR/bitwise OR/ + + +Changes to individual pages +--------------------------- + +clock_nanosleep.2 + Michael Kerrisk + Fix discussion of return value when interrupted by a signal + +epoll_ctl.2 + Yuri Kozlov + Small fix to types in data structures + +eventfd.2 + Alexander Shishkin + Clarified close-on-exec behavior + +madvise.2 + Michael Kerrisk + Improve discussion of MADV_SOFT_OFFLINE + +mkdir.2 + Michael Kerrisk + Add EMLINK error to ERRORS + +mq_getsetattr.2 +mq_close.3 +mq_getattr.3 +mq_notify.3 +mq_send.3 +mq_unlink.3 + Lnac Huard + Fix return type in SYNOPSIS (s/mqd_t/int/) + +recv.2 +send.2 + Michael Kerrisk + Remove obsolete reference to glibc version in NOTES + +recv.2 +send.2 + Nicholas Hunt + Adjust type shown for msg_controllen to glibc reality + This patch fixes the type of msg_controllen in the struct msghdr + definition given in send.2 and recv.2 to match the definition in + glibc and the kernel. + +select.2 + Michael Kerrisk + Update NOTES on old glibc pselect() + Make it clear that modern glibc uses the kernel pselect() + on systems where it is available. + See https://bugzilla.kernel.org/show_bug.cgi?id=14411 + +statfs.2 + Guillem Jover + Fix copy & paste error for __SWORD_TYPE definition + +sysfs.2 + Michael Kerrisk + Clarify that this syscall is obsolete. + And strengthen recommendation to use /proc/filesystems instead. + +write.2 + Michael Kerrisk + Add EDESTADDRREQ error + +a64l.3 + Peng Haitao + Fix error in NOTES, s/a64l/l64a/ + +error.3 + Linus Nilsson + Change "perror" to "strerror" in DESCRIPTION of error() + +mq_send.3 + Michael Kerrisk + Fix EAGAIN description (s/empty/full) + +initrd.4 + Yuri Kozlov + Fix IP address in explanation of NFS example + +tzfile.5 + Michael Kerrisk + Add information on version 2 format timezone files + Updated using information from the tzcode 2010l release at + ftp://elsie.nci.nih.gov/pub. + (It's an open question whether or not a version of tzfile.5 + should live independently in man-pages. It was added to the + man-pages set many years ago. For now, I'll follow a + conservative course that causes least pain to downstream, + by continuing to maintain a separate copy in man-pages.) + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=594219 + + +==================== Changes in man-pages-3.27 ==================== + +Released: 2010-09-22, Nuernberg + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +caishuxian +Denis Barbier +Denis Silakov +der Mouse +Jan Kratochvil +Jim Belton +Jiri Olsa +KOSAKI Motohiro +Mark Hills +Matthew Flaschen +Michael Kerrisk +Ozgur Gurcan +Petr Baudis +Remi Denis-Courmont +Tanaka Akira +Tim Stoakes +W. Trevor King +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +sigevent.7 + Petr Baudis, Michael Kerrisk + New page to centralize description of sigevent structure + Several interfaces use this structure. Best to centralize the + common details in one place. Content taken from the existing + timerfd_create.2 and mq_open.3 pages, with additions by + Petr Baudis and Michael Kerrisk. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +ip.7 + Jiri Olsa + Document IP_NODEFRAG + This option is new in Linux 2.6.36 + +unix.7 + Michael Kerrisk + Document SIOCINQ ioctl() operation + + +Global changes +-------------- + +_exit.2 +brk.2 +chdir.2 +chmod.2 +chown.2 +chroot.2 +clock_nanosleep.2 +getdtablesize.2 +gethostname.2 +getpagesize.2 +getsid.2 +killpg.2 +mknod.2 +mknodat.2 +posix_fadvise.2 +pread.2 +readlink.2 +setpgid.2 +setreuid.2 +sigaltstack.2 +stat.2 +symlink.2 +sync.2 +truncate.2 +vfork.2 +wait.2 +wait4.2 +a64l.3 +abs.3 +acos.3 +acosh.3 +asin.3 +asinh.3 +atan.3 +atan2.3 +atanh.3 +atoi.3 +cbrt.3 +ceil.3 +clock_getcpuclockid.3 +copysign.3 +cos.3 +cosh.3 +dirfd.3 +div.3 +dprintf.3 +ecvt.3 +erf.3 +erfc.3 +exp.3 +exp2.3 +expm1.3 +fabs.3 +fdim.3 +fexecve.3 +ffs.3 +floor.3 +fma.3 +fmax.3 +fmemopen.3 +fmin.3 +fmod.3 +fpclassify.3 +frexp.3 +fwide.3 +gamma.3 +gcvt.3 +getcwd.3 +getdate.3 +getgrent.3 +gethostid.3 +getpass.3 +getpwent.3 +getsubopt.3 +getw.3 +hypot.3 +ilogb.3 +insque.3 +isalpha.3 +isgreater.3 +iswblank.3 +j0.3 +j0.3 +ldexp.3 +lockf.3 +log.3 +log10.3 +log1p.3 +log2.3 +logb.3 +lrint.3 +lround.3 +mbsnrtowcs.3 +mkdtemp.3 +mkstemp.3 +mktemp.3 +modf.3 +mq_receive.3 +mq_send.3 +nan.3 +nextafter.3 +posix_fallocate.3 +posix_memalign.3 +pow.3 +printf.3 +qecvt.3 +random.3 +realpath.3 +remainder.3 +remquo.3 +rint.3 +rint.3 +round.3 +scalb.3 +scalbln.3 +scanf.3 +siginterrupt.3 +signbit.3 +sigset.3 +sin.3 +sinh.3 +sqrt.3 +stpcpy.3 +stpncpy.3 +strdup.3 +strdup.3 +strnlen.3 +strsignal.3 +strtod.3 +strtol.3 +strtoul.3 +tan.3 +tanh.3 +tgamma.3 +trunc.3 +ttyslot.3 +ualarm.3 +usleep.3 +wcpcpy.3 +wcpncpy.3 +wcscasecmp.3 +wcsdup.3 +wcsncasecmp.3 +wcsnlen.3 +wcsnrtombs.3 +wprintf.3 + Michael Kerrisk + Add/fix/update feature test macro requirements in SYNOPSIS + Various changes to: + * Update feature test requirements to note changes in + recent glibc releases + * Correct errors in feature test macro requirements + * Add feature test macro requirements to pages where + the requirements were not previously stated. + +accept.2 +clone.2 +dup.2 +fallocate.2 +pipe.2 +readahead.2 +sched_setaffinity.2 +unshare.2 +CPU_SET.3 +endian.3 +euidaccess.3 +fexecve.3 +getpt.3 +getpw.3 +getumask.3 +getutmp.3 +gnu_get_libc_version.3 +makedev.3 +matherr.3 +mbsnrtowcs.3 +memfrob.3 +pthread_attr_setaffinity_np.3 +pthread_getattr_np.3 +pthread_setaffinity_np.3 +pthread_tryjoin_np.3 +tcgetsid.3 +wcscasecmp.3 +wcsncasecmp.3 +wcsnlen.3 +wcsnrtombs.3 +wcswidth.3 +rtld-audit.7 + Michael Kerrisk + SYNOPSIS: Add reference to feature_test_macros(7) + These pages specify feature test macros in the function + prototypes. Add a reference to feature_test_macros(7), + so that readers are pointed to the information that + feature test macros must be defined before including + *any* header file. + +clock_nanosleep.2 +clock_getcpuclockid.3 +getnetent_r.3 +getprotoent_r.3 +getrpcent_r.3 +getservent_r.3 +sigwait.3 + Michael Kerrisk + RETURN VALUE: Note that "positive error numbers" are listed in ERRORS + +fcntl.2 +intro.2 +open.2 +poll.2 +ftw.3 +intro.3 +matherr.3 +system.3 +tmpnam.3 +unix.7 + Michael Kerrisk + Note that feature test macros must be defined before *any* includes + Programmers often make the mistake of including a feature test + macro only after having already included some header files. + This patch adds some text at opportune places to remind + programmers to do things the right way. + +index.3 +stpcpy.3 +strcasecmp.3 +strcat.3 +strchr.3 +strcmp.3 +strcoll.3 +strcpy.3 +strdup.3 +strfry.3 +strpbrk.3 +strsep.3 +strspn.3 +strstr.3 +strtok.3 +strxfrm.3 + Michael Kerrisk + SEE ALSO: Add reference to string(3) + The idea here is to provide a route to discover other + string functions. + +armscii-8.7 +cp1251.7 +iso_8859-3.7 +iso_8859-5.7 +iso_8859-6.7 +iso_8859-8.7 +iso_8859-10.7 +iso_8859-11.7 +iso_8859-13.7 +iso_8859-14.7 +koi8-u.7 + Denis Barbier + Fix decimal values in encoding tables + Octal and hexadecimal values are right, but there are some + off-by one errors in decimal values. Correct values are + printed by this command: + + perl -pi -e 'if (s/^([0-7]+)\t([0-9]+)\t([0-9a-fA-F]+)//) + {printf "%03o\t%d\t%s", hex($3), hex($3), $3;};' man7/*.7 + + +Changes to individual pages +--------------------------- + +capget.2 + Michael Kerrisk + SYNOPSIS: Remove unneeded "undef _POSIX_SOURCE" + +fcntl.2 + Michael Kerrisk + Add feature test macro requirements for F_GETOWN and F_SETOWN + +fcntl.2 + Michael Kerrisk + Note feature test macro requirements for F_DUPFD_CLOEXEC + +getrlimit.2 + Michael Kerrisk + Document units for RLIMIT_RTTIME limit + This limit is in microseconds + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=596492 + +lseek.2 + Michael Kerrisk + Removed note about return type on ancient systems + +mount.2 + Michael Kerrisk + Definitions of various MS_* constants only appeared in glibc 2.12 + See http://sourceware.org/bugzilla/show_bug.cgi?id=11235 + +stat.2 + Michael Kerrisk + Update information on nanosecond timestamp fields + Update feature test macro requirements for exposing these fields. + Note that these fields are specified in POSIX.1-2008. + +timer_create.2 + Michael Kerrisk + Factor out generic material that was moved to new sigevent(7) page + +aio_fsync.3 + Michael Kerrisk + Add reference to new sigevent(7) page + +atanh.3 + Michael Kerrisk + glibc 2.10 fixed pole error bug + http://sourceware.org/bugzilla/show_bug.cgi?id=6759 + was resolved. + +cerf.3 + Michael Kerrisk + Make it clearer that this function is unimplemented + +cos.3 + Michael Kerrisk + errno is now correctly set to EDOM on a domain error + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6780 + was (silently) resolved. + +expm1.3 + Michael Kerrisk + errno is now correctly set to ERANGE on a range error + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6788 + was (silently) resolved. + +fmod.3 + Michael Kerrisk + errno is now correctly set to EDOM for the x==inf domain error + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6784 + was (silently) resolved. + +insque.3 + Michael Kerrisk + Noted prev == NULL bug in glibc 2.4 and earlier + As noted by Remi Denis-Courmont, glibc nowadays allows + 'prev' to be NULL, as required by POSIX for initializing + a linear list. But in glibc 2.4 and earlier, 'prev' could + not be NULL. Add a BUGS section noting this. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=551201 + Michael Kerrisk + Added info on circular lists, and initializing circular lists + Michael Kerrisk + Added example program + +lgamma.3 + Michael Kerrisk + glibc 2.10 fixed pole error bug + http://sourceware.org/bugzilla/show_bug.cgi?id=6777 + was (silently) resolved. + +log2.3 + Matthew Flaschen + log2() function does not conform to C89 + log2(), log2f(), and log2l() do not conform to C89. + They are defined in C99. See http://flash-gordon.me.uk/ansi.c.txt + and http://www.schweikhardt.net/identifiers.html + +mq_notify.3 + Michael Kerrisk + Factor out generic material that was moved to new sigevent(7) page + +pow.3 + Michael Kerrisk + errno is now correctly set to ERANGE on a pole error + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6776 + was (silently) resolved. + +pthread_kill_other_threads_np.3 + Michael Kerrisk + CONFORMING TO: Note meaning of "_np" suffix + +rand.3 + Michael Kerrisk + Clarify description of range of returned value + Michael Kerrisk + Add an example program + Michael Kerrisk + Expand description of rand_r() + +random.3 + W. Trevor King + Update initstate() return value description to match glibc + +readdir.3 + Michael Kerrisk + Clarify that "positive error numbers" are listed in ERRORS + +rexec.3 + Michael Kerrisk + SYNOPSIS: Add header file and feature test macro requirements + +sigpause.3 + Michael Kerrisk + Correct discussion of when BSD vs SysV version is used in glibc + +sin.3 + Michael Kerrisk + errno is now correctly set to EDOM on a domain error + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6781 + was (silently) resolved. + +tan.3 + Michael Kerrisk + errno is now correctly set to EDOM on a domain error + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6782 + was (silently) resolved. + +wcscasecmp.3 +wcsncasecmp.3 +wcsnlen.3 + Michael Kerrisk + Added VERSIONS section + +boot.7 + Yuri Kozlov + Update list of major Linux distributions + +feature_test_macros.7 + Michael Kerrisk + Make text on required placement of macros more prominent + Move the text that notes the requirement that feature test macros + must be defined before including any header files to the top of + the page, and highlight the text further, so that the reader will + not miss this point. + +pthreads.7 +signal.7 + Michael Kerrisk + Add SEE ALSO reference to new sigevent(7) page + +tcp.7 + Michael Kerrisk + Clarify header file details for SIOCINQ and SIOCOUTQ + Also note synonymous FIONREAD and TIOCOUTQ. + + +==================== Changes in man-pages-3.28 ==================== + +Released: 2010-10-04, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andries E. Brouwer +Denis Barbier +Jan Kara +Landijk +Lennart Poettering +Michael Haardt +Michael Kerrisk +Petr Baudis +Sam Varshavchik + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +getaddrinfo_a.3 + Petr Baudis + New page documenting getaddrinfo_a() + The page also documents gai_suspend(), gai_cancel(), + and gai_error(). + +aio.7 + Michael Kerrisk + New page providing an overview of POSIX asynchronous I/O + + +Newly documented interfaces in existing pages +--------------------------------------------- + +exec.3 + Michael Kerrisk + Document execvpe() + This function was added to glibc in version 2.11. + Also various other small rewrites in the page. + + +New and changed links +--------------------- + +gai_cancel.3 +gai_error.3 +gai_suspend.3 + Petr Baudis + New links to new getaddrinfo_a.3 page + +error_one_per_line.3 + Michael Kerrisk + Fix misnamed link file (was error_on_per_line.3) + +execvpe.3 + Michael Kerrisk + New link to exec.3 + +sigstack.3 + Michael Kerrisk + New link to sigaltstack.2 + No new programs should use sigstack(3). Point the user to the + better sigaltstack(2), whose man page briefly mentions sigstack(3). + +vlimit.3 + Michael Kerrisk + New link to getrlimit.2 + No new programs should use vlimit(3). Point the user to the + better setrlimit(2), whose man page briefly mentions vlimit(3). + +vtimes.3 + Michael Kerrisk + New link to getrusage.2 + No new programs should use vtimes(3). Point the user to the + better getrusage(2), whose man page briefly mentions vtimes(3). + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Switch to American usage: "-wards" ==> "-ward" + American English uses "afterward" in preference to "afterwards", + and so on + +chdir.2 +chmod.2 +chown.2 +gethostname.2 +getsid.2 +pread.2 +setpgid.2 +sigaltstack.2 +stat.2 +truncate.2 +wait.2 +dirfd.3 +getsubopt.3 +mkdtemp.3 +mkstemp.3 +siginterrupt.3 +strdup.3 + Michael Kerrisk + Simplify feature test macro requirements + + +Changes to individual pages +--------------------------- + +getrlimit.2 + Michael Kerrisk + Add mention of the ancient vlimit() function + +getrusage.2 + Michael Kerrisk + Add mention of the ancient vtimes() function + +io_cancel.2 +io_destroy.2 +io_getevents.2 +io_setup.2 +io_submit.2 + Michael Kerrisk + SEE ALSO: add aio(7) + +sched_setscheduler.2 + Michael Kerrisk + ERRORS: note that NULL 'param' yields EINVAL + +stat.2 + Michael Kerrisk + Note feature test macro requirements for blkcnt_t and blksize_t + +timer_create.2 + Michael Kerrisk + Standardize on name 'sevp' for sigevent argument + +truncate.2 + Michael Kerrisk + Correct and simplify ftruncate() feature test macro requirements + The glibc 2.12 feature test macro requirements for ftruncate() are + buggy; see http://sourceware.org/bugzilla/show_bug.cgi?id=12037. + Corrected the requirements in the SYNOPSIS, and added a BUGS + section describing the problem in glibc 2.12. + +aio_cancel.3 + Michael Kerrisk + Add pointer to aio(7) for example program + Refer the reader to aio(7) for a description of the aiocb structure + CONFORMING TO: Add POSIX.1-2008; add VERSIONS section + +aio_error.3 + Michael Kerrisk + Wording improvements in RETURN VALUE + Add pointer to aio(7) for example program + Refer the reader to aio(7) for a description of the aiocb structure + CONFORMING TO: Add POSIX.1-2008; add VERSIONS section + +aio_fsync.3 + Michael Kerrisk + Refer the reader to aio(7) for a description of the aiocb structure + CONFORMING TO: Add POSIX.1-2008; add VERSIONS section + +aio_read.3 + Michael Kerrisk + Various minor rewordings and additions + Add pointer to sigevent(7) for details of notification of I/O completion + Add pointer to aio(7) for example program + Refer the reader to aio(7) for a description of the aiocb structure + CONFORMING TO: Add POSIX.1-2008; add VERSIONS section + +aio_return.3 + Michael Kerrisk + Improve description in RETURN VALUE + Add pointer to aio(7) for example program + Refer the reader to aio(7) for a description of the aiocb structure + CONFORMING TO: Add POSIX.1-2008; add VERSIONS section + +aio_suspend.3 + Michael Kerrisk + Various additions and rewordings. + Give some arguments more meaningful names. + More explicitly describe the 'nitems' argument. + Explicitly note that return is immediate if an I/O operation + has already completed. + Note that aio_error(3) should be used to scan the aiocb list + after a successful return. + Add references to other relevant pages. + Various other pieces rewritten. + Refer the reader to aio(7) for a description of the aiocb structure + CONFORMING TO: Add POSIX.1-2008; add VERSIONS section + +aio_write.3 + Michael Kerrisk + Add pointer to sigevent(7) for details of notification of I/O completion + Various minor rewordings and additions + Refer the reader to aio(7) for a description of the aiocb structure + CONFORMING TO: Add POSIX.1-2008; add VERSIONS section + +clearenv.3 + Michael Kerrisk + Fix error in feature test macro requirements + +dysize.3 + Michael Kerrisk + Remove crufty statement about old SCO bug + +exec.3 + Michael Kerrisk + Add feature test macro requirements for execvpe() + Rewrite description of PATH and mention _CS_PATH + Note execvp() and execlp() behavior for filename containing a slash + +getaddrinfo.3 + Michael Kerrisk + Add SEE ALSO reference to new getaddrinfo_a.3 page + +gethostbyname.3 + Michael Kerrisk + Fix formatting of feature test macros + +getw.3 + Michael Kerrisk + Fix feature test macros + +malloc.3 + Landijk + Remove editorializing comments on memory overcommitting + See https://bugzilla.kernel.org/show_bug.cgi?id=19332 + Michael Kerrisk + Various minor reorganizations and wording fix-ups + +mq_notify.3 + Michael Kerrisk + Standardize on name 'sevp' for sigevent argument + +nl_langinfo.3 + Michael Haardt + Make it clear that nl_langinfo() interacts with setlocale() + Add an example program + +posix_openpt.3 + Michael Kerrisk + Fix feature test macro requirements + +rand.3 + Michael Kerrisk + Remove duplicate #include in example program + +strtok.3 + Petr Baudis + Add reference to strtok() example in getaddrinfo(3) + +inotify.7 + Michael Kerrisk + Added section noting limitations and caveats of inotify + +sigevent.7 + Michael Kerrisk + Add SEE ALSO reference to new getaddrinfo_a.3 page + Add SEE ALSO referring to new aio(7) page + +suffixes.7 + Michael Kerrisk + Change explanation of ".rpm" to "RPM software package" + + +==================== Changes in man-pages-3.29 ==================== + +Released: 2010-10-19, Detroit + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Balazs Scheidler +David Prevot +Denis Barbier +Guillem Jover +Ivana Varekova +Lennart Poettering +Michael Kerrisk +Sam Varshavchik +Simon Paillard +Stephan Mueller +Thomas Jarosch +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +subpage_prot.2 + Michael Kerrisk + New page documenting the PowerPC-specific subpage_prot(2) + +aio_init.3 + Michael Kerrisk + New page documenting aio_init(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +posix_fadvise.2 + Michael Kerrisk + Document the architecture-specific arm_fadvise64_64() system call + This ARM-specific system call fixes the argument ordering + for that architecture. Since Linux 2.6.14. + +sync_file_range.2 + Michael Kerrisk + Document the architecture-specific sync_file_range2() system call + As described in commit edd5cd4a9424f22b0fa08bef5e299d41befd5622, + the sync_file_range() argument order is broken for some + architectures (PowerPC, ARM, tile). The remedy was a different + system call using the right argument order on those architectures. + +psignal.3 + Guillem Jover + Document psiginfo() + psiginfo() was added to glibc in version 2.10. + Michael Kerrisk + Add details, VERSIONS, and BUGS for psiginfo() + +ip.7 + Balazs Scheidler + Document IP_RECVORIGDSTADDR + Document IP_TRANSPARENT + Michael Kerrisk + Document IP_FREEBIND + Text based on input from Lennart Poettering and Balazs Scheidler. + See https://bugzilla.kernel.org/show_bug.cgi?id=20082 + + +New and changed links +--------------------- + +arm_fadvise64_64.2 + Michael Kerrisk + New link to posix_fadvise.2 + +arm_sync_file_range.2, sync_file_range2.2 + Michael Kerrisk + New links to sync_file_range.2 + +arrm_fadvise.2 + Michael Kerrisk + New link to posix_fadvise.2 + +psiginfo.3 + Guillem Jover + New link to psignal.3 + + +Global changes +-------------- + +Many pages + Michael Kerrisk + global fix: s/Unix/UNIX/ + The man pages were rather inconsistent in the use of "Unix" + versus "UNIX". Let's go with the trademark usage. + +Various pages + Michael Kerrisk + Global fix: s/pseudo-terminal/pseudoterminal/ + +grantpt.3, ptsname.3, unlockpt.3, pts.4 + Michael Kerrisk + Global fix: s/pty/pseudoterminal/ + +recv.2, cmsg.3, unix.7 + Michael Kerrisk + global fix: s/UNIX socket/UNIX domain socket/ + +fmtmsg.3, gethostbyname.3, termios.3 + Michael Kerrisk + Global fix: s/Unixware/UnixWare/ + + +Changes to individual pages +--------------------------- + +inotify_rm_watch.2 + Michael Kerrisk + SYNOPSIS: fix type of 'wd' argument + +posix_fadvise.2 + Michael Kerrisk + Rewrite VERSIONS, noting that the system call is fadvise64() + +syscalls.2 + Michael Kerrisk + Add the PowerPC-specific subpage_prot() system call + Add sync_file_range2() + +truncate.2 + Michael Kerrisk + Fix feature test macros + +aio_cancel.3 +aio_error.3 +aio_fsync.3 +aio_read.3 +aio_return.3 +aio_suspend.3 +aio_write.3 + Michael Kerrisk + SEE ALSO: Add lio_listio(3) + +gai_cancel.3 +gai_error.3 +gai_suspend.3 + Michael Kerrisk + Make these into links + In the previous release, these files were accidentally made copies + of getaddrinfo_a.3, instead of being made as link files. + +getifaddrs.3 + Thomas Jarosch + Prevent possible NULL pointer access in example program + +malloc.3 + Michael Kerrisk + Emphasize that malloc() and realloc() do not initialize allocated memory + +malloc_hook.3 + Ivana Varekova + Warn that these functions are deprecated + +strcpy.3 + Michael Kerrisk + Formatting fixes in strncpy() example implementation code + +ip.7 + Michael Kerrisk + Reword NOTES on Linux-specific options + +sigevent.7 + Michael Kerrisk + SEE ALSO: Add aio_read(3), aio_write(3), and lio_listio(3) + +unix.7 + Michael Kerrisk + Document the autobind feature + Michael Kerrisk + Fix description of abstract socket names + As reported by Lennart Poettering: + The part about "abstract" sockets is misleading as it suggests + that the sockaddr returned by getsockname() would necessarily + have the size of sizeof(struct sockaddr), which however is not + the case: getsockname() returns exactly the sockaddr size that + was passed in on bind(). In particular, two sockets that are + bound to the same sockaddr but different sizes are completely + independent. + See https://bugzilla.kernel.org/show_bug.cgi?id=19812 + Michael Kerrisk + Fix description of "pathname" sockets + As reported by Lennart Poettering: + The part about "pathname" sockets suggests usage of + sizeof(sa_family_t) + strlen(sun_path) + 1 + for calculating the sockaddr size. Due to alignment/padding + this is probably not a good idea. Instead, one should use + offsetof(struct sockaddr_un, sun_path) + strlen() + 1 + or something like that. + See https://bugzilla.kernel.org/show_bug.cgi?id=19812 + + +==================== Changes in man-pages-3.30 ==================== + +Released: 2010-11-01, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +Bernhard Walle +David Prevot +Eric W. Biederman +Florian Lehmann +Jan Engelhardt +Lucian Adrian Grijincu +Michael Kerrisk +Paul Mackerras +Pádraig Brady +Reuben Thomas +scarlettsp +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +kexec_load.2 + Andi Kleen + New page documenting kexec_load(2) + Michael Kerrisk + Add license + Michael Kerrisk + Incorporate fixes from Eric W. Biederman + Eric noted that a few instances of "virtual" should + be "physical" and noted: + + There is an expectation that at hand off from sys_kexec that + virtual and physical addresses will be identity mapped. But + this isn't the old Alpha booting convention where you have + a virtual address and then you have to parse the page table + to figure out where your kernel was actually loaded. + Michael Kerrisk + Additions and edits by mtk + Various wording and layout improvements. + Fixed the name of a constant: s/KEXEC_ARCH_I386/KEXEC_ARCH_386/. + Added RETURN VALUE and ERRORS sections. + Added VERSIONS section + Note that CONFIG_KEXEC is needed + Removed details of using syscall; the reader can find them in + syscall(2). + Added some details for KEXEC_PRESERVE_CONTEXT. + Revised the text mentioning the kernel header, since it is + not yet exported, and it's not certain that it will be. + +lio_listio.3 + Michael Kerrisk + New page documenting lio_listio(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +reboot.2 + Andi Kleen + Document LINUX_REBOOT_KEXEC + Some fix-ups by Michael Kerrisk + Michael Kerrisk + Place 'cmd' values in alphabetical order. + +unshare.2 + Michael Kerrisk + Document CLONE_NEWIPC + Michael Kerrisk + Document CLONE_NEWNET + Lucian Adrian Grijincu + Improve description of CLONE_NEWNET + CLONE_NEWNET creates a new network namespace from scratch. + You don't have anything from the old network namespace in + the new one. Even the loopback device is new. + Michael Kerrisk + Document CLONE_SYSVSEM + Michael Kerrisk + Document CLONE_NEWUTS + Michael Kerrisk + Relocate discussion of CAP_SYS_ADMIN to CLONE_NEWNS section + And rewrite the EPERM description to be more general in + preparation for the new flags to be documented. + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Add reference to feature_test_macros(7) + Some pages simply list feature test macro requirements in + the form: + + #define #GNU_SOURCE + #include + + For these pages, add a "See feature_test_macros(7)" comment + on the "#define" line. + +Various pages + Michael Kerrisk + SEE ALSO: Remove redundant reference to feature_test_macros(7) + +Various pages + David Prevot + Use greater consistency in NAME line + (Remove definite article at start of descriptive clause.) + +Various pages + Michael Kerrisk + SEE ALSO: Place entries in correct order + +Various pages + Michael Kerrisk + ERRORS: Place entries in correct order + +Various pages + Michael Kerrisk + Add section number to references to functions documented in other pages + +Various pages + Michael Kerrisk + Remove redundant section number in page references + Remove section number in function references that are for + functions documented on this page. + +armscii-8.7 +iso_8859-3.7 +iso_8859-4.7 +iso_8859-5.7 +iso_8859-6.7 +iso_8859-10.7 +iso_8859-11.7 +iso_8859-13.7 +iso_8859-14.7 +koi8-u.7 + David Prevot + Capitalize hexadecimal numbers + + +Changes to individual pages +--------------------------- + +access.2 + Michael Kerrisk + Note use of faccessat(2) for checking symbolic link permissions + Michael Kerrisk + Give an example of a safer alternative to using access() + +clone.2 + Michael Kerrisk + Clarify when CLONE_NEWNET implementation was completed + +faccessat.2 + Michael Kerrisk + Note that faccessat() is racy + +fcntl.2 + Michael Kerrisk + RETURN VALUE: Improve description of F_GETFD and F_GETFL + +inotify_add_watch.2 + Michael Kerrisk + Document ENOENT error + +mlock.2 + Michael Kerrisk + Improve wording describing /proc/PID/status /VmLck field + Michael Kerrisk + shmctl() SHM_LOCKed memory is not included in VmLck + +reboot.2 + Michael Kerrisk + Place 'cmd' values in alphabetical order + +subpage_prot.2 + Michael Kerrisk + Change 1-line page description + Michael Kerrisk + Improvements after review by Paul Mackerras + +timer_settime.3 + Michael Kerrisk + Remove redundant SEE ALSO reference + +euidaccess.3 + Michael Kerrisk + Note the use of faccessat(2) to operate on symbolic links + Michael Kerrisk + Note that the use of euidaccess() is racy + +fenv.3 + Michael Kerrisk + Clarify wording relating to glibc version + +getgrent.3 +getgrent_r.3 +getgrnam.3 + Michael Kerrisk + Refer reader for group(5) for more info on group structure + +getopt.3 + Bernhard Walle + Use constants in getopt_long() example + The description of getopt_long() mentions the constants + required_argument, no_argument and optional_argument. + Use them in the example to make the code easier to understand. + +getpw.3 + Michael Kerrisk + Change comment describing pw_gecos + +getpw.3 +getpwent.3 +getpwent_r.3 + Michael Kerrisk + Refer reader to passwd(5) for more info on the passwd structure + +getpwent.3 +getpwnam.3 + Michael Kerrisk + Note that pw_gecos is not in POSIX + And change the comment describing this field + +getpwent_r.3 + Michael Kerrisk + Change comment describing pw_gecos + +getpwnam.3 + Michael Kerrisk + Some rewording and restructuring + +sched_getcpu.3 + Michael Kerrisk + Fix feature test macro requirements + +strnlen.3 + Michael Kerrisk + Fix feature test macro requirements + +group.5 + Michael Kerrisk + Various minor rewordings + +hosts.5 +protocols.5 +spufs.7 +termio.7 + David Prevot + Remove definite article from NAME section + Please find inline another tiny patch in order to shrink + the definite article from some other pages (found with + "rgrep -i ' \\\- the' man*"). + +passwd.5 + Michael Kerrisk + Various minor rewordings + +proc.5 + Michael Kerrisk + Add reference to mlock(2) for further info on /proc/PID/status VmLck + +armscii-8.7 + David Prevot + Write the character set name as ArmSCII + +cp1251.7 + David Prevot + Capitalize hexadecimal numbers + +ip.7 + David Prevot + Fix name of socket option: s/IP_TTL/IP_TRANSPARENT/ + David Prevot + Place socket options in alphabetical order + +koi8-r.7 + David Prevot + Fix special character names + Comparing to koi8-u.7, I noticed some inconsistencies in special + character names. After checking with the following Unicode related + pages, please find inline (and gzipped attached, hopefully not + messing with encoding), a patch in order to make it right, on an + Unicode point of view. + + http://www.unicode.org/charts/PDF/U2500.pdf + http://www.unicode.org/charts/PDF/U25A0.pdf + http://www.unicode.org/charts/PDF/U0080.pdf + http://www.unicode.org/charts/PDF/U1D400.pdf + David Prevot + Fix SEE ALSO reference and letter names + The koi8-r(7) (Russian Net Character Set) manual page refers + to iso-8859-7(7) manual page, which is the Latin/Greek one. + I guess it should refer instead to the iso-8859-5(7) + (Latin/Cyrillic) one. This is addressed at the end of the patch. + + It has also been spotted that letter names are different in + this manual page and in the Unicode related page [0], the + first part of the page address this. + + 0: http://www.unicode.org/charts/PDF/U0400.pdf + +man-pages.7 + Michael Kerrisk + Update example + The old example used the chmod(2) man page, but the + feature test macro requirements on that page had changed. + Update to use an example from a different page (acct(2), + whose feature test macro requirements are probably unlikely + to change in the future). + + +==================== Changes in man-pages-3.31 ==================== + +Released: 2010-11-12, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Andi Kleen +David Prevot +Denis Barbier +Krzysztof Żelechowski +Michael Kerrisk +Yuri Kozlov + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +getrlimit.2 + Michael Kerrisk + Added documentation of prlimit() + prlimit() is new in kernel 2.6.36. + +inotify.7 + Michael Kerrisk + Document IN_EXCL_UNLINK + This flag was added in Linux 2.6.36. + See kernel commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6. + + +New and changed links +--------------------- + +prlimit.2 + Michael Kerrisk + New link to getrlimit.2 + + +Changes to individual pages +--------------------------- + +getrlimit.2 + Michael Kerrisk + Remove unneeded text in DESCRIPTION + +intro.2 + Michael Kerrisk + Added various pages to SEE ALSO + +kexec_load.2 + Michael Kerrisk + Add kernel version where KEXEC_PRESERVE_CONTEXT first appeared + Added kernel version number where KEXEC_ON_CRASH first appeared + Fix copyright + Make copyright in the name of Intel corporation + VERSIONS: Fix version number + kexec_load() was first implemented in 2.6.13, though the entry + in the system call table was reserved starting in 2.6.7. + +migrate_pages.2 + Michael Kerrisk + SEE ALSO: Add reference to Documentation/vm/page_migration + +sched_setaffinity.2 + Michael Kerrisk + Add missing word "real" to "user ID" + +syscalls.2 + Michael Kerrisk + Fix kernel version number for kexec_load + kexec_load() was first implemented in 2.6.13, though the entry + in the system call table was reserved starting in 2.6.7. + Michael Kerrisk + Add prlimit() to list + +intro.3 + Michael Kerrisk + Added various pages to SEE ALSO + +printf.3 + Michael Kerrisk + Formatting fixes in example code + +hostname.7 + Michael Kerrisk + Small improvement to description of domains + See: https://bugzilla.novell.com/show_bug.cgi?id=651900 + + +==================== Changes in man-pages-3.32 ==================== + +Released: 2010-12-03, Munich + + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +A. Costa +Denis Barbier +Emil Mikulic +Eugene Kapun +Hugh Dickins +Ivana Hutarova Varekova +Joern Heissler +Lars Wirzenius +Martin Eberhard Schauer +Michael Kerrisk +Petr Uzel +Roger Pate +Török Edwin +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pthread_sigqueue.3 + Michael Kerrisk + New page documenting pthread_sigqueue() + pthread_sigqueue() is new in glibc 2.11 (requires a kernel with + rt_tgsigqueinfo(), added in Linux 2.6.31). + + +Newly documented interfaces in existing pages +--------------------------------------------- + +readv.2 + Michael Kerrisk + Add documentation of preadv() and pwritev() + The preadv() and pwritev() system calls were added in + Linux 2.6.30. + + +New and changed links +--------------------- + +preadv.2 + Michael Kerrisk + New link to readv.2 + +pwritev.2 + Michael Kerrisk + New link to readv.2 + + +Changes to individual pages +--------------------------- + +chdir.2 + Michael Kerrisk + Remove redundant and incorrect info on FTMs from NOTES + +chown.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +clock_nanosleep.2 + Michael Kerrisk + Clarify that clock_nanosleep() suspends the calling *thread* + +epoll_create.2 + Michael Kerrisk + Note that 'size' argument must be greater than 0 + See https://bugzilla.kernel.org/show_bug.cgi?id=23872 + Michael Kerrisk + Added VERSIONS section + +epoll_ctl.2 + Michael Kerrisk + Added VERSIONS section + +epoll_wait.2 + Michael Kerrisk + Updated VERSIONS section + +fcntl.2 + Michael Kerrisk + Add notes on fcntl64() + +fstatat.2 + Michael Kerrisk + Add NOTES on fstatat64(), the name of the underlying system call + +getdents.2 + Michael Kerrisk + Added notes on getdents64() + +getgid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +getgroups.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +getpagesize.2 + Michael Kerrisk + Improve description of getpagesize() + Improve description of getpagesize() and relocate discussion + of sysconf(_SC_PAGESIZE). + + In part inspired by + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=537272 + +getresuid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +getrlimit.2 + Michael Kerrisk + Add example program for prlimit() + +getuid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +open.2 + Ivana Hutarova Varekova + O_EXCL can be used without O_CREAT for block devices + Since Linux 2.6 there is a possibility to use O_EXCL without + O_CREAT. See patch: http://lkml.org/lkml/2003/8/10/221. + +pread.2 + Michael Kerrisk + Add notes on pread64() and pwrite64() + See https://bugzilla.kernel.org/show_bug.cgi?id=23072 + Michael Kerrisk + SEE ALSO: add readv(3) + +readv.2 + Michael Kerrisk + Wording fix: readv() and writev() are system calls, not functions + +sendfile.2 + Michael Kerrisk + Add notes on sendfile64() + +setfsgid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +setfsuid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +setgid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +setresuid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +setreuid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +setuid.2 + Michael Kerrisk + Add NOTES explaining 32-bit system calls added in Linux 2.4 + +sigqueue.2 +pthreads.7 +signal.7 + Michael Kerrisk + SEE ALSO: Add pthread_sigqueue(3) + +stat.2 + Michael Kerrisk + Fix EOVERFLOW error description + 2<<31 should read 1<<31 (which equals 2^31). + +statfs.2 + Michael Kerrisk + Add notes on statfs64() and fstatfs64() + +swapon.2 + Hugh Dickins + Document SWAP_FLAG_DISCARD and discarding of swap pages + +truncate.2 + Michael Kerrisk + Add notes on truncate64() and ftruncate64() + +memcpy.3 + Michael Kerrisk + Change "should not overlap" to "must not overlap" + glibc 2.12 changed things so that applications that use memcpy() on + overlapping regions will encounter problems. (The standards have + long said that the behaviors is undefined if the memory areas + overlap.) + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=603144 + In reference of http://lwn.net/Articles/414467/ + and http://article.gmane.org/gmane.comp.lib.glibc.alpha/15278 + +usleep.3 + Petr Uzel + usleep() suspends calling thread, not process + +core.5 + Michael Kerrisk + Change single quote to double quote in shell session example + The example section has a sample shell session containing: + + echo '|$PWD/core_pattern_pipe_test %p UID=%u GID=%g sig=%s' + + But $PWD won't be expanded in single quotes. It should be double + quotes around the entire argument or some other form. + +pthreads.7 + Michael Kerrisk + Added description of async-cancel-safe functions + +unix.7 + Michael Kerrisk + Reworded the text of various errors + Michael Kerrisk + Added ENOENT error + + +==================== Changes in man-pages-3.33 ==================== + +Released: 2011-09-16, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes and ideas that have been +incorporated in changes in this release: + +Akira Fujita +Alexander Schuch +Andries Brouwer +Brian M. Carlson +Dan Jacobson +Folkert van Heusden +Graham Gower +Hendrik Jan Thomassen +Jan Engelhardt +Joey Adams +Johannes Laire +Jon Grant +Josh Triplett +Konstantin Ritt +Luis Javier Merino +Michael Kerrisk +Mike Frysinger +Mikel Ward +Nick Black +Paul Evans +Petr Pisar +Przemyslaw Pawelczyk +Regid Ichira +Reuben Thomas +Richard B. Kreckel +Ryan Mullen +Sebastian Geiger +Sebastian Unger +Seonghun Lim +Serge E. Hallyn +Simon Cross +Simon Paillard +Stan Sieler +Timmy Lee +Tolga Dalman +Tomislav Jonjic +Yuri Kozlov +Wei Luosheng + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +sync.2 + Michael Kerrisk + Added new syncfs() system call + syncfs() was added in Linux 2.6.39. + + +New and changed links +--------------------- + +syncfs.2 + Michael Kerrisk + New link for sync(2). + + +Global changes +-------------- + +Various pages + Simon Paillard + Global fix: properly escape minus sign + + +Changes to individual pages +--------------------------- + +clone.2 + Michael Kerrisk + Note that CLONE_STOPPED was removed in 2.6.38 + +execve.2 + Michael Kerrisk [Sebastian Geiger] + Note that the first argv[] value should contain name of executable + +fcntl.2 + Michael Kerrisk [Reuben Thomas] + Note that F_GETFL also retrieves file access mode + +getrlimit.2 + Michael Kerrisk [Ryan Mullen] + Remove mention of kernel versions in discussion of RLIMIT_CPU + Michael Kerrisk [Seonghun Lim] + Fix example program and add _FILE_OFFSET_BITS requirement + +mlock.2 + Michael Kerrisk [Brian M. Carlson] + Clarify EINVAL error + See http://bugs.debian.org/cgi-bin/bugreport.cgi?625747 + Michael Kerrisk [Seonghun Lim] + Simplify and correct text for EPERM error + +mprotect.2 + Seonghun Lim + Fix off-by-one error in a memory range + Seonghun Lim + Fix small bug in example program + The description of the example program says that it makes the + third page "read-only". Thus use PROT_READ instead of PROT_NONE. + +open.2 + Folkert van Heusden + Remove text describing O_CLOEXEC as Linux-specific + O_CLOEXEC is specified in POSIX.1-2008, as noted + elsewhere in the page. + +readlink.2 + Michael Kerrisk [Dan Jacobson] + SEE ALSO: Add readlink(1) + +sendfile.2 + Akira Fujita + Since 2.6.33, 'out_fd' can refer to any file type + Linux kernel commit cc56f7de7f00d188c7c4da1e9861581853b9e92f + meant sendfile(2) can work with any output file. + Michael Kerrisk + Shift text on falling back to read()/write() to NOTES + Michael Kerrisk [Tolga Dalman] + Remove mention of kernel version for 'in_fd' argument + Tolga Dalman + Add an explicit reference to splice(2) + Unlike sendfile(), splice() can transfer data + between a pair of sockets. + +sigaction.2 + Michael Kerrisk [Tolga Dalman] + Add a little info about ucontext_t + +stat.2 + Michael Kerrisk [Jon Grant] + Small rewording of ENAMETOOLONG error + +sync.2 + Michael Kerrisk + Some rewrites to description of sync() + +syscalls.2 + Michael Kerrisk + Added fanotify_init() and fanotify_mark() to syscall list + Michael Kerrisk + Added new 2.6.39 system calls + Michael Kerrisk + Updated for Linux 3.0 system calls + Michael Kerrisk + Update kernel version at head of syscall list + Michael Kerrisk + Update to mention 3.x kernel series + +syslog.2 + Michael Kerrisk [Serge E. Hallyn] + Update for kernel 2.6.37 changes + Document /proc/sys/kernel/dmesg_restrict. + Document CAP_SYSLOG. + +time.2 + Michael Kerrisk [Alexander Schuch] + NOTES: Fix description of "Seconds since the Epoch" + +timerfd_create.2 + Michael Kerrisk [Josh Triplett] + Note behavior when timerfd_settime() old_value is NULL + See http://bugs.debian.org/cgi-bin/bugreport.cgi?641513 + Tomislav Jonjic + Fix small error in description of timerfd_settime() + +truncate.2 + Seonghun Lim + Remove redundant EINTR description + +unlink.2 + Hendrik Jan Thomassen + Improve EBUSY description + +cacos.3 +cacosh.3 +catan.3 +catanh.3 + Michael Kerrisk [Richard B. Kreckel, Andries Brouwer] + Fix formula describing function + The man pages for cacos(), cacosh(), catan(), catanh() + contain incorrect formulae describing the functions. + +cacos.3 + Michael Kerrisk + Add example program + +cacosh.3 + Michael Kerrisk + Add example program + +cacosh.3 +casinh.3 +catan.3 +catanh.3 + Michael Kerrisk + SEE ALSO: Add reference to inverse function + +catan.3 + Michael Kerrisk + Add example program + +catanh.3 + Michael Kerrisk + Add example program + +ccos.3 +ccosh.3 +csin.3 +csinh.3 +ctan.3 +ctanh.3 + Michael Kerrisk + SEE ALSO Add reference to "arc" inverse function + +cexp.3 + Michael Kerrisk + SEE ALSO: add cexp(3) + +clog.3 + Michael Kerrisk + SEE ALSO: Add reference to clog(2) + +crypt.3 + Michael Kerrisk [Jan Engelhardt] + Fix header file and feature test macro requirements for crypt_r() + +err.3 + Seonghun Lim + Clean up description of error message source + In the second paragraph of DESCRIPTION section, one of the + sources of error messages is incorrect: the four functions obtain + error message only from errno, and "a code" is just relevant + with errc() and warnc(), which are not present on Linux. + see http://www.unix.com/man-page/freebsd/3/ERR/ . + + Then, the third paragraph becomes a duplicate. + +fflush.3 + Regid Ichira + Fix wording error + See http://bugs.debian.org/cgi-bin/bugreport.cgi?614021 + +hsearch.3 + Seonghun Lim + Update ERRORS section + EINVAL can occur for hdestroy_r(). + EINVAL can't occur for hcreate(). + Other minor fixes. + +lockf.3 + Michael Kerrisk [Mikel Ward] + ERRORS: EBADF can also occur for nonwritable file descriptor + As noted in the DESCRIPTION, the file descriptor must be writable + in order to place a lock. + +malloc.3 + Seonghun Lim + Reorder prototypes in SYNOPSIS + calloc() comes before realloc() in the other sections, + so should do in SYNOPSIS, too. + +mbstowcs.3 + Michael Kerrisk + SEE ALSO: add reference to wcstombs(3) + +memcmp.3 + Michael Kerrisk [Sebastian Unger] + Clarify that comparison interprets bytes as "unsigned char" + +realpath.3 + Michael Kerrisk [Seonghun Lim] + Fix EINVAL error + Since glibc 2.3, resolved_path can be non-NULL (with the + semantics already documented in the page). + +scandir(3) + Mike Frysinger + Add ENOENT/ENOTDIR errors + +siginterrupt.3 + Michael Kerrisk [Luis Javier Merino] + Remove misleading sentence about signal(2) and system call interruption + +strlen.3 + Michael Kerrisk [Jon Grant] + SEE ALSO: Add strnlen(3) + +strnlen.3 + Michael Kerrisk [Jon Grant] + CONFORMING TO: Note that strnlen() is in POSIX.1-2008 + +strtoul.3 + Michael Kerrisk [Tolga Dalman] + Fix NOTES section constants + +termios.3 + Michael Kerrisk + Use "terminal special characters" consistently throughout page + Michael Kerrisk [Paul Evans] + Add documentation of _POSIX_VDISABLE + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=627841 + Michael Kerrisk + Add a description of STATUS character + Michael Kerrisk + Added description of SWTCH character + Michael Kerrisk + Add names of terminal special characters + Michael Kerrisk + List terminal special characters in alphabetical order + +wcstombs.3 + Michael Kerrisk + SEE ALSO: add mbstowcs(3) + +console_codes.4 + Petr Pisar + Add ESC [ 3 J + Linux 3.0 (commit f8df13e0a901fe55631fed66562369b4dba40f8b) + implements \E[3J to allow scrambling content of console + including scroll-back buffer + (http://thread.gmane.org/gmane.linux.kernel/1125792). + +proc.5 + Michael Kerrisk [Stan Sieler] + Add description of 'PPid' field of /proc/PID/status + Michael Kerrisk [Stan Sieler] + Add description of 'SigQ' field of /proc/PID/status + +capabilities.7 + Michael Kerrisk [Serge E. Hallyn] + Document CAP_SYSLOG and related changes in Linux 2.6.37 + Michael Kerrisk + File capabilities are no longer optional + Starting with Linux 2.6.33, the CONFIG_SECURITY_FILE_CAPABILITIES + has been removed, and file capabilities are always part of the + kernel. + +complex.7 + Michael Kerrisk + Updated SEE ALSO list to include all complex math functions + +ipv6.7 + Michael Kerrisk [Simon Cross] + Fix description of address notation: "8 4-digit hexadecimal numbers" + +signal.7 + Seonghun Lim + Remove crufty repeated info about LinuxThreads + +unix.7 + Michael Kerrisk + Add pointer to cmsg(3) for an example of the use of SCM_RIGHTS + + +==================== Changes in man-pages-3.34 ==================== + +Released: 2011-09-23, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes and ideas that have been +incorporated in changes in this release: + +Alan Curry +Benjamin Poirier +Brian M. Carlson +David Howells +David Prévot +Denis Barbier +Doug Goldstein +Eric Blake +Guillem Jover +Jon Grant +Michael Kerrisk +Neil Horman +Paul Pluzhnikov +Reuben Thomas +Stefan Puiu +Stephan Mueller +Stephen Cameron +Sunil Mushran + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +rt_sigqueueinfo.2 + Michael Kerrisk [Stephan Mueller] + New page for rt_sigqueueinfo(2) and rt_tgsigqueueinfo(2) + This replaces the previous '.so' man page link file for + rt_sigqueueinfo.2, which linked to this sigqueue() man page. + +cciss.4 + Stephen M. Cameron + New man page for cciss driver + I obtained the information in this man page as a consequence + of having worked on the cciss driver for the past several years, + and having written considerable portions of it. + Michael Kerrisk + Copyedit by mtk + +hpsa.4 + Stephen M. Cameron + New man page for the hpsa driver + I obtained the information in this man page as a consequence + of being the main author of the hpsa driver. + Michael Kerrisk + Copyedits my mtk + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fstatat.2 + Michael Kerrisk [David Howells] + Document AT_NO_AUTOMOUNT + This flag was added in Linux 2.6.38. + +lseek.2 + Michael Kerrisk [Eric Blake, Sunil Mushran] + Document SEEK_HOLE and SEEK_DATA + These flags, designed for discovering holes in a file, + were added in Linux 3.1. Included comments from Eric + Blake and Sunil Mushran. + +madvise.2 + Doug Goldstein + Add MADV_HUGEPAGE and MADV_NOHUGEPAGE + Document the MADV_HUGEPAGE and MADV_NOHUGEPAGE flags added to + madvise() in Linux 2.6.38. + + +New and changed links +--------------------- + +rt_tgsigqueueinfo.2 + Michael Kerrisk + New link to new rt_sigqueueinfo.2 page + +sigqueue.2 + Michael Kerrisk + Create link to page that was relocated to section 3 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Change reference to "sigqueue(2)" to "sigqueue(3)" + + +Changes to individual pages +--------------------------- + +fallocate.2 + Michael Kerrisk + ERRORS: Add EPERM and ESPIPE errors + +lseek.2 + Michael Kerrisk [Alan Curry, Reuben Thomas] + Remove suspect note about 'whence' being incorrect English + +prctl.2 + Paul Pluzhnikov + PR_SET_DUMPABLE makes process non-ptrace-attachable + +readlink.2 + Guillem Jover + Document using st_size to allocate the buffer + Michael Kerrisk + Added copyright text + changelog note for Guillem Jover's patch + +sched_setscheduler.2 + Michael Kerrisk + Document 2.6.39 changes to rules governing changes from SCHED_IDLE policy + Since Linux 2.6.39, unprivileged processes under the + SCHED_IDLE policy can switch to another nonrealtime + policy if their nice value falls within the range + permitted by their RLIMIT_NICE limit. + +tkill.2 + Michael Kerrisk + SEE ALSO: Add rt_sigqueueinfo (2) + +btowc.3, wctob.3 + Michael Kerrisk [Brian M. Carlson] + Add pointers to better, thread-safe alternative functions + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=606899 + +fwide.3 + Michael Kerrisk + Add _ISOC95_SOURCE to feature test macro requirements + Since glibc 2.12, _ISOC95_SOURCE can also be used to expose + prototype of this function. + +index.3 + Michael Kerrisk [Jon Grant] + Fix text mentioning terminating null + +pthread_sigqueue.3 + Michael Kerrisk + Replace explicit mention of rt_tgsigqueueinfo() with SEE ALSO reference + +sigqueue.3 + Michael Kerrisk + Move this page to section 3 + Now that the underlying system call rt_sigqueueinfo(2) is + properly documented, move sigqueue() to Section 3, since + it is really a library function. + Michael Kerrisk + Update text in line with existence of new rt_sigqueueinfo.2 page + +wcsnlen.3 + Jon Grant + Improve description of 'maxlen' argument + It's worth clarifying 'maxlen' is in wide-char units, not bytes. + +wprintf.3 + Michael Kerrisk + Add _ISOC95_SOURCE to feature test macro requirements + Since glibc 2.12, _ISOC95_SOURCE can also be used to expose + prototype of these functions. + +feature_test_macros.7 + Michael Kerrisk + Document _ISOC95_SOURCE + _ISOC95_SOURCE was added in glibc 2.12 as a means + to expose C90 Amendment 1 definitions. + +ip.7 + Benjamin Poirier [Neil Horman] + Improve description of IP_MTU_DISCOVER + +signal.7 + Michael Kerrisk + SEE ALSO: Add rt_sigqueueinfo(2) + + +==================== Changes in man-pages-3.35 ==================== + +Released: 2011-10-04, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes and ideas that have been +incorporated in changes in this release: + +Andi Kleen +David Prévot +Denis Barbier +Eric W. Biederman +Guillem Jover +Jon Grant +Kevin Lyda +Michael Kerrisk +Mike Frysinger +Reuben Thomas + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +recvmmsg.2 + Andi Kleen, Michael Kerrisk + New man page for recvmmsg(2) + +setns.2 + Eric W. Biederman + New manual page for setns(2) + Michael Kerrisk + Various improvements + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix: remove spaces around em-dash + Normal English typographical convention is not to have + spaces around em dashes. + +Various pages + Michael Kerrisk + Global fix: s/null pointer/NULL pointer/ + +Various pages + Michael Kerrisk + Global fix: use ORing + Use "ORing", not "OR'ing", nor an italic ".IR OR ing". + +Various pages + Michael Kerrisk + Global fix: consistent use of "null wide character" + Bring more consistency to the discussion of + "[terminating] null wide character" + by writing (at least in the initial use in a page) + "[terminating] null wide character (L'\0')". + +Various pages + Michael Kerrisk + Global fix: consistent use of "null byte" + Bring more consistency to the discussion of + "[terminating] null byte" + by writing (at least in the initial use in a page) + "[terminating] null byte ('\0')". + +mount.2, prctl.2 + Michael Kerrisk + s/task/thread/ for consistency with other pages + + +Changes to individual pages +--------------------------- + +lseek.2 + Guillem Jover + CONFORMING TO: Note other systems that have SEEK_HOLE+SEEK_DATA + +recv.2 + Michael Kerrisk + Add mention of recvmmsg(2) + +recvmmsg.2 + Michael Kerrisk + SEE ALSO: add sendmmsg(2) + +send.2 + Michael Kerrisk + CONFORMING TO: POSIX.1-2008 adds MSG_NOSIGNAL + +sigwaitinfo.2 + Michael Kerrisk + Note that attempts to wait for SIGKILL and SIGSTOP are silently ignored + +stat.2 + Michael Kerrisk + Note POSIX.1-2001 and POSIX.1-2008 requirements for lstat() + Michael Kerrisk + Regarding automounter action, add a reference to fstatat(2) + Michael Kerrisk + Clean up text describing which POSIX describes S_IF* constants + +aio_cancel.3 + Michael Kerrisk [Jon Grant] + Clarify meaning of "return status" and "error status" + +gets.3 + Michael Kerrisk + POSIX.1-2008 marks gets() obsolescent + The page formerly erroneously stated that POSIX.1-2008 + removed the specification of this function. + +mbsnrtowcs.3 + Michael Kerrisk + CONFORMING TO: Add POSIX.1-2008 + This function is specified in the POSIX.1-2008 revision. + +regex.3 + Michael Kerrisk [Reuben Thomas] + Change "terminating null" to "terminating null byte" + +stpcpy.3 +stpncpy.3 + Mike Frysinger + Note that these functions are in POSIX.1-2008 + Update the "CONFORMING TO" sections of these functions to + note that they are now part of the POSIX.1-2008 standard. + +stpncpy.3 + Michael Kerrisk + Change "terminating null" to "terminating null byte" + +strcpy.3 + Mike Frysinger + SEE ALSO: Add stpncpy(3) + +strdup.3 + Michael Kerrisk + CONFORMING TO: strndup() is in POSIX.1-2008 + +wcpcpy.3 +wcpncpy.3 +wcsnlen.3 +wcsnrtombs.3 + Michael Kerrisk + CONFORMING TO: Add POSIX.1-2008 + These functions are specified in the POSIX.1-2008 revision. + +proc.5 + Eric W. Biederman + Document /proc/[pid]/ns/ + Michael Kerrisk + Some edit's to Eric Biederman's /proc/[pid]/ns/ additions + +capabilities.7 + Michael Kerrisk + List setns(2) as an operation allowed by CAP_SYS_ADMIN + + +==================== Changes in man-pages-3.36 ==================== + +Released: 2012-02-27, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes and ideas that have been +incorporated in changes in this release: + +Alain Benedetti +carado +Christoph Hellwig +Clemens Ladisch +David Prévot +Elie De Brauwer +Guillem Jover +Jessica McKellar +Josef Bacik +Junjiro Okajima +Lucian Adrian Grijincu +Michael Kerrisk +Mike Frysinger +Pat Pannuto +Salvo Tomaselli +Simone Piccardi +Slaven Rezic +starlight +Stephan Mueller +Vijay Rao +Walter Haidinger +Walter Harms +Yang Yang + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +sendmmsg.2 + Michael Kerrisk [Stephan Mueller] + New page for sendmmsg(2) + Some pieces inspired by an initial attempt by Stephan Mueller. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fallocate.2 + Lucian Adrian Grijincu + Document FALLOC_FL_PUNCH_HOLE + FALLOC_FL_PUNCH_HOLE was added in Linux 2.6.38, + for punching holes in the allocated space in a file. + + +Changes to individual pages +--------------------------- + +dup.2 + Michael Kerrisk + SYNOPSIS: Add "#include " for O_* constants + +fallocate.2 + Michael Kerrisk + Substantial restructuring of DESCRIPTION + The addition of a second class of operation ("hole punching") + to the man page made it clear that some significant restructuring + is required. So I substantially reworked the page, including the + preexisting material on the default "file allocation" operation. + Michael Kerrisk [Josef Bacik] + Add further details for FALLOC_FL_PUNCH_HOLE + Michael Kerrisk + ERRORS: Add EPERM error case for FALLOC_FL_PUNCH_HOLE + +fork.2 + Michael Kerrisk + NOTES: Describe clone() call equivalent to fork() + +fsync.2 + Christoph Hellwig + Various improvements + - explain the situation with disk caches better + - remove the duplicate fdatasync() explanation in the NOTES + section + - remove an incorrect note about fsync() generally requiring two + writes + - remove an obsolete ext2 example note + - fsync() works on any file descriptor (doesn't need to be + writable); correct the EBADF error code explanation + Michael Kerrisk [Guillem Jover] + Note that some systems require a writable file descriptor + An edited version of Guillem Jover's comments: + [While the file descriptor does not need to be writable on Linux] + that's not a safe portable assumption to make on POSIX in general + as that behavior is not specified and as such is + implementation-specific. Some Unix systems do actually fail on + read-only file descriptors, for example [HP-UX and AIX]. + +mount.2 + Michael Kerrisk [Junjiro Okajima] + Removed erroneous statement about MS_RDONLY and bind mounts + +open.2 + Jessica McKellar + Fix grammar in O_DIRECT description + Some small grammar fixes to the O_DIRECT description. + +pipe.2 + Michael Kerrisk [Salvo Tomaselli] + SYNOPSIS: Add "#include " for O_* constants + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=659750 + +sched_rr_get_interval.2 + Clemens Ladisch + Update notes on modifying quantum + Since Linux 2.6.24, it is no longer possible to + modify the SCHED_RR quantum using setpriority(2). + (Slight edits to Clemens' patch by mtk.) + Michael Kerrisk + Reordered various pieces of text + Michael Kerrisk + Reworded text of ESRCH error + +send.2 + Michael Kerrisk + Add mention of sendmmsg(2) + +sync.2 + Michael Kerrisk [Simone Piccardi] + PROTOTYPE: Fix return type of syncfs() + +vfork.2 + Michael Kerrisk [starlight] + Clarify what is duplicated in the child + Add some words to make it clear to the reader that vfork(), + like fork(), creates duplicates of process attributes + in the child. + Michael Kerrisk + Note clone() flags equivalent to vfork() + Michael Kerrisk [starlight, Mike Frysinger] + Add some notes on reasons why vfork() still exists + Michael Kerrisk [starlight] + Clarify that calling *thread* is suspended during vfork() + Michael Kerrisk + CONFORMING TO: Note that POSIX.1-2001 marked vfork() obsolete + +gets.3 + Michael Kerrisk + Document C11 and glibc 2.16 changes affecting gets() + +pthread_sigmask.3 + Michael Kerrisk [Pat Pannuto] + Fix comment that was inconsistent with code in example program + +sem_wait.3 + Walter Harms + EXAMPLE: Remove extraneous line of output from shell session + +wcsnrtombs.3 +wcsrtombs.3 +wcstombs.3 + Michael Kerrisk + Fix-ups for e9c23bc636426366d659809bc99cd84661e86464 + +core.5 + Michael Kerrisk [Junjiro Okajima] + Document %E specifier for core_pattern + +passwd.5 + Michael Kerrisk [Walter Haidinger] + s/asterisk/asterisk (*)/ to improve clarity + Michael Kerrisk + Correct note on passwd field value when shadowing is enabled + When password shadowing is enabled, the password field + contains an 'x' (not "*'). + +proc.5 + Elie De Brauwer + Fix description of fourth field of /proc/loadavg + SIgned-off-by: Elie De Brauwer + +resolv.conf.5 + Michael Kerrisk [Slaven Rezic] + Describe syntax used for comments + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=656994 + +feature_test_macros.7 + Michael Kerrisk + Document _ISOC11_SOURCE + +inotify.7 + Michael Kerrisk [Yang Yang] + Note that 'cookie' field is set to zero when unused + +man.7 + Michael Kerrisk + Various fixes for description of NAME section + As noted by reporter: + * The code sample given for the NAME section is incomplete because + the actual content sample is not given. + * Additionally, the description assumes that the item described is + a command, which need not be the case. + * The command makewhatis is not present on my system; the + documented tool to create the whatis database is called mandb. + * The description on .SH NAME in man(7) should either copy the + relevant paragraph of lexgrog(1) or refer to it. + + +==================== Changes in man-pages-3.37 ==================== + +Released: 2012-03-06, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes and ideas that have been +incorporated in changes in this release: + +Denys Vlasenko +Mark R. Bannister +Michael Kerrisk +Oleg Nesterov +Tejun Heo + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +getent.1 + Mark R. Bannister + New page to document 'getent' binary provided by glibc + + +Changes to individual pages +--------------------------- + +bdflush.2 + Michael Kerrisk + Note that bdflush() is deprecated, and does nothing + +nfsservctl.2 + Michael Kerrisk + Note that this system call was removed in Linux 3.1 + +ptrace.2 + Denys Vlasenko [Oleg Nesterov, Tejun Heo] + add extended description of various ptrace quirks + Changes include: + + s/parent/tracer/g, s/child/tracee/g - ptrace interface now + is sufficiently cleaned up to not treat tracing process + as parent. + + Deleted several outright false statements: + - pid 1 can be traced + - tracer is not shown as parent in ps output + - PTRACE_ATTACH is not "the same behavior as if tracee had done + a PTRACE_TRACEME": PTRACE_ATTACH delivers a SIGSTOP. + - SIGSTOP _can_ be injected. + - Removed mentions of SunOS and Solaris as irrelevant. + - Added a few more known bugs. + + Added a large block of text in DESCRIPTION which doesn't focus + on mechanical description of each flag and operation, but rather + tries to describe a bigger picture. The targeted audience is + a person which is reasonably knowledgeable in Unix but did not + spend years working with ptrace, and thus may be unaware of its + quirks. This text went through several iterations of review by + Oleg Nesterov and Tejun Heo. + This block of text intentionally uses as little markup as possible, + otherwise future modifications to it will be very hard to make. + Michael Kerrisk + Global clean-up of page + * Wording and formatting fixes to existing text and + Denys Vlasenko's new text. + * Various technical amendments and improvements to + Denys Vlasenko's new text. + * Added FIXME for various problems with the current text. + Michael Kerrisk + Integrated changes after further review from Denys Vlasenko + +syscalls.2 + Michael Kerrisk + Note that nfsservctl(2) was removed in Linux 3.1 + Note that bdflush(2) is deprecated + +capabilities.7 + Michael Kerrisk + Add CAP_WAKE_ALARM + Michael Kerrisk + Add various operations under CAP_SYS_ADMIN + Add perf_event_open(2) to CAP_SYS_ADMIN + Add VM86_REQUEST_IRQ vm86(2) command to CAP_SYS_ADMIN + Update CAP_NET_ADMIN with notes from include/linux/capability.h + Add nfsservctl(2) to CAP_SYS_ADMIN + Michael Kerrisk + Add ioctl(FIBMAP) under CAP_SYS_RAWIO + Michael Kerrisk + Add virtual terminal ioctl()s under CAP_SYS_TTY_CONFIG + Michael Kerrisk + Update CAP_NET_RAW with notes from include/linux/capability.h + Michael Kerrisk + Add F_SETPIPE_SZ case to CAP_SYS_RESOURCE + Add POSIX messages queues queues_max case to CAP_SYS_RESOURCE + Update CAP_SYS_RESOURCE with notes from include/linux/capability.h + Michael Kerrisk + SEE ALSO: Add libcap(3) + +ld.so.8 + Michael Kerrisk + Add --audit command-line option + + +==================== Changes in man-pages-3.38 ==================== + +Released: 2012-03-25, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Akihiro MOTOKI +Artyom Pervukhin +Beňas Petr +Ben Bacarisse +Bjarni Ingi Gislason +David Prévot +Denis Barbier +Denys Vlasenko +Eric Blake +Iain Fraser +Justin T Pryzby +Kirill Brilliantov +Mark R Bannister +Matthew Gregan +Michael Kerrisk +Nix +Peter Schiffer +Sergei Zhirikov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +get_nprocs_conf.3 + Beňas Petr + New page documenting get_nprocs_conf(3) and get_nprocs(3) + Michael Kerrisk + Some additions and improvements + +malloc_get_state.3 + Michael Kerrisk + New page documenting malloc_get_state(3) and malloc_set_state(3) + +mallopt.3 + Michael Kerrisk + New man page for mallopt(3) + +mtrace.3 + Michael Kerrisk + Complete rewrite of page, adding much more detail + +scandirat.3 + Mark R Bannister + New page for scandirat(3) (new in glibc 2.15) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +posix_memalign.3 + Michael Kerrisk + Document aligned_alloc(3) + aligned_alloc() is new in C11. + Michael Kerrisk + Document pvalloc(3) + +qsort.3 + Mark R Bannister + Add documentation of qsort_r(3) + Ben Bacarisse + Improvements to Mark R Bannister's qsort_r() patch + Michael Kerrisk + Add VERSIONS section for qsort_r() + + +New and changed links +--------------------- + +aligned_alloc.3 + Michael Kerrisk + New link to posix_memalign.3 + +get_nprocs.3 + Beňas Petr + Link to new get_nprocs_conf.3 page + +malloc_set_state.3 + Michael Kerrisk + Link to new malloc_get_state.3 page + +pvalloc.3 + Michael Kerrisk + New link to posix_memalign.3 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global formatting fix: balance .nf/.fi pairs + +Various pages + Michael Kerrisk + Global fix: place sections in correct order + +Various pages + Michael Kerrisk [Justin T Pryzby] + Global fix: Remove duplicated words + Remove instances of duplicate words found using Justin's + grep-fu: + + for f in man?/*.[1-9]; do + grep -HE ' ([[:alpha:]]{2,} +)\1' "$f" | + grep -Evw '(proc|hugetlbfs|XXX*|root|long) *\1'; + done | grep -E --colo ' ([[:alpha:]]{2,} +)\1' + +Various pages + Michael Kerrisk + Correct order of SEE ALSO entries + + +Changes to individual pages +--------------------------- + +futimesat.2 + Michael Kerrisk + PROTOTYPE: Correct header file and feature test macro requirements + +keyctl.2 + Bjarni Ingi Gislason + Strip trailing tabs from source line + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=664688 + +ptrace.2 + Denys Vlasenko + Document PTRACE_GETEVENTMSG for PTRACE_EVENT_EXEC + Denys Vlasenko + Various fixes to recent updates of this page + +symlinkat.2 + Michael Kerrisk [Eric Blake] + PROTOTYPE: Correct header file + +syscalls.2 + Michael Kerrisk + Remove unimplemented system calls from main syscall list + The unimplemented system calls are in any case noted lower down + in the page. Also: rearrange the text describing the unimplemented + system calls. + Michael Kerrisk + Note a few system calls that were removed in Linux 2.6 + Michael Kerrisk + Add process_vm_readv(2) and process_vm_writev(2) + +unlinkat.2 + Michael Kerrisk [Eric Blake] + PROTOTYPE: Correct header file + Michael Kerrisk + PROTOTYPE: Add for AT_* constants + +utimensat.2 + Michael Kerrisk + PROTOTYPE: Add for AT_* constants + +copysign.3 + Michael Kerrisk [Tolga Dalman] + DESCRIPTION: Add a couple of examples + +malloc.3 + Michael Kerrisk + NOTES: Add a short discussion of arenas + Michael Kerrisk + Replace discussion of MALLOC_CHECK_ with pointer to mallopt(3) + Michael Kerrisk + SEE ALSO: Add mtrace(3) + SEE ALSO: add malloc_get_state(3) + +posix_memalign.3 + Michael Kerrisk + Rename memalign() argument + Rename "boundary" to "alignment" for consistency + with posix_memalign(). + Michael Kerrisk + Improve discussion of feature test macros and header files for valloc(3) + +rtnetlink.3 + Kirill Brilliantov [Sergei Zhirikov] + Fix example code, rta_len assignment should use RTA_LENGTH() + See also http://bugs.debian.org/655088 + +scandir.3 + Mark R Bannister + SEE ALSO: Add scandirat(3) + +sigqueue.3 + Nix + Remove rt_sigqueueinfo from TH line + rt_sigqueueinfo() now has its own manual page, so should not + be listed in the .TH line of this page. + +tzset.3 + Peter Schiffer + Correct description for Julian 'n' date format + The Julian 'n' date format counts starting from 0, not 1. + Michael Kerrisk + Add some clarifying remarks to discussion of Julian day formats + +packet.7 + Michael Kerrisk [Iain Fraser] + Fix comment on 'sll_hatype' field + +tcp.7 + Michael Kerrisk [Artyom Pervukhin] + Correct RFC for TIME_WAIT assassination hazards + + +==================== Changes in man-pages-3.39 ==================== + +Released: 2012-04-17, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Abhijith Das +Alexander Kruppa +Andreas Jaeger +Armin Rigo +Cyrill Gorcunov +Denys Vlasenko +Eric Blake +Felix +Jak +Jeff Mahoney +Jesus Otero +Jonathan Nieder +Kevin O'Gorman +Mark R Bannister +Michael Kerrisk +Michael Welsh Duggan +Mike Frysinger +Petr Gajdos +Regid Ichira +Reuben Thomas +Ricardo Catalinas Jiménez +Simone Piccardi +Tetsuo Handa + + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +malloc_trim.3 + Michael Kerrisk + New man page for malloc_trim(3) + +malloc_usable_size.3 + Michael Kerrisk + New man page for malloc_usable_size(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +prctl.2 + Cyrill Gorcunov + Document PR_SET_MM (new in Linux 3.3) + Michael Kerrisk + Various edits and improvements to Cyrill's patch + + +Changes to individual pages +--------------------------- + +epoll_create.2 + Michael Kerrisk + Rework discussion of 'size' argument + Michael Kerrisk + Add .SS for description of epoll_create1() + +epoll_wait.2 + Michael Kerrisk [Armin Rigo] + Another thread can add to epoll instance while epoll_wait is blocked + See https://bugzilla.kernel.org/show_bug.cgi?id=43072 + Michael Kerrisk + Clarify that epoll_pwait() blocks calling *thread* + A few wording improvements + +fchmodat.2 + Michael Kerrisk [Mike Frysinger] + Note difference between glibc wrapper and underlying system call + The wrapper function has a 'flags' argument (which currently + serves no purpose), while the underlying system call does not. + +fcntl.2 + Abhijith Das + Explain behaviour of F_GETLEASE during lease break + Michael Kerrisk [Eric Blake] + Change type of arg from "long" to "int" + Various fcntl(2) commands require an integral 'arg'. + The man page said it must be "long" in all such cases. + However, for the cases covered by POSIX, there is an + explicit requirement that these arguments be "int". + Update the man page to reflect. Probably, all of the + other "long" cases (not specified in POSIX) should + be "int", and this patch makes them so. Based on a + note fromEric Blake, relating to F_DUPFD_CLOEXEC. + +gettimeofday.2 + Michael Kerrisk + Reorganize content + The main change is to move the historical information about + the 'tz_dsttime' to NOTES. + Michael Kerrisk [Felix] + Note that compiler issues warnings if 'tv' is NULL + +mmap.2 + Michael Kerrisk [Kevin O'Gorman] + Clarify that this system call should not be invoked directly + See https://bugzilla.kernel.org/show_bug.cgi?id=42892 + Michael Kerrisk + Clarify NOTES discussion of mmap() versus mmap2() + +poll.2 + Michael Kerrisk [Michael Welsh Duggan] + Document negative value in 'fd' field + Michael Kerrisk + Document semantics of passing zero in 'events' field + +ptrace.2 + Denys Vlasenko + Various fixes + For some reason, the PTRACE_TRACEME paragraph talks about some + general aspects of ptraced process behavior. It repeats the + "tracee stops on every signal" information even though that was + already explained just a few paragraphs before. Then it describes + legacy SIGTRAP on execve(). + + This patch deletes the first part, and moves the second part up, + into the general ptrace description. It also adds + "If PTRACE_O_TRACEEXEC option is not in effect" to the description + of the legacy SIGTRAP on execve(). + + The patch also amends the part which says "For requests other + than PTRACE_KILL, the tracee must be stopped." - PTRACE_ATTACH + also doesn't require that. + +sigaction.2 + Michael Kerrisk [Andreas Jaeger, ] + Clarify that the use of SI_SIGIO is for Linux 2.2 only + See also http://sourceware.org/bugzilla/show_bug.cgi?id=6745 + +sigprocmask.2 + Mike Frysinger + ERRORS: add EFAULT + +times.2 + Michael Kerrisk [Simone Piccardi] + ERRORS: Add EFAULT + +div.3 + Michael Kerrisk [Reuben Thomas] + CONFORMING TO: Add C99 + +fread.3 + Regid Ichira + Clarify further that return value is number of items, not bytes + See also http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=665780 + +getaddrinfo.3 + Michael Kerrisk [Jak] + Correct type of ai_addrlen field + +malloc.3 + Michael Kerrisk + SEE ALSO: add malloc_usable_size(3) + SEE ALSO: Add malloc_trim(3) + +mallopt.3 + Michael Kerrisk + Fix text describing M_PERTURB and free() + SEE ALSO: Add malloc_trim(3) + +memchr.3 + Michael Kerrisk [Reuben Thomas] + Remove mention of terminating null in description of rawmemchr() + +perror.3 + Michael Kerrisk [Jesus Otero] + Note that use of 'sys_errlist' is deprecated + +rcmd.3 + Michael Kerrisk + glibc eventually added a declaration of iruserok() in version 2.12 + +sysconf.3 + Michael Kerrisk [Ricardo Catalinas Jiménez] + Add mention of _SC_SYMLOOP_MAX + +nologin.5 + Michael Kerrisk [Tetsuo Handa] + nologin must not only exist, but *be readable* to be effective + +nsswitch.conf.5 + Mark R Bannister + Significant rewrites and improvements + This patch applies to nsswitch.conf.5 in man-pages-3.36. + + My changes almost completely rewrite large sections of the + man page. They are needed to add clarity, correct grammar, + reduce confusion, and bring up-to-date with the latest glibc. + I have checked the man page against the nss source code in + glibc 2.14.90. + + Historical notes are demoted to the footer. + + The rewrite makes the man page much clearer to + understand, more authoratitive, and easier to read. + Michael Kerrisk + Light edits to Mark Bannister's changes + +capabilities.7 + Michael Kerrisk + Add prctl(PR_SET_MM) to CAP_SYS_RESOURCE + +epoll.7 + Michael Kerrisk + Some minor clarifications at start of DESCRIPTION + +netlink.7 + Jeff Mahoney [Petr Gajdos] + Note cases where nonprivileged users can use netlink multicast groups + See also https://bugzilla.novell.com/show_bug.cgi?id=754611 + +unix.7 + Michael Kerrisk [Tetsuo Handa] + Add a detail on autobind feature + +ld.so.8 + Jonathan Nieder [Reuben Thomas] + Document effect of hwcaps on search path + Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04). + + Addresses http://bugs.debian.org/622385 + + +==================== Changes in man-pages-3.40 ==================== + +Released: 2012-04-27, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alexey Toptygin +Bernhard Walle +Brian F. G. Bidulock +Brian M. Carlson +Christopher Yeoh +Daniel J Blueman +Eric Blake +Eugen Dedu +James Hunt +John Sullivan +Jon Grant +lepton +Marcel Holtmann +Michael Kerrisk +Mike Frysinger +Petr Baudis +Simon Paillard +Stefan Puiu +Ulrich Drepper +Vadim Mikhailov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +process_vm_readv.2 + Mike Frysinger, Christopher Yeoh, Michael Kerrisk + New page for process_vm_readv(2) and process_vm_writev(2) + +mcheck.3 + Michael Kerrisk + New man page for mcheck(3) and related functions + Also describes mcheck_check_all(3), mcheck_pedantic(3), + and mprobe(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +rcmd.3 + Michael Kerrisk + Document "_af" variants of these functions + Document rcmd_af(), rresvport_af(), iruserok_af(), ruserok_af(). + Also some restructuring and other clarifications. + +rexec.3 + Michael Kerrisk + Document rexec_af() + + +New and changed links +--------------------- + +iruserok_af.3 +rcmd_af.3 +rresvport_af.3 +ruserok_af.3 + Michael Kerrisk + New links to rcmd.3 + +rexec_af.3 + Michael Kerrisk + New link to rexec.3 + + +Changes to individual pages +--------------------------- + +clock_getres.2 + Michael Kerrisk + Clarify difference between CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW + Note interactions of these two clocks with discontinuous + adjustments to the system time and NTP/adjtime(2). + +fallocate.2 + Michael Kerrisk [John Sullivan] + Fix description of ENOSYS and EOPNOTSUP errors + As reported in https://bugzilla.redhat.com/show_bug.cgi?id=680214 + +fchmodat.2 + Michael Kerrisk [Mike Frysinger] + Improve discussion of difference between wrapper and underlying syscall + +gettimeofday.2 + Michael Kerrisk + gettimeofday() is affected by discontinuous jumps in the system time + Advise reader to use clock_gettime(2), if they need a + monotonically increasing time source. + Michael Kerrisk + SEE ALSO: Add clock_gettime(2) + +prctl.2 + Michael Kerrisk + Add PR_TASK_PERF_EVENTS_DISABLE and PR_TASK_PERF_EVENTS_ENABLE + Add some basic documentation of these operations, with a pointer to + tools/perf/design.txt for more information. + Michael Kerrisk [Marcel Holtmann] + Amend details of PR_SET_PDEATHSIG + +ptrace.2 + Michael Kerrisk [Mike Frysinger] + Note SPARC deviation with respect to get/set regs + SPARC reverses the use of 'addr' and 'data' for + PTRACE_GETREGS, PTRACE_GETFPREGS, PTRACE_SETREGS, + and PTRACE_SETFPREGS. + +send.2 + Stefan Puiu + Document EACCES error case for UDP + +sigaction.2 + Michael Kerrisk + Remove mention of raise(3) for SI_USER + For a long time now, glibc's raise(3) didn't yield SI_USER + for the signal receiver, so remove mention of raise(3) + here. The user can deduce the details, if needed, by looking + at the recently updated raise(3) page. + +aio_cancel.3 + Michael Kerrisk [Jon Grant] + Rewrite RETURN VALUE section to be clearer + +aio_init.3 + Michael Kerrisk [Jon Grant] + Remove extraneous "POSIX" from NAME section + +btree.3 +dbopen.3 +hash.3 +mpool.3 +recno.3 + Michael Kerrisk [Brian M. Carlson] + Note that glibc no longer provides these interfaces + glibc stopped providing these interfaces with v2.2. + Nowadays, the user that finds these pages probably wants + the libdb API, so note this in the page. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=337581 + +fopen.3 + Michael Kerrisk + BUGS: Note limitation on number of flag characters parsed in 'mode' + Michael Kerrisk + Note that 'c' and 'e' flags are ignored for fdopen() + Determined from reading libio/iofdopen.c. + Michael Kerrisk + Document ",ccs=string" feature of 'mode' for fopen()/freopen() + +getgrnam.3 + Michael Kerrisk [Ulrich Drepper] + Fix discussion of _SC_GETGR_R_SIZE_MAX + The value is not meant to be a maximum (as was specified in + SUSv3) but an initial guess at the required size + (as specified in SUSv4). + +getpwnam.3 + Michael Kerrisk [Ulrich Drepper] + Fix discussion of _SC_GETPW_R_SIZE_MAX + The value is not meant to be a maximum (as was specified in + SUSv3) but an initial guess at the required size + (as specified in SUSv4). + +malloc.3 +mallopt.3 +mtrace.3 + Michael Kerrisk + SEE ALSO: add mcheck(3) + +memchr.3 + Michael Kerrisk + Clarify description, omitting mention of "strings" and "characters" + The existing text slipped into talking about characters and + strings, which could mislead readers into thing that, for + example, searches for the byte '\0' are treated specially. + Therefore, rewrite in terms of "bytes" and "memory areas". + + At the same time, make a few source file clean-ups. + +mkstemp.3 + Michael Kerrisk + Add "mkstemps" and "mkostemps" to NAME line + +posix_openpt.3 + Michael Kerrisk [Vadim Mikhailov] + Add some details on use of the slave pathname + An explicit pointer to ptsname(3) is useful, as is a note + of the fact that the slave device pathname exists only as + long as the master device is held open. + +raise.3 + Michael Kerrisk + Add some notes on underlying system call that is used + +rcmd.3 + Michael Kerrisk + Add some details of the rresvport() 'port' argument + +resolver.3 + Petr Baudis + Note that many options are documented in resolv.conf(5) + +scandir.3 + Michael Kerrisk [Daniel J Blueman] + Improve EXAMPLE source code: s/0/NULL/ in scandir() call + +strchr.3 + James Hunt + Explain behavior when searching for '\0' + +strerror.3 + Eric Blake [Stefan Puiu] + Improve strerror_r() description + POSIX requires that perror() not modify the static storage + returned by strerror(). POSIX 2008 and C99 both require that + strerror() never return NULL (a strerror() that always + returns "" for all inputs is valid for C99, but not for POSIX). + + http://sourceware.org/bugzilla/show_bug.cgi?id=12204 + documents glibc's change to come into compliance with POSIX + regarding strerror_r() return value. The GNU strerror_r() use + of 'buf' was confusing - I ended up writing a test program that + proves that 'buf' is unused for valid 'errnum', but contains + truncated "unknown message" for out-of-range 'errnum'. + + See also http://austingroupbugs.net/view.php?id=382 + Bernhard Walle + Correct description of error return for XSI strerror_r() + Michael Kerrisk [Eric Blake] + Note how to use 'errno' to detect errors when calling strerror() + Michael Kerrisk [Jon Grant] + Add an example of the kind of string returned by strerror() + +resolv.conf.5 + Petr Baudis + Document "single-request" option + +inotify.7 + Michael Kerrisk + Note buffer size that guarantees being able to read at least one event + James Hunt + Correct description of size of inotify_event structure + +iso_8859-1.7 + Eugen Dedu + Add "-" for SOFT HYPHEN + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=156154 + +netdevice.7 + Brian F. G. Bidulock + Document some SIOC configuration ioctls + This patch adds common but missing SIOC configuration ioctls to + the netdevice.7 manual pages that are not documented anywhere + else. SIOCSIFPFLAGS and SIOCGIFPFLAGS are linux-specific. Flag + values come from Linux 2.6.25 kernel headers for sockios. The + others are standard BSD ioctls that have always been implemented + by Linux and were verified from inspecting netdevice.c kernel + code. + +socket.7 + Michael Kerrisk [Alexey Toptygin] + Correct description of SO_BROADCAST + +tcp.7 + lepton + Correct description for TCP_MAXSEG on modern kernel + + +==================== Changes in man-pages-3.41 ==================== + +Released: 2012-05-11, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Akihiro MOTOKI +Andries E. Brouwer +Angelo Borsotti +Bjarni Ingi Gislason +Brian M. Carlson +Casper Dik +David Prévot +D. Barbier +Eric Blake +Hugh Dickins +Ivana Varekova +Jakub Jelinek +Jan Kara +Jason Baron +Jean-Michel Vourgère +Jeff Moyer +Josh Triplett +Kasper Dupont +KOSAKI Motohiro +Lauri Kasanen +Mel Gorman +Michael Kerrisk +Mike Frysinger +Nick Piggin +Paul Pluzhnikov +Petr Baudis +Ralph Corderoy +Rich Felker +Simone Piccardi +Simon Paillard +Stefan Puiu +Stephen Hemminger +Vincent Lefevre +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +get_robust_list.2 + Ivana Varekova [Michael Kerrisk] + New page documenting get_robust_list(2) and set_robust_list(2) + +mallinfo.3 + Michael Kerrisk [KOSAKI Motohiro, Paul Pluzhnikov] + New page for mallinfo(3) + +malloc_info.3 + Michael Kerrisk [Jakub Jelinek] + New page for malloc_info(3) + +malloc_stats.3 + Michael Kerrisk [KOSAKI Motohiro] + New man page for malloc_stats(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +madvise.2 + Jason Baron + Document MADV_DONTDUMP and MADV_DODUMP + + +New and changed links +--------------------- + +set_robust_list.2 + Michael Kerrisk + New link to new get_robust_list.2 page + +LIST_ENTRY.3 +LIST_HEAD.3 +LIST_INIT.3 +LIST_INSERT_AFTER.3 +LIST_INSERT_HEAD.3 +LIST_REMOVE.3 +TAILQ_ENTRY.3 +TAILQ_HEAD.3 +TAILQ_INIT.3 +TAILQ_INSERT_AFTER.3 +TAILQ_INSERT_HEAD.3 +TAILQ_INSERT_TAIL.3 +TAILQ_REMOVE.3 +CIRCLEQ_ENTRY.3 +CIRCLEQ_HEAD.3 +CIRCLEQ_INIT.3 +CIRCLEQ_INSERT_AFTER.3 +CIRCLEQ_INSERT_BEFORE.3 +CIRCLEQ_INSERT_HEAD.3 +CIRCLEQ_INSERT_TAIL.3 +CIRCLEQ_REMOVE.3 + Michael Kerrisk + New link to queue.3 + The queue(3) page documents these macros, so it makes sense to + have links for the names. + +DES_FAILED.3 + Michael Kerrisk + New link to des_crypt.3 + The des_crypt(3) page documents this macro, so it makes sense + to have a link for the name. + +qsort_r.3 + Michael Kerrisk + New link to qsort.3 + Overlooked to add this link in 3.38, when documentation of + qsort_r() was added to the qsort.3 page. + + +Global changes +-------------- + +faccessat.2 +fchmodat.2 +fchownat.2 +fstatat.2 +futimesat.2 +inotify_init.2 +linkat.2 +mkdirat.2 +mknodat.2 +openat.2 +readlinkat.2 +renameat.2 +setns.2 +splice.2 +symlinkat.2 +sync.2 +tee.2 +unlinkat.2 +vmsplice.2 + Michael Kerrisk [Lauri Kasanen] + Global fix: note glibc version that added library support + +confstr.3 +strcasecmp.3 +strcat.3 +strcmp.3 +strcpy.3 +strdup.3 +strftime.3 +strlen.3 +strnlen.3 +strpbrk.3 +strspn.3 +strtok.3 +strxfrm.3 + Michael Kerrisk [Andries E. Brouwer] + Clarify that these functions operate on bytes, not (wide) characters + Change 'character(s)' to 'byte(s)' to make clear that these + functions operate on bytes, not wide / UTF8 characters. + (POSIX uses 'byte(s)' similarly, to make this point.) + +icmp.7 +ipv6.7 +packet.7 +raw.7 +rtnetlink.7 +unix.7 +x25.7 + Michael Kerrisk + Remove names of constants from NAME line + Some of the sockets/network protocol pages included names of + the corresponding address family constants in the NAME line, + but this wasn't done consistently across all pages, and probably + it adds little value in those pages that did do this. So, remove + these constants from those pages that have them in the NAME + section. + + +Changes to individual pages +--------------------------- + +clock_getres.2 + Michael Kerrisk [Josh Triplett] + Expand description of CLOCK_REALTIME + Make it clear that this clock may be discontinuous, and is + affected my incremental NTP and clock-adjtime(2) adjustments. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=540872 + +epoll_wait.2 + Michael Kerrisk + Clarify that 'timeout' is a *minimum* interval + Make it clear that 'timeout' is a minimum interval; the actual + interval will be rounded up to the system clock granularity, + and may overrun because of kernel scheduling delays. + +execve.2 + Michael Kerrisk + Rewording to deemphasize libc5 details + +fork.2 + Mike Frysinger + ERRORS: add ENOSYS + Can occur on, for example, non-MMU hardware. + +getcpu.2 + Mike Frysinger + Add RETURN VALUE and ERRORS sections + Michael Kerrisk + Refer reader to NOTES for more info about 'tcache' + Michael Kerrisk + DESCRIPTION: reword a sentence to be clearer + +io_cancel.2 +io_destroy.2 +io_getevents.2 +io_setup.2 +io_submit.2 + Michael Kerrisk + Rewrite to focus on system call API + Rewrite to focus on the system call interface, adding + some notes on the libaio wrapper differences. + See the following mail: + 2012-05-07 "aio manuals", linux-man@vger + http://thread.gmane.org/gmane.linux.man/1935/focus=2910 + + Other minor rewrites. + +mount.2 + Michael Kerrisk + Comment out an old Linux libc detail + +open.2 + Nick Piggin [KOSAKI Motohiro, Jan Kara, Hugh Dickins] + Describe race of direct I/O and fork() + Rework 04cd7f64, which didn't capture the details correctly. + See the April/May 2012 linux-man@ mail thread "[PATCH] + Describe race of direct read and fork for unaligned buffers" + http://thread.gmane.org/gmane.linux.kernel.mm/77571 + +poll.2 + Michael Kerrisk + Clarify that 'timeout' is a *minimum* interval + Make it clear that 'timeout' is a minimum interval; the actual + interval will be rounded up to the system clock granularity, + and may overrun because of kernel scheduling delays. + Michael Kerrisk + Clarify discussion of wrapper function emulation + Clarify that glibc (as well as old libc) provides emulation + using select(2) on older kernels that don't have a poll() + system call. + Michael Kerrisk + Make the meaning of a zero timeout explicit + Clarify that timeout==0 causes an immediate return, even if + no file descriptors are ready. + +pread.2 + Michael Kerrisk [Kasper Dupont] + BUGS: Note O_APPEND + pwrite() does the wrong thing + See https://bugzilla.kernel.org/show_bug.cgi?id=43178 + +recvmmsg.2 + Michael Kerrisk + Clarify that 'timeout' is a *minimum* interval + Make it clear that 'timeout' interval will be rounded up to the + system clock granularity, and may overrun because of kernel + scheduling delays. + +select.2 + Michael Kerrisk + Clarify that 'timeout' is a *minimum* interval + Make it clear that 'timeout' is a minimum interval; the actual + interval will be rounded up to the system clock granularity, + and may overrun because of kernel scheduling delays. + Michael Kerrisk + Expand description of the self-pipe trick + Michael Kerrisk + Add further details on pselect6() system call that underlies pselect() + +semop.2 + Michael Kerrisk + Clarify that 'timeout' of semtimedop() is a *minimum* interval + Make it clear that 'timeout' interval will be rounded up to the + system clock granularity, and may overrun because of kernel + scheduling delays. + +signal.2 + Michael Kerrisk + Note that 'sig_t' requires _BSD_SOURCE + Also remove some old Linux libc details + +sigwaitinfo.2 + Michael Kerrisk + Clarify that 'timeout' of sigtimedwait() is a *minimum* interval + Make it clear that 'timeout' is a minimum interval; the actual + interval will be rounded up to the system clock granularity, + and may overrun because of kernel scheduling delays. + +stat.2 + Bjarni Ingi Gislason + Formatting fixes + From "groff -ww" (or "man --warnings=w ..."): + + warning: around line 442: table wider than line width + + GNU man uses line length of 78. + + Use text blocks. Two spaces between sentences or better: start + each sentence in a new line. + +syscalls.2 + Bjarni Ingi Gislason + Formatting fixes + From "groff -ww ..." (or "man --warnings=w ..."): + + warning: around line 157: table wider than line width + + Have to use text blocks. Move some text to its correct column. + Split text to two columns to avoid hyphenation. + +sysinfo.2 + Michael Kerrisk + Remove reference to obsolete libc5 + +syslog.2 + Michael Kerrisk + Remove some details about obsolete Linux libc + +aio_cancel.3 +aio_error.3 +aio_fsync.3 +aio_read.3 +aio_return.3 +aio_suspend.3 +aio_write.3 + Michael Kerrisk + ERRORS: Add/update ENOSYS error + +aio_cancel.3 + Michael Kerrisk + Clarify what happens when a request isn't successfully canceled + Michael Kerrisk + Add pointers to aio(7) and sigevent(7) + +dbopen.3 + Michael Kerrisk + SYNOPSIS: Add header file + Upstreamed from Debian, and consistent with FreeBSD + dbopen(3) man page. + +fmemopen.3 + Michael Kerrisk + Note details of POSIX.1-2008 specification of 'b' in 'mode' + Michael Kerrisk [Rich Felker] + BUGS: fmemopen() doesn't correctly set file position in some cases + If 'mode' is append, but 'size' does not cover a null byte + in 'buf', then fmemopen() incorrectly sets the initial file + position to -1, rather than the next byte after the end of + the buffer. + + See http://sourceware.org/bugzilla/show_bug.cgi?id=13151 + Michael Kerrisk + BUGS: fmemopen() incorrectly handles size==0 case + If size is zero, fmemopen() fails, This is surprising behavior, + and not specified in POSIX.1-2008. + + See http://sourceware.org/bugzilla/show_bug.cgi?id=11216 + + Reported-by; Alex Shinn + Michael Kerrisk + BUGS: Note silent ABI change for fmemopen() in glibc 2.9 + Michael Kerrisk [Rich Felker] + BUGS: Append mode does not force writes to append + Append mode correctly sets the initial offset but does + not force subsequent writes to append at end of stream. + + See http://sourceware.org/bugzilla/show_bug.cgi?id=13152 + Michael Kerrisk [Eric Blake] + BUGS: Note inconsistent treatment of 'b' in 'mode' + fopen() permits, for example, both "w+b" and "wb+", + but only the latter is meaningful to fmemopen(). + + See http://sourceware.org/bugzilla/show_bug.cgi?id=12836 + +fopencookie.3 + Michael Kerrisk [Petr Baudis] + Correct description of return for user-supplied 'write' function + See http://sourceware.org/bugzilla/show_bug.cgi?id=2074 + +getaddrinfo.3 + Jean-Michel Vourgère + Note that AI_ADDRCONFIG is not affected by loopback addresses + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=660479 + +iconv.3 + Michael Kerrisk + Upstream useful NOTE from Debian + Warn the reader that the pointer arguments can't be + interpreted as C style strings. Also, note possible + alignment requirements for the referenced bytes sequences, + Michael Kerrisk + Write a better paragraph introducing iconv() and its arguments + +isgreater.3 + Michael Kerrisk [Vincent Lefevre] + Clarify that the arguments to these macros must be real-floating + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=609033 + +lio_listio.3 + Michael Kerrisk + Clarify that async notification occurs when *all* I/Os complete + +makedev.3 + Michael Kerrisk + SYNOPSIS: Correct return types of major() and minor() + See https://bugzilla.redhat.com/show_bug.cgi?id=754188 + + Reported-by; Zdenek Kabelac + +malloc.3 + Michael Kerrisk + SEE ALSO: Add malloc_info(3) + +malloc_get_state.3 + Michael Kerrisk + Fix wordos in function names in NAME line + +mallopt.3 + Michael Kerrisk + Fix example program + The example code was a version that was not consistent with + the shell output shown on the page. + + Reported-bY: Simon Paillard + Michael Kerrisk + Restore accidentally omitted line in shell session + Michael Kerrisk + SEE ALSO: Add malloc_stats(3) + +mmap64.3 + Michael Kerrisk + Change target of link to mmap.2 (was mmap2.2) + Upstreamed from Red Hat / Fedora + +realpath.3 + Michael Kerrisk [Casper Dik] + Remove note about Solaris possibly returning a relative path + +syslog.3 + Michael Kerrisk [Ralph Corderoy] + Document behavior when 'ident' argument to openlog() is NULL + See https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/382096 + Michael Kerrisk + Update CONFORMING TO for POSIX.1-2008 + POSIX.1-2008 doesn't change any details, but make + that more explicit. + +undocumented.3 + Michael Kerrisk + Remove some functions that have been documented + +sd.4 + Michael Kerrisk + Remove reference to nonexistent scsi(4) page + Upstreamed from RedHat / Fedora + +sk98lin.4 + Michael Kerrisk [Stephen Hemminger] + Note that this driver was removed in 2.6.28 + See https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/528020 + +passwd.5 + Michael Kerrisk + Upstream pieces from Red Hat/Fedora + Note mention of empty password field. + Add description of "*NP*" in password field. + Michael Kerrisk + Various minor fixes and improvements + +proc.5 + Michael Kerrisk + Note that CAP_SYS_ADMIN processes can override file-max + Upstreamed from red Hat / Fedora + Michael Kerrisk + Document /proc/[pid]/cgroup + Upstreamed from Red Hat / Fedora + +resolv.conf.5 + Michael Kerrisk + Take a Debian improvement into upstream + +tzfile.5 + Michael Kerrisk + Mention timezone directories in DESCRIPTION + Note that timezone files are usually in /usr/lib/zoneinfo + or /usr/share/zoneinfo. + Michael Kerrisk + Drop SYNOPSIS + The SYNOPSIS doesn't correspond to a user-visible file. + Michael Kerrisk + SEE ALSO: Add pointer to glibc source file timezone/tzfile.h + Michael Kerrisk + SEE ALSO: add tzset(3) and tzselect(8) + +ascii.7 + Bjarni Ingi Gislason + Indent for "troff" makes table too wide + Fix following from "groff -t -ww ...": + + warning: around line 53: table wider than line width + + Extra indent for "troff" makes the table look misplaced + (default "ps" output). + +cp1251.7 + Bjarni Ingi Gislason + table too wide + From "nroff -ww -t ...": + + warning: around line 44: table wider than line width + + Columns are made narrower (column gutter decreased). + +ipv6.7 + Stefan Puiu + Add ENODEV error for bind() to link-local IPv6 address + +signal.7 + Michael Kerrisk [Simone Piccardi] + Clarify that SIGLOST is unused + Michael Kerrisk + Comment out crufty BUGS text on SIGLOST + It must be a very long time since the statement there + about SIGLOST was true. (The text seems to date back to + 1996.) + Michael Kerrisk + Update architectures for tables of signal numbers + +utf-8.7 + Brian M. Carlson + Two clarifications + This patch clarifies that 0xc0 and 0xc1 are not valid in any UTF-8 + encoding[0], and it also references RFC 3629 instead of RFC 2279. + + [0] In order to have 0xc0, you'd have to have a two-byte encoding + with all the data bits zero in the first byte (and thus only six + bits of data), which would be an ASCII character encoded in the + non-shortest form. Similarly with 0xc1. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=538641 + +ldconfig.8 +nscd.8 + Michael Kerrisk + Remove path prefix from NAME line + Command names shown in NAME are normally just the basename, + not the full pathname of the command. + + +==================== Changes in man-pages-3.42 ==================== + +Released: 2012-08-14, Konolfingen + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Aaron Peschel +Adrian Dabrowski +Akihiro MOTOKI +Alan Curry +Bjarni Ingi Gislason +Christoph Lameter +Colin McCabe +Daniel Zingaro +David Prévot +Denys Vlasenko +Henry Hu +Herbert Xu +Jan Engelhardt +Jim Hill +JoonSoo Kim +Kalle Olavi Niemitalo +Martin H +Michael Kerrisk +Michael S. Tsirkin +Rasmus Villemoes +Sami Kerola +Sam Varshavchik +Shawn Landden +Simon Paillard +Tolga Dalman +Ulrich Drepper +Марк Коренберг + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages + Sami Kerola + Global fix: use UR macro where applicable + The syntax .UR http://example.com paired with .UE will create + links which one can interact, if the pager allows that. One + way to see the effect is ask the man(1) command to use browser + display, e.g.: + + man -H man7/uri.7 + + ("\:" is optional groff syntax to permit hyphenless line breaks.) + + +Changes to individual pages +--------------------------- + +ldd.1 + Michael Kerrisk + Add security note on untrusted executables + See also http://www.catonmat.net/blog/ldd-arbitrary-code-execution/ + and + http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html + +clone.2 + Michael Kerrisk + Rewrite discussion of sys_clone + +futex.2 + Марк Коренберг + Consolidate error descriptions to ERRORS + Michael Kerrisk + Various wording fix-ups + Michael Kerrisk + Fix description of EINVAL error + The current text seems incorrect. Replace with a more general + description. + +getdents.2 +select_tut.2 +atof.3 +atoi.3 +pthread_create.3 +pthread_sigmask.3 +rtime.3 +setbuf.3 +tsearch.3 +netlink.7 + Michael Kerrisk [Jan Engelhardt] + Remove unneeded casts + +get_robust_list.2 +get_thread_area.2 +getcpu.2 +getdents.2 +gettid.2 +io_cancel.2 +io_destroy.2 +io_getevents.2 +io_setup.2 +io_submit.2 +ioprio_set.2 +kexec_load.2 +llseek.2 +modify_ldt.2 +mq_getsetattr.2 +pivot_root.2 +readdir.2 +rt_sigqueueinfo.2 +set_thread_area.2 +sgetmask.2 +spu_create.2 +spu_run.2 +subpage_prot.2 +sysctl.2 +tkill.2 + Michael Kerrisk + Add note to SYNOPSIS that there is no glibc wrapper for system call + Reduce the chance that the reader may be misled into thinking + that there is a wrapper function for this system call by noting + explicitly in the SYNOPSIS that there is no glibc wrapper and + pointing the reader to NOTES for further details. + +ioprio_set.2 + Colin McCabe + Clarify the multithreaded behavior of ioprio_set(2) + Michael Kerrisk [Марк Коренберг, Kalle Olavi Niemitalo] + Document who==0 for IOPRIO_WHO_PROCESS and IOPRIO_WHO_PGRP + For IOPRIO_WHO_PROCESS, who==0 means operate on the caller. + For IOPRIO_WHO_PGRP, who==0 means operate on the caller's + process group. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443 + +migrate_pages.2 + Michael Kerrisk [Christoph Lameter, JoonSoo Kim] + Fix description of return value + +mount.2 + Michael Kerrisk + For MS_REMOUNT, source is ignored + +mprotect.2 + Michael Kerrisk [Rasmus Villemoes] + 'addr' argument is not const + As reported by Rasmus: + + Both my system's man-pages (3.22) and the latest online + (3.41) show: + + int mprotect(const void *addr, size_t len, int prot); + + as the prototype for mprotect(2). However, POSIX [1] and the + actual sys/mman.h (on all the systems I checked) do not have + the const qualifier on the first argument. + +msgctl.2 +semctl.2 +shmctl.2 +svipc.7 + Michael Kerrisk + Don't mention that ipc_perm is defined in + There's no need to mention that the 'ipc_perm' structure + is defined in . That's an implementation detail, + and furthermore is itself included by the other + System V IPC header files. The current text might lead the + reader to conclude that they must include , which + is not the case (it is required neither on Linux, nor by the + standards). + +msgctl.2 +msgget.2 +msgop.2 +semctl.2 +semget.2 +semop.2 +shmctl.2 +shmget.2 + Michael Kerrisk + NOTES: and aren't strictly needed + Add text to NOTES to say that the and + header files aren't required by Linux or the standards, but may + be needed for portability to old systems. + +ptrace.2 + Denys Vlasenko + Explain WNOHANG behavior and EINTR bug + I didn't like the "SIGKILL operates similarly, with exceptions" + phrase (if it's different, then it's not "similar", right?), + and now I got around to changing it. Now it says simply: + "SIGKILL does not generate signal-delivery-stop and therefore + the tracer can't suppress it." + + Replaced "why WNOHANG is not reliable" example with a more + realistic one (the one which actually inspired to add this + information to man page in the first place): we got + ESRCH - process is gone! - but waitpid(WNOHANG) can still + confusingly return 0 "no processes to wait for". + + Replaced "This means that unneeded trailing arguments may + be omitted" part with a much better recommendation + to never do that and to supply zero arguments instead. + (The part about "undocumentedness" of gcc behavior was bogus, + btw - deleted). + + Expanded BUGS section with the explanation and an example + of visible strace behavior on the buggy syscalls which + exit with EINTR on ptrace attach. I hope this will lead + to people submitting better bug reports to lkml about + such syscalls. + +seteuid.2 + Michael Kerrisk + Note glibc version where setegid() implementation changed + In glibc 2.2/2.3, setegid() switched from setregid() to setresgid(). + +set_tid_address.2 + Michael Kerrisk + Rename 'ctid' argument for consistency with clone(2) page + Michael Kerrisk + Some rewordings and minor clarifications + +sigwaitinfo.2 + Michael Kerrisk [Daniel Zingaro] + Some wording clarifications + Mainly rewording things like "is delivered" to "becomes pending", + which is more accurate terminology. + +syscall.2 + Michael Kerrisk + Add some more details to the description of syscall(2) + And add another example of using syscall() to the program example. + +syscalls.2 + Michael Kerrisk + Add kcmp(2) + Michael Kerrisk + Move discussion of set_zone_reclaim(2) out of main table + This system call was never visible to user space, so it makes + sense to move it out of the main table of system calls into + the notes below the table. + +getifaddrs.3 + Michael Kerrisk [Adrian Dabrowski] + Note that ifa_addr and ifa_netmask can be NULL + +readdir.3 + Michael Kerrisk [Jan Engelhardt] + Handle -1 error from pathconf() in example code snippet + Improve the example demonstrating allocation of a buffer + for readdir_r() to handle -1 error return from pathconf(). + Otherwise, naive readers may think that pathconf() return + value can be used without checking. + +realpath.3 + Shawn Landden + Use past tense with ancient history (libc4, libc5) + +regex.3 + Michael Kerrisk + Correct SEE ALSO reference to glibc manual "regex" section + +rtime.3 + Michael Kerrisk [Jan Engelhardt] + Fix broken pointer cast in example code + +sem_close.3 +sem_destroy.3 +sem_getvalue.3 +sem_init.3 +sem_open.3 +sem_post.3 +sem_unlink.3 +sem_wait.3 +sem_overview.7 + Michael Kerrisk + Note that "cc -pthread" is required; "-lrt" no longer works + See https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/874418 + +sigwait.3 + Michael Kerrisk + Reword "is delivered" to "becomes pending" + +strcat.3 + Michael Kerrisk + Add some text to emphasize the dangers of buffer overruns + Michael Kerrisk + NOTES: Add discussion of strlcat() + +strcpy.3 + Michael Kerrisk + Note that info is lost when strncpy() doesn't null terminate + Michael Kerrisk + Add some text to emphasize possibility of buffer runs with strcpy() + Michael Kerrisk + NOTES: Add a discussion of strlcpy() + Inspired by https://lwn.net/Articles/506530/ + Michael Kerrisk + Fix description of the null-byte padding performed by strncpy() + +tsearch.3 + Michael Kerrisk + NOTES: remove redundant discussion of unorthodox use of term "postorder" + This point is already covered at greater length in the main + text of the page (See the piece "More commonly, ..."). + Michael Kerrisk + Clarify use for first argument to the twalk() 'action' function + There's a number of details in POSIX that are omitted in + the current version of this page. + Michael Kerrisk + Some wording fixes + +core.5 + Michael Kerrisk + Note effect of madvise(2) MADV_DONTDUMP flag + +capabilities.7 + Michael Kerrisk + Document CAP_BLOCK_SUSPEND + +glob.7 + Bjarni Ingi Gislason + Change 8 bit characters to 7 bit representation + Fixes rendering errors for accented 'a' characters. + Michael Kerrisk [Aaron Peschel] + Update bash(1) command used to obtain classical globbing behavior + The man page formerly noted the bash(1) v1 command to do this. + +iso_8859-1.7 + Bjarni Ingi Gislason + Explanation of SOFT HYPHEN and the code for it + :89: warning: can't find special character `shc' + + This is the only "iso_8859-*.7" file that has this (now) + undefined character. The code in column four in "iso_8859-1.7" is + "0x2D" ("HYPHEN, MINUS SIGN" or "HYPHEN-MINUS") instead of "0xAD". + See Debian bug 156154 (or package "manpages"). + + There should be an explanation for this graphic character and the + code should be 0xAD in iso_8859-1.7 (as in all others), even + though "[gn]roff" does not display a "HYPHEN" in that position of + the table. + + The line with "SOFT HYPHEN" gets a footnote and a short + explanation. + +mdoc.7 + Bjarni Ingi Gislason + Fixing a warning and a table + Fis warning from "groff -ww ..." (or "man --warnings=w ..."): + + :294: warning: + tab character in unquoted macro argument + + In one table the distance between columns is too small in the + "ps" output. (Bug in the groff "doc.tmac" macro?) + +mdoc.samples.7 + Bjarni Ingi Gislason + Fix warnings from [ng]roff, corrections + From "man -ww ..." (groff -ww ...): + + :541: warning: + tab character in unquoted macro argument + [+3 similar warnings] + :813: warning: macro `Pu' not defined + Usage: .Rv -std in sections 2 and 3 only (#1669) + mdoc warning: A .Bl directive has no matching .El (#1821) + + String "Pu" defined as a row of punctuation characters. + ".Bl" and ".El" fixed. + Some arguments, that start with a period or are the name of a + macro, protected with "\&". + Variable name for macro ".Rv" corrected. + +netdevice.7 + Bjarni Ingi Gislason + Line in table too long + Fix warning from "man ..." ("nroff -ww ..."): + + nroff: netdevice.7: warning: around line 98: + table wider than line width + + Fix: No right adjustment in text blocks in tables. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=673873 + +netlink.7 + Bjarni Ingi Gislason + Line in table is too long + Fix warning from "man ..." ("nroff -ww ..."): + + nroff: netlink.7: warning: around line 195: + table wider than line width + + Horizontal line incorporated into table. + No right adjustment of text blocks in tables. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=673875 + Simon Paillard [Herbert Xu] + Change description of "*_pid" fields to "Port ID" + As reported by Herbert Xu, these should not be considered as PIDs. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=383296 + +rtnetlink.7 + Bjarni Ingi Gislason + Line in table too long + Fix warning from "man ..." ("nroff -ww ..."): + + nroff: rtnetlink.7: warning: around line 415: + table wider than line width + + Column gutter reduced to fit line length. + Right adjustment in text blocks removed in tables. + Some header made centered in tables. + One table put on same page. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=674051 + +socket.7 + Martin H + Document SO_MARK socket option + Commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0 in Jan 2008 added + the new SO_MARK socket option. + + This patch is based on text from the commit message. + + See https://bugzilla.kernel.org/show_bug.cgi?id=16461. + +svipc.7 + Michael Kerrisk + SYNOPSIS: Remove include of and + Including and isn't needed on Linux + and isn't really relevant for the explanation on this page. + + +==================== Changes in man-pages-3.43 ==================== + +Released: 2012-10-05, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Adrian Bunk +Anatoli Klassen +Andreas Schwab +Bjarni Ingi Gislason +David Prévot +Eric Dumazet +Florian Weimer +Frédéric Brière +Fredrik Arnerup +Guillem Jover +Jan Engelhardt +Michael Kerrisk +Simon Josefsson +Stephane Fillod +Trevor Woerner +Yuri Kozlov + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +getenv.3 + Michael Kerrisk [Florian Weimer, Andreas Schwab] + Document secure_getenv(3) + + +New and changed links +--------------------- + +phys.2 + Michael Kerrisk + New link to unimplemented.2 + +secure_getenv.3 + Michael Kerrisk + New link to getenv.3 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix: s/-/\\-/ when real hyphen is required (e.g., in code) + +Various pages + David Prévot [Michael Kerrisk] + Global fix: Various consistency fixes for SEE ALSO + +Various pages + Michael Kerrisk + Global fix: use "Linux kernel source" consistently + Rather than "kernel source". + +Various pages + Michael Kerrisk + Global fix: disable justification and hyphenation in SEE ALSO + For a better visual result, disable justification and hyphenation + in SEE ALSO where page names are long. + +syscalls.2 +uname.2 +boot.7 + Michael Kerrisk + Global fix: s/OS/operating system/ + + +Changes to individual pages +--------------------------- + +epoll_wait.2 + Michael Kerrisk [Fredrik Arnerup] + Describe timeout limitation in kernels < 2.6.37 + As reported by Fredrik (and as far as I can tell the problem + went back to 2.6.0): + + The timeout argument has an upper limit. Any values above that + limit are treated the same as -1, i.e. to wait indefinitely. + The limit is given by: + + #define EP_MAX_MSTIMEO min(1000ULL * MAX_SCHEDULE_TIMEOUT / HZ, \ + (LONG_MAX - 999ULL) / HZ) + + That is, the limit depends on the size of a long and the timer + frequency. Assuming the long is never smaller than 32 bits + and HZ never larger than 1000, the worst case is 35 minutes. + I think this should be mentioned under "BUGS". + + Although this is likely to be fixed in the future + (http://lkml.org/lkml/2010/8/8/144), the problem exists in + at least 2.6.14 - 2.6.35. I don't know if select(2) and poll(2) + are affected. + + https://bugzilla.kernel.org/show_bug.cgi?id=20762 + Michael Kerrisk + Add pointer to select(2) for discussion of close in another thread + +getitimer.2 + Michael Kerrisk [Trevor Woerner] + Note Linux's odd handling of the new_value==NULL case + Michael Kerrisk [Trevor Woerner] + Fix types used to declare fields in timeval struct + +keyctl.2 + David Prévot + Reorder SEE ALSO, without .br + +poll.2 + Michael Kerrisk + Add pointer to select(2) for discussion of close in another thread + +select.2 + Michael Kerrisk [Stephane Fillod] + Note behavior if monitored file descriptor is closed in another thread + Executive summary: a sane application can't rely on any + particular behavior if another thread closes a file descriptor + being monitored by select(). + + See https://bugzilla.kernel.org/show_bug.cgi?id=40852 + Michael Kerrisk + Clarify equivalent pselect() code in terms of threads + s/sigprogmask/pthread_sigmask/ + +semop.2 + Michael Kerrisk + Recast discussion of blocking behavior in terms of threads + semop() blocks the calling thread, not the process. + Michael Kerrisk + SEE ALSO: Add clone(2) + Give reader a clue about CLONE_SYSVSEM. + +shutdown.2 + Michael Kerrisk [Eric Dumazet] + Document EINVAL error (and associated bug) + Eric Dumazet noted that EINVAL was not documented. Some further + digging shows that it's also not diagnosed consistently. + See https://bugzilla.kernel.org/show_bug.cgi?id=47111. + +sigaction.2 + Michael Kerrisk + Tweak SA_RESETHAND description + +timer_settime.2 + Michael Kerrisk + Small rewording around discussion of pointer arguments + +wait4.2 + Adrian Bunk + Note that these functions are nonstandard and recommend alternatives + Some edits to Adrian's patch by mtk. + Michael Kerrisk + CONFORMING TO: Note SUS details for wait3() + +gnu_get_libc_version.3 + Michael Kerrisk + Remove unneeded "#define _GNU_SOURCE" from SYNOPSIS + +pthread_kill.3 +pthread_sigqueue.3 + Michael Kerrisk + Remove wording "another" + Writing "another thread" in these pages implies that these + functions can't be used to send a signal to the calling thread + itself, which is of course untrue. + +sigvec.3 + Michael Kerrisk + Add "int" arg to sv_handler definition in sigvec structure + Michael Kerrisk + Fix small error in discussion of blocking of signals + The signal that causes the handler to be invoked is blocked, + but saying "by default" implies that this can be changed via + the API. It cannot. (One needs sigaction(2) for that.) + +syslog.3 + Simon Josefsson + Remove (apparently bogus) text claiming LOG_AUTH is deprecated + LOG_AUTH is in POSIX, and widely available. There + seems to be no basis to the claim it is deprecated. + + Quoting Simon: + I cannot find any other source that claim LOG_AUTH is + deprecated in any way. LOG_AUTH is distinct from + LOG_AUTHPRIV. The GNU C Library manual only documents + LOG_AUTH. The header files contains both without any + comment. Common systems like Debian appear to refer to + both auth and authpriv facilities in syslog configurations. + Popular daemons appear to use both facilities. + Both facilities are discussed in several RFCs. + + See https://bugzilla.kernel.org/show_bug.cgi?id=46091 + +ttyname.3 + Michael Kerrisk + SEE ALSO: Add ctermid(3) + +proc.5 + Michael Kerrisk + Clarify header file related to 'flags' field of /proc/PID/stat + Michael Kerrisk [Frédéric Brière] + Update description of 'starttime' field of /proc/PID/stat + The unit of measurement changed from jiffies to clock ticks in + Linux 2.6. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=675891 + Michael Kerrisk + Document /proc/sys/kernel/kptr_restrict + Michael Kerrisk [Kees Cook] + Document /proc/sys/fs/protected_symlinks + Based on text in Documentation/sysctl/fs.txt by Kees Cook + Michael Kerrisk [Kees Cook] + Document /proc/sys/fs/protected_hardlinks + Based on text in Documentation/sysctl/fs.txt by Kees Cook + +capabilities.7 + Michael Kerrisk + Document interaction of CAP_SYSLOG and /proc/sys/kernel/kptr_restrict + +ip.7 + Michael Kerrisk + SEE ALSO: Add ipv6(7) + SEE ALSO: Add icmp(7) + +man-pages.7 + Michael Kerrisk + Add some advice about disabling hyphenation in SEE ALSO + +ld.so.8 + Michael Kerrisk + Describe interpretation of slashes in dependency strings + Michael Kerrisk + Repeat note that LD_LIBRARY_PATH is ignored in privileged programs + This point is already noted when discussing search order for + libraries, but it's worth repeating under the specific discussion + of LD_LIBRARY_PATH further down the page. + Michael Kerrisk + Add some details for LD_PRELOAD + Note that LD_PRELOAD list separator can be space or colon + + +==================== Changes in man-pages-3.44 ==================== + +Released: 2012-11-07, Barcelona + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Bert Hubert +David Prévot +James Youngman +Kees Cook +Lars Wirzenius +Lucas De Marchi +Michael Kerrisk +Rusty Russell +Simon Paillard +Thomas Habets + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +delete_module.2 + Michael Kerrisk + Rewrite to Linux 2.6+ reality + Michael Kerrisk + Change license and copyright + There is now nothing left of the original FSF-copyrighted + page. So, change the copyright and license. + Michael Kerrisk [Lucas De Marchi, Rusty Russell] + Substantial reorganization after comments from Rusty Russell + Rusty notes that O_NONBLOCK is almost always used in + practice. Therefore, it would be better to reorganize + the page to consider that "the default". + +init_module.2 + Michael Kerrisk + Rewrite to Linux 2.6+ reality + Michael Kerrisk + Change copyright and license + Little of the original page now remains. Change + copyright and license + Michael Kerrisk [Rusty Russell] + Changes after review comments from Rusty Russell + Kees Cook + Add various pieces describing Linux 2.6+ behavior + Pieces take from, or inspired by, a patch sent by Kees. + +getauxval.3 + Michael Kerrisk + Document getauxval() function added in glibc 2.16 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix: Use consistent capitalization in NAME section + The line(s) in the NAME section should only use capitals + where English usage dictates that. Otherwise, use + lowercase throughout. + +Various pages + Michael Kerrisk + Global fix: "userspace" ==> "user space" or "user-space" + Existing pages variously use "userspace or "user space". + But, "userspace" is not quite an English word. + So change "userspace" to "user space" or, when used + attributively, "user-space". + + +Changes to individual pages +--------------------------- + +clock_getres.2 +clock_nanosleep.2 + Michael Kerrisk + Linking with -lrt is no longer needed from glibc 2.17 onward + +create_module.2 + Michael Kerrisk + Note that this system call is present only in kernels before 2.6 + Michael Kerrisk + Note that ENOSYS probably indicates kernel 2.6+ + +execve.2 + Michael Kerrisk + Document treatment of PR_SET_PDEATHSIG on execve() + Michael Kerrisk + Document treatment of SECBIT_KEEP_CAPS securebits flag on execve() + +fork.2 + Michael Kerrisk + Note treatment of default timer slack value on fork() + +getdomainname.2 + Simon Paillard [Lars Wirzenius] + Point out that these calls relate to NIS, not DNS + See http://bugs.debian.org/295635 + +get_kernel_syms.2 + Michael Kerrisk + Note that this system call is present only in kernels before 2.6 + +ipc.2 + Michael Kerrisk + Update note on architectures that don't have ipc() + Replace mention of ia64 with x86-64 and ARM. + +link.2 + Michael Kerrisk + Add EPERM error triggered by /proc/sys/fs/protected_hardlink + +prctl.2 + Michael Kerrisk + Mention Documentation/prctl/no_new_privs.txt for PR_SET_NO_NEW_PRIVS + Kees Cook + update seccomp sections for mode 2 (BPF) + This adds a short summary of the arguments used + for "mode 2" (BPF) seccomp. + Michael Kerrisk + Small improvements to PR_SET_SECCOMP discussion + Note type of 'arg3' for SECCOMP_MODE_FILTER. + Add pointer to Documentation/prctl/seccomp_filter.txt. + Michael Kerrisk + Note 'seccomp' semantics with respect to fork(), execve(), and prctl() + Michael Kerrisk + Document PR_SET_TIMERSLACK and PR_GET_TIMERSLACK + Michael Kerrisk + Reword PR_SET_NAME and PR_GET_NAME in terms of threads + Plus tfix + Kees Cook + document PR_SET_NO_NEW_PRIVS, PR_GET_NO_NEW_PRIVS + This adds a short description of the no_new_privs bit, + as described in Documentation/prctl/no_new_privs.txt. + +ptrace.2 + Michael Kerrisk + Clarify that some operations are not present on all architectures + PTRACE_GETREGS, PTRACE_SETGREFS, PTRACE_GETFPREGS, + and PTRACE_GETSPREGS are not present on all architectures. + PTRACE_SYSEMU and PTRACE_SYSEMU_SINGLESTEP are present only + on x86. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=122383 + +query_module.2 + Michael Kerrisk + Add a few words clarifying reference to /sys/module + Michael Kerrisk + Note that this system call is present only in kernels before 2.6 + Michael Kerrisk + Note that ENOSYS probably indicates kernel 2.6+ + Michael Kerrisk + SEE ALSO: Add modinfo(8) and lsinfo(8) + Michael Kerrisk + Move some information in NOTES to VERSIONS + +socketcall.2 + Michael Kerrisk + Update note on architectures that don't have socketcall() + Replace mention of ia64 with x86-64 and ARM. + +times.2 + Thomas Habets + Recommend clock_gettime(2) as alternative to times(2) + +clock_getcpuclockid.3 + Michael Kerrisk + Linking with -lrt is no longer needed from glibc 2.17 onward + +fts.3 + Simon Paillard [James Youngman] + Improve description of physical vs. logical tree walking + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=633505 + +getenv.3 + Michael Kerrisk + SEE ALSO: add getauxval(3) + +proc.5 + Michael Kerrisk + Document /proc/meminfo + Info mostly taken from Documentation/filesystems/proc.txt + and Documentation/vm/hugetlbpage.txt. + Michael Kerrisk + Default for /proc/sys/fs/protected_{hardlinks,symlinks} is now 0 + The default setting of 1 in/proc/sys/fs/protected_hardlinks + and /proc/sys/fs/protected_symlinks caused one too many + breakages for Linus's taste, so commit 561ec64ae67e changed + the default for both files to 0. + Note system call error yielded by /proc/sys/fs/protected_symlinks + Note that violating 'protected_symlinks' restrictions + causes system calls to fail with the error EACCES. + Michael Kerrisk + Since Linux 2.6.27, /proc/sys/kernel/modprobe depends on CONFIG_MODULES + +ipv6.7 + Bert Hubert + Document IPV6_RECVPKTINFO + +man-pages.7 + Michael Kerrisk + Note rules for capitalization in NAME section + +time.7 + Michael Kerrisk + Add a subsection on timer slack + +ld.so.8 + Michael Kerrisk + SEE ALSO: add getauxval(3) + + +==================== Changes in man-pages-3.45 ==================== + +Released: 2012-12-21, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andi Kleen +Cyril Hrubis +David Prévot +Elie De Brauwer +Eric Dumazet +Felipe Pena +Florian Weimer +Gao Feng +Jan Glauber +Jim Paris +Jon Grant +Julien Cristau +Michael Kerrisk +Mike Frysinger +Rens van der Heijden +Simon Paillard +Thierry Vignaud +Trevor Woerner +YOSHIFUJI Hideaki + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +s390_runtime_instr.2 + Jan Glauber + New page for s390-specific s390_runtime_instr(2) + +if_nameindex.3 + YOSHIFUJI Hideaki + Document if_nameindex(3) and if_freenameindex(3) + Michael Kerrisk + Edits, improvements and corrections to Hideaki's page + Michael Kerrisk + Add an example program + +if_nametoindex.3 + YOSHIFUJI Hideaki + New page documenting if_nametoindex(3) and if_indextoname(3) + + +New and changed links +--------------------- + +if_freenameindex.3 + Michael Kerrisk + New link to if_nameindex.3 + +if_indextoname.3 + Michael Kerrisk + New link to if_nametoindex.3 + + +Global changes +-------------- + +sysconf.3 +cciss.4 + Michael Kerrisk + Global fix: s/runtime/run time/ + + +Changes to individual pages +--------------------------- + +clone.2 + Michael Kerrisk + Since 2.6.30, CLONE_NEWIPC also supports POSIX message queues + +delete_module.2 + Michael Kerrisk + Small rewording of description of effect of O_TRUNC + +getrlimit.2 + Michael Kerrisk [Trevor Woerner] + Document Linux's nonstandard treatment or RLIMIT_CPU soft limit + Upon encountering the RLIMIT_CPU soft limit when a SIGXCPU handler + has been installed, Linux invokes the signal handler *and* raises + the soft limit by one second. This behavior repeats until the + limit is encountered. No other implementation that I tested + (Solaris 10, FreeBSD 9.0, OpenBSD 5.0) does this, and it seems + unlikely to be POSIX-conformant. The (Linux-specific) + RLIMIT_RTTIME soft limit exhibits similar behavior. + Michael Kerrisk + Point reader at discussion of /proc/[pid]/limits in proc(5) + +io_getevents.2 + Michael Kerrisk + io_getevents() may cause segfault when called with invalid ctx_id + For reference see: http://marc.info/?l=linux-aio&m=130089887002435&w=2 + +recv.2 + Michael Kerrisk [Eric Dumazet] + UNIX domain sockets support MSG_TRUNC since 3.4 + +sendmmsg.2 + Elie De Brauwer + Add example program for sendmmsg() + +stat.2 + Simon Paillard + Clarify description of EOVERFLOW error + The EOVERFLOW error is not only for st_size, but also + inode and block size fields. See glibc source file + sysdeps/unix/sysv/linux/xstatconv.c and kernel source + file fs/stat.c. Also, fix bit/byte confusion + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=604928 + +syscalls.2 + Michael Kerrisk + Update various references to "i386" to "x86" + Michael Kerrisk + Add s390_runtime_instr(2) + +sysctl.2 + Michael Kerrisk + Mention CONFIG_SYSCTL_SYSCALL + Michael Kerrisk + Calls to sysctl() log warnings to the kernel log since 2.6.24 + +syslog.2 + Michael Kerrisk + Substantially reorganize discussion of commands + Make the layout of the discussion of the commands + more readable. + Michael Kerrisk + Add kernel symbolic 'type' names + Michael Kerrisk + Clarify SYSLOG_ACTION_SIZE_UNREAD semantics + SYSLOG_ACTION_SIZE_UNREAD returns the number of bytes + available for reading via SYSLOG_ACTION_READ. + Michael Kerrisk + Clarify where SYSLOG_ACTION_READ_ALL places data it reads + Michael Kerrisk + Clarify semantics of SYSLOG_ACTION_CLEAR + The SYSLOG_ACTION_CLEAR command (5) does not really clear + the ring buffer; rather it affects the semantics of what + is returned by commands 3 (SYSLOG_ACTION_READ_ALL) and + 4 (SYSLOG_ACTION_READ_CLEAR). + Michael Kerrisk + Clarify discussion of privileges for commands 3 and 10 + Michael Kerrisk + Add mention of CONFIG_LOG_BUF_SHIFT + +wait.2 + Michael Kerrisk + BUGS: Document odd waitid() behavior when 'infop' is NULL + +getifaddrs.3 + Michael Kerrisk [Julien Cristau] + Update description of ifa_data to Linux 2.6+ reality + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=526778 + +memcmp.3 + Michael Kerrisk [Jon Grant] + Enhance RETURN VALUE text and remove redundant text from DESCRIPTION + Note that sign of result equals sign of difference between + first two bytes that differ (treated as "unsigned char")." + +mkstemp.3 + Michael Kerrisk [Florian Weimer] + Deemphasize discussion of mode 066 in glibc 2.0.6 + Glibc 2.0.6 is now so ld that the discussion of details + of that version can be deemphasized placing just under + NOTES. + + See https://bugzilla.kernel.org/show_bug.cgi?id=51811 + +strcmp.3 + Michael Kerrisk [Jon Grant] + Enhance RETURN VALUE text and remove redundant text from DESCRIPTION + Note that sign of result equals sign of difference between + first two bytes that differ (treated as "unsigned char")." + +ttyname.3 + Michael Kerrisk + Fix confused text in ERRORS + The existing text suggested that the ERRORS applied + only for ttyname_r(). However, 2 of the 3 errors + can occur for ttyname(). + +undocumented.3 + Michael Kerrisk + Remove some now documented functions + +proc.5 + Michael Kerrisk [Jim Paris] + Correct description of SwapFree in /proc/meminfo + Michael Kerrisk + Note change of /proc/[pid]/limits file permissions in 2.6.36 + +resolv.conf.5 + Simon Paillard + Document IPv6 format for nameserver + See: http://bugs.debian.org/610036 + +capabilities.7 + Michael Kerrisk [Rens van der Heijden] + Correct URL for POSIX.1e draft + +ipv6.7 + Gao Feng + Add description of getsockopt() for IPV6_MTU + In IPv4,IP_MTU is only supported by getsockopt. + In IPv6, we can use IPV6_MTU to set socket's MTU, + but the return value of getsockopt() is the path MTU. + +rtnetlink.7 + Michael Kerrisk [Julien Cristau] + Update description of IFLA_STATS to Linux 2.6+ reality + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=526778 + +socket.7 + Michael Kerrisk [YOSHIFUJI Hideaki] + Document 'sockaddr' and 'sockaddr_storage' types + Andi Kleen + Explain effect of SO_SNDTIMEO for connect() + When SO_SNDTIMEO is set before connect(), then connect() + may return EWOULDBLOCK when the timeout fires. + + +==================== Changes in man-pages-3.46 ==================== + +Released: 2013-01-27, Canberra + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andrew Perepechko +Cédric Boutillier +Cyrill Gorcunov +Daan Spitz +David Prévot +Elie De Brauwer +Garrett Cooper +James Noble +Justin Lebar +Kees Cook +Lucas De Marchi +Mark Hills +Maxin B. John +Michael Kerrisk +Michal Gorny +Peter Budny +Peter Lekeynstein +Rusty Russell +Samuel Thibault +Sam Varshavchik +Shawn Landden +Simon Paillard +Starlight +Theodore Ts'o +Wolfgang Rohdewald +Zsbán Ambrus + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +kcmp.2 + Cyrill Gorcunov, Michael Kerrisk + New page for kcmp(2) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +init_module.2 + Michael Kerrisk [Kees Cook, Rusty Russell, Lucas De Marchi] + Document finit_module(2) + Rusty Russell [Lucas De Marchi, Kees Cook] + Document finit_module() 'flags' argument + Document MODULE_INIT_IGNORE_MODVERSIONS and + MODULE_INIT_IGNORE_VERMAGIC. (Some edits by mtk.) + + +New and changed links +--------------------- + +finit_module.2 + Michael Kerrisk + New link to init_module.2 + +__after_morecore_hook.3 +__free_hook.3 +__malloc_initialize_hook.3 +__memalign_hook.3 +__realloc_hook.3 + Michael Kerrisk + New link to malloc_hook.3 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix: s/tty/terminal/ + + +Changes to individual pages +--------------------------- + +clone.2 + Michael Kerrisk + Add kernel versions for various CLONE_* constants + Michael Kerrisk + CLONE_NEWIPC governs mechanisms that don't have filesystem pathnames + Michael Kerrisk + CLONE_NEWIPC doesn't mount the POSIX MQ file system + Michael Kerrisk + Add an example program (CLONE_NEWUTS) + Michael Kerrisk + Some reworking of CLONE_NEWIPC text + No substantial content changes. + Michael Kerrisk + SEE ALSO: add kcmp(2) + SEE ALSO: add setns(2) + +fallocate.2 + Michael Kerrisk + FALLOC_FL_* flags are defined in glibc only since 2.18 + +getxattr.2 +removexattr.2 +setxattr.2 + Michael Kerrisk [Andrew Perepechko, ] + Note that ENOATTR is a synonym for ENODATA + Various people have pointed out that strace(1) shows ENODATA + for the case where the named attribute does not exist, or + the process has no access to this attribute. ENODATA + and ENOATTR are in fact defined as synonyms. Point this out + in the man page, so that people understand the strace(1) info. + + See https://bugzilla.kernel.org/show_bug.cgi?id=51871 + +getxattr.2 +listxattr.2 +removexattr.2 +setxattr.2 + Michael Kerrisk + Put errors under ERRORS section + The errno values on these pages were listed in a nonstandard + way under the RETURN VALUE section. Put them in ERRORS sections. + +init_module.2 + Michael Kerrisk [Rusty Russell] + ERRORS: Add errors for module signatures (EBADMSG, ENOKEY) + +link.2 +mkdir.2 +mknod.2 +open.2 +rename.2 +symlink.2 +write.2 +mkfifo.3 + Mark Hills + Document EDQUOT error + The return error EDQUOT is not documented in open(2), write(2), + symlink(2) etc. + + Whether inodes or disk blocks are required for each function + is something I based on received wisdom and BSD documentation, + rather than tracing the code to the kernel. For symlink(2) + this certainly depends on the file system type. + +listxattr.2 + Michael Kerrisk [Theodore Ts'o] + Fix RETURN VALUE description + On success, 0 may be returned, so change wording from + "positive number" to "nonnegative number". + +outb.2 + Michael Kerrisk + Add SYNOPSIS + +prctl.2 + Kees Cook + Document PR_SET_PTRACER + Document the Yama LSM's prctl handler that allows processes to + declare ptrace restriction exception relationships via + PR_SET_PTRACER. + Michael Kerrisk + Make it explicit that PR_SET_PTRACER replaces previous setting + The attribute is a scalar, not a list. + Shawn Landden + Document EINVAL error for PR_SET_PTRACER + Michael Kerrisk + Document PR_GET_TID_ADDRESS + +ptrace.2 + Michael Kerrisk + Document PTRACE_O_EXITKILL + Michael Kerrisk + Place PTRACE_SETOPTIONS list in alphabetical order + +query_module.2 + Michael Kerrisk + Must be called using syscall(2) + Yes, the call is way obsolete, but add this info + for completeness. + +recvmmsg.2 + Elie De Brauwer + Add/correct kernel version info for recvmmsg() and MSG_WAITFORNONE + This patch isolates the since/version related fixes as requested. + This change introduces the following delta: + * The page states it was added in 2.6.32 but it is only added + 2.6.33 (ref: http://kernelnewbies.org/Linux_2_6_33) + * The MSG_WAITFORONE flag was in turn only added in 2.6.34 + (ref: http://kernelnewbies.org/Linux_2_6_34) + Elie De Brauwer + Add an example program + +setns.2 + Michael Kerrisk + Add example program + +sigaction.2 + Michael Kerrisk [Zsbán Ambrus] + Note feature test macro requirements for 'siginfo_t' + See https://bugzilla.kernel.org/show_bug.cgi?id=52931 + +syscalls.2 + Michael Kerrisk + Add kern_features(2) + Michael Kerrisk + Add utrap_install(2) + Sparc-specific, present since ancient times + Michael Kerrisk + Add finit_module(2) + +sysctl.2 + Michael Kerrisk [Garrett Cooper] + ERRORS: EACCES as a synonym for EPRM + See https://bugzilla.kernel.org/show_bug.cgi?id=46731 + and http://thread.gmane.org/gmane.linux.ltp/11413/focus=957635 + From: Garrett Cooper gmail.com> + Subject: Re: [LTP] [PATCH] sysctl03: sysctl returns EACCES after 2.6.33-rc1 + Newsgroups: gmane.linux.kernel, gmane.linux.ltp + Date: 2010-03-04 18:35:33 GMT + +unshare.2 + Michael Kerrisk + Update NOTES on unimplemented flags + Michael Kerrisk + Fix text problems in description of CLONE_FS + Michael Kerrisk + SEE ALSO: add kcmp(2) + SEE ALSO: add setns(2) + Michael Kerrisk + Reorder CLONE_NEWUTS entry in list + +difftime.3 + Michael Kerrisk [Michal Gorny] + Remove crufty text about 'time_t' on "other systems" + Back in 2006, some text came in via Debian patches that seems + crufty. Remove it. + + See https://bugzilla.kernel.org/show_bug.cgi?id=46731 + +getaddrinfo.3 +getnameinfo.3 + Michael Kerrisk [Peter Budny] + Fix some confused references to function names + See https://bugzilla.kernel.org/show_bug.cgi?id=52741 + +getspnam.3 + Michael Kerrisk [Wolfgang Rohdewald] + ERRORS: Add EACCES + See https://bugzilla.kernel.org/show_bug.cgi?id=52681 + +__setfpucw.3 + Michael Kerrisk + Add proper page cross refs for alternate functions + +core.5 +proc.5 + Kees Cook + Clarify suid_dumpable versus core_pattern + In Linux 3.6, additional requirements were placed on core_pattern + when suid_dumpable is set to 2. Document this and include commit + references. + Justin Lebar + statm's "shared" field refers to pages backed by files + I noticed that statm's "shared" field doesn't match the sum of + all the "shared" entries in smaps [1]. + + The kernel docs explain that statm's "shared" field is "number of + pages that are shared (i.e. backed by a file)" [2]. smaps appears + to call a page shared if it's mapped by at least two processes, + which explains this discrepancy. + + I'm not a kernel hacker, but it appears to me they do mean "i.e." + and not "e.g." in the statm description: In + fs/proc/task_mmu.c::task_statm, I see + + *shared = get_mm_counter(mm, MM_FILEPAGES); + + Here's a patch which updates the man page to match the (hopefully + correct) kernel docs. + + [1] https://bugzilla.mozilla.org/show_bug.cgi?id=807181 + [2] http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=Documentation/filesystems/proc.txt;h=a1793d670cd01bd374eddf54ffdfc768504291ff;hb=HEAD + +proc.5 + Kees Cook + Put /proc/sys/kernel/hotplug in alphabetical order + Kees Cook + Document /proc/sys/kernel/dmesg_restrict + Kees Cook + Linux 3.4 changed permissions needed to change kptr_restrict + Michael Kerrisk [Samuel Thibault, Simon Paillard] + Add field numbers for /proc/PID/stat + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=553413 + Add numbering to /proc/stat "cpu" fields + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=553413 + Michael Kerrisk + Reorganize text describing /proc/stat "cpu" fields + Michael Kerrisk + Rewording of suid_dumpable text after comments from Kees Cook + Michael Kerrisk [Samuel Thibault, Simon Paillard] + Add field numbers for /proc/[pid]/statm + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=553413 + Michael Kerrisk + Document /proc/stat "cpu" "nice_guest" field + Info taken from commit ce0e7b28fb75cb003cfc8d0238613aaf1c55e797 + Michael Kerrisk [Peter Lekeynstein] + Document /prod/[pid]/oom_score_adj + Text taken directly from Documentation/filesystems/proc.txt, + with some light editing. + + See https://bugzilla.kernel.org/show_bug.cgi?id=50421 + +shells.5 + Michael Kerrisk + Add /etc/bash to list of example shells + +ttytype.5 + Michael Kerrisk + Add proper xref for termcap and terminfo pages + +capabilities.7 + Michael Kerrisk + Add kcmp(2) under CAP_SYS_PTRACE + +man-pages.7 + Michael Kerrisk + Update description of Section 7 + + +==================== Changes in man-pages-3.47 ==================== + +Released: 2013-02-12, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +David Prévot +D. Barbier +Lennart Poettering +Michael Kerrisk +Mike Frysinger +Peter Schiffer +Radek Pazdera +Reuben Thomas +Shawn Landden +Simon Paillard +Vince Weaver + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +perf_event_open.2 + Vincent Weaver + New page documenting perf_event_open(2) + +pthread_setname_np.3 + Chandan Apsangi, Michael Kerrisk + New page for pthread_setname_np(3) and pthread_getname_np(3) + +sln.8 + Michael Kerrisk [Peter Schiffer] + New page documenting the 'sln' command provided by glibc + Inspired by a Red Hat downstream page, but with rather + more detail. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +prctl.2 + Michael Kerrisk [Shawn Landden, Lennart Poettering] + Document PR_SET_CHILD_SUBREAPER and PR_GET_CHILD_SUBREAPER + +ip.7 + Radek Pazdera + Add source-specific multicast sockopts + This patch adds documentation of several source-specific multicast + socket options that were added to kernel with implementation + of IGMPv3 in 2.5.68. + + The following socket options were added: + IP_ADD_SOURCE_MEMBERSHIP + IP_DROP_SOURCE_MEMBERSHIP + IP_BLOCK_SOURCE + IP_UNBLOCK_SOURCE + IP_MSFILTER + + +Pages moved across sections +--------------------------- + +getcontext.3 + Michael Kerrisk + This page really belongs in Section 3 (moved from Section 2) + +getdtablesize.3 + Michael Kerrisk + Move from Section 2 + + +New and changed links +--------------------- + +getcontext.2 + Michael Kerrisk + Make link to page moved into Section 3 + +getdtablesize.2 + Michael Kerrisk + Link to renamed getdtablesize.3 + +setcontext.2 + Michael Kerrisk + Modify link to point to Section 3 + +pthread_getname_np.3 + Michael Kerrisk + New link to new pthread_setname_np.3 + +setcontext.3 + Michael Kerrisk + Link to getcontext page renamed into Section 3 + + +Changes to individual pages +--------------------------- + +fallocate.2 + Michael Kerrisk + SEE ALSO: add fallocate(1) + +flock.2 + Michael Kerrisk + SEE ALSO: add flock(1) + +fork.2 + Michael Kerrisk + SEE ALSO: add exit(2) + +getpriority.2 + Michael Kerrisk + BUGS: note that nice value is per-thread on Linux + +getrlimit.2 + Michael Kerrisk + SEE ALSO: add prlimit(1) + +gettid.2 + Michael Kerrisk + SEE ALSO: add various system calls that use thread IDs + +ioprio_set.2 + Michael Kerrisk + SEE ALSO: add ionice(1) + +sched_setaffinity.2 + Michael Kerrisk + SEE ALSO: add taskset(1) + +sched_setparam.2 + Michael Kerrisk + Scheduling policy and parameters are per-thread on Linux + Direct the reader to the discussion in sched_setscheduler(2). + +sched_setscheduler.2 + Michael Kerrisk + Scheduling policy and parameters are per-thread on Linux + Michael Kerrisk + SEE ALSO: add chrt(1) + +setsid.2 + Michael Kerrisk + SEE ALSO: add setsid(1) + +shmop.2 + Michael Kerrisk [Peter Schiffer] + ERRORS: Add EIDRM + Taken from Red Hat downstream patch + +sigaction.2 +makecontext.3 + Michael Kerrisk + Change getcontext/setcontext page ref to Section 3 + +signal.2 + Michael Kerrisk [Reuben Thomas] + Clarify System V vs BSD semantics for signal() + +syscalls.2 + Michael Kerrisk + The list on this page is not just syscalls common to all platforms + Michael Kerrisk + Add perfctr(2) + Add ppc_rtas(2) + Michael Kerrisk + Add kernel version number of utrap_install(2) + +unimplemented.2 + Michael Kerrisk [Peter Schiffer] + Remove mention of kernel version number in DESCRIPTION + +inet.3 + Michael Kerrisk [Peter Schiffer] + Fix error in EXAMPLE using inet_aton() + See https://bugzilla.redhat.com/show_bug.cgi?id=837090 + Patch taken from Red Hat downstream. + +posix_fallocate.3 + Michael Kerrisk + SEE ALSO: add fallocate(1) + +regex.3 + Reuben Thomas + Clarify details of matching + The first is that it's far from clear that the end points of the + complete string match are stored in the zero'th element of the + regmatch_t array; secondly, the phrase "next largest substring + match" is positively misleading, implying some sort of size + ordering, whereas in fact they are ordered according to their + appearance in the regex pattern. + +scanf.3 + Michael Kerrisk + Clarify meaning of "string conversions" for 'm' modifier + Mike Frysinger + Update %a vs %m documentation + POSIX.1-2008 adopted the 'm' flag for dynamic allocation. Update + page to cover it and relegate the glibc-specific 'a' flag to + NOTES. + +strtol.3 + Michael Kerrisk [Peter Schiffer] + Replace some bogus text about "thousands separator" + See https://bugzilla.redhat.com/show_bug.cgi?id=652870 + +sysconf.3 + Michael Kerrisk [Peter Schiffer] + Use "_SC_PAGESIZE" consistently on page + s/_SC_PAGE_SIZE/_SC_PAGESIZE/ in one instance. + From Red Hat downstream patch. + +nscd.conf.5 + Peter Schiffer + Add max-db-size and auto-propagate descriptions, default values, + misc + * added missing valid services (services and netgroup) + * added many default values for options + * reordered options according to the nscd.conf file + (logical order) + * added 2 missing options: max-db-size and auto-propagate + +nsswitch.conf.5 + Peter Schiffer + Mention initgroups db + +proc.5 + Michael Kerrisk + Document /proc/profile + Michael Kerrisk [Peter Schiffer] + Update /proc/sys/fs/file-nr to include Linux 2.6 details + Michael Kerrisk + Clarify relationship between file-max and file-nr + The third value in /proc/sys/fs/file-nr is the same as + the value in /proc/sys/fs/file-max. + Michael Kerrisk + Note message written to kernel log when file-max limit is hit + Info from Documentation/sysctl/fs.txt. + Michael Kerrisk + Mention lscpu(1) under discussion of /proc/cpuinfo + +resolv.conf.5 + Michael Kerrisk [Peter Schiffer] + Document "single-request-reopen" option + Taken from Red Hat downstream patch + + See https://bugzilla.redhat.com/show_bug.cgi?id=717770 + See http://thread.gmane.org/gmane.linux.man/3161 + +utmp.5 + Michael Kerrisk + SEE ALSO: add utmpdump(1) + +cpuset.7 + Simon Paillard + Add missing 'cpuset.' prefix for some flags + See kernel commit e21a05cb408bb9f244f11a0813d4b355dad0822e + +svipc.7 + Michael Kerrisk + SEE ALSO: add ipcmk(1), ipcrm(1), ipcs(1) + +termio.7 + Michael Kerrisk + SEE ALSO: add reset(1), setterm(1), stty(1), tty(4) + +ld.so.8 + Michael Kerrisk [Peter Schiffer] + LD_VERBOSE does not work with ld.so --list and --verify + From Red Hat downstream patch + + See https://bugzilla.redhat.com/show_bug.cgi?id=532629 + Michael Kerrisk + SEE ALSO: add sln(8) + +zdump.8 + Michael Kerrisk [Peter Schiffer] + Bring up to date with zdump --help + Patch taken from Red Hat downstream. + + +==================== Changes in man-pages-3.48 ==================== + +Released: 2013-03-05, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andrey Vagin +Aristeu Rozanski +Colin Walters +Cyril Hrubis +Cyrill Gorcunov +Daniel P. Berrange +David Prévot +D. Barbier +Denys Vlasenko +Flavio Leitner +Graham Gower +Ivana Varekova +Kai Kunschke +Marcela Maslanova +Marc Lehmann +Marshel Abraham +Michael Kerrisk +Nathan Stratton Treadway +Pavel Emelyanov +Peter Schiffer +Simon Heimberg +Simon Paillard +Török Edwin +Ulrich Drepper +Zack Weinberg + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +getunwind.2 + Marcela Maslanova + New page documenting getunwind(2) + Taken from Red Hat downstream man pages set + Michael Kerrisk + Much rewriting + Some text taken from arch/ia64/kernel/unwind.c. + +perfmonctl.2 + Ivana Varekova + New page documenting IA-64-specific perfmonctl(2) + Taken from Red Hat downstream man pages + Michael Kerrisk + Rework discussion of PFM_CREATE_CONTEXT + Add VERSIONS and CONFORMING TO + Note that there is no glibc wrapper + Remove PFM_CREATE_EVTSETS, PFM_DELETE_EVTSETS, PFM_GETINFO_EVTSETS + These don't exist, and it appears they never have. + Fix argument types for PFM_WRITE_PMCS, PFM_WRITE_PMDS, PFM_READ_PMDS + The types that were being used don't exist! + Briefly document PFM_GET_FEATURES, PFM_DEBUG, PFM_GET_PMC_RESET_VAL + +gai.conf.5 + Ulrich Drepper + New page documenting gai.conf + Taken from Red Hat downstream pages + +nss.5 + Ulrich Drepper + New page describing nss.conf + + +Newly documented interfaces in existing pages +--------------------------------------------- + +clock_getres.2 + Cyril Hrubis + Document CLOCK_REALTIME_COARSE and CLOCK_MONOTONIC_COARSE + Cyril Hrubis + Document CLOCK_BOOTTIME + Michael Kerrisk + Some improvements to CLOCK_BOOTTIME description + +ptrace.2 + Denys Vlasenko + Document PTRACE_GETREGSET, PTRACE_SETREGSET, PTRACE_SEIZE, and friends + Document PTRACE_GETREGSET, PTRACE_SETREGSET, + PTRACE_SEIZE, PTRACE_INTERRUPT, and PTRACE_LISTEN. + + +New and changed links +--------------------- + +fattach.2 +fdetach.2 +getmsg.2 +isastream.2 +putmsg.2 + Michael Kerrisk [Peter Schiffer] + New link to unimplemented.2 + Taken from Red Hat downstream. + + See https://bugzilla.redhat.com/show_bug.cgi?id=436407 + + +Global changes +-------------- + +Many pages + Michael Kerrisk + Global fix: remove unneeded double quotes in .SH headings + +Many pages + Michael Kerrisk + Global fix: remove unneeded double quotes in .SS headings + +Many pages + Michael Kerrisk + Global fix: use consistent capitalization in .SS headings + Capitalization in .SS sections across pages (and sometimes even + within a single page) is wildly inconsistent. Make it consistent. + Capitalize first word in heading, but otherwise use lower case, + except where English usage (e.g., proper nouns) or programming + language requirements (e.g., identifier names) dictate otherwise. + +Many pages + Michael Kerrisk [Denys Vlasenko] + Remove double blank lines in output + +Various pages + Michael Kerrisk + Fix order of SH sections + + +Changes to individual pages +--------------------------- + +accept.2 + Michael Kerrisk + NAME: Add "accept4" + +access.2 + Colin Walters + Note that access() may also fail for FUSE + Since in some cases (e.g. libguestfs's guestmount) it also has the + semantics where files can appear owned by root, but are actually + mutable by the user, despite what one might infer from the Unix + permissions. + +getpeername.2 + Michael Kerrisk [Kai Kunschke] + Clarify semantics of getpeername() for datagram sockets + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=674034 + +getuid.2 + Michael Kerrisk + Remove duplicate section heading + +mmap.2 + Cyril Hrubis + Add note about partial page in BUGS section + This adds a note about Linux behavior with partial page at the end + of the object. The problem here is that a page that contains only + part of a file (because the file size is not multiple of PAGE_SIZE) + stays in page cache even after the mapping is unmapped and the file + is closed. So if some process dirties such page, other mappings + will see the changes rather than zeroes. + Michael Kerrisk [Török Edwin] + Some 'flags' values require a feature test macro to be defined + Add text to NOTES noting that some MAP_* constants are + defined only if a suitable feature test macro is defined. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=542601 + Cyril Hrubis + Document EOVERFLOW error + +open.2 + Michael Kerrisk + Clarify list of file creation flags + POSIX.1-2008 TC1 clarified this, so that O_CLOEXEC, + O_DIRECTORY, and O_NOFOLLOW are also in this list. + +prctl.2 + Cyrill Gorcunov + Add some details for PR_GET_TID_ADDRESS + +read.2 + Michael Kerrisk [Zack Weinberg] + Clarify interaction of count==0 and error checking + POSIX deliberately leaves this case open, so the man + page should be less specific about what happens. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=533232 + Michael Kerrisk [Marc Lehmann] + Remove crufty text about O_NONBLOCK on files + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=700529 + Michael Kerrisk + Clarify details for seekable files + +unimplemented.2 + Michael Kerrisk [Peter Schiffer] + Add various STREAMS interfaces to NAME + Taken from Red Hat downstream. + + See https://bugzilla.redhat.com/show_bug.cgi?id=436407 + +cexp2.3 + Michael Kerrisk + Still does not exist in glibc 2.17 + +exit.3 + Michael Kerrisk + Note that a call to execve() clears exit handler registrations + +getaddrinfo.3 + Michael Kerrisk + SEE ALSO: Add gai.conf(5) + +malloc_trim.3 + Michael Kerrisk + Remove duplicate section title + +printf.3 + Marshel Abraham [Graham Gower, Graham Gower] + Fix error handling in example code + See https://bugzilla.kernel.org/show_bug.cgi?id=23282 + +pthread_yield.3 + Michael Kerrisk [Aristeu Rozanski] + Add _GNU_SOURCE feature test macro to SYNOPSIS + +resolver.3 +resolv.conf.5 + Michael Kerrisk [Nathan Stratton Treadway, Simon Heimberg] + RES_DEBUG is only available if glibc is compiled with debug support + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=692136 + and https://bugzilla.kernel.org/show_bug.cgi?id=43061 + +strtol.3 + Michael Kerrisk [Peter Schiffer] + Remove crufty text from previous fix + +core.5 + Michael Kerrisk + Document CONFIG_COREDUMP + +capabilities.7 + Andrey Vagin + Nonexistent bits are no longer shown as set in /proc/PID/status Cap* + +inotify.7 + Michael Kerrisk + A monitoring process can't easily distinguish events triggered by itself + +ip.7 + Flavio Leitner [Peter Schiffer] + Improve explanation about calling listen() or connect() + +man-pages.7 + Michael Kerrisk + Describe rules for capitalization in .SS headings + +rtnetlink.7 + Pavel Emelyanov + Add info about ability to create links with given index + Since kernel v3.7 the RTM_NEWLINK message now accepts nonzero + values in ifi_index field. Mention this fact in the respective + rtnetlink.7 section. + +socket.7 + Pavel Emelyanov + SO_BINDTODEVICE is now readable + SO_BINDTODEVICE is readable since kernel 3.8. + + +==================== Changes in man-pages-3.49 ==================== + +Released: 2013-03-10, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Michael Kerrisk + + +Global changes +-------------- + +The goal of the changes below to consistently format copyright +and license information in the comments in the page source +at the top of each page. This allows for easy scripting to +extract that information. Following these changes the comments +the top of the page source should now consistently have the form: + + .\" + .\" + .\" %%%LICENSE_START() + .\" + .\" %%%LICENSE_END + .\" + +Note that the 'license-type' is merely descriptive. Its purpose is +to simplify scripting for the purpose of gathering statistics on +types of licenses used in man-pages. It is NOT a statement about +the actual licensing of the page; that license is contain INSIDE the +LICENSE_START...LICENSE_END clause. + +All pages + Michael Kerrisk + Add a LICENSE_START()...LICENSE_END clause in source at + top of each page that encapsulates the license text. + Michael Kerrisk + Put copyright info at top of page, followed by blank line and LICENSE + +Various pages + Michael Kerrisk + Update info in source comments on where to get a copy of the GPL + +Various pages + Michael Kerrisk + Remove "Hey Emacs" comment in page source + Only certain pages have this; there is no consistency, so + remove it from all pages + Michael Kerrisk + Remove "-*- nroff -*-" comment at top of source + + +==================== Changes in man-pages-3.50 ==================== + +Released: 2013-03-15, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andrey Vagin +Bernhard Kuemel +Elie De Brauwer +Erik Saule +Florian Weimer +Friedrich Delgado Friedrichs +Jonathan Nieder +Jose Luis Domingo Lopez +Mark R Bannister +Michael Kerrisk +Sam Varshavchik +Simon Paillard + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +canonicalize_file_name.3 + Michael Kerrisk + Rewrite page, adding much more detail + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix: s/END_LICENSE/LICENSE_END/ + +Various pages + Michael Kerrisk + Global fix: s/bitmask/bit mask/ + + +Changes to individual pages +--------------------------- + +getent.1 + Mark R Bannister + netgroup description incorrectly refers to initgroups + +capget.2 + Michael Kerrisk + Update URL for libcap + +fork.2 + Michael Kerrisk + Port access permission bits (ioperm()) are turned off in the child + +futex.2 + Michael Kerrisk + 'timeout' is a minimum duration that the call will wait, not a maximum + +ioperm.2 + Michael Kerrisk + Note that iopl() level of 3 is needed to access ports + Michael Kerrisk + 'num' is *bits* not bytes! + Michael Kerrisk + Linux 2.6.8 lifted the port limit to 65,536 + See http://article.gmane.org/gmane.linux.kernel/202624/ + From: Stas Sergeev aknet.ru> + Subject: [patch][rfc] Larger IO bitmap + Date: 2004-05-07 19:55:03 GMT + Michael Kerrisk + ioperm() operates on the calling *thread* (not process) + Michael Kerrisk + Clarify meaning of 'turn_on' argument + Plus form formatting fixes. + Michael Kerrisk + Clarify that default state of permission bits in child is off + Michael Kerrisk + NOTES: add mention of /proc/ioports + Michael Kerrisk + SEE ALSO: add outb(2) + +iopl.2 + Michael Kerrisk + CAP_SYS_RAWIO is required to *raise* the I/O privilege level + Michael Kerrisk + Clarify that the two least significant bits of 'level' are what matter + Michael Kerrisk + SEE ALSO: add outb(2) + +syscalls.2 + Michael Kerrisk + Add version information for all (other) syscalls + Michael Kerrisk + Add perfmonctl(2) + +futimes.3 + Michael Kerrisk [Jonathan Nieder] + ERRORS: Add ENOSYS for lutimes() + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=620746 + +getpass.3 + Michael Kerrisk [Erik Saule] + Suggest use of the ECHO flag as an alternative + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=644261 + +realpath.3 + Michael Kerrisk + Document GNU extensions for EACCES and ENOENT errors + +stdarg.3 + Michael Kerrisk [Friedrich Delgado Friedrichs] + Describe va_copy() + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=575077 + +termios.3 + Michael Kerrisk [Bernhard Kuemel] + Mention that noncanonical mode does not do input processing + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=643854 + +random.4 + Elie De Brauwer + Document write and document the ioctl interface of /dev/random + The update consists out of two parts: + - a minor thing which just documents what happens if a write to + /dev/(u)random is performed, which is used in the example + script but not explicitly mentioned. + - the other (biggest) part is the documentation of the ioctl() + interface which /dev/(u)random exposes. This ioctl() lives in + drivers/char/random.c and the primitives can be found in + include/linux/random.h + + One comment remains, there used to be an RNDGETPOOL ioctl() which + disappeared in v2.6.9. I found two patches on the net: + - http://www.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/2.6.8.1/2.6.8.1-mm4/broken-out/dev-random-remove-rndgetpool-ioctl.patch + - https://lkml.org/lkml/2004/3/25/168 + + But as far as I can tell the first one got applied but the 2nd + one seems more correct. The result is that even today one can + still find traces of the RNDGETPOOL ioctl() in the header files. + Is this there for historical reasons or because it might break + userspace, even though using it will just give an EINVAL. + +bootparam.7 + Jose Luis Domingo Lopez + Document 'rootfstype' option + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=182014 + +capabilities.7 + Michael Kerrisk + Add various pieces under CAP_SYS_RAWIO + Info obtained by grepping the kernel source. + Michael Kerrisk + Add CAP_SYS_RESOURCE /proc/PID/oom_score_adj case + +netlink.7 + Andrey Vagin + Add a note about broadcast messages to multiple groups + +socket.7 + Michael Kerrisk [Florian Weimer] + Define _GNU_SOURCE to obtain the definition of 'struct ucred' + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=572210 + + +==================== Changes in man-pages-3.51 ==================== + +Released: 2013-04-17, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andreas Jaeger +Andrew Clayton +Brian M. Carlson +Changhee Han +Cyril Hrubis +Damien Grassart +David Prévot +Denis Barbier +Jeff Moyer +Krzysztof Konopko +Kyle McMartin +Mark H Weaver +Michael Kerrisk +Mike Frysinger +Nicolas Hillegeer +Pavel Emelyanov +Peter Schiffer +Radek Pazdera +Ralph Loader +Simon Paillard +The Wanderer + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +sched_rr_get_interval.2 + Michael Kerrisk + Document /proc/sys/kernel/sched_rr_timeslice_ms + +proc.5 + Pavel Emelyanov + Document /proc/[pid]/map_files directory + This directory was added in Linux v3.3 and provides info about + files being mmap-ed in a way very similar to how /proc/[pid]/fd + works. + + v2: Added examples of how links look like and noted dependency + on kernel config option CONFIG_CHECKPOINT_RESTORE. + Michael Kerrisk + Document /proc/sys/kernel/shm_rmid_forced + +capabilities.7 + Michael Kerrisk + Document /proc/sys/kernel/cap_last_cap + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix: fix placement of word "only" + +Various pages + Simon Paillard + License headers: consistent format + +Various pages + Michael Kerrisk + Global fix: s/since kernel/since Linux/ + +Various System V IPC pages in Section 2 + Michael Kerrisk + Add "System V" to .TH line and text + Make it clear that these pages relate to System V IPC, + not POSIX IPC. + + +Changes to individual pages +--------------------------- + +access.2 + Michael Kerrisk [The Wanderer] + Clarify RETURN VALUE for F_OK + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=705293 + +alarm.2 + Michael Kerrisk + Correct the description of behavior when 'seconds' is 0 + +clone.2 + Michael Kerrisk [Peter Schiffer] + Add prototype for syscall to SYNOPSIS + And further clarify the distinction between the system call + and the wrapper function in the introductory text. + Michael Kerrisk + Update feature test macro requirements + The requirements quietly changed in glibc 2.14 + + See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749 + Michael Kerrisk [Mike Frysinger] + Clarify differences between clone2() syscall and wrapper function + Michael Kerrisk [Mike Frysinger] + Note those architectures where the sys_clone argument order differs + Michael Kerrisk [Mike Frysinger] + Add short subsection noting that blackfin, m68k, and sparc are different + Michael Kerrisk + Move clone2() text to subsection in description + The description of ia64 clone2() should follow the discussion + of the raw system call interface. + Michael Kerrisk + Change subhead for ia64 discussion + +getcpu.2 + Michael Kerrisk + Recommend that 'tcache' should be specified as NULL nowadays + +io_cancel.2 + Jeff Moyer, Michael Kerrisk [Cyril Hrubis] + Improve description + +io_destroy.2 + Jeff Moyer + Improve description + The description was rather vague, citing a "list of I/O contexts" + and stating that it "can" cancel outstanding requests. This + update makes things more concrete so that the reader knows exactly + what's going on. + +io_getevents.2 + Jeff Moyer + The 'timeout' argument is not updated + I looked back through the kernel code, and the timeout was + never updated in any case. I've submitted a patch upstream + to change the comment above io_getevents. + +io_setup.2 + Jeff Moyer + Clarify nr_events + nr_events is technically the number of completion events that can + be stored in the completion ring. The wording of the man page: + "capable of receiving at least nr_events" seems dubious to me, + only because I worry that folks might interpret that to mean + 'nr_events' total, instead of 'nr_events' concurrently. + + Further, I've added information on where to find the per-user + limit on 'nr_events', /proc/sys/fs/aio-max-nr. Let me know if + you think that is not relevant. + +listxattr.2 + Michael Kerrisk + Explain use of 'size' argument + +lseek.2 + Michael Kerrisk [Andreas Jaeger] + _GNU_SOURCE must be defined to get SEEK_DATA and SEEK_HOLE definitions + See http://sourceware.org/bugzilla/show_bug.cgi?id=15312 + +mmap.2 + Michael Kerrisk + Add pointers to relevant /proc files described in proc(5) + +posix_fadvise.2 +pread.2 +readahead.2 +sync_file_range.2 +truncate.2 + Michael Kerrisk + Refer to syscall(2) for ABI semantics on certain 32-bit architectures + Also: in sync_file_range.2 and posix_fadvise.2 remove description + of conventional calling signature as flawed, and in + posix_fadvise.2, de-emphasize focus on ARM, and rather phrase + as a more general discussion of certain architectures. + +readdir.2 + Michael Kerrisk + readdir(2) doesn't exist on x86-64 + +semop.2 + Michael Kerrisk + Clarify the discussion of 'semadj' + +shmctl.2 + Michael Kerrisk + Refer to proc(5) for description of /proc/sys/kernel/shm_rmid_forced + +syscall.2 + Changhee Han + Add notes that caution users when passing arguments to syscall() + For example, passing 'long long' on ARM-32 requires special + treatment. + Mike Frysinger [Michael Kerrisk] + Document the exact calling convention for architecture system calls + Mike Frysinger [Kyle McMartin] + Add PA-RISC details under calling conventions + Michael Kerrisk [Mike Frysinger] + Refine discussion of ARM and other ABIs + +syscalls.2 + Michael Kerrisk + Update kernel version number at start of list + +umask.2 + Michael Kerrisk + SEE ALSO: add acl(5) + +unshare.2 + Michael Kerrisk + Update feature test macro requirements + The requirements quietly changed in glibc 2.14 + + See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749 + +fopencookie.3 + Michael Kerrisk [Ralph Loader] + Correct definition of cookie_io_functions_t + +pthread_setname_np.3 + Andrew Clayton + The thread argument is passed in by value + +readir.3 +seekdir.3 +telldir.3 + Michael Kerrisk + Eliminate the implication that these functions deal with "offsets" + The directory position dealt with by the readdir() and + friends is not a simple file offset in modern file systems. + Typically, it is some kind of cookie value. Add text and + make other changes to these pages to eliminate the + implication that this is an offset, and warn the reader + that directory positions should be treated strictly as + opaque values. + + In the process, rename the 'offset' argument of seekdir(3) + to 'loc', and add some text to readdir(3) to note that + the 'd_off' field is the same value returned by telldir(3) + at the current directory position. + + See also https://lwn.net/Articles/544298/ + +scalb.3 + Mark H Weaver + Fix prototypes for scalbf() and scalbl() + +sched_getcpu.3 + Michael Kerrisk + Update feature test macro requirements + The requirements quietly changed in glibc 2.14 + + See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749 + +ualarm.3 + Michael Kerrisk [Nicolas Hillegeer] + Add note on the behavior when 'usecs' is zero + POSIX.1-2001 does not specify the behavior in this case + and no other system that I checked documented the behavior. + Probably, most or all systems do what Linux does in this + case: cancel any pending alarm, just as alarm(0) does. + Add that info in NOTES. + +elf.5 + Mike Frysinger + Add byte positions for all EI_xxx fields + When describing e_ident, most of the EI_xxx defines mention the + exact byte number. This is useful when manually hacking an ELF + with a hex editor. However, the last few fields don't do this, + which means you have to count things up yourself. + Add a single word to each so you don't have to do that. + +proc.5 + Michael Kerrisk + Refer to sched_rr_get_interval(2) for info on sched_rr_timeslice_ms + Since Linux 3.9, /proc/sys/kernel/sched_rr_timeslice_ms can + be used to change the SCHED_RR quantum. + Michael Kerrisk + SEE ALSO: Add sysctl(8) + Krzysztof Konopko + Simplify the example of printing out environ + The binutils package contains a very handy utility to + print out null-byte delimited strings from a file. This + can replace a rather complex expression with cat(1) + provided as an example for printing out /proc/[pid]/environ. + Michael Kerrisk + Update /proc/PID/maps example + Update to 64-bit example that includes "[heap]", "[stack], + and "[vdso]" + Michael Kerrisk + Formatting fixes for /proc/PID/maps + Mike Frysinger + Document the "pathname" field of /proc/PID/maps + Michael Kerrisk + Add reference to capabilities(7) for /proc/sys/kernel/cap_last_cap + Michael Kerrisk + /proc/PID/maps: add a reference to mmap(2) + +ip.7 + Radek Pazdera + Document IP_MULTICAST_ALL + This commit adds documentation for the IP_MULTICAST_ALL socket + option. + + The option was added to the Linux kernel in 2.6.31: + + Author Nivedita Singhvi + Commit f771bef98004d9d141b085d987a77d06669d4f4f + + The description is based on a previous one [3] posted by the + original author of the code -- Nivedita, but it is slightly + re-worded. + + I tested it myself and it works as described. + + References: + [1] http://lxr.free-electrons.com/source/net/ipv4/ip_sockglue.c#L972 + [2] http://lxr.free-electrons.com/source/net/ipv4/igmp.c#L2267 + [3] http://patchwork.ozlabs.org/patch/28902/ + +units.7 + Brian M. Carlson + units should use an actual µ + The units(7) man page uses an ASCII u in place of the actual Greek + letter mu. Since we're in the twenty-first century, with + UTF-8-compatible terminals and terminal emulators, we should use + the actual letter µ instead of an ASCII approximation. + + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=704787 + + +==================== Changes in man-pages-3.52 ==================== + +Released: 2013-07-04, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Adrian Bunk +Andrea Remondini +Anthony Foiani +Brian Norris +Cyril Hrubis +Dan Jacobson +David Prévot +Eric S. Raymond +Georg Sauthoff +Jeff Moyer +Jérémie Galarneau +Jon Grant +Manuel Traut +Марк Коренберг +Michael Kerrisk +Mike Frysinger +Pavel Emelyanov +Peng Haitao +Peter LaDow +Petr Gajdos +Regid +Siddhesh Poyarekar +Simone Piccardi +Simon Paillard +Vince Weaver +Yuri Kozlov + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +perf_event_open.2 + Vince Weaver + Add PERF_IOC_FLAG_GROUP documentation + The perf_event_open() ENABLE/DISABLE/RESET ioctls can take an + argument, PERF_IOC_FLAG_GROUP. This wasn't documented at all + until about a year ago (despite the support being there from + the beginning) so I missed this when initially writing + the man page. + +socket.7 + Pavel Emelyanov, Michael Kerrisk + Document SO_PEEK_OFF option + Since Linux 3.4 there appeared an ability to specify the + offset in bytes from which the data will be MSG_PEEK-ed. + Describe this socket option in the socket(7) page, where + all the other socket options are described. + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Convert inline formatting (\fX...\fP) to dot-directive formatting + +readdir.2 +asprintf. +getline.3 +getlogin.3 +pthread_setname_np.3 +readdir.3 +strerror.3 + Michael Kerrisk [Jon Grant] + Clarify that terminating null byte is '\0' + + +Changes to individual pages +--------------------------- + +execve.2 + Peter LaDow + Add envp to the Linux notes about NULL pointers + During the review of static analysis results, we discovered a + functional, but non-portable, use of execve(). For example: + + char *cmd[] = { "/path/to/some/file", NULL }; + execve(cmd[0], cmd, NULL); + + The call succeeds. Yet, the static analysis tool (rightly) + pointed out that envp could be dereferenced. But digging into + glibc and the kernel, it appears that like argv, envp when NULL + is treated as if it were an empty list. + + So, to clear things up, I'm submitting this patch to update the + man page to indicate that envp is treated like argv. + +fallocate.2 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +io_setup.2 + Cyril Hrubis [Jeff Moyer] + Clarify the nr_events parameter + Currently the io_setup.2 man page describes what the kernel really + does, i.e., that the resulting context may be able to hold more + than the 'nr_event's operations because the memory allocated in + kernel is rounded to be multiple of page size. + + It is better not to expose this implementation detail and + simply state that the resulting context is suitable for + 'nr_events' operations. + +perf_event_open.2 + Vince Weaver + Clarify the perf_event_open() wakeup_events/wakeup_watermark fields + Clarify the perf_event_open() wakeup_events/wakeup_watermark + fields a bit, based on info from kernel commit cfeb1d90a1b1. + Vince Weaver + Update to match the Linux 3.10 release + This patch updates the perf_event_open() documentation to include + new interfaces added in the 3.10 kernel. + + It also documents a few [To be documented] instances left over + from the 3.7 kernel. + Vince Weaver + Small correction to description of 'flags' argument + +prctl.2 + Michael Kerrisk + Note equivalents of PR_SET_NAME + pthread_setname_np() and pthread_getname_np() and + /proc/self/task/TID/comm provide access to the same + attribute. + +pread.2 + Michael Kerrisk [Марк Коренберг] + pread() and pwrite() are especially useful in multithreaded applications + +recv.2 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +semctl.2 + Michael Kerrisk [Simone Piccardi] + 'sem_nsems' is 'unsigned long' since Linux 2.4 + +shmget.2 + Michael Kerrisk + Rewrite RETURN VALUE and mention that 'errno' is set on error + +sigaction.2 + Michael Kerrisk [Brian Norris] + RETURN VALUE: mention that 'errno' is set on error + +signal.2 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +sigpending.2 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +sigprocmask.2 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +sigsuspend.2 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +syscall.2 + Mike Frysinger + Document s390/s390x calling convention + +a64l.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function l64a() is not thread safe. + +abs.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions abs(), labs(), llabs() and imaxabs() are + thread-safe. + +aio_error.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function aio_error() is thread safe. + +aio_return.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function aio_return() is thread safe. + +alloca.3 + Adrian Bunk + Correct information on getting non-inlined version with gcc+glibc + - remove the incorrect information that -fno-builtin would help + - add -std=c11 to the list of strict options + - emphasize more that both the gcc option and not including + alloca.h are needed + - add the #ifdef from the glibc alloca.h to make the situation + clearer + +bindresvport.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + Before glibc 2.17, bindresvport() is not thread-safe. + Since glibc 2.17, it is thread-safe, the patch can refer to URL: + http://sourceware.org/git/?p=glibc.git;a=commit;h=f6da27e53695ad1cc0e2a9490358decbbfdff5e5 + +canonicalize_file_name.3 + Michael Kerrisk + Put CONFORMING TO section in right location + +catgets.3 + Michael Kerrisk [Jon Grant] + Clarify that null byte is '\0' + +ceil.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions ceil(), ceilf() and ceill() are thread safe. + +cimag.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions cimag(), cimagf() and cimagl() are thread safe. + +clock_getcpuclockid.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function clock_getcpuclockid() is thread safe. + +conj.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions conj(), conjf() and conjl() are thread safe. + +crypt.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function crypt() is not thread safe. + +ctermid.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function ctermid() is thread safe with exceptions. + +dirfd.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +drand48.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions drand48(), erand48(), lrand48(), nrand48(), + mrand48(), jrand48(), srand48(), seed48() and lcong48() are + not thread safe. + +ecvt.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions ecvt() and fcvt() return a string located in a + static buffer which is overwritten by the next call to the + functions, so they are not thread-safe. + +encrypt.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions encrypt() and setkey() are not thread safe. + +ether_aton.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions ether_aton() and ether_ntoa() are not thread safe. + +fcloseall.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function fcloseall() is not thread safe. + +ferror.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions ferror(), clearerr(), feof() and fileno() are + thread safe. + +fgetgrent.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +fgetpwent.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +fgetwc.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +fmtmsg.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + Before glibc 2.16, fmtmsg() is not thread-safe. + Since glibc 2.16, it is thread-safe, the patch can refer to URL: + http://sourceware.org/git/?p=glibc.git;a=commit;h=7724defcf8873116fe4efab256596861eef21a94 + +fputwc.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +getdate.3 + Peng Haitao + ATTRIBUTES: Note functions that are and aren't thread-safe + +getgrent.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function getgrent() is not thread safe. + +getgrnam.3 + Peng Haitao + ATTRIBUTES: Note functions that are and aren't thread-safe + +getline.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +getlogin.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function getlogin() is not thread safe. + The function cuserid() is thread-safe with exceptions. + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +getpass.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + +getpwent.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function getpwent() is not thread safe. + +getpwnam.3 + Peng Haitao + ATTRIBUTES: Note functions that are and aren't thread-safe + +getspnam.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +getttyent.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + +getusershell.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions getusershell(), setusershell() and endusershell() + are not thread safe. + +getutent.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +hsearch.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +hsearch.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions hsearch(), hcreate() and hdestroy() are not + thread-safe. + +localeconv.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The function localeconv() returns a pointer to a structure which + might be overwritten by subsequent calls to localeconv() or by + calls to setlocale(), so it is not thread-safe. + Peng Haitao + Add RETURN VALUE section + +malloc_info.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +mblen.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function mblen() is not thread safe. + +mbrlen.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function mbrlen() is thread safe with exceptions. + +mbrtowc.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function mbrtowc() is thread safe with exceptions. + +mktemp.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +modf.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions modf(), modff() and modfl() are thread safe. + +popen.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +pthread_attr_setinheritsched.3 + Michael Kerrisk + Note the scheduling attributes affected by this function + +pthread_attr_setschedparam.3 +pthread_attr_setschedpolicy.3 +pthread_attr_setscope.3 + Michael Kerrisk [Manuel Traut, Siddhesh Poyarekar] + The inherit-scheduler attribute must be set to PTHREAD_EXPLICIT_SCHED + In order for the attributes set by these functions to have + an effect, the caller must use pthread_attr_setinheritsched(3) + to set the inherit-scheduler attribute of the attributes object + to PTHREAD_EXPLICIT_SCHED. + +ptsname.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function ptsname() is not thread safe. + +putenv.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +putpwent.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +qecvt.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions qecvt() and qfcvt() are not thread-safe. + +random.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + Michael Kerrisk + Add EINVAL error for setstate() + Michael Kerrisk + BUGS: initstate() does not return NULL on error + http://sourceware.org/bugzilla/show_bug.cgi?id=15380 + +random_r.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +readdir.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The data returned by readdir() may be overwritten by subsequent + calls to readdir() for the same directory stream, so it is not + thread-safe. + +re_comp.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions re_comp() and re_exec() are not thread safe. + +rexec.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions rexec() and rexec_af() are not thread safe. + +round.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions round(), roundf() and roundl() are thread safe. + +scalbln.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions scalbn(), scalbnf(), scalbnl(), scalbln(), + scalblnf() and scalblnl() are thread safe. + +scandir.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +siginterrupt.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +signbit.3 + Peng Haitao + ATTRIBUTES: Note macro that is thread-safe + The macro signbit() is thread safe. + +sigsetops.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +stdio_ext.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions __fbufsize(), __fpending(), __fpurge() and + __fsetlocking() are not thread safe. + +strdup.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +strerror.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function strerror() is not thread safe. + +strftime.3 + Michael Kerrisk + Clarify details of return value + Michael Kerrisk + BUGS: 'errno' is not set if the result string would exceed 'max' bytes + +strtok.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function strtok() is not thread safe. + Michael Kerrisk [Georg Sauthoff] + Add more detail on the operation of strtok() + Add a number of missing details on the operation of strtok() + +tempnam.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +timegm.3 + Jérémie Galarneau + copy the string returned by getenv() + The example of a portable version of timegm() uses the string + returned by getenv() after calling setenv() on the same + environment variable. The tz string may be invalid as per + getenv.3: + + "The string pointed to by the return value of getenv() + may be statically allocated, and can be modified by a + subsequent call to getenv(), putenv(3), setenv(3), or + unsetenv(3)." + +tmpnam.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function tmpnam() is thread safe with exceptions. + +trunc.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions trunc(), truncf() and truncl() are thread safe. + +ttyname.3 + Michael Kerrisk + ATTRIBUTES: Note functions that are and aren't thread-safe + +ttyslot.3 + Michael Kerrisk + ATTRIBUTES: Note functions that are not thread-safe + +usleep.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +wcsdup.3 + Michael Kerrisk + RETURN VALUE: mention that 'errno' is set on error + +core.5 + Michael Kerrisk + Implicitly adding the PID to a core filename was dropped in 2.6.27 + +proc.5 + Michael Kerrisk + Document /proc/[pid]/fd/ anon_inode symlinks + Mike Frysinger + Document /proc/[pid]/fd/ symlinks a bit more + Describe the type:[inode] syntax used in this dir + +bootparam.7 + Michael Kerrisk [Dan Jacobson] + Remove outdated text on LILO and LoadLin + Strike the discussion of LILO and LoadLin, which + are long obsolete, and make a brief mention of GRUB. + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=604019 + Regid + Remove mention of the deprecated rdev(8) + The deprecated rdev(8) command was removed from util-linux in 2010. + See https://git.kernel.org/?p=utils/util-linux/util-linux.git;a=commit;h=a3e40c14651fccf18e7954f081e601389baefe3fO + Andrea Remondini + Document the 'resume' boot parameter + +inotify.7 + Michael Kerrisk [Jon Grant] + Clarify that null byte is '\0' + +iso_8859-2.7 + Eric S. Raymond + Remove incorrect reference to nonexistent groff glyph \[shc] + The reference incorrectly attempted to duplicate an + actual soft hyphen (hex 0xad) just before it in the file. + +man-pages.7 + Peng Haitao + Add description of "ATTRIBUTES" + "ATTRIBUTES" section can mention thread safety, + cancellation safety, and async-cancel-safety. + +socket.7 + Michael Kerrisk + Note that 'optval' for socket options is an 'int' in most cases + +tcp.7 + Michael Kerrisk + Note that 'optval' for socket options is an 'int' in most cases + +udp.7 + Michael Kerrisk + Note that 'optval' for socket options is an 'int' in most cases + + +==================== Changes in man-pages-3.53 ==================== + +Released: 2013-07-31, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Al Viro +Andrey Vagin +Benjamin Poirier +Chris Heath +Chuck Coffing +David Prévot +Denys Vlasenko +Dmitry V. Levin +Felix Schulte +Graud +Michael Kerrisk +Oleg Nesterov +Peng Haitao +Peter Schiffer +Simon Paillard +Vince Weaver + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +restart_syscall.2 + Michael Kerrisk + New page for restart_syscall(2) system call + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fchownat.2 + Michael Kerrisk + Document AT_EMPTY_PATH + +fstatat.2 + Michael Kerrisk + Document AT_EMPTY_PATH + +linkat.2 + Michael Kerrisk + Document AT_EMPTY_PATH + +open.2 + Michael Kerrisk [Al Viro] + Document O_PATH + See also https://bugzilla.redhat.com/show_bug.cgi?id=885740 + + +Changes to individual pages +--------------------------- + +clock_nanosleep.2 +futex.2 +nanosleep.2 +poll.2 +sigaction.2 +sigreturn.2 +signal.7 + Michael Kerrisk + SEE ALSO: add restart_syscall(2) + +open.2 + Michael Kerrisk [Geoffrey Thomas] + Remove warning that O_DIRECTORY is only for use with opendir(3) + O_DIRECTORY can also be used with, for example, O_PATH. + +perf_event_open.2 + Vince Weaver + Improve PERF_SAMPLE_BRANCH_STACK documentation + Vince Weaver + Fix indentation of the MMAP layout section + The indentation of the MMAP layout section wasn't quite right. + I think this improves things but I admit I'm not an expert at the + low-level indentation directives. + Vince Weaver + Update PERF_IOC_FLAG_GROUP info + It turns out PERF_IOC_FLAG_GROUP was broken from 75f937f24bd9 + (in Linux 2.6.31, the initial perf_event release) until + 724b6daa1 (Linux 3.4). + + I've done some extensive kernel source code digging plus + running tests of various kernels and I hope the info + presented is accurate now. + + (Patch edited somewhat by mtk.) + Vince Weaver + Improve sysfs files documentation + This improves the documentation of the various + perf_event_open()-related sysfs files. + +ptrace.2 + Denys Vlasenko [Oleg Nesterov, Dmitry V. Levin] + If SEIZE was used, initial auto-attach stop is EVENT_STOP + For every PTRACE_O_TRACEfoo option, mention that old-style SIGSTOP + is replaced by PTRACE_EVENT_STOP if PTRACE_SEIZE attach was used. + + Mention the same thing again in the description of + PTRACE_EVENT_STOP. + Denys Vlasenko [Oleg Nesterov, Dmitry V. Levin] + Mention that PTRACE_PEEK* libc API and kernel API are different + Denys Vlasenko [Oleg Nesterov, Dmitry V. Levin] + Clarify PTRACE_INTERRUPT, PTRACE_LISTEN, and group-stop behavior + +readlink.2 + Michael Kerrisk + Document use of empty 'pathname' argument + Michael Kerrisk + Change error check in example program from "< 0" to "== -1" + Chuck Coffing + Fix possible race condition in readlink.2 example + I noticed that the example in the readlink.2 man pages does error + checking for a race condition that would cause the value of the + symbolic link to get larger. However, it doesn't handle the + opposite case, in which the value gets shorter. (The NULL + terminator is always set at the old, longer offset.) This could + cause the program to operate on uninitialized data. + +setpgid.2 + Michael Kerrisk [Graud] + s/SIGTSTP/SIGTTIN/ when discussing reads from terminal + See https://bugzilla.kernel.org/show_bug.cgi?id=60504 + +clog2.3 + Michael Kerrisk + Note that these functions are still not present in glibc 2.17 + +dirfd.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function dirfd() is thread safe. + +div.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions div(), ldiv(), lldiv() and imaxdiv() are thread + safe. + +fabs.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions fabs(), fabsf() and fabsl() are thread safe. + +fdim.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions fdim(), fdimf() and fdiml() are thread safe. + +fflush.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function fflush() is thread safe. + +finite.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions finite(), finitef(), finitel(), isinf(), isinff(), + isinfl(), isnan(), isnanf() and isnanl() are thread safe. + +flockfile.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions flockfile(), ftrylockfile() and funlockfile() are + thread safe. + +floor.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions floor(), floorf() and floorl() are thread safe. + +resolv.conf.5 + Simon Paillard + Explain how to set empty domain + See http://bugs.debian.org/463575 + +capabilities.7 + Michael Kerrisk + Add open_by_handle_at(2) under CAP_DAC_READ_SEARCH + +inotify.7 + Michael Kerrisk [Felix Schulte] + Clarify description of IN_MOVED_FROM and IN_MOVED_TO + +man-pages.7 + Michael Kerrisk + DESCRIPTION should note versions for new interface features or behavior + +udp.7 + Benjamin Poirier + Add missing #include directive + Using the UDP_CORK socket option documented in udp.7 requires + including . + +ld.so.8 + Michael Kerrisk + Rework rpath token expansion text + Michael Kerrisk + Describe $PLATFORM rpath token + Michael Kerrisk + Describe $LIB rpath token + Michael Kerrisk + Document LD_BIND_NOT + Michael Kerrisk [Simon Paillard] + Add reference to pthreads(7) in discussion of LD_ASSUME_KERNEL + + +==================== Changes in man-pages-3.54 ==================== + +Released: 2013-09-17, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +A. Costa +Akihiro MOTOKI +Andreas Wiese +Andrew Hunter +Chen Gang +Christopher Hall +Christos Tsopokis +David Prévot +D. Barbier +Doug Goldstein +Elie De Brauwer +Eugen Dedu +Felix Janda +G.raud +Hannes Landeholm +J. Bruce Fields +J. Bruce Fields +Johan Erlandsson +Jon Grant +Magnus Reftel +Marko Myllynen +Michael Kerrisk +Oleg Nesterov +Peng Haitao +Peter Schiffer +Robert Harris +Rodrigo Campos +Simon Paillard +Stas +Vince Weaver +Will Newton +Zdenek Pavlas +Zsbán Ambrus + +Apologies if I missed anyone! + + + +Newly documented interfaces in existing pages +--------------------------------------------- + +ioctl_list.2 + Zsbán Ambrus + Document FAT_IOCTL_GET_ATTRIBUTES + The attached patch adds four ioctls from linux/msdos_fs.h to the + ioctl_list(2) manpage. + + The ioctl FAT_IOCTL_GET_ATTRIBUTES reads FAT attributes of a + file a mounted vfat file system. I tested this on Linux + 2.6.33, an example script can be found at + http://www.perlmonks.com/?node_id=832623 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix: s/file system/filesystem/ + Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c, + "filesystem" is the form used by the great majority of man pages + outside the man-pages project and in a number of other sources, + so let's go with that. + + +Changes to individual pages +--------------------------- + +access.2 + J. Bruce Fields + Fix outdated NFS information + Note that NFS versions since version 3 support an "access" call + so that the client doesn't have to guess permissions or ID + mapping on its own. + + (See RFC 1813 sections 1.7 and 3.3.4.) + +adjtimex.2 + Michael Kerrisk + SEE ALSO: Add adjtimex(8) + +clock_getres.2 + Michael Kerrisk [Rodrigo Campos] + Note circumstances in which "SMP" note applies. + Michael Kerrisk + Add kernel version for CLOCK_*_CPUTIME_ID + CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID + appeared in 2.6.12. + Michael Kerrisk + Add VERSIONS section + +futex.2 + Michael Kerrisk + The 'timeout' can be rounded upwards by clock granularity and also overrun + +kill.2 + Michael Kerrisk + Small improvements to text on historical rules for permissions + +nfsservctl.2 + Michael Kerrisk + Note commands that were only in Linux 2.4.x and earlier + +open.2 + Robert Harris + Add mmap(2) to list of calls that fail when given an O_PATH descriptor + Doug Goldstein + Add EINVAL to errors list + EINVAL can be returned by open(2) when the underlying filesystem + doesn't support O_DIRECT. It is documented in the NOTES section + but this patch adds it to the list of possible errors. + +perf_event_open.2 + Vince Weaver + PERF_SAMPLE_BRANCH_STACK updates + This started out as just adding the new perf_event_open features + from Linux 3.11 (which was the addition of transactional memory + defines for PERF_SAMPLE_BRANCH_STACK samples) but turned into a + general cleanup of the PERF_SAMPLE_BRANCH_STACK documentation. + + The main clarification is that at least one of the non-privilege + values must be set or else perf_event_open() will return an EINVAL + error. + Michael Kerrisk + Reorder text describing fields of 'perf_event_header' structure + Place the fields with the shorter descriptions first, to make the + information easier to read. + +poll.2 + Michael Kerrisk + Clarify wording of 'timeout' as a "minimum" interval + +sched_setaffinity.2 + Michael Kerrisk [Christos Tsopokis] + Clarify that these system calls affect a per-thread attribute + +sched_setparam.2 + Michael Kerrisk + Clarify that this system call applies to threads (not processes) + +sched_setscheduler.2 + Michael Kerrisk + Clarify that this system call applies to threads (not processes) + +select.2 + Michael Kerrisk [G.raud] + Clarify wording of 'timeout' as a "minimum" interval + +setfsgid.2 + Michael Kerrisk [Oleg Nesterov] + Clarify description of return value + More clearly describe the weirdness in the return value of this + system call, and note the problems it creates in BUGS + Michael Kerrisk + Correct header file in SYNOPSIS + Michael Kerrisk + Refer to setfsuid(2) for an explanation of why setfsgid() is obsolete + Michael Kerrisk + Wording improvements + +setfsuid.2 + Michael Kerrisk [Oleg Nesterov] + Clarify description of return value + More clearly describe the weirdness in the return value of this + system call, and note the problems it creates in BUGS + Michael Kerrisk [Chen Gang] + Clarify historical details and note that setfsuid() is obsolete + Michael Kerrisk + Wording improvements + Michael Kerrisk + Correct header file in SYNOPSIS + +sigwaitinfo.2 + Michael Kerrisk + Clarify wording of 'timeout' as a "minimum" interval + +syscall.2 + Johan Erlandsson + Add missing argument in example + Johan Erlandsson + Correct registers for arm/EABI + Registers was off by one. + + Reference: + http://www.arm.linux.org.uk/developer/patches/viewpatch.php?id=3105/4 + + See also: + http://peterdn.com/post/e28098Hello-World!e28099-in-ARM-assembly.aspx + https://wiki.debian.org/ArmEabiPort + http://en.wikipedia.org/wiki/Calling_convention#ARM + +wait.2 + Michael Kerrisk [Hannes Landeholm] + Add details on the fifth argument provided by raw waitid() system call + See https://bugzilla.kernel.org/show_bug.cgi?id=60744 + +clock.3 + Michael Kerrisk + clock() switched from using times(2) to clock_gettime() in glibc 2.18 + +drand48_r.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions drand48_r(), erand48_r(), lrand48_r(), + nrand48_r(), mrand48_r(), jrand48_r(), srand48_r(), seed48_r(), + and lcong48_r() are thread safe. + +fma.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions fma(), fmaf() and fmal() are thread safe. + +fmax.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions fmax(), fmaxf() and fmaxl() are thread safe. + +fmin.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions fmin(), fminf() and fminl() are thread safe. + +fpclassify.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions fpclassify(), isfinite(), isnormal(), isnan(), and + isinf() are thread safe. + +frexp.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions frexp(), frexpf() and frexpl() are thread safe. + +gethostbyname.3 + Michael Kerrisk [Jon Grant] + gai_strerror() is the modern replacement for herror() and hstrerror() + Michael Kerrisk + Update feature test macro requirements for herror() and hstrerror() + Michael Kerrisk + Add feature test macro requirements for h_errno + +ilogb.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions ilogb(), ilogbf() and ilogbl() are thread safe. + +ldexp.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions ldexp(), ldexpf() and ldexpl() are thread safe. + +lrint.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions lrint(), lrintf(), lrintl(), llrint(), llrintf(), + and llrintl() are thread safe. + +lround.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions lround(), lroundf(), lroundl(), llround(), + llroundf() and llroundl() are thread safe. + +lseek64.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function lseek64() is thread safe. + +mbsinit.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function mbsinit() is thread safe. + +nextafter.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions nextafter(), nextafterf(), nextafterl(), + nexttoward(), nexttowardf() and nexttowardl() are thread safe. + +posix_memalign.3 + Michael Kerrisk [Will Newton] + 'errno" is indeterminate after a call to posix_memalign() + Michael Kerrisk [Will Newton] + Clarify wording on "return value" when size==0 + +printf.3 + Christopher Hall + Correctly describe the meaning of a negative precision + The printf(3) manpage says that a negative precision is taken to + be zero, whereas printf(3p) says that a negative precision is + taken as if the precision were omitted. glibc agrees with the + latter (POSIX) specification. + + Test code: + + printf("%f\n",42.0); // "42.000000" + printf("%.*f\n",0,42.0); // "42" + printf("%.*f\n",-1,42.0); // "42.000000" + + This patch corrects the explanation to match what actually happens. + +rewinddir.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function rewinddir() is thread safe. + +rint.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions nearbyint(), nearbyintf(), nearbyintl(), rint(), + rintf() and rintl() are thread safe. + +seekdir.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function seekdir() is thread safe. + +telldir.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function telldir() is thread safe. + +wctomb.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function wctomb() is not thread safe. + +wavelan.4 + Michael Kerrisk [Elie De Brauwer] + This driver disappeared in 2.56.35 + +dir_colors.5 + Michael Kerrisk [Stas] + Add various synonyms + See http://bugs.debian.org/553477 + Simon Paillard [Stas] + Add keywords SUID, SGID, STICKY, STICKY_OTHER_WRITABLE, OTHER_WRITABLE + See http://bugs.debian.org/553477 + See ls.c and dircolors.c in coreutils + +proc.5 + Peter Schiffer + Document /proc/[pid]/io file + Attempt to document fields in the /proc/[pid]/io file, based on + the Documentation/filesystems/proc.txt. The text will probably + need some grammar corrections. + Michael Kerrisk [Marko Myllynen] + /proc/sys/fs/inode-max went away in Linux 2.4 + Also, the 'preshrink' field in /proc/sys/fs/inode-state became + a dummy value in Linux 2.4. + + See https://bugzilla.kernel.org/show_bug.cgi?id=60836 + Michael Kerrisk [A. Costa] + Note block size used by /proc/partitions + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=666972 + Michael Kerrisk + Add rationale on drop_caches and note that it can hurt performance + See also http://lwn.net/Articles/562211/ + +bootparam.7 + Michael Kerrisk [Eugen Dedu] + Remove "lilo" entries from SEE ALSO + See http://bugs.debian.org/604019 + +inotify.7 + Michael Kerrisk + SEE ALSO: add inotifywait(1) and inotifywatch(1) + +ip.7 + Simon Paillard + IP_MULTICAST_IF setsockopt recognizes struct mreq (compatibility) + Kernel added compatibility only recently in + 3a084ddb4bf299a6e898a9a07c89f3917f0713f7 + See: http://bugs.debian.org/607979 + +standards.7 + Michael Kerrisk + Add mention of SUSv4-TC1 (POSIX.1-2013) + + +==================== Changes in man-pages-3.55 ==================== + +Released: 2013-12-12, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alfred Agrell +Andreas Sandberg +Christoph Hellwig +David Gibson +David Prévot +Fabrice Bauzac +Greg Price +Jon Grant +KOSAKI Motohiro +Liu Jiaming +Maxin B. John +Michael Kerrisk +Paolo Bonzini +Peng Haitao +Robert P. J. Day +Rodrigo Campos +Shawn Landden +Trevor Bramwell +Vince Weaver +Yang Yang +Yuanhang Zheng +Yuri Kozlov +janh + +Apologies if I missed anyone! + + +Global changes +-------------- + +assert.3 +assert_perror.3 +rexec.3 +rpc.3 + Michael Kerrisk [Jon Grant] + Reword a sentence to use more gender-neutral language + + +Changes to individual pages +--------------------------- + +execve.2 + Michael Kerrisk + 'arg...' for interpreter scripts starts with argv[1] + +fallocate.2 + Christoph Hellwig + Clarify the zeroing behavior + fallocate() zeroes only space that did not previously contain + data, but leaves existing data untouched. + +futex.2 + Rodrigo Campos + Fix link to Rusty's futex example library + When I asked to webmaster@kernel.org, Konstantin Ryabitsev + answered that the ".nl." is "an obsolete scheme and really + should be changed to just ftp.kernel.org". + +getgroups.2 + Michael Kerrisk + Note that NGROUPS_MAX is defined in + Michael Kerrisk + Clarify that sysconf(_SC_NGROUPS_MAX) is a run-time technique + Michael Kerrisk + Document /proc/sys/kernel/ngroups_max + +ioctl.2 + Michael Kerrisk [KOSAKI Motohiro, David Gibson] + 'request' argument is typed as 'unsigned long' in glibc + See https://bugzilla.kernel.org/show_bug.cgi?id=42705 + +perf_event_open.2 + Vince Weaver + Linux 3.12 rdpmc/mmap + It turns out that the perf_event mmap page rdpmc/time setting was + broken, dating back to the introduction of the feature. Due + to a mistake with a bitfield, two different values mapped to + the same feature bit. + + A new somewhat backwards compatible interface was introduced + in Linux 3.12. A much longer report on the issue can be found + here: + https://lwn.net/Articles/567894/ + Vince Weaver + Linux 3.12 adds PERF_SAMPLE_IDENTIFIER + A new PERF_SAMPLE_IDENTIFIER sample type was added in Linux 3.12. + Vince Weaver + E2BIG documentation + The following documents the E2BIG error return for + perf_event_open(). + + I actually ran into this error the hard way and it took me + half a day to figure out why my ->size value was changing. + Vince Weaver + Linux 3.12 adds PERF_EVENT_IOC_ID + A new perf_event related ioctl, PERF_EVENT_IOC_ID, was added + in Linux 3.12. + Vince Weaver + PERF_COUNT_SW_DUMMY support + Support for the PERF_COUNT_SW_DUMMY event type was added in + Linux 3.12. + Vince Weaver [Andreas Sandberg] + PERF_EVENT_IOC_PERIOD update + The PERF_EVENT_IOC_PERIOD ioctl was broken until 2.6.36, + and it turns out that the ARM architecture has some + differing behavior too. + +pipe.2 + Trevor Bramwell + Fix error in example program + +poll.2 + Michael Kerrisk [Paolo Bonzini] + Clarify meaning of events==0 + events==0 does not mean that revents is always returned as + zero. The "output only" events (POLLHUP, POLLERR, POLLNVAL) + can still be returned. + + See https://bugzilla.kernel.org/show_bug.cgi?id=61911 + +readlink.2 + Michael Kerrisk [Yuanhang Zheng] + Fix typo in error message in example program + +recv.2 + Michael Kerrisk + Remove out-of-date statement that UNIX domain does not support MSG_TRUNC + Should have removed that sentence as part of + commit a25601b48b822eb1882ae336574b8d062a17e564 + +sched_get_priority_max.2 + Michael Kerrisk + Add SCHED_IDLE to discussion + +send.2 + Michael Kerrisk + RETURN VALUE: these calls return number of bytes (not characters) sent + +setreuid.2 + Michael Kerrisk + Small clarification to description of when saved set-user-ID is set + +sigpending.2 + Michael Kerrisk + Note treatment of signals that are blocked *and* ignored + +stat.2 + Michael Kerrisk + Note filesystem support for nanosecond timestamps + Add some detail on which native filesystems do and don't + support nanosecond timestamps. + Michael Kerrisk + Cosmetic reworking of timestamp discussion in NOTES + Michael Kerrisk [Yang Yang] + Update discussion of nanosecond timestamps + The existing text describes the timestamp fields as 'time_t' + and delegates discussion of nanosecond timestamps under NOTES. + Nanosecond timestamps have been around for a while now, + and are in POSIX.1-2008, so reverse the orientation of the + discussion, putting the nanosecond fields into DESCRIPTION + and detailing the historical situation under NOTES. + +symlink.2 + Michael Kerrisk + Further fine tuning of argument names + Follow-up to f2ae6dde0c68448bec986d12fe32268a2c98bfd9 + See https://sourceware.org/bugzilla/show_bug.cgi?id=16073 + Michael Kerrisk [Fabrice Bauzac] + Give arguments of symlink() more meaningful names + +adjtime.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function adjtime() is thread safe. + +alloca.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function alloca() is thread safe. + +asinh.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions asinh(), asinhf() and asinhl() are thread safe. + +atan.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions atan(), atanf() and atanl() are thread safe. + +atof.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function atof() is thread safe with exceptions. + +atoi.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions atoi(), atol() and atoll() are thread safe with + exceptions. + +bcmp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function bcmp() is thread safe. + +bcopy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function bcopy() is thread safe. + +bsd_signal.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function bsd_signal() is thread safe. + +bzero.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function bzero() is thread safe. + +cbrt.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions cbrt(), cbrtf() and cbrtl() are thread safe. + +copysign.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions copysign(), copysignf() and copysignl() are thread + safe. + +cos.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions cos(), cosf() and cosl() are thread safe. + +cproj.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions cproj(), cprojf() and cprojl() are thread safe. + +creal.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions creal(), crealf() and creall() are thread safe. + +daemon.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function daemon() is thread safe. + +des_crypt.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions ecb_crypt(), cbc_crypt() and des_setparity() are + thread safe. + +difftime.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function difftime() is thread safe. + +dysize.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function dysize() is thread safe. + +erf.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions erf(), erff() and erfl() are thread safe. + +erfc.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions erfc(), erfcf() and erfcl() are thread safe. + +euidaccess.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions euidaccess() and eaccess() are thread safe. + +expm1.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions expm1(), expm1f() and expm1l() are thread safe. + +fexecve.3 + Michael Kerrisk + POSIX.1-2008 specifies fexecve() + Michael Kerrisk + Explain the use and rationale of fexecve() + +ftime.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function ftime() is thread safe. + +ftok.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function ftok() is thread safe. + +ftw.3 + Michael Kerrisk + nftw() visits directories with FTW_D if FTW_DEPTH was not specified + Michael Kerrisk + Explain probable cause of FTW_NS + +futimes.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions futimes() and lutimes() are thread safe. + +getaddrinfo.3 + Michael Kerrisk + Explain one use case for AI_ADDRCONFIG + Michael Kerrisk + Highlight difference in ai_flags when hints==NULL + NOTES already described how glibc differs from POSIX. + Add a pointer to that text from the point in DESCRIPTION + where hints==NULL is discussed. + +kcmp.3 + Shawn Landden + Reword slightly awkward section + +malloc.3 + Greg Price + Scale back promises of alignment + It's not true that the return value is suitably aligned for "any + variable"; for example, it's unsuitable for a variable like + float *x __attribute__ ((__vector_size__ (32))); + which requires 32-byte alignment. Types like this are defined in + , and with 16-byte alignment in and + , so the application programmer need not even know + that a vector_size attribute has been applied. + + On an x86 architecture, a program that loads from or stores to a + pointer with this type derived from malloc can crash because GCC + generates an aligned load/store, like MOVDQA. + + The C99 standard (TC3, as of N1256) does say the return value is + suitably aligned for "any type of object". The C11 standard (as + of N1570) revises this to any type with "fundamental alignment", + which means an alignment "supported by the implementation in all + contexts", which I suppose tautologically includes aligning + malloc/realloc return values. + + The actual behavior of current glibc malloc is to align to the + greater of 2 * sizeof(size_t) and __alignof__ (long double), + which may be one bit greater than this commit promises. + +mq_receive.3 + Michael Kerrisk [janh] + msg_len must be greater than *or equal to* mq_msgsize + See https://bugzilla.kernel.org/show_bug.cgi?id=64571 + +setenv.3 + Michael Kerrisk + Clarify that setenv() returns success in the overwrite==0 case + +sigsetops.3 + Michael Kerrisk [Robert P. J. Day] + Add 'const' to sigisemptyset(), sigorset(), sigandset() declarations + Michael Kerrisk + Rework text describing sigisemptyset(), sigorset(), and sigandset() + +statvfs.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions statvfs() and fstatvfs() are thread safe. + +stdarg.3 + Peng Haitao + ATTRIBUTES: Note macros that are thread-safe + The macros va_start(), va_arg(), va_end() and va_copy() are + thread safe. + +termios.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions tcgetattr(), tcsetattr(), tcsendbreak(), + tcdrain(), tcflush(), tcflow(), cfmakeraw(), cfgetispeed(), + cfgetospeed(), cfsetispeed(), cfsetospeed() and cfsetspeed() + are thread safe. + +ungetwc.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function ungetwc() is thread safe. + +unlockpt.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function unlockpt() is thread safe. + +usleep.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function usleep() is thread safe. + +wcpcpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcpcpy() is thread safe. + +wcscasecmp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function wcscasecmp() is thread safe with exceptions. + +wcscat.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcscat() is thread safe. + +wcschr.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcschr() is thread safe. + +wcscmp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcscmp() is thread safe. + +wcscpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcscpy() is thread safe. + +wcscspn.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcscspn() is thread safe. + +wcslen.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcslen() is thread safe. + +wcsncasecmp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function wcsncasecmp() is thread safe with exceptions. + +wcsncat.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcsncat() is thread safe. + +wcsncmp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcsncmp() is thread safe. + +wcsncpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcsncpy() is thread safe. + +wcsnlen.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcsnlen() is thread safe. + +wcspbrk.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcspbrk() is thread safe. + +wcsrchr.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcsrchr() is thread safe. + +wcsspn.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcsspn() is thread safe. + +wcsstr.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcsstr() is thread safe. + +wcstoimax.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions wcstoimax() and wcstoumax() are thread safe with + exceptions. + +wcstok.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcstok() is thread safe. + +wcswidth.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function wcswidth() is thread safe with exceptions. + +wctrans.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function wctrans() is thread safe with exceptions. + +wctype.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function wctype() is thread safe with exceptions. + +wcwidth.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function wcwidth() is thread safe with exceptions. + +wmemchr.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wmemchr() is thread safe. + +wmemcmp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wmemcmp() is thread safe. + +wmemcpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wmemcpy() is thread safe. + +wmemmove.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wmemmove() is thread safe. + +wmemset.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wmemset() is thread safe. + +tty_ioctl.4 + Michael Kerrisk [Liu Jiaming] + Note that 'arg' should be 0 in the usual case when using TIOCSCTTY + Michael Kerrisk + Rework text on root to discuss just in terms of capabilities + +proc.5 + Michael Kerrisk + Document /proc/sys/kernel/ngroups_max + +capabilities.7 + Michael Kerrisk + Fix 2 version numbers under "Effect of user ID changes on capabilities" + +feature_test_macros.7 + Michael Kerrisk + Add _ISOC11_SOURCE to example program + +tcp.7 + Michael Kerrisk + Fix (nontrivial) wordo in discussion of MSG_TRUNC + s/MSG_PEEK/MSG_TRUNC/ + +ld.so.8 + Michael Kerrisk [Alfred Agrell] + Fix crufty wording in one sentence + + +==================== Changes in man-pages-3.56 ==================== + +Released: 2014-01-11, Christchurch + +In memory of Doris Church (1939-2013) + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andre Majorel +Arif Zaman +Bert Wesarg +Daniel Borkmann +David Malcolm +David Prévot +Dongsheng Song +Elie De Brauwer +James Smith +Janne Blomqvist +Joseph S. Myers +Luke Hutchison +Marco Dione +Mathieu Desnoyers +Mathieu Malaterre +Matthias Klose +Michael Kerrisk +Mike Frysinger +Moritz 'Morty' Strübe +Nadav Har'El +Ondřej Bílka +Prádraig Brady +Peng Haitao +Raphael Geissert +Shawn Landden +Simon Paillard +Stephen Kell +Sudhanshu Goswami +Sworddragon2 +Vince Weaver +Willem de Bruijn +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +fgetc.3 +gets.3 + David Malcolm + Split gets(3) to isolate unsafe gets(3) to a page on its own + Currently man3/gets.3 documents various safe I/O functions, along + with the toxic "gets" function. + + At the risk of being melodramatic, this strikes me as akin to + storing rat poison in a food cabinet, in the same style of + packaging as the food, but with a post-it note on it saying + "see warnings below". + + I think such "never use this" functions should be quarantined + into their own manpages, rather than listing them alongside + sane functions. + + The attached patch does this for "gets", moving the documentation + of the good functions from man3/gets.3 into man3/fgetc.3, + updating the SO links in the relevant functions to point at the + latter. + + It then rewrites man3/gets.3 to spell out that "gets" is toxic + and should never be used (with a link to CWE-242 for good + measure). + Michael Kerrisk [Andre Majorel] + Tweaks to David Malcolm's patch + +vdso.7 + Mike Frysinger + New page documenting the vDSO mapped into each process by the kernel + + +Newly documented interfaces in existing pages +--------------------------------------------- + +reboot.2 + Elie De Brauwer + Document LINUX_REBOOT_SW_SUSPEND + + +New and changed links +--------------------- + +fgets.3 +getc.3 +getchar.3 +ungetc.3 + Michael Kerrisk + Adjust links to gets(3) to point to fgetc(3) + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global fix of "NULL pointer" + Change "NULL pointer" to "NULL" or null pointer". + POSIX uses the term "null pointer", not "NULL pointer". + +Various pages + Michael Kerrisk + Stylistic changes to code example + For ease of reading, don't embed assignments inside if(). + +Various pages + Michael Kerrisk + Replace uses of "i.e.," in main text with "that is" or similar + Usual man-pages style is to use "i.e." only within + parenthetical expressions. + +Various pages + Michael Kerrisk + Replace uses of "e.g." in main text with "for example" or similar + Usual man-pages style is to use "e.g." only within + parenthetical expressions. + +Various pages + Michael Kerrisk + Add "Program source" subheading under EXAMPLE + +Various pages + Michael Kerrisk + Add "static" to global variables and functions in example program + + +Changes to individual pages +--------------------------- + +clock_getres.2 + Michael Kerrisk [Nadav Har'El] + Improve description of CLOCK_PROCESS_CPUTIME_ID + See https://bugzilla.kernel.org/show_bug.cgi?id=67291 + +close.2 + Michael Kerrisk [P?draig Brady] + Note that errors from close() should be used only for diagnosis + In particular, retrying after EINTR is a bad idea. + + See http://austingroupbugs.net/view.php?id=529 + + See http://thread.gmane.org/gmane.comp.lib.glibc.alpha/37702 + Subject: [RFC][BZ #14627] Make linux close errno to EINPROGRESS + when interrupted in signal. + +execve.2 + Michael Kerrisk [Marco Dione] + Add further cases to EFAULT error + See https://sourceware.org/bugzilla/show_bug.cgi?id=16402 + +perf_event_open.2 + Vince Weaver [Sudhanshu Goswami] + Clarify issues with the disabled bit + Clarify the perf_event_open behavior with respect to the disabled + bit and creating event groups. + Vince Weaver [Sudhanshu Goswami] + Clarify issues with the exclusive bit + Warn that using the perf_event_open "exclusive" bit, while + it might seem like a good idea, might lead to all 0 results + in some common usage cases. + +reboot.2 + Elie De Brauwer + Mention RB_POWER_OFF + The manpage did not mention RB_POWER_OFF which is the glibc + symbolic name for LINUX_REBOOT_CMD_POWER_OFF. + + $ cd /usr/include + $ cat x86_64-linux-gnu/sys/reboot.h | grep POWER_OFF + define RB_POWER_OFF 0x4321fedc + Elie De Brauwer + Add "Linux" to kernel version numbers + Michael Kerrisk + Add RB_SW_SUSPEND synonym + Michael Kerrisk + Add RB_KEXEC synonym + +setpgid.2 + Michael Kerrisk [Joseph S. Myers] + BSD getpgrp() and setpgrp() go away in glibc 2.19 + +socket.2 + Michael Kerrisk [Dongsheng Song] + Remove crufty statement that AF_INET does not support SOCK_SEQPACKET + Linux AF_INET supports SOCK_SEQPACKET via SCTP. + +syscall.2 + Mike Frysinger + Fix ia64 registers + The original list of registers was created by confusing strace + source code--this is for parsing legacy 32-bit code (which is + dead and no one cares). Update the list to reflect native ia64 + syscall interface. + +syscall.2 +syscalls.2 +getauxval.3 + Mike Frysinger + Add references to new vdso(7) page + +utimensat.2 + Michael Kerrisk + Small wording improvement for times!=NULL case + +dlopen.3 + Michael Kerrisk [Mike Frysinger] + Update remarks on cast needed when assigning dlsym() return value + POSIX.1-2013 eases life when casting the dlsym() return value to a + function pointer + Michael Kerrisk [Stephen Kell] + Fix description of dli_sname + See https://sourceware.org/bugzilla/show_bug.cgi?id=16262 + +getline.3 + Michael Kerrisk [Luke Hutchison] + Correct description of how '*n' is used when '*lineptr' == NULL + See https://sourceware.org/bugzilla/show_bug.cgi?id=5468 + Michael Kerrisk + Remove SEE ALSO reference to unsafe gets(3) + +mcheck.3 + Simon Paillard [Raphael Geissert] + typo in compiler flag + See http://bugs.debian.org/732464 + +mkstemp.3 + Michael Kerrisk [Janne Blomqvist] + Better describe 'flags' that can be specified for mkostemp() + +printf.3 + Michael Kerrisk [Arif Zaman] + Fix memory leak in snprintf() example + See http://stackoverflow.com/questions/19933479/snprintf-man-page-example-memory-leak + +pthread_kill.3 + Michael Kerrisk [Mathieu Desnoyers] + POSIX.1-2008 removes ESRCH + POSIX.1-2001 mistakenly documented an ESRCH error, and + POSIX.1-2008 removes this error. Glibc does return + this error in cases where it can determine that a thread ID + is invalid, but equally, the use of an invalid thread ID + can cause a segmentation fault. + +puts.3 + Michael Kerrisk + SEE ALSO: replace reference to gets(3) with fgets(3) + +scanf.3 + Michael Kerrisk [Ondřej Bílka] + Improve discussion of obsolete 'a' dynamic allocation modifier + +setjmp.3 + Michael Kerrisk [Joseph S. Myers] + BSD setjmp() semantics go away in glibc 2.19 + +sigpause.3 + Michael Kerrisk [Joseph S. Myers] + BSD sigpause() goes away in glibc 2.19 + Michael Kerrisk + Correct feature text macro requirements + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sigpause() is thread safe. + +sigqueue.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sigqueue() is thread safe. + +sigwait.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sigwait() is thread safe. + +sin.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions sin(), sinf() and sinl() are thread safe. + +sincos.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions sincos(), sincosf() and sincosl() are thread safe. + +string.3 + Moritz 'Morty' Strübe + Add short description of the functions + It is helpful to have a short description about what the different + functions in string.h do. + Michael Kerrisk + Fixes and enhancements to Moritz Strübe's patch + +strptime.3 + Michael Kerrisk [Mathieu Malaterre, Simon Paillard] + Add number ranges to comments in 'tm' structure + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=729570 + Michael Kerrisk + Point to ctime(3) for more details on 'tm' structure + Michael Kerrisk + Some rewording and reorganization + +strsep.3 + Michael Kerrisk + Clarify description + The use of "symbols" in the existing description is confusing; + it's "bytes". Other fixes as well. + +strspn.3 + Michael Kerrisk [Mathieu Malaterre] + Improve description in NAME + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=723659 + +strstr.3 + Michael Kerrisk + Clarify RETURN VALUE: s/substring/located substring/ + +sysv_signal.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sysv_signal() is thread safe. + +tan.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions tan(), tanf() and tanl() are thread safe. + +tanh.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions tanh(), tanhf() and tanhl() are thread safe. + +toascii.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function toascii() is thread safe. + +toupper.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions toupper() and tolower() are thread safe with + exceptions. + +towctrans.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function towctrans() is thread safe. + +towlower.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function towlower() is thread safe with exceptions. + +towupper.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function towupper() is thread safe with exceptions. + +ualarm.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function ualarm() is thread safe. + +wcpncpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function wcpncpy() is thread safe. + +proc.5 + Michael Kerrisk [Sworddragon2] + Fix formula for CommitLimit under /proc/meminfo + See https://bugzilla.kernel.org/show_bug.cgi?id=60991 + +credentials.7 + Michael Kerrisk + List APIs that operate on process groups + Michael Kerrisk + Add details on controlling terminal and foreground/background jobs + +feature_test_macros.7 + Michael Kerrisk + Document _DEFAULT_SOURCE + Michael Kerrisk [Joseph S. Myers] + From glibc 2.19, _BSD_SOURCE no longer causes __FAVOR_BSD + Starting with glibc 2.19, _BSD_SOURCE no longer causes BSD + definitions to be favored in cases where standards conflict. + +libc.7 + Mike Frysinger + SEE ALSO: add various entries + +man-pages.7 + Michael Kerrisk [Mike Frysinger] + Add STYLE GUIDE section + Incorporate some of the existing material in the page + into the STYLE GUIDE, and add a lot more material, mainly + drawn from the "Global changes" sections in the release + changelogs. + Michael Kerrisk + Add historical note on reason for use of American spelling + Michael Kerrisk [Mike Frysinger] + Various improvements to style guide + +packet.7 + Willem de Bruijn [Daniel Borkmann] + Document fanout, ring, and auxiliary options + This patch adds descriptions of the common packet socket options + PACKET_AUXDATA, PACKET_FANOUT, PACKET_RX_RING, PACKET_STATISTICS, + PACKET_TX_RING + and the ring-specific options + PACKET_LOSS, PACKET_RESERVE, PACKET_TIMESTAMP, PACKET_VERSION + Michael Kerrisk + Add kernel version numbers for PACKET_VERSION and PACKET_TIMESTAMP + +ld.so.8 + Michael Kerrisk [Matthias Klose] + Default output file for D_DEBUG is stderr not stdout + See https://sourceware.org/bugzilla/show_bug.cgi?id=6874 + + + +==================== Changes in man-pages-3.57 ==================== + +Released: 2014-01-24, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andi Kleen +Andre Majorel +Andrey Vagin +Andy Lutomirski +Axel Beckert +Bernhard Walle +Brandon Edens +Eliezer Tamir +Gioele Barabucci +Ian Abbott +Jerry Chu +Jonas Jonsson +Marc Lehmann +Michael Kerrisk +Mike Frysinger +Peng Haitao +Reuben Thomas +Simone Piccardi +Simon Paillard +Thomas Posch +Tilman Schmidt +Vince Weaver +Yuri Kozlov +Марк Коренберг + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +msgop.2 + Michael Kerrisk + Document MSG_COPY + +open.2 + Michael Kerrisk, Andy Lutomirski + Document O_TMPFILE + O_TMPFILE is new in Linux 3.11 + +perf_event_open.2 + Vince Weaver [Andi Kleen] + PERF_SAMPLE_TRANSACTION support in Linux 3.13 + The following patch adds descriptions of the new perf_event_open.2 + PERF_SAMPLE_TRANSACTION sample type as added in Linux 3.13. + + The descriptions are based on information provided by Andi Kleen, + both in the e-mail + + [PATCH 1/6] perf, core: Add generic transaction flags v5 + + sent to the linux-kernel list as well as an e-mail + + [PATCH] Document transaction flags in perf_event_open manpage + + sent to the linux-man list. + + The implementation is based heavily on the Intel Haswell + processor. Documentation can be found at this page: + http://software.intel.com/en-us/blogs/2013/05/03/intelr-transactional-synchronization-extensions-intelr-tsx-profiling-with-linux-0 + as well as in section 18.11.5.1 of volume 3 of the + Intel 64 and IA-32 Architecture Software Developer's Manual. + +ptrace.2 + Andrey Vagin + Add description for PTRACE_PEEKSIGINFO + Retrieve signals without removing them from a queue. + Andrey Vagin + Add description for PTRACE_GETSIGMASK and PTRACE_SETSIGMASK + These two commands allow to examine and change mask of blocked + signals. + +socket.7 + Eliezer Tamir + Add description for SO_BUSY_POLL + Add description for the SO_BUSY_POLL socket option. + +tcp.7 + Michael Kerrisk [Jerry Chu] + Document TCP_USER_TIMEOUT + Text slightly adapted from Jerry Chu's (excellent) commit + message (commit dca43c75e7e545694a9dd6288553f55c53e2a3a3). + Michael Kerrisk + Document TCP_CONGESTION + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Reword to avoid use of "etc." + +Various pages + Peng Haitao [Andre Majorel] + Make wording around thread-safety and setlocale() more precise + +getdate.3 +strptime.3 +locale.5 + Michael Kerrisk + Replace "weekday" with less ambiguous language + Notwithstanding POSIX's use of the term "weekday", in everyday + English, "weekday" is commonly understood to mean a day in the + set [Monday..Friday] (vs one of the "weekend" days). + + +Changes to individual pages +--------------------------- + +epoll_wait.2 + Michael Kerrisk [Jonas Jonsson] + Clarify wording of EINTR error + See https://bugzilla.kernel.org/show_bug.cgi?id=66571 + +faccessat.2 + Michael Kerrisk + Note that the system call takes only three arguments + +fallocate.2 + Michael Kerrisk + Note filesystems that support FALLOC_FL_PUNCH_HOLE operation + +fcntl.2 + Michael Kerrisk + BUGS: The O_SYNC and O_DSYNC flags are not modifiable using F_SETFL + Michael Kerrisk + Add subsections under BUGS + There's several bugs listed. It's helpful to mark + them separately. + Michael Kerrisk + POSIX.1 specifies F_SETOWN and F_GETOWN for sockets/SIGURG + +getrlimit.2 + Michael Kerrisk [Марк Коренберг] + Note that rlim_cur can be set lower than current resource consumption + +getsockopt.2 + Michael Kerrisk + SEE ALSO: add ip(7) and udp(7) + +keyctl.2 + Michael Kerrisk + SEE ALSO: mention Documentation/security/keys.txt + +linkat.2 + Michael Kerrisk + Add ENOENT for O_TMPFILE created with O_EXCL + Michael Kerrisk + ERRORS: Add EINVAL + +lseek.2 + Michael Kerrisk + Note which filesystems support SEEK_HOLE/SEEK_DATA + +msgop.2 + Michael Kerrisk + Note that MSG_EXCEPT is Linux-specific + +open.2 + Michael Kerrisk + Update CONFORMING TO + Add POSIX.1-2008. Add mention of O_TMPFILE. + Update text on various flags that were added in POSIX.1-2008, and + whose definitions can, since glibc 2.12, be obtained by suitably + defining _POSIX_C_SOURCE or _XOPEN_SOURCE + Michael Kerrisk + Add pointer in description to BUGS, for O_ASYNC limitation + Michael Kerrisk + Remove crufty duplicate text on modifying file status flags + +ptrace.2 + Michael Kerrisk + Add details to descriptions of PTRACE_GETSIGMASK and PTRACE_SETSIGMASK + +select.2 + Michael Kerrisk [Marc Lehmann] + RETURN VALUE: Fix discussion of treatment of file descriptor sets + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=574370 + +syscalls.2 + Michael Kerrisk + Remove madvise1() from main list + madvise1() is one of the system calls that was never + implemented, and listed toward the bottom of the page. + +timer_create.2 + Michael Kerrisk + Add pointer to proc(5) for info on /proc/[pid]/timers + +unlinkat.2 + Michael Kerrisk [Mike Frysinger:] + ERRORS: Add EISDIR + See https://bugzilla.kernel.org/show_bug.cgi?id=29702 + +ferror.3 + Michael Kerrisk + clearerr(), feof(), and ferror() are also POSIX-conformant + Michael Kerrisk [Reuben Thomas] + CONFORMING TO: add fileno() + +gets.3 + Ian Abbott + SEE ALSO: add fgets(3) + +mq_receive.3 +mq_send.3 + Michael Kerrisk [Simone Piccardi] + SYNOPSIS: s/unsigned/unsigned int/ + +printf.3 + Michael Kerrisk + Small reorganization of text in EXAMPLE + +rand.3 + Michael Kerrisk + s/unsigned/unsigned int/ in example + +stpcpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function stpcpy() is thread safe. + +stpncpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function stpncpy() is thread safe. + +strcat.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions strcat() and strncat() are thread safe. + +strchr.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions strchr(), strrchr() and strchrnul() are thread safe. + +strcmp.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions strcmp() and strncmp() are thread safe. + +strftime.3 + Brandon Edens + Change "week day" to "day of week" + See https://bugzilla.kernel.org/show_bug.cgi?id=68861 + +strstr.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function strstr() is thread safe. + The function strcasestr() is thread safe with exceptions. + +strtod.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions strtod(), strtof() and strtold() are thread safe + with exceptions. + +strtoimax.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions strtoimax() and strtoumax() are thread safe with + exceptions. + +strtol.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions strtol(), strtoll() and strtoq() are thread safe + with exceptions. + +tcgetpgrp.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions tcgetpgrp() and tcsetpgrp() are thread safe. + +tcgetsid.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function tcgetsid() is thread safe. + +core.5 + Bernhard Walle + Mention that %E exists since Linux 3.0 + '%E' in the 'core_pattern' has been introduced in kernel commit + 57cc083ad9e1bfeeb4a0ee831e7bb008c8865bf0 which was included in + version 3.0. Add that information to the manual page. + +filesystems.5 + Michael Kerrisk [Axel Beckert] + Add reference to proc(5) for more details on /proc/filesystems + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=735590 + +locale.5 + Michael Kerrisk + SEE ALSO: add locale(7) + +proc.5 + Michael Kerrisk + Document /proc/[pid]/timers + Michael Kerrisk + Update discussion of wchan + Remove crufty reference to /etc/psdatabase in /proc/PID/stat. + Add /proc/PID/wchan. + + See https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/737452 + +environ.7 + Michael Kerrisk [Gioele Barabucci] + Correct reference to locale(7) (not locale(5)) + locale(7) is the right place for details of the LC_* + environment variables. + + See http://bugs.debian.org/638186 + Michael Kerrisk + Improve references for discussion of locale environment variables + Michael Kerrisk + SEE ALSO: add catopen(3) + Michael Kerrisk + SEE ALSO: add locale(5) + +man-pages.7 + Michael Kerrisk + Prefer "usable" over "useable" + +netdevice.7 + Tilman Schmidt + Document SIOCGIFCONF case ifc_req==NULL + Add the missing description of the possibility to call SIOCGIFCONF + with ifc_req==NULL to determine the needed buffer size, as + described in + http://lkml.indiana.edu/hypermail/linux/kernel/0110.1/0506.html + and verified against source files net/core/dev_ioctl.c and + net/ipv4/devinet.c in the current kernel git tree. + This functionality has been present since the beginning of the 2.6 + series. It's about time it gets documented. + + While I'm at it, also generally clarify the section on + SIOCGIFCONF. + +standards.7 + Michael Kerrisk + Enhance description of V7 + Michael Kerrisk + Add C11 + +tcp.7 + Michael Kerrisk + Describe format of tcp_*_congestion_control /proc files + Describe format of tcp_allowed_congestion_control and + tcp_available_congestion_control. + + +==================== Changes in man-pages-3.58 ==================== + +Released: 2014-02-11, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Cyril Hrubis +Daniel Borkmann +David Prévot +Fabrice Bauzac +Michael Kerrisk +Mike Frysinger +Network Nut +Ola Olsson +Peng Haitao +Peter Schiffer +Simone Piccardi +Simon Paillard +Yuri Kozlov +Марк Коренберг +未卷起的浪 + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +pipe.2 + Michael Kerrisk + Document the pipe2() O_DIRECT flag added in Linux 3.4 + +packet.7 + Daniel Borkmann + Document PACKET_QDISC_BYPASS + New in Linux 3.14. + + +Global changes +-------------- + +Various pages + Simon Paillard + Formatting fix: add space between function and () if BR or IR + Detected through the regex: + git grep -P '^\.(BR|IR) [\w]*\([\d]*\)$' + +Various pages + Simon Paillard + Formatting fix: add space between word and punctuation if BR or IR + Detected through the regex: + git grep -P '^\.(BR|IR) [^ ]*[,\.]$' + + Could probably be extended to match more cases and fix in perl. + +Various pages + Michael Kerrisk + Use Oxford comma + +gettid.2 +restart_syscall.2 +passwd.5 +socket.7 + Michael Kerrisk + Fix order of SEE ALSO entries + + +Changes to individual pages +--------------------------- + +epoll_wait.2 + Michael Kerrisk [Network Nut] + Remove word "minimum" from the description of 'timeout' + +epoll_wait.2 +poll.2 +select.2 + Michael Kerrisk + Go into more detail on timeout and when call will cease blocking + +getxattr.2 +listxattr.2 +removexattr.2 +setxattr.2 + Michael Kerrisk [Fabrice Bauzac] + Correct header file is (not ) + See https://bugzilla.kernel.org/show_bug.cgi?id=70141 + +msgctl.2 + Cyril Hrubis + Add note about ignored arg to IPC_RMID + +prctl.2 + Michael Kerrisk [Марк Коренберг] + PR_SET_PDEATHSIG value is preserved across execve(2) + +recv.2 + Michael Kerrisk + Rework and reorganize the text in various parts of the page. + Isolate details specific to recv() vs recvfrom() vs recvmsg() + Place details specific to each system call under a + separate subheading. + Rework discussion of 'src_addr' and 'addrlen' for recvfrom() + Add description of 'buf' and 'len' in recvfrom() section + 'addrlen' should be 0 (*not* NULL) when 'src_addr' is NULL + Improve text describing recvfrom() call that is equivalent to recv() + Michael Kerrisk [未卷起的浪] + Describe the various cases where the return value can be 0 + +shmctl.2 + Michael Kerrisk + Note that 'buf' is ignored for IPC_RMID + +symlinkat.2 + Michael Kerrisk + Make argument names consistent with symlink(2) page + +isalpha.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions isalnum(), isalpha(), isascii(), isblank(), + iscntrl(), isdigit(), isgraph(), islower(), isprint(), + ispunct(), isspace(), isupper() and isxdigit() are thread safe. + +isatty.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function isatty() is thread safe. + +isgreater.3 + Peng Haitao + ATTRIBUTES: Note macros that are thread-safe + The macros isgreater(), isgreaterequal(), isless(), + islessequal(), islessgreater() and isunordered() are thread safe. + +iswalnum.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswalnum() is thread safe with exceptions. + +iswalpha.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswalpha() is thread safe with exceptions. + +iswblank.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswblank() is thread safe with exceptions. + +iswcntrl.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswcntrl() is thread safe with exceptions. + +lockf.3 + Michael Kerrisk [Simone Piccardi] + Fix incorrect argument mentioned under EINVAL error + +pthread_kill.3 + Michael Kerrisk + Add feature test macro requirements + +pthread_sigmask.3 + Michael Kerrisk + Add feature test macro requirements + +strtoul.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions strtoul(), strtoull() and strtouq() are thread safe + with exceptions. + +nscd.conf.5 + Peter Schiffer + Add note about default values + +proc.5 + Michael Kerrisk + SEE ALSO: Add some further kernel Documentation/sysctl files + +man-pages.7 + Michael Kerrisk + ATTRIBUTES sections come after VERSIONS + Peng Haitao has consistently ordered the ATTRIBUTES after + VERSIONS, so adjust the text in man-pages.7 + +vdso.7 + Michael Kerrisk + Add words "virtual dynamic shared object" in DESCRIPTION + + +==================== Changes in man-pages-3.59 ==================== + +Released: 2014-02-16, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Michael Kerrisk +Peter Schiffer +Weizhou Pan + +Apologies if I missed anyone! + + +Global changes +-------------- + +Various pages + Peter Schiffer, Michael Kerrisk [Weizhou Pan] + Convert pages containing non-ASCII in source code comments to use UTF-8 + Done using a slightly modified version of Peter Schiffer's + convert_to_utf_8.sh script. The script was modified so as *not* + a "coding:" marker to the groff source. For now, we'll only put + that marker on pages that contain non-ASCII characters in the + rendered text. + + See https://bugzilla.kernel.org/show_bug.cgi?id=60807 + +armscii-8.7 +cp1251.7 +iso_8859-1.7 +iso_8859-10.7 +iso_8859-11.7 +iso_8859-13.7 +iso_8859-14.7 +iso_8859-15.7 +iso_8859-16.7 +iso_8859-2.7 +iso_8859-3.7 +iso_8859-4.7 +iso_8859-5.7 +iso_8859-6.7 +iso_8859-7.7 +iso_8859-8.7 +iso_8859-9.7 +koi8-r.7 +koi8-u.7 + Peter Schiffer, Michael Kerrisk [Weizhou Pan] + Convert pages containing non-ASCII to use UTF-8 + Done using Peter Schiffer's convert_to_utf_8.sh script. + These pages containing non-ASCII in the rendered characters, and + so the script inserts a "coding:" marker into the groff source. + + See https://bugzilla.kernel.org/show_bug.cgi?id=60807 + + +==================== Changes in man-pages-3.60 ==================== + +Released: 2014-02-18, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +David Prévot +D. Barbier +Kalle Olavi Niemitalo +Michael Kerrisk +Simon Paillard + +Apologies if I missed anyone! + + +Changes to individual pages +--------------------------- +sigvec.3 + Michael Kerrisk [Kalle Olavi Niemitalo] + Fix error in code snippet + s/sigpause/sigmask/ + +armscii-8.7 +cp1251.7 +iso_8859-1.7 +iso_8859-10.7 +iso_8859-11.7 +iso_8859-13.7 +iso_8859-14.7 +iso_8859-15.7 +iso_8859-16.7 +iso_8859-2.7 +iso_8859-3.7 +iso_8859-4.7 +iso_8859-5.7 +iso_8859-6.7 +iso_8859-7.7 +iso_8859-8.7 +iso_8859-9.7 +koi8-u.7 + Michael Kerrisk [Simon Paillard] + Remove comment that glyphs in column 4 may not display correctly + With the conversion to UTF-8, the glyphs in column 4 of the + tables in these pages will display regardless of whether the + environment is configured for the corresponding character set. + +iso_8859-11.7 +iso_8859-13.7 + D. Barbier [Simon Paillard] + Fix encoding mistakes in 5f7f4042b8848127d852c6fa7c02e31ccfaeeae5 + Fixed via: + + for f in iso_8859-11 iso_8859-13; do + cp man7/$f.7 $f + iconv -f utf8 -t latin1 $f | iconv -f iso-${f#iso_} -t utf8 > man7/$f.7 + done + + + + +==================== Changes in man-pages-3.61 ==================== + +Released: 2014-02-26, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andrew Hunter +Carlos O'Donell +Christoph Hellwig +Daniel Borkmann +Duncan de Wet +Kir Kolyshkin +KOSAKI Motohiro +Michael Kerrisk +Neil Horman +Peng Haitao +Simon Paillard +Sulaiman Mustafa +Xiawei Chen + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +A note from Christoph Hellwig prompted me to perform a task that has +been queued for a while: merging the text of the man pages for the +*at([23]) ("directory file descriptor") APIs into their corresponding +traditional pages. When the *at([23]) pages were originally written +(mostly in 2006), the APIs were not part of POSIX and (in most cases) +were not available on other systems. So, it made some sense to wall +them off into their own separate pages. Eight years later, with the +APIs now all in POSIX (except scandirat()), it is much more sensible +to document the newer APIs alongside their traditional counterparts, +so that the newer APIs are not "hidden", and the reader can more +easily see the differences between the APIs. + +Thus, the text of 14 pairs of pages has been merged, and the "merged +from" pages have been converted to links to the "merged to" pages. +Along the way, a few other fixes were made to the pages, as noted +below. + +One page that did not undergo such a change was utimensat(2), which +is different enough from utime(2) that it warrants a separate page. +Unlike the other *at() pages, the utimensat(2) page was also already +self-contained, rather than defining itself in terms of differences +from utime(2) as the other *at() pages did. + +access.2 + Michael Kerrisk + Merge text from faccessat(2) + Michael Kerrisk + Remove faccessat() race warning + That point is already covered in existing text in this page. + Michael Kerrisk + access() also conforms to POSIX.1-2008 + +chmod.2 + Michael Kerrisk + Merge text from fchmodat(2) + Michael Kerrisk + Use argument name 'pathname' throughout page + (Some APIs were using 'path' while others used 'pathname') + Michael Kerrisk + CONFORMING TO: chmod() and fchmod() are also in POSIX.1-2008 + +chown.2 + Michael Kerrisk + Merge text of fchownat(2) + Michael Kerrisk + AT_EMPTY_PATH is Linux-specific and requires _GNU_SOURCE + Michael Kerrisk + Use argument name 'pathname' throughout page + (Some APIs were using 'path' while others used 'pathname') + Michael Kerrisk + Remove sentence that fchownat() is present on Solaris + That point was only really relevant before fchownat() was + standardized in POSIX.1.2008. + Michael Kerrisk + CONFORMING TO: chown(), fchown(), lchown() are in POSIX.1-2008 + +link.2 + Michael Kerrisk + Merge text of linkat(2) + Michael Kerrisk + CONFORMING TO: link() is in POSIX.1-2008 + Michael Kerrisk + AT_EMPTY_PATH is Linux-specific and requires _GNU_SOURCE + +mkdir.2 + Michael Kerrisk + Merge text of mkdirat(2) + Michael Kerrisk + CONFORMING TO: mkdir() is in POSIX.1-2008 + +mknod.2 + Michael Kerrisk + Merge text of mknodat(2) + Michael Kerrisk + CONFORMING TO: mknod(2) is in POSIX.1-2008 + +open.2 + Michael Kerrisk + Merge text from openat(2) + Michael Kerrisk + Remove sentence that openat() is present on Solaris + That point was only really relevant before openat() was + standardized in POSIX.1.2008. + +readlink.2 + Michael Kerrisk + Merge text of readlinkat(2) + Michael Kerrisk + CONFORMING TO: readlink() is in POSIX.1-2008. + Michael Kerrisk + Use argument name 'pathname' throughout page + (Some APIs were using 'path' while others used 'pathname') + +rename.2 + Michael Kerrisk + Merge text of renameat(2) + Michael Kerrisk + CONFORMING TO: rename(2) is in POSIX.1-2008 + +stat.2 + Michael Kerrisk + Merge text from fstatat(2) + Michael Kerrisk + AT_EMPTY_PATH and AT_NO_AUTOMOUNT are Linux-specific + These flags require _GNU_SOURCE. + Michael Kerrisk + Use argument name 'pathname' throughout page + (Some APIs were using 'path' while others used 'pathname') + Michael Kerrisk + Remove sentence that fstatat() is present on Solaris + That point was only really relevant before fstatat() was + standardized in POSIX.1.2008. + Michael Kerrisk + CONFORMING TO: stat(), fstat(), lstat() are specified in POSIX.1-2008 + +symlink.2 + Michael Kerrisk + Merge text of symlinkat(2) + Michael Kerrisk + CONFORMING TO: symlink() is in POSIX.1-2008 + +unlink.2 + Michael Kerrisk + Merge text of unlinkat(2) + Michael Kerrisk + Remove sentence that unlinkat() is present on Solaris + That point was only really relevant before unlinkat() was + standardized in POSIX.1.2008. + Michael Kerrisk + CONFORMING TO: unlink() is in POSIX.1-2008 + +mkfifo.3 + Michael Kerrisk + Merge text of mkfifoat(3) + Michael Kerrisk + CONFORMING TO: mkfifo() is in POSIX.1-2008 + +scandir.3 + Michael Kerrisk + Merge text of scandirat(3) + Michael Kerrisk + Update feature test macro requirements + The FTM requirements changed in glibc 2.10. + Michael Kerrisk + Remove libc4/libc5 note under CONFORMING TO + No-one much cares about Linux libc these days. + Michael Kerrisk + Put detail about alphasort under a NOTES heading + This text was under CONFORMING TO, which made no sense. + Michael Kerrisk + Rework CONFORMING TO text + + +Newly documented interfaces in existing pages +--------------------------------------------- + +prctl.2 + Kir Kolyshkin + Document PR_SET_MM options in Linux 3.5 + Some of the PR_SET_MM options were merged to vanilla kernel + later, and appeared in Linux 3.5. Those are: + + - PR_SET_MM_ARG_START + - PR_SET_MM_ARG_END + - PR_SET_MM_ENV_START + - PR_SET_MM_ENV_END + - PR_SET_MM_AUXV + - PR_SET_MM_EXE_FILE + +socket.7 + Neil Horman + Document the SO_RXQ_OVFL socket option + Michael Kerrisk + Add kernel version number for SO_RXQ_OVFL + + +New and changed links +--------------------- + +faccessat.2 + Michael Kerrisk + Convert to link to access.2 + +fchmodat.2 + Michael Kerrisk + Convert to link to chmod.2 + +fchownat.2 + Michael Kerrisk + Convert to link to chown.2 + +fstatat.2 + Michael Kerrisk + Convert to link to stat.2 + +linkat.2 + Michael Kerrisk + Convert to link to link.2 + +mkdirat.2 + Michael Kerrisk + Convert to link to mkdir.2 + +mknodat.2 + Michael Kerrisk + Convert to link to mknod.2 + +openat.2 + Michael Kerrisk + Convert to link to open.2 + +readlinkat.2 + Michael Kerrisk + Convert to link to symlink.2 + +renameat.2 + Michael Kerrisk + Convert to link rename.2 + +symlinkat.2 + Michael Kerrisk + Convert to link to symlink.2 + +unlinkat.2 + Michael Kerrisk + Convert to link to unlink.2 + +mkfifoat.3 + Michael Kerrisk + Convert to link to mkfifo.3 + +scandirat.3 + Michael Kerrisk + Convert to link to scandir.3 + + +Changes to individual pages +--------------------------- + +alarm.2 + Michael Kerrisk + Note semantics of alarm with respect to fork() and execve() + +fcntl.2 + Michael Kerrisk + Warn that F_GETLK info may already be out of date when the call returns + +intro.2 + Michael Kerrisk + Describe policy on documenting differences between syscall and glibc API + +mmap2.2 + Michael Kerrisk + Reword note on glibc mmap() wrapper invocation of mmap2() + Michael Kerrisk + This system call does not exist on x86-64 + +msgctl.2 + Michael Kerrisk + ERRORS: add EPERM for unprivileged attempt to set msg_qbytes > MSGMNB + +prctl.2 + Michael Kerrisk [Xiawei Chen] + Clarify that PR_GET_TIMERSLACK is returned as the function result + Michael Kerrisk + Clarify that PR_GET_SECCOMP is returned as function result + Michael Kerrisk + Clarify that PR_GET_NO_NEW_PRIVS is returned as function result + +ptrace.2 + Michael Kerrisk [Andrew Hunter] + Make it clearer that glibc and syscall APIs differ for PTRACE_PEEK* + Thanks to Denys Vlasenko's additions in 78686915aed6bd12 + this page does note that the glibc API for PTRACE_PEEK* + differs from the raw syscall interface. But, as the report + at https://bugzilla.kernel.org/show_bug.cgi?id=70801 shows, + this information could be more obvious. This patch makes its so. + +sgetmask.2 + Michael Kerrisk + Note that these system calls don't exist on x86-64 + +swapon.2 + Michael Kerrisk + Split EINVAL cases into separate entries under ERRORS + Michael Kerrisk + Add EINVAL error for invalid flags to swapon() + +syscalls.2 + Michael Kerrisk + SEE ALSO: add intro(2) + +umount.2 + Michael Kerrisk + Split EINVAL cases into separate items + Michael Kerrisk + ERRORS: Add EINVAL case that was new in 2.6.34 + +utime.2 + Michael Kerrisk + Add note that modern applications probably want utimensat(2) etc. + +crypt.3 + Michael Kerrisk [KOSAKI Motohiro] + ERRORS: Add EINVAL and EPERM errors + See https://bugzilla.kernel.org/show_bug.cgi?id=69771 + +getifaddrs.3 + Michael Kerrisk + Enhance example program + Print statistics for AF_PACKET interfaces. + Add missing feature test macro definition. + Reformat output. + +iswctype.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function iswctype() is thread safe. + +sem_post.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sem_post() is thread safe. + +sem_unlink.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sem_unlink() is thread safe. + +sem_wait.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions sem_wait(), sem_trywait() and sem_timedwait() are + thread safe. + +setbuf.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions setbuf(), setbuffer(), setlinebuf() and setvbuf() + are thread safe. + +strlen.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function strlen() is thread safe. + +strnlen.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function strnlen() is thread safe. + +strpbrk.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function strpbrk() is thread safe. + +strsep.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function strsep() is thread safe. + +swab.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function swab() is thread safe. + +resolv.conf.5 + Carlos O'Donell + DESCRIPTION: mention that the data is trusted + In a recent discussion about DNSSEC it was brought to my + attention that not all system administrators may understand + that the information in /etc/resolv.conf is fully trusted. + The resolver implementation in glibc treats /etc/resolv.conf + as a fully trusted source of DNS information and passes on + the AD-bit for DNSSEC as trusted. + + This patch adds a clarifying sentence to make it absolutely + clear that indeed this source of information is trusted. + +ascii.7 + Michael Kerrisk [Sulaiman Mustafa] + Fix rendering of single quote (decimal character 39) + Michael Kerrisk + SEE ALSO: add utf-8(7) + Michael Kerrisk [Duncan de Wet] + Remove mention of ISO 8859-1 as being the default encoding on Linux + +packet.7 + Neil Horman + Document PACKET_FANOUT_QM fanout mode + Michael Kerrisk + Add kernel version for PACKET_FANOUT_QM + Daniel Borkmann + Improve PACKET_QDISC_BYPASS description + +socket.7 + Michael Kerrisk + Add kernel version number for SO_BUSY_POLL + + +==================== Changes in man-pages-3.62 ==================== + +Released: 2014-03-11, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Cyril Hrubis +Joseph S. Myers +Marius Gaubas +Michael Kerrisk +Mike Frysinger +Peng Haitao +Rick Stanley +Simon Paillard + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +locale.1 + Michael Kerrisk [review from Mike Frysinger] + New page describing locale(1) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +locale.5 + Michael Kerrisk + Document LC_ADDRESS + Michael Kerrisk + Document LC_IDENTIFICATION + Michael Kerrisk + Document LC_MEASUREMENT + Michael Kerrisk + Document LC_NAME + Michael Kerrisk + Document LC_PAPER + Michael Kerrisk + Document LC_TELEPHONE + + +Removed Pages +------------- + +sync.8 + Michael Kerrisk [Christoph Hellwig, Pádraig Brady] + Sometime in the 20th century (before my watch), a sync(8) + page into man-pages. It documents the sync command from + "fileutils", which long ago become coreutils, and the + piece under NOTES note some behavior of sync(2) + that ceased to be true many years ago. The man-pages + project generally focuses on only Linux kernel and + (g)libc interfaces, so this sync(8) page doesn't really + belong. Furthermore, coreutils has a sync(1) page which + covers the same command. After discussions on the + coreutils list, I've decided to retire this page from + man-pages. + +Changes to individual pages +--------------------------- + +clone.2 + Michael Kerrisk + Note that CLONE_THREAD also in effect requires CLONE_VM + +stat.2 + Michael Kerrisk [Marius Gaubas] + Warn the reader that the 'stat' structure definition is not precise + Padding fields aren't shown, and the order of fields varies + somewhat across architectures. + +gethostbyname.3 + Michael Kerrisk + Remove redundant FTM requirements + _GNU_SOURCE implies _SVID_SOURCE and _BSD_SOURCE, so + + _BSD_SOURCE || _SVID_SOURCE || _GNU_SOURCE + + is the same as + + _BSD_SOURCE || _SVID_SOURCE + +getutmp.3 + Michael Kerrisk + SEE ALSO: add utmpdump(1) + +log1p.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions log1p(), log1pf() and log1pl() are thread safe. + +logb.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions logb(), logbf() and logbl() are thread safe. + +memccpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function memccpy() is thread safe. + +memchr.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions memchr(), memrchr() and rawmemchr() are thread safe. + +mktemp.3 + Michael Kerrisk + Make warning not to use this function more prominent + +qecvt.3 + Michael Kerrisk [Joseph S. Myers] + Recommend snprintf(3) not sprintf(3) + +raise.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function raise() is thread safe. + +remove.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function remove() is thread safe. + +sem_destroy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sem_destroy() is thread safe. + +sem_getvalue.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sem_getvalue() is thread safe. + +sem_init.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sem_init() is thread safe. + +sockatmark.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sockatmark() is thread safe. + +strcpy.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions strcpy() and strncpy() are thread safe. + Michael Kerrisk [Rick Stanley] + Fix a bug, and improve discussion of forcing termination with strncpy() + +strspn.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions strspn() and strcspn() are thread safe. + +tempnam.3 + Michael Kerrisk + Make warning not to use this function more prominent + +tmpnam.3 + Michael Kerrisk + Recommend use mkstemp(3) or tmpfile(3) instead + +locale.5 + Michael Kerrisk + Add intro section that lists all of the LC categories + Michael Kerrisk + 'p_cs_precedes' is for *positive* values + Michael Kerrisk + Clarify 'p_sign_posn' and 'n_sign_posn'; simplify 'n_sign_posn' + Add initial sentence for 'p_sign_posn' and 'n_sign_posn'. + Remove repeated list for 'n_sign_posn'. + Michael Kerrisk + Document LC_MESSAGES 'yesstr' and 'nostr' + Michael Kerrisk + Clarify LC_MONETARY 'n_cs_precedes' + Michael Kerrisk + LC_MONETARY: Document 'int_p_sign_posn' and 'int_n_sign_posn' + Michael Kerrisk + Clarify/rework 'p_cs_precedes' and 'n_cs_precedes' + Michael Kerrisk + LC_MONETARY: document 'int_p_sep_by_space' and 'int_n_sep_by_space' + Michael Kerrisk + Remove crufty reference to POSIX.2 + Michael Kerrisk + LC_MONETARY: document 'int_p_cs_precedes' and 'int_n_cs_precedes' + Michael Kerrisk + Clarify/simplify 'n_sep_by_space' + Michael Kerrisk + LC_TIME: document 'cal_direction' and 'date_fmt' + Michael Kerrisk + Clarify 'p_sep_by_space' + +feature_test_macros.7 + Michael Kerrisk + _BSD_SOURCE and _SVID_SOURCE are deprecated in glibc 2.20 + Michael Kerrisk + _GNU_SOURCE implicitly defines other macros + Saying that _GNU_SOURCE has the "effects of" other macros is not + quite precise. + Michael Kerrisk + Reword glibc version for _ISOC95_SOURCE + Michael Kerrisk + _ISOC99_SOURCE also exposes C95 definitions + Michael Kerrisk + _ISOC11_SOURCE implies the effects of _ISOC99_SOURCE + Michael Kerrisk + Note version number for _POSIX_C_SOURCE >= 200112L implies C99/C95 + _POSIX_C_SOURCE >= 200112L causes C95 definitions to be + exposed only since glibc 2.12 and C99 definitions only + since 2.10. + Michael Kerrisk + _XOPEN_SOURCE may implicitly define _POSIX_SOURCE and _POSIX_C_SOURCE + Michael Kerrisk + Reword glibc version for _ISOC99_SOURCE + Michael Kerrisk + Rework discussion of _ISOC99_SOURCE + Michael Kerrisk + Improve discussion of _DEFAULT_SOURCE + Michael Kerrisk + _POSIX_C_SOURCE >= 200112L implies C95 and C95 features + + + +==================== Changes in man-pages-3.63 ==================== + +Released: 2014-03-18, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Carlos O'Donell +Christoph Hellwig +Corrado Zoccolo +Gregory P. Smith +Joseph S. Myers +Michael Kerrisk +Mike Frysinger +Peng Haitao +Phillip Susi +Robert P. J. Day +Stefan Puiu +Zhu Yanhai + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +duplocale.3 + Michael Kerrisk + New page documenting duplocale(3) + +newlocale.3 + Michael Kerrisk [Mike Frysinger] + New page documenting newlocale(3) and freelocale(3) + +towlower.3 + Michael Kerrisk + Largely rewrite description of towlower() to be simpler and clearer + +towupper.3 + Michael Kerrisk + Largely rewrite description of towupper() to be simpler and clearer + +uselocale.3 + Michael Kerrisk + New page documenting uselocale(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +open.2 + Michael Kerrisk + Document O_DSYNC and rewrite discussion of O_SYNC + +isalpha.3 + Michael Kerrisk + Document the "_l" locale APIs + The GNU C library v2.3 added some locale APIs, most of which + were later specified in POSIX.1-2008, namely: + + isalnum_l() + isalpha_l() + isblank_l() + iscntrl_l() + isdigit_l() + isgraph_l() + islower_l() + isprint_l() + ispunct_l() + isspace_l() + isupper_l() + isxdigit_l() + isascii_l() + + Also update and correct various pieces in CONFORMING TO + (and remove a few crufty old pieces there). + +strerror.3 + Michael Kerrisk + Document strerror_l() + +toupper.3 + Michael Kerrisk + Document toupper_l() and tolower_l() + +towlower.3 + Michael Kerrisk + Document towlower_l() + +towupper.3 + Michael Kerrisk + Document towupper_l() + +proc.5 + Michael Kerrisk + Document /proc/sys/kernel/random/uuid + +locale.7 + Michael Kerrisk + Document LC_ADDRESS + Document LC_IDENTIFICATION + Document LC_MEASUREMENT + Document LC_NAME + Document LC_PAPER + Document LC_TELEPHONE + + +New and changed links +--------------------- + +freelocale.3 + Michael Kerrisk + New link to new newlocale.3 page + +isalnum_l.3 +isascii_l.3 +isblank_l.3 +iscntrl_l.3 +isdigit_l.3 +isgraph_l.3 +islower_l.3 +isprint_l.3 +ispunct_l.3 +isspace_l.3 +isupper_l.3 +isxdigit_l.3 + Michael Kerrisk + New links to isalpha.3 + +tolower_l.3 +toupper_l.3 + Michael Kerrisk + New links to toupper.3 + +towlower_l.3 + Michael Kerrisk + New link to towlower.3 + +towupper_l.3 + Michael Kerrisk + New link to towupper.3 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Global change: "upper case" ==> "uppercase", "lower case" ==> lowercase" + + +Changes to individual pages +--------------------------- + +mount.2 + Michael Kerrisk + SEE ALSO: add blkid(1) + +msgop.2 + Michael Kerrisk + Document two MSG_COPY failure modes + Since Linux 3.14, the kernel now diagnoses two errors + when using msgrcv() MSG_COPY: + * MSG_COPY must be specified with IPC_NOWAIT + * MSG_COPY can't be specified with MSG_EXCEPT + +open.2 + Michael Kerrisk + Organize some material under additional subheadings in NOTES + There's an amorphous mass of material under NOTES. Structure + it with some subheadings, and do a little reorganizing. + Michael Kerrisk + Add other system calls and functions that are like openat() + fanotify_mark(2), name_to_handle_at(2), and scandirat(3) have a + directory file descriptor argument for the same reason as openat(). + Also: reword the rationale for the *at() functions somewhat. + Michael Kerrisk + Clarify ELOOP error interaction with O_PATH + +readahead.2 + Phillip Susi [Corrado Zoccolo, Gregory P. Smith, Zhu Yanhai, Michael Kerrisk, Christoph Hellwig] + Don't claim the call blocks until all data has been read + The readahead(2) man page was claiming that the call blocks until + all data has been read into the cache. This is incorrect. + + See https://bugzilla.kernel.org/show_bug.cgi?id=54271 + +stat.2 + Michael Kerrisk + SEE ALSO: add ls(1) and stat(1) + +fts.3 + Christoph Hellwig [Michael Kerrisk] + The fts(3) API does not work with LFS builds + As pointed out during a recent discussion on libc-hacker the + fts(3) APIs can't be used with large file offsets: + + https://sourceware.org/bugzilla/show_bug.cgi?id=15838 + +mbrtowc.3 +mbsnrtowcs.3 +mbsrtowcs.3 +mbtowc.3 + Michael Kerrisk + Add entries in SEE ALSO + Mainly inspired by the POSIX pages. + +mbsinit.3 + Michael Kerrisk + SEE ALSO: add mbrlen(3), mbrtowc(3), and wcrtomb(3) + +mbsrtowcs.3 +wcsrtombs.3 + Michael Kerrisk + SEE ALSO: add mbsinit(3) + +mbstowcs.3 + Michael Kerrisk [Stefan Puiu] + Add example program + And add some SEE ALSO entries + +memcmp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function memcmp() is thread safe. + +memcpy.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function memcpy() is thread safe. + +memfrob.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function memfrob() is thread safe. + +memmem.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function memmem() is thread safe. + +memmove.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function memmove() is thread safe. + +mempcpy.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions mempcpy() and wmempcpy() are thread safe. + +memset.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function memset() is thread safe. + +strerror.3 + Michael Kerrisk + CONFORMING TO: strerror() and strerror_r() are in POSIX.1-2008 + Michael Kerrisk + Add SS heading for strerror_r() + +toupper.3 + Michael Kerrisk + Rewrite to more explicitly bring locales into the discussion + Michael Kerrisk + Retitle BUGS section to NOTES + These are not really bugs, just background info. + +wcrtomb.3 +wcsnrtombs.3 +wcsrtombs.3 +wcstombs.3 +wctomb.3 + Michael Kerrisk + SEE ALSO: add various entries + Mainly inspired by POSIX + +core.5 + Mike Frysinger [Michael Kerrisk] + Document core_pattern %d specifier + Document %P core_pattern specifier + Michael Kerrisk + Rearrange core_pattern specifiers alphabetically + +locale.5 + Michael Kerrisk + SEE ALSO: add newlocale(3) + duplocale(3) + +feature_test_macros.7 + Michael Kerrisk [Joseph S. Myers] + Remove mention of bogus _ISOC95_SOURCE macro + The _ISOC95_SOURCE macro is defined in , but it + does nothing. So remove discussion of it, and move some of + the discussion of C95 under the _ISOC99_SOURCE subhead. + Michael Kerrisk [Carlos O'Donell] + Add packaging note for _BSD_SOURCE/_SVID_SOURCE/_DEFAULT_SOURCE + To compile warning-free across glibc < 2.20 and glibc >= 2.20 + code may been to define both _DEFAULT_SOURCE and either + _BSD_SOURCE or _SVID_SOURCE. + Michael Kerrisk + Reword description of C90 + +locale.7 + Michael Kerrisk + Add subsection on POSIX.1-2008 (originally GNU) extensions to locale API + Michael Kerrisk + Remove reference to LI18NUX2000 + LI18NUX2000 is difficult to even find these days, and in any case + this page does not document gettext(), so notes about gettext() + in the CONFORMING TO section here make no sense. + Michael Kerrisk + SEE ALSO: add mbstowcs(3) and wcstombs(3) + SEE ALSO: add newlocale(3) + duplocale(3) + +man-pages.7 + Michael Kerrisk + Add preferred term "superblock" + Michael Kerrisk + Add preferred terms "uppercase" and "lowercase" + + + +==================== Changes in man-pages-3.64 ==================== + +Released: 2014-04-06, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Abhay Sachan +Alexey Samsonov +Andrey Vagin +Aneesh Kumar K.V +Christoph Hellwig +David Prévot +Eric Dumazet +Eric W. Biederman +Jan Kara +Kir Kolyshkin +Michael Kerrisk +Mike Frysinger +NeilBrown +Peng Haitao +Peter Hurley +Petr Gajdos +Robert P. J. Day +Vince Weaver +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +open_by_handle_at.2 + Michael Kerrisk [Mike Frysinger, Neil Brown, Aneesh Kumar K.V, + Christoph Hellwig] + New page describing name_to_handle_at(2) and open_by_handle_at(2) + +inotify.7 + Michael Kerrisk + Rewrite introductory section + Reorganize "Limitations and caveats" subsection + Michael Kerrisk + Further describe the race when adding a watch to a new subtree + Michael Kerrisk + Directory renames may invalidate multiple paths cached by application + Michael Kerrisk + Add paragraph on cache consistency checking + Michael Kerrisk + Mention cache rebuilding to handle overflow events + Michael Kerrisk + Moving an object to another filesystem generates IN_DELETE_SELF + Michael Kerrisk [Jan Kara] + Add text on dealing with rename() events + Michael Kerrisk + Note rationale and consequences of event coalescing + Michael Kerrisk [Eric W. Biederman] + Inotify doesn't work for remote and pseudo filesystems + Michael Kerrisk + Add some examples of events generated by various system calls + Michael Kerrisk + BUGS: IN_ONESHOT does now cause IN_IGNORED when the watch is dropped + A silent change as a result of the fanotify work in kernel 2.6.36. + Michael Kerrisk + Note that IN_DELETE_SELF will be followed by IN_IGNORED + Michael Kerrisk + Note that IN_UNMOUNT will be followed by an IN_IGNORED event + Michael Kerrisk + Inotify does not report events for mmap(2) and msync(2) + Michael Kerrisk + Add examples of syscalls that trigger IN_ATTRIB + Michael Kerrisk + Add some examples of syscalls that trigger IN_MODIFY + Michael Kerrisk + execve(2) also generates IN_ACCESS + Michael Kerrisk + Add examples of syscalls that trigger IN_CREATE + + +Newly documented interfaces in existing pages +--------------------------------------------- + +perf_event_open.2 + Vince Weaver [Michael Kerrisk] + Document the PERF_FLAG_FD_CLOEXEC flag + The Linux 3.14 release adds support for the PERF_FLAG_FD_CLOEXEC + flag. + +feature_test_macros.7 + Michael Kerrisk + Document _LARGEFILE_SOURCE + +tcp.7 + Michael Kerrisk [Eric Dumazet] + Document /proc/sys/net/ipv4/tcp_autocorking + Text heavily based on Documentation/networking/ip-sysctl.txt + + +New and changed links +--------------------- + +name_to_handle_at.2 + Michael Kerrisk + New link to new open_by_handle_at(2) page + + +Global changes +-------------- + +fmemopen.3 +getaddrinfo.3 +mq_notify.3 +offsetof.3 +aio.7 + Michael Kerrisk + Print size_t/ssize_t values using %z printf() modifier + There are fewer and fewer systems these days that don't + support the %z specifier mandated in C99. So replace the + use of %ld/%lu + (long) cast with %zd/%zu. + + +Changes to individual pages +--------------------------- + +bdflush.2 +fsync.2 +sync.2 + Kir Kolyshkin + SEE ALSO: remove update(8) reference + Remove reference to update(8) man page, since there is no such + page. This is an ancient BSD leftover I believe. + +chown.2 + Michael Kerrisk + Note that 'dirfd' can be AT_FDCWD when AT_EMPTY_PATH is used + +getxattr.2 + Abhay Sachan + Fix RETURN VALUE description + A EA can have length zero. + +inotify_add_watch.2 + Michael Kerrisk + ERRORS: add ENAMETOOLONG + +inotify_init.2 + Michael Kerrisk + Add pointer to inotify(7) + +link.2 + Michael Kerrisk + When AT_EMPTY_PATH is specified, 'olddirfd' must not refer to a + directory + +mmap.2 + Andrey Vagin + The file descriptor for a file mapping must be readable + There is no difference between MAP_SHARED and MAP_PRIVATE. + +open.2 + Michael Kerrisk + SEE ALSO: add open_by_name_at(2) + +perf_event_open.2 + Vince Weaver + Document PERF_EVENT_IOC_PERIOD behavior change + Linux 3.14 (in commit bad7192b842c83e580747ca57104dd51fe08c223) + changes the perf_event PERF_EVENT_IOC_PERIOD ioctl() behavior + on all architectures to update immediately, to match the behavior + found on ARM. + +stat.2 + Michael Kerrisk + Note that 'dirfd' can be AT_FDCWD when AT_EMPTY_PATH is used + +syscalls.2 + Michael Kerrisk + Add sched_getattr() and sched_setattr() + And update kernel version to 3.14 + +abort.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function abort() is thread safe. + +confstr.3 + Michael Kerrisk + SEE ALSO: add getconf(1), fpathconf(3), sysconf(3), pathconf(3) + +exit.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function exit() is not thread safe. + +fenv.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions feclearexcept(), fegetexceptflag(), feraiseexcept(), + fesetexceptflag(), fetestexcept(), fegetround(), fesetround(), + fegetenv(), feholdexcept(), fesetenv(), feupdateenv(), + feenableexcept(), fedisableexcept() and fegetexcept() are thread + safe. + +fpathconf.3 + Michael Kerrisk + SEE ALSO: add confstr(3) + +fseek.3 + Michael Kerrisk [Petr Gajdos] + Document EINVAL error for negative file offset + +fseeko.3 + Michael Kerrisk + Add feature test macro requirements + +fts.3 + Michael Kerrisk [Mike Frysinger] + Remove mention of "32-bit systems" in BUGS + +fwide.3 +wprintf.3 + Michael Kerrisk [Robert P. J. Day] + Remove mention of bogus _ISOC95_SOURCE feature test macro + +getline.3 + Alexey Samsonov + Caller should free the allocated buffer even if getline() failed + Relevant discussion in glibc bugzilla: + https://sourceware.org/bugzilla/show_bug.cgi?id=5666 + +getloadavg.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function getloadavg() is thread safe. + +getpt.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function getpt() is thread safe. + +if_nametoindex.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions if_nametoindex() and if_indextoname() are thread safe. + +index.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions index() and rindex() are thread safe. + +mkfifo.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions mkfifo() and mkfifoat() are thread safe. + +netlink.3 + Michael Kerrisk + SEE ALSO: make the reference for libnetlink the libnetlink(3) man page + +random.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions random(), srandom(), initstate() and setstate() + are thread safe. + +random_r.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions random_r(), srandom_r(), initstate_r() and + setstate_r() are thread safe. + +sigvec.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions sigvec(), sigblock(), sigsetmask() and + siggetmask() are thread safe. + + The macro sigmask() is thread safe. + +sysconf.3 + Michael Kerrisk + SEE ALSO: add confstr(3) + +termios.3 + Michael Kerrisk [Peter Hurley] + Fix error in discussion of MIN > 0, TIME == 0 noncanonical mode + As reported by Peter Hurley, for the MIN > 0, TIME == 0 case: + + read() may unblock when MIN bytes are available but return + up to the 'count' parameter if more input arrives in between + waking and copying into the user buffer. + ... + read() may also _not_ return until MIN bytes have been + received, even if 'count' bytes have been received. + Michael Kerrisk + Add a note on interaction of O_NONBLOCK with noncanonical MIN/TIME + POSIX leaves the behavior open. + Michael Kerrisk + Clarify termination conditions for MIN > 0, TIME > 0 + Michael Kerrisk + Clarify behavior if data is available before noncanonical read() + Michael Kerrisk + Add descriptive titles to noncanonical read() cases + +symlink.7 + Michael Kerrisk + Add subsection on opening a symbolic link with O_PATH + Michael Kerrisk + name_to_handle_at(2) and open_by_handle_at(2) optionally follow symlinks + Michael Kerrisk + Mention use of readlink(2) to read contents of a symlink + + +==================== Changes in man-pages-3.65 ==================== + +Released: 2014-04-20, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alex Thorlton +Ashish Sangwan +Christopher Covington +Christoph Hellwig +Craig McQueen +Dave Chinner +David Prévot +Greg Troxel +Matthew Dempsky +Michael Kerrisk +Mike Frysinger +Namjae Jeon +Peng Haitao +Petr Gajdos +Richard Hansen +Simon Paillard +Steven Stewart-Gallus +Vince Weaver +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +inet_net_pton.3 + Michael Kerrisk + New page describing inet_net_pton(3) and inet_net_ntop(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fallocate.2 + Michael Kerrisk, Namjae Jeon [Christoph Hellwig, Dave Chinner] + Document FALLOC_FL_COLLAPSE_RANGE + +prctl.2 + Michael Kerrisk [Alex Thorlton] + Document PR_SET_THP_DISABLE and PR_GET_THP_DISABLE + +proc.5 + Michael Kerrisk + Document /proc/[pid]/stack + Michael Kerrisk + Document /proc/[pid]/clear_refs + + +New and changed links +--------------------- + +inet_net_ntop.3 + Michael Kerrisk + New link to new inet_net_pton.3 + + +Changes to individual pages +--------------------------- + +fcntl.2 + Michael Kerrisk + Note the race when O_CLOEXEC is used at same time as fork()+execve() + +madvise.2 + Michael Kerrisk + SEE ALSO: see prctl(2) + Because of PR_SET_THP_DISABLE. + +mlock.2 + Michael Kerrisk + Describe treatment of MCL_FUTURE during fork(2) and execve(2) + +msync.2 + Michael Kerrisk [Richard Hansen, Greg Troxel] + Warn that one of MS_SYNC or MS_ASYNC is required + +open.2 + Michael Kerrisk + Add more detail on the race that O_CLOEXEC is designed to avoid + Michael Kerrisk [Matthew Dempsky] + Remove crufty text stating that O_DIRECTORY is Linux-specific + Michael Kerrisk + Note which filesystems support O_TMPFILE + +perf_event_open.2 + Vince Weaver [Michael Kerrisk] + Clarify EACCES and EPERM errors + Clarify the reasons for EACCES and EPERM errors. + Vince Weaver [Michael Kerrisk] + Make the ERRORS section more comprehensive. + Determined both by code inspection and by writing a large + number of test programs. + +personality.2 + Michael Kerrisk + Available execution domains are listed in + Michael Kerrisk + Fix discussion of return value + +prctl.2 + Michael Kerrisk + ERRORS: document EINVAL for PR_GET_NO_NEW_PRIVS + ERRORS: document EINVAL for PR_SET_PDEATHSIG + ERRORS: document EINVAL for PR_SET_TIMING + ERRORS: document EINVAL for PR_SET_DUMPABLE + ERRORS: document EINVAL for PR_SET_NO_NEW_PRIVS + +shmget.2 + Michael Kerrisk + Rewrite description of SHMMNI default value + Michael Kerrisk + Note default value of SHMMAX + Note default value for SHMALL + +byteorder.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions htonl(), htons(), ntohl() and ntohs() are thread + safe. + +fexecve.3 + Michael Kerrisk [Steven Stewart-Gallus] + If 'fd' is a close-on-exec file descriptor for a script, fexecve() fails + See https://bugzilla.kernel.org/show_bug.cgi?id=74481 + +ffs.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions ffs(), ffsl() and ffsll() are thread safe. + +getauxval.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function getauxval() is thread safe. + +getcontext.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions getcontext() and setcontext() are thread safe. + +getsubopt.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function getsubopt() is thread safe. + +getutmp.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions getutmp() and getutmpx() are thread safe. + +inet.3 + Michael Kerrisk + Note success and error return for inet_aton() + +inet.3 + Michael Kerrisk [Craig McQueen] + The form 'a.b' if is suitable for Class A addresses (not class C) + Michael Kerrisk + SEE ALSO: add inet_net_pton(3) + +makecontext.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions makecontext() and swapcontext() are thread safe. + +pthread_attr_setdetachstate.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setdetachstate() and + pthread_attr_getdetachstate() are thread safe. + +pthread_attr_setguardsize.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setguardsize() and + pthread_attr_getguardsize() are thread safe. + +sigsetops.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions sigemptyset(), sigfillset(), sigaddset(), + sigdelset(), sigismember(), sigisemptyset(), sigorset() and + sigandset() are thread safe. + +proc.5 + Petr Gajdos + Improve /proc/[pid]/smaps entries description + Michael Kerrisk + /proc/PID/smaps is present only if CONFIG_PROC_PAGE_MONITOR + Michael Kerrisk + Note kernel version for /proc/sys/kernel/{shmall,shmmax} + Michael Kerrisk + Note kernel version for /proc/sys/kernel/{msgmax,msgmnb} + +capabilities.7 + Michael Kerrisk + SEE ALSO: add capsh(1) + +libc.7 + Michael Kerrisk + Add musl libc + + +==================== Changes in man-pages-3.66 ==================== + +Released: 2014-05-08, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alan Curry +Carsten Andrich +Daniel Borkmann +David Prévot +Eric Siegerman +Heinrich Schuchardt +Jan Kara +Jan Moskyto Matejka +John Marshall +Lukáš Czerner +Manfred Spraul +Michael Kerrisk +Miklos Szeredi +Neil Horman +Peng Haitao +Peter Schiffer +Randy Dunlap +Silvan Jegen +Simon Paillard +Stefan Puiu +Steven Stewart-Gallus +Stijn Hinterding +Willem de Bruijn +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +fanotify_init.2 + Heinrich Schuchardt, Michael Kerrisk + New page documenting fanotify_init(2) + +fanotify_mark.2 + Heinrich Schuchardt, Michael Kerrisk + New page documenting fanotify_mark(2) + +sched_setscheduler.2 + Michael Kerrisk + Page rewritten + Stripped out the general scheduling material, which + moved to sched(7), and rewrote much of the remainder. + Changed copyright and license since pretty much all + of the content was or is written by mtk. + +fanotify.7 + Heinrich Schuchardt, Michael Kerrisk + New page providing overview of the fanotify API + +sched.7 + Michael Kerrisk + New page providing an overview of the scheduling APIs + Most of this content derives from sched_setscheduler(2). In + preparation for adding a sched_setattr(2) page, it makes + sense to isolate out this general content to a separate + page that is referred to by the other scheduling pages. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fallocate.2 + Lukas Czerner [Michael Kerrisk] + Document FALLOC_FL_ZERO_RANGE + FALLOC_FL_ZERO_RANGE was added in Linux 3.14, + for zeroing ranges in the allocated space in a file. + +rename.2 + Miklos Szeredi [Michael Kerrisk] + Document renameat2() system call added in Linux 3.15 + +shmop.2 + Michael Kerrisk + Document SHM_EXEC + + +Changes to individual pages +--------------------------- + +flock.2 + Michael Kerrisk + Employ term "open file description" in DESCRIPTION + And include reference to open(2) for an explanation of the term. + +getpriority.2 + Michael Kerrisk + SEE ALSO: add sched(7) + +getsockopt.2 + Carsten Andrich + SEE ALSO: add packet(7) + +link.2 + Michael Kerrisk [Steven Stewart-Gallus] + Document ENOENT error for linkat() + See https://bugzilla.kernel.org/show_bug.cgi?id=73301 + +msgget.2 + Michael Kerrisk + Reword EEXIST error + +msgop.2 + Michael Kerrisk + Note capability required to raise MQ size beyond MSGMNB + +msync.2 + Michael Kerrisk [Heinrich Schuchardt] + s/flushes... back to disk/flushes... back to filesystem/ + +nice.2 + Michael Kerrisk + SEE ALSO: add sched(7) + +open.2 + Peter Schiffer + Update note on alignment of user buffer and file offset for O_DIRECT + The sentence in open(2) man page in notes for O_DIRECT flag: + + "Under Linux 2.6, alignment to 512-byte boundaries suffices." + + is not universally correct. The alignment is a property of the + storage, for example, 4k-sector drives with no 512 byte sector + emulation will be unable to perform 512-byte direct I/O. + Michael Kerrisk + Note some of the various synonyms for "open file description" + Michael Kerrisk + Remove repetitious text on use of fcntl() to change file status flags + +open_by_handle_at.2 + Michael Kerrisk + Mention FreeBSD analogs + +posix_fadvise.2 + Michael Kerrisk [Eric Siegerman] + Fix wording error under "Architecture-specific variants" + See https://bugzilla.kernel.org/show_bug.cgi?id=75431 + +process_vm_readv.2 + Michael Kerrisk [Stijn Hinterding] + Add feature test macro requirements + The _GNU_SOURCE FTM must be defined. + +read.2 + Michael Kerrisk + BUGS: detail nonatomicity bug with respect to file offset updates + This bug was fixed in Linux 3.14, with commit + 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4 + See also http://thread.gmane.org/gmane.linux.kernel/1649458 + +sched_get_priority_max.2 + Michael Kerrisk + Small changes consistent with migration of content to sched(7) + +sched_rr_get_interval.2 + Michael Kerrisk + Small changes consistent with migration of content to sched(7) + +sched_setaffinity.2 + Michael Kerrisk + Small changes consistent with migration of content to sched(7) + +sched_setparam.2 + Michael Kerrisk + Small changes consistent with migration of content to sched(7) + +sched_yield.2 + Michael Kerrisk + Small changes consistent with migration of content to sched(7) + +semget.2 + Michael Kerrisk + Consolidate discussion on noninitialization of semaphores + The fact that semget() does not initialize the semaphores + in a new set was covered in two places (in DESCRIPTION + and BUGS). Consolidate these into one place (in NOTES) + and also point out that POSIX.1-2008 says that a future + version of the standard may require an implementation to + initialize the semaphores to 0. + Michael Kerrisk + Clarify SEMMNS versus SEMMSL*SEMMNI + Michael Kerrisk + Rework EINVAL text a little + Michael Kerrisk + Clarify wording for EEXIST error + +shmget.2 + Manfred Spraul + Clarify SHMALL + The default for SHMALL is a limit of 8 GB, regardless of + PAGE_SIZE. The current documentation does not mention that + and is therefore more difficult to understand than necessary. + Manfred Spraul + Correct math error + 2097152 is 2^21, not 2^20. + Michael Kerrisk + Reword EEXIST error + Michael Kerrisk + Clarify one of the EINVAL cases + Michael Kerrisk + Note that SHM_NORESERVE is a Linux extension + Michael Kerrisk [Simon Paillard] + Fix kernel version numbers in discussion of SHMALL + Michael Kerrisk + Rework EINVAL text + Michael Kerrisk + Move and rework discussion of mode bits + Michael Kerrisk + Reword description of O_EXCL + +shmop.2 + Michael Kerrisk + Move fork(2), execve(2), _exit(2) discussion to NOTES + Michael Kerrisk + Add subheads for shmat() and shmdt() + Michael Kerrisk + Rework discussion of SHM_RDONLY and SHM_REMAP into list format + Michael Kerrisk + Structure the attach cases as a list + +sigaction.2 + Alan Curry + Fix bad cross reference (times(2) not time(2)) + The system call that reports child CPU usage is times(2), + not time(2). + +symlink.2 + Michael Kerrisk [Steven Stewart-Gallus] + Document ENOENT error for symlinkat() + See https://bugzilla.kernel.org/show_bug.cgi?id=73301 + +syscalls.2 + Michael Kerrisk + Add renameat2() + And bump kernel version. + +write.2 + Michael Kerrisk + BUGS: detail nonatomicity bug with respect to file offset updates + This bug was fixed in Linux 3.14, with commit + 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4 + See also http://thread.gmane.org/gmane.linux.kernel/1649458 + +pthread_attr_setinheritsched.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setinheritsched() and + pthread_attr_getinheritsched() are thread safe. + +pthread_attr_setschedparam.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setschedparam() and + pthread_attr_getschedparam() are thread safe. + +pthread_attr_setschedpolicy.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setschedpolicy() and + pthread_attr_getschedpolicy() are thread safe. + +pthread_attr_setscope.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setscope() and pthread_attr_getscope() + are thread safe. + +pthread_attr_setstack.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setstack() and pthread_attr_getstack() + are thread safe. + +sched_getcpu.3 + Michael Kerrisk + SEE ALSO: add sched(7) + +termios.3 + Michael Kerrisk [Yuri Kozlov] + Rework intro text for 'c_oflag' + Michael Kerrisk + OFDEL is in POSIX.1-2001, so remove "(Not in POSIX)" text + +proc.5 + Jan Moskyto Matejka [Randy Dunlap] + Improve description of /proc/stat 'intr' field + The sum at the beginning of line "intr" includes also + unnumbered interrupts. + +packet.7 + Carsten Andrich [Neil Horman] + Improve sockopt documentation for packet sockets + Carsten Andrich [Willem de Bruijn] + PACKET_LOSS has inverse meaning + Stefan Puiu [Daniel Borkmann, Carsten Andrich] + Status in PACKET_RX_RING is actually a bit mask + Michael Kerrisk [Carsten Andrich] + SEE ALSO: add /tools/testing/selftests/net/psock_tpacket.c + + +==================== Changes in man-pages-3.67 ==================== + +Released: 2014-05-21, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andy Lutomirski +Aurelien Jarno +Bill Allombert +Christoph Hellwig +Davidlohr Bueso +Heinrich Schuchardt +Ingo Schwarze +Jan Kara +Jon Grant +Juri Lelli +Lucas De Marchi +Michael Kerrisk +Peng Haitao +Peter Zijlstra +Rasmus Villemoes +Sam Varshavchik +Simon Paillard +Steven Stewart-Gallus +Török Edwin +William Morriss +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +sched_setattr.2 + Michael Kerrisk, Peter Zijlstra [Juri Lelli] + New page describing sched_setattr(2) and sched_getattr(2) + +system.3 + Michael Kerrisk + Rewrote large parts of the page and added a number of details + + +Newly documented interfaces in existing pages +--------------------------------------------- + +sched.7 + Peter Zijlstra, Michael Kerrisk [Juri Lelli] + Document SCHED_DEADLINE + +New and changed links +--------------------- + +renameat2.2 + Michael Kerrisk + New link to rename.2 + +sched_getattr.2 + Michael Kerrisk + New link to new sched_setattr + + +Changes to individual pages +--------------------------- + +bind.2 + Michael Kerrisk + ERRORS: Add EADDRINUSE for ephemeral port range exhaustion + +chown.2 + Michael Kerrisk + NOTES: Add some subheadings + +connect.2 + Michael Kerrisk [William Morriss] + ERRORS: Add EADDRNOTAVAIL for ephemeral port range exhaustion + Verified from testing and the kernel source. + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=745775 + Michael Kerrisk + Remove mention of ip_local_port_range under EAGAIN error + +create_module.2 +delete_module.2 +init_module.2 +query_module.2 + Michael Kerrisk [Lucas De Marchi] + Clarify glibc header file declaration/ABI wrapper details + create_module(), delete_module(), init_module(), and + query_module() are not declared in header files, but + through an accident of history glibc provides an ABI + for them that it continues to maintain, for + compatibility reasons. + +execve.2 + Michael Kerrisk [Steven Stewart-Gallus] + Note SIGKILL case when execve() fails beyond the point of no return + Michael Kerrisk + NOTES: Add a subheading and reorder paragraphs + +fanotify_init.2 + Heinrich Schuchardt [Michael Kerrisk] + Document range of permitted flags for event_f_flags + With a new patch included in the mm tree, event_f_flags is + checked for allowable values. + +fcntl.2 + Michael Kerrisk + Add "file locking" subheading under NOTES + +fork.2 + Michael Kerrisk + ERRORS: SCHED_DEADLINE tasks can fail with EAGAIN + SCHED_DEADLINE tasks can fail with EAGAIN unless the + reset-on-fork flag is set. + +futex.2 + Michael Kerrisk + Note that there is no glibc wrapper + +getpriority.2 + Rasmus Villemoes + Fix prototypes for getpriority() and setpriority() + The who argument has type id_t (which happens to be u32 on linux). + +get_robust_list.2 + Rasmus Villemoes + Add to synopsis of get_robust_list() + If one were to implement wrappers for [gs]et_robust_list() using the + given prototypes, one would also have to include sys/types.h to get + a definition of size_t. + +getrusage.2 + Michael Kerrisk [Bill Allombert] + _GNU_SOURCE must be defined to obtain RUSAGE_THREAD definition + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=746569 + +link.2 +open.2 + Andy Lutomirski [Michael Kerrisk] + Update AT_EMPTY_PATH and O_PATH documentation + +listen.2 + Michael Kerrisk + ERRORS: Add EADDRINUSE for ephemeral port range exhaustion + +mbind.2 + Rasmus Villemoes + Fix prototype for mbind(2) + The nmask argument is const. The return type in numaif.h is long. + (Well, at least says nmask is const. The current kernel + does not define it as a const argument, but sys_mbind() only + passes it to get_nodes(), which does treat it as const.) + +msgop.2 + Davidlohr Bueso [Michael Kerrisk] + Enhance description of "full queue" criteria + +poll.2 + Rasmus Villemoes + Add to synopsis for ppoll() + One needs to #include to get the definition of the + type (sigset_t) of the mask argument to ppoll(). + +readlink.2 + Rasmus Villemoes + Fix return type of readlinkat() + +recv.2 + Michael Kerrisk + Clarify details of msg_name and msg_namelen fields + +recvmmsg.2 + Michael Kerrisk + Describe timeout bug + See https://bugzilla.kernel.org/show_bug.cgi?id=75371 + and http://thread.gmane.org/gmane.linux.man/5677 + +remap_file_pages.2 + Andy Lutomirski [Christoph Hellwig, Andy Lutomirski] + remap_file_pages() has no benefit for real files + Linux commit 3ee6dafc677a68e461a7ddafc94a580ebab80735 caused + remap_file_pages to be emulated when used on real file. + +sched_get_priority_max.2 + Michael Kerrisk + 'policy' can also be SCHED_DEADLINE + +sched_setaffinity.2 + Rasmus Villemoes + Fix prototype for sched_setaffinity() + The mask argument is const. + +sched_setparam.2 + Michael Kerrisk + ERRORS: mark errors that apply just for sched_setparam() + Michael Kerrisk + ERRORS: Add EINVAL for invalid arguments + Michael Kerrisk + SEE ALSO: add sched_setattr(2) + +sched_setscheduler.2 + Michael Kerrisk + ERRORS: mark errors that apply just to sched_setscheduler() + Michael Kerrisk + ERRORS: add EINVAL case for pid < 0 + Michael Kerrisk + ERRORS: separate out EINVAL cases + +semget.2 + Michael Kerrisk + NOTES: Add subheadings and reorder paragraphs + +semop.2 + Rasmus Villemoes + Fix prototypes for semop() and semtimedop() + The nsops arguments have type size_t, not unsigned, and the + timeout argument of semtimedop() is const. + Michael Kerrisk + NOTES: Add a subheading + +send.2 + Michael Kerrisk + Add details on various 'msghdr' fields + Michael Kerrisk + ERRORS: Add EAGAIN for ephemeral port range exhaustion + Michael Kerrisk + Add some subheadings under DESCRIPTION + +shmget.2 + Michael Kerrisk + NOTES: Add a subheading + +stat.2 + Michael Kerrisk [Aurelien Jarno] + Describe feature test macro requirements for file type test macros + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=728240 + Michael Kerrisk + Update FTM requirements for lstat() + Michael Kerrisk + Split discussion of 'st_mode' fields into type and permissions + Michael Kerrisk + Move text on S_I*() macros to follow text on S_I* macros + That ordering is more logical + +stime.2 + Rasmus Villemoes + Fix prototype for stime() + The argument is const, both according to the actual header files and + according to . + +syscall.2 + Rasmus Villemoes + Fix prototype for syscall() + The first argument and the return value of syscall() has type long, + not int. + +getopt.3 + Michael Kerrisk + EXAMPLE: Add subheadings to distinguish the two example programs + +malloc.3 + Michael Kerrisk + Reword text referring to mallopt(3) + Linux libc is no longer "recent"; drop mention of it. + +pthread_attr_setinheritsched.3 +pthread_attr_setschedparam.3 +pthread_attr_setschedpolicy.3 +pthread_setaffinity_np.3 +pthread_setschedparam.3 +pthread_setschedprio.3 +pthread_yield.3 +pthreads.7 + Michael Kerrisk + Change references to "sched_setscheduler(2)" to "sched(7)" + Change consistent with the fact that the scheduling overview + page is now sched(7) not sched_setscheduler(2). + +pthread_attr_setstackaddr.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setstackaddr() and + pthread_attr_getstackaddr() are thread safe. + +pthread_attr_setstacksize.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_attr_setstacksize() and + pthread_attr_getstacksize() are thread safe. + +pthread_kill.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_kill() is thread safe. + +pthread_kill_other_threads_np.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_kill_other_threads_np() is thread safe. + +pthread_self.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_self() is thread safe. + +pthread_setcancelstate.3 + Michael Kerrisk + Add paragraph breaks to "Asynchronous cancelability" subsection + +pthread_setcancelstate.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_setcancelstate() and + pthread_setcanceltype() are thread safe. + Michael Kerrisk + NOTES: Add some subheadings + +pthread_setschedparam.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_setschedparam() and pthread_getschedparam() + are thread safe. + +pthread_setschedprio.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_setschedprio() is thread safe. + +pthread_sigmask.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_sigmask() is thread safe. + +pthread_sigqueue.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_sigqueue() is thread safe. + +pthread_testcancel.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_testcancel() is thread safe. + +pthread_yield.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_yield() is thread safe. + +remquo.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions remquo(), remquof() and remquol() are thread safe. + +rtime.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function rtime() is thread safe. + +sched_getcpu.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function sched_getcpu() is thread safe. + +stpcpy.3 + Ingo Schwarze + Note some history of stpcpy() + Quoting Ingo: + I just noticed that the stpcpy(3) manual contains a speculation + that appears to be untrue on closer investigation: That function + did not originate in MS DOS, but in Lattice C on AmigaDOS. + + Here is a patch against the git master HEAD to fix that, and add + some more historical information. To provide some background and + allow you to more easily verify the correctness of the patch, i'm + appending my mail to , where i'm giving some + more details about the history and pointing to some primary + sources. That mail also contains the (similar, but shorter) + patch i just committed to the OpenBSD manual page. + +strcasecmp.3 + Michael Kerrisk [Aurelien Jarno, Török Edwin] + Explain why strcasecmp()+strncasecmp() are also declared in + See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=729436 + +strcpy.3 + Michael Kerrisk + NOTES: Add a subheading + +fd.4 + Michael Kerrisk [Sam Varshavchik] + Fix floppy disk device names + The naming convention shown in the page was ancient. + Now, the page is consistent with Documentation/devices.txt + (where it is noted that "The use of the capital letters + D, H and E for the 3.5" models have been deprecated, since + the drive type is insignificant for these devices" + +proc.5 + Michael Kerrisk + Document /proc/timer_stats + Michael Kerrisk + (Briefly) document /proc/timer_list + Michael Kerrisk + Add /proc/sys/kernel/{sched_rt_period_us,sched_rt_runtime_us} + Reference sched(7) for an explanation of these two files + +capabilities.7 + Michael Kerrisk + Mention sched_setattr(2) under CAP_SYS_NICE + +cpuset.7 + Michael Kerrisk + SEE ALSO: add sched(7) + +credentials.7 + Michael Kerrisk + Mention sched_getattr() as a place where credentials are checked + +fanotify.7 + Heinrich Schuchardt [Jan Kara] + BUGS: error events can be lost when reading from fanotify FD + Michael Kerrisk [Heinrich Schuchardt] + Fix description of FAN_EVENT_NEXT() + FAN_EVENT_NEXT() does not update 'meta'; rather, it returns a + pointer to the next metadata structure. In addition, generally + rework the description to be a bit clearer and more detailed. + Heinrich Schuchardt + Document FAN_EVENT_METADATA_LEN + +ip.7 + Michael Kerrisk + Note cases where an ephemeral port is used + Michael Kerrisk + Remove BUGS text on glibc failing to declare in_pktinfo + Michael Kerrisk + Clarify 'ip_local_port_range' and mention the term "ephemeral ports" + Michael Kerrisk + Note some more details about assignment of ephemeral ports + Michael Kerrisk + BUGS: ephemeral port range exhaustion is diagnosed inconsistently + Different system calls use different 'errno' values to diagnose + exhaustion of the ephemeral port range. + +sched.7 + Michael Kerrisk + Document sched_rt_period_us and sched_rt_runtime_us /proc files + And rework and relocate the text on dealing with runaway + real-time processes. + Michael Kerrisk + Mention sched_setattr(2) in list of APIs that can change policies + Michael Kerrisk + sched_setattr(2) can also be used to set 'nice' value + Michael Kerrisk + Remove mention of sched_setscheduler() when talking about sched_priority + There are nowadays multiple ways to set sched_priority (and + in fact there always were, since we also had sched_setparam(2)). + Michael Kerrisk + SEE ALSO: Add Documentation/scheduler/sched-design-CFS.txt + Michael Kerrisk + Don't mention sched_setscheduler(2) in discussions of setting policies + In a couple of places, sched_setscheduler(2) is mentioned as the + way of setting policies. But now there is sched_setattr(2) as + well, rewrite the text in a more generic way. + Michael Kerrisk + Rework summary text describing sched_setattr(2) and sched_getattr(2) + Note that these APIs are a superset of sched_setscheduler(2) + and sched_getscheduler(2). + Michael Kerrisk + Remove crufty text relating to sched_setscheduler() + All of the removed text is in sched_setscheduler(2) and + should have been trimmed from this page. + Michael Kerrisk + SEE ALSO: Mention more files in Documentation/scheduler/ directory + + +==================== Changes in man-pages-3.68 ==================== + +Released: 2014-05-28, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alastair McKinstry +Carsten Grohmann +Colin Williams +Heinrich Schuchardt +Lars Wirzenius +Marko Myllynen +Michael Kerrisk +Peng Haitao +Rasmus Villemoes +Richard Braakman +Simon Paillard + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +localedef.1 + Marko Myllynen, Richard Braakman, Alastair McKinstry, Lars Wirzenius + New page for localedef(1) + Add new page based on Debian localedef(1) page. + + +New and changed links +--------------------- + +procfs.5 + New link to proc.5 + Since the term "procfs" is widely used, it seems reasonable to have + a link from that name to proc(5). + + +Changes to individual pages +--------------------------- + +locale.1 + Marko Myllynen + Provide a step-by-step example of how to use a custom locale + Marko Myllynen + Use LC_TELEPHONE instead of LC_MESSAGES in the example + yesstr/nostr in LC_MESSAGES are planned to be changed at some + point [1], so it's better to provide an example which won't + be obsoleted by that change. + + [1] https://sourceware.org/bugzilla/show_bug.cgi?id=16975 + +adjtimex.2 + Michael Kerrisk + Add feature test macro requirements + +clone.2 + Michael Kerrisk + ERRORS: add cross-reference to fork(2) for explanation of EAGAIN + +fork.2 + Michael Kerrisk + ERRORS: add pid_max and threads-max to EAGAIN + And rewrite text to be the same as pthread_create(3). + +getrlimit.2 + Michael Kerrisk + RLIMIT_NPROC is not enforced if CAP_SYS_ADMIN or CAP_SYS_RESOURCE + +remap_file_pages.2 + Rasmus Villemoes + Fix prototype + The pgoff argument has type size_t, not ssize_t (and in the + kernel it is unsigned long). + +set_mempolicy.2 + Rasmus Villemoes + Fix prototype for set_mempolicy(2) + The nodemask argument is const. The return type in numaif.h is long. + +swapon.2 + Rasmus Villemoes + Remove header from synopsis + The header is not readily available, and the comment + seems to indicate that it is for getting PAGE_SIZE. But it is + never mentioned why one would need to know that, and it is in any + case better obtained using sysconf(), provided by . + +a64l.3 + Rasmus Villemoes + Fix prototype for a64l() + The argument is const, both according to POSIX and the + glibc headers. + +adjtime.3 + Rasmus Villemoes + Add required header + The prototype for adjtime(3) is declared in . + +argz_add.3 + Rasmus Villemoes + Fix prototypes + Update the prototypes of argz_{delete,extract,next} to agree with + glibc headers and manual. + +bstring.3 + Rasmus Villemoes + Fix prototypes + The length parameter n has type size_t in bcmp(), bcopy() and + bzero(). + +envz_add.3 + Rasmus Villemoes + Fix prototypes + The envz_len parameters for envz_entry() and envz_get() are not + passed by reference. + +fpathconf.3 + Rasmus Villemoes + Fix prototype + The path argument to pathconf() is const. + +fseek.3 + Rasmus Villemoes + Fix prototype + The pos argument to fsetpos() is const. + +gcvt.3 + Rasmus Villemoes + Fix prototype + The ndigit parameter to gcvt() has type int. + +getaddrinfo_a.3 + Rasmus Villemoes + Fix prototype + The pointer arguments to gai_suspend() are const. + +getauxval.3 + Rasmus Villemoes + Fix permissions + There doesn't seem to be any reason for getauxval.3 to be + executable... + +getnameinfo.3 + Rasmus Villemoes + Fix prototype + The hostlen and servlen parameters have type socklen_t. + (The types changed in glibc 2.2) + Michael Kerrisk + Note types of 'hostlen'; and 'servlen' in glibc < 2.2 + +getrpcent.3 + Rasmus Villemoes + Fix prototype + The argument to getrpcbyname() is const. + +getrpcport.3 + Rasmus Villemoes + Add #include and fix prototype + The prototype for getrpcport() is obtained by #include'ing + . Also, update its prototype. + +getspnam.3 + Rasmus Villemoes + Fix prototype + The struct spwd argument to putspent() is const. + +getutent.3 + Rasmus Villemoes + Fix prototypes + The arguments to getutid(), getutline(), and pututline() + are const. + +inet.3 + Rasmus Villemoes + Fix prototype + The parameters to inet_makeaddr have type in_addr_t. + +inet_net_pton.3 + Rasmus Villemoes + srcfix, cfix + Use a consistent style throughout the man-pages. + +key_setsecret.3 + Rasmus Villemoes + Fix prototypes + Remove const qualifiers from arguments to key_decryptsession, + key_encryptsession, and key_setsecret. + +makecontext.3 + Rasmus Villemoes + Fix prototype + The second argument to swapcontext() is const. + +makedev.3 + Rasmus Villemoes + Fix prototype + gnu_dev_makedev, and hence its trivial macro wrapper makedev, takes + two unsigned int parameters; this is consistent with it being the + inverse of (gnu_dev_)major/minor, which return unsigned int. + +malloc_trim.3 + Rasmus Villemoes + Fix prototype + As mentioned further down, malloc_trim returns an integer. + +mq_getattr.3 + Rasmus Villemoes + Fix prototype + The newattr parameter to mq_setattr is const. + +newlocale.3 + Marko Myllynen + List all available category masks + Michael Kerrisk + Add LC_ALL_MASK description + +nl_langinfo.3 + Marko Myllynen + Expand the example code a bit + Better illustrate querying elements from different categories. + +perror.3 + Rasmus Villemoes + Fix declaration + The elements of the array sys_errlist are also const. + +pthread_attr_setaffinity_np.3 +pthread_attr_setdetachstate.3 +pthread_attr_setguardsize.3 +pthread_attr_setinheritsched.3 +pthread_attr_setschedparam.3 +pthread_attr_setschedpolicy.3 +pthread_attr_setscope.3 +pthread_attr_setstack.3 +pthread_attr_setstackaddr.3 +pthread_attr_setstacksize.3 + Rasmus Villemoes + Constify parameters + Each of the pthread_attr_get* functions extract some piece of + information from a pthread_attr_t, which is passed by const + reference. Add the const keyword to the prototypes of these + functions. + +pthread_cleanup_push_defer_np.3 + Michael Kerrisk [Rasmus Villemoes] + Add feature test macro requirements + +pthread_create.3 + Michael Kerrisk [Carsten Grohmann] + Add pid_max limit to EAGAIN error cases + +pthread_equal.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_equal() is thread safe. + +pthread_exit.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_exit() is thread safe. + +pthread_getcpuclockid.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function pthread_getcpuclockid() is thread safe. + +pthread_setaffinity_np.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_setaffinity_np() and + pthread_getaffinity_np() are thread safe. + +pthread_setconcurrency.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions pthread_setconcurrency() and + pthread_getconcurrency() are thread safe. + +pthread_setname_np.3 + Rasmus Villemoes + Fix prototype + The name parameter of pthread_getname_np is an output parameter and + hence not const. + +pthread_setschedparam.3 + Rasmus Villemoes + Fix prototypes + Add return type for pthread_{s,g}etschedparam. + +pthread_setschedprio.3 + Rasmus Villemoes + Fix prototype + Add return type for pthread_setschedprio. + +pthread_sigqueue.3 + Rasmus Villemoes + Add missing #include + +rcmd.3 + Rasmus Villemoes + Fix prototypes + Unlike the BSDs, the second argument of rcmd() and rcmd_af() has + type unsigned short. + The first argument of iruserok_af() has type const void*. + +re_comp.3 + Rasmus Villemoes + Fix prototypes + re_comp and re_exec take const char* arguments. + +resolver.3 + Rasmus Villemoes + Fix prototypes and extern-declaration + Fix const- and signedness of various char* parameters. + + Also, there is no "struct state", but _res is a struct + __res_state. (Actually, _res is errno-like in that it is really a + macro expanding to (*__res_state()).) + +rexec.3 + Rasmus Villemoes + Fix prototypes + The user, passwd and cmd arguments to rexec and rexec_af are all + const. + +rtime.3 + Rasmus Villemoes + Replace header + The header does not provide rtime(); + does, as is also implied in both the NOTES and + EXAMPLE sections. + +scandir.3 + Rasmus Villemoes + Fix prototypes + The alphasort and versionsort functions take arguments of type + const struct dirent **, not const void *. + +setlocale.3 + Michael Kerrisk [Marko Myllynen] + Simplify locale category listing and add GNU-specific locale categories + Some information that was here will move to locale(7). + Marko Myllynen + Remove now obsolete NOTES section + +setnetgrent.3 + Rasmus Villemoes + Fix prototype + The buflen argument to getnetgrent_r has type size_t. + +sigvec.3 + Rasmus Villemoes + Fix prototype + The vec argument to sigvec is const. + +tsearch.3 + Rasmus Villemoes + Fix prototype + The rootp argument to tfind is "void * const *", + not "const void **". + +core.5 + Michael Kerrisk + Core dump files are nowadays core.pid by default + +locale.5 + Marko Myllynen + Document mon_grouping and grouping properly + Michael Kerrisk + Note default value for 'first_workday' + Michael Kerrisk [Marko Myllynen] + Add brief descriptions of collating-element and collating-symbol + Marko Myllynen + t_fmt_ampm is needed only for locales that employ AM/PM convention + Michael Kerrisk [Marko Myllynen] + Remove crufty reference to /usr/lib/nls/src + That file is nowhere to be found + Marko Myllynen + Clarify LC_TIME/am_pm and LC_NAME keywords usage + am_pm should be defined only if AM/PM convention is used to signal + applications they should not try to print them when using them in + unwanted. + + Same for all LC_NAME keywords expect for name_fmt which should be + always defined. + Marko Myllynen + Clarify lang_term / lang_lib + As noted by Keld Simonsen in the lib-locales@sourceware mailing + list: + + https://sourceware.org/ml/libc-locales/2014-q2/msg00008.html + From: Keld Simonsen + To: Marko Myllynen + Date: Tue, 29 Apr 2014 17:02:09 +0200 + + lang_term reflects ISO 639-2/T (terminology) codes, while + lang_lib reflects ISO 639-2/B (bibliographic) codes. + lang_term is preferred over lang_lib codes for locale names. + There are 20 specific ISO 639-2/B codes. + Marko Myllynen + Correct the FILES section + +proc.5 + Michael Kerrisk + 'pid_max' is a system-wide limit on number of threads and processes + Since PIDs > /proc/sys/kernel/pid_max are not allocated, this + file thus also imposes a system-wide limit on the number of + threads and processes. + +capabilities.7 + Michael Kerrisk + CAP_SYS_ADMIN allows overriding RLIMIT_NPROC + Michael Kerrisk + CAP_SYS_PTRACE allows process_vm_readv(2) and process_vm_writev(2) + +charsets.7 + Michael Kerrisk [Marko Myllynen] + Remove crufty statement that Romanian may be switching to ISO 8859-16 + Michael Kerrisk + Remove ancient paragraph on charsets supported in glibc 2.3.2 + That test is rather ancient, and probably of little use. + +fanotify.7 + Heinrich Schuchardt + Fix to example program: fanotify read() should use aligned buffer + +inotify.7 + Heinrich Schuchardt + Add example program + This example of the usage of the inotify API shows the + usage of inotify_init1(2) and inotify_add_watch(2) as well + as polling and reading from the inotify file descriptor. + Heinrich Schuchardt + munmap() does not generate inotify events + +locale.7 + Marko Myllynen [Michael Kerrisk] + Document the LOCPATH environment variable + Michael Kerrisk + Add further details on various categories + + + +==================== Changes in man-pages-3.69 ==================== + +Released: 2014-06-14, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Cyril Hrubis +Jan Chaloupka +Jeff Layton +Kirill A. Shutemov +KOSAKI Motohiro +Marko Myllynen +Michael Kerrisk +NeilBrown +Peng Haitao +Petr Gajdos +Qian Lei +Rasmus Villemoes +Vasiliy Kulikov +Walter Harms +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +iconv.1 + Marko Myllynen [Michael Kerrisk] + New page for the iconv(1) command + +iconvconfig.8 + Marko Myllynen + New page for iconvconfig(8) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fcntl.2 + Jeff Layton, Michael Kerrisk + Document open file description locks + As provided by the fcntl() operations F_OFD_SETLK, + F_OFD_SETLKW, and F_OFD_GETLK + + +Changes to individual pages +--------------------------- + +locale.1 + Marko Myllynen + Add FILES section, add charmap(5) reference + Marko Myllynen + Align with recent charmap(5) / repertoiremap(5) changes + +execve.2 + Michael Kerrisk [NeilBrown] + Before kernel 2.6.0, RLIMIT_NPROC had no effect for set*uid() + Michael Kerrisk [Vasiliy Kulikov] + RLIMIT_NPROC is checked only if preceded by set*uid() + Michael Kerrisk [Vasiliy Kulikov, NeilBrown, KOSAKI Motohiro] + Document EAGAIN error + See also https://bugzilla.kernel.org/show_bug.cgi?id=42704 + +fcntl.2 + Michael Kerrisk + Detail the limitations of traditional (process-associated) locks + Michael Kerrisk [Jeff Layton] + Describe how to check whether the kernel supports a particular command + Michael Kerrisk + ERRORS: add EINVAL for invalid 'cmd' + Michael Kerrisk + Add para introducing advisory locks and noting existence of OFD locks + Michael Kerrisk [Jeff Layton] + Add notes on F_SETLKW deadlock detection and its limitations + Michael Kerrisk + Add an explicit note that mandatory locking is not in POSIX + Michael Kerrisk + Rewrite introductory paragraphs on mandatory locking + Make the structure more logical, and also explicitly mention + OFD locks. + Michael Kerrisk [Jeff Layton] + Reword discussion of mandatory lock bug a little + Jeff Layton confirmed that the bug remains even in modern kernels. + Michael Kerrisk + Explain POSIX background to EACCES/EAGAIN error for F_GETLK + Michael Kerrisk + Add NOTES subhead for record locking and NFS + Michael Kerrisk [NeilBrown] + Note treatment of locks when an NFS client loses contact with the server + Michael Kerrisk [Jeff Layton] + nfsv4leasetime controls the "contact lost" interval for NFSv4 + +flock.2 + Michael Kerrisk + In some modern BSDs, fcntl() and flock() locks do interact + So, reword and extend the discussion of this topic in NOTES. + Michael Kerrisk + Move NOTES text describing implementation of flock() + Michael Kerrisk [NeilBrown] + Add more details on NFS, including Linux 2.6.37 changes + Also: move NOTES text describing interaction of fcntl() + and flock() locks. + +fork.2 + Michael Kerrisk + Add notes on inheritance of flock() and OFD locks across fork() + +lseek.2 + Michael Kerrisk + Add reference to open(2) for discussion of file descriptors and OFDs + +open.2 + Michael Kerrisk + Rework and extend the discussion of open file descriptions + +open_by_handle_at.2 + Rasmus Villemoes + Add reference to feature_test_macros(7) + +recvmmsg.2 + Rasmus Villemoes + Add reference to feature_test_macros(7) + +remap_file_pages.2 + Michael Kerrisk [Kirill A. Shutemov] + Note that remap_file_pages() is deprecated + +sendmmsg.2 + Rasmus Villemoes + Add reference to feature_test_macros(7) + +seteuid.2 + Michael Kerrisk + seteuid() and setegid() are implemented as library functions + Michael Kerrisk + Error checking should always be performed, even when caller is UID 0 + +setresuid.2 + Michael Kerrisk + Document EAGAIN error that can occur after kernel alloc_uid() failure + Michael Kerrisk + Since Linux 3.1, the EAGAIN case for RLIMIT_NPROC no longer occurs + Michael Kerrisk + Correct the description of the EAGAIN error + Michael Kerrisk + Error checking should always be performed, even when caller is UID 0 + +setreuid.2 + Michael Kerrisk + Document EAGAIN error that can occur after kernel alloc_uid() failure + Michael Kerrisk + Error checking should always be performed, even when caller is UID 0 + Michael Kerrisk + Add EAGAIN error for hitting RLIMIT_NPROC limit + Michael Kerrisk + Since Linux 3.1, the EAGAIN case for RLIMIT_NPROC no longer occurs + +setuid.2 + Michael Kerrisk + Document EAGAIN error that can occur after kernel alloc_uid() failure + Michael Kerrisk + Correct the description of the EAGAIN error + Michael Kerrisk + Error checking should always be performed, even when caller is UID 0 + Michael Kerrisk + Since Linux 3.1, the EAGAIN case for RLIMIT_NPROC no longer occurs + +statfs.2 + Cyril Hrubis + Update MAGIC constants + Most of the updates are taken from /usr/include/linux/magic.h, + some were found by grepping the Linux source code. + Cyril Hrubis [Michael Kerrisk] + fstatfs(2) was broken on file descriptors from pipe(2) + +syscalls.2 + Michael Kerrisk + Note that remap_file_pages() is deprecated + +basename.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions basename() and dirname() are thread safe. + +catgets.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function catgets() is thread safe. + +getdate.3 + Rasmus Villemoes + Use blank definition of _GNU_SOURCE in example program + +getdirentries.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function getdirentries() is thread safe. + +getdtablesize.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function getdtablesize() is thread safe. + +iconv.3 + Qian Lei [Peng Haitao] + ATTRIBUTES: Note function that is thread-safe + The function iconv() is thread safe. + Michael Kerrisk + SEE ALSO: add iconvconfig(8) + +lockf.3 + Qian Lei [Peng Haitao] + ATTRIBUTES: Note function that is thread-safe + The function lockf() is thread safe. + +malloc_get_state.3 + Rasmus Villemoes + SYNOPSIS: use correct header + The nonstandard functions malloc_set_state() and + malloc_get_state() are provided by not . + +malloc_usable_size.3 + Qian Lei + ATTRIBUTES: Note function that is thread-safe + The function malloc_usable_size() is thread safe. + +matherr.3 + Qian Lei [Peng Haitao] + ATTRIBUTES: Note function that is thread-safe + The function matherr() is thread safe. + +mkdtemp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function mkdtemp() is thread safe. + +mkstemp.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions mkstemp(), mkostemp(), mkstemps() and mkostemps() + are thread safe. + +mq_close.3 + Qian Lei + ATTRIBUTES: Note function that is thread-safe + The function mq_close() is thread safe. + +mq_getattr.3 + Qian Lei + ATTRIBUTES: Note function that is thread-safe + The functions mq_getattr() and mq_setattr() are thread safe. + +mq_open.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function mq_open() is thread safe. + +mq_receive.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions mq_receive() and mq_timedreceive() are thread safe. + +mq_send.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions mq_send() and mq_timedsend() are thread safe. + +mq_unlink.3 + Qian Lei + ATTRIBUTES: Note function that is thread-safe + The function mq_unlink() is thread safe. + +posix_fallocate.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function posix_fallocate() is thread safe. + +posix_openpt.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function posix_openpt() is thread safe. + +siginterrupt.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function siginterrupt() is not thread safe. + +system.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function system() is thread safe. + +charmap.5 + Marko Myllynen + Update to match current glibc + charmap(5) was outdated, bring it to closer to reality by fixing + syntax descriptions to match current glibc code and practices, + adding missing options, removing obsolete comments and references, + and removing now incorrect examples. + +locale.5 + Marko Myllynen + Clarify AM/PM settings a bit + localedef(1) complains if really undefined, should be empty instead. + Also: add some SEE ALSO references. + Marko Myllynen + Document glibc conventions regarding days and week + Based on existing practice and glibc community wiki page at + https://sourceware.org/glibc/wiki/Locales + +proc.5 + Michael Kerrisk [Jan Chaloupka, Walter Harms] + Add a brief description of /proc/fs + +repertoiremap.5 + Marko Myllynen + New page for repertoiremap(5) + Rather obsolete feature but localedef(1) refers to repertoiremaps. + +bootparam.7 + Petr Gajdos + Describe 'rootflags' and 'rootdelay' kernel parameters + Patch based on text from Documentation/kernel-parameters.txt + +charsets.7 + Marko Myllynen + Update to reflect past developments + Rewrite the introduction to make Unicode's prominence more obvious. + Reformulate parts of the text to reflect current Unicode world. + Minor clarification for ASCII/ISO sections, some other minor fixes. + Marko Myllynen + List CJK encodings in the order of C, J, K + +environ.7 + Michael Kerrisk + SEE ALSO: add env(1), printenv(1), ld.so(8) + +locale.7 + Marko Myllynen + Add some SEE ALSO references + +man-pages.7 + Michael Kerrisk + Note that .TH 'date' field is nowadays automatically updated by scripts + +signal.7 + Michael Kerrisk + Describe EINTR semantics for recvmmsg(2) + Michael Kerrisk + Clarify text describing EINTR semantics for socket interfaces + +unicode.7 + Marko Myllynen + Update to reflect past developments + The unicode(7) page will look more modern with few small changes: + + - drop old BUGS section, editors cope with UTF-8 ok these days, + and perhaps the state-of-the-art is better described elsewhere + anyway than in a man page + - drop old suggestion about avoiding combined characters + - refer to LANANA for Linux zone, add registry file reference + - drop a reference to an inactive/dead mailing list + - update some reference URLs + +utf-8.7 + Marko Myllynen + Drop an old comment about UTF-8 replacing ISO 8859 + And add locale(1) under SEE ALSO. + + +==================== Changes in man-pages-3.70 ==================== + +Released: 2014-07-08, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Carlos O'Donell +Elie De Brauwer +Florian Weimer +Heinrich Schuchardt +Marko Myllynen +Michael Kerrisk +Nadav Har'El +NeilBrown +Rich Felker +Robert P. J. Day +Simon Paillard +Tomi Salminen +Walter Harms +Yuri Kozlov +Кирилл + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +sprof.1 + Michael Kerrisk [Marko Myllynen] + New page for the glibc sprof(1) command + + +Newly documented interfaces in existing pages +--------------------------------------------- + +epoll_ctl.2 + NeilBrown + Document EPOLLWAKEUP + +epoll.7 + NeilBrown + Document EPOLLWAKEUP + + +Changes to individual pages +--------------------------- + +iconv.1 +iconvconfig.8 + Marko Myllynen + Clarify gconv file terminology a bit + +ldd.1 + Michael Kerrisk + SEE ALSO: add sprof(1) + +connect.2 + Michael Kerrisk + ERRORS: add EPROTOTYPE + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=708394 + +dup.2 + Michael Kerrisk [Rich Felker] + Fix erroneous discussion regarding closing 'newfd' before calling dup2() + And propose a workaround if the caller cares about catching + close() time errors. + + See http://stackoverflow.com/questions/23440216/race-condition-when-using-dup2#comment36888604_23444465 + and http://austingroupbugs.net/view.php?id=411 + Michael Kerrisk + Rework and enhance discussion of dup2() + In particular, note that dup2() performs the steps of closing + and reusing 'newfd' atomically. + Michael Kerrisk + Add subhead for dup3() + +epoll_ctl.2 + Michael Kerrisk + BUGS: EPOLLWAKEUP is silently ignored without CAP_BLOCK_SUSPEND + If the caller does not have CAP_BLOCK_SUSPEND, then EPOLLWAKEUP + is silently ignored. + +fcntl.2 + Michael Kerrisk [Tomi Salminen] + The return value for F_SETPIPE_SZ is the pipe capacity + Michael Kerrisk + ERRORS: Document ENOTDIR error for F_NOTIFY + Michael Kerrisk + Use proper page cross-references in F_NOTIFY discussion + Michael Kerrisk + Suggest the use of real-time signals with F_NOTIFY + +getitimer.2 + Michael Kerrisk + Rewrite a few pieces to clarify some details + +inotify_add_watch.2 + Michael Kerrisk + Clarify that the target of a watch is an i-node + The target of a watch is an i-node, not a pathname. Clarify + the text to prevent the reader possibly misunderstanding + that establishing watches by two different links to the same + file might create different watch descriptors. + +open.2 + Michael Kerrisk [Кирилл] + O_CLOEXEC is also one the flags not ignored when O_PATH is specified + +pipe.2 + Elie De Brauwer + PIPE_BUF is defined in limits.h + To make use of PIPE_BUF in an application one should include + . Adding a reference to this inclusion. + +poll.2 + Michael Kerrisk [Nadav Har'El] + The negate-fd-to-ignore technique does not work for file descriptor 0 + See https://bugzilla.kernel.org/show_bug.cgi?id=79411 + +set_tid_address.2 + Michael Kerrisk [Rich Felker] + Use "thread" rather than "process" in DESCRIPTION + Michael Kerrisk + SEE ALSO: add gettid(2) + +shmop.2 + Michael Kerrisk + Explain SHMLBA in much more detail + +splice.2 + Michael Kerrisk + Document EAGAIN error + See https://bugzilla.kernel.org/show_bug.cgi?id=48641 + +syscalls.2 + Carlos O'Donell + Add prlimit64(2) + While trying to reconcile the new features in glibc with the + documented entries in the linux kernel man pages I noticed that + glibc exports prlimit64 for use by 32-bit applications (as does + the linux kernel), but that prlimit64 was not defined in the + syscalls list or in the prlimit-related page. + + This is not the complete fix for this, but I don't have the time + to explain why and when prlimit64 should be used (or how it should + be used safely). Therefore I'm just patching the syscalls.2 list + to show that prlimit64 exists and was added in 2.6.36 (verified + with git by checking out the tags before and after). + +syslog.2 + Michael Kerrisk + Rework introductory paragraph + Michael Kerrisk [Robert P. J. Day] + Rework text describing loglevels + The kernel header file mentioned in the discussion of the KERN_* + constants has morphed and is no longer exported inside glibc. + And the definitions of the constants themselves changed subtly + with kernel commit 04d2c8c83d0e3ac5f78aeede51babb3236200112. + So, rewrite the description of the constants to be a bit more + abstract. + Michael Kerrisk + Rewrite parts of the page, and import /proc/sys/kernel/printk + * Move /proc/sys/kernel/printk from proc(5) to this page, + and correct various details in the discussion of that file. + * Rewrite and correct various other details on the page. + * Clean out some crufty text. + * Miscellaneous minor fixes. + Michael Kerrisk + Update SYSLOG_ACTION_CONSOLE_OFF + SYSLOG_ACTION_CONSOLE_ON description + Details changed in Linux 2.6.32 + +tee.2 + Michael Kerrisk + Document EAGAIN error + See https://bugzilla.kernel.org/show_bug.cgi?id=48641 + +vmsplice.2 + Michael Kerrisk + Document EAGAIN error + See https://bugzilla.kernel.org/show_bug.cgi?id=48641 + +ether_aton.3 + Michael Kerrisk + Make description of ether_line() bug a little more informative + +mallopt.3 + Michael Kerrisk [Florian Weimer] + MALLOC_MMAP_THRESHOLD_ and MALLOC_MMAP_MAX_ *do* work in setgid programs + My testing on this point was bogus, overlooking details of + strace(1)'s behavior with setuid programs. + + See https://sourceware.org/bugzilla/show_bug.cgi?id=12155 + +printf.3 + Michael Kerrisk [Rich Felker] + Remove libc4 and libc5 details + Rich Felker noted that "scare text" in the man page warned about + the use of snprintf() on libc, and that some people had cited + this as a reason not to use snprintf(). Linux libc is now + ancient history, so there is no real need to keep that text. + But, while we're at it, we may as well clear out all of the + other ancient libc4 and libc5 pieces in the page. They are + nowadays more clutter than help. + Michael Kerrisk + SUSv3 and later agree with C99 for the snprintf() return value + Determined by inspection of the SUSv3 and SUSv4 specifications. + Michael Kerrisk + Remove some old text about glibc 2.0 changes + We probably don't now need such ancient info. + Michael Kerrisk + Update references to standards for C and S conversion specifiers + +profil.3 + Michael Kerrisk + SEE ALSO: add sprof(1) + +charmap.5 + Marko Myllynen + Various minor updates and improvements + - more precise title + - extend description a bit + - document previously omitted WIDTH_DEFAULT + Marko Myllynen + Remove accidental ISO C compliance reference + glibc refers in locale/programs/charmap.c to ISO C 99 section + 7.17.(2) and ISO C 99 section 5.2.1.(3) that if a character map + is not ASCII compatible then the locale using it is not ISO C + compliant. This does not state anything about the character set + itself. + +proc.5 + Michael Kerrisk + Replace /proc/sys/kernel/printk discussion with reference to syslog(2) + It makes more sense to have the /proc/sys/kernel/printk with + the related material in syslog(2). + Michael Kerrisk + Rewrite /proc/sys/kernel/printk description + +inotify.7 + Michael Kerrisk + Clarify which events are generated for watched directories + Really, with respect to watched directories, events fall into + three classes (not two, as was shown): + + * Events that can be generated only for the watched directory. + * Events that can be generated only for objects that are inside + the watched directory. + * Events that can be generated both for the watched directory + and for objects inside the directory. + + So, mark these three classes more clearly in the list of inotify + events. + Heinrich Schuchardt [Michael Kerrisk] + BUGS: Note possible bug triggered by watch descriptor reuse + Watch descriptor IDs are returned by inotify_add_watch(). + When calling inotify_rm_watch() an IN_IGNORED is placed on the + inotify queue pointing to the ID of the removed watch. + + inotify_add_watch() should not return a watch descriptor ID for + which events are still on the queue but should return an + unused ID. + + Unfortunately, the existing Kernel code does not provide such a + guarantee. + + Actually, in rare cases watch descriptor IDs are returned by + inotify_add_watch() for which events are still on the inotify + queue. + + See https://bugzilla.kernel.org/show_bug.cgi?id=77111 + Michael Kerrisk + Add further detail to the watch descriptor reuse bug + As well as inotify_rm_watch(), file deletion and unmounting a + filesystem can also cause a watch descriptor to be deleted. + Michael Kerrisk + The watch descriptor reuse bug may be hard to hit in practice + Explain the circumstances in detail, indicating that the + bug may be very unlikely to occur in practice. + Michael Kerrisk + Clarify description of IN_EXCL_UNLINK + Clarify the text a little, in particular making it clearer + that the target of a watch is an i-node (not a pathname). + Michael Kerrisk + Clarify IN_ONESHOT explanation + Make it clearer that the target of monitoring is an i-node, + not a pathname. + Michael Kerrisk + Make comment on 'mask' field more accurate + +libc.7 + Michael Kerrisk + Clarify man-pages policy on documenting C libraries other than glibc + Michael Kerrisk + Use absolute dates in discussion of libc vs glibc + +pipe.7 + Elie De Brauwer + Add reference that the pipe capacity can be changed + In fcntl(2) F_SETPIPE_SZ, F_GETPIPE_SZ and + /proc/sys/fs/pipe-max-size are defined, however + pipe(7) still defines the pipe capacity as being + a static entity. Adding a reference to fcntl(2). + Michael Kerrisk [Walter Harms] + Clarify that since 2.6.35, 65535 bytes is the default pipe capacity + +ld.so.8 + Michael Kerrisk + Clarify that LD_PROFILE can specify just a single shared object + Michael Kerrisk + Clarify that LD_PROFILE output is appended to target file + The LD_PROFILE output is appended to any existing + contents of the target file. + Michael Kerrisk + SEE ALSO: add sprof(1) + + +==================== Changes in man-pages-3.71 ==================== + +Released: 2014-08-17, Chicago + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Adrian Bunk +Damir Nedzibovic +David Prévot +D. Barbier +Jakub Wilk +Jan Chaloupka +Marko Myllynen +Michael Kerrisk +Mike Frysinger +NeilBrown +Paul Jackson +Peng Haitao +Rahul Bedarkar +Rob Landley +Ryan Hammonds +Simon Paillard +Ville Ylenius +Vince Weaver +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +group_member.3 + Michael Kerrisk + New page documenting group_member(3) + +isfdtype.3 + Michael Kerrisk + New page documenting isfdtype(3) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +perf_event_open.2 + Vince Weaver + Document new comm_exec flag + Linux 3.16 (more specifically, commit 82b897782d10fcc4 ) + added support for differentiating between process renames + caused by exec versus those caused by other methods. + Vince Weaver + Document new mmap2 record type + Linux 3.16 (more specifically, commit a5a5ba72843dd05f9 ) + enabled the enhanced mmap2 record support. + The interface was added in Linux 3.12 but disabled until + Linux 3.16. + Vince Weaver + Document PERF_SAMPLE_BRANCH_COND + Linux 3.16 (more specifically, commit bac52139f0b7ab31330 ) + adds support for gathering PERF_SAMPLE_BRANCH_COND + conditional branch values when doing PERF_SAMPLE_BRANCH_STACK + sampling. + +proc.5 + Michael Kerrisk + Document /proc/PID/comm + Michael Kerrisk + Document /proc/PID/pagemap + Michael Kerrisk + Document /proc/PID/personality + Michael Kerrisk + Document /proc/PID/syscall + Michael Kerrisk + Document /proc/kpagecount + Michael Kerrisk + Document /proc/kpageflags + Michael Kerrisk + Document /proc/sys/vm/overcommit_kbytes + +capabilities.7 + Michael Kerrisk + Add CAP_AUDIT_READ + CAP_AUDIT_READ is new in Linux 3.16. + + +Global changes +-------------- + +ldd.1 +clone.2 +execve.2 +getpagesize.2 +ioperm.2 +msgop.2 +readv.2 +recv.2 +select.2 +send.2 +seteuid.2 +shmop.2 +signal.2 +sync.2 +sysinfo.2 +utime.2 +abs.3 +atoi.3 +catopen.3 +clearenv.3 +ctime.3 +des_crypt.3 +ecvt.3 +flockfile.3 +fseeko.3 +ftime.3 +ftok.3 +ftw.3 +getcwd.3 +getdtablesize.3 +getline.3 +getpass.3 +getpass.3 +getutent.3 +glob.3 +insque.3 +lseek64.3 +memmem.3 +mkstemp.3 +mktemp.3 +on_exit.3 +openpty.3 +putenv.3 +putenv.3 +qecvt.3 +realpath.3 +realpath.3 +remove.3 +setbuf.3 +sigpause.3 +strftime.3 +strptime.3 +tzset.3 +xcrypt.3 +utmp.5 +environ.7 +ipv6.7 +packet.7 + Michael Kerrisk + Remove ancient Linux libc details + +access.2 +brk.2 +chmod.2 +eventfd.2 +gethostname.2 +getpriority.2 +mmap.2 +poll.2 +ptrace.2 +readv.2 +sched_setaffinity.2 +select.2 +seteuid.2 +signalfd.2 +sync_file_range.2 +timer_create.2 +uname.2 +wait.2 + Michael Kerrisk + NOTES: add "C library/kernel ABI differences" subheading + + +Changes to individual pages +--------------------------- + +access.2 + Michael Kerrisk + Glibc falls back to using access() on kernels that lack faccessat() + +bdflush.2 +fsync.2 +sync.2 +proc.5 + Adrian Bunk + Change "sync(1)" to "sync(8)" + +bind.2 + Michael Kerrisk [Ryan Hammonds] + Correct EINVAL error description + As pointed out by Ryan: + + My application is trying to bind an IPv4 UDP socket to an + address. I've found that passing an invalid address length + to bind() causes bind to return EINVAL. According to the + bind(2) manpage, this should only occur when using unix + domain sockets (which I am not). + +chmod.2 + Michael Kerrisk + Glibc falls back to chmod() on kernels that don't support fchmodat() + Michael Kerrisk + Glibc falls back to chown()/lchown() on kernels that lack fchownat() + +epoll_wait.2 + Michael Kerrisk + NOTES: describe raw epoll_pwait() system call differences + +getgroups.2 + Michael Kerrisk + SEE ALSO: add group_member(3) + +getpriority.2 + Michael Kerrisk + Enhance discussion of kernel nice range versus user-space nice range + Michael Kerrisk + Move text describing nice range on other systems + +getrlimit.2 + Michael Kerrisk + Add cross reference to core(5) in discussion of RLIMIT_CORE + Michael Kerrisk + Describe the "large" resource limit bug on 32-bit platforms + See https://bugzilla.kernel.org/show_bug.cgi?id=5042. + Michael Kerrisk + Glibc's setrlimit() and getrlimit() are implemented using prlimit() + +kexec_load.2 + Michael Kerrisk + Note limit of 16 for 'nr_segments' + Michael Kerrisk + Clarify the 'flags' bits that contain the architecture + Michael Kerrisk + Add KEXEC_ARCH_68K to list of architectures for 'flags' + Michael Kerrisk + Reword description of 'flags' a little + +link.2 + Michael Kerrisk + Glibc falls back to link() on kernels that lack linkat() + Unless 'flags' contains AT_SYMLINK_FOLLOW. + +mkdir.2 + Michael Kerrisk + Glibc falls back to mkdir() on kernels that don't support mkdirat() + +perf_event_open.2 + Vince Weaver + Clarify PERF_SAMPLE_STACK_USER usage + This clarifies the PERF_SAMPLE_STACK_USER section. + I found these issue while implementing some code that uses + the option. The important change is fixing the name of the + sample_stack_user parameter, the rest is just some wording + fixes and minor clarifications. + Vince Weaver + Clarify PERF_SAMPLE_DATA_SRC usage + When checking the fields in the PERF_SAMPLE_DATA_SRC type samples + you need to shift the masks before doing the compare. + + Although the value you are checking (perf_mem_data_src) is + specified as a bitfield so this might all fall apart if trying + to access the field in a cross-endian way. The Power people + were working on this issue, not sure if they resolved it. + +poll.2 + Michael Kerrisk + Describe fifth argument (sigsetsize) of raw ppoll() system call + +process_vm_readv.2 + Michael Kerrisk [Ville Ylenius] + Fix typo in example program + +readlink.2 + Michael Kerrisk + Glibc falls back to readlink() on kernels that lack readlinkat() + +recv.2 + Michael Kerrisk + 'addrlen' should be NULL (not 0) if we don't need sender address + +rename.2 + Michael Kerrisk + Glibc falls back to rename() when the kernel doesn't have renameat() + +sigwaitinfo.2 + Michael Kerrisk + The raw sigtimedwait() system call has a fifth argument + +symlink.2 + Michael Kerrisk + Glibc falls back to symlink() on kernels that lack symlinkat() + +sysinfo.2 + Michael Kerrisk + Add VERSIONS section + +unlink.2 + Michael Kerrisk + Glibc falls back to unlink() or rmdir() on kernels that lack unlinkat() + +atoi.3 + Michael Kerrisk + Downgrade discussion of atoq() + Remove most references to atoq() in this page, since this function + was present only in Linux libc (not glibc). + +cerf.3 +cexp2.3 +clog2.3 + Michael Kerrisk + Update version number on "Not yet in glibc" sentence + +fgetgrent.3 +getgrent.3 +getgrent_r.3 +getgrnam.3 + Michael Kerrisk [Rob Landley] + Clarify that 'gr_mem' is a NULL-terminated array of pointers + +fseeko.3 + Michael Kerrisk + Add VERSIONS section + +ftw.3 + Michael Kerrisk + Add VERSIONS section + +getauxval.3 + Michael Kerrisk + Document ENOENT error + And add an entry to BUGS explaining the ambiguity that was + present before the addition of this error. + +getgrouplist.3 + Michael Kerrisk + SEE ALSO: add group_member(3) + +getline.3 + Rahul Bedarkar + Close opened file at end of example program + +memmem.3 + Michael Kerrisk + Rewrite text of glibc 2.0 bug + +printf.3 + Michael Kerrisk [Jakub Wilk] + Clarify details of the %n conversion specifier + See http://bugs.debian.org/756602 + Michael Kerrisk [Jakub Wilk] + Note use of 'j', 'z', and 't' length modifiers for '%n' + See http://bugs.debian.org/756602 + Michael Kerrisk + Update with some SUSv3 details + +setbuf.3 + Michael Kerrisk + Remove ancient Linux libc and 4.x BSD details + +strstr.3 + Michael Kerrisk + Remove discussion of Linux libc bugs + Linux libc is old enough that we needn't care any longer. + +strtod.3 + Michael Kerrisk + Explain NAN(n-char-sequence) + +strtod.3 + Michael Kerrisk + SEE ALSO: add nan(3), nanf(3), NANL(3) + +updwtmp.3 + Michael Kerrisk + Replace AVAILABILITY section with note to link logwtmp() using -lutil + Linux libc details are no longer needed these days. + +core.5 + Rahul Bedarkar + Close opened file in example program + +proc.5 + Michael Kerrisk + Fix kernel version numbers for /proc/PID/stat fields + +proc.5 + Jan Chaloupka + Add missing proc stats fields + Adding missing proc stats fields from + https://www.kernel.org/doc/Documentation/filesystems/proc.txt + Michael Kerrisk [Simon Paillard] + Remove crufty text under 'timer_stats' + Michael Kerrisk + Update /proc/PID/stat 'state' field documentation + Michael Kerrisk + Improve description of /proc/PID/stat fields added in Linux 3.3 and 3.5 + Michael Kerrisk + Refer to getauxval(3) in discussion of /proc/PID/auxv + Michael Kerrisk + Rework formatting of /proc/PID/stat list + Make the field numbers more prominent. + Michael Kerrisk + Note that /proc/PID/cmdline is read-only + Michael Kerrisk + Rework discussion of CommitLimit and /proc/sys/vm/overcommit_memory + Michael Kerrisk + Improve discussion of /proc/sys/vm/overcommit_ratio + +charsets.7 + David Prévot [Marko Myllynen] + Tidy up list + Remove German from main list, to be consistent with earlier + removal of Dutch and French (in commit a8ed5f7430e0d1). + +inotify.7 + Michael Kerrisk + Note that IN_ONLY_DIR can be used to avoid races + Michael Kerrisk + Note that insertion of IN_MOVED_FROM+IN_MOVED_TO pair is not atomic + Michael Kerrisk + Mention use of timeout when reading IN_MOVED_TO after IN_MOVED_FROM + +man-pages.7 + Michael Kerrisk + Add description of "C library/kernel ABI differences" subsection + Michael Kerrisk + Rework text describing sections (stylistic improvements) + +vdso.7 + Mike Frysinger + Add new i386 vdso symbols in Linux 3.15 + Michael Kerrisk + Note kernel version that exports new i386 symbols (Linux 3.15) + + +==================== Changes in man-pages-3.72 ==================== + +Released: 2014-09-07, Mountain View + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Christian von Roques +Holger Hans Peter Freyther +Michael Haardt +Michael Kerrisk +Mike Frysinger +Peter Schiffer +Rusty Russell +Sorin Dumitru + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +memusage.1 + Peter Schiffer, Michael Kerrisk [Jan Chaloupka] + New page for glibc memusage(1) command + +memusagestat.1 + Peter Schiffer [Jan Chaloupka, Michael Kerrisk] + New page for glibc memusagestat(1) command + +mtrace.1 + Peter Schiffer [Jan Chaloupka] + New page describing the glibc mtrace(1) command + + +Changes to individual pages +--------------------------- + +connect.2 + Michael Haardt + Note that a new socket should be used if connect() fails + +fcntl.2 + Michael Kerrisk + One must define _GNU_SOURCE to get the F_OFD_* definitions + +poll.2, select.2 + Rusty Russell + Fix erroneous description of "available for write". + POSIX says: "POLLOUT Normal data may be written without + blocking.". This "may" is misleading, see the POSIX + write page: + + Write requests to a pipe or FIFO shall be handled in the + same way as a regular file with the following exceptions: + ... + If the O_NONBLOCK flag is clear, a write request may cause + the thread to block, but on normal completion it shall + return nbyte. + ... + When attempting to write to a file descriptor (other than a + pipe or FIFO) that supports non-blocking writes and cannot + accept the data immediately: + + If the O_NONBLOCK flag is clear, write() shall block the + calling thread until the data can be accepted. + + If the O_NONBLOCK flag is set, write() shall not block the + thread. If some data can be written without blocking the + thread, write() shall write what it can and return the + number of bytes written. Otherwise, it shall return -1 and + set errno to [EAGAIN]. + + The net result is that write() of more than 1 byte on a + socket, pipe or FIFO which is "ready" may block: write() + (unlike read!) will attempt to write the entire buffer and + only return a short write under exceptional circumstances. + + Indeed, this is the behaviour we see in Linux: + + https://github.com/rustyrussell/ccan/commit/897626152d12d7fd13a8feb36989eb5c8c1f3485 + https://plus.google.com/103188246877163594460/posts/BkTGTMHDFgZ + +errno.3 + Michael Kerrisk + SEE ALSO: add errno(1) + +rtnetlink.3 + Holger Hans Peter Freyther + Fix parameters for the send() call in the example + +inotify.7 + Michael Kerrisk + IN_OPEN and IN_CLOSE_NOWRITE can also occur for directories + Michael Kerrisk + IN_CLOSE_WRITE occurs only for files (not monitored directory) + Michael Kerrisk + IN_MODIFY is generated for files only (not monitored directories) + Michael Kerrisk + IN_ACCESS occurs only for files inside directories + IN_ACCESS does not occur for monitored directory. + +packet.7 + Sorin Dumitru + Fix include file + It looks like most of the socket options from this man pages + are not defined in . They are defined in + so we should include that one. + + +==================== Changes in man-pages-3.73 ==================== + +Released: 2014-09-21, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +David Prévot +Eric W. Biederman +J. Bruce Fields +Justin Cormack +Lorenzo Beretta +Michael Kerrisk +Rob Landley +Serge E. Hallyn +Serge Hallyn +Vasily Kulikov +Vincent Lefevre +Vitaly Rybnikov +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +namespaces.7 + Michael Kerrisk [Eric W. Biederman] + New page providing overview of Linux namespaces + +pid_namespaces.7 + Michael Kerrisk [Eric W. Biederman, Vasily Kulikov, Rob Landley, + Serge Hallyn] + New page describing PID namespaces + +user_namespaces.7 + Michael Kerrisk [Eric W. Biederman, Andy Lutomirski, Serge Hallyn] + New page describing user namespaces. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +clone.2 + Eric W. Biederman [Michael Kerrisk] + Document CLONE_NEWUSER for creating a new user namespace + +setns.2 + Eric W. Biederman, Michael Kerrisk + Document the PID, user, and mount namespace support + Document CLONE_NEWPID, CLONE_NEWUSER, and CLONE_NEWNS flags. + +unshare.2 + Michael Kerrisk [Eric W. Biederman] + Document CLONE_NEWPID + Michael Kerrisk [Eric W. Biederman] + Document CLONE_NEWUSER + Michael Kerrisk + Document CLONE_THREAD, CLONE_SIGHAND, and CLONE_VM + + +Changes to individual pages +--------------------------- + +clone.2 + Michael Kerrisk + Move some CLONE_NEWNET text to namespaces.7 + Michael Kerrisk + Move some CLONE_NEWUTS text 2 to namespaces.7 + Michael Kerrisk + Move some CLONE_NEWIPC text to namespaces.7 + Michael Kerrisk + Reword discussion of CLONE_NEWNS, removing text also in namespaces(7) + Michael Kerrisk + Standardize text on CLONE_NEW* flags and CAP_SYS_ADMIN + Michael Kerrisk + EINVAL if (CLONE_NEWUSER|CLONE_NEWPID) && (CLONE_THREAD|CLONE_PARENT) + Michael Kerrisk + Add more detail on the meaning of CLONE_SYSVSEM + +flock.2 + Michael Kerrisk [J. Bruce Fields] + Don't mention "classical BSD" in discussion of fcntl()/flock interaction + The noninteraction of flock(2) and fcntl(2) locks does + not seem to be classical BSD semantics (at least, checking + the 4.4BSD sources suggest that the lock types do interact, + although there have been other systems also where fcntl() + and flock() locks do not interact). So, fix the text + discussing "classical BSD" lock semantics. + +getunwind.2 + Michael Kerrisk [Yuri Kozlov] + Fix description of return value + s/size of unwind table/size of the unwind data/ + +mount.2 + Eric W. Biederman + Clarify use of 'mountflags' and 'data' for MS_REMOUNT + +reboot.2 + Michael Kerrisk [Justin Cormack, Eric W. Biederman] + Document effect of reboot() inside PID namespaces + +semop.2 + Michael Kerrisk + Refer to clone(2) for semantics of CLONE_SYSVSEM and semadj lists + +seteuid.2 +setgid.2 +setresuid.2 +setreuid.2 +setuid.2 + Michael Kerrisk + EINVAL can occur if UID/GID is not valid in caller's user namespace + +setns.2 + Michael Kerrisk [Eric W. Biederman] + Clarify capabilities required for reassociating with a mount namespace + Michael Kerrisk + Specify kernel version on each CLONE_NEW* flag + And remove text on flags from VERSIONS. + +unshare.2 + Michael Kerrisk + Add an example program + Michael Kerrisk + Clarify semantics of CLONE_SYSVSEM + Michael Kerrisk + CLONE_SYSVSEM does not require CAP_SYS_ADMIN + Michael Kerrisk + Note flags implied by CLONE_THREAD and CLONE_VM + +clock.3 + Michael Kerrisk [Vincent Lefevre] + The implementation uses clock_gettime() was to improve *accuracy* + (The man page text mistakenly used the word "precision".) + +drand48.3 + Michael Kerrisk [Lorenzo Beretta] + Remove crufty text about SVID 3 marking drand48() obsolete + See http://bugs.debian.org/758293 + +proc.5 + Michael Kerrisk + Move /proc/[pid]/mounts text to namespaces.7 + Michael Kerrisk + Move /proc/[pid]/mountstats text to namespaces.7 + +capabilities.7 + Michael Kerrisk + Refer reader to user_namespaces(7) for a discussion of capabilities + Michael Kerrisk + Document CAP_SETUID and CAP_SETGID for user namespace mappings + Michael Kerrisk + setns() needs CAP_SYS_ADMIN in the *target* namespace + Michael Kerrisk + Since Linux 3.8, user namespaces no longer require CAP_SYS_ADMIN + +mq_overview.7 + Michael Kerrisk + Refer to namespaces(7) for info on POSIX MQs and IPC namespaces + +svipc.7 + Michael Kerrisk + Refer to namespaces(7) for info on System V IPC and IPC namespaces + + +==================== Changes in man-pages-3.74 ==================== + +Released: 2014-10-03, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Arto Bendiken +Ben Hutchings +Benjamin Herr +C. Alex North-Keys +Carlos O'Donell +Cyril Hrubis +Davidlohr Bueso +Doug Ledford +Elie De Brauwer +Heinrich Schuchardt +Jonny Grant +Lanchon +Manfred Spraul +Marko Myllynen +Michael Kerrisk +Shriramana Sharma +Thomas Mack +Wieland Hoffmann + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pldd.1 + Michael Kerrisk + New page for pldd(1) command added to glibc in version 2.15 + +cp1252.7 + Marko Myllynen + New page documenting CP 1252 + CP 1252 is probably one of the most used Windows Code Pages so + let's add a page for it alongside with the already provided + CP 1251 page. + + Table generated from /usr/share/i18n/charmaps/CP1252. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +mq_overview.7 + Michael Kerrisk + Document /proc/sys/fs/mqueue/msgsize_default + Michael Kerrisk + Document /proc/sys/fs/mqueue/msg_default + + +Changes to individual pages +--------------------------- + +ldd.1 + Michael Kerrisk + SEE ALSO: add pldd(1) + +execve.2 + Michael Kerrisk [C. Alex North-Keys] + Remove unneeded ".sh" extension in interpreter script example + See https://bugzilla.kernel.org/show_bug.cgi?id=84701 + +fanotify_init.2 + Heinrich Schuchardt + BUGS: O_CLOEXEC is ignored + Michael Kerrisk [Heinrich Schuchardt] + The 'event_f_flags' failure to check invalid flags was fixed in 3.15 + +fanotify_mark.2 + Michael Kerrisk + Note that various bugs were fixed in Linux 3.16 + +getrlimit.2 + Michael Kerrisk [Doug Ledford] + Since Linux 3.5, the accounting formula for RLIMIT_MSGQUEUE has changed + +open.2 + Michael Kerrisk [Shriramana Sharma] + Fix number and formula in description of EOVERFLOW error + +readlink.2 + Michael Kerrisk [Ben Hutchings] + Fix description of readlinkat() with empty 'pathname' + Michael Kerrisk + SEE ALSO: add realpath(3) + +sched_setattr.2 +sched_setscheduler.2 + Michael Kerrisk + SEE ALSO: add chrt(1) + +shmget.2 + Manfred Spraul [Michael Kerrisk, Davidlohr Bueso] + Update for increase of SHMALL and SHMMAX + The default values of SHMALL and SHMMAX have been increased. + +syscalls.2 + Michael Kerrisk + Add 3 new system calls added in Linux 3.17 + +vmsplice.2 + Cyril Hrubis + vmsplice() does not fail when nr_segs==0 + This nr_segs==0 case is no-op; the call succeeds and no + EINVAL error is returned. + +dlopen.3 + Michael Kerrisk + SEE ALSO: add pldd(1) + +fseeko.3 + Michael Kerrisk [Thomas Mack] + _FILE_OFFSET_BITS must be defined before including any header file + +getgrent.3 + Carlos O'Donell + Add ENOENT and EAGAIN to error list + +mq_getattr.3 + Michael Kerrisk + Add an example program + The example program can be used to discover the default + 'mq_maxmsg' and 'mq_msgsize' values used to create a queue with + a mq_open(3) call in which 'attr' is NULL. + +mq_open.3 + Michael Kerrisk + Two /proc files control the defaults for the attrp==NULL case + Refer the reader to the discussion in mq_overview(7) for a + discussion of these files, which exist since Linux 3.5. + +realpath.3 + Michael Kerrisk + SEE ALSO: add realpath(1) + +proc.5 + Elie De Brauwer + Document /proc/buddyinfo + This patch adds a short description about the contents of + /proc/buddyinfo and how this file can be used to assist + in checking for memory fragmentation issues. + Michael Kerrisk + Mention pmap(1) in discussion of /proc/PID/smaps + +armscii-8.7 + Marko Myllynen + Charset pages unification, minor cleanups + +ascii.7 + Marko Myllynen + Charset pages unification, minor cleanups + This and [the related *.7] patches will provide unification of + charset pages, minor cleanups, and some unifying cosmetic + changes. References are adjusted so that all pages include + a reference to charsets(7), which contains a description of + these sets, stray comments are removed, some obsolete + statements (like ISO 8859-1 being the de-facto ASCII + replacement) are removed, and some minor reformatting + to minimize diff's between the pages are done. + + The actual substance, the character tables, remain unchanged. + + This series changes the following pages (under man7): ascii, + armscii, cp1251, koi8-r, koi8-u, and all of iso_8859-*. + +cp1251.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-10.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-11.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-13.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-14.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-15.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-16.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-1.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-2.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-3.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-4.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-5.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-6.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-7.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-8.7 + Marko Myllynen + Charset pages unification, minor cleanups + +iso_8859-9.7 + Marko Myllynen + Charset pages unification, minor cleanups + +koi8-r.7 + Marko Myllynen + Charset pages unification, minor cleanups + - remove stray comments, streamline description + (charsets(7) and Wikipedia provide more detailed + and up-to-date description) + - list differences between koi8-r.7 vs koi8-u.7 + +koi8-u.7 + Marko Myllynen + Charset pages unification, minor cleanups + - remove stray comments, streamline description + (charsets(7) and Wikipedia provide more detailed + and up-to-date description) + - list differences between koi8-r.7 vs koi8-u.7 + +mq_overview.7 + Michael Kerrisk + Update queues_max details for Linux 3.14 + And in general rework the text a little. + Michael Kerrisk + Update discussion of HARD_MSGMAX + The limit has changed in 2.6.33 and then again in 3.5. + Michael Kerrisk [Arto Bendiken] + Update details for 'queues_max' limit + Things changed in Linux 3.5. + See https://bugs.launchpad.net/bugs/1155695 + Michael Kerrisk + Update details on defaults and ceiling for 'msgsize_max' limit + Michael Kerrisk + Rework discussion of HARD_MSGMAX + Michael Kerrisk [Davidlohr Bueso] + Various fixes after review from Davidlohr Bueso + +sched.7 + Michael Kerrisk + SEE ALSO: add taskset(1) + +ld.so.8 + Michael Kerrisk + SEE ALSO: add pldd(1) + Michael Kerrisk + SEE ALSO: add dlopen(3) + Michael Kerrisk + SEE ALSO: add ld(1) + + + +==================== Changes in man-pages-3.75 ==================== + +Released: 2014-10-15, Düsseldorf + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Jonny Grant +Michael Kerrisk +Robert Schweikert +Tetsuo Handa +Walter Harms + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pthread_rwlockattr_setkind_np.3 + Robert Schweikert [Michael Kerrisk] + New page documenting pthread_rwlockattr_[sg]etkind_np(3) + Documents pthread_rwlockattr_setkind_np(3) and + pthread_rwlockattr_getkind_np(3). + + +New and changed links +--------------------- + +pthread_rwlockattr_getkind_np.3 + Robert Schweikert + New link to pthread_rwlockattr_setkind_np(3) + + +Changes to individual pages +--------------------------- + +readlink.2 + Michael Kerrisk [Jonny Grant] + Add free() call to example program + +readv.2 + Michael Kerrisk + The raw preadv() and pwritev() syscalls split 'offset' into 2 arguments + +signal.7 + Michael Kerrisk + pthread_mutex_lock() and pthread_cond_wait() are restartable + pthread_mutex_lock(, pthread_cond_wait(), and related APIs are + automatically restarted if interrupted by a signal handler. + +unix.7 + Michael Kerrisk [Carlos O'Donell, David Miller, Tetsuo Handa] + Various additions and rewordings + Notable changes: + * Clarify some details for pathname sockets. + * Add some advice on portably coding with pathname sockets. + * Note the "buggy" behavior for pathname sockets when + the supplied pathname is 108 bytes (after a report by + Tetsuo Handa). + + +==================== Changes in man-pages-3.76 ==================== + +Released: 2014-12-31, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Adam Jiang +Andrea Balboni +Andreas Schwab +Bernhard Walle +Carlos O'Donell +David Wragg +Florian Westphal +Heinrich Schuchardt +Huxiaoxiang +Jan Chaloupka +Jonathan Wakely +Jonny Grant +Josh Triplett +Kamezawa Hiroyuki +Laurent Georget +Manuel López-Ibáñez +Marko Myllynen +Ma Shimiao +Mel Gorman +Michael Gehring +Michael Haardt +Michael Kerrisk +Mike Frysinger +Rasmus Villemoes +Richard Weinberger +Rich Felker +Scott Harvey +Siddhesh Poyarekar +Simon Newton +Simon Paillard +Sven Hoexter +Tobias Werth +Weijie Yang +Will Newton +Yuri Kozlov +刘湃 +尹杰 + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +adjtimex.2 + Laurent Georget + Add fields in struct timex description + This patch updates the man page with the new fields added in + struct timex since last edition of the man page. + Laurent Georget [Michael Kerrisk] + Document ADJ_TAI + Michael Kerrisk + Improve description of ADJ_OFFSET_SINGLESHOT + Michael Kerrisk + Add brief documentation of ADJ_MICRO and ADJ_NANO + Michael Kerrisk + Reformat return value list + And remove numeric values, since they're not needed + Michael Kerrisk + Other 'modes' bits are ignored on ADJ_OFFSET_* + Other bits in 'modes' are ignored if modes contains + ADJ_OFFSET_SINGLESHOT or ADJ_OFFSET_SS_READ. + Michael Kerrisk + Add nanosecond details + Fixes https://bugzilla.kernel.org/show_bug.cgi?id=61171. + Michael Kerrisk + Document ADJ_OFFSET_SS_READ + Michael Kerrisk + Reformat 'times' flags as list + And remove numeric values, since they're not needed. + Michael Kerrisk + Note effect of ADJ_NANO for ADJ_SETOFFSET + Michael Kerrisk + Add comment noting that timex structure contains padding bytes + Michael Kerrisk + Add more details to description of 'tai' field + Michael Kerrisk + Note meaning of "PLL" abbreviation + Michael Kerrisk + Clarify which 'timex' field is used by each 'modes' bit + Michael Kerrisk + Document timex 'status' bits + Michael Kerrisk + Clarify treatment of other 'modes' bits for ADJ_OFFSET_* + Michael Kerrisk + Update RFC number: RFC 5905 obsoletes RFC 1305 + Michael Kerrisk + Briefly document ADJ_SETOFFSET + Michael Kerrisk + Note PPS (pulse per second) fields in timex structure + +sigreturn.2 + Michael Kerrisk + Add (a lot) more detail on the signal trampoline + And rewrite much of the page. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +proc.5 + Bernhard Walle + Document /proc/thread-self + /proc/thread-self has been introduced in Linux 3.17 with + commit 0097875bd41528922fb3bb5f348c53f17e00e2fd. + Sven Hoexter [Michael Kerrisk, Kamezawa Hiroyuki] + Document "VmSwap" field of /proc/[pid]/status + Florian Westphal + Document /proc/net/netfilter/nfnetlink_queue + + +Changes to individual pages +--------------------------- + +localedef.1 + Marko Myllynen + Mention default path for compiled files + +clock_nanosleep.2 + Michael Kerrisk + Note that 'clock_id' can also be a CPU clock ID + +epoll_ctl.2 + Michael Kerrisk + Regular files and directories can't be monitored with epoll_ctl() + +ioctl.2 + Heinrich Schuchardt + Rename 'd' argument to 'fd' in text + In most other manpages file descriptors are called 'fd'. + This patches renames attribute 'd' to 'fd'. + +madvise.2 + Michael Kerrisk + VERSIONS: Support for madvise() is now configurable + Support for this system call now depends on the + CONFIG_ADVISE_SYSCALLS configuration option. + +open.2 + Michael Kerrisk + Enhance rationale discussion for openat() and friends + +posix_fadvise.2 + Mel Gorman + Document the behavior of partial page discard requests + It is not obvious from the interface that "partial page discard" + requests are ignored. It should be spelled out. + Michael Kerrisk [Weijie Yang] + ERRORS: Since 2.6.16, the kernel correctly deals with the ESPIPE case + Michael Kerrisk + Support for fadvise64() is now configurable + Support for this system call now depends on the + CONFIG_ADVISE_SYSCALLS configuration option. + +prctl.2 + Andreas Schwab + Correct description of null-termination in PR_GET_NAME and PR_SET_NAME + The size of the process name has always been at most 16 byte + _including_ the null terminator. This also means that the + name returned by PR_GET_NAME is always null-terminated. + Michael Kerrisk + PR_SET_NAME silently truncates strings that exceed 16 bytes + +restart_syscall.2 + Michael Kerrisk + Add some text explaining why restart_syscall() exists + +sched_setaffinity.2 + Michael Kerrisk + NOTES: Add paragraph on how to discover set of CPUs available on system + Michael Kerrisk + SEE ALSO: add nproc(1) and lscpu(1) + +select.2 + Michael Kerrisk + SEE ALSO: add restart_syscall(2) + +semop.2 + Michael Kerrisk + Add note that interrupted semtimedop() returns 'timeout' unchanged + Michael Kerrisk + Remove information about semtimedop() EAGAIN that is repeated elsewhere + Michael Kerrisk + Add subsection head for semtimedop() + +setsid.2 + Michael Kerrisk + Rewrite some pieces and add some details + Among other changes, add an explanation of why setsid() can't + be called from a process group leader + +sgetmask.2 + Michael Kerrisk + Since 3.16, support for these system calls is configurable + Support for these calls is now dependent on the setting of the + CONFIG_SGETMASK_SYSCALL option. + +sigaction.2 + Michael Kerrisk + Document SA_RESTORER + Michael Kerrisk + Add some detail on the sa_restorer field + Michael Kerrisk + SEE ALSO: add sigreturn(2) + +splice.2 + Michael Kerrisk + Reformat description of 'fd_in' and 'off_in' to improve readability + +syscall.2 + Michael Kerrisk + SEE ALSO: add errno(3) + +syscalls.2 + Michael Kerrisk + SEE ALSO: add errno(3) + Michael Kerrisk + 3.19 adds execveat() + Michael Kerrisk + Add bpf(2) to list + +tee.2 + Michael Kerrisk + Add shell session demonstrating use of the example program + +tkill.2 + Michael Kerrisk [Rich Felker] + Remove bogus text saying tgid==-1 makes tgkill() equivalent to tkill() + +abort.3 + Michael Kerrisk + Note that SIGABRT is raised as though raise(3) is called + Also note that abort() is POSIX.1-2008 compliant. + +cmsg.3 + David Wragg + Ensure buf is suitably aligned in sending example + Inspection of the definition of CMSG_FIRSTHDR (both in glibc and + the suggested definition in RFC3542) shows that it yields the + msg_control field. So when sending, the pointer placed in + msg_control should be suitably aligned as a struct cmsghdr. + In the sending example, buf was declared as a bare char array, + and so is not necessarily suitably aligned. + + The solution here involves placing buf inside a union, and is + based on the sockets/scm_rights_send.c sample from The Linux + Programming Interface "dist" source code collection. + +exp10.3 + Michael Kerrisk + Before glibc 2.19, exp() did not give ERANGE error on underflow + http://sources.redhat.com/bugzilla/show_bug.cgi?id=6787 + +ftw.3 + Michael Kerrisk + FTW_CHDIR has no effect on the 'fpath' argument passed to fn() + +getopt.3 + Michael Kerrisk [Jonny Grant] + Ensure that 'nsecs' is used + +ilogb.3 + Michael Kerrisk [Will Newton] + Since glibc 2.16, ilogb() does correctly diagnose domain errors + +memcmp.3 + Michael Haardt + Document return value for n==0 case + Michael Haardt + Warn against use of memcmp() for comparing security-critical data + +mq_open.3 + Michael Kerrisk + Document the O_CLOEXEC flag + Michael Kerrisk + Place 'flags' constants in alphabetical order + +pow.3 + Manuel López-Ibáñez + Add note on performance characteristics of pow() + +pthread_setschedparam.3 + Simon Newton + Fix logic error in example program + The example program will crash if -A is used, since 'attr' + is uninitialized. + + $ ./a.out -A + *** Error in `./a.out': free(): invalid pointer: 0xb779c3c4 *** + Aborted (core dumped) + 刘湃 + Small fixes to example program + +sigvec.3 + Michael Kerrisk + Starting with version 2.21, glibc no longer exports sigvec() + +sysconf.3 + Josh Triplett + Document _SC_NGROUPS_MAX + Already documented in getgroups(2), but not in sysconf(3). + +termios.3 + Michael Kerrisk + SEE ALSO: add tset(1) + +tgamma.3 + Michael Kerrisk + Since glibc 2.18, errno is correctly set to EDOM when (x == -infinity)) + +wordexp.3 + Carlos O'Donell + Make it clear that WRDE_NOCMD prevents command substitution + The use of WRDE_NOCMD prevents command substitution. If the flag + WRDE_NOCMD is set then no command substitution shall occur and + the error WRDE_CMDSUB will be returned if such substitution is + requested when processing the words. + + The manual page as-is makes it seem like the command substitution + occurs, and an error is returned *after* the substitution. + This patch clarifies that. + +locale.5 + Marko Myllynen + Describe the formats of values + locale(5) describes what a locale should define but doesn't + spell out how (in what format). The patch attempts to address + this, it also has few trivial additional enhancements. + + * Reference to locale(7) for category descriptions. + * Clarify first_workday in NOTES a bit. + * Add upstream BZ reference for two missing LC_ADDRESS fields. + Marko Myllynen + Fix miscoded character + +resolv.conf.5 + Jan Chaloupka + Add missing no-tld-query option + Based on commit [1], the no-tld-query option exists for + resolv.conf configuration file. Description of this option + is provided in [2]. This patch just copies this option + into resolv.conf.5 man page. Plus changes 'a' member + into 'an' before 'unqualified name as if it ...' + on the third line of [2]. Based on [3], this option + was added in glibc 2.14 as solving [4] bug. + + [1] https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=f87dfb1f11c01f2ccdc40d81e134cd06b32e28e8 + [2] http://www.daemon-systems.org/man/resolv.conf.5.html man page. + [3] https://sourceware.org/git/?p=glibc.git;a=blob;f=NEWS;h=952f32af17e7fb49c4c1a305de673a13075bfaf5;hb=f87dfb1f11c01f2ccdc40d81e134cd06b32e28e8 + [4] https://sourceware.org/bugzilla/show_bug.cgi?id=12734 + +credentials.7 + Josh Triplett + Cross-reference getgroups(2) + Since credentials.7 discusses supplementary GIDs, it should + reference getgroups(2). + +fanotify.7 + Heinrich Schuchardt + Allow relative paths in example + The current example code requires passing an absolute + path to the mount to be watched. + + By passing AT_FDCWD to fanotify_mark it can use both + absolute and relative paths. + Heinrich Schuchardt + fallocate(2) creates no events + fallocate(2) should create FAN_MODIFY events but does not. + Heinrich Schuchardt [Michael Kerrisk] + fanotify notifies only events generated on the same mount + Unfortunately, fanotify does not inform listeners for all paths + under which a touched filesystem object is visible, but only the + listener using the same path as the process touching the + filesystem object. + Heinrich Schuchardt + Update BUGS to note bugs still not fixed in 3.17 + I bumped the Linux version number in the BUGS section to 3.17. + +inotify.7 + Heinrich Schuchardt + fallocate(2) does not trigger inotify events + Calling fallocate(2) does not result in inotify events. + +locale.7 + Marko Myllynen + Improve LOCPATH description + LOCPATH is ignored by privileged programs. + + Add locale archive references. + + Add FILES section. + +man-pages.7 + Michael Kerrisk [Laurent Georget] + Clarify that SEE ALSO entries may refer to pages from other projects + +signal.7 + Michael Kerrisk + Mention other "slow devices" + Reads from eventfd(2), signalfd(2), timerfd(2), inotify(7), + and fanotify(7) file descriptors are also slow operations + that are restartable. + Michael Kerrisk + Fix SO_RECVTIMEO/ SO_SENDTIMEO confusion in text + Michael Kerrisk + Since Linux 3.8, reads on inotify(7) file descriptors are restartable + Michael Kerrisk + inotify(7) reads no longer show the odd EINTR error after SIGCONT + Since kernel 3.7, reads from inotify(7) file descriptors no longer + show the (Linux oddity) behavior of failing with EINTR when the + process resumes after a stop signal + SIGCONT. + Michael Kerrisk + SEE ALSO: add sigreturn(2) + +unix.7 + Michael Kerrisk [Scott Harvey] + Fix buglet in code snippet in BUGS section + +ld.so.8 + Carlos O'Donell + Add --inhibit-cache option + The dynamic loader has 6 options, only 5 are documented. + This patch documents the sixth option i.e. `--inhibit-cache`. + Jonathan Wakely [Siddhesh Poyarekar] + Correct documentation of $ORIGIN + As noted by Siddhesh: + + The ld.so man page says: + + $ORIGIN (or equivalently ${ORIGIN}) + This expands to the directory containing the + application executable. Thus, an application located + in somedir/app could be compiled with + + This is incorrect since it expands to the directory containing + the DSO and not the application executable. This seems like + deliberate behaviour in dl-object.c, so it needs to be fixed in + the man page. + + See http://stackoverflow.com/questions/26280738/what-is-the-equivalent-of-loader-path-for-rpath-specification-on-linux/26281226#26281226 + + + +==================== Changes in man-pages-3.77 ==================== + +Released: 2015-01-10, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Akihiro Motoki +Alexandre Bique +Andre Majorel +Andy Lutomirski +Daniel Borkmann +Dave Hansen +Elie De Brauwer +Heinrich Schuchardt +Ignat Loskutov +Jeff Epler +Jérôme Pouiller +Kees Cook +Laurent Georget +Masanari Iida +Michael Haardt +Michael Kerrisk +Mike Frysinger +Richard Cochran +Stephan Mueller +Troy Davis +Vince Weaver +Will Drewry + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +seccomp.2 + Kees Cook, Michael Kerrisk, Will Drewry [Andy Lutomirski] + New page documenting seccomp(2) + Combines documentation from prctl, in-kernel seccomp_filter.txt + and dropper.c, along with details specific to the new system call. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +netlink.7 + Stephan Mueller [Michael Kerrisk] + Add NETLINK_CRYPTO + + +Changes to individual pages +--------------------------- + +adjtimex.2 + Laurent Georget [Richard Cochran, Jeff Epler] + Clarify the 'ppm scaling' used in struct timex + This patch makes explicit and clarifies the unit used for + the fields "freq", "ppsfreq" and "stabil" in struct timex. + Michael Kerrisk [Masanari Iida] + Note that TIME_ERROR is the modern synonym for TIME_BAD + +perf_event_open.2 + Vince Weaver + Clarify the PERF_FLAG_FD_* flags + This change clarifies the behavior of the PERF_FLAG_FD_OUTPUT and + PERF_FLAG_FD_NO_GROUP flags to perf_event_open(), and removes + the related FIXME comments. + + While writing tests to validate the behavior of these flags I + discovered that PERF_FLAG_FD_OUTPUT has been broken since the + 2.6.35 kernel release. + +prctl.2 + Dave Hansen [Michael Kerrisk] + Add description of Intel MPX calls + The 3.19 kernel will have support for Intel MPX, including + a pair of new prctl() calls (PR_MPX_ENABLE_MANAGEMENT and + PR_MPX_DISABLE_MANAGEMENT) for enabling and disabling the + kernel's management of the "bounds tables". Add a + descriptions of the interface. + Michael Kerrisk + Add mention of seccomp(2) under PR_SET_SECCOMP + Michael Kerrisk + Suggest /proc/PID/status "Seccomp" as alternative to PR_GET_SECCOMP + Michael Kerrisk + SIGKILL can also occur PR_GET_SECCOMP in SECCOMP_MODE_FILTER mode + Kees Cook [Andy Lutomirski] + Document SECCOMP_MODE_FILTER vs EFAULT + This notes the distinction made between EINVAL and EFAULT when + attempting to use SECCOMP_MODE_FILTER with PR_SET_SECCOMP. + +setns.2 +pid_namespaces.7 + Mike Frysinger + Elaborate discussion of the PID namespace descendant limitation + The setns(2) man page already mentions that CLONE_NEWPID may only + be used with descendant namespaces, but this nuance could be + listed in a few more places so it is not missed. + +shmget.2 + Michael Kerrisk [Akihiro Motoki] + Make wording of SHMALL description a little clearer + +sigaction.2 + Michael Kerrisk + Add siginfo_t fields for SECCOMP_RET_TRAP + +memchr.3 +strstr.3 + Alexandre Bique + Reference memmem(3) in SEE ALSO section + +memcmp.3 + Michael Kerrisk [Michael Haardt] + NOTES: add some detail on avoiding memcmp() of cryptographic data + Wording largely based on comments from Michael Haardt. + +pthread_tryjoin_np.3 + Jérôme Pouiller [Michael Kerrisk] + Document EINVAL error for pthread_timedjoin_np() + +mem.4 + Elie De Brauwer + /dev/kmem depends on CONFIG_DEVKMEM + Elie De Brauwer + Correct /dev/port group in example + mem.4 mentions that group for /dev/port should be set to 'mem' + However, all other files (/dev/mem and /dev/kmem) use the kmem + group in their examples and on my system /dev/port belongs to + kmem. Hence the 'mem' group was probably a typo: + Elie De Brauwer + Add CONFIG_STRICT_DEVMEM + Since 2.6.26 the CONFIG_NONPROMISC_DEVMEM options limits the + physical addresses which can be accessed through /dev/mem. + +random.4 + Heinrich Schuchardt + Describe handling of O_NONBLOCK + /dev/random and /dev/urandom treat O_NONBLOCK differently. + This should be described in the manpage. + Heinrich Schuchardt + Mention PRNG used by urandom + /dev/urandom uses a pseudo-random number generator to replace + missing entropy. + +proc.5 + Michael Kerrisk + Document "Seccomp" field of /proc/PID/status + +epoll.7 + Michael Kerrisk [Ignat Loskutov] + Use epoll_create1() rather than epoll_create() in the code example + epoll_create1() is more or less the preferred API for new + applications, since it allows for some flags and avoids the + misdesigned epoll_create() argument, and so it seems sensible + to use that in the example, rather than epoll_create(). + +tcp.7 + Troy Davis + Clarify tcp_tw_recycle on Internet-facing hosts + Clarify that tcp_tw_recycle will break communication with many + general-purpose remote Internet hosts (namely, remote NAT devices) + even when the Linux device itself is not behind NAT. + + +==================== Changes in man-pages-3.78 ==================== + +Released: 2015-01-22, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Akihiro Motoki +Alexey Ishchuk +Carlos O'Donell +Christian Seiler +Daniel J Blueman +David Drysdale +David Herrmann +Elie De Brauwer +Elliot Hughes +Jessica McKellar +Kees Cook +Michael Hayes +Michael Kerrisk +Rich Felker +Vince Weaver + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +execveat.2 + David Drysdale, Michael Kerrisk [Rich Felker] + New page for execveat(2) + +memfd_create.2 + Michael Kerrisk, David Herrmann + New page for memfd_create() system call + Including notes about file sealing + +s390_pci_mmio_write.2 + Alexey Ishchuk + New page for s390 s390_pci_mmio_write() and s390_pci_mmio_read() + New manual page for the new PCI MMIO memory access system + calls, s390_pci_mmio_write() and s390_pci_mmio_read(), + added for the s390 platform. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fcntl.2 + David Herrmann [Michael Kerrisk] + Document F_ADD_SEALS and F_GET_SEALS commands + +proc.5 + Elie De Brauwer + Document /proc/sys/vm/compact_memory + Michael Kerrisk + Document /proc/sys/fs/nr_open + + +New and changed links +--------------------- + +s390_pci_mmio_read.2 + Michael Kerrisk + New link to new s390_pci_mmio_write(2) page + + +Changes to individual pages +--------------------------- + +dup.2 + Michael Kerrisk + Add reference to RLIMIT_NOFILE for EMFILE error + Michael Kerrisk + Add reference to RLIMIT_NOFILE for EBADF error on 'newfd'. + +execve.2 +fexecve.3 + Michael Kerrisk + SEE ALSO: add execveat(2) + +fallocate.2 +mmap.2 +open.2 +truncate.2 +write.2 + Michael Kerrisk + ERRORS: add EPERM for operation denied by file seal + +fcntl.2 + Michael Kerrisk + ERRORS: add EBUSY case for F_SETPIPE_SZ + Michael Kerrisk + Add reference to RLIMIT_NOFILE for F_DUPFD EINVAL error on 'arg'. + Michael Kerrisk + ERRORS: add open file description lock error cases + +getrlimit.2 + Michael Kerrisk + Update text on RLIMIT_NOFILE ceiling to refer to /proc/sys/fs/file-max + +mbind.2 + Michael Kerrisk [Daniel J Blueman] + Clarify EFAULT text + +mmap.2 +shmget.2 +shm_open.3 + Michael Kerrisk + SEE ALSO: add memfd_create(2) + +open.2 + Michael Kerrisk + Refer to RLIMIT_NOFILE for explanation of EMFILE error + Michael Kerrisk + Add execveat(2) in system call list under "Rationale for openat()" + +perf_event_open.2 + Vince Weaver + Clarify description of overflow events + Update the perf_event_open manpage to be more consistent when + discussing overflow events. It merges the discussion of + poll-type notifications with those generated by SIGIO + signal handlers. + This addresses the remaining FIXMEs is the document. + Vince Weaver + Remove inaccurate paragraph describing attr.config + Remove an inaccurate paragraph about values in the attr.config + field. This information was never true in any released kernel; + it somehow snuck into the manpage because it is still described + this way in tools/perf/design.txt in the kernel source tree. + Michael Kerrisk + Correct the kernel version number for PERF_COUNT_HW_CACHE_NODE + Michael Kerrisk + Add some kernel version numbers to various fields and constants + +ptrace.2 +sigaction.2 +seccomp.2 + Kees Cook + Ptrace and siginfo details + While writing some additional seccomp tests, I realized + PTRACE_EVENT_SECCOMP wasn't documented yet. Fixed this, and added + additional notes related to ptrace events SIGTRAP details. + +readv.2 + Michael Kerrisk + Update details on glibc readv()/writev() wrapper behavior + And add a historical detail about Linux 2.0. + +select.2 + Michael Kerrisk + Mention RLIMIT_NOFILE as a possible cause of EINVAL error + +syscall.2 + Kees Cook + Add arm64 and mips + Add mips and arm64 to tables, along with some further + details on these architectures, + +syscalls.2 + Michael Kerrisk + Add s390_pci_mmio_read(2) and s390_pci_mmio_write(2) + Michael Kerrisk + Note kernel() version that introduced get_kernel_syms() + Note kernel version that introduced ppc_rtas() + Note kernel version that introduced create_module() + Note kernel version that added setup() + Michael Kerrisk + Remove some details for sync_file_range2() + Make the table a bit simpler. The details can anyway be + found in the system call man page. + +utimensat.2 + Michael Kerrisk [Elliot Hughes] + If both tv_sec fields are UTIME_OMIT, the file need not exist + As noted by Elliot, if both tv_sec fields are UTIME_OMIT, + utimensat() will return success even if the file does not exist. + +errno.3 + Michael Kerrisk + The RLIMIT_NOFILE resource limit is a common cause of EMFILE + +exec.3 + Michael Kerrisk + SEE ALSO: add execveat(2) + +fclose.3 + Carlos O'Donell + Consistency fix: use "stream" as name for "FILE *" argument + Harmonize all the manual pages to use "stream" for FILE* + instead of randomly using "fp" or "stream." Choosing something + and being consistent helps users scan the man pages quickly + and understand what they are looking at. + +fexecve.3 + Michael Kerrisk + Rewrite the script+close-on-exec problem as a BUG + Also, add one or two details about this scenario. + Michael Kerrisk + The natural idiom when using fexecve() is to use the close-on-exec flag + +fmemopen.3 + Michael Kerrisk + Consistency fix: use "stream" as name for "FILE *" argument + +fopencookie.3 + Michael Kerrisk + Consistency fix: use "stream" as name for "FILE *" argument + +getgrent_r.3 + Carlos O'Donell + Consistency fix: use "stream" as name for "FILE *" argument + +getline.3 + Michael Kerrisk + Consistency fix: use "stream" as name for "FILE *" argument + +getmntent.3 + Carlos O'Donell + Consistency fix: use "stream" as name for "FILE *" argument + +getpw.3 + Michael Kerrisk [Carlos O'Donell] + Describe return value when 'uid' is not found + +getpwent_r.3 + Carlos O'Donell + Consistency fix: use "stream" as name for "FILE *" argument + +getspnam.3 + Carlos O'Donell + Consistency fix: use "stream" as name for "FILE *" argument + +malloc_info.3 + Carlos O'Donell + Consistency fix: use "stream" as name for "FILE *" argument + +posix_fallocate.3 + Michael Kerrisk + Note that posix_fallocate() is implemented using fallocate(2) + +putgrent.3 + Carlos O'Donell + Consistency fix: use "stream" as name for "FILE *" argument + Harmonize all the manual pages to use "stream" for FILE* + instead of randomly using "fp" or "stream." Choosing something + and being consistent helps users scan the man pages quickly + and understand what they are looking at. + +locale.5 + Akihiro Motoki + Correct variable name + +proc.5 + Michael Kerrisk + Remove bogus statement about NR_OPEN being a ceiling for file-max + + +==================== Changes in man-pages-3.79 ==================== + +Released: 2015-02-01, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Akihiro Motoki +Heinrich Schuchardt +J William Piggott +Masanari Iida +Michael Kerrisk +Scot Doyle +Sergey V. Zubkov +Stephan Mueller +Vince Weaver +Vivek Goyal + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +getrandom.2 + Heinrich Schuchardt, Theodore T'so, Michael Kerrisk + New page documenting getrandom(2) + Kernel 3.17 introduces a new system call getrandom(2). + +kexec_load.2 + Vivek Goyal, Michael Kerrisk + Add documentation of kexec_file_load(2) + Michael Kerrisk, Vivek Goyal + Rewrite and extend documentation of kexec_load(). + + +New and changed links +--------------------- + +kexec_file_load.2 + Michael Kerrisk + New link to kexec_load.2 + +Changes to individual pages +--------------------------- + +personality.2 + Michael Kerrisk + SEE ALSO: add setarch(8) + +prctl.2 + Michael Kerrisk + Unused arguments of PR_MPX_(EN,DIS}ABLE_MANAGEMENT must be zero + +reboot.2 + Michael Kerrisk + SEE ALSO: add kexec_load(2) + +socket.2 + Stephan Mueller + document AF_ALG + Add a reference to the AF_ALG protocol accessible via socket(2). + +fflush.3 + Michael Kerrisk [Sergey V. Zubkov] + Clarify that flushing of input streams occurs only for seekable files + See https://bugzilla.kernel.org/show_bug.cgi?id=91931 + Michael Kerrisk [Sergey V. Zubkov] + POSIX.1-2008 specifies the behavior when flushing input streams + POSIX.1-2001 did not have a specification for input streams, + but POSIX.1-2008 added one. + +getopt.3 + Michael Kerrisk + SEE ALSO: add getopt(1) + +random.3 + Heinrich Schuchardt + SEE ALSO: add getrandom(2) + +termios.3 + Michael Kerrisk + SEE ALSO: add reset(1), setterm(1), tput(1) + +tzset.3 + J William Piggott + Document behavior when TZ filespec omits the colon + If the TZ filespec omits the leading colon, glibc will parse + it for any valid format, i.e., it will still work. + J William Piggott + Add description for posixrules file + J William Piggott + Correct system timezone file path + J William Piggott + There are only two TZ formats + tzset(3) currently states that there are three TZ formats. The + first two it lists are actually variations of the POSIX-style + TZ format, of which there are at least five variations. + + This patch corrects this to match the POSIX specification of + TZ having only two formats. + J William Piggott + Filespec omitted incorrect + Paragraph three of the DESCRIPTION section says + that when TZ is set, but empty, then UTC is used. + + Later it says if the TZ filespec is omitted then the file + /usr/share/zoneinfo/localtime is used. This is incorrect, + it will use UTC in that case as well. + J William Piggott + Fix incorrect TZ string representation + The TZ string representation indicates that the start/end + rules are required; this is incorrect. + J William Piggott + Add ENVIRONMENT section + other rearrangements + FILES section was overly verbose and included + environment variables. Added ENVIRONMENT section, + removing ENV VARS from the FILES section. + +random.4 + Heinrich Schuchardt + SEE ALSO: add getrandom(2) + +passwd.5 + Michael Kerrisk + SEE ALSO: add chfn(1), chsh(1) + +capabilities.7 + Michael Kerrisk + SEE ALSO: add setpriv(1) + +signal.7 + Michael Kerrisk + Add getrandom(2) to list of restartable system calls + Michael Kerrisk + Add F_OFD_SETLKW to list of restartable operations + + + +==================== Changes in man-pages-3.80 ==================== + +Released: 2015-02-21, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Akihiro Motoki +Andy Lutomirski +Bill McConnaughey +Chris Mayo +Christophe Blaess +David Wilson +Denys Vlasenko +Doug Goldstein +Eric Wong +Heinrich Schuchardt +J William Piggott +James Hunt +Jan Chaloupka +Jan Stancek +Jeff Layton +Jens Thoms Toerring +Kevin Easton +Luke Faraone +Mark Seaborn +Mathieu Malaterre +Michael Kerrisk +Michal Hocko +Minchan Kim +Patrick Horgan +Peng Haitao +Ralf Baechle +Rob Somers +Simon Paillard +Stephen Smalley +Tao Ma +Tobias Herzke +Vince Weaver +Vlastimil Babka +Zbigniew Brzeziński + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +ioctl_fat.2 + Heinrich Schuchardt [Michael Kerrisk] + New man page for the ioctl(2) FAT API + The ioctl(2) system call may be used to retrieve information about + the FAT file system and to set file attributes. + +madvise.2 + Michael Kerrisk + Summary: this page has been significantly reorganised and rewritten + Michael Kerrisk + Recast discussion of 'advice' into two groups of values + madvise() is one of those system calls that has congealed over + time, as has the man page. It's helpful to split the discussion + of 'advice' into those flags into two groups: + + * Those flags that are (1) widespread across implementations; + (2) have counterparts in posix_madvise(3); and (3) were present + in the initial Linux madvise implementation. + * The rest, which are values that (1) may not have counterparts + in other implementations; (2) have no counterparts in + posix_madvise(3); and (3) were added to Linux in more recent + times. + Michael Kerrisk + Explicitly list the five flags provided by posix_fadvise() + Over time, bit rot has afflicted this page. Since the original + text was written many new Linux-specific flags have been added. + So, now it's better to explicitly list the flags that + correspond to the POSIX analog of madvise(). + Jan Chaloupka [Hugh Dickins, Michael Kerrisk] + Starting with Linux 3.5, more file systems support MADV_REMOVE + Michael Kerrisk + Split EINVAL error into separate cases + Michael Kerrisk + Explain MADV_REMOVE in terms of file hole punching + Michael Kerrisk + MADV_REMOVE can be applied only to shared writable mappings + Michael Kerrisk + MADV_REMOVE cannot be applied to locked or Huge TLB pages + Michael Kerrisk [Vlastimil Babka] + Clarify that MADV_DONTNEED has effect on pages only if it succeeds + Michael Kerrisk [Vlastimil Babka] + Clarifications for MADV_DONTNEED + Michael Kerrisk [Michal Hocko] + Improve MADV_DONTNEED description + Michael Kerrisk + MADV_DONTNEED cannot be applied to Huge TLB or locked pages + Michael Kerrisk [Vlastimil Babka] + Remove mention of "shared pages" as a cause of EINVAL for MADV_DONTNEED + Michael Kerrisk [Vlastimil Babka] + Note Huge TLB as a cause of EINVAL for MADV_DONTNEED + Michael Kerrisk [Minchan Kim] + Add mention of VM_PFNMAP in discussion of MADV_DONTNEED and MADV_REMOVE + Michael Kerrisk + Drop sentence saying that kernel may ignore 'advice' + The sentence creates misunderstandings, and does not really + add information. + Michael Kerrisk + Note that some Linux-specific 'advice' change memory-access semantics + Michael Kerrisk + NOTES: Remove crufty text about "command" versus "advice" + The point made in this fairly ancient text is more or less evident + from the DESCRIPTION, and it's not clear what "standard" is being + referred to. + Michael Kerrisk + Mention POSIX.1-2008 addition of POSIX_MADV_NOREUSE + Michael Kerrisk + Remove "POSIX.1b" from CONFORMING TO + Michael Kerrisk + Move mention of posix_fadvise() from CONFORMING TO to SEE ALSO + Michael Kerrisk + ERRORS: add EPERM error case for MADV_HWPOISON + Michael Kerrisk + Note that madvise() is nonstandard, but widespread + + +Newly documented interfaces in existing pages +--------------------------------------------- + +proc.5 + Michael Kerrisk + (Briefly) document /proc/PID/attr/socketcreate + Michael Kerrisk + (Briefly) document /proc/PID/attr/keycreate + Michael Kerrisk [Stephen Smalley] + Document /proc/PID/attr/{current,exec,fscreate,prev} + Heavily based on Stephen Smalley's text in + https://lwn.net/Articles/28222/ + From: Stephen Smalley + To: LKML and others + Subject: [RFC][PATCH] Process Attribute API for Security Modules + Date: 08 Apr 2003 16:17:52 -0400 + Michael Kerrisk + Document /proc/sys/kernel/auto_msgmni + +socket.7 + David Wilson [Michael Kerrisk] + Document SO_REUSEPORT socket option + + +New and changed links +--------------------- + +get_thread_area.2 + Andy Lutomirski + Make get_thread_area.2 a link to rewritten set_thread_area.2 page + + +Changes to individual pages +--------------------------- + +time.1 + Michael Kerrisk + Make option argument formatting consistent with other pages + +access.2 + Denys Vlasenko + Explain how access() check treats capabilities + We have users who are terribly confused why their binaries + with CAP_DAC_OVERRIDE capability see EACCESS from access() calls, + but are able to read the file. + + The reason is access() isn't the "can I read/write/execute this + file?" question, it is the "(assuming that I'm a setuid binary,) + can *the user who invoked me* read/write/execute this file?" + question. + + That's why it uses real UIDs as documented, and why it ignores + capabilities when capability-endorsed binaries are run by non-root + (this patch adds this information). + + To make users more likely to notice this less-known detail, + the patch expands the explanation with rationale for this logic + into a separate paragraph. + +arch_prctl.2 +set_thread_area.2 +get_thread_area.2 + Andy Lutomirski + Improve TLS documentation + The documentation for set_thread_area was very vague. This + improves it, accounts for recent kernel changes, and merges + it with get_thread_area.2. + + get_thread_area.2 now becomes a link. + + While I'm at it, clarify the related arch_prctl.2 man page. + +cacheflush.2 + Ralf Baechle + Update some portability details and bugs + Michael Kerrisk + Refer reader to BUGS in discussion of EINVAL error + +capget.2 + Michael Kerrisk + Document V3 capabilities constants + Michael Kerrisk + Rewrite discussion of kernel versions that support file capabilities + File capabilities ceased to be optional in Linux 2.6.33. + +clone.2 + Peng Haitao + Fix description of CLONE_PARENT_SETTID + CLONE_PARENT_SETTID only stores child thread ID in parent memory. + +clone.2 +execve.2 + Kevin Easton + Document interaction of execve(2) with CLONE_FILES + This patch the fact that a successful execve(2) in a process that + is sharing a file descriptor table results in unsharing the table. + + I discovered this through testing and verified it by source + inspection - there is a call to unshare_files() early in + do_execve_common(). + +fcntl.2 + Michael Kerrisk [Jeff Layton] + Clarify cases of conflict between traditional record and OFD locks + Verified by experiment on Linux 3.15 and 3.19rc4. + +fork.2 + Michal Hocko + EAGAIN is not reported when task allocation fails + I am not sure why we have: + + "EAGAIN fork() cannot allocate sufficient memory to copy + the parent's page tables and allocate a task structure + or the child." + + The text seems to be there from the time when man-pages + were moved to git so there is no history for it. + + And it doesn't reflect reality: the kernel reports both + dup_task_struct and dup_mm failures as ENOMEM to the + userspace. This seems to be the case from early 2.x times + so let's simply remove this part. + Heinrich Schuchardt + Child and parent run in separate memory spaces + fork.2 should clearly point out that child and parent + process run in separate memory spaces. + Michael Kerrisk + NOTES: add "C library/kernel ABI differences" subheading + +getpid.2 + Michael Kerrisk + NOTES: add "C library/kernel ABI differences" subheading + +getxattr.2 + Michael Kerrisk + Various rewordings plus one or two details clarified + Michael Kerrisk + Add pointer to example in listxattr(2) + +killpg.2 + Michael Kerrisk + NOTES: add "C library/kernel ABI differences" subheading + +listxattr.2 + Heinrich Schuchardt + Provide example program + Michael Kerrisk + Reword discussion of size==0 case + Michael Kerrisk + Add note on handling increases in sizes of keys or values + Michael Kerrisk + Remove mention of which filesystems implement ACLs + Such a list will only become outdated (as it already was). + +migrate_pages.2 + Jan Stancek + Document EFAULT and EINVAL errors + I encountered these errors while writing testcase for migrate_pages + syscall for LTP (Linux test project). + + I checked stable kernel tree 3.5 to see which paths return these. + Both can be returned from get_nodes(), which is called from: + SYSCALL_DEFINE4(migrate_pages, pid_t, pid, unsigned long, maxnode, + const unsigned long __user *, old_nodes, + const unsigned long __user *, new_nodes) + + The testcase does following: + EFAULT + a) old_nodes/new_nodes is area mmaped with PROT_NONE + b) old_nodes/new_nodes is area not mmapped in process address + space, -1 or area that has been just munmmaped + + EINVAL + a) maxnodes overflows kernel limit + b) new_nodes contain node, which has no memory or does not exist + or is not returned for get_mempolicy(MPOL_F_MEMS_ALLOWED). + +modify_ldt.2 + Andy Lutomirski + Overhaul the documentation + This clarifies the behavior and documents all four functions. + Andy Lutomirski + Clarify the lm bit's behavior + The lm bit should never have existed in the first place. Sigh. + +mprotect.2 + Mark Seaborn + Mention effect of READ_IMPLIES_EXEC personality flag + I puzzled over mprotect()'s effect on /proc/*/maps for a while + yesterday -- it was setting "x" without PROT_EXEC being specified. + Here is a patch to add some explanation. + +msgget.2 + Michael Kerrisk + Add details of MSGMNI default value + +msgop.2 + Michael Kerrisk + Clarify wording of MSGMAX and MSGMNB limits + +perf_event_open.2 + Vince Weaver + Clarify PERF_EVENT_IOC_REFRESH behavior + Currently the PERF_EVENT_IOC_REFRESH ioctl, when applied to a group + leader, will refresh all children. Also if a refresh value of 0 + is chosen then the refresh becomes infinite (never runs out). + Back in 2011 PAPI was relying on these behaviors but I was told + that both were unsupported and subject to being removed at any time. + (See https://lkml.org/lkml/2011/5/24/337 ) + However the behavior has not been changed. + + This patch updates the manpage to still list the behavior as + unsupported, but removes the inaccurate description of it + only being a problem with 2.6 kernels. + +prctl.2 + Michael Kerrisk [Bill McConnaughey] + Mention file capabilities in discussion of PR_SET_DUMPABLE + Michael Kerrisk + Greatly expand discussion of "dumpable" flag + In particular, detail the interactions with + /proc/sys/fs/suid_dumpable. + Michael Kerrisk + Reorder paragraphs describing PR_SET_DUMPABLE + Michael Kerrisk + Mention SUID_DUMP_DISABLE and SUID_DUMP_USER under PR_SET_DUMPABLE + Michael Kerrisk + Executing a file with capabilities also resets the parent death signal + +ptrace.2 + James Hunt + Explain behaviour should ptrace tracer call execve(2) + This behaviour was verified by reading the kernel source and + confirming the behaviour using a test program. + Denys Vlasenko + Add information on PTRACE_SEIZE versus PTRACE_ATTACH differences + Extend description of PTRACE_SEIZE with the short summary of its + differences from PTRACE_ATTACH. + + The following paragraph: + + PTRACE_EVENT_STOP + Stop induced by PTRACE_INTERRUPT command, or group-stop, or ini- + tial ptrace-stop when a new child is attached (only if attached + using PTRACE_SEIZE), or PTRACE_EVENT_STOP if PTRACE_SEIZE was used. + + has an editing error (the part after last comma makes no sense). + Removing it. + + Mention that legacy post-execve SIGTRAP is disabled by PTRACE_SEIZE. + +sched_setattr.2 + Michael Kerrisk [Christophe Blaess] + SYNOPSIS: remove 'const' from 'attr' sched_getattr() argument + +semget.2 + Michael Kerrisk + Note default value for SEMMNI and SEMMSL + +semop.2 + Michael Kerrisk + Note defaults for SEMOPM and warn against increasing > 1000 + +sendfile.2 + Eric Wong + Caution against modifying sent pages + +setxattr.2 + Michael Kerrisk + ERRORS: add ENOTSUP for invalid namespace prefix + Michael Kerrisk + Remove redundant text under ENOTSUP error + Michael Kerrisk + Note that zero-length attribute values are permitted + Michael Kerrisk + Rework text describing 'flags' argument + +stat.2 + Michael Kerrisk + NOTES: add "C library/kernel ABI differences" subheading + +statfs.2 + Michael Kerrisk [Jan Chaloupka] + Document the 'f_flags' field added in Linux 2.6.36 + Michael Kerrisk + Clarify that 'statfs' structure has some padding bytes + The number of padding bytes has changed over time, as some + bytes are used, so describe this aspect of the structure + less explicitly. + Tao Ma + Add OCFS2_SUPER_MAGIC + Michael Kerrisk + Use __fsword_t in statfs structure definition + This more closely matches modern glibc reality. + Michael Kerrisk + Add a note on the __fsword_t type + Michael Kerrisk + Document 'f_spare' more vaguely + +wait.2 + Michael Kerrisk + Note that waitpid() is a wrapper for wait4() + Michael Kerrisk + Note that wait() is a library function implemented via wait4() + +wait4.2 + Michael Kerrisk + NOTES: add "C library/kernel ABI differences" subheading + +encrypt.3 + Rob Somers + Improve code example + I (and some others) found that the original example code + did not seem to work as advertised. The new code (used by + permission of the original author, Jens Thoms Toerring) + was found on comp.os.linux.development. + +mktemp.3 + Luke Faraone + DESCRIPTION reference to BUGS corrected + mktemp(3)'s DESCRIPTION referenced NOTES, but no such + section exists. Corrected to refer to BUGS. + +pthread_attr_setschedparam.3 + Tobias Herzke + Describe EINVAL in ERRORS + +resolver.3 +host.conf.5 + Simon Paillard + host.conf 'order' option deprecated, replaced by nsswitch.conf(5) + http://www.sourceware.org/bugzilla/show_bug.cgi?id=2389 + http://repo.or.cz/w/glibc.git/commit/b9c65d0902e5890c4f025b574725154032f8120a + + Reported at http://bugs.debian.org/270368, + http://bugs.debian.org/396633, and http://bugs.debian.org/344233. + +statvfs.3 + Michael Kerrisk + Document missing 'f_flag' bit values + And reorganize information relating to which flags are in + POSIX.1. + Michael Kerrisk [Jan Chaloupka] + statvfs() now populates 'f_flag' from statfs()'s f_flag field + These changes came with glibc 2.13, and the kernel's addition of + a 'f_flags' field in Linux 2.6.36. + +syslog.3 + Michael Kerrisk [Doug Goldstein] + Remove unneeded + vsyslog() does not need this. + +tzset.3 + J William Piggott + Add offset format + tzset.3 does not illustrate the POSIX offset format. + Specifically, there is no indication in the manual + what the optional components of it are. + +random.4 + Michael Kerrisk + Note maximum number of bytes returned by read(2) on /dev/random + Michael Kerrisk [Mathieu Malaterre] + Since Linux 3.16, reads from /dev/urandom return at most 32 MB + See https://bugs.debian.org/775328 and + https://bugzilla.kernel.org/show_bug.cgi?id=80981#c9 + +core.5 + Michael Kerrisk [Bill McConnaughey] + Executing a file that has capabilities also prevents core dumps + Michael Kerrisk + Document "%i" and "%I" core_pattern specifiers + +intro.5 + Michael Kerrisk + Remove words "and protocols" + There are no protocol descriptions in Section 5. Protocols are + in Section 7. + +proc.5 + Michael Kerrisk + Add reference to prctl(2) in discussion of /proc/sys/fs/suid_dumpable + And note that /proc/sys/fs/suid_dumpable defines the + value assigned to the process "dumpable" flag in certain + circumstances. + Michael Kerrisk + Note that CAP_SYS_ADMIN is required to list /proc/PID/map_files + This might however change in the future; see the Jan 2015 LKML thread: + + Re: [RFC][PATCH v2] procfs: Always expose /proc//map_files/ + and make it readable + +resolv.conf.5 + Michael Kerrisk + SEE ALSO: add nsswitch.conf(5) + +capabilities.7 + Michael Kerrisk + Mention SECBIT_KEEP_CAPS as an alternative to prctl() PR_SET_KEEPCAPS + Chris Mayo + NOTES: add last kernel versions for obsolete options + The CONFIG_SECURITY_CAPABILITIES option was removed by + commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 + + The CONFIG_SECURITY_FILE_CAPABILITIES option removed in + Linux 2.6.33 as already mentioned in DESCRIPTION. + +pthreads.7 + Michael Kerrisk + SEE ALSO: add fork(2) + +unix.7 + Jan Chaloupka + Mention SOCK_STREAM socket for ioctl_type of ioctl() + from https://bugzilla.redhat.com/show_bug.cgi?id=1110401. + + unix.7 is not clear about socket type of ioctl_type argument of + ioctl() function. The description of SIOCINQ is applicable only + for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives + correct description of SIOCINQ + +ldconfig.8 + Michael Kerrisk + Place options in alphabetical order + Michael Kerrisk + Note glibc version number for '-l' option + Michael Kerrisk + Document -c/--format option + Michael Kerrisk + Add long form of some options + Michael Kerrisk [Patrick Horgan] + ld.so.conf uses only newlines as delimiters + mtk: confirmed by reading source of parse_conf() in + elf/ldconfig.c. + Michael Kerrisk + Document -V/--version option + Michael Kerrisk + Document -i/--ignore-aux-cache option + +ld.so.8 + Michael Kerrisk + Relocate "Hardware capabilities" to be a subsection under notes + This is more consistent with standard man-pages headings + and layout. + Michael Kerrisk + (Briefly) document LD_TRACE_PRELINKING + Michael Kerrisk + Remove duplicate description of LD_BIND_NOT + + +==================== Changes in man-pages-3.81 ==================== + +Released: 2015-03-02, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alexandre Oliva +Carlos O'Donell +Ma Shimiao +Michael Kerrisk +Peng Haitao + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +attributes.7 + Alexandre Oliva, Michael Kerrisk [Carlos O'Donell] + New page describing POSIX safety concepts + + +Global changes +-------------- + +Many pages + Peng Haitao, Michael Kerrisk + Reformat existing thread-safety information to use a + tabular format, rather than plain text. + + +Changes to individual pages +--------------------------- + +mmap.2 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function mmap() and munmap() are thread safe. + +a64l.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +acos.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function acos(), acosf() and acosl() are thread safe. + +acosh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function acosh(), acoshf() and acoshl() are thread safe. + +addseverity.3 + Ma Shimiao + ATTRIBUTES: Note function is thread-safe + The function addseverity() is thread safe. + +aio_cancel.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function aio_cancel() is thread safe. + +aio_fsync.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function aio_fsync() is thread safe. + +aio_read.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function aio_read() is thread safe. + +aio_suspend.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function aio_suspend() is thread safe. + +aio_write.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function aio_write() is thread safe. + +argz_add.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + +asin.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function asin(), asinf() and asinl() are thread safe. + +assert.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + Its marking matches glibc marking. + +assert_perror.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + Its marking matches glibc marking. + +atan2.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function atan2(), atan2f() and atan2l() are thread safe. + +atanh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function atanh(), atanhf() and atanhl() are thread safe. + +backtrace.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The markings match glibc markings. + +btowc.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function btowc() in glibc is thread safe. + Its marking matches glibc marking. + +cabs.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function cabs(), cabsf() and cabsl() are thread safe. + +cacos.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function cacos(), cacosf() and cacosl() are thread safe. + +cacosh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions cacosh(), cacoshf() and cacoshl() in glibc are + thread safe. Its markings match glibc markings. + +canonicalize_file_name.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The functions canonicalize_file_name() in glibc is thread safe. + Its marking matches glibc marking. + +carg.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function carg(), cargf() and cargl() are thread safe. + +casin.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions casin(), casinf() and casinl() are thread safe. + Their markings match glibc markings. + +casinh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions casinh(), casinhf() and casinhl() in glibc are + thread safe. Its markings match glibc markings. + +catan.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions catan(), catanf() and catanl() are thread safe. + Their markings match glibc markings. + +catanh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions catanh(), catanhf() and catanhl() in glibc are + thread safe. Its markings match glibc markings. + +catopen.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions catopen() and catclose() are thread safe. + +cfree.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function cfree() in glibc is thread safe. + Its marking matches glibc marking. + +clog10.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions clog10(), clog10f() and clog10l() in glibc are + thread safe. Its markings match glibc markings. + +clog.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function clog(), clogf() and clogl() are thread safe. + +closedir.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function closedir() in glibc is thread safe. + Its marking matches glibc marking. + +confstr.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function confstr() is thread safe. + +cosh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions cosh(), coshf() and coshl() in glibc are thread safe. + Its markings match glibc markings. + +cpow.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions cpow(), cpowf() and cpowl() in glibc are thread safe. + Its markings match glibc markings. + +crypt.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +ctermid.3 + Ma Shimiao + Modify thread-safety information + According to the change of source code, ctermid's level has been + changed from MT-Unsafe to MT-Safe. After modifying, the marking + matches the glibc marking. + +drand48.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +drand48_r.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +ecvt.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be same as glibc manual. + +ecvt_r.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The markings match glibc markings. + +encrypt.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +envz_add.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +exec.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions execl(), execlp(), execle(), execv(), execvp() and + execvpe() are thread safe. + +exit.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +exp10.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + +exp2.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function exp2(), exp2f() and exp2l() are thread safe. + +exp.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function exp(), expf() and expl() are thread safe. + +fclose.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The function fclose() is thread safe. + Its marking matches glibc marking. + +fcloseall.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +fgetc.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +fgetwc.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +fgetws.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +fmod.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function fmod(), fmodf() and fmodl() are thread safe. + +fnmatch.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function fnmatch() is thread safe with exceptions. + +fopen.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The markings match glibc markings. + +fopencookie.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +fread.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions fread() and fwrite() are thread safe. + +gamma.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions gamma(), gammaf() and gammal() are not thread safe. + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getcontext.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getcwd.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions getcwd(), getwd() and get_current_dir_name() are + thread safe. + +getdate.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getenv.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions getenv() and secure_getenv() are thread safe. + +getfsent.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions setfsent(), getfsent(), endfsent(), getfsspec() + and getfsfile() are not thread safe. + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getgrent.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + Its marking matches glibc marking. + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getgrnam.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getgrouplist.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function getgrouplist() is thread safe with exceptions. + +getlogin.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getopt.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions getopt(), getopt_long() and getopt_long_only() are + not thread safe. + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getpass.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getpwent.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +getpwnam.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +gets.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + Its marking matches glibc marking. + +getw.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions getw() and putw() are thread safe. + +gnu_get_libc_version.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions gnu_get_libc_version() and gnu_get_libc_release() + are thread safe. + +hsearch.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +iconv.3 + Peng Haitao + Modify thread-safety information + +inet.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions inet_aton() and inet_addr() are thread safe with + exceptions. + The functions inet_network(), inet_ntoa(), inet_makeaddr(), + inet_lnaof() and inet_netof() are thread safe. + Modify thread-safety information + After researching and talking, we think inet_network() and + inet_ntoa() should be marked with locale. + After changing, the markings match glbc markings. + +inet_pton.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function inet_pton() is thread safe with exceptions. + +iswdigit.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswdigit() is thread safe with exceptions. + +iswgraph.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswgraph() is thread safe with exceptions. + +iswlower.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswlower() is thread safe with exceptions. + +iswprint.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswprint() is thread safe with exceptions. + +iswpunct.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswpunct() is thread safe with exceptions. + +iswspace.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswspace() is thread safe with exceptions. + +iswupper.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswupper() is thread safe with exceptions. + +iswxdigit.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function iswxdigit() is thread safe with exceptions. + +j0.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function j0(), j1f() jnl() and so on are thread safe. + +lio_listio.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + Its marking matches glibc marking. + +log10.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function log10(), log10f() and log10l() are thread safe. + +log2.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function log2(), log2f() and log2l() are thread safe. + +log.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function log(), logf() and logl() are thread safe. + +makecontext.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +makedev.3 + Peng Haitao + ATTRIBUTES: Note macros that are thread-safe + The macros makedev(), major() and minor() are thread safe. + +malloc.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function malloc(), free(), calloc() and realloc() are + thread safe. + +mblen.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +mbstowcs.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +mbtowc.3 + Peng Haitao + ATTRIBUTES: Note function that is not thread-safe + The function mbtowc() is not thread safe. + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +mktemp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function mktemp() is thread safe. + +mtrace.3 + Peng Haitao + ATTRIBUTES: Note functions that are not thread-safe + The functions mtrace() and muntrace() are not thread safe. + +nan.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +nl_langinfo.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function nl_langinfo() is thread safe with exceptions. + +opendir.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The markings match glibc markings. + +pow10.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function pow10(), pow10f() and pow10l() are thread safe. + +pow.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function pow(), powf() and powl() are thread safe. + +pthread_setcancelstate.3 + Michael Kerrisk + Add async-signal-safety information + +ptsname.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +putenv.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-unsafe + The function putenv() is thread unsafe. + +puts.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread-safe + The functions fputc(), fputs(), putc(), putchar() and puts() are + thread safe. + +putwchar.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +qecvt.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be same as glibc manual. + +rand.3 + Peng Haitao + ATTRIBUTES: Note macros that are thread-safe + The functions rand(), rand_r() and srand() are thread safe. + +random_r.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +readdir.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be same as glibc manual. + +realpath.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +regex.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions regcomp() and regexec() are thread safe with + exceptions. + The functions regerror() and regfree() are thread safe. + +remainder.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The markings match glibc markings. + +scalb.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function scalb(), scalbf() and scalbl() are thread safe. + +setenv.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-unsafe + The function setenv() and unsetenv() are thread unsafe. + +siginterrupt.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +sigset.3 + Peng Haitao + ATTRIBUTES: Note macros that are thread-safe + The functions sigset(), sighold(), sigrelse() and sigignore() + are thread safe. + +sinh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function sinh(), sinhf() and sinhl() are thread safe. + +sqrt.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function sqrt(), sqrtf() and sqrtl() are thread safe. + +stdarg.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +stdio_ext.3 + Ma Shimiao + Modify thread-safety information + Change the thread safety information to be the same as glibc. + +strcasecmp.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions strcasecmp() and strncasecmp() are thread safe + with exceptions. + +strerror.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +strfmon.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + Its marking matches glibc marking. + +strfry.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function strfry() is thread safe. + +strftime.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function strftime() is thread safe with exceptions. + +strptime.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function strptime() is thread safe with exceptions. + +strtok.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +strverscmp.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function strverscmp() is thread safe. + +strxfrm.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +syslog.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions openlog() and closelog() are thread safe. + The functions syslog() and vsyslog() are thread safe with + exceptions. + +tempnam.3 + Peng Haitao + ATTRIBUTES: Note function that is thread-safe + The function tempnam() is thread safe. + +termios.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + Ma Shimiao + Modify thread-safety information + As this is man page for Linux, we don't need thread safety + information for bsd + +tgamma.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions tgamma(), tgammaf() and tgammal() in glibc are + thread safe. Its markings match glibc markings. + +timegm.3 + Peng Haitao + ATTRIBUTES: Note functions that are thread safe with exceptions + The functions timelocal() and timegm() are thread safe with + exceptions. + +tmpfile.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + Its markings match glibc markings. + +tmpnam.3 + Peng Haitao + Modify thread-safety information + When the argument s is NULL, tmpnam() should be MT-Unsafe. + +toupper.3 + Ma Shimiao + Modify thread-safety information + After researching and talking, we think toupper() and tolower() + should not be marked with locale. + After changing, the markings match glbc markings. + +tsearch.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The functions' markings match glibc markings. + +ttyname.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be same as glibc manual. + +tzset.3 + Peng Haitao + ATTRIBUTES: Note function that is thread safe with exceptions + The function tzset() is thread safe with exceptions. + +wcsdup.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + Its marking matches glibc marking. + +wctomb.3 + Ma Shimiao + Modify thread-safety information + As annotation in glibc manual is more detailed, change the + thread-safety information to be the same as glibc manual. + +y0.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The function y0(), y1f() ynl() and so on are thread safe. + +man-pages.7 + Michael Kerrisk + Refer reader to attributes(7) for details of ATTRIBUTES section + Michael Kerrisk + SEE ALSO: add attributes(7) + +pthreads.7 + Michael Kerrisk + SEE ALSO: add attributes(7) + +standards.7 + Michael Kerrisk + SEE ALSO: add attributes(7) + + + +==================== Changes in man-pages-3.82 ==================== + +Released: 2015-03-29, Paris + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alban Crequy +Andy Lutomirski +Bert Wesarg +Bill Pemberton +Chris Delozier +David Madore +Dmitry Deshevoy +Eric W. Biederman +Heinrich Schuchardt +Jakub Wilk +Jann Horn +Jason Vas Dias +Josh Triplett +J William Piggott +Kees Cook +Konstantin Shemyak +Ma Shimiao +Matt Turner +Michael Kerrisk +Michael Witten +Mikael Pettersson +Namhyung Kim +Nicolas FRANCOIS +Paul E Condon +Peter Adkins +Scot Doyle +Shawn Landden +Stéphane Aulery +Stephen Smalley +Taisuke Yamada +Torvald Riegel +Vincent Lefevre + +Yuri Kozlov + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +nptl.7 + Michael Kerrisk + New page with details of the NPTL POSIX threads implementation + + +Newly documented interfaces in existing pages +--------------------------------------------- + +user_namespaces.7 + Eric W. Biederman [Michael Kerrisk] + Document /proc/[pid]/setgroups + + +Changes to individual pages +--------------------------- + +intro.1 + Stéphane Aulery + Prompt is not % but $ + Stéphane Aulery + Various improvements + - Add reference to other common shells dash(1), ksh(1) + - Add a reference to stdout(3) + - Separate cp and mv descriptions + - Add examples of special cases of cd + - Add su(1) and shutdown(8) references for section Logout + and poweroff + - Move Control-D to section Logout and poweroff + - Fix some little formatting errors + Stéphane Aulery + Add cross references cited + Stéphane Aulery + Order SEE ALSO section + +clone.2 + Josh Triplett + Document that clone() silently ignores CLONE_PID and CLONE_STOPPED + Normally, system calls return EINVAL for flags they don't support. + Explicitly document that clone does *not* produce an error for + these two obsolete flags. + Michael Kerrisk + Small rewording of explanation of clone() wrt threads + Clone has so many effects that it's an oversimplification to say + that the *main* use of clone is to create a thread. (In fact, + the use of clone() to create new processes may well be more + common, since glibc's fork() is a wrapper that calls clone().) + +getgroups.2 + Michael Kerrisk [Shawn Landden] + Add discussion of NPTL credential-changing mechanism + At the kernel level, credentials (UIDs and GIDs) are a per-thread + attribute. NPTL uses a signal-based mechanism to ensure that + when one thread changes its credentials, all other threads change + credentials to the same values. By this means, the NPTL + implementation conforms to the POSIX requirement that the threads + in a process share credentials. + Michael Kerrisk + ERRORS: add EPERM for the case where /proc/PID/setgroups is "deny" + Michael Kerrisk + Note capability associated with EPERM error for setgroups(2) + Michael Kerrisk + Refer reader to user_namespaces(7) for discussion of /proc/PID/setgroups + The discussion of /proc/PID/setgroups has moved from + proc(5) to user_namespaces(7). + +getpid.2 + Michael Kerrisk + Note that getppid() returns 0 if parent is in different PID namespace + +getsockopt.2 + Konstantin Shemyak + Note RETURN VALUE details when netfilter is involved + +ioctl_list.2 + Heinrich Schuchardt + SEE ALSO ioctl_fat.2 + Add FAT_IOCTL_GET_VOLUME_ID + SEE ALSO ioctl_fat.2 + Heinrich Schuchardt + include/linux/ext2_fs.h + Include linux/ext2_fs.h does not contain any ioctl definitions + anymore. + + Request codes EXT2_IOC* have been replaced by FS_IOC* in + linux/fs.h. + + Some definitions of FS_IOC_* use long* but the actual code expects + int* (see fs/ext2/ioctl.c). + +msgop.2 + Bill Pemberton + Remove EAGAIN as msgrcv() errno + The list of errnos for msgrcv() lists both EAGAIN and ENOMSG as + the errno for no message available with the IPC_NOWAIT flag. + ENOMSG is the errno that will be set. + Bill Pemberton + Add an example program + +open.2 + Michael Kerrisk [Jason Vas Dias] + Mention blocking semantics for FIFO opens + See https://bugzilla.kernel.org/show_bug.cgi?id=95191 + +seccomp.2 + Jann Horn [Kees Cook, Mikael Pettersson, Andy Lutomirski] + Add note about alarm(2) not being sufficient to limit runtime + Jann Horn + Explain blacklisting problems, expand example + Michael Kerrisk [Kees Cook] + Add mention of libseccomp + +setgid.2 + Michael Kerrisk + Clarify that setgid() changes all GIDs when caller has CAP_SETGID + Michael Kerrisk [Shawn Landden] + Add discussion of NPTL credential-changing mechanism + At the kernel level, credentials (UIDs and GIDs) are a per-thread + attribute. NPTL uses a signal-based mechanism to ensure that + when one thread changes its credentials, all other threads change + credentials to the same values. By this means, the NPTL + implementation conforms to the POSIX requirement that the threads + in a process share credentials. + +setresuid.2 + Michael Kerrisk [Shawn Landden] + Add discussion of NPTL credential-changing mechanism + At the kernel level, credentials (UIDs and GIDs) are a per-thread + attribute. NPTL uses a signal-based mechanism to ensure that + when one thread changes its credentials, all other threads change + credentials to the same values. By this means, the NPTL + implementation conforms to the POSIX requirement that the threads + in a process share credentials. + +setreuid.2 + Michael Kerrisk [Shawn Landden] + Add discussion of NPTL credential-changing mechanism + At the kernel level, credentials (UIDs and GIDs) are a per-thread + attribute. NPTL uses a signal-based mechanism to ensure that + when one thread changes its credentials, all other threads change + credentials to the same values. By this means, the NPTL + implementation conforms to the POSIX requirement that the threads + in a process share credentials. + Michael Kerrisk + SEE ALSO: add credentials(7) + +setuid.2 + Michael Kerrisk + Clarify that setuid() changes all UIDs when caller has CAP_SETUID + Michael Kerrisk [Shawn Landden] + Add discussion of NPTL credential-changing mechanism + At the kernel level, credentials (UIDs and GIDs) are a per-thread + attribute. NPTL uses a signal-based mechanism to ensure that + when one thread changes its credentials, all other threads change + credentials to the same values. By this means, the NPTL + implementation conforms to the POSIX requirement that the threads + in a process share credentials. + +sigaction.2 + Michael Kerrisk + Add discussion of rt_sigaction(2) + Michael Kerrisk + Note treatment of signals used internally by NPTL + The glibc wrapper gives an EINVAL error on attempts to change the + disposition of either of the two real-time signals used by NPTL. + +sigpending.2 + Michael Kerrisk + Add discussion of rt_sigpending(2) + +sigprocmask.2 + Michael Kerrisk + Add discussion of rt_sigprocmask(2) + Michael Kerrisk + Note treatment of signals used internally by NPTL + The glibc wrapper silently ignores attempts to block the two + real-time signals used by NPTL. + +sigreturn.2 + Michael Kerrisk + Add discussion of rt_sigreturn(2) + +sigsuspend.2 + Michael Kerrisk + Add discussion of rt_sigsuspend(2) + +sigwaitinfo.2 + Michael Kerrisk + Note treatment of signals used internally by NPTL + The glibc wrappers silently ignore attempts to wait for + signals used by NPTL. + Michael Kerrisk + Add discussion of rt_sigtimedwait(2) + +socket.2 + Heinrich Schuchardt + SEE ALSO close(2) + The description mentions close(2). Hence it should also be + referenced in the SEE ALSO section. + +syscall.2 + Jann Horn + Add x32 ABI + +umount.2 + Eric W. Biederman + Document the effect of shared subtrees on umount(2) + Eric W. Biederman + Correct the description of MNT_DETACH + I recently realized that I had been reasoning improperly about + what umount(MNT_DETACH) did based on an insufficient description + in the umount.2 man page, that matched my intuition but not the + implementation. + + When there are no submounts, MNT_DETACH is essentially harmless to + applications. Where there are submounts, MNT_DETACH changes what + is visible to applications using the detach directories. + Michael Kerrisk + Move "shared mount + umount" text to a subsection in NOTES + +aio_return.3 + Stéphane Aulery + Document the return value on error + Reported by Alexander Holler + +clock.3 + Stéphane Aulery + CLOCKS_PER_SEC = 1000000 is required by XSI, not POSIX + Debian Bug #728213 reported by Tanaka Akira + + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=728213 + +dlopen.3 + Michael Kerrisk + Amend error in description of dlclose() behavior + The current text says that unloading depends on whether + the reference count falls to zero *and no other libraries + are using symbols in this library*. That latter text has + been there since man-pages-1.29, but it seems rather dubious. + How could the implementation know whether other libraries + are still using symbols in this library? Furthermore, no + other implementation's man page mentions this point. + Seems best to drop this point. + Michael Kerrisk + Add some details for RTLD_DEFAULT + Michael Kerrisk + Add some details on RTLD_NEXT and preloading + Michael Kerrisk + RTLD_NEXT works for symbols generally, not just functions + The common use case is for functions, but RTLD_NEXT + also applies to variable symbols. + Michael Kerrisk + dlclose() recursively closes dependent libraries + Note that dlclose() recursively closes dependent libraries + that were loaded by dlopen() + Michael Kerrisk + Rename second dlopen() argument from "flag" to "flags" + This is more consistent with other such arguments + Michael Kerrisk + Reformat text on RTLD_DEFAULT and RTLD_NEXT + +fmemopen.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +fpathconf.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The marking matches glibc marking. + +fputwc.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The marking matches glibc marking. + +fputws.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +fseek.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +fseeko.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +gcvt.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +getline.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The marking matches glibc marking. + +getwchar.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +hypot.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +iconv_open.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +if_nameindex.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The markings match glibc markings. + +initgroups.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The markings match glibc markings. + +mq_open.3 + Torvald Riegel + Add EINVAL error case for invalid name + This behavior is implementation-defined by POSIX. If the name + doesn't start with a '/', glibc returns EINVAL without attempting + the syscall. + +popen.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The marking matches glibc marking. + +pthread_kill.3 + Michael Kerrisk + Note treatment of signals used internally by NPTL + The glibc pthread_kill() function gives an error on attempts + to send either of the real-time signals used by NPTL. + +pthread_sigmask.3 + Michael Kerrisk + Note treatment of signals used internally by NPTL + The glibc implementation silently ignores attempts to block the two + real-time signals used by NPTL. + +pthread_sigqueue.3 + Michael Kerrisk + Note treatment of signals used internally by NPTL + The glibc pthread_sigqueue() function gives an error on attempts + to send either of the real-time signals used by NPTL. + +resolver.3 + Stéphane Aulery [Jakub Wilk] + Document missing options used by _res structure indicate defaults + Missing options: RES_INSECURE1, RES_INSECURE2, RES_NOALIASES, + USE_INET6, ROTATE, NOCHECKNAME, RES_KEEPTSIG, BLAST, USEBSTRING, + NOIP6DOTINT, USE_EDNS0, SNGLKUP, SNGLKUPREOP, RES_USE_DNSSEC, + NOTLDQUERY, DEFAULT + + Written from the glibc source and resolv.conf.5. + + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=527136 + Stéphane Aulery + RES_IGNTC is implemented + +rint.3 + Matt Turner + Document that halfway cases are rounded to even + Per IEEE-754 rounding rules. + + The round(3) page describes the behavior of rint and nearbyint + in the halfway cases by saying: + + These functions round x to the nearest integer, but round + halfway cases away from zero [...], instead of to the + nearest even integer like rint(3) + +sigqueue.3 + Michael Kerrisk + NOTES: add "C library/kernel ABI differences" subheading + Michael Kerrisk + Clarify version info (mention rt_sigqueueinfo()) + +sigsetops.3 + Michael Kerrisk + Note treatment of signals used internally by NPTL + The glibc sigfillset() function excludes the two real-time + signals used by NPTL. + +sigwait.3 + Michael Kerrisk + Note treatment of signals used internally by NPTL + The glibc sigwait() silently ignore attempts to wait for + signals used by NPTL. + +strcoll.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The markings match glibc markings. + +strdup.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + The marking matches glibc marking. + +tzset.3 + J William Piggott + Add 'std' quoting information + +ulimit.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +wcstombs.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +wctob.3 + Ma Shimiao + ATTRIBUTES: Note function that is thread-safe + The marking matches glibc marking. + +xdr.3 + Taisuke Yamada + Clarified incompatibility and correct usage of XDR API + See http://bugs.debian.org/628099 + +console_codes.4 + Scot Doyle + Add Console Private CSI sequence 15 + An undocumented escape sequence in drivers/tty/vt/vt.c brings the + previously accessed virtual terminal to the foreground. + mtk: Patch misattributed to Taisuke Yamada in Git commit + because of a muck up on my part. + Michael Kerrisk + Add kernel version number for CSI sequence 15 + +random.4 + Michael Kerrisk + Fix permissions shown for the devices + These days, the devices are RW for everyone. + +filesystems.5 + Michael Kerrisk + Remove dubious claim about comparative performance of ext2 + Perhaps it was the best filesystem performance-wise in + the 20th century, when that text was written. That probably + ceased to be true quite a long time ago, though. + Stéphane Aulery + Add cross references for ext filesystems + Stéphane Aulery + Specifies the scope of this list and its limits. + +host.conf.5 +hosts.5 +resolv.conf.5 + Stéphane Aulery [Paul E Condon] + Cross references of these pages. + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=298259 + +host.conf.5 + Stéphane Aulery + Rework discussion of nospoof, spoofalert, spoof and RESOLV_SPOOF_CHECK + The keywords and environment variables "nospoof", "spoofalert", + "spoof" and RESOLV_SPOOF_CHECK were added to glibc 2.0.7 but + never implemented + + Move descriptions to historical section and reorder it for clarity + + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=773443 + +hosts.5 + Stéphane Aulery [Vincent Lefevre] + Mention 127.0.1.1 for FQDN and IPv6 examples + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=562890 + +proc.5 + Taisuke Yamada + Document /proc/PID/status VmPin field + See https://bugs.launchpad.net/bugs/1071746 + Michael Kerrisk + Document (the obsolete) /proc/PID/seccomp + Michael Kerrisk + Replace description of 'uid_map' with a reference to user_namespaces(7) + All of the information in proc(5) was also present in + user_namespaces(7), but the latter was more detailed + and up to date. + Taisuke Yamada + Fix SELinux /proc/pid/attr/current example + Since the /proc/pid/attr API was added to the kernel, there + have been a couple of changes to the SELinux handling of + /proc/pid/attr/current. Fix the SELinux /proc/pid/attr/current + example text to reflect these changes and note which kernel + versions first included the changes. + +securetty.5 + Stéphane Aulery [Nicolas FRANCOIS] + Note that the pam_securetty module also uses this file + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=528015 + + This patch is a modified version of the one proposed without + parts specific to Debian. + +boot.7 + Michael Witten + Copy edit + While a lot of the changes are issues of presentation, + there are also issues of grammar and punctuation. + Michael Witten + Mention `systemd(1)' and its related `bootup(7)' + It's important that the reader receive contemporary information. + +credentials.7 + Michael Kerrisk + SEE ALSO: add pthreads(7) + Michael Kerrisk + Add reference to nptl(7) + +feature_test_macros.7 + Michael Kerrisk + Update discussion of _FORTIFY_SOURCE + Since the initial implementation a lot more checks were added. + Describe all the checks would be too verbose (and would soon + fall out of date as more checks are added). So instead, describe + the kinds of checks that are done more generally. + Also a few other minor edits to the text. + +hier.7 + Stéphane Aulery + First patch of a series to achieve compliance with FHS 2.3 + Stéphane Aulery + SGML and XML directories are separated in FHS 2.3 + Stéphane Aulery + Add missing directories defined by FHS 2.3 + Stéphane Aulery + Identify which directories are optional + Stéphane Aulery + Document /initrd, /lost+found and /sys + Ubuntu Bug #70094 reported by Brian Beck + https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/70094 + Stéphane Aulery + Explain YP, which is not obvious + +ipv6.7 + Stéphane Aulery [David Madore] + SOL_IPV6 and other SOL_* options socket are not portable + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=472447 + +man-pages.7 + Michael Kerrisk [Bill Pemberton] + Add indent(1) command that produces desired formatting for example code + Stéphane Aulery + Improve description of sections in accordance with intro pages + +packet.7 + Michael Kerrisk + Rework description of fanout algorithms as list + Michael Kerrisk + Remove mention of needing UID 0 to create packet socket + The existing text makes no sense. The check is based + purely on a capability check. (Kernel function + net/packet/af_packet.c::packet_create() + Michael Kerrisk + Remove text about ancient glibc not defining SOL_PACKET + This was fixed in glibc 2.1.1, which is a long while ago. + And in any case, there is nothing special about this case; + it's just one of those times when glibc lags. + Michael Kerrisk + Rework description of 'sockaddr_ll' fields as a list + Michael Kerrisk + Various minor edits + +pthreads.7 + Michael Kerrisk + Add references to nptl(7) + +raw.7 + Michael Kerrisk + Rephrase "Linux 2.2" language to "Linux 2.2 or later" + The man page was written in the LInux 2.2 timeframe, and + some phrasing was not future-proof. + +signal.7 + Michael Kerrisk + Note when Linux added realtime signals + Michael Kerrisk + Correct the range of realtime signals + Michael Kerrisk + Summarize 2.2 system call changes that resulted from larger signal sets + Michael Kerrisk + SEE ALSO: add nptl(7) + +tcp.7 + Peter Adkins + Document removal of TCP_SYNQ_HSIZE + Looking over the man page for 'tcp' I came across a reference to + tuning the 'TCP_SYNQ_HSIZE' parameter when increasing + 'tcp_max_syn_backlog' above 1024. However, this static sizing was + removed back in Linux 2.6.20 in favor of dynamic scaling - as + part of commit 72a3effaf633bcae9034b7e176bdbd78d64a71db. + +user_namespaces.7 + Eric W. Biederman + Update the documentation to reflect the fixes for negative groups + Files with access permissions such as rwx---rwx give fewer + permissions to their group then they do to everyone else. Which + means dropping groups with setgroups(0, NULL) actually grants a + process privileges. + + The unprivileged setting of gid_map turned out not to be safe + after this change. Privileged setting of gid_map can be + interpreted as meaning yes it is ok to drop groups. [ Eric + additionally noted: Setting of gid_map with privilege has been + clarified to mean that dropping groups is ok. This allows + existing programs that set gid_map with privilege to work + without changes. That is, newgidmap(1) continues to work + unchanged.] + + To prevent this problem and future problems, user namespaces were + changed in such a way as to guarantee a user can not obtain + credentials without privilege that they could not obtain without + the help of user namespaces. + + This meant testing the effective user ID and not the filesystem + user ID, as setresuid(2) and setregid(2) allow setting any process + UID or GID (except the supplementary groups) to the effective ID. + + Furthermore, to preserve in some form the useful applications + that have been setting gid_map without privilege, the file + /proc/[pid]/setgroups was added to allow disabling setgroups(2). + With setgroups(2) permanently disabled in a user namespace, it + again becomes safe to allow writes to gid_map without privilege. + Michael Kerrisk + Rework some text describing permission rules for updating map files + No (intentional) change to the facts, but this restructuring + should make the meaning easier to grasp. + Michael Kerrisk + Update kernel version associated with 5-line limit for map files + As at Linux 3.18, the limit is still five lines, so mention the + more recent kernel version in the text. + Michael Kerrisk [Alban Crequy] + Handle /proc/PID/setgroups in the example program + Michael Kerrisk + Rework text describing restrictions on updating /proc/PID/setgroups + No (intentional) changes to factual description, but the + restructured text is hopefully easier to grasp. + Michael Kerrisk + Explain why the /proc/PID/setgroups file was added + +ldconfig.8 + Michael Kerrisk + Note use of /lib64 and /usr/lib64 on some 64-bit architectures + +ld.so.8 + Michael Kerrisk + Note the use of /lib64 and /usr/lib64 on some 64-bit architectures + + + +==================== Changes in man-pages-3.83 ==================== + +Released: 2015-04-19, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Andreas Baak +Andreas Dilger +cdlscpmv +Cyrill Gorcunov +Darrick J. Wong +David Rientjes +Dima Tisnek +Eric Sandeen +Fabien Pichot +Felix Sedlmeier +Gleb Fotengauer-Malinovskiy +Heinrich Schuchardt +Jann Horn +Jon Grant +Jonny Grant +Kees Cook +Masanari Iida +Ma Shimiao +Michael Kerrisk +Nikos Mavrogiannopoulos +Omar Sandoval +Pierre Chifflier +Robin H. Johnson +Rob Landley +Theodore Ts'o +Vlastimil Babka +Walter Harms +William Woodruff +YOSHIFUJI Hideaki +Zeng Linggang + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +posix_madvise.3 + Michael Kerrisk + New page documenting posix_madvise(3) + +ftw.3 + Michael Kerrisk + Reorganize the page to give primacy to nftw() + nftw() is the better API, and POSIX.1-2008 marks ftw() obsolete. + +Newly documented interfaces in existing pages +--------------------------------------------- + +getdents.2 + Michael Kerrisk [Dima Tisnek] + Document getdents64() + See https://bugzilla.kernel.org/show_bug.cgi?id=14795 + +mount.2 + Michael Kerrisk, Theodore Ts'o [Eric Sandeen, Andreas Dilger, + Omar Sandoval, Darrick J. Wong] + Document MS_LAZYTIME + +proc.5 + Michael Kerrisk + Document /proc/sys/kernel/randomize_va_space + Michael Kerrisk + Document /proc/PID/fdinfo epoll format + Michael Kerrisk + Describe /proc/PID/fdinfo eventfd format + Michael Kerrisk + Document /proc/PID/fdinfo signalfd format + + +New and changed links +--------------------- + +newfstatat.2 + Michael Kerrisk + New link to fstatat64.2 + +prlimit64.2 + Michael Kerrisk + New link to getrlimit.2 + + +Global changes +-------------- + +Various section 3 math pages + Michael Kerrisk + Note that these functions are also in POSIX.1-2001 and POSIX.1-2008 + + +Changes to individual pages +--------------------------- + +getent.1 + Robin H. Johnson + Document options + The options to getent are now documented, after being around for + nearly a decade without changes. + Michael Kerrisk + Document help and version options + +fallocate.2 + Michael Kerrisk + Fix kernel version number for FALLOC_FL_ZERO_RANGE + FALLOC_FL_ZERO_RANGE was added in 3.15, not 3.14. + Michael Kerrisk + Note that SMB3 added FALLOC_FL_ZERO_RANGE support in Linux 3.17 + +getrlimit.2 + Michael Kerrisk + Note that the underlying system call for prlimit() is prlimit64() + Michael Kerrisk + Remove "_FILE_OFFSET_BITS == 64" from prlimit() FTM requirements + "_FILE_OFFSET_BITS == 64" is not needed to get the prlimit() + declaration. + +ioctl_list.2 + Nikos Mavrogiannopoulos + SIOCADDRT accepts in6_rtmsg in INET6 protocol + Heinrich Schuchardt + TFD_IOC_SET_TICKS + timerfd_create.2 mentions TFD_IOC_SET_TICKS. We should add it to + ioctl_list.2, too. + +llseek.2 + Michael Kerrisk + Advise reader to use lseek(2) instead + Michael Kerrisk + llseek() exists on 32-bit platforms to support seeking to large offsets + +madvise.2 + David Rientjes + Specify MADV_REMOVE returns EINVAL for hugetlbfs + madvise(2) actually returns with error EINVAL for MADV_REMOVE + when used for hugetlb VMAs, not EOPNOTSUPP, and this has been + the case since MADV_REMOVE was introduced in commit f6b3ec238d12 + ("madvise(MADV_REMOVE): remove pages from tmpfs shm backing + store"). Specify the exact behavior. + Michael Kerrisk + SEE ALSO: add posix_madvise(2) + +poll.2 + Michael Kerrisk [Andreas Baak] + SEE ALSO: add epoll(7) + +posix_fadvise.2 + Michael Kerrisk + Add "C library/kernel ABI differences" subsection + +pread.2 + Michael Kerrisk + Add "C library/kernel ABI differences" subsection + +seccomp.2 + Michael Kerrisk [Pierre Chifflier, Kees Cook] + Note that seccomp_data is read-only + +stat.2 + Michael Kerrisk + Add some details on various "stat" versions + Three versions of "stat" appeared on 32-bit systems, + dealing with structures of different (increasing) sizes. + Explain some of the details, and also note that the + situation is simpler on modern 64-bit architectures. + Michael Kerrisk + Add mention of newfstatat() + The underlying system call for fstatat() is newfstatat() + on some architectures. + +symlink.2 + Michael Kerrisk [Jonny Grant] + ERRORS: add linkpath=="" case for ENOENT + +syscalls.2 + Michael Kerrisk + Remove prlimit() + There really is only the prlimit64() system call. + Michael Kerrisk + Add some details about the "multiple versions of system calls" + The multiple-system-call-version phenomenon is particularly a + feature of older 32-bit platforms. Hint at that fact in the text. + +timerfd_create.2 + Cyrill Gorcunov [Michael Kerrisk] + Document TFD_IOC_SET_TICKS ioctl() operation + Michael Kerrisk + Add some details to C library/kernel ABI differences + +unshare.2 + Michael Kerrisk [Fabien Pichot] + Remove mention of "System V" from discussion of CLONE_NEWIPC + These days, CLONE_NEWIPC also affects POSIX message queues. + +asprintf.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +carg.3 + Michael Kerrisk + Add introductory sentence explaining what these functions calculate + +ccos.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + Michael Kerrisk + Add introductory sentence explaining what these functions calculate + +ccosh.3 + Michael Kerrisk + Add introductory sentence explaining what these functions calculate + +cexp.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + +clock.3 + Ma Shimiao + ATTRIBUTES: Note functions that is thread-safe + +clog.3 + Michael Kerrisk + Add introductory sentence explaining what these functions calculate + +csin.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + Michael Kerrisk + Add introductory sentence explaining what these functions calculate + +csinh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + Michael Kerrisk + Add introductory sentence explaining what these functions calculate + +csqrt.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + Michael Kerrisk + Simplify description of what these functions calculate + +ctan.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + Michael Kerrisk + Add introductory sentence explaining what these functions calculate + +ctanh.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + Michael Kerrisk + Add introductory sentence explaining what these functions calculate + +ctime.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +exec.3 + Michael Kerrisk + SYNOPSIS: Clarify calling signature for execl() and execlp() + Michael Kerrisk [Andreas Baak] + Correct prototype for execle() + Make the prototype shown into correct C. + +ftw.3 + Michael Kerrisk [Felix Sedlmeier] + ftw() and nftw() differ for the non-stat-able symlink case + The POSIX specification of ftw() says that an un-stat-able + symlink may yield either FTW_NS or FTW_SL. The specification + of nftw() does not carry this statement. + Michael Kerrisk + CONFORMING TO: add POSIX.1-2008 + Michael Kerrisk + Update POSIX version references in NOTES + +getcwd.3 + Jann Horn [Michael Kerrisk] + Note behavior for unreachable current working directory + Michael Kerrisk + Add ENOMEM error + +gethostbyname.3 + Michael Kerrisk [Jonny Grant] + Clarify that NO_ADDRESS and NO_DATA are synonyms + Michael Kerrisk + Add some detail for NO_DATA + Text consistent with POSIX and FreeBSD's gethostbyname() man page. + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +getnetent.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +get_nprocs_conf.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +getutent.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +glob.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +insque.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + +login.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +lseek64.3 + Michael Kerrisk + Clarify details with respect to 32-bit and 64-bit systems + +malloc.3 + Michael Kerrisk + Add ENOMEM error + +mbsnrtowcs.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +mbsrtowcs.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +mq_notify.3 + Michael Kerrisk + Add "C library/kernel ABI differences" subsection + +mq_open.3 + Michael Kerrisk [Fabien Pichot] + NOTES: explain differences from the underlying system call + The check for the slash at the start of a pathname is done in glibc + +openpty.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +perror.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +posix_memalign.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +printf.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + Walter Harms [Michael Kerrisk] + Simplify the example code + +qsort.3 + Michael Kerrisk [Rob Landley] + alphasort() and versionsort() are not suitable for 'compar' + In glibc 2.10, the prototypes of alphasort() and versionsort() + were changed so that the arguments switched from 'const void *' to + 'const struct dirent **', to match the POSIX.1-2008 specification + of alphasort(). As such, compiler warnings will result if + these functions are used as the arguments of qsort(). + + warning: passing argument 4 of 'qsort' from incompatible + pointer type + expected '__compar_fn_t' but argument is of type + 'int (*)(const struct dirent **, const struct dirent **)' + + Therefore, remove the ancient NOTES text suggesting that + alphasort() and versionsort() can be used as suitable + 'compar' arguments for qsort(). + +realpath.3 + Michael Kerrisk [Jon Grant] + Add ENOMEM error + +scandir.3 + Michael Kerrisk + glibc 2.10 changed the argument types for alphasort() and versionsort() + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +scanf.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +setnetgrent.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +significand.3 + Ma Shimiao + ATTRIBUTES: Note functions that are thread-safe + +strcasecmp.3 + Michael Kerrisk [Jonny Grant] + Clarify that strcasecmp() does a byte-wise comparison + Michael Kerrisk + CONFORMING TO: add POSIX.1-2008 + +unlocked_stdio.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +updwtmp.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +wcrtomb.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +wcsnrtombs.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +wcsrtombs.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +wordexp.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +wprintf.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +proc.5 + Michael Kerrisk + Describe "mnt_id" field of /proc/PID/fdinfo + Michael Kerrisk + Note that abstract sockets are included in /proc/net/unix + Michael Kerrisk + Update description /proc/sys/unix 'Type' field + The existing text was very crufty. UNIX domain sockets + support more than SOCK_STREAM for a _very_ long time now. + Michael Kerrisk + Add some detail to /proc/PID/timers + Michael Kerrisk [Vlastimil Babka] + Enhance discussion of /proc/PID/status 'VmSwap' field + +epoll.7 + Michael Kerrisk + SEE ALSO: add poll(2) and select(2) + +icmp.7 + YOSHIFUJI Hideaki/吉藤英明 + Document net.ipv4.ping_group_range knob + +nptl.7 + Michael Kerrisk + Add reference to timer_create(2) + + +==================== Changes in man-pages-4.00 ==================== + +Released: 2015-05-07, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Advait Dixi +Alain Kalker +Andi Kleen +Andreas Gruenbacher +Andreas Heiduk +Askar Safin +Brice Goglin +Cameron Norman +Carlos O'Donell +Chris Metcalf +Christophe Lohr +Christopher Head +Christoph Hellwig +David Wilcox +Denis Du +Egmont Koblinger +Filipe Brandenburger +Filipus Klutiero +Florian Weimer +Frédéric Maria +Gleb Fotengauer-Malinovskiy +Graham Shaw +Gregor Jasny +Guillem Jover +Guy Harris +Heinrich Schuchardt +Ian Pilcher +Jann Horn +Jason Newton +J. Bruce Fields +Jiri Pirko +Joachim Wuttke +Joern Heissler +Jonathan Nieder +Joonas Salo +Jussi Lehtola +Kirill A. Shutemov +KOSAKI Motohiro +Laurence Gonsalves +Magnus REFTEL +Michael Kerrisk +NeilBrown +Regid Ichira +Sam Varshavchik +Steinar H. Gunderson +Stéphane Aulery +Stephane Fillod +Tetsuo Handa +Thomas Hood +Urs Thuermann +Vasiliy Kulikov +Vegard Nossum +Weijie Yang +William Woodruff +Zeng Linggang + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +get_phys_pages.3 + William Woodruff + Document get_phys_pages() and get_avphys_pages() + +loop.4 + Urs Thuermann, Michael Kerrisk + New page documenting the loop device + +xattr.7 + Andreas Gruenbacher + Import attr(5) man page from the 'attr' project + After discussions with Andreas Gruenbacher, it makes sense to + move this page into man-pages, since it mostly relates to + kernel details. Since this is an overview page, + we'll move it to Section 7. + Michael Kerrisk + Rename page + "xattr" is a more meaningful name than "attr" (it resonates + with the names of the system calls), so as long as we are + moving the page to a new section, we'll change the name as well, + and retain an acl(5) link so that old references remain valid. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +mmap.2 + Michael Kerrisk [Andi Kleen] + Document MAP_HUGE_2MB, MAP_HUGE_1GB, and MAP_HUGE_SHIFT + +shmget.2 + Michael Kerrisk [Andi Kleen] + Document SHM_HUGE_2MB, SHM_HUGE_1GB, and SHM_HUGE_SHIFT + +resolver.3 + Michael Kerrisk [Jonathan Nieder] + Add descriptions of some other resolver functions + Add res_ninit(), res_nquery(), res_nsearch(), + and res_nquerydomain(), res_nmkquery(), res_nsend(). + +tty_ioctl.4 + Frédéric Maria [Stephane Fillod, Andreas Heiduk] + Document TIOCMIWAIT and TIOCGICOUNT + Michael Kerrisk + Document TIOCGEXCL + Michael Kerrisk + Document TIOGCPKT + Michael Kerrisk + Document TIOCSPTLCK + Michael Kerrisk + Document TIOCGPTLCK + + +New and changed links +--------------------- + +CMSG_DATA.3 + Michael Kerrisk + New link to cmsg(3) + +CMSG_LEN.3 + Michael Kerrisk + New link to cmsg(3) + +dprintf.3 + Michael Kerrisk + Convert to a link to printf.3 + +get_avphys_pages.3 + William Woodruff + New link to new get_phys_pages.3 page + +res_ninit.3 +res_nmkquery.3 +res_nquery.3 +res_nquerydomain.3 +res_nsearch.3 +res_nsend.3 + Michael Kerrisk + New links to resolver(3) man page + +loop-control.4 + Michael Kerrisk + New link to loop.4 + +attr.5 + Michael Kerrisk + New link to xattr(7) + + +Global changes +-------------- + +chown.2 +execve.2 +prctl.2 +truncate.2 +proc.5 +capabilities.7 +ld.so.8 + Michael Kerrisk + Tighter wording: 'mode bit' rather than 'permission bit' + For sticky, set-UID, and set-GID mode bits (as used in POSIX). + + +Changes to individual pages +--------------------------- + +add_key.2 +keyctl.2 +request_key.2 + Michael Kerrisk + SEE ALSO: add keyrings(7) + +add_key.2 +request_key.2 + Michael Kerrisk + SEE ALSO: add keyctl(3) + +epoll_ctl.2 + Michael Kerrisk + After EPOLLHUP, EOF will be seen only after all data has been consumed + +epoll_wait.2 + Michael Kerrisk + Clarify that signal mask treatment in epoll_pwait() is per-thread + s/sigprocmask()/pthread_sigmask()/ + +fcntl.2 + Michael Kerrisk [Vegard Nossum] + Note an F_SETSIG corner case + +get_mempolicy.2, set_mempolicy + Brice Goglin + Policy is per thread, not per process + +getxattr.2 +listxattr.2 +removexattr.2 +setxattr.2 +capabilities.7 + Michael Kerrisk + Adjust "attr(5)" references to "xattr(7)" + +ioctl.2 + Michael Kerrisk + SEE ALSO: add console_ioctl(2) and tty_ioctl(2) + +listxattr.2 +xattr.7 + Michael Kerrisk + Describe listxattr(2) E2BIG error and document it as a BUG + +mkdir.2 + Michael Kerrisk + Wording fixes + point reader at stat(2) for explanation of file mode + Michael Kerrisk [Andreas Grünbacher] + Further tweaks to text on S_ISVTX and 'mode' argument + +mknod.2 + Michael Kerrisk + Rewordings + point reader at stat(2) for details of mode bits + +mmap.2 + Michael Kerrisk + Remove text that implies that munmap() syncs MAP_SHARED mapping to file + The existing text in this page: + + MAP_SHARED Share this mapping. Updates to the mapping + are visible to other processes that map this + file, and are carried through to the underly‐ + ing file. The file may not actually be + updated until msync(2) or munmap() is called. + + implies that munmap() will sync the mapping to the underlying + file. POSIX doesn't require this, and some light reading of the + code and some light testing (fsync() after munmap() of a large + file) also indicates that Linux doesn't do this. + +msync.2 + Michael Kerrisk + Rework text of DESCRIPTION + Rewrite the text somewhat, for easier comprehension. + No (intentional) changes to factual content + +nfsservctl.2 + Michael Kerrisk [J. Bruce Fields] + Note that nfsservctl() was replaced by files in nfsd filesystem + +open.2 + Michael Kerrisk [Andreas Gruenbacher] + open() honors the S_ISVTX, S_ISUID, and S_ISGID bits in 'mode' + Michael Kerrisk + Tighten wording: use 'mode bit' rather than 'permission bit' + Michael Kerrisk [NeilBrown] + BUGS: O_CREAT | O_DIRECTORY succeeds if pathname does not exist + +poll.2 + Michael Kerrisk [Ian Pilcher] + Clarify that signal mask treatment in ppoll() is per-thread + s/sigprocmask()/pthread_sigmask()/ + Michael Kerrisk [Sam Varshavchik] + After POLLHUP, EOF will be seen only after all data has been consumed + Michael Kerrisk + Make it clearer which bits are ignored in 'events' + +prctl.2 + Michael Kerrisk [David Wilcox, Filipe Brandenburger] + Note that "parent" for purposes of PR_SET_DEATHSIG is a *thread* + See https://bugzilla.kernel.org/show_bug.cgi?id=43300 + +sendfile.2 + Michael Kerrisk [Jason Newton] + Note that sendfile does not support O_APPEND for 'out_fd' + See https://bugzilla.kernel.org/show_bug.cgi?id=82841 + Michael Kerrisk [Gregor Jasny] + RETURN VALUE: note the possibility of "short sends" + See https://bugzilla.kernel.org/show_bug.cgi?id=97491 + Michael Kerrisk [Askar Safin] + Clarify text on 'out_fd' and regular files in Linux 2.4 + See https://bugzilla.kernel.org/show_bug.cgi?id=86001 + +shutdown.2 + Michael Kerrisk [Stéphane Aulery] + BUGS: UNIX domain sockets now detect invalid 'how' values + Bug fixed in Linux 3.7. + See https://bugzilla.kernel.org/show_bug.cgi?id=47111 + +sigaction.2 + Michael Kerrisk + Refer the reader to fcntl(2) F_SETSIG for further details on si_fd + +stat.2 + Jann Horn + Add note about stat() being racy + Andreas Gruenbacher + Improve description of some mode constants + Michael Kerrisk [Andreas Grünbacher] + Remove excessive leading zeros on some constants + Michael Kerrisk + Add text on POSIX terms "file mode bits" and "file permission bits" + Recent changes to various pages employ this distinction. + Michael Kerrisk + Tighten wording: use 'mode bit' rather than 'permission bit' + According to POSIX, the 9 UGO*RWX bits are permissions, and + 'mode' is used to refer to collectively to those bits plus sticky, + set-UID, and set_GID bits. + +syslog.2 + Michael Kerrisk + SEE ALSO: add dmesg(1) + +umask.2 +open.2 +mknod.2 +mkdir.2 + Andreas Gruenbacher + Explain what default ACLs do + Explain the effect that default ACLs have (instead of the umask) + in umask.2. Mention that default ACLs can have an affect in + open.2, mknod.2, and mkdir.2. + +unshare.2 + Michael Kerrisk [Florian Weimer] + Give the reader a hint that unshare() works on processes or threads + See https://bugzilla.kernel.org/show_bug.cgi?id=59281 + +atexit.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +bsearch.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +cmsg.3 + Michael Kerrisk [Christopher Head] + Fix error in SCM_RIGHTS code sample + Remove erroneous second initialization of msg.msg_controllen + in the example code for SCM_RIGHTS. + See https://bugzilla.kernel.org/show_bug.cgi?id=15952 + +CPU_SET.3 + Chris Metcalf + Clarify language about "available" cpus + The CPU_SET.3 man page uses the adjective "available" when + explaining what the argument to CPU_SET() means. This is + confusing, since "available" isn't well-defined. The kernel + has a set of adjectives (possible, present, online, and active) + that qualify cpus, but normally none of these are what the + cpu_set_t bit index means: it's just "which cpu", using the + kernel's internal numbering system, even if that cpu isn't + possible or present. + + This change removes the word "available" and adds a sentence + warning that cpu sets may not be contiguous due to dynamic + cpu hotplug, etc. + +err.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +ftw.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +gethostbyname.3 + Carlos O'Donell + NSS plugins searched first + Carlos O'Donell + "order" is obsolete + +gethostid.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +getmntent.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +get_nprocs_conf.3 + Michael Kerrisk + Use exit() rather than return in main() + +getopt.3 + Michael Kerrisk [Guy Harris] + Remove crufty BUGS section + See https://bugzilla.kernel.org/show_bug.cgi?id=90261 + +iconv_close.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +inet_ntop.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +longjmp.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +lsearch.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +mcheck.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +on_exit.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +printf.3 + Michael Kerrisk [Egmont Koblinger] + Merge dprintf() and vdprintf() discussion into this page + Michael Kerrisk + SEE ALSO: add puts(3) + Michael Kerrisk + Move return value discussion to proper RETURN VALUE section + +putpwent.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +qsort.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +regex.3 + Michael Kerrisk [Laurence Gonsalves] + Fix error in description of 'cflags' + 'cflags' is a bit mask of *zero* (not one) or more flags. + +resolver.3 + Stéphane Aulery + Add info about RES_INSECURE1 and RES_INSECURE2 option in debug mode + +scanf.3 + Joern Heissler + Improve description of %n specifier + +setjmp.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +setlocale.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +setlogmask.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +sleep.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +strsignal.3 + Zeng Linggang + ATTRIBUTES: Note function that isn't thread-safe + +sysconf.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +undocumented.3 + William Woodruff + Remove documented functions + +tty_ioctl.4 + Michael Kerrisk [Denis Du] + Fix error in code example + +proc.5 + Michael Kerrisk [Cameron Norman, Vasiliy Kulikov] + Document /proc mount options + Document the 'hidepid' and 'gid' mount options that were added in + Linux 3.3. See https://bugzilla.kernel.org/show_bug.cgi?id=90641 + Based on text by Vasiliy Kulikov in + Documentation/filesystems/proc.txt. + Michael Kerrisk [Kirill A. Shutemov] + Improve description of /proc/PID/status + Guillem Jover + Document /proc/PID/exe behaviour on unlinked pathnames + Michael Kerrisk [Weijie Yang] + Document /proc/PID/status VmPMD + +resolv.conf.5 + Stéphane Aulery [Thomas Hood] + Document use-vc option added to glibc 2.14 + Fix Ubuntu bug #1110781: + https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/1110781 + Stéphane Aulery [Thomas Hood] + Document RES_SNGLKUPREOP + Fix Ubuntu bug #1110781: + https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/1110781 + +tzfile.5 + Sam Varshavchik + Add various details on version 2 format + +aio.7 + Michael Kerrisk + Add details and update URL for OLS 2003 paper on AIO + +bootparam.7 + Michael Kerrisk [Alain Kalker] + Update discussion of 'debug' option + See https://bugzilla.kernel.org/show_bug.cgi?id=97161 + Michael Kerrisk + Summary of multiple changes: remove cruft from this page. + Much of the detail on hardware specifics in this page dates + from the 20th century. (The last major update to this page was in + man-pages-1.14!) It's hugely out of date now (many of these + devices disappeared from the kernel years ago.) So, I've taken + a large scythe to the page to remove anything that looks + seriously dated. In the process, the page has shrunk to less + than 50% of its previous size. + Michael Kerrisk + Remove "buff=" details + This seems to have gone away in Linux 2.2. + Michael Kerrisk + Remove crufty "Mouse drivers" options + Michael Kerrisk + Remove crufty "General non-device-specific boot arguments" options + Michael Kerrisk + Remove crufty "Hard disks" options + Michael Kerrisk + Remove crufty "mem=" details + Michael Kerrisk + Remove crufty details on IBM MCA bus devices + Michael Kerrisk + Remove 'swap=" details + This seems to have gone away in Linux 2.2, + Michael Kerrisk + Remove crufty floppy disk driver options + In the specific case of floppy drives: the drivers still + exist, but it's been a while since most of saw these devices + in the wild. So, just refer the reader to the kernel source + file for details. (The detail in this man page was after all + originally drawn from that file.) + Remove crufty "ISDN drivers" options + Michael Kerrisk + Remove crufty "line printer driver" options + Michael Kerrisk + Remove crufty "Serial port drivers" options + Michael Kerrisk + Remove crufty reference to CONFIG_BUGi386 + That option disappeared in Linux 2.4. + Michael Kerrisk + Remove crufty text + "bootsetups array" dates from Linux 2.0. + Michael Kerrisk + Remove crufty "Video hardware" options + Michael Kerrisk + Remove crufty SCSI device driver options + +fanotify.7 + Michael Kerrisk [Heinrich Schuchardt] + Since Linux 3.19, fallocate(2) generates FAN_MODIFY events + +inotify.7 + Michael Kerrisk [Heinrich Schuchardt] + Since Linux 3.19, fallocate(2) generates IN_MODIFY events + +ip.7 + Michael Kerrisk + Explain how IP_ADD_MEMBERSHIP determines its argument type + Michael Kerrisk [Jiri Pirko, Magnus REFTEL] + Clarify details of the IP_MULTICAST_IF socket option + Michael Kerrisk [Advait Dixi] + Remove dubious text that says that SO_PRIORITY sets IP TOS + See https://bugzilla.kernel.org/show_bug.cgi?id=35852 + Michael Kerrisk + Relocate misplaced text describing ENOPROTOOPT error + +packet.7 + Graham Shaw + Add sll_protocol to list of required fields for outbound packets + +pthreads.7 + Michael Kerrisk [KOSAKI Motohiro] + Using thread IDs whose lifetime has expired gives undefined behavior + See https://bugzilla.kernel.org/show_bug.cgi?id=53061 + +raw.7 + Michael Kerrisk [Tetsuo Handa] + For incoming datagrams, sin_port is set to zero + Michael Kerrisk + Mention sendto(), recvfrom(), and so on when discussing address format + This gives the reader a little context for the following + discussion of 'sin_port'. + Michael Kerrisk + Remove crufty reference to + Michael Kerrisk + Replace reference to RFC 1700 with pointer to IANA protocol number list + +signal.7 + Michael Kerrisk [Steinar H. Gunderson] + Clarify that I/O operations on disks are not interrupted by signals + See https://bugzilla.kernel.org/show_bug.cgi?id=97721 + +unix.7 + Michael Kerrisk [Christophe Lohr] + Remove mention of UNIX_PATH_MAX + This kernel constant is not exposed to user space. + Michael Kerrisk + Note the 108 bytes for sun_path is how things are done on Linux + And refer the reader to NOTES for discussion of portability. + +xattr.7 + Michael Kerrisk + Document EA limits for Btrfs + Michael Kerrisk + Document VFS-imposed limits on EAs + VFS imposes a 255-byte limit on EA names, and a 64kB limit on + EA values. + Michael Kerrisk + The ext[234] block limitation applies to sum of all EAs + It is not a per-EA limit. + Michael Kerrisk + Clarify permissions required to work with 'user' EAs + Michael Kerrisk + ext2 and ext3 no longer need mounting with 'user_xattr' for user EAs + Michael Kerrisk + Add various relevant pages to SEE ALSO + Michael Kerrisk + Add CONFORMING TO section + Michael Kerrisk + Modify headings to man-pages norms + Michael Kerrisk + Btrfs also supports extended attributes + Michael Kerrisk + File capabilities are implemented using *security* attributes + Not *system* attributes + Michael Kerrisk + Describe limit on EA values for JFS, XFS, and Reiserfs + Michael Kerrisk + Explicitly mention some of the xattr system calls in DESCRIPTION + Naming the system calls helps to orient the reader + +nscd.8 + Michael Kerrisk + Add mention of 'services' and 'netgroup' databases + This makes the page consistent with nscd.conf(5). + + +==================== Changes in man-pages-4.01 ==================== + +Released: 2015-07-23, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alexei Starovoitov +Andries E. Brouwer +Arjun Shankar +Ashish Sangwan +Ben Woodard +Carlos O'Donell +Christoph Thompson +Cortland Setlow +Daniel Borkmann +David Leppik +Dilyan Palauzov +Doug Klima +Eric B Munson +Florian Weimer +Hack NDo +Jann Horn +Jens Axboe +Jian Wen +Joerg Roedel +Julian Orth +Kees Cook +Laszlo Ersek +Marko Myllynen +Mehdi Aqadjani Memar +Michael Kerrisk +Michal Hocko +Mike Frysinger +Mike Hayward +Miklos Szeredi +Namhyung Kim +Namjae Jeon +Nathan Lynch +NeilBrown +Pádraig Brady +Pavel Machek +Peter Hurley +Sam Varshavchik +Scot Doyle +Stephan Mueller +Tobias Stoeckmann +Tulio Magno Quites Machado Filho +Uwe Kleine-König +Vegard Nossum +Ville Skyttä +Vince Weaver +Zeng Linggang +文剑 + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +bpf.2 + Alexei Starovoitov, Michael Kerrisk [Daniel Borkmann] + New page documenting bpf(2) + +__ppc_get_timebase.3 + Tulio Magno Quites Machado Filho + New page documenting __ppc_get_timebase() and __ppc_get_timebase_freq() + Glibc 2.16 was released with a new function for the Power + architecture that can read its Time Base Register. + Glibc 2.17 adds a function to read the frequency at which the Time + Base Register of Power processors is updated. + +queue.3 + Michael Kerrisk [David Leppik, Doug Klima] + Reimport from latest FreeBSD page + Long ago, Doug Klima noted that many macros were not + documented in the queue(3) page. Fix by reimporting from + latest [1] FreeBSD man page. + + [1] Revision 263142, Modified Fri Mar 14 03:07:51 2014 UTC + + This also fixes https://sourceware.org/bugzilla/show_bug.cgi?id=1506 + + This time, I'll learn from past mistakes and not convert + from 'mdoc' to 'man' macros. + Michael Kerrisk + Use subsections in DESCRIPTION + Michael Kerrisk + Remove SEE ALSO reference to nonexistent tree(3) + Michael Kerrisk + Use real hyphens in code samples + Michael Kerrisk + Comment out text for functions not in glibc + Michael Kerrisk + Replace HISTORY with CONFORMING TO + + +Newly documented interfaces in existing pages +--------------------------------------------- + +rename.2 + Michael Kerrisk [Miklos Szeredi] + Document RENAME_WHITEOUT + Heavily based on text by Miklos Szeredi. + + +New and changed links +--------------------- + +__ppc_get_timebase_freq.3 + Tulio Magno Quites Machado Filho + New link to new __ppc_get_timebase(3) page + +LIST_EMPTY.3 +LIST_FIRST.3 +LIST_FOREACH.3 +LIST_HEAD_INITIALIZER.3 +LIST_INSERT_BEFORE.3 +LIST_NEXT.3 +SLIST_EMPTY.3 +SLIST_ENTRY.3 +SLIST_FIRST.3 +SLIST_FOREACH.3 +SLIST_HEAD.3 +SLIST_HEAD_INITIALIZER.3 +SLIST_INIT.3 +SLIST_INSERT_AFTER.3 +SLIST_INSERT_HEAD.3 +SLIST_NEXT.3 +SLIST_REMOVE.3 +SLIST_REMOVE_HEAD.3 +STAILQ_CONCAT.3 +STAILQ_EMPTY.3 +STAILQ_ENTRY.3 +STAILQ_FIRST.3 +STAILQ_FOREACH.3 +STAILQ_HEAD.3 +STAILQ_HEAD_INITIALIZER.3 +STAILQ_INIT.3 +STAILQ_INSERT_AFTER.3 +STAILQ_INSERT_HEAD.3 +STAILQ_INSERT_TAIL.3 +STAILQ_NEXT.3 +STAILQ_REMOVE.3 +STAILQ_REMOVE_HEAD.3 +TAILQ_CONCAT.3 +TAILQ_EMPTY.3 +TAILQ_FIRST.3 +TAILQ_FOREACH.3 +TAILQ_FOREACH_REVERSE.3 +TAILQ_HEAD_INITIALIZER.3 +TAILQ_INSERT_BEFORE.3 +TAILQ_LAST.3 +TAILQ_NEXT.3 +TAILQ_PREV.3 +TAILQ_SWAP.3 + Michael Kerrisk + New links to queue.3 + + +Global changes +-------------- + +Various pages + Michael Kerrisk [Andries E. Brouwer] + Remove "ABI" from "C library/kernel ABI differences" subheadings + The "ABI" doesn't really convey anything significant in + the title. These subsections are about describing differences + between the kernel and (g)libc interfaces. + + +Changes to individual pages +--------------------------- + +intro.1 + Michael Kerrisk [Andries E. Brouwer] + Drop intro paragraph on '$?' shell variable + As Andries notes, this piece of text is rather out of place in + a page that was intended to provide a tutorial introduction for + beginners logging in on a Linux system. + +locale.1 + Marko Myllynen + A minor output format clarification + A minor clarification for the locale output format which was + brought up at + https://sourceware.org/bugzilla/show_bug.cgi?id=18516. + + For reference, see + https://sourceware.org/bugzilla/show_bug.cgi?id=18516 + http://pubs.opengroup.org/onlinepubs/9699919799/utilities/locale.html + + Add CONFORMING TO section + +capget.2 + Julian Orth + Clarify that hdrp->pid==0 is equivalent gettid() not getpid() + +chroot.2 + Jann Horn + chroot() is not intended for security; document attack + It is unfortunate that this discourages this use of chroot(2) + without pointing out alternative solutions - for example, + OpenSSH and vsftpd both still rely on chroot(2) for security. + + Bind mounts should theoretically be usable as a replacement, but + currently, they have a similar problem (CVE-2015-2925) that hasn't + been fixed in ~6 months, so I'd rather not add it to the manpage + as a solution before a fix lands. + +clock_getres.2 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +eventfd.2 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +execve.2 + Michael Kerrisk + Elaborate on envp/argv as NULL behavior + +_exit.2 + Michael Kerrisk + Open stdio frames are not flushed, temporary files are deleted + Many years ago, text was added to the page saying that it is + implementation-dependent whether stdio streams are flushed and + whether temporary are removed. In part, this change appears to + be because POSIX.1-2001 added text related to this point. + However, that seems to have been an error in POSIX, and the + text was subsequently removed for POSIX.1-2008. See + https://collaboration.opengroup.org/austin/interps/documents/9984/AI-085.txt + Austin Group Interpretation reference 1003.1-2001 #085 + +fallocate.2 + Namjae Jeon [Michael Kerrisk] + Document FALLOC_FL_INSERT_RANGE + Michael Kerrisk + Since Linux 4.2, ext4 supports FALLOC_FL_INSERT_RANGE + +fcntl.2 + Michael Kerrisk + OFD locks are proposed for inclusion in the next POSIX revision + +getrlimit.2 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +getrusage.2 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +gettid.2 + Michael Kerrisk + Note that for a thread group leader, gettid() == getpid() + +iopl.2 + Michael Kerrisk + Remove some historical libc5 and glibc 1 details + These details are ancient, and long ago ceased to be relevant. + +ioprio_set.2 + Michael Kerrisk [Jens Axboe] + Document meaning of ioprio==0 + +mlock.2 + Michael Kerrisk [Mehdi Aqadjani Memar] + Document another ENOMEM error case + ENOMEM can occur if locking/unlocking in the middle of a region + would increase the number of VMAs beyond the system limit (64k). + +mmap.2 + Michal Hocko [Eric B Munson] + Clarify MAP_POPULATE + David Rientjes has noticed that MAP_POPULATE wording might promise + much more than the kernel actually provides and intends to provide. + The primary usage of the flag is to pre-fault the range. There is + no guarantee that no major faults will happen later on. The pages + might have been reclaimed by the time the process tries to access + them. + Michal Hocko [Eric B Munson] + Clarify MAP_LOCKED semantics + MAP_LOCKED had a subtly different semantic from mmap(2)+mlock(2) + since it has been introduced. + mlock(2) fails if the memory range cannot get populated to + guarantee that no future major faults will happen on the range. + mmap(MAP_LOCKED) on the other hand silently succeeds even if + the range was populated only partially. + + Fixing this subtle difference in the kernel is rather awkward + because the memory population happens after mm locks have been + dropped and so the cleanup before returning failure (munlock) + could operate on something else than the originally mapped area. + + E.g. speculative userspace page fault handler catching SEGV and + doing mmap(fault_addr, MAP_FIXED|MAP_LOCKED) might discard portion + of a racing mmap and lead to lost data. Although it is not clear + whether such a usage would be valid, mmap page doesn't explicitly + describe requirements for threaded applications so we cannot + exclude this possibility. + + This patch makes the semantic of MAP_LOCKED explicit and suggests + using mmap + mlock as the only way to guarantee no later major + page faults. + Michael Kerrisk + ERRORS: point out that ENOMEM can occur even for munmap() + +mprotect.2 + Michael Kerrisk + Note ENOMEM error that can occur when we reach limit on maximum VMAs + +open.2 +read.2 +write.2 + Michael Kerrisk [Mike Hayward] + Clarify that O_NONBLOCK is a no-op for regular files and block devices + +perf_event_open.2 + Vince Weaver [Joerg Roedel] + Exclude_host/exclude_guest clarification + This patch relates to the exclude_host and exclude_guest bits added + by the following commit: + + exclude_host, exclude_guest; Linux 3.2 + commit a240f76165e6255384d4bdb8139895fac7988799 + Author: Joerg Roedel + Date: Wed Oct 5 14:01:16 2011 +0200 + + perf, core: Introduce attrs to count in either host or guest mode + + The updated manpage text clarifies that the "exclude_host" and + "exclude_guest" perf_event_open() attr bits only apply in the + context of a KVM environment and are currently x86 only. + Vince Weaver + Document PERF_SAMPLE_REGS_INTR + This patch relates to the addition of PERF_SAMPLE_REGS_INTR + support added in the following commit: + + perf_sample_regs_intr; Linux 3.19 + commit 60e2364e60e86e81bc6377f49779779e6120977f + Author: Stephane Eranian + + perf: Add ability to sample machine state on interrupt + + The primary difference between PERF_SAMPLE_REGS_INTR and the + existing PERF_SAMPLE_REGS_USER is that the new support will + return kernel register values. Also if precise_ip is + set higher than 0 then the PEBS register state will be returned + rather than the saved interrupt state. + + This patch incorporates feedback from Stephane Eranian and + Andi Kleen. + +prctl.2 +seccomp.2 + Michael Kerrisk + Clarify that SECCOMP_SET_MODE_STRICT disallows exit_group(2) + These days, glibc implements _exit() as a wrapper around + exit_group(2). (When seccomp was originally introduced, this was + not the case.) Give the reader a clue that, despite what glibc is + doing, what SECCOMP_SET_MODE_STRICT permits is the true _exit(2) + system call, and not exit_group(2). + +pread.2 +read.2 +readv.2 +sendfile.2 +write.2 + Michael Kerrisk + Clarify that Linux limits transfers to a maximum of 0x7ffff000 bytes + See https://bugs.debian.org/629994 and + https://bugs.debian.org/630029. + +pread.2 + Michael Kerrisk + Rewrite RETURN VALUE section + (Also drop the text on pwrite() returning zero; that seems bogus.) + +ptrace.2 + Michael Kerrisk [Vegard Nossum] + PTRACE_O_TRACEEXIT clarification + +readv.2 + Michael Kerrisk + Remove BUGS heading + The text on mixing I/O syscalls and stdio is a general point + of behavior. It's not a bug as such. + +recv.2 +send.2 + Michael Kerrisk + Explain some subtleties of MSG_DONTWAIT versus O_NONBLOCK + +rename.2 + Michael Kerrisk + Michael Kerrisk + Note that RENAME_NOREPLACE can't be employed with RENAME_EXCHANGE + +sched_setaffinity.2 + Michael Kerrisk + Add an example program + Michael Kerrisk [Florian Weimer] + Explain how to deal with 1024-CPU limitation of glibc's cpu_set_t type + Michael Kerrisk + Mention the use of the 'isolcpus' kernel boot option + +sched_setattr.2 + Julian Orth + Remove a const attribute + The attr argument of sched_setattr was documented as const but the + kernel will modify the size field of this struct if it contains an + invalid value. See the documentation of the size field for details. + +seccomp.2 + Michael Kerrisk + SEE ALSO: add bpf(2) + +send.2 + Michael Kerrisk + Expand on subtleties of MSG_NOSIGNAL versus ignoring SIGPIPE + +sigaltstack.2 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +socket.2 + Stephan Mueller + Update documentation reference for AF_ALG + +truncate.2 + Michael Kerrisk + ERRORS: ftruncate() can fail if the file descriptor is not writable + +utimensat.2 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + After research, We think utimensat() and futimens() are thread-safe. + But, there are not markings of utimensat() and futimens() in glibc + document. + +clearenv.3 + Zeng Linggang + ATTRIBUTES: Note function that is not thread-safe + +dl_iterate_phdr.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +error.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +fexecve.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +fpurge.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +fread.3 + Andries E. Brouwer + Clarify terminology + In the "RETURN VALUE" section the word item is in italics + as if it were one of the function parameters. But the word + "item" occurs here for the first time, earlier the text + uses "element". [Patch improves this.] + +fts.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +getaddrinfo.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +getaddrinfo_a.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +getauxval.3 + Michael Kerrisk + File capabilities also trigger AT_SECURE + Michael Kerrisk + (Briefly) document AT_HWCAP2 + +getgrent_r.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +gethostbyname.3 + Michael Kerrisk [Laszlo Ersek] + Remove mention of IPv6 addresses, which are not supported + As reported by Laszlo Ersek: + + gethostbyname(3) fails to resolve the IPv6 address "::1", + but the manual page says: "If name is an IPv4 or IPv6 address, + no lookup is performed and gethostbyname() simply copies name + into the h_name field [...]". + + Debian bug report: + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=455762 + + glibc bug report: + http://sourceware.org/bugzilla/show_bug.cgi?id=5479 + + SUSv3 link for gethostbyname(3): + http://www.opengroup.org/onlinepubs/000095399/functions/gethostbyname.html + + It seems that the glibc behavior is conformant, and the manual + page is in error. + +getifaddrs.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +getnameinfo.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +getnetent_r.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +getprotoent.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +getprotoent_r.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +getpw.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +getpwent_r.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +getrpcent.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +getrpcent_r.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +getrpcport.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +getservent.3 + Zeng Linggang + ATTRIBUTES: Note functions that aren't thread-safe + +getservent_r.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +gsignal.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +key_setsecret.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +malloc_get_state.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +malloc_info.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +malloc_stats.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +malloc_trim.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +MB_LEN_MAX.3 + Michael Kerrisk + Clarify meaning of MB_LEN_MAX + Michael Kerrisk [Pádraig Brady] + MB_LEN_MAX is 16 in modern glibc versions + +memcpy.3 + Michael Kerrisk + NOTES: describe the glibc 2.13 changes that revealed buggy applications + Adding a note on this point seems worthwhile as a way of + emphasizing the point that the buffers must not overlap. + +mq_notify.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +perror.3 + Michael Kerrisk + Some wording improvements and clarifications + +profil.3 + Zeng Linggang + ATTRIBUTES: Note function that is not thread-safe + +psignal.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +pthread_attr_init.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + Michael Kerrisk + Use "%zd" for printing size_t in example code + +pthread_attr_setaffinity_np.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +pthread_cancel.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +pthread_cleanup_push.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +pthread_create.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +pthread_detach.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +pthread_getattr_np.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +pthread_join.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +pthread_setname_np.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +pthread_tryjoin_np.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +putgrent.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +rcmd.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +resolver.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +rpc.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +rpmatch.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +sem_close.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +sem_open.3 + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +setaliasent.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +setlocale.3 + Marko Myllynen + Update CONFORMING TO + http://pubs.opengroup.org/onlinepubs/9699919799/functions/setlocale.html + +setlocale.3 + Marko Myllynen + Tweak C/POSIX locale portability description + As discussed earlier, the current description might be a little + bit too stringent, let's avoid the issue by describing the + portability aspect on a slightly higher level. + + References: + + http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html + http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html + http://pubs.opengroup.org/onlinepubs/9699919799/functions/setlocale.html + +shm_open.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +strfmon.3 + Marko Myllynen + Document strfmon_l(3) + Describe strfmon_l(3). + + http://pubs.opengroup.org/onlinepubs/9699919799/functions/strfmon.html + Marko Myllynen + Fix CONFORMING TO + AFAICS strfmon(3) is now defined in POSIX and the glibc + implementation is as specified there. + + http://pubs.opengroup.org/onlinepubs/9699919799/functions/strfmon.html + Marko Myllynen + Rewrite the example + I think the example is more accurate when we use the exact + locale names and also the Euro sign where appropriate. + +xcrypt.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +xdr.3 + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +console_codes.4 + Scot Doyle [Pavel Machek, Michael Kerrisk] + Add CSI sequence for cursor blink interval + Add a Console Private CSI sequence to specify the current + console's cursor blink interval. The interval is specified + as a number of milliseconds until the next cursor display + state toggle, from 50 to 65535. + +null.4 + Michael Kerrisk + Note that reads from /dev/zero are interruptible since Linux 2.6.31 + +core.5 + Michael Kerrisk + Mention 'coredump_filter' boot option + +host.conf.5 + Michael Kerrisk + Wording fix: s/resolv+/the resolver library/ + The term "resolv+" seems to be historical cruft. + +hosts.equiv.5 + Carlos O'Donell + Fix format, clarify IdM needs, and provide examples. + In some recent work with a Red Hat customer I had the opportunity + to discuss the fine nuances of the ruserok() function and related + API which are used to implement rlogin and rsh. + + It came to my attention after working with QE on some automated + internal testing that there were no good examples in the hosts.equiv + manual page showing how the format was supposed to work for this + file and for ~/.rhosts, worse the "format" line showed that there + should be spaces between arguments when that would clearly lead + to incorrect behaviour. In addition some things that the format + allows you to write are just wrong like "-host -user" which makes + no sense since the host is already rejected, and should be written + as "host -user" instead. I added notes in the example to make it + clear that "-host -user" is invalid. + + I fixed three things: + + (a) The format line. + - Either +, or [-]hostname, or +@netgrp or -@netgrp. + - Either +, or [-]username, or +@netgrp or -@netgrp. + - You must specify something in the hostname portion so remove + optional brackets. + + (b) Clarify language around credentials + - If the host is not trusted you must provide credentials to + the login system and that could be anything really and it + depends on your configuration e.g. PAM or whatever IdM you have. + + (c) Provide real-world examples + - Provide several real world examples and some corner case + examples for how you would write something. Hopefully others + can add examples as they see fit. + Michael Kerrisk [Carlos O'Donell, Arjun Shankar] + Improve explanation in EXAMPLE + +locale.5 + Marko Myllynen + Document map to_inpunct, map to_outpunct + See e.g. fa_IR for reference. + Marko Myllynen + Document class in LC_CTYPE + See e.g. the locale zh_CN and + + http://en.cppreference.com/w/cpp/string/wide/towctrans + http://en.cppreference.com/w/cpp/string/wide/wctrans + Marko Myllynen + Add iconv(1) reference + Marko Myllynen + Document character transliteration + See e.g. da_DK for reference. + + (Not sure should we actually provide an example here?) + Marko Myllynen + Document era keywords + This patch completes the LC_TIME section - since these era + keywords are so tightly coupled, I'm providing them as a + single patch. + + Based on + http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap07.html + http://www.open-std.org/jtc1/SC22/WG20/docs/n972-14652ft.pdf + Marko Myllynen + Document default_missing + Marko Myllynen + Document outdigit and alt_digits + See e.g. fa_IR for reference. + Marko Myllynen + Refer to locale(7) more prominently + It's probably a good idea to refer to locale(7) so that a reader + can check what a category is about before describing them in + detail. + Marko Myllynen + Document charclass and charconv + See e.g. the locales ja_JP and ko_KR and + + http://en.cppreference.com/w/cpp/string/wide/towctrans + http://en.cppreference.com/w/cpp/string/wide/wctrans + Marko Myllynen + Copy is not exclusive in LC_CTYPE and LC_COLLATE + See e.g. da_DK for reference. + Marko Myllynen + Remove the FIXME for timezone + The timezone of LC_TIME is not in POSIX, only 6 (out of ~300) + glibc locales define it, the glibc code comment below from + glibc.git/programs/ld-time.c seems to suggest it's not a good + idea, and there's been a proposal in upstream [1] to remove the + existing timezone definitions from glibc locales so I think + it's actually better to leave this one undocumented: + + /* XXX We don't perform any tests on the timezone value since this is + simply useless, stupid $&$!@... */ + + 1) https://sourceware.org/ml/libc-alpha/2015-06/msg00098.html + + Move the remaining LC_COLLATE FIXMEs together while at it. + Marko Myllynen + Fix country_isbn format + Both plain numbers and Unicode code points are used in + glibc locales but checking the code reveals that country_isbn + is handled like the rest of its category expect for country_num + which was clarified earlier. + Marko Myllynen + Sort according to the standard + Sort the options so that those defined in POSIX are listed first, + then followed by those defined in ISO/IEC TR 14652 in the order + of common convention in many widely used glibc locales. + + Actual descriptions are unchanged. + + http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html + Marko Myllynen + Refer to strftime(3) where appropriate + The relationship between the locale time format syntax + and strftime() cannot be considered as obvious. + Marko Myllynen + Document map "totitle" + See e.g. locales/i18n for reference. + Michael Kerrisk [Marko Myllynen] + Remove BUGS section saying man page is not complete + To some degree, this is true of many pages. And anyway, this + page is much better after recent work by Marko. + +proc.5 + Michael Kerrisk + List /proc/vmstat fields + Michael Kerrisk + Tweak /proc/vmstat text + Michael Kerrisk + Add /proc/crypto entry with a pointer to further information + Michael Kerrisk [Kees Cook] + Document /proc/sys/kernel/sysctl_writes_strict + Based on text in Documentation/sysctl/kernel.txt. + Michael Kerrisk + Move misordered /proc/[pid]/timers entry + Michael Kerrisk + Refer to bpf(2) for explanation of /proc/sys/net/core/bpf_jit_enable + +repertoiremap.5 + Marko Myllynen + Symbolic names AKA mnemonics + A long time ago in glibc, repertoire maps were used (but they + were removed already in 2000), those mapping files were named + as mnemonics, so "mnemonic" is a term that would almost + certainly come up if somebody studies glibc side (perhaps even + the related standards like ISO 9945 [which I don't have access + to]) so I thought it's worth to mention to term in the man page + to make sure we're talking about the same thing, otherwise + someone might wonder is that something different or not. + + IOW, symbolic names and mnemonics are often used interchangeably, + let's mention the other often used term in the page, too. + +capabilities.7 + Michael Kerrisk + CAP_SYS_ADMIN allows calling bpf(2) + +locale.7 + Marko Myllynen + LC_CTYPE determines transliteration rules on glibc systems + +packet.7 + 文剑 [Cortland Setlow] + Fix description of binding a packet socket to an interface + +pty.7 + NeilBrown [Peter Hurley] + Clarify asynchronous nature of PTY I/O + A PTY is not like a pipe - there may be delayed between data + being written at one end and it being available at the other. + + This became particularly apparent after + commit f95499c3030f + ("n_tty: Don't wait for buffer work in read() loop") + in Linux 3.12 + + See also the mail thread at https://lkml.org/lkml/2015/5/1/35 + Date Mon, 04 May 2015 12:32:04 -0400 + From Peter Hurley <> + Subject Re: [PATCH bisected regression] input_available_p() + sometimes says 'no' when it should say 'yes' + +rtld-audit.7 + Ben Woodard + Use correct printf() specifier for pointer types + In the example code you used %x rather than %p in the example + code for an audit library. The problem is that it truncates the + pointers on 64b platforms. So you get something like: + + la_symbind64(): symname = strrchr sym->st_value = 0x7f4b8a3f8960 + ndx = 222 flags = 0x0 refcook = 8b53e5c8 defcook = 8b537e30 + + rather than: + + la_symbind64(): symname = fclose sym->st_value = 0x7fa452dd49b0 + ndx = 1135 flags = 0x0 refcook = 0x7fa453f395c8 defcook = 0x7fa453f32e30 + + This has bitten me a handful of times when playing around with + audit test libraries to investigate its behavior. + +sched.7 + Michael Kerrisk + Remove ancient, wildly optimistic prediction about future of RT patches + It seems the patches were not merged by 2.6.30... + +socket.7 + Michael Kerrisk + SEE ALSO: add bpf(2) + +vdso.7 + Nathan Lynch [Mike Frysinger] + Update for ARM + The 32-bit ARM architecture in Linux has gained a vDSO as of the + 4.1 release. (I was the primary author.) + + Document the symbols exported by the ARM VDSO. + + Accepted kernel submission: + http://lists.infradead.org/pipermail/linux-arm-kernel/2015-March/332573.html + + +==================== Changes in man-pages-4.02 ==================== + +Released: 2015-08-08, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Carlos O'Donell +Daniel Borkmann +David Rientjes +Dilyan Palauzov +Gabriel F. T. Gomes +Gleb Fotengauer-Malinovskiy +Goswin von Brederlow +Heinrich Schuchardt +Jonathan David Amery +Michael Kerrisk +Mike Frysinger +Mike Kravetz +Nicholas Miell +Nikola Forró +Sam Varshavchik +Yaarit +Zeng Linggang + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +dladdr.3 + Michael Kerrisk + New page documenting dladdr() and dladdr1() + Relocate/rewrite dladdr() text formerly contained in dlopen(3). + + Add documentation of dladdr1(). + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + +dlerror.3 + Michael Kerrisk + Migrate dlerror(3) to new separate man page + Michael Kerrisk + Note that the returned message may be in a statically allocated buffer + Michael Kerrisk + Note that the returned string does not include a trailing newline + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +dlinfo.3 + Michael Kerrisk + New page describing dlinfo(3) + Zeng Linggang + ATTRIBUTES: Note function that is thread-safe + +dlopen.3 + Michael Kerrisk + This page was substantially rewritten and enhanced. Notably: + * the dladdr(), dlsym, dlvsym(), and dlerror() content were moved + to separate new pages; + * documentation for dlmopen was added; + * and other changes as noted below. + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + Michael Kerrisk + Move atexit() discussion under "Initialization and Finalization" + Michael Kerrisk + Move discussion of _init() and _fini() to NOTES + Michael Kerrisk + Rework the discussion of initialization and finalization functions + Deemphasize the obsolete _init/_fini and give more prominence + to gcc constructors/destructors. + Michael Kerrisk + dlclose() will unload the object when all references have been released + Michael Kerrisk + EXAMPLE: Remove mention of "-rdynamic" + That option isn't needed for compiling and running this program. + Michael Kerrisk + Remove reference to ld.so info page + The command "info ld.so" simply shows the man page... + Michael Kerrisk + Add VERSIONS section + Michael Kerrisk + Reorganize conformance information for 'flags' + +dlsysm.3 + Michael Kerrisk + Move dlsym() and dlvsym() content to new separate page + Zeng Linggang + ATTRIBUTES: Note functions that are thread-safe + + +Newly documented interfaces in existing pages +--------------------------------------------- + +dlopen.3 + Michael Kerrisk, Carlos O'Donell + Document dlmopen(3) + +nl_langinfo.3 + Sam Varshavchik, Michael Kerrisk + Add documentation for nl_langinfo_l(3) + +__ppc_set_ppr_med.3 + Gabriel F. T. Gomes + Document PPC functions providing access to PPR + GNU C Library 2.18 adds functions (__ppc_set_ppr_low(3), + __ppc_set_ppr_med(3), __ppc_set_ppr_med_low(3)) that provide + access to the Program Priority Register (PPR). + +__ppc_yield.3 + Gabriel F. T. Gomes + Document PPC performance-hint functions + GNU C Library 2.18 adds functions __ppc_yield(3), __ppc_mdoio(3), + and __ppc_mdoom(3) that can be used provide a hint that + performance could be improved if shared resources are released + for use by other processors. + + +New and changed links +--------------------- + +dladdr1.3 + Michael Kerrisk + New link to (new) dladdr(3) page + +dlmopen.3 + Michael Kerrisk + New link to dlopen.3 + +dlvsym.3 + Michael Kerrisk + Adjust link to point to new self-contained dlsym(3) page + +nl_langinfo_l.3 + Michael Kerrisk + New link to nl_langinfo.3 + +__ppc_mdoio.3 + Gabriel F. T. Gomes + New link to __ppc_yield.3 + +__ppc_mdoom.3 + Gabriel F. T. Gomes + New link to __ppc_yield.3 + +__ppc_set_ppr_low.3 + Gabriel F. T. Gomes + New link to __ppc_set_ppr_med.3 + +__ppc_set_ppr_med_low.3 + Gabriel F. T. Gomes + New link to __ppc_set_ppr_med.3 + + +Global changes +-------------- + +Very many pages + Michael Kerrisk + Update CONFORMING TO section to reflect POSIX.1-2001 and POSIX.1-2008 + details. (By now, I believe all pages should be up to date with + respect to appropriately mentioning POSIX.1-2001 and POSIX.1-2008.) + +ldd.1 +sprof.1 +execve.2 +dlopen.3 +ld.so.8 + Michael Kerrisk + Prefer "shared object" over "shared library" + The man pages variously use "shared library" or "shared object". + Try to more consistently use one term ("shared object"), while + also pointing out on a few pages that the terms are synonymous. + + +Changes to individual pages +--------------------------- + +accept.2 + Michael Kerrisk + Add mention of POSIX.1-2008 regarding EAGAIN vs EWOULDBLOCK + +bpf.2 + Daniel Borkmann + Various updates/follow-ups to address some fixmes + A couple of follow-ups to the bpf(2) man-page, besides others: + + * Description of map data types + * Explanation on eBPF tail calls and program arrays + * Paragraph on tc holding ref of the eBPF program in the kernel + * Updated ASCII image with tc ingress and egress invocations + * __sync_fetch_and_add() and example usage mentioned on arrays + * minor reword on the licensing and other minor fixups + +execve.2 + Michael Kerrisk + Reword text on POSIX and #! + +io_getevents.2 + Michael Kerrisk + Note return value on interruption by a signal handler + Michael Kerrisk + Clarify details of return value for timeout-expired case + Michael Kerrisk + Clarify and extend discussion of 'timeout' argument + +mmap.2 + Michael Kerrisk + Note that 'length' need not be a page-size multiple for munmap() + Michael Kerrisk [David Rientjes, David Rientjes, Mike Kravetz] + Describe mmap()/munmap() argument requirements for huge-page mappings + Michael Kerrisk + Move discussion of timestamps to NOTES + A straight move; no changes to the content. + This content is better placed in NOTES. + +seccomp.2 + Michael Kerrisk + SEE ALSO: mention libseccomp pages + SEE ALSO: add scmp_sys_resolver(1) + +sigaction.2 + Michael Kerrisk + Correct the list of flags that were added in POSIX.1-2001 + +socketpair.2 + Michael Kerrisk [Goswin von Brederlow] + Clarify use of SOCK_* flags in 'type' argument + See http://bugs.debian.org/794217 + +atexit.3 + Michael Kerrisk + SEE ALSO: add dlopen(3) + +clock_getcpuclockid.3 + Michael Kerrisk + Improve wording of EPERM error + It's imprecise to say that this is an "optional" error + in POSIX.1. + +dl_iterate_phdr.3 + Michael Kerrisk + Note that 'size' allows callback() to discover structure extensions + Michael Kerrisk + SEE ALSO: add dladdr(3) + Michael Kerrisk + CONFORMING TO: note that this function appears on some other systems + +fseeko.3 + Michael Kerrisk + Remove crufty NOTES section + This ancient System V detail is unneeded. + +getutent.3 + Michael Kerrisk + Mention POSIX.1-2008 for the "utmpx" functions + +iconv_close.3 +iconv_open.3 + Michael Kerrisk + CONFORMING TO: change "UNIX98" to "SUSv2" + +malloc.3 + Michael Kerrisk + Change "UNIX 98" to "SUSv2" + +mktemp.3 + Gleb Fotengauer-Malinovskiy + Reference mkdtemp(3) in addition to mkstemp(3) + Mention mkdtemp(3) as another secure alternative to mktemp(3). + + See also https://sourceware.org/bugzilla/show_bug.cgi?id=2898. + +mq_receive.3 +mq_send.3 + Michael Kerrisk + Clarify discussion of 'timeout' + In particular, remove the word 'ceiling', which falsely + suggests that the call might return prematurely. + +nl_langinfo.3 + Michael Kerrisk + Explicitly describe the return value on success + Michael Kerrisk + POSIX specifies that the caller may not modify the returned string + Michael Kerrisk + Enhance RETURN VALUE description + Note some further cases where returned string may be + invalidated or overwritten. + +perror.3 + Michael Kerrisk + Reformat CONFORMING to information + Michael Kerrisk + Note that 'sys_errlist' and 'sys_nerr' are not in POSIX.1 + +posix_openpt.3 + Michael Kerrisk + Reword text regarding systems that don't have posix_openpt() + +printf.3 + Michael Kerrisk + CONFORMING TO: update details for dprintf() and vdprintf() + +setlogmask.3 + Michael Kerrisk + Remove useless statement in CONFORMING TO + Saying that the description in PSOX.1-2001 is flawed, + without saying what the fla is, is not helpful. + (And no, I don't know what the flaw is.) + +shm_open.3 + Michael Kerrisk + Add POSIX.1-2008 details regarding group ID of new shared memory object + +strfmon.3 + Michael Kerrisk + Fix erroneous CONFORMING to + strfmon() is in POSIX.1. + +fanotify.7 + Heinrich Schuchardt + Clarify effects of file moves + If files or directories are moved to other mounts, the inode is + deleted. Fanotify marks are lost. + +mq_overview.7 + Michael Kerrisk + Remove unneeded CONFORMING TO section + +nptl.7 + Michael Kerrisk [Nicholas Miell] + Note that i386 and x86-64 binaries can't share mutexes + +sched.7 + Nikola Forró + Fix descriptions of sched_get_priority_max() / sched_get_priority_min() + +sem_overview.7 + Michael Kerrisk + Remove unneeded CONFORMING TO section + +shm_overview.7 + Michael Kerrisk + Remove unneeded CONFORMING TO section + +sigevent.7 + Michael Kerrisk + Remove unneeded CONFORMING TO section + +symlink.7 + Michael Kerrisk + Update with POSIX.1-2008 details for link(2) + +ld.so.8 + Michael Kerrisk [Jonathan David Amery] + Items in LD_LIBRARY_PATH can also be delimited by semicolons + See http://bugs.debian.org/794559. + + +==================== Changes in man-pages-4.03 ==================== + +Released: 2015-12-05, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alexander Shishkin +Alexei Starovoitov +Andy Lutomirski +Arto Bendiken +Carlos O'Donell +Casper Ti. Vector +Daniel Borkmann +David Drysdale +Eric B Munson +Florian Weimer +Gabriel F. T. Gomes +Heinrich Schuchardt +Ingo Molnar +Jakub Wilk +Johannes Stüttgen +Jonathan Wakely +Jonny Grant +Kees Cook +Maria Guseva +Masami Hiramatsu +Meikun Wang +Michael Kerrisk +Michal Hocko +Mike Frysinger +Namhyung Kim +Nikola Forró +Olivier TARTROU +Peter Hurley +Peter Zijlstra (Intel) +Ross Zwisler +Serge Hallyn +Silvan Jegen +Stefan Tauner +Steven Rostedt +Tobias Stoeckmann +Tycho Andersen +Ville Skyttä +Vince Weaver +Zeng Linggang + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +perf_event_open.2 + Vince Weaver + 4.1 adds AUX sample support + Vince Weaver + 4.1 data_offset and data_size fields + Vince Weaver [Alexander Shishkin] + Document aux_{head,tail,offset,size} support + Vince Weaver + 4.0 update rdpmc documentation + Vince Weaver + 4.1 adds PERF_RECORD_ITRACE_START + Vince Weaver + Document 4.1 clockid support + Vince Weaver [Steven Rostedt, Masami Hiramatsu] + 4.1 PERF_EVENT_IOC_SET_BPF support + Vince Weaver + 4.1 adds AUX_FLAG_OVERWRITE support + Vince Weaver + 4.1 PERF_SAMPLE_BRANCH_CALL_STACK + Vince Weaver + 4.1 adds aux_watermark + Vince Weaver + Add possibility of EBUSY error + +prctl.2 + Andy Lutomirski [Kees Cook, Serge Hallyn] + Document operations for ambient capabilities + Michael Kerrisk + Rework PR_CAP_AMBIENT text + Note that arg4 and arg5 must be zero for CAP_AMBIENT + RETURN VALUE: Add PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET case + ERRORS: document PR_CAP_AMBIENT error cases + +__ppc_set_ppr_med.3 + Gabriel F. T. Gomes + Document PPC functions providing access to PPR + GNU C Library commit 1747fcda4902a3b46183d93fb16ed9b436b2608b + extends the priorities that can be set to the Program Priority + Register (PPR), with the functions: __ppc_set_ppr_very_low(3) + and __ppc_set_ppr_med_high(3). + +capabilities.7 + Andy Lutomirski [Kees Cook, Serge Hallyn] + Document ambient capabilities + Michael Kerrisk + Various additions and reworkings for ambient capability text + + +New and changed links +--------------------- + +__ppc_set_ppr_med_high.3 + Gabriel F. T. Gomes + New link to __ppc_set_ppr_med.3 + +__ppc_set_ppr_very_low.3 + Gabriel F. T. Gomes + New link to __ppc_set_ppr_med.3 + + +Changes to individual pages +--------------------------- + +mremap.2 + Eric B Munson [Michal Hocko] + Add note about mremap() with locked areas + When mremap() is used to move or expand a mapping that is locked + with mlock() or equivalent it will attempt to populate the new + area. However, like mmap(MAP_LOCKED), mremap() will not fail if + the area cannot be populated. Also like mmap(MAP_LOCKED) this + might come as a surprise to users and should be noted. +open.2 + Michael Kerrisk [David Drysdale] + Remove accidental mention of O_TTY_INIT + An earlier edit mentioned O_TTY_INIT as a file creation flag. + That's true, according POSIX, but Linux does not implement + this flag, so remove mention of it. + +pipe.2 + Michael Kerrisk + SEE ALSO: add splice(2) + +prctl.2 + Michael Kerrisk + Reorder options alphabetically + Employ a pseudo-alphabetical order, ordering options after removal + of any "PR_", "PR_SET_", or "PR_GET" prefix. + Michael Kerrisk + Fix alphabetical misplacements in ERRORS + +ptrace.2 + Tycho Andersen + Document PTRACE_O_SUSPEND_SECCOMP flag + Michael Kerrisk + Document /proc/sys/kernel/yama/ptrace_scope + Michael Kerrisk + Note that PTRACE_ATTACH cannot be applied to nondumpable processes + Michael Kerrisk + SEE ALSO: add prctl(2) + +reboot.2 + Casper Ti. Vector + 1-argument reboot() is also provided by alternative libc + +seccomp.2 + Michael Kerrisk + Describe use of 'instruction_pointer' data field + Michael Kerrisk [Kees Cook] + Note why all filters in a set are executed even after SECCOMP_RET_KILL + +signalfd.2 + Michael Kerrisk + Describe semantics with respect to SCM_RIGHTS + +syscalls.2 + Michael Kerrisk + Add mlock(2) + Michael Kerrisk + Add userfaultfd() + +daemon.3 + Michael Kerrisk [Johannes Stüttgen] + Note that daemon() is buggy with respect to controlling tty acquisition + +dirfd.3 + Jonathan Wakely + Remove outdated NOTES + As stated in the SYNOPSIS, since glibc 2.10 this function is also + declared by the relevant X/Open and POSIX macros. + +dlopen.3 + Michael Kerrisk + Make it more explicit that LD_BIND_NOW overrides RTLD_LAZY + Michael Kerrisk [Florian Weimer] + Correct the pathname used in EXAMPLE + Quoting Florian: + + This does not work because libm.so can be a linker script: + + handle = dlopen("libm.so", RTLD_LAZY); + + The proper way to do this is to include + and use LIBM_SO. + + See https://bugzilla.kernel.org/show_bug.cgi?id=108821 + Michael Kerrisk + Include a shell session showing build/run in EXAMPLE + Michael Kerrisk + Change arguments to main() to "void" in EXAMPLE + +fgetgrent.3 + Zeng Linggang + ATTRIBUTES: Note function that is not thread-safe + +fgetpwent.3 + Zeng Linggang + ATTRIBUTES: Note function that is not thread-safe + +getauxval.3 + Michael Kerrisk + Add some details for AT_SECURE + +getspnam.3 + Zeng Linggang + ATTRIBUTES: Note functions that are/aren't thread-safe + +mallinfo.3 + Zeng Linggang + ATTRIBUTES: Note function that is not thread-safe + +mallopt.3 + Carlos O'Donell + Document M_ARENA_TEST and M_ARENA_MAX + +posix_fallocate.3 + Michael Kerrisk + Clarify text relating to MT-safety + Carlos O'Donell + Mention glibc emulation caveats + +termios.3 + Olivier TARTROU + Add missing details on behaviour of PARMRK + For a serial terminal, with a specific configuration, input bytes + with value 0377 are passed to the program as two bytes, 0377 0377. + +tty_ioctl.4 + Michael Kerrisk [Peter Hurley] + Note that TIOCTTYGSTRUCT went away in Linux 2.5.67 + +core.5 + Ross Zwisler + Add info about DAX coredump filtering flags + Kernel 4.4 added two new core dump filtering flags, + MMF_DUMP_DAX_PRIVATE and MMF_DUMP_DAX_SHARED. + + These flags allow us to explicitly filter DAX mappings. + This is desirable because DAX mappings, like hugetlb + mappings, have the potential to be very large. + +nsswitch.conf.5 + Nikola Forró + Add list of files being read when "files" service is used + This is not mentioned anywhere. Users can assume that the file + being read is something like /etc/$DATABASE, but that's not + always the case. It's better to explicitly specify which + file is read for each respective database. The list of + files was acquired from glibc source code. + +proc.5 + Heinrich Schuchardt [Michael Kerrisk] + Add details for threads-max + Add detail information for threads-max. + The checks for minimum and maximum values exist since kernel 4.1. + https://lkml.org/lkml/2015/3/15/96 + Heinrich Schuchardt + /proc/sys: Describe whitespace characters + Michael Kerrisk + Document 'CapAmb' in /proc/PID/status + Michael Kerrisk + Add reference to ptrace(2) for /proc/sys/kernel/yama/ptrace_scope + +aio.7 + Michael Kerrisk [Meikun Wang] + Add missing include file, , to example program + +mq_overview.7 + Michael Kerrisk [Arto Bendiken] + Document QSIZE bug that appeared in 3.5 and was fixed in 4.2 + +path_resolution.7 + Michael Kerrisk + Clarify recursive resolution of symlinks and note limits + +pipe.7 + Michael Kerrisk + SEE ALSO: add splice(2) + +rtld-audit.7 + Namhyung Kim + Fix (typo) error in la_pltenter() description + s/la_pltenter()/la_pltexit()/ + + la_pltenter() is called regardless of the value of + framesizep but la_pltexit() is called only if la_pltenter() + returns with non-zero framesizep set. I spent long time to + figure out why la_pltexit() is not called at all. + +signal.7 + Michael Kerrisk [Michael Hocko] + Note async-signal-safe functions added by POSIX.1-2008 TC1 + +tcp.7 + Daniel Borkmann [Michael Kerrisk] + Improve paragraphs on tcp_ecn and add tcp_ecn_fallback bullet + Improve description of tcp_ecn, fix the RFC number and it's + not a boolean anymore since long time, and add a description + for tcp_ecn_fallback. + + See also kernel doc under Documentation/networking/ip-sysctl.txt + on tcp_ecn and tcp_ecn_fallback. + +ld.so.8 + Michael Kerrisk + LD_POINTER_GUARD has been removed in glibc 2.23 + Michael Kerrisk + Describe secure-execution mode + Michael Kerrisk [Maria Guseva] + Replace mentions of set-UID/set-GID programs with secure-execution mode + Inspired by a patch from Maria Guseva. + Maria Guseva [Silvan Jegen] + LD_DEBUG is effective in secure-execution mode if /etc/suid-debug exists + + +==================== Changes in man-pages-4.04 ==================== + +Released: 2015-12-29, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alexander Monakov +Andries E. Brouwer +Archie Cobbs +Carlos O'Donell +Colin Rice +Darren Hart +Davidlohr Bueso +Dmitry V. Levin +Eric B Munson +Heinrich Schuchardt +H.J. Lu +Jakub Wilk +Jonathan Wakely +Jonny Grant +Laurent Georget +Lennart Poettering +Mathieu Desnoyers +Michael Kerrisk +Michal Hocko +Mike Frysinger +Pádraig Brady +Paul Eggert +Pavel Machek +Phil Blundell +Richard Voigt +Rich Felker +Rusty Russell +Thomas Gleixner +Tom Gundersen +Torvald Riegel +Vincent Lefevre +Vlastimil Babka +Walter Harms +Zack Weinberg + + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +futex.2 + Michael Kerrisk, Thomas Gleixner, Torvald Riegel [Davidlohr Bueso, Heinrich Schuchardt, Darren Hart, Rusty Russell, Pavel Machek, Rich Felker] + Rewrite and massively expand page + +membarrier.2 + Mathieu Desnoyers [Michael Kerrisk] + New page documenting membarrier() system call + + +Newly documented interfaces in existing pages +--------------------------------------------- + +mlock.2 + Eric B Munson [Michal Hocko, Vlastimil Babka, Michael Kerrisk] + Document mlock2(2) and MCL_ONFAULT + + +New and changed links +--------------------- + +mlock2.2 + Eric B Munson + New link to mlock.2 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + ERRORS: standardize text for EMFILE error + +Various pages + Michael Kerrisk + ERRORS: standardize error text for ENOTSOCK error + +Various pages + Michael Kerrisk + ERRORS: standardize text for ENFILE error + + +Changes to individual pages +--------------------------- + +clock_getres.2 + Michael Kerrisk + SEE ALSO: add vdso(7) + +epoll_create.2 + Michael Kerrisk + ERRORS: add another EMFILE error case + +fanotify_init.2 + Michael Kerrisk + ERRORS: add an EMFILE error case + +fork.2 + Michael Kerrisk + Child of MT-process is restricted to async-signal-safe functions + +getcpu.2 + Michael Kerrisk + SEE ALSO: add vdso(7) + +getrlimit.2 + Michael Kerrisk [Lennart Poettering] + The init of measurement for RLIMIT_RSS is bytes, not pages + +get_robust_list.2 + Michael Kerrisk + Reword EINVAL error text + +gettimeofday.2 + Carlos O'Donell + Expand on the historical meaning of tz_dsttime + Michael Kerrisk + SEE ALSO: add vdso(7) + +inotify_init.2 + Michael Kerrisk + ERRORS: add an EMFILE error case + +personality.2 + Dmitry V. Levin + Note kernel and glibc versions that introduced this system call + +poll.2 + Richard Voigt + timeout_ts is a pointer, so use -> not . for member access + Michael Kerrisk + Shorten name of timeout argument for ppoll() + The name is overly long, and does not hint at the fact + that this argument is a pointer. Fix this by renaming: + s/timeout_ts/tmo_p/ + +sendfile.2 + Laurent Georget + Document more ERRORS + +sigreturn.2 + Michael Kerrisk + SEE ALSO: add vdso(7) + +socketcall.2 + Michael Kerrisk + Since Linux 4.3, x86-32 provides direct system calls for the sockets API + +time.2 + Zack Weinberg + Explain why the glibc time() wrapper never sets 'errno' + Michael Kerrisk [H.J. Lu] + Where time() is provided by vDSO, an invalid address may give SIGSEGV + Michael Kerrisk [Paul Eggert] + Describe EOVERFLOW details + Michael Kerrisk + SEE ALSO: add vdso(7) + Michael Kerrisk + Rename 't' argument to 'tloc' + +dlerror.3 + Michael Kerrisk [Jonny Grant] + Clarify that the string returned by dlerror() is null terminated + +dlopen.3 + Michael Kerrisk + Include a shell session showing build/run in EXAMPLE + Michael Kerrisk + Change arguments to main() to "void" in EXAMPLE + +drand48.3 + Michael Kerrisk [Vincent Lefevre] + Correct descriptions of ranges returned by these functions + See http://bugs.debian.org/803459 + +errno.3 + Michael Kerrisk + Note probable cause of ENFILE error + +fnmatch.3 + Pádraig Brady + Describe the FNM_EXTMATCH flag and pattern syntax + +iconv.3 + Andries E. Brouwer + NOTES: describe correct usage for flushing partially buffered input + +random_r.3 + Michael Kerrisk [Archie Cobbs] + Clarify need to use initstate_r() + +tzset.3 + Carlos O'Donell + Clarify "daylight" and remove erroneous note + +random.4 + Michael Kerrisk [Tom Gundersen] + Rework example scripts to assume 'poolsize' unit is bits, not bytes + Michael Kerrisk [Walter Harms] + Use modern command substitution syntax in shell session log + +proc.5 + Michael Kerrisk + Reaching /proc/sys/fs/file-max limit normally produces an ENFILE error + +futex.7 + Heinrich Schuchardt + SEE ALSO updates + Michael Kerrisk + Note some other locking primitives that are built with futexes + Heinrich Schuchardt + NPTL, avoid abbreviation + Michael Kerrisk + Note that a futex is 4 bytes on all platforms + +vdso.7 + Michael Kerrisk + Add note on strace(1) and vDSO + +ld.so.8 + H.J. Lu [Michael Kerrisk] + Document LD_PREFER_MAP_32BIT_EXEC + Michael Kerrisk + Clarify setting of LD_BIND_NOT + Michael Kerrisk + Clarify setting of LD_DYNAMIC_WEAK + Michael Kerrisk + Clarify setting of LD_TRACE_PRELINKING + Michael Kerrisk + Clarify some details for LD_SHOW_AUXV + + +==================== Changes in man-pages-4.05 ==================== + +Released: 2016-03-15, Christchurch + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Adhemerval Zanella +Akihiro Suda +Alan Aversa +Alan Cox +Alec Leamas +Alex Henrie +Alexander Miller +Andreas Gruenbacher +Andreas Schwab +Anna Schumaker +Askar Safin +Bill O. Gallmeister +Carlos O'Donell +Chris Pick +Christoph Hellwig +Craig Gallek +Darrick J. Wong +Davidlohr Bueso +Dmitry V. Levin +Dr. Tobias Quathamer +Eric Blake +Eric Dumazet +Florian Weimer +Gabriel Corona +Heinrich Schuchardt +Ivan Shapovalov +Jakub Wilk +Jason Baron +Jason Vas Dias +Jérémie Galarneau +Jeremy Harris +Joachim Wuttke +Joe Stein +John Stultz +Josh Triplett +Kondo, Naoya +Krzysztof Adamski +Manfred Spraul +Marianne CHEVROT +Marko Myllynen +Mark Post +Martin Gebert +Mats Wichmann +Matt Zimmerman +Michael Kerrisk ` +Mike Frysinger +Minchan Kim +Naoya Kondo +Naresh Kamboju +Nikola Forró +Nikos Mavrogiannopoulos +Orion Poplawski +Pakin Yury +Patrick Donnelly +Paul Eggert +Paul Pluzhnikov +Peter Hurley +Peter Wu +Petr Gajdos +Philip Semanchuk +Rasmus Villemoes +Rich Felker +Simon Que +Stephan Bergmann +Stéphane Aulery +Stephen Hurd +Vincent Bernat +William Preston +Yuri Kozlov +Zefram + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +copy_file_range.2 + Anna Schumaker [Darrick J. Wong, Christoph Hellwig, Michael Kerrisk] + New page documenting copy_file_range() + copy_file_range() is a new system call for copying ranges of data + completely in the kernel. This gives filesystems an opportunity to + implement some kind of "copy acceleration", such as reflinks or + server-side-copy (in the case of NFS). + +personality.2 + Michael Kerrisk + This page has been greatly expanded, to add descriptions of + personality domains. + +fmemopen.3 + Michael Kerrisk [Adhemerval Zanella] + Significant reworking of this page: + * Rework discussion of the (obsolete) binary mode + * Split open_memstream(3) description into a separate page. + * Note various fmemopen() bugs that were fixed in glibc 2.22 + * Greatly expand description of 'mode' argument + * Rework description of 'buf' and 'len' arguments + * Expand discussion of "current position" for fmemopen() stream + +ntp_gettime.3 + Michael Kerrisk + New page describing ntp_gettime(3) and ntp_gettimex(3) + +open_memstream.3 + Michael Kerrisk + New page created by split of fmemopen(3). + At the same time, add and rework a few details in the text. + +posix_spawn.3 + Bill O. Gallmeister, Michael Kerrisk + New man page documenting posix_spawn(3) and posix_spawnp(3) + +readdir.3 + Michael Kerrisk [Florian Weimer] + Split readdir_r() content into separate page + As suggested by Florian Weimer: + + It may make sense to move this documentation to a separate + manual page, specific to readdir_r. This will keep the + readdir() documentation nice and crisp. Most programmers + will never have to consult all these details. + Michael Kerrisk + Near complete restructuring of the page and add some further details + Michael Kerrisk [Florian Weimer, Rich Felker, Paul Eggert] + Add a lot more detail on portable use of the 'd_name' field + +readdir_r.3 + Michael Kerrisk [Florian Weimer] + New page created after split of readdir(3). + Michael Kerrisk [Florian Weimer] + Explain why readdir_r() is deprecated and readdir() is preferred + Michael Kerrisk [Florian Weimer] + Remove misleading code example using pathconf() + +lirc.4 + Alec Leamas + New page documenting lirc device driver + + +Newly documented interfaces in existing pages +--------------------------------------------- + +adjtimex.2 + Michael Kerrisk + Document ntp_adjtime(3) + +epoll_ctl.2 + Michael Kerrisk [Jason Baron] + Document EPOLLEXCLUSIVE + +madvise.2 + Minchan Kim [Michael Kerrisk] + Document MADV_FREE + Document the MADV_FREE flag added to madvise() in Linux 4.5. + +proc.5 + Michael Kerrisk + Document CmaTotal and CmaFree fields of /proc/meminfo + Michael Kerrisk + Document additional /proc/meminfo fields + Document DirectMap4k, DirectMap4M, DirectMap2M, DirectMap1G + Michael Kerrisk + Document MemAvailable /proc/meminfo field + Michael Kerrisk + Document inotify /proc/PID/fdinfo entries + Michael Kerrisk + Document fanotify /proc/PID/fdinfo entries + Michael Kerrisk + Add some kernel version numbers for /proc/PID/fdinfo entries + Michael Kerrisk [Patrick Donnelly] + /proc/PID/fdinfo displays the setting of the close-on-exec flag + Note also the pre-3.1 bug in the display of this info. + +socket.7 + Craig Gallek [Michael Kerrisk, Vincent Bernat] + Document some BPF-related socket options + Document the behavior and the first kernel version for each of the + following socket options: + + SO_ATTACH_FILTER + SO_ATTACH_BPF + SO_ATTACH_REUSEPORT_CBPF + SO_ATTACH_REUSEPORT_EBPF + SO_DETACH_FILTER + SO_DETACH_BPF + SO_LOCK_FILTER + + +New and changed links +--------------------- + +isalpha_l.3 + Michael Kerrisk + New link to isalpha.3 + +longjmp.3 + Michael Kerrisk + Replace page with link to setjmp(3), which now incorporates longjmp() + +ntp_adjtime.3 + Michael Kerrisk + New link to adjtimex(2) + +ntp_gettimex.3 + Michael Kerrisk + New link to ntp_gettime.3 + +open_wmemstream.3 + Michael Kerrisk + Update link to point to new open_memstream(2) page + +posix_spawnp.3 + Michael Kerrisk + New link to new posix_spawn.3 page + +siglongjmp.3 + Michael Kerrisk + Rewire link to point to setjmp(3) + +strerror_l.3 + Michael Kerrisk + New link to strerror.3 + Fix missing link + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Update FTM requirements (_DEFAULT_SOURCE) + Michael Kerrisk + Update feature test macro requirements + Update to use _DEFAULT_SOURCE, and also changes brought by + glibc commit 266865c0e7b79d4196e2cc393693463f03c90bd8. + +Various pages + Michael Kerrisk + Simplify FTM requirements + Looking at (or feature_test_macros(7)), one can + see that when _XOPEN_SOURCE is defined with the value 700 + (or greater), then _POSIX_C_SOURCE is defined with the value + 200809L (or greater). Therefore, terms in the man pages such as + + _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L + + can be simplified to: + + _POSIX_C_SOURCE\ >=\ 200809L + +Various pages + Michael Kerrisk + Simplify FTM requirements + Looking at (or feature_test_macros(7)), one can + see that when _XOPEN_SOURCE is defined with the value 600 + (or greater), then _POSIX_C_SOURCE is defined with the value + 200112L (or greater). Therefore, terms in the man pages such as + + _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L + + can be simplified to: + + _POSIX_C_SOURCE\ >=\ 200112L + +Various pages + Michael Kerrisk + Simplify FTM requirements + _XOPEN_SOURCE implies _POSIX_C_SOURCE >=2, so simplify FTM + requirements in various pages. + +Various pages + Michael Kerrisk + Remove "or 'cc -std=c99'" from SYNOPSIS + Under the FTM requirements all of these pages document the + requirement for _ISOC99_SOURCE. And feature_test_macros(7) now + documents that "cc -std=c99" produces the same effect as defining + _ISOC99_SOURCE. So, all of these pages don't additionally need + to specify "or 'cc -std=c99'" under the FTM requirements + in the SYNOPSIS. Removing that redundant text also simplifies + the SYNOPSIS a little. + +Various pages + Michael Kerrisk + Simplify FTM requirements + Looking at (or feature_test_macros(7)), one can + see that when _XOPEN_SOURCE is defined with the value 600 + (or greater), then _POSIX_C_SOURCE is defined with the value + 200112L (or greater). Therefore, terms in the man pages such as + + _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L + + can be simplified to: + + _POSIX_C_SOURCE\ >=\ 200112L + +Various pages + Michael Kerrisk + Remove references to _XOPEN_SOURCE_EXTENDED in SYNOPSIS + _XOPEN_SOURCE_EXTENDED is obsolete (it existed in SUSv1, but not + subsequent standards). _XOPEN_SOURCE >= 500 produces the same + effects as (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED). Modifying + the SYNOPSIS of various ages that contain: + + _XOPEN_SOURCE\ >=\ 500 || + _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + + to just: + + _XOPEN_SOURCE\ >=\ 500 + + This has the following benefits: + + a) Simplifying the SYNOPSIS by removing ancient + historical information. + + b) Preventing users from being misled into using + _XOPEN_SOURCE_EXTENDED in new source code. + +Various pages + Michael Kerrisk + Remove mention of the obsolete _POSIX_SOURCE macro from SYNOPSIS + _POSIX_SOURCE was a POSIX.1-1990 creation that was soon made + obsolete bu _POSIX_C_SOURCE. Retaining mention of it + in the feature test macro requirements section of the + SYNOPSIS doesn't contain important information, and may + mislead readers into actually trying to use this macro. + A few mentions of it are maintained in a some pages where + defining _POSIX_SOURCE inhibits some behavior. + +Various sockets-related pages + Michael Kerrisk [Carlos O'Donell] + Use consistent argument/variable names for socket addresses and lengths + As noted by Carlos, there's quite a bit of inconsistency across + pages. Use 'addr' and 'addrlen' consistently in variables and + function arguments. + +Various pages + Michael Kerrisk + Wording fix: "current file offset" ==> "file offset" + "File offset" is the preferred POSIX terminology. + +Various pages + Michael Kerrisk + Word "descriptor" more precisely + Use either "file descriptor" or "message queue descriptor". + +Various pages + Michael Kerrisk + ERRORS: add reference to signal(7) in description of EINTR + + +Changes to individual pages +--------------------------- + +locale.1 + Marko Myllynen + Add "locale -c charmap" as an example + Addresses https://bugzilla.kernel.org/show_bug.cgi?id=104511. + +localedef.1 + Marko Myllynen + Add hint on purpose of --no-archive + Indicate why using --no-archive might be a good idea. The issue + is that if you create a custom locale with localedef(1) and put + it to the locale archive then during the next glibc upgrade the + locale archive is updated as well and your custom locale is gone.) + +accept.2 + Michael Kerrisk + ERRORS: improve description for EBADF + +adjtimex.2 + Michael Kerrisk [John Stultz] + Various improvements after feedback from John Stultz + Michael Kerrisk + Remove FTM requirements + It seems that adjtimex() never needed _BSD_SOURCE (and my + earlier commit 5918743bc8b02b was simply a blunder). + Michael Kerrisk + Split EINVAL error cases + Michael Kerrisk + Note treatment of out-of-range buf.offset + Michael Kerrisk + Don't refer reader to adjtime(3) + Probably, it's not wise to suggest adjtime(3) as the more + portable API. Rather, ntp_adjtime(3) should be used. + Michael Kerrisk [Naresh Kamboju] + Update details of buf.offset EINVAL error + Michael Kerrisk + SEE ALSO: add ntp_gettime(3) + Michael Kerrisk + Improve description of some PPS timex fields + Michael Kerrisk + Add ATTRIBUTES section + William Preston [Petr Gajdos] + Update a detail in adjtimex return value description + Michael Kerrisk + Note range constraints and clamping for ADJ_FREQUENCY + +bdflush.2 + Michael Kerrisk + Note that glibc support for this system call went away in version 2.23 + +bind.2 + Michael Kerrisk + Improve description of ENOENT error + +bpf.2 + Michael Kerrisk + Document close-on-exec semantics + The close-on-exec file descriptor flag is automatically enabled + for FDs returned by bpf(). + +chmod.2 + Michael Kerrisk + Clarify terminology (file mode versus file permission bits) + +chown.2 + Michael Kerrisk + ERRORS: improve EBADF description + +clone.2 +unshare.2 + Michael Kerrisk + Remove mention of _BSD_SOURCE and _SVID_SOURCE + The right way to expose declarations for these Linux-specific + system calls was always _GNU_SOURCE. Mentioning the historical + use of _BSD_SOURCE and _SVID_SOURCE just clouds the issue. + +connect.2 + Michael Kerrisk + ERRORS: improve EBADF description + +create_module.2 + Michael Kerrisk + Glibc 2.23 removed last vestiges of support for this system call + +delete_module.2 + Michael Kerrisk + Glibc 2.23 removed last vestiges of support for this system call + +epoll_ctl.2 + Michael Kerrisk + Document ELOOP error for circular monitoring loops + +eventfd.2 + Michael Kerrisk + Note that eventfd info is available in /proc/PID/fdinfo + +execve.2 + Michael Kerrisk [Krzysztof Adamski] + Add EPERM error for capabilities check of capability-dumb binaries + Michael Kerrisk + Add reference to ld-linux.so(8) + Michael Kerrisk + SEE ALSO: add system(3) + +fanotify_init.2 + Michael Kerrisk + Note kernel version that allowed O_CLOEXEC for event_f_flags + +fcntl.2 +flock.2 + Michael Kerrisk + SEE ALSO: add lslocks(8) + +fcntl.2 + Michael Kerrisk [Jason Vas Dias] + Rework description of F_SETOWN + As suggested by Jason, make it clearer that I/O signalling + requires the use of both F_SETOWN and O_ASYNC. While we're at, + make a few other cleanups to the text. + Michael Kerrisk + Remove mention of _BSD_SOURCE to get definition of F_SETOWN/F_GETOWN + This usage went away in glibc 2.20, and the simplest remedy + is just to omit mention of it. + +futex.2 + Michael Kerrisk + FUTEX_CLOCK_REALTIME can now be used with FUTEX_WAIT + +get_kernel_syms.2 + Michael Kerrisk + Note that glibc does not support this system call + +init_module.2 + Michael Kerrisk + Glibc 2.23 removed last vestiges of support for this system call + +ioctl_list.2 + Heinrich Schuchardt + Include uapi/linux/wireless.h + Add the list of wireless IOCTLs. + Heinrich Schuchardt + Path to sockios.h + sockios.h is now in include/uapi + Heinrich Schuchardt + Add reference to netdevice.7 + netdevice.7 describes most of the IOCTLs of sockios.h + Heinrich Schuchardt + Transfer structure (wireless.h IOCTLs) + The sole parameter to be passed to the wireless.h IOCTLs is + of type struct iwreq *. + +ioperm.2 + Michael Kerrisk [Alex Henrie] + ioperm.2: Permissions are inherited across fork(2) + See https://bugzilla.kernel.org/show_bug.cgi?id=99911 + +iopl.2 + Michael Kerrisk [Alex Henrie] + Permissions are not inherited across fork(2) or preserved on execve(2) + See https://bugzilla.kernel.org/show_bug.cgi?id=99901 + +lseek.2 + Michael Kerrisk + FUSE now supports SEEK_HOLE and SEEK_DATA + Michael Kerrisk + NFS supports SEEK_HOLE and SEEK_DATA + + Michael Kerrisk + SEE ALSO: add open(2) + +madvise.2 + Michael Kerrisk + Clarify MADV_HWPOISON wording to say that it applies to a page range + +mknod.2 + Michael Kerrisk + SEE ALSO: add mknod(1) + +mount.2 + Michael Kerrisk + SEE ALSO: add findmnt(8) + +open.2 + Michael Kerrisk + NOTES: mention existence of proc/PID/fd and /proc/PID/fdinfo + Mark Post [Petr Gajdos] + O_TMPFILE support is now provided bt Btrfs + +pipe.2 + Michael Kerrisk [Eric Blake] + Note treatment of 'pipefd' on error + +poll.2 + Michael Kerrisk [Josh Triplett] + Document spurious EAGAIN error that can occur on other systems + Light reworking of text proposed by Josh Triplett. + +readlink.2 + Michael Kerrisk + Clarify EINVAL error description + +recv.2 + Heinrich Schuchardt + Equivalence to read() + Describe the recv(2)-read(2) and the recvfrom(2)-recv(2) + equivalences for zero-valued arguments. + Michael Kerrisk + MSG_WAITALL has no effect for datagram sockets + +recv.2 +cmsg.3 + Nikola Forró + Fix type of cmsg_len member of cmsghdr structure + The type shown for cmsg_len member of cmsghdr structure is socklen_t, + but the actual type used by glibc and the kernel is size_t. + The information was obtained from glibc source code: + http://bit.ly/21m1RMp + Michael Kerrisk + Note that cmsg_len is typed as socklen_t in POSIX.1 + + +sched_setaffinity.2 + Michael Kerrisk [Florian Weimer, Florian Weimer] + Warn that CPU_ALLOC() may allocate a slightly CPU set than requested + Michael Kerrisk [Florian Weimer] + Add reference to CPU_ALLOC(3) + +sched_setattr.2 + Michael Kerrisk [Akihiro Suda] + EPERM depends on affinity mask of target thread, not calling thread + +select.2 + Michael Kerrisk [Josh Triplett] + Document spurious EAGAIN error that can occur on other systems + Light reworking of text proposed by Josh Triplett. + Nikos Mavrogiannopoulos + Mention the 'fd_set' size limitation early and refer to poll(2) + Change this because of the serious limitation of select() + imposing a limit on the range of file descriptors that can + be monitored. This is currently mentioned too late in the + documentation (in the NOTES section). The man page should + warn early and refer to poll(2) as soon as possible. + Michael Kerrisk + Add details on the glibc fixed-size fd_set limitation + No modern application should use select() on Linux. + +select_tut.2 + Michael Kerrisk + Some readability fixes to example program + Michael Kerrisk + Better variable names in example program + Michael Kerrisk + Simplify 'if' logic in example program + Michael Kerrisk + Use correct type (socklen_t) for addrlen + +semctl.2 + Michael Kerrisk [Davidlohr Bueso, Manfred Spraul, Philip Semanchuk] + NOTES: note when 'sempid' is set on various implementations + See https://bugzilla.kernel.org/show_bug.cgi?id=112271 and + http://thread.gmane.org/gmane.linux.kernel/2162754/ + Subject: [PATCH] Don't set sempid in semctl syscall. + Date: 2016-02-26 12:21:38 GMT + +semop.2 + Michael Kerrisk + Tweak comment describing 'sempid' + +sendfile.2 + Askar Safin + Fix incorrect description in text referring to splice(2) + Michael Kerrisk + SEE ALSO: add copy_file_range(2) + +setpgid.2 + Michael Kerrisk + Correct/simplify FTM requirements for BSD setpgrp() and getpgrp() + +signalfd.2 + Michael Kerrisk + Note that signalfd info is available in /proc/PID/fdinfo + +sigprocmask.2 + Michael Kerrisk [Mike Frysinger] + Explicitly refer the reader to sigsetops(3) + This man page did not make it obvious which functions + should be used for manipulating signals sets, nor where + those functions were documented. + +socketpair.2 + Michael Kerrisk [Eric Blake] + Note treatment of 'sv' on error + +splice.2 + Askar Safin + Improve description of 0 return value. + See https://bugzilla.kernel.org/show_bug.cgi?id=90911 + +statfs.2 + Michael Kerrisk [Jakub Wilk] + Use consistent case for hex constants + +sync.2 + Christoph Hellwig + Clarify description and document the Linux data integrity guarantees + +syscall.2 + Mike Frysinger + Add more architectures and improve error documentation + Move the error register documentation into the main table rather + than listing them in sentences after the fact. + + Add sparc error return details. + + Add details for alpha/arc/m68k/microblaze/nios2/powerpc/superh/ + tile/xtensa. + +syscalls.2 + Michael Kerrisk + Add copy_file_range(2) + +times.2 + Kondo, Naoya + Fix an incorrect description in NOTES + The text has an incorrect description in NOTES, it says + that (2^32/HZ) - 300 is about 429 million. It is correct + only if HZ=10 which does not look common today. So just + removing "(i.e., about 429 million)" is good enough. + +truncate.2 + Michael Kerrisk + SEE ALSO: add truncate(1) + +uselib.2 + Michael Kerrisk + Mention CONFIG_USELIB + Michael Kerrisk + Note that glibc does not support this (obsolete) system call + +wait.2 +wait4.2 + Michael Kerrisk + Rename the "status" argument to "wstatus" + The fact that exit(3)/_exit(2) has an argument called + "status" and the same name is used in the arguments to the + wait*() calls can a little too easily lead the user into + thinking that the two arguments hold the same information, + when of course they don't. So, use a different name + for the argument of the wait*() functions, to reduce + the chances of such confusion. + +backtrace.3 + Michael Kerrisk [Martin Gebert] + Small fixes to example program + +clearenv.3 + Michael Kerrisk [Matt Zimmerman] + Clarify the use and effect of clearenv() + See http://bugs.debian.org/679323 + Michael Kerrisk + Variables can be added to the environment after calling clearenv() + +clog10.3 + Michael Kerrisk + Show an alternative equivalence for clog10() + Michael Kerrisk + Update CONFORMING TO + Fix grammar error and add C11. + +dl_iterate_phdr.3 + Michael Kerrisk [Paul Pluzhnikov] + Describe 'struct dl_phdr_info' fields added in glibc 2.4 + See https://bugzilla.kernel.org/show_bug.cgi?id=103011 + Michael Kerrisk [Simon Que] + Note that first object visited by 'callback' is the main program + See https://bugzilla.kernel.org/show_bug.cgi?id=94141 + +errno.3 + Michael Kerrisk + Add some explanation of ENOENT error + +exec.3 + Michael Kerrisk + SEE ALSO: add system(3) + +exp.3 + Michael Kerrisk [Joachim Wuttke] + SEE ALSO: add expm1(3) + +fopen.3 + Michael Kerrisk + SEE ALSO: add open_memstream(3) + +fts.3 + Michael Kerrisk + BUGS: glibc-2.23 now has LFS support for the fts functions + +gamma.3 + Michael Kerrisk [Alan Cox] + gamma() was documented in SVID 2 + +getaddrinfo.3 + Michael Kerrisk [Andreas Schwab, Orion Poplawski] + Update FTM requirements for glibc 2.22 + Since glibc 2.22 getaddrinfo() etc. are only declared for + POSIX.1-2001 or later. + +getcwd.3 + Michael Kerrisk + SEE ALSO: add pwd(1) + +opendir.3 + Michael Kerrisk + Help the reader by explicitly mentioning the use of readdir(3) + +perror.3 + Michael Kerrisk + Suggest use of strerror(3) in place of deprecated 'sys_errlist' + +posix_fallocate.3 + Jérémie Galarneau + ERRORS: add EINTR + The glibc implementation of posix_fallocate(), which calls + fallocate(), may be interrupted. The fallocate() emulation + also makes use of pread()/pwrite(), which may also be + interrupted. + +posix_memalign.3 + Michael Kerrisk [Eric Blake] + Note posix_memalign()'s treatment of 'memptr' on error + +pthread_setaffinity_np.3 + Michael Kerrisk + SEE ALSO: add CPU_SET(3) + +queue.3 + Dr. Tobias Quathamer + Remove double CONFORMING TO section + +rcmd.3 + Nikola Forró + Add missing condition concerning .rhosts file + The list of conditions determining if iruserok() and ruserok() + functions automatically fail is incomplete. According to glibc + source code, the functions also fail if the .rhosts file + is hard linked anywhere. + +setbuf.3 + Michael Kerrisk + SEE ALSO: add stdbuf(1) + +setjmp.3 + Michael Kerrisk + Rewrite and merge longjmp()/siglongjmp() discussion into this page + The discussion of nonlocal gotos is much easier to read if + setjmp() and longjmp() are discussed in the same page. While + we're at it, rework almost the entire text and add several + more details. + Michael Kerrisk + Note the interactions of longjmp() and non-async-signal-safe functions + POSIX.1-2008 TC2 adds explicit text on this point. + See http://austingroupbugs.net/view.php?id=516#c1195 + Michael Kerrisk + Explain why nonlocal gotos make code harder to maintain + Michael Kerrisk + Reword warning on longjmp() to function that has already returned + Michael Kerrisk + Remove reference to obsolete _XOPEN_SOURCE_EXTENDED + +sleep.3 + Michael Kerrisk + SEE ALSO: add sleep(1) + +strftime.3 + Michael Kerrisk [Jeremy Harris] + Note which 'tm' fields are used to calculate each output string + See https://bugzilla.redhat.com/show_bug.cgi?id=1162218 + +strlen.3 + Michael Kerrisk [Alan Aversa] + CONFORMING TO: add C11 + +system.3 + Michael Kerrisk + SEE ALSO: add execve(2) + +termios.3 + Dr. Tobias Quathamer + Document line length in canonical mode + See https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/tty/n_tty.c#n1673 + See https://bugs.debian.org/797479 + Michael Kerrisk + SEE ALSO: add tty(1) + Michael Kerrisk [Peter Hurley] + Further improvements to recent tweaks of canonical mode 4096 char limit + +timegm.3 + Michael Kerrisk [Stephen Hurd, Mats Wichmann] + Remove sample implementation of timegm() + Stephen and Mats both question the wisdom of showing a portable + *non-thread-safe* implementation of timegm(), and I find it + hard to disagree. So, remove this code. + + See https://bugzilla.kernel.org/show_bug.cgi?id=103701 + Michael Kerrisk + Expand DESCRIPTION a little + +st4.4 + Dr. Tobias Quathamer + Remove spurious copyright section + +tty_ioctl.4 + Michael Kerrisk + SEE ALSO: add ldattach(1) + +elf.5 + Michael Kerrisk [Gabriel Corona, Mike Frysinger] + Fix description of STV_PROTECTED + Michael Kerrisk + Improve description of STV_DEFAULT + Michael Kerrisk + Improve description of STV_HIDDEN + Chris Pick + Remove erroneous, duplicate SHN_* section + Michael Kerrisk [Chris Pick] + Reword discussion of range values a little + +gai.conf.5 + Michael Kerrisk + Add VERSIONS section + +group.5 + Michael Kerrisk + SEE ALSO: add groups(2) + SEE ALSO: add gpasswd(1) + SEE ALSO: add sg(1) + SE ALSO: add gshadow(5) + SEE ALSO: add chgrp(1) + +locale.5 + Marko Myllynen [Mike Frysinger] + tel + fax are deprecated + +nsswitch.conf.5 + Nikola Forró + Update NSS compatibility mode description + +utmp.5 + Michael Kerrisk + SEE ALSO: add lslogins(1) + +aio.7 + Andreas Gruenbacher + Improve example + When aio_sigevent.sigev_notify is set to SIGEV_SIGNAL, signal + handlers called for asynchronous I/O operations will have + si->si_code set to SI_ASYNCIO. Check to make sure that + si->si_value.sival_ptr is defined. + +capabilities.7 + Michael Kerrisk + Explain safety check for capability-dumb binaries + Michael Kerrisk + SEE ALSO: add sg(1), su(1) + SEE ALSO: add id(1), group(5), passwd(5) + +credentials.7 + Michael Kerrisk + SEE ALSO: add groups(2) + +environ.7 + Michael Kerrisk + Describe the Bourne "NAME=value command" syntax + Michael Kerrisk + Add some details describing hos shell's environment is initialized + Michael Kerrisk + Note that child of fork(2) inherits copy of parent's environment + Michael Kerrisk + SEE ALSO: add pam_env(3) + +epoll.7 + Michael Kerrisk + Mention that epoll info is available via /proc/PID/fdinfo + +fanotify.7 + Michael Kerrisk + Refer reader to proc(5) for info on /proc/PID/fdinfo fanotify entries + + +feature_test_macros.7 + Michael Kerrisk + Add a summary of some FTM key points + Michael Kerrisk + Give an early hint about some macros being defined by default + Michael Kerrisk + Clarify relation between _XOPEN_SOURCE >=500 and _XOPEN_SOURCE_EXTENDED + Emphasize that defining _XOPEN_SOURCE >=500 produces same + effects as defining _XOPEN_SOURCE_EXTENDED. + Michael Kerrisk + Note that man pages don't mention _XOPEN_SOURCE_EXTENDED + As per previous commit, mention of _XOPEN_SOURCE_EXTENDED + has generally been removed from the man pages. + Michael Kerrisk + Note effects of "cc -std=c99" and "cc -std=c11" + Michael Kerrisk + Clarify some _ISOC99_SOURCE / _DEFAULT_SOURCE details + Michael Kerrisk + Clarify that _XOPEN_SOURCE_EXTENDED is obsolete + Since SUSv2, _XOPEN_SOURCE_EXTENDED is no longer specified + in the standard. + +inotify.7 + Michael Kerrisk + Refer reader to proc(5) for info on /proc/PID/fdinfo inotify entries + +ip.7 + Eric Dumazet + Document IP_BIND_ADDRESS_NO_PORT socket option + +mq_overview.7 + Michael Kerrisk + Note that the close-on-exec flag is automatically set on MQ descriptors + +namespaces.7 + Michael Kerrisk + SEE ALSO: add lsns(1) + lsns(1) was recently added in util-linux, probably to appear + in next release (2.28?). + +pipe.7 + Michael Kerrisk [Jason Vas Dias] + Clarify that I/O signalling requires use of both F_SETOWN and O_ASYNC + Michael Kerrisk + SEE ALSO: add mkfifo(1) + +signal.7 + Michael Kerrisk + Note the interactions of longjmp() and non-async-signal-safe functions + See http://austingroupbugs.net/view.php?id=516#c1195. + +socket.7 + Michael Kerrisk + SEE ALSO: add pcap(3) + SEE ALSO: add wireshark(1) and tcpdump(8) + +standards.7 + Michael Kerrisk + Add POSIX.1-2008 TC2 (POSIX.1-2016) + +svipc.7 + Michael Kerrisk + Tweak description of 'sempid' + Michael Kerrisk + SEE ALSO: add lsipc(1) + +symlink.7 + Michael Kerrisk [Zefram] + Some "magic" symlinks have permissions other than 0777 + See https://bugs.debian.org/743525 + +time.7 + Michael Kerrisk + SEE ALSO: add timeout(1) + SEE ALSO: add ntp_adjtime(3) and ntp_gettime(3) + +unicode.7 + Dr. Tobias Quathamer + Document private use areas + See https://bugs.debian.org/285444 + +unix.7 + Heinrich Schuchardt + Add example + A complete example demonstrating the usage of sockets for local + interprocess communication is added. + Michael Kerrisk + Introduce term "sequenced-packet" for SOCK_SEQPACKET + Michael Kerrisk + Some wording improvements + + +==================== Changes in man-pages-4.06 ==================== + +Released: 2016-05-09, Oslo + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alexander Miller +Alon Bar-Lev +Benjamin Poirier +Christoph Hellwig +Colin Ian King +Dr. Tobias Quathamer +Ed Avis +Georg Sauthoff +Heinrich Schuchardt +Jakub Wilk +Jordan Birks +Marko Myllynen +Michael Kerrisk +Mike Frysinger +Nikola Forró +Rasmus Villemoes +Serge E. Hallyn +Serge Hallyn +Valery Reznic +Zubair Lutfullah Kakakhel + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +cgroups.7 + Serge Hallyn, Michael Kerrisk + New page documenting cgroups + +cgroup_namespaces.7 + Michael Kerrisk [Serge Hallyn] + New page describing cgroup namespaces + + +Newly documented interfaces in existing pages +--------------------------------------------- + +clone.2 + Michael Kerrisk + Document CLONE_NEWCGROUP + +readv.2 + Christoph Hellwig + Document preadv2() and pwritev2() +setns.2 + Michael Kerrisk + Document CLONE_NEWCGROUP + +unshare.2 + Michael Kerrisk + Document CLONE_NEWCGROUP + + +Changes to individual pages +--------------------------- + +clock_getres.2 + Michael Kerrisk [Rasmus Villemoes] + Note that coarse clocks need architecture and VDSO support + +clone.2 +fork.2 + Nikola Forró + Document ERESTARTNOINTR error code + +clone.2 + Michael Kerrisk [Colin Ian King] + ERRORS: add EINVAL for improperly aligned 'child_stack' value + +execve.2 + Michael Kerrisk [Valery Reznic] + Since Linux 2.6.28, recursive script interpretation is supported + +fcntl.2 + Michael Kerrisk + Note that mandatory locking is now governed by a configuration option + +fsync.2 + Michael Kerrisk [Georg Sauthoff] + Give some examples of files where sync can fail with EINVAL + +getrlimit.2 + Michael Kerrisk + SEE ALSO: add cgroups(7) + +ioctl_fat.2 + Heinrich Schuchardt + Use %04x to print volume ID + Leading zeroes should be used when display a FAT volume ID. + +ioprio_set.2 + Michael Kerrisk + SEE ALSO: add cgroups(7) + +lseek.2 + Michael Kerrisk + Note that 'off_t' is an integer data type defined by POSIX + +memfd_create.2 + Michael Kerrisk + Note that memfd_create() does not have a glibc wrapper + +mount.2 + Michael Kerrisk + MS_MANDLOCK requires CAP_SYS_ADMIN (since Linux 4.5) + +quotactl.2 + Michael Kerrisk + Document Q_GETNEXTQUOTA and Q_XGETNEXTQUOTA + Michael Kerrisk + Rework/reorder ERRORS list + Make into a single alphabetically ordered list + Michael Kerrisk + Note kernel version that removed Q_GETSTATS + Michael Kerrisk + Add kernel version for G_GETINFO, Q_SETINFO, and Q_GETFMT + +readv.2 + Michael Kerrisk + Clarify that 'size_t' and 'ssize_t' are integer types specified in POSIX + +semctl.2 + Michael Kerrisk + From kernel 4.6, Linux now updates 'sempid' on SETALL operations + +sigaction.2 + Michael Kerrisk + Document SEGV_BNDERR + Michael Kerrisk + Document SEGV_PKUERR + +syscalls.2 + Michael Kerrisk + Add preadv2() and pwritev2() + +write.2 + Michael Kerrisk + Clarify that 'size_t' and 'ssize_t' are integer types specified in POSIX + +makedev.3 + Mike Frysinger + Use in SYNOPSIS + Defining these functions via causes problems for + some folk. As noted by Zack Wein: + + libstdc++ force-enables _GNU_SOURCE, which means people + writing in C++ _can't_ avoid these nonstandard macros by + using a strict conformance mode. + + Since glibc has basically always used , + update the docs to have people include that instead. + Michael Kerrisk + NOTES: mention that may also define these macros + +popen.3 + Nikola Forró + RETURN VALUE: describe successful case + Reference: + http://pubs.opengroup.org/onlinepubs/9699919799/functions/popen.html + http://pubs.opengroup.org/onlinepubs/9699919799/functions/pclose.html + +strtod.3 + Michael Kerrisk [Ed Avis] + Improve a detail in RETURN VALUE + +core.5 + Michael Kerrisk + Document /proc/sys/kernel/core_pipe_limit + +locale.5 + Marko Myllynen + Adjust LC_IDENTIFICATION / abbreviation + Tiny tweak to locale.5 based on the on ISO/IEC TR 14652: + + http://www.open-std.org/jtc1/SC22/WG20/docs/n972-14652ft.pdf + Marko Myllynen + Update LC_ADDRESS after glibc change + This patch updates locale.5 to match the recent glibc change + in commit a837257199ffab76237385b830cc7b6179fc2f18 + Marko Myllynen + Complete LC_COLLATE + Here's the first attempt to (almost) complete the locale.5 manual + page by documenting all (but perhaps one) of the missing + LC_COLLATE keywords. + Mike Frysinger + country_car: Add a better description + + +nsswitch.conf.5 + Marko Myllynen + Document group merging + Document the recently merged glibc group merge support. + Glibc commit ced8f8933673f4efda1d666d26a1a949602035ed + https://sourceware.org/glibc/wiki/Proposals/GroupMerging + +proc.5 + Michael Kerrisk + Move /proc/PID/cgroup discussion to cgroups(7) page + Michael Kerrisk + Add some background on why /proc/PID/mountinfo was added + Michael Kerrisk + Improve description of /proc/PID/mountinfo 'root' field + Michael Kerrisk + Add pointer to cgroups(7) for documentation of /proc/cgroups + Michael Kerrisk + Add reference to core(5) for info on /proc/sys/kernel/core_pipe_limit + +cpuset.7 + Michael Kerrisk + SEE ALSO: add cgroups(7) + +ip.7 + Benjamin Poirier + Fix incorrect sockopt name + "IP_LEAVE_GROUP" does not exist. It was perhaps a confusion with + MCAST_LEAVE_GROUP. Change the text to IP_DROP_MEMBERSHIP which has + the same function as MCAST_LEAVE_GROUP and is documented in the + ip.7 man page. + + Reference: + Linux kernel net/ipv4/ip_sockglue.c do_ip_setsockopt() + +namespaces.7 + Michael Kerrisk + SEE ALSO: add cgroups(7), cgroup_namespaces(7) + +vdso.7 + Zubair Lutfullah Kakakhel [Mike Frysinger] + Update for MIPS + Document the symbols exported by the MIPS VDSO. + VDSO support was added from kernel 4.4 onwards. + + See https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/log/arch/mips/vdso + Michael Kerrisk [Rasmus Villemoes] + The __kernel_clock_* interfaces don't support *_COARSE clocks on PowerPC + +ld.so.8 + Michael Kerrisk [Alon Bar-Lev] + Document use of $ORIGIN, $LIB, and $PLATFORM in environment variables + These strings are meaningful in LD_LIBRARY_PATH and LD_PRELOAD. + + +==================== Changes in man-pages-4.07 ==================== + +Released: 2016-07-17, Ulm + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alec Leamas +Andrey Vagin +Andy Lutomirski +Carsten Grohmann +Chris Gassib +Christoph Hellwig +Darren Hart +Darrick J. Wong +Élie Bouttier +Eric Biggers +Eric W. Biederman +Florian Weimer +Håkon Sandsmark +Iustin Pop +Jacob Willoughby +Jakub Wilk +James H Cownie +Jann Horn +John Wiersba +Jörn Engel +Josh Triplett +Kai Mäkisara +Kees Cook +Keno Fischer +Li Peng +Marko Kevac +Marko Myllynen +Michael Kerrisk +Michał Zegan +Miklos Szeredi +Mitch Walker +Neven Sajko +Nikos Mavrogiannopoulos +Omar Sandoval +Ori Avtalion +Rahul Bedarkar +Robin Kuzmin +Rob Landley +Shawn Landden +Stefan Puiu +Stephen Smalley +Szabolcs Nagy +Thomas Gleixner +Tobias Stoeckmann +Tom Callaway +Tom Gundersen +Vince Weaver +W. Trevor King +"Yuming Ma(马玉明)" + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +ioctl_fideduperange.2 + Darrick J. Wong [Christoph Hellwig, Michael Kerrisk] + New page documenting the FIDEDUPERANGE ioctl + Document the FIDEDUPERANGE ioctl, formerly known as + BTRFS_IOC_EXTENT_SAME. + +ioctl_ficlonerange.2 + Darrick J. Wong [Christoph Hellwig, Michael Kerrisk] + New page documenting FICLONE and FICLONERANGE ioctls + Document the FICLONE and FICLONERANGE ioctls, formerly known as + the BTRFS_IOC_CLONE and BTRFS_IOC_CLONE_RANGE ioctls. + +nextup.3 + Michael Kerrisk + New page documenting nextup(), nextdown(), and related functions + +mount_namespaces.7 + Michael Kerrisk [Michael Kerrisk] + New page describing mount namespaces + + +Newly documented interfaces in existing pages +--------------------------------------------- + +mount.2 + Michael Kerrisk + Document flags used to set propagation type + Document MS_SHARED, MS_PRIVATE, MS_SLAVE, and MS_UNBINDABLE. + Michael Kerrisk + Document the MS_REC flag + +ptrace.2 + Michael Kerrisk [Kees Cook, Jann Horn, Eric W. Biederman, Stephen Smalley] + Document ptrace access modes + +proc.5 + Michael Kerrisk + Document /proc/[pid]/timerslack_ns + Michael Kerrisk + Document /proc/PID/status 'Ngid' field + Michael Kerrisk + Document /proc/PID/status fields: 'NStgid', 'NSpid', 'NSpgid', 'NSsid' + Michael Kerrisk + Document /proc/PID/status 'Umask' field + + +New and changed links +--------------------- + +preadv2.2 +pwritev2.2 + Michael Kerrisk + New links to readv(2) + +nextdown.3 +nextdownf.3 +nextdownl.3 +nextupf.3 +nextupl.3 + Michael Kerrisk + New links to nextup(3) + + +Changes to individual pages +--------------------------- + +ldd.1 + Michael Kerrisk + Add a little more detail on why ldd is unsafe with untrusted executables + Michael Kerrisk + Add more detail on the output of ldd + +localedef.1 + Marko Myllynen + Drop --old-style description + The glibc upstream decided to drop localedef(1) --old-style + option [1] altogether, I think we can do the same with + localedef(1), the option hasn't done anything in over 16 + years and I doubt anyone uses it. + +add_key.2 + Mitch Walker + Empty payloads are not allowed in user-defined keys + +chroot.2 + Michael Kerrisk + SEE ALSO: add pivot_root(2) + +clone.2 + Michael Kerrisk + Add reference to mount_namespaces(7) under CLONE_NEWNS description + +fork.2 + Michael Kerrisk + Add ENOMEM error for PID namespace where "init" has died + +futex.2 + Michael Kerrisk + Correct an ENOSYS error description + Since Linux 4.5, FUTEX_CLOCK_REALTIME is allowed with FUTEX_WAIT. + Michael Kerrisk [Darren Hart] + Remove crufty text about FUTEX_WAIT_BITSET interpretation of timeout + Since Linux 4.5, FUTEX_WAIT also understands + FUTEX_CLOCK_REALTIME. + Michael Kerrisk [Thomas Gleixner] + Explain how to get equivalent of FUTEX_WAIT with an absolute timeout + Michael Kerrisk + Describe FUTEX_BITSET_MATCH_ANY + Describe FUTEX_BITSET_MATCH_ANY and FUTEX_WAIT and FUTEX_WAKE + equivalences. + Michael Kerrisk + Note that at least one bit must be set in mask for BITSET operations + At least one bit must be set in the 'val3' mask supplied for the + FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET operations. + Michael Kerrisk [Thomas Gleixner, Darren Hart] + Fix descriptions of various timeouts + Michael Kerrisk + Clarify clock default and choices for FUTEX_WAIT + +getitimer.2 + Michael Kerrisk + Substantial rewrites to various parts of the page + Michael Kerrisk [Tom Callaway] + Change license to note that page may be modified + The page as originally written carried text that said the page may + be freely distributed but made no statement about modification. + In the 20+ years since it was first written, the page has in fact + seen repeated, sometimes substantial, modifications, and only a + small portion of the original text remains. One could I suppose + rewrite the last few pieces that remain from the original, + but as the largest contributor to the pages existing text, + I'm just going to relicense it to explicitly note that + modification is permitted. (I presume the failure by the + original author to grant permission to modify was simply an + oversight; certainly, the large number of people who have + changed the page have taken that to be the case.) + + See also https://bugzilla.kernel.org/show_bug.cgi?id=118311 + +get_mempolicy.2 + Michael Kerrisk [Jörn Engel] + Correct rounding to 'maxnodes' (bits, not bytes) + Michael Kerrisk [Jörn Engel] + Fix prototype for get_mempolicy() + In numaif.h, 'addr' is typed as 'void *' + +getpriority.2 + Michael Kerrisk + Make discussion of RLIMIT_NICE more prominent + The discussion of RLIMIT_NICE was hidden under the EPERM error, + where it was difficult to find. Place some relevant text in + DESCRIPTION. + Michael Kerrisk + Note that getpriority()/setpriority deal with same attribute as nice(2) + Michael Kerrisk [Robin Kuzmin] + Clarify equivalence between lower nice value and higher priority + +get_robust_list.2 + Michael Kerrisk + get_robust_list() is governed by PTRACE_MODE_READ_REALCREDS + +ioctl.2 + Michael Kerrisk + SEE ALSO: add ioctl_fideduperange(2) and ioctl_ficlonerange(2) + +kcmp.2 + Michael Kerrisk + kcmp() is governed by PTRACE_MODE_READ_REALCREDS + Shawn Landden + Note about SECURITY_YAMA +kill.2 + Michael Kerrisk [John Wiersba] + Clarify the meaning if sig==0 + +lookup_dcookie.2 + Michael Kerrisk + SEE ALSO: add oprofile(1) + +mmap.2 + Michael Kerrisk [Rahul Bedarkar] + EXAMPLE: for completeness, add munmap() and close() calls + +mount.2 + Michael Kerrisk + Restructure discussion of 'mountflags' into functional groups + The existing text makes no differentiation between different + "classes" of mount flags. However, certain flags such as + MS_REMOUNT, MS_BIND, MS_MOVE, etc. determine the general + type of operation that mount() performs. Furthermore, the + choice of which class of operation to perform is performed in + a certain order, and that order is significant if multiple + flags are specified. Restructure and extend the text to + reflect these details. + Michael Kerrisk + Relocate text on multimounting and mount stacking to NOTES + The text was somewhat out of place in its previous location; + NOTES is a better location. + Michael Kerrisk + Remove version numbers attached to flags that are modifiable on remount + This information was simply bogus. Mea culpa. + Michael Kerrisk + Refer reader to mount_namespaces(7) for details on propagation types + Michael Kerrisk + SEE ALSO: s/namespaces(7)/mount_namespaces(7)/ + Omar Sandoval + MS_BIND still ignores mountflags + This is clear from the do_mount() function in the kernel as of v4.6. + Michael Kerrisk + Note the default treatment of ATIME flags during MS_REMOUNT + The behavior changed in Linux 3.17. + Michael Kerrisk + Clarify that MS_MOVE ignores remaining bits in 'mountflags' + Michael Kerrisk + Note kernel version that added MS_MOVE + Michael Kerrisk + MS_NOSUID also disables file capabilities + Michael Kerrisk + Relocate/demote/rework text on MS_MGC_VAL + The use of this constant has not been needed for 15 years now. + Michael Kerrisk + Clarify that 'source' and 'target' are pathnames, and can refer to files + Michael Kerrisk + Update example list of filesystem types + Put more modern examples in; remove many older examples. + Michael Kerrisk + MS_LAZYTIME and MS_RELATIME can be changed on remount + Michael Kerrisk + Explicitly note that MS_DIRSYNC setting cannot be changed on remount + Michael Kerrisk + Move text describing 'data' argument higher up in page + In preparation for other reworking. + Michael Kerrisk + Since Linux 2.6.26, bind mounts can be made read-only + +open.2 + Eric Biggers + Refer to correct functions in description of O_TMPFILE + +pciconfig_read.2 + Michael Kerrisk [Tom Callaway] + Change license to note that page may be modified + Niki Rahimi, the author of this page, has agreed that it's okay + to change the license to note that the page can be modified. + + See https://bugzilla.kernel.org/show_bug.cgi?id=118311 + +perf_event_open.2 + Michael Kerrisk + If pid > 0, the operation is governed by PTRACE_MODE_READ_REALCREDS + Jann Horn + Document new perf_event_paranoid default + Keno Fischer [Vince Weaver] + Add a note that dyn_size is omitted if size == 0 + The perf_output_sample_ustack in kernel/events/core.c only writes + a single 64 bit word if it can't dump the user registers. From the + current version of the man page, I would have expected two 64 bit + words (one for size, one for dyn_size). Change the man page to + make this behavior explicit. + +prctl.2 + Michael Kerrisk + Some wording improvements in timer slack description + Michael Kerrisk + Refer reader to discussion of /proc/[pid]/timerslack_ns + Under discussion of PR_SET_TIMERSLACK, refer the reader to + the /proc/[pid]/timerslack_ns file, documented in proc(5). + +process_vm_readv.2 + Michael Kerrisk + Rephrase permission rules in terms of a ptrace access mode check + +ptrace.2 + Michael Kerrisk [Jann Horn] + Update Yama ptrace_scope documentation + Reframe the discussion in terms of PTRACE_MODE_ATTACH checks, + and make a few other minor tweaks and additions. + Michael Kerrisk, Jann Horn + Note that user namespaces can be used to bypass Yama protections + Michael Kerrisk + Note that PTRACE_SEIZE is subject to a ptrace access mode check + Michael Kerrisk + Rephrase PTRACE_ATTACH permissions in terms of ptrace access mode check + +quotactl.2 + Michael Kerrisk [Jacob Willoughby] + 'dqb_curspace' is in bytes, not blocks + This error appears to have been injected into glibc + when copying some headers from BSD. + + See https://bugs.debian.org/825548 + +recv.2 + Michael Kerrisk [Tom Gundersen] + With pending 0-length datagram read() and recv() with flags == 0 differ + +setfsgid.2 +setfsuid.2 + Jann Horn [Michael Kerrisk] + Fix note about errors from the syscall wrapper + See sysdeps/unix/sysv/linux/i386/setfsuid.c in glibc-2.2.1. + (This code is not present in modern glibc anymore.) + Michael Kerrisk + Move glibc wrapper notes to "C library/kernel differences" subsection + +sysinfo.2 + Michael Kerrisk + Rewrite and update various pieces + +umask.2 + Michael Kerrisk + NOTES: Mention /proc/PID/status 'Umask' field + +umount.2 + Michael Kerrisk + SEE ALSO: add mount_namespaces(7) + +unshare.2 + Michael Kerrisk + Add reference to mount_namespaces(7) under CLONE_NEWNS description + +utimensat.2 + Michael Kerrisk [Rob Landley] + Note that the glibc wrapper disallows pathname==NULL + +wait.2 + Michael Kerrisk + Since Linux 4.7, __WALL is implied if child being ptraced + Michael Kerrisk + waitid() now (since Linux 4.7) also supports __WNOTHREAD/__WCLONE/__WALL + +assert.3 + Nikos Mavrogiannopoulos + Improved description + Removed text referring to text not being helpful to users. Provide + the error text instead to allow the reader to determine whether it + is helpful. Recommend against using NDEBUG for programs to + exhibit deterministic behavior. Moved description ahead of + recommendations. + Michael Kerrisk + Clarify details of message printed by assert() + +fmax.3 +fmin.3 + Michael Kerrisk + SEE ALSO: add fdim(3) + +getauxval.3 + Cownie, James H + Correct AT_HWCAP result description + +inet_pton.3 + Stefan Puiu + Mention byte order + +malloc_hook.3 + Michael Kerrisk + glibc 2.24 removes __malloc_initialize_hook + +memmem.3 + Michael Kerrisk [Shawn Landden] + Note that memmem() is present on some other systems + +mkdtemp.3 +mktemp.3 + Michael Kerrisk + SEE ALSO: add mktemp(1) + +printf.3 + Michael Kerrisk [Shawn Landden] + Note support in other C libraries for %m and %n + +strcasecmp.3 + Michael Kerrisk [Ori Avtalion] + Make details of strncasecmp() comparison clearer + +strcat.3 + Michael Kerrisk + Add a program that shows the performance characteristics of strcat() + In honor of Joel Spolksy's visit to Munich, let's start educating + Schlemiel The Painter. + +strtoul.3 + Michael Kerrisk + SEE ALSO: add a64l(3) + +strxfrm.3 + Michael Kerrisk [Florian Weimer] + Remove NOTES section + strxfrm() and strncpy() are not precisely equivalent in the + POSIX locale, so this NOTES section was not really correct. + + See https://bugzilla.kernel.org/show_bug.cgi?id=104221 + +console_codes.4 +console_ioctl.4 +tty.4 +vcs.4 +charsets.7 + Marko Myllynen + Remove console(4) references + 0f9e647 removed the obsolete console(4) page but we still have few + references to it. The patch below removes them or converts to refs + to console_ioctl(4) where appropriate. + +console_ioctl.4 + Michael Kerrisk [Chris Gassib] + The argument to KDGETMODE is an 'int' + +lirc.4 + Alec Leamas + Update after upstreamed lirc.h, bugfixes. + +st.4 + Kai Mäkisara + Fix description of read() when block is larger than request + Kai Mäkisara + Update MTMKPART for kernels >= 4.6 + Update the description of the MTMKPART operation of MTIOCTOP to match + the changes in kernel version 4.6. + +charmap.5 + Marko Myllynen + Clarify keyword syntax + Updates charmap(5) to match the syntax all the glibc + charmap files are using currently. + +elf.5 + Michael Kerrisk + SEE ALSO: add readelf(1) + +locale.5 + Marko Myllynen + Document missing keywords, minor updates + Marko Myllynen + Clarify keyword syntax + Marko Myllynen + Adjust conformance + +proc.5 +namespaces.7 + Michael Kerrisk + Move /proc/PID/mounts information to proc(5) + There was partial duplication, and some extra information + in namespaces(7). Move everything to proc(5). + +proc.5 + Michael Kerrisk + /proc/PID/fd/* are governed by PTRACE_MODE_READ_FSCREDS + Permission to dereference/readlink /proc/PID/fd/* symlinks is + governed by a PTRACE_MODE_READ_FSCREDS ptrace access mode check. + Michael Kerrisk + /proc/PID/timerslack_ns is governed by PTRACE_MODE_ATTACH_FSCREDS + Permission to access /proc/PID/timerslack_ns is governed by + a PTRACE_MODE_ATTACH_FSCREDS ptrace access mode check. + Michael Kerrisk + Document /proc/PID/{maps,mem,pagemap} access mode checks + Permission to access /proc/PID/{maps,pagemap} is governed by a + PTRACE_MODE_READ_FSCREDS ptrace access mode check. + + Permission to access /proc/PID/mem is governed by a + PTRACE_MODE_ATTACH_FSCREDS ptrace access mode check. + Michael Kerrisk + Note /proc/PID/stat fields that are governed by PTRACE_MODE_READ_FSCREDS + Michael Kerrisk + /proc/PID/{cwd,exe,root} are governed by PTRACE_MODE_READ_FSCREDS + Permission to dereference/readlink /proc/PID/{cwd,exe,root} is + governed by a PTRACE_MODE_READ_FSCREDS ptrace access mode check. + Michael Kerrisk + /proc/PID/io is governed by PTRACE_MODE_READ_FSCREDS + Permission to access /proc/PID/io is governed by + a PTRACE_MODE_READ_FSCREDS ptrace access mode check. + Michael Kerrisk + /proc/PID/{personality,stack,syscall} are governed by PTRACE_MODE_ATTACH_FSCREDS + Permission to access /proc/PID/{personality,stack,syscall} is + governed by a PTRACE_MODE_ATTACH_FSCREDS ptrace access mode check. + Michael Kerrisk + /proc/PID/{auxv,environ,wchan} are governed by PTRACE_MODE_READ_FSCREDS + Permission to access /proc/PID/{auxv,environ,wchan} is governed by + a PTRACE_MODE_READ_FSCREDS ptrace access mode check. + Michael Kerrisk + Move shared subtree /proc/PID/mountinfo fields to mount_namespaces(7) + Move information on shared subtree fields in /proc/PID/mountinfo + to mount_namespaces(7). + Michael Kerrisk ["Yuming Ma(马玉明)"] + Note that /proc/net is now virtualized per network namespace + Michael Kerrisk + Add references to mount_namespaces(7) + +repertoiremap.5 + Marko Myllynen + Clarify keyword syntax + +utmp.5 + Michael Kerrisk + SEE ALSO: add logname(1) + +capabilities.7 + Michael Kerrisk [Andy Lutomirski] + Note on SECURE_NO_CAP_AMBIENT_RAISE for capabilities-only environment + Michael Kerrisk + Add a detail on use of securebits + +cgroup_namespaces.7 + Michael Kerrisk + SEE ALSO: add namespaces(7) + +cgroups.7 + Michael Kerrisk + ERRORS: add mount(2) EBUSY error + +cp1251.7 +cp1252.7 +iso_8859-1.7 +iso_8859-15.7 +iso_8859-5.7 +koi8-r.7 +koi8-u.7 + Marko Myllynen + Add some charset references + Add some references to related charsets here and there. + +credentials.7 + Michael Kerrisk + SEE ALSO: add runuser(1) + SEE ALSO: add newgrp(1) + SEE ALSO: add sudo(8) + +feature_test_macros.7 + Michael Kerrisk + Emphasize that applications should not directly include + +man-pages.7 + Michael Kerrisk + Clarify which sections man-pages provides man pages for + Michael Kerrisk [Josh Triplett] + Add a few more details on formatting conventions + Add some more details for Section 1 and 8 formatting. + Separate out formatting discussion into commands, functions, + and "general". + +namespaces.7 + Michael Kerrisk + /proc/PID/ns/* are governed by PTRACE_MODE_READ_FSCREDS + Permission to dereference/readlink /proc/PID/ns/* symlinks is + governed by a PTRACE_MODE_READ_FSCREDS ptrace access mode check. + Michael Kerrisk + Nowadays, file changes in /proc/PID/mounts are notified differently + Exceptional condition for select(), (E)POLLPRI for (e)poll + Michael Kerrisk + Remove /proc/PID/mountstats description + This is a duplicate of information in proc(5). + Michael Kerrisk + Refer to new mount_namespaces(7) for information on mount namespaces + +netlink.7 + Andrey Vagin + Describe netlink socket options + Michael Kerrisk + Rework version information + (No changes in technical details.) + +pid_namespaces.7 + Michael Kerrisk + SEE ALSO: add namespaces(7) + +unix.7 + Michael Kerrisk + Move discussion on pathname socket permissions to DESCRIPTION + Michael Kerrisk + Expand discussion of socket permissions + Michael Kerrisk + Fix statement about permissions needed to connect to a UNIX domain socket + Read permission is not required (verified by experiment). + Michael Kerrisk + Clarify ownership and permissions assigned during socket creation + Michael Kerrisk [Carsten Grohmann] + Update text on socket permissions on other systems + At least some of the modern BSDs seem to check for write + permission on a socket. (I tested OpenBSD 5.9.) On Solaris 10, + some light testing suggested that write permission is still + not checked on that system. + Michael Kerrisk + Note that umask / permissions have no effect for abstract sockets + W. Trevor King + Fix example code: 'ret' check after accept populates 'data_socket' + Michael Kerrisk + Move some abstract socket details to a separate subsection + Michael Kerrisk + Note that abstract sockets automatically disappear when FDs are closed + +user_namespaces.7 + Michael Kerrisk [Michał Zegan] + Clarify meaning of privilege in a user namespace + Having privilege in a user NS only allows privileged + operations on resources governed by that user NS. Many + privileged operations relate to resources that have no + association with any namespace type, and only processes + with privilege in the initial user NS can perform those + operations. + + See https://bugzilla.kernel.org/show_bug.cgi?id=120671 + Michael Kerrisk [Michał Zegan] + List the mount operations permitted by CAP_SYS_ADMIN + List the mount operations permitted by CAP_SYS_ADMIN in a + noninitial userns. + + See https://bugzilla.kernel.org/show_bug.cgi?id=120671 + Michael Kerrisk [Michał Zegan] + CAP_SYS_ADMIN allows mounting cgroup filesystems + See https://bugzilla.kernel.org/show_bug.cgi?id=120671 + Michael Kerrisk + Clarify details of CAP_SYS_ADMIN and cgroup v1 mounts + With respect to cgroups version 1, CAP_SYS_ADMIN in the user + namespace allows only *named* hierarchies to be mounted (and + not hierarchies that have a controller). + Michael Kerrisk + Clarify CAP_SYS_ADMIN details for mounting FS_USERNS_MOUNT filesystems + Michael Kerrisk + Correct user namespace rules for mounting /proc + Michael Kerrisk + Describe a concrete example of capability checking + Add a concrete example of how the kernel checks capabilities in + an associated user namespace when a process attempts a privileged + operation. + Michael Kerrisk + Correct kernel version where XFS added support for user namespaces + Linux 3.12, not 3.11. + Michael Kerrisk + SEE ALSO: add ptrace(2) + SEE ALSO: add cgroup_namespaces(7) + +utf-8.7: + Shawn Landden + Include RFC 3629 and clarify endianness which is left ambiguous + The endianness is suggested by the order the bytes are displayed, + but the text is ambiguous. + + +==================== Changes in man-pages-4.08 ==================== + +Released: 2016-10-08, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Arnaud Gaillard +Bill Pemberton +Carlos O'Donell +Christoph Hellwig +David Turner +Dr. Tobias Quathamer +Elliott Hughes +Eugene Syromyatnikov +Heinrich Schuchardt +Hu Keping +Igor Liferenko +Ivan Kharpalev +Jakub Wilk +Jann Horn +Josh Triplett +Keno Fischer +Laurent Georget +Local Lembke +Mats Wichmann +Michael Kerrisk +Mike Crowe +Mike Frysinger +Namhyung Kim +Nikola Forró +Patrick McLean +Peter Wu +Petr Cermak +Quentin Rameau +Ray Bellis +Rich Felker +Ruben Kerkhof +Sam Varshavchik +Sebastian Andrzej Siewior +Siward de Groot +Sloane Bernstein +Stefan Tauner +Tim Savannah +Ursache Vladimir +Zefram +王守堰 + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +quotactl.2 + Eugene Syromyatnikov [Michael Kerrisk] + Updated information regarding disk quota flags + Added information regarding DQF_SYS_FILE flag; updated definition + of V1_DQF_RSQUASH, which has been defined privately and defined + publicly as DQF_ROOT_SQUASH. + Eugene Syromyatnikov + Updated information regarding XFS-specific quotactl subcommands + Added information regarding structure definitions used for + XFS-specific subcommands, updated flag constants, added + information regarding ignored syscall arguments, added notes on + usage of kernel UAPI header. + Eugene Syromyatnikov + Additions regarding project quotas + Added information regarding presence of project quotas. + +bswap.3 + Michael Kerrisk + New page documenting bswap_16(), bswap_32(), and bswap_64() + +cgroups.7 + Michael Kerrisk + Substantial rewrites, additions, and corrections. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +readv.2 + Michael Kerrisk + Document the pwritev2() RWF_SYNC and RWF_DSYNC flags + +proc.5 + Michael Kerrisk + Document /proc/PID/seccomp + Jann Horn + Document /proc/[pid]/task/[tid]/children + Document the /proc/[pid]/task/[tid]/children interface from + CRIU, and more importantly, document why it's usually not + a good interface. + + +New and changed links +--------------------- + +bswap_16.3 +bswap_32.3 +bswap_64.3 + New link to new bswap.3 + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Fix section ordering + Various pages had sections in an order different from + that prescribed in man-pages(7). + +Various pages + Michael Kerrisk [Mike Frysinger] + Consistently use /proc/[pid] (not /proc/PID) + +Various pages + Michael Kerrisk + Fix order of SEE ALSO entries + Entries should be ordered first by section, and then alphabetically + within the section. + +Various pages + Michael Kerrisk + Order ERRORS alphabetically + +Various pages + Michael Kerrisk + Remove section number from page self reference + Fix places where pages refer to the function that they describe + and include a section number in that reference. Such references + cause some HTML-rendering tools to create self-references in the + page. + +A few pages + Michael Kerrisk + Eliminate groff "cannot adjust line" warnings + + +Changes to individual pages +--------------------------- + +pldd.1 + Michael Kerrisk [Carlos O'Donell] + Note gdb(1) command that can be used as a replacement for pldd + Taken from Carlos O'Donnell's suggestion in + https://sourceware.org/bugzilla/show_bug.cgi?id=18035#c2 + Michael Kerrisk + BUGS: pldd has not worked since glibc 2.19 + +accept.2 + Michael Kerrisk + Mention epoll(7) alongside poll()/select() + Michael Kerrisk + Demote discussion of DECNet to NOTES + DECNet ceased to be important long ago... + +adjtimex.2 + Nikola Forró + Fix kernel version references + +chroot.2 + Michael Kerrisk + Note user namespace requirements for CAP_SYS_CHROOT + +clone.2 + Keno Fischer [Josh Triplett] + Adjust syscall prototype and expand CLONE_SETTLS description + Michael Kerrisk [Josh Triplett, Josh Triplett] + Document raw syscall interfaces on various other architectures + Michael Kerrisk + Change types for 'ptid' and 'ctid' in syscall prototypes + These types changed from 'void *' to 'int *' back in Linux 3.8. + Michael Kerrisk + EINVAL is generated by glibc wrapper for NULL 'fn' or 'child_stack' + Clarify that this error is produced by the wrapper function, not + the underlying system call. In particular, the point is that the + raw system call can accommodate a NULL pointer for 'child_stack'. + Michael Kerrisk [Elliott Hughes] + Make the implications of CLONE_FILES more explicit + If CLONE_FILES is not set, the duplicated FDs nevertheless share + file offset and status flags via the open file description. + Michael Kerrisk + Mention kcmp() under notes + +close.2 + Michael Kerrisk + Add mention of the close-on-exec flag + Michael Kerrisk + Clarify discussion noting that close() does not flush buffer cache + +epoll_wait.2 + Mike Crowe + Clarify that the timeout is measured against CLOCK_MONOTONIC + +execve.2 + Michael Kerrisk + Mention use of 'environ' to access environment list + Michael Kerrisk + Note that real UID, real GID, and supplementary GIDs are unchanged + +fanotify_init.2 + Heinrich Schuchardt + Update BUGS information + +fcntl.2 + Michael Kerrisk + Note an important detail of F_SETOWN permission rules for signals + F_SETOWN records the caller's credentials at the time of + the fcntl() call, and it is these saved credentials that + are used for subsequent permission checks. + Michael Kerrisk + Make the description of the effect of close-on-exec a little clearer + Michael Kerrisk + Clarify that F_GETFD and F_GETFL return flags via the function result + +fork.2 + Michael Kerrisk + PID of new process also does not match any existing session ID + +fsync.2 + Michael Kerrisk + SEE ALSO: add pwritev(2) + Since Linux 4.7, pwritev() has flags related to I/O + integrity completion. + +getdomainname.2 + Michael Kerrisk + Note user namespace requirements for CAP_SYS_ADMIN + +getgroups.2 + Michael Kerrisk + Note user namespace requirements for CAP_SETGID + +gethostname.2 + Michael Kerrisk + Note user namespace requirements for CAP_SYS_ADMIN + +getrlimit.2 + Michael Kerrisk + Note user namespace semantics for CAP_SYS_RESOURCE + +getsid.2 + Michael Kerrisk + Rework description to be somewhat clearer + Michael Kerrisk + Correct the definition of "session ID" + +getunwind.2 + Michael Kerrisk + Simplify text referring to vdso(7) + The detail given here is redundant, since this info is also + in vdso(7). + +kcmp.2 + Michael Kerrisk + Add an example program + +kill.2 + Michael Kerrisk + Note the user namespace requirement for CAP_KILL + +killpg.2 + Michael Kerrisk + Refer reader to kill(2) for signal permission rules + +mlock.2 + Sebastian Andrzej Siewior + Document that fork() after mlock() may be a bad idea in a RT process + +mmap.2 + Jann Horn + Describe treatment of 'offset' for MAP_ANONYMOUS + Michael Kerrisk [Siward de Groot] + Small improvement to description of MAP_SHARED + See https://sourceware.org/bugzilla/show_bug.cgi?id=6887 + +msgctl.2 +msgget.2 +msgop.2 +semctl.2 +semget.2 +semop.2 +shmctl.2 +shmget.2 +shmop.2 + Michael Kerrisk + Note the user namespace requirements for CAP_IPC_OWNER + +open.2 + Michael Kerrisk + Clarify user namespace capability requirements for O_NOATIME + Michael Kerrisk + NOTES: kcmp() can be used to test if two FDs refer to the same OFD + Michael Kerrisk + F2FS support for O_TMPFILE was added in Linux 3.16 + Michael Kerrisk + Clarify the rules about how the group ID of a new file is determined + +prctl.2 + Michael Kerrisk + Refer to proc(5) for effects of dumpability on ownership of /proc/PID/* + Michael Kerrisk + ERRORS: Add EACCES error for PR_SET_SECCOMP-SECCOMP_MODE_FILTER + Michael Kerrisk + Simplify list of cases where "dumpable" attribute is reset + Michael Kerrisk + Note user namespace requirements for PR_CAPBSET_DROP CAP_SETPCAP + +readlink.2 + Michael Kerrisk [Ursache Vladimir] + Make example program handle links that report a size of zero + Some "magic" symlinks created by the kernel (e.g., those under + /proc and /sys) report 'st_size' as zero. Modify the example + program to handle that possibility. + Michael Kerrisk + Emphasize that truncation of returned buffer generates no error + +readv.2 + Michael Kerrisk [Christoph Hellwig] + Clarify that RWF_DSYNC and RWF_SYNC apply only to data being written + Michael Kerrisk + Add preadv2() and pwritev2() to NAME line + +reboot.2 + Michael Kerrisk + Note user namespace requirements around CAP_SYS_BOOT + +rename.2 + Michael Kerrisk [Tim Savannah] + Clarify that ERRORS may cause rename to fail (not to be nonatomic) + +sched_setaffinity.2 + Michael Kerrisk + Note user namespace requirements for CAP_SYS_NICE + +seccomp.2 + Michael Kerrisk + CAP_SYS_ADMIN is required only in caller's user namespace + +select_tut.2 + Peter Wu + Fix various issues in example program + +seteuid.2 + Michael Kerrisk + Note user namespace requirements for CAP_SETUID and CAP_SETGID + +setgid.2 + Michael Kerrisk + Note user namespace requirements for CAP_SETGID + +setpgid.2 + Michael Kerrisk + Add a reference to credentials(7) + +setpgid.2 +setsid.2 + Michael Kerrisk + Relocate some text on sessions and sessions leaders + Some text that was in setpgid(2) is better placed in setsid(2). + +setresuid.2 + Michael Kerrisk + Note user namespace requirements for CAP_SETUID + +setreuid.2 + Michael Kerrisk + Note user namespace requirements for CAP_SETUID and CAP_SETGID + +setsid.2 + Michael Kerrisk + Refer to credentials(7) for details for details on controlling terminal + Refer to credentials(7) for details of how a session obtains + a controlling terminal. + +set_thread_area.2 + Michael Kerrisk + Add get_thread_area() to NAME + +setuid.2 + Michael Kerrisk + Note user namespace requirements for CAP_SETUID + +sigprocmask.2 + Keno Fischer + Expand/clarify libc/kernel sigset_t difference + +stat.2 + Michael Kerrisk [Ursache Vladimir, Mats Wichmann] + Improve discussion of 'st_size' for /proc and /sys files + Michael Kerrisk + _BSD_SOURCE and _SVID_SOURCE no longer expose nanosecond timestamps + +umask.2 + Michael Kerrisk + Provide a rationale for the existence of /proc/PID/status 'Umask' field + +wait.2 + Michael Kerrisk + Remove erroneous statement that waitpid() is implemented via wait4() + There is a fallback to wait4(), but only if the kernel does + not provide a waitpid() system call. + +bindresvport.3 +rcmd.3 +ip.7 + Michael Kerrisk + Note user namespace requirements for CAP_NET_BIND_SERVICE + +byteorder.3 + Michael Kerrisk + SEE ALSO: add bswap(3) + +dlopen.3 + Michael Kerrisk + dlmopen() is still broken in glibc 2.24 + +endian.3 + Michael Kerrisk + SEE ALSO: add bswap(3) + +ffs.3 + Michael Kerrisk [Stefan Tauner] + Correct feature test macro requirements + +fmemopen.3 + Michael Kerrisk [Rich Felker] + Remove bogus suggestion to use setbuffer() + +getlogin.3 + Michael Kerrisk + Update feature test macro requirements for cuserid() + +getumask.3 + Michael Kerrisk + Note that getumask() is still unavailable in glibc 2.24 + Michael Kerrisk + Point to umask(2) for a thread-safe way to discover process's umask + +mkstemp.3 + Quentin Rameau + Fix _POSIX_C_SOURCE value for mkstemp() + The correct _POSIX_C_SOURCE value has always been 200809L, + not 200112L. + +pthread_join.3 + Michael Kerrisk [Mats Wichmann] + Note that the caller might do clean up after joining with a thread + Michael Kerrisk [王守堰] + Clarify use of 'retval' pointer + +resolver.3 + Ray Bellis + Correct arguments to res_ninit(res_state statep) + +strverscmp.3 + Michael Kerrisk + Add an example program + +wcstombs.3 + Michael Kerrisk [Igor Liferenko] + wcsrtombs() does not provide thread-safe interface to same functionality + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=741360 + +core.5 + Mike Frysinger [Michael Kerrisk] + Add more details for output paths and the crash handler + People sometimes assume that the crash handler runs in the same + context as the crashing process. They would be incorrect :). + +proc.5 + Mike Frysinger + Clarify the root symlink and mount namespaces + If the target process is in a different mount namespace, the root + symlink actually shows that view of the filesystem. + Michael Kerrisk [Mike Frysinger] + Expand discussion of /proc/[pid]/root + Add a shell example showing that /proc/[pid]/root is more + than a symlink. Based on an example provided by Mike Frysinger + in an earlier commit message. + Michael Kerrisk + Explain rules determining ownership of /proc/PID/* files + Describe the effect of the "dumpable" attribute on ownership + of /proc/PID files. + Michael Kerrisk + Note effect of 'suid_dumpable' on ownership of /proc/PID files + Michael Kerrisk + Refer to ptrace(2) for info on effect of suid_dumpable on ptraceability + Michael Kerrisk + Add reference to core(5) in discussion of 'suid_dumpable' + Michael Kerrisk + Note that 'suid_dumpable' mode 1 is insecure + Michael Kerrisk + Document /proc/meminfo '+ShmemHugePages' and 'ShmemPmdMapped' fields + Michael Kerrisk + Document /proc/PID/status 'RssAnon', 'RssFile', and 'RssShmem' fields + Michael Kerrisk + Document /proc/PID/status 'HugetlbPages' field + Michael Kerrisk [Zefram] + Clarify that /proc/PID/statm 'shared' field counts *resident* pages + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=741360 + Michael Kerrisk + Add reference to umask(2) in discussion of /proc/PID/status 'Umask' + Michael Kerrisk + Clarify user namespace requirements for /proc/sys/fs/protected_hardlinks + Michael Kerrisk + Note changes to config option governing /proc/[pid]/task/[tid]/children + Michael Kerrisk + Clarify description of /proc/PID/statm 'lib' and 'dt' fields + These fields are always zero since Linux 2.6. + Namhyung Kim [Petr Cermak] + Add description of CLEAR_REFS_MM_HIWATER_RSS + Michael Kerrisk + Update example VM values in /proc/PID/status + +capabilities.7 + Michael Kerrisk + Add note about nosuid to file capabilities section + Michael Kerrisk + SEE ALSO: add proc(5) + Michael Kerrisk + SEE ALSO: add setsid(2) and setpgid(2) + +glob.7 + Michael Kerrisk [Arnaud Gaillard] + Clarify that syntactically incorrect patterns are left unchanged + +packet.7 + Michael Kerrisk + Clarify user namespace requirements for CAP_NET_RAW + +pipe.7 + Michael Kerrisk [Patrick McLean] + Document FIONREAD + +raw.7 + Michael Kerrisk + Clarify user namespace requirements for CAP_NET_RAW + Also remove mention of UID 0 as a method or creating + a raw socket. As far as I can tell from reading the + kernel source (net/ipv4/af_inet.c), this is not true. + +socket.7 + Michael Kerrisk + SIOCSPGRP: refer to fcntl(2) F_SETOWN for correct permission rules + The permission rules described for SIOCCPGRP are wrong. Rather + than repeat the rules here, just refer the reader to fcntl(2), + where the rules are described for F_SETOWN. + +unix.7 + Michael Kerrisk [Laurent Georget, Ivan Kharpalev] + Remove mention of recvmsg() from discussion of EPIPE error + See https://bugzilla.kernel.org/show_bug.cgi?id=137351 + +ld.so.8 + Michael Kerrisk + Expand description of LD_DEBUG + Provide a list of the categories, and note that multiple + categories can be specified. + Michael Kerrisk + Add glibc version for LD_USE_LOAD_BIAS + Michael Kerrisk + Clarify text describing whether secure-mode programs preload libraries + Michael Kerrisk + Remove discussion of environment variables understood by libc5 + libc5 disappeared long ago, so cease cluttering up this page + with those ancient details. Thus, remove discussion of the + following environment variables: LD_AOUT_LIBRARY_PATH, + LD_AOUT_PRELOAD, LD_KEEPDIR, LD_NOWARN, and LDD_ARGV0. + Michael Kerrisk + Remove text with ancient libc4 and Linux libc details + Michael Kerrisk + Remove mention of "ELF only" + Drawing a distinction between ELF-only features versus a,out + ceased to be relevant long ago, so cluttering the page + with "ELF-only" serves no purpose. + + + +==================== Changes in man-pages-4.09 ==================== + +Released: 2016-12-12, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Afzal Mohammed +Andrew Clayton +Carlos O'Donell +Christoph Lameter +Daniel Baluta +Daniel Berrange +Daniel Wagner +Darrick J. Wong +Dave Hansen +Dmitry V. Levin +Dr. Tobias Quathamer +Elliott Hughes +Eric W. Biederman +Eugene Syromyatnikov +Florian Weimer +Heinrich Schuchardt +Igor Liferenko +Jakub Wilk +Jann Horn +Jeremy Harris +Kees Cook +Keno Fischer +Laurent Georget +Laurent Georget +Marcos Mello +Michael Hausenblas +Michael Kerrisk +Mike Frysinger +Mike Galbraith +Miroslav Koskar +Nikos Mavrogiannopoulos +Omar Sandoval +Pavel Emelyanov +Piotr Kwapulinski +Siddhesh Poyarekar +Theodore Ts'o +Vegard Nossum +Vincent Lefevre +Vince Weaver +Wainer dos Santos Moschetta +Wang Long +Willy Tarreau +Zack Weinberg + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pkey_alloc.2 + Dave Hansen [Michael Kerrisk] + New page documenting pkey_alloc(2) and pkey_free(2) + +pthread_getattr_default_np.3 + Michael Kerrisk + New page documenting pthread_getattr_default_np(3) and pthread_setattr_default_np(3) + +strfromd.3 + Wainer dos Santos Moschetta + New page documenting strfromd(3), strfromf(3), and strfroml(3) + The ISO/IEC TS 18661-1 specifies the strfrom() class + of functions that convert a float-point value to string. + +fuse.4 + Keno Fischer [Michael Kerrisk] + New page describing /dev/fuse + This is my writeup of a basic description of /dev/fuse after + playing with it for a few hours today. It is of course woefully + incomplete, and since I neither have a use case nor am working + on this code, I will not be in a position to expand it in the + near future. However, I'm hoping this could still serve as a + handy reference for others looking at this interface. + + [mtk: Notwithstanding the incompleteness of this page, + it's a good base for future extension.] + +tmpfs.5 + Michael Kerrisk + New page documenting the tmpfs filesystem + +pkeys.7 + Dave Hansen [Michael Kerrisk] + New page with overview of Memory Protection Keys + +random.7 + Michael Kerrisk [Theodore Ts'o, Nikos Mavrogiannopoulos, Laurent Georget] + New page providing an overview of interfaces for obtaining randomness + Contains material extracted from getrandom(2) and random(4), + as well as new material. + +sock_diag.7 + Pavel Emelyanov, Dmitry V. Levin + New page documenting NETLINK_SOCK_DIAG interface + +close.2 +getpriority.2 +nice.2 +timer_create.2 +timerfd_create.2 +random.4 +elf.5 +proc.5 +sched.7 + Various authors + These pages also saw substantial updates, as described under + "Changes to individual pages". + + +Newly documented interfaces in existing pages +--------------------------------------------- + +mmap.2 + Michael Kerrisk + Add (much) more detail on MAP_GROWSDOWN + +mprotect.2 + Dave Hansen + Document the new pkey_mprotect() system call + Eugene Syromyatnikov + Document PROT_SEM, PROT_SAO, PROT_GROWSUP, and PROT_GROWSDOWN + +prctl.2 + Eugene Syromyatnikov + Document PR_SET_FP_MODE and PR_GET_FP_MODE + +perf_event_open.2 + Vince Weaver + PERF_RECORD_SWITCH support + Linux 4.3 introduced two new record types for recording context + switches: PERF_RECORD_SWITCH and PERF_RECORD_SWITCH_CPU_WIDE. + Vince Weaver + Add PERF_SAMPLE_BRANCH_CALL branch sample type + Vince Weaver + PERF_SAMPLE_BRANCH_IND_JUMP branch_sample_type + Linux 4.2 added a new branch_sample_type: PERF_SAMPLE_BRANCH_IND_JUMP + Vince Weaver + Document PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT + Vince Weaver + Document sample_max_stack and /proc/sys/kernel/perf_event_max_stack + Linux 4.8 added a new sample_max_stack parameter, as well as + /proc/sys/kernel/perf_event_max_stack which limits it and a new + EOVERFLOW error return. + Dave Hansen + PERF_RECORD_LOST_SAMPLES record type + Linux 4.2 added a new record type: PERF_RECORD_LOST_SAMPLES + It is generated when hardware samples (currently only Intel PEBS) + are lost. + +ptrace.2 + Michael Kerrisk + Document PTRACE_SECCOMP_GET_FILTER + Michael Kerrisk + Document PTRACE_GET_THREAD_AREA and PTRACE_SET_THREAD_AREA + +namespaces.7 + Michael Kerrisk [Eric W. Biederman] + Document the NS_GET_USERNS and NS_GET_PARENT ioctl() operations + +sched.7 + Michael Kerrisk [Mike Galbraith] + Document the autogroup feature + Includes documenting autogroup nice value + Michael Kerrisk + Autogrouping breaks traditional semantics of nice in many cases + When autogrouping is enabled (the default in many distros) + there are many traditional use cases where the nice value + ceases to have any effect. + Michael Kerrisk + Add a subsection on nice value and group scheduling + + +New and changed links +--------------------- + +killpg.2 + Michael Kerrisk + New link to relocated killpg(3) page + +pkey_free.2 + Michael Kerrisk + New link to new pkey_alloc(2) page + +pkey_mprotect.2 + Michael Kerrisk + New link to mprotect(2) + +pthread_setattr_default_np.3 + Michael Kerrisk + New link to new pthread_getattr_default_np.3 + +strfromf.3 + Wainer dos Santos Moschetta + New link to strfromd(3) + +strfroml.3 + Wainer dos Santos Moschetta + New link to strfromd(3) + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Remove ancient libc4 and libc5 details + It's nearly 20 years now since Linux libc went away. + Remove some ancient details from the pages. + +Various pages + Michael Kerrisk + Add cross references to new tmpfs(5) page + +Various pages + Michael Kerrisk + Change section number from 2 to 3 in killpg() references + + +Changes to individual pages +--------------------------- + +accept.2 + Michael Kerrisk + Remove editorializing comments about 'socklen_t' + Michael Kerrisk + Simplify the discussion of 'socklen_t' + We don't really need to list the old OSes in this discussion. + +adjtimex.2 +clock_getres.2 +gettimeofday.2 + Michael Kerrisk + SEE ALSO: add hwclock(8) + +bind.2 +connect.2 +getpeername.2 +getsockname.2 +getsockopt.2 + Michael Kerrisk + Replace discussion of 'socklen_t' with reference to accept(2) + The discussion of 'socklen_t' editorializes and is repeated + across several pages. Replace it with a reference to accept(2), + where some details about this type are provided. + +chmod.2 + Michael Kerrisk + SEE ALSO: add chmod(1) + +chown.2 + Michael Kerrisk + SEE ALSO: add chgrp(1) and chown(1) + +chroot.2 + Michael Kerrisk + SEE ALSO: add chroot(1) + +clone.2 + Michael Kerrisk + The CLONE_*_SETTID operations store TID before return to user space + CLONE_PARENT_SETTID and CLONE_CHILD_SETTID store the new + TID before clone() returns to user space + +close.2 + Michael Kerrisk [Daniel Wagner] + Rework and greatly extend discussion of error handling + Further clarify that an error return should be used only + for diagnostic or remedial purposes. + Michael Kerrisk + Other UNIX implementations also close the FD, even if reporting an error + Looking at some historical source code suggests + that the "close() always closes regardless of error return" + behavior has a long history, predating even POSIX.1-1990. + Michael Kerrisk + Note that future POSIX plans to require that the FD is closed on error + See http://austingroupbugs.net/view.php?id=529#c1200. + Michael Kerrisk + Clarify the variation in EINTR behavior per POSIX and other systems + +fallocate.2 + Darrick J. Wong + Document behavior with shared blocks + Note that FALLOC_FL_UNSHARE may use CoW to unshare blocks to + guarantee that a disk write won't fail with ENOSPC. + +fanotify_mark.2 + Heinrich Schuchardt + Mention FAN_Q_OVERFLOW + To receive overflow events it is necessary to set this bit + in fanotify_mark(). + +fcntl.2 + Michael Kerrisk + F_GETPIPE_SZ allocates next power-of-2 multiple of requested size + Add some detail about current implementation, since this helps + the user understand the effect of the user pipe limits added in + Linux 4.5 (described in pipe(7)). + Michael Kerrisk + Add EPERM that occurs for F_SETPIPE_SZ when user pipe limit is reached + +fideduperange.2 + Darrick J. Wong [Omar Sandoval] + Fix the discussion of maximum sizes + Fix the discussion of the limitations on the dest_count and + src_length parameters to the fideduperange ioctl() to reflect + what's actually in the kernel. + +fsync.2 + Michael Kerrisk + SEE ALSO: add fileno(3) + fileno(3) is useful if one is combining fflush(3)/fclose(3) + and fsync(2). + Michael Kerrisk + SEE ALSO: add fflush(3) + +getgroups.2 + Andrew Clayton + FTM requirements fix for setgroups(2) + +gethostname.2 + Michael Kerrisk + SEE ALSO: add hostname(1) + +get_mempolicy.2 + Michael Kerrisk + Note that 'addr' must be NULL when 'flags' is 0 + +getpriority.2 + Michael Kerrisk + Warn that autogrouping voids the effect of 'nice' in many cases + Refer the reader to sched(7) for the details. + Michael Kerrisk + Expand discussion of getpriority() return value + Michael Kerrisk + The nice value supplied to setpriority() is clamped + Note that the nice value supplied to setpriority() is clamped + to the permitted range. + Michael Kerrisk + Improve description of setpriority() return value + +getpriority.2 +sched.7 + Michael Kerrisk + Move nice value details from getpriority(2) to sched(7) + Centralizing these details in sched(7) is more logical. + +getrandom.2 +random.4 + Michael Kerrisk + Consolidate and improve discussion on usage of randomness + Currently, recommendations on how to consume randomness are + spread across both getrandom(2) and random(4) and the general + opinion seems to be that the text in getrandom(2) does a + somewhat better job. Consolidate the discussion to a single + page (getrandom(2)) and address some of the concerns + expressed about the existing text in random(4). + [Some of this text ultimately made its way into the new + random(7) page.] + +getrandom.2 + Michael Kerrisk + Remove material incorporated into random(7) + Michael Kerrisk + Note advantages of fact that getrandom() doesn't use file descriptors + Michael Kerrisk + Clarify that getrandom() is not "reading" from /dev/{random,urandom} + +getrlimit.2 + Michael Kerrisk + Refer to sched(7) in discussion of RLIMIT_RTPRIO and RLIMIT_RTTIME + Michael Kerrisk + Describe the range of the RLIMIT_NICE limit + Michael Kerrisk + Refer to sched(7) in the discussion of RLIMIT_NICE + Michael Kerrisk + SEE ALSO: add credentials(7) + +ioctl_ficlonerange.2 +ioctl_fideduperange.2 + Darrick J. Wong + Clarify the behavior of the FIDEDUPERANGE ioctl + +kill.2 + Michael Kerrisk + SEE ALSO: add kill(1) + +mbind.2 + Michael Kerrisk [Christoph Lameter] + Memory policy is a per-thread attribute, not a per-process attribute + +mbind.2 +set_mempolicy.2 + Piotr Kwapulinski [Christoph Lameter, Michael Kerrisk] + Add MPOL_LOCAL NUMA memory policy documentation + +mount.2 + Michael Kerrisk + SEE ALSO: add mountpoint(1) + +mprotect.2 + Michael Kerrisk + CONFORMING TO: note that pkey_mprotect() is Linux-specific + +nice.2 + Michael Kerrisk + Warn that autogrouping voids the effect of 'nice' in many cases + Michael Kerrisk + CONFORMING TO: Remove an ancient SVr4 detail on errno values + Michael Kerrisk + Rework discussion of nice() return value and standards conformance + Make the text a little clearer. In particular, clarify that the + raw system call (still) returns 0 on success. + Michael Kerrisk + Clarify the range of the nice value, and note that it is clamped + Michael Kerrisk + Add mention of RLIMIT_NICE + Michael Kerrisk + Move discussion of handling the -1 success return to RETURN VALUE + This detail was rather hidden in NOTES. Also, rework the text + a little. + Michael Kerrisk + Clarify that nice() changes the nice value of the calling *thread* + Michael Kerrisk + Add "C library/kernel differences" subsection heading + Michael Kerrisk + Add reference to sched(7) for further details on the nice value + +open.2 + Michael Kerrisk + ubifs supports O_TMPFILE starting with Linux 4.9 + Michael Kerrisk + Document ENOMEM that occurs when opening FIFO because of pipe hard limit + +perf_event_open.2 + Vince Weaver + Add cycles field in LBR records + Linux 4.3 added a cycles field to the PERF_SAMPLE_BRANCH_STACK + last branch records. + Vince Weaver + Update time_shift sample code + Linux 4.3 improved the accuracy of the clock/ns conversion routines. + Michael Kerrisk + Clarify the use of signals for capturing overflow events + +pipe.2 + Michael Kerrisk + Add ENFILE error for user pipe hard limit reached + +prctl.2 + Eugene Syromyatnikov + Some additional details regarding the PR_GET_UNALIGNED operation + Eugene Syromyatnikov + Note the output buffer size for PR_GET_TID_ADDRESS operation on x32/n32 + Michael Kerrisk + Remove numeric definitions of PR_FP_MODE_FR and PR_FP_MODE_FRE bits + +ptrace.2 + Keno Fischer + Document the behavior of PTRACE_SYSEMU stops + Keno Fischer + Expand documentation PTRACE_EVENT_SECCOMP traps + In Linux 4.8, the order of PTRACE_EVENT_SECCOMP and + syscall-entry-stops was reversed. Document both behaviors and + their interaction with the various forms of restart. + +quotactl.2 + Eugene Syromyatnikov + Describe Q_XQUOTASYNC, which is present but no-op in recent kernels + +reboot.2 + Wang Long + Note errors for invalid commands inside a PID namespace + +sched_setattr.2 + Michael Kerrisk + Fix cross reference for further info on the nice value + The information moved from getpriority(2) to sched(7). + +sched_setscheduler.2 + Michael Kerrisk [Daniel Berrange] + Mention SCHED_DEADLINE + Give the reader a clue that there is another policy + available that can't be set via sched_setscheduler(2). + +seccomp.2 + Jann Horn + Document changed interaction with ptrace + Before kernel 4.8, the seccomp check will not be run again + after the tracer is notified. Fixed in kernel 4.9. + Michael Kerrisk + NOTES: mention ptrace(PTRACE_SECCOMP_GET_FILTER) to dump seccomp filters + +set_mempolicy.2 + Michael Kerrisk + Reformat list of modes + +setsid.2 + Michael Kerrisk + Improve wording of text on calling setsid() after fork()+_exit() + Michael Kerrisk + SEE ALSO: add sched(7) + List sched(7), because setsid(2) is part of the machinery + of autogrouping. + +sigaction.2 + Dave Hansen + Further documentation of SEGV_PKUERR + +signalfd.2 + Michael Kerrisk + Document ssi_addr_lsb field of signalfd_siginfo + +symlink.2 + Michael Kerrisk + SEE ALSO: add namei(1) + +sync_file_range.2 + Michael Kerrisk + Fix description for ESPIPE error + A file descriptor can't refer to a symbolic link. + +syscalls.2 + Michael Kerrisk + Add pkey_alloc(), pkey_free(), and pkey_mprotect() + New system calls in Linux 4.9. + Michael Kerrisk + Add ppc_swapcontext(2) + +timer_create.2 + Michael Kerrisk + Document CLOCK_BOOTTIME + Michael Kerrisk + Document CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM + +timerfd_create.2 + Michael Kerrisk + Document CLOCK_BOOTTIME, CLOCK_REALTIME_ALARM, and CLOCK_BOOTTIME_ALARM + Michael Kerrisk + Document TFD_TIMER_CANCEL_ON_SET + Michael Kerrisk + Rework discussion on relative and absolute timers + +unlink.2 + Michael Kerrisk + SEE ALSO: add unlink(2) + +utime.2 +utimensat.2 + Michael Kerrisk + SEE ALSO: add touch(1) + +wait.2 + Michael Kerrisk + On some architectures, waitpid() is a wrapper that calls wait4(). + +atof.3 + Wainer dos Santos Moschetta + SEE ALSO: add strfromd(3) + +ctime.3 + Michael Kerrisk + Add ERRORS section + Michael Kerrisk + RETURN VALUE: describe return values more explicitly + +errno.3 + Michael Kerrisk [Igor Liferenko] + Add glibc error text for EILSEQ + +fclose.3 +fflush.3 + Michael Kerrisk + SEE ALSO: add fileno(2) + +getlogin.3 + Michael Kerrisk + Remove deprecated _REENTRANT from FTM requirements for getlogin_r() + Michael Kerrisk + SEE ALSO: add logname(1) + +isalpha.3 + Michael Kerrisk + Note circumstances where 'c' must be cast to 'unsigned char' + +killpg.3 + Michael Kerrisk + Move killpg.2 from section to section 3 + +mallopt.3 + Michael Kerrisk [Siddhesh Poyarekar] + Document 0 as default value of M_ARENA_MAX and explain its meaning + Michael Kerrisk + Improve description of M_ARENA_TEST + Michael Kerrisk + Document default value for M_ARENA_TEST + Michael Kerrisk + Note default value of M_PERTURB + +mbsnrtowcs.3 + Michael Kerrisk [Igor Liferenko] + Note behavior of mbsnrtowcs() for an incomplete character + Note the behavior of mbsnrtowcs() when an incomplete character + is found at end of the input buffer. + +mbstowcs.3 +wcstombs.3 + Michael Kerrisk [Igor Liferenko] + Improve language relating to "initial state" + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839705 + +mbstowcs.3 + Michael Kerrisk [Igor Liferenko] + Add missing include to example program + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=845172 + +mq_close.3 + Michael Kerrisk + DESCRIPTION: add reference to mq_notify(3) + +mq_open.3 + Eugene Syromyatnikov + Clarification regarding usage of mq_flags attribute in mq_open() + +mq_receive.3 +mq_send.3 + Eugene Syromyatnikov + Clarification regarding reasons behind EBADF + +printf.3 + Wainer dos Santos Moschetta + SEE ALSO: add strfromd(3) + +pthread_attr_init.3 + Michael Kerrisk + SEE ALSO: add pthread_setattr_default_np(3) + +pthread_create.3 + Michael Kerrisk + SEE ALSO: add pthread_setattr_default_np(3) + +ptsname.3 + Michael Kerrisk + Note that ptsname_r() is proposed for future inclusion in POSIX.1 + Michael Kerrisk + CONFORMING TO:: clarify that only ptsname() is standardized (so far) + +remainder.3 + Michael Kerrisk + Note fix to remainder(nan(""), 0) handling + The bug https://www.sourceware.org/bugzilla/show_bug.cgi?id=6779 + has been fixed in glibc 2.15. + Michael Kerrisk + Document fixes for EDOM handling for range errors + The bug http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783 + was fixed in glibc 2.15. + +setjmp.3 + Michael Kerrisk + _BSD_SOURCE must be *explicitly* defined to get BSD setjmp() semantics + +strtod.3 + Wainer dos Santos Moschetta + SEE ALSO: add strfromd(3) + +tgamma.3 + Michael Kerrisk + Document fixes to give ERANGE for underflow range error + The bug https://www.sourceware.org/bugzilla/show_bug.cgi?id=6810 + was fixed in glibc 2.19. + +timegm.3 + Michael Kerrisk + Add ERRORS section + Michael Kerrisk [Vincent Lefevre] + Add RETURN VALUE section + +tmpnam.3 + Michael Kerrisk + Properly document tmpnam_r(3) + +toupper.3 + Michael Kerrisk + Note circumstances where 'c' must be cast to 'unsigned char' + +ttyname.3 + Michael Kerrisk + SEE ALSO: add tty(1) + +console_ioctl.4 + Michael Kerrisk + Add brief descriptive text for KDGKBMODE modes + Miroslav Koskar + Add K_OFF keyboard mode + +random.4 + Michael Kerrisk + Add reference to new random(7) page + Michael Kerrisk + Rework formatting of /proc interfaces + Make the information easier to parse by formatting the file + descriptions as hanging lists. No significant content changes. + Nikos Mavrogiannopoulos [Laurent Georget] + Provide a more accurate description of /dev/urandom + This documents the "property" of /dev/urandom of being able to + serve numbers prior to pool being initialized, and removes any + suggested usages of /dev/random which are disputable + (i.e., one-time pad). Document the fact /dev/random is only + suitable for applications which can afford indeterminate delays + since very few applications can do so. Smooth the alarming + language about a theoretical attack, and mention that its + security depends on the cryptographic primitives used by the + kernel, as well as the total entropy gathered. + Michael Kerrisk [Laurent Georget, Theodore Ts'o] + Improve discussion of /dev/urandom, blocking reads, and signals + The text currently states that O_NONBLOCK has no effect for + /dev/urandom, which is true. It also says that reads from + /dev/urandom are nonblocking. This is at the least confusing. + If one attempts large reads (say 10MB) from /dev/urandom + there is an appreciable delay, and interruption by a signal + handler will result in a short read. Amend the text to + reflect this. + +elf.5 + Mike Frysinger + Add subsection headers at major points + The current pages dumps all the content into one big DESCRIPTION + with no real visual break up between logically independent + sections. Add some subsection headers to make it easier to + read and scan. + Mike Frysinger + Document notes + Document the Elf{32,64}_Nhdr structure, the sections/segments that + contain notes, and how to interpret them. I've been lazy and only + included the GNU extensions here, especially as others are not + defined in the elf.h header file as shipped by glibc. + +filesystems.5 + Michael Kerrisk + SEE ALSO: add fuse(4) + +proc.5 + Dave Hansen + Describe new ProtectionKey 'smaps' field + Michael Kerrisk + Add example ProtectionKey output for 'smaps' file + Michael Kerrisk + Add pointers to sched(7) for autogroup files + sched(7) describes /proc/sys/kernel/sched_autogroup_enabled + and /proc/PID/autogroup. + Michael Kerrisk + Add /proc/sys/fs/pipe-user-pages-{hard,soft} entries + Michael Kerrisk + Improve description of the KernelPageSize and MMUPageSize 'smaps' fields + Michael Kerrisk + Rework 'smaps' ProtectionKey text and add some details + Michael Kerrisk + Mention lslocks(8) in discussion of /proc/locks + Michael Kerrisk + Describe Shmem field of /proc/meminfo + Michael Kerrisk + Rework 'smaps' VmFlags text, and add kernel version and example output + +proc.5 +pipe.7 + Michael Kerrisk + Move /proc/sys/fs/pipe-max-size content from proc(5) to pipe(7) + +resolv.conf.5 + Carlos O'Donell [Florian Weimer] + Timeout does not map to resolver API calls + +utmp.5 + Michael Kerrisk + SEE ALSO: add users(1) + +capabilities.7 + Michael Kerrisk + CAP_SYS_ADMIN governs ptrace(2) PTRACE_SECCOMP_GET_FILTER + Michael Kerrisk + CAP_SYS_ADMIN allows privileged ioctl() operations on /dev/random + +cgroups.7 + Michael Kerrisk + Add details on 'cpu' CFS bandwidth control + +credentials.7 + Michael Kerrisk + SEE ALSO: add setpriv(1) + Michael Kerrisk + SEE ALSO: add shadow(5) + +feature_test_macros.7 + Michael Kerrisk [Zack Weinberg] + Note that _REENTRANT and _THREAD_SAFE are now deprecated + Michael Kerrisk + Note that "cc -pthread" defines _REENTRANT + +inotify.7 + Michael Kerrisk + Note a subtlety of event generation when monitoring a directory + +libc.7 + Michael Kerrisk + Add a note on why glibc 2.x uses the soname libc.so.6 + Michael Kerrisk + Add a few historical details on Linux libc4 and libc5 + Just for historical interest. Details taken from + http://www.linux-m68k.org/faq/glibcinfo.html. + +mdoc.7 + Michael Kerrisk + Add a cross-reference to groff_mdoc(7) + +mount_namespaces.7 + Michael Kerrisk + SEE ALSO: add user_namespaces(7) + +mount_namespaces.7 +user_namespaces.7 + Michael Kerrisk + Migrate subsection on mount restrictions to mount_namespaces(7) + This section material in the user_namespaces(7) page was written + before the creation of the mount_namespaces(7) manual page. + Nowadays, this material properly belongs in the newer page. + +netlink.7 + Dmitry V. Levin + Document NETLINK_INET_DIAG rename to NETLINK_SOCK_DIAG + Dmitry V. Levin + Add references to sock_diag(7) + +pid_namespaces.7 + Michael Kerrisk + Refer to namespaces(7) for information about NS_GET_PARENT + +pipe.7 + Michael Kerrisk, Vegard Nossum [Vegard Nossum] + Document /proc files controlling memory usage by pipes + Document /proc/sys/fs/pipe-max-size and + /proc/sys/fs/pipe-user-pages-{soft,hard}. + Michael Kerrisk + Document pre-Linux 4.9 bugs in pipe limit checking + +sched.7 + Michael Kerrisk + Add a new introductory paragraph describing the nice value + Michael Kerrisk + Add more precise details on CFS's treatment of the nice value + Michael Kerrisk + Mention RLIMIT_NICE in the discussion of the nice value + Michael Kerrisk + NOTES: mention cgroups CPU controller + Michael Kerrisk + Add introductory sentence mentioning CFS scheduler + Michael Kerrisk + Add nice(2), getpriority(2), and setpriority(2) to API list + Michael Kerrisk + Make it clearer that SCHED_OTHER is always scheduled below real-time + Michael Kerrisk + Give the page a more generic NAME + The page isn't just about APIs. + +standards.7 + Michael Kerrisk + POSIX.1-2016 (POSIX.1-2008 TC2) has now been released + +symlink.7 + Michael Kerrisk + SEE ALSO: add namei(1) + +uri.7 + Jakub Wilk + Use "example.com" as example domain + +user_namespaces.7 + Michael Kerrisk + Add reference to namespaces(7) for NS_GET_USERNS operation + Michael Kerrisk + Add reference to namespaces(7) for NS_GET_PARENT operation + + +==================== Changes in man-pages-4.10 ==================== + +Released: 2017-03-13, Paris + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Adam Martindale +Alex +Anders Thulin +Andreas Gruenbacher +Brian Masney +Casey Schaufler +David Howells +Erik Kline +Erik Roland van der Meer +Eugene Syromyatnikov +Fabjan Sukalia +Heinrich Schuchardt +Helmut Eller +Hugo Guiroux +Ian Jackson +Jakub Wilk +Jann Horn +Jan Ziak <0xe2.0x9a.0x9b@gmail.com> +John Wiersba +Jon Jensen +Kai NODA +KASAKI Motohiro +Keno Fischer +Kent Fredic +Krzysztof Kulakowski +Maik Zumstrull +Mat Martineau +Michael Kerrisk +Mike Frysinger +Nadav Har'El +Namhyung Kim +Nicolas Biscos +Omar Sandoval +Paul Fee +Reverend Homer +Rob Landley +Sergey Polovko +Steven Luo +Tadeusz Struk +Vincent Bernat +Vivenzio Pagliari +Wainer dos Santos Moschetta +Willy Tarreau + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +add_key.2 + Michael Kerrisk [Eugene Syromyatnikov, David Howells] + Major improvements and additions + The page has doubled in length. + +ioctl_iflags.2 + Michael Kerrisk + New page describing inode flags and ioctl() operations + +ioctl_ns.2 + Michael Kerrisk + New page created by splitting ioctl(2) operations out of namespaces(7) + +keyctl.2 + Michael Kerrisk, Eugene Syromyatnikov [David Howells, Mat Martineau] + A vast number of additions and improvements + The page has gone from somewhat over 100 lines to well over + 1000 lines and now more or less documents the complete interface + provided by this system call. + +getentropy.3 + Michael Kerrisk + New page documenting getentropy(3) + getentropy(3) is added to glibc in version 2.25. + +keyrings.7 + David Howells + New page (written by David Howells) adopted from keyutils + Since this page documents kernel-user-space interfaces, + it makes sense to have it as part of man-pages, rather + than the keyutils package. + Michael Kerrisk [Eugene Syromyatnikov, David Howells] + Very many additions and improvements + Michael Kerrisk + Document /proc/keys + Michael Kerrisk + Document /proc/sys/kernel/keys/persistent_keyring_expiry + Michael Kerrisk + Document /proc/key-users + Michael Kerrisk + Document /proc/sys/kernel/keys/gc_delay + Michael Kerrisk + Document /proc files that define key quotas + +persistent-keyring.7 + Michael Kerrisk + New page (written by David Howells) adopted from keyutils + Since this page documents kernel-user-space interfaces, + it makes sense to have it as part of man-pages, rather + than the keyutils package. + Michael Kerrisk + Various clean-ups and additions + +process-keyring.7 + Michael Kerrisk + New page (written by David Howells) adopted from keyutils + Since this page documents kernel-user-space interfaces, + it makes sense to have it as part of man-pages, rather + than the keyutils package. + Michael Kerrisk + Various additions and improvements + +request_key.2 + Michael Kerrisk, Eugene Syromyatnikov [David Howells] + Very many additions and improvements + The page is now three times its former length. + +session-keyring.7 + Michael Kerrisk + New page (written by David Howells) adopted from keyutils + Since this page documents kernel-user-space interfaces, + it makes sense to have it as part of man-pages, rather + than the keyutils package. + Michael Kerrisk + Various reworking and additions + +signal-safety.7 + Michael Kerrisk + New page created by migrating the signal-safety discussion from + signal(7). Along the way some more details got added. + Michael Kerrisk [KASAKI Motohiro] + Note async-signal-safety problems caused by pthread_atfork() + See https://bugzilla.kernel.org/show_bug.cgi?id=25292 + Michael Kerrisk [KASAKI Motohiro] + Note glibc deviations from POSIX requirements + See https://bugzilla.kernel.org/show_bug.cgi?id=25292 + +thread-keyring.7 + Michael Kerrisk + New page (written by David Howells) adopted from keyutils + Since this page documents kernel-user-space interfaces, + it makes sense to have it as part of man-pages, rather + than the keyutils package. + Michael Kerrisk + Various rewordings and additions + +user-keyring.7 + Michael Kerrisk + New page (written by David Howells) adopted from keyutils + Since this page documents kernel-user-space interfaces, + it makes sense to have it as part of man-pages, rather + than the keyutils package. + Michael Kerrisk + Various reworking and improvements + +user-session-keyring.7 + Michael Kerrisk + New page (written by David Howells) adopted from keyutils + Since this page documents kernel-user-space interfaces, + it makes sense to have it as part of man-pages, rather + than the keyutils package. + Michael Kerrisk + Various rewordings and additions + + +Newly documented interfaces in existing pages +--------------------------------------------- + +bzero.3 + Michael Kerrisk + Document explicit_bzero() (new in glibc 2.25) + Also, reword the description of bzero somewhat. + +proc.5 + Michael Kerrisk + Document /proc/sys/vm/user_reserve_kbytes + Michael Kerrisk + Document /proc/sys/vm/admin_reserve_kbytes + Michael Kerrisk + Document /proc/sys/fs/mount-max + Michael Kerrisk + Document /proc/PID/status 'NoNewPrivs' field + + +New and changed links +--------------------- + +explicit_bzero.3 + Michael Kerrisk + New link to bzero.3 + + +Changes to individual pages +--------------------------- + +chmod.2 + Michael Kerrisk + ERRORS: add EPERM error for immutable/append-only file + +chown.2 + Michael Kerrisk + ERRORS: add EPERM error for immutable/append-only file + +chroot.2 + Michael Kerrisk + SEE ALSO: add switch_root(8) + +clock_getres.2 + Michael Kerrisk + Note POSIX.1 requirements re relative time services and CLOCK_REALTIME + +clone.2 + Michael Kerrisk + clone() does not execute fork handlers + +execve.2 + Michael Kerrisk + Rework text describing when effective IDs aren't transformed by execve() + Michael Kerrisk + File capabilities can be ignored for the same reasons as set-UID/set-GID + Michael Kerrisk + The 'no_new_privs' bit inhibits transformations of the effective IDs + +fork.2 + Michael Kerrisk + cgroup PIDs controller may also be trigger for EAGAIN error + +fsync.2 + Michael Kerrisk + SEE ALSO: add posix_fadvise(2) + +getrandom.2 + Michael Kerrisk + Remove getentropy(3) details and defer to new getentropy(3) page + Michael Kerrisk + Starting with glibc 2.25, getrandom() is now declared in + Michael Kerrisk + glibc support was added in version 2.25 + +getrlimit.2 + Michael Kerrisk + Document role of RLIMIT_NOFILE for FD passing over UNIX sockets + +getxattr.2 +listxattr.2 + Andreas Gruenbacher + Document E2BIG errors + +inotify_add_watch.2 + Michael Kerrisk + Note "inode" as a synonym for "filesystem object" + Consistent with clarifications just made in inotify(7). + +ioctl.2 + Michael Kerrisk + SEE ALSO: add ioctl_ns(2), ioctl_iflags(2) + +ioctl_fat.2 + Brian Masney + Correctly reference volume ID instead of volume label + +kcmp.2 + Michael Kerrisk + Mention the clone(2) flags relating to various kcmp() 'type' values + Michael Kerrisk + KCMP_FILE: note reasons why FDs may refer to same open file description + +link.2 + Michael Kerrisk + When using linkat() AT_EMPTY_PATH, 'olddirfd' must not be a directory + Michael Kerrisk + ERRORS: add EPERM for immutable/append-only files + Michael Kerrisk + Note limits where EMLINK is encountered on ext4 and Btrfs + +listxattr.2 + Michael Kerrisk + Eliminate extra E2BIG error text + Andreas' patch added a second description of E2BIG that + was (mostly) more detailed than the existing text. Combine + the two texts. + +lseek.2 + Michael Kerrisk + O_APPEND overrides the effect of lseek() when doing file writes + Michael Kerrisk + Remove ancient info about whence values and return values on old systems + Michael Kerrisk + Remove slightly bogus advice about race conditions + The page already (by now) contains a reference to open(2) + for a discussion of open file descriptions. Leave it at that, + since the reader can then deduce how things work. + +madvise.2 + Michael Kerrisk + Note that madvise() is generally about improving performance + +mbind.2 + Krzysztof Kulakowski [Michael Kerrisk] + Update MPOL_BIND description + The behavior of MPOL_BIND changed in Linux 2.6.26. + +mincore.2 + Michael Kerrisk + SEE ALSO: add madvise(2), posix_fadvise(2), posix_madvise(3) + +mlock.2 + Michael Kerrisk + Note pre-4.9 bug in RLIMIT_MEMLOCK accounting for overlapping locks + Michael Kerrisk + SEE ALSO: add mincore(2) + +mmap.2 + Michael Kerrisk + mincore(2) can be used to discover which pages of a mapping are resident + +mount.2 + Michael Kerrisk [Rob Landley] + Refer to mount_namespaces(7) for details of default propagation type + +nanosleep.2 + Michael Kerrisk + Describe "creeping sleep" problem + nanosleep() has a problem if used in a program that catches + signals and those signals are delivered at a very high rate. + Describe the problem, and note that clock_nanosleep(2) + provides a solution. + Michael Kerrisk + BUGS: explicitly note that the Linux 2.4 bug was fixed in Linux 2.6 + +open.2 + Michael Kerrisk + Make it clear that O_APPEND implies atomicity + Michael Kerrisk + Clarify distinction between file creation flags and file status flags + Michael Kerrisk + Note ambiguity of ELOOP error when using O_NOFOLLOW + Michael Kerrisk + Restructure O_NOFOLLOW text for easier parsing + Michael Kerrisk + Clarify that O_NOFOLLOW is now in POSIX + +poll.2 +select.2 + Nicolas Biscos + Add a reference to the sigset discussion in sigprocmask(2) + A little while back, I added a note to sigprocmask.2 that + discussed the difference between the libc's and the kernel's + sigset_t structures. I added that note, because I saw this being + done wrong in a tool tracing system calls (causing subtle bugs). + As it turns out, the same bugs existed for ppoll and pselect, for + the same reason. I'm hoping by adding the reference here, future + writers of similar tools will find that discussion and not make + the same mistake. + +posix_fadvise.2 + Michael Kerrisk + Mention /proc/sys/vm/drop_caches + It may be helpful for the reader of this page to know about + /proc/sys/vm/drop_caches. + Michael Kerrisk + Reorganize some text + Details for various flags were hidden under NOTES. + Move them to DESCRIPTION, to make the details more + obvious. + Michael Kerrisk + One can use open(2) + mmap(2) + mincore(2) as a 'fincore' + Note that open(2) + mmap(2) + mincore(2) can be used to get a view + of which pages of a file are currently cached. + Michael Kerrisk [Maik Zumstrull] + Note that POSIX_FADV_DONTNEED *may* try to write back dirty pages + Michael Kerrisk + SEE ALSO: mincore(2) + +prctl.2 + Michael Kerrisk + Clarify that the ambient capability set is per-thread + Keno Fischer + Be more precise in what causes dumpable to reset + Michael Kerrisk + The no_new_privs setting is per-thread (not per-process) + Michael Kerrisk + Mention /proc/PID/status 'NoNewPrivs' field + Michael Kerrisk + Add reference to seccomp(2) in discussion of PR_SET_NO_NEW_PRIVS + +ptrace.2 + Omar Sandoval + Clarify description of PTRACE_O_EXITKILL + +read.2 + Michael Kerrisk [Kai NODA] + Rework text in DESCRIPTION that talks about limits for 'count' + See https://bugzilla.kernel.org/show_bug.cgi?id=86061 + Michael Kerrisk [Steven Luo] + Remove crufty text about EINTR and partial read + Remove bogus text saying that POSIX permits partial read + to return -1/EINTR on interrupt by a signal handler. + That statement already ceased to be true in SUSv1 (1995)! + + See https://bugzilla.kernel.org/show_bug.cgi?id=193111 + +readv.2 + Michael Kerrisk + Remove generic advice about mixing stdio and syscalls on same file + There is nothing specific to readv()/writev() about this advice. + +recv.2 + Michael Kerrisk [Vincent Bernat] + Remove duplicate paragraph + man-pages-1.34 included changes that duplicated an existing + paragraph. Remove that duplicate. + Michael Kerrisk + SEE ALSO: add ip(7), ipv6(7), tcp(7), udp(7), unix(7) + +remap_file_pages.2 + Michael Kerrisk + remap_file_pages() has been replaced by a slower in-kernel emulation + +send.2 + Michael Kerrisk + SEE ALSO: add ipv6(7), socket(7), unix(7) + +setxattr.2 + Michael Kerrisk + ERRORS: add EPERM for immutable/append-only files + +signalfd.2 + Michael Kerrisk + signalfd() doesn't play well with helper programs spawned by libraries + See https://lwn.net/Articles/415684/. + Michael Kerrisk + signalfd can't be used to receive synchronously generated signals + Signals such as the SIGSEGV that results from an invalid + memory access can be caught only with a handler. + +stat.2 + Michael Kerrisk + EXAMPLE: extend program to also show ID of the containing device + Michael Kerrisk + NOTES: mention fstatat() AT_NO_AUTOMOUNT in discussion of automounting + +statfs.2 + Namhyung Kim + Add more filesystem types + Add missing magic numbers from /usr/include/linux/magic.h + +syscall.2 + Mike Frysinger + Add endian details with 64-bit splitting + Architectures that split 64-bit values across register pairs + usually do so according to their C ABI calling convention (which + means endianness). Add some notes to that effect, and change the + readahead example to show a little endian example (since that is + way more common than big endian). + + Also start a new list of syscalls that this issue does not apply + to. + Mike Frysinger + Note parisc handling of aligned register pairs + While parisc would normally have the same behavior as ARM/PowerPC, + they decide to write shim syscall stubs to unpack/realign rather + than expose the padding to userspace. + +tkill.2 + Jann Horn + Document EAGAIN error for real-time signals + +truncate.2 + Michael Kerrisk + Note use of ftruncate() for POSIX shared memory objects + +unlink.2 + Michael Kerrisk + ERRORS: add EPERM error for immutable/read-only files + +vfork.2 + Michael Kerrisk + Explain why the child should not call exit(3) + Michael Kerrisk + Another reason to use vfork() is to avoid overcommitting memory + Michael Kerrisk + Note some caveats re the use of vfork() + Inspired by Rich Felker's post at http://ewontfix.com/7/. + See also https://sourceware.org/bugzilla/show_bug.cgi?id=14749 and + See also https://sourceware.org/bugzilla/show_bug.cgi?id=14750. + Michael Kerrisk + SEE ALSO: add _exit(2) + +write.2 + Michael Kerrisk [Kai NODA] + Alert the reader that there is a limit on 'count' + See https://bugzilla.kernel.org/show_bug.cgi?id=86061 + +aio_suspend.3 + Michael Kerrisk + Note that the glibc implementation is not async-signal-safe + See https://sourceware.org/bugzilla/show_bug.cgi?id=13172 + +backtrace.3 + Michael Kerrisk + SEE ALSO: add addr2line(1) and gdb(1) + +bcmp.3 +bcopy.3 +bzero.3 +memccpy.3 +memchr.3 +memcmp.3 +memcpy.3 +memfrob.3 +memmem.3 +memmove.3 +memset.3 + Michael Kerrisk + SEE ALSO: add bstring(3) + +exec.3 + Michael Kerrisk + execl() and execle() were not async-signal-safe before glibc 2.24 + +fopen.3 + Michael Kerrisk [Helmut Eller] + Describe freopen() behavior for NULL pathname argument + See https://bugzilla.kernel.org/show_bug.cgi?id=191261 + Michael Kerrisk + Note the open(2) flags that correspond to the 'mode' argument + Michael Kerrisk + Change argument name: 'path' to 'pathname' + For consistency with open(2). + Michael Kerrisk + Add subsection headings for each function + +fts.3 + Michael Kerrisk + Use better argument name for fts_children() and fts_set() + Michael Kerrisk + Fix minor error in FTSENT structure definition + Michael Kerrisk + Improve explanation of 'fts_errno' + Michael Kerrisk + Give a hint that there are further fields in the FTSENT structure + Michael Kerrisk + Clarify meaning of zero as 'instr' value for fts_set() + +ftw.3 + Michael Kerrisk + Correctly handle use of stat info for FTW_NS in example program + Michael Kerrisk + Clarify that stat buffer is undefined for FTW_NS + +getline.3 + Michael Kerrisk + EXAMPLE: better error handling + Michael Kerrisk [Kent Fredic] + EXAMPLE: handle null bytes in input + Jann Horn + Document ENOMEM error case + see the error handling in libio/iogetdelim.c + Michael Kerrisk + EXAMPLE: specify file to be opened as command-line argument + Michael Kerrisk + Use better variable name in example program + +getmntent.3 + Michael Kerrisk [Anders Thulin] + Prefer '\\' as the escape to get a backslash + See https://bugzilla.kernel.org/show_bug.cgi?id=191611 + +getopt.3 + Michael Kerrisk + Reword discussion of error handling and reporting + The existing description was hard to understand. Break + it into a bullet list that separates out the details + in a manner that is easier to parse. + Michael Kerrisk + Correct details of use of to get getopt() declaration + Michael Kerrisk [John Wiersba] + Remove some redundant text + +mq_open.3 + Michael Kerrisk [Adam Martindale] + Include definition of the 'mq_attr' structure in this man page + Make the reader's life a little easier by saving them from + having to refer to mq_getattr(3). + +mq_send.3 + Michael Kerrisk [Adam Martindale] + Refer to mq_overview(7) for details on range of message priority + +__ppc_set_ppr_med.3 + Wainer dos Santos Moschetta + Note need for _ARCH_PWR8 macro + The _ARCH_PWR8 macro must be defined to get the + __ppc_set_ppr_very_low() and __ppc_set_ppr_med_high() + definitions. + +printf.3 + Michael Kerrisk + Document nonstandard 'Z' modifier + Michael Kerrisk + Document 'q' length modifier + Michael Kerrisk [Erik Roland van der Meer] + Fix a small bug in example code + Move the second call to va_end(ap) to above the if-block that + precedes it, so that the va_list 'ap' will be cleaned up in + all cases. + Michael Kerrisk [Nadav Har'El] + As a nonstandard extension, GNU treats 'll' and 'L' as synonyms + See https://bugzilla.kernel.org/show_bug.cgi?id=190341. + Michael Kerrisk + Add references to setlocale(3) in discussions of locales + Michael Kerrisk + SEE ALSO: remove bogus self reference (dprintf(3)) + +random.3 + Michael Kerrisk + Relocate information of "optimal" value of initstate() 'n' argument + The information was a bit hidden in NOTES. + +random_r.3 + Michael Kerrisk [Jan Ziak] + 'buf.state' must be initialized to NULL before calling initstate_r() + See https://bugzilla.kernel.org/show_bug.cgi?id=192801. + Michael Kerrisk + Add some usage notes for setstate_r() + Michael Kerrisk + Note that 'buf' records a pointer to 'statebuf' + See https://sourceware.org/bugzilla/show_bug.cgi?id=3662. + Michael Kerrisk + Add BUGS section pointing out the weirdness of the initstate_r() API + +resolver.3 + Michael Kerrisk + RES_AAONLY, RES_PRIMARY, RES_NOCHECKNAME, RES_KEEPTSIG are deprecated + These options were never implemented; since glibc 2.25, they + are deprecated. + Michael Kerrisk + The RES_NOIP6DOTINT is removed in glibc 2.25 + Michael Kerrisk + Note that RES_BLAST was unimplemented and is now deprecated + Michael Kerrisk + RES_USE_INET6 is deprecated since glibc 2.25 + Michael Kerrisk + RES_USEBSTRING was removed in glibc 2.25 + +resolver.3 +resolv.conf.5 + Michael Kerrisk + Note that RES_USEBSTRING defaults to off + +scandir.3 + Michael Kerrisk [Ian Jackson] + Fix errors in example program + See http://bugs.debian.org/848231. + Michael Kerrisk + Improve logic of the example program + +scanf.3 + Michael Kerrisk + Document the quote (') modifier for decimal conversions + +sem_post.3 +setjmp.3 + Michael Kerrisk + SEE ALSO: add signal-safety(7) + +sem_wait.3 + Michael Kerrisk [Fabjan Sukalia] + Remove statement that SA_RESTART does not cause restarting + This has not been true since Linux 2.6.22. The description + of EINTR maintains a reference to signal(7), which explains + the historical details. + + See https://bugzilla.kernel.org/show_bug.cgi?id=192071 + +sleep.3 + Michael Kerrisk [Mike Frysiner] + Note that sleep() is implemented via nanosleep(2) + See https://bugzilla.kernel.org/show_bug.cgi?id=73371. + Michael Kerrisk [Mike Frysinger] + Note that sleep() sleeps for a real-time number of seconds + See https://bugzilla.kernel.org/show_bug.cgi?id=73371. + Michael Kerrisk + Convert BUGS text to "Portability notes" subsection + The existing text is not a bug, as such. + Michael Kerrisk + DESCRIPTION: minor reworking + +strerror.3 + Heinrich Schuchardt + Indicate reasonable buffer size for strerror_r() and strerror_l() + Add a hint which buffer size is needed for + strerror_r() and strerror_l(). + +strverscmp.3 + Michael Kerrisk [Vivenzio Pagliari] + Fix comparison error in example program + +system.3 + Michael Kerrisk + In the glibc implementation, fork handlers are not executed by system() + +random.4 + Michael Kerrisk [Jon Jensen] + Note that entropy_avail will be a number in the range 0..4096 + +core.5 + Michael Kerrisk + Clarify that dumping program's initial CWD is root directory + Michael Kerrisk + The target of core dump piping can also be a script + +filesystems.5 + Michael Kerrisk + SEE ALSO: add btrfs(5), nfs(5), tmpfs(5) + +intro.5 + Michael Kerrisk + Document the reality that by now Section 5 also covers filesystems + There are by now, from various filesystem projects, various + pages in Section 5 that document different filesystems. + Change intro(5) to reflect that. + + Documented after following: http://bugs.debian.org/847998 + +proc.5 + Mike Frysinger [Michael Kerrisk] + Clarify /proc/pid/environ behavior + /proc/pid/environ reflects process environment at + *start* of program execution; it is set at time of execve(2) + Michael Kerrisk + Add reference to slabinfo(5) in discussion of /proc/meminfo 'Slab' field + Michael Kerrisk + Add entries for "keys" files that refer reader to keyrings(7) + Michael Kerrisk + Remove duplicate /proc/[pid]/seccomp entry + Michael Kerrisk + Mention other system calls that create 'anon_inode' file descriptors + Mention a few other system calls that create file descriptors + that display an 'anon_inode' symlink in /proc/PID/fd + Michael Kerrisk + Add some detail on overcommit_memory value 1 + Michael Kerrisk + Add reference to vdso(7) in discussion of /proc/PID/maps + +resolv.conf.5 + Michael Kerrisk + ip6-bytestring was removed in glibc 2.25 + Michael Kerrisk + The ipc-dotint and no-ip6-dotint options were removed in glibc 2.25 + Michael Kerrisk + The 'inet6' option is deprecated since glibc 2.25 + +slabinfo.5 + Michael Kerrisk + SEE ALSO: add slabtop(1) + +capabilities.7 + Michael Kerrisk [Casey Schaufler] + Add subsection with notes to kernel developers + Provide some notes to kernel developers considering how to choose + which capability should govern a new kernel feature. + Michael Kerrisk + Further enhance the recommendation against new uses of CAP_SYS_ADMIN + Michael Kerrisk + Explicitly point from CAP_SYS_ADMIN to "Notes for kernel developers" + Michael Kerrisk + Add another case for CAP_DAC_READ_SEARCH + Michael Kerrisk + Refer to execve(2) for the reasons that file capabilities may be ignored + Michael Kerrisk + Document a new use of CAP_SYS_RESOURCE + Michael Kerrisk + Add some more operations governed by CAP_SYS_ADMIN + Michael Kerrisk + Adjust references to chattr(1) to point to ioctl_iflags(2) + +environ.7 + Michael Kerrisk + Mention prctl(2) PR_SET_MM_ENV_START and PR_SET_MM_ENV_END operations + +inotify.7 + Michael Kerrisk + Point out that inotify monitoring is inode based + +ip.7 + Michael Kerrisk + SEE ALSO: add ip(8) + +man.7 +uri.7 + Jakub Wilk + Use "www.kernel.org" in example URLs + Apparently www.kernelnotes.org is now a spam site. + +mount_namespaces.7 + Michael Kerrisk [Rob Landley] + Rework the discussion of defaults for mount propagation types + Add rather more detail. In particular, note the cases where the + default propagation type is MS_PRIVATE vs MS_SHARED. + +namespaces.7 + Michael Kerrisk + EXAMPLE: fix an error in shell session + Michael Kerrisk + EXAMPLE: rename the example program + Use a more generic name, since this program may be expanded + in various ways in the future. + Michael Kerrisk + SEE ALSO: add ip-netns(8) + Michael Kerrisk + Remove content split out into ioctl_ns(2) + +netlink.7 + Michael Kerrisk + NETLINK_IP6_FW went away in Linux 3.5 + Michael Kerrisk + NETLINK_W1 went away in Linux 2.6.18 + Michael Kerrisk + Add NETLINK_SCSITRANSPORT to list + Michael Kerrisk + Add NETLINK_RDMA to list + Michael Kerrisk + NETLINK_FIREWALL was removed in Linux 3.5 + Michael Kerrisk + NETLINK_NFLOG was removed in Linux 3.17 + Jakub Wilk + Update libnl homepage URL + The original URL is 404. + +pid_namespaces.7 +user_namespaces.7 + Michael Kerrisk + Adjust references to namespaces(7) to ioctl_ns(2) + +pid_namespaces.7 + Keno Fischer + CLONE_SIGHAND|CLONE_VM|CLONE_NEWPID is no longer disallowed + +pipe.7 + Michael Kerrisk + Since Linux 4.9, pipe-max-size is ceiling for the default pipe capacity + Michael Kerrisk + Clarify that default pipe capacity is 16 pages + The statement that the default pipe capacity is 65536 bytes + is accurate only on systems where the page size is 4096B. + See the use of PIPE_DEF_BUFFERS in the kernel source. + +random.7 + Michael Kerrisk + Mention getentropy(3) + Michael Kerrisk + SEE ALSO: add getentropy(3) + Michael Kerrisk + SEE ALSO: add getauxval(3) + A small hint to the reader that some random bytes arrive + in the auxiliary vector. + +signal.7 + Michael Kerrisk + SIGSYS: add reference to seccomp(2) + Michael Kerrisk + Change description of SIGSYS to "Bad system call" + This is the more typical definition. + Michael Kerrisk + SIGPIPE: add reference to pipe(7) + Michael Kerrisk + SIGXFSZ: add reference to setrlimit(2) + Michael Kerrisk + Add a name for SIGEMT + Michael Kerrisk + SIGXCPU: add reference to setrlimit(2) + Michael Kerrisk + Migrated signal-safety discussion to new signal-safety(7) page + +unix.7 + Michael Kerrisk [Sergey Polovko] + Since Linux 3.4, UNIX domain sockets support MSG_TRUNC + This was correctly noted in recv(2), but the unix(7) page + was not correspondingly updated for the Linux 3.4 change. + Michael Kerrisk [Willy Tarreau] + Document ETOOMANYREFS for SCM_RIGHTS send exceeding RLIMIT_NOFILE limit + +user_namespaces.7 + Michael Kerrisk + Change page cross reference: keyctl(2) ==> keyrings(7) + +ld.so.8 + Michael Kerrisk + LD_BIND_NOT has effect only for function symbols + Michael Kerrisk + Describe use of LD_DEBUG with LD_BIND_NOT + Michael Kerrisk + In secure mode, LD_AUDIT restricts the libraries that it will load + Michael Kerrisk + LD_AUDIT understands $ORIGIN, $LIB, and $PLATFORM + + + +==================== Changes in man-pages-4.11 ==================== + +Released: 2017-05-03, Baden, Switzerland + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alexander Alemayhu +Alexander Miller +Andrea Arcangeli +Andreas Dilger +Andrew Clayton +Arnd Bergmann +Ben Dog +Carlos O'Donell +Chema Gonzalez +Christian Brauner +Cyril Hrubis +David Howells +Dmitry V. Levin +Florian Weimer +Francois Saint-Jacques +Frank Theile +Georg Sauthoff +Ian Abbott +Jakub Wilk +Jan Heberer +Marcin Ślusarz +Marko Myllynen +Matthew Wilcox +Michael Kerrisk +Mike Frysinger +Mike Rapoport +Nicolas Biscos +Nicolas Iooss +Nikos Mavrogiannopoulos +Nominal Animal +Silvan Jegen +Stephan Bergmann +Walter Harms +Zack Weinberg +丁贵强 + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +ioctl_userfaultfd.2 + Michael Kerrisk, Mike Rapoport + New page describing ioctl(2) operations for userfaultfd + +statx.2 + David Howells, Michael Kerrisk [Andreas Dilger] + New page describing statx(2) system call added in Linux 4.11 + +userfaultfd.2 + Mike Rapoport, Michael Kerrisk [Andrea Arcangeli] + New page describing userfaultfd(2) system call. + +pthread_atfork.3 + Michael Kerrisk + New page describing pthread_atfork(3) + +slabinfo.5 + Michael Kerrisk + Rewrite to try to bring the content close to current reality + There's still gaps to fill in, but the existing page + was in any case hugely out of date. + +inode.7 + Michael Kerrisk + New page with information about inodes + David Howells provided a statx(2) page that duplicated much of + the information from stat(2). Avoid such duplication + by moving the common information in stat(2) and statx(2) + to a new page. + + +Renamed pages +-------------- + +ioctl_console.2 + Michael Kerrisk + Renamed from console_ioctl.4 + Most ioctl() man pages are in section 2, so move this one there + for consistency. + Michael Kerrisk + Note type of 'argp' for a various operations + For some commands, there was no clear statement about the type + of the 'argp' argument. + +ioctl_tty.2 + Michael Kerrisk + Renamed from tty_ioctl(4) + All other ioctl(2) pages are in section 2. Make this + page consistent. + Michael Kerrisk + Packet mode state change events give POLLPRI events for poll(2) + + +Newly documented interfaces in existing pages +--------------------------------------------- + +ioctl_ns.2 + Michael Kerrisk + Document the NS_GET_NSTYPE operation added in Linux 4.11 + Michael Kerrisk + Document the NS_GET_OWNER_UID operation added in Linux 4.11 + +proc.5 + Michael Kerrisk + Document /proc/sys/kernel/sched_child_runs_first + +namespaces.7 + Michael Kerrisk + Document the /proc/sys/user/* files added in Linux 4.9 + +socket.7 + Francois Saint-Jacques, Michael Kerrisk + Document SO_INCOMING_CPU + + +New and changed links +--------------------- + +console_ioctl.4 + Michael Kerrisk + Link for old name of ioctl_console(2) page + +tty_ioctl.4 + Michael Kerrisk + Link for old name of ioctl_tty(2) page + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Change page cross-references from tty_ioctl(4) to ioctl_tty(2) + Michael Kerrisk + Change page cross-references for console_ioctl(4) to ioctl_console(2) + + +Changes to individual pages +--------------------------- + +alarm.2 + Michael Kerrisk + SEE ALSO: add timer_create(2) and timerfd_create(2) + +chmod.2 +fsync.2 +mkdir.2 +mknod.2 +open.2 +truncate.2 +umask.2 +utime.2 +utimensat.2 + Michael Kerrisk + Add/replace references to inode(7) + +clone.2 + Michael Kerrisk + CLONE_NEWCGROUP by an unprivileged process also causes an EPERM error + +clone.2 +unshare.2 + Michael Kerrisk + Exceeding one of the limits in /proc/sys/user/* can cause ENOSPC + Michael Kerrisk + CLONE_NEWPID yields ENOSPC if nesting limit of PID namespaces is reached + Michael Kerrisk + Exceeding the maximum nested user namespace limit now gives ENOSPC + Formerly, if the limit of 32 nested user namespaces was exceeded, + the error EUSERS resulted. Starting with Linux 4.9, the error + is ENOSPC. + +epoll_ctl.2 + Michael Kerrisk + Defer to poll(2) for an explanation of EPOLLIN + Michael Kerrisk [Nicolas Biscos] + EPOLLERR is also set on write end of a pipe when the read end is closed + Michael Kerrisk [Nicolas Biscos] + Give the reader a clue that the 'events' field can be zero + 'events' specified as zero still allows EPOLLHUP and + EPOLLERR to be reported. + +_exit.2 + Michael Kerrisk + On exit, child processes may be inherited by a "subreaper" + It is no longer necessarily true that orphaned processes + are inherited by PID 1. + Michael Kerrisk + Only the least significant byte of exit status is passed to the parent + +fcntl.2 + Michael Kerrisk + Mention memfd_create() in the discussion of file seals + Give the reader a clue about what kinds of objects can + be employed with file seals. + Michael Kerrisk + File seals are not generally applicable to tmpfs(5) files + As far as I can see, file seals can be applied only to + memfd_create(2) file descriptors. This was checked by experiment + and by reading mm/shmem.c::shmem_get_inode((), where one finds + the following line that applies to all new shmem files: + + info->seals = F_SEAL_SEAL; + + Only in the code of the memfd_create() system call is this + setting reversed (in mm/shmem.c::memfd_create): + + if (flags & MFD_ALLOW_SEALING) + info->seals &= ~F_SEAL_SEAL; + +fork.2 + Michael Kerrisk + SEE ALSO: add pthread_atfork(3) + +getdents.2 +open.2 +stat.2 +statx.2 + Michael Kerrisk + SEE ALSO: add inode(7) + +getdtablesize.2 +attr.5 + Alexander Miller + Move .so directive to first line + Improves compatibility with the man and other dumb tools + that process man page files. + +getpid.2 + Michael Kerrisk + Mention init(1) and "subreapers" in discussion of parent PID + +ioctl_list.2 + Cyril Hrubis [Arnd Bergmann] + BLKRASET/BLKRAGET take unsigned long + +ioctl_ns.2 + Michael Kerrisk + ERRORS: document ENOTTY + +kexec_load.2 +sched_setaffinity.2 +bootparam.7 + Michael Kerrisk + Documentation/kernel-parameters.txt is now in Documentation/admin-guide/ + +lseek.2 + Michael Kerrisk + SEE ALSO: add fallocate(2) + Both of these pages discuss file holes. + +mincore.2 + Michael Kerrisk + SEE ALSO: add fincore(1) + +mmap.2 + Michael Kerrisk + Remove ancient reference to flags that appear on some other systems + MAP_AUTOGROW, MAP_AUTORESRV, MAP_COPY, and MAP_LOCAL may have + appeared on some systems many years ago, but the discussion here + mentions no details and the systems and flags probably ceased to + be relevant long ago. So, remove this text. + Michael Kerrisk + SEE ALSO: add userfaultfd(2) + +open.2 + Michael Kerrisk + Add statx() to list of "at" calls in rationale discussion + +poll.2 + Michael Kerrisk + Expand discussion of POLLPRI + Michael Kerrisk [Nicolas Biscos] + POLLERR is also set on write end of a pipe when the read end is closed + +posix_fadvise.2 + Michael Kerrisk + SEE ALSO: add fincore(1) + +prctl.2 + Mike Frysinger + PR_SET_MM: Refine CONFIG_CHECKPOINT_RESTORE requirement + The Linux 3.10 release dropped the c/r requirement and opened it + up to all users. + Mike Frysinger + PR_SET_MM: Document new PR_SET_MM_MAP{,_SIZE} helpers + Mike Frysinger + PR_SET_MM: Document arg4/arg5 zero behavior + The kernel will immediately reject calls where arg4/arg5 are not + zero. See kernel/sys.c:prctl_set_mm(). + Michael Kerrisk + Explain rationale for use of subreaper processes + Michael Kerrisk + Note semantics of child_subreaper setting on fork() and exec() + Michael Kerrisk + Improve description of PR_SET_CHILD_SUBREAPER + +rename.2 + Michael Kerrisk [Georg Sauthoff] + Note that there is no glibc wrapper for renameat2() + +sched_setaffinity.2 + Michael Kerrisk + SEE ALSO: add get_nprocs(3) + +select.2 + Michael Kerrisk [Matthew Wilcox, Carlos O'Donell] + Linux select() is buggy wrt POSIX in its check for EBADF errors + Michael Kerrisk + Show correspondence between select() and poll() readiness notifications + Michael Kerrisk + Give a hint that sets must be reinitialized if using select() in a loop + Michael Kerrisk + Refer to POLLPRI in poll(2) for info on exceptional conditions + Michael Kerrisk + Move mislocated text describing the self-pipe text from BUGS to NOTES + +sigaction.2 + Michael Kerrisk + Show the prototype of an SA_SIGINFO signal handler + +signalfd.2 + Michael Kerrisk + SIGKILL and SIGSTOP are silently ignored in 'mask' + +sigprocmask.2 + Dmitry V. Levin + Do not specify an exact value of rt_sigprocmask's 4th argument + As sizeof(kernel_sigset_t) is not the same for all architectures, + it would be better not to mention any numbers as its value. + Michael Kerrisk + 'set' and 'oldset' can both be NULL + +sigwaitinfo.2 + Michael Kerrisk + sigwaitinfo() can't be used to accept synchronous signals + +socketcall.2 + Mike Frysinger + Document call argument + +stat.2 + Michael Kerrisk + Remove information migrated to inode(7) page + Michael Kerrisk + Restructure field descriptions as a hanging list + Michael Kerrisk + Remove "Other systems" subsection + These details about other systems were added in 1999, + and were probably of limited use then, and even less today. + However, they do clutter the page, so remove them. + Michael Kerrisk + DESCRIPTION: add list entries for 'st_uid' and 'st_gid' + Michael Kerrisk + Add some subsection headings to ease readability + David Howells + ERRORS: correct description of ENOENT + Michael Kerrisk + Give 'struct stat' argument a more meaningful name ('statbuf') + Marcin Ślusarz + Tweak description of AT_EMPTY_PATH + Currently it says when dirfd is AT_FDCWD it can be something + other than directory, which doesn't make much sense. Just swap + the order of sentences. + Michael Kerrisk + Add slightly expanded description of 'st_ino' field + Michael Kerrisk + DESCRIPTION: add a list entry for 'st_ino' + Michael Kerrisk + DESCRIPTION: add a list entry for 'st_nlinks' field + +syscalls.2 + Michael Kerrisk + Add membarrier(2) + Michael Kerrisk + Fix kernel version for userfaultfd(2) + Michael Kerrisk + Linux 4.11 added statx() + Michael Kerrisk + Include deprecated getunwind(2) in list + +wait.2 + Michael Kerrisk + Orphaned children may be adopted by a "subreaper", rather by than PD 1 + +bzero.3 + Michael Kerrisk [Zack Weinberg] + Add correct header file for explicit_bzero() + +cfree.3 + Michael Kerrisk + cfree() is removed from glibc in version 2.26 + +exit.3 + Michael Kerrisk + Improve discussion of zombie processes + +getentropy.3 + Nikos Mavrogiannopoulos [Michael Kerrisk, Florian Weimer] + Correct header file + Michael Kerrisk [Frank Theile] + SYNOPSIS: add missing return type for getentropy() declaration + +grantpt.3 + Michael Kerrisk + Tell a more nuanced story about what grantpt() does or does not do + +insque.3 + Michael Kerrisk + SEE ALSO: add queue(3) + +queue.3 + Michael Kerrisk + SEE ALSO: add insque(3) + +shm_open.3 + Michael Kerrisk + Clarify that POSIX shared memory uses tmpfs(5) + +syslog.3 + Michael Kerrisk [Ian Abbott, Walter Harms] + Reorganize page text for easier parsing and better readability + Michael Kerrisk + Various rewordings and improvements + Michael Kerrisk + Note default value for 'facility' when calling openlog() + Michael Kerrisk + SEE ALSO: add journalctl(1) + +ttyname.3 + Dmitry V. Levin + Document ENODEV error code + Christian Brauner + NOTES: warn about a confusing case that may occur with mount namespaces + +wcsdup.3 + Jan Heberer + RETURN VALUE: fix error in return value description + Return value for failure was accidentally changed from NULL to + -1 in man-pages commit 572acb41c48b6b8e690d50edff367d8b8b01702a. + +elf.5 + Michael Kerrisk + SEE ALSO: add elfedit(1), nm(1), size(1), strings(1), and strip(1) + +nsswitch.conf.5 + Florian Weimer + Mention sudoers + It turns out that sudo drops things into nsswitch.conf, too. + +proc.5 + Michael Kerrisk + Refer to namespaces(7) for discussion of /proc/sys/user/* files + Michael Kerrisk + Simplify /proc/slabinfo entry + Don't repeat (out-of-date) info from slabinfo(5); just defer to + that page. + +tmpfs.5 + Michael Kerrisk + tmpfs supports extended attributes, but not 'user' extended attributes + +environ.7 + Jakub Wilk + Fix name of function that honors TMPDIR + tempnam() takes the TMPDIR environment variable into account, unlike + tmpnam(), which always creates pathnames within /tmp. + +hostname.7 + Marko Myllynen + Use lower case for hostname example + Marko Myllynen + Use generic names in examples + Marko Myllynen + Describe accepted characters for hostname + +inotify.7 + Michael Kerrisk [Nicolas Iooss] + Mounting a filesystem on top of a monitored directory causes no event + +man-pages.7 + Michael Kerrisk + Note preferred approach for 'duplicate' errors + +pid_namespaces.7 + Michael Kerrisk + The maximum nesting depth for PID namespaces is 32 + +user_namespaces.7 + Stephan Bergmann + Fixes to example + While toying around with the userns_child_exec example program on the + user_namespaces(7) man page, I noticed two things: + + * In the EXAMPLE section, we need to mount the new /proc before + looking at /proc/$$/status, otherwise the latter will print + information about the outer namespace's PID 1 (i.e., the real + init). So the two paragraphs need to be swapped. + + * In the program source, make sure to close pipe_fd[0] in the + child before exec'ing. + +pthreads.7 + Michael Kerrisk + SEE ALSO: add pthread_rwlockattr_setkind_np(3) + +pty.7 + Michael Kerrisk + Mention a couple of other applications of pseudoterminals + +sem_overview.7 + Michael Kerrisk + SEE ALSO: add shm_overview(7) + +signal.7 + Michael Kerrisk + SEE ALSO: add sigreturn(2) + +tcp.7 + Michael Kerrisk + Note indications for OOB data given by select(2) and poll(2) + Chema Gonzalez + tcp_abc was removed in 3.9 + +xattr.7 + Michael Kerrisk + SEE ALSO: add ioctl_iflags(2) + People sometimes confuse xattrs and inode flags. Provide a link + to the page that describes inode flags to give them a tip. + +ld.so.8 + Michael Kerrisk + Mention quoting when using "Rpath tokens" in LD_AUDIT and LD_PRELOAD + Michael Kerrisk + Expand description of /etc/ld.so.preload + Michael Kerrisk + Mention ldconfig(8) in discussion of /etc/ld.so.cache + +zdump.8 + Jakub Wilk + Add OPTIONS section heading + + +==================== Changes in man-pages-4.12 ==================== + +Released: 2017-07-13, London + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alex Henrie +Andi Kleen +Arjun Shankar +Brad Bendily +Cameron Wright +Carlos O'Donell +Darrick J. Wong +David Lewis +DJ Delorie +Douglas Caetano dos Santos +Dr. Tobias Quathamer +Eric Biggers +Ferdinand Thiessen +G. Branden Robinson +Heinrich Schuchardt +Henry Bent +Jakub Wilk +Janne Snabb +Joe Brown +Jorge Nerin +Kirill Tkhai +lilydjwg +Long Wang +Michael Kerrisk +Mike Frysinger +Nadav Har'El +NeilBrown +Pavel Tikhomirov +Quentin Rameau +Ruben Kerkhof +sulit +石井大貴 + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +ioctl_getfsmap.2 + Darrick J. Wong + Document the GETFSMAP ioctl + Document the new GETFSMAP ioctl that returns the physical layout of a + (disk-based) filesystem. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +namespaces.7 + Kirill Tkhai [Michael Kerrisk] + Document the /proc/[pid]/ns/pid_for_children file + + +Changes to individual pages +--------------------------- + +ldd.1 + Michael Kerrisk + 'objdump -p prog | grep NEEDED' doesn't give quite same info as 'ldd' + +chmod.2 + Michael Kerrisk + Put fchmod() feature test macro requirements in a more readable format + Michael Kerrisk + Note glibc 2.24 feature test macro requirements changes for fchmod() + +chown.2 + Michael Kerrisk + When file owner or group is changed, file capabilities are cleared + Michael Kerrisk + Changes to file owner by root also clear set-UID and set-GID bits + +clone.2 + Michael Kerrisk + Update BUGS to reflect fact that PID caching was removed in glibc 2.25 + +epoll_wait.2 + Michael Kerrisk + Clarify semantics of returned 'data' field + The returned 'data' is the 'data' most recently set via + epoll_ctl(). + +get_mempolicy.2 + Michael Kerrisk [Nadav Har'El, Andi Kleen] + SYNOPSIS: fix return type of get_mempolicy() + See https://bugzilla.kernel.org/show_bug.cgi?id=97051 + +getpid.2 + Carlos O'Donell, Michael Kerrisk + Note that PID caching is removed as of glibc 2.25 + Since glibc 2.25 the PID cache is removed. + + Rationale given in the release notes: + https://sourceware.org/glibc/wiki/Release/2.25#pid_cache_removal + +ioctl.2 + Michael Kerrisk + SEE ALSO: add ioctl_getfsmap(2) + +ioctl_getfsmap.2 + Michael Kerrisk + Fix ordering of sections + Michael Kerrisk + Add VERSIONS section + Michael Kerrisk + ERRORS: order alphabetically + +madvise.2 + Michael Kerrisk + Remove bogus text re POSIX_MADV_NOREUSE + There is a POSIX_FADV_NOREUSE for posix_fadvise(), + but no POSIX_MADV_NOREUSE for any API in POSIX. + +membarrier.2 + Michael Kerrisk + Add ENOSYS error for 'nohz_full' CPU setting + +mount.2 + NeilBrown + Revise description of MS_REMOUNT | MS_BIND + MS_REMOUNT|MS_BIND affects all per-mount-point + flag. MS_RDONLY is only special because it, + uniquely, is both a per-mount-point flag *and* a + per-filesystem flag. + + So the sections of per-mount-point flags and + MS_REMOUNT can usefully be clarified. + +open.2 + Michael Kerrisk + Note some further advantages of the *at() APIs + +pipe.2 + Michael Kerrisk + SEE ALSO: add tee(2) and vmsplice(2) + +readv.2 + Michael Kerrisk + glibc 2.26 adds library support for preadv2() and pwritev2() + +sched_setaffinity.2 + Michael Kerrisk + Mention cpuset cgroups as a cause of EINVAL error + +seccomp.2 + Mike Frysinger + Expand SECCOMP_RET_KILL documentation + +sigaction.2 + Michael Kerrisk + Note feature test macro requirements for 'si_code' constants + Michael Kerrisk + Add a subheading for the description of 'si_code' + Michael Kerrisk + TRAP_BRANCH and TRAP_HWBKPT are present only on IA64 + +sigaltstack.2 + Michael Kerrisk + Note that specifying SS_ONSTACK in ss.ss_flags decreases portability + In the Illumos source (which presumably mirrors its Solaris + ancestry), there is this check in the sigaltstack() + implementation: + + if (ss.ss_flags & ~SS_DISABLE) + return (set_errno(EINVAL)); + + And in the FreeBSD source we find similar: + + if ((ss->ss_flags & ~SS_DISABLE) != 0) + return (EINVAL); + Michael Kerrisk + Note buggy addition of ss.ss_flags==SS_ONSTACK + Note buggy addition of ss.ss_flags==SS_ONSTACK as a synonym + for ss_flags==0. No other implementation does this, AFAIK. + And it was not needed :-(. + Michael Kerrisk + Specifying 'ss' returns the current settings without changing them + Michael Kerrisk + Give 'oss' argument a more meaningful name: 'old_ss' + Michael Kerrisk + Some minor reworking of the text + Michael Kerrisk + ERRORS: update description of EINVAL error + +splice.2 +tee.2 +vmsplice.2 + Michael Kerrisk + SEE ALSO: add pipe(7) + +splice.2 + Michael Kerrisk + ERRORS: split EINVAL error cases + Michael Kerrisk + ERRORS: add EINVAL for case where both descriptors refer to same pipe + +timer_create.2 + Michael Kerrisk + Document the CONFIG_POSIX_TIMERS option added in Linux 4.10 + +wait.2 + Michael Kerrisk + Note glibc 2.26 changes to feature test macro requirements for waitid() + +acosh.3 +asinh.3 +atanh.3 + Alex Henrie + Remove C89 designation. + See https://bugzilla.kernel.org/show_bug.cgi?id=196319 + +bsd_signal.3 + Michael Kerrisk + Note feature test macro requirements changes for glibc 2.26 + +dl_iterate_phdr.3 + Michael Kerrisk + dl_iterate_phdr() shows the order in which objects were loaded + dl_iterate_phdr() tells us not just which objects are + loaded, but also the order in which they are loaded + (the "link-map order"). Since the order is relevant for + understanding symbol resolution, give the reader this clue. + Michael Kerrisk + Expand the code example, and show sample output + Michael Kerrisk + List values for the 'p_type' field + +dlsym.3 + Michael Kerrisk + _GNU_SOURCE is needed to get RTLD_DEFAULT and RTLD_NEXT definitions + +flockfile.3 + Michael Kerrisk + Note glibc 2.24 feature test macro requirement changes + +fpathconf.3 + Michael Kerrisk + Rework RETURN VALUE description to add more detail + Michael Kerrisk + Add an errors section + Michael Kerrisk + Largely rewrite the description of _PC_CHOWN_RESTRICTED + Michael Kerrisk + Rewrite description of _PC_PIPE_BUF + The existing description was not accurate, and lacked details. + +ftw.3 + Michael Kerrisk + BUGS: document a probable glibc regression in FTW_SLN case + See https://bugzilla.redhat.com/show_bug.cgi?id=1422736 + and http://austingroupbugs.net/view.php?id=1121. + +getaddrinfo.3 + Quentin Rameau + Fix _POSIX_C_SOURCE value for getaddrinfo() + The correct _POSIX_C_SOURCE value is 200112L, not 201112L in features.h. + +getcontext.3 + Carlos O'Donell + Exemplar structure should use 'ucontext_t'. + +getgrent.3 + Michael Kerrisk + Note glibc 2.22 changes for feature test macro requirements + +grantpt.3 +ptsname.3 +unlockpt.3 + Ferdinand Thiessen [Michael Kerrisk] + Update feature test macro-requirements for glibc 2.24 + +if_nametoindex.3 + Douglas Caetano dos Santos + Add ENODEV error for if_nametoindex() + +malloc.3 + Michael Kerrisk + Document the reallocarray() added in glibc 2.26 + +nl_langinfo.3 + Michael Kerrisk + Note feature test macro requirements for nl_langinfo_l() + +posix_madvise.3 + Dr. Tobias Quathamer + Remove paragraph about POSIX_FADV_NOREUSE + POSIX_FADV_NOREUSE is documented for posix_fadvise, and a + corresponding POSIX_MADV_NOREUSE flag is not specified by POSIX. + See https://bugs.debian.org/865699 + +ptsname.3 + Michael Kerrisk [Arjun Shankar] + Since glibc 2.26, ptsname_r() no longer gives EINVAL for buf==NULL + +rand.3 + Michael Kerrisk + Note glibc 2.24 feature test macro requirement changes for rand_r() + +resolver.3 + Michael Kerrisk + Add basic notes on 'op' argument of res_nmkquery() and res_mkquery() + +sigpause.3 + Michael Kerrisk + Note glibc 2.26 changes to feature test macro requirements + +sigwait.3 + Michael Kerrisk + Note glibc 2.26 feature test macro changes + +strtol.3 + Heinrich Schuchardt + Mention 0X prefix + The prefix 0x may be capitalized as 0X. + + See ISO/IEC 9899:1999. + +sysconf.3 + Michael Kerrisk [Pavel Tikhomirov] + Rework RETURN VALUE description to add more detail + Make the discussion clearer, and add a few details. + Also, fix the problem report from Pavel Tikhomirov + who noted that the man page falsely said that errno + is not changed on a successful return. + + Addresses https://bugzilla.kernel.org/show_bug.cgi?id=195955 + Michael Kerrisk + Add ERRORS section + +ttyslot.3 + Michael Kerrisk + Fix error in feature test macro requirements + Michael Kerrisk + Note feature test macro requirements changes in glibc 2.24 + Michael Kerrisk + Clarify details of use of file + +unlocked_stdio.3 + Michael Kerrisk + Note glibc 2.24 feature test macro requirement changes + +elf.5 + Michael Kerrisk + SEE ALSO: add dl_iterate_phdr(3) + +nsswitch.conf.5 + DJ Delorie + Clarify group merge rules + This minor patch clarifies when merging is not done, + and how duplicate entries are merged. + +proc.5 + Michael Kerrisk + Document that 'iowait' field of /proc/stat is unreliable + Text taken from Chao Fan's kernel commit 9c240d757658a3ae996. + +slabinfo.5 + Michael Kerrisk [Jorge Nerin] + SEE ALSO: add some references to relevant kernel source files + +tmpfs.5 + Michael Kerrisk + SEE ALSO: add memfd_create(2), mmap(2), shm_open(3) + +capabilities.7 + Michael Kerrisk + Clarify the effect on process capabilities when UID 0 does execve(2) + Michael Kerrisk + Note effect on capabilities when a process with UID != 0 does execve(2) + Michael Kerrisk [David Lewis] + Fix reversed descriptions of CAP_MAC_OVERRIDE and CAP_MAC_ADMIN + Michael Kerrisk + SEE ALSO: add filecap(8), netcap(8), pscap(8) + +cgroup_namespaces.7 + Michael Kerrisk + Add some further explanation of the example shell session + Michael Kerrisk + Fix a bug in shell session example + +inode.7 + Michael Kerrisk + Note glibc 2.24 feature test macro changes for S_IFSOCK and S_ISSOCK() + +man.7 + G. Branden Robinson + Undocument "URL" macro in man(7) in favor .UR+.UE + +pid_namespaces.7 + Michael Kerrisk + Mention /proc/[pid]/ns/pid_for_children + +pipe.7 + Michael Kerrisk + SEE ALSO: add tee(2) and vmsplice(2) + +sigevent.7 + Michael Kerrisk + Mention signal.h header file + +signal.7 + Michael Kerrisk [lilydjwg] + Since Linux 3.8, read(2) on an inotify FD is restartable with SA_RESTART + See https://bugzilla.kernel.org/show_bug.cgi?id=195711 + Michael Kerrisk + read() from an inotify FD is no longer interrupted by a stop signal + (Change was in Linux 3.8.) + +tcp.7 + Michael Kerrisk + Document value '2' for tcp_timestamps + Since Linux 4.10, the value '2' is meaningful for tcp_timestamps + Ruben Kerkhof + Change default value of tcp_frto + The default changed in c96fd3d461fa495400df24be3b3b66f0e0b152f9 + (Linux 2.6.24). + +ld.so.8 + Michael Kerrisk + Greatly expand the explanation of LD_DYNAMIC_WEAK + Carlos O'Donell + Expand DT_RUNPATH details. + ld.so.8: Expand DT_RUNPATH details. + + Every 3 years we get asked why DT_RUNPATH doesn't work like DT_RPATH. + The most recent question was here: + https://www.sourceware.org/ml/libc-help/2017-06/msg00013.html + + We need to expand the description of DT_RUNPATH to cover this + situation and explain that the DT_RUNPATH entries apply only to the + immediate DT_NEEDED, not that of another, say dlopen'd child object. + Michael Kerrisk + Since glibc 2.2.5, LD_PROFILE is ignored in secure-execution mode + Michael Kerrisk + Make notes on secure-execute mode more prominent + Place each note on secure-execution mode in a separate + paragraph, to make it more obvious. + Michael Kerrisk + Note that libraries in standard directories are not normally set-UID + In secure mode, LD_PRELOAD loads only libraries from standard + directories that are marked set-UID. Note that it is unusual for + a library to be marked in this way. + Michael Kerrisk + SEE ALSO: add elf(5) + Michael Kerrisk + Note version where secure-execution started ignoring LD_USE_LOAD_BIAS + Michael Kerrisk + Correct glibc version that ignores LD_SHOW_AUXV in secure-execution mode + Ignored since 2.3.4 (not 2.3.5). + Michael Kerrisk + Rewrite LD_DEBUG_OUTPUT description and note that .PID is appended + + +==================== Changes in man-pages-4.13 ==================== + +Released: 2017-09-15, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Aleksa Sarai +Alex Henrie +Benjamin Peterson +Bjarni Ingi Gislason +Cyrill Gorcunov +Darrick J. Wong +David Wilder +Dennis Knorr +Don Brace +Douglas Caetano dos Santos +Elliott Hughes +Eugene Syromyatnikov +Fabio Scotoni +Florian Weimer +Jakub Wilk +Jason Noakes +Jens Axboe +Jonas Grabber +Kees Cook +Konstantin Shemyak +Li Zhijian +Marko Myllynen +Mark Wielaard +Meelis Roos +Michael Kerrisk +Mike Rapoport +NeilBrown +Otto Ebeling +Paul Eggert +Rick Jones +Sage Weil +Sam Varshavchik +Sergey Z. +Shrikant Giridhar +Stephan Müller +Sukadev Bhattiprolu +Tej Chajed +Thiago Jung Bauermann +Vincent Bernat +Yubin Ruan +Ильдар Низамов + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pthread_mutex_consistent.3 + Yubin Ruan, Michael Kerrisk + New page documenting pthread_mutex_consistent(3) + +pthread_mutexattr_getpshared.3 + Michael Kerrisk + New page for pthread_mutexattr_getpshared(3) and pthread_mutexattr_setpshared(3) + +pthread_mutexattr_init.3 + Michael Kerrisk + New page for pthread_mutexattr_init(3) and pthread_mutexattr_destroy(3) + +pthread_mutexattr_setrobust.3 + Yubin Ruan, Michael Kerrisk + New page for pthread_mutexattr_setrobust(3) and pthread_mutexattr_getrobust(3) + +sysfs.5 + Michael Kerrisk [Mark Wielaard] + New page documenting the sysfs filesystem + Just a skeleton page so far, but perhaps it will be filled out + over time. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +fcntl.2 + Jens Axboe, Michael Kerrisk + Describe the set/get write hints commands that are added in Linux 4.13 + Document F_GET_RW_HINT, F_SET_RW_HINT, F_GET_FILE_RW_HINT, and + F_SET_FILE_RW_HINT. + +ioctl_tty.2 + Aleksa Sarai, Michael Kerrisk + Add TIOCGPTPEER documentation + +kcmp.2 + Cyrill Gorcunov + Add KCMP_EPOLL_TFD description + +keyctl.2 + Eugene Syromyatnikov + Document the KEYCTL_RESTRICT_KEYRING operation + Eugene Syromyatnikov [Stephan Müller] + Document the ability to provide KDF parameters in KEYCTL_DH_COMPUTE + + +New and changed links +--------------------- + +pthread_mutexattr_destroy.3 + Michael Kerrisk + New link to new pthread_mutexattr_init.3 page + +pthread_mutexattr_getrobust.3 +pthread_mutexattr_getrobust_np.3 +pthread_mutexattr_setrobust_np.3 + Michael Kerrisk + New links to new pthread_mutexattr_setrobust.3 page + +pthread_mutexattr_setpshared.3 + Michael Kerrisk + New link to new pthread_mutexattr_getpshared.3 page + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Use .EX/.EE for EXAMPLE programs + +Various pages + Michael Kerrisk + Use consistent markup for code snippets + Change .nf/.fi to .EX/.EE + +Various pages + Michael Kerrisk + Use consistent markup for code snippets + The preferred form is + + .PP/.IP + .in +4n + .EX + + .EE + .in + .PP/.IP + +Various pages + Michael Kerrisk + Formatting fix: replace blank lines with .PP/.IP + Blank lines shouldn't generally appear in *roff source (other + than in code examples), since they create large vertical + spaces between text blocks. + +Various pages + Michael Kerrisk [Bjarni Ingi Gislason] + Add a non-breaking space between a number and a unit (prefix) + Based on a patch by Bjarni Ingi Gislason. + +Various pages + Michael Kerrisk [Bjarni Ingi Gislason] + Use en-dash for ranges + Based on a patch by Bjarni Ingi Gislason. + +A few pages + Michael Kerrisk + Fix misordering of sections + Michael Kerrisk + Fix order of SEE ALSO entries + + +Changes to individual pages +--------------------------- + +ldd.1 + Michael Kerrisk + Add more detail on ldd security implications, noting glibc 2.27 changes + +add_key.2 +backtrace.3 +syslog.3 + Michael Kerrisk + Fix misordered SEE ALSO entries + +add_key.2 +request_key.2 +keyrings.7 + Eugene Syromyatnikov + Update Linux documentation pointers + +chown.2 + Michael Kerrisk + Update kernel version in note on support for grpid/nogrpid mount options + There has been no change since Linux 2.6.25, so update the + kernel version to 4.12. + +execve.2 + Michael Kerrisk + SEE ALSO: add get_robust_list(2) + +getrandom.2 + Michael Kerrisk [Fabio Scotoni] + SYNOPSIS: make return type of getrandom() 'ssize_t' + This accords with glibc headers and the Linux kernel source. + +getrlimit.2 + Thiago Jung Bauermann + Mention unit used by RLIMIT_CORE and RLIMIT_FSIZE + Michael Kerrisk + Note that RLIMIT_AS and RLIMIT_DATA are rounded down to system page size + Michael Kerrisk + Mention unit for RLIMIT_DATA + +getrlimit.2 +mmap.2 +malloc.3 + Jonas Grabber + RLIMIT_DATA affects mmap(2) since Linux 4.7 + +get_robust_list.2 + Michael Kerrisk + Detail the operation of robust futex lists + Michael Kerrisk + Since Linux 2.6.28, robust futex lists also have an effect for execve(2) + Michael Kerrisk + Clarify that "thread ID" means "kernel thread ID" + Michael Kerrisk + SEE ALSO: add pthread_mutexattr_setrobust(3) + +ioctl_getfsmap.2 + Darrick J. Wong + Correct semantics of FMR_OF_LAST flag + +ioctl_userfaultfd.2 + Mike Rapoport + Document replacement of ENOSPC with ESRCH + Mike Rapoport + Update uffdio_api.features description + There is no requirement that uffdio_api.features must be zero + for newer kernels. This field actually defines what features + space would like to enable. + +io_submit.2 + Sage Weil + Acknowledge possibility of short return + Note that the return value may be a value less than 'nr' + if not all iocbs were queued at once. + +ipc.2 + Michael Kerrisk + SEE ALSO: add svipc(7) + +keyctl.2 + Eugene Syromyatnikov + mention keyctl_dh_compute(3) and keyctl_dh_compute_alloc (3) + These functions have been added in keyutils 1.5.10 + Eugene Syromyatnikov + Mention ENOMEM in ERRORS + Eugene Syromyatnikov + Update kernel documentation path reference + +move_pages.2 + Otto Ebeling [Michael Kerrisk] + Note permission changes that occurred in Linux 4.13 + +mprotect.2 + Michael Kerrisk [Shrikant Giridhar] + Add warning about the use of printf() in the example code + +open.2 + NeilBrown + Improve O_PATH documentation + - fstatfs is now permitted. + - ioctl isn't, and is worth listing explicitly + - O_PATH allows an automount point to be opened with + triggering the mount. + +prctl.2 +seccomp.2 + Eugene Syromyatnikov + Update pointer to in-kernel seccomp documentation + +prctl.2 +ptrace.2 + Eugene Syromyatnikov + Update pointer to in-kernel Yama documentation + +prctl.2 + Eugene Syromyatnikov + Update pointer to in-kernel no_new_privs flag documentation + +readlink.2 + Michael Kerrisk [Jason Noakes] + Fix an off-by-one error in example code + +seccomp.2 + Kees Cook + Clarify SECCOMP_RET_KILL kills tasks not processes + +select_tut.2 + Michael Kerrisk [Sergey Z.] + Clarify an ambiguity with respect to select() and EAGAIN + See https://bugzilla.kernel.org/show_bug.cgi?id=196345 + +set_tid_address.2 + Elliott Hughes + Note that there's no glibc wrapper for set_tid_address() + +socket.2 + Michael Kerrisk [Yubin Ruan] + socket() uses the lowest available file descriptor + +_syscall.2 + Michael Kerrisk + Remove redundant comment from EXAMPLE + A discussion of the nroff source of the manual + page isn't very useful... + +sysfs.2 + Michael Kerrisk + Add a pointer to sysfs(5) to help possibly confused readers + Michael Kerrisk + Make it clearer near the start of the page that sysfs(2) is obsolete + +timer_create.2 + Michael Kerrisk + Strengthen the warning about use of printf() in the example program + Michael Kerrisk + Update cross reference: signal(7) should be signal-safety(7) + +umount.2 + NeilBrown + Revise MNT_FORCE description + MNT_FORCE does not allow a busy filesystem to be unmounted. Only + MNT_DETACH allows that. MNT_FORCE only tries to abort pending + transactions, in the hope that might help umount not to block, + + Also, other filesystems than NFS support MNT_FORCE. + +unshare.2 + Eugene Syromyatnikov + Update pointer to in-kernel unshare documentation + +wait.2 + Michael Kerrisk [Ильдар Низамов] + POSIX.1-2008 TC1 clarifies treatment of 'si_pid' for waitid() WNOHANG + +cmsg.3 + Sukadev Bhattiprolu + Add a scatter/gather buffer to sample code + Michael Kerrisk + Reorganize the text somewhat (no content changes) + +crypt.3 + Konstantin Shemyak [Michael Kerrisk] + Add description of previously undocumented 'rounds' parameter + Konstantin Shemyak + Encryption isn't done with SHA-xxx, but with a function based on SHA-xxx + Konstantin Shemyak + Clarify that ending of the salt string with '$' is optional + +exit.3 + Michael Kerrisk + Mention the prctl(2) PR_SET_PDEATHSIG operation + Michael Kerrisk + SEE ALSO: add get_robust_list(2) + Michael Kerrisk + Add a heading to delimit discussion of signals sent to other processes + +exp2.3 + Alex Henrie + Remove C89 designation + +log1p.3 + Alex Henrie + Document fixes to give EDOM or ERANGE on error + +matherr.3 + Michael Kerrisk + Note that glibc 2.27 removes the 'matherr' mechanism + Michael Kerrisk + Remove crufty feature test macro requirements + +pow10.3 + Michael Kerrisk + Note that pow10() is now obsolete in favor of exp10() + Also, the pow10() functions are no longer supported by glibc, + starting with version 2.27. + +sincos.3 + Michael Kerrisk + Note that sincos() is intended to be more efficient than sin() + cos() + +cciss.4 +hpsa.4 + Eugene Syromyatnikov [Don Brace, Meelis Roos] + Mention cciss removal in Linux 4.14 + During the Linux 4.13 development cycle, the cciss driver has been + removed in favor of the hpsa driver, which has been amended with + some legacy board support. + +initrd.4 +proc.5 +bootparam.7 + Eugene Syromyatnikov + Update pointer to in-kernel initrd documentation + +initrd.4 + Eugene Syromyatnikov + Update pointer to in-kernel root over NFS documentation + +intro.4 + Michael Kerrisk + SEE ALSO: add mknod(1) and mknod(2) + +host.conf.5 + Michael Kerrisk + Add cross-reference to hosts(5) + +locale.5 + Marko Myllynen + Refer to existing locales for encoding details + Since I don't think it would make sense to try to have different + explanation for each glibc version on the locale(5) man page, I'm + proposing that we apply the below patch so that we refer to + existing locale definition files in general and not spell out the + exact format or any certain locale as a definitive guideline. + +nologin.5 + Michael Kerrisk + Add a sentence explaining why nologin is useful + +proc.5 + Eugene Syromyatnikov + Document removal of htab-reclaim sysctl file + This PPC-specific sysctl option has been removed in Linux 2.4.9.2, + according to historic Linux repository commit log. + Eugene Syromyatnikov + Add description for cpuN lines in /proc/stat + Eugene Syromyatnikov + Add description for softirq line in /proc/stat + Eugene Syromyatnikov + Document removal of timer_stats file + Michael Kerrisk + Note Linux 4.9 changes to privileges for /proc/[pid]/timerslack_ns + Michael Kerrisk + Show command used to mount /proc + Michael Kerrisk + Explicitly note in intro that some /proc files are writable + Eugene Syromyatnikov + Update pointer to in-kernel SysRq documentation + Michael Kerrisk + SEE ALSO: add sysfs(5) + Eugene Syromyatnikov + Update pointer to in-kernel security keys documentation + Benjamin Peterson + Fix path to binfmt_misc docs + Eugene Syromyatnikov + Update pointer to in-kernel MTRR documentation + Eugene Syromyatnikov + Update reference to kernel's crypto API documentation + +tzfile.5 + Paul Eggert + Sync from tzdb upstream + This makes tzfile.5 a copy of the tzdb version, except that the + tzdb version's first line is replaced by man-pages boilerplate. + The new version documents version 3 format, among other things. + Also, it removes the "Summary of the timezone information file + format" section, which should no longer be needed due to + improvements in the part of the man page. + +capabilities.7 + Michael Kerrisk + Note semantics for a program that is set-UID-root and has capabilities + Note semantics for a program that is both set-user-ID-root and has + file capabilities. + Michael Kerrisk [Dennis Knorr] + Note that a set-UID-root program may have an empty file capability set + +cgroups.7 + Michael Kerrisk + SEE ALSO: systemd-cgls(1) + +cpuset.7 + Eugene Syromyatnikov + Update pointer to in-kernel cpusets documentation + +keyrings.7 + Eugene Syromyatnikov + Document description restriction for logon keys + "logon" type has additional check that enforces colon-separated + prefix in key descriptions. + Eugene Syromyatnikov + Add pointers to kernel's documentation + Mostly because of asymmetric-keys.txt, which is outside + security/keys for some reason. + +man-pages.7 + Michael Kerrisk + Expand the guidance on formatting code snippets + +netlink.7 + David Wilder + Change buffer size in example code about reading netlink message + Michael Kerrisk [Rick Jones] + Add a comment on 8192 buffer size in example code + +pthreads.7 + Michael Kerrisk + SEE ALSO: add pthread_mutexattr_destroy(3) and pthread_mutexattr_init(3) + +signal.7 + Michael Kerrisk + Since glibc 2.26, SIGUNUSED is no longer defined + +tcp.7 + Vincent Bernat + tcp_tw_recycle is removed from Linux 4.12 + And it is completely broken. + +unicode.7 + Eugene Syromyatnikov + Update pointer to in-kernel Unicode terminal support documentation + + +==================== Changes in man-pages-4.14 ==================== + +Released: 2017-11-27, Paris + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Adhemerval Zanella +Adrian Bunk +Ahmad Fatoum +Andrea Arcangeli +Bastien Roucaries +Breno Leitao +Carlos O'Donell +Christian Brauner +Christoph Hellwig +Colm MacCárthaigh +Craig Ringer +Cristian Rodríguez +David Eckardt +Don Brace +Elliot Hughes +Eric W. Biederman +Fabio Scotoni +Fangrui Song +Florian Weimer +G. Branden Robinson +Goldwyn Rodrigues +Grégory Vander Schueren +Jakub Wilk +Jann Horn +Jeff Layton +Jens Axboe +Jonny Grant +Julien Gomes +Kees Cook +Křištof Želechovski +Lennart Poettering +Lucas Werkmeister +Marcus Folkesson +Marin H. +Mathieu Desnoyers +Matthew Wilcox +Michael Kerrisk +Michal Hocko +Michał Zegan +Mihir Mehta +Mike Frysinger +Mike Kravetz +Mike Rapoport +Miklos Szeredi +NeilBrown +Oliver Ebert +Pedro Alves +Per Böhlin +Peter Zijlstra +Petr Malat +Petr Uzel +Prakash Sangappa +Raghavendra D Prabhu +Rahul Bedarkar +Ram Pai +Richard Knutsson +Rik van Riel +Scott Vokes +Seonghun Lim +Stas Sergeev +Stefan Puiu +Thomas Gleixner +Tobias Klausmann +Tomas Pospisek +Tyler Hicks +Victor Porton +Walter Harms +Wesley Aptekar-Cassels +Yubin Ruan +Zack Weinberg +Дилян Палаузов + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +pthread_spin_init.3 + Michael Kerrisk [Peter Zijlstra, Thomas Gleixner, Zack Weinberg, + Florian Weimer] + New page describing pthread_spin_init(3) and pthread_spin_destroy(3) + +pthread_spin_lock.3 + Michael Kerrisk [Carlos O'Donell] + New page describing functions that lock and unlock spin locks + Add a page describing pthread_spin_lock(3), pthread_spin_unlock(3), + and pthread_spin_trylock(3). + +smartpqi.4 + Don Brace [Michael Kerrisk, G. Branden Robinson] + Document the smartpqi SCSI driver + +veth.4 + Tomáš Pospíšek, Eric Biederman, Michael Kerrisk + New page documenting veth virtual ethernet devices + Based on a page from Tomáš Pospíšek, with some clean-ups by mtk. + + +Removed pages +------------- + +infnan.3: + Michael Kerrisk + This function was in libc4 and libc5, but never part + of glibc. It ceased to be relevant nearly 20 years + ago. Time to remove the man page. + + +Newly documented interfaces in existing pages +--------------------------------------------- + +ioctl_userfaultfd.2 +userfaultfd.2 + Prakash Sangappa [Andrea Arcangeli, Mike Rapoport] + Add description for UFFD_FEATURE_SIGBUS + +madvise.2 + Rik van Riel [Colm MacCárthaigh, Michael Kerrisk] + Document MADV_WIPEONFORK and MADV_KEEPONFORK + Michael Kerrisk + Note fork() and execve() semantics for wipe-on-fork setting + +membarrier.2 + Mathieu Desnoyers + Update membarrier manpage for 4.14 + Add documentation for these new membarrier() commands: + MEMBARRIER_CMD_PRIVATE_EXPEDITED + MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED + +memfd_create.2 + Mike Kravetz + Add description of MFD_HUGETLB (hugetlbfs) support + hugetlbfs support for memfd_create() was recently merged by Linus + and should be in the Linux 4.14 release. To request hugetlbfs + support a new memfd_create() flag (MFD_HUGETLB) was added. + +readv.2 + Christoph Hellwig + Document RWF_NOWAIT added in Linux 4.14 + +seccomp.2 + Tyler Hicks + Document the SECCOMP_GET_ACTION_AVAIL operation added in Linux 4.14 + Tyler Hicks + Document the SECCOMP_FILTER_FLAG_LOG flag added in Linux 4.14 + Tyler Hicks + Document the SECCOMP_RET_LOG action added In Linux 4.14 + Michael Kerrisk [Kees Cook] + Add description of SECCOMP_RET_KILL_PROCESS + Michael Kerrisk + Add SECCOMP_RET_KILL_THREAD description and rework SECCOMP_RET_KILL text + Michael Kerrisk + Document the seccomp audit logging feature added in Linux 4.14 + +seccomp.2 +proc.5 + Tyler Hicks + Document the seccomp /proc interfaces added in Linux 4.14 + Document the seccomp /proc interfaces in Linux 4.14: + /proc/sys/kernel/seccomp/actions_avail and + /proc/sys/kernel/seccomp/actions_logged. + +sigaltstack.2 + Michael Kerrisk [Stas Sergeev] + Document the SS_AUTODISARM flag added in Linux 4.7 + +proc.5 + Michael Kerrisk + Document /proc/locks + Oliver Ebert + Document /proc/kpagecgroup + Oliver Ebert + Add KPF_BALLOON, KPF_ZERO_PAGE, and KPF_IDLE for /proc/kpageflags + +pid_namespaces.7 + Michael Kerrisk + Document /proc/sys/kernel/ns_last_pid + + +New and changed links +--------------------- + +pthread_spin_destroy.3 + Michael Kerrisk + New link to new pthread_spin_init.3 page + +pthread_spin_trylock.3 +pthread_spin_unlock.3 + Michael Kerrisk + New links to new pthread_spin_lock.3 page + + +Global changes +-------------- + +Various pages + Michael Kerrisk + Consistently use "x86-64", not "x86_64" + When referring to the architecture, consistently use "x86-64", + not "x86_64". Hitherto, there was a mixture of usages, with + "x86-64" predominant. + +Various pages + G. Branden Robinson + Replace incorrect uses of Latin abbreviation "cf.". + People seem to be using "cf." ("conferre"), which means "compare", + to mean "see" instead, for which the Latin abbreviation would be + "q.v." ("quod vide" -> "which see"). + + In some cases "cf." might actually be the correct term but it's + still not clear what specific aspects of a function/system call + one is supposed to be comparing. + + + +Changes to individual pages +--------------------------- + +capget.2 + Michael Kerrisk + Clarify discussion of kernels that have no VFS capability support + +clock_getres.2 + Michael Kerrisk + clock_gettime() may be implemented in the vDSO + +clone.2 + Michael Kerrisk + Warn that the clone() wrapper modifies child_stack in the parent + Michael Kerrisk + Rework the discussion of the historical CLONE_PID for clarity + Michael Kerrisk + Add NOTES heading + Michael Kerrisk + Add a reference to new veth(4) page + Michael Kerrisk + Eliminate some redundant phrasing in discussion of "fn()" + Michael Kerrisk + Combine redundant paragraphs describing child_stack==NULL + Michael Kerrisk + Note that child_stack can be NULL when using the raw system call + Michael Kerrisk + Remove a redundant paragraph + +connect.2 + Michael Kerrisk + Clarify that ECONNREFUSED is for stream sockets + +fcntl.2 + Michael Kerrisk [Jens Axboe] + Inode read-write hints persist only until the filesystem is unmounted + +flock.2 + Michael Kerrisk + Move NFS details to a headed subsection + Michael Kerrisk [Petr Uzel] + Placing an exclusive lock over NFS requires the file is open for writing + +fork.2 + Rik van Riel [Colm MacCárthaigh, Michael Kerrisk] + Document effect of MADV_WIPEONFORK + +fork.2 +getsid.2 +setpgid.2 +setsid.2 + Ahmad Fatoum + Include in SYNOPSIS to obtain declaration of pid_t + +fsync.2 + Craig Ringer + ERRORS: add ENOSPC + +getcpu.2 + Michael Kerrisk + getcpu() may have an implementation in the vDSO + +getpid.2 + Michael Kerrisk + Mention that PID == TGID, and note contrast with TID + Michael Kerrisk + SEE ALSO: add gettid(2) + +getrandom.2 + Michael Kerrisk [Fabio Scotoni] + ERRORS: add ENOSYS + +getrlimit.2 + Michael Kerrisk [Scott Vokes] + Make it clear RLIMIT_NPROC is a limit on current number of processes + https://twitter.com/silentbicycle/status/893849097903505409 + +gettid.2 + Michael Kerrisk + SEE ALSO: add getpid(2) + +gettimeofday.2 + Michael Kerrisk + Note that gettimeofday() may be implemented in the vDSO + +ioctl_userfaultfd.2 + Michael Kerrisk + Rework version information for feature bits + +io_submit.2 + Goldwyn Rodrigues + Add iocb details to io_submit + Add more information about the iocb structure. Explains the + fields of the I/O control block structure which is passed to the + io_submit() call. + Michael Kerrisk + Add cross-reference to io_getevents(2) + Michael Kerrisk + Cross reference pwritev(2) in discussion of RWF_SYNC and RWF_DSYNC + +membarrier.2 + Mathieu Desnoyers + Update example to take TSO into account + The existing example given specifically states that it focus on + x86 (TSO memory model), but gives a read-read vs write-write + ordering example, even though this scenario does not require + explicit barriers on TSO. + + So either we change the example architecture to a weakly-ordered + architecture, or we change the example to a scenario requiring + barriers on x86. + + Let's stay on x86, but provide a Dekker as example instead. + Mathieu Desnoyers + Adapt the MEMBARRIER_CMD_SHARED return value documentation to + reflect that it now returns -EINVAL when issued on a system + configured for nohz_full. + +memfd_create.2 + Michael Kerrisk + Note the limit for size of 'name' + +mkdir.2 + Michael Kerrisk [Raghavendra D Prabhu] + ERRORS: document EINVAL error for invalid filename + +mmap.2 + Michael Kerrisk + Add explicit text noting that 'length' must be greater than 0 + Currently, this detail is hidden in ERRORS. Make it clear in + the main text. + Michael Kerrisk + SEE ALSO: add ftruncate(2) + +mremap.2 + Mike Kravetz [Florian Weimer, Jann Horn] + Add description of old_size == 0 functionality + Since at least the 2.6 time frame, mremap() would create a new + mapping of the same pages if 'old_size == 0'. It would also leave + the original mapping. This was used to create a 'duplicate + mapping'. + + A recent change was made to mremap() so that an attempt to create a + duplicate a private mapping will fail. + Michael Kerrisk [Michal Hocko, Mike Kravetz] + BUGS: describe older behavior for old_size==0 on private mappings + Explain the older behavior, and why it changed. This is a + follow-up to Mike Kravetz's patch documenting the behavior + for old_size==0 with shared mappings. + Michael Kerrisk + Reformat EINVAL errors as a list + +open.2 + Michael Kerrisk + By contrast with O_RDONLY, no file permissions are required for O_PATH + Note one of the significant advantages of O_PATH: many of the + operations applied to O_PATH file descriptors don't require + read permission, so there's no reason why the open() itself + should require read permission. + Michael Kerrisk + Note use of O_PATH to provide O_EXEC functionality + Michael Kerrisk + Mention O_PATH file descriptor use with fexecve(3) + Michael Kerrisk + ERRORS: document EINVAL error for invalid filename + Michael Kerrisk + Clarify that O_TMPFILE creates a *regular* file + Michael Kerrisk + Make it explicit that O_CREAT creates a regular file + Michael Kerrisk + Since glibc 2.26, the open() wrapper always uses the openat() syscall + Michael Kerrisk + Change pathname used in discussion of rationale for openat() + /path/to/file is a little confusing as a pathname + Michael Kerrisk + Make the purpose of open() a little clearer at the start of the page + +open_by_handle_at.2 + NeilBrown + Clarifications needed due to NFS reexport + NeilBrown [Lennart Poettering] + Clarify MAX_HANDLE_SZ + As hinted in the kernel source, MAX_HANDLE_SZ is a hint + rather than a promise. + +pipe.2 + Michael Kerrisk [Marin H.] + Since Linux 4.5, fcntl() can be used to set O_DIRECT for a pipe + See https://bugzilla.kernel.org/show_bug.cgi?id=197917 + +pivot_root.2 + Michael Kerrisk + SEE ALSO: add switch_root(8) + +pkey_alloc.2 + Breno Leitao + Fix argument order + Currently pkey_alloc() syscall has two arguments, and the very + first argument is still not supported and should be set to zero. + The second argument is the one that should specify the + page access rights. + +ptrace.2 + Michael Kerrisk + SEE ALSO: add ltrace(1) + +reboot.2 + Michael Kerrisk [Michał Zegan] + Fix bogus description of reboot() from non-initial PID namespace + The current text was confused (mea culpa). No signal is sent to + the init() process. Rather, depending on the 'cmd' given to + reboot(), the 'group_exit_code' value will set to either SIGHUP or + SIGINT, with the effect that one of those signals is reported to + wait() in the parent process. + + See https://bugzilla.kernel.org/show_bug.cgi?id=195899 + Michael Kerrisk + SEE ALSO: remove reboot(8) (synonym for halt(8)); add shutdown(8) + Michael Kerrisk + SEE ALSO: add systemctl(1), systemd(1) + +recvmmsg.2 +sendmmsg.2 + Elliot Hughes + Type fixes in SYNOPSIS + [mtk: The raw system calls use "unsigned int", but the glibc + wrappers have "int" for the 'flags' argument.] + +sched_setaffinity.2 + Michael Kerrisk + SEE ALSO: add numactl(8) + +sched_yield.2 + Michael Kerrisk [Peter Zijlstra] + sched_yield() is intended for use with real-time scheduling policies + +seccomp.2 + Michael Kerrisk [Adhemerval Zanella, Florian Weimer, Kees Cook] + Add some Caveats regarding the use of seccomp filters + Michael Kerrisk + Document the "default" filter return action + The kernel defaults to either SECCOMP_RET_KILL_PROCESS + or SECCOMP_RET_KILL_THREAD for unrecognized filter + return action values. + Michael Kerrisk [Kees Cook] + Change SECCOMP_RET_ACTION to SECCOMP_RET_ACTION_FULL + In Linux 4.14, the action component of the return value + switched from being 15 bits to being 16 bits. A new macro, + SECCOMP_RET_ACTION_FULL, that masks the 16 bits was added, + to replace the older SECCOMP_RET_ACTION. + Michael Kerrisk + Explicitly note that other threads survive SECCOMP_RET_KILL_THREAD + Michael Kerrisk + SEE ALSO: add strace(1) + +send.2 + Grégory Vander Schueren + Add EALREADY to ERRORS + +setns.2 + Michael Kerrisk + SEE ALSO: add nsenter(1) + +shmop.2 + Yubin Ruan + Note that return value of shmat() is page-aligned + +sigaction.2 + Michael Kerrisk + Rework discussion of SA_SIGINFO handler arguments + Expand and rework the text a little, in particular adding + a reference to sigreturn(2) as a source of further + information about the ucontext argument. + Michael Kerrisk + Mention that libc sets the act.sa_restorer field + +sigaltstack.2 + Michael Kerrisk [Walter Harms] + Reword BUGS text to be a little clearer + Michael Kerrisk + Add explicit error handling to example code + Michael Kerrisk + Add use of sigaction() to example code + +sigreturn.2 + Michael Kerrisk + Make it a little clearer that a stack frame is created by the kernel + Michael Kerrisk + glibc has a simple wrapper for sigreturn() that returns ENOSYS + +splice.2 + Michael Kerrisk + Since Linux 2.6.31,'fd_in' and 'fd_out' may both refer to pipes + +stat.2 + Michael Kerrisk [Richard Knutsson] + Use lstat() instead of stat() + It's more logical to use lstat() in the example code, + since one can then experiment with symbolic links, and + also the S_IFLNK case can also occur. + NeilBrown + Correct AT_NO_AUTOMOUNT text and general revisions + Expand on the relationship between fstatat() and the other three + functions, and improve the description of AT_NO_AUTOMOUNT. + Specifically, both stat() and lstat() act the same way with + respect to automounts, and that behavior matches fstatat() with + the AT_NO_AUTOMOUNT flag. + +statfs.2 + Michael Kerrisk + Add some comments noting filesystems that are no longer current + Michael Kerrisk + Add comments describing a few filesystem types + +time.2 + Michael Kerrisk + Note that time() may be implemented in the vDSO + Michael Kerrisk [Victor Porton] + Language fix-up: clarify that "tasks" means "work" + See https://bugzilla.kernel.org/show_bug.cgi?id=197183 + +userfaultfd.2 + Mike Rapoport + BUGS: document spurious UFFD_EVENT_FORK + +write.2 +fsync.2 +close.2 + NeilBrown [Jeff Layton] + Update description of error codes + Since 4.13, errors from writeback are more reliably reported + to all file descriptors that might be relevant. + + Add notes to this effect, and also add detail about ENOSPC and + EDQUOT which can be delayed in a similar many to EIO - for NFS + in particular. + +abort.3 + Michael Kerrisk + Starting with glibc 2.27, abort() does not attempt to flush streams + Michael Kerrisk + SEE ALSO: add assert(3) + +backtrace_symbols_fd(3) + Stefan Puiu [Walter Harms] + backtrace_symbols_fd() can trigger a call to malloc() + +daemon.3 + Michael Kerrisk + SEE ALSO: add daemon(7), logrotate(8) + +errno.3 + Michael Kerrisk + Note use of errno(1) to look up error names and numbers + Michael Kerrisk + Update error list for POSIX.1-2008 + POSIX.1-2008 specified a couple of new errors not present in + POSIX.1-2001. + Michael Kerrisk [Walter Harms] + Note the use of perror(3) and strerror(3) + Michael Kerrisk + Recast the advice against manually declaring 'errno' + Recast the advice against manually declaring 'errno' to + a more modern perspective. It's 13 years since the original + text was added, and even then it was describing old behavior. + Cast the description to be about behavior further away in + time, and note more clearly that manual declaration will + cause problems with modern C libraries. + Michael Kerrisk + Add some missing errors + Michael Kerrisk + Error numbers are positive values (rather than nonzero values) + POSIX.1-2008 noted the explicitly the change (to align with + the C standards) that error numbers are positive, rather + than nonzero. + Michael Kerrisk + Reorganize the text and add some subheadings + Restructure the text and add some subheadings for better + readability. No (intentional) content changes. + Michael Kerrisk [Wesley Aptekar-Cassels] + Note that error numbers vary somewhat across architectures + Added after a patch from Wesley Aptekar-Cassels that proposed + to add error numbers to the text. + Michael Kerrisk + Note the also provides the symbolic error names + Michael Kerrisk [Walter Harms] + Explicitly note that error numbers vary also across UNIX systems + +exec.3 + Michael Kerrisk + glibc 2.24 dropped CWD from the default path + Document the glibc 2.24 change that dropped CWD from the default + search path employed by execlp(), execvp() and execvpe() when + PATH is not defined. + +fexecve.3 + Michael Kerrisk + O_PATH file descriptors are also usable with fexecve() + Cristian Rodríguez + fexecve() is now implemented with execveat(2), where available + Michael Kerrisk + Add some detail on the glibc implementation of fexecve() via execveat(2) + +ffs.3 + Michael Kerrisk + glibc 2.27 relaxes the FTM requirements for ffsl() and ffsll() + +get_nprocs_conf.3 + Michael Kerrisk + SEE ALSO: add nproc(1) + +lround.3 + Michael Kerrisk [David Eckardt] + Clarify that lround() rounds *halfway cases" away from zero + See https://bugzilla.kernel.org/show_bug.cgi?id=194601 + +makedev.3 + Adrian Bunk + glibc has deprecated exposing the definitions via + +mallinfo.3 + Jakub Wilk + Fix the example + Remove reference to non-standard "tlpi_hdr.h" and replace calls to + functions that were declared in this header. + +malloc.3 + Michael Kerrisk + SEE ALSO: add valgrind(1) + +popen.3 + Michael Kerrisk + Add a cross reference to Caveats in system(3) + All of the same risks regarding system() also apply to popen(). + +pthread_detach.3 + Michael Kerrisk [Rahul Bedarkar] + Improve sentence describing freeing of resources on process termination + As reported by Rahul, the existing sentence could be read as + meaning that resources of joined and terminated detached + threads are freed only at process termination. Eliminate + that possible misreading. + +pthread_yield.3 + Michael Kerrisk [Peter Zijlstra] + pthread_yield() is intended for use with real-time scheduling policies + +setlocale.3 + Michael Kerrisk [Křištof Želechovski] + The standards do not specify all of the locale categories + +sockatmark.3 + Seonghun Lim + Fix cruft in code example + +stdio.3 + Michael Kerrisk + Use proper section cross references in function list + Michael Kerrisk + Remove crufty reference to pc(1) + +sysconf.3 + Michael Kerrisk + Mention get_nprocs_conf(3) + Mention get_nprocs_conf(3) in discussion of _SC_NPROCESSORS_CONF + and _SC_NPROCESSORS_ONLN. + +system.3 + Michael Kerrisk [Bastien Roucaries] + Create a "Caveats" subsection to hold warnings about the use of system() + See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=882222 + Michael Kerrisk [Bastien Roucaries] + Mention PATH explicitly in discussion of system() and set-UID programs + Michael Kerrisk [Bastien Roucaries] + Note that user input for system() should be carefully sanitized + Michael Kerrisk + Mention file capabilities in discussion of privileged programs + Michael Kerrisk + Correctly note which shell Debian uses as (noninteractive) /bin/sh + +core.5 + Michael Kerrisk + Add some notes on systemd and core dumps + Michael Kerrisk + Dumps are not produced if core_pattern is empty and core_uses_pid is 0 + Michael Kerrisk [Per Böhlin] + RLIMIT_CORE is not enforced when piping core dump to a program + Michael Kerrisk + SEE ALO: add systemd-coredump(8) + Michael Kerrisk + SEE ALSO: add coredumpctl(1) + +filesystems.5 + Michael Kerrisk [Jonny Grant] + Replace crufty URL reference for 'smb' with up-to-date URL + Michael Kerrisk [Jonny Grant] + Refer to VFAT as an extended FAT (not DOS) filesystem + +proc.5 + Michael Kerrisk [Miklos Szered, Ram Pai] + Correct the description of the parent mount ID for /proc/PID/mountinfo + Oliver Ebert + Add mmap-exclusive bit for /proc/[pid]/pagemap + Marcus Folkesson + Update description of /proc//oom_score + Lucas Werkmeister + Clarify permissions in /proc/[pid]/fd/ + Michael Kerrisk + Add reference to pid_namespaces(7) for /proc/sys/kernel/ns_last_pid + +shells.5 + Michael Kerrisk + SEE ALSO: add pam_shells(8) + +sysfs.5 + Michael Kerrisk + Add a brief explanation of /sys/kernel + Michael Kerrisk + Add a brief description of /sys/class/net + Michael Kerrisk + Add a brief description of /sys/kernel/mm + Michael Kerrisk + Add brief description of /sys/kernel/debug/tracing + Michael Kerrisk + Add a description of /sys/kernel/mm/hugepages + +arp.7 + Michael Kerrisk + SEE ALSO: add arpd(8) + +capabilities.7 + Michael Kerrisk + Add a reference to xattr(7) in the discussion of extended attributes + Michael Kerrisk + SEE ALSO: add captest(8) + +epoll.7 + Michael Kerrisk + Note existence of kcmp() KCMP_EPOLL_TFD operation + +fifo.7 + Michael Kerrisk + Refer reader to pipe(7) for details of I/O semantics of FIFOs + +hier.7 + Michael Kerrisk + SEE ALSO: add file-hierarchy(7) + +icmp.7 + Michael Kerrisk + SEE ALSO: add rdisc(8) + +man-pages.7 + Michael Kerrisk + Note that "x86-64" is generally preferred over "x86_64" + G. Branden Robinson + Add a use case for real minus character + +namespaces.7 + Michael Kerrisk + Add a reference to new veth(4) page + Michael Kerrisk + EXAMPLE: refer also to example in clone(2) + +pid_namespaces.7 + Michael Kerrisk + SEE ALSO: add reboot(2) + Add because reboot(2) has special semantics for non-initial + PID namespaces. + +pthreads.7 + Michael Kerrisk + SEE ALSO: add pthread_spin_init(3) and pthread_spin_lock(3) + +socket.7 + Michael Kerrisk [Petr Malat, Tobias Klausmann] + Correct the description of SO_RXQ_OVFL + +standards.7 + Michael Kerrisk + SEE ALSO: add getconf(1), confstr(3), pathconf(3), sysconf(3) + +user_namespaces.7 + Christian Brauner [Michael Kerrisk] + Document new 340 line idmap limit + +ld.so.8 + Michael Kerrisk [Yubin Ruan] + Simplify language around conferring capabilities + The statement "conferring permitted or effective capabilities" + to the process is somewhat redundant. Binaries with capabilities + confer capabilities only to those process capability sets, so it's + simpler to just say "confers capabilities to the process". diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..49757c6 --- /dev/null +++ b/Makefile @@ -0,0 +1,45 @@ +DESTDIR= +prefix?=/usr +MANDIR=$(prefix)/share/man + +all: remove install + +uninstall remove: + for i in man?/*; do \ + rm -f $(MANDIR)/"$$i" $(MANDIR)/"$$i".*; \ + done + +# Use with +# make HTDIR=/some/dir HTOPTS=whatever html +# The sed removes the lines "Content-type: text/html\n\n" +html: + @if [ x$(HTDIR) = x ]; then echo "You must set HTDIR."; else \ + for i in man?; do \ + [ -d $(HTDIR)/"$$i" ] || mkdir -p $(HTDIR)/"$$i"; \ + find "$$i/" -type f | while read f; do \ + (cd "$$i"; man2html $(HTOPTS) `basename $$f`) | \ + sed -e '1,2d' > $(HTDIR)/"$$i"/`basename $$f`.html; \ + done; \ + done; fi + +install: + for i in man?; do \ + install -d -m 755 $(DESTDIR)$(MANDIR)/"$$i" || exit $$?; \ + install -m 644 "$$i"/* $(DESTDIR)$(MANDIR)/"$$i" || exit $$?; \ + done + +# Check if groff reports warnings (may be words of sentences not displayed) +# from http://lintian.debian.org/tags/manpage-has-errors-from-man.html +check-groff-warnings: + GROFF_LOG="$$(mktemp --tmpdir manpages-checksXXXX)" || exit $$?; \ + for i in man?/*.[1-9]; \ + do \ + if grep -q 'SH.*NAME' "$$i"; then \ + LC_ALL=en_US.UTF-8 MANWIDTH=80 man --warnings -E UTF-8 -l "$$i" > /dev/null 2>| "$$GROFF_LOG"; \ + [ -s "$$GROFF_LOG" ] && { echo "$$i: "; cat "$$GROFF_LOG"; echo; }; \ + fi; \ + done; \ + rm -f "$$GROFF_LOG" + +# someone might also want to look at /var/catman/cat2 or so ... +# a problem is that the location of cat pages varies a lot diff --git a/README b/README new file mode 100644 index 0000000..9de67a0 --- /dev/null +++ b/README @@ -0,0 +1,37 @@ +This package contains Linux man pages for sections 1 through 8. Some +more information is given in the 'man-pages-x.y.Announce' file. + +Installing and uninstalling +=========================== +"make install" will copy these man pages to /usr/share/man/man[1-8]. + +To install to a path different from /usr, use +"make install prefix=/install/path". + +"make remove" or "make uninstall" will remove any man page in this +distribution from its destination. Use with caution, and remember to +use "prefix" if desired, as with the "install" target. + +"make" or "make all" will perform "make uninstall" followed by "make +install". + +Man page overlap and duplication +================================ +Note that sometimes these pages are duplicates of pages also distributed +in other packages. This has been reported about: + +man page also found in +------------------------------------- +resolver.3 bind-utils, bind9utils +resolv.conf.5 " +passwd.5 shadow, passwd +mailaddr.7 ? + +Copyrights +========== +See the 'man-pages-x.y.Announce' file. + +Homepage +======== +For much more about the Linux man-pages project, see +http://www.kernel.org/doc/man-pages/index.html. diff --git a/man-pages-4.15.Announce b/man-pages-4.15.Announce new file mode 100644 index 0000000..72ee3a8 --- /dev/null +++ b/man-pages-4.15.Announce @@ -0,0 +1,62 @@ +RELEASE +The Linux man page maintainer proudly announces. . . + + man-pages-4.15.tar.gz - man pages for Linux + +Differences from the previous manual pages release are listed in +the file "Changes". + +For further information, visit http://www.kernel.org/doc/man-pages/ + +POSIX PAGES +This package used to contains a copy of the POSIX 1003.1-2003 +man pages. The POSIX pages are now distributed in the separate +man-pages-posix package. + +THE PAGES +These pages are most of the section 2, 3, 4, 5, 7 man pages +for Linux. A few pages are provided in sections 1 and 8 for commands +that are not documented in other packages, and there are a few pages +in sections 5 and 8 for the timezone utilities. + +[The timezone pages were taken from +ftp://elsie.nci.nih.gov/pub/tzcode2001a.tar.gz.] +[The section 3 man pages for the db routines have been taken from +ftp://ftp.terra.net/pub/sleepycat/db.1.86.tar.gz.] +[The rpc man pages were taken from the 4.4BSD-Lite CDROM.] + +Here is a breakdown of what this distribution contains: + + Section 1 = user commands (intro, plus a few other pages) + Section 2 = system calls + Section 3 = libc calls + Section 4 = devices (e.g., hd, sd) + Section 5 = file formats and configuration files (e.g., wtmp, /etc/passwd) + Section 6 = games (intro only) + Section 7 = overviews, conventions, macro packages, etc. + Section 8 = system administration (intro, plus a few other pages) + + This package contains no, or very few, section 1, 6, and 8 man pages + because these should be distributed with the binaries they are written + for. Sometimes Section 9 is used for man pages describing parts of + the kernel. + + Note that only Section 2 is rather complete, but Section 3 contains + several hundred man pages. If you want to write some man pages, + or suggest improvements to existing pages, please visit + http://www.kernel.org/doc/man-pages/ . + + +Copyright information: + + These man pages are distributed under a variety of copyright licenses. + Although these licenses permit free distribution of the nroff sources + contained in this package, commercial distribution may impose other + requirements (e.g., acknowledgement of copyright or inclusion of the + raw nroff sources with the commercial distribution). + If you distribute these man pages commercially, it is your + responsibility to figure out your obligations. (For many man pages, + these obligations require you to distribute nroff sources with any + pre-formatted man pages that you provide.) Each file that contains + nroff source for a man page also contains the author(s) name, email + address, and copyright notice. diff --git a/man-pages-4.15.lsm b/man-pages-4.15.lsm new file mode 100644 index 0000000..72e7f14 --- /dev/null +++ b/man-pages-4.15.lsm @@ -0,0 +1,14 @@ +Begin3 +Title: Section 2, 3, 4, 5 and 7 man pages for Linux +Version: 4.15.14.14 +Entered-date: 2018-02-02 +Description: Linux manual pages +Keywords: man pages +Author: several +Maintained-by: Michael Kerrisk +Primary-site: ftp://ftp.kernel.org/pub/linux/docs/man-pages + 2572k man-pages-4.15.tar.gz +Alternate-site: ftp://ftp.win.tue.nl/pub/linux-local/manpages +Copying-policy: several; the pages are all freely distributable as long as + nroff source is provided +End diff --git a/man-pages-additional-20140218/Makefile b/man-pages-additional-20140218/Makefile new file mode 100644 index 0000000..0d3f0bb --- /dev/null +++ b/man-pages-additional-20140218/Makefile @@ -0,0 +1,14 @@ +# Do "make install" to copy the pages to their destination. + +DESTDIR= +prefix?=/usr +MANDIR=$(prefix)/share/man + +all: install + +install: + for i in man*; do \ + install -d -m 755 $(DESTDIR)$(MANDIR)/"$$i" || exit $$?; \ + install -m 644 "$$i"/* $(DESTDIR)$(MANDIR)/"$$i" || exit $$?; \ + done; \ + diff --git a/man-pages-additional-20140218/man2/rtas.2 b/man-pages-additional-20140218/man2/rtas.2 new file mode 100644 index 0000000..5c4ce59 --- /dev/null +++ b/man-pages-additional-20140218/man2/rtas.2 @@ -0,0 +1,61 @@ +.\" Copyright (C) 2004 IBM Corporation +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" +.\" This page documents the differences between the low-level kernel system call interface .\" and that made available to applications by glibc. Portable applications should always .\" use the official library interface. +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "RTAS" 2 +.SH NAME +rtas \- Allows userspace to call RTAS (Run Time Abstraction Services) +.SH "SYNOPSIS" +.ad l +.hy 0 +.HP 17 +int\ \fBppc_rtas\fR\ (struct rtas_args\ \fI*uargs\fR); +.ad +.hy + +.SH "DESCRIPTION" +\fBppc_rtas\fR enables userspace manipulation of the RunTime Abstraction Services (RTAS). RTAS provides for a portable method of access and setting system information. For example, you could gather information on various system sensors and set poweron values. RTAS is accessed via the /proc entry called "rtas". Manipulations on RTAS are implemented via command line arguments on /proc/rtas. +The values for \fIuargs\fR vary greatly. +For more information, see the \fIview/arch/ppcKconfig\fR file. + +.SH "RETURN VALUE" + +.PP +\fBrtas\fR returns 0 on success; otherwise it returns one of the errors listed in the "Errors" section. + +.SH "ERRORS" + +.TP +-EPERM +User does not have CAP_SYS_ADMIN capabilities. + +.TP +-EFAULT +Problem copying \fIuargs\fR values to/from user space. + +.TP +-EINVAL +Either number of \fIuargs\fR passed in too large or size of \fIuargs\fR array too large. + +.SH AUTHOR +Niki Rahimi. diff --git a/man-pages-additional-20140218/man2/swapcontext.2 b/man-pages-additional-20140218/man2/swapcontext.2 new file mode 100644 index 0000000..f334b21 --- /dev/null +++ b/man-pages-additional-20140218/man2/swapcontext.2 @@ -0,0 +1,63 @@ +.\" Copyright (C) 2004 IBM Corporation +.\" This file is distributed according to the GNU General Public License. +.\" See the file COPYING in the top level source directory for details. +.\" + +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "SWAPCONTEXT" 2 "2004-March-12" "Linux 2.6" "Linux 2.6 Programmer's Guide" +.SH NAME +swapcontext \- Swap out old context with new context +.SH "SYNOPSIS" +.ad l +.hy 0 +.HP 21 +int\ \fBsys_swapcontext\fR\ (struct\ ucontext\ \fI*old_ctx\fR, struct\ ucontext\ \fI*new_ctx\fR, int\ \fIr5\fR, int\ \fIr6\fR, int\ \fIr7\fR, int\ \fIr8\fR, struct\ pt_regs\ \fI*regs\fR); +.ad +.hy + +.SH "DESCRIPTION" + +.PP +\fBswapcontext\fR swaps out context \fIold_ctx\fR with new context \fInew_ctx\fR. The \fIint r#\fR values have no place in the system call functionality. The \fIregs\fR value indicates the current user register values from the user stack. + +.SH "RETURN VALUE" + +.PP +\fBswapcontext\fR returns 0 on success; otherwise, \fBswapcontext\fR returns one of the errors listed in the "Errors" section. + +.SH "ERRORS" + +.TP +-EFAULT +\fIswapcontext\fR could not verify that the memory area pointed to by \fIold_ctx\fR or \fInew_ctx\fR was accessible for the operation. + +.TP +-SIGSEGV +A fault occurred when the context was being copied into the kernel's image of the user's registers. The should only occur in an out-of-memory situation. + +.SH "SEE ALSO" +.BR getcontext(2), +.BR sigaction(2), +.BR sigaltstack(2), +.BR sigprocmask(2) +\fB\fR + +.SH AUTHOR +Niki Rahimi diff --git a/man-pages-additional-20140218/man8/cons.saver.8 b/man-pages-additional-20140218/man8/cons.saver.8 new file mode 100644 index 0000000..89ff86c --- /dev/null +++ b/man-pages-additional-20140218/man8/cons.saver.8 @@ -0,0 +1,32 @@ +.\" This file is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See +.\" the GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this file; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, +.\" MA 02111-1307 USA +.\" +.\" HISTORY: +.\" 2006-05-16, created by Rodrigo Rubira Branco +.TH cons.saver 8 "May 16, 2006" Linux "User Manuals" +.SH NAME +cons.saver \- general-purpose Linux console screen save and restore server +.SH SYNOPSIS +.nf +.fam C +cons.saver \fITTY\fP +.fam T +.fi +.SH DESCRIPTION +.TP +Invoke this helper program with the Ctrl-o key combination to save and restore the user session on the screen. +.SH OPTIONS +cons.saver takes only one argument, the \fITTY\fP \fINAME\fP from which the system will save and restore. +.SH SECURITY +Cons.saver does not need to be invoked by root. It only needs read and write access to /dev/vcsa*, which is a priviledged operation. You should create an unprivileged user, make cons.saver setuid to that user, and assure that all the vcsa* are owned by that user too. +.SH AUTHOR +Manpage written by Rodrigo Rubira Branco +.SH SEE ALSO +\fBmc\fP(1), \fBmcserv\fP(8) diff --git a/man-pages-posix-2013-a/Makefile b/man-pages-posix-2013-a/Makefile new file mode 100644 index 0000000..7e71ec0 --- /dev/null +++ b/man-pages-posix-2013-a/Makefile @@ -0,0 +1,59 @@ +# Do "make screen" first, if you want to protect already installed, +# more up-to-date manual pages than the ones included in this package. +# Do "make install" to copy the pages to their destination. +# Do "make gz" or "make bz2" first if you use compressed source pages. + +DESTDIR= +prefix?=/usr +MANDIR=$(prefix)/share/man + +GZIP=gzip -9 +BZIP2=bzip2 -9 + +all: screen remove install + +allgz: gz all + +allbz: bz2 all + +screen: + -mkdir not_installed + for i in man?p/*; do \ + if [ $(MANDIR)/"$$i" -nt "$$i" ]; then \ + cmp -s $(MANDIR)/"$$i" "$$i" > /dev/null 2>&1; \ + if [ "$$?" != 0 ]; then mv "$$i" not_installed; fi; \ + fi; \ + done + +remove: + for i in man?p/*; do \ + rm -f $(MANDIR)/"$$i" $(MANDIR)/"$$i".gz $(MANDIR)/"$$i".bz2; \ + done + +gz: + for i in man?p; do $(GZIP) "$$i"/*; done + +bz2: + for i in man?p; do $(BZIP2) "$$i"/*; done + +# Use with +# make HTDIR=/some/dir HTOPTS=whatever html +# The sed removes the lines "Content-type: text/html\n\n" +html: + @if [ x$(HTDIR) = x ]; then echo "You must set HTDIR."; else \ + for i in man?p; do \ + [ -d $(HTDIR)/"$$i" ] || mkdir -p $(HTDIR)/"$$i"; \ + find "$$i/" -type f | while read f; do \ + (cd "$$i"; man2html $(HTOPTS) `basename $$f`) | \ + sed -e '1,2d' > $(HTDIR)/"$$i"/`basename $$f`.html; \ + done; \ + done; fi + +install: + for i in man?p; do \ + install -d -m 755 $(DESTDIR)$(MANDIR)/"$$i" || exit $$?; \ + install -m 644 "$$i"/* $(DESTDIR)$(MANDIR)/"$$i" || exit $$?; \ + done; \ + +# someone might also want to look at /var/catman/cat2 or so ... +# a problem is that the location of cat pages varies a lot diff --git a/man-pages-posix-2013-a/POSIX-COPYRIGHT b/man-pages-posix-2013-a/POSIX-COPYRIGHT new file mode 100644 index 0000000..3097301 --- /dev/null +++ b/man-pages-posix-2013-a/POSIX-COPYRIGHT @@ -0,0 +1,25 @@ +The Institute of Electrical and Electronics Engineers (IEEE) and +The Open Group, have given us permission to reprint portions of +their documentation. + +In the following statement, the phrase ``this text'' refers to +portions of the system documentation. + +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri- +cal and Electronics Engineers, Inc and The Open Group. (This is +POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online +at http://www.unix.org/online.html . + +This notice shall appear on any product containing this material. + +Redistribution of this material is permitted so long as this notice and +the corresponding notices within each POSIX manual page are retained on +any distribution, and the nroff source is included. Modifications to +the text are permitted so long as any conflicts with the standard +are clearly marked as such in the text. diff --git a/man-pages-posix-2013-a/README b/man-pages-posix-2013-a/README new file mode 100644 index 0000000..8e1ccb8 --- /dev/null +++ b/man-pages-posix-2013-a/README @@ -0,0 +1,22 @@ +These are pages from POSIX.1-2008, Technical Corrigendum 1. +Since TC1 appeared in 2013, it is also known as POSIX.1-2013. + +This package contains the POSIX man pages (pages in sections +except 0p, 1p, and 3p). Some more information is given in the +`Announce' file. Some background on UNIX standards, including +POSIX, can be found in the standards(7) page provide as part +of the separate Linux man-pages package. + +Install by copying to your favourite location. +"make install" will just copy them to /usr/share/man/man[013]p. +"make" will move the pages from this package that are older than +the already installed ones to a subdirectory `not_installed', +then remove old versions (compressed or not), +compress the pages, and copy them to /usr/share/man/man[013]p. + +Note that you may have to remove preformatted pages. + +Copyrights: see the file POSIX-COPYRIGHT. + +If you have corrections and additions to suggest, then visit +https://www.kernel.org/doc/man-pages/reporting_bugs.html diff --git a/man-pages-posix-2013-a/man-pages-posix-2013-a.Announce b/man-pages-posix-2013-a/man-pages-posix-2013-a.Announce new file mode 100644 index 0000000..6b16e78 --- /dev/null +++ b/man-pages-posix-2013-a/man-pages-posix-2013-a.Announce @@ -0,0 +1,28 @@ +RELEASE +The Linux man-pages maintainer proudly announces. . . + + man-pages-posix-2013-a.tar.gz - POSIX man pages + +For further information, visit http://www.kernel.org/doc/man-pages/ + +POSIX +This release contains a copy of the POSIX 1003.1-2013 man pages. +The directories man0p, man1p, man3p contain descriptions of the +headers, the utilities, and the functions documented in that standard. +For the copyright notice, see the file POSIX-COPYRIGHT. + +In order to use this, put in {/usr/share/misc/}man.conf{ig} or so +your favourite order of looking at these pages, for example, +MANSECT 1p:1:8:0p:3p:2:3:4:5:6:7:9:tcl:n:l:p:o +or set the MANSECT environment variable. + +Here is a breakdown of what this distribution contains: + + Section 0p = POSIX headers + Section 1p = POSIX utilities + Section 3p = POSIX functions + +Copyright information: + + For the POSIX pages permission to distribute was given by IEEE + and the Open Group, see POSIX-COPYRIGHT. diff --git a/man-pages-posix-2013-a/man-pages-posix-2013-a.lsm b/man-pages-posix-2013-a/man-pages-posix-2013-a.lsm new file mode 100644 index 0000000..d9bfaa6 --- /dev/null +++ b/man-pages-posix-2013-a/man-pages-posix-2013-a.lsm @@ -0,0 +1,12 @@ +Begin3 +Title: Section 0p, 1p, and 3p man pages (the POSIX.1-2013 man-pages) for Linux +Version: 2013-a +Entered-date: 2014-01-19 +Description: POSIX manual pages +Keywords: man pages +Author: The Open Group +Maintained-by: Michael Kerrisk +Primary-site: https://www.kernel.org/pub/linux/docs/man-pages/man-pages-posix/ + 1499k man-pages-posix-2013-a.tar.gz +Copying-policy: See the file POSIX-COPYRIGHT; +End diff --git a/man-pages-posix-2013-a/man0p/aio.h.0p b/man-pages-posix-2013-a/man0p/aio.h.0p new file mode 100644 index 0000000..0a5c829 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/aio.h.0p @@ -0,0 +1,174 @@ +'\" et +.TH aio.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +aio.h +\(em asynchronous input and output +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR aiocb +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int aio_fildes \fRFile descriptor.\fR +off_t aio_offset \fRFile offset.\fR +volatile void *aio_buf \fRLocation of buffer.\fR +size_t aio_nbytes \fRLength of transfer.\fR +int aio_reqprio \fRRequest priority offset.\fR +struct sigevent aio_sigevent \fRSignal number and value.\fR +int aio_lio_opcode \fROperation to be performed.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR off_t , +.BR pthread_attr_t , +.BR size_t , +and +.BR ssize_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR "struct timespec" +structure as described in +.IR . +.P +The tag +.BR sigevent +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The +.IR +header shall define the following symbolic constants: +.IP AIO_ALLDONE 14 +A return value indicating that none of the requested operations could +be canceled since they are already complete. +.IP AIO_CANCELED 14 +A return value indicating that all requested operations have been +canceled. +.IP AIO_NOTCANCELED 14 +.br +A return value indicating that some of the requested operations could +not be canceled since they are in progress. +.IP LIO_NOP 14 +A +\fIlio_listio\fR() +element operation option indicating that no transfer is requested. +.IP LIO_NOWAIT 14 +A +\fIlio_listio\fR() +synchronization operation indicating that the calling thread is to +continue execution while the +\fIlio_listio\fR() +operation is being performed, and no notification is given when the +operation is complete. +.IP LIO_READ 14 +A +\fIlio_listio\fR() +element operation option requesting a read. +.IP LIO_WAIT 14 +A +\fIlio_listio\fR() +synchronization operation indicating that the calling thread is to +suspend until the +\fIlio_listio\fR() +operation is complete. +.IP LIO_WRITE 14 +A +\fIlio_listio\fR() +element operation option requesting a write. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int aio_cancel(int, struct aiocb *); +int aio_error(const struct aiocb *); +int aio_fsync(int, struct aiocb *); +int aio_read(struct aiocb *); +ssize_t aio_return(struct aiocb *); +int aio_suspend(const struct aiocb *const [], int, + const struct timespec *); +int aio_write(struct aiocb *); +int lio_listio(int, struct aiocb *restrict const [restrict], int, + struct sigevent *restrict); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible symbols defined in the headers +.IR , +.IR , +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_fsync\fR\^(\|)", +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_suspend\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIfsync\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/arpa_inet.h.0p b/man-pages-posix-2013-a/man0p/arpa_inet.h.0p new file mode 100644 index 0000000..6c4bdbe --- /dev/null +++ b/man-pages-posix-2013-a/man0p/arpa_inet.h.0p @@ -0,0 +1,118 @@ +'\" et +.TH arpa_inet.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +arpa/inet.h +\(em definitions for internet operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR in_port_t +and +.BR in_addr_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR in_addr +structure as described in +.IR . +.P +The +.IR +header shall define the INET_ADDRSTRLEN +and INET6_ADDRSTRLEN +macros as described in +.IR . +.P +The following shall be declared as functions, or defined as macros, +or both. If functions are declared, function prototypes shall be +provided. +.sp +.RS 4 +.nf +\fB +uint32_t htonl(uint32_t); +uint16_t htons(uint16_t); +uint32_t ntohl(uint32_t); +uint16_t ntohs(uint16_t); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR uint32_t +and +.BR uint16_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +in_addr_t inet_addr(const char *); +char *inet_ntoa(struct in_addr); +const char *inet_ntop(int, const void *restrict, char *restrict, + socklen_t); +int inet_pton(int, const char *restrict, void *restrict); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIhtonl\fR\^(\|)", +.IR "\fIinet_addr\fR\^(\|)", +.IR "\fIinet_ntop\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/assert.h.0p b/man-pages-posix-2013-a/man0p/assert.h.0p new file mode 100644 index 0000000..2957f9b --- /dev/null +++ b/man-pages-posix-2013-a/man0p/assert.h.0p @@ -0,0 +1,82 @@ +'\" et +.TH assert.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +assert.h +\(em verify program assertion +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the +\fIassert\fR() +macro. It refers to the macro NDEBUG +which is not defined in the header. If NDEBUG is defined as a macro +name before the inclusion of this header, the +\fIassert\fR() +macro shall be defined simply as: +.sp +.RS 4 +.nf +\fB +#define assert(ignore)((void) 0) +.fi \fR +.P +.RE +.P +Otherwise, the macro behaves as described in +\fIassert\fR(). +.P +The +\fIassert\fR() +macro shall be redefined according to the current state of NDEBUG each +time +.IR +is included. +.P +The +\fIassert\fR() +macro shall be implemented as a macro, not as a function. If the macro +definition is suppressed in order to access an actual function, the +behavior is undefined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIassert\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/complex.h.0p b/man-pages-posix-2013-a/man0p/complex.h.0p new file mode 100644 index 0000000..517ecf4 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/complex.h.0p @@ -0,0 +1,254 @@ +'\" et +.TH complex.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +complex.h +\(em complex arithmetic +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following macros: +.IP complex 12 +Expands to +.BR _Complex . +.IP _Complex_I 12 +Expands to a constant expression of type +.BR "const float _Complex" , +with the value of the imaginary unit (that is, a number +.IR i +such that \fIi\fR\s-3\u2\d\s+3=\(mi1). +.IP imaginary 12 +Expands to +.BR _Imaginary . +.IP _Imaginary_I 12 +Expands to a constant expression of type +.BR "const float _Imaginary" +with the value of the imaginary unit. +.IP I 12 +Expands to either _Imaginary_I or _Complex_I. If _Imaginary_I is not +defined, I expands to _Complex_I. +.P +The macros imaginary and _Imaginary_I shall be defined if and only if +the implementation supports imaginary types. +.P +An application may undefine and then, perhaps, redefine the complex, +imaginary, and I macros. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +double cabs(double complex); +float cabsf(float complex); +long double cabsl(long double complex); +double complex cacos(double complex); +float complex cacosf(float complex); +double complex cacosh(double complex); +float complex cacoshf(float complex); +long double complex cacoshl(long double complex); +long double complex cacosl(long double complex); +double carg(double complex); +float cargf(float complex); +long double cargl(long double complex); +double complex casin(double complex); +float complex casinf(float complex); +double complex casinh(double complex); +float complex casinhf(float complex); +long double complex casinhl(long double complex); +long double complex casinl(long double complex); +double complex catan(double complex); +float complex catanf(float complex); +double complex catanh(double complex); +float complex catanhf(float complex); +long double complex catanhl(long double complex); +long double complex catanl(long double complex); +double complex ccos(double complex); +float complex ccosf(float complex); +double complex ccosh(double complex); +float complex ccoshf(float complex); +long double complex ccoshl(long double complex); +long double complex ccosl(long double complex); +double complex cexp(double complex); +float complex cexpf(float complex); +long double complex cexpl(long double complex); +double cimag(double complex); +float cimagf(float complex); +long double cimagl(long double complex); +double complex clog(double complex); +float complex clogf(float complex); +long double complex clogl(long double complex); +double complex conj(double complex); +float complex conjf(float complex); +long double complex conjl(long double complex); +double complex cpow(double complex, double complex); +float complex cpowf(float complex, float complex); +long double complex cpowl(long double complex, long double complex); +double complex cproj(double complex); +float complex cprojf(float complex); +long double complex cprojl(long double complex); +double creal(double complex); +float crealf(float complex); +long double creall(long double complex); +double complex csin(double complex); +float complex csinf(float complex); +double complex csinh(double complex); +float complex csinhf(float complex); +long double complex csinhl(long double complex); +long double complex csinl(long double complex); +double complex csqrt(double complex); +float complex csqrtf(float complex); +long double complex csqrtl(long double complex); +double complex ctan(double complex); +float complex ctanf(float complex); +double complex ctanh(double complex); +float complex ctanhf(float complex); +long double complex ctanhl(long double complex); +long double complex ctanl(long double complex); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Values are interpreted as radians, not degrees. +.SH RATIONALE +The choice of +.IR I +instead of +.IR i +for the imaginary unit concedes to the widespread use of the identifier +.IR i +for other purposes. The application can use a different identifier, say +.IR j , +for the imaginary unit by following the inclusion of the +.IR +header with: +.sp +.RS 4 +.nf +\fB +#undef I +#define j _Imaginary_I +.fi \fR +.P +.RE +.P +An +.IR I +suffix to designate imaginary constants is not required, as +multiplication by +.IR I +provides a sufficiently convenient and more generally useful notation +for imaginary terms. The corresponding real type for the imaginary unit +is +.BR float , +so that use of +.IR I +for algorithmic or notational convenience will not result in +widening types. +.P +On systems with imaginary types, the application has the ability to +control whether use of the macro I introduces an imaginary type, by +explicitly defining I to be _Imaginary_I or _Complex_I. Disallowing +imaginary types is useful for some applications intended to run on +implementations without support for such types. +.P +The macro _Imaginary_I provides a test for whether imaginary types are +supported. +.P +The +\fIcis\fR() +function (\fIcos\fR(\fIx\fR) + \fII\fR*\fIsin\fR(\fIx\fR)) was +considered but rejected because its implementation is easy and +straightforward, even though some implementations could compute sine +and cosine more efficiently in tandem. +.SH "FUTURE DIRECTIONS" +The following function names and the same names suffixed with +.IR f +or +.IR l +are reserved for future use, and may be added to the declarations +in the +.IR +header. +.sp +.RS +.TS +tab(!); +l l l. +T{ +.nf +\fIcerf\fR() +\fIcerfc\fR() +\fIcexp2\fR() +T}!T{ +.nf +\fIcexpm1\fR() +\fIclog10\fR() +\fIclog1p\fR() +T}!T{ +.nf +\fIclog2\fR() +\fIclgamma\fR() +\fIctgamma\fR() +.fi +T} +.TE +.RE +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcabs\fR\^(\|)", +.IR "\fIcacos\fR\^(\|)", +.IR "\fIcacosh\fR\^(\|)", +.IR "\fIcarg\fR\^(\|)", +.IR "\fIcasin\fR\^(\|)", +.IR "\fIcasinh\fR\^(\|)", +.IR "\fIcatan\fR\^(\|)", +.IR "\fIcatanh\fR\^(\|)", +.IR "\fIccos\fR\^(\|)", +.IR "\fIccosh\fR\^(\|)", +.IR "\fIcexp\fR\^(\|)", +.IR "\fIcimag\fR\^(\|)", +.IR "\fIclog\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcpow\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)", +.IR "\fIcreal\fR\^(\|)", +.IR "\fIcsin\fR\^(\|)", +.IR "\fIcsinh\fR\^(\|)", +.IR "\fIcsqrt\fR\^(\|)", +.IR "\fIctan\fR\^(\|)", +.IR "\fIctanh\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/cpio.h.0p b/man-pages-posix-2013-a/man0p/cpio.h.0p new file mode 100644 index 0000000..f3727ac --- /dev/null +++ b/man-pages-posix-2013-a/man0p/cpio.h.0p @@ -0,0 +1,91 @@ +'\" et +.TH cpio.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cpio.h +\(em cpio archive values +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the symbolic constants needed by the +.IR c_mode +field of the +.IR cpio +archive format, with the names and values given in the following table: +.TS +box center tab(@); +cB| cB |cB +l| l |c. +Name@Description@Value (Octal) +_ +C_IRUSR@Read by owner.@0000400 +C_IWUSR@Write by owner.@0000200 +C_IXUSR@Execute by owner.@0000100 +C_IRGRP@Read by group.@0000040 +C_IWGRP@Write by group.@0000020 +C_IXGRP@Execute by group.@0000010 +C_IROTH@Read by others.@0000004 +C_IWOTH@Write by others.@0000002 +C_IXOTH@Execute by others.@0000001 +C_ISUID@Set user ID.@0004000 +C_ISGID@Set group ID.@0002000 +C_ISVTX@On directories, restricted deletion flag.@0001000 +C_ISDIR@Directory.@0040000 +C_ISFIFO@FIFO.@0010000 +C_ISREG@Regular file.@0100000 +C_ISBLK@Block special.@0060000 +C_ISCHR@Character special.@0020000 +C_ISCTG@Reserved.@0110000 +C_ISLNK@Symbolic link.@0120000 +C_ISSOCK@Socket.@0140000 +.TE +.P +The +.IR +header shall define the following symbolic constant as a string: +.sp +.RS 4 +.nf +\fB +MAGIC "070707" +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIpax\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/ctype.h.0p b/man-pages-posix-2013-a/man0p/ctype.h.0p new file mode 100644 index 0000000..a85b241 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/ctype.h.0p @@ -0,0 +1,138 @@ +'\" et +.TH ctype.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctype.h +\(em character types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR , +representing a locale object. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +int isalnum(int); +int isalnum_l(int, locale_t); +int isalpha(int); +int isalpha_l(int, locale_t); +int isascii(int); +int isblank(int); +int isblank_l(int, locale_t); +int iscntrl(int); +int iscntrl_l(int, locale_t); +int isdigit(int); +int isdigit_l(int, locale_t); +int isgraph(int); +int isgraph_l(int, locale_t); +int islower(int); +int islower_l(int, locale_t); +int isprint(int); +int isprint_l(int, locale_t); +int ispunct(int); +int ispunct_l(int, locale_t); +int isspace(int); +int isspace_l(int, locale_t); +int isupper(int); +int isupper_l(int, locale_t); +int isxdigit(int); +int isxdigit_l(int, locale_t); +int toascii(int); +int tolower(int); +int tolower_l(int, locale_t); +int toupper(int); +int toupper_l(int, locale_t); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following as macros: +.sp +.RS 4 +.nf +\fB +int _toupper(int); +int _tolower(int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisascii\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fImblen\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fItoascii\fR\^(\|)", +.IR "\fItolower\fR\^(\|)", +.IR "\fI_tolower\fR\^(\|)", +.IR "\fItoupper\fR\^(\|)", +.IR "\fI_toupper\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/dirent.h.0p b/man-pages-posix-2013-a/man0p/dirent.h.0p new file mode 100644 index 0000000..3df87ce --- /dev/null +++ b/man-pages-posix-2013-a/man0p/dirent.h.0p @@ -0,0 +1,163 @@ +'\" et +.TH dirent.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dirent.h +\(em format of directory entries +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The internal format of directories is unspecified. +.P +The +.IR +header shall define the following type: +.IP "\fBDIR\fR" 8 +A type representing a directory stream. The +.BR DIR +type may be an incomplete type. +.P +It shall also define the structure +.BR dirent +which shall include the following members: +.sp +.RS 4 +.nf +\fB +ino_t d_ino \fRFile serial number.\fR +char d_name[] \fRFilename string of entry.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR ino_t +type as described in +.IR . +.P +The array +.IR d_name +is of unspecified size, but shall contain a filename of at most +{NAME_MAX} +bytes followed by a terminating null byte. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int alphasort(const struct dirent **, const struct dirent **); +int closedir(DIR *); +int dirfd(DIR *); +DIR *fdopendir(int); +DIR *opendir(const char *); +struct dirent *readdir(DIR *); +int readdir_r(DIR *restrict, struct dirent *restrict, + struct dirent **restrict); +void rewinddir(DIR *); +int scandir(const char *, struct dirent ***, + int (*)(const struct dirent *), + int (*)(const struct dirent **, + const struct dirent **)); +void seekdir(DIR *, long); +long telldir(DIR *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Information similar to that in the +.IR +header is contained in a file +.IR +in 4.2 BSD and 4.3 BSD. The equivalent in these implementations of +.BR "struct dirent" +from this volume of POSIX.1\(hy2008 is +.BR "struct direct" . +The filename was changed because the name +.IR +was also used in earlier implementations to refer to definitions +related to the older access method; this produced name conflicts. The +name of the structure was changed because this volume of POSIX.1\(hy2008 does not completely +define what is in the structure, so it could be different on some +implementations from +.BR "struct direct" . +.P +The name of an array of +.BR char +of an unspecified size should not be used as an lvalue. Use of: +.sp +.RS 4 +.nf +\fB +sizeof(d_name) +.fi \fR +.P +.RE +.P +is incorrect; use: +.sp +.RS 4 +.nf +\fB +strlen(d_name) +.fi \fR +.P +.RE +.P +instead. +.P +The array of +.BR char +.IR d_name +is not a fixed size. Implementations may need to declare +.BR "struct dirent" +with an array size for +.IR d_name +of 1, but the actual number of bytes provided matches (or only slightly +exceeds) the length of the filename string. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIalphasort\fR\^(\|)", +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIrewinddir\fR\^(\|)", +.IR "\fIseekdir\fR\^(\|)", +.IR "\fItelldir\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/dlfcn.h.0p b/man-pages-posix-2013-a/man0p/dlfcn.h.0p new file mode 100644 index 0000000..a33c254 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/dlfcn.h.0p @@ -0,0 +1,78 @@ +'\" et +.TH dlfcn.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dlfcn.h +\(em dynamic linking +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define at least the following symbolic constants for use +in the construction of a +\fIdlopen\fR() +.IR mode +argument: +.IP RTLD_LAZY 14 +Relocations are performed at an implementation-defined time. +.IP RTLD_NOW 14 +Relocations are performed when the object is loaded. +.IP RTLD_GLOBAL 14 +All symbols are available for relocation processing of other modules. +.IP RTLD_LOCAL 14 +All symbols are not made available for relocation processing by other +modules. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int dlclose(void *); +char *dlerror(void); +void *dlopen(const char *, int); +void *dlsym(void *restrict, const char *restrict); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIdlclose\fR\^(\|)", +.IR "\fIdlerror\fR\^(\|)", +.IR "\fIdlopen\fR\^(\|)", +.IR "\fIdlsym\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/errno.h.0p b/man-pages-posix-2013-a/man0p/errno.h.0p new file mode 100644 index 0000000..856ae5e --- /dev/null +++ b/man-pages-posix-2013-a/man0p/errno.h.0p @@ -0,0 +1,333 @@ +'\" et +.TH errno.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +errno.h +\(em system error numbers +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends +the ISO\ C standard. Any conflict between the requirements described here +and the ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The ISO\ C standard only requires the symbols +.BR [EDOM] , +.BR [EILSEQ] , +and +.BR [ERANGE] +to be defined. +.P +The +.IR +header shall provide a declaration or definition for +.IR errno . +The symbol +.IR errno +shall expand to a modifiable lvalue of type +.BR int . +It is unspecified whether +.IR errno +is a macro or an identifier declared with external linkage. If a macro +definition is suppressed in order to access an actual object, or a +program defines an identifier with the name +.IR errno , +the behavior is undefined. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions with type +.BR int , +distinct positive values (except as noted below), and which shall be +suitable for use in +.BR #if +preprocessing directives: +.TP +.BR E2BIG +Argument list too long. +.TP +.BR EACCES +Permission denied. +.TP +.BR EADDRINUSE +Address in use. +.TP +.BR EADDRNOTAVAIL +Address not available. +.TP +.BR EAFNOSUPPORT +Address family not supported. +.TP +.BR EAGAIN +Resource unavailable, try again (may be the same value as +.BR [EWOULDBLOCK] ). +.TP +.BR EALREADY +Connection already in progress. +.TP +.BR EBADF +Bad file descriptor. +.TP +.BR EBADMSG +Bad message. +.TP +.BR EBUSY +Device or resource busy. +.TP +.BR ECANCELED +Operation canceled. +.TP +.BR ECHILD +No child processes. +.TP +.BR ECONNABORTED +Connection aborted. +.TP +.BR ECONNREFUSED +Connection refused. +.TP +.BR ECONNRESET +Connection reset. +.TP +.BR EDEADLK +Resource deadlock would occur. +.TP +.BR EDESTADDRREQ +Destination address required. +.TP +.BR EDOM +Mathematics argument out of domain of function. +.TP +.BR EDQUOT +Reserved. +.TP +.BR EEXIST +File exists. +.TP +.BR EFAULT +Bad address. +.TP +.BR EFBIG +File too large. +.TP +.BR EHOSTUNREACH +Host is unreachable. +.TP +.BR EIDRM +Identifier removed. +.TP +.BR EILSEQ +Illegal byte sequence. +.TP +.BR EINPROGRESS +Operation in progress. +.TP +.BR EINTR +Interrupted function. +.TP +.BR EINVAL +Invalid argument. +.TP +.BR EIO +I/O error. +.TP +.BR EISCONN +Socket is connected. +.TP +.BR EISDIR +Is a directory. +.TP +.BR ELOOP +Too many levels of symbolic links. +.TP +.BR EMFILE +File descriptor value too large. +.TP +.BR EMLINK +Too many links. +.TP +.BR EMSGSIZE +Message too large. +.TP +.BR EMULTIHOP +Reserved. +.TP +.BR ENAMETOOLONG +Filename too long. +.TP +.BR ENETDOWN +Network is down. +.TP +.BR ENETRESET +Connection aborted by network. +.TP +.BR ENETUNREACH +Network unreachable. +.TP +.BR ENFILE +Too many files open in system. +.TP +.BR ENOBUFS +No buffer space available. +.TP +.BR ENODATA +No message is available on the STREAM head read queue. +.TP +.BR ENODEV +No such device. +.TP +.BR ENOENT +No such file or directory. +.TP +.BR ENOEXEC +Executable file format error. +.TP +.BR ENOLCK +No locks available. +.TP +.BR ENOLINK +Reserved. +.TP +.BR ENOMEM +Not enough space. +.TP +.BR ENOMSG +No message of the desired type. +.TP +.BR ENOPROTOOPT +Protocol not available. +.TP +.BR ENOSPC +No space left on device. +.TP +.BR ENOSR +No STREAM resources. +.TP +.BR ENOSTR +Not a STREAM. +.TP +.BR ENOSYS +Function not supported. +.TP +.BR ENOTCONN +The socket is not connected. +.TP +.BR ENOTDIR +Not a directory or a symbolic link to a directory. +.TP +.BR ENOTEMPTY +Directory not empty. +.TP +.BR ENOTRECOVERABLE +.br +State not recoverable. +.TP +.BR ENOTSOCK +Not a socket. +.TP +.BR ENOTSUP +Not supported (may be the same value as +.BR [EOPNOTSUPP] ). +.TP +.BR ENOTTY +Inappropriate I/O control operation. +.TP +.BR ENXIO +No such device or address. +.TP +.BR EOPNOTSUPP +Operation not supported on socket (may be the same value as +.BR [ENOTSUP] ). +.TP +.BR EOVERFLOW +Value too large to be stored in data type. +.TP +.BR EOWNERDEAD +Previous owner died. +.TP +.BR EPERM +Operation not permitted. +.TP +.BR EPIPE +Broken pipe. +.TP +.BR EPROTO +Protocol error. +.TP +.BR EPROTONOSUPPORT +.br +Protocol not supported. +.TP +.BR EPROTOTYPE +Protocol wrong type for socket. +.TP +.BR ERANGE +Result too large. +.TP +.BR EROFS +Read-only file system. +.TP +.BR ESPIPE +Invalid seek. +.TP +.BR ESRCH +No such process. +.TP +.BR ESTALE +Reserved. +.TP +.BR ETIME +Stream +\fIioctl\fR() +timeout. +.TP +.BR ETIMEDOUT +Connection timed out. +.TP +.BR ETXTBSY +Text file busy. +.TP +.BR EWOULDBLOCK +Operation would block (may be the same value as +.BR [EAGAIN] ). +.TP +.BR EXDEV +Cross-device link. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Additional error numbers may be defined on conforming systems; see +the System Interfaces volume of POSIX.1\(hy2008. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.3" ", " "Error Numbers" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/fcntl.h.0p b/man-pages-posix-2013-a/man0p/fcntl.h.0p new file mode 100644 index 0000000..6848144 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/fcntl.h.0p @@ -0,0 +1,375 @@ +'\" et +.TH fcntl.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fcntl.h +\(em file control options +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants for the +.IR cmd +argument used by +\fIfcntl\fR(). +The values shall be unique and shall be suitable for use in +.BR #if +preprocessing directives. +.IP F_DUPFD 12 +Duplicate file descriptor. +.IP F_DUPFD_CLOEXEC 12 +.br +Duplicate file descriptor with the close-on-\c +.IR exec +flag FD_CLOEXEC set. +.IP F_GETFD 12 +Get file descriptor flags. +.IP F_SETFD 12 +Set file descriptor flags. +.IP F_GETFL 12 +Get file status flags and file access modes. +.IP F_SETFL 12 +Set file status flags. +.IP F_GETLK 12 +Get record locking information. +.IP F_SETLK 12 +Set record locking information. +.IP F_SETLKW 12 +Set record locking information; wait if blocked. +.IP F_GETOWN 12 +Get process or process group ID to receive SIGURG signals. +.IP F_SETOWN 12 +Set process or process group ID to receive SIGURG signals. +.P +The +.IR +header shall define the following symbolic constant used for the +\fIfcntl\fR() +file descriptor flags, which shall be suitable for use in +.BR #if +preprocessing directives. +.IP FD_CLOEXEC 12 +Close the file descriptor upon execution of an +.IR exec +family function. +.P +The +.IR +header shall also define the following symbolic constants for the +.IR l_type +argument used for record locking with +\fIfcntl\fR(). +The values shall be unique and shall be suitable for use in +.BR #if +preprocessing directives. +.IP F_RDLCK 12 +Shared or read lock. +.IP F_UNLCK 12 +Unlock. +.IP F_WRLCK 12 +Exclusive or write lock. +.P +The +.IR +header shall define the values used for +.IR l_whence , +SEEK_SET, SEEK_CUR, and SEEK_END +as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants as file creation +flags for use in the +.IR oflag +value to +\fIopen\fR() +and +\fIopenat\fR(). +The values shall be bitwise-distinct and shall be suitable for use in +.BR #if +preprocessing directives. +.IP O_CLOEXEC 12 +The FD_CLOEXEC flag associated with the new descriptor shall be +set to close the file descriptor upon execution of an +.IR exec +family function. +.IP O_CREAT 12 +Create file if it does not exist. +.IP O_DIRECTORY 12 +Fail if not a directory. +.IP O_EXCL 12 +Exclusive use flag. +.IP O_NOCTTY 12 +Do not assign controlling terminal. +.IP O_NOFOLLOW 12 +Do not follow symbolic links. +.IP O_TRUNC 12 +Truncate flag. +.IP O_TTY_INIT 12 +Set the +.BR termios +structure terminal parameters to a state that provides conforming +behavior; see +.IR "Section 11.2" ", " "Parameters that Can be Set". +.P +The O_TTY_INIT flag can have the value zero and in this case it need +not be bitwise-distinct from the other flags. +.P +The +.IR +header shall define the following symbolic constants for use as +file status flags for +\fIopen\fR(), +\fIopenat\fR(), +and +\fIfcntl\fR(). +The values shall be suitable for use in +.BR #if +preprocessing directives. +.IP O_APPEND 12 +Set append mode. +.IP O_DSYNC 12 +Write according to synchronized I/O data integrity completion. +.IP O_NONBLOCK 12 +Non-blocking mode. +.IP O_RSYNC 12 +Synchronized read I/O operations. +.IP O_SYNC 12 +Write according to synchronized I/O file integrity completion. +.P +The +.IR +header shall define the following symbolic constant for use as the mask +for file access modes. The value shall be suitable for use in +.BR #if +preprocessing directives. +.IP O_ACCMODE 12 +Mask for file access modes. +.P +The +.IR +header shall define the following symbolic constants for use as +the file access modes for +\fIopen\fR(), +\fIopenat\fR(), +and +\fIfcntl\fR(). +The values shall be unique, except that O_EXEC and O_SEARCH may have +equal values. The values shall be suitable for use in +.BR #if +preprocessing directives. +.IP O_EXEC 12 +Open for execute only (non-directory files). The result is unspecified +if this flag is applied to a directory. +.IP O_RDONLY 12 +Open for reading only. +.IP O_RDWR 12 +Open for reading and writing. +.IP O_SEARCH 12 +Open directory for search only. The result is unspecified if this flag +is applied to a non-directory file. +.IP O_WRONLY 12 +Open for writing only. +.P +The +.IR +header shall define the symbolic constants for file modes for use as +values of +.BR mode_t +as described in +.IR . +.P +The +.IR +header shall define the following symbolic constant as a special value +used in place of a file descriptor for the +.IR *at (\|) +functions which take a directory file descriptor as a parameter: +.IP AT_FDCWD 12 +Use the current working directory to determine the target of relative +file paths. +.P +The +.IR +header shall define the following symbolic constant as a value for the +.IR flag +used by +\fIfaccessat\fR(): +.IP AT_EACCESS 12 +Check access using effective user and group ID. +.P +The +.IR +header shall define the following symbolic constant as a value for the +.IR flag +used by +\fIfstatat\fR(), +\fIfchmodat\fR(), +\fIfchownat\fR(), +and +\fIutimensat\fR(): +.IP AT_SYMLINK_NOFOLLOW 12 +.br +Do not follow symbolic links. +.P +The +.IR +header shall define the following symbolic constant as a value for +the flag used by +\fIlinkat\fR(): +.IP AT_SYMLINK_FOLLOW 12 +.br +Follow symbolic link. +.br +.P +The +.IR +header shall define the following symbolic constant as a value +for the flag used by +\fIunlinkat\fR(): +.IP AT_REMOVEDIR 12 +.br +Remove directory instead of file. +.P +The +.IR +header shall define the following symbolic constants for the +.IR advice +argument used by +\fIposix_fadvise\fR(): +.IP POSIX_FADV_DONTNEED 6 +.br +The application expects that it will not access the specified data in +the near future. +.IP POSIX_FADV_NOREUSE 6 +.br +The application expects to access the specified data once and then not +reuse it thereafter. +.IP POSIX_FADV_NORMAL 6 +.br +The application has no advice to give on its behavior with respect to +the specified data. It is the default characteristic if no advice is +given for an open file. +.IP POSIX_FADV_RANDOM 6 +.br +The application expects to access the specified data in a random +order. +.IP POSIX_FADV_SEQUENTIAL 6 +.br +The application expects to access the specified data sequentially from +lower offsets to higher offsets. +.IP POSIX_FADV_WILLNEED 6 +.br +The application expects to access the specified data in the near +future. +.P +The +.IR +header shall define the +.BR flock +structure describing a file lock. It shall include the following members: +.sp +.RS 4 +.nf +\fB +short l_type \fRType of lock; F_RDLCK, F_WRLCK, F_UNLCK.\fR +short l_whence \fRFlag for starting offset.\fR +off_t l_start \fRRelative offset in bytes.\fR +off_t l_len \fRSize; if 0 then until EOF.\fR +pid_t l_pid \fRProcess ID of the process holding the lock; returned with F_GETLK.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR mode_t , +.BR off_t , +and +.BR pid_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int creat(const char *, mode_t); +int fcntl(int, int, ...); +int open(const char *, int, ...); +int openat(int, const char *, int, ...); +int posix_fadvise(int, off_t, off_t, int); +int posix_fallocate(int, off_t, off_t); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Although no existing implementation defines AT_SYMLINK_FOLLOW and +AT_SYMLINK_NOFOLLOW as the same numeric value, POSIX.1\(hy2008 does not prohibit +that as the two constants are not used with the same interfaces. +.SH RATIONALE +While many of the symbolic constants introduced in the +.IR +header do not strictly need to be used in +.BR #if +preprocessor directives, widespread historic practice has defined +them as macros that are usable in such constructs, and examination +of existing applications has shown that they are occasionally used in +such a way. Therefore it was decided to retain this requirement on an +implementation in POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcreat\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_fadvise\fR\^(\|)", +.IR "\fIposix_fallocate\fR\^(\|)", +.IR "\fIposix_madvise\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/fenv.h.0p b/man-pages-posix-2013-a/man0p/fenv.h.0p new file mode 100644 index 0000000..b0b014d --- /dev/null +++ b/man-pages-posix-2013-a/man0p/fenv.h.0p @@ -0,0 +1,285 @@ +'\" et +.TH fenv.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fenv.h +\(em floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBfenv_t\fR" 10 +Represents the entire floating-point environment. The floating-point +environment refers collectively to any floating-point status flags and +control modes supported by the implementation. +.IP "\fBfexcept_t\fR" 10 +Represents the floating-point status flags collectively, including any +status the implementation associates with the flags. A floating-point +status flag is a system variable whose value is set (but never cleared) +when a floating-point exception is raised, which occurs as a side-effect +of exceptional floating-point arithmetic to provide auxiliary +information. A floating-point control mode is a system variable whose +value may be set by the user to affect the subsequent behavior of +floating-point arithmetic. +.P +The +.IR +header shall define each of the following macros if and only if the +implementation supports the floating-point exception by means of the +floating-point functions +\fIfeclearexcept\fR(), +\fIfegetexceptflag\fR(), +\fIferaiseexcept\fR(), +\fIfesetexceptflag\fR(), +and +\fIfetestexcept\fR(). +The defined macros shall expand to integer constant expressions with +values that are bitwise-distinct. +.sp +.RS +FE_DIVBYZERO +FE_INEXACT +FE_INVALID +FE_OVERFLOW +FE_UNDERFLOW +.RE +.P +If the implementation supports the IEC 60559 Floating-Point option, all +five macros shall be defined. +Additional implementation-defined floating-point exceptions with +macros beginning with FE_ and an uppercase letter may also be +specified by the implementation. +.P +The +.IR +header shall define the macro FE_ALL_EXCEPT as the bitwise-inclusive +OR of all floating-point exception macros defined by the +implementation, if any. If no such macros are defined, then the +macro FE_ALL_EXCEPT shall be defined as zero. +.P +The +.IR +header shall define each of the following macros if and only if the +implementation supports getting and setting the represented rounding +direction by means of the +\fIfegetround\fR() +and +\fIfesetround\fR() +functions. The defined macros shall expand to integer constant +expressions whose values are distinct non-negative values. +.sp +.RS +FE_DOWNWARD +FE_TONEAREST +FE_TOWARDZERO +FE_UPWARD +.RE +.P +If the implementation supports the IEC 60559 Floating-Point option, all +four macros shall be defined. +Additional implementation-defined rounding directions with macros +beginning with FE_ and an uppercase letter may also be specified by the +implementation. +.P +The +.IR +header shall define the following macro, which represents the +default floating-point environment (that is, the one installed at +program startup) and has type pointer to const-qualified +.BR fenv_t . +It can be used as an argument to the functions within the +.IR +header that manage the floating-point environment. +.sp +.RS +FE_DFL_ENV +.RE +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int feclearexcept(int); +int fegetenv(fenv_t *); +int fegetexceptflag(fexcept_t *, int); +int fegetround(void); +int feholdexcept(fenv_t *); +int feraiseexcept(int); +int fesetenv(const fenv_t *); +int fesetexceptflag(const fexcept_t *, int); +int fesetround(int); +int fetestexcept(int); +int feupdateenv(const fenv_t *); +.fi \fR +.P +.RE +.P +The FENV_ACCESS pragma provides a means to inform the implementation +when an application might access the floating-point environment to test +floating-point status flags or run under non-default floating-point +control modes. The pragma shall occur either outside external +declarations or preceding all explicit declarations and statements +inside a compound statement. When outside external declarations, the +pragma takes effect from its occurrence until another FENV_ACCESS +pragma is encountered, or until the end of the translation unit. When +inside a compound statement, the pragma takes effect from its +occurrence until another FENV_ACCESS pragma is encountered (including +within a nested compound statement), or until the end of the compound +statement; at the end of a compound statement the state for the pragma +is restored to its condition just before the compound statement. If +this pragma is used in any other context, the behavior is undefined. If +part of an application tests floating-point status flags, sets +floating-point control modes, or runs under non-default mode settings, +but was translated with the state for the FENV_ACCESS pragma off, the +behavior is undefined. The default state (on or off) for the pragma is +implementation-defined. (When execution passes from a part of the +application translated with FENV_ACCESS off to a part translated with +FENV_ACCESS on, the state of the floating-point status flags is +unspecified and the floating-point control modes have their default +settings.) +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This header is designed to support the floating-point exception status +flags and directed-rounding control modes required by the IEC\ 60559:\|1989 standard, and +other similar floating-point state information. Also it is designed to +facilitate code portability among all systems. +.P +Certain application programming conventions support the intended model +of use for the floating-point environment: +.IP " *" 4 +A function call does not alter its caller's floating-point control +modes, clear its caller's floating-point status flags, nor depend on +the state of its caller's floating-point status flags unless the +function is so documented. +.IP " *" 4 +A function call is assumed to require default floating-point control +modes, unless its documentation promises otherwise. +.IP " *" 4 +A function call is assumed to have the potential for raising +floating-point exceptions, unless its documentation promises otherwise. +.P +With these conventions, an application can safely assume default +floating-point control modes (or be unaware of them). The +responsibilities associated with accessing the floating-point +environment fall on the application that does so explicitly. +.P +Even though the rounding direction macros may expand to constants +corresponding to the values of FLT_ROUNDS, they are not required to do +so. +.P +For example: +.sp +.RS 4 +.nf +\fB +#include +void f(double x) +{ + #pragma STDC FENV_ACCESS ON + void g(double); + void h(double); + /* ... */ + g(x + 1); + h(x + 1); + /* ... */ +} +.fi \fR +.P +.RE +.P +If the function +\fIg\fR() +might depend on status flags set as a side-effect of the first +.IR x +1, +or if the second +.IR x +1 +might depend on control modes set as a side-effect of the call to +function +\fIg\fR(), +then the application shall contain an appropriately placed invocation +as follows: +.sp +.RS 4 +.nf +\fB +#pragma STDC FENV_ACCESS ON +.fi \fR +.P +.RE +.SH RATIONALE +.SS "The fexcept_t Type" +.P +.BR fexcept_t +does not have to be an integer type. Its values must be obtained by a +call to +\fIfegetexceptflag\fR(), +and cannot be created by logical operations from the exception macros. +An implementation might simply implement +.BR fexcept_t +as an +.BR int +and use the representations reflected by the exception macros, but is +not required to; other representations might contain extra information +about the exceptions. +.BR fexcept_t +might be a +.BR struct +with a member for each exception (that might hold the address of the +first or last floating-point instruction that caused that exception). +The ISO/IEC\ 9899:\|1999 standard makes no claims about the internals of an +.BR fexcept_t , +and so the user cannot inspect it. +.SS "Exception and Rounding Macros" +.P +Macros corresponding to unsupported modes and rounding directions are +not defined by the implementation and must not be defined by the +application. An application might use +.BR #ifdef +to test for this. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfegetenv\fR\^(\|)", +.IR "\fIfegetexceptflag\fR\^(\|)", +.IR "\fIfegetround\fR\^(\|)", +.IR "\fIfeholdexcept\fR\^(\|)", +.IR "\fIferaiseexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfeupdateenv\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/float.h.0p b/man-pages-posix-2013-a/man0p/float.h.0p new file mode 100644 index 0000000..f63b661 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/float.h.0p @@ -0,0 +1,364 @@ +'\" et +.TH float.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.EQ +delim $$ +.EN +.SH NAME +float.h +\(em floating types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The characteristics of floating types are defined in terms of a model +that describes a representation of floating-point numbers and values +that provide information about an implementation's floating-point +arithmetic. +.P +The following parameters are used to define the model for each +floating-point type: +.IP "\fIs\fP" 6 +Sign (\(+-1). +.IP "\fIb\fP" 6 +Base or radix of exponent representation (an integer >1). +.IP "\fIe\fP" 6 +Exponent (an integer between a minimum $e_ min$ and a maximum +$e_ max$). +.IP "\fIp\fP" 6 +Precision (the number of base\(mi\fIb\fP digits in the significand). +.IP "$f_ k$" 6 +Non-negative integers less than +.IR b +(the significand digits). +.P +A floating-point number +.IR x +is defined by the following model: +.P +.EQ +x " " = " " sb"^" e" " " " sum from k=1 to p^ " " f_ k" " " " b"^" " "-k , + " " e_ min" " " " <= " " e " " <= " " e_ max" " +.EN +.P +In addition to normalized floating-point numbers ($f_ 1$>0 if +.IR x \(!=0), +floating types may be able to contain other kinds of floating-point +numbers, such as subnormal floating-point numbers (\c +.IR x \(!=0, +.IR e =\c +$e_ min$, $f_ 1$=0) and unnormalized floating-point numbers (\c +.IR x \(!=0, +.IR e >\c +$e_ min$, $f_ 1$=0), and values that are not floating-point +numbers, such as infinities and NaNs. A +.IR NaN +is an encoding signifying Not-a-Number. A +.IR "quiet NaN" +propagates through almost every arithmetic operation without raising a +floating-point exception; a +.IR "signaling NaN" +generally raises a floating-point exception when occurring as an +arithmetic operand. +.P +An implementation may give zero and non-numeric values, such as +infinities and NaNs, a sign, or may leave them unsigned. Wherever such +values are unsigned, any requirement in POSIX.1\(hy2008 to retrieve the +sign shall produce an unspecified sign and any requirement to set the +sign shall be ignored. +.P +The accuracy of the floating-point operations (\c +.BR '+' , +.BR '\(mi' , +.BR '*' , +.BR '/' ) +and of the functions in +.IR +and +.IR +that return floating-point results is implementation-defined, as is the +accuracy of the conversion between floating-point internal +representations and string representations performed by the functions +in +.IR , +.IR , +and +.IR . +The implementation may state that the accuracy is unknown. +.P +All integer values in the +.IR +header, except FLT_ROUNDS, shall be constant expressions suitable for +use in +.BR #if +preprocessing directives; all floating values shall be constant +expressions. All except DECIMAL_DIG, FLT_EVAL_METHOD, FLT_RADIX, and +FLT_ROUNDS have separate names for all three floating-point types. The +floating-point model representation is provided for all values except +FLT_EVAL_METHOD and FLT_ROUNDS. +.P +The rounding mode for floating-point addition is characterized by the +implementation-defined value of FLT_ROUNDS: +.IP "\(mi1" 6 +Indeterminable. +.IP "\00" 6 +Toward zero. +.IP "\01" 6 +To nearest. +.IP "\02" 6 +Toward positive infinity. +.IP "\03" 6 +Toward negative infinity. +.P +All other values for FLT_ROUNDS characterize implementation-defined +rounding behavior. +.P +The values of operations with floating operands and values subject to +the usual arithmetic conversions and of floating constants are +evaluated to a format whose range and precision may be greater than +required by the type. The use of evaluation formats is characterized by +the implementation-defined value of FLT_EVAL_METHOD: +.IP "\(mi1" 6 +Indeterminable. +.IP "\00" 6 +Evaluate all operations and constants just to the range and +precision of the type. +.IP "\01" 6 +Evaluate operations and constants of type +.BR float +and +.BR double +to the range and precision of the +.BR double +type; evaluate +.BR "long double" +operations and constants to the range and precision of the +.BR "long double" +type. +.IP "\02" 6 +Evaluate all operations and constants to the range and precision of the +.BR "long double" +type. +.P +All other negative values for FLT_EVAL_METHOD characterize +implementation-defined behavior. +.P +The +.IR +header shall define the following values as constant expressions with +implementation-defined values that are greater or equal in magnitude +(absolute value) to those shown, with the same sign. +.IP " *" 4 +Radix of exponent representation, +.IR b . +.RS 4 +.IP FLT_RADIX 14 +2 +.RE +.IP " *" 4 +Number of base-FLT_RADIX digits in the floating-point significand, +.IR p . +.RS 4 +.IP FLT_MANT_DIG 14 +.IP DBL_MANT_DIG 14 +.IP LDBL_MANT_DIG 14 +.RE +.IP " *" 4 +Number of decimal digits, +.IR n , +such that any floating-point number in the widest supported floating +type with $p_ max$ radix +.IR b +digits can be rounded to a floating-point number with +.IR n +decimal digits and back again without change to the value. +.RS 4 +.P +.EQ +lpile { p_ max" " " " log_ 10" " " " b above +left ceiling " " 1 " " + " " p_ max" " " " log_ 10" " " " b right ceiling } + " " " " lpile {if " " b " " is " " a " " power " " of " " 10 above otherwise} +.EN +.IP DECIMAL_DIG 14 +10 +.RE +.br +.RE +.IP " *" 4 +Number of decimal digits, +.IR q , +such that any floating-point number with +.IR q +decimal digits can be rounded into a floating-point number with +.IR p +radix +.IR b +digits and back again without change to the +.IR q +decimal digits. +.RS 4 +.P +.EQ +lpile { p " " log_ 10" " " " b above +left floor " " (p " " - " " 1) " " log_ 10" " " " b " " right floor } + " " " " lpile {if " " b " " is " " a " " power " " of " " 10 above otherwise} +.EN +.IP FLT_DIG 14 +6 +.IP DBL_DIG 14 +10 +.IP LDBL_DIG 14 +10 +.RE +.IP " *" 4 +Minimum negative integer such that FLT_RADIX raised to that power +minus 1 is a normalized floating-point number, $e_ min$. +.RS 4 +.IP FLT_MIN_EXP 14 +.IP DBL_MIN_EXP 14 +.IP LDBL_MIN_EXP 14 +.RE +.IP " *" 4 +Minimum negative integer such that 10 raised to that power is in +the range of normalized floating-point numbers. +.RS 4 +.P +.EQ +left ceiling " " log_ 10" " " " b"^" " "{ e_ min" " " " "^" " "-1 } ^ " " right ceiling +.EN +.IP FLT_MIN_10_EXP 14 +\(mi37 +.IP DBL_MIN_10_EXP 14 +\(mi37 +.IP LDBL_MIN_10_EXP 14 +\(mi37 +.RE +.IP " *" 4 +Maximum integer such that FLT_RADIX raised to that power +minus 1 is a representable finite floating-point number, $e_ max$. +.RS 4 +.IP FLT_MAX_EXP 14 +.IP DBL_MAX_EXP 14 +.IP LDBL_MAX_EXP 14 +.P +Additionally, FLT_MAX_EXP shall be at least as large as FLT_MANT_DIG, +DBL_MAX_EXP shall be at least as large as DBL_MANT_DIG, and LDBL_MAX_EXP +shall be at least as large as LDBL_MANT_DIG; which has the effect that +FLT_MAX, DBL_MAX, and LDBL_MAX are integral. +.RE +.IP " *" 4 +Maximum integer such that 10 raised to that power is in the range +of representable finite floating-point numbers. +.RS 4 +.P +.EQ +left floor " " log_ 10" " ( ( 1 " " - " " b"^" " "-p ) " " + b"^" e" "_ max" "^ ) " " right floor +.EN +.IP FLT_MAX_10_EXP 14 ++37 +.IP DBL_MAX_10_EXP 14 ++37 +.IP LDBL_MAX_10_EXP 14 ++37 +.RE +.P +The +.IR +header shall define the following values as constant expressions with +implementation-defined values that are greater than or equal to those +shown: +.IP " *" 4 +Maximum representable finite floating-point number. +.RS 4 +.P +.EQ +(1 " " - " " b"^" " "-p^) " " b"^" e" "_ max" " +.EN +.IP FLT_MAX 14 +1E+37 +.IP DBL_MAX 14 +1E+37 +.IP LDBL_MAX 14 +1E+37 +.RE +.P +The +.IR +header shall define the following values as constant expressions with +implementation-defined (positive) values that are less than or equal to +those shown: +.IP " *" 4 +The difference between 1 and the least value greater than 1 +that is representable in the given floating-point type, $b"^" " "{1 " " - " " p}$. +.RS 4 +.IP FLT_EPSILON 14 +1E\(mi5 +.IP DBL_EPSILON 14 +1E\(mi9 +.IP LDBL_EPSILON 14 +1E\(mi9 +.RE +.IP " *" 4 +Minimum normalized positive floating-point number, +$b"^" " "{ e_ min" " " " "^" " "-1 }$. +.RS 4 +.IP FLT_MIN 14 +1E\(mi37 +.IP DBL_MIN 14 +1E\(mi37 +.IP LDBL_MIN 14 +1E\(mi37 +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +All known hardware floating-point formats satisfy the property that the +exponent range is larger than the number of mantissa digits. The ISO\ C standard +permits a floating-point format where this property is not true, such that +the largest finite value would not be integral; however, it is unlikely +that there will ever be hardware support for such a floating-point format, +and it introduces boundary cases that portable programs should not have +to be concerned with (for example, a non-integral DBL_MAX means that +\fIceil\fR() +would have to worry about overflow). Therefore, this standard imposes +an additional requirement that the largest representable finite value +is integral. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/fmtmsg.h.0p b/man-pages-posix-2013-a/man0p/fmtmsg.h.0p new file mode 100644 index 0000000..396e812 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/fmtmsg.h.0p @@ -0,0 +1,129 @@ +'\" et +.TH fmtmsg.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fmtmsg.h +\(em message display structures +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants: +.IP MM_HARD 14 +Source of the condition is hardware. +.IP MM_SOFT 14 +Source of the condition is software. +.IP MM_FIRM 14 +Source of the condition is firmware. +.IP MM_APPL 14 +Condition detected by application. +.IP MM_UTIL 14 +Condition detected by utility. +.IP MM_OPSYS 14 +Condition detected by operating system. +.IP MM_RECOVER 14 +Recoverable error. +.IP MM_NRECOV 14 +Non-recoverable error. +.IP MM_HALT 14 +Error causing application to halt. +.IP MM_ERROR 14 +Application has encountered a non-fatal fault. +.IP MM_WARNING 14 +Application has detected unusual non-error condition. +.IP MM_INFO 14 +Informative message. +.IP MM_NOSEV 14 +No severity level provided for the message. +.IP MM_PRINT 14 +Display message on standard error. +.IP MM_CONSOLE 14 +Display message on system console. +.P +The table below indicates the null values and identifiers for +\fIfmtmsg\fR() +arguments. The +.IR +header shall define the symbolic constants in the +.BR Identifier +column, which shall have the type indicated in the +.BR Type +column: +.TS +box tab(!) center; +cB | cB | cB | cB +lI | lB | l | l. +Argument!Type!Null-Value!Identifier +_ +label!char *!(\fBchar\fR*)0!MM_NULLLBL +severity!int!0!MM_NULLSEV +class!long!\fB0L\fR!MM_NULLMC +text!char *!(\fBchar\fR*)0!MM_NULLTXT +action!char *!(\fBchar\fR*)0!MM_NULLACT +tag!char *!(\fBchar\fR*)0!MM_NULLTAG +.TE +.P +The +.IR +header shall also define the following symbolic constants for use +as return values for +\fIfmtmsg\fR(): +.IP MM_OK 14 +The function succeeded. +.IP MM_NOTOK 14 +The function failed completely. +.IP MM_NOMSG 14 +The function was unable to generate a message on standard error, but +otherwise succeeded. +.IP MM_NOCON 14 +The function was unable to generate a console message, but otherwise +succeeded. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +int fmtmsg(long, const char *, int, + const char *, const char *, const char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfmtmsg\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/fnmatch.h.0p b/man-pages-posix-2013-a/man0p/fnmatch.h.0p new file mode 100644 index 0000000..793945e --- /dev/null +++ b/man-pages-posix-2013-a/man0p/fnmatch.h.0p @@ -0,0 +1,80 @@ +'\" et +.TH fnmatch.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fnmatch.h +\(em filename-matching types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants: +.IP FNM_NOMATCH 14 +The string does not match the specified pattern. +.IP FNM_PATHNAME 14 + +in +.IR string +only matches + +in +.IR pattern . +.IP FNM_PERIOD 14 +Leading + +in +.IR string +must be exactly matched by + +in +.IR pattern . +.IP FNM_NOESCAPE 14 +Disable backslash escaping. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +int fnmatch(const char *, const char *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfnmatch\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/ftw.h.0p b/man-pages-posix-2013-a/man0p/ftw.h.0p new file mode 100644 index 0000000..ecd9c88 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/ftw.h.0p @@ -0,0 +1,131 @@ +'\" et +.TH ftw.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ftw.h +\(em file tree traversal +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR FTW +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int base +int level +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for use as values +of the third argument to the application-supplied function that is +passed as the second argument to +\fIftw\fR() +and +\fInftw\fR(): +.IP FTW_F 14 +Non-directory file. +.IP FTW_D 14 +Directory. +.IP FTW_DNR 14 +Directory without read permission. +.IP FTW_DP 14 +Directory with subdirectories visited. +.IP FTW_NS 14 +Unknown type; +\fIstat\fR() +failed. +.IP FTW_SL 14 +Symbolic link. +.IP FTW_SLN 14 +Symbolic link that names a nonexistent file. +.P +The +.IR +header shall define the following symbolic constants for use as +values of the fourth argument to +\fInftw\fR(): +.IP FTW_PHYS 14 +Physical walk, does not follow symbolic links. Otherwise, +\fInftw\fR() +follows links but does not walk down any path that crosses itself. +.IP FTW_MOUNT 14 +The walk does not cross a mount point. +.IP FTW_DEPTH 14 +All subdirectories are visited before the directory itself. +.IP FTW_CHDIR 14 +The walk changes to each directory before reading it. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int ftw(const char *, int (*)(const char *, const struct stat *, + int), int); +int nftw(const char *, int (*)(const char *, const struct stat *, + int, struct FTW *), int, int); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR stat +structure and the symbolic names for +.IR st_mode +and the file type test macros as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIftw\fR\^(\|)", +.IR "\fInftw\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/glob.h.0p b/man-pages-posix-2013-a/man0p/glob.h.0p new file mode 100644 index 0000000..c6eac83 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/glob.h.0p @@ -0,0 +1,132 @@ +'\" et +.TH glob.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +glob.h +\(em pathname pattern-matching types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structures and symbolic constants used by the +\fIglob\fR() +function. +.P +The +.IR +header shall define the +.BR glob_t +structure type, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +size_t gl_pathc \fRCount of paths matched by \fIpattern.\fR +char **gl_pathv \fRPointer to a list of matched pathnames.\fR +size_t gl_offs \fRSlots to reserve at the beginning of \fIgl_pathv.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants as values for the +.IR flags +argument: +.IP GLOB_APPEND 14 +Append generated pathnames to those previously obtained. +.IP GLOB_DOOFFS 14 +Specify how many null pointers to add to the beginning of +.IR gl_pathv . +.IP GLOB_ERR 14 +Cause +\fIglob\fR() +to return on error. +.IP GLOB_MARK 14 +Each pathname that is a directory that matches +.IR pattern +has a + +appended. +.IP GLOB_NOCHECK 14 +If +.IR pattern +does not match any pathname, then return a list consisting of only +.IR pattern . +.IP GLOB_NOESCAPE 14 +Disable backslash escaping. +.IP GLOB_NOSORT 14 +Do not sort the pathnames returned. +.P +The +.IR +header shall define the following symbolic constants as error +return values: +.IP GLOB_ABORTED 14 +The scan was stopped because GLOB_ERR was set or (*\fIerrfunc\fP)(\|) +returned non-zero. +.IP GLOB_NOMATCH 14 +The pattern does not match any existing pathname, and GLOB_NOCHECK was +not set in +.IR flags . +.IP GLOB_NOSPACE 14 +An attempt to allocate memory failed. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int glob(const char *restrict, int, int(*)(const char *, int), + glob_t *restrict); +void globfree(glob_t *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIglob\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/grp.h.0p b/man-pages-posix-2013-a/man0p/grp.h.0p new file mode 100644 index 0000000..02033ff --- /dev/null +++ b/man-pages-posix-2013-a/man0p/grp.h.0p @@ -0,0 +1,93 @@ +'\" et +.TH grp.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +grp.h +\(em group structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall declare the +.BR group +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +char *gr_name \fRThe name of the group.\fR +gid_t gr_gid \fRNumerical group ID.\fR +char **gr_mem \fRPointer to a null-terminated array of character\fR + \fRpointers to member names.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR gid_t +and +.BR size_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void endgrent(void); +struct group *getgrent(void); +struct group *getgrgid(gid_t); +int getgrgid_r(gid_t, struct group *, char *, + size_t, struct group **); +struct group *getgrnam(const char *); +int getgrnam_r(const char *, struct group *, char *, + size_t , struct group **); +void setgrent(void); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIgetgrnam\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/iconv.h.0p b/man-pages-posix-2013-a/man0p/iconv.h.0p new file mode 100644 index 0000000..0552017 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/iconv.h.0p @@ -0,0 +1,71 @@ +'\" et +.TH iconv.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iconv.h +\(em codeset conversion facility +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following types: +.IP "\fBiconv_t\fP" 12 +Identifies the conversion from one codeset to another. +.IP "\fBsize_t\fP" 12 +As described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +size_t iconv(iconv_t, char **restrict, size_t *restrict, + char **restrict, size_t *restrict); +int iconv_close(iconv_t); +iconv_t iconv_open(const char *, const char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIiconv\fR\^(\|)", +.IR "\fIiconv_close\fR\^(\|)", +.IR "\fIiconv_open\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/inttypes.h.0p b/man-pages-posix-2013-a/man0p/inttypes.h.0p new file mode 100644 index 0000000..4c8ab75 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/inttypes.h.0p @@ -0,0 +1,242 @@ +'\" et +.TH inttypes.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +inttypes.h +\(em fixed size integer types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall include the +.IR +header. +.P +The +.IR +header shall define at least the following types: +.IP "\fBimaxdiv_t\fR" 12 +Structure type that is the type of the value returned by the +\fIimaxdiv\fR() +function. +.IP "\fBwchar_t\fR" 12 +As described in +.IR . +.P +The +.IR +header shall define the following macros. Each expands to a +character string literal containing a conversion specifier, possibly +modified by a length modifier, suitable for use within the +.IR format +argument of a formatted input/output function when converting the +corresponding integer type. These macros have the general form of +PRI (character string literals for the +\fIfprintf\fR() +and +\fIfwprintf\fR() +family of functions) or SCN (character string literals for the +\fIfscanf\fR() +and +\fIfwscanf\fR() +family of functions), followed by the conversion specifier, followed by +a name corresponding to a similar type name in +.IR . +In these names, +.IR N +represents the width of the type as described in +.IR . +For example, +.IR PRIdFAST32 +can be used in a format string to print the value of an integer of type +.BR int_fast32_t . +.P +The +\fIfprintf\fR() +macros for signed integers are: +.sp +.RS +.TS +tab(!); +le le le le le. +PRId\fIN\fR!PRIdLEAST\fIN\fR!PRIdFAST\fIN\fR!PRIdMAX!PRIdPTR +PRIi\fIN\fR!PRIiLEAST\fIN\fR!PRIiFAST\fIN\fR!PRIiMAX!PRIiPTR +.TE +.RE +.P +The +\fIfprintf\fR() +macros for unsigned integers are: +.sp +.RS +.TS +tab(!); +le le le le le. +PRIo\fIN\fR!PRIoLEAST\fIN\fR!PRIoFAST\fIN\fR!PRIoMAX!PRIoPTR +PRIu\fIN\fR!PRIuLEAST\fIN\fR!PRIuFAST\fIN\fR!PRIuMAX!PRIuPTR +PRIx\fIN\fR!PRIxLEAST\fIN\fR!PRIxFAST\fIN\fR!PRIxMAX!PRIxPTR +PRIX\fIN\fR!PRIXLEAST\fIN\fR!PRIXFAST\fIN\fR!PRIXMAX!PRIXPTR +.TE +.RE +.P +The +\fIfscanf\fR() +macros for signed integers are: +.sp +.RS +.TS +tab(!); +le le le le le. +SCNd\fIN\fR!SCNdLEAST\fIN\fR!SCNdFAST\fIN\fR!SCNdMAX!SCNdPTR +SCNi\fIN\fR!SCNiLEAST\fIN\fR!SCNiFAST\fIN\fR!SCNiMAX!SCNiPTR +.TE +.RE +.P +The +\fIfscanf\fR() +macros for unsigned integers are: +.sp +.RS +.TS +tab(!); +le le le le le. +SCNo\fIN\fR!SCNoLEAST\fIN\fR!SCNoFAST\fIN\fR!SCNoMAX!SCNoPTR +SCNu\fIN\fR!SCNuLEAST\fIN\fR!SCNuFAST\fIN\fR!SCNuMAX!SCNuPTR +SCNx\fIN\fR!SCNxLEAST\fIN\fR!SCNxFAST\fIN\fR!SCNxMAX!SCNxPTR +.TE +.RE +.P +For each type that the implementation provides in +.IR , +the corresponding +\fIfprintf\fR() +and +\fIfwprintf\fR() +macros shall be defined and the corresponding +\fIfscanf\fR() +and +\fIfwscanf\fR() +macros shall be defined unless the implementation does not have a +suitable modifier for the type. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +intmax_t imaxabs(intmax_t); +imaxdiv_t imaxdiv(intmax_t, intmax_t); +intmax_t strtoimax(const char *restrict, char **restrict, int); +uintmax_t strtoumax(const char *restrict, char **restrict, int); +intmax_t wcstoimax(const wchar_t *restrict, wchar_t **restrict, int); +uintmax_t wcstoumax(const wchar_t *restrict, wchar_t **restrict, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +.LP +.nf +#include +#include +int main(void) +{ + uintmax_t i = UINTMAX_MAX; // This type always exists. + wprintf(L"The largest integer value is %020" + PRIxMAX "\en", i); + return 0; +} +.fi +.SH "APPLICATION USAGE" +The purpose of +.IR +is to provide a set of integer types whose definitions are consistent +across machines and independent of operating systems and other +implementation idiosyncrasies. It defines, through +.BR typedef , +integer types of various sizes. Implementations are free to +.BR typedef +them as ISO\ C standard integer types or extensions that they support. Consistent +use of this header will greatly increase the portability of applications +across platforms. +.SH RATIONALE +The ISO/IEC\ 9899:\|1990 standard specified that the language should support four signed and +unsigned integer data types\(em\c +.BR char , +.BR short , +.BR int , +and +.BR long \(em\c +but placed very little requirement on their size other than that +.BR int +and +.BR short +be at least 16 bits and +.BR long +be at least as long as +.BR int +and not smaller than 32 bits. For 16-bit systems, most implementations +assigned 8, 16, 16, and 32 bits to +.BR char , +.BR short , +.BR int , +and +.BR long , +respectively. For 32-bit systems, the common practice has been to +assign 8, 16, 32, and 32 bits to these types. This difference in +.BR int +size can create some problems for users who migrate from one system to +another which assigns different sizes to integer types, because the +ISO\ C standard integer promotion rule can produce silent changes unexpectedly. +The need for defining an extended integer type increased with the +introduction of 64-bit systems. +.SH "FUTURE DIRECTIONS" +Macro names beginning with PRI or SCN followed by any lowercase letter +or +.BR 'X' +may be added to the macros defined in the +.IR +header. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIimaxabs\fR\^(\|)", +.IR "\fIimaxdiv\fR\^(\|)", +.IR "\fIstrtoimax\fR\^(\|)", +.IR "\fIwcstoimax\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/iso646.h.0p b/man-pages-posix-2013-a/man0p/iso646.h.0p new file mode 100644 index 0000000..63d1006 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/iso646.h.0p @@ -0,0 +1,74 @@ +'\" et +.TH iso646.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iso646.h +\(em alternative spellings +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following eleven macros (on the left) that +expand to the corresponding tokens (on the right): +.IP and 10 +\&\fR&&\fR +.IP and_eq 10 +\&\fR&=\fR +.IP bitand 10 +\&\fR&\fR +.IP bitor 10 +\&\fR|\fR +.IP compl 10 +\&\fR~\fR +.IP not 10 +\&\fR!\fR +.IP not_eq 10 +\&\fR!=\fR +.IP or 10 +\&\fR||\fR +.IP or_eq 10 +\&\fR|=\fR +.IP xor 10 +\&\fR^\fR +.IP xor_eq 10 +\&\fR^=\fR +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/langinfo.h.0p b/man-pages-posix-2013-a/man0p/langinfo.h.0p new file mode 100644 index 0000000..aaf2461 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/langinfo.h.0p @@ -0,0 +1,195 @@ +'\" et +.TH langinfo.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +langinfo.h +\(em language information constants +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the symbolic constants used to identify items of +.IR langinfo +data (see +\fInl_langinfo\fR()). +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR nl_item +type as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants with type +.BR nl_item . +The entries under +.BR Category +indicate in which +\fIsetlocale\fR() +category each item is defined. +.TS +box center tab(!); +cB | cB | cB +l1 | lI1 | l. +Constant!Category!Meaning +_ +CODESET!LC_CTYPE!Codeset name. +D_T_FMT!LC_TIME!String for formatting date and time. +D_FMT!LC_TIME!Date format string. +T_FMT!LC_TIME!Time format string. +T_FMT_AMPM!LC_TIME!a.m. or p.m. time format string. +AM_STR!LC_TIME!Ante-meridiem affix. +PM_STR!LC_TIME!Post-meridiem affix. +DAY_1!LC_TIME!Name of the first day of the week (for example, Sunday). +DAY_2!LC_TIME!Name of the second day of the week (for example, Monday). +DAY_3!LC_TIME!Name of the third day of the week (for example, Tuesday). +DAY_4!LC_TIME!Name of the fourth day of the week + !!(for example, Wednesday). +DAY_5!LC_TIME!Name of the fifth day of the week (for example, Thursday). +DAY_6!LC_TIME!Name of the sixth day of the week (for example, Friday). +DAY_7!LC_TIME!Name of the seventh day of the week + !!(for example, Saturday). +ABDAY_1!LC_TIME!Abbreviated name of the first day of the week. +ABDAY_2!LC_TIME!Abbreviated name of the second day of the week. +ABDAY_3!LC_TIME!Abbreviated name of the third day of the week. +ABDAY_4!LC_TIME!Abbreviated name of the fourth day of the week. +ABDAY_5!LC_TIME!Abbreviated name of the fifth day of the week. +ABDAY_6!LC_TIME!Abbreviated name of the sixth day of the week. +ABDAY_7!LC_TIME!Abbreviated name of the seventh day of the week. +MON_1!LC_TIME!Name of the first month of the year. +MON_2!LC_TIME!Name of the second month. +MON_3!LC_TIME!Name of the third month. +MON_4!LC_TIME!Name of the fourth month. +MON_5!LC_TIME!Name of the fifth month. +MON_6!LC_TIME!Name of the sixth month. +MON_7!LC_TIME!Name of the seventh month. +MON_8!LC_TIME!Name of the eighth month. +MON_9!LC_TIME!Name of the ninth month. +MON_10!LC_TIME!Name of the tenth month. +MON_11!LC_TIME!Name of the eleventh month. +MON_12!LC_TIME!Name of the twelfth month. +ABMON_1!LC_TIME!Abbreviated name of the first month. +ABMON_2!LC_TIME!Abbreviated name of the second month. +ABMON_3!LC_TIME!Abbreviated name of the third month. +ABMON_4!LC_TIME!Abbreviated name of the fourth month. +ABMON_5!LC_TIME!Abbreviated name of the fifth month. +ABMON_6!LC_TIME!Abbreviated name of the sixth month. +ABMON_7!LC_TIME!Abbreviated name of the seventh month. +ABMON_8!LC_TIME!Abbreviated name of the eighth month. +ABMON_9!LC_TIME!Abbreviated name of the ninth month. +ABMON_10!LC_TIME!Abbreviated name of the tenth month. +ABMON_11!LC_TIME!Abbreviated name of the eleventh month. +ABMON_12!LC_TIME!Abbreviated name of the twelfth month. +ERA!LC_TIME!Era description segments. +ERA_D_FMT!LC_TIME!Era date format string. +ERA_D_T_FMT!LC_TIME!Era date and time format string. +ERA_T_FMT!LC_TIME!Era time format string. +ALT_DIGITS!LC_TIME!Alternative symbols for digits. +RADIXCHAR!LC_NUMERIC!Radix character. +THOUSEP!LC_NUMERIC!Separator for thousands. +YESEXPR!LC_MESSAGES!Affirmative response expression. +NOEXPR!LC_MESSAGES!Negative response expression. +CRNCYSTR!LC_MONETARY!T{ +Local currency symbol, preceded by +.BR '\(mi' +if the symbol should appear before the value, +.BR '+' +if the symbol should appear after the value, or +.BR '.' +if the symbol should replace the radix character. If the local +currency symbol is the empty string, implementations may return +the empty string (\c +.BR \(dq\&\(dq ). +T} +.TE +.P +If the locale's values for +.BR p_cs_precedes +and +.BR n_cs_precedes +do not match, the value of +.IR nl_langinfo (CRNCYSTR) +and +.IR nl_langinfo_l (CRNCYSTR,loc) +is unspecified. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +char *nl_langinfo(nl_item); +char *nl_langinfo_l(nl_item, locale_t); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Wherever possible, users are advised to use functions compatible with +those in the ISO\ C standard to access items of +.IR langinfo +data. In particular, the +\fIstrftime\fR() +function should be used to access date and time information defined in +category +.IR LC_TIME . +The +\fIlocaleconv\fR() +function should be used to access information corresponding to +RADIXCHAR, THOUSEP, and CRNCYSTR. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fInl_langinfo\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fIstrfmon\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/libgen.h.0p b/man-pages-posix-2013-a/man0p/libgen.h.0p new file mode 100644 index 0000000..43a020c --- /dev/null +++ b/man-pages-posix-2013-a/man0p/libgen.h.0p @@ -0,0 +1,57 @@ +'\" et +.TH libgen.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +libgen.h +\(em definitions for pattern matching functions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +char *basename(char *); +char *dirname(char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIbasename\fR\^(\|)", +.IR "\fIdirname\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/limits.h.0p b/man-pages-posix-2013-a/man0p/limits.h.0p new file mode 100644 index 0000000..6f126d5 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/limits.h.0p @@ -0,0 +1,1179 @@ +'\" et +.TH limits.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +limits.h +\(em implementation-defined constants +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +Many of the symbols listed here are not defined by the ISO/IEC\ 9899:\|1999 standard. Such symbols +are not shown as CX shaded, except under the heading ``Numerical Limits''. +.P +The +.IR +header shall define macros and symbolic constants for various limits. +Different categories of limits are described below, representing various +limits on resources that the implementation imposes on applications. +All macros and symbolic constants defined in this header shall be +suitable for use in +.BR #if +preprocessing directives. +.P +Implementations may choose any appropriate value for each limit, +provided it is not more restrictive than the Minimum Acceptable Values +listed below. Symbolic constant names beginning with _POSIX may be +found in +.IR . +.P +Applications should not assume any particular value for a limit. To +achieve maximum portability, an application should not require more +resource than the Minimum Acceptable Value quantity. However, an +application wishing to avail itself of the full amount of a resource +available on an implementation may make use of the value given in +.IR +on that particular implementation, by using the macros and symbolic +constants listed below. It should be noted, however, that many of the +listed limits are not invariant, and at runtime, the value of the limit +may differ from those given in this header, for the following reasons: +.IP " *" 4 +The limit is pathname-dependent. +.IP " *" 4 +The limit differs between the compile and runtime machines. +.P +For these reasons, an application may use the +\fIfpathconf\fR(), +\fIpathconf\fR(), +and +\fIsysconf\fR() +functions to determine the actual value of a limit at runtime. +.P +The items in the list ending in _MIN give the most negative values that +the mathematical types are guaranteed to be capable of representing. +Numbers of a more negative value may be supported on some +implementations, as indicated by the +.IR +header on the implementation, but applications requiring such numbers +are not guaranteed to be portable to all implementations. For positive +constants ending in _MIN, this indicates the minimum acceptable value. +.SS "Runtime Invariant Values (Possibly Indeterminate)" +.P +A definition of one of the symbolic constants in the following list +shall be omitted from +.IR +on specific implementations where the corresponding value is equal to +or greater than the stated minimum, but is unspecified. +.P +This indetermination might depend on the amount of available memory +space on a specific instance of a specific implementation. The actual +value supported by a specific instance shall be provided by the +\fIsysconf\fR() +function. +.IP {AIO_LISTIO_MAX} 6 +.br +Maximum number of I/O operations in a single list I/O call supported by +the implementation. +.br +Minimum Acceptable Value: +{_POSIX_AIO_LISTIO_MAX} +.IP {AIO_MAX} 6 +.br +Maximum number of outstanding asynchronous I/O operations supported by +the implementation. +.br +Minimum Acceptable Value: +{_POSIX_AIO_MAX} +.IP {AIO_PRIO_DELTA_MAX} 6 +.br +The maximum amount by which a process can decrease its asynchronous I/O +priority level from its own scheduling priority. +.br +Minimum Acceptable Value: 0 +.IP {ARG_MAX} 6 +.br +Maximum length of argument to the +.IR exec +functions including environment data. +.br +Minimum Acceptable Value: +{_POSIX_ARG_MAX} +.IP {ATEXIT_MAX} 6 +.br +Maximum number of functions that may be registered with +\fIatexit\fR(). +.br +Minimum Acceptable Value: 32 +.IP {CHILD_MAX} 6 +.br +Maximum number of simultaneous processes per real user ID. +.br +Minimum Acceptable Value: +{_POSIX_CHILD_MAX} +.IP {DELAYTIMER_MAX} 6 +.br +Maximum number of timer expiration overruns. +.br +Minimum Acceptable Value: +{_POSIX_DELAYTIMER_MAX} +.IP {HOST_NAME_MAX} 6 +.br +Maximum length of a host name (not including the terminating null) +as returned from the +\fIgethostname\fR() +function. +.br +Minimum Acceptable Value: +{_POSIX_HOST_NAME_MAX} +.IP {IOV_MAX} 6 +.br +Maximum number of +.BR iovec +structures that one process has available for use with +\fIreadv\fR() +or +\fIwritev\fR(). +.br +Minimum Acceptable Value: +{_XOPEN_IOV_MAX} +.IP {LOGIN_NAME_MAX} 6 +.br +Maximum length of a login name. +.br +Minimum Acceptable Value: +{_POSIX_LOGIN_NAME_MAX} +.IP {MQ_OPEN_MAX} 6 +.br +The maximum number of open message queue descriptors a process may +hold. +.br +Minimum Acceptable Value: +{_POSIX_MQ_OPEN_MAX} +.IP {MQ_PRIO_MAX} 6 +.br +The maximum number of message priorities supported by the implementation. +.br +Minimum Acceptable Value: +{_POSIX_MQ_PRIO_MAX} +.IP {OPEN_MAX} 6 +.br +A value one greater than the maximum value that the system may +assign to a newly-created file descriptor. +.br +Minimum Acceptable Value: +{_POSIX_OPEN_MAX} +.IP {PAGESIZE} 6 +.br +Size in bytes of a page. +.br +Minimum Acceptable Value: 1 +.IP {PAGE_SIZE} 6 +.br +Equivalent to +{PAGESIZE}. +If either +{PAGESIZE} +or +{PAGE_SIZE} +is defined, the other is defined with the same value. +.IP {PTHREAD_DESTRUCTOR_ITERATIONS} 6 +.br +Maximum number of attempts made to destroy a thread's thread-specific +data values on thread exit. +.br +Minimum Acceptable Value: +{_POSIX_THREAD_DESTRUCTOR_ITERATIONS} +.IP {PTHREAD_KEYS_MAX} 6 +.br +Maximum number of data keys that can be created by a process. +.br +Minimum Acceptable Value: +{_POSIX_THREAD_KEYS_MAX} +.IP {PTHREAD_STACK_MIN} 6 +.br +Minimum size in bytes of thread stack storage. +.br +Minimum Acceptable Value: 0 +.IP {PTHREAD_THREADS_MAX} 6 +.br +Maximum number of threads that can be created per process. +.br +Minimum Acceptable Value: +{_POSIX_THREAD_THREADS_MAX} +.IP {RE_DUP_MAX} 6 +.br +Maximum number of repeated occurrences of a BRE or ERE interval +expression; see +.IR "Section 9.3.6" ", " "BREs Matching Multiple Characters" +and +.IR "Section 9.4.6" ", " "EREs Matching Multiple Characters". +.br +Minimum Acceptable Value: +{_POSIX2_RE_DUP_MAX} +.IP {RTSIG_MAX} 6 +.br +Maximum number of realtime signals reserved for application use in this +implementation. +.br +Minimum Acceptable Value: +{_POSIX_RTSIG_MAX} +.IP {SEM_NSEMS_MAX} 6 +.br +Maximum number of semaphores that a process may have. +.br +Minimum Acceptable Value: +{_POSIX_SEM_NSEMS_MAX} +.IP {SEM_VALUE_MAX} 6 +.br +The maximum value a semaphore may have. +.br +Minimum Acceptable Value: +{_POSIX_SEM_VALUE_MAX} +.IP {SIGQUEUE_MAX} 6 +.br +Maximum number of queued signals that a process may send and have +pending at the receiver(s) at any time. +.br +Minimum Acceptable Value: +{_POSIX_SIGQUEUE_MAX} +.IP {SS_REPL_MAX} 6 +.br +The maximum number of replenishment operations that may be simultaneously +pending for a particular sporadic server scheduler. +.br +Minimum Acceptable Value: +{_POSIX_SS_REPL_MAX} +.IP {STREAM_MAX} 6 +.br +Maximum number of streams that one process can have open at one time. +If defined, it has the same value as +{FOPEN_MAX} +(see +.IR ). +.br +Minimum Acceptable Value: +{_POSIX_STREAM_MAX} +.IP {SYMLOOP_MAX} 6 +.br +Maximum number of symbolic links that can be reliably traversed in the +resolution of a pathname in the absence of a loop. +.br +Minimum Acceptable Value: +{_POSIX_SYMLOOP_MAX} +.IP {TIMER_MAX} 6 +.br +Maximum number of timers per process supported by the implementation. +.br +Minimum Acceptable Value: +{_POSIX_TIMER_MAX} +.IP {TRACE_EVENT_NAME_MAX} 6 +.br +Maximum length of the trace event name (not including the terminating null). +.br +Minimum Acceptable Value: +{_POSIX_TRACE_EVENT_NAME_MAX} +.IP {TRACE_NAME_MAX} 6 +.br +Maximum length of the trace generation version string or of the +trace stream name (not including the terminating null). +.br +Minimum Acceptable Value: +{_POSIX_TRACE_NAME_MAX} +.IP {TRACE_SYS_MAX} 6 +.br +Maximum number of trace streams that may simultaneously exist in +the system. +.br +Minimum Acceptable Value: +{_POSIX_TRACE_SYS_MAX} +.IP {TRACE_USER_EVENT_MAX} 6 +.br +Maximum number of user trace event type identifiers that may +simultaneously exist in a traced process, including the predefined +user trace event POSIX_TRACE_UNNAMED_USER_EVENT. +.br +Minimum Acceptable Value: +{_POSIX_TRACE_USER_EVENT_MAX} +.IP {TTY_NAME_MAX} 6 +.br +Maximum length of terminal device name. +.br +Minimum Acceptable Value: +{_POSIX_TTY_NAME_MAX} +.IP {TZNAME_MAX} 6 +.br +Maximum number of bytes supported for the name of a timezone (not of +the +.IR TZ +variable). +.br +Minimum Acceptable Value: +{_POSIX_TZNAME_MAX} +.TP 10 +.BR Note: +The length given by +{TZNAME_MAX} +does not include the quoting characters mentioned in +.IR "Section 8.3" ", " "Other Environment Variables". +.P +.SS "Pathname Variable Values" +.P +The values in the following list may be constants within an +implementation or may vary from one pathname to another. For example, +file systems or directories may have different characteristics. +.P +A definition of one of the symbolic constants in the following list +shall be omitted from the +.IR +header on specific implementations where the corresponding value is +equal to or greater than the stated minimum, but where the value can +vary depending on the file to which it is applied. The actual value +supported for a specific pathname shall be provided by the +\fIpathconf\fR() +function. +.IP {FILESIZEBITS} 6 +.br +Minimum number of bits needed to represent, as a signed integer value, +the maximum size of a regular file allowed in the specified directory. +.br +Minimum Acceptable Value: 32 +.IP {LINK_MAX} 6 +.br +Maximum number of links to a single file. +.br +Minimum Acceptable Value: +{_POSIX_LINK_MAX} +.IP {MAX_CANON} 6 +.br +Maximum number of bytes in a terminal canonical input line. +.br +Minimum Acceptable Value: +{_POSIX_MAX_CANON} +.IP {MAX_INPUT} 6 +.br +Minimum number of bytes for which space is available in a terminal +input queue; therefore, the maximum number of bytes a conforming +application may require to be typed as input before reading them. +.br +Minimum Acceptable Value: +{_POSIX_MAX_INPUT} +.IP {NAME_MAX} 6 +.br +Maximum number of bytes in a filename (not including the terminating +null of a filename string). +.br +Minimum Acceptable Value: +{_POSIX_NAME_MAX} +.br +Minimum Acceptable Value: +{_XOPEN_NAME_MAX} +.IP {PATH_MAX} 6 +.br +Maximum number of bytes the implementation will store as a pathname in +a user-supplied buffer of unspecified size, including the terminating +null character. Minimum number the implementation will accept as the +maximum number of bytes in a pathname. +.br +Minimum Acceptable Value: +{_POSIX_PATH_MAX} +.br +Minimum Acceptable Value: +{_XOPEN_PATH_MAX} +.IP {PIPE_BUF} 6 +.br +Maximum number of bytes that is guaranteed to be atomic when writing to +a pipe. +.br +Minimum Acceptable Value: +{_POSIX_PIPE_BUF} +.IP {POSIX_ALLOC_SIZE_MIN} 6 +.br +Minimum number of bytes of storage actually allocated for any portion +of a file. +.br +Minimum Acceptable Value: Not specified. +.IP {POSIX_REC_INCR_XFER_SIZE} 6 +.br +Recommended increment for file transfer sizes between the +{POSIX_REC_MIN_XFER_SIZE} +and +{POSIX_REC_MAX_XFER_SIZE} +values. +.br +Minimum Acceptable Value: Not specified. +.IP {POSIX_REC_MAX_XFER_SIZE} 6 +.br +Maximum recommended file transfer size. +.br +Minimum Acceptable Value: Not specified. +.IP {POSIX_REC_MIN_XFER_SIZE} 6 +.br +Minimum recommended file transfer size. +.br +Minimum Acceptable Value: Not specified. +.IP {POSIX_REC_XFER_ALIGN} 6 +.br +Recommended file transfer buffer alignment. +.br +Minimum Acceptable Value: Not specified. +.IP {SYMLINK_MAX} 6 +.br +Maximum number of bytes in a symbolic link. +.br +Minimum Acceptable Value: +{_POSIX_SYMLINK_MAX} +.SS "Runtime Increasable Values" +.P +The magnitude limitations in the following list shall be fixed by +specific implementations. An application should assume that the value +of the symbolic constant defined by +.IR +in a specific implementation is the minimum that pertains whenever the +application is run under that implementation. A specific instance of a +specific implementation may increase the value relative to that +supplied by +.IR +for that implementation. The actual value supported by a specific +instance shall be provided by the +\fIsysconf\fR() +function. +.IP {BC_BASE_MAX} 6 +.br +Maximum +.IR obase +values allowed by the +.IR bc +utility. +.br +Minimum Acceptable Value: +{_POSIX2_BC_BASE_MAX} +.IP {BC_DIM_MAX} 6 +.br +Maximum number of elements permitted in an array by the +.IR bc +utility. +.br +Minimum Acceptable Value: +{_POSIX2_BC_DIM_MAX} +.IP {BC_SCALE_MAX} 6 +.br +Maximum +.IR scale +value allowed by the +.IR bc +utility. +.br +Minimum Acceptable Value: +{_POSIX2_BC_SCALE_MAX} +.IP {BC_STRING_MAX} 6 +.br +Maximum length of a string constant accepted by the +.IR bc +utility. +.br +Minimum Acceptable Value: +{_POSIX2_BC_STRING_MAX} +.IP {CHARCLASS_NAME_MAX} 6 +.br +Maximum number of bytes in a character class name. +.br +Minimum Acceptable Value: +{_POSIX2_CHARCLASS_NAME_MAX} +.IP {COLL_WEIGHTS_MAX} 6 +.br +Maximum number of weights that can be assigned to an entry of the +.IR LC_COLLATE +.BR order +keyword in the locale definition file; see +.IR "Chapter 7" ", " "Locale". +.br +Minimum Acceptable Value: +{_POSIX2_COLL_WEIGHTS_MAX} +.IP {EXPR_NEST_MAX} 6 +.br +Maximum number of expressions that can be nested within parentheses by +the +.IR expr +utility. +.br +Minimum Acceptable Value: +{_POSIX2_EXPR_NEST_MAX} +.IP {LINE_MAX} 6 +.br +Unless otherwise noted, the maximum length, in bytes, of a utility's +input line (either standard input or another file), when the utility is +described as processing text files. The length includes room for the +trailing +. +.br +Minimum Acceptable Value: +{_POSIX2_LINE_MAX} +.IP {NGROUPS_MAX} 6 +.br +Maximum number of simultaneous supplementary group IDs per process. +.br +Minimum Acceptable Value: +{_POSIX_NGROUPS_MAX} +.IP {RE_DUP_MAX} 6 +.br +Maximum number of repeated occurrences of a regular expression +permitted when using the interval notation \e{\fIm\fP,\fIn\fP\e}; see +.IR "Chapter 9" ", " "Regular Expressions". +.br +Minimum Acceptable Value: +{_POSIX2_RE_DUP_MAX} +.SS "Maximum Values" +.P +The +.IR +header shall define the following symbolic constants with the values +shown. These are the most restrictive values for certain features on +an implementation. A conforming implementation shall provide values no +larger than these values. A conforming application must not require a +smaller value for correct operation. +.IP {_POSIX_CLOCKRES_MIN} 6 +.br +The resolution of the CLOCK_REALTIME clock, in nanoseconds. +.br +Value: 20 000 000 +.RS 6 +.P +If the Monotonic Clock option is supported, the resolution of the +CLOCK_MONOTONIC clock, in nanoseconds, is represented by +{_POSIX_CLOCKRES_MIN}. +.RE +.SS "Minimum Values" +.P +The +.IR +header shall define the following symbolic constants with the values +shown. These are the most restrictive values for certain features on +an implementation conforming to this volume of POSIX.1\(hy2008. Related symbolic constants are +defined elsewhere in this volume of POSIX.1\(hy2008 which reflect the actual implementation and +which need not be as restrictive. For each of these limits, a conforming +implementation shall provide a value at least this large or shall have +no limit. A strictly conforming application must not require a larger +value for correct operation. +.IP {_POSIX_AIO_LISTIO_MAX} 6 +.br +The number of I/O operations that can be specified in a list I/O call. +.br +Value: 2 +.IP {_POSIX_AIO_MAX} 6 +.br +The number of outstanding asynchronous I/O operations. +.br +Value: 1 +.IP {_POSIX_ARG_MAX} 6 +.br +Maximum length of argument to the +.IR exec +functions including environment data. +.br +Value: 4 096 +.IP {_POSIX_CHILD_MAX} 6 +.br +Maximum number of simultaneous processes per real user ID. +.br +Value: 25 +.IP {_POSIX_DELAYTIMER_MAX} 6 +.br +The number of timer expiration overruns. +.br +Value: 32 +.IP {_POSIX_HOST_NAME_MAX} 6 +.br +Maximum length of a host name (not including the terminating null) +as returned from the +\fIgethostname\fR() +function. +.br +Value: 255 +.IP {_POSIX_LINK_MAX} 6 +.br +Maximum number of links to a single file. +.br +Value: 8 +.IP {_POSIX_LOGIN_NAME_MAX} 6 +.br +The size of the storage required for a login name, in bytes +(including the terminating null). +.br +Value: 9 +.IP {_POSIX_MAX_CANON} 6 +.br +Maximum number of bytes in a terminal canonical input queue. +.br +Value: 255 +.IP {_POSIX_MAX_INPUT} 6 +.br +Maximum number of bytes allowed in a terminal input queue. +.br +Value: 255 +.IP {_POSIX_MQ_OPEN_MAX} 6 +.br +The number of message queues that can be open for a single process. +.br +Value: 8 +.IP {_POSIX_MQ_PRIO_MAX} 6 +.br +The maximum number of message priorities supported by the implementation. +.br +Value: 32 +.IP {_POSIX_NAME_MAX} 6 +.br +Maximum number of bytes in a filename (not including the terminating +null of a filename string). +.br +Value: 14 +.IP {_POSIX_NGROUPS_MAX} 6 +.br +Maximum number of simultaneous supplementary group IDs per process. +.br +Value: 8 +.IP {_POSIX_OPEN_MAX} 6 +.br +A value one greater than the maximum value that the system may assign +to a newly-created file descriptor. +.br +Value: 20 +.IP {_POSIX_PATH_MAX} 6 +.br +Minimum number the implementation will accept as the maximum number of +bytes in a pathname. +.br +Value: 256 +.IP {_POSIX_PIPE_BUF} 6 +.br +Maximum number of bytes that is guaranteed to be atomic when writing to +a pipe. +.br +Value: 512 +.IP {_POSIX_RE_DUP_MAX} 6 +.br +The number of repeated occurrences of a BRE permitted by the +\fIregexec\fR() +and +\fIregcomp\fR() +functions when using the interval notation {\e(\fIm\fR,\fIn\fR\e}; see +.IR "Section 9.3.6" ", " "BREs Matching Multiple Characters". +.br +Value: 255 +.IP {_POSIX_RTSIG_MAX} 6 +.br +The number of realtime signal numbers reserved for application use. +.br +Value: 8 +.IP {_POSIX_SEM_NSEMS_MAX} 6 +.br +The number of semaphores that a process may have. +.br +Value: 256 +.IP {_POSIX_SEM_VALUE_MAX} 6 +.br +The maximum value a semaphore may have. +.br +Value: 32 767 +.IP {_POSIX_SIGQUEUE_MAX} 6 +.br +The number of queued signals that a process may send and have pending +at the receiver(s) at any time. +.br +Value: 32 +.IP {_POSIX_SSIZE_MAX} 6 +.br +The value that can be stored in an object of type +.BR ssize_t . +.br +Value: 32 767 +.IP {_POSIX_SS_REPL_MAX} 6 +.br +The number of replenishment operations that may be simultaneously +pending for a particular sporadic server scheduler. +.br +Value: 4 +.IP {_POSIX_STREAM_MAX} 6 +.br +The number of streams that one process can have open at one time. +.br +Value: 8 +.IP {_POSIX_SYMLINK_MAX} 6 +.br +The number of bytes in a symbolic link. +.br +Value: 255 +.IP {_POSIX_SYMLOOP_MAX} 6 +.br +The number of symbolic links that can be traversed in the resolution of +a pathname in the absence of a loop. +.br +Value: 8 +.IP {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} 6 +.br +The number of attempts made to destroy a thread's thread-specific data +values on thread exit. +.br +Value: 4 +.IP {_POSIX_THREAD_KEYS_MAX} 6 +.br +The number of data keys per process. +.br +Value: 128 +.IP {_POSIX_THREAD_THREADS_MAX} 6 +.br +The number of threads per process. +.br +Value: 64 +.IP {_POSIX_TIMER_MAX} 6 +.br +The per-process number of timers. +.br +Value: 32 +.IP {_POSIX_TRACE_EVENT_NAME_MAX} 6 +.br +The length in bytes of a trace event name (not including the terminating null). +.br +Value: 30 +.IP {_POSIX_TRACE_NAME_MAX} 6 +.br +The length in bytes of a trace generation version string or a trace +stream name (not including the terminating null). +.br +Value: 8 +.IP {_POSIX_TRACE_SYS_MAX} 6 +.br +The number of trace streams that may simultaneously exist in the system. +.br +Value: 8 +.IP {_POSIX_TRACE_USER_EVENT_MAX} 6 +.br +The number of user trace event type identifiers that may simultaneously +exist in a traced process, including the predefined user trace event +POSIX_TRACE_UNNAMED_USER_EVENT. +.br +Value: 32 +.IP {_POSIX_TTY_NAME_MAX} 6 +.br +The size of the storage required for a terminal device name, in bytes +(including the terminating null). +.br +Value: 9 +.IP {_POSIX_TZNAME_MAX} 6 +.br +Maximum number of bytes supported for the name of a timezone (not of +the +.IR TZ +variable). +.br +Value: 6 +.RS 6 +.TP 10 +.BR Note: +The length given by +{_POSIX_TZNAME_MAX} +does not include the quoting characters mentioned in +.IR "Section 8.3" ", " "Other Environment Variables". +.P +.RE +.IP {_POSIX2_BC_BASE_MAX} 6 +.br +Maximum +.IR obase +values allowed by the +.IR bc +utility. +.br +Value: 99 +.IP {_POSIX2_BC_DIM_MAX} 6 +.br +Maximum number of elements permitted in an array by the +.IR bc +utility. +.br +Value: 2 048 +.IP {_POSIX2_BC_SCALE_MAX} 6 +.br +Maximum +.IR scale +value allowed by the +.IR bc +utility. +.br +Value: 99 +.IP {_POSIX2_BC_STRING_MAX} 6 +.br +Maximum length of a string constant accepted by the +.IR bc +utility. +.br +Value: 1 000 +.IP {_POSIX2_CHARCLASS_NAME_MAX} 6 +.br +Maximum number of bytes in a character class name. +.br +Value: 14 +.IP {_POSIX2_COLL_WEIGHTS_MAX} 6 +.br +Maximum number of weights that can be assigned to an entry of the +.IR LC_COLLATE +.BR order +keyword in the locale definition file; see +.IR "Chapter 7" ", " "Locale". +.br +Value: 2 +.IP {_POSIX2_EXPR_NEST_MAX} 6 +.br +Maximum number of expressions that can be nested within parentheses by +the +.IR expr +utility. +.br +Value: 32 +.IP {_POSIX2_LINE_MAX} 6 +.br +Unless otherwise noted, the maximum length, in bytes, of a utility's +input line (either standard input or another file), when the utility is +described as processing text files. The length includes room for the +trailing +. +.br +Value: 2 048 +.IP {_POSIX2_RE_DUP_MAX} 6 +.br +Maximum number of repeated occurrences of a regular expression +permitted when using the interval notation \e{\fIm\fP,\fIn\fP\e}; see +.IR "Chapter 9" ", " "Regular Expressions". +.br +Value: 255 +.IP {_XOPEN_IOV_MAX} 6 +.br +Maximum number of +.BR iovec +structures that one process has available for use with +\fIreadv\fR() +or +\fIwritev\fR(). +.br +Value: 16 +.IP {_XOPEN_NAME_MAX} 6 +.br +Maximum number of bytes in a filename (not including the terminating +null of a filename string). +.br +Value: 255 +.IP {_XOPEN_PATH_MAX} 6 +.br +Minimum number the implementation will accept as the maximum number of +bytes in a pathname. +.br +Value: 1\|024 +.SS "Numerical Limits" +.P +The +.IR +header shall define the following macros and, except for +{CHAR_BIT}, +{LONG_BIT}, +{MB_LEN_MAX}, +and +{WORD_BIT}, +they shall be replaced by expressions that have the same type as +would an expression that is an object of the corresponding type +converted according to the integer promotions. +.P +If the value of an object of type +.BR char +is treated as a signed integer when used in an expression, the value of +{CHAR_MIN} +is the same as that of +{SCHAR_MIN} +and the value of +{CHAR_MAX} +is the same as that of +{SCHAR_MAX}. +Otherwise, the value of +{CHAR_MIN} +is 0 and the value of +{CHAR_MAX} +is the same as that of +{UCHAR_MAX}. +.IP {CHAR_BIT} 6 +.br +Number of bits in a type +.BR char . +.br +Value: 8 +.IP {CHAR_MAX} 6 +.br +Maximum value for an object of type +.BR char . +.br +Value: +{UCHAR_MAX} +or +{SCHAR_MAX} +.IP {CHAR_MIN} 6 +.br +Minimum value for an object of type +.BR char . +.br +Value: +{SCHAR_MIN} +or 0 +.IP {INT_MAX} 6 +.br +Maximum value for an object of type +.BR int . +.br +Minimum Acceptable Value: 2 147 483 647 +.IP {INT_MIN} 6 +.br +Minimum value for an object of type +.BR int . +.br +Maximum Acceptable Value: \(mi2 147 483 647 +.IP {LLONG_MAX} 6 +.br +Maximum value for an object of type +.BR "long long" . +.br +Minimum Acceptable Value: +9\|223\|372\|036\|854\|775\|807 +.IP {LLONG_MIN} 6 +.br +Minimum value for an object of type +.BR "long long" . +.br +Maximum Acceptable Value: \(mi9\|223\|372\|036\|854\|775\|807 +.IP {LONG_BIT} 6 +.br +Number of bits in an object of type +.BR long . +.br +Minimum Acceptable Value: 32 +.IP {LONG_MAX} 6 +.br +Maximum value for an object of type +.BR long . +.br +Minimum Acceptable Value: +2 147 483 647 +.IP {LONG_MIN} 6 +.br +Minimum value for an object of type +.BR long . +.br +Maximum Acceptable Value: \(mi2 147 483 647 +.IP {MB_LEN_MAX} 6 +.br +Maximum number of bytes in a character, for any supported locale. +.br +Minimum Acceptable Value: 1 +.IP {SCHAR_MAX} 6 +.br +Maximum value for an object of type +.BR "signed char" . +.br +Value: +127 +.IP {SCHAR_MIN} 6 +.br +Minimum value for an object of type +.BR "signed char" . +.br +Value: \(mi128 +.IP {SHRT_MAX} 6 +.br +Maximum value for an object of type +.BR short . +.br +Minimum Acceptable Value: +32 767 +.IP {SHRT_MIN} 6 +.br +Minimum value for an object of type +.BR short . +.br +Maximum Acceptable Value: \(mi32 767 +.IP {SSIZE_MAX} 6 +.br +Maximum value for an object of type +.BR ssize_t . +.br +Minimum Acceptable Value: +{_POSIX_SSIZE_MAX} +.IP {UCHAR_MAX} 6 +.br +Maximum value for an object of type +.BR "unsigned char" . +.br +Value: 255 +.IP {UINT_MAX} 6 +.br +Maximum value for an object of type +.BR unsigned . +.br +Minimum Acceptable Value: 4 294 967 295 +.IP {ULLONG_MAX} 6 +.br +Maximum value for an object of type +.BR "unsigned long long" . +.br +Minimum Acceptable Value: 18\|446\|744\|073\|709\|551\|615 +.IP {ULONG_MAX} 6 +.br +Maximum value for an object of type +.BR "unsigned long" . +.br +Minimum Acceptable Value: 4 294 967 295 +.IP {USHRT_MAX} 6 +.br +Maximum value for an object of type +.BR "unsigned short" . +.br +Minimum Acceptable Value: 65 535 +.IP {WORD_BIT} 6 +.br +Number of bits in an object of type +.BR int . +.br +Minimum Acceptable Value: 32 +.SS "Other Invariant Values" +.P +The +.IR +header shall define the following symbolic constants: +.IP {NL_ARGMAX} 6 +.br +Maximum value of +.IR n +in conversion specifications using the \fR"%\fIn\fR$"\fR +sequence in calls to the +\fIprintf\fR() +and +\fIscanf\fR() +families of functions. +.br +Minimum Acceptable Value: 9 +.IP {NL_LANGMAX} 6 +.br +Maximum number of bytes in a +.IR LANG +name. +.br +Minimum Acceptable Value: 14 +.IP {NL_MSGMAX} 6 +.br +Maximum message number. +.br +Minimum Acceptable Value: 32 767 +.IP {NL_SETMAX} 6 +.br +Maximum set number. +.br +Minimum Acceptable Value: 255 +.IP {NL_TEXTMAX} 6 +.br +Maximum number of bytes in a message string. +.br +Minimum Acceptable Value: +{_POSIX2_LINE_MAX} +.IP {NZERO} 6 +.br +Default process priority. +.br +Minimum Acceptable Value: 20 +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +A request was made to reduce the value of +{_POSIX_LINK_MAX} +from the value of 8 specified for it in the POSIX.1\(hy1990 standard to 2. The +standard developers decided to deny this request for several reasons: +.IP " *" 4 +They wanted to avoid making any changes to the standard that could +break conforming applications, and the requested change could have that +effect. +.IP " *" 4 +The use of multiple hard links to a file cannot always be replaced with +use of symbolic links. Symbolic links are semantically different from +hard links in that they associate a pathname with another pathname +rather than a pathname with a file. This has implications for access +control, file permanence, and transparency. +.IP " *" 4 +The original standard developers had considered the issue of allowing +for implementations that did not in general support hard links, and +decided that this would reduce consensus on the standard. +.P +Systems that support historical versions of the development option of +the ISO\ POSIX\(hy2 standard retain the name +{_POSIX2_RE_DUP_MAX} +as an alias for +{_POSIX_RE_DUP_MAX}. +.IP {PATH_MAX} 6 +.br +IEEE PASC Interpretation 1003.1 #15 addressed the inconsistency in the +standard with the definition of pathname and the description of +{PATH_MAX}, +allowing application developers to allocate either +{PATH_MAX} +or +{PATH_MAX}+1 +bytes. The inconsistency has been removed by correction to the +{PATH_MAX} +definition to include the null character. With this change, +applications that previously allocated +{PATH_MAX} +bytes will continue to succeed. +.IP {SYMLINK_MAX} 6 +.br +This symbol refers to space for data that is stored in the file system, +as opposed to +{PATH_MAX} +which is the length of a name that can be passed to a function. In some +existing implementations, the pathnames pointed to by symbolic links +are stored in the +.IR inode s +of the links, so it is important that +{SYMLINK_MAX} +not be constrained to be as large as +{PATH_MAX}. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/locale.h.0p b/man-pages-posix-2013-a/man0p/locale.h.0p new file mode 100644 index 0000000..202a878 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/locale.h.0p @@ -0,0 +1,177 @@ +'\" et +.TH locale.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +locale.h +\(em category macros +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the +.BR lconv +structure, which shall include at least the following members. +(See the definitions of +.IR LC_MONETARY +in +.IR "Section 7.3.3" ", " "LC_MONETARY" +and +.IR "Section 7.3.4" ", " "LC_NUMERIC".) +.sp +.RS 4 +.nf +\fB +char *currency_symbol +char *decimal_point +char frac_digits +char *grouping +char *int_curr_symbol +char int_frac_digits +char int_n_cs_precedes +char int_n_sep_by_space +char int_n_sign_posn +char int_p_cs_precedes +char int_p_sep_by_space +char int_p_sign_posn +char *mon_decimal_point +char *mon_grouping +char *mon_thousands_sep +char *negative_sign +char n_cs_precedes +char n_sep_by_space +char n_sign_posn +char *positive_sign +char p_cs_precedes +char p_sep_by_space +char p_sign_posn +char *thousands_sep +.fi \fR +.P +.RE +.P +The +.IR +header shall define NULL (as described in +.IR ) +and at least the following as macros: +.P +.nf +LC_ALL +LC_COLLATE +LC_CTYPE +LC_MESSAGES +LC_MONETARY +LC_NUMERIC +LC_TIME +.fi +.P +which shall expand to integer constant expressions with distinct +values for use as the first argument to the +\fIsetlocale\fR() +function. +.P +Implementations may add additional masks using the form +.IR LC_* +and an uppercase letter. +.P +The +.IR +header shall contain at least the following macros representing +bitmasks for use with the +\fInewlocale\fR() +function for each supported locale category: +LC_COLLATE_MASK +LC_CTYPE_MASK +LC_MESSAGES_MASK +LC_MONETARY_MASK +LC_NUMERIC_MASK +LC_TIME_MASK +.P +Implementations may add additional masks using the form LC_*_MASK. +.P +In addition, a macro to set the bits for all categories set shall be +defined: +LC_ALL_MASK +.P +The +.IR +header shall define LC_GLOBAL_LOCALE, a special locale object descriptor +used by the +\fIduplocale\fR() +and +\fIuselocale\fR() +functions. +.P +The +.IR +header shall define the +.BR locale_t +type, representing a locale object. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +locale_t duplocale(locale_t); +void freelocale(locale_t); +struct lconv *localeconv(void); +locale_t newlocale(int, const char *, locale_t); +char *setlocale(int, const char *); +locale_t uselocale (locale_t); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIduplocale\fR\^(\|)", +.IR "\fIfreelocale\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/math.h.0p b/man-pages-posix-2013-a/man0p/math.h.0p new file mode 100644 index 0000000..c8cf2cd --- /dev/null +++ b/man-pages-posix-2013-a/man0p/math.h.0p @@ -0,0 +1,582 @@ +'\" et +.TH math.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.EQ +delim $$ +.EN +.SH NAME +math.h +\(em mathematical declarations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define at least the following types: +.IP "\fBfloat_t\fR" 12 +A real-floating type at least as wide as +.BR float . +.IP "\fBdouble_t\fR" 12 +A real-floating type at least as wide as +.BR double , +and at least as wide as +.BR float_t . +.P +If FLT_EVAL_METHOD equals 0, +.BR float_t +and +.BR double_t +shall be +.BR float +and +.BR double , +respectively; if FLT_EVAL_METHOD equals 1, they shall both be +.BR double ; +if FLT_EVAL_METHOD equals 2, they shall both be +.BR "long double" ; +for other values of FLT_EVAL_METHOD, they are otherwise +implementation-defined. +.P +The +.IR +header shall define the following macros, where real-floating indicates +that the argument shall be an expression of real-floating type: +.sp +.RS 4 +.nf +\fB +int fpclassify(real-floating x); +int isfinite(real-floating x); +int isgreater(real-floating x, real-floating y); +int isgreaterequal(real-floating x, real-floating y); +int isinf(real-floating x); +int isless(real-floating x, real-floating y); +int islessequal(real-floating x, real-floating y); +int islessgreater(real-floating x, real-floating y); +int isnan(real-floating x); +int isnormal(real-floating x); +int isunordered(real-floating x, real-floating y); +int signbit(real-floating x); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants. The values +shall have type +.BR double +and shall be accurate within the precision of the +.BR double +type. +.IP M_E 12 +Value of $e$ +.IP M_LOG2E 12 +Value of $log_ 2" " e$ +.IP M_LOG10E 12 +Value of $log_ 10" " e$ +.IP M_LN2 12 +Value of $log_ e" " 2$ +.IP M_LN10 12 +Value of $log_ e" " 10$ +.IP M_PI 12 +Value of $pi$ +.IP M_PI_2 12 +Value of $pi /2$ +.IP M_PI_4 12 +Value of $pi /4$ +.IP M_1_PI 12 +Value of $1/ pi$ +.IP M_2_PI 12 +Value of $2/ pi$ +.IP M_2_SQRTPI 12 +Value of $2/ sqrt pi$ +.IP M_SQRT2 12 +Value of $sqrt 2$ +.IP M_SQRT1_2 12 +Value of $1/ sqrt 2$ +.P +The +.IR +header shall define the following symbolic constant: +.IP MAXFLOAT 12 +Same value as FLT_MAX in +.IR . +.P +The +.IR +header shall define the following macros: +.IP HUGE_VAL 12 +A positive +.BR double +constant expression, not necessarily representable as a +.BR float . +Used as an error value returned by the mathematics library. HUGE_VAL +evaluates to +infinity on systems supporting IEEE\ Std\ 754\(hy1985. +.IP HUGE_VALF 12 +A positive +.BR float +constant expression. Used as an error value returned by the mathematics +library. HUGE_VALF evaluates to +infinity on systems supporting IEEE\ Std\ 754\(hy1985. +.IP HUGE_VALL 12 +A positive +.BR "long double" +constant expression. Used as an error value returned by the mathematics +library. HUGE_VALL evaluates to +infinity on systems supporting IEEE\ Std\ 754\(hy1985. +.IP INFINITY 12 +A constant expression of type +.BR float +representing positive or unsigned infinity, if available; else a +positive constant of type +.BR float +that overflows at translation time. +.IP NAN 12 +A constant expression of type +.BR float +representing a quiet NaN. This macro is only defined if the +implementation supports quiet NaNs for the +.BR float +type. +.P +The following macros shall be defined for number classification. They +represent the mutually-exclusive kinds of floating-point values. They +expand to integer constant expressions with distinct values. Additional +implementation-defined floating-point classifications, with macro +definitions beginning with FP_ and an uppercase letter, may also be +specified by the implementation. +.sp +.RS +FP_INFINITE +FP_NAN +FP_NORMAL +FP_SUBNORMAL +FP_ZERO +.RE +.P +The following optional macros indicate whether the +\fIfma\fR() +family of functions are fast compared with direct code: +.sp +.RS +FP_FAST_FMA +FP_FAST_FMAF +FP_FAST_FMAL +.RE +.P +If defined, the FP_FAST_FMA macro shall expand to the integer constant +1 and shall indicate that the +\fIfma\fR() +function generally executes about as fast as, or faster than, a +multiply and an add of +.BR double +operands. If undefined, the speed of execution is unspecified. The +other macros have the equivalent meaning for the +.BR float +and +.BR "long double" +versions. +.P +The following macros shall expand to integer constant expressions whose +values are returned by +.IR ilogb (\c +.IR x ) +if +.IR x +is zero or NaN, respectively. The value of FP_ILOGB0 shall be either +{INT_MIN} +or \(mi\c +{INT_MAX}. +The value of FP_ILOGBNAN shall be either +{INT_MAX} +or +{INT_MIN}. +.sp +.RS +FP_ILOGB0 +FP_ILOGBNAN +.RE +.P +The following macros shall expand to the integer constants 1 and 2, +respectively; +.sp +.RS +MATH_ERRNO +MATH_ERREXCEPT +.RE +.P +The following macro shall expand to an expression that has type +.BR int +and the value MATH_ERRNO, MATH_ERREXCEPT, or the bitwise-inclusive OR +of both: +.sp +.RS +math_errhandling +.RE +.P +The value of math_errhandling is constant for the duration of the +program. It is unspecified whether math_errhandling is a macro or an +identifier with external linkage. If a macro definition is suppressed +or a program defines an identifier with the name math_errhandling , the +behavior is undefined. If the expression (math_errhandling & +MATH_ERREXCEPT) can be non-zero, the implementation shall define the +macros FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +double acos(double); +float acosf(float); +double acosh(double); +float acoshf(float); +long double acoshl(long double); +long double acosl(long double); +double asin(double); +float asinf(float); +double asinh(double); +float asinhf(float); +long double asinhl(long double); +long double asinl(long double); +double atan(double); +double atan2(double, double); +float atan2f(float, float); +long double atan2l(long double, long double); +float atanf(float); +double atanh(double); +float atanhf(float); +long double atanhl(long double); +long double atanl(long double); +double cbrt(double); +float cbrtf(float); +long double cbrtl(long double); +double ceil(double); +float ceilf(float); +long double ceill(long double); +double copysign(double, double); +float copysignf(float, float); +long double copysignl(long double, long double); +double cos(double); +float cosf(float); +double cosh(double); +float coshf(float); +long double coshl(long double); +long double cosl(long double); +double erf(double); +double erfc(double); +float erfcf(float); +long double erfcl(long double); +float erff(float); +long double erfl(long double); +double exp(double); +double exp2(double); +float exp2f(float); +long double exp2l(long double); +float expf(float); +long double expl(long double); +double expm1(double); +float expm1f(float); +long double expm1l(long double); +double fabs(double); +float fabsf(float); +long double fabsl(long double); +double fdim(double, double); +float fdimf(float, float); +long double fdiml(long double, long double); +double floor(double); +float floorf(float); +long double floorl(long double); +double fma(double, double, double); +float fmaf(float, float, float); +long double fmal(long double, long double, long double); +double fmax(double, double); +float fmaxf(float, float); +long double fmaxl(long double, long double); +double fmin(double, double); +float fminf(float, float); +long double fminl(long double, long double); +double fmod(double, double); +float fmodf(float, float); +long double fmodl(long double, long double); +double frexp(double, int *); +float frexpf(float, int *); +long double frexpl(long double, int *); +double hypot(double, double); +float hypotf(float, float); +long double hypotl(long double, long double); +int ilogb(double); +int ilogbf(float); +int ilogbl(long double); +double j0(double); +double j1(double); +double jn(int, double); +double ldexp(double, int); +float ldexpf(float, int); +long double ldexpl(long double, int); +double lgamma(double); +float lgammaf(float); +long double lgammal(long double); +long long llrint(double); +long long llrintf(float); +long long llrintl(long double); +long long llround(double); +long long llroundf(float); +long long llroundl(long double); +double log(double); +double log10(double); +float log10f(float); +long double log10l(long double); +double log1p(double); +float log1pf(float); +long double log1pl(long double); +double log2(double); +float log2f(float); +long double log2l(long double); +double logb(double); +float logbf(float); +long double logbl(long double); +float logf(float); +long double logl(long double); +long lrint(double); +long lrintf(float); +long lrintl(long double); +long lround(double); +long lroundf(float); +long lroundl(long double); +double modf(double, double *); +float modff(float, float *); +long double modfl(long double, long double *); +double nan(const char *); +float nanf(const char *); +long double nanl(const char *); +double nearbyint(double); +float nearbyintf(float); +long double nearbyintl(long double); +double nextafter(double, double); +float nextafterf(float, float); +long double nextafterl(long double, long double); +double nexttoward(double, long double); +float nexttowardf(float, long double); +long double nexttowardl(long double, long double); +double pow(double, double); +float powf(float, float); +long double powl(long double, long double); +double remainder(double, double); +float remainderf(float, float); +long double remainderl(long double, long double); +double remquo(double, double, int *); +float remquof(float, float, int *); +long double remquol(long double, long double, int *); +double rint(double); +float rintf(float); +long double rintl(long double); +double round(double); +float roundf(float); +long double roundl(long double); +double scalbln(double, long); +float scalblnf(float, long); +long double scalblnl(long double, long); +double scalbn(double, int); +float scalbnf(float, int); +long double scalbnl(long double, int); +double sin(double); +float sinf(float); +double sinh(double); +float sinhf(float); +long double sinhl(long double); +long double sinl(long double); +double sqrt(double); +float sqrtf(float); +long double sqrtl(long double); +double tan(double); +float tanf(float); +double tanh(double); +float tanhf(float); +long double tanhl(long double); +long double tanl(long double); +double tgamma(double); +float tgammaf(float); +long double tgammal(long double); +double trunc(double); +float truncf(float); +long double truncl(long double); +double y0(double); +double y1(double); +double yn(int, double); +.fi \fR +.P +.RE +.P +The following external variable shall be defined: +.sp +.RS 4 +.nf +\fB +extern int signgam; +.fi \fR +.P +.RE +.P +The behavior of each of the functions defined in +.IR +is specified in the System Interfaces volume of POSIX.1\(hy2008 for all representable values of its input +arguments, except where stated otherwise. Each function shall execute +as if it were a single operation without generating any externally +visible exceptional conditions. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The FP_CONTRACT pragma can be used to allow (if the state is on) or +disallow (if the state is off) the implementation to contract +expressions. Each pragma can occur either outside external declarations +or preceding all explicit declarations and statements inside a compound +statement. When outside external declarations, the pragma takes effect +from its occurrence until another FP_CONTRACT pragma is encountered, or +until the end of the translation unit. When inside a compound +statement, the pragma takes effect from its occurrence until another +FP_CONTRACT pragma is encountered (including within a nested compound +statement), or until the end of the compound statement; at the end of a +compound statement the state for the pragma is restored to its +condition just before the compound statement. If this pragma is used in +any other context, the behavior is undefined. The default state (on or +off) for the pragma is implementation-defined. +.P +Applications should use FLT_MAX as described in the +.IR +header instead of the obsolescent MAXFLOAT. +.SH RATIONALE +Before the ISO/IEC\ 9899:\|1999 standard, the math library was defined only for the floating +type +.BR double . +All the names formed by appending +.BR 'f' +or +.BR 'l' +to a name in +.IR +were reserved to allow for the definition of +.BR float +and +.BR "long double" +libraries; and the ISO/IEC\ 9899:\|1999 standard provides for all three versions of math +functions. +.P +The functions +.IR ecvt (\|), +.IR fcvt (\|), +and +.IR gcvt (\|) +have been dropped from the ISO\ C standard since their capability is available +through +\fIsprintf\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIacos\fR\^(\|)", +.IR "\fIacosh\fR\^(\|)", +.IR "\fIasin\fR\^(\|)", +.IR "\fIasinh\fR\^(\|)", +.IR "\fIatan\fR\^(\|)", +.IR "\fIatan2\fR\^(\|)", +.IR "\fIatanh\fR\^(\|)", +.IR "\fIcbrt\fR\^(\|)", +.IR "\fIceil\fR\^(\|)", +.IR "\fIcopysign\fR\^(\|)", +.IR "\fIcos\fR\^(\|)", +.IR "\fIcosh\fR\^(\|)", +.IR "\fIerf\fR\^(\|)", +.IR "\fIerfc\fR\^(\|)", +.IR "\fIexp\fR\^(\|)", +.IR "\fIexp2\fR\^(\|)", +.IR "\fIexpm1\fR\^(\|)", +.IR "\fIfabs\fR\^(\|)", +.IR "\fIfdim\fR\^(\|)", +.IR "\fIfloor\fR\^(\|)", +.IR "\fIfma\fR\^(\|)", +.IR "\fIfmax\fR\^(\|)", +.IR "\fIfmin\fR\^(\|)", +.IR "\fIfmod\fR\^(\|)", +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIfrexp\fR\^(\|)", +.IR "\fIhypot\fR\^(\|)", +.IR "\fIilogb\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)", +.IR "\fIj0\fR\^(\|)", +.IR "\fIldexp\fR\^(\|)", +.IR "\fIlgamma\fR\^(\|)", +.IR "\fIllrint\fR\^(\|)", +.IR "\fIllround\fR\^(\|)", +.IR "\fIlog\fR\^(\|)", +.IR "\fIlog10\fR\^(\|)", +.IR "\fIlog1p\fR\^(\|)", +.IR "\fIlog2\fR\^(\|)", +.IR "\fIlogb\fR\^(\|)", +.IR "\fIlrint\fR\^(\|)", +.IR "\fIlround\fR\^(\|)", +.IR "\fImodf\fR\^(\|)", +.IR "\fInan\fR\^(\|)", +.IR "\fInearbyint\fR\^(\|)", +.IR "\fInextafter\fR\^(\|)", +.IR "\fIpow\fR\^(\|)", +.IR "\fIremainder\fR\^(\|)", +.IR "\fIremquo\fR\^(\|)", +.IR "\fIrint\fR\^(\|)", +.IR "\fIround\fR\^(\|)", +.IR "\fIscalbln\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)", +.IR "\fIsin\fR\^(\|)", +.IR "\fIsinh\fR\^(\|)", +.IR "\fIsqrt\fR\^(\|)", +.IR "\fItan\fR\^(\|)", +.IR "\fItanh\fR\^(\|)", +.IR "\fItgamma\fR\^(\|)", +.IR "\fItrunc\fR\^(\|)", +.IR "\fIy0\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/monetary.h.0p b/man-pages-posix-2013-a/man0p/monetary.h.0p new file mode 100644 index 0000000..e377655 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/monetary.h.0p @@ -0,0 +1,83 @@ +'\" et +.TH monetary.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +monetary.h +\(em monetary types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR ssize_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +ssize_t strfmon(char *restrict, size_t, const char *restrict, ...); +ssize_t strfmon_l(char *restrict, size_t, locale_t, + const char *restrict, ...); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIstrfmon\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/mqueue.h.0p b/man-pages-posix-2013-a/man0p/mqueue.h.0p new file mode 100644 index 0000000..c551a6a --- /dev/null +++ b/man-pages-posix-2013-a/man0p/mqueue.h.0p @@ -0,0 +1,140 @@ +'\" et +.TH mqueue.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mqueue.h +\(em message queues +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR mqd_t +type, which is used for message queue descriptors. This is not an +array type. +.P +The +.IR +header shall define the +.BR pthread_attr_t , +.BR size_t , +and +.BR ssize_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR "struct timespec" +structure as described in +.IR . +.P +The tag +.BR sigevent +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The +.IR +header shall define the +.BR mq_attr +structure, which is used in getting and setting the attributes of a +message queue. Attributes are initially set when the message queue is +created. An +.BR mq_attr +structure shall have at least the following fields: +.sp +.RS 4 +.nf +\fB +long mq_flags \fRMessage queue flags.\fP +long mq_maxmsg \fRMaximum number of messages.\fP +long mq_msgsize \fRMaximum message size.\fP +long mq_curmsgs \fRNumber of messages currently queued.\fP +.fi \fR +.P +.RE +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int mq_close(mqd_t); +int mq_getattr(mqd_t, struct mq_attr *); +int mq_notify(mqd_t, const struct sigevent *); +mqd_t mq_open(const char *, int, ...); +ssize_t mq_receive(mqd_t, char *, size_t, unsigned *); +int mq_send(mqd_t, const char *, size_t, unsigned); +int mq_setattr(mqd_t, const struct mq_attr *restrict, + struct mq_attr *restrict); +ssize_t mq_timedreceive(mqd_t, char *restrict, size_t, + unsigned *restrict, const struct timespec *restrict); +int mq_timedsend(mqd_t, const char *, size_t, unsigned, + const struct timespec *); +int mq_unlink(const char *); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible symbols defined in the headers +.IR , +.IR , +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/ndbm.h.0p b/man-pages-posix-2013-a/man0p/ndbm.h.0p new file mode 100644 index 0000000..8037aeb --- /dev/null +++ b/man-pages-posix-2013-a/man0p/ndbm.h.0p @@ -0,0 +1,115 @@ +'\" et +.TH ndbm.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ndbm.h +\(em definitions for ndbm database operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR datum +type as a structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void *dptr \fRA pointer to the application's data.\fR +size_t dsize \fRThe size of the object pointed to by \fIdptr.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR DBM +type. +.P +The +.IR +header shall define the following symbolic constants as possible +values for the +.IR store_mode +argument to +\fIdbm_store\fR(): +.IP DBM_INSERT 14 +Insertion of new entries only. +.IP DBM_REPLACE 14 +Allow replacing existing entries. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int dbm_clearerr(DBM *); +void dbm_close(DBM *); +int dbm_delete(DBM *, datum); +int dbm_error(DBM *); +datum dbm_fetch(DBM *, datum); +datum dbm_firstkey(DBM *); +datum dbm_nextkey(DBM *); +DBM *dbm_open(const char *, int, mode_t); +int dbm_store(DBM *, datum, datum, int); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR mode_t +type through +.BR typedef , +as described in +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIdbm_clearerr\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/net_if.h.0p b/man-pages-posix-2013-a/man0p/net_if.h.0p new file mode 100644 index 0000000..fb150dc --- /dev/null +++ b/man-pages-posix-2013-a/man0p/net_if.h.0p @@ -0,0 +1,84 @@ +'\" et +.TH net_if.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +net/if.h +\(em sockets local interfaces +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR if_nameindex +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +unsigned if_index \fRNumeric index of the interface.\fR +char *if_name \fRNull-terminated name of the interface.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constant for the length of +a buffer containing an interface name (including the terminating NULL +character): +.IP IF_NAMESIZE 12 +Interface name length. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void if_freenameindex(struct if_nameindex *); +char *if_indextoname(unsigned, char *); +struct if_nameindex *if_nameindex(void); +unsigned if_nametoindex(const char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIif_freenameindex\fR\^(\|)", +.IR "\fIif_indextoname\fR\^(\|)", +.IR "\fIif_nameindex\fR\^(\|)", +.IR "\fIif_nametoindex\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/netdb.h.0p b/man-pages-posix-2013-a/man0p/netdb.h.0p new file mode 100644 index 0000000..41d1376 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/netdb.h.0p @@ -0,0 +1,325 @@ +'\" et +.TH netdb.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +netdb.h +\(em definitions for network database operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header may define the +.BR in_port_t +type and the +.BR in_addr_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR hostent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *h_name \fROfficial name of the host.\fR +char **h_aliases \fRA pointer to an array of pointers to\fR + \fRalternative host names, terminated by a\fR + \fRnull pointer.\fR +int h_addrtype \fRAddress type.\fR +int h_length \fRThe length, in bytes, of the address.\fR +char **h_addr_list \fRA pointer to an array of pointers to network\fR + \fRaddresses (in network byte order) for the host,\fR + \fRterminated by a null pointer.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR netent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *n_name \fROfficial, fully-qualified (including the\fR + \fRdomain) name of the host.\fR +char **n_aliases \fRA pointer to an array of pointers to\fR + \fRalternative network names, terminated by a\fR + \fRnull pointer.\fR +int n_addrtype \fRThe address type of the network.\fR +uint32_t n_net \fRThe network number, in host byte order.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR uint32_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR protoent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *p_name \fROfficial name of the protocol.\fR +char **p_aliases \fRA pointer to an array of pointers to\fR + \fRalternative protocol names, terminated by\fR + \fRa null pointer.\fR +int p_proto \fRThe protocol number.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR servent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *s_name \fROfficial name of the service.\fR +char **s_aliases \fRA pointer to an array of pointers to\fR + \fRalternative service names, terminated by\fR + \fRa null pointer.\fR +int s_port \fRA value which, when converted to uint16_t,\fR + \fRyields the port number in network byte order\fR + \fRat which the service resides.\fR +char *s_proto \fRThe name of the protocol to use when\fR + \fRcontacting the service.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the IPPORT_RESERVED symbolic constant with the +value of the highest reserved Internet port number. +.SS "Address Information Structure" +.P +The +.IR +header shall define the +.BR addrinfo +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int ai_flags \fRInput flags.\fR +int ai_family \fRAddress family of socket.\fR +int ai_socktype \fRSocket type.\fR +int ai_protocol \fRProtocol of socket.\fR +socklen_t ai_addrlen \fRLength of socket address.\fR +struct sockaddr *ai_addr \fRSocket address of socket.\fR +char *ai_canonname \fRCanonical name of service location.\fR +struct addrinfo *ai_next \fRPointer to next in list.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants that evaluate to +bitwise-distinct integer constants for use in the +.IR flags +field of the +.BR addrinfo +structure: +.IP AI_PASSIVE 14 +Socket address is intended for +\fIbind\fR(). +.IP AI_CANONNAME 14 +Request for canonical name. +.IP AI_NUMERICHOST 14 +Return numeric host address as name. +.IP AI_NUMERICSERV 14 +Inhibit service name resolution. +.IP AI_V4MAPPED 14 +If no IPv6 addresses are found, query for IPv4 addresses and return +them to the caller as IPv4-mapped IPv6 addresses. +.IP AI_ALL 14 +Query for both IPv4 and IPv6 addresses. +.IP AI_ADDRCONFIG 14 +Query for IPv4 addresses only when an IPv4 address is configured; +query for IPv6 addresses only when an IPv6 address is configured. +.P +The +.IR +header shall define the following symbolic constants that evaluate +to bitwise-distinct integer constants for use in the +.IR flags +argument to +\fIgetnameinfo\fR(): +.IP NI_NOFQDN 14 +Only the nodename portion of the FQDN is returned for local hosts. +.IP NI_NUMERICHOST 14 +The numeric form of the node's address is returned instead of its +name. +.IP NI_NAMEREQD 14 +Return an error if the node's name cannot be located in the database. +.IP NI_NUMERICSERV 14 +The numeric form of the service address is returned instead of its name. +.IP NI_NUMERICSCOPE 14 +.br +For IPv6 addresses, the numeric form of the scope identifier is +returned instead of its name. +.IP NI_DGRAM 14 +Indicates that the service is a datagram service (SOCK_DGRAM). +.SS "Address Information Errors" +.P +The +.IR +header shall define the following symbolic constants for use as +error values for +\fIgetaddrinfo\fR() +and +\fIgetnameinfo\fR(). +The values shall be suitable for use in +.BR #if +preprocessing directives. +.IP EAI_AGAIN 14 +The name could not be resolved at this time. Future attempts may +succeed. +.IP EAI_BADFLAGS 14 +The flags had an invalid value. +.IP EAI_FAIL 14 +A non-recoverable error occurred. +.IP EAI_FAMILY 14 +The address family was not recognized or the address length was invalid +for the specified family. +.IP EAI_MEMORY 14 +There was a memory allocation failure. +.IP EAI_NONAME 14 +The name does not resolve for the supplied parameters. +.RS 14 +.P +NI_NAMEREQD is set and the host's name cannot be located, or both +.IR nodename +and +.IR servname +were null. +.RE +.IP EAI_SERVICE 14 +The service passed was not recognized for the specified socket type. +.IP EAI_SOCKTYPE 14 +The intended socket type was not recognized. +.IP EAI_SYSTEM 14 +A system error occurred. The error code can be found in +.IR errno . +.IP EAI_OVERFLOW 14 +An argument buffer overflowed. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void endhostent(void); +void endnetent(void); +void endprotoent(void); +void endservent(void); +void freeaddrinfo(struct addrinfo *); +const char *gai_strerror(int); +int getaddrinfo(const char *restrict, const char *restrict, + const struct addrinfo *restrict, + struct addrinfo **restrict); +struct hostent *gethostent(void); +int getnameinfo(const struct sockaddr *restrict, socklen_t, + char *restrict, socklen_t, char *restrict, + socklen_t, int); +struct netent *getnetbyaddr(uint32_t, int); +struct netent *getnetbyname(const char *); +struct netent *getnetent(void); +struct protoent *getprotobyname(const char *); +struct protoent *getprotobynumber(int); +struct protoent *getprotoent(void); +struct servent *getservbyname(const char *, const char *); +struct servent *getservbyport(int, const char *); +struct servent *getservent(void); +void sethostent(int); +void setnetent(int); +void setprotoent(int); +void setservent(int); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR socklen_t +type through +.BR typedef , +as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR , +.IR , +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIbind\fR\^(\|)", +.IR "\fIendhostent\fR\^(\|)", +.IR "\fIendnetent\fR\^(\|)", +.IR "\fIendprotoent\fR\^(\|)", +.IR "\fIendservent\fR\^(\|)", +.IR "\fIfreeaddrinfo\fR\^(\|)", +.IR "\fIgai_strerror\fR\^(\|)", +.IR "\fIgetnameinfo\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/netinet_in.h.0p b/man-pages-posix-2013-a/man0p/netinet_in.h.0p new file mode 100644 index 0000000..039a116 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/netinet_in.h.0p @@ -0,0 +1,391 @@ +'\" et +.TH netinet_in.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +netinet/in.h +\(em Internet address family +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following types: +.IP "\fBin_port_t\fP" 10 +Equivalent to the type +.BR uint16_t +as described in +.IR . +.IP "\fBin_addr_t\fP" 10 +Equivalent to the type +.BR uint32_t +as described in +.IR . +.P +The +.IR +header shall define the +.BR sa_family_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR uint8_t +and +.BR uint32_t +types as described in +.IR . +Inclusion of the +.IR +header may also make visible all symbols from +.IR +and +.IR . +.P +The +.IR +header shall define the +.BR in_addr +structure, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +in_addr_t s_addr +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR sockaddr_in +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t sin_family \fRAF_INET.\fR +in_port_t sin_port \fRPort number.\fR +struct in_addr sin_addr \fRIP address.\fR +.fi \fR +.P +.RE +.P +The +.IR sin_port +and +.IR sin_addr +members shall be in network byte order. +.P +The +.BR sockaddr_in +structure is used to store addresses for the Internet address family. +Pointers to this type shall be cast by applications to +.BR "struct sockaddr *" +for use with socket functions. +.P +The +.IR +header shall define the +.BR in6_addr +structure, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +uint8_t s6_addr[16] +.fi \fR +.P +.RE +.P +This array is used to contain a 128-bit IPv6 address, stored in network +byte order. +.P +The +.IR +header shall define the +.BR sockaddr_in6 +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t sin6_family \fRAF_INET6.\fR +in_port_t sin6_port \fRPort number.\fR +uint32_t sin6_flowinfo \fRIPv6 traffic class and flow information.\fR +struct in6_addr sin6_addr \fRIPv6 address.\fR +uint32_t sin6_scope_id \fRSet of interfaces for a scope.\fR +.fi \fR +.P +.RE +.P +The +.IR sin6_port +and +.IR sin6_addr +members shall be in network byte order. +.P +The +.BR sockaddr_in6 +structure shall be set to zero by an application prior to using it, +since implementations are free to have additional, +implementation-defined fields in +.BR sockaddr_in6 . +.P +The +.IR sin6_scope_id +field is a 32-bit integer that identifies a set of interfaces as +appropriate for the scope of the address carried in the +.IR sin6_addr +field. For a link scope +.IR sin6_addr , +the application shall ensure that +.IR sin6_scope_id +is a link index. For a site scope +.IR sin6_addr , +the application shall ensure that +.IR sin6_scope_id +is a site index. The mapping of +.IR sin6_scope_id +to an interface or set of interfaces is implementation-defined. +.P +The +.IR +header shall declare the following external variable: +.sp +.RS 4 +.nf +\fB +const struct in6_addr in6addr_any +.fi \fR +.P +.RE +.P +This variable is initialized by the system to contain the wildcard IPv6 +address. The +.IR +header also defines the IN6ADDR_ANY_INIT macro. This macro must be +constant at compile time and can be used to initialize a variable of +type +.BR "struct in6_addr" +to the IPv6 wildcard address. +.P +The +.IR +header shall declare the following external variable: +.sp +.RS 4 +.nf +\fB +const struct in6_addr in6addr_loopback +.fi \fR +.P +.RE +.P +This variable is initialized by the system to contain the loopback IPv6 +address. The +.IR +header also defines the IN6ADDR_LOOPBACK_INIT macro. This macro must be +constant at compile time and can be used to initialize a variable of +type +.BR "struct in6_addr" +to the IPv6 loopback address. +.P +The +.IR +header shall define the +.BR ipv6_mreq +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct in6_addr ipv6mr_multiaddr \fRIPv6 multicast address.\fR +unsigned ipv6mr_interface \fRInterface index.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for use as +values of the +.IR level +argument of +\fIgetsockopt\fR() +and +\fIsetsockopt\fR(): +.IP IPPROTO_IP 16 +Internet protocol. +.IP IPPROTO_IPV6 16 +Internet Protocol Version 6. +.IP IPPROTO_ICMP 16 +Control message protocol. +.IP IPPROTO_RAW 16 +Raw IP Packets Protocol. +.IP IPPROTO_TCP 16 +Transmission control protocol. +.IP IPPROTO_UDP 16 +User datagram protocol. +.P +The +.IR +header shall define the following symbolic constants for use as +destination addresses for +\fIconnect\fR(), +\fIsendmsg\fR(), +and +\fIsendto\fR(): +.IP INADDR_ANY 16 +IPv4 local host address. +.IP INADDR_BROADCAST 16 +IPv4 broadcast address. +.P +The +.IR +header shall define the following symbolic constant, with the value +specified, to help applications declare buffers of the proper size +to store IPv4 addresses in string form: +.IP INET_ADDRSTRLEN 16 +16. Length of the string form for IP. +.P +The +\fIhtonl\fR(), +\fIhtons\fR(), +\fIntohl\fR(), +and +\fIntohs\fR() +functions shall be available as described in +.IR . +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.P +The +.IR +header shall define the following symbolic constant, with the value +specified, to help applications declare buffers of the proper size +to store IPv6 addresses in string form: +.IP INET6_ADDRSTRLEN 16 +46. Length of the string form for IPv6. +.br +.P +The +.IR +header shall define the following symbolic constants, with distinct +integer values, for use in the +.IR option_name +argument in the +\fIgetsockopt\fR() +or +\fIsetsockopt\fR() +functions at protocol level IPPROTO_IPV6: +.IP IPV6_JOIN_GROUP 16 +Join a multicast group. +.IP IPV6_LEAVE_GROUP 16 +Quit a multicast group. +.IP IPV6_MULTICAST_HOPS 16 +.br +Multicast hop limit. +.IP IPV6_MULTICAST_IF 16 +Interface to use for outgoing multicast packets. +.IP IPV6_MULTICAST_LOOP 16 +.br +Multicast packets are delivered back to the local application. +.IP IPV6_UNICAST_HOPS 16 +Unicast hop limit. +.IP IPV6_V6ONLY 16 +Restrict AF_INET6 socket to IPv6 communications only. +.P +The +.IR +header shall define the following macros that test for special IPv6 +addresses. Each macro is of type +.BR int +and takes a single argument of type +.BR "const struct in6_addr *" : +.IP IN6_IS_ADDR_UNSPECIFIED 6 +.br +Unspecified address. +.IP IN6_IS_ADDR_LOOPBACK 6 +.br +Loopback address. +.IP IN6_IS_ADDR_MULTICAST 6 +.br +Multicast address. +.IP IN6_IS_ADDR_LINKLOCAL 6 +.br +Unicast link-local address. +.IP IN6_IS_ADDR_SITELOCAL 6 +.br +Unicast site-local address. +.IP IN6_IS_ADDR_V4MAPPED 6 +.br +IPv4 mapped address. +.IP IN6_IS_ADDR_V4COMPAT 6 +.br +IPv4-compatible address. +.IP IN6_IS_ADDR_MC_NODELOCAL 6 +.br +Multicast node-local address. +.IP IN6_IS_ADDR_MC_LINKLOCAL 6 +.br +Multicast link-local address. +.IP IN6_IS_ADDR_MC_SITELOCAL 6 +.br +Multicast site-local address. +.IP IN6_IS_ADDR_MC_ORGLOCAL 6 +.br +Multicast organization-local address. +.IP IN6_IS_ADDR_MC_GLOBAL 6 +.br +Multicast global address. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 4.9" ", " "Host and Network Byte Orders", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIhtonl\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/netinet_tcp.h.0p b/man-pages-posix-2013-a/man0p/netinet_tcp.h.0p new file mode 100644 index 0000000..b04e7c3 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/netinet_tcp.h.0p @@ -0,0 +1,59 @@ +'\" et +.TH netinet_tcp.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +netinet/tcp.h +\(em definitions for the Internet Transmission Control Protocol (TCP) +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constant for use as a +socket option at the IPPROTO_TCP level: +.IP TCP_NODELAY 12 +Avoid coalescing of small segments. +.P +The implementation need not allow the value of the option to be set via +\fIsetsockopt\fR() +or retrieved via +\fIgetsockopt\fR(). +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/nl_types.h.0p b/man-pages-posix-2013-a/man0p/nl_types.h.0p new file mode 100644 index 0000000..f0ef942 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/nl_types.h.0p @@ -0,0 +1,109 @@ +'\" et +.TH nl_types.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nl_types.h +\(em data types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define at least the following types: +.IP "\fBnl_catd\fP" 14 +Used by the message catalog functions +\fIcatopen\fR(), +\fIcatgets\fR(), +and +\fIcatclose\fR() +to identify a catalog descriptor. +.IP "\fBnl_item\fP" 14 +Used by +\fInl_langinfo\fR() +to identify items of +.IR langinfo +data. Values of objects of type +.BR nl_item +are defined in +.IR . +.P +The +.IR +header shall define at least the following symbolic constants: +.IP NL_SETD 14 +Used by +.IR gencat +when no $\fIset\fP directive is specified in a message text source +file. This constant can be passed as the value of +.IR set_id +on subsequent calls to +\fIcatgets\fR() +(that is, to retrieve messages from the default message set). The +value of NL_SETD is implementation-defined. +.IP NL_CAT_LOCALE 14 +Value that must be passed as the +.IR oflag +argument to +\fIcatopen\fR() +to ensure that message catalog selection depends on the +.IR LC_MESSAGES +locale category, rather than directly on the +.IR LANG +environment variable. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int catclose(nl_catd); +char *catgets(nl_catd, int, int, const char *); +nl_catd catopen(const char *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcatclose\fR\^(\|)", +.IR "\fIcatgets\fR\^(\|)", +.IR "\fIcatopen\fR\^(\|)", +.IR "\fInl_langinfo\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgencat\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/poll.h.0p b/man-pages-posix-2013-a/man0p/poll.h.0p new file mode 100644 index 0000000..82680aa --- /dev/null +++ b/man-pages-posix-2013-a/man0p/poll.h.0p @@ -0,0 +1,135 @@ +'\" et +.TH poll.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +poll.h +\(em definitions for the poll(\|) function +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR pollfd +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int fd \fRThe following descriptor being polled.\fP +short events \fRThe input event flags (see below).\fP +short revents \fRThe output event flags (see below).\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following type through +.BR typedef : +.IP "\fBnfds_t\fR" 14 +An unsigned integer type used for the number of file descriptors. +.P +The implementation shall support one or more programming environments +in which the width of +.BR nfds_t +is no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.P +The +.IR +header shall define the following symbolic constants, zero or more of +which may be OR'ed together to form the +.IR events +or +.IR revents +members in the +.BR pollfd +structure: +.IP POLLIN 14 +Data other than high-priority data may be read without blocking. +.IP POLLRDNORM 14 +Normal data may be read without blocking. +.IP POLLRDBAND 14 +Priority data may be read without blocking. +.IP POLLPRI 14 +High priority data may be read without blocking. +.IP POLLOUT 14 +Normal data may be written without blocking. +.IP POLLWRNORM 14 +Equivalent to POLLOUT. +.IP POLLWRBAND 14 +Priority data may be written. +.IP POLLERR 14 +An error has occurred (\c +.IR revents +only). +.IP POLLHUP 14 +Device has been disconnected (\c +.IR revents +only). +.IP POLLNVAL 14 +Invalid +.IR fd +member (\c +.IR revents +only). +.P +The significance and semantics of normal, priority, and high-priority +data are file and device-specific. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +int poll(struct pollfd [], nfds_t, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/pthread.h.0p b/man-pages-posix-2013-a/man0p/pthread.h.0p new file mode 100644 index 0000000..e8e1bce --- /dev/null +++ b/man-pages-posix-2013-a/man0p/pthread.h.0p @@ -0,0 +1,325 @@ +'\" et +.TH pthread.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread.h +\(em threads +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants: +.P +.nf +PTHREAD_BARRIER_SERIAL_THREAD +PTHREAD_CANCEL_ASYNCHRONOUS +PTHREAD_CANCEL_ENABLE +PTHREAD_CANCEL_DEFERRED +PTHREAD_CANCEL_DISABLE +PTHREAD_CANCELED +PTHREAD_CREATE_DETACHED +PTHREAD_CREATE_JOINABLE +PTHREAD_EXPLICIT_SCHED +PTHREAD_INHERIT_SCHED +PTHREAD_MUTEX_DEFAULT +PTHREAD_MUTEX_ERRORCHECK +PTHREAD_MUTEX_NORMAL +PTHREAD_MUTEX_RECURSIVE +PTHREAD_MUTEX_ROBUST +PTHREAD_MUTEX_STALLED +PTHREAD_ONCE_INIT +PTHREAD_PRIO_INHERIT +PTHREAD_PRIO_NONE +PTHREAD_PRIO_PROTECT +PTHREAD_PROCESS_SHARED +PTHREAD_PROCESS_PRIVATE +PTHREAD_SCOPE_PROCESS +PTHREAD_SCOPE_SYSTEM +.fi +.P +The +.IR +header shall define the following compile-time constant +expressions valid as initializers for the following types: +.TS +tab(!) center box; +cB | cB +l | lB. +Name!Initializer for Type +_ +PTHREAD_COND_INITIALIZER!pthread_cond_t +PTHREAD_MUTEX_INITIALIZER!pthread_mutex_t +PTHREAD_RWLOCK_INITIALIZER!pthread_rwlock_t +.TE +.P +The +.IR +header shall define the +.BR pthread_attr_t , +.BR pthread_barrier_t , +.BR pthread_barrierattr_t , +.BR pthread_cond_t , +.BR pthread_condattr_t , +.BR pthread_key_t , +.BR pthread_mutex_t , +.BR pthread_mutexattr_t , +.BR pthread_once_t , +.BR pthread_rwlock_t , +.BR pthread_rwlockattr_t , +.BR pthread_spinlock_t , +and +.BR pthread_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int pthread_atfork(void (*)(void), void (*)(void), + void(*)(void)); +int pthread_attr_destroy(pthread_attr_t *); +int pthread_attr_getdetachstate(const pthread_attr_t *, int *); +int pthread_attr_getguardsize(const pthread_attr_t *restrict, + size_t *restrict); +int pthread_attr_getinheritsched(const pthread_attr_t *restrict, + int *restrict); +int pthread_attr_getschedparam(const pthread_attr_t *restrict, + struct sched_param *restrict); +int pthread_attr_getschedpolicy(const pthread_attr_t *restrict, + int *restrict); +int pthread_attr_getscope(const pthread_attr_t *restrict, + int *restrict); +int pthread_attr_getstack(const pthread_attr_t *restrict, + void **restrict, size_t *restrict); +int pthread_attr_getstacksize(const pthread_attr_t *restrict, + size_t *restrict); +int pthread_attr_init(pthread_attr_t *); +int pthread_attr_setdetachstate(pthread_attr_t *, int); +int pthread_attr_setguardsize(pthread_attr_t *, size_t); +int pthread_attr_setinheritsched(pthread_attr_t *, int); +int pthread_attr_setschedparam(pthread_attr_t *restrict, + const struct sched_param *restrict); +int pthread_attr_setschedpolicy(pthread_attr_t *, int); +int pthread_attr_setscope(pthread_attr_t *, int); +int pthread_attr_setstack(pthread_attr_t *, void *, size_t); +int pthread_attr_setstacksize(pthread_attr_t *, size_t); +int pthread_barrier_destroy(pthread_barrier_t *); +int pthread_barrier_init(pthread_barrier_t *restrict, + const pthread_barrierattr_t *restrict, unsigned); +int pthread_barrier_wait(pthread_barrier_t *); +int pthread_barrierattr_destroy(pthread_barrierattr_t *); +int pthread_barrierattr_getpshared( + const pthread_barrierattr_t *restrict, int *restrict); +int pthread_barrierattr_init(pthread_barrierattr_t *); +int pthread_barrierattr_setpshared(pthread_barrierattr_t *, int); +int pthread_cancel(pthread_t); +void pthread_cleanup_pop(int); +void pthread_cleanup_push(void (*)(void*), void *); +int pthread_cond_broadcast(pthread_cond_t *); +int pthread_cond_destroy(pthread_cond_t *); +int pthread_cond_init(pthread_cond_t *restrict, + const pthread_condattr_t *restrict); +int pthread_cond_signal(pthread_cond_t *); +int pthread_cond_timedwait(pthread_cond_t *restrict, + pthread_mutex_t *restrict, const struct timespec *restrict); +int pthread_cond_wait(pthread_cond_t *restrict, + pthread_mutex_t *restrict); +int pthread_condattr_destroy(pthread_condattr_t *); +int pthread_condattr_getclock(const pthread_condattr_t *restrict, + clockid_t *restrict); +int pthread_condattr_getpshared(const pthread_condattr_t *restrict, + int *restrict); +int pthread_condattr_init(pthread_condattr_t *); +int pthread_condattr_setclock(pthread_condattr_t *, clockid_t); +int pthread_condattr_setpshared(pthread_condattr_t *, int); +int pthread_create(pthread_t *restrict, const pthread_attr_t *restrict, + void *(*)(void*), void *restrict); +int pthread_detach(pthread_t); +int pthread_equal(pthread_t, pthread_t); +void pthread_exit(void *); +int pthread_getconcurrency(void); +int pthread_getcpuclockid(pthread_t, clockid_t *); +int pthread_getschedparam(pthread_t, int *restrict, + struct sched_param *restrict); +void *pthread_getspecific(pthread_key_t); +int pthread_join(pthread_t, void **); +int pthread_key_create(pthread_key_t *, void (*)(void*)); +int pthread_key_delete(pthread_key_t); +int pthread_mutex_consistent(pthread_mutex_t *); +int pthread_mutex_destroy(pthread_mutex_t *); +int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict, + int *restrict); +int pthread_mutex_init(pthread_mutex_t *restrict, + const pthread_mutexattr_t *restrict); +int pthread_mutex_lock(pthread_mutex_t *); +int pthread_mutex_setprioceiling(pthread_mutex_t *restrict, int, + int *restrict); +int pthread_mutex_timedlock(pthread_mutex_t *restrict, + const struct timespec *restrict); +int pthread_mutex_trylock(pthread_mutex_t *); +int pthread_mutex_unlock(pthread_mutex_t *); +int pthread_mutexattr_destroy(pthread_mutexattr_t *); +int pthread_mutexattr_getprioceiling( + const pthread_mutexattr_t *restrict, int *restrict); +int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *restrict, + int *restrict); +int pthread_mutexattr_getpshared(const pthread_mutexattr_t *restrict, + int *restrict); +int pthread_mutexattr_getrobust(const pthread_mutexattr_t *restrict, + int *restrict); +int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict, + int *restrict); +int pthread_mutexattr_init(pthread_mutexattr_t *); +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int); +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int); +int pthread_mutexattr_setpshared(pthread_mutexattr_t *, int); +int pthread_mutexattr_setrobust(pthread_mutexattr_t *, int); +int pthread_mutexattr_settype(pthread_mutexattr_t *, int); +int pthread_once(pthread_once_t *, void (*)(void)); +int pthread_rwlock_destroy(pthread_rwlock_t *); +int pthread_rwlock_init(pthread_rwlock_t *restrict, + const pthread_rwlockattr_t *restrict); +int pthread_rwlock_rdlock(pthread_rwlock_t *); +int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict, + const struct timespec *restrict); +int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict, + const struct timespec *restrict); +int pthread_rwlock_tryrdlock(pthread_rwlock_t *); +int pthread_rwlock_trywrlock(pthread_rwlock_t *); +int pthread_rwlock_unlock(pthread_rwlock_t *); +int pthread_rwlock_wrlock(pthread_rwlock_t *); +int pthread_rwlockattr_destroy(pthread_rwlockattr_t *); +int pthread_rwlockattr_getpshared( + const pthread_rwlockattr_t *restrict, int *restrict); +int pthread_rwlockattr_init(pthread_rwlockattr_t *); +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int); +pthread_t + pthread_self(void); +int pthread_setcancelstate(int, int *); +int pthread_setcanceltype(int, int *); +int pthread_setconcurrency(int); +int pthread_setschedparam(pthread_t, int, + const struct sched_param *); +int pthread_setschedprio(pthread_t, int); +int pthread_setspecific(pthread_key_t, const void *); +int pthread_spin_destroy(pthread_spinlock_t *); +int pthread_spin_init(pthread_spinlock_t *, int); +int pthread_spin_lock(pthread_spinlock_t *); +int pthread_spin_trylock(pthread_spinlock_t *); +int pthread_spin_unlock(pthread_spinlock_t *); +void pthread_testcancel(void); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header shall make symbols defined in the headers +.IR +and +.IR +visible. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)", +.IR "\fIpthread_attr_getguardsize\fR\^(\|)", +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)", +.IR "\fIpthread_attr_getschedparam\fR\^(\|)", +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)", +.IR "\fIpthread_attr_getscope\fR\^(\|)", +.IR "\fIpthread_attr_getstack\fR\^(\|)", +.IR "\fIpthread_attr_getstacksize\fR\^(\|)", +.IR "\fIpthread_barrier_destroy\fR\^(\|)", +.IR "\fIpthread_barrier_wait\fR\^(\|)", +.IR "\fIpthread_barrierattr_destroy\fR\^(\|)", +.IR "\fIpthread_barrierattr_getpshared\fR\^(\|)", +.IR "\fIpthread_cancel\fR\^(\|)", +.IR "\fIpthread_cleanup_pop\fR\^(\|)", +.IR "\fIpthread_cond_broadcast\fR\^(\|)", +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_condattr_destroy\fR\^(\|)", +.IR "\fIpthread_condattr_getclock\fR\^(\|)", +.IR "\fIpthread_condattr_getpshared\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_detach\fR\^(\|)", +.IR "\fIpthread_equal\fR\^(\|)", +.IR "\fIpthread_exit\fR\^(\|)", +.IR "\fIpthread_getconcurrency\fR\^(\|)", +.IR "\fIpthread_getcpuclockid\fR\^(\|)", +.IR "\fIpthread_getschedparam\fR\^(\|)", +.IR "\fIpthread_getspecific\fR\^(\|)", +.IR "\fIpthread_join\fR\^(\|)", +.IR "\fIpthread_key_create\fR\^(\|)", +.IR "\fIpthread_key_delete\fR\^(\|)", +.IR "\fIpthread_mutex_consistent\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_getprioceiling\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIpthread_mutexattr_destroy\fR\^(\|)", +.IR "\fIpthread_mutexattr_getprioceiling\fR\^(\|)", +.IR "\fIpthread_mutexattr_getprotocol\fR\^(\|)", +.IR "\fIpthread_mutexattr_getpshared\fR\^(\|)", +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)", +.IR "\fIpthread_mutexattr_gettype\fR\^(\|)", +.IR "\fIpthread_once\fR\^(\|)", +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)", +.IR "\fIpthread_rwlockattr_destroy\fR\^(\|)", +.IR "\fIpthread_rwlockattr_getpshared\fR\^(\|)", +.IR "\fIpthread_self\fR\^(\|)", +.IR "\fIpthread_setcancelstate\fR\^(\|)", +.IR "\fIpthread_setschedprio\fR\^(\|)", +.IR "\fIpthread_spin_destroy\fR\^(\|)", +.IR "\fIpthread_spin_lock\fR\^(\|)", +.IR "\fIpthread_spin_unlock\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/pwd.h.0p b/man-pages-posix-2013-a/man0p/pwd.h.0p new file mode 100644 index 0000000..f57166c --- /dev/null +++ b/man-pages-posix-2013-a/man0p/pwd.h.0p @@ -0,0 +1,95 @@ +'\" et +.TH pwd.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pwd.h +\(em password structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR "struct passwd" , +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *pw_name \fRUser's login name.\fP +uid_t pw_uid \fRNumerical user ID.\fP +gid_t pw_gid \fRNumerical group ID.\fP +char *pw_dir \fRInitial working directory.\fP +char *pw_shell \fRProgram to use as shell.\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR gid_t , +.BR uid_t , +and +.BR size_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void endpwent(void); +struct passwd *getpwent(void); +struct passwd *getpwnam(const char *); +int getpwnam_r(const char *, struct passwd *, char *, + size_t, struct passwd **); +struct passwd *getpwuid(uid_t); +int getpwuid_r(uid_t, struct passwd *, char *, + size_t, struct passwd **); +void setpwent(void); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIendpwent\fR\^(\|)", +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/regex.h.0p b/man-pages-posix-2013-a/man0p/regex.h.0p new file mode 100644 index 0000000..5d0caa5 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/regex.h.0p @@ -0,0 +1,209 @@ +'\" et +.TH regex.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +regex.h +\(em regular expression matching types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structures and symbolic constants used by the +\fIregcomp\fR(), +\fIregexec\fR(), +\fIregerror\fR(), +and +\fIregfree\fR() +functions. +.P +The +.IR +header shall define the +.BR regex_t +structure type, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +size_t re_nsub \fRNumber of parenthesized subexpressions.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR regoff_t +type as a signed integer type that can hold +the largest value that can be stored in either a +.BR ptrdiff_t +type or a +.BR ssize_t +type. +.P +The +.IR +header shall define the +.BR regmatch_t +structure type, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +regoff_t rm_so \fRByte offset from start of string\fR + \fRto start of substring.\fR +regoff_t rm_eo \fRByte offset from start of string of the\fR + \fRfirst character after the end of substring.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for the +.IR cflags +parameter to the +\fIregcomp\fR() +function: +.IP REG_EXTENDED 14 +Use Extended Regular Expressions. +.IP REG_ICASE 14 +Ignore case in match. +.IP REG_NOSUB 14 +Report only success or fail in +\fIregexec\fR(). +.IP REG_NEWLINE 14 +Change the handling of +. +.P +The +.IR +header shall define the following symbolic constants for the +.IR eflags +parameter to the +\fIregexec\fR() +function: +.IP REG_NOTBOL 14 +The + +character (\c +.BR '^' ), +when taken as a special character, does not match the beginning of +.IR string . +.IP REG_NOTEOL 14 +The + +(\c +.BR '$' ), +when taken as a special character, does not match the end of +.IR string . +.P +The +.IR +header shall define the following symbolic constants as error +return values: +.IP REG_NOMATCH 14 +\fIregexec\fR() +failed to match. +.IP REG_BADPAT 14 +Invalid regular expression. +.IP REG_ECOLLATE 14 +Invalid collating element referenced. +.IP REG_ECTYPE 14 +Invalid character class type referenced. +.IP REG_EESCAPE 14 +Trailing + +character in pattern. +.IP REG_ESUBREG 14 +Number in \e\fIdigit\fP invalid or in error. +.IP REG_EBRACK 14 +.BR \(dq[]\(dq +imbalance. +.IP REG_EPAREN 14 +.BR \(dq\e(\e)\(dq +or +.BR \(dq()\(dq +imbalance. +.IP REG_EBRACE 14 +.BR \(dq\e{\e}\(dq +imbalance. +.IP REG_BADBR 14 +Content of +.BR \(dq\e{\e}\(dq +invalid: not a number, number too large, more than two numbers, first +larger than second. +.IP REG_ERANGE 14 +Invalid endpoint in range expression. +.IP REG_ESPACE 14 +Out of memory. +.IP REG_BADRPT 14 +.BR '?' , +.BR '*' , +or +.BR '+' +not preceded by valid regular expression. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int regcomp(regex_t *restrict, const char *restrict, int); +size_t regerror(int, const regex_t *restrict, char *restrict, size_t); +int regexec(const regex_t *restrict, const char *restrict, size_t, + regmatch_t [restrict], int); +void regfree(regex_t *); +.fi \fR +.P +.RE +.P +The implementation may define additional macros or constants using +names beginning with REG_. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIregcomp\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sched.h.0p b/man-pages-posix-2013-a/man0p/sched.h.0p new file mode 100644 index 0000000..488ffd1 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sched.h.0p @@ -0,0 +1,155 @@ +'\" et +.TH sched.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sched.h +\(em execution scheduling +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR pid_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR time_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR timespec +structure as described in +.IR . +.P +The +.IR +header shall define the +.BR sched_param +structure, which shall include the scheduling parameters required for +implementation of each supported scheduling policy. This structure +shall include at least the following member: +.sp +.RS 4 +.nf +\fB +int sched_priority \fRProcess or thread execution scheduling priority.\fP +.fi \fR +.P +.RE +.P +The +.BR sched_param +structure defined in +.IR +shall include the following members in addition to those specified +above: +.sp +.RS 4 +.nf +\fB +int sched_ss_low_priority \fRLow scheduling priority for\fR + \fRsporadic server.\fR +struct timespec sched_ss_repl_period \fRReplenishment period for\fR + \fRsporadic server.\fR +struct timespec sched_ss_init_budget \fRInitial budget for sporadic server.\fR +int sched_ss_max_repl \fRMaximum pending replenishments for\fR + \fRsporadic server.\fR +.fi \fR +.P +.RE +.P +Each process or thread is controlled by an associated scheduling policy +and priority. Associated with each policy is a priority range. Each +policy definition specifies the minimum priority range for that +policy. The priority ranges for each policy may overlap the priority +ranges of other policies. +.P +Four scheduling policies are defined; others may be defined by the +implementation. The four standard policies are indicated by the +values of the following symbolic constants: +.IP SCHED_FIFO 14 +First in-first out (FIFO) scheduling policy. +.IP SCHED_RR 14 +Round robin scheduling policy. +.IP SCHED_SPORADIC 14 +Sporadic server scheduling policy. +.IP SCHED_OTHER 14 +Another scheduling policy. +.P +The values of these constants are distinct. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int sched_get_priority_max(int); +int sched_get_priority_min(int); +int sched_getparam(pid_t, struct sched_param *); +int sched_getscheduler(pid_t); +int sched_rr_get_interval(pid_t, struct timespec *); +int sched_setparam(pid_t, const struct sched_param *); +int sched_setscheduler(pid_t, int, const struct sched_param *); +int sched_yield(void); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIsched_get_priority_max\fR\^(\|)", +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_rr_get_interval\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)", +.IR "\fIsched_yield\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/search.h.0p b/man-pages-posix-2013-a/man0p/search.h.0p new file mode 100644 index 0000000..fca8acf --- /dev/null +++ b/man-pages-posix-2013-a/man0p/search.h.0p @@ -0,0 +1,115 @@ +'\" et +.TH search.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +search.h +\(em search tables +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR ENTRY +type for structure +.BR entry +which shall include the following members: +.sp +.RS 4 +.nf +\fB +char *key +void *data +.fi \fR +.P +.RE +.P +and shall define +.BR ACTION +and +.BR VISIT +as enumeration data types through type definitions as follows: +.sp +.RS 4 +.nf +\fB +enum { FIND, ENTER } ACTION; +enum { preorder, postorder, endorder, leaf } VISIT; +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int hcreate(size_t); +void hdestroy(void); +ENTRY *hsearch(ENTRY, ACTION); +void insque(void *, void *); +void *lfind(const void *, const void *, size_t *, + size_t, int (*)(const void *, const void *)); +void *lsearch(const void *, void *, size_t *, + size_t, int (*)(const void *, const void *)); +void remque(void *); +void *tdelete(const void *restrict, void **restrict, + int(*)(const void *, const void *)); +void *tfind(const void *, void *const *, + int(*)(const void *, const void *)); +void *tsearch(const void *, void **, + int(*)(const void *, const void *)); +void twalk(const void *, + void (*)(const void *, VISIT, int )); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIhcreate\fR\^(\|)", +.IR "\fIinsque\fR\^(\|)", +.IR "\fIlsearch\fR\^(\|)", +.IR "\fItdelete\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/semaphore.h.0p b/man-pages-posix-2013-a/man0p/semaphore.h.0p new file mode 100644 index 0000000..3f277f4 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/semaphore.h.0p @@ -0,0 +1,100 @@ +'\" et +.TH semaphore.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +semaphore.h +\(em semaphores +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR sem_t +type, used in performing semaphore operations. The semaphore may be +implemented using a file descriptor, in which case applications are +able to open up at least a total of +{OPEN_MAX} +files and semaphores. +.P +The +.IR +header shall define the symbolic constant SEM_FAILED which shall +have type +.BR "sem_t *" . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int sem_close(sem_t *); +int sem_destroy(sem_t *); +int sem_getvalue(sem_t *restrict, int *restrict); +int sem_init(sem_t *, int, unsigned); +sem_t *sem_open(const char *, int, ...); +int sem_post(sem_t *); +int sem_timedwait(sem_t *restrict, const struct timespec *restrict); +int sem_trywait(sem_t *); +int sem_unlink(const char *); +int sem_wait(sem_t *); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible symbols defined in the +.IR +and +.IR +headers. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_getvalue\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/setjmp.h.0p b/man-pages-posix-2013-a/man0p/setjmp.h.0p new file mode 100644 index 0000000..c090cc7 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/setjmp.h.0p @@ -0,0 +1,89 @@ +'\" et +.TH setjmp.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setjmp.h +\(em stack environment declarations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the array types +.BR jmp_buf +and +.BR sigjmp_buf . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void _longjmp(jmp_buf, int); +void longjmp(jmp_buf, int); +void siglongjmp(sigjmp_buf, int); +.fi \fR +.P +.RE +.P +The following may be declared as functions, or defined as macros, or +both. If functions are declared, function prototypes shall be +provided. +.sp +.RS 4 +.nf +\fB +int _setjmp(jmp_buf); +int setjmp(jmp_buf); +int sigsetjmp(sigjmp_buf, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fI_longjmp\fR\^(\|)", +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIsetjmp\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/signal.h.0p b/man-pages-posix-2013-a/man0p/signal.h.0p new file mode 100644 index 0000000..c3b579c --- /dev/null +++ b/man-pages-posix-2013-a/man0p/signal.h.0p @@ -0,0 +1,582 @@ +'\" et +.TH signal.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +signal.h +\(em signals +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following macros, which shall expand to constant +expressions with distinct values that have a type compatible with the +second argument to, and the return value of, the +\fIsignal\fR() +function, and whose values shall compare unequal to the address of any +declarable function. +.IP SIG_DFL 14 +Request for default signal handling. +.IP SIG_ERR 14 +Return value from +\fIsignal\fR() +in case of error. +.IP SIG_HOLD 14 +Request that signal be held. +.IP SIG_IGN 14 +Request that signal be ignored. +.P +The +.IR +header shall define the +.BR pthread_t , +.BR size_t , +and +.BR uid_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR timespec +structure as described in +.IR . +.P +The +.IR +header shall define the following data types: +.IP "\fBsig_atomic_t\fP" 14 +Possibly volatile-qualified integer type of an object that can be +accessed as an atomic entity, even in the presence of asynchronous +interrupts. +.IP "\fBsigset_t\fP" 14 +Integer or structure type of an object used to represent sets of +signals. +.IP "\fBpid_t\fP" 14 +As described in +.IR . +.P +The +.IR +header shall define the +.BR pthread_attr_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR sigevent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int sigev_notify \fRNotification type.\fP +int sigev_signo \fRSignal number.\fP +union sigval sigev_value \fRSignal value.\fP +void (*sigev_notify_function)(union sigval) + \fRNotification function.\fP +pthread_attr_t *sigev_notify_attributes \fRNotification attributes.\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for the values of +.IR sigev_notify : +.IP SIGEV_NONE 14 +No asynchronous notification is delivered when the event of interest +occurs. +.IP SIGEV_SIGNAL 14 +A queued signal, with an application-defined value, is generated when +the event of interest occurs. +.IP SIGEV_THREAD 14 +A notification function is called to perform notification. +.br +.P +The +.BR sigval +union shall be defined as: +.sp +.RS 4 +.nf +\fB +int sival_int \fRInteger signal value.\fP +void *sival_ptr \fRPointer signal value.\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall declare the SIGRTMIN and SIGRTMAX macros, +which shall expand to positive integer expressions with type +.BR int , +but which need not be constant expressions. These macros specify a +range of signal numbers that are reserved for application use and for +which the realtime signal behavior specified in this volume of POSIX.1\(hy2008 is supported. The +signal numbers in this range do not overlap any of the signals specified +in the following table. +.P +The range SIGRTMIN through SIGRTMAX inclusive shall include at least +{RTSIG_MAX} +signal numbers. +.P +It is implementation-defined whether realtime signal behavior is +supported for other signals. +.P +The +.IR +header shall define the following macros that are used to refer to the +signals that occur in the system. Signals defined here begin with the +letters SIG followed by an uppercase letter. The macros shall expand to +positive integer constant expressions with type +.BR int +and distinct values. The value 0 is reserved for use as the null signal +(see +\fIkill\fR()). +Additional implementation-defined signals may occur in the system. +.P +The ISO\ C standard only requires the signal names SIGABRT, SIGFPE, SIGILL, +SIGINT, SIGSEGV, and SIGTERM to be defined. +.P +The following signals shall be supported on all implementations +(default actions are explained below the table): +.TS +box center tab(!); +cB | cB | cB +l | n | lw(3.6i). +Signal!Default Action!Description +_ +SIGABRT!A!Process abort signal. +SIGALRM!T!Alarm clock. +SIGBUS!A!Access to an undefined portion of a memory object. +SIGCHLD!I!Child process terminated, stopped, +!!or continued. +SIGCONT!C!Continue executing, if stopped. +SIGFPE!A!Erroneous arithmetic operation. +SIGHUP!T!Hangup. +SIGILL!A!Illegal instruction. +SIGINT!T!Terminal interrupt signal. +SIGKILL!T!Kill (cannot be caught or ignored). +SIGPIPE!T!Write on a pipe with no one to read it. +SIGQUIT!A!Terminal quit signal. +SIGSEGV!A!Invalid memory reference. +SIGSTOP!S!Stop executing (cannot be caught or ignored). +SIGTERM!T!Termination signal. +SIGTSTP!S!Terminal stop signal. +SIGTTIN!S!Background process attempting read. +SIGTTOU!S!Background process attempting write. +SIGUSR1!T!User-defined signal 1. +SIGUSR2!T!User-defined signal 2. +SIGPOLL!T!Pollable event. +SIGPROF!T!Profiling timer expired. +SIGSYS!A!Bad system call. +SIGTRAP!A!Trace/breakpoint trap. +SIGURG!I!High bandwidth data is available at a socket. +SIGVTALRM!T!Virtual timer expired. +SIGXCPU!A!CPU time limit exceeded. +SIGXFSZ!A!File size limit exceeded. +.sp +.TE +.br +.P +The default actions are as follows: +.IP T 6 +Abnormal termination of the process. +.IP A 6 +Abnormal termination of the process +with additional actions. +.IP I 6 +Ignore the signal. +.IP S 6 +Stop the process. +.IP C 6 +Continue the process, if it is stopped; otherwise, ignore the signal. +.P +The effects on the process in each case are described in the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.4.3" ", " "Signal Actions". +.P +The +.IR +header shall declare the +.BR sigaction +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void (*sa_handler)(int) \fRPointer to a signal-catching function\fR + \fRor one of the SIG_IGN or SIG_DFL.\fR +sigset_t sa_mask \fRSet of signals to be blocked during execution\fR + \fRof the signal handling function.\fR +int sa_flags \fRSpecial flags.\fR +void (*sa_sigaction)(int, siginfo_t *, void *) + \fRPointer to a signal-catching function.\fR +.fi \fR +.P +.RE +.P +The storage occupied by +.IR sa_handler +and +.IR sa_sigaction +may overlap, and a conforming application shall not use both +simultaneously. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions that need not be usable in +.BR #if +preprocessing directives: +.IP SIG_BLOCK 14 +The resulting set is the union of the current set and the signal set +pointed to by the argument +.IR set . +.IP SIG_UNBLOCK 14 +The resulting set is the intersection of the current set and the +complement of the signal set pointed to by the argument +.IR set . +.IP SIG_SETMASK 14 +The resulting set is the signal set pointed to by the argument +.IR set . +.P +The +.IR +header shall also define the following symbolic constants: +.IP SA_NOCLDSTOP 14 +Do not generate SIGCHLD when children stop +.br +or stopped children continue. +.IP SA_ONSTACK 14 +Causes signal delivery to occur on an alternate stack. +.IP SA_RESETHAND 14 +Causes signal dispositions to be set to SIG_DFL on entry to signal +handlers. +.IP SA_RESTART 14 +Causes certain functions to become restartable. +.IP SA_SIGINFO 14 +Causes extra information to be passed to signal handlers at the time of +receipt of a signal. +.IP SA_NOCLDWAIT 14 +Causes implementations not to create zombie processes on child death. +.IP SA_NODEFER 14 +Causes signal not to be automatically blocked on entry to signal handler. +.IP SS_ONSTACK 14 +Process is executing on an alternate signal stack. +.IP SS_DISABLE 14 +Alternate signal stack is disabled. +.IP MINSIGSTKSZ 14 +Minimum stack size for a signal handler. +.IP SIGSTKSZ 14 +Default size in bytes for the alternate signal stack. +.P +The +.IR +header shall define the +.BR mcontext_t +type through +.BR typedef . +.P +The +.IR +header shall define the +.BR ucontext_t +type as a structure that shall include at least the following members: +.sp +.RS 4 +.nf +\fB +ucontext_t *uc_link \fRPointer to the context that is resumed\fR + \fRwhen this context returns.\fR +sigset_t uc_sigmask \fRThe set of signals that are blocked when this\fR + \fRcontext is active.\fR +stack_t uc_stack \fRThe stack used by this context.\fR +mcontext_t uc_mcontext \fRA machine-specific representation of the saved\fR + \fRcontext.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR stack_t +type as a structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void *ss_sp \fRStack base or pointer.\fR +size_t ss_size \fRStack size.\fR +int ss_flags \fRFlags.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR siginfo_t +type as a structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int si_signo \fRSignal number.\fR +int si_code \fRSignal code.\fR +int si_errno \fRIf non-zero, an \fIerrno\fR value associated with\fR + \fRthis signal, as described in \fB\fR.\fR +pid_t si_pid \fRSending process ID.\fR +uid_t si_uid \fRReal user ID of sending process.\fR +void *si_addr \fRAddress of faulting instruction.\fR +int si_status \fRExit value or signal.\fR +long si_band \fRBand event for SIGPOLL.\fR +union sigval si_value \fRSignal value.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the symbolic constants in the +.BR Code +column of the following table for use as values of +.IR si_code +that are signal-specific or non-signal-specific reasons why the +signal was generated. +.TS +box center tab(!); +cB | cB | cB +l1 | l1 | l. +Signal!Code!Reason +_ +SIGILL!ILL_ILLOPC!Illegal opcode. +!ILL_ILLOPN!Illegal operand. +!ILL_ILLADR!Illegal addressing mode. +!ILL_ILLTRP!Illegal trap. +!ILL_PRVOPC!Privileged opcode. +!ILL_PRVREG!Privileged register. +!ILL_COPROC!Coprocessor error. +!ILL_BADSTK!Internal stack error. +_ +SIGFPE!FPE_INTDIV!Integer divide by zero. +!FPE_INTOVF!Integer overflow. +!FPE_FLTDIV!Floating-point divide by zero. +!FPE_FLTOVF!Floating-point overflow. +!FPE_FLTUND!Floating-point underflow. +!FPE_FLTRES!Floating-point inexact result. +!FPE_FLTINV!Invalid floating-point operation. +!FPE_FLTSUB!Subscript out of range. +_ +SIGSEGV!SEGV_MAPERR!Address not mapped to object. +!SEGV_ACCERR!Invalid permissions for mapped object. +_ +SIGBUS!BUS_ADRALN!Invalid address alignment. +!BUS_ADRERR!Nonexistent physical address. +!BUS_OBJERR!Object-specific hardware error. +_ +SIGTRAP!TRAP_BRKPT!Process breakpoint. +!TRAP_TRACE!Process trace trap. +_ +SIGCHLD!CLD_EXITED!Child has exited. +!CLD_KILLED!Child has terminated abnormally and did not create a \fBcore\fP file. +!CLD_DUMPED!Child has terminated abnormally and created a \fBcore\fP file. +!CLD_TRAPPED!Traced child has trapped. +!CLD_STOPPED!Child has stopped. +!CLD_CONTINUED!Stopped child has continued. +_ +SIGPOLL!POLL_IN!Data input available. +!POLL_OUT!Output buffers available. +!POLL_MSG!Input message available. +!POLL_ERR!I/O error. +!POLL_PRI!High priority input available. +!POLL_HUP!Device disconnected. +_ +Any!SI_USER!Signal sent by \fIkill\fP\^(\|). +!SI_QUEUE!Signal sent by \fIsigqueue\fP\^(\|). +!SI_TIMER!Signal generated by expiration of a timer set by \fItimer_settime\fP\^(\|). +!SI_ASYNCIO!Signal generated by completion of an asynchronous I/O +!!request. +!SI_MESGQ!Signal generated by arrival of a message on an empty message +!!queue. +.TE +.P +Implementations may support additional +.IR si_code +values not included in this list, may generate values included in this +list under circumstances other than those described in this list, and +may contain extensions or limitations that prevent some values from +being generated. Implementations do not generate a different value from +the ones described in this list for circumstances described in this +list. +.br +.P +In addition, the following signal-specific information shall be +available: +.TS +box center tab(!); +cB | cB | cB +l | lB | lw(3.9i). +Signal!Member!Value +_ +SIGILL!void * \fIsi_addr\fP!Address of faulting instruction. +SIGFPE +_ +SIGSEGV!void * \fIsi_addr\fP!Address of faulting memory reference. +SIGBUS +_ +SIGCHLD!pid_t \fIsi_pid\fP!Child process ID. +!int \fIsi_status\fP!Exit value or signal. +!uid_t \fIsi_uid\fP!Real user ID of the process that sent the signal. +_ +SIGPOLL!long \fIsi_band\fP!Band event for POLL_IN, POLL_OUT, or POLL_MSG. +.TE +.P +For some implementations, the value of \fIsi_addr\fR may be inaccurate. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int kill(pid_t, int); +int killpg(pid_t, int); +void psiginfo(const siginfo_t *, const char *); +void psignal(int, const char *); +int pthread_kill(pthread_t, int); +int pthread_sigmask(int, const sigset_t *restrict, + sigset_t *restrict); +int raise(int); +int sigaction(int, const struct sigaction *restrict, + struct sigaction *restrict); +int sigaddset(sigset_t *, int); +int sigaltstack(const stack_t *restrict, stack_t *restrict); +int sigdelset(sigset_t *, int); +int sigemptyset(sigset_t *); +int sigfillset(sigset_t *); +int sighold(int); +int sigignore(int); +int siginterrupt(int, int); +int sigismember(const sigset_t *, int); +void (*signal(int, void (*)(int)))(int); +int sigpause(int); +int sigpending(sigset_t *); +int sigprocmask(int, const sigset_t *restrict, sigset_t *restrict); +int sigqueue(pid_t, int, const union sigval); +int sigrelse(int); +void (*sigset(int, void (*)(int)))(int); +int sigsuspend(const sigset_t *); +int sigtimedwait(const sigset_t *restrict, siginfo_t *restrict, + const struct timespec *restrict); +int sigwait(const sigset_t *restrict, int *restrict); +int sigwaitinfo(const sigset_t *restrict, siginfo_t *restrict); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +On systems not supporting the XSI option, the +.IR si_pid +and +.IR si_uid +members of +.BR siginfo_t +are only required to be valid when +.IR si_code +is SI_USER or SI_QUEUE. On XSI-conforming systems, they are also +valid for all +.IR si_code +values less than or equal to 0; however, it is unspecified whether +SI_USER and SI_QUEUE have values less than or equal to zero, and +therefore XSI applications should check whether +.IR si_code +has the value SI_USER or SI_QUEUE or is less than or equal to 0 +to tell whether +.IR si_pid +and +.IR si_uid +are valid. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The SIGPOLL and SIGPROF signals may be removed in a future version. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIalarm\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIkillpg\fR\^(\|)", +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIpthread_kill\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsighold\fR\^(\|)", +.IR "\fIsiginterrupt\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigqueue\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIsigtimedwait\fR\^(\|)", +.IR "\fIsigwait\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/spawn.h.0p b/man-pages-posix-2013-a/man0p/spawn.h.0p new file mode 100644 index 0000000..1fe6495 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/spawn.h.0p @@ -0,0 +1,168 @@ +'\" et +.TH spawn.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +spawn.h +\(em spawn (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR posix_spawnattr_t +and +.BR posix_spawn_file_actions_t +types used in performing spawn operations. +.P +The +.IR +header shall define the +.BR mode_t +and +.BR pid_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR sigset_t +type as described in +.IR . +.P +The tag +.BR sched_param +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The +.IR +header shall define the following symbolic constants for use as the +flags that may be set in a +.BR posix_spawnattr_t +object using the +\fIposix_spawnattr_setflags\fR() +function: +.P +.nf +POSIX_SPAWN_RESETIDS +POSIX_SPAWN_SETPGROUP +POSIX_SPAWN_SETSCHEDPARAM +POSIX_SPAWN_SETSCHEDULER +POSIX_SPAWN_SETSIGDEF +POSIX_SPAWN_SETSIGMASK +.fi +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int posix_spawn(pid_t *restrict, const char *restrict, + const posix_spawn_file_actions_t *, + const posix_spawnattr_t *restrict, char *const [restrict], + char *const [restrict]); +int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *, + int); +int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t *, + int, int); +int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict, + int, const char *restrict, int, mode_t); +int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t *); +int posix_spawn_file_actions_init(posix_spawn_file_actions_t *); +int posix_spawnattr_destroy(posix_spawnattr_t *); +int posix_spawnattr_getflags(const posix_spawnattr_t *restrict, + short *restrict); +int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict, + pid_t *restrict); +int posix_spawnattr_getschedparam(const posix_spawnattr_t *restrict, + struct sched_param *restrict); +int posix_spawnattr_getschedpolicy(const posix_spawnattr_t *restrict, + int *restrict); +int posix_spawnattr_getsigdefault(const posix_spawnattr_t *restrict, + sigset_t *restrict); +int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict, + sigset_t *restrict); +int posix_spawnattr_init(posix_spawnattr_t *); +int posix_spawnattr_setflags(posix_spawnattr_t *, short); +int posix_spawnattr_setpgroup(posix_spawnattr_t *, pid_t); +.br +int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict, + const struct sched_param *restrict); +int posix_spawnattr_setschedpolicy(posix_spawnattr_t *, int); +int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict, + const sigset_t *restrict); +int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict, + const sigset_t *restrict); +int posix_spawnp(pid_t *restrict, const char *restrict, + const posix_spawn_file_actions_t *, + const posix_spawnattr_t *restrict, + char *const [restrict], char *const [restrict]); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible symbols defined in the +.IR +and +.IR +headers. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_adddup2\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/stdarg.h.0p b/man-pages-posix-2013-a/man0p/stdarg.h.0p new file mode 100644 index 0000000..bfd5979 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/stdarg.h.0p @@ -0,0 +1,224 @@ +'\" et +.TH stdarg.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stdarg.h +\(em handle variable argument list +.SH SYNOPSIS +.LP +.nf +#include +.P +void va_start(va_list \fIap\fP, \fIargN\fP); +void va_copy(va_list \fIdest\fP, va_list \fIsrc\fP); +\fItype\fP va_arg(va_list \fIap\fP, \fItype\fP); +void va_end(va_list \fIap\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall contain a set of macros which allows portable functions +that accept variable argument lists to be written. Functions that have +variable argument lists (such as +\fIprintf\fR()) +but do not use these macros are inherently non-portable, as different +systems use different argument-passing conventions. +.P +The +.IR +header shall define the +.BR va_list +type for variables used to traverse the list. +.P +The +\fIva_start\fR() +macro is invoked to initialize +.IR ap +to the beginning of the list before any calls to +\fIva_arg\fR(). +.P +The +\fIva_copy\fR() +macro initializes +.IR dest +as a copy of +.IR src , +as if the +\fIva_start\fR() +macro had been applied to +.IR dest +followed by the same sequence of uses of the +\fIva_arg\fR() +macro as had previously been used to reach the present state of +.IR src . +Neither the +\fIva_copy\fR() +nor +\fIva_start\fR() +macro shall be invoked to reinitialize +.IR dest +without an intervening invocation of the +\fIva_end\fR() +macro for the same +.IR dest . +.P +The object +.IR ap +may be passed as an argument to another function; if that function +invokes the +\fIva_arg\fR() +macro with parameter +.IR ap , +the value of +.IR ap +in the calling function is unspecified and shall be passed to the +\fIva_end\fR() +macro prior to any further reference to +.IR ap . +The parameter +.IR argN +is the identifier of the rightmost parameter in the variable parameter +list in the function definition (the one just before the .\|.\|.). If +the parameter +.IR argN +is declared with the +.BR register +storage class, with a function type or array type, or with a type that +is not compatible with the type that results after application of the +default argument promotions, the behavior is undefined. +.P +The +\fIva_arg\fR() +macro shall return the next argument in the list pointed to by +.IR ap . +Each invocation of +\fIva_arg\fR() +modifies +.IR ap +so that the values of successive arguments are returned in turn. The +.IR type +parameter shall be a type name specified such that the type of a +pointer to an object that has the specified type can be obtained simply +by postfixing a +.BR '*' +to type. If there is no actual next argument, or if +.IR type +is not compatible with the type of the actual next argument (as +promoted according to the default argument promotions), the behavior is +undefined, except for the following cases: +.IP " *" 4 +One type is a signed integer type, the other type is the corresponding +unsigned integer type, and the value is representable in both types. +.IP " *" 4 +One type is a pointer to +.BR void +and the other is a pointer to a character type. +.IP " *" 4 +Both types are pointers. +.P +Different types can be mixed, but it is up to the routine to +know what type of argument is expected. +.P +The +\fIva_end\fR() +macro is used to clean up; it invalidates +.IR ap +for use (unless +\fIva_start\fR() +or +\fIva_copy\fR() +is invoked again). +.P +Each invocation of the +\fIva_start\fR() +and +\fIva_copy\fR() +macros shall be matched by a corresponding invocation of the +\fIva_end\fR() +macro in the same function. +.P +Multiple traversals, each bracketed by +\fIva_start\fR() +\&.\|.\|. +\fIva_end\fR(), +are possible. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +This example is a possible implementation of +\fIexecl\fR(): +.sp +.RS 4 +.nf +\fB +#include +.P +#define MAXARGS 31 +.P +/* + * execl is called by + * execl(file, arg1, arg2, ..., (char *)(0)); + */ +int execl(const char *file, const char *args, ...) +{ + va_list ap; + char *array[MAXARGS +1]; + int argno = 0; +.P + va_start(ap, args); + while (args != 0 && argno < MAXARGS) + { + array[argno++] = args; + args = va_arg(ap, const char *); + } + array[argno] = (char *) 0; + va_end(ap); + return execv(file, array); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +It is up to the calling routine to communicate to the called routine +how many arguments there are, since it is not always possible for the +called routine to determine this in any other way. For example, +\fIexecl\fR() +is passed a null pointer to signal the end of the list. The +\fIprintf\fR() +function can tell how many arguments are there by the +.IR format +argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^", +.IR "\fIfprintf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/stdbool.h.0p b/man-pages-posix-2013-a/man0p/stdbool.h.0p new file mode 100644 index 0000000..746124b --- /dev/null +++ b/man-pages-posix-2013-a/man0p/stdbool.h.0p @@ -0,0 +1,65 @@ +'\" et +.TH stdbool.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stdbool.h +\(em boolean type and values +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following macros: +.IP bool 8 +Expands to +.BR _Bool . +.IP true 8 +Expands to the integer constant 1. +.IP false 8 +Expands to the integer constant 0. +.IP "_\|_bool_true_false_are_defined" 8 +.br +Expands to the integer constant 1. +.P +An application may undefine and then possibly redefine the macros bool, +true, and false. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The ability to undefine and redefine the macros bool, true, and false +is an obsolescent feature and may be removed in a future version. +.SH "SEE ALSO" +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/stddef.h.0p b/man-pages-posix-2013-a/man0p/stddef.h.0p new file mode 100644 index 0000000..48a629d --- /dev/null +++ b/man-pages-posix-2013-a/man0p/stddef.h.0p @@ -0,0 +1,104 @@ +'\" et +.TH stddef.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stddef.h +\(em standard type definitions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following macros: +.IP NULL 10 +Null pointer constant. +The macro shall expand to an integer constant expression with the +value 0 cast to type +.BR "void *" . +.IP "offsetof(\fItype\fP, \fImember-designator\fP)" 10 +.br +Integer constant expression of type +.BR size_t , +the value of which is the offset in bytes to the structure member +(\fImember-designator\fP), from the beginning of its structure +(\fItype\fP). +.P +The +.IR +header shall define the following types: +.IP "\fBptrdiff_t\fP" 10 +Signed integer type of the result of subtracting two pointers. +.IP "\fBwchar_t\fP" 10 +Integer type whose range of values can represent distinct codes for +all members of the largest extended character set specified among the +supported locales; the null character shall have the code value zero. Each +member of the basic character set shall have a code value equal to its +value when used as the lone character in an integer character constant +if an implementation does not define _\|_STDC_MB_MIGHT_NEQ_WC_\|_. +.IP "\fBsize_t\fP" 10 +Unsigned integer type of the result of the +.IR sizeof +operator. +.P +The implementation shall support one or more programming environments +in which the widths of +.BR ptrdiff_t , +.BR size_t , +and +.BR wchar_t +are no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The ISO\ C standard does not require the NULL macro to include the cast to type +.BR "void *" +and specifies that the NULL macro be implementation-defined. POSIX.1\(hy2008 +requires the cast and therefore need not be implementation-defined. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconfstr\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/stdint.h.0p b/man-pages-posix-2013-a/man0p/stdint.h.0p new file mode 100644 index 0000000..96a0428 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/stdint.h.0p @@ -0,0 +1,644 @@ +'\" et +.TH stdint.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.EQ +delim $$ +.EN +.SH NAME +stdint.h +\(em integer types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall declare sets of integer types having specified widths, and +shall define corresponding sets of macros. It shall also define macros +that specify limits of integer types corresponding to types defined in +other standard headers. +.TP 10 +.BR Note: +The ``width'' of an integer type is the number of bits used to store +its value in a pure binary system; the actual type may use more bits +than that (for example, a 28-bit type could be stored in 32 bits of +actual storage). An +.IR N -bit +signed type has values in the range \(mi2\s-3\u\fIN\fR\(mi1\d\s+3 or +1\(mi2\s-3\u\fIN\fR\(mi1\d\s+3 to 2\s-3\u\fIN\fR\(mi1\d\s+3\(mi1, while +an +.IR N -bit +unsigned type has values in the range 0 to 2\s-3\u\fIN\fR\d\s+3\(mi1. +.P +.P +Types are defined in the following categories: +.IP " *" 4 +Integer types having certain exact widths +.IP " *" 4 +Integer types having at least certain specified widths +.IP " *" 4 +Fastest integer types having at least certain specified widths +.IP " *" 4 +Integer types wide enough to hold pointers to objects +.IP " *" 4 +Integer types having greatest width +.P +(Some of these types may denote the same type.) +.P +Corresponding macros specify limits of the declared types and construct +suitable constants. +.P +For each type described herein that the implementation provides, the +.IR +header shall declare that +.BR typedef +name and define the associated macros. Conversely, for each type +described herein that the implementation does not provide, the +.IR +header shall not declare that +.BR typedef +name, nor shall it define the associated macros. An implementation +shall provide those types described as required, but need not provide +any of the others (described as optional). +.SS "Integer Types" +.P +When +.BR typedef +names differing only in the absence or presence of the initial +.IR u +are defined, they shall denote corresponding signed and unsigned types +as described in the ISO/IEC\ 9899:\|1999 standard, Section 6.2.5; an implementation providing +one of these corresponding types shall also provide the other. +.P +In the following descriptions, the symbol +.IR N +represents an unsigned decimal integer with no leading zeros (for +example, 8 or 24, but not 04 or 048). +.IP " *" 4 +Exact-width integer types +.RS 4 +.P +The +.BR typedef +name +.BR int \c +.IR N \c +.BR _t +designates a signed integer type with width +.IR N , +no padding bits, and a two's-complement representation. Thus, +.BR int8_t +denotes a signed integer type with a width of exactly 8 bits. +.P +The +.BR typedef +name +.BR uint \c +.IR N \c +.BR _t +designates an unsigned integer type with width +.IR N . +Thus, +.BR uint24_t +denotes an unsigned integer type with a width of exactly 24 bits. +.P +The following types are required: +.P +.nf +.BR int8_t +.BR int16_t +.BR int32_t +.BR uint8_t +.BR uint16_t +.BR uint32_t +.fi +.P +If an implementation provides integer types with width 64 that +meet these requirements, then the following types are required: +.BR int64_t +.BR uint64_t +.P +In particular, this will be the case if any of the following are +true: +.IP -- 4 +The implementation supports the _POSIX_V7_ILP32_OFFBIG programming +environment and the application is being built in the +_POSIX_V7_ILP32_OFFBIG programming environment (see the Shell and Utilities volume of POSIX.1\(hy2008, +.IR c99 , +Programming Environments). +.IP -- 4 +The implementation supports the _POSIX_V7_LP64_OFF64 programming +environment and the application is being built in the +_POSIX_V7_LP64_OFF64 programming environment. +.IP -- 4 +The implementation supports the _POSIX_V7_LPBIG_OFFBIG programming +environment and the application is being built in the +_POSIX_V7_LPBIG_OFFBIG programming environment. +.P +All other types of this form are optional. +.RE +.IP " *" 4 +Minimum-width integer types +.RS 4 +.P +The +.BR typedef +name +.BR int_least \c +.IR N \c +.BR _t +designates a signed integer type with a width of at least +.IR N , +such that no signed integer type with lesser size has at least the +specified width. Thus, +.BR int_least32_t +denotes a signed integer type with a width of at least 32 bits. +.P +The +.BR typedef +name +.BR uint_least \c +.IR N \c +.BR _t +designates an unsigned integer type with a width of at least +.IR N , +such that no unsigned integer type with lesser size has at least the +specified width. Thus, +.BR uint_least16_t +denotes an unsigned integer type with a width of at least 16 bits. +.P +The following types are required: +.BR int_least8_t +.BR int_least16_t +.BR int_least32_t +.BR int_least64_t +.BR uint_least8_t +.BR uint_least16_t +.BR uint_least32_t +.BR uint_least64_t +.P +All other types of this form are optional. +.RE +.IP " *" 4 +Fastest minimum-width integer types +.RS 4 +.P +Each of the following types designates an integer type that is usually +fastest to operate with among all integer types that have at least the +specified width. +.P +The designated type is not guaranteed to be fastest for all purposes; +if the implementation has no clear grounds for choosing one type over +another, it will simply pick some integer type satisfying the +signedness and width requirements. +.P +The +.BR typedef +name +.BR int_fast \c +.IR N \c +.BR _t +designates the fastest signed integer type with a width of at least +.IR N . +The +.BR typedef +name +.BR uint_fast \c +.IR N \c +.BR _t +designates the fastest unsigned integer type with a width of at least +.IR N . +.P +The following types are required: +.BR int_fast8_t +.BR int_fast16_t +.BR int_fast32_t +.BR int_fast64_t +.BR uint_fast8_t +.BR uint_fast16_t +.BR uint_fast32_t +.BR uint_fast64_t +.P +All other types of this form are optional. +.RE +.IP " *" 4 +Integer types capable of holding object pointers +.RS 4 +.P +The following type designates a signed integer type with the property +that any valid pointer to +.BR void +can be converted to this type, then converted back to a pointer to +.BR void , +and the result will compare equal to the original pointer: +.BR intptr_t +.P +The following type designates an unsigned integer type with the +property that any valid pointer to +.BR void +can be converted to this type, then converted back to a pointer to +.BR void , +and the result will compare equal to the original pointer: +.BR uintptr_t +.P +On XSI-conformant systems, the +.BR intptr_t +and +.BR uintptr_t +types are required; +otherwise, they are optional. +.RE +.IP " *" 4 +Greatest-width integer types +.RS 4 +.P +The following type designates a signed integer type capable of +representing any value of any signed integer type: +.BR intmax_t +.P +The following type designates an unsigned integer type capable of +representing any value of any unsigned integer type: +.BR uintmax_t +.P +These types are required. +.RE +.TP 10 +.BR Note: +Applications can test for optional types by using the corresponding +limit macro from +.IR "Limits of Specified-Width Integer Types". +.P +.SS "Limits of Specified-Width Integer Types" +.P +The following macros specify the minimum and maximum limits of the +types declared in the +.IR +header. Each macro name corresponds to a similar type name in +.IR "Integer Types". +.P +Each instance of any defined macro shall be replaced by a constant +expression suitable for use in +.BR #if +preprocessing directives, and this expression shall have the same type +as would an expression that is an object of the corresponding type +converted according to the integer promotions. Its +implementation-defined value shall be equal to or greater in magnitude +(absolute value) than the corresponding value given below, with the +same sign, except where stated to be exactly the given value. +.IP " *" 4 +Limits of exact-width integer types +.RS 4 +.IP -- 4 +Minimum values of exact-width signed integer types: +.RS 4 +.IP "{INT\fIN\fR_MIN}" 16 +Exactly \(mi($2"^" N\(mi1$) +.RE +.IP -- 4 +Maximum values of exact-width signed integer types: +.RS 4 +.IP "{INT\fIN\fR_MAX}" 16 +Exactly $2"^" N\(mi1$ \(mi1 +.RE +.IP -- 4 +Maximum values of exact-width unsigned integer types: +.RS 4 +.IP "{UINT\fIN\fR_MAX}" 16 +Exactly $2"^" N$ \(mi1 +.RE +.RE +.IP " *" 4 +Limits of minimum-width integer types +.RS 4 +.IP -- 4 +Minimum values of minimum-width signed integer types: +.RS 4 +.IP "{INT_LEAST\fIN\fR_MIN}" 16 +\(mi($2"^" N\(mi1$ \(mi1) +.RE +.IP -- 4 +Maximum values of minimum-width signed integer types: +.RS 4 +.IP "{INT_LEAST\fIN\fR_MAX}" 16 +$2"^" N\(mi1$ \(mi1 +.RE +.IP -- 4 +Maximum values of minimum-width unsigned integer types: +.RS 4 +.IP "{UINT_LEAST\fIN\fR_MAX}" 16 +$2"^" N$ \(mi1 +.RE +.RE +.IP " *" 4 +Limits of fastest minimum-width integer types +.RS 4 +.IP -- 4 +Minimum values of fastest minimum-width signed integer types: +.RS 4 +.IP "{INT_FAST\fIN\fR_MIN}" 16 +\(mi($2"^" N\(mi1$ \(mi1) +.RE +.IP -- 4 +Maximum values of fastest minimum-width signed integer types: +.RS 4 +.IP "{INT_FAST\fIN\fR_MAX}" 16 +$2"^" N\(mi1$ \(mi1 +.RE +.IP -- 4 +Maximum values of fastest minimum-width unsigned integer types: +.RS 4 +.IP "{UINT_FAST\fIN\fR_MAX}" 16 +$2"^" N$ \(mi1 +.RE +.RE +.IP " *" 4 +Limits of integer types capable of holding object pointers +.RS 4 +.IP -- 4 +Minimum value of pointer-holding signed integer type: +.RS 4 +.IP {INTPTR_MIN} 16 +\(mi($2"^" 15$ \(mi1) +.RE +.IP -- 4 +Maximum value of pointer-holding signed integer type: +.RS 4 +.IP {INTPTR_MAX} 16 +$2"^" 15$ \(mi1 +.RE +.IP -- 4 +Maximum value of pointer-holding unsigned integer type: +.RS 4 +.IP {UINTPTR_MAX} 16 +$2"^" 16$ \(mi1 +.RE +.RE +.IP " *" 4 +Limits of greatest-width integer types +.RS 4 +.IP -- 4 +Minimum value of greatest-width signed integer type: +.RS 4 +.IP {INTMAX_MIN} 16 +\(mi($2"^" 63$ \(mi1) +.RE +.IP -- 4 +Maximum value of greatest-width signed integer type: +.RS 4 +.IP {INTMAX_MAX} 16 +$2"^" 63$ \(mi1 +.RE +.IP -- 4 +Maximum value of greatest-width unsigned integer type: +.RS 4 +.IP {UINTMAX_MAX} 16 +$2"^" 64$ \(mi1 +.RE +.RE +.SS "Limits of Other Integer Types" +.P +The following macros specify the minimum and maximum limits of integer +types corresponding to types defined in other standard headers. +.P +Each instance of these macros shall be replaced by a constant +expression suitable for use in +.BR #if +preprocessing directives, and this expression shall have the same type +as would an expression that is an object of the corresponding type +converted according to the integer promotions. Its +implementation-defined value shall be equal to or greater in magnitude +(absolute value) than the corresponding value given below, with the +same sign. +.IP " *" 4 +Limits of \fBptrdiff_t\fR: +.RS 4 +.IP {PTRDIFF_MIN} 16 +\(mi65\|535 +.IP {PTRDIFF_MAX} 16 ++65\|535 +.RE +.IP " *" 4 +Limits of \fBsig_atomic_t\fR: +.RS 4 +.IP {SIG_ATOMIC_MIN} 16 +See below. +.IP {SIG_ATOMIC_MAX} 16 +See below. +.RE +.IP " *" 4 +Limit of \fBsize_t\fR: +.RS 4 +.IP {SIZE_MAX} 16 +65\|535 +.RE +.IP " *" 4 +Limits of \fBwchar_t\fR: +.RS 4 +.IP {WCHAR_MIN} 16 +See below. +.IP {WCHAR_MAX} 16 +See below. +.RE +.IP " *" 4 +Limits of \fBwint_t\fR: +.RS 4 +.IP {WINT_MIN} 16 +See below. +.IP {WINT_MAX} 16 +See below. +.RE +.P +If +.BR sig_atomic_t +(see the +.IR +header) is defined as a signed integer type, the value of +{SIG_ATOMIC_MIN} +shall be no greater than \(mi127 and the value of +{SIG_ATOMIC_MAX} +shall be no less than 127; otherwise, +.BR sig_atomic_t +shall be defined as an unsigned integer type, and the value of +{SIG_ATOMIC_MIN} +shall be 0 and the value of +{SIG_ATOMIC_MAX} +shall be no less than 255. +.P +If +.BR wchar_t +(see the +.IR +header) is defined as a signed integer type, the value of +{WCHAR_MIN} +shall be no greater than \(mi127 and the value of +{WCHAR_MAX} +shall be no less than 127; otherwise, +.BR wchar_t +shall be defined as an unsigned integer type, and the value of +{WCHAR_MIN} +shall be 0 and the value of +{WCHAR_MAX} +shall be no less than 255. +.P +If +.BR wint_t +(see the +.IR +header) is defined as a signed integer type, the value of +{WINT_MIN} +shall be no greater than \(mi32\|767 and the value of +{WINT_MAX} +shall be no less than 32\|767; otherwise, +.BR wint_t +shall be defined as an unsigned integer type, and the value of +{WINT_MIN} +shall be 0 and the value of +{WINT_MAX} +shall be no less than 65\|535. +.SS "Macros for Integer Constant Expressions" +.P +The following macros expand to integer constant expressions suitable for +initializing objects that have integer types corresponding to types +defined in the +.IR +header. Each macro name corresponds to a similar type name listed under +\fIMinimum-width integer types\fR and \fIGreatest-width integer +types\fR. +.P +Each invocation of one of these macros shall expand to an integer +constant expression suitable for use in +.BR #if +preprocessing directives. The type of the expression shall have the +same type as would an expression that is an object of the corresponding +type converted according to the integer promotions. The value of the +expression shall be that of the argument. +.P +The argument in any instance of these macros shall be an unsuffixed +integer constant with a value that does not exceed the limits for the +corresponding type. +.IP " *" 4 +Macros for minimum-width integer constant expressions +.RS 4 +.P +The macro +.IR INTN_C (\c +.IR value ) +shall expand to an integer constant expression corresponding to the +type +.BR int_least \c +.IR N \c +.BR _t . +The macro +.IR UINTN_C (\c +.IR value ) +shall expand to an integer constant expression corresponding to the +type +.BR uint_least \c +.IR N \c +.BR _t . +For example, if +.BR uint_least64_t +is a name for the type +.BR "unsigned long long" , +then +.IR UINT64_C (0x123) +might expand to the integer constant 0x123ULL. +.RE +.IP " *" 4 +Macros for greatest-width integer constant expressions +.RS 4 +.P +The following macro expands to an integer constant expression having +the value specified by its argument and the type +.BR intmax_t : +INTMAX_C(\fIvalue\fR) +.P +The following macro expands to an integer constant expression having +the value specified by its argument and the type +.BR uintmax_t : +UINTMAX_C(\fIvalue\fR) +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +.IR +header is a subset of the +.IR +header more suitable for use in freestanding environments, which might +not support the formatted I/O functions. In some environments, if the +formatted conversion support is not wanted, using this header instead +of the +.IR +header avoids defining such a large number of macros. +.br +.P +As a consequence of adding +.BR int8_t , +the following are true: +.IP " *" 4 +A byte is exactly 8 bits. +.IP " *" 4 +{CHAR_BIT} +has the value 8, +{SCHAR_MAX} +has the value 127, +{SCHAR_MIN} +has the value \(mi128, and +{UCHAR_MAX} +has the value 255. +.P +(The POSIX standard explicitly requires 8-bit char and +two's-complement arithmetic.) +.SH "FUTURE DIRECTIONS" +.BR typedef +names beginning with +.BR int +or +.BR uint +and ending with _t may be added to the types defined in the +.IR +header. Macro names beginning with INT or UINT and ending with _MAX, +_MIN, or _C may be added to the macros defined in the +.IR +header. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/stdio.h.0p b/man-pages-posix-2013-a/man0p/stdio.h.0p new file mode 100644 index 0000000..1954b79 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/stdio.h.0p @@ -0,0 +1,327 @@ +'\" et +.TH stdio.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stdio.h +\(em standard buffered input/output +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBFILE\fP" 14 +A structure containing information about a file. +.IP "\fBfpos_t\fP" 14 +A non-array type containing all information needed to specify uniquely +every position within a file. +.IP "\fBoff_t\fP" 14 +As described in +.IR . +.IP "\fBsize_t\fP" 14 +As described in +.IR . +.IP "\fBssize_t\fP" 14 +As described in +.IR . +.IP "\fBva_list\fP" 14 +As described in +.IR . +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions: +.IP BUFSIZ 14 +Size of +.IR +buffers. +This shall expand to a positive value. +.IP L_ctermid 14 +Maximum size of character array to hold +\fIctermid\fR() +output. +.IP L_tmpnam 14 +Maximum size of character array to hold +\fItmpnam\fR() +output. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions with distinct values: +.IP _IOFBF 14 +Input/output fully buffered. +.IP _IOLBF 14 +Input/output line buffered. +.IP _IONBF 14 +Input/output unbuffered. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions with distinct values: +.IP SEEK_CUR 14 +Seek relative to current position. +.IP SEEK_END 14 +Seek relative to end-of-file. +.IP SEEK_SET 14 +Seek relative to start-of-file. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions denoting implementation limits: +.IP {FILENAME_MAX} 14 +Maximum size in bytes of the longest pathname that the implementation +guarantees can be opened. +.IP {FOPEN_MAX} 14 +Number of streams which the implementation guarantees can be open +simultaneously. The value is at least eight. +.IP {TMP_MAX} 14 +Minimum number of unique filenames generated by +\fItmpnam\fR(). +Maximum number of times an application can call +\fItmpnam\fR() +reliably. The value of +{TMP_MAX} +is at least 25. +.RS 14 +.P +On XSI-conformant systems, the value of +{TMP_MAX} +is at least 10\|000. +.RE +.P +The +.IR +header shall define the following macro which shall expand to an integer +constant expression with type +.BR int +and a negative value: +.IP EOF 14 +End-of-file return value. +.P +The +.IR +header shall define NULL as described in +.IR . +.br +.P +The +.IR +header shall define the following macro which shall expand to a +string constant: +.IP P_tmpdir 14 +Default directory prefix for +\fItempnam\fR(). +.P +The +.IR +header shall define the following macros which shall expand to +expressions of type ``pointer to +.BR FILE '' +that point to the +.BR FILE +objects associated, respectively, with the standard error, input, and +output streams: +.IP "\fIstderr\fR" 14 +Standard error output stream. +.IP "\fIstdin\fR" 14 +Standard input stream. +.IP "\fIstdout\fR" 14 +Standard output stream. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void clearerr(FILE *); +char *ctermid(char *); +int dprintf(int, const char *restrict, ...) +int fclose(FILE *); +FILE *fdopen(int, const char *); +int feof(FILE *); +int ferror(FILE *); +int fflush(FILE *); +int fgetc(FILE *); +int fgetpos(FILE *restrict, fpos_t *restrict); +char *fgets(char *restrict, int, FILE *restrict); +int fileno(FILE *); +void flockfile(FILE *); +FILE *fmemopen(void *restrict, size_t, const char *restrict); +FILE *fopen(const char *restrict, const char *restrict); +int fprintf(FILE *restrict, const char *restrict, ...); +int fputc(int, FILE *); +int fputs(const char *restrict, FILE *restrict); +size_t fread(void *restrict, size_t, size_t, FILE *restrict); +FILE *freopen(const char *restrict, const char *restrict, + FILE *restrict); +int fscanf(FILE *restrict, const char *restrict, ...); +int fseek(FILE *, long, int); +int fseeko(FILE *, off_t, int); +int fsetpos(FILE *, const fpos_t *); +long ftell(FILE *); +off_t ftello(FILE *); +int ftrylockfile(FILE *); +void funlockfile(FILE *); +size_t fwrite(const void *restrict, size_t, size_t, FILE *restrict); +int getc(FILE *); +int getchar(void); +int getc_unlocked(FILE *); +int getchar_unlocked(void); +ssize_t getdelim(char **restrict, size_t *restrict, int, + FILE *restrict); +ssize_t getline(char **restrict, size_t *restrict, FILE *restrict); +char *gets(char *); +FILE *open_memstream(char **, size_t *); +int pclose(FILE *); +void perror(const char *); +FILE *popen(const char *, const char *); +int printf(const char *restrict, ...); +int putc(int, FILE *); +int putchar(int); +int putc_unlocked(int, FILE *); +int putchar_unlocked(int); +int puts(const char *); +int remove(const char *); +int rename(const char *, const char *); +int renameat(int, const char *, int, const char *); +void rewind(FILE *); +int scanf(const char *restrict, ...); +void setbuf(FILE *restrict, char *restrict); +int setvbuf(FILE *restrict, char *restrict, int, size_t); +int snprintf(char *restrict, size_t, const char *restrict, ...); +int sprintf(char *restrict, const char *restrict, ...); +int sscanf(const char *restrict, const char *restrict, ...); +char *tempnam(const char *, const char *); +FILE *tmpfile(void); +char *tmpnam(char *); +int ungetc(int, FILE *); +int vdprintf(int, const char *restrict, va_list); +int vfprintf(FILE *restrict, const char *restrict, va_list); +int vfscanf(FILE *restrict, const char *restrict, va_list); +int vprintf(const char *restrict, va_list); +int vscanf(const char *restrict, va_list); +int vsnprintf(char *restrict, size_t, const char *restrict, + va_list); +int vsprintf(char *restrict, const char *restrict, va_list); +int vsscanf(const char *restrict, const char *restrict, va_list); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since standard I/O streams may use an underlying file descriptor to +access the file associated with a stream, application developers need +to be aware that +{FOPEN_MAX} +streams may not be available if file descriptors are being used to access +files that are not associated with streams. +.SH RATIONALE +There is a conflict between the ISO\ C standard and the POSIX definition of the +{TMP_MAX} +macro that is addressed by ISO/IEC\ 9899:\|1999 standard, Defect Report 336. The POSIX standard is +in alignment with the public record of the response to the Defect Report. +This change has not yet been published as part of the ISO\ C standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIclearerr\fR\^(\|)", +.IR "\fIctermid\fR\^(\|)", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfflush\fR\^(\|)", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfgetpos\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)", +.IR "\fIfileno\fR\^(\|)", +.IR "\fIflockfile\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfputc\fR\^(\|)", +.IR "\fIfputs\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIfsetpos\fR\^(\|)", +.IR "\fIftell\fR\^(\|)", +.IR "\fIfwrite\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIgetc_unlocked\fR\^(\|)", +.IR "\fIgetdelim\fR\^(\|)", +.IR "\fIgetopt\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIpclose\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputchar\fR\^(\|)", +.IR "\fIputs\fR\^(\|)", +.IR "\fIremove\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)", +.IR "\fIsetvbuf\fR\^(\|)", +.IR "\fIstdin\fR\^", +.IR "\fIsystem\fR\^(\|)", +.IR "\fItempnam\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fItmpnam\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)", +.IR "\fIvfprintf\fR\^(\|)", +.IR "\fIvfscanf\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/stdlib.h.0p b/man-pages-posix-2013-a/man0p/stdlib.h.0p new file mode 100644 index 0000000..8558574 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/stdlib.h.0p @@ -0,0 +1,260 @@ +'\" et +.TH stdlib.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stdlib.h +\(em standard library definitions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions: +.IP EXIT_FAILURE 12 +Unsuccessful termination for +\fIexit\fR(); +evaluates to a non-zero value. +.IP EXIT_SUCCESS 12 +Successful termination for +\fIexit\fR(); +evaluates to 0. +.IP {RAND_MAX} 12 +Maximum value returned by +\fIrand\fR(); +at least 32\|767. +.P +The +.IR +header shall define the following macro which shall expand to a +positive integer expression with type +.BR size_t : +.IP {MB_CUR_MAX} 12 +Maximum number of bytes in a character specified by the current +locale (category +.IR LC_CTYPE ). +.P +The +.IR +header shall define NULL as described in +.IR . +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBdiv_t\fP" 12 +Structure type returned by the +\fIdiv\fR() +function. +.IP "\fBldiv_t\fP" 12 +Structure type returned by the +\fIldiv\fR() +function. +.IP "\fBlldiv_t\fP" 12 +Structure type returned by the +\fIlldiv\fR() +function. +.IP "\fBsize_t\fP" 12 +As described in +.IR . +.IP "\fBwchar_t\fP" 12 +As described in +.IR . +.P +In addition, the +.IR +header shall define the following symbolic constants and macros +as described in +.IR : +.P +.nf +WEXITSTATUS +WIFEXITED +WIFSIGNALED +WIFSTOPPED +WNOHANG +WSTOPSIG +WTERMSIG +WUNTRACED +.fi +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void _Exit(int); +long a64l(const char *); +void abort(void); +int abs(int); +int atexit(void (*)(void)); +double atof(const char *); +int atoi(const char *); +long atol(const char *); +long long atoll(const char *); +void *bsearch(const void *, const void *, size_t, size_t, + int (*)(const void *, const void *)); +void *calloc(size_t, size_t); +div_t div(int, int); +double drand48(void); +double erand48(unsigned short [3]); +void exit(int); +void free(void *); +char *getenv(const char *); +int getsubopt(char **, char *const *, char **); +int grantpt(int); +char *initstate(unsigned, char *, size_t); +long jrand48(unsigned short [3]); +char *l64a(long); +long labs(long); +void lcong48(unsigned short [7]); +ldiv_t ldiv(long, long); +long long llabs(long long); +lldiv_t lldiv(long long, long long); +long lrand48(void); +void *malloc(size_t); +int mblen(const char *, size_t); +size_t mbstowcs(wchar_t *restrict, const char *restrict, size_t); +int mbtowc(wchar_t *restrict, const char *restrict, size_t); +char *mkdtemp(char *); +int mkstemp(char *); +long mrand48(void); +long nrand48(unsigned short [3]); +int posix_memalign(void **, size_t, size_t); +int posix_openpt(int); +char *ptsname(int); +int putenv(char *); +void qsort(void *, size_t, size_t, int (*)(const void *, + const void *)); +int rand(void); +int rand_r(unsigned *); +long random(void); +void *realloc(void *, size_t); +char *realpath(const char *restrict, char *restrict); +unsigned short *seed48(unsigned short [3]); +int setenv(const char *, const char *, int); +void setkey(const char *); +char *setstate(char *); +void srand(unsigned); +void srand48(long); +void srandom(unsigned); +double strtod(const char *restrict, char **restrict); +float strtof(const char *restrict, char **restrict); +long strtol(const char *restrict, char **restrict, int); +long double strtold(const char *restrict, char **restrict); +long long strtoll(const char *restrict, char **restrict, int); +unsigned long strtoul(const char *restrict, char **restrict, int); +unsigned long long + strtoull(const char *restrict, char **restrict, int); +int system(const char *); +int unlockpt(int); +int unsetenv(const char *); +size_t wcstombs(char *restrict, const wchar_t *restrict, size_t); +int wctomb(char *, wchar_t); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR , +.IR , +.IR , +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fI_Exit\fR\^(\|)", +.IR "\fIa64l\fR\^(\|)", +.IR "\fIabort\fR\^(\|)", +.IR "\fIabs\fR\^(\|)", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIatof\fR\^(\|)", +.IR "\fIatoi\fR\^(\|)", +.IR "\fIatol\fR\^(\|)", +.IR "\fIbsearch\fR\^(\|)", +.IR "\fIcalloc\fR\^(\|)", +.IR "\fIdiv\fR\^(\|)", +.IR "\fIdrand48\fR\^(\|)", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIgetsubopt\fR\^(\|)", +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIinitstate\fR\^(\|)", +.IR "\fIlabs\fR\^(\|)", +.IR "\fIldiv\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fImblen\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fIposix_memalign\fR\^(\|)", +.IR "\fIposix_openpt\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIqsort\fR\^(\|)", +.IR "\fIrand\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)", +.IR "\fIrealpath\fR\^(\|)", +.IR "\fIsetenv\fR\^(\|)", +.IR "\fIsetkey\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIstrtol\fR\^(\|)", +.IR "\fIstrtoul\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)", +.IR "\fIunsetenv\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/string.h.0p b/man-pages-posix-2013-a/man0p/string.h.0p new file mode 100644 index 0000000..a178bc8 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/string.h.0p @@ -0,0 +1,146 @@ +'\" et +.TH string.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +string.h +\(em string operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define NULL and +.BR size_t +as described in +.IR . +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +void *memccpy(void *restrict, const void *restrict, int, size_t); +void *memchr(const void *, int, size_t); +int memcmp(const void *, const void *, size_t); +void *memcpy(void *restrict, const void *restrict, size_t); +void *memmove(void *, const void *, size_t); +void *memset(void *, int, size_t); +char *stpcpy(char *restrict, const char *restrict); +char *stpncpy(char *restrict, const char *restrict, size_t); +char *strcat(char *restrict, const char *restrict); +char *strchr(const char *, int); +int strcmp(const char *, const char *); +int strcoll(const char *, const char *); +int strcoll_l(const char *, const char *, locale_t); +char *strcpy(char *restrict, const char *restrict); +size_t strcspn(const char *, const char *); +char *strdup(const char *); +char *strerror(int); +char *strerror_l(int, locale_t); +int strerror_r(int, char *, size_t); +size_t strlen(const char *); +char *strncat(char *restrict, const char *restrict, size_t); +int strncmp(const char *, const char *, size_t); +char *strncpy(char *restrict, const char *restrict, size_t); +char *strndup(const char *, size_t); +size_t strnlen(const char *, size_t); +char *strpbrk(const char *, const char *); +char *strrchr(const char *, int); +char *strsignal(int); +size_t strspn(const char *, const char *); +char *strstr(const char *, const char *); +char *strtok(char *restrict, const char *restrict); +char *strtok_r(char *restrict, const char *restrict, char **restrict); +size_t strxfrm(char *restrict, const char *restrict, size_t); +size_t strxfrm_l(char *restrict, const char *restrict, + size_t, locale_t); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fImemccpy\fR\^(\|)", +.IR "\fImemchr\fR\^(\|)", +.IR "\fImemcmp\fR\^(\|)", +.IR "\fImemcpy\fR\^(\|)", +.IR "\fImemmove\fR\^(\|)", +.IR "\fImemset\fR\^(\|)", +.IR "\fIstrcat\fR\^(\|)", +.IR "\fIstrchr\fR\^(\|)", +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)", +.IR "\fIstrcpy\fR\^(\|)", +.IR "\fIstrcspn\fR\^(\|)", +.IR "\fIstrdup\fR\^(\|)", +.IR "\fIstrerror\fR\^(\|)", +.IR "\fIstrlen\fR\^(\|)", +.IR "\fIstrncat\fR\^(\|)", +.IR "\fIstrncmp\fR\^(\|)", +.IR "\fIstrncpy\fR\^(\|)", +.IR "\fIstrpbrk\fR\^(\|)", +.IR "\fIstrrchr\fR\^(\|)", +.IR "\fIstrsignal\fR\^(\|)", +.IR "\fIstrspn\fR\^(\|)", +.IR "\fIstrstr\fR\^(\|)", +.IR "\fIstrtok\fR\^(\|)", +.IR "\fIstrxfrm\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/strings.h.0p b/man-pages-posix-2013-a/man0p/strings.h.0p new file mode 100644 index 0000000..f1f114c --- /dev/null +++ b/man-pages-posix-2013-a/man0p/strings.h.0p @@ -0,0 +1,78 @@ +'\" et +.TH strings.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strings.h +\(em string operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +int ffs(int); +int strcasecmp(const char *, const char *); +int strcasecmp_l(const char *, const char *, locale_t); +int strncasecmp(const char *, const char *, size_t); +int strncasecmp_l(const char *, const char *, size_t, locale_t); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIffs\fR\^(\|)", +.IR "\fIstrcasecmp\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/stropts.h.0p b/man-pages-posix-2013-a/man0p/stropts.h.0p new file mode 100644 index 0000000..814bfb1 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/stropts.h.0p @@ -0,0 +1,433 @@ +'\" et +.TH stropts.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stropts.h +\(em STREAMS interface (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR bandinfo +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int bi_flag \fRFlushing type.\fR +unsigned char bi_pri \fRPriority band.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strpeek +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct strbuf ctlbuf \fRThe control portion of the message.\fR +struct strbuf databuf \fRThe data portion of the message.\fR +t_uscalar_t flags \fRRS_HIPRI or 0.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strbuf +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *buf \fRPointer to buffer.\fP +int len \fRLength of data.\fP +int maxlen \fRMaximum buffer length.\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strfdinsert +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct strbuf ctlbuf \fRThe control portion of the message.\fR +struct strbuf databuf \fRThe data portion of the message.\fR +int fildes \fRFile descriptor of the other STREAM.\fR +t_uscalar_t flags \fRRS_HIPRI or 0.\fR +int offset \fRRelative location of the stored value.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strioctl +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int ic_cmd \fIioctl\fR(\|) command.\fR +char *ic_dp \fRPointer to buffer.\fR +int ic_len \fRLength of data.\fR +int ic_timout \fRTimeout for response.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strrecvfd +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int fd \fRReceived file descriptor.\fR +gid_t gid \fRGID of sender.\fR +uid_t uid \fRUID of sender.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR uid_t +and +.BR gid_t +types through +.BR typedef , +as described in +.IR . +.P +The +.IR +header shall define the +.BR t_scalar_t +and +.BR t_uscalar_t +types, respectively, as signed and unsigned opaque types of equal +length of at least 32 bits. +.P +The +.IR +header shall define the +.BR str_list +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct str_mlist *sl_modlist \fRSTREAMS module names.\fR +int sl_nmods \fRNumber of STREAMS module names.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR str_mlist +structure, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +char l_name[FMNAMESZ+1] \fRA STREAMS module name.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define at least the following symbolic constants for use +as the +.IR request +argument to +\fIioctl\fR(): +.IP I_ATMARK 12 +Is the top message ``marked''? +.IP I_CANPUT 12 +Is a band writable? +.IP I_CKBAND 12 +See if any messages exist in a band. +.IP I_FDINSERT 12 +Send implementation-defined information about another STREAM. +.IP I_FIND 12 +Look for a STREAMS module. +.IP I_FLUSH 12 +Flush a STREAM. +.IP I_FLUSHBAND 12 +Flush one band of a STREAM. +.IP I_GETBAND 12 +Get the band of the top message on a STREAM. +.IP I_GETCLTIME 12 +Get close time delay. +.IP I_GETSIG 12 +Retrieve current notification signals. +.IP I_GRDOPT 12 +Get the read mode. +.IP I_GWROPT 12 +Get the write mode. +.IP I_LINK 12 +Connect two STREAMs. +.IP I_LIST 12 +Get all the module names on a STREAM. +.IP I_LOOK 12 +Get the top module name. +.IP I_NREAD 12 +Size the top message. +.IP I_PEEK 12 +Peek at the top message on a STREAM. +.IP I_PLINK 12 +Persistently connect two STREAMs. +.IP I_POP 12 +Pop a STREAMS module. +.IP I_PUNLINK 12 +Dismantle a persistent STREAMS link. +.IP I_PUSH 12 +Push a STREAMS module. +.IP I_RECVFD 12 +Get a file descriptor sent via I_SENDFD. +.IP I_SENDFD 12 +Pass a file descriptor through a STREAMS pipe. +.IP I_SETCLTIME 12 +Set close time delay. +.IP I_SETSIG 12 +Ask for notification signals. +.IP I_SRDOPT 12 +Set the read mode. +.IP I_STR 12 +Send a STREAMS +\fIioctl\fR(). +.IP I_SWROPT 12 +Set the write mode. +.IP I_UNLINK 12 +Disconnect two STREAMs. +.P +The +.IR +header shall define at least the following symbolic constant for use +with I_LOOK: +.IP FMNAMESZ 12 +The minimum size in bytes of the buffer referred to by the +.IR arg +argument. +.P +The +.IR +header shall define at least the following symbolic constants for use +with I_FLUSH: +.IP FLUSHR 12 +Flush read queues. +.IP FLUSHRW 12 +Flush read and write queues. +.IP FLUSHW 12 +Flush write queues. +.P +The +.IR +header shall define at least the following symbolic constants for use +with I_SETSIG: +.IP S_BANDURG 12 +When used in conjunction with S_RDBAND, SIGURG is generated instead of +SIGPOLL when a priority message reaches the front of the STREAM head +read queue. +.IP S_ERROR 12 +Notification of an error condition reaches the STREAM head. +.IP S_HANGUP 12 +Notification of a hangup reaches the STREAM head. +.IP S_HIPRI 12 +A high-priority message is present on a STREAM head read queue. +.IP S_INPUT 12 +A message, other than a high-priority message, has arrived at the head +of a STREAM head read queue. +.IP S_MSG 12 +A STREAMS signal message that contains the SIGPOLL signal reaches the +front of the STREAM head read queue. +.IP S_OUTPUT 12 +The write queue for normal data (priority band 0) just below the STREAM +head is no longer full. This notifies the process that there is room +on the queue for sending (or writing) normal data downstream. +.IP S_RDBAND 12 +A message with a non-zero priority band has arrived at the head of a +STREAM head read queue. +.IP S_RDNORM 12 +A normal (priority band set to 0) message has arrived at the head of a +STREAM head read queue. +.IP S_WRBAND 12 +The write queue for a non-zero priority band just below the STREAM head +is no longer full. +.IP S_WRNORM 12 +Equivalent to S_OUTPUT. +.P +The +.IR +header shall define at least the following symbolic constant for use +with I_PEEK: +.IP RS_HIPRI 12 +Only look for high-priority messages. +.P +The +.IR +header shall define at least the following symbolic constants for use +with I_SRDOPT: +.IP RMSGD 12 +Message-discard mode. +.IP RMSGN 12 +Message-non-discard mode. +.IP RNORM 12 +Byte-STREAM mode, the default. +.IP RPROTDAT 12 +Deliver the control part of a message as data when a process issues a +\fIread\fR(). +.IP RPROTDIS 12 +Discard the control part of a message, delivering any data part, when a +process issues a +\fIread\fR(). +.IP RPROTNORM 12 +Fail +\fIread\fR() +with +.BR [EBADMSG] +if a message containing a control part is at the front of the STREAM +head read queue. +.P +The +.IR +header shall define at least the following symbolic constant for use +with I_SWOPT: +.IP SNDZERO 12 +Send a zero-length message downstream when a +\fIwrite\fR() +of 0 bytes occurs. +.P +The +.IR +header shall define at least the following symbolic constants for use +with I_ATMARK: +.IP ANYMARK 12 +Check if the message is marked. +.IP LASTMARK 12 +Check if the message is the last one marked on the queue. +.P +The +.IR +header shall define at least the following symbolic constant for use +with I_UNLINK: +.IP MUXID_ALL 12 +Unlink all STREAMs linked to the STREAM associated with +.IR fildes . +.P +The +.IR +header shall define the following symbolic constants for +\fIgetmsg\fR(), +\fIgetpmsg\fR(), +\fIputmsg\fR(), +and +\fIputpmsg\fR(): +.IP MORECTL 12 +More control information is left in message. +.IP MOREDATA 12 +More data is left in message. +.IP MSG_ANY 12 +Receive any message. +.IP MSG_BAND 12 +Receive message from specified band. +.IP MSG_HIPRI 12 +Send/receive high-priority message. +.P +The +.IR +header may make visible all of the symbols from +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int fattach(int, const char *); +int fdetach(const char *); +int getmsg(int, struct strbuf *restrict, struct strbuf *restrict, + int *restrict); +int getpmsg(int, struct strbuf *restrict, struct strbuf *restrict, + int *restrict, int *restrict); +int ioctl(int, int, ...); +int isastream(int); +int putmsg(int, const struct strbuf *, const struct strbuf *, int); +int putpmsg(int, const struct strbuf *, const struct strbuf *, int, + int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIclose\fR\^(\|)", +.IR "\fIfattach\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfdetach\fR\^(\|)", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIisastream\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_ipc.h.0p b/man-pages-posix-2013-a/man0p/sys_ipc.h.0p new file mode 100644 index 0000000..6b8f259 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_ipc.h.0p @@ -0,0 +1,120 @@ +'\" et +.TH sys_ipc.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/ipc.h +\(em XSI interprocess communication access structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header is used by three mechanisms for XSI interprocess communication +(IPC): +messages, semaphores, and shared memory. All use a common structure +type, +.BR ipc_perm , +to pass information used in determining permission to perform an IPC +operation. +.P +The +.IR +header shall define the +.BR ipc_perm +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +uid_t uid \fROwner's user ID.\fR +gid_t gid \fROwner's group ID.\fR +uid_t cuid \fRCreator's user ID.\fR +gid_t cgid \fRCreator's group ID.\fR +mode_t mode \fRRead/write permission.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR uid_t , +.BR gid_t , +.BR mode_t , +and +.BR key_t +types as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants. +.P +Mode bits: +.IP IPC_CREAT 12 +Create entry if key does not exist. +.IP IPC_EXCL 12 +Fail if key exists. +.IP IPC_NOWAIT 12 +Error if request must wait. +.P +Keys: +.IP IPC_PRIVATE 12 +Private key. +.P +Control commands: +.IP IPC_RMID 12 +Remove identifier. +.IP IPC_SET 12 +Set options. +.IP IPC_STAT 12 +Get options. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +key_t ftok(const char *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIftok\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_mman.h.0p b/man-pages-posix-2013-a/man0p/sys_mman.h.0p new file mode 100644 index 0000000..5b3dc15 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_mman.h.0p @@ -0,0 +1,213 @@ +'\" et +.TH sys_mman.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/mman.h +\(em memory management declarations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants for use as +protection options: +.IP PROT_EXEC 14 +Page can be executed. +.IP PROT_NONE 14 +Page cannot be accessed. +.IP PROT_READ 14 +Page can be read. +.IP PROT_WRITE 14 +Page can be written. +.P +The +.IR +header shall define the following symbolic constants for use as +flag options: +.IP MAP_FIXED 14 +Interpret +.IR addr +exactly. +.IP MAP_PRIVATE 14 +Changes are private. +.IP MAP_SHARED 14 +Share changes. +.P +The +.IR +header shall define the following symbolic constants for the +\fImsync\fR() +function: +.IP MS_ASYNC 14 +Perform asynchronous writes. +.IP MS_INVALIDATE 14 +Invalidate mappings. +.IP MS_SYNC 14 +Perform synchronous writes. +.P +The +.IR +header shall define the following symbolic constants for the +\fImlockall\fR() +function: +.IP MCL_CURRENT 14 +Lock currently mapped pages. +.IP MCL_FUTURE 14 +Lock pages that become mapped. +.P +The +.IR +header shall define the symbolic constant MAP_FAILED which shall +have type +.BR "void *" +and shall be used to indicate a failure from the +\fImmap\fR() +function . +.P +If the Advisory Information option is supported, the +.IR +header shall define symbolic constants for the +.IR advice +argument to the +\fIposix_madvise\fR() +function as follows: +.IP POSIX_MADV_DONTNEED 6 +.br +The application expects that it will not access the specified range in +the near future. +.IP POSIX_MADV_NORMAL 6 +.br +The application has no advice to give on its behavior with respect to +the specified range. It is the default characteristic if no advice is +given for a range of memory. +.IP POSIX_MADV_RANDOM 6 +.br +The application expects to access the specified range in a random +order. +.IP POSIX_MADV_SEQUENTIAL 6 +.br +The application expects to access the specified range sequentially from +lower addresses to higher addresses. +.IP POSIX_MADV_WILLNEED 6 +.br +The application expects to access the specified range in the near +future. +.P +The +.IR +header shall define the following symbolic constants for use as +flags for the +\fIposix_typed_mem_open\fR() +function: +.IP POSIX_TYPED_MEM_ALLOCATE 6 +.br +Allocate on +\fImmap\fR(). +.IP POSIX_TYPED_MEM_ALLOCATE_CONTIG 6 +.br +Allocate contiguously on +\fImmap\fR(). +.IP POSIX_TYPED_MEM_MAP_ALLOCATABLE 6 +.br +Map on +\fImmap\fR(), +without affecting allocatability. +.P +The +.IR +header shall define the +.BR mode_t , +.BR off_t , +and +.BR size_t +types as described in +.IR "\fB\fP". +.P +The +.IR +header shall define the +.BR posix_typed_mem_info +structure, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +size_t posix_tmi_length \fRMaximum length which may be allocated\fR + \fRfrom a typed memory object.\fR +.fi \fR +.P +.RE +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int mlock(const void *, size_t); +int mlockall(int); +void *mmap(void *, size_t, int, int, int, off_t); +int mprotect(void *, size_t, int); +int msync(void *, size_t, int); +int munlock(const void *, size_t); +int munlockall(void); +int munmap(void *, size_t); +int posix_madvise(void *, size_t, int); +int posix_mem_offset(const void *restrict, size_t, off_t *restrict, + size_t *restrict, int *restrict); +int posix_typed_mem_get_info(int, struct posix_typed_mem_info *); +int posix_typed_mem_open(const char *, int, int); +int shm_open(const char *, int, mode_t); +int shm_unlink(const char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImlock\fR\^(\|)", +.IR "\fImlockall\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fImprotect\fR\^(\|)", +.IR "\fImsync\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)", +.IR "\fIposix_madvise\fR\^(\|)", +.IR "\fIposix_mem_offset\fR\^(\|)", +.IR "\fIposix_typed_mem_get_info\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_msg.h.0p b/man-pages-posix-2013-a/man0p/sys_msg.h.0p new file mode 100644 index 0000000..032a23d --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_msg.h.0p @@ -0,0 +1,122 @@ +'\" et +.TH sys_msg.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/msg.h +\(em XSI message queue structures +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBmsgqnum_t\fP" 14 +Used for the number of messages in the message queue. +.IP "\fBmsglen_t\fP" 14 +Used for the number of bytes allowed in a message queue. +.P +These types shall be unsigned integer types that are able to store +values at least as large as a type +.BR "unsigned short" . +.P +The +.IR +header shall define the following symbolic constant as a message +operation flag: +.IP MSG_NOERROR 14 +No error if big message. +.P +The +.IR +header shall define the +.BR msqid_ds +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +struct ipc_perm msg_perm \fROperation permission structure.\fR +msgqnum_t msg_qnum \fRNumber of messages currently on queue.\fR +msglen_t msg_qbytes \fRMaximum number of bytes allowed on queue.\fR +pid_t msg_lspid \fRProcess ID of last \fImsgsnd\fP\^(\|).\fR +pid_t msg_lrpid \fRProcess ID of last \fImsgrcv\fP\^(\|).\fR +time_t msg_stime \fRTime of last \fImsgsnd\fP\^(\|).\fR +time_t msg_rtime \fRTime of last \fImsgrcv\fP\^(\|).\fR +time_t msg_ctime \fRTime of last change.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR pid_t , +.BR size_t , +.BR ssize_t , +and +.BR time_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int msgctl(int, int, struct msqid_ds *); +int msgget(key_t, int); +ssize_t msgrcv(int, void *, size_t, long, int); +int msgsnd(int, const void *, size_t, int); +.fi \fR +.P +.RE +.P +In addition, the +.IR +header shall include the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_resource.h.0p b/man-pages-posix-2013-a/man0p/sys_resource.h.0p new file mode 100644 index 0000000..9c30d1e --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_resource.h.0p @@ -0,0 +1,207 @@ +'\" et +.TH sys_resource.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/resource.h +\(em definitions for XSI resource operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants as possible values +of the +.IR which +argument of +\fIgetpriority\fR() +and +\fIsetpriority\fR(): +.IP PRIO_PROCESS 16 +Identifies the +.IR who +argument as a process ID. +.IP PRIO_PGRP 16 +Identifies the +.IR who +argument as a process group ID. +.IP PRIO_USER 16 +Identifies the +.IR who +argument as a user ID. +.P +The +.IR +header shall define the following type through +.BR typedef : +.IP "\fBrlim_t\fR" 16 +Unsigned integer type used for limit values. +.P +The +.IR +header shall define the following symbolic constants, which shall have +values suitable for use in +.BR #if +preprocessing directives: +.IP RLIM_INFINITY 16 +A value of +.BR rlim_t +indicating no limit. +.IP RLIM_SAVED_MAX 16 +A value of type +.BR rlim_t +indicating an unrepresentable saved hard limit. +.IP RLIM_SAVED_CUR 16 +A value of type +.BR rlim_t +indicating an unrepresentable saved soft limit. +.P +On implementations where all resource limits are representable in an +object of type +.BR rlim_t , +RLIM_SAVED_MAX and RLIM_SAVED_CUR need not be distinct from +RLIM_INFINITY. +.P +The +.IR +header shall define the following symbolic constants as possible values +of the +.IR who +parameter of +\fIgetrusage\fR(): +.IP RUSAGE_SELF 16 +Returns information about the current process. +.IP RUSAGE_CHILDREN 16 +Returns information about children of the current process. +.P +The +.IR +header shall define the +.BR rlimit +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +rlim_t rlim_cur \fRThe current (soft) limit.\fR +rlim_t rlim_max \fRThe hard limit.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR rusage +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct timeval ru_utime \fRUser time used.\fR +struct timeval ru_stime \fRSystem time used.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR timeval +structure as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants as possible values +for the +.IR resource +argument of +\fIgetrlimit\fR() +and +\fIsetrlimit\fR(): +.IP RLIMIT_CORE 16 +Limit on size of +.BR core +file. +.IP RLIMIT_CPU 16 +Limit on CPU time per process. +.IP RLIMIT_DATA 16 +Limit on data segment size. +.IP RLIMIT_FSIZE 16 +Limit on file size. +.IP RLIMIT_NOFILE 16 +Limit on number of open files. +.IP RLIMIT_STACK 16 +Limit on stack size. +.IP RLIMIT_AS 16 +Limit on address space size. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int getpriority(int, id_t); +int getrlimit(int, struct rlimit *); +int getrusage(int, struct rusage *); +int setpriority(int, id_t, int); +int setrlimit(int, const struct rlimit *); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR id_t +type through +.BR typedef , +as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetpriority\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIgetrusage\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_select.h.0p b/man-pages-posix-2013-a/man0p/sys_select.h.0p new file mode 100644 index 0000000..af643c8 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_select.h.0p @@ -0,0 +1,144 @@ +'\" et +.TH sys_select.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/select.h +\(em select types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR timeval +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +time_t tv_sec \fRSeconds.\fR +suseconds_t tv_usec \fRMicroseconds.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR time_t +and +.BR suseconds_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR sigset_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR timespec +structure as described in +.IR . +.P +The +.IR +header shall define the +.BR fd_set +type as a structure. +.P +The +.IR +header shall define the following symbolic constant, which shall have +a value suitable for use in +.BR #if +preprocessing directives: +.IP FD_SETSIZE 12 +Maximum number of file descriptors in an +.BR fd_set +structure. +.P +The following shall be declared as functions, defined as macros, or +both. If functions are declared, function prototypes shall be +provided. +.sp +.RS 4 +.nf +\fB +void FD_CLR(int, fd_set *); +int FD_ISSET(int, fd_set *); +void FD_SET(int, fd_set *); +void FD_ZERO(fd_set *); +.fi \fR +.P +.RE +.P +If implemented as macros, these may evaluate their arguments more than +once, so applications should ensure that the arguments they supply are +never expressions with side-effects. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int pselect(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + const struct timespec *restrict, const sigset_t *restrict); +int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + struct timeval *restrict); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the headers +.IR +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIpselect\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_sem.h.0p b/man-pages-posix-2013-a/man0p/sys_sem.h.0p new file mode 100644 index 0000000..678771a --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_sem.h.0p @@ -0,0 +1,162 @@ +'\" et +.TH sys_sem.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/sem.h +\(em XSI semaphore facility +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constant for use as a +semaphore operation flag: +.IP SEM_UNDO 12 +Set up adjust on exit entry. +.P +The +.IR +header shall define the following symbolic constants for use as +commands for the +\fIsemctl\fR() +function: +.IP GETNCNT 12 +Get +.IR semncnt . +.IP GETPID 12 +Get +.IR sempid . +.IP GETVAL 12 +Get +.IR semval . +.IP GETALL 12 +Get all cases of +.IR semval . +.IP GETZCNT 12 +Get +.IR semzcnt . +.IP SETVAL 12 +Set +.IR semval . +.IP SETALL 12 +Set all cases of +.IR semval . +.P +The +.IR +header shall define the +.BR semid_ds +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +struct ipc_perm sem_perm \fROperation permission structure.\fR +unsigned short sem_nsems \fRNumber of semaphores in set.\fR +time_t sem_otime \fRLast \fIsemop\fP\^(\|) time.\fR +time_t sem_ctime \fRLast time changed by \fIsemctl\fP\^(\|).\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR pid_t , +.BR size_t , +and +.BR time_t +types as described in +.IR . +.P +A semaphore shall be represented by an anonymous structure, +which shall include the following members: +.sp +.RS 4 +.nf +\fB +unsigned short semval \fRSemaphore value.\fR +pid_t sempid \fRProcess ID of last operation.\fR +unsigned short semncnt \fRNumber of processes waiting for \fIsemval\fR + \fRto become greater than current value.\fR +unsigned short semzcnt \fRNumber of processes waiting for \fIsemval\fR + \fRto become 0.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR sembuf +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +unsigned short sem_num \fRSemaphore number.\fR +short sem_op \fRSemaphore operation.\fR +short sem_flg \fROperation flags.\fR +.fi \fR +.P +.RE +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int semctl(int, int, int, ...); +int semget(key_t, int, int); +int semop(int, struct sembuf *, size_t); +.fi \fR +.P +.RE +.P +In addition, the +.IR +header shall include the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_shm.h.0p b/man-pages-posix-2013-a/man0p/sys_shm.h.0p new file mode 100644 index 0000000..fcb74a8 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_shm.h.0p @@ -0,0 +1,120 @@ +'\" et +.TH sys_shm.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/shm.h +\(em XSI shared memory facility +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants: +.IP SHM_RDONLY 12 +Attach read-only (else read-write). +.IP SHM_RND 12 +Round attach address to SHMLBA. +.IP SHMLBA 12 +Segment low boundary address multiple. +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBshmatt_t\fP" 12 +Unsigned integer used for the number of current attaches that must be +able to store values at least as large as a type +.BR "unsigned short" . +.P +The +.IR +header shall define the +.BR shmid_ds +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +struct ipc_perm shm_perm \fROperation permission structure.\fR +size_t shm_segsz \fRSize of segment in bytes.\fR +pid_t shm_lpid \fRProcess ID of last shared memory operation.\fR +pid_t shm_cpid \fRProcess ID of creator.\fR +shmatt_t shm_nattch \fRNumber of current attaches.\fR +time_t shm_atime \fRTime of last \fIshmat\fP\^(\|).\fR +time_t shm_dtime \fRTime of last \fIshmdt\fP\^(\|).\fR +time_t shm_ctime \fRTime of last change by \fIshmctl\fP\^(\|).\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR pid_t , +.BR size_t , +and +.BR time_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void *shmat(int, const void *, int); +int shmctl(int, int, struct shmid_ds *); +int shmdt(const void *); +int shmget(key_t, size_t, int); +.fi \fR +.P +.RE +.P +In addition, the +.IR +header shall include the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_socket.h.0p b/man-pages-posix-2013-a/man0p/sys_socket.h.0p new file mode 100644 index 0000000..1f0f18f --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_socket.h.0p @@ -0,0 +1,563 @@ +'\" et +.TH sys_socket.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/socket.h +\(em main sockets header +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR socklen_t +type, which is an integer type of width of at least 32 bits; +see APPLICATION USAGE. +.P +The +.IR +header shall define the +.BR sa_family_t +unsigned integer type. +.P +The +.IR +header shall define the +.BR sockaddr +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t sa_family \fRAddress family.\fR +char sa_data[] \fRSocket address (variable-length data).\fR +.fi \fR +.P +.RE +.P +The +.BR sockaddr +structure is used to define a socket address which is used +in the +\fIbind\fR(), +\fIconnect\fR(), +\fIgetpeername\fR(), +\fIgetsockname\fR(), +\fIrecvfrom\fR(), +and +\fIsendto\fR() +functions. +.P +The +.IR +header shall define the +.BR sockaddr_storage +structure, which shall be: +.IP " *" 4 +Large enough to accommodate all supported protocol-specific address +structures +.IP " *" 4 +Aligned at an appropriate boundary so that pointers to it can be cast +as pointers to protocol-specific address structures and used to access +the fields of those structures without alignment problems +.P +The +.BR sockaddr_storage +structure shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t ss_family +.fi \fR +.P +.RE +.P +When a pointer to a +.BR sockaddr_storage +structure is cast as a pointer to a +.BR sockaddr +structure, the +.IR ss_family +field of the +.BR sockaddr_storage +structure shall map onto the +.IR sa_family +field of the +.BR sockaddr +structure. When a pointer to a +.BR sockaddr_storage +structure is cast as a pointer to a protocol-specific address structure, +the +.IR ss_family +field shall map onto +a field of that structure that is of type +.BR sa_family_t +and that identifies the protocol's address family. +.P +The +.IR +header shall define the +.BR msghdr +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void *msg_name \fROptional address.\fR +socklen_t msg_namelen \fRSize of address.\fR +struct iovec *msg_iov \fRScatter/gather array.\fR +int msg_iovlen \fRMembers in \fImsg_iov\fR.\fR +void *msg_control \fRAncillary data; see below.\fR +socklen_t msg_controllen \fRAncillary data buffer \fIlen\fR.\fR +int msg_flags \fRFlags on received message.\fR +.fi \fR +.P +.RE +.P +The +.BR msghdr +structure is used to minimize the number of directly supplied +parameters to the +\fIrecvmsg\fR() +and +\fIsendmsg\fR() +functions. This structure is used as a +.IR value \(hy\c +.IR result +parameter in the +\fIrecvmsg\fR() +function and +.IR value +only for the +\fIsendmsg\fR() +function. +.P +The +.IR +header shall define the +.BR iovec +structure as described in +.IR . +.P +The +.IR +header shall define the +.BR cmsghdr +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +socklen_t cmsg_len \fRData byte count, including the \fBcmsghdr\fR.\fR +int cmsg_level \fROriginating protocol.\fR +int cmsg_type \fRProtocol-specific type.\fR +.fi \fR +.P +.RE +.P +The +.BR cmsghdr +structure is used for storage of ancillary data object information. +.P +Ancillary data consists of a sequence of pairs, each consisting of a +.BR cmsghdr +structure followed by a data array. The data array contains the +ancillary data message, and the +.BR cmsghdr +structure contains descriptive information that allows an application +to correctly parse the data. +.P +The values for +.IR cmsg_level +shall be legal values for the +.IR level +argument to the +\fIgetsockopt\fR() +and +\fIsetsockopt\fR() +functions. The system documentation shall specify the +.IR cmsg_type +definitions for the supported protocols. +.P +Ancillary data is also possible at the socket level. The +.IR +header shall define the following symbolic constant for use as the +.IR cmsg_type +value when +.IR cmsg_level +is SOL_SOCKET: +.IP SCM_RIGHTS 14 +Indicates that the data array contains the access rights to be sent or +received. +.P +The +.IR +header shall define the following macros to gain access to the data +arrays in the ancillary data associated with a message header: +.IP "CMSG_DATA(\fIcmsg\fP)" 6 +.br +If the argument is a pointer to a +.BR cmsghdr +structure, this macro shall return an unsigned character pointer +to the data array associated with the +.BR cmsghdr +structure. +.IP "CMSG_NXTHDR(\fImhdr,cmsg\fP)" 6 +.br +If the first argument is a pointer to a +.BR msghdr +structure and the second argument is a pointer to a +.BR cmsghdr +structure in the ancillary data pointed to by the +.IR msg_control +field of that +.BR msghdr +structure, this macro shall return a pointer to the next +.BR cmsghdr +structure, or a null pointer if this structure is the last +.BR cmsghdr +in the ancillary data. +.IP "CMSG_FIRSTHDR(\fImhdr\fP)" 6 +.br +If the argument is a pointer to a +.BR msghdr +structure, this macro shall return a pointer to the first +.BR cmsghdr +structure in the ancillary data associated with this +.BR msghdr +structure, or a null pointer if there is no ancillary data associated +with the +.BR msghdr +structure. +.P +The +.IR +header shall define the +.BR linger +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int l_onoff \fRIndicates whether linger option is enabled.\fR +int l_linger \fRLinger time, in seconds.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants with distinct values: +.IP SOCK_DGRAM 14 +Datagram socket. +.IP SOCK_RAW 14 +Raw Protocol Interface. +.IP SOCK_SEQPACKET 14 +Sequenced-packet socket. +.IP SOCK_STREAM 14 +Byte-stream socket. +.P +The +.IR +header shall define the following symbolic constant for use as the +.IR level +argument of +\fIsetsockopt\fR() +and +\fIgetsockopt\fR(). +.IP SOL_SOCKET 14 +Options to be accessed at socket level, not protocol level. +.P +The +.IR +header shall define the following symbolic constants with distinct values +for use as the +.IR option_name +argument in +\fIgetsockopt\fR() +or +\fIsetsockopt\fR() +calls (see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.10.16" ", " "Use of Options"): +.IP SO_ACCEPTCONN 14 +Socket is accepting connections. +.IP SO_BROADCAST 14 +Transmission of broadcast messages is supported. +.IP SO_DEBUG 14 +Debugging information is being recorded. +.IP SO_DONTROUTE 14 +Bypass normal routing. +.IP SO_ERROR 14 +Socket error status. +.IP SO_KEEPALIVE 14 +Connections are kept alive with periodic messages. +.IP SO_LINGER 14 +Socket lingers on close. +.IP SO_OOBINLINE 14 +Out-of-band data is transmitted in line. +.IP SO_RCVBUF 14 +Receive buffer size. +.IP SO_RCVLOWAT 14 +Receive ``low water mark''. +.IP SO_RCVTIMEO 14 +Receive timeout. +.IP SO_REUSEADDR 14 +Reuse of local addresses is supported. +.IP SO_SNDBUF 14 +Send buffer size. +.IP SO_SNDLOWAT 14 +Send ``low water mark''. +.IP SO_SNDTIMEO 14 +Send timeout. +.IP SO_TYPE 14 +Socket type. +.P +The +.IR +header shall define the following symbolic constant for use as the maximum +.IR backlog +queue length which may be specified by the +.IR backlog +field of the +\fIlisten\fR() +function: +.IP SOMAXCONN 14 +The maximum +.IR backlog +queue length. +.P +The +.IR +header shall define the following symbolic constants with distinct values +for use as the valid values for the +.IR msg_flags +field in the +.BR msghdr +structure, or the +.IR flags +parameter in +\fIrecv\fR(), +\fIrecvfrom\fR(), +\fIrecvmsg\fR(), +\fIsend\fR(), +\fIsendmsg\fR(), +or +\fIsendto\fR() +calls: +.IP MSG_CTRUNC 14 +Control data truncated. +.IP MSG_DONTROUTE 14 +Send without using routing tables. +.IP MSG_EOR 14 +Terminates a record (if supported by the protocol). +.IP MSG_OOB 14 +Out-of-band data. +.IP MSG_NOSIGNAL 14 +No SIGPIPE generated when an attempt to send is made on a +stream-oriented socket that is no longer connected. +.IP MSG_PEEK 14 +Leave received data in queue. +.IP MSG_TRUNC 14 +Normal data truncated. +.IP MSG_WAITALL 14 +Attempt to fill the read buffer. +.P +The +.IR +header shall define the following symbolic constants with distinct values: +.IP AF_INET 14 +Internet domain sockets for use with IPv4 addresses. +.IP AF_INET6 14 +Internet domain sockets for use with IPv6 addresses. +.IP AF_UNIX 14 +UNIX domain sockets. +.IP AF_UNSPEC 14 +Unspecified. +.P +The +.IR +header shall define the following symbolic constants with distinct values: +.IP SHUT_RD 14 +Disables further receive operations. +.IP SHUT_RDWR 14 +Disables further send and receive operations. +.IP SHUT_WR 14 +Disables further send operations. +.P +The +.IR +header shall define the +.BR size_t +and +.BR ssize_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int accept(int, struct sockaddr *restrict, socklen_t *restrict); +int bind(int, const struct sockaddr *, socklen_t); +int connect(int, const struct sockaddr *, socklen_t); +int getpeername(int, struct sockaddr *restrict, socklen_t *restrict); +int getsockname(int, struct sockaddr *restrict, socklen_t *restrict); +int getsockopt(int, int, int, void *restrict, socklen_t *restrict); +int listen(int, int); +ssize_t recv(int, void *, size_t, int); +ssize_t recvfrom(int, void *restrict, size_t, int, + struct sockaddr *restrict, socklen_t *restrict); +ssize_t recvmsg(int, struct msghdr *, int); +ssize_t send(int, const void *, size_t, int); +ssize_t sendmsg(int, const struct msghdr *, int); +ssize_t sendto(int, const void *, size_t, int, const struct sockaddr *, + socklen_t); +int setsockopt(int, int, int, const void *, socklen_t); +int shutdown(int, int); +int sockatmark(int); +int socket(int, int, int); +int socketpair(int, int, int, int [2]); +.fi \fR +.P +.RE +.P +Inclusion of +.IR +may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +To forestall portability problems, it is recommended that applications +not use values larger than 2\u\s-331\s+3\d \(mi1 for the +.BR socklen_t +type. +.P +The +.BR sockaddr_storage +structure solves the problem of declaring storage for automatic +variables which is both large enough and aligned enough for storing the +socket address data structure of any family. For example, code with a +file descriptor and without the context of the address family can pass +a pointer to a variable of this type, where a pointer to a socket +address structure is expected in calls such as +\fIgetpeername\fR(), +and determine the address family by accessing the received content +after the call. +.P +The example below illustrates a data structure which aligns on a 64-bit +boundary. An implementation-defined field +.IR _ss_align +following +.IR _ss_pad1 +is used to force a 64-bit alignment which covers proper alignment good +enough for needs of at least +.BR sockaddr_in6 +(IPv6) and +.BR sockaddr_in +(IPv4) address data structures. The size of padding field +.IR _ss_pad1 +depends on the chosen alignment boundary. The size of padding field +.IR _ss_pad2 +depends on the value of overall size chosen for the total size of the +structure. This size and alignment are represented in the above example +by implementation-defined (not required) constants _SS_MAXSIZE +(chosen value 128) and _SS_ALIGNMENT (with chosen value 8). Constants +_SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 112) are +also for illustration and not required. The implementation-defined +definitions and structure field names above start with an + +to denote implementation private name space. Portable code is not expected +to access or reference those fields or constants. +.sp +.RS 4 +.nf +\fB +/* + * Desired design of maximum size and alignment. + */ +#define _SS_MAXSIZE 128 + /* Implementation-defined maximum size. */ +#define _SS_ALIGNSIZE (sizeof(int64_t)) + /* Implementation-defined desired alignment. */ +.P +/* + * Definitions used for sockaddr_storage structure paddings design. + */ +#define _SS_PAD1SIZE (_SS_ALIGNSIZE \(mi sizeof(sa_family_t)) +#define _SS_PAD2SIZE (_SS_MAXSIZE \(mi (sizeof(sa_family_t)+ \e + _SS_PAD1SIZE + _SS_ALIGNSIZE)) +struct sockaddr_storage { + sa_family_t ss_family; /* Address family. */ +/* + * Following fields are implementation-defined. + */ + char _ss_pad1[_SS_PAD1SIZE]; + /* 6-byte pad; this is to make implementation-defined + pad up to alignment field that follows explicit in + the data structure. */ + int64_t _ss_align; /* Field to force desired structure + storage alignment. */ + char _ss_pad2[_SS_PAD2SIZE]; + /* 112-byte pad to achieve desired size, + _SS_MAXSIZE value minus size of ss_family + __ss_pad1, __ss_align fields is 112. */ +}; +.fi \fR +.P +.RE +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetpeername\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIlisten\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsockatmark\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIsocketpair\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_stat.h.0p b/man-pages-posix-2013-a/man0p/sys_stat.h.0p new file mode 100644 index 0000000..d8cabe9 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_stat.h.0p @@ -0,0 +1,406 @@ +'\" et +.TH sys_stat.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/stat.h +\(em data returned by the stat(\|) function +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structure of the data returned by the +\fIfstat\fR(), +\fIlstat\fR(), +and +\fIstat\fR() +functions. +.P +The +.IR +header shall define the +.BR stat +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +dev_t st_dev \fRDevice ID of device containing file.\fR +ino_t st_ino \fRFile serial number.\fR +mode_t st_mode \fRMode of file (see below).\fR +nlink_t st_nlink \fRNumber of hard links to the file.\fR +uid_t st_uid \fRUser ID of file.\fR +gid_t st_gid \fRGroup ID of file.\fR +dev_t st_rdev \fRDevice ID (if file is character or block special).\fR +off_t st_size \fRFor regular files, the file size in bytes.\fR + \fRFor symbolic links, the length in bytes of the\fR + \fRpathname contained in the symbolic link.\fR + \fRFor a shared memory object, the length in bytes.\fR + \fRFor a typed memory object, the length in bytes.\fR + \fRFor other file types, the use of this field is\fR + \fRunspecified.\fR +struct timespec st_atim \fRLast data access timestamp.\fR +struct timespec st_mtim \fRLast data modification timestamp.\fR +struct timespec st_ctim \fRLast file status change timestamp.\fR +blksize_t st_blksize \fRA file system-specific preferred I/O block size\fR + \fRfor this object. In some file system types, this\fR + \fRmay vary from file to file.\fR +blkcnt_t st_blocks \fRNumber of blocks allocated for this object.\fR +.fi \fR +.P +.RE +.P +The +.IR st_ino +and +.IR st_dev +fields taken together uniquely identify the file within the system. +.P +The +.IR +header shall define the +.BR blkcnt_t , +.BR blksize_t , +.BR dev_t , +.BR ino_t , +.BR mode_t , +.BR nlink_t , +.BR uid_t , +.BR gid_t , +.BR off_t , +and +.BR time_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR timespec +structure as described in +.IR . +Times shall be given in seconds since the Epoch. +.P +Which structure members have meaningful values depends on the +type of file. For further information, see the descriptions of +\fIfstat\fR(), +\fIlstat\fR(), +and +\fIstat\fR() +in the System Interfaces volume of POSIX.1\(hy2008. +.P +For compatibility with earlier versions of this standard, the +.IR st_atime +macro shall be defined with the value +.IR st_atim.tv_sec . +Similarly, +.IR st_ctime +and +.IR st_mtime +shall be defined as macros with the values +.IR st_ctim.tv_sec +and +.IR st_mtim.tv_sec , +respectively. +.br +.P +The +.IR +header shall define the following symbolic constants for the +file types encoded in type +.BR mode_t . +The values shall be suitable for use in +.BR #if +preprocessing directives: +.IP S_IFMT 12 +Type of file. +.RS 12 +.IP S_IFBLK 12 +Block special. +.IP S_IFCHR 12 +Character special. +.IP S_IFIFO 12 +FIFO special. +.IP S_IFREG 12 +Regular. +.IP S_IFDIR 12 +Directory. +.IP S_IFLNK 12 +Symbolic link. +.IP S_IFSOCK 12 +Socket. +.RE +.P +The +.IR +header shall define the following symbolic constants for the file mode +bits encoded in type +.BR mode_t , +with the indicated numeric values. These macros shall expand to an +expression which has a type that allows them to be used, either singly +or OR'ed together, as the third argument to +\fIopen\fR() +without the need for a +.BR mode_t +cast. The values shall be suitable for use in +.BR #if +preprocessing directives. +.TS +center box tab(@); +cB | cB | cB +l | n | l. +Name@Numeric Value@Description +_ +S_IRWXU@0700@Read, write, execute/search by owner. +S_IRUSR@0400@Read permission, owner. +S_IWUSR@0200@Write permission, owner. +S_IXUSR@0100@Execute/search permission, owner. +_ +S_IRWXG@070@Read, write, execute/search by group. +S_IRGRP@040@Read permission, group. +S_IWGRP@020@Write permission, group. +S_IXGRP@010@Execute/search permission, group. +_ +S_IRWXO@07@Read, write, execute/search by others. +S_IROTH@04@Read permission, others. +S_IWOTH@02@Write permission, others. +S_IXOTH@01@Execute/search permission, others. +_ +S_ISUID@04000@Set-user-ID on execution. +S_ISGID@02000@Set-group-ID on execution. +\*!S_ISVTX@01000@On directories, restricted deletion flag.\0\0\0\*? +.TE +.P +The following macros shall be provided to test whether a file is of the +specified type. The value +.IR m +supplied to the macros is the value of +.IR st_mode +from a +.BR stat +structure. The macro shall evaluate to a non-zero value if the test is +true; 0 if the test is false. +.IP "S_ISBLK(\fIm\fP)" 14 +Test for a block special file. +.IP "S_ISCHR(\fIm\fP)" 14 +Test for a character special file. +.IP "S_ISDIR(\fIm\fP)" 14 +Test for a directory. +.IP "S_ISFIFO(\fIm\fP)" 14 +Test for a pipe or FIFO special file. +.IP "S_ISREG(\fIm\fP)" 14 +Test for a regular file. +.IP "S_ISLNK(\fIm\fP)" 14 +Test for a symbolic link. +.IP "S_ISSOCK(\fIm\fP)" 14 +Test for a socket. +.P +The implementation may implement message queues, semaphores, or shared +memory objects as distinct file types. The following macros shall be +provided to test whether a file is of the specified type. The value of +the +.IR buf +argument supplied to the macros is a pointer to a +.BR stat +structure. The macro shall evaluate to a non-zero value if the +specified object is implemented as a distinct file type and the +specified file type is contained in the +.BR stat +structure referenced by +.IR buf . +Otherwise, the macro shall evaluate to zero. +.IP "S_TYPEISMQ(\fIbuf\fP)" 14 +Test for a message queue. +.IP "S_TYPEISSEM(\fIbuf\fP)" 14 +Test for a semaphore. +.IP "S_TYPEISSHM(\fIbuf\fP)" 14 +Test for a shared memory object. +.P +The implementation may implement typed memory objects as distinct +file types, and the following macro shall test whether a file is of the +specified type. The value of the +.IR buf +argument supplied to the macros is a pointer to a +.BR stat +structure. The macro shall evaluate to a non-zero value if the +specified object is implemented as a distinct file type and the +specified file type is contained in the +.BR stat +structure referenced by +.IR buf . +Otherwise, the macro shall evaluate to zero. +.IP "S_TYPEISTMO(\fIbuf\fP)" 14 +Test macro for a typed memory object. +.P +The +.IR +header shall define the following symbolic constants as distinct +integer values outside of the range [0,999\|999\|999], +for use with the +\fIfutimens\fR() +and +\fIutimensat\fR() +functions: +UTIME_NOW +UTIME_OMIT +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int chmod(const char *, mode_t); +int fchmod(int, mode_t); +int fchmodat(int, const char *, mode_t, int); +int fstat(int, struct stat *); +int fstatat(int, const char *restrict, struct stat *restrict, int); +int futimens(int, const struct timespec [2]); +int lstat(const char *restrict, struct stat *restrict); +int mkdir(const char *, mode_t); +int mkdirat(int, const char *, mode_t); +int mkfifo(const char *, mode_t); +int mkfifoat(int, const char *, mode_t); +int mknod(const char *, mode_t, dev_t); +int mknodat(int, const char *, mode_t, dev_t); +int stat(const char *restrict, struct stat *restrict); +mode_t umask(mode_t); +int utimensat(int, const char *, const struct timespec [2], int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Use of the macros is recommended for determining the type of a file. +.SH RATIONALE +A conforming C-language application must include +.IR +for functions that have arguments or return values of type +.BR mode_t , +so that symbolic values for that type can be used. An alternative +would be to require that these constants are also defined by including +.IR . +.P +The S_ISUID and S_ISGID +bits may be cleared on any write, not just on +\fIopen\fR(), +as some historical implementations do. +.P +System calls that update the time entry fields in the +.BR stat +structure must be documented by the implementors. POSIX-conforming +systems should not update the time entry fields for functions listed in +the System Interfaces volume of POSIX.1\(hy2008 unless the standard requires that they do, except in the case +of documented extensions to the standard. +.P +Upon assignment, file timestamps are immediately converted to the +resolution of the file system by truncation (i.e., the recorded time +can be older than the actual time). For example, if the file system +resolution is 1 microsecond, then a conforming +\fIstat\fR() +must always return an +.IR st_mtim.tv_nsec +that is a multiple of 1000. Some older implementations returned +higher-resolution timestamps while the +.IR inode +information was cached, and then spontaneously truncated the +.IR tv_nsec +fields when they were stored to and retrieved from disk, but this behavior +does not conform. +.P +Note that +.IR st_dev +must be unique within a Local Area Network (LAN) in a ``system'' made +up of multiple computers' file systems connected by a LAN. +.P +Networked implementations of a POSIX-conforming system must guarantee +that all files visible within the file tree (including parts of the +tree that may be remotely mounted from other machines on the network) +on each individual processor are uniquely identified by the combination +of the +.IR st_ino +and +.IR st_dev +fields. +.P +The unit for the +.IR st_blocks +member of the +.BR stat +structure is not defined within POSIX.1\(hy2008. In some implementations +it is 512 bytes. It may differ on a file system basis. There is no +correlation between values of the +.IR st_blocks +and +.IR st_blksize , +and the +.IR f_bsize +(from +.IR ) +structure members. +.P +Traditionally, some implementations defined the multiplier for +.IR st_blocks +in +.IR +as the symbol DEV_BSIZE. +.P +Some earlier versions of this standard did not specify values for the +file mode bit macros. The expectation was that some implementors might +choose to use a different encoding for these bits than the traditional +one, and that new applications would use symbolic file modes instead of +numeric. This version of the standard specifies the traditional encoding, +in recognition that nearly 20 years after the first publication of this +standard numeric file modes are still in widespread use by application +developers, and that all conforming implementations still use the +traditional encoding. +.SH "FUTURE DIRECTIONS" +No new S_IFMT symbolic names for the file type values of +.BR mode_t +will be defined by POSIX.1\(hy2008; if new file types are required, they will +only be testable through +.IR S_ISxx (\|) +or +.IR S_TYPEISxxx (\|) +macros instead. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfchmod\fR\^(\|)", +.IR "\fIfstat\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_statvfs.h.0p b/man-pages-posix-2013-a/man0p/sys_statvfs.h.0p new file mode 100644 index 0000000..ca53935 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_statvfs.h.0p @@ -0,0 +1,104 @@ +'\" et +.TH sys_statvfs.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/statvfs.h +\(em VFS File System information structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR statvfs +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +unsigned long f_bsize \fRFile system block size.\fR +unsigned long f_frsize \fRFundamental file system block size.\fR +fsblkcnt_t f_blocks \fRTotal number of blocks on file system in units of \fIf_frsize.\fR +fsblkcnt_t f_bfree \fRTotal number of free blocks.\fR +fsblkcnt_t f_bavail \fRNumber of free blocks available to\fR + \fRnon-privileged process.\fR +fsfilcnt_t f_files \fRTotal number of file serial numbers.\fR +fsfilcnt_t f_ffree \fRTotal number of free file serial numbers.\fR +fsfilcnt_t f_favail \fRNumber of file serial numbers available to\fR + \fRnon-privileged process.\fR +unsigned long f_fsid \fRFile system ID.\fR +unsigned long f_flag \fRBit mask of \fIf_flag\fR values.\fR +unsigned long f_namemax \fRMaximum filename length.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR fsblkcnt_t +and +.BR fsfilcnt_t +types as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants for the +.IR f_flag +member: +.IP ST_RDONLY 12 +Read-only file system. +.IP ST_NOSUID 12 +Does not support the semantics of the ST_ISUID and ST_ISGID file mode +bits. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int fstatvfs(int, struct statvfs *); +int statvfs(const char *restrict, struct statvfs *restrict); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfstatvfs\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_time.h.0p b/man-pages-posix-2013-a/man0p/sys_time.h.0p new file mode 100644 index 0000000..30d38ae --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_time.h.0p @@ -0,0 +1,145 @@ +'\" et +.TH sys_time.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/time.h +\(em time types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR timeval +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +time_t tv_sec \fRSeconds.\fR +suseconds_t tv_usec \fRMicroseconds.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR itimerval +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct timeval it_interval \fRTimer interval.\fR +struct timeval it_value \fRCurrent value.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR time_t +and +.BR suseconds_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR fd_set +type as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants for the +.IR which +argument of +\fIgetitimer\fR() +and +\fIsetitimer\fR(): +.IP ITIMER_REAL 14 +Decrements in real time. +.IP ITIMER_VIRTUAL 14 +Decrements in process virtual time. +.IP ITIMER_PROF 14 +Decrements both in process virtual time and when the system is running +on behalf of the process. +.P +The +.IR +header shall define the following as described in +.IR : +\fIFD_CLR\fR() +\fIFD_ISSET\fR() +\fIFD_SET\fR() +\fIFD_ZERO\fR() +FD_SETSIZE +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int getitimer(int, struct itimerval *); +int gettimeofday(struct timeval *restrict, void *restrict); +int setitimer(int, const struct itimerval *restrict, + struct itimerval *restrict); +int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + struct timeval *restrict); +int utimes(const char *, const struct timeval [2]); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfutimens\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIgettimeofday\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_times.h.0p b/man-pages-posix-2013-a/man0p/sys_times.h.0p new file mode 100644 index 0000000..28367a8 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_times.h.0p @@ -0,0 +1,83 @@ +'\" et +.TH sys_times.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/times.h +\(em file access and modification times structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR tms +structure, which is returned by +\fItimes\fR() +and shall include at least the following members: +.sp +.RS 4 +.nf +\fB +clock_t tms_utime \fRUser CPU time.\fR +clock_t tms_stime \fRSystem CPU time.\fR +clock_t tms_cutime \fRUser CPU time of terminated child processes.\fR +clock_t tms_cstime \fRSystem CPU time of terminated child processes.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR clock_t +type as described in +.IR . +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +clock_t times(struct tms *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fItimes\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_types.h.0p b/man-pages-posix-2013-a/man0p/sys_types.h.0p new file mode 100644 index 0000000..1eb0d65 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_types.h.0p @@ -0,0 +1,241 @@ +'\" et +.TH sys_types.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/types.h +\(em data types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define at least the following types: +.IP "\fBblkcnt_t\fP" 16 +Used for file block counts. +.IP "\fBblksize_t\fP" 16 +Used for block sizes. +.IP "\fBclock_t\fP" 16 +Used for system times in clock ticks or CLOCKS_PER_SEC; see +.IR . +.IP "\fBclockid_t\fP" 16 +Used for clock ID type in the clock and timer functions. +.IP "\fBdev_t\fP" 16 +Used for device IDs. +.IP "\fBfsblkcnt_t\fP" 16 +Used for file system block counts. +.IP "\fBfsfilcnt_t\fP" 16 +Used for file system file counts. +.IP "\fBgid_t\fP" 16 +Used for group IDs. +.IP "\fBid_t\fP" 16 +Used as a general identifier; can be used to contain at least a +.BR pid_t , +.BR uid_t , +or +.BR gid_t . +.IP "\fBino_t\fP" 16 +Used for file serial numbers. +.IP "\fBkey_t\fP" 16 +Used for XSI interprocess communication. +.IP "\fBmode_t\fP" 16 +Used for some file attributes. +.IP "\fBnlink_t\fP" 16 +Used for link counts. +.IP "\fBoff_t\fP" 16 +Used for file sizes. +.IP "\fBpid_t\fP" 16 +Used for process IDs and process group IDs. +.IP "\fBpthread_attr_t\fP" 16 +Used to identify a thread attribute object. +.IP "\fBpthread_barrier_t\fP" 16 +Used to identify a barrier. +.IP "\fBpthread_barrierattr_t\fP" 16 +Used to define a barrier attributes object. +.IP "\fBpthread_cond_t\fP" 16 +Used for condition variables. +.IP "\fBpthread_condattr_t\fP" 16 +Used to identify a condition attribute object. +.IP "\fBpthread_key_t\fP" 16 +Used for thread-specific data keys. +.IP "\fBpthread_mutex_t\fP" 16 +Used for mutexes. +.IP "\fBpthread_mutexattr_t\fP" 16 +Used to identify a mutex attribute object. +.IP "\fBpthread_once_t\fP" 16 +Used for dynamic package initialization. +.IP "\fBpthread_rwlock_t\fP" 16 +Used for read-write locks. +.IP "\fBpthread_rwlockattr_t\fP" 16 +Used for read-write lock attributes. +.IP "\fBpthread_spinlock_t\fP" 16 +Used to identify a spin lock. +.IP "\fBpthread_t\fP" 16 +Used to identify a thread. +.IP "\fBsize_t\fP" 16 +Used for sizes of objects. +.IP "\fBssize_t\fP" 16 +Used for a count of bytes or an error indication. +.IP "\fBsuseconds_t\fP" 16 +Used for time in microseconds. +.IP "\fBtime_t\fP" 16 +Used for time in seconds. +.IP "\fBtimer_t\fP" 16 +Used for timer ID returned by +\fItimer_create\fR(). +.IP "\fBtrace_attr_t\fP" 16 +Used to identify a trace stream attributes object +.IP "\fBtrace_event_id_t\fP" 16 +Used to identify a trace event type. +.IP "\fBtrace_event_set_t\fP" 16 +Used to identify a trace event type set. +.IP "\fBtrace_id_t\fP" 16 +Used to identify a trace stream. +.IP "\fBuid_t\fP" 16 +Used for user IDs. +.P +All of the types shall be defined as arithmetic types of an appropriate +length, with the following exceptions: +.P +.nf +.BR pthread_attr_t +.BR pthread_barrier_t +.BR pthread_barrierattr_t +.BR pthread_cond_t +.BR pthread_condattr_t +.BR pthread_key_t +.BR pthread_mutex_t +.BR pthread_mutexattr_t +.BR pthread_once_t +.BR pthread_rwlock_t +.BR pthread_rwlockattr_t +.BR pthread_spinlock_t +.BR pthread_t +.BR trace_attr_t +.BR trace_event_id_t +.BR trace_event_set_t +.BR trace_id_t +.fi +.P +Additionally: +.IP " *" 4 +.BR mode_t +shall be an integer type. +.IP " *" 4 +.BR dev_t +shall be an integer type. +.IP " *" 4 +.BR nlink_t , +.BR uid_t , +.BR gid_t , +and +.BR id_t +shall be integer types. +.IP " *" 4 +.BR blkcnt_t +and +.BR off_t +shall be signed integer types. +.IP " *" 4 +.BR fsblkcnt_t , +.BR fsfilcnt_t , +and +.BR ino_t +shall be defined as unsigned integer types. +.IP " *" 4 +.BR size_t +shall be an unsigned integer type. +.IP " *" 4 +.BR blksize_t , +.BR pid_t , +and +.BR ssize_t +shall be signed integer types. +.IP " *" 4 +.BR clock_t +shall be an integer or real-floating type. +.BR time_t +shall be an integer type. +.P +The type +.BR ssize_t +shall be capable of storing values at least in the range +[\(mi1,\ {SSIZE_MAX}]. +.P +The type +.BR suseconds_t +shall be a signed integer type capable of storing values at least in +the range [\(mi1,\ 1\|000\|000]. +.P +The implementation shall support one or more programming environments +in which the widths of +.BR blksize_t , +.BR pid_t , +.BR size_t , +.BR ssize_t , +and +.BR suseconds_t +are no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.P +There are no defined comparison or assignment operators for the +following types: +.P +.nf +.BR pthread_attr_t +.BR pthread_barrier_t +.BR pthread_barrierattr_t +.BR pthread_cond_t +.BR pthread_condattr_t +.BR pthread_mutex_t +.BR pthread_mutexattr_t +.BR pthread_rwlock_t +.BR pthread_rwlockattr_t +.BR pthread_spinlock_t +.BR trace_attr_t +.fi +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconfstr\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_uio.h.0p b/man-pages-posix-2013-a/man0p/sys_uio.h.0p new file mode 100644 index 0000000..d91d39f --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_uio.h.0p @@ -0,0 +1,104 @@ +'\" et +.TH sys_uio.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/uio.h +\(em definitions for vector I/O operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR iovec +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void *iov_base \fRBase address of a memory region for input or output.\fR +size_t iov_len \fRThe size of the memory pointed to by \fIiov_base.\fR +.fi \fR +.P +.RE +.P +The +.IR +header uses the +.BR iovec +structure for scatter/gather I/O. +.P +The +.IR +header shall define the +.BR ssize_t +and +.BR size_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +ssize_t readv(int, const struct iovec *, int); +ssize_t writev(int, const struct iovec *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The implementation can put a limit on the number of scatter/gather +elements which can be processed in one call. The symbol +{IOV_MAX} +defined in +.IR +should always be used to learn about the limits instead of assuming a +fixed value. +.SH RATIONALE +Traditionally, the maximum number of scatter/gather elements the system +can process in one call were described by the symbolic value +{UIO_MAXIOV}. +In IEEE\ Std\ 1003.1\(hy2001 this value is replaced by the constant +{IOV_MAX} +which can be found in +.IR . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIread\fR\^(\|)", +.IR "\fIreadv\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)", +.IR "\fIwritev\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_un.h.0p b/man-pages-posix-2013-a/man0p/sys_un.h.0p new file mode 100644 index 0000000..bb7bce6 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_un.h.0p @@ -0,0 +1,89 @@ +'\" et +.TH sys_un.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/un.h +\(em definitions for UNIX domain sockets +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR sockaddr_un +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t sun_family \fRAddress family.\fR +char sun_path[] \fRSocket pathname.\fR +.fi \fR +.P +.RE +.P +The +.BR sockaddr_un +structure is used to store addresses for UNIX domain sockets. +Pointers to this type shall be cast by applications to +.BR "struct sockaddr *" +for use with socket functions. +.P +The +.IR +header shall define the +.BR sa_family_t +type as described in +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The size of +.IR sun_path +has intentionally been left undefined. This is because different +implementations use different sizes. For example, 4.3 BSD uses a size of +108, and 4.4 BSD uses a size of 104. Since most implementations +originate from BSD versions, the size is typically in the range 92 to +108. +.P +Applications should not assume a particular length for +.IR sun_path +or assume that it can hold +{_POSIX_PATH_MAX} +bytes (256). +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIbind\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIsocketpair\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_utsname.h.0p b/man-pages-posix-2013-a/man0p/sys_utsname.h.0p new file mode 100644 index 0000000..dabaec3 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_utsname.h.0p @@ -0,0 +1,77 @@ +'\" et +.TH sys_utsname.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/utsname.h +\(em system name structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structure +.BR utsname +which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char sysname[] \fRName of this implementation of the operating system.\fR +char nodename[] \fRName of this node within the communications\fR + \fRnetwork to which this node is attached, if any.\fR +char release[] \fRCurrent release level of this implementation.\fR +char version[] \fRCurrent version level of this release.\fR +char machine[] \fRName of the hardware type on which the system is running.\fR +.fi \fR +.P +.RE +.P +The character arrays are of unspecified size, but the data stored in +them shall be terminated by a null byte. +.P +The following shall be declared as a function and may also be defined +as a macro: +.sp +.RS 4 +.nf +\fB +int uname(struct utsname *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIuname\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/sys_wait.h.0p b/man-pages-posix-2013-a/man0p/sys_wait.h.0p new file mode 100644 index 0000000..cf88bc8 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/sys_wait.h.0p @@ -0,0 +1,145 @@ +'\" et +.TH sys_wait.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/wait.h +\(em declarations for waiting +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants for use with +\fIwaitpid\fR(): +.IP WCONTINUED 14 +Report status of continued child process. +.IP WNOHANG 14 +Do not hang if no status is available; return immediately. +.IP WUNTRACED 14 +Report status of stopped child process. +.P +The +.IR +header shall define the following macros for analysis of process status +values: +.IP WEXITSTATUS 14 +Return exit status. +.IP WIFCONTINUED 14 +True if child has been continued. +.IP WIFEXITED 14 +True if child exited normally. +.IP WIFSIGNALED 14 +True if child exited due to uncaught signal. +.IP WIFSTOPPED 14 +True if child is currently stopped. +.IP WSTOPSIG 14 +Return signal number that caused process to stop. +.IP WTERMSIG 14 +Return signal number that caused process to terminate. +.P +The +.IR +header shall define the following symbolic constants as possible values +for the +.IR options +argument to +\fIwaitid\fR(): +.IP WEXITED 14 +Wait for processes that have exited. +.IP WNOWAIT 14 +Keep the process whose status is returned in +.IR infop +in a waitable state. +.IP WSTOPPED 14 +Status is returned for any child that has stopped upon receipt of a +signal. +.P +The +WCONTINUED +and WNOHANG constants, described above for +\fIwaitpid\fR(), +can also be used with +\fIwaitid\fR(). +.P +The type +.BR idtype_t +shall be defined as an enumeration type whose possible values shall +include at least the following: +P_ALL +P_PGID +P_PID +.P +The +.IR +header shall define the +.BR id_t +and +.BR pid_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR siginfo_t +type as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible +all symbols from +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +pid_t wait(int *); +int waitid(idtype_t, id_t, siginfo_t *, int); +pid_t waitpid(pid_t, int *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/syslog.h.0p b/man-pages-posix-2013-a/man0p/syslog.h.0p new file mode 100644 index 0000000..8793f9d --- /dev/null +++ b/man-pages-posix-2013-a/man0p/syslog.h.0p @@ -0,0 +1,158 @@ +'\" et +.TH syslog.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +syslog.h +\(em definitions for system error logging +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants, zero or more +of which may be OR'ed together to form the +.IR logopt +option of +\fIopenlog\fR(): +.IP LOG_PID 14 +Log the process ID with each message. +.IP LOG_CONS 14 +Log to the system console on error. +.IP LOG_NDELAY 14 +Connect to syslog daemon immediately. +.IP LOG_ODELAY 14 +Delay open until +\fIsyslog\fR() +is called. +.IP LOG_NOWAIT 14 +Do not wait for child processes. +.P +The +.IR +header shall define the following symbolic constants for use as the +.IR facility +argument to +\fIopenlog\fR(): +.IP LOG_KERN 14 +Reserved for message generated by the system. +.IP LOG_USER 14 +Message generated by a process. +.IP LOG_MAIL 14 +Reserved for message generated by mail system. +.IP LOG_NEWS 14 +Reserved for message generated by news system. +.IP LOG_UUCP 14 +Reserved for message generated by UUCP system. +.IP LOG_DAEMON 14 +Reserved for message generated by system daemon. +.IP LOG_AUTH 14 +Reserved for message generated by authorization daemon. +.IP LOG_CRON 14 +Reserved for message generated by clock daemon. +.IP LOG_LPR 14 +Reserved for message generated by printer system. +.IP LOG_LOCAL0 14 +Reserved for local use. +.IP LOG_LOCAL1 14 +Reserved for local use. +.IP LOG_LOCAL2 14 +Reserved for local use. +.IP LOG_LOCAL3 14 +Reserved for local use. +.IP LOG_LOCAL4 14 +Reserved for local use. +.IP LOG_LOCAL5 14 +Reserved for local use. +.IP LOG_LOCAL6 14 +Reserved for local use. +.IP LOG_LOCAL7 14 +Reserved for local use. +.P +The +.IR +header shall define the following macros for constructing the +.IR maskpri +argument to +\fIsetlogmask\fR(). +The following macros expand to an expression of type +.BR int +when the argument +.IR pri +is an expression of type +.BR int : +.IP "LOG_MASK(\fIpri\fR)" 14 +A mask for priority +.IR pri . +.P +The +.IR +header shall define the following symbolic constants for use as the +.IR priority +argument of +\fIsyslog\fR(): +.IP LOG_EMERG 14 +A panic condition was reported to all processes. +.IP LOG_ALERT 14 +A condition that should be corrected immediately. +.IP LOG_CRIT 14 +A critical condition. +.IP LOG_ERR 14 +An error message. +.IP LOG_WARNING 14 +A warning message. +.IP LOG_NOTICE 14 +A condition requiring special handling. +.IP LOG_INFO 14 +A general information message. +.IP LOG_DEBUG 14 +A message useful for debugging programs. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void closelog(void); +void openlog(const char *, int, int); +int setlogmask(int); +void syslog(int, const char *, ...); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcloselog\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/tar.h.0p b/man-pages-posix-2013-a/man0p/tar.h.0p new file mode 100644 index 0000000..499fc05 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/tar.h.0p @@ -0,0 +1,102 @@ +'\" et +.TH tar.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tar.h +\(em extended tar definitions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants with the +indicated values. +.P +General definitions: +.TS +center box tab(@); +cB | cB | cB +lw(15) | cf5w(15) | lw(40). +Name@Value@Description +_ +TMAGIC@"ustar"@ustar plus null byte. +TMAGLEN@6@Length of the above. +TVERSION@"00"@00 without a null byte. +TVERSLEN@2@Length of the above. +.TE +.P +.IR Typeflag +field definitions: +.TS +center box tab(@); +cB | cB | cB +lw(15) | cf5w(15) | lw(40). +Name@Value@Description +_ +REGTYPE@'0'@Regular file. +AREGTYPE@'\e0'@Regular file. +LNKTYPE@'1'@Link. +SYMTYPE@'2'@Symbolic link. +CHRTYPE@'3'@Character special. +BLKTYPE@'4'@Block special. +DIRTYPE@'5'@Directory. +FIFOTYPE@'6'@FIFO special. +CONTTYPE@'7'@Reserved. +.TE +.P +\fIMode\fP field bit definitions (octal): +.TS +center box tab(@); +cB | cB | cB +lw(15) | cw(15) | lw(40). +Name@Value@Description +_ +TSUID@04000@Set UID on execution. +TSGID@02000@Set GID on execution. +TSVTX@01000@\*!On directories, restricted deletion flag.\0\0\0\*? +TUREAD@00400@Read by owner. +TUWRITE@00200@Write by owner special. +TUEXEC@00100@Execute/search by owner. +TGREAD@00040@Read by group. +TGWRITE@00020@Write by group. +TGEXEC@00010@Execute/search by group. +TOREAD@00004@Read by other. +TOWRITE@00002@Write by other. +TOEXEC@00001@Execute/search by other. +.TE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIpax\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/termios.h.0p b/man-pages-posix-2013-a/man0p/termios.h.0p new file mode 100644 index 0000000..a76d631 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/termios.h.0p @@ -0,0 +1,457 @@ +'\" et +.TH termios.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +termios.h +\(em define values for termios +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall contain the definitions used by the terminal I/O +interfaces (see +.IR "Chapter 11" ", " "General Terminal Interface" +for the structures and names defined). +.SS "The termios Structure" +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBcc_t\fP" 12 +Used for terminal special characters. +.IP "\fBspeed_t\fP" 12 +Used for terminal baud rates. +.IP "\fBtcflag_t\fP" 12 +Used for terminal modes. +.P +The above types shall be all unsigned integer types. +.P +The implementation shall support one or more programming environments +in which the widths of +.BR cc_t , +.BR speed_t , +and +.BR tcflag_t +are no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.P +The +.IR +header shall define the +.BR termios +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +tcflag_t c_iflag \fRInput modes.\fR +tcflag_t c_oflag \fROutput modes.\fR +tcflag_t c_cflag \fRControl modes.\fR +tcflag_t c_lflag \fRLocal modes.\fR +cc_t c_cc[NCCS] \fRControl characters.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constant: +.IP NCCS 12 +Size of the array +.IR c_cc +for control characters. +.P +The +.IR +header shall define the following symbolic constants for use as +subscripts for the array +.IR c_cc : +.TS +box center tab(!); +cb s | l +cb cb | cb +l | l | l. +Subscript Usage +Canonical Mode!Non-Canonical Mode!Description +_ +VEOF!!EOF character. +VEOL!!EOL character. +VERASE!!ERASE character. +VINTR!VINTR!INTR character. +VKILL!!KILL character. +\&!VMIN!MIN value. +VQUIT!VQUIT!QUIT character. +VSTART!VSTART!START character. +VSTOP!VSTOP!STOP character. +VSUSP!VSUSP!SUSP character. +\&!VTIME!TIME value. +.TE +.P +The subscript values shall be suitable for use in +.BR #if +preprocessing directives and shall be distinct, except that the VMIN +and VTIME subscripts may have the same values as the VEOF and +VEOL subscripts, respectively. +.SS "Input Modes" +.P +The +.IR +header shall define the following symbolic constants for use as flags +in the +.IR c_iflag +field. The +.IR c_iflag +field describes the basic terminal input control. +.IP BRKINT 12 +Signal interrupt on break. +.IP ICRNL 12 +Map CR to NL on input. +.IP IGNBRK 12 +Ignore break condition. +.IP IGNCR 12 +Ignore CR. +.IP IGNPAR 12 +Ignore characters with parity errors. +.IP INLCR 12 +Map NL to CR on input. +.IP INPCK 12 +Enable input parity check. +.IP ISTRIP 12 +Strip character. +.IP IXANY 12 +Enable any character to restart output. +.IP IXOFF 12 +Enable start/stop input control. +.IP IXON 12 +Enable start/stop output control. +.IP PARMRK 12 +Mark parity errors. +.SS "Output Modes" +.P +The +.IR +header shall define the following symbolic constants for use as flags +in the +.IR c_oflag +field. The +.IR c_oflag +field specifies the system treatment of output. +.IP OPOST 12 +Post-process output. +.IP ONLCR 12 +Map NL to CR-NL on output. +.IP OCRNL 12 +Map CR to NL on output. +.IP ONOCR 12 +No CR output at column 0. +.IP ONLRET 12 +NL performs CR function. +.IP OFDEL 12 +Fill is DEL. +.IP OFILL 12 +Use fill characters for delay. +.IP NLDLY 12 +Select newline delays: +.RS 12 +.IP NL0 8 +Newline type 0. +.IP NL1 8 +Newline type 1. +.RE +.IP CRDLY 12 +Select carriage-return delays: +.RS 12 +.IP CR0 8 +Carriage-return delay type 0. +.IP CR1 8 +Carriage-return delay type 1. +.IP CR2 8 +Carriage-return delay type 2. +.IP CR3 8 +Carriage-return delay type 3. +.RE +.IP TABDLY 12 +Select horizontal-tab delays: +.RS 12 +.IP TAB0 8 +Horizontal-tab delay type 0. +.IP TAB1 8 +Horizontal-tab delay type 1. +.IP TAB2 8 +Horizontal-tab delay type 2. +.IP TAB3 8 +Expand tabs to spaces. +.RE +.IP BSDLY 12 +Select backspace delays: +.RS 12 +.IP BS0 8 +Backspace-delay type 0. +.IP BS1 8 +Backspace-delay type 1. +.RE +.IP VTDLY 12 +Select vertical-tab delays: +.RS 12 +.IP VT0 8 +Vertical-tab delay type 0. +.IP VT1 8 +Vertical-tab delay type 1. +.RE +.IP FFDLY 12 +Select form-feed delays: +.RS 12 +.IP FF0 8 +Form-feed delay type 0. +.IP FF1 8 +Form-feed delay type 1. +.RE +.SS "Baud Rate Selection" +.P +The +.IR +header shall define the following symbolic constants for use as values +of objects of type +.BR speed_t . +.P +The input and output baud rates are stored in the +.BR termios +structure. These are the valid values for objects of type +.BR speed_t . +Not all baud rates need be supported by the underlying hardware. +.IP B0 12 +Hang up +.IP B50 12 +50 baud +.IP B75 12 +75 baud +.IP B110 12 +110 baud +.IP B134 12 +134.5 baud +.IP B150 12 +150 baud +.IP B200 12 +200 baud +.IP B300 12 +300 baud +.IP B600 12 +600 baud +.IP B1200 12 +1\|200 baud +.IP B1800 12 +1\|800 baud +.IP B2400 12 +2\|400 baud +.IP B4800 12 +4\|800 baud +.IP B9600 12 +9\|600 baud +.IP B19200 12 +19\|200 baud +.IP B38400 12 +38\|400 baud +.SS "Control Modes" +.P +The +.IR +header shall define the following symbolic constants for use as flags +in the +.IR c_cflag +field. The +.IR c_cflag +field describes the hardware control of the terminal; not all values +specified are required to be supported by the underlying hardware. +.IP CSIZE 12 +Character size: +.RS 12 +.IP CS5 8 +5 bits +.IP CS6 8 +6 bits +.IP CS7 8 +7 bits +.IP CS8 8 +8 bits +.RE +.IP CSTOPB 12 +Send two stop bits, else one. +.IP CREAD 12 +Enable receiver. +.IP PARENB 12 +Parity enable. +.IP PARODD 12 +Odd parity, else even. +.IP HUPCL 12 +Hang up on last close. +.IP CLOCAL 12 +Ignore modem status lines. +.P +The implementation shall support the functionality associated with the +symbols CS7, CS8, CSTOPB, PARODD, and PARENB. +.SS "Local Modes" +.P +The +.IR +header shall define the following symbolic constants for use as flags +in the +.IR c_lflag +field. The +.IR c_lflag +field of the argument structure is used to control various terminal +functions. +.IP ECHO 12 +Enable echo. +.IP ECHOE 12 +Echo erase character as error-correcting backspace. +.IP ECHOK 12 +Echo KILL. +.IP ECHONL 12 +Echo NL. +.IP ICANON 12 +Canonical input (erase and kill processing). +.IP IEXTEN 12 +Enable extended input character processing. +.IP ISIG 12 +Enable signals. +.IP NOFLSH 12 +Disable flush after interrupt or quit. +.IP TOSTOP 12 +Send SIGTTOU for background output. +.SS "Attribute Selection" +.P +The +.IR +header shall define the following symbolic constants for use with +\fItcsetattr\fR(): +.IP TCSANOW 12 +Change attributes immediately. +.IP TCSADRAIN 12 +Change attributes when output has drained. +.IP TCSAFLUSH 12 +Change attributes when output has drained; also flush pending input. +.SS "Line Control" +.P +The +.IR +header shall define the following symbolic constants for use with +\fItcflush\fR(): +.IP TCIFLUSH 12 +Flush pending input. +.IP TCIOFLUSH 12 +Flush both pending input and untransmitted output. +.IP TCOFLUSH 12 +Flush untransmitted output. +.P +The +.IR +header shall define the following symbolic constants for use with +\fItcflow\fR(): +.IP TCIOFF 12 +Transmit a STOP character, intended to suspend input data. +.IP TCION 12 +Transmit a START character, intended to restart input data. +.IP TCOOFF 12 +Suspend output. +.IP TCOON 12 +Restart output. +.P +The +.IR +header shall define the +.BR pid_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +speed_t cfgetispeed(const struct termios *); +speed_t cfgetospeed(const struct termios *); +int cfsetispeed(struct termios *, speed_t); +int cfsetospeed(struct termios *, speed_t); +int tcdrain(int); +int tcflow(int, int); +int tcflush(int, int); +int tcgetattr(int, struct termios *); +pid_t tcgetsid(int); +int tcsendbreak(int, int); +int tcsetattr(int, int, const struct termios *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The following names are reserved for XSI-conformant systems to use as +an extension to the above; therefore strictly conforming applications +shall not use them: +.TS +tab(@); +le le le. +CBAUD@EXTB@VDSUSP +DEFECHO@FLUSHO@VLNEXT +ECHOCTL@LOBLK@VREPRINT +ECHOKE@PENDIN@VSTATUS +ECHOPRT@SWTCH@VWERASE +EXTA@VDISCARD +.TE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fIcfgetospeed\fR\^(\|)", +.IR "\fIcfsetispeed\fR\^(\|)", +.IR "\fIcfsetospeed\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fItcdrain\fR\^(\|)", +.IR "\fItcflow\fR\^(\|)", +.IR "\fItcflush\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)", +.IR "\fItcgetsid\fR\^(\|)", +.IR "\fItcsendbreak\fR\^(\|)", +.IR "\fItcsetattr\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/tgmath.h.0p b/man-pages-posix-2013-a/man0p/tgmath.h.0p new file mode 100644 index 0000000..8ebfa52 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/tgmath.h.0p @@ -0,0 +1,396 @@ +'\" et +.TH tgmath.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tgmath.h +\(em type-generic macros +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall include the headers +.IR +and +.IR +and shall define several type-generic macros. +.P +Of the functions contained within the +.IR +and +.IR +headers without an +.IR f +(\c +.BR float ) +or +.IR l +(\c +.BR "long double" ) +suffix, several have one or more parameters whose corresponding real +type is +.BR double . +For each such function, except +\fImodf\fR(), +\fIj0\fR(), +\fIj1\fR(), +\fIjn\fR(), +\fIy0\fR(), +\fIy1\fR(), +and +\fIyn\fR(), +there shall be a corresponding type-generic macro. The parameters +whose corresponding real type is +.BR double +in the function synopsis are generic parameters. Use of the macro +invokes a function whose corresponding real type and type domain are +determined by the arguments for the generic parameters. +.P +Use of the macro invokes a function whose generic parameters have the +corresponding real type determined as follows: +.IP " *" 4 +First, if any argument for generic parameters has type +.BR "long double" , +the type determined is +.BR "long double" . +.IP " *" 4 +Otherwise, if any argument for generic parameters has type +.BR double +or is of integer type, the type determined is +.BR double . +.IP " *" 4 +Otherwise, the type determined is +.BR float . +.P +For each unsuffixed function in the +.IR +header for which there is a function in the +.IR +header with the same name except for a +.IR c +prefix, the corresponding type-generic macro (for both functions) has +the same name as the function in the +.IR +header. The corresponding type-generic macro for +\fIfabs\fR() +and +\fIcabs\fR() +is +\fIfabs\fR(). +.TS +center box tab(!); +cB | cB | cB +l | l | l. + Function! Function!Type-Generic Macro +_ +\fIacos\fR\^(\|)!\fIcacos\fR\^(\|)!\fIacos\fR\^(\|) +\fIasin\fR\^(\|)!\fIcasin\fR\^(\|)!\fIasin\fR\^(\|) +\fIatan\fR\^(\|)!\fIcatan\fR\^(\|)!\fIatan\fR\^(\|) +\fIacosh\fR\^(\|)!\fIcacosh\fR\^(\|)!\fIacosh\fR\^(\|) +\fIasinh\fR\^(\|)!\fIcasinh\fR\^(\|)!\fIasinh\fR\^(\|) +\fIatanh\fR\^(\|)!\fIcatanh\fR\^(\|)!\fIatanh\fR\^(\|) +\fIcos\fR\^(\|)!\fIccos\fR\^(\|)!\fIcos\fR\^(\|) +\fIsin\fR\^(\|)!\fIcsin\fR\^(\|)!\fIsin\fR\^(\|) +\fItan\fR\^(\|)!\fIctan\fR\^(\|)!\fItan\fR\^(\|) +\fIcosh\fR\^(\|)!\fIccosh\fR\^(\|)!\fIcosh\fR\^(\|) +\fIsinh\fR\^(\|)!\fIcsinh\fR\^(\|)!\fIsinh\fR\^(\|) +\fItanh\fR\^(\|)!\fIctanh\fR\^(\|)!\fItanh\fR\^(\|) +\fIexp\fR\^(\|)!\fIcexp\fR\^(\|)!\fIexp\fR\^(\|) +\fIlog\fR\^(\|)!\fIclog\fR\^(\|)!\fIlog\fR\^(\|) +\fIpow\fR\^(\|)!\fIcpow\fR\^(\|)!\fIpow\fR\^(\|) +\fIsqrt\fR\^(\|)!\fIcsqrt\fR\^(\|)!\fIsqrt\fR\^(\|) +\fIfabs\fR\^(\|)!\fIcabs\fR\^(\|)!\fIfabs\fR\^(\|) +.TE +.P +If at least one argument for a generic parameter is complex, then use +of the macro invokes a complex function; otherwise, use of the macro +invokes a real function. +.P +For each unsuffixed function in the +.IR +header without a +.IR c -prefixed +counterpart in the +.IR +header, except for +\fImodf\fR(), +\fIj0\fR(), +\fIj1\fR(), +\fIjn\fR(), +\fIy0\fR(), +\fIy1\fR(), +and +\fIyn\fR(), +the corresponding type-generic macro has the same name as the function. +These type-generic macros are: +.sp +.RS +.TS +tab(!); +l l l l. +T{ +.nf +\fIatan2\fR() +\fIcbrt\fR() +\fIceil\fR() +\fIcopysign\fR() +\fIerf\fR() +\fIerfc\fR() +\fIexp2\fR() +\fIexpm1\fR() +\fIfdim\fR() +\fIfloor\fR() +T}!T{ +.nf +\fIfma\fR() +\fIfmax\fR() +\fIfmin\fR() +\fIfmod\fR() +\fIfrexp\fR() +\fIhypot\fR() +\fIilogb\fR() +\fIldexp\fR() +\fIlgamma\fR() +\fIllrint\fR() +T}!T{ +.nf +\fIllround\fR() +\fIlog10\fR() +\fIlog1p\fR() +\fIlog2\fR() +\fIlogb\fR() +\fIlrint\fR() +\fIlround\fR() +\fInearbyint\fR() +\fInextafter\fR() +\fInexttoward\fR() +T}!T{ +.nf +\fIremainder\fR() +\fIremquo\fR() +\fIrint\fR() +\fIround\fR() +\fIscalbln\fR() +\fIscalbn\fR() +\fItgamma\fR() +\fItrunc\fR() +.fi +T} +.TE +.RE +.P +If all arguments for generic parameters are real, then use of the macro +invokes a real function; otherwise, use of the macro results in +undefined behavior. +.P +For each unsuffixed function in the +.IR +header that is not a +.IR c -prefixed +counterpart to a function in the +.IR +header, the corresponding type-generic macro has the same name as the +function. These type-generic macros are: +.sp +.RS +\fIcarg\fR() +\fIcimag\fR() +\fIconj\fR() +\fIcproj\fR() +\fIcreal\fR() +.RE +.P +Use of the macro with any real or complex argument invokes a complex +function. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +With the declarations: +.sp +.RS 4 +.nf +\fB +#include +int n; +float f; +double d; +long double ld; +float complex fc; +double complex dc; +long double complex ldc; +.fi \fR +.P +.RE +.P +functions invoked by use of type-generic macros are shown in the +following table: +.TS +center box tab(!); +cB | cB +l | l. +Macro!Use Invokes +_ +\fIexp\fR(\fIn\fR)!\fIexp\fR(\fIn\fR), the function +\fIacosh\fR(\fIf\fR)!\fIacoshf\fR(\fIf\fR) +\fIsin\fR(\fId\fR)!\fIsin\fR(\fId\fR), the function +\fIatan\fR(\fIld\fR)!\fIatanl\fR(\fIld\fR) +\fIlog\fR(\fIfc\fR)!\fIclogf\fR(\fIfc\fR) +\fIsqrt\fR(\fIdc\fR)!\fIcsqrt\fR(\fIdc\fR) +\fIpow\fR(\fIldc,f\fR)!\fIcpowl\fR(\fIldc, f\fR) +\fIremainder\fR(\fIn,n\fR)!\fIremainder\fR(\fIn, n\fR), the function +\fInextafter\fR(\fId,f\fR)!\fInextafter\fR(\fId, f\fR), the function +\fInexttoward\fR(\fIf,ld\fR)!\fInexttowardf\fR(\fIf, ld\fR) +\fIcopysign\fR(\fIn,ld\fR)!\fIcopysignl\fR(\fIn, ld\fR) +\fIceil\fR(\fIfc\fR)!Undefined behavior +\fIrint\fR(\fIdc\fR)!Undefined behavior +\fIfmax\fR(\fIldc,ld\fR)!Undefined behavior +\fIcarg\fR(\fIn\fR)!\fIcarg\fR(\fIn\fR), the function +\fIcproj\fR(\fIf\fR)!\fIcprojf\fR(\fIf\fR) +\fIcreal\fR(\fId\fR)!\fIcreal\fR(\fId\fR), the function +\fIcimag\fR(\fIld\fR)!\fIcimagl\fR(\fIld\fR) +\fIcabs\fR(\fIfc\fR)!\fIcabsf\fR(\fIfc\fR) +\fIcarg\fR(\fIdc\fR)!\fIcarg\fR(\fIdc\fR), the function +\fIcproj\fR(\fIldc\fR)!\fIcprojl\fR(\fIldc\fR) +.TE +.SH RATIONALE +Type-generic macros allow calling a function whose type is determined +by the argument type, as is the case for C operators such as +.BR '+' +and +.BR '*' . +For example, with a type-generic +\fIcos\fR() +macro, the expression +.IR cos ((\c +.BR float )\c +.IR x ) +will have type +.BR float . +This feature enables writing more portably efficient code and +alleviates need for awkward casting and suffixing in the process of +porting or adjusting precision. Generic math functions are a widely +appreciated feature of Fortran. +.P +The only arguments that affect the type resolution are the arguments +corresponding to the parameters that have type +.BR double +in the synopsis. Hence the type of a type-generic call to +\fInexttoward\fR(), +whose second parameter is +.BR "long double" +in the synopsis, is determined solely by the type of the first +argument. +.P +The term ``type-generic'' was chosen over the proposed alternatives of +intrinsic and overloading. The term is more specific than intrinsic, +which already is widely used with a more general meaning, and reflects +a closer match to Fortran's generic functions than to C++ overloading. +.P +The macros are placed in their own header in order not to silently +break old programs that include the +.IR +header; for example, with: +.sp +.RS 4 +.nf +\fB +printf ("%e", sin(x)) +.fi \fR +.P +.RE +.P +.IR modf (\c +.BR double , +.BR "double *" ) +is excluded because no way was seen to make it safe without +complicating the type resolution. +.P +The implementation might, as an extension, endow appropriate ones of +the macros that POSIX.1\(hy2008 specifies only for real arguments with the +ability to invoke the complex functions. +.P +POSIX.1\(hy2008 does not prescribe any particular implementation mechanism +for generic macros. It could be implemented simply with built-in +macros. The generic macro for +\fIsqrt\fR(), +for example, could be implemented with: +.sp +.RS 4 +.nf +\fB +#undef sqrt +#define sqrt(x) __BUILTIN_GENERIC_sqrt(x) +.fi \fR +.P +.RE +.P +Generic macros are designed for a useful level of consistency with C++ +overloaded math functions. +.P +The great majority of existing C programs are expected to be unaffected +when the +.IR +header is included instead of the +.IR +or +.IR +headers. Generic macros are similar to the ISO/IEC\ 9899:\|1999 standard library masking +macros, though the semantic types of return values differ. +.P +The ability to overload on integer as well as floating types would have +been useful for some functions; for example, +\fIcopysign\fR(). +Overloading with different numbers of arguments would have allowed +reusing names; for example, +\fIremainder\fR() +for +\fIremquo\fR(). +However, these facilities would have complicated the specification; and +their natural consistent use, such as for a floating +\fIabs\fR() +or a two-argument +\fIatan\fR(), +would have introduced further inconsistencies with the ISO/IEC\ 9899:\|1999 standard for +insufficient benefit. +.P +The ISO\ C standard in no way limits the implementation's options for efficiency, +including inlining library functions. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcabs\fR\^(\|)", +.IR "\fIfabs\fR\^(\|)", +.IR "\fImodf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/time.h.0p b/man-pages-posix-2013-a/man0p/time.h.0p new file mode 100644 index 0000000..81f63b6 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/time.h.0p @@ -0,0 +1,331 @@ +'\" et +.TH time.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +time.h +\(em time types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the +.BR clock_t , +.BR size_t , +.BR time_t , +types as described in +.IR . +.P +The +.IR +header shall define the +.BR clockid_t +and +.BR timer_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR pid_t +type as described in +.IR . +.P +The tag +.BR sigevent +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The +.IR +header shall declare the +.BR tm +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int tm_sec \fRSeconds [0,60].\fR +int tm_min \fRMinutes [0,59].\fR +int tm_hour \fRHour [0,23].\fR +int tm_mday \fRDay of month [1,31].\fR +int tm_mon \fRMonth of year [0,11].\fR +int tm_year \fRYears since 1900.\fR +int tm_wday \fRDay of week [0,6] (Sunday =0).\fR +int tm_yday \fRDay of year [0,365].\fR +int tm_isdst \fRDaylight Savings flag.\fR +.fi \fR +.P +.RE +.P +The value of +.IR tm_isdst +shall be positive if Daylight Savings Time is in effect, 0 if Daylight +Savings Time is not in effect, and negative if the information is not +available. +.P +The +.IR +header shall declare the +.BR timespec +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +time_t tv_sec \fRSeconds.\fR +long tv_nsec \fRNanoseconds.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall also declare the +.BR itimerspec +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct timespec it_interval \fRTimer period.\fR +struct timespec it_value \fRTimer expiration.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following macros: +.IP NULL 14 +As described in +.IR . +.IP CLOCKS_PER_SEC 14 +A number used to convert the value returned by the +\fIclock\fR() +function into seconds. The value shall be an expression with type +.BR clock_t . +The value of CLOCKS_PER_SEC shall be 1 million +on XSI-conformant systems. However, it may be variable on other systems, +and it should not be assumed that CLOCKS_PER_SEC is a compile-time +constant. +.P +The +.IR +header shall define the following symbolic constants. The values shall +have a type that is assignment-compatible with +.BR clockid_t . +.IP CLOCK_MONOTONIC 14 +.br +The identifier for the system-wide monotonic clock, which is defined as +a clock measuring real time, whose value cannot be set via +\fIclock_settime\fR() +and which cannot have negative clock jumps. The maximum possible clock +jump shall be implementation-defined. +.IP CLOCK_PROCESS_CPUTIME_ID 14 +.br +The identifier of the CPU-time clock associated with the process +making a +\fIclock\fR() +or +.IR timer* (\|) +function call. +.IP CLOCK_REALTIME 14 +The identifier of the system-wide clock measuring real time. +.IP CLOCK_THREAD_CPUTIME_ID 14 +.br +The identifier of the CPU-time clock associated with the thread making a +\fIclock\fR() +or +.IR timer* (\|) +function call. +.P +The +.IR +header shall define the following symbolic constant: +.IP TIMER_ABSTIME 14 +Flag indicating time is absolute. For functions taking timer objects, +this refers to the clock associated with the timer. +.P +The +.IR +header shall provide a declaration or definition for +.IR getdate_err . +The +.IR getdate_err +symbol shall expand to an expression of type +.BR int . +It is unspecified whether +.IR getdate_err +is a macro or an identifier declared with external linkage, and whether or +not it is a modifiable lvalue. If a macro definition is suppressed in +order to access an actual object, or a program defines an identifier +with the name +.IR getdate_err , +the behavior is undefined. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +char *asctime(const struct tm *); +char *asctime_r(const struct tm *restrict, char *restrict); +clock_t clock(void); +int clock_getcpuclockid(pid_t, clockid_t *); +int clock_getres(clockid_t, struct timespec *); +int clock_gettime(clockid_t, struct timespec *); +int clock_nanosleep(clockid_t, int, const struct timespec *, + struct timespec *); +int clock_settime(clockid_t, const struct timespec *); +char *ctime(const time_t *); +char *ctime_r(const time_t *, char *); +double difftime(time_t, time_t); +struct tm *getdate(const char *); +struct tm *gmtime(const time_t *); +struct tm *gmtime_r(const time_t *restrict, struct tm *restrict); +struct tm *localtime(const time_t *); +struct tm *localtime_r(const time_t *restrict, struct tm *restrict); +time_t mktime(struct tm *); +int nanosleep(const struct timespec *, struct timespec *); +size_t strftime(char *restrict, size_t, const char *restrict, + const struct tm *restrict); +size_t strftime_l(char *restrict, size_t, const char *restrict, + const struct tm *restrict, locale_t); +char *strptime(const char *restrict, const char *restrict, + struct tm *restrict); +time_t time(time_t *); +int timer_create(clockid_t, struct sigevent *restrict, + timer_t *restrict); +int timer_delete(timer_t); +int timer_getoverrun(timer_t); +int timer_gettime(timer_t, struct itimerspec *); +int timer_settime(timer_t, int, const struct itimerspec *restrict, + struct itimerspec *restrict); +void tzset(void); +.fi \fR +.P +.RE +.br +.P +The +.IR +header shall declare the following as variables: +.sp +.RS 4 +.nf +\fB +extern int daylight; +extern long timezone; +extern char *tzname[]; +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The range [0,60] for +.IR tm_sec +allows for the occasional leap second. +.P +.IR tm_year +is a signed value; therefore, years before 1900 may be represented. +.P +To obtain the number of clock ticks per second returned by the +\fItimes\fR() +function, applications should call +.IR sysconf (_SC_CLK_TCK). +.SH RATIONALE +The range [0,60] seconds allows for positive or negative leap seconds. +The formal definition of UTC does not permit double leap seconds, so +all mention of double leap seconds has been removed, and the range +shortened from the former [0,61] seconds seen in earlier versions of +this standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIclock_getcpuclockid\fR\^(\|)", +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIclock_nanosleep\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgetdate\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpthread_getcpuclockid\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)", +.IR "\fItimer_delete\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/trace.h.0p b/man-pages-posix-2013-a/man0p/trace.h.0p new file mode 100644 index 0000000..4e0555f --- /dev/null +++ b/man-pages-posix-2013-a/man0p/trace.h.0p @@ -0,0 +1,236 @@ +'\" et +.TH trace.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +trace.h +\(em tracing +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR posix_trace_event_info +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +trace_event_id_t posix_event_id +pid_t posix_pid +void *posix_prog_address +pthread_t posix_thread_id +struct timespec posix_timestamp +int posix_truncation_status +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR posix_trace_status_info +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int posix_stream_full_status +int posix_stream_overrun_status +int posix_stream_status +int posix_log_full_status +int posix_log_overrun_status +int posix_stream_flush_error +int posix_stream_flush_status +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants: +.P +.nf +POSIX_TRACE_ALL_EVENTS +POSIX_TRACE_APPEND +POSIX_TRACE_CLOSE_FOR_CHILD +POSIX_TRACE_FILTER +POSIX_TRACE_FLUSH +POSIX_TRACE_FLUSH_START +POSIX_TRACE_FLUSH_STOP +POSIX_TRACE_FLUSHING +POSIX_TRACE_FULL +POSIX_TRACE_LOOP +POSIX_TRACE_NO_OVERRUN +POSIX_TRACE_NOT_FLUSHING +POSIX_TRACE_NOT_FULL +POSIX_TRACE_INHERITED +POSIX_TRACE_NOT_TRUNCATED +POSIX_TRACE_OVERFLOW +POSIX_TRACE_OVERRUN +POSIX_TRACE_RESUME +POSIX_TRACE_RUNNING +POSIX_TRACE_START +POSIX_TRACE_STOP +POSIX_TRACE_SUSPENDED +POSIX_TRACE_SYSTEM_EVENTS +POSIX_TRACE_TRUNCATED_READ +POSIX_TRACE_TRUNCATED_RECORD +POSIX_TRACE_UNNAMED_USER_EVENT +POSIX_TRACE_UNTIL_FULL +POSIX_TRACE_WOPID_EVENTS +.fi +.P +The +.IR +header shall define the +.BR size_t , +.BR trace_attr_t , +.BR trace_event_id_t , +.BR trace_event_set_t , +and +.BR trace_id_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int posix_trace_attr_destroy(trace_attr_t *); +int posix_trace_attr_getclockres(const trace_attr_t *, + struct timespec *); +int posix_trace_attr_getcreatetime(const trace_attr_t *, + struct timespec *); +int posix_trace_attr_getgenversion(const trace_attr_t *, char *); +int posix_trace_attr_getinherited(const trace_attr_t *restrict, + int *restrict); +int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict, + int *restrict); +int posix_trace_attr_getlogsize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_getmaxsystemeventsize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_getmaxusereventsize(const trace_attr_t *restrict, + size_t, size_t *restrict); +int posix_trace_attr_getname(const trace_attr_t *, char *); +int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict, + int *restrict); +int posix_trace_attr_getstreamsize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_init(trace_attr_t *); +int posix_trace_attr_setinherited(trace_attr_t *, int); +int posix_trace_attr_setlogfullpolicy(trace_attr_t *, int); +int posix_trace_attr_setlogsize(trace_attr_t *, size_t); +int posix_trace_attr_setmaxdatasize(trace_attr_t *, size_t); +int posix_trace_attr_setname(trace_attr_t *, const char *); +int posix_trace_attr_setstreamfullpolicy(trace_attr_t *, int); +int posix_trace_attr_setstreamsize(trace_attr_t *, size_t); +int posix_trace_clear(trace_id_t); +int posix_trace_close(trace_id_t); +int posix_trace_create(pid_t, const trace_attr_t *restrict, + trace_id_t *restrict); +int posix_trace_create_withlog(pid_t, const trace_attr_t *restrict, + int, trace_id_t *restrict); +void posix_trace_event(trace_event_id_t, const void *restrict, size_t); +int posix_trace_eventid_equal(trace_id_t, trace_event_id_t, + trace_event_id_t); +int posix_trace_eventid_get_name(trace_id_t, trace_event_id_t, char *); +int posix_trace_eventid_open(const char *restrict, + trace_event_id_t *restrict); +int posix_trace_eventset_add(trace_event_id_t, trace_event_set_t *); +int posix_trace_eventset_del(trace_event_id_t, trace_event_set_t *); +int posix_trace_eventset_empty(trace_event_set_t *); +int posix_trace_eventset_fill(trace_event_set_t *, int); +int posix_trace_eventset_ismember(trace_event_id_t, + const trace_event_set_t *restrict, int *restrict); +int posix_trace_eventtypelist_getnext_id(trace_id_t, + trace_event_id_t *restrict, int *restrict); +int posix_trace_eventtypelist_rewind(trace_id_t); +int posix_trace_flush(trace_id_t); +int posix_trace_get_attr(trace_id_t, trace_attr_t *); +int posix_trace_get_filter(trace_id_t, trace_event_set_t *); +int posix_trace_get_status(trace_id_t, + struct posix_trace_status_info *); +int posix_trace_getnext_event(trace_id_t, + struct posix_trace_event_info *restrict, void *restrict, + size_t, size_t *restrict, int *restrict); +int posix_trace_open(int, trace_id_t *); +int posix_trace_rewind(trace_id_t); +int posix_trace_set_filter(trace_id_t, const trace_event_set_t *, int); +int posix_trace_shutdown(trace_id_t); +int posix_trace_start(trace_id_t); +int posix_trace_stop(trace_id_t); +int posix_trace_timedgetnext_event(trace_id_t, + struct posix_trace_event_info *restrict, void *restrict, + size_t, size_t *restrict, int *restrict, + const struct timespec *restrict); +int posix_trace_trid_eventid_open(trace_id_t, const char *restrict, + trace_event_id_t *restrict); +int posix_trace_trygetnext_event(trace_id_t, + struct posix_trace_event_info *restrict, void *restrict, size_t, + size_t *restrict, int *restrict); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +.IR +header may be removed in a future version. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.11" ", " "Tracing", +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_attr_getclockres\fR\^(\|)", +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)", +.IR "\fIposix_trace_attr_getlogsize\fR\^(\|)", +.IR "\fIposix_trace_clear\fR\^(\|)", +.IR "\fIposix_trace_close\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_eventset_add\fR\^(\|)", +.IR "\fIposix_trace_eventtypelist_getnext_id\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIposix_trace_get_filter\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/ulimit.h.0p b/man-pages-posix-2013-a/man0p/ulimit.h.0p new file mode 100644 index 0000000..284107b --- /dev/null +++ b/man-pages-posix-2013-a/man0p/ulimit.h.0p @@ -0,0 +1,68 @@ +'\" et +.TH ulimit.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ulimit.h +\(em ulimit commands +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the symbolic constants used by the +\fIulimit\fR() +function. +.P +Symbolic constants: +.IP UL_GETFSIZE 12 +Get maximum file size. +.IP UL_SETFSIZE 12 +Set maximum file size. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +long ulimit(int, ...); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +See +\fIulimit\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIulimit\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/unistd.h.0p b/man-pages-posix-2013-a/man0p/unistd.h.0p new file mode 100644 index 0000000..a2a9b7c --- /dev/null +++ b/man-pages-posix-2013-a/man0p/unistd.h.0p @@ -0,0 +1,1621 @@ +'\" et +.TH unistd.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unistd.h +\(em standard symbolic constants and types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header defines miscellaneous symbolic constants and types, and declares +miscellaneous functions. The actual values of the constants are +unspecified except as shown. The contents of this header are shown +below. +.SS "Version Test Macros" +.P +The +.IR +header shall define the following symbolic constants. The values shall +be suitable for use in +.BR #if +preprocessing directives. +.IP _POSIX_VERSION 6 +.br +Integer value indicating version of this standard (C-language +binding) to which the implementation conforms. For implementations +conforming to POSIX.1\(hy2008, the value shall be 200809L. +.IP _POSIX2_VERSION 6 +.br +Integer value indicating version of the Shell and Utilities volume of POSIX.1 to which the implementation +conforms. For implementations conforming to POSIX.1\(hy2008, the value shall +be 200809L. For profile implementations that define _POSIX_SUBPROFILE +(see +.IR "Section 2.1.5.1" ", " "Subprofiling Considerations") +in +.IR , +POSIX2_VERSION may be left undefined or be defined with the value \(mi1 +to indicate that the Shell and Utilities volume of POSIX.1 is not supported. In this case, a call to +.IR sysconf(_SC_2_VERSION) +shall return either 200809L or \(mi1 indicating that the Shell and Utilities volume of POSIX.1 is or is +not, respectively, supported at runtime. +.P +The +.IR +header shall define the following symbolic constant only if +the implementation supports the XSI option; see +.IR "Section 2.1.4" ", " "XSI Conformance". +If defined, its value shall be suitable for use in +.BR #if +preprocessing directives. +.IP _XOPEN_VERSION 6 +.br +Integer value indicating version of the X/Open Portability Guide +to which the implementation conforms. The value shall be 700. +.SS "Constants for Options and Option Groups" +.P +The following symbolic constants, if defined in +.IR , +shall have a value of \(mi1, 0, or greater, unless otherwise specified +below. For profile implementations that define _POSIX_SUBPROFILE (see +.IR "Section 2.1.5.1" ", " "Subprofiling Considerations") +in +.IR , +constants described below as always having a value greater than zero need +not be defined and, if defined, may have a value of \(mi1, 0, or greater. +The values shall be suitable for use in +.BR #if +preprocessing directives. +.P +If a symbolic constant is not defined or is defined with the value +\(mi1, the option is not supported for compilation. If it is defined +with a value greater than zero, the option shall always be supported +when the application is executed. If it is defined with the value zero, +the option shall be supported for compilation and might or might not be +supported at runtime. See +.IR "Section 2.1.6" ", " "Options" +for further information about the conformance requirements of these +three categories of support. +.IP _POSIX_ADVISORY_INFO 6 +.br +The implementation supports the Advisory Information option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_ASYNCHRONOUS_IO 6 +.br +The implementation supports asynchronous input and output. +This symbol shall always be set to the value 200809L. +.IP _POSIX_BARRIERS 6 +.br +The implementation supports barriers. +This symbol shall always be set to the value 200809L. +.IP _POSIX_CHOWN_RESTRICTED 6 +.br +The use of +\fIchown\fR() +and +\fIfchown\fR() +is restricted to a process with appropriate privileges, and to changing +the group ID of a file only to the effective group ID of the process or +to one of its supplementary group IDs. This symbol shall be defined +with a value other than \(mi1. +.IP _POSIX_CLOCK_SELECTION 6 +.br +The implementation supports clock selection. +This symbol shall always be set to the value 200809L. +.IP _POSIX_CPUTIME 6 +.br +The implementation supports the Process CPU-Time Clocks option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_FSYNC 6 +.br +The implementation supports the File Synchronization option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_IPV6 6 +.br +The implementation supports the IPv6 option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_JOB_CONTROL 6 +.br +The implementation supports job control. This symbol shall always be +set to a value greater than zero. +.IP _POSIX_MAPPED_FILES 6 +.br +The implementation supports memory mapped Files. +This symbol shall always be set to the value 200809L. +.IP _POSIX_MEMLOCK 6 +.br +The implementation supports the Process Memory Locking option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_MEMLOCK_RANGE 6 +.br +The implementation supports the Range Memory Locking option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_MEMORY_PROTECTION 6 +.br +The implementation supports memory protection. +This symbol shall always be set to the value 200809L. +.IP _POSIX_MESSAGE_PASSING 6 +.br +The implementation supports the Message Passing option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_MONOTONIC_CLOCK 6 +.br +The implementation supports the Monotonic Clock option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_NO_TRUNC 6 +.br +Pathname components longer than +{NAME_MAX} +generate an error. This symbol shall be defined with a value +other than \(mi1. +.IP _POSIX_PRIORITIZED_IO 6 +.br +The implementation supports the Prioritized Input and Output option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_PRIORITY_SCHEDULING 6 +.br +The implementation supports the Process Scheduling option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_RAW_SOCKETS 6 +.br +The implementation supports the Raw Sockets option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_READER_WRITER_LOCKS 6 +.br +The implementation supports read-write locks. +This symbol shall always be set to the value 200809L. +.IP _POSIX_REALTIME_SIGNALS 6 +.br +The implementation supports realtime signals. +This symbol shall always be set to the value 200809L. +.IP _POSIX_REGEXP 6 +.br +The implementation supports the Regular Expression Handling option. +This symbol shall always be set to a value greater than zero. +.IP _POSIX_SAVED_IDS 6 +.br +Each process has a saved set-user-ID and a saved set-group-ID. +This symbol shall always be set to a value greater than zero. +.IP _POSIX_SEMAPHORES 6 +.br +The implementation supports semaphores. +This symbol shall always be set to the value 200809L. +.IP _POSIX_SHARED_MEMORY_OBJECTS 6 +.br +The implementation supports the Shared Memory Objects option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_SHELL 6 +.br +The implementation supports the POSIX shell. This symbol shall always +be set to a value greater than zero. +.IP _POSIX_SPAWN 6 +.br +The implementation supports the Spawn option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_SPIN_LOCKS 6 +.br +The implementation supports spin locks. +This symbol shall always be set to the value 200809L. +.IP _POSIX_SPORADIC_SERVER 6 +.br +The implementation supports the Process Sporadic Server option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_SYNCHRONIZED_IO 6 +.br +The implementation supports the Synchronized Input and Output option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_ATTR_STACKADDR 6 +.br +The implementation supports the Thread Stack Address Attribute option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_ATTR_STACKSIZE 6 +.br +The implementation supports the Thread Stack Size Attribute option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_CPUTIME 6 +.br +The implementation supports the Thread CPU-Time Clocks option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_PRIO_INHERIT 6 +.br +The implementation supports the Non-Robust Mutex Priority +Inheritance option. If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_PRIO_PROTECT 6 +.br +The implementation supports the Non-Robust Mutex Priority +Protection option. If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_PRIORITY_SCHEDULING 6 +.br +The implementation supports the Thread Execution Scheduling option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_PROCESS_SHARED 6 +.br +The implementation supports the Thread Process-Shared Synchronization +option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_ROBUST_PRIO_INHERIT 6 +.br +The implementation supports the Robust Mutex Priority Inheritance +option. If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_ROBUST_PRIO_PROTECT 6 +.br +The implementation supports the Robust Mutex Priority Protection +option. If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_SAFE_FUNCTIONS 6 +.br +The implementation supports thread-safe functions. +This symbol shall always be set to the value 200809L. +.IP _POSIX_THREAD_SPORADIC_SERVER 6 +.br +The implementation supports the Thread Sporadic Server option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREADS 6 +.br +The implementation supports threads. +This symbol shall always be set to the value 200809L. +.IP _POSIX_TIMEOUTS 6 +.br +The implementation supports timeouts. +This symbol shall always be set to the value 200809L. +.IP _POSIX_TIMERS 6 +.br +The implementation supports timers. +This symbol shall always be set to the value 200809L. +.IP _POSIX_TRACE 6 +.br +The implementation supports the Trace option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_TRACE_EVENT_FILTER 6 +.br +The implementation supports the Trace Event Filter option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_TRACE_INHERIT 6 +.br +The implementation supports the Trace Inherit option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_TRACE_LOG 6 +.br +The implementation supports the Trace Log option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_TYPED_MEMORY_OBJECTS 6 +.br +The implementation supports the Typed Memory Objects option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_V6_ILP32_OFF32 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _POSIX_V6_ILP32_OFFBIG 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int , +.BR long , +and +.BR pointer +types and an +.BR off_t +type using at least 64 bits. +.IP _POSIX_V6_LP64_OFF64 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _POSIX_V6_LPBIG_OFFBIG 6 +.br +The implementation provides a C-language compilation environment with +an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _POSIX_V7_ILP32_OFF32 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _POSIX_V7_ILP32_OFFBIG 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int , +.BR long , +and +.BR pointer +types and an +.BR off_t +type using at least 64 bits. +.IP _POSIX_V7_LP64_OFF64 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _POSIX_V7_LPBIG_OFFBIG 6 +.br +The implementation provides a C-language compilation environment with +an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _POSIX2_C_BIND 6 +.br +The implementation supports the C-Language Binding option. This +symbol shall always have the value 200809L. +.IP _POSIX2_C_DEV 6 +.br +The implementation supports the C-Language Development Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_CHAR_TERM 6 +.br +The implementation supports the Terminal Characteristics option. +The value of this symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or a value greater than zero. +.IP _POSIX2_FORT_DEV 6 +.br +The implementation supports the FORTRAN Development Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_FORT_RUN 6 +.br +The implementation supports the FORTRAN Runtime Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_LOCALEDEF 6 +.br +The implementation supports the creation of locales by the +.IR localedef +utility. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS 6 +.br +The implementation supports the Batch Environment Services and +Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_ACCOUNTING 6 +.br +The implementation supports the Batch Accounting option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_CHECKPOINT 6 +.br +The implementation supports the Batch Checkpoint/Restart option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_LOCATE 6 +.br +The implementation supports the Locate Batch Job Request option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_MESSAGE 6 +.br +The implementation supports the Batch Job Message Request option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_TRACK 6 +.br +The implementation supports the Track Batch Job Request option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_SW_DEV 6 +.br +The implementation supports the Software Development Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_UPE 6 +.br +The implementation supports the User Portability Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _XOPEN_CRYPT 6 +.br +The implementation supports the X/Open Encryption Option Group. +.IP _XOPEN_ENH_I18N 6 +.br +The implementation supports the Issue 4, Version 2 Enhanced +Internationalization Option Group. This symbol shall always be set +to a value other than \(mi1. +.IP _XOPEN_REALTIME 6 +.br +The implementation supports the X/Open Realtime Option Group. +.IP _XOPEN_REALTIME_THREADS 6 +.br +The implementation supports the X/Open Realtime Threads Option Group. +.IP _XOPEN_SHM 6 +.br +The implementation supports the Issue 4, Version 2 Shared Memory Option +Group. This symbol shall always be set to a value other than \(mi1. +.IP _XOPEN_STREAMS 6 +.br +The implementation supports the XSI STREAMS Option Group. +.IP _XOPEN_UNIX 6 +.br +The implementation supports the XSI option. +.IP _XOPEN_UUCP 6 +.br +The implementation supports the UUCP Utilities option. If this symbol +is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this symbol +reported by +\fIsysconf\fR() +shall be either \(mi1 or 200809L. +.SS "Execution-Time Symbolic Constants" +.P +If any of the following symbolic constants are not defined in the +.IR +header, the value shall vary depending on the file to which it +is applied. If defined, they shall have values suitable for use in +.BR #if +preprocessing directives. +.P +If any of the following symbolic constants are defined to have value +\(mi1 in the +.IR +header, the implementation shall not provide the option on any file; if +any are defined to have a value other than \(mi1 in the +.IR +header, the implementation shall provide the option on all applicable +files. +.P +All of the following values, whether defined as symbolic constants in +.IR +or not, may be queried with respect to a specific file using the +\fIpathconf\fR() +or +\fIfpathconf\fR() +functions: +.IP _POSIX_ASYNC_IO 6 +.br +Asynchronous input or output operations may be performed for the +associated file. +.IP _POSIX_PRIO_IO 6 +.br +Prioritized input or output operations may be performed for the +associated file. +.IP _POSIX_SYNC_IO 6 +.br +Synchronized input or output operations may be performed for the +associated file. +.P +If the following symbolic constants are defined in the +.IR +header, they apply to files and all paths in all file systems on +the implementation: +.IP _POSIX_TIMESTAMP_RESOLUTION 6 +.br +The resolution in nanoseconds for all file timestamps. +.IP _POSIX2_SYMLINKS 6 +.br +Symbolic links can be created. +.SS "Constants for Functions" +.P +The +.IR +header shall define NULL as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants for use with the +\fIaccess\fR() +function. The values shall be suitable for use in +.BR #if +preprocessing directives. +.IP F_OK 12 +Test for existence of file. +.IP R_OK 12 +Test for read permission. +.IP W_OK 12 +Test for write permission. +.IP X_OK 12 +Test for execute (search) permission. +.P +The constants F_OK, R_OK, W_OK, and X_OK and the expressions +\fIR_OK\fP|\fIW_OK\fP, \fIR_OK\fP|\fIX_OK\fP, and +\fIR_OK\fP|\fIW_OK\fP|\fIX_OK\fP shall all have distinct values. +.P +The +.IR +header shall define the following symbolic constants for the +\fIconfstr\fR() +function: +.IP _CS_PATH 6 +.br +This is the value for the +.IR PATH +environment variable that finds all standard utilities. +.IP _CS_POSIX_V7_ILP32_OFF32_CFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFF32) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of initial +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_ILP32_OFF32_LDFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFF32) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of final +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_ILP32_OFF32_LIBS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFF32) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of +libraries to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_ILP32_OFFBIG_CFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of initial +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +and +.BR pointer +types, and an +.BR off_t +type using at least 64 bits. +.IP _CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of final +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +and +.BR pointer +types, and an +.BR off_t +type using at least 64 bits. +.IP _CS_POSIX_V7_ILP32_OFFBIG_LIBS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of +libraries to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +and +.BR pointer +types, and an +.BR off_t +type using at least 64 bits. +.IP _CS_POSIX_V7_LP64_OFF64_CFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_LP64_OFF64) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of initial +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_LP64_OFF64_LDFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_LP64_OFF64) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of final +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_LP64_OFF64_LIBS 6 +.br +If \fIsysconf\fP(_SC_V7_LP64_OFF64) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of +libraries to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_LPBIG_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of initial +options to be given to the +.IR c99 +utility to build an application using a programming model with an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_LPBIG_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of final +options to be given to the +.IR c99 +utility to build an application using a programming model with an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _CS_POSIX_V7_LPBIG_OFFBIG_LIBS 6 +.br +If \fIsysconf\fP(_SC_V7_LPBIG_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of +libraries to be given to the +.IR c99 +utility to build an application using a programming model with an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _CS_POSIX_V7_THREADS_CFLAGS 6 +.br +If +.IR sysconf (_SC_POSIX_THREADS) +returns \(mi1, the meaning of this value is unspecified. Otherwise, +this value is the set of initial options to be given to the +.IR c99 +utility to build a multi-threaded application. These flags are in addition +to those associated with any of the other _CS_POSIX_V7_*_CFLAGS values +used to specify particular type size programing environments. +.IP _CS_POSIX_V7_THREADS_LDFLAGS 6 +.br +If +.IR sysconf (_SC_POSIX_THREADS) +returns \(mi1, the meaning of this value is unspecified. Otherwise, +this value is the set of final options to be given to the +.IR c99 +utility to build a multi-threaded application. These flags are in addition +to those associated with any of the other _CS_POSIX_V7_*_LDFLAGS values +used to specify particular type size programing environments. +.IP _CS_POSIX_V7_WIDTH_RESTRICTED_ENVS 6 +.br +This value is a +-separated +list of names of programming environments supported by the +implementation in which the widths of the +.BR blksize_t , +.BR cc_t , +.BR mode_t , +.BR nfds_t , +.BR pid_t , +.BR ptrdiff_t , +.BR size_t , +.BR speed_t , +.BR ssize_t , +.BR suseconds_t , +.BR tcflag_t , +.BR wchar_t , +and +.BR wint_t +types are no greater than the width of type +.BR long . +The format of each name shall be suitable for use with the +.IR getconf +.BR \(miv +option. +.IP _CS_V7_ENV 6 +.br +This is the value that provides the environment variable information +(other than that provided by _CS_PATH) that is required by the +implementation to create a conforming environment, as described in the +implementation's conformance documentation. +.br +.P +The following symbolic constants are reserved for compatibility +with Issue 6: +.P +.nf +_CS_POSIX_V6_ILP32_OFF32_CFLAGS +_CS_POSIX_V6_ILP32_OFF32_LDFLAGS +_CS_POSIX_V6_ILP32_OFF32_LIBS +_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS +_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS +_CS_POSIX_V6_ILP32_OFFBIG_LIBS +_CS_POSIX_V6_LP64_OFF64_CFLAGS +_CS_POSIX_V6_LP64_OFF64_LDFLAGS +_CS_POSIX_V6_LP64_OFF64_LIBS +_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS +_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS +_CS_POSIX_V6_LPBIG_OFFBIG_LIBS +_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS +_CS_V6_ENV +.fi +.P +The +.IR +header shall define SEEK_CUR, SEEK_END, and SEEK_SET as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants as possible +values for the +.IR function +argument to the +\fIlockf\fR() +function: +.IP F_LOCK 12 +Lock a section for exclusive use. +.IP F_TEST 12 +Test section for locks by other processes. +.IP F_TLOCK 12 +Test and lock a section for exclusive use. +.IP F_ULOCK 12 +Unlock locked sections. +.P +The +.IR +header shall define the following symbolic constants for +\fIpathconf\fR(): +.P +.nf +_PC_2_SYMLINKS +_PC_ALLOC_SIZE_MIN +_PC_ASYNC_IO +_PC_CHOWN_RESTRICTED +_PC_FILESIZEBITS +_PC_LINK_MAX +_PC_MAX_CANON +_PC_MAX_INPUT +_PC_NAME_MAX +_PC_NO_TRUNC +_PC_PATH_MAX +_PC_PIPE_BUF +_PC_PRIO_IO +_PC_REC_INCR_XFER_SIZE +_PC_REC_MAX_XFER_SIZE +_PC_REC_MIN_XFER_SIZE +_PC_REC_XFER_ALIGN +_PC_SYMLINK_MAX +_PC_SYNC_IO +_PC_TIMESTAMP_RESOLUTION +_PC_VDISABLE +.fi +.P +The +.IR +header shall define the following symbolic constants for +\fIsysconf\fR(): +.P +.nf +_SC_2_C_BIND +_SC_2_C_DEV +_SC_2_CHAR_TERM +_SC_2_FORT_DEV +_SC_2_FORT_RUN +_SC_2_LOCALEDEF +_SC_2_PBS +_SC_2_PBS_ACCOUNTING +_SC_2_PBS_CHECKPOINT +_SC_2_PBS_LOCATE +_SC_2_PBS_MESSAGE +_SC_2_PBS_TRACK +_SC_2_SW_DEV +_SC_2_UPE +_SC_2_VERSION +_SC_ADVISORY_INFO +_SC_AIO_LISTIO_MAX +_SC_AIO_MAX +_SC_AIO_PRIO_DELTA_MAX +_SC_ARG_MAX +_SC_ASYNCHRONOUS_IO +_SC_ATEXIT_MAX +_SC_BARRIERS +_SC_BC_BASE_MAX +_SC_BC_DIM_MAX +_SC_BC_SCALE_MAX +_SC_BC_STRING_MAX +_SC_CHILD_MAX +_SC_CLK_TCK +_SC_CLOCK_SELECTION +_SC_COLL_WEIGHTS_MAX +_SC_CPUTIME +_SC_DELAYTIMER_MAX +_SC_EXPR_NEST_MAX +_SC_FSYNC +_SC_GETGR_R_SIZE_MAX +_SC_GETPW_R_SIZE_MAX +_SC_HOST_NAME_MAX +_SC_IOV_MAX +_SC_IPV6 +_SC_JOB_CONTROL +_SC_LINE_MAX +_SC_LOGIN_NAME_MAX +_SC_MAPPED_FILES +_SC_MEMLOCK +_SC_MEMLOCK_RANGE +_SC_MEMORY_PROTECTION +_SC_MESSAGE_PASSING +_SC_MONOTONIC_CLOCK +_SC_MQ_OPEN_MAX +_SC_MQ_PRIO_MAX +_SC_NGROUPS_MAX +_SC_OPEN_MAX +_SC_PAGE_SIZE +_SC_PAGESIZE +_SC_PRIORITIZED_IO +_SC_PRIORITY_SCHEDULING +_SC_RAW_SOCKETS +_SC_RE_DUP_MAX +_SC_READER_WRITER_LOCKS +_SC_REALTIME_SIGNALS +_SC_REGEXP +_SC_RTSIG_MAX +_SC_SAVED_IDS +_SC_SEM_NSEMS_MAX +_SC_SEM_VALUE_MAX +_SC_SEMAPHORES +_SC_SHARED_MEMORY_OBJECTS +_SC_SHELL +_SC_SIGQUEUE_MAX +_SC_SPAWN +_SC_SPIN_LOCKS +_SC_SPORADIC_SERVER +_SC_SS_REPL_MAX +_SC_STREAM_MAX +_SC_SYMLOOP_MAX +_SC_SYNCHRONIZED_IO +_SC_THREAD_ATTR_STACKADDR +_SC_THREAD_ATTR_STACKSIZE +_SC_THREAD_CPUTIME +_SC_THREAD_DESTRUCTOR_ITERATIONS +_SC_THREAD_KEYS_MAX +_SC_THREAD_PRIO_INHERIT +_SC_THREAD_PRIO_PROTECT +_SC_THREAD_PRIORITY_SCHEDULING +_SC_THREAD_PROCESS_SHARED +_SC_THREAD_ROBUST_PRIO_INHERIT +_SC_THREAD_ROBUST_PRIO_PROTECT +_SC_THREAD_SAFE_FUNCTIONS +_SC_THREAD_SPORADIC_SERVER +_SC_THREAD_STACK_MIN +_SC_THREAD_THREADS_MAX +_SC_THREADS +_SC_TIMEOUTS +_SC_TIMER_MAX +_SC_TIMERS +_SC_TRACE +_SC_TRACE_EVENT_FILTER +_SC_TRACE_EVENT_NAME_MAX +_SC_TRACE_INHERIT +_SC_TRACE_LOG +_SC_TRACE_NAME_MAX +_SC_TRACE_SYS_MAX +_SC_TRACE_USER_EVENT_MAX +_SC_TTY_NAME_MAX +_SC_TYPED_MEMORY_OBJECTS +_SC_TZNAME_MAX +_SC_V7_ILP32_OFF32 +_SC_V7_ILP32_OFFBIG +_SC_V7_LP64_OFF64 +_SC_V7_LPBIG_OFFBIG +_SC_V6_ILP32_OFF32 +_SC_V6_ILP32_OFFBIG +_SC_V6_LP64_OFF64 +_SC_V6_LPBIG_OFFBIG +_SC_VERSION +_SC_XOPEN_CRYPT +_SC_XOPEN_ENH_I18N +_SC_XOPEN_REALTIME +_SC_XOPEN_REALTIME_THREADS +_SC_XOPEN_SHM +_SC_XOPEN_STREAMS +_SC_XOPEN_UNIX +_SC_XOPEN_UUCP +_SC_XOPEN_VERSION +.fi +.P +The two constants _SC_PAGESIZE and _SC_PAGE_SIZE may be defined to +have the same value. +.P +The +.IR +header shall define the following symbolic constants for file streams: +.IP STDERR_FILENO 14 +File number of +.IR stderr ; +2. +.IP STDIN_FILENO 14 +File number of +.IR stdin ; +0. +.IP STDOUT_FILENO 14 +File number of +.IR stdout ; +1. +.P +The +.IR +header shall define the following symbolic constant for terminal +special character handling: +.IP _POSIX_VDISABLE 14 +This symbol shall be defined to be the value of a character that shall +disable terminal special character handling as described in +.IR "Section 11.2.6" ", " "Special Control Characters". +This symbol shall always be set to a value other than \(mi1. +.SS "Type Definitions" +.P +The +.IR +header shall define the +.BR size_t , +.BR ssize_t , +.BR uid_t , +.BR gid_t , +.BR off_t , +and +.BR pid_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR intptr_t +type as described in +.IR . +.SS "Declarations" +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int access(const char *, int); +unsigned alarm(unsigned); +int chdir(const char *); +int chown(const char *, uid_t, gid_t); +int close(int); +size_t confstr(int, char *, size_t); +char *crypt(const char *, const char *); +int dup(int); +.br +int dup2(int, int); +void _exit(int); +void encrypt(char [64], int); +int execl(const char *, const char *, ...); +int execle(const char *, const char *, ...); +int execlp(const char *, const char *, ...); +int execv(const char *, char *const []); +int execve(const char *, char *const [], char *const []); +int execvp(const char *, char *const []); +int faccessat(int, const char *, int, int); +int fchdir(int); +int fchown(int, uid_t, gid_t); +int fchownat(int, const char *, uid_t, gid_t, int); +int fdatasync(int); +int fexecve(int, char *const [], char *const []); +pid_t fork(void); +long fpathconf(int, int); +int fsync(int); +int ftruncate(int, off_t); +char *getcwd(char *, size_t); +gid_t getegid(void); +uid_t geteuid(void); +gid_t getgid(void); +int getgroups(int, gid_t []); +long gethostid(void); +int gethostname(char *, size_t); +char *getlogin(void); +int getlogin_r(char *, size_t); +int getopt(int, char * const [], const char *); +pid_t getpgid(pid_t); +pid_t getpgrp(void); +pid_t getpid(void); +pid_t getppid(void); +pid_t getsid(pid_t); +uid_t getuid(void); +int isatty(int); +int lchown(const char *, uid_t, gid_t); +int link(const char *, const char *); +int linkat(int, const char *, int, const char *, int); +int lockf(int, int, off_t); +off_t lseek(int, off_t, int); +int nice(int); +long pathconf(const char *, int); +int pause(void); +int pipe(int [2]); +ssize_t pread(int, void *, size_t, off_t); +ssize_t pwrite(int, const void *, size_t, off_t); +ssize_t read(int, void *, size_t); +ssize_t readlink(const char *restrict, char *restrict, size_t); +ssize_t readlinkat(int, const char *restrict, char *restrict, size_t); +int rmdir(const char *); +int setegid(gid_t); +int seteuid(uid_t); +int setgid(gid_t); +.br +int setpgid(pid_t, pid_t); +pid_t setpgrp(void); +int setregid(gid_t, gid_t); +int setreuid(uid_t, uid_t); +pid_t setsid(void); +int setuid(uid_t); +unsigned sleep(unsigned); +void swab(const void *restrict, void *restrict, ssize_t); +int symlink(const char *, const char *); +int symlinkat(const char *, int, const char *); +void sync(void); +long sysconf(int); +pid_t tcgetpgrp(int); +int tcsetpgrp(int, pid_t); +int truncate(const char *, off_t); +char *ttyname(int); +int ttyname_r(int, char *, size_t); +int unlink(const char *); +int unlinkat(int, const char *, int); +ssize_t write(int, const void *, size_t); +.fi \fR +.P +.RE +.P +Implementations may also include the +\fIpthread_atfork\fR() +prototype as defined in +.IR . +Implementations may also include the +\fIctermid\fR() +prototype as defined in +.IR . +.P +The +.IR +header shall declare the following external variables: +.sp +.RS 4 +.nf +\fB +extern char *optarg; +extern int opterr, optind, optopt; +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +POSIX.1\(hy2008 only describes the behavior of systems that claim conformance to +it. However, application developers who want to write applications that +adapt to other versions of this standard (or to systems that do not +conform to any POSIX standard) may find it useful to code them so as to +conditionally compile different code depending on the value of +_POSIX_VERSION, for example: +.sp +.RS 4 +.nf +\fB +#if _POSIX_VERSION >= 200112L +/* Use the newer function that copes with large files. */ +off_t pos=ftello(fp); +#else +/* Either this is an old version of POSIX, or _POSIX_VERSION is + not even defined, so use the traditional function. */ +long pos=ftell(fp); +#endif +.fi \fR +.P +.RE +.P +Earlier versions of POSIX.1\(hy2008 and of the Single UNIX Specification +can be identified by the following macros: +.IP "POSIX.1\(hy1988 standard" 6 +.br +_POSIX_VERSION\|=\^=\|198808L +.IP "POSIX.1\(hy1990 standard" 6 +.br +_POSIX_VERSION\|=\^=\|199009L +.IP "ISO\ POSIX\(hy1:\|1996 standard" 6 +.br +_POSIX_VERSION\|=\^=\|199506L +.IP "Single UNIX Specification, Version 1" 6 +.br +_XOPEN_UNIX and _XOPEN_VERSION\|=\^=\|4 +.IP "Single UNIX Specification, Version 2" 6 +.br +_XOPEN_UNIX and _XOPEN_VERSION\|=\^=\|500 +.IP "ISO POSIX\(hy1:\|2001 and Single UNIX Specification, Version 3" 6 +.br +_POSIX_VERSION\|=\^=\|200112L, plus (if the XSI option is supported) +_XOPEN_UNIX and _XOPEN_VERSION\|=\^=\|600 +.P +POSIX.1\(hy2008 does not make any attempt to define application binary +interaction with the underlying operating system. However, application +developers may find it useful to query _SC_VERSION at runtime via +\fIsysconf\fR() +to determine whether the current version of the operating system +supports the necessary functionality as in the following program +fragment: +.sp +.RS 4 +.nf +\fB +if (sysconf(_SC_VERSION) < 200809L) { + fprintf(stderr, "POSIX.1-2008 system required, terminating \en"); + exit(1); +} +.fi \fR +.P +.RE +.P +New applications should not use _XOPEN_SHM or _XOPEN_ENH_I18N. +.SH RATIONALE +As POSIX.1\(hy2008 evolved, certain options became sufficiently standardized that +it was concluded that simply requiring one of the option choices was +simpler than retaining the option. However, for backwards-compatibility, +the option flags (with required constant values) are retained. +.SS "Version Test Macros" +.P +The standard developers considered altering the definition of +_POSIX_VERSION and removing _SC_VERSION from the specification of +\fIsysconf\fR() +since the utility to an application was deemed by some to be minimal, +and since the implementation of the functionality is potentially +problematic. However, they recognized that support for existing +application binaries is a concern to manufacturers, application +developers, and the users of implementations conforming to POSIX.1\(hy2008. +.P +While the example using _SC_VERSION in the APPLICATION USAGE section +does not provide the greatest degree of imaginable utility to the +application developer or user, it is arguably better than a +.BR core +file or some other equally obscure result. (It is also possible for +implementations to encode and recognize application binaries compiled +in various POSIX.1-conforming environments, and modify the semantics of +the underlying system to conform to the expectations of the +application.) For the reasons outlined in the preceding paragraphs and +in the APPLICATION USAGE section, the standard developers elected to +retain the _POSIX_VERSION and _SC_VERSION functionality. +.SS "Compile-Time Symbolic Constants for System-Wide Options" +.P +POSIX.1\(hy2008 includes support in certain areas for the newly adopted +policy governing options and stubs. +.P +This policy provides flexibility for implementations in how they +support options. It also specifies how conforming applications can +adapt to different implementations that support different sets of +options. It allows the following: +.IP " 1." 4 +If an implementation has no interest in supporting an option, it does +not have to provide anything associated with that option beyond the +announcement that it does not support it. +.IP " 2." 4 +An implementation can support a partial or incompatible version of an +option (as a non-standard extension) as long as it does not claim to +support the option. +.IP " 3." 4 +An application can determine whether the option is supported. A +strictly conforming application must check this announcement mechanism +before first using anything associated with the option. +.P +There is an important implication of this policy. POSIX.1\(hy2008 cannot +dictate the behavior of interfaces associated with an option when the +implementation does not claim to support the option. In particular, it +cannot require that a function associated with an unsupported option +will fail if it does not perform as specified. However, this policy +does not prevent a standard from requiring certain functions to always +be present, but that they shall always fail on some implementations. +The +\fIsetpgid\fR() +function in the POSIX.1\(hy1990 standard, for example, is considered appropriate. +.P +The POSIX standards include various options, and the C-language +binding support for an option implies that the implementation must +supply data types and function interfaces. An application must be able +to discover whether the implementation supports each option. +.P +Any application must consider the following three cases for each +option: +.IP " 1." 4 +Option never supported. +.RS 4 +.P +The implementation advertises at compile time that the option will +never be supported. In this case, it is not necessary for the +implementation to supply any of the data types or function interfaces +that are provided only as part of the option. The implementation might +provide data types and functions that are similar to those defined by +POSIX.1\(hy2008, but there is no guarantee for any particular behavior. +.RE +.IP " 2." 4 +Option always supported. +.RS 4 +.P +The implementation advertises at compile time that the option will +always be supported. In this case, all data types and function +interfaces shall be available and shall operate as specified. +.RE +.IP " 3." 4 +Option might or might not be supported. +.RS 4 +.P +Some implementations might not provide a mechanism to specify support +of options at compile time. In addition, the implementation might be +unable or unwilling to specify support or non-support at compile time. +In either case, any application that might use the option at runtime +must be able to compile and execute. The implementation must provide, +at compile time, all data types and function interfaces that are +necessary to allow this. In this situation, there must be a mechanism +that allows the application to query, at runtime, whether the option is +supported. If the application attempts to use the option when it is not +supported, the result is unspecified unless explicitly specified +otherwise in POSIX.1\(hy2008. +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaccess\fR\^(\|)", +.IR "\fIalarm\fR\^(\|)", +.IR "\fIchown\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIcrypt\fR\^(\|)", +.IR "\fIctermid\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fI_Exit\fR\^(\|)", +.IR "\fIencrypt\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfchdir\fR\^(\|)", +.IR "\fIfchown\fR\^(\|)", +.IR "\fIfdatasync\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIfsync\fR\^(\|)", +.IR "\fIftruncate\fR\^(\|)", +.IR "\fIgetcwd\fR\^(\|)", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetgroups\fR\^(\|)", +.IR "\fIgethostid\fR\^(\|)", +.IR "\fIgethostname\fR\^(\|)", +.IR "\fIgetlogin\fR\^(\|)", +.IR "\fIgetopt\fR\^(\|)", +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetppid\fR\^(\|)", +.IR "\fIgetsid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIisatty\fR\^(\|)", +.IR "\fIlchown\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIlockf\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fInice\fR\^(\|)", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIreadlink\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetpgrp\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)", +.IR "\fIswab\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIsync\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fItcgetpgrp\fR\^(\|)", +.IR "\fItcsetpgrp\fR\^(\|)", +.IR "\fItruncate\fR\^(\|)", +.IR "\fIttyname\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/utime.h.0p b/man-pages-posix-2013-a/man0p/utime.h.0p new file mode 100644 index 0000000..9474f4f --- /dev/null +++ b/man-pages-posix-2013-a/man0p/utime.h.0p @@ -0,0 +1,91 @@ +'\" et +.TH utime.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +utime.h +\(em access and modification times structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall declare the +.BR utimbuf +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +time_t actime \fRAccess time.\fR +time_t modtime \fRModification time.\fR +.fi \fR +.P +.RE +.P +The times shall be measured in seconds since the Epoch. +.P +The +.IR +header shall define the +.BR time_t +type as described in +.IR . +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +int utime(const char *, const struct utimbuf *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +\fIutime\fR() +function only allows setting file timestamps to the nearest second. +Applications should use the +\fIutimensat\fR() +function instead. See +.IR . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +.IR +header may be removed in a future version. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfutimens\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/utmpx.h.0p b/man-pages-posix-2013-a/man0p/utmpx.h.0p new file mode 100644 index 0000000..8b14cd7 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/utmpx.h.0p @@ -0,0 +1,128 @@ +'\" et +.TH utmpx.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +utmpx.h +\(em user accounting database definitions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR utmpx +structure that shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char ut_user[] \fRUser login name.\fR +char ut_id[] \fRUnspecified initialization process identifier.\fR +char ut_line[] \fRDevice name.\fR +pid_t ut_pid \fRProcess ID.\fR +short ut_type \fRType of entry.\fR +struct timeval ut_tv \fRTime entry was made.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR pid_t +type through +.BR typedef , +as described in +.IR . +.P +The +.IR +header shall define the +.BR timeval +structure as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.P +The +.IR +header shall define the following symbolic constants as possible values +for the +.IR ut_type +member of the +.BR utmpx +structure: +.IP EMPTY 14 +No valid user accounting information. +.IP BOOT_TIME 14 +Identifies time of system boot. +.IP OLD_TIME 14 +Identifies time when system clock changed. +.IP NEW_TIME 14 +Identifies time after system clock changed. +.IP USER_PROCESS 14 +Identifies a process. +.IP INIT_PROCESS 14 +Identifies a process spawned by the init process. +.IP LOGIN_PROCESS 14 +Identifies the session leader of a logged-in user. +.IP DEAD_PROCESS 14 +Identifies a session leader who has exited. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void endutxent(void); +struct utmpx *getutxent(void); +struct utmpx *getutxid(const struct utmpx *); +struct utmpx *getutxline(const struct utmpx *); +struct utmpx *pututxline(const struct utmpx *); +void setutxent(void); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIendutxent\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/wchar.h.0p b/man-pages-posix-2013-a/man0p/wchar.h.0p new file mode 100644 index 0000000..c202a3f --- /dev/null +++ b/man-pages-posix-2013-a/man0p/wchar.h.0p @@ -0,0 +1,353 @@ +'\" et +.TH wchar.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wchar.h +\(em wide-character handling +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following types: +.IP "\fBFILE\fP" 12 +As described in +.IR . +.IP "\fBlocale_t\fP" 12 +As described in +.IR . +.IP "\fBmbstate_t\fP" 12 +An object type other than an array type that can hold the conversion +state information necessary to convert between sequences of (possibly +multi-byte) characters and wide characters. +If a codeset is being used such that an +.BR mbstate_t +needs to preserve more than two levels of reserved state, the +results are unspecified. +.IP "\fBsize_t\fP" 12 +As described in +.IR . +.IP "\fBva_list\fP" 12 +As described in +.IR . +.IP "\fBwchar_t\fP" 12 +As described in +.IR . +.IP "\fBwctype_t\fP" 12 +A scalar type of a data object that can hold values which represent +locale-specific character classification. +.IP "\fBwint_t\fP" 12 +An integer type capable of storing any valid value of +.BR wchar_t +or WEOF. +.P +The tag +.BR tm +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The implementation shall support one or more programming environments +in which the width of +.BR wint_t +is no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.P +The +.IR +header shall define the following macros: +.IP WCHAR_MAX 12 +As described in +.IR . +.IP WCHAR_MIN 12 +As described in +.IR . +.IP WEOF 12 +Constant expression of type +.BR wint_t +that is returned by several WP functions to indicate end-of-file. +.IP NULL 12 +As described in +.IR . +.P +Inclusion of the +.IR +header may make visible all symbols from the headers +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +wint_t btowc(int); +wint_t fgetwc(FILE *); +wchar_t *fgetws(wchar_t *restrict, int, FILE *restrict); +wint_t fputwc(wchar_t, FILE *); +int fputws(const wchar_t *restrict, FILE *restrict); +int fwide(FILE *, int); +int fwprintf(FILE *restrict, const wchar_t *restrict, ...); +int fwscanf(FILE *restrict, const wchar_t *restrict, ...); +wint_t getwc(FILE *); +wint_t getwchar(void); +int iswalnum(wint_t); +int iswalpha(wint_t); +int iswcntrl(wint_t); +int iswctype(wint_t, wctype_t); +int iswdigit(wint_t); +int iswgraph(wint_t); +int iswlower(wint_t); +int iswprint(wint_t); +int iswpunct(wint_t); +int iswspace(wint_t); +int iswupper(wint_t); +int iswxdigit(wint_t); +size_t mbrlen(const char *restrict, size_t, mbstate_t *restrict); +size_t mbrtowc(wchar_t *restrict, const char *restrict, size_t, + mbstate_t *restrict); +int mbsinit(const mbstate_t *); +size_t mbsnrtowcs(wchar_t *restrict, const char **restrict, + size_t, size_t, mbstate_t *restrict); +size_t mbsrtowcs(wchar_t *restrict, const char **restrict, size_t, + mbstate_t *restrict); +FILE *open_wmemstream(wchar_t **, size_t *); +wint_t putwc(wchar_t, FILE *); +wint_t putwchar(wchar_t); +int swprintf(wchar_t *restrict, size_t, + const wchar_t *restrict, ...); +int swscanf(const wchar_t *restrict, + const wchar_t *restrict, ...); +wint_t towlower(wint_t); +wint_t towupper(wint_t); +wint_t ungetwc(wint_t, FILE *); +int vfwprintf(FILE *restrict, const wchar_t *restrict, va_list); +int vfwscanf(FILE *restrict, const wchar_t *restrict, va_list); +int vswprintf(wchar_t *restrict, size_t, + const wchar_t *restrict, va_list); +int vswscanf(const wchar_t *restrict, const wchar_t *restrict, + va_list); +int vwprintf(const wchar_t *restrict, va_list); +int vwscanf(const wchar_t *restrict, va_list); +wchar_t *wcpcpy(wchar_t *restrict, const wchar_t *restrict); +wchar_t *wcpncpy(wchar_t *restrict, const wchar_t *restrict, size_t); +size_t wcrtomb(char *restrict, wchar_t, mbstate_t *restrict); +int wcscasecmp(const wchar_t *, const wchar_t *); +int wcscasecmp_l(const wchar_t *, const wchar_t *, locale_t); +wchar_t *wcscat(wchar_t *restrict, const wchar_t *restrict); +wchar_t *wcschr(const wchar_t *, wchar_t); +int wcscmp(const wchar_t *, const wchar_t *); +int wcscoll(const wchar_t *, const wchar_t *); +int wcscoll_l(const wchar_t *, const wchar_t *, locale_t); +wchar_t *wcscpy(wchar_t *restrict, const wchar_t *restrict); +size_t wcscspn(const wchar_t *, const wchar_t *); +wchar_t *wcsdup(const wchar_t *); +size_t wcsftime(wchar_t *restrict, size_t, + const wchar_t *restrict, const struct tm *restrict); +size_t wcslen(const wchar_t *); +int wcsncasecmp(const wchar_t *, const wchar_t *, size_t); +int wcsncasecmp_l(const wchar_t *, const wchar_t *, size_t, + locale_t); +wchar_t *wcsncat(wchar_t *restrict, const wchar_t *restrict, size_t); +int wcsncmp(const wchar_t *, const wchar_t *, size_t); +wchar_t *wcsncpy(wchar_t *restrict, const wchar_t *restrict, size_t); +size_t wcsnlen(const wchar_t *, size_t); +size_t wcsnrtombs(char *restrict, const wchar_t **restrict, size_t, + size_t, mbstate_t *restrict); +wchar_t *wcspbrk(const wchar_t *, const wchar_t *); +wchar_t *wcsrchr(const wchar_t *, wchar_t); +size_t wcsrtombs(char *restrict, const wchar_t **restrict, + size_t, mbstate_t *restrict); +size_t wcsspn(const wchar_t *, const wchar_t *); +wchar_t *wcsstr(const wchar_t *restrict, const wchar_t *restrict); +double wcstod(const wchar_t *restrict, wchar_t **restrict); +float wcstof(const wchar_t *restrict, wchar_t **restrict); +wchar_t *wcstok(wchar_t *restrict, const wchar_t *restrict, + wchar_t **restrict); +long wcstol(const wchar_t *restrict, wchar_t **restrict, int); +long double wcstold(const wchar_t *restrict, wchar_t **restrict); +long long wcstoll(const wchar_t *restrict, wchar_t **restrict, int); +unsigned long wcstoul(const wchar_t *restrict, wchar_t **restrict, int); +unsigned long long + wcstoull(const wchar_t *restrict, wchar_t **restrict, int); +int wcswidth(const wchar_t *, size_t); +size_t wcsxfrm(wchar_t *restrict, const wchar_t *restrict, size_t); +size_t wcsxfrm_l(wchar_t *restrict, const wchar_t *restrict, + size_t, locale_t); +int wctob(wint_t); +wctype_t wctype(const char *); +int wcwidth(wchar_t); +wchar_t *wmemchr(const wchar_t *, wchar_t, size_t); +int wmemcmp(const wchar_t *, const wchar_t *, size_t); +wchar_t *wmemcpy(wchar_t *restrict, const wchar_t *restrict, size_t); +wchar_t *wmemmove(wchar_t *, const wchar_t *, size_t); +wchar_t *wmemset(wchar_t *, wchar_t, size_t); +int wprintf(const wchar_t *restrict, ...); +int wscanf(const wchar_t *restrict, ...); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +\fIiswblank\fR() +function was a late addition to the ISO\ C standard and was introduced at the same +time as the ISO\ C standard introduced +.IR , +which contains all of the +.IR isw* (\|) +functions. The Open Group Base Specifications had previously aligned +with the MSE working draft and had introduced the rest of the +.IR isw* (\|) +functions into +.IR . +For backwards-compatibility, the original set of +.IR isw* (\|) +functions, without +\fIiswblank\fR(), +are permitted (as part of the XSI option) in +.IR . +For maximum portability, applications should include +.IR +in order to obtain declarations for the +.IR isw* (\|) +functions. This compatibility has been made obsolescent. +.SH RATIONALE +In the ISO\ C standard, the symbols referenced as XSI extensions are in +.IR . +Their presence here is thus an extension. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIbtowc\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIfgetwc\fR\^(\|)", +.IR "\fIfgetws\fR\^(\|)", +.IR "\fIfputwc\fR\^(\|)", +.IR "\fIfputws\fR\^(\|)", +.IR "\fIfwide\fR\^(\|)", +.IR "\fIfwprintf\fR\^(\|)", +.IR "\fIfwscanf\fR\^(\|)", +.IR "\fIgetwc\fR\^(\|)", +.IR "\fIgetwchar\fR\^(\|)", +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fImbrlen\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fImbsinit\fR\^(\|)", +.IR "\fImbsrtowcs\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIputwc\fR\^(\|)", +.IR "\fIputwchar\fR\^(\|)", +.IR "\fItowlower\fR\^(\|)", +.IR "\fItowupper\fR\^(\|)", +.IR "\fIungetwc\fR\^(\|)", +.IR "\fIvfwprintf\fR\^(\|)", +.IR "\fIvfwscanf\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)", +.IR "\fIwcscasecmp\fR\^(\|)", +.IR "\fIwcscat\fR\^(\|)", +.IR "\fIwcschr\fR\^(\|)", +.IR "\fIwcscmp\fR\^(\|)", +.IR "\fIwcscoll\fR\^(\|)", +.IR "\fIwcscpy\fR\^(\|)", +.IR "\fIwcscspn\fR\^(\|)", +.IR "\fIwcsdup\fR\^(\|)", +.IR "\fIwcsftime\fR\^(\|)", +.IR "\fIwcslen\fR\^(\|)", +.IR "\fIwcsncat\fR\^(\|)", +.IR "\fIwcsncmp\fR\^(\|)", +.IR "\fIwcsncpy\fR\^(\|)", +.IR "\fIwcspbrk\fR\^(\|)", +.IR "\fIwcsrchr\fR\^(\|)", +.IR "\fIwcsrtombs\fR\^(\|)", +.IR "\fIwcsspn\fR\^(\|)", +.IR "\fIwcsstr\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)", +.IR "\fIwcstok\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)", +.IR "\fIwcstoul\fR\^(\|)", +.IR "\fIwcswidth\fR\^(\|)", +.IR "\fIwcsxfrm\fR\^(\|)", +.IR "\fIwctob\fR\^(\|)", +.IR "\fIwctype\fR\^(\|)", +.IR "\fIwcwidth\fR\^(\|)", +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.ad b +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/wctype.h.0p b/man-pages-posix-2013-a/man0p/wctype.h.0p new file mode 100644 index 0000000..3d2e1c6 --- /dev/null +++ b/man-pages-posix-2013-a/man0p/wctype.h.0p @@ -0,0 +1,178 @@ +'\" et +.TH wctype.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wctype.h +\(em wide-character classification and mapping utilities +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following types: +.IP "\fBwint_t\fP" 12 +As described in +.IR . +.IP "\fBwctrans_t\fP" 12 +A scalar type that can hold values which represent locale-specific +character mappings. +.IP "\fBwctype_t\fP" 12 +As described in +.IR . +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the following macro: +.IP WEOF 12 +As described in +.IR . +.P +For all functions described in this header that accept an argument of +type +.BR wint_t , +the value is representable as a +.BR wchar_t +or equals the value of WEOF. If this argument has any other value, the +behavior is undefined. +.P +The behavior of these functions shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +Inclusion of the +.IR +header may make visible all symbols from the headers +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +int iswalnum(wint_t); +int iswalnum_l(wint_t, locale_t); +int iswalpha(wint_t); +int iswalpha_l(wint_t, locale_t); +int iswblank(wint_t); +int iswblank_l(wint_t, locale_t); +int iswcntrl(wint_t); +int iswcntrl_l(wint_t, locale_t); +int iswctype(wint_t, wctype_t); +int iswctype_l(wint_t, wctype_t, locale_t); +int iswdigit(wint_t); +int iswdigit_l(wint_t, locale_t); +int iswgraph(wint_t); +int iswgraph_l(wint_t, locale_t); +int iswlower(wint_t); +int iswlower_l(wint_t, locale_t); +int iswprint(wint_t); +int iswprint_l(wint_t, locale_t); +int iswpunct(wint_t); +int iswpunct_l(wint_t, locale_t); +int iswspace(wint_t); +int iswspace_l(wint_t, locale_t); +int iswupper(wint_t); +int iswupper_l(wint_t, locale_t); +int iswxdigit(wint_t); +int iswxdigit_l(wint_t, locale_t); +wint_t towctrans(wint_t, wctrans_t); +wint_t towctrans_l(wint_t, wctrans_t, locale_t); +wint_t towlower(wint_t); +wint_t towlower_l(wint_t, locale_t); +wint_t towupper(wint_t); +wint_t towupper_l(wint_t, locale_t); +wctrans_t wctrans(const char *); +wctrans_t wctrans_l(const char *, locale_t); +wctype_t wctype(const char *); +wctype_t wctype_l(const char *, locale_t); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswblank\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fItowctrans\fR\^(\|)", +.IR "\fItowlower\fR\^(\|)", +.IR "\fItowupper\fR\^(\|)", +.IR "\fIwctrans\fR\^(\|)", +.IR "\fIwctype\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man0p/wordexp.h.0p b/man-pages-posix-2013-a/man0p/wordexp.h.0p new file mode 100644 index 0000000..c036cbd --- /dev/null +++ b/man-pages-posix-2013-a/man0p/wordexp.h.0p @@ -0,0 +1,152 @@ +'\" et +.TH wordexp.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wordexp.h +\(em word-expansion types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structures and symbolic constants used by the +\fIwordexp\fR() +and +\fIwordfree\fR() +functions. +.P +The +.IR +header shall define the +.BR wordexp_t +structure type, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +size_t we_wordc \fRCount of words matched by \fIwords.\fR +char **we_wordv \fRPointer to list of expanded words.\fR +size_t we_offs \fRSlots to reserve at the beginning of \fIwe_wordv.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for use as flags +for the +\fIwordexp\fR() +function: +.IP WRDE_APPEND 14 +Append words to those previously generated. +.IP WRDE_DOOFFS 14 +Number of null pointers to prepend to +.IR we_wordv . +.IP WRDE_NOCMD 14 +Fail if command substitution is requested. +.IP WRDE_REUSE 14 +The +.IR pwordexp +argument was passed to a previous successful call to +\fIwordexp\fR(), +and has not been passed to +\fIwordfree\fR(). +The result is the same as if the application had called +\fIwordfree\fR() +and then called +\fIwordexp\fR() +without WRDE_REUSE. +.IP WRDE_SHOWERR 14 +Do not redirect +.IR stderr +to +.BR /dev/null . +.IP WRDE_UNDEF 14 +Report error on an attempt to expand an undefined shell variable. +.P +The +.IR +header shall define the following symbolic constants as error +return values: +.IP WRDE_BADCHAR 14 +One of the unquoted characters\(em\c +, +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' , +.BR '(' , +.BR ')' , +.BR '{' , +.BR '}' \(em\c +appears in +.IR words +in an inappropriate context. +.IP WRDE_BADVAL 14 +Reference to undefined shell variable when WRDE_UNDEF is set in +.IR flags . +.IP WRDE_CMDSUB 14 +Command substitution requested when WRDE_NOCMD was set in +.IR flags . +.IP WRDE_NOSPACE 14 +Attempt to allocate memory failed. +.IP WRDE_SYNTAX 14 +Shell syntax error, such as unbalanced parentheses or unterminated string. +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int wordexp(const char *restrict, wordexp_t *restrict, int); +void wordfree(wordexp_t *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.6" ", " "Word Expansions" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/admin.1p b/man-pages-posix-2013-a/man1p/admin.1p new file mode 100644 index 0000000..485769e --- /dev/null +++ b/man-pages-posix-2013-a/man1p/admin.1p @@ -0,0 +1,510 @@ +'\" et +.TH ADMIN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +admin +\(em create and administer SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +admin \(mii\fB[\fIname\fB] [\fR\(min\fB] [\fR\(mia \fIlogin\fB] [\fR\(mid \fIflag\fB] [\fR\(mie \fIlogin\fB] [\fR\(mif \fIflag\fB] + [\fR\(mim \fImrlist\fB] [\fR\(mir \fIrel\fB] [\fR\(mit\fB[\fIname\fB] [\fR\(miy\fB[\fIcomment\fB]] \fInewfile\fR +.P +admin \(min\fB [\fR\(mia \fIlogin\fB] [\fR\(mid \fIflag\fB] [\fR\(mie \fIlogin\fB] [\fR\(mif \fIflag\fB] [\fR\(mim \fImrlist\fB] + [\fR\(mit\fB[\fIname\fB]] [\fR\(miy\fB[\fIcomment\fB]] \fInewfile\fR... +.P +admin \fB[\fR\(mia \fIlogin\fB] [\fR\(mid \fIflag\fB] [\fR\(mim \fImrlist\fB] [\fR\(mir \fIrel\fB] [\fR\(mit\fB[\fIname\fB]]\fR \fIfile\fR... +.P +admin \(mih \fIfile\fR... +.P +admin \(miz \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR admin +utility shall create new SCCS files or change parameters of existing +ones. If a named file does not exist, it shall be created, and its +parameters shall be initialized according to the specified options. +Parameters not initialized by an option shall be assigned a default +value. If a named file does exist, parameters corresponding to +specified options shall be changed, and other parameters shall be left +as is. +.P +All SCCS filenames supplied by the application shall be of the form +s.\fIfilename\fP. New SCCS files shall be given read-only permission +mode. Write permission in the parent directory is required to create a +file. All writing done by +.IR admin +shall be to a temporary +.IR x-file , +named x.\fIfilename\fP (see +.IR "\fIget\fR\^") +created with read-only mode if +.IR admin +is creating a new SCCS file, or created with the same mode as that of +the SCCS file if the file already exists. After successful execution of +.IR admin , +the SCCS file shall be removed (if it exists), and the +.IR x-file +shall be renamed with the name of the SCCS file. This ensures that +changes are made to the SCCS file only if no errors occur. +.P +The +.IR admin +utility shall also use a transient lock file (named z.\fIfilename\fP), +which is used to prevent simultaneous updates to the SCCS file; see +.IR "\fIget\fR\^". +.SH OPTIONS +The +.IR admin +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the +.BR \(mii , +.BR \(mit , +and +.BR \(miy +options have optional option-arguments. These optional option-arguments +shall not be presented as separate arguments. The following options are +supported: +.IP "\fB\(min\fP" 10 +Create a new SCCS file. When +.BR \(min +is used without +.BR \(mii , +the SCCS file shall be created with control information but without any +file data. +.IP "\fB\(mii[\fIname\fB]\fR" 10 +Specify the +.IR name +of a file from which the text for a new SCCS file shall be taken. The +text constitutes the first delta of the file (see the +.BR \(mir +option for the delta numbering scheme). If the +.BR \(mii +option is used, but the +.IR name +option-argument is omitted, the text shall be obtained by reading the +standard input. If this option is omitted, the SCCS file shall be +created with control information but without any file data. The +.BR \(mii +option implies the +.BR \(min +option. +.IP "\fB\(mir\ \fISID\fR" 10 +Specify the SID of the initial delta to be inserted. This SID shall be +a trunk SID; that is, the branch and sequence numbers shall be zero or +missing. The level number is optional, and defaults to 1. +.IP "\fB\(mit[\fIname\fB]\fR" 10 +Specify the +.IR name +of a file from which descriptive text for the SCCS file shall be taken. +In the case of existing SCCS files (neither +.BR \(mii +nor +.BR \(min +is specified): +.RS 10 +.IP " *" 4 +A +.BR \(mit +option without a +.IR name +option-argument shall cause the removal of descriptive text (if any) +currently in the SCCS file. +.IP " *" 4 +A +.BR \(mit +option with a +.IR name +option-argument shall cause the text (if any) in the named file to +replace the descriptive text (if any) currently in the SCCS file. +.RE +.IP "\fB\(mif\ \fIflag\fR" 10 +Specify a +.IR flag , +and, possibly, a value for the +.IR flag , +to be placed in the SCCS file. Several +.BR \(mif +options may be supplied on a single +.IR admin +command line. Implementations shall recognize the following flags +and associated values: +.RS 10 +.IP "\fBb\fP" 8 +Allow use of the +.BR \(mib +option on a +.IR get +command to create branch deltas. +.IP "\fBc\fIceil\fR" 8 +Specify the highest release (that is, ceiling), a number less than or +equal to 9\|999, which may be retrieved by a +.IR get +command for editing. The default value for an unspecified +.BR c +flag shall be 9\|999. +.IP "\fBf\fIfloor\fR" 8 +Specify the lowest release (that is, floor), a number greater than 0 +but less than 9\|999, which may be retrieved by a +.IR get +command for editing. The default value for an unspecified +.BR f +flag shall be 1. +.IP "\fBd\fISID\fR" 8 +Specify the default delta number (SID) to be used by a +.IR get +command. +.IP "\fBi\fIstr\fR" 8 +Treat the ``No ID keywords'' message issued by +.IR get +or +.IR delta +as a fatal error. In the absence of this flag, the message is only a +warning. The message is issued if no SCCS identification keywords (see +.IR "\fIget\fR\^") +are found in the text retrieved or stored in the SCCS file. If a value +is supplied, the application shall ensure that the keywords exactly +match the given string; however, the string shall contain a keyword, +and no embedded + +characters. +.IP "\fBj\fP" 8 +Allow concurrent +.IR get +commands for editing on the same SID of an SCCS file. This allows +multiple concurrent updates to the same version of the SCCS file. +.IP "\fBl\fIlist\fR" 8 +Specify a +.IR list +of releases to which deltas can no longer be made (that is, +.IR get +.BR \(mie +against one of these locked releases fails). Conforming applications +shall use the following syntax to specify a +.IR list . +Implementations may accept additional forms as an extension: +.RS 8 +.sp +.RS 4 +.nf +\fB + ::= a | + ::= | , + ::= +.fi \fR +.P +.RE +.P +The character +.IR a +in the +.IR list +shall be equivalent to specifying all releases for the named SCCS file. +The non-terminal <\fISID\fP> in range shall be the delta number of an +existing delta associated with the SCCS file. +.RE +.IP "\fBn\fP" 8 +Cause +.IR delta +to create a null delta in each of those releases (if any) being skipped +when a delta is made in a new release (for example, in making delta 5.1 +after delta 2.7, releases 3 and 4 are skipped). These null deltas shall +serve as anchor points so that branch deltas may later be created from +them. The absence of this flag shall cause skipped releases to be +nonexistent in the SCCS file, preventing branch deltas from being +created from them in the future. During the initial creation of an SCCS +file, the +.BR n +flag may be ignored; that is, if the +.BR \(mir +option is used to set the release number of the initial SID to a value +greater than 1, null deltas need not be created for the ``skipped'' +releases. +.IP "\fBq\fItext\fR" 8 +Substitute user-definable +.IR text +for all occurrences of the %\fBQ\fP% keyword in the SCCS file text +retrieved by +.IR get . +.IP "\fBm\fImod\fR" 8 +Specify the module name of the SCCS file substituted for all +occurrences of the %\fBM\fP% keyword in the SCCS file text retrieved by +.IR get . +If the +.BR m +flag is not specified, the value assigned shall be the name of the SCCS +file with the leading +.BR '.' +removed. +.IP "\fBt\fItype\fR" 8 +Specify the +.IR type +of module in the SCCS file substituted for all occurrences of the +%\fBY\fP% keyword in the SCCS file text retrieved by +.IR get . +.IP "\fBv\fIpgm\fR" 8 +Cause +.IR delta +to prompt for modification request (MR) numbers as the reason for +creating a delta. The optional value specifies the name of an MR +number validation program. (If this flag is set when creating an SCCS +file, the application shall ensure that the +.BR m +option is also used even if its value is null.) +.RE +.IP "\fB\(mid\ \fIflag\fR" 10 +Remove (delete) the specified +.IR flag +from an SCCS file. Several +.BR \(mid +options may be supplied on a single +.IR admin +command. See the +.BR \(mif +option for allowable +.IR flag +names. (The +.BR l \c +.IR list +flag gives a +.IR list +of releases to be unlocked. See the +.BR \(mif +option for further description of the +.BR l +flag and the syntax of a +.IR list .) +.IP "\fB\(mia\ \fIlogin\fR" 10 +Specify a +.IR login +name, or numerical group ID, to be added to the list of users who may +make deltas (changes) to the SCCS file. A group ID shall be equivalent +to specifying all +.IR login +names common to that group ID. Several +.BR \(mia +options may be used on a single +.IR admin +command line. As many +.IR login s, +or numerical group IDs, as desired may be on the list simultaneously. +If the list of users is empty, then anyone may add deltas. If +.IR login +or group ID is preceded by a +.BR '!' , +the users so specified shall be denied permission to make deltas. +.IP "\fB\(mie\ \fIlogin\fR" 10 +Specify a +.IR login +name, or numerical group ID, to be erased from the list of users +allowed to make deltas (changes) to the SCCS file. Specifying a group +ID is equivalent to specifying all +.IR login +names common to that group ID. Several +.BR \(mie +options may be used on a single +.IR admin +command line. +.IP "\fB\(miy[\fIcomment\fB]\fR" 10 +Insert the +.IR comment +text into the SCCS file as a comment for the initial delta in a manner +identical to that of +.IR delta . +In the POSIX locale, omission of the +.BR \(miy +option shall result in a default comment line being inserted in +the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +"date and time created %s %s by %s", <\fIdate\fR>, <\fItime\fR>, <\fIlogin\fR> +.fi \fR +.P +.RE +.P +where <\fIdate\fP> is expressed in the format of the +.IR date +utility's +.BR %y /\c +.BR %m /\c +.BR %d +conversion specification, <\fItime\fP> in the format of the +.IR date +utility's +.BR %T +conversion specification format, and <\fIlogin\fP> is the login name of +the user creating the file. +.RE +.IP "\fB\(mim\ \fImrlist\fR" 10 +Insert the list of modification request (MR) numbers into the SCCS +file as the reason for creating the initial delta in a manner identical to +.IR delta . +The application shall ensure that the +.BR v +flag is set and the MR numbers are validated if the +.BR v +flag has a value (the name of an MR number validation program). +A diagnostic message shall be written if the +.BR v +flag is not set or MR validation fails. +.IP "\fB\(mih\fP" 10 +Check the structure of the SCCS file and compare the newly computed +checksum with the checksum that is stored in the SCCS file. If the +newly computed checksum does not match the checksum in the SCCS file, a +diagnostic message shall be written. +.IP "\fB\(miz\fR" 10 +Recompute the SCCS file checksum and store it in the first line of the +SCCS file (see the +.BR \(mih +option above). Note that use of this option on a truly corrupted +file may prevent future detection of the corruption. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR admin +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.IP "\fInewfile\fR" 10 +A pathname of an SCCS file to be created. +.P +If exactly one +.IR file +or +.IR newfile +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.SH STDIN +The standard input shall be a text file used only if +.BR \(mii +is specified without an option-argument or if a +.IR file +or +.IR newfile +operand is specified as +.BR '\(mi' . +If the first character of any standard input line is + +in the POSIX locale, the results are unspecified. +.SH "INPUT FILES" +The existing SCCS files shall be text files of an unspecified format. +.P +The application shall ensure that the file named by the +.BR \(mii +option's +.IR name +option-argument shall be a text file; if the first character of any +line in this file is + +in the POSIX locale, the results are unspecified. If this file contains +more than 99\|999 lines, the number of lines recorded in the header for +this file shall be 99\|999 for this delta. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR admin : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and the +contents of the default +.BR \(miy +comment. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Any SCCS files created shall be text files of an unspecified format. +During processing of a +.IR file , +a locking +.IR z-file , +as described in +.IR "\fIget\fR\^", +may be created and deleted. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +It is recommended that directories containing SCCS files be writable by +the owner only, and that SCCS files themselves be read-only. The mode +of the directories should allow only the owner to modify SCCS files +contained in the directories. The mode of the SCCS files prevents any +modification at all except by SCCS commands. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/alias.1p b/man-pages-posix-2013-a/man1p/alias.1p new file mode 100644 index 0000000..bf15887 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/alias.1p @@ -0,0 +1,222 @@ +'\" et +.TH ALIAS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +alias +\(em define or display aliases +.SH SYNOPSIS +.LP +.nf +alias \fB[\fIalias-name\fB[\fR=\fIstring\fB]\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR alias +utility shall create or redefine alias definitions or write the values +of existing alias definitions to standard output. An alias definition +provides a string value that shall replace a command name when it is +encountered; see +.IR "Section 2.3.1" ", " "Alias Substitution". +.P +An alias definition shall affect the current shell execution +environment and the execution environments of the subshells of the +current shell. When used as specified by this volume of POSIX.1\(hy2008, the alias definition +shall not affect the parent process of the current shell nor any +utility environment invoked by the shell; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIalias-name\fR" 10 +Write the alias definition to standard output. +.IP "\fIalias-name\fP=\fIstring\fR" 10 +.br +Assign the value of +.IR string +to the alias +.IR alias-name . +.P +If no operands are given, all alias definitions shall be written to +standard output. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR alias : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The format for displaying aliases (when no operands or only +.IR name +operands are specified) shall be: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", \fIname\fR, \fIvalue\fR +.fi \fR +.P +.RE +.P +The +.IR value +string shall be written with appropriate quoting so that it is suitable +for reinput to the shell. See the description of shell quoting in +.IR "Section 2.2" ", " "Quoting". +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +One of the +.IR name +operands specified did not have an alias definition, or an error +occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +Create a short alias for a commonly used +.IR ls +command: +.RS 4 +.sp +.RS 4 +.nf +\fB +alias lf="ls \(miCF" +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Create a simple ``redo'' command to repeat previous entries in the +command history file: +.RS 4 +.sp +.RS 4 +.nf +\fB +alias r='fc \(mis' +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Use 1K units for +.IR du : +.RS 4 +.sp +.RS 4 +.nf +\fB +alias du=du\e \(mik +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Set up +.IR nohup +so that it can deal with an argument that is itself an alias name: +.RS 4 +.sp +.RS 4 +.nf +\fB +alias nohup="nohup " +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR alias +description is based on historical KornShell implementations. Known +differences exist between that and the C shell. The KornShell version +was adopted to be consistent with all the other KornShell features in +\&this volume of POSIX.1\(hy2008, such as command line editing. +.P +Since +.IR alias +affects the current shell execution environment, it is generally +provided as a shell regular built-in. +.P +Historical versions of the KornShell have allowed aliases to be +exported to scripts that are invoked by the same shell. This is +triggered by the +.IR alias +.BR \(mix +flag; it is allowed by this volume of POSIX.1\(hy2008 only when an explicit extension such as +.BR \(mix +is used. The standard developers considered that aliases were of use +primarily to interactive users and that they should normally not affect +shell scripts called by those users; functions are available to such +scripts. +.P +Historical versions of the KornShell had not written aliases in a +quoted manner suitable for reentry to the shell, but this volume of POSIX.1\(hy2008 has made +this a requirement for all similar output. Therefore, consistency was +chosen over this detail of historical practice. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.5" ", " "Function Definition Command" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ar.1p b/man-pages-posix-2013-a/man1p/ar.1p new file mode 100644 index 0000000..760dd6f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ar.1p @@ -0,0 +1,727 @@ +'\" et +.TH AR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ar +\(em create and maintain library archives +.SH SYNOPSIS +.LP +.nf +ar \(mid \fB[\fR\(miv\fB] \fIarchive file\fR... +.P +ar \(mim \fB[\fR\(miv\fB] \fIarchive file\fR... +ar \(mim \(mia \fB[\fR\(miv\fB] \fIposname archive file\fR... +ar \(mim \(mib \fB[\fR\(miv\fB] \fIposname archive file\fR... +ar \(mim \(mii \fB[\fR\(miv\fB] \fIposname archive file\fR... +.P +ar \(mip \fB[\fR\(miv\fB] [\fR\(mis\fB] \fIarchive\fB [\fIfile\fR...\fB]\fR +.P +ar \(miq \fB[\fR\(micv\fB] \fIarchive file\fR... +.P +ar \(mir \fB[\fR\(micuv\fB] \fIarchive file\fR... +.P +ar \(mir \(mia \fB[\fR\(micuv\fB] \fIposname archive file\fR... +ar \(mir \(mib \fB[\fR\(micuv\fB] \fIposname archive file\fR... +ar \(mir \(mii \fB[\fR\(micuv\fB] \fIposname archive file\fR... +.P +ar \(mit \fB[\fR\(miv\fB] [\fR\(mis\fB] \fIarchive \fB[\fIfile\fR...\fB]\fR +.P +ar \(mix \fB[\fR\(miv\fB] [\fR\(misCT\fB] \fIarchive \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +.P +The +.IR ar +utility is part of the Software Development Utilities option. +.P +The +.IR ar +utility can be used to create and maintain groups of files combined +into an archive. Once an archive has been created, new files can be +added, and existing files in an archive can be extracted, deleted, or +replaced. When an archive consists entirely of valid object files, the +implementation shall format the archive so that it is usable as a +library for link editing (see +.IR c99 +and +.IR fort77 ). +When some of the archived files are not valid object files, the +suitability of the archive for library use is undefined. +If an archive consists entirely of printable files, the entire +archive shall be printable. +.P +When +.IR ar +creates an archive, it creates administrative information indicating +whether a symbol table is present in the archive. When there is at +least one object file that +.IR ar +recognizes as such in the archive, an archive symbol table shall be +created in the archive and maintained by +.IR ar ; +it is used by the link editor to search the archive. Whenever the +.IR ar +utility is used to create or update the contents of such an archive, +the symbol table shall be rebuilt. The +.BR \(mis +option shall force the symbol table to be rebuilt. +.P +All +.IR file +operands can be pathnames. However, files within archives shall be +named by a filename, which is the last component of the pathname used +when the file was entered into the archive. The comparison of +.IR file +operands to the names of files in archives shall be performed by +comparing the last component of the operand to the name of the file +in the archive. +.P +It is unspecified whether multiple files in the archive may be +identically named. In the case of such files, however, each +.IR file +and +.IR posname +operand shall match only the first file in the archive having a name +that is the same as the last component of the operand. +.SH OPTIONS +The +.IR ar +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Position new files in the archive after the file named by the +.IR posname +operand. +.IP "\fB\(mib\fP" 10 +Position new files in the archive before the file named by the +.IR posname +operand. +.IP "\fB\(mic\fP" 10 +Suppress the diagnostic message that is written to standard error by +default when the archive +.IR archive +is created. +.IP "\fB\(miC\fP" 10 +Prevent extracted files from replacing like-named files in the +file system. This option is useful when +.BR \(miT +is also used, to prevent truncated filenames from replacing files with +the same prefix. +.IP "\fB\(mid\fP" 10 +Delete one or more +.IR file s +from +.IR archive . +.IP "\fB\(mii\fP" 10 +Position new files in the archive before the file in the archive +named by the +.IR posname +operand (equivalent to +.BR \(mib ). +.IP "\fB\(mim\fP" 10 +Move the named files in the archive. The +.BR \(mia , +.BR \(mib , +or +.BR \(mii +options with the +.IR posname +operand indicate the position; otherwise, move the names files in the +archive to the end of the archive. +.IP "\fB\(mip\fP" 10 +Write the contents of the +.IR file s +in the archive named by +.IR file +operands from +.IR archive +to the standard output. If no +.IR file +operands are specified, the contents of all files in the archive shall +be written in the order of the archive. +.IP "\fB\(miq\fP" 10 +Append the named files to the end of the archive. In this case +.IR ar +does not check whether the added files are already in the archive. +This is useful to bypass the searching otherwise done when creating a +large archive piece by piece. +.IP "\fB\(mir\fP" 10 +Replace or add +.IR file s +to +.IR archive . +If the archive named by +.IR archive +does not exist, a new archive shall be created and a diagnostic message +shall be written to standard error (unless the +.BR \(mic +option is specified). If no +.IR file s +are specified and the +.IR archive +exists, the results are undefined. Files that replace existing files in +the archive shall not change the order of the archive. Files that do +not replace existing files in the archive shall be appended to the +archive +unless a +.BR \(mia , +.BR \(mib , +or +.BR \(mii +option specifies another position. +.IP "\fB\(mis\fP" 10 +Force the regeneration of the archive symbol table even if +.IR ar +is not invoked with an option that modifies the archive contents. This +option is useful to restore the archive symbol table after it has been +stripped; see +.IR strip . +.IP "\fB\(mit\fP" 10 +Write a table of contents of +.IR archive +to the standard output. Only the files specified by the +.IR file +operands shall be included in the written list. If no +.IR file +operands are specified, all files in +.IR archive +shall be included in the order of the archive. +.IP "\fB\(miT\fP" 10 +Allow filename truncation of extracted files whose archive names are +longer than the file system can support. By default, extracting a file +with a name that is too long shall be an error; a diagnostic message +shall be written and the file shall not be extracted. +.IP "\fB\(miu\fP" 10 +Update older files in the archive. When used with the +.BR \(mir +option, files in the archive shall be replaced only if the +corresponding +.IR file +has a modification time that is at least as new as the modification +time of the file in the archive. +.IP "\fB\(miv\fP" 10 +Give verbose output. When used with the option characters +.BR \(mid , +.BR \(mir , +or +.BR \(mix , +write a detailed file-by-file description of the archive creation and +maintenance activity, as described in the STDOUT section. +.RS 10 +.P +When used with +.BR \(mip , +write the name of the file in the archive to the standard output before +writing the file in the archive itself to the standard output, as +described in the STDOUT section. +.P +When used with +.BR \(mit , +include a long listing of information about the files in the archive, +as described in the STDOUT section. +.RE +.IP "\fB\(mix\fP" 10 +Extract the files in the archive named by the +.IR file +operands from +.IR archive . +The contents of the archive shall not be changed. If no +.IR file +operands are given, all files in the archive shall be extracted. The +modification time of each file extracted shall be set to the time the +file is extracted from the archive. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIarchive\fR" 10 +A pathname of the archive. +.IP "\fIfile\fR" 10 +A pathname. Only the last component shall be used when comparing +against the names of files in the archive. If two or more +.IR file +operands have the same last pathname component (basename), the results +are unspecified. The implementation's archive format shall not truncate +valid filenames of files added to or replaced in the archive. +.IP "\fIposname\fR" 10 +The name of a file in the archive, used for relative positioning; see +options +.BR \(mim +and +.BR \(mir . +.SH STDIN +Not used. +.SH "INPUT FILES" +The archive named by +.IR archive +shall be a file in the format created by +.IR ar +.BR \(mir . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ar : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and content for date and time strings written by +.IR ar +.BR \(mitv . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that overrides the default directory for +temporary files, if any. +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings written +by +.IR ar +.BR \(mitv . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mid +option is used with the +.BR \(miv +option, the standard output format shall be: +.sp +.RS 4 +.nf +\fB +"d \(mi %s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where +.IR file +is the operand specified on the command line. +.P +If the +.BR \(mip +option is used with the +.BR \(miv +option, +.IR ar +shall precede the contents of each file with: +.sp +.RS 4 +.nf +\fB +"\en<%s>\en\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, and the name of the file in the archive if +they were not. +.P +If the +.BR \(mir +option is used with the +.BR \(miv +option: +.IP " *" 4 +If +.IR file +is already in the archive, the standard output format shall be: +.RS 4 +.sp +.RS 4 +.nf +\fB +"r \(mi %s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where <\fIfile\fP> is the operand specified on the command line. +.RE +.IP " *" 4 +If +.IR file +is not already in the archive, the standard output format shall be: +.RS 4 +.sp +.RS 4 +.nf +\fB +"a \(mi %s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where <\fIfile\fP> is the operand specified on the command line. +.RE +.P +If the +.BR \(mit +option is used, +.IR ar +shall write the names of the files in the archive to the standard +output in the format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.P +If the +.BR \(mit +option is used with the +.BR \(miv +option, the standard output format shall be: +.sp +.RS 4 +.nf +\fB +"%s %u/%u %u %s %d %d:%d %d %s\en", <\fImember mode\fR>, <\fIuser ID\fR>, + <\fIgroup ID\fR>, <\fInumber of bytes in member\fR>, + <\fIabbreviated month\fR>, <\fIday-of-month\fR>, <\fIhour\fR>, + <\fIminute\fR>, <\fIyear\fR>, <\fIfile\fR> +.fi \fR +.P +.RE +.P +where: +.IP "<\fIfile\fR>" 10 +Shall be the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.IP "<\fImember\ mode\fR>" 10 +.br +Shall be formatted the same as the <\fIfile\ mode\fR> string defined in +the STDOUT section of +.IR ls , +except that the first character, the <\fIentry\ type\fR>, is not used; +the string represents the file mode of the file in the archive at the +time it was added to or replaced in the archive. +.br +.P +The following represent the last-modification time of a file when it +was most recently added to or replaced in the archive: +.IP "<\fIabbreviated\ month\fR>" 10 +.br +Equivalent to the format of the +.BR %b +conversion specification format in +.IR date . +.IP "<\fIday-of-month\fR>" 10 +.br +Equivalent to the format of the +.BR %e +conversion specification format in +.IR date . +.IP "<\fIhour\fR>" 10 +Equivalent to the format of the +.BR %H +conversion specification format in +.IR date . +.IP "<\fIminute\fR>" 10 +Equivalent to the format of the +.BR %M +conversion specification format in +.IR date . +.IP "<\fIyear\fR>" 10 +Equivalent to the format of the +.BR %Y +conversion specification format in +.IR date . +.P +When +.IR LC_TIME +does not specify the POSIX locale, a different format and order of +presentation of these fields relative to each other may be used in a +format appropriate in the specified locale. +.P +If the +.BR \(mix +option is used with the +.BR \(miv +option, the standard output format shall be: +.sp +.RS 4 +.nf +\fB +"x \(mi %s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.SH STDERR +The standard error shall be used only for diagnostic messages. +The diagnostic message about creating a new archive when +.BR \(mic +is not specified shall not modify the exit status. +.SH "OUTPUT FILES" +Archives are files with unspecified formats. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The archive format is not described. It is recognized that there are +several known +.IR ar +formats, which are not compatible. The +.IR ar +utility is included, however, to allow creation of archives that +are intended for use only on one machine. The archive is +specified as a file, and it can be moved as a file. This does allow an +archive to be moved from one machine to another machine that uses the +same implementation of +.IR ar . +.P +Utilities such as +.IR pax +(and its forebears +.IR tar +and +.IR cpio ) +also provide portable ``archives''. This is a not a duplication; the +.IR ar +utility is included to provide an interface primarily for +.IR make +and the compilers, based on a historical model. +.P +In historical implementations, the +.BR \(miq +option (available on XSI-conforming systems) is known to execute +quickly because +.IR ar +does not check on whether the added members are already in the +archive. This is useful to bypass the searching otherwise done when +creating a large archive piece-by-piece. These remarks may but need not +remain true for a brand new implementation of this utility; hence, +these remarks have been moved into the RATIONALE. +.P +BSD implementations historically required applications to provide the +.BR \(mis +option whenever the archive was supposed to contain a symbol table. +As in this volume of POSIX.1\(hy2008, System V historically creates or updates an archive symbol +table whenever an object file is removed from, added to, or updated +in the archive. +.P +The OPERANDS section requires what might seem to be true without +specifying it: the archive cannot truncate the filenames below +{NAME_MAX}. +Some historical implementations do so, however, causing unexpected +results for the application. Therefore, this volume of POSIX.1\(hy2008 makes the requirement +explicit to avoid misunderstandings. +.P +According to the System V documentation, the options +.BR \(midmpqrtx +are not required to begin with a + +(\c +.BR '\(mi' ). +This volume of POSIX.1\(hy2008 requires that a conforming application use the leading +. +.P +The archive format used by the 4.4 BSD implementation is documented in +this RATIONALE as an example: +.sp +.RS +A file created by +.IR ar +begins with the ``magic'' string +.BR \(dq!\en\(dq . +The rest of the archive is made up of objects, each of which is +composed of a header for a file, a possible filename, and the file +contents. The header is portable between machine architectures, and, if +the file contents are printable, the archive is itself printable. +.P +The header is made up of six ASCII fields, followed by a two-character +trailer. The fields are the object name (16 characters), the file last +modification time (12 characters), the user and group IDs (each 6 +characters), the file mode (8 characters), and the file size (10 +characters). All numeric fields are in decimal, except for the file +mode, which is in octal. +.P +The modification time is the file +.IR st_mtime +field. The user and group IDs are the file +.IR st_uid +and +.IR st_gid +fields. The file mode is the file +.IR st_mode +field. The file size is the file +.IR st_size +field. The two-byte trailer is the string +.BR \(dq`\(dq . +.P +Only the name field has any provision for overflow. If any filename is +more than 16 characters in length or contains an embedded space, the +string +.BR \(dq#1/\(dq +followed by the ASCII length of the name is written in the name field. +The file size (stored in the archive header) is incremented by the +length of the name. The name is then written immediately following the +archive header. +.P +Any unused characters in any of these fields are written as + +characters. If any fields are their particular maximum number of +characters in length, there is no separation between the fields. +.P +Objects in the archive are always an even number of bytes long; files +that are an odd number of bytes long are padded with a +, +although the size in the header does not reflect this. +.RE +.P +The +.IR ar +utility description requires that (when all its members are valid +object files) +.IR ar +produce an object code library, which the linkage editor can use to +extract object modules. If the linkage editor needs a symbol table to +permit random access to the archive, +.IR ar +must provide it; however, +.IR ar +does not require a symbol table. +.P +The BSD +.BR \(mio +option was omitted. It is a rare conforming application that uses +.IR ar +to extract object code from a library with concern for its modification +time, since this can only be of importance to +.IR make . +Hence, since this functionality is not deemed important for +applications portability, the modification time of the extracted files +is set to the current time. +.P +There is at least one known implementation (for a small computer) that +can accommodate only object files for that system, disallowing mixed +object and other files. The ability to handle any type of file is not +only historical practice for most implementations, but is also a +reasonable expectation. +.P +Consideration was given to changing the output format of +.IR ar +.BR \(mitv +to the same format as the output of +.IR ls +.BR \(mil . +This would have made parsing the output of +.IR ar +the same as that of +.IR ls . +This was rejected in part because the current +.IR ar +format is commonly used and changes would break historical usage. +Second, +.IR ar +gives the user ID and group ID in numeric format separated by a +. +Changing this to be the user name and group name would not be correct +if the archive were moved to a machine that contained a different user +database. Since +.IR ar +cannot know whether the archive was generated on the same machine, +it cannot tell what to report. +.P +The text on the +.BR \(miur +option combination is historical practice\(emsince one filename can +easily represent two different files (for example, +.BR /a/foo +and +.BR /b/foo ), +it is reasonable to replace the file in the archive even when the +modification time in the archive is identical to that in the file +system. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIdate\fR\^", +.IR "\fIfort77\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIstrip\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP", +description of +{POSIX_NO_TRUNC} +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/asa.1p b/man-pages-posix-2013-a/man1p/asa.1p new file mode 100644 index 0000000..2f75607 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/asa.1p @@ -0,0 +1,212 @@ +'\" et +.TH ASA "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +asa +\(em interpret carriage-control characters +.SH SYNOPSIS +.LP +.nf +asa \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR asa +utility shall write its input files to standard output, mapping +carriage-control characters from the text files to line-printer control +sequences in an implementation-defined manner. +.P +The first character of every line shall be removed from the input, and +the following actions are performed. +.P +If the character removed is: +.IP 10 +The rest of the line is output without change. +.IP 0 10 +A + +is output, then the rest of the input line. +.IP 1 10 +One or more implementation-defined characters that causes an advance +to the next page shall be output, followed by the rest of the input +line. +.IP "\fR+\fP" 10 +The + +of the previous line shall be replaced with one or more +implementation-defined characters that causes printing to return to +column position 1, followed by the rest of the input line. If the +.BR '\(pl' +is the first character in the input, it shall be equivalent to +. +.P +The action of the +.IR asa +utility is unspecified upon encountering any character other than those +listed above as the first character in a line. +.SH OPTIONS +None. +.SH OPERANDS +.IP "\fIfile\fR" 10 +A pathname of a text file used for input. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR asa : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be the text from the input file modified as +described in the DESCRIPTION section. +.SH STDERR +None. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +asa \fIfile\fR +.fi \fR +.P +.RE +.P +permits the viewing of +.IR file +(created by a program using FORTRAN-style carriage-control characters) +on a terminal. +.RE +.IP " 2." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +a.out | asa | lp +.fi \fR +.P +.RE +.P +formats the FORTRAN output of +.BR a.out +and directs it to the printer. +.RE +.SH RATIONALE +The +.IR asa +utility is needed to map ``standard'' FORTRAN 77 output into a form +acceptable to contemporary printers. Usually, +.IR asa +is used to pipe data to the +.IR lp +utility; see +.IR lp . +.P +This utility is generally used only by FORTRAN programs. The +standard developers decided to retain +.IR asa +to avoid breaking the historical large base of FORTRAN applications +that put carriage-control characters in their output files. There is no +requirement that a system have a FORTRAN compiler in order to run +applications that need +.IR asa . +.P +Historical implementations have used an ASCII + +in response to a 1 and an ASCII + +in response to a +.BR '\(pl' . +It is suggested that implementations treat characters other than 0, 1, +and +.BR '\(pl' +as + +in the absence of any compelling reason to do otherwise. However, the +action is listed here as ``unspecified'', permitting an implementation +to provide extensions to access fast multiple-line slewing and channel +seeking in a non-portable manner. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfort77\fR\^", +.IR "\fIlp\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/at.1p b/man-pages-posix-2013-a/man1p/at.1p new file mode 100644 index 0000000..fab231c --- /dev/null +++ b/man-pages-posix-2013-a/man1p/at.1p @@ -0,0 +1,798 @@ +'\" et +.TH AT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +at +\(em execute commands at a later time +.SH SYNOPSIS +.LP +.nf +at \fB[\fR\(mim\fB] [\fR\(mif \fIfile\fB] [\fR\(miq \fIqueuename\fB] \fR\(mit \fItime_arg\fR +.P +at \fB[\fR\(mim\fB] [\fR\(mif \fIfile\fB] [\fR\(miq \fIqueuename\fB] \fItimespec\fR... +.P +at \(mir \fIat_job_id\fR... +.P +at \(mil \(miq \fIqueuename\fR +.P +at \(mil \fB[\fIat_job_id\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR at +utility shall read commands from standard input and group them together +as an +.IR at-job , +to be executed at a later time. +.P +The at-job shall be executed in a separate invocation of the shell, +running in a separate process group with no controlling terminal, +except that the environment variables, current working directory, +file creation mask, and other implementation-defined execution-time +attributes in effect when the +.IR at +utility is executed shall be retained and used when the at-job is +executed. +.P +When the at-job is submitted, the +.IR at_job_id +and scheduled time shall be written to standard error. The +.IR at_job_id +is an identifier that shall be a string consisting solely of +alphanumeric characters and the + +character. The +.IR at_job_id +shall be assigned by the system when the job is scheduled such that it +uniquely identifies a particular job. +.P +User notification and the processing of the job's standard output and +standard error are described under the +.BR \(mim +option. +.P +Users shall be permitted to use +.IR at +if their name appears in the file +.BR at.allow +which is located in an implementation-defined directory. +If that file does not exist, the file +.BR at.deny , +which is located in an implementation-defined directory, +shall be checked to determine whether the user shall be denied access to +.IR at . +If neither file exists, only a process with appropriate privileges +shall be allowed to submit a job. If only +.BR at.deny +exists and is empty, global usage shall be permitted. The +.BR at.allow +and +.BR at.deny +files shall consist of one user name per line. +.SH OPTIONS +The +.IR at +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\ \fIfile\fR" 10 +Specify the pathname of a file to be used as the source of the at-job, +instead of standard input. +.IP "\fB\(mil\fP" 10 +(The letter ell.) Report all jobs scheduled for the invoking user if no +.IR at_job_id +operands are specified. If +.IR at_job_id s +are specified, report only information for these jobs. The output shall +be written to standard output. +.IP "\fB\(mim\fP" 10 +Send mail to the invoking user after the at-job has run, announcing its +completion. Standard output and standard error produced by the at-job +shall be mailed to the user as well, unless redirected elsewhere. Mail +shall be sent even if the job produces no output. +.RS 10 +.P +If +.BR \(mim +is not used, the job's standard output and standard error shall be +provided to the user by means of mail, unless they are redirected +elsewhere; if there is no such output to provide, the implementation +need not notify the user of the job's completion. +.RE +.IP "\fB\(miq\ \fIqueuename\fR" 10 +.br +Specify in which queue to schedule a job for submission. When used with +the +.BR \(mil +option, limit the search to that particular queue. By default, at-jobs +shall be scheduled in queue +.IR a . +In contrast, queue +.IR b +shall be reserved for batch jobs; see +.IR batch . +The meanings of all other +.IR queuename s +are implementation-defined. If +.BR \(miq +is specified along with either of the +.BR \(mit +.IR time_arg +or +.IR timespec +arguments, the results are unspecified. +.IP "\fB\(mir\fP" 10 +Remove the jobs with the specified +.IR at_job_id +operands that were previously scheduled by the +.IR at +utility. +.IP "\fB\(mit\ \fItime_arg\fR" 10 +Submit the job to be run at the time specified by the +.IR time +option-argument, which the application shall ensure has the format as +specified by the +.IR touch +.BR \(mit +.IR time +utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIat_job_id\fR" 10 +The name reported by a previous invocation of the +.IR at +utility at the time the job was scheduled. +.IP "\fItimespec\fR" 10 +Submit the job to be run at the date and time specified. All of the +.IR timespec +operands are interpreted as if they were separated by + +characters and concatenated, and shall be parsed as described in the +grammar at the end of this section. The date and time shall be interpreted +as being in the timezone of the user (as determined by the +.IR TZ +variable), unless a timezone name appears as part of +.IR time , +below. +.RS 10 +.P +In the POSIX locale, the following describes the three parts of the +time specification string. All of the values from the +.IR LC_TIME +categories in the POSIX locale shall be recognized in a +case-insensitive manner. +.IP "\fItime\fR" 10 +The time can be specified as one, two, or four digits. One-digit and +two-digit numbers shall be taken to be hours; four-digit numbers to be +hours and minutes. The time can alternatively be specified as two +numbers separated by a +, +meaning \fIhour\fP:\fIminute\fR. An AM/PM indication (one of the values +from the +.BR am_pm +keywords in the +.IR LC_TIME +locale category) can follow the time; otherwise, a 24-hour clock time +shall be understood. A timezone name can also follow to further qualify +the time. The acceptable timezone names are implementation-defined, +except that they shall be case-insensitive and the string +.BR utc +is supported to indicate the time is in Coordinated Universal Time. +In the POSIX locale, the +.IR time +field can also be one of the following tokens: +.RS 10 +.IP "\fBmidnight\fR" 10 +Indicates the time 12:00 am (00:00). +.IP "\fBnoon\fR" 10 +Indicates the time 12:00 pm. +.IP "\fBnow\fR" 10 +Indicates the current day and time. Invoking +.IR at +<\fBnow\fR> shall submit an at-job for potentially immediate execution +(that is, subject only to unspecified scheduling delays). +.RE +.IP "\fIdate\fR" 10 +An optional +.IR date +can be specified as either a month name (one of the values from the +.BR mon +or +.BR abmon +keywords in the +.IR LC_TIME +locale category) followed by a day number (and possibly year number +preceded by a comma), or a day of the week (one of the values from the +.BR day +or +.BR abday +keywords in the +.IR LC_TIME +locale category). In the POSIX locale, two special days shall be +recognized: +.RS 10 +.IP "\fBtoday\fR" 10 +Indicates the current day. +.IP "\fBtomorrow\fR" 10 +Indicates the day following the current day. +.P +If no +.IR date +is given, +.BR today +shall be assumed if the given time is greater than the current time, +and +.BR tomorrow +shall be assumed if it is less. If the given month is less than the +current month (and no year is given), next year shall be assumed. +.RE +.IP "\fIincrement\fR" 10 +The optional +.IR increment +shall be a number preceded by a + +(\c +.BR '\(pl' ) +and suffixed by one of the following: +.BR minutes , +.BR hours , +.BR days , +.BR weeks , +.BR months , +or +.BR years . +(The singular forms shall also be accepted.) The keyword +.BR next +shall be equivalent to an increment number of +1. For example, the +following are equivalent commands: +.RS 10 +.sp +.RS 4 +.nf +\fB +at 2pm + 1 week +at 2pm next week +.fi \fR +.P +.RE +.RE +.RE +.P +The following grammar describes the precise format of +.IR timespec +in the POSIX locale. The general conventions for this style of grammar +are described in +.IR "Section 1.3" ", " "Grammar Conventions". +This formal syntax shall take precedence over the preceding text syntax +description. The longest possible token or delimiter shall be +recognized at a given point. When used in a +.IR timespec , +white space shall also delimit tokens. +.sp +.RS 4 +.nf +\fB +%token hr24clock_hr_min +%token hr24clock_hour +/* + An hr24clock_hr_min is a one, two, or four-digit number. A one-digit + or two-digit number constitutes an hr24clock_hour. An hr24clock_hour + may be any of the single digits [0,9], or may be double digits, ranging + from [00,23]. If an hr24clock_hr_min is a four-digit number, the + first two digits shall be a valid hr24clock_hour, while the last two + represent the number of minutes, from [00,59]. +*/ +.P +%token wallclock_hr_min +%token wallclock_hour +/* + A wallclock_hr_min is a one, two-digit, or four-digit number. + A one-digit or two-digit number constitutes a wallclock_hour. + A wallclock_hour may be any of the single digits [1,9], or may + be double digits, ranging from [01,12]. If a wallclock_hr_min + is a four-digit number, the first two digits shall be a valid + wallclock_hour, while the last two represent the number of + minutes, from [00,59]. +*/ +.P +%token minute +/* + A minute is a one or two-digit number whose value can be [0,9] + or [00,59]. +*/ +.P +%token day_number +/* + A day_number is a number in the range appropriate for the particular + month and year specified by month_name and year_number, respectively. + If no year_number is given, the current year is assumed if the given + date and time are later this year. If no year_number is given and + the date and time have already occurred this year and the month is + not the current month, next year is the assumed year. +*/ +.P +%token year_number +/* + A year_number is a four-digit number representing the year A.D., in + which the at_job is to be run. +*/ +.P +%token inc_number +/* + The inc_number is the number of times the succeeding increment + period is to be added to the specified date and time. +*/ +.P +%token timezone_name +/* + The name of an optional timezone suffix to the time field, in an + implementation-defined format. +*/ +.P +%token month_name +/* + One of the values from the mon or abmon keywords in the LC_TIME + locale category. +*/ +.P +%token day_of_week +/* + One of the values from the day or abday keywords in the LC_TIME + locale category. +*/ +.P +%token am_pm +/* + One of the values from the am_pm keyword in the LC_TIME locale + category. +*/ +.P +%start timespec +%% +timespec : time + | time date + | time increment + | time date increment + | nowspec + ; +.P +nowspec : "now" + | "now" increment + ; +.P +time : hr24clock_hr_min + | hr24clock_hr_min timezone_name + | hr24clock_hour ":" minute + | hr24clock_hour ":" minute timezone_name + | wallclock_hr_min am_pm + | wallclock_hr_min am_pm timezone_name + | wallclock_hour ":" minute am_pm + | wallclock_hour ":" minute am_pm timezone_name + | "noon" + | "midnight" + ; +.P +date : month_name day_number + | month_name day_number "," year_number + | day_of_week + | "today" + | "tomorrow" + ; +.P +increment : "+" inc_number inc_period + | "next" inc_period + ; +.P +inc_period : "minute" | "minutes" + | "hour" | "hours" + | "day" | "days" + | "week" | "weeks" + | "month" | "months" + | "year" | "years" + ; +.fi \fR +.P +.RE +.SH STDIN +The standard input shall be a text file consisting of commands +acceptable to the shell command language described in +.IR "Chapter 2" ", " "Shell Command Language". +The standard input shall only be used if no +.BR \(mif +.IR file +option is specified. +.SH "INPUT FILES" +See the STDIN section. +.P +The text files +.BR at.allow +and +.BR at.deny , +which are located in an implementation-defined directory, +shall contain zero or more user names, one per line, of users who are, +respectively, authorized or denied access to the +.IR at +and +.IR batch +utilities. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR at : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fILC_TIME\fP" 10 +Determine the format and contents for date and time strings written and +accepted by +.IR at . +.IP "\fISHELL\fP" 10 +Determine a name of a command interpreter to be used to invoke the +at-job. If the variable is unset or null, +.IR sh +shall be used. If it is set to a value other than a name for +.IR sh , +the implementation shall do one of the following: use that shell; use +.IR sh ; +use the login shell from the user database; or any of the preceding +accompanied by a warning diagnostic about which was chosen. +.IP "\fITZ\fP" 10 +Determine the timezone. The job shall be submitted for execution at the +time specified by +.IR timespec +or +.BR \(mit +.IR time +relative to the timezone specified by the +.IR TZ +variable. If +.IR timespec +specifies a timezone, it shall override +.IR TZ . +If +.IR timespec +does not specify a timezone and +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When standard input is a terminal, prompts of unspecified format for +each line of the user input described in the STDIN section may be +written to standard output. +.P +In the POSIX locale, the following shall be written to the standard +output for each job when jobs are listed in response to the +.BR \(mil +option: +.sp +.RS 4 +.nf +\fB +"%s\et%s\en", \fIat_job_id\fR, <\fIdate\fR> +.fi \fR +.P +.RE +.P +where +.IR date +shall be equivalent in format to the output of: +.sp +.RS 4 +.nf +\fB +date +"%a %b %e %T %Y" +.fi \fR +.P +.RE +.P +The date and time written shall be adjusted so that they appear in the +timezone of the user (as determined by the +.IR TZ +variable). +.SH STDERR +In the POSIX locale, the following shall be written to standard error +when a job has been successfully submitted: +.sp +.RS 4 +.nf +\fB +"job %s at %s\en", \fIat_job_id\fR, <\fIdate\fR> +.fi \fR +.P +.RE +.P +where +.IR date +has the same format as that described in the STDOUT section. Neither +this, nor warning messages concerning the selection of the command +interpreter, shall be considered a diagnostic that changes the exit +status. +.P +Diagnostic messages, if any, shall be written to standard error. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The +.IR at +utility successfully submitted, removed, or listed a job or jobs. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The job shall not be scheduled, removed, or listed. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The format of the +.IR at +command line shown here is guaranteed only for the POSIX locale. Other +cultures may be supported with substantially different interfaces, +although implementations are encouraged to provide comparable levels of +functionality. +.P +Since the commands run in a separate shell invocation, running in a +separate process group with no controlling terminal, open file +descriptors, traps, and priority inherited from the invoking +environment are lost. +.P +Some implementations do not allow substitution of different shells +using +.IR SHELL . +System V systems, for example, have used the login shell value for the +user in +.BR /etc/passwd . +To select reliably another command interpreter, the user must include +it as part of the script, such as: +.sp +.RS 4 +.nf +\fB +\fB$\fR at 1800 +myshell myscript +EOT +\fBjob ... at ... +\fB$\fR +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +This sequence can be used at a terminal: +.RS 4 +.sp +.RS 4 +.nf +\fB +at \(mim 0730 tomorrow +sort < file >outfile +EOT +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +This sequence, which demonstrates redirecting standard error to a pipe, +is useful in a command procedure (the sequence of output redirection +specifications is significant): +.RS 4 +.sp +.RS 4 +.nf +\fB +at now + 1 hour <&1 >outfile | mailx mygroup +! +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +To have a job reschedule itself, +.IR at +can be invoked from within the at-job. For example, this daily +processing script named +.BR my.daily +runs every day (although +.IR crontab +is a more appropriate vehicle for such work): +.RS 4 +.sp +.RS 4 +.nf +\fB +# my.daily runs every day +\fIdaily processing\fR +at now tomorrow < my.daily +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +The spacing of the three portions of the POSIX locale +.IR timespec +is quite flexible as long as there are no ambiguities. Examples of +various times and operand presentation include: +.RS 4 +.sp +.RS 4 +.nf +\fB +at 0815am Jan 24 +at 8 :15amjan24 +at now "+ 1day" +at 5 pm FRIday +at '17 + utc+ + 30minutes' +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR at +utility reads from standard input the commands to be executed at a +later time. It may be useful to redirect standard output and standard +error within the specified commands. +.P +The +.BR \(mit +.IR time +option was added as a new capability to support an internationalized +way of specifying a time for execution of the submitted job. +.P +Early proposals added a ``jobname'' concept as a way of giving +submitted jobs names that are meaningful to the user submitting them. +The historical, system-specified +.IR at_job_id +gives no indication of what the job is. Upon further reflection, it was +decided that the benefit of this was not worth the change in historical +interface. The +.IR at +functionality is useful in simple environments, but in large or complex +situations, the functionality provided by the Batch Services option is +more suitable. +.P +The +.BR \(miq +option historically has been an undocumented option, used mainly by the +.IR batch +utility. +.P +The System V +.BR \(mim +option was added to provide a method for informing users that an at-job +had completed. Otherwise, users are only informed when output to +standard error or standard output are not redirected. +.P +The behavior of +.IR at +<\fBnow\fP> was changed in an early proposal from being unspecified to +submitting a job for potentially immediate execution. Historical BSD +.IR at +implementations support this. Historical System V implementations give +an error in that case, but a change to the System V versions should +have no backwards-compatibility ramifications. +.P +On BSD-based systems, a +.BR \(miu +.IR user +option has allowed those with appropriate privileges to access the work +of other users. Since this is primarily a system administration feature +and is not universally implemented, it has been omitted. Similarly, a +specification for the output format for a user with appropriate +privileges viewing the queues of other users has been omitted. +.P +The +.BR \(mif +.IR file +option from System V is used instead of the BSD method of using the +last operand as the pathname. The BSD method is ambiguous\(emdoes: +.sp +.RS 4 +.nf +\fB +at 1200 friday +.fi \fR +.P +.RE +.P +mean the same thing if there is a file named +.BR friday +in the current directory? +.P +The +.IR at_job_id +is composed of a limited character set in historical practice, and it +is mandated here to invalidate systems that might try using characters +that require shell quoting or that could not be easily parsed by shell +scripts. +.P +The +.IR at +utility varies between System V and BSD systems in the way timezones +are used. On System V systems, the +.IR TZ +variable affects the at-job submission times and the times displayed +for the user. On BSD systems, +.IR TZ +is not taken into account. The BSD behavior is easily achieved with +the current specification. If the user wishes to have the timezone +default to that of the system, they merely need to issue the +.IR at +command immediately following an unsetting or null assignment to +.IR TZ . +For example: +.sp +.RS 4 +.nf +\fB +TZ= at noon ... +.fi \fR +.P +.RE +.P +gives the desired BSD result. +.P +While the +.IR yacc -like +grammar specified in the OPERANDS section is lexically unambiguous with +respect to the digit strings, a lexical analyzer would probably be +written to look for and return digit strings in those cases. The parser +could then check whether the digit string returned is a valid +.IR day_number , +.IR year_number , +and so on, based on the context. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbatch\fR\^", +.IR "\fIcrontab\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/awk.1p b/man-pages-posix-2013-a/man1p/awk.1p new file mode 100644 index 0000000..8a67a2f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/awk.1p @@ -0,0 +1,3966 @@ +'\" et +.TH AWK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +awk +\(em pattern scanning and processing language +.SH SYNOPSIS +.LP +.nf +awk \fB[\fR\(miF \fIsepstring\fB] [\fR\(miv \fIassignment\fB]\fR... \fIprogram\fB [\fIargument\fR...\fB]\fR +.P +awk \fB[\fR\(miF \fIsepstring\fB] \fR\(mif \fIprogfile \fB[\fR\(mif \fIprogfile\fB]\fR... \fB[\fR\(miv \fIassignment\fB]\fR... + \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR awk +utility shall execute programs written in the +.IR awk +programming language, which is specialized for textual data +manipulation. An +.IR awk +program is a sequence of patterns and corresponding actions. When +input is read that matches a pattern, the action associated with that +pattern is carried out. +.P +Input shall be interpreted as a sequence of records. By default, a +record is a line, less its terminating +, +but this can be changed by using the +.BR RS +built-in variable. Each record of input shall be matched in turn +against each pattern in the program. For each pattern matched, the +associated action shall be executed. +.P +The +.IR awk +utility shall interpret each input record as a sequence of fields +where, by default, a field is a string of non-\c + +non-\c + +characters. This default + +and + +field delimiter can be changed by using the +.BR FS +built-in variable or the +.BR \(miF +.IR sepstring +option. The +.IR awk +utility shall denote the first field in a record $1, the second $2, and +so on. The symbol $0 shall refer to the entire record; setting any +other field causes the re-evaluation of $0. Assigning to $0 shall reset +the values of all other fields and the +.BR NF +built-in variable. +.SH OPTIONS +The +.IR awk +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miF\ \fIsepstring\fR" 10 +Define the input field separator. This option shall be equivalent to: +.RS 10 +.sp +.RS 4 +.nf +\fB +-v FS=\fIsepstring +.fi \fR +.P +.RE +.P +except that if +.BR \(miF +.IR sepstring +and +.BR \(miv +.IR \fRFS=\fPsepstring\fR +are both used, it is unspecified whether the +.BR FS +assignment resulting from +.BR \(miF +.IR sepstring +is processed in command line order or is processed after the last +.BR \(miv +.IR \fRFS=\fPsepstring\fR . +See the description of the +.BR FS +built-in variable, and how it is used, in the EXTENDED DESCRIPTION +section. +.RE +.IP "\fB\(mif\ \fIprogfile\fR" 10 +Specify the pathname of the file +.IR progfile +containing an +.IR awk +program. A pathname of +.BR '\(mi' +shall denote the standard input. If multiple instances of this option +are specified, the concatenation of the files specified as +.IR progfile +in the order specified shall be the +.IR awk +program. The +.IR awk +program can alternatively be specified in the command line as a single +argument. +.IP "\fB\(miv\ \fIassignment\fR" 10 +.br +The application shall ensure that the +.IR assignment +argument is in the same form as an +.IR assignment +operand. The specified variable assignment shall occur prior to +executing the +.IR awk +program, including the actions associated with +.BR BEGIN +patterns (if any). Multiple occurrences of this option can be +specified. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIprogram\fR" 10 +If no +.BR \(mif +option is specified, the first operand to +.IR awk +shall be the text of the +.IR awk +program. The application shall supply the +.IR program +operand as a single argument to +.IR awk . +If the text does not end in a +, +.IR awk +shall interpret the text as if it did. +.IP "\fIargument\fR" 10 +Either of the following two types of +.IR argument +can be intermixed: +.RS 10 +.IP "\fIfile\fR" 10 +A pathname of a file that contains the input to be read, which is +matched against the set of patterns in the program. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIassignment\fR" 10 +An operand that begins with an + +or alphabetic character from the portable character set (see the table +in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"), +followed by a sequence of underscores, digits, and alphabetics from the +portable character set, followed by the +.BR '=' +character, shall specify a variable assignment rather than a pathname. +The characters before the +.BR '=' +represent the name of an +.IR awk +variable; if that name is an +.IR awk +reserved word (see +.IR "Grammar") +the behavior is undefined. The characters following the + +shall be interpreted as if they appeared in the +.IR awk +program preceded and followed by a double-quote (\c +.BR '\&"' ) +character, as a +.BR STRING +token (see +.IR "Grammar"), +except that if the last character is an unescaped +, +it shall be interpreted as a literal + +rather than as the first character of the sequence +.BR \(dq\e"\(dq . +The variable shall be assigned the value of that +.BR STRING +token and, if appropriate, shall be considered a +.IR "numeric string" +(see +.IR "Expressions in awk"), +the variable shall also be assigned its numeric value. Each such +variable assignment shall occur just prior to the processing of the +following +.IR file , +if any. Thus, an assignment before the first +.IR file +argument shall be executed after the +.BR BEGIN +actions (if any), while an assignment after the last +.IR file +argument shall occur before the +.BR END +actions (if any). If there are no +.IR file +arguments, assignments shall be executed before processing the standard +input. +.RE +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +or if a +.IR progfile +option-argument is +.BR '\(mi' ; +see the INPUT FILES section. If the +.IR awk +program contains no actions and no patterns, but is otherwise a valid +.IR awk +program, standard input and any +.IR file +operands shall not be read and +.IR awk +shall exit with a return status of zero. +.SH "INPUT FILES" +Input files to the +.IR awk +program from any of the following sources shall be text files: +.IP " *" 4 +Any +.IR file +operands or their equivalents, achieved by modifying the +.IR awk +variables +.BR ARGV +and +.BR ARGC +.IP " *" 4 +Standard input in the absence of any +.IR file +operands +.IP " *" 4 +Arguments to the +.BR getline +function +.P +Whether the variable +.BR RS +is set to a value other than a + +or not, for these files, implementations shall support records +terminated with the specified separator up to +{LINE_MAX} +bytes and may support longer records. +.P +If +.BR \(mif +.IR progfile +is specified, the application shall ensure that the files named by each +of the +.IR progfile +option-arguments are text files and their concatenation, in the same +order as they appear in the arguments, is an +.IR awk +program. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR awk : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions and +in comparisons of string values. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes within regular expressions, the identification of +characters as letters, and the mapping of uppercase and lowercase +characters for the +.BR toupper +and +.BR tolower +functions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the radix character used when interpreting numeric input, +performing conversions between numeric and string values, and +formatting numeric output. Regardless of locale, the + +character (the decimal-point character of the POSIX locale) is the +decimal-point character recognized in processing +.IR awk +programs (including assignments in command line arguments). +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path when looking for commands executed by +\fIsystem\fR(\fIexpr\fR), or input and output pipes; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +In addition, all environment variables shall be visible via the +.IR awk +variable +.BR ENVIRON . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The nature of the output files depends on the +.IR awk +program. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The nature of the output files depends on the +.IR awk +program. +.br +.SH "EXTENDED DESCRIPTION" +.SS "Overall Program Structure" +.P +An +.IR awk +program is composed of pairs of the form: +.sp +.RS 4 +.nf +\fB +\fIpattern\fR { \fIaction\fR } +.fi \fR +.P +.RE +.P +Either the pattern or the action (including the enclosing brace +characters) can be omitted. +.P +A missing pattern shall match any record of input, and a missing action +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +{ print } +.fi \fR +.P +.RE +.P +Execution of the +.IR awk +program shall start by first executing the actions associated with all +.BR BEGIN +patterns in the order they occur in the program. Then each +.IR file +operand (or standard input if no files were specified) shall be +processed in turn by reading data from the file until a record +separator is seen (\c + +by default). Before the first reference to a field in the record is +evaluated, the record shall be split into fields, according to the +rules in +.IR "Regular Expressions", +using the value of +.BR FS +that was current at the time the record was read. Each pattern in the +program then shall be evaluated in the order of occurrence, and the +action associated with each pattern that matches the current record +executed. The action for a matching pattern shall be executed before +evaluating subsequent patterns. Finally, the actions associated with +all +.BR END +patterns shall be executed in the order they occur in the program. +.SS "Expressions in awk" +.P +Expressions describe computations used in +.IR patterns +and +.IR actions . +In the following table, valid expression operations are given in groups +from highest precedence first to lowest precedence last, with +equal-precedence operators grouped between horizontal lines. In +expression evaluation, where the grammar is formally ambiguous, higher +precedence operators shall be evaluated before lower precedence +operators. In this table +.IR expr , +.IR expr1 , +.IR expr2 , +and +.IR expr3 +represent any expression, while lvalue represents any entity that can +be assigned to (that is, on the left side of an assignment operator). +The precise syntax of expressions is given in +.IR "Grammar". +.sp +.ce 1 +\fBTable 4-1: Expressions in Decreasing Precedence in \fIawk\fP\fR +.TS +box tab(@) center; +cB | cB | cB | cB +l1f5 | l1 | l1 | l. +Syntax@Name@Type of Result@Associativity +_ +( \fIexpr\fP )@Grouping@Type of \fIexpr\fP@N/A +_ +$\fIexpr\fP@Field reference@String@N/A +_ +lvalue ++@Post-increment@Numeric@N/A +lvalue \(mi\|\(mi@Post-decrement@Numeric@N/A +_ +++ lvalue@Pre-increment@Numeric@N/A +\(mi\|\(mi lvalue@Pre-decrement@Numeric@N/A +_ +\fIexpr\fP ^ \fIexpr\fP@Exponentiation@Numeric@Right +_ +! \fIexpr\fP@Logical not@Numeric@N/A ++ \fIexpr\fP@Unary plus@Numeric@N/A +\(mi \fIexpr\fP@Unary minus@Numeric@N/A +_ +\fIexpr\fP * \fIexpr\fP@Multiplication@Numeric@Left +\fIexpr\fP / \fIexpr\fP@Division@Numeric@Left +\fIexpr\fP % \fIexpr\fP@Modulus@Numeric@Left +_ +\fIexpr\fP + \fIexpr\fP@Addition@Numeric@Left +\fIexpr\fP \(mi \fIexpr\fP@Subtraction@Numeric@Left +_ +\fIexpr\fP \fIexpr\fP@String concatenation@String@Left +_ +\fIexpr\fP < \fIexpr\fP@Less than@Numeric@None +\fIexpr\fP <= \fIexpr\fP@Less than or equal to@Numeric@None +\fIexpr\fP != \fIexpr\fP@Not equal to@Numeric@None +\fIexpr\fP == \fIexpr\fP@Equal to@Numeric@None +\fIexpr\fP > \fIexpr\fP@Greater than@Numeric@None +\fIexpr\fP >= \fIexpr\fP@Greater than or equal to@Numeric@None +_ +\fIexpr\fP ~ \fIexpr\fP@ERE match@Numeric@None +\fIexpr\fP !~ \fIexpr\fP@ERE non-match@Numeric@None +_ +\fIexpr\fP in array@Array membership@Numeric@Left +( \fIindex\fP ) in \fIarray\fP@Multi-dimension array@Numeric@Left +@membership +_ +\fIexpr\fP && \fIexpr\fP@Logical AND@Numeric@Left +_ +\fIexpr\fP || \fIexpr\fP@Logical OR@Numeric@Left +_ +\fIexpr1\fP ? \fIexpr2\fP : \fIexpr3\fP@Conditional expression@Type of selected@Right +@@\fIexpr2\fP or \fIexpr3\fP +_ +lvalue ^= \fIexpr\fP@Exponentiation assignment@Numeric@Right +lvalue %= \fIexpr\fP@Modulus assignment@Numeric@Right +lvalue *= \fIexpr\fP@Multiplication assignment@Numeric@Right +lvalue /= \fIexpr\fP@Division assignment@Numeric@Right +lvalue += \fIexpr\fP@Addition assignment@Numeric@Right +lvalue \(mi= \fIexpr\fP@Subtraction assignment@Numeric@Right +lvalue = \fIexpr\fP@Assignment@Type of \fIexpr\fP@Right +.TE +.P +Each expression shall have either a string value, a numeric value, or +both. Except as stated for specific contexts, the value of an expression +shall be implicitly converted to the type needed for the context in which +it is used. A string value shall be converted to a numeric value either by +the equivalent of the following calls to functions defined by the ISO\ C standard: +.sp +.RS 4 +.nf +\fB +setlocale(LC_NUMERIC, ""); +\fInumeric_value\fR = atof(\fIstring_value\fR); +.fi \fR +.P +.RE +.P +or by converting the initial portion of the string to type +.BR double +representation as follows: +.sp +.RS +The input string is decomposed into two parts: an initial, possibly empty, +sequence of white-space characters (as specified by +\fIisspace\fR()) +and a subject sequence interpreted as a floating-point constant. +.P +The expected form of the subject sequence is an optional +.BR '+' +or +.BR '\(mi' +sign, then a non-empty sequence of digits optionally containing a +, +then an optional exponent part. An exponent part consists of +.BR 'e' +or +.BR 'E' , +followed by an optional sign, followed by one or more decimal digits. +.P +The sequence starting with the first digit or the + +(whichever occurs first) is interpreted as a floating constant of the +C language, and if neither an exponent part nor a + +appears, a + +is assumed to follow the last digit in the string. If the subject +sequence begins with a minus-sign, the value resulting from the conversion +is negated. +.RE +.P +A numeric value that is exactly equal to the value of an integer (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard") +shall be converted to a string by the equivalent of a call to the +.BR sprintf +function (see +.IR "String Functions") +with the string +.BR \(dq%d\(dq +as the +.IR fmt +argument and the numeric value being converted as the first and only +.IR expr +argument. Any other numeric value shall be converted to a string by the +equivalent of a call to the +.BR sprintf +function with the value of the variable +.BR CONVFMT +as the +.IR fmt +argument and the numeric value being converted as the first and only +.IR expr +argument. The result of the conversion is unspecified if the value of +.BR CONVFMT +is not a floating-point format specification. This volume of POSIX.1\(hy2008 specifies no +explicit conversions between numbers and strings. An application can +force an expression to be treated as a number by adding zero to it, or +can force it to be treated as a string by concatenating the null string +(\c +.BR \(dq\^\(dq ) +to it. +.P +A string value shall be considered a +.IR "numeric string" +if it comes from one of the following: +.IP " 1." 4 +Field variables +.IP " 2." 4 +Input from the +\fIgetline\fR() +function +.IP " 3." 4 +.BR FILENAME +.IP " 4." 4 +.BR ARGV +array elements +.IP " 5." 4 +.BR ENVIRON +array elements +.IP " 6." 4 +Array elements created by the +\fIsplit\fR() +function +.IP " 7." 4 +A command line variable assignment +.IP " 8." 4 +Variable assignment from another numeric string variable +.P +and an implementation-dependent condition corresponding to either +case (a) or (b) below is met. +.IP " a." 4 +After the equivalent of the following calls to functions defined by +the ISO\ C standard, +.IR string_value_end +would differ from +.IR string_value , +and any characters before the terminating null character in +.IR string_value_end +would be + +characters: +.RS 4 +.sp +.RS 4 +.nf +\fB +char *string_value_end; +setlocale(LC_NUMERIC, ""); +numeric_value = strtod (string_value, &string_value_end); +.fi \fR +.P +.RE +.RE +.IP " b." 4 +After all the following conversions have been applied, the resulting +string would lexically be recognized as a +.BR NUMBER +token as described by the lexical conventions in +.IR "Grammar": +.RS 4 +.IP -- 4 +All leading and trailing + +characters are discarded. +.IP -- 4 +If the first non-\c + +is +.BR '\(pl' +or +.BR '\(mi' , +it is discarded. +.IP -- 4 +Each occurrence of the decimal point character from the current locale +is changed to a +. +.RE +In case (a) the numeric value of the +.IR "numeric string" +shall be the value that would be returned by the +\fIstrtod\fR() +call. In case (b) if the first non-\c + +is +.BR '\(mi' , +the numeric value of the +.IR "numeric string" +shall be the negation of the numeric value of the recognized +.BR NUMBER +token; otherwise, the numeric value of the +.IR "numeric string" +shall be the numeric value of the recognized +.BR NUMBER +token. Whether or not a string is a +.IR "numeric string" +shall be relevant only in contexts where that term is used in this +section. +.P +When an expression is used in a Boolean context, if it has a numeric +value, a value of zero shall be treated as false and any other value +shall be treated as true. Otherwise, a string value of the null string +shall be treated as false and any other value shall be treated as true. +A Boolean context shall be one of the following: +.IP " *" 4 +The first subexpression of a conditional expression +.IP " *" 4 +An expression operated on by logical NOT, logical AND, or logical OR +.IP " *" 4 +The second expression of a +.BR for +statement +.IP " *" 4 +The expression of an +.BR if +statement +.IP " *" 4 +The expression of the +.BR while +clause in either a +.BR while +or +.BR do .\|.\|.\c +.BR while +statement +.IP " *" 4 +An expression used as a pattern (as in Overall Program Structure) +.P +All arithmetic shall follow the semantics of floating-point arithmetic as +specified by the ISO\ C standard (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"). +.P +The value of the expression: +.sp +.RS 4 +.nf +\fB +\fIexpr1\fR ^ \fIexpr2\fR +.fi \fR +.P +.RE +.P +shall be equivalent to the value returned by the ISO\ C standard function call: +.sp +.RS 4 +.nf +\fB +\fRpow(\fIexpr1\fR, \fIexpr2\fR) +.fi \fR +.P +.RE +.P +The expression: +.sp +.RS 4 +.nf +\fB +lvalue ^= \fIexpr\fR +.fi \fR +.P +.RE +.P +shall be equivalent to the ISO\ C standard expression: +.sp +.RS 4 +.nf +\fB +lvalue = pow(lvalue, \fIexpr\fR) +.fi \fR +.P +.RE +.P +except that lvalue shall be evaluated only once. The value of the +expression: +.sp +.RS 4 +.nf +\fB +\fIexpr1\fR % \fIexpr2\fR +.fi \fR +.P +.RE +.P +shall be equivalent to the value returned by the ISO\ C standard function call: +.sp +.RS 4 +.nf +\fB +fmod(\fIexpr1\fR, \fIexpr2\fR) +.fi \fR +.P +.RE +.P +The expression: +.sp +.RS 4 +.nf +\fB +lvalue %= \fIexpr\fR +.fi \fR +.P +.RE +.P +shall be equivalent to the ISO\ C standard expression: +.sp +.RS 4 +.nf +\fB +lvalue = fmod(lvalue, \fIexpr\fR) +.fi \fR +.P +.RE +.P +except that lvalue shall be evaluated only once. +.P +Variables and fields shall be set by the assignment statement: +.sp +.RS 4 +.nf +\fB +lvalue = \fIexpression\fR +.fi \fR +.P +.RE +.P +and the type of +.IR expression +shall determine the resulting variable type. The assignment includes +the arithmetic assignments (\c +.BR \(dq+=\(dq , +.BR \(dq\(mi=\(dq , +.BR \(dq*=\(dq , +.BR \(dq/=\(dq , +.BR \(dq%=\(dq , +.BR \(dq^=\(dq , +.BR \(dq++\(dq , +.BR \(dq\(mi\|\(mi\(dq ) +all of which shall produce a numeric result. The left-hand side of an +assignment and the target of increment and decrement operators can be +one of a variable, an array with index, or a field selector. +.P +The +.IR awk +language supplies arrays that are used for storing numbers or strings. +Arrays need not be declared. They shall initially be empty, and their +sizes shall change dynamically. The subscripts, or element identifiers, +are strings, providing a type of associative array capability. An array +name followed by a subscript within square brackets can be used as an +lvalue and thus as an expression, as described in the grammar; see +.IR "Grammar". +Unsubscripted array names can be used in only the following contexts: +.IP " *" 4 +A parameter in a function definition or function call +.IP " *" 4 +The +.BR NAME +token following any use of the keyword +.BR in +as specified in the grammar (see +.IR "Grammar"); +if the name used in this context is not an array name, the behavior is +undefined +.P +A valid array +.IR index +shall consist of one or more +-separated +expressions, similar to the way in which multi-dimensional arrays are +indexed in some programming languages. Because +.IR awk +arrays are really one-dimensional, such a +-separated +list shall be converted to a single string by concatenating the string +values of the separate expressions, each separated from the other by +the value of the +.BR SUBSEP +variable. Thus, the following two index operations shall be +equivalent: +.sp +.RS 4 +.nf +\fB +\fIvar\fB[\fIexpr1\fR, \fIexpr2\fR, ... \fIexprn\fB] +.P +\fIvar\fB[\fIexpr1\fR SUBSEP \fIexpr2\fR SUBSEP ... \fRSUBSEP \fIexprn\fB]\fR +.fi \fR +.P +.RE +.P +The application shall ensure that a multi-dimensioned +.IR index +used with the +.BR in +operator is parenthesized. The +.BR in +operator, which tests for the existence of a particular array element, +shall not cause that element to exist. Any other reference to a +nonexistent array element shall automatically create it. +.P +Comparisons (with the +.BR '<' , +.BR \(dq<=\(dq , +.BR \(dq!=\(dq , +.BR \(dq==\(dq , +.BR '>' , +and +.BR \(dq>=\(dq +operators) shall be made numerically if both operands are numeric, if +one is numeric and the other has a string value that is a numeric +string, or if one is numeric and the other has the uninitialized value. +Otherwise, operands shall be converted to strings as required and a +string comparison shall be made using the locale-specific collation +sequence. The value of the comparison expression shall be 1 if the +relation is true, or 0 if the relation is false. +.SS "Variables and Special Variables" +.P +Variables can be used in an +.IR awk +program by referencing them. With the exception of function parameters +(see +.IR "User-Defined Functions"), +they are not explicitly declared. Function parameter names shall be +local to the function; all other variable names shall be global. The +same name shall not be used as both a function parameter name and as +the name of a function or a special +.IR awk +variable. The same name shall not be used both as a variable name with +global scope and as the name of a function. The same name shall not be +used within the same scope both as a scalar variable and as an array. +Uninitialized variables, including scalar variables, array elements, +and field variables, shall have an uninitialized value. An +uninitialized value shall have both a numeric value of zero and a +string value of the empty string. Evaluation of variables with an +uninitialized value, to either string or numeric, shall be determined +by the context in which they are used. +.P +Field variables shall be designated by a +.BR '$' +followed by a number or numerical expression. The effect of the field +number +.IR expression +evaluating to anything other than a non-negative integer is +unspecified; uninitialized variables or string values need not be +converted to numeric values in this context. New field variables can be +created by assigning a value to them. References to nonexistent fields +(that is, fields after $\fBNF\fP), shall evaluate to the uninitialized +value. Such references shall not create new fields. However, assigning +to a nonexistent field (for example, $(\fBNF\fP+2)=5) shall increase +the value of +.BR NF ; +create any intervening fields with the uninitialized value; and cause +the value of $0 to be recomputed, with the fields being separated by +the value of +.BR OFS . +Each field variable shall have a string value or an uninitialized value +when created. Field variables shall have the uninitialized value when +created from $0 using +.BR FS +and the variable does not contain any characters. If appropriate, the +field variable shall be considered a numeric string (see +.IR "Expressions in awk"). +.P +Implementations shall support the following other special variables +that are set by +.IR awk : +.IP "\fBARGC\fR" 10 +The number of elements in the +.BR ARGV +array. +.IP "\fBARGV\fR" 10 +An array of command line arguments, excluding options and the +.IR program +argument, numbered from zero to +.BR ARGC \(mi1. +.RS 10 +.P +The arguments in +.BR ARGV +can be modified or added to; +.BR ARGC +can be altered. As each input file ends, +.IR awk +shall treat the next non-null element of +.BR ARGV , +up to the current value of +.BR ARGC \(mi1, +inclusive, as the name of the next input file. Thus, setting an element +of +.BR ARGV +to null means that it shall not be treated as an input file. The name +.BR '\(mi' +indicates the standard input. If an argument matches the format of an +.IR assignment +operand, this argument shall be treated as an +.IR assignment +rather than a +.IR file +argument. +.RE +.IP "\fBCONVFMT\fR" 10 +The +.BR printf +format for converting numbers to strings (except for output statements, +where +.BR OFMT +is used); +.BR \(dq%.6g\(dq +by default. +.IP "\fBENVIRON\fR" 10 +An array representing the value of the environment, as described in the +.IR exec +functions defined in the System Interfaces volume of POSIX.1\(hy2008. The indices of the array shall be +strings consisting of the names of the environment variables, and the +value of each array element shall be a string consisting of the value +of that variable. If appropriate, the environment variable shall be +considered a +.IR "numeric string" +(see +.IR "Expressions in awk"); +the array element shall also have its numeric value. +.RS 10 +.P +In all cases where the behavior of +.IR awk +is affected by environment variables (including the environment of any +commands that +.IR awk +executes via the +.BR system +function or via pipeline redirections with the +.BR print +statement, the +.BR printf +statement, or the +.BR getline +function), the environment used shall be the environment at the time +.IR awk +began executing; it is implementation-defined whether any +modification of +.BR ENVIRON +affects this environment. +.RE +.IP "\fBFILENAME\fR" 10 +A pathname of the current input file. Inside a +.BR BEGIN +action the value is undefined. Inside an +.BR END +action the value shall be the name of the last input file processed. +.IP "\fBFNR\fR" 10 +The ordinal number of the current record in the current file. Inside a +.BR BEGIN +action the value shall be zero. Inside an +.BR END +action the value shall be the number of the last record processed in +the last file processed. +.IP "\fBFS\fR" 10 +Input field separator regular expression; a + +by default. +.IP "\fBNF\fR" 10 +The number of fields in the current record. Inside a +.BR BEGIN +action, the use of +.BR NF +is undefined unless a +.BR getline +function without a +.IR var +argument is executed previously. Inside an +.BR END +action, +.BR NF +shall retain the value it had for the last record read, unless a +subsequent, redirected, +.BR getline +function without a +.IR var +argument is performed prior to entering the +.BR END +action. +.IP "\fBNR\fR" 10 +The ordinal number of the current record from the start of input. +Inside a +.BR BEGIN +action the value shall be zero. Inside an +.BR END +action the value shall be the number of the last record processed. +.IP "\fBOFMT\fR" 10 +The +.BR printf +format for converting numbers to strings in output statements (see +.IR "Output Statements"); +.BR \(dq%.6g\(dq +by default. The result of the conversion is unspecified if the value of +.BR OFMT +is not a floating-point format specification. +.IP "\fBOFS\fR" 10 +The +.BR print +statement output field separator; + +by default. +.IP "\fBORS\fR" 10 +The +.BR print +statement output record separator; a + +by default. +.IP "\fBRLENGTH\fR" 10 +The length of the string matched by the +.BR match +function. +.IP "\fBRS\fR" 10 +The first character of the string value of +.BR RS +shall be the input record separator; a + +by default. If +.BR RS +contains more than one character, the results are unspecified. If +.BR RS +is null, then records are separated by sequences consisting of a + +plus one or more blank lines, leading or trailing blank lines shall not +result in empty records at the beginning or end of the input, and a + +shall always be a field separator, no matter what the value of +.BR FS +is. +.IP "\fBRSTART\fR" 10 +The starting position of the string matched by the +.BR match +function, numbering from 1. This shall always be equivalent to the +return value of the +.BR match +function. +.IP "\fBSUBSEP\fR" 10 +The subscript separator string for multi-dimensional arrays; the +default value is implementation-defined. +.SS "Regular Expressions" +.P +The +.IR awk +utility shall make use of the extended regular expression notation +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions") +except that it shall allow the use of C-language conventions +for escaping special characters within the EREs, as specified in the +table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +and the following table; these escape sequences shall be recognized +both inside and outside bracket expressions. Note that records need not +be separated by + +characters and string constants can contain + +characters, so even the +.BR \(dq\en\(dq +sequence is valid in +.IR awk +EREs. Using a + +character within an ERE requires the escaping shown in the following +table. +.br +.sp +.ce 1 +\fBTable 4-2: Escape Sequences in \fIawk\fP\fR +.ad l +.TS +center tab(@) box; +cB | cB | cB +cB | cB | cB +lf5 | lw(34) | lw(34). +Escape +Sequence@Description@Meaning +_ +\e"@T{ + +T}@T{ + character +T} +_ +\e/@T{ + +T}@T{ + character +T} +_ +\eddd@T{ +A + +character followed by the longest sequence of one, two, or +three octal-digit characters (01234567). If all of the digits are 0 +(that is, representation of the NUL character), the behavior is +undefined. +T}@T{ +The character whose encoding is represented by the one, two, or +three-digit octal integer. Multi-byte characters require +multiple, concatenated escape sequences of this type, including the +leading + +for each byte. +T} +_ +\ec@T{ +A + +character followed by any character not described in this +table or in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +T}@Undefined +.TE +.ad b +.P +A regular expression can be matched against a specific field or string +by using one of the two regular expression matching operators, +.BR '~' +and +.BR \(dq!~\(dq . +These operators shall interpret their right-hand operand as a regular +expression and their left-hand operand as a string. If the regular +expression matches the string, the +.BR '~' +expression shall evaluate to a value of 1, and the +.BR \(dq!~\(dq +expression shall evaluate to a value of 0. (The regular expression +matching operation is as defined by the term matched in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.1" ", " "Regular Expression Definitions", +where a match occurs on any part of the string unless the regular +expression is limited with the + +or + +special characters.) If the regular expression does not match the +string, the +.BR '~' +expression shall evaluate to a value of 0, and the +.BR \(dq!~\(dq +expression shall evaluate to a value of 1. If the right-hand operand is +any expression other than the lexical token +.BR ERE , +the string value of the expression shall be interpreted as an extended +regular expression, including the escape conventions described above. +Note that these same escape conventions shall also be applied in +determining the value of a string literal (the lexical token +.BR STRING ), +and thus shall be applied a second time when a string literal is used +in this context. +.P +When an +.BR ERE +token appears as an expression in any context other than as the +right-hand of the +.BR '~' +or +.BR \(dq!~\(dq +operator or as one of the built-in function arguments described below, +the value of the resulting expression shall be the equivalent of: +.sp +.RS 4 +.nf +\fB +$0 " " /\fIere\fR/ +.fi \fR +.P +.RE +.P +The +.IR ere +argument to the +.BR gsub , +.BR match , +.BR sub +functions, and the +.IR fs +argument to the +.BR split +function (see +.IR "String Functions") +shall be interpreted as extended regular expressions. These can be +either +.BR ERE +tokens or arbitrary expressions, and shall be interpreted in the same +manner as the right-hand side of the +.BR '~' +or +.BR \(dq!~\(dq +operator. +.P +An extended regular expression can be used to separate fields by assigning +a string containing the expression to the built-in variable +.BR FS , +either directly or as a consequence of using the +.BR \(miF +.IR sepstring +option. +The default value of the +.BR FS +variable shall be a single +. +The following describes +.BR FS +behavior: +.IP " 1." 4 +If +.BR FS +is a null string, the behavior is unspecified. +.IP " 2." 4 +If +.BR FS +is a single character: +.RS 4 +.IP " a." 4 +If +.BR FS +is +, +skip leading and trailing + +and + +characters; fields shall be delimited by sets of one or more + +or + +characters. +.IP " b." 4 +Otherwise, if +.BR FS +is any other character +.IR c , +fields shall be delimited by each single occurrence of +.IR c . +.RE +.IP " 3." 4 +Otherwise, the string value of +.BR FS +shall be considered to be an extended regular expression. Each +occurrence of a sequence matching the extended regular expression shall +delimit fields. +.P +Except for the +.BR '~' +and +.BR \(dq!~\(dq +operators, and in the +.BR gsub , +.BR match , +.BR split , +and +.BR sub +built-in functions, ERE matching shall be based on input records; that +is, record separator characters (the first character of the value of +the variable +.BR RS , + +by default) cannot be embedded in the expression, and no expression +shall match the record separator character. If the record separator is +not +, + +characters embedded in the expression can be matched. For the +.BR '~' +and +.BR \(dq!~\(dq +operators, and in those four built-in functions, ERE matching shall be +based on text strings; that is, any character (including + +and the record separator) can be embedded in the pattern, and an +appropriate pattern shall match any character. However, in all +.IR awk +ERE matching, the use of one or more NUL characters in the pattern, +input record, or text string produces undefined results. +.SS "Patterns" +.P +A +.IR pattern +is any valid +.IR expression , +a range specified by two expressions separated by a comma, or one of the +two special patterns +.BR BEGIN +or +.BR END . +.SS "Special Patterns" +.P +The +.IR awk +utility shall recognize two special patterns, +.BR BEGIN +and +.BR END . +Each +.BR BEGIN +pattern shall be matched once and its associated action executed before +the first record of input is read\(emexcept possibly by use of the +.BR getline +function (see +.IR "Input/Output and General Functions") +in a prior +.BR BEGIN +action\(emand before command line assignment is done. Each +.BR END +pattern shall be matched once and its associated action executed after +the last record of input has been read. These two patterns shall have +associated actions. +.P +.BR BEGIN +and +.BR END +shall not combine with other patterns. Multiple +.BR BEGIN +and +.BR END +patterns shall be allowed. The actions associated with the +.BR BEGIN +patterns shall be executed in the order specified in the program, as +are the +.BR END +actions. An +.BR END +pattern can precede a +.BR BEGIN +pattern in a program. +.P +If an +.IR awk +program consists of only actions with the pattern +.BR BEGIN , +and the +.BR BEGIN +action contains no +.BR getline +function, +.IR awk +shall exit without reading its input when the last statement in the +last +.BR BEGIN +action is executed. If an +.IR awk +program consists of only actions with the pattern +.BR END +or only actions with the patterns +.BR BEGIN +and +.BR END , +the input shall be read before the statements in the +.BR END +actions are executed. +.SS "Expression Patterns" +.P +An expression pattern shall be evaluated as if it were an expression in +a Boolean context. If the result is true, the pattern shall be +considered to match, and the associated action (if any) shall be +executed. If the result is false, the action shall not be executed. +.SS "Pattern Ranges" +.P +A pattern range consists of two expressions separated by a comma; in +this case, the action shall be performed for all records between a +match of the first expression and the following match of the second +expression, inclusive. At this point, the pattern range can be repeated +starting at input records subsequent to the end of the matched range. +.SS "Actions" +.P +An action is a sequence of statements as shown in the grammar in +.IR "Grammar". +Any single statement can be replaced by a statement list enclosed in +curly braces. The application shall ensure that statements in a +statement list are separated by + +or + +characters. Statements in a statement list shall be executed sequentially +in the order that they appear. +.P +The +.IR expression +acting as the conditional in an +.BR if +statement shall be evaluated and if it is non-zero or non-null, the +following statement shall be executed; otherwise, if +.BR else +is present, the statement following the +.BR else +shall be executed. +.P +The +.BR if , +.BR while , +.BR do .\|.\|.\c +.BR while , +.BR for , +.BR break , +and +.BR continue +statements are based on the ISO\ C standard (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"), +except that the Boolean expressions shall be treated as described in +.IR "Expressions in awk", +and except in the case of: +.sp +.RS 4 +.nf +\fB +for (\fIvariable\fR in \fIarray\fR) +.fi \fR +.P +.RE +.P +which shall iterate, assigning each +.IR index +of +.IR array +to +.IR variable +in an unspecified order. The results of adding new elements to +.IR array +within such a +.BR for +loop are undefined. If a +.BR break +or +.BR continue +statement occurs outside of a loop, the behavior is undefined. +.P +The +.BR delete +statement shall remove an individual array element. Thus, the following +code deletes an entire array: +.sp +.RS 4 +.nf +\fB +for (index in array) + delete array[index] +.fi \fR +.P +.RE +.P +The +.BR next +statement shall cause all further processing of the current input +record to be abandoned. The behavior is undefined if a +.BR next +statement appears or is invoked in a +.BR BEGIN +or +.BR END +action. +.P +The +.BR exit +statement shall invoke all +.BR END +actions in the order in which they occur in the program source and then +terminate the program without reading further input. An +.BR exit +statement inside an +.BR END +action shall terminate the program without further execution of +.BR END +actions. If an expression is specified in an +.BR exit +statement, its numeric value shall be the exit status of +.IR awk , +unless subsequent errors are encountered or a subsequent +.BR exit +statement with an expression is executed. +.SS "Output Statements" +.P +Both +.BR print +and +.BR printf +statements shall write to standard output by default. The output shall +be written to the location specified by +.IR output_redirection +if one is supplied, as follows: +.sp +.RS 4 +.nf +\fB +> \fIexpression\fR +>> \fIexpression\fR +| \fIexpression\fR +.fi \fR +.P +.RE +.P +In all cases, the +.IR expression +shall be evaluated to produce a string that is used as a pathname +into which to write (for +.BR '>' +or +.BR \(dq>>\(dq ) +or as a command to be executed (for +.BR '|' ). +Using the first two forms, if the file of that name is not currently +open, it shall be opened, creating it if necessary and using the first +form, truncating the file. The output then shall be appended to the +file. As long as the file remains open, subsequent calls in which +.IR expression +evaluates to the same string value shall simply append output to the +file. The file remains open until the +.BR close +function (see +.IR "Input/Output and General Functions") +is called with an expression that evaluates to the same string value. +.P +The third form shall write output onto a stream piped to the input of a +command. The stream shall be created if no stream is currently open +with the value of +.IR expression +as its command name. The stream created shall be equivalent to one +created by a call to the +\fIpopen\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 with the value of +.IR expression +as the +.IR command +argument and a value of +.IR w +as the +.IR mode +argument. As long as the stream remains open, subsequent calls in which +.IR expression +evaluates to the same string value shall write output to the existing +stream. The stream shall remain open until the +.BR close +function (see +.IR "Input/Output and General Functions") +is called with an expression that evaluates to the same string value. +At that time, the stream shall be closed as if by a call to the +\fIpclose\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. +.P +As described in detail by the grammar in +.IR "Grammar", +these output statements shall take a +-separated +list of +.IR expression s +referred to in the grammar by the non-terminal symbols +.BR expr_list , +.BR print_expr_list , +or +.BR print_expr_list_opt . +This list is referred to here as the +.IR "expression list" , +and each member is referred to as an +.IR "expression argument" . +.P +The +.BR print +statement shall write the value of each expression argument onto the +indicated output stream separated by the current output field separator +(see variable +.BR OFS +above), and terminated by the output record separator (see variable +.BR ORS +above). All expression arguments shall be taken as strings, being +converted if necessary; this conversion shall be as described in +.IR "Expressions in awk", +with the exception that the +.BR printf +format in +.BR OFMT +shall be used instead of the value in +.BR CONVFMT . +An empty expression list shall stand for the whole input record ($0). +.P +The +.BR printf +statement shall produce output based on a notation similar to the +File Format Notation used to describe file formats in this volume of POSIX.1\(hy2008 (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation"). +Output shall be produced as specified with the first +.IR expression +argument as the string +.IR format +and subsequent +.IR expression +arguments as the strings +.IR arg1 +to +.IR argn , +inclusive, with the following exceptions: +.IP " 1." 4 +The +.IR format +shall be an actual character string rather than a graphical +representation. Therefore, it cannot contain empty character +positions. The + +in the +.IR format +string, in any context other than a +.IR flag +of a conversion specification, shall be treated as an ordinary +character that is copied to the output. +.IP " 2." 4 +If the character set contains a +.BR ' ' +character and that character appears in the +.IR format +string, it shall be treated as an ordinary character that is copied to +the output. +.IP " 3." 4 +The +.IR "escape sequences" +beginning with a + +character shall be treated as sequences of ordinary characters that are +copied to the output. Note that these same sequences shall be interpreted +lexically by +.IR awk +when they appear in literal strings, but they shall not be treated +specially by the +.BR printf +statement. +.IP " 4." 4 +A +.IR "field width" +or +.IR precision +can be specified as the +.BR '*' +character instead of a digit string. In this case the next argument +from the expression list shall be fetched and its numeric value taken +as the field width or precision. +.IP " 5." 4 +The implementation shall not precede or follow output from the +.BR d +or +.BR u +conversion specifier characters with + +characters not specified by the +.IR format +string. +.IP " 6." 4 +The implementation shall not precede output from the +.BR o +conversion specifier character with leading zeros not specified by the +.IR format +string. +.IP " 7." 4 +For the +.BR c +conversion specifier character: if the argument has a numeric value, the +character whose encoding is that value shall be output. If the value is +zero or is not the encoding of any character in the character set, the +behavior is undefined. If the argument does not have a numeric value, +the first character of the string value shall be output; if the string +does not contain any characters, the behavior is undefined. +.IP " 8." 4 +For each conversion specification that consumes an argument, the next +expression argument shall be evaluated. With the exception of the +.BR c +conversion specifier character, the value shall be converted (according +to the rules specified in +.IR "Expressions in awk") +to the appropriate type for the conversion specification. +.IP " 9." 4 +If there are insufficient expression arguments to satisfy all the +conversion specifications in the +.IR format +string, the behavior is undefined. +.IP 10. 4 +If any character sequence in the +.IR format +string begins with a +.BR '%' +character, but does not form a valid conversion specification, the +behavior is unspecified. +.P +Both +.BR print +and +.BR printf +can output at least +{LINE_MAX} +bytes. +.SS "Functions" +.P +The +.IR awk +language has a variety of built-in functions: arithmetic, string, +input/output, and general. +.SS "Arithmetic Functions" +.P +The arithmetic functions, except for +.BR int , +shall be based on the ISO\ C standard (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"). +The behavior is undefined in cases where the ISO\ C standard specifies that an +error be returned or that the behavior is undefined. Although the +grammar (see +.IR "Grammar") +permits built-in functions to appear with no arguments or parentheses, +unless the argument or parentheses are indicated as optional in the +following list (by displaying them within the +.BR \(dq[]\(dq +brackets), such use is undefined. +.IP "\fBatan2\fR(\fIy\fR,\fIx\fR)" 10 +Return arctangent of \fIy\fP/\fIx\fR in radians in the range +[\(mi\(*p,\(*p]. +.IP "\fBcos\fR(\fIx\fR)" 10 +Return cosine of \fIx\fP, where \fIx\fP is in radians. +.IP "\fBsin\fR(\fIx\fR)" 10 +Return sine of \fIx\fP, where \fIx\fP is in radians. +.IP "\fBexp\fR(\fIx\fR)" 10 +Return the exponential function of \fIx\fP. +.IP "\fBlog\fR(\fIx\fR)" 10 +Return the natural logarithm of \fIx\fP. +.IP "\fBsqrt\fR(\fIx\fR)" 10 +Return the square root of \fIx\fP. +.IP "\fBint\fR(\fIx\fR)" 10 +Return the argument truncated to an integer. Truncation shall +be toward 0 when \fIx\fP>0. +.IP "\fBrand\fP(\|)" 10 +Return a random number \fIn\fP, such that 0\(<=\fIn\fP<1. +.IP "\fBsrand\fR(\fB[\fIexpr\fB]\fR)" 10 +Set the seed value for +.IR rand +to +.IR expr +or use the time of day if +.IR expr +is omitted. The previous seed value shall be returned. +.SS "String Functions" +.P +The string functions in the following list shall be supported. +Although the grammar (see +.IR "Grammar") +permits built-in functions to appear with no arguments or parentheses, +unless the argument or parentheses are indicated as optional in the +following list (by displaying them within the +.BR \(dq[]\(dq +brackets), such use is undefined. +.IP "\fBgsub\fR(\fIere\fR,\ \fIrepl\fB[\fR,\ \fIin\fB]\fR)" 10 +.br +Behave like +.BR sub +(see below), except that it shall replace all occurrences of the +regular expression (like the +.IR ed +utility global substitute) in $0 or in the +.IR in +argument, when specified. +.IP "\fBindex\fR(\fIs\fR,\ \fIt\fR)" 10 +Return the position, in characters, numbering from 1, in string +.IR s +where string +.IR t +first occurs, or zero if it does not occur at all. +.IP "\fBlength[\fR(\fB[\fIs\fB]\fR)\fB]\fR" 10 +Return the length, in characters, of its argument taken as a string, or +of the whole record, $0, if there is no argument. +.IP "\fBmatch\fR(\fIs\fR,\ \fIere\fR)" 10 +Return the position, in characters, numbering from 1, in string +.IR s +where the extended regular expression +.IR ere +occurs, or zero if it does not occur at all. RSTART shall be set to the +starting position (which is the same as the returned value), zero if no +match is found; RLENGTH shall be set to the length of the matched +string, \(mi1 if no match is found. +.IP "\fBsplit\fR(\fIs\fR,\ \fIa\fB[\fR,\ \fIfs\ \fB]\fR)" 10 +.br +Split the string +.IR s +into array elements +.IR a [1], +.IR a [2], +\&.\|.\|., +.IR a [ n ], +and return +.IR n . +All elements of the array shall be deleted before the split is +performed. The separation shall be done with the ERE +.IR fs +or with the field separator +.BR FS +if +.IR fs +is not given. Each array element shall have a string value when created +and, if appropriate, the array element shall be considered a numeric +string (see +.IR "Expressions in awk"). +The effect of a null string as the value of +.IR fs +is unspecified. +.IP "\fBsprintf\fR(\fIfmt\fR,\ \fIexpr\fR,\ \fIexpr\fR,\ .\|.\|.)" 10 +.br +Format the expressions according to the +.BR printf +format given by +.IR fmt +and return the resulting string. +.IP "\fBsub(\fIere\fR,\ \fIrepl\fB[\fR,\ \fIin\ \fB]\fR)" 10 +.br +Substitute the string +.IR repl +in place of the first instance of the extended regular expression +.IR ERE +in string +.IR in +and return the number of substitutions. An + +(\c +.BR '&' ) +appearing in the string +.IR repl +shall be replaced by the string from +.IR in +that matches the ERE. An + +preceded with a + +shall be interpreted as the literal + +character. An occurrence of two consecutive + +characters shall be interpreted as just a single literal + +character. Any other occurrence of a + +(for example, preceding any other character) shall be treated as a +literal + +character. Note that if +.IR repl +is a string literal (the lexical token +.BR STRING ; +see +.IR "Grammar"), +the handling of the + +character occurs after any lexical processing, including any lexical +-escape +sequence processing. If +.IR in +is specified and it is not an lvalue (see +.IR "Expressions in awk"), +the behavior is undefined. If +.IR in +is omitted, +.IR awk +shall use the current record ($0) in its place. +.IP "\fBsubstr\fR(\fIs\fR,\ \fIm\fB[\fR,\ \fIn\ \fB]\fR)" 10 +.br +Return the at most +.IR n -character +substring of +.IR s +that begins at position +.IR m , +numbering from 1. If +.IR n +is omitted, or if +.IR n +specifies more characters than are left in the string, the length of +the substring shall be limited by the length of the string +.IR s . +.IP "\fBtolower\fR(\fIs\fR)" 10 +Return a string based on the string +.IR s . +Each character in +.IR s +that is an uppercase letter specified to have a +.BR tolower +mapping by the +.IR LC_CTYPE +category of the current locale shall be replaced in the returned string +by the lowercase letter specified by the mapping. Other characters in +.IR s +shall be unchanged in the returned string. +.IP "\fBtoupper\fR(\fIs\fR)" 10 +Return a string based on the string +.IR s . +Each character in +.IR s +that is a lowercase letter specified to have a +.BR toupper +mapping by the +.IR LC_CTYPE +category of the current locale is replaced in the returned string by +the uppercase letter specified by the mapping. Other characters in +.IR s +are unchanged in the returned string. +.P +All of the preceding functions that take +.IR ERE +as a parameter expect a pattern or a string valued expression that is a +regular expression as defined in +.IR "Regular Expressions". +.SS "Input/Output and General Functions" +.P +The input/output and general functions are: +.IP "\fBclose\fR(\fIexpression\fR)" 10 +.br +Close the file or pipe opened by a +.BR print +or +.BR printf +statement or a call to +.BR getline +with the same string-valued +.IR expression . +The limit on the number of open +.IR expression +arguments is implementation-defined. If the close was successful, the +function shall return zero; otherwise, it shall return non-zero. +.IP "\fIexpression\ |\ \fBgetline\ [\fIvar\fB]\fR" 10 +.br +Read a record of input from a stream piped from the output of a +command. The stream shall be created if no stream is currently open +with the value of +.IR expression +as its command name. The stream created shall be equivalent to one +created by a call to the +\fIpopen\fR() +function with the value of +.IR expression +as the +.IR command +argument and a value of +.IR r +as the +.IR mode +argument. As long as the stream remains open, subsequent calls in which +.IR expression +evaluates to the same string value shall read subsequent records from +the stream. The stream shall remain open until the +.BR close +function is called with an expression that evaluates to the same string +value. At that time, the stream shall be closed as if by a call to the +\fIpclose\fR() +function. If +.IR var +is omitted, $0 and +.BR NF +shall be set; otherwise, +.IR var +shall be set and, if appropriate, it shall be considered a numeric +string (see +.IR "Expressions in awk"). +.RS 10 +.P +The +.BR getline +operator can form ambiguous constructs when there are unparenthesized +operators (including concatenate) to the left of the +.BR '|' +(to the beginning of the expression containing +.BR getline ). +In the context of the +.BR '$' +operator, +.BR '|' +shall behave as if it had a lower precedence than +.BR '$' . +The result of evaluating other operators is unspecified, and conforming +applications shall parenthesize properly all such usages. +.RE +.IP "\fBgetline\fR" 10 +Set $0 to the next input record from the current input file. This form +of +.BR getline +shall set the +.BR NF , +.BR NR , +and +.BR FNR +variables. +.IP "\fBgetline\ \fIvar\fR" 10 +Set variable +.IR var +to the next input record from the current input file and, if +appropriate, +.IR var +shall be considered a numeric string (see +.IR "Expressions in awk"). +This form of +.BR getline +shall set the +.BR FNR +and +.BR NR +variables. +.IP "\fBgetline\ \fB[\fIvar\fB]\ \fR<\ \fIexpression\fR" 10 +.br +Read the next record of input from a named file. The +.IR expression +shall be evaluated to produce a string that is used as a pathname. +If the file of that name is not currently open, it shall be opened. As +long as the stream remains open, subsequent calls in which +.IR expression +evaluates to the same string value shall read subsequent records from +the file. The file shall remain open until the +.BR close +function is called with an expression that evaluates to the same string +value. If +.IR var +is omitted, $0 and +.BR NF +shall be set; otherwise, +.IR var +shall be set and, if appropriate, it shall be considered a numeric +string (see +.IR "Expressions in awk"). +.RS 10 +.P +The +.BR getline +operator can form ambiguous constructs when there are unparenthesized +binary operators (including concatenate) to the right of the +.BR '<' +(up to the end of the expression containing the +.BR getline ). +The result of evaluating such a construct is unspecified, and conforming +applications shall parenthesize properly all such usages. +.RE +.IP "\fBsystem\fR(\fIexpression\fR)" 10 +.br +Execute the command given by +.IR expression +in a manner equivalent to the +\fIsystem\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 and return the exit status of the +command. +.P +All forms of +.BR getline +shall return 1 for successful input, zero for end-of-file, and \(mi1 +for an error. +.P +Where strings are used as the name of a file or pipeline, the +application shall ensure that the strings are textually identical. The +terminology ``same string value'' implies that ``equivalent strings'', +even those that differ only by + +characters, represent different files. +.SS "User-Defined Functions" +.P +The +.IR awk +language also provides user-defined functions. Such functions can be +defined as: +.sp +.RS 4 +.nf +\fB +function \fIname\fR(\fB[\fIparameter\fR, ...\fB]\fR) { \fIstatements\fR } +.fi \fR +.P +.RE +.P +A function can be referred to anywhere in an +.IR awk +program; in particular, its use can precede its definition. The scope +of a function is global. +.P +Function parameters, if present, can be either scalars or arrays; the +behavior is undefined if an array name is passed as a parameter that +the function uses as a scalar, or if a scalar expression is passed as a +parameter that the function uses as an array. Function parameters shall +be passed by value if scalar and by reference if array name. +.P +The number of parameters in the function definition need not match the +number of parameters in the function call. Excess formal parameters can +be used as local variables. If fewer arguments are supplied in a +function call than are in the function definition, the extra parameters +that are used in the function body as scalars shall evaluate to the +uninitialized value until they are otherwise initialized, and the extra +parameters that are used in the function body as arrays shall be +treated as uninitialized arrays where each element evaluates to the +uninitialized value until otherwise initialized. +.P +When invoking a function, no white space can be placed between the +function name and the opening parenthesis. Function calls can be nested +and recursive calls can be made upon functions. Upon return from any +nested or recursive function call, the values of all of the calling +function's parameters shall be unchanged, except for array parameters +passed by reference. The +.BR return +statement can be used to return a value. If a +.BR return +statement appears outside of a function definition, the behavior is +undefined. +.P +In the function definition, + +characters shall be optional before the opening brace and after the +closing brace. Function definitions can appear anywhere in the program +where a +.IR pattern-action +pair is allowed. +.SS "Grammar" +.P +The grammar in this section and the lexical conventions in the +following section shall together describe the syntax for +.IR awk +programs. The general conventions for this style of grammar are +described in +.IR "Section 1.3" ", " "Grammar Conventions". +A valid program can be represented as the non-terminal symbol +.IR program +in the grammar. This formal syntax shall take precedence over the +preceding text syntax description. +.sp +.RS 4 +.nf +\fB +%token NAME NUMBER STRING ERE +%token FUNC_NAME /* Name followed by '(' without white space. */ +.P +/* Keywords */ +%token Begin End +/* 'BEGIN' 'END' */ +.P +%token Break Continue Delete Do Else +/* 'break' 'continue' 'delete' 'do' 'else' */ +.P +%token Exit For Function If In +/* 'exit' 'for' 'function' 'if' 'in' */ +.P +%token Next Print Printf Return While +/* 'next' 'print' 'printf' 'return' 'while' */ +.P +/* Reserved function names */ +%token BUILTIN_FUNC_NAME + /* One token for the following: + * atan2 cos sin exp log sqrt int rand srand + * gsub index length match split sprintf sub + * substr tolower toupper close system + */ +%token GETLINE + /* Syntactically different from other built-ins. */ +.P +/* Two-character tokens. */ +%token ADD_ASSIGN SUB_ASSIGN MUL_ASSIGN DIV_ASSIGN MOD_ASSIGN POW_ASSIGN +/* '+=' '\(mi=' '*=' '/=' '%=' '^=' */ +.P +%token OR AND NO_MATCH EQ LE GE NE INCR DECR APPEND +/* '||' '&&' '!\^~' '==' '<=' '>=' '!=' '++' '\(mi\|\(mi' '>>' */ +.P +/* One-character tokens. */ +%token '{' '}' '(' ')' '[' ']' ',' ';' NEWLINE +%token '+' '\(mi' '*' '%' '^' '!' '>' '<' '|' '?' ':' ' " " ' '$' '=' +.P +%start program +%% +.P +program : item_list + | actionless_item_list + ; +.P +item_list : newline_opt + | actionless_item_list item terminator + | item_list item terminator + | item_list action terminator + ; +.P +actionless_item_list : item_list pattern terminator + | actionless_item_list pattern terminator + ; +.P +item : pattern action + | Function NAME '(' param_list_opt ')' + newline_opt action + | Function FUNC_NAME '(' param_list_opt ')' + newline_opt action + ; +.P +param_list_opt : /* empty */ + | param_list + ; +.P +param_list : NAME + | param_list ',' NAME + ; +.P +pattern : Begin + | End + | expr + | expr ',' newline_opt expr + ; +.P +action : '{' newline_opt '}' + | '{' newline_opt terminated_statement_list '}' + | '{' newline_opt unterminated_statement_list '}' + ; +.P +terminator : terminator ';' + | terminator NEWLINE + | ';' + | NEWLINE + ; +.P +terminated_statement_list : terminated_statement + | terminated_statement_list terminated_statement + ; +.P +unterminated_statement_list : unterminated_statement + | terminated_statement_list unterminated_statement + ; +.P +terminated_statement : action newline_opt + | If '(' expr ')' newline_opt terminated_statement + | If '(' expr ')' newline_opt terminated_statement + Else newline_opt terminated_statement + | While '(' expr ')' newline_opt terminated_statement + | For '(' simple_statement_opt ';' + expr_opt ';' simple_statement_opt ')' newline_opt + terminated_statement + | For '(' NAME In NAME ')' newline_opt + terminated_statement + | ';' newline_opt + | terminatable_statement NEWLINE newline_opt + | terminatable_statement ';' newline_opt + ; +.P +unterminated_statement : terminatable_statement + | If '(' expr ')' newline_opt unterminated_statement + | If '(' expr ')' newline_opt terminated_statement + Else newline_opt unterminated_statement + | While '(' expr ')' newline_opt unterminated_statement + | For '(' simple_statement_opt ';' + expr_opt ';' simple_statement_opt ')' newline_opt + unterminated_statement + | For '(' NAME In NAME ')' newline_opt + unterminated_statement + ; +.P +terminatable_statement : simple_statement + | Break + | Continue + | Next + | Exit expr_opt + | Return expr_opt + | Do newline_opt terminated_statement While '(' expr ')' + ; +.P +simple_statement_opt : /* empty */ + | simple_statement + ; +.P +simple_statement : Delete NAME '[' expr_list ']' + | expr + | print_statement + ; +.P +print_statement : simple_print_statement + | simple_print_statement output_redirection + ; +.P +simple_print_statement : Print print_expr_list_opt + | Print '(' multiple_expr_list ')' + | Printf print_expr_list + | Printf '(' multiple_expr_list ')' + ; +.P +output_redirection : '>' expr + | APPEND expr + | '|' expr + ; +.P +expr_list_opt : /* empty */ + | expr_list + ; +.P +expr_list : expr + | multiple_expr_list + ; +.P +multiple_expr_list : expr ',' newline_opt expr + | multiple_expr_list ',' newline_opt expr + ; +.P +expr_opt : /* empty */ + | expr + ; +.P +expr : unary_expr + | non_unary_expr + ; +.P +unary_expr : '+' expr + | '\(mi' expr + | unary_expr '^' expr + | unary_expr '*' expr + | unary_expr '/' expr + | unary_expr '%' expr + | unary_expr '+' expr + | unary_expr '\(mi' expr + | unary_expr non_unary_expr + | unary_expr '<' expr + | unary_expr LE expr + | unary_expr NE expr + | unary_expr EQ expr + | unary_expr '>' expr + | unary_expr GE expr + | unary_expr '~' expr + | unary_expr NO_MATCH expr + | unary_expr In NAME + | unary_expr AND newline_opt expr + | unary_expr OR newline_opt expr + | unary_expr '?' expr ':' expr + | unary_input_function + ; +.P +non_unary_expr : '(' expr ')' + | '!' expr + | non_unary_expr '^' expr + | non_unary_expr '*' expr + | non_unary_expr '/' expr + | non_unary_expr '%' expr + | non_unary_expr '+' expr + | non_unary_expr '\(mi' expr + | non_unary_expr non_unary_expr + | non_unary_expr '<' expr + | non_unary_expr LE expr + | non_unary_expr NE expr + | non_unary_expr EQ expr + | non_unary_expr '>' expr + | non_unary_expr GE expr + | non_unary_expr '~' expr + | non_unary_expr NO_MATCH expr + | non_unary_expr In NAME + | '(' multiple_expr_list ')' In NAME + | non_unary_expr AND newline_opt expr + | non_unary_expr OR newline_opt expr + | non_unary_expr '?' expr ':' expr + | NUMBER + | STRING + | lvalue + | ERE + | lvalue INCR + | lvalue DECR + | INCR lvalue + | DECR lvalue + | lvalue POW_ASSIGN expr + | lvalue MOD_ASSIGN expr + | lvalue MUL_ASSIGN expr + | lvalue DIV_ASSIGN expr + | lvalue ADD_ASSIGN expr + | lvalue SUB_ASSIGN expr + | lvalue '=' expr + | FUNC_NAME '(' expr_list_opt ')' + /* no white space allowed before '(' */ + | BUILTIN_FUNC_NAME '(' expr_list_opt ')' + | BUILTIN_FUNC_NAME + | non_unary_input_function + ; +.P +print_expr_list_opt : /* empty */ + | print_expr_list + ; +.P +print_expr_list : print_expr + | print_expr_list ',' newline_opt print_expr + ; +.P +print_expr : unary_print_expr + | non_unary_print_expr + ; +.P +unary_print_expr : '+' print_expr + | '\(mi' print_expr + | unary_print_expr '^' print_expr + | unary_print_expr '*' print_expr + | unary_print_expr '/' print_expr + | unary_print_expr '%' print_expr + | unary_print_expr '+' print_expr + | unary_print_expr '\(mi' print_expr + | unary_print_expr non_unary_print_expr + | unary_print_expr '~' print_expr + | unary_print_expr NO_MATCH print_expr + | unary_print_expr In NAME + | unary_print_expr AND newline_opt print_expr + | unary_print_expr OR newline_opt print_expr + | unary_print_expr '?' print_expr ':' print_expr + ; +.P +non_unary_print_expr : '(' expr ')' + | '!' print_expr + | non_unary_print_expr '^' print_expr + | non_unary_print_expr '*' print_expr + | non_unary_print_expr '/' print_expr + | non_unary_print_expr '%' print_expr + | non_unary_print_expr '+' print_expr + | non_unary_print_expr '\(mi' print_expr + | non_unary_print_expr non_unary_print_expr + | non_unary_print_expr '~' print_expr + | non_unary_print_expr NO_MATCH print_expr + | non_unary_print_expr In NAME + | '(' multiple_expr_list ')' In NAME + | non_unary_print_expr AND newline_opt print_expr + | non_unary_print_expr OR newline_opt print_expr + | non_unary_print_expr '?' print_expr ':' print_expr + | NUMBER + | STRING + | lvalue + | ERE + | lvalue INCR + | lvalue DECR + | INCR lvalue + | DECR lvalue + | lvalue POW_ASSIGN print_expr + | lvalue MOD_ASSIGN print_expr + | lvalue MUL_ASSIGN print_expr + | lvalue DIV_ASSIGN print_expr + | lvalue ADD_ASSIGN print_expr + | lvalue SUB_ASSIGN print_expr + | lvalue '=' print_expr + | FUNC_NAME '(' expr_list_opt ')' + /* no white space allowed before '(' */ + | BUILTIN_FUNC_NAME '(' expr_list_opt ')' + | BUILTIN_FUNC_NAME + ; +.P +lvalue : NAME + | NAME '[' expr_list ']' + | '$' expr + ; +.P +non_unary_input_function : simple_get + | simple_get '<' expr + | non_unary_expr '|' simple_get + ; +.P +unary_input_function : unary_expr '|' simple_get + ; +.P +simple_get : GETLINE + | GETLINE lvalue + ; +.P +newline_opt : /* empty */ + | newline_opt NEWLINE + ; +.fi \fR +.P +.RE +.P +This grammar has several ambiguities that shall be resolved as +follows: +.IP " *" 4 +Operator precedence and associativity shall be as described in +.IR "Table 4-1, Expressions in Decreasing Precedence in \fIawk\fP". +.IP " *" 4 +In case of ambiguity, an +.BR else +shall be associated with the most immediately preceding +.BR if +that would satisfy the grammar. +.IP " *" 4 +In some contexts, a + +(\c +.BR '/' ) +that is used to surround an ERE could also be the division operator. +This shall be resolved in such a way that wherever the division +operator could appear, a + +is assumed to be the division operator. (There is no unary division +operator.) +.P +Each expression in an +.IR awk +program shall conform to the precedence and associativity rules, even +when this is not needed to resolve an ambiguity. For example, because +.BR '$' +has higher precedence than +.BR '++' , +the string +.BR \(dq$x++\(mi\|\(mi\(dq +is not a valid +.IR awk +expression, even though it is unambiguously parsed by the grammar as +.BR \(dq$(x++)\(mi\|\(mi\(dq . +.P +One convention that might not be obvious from the formal grammar is +where + +characters are acceptable. There are several obvious placements such as +terminating a statement, and a + +can be used to escape + +characters between any lexical tokens. In addition, + +characters without + +characters can follow a comma, an open brace, logical AND operator (\c +.BR \(dq&&\(dq ), +logical OR operator (\c +.BR \(dq||\(dq ), +the +.BR do +keyword, the +.BR else +keyword, and the closing parenthesis of an +.BR if , +.BR for , +or +.BR while +statement. For example: +.sp +.RS 4 +.nf +\fB +{ print $1, + $2 } +.fi \fR +.P +.RE +.SS "Lexical Conventions" +.P +The lexical conventions for +.IR awk +programs, with respect to the preceding grammar, shall be as follows: +.IP " 1." 4 +Except as noted, +.IR awk +shall recognize the longest possible token or delimiter beginning at a +given point. +.IP " 2." 4 +A comment shall consist of any characters beginning with the + +character and terminated by, but excluding the next occurrence of, a +. +Comments shall have no effect, except to delimit lexical tokens. +.IP " 3." 4 +The + +shall be recognized as the token +.BR NEWLINE . +.IP " 4." 4 +A + +character immediately followed by a + +shall have no effect. +.IP " 5." 4 +The token +.BR STRING +shall represent a string constant. A string constant shall begin with +the character +.BR '\&"' . +Within a string constant, a + +character shall be considered to begin an escape sequence as specified +in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +In addition, the escape sequences in +.IR "Table 4-2, Escape Sequences in \fIawk\fP" +shall be recognized. A + +shall not occur within a string constant. A string constant shall be +terminated by the first unescaped occurrence of the character +.BR '\&"' +after the one that begins the string constant. The value of the string +shall be the sequence of all unescaped characters and values of escape +sequences between, but not including, the two delimiting +.BR '\&"' +characters. +.IP " 6." 4 +The token +.BR ERE +represents an extended regular expression constant. An ERE constant +shall begin with the + +character. Within an ERE constant, a + +character shall be considered to begin an escape sequence as +specified in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation". +In addition, the escape sequences in +.IR "Table 4-2, Escape Sequences in \fIawk\fP" +shall be recognized. The application shall ensure that a + +does not occur within an ERE constant. An ERE constant shall be +terminated by the first unescaped occurrence of the + +character after the one that begins the ERE constant. The extended regular +expression represented by the ERE constant shall be the sequence of all +unescaped characters and values of escape sequences between, but not +including, the two delimiting + +characters. +.IP " 7." 4 +A + +shall have no effect, except to delimit lexical tokens or within +.BR STRING +or +.BR ERE +tokens. +.IP " 8." 4 +The token +.BR NUMBER +shall represent a numeric constant. Its form and numeric value shall +either be equivalent to the +.BR decimal-floating-constant +token as specified by the ISO\ C standard, or it shall be a sequence of decimal +digits and shall be evaluated as an integer constant in decimal. In +addition, implementations may accept numeric constants with the form +and numeric value equivalent to the +.BR hexadecimal-constant +and +.BR hexadecimal-floating-constant +tokens as specified by the ISO\ C standard. +.RS 4 +.P +If the value is too large or too small to be representable (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"), +the behavior is undefined. +.RE +.IP " 9." 4 +A sequence of underscores, digits, and alphabetics from the portable +character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"), +beginning with an + +or alphabetic character, shall be considered a word. +.IP 10. 4 +The following words are keywords that shall be recognized as individual +tokens; the name of the token is the same as the keyword: +.TS +tab(@); +lw(0.6i)eB leB leB leB leB leB. +T{ +.nf +BEGIN +break +continue +T}@T{ +.nf +delete +do +else +T}@T{ +.nf +END +exit +for +T}@T{ +.nf +function +getline +if +T}@T{ +.nf +in +next +print +T}@T{ +.nf +printf +return +while +T} +.TE +.IP 11. 4 +The following words are names of built-in functions and shall be +recognized as the token +.BR BUILTIN_FUNC_NAME : +.TS +tab(@); +lw(0.6i)eB leB leB leB leB leB. +T{ +.nf +atan2 +close +cos +exp +T}@T{ +.nf +gsub +index +int +length +T}@T{ +.nf +log +match +rand +sin +T}@T{ +.nf +split +sprintf +sqrt +srand +T}@T{ +.nf +sub +substr +system +tolower +T}@T{ +.nf +toupper +.fi +T} +.TE +.RS 4 +.P +The above-listed keywords and names of built-in functions are +considered reserved words. +.RE +.IP 12. 4 +The token +.BR NAME +shall consist of a word that is not a keyword or a name of a built-in +function and is not followed immediately (without any delimiters) by +the +.BR '(' +character. +.IP 13. 4 +The token +.BR FUNC_NAME +shall consist of a word that is not a keyword or a name of a built-in +function, followed immediately (without any delimiters) by the +.BR '(' +character. The +.BR '(' +character shall not be included as part of the token. +.IP 14. 4 +The following two-character sequences shall be recognized as the named +tokens: +.TS +box center tab(@); +cB | cB | cB | cB +lB | cf5 | lB | cf5. +Token Name@Sequence@Token Name@Sequence +_ +ADD_ASSIGN@+=@NO_MATCH@!~ +SUB_ASSIGN@\(mi=@EQ@== +MUL_ASSIGN@*=@LE@<= +DIV_ASSIGN@/=@GE@>= +MOD_ASSIGN@%=@NE@!= +POW_ASSIGN@^=@INCR@++ +OR@||@DECR@\(mi\|\(mi +AND@&&@APPEND@>> +.TE +.IP 15. 4 +The following single characters shall be recognized as tokens whose +names are the character: +.RS 4 +.sp +.RS 4 +.nf +\fB + { } ( ) [ ] , ; + \(mi * % ^ ! > < | ? : " " $ = +.fi \fR +.P +.RE +.RE +.P +There is a lexical ambiguity between the token +.BR ERE +and the tokens +.BR '/' +and +.BR DIV_ASSIGN . +When an input sequence begins with a + +character in any syntactic context where the token +.BR '/' +or +.BR DIV_ASSIGN +could appear as the next token in a valid program, the longer of those +two tokens that can be recognized shall be recognized. In any other +syntactic context where the token +.BR ERE +could appear as the next token in a valid program, the token +.BR ERE +shall be recognized. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were processed successfully. +.IP >0 6 +An error occurred. +.P +The exit status can be altered within the program by using an +.BR exit +expression. +.SH "CONSEQUENCES OF ERRORS" +If any +.IR file +operand is specified and the named file cannot be accessed, +.IR awk +shall write a diagnostic message to standard error and terminate +without any further action. +.P +If the program specified by either the +.IR program +operand or a +.IR progfile +operand is not a valid +.IR awk +program (as specified in the EXTENDED DESCRIPTION section), the +behavior is undefined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR index , +.BR length , +.BR match , +and +.BR substr +functions should not be confused with similar functions in the ISO\ C standard; +the +.IR awk +versions deal with characters, while the ISO\ C standard deals with bytes. +.P +Because the concatenation operation is represented by adjacent +expressions rather than an explicit operator, it is often necessary to +use parentheses to enforce the proper evaluation precedence. +.SH EXAMPLES +The +.IR awk +program specified in the command line is most easily specified within +single-quotes (for example, '\fIprogram\fP') for applications using +.IR sh , +because +.IR awk +programs commonly contain characters that are special to the shell, +including double-quotes. In the cases where an +.IR awk +program contains single-quote characters, it is usually easiest to +specify most of the program as strings within single-quotes +concatenated by the shell with quoted single-quote characters. For +example: +.sp +.RS 4 +.nf +\fB +awk '/'\e''/ { print "quote:", $0 }' +.fi \fR +.P +.RE +.P +prints all lines from the standard input containing a single-quote +character, prefixed with +.IR quote :. +.P +The following are examples of simple +.IR awk +programs: +.IP " 1." 4 +Write to the standard output all input lines for which field 3 is +greater than 5: +.RS 4 +.sp +.RS 4 +.nf +\fB +$3 > 5 +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Write every tenth line: +.RS 4 +.sp +.RS 4 +.nf +\fB +(NR % 10) == 0 +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Write any line with a substring matching the regular expression: +.RS 4 +.sp +.RS 4 +.nf +\fB +/(G|D)(2[0\(mi9][[:alpha:]]*)/ +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Print any line with a substring containing a +.BR 'G' +or +.BR 'D' , +followed by a sequence of digits and characters. This example uses +character classes +.BR digit +and +.BR alpha +to match language-independent digit and alphabetic characters +respectively: +.RS 4 +.sp +.RS 4 +.nf +\fB +/(G|D)([[:digit:][:alpha:]]*)/ +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +Write any line in which the second field matches the regular expression +and the fourth field does not: +.RS 4 +.sp +.RS 4 +.nf +\fB +$2 " " /xyz/ && $4 ! " " /xyz/ +.fi \fR +.P +.RE +.RE +.IP " 6." 4 +Write any line in which the second field contains a +: +.RS 4 +.sp +.RS 4 +.nf +\fB +$2 " " /\e\e/ +.fi \fR +.P +.RE +.RE +.IP " 7." 4 +Write any line in which the second field contains a +. +Note that +-escapes +are interpreted twice; once in lexical processing of the string and once +in processing the regular expression: +.RS 4 +.sp +.RS 4 +.nf +\fB +$2 " " "\e\e\e\e" +.fi \fR +.P +.RE +.RE +.IP " 8." 4 +Write the second to the last and the last field in each line. Separate +the fields by a +: +.RS 4 +.sp +.RS 4 +.nf +\fB +{OFS=":";print $(NF\(mi1), $NF} +.fi \fR +.P +.RE +.RE +.IP " 9." 4 +Write the line number and number of fields in each line. The three +strings representing the line number, the +, +and the number of fields are concatenated and that string is written to +standard output: +.RS 4 +.sp +.RS 4 +.nf +\fB +{print NR ":" NF} +.fi \fR +.P +.RE +.RE +.IP 10. 4 +Write lines longer than 72 characters: +.RS 4 +.sp +.RS 4 +.nf +\fB +length($0) > 72 +.fi \fR +.P +.RE +.RE +.IP 11. 4 +Write the first two fields in opposite order separated by +.BR OFS : +.RS 4 +.sp +.RS 4 +.nf +\fB +{ print $2, $1 } +.fi \fR +.P +.RE +.RE +.IP 12. 4 +Same, with input fields separated by a + +or + +and + +characters, or both: +.RS 4 +.sp +.RS 4 +.nf +\fB +BEGIN { FS = ",[ \et]*|[ \et]+" } + { print $2, $1 } +.fi \fR +.P +.RE +.RE +.IP 13. 4 +Add up the first column, print sum, and average: +.RS 4 +.sp +.RS 4 +.nf +\fB + {s += $1 } +END {print "sum is ", s, " average is", s/NR} +.fi \fR +.P +.RE +.RE +.IP 14. 4 +Write fields in reverse order, one per line (many lines out for each +line in): +.RS 4 +.sp +.RS 4 +.nf +\fB +{ for (i = NF; i > 0; \(mi\|\(mii) print $i } +.fi \fR +.P +.RE +.RE +.IP 15. 4 +Write all lines between occurrences of the strings +.BR start +and +.BR stop : +.RS 4 +.sp +.RS 4 +.nf +\fB +/start/, /stop/ +.fi \fR +.P +.RE +.RE +.IP 16. 4 +Write all lines whose first field is different from the previous one: +.RS 4 +.sp +.RS 4 +.nf +\fB +$1 != prev { print; prev = $1 } +.fi \fR +.P +.RE +.RE +.IP 17. 4 +Simulate +.IR echo : +.RS 4 +.sp +.RS 4 +.nf +\fB +BEGIN { + for (i = 1; i < ARGC; ++i) + printf("%s%s", ARGV[i], i==ARGC\(mi1?"\en":" ") +} +.fi \fR +.P +.RE +.RE +.IP 18. 4 +Write the path prefixes contained in the +.IR PATH +environment variable, one per line: +.RS 4 +.sp +.RS 4 +.nf +\fB +BEGIN { + n = split (ENVIRON["PATH"], path, ":") + for (i = 1; i <= n; ++i) + print path[i] +} +.fi \fR +.P +.RE +.RE +.IP 19. 4 +If there is a file named +.BR input +containing page headers of the form: +Page # +.RS 4 +.P +and a file named +.BR program +that contains: +.sp +.RS 4 +.nf +\fB +/Page/ { $2 = n++; } + { print } +.fi \fR +.P +.RE +then the command line: +.sp +.RS 4 +.nf +\fB +awk \(mif program n=5 input +.fi \fR +.P +.RE +.P +prints the file +.BR input , +filling in page numbers starting at 5. +.RE +.SH RATIONALE +This description is based on the new +.IR awk , +``nawk'', (see the referenced \fIThe AWK Programming Language\fP), which introduced a number of new features to +the historical +.IR awk : +.IP " 1." 4 +New keywords: +.BR delete , +.BR do , +.BR function , +.BR return +.IP " 2." 4 +New built-in functions: +.BR atan2 , +.BR close , +.BR cos , +.BR gsub , +.BR match , +.BR rand , +.BR sin , +.BR srand , +.BR sub , +.BR system +.IP " 3." 4 +New predefined variables: +.BR FNR , +.BR ARGC , +.BR ARGV , +.BR RSTART , +.BR RLENGTH , +.BR SUBSEP +.IP " 4." 4 +New expression operators: +.BR ? , +.BR : , +.BR , , +.BR ^ +.IP " 5." 4 +The +.BR FS +variable and the third argument to +.BR split , +now treated as extended regular expressions. +.IP " 6." 4 +The operator precedence, changed to more closely match the C language. +Two examples of code that operate differently are: +.RS 4 +.sp +.RS 4 +.nf +\fB +while ( n /= 10 > 1) ... +if (!"wk" ~ /bwk/) ... +.fi \fR +.P +.RE +.RE +.P +Several features have been added based on newer implementations of +.IR awk : +.IP " *" 4 +Multiple instances of +.BR \(mif +.IR progfile +are permitted. +.IP " *" 4 +The new option +.BR \(miv +.IR assignment. +.IP " *" 4 +The new predefined variable +.BR ENVIRON . +.IP " *" 4 +New built-in functions +.BR toupper +and +.BR tolower . +.IP " *" 4 +More formatting capabilities are added to +.BR printf +to match the ISO\ C standard. +.P +The overall +.IR awk +syntax has always been based on the C language, with a few features +from the shell command language and other sources. Because of this, it +is not completely compatible with any other language, which has caused +confusion for some users. It is not the intent of the standard +developers to address such issues. A few relatively minor changes +toward making the language more compatible with the ISO\ C standard were +made; most of these changes are based on similar changes in recent +implementations, as described above. There remain several C-language +conventions that are not in +.IR awk . +One of the notable ones is the + +operator, which is commonly used to specify multiple expressions in the +C language +.BR for +statement. Also, there are various places where +.IR awk +is more restrictive than the C language regarding the type of +expression that can be used in a given context. These limitations are +due to the different features that the +.IR awk +language does provide. +.P +Regular expressions in +.IR awk +have been extended somewhat from historical implementations to make +them a pure superset of extended regular expressions, as defined by +POSIX.1\(hy2008 (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions"). +The main extensions are internationalization +features and interval expressions. Historical implementations of +.IR awk +have long supported +-escape +sequences as an extension to extended regular expressions, and +this extension has been retained despite inconsistency with other +utilities. The number of escape sequences recognized in both extended +regular expressions and strings has varied (generally increasing with +time) among implementations. The set specified by POSIX.1\(hy2008 includes most +sequences known to be supported by popular implementations and by the +ISO\ C standard. One sequence that is not supported is hexadecimal value escapes +beginning with +.BR '\ex' . +This would allow values expressed in more than 9 bits to be used within +.IR awk +as in the ISO\ C standard. However, because this syntax has a non-deterministic +length, it does not permit the subsequent character to be a hexadecimal +digit. This limitation can be dealt with in the C language by the use +of lexical string concatenation. In the +.IR awk +language, concatenation could also be a solution for strings, but not +for extended regular expressions (either lexical ERE tokens or strings +used dynamically as regular expressions). Because of this limitation, +the feature has not been added to POSIX.1\(hy2008. +.P +When a string variable is used in a context where an extended regular +expression normally appears (where the lexical token ERE is used in the +grammar) the string does not contain the literal + +characters. +.P +Some versions of +.IR awk +allow the form: +.sp +.RS 4 +.nf +\fB +func name(args, ... ) { statements } +.fi \fR +.P +.RE +.P +This has been deprecated by the authors of the language, who asked that +it not be specified. +.P +Historical implementations of +.IR awk +produce an error if a +.BR next +statement is executed in a +.BR BEGIN +action, and cause +.IR awk +to terminate if a +.BR next +statement is executed in an +.BR END +action. This behavior has not been documented, and it was not believed +that it was necessary to standardize it. +.P +The specification of conversions between string and numeric values is +much more detailed than in the documentation of historical +implementations or in the referenced \fIThe AWK Programming Language\fP. Although most of the behavior is +designed to be intuitive, the details are necessary to ensure +compatible behavior from different implementations. This is especially +important in relational expressions since the types of the operands +determine whether a string or numeric comparison is performed. From the +perspective of an application developer, it is usually sufficient to +expect intuitive behavior and to force conversions (by adding zero or +concatenating a null string) when the type of an expression does not +obviously match what is needed. The intent has been to specify +historical practice in almost all cases. The one exception is that, in +historical implementations, variables and constants maintain both +string and numeric values after their original value is converted by +any use. This means that referencing a variable or constant can have +unexpected side-effects. For example, with historical implementations +the following program: +.sp +.RS 4 +.nf +\fB +{ + a = "+2" + b = 2 + if (NR % 2) + c = a + b + if (a == b) + print "numeric comparison" + else + print "string comparison" +} +.fi \fR +.P +.RE +.P +would perform a numeric comparison (and output numeric comparison) for +each odd-numbered line, but perform a string comparison (and output +string comparison) for each even-numbered line. POSIX.1\(hy2008 ensures that +comparisons will be numeric if necessary. With historical +implementations, the following program: +.sp +.RS 4 +.nf +\fB +BEGIN { + OFMT = "%e" + print 3.14 + OFMT = "%f" + print 3.14 +} +.fi \fR +.P +.RE +.P +would output +.BR \(dq3.140000e+00\(dq +twice, because in the second +.BR print +statement the constant +.BR \(dq3.14\(dq +would have a string value from the previous conversion. POSIX.1\(hy2008 requires +that the output of the second +.BR print +statement be +.BR \(dq3.140000\(dq . +The behavior of historical implementations was seen as too unintuitive +and unpredictable. +.P +It was pointed out that with the rules contained in early drafts, the +following script would print nothing: +.sp +.RS 4 +.nf +\fB +BEGIN { + y[1.5] = 1 + OFMT = "%e" + print y[1.5] +} +.fi \fR +.P +.RE +.P +Therefore, a new variable, +.BR CONVFMT , +was introduced. The +.BR OFMT +variable is now restricted to affecting output conversions of numbers +to strings and +.BR CONVFMT +is used for internal conversions, such as comparisons or array +indexing. The default value is the same as that for +.BR OFMT , +so unless a program changes +.BR CONVFMT +(which no historical program would do), it will receive the historical +behavior associated with internal string conversions. +.P +The POSIX +.IR awk +lexical and syntactic conventions are specified more formally than in +other sources. Again the intent has been to specify historical +practice. One convention that may not be obvious from the formal +grammar as in other verbal descriptions is where + +characters are acceptable. There are several obvious placements such as +terminating a statement, and a + +can be used to escape + +characters between any lexical tokens. In addition, + +characters without + +characters can follow a comma, an open brace, a logical AND operator (\c +.BR \(dq&&\(dq ), +a logical OR operator (\c +.BR \(dq||\(dq ), +the +.BR do +keyword, the +.BR else +keyword, and the closing parenthesis of an +.BR if , +.BR for , +or +.BR while +statement. For example: +.sp +.RS 4 +.nf +\fB +{ print $1, + $2 } +.fi \fR +.P +.RE +.P +The requirement that +.IR awk +add a trailing + +to the program argument text is to simplify the grammar, making it +match a text file in form. There is no way for an application or test +suite to determine whether a literal + +is added or whether +.IR awk +simply acts as if it did. +.P +POSIX.1\(hy2008 requires several changes from historical implementations in order +to support internationalization. Probably the most subtle of these is +the use of the decimal-point character, defined by the +.IR LC_NUMERIC +category of the locale, in representations of floating-point numbers. +This locale-specific character is used in recognizing numeric input, in +converting between strings and numeric values, and in formatting +output. However, regardless of locale, the + +character (the decimal-point character of the POSIX locale) is the +decimal-point character recognized in processing +.IR awk +programs (including assignments in command line arguments). This is +essentially the same convention as the one used in the ISO\ C standard. The +difference is that the C language includes the +\fIsetlocale\fR() +function, which permits an application to modify its locale. Because of +this capability, a C application begins executing with its locale set +to the C locale, and only executes in the environment-specified locale +after an explicit call to +\fIsetlocale\fR(). +However, adding such an elaborate new feature to the +.IR awk +language was seen as inappropriate for POSIX.1\(hy2008. It is possible to execute +an +.IR awk +program explicitly in any desired locale by setting the environment in +the shell. +.P +The undefined behavior resulting from NULs in extended regular +expressions allows future extensions for the GNU +.IR gawk +program to process binary data. +.P +The behavior in the case of invalid +.IR awk +programs (including lexical, syntactic, and semantic errors) is +undefined because it was considered overly limiting on implementations +to specify. In most cases such errors can be expected to produce a +diagnostic and a non-zero exit status. However, some implementations +may choose to extend the language in ways that make use of certain +invalid constructs. Other invalid constructs might be deemed worthy of +a warning, but otherwise cause some reasonable behavior. Still other +constructs may be very difficult to detect in some implementations. +Also, different implementations might detect a given error during an +initial parsing of the program (before reading any input files) while +others might detect it when executing the program after reading some +input. Implementors should be aware that diagnosing errors as early as +possible and producing useful diagnostics can ease debugging of +applications, and thus make an implementation more usable. +.P +The unspecified behavior from using multi-character +.BR RS +values is to allow possible future extensions based on extended regular +expressions used for record separators. Historical implementations take +the first character of the string and ignore the others. +.P +Unspecified behavior when +.IR split (\c +.IR string ,\c +.IR array ,\c +) +is used is to allow a proposed future extension that would split up a +string into an array of individual characters. +.P +In the context of the +.BR getline +function, equally good arguments for different precedences of the +.BR | +and +.BR < +operators can be made. Historical practice has been that: +.sp +.RS 4 +.nf +\fB +getline < "a" "b" +.fi \fR +.P +.RE +.P +is parsed as: +.sp +.RS 4 +.nf +\fB +( getline < "a" ) "b" +.fi \fR +.P +.RE +.P +although many would argue that the intent was that the file +.BR ab +should be read. However: +.sp +.RS 4 +.nf +\fB +getline < "x" + 1 +.fi \fR +.P +.RE +.P +parses as: +.sp +.RS 4 +.nf +\fB +getline < ( "x" + 1 ) +.fi \fR +.P +.RE +.P +Similar problems occur with the +.BR | +version of +.BR getline , +particularly in combination with +.BR $ . +For example: +.sp +.RS 4 +.nf +\fB +$"echo hi" | getline +.fi \fR +.P +.RE +.P +(This situation is particularly problematic when used in a +.BR print +statement, where the +.BR |getline +part might be a redirection of the +.BR print .) +.P +Since in most cases such constructs are not (or at least should not) be +used (because they have a natural ambiguity for which there is no +conventional parsing), the meaning of these constructs has been made +explicitly unspecified. (The effect is that a conforming application that +runs into the problem must parenthesize to resolve the ambiguity.) +There appeared to be few if any actual uses of such constructs. +.P +Grammars can be written that would cause an error under these +circumstances. Where backwards-compatibility is not a large +consideration, implementors may wish to use such grammars. +.P +Some historical implementations have allowed some built-in functions to +be called without an argument list, the result being a default argument +list chosen in some ``reasonable'' way. Use of +.BR length +as a synonym for +.BR "length($0)" +is the only one of these forms that is thought to be widely known or +widely used; this particular form is documented in various places (for +example, most historical +.IR awk +reference pages, although not in the referenced \fIThe AWK Programming Language\fP) as legitimate practice. +With this exception, default argument lists have always been +undocumented and vaguely defined, and it is not at all clear how (or +if) they should be generalized to user-defined functions. They add no +useful functionality and preclude possible future extensions that might +need to name functions without calling them. Not standardizing them +seems the simplest course. The standard developers considered that +.BR length +merited special treatment, however, since it has been documented in the +past and sees possibly substantial use in historical programs. +Accordingly, this usage has been made legitimate, but Issue\ 5 +removed the obsolescent marking for XSI-conforming implementations +and many otherwise conforming applications depend on this feature. +.P +In +.BR sub +and +.BR gsub , +if +.IR repl +is a string literal (the lexical token +.BR STRING ), +then two consecutive + +characters should be used in the string to ensure a single + +will precede the + +when the resultant string is passed to the function. (For example, +to specify one literal + +in the replacement string, use +.BR gsub (\c +.BR ERE , +.BR \(dq\e\e&\(dq ).) +.P +Historically, the only special character in the +.IR repl +argument of +.BR sub +and +.BR gsub +string functions was the + +(\c +.BR '&' ) +character and preceding it with the + +character was used to turn off its special meaning. +.P +The description in the ISO\ POSIX\(hy2:\|1993 standard introduced behavior such that the + +character was another special character and it was unspecified whether +there were any other special characters. This description introduced +several portability problems, some of which are described below, and so +it has been replaced with the more historical description. Some of the +problems include: +.IP " *" 4 +Historically, to create the replacement string, a script could use +.BR gsub (\c +.BR ERE , +.BR \(dq\e\e&\(dq ), +but with the ISO\ POSIX\(hy2:\|1993 standard wording, it was necessary to use +.BR gsub (\c +.BR ERE , +.BR \(dq\e\e\e\e&\(dq ). +The + +characters are doubled here because all string literals are subject to +lexical analysis, which would reduce each pair of + +characters to a single + +before being passed to +.BR gsub . +.IP " *" 4 +Since it was unspecified what the special characters were, for portable +scripts to guarantee that characters are printed literally, each +character had to be preceded with a +. +(For example, a portable script had to use +.BR gsub (\c +.BR ERE , +.BR \(dq\e\eh\e\ei\(dq ) +to produce a replacement string of +.BR \(dqhi\(dq .) +.P +The description for comparisons in the ISO\ POSIX\(hy2:\|1993 standard did not properly describe +historical practice because of the way numeric strings are compared as +numbers. The current rules cause the following code: +.sp +.RS 4 +.nf +\fB +if (0 == "000") + print "strange, but true" +else + print "not true" +.fi \fR +.P +.RE +.P +to do a numeric comparison, causing the +.BR if +to succeed. It should be intuitively obvious that this is incorrect +behavior, and indeed, no historical implementation of +.IR awk +actually behaves this way. +.P +To fix this problem, the definition of +.IR "numeric string" +was enhanced to include only those values obtained from specific +circumstances (mostly external sources) where it is not possible to +determine unambiguously whether the value is intended to be a string or +a numeric. +.P +Variables that are assigned to a numeric string shall also be treated +as a numeric string. (For example, the notion of a numeric string can +be propagated across assignments.) In comparisons, all variables having +the uninitialized value are to be treated as a numeric operand +evaluating to the numeric value zero. +.P +Uninitialized variables include all types of variables including +scalars, array elements, and fields. The definition of an uninitialized +value in +.IR "Variables and Special Variables" +is necessary to describe the value placed on uninitialized variables +and on fields that are valid (for example, +.BR < +.BR $NF ) +but have no characters in them and to describe how these variables are +to be used in comparisons. A valid field, such as +.BR $1 , +that has no characters in it can be obtained from an input line of +.BR \(dq\et\et\(dq +when +.BR FS= \c +.BR '\et' . +Historically, the comparison (\c +.BR $1< 10) +was done numerically after evaluating +.BR $1 +to the value zero. +.P +The phrase ``.\|.\|. also shall have the numeric value of the numeric +string'' was removed from several sections of the ISO\ POSIX\(hy2:\|1993 standard because is +specifies an unnecessary implementation detail. It is not necessary for +POSIX.1\(hy2008 to specify that these objects be assigned two different values. +It is only necessary to specify that these objects may evaluate to two +different values depending on context. +.P +Historical implementations of +.IR awk +did not parse hexadecimal integer or floating constants like +.BR \(dq0xa\(dq +and +.BR \(dq0xap0\(dq . +Due to an oversight, the 2001 through 2004 editions of this standard +required support for hexadecimal floating constants. This was due to +the reference to +\fIatof\fR(). +This version of the standard allows but does not require implementations +to use +\fIatof\fR() +and includes a description of how floating-point numbers are recognized +as an alternative to match historic behavior. The intent of this change +is to allow implementations to recognize floating-point constants +according to either the ISO/IEC\ 9899:\|1990 standard or ISO/IEC\ 9899:\|1999 standard, and to allow (but not require) +implementations to recognize hexadecimal integer constants. +.P +Historical implementations of +.IR awk +did not support floating-point infinities and NaNs in +.IR "numeric strings" ; +e.g., +.BR \(dq\(miINF\(dq +and +.BR \(dqNaN\(dq . +However, implementations that use the +\fIatof\fR() +or +\fIstrtod\fR() +functions to do the conversion picked up support for these values if they +used a ISO/IEC\ 9899:\|1999 standard version of the function instead of a ISO/IEC\ 9899:\|1990 standard version. Due to +an oversight, the 2001 through 2004 editions of this standard did not +allow support for infinities and NaNs, but in this revision support is +allowed (but not required). This is a silent change to the behavior of +.IR awk +programs; for example, in the POSIX locale the expression: +.sp +.RS 4 +.nf +\fB +("-INF" + 0 < 0) +.fi \fR +.P +.RE +.P +formerly had the value 0 because +.BR \(dq\(miINF\(dq +converted to 0, but now it may have the value 0 or 1. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.3" ", " "Grammar Conventions", +.IR "\fIgrep\fR\^", +.IR "\fIlex\fR\^", +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 9" ", " "Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIatof\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/basename.1p b/man-pages-posix-2013-a/man1p/basename.1p new file mode 100644 index 0000000..d5153f7 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/basename.1p @@ -0,0 +1,288 @@ +'\" et +.TH BASENAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +basename +\(em return non-directory portion of a pathname +.SH SYNOPSIS +.LP +.nf +basename \fIstring \fB[\fIsuffix\fB]\fR +.fi +.SH DESCRIPTION +The +.IR string +operand shall be treated as a pathname, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname". +The string +.IR string +shall be converted to the filename corresponding to the last pathname +component in +.IR string +and then the suffix string +.IR suffix , +if present, shall be removed. This shall be done by performing actions +equivalent to the following steps in order: +.IP " 1." 4 +If +.IR string +is a null string, it is unspecified whether the resulting string is +.BR '.' +or a null string. In either case, skip steps 2 through 6. +.IP " 2." 4 +If +.IR string +is +.BR \(dq//\(dq , +it is implementation-defined whether steps 3 to 6 are skipped or +processed. +.IP " 3." 4 +If +.IR string +consists entirely of + +characters, +.IR string +shall be set to a single + +character. In this case, skip steps 4 to 6. +.IP " 4." 4 +If there are any trailing + +characters in +.IR string , +they shall be removed. +.IP " 5." 4 +If there are any + +characters remaining in +.IR string , +the prefix of +.IR string +up to and including the last + +character in +.IR string +shall be removed. +.IP " 6." 4 +If the +.IR suffix +operand is present, is not identical to the characters remaining in +.IR string , +and is identical to a suffix of the characters remaining in +.IR string , +the suffix +.IR suffix +shall be removed from +.IR string . +Otherwise, +.IR string +is not modified by this step. It shall not be considered an error if +.IR suffix +is not found in +.IR string . +.P +The resulting string shall be written to standard output. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIstring\fR" 10 +A string. +.IP "\fIsuffix\fR" 10 +A string. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR basename : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR basename +utility shall write a line to the standard output in the following +format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIresulting string\fP> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The definition of +.IR pathname +specifies implementation-defined behavior for pathnames starting with +two + +characters. Therefore, applications shall not arbitrarily add + +characters to the beginning of a pathname unless they can ensure +that there are more or less than two or are prepared to deal with the +implementation-defined consequences. +.SH EXAMPLES +If the string +.IR string +is a valid pathname: +.sp +.RS 4 +.nf +\fB +$(basename -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +produces a filename that could be used to open the file named by +.IR string +in the directory returned by: +.sp +.RS 4 +.nf +\fB +$(dirname -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +If the string +.IR string +is not a valid pathname, the same algorithm is used, but the result +need not be a valid filename. The +.IR basename +utility is not expected to make any judgements about the validity of +.IR string +as a pathname; it just follows the specified algorithm to produce a +result string. +.P +The following shell script compiles +.BR /usr/src/cmd/cat.c +and moves the output to a file named +.BR cat +in the current directory when invoked with the argument +.BR /usr/src/cmd/cat +or with the argument +.BR /usr/src/cmd/cat.c : +.sp +.RS 4 +.nf +\fB +c99 -- "$(dirname -- "$1")/$(basename -- "$1" .c).c" && +mv a.out "$(basename -- "$1" .c)" +.fi \fR +.P +.RE +.SH RATIONALE +The behaviors of +.IR basename +and +.IR dirname +have been coordinated so that when +.IR string +is a valid pathname: +.sp +.RS 4 +.nf +\fB +$(basename -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +would be a valid filename for the file in the directory: +.sp +.RS 4 +.nf +\fB +$(dirname -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +This would not work for the early proposal versions of these utilities due +to the way it specified handling of trailing + +characters. +.P +Since the definition of +.IR pathname +specifies implementation-defined behavior for pathnames starting with +two + +characters, this volume of POSIX.1\(hy2008 specifies similar implementation-defined behavior +for the +.IR basename +and +.IR dirname +utilities. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "\fIdirname\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname", +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/batch.1p b/man-pages-posix-2013-a/man1p/batch.1p new file mode 100644 index 0000000..1cbadf4 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/batch.1p @@ -0,0 +1,275 @@ +'\" et +.TH BATCH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +batch +\(em schedule commands to be executed in a batch queue +.SH SYNOPSIS +.LP +.nf +\fIbatch\fR +.fi +.SH DESCRIPTION +The +.IR batch +utility shall read commands from standard input and schedule them +for execution in a batch queue. It shall be the equivalent of +the command: +.sp +.RS 4 +.nf +\fB +at \(miq b \(mim now +.fi \fR +.P +.RE +.P +where queue +.IR b +is a special +.IR at +queue, specifically for batch jobs. Batch jobs shall be submitted to the +batch queue with no time constraints and shall be run by the system using +algorithms, based on unspecified factors, that may vary with each +invocation of +.IR batch . +.P +Users shall be permitted to use +.IR batch +if their name appears in the file +.BR at.allow +which is located in an implementation-defined directory. +If that file does not exist, the file +.BR at.deny , +which is located in an implementation-defined directory, +shall be checked to determine whether the user shall be denied access to +.IR batch . +If neither file exists, only a process with appropriate privileges +shall be allowed to submit a job. If only +.BR at.deny +exists and is empty, global usage shall be permitted. The +.BR at.allow +and +.BR at.deny +files shall consist of one user name per line. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +The standard input shall be a text file consisting of commands +acceptable to the shell command language described in +.IR "Chapter 2" ", " "Shell Command Language". +.SH "INPUT FILES" +The text files +.BR at.allow +and +.BR at.deny , +which are located in an implementation-defined directory, +shall contain zero or more user names, one per line, of users who are, +respectively, authorized or denied access to the +.IR at +and +.IR batch +utilities. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR batch : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents for date and time strings written by +.IR batch . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fISHELL\fP" 10 +Determine the name of a command interpreter to be used to invoke the +at-job. If the variable is unset or null, +.IR sh +shall be used. If it is set to a value other than a name for +.IR sh , +the implementation shall do one of the following: use that shell; use +.IR sh ; +use the login shell from the user database; any of the preceding +accompanied by a warning diagnostic about which was chosen. +.IP "\fITZ\fP" 10 +Determine the timezone. The job shall be submitted for execution at the +time specified by +.IR timespec +or +.BR \(mit +.IR time +relative to the timezone specified by the +.IR TZ +variable. If +.IR timespec +specifies a timezone, it overrides +.IR TZ . +If +.IR timespec +does not specify a timezone and +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When standard input is a terminal, prompts of unspecified format for +each line of the user input described in the STDIN section may be +written to standard output. +.SH STDERR +The following shall be written to standard error when a job has been +successfully submitted: +.sp +.RS 4 +.nf +\fB +"job %s at %s\en", \fIat_job_id\fR, <\fIdate\fR> +.fi \fR +.P +.RE +.P +where +.IR date +shall be equivalent in format to the output of: +.sp +.RS 4 +.nf +\fB +date +"%a %b %e %T %Y" +.fi \fR +.P +.RE +.P +The date and time written shall be adjusted so that they appear in the +timezone of the user (as determined by the +.IR TZ +variable). +.P +Neither this, nor warning messages concerning the selection of the +command interpreter, are considered a diagnostic that changes the exit +status. +.P +Diagnostic messages, if any, shall be written to standard error. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The job shall not be scheduled. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +It may be useful to redirect standard output within the specified +commands. +.SH EXAMPLES +.IP " 1." 4 +This sequence can be used at a terminal: +.RS 4 +.sp +.RS 4 +.nf +\fB +batch +sort < file >outfile +EOT +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +This sequence, which demonstrates redirecting standard error to a pipe, +is useful in a command procedure (the sequence of output redirection +specifications is significant): +.RS 4 +.sp +.RS 4 +.nf +\fB +batch <&1 >outfile | mailx mygroup +! +.fi \fR +.P +.RE +.RE +.SH RATIONALE +Early proposals described +.IR batch +in a manner totally separated from +.IR at , +even though the historical model treated it almost as a synonym for +.IR at +.BR \(miqb . +A number of features were added to list and control batch work +separately from those in +.IR at . +Upon further reflection, it was decided that the benefit of this did +not merit the change to the historical interface. +.P +The +.BR \(mim +option was included on the equivalent +.IR at +command because it is historical practice to mail results to the +submitter, even if all job-produced output is redirected. As explained +in the RATIONALE for +.IR at , +the +.BR now +keyword submits the job for immediate execution (after scheduling +delays), despite some historical systems where +.IR at +.BR now +would have been considered an error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/bc.1p b/man-pages-posix-2013-a/man1p/bc.1p new file mode 100644 index 0000000..a535d59 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/bc.1p @@ -0,0 +1,1615 @@ +'\" et +.TH BC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +bc +\(em arbitrary-precision arithmetic language +.SH SYNOPSIS +.LP +.nf +bc \fB[\fR\(mil\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR bc +utility shall implement an arbitrary precision calculator. It shall +take input from any files given, then read from the standard input. If +the standard input and standard output to +.IR bc +are attached to a terminal, the invocation of +.IR bc +shall be considered to be +.IR interactive , +causing behavioral constraints described in the following sections. +.SH OPTIONS +The +.IR bc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mil\fP" 10 +(The letter ell.) Define the math functions and initialize +.IR scale +to 20, instead of the default zero; see the EXTENDED DESCRIPTION +section. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file containing +.IR bc +program statements. After all +.IR file s +have been read, +.IR bc +shall read the standard input. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Input files shall be text files containing a sequence of comments, +statements, and function definitions that shall be executed as they are +read. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR bc : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The output of the +.IR bc +utility shall be controlled by the program read, and consist of zero or +more lines containing the value of all executed expressions without +assignments. The radix and precision of the output shall be controlled +by the values of the +.BR obase +and +.BR scale +variables; see the EXTENDED DESCRIPTION section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +.SS "Grammar" +.P +The grammar in this section and the lexical conventions in the +following section shall together describe the syntax for +.IR bc +programs. The general conventions for this style of grammar are +described in +.IR "Section 1.3" ", " "Grammar Conventions". +A valid program can be represented as the non-terminal symbol +.BR program +in the grammar. This formal syntax shall take precedence over the +text syntax description. +.sp +.RS 4 +.nf +\fB +%token EOF NEWLINE STRING LETTER NUMBER +.P +%token MUL_OP +/* '*', '/', '%' */ +.P +%token ASSIGN_OP +/* '=', '+=', '\(mi=', '*=', '/=', '%=', '^=' */ +.P +%token REL_OP +/* '==', '<=', '>=', '!=', '<', '>' */ +.P +%token INCR_DECR +/* '++', '\(mi\|\(mi' */ +.P +%token Define Break Quit Length +/* 'define', 'break', 'quit', 'length' */ +.P +%token Return For If While Sqrt +/* 'return', 'for', 'if', 'while', 'sqrt' */ +.P +%token Scale Ibase Obase Auto +/* 'scale', 'ibase', 'obase', 'auto' */ +.P +%start program +.P +%% +.P +program : EOF + | input_item program + ; +.P +input_item : semicolon_list NEWLINE + | function + ; +.P +semicolon_list : /* empty */ + | statement + | semicolon_list ';' statement + | semicolon_list ';' + ; +.P +statement_list : /* empty */ + | statement + | statement_list NEWLINE + | statement_list NEWLINE statement + | statement_list ';' + | statement_list ';' statement + ; +.P +statement : expression + | STRING + | Break + | Quit + | Return + | Return '(' return_expression ')' + | For '(' expression ';' + relational_expression ';' + expression ')' statement + | If '(' relational_expression ')' statement + | While '(' relational_expression ')' statement + | '{' statement_list '}' + ; +.P +function : Define LETTER '(' opt_parameter_list ')' + '{' NEWLINE opt_auto_define_list + statement_list '}' + ; +.P +opt_parameter_list : /* empty */ + | parameter_list + ; +.P +parameter_list : LETTER + | define_list ',' LETTER + ; +.P +opt_auto_define_list : /* empty */ + | Auto define_list NEWLINE + | Auto define_list ';' + ; +.P +define_list : LETTER + | LETTER '[' ']' + | define_list ',' LETTER + | define_list ',' LETTER '[' ']' + ; +.P +opt_argument_list : /* empty */ + | argument_list + ; +.P +argument_list : expression + | LETTER '[' ']' ',' argument_list + ; +.P +relational_expression : expression + | expression REL_OP expression + ; +.P +return_expression : /* empty */ + | expression + ; +.P +expression : named_expression + | NUMBER + | '(' expression ')' + | LETTER '(' opt_argument_list ')' + | '\(mi' expression + | expression '+' expression + | expression '\(mi' expression + | expression MUL_OP expression + | expression '^' expression + | INCR_DECR named_expression + | named_expression INCR_DECR + | named_expression ASSIGN_OP expression + | Length '(' expression ')' + | Sqrt '(' expression ')' + | Scale '(' expression ')' + ; +.P +named_expression : LETTER + | LETTER '[' expression ']' + | Scale + | Ibase + | Obase + ; +.fi \fR +.P +.RE +.SS "Lexical Conventions in bc" +.P +The lexical conventions for +.IR bc +programs, with respect to the preceding grammar, shall be as follows: +.IP " 1." 4 +Except as noted, +.IR bc +shall recognize the longest possible token or delimiter beginning at a +given point. +.IP " 2." 4 +A comment shall consist of any characters beginning with the two adjacent +characters +.BR \(dq/*\(dq +and terminated by the next occurrence of the two adjacent characters +.BR \(dq*/\(dq . +Comments shall have no effect except to delimit lexical tokens. +.IP " 3." 4 +The + +shall be recognized as the token +.BR NEWLINE . +.IP " 4." 4 +The token +.BR STRING +shall represent a string constant; it shall consist of any characters +beginning with the double-quote character (\c +.BR '\&"' ) +and terminated by another occurrence of the double-quote character. The +value of the string is the sequence of all characters between, but not +including, the two double-quote characters. All characters shall be +taken literally from the input, and there is no way to specify a string +containing a double-quote character. The length of the value of each +string shall be limited to +{BC_STRING_MAX} +bytes. +.IP " 5." 4 +A + +shall have no effect except as an ordinary character if it appears +within a +.BR STRING +token, or to delimit a lexical token other than +.BR STRING . +.IP " 6." 4 +The combination of a + +character immediately followed by a + +shall have no effect other than to delimit lexical tokens with the +following exceptions: +.RS 4 +.IP " *" 4 +It shall be interpreted as the character sequence +.BR \(dq\e\(dq +in +.BR STRING +tokens. +.IP " *" 4 +It shall be ignored as part of a multi-line +.BR NUMBER +token. +.RE +.IP " 7." 4 +The token +.BR NUMBER +shall represent a numeric constant. It shall be recognized by the +following grammar: +.RS 4 +.sp +.RS 4 +.nf +\fB +NUMBER : integer + | '.' integer + | integer '.' + | integer '.' integer + ; +.P +integer : digit + | integer digit + ; +.P +digit : 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 + | 8 | 9 | A | B | C | D | E | F + ; +.fi \fR +.P +.RE +.RE +.IP " 8." 4 +The value of a +.BR NUMBER +token shall be interpreted as a numeral in the base specified by the +value of the internal register +.BR ibase +(described below). Each of the +.BR digit +characters shall have the value from 0 to 15 in the order listed here, +and the + +character shall represent the radix point. The behavior is undefined if +digits greater than or equal to the value of +.BR ibase +appear in the token. However, note the exception for single-digit +values being assigned to +.BR ibase +and +.BR obase +themselves, in +.IR "Operations in bc". +.IP " 9." 4 +The following keywords shall be recognized as tokens: +.TS +tab(@); +lBw(0.6i)e lBe lBe lBe lBe. +T{ +.nf +auto +break +define +T}@T{ +.nf +ibase +if +for +T}@T{ +.nf +length +obase +quit +T}@T{ +.nf +return +scale +sqrt +T}@T{ +.nf +while +.fi +T} +.TE +.IP 10. 4 +Any of the following characters occurring anywhere except within a +keyword shall be recognized as the token +.BR LETTER : +.RS 4 +.sp +.RS 4 +.nf +\fB +a b c d e f g h i j k l m n o p q r s t u v w x y z +.fi \fR +.P +.RE +.RE +.IP 11. 4 +The following single-character and two-character sequences shall be +recognized as the token +.BR ASSIGN_OP : +.RS 4 +.sp +.RS 4 +.nf +\fB += += \(mi= *= /= %= ^= +.fi \fR +.P +.RE +.RE +.IP 12. 4 +If an +.BR '=' +character, as the beginning of a token, is followed by a +.BR '\(mi' +character with no intervening delimiter, the behavior is undefined. +.IP 13. 4 +The following single-characters shall be recognized as the token +.BR MUL_OP : +.RS 4 +.sp +.RS 4 +.nf +\fB +* / % +.fi \fR +.P +.RE +.RE +.IP 14. 4 +The following single-character and two-character sequences shall be +recognized as the token +.BR REL_OP : +.RS 4 +.sp +.RS 4 +.nf +\fB +== <= >= != < > +.fi \fR +.P +.RE +.RE +.IP 15. 4 +The following two-character sequences shall be recognized as the token +.BR INCR_DECR : +.RS 4 +.sp +.RS 4 +.nf +\fB +++ \(mi\|\(mi +.fi \fR +.P +.RE +.RE +.IP 16. 4 +The following single characters shall be recognized as tokens whose +names are the character: +.RS 4 +.sp +.RS 4 +.nf +\fB + ( ) , + \(mi ; [ ] ^ { } +.fi \fR +.P +.RE +.RE +.IP 17. 4 +The token +.BR EOF +is returned when the end of input is reached. +.SS "Operations in bc" +.P +There are three kinds of identifiers: ordinary identifiers, array +identifiers, and function identifiers. +All three types consist of single lowercase letters. Array identifiers +shall be followed by square brackets (\c +.BR \(dq[]\(dq ). +An array subscript is required except in an argument or auto list. +Arrays are singly dimensioned and can contain up to +{BC_DIM_MAX} +elements. Indexing shall begin at zero so an array is indexed from 0 to +{BC_DIM_MAX}\(mi1. +Subscripts shall be truncated to integers. The application shall ensure +that function identifiers are followed by parentheses, possibly +enclosing arguments. The three types of identifiers do not conflict. +.P +The following table summarizes the rules for precedence and +associativity of all operators. Operators on the same line shall have +the same precedence; rows are in order of decreasing precedence. +.sp +.ce 1 +\fBTable: Operators in \fIbc\fP\fR +.TS +center tab(@) box; +cB | cB +lf5 | l. +Operator@Associativity +_ +++, \(mi\|\(mi@N/A +unary \(mi@N/A +\&^@Right to left +*, /, %@Left to right ++, binary \(mi@Left to right +=, +=, \(mi=, *=, /=, %=, ^=@Right to left +==, <=, >=, !=, <, >@None +.TE +.P +Each expression or named expression has a +.IR scale , +which is the number of decimal digits that shall be maintained as the +fractional portion of the expression. +.P +.IR "Named expressions" +are places where values are stored. Named expressions shall be valid on +the left side of an assignment. The value of a named expression shall +be the value stored in the place named. Simple identifiers and array +elements are named expressions; they have an initial value of zero and +an initial scale of zero. +.P +The internal registers +.BR scale , +.BR ibase , +and +.BR obase +are all named expressions. The scale of an expression consisting of the +name of one of these registers shall be zero; values assigned to any of +these registers are truncated to integers. The +.BR scale +register shall contain a global value used in computing the scale of +expressions (as described below). The value of the register +.BR scale +is limited to 0 \(<= +.BR scale +\(<= +{BC_SCALE_MAX} +and shall have a default value of zero. The +.BR ibase +and +.BR obase +registers are the input and output number radix, respectively. The +value of +.BR ibase +shall be limited to: +.sp +.RS 4 +.nf +\fB +2 \(<= ibase \(<= 16 +.fi \fR +.P +.RE +.P +The value of +.BR obase +shall be limited to: +.sp +.RS 4 +.nf +\fB +2 \(<= obase \(<= {BC_BASE_MAX} +.fi \fR +.P +.RE +.P +When either +.BR ibase +or +.BR obase +is assigned a single +.BR digit +value from the list in +.IR "Lexical Conventions in bc", +the value shall be assumed in hexadecimal. (For example, +.BR ibase =A +sets to base ten, regardless of the current +.BR ibase +value.) Otherwise, the behavior is undefined when digits greater than +or equal to the value of +.BR ibase +appear in the input. Both +.BR ibase +and +.BR obase +shall have initial values of 10. +.P +Internal computations shall be conducted as if in decimal, regardless +of the input and output bases, to the specified number of decimal +digits. When an exact result is not achieved (for example, +.BR scale "=0;\ 3.2/1)", +the result shall be truncated. +.P +For all values of +.BR obase +specified by this volume of POSIX.1\(hy2008, +.IR bc +shall output numeric values by performing each of the following steps +in order: +.IP " 1." 4 +If the value is less than zero, a + +(\c +.BR '\(mi' ) +character shall be output. +.IP " 2." 4 +One of the following is output, depending on the numerical value: +.RS 4 +.IP " *" 4 +If the absolute value of the numerical value is greater than or equal +to one, the integer portion of the value shall be output as a series of +digits appropriate to +.BR obase +(as described below), most significant digit first. The most significant +non-zero digit shall be output next, followed by each successively +less significant digit. +.IP " *" 4 +If the absolute value of the numerical value is less than one but +greater than zero and the scale of the numerical value is greater than +zero, it is unspecified whether the character 0 is output. +.IP " *" 4 +If the numerical value is zero, the character 0 shall be output. +.RE +.IP " 3." 4 +If the scale of the value is greater than zero and the numeric value +is not zero, a + +character shall be output, followed by a series of digits appropriate to +.BR obase +(as described below) representing the most significant portion of the +fractional part of the value. If +.IR s +represents the scale of the value being output, the number of digits +output shall be +.IR s +if +.BR obase +is 10, less than or equal to +.IR s +if +.BR obase +is greater than 10, or greater than or equal to +.IR s +if +.BR obase +is less than 10. For +.BR obase +values other than 10, this should be the number of digits needed to +represent a precision of 10\u\s-3\fIs\fP\s+3\d. +.P +For +.BR obase +values from 2 to 16, valid digits are the first +.BR obase +of the single characters: +.sp +.RS 4 +.nf +\fB +0 1 2 3 4 5 6 7 8 9 A B C D E F +.fi \fR +.P +.RE +.P +which represent the values zero to 15, inclusive, respectively. +.P +For bases greater than 16, each digit shall be written as a separate +multi-digit decimal number. Each digit except the most significant +fractional digit shall be preceded by a single +. +For bases from 17 to 100, +.IR bc +shall write two-digit decimal numbers; for bases from 101 to 1\|000, +three-digit decimal strings, and so on. For example, the decimal number +1\|024 in base 25 would be written as: +.sp +.RS 4 +.nf +\fB + 01 15 24 +.fi \fR +.P +.RE +.P +and in base 125, as: +.sp +.RS 4 +.nf +\fB + 008 024 +.fi \fR +.P +.RE +.P +Very large numbers shall be split across lines with 70 characters per +line in the POSIX locale; other locales may split at different +character boundaries. Lines that are continued shall end with a +. +.P +A function call shall consist of a function name followed by +parentheses containing a +-separated +list of expressions, which are the function arguments. A whole array +passed as an argument shall be specified by the array name followed +by empty square brackets. All function arguments shall be passed by +value. As a result, changes made to the formal parameters shall have no +effect on the actual arguments. If the function terminates by executing a +.BR return +statement, the value of the function shall be the value of the +expression in the parentheses of the +.BR return +statement or shall be zero if no expression is provided or if there is +no +.BR return +statement. +.P +The result of +.BR sqrt (\c +.IR expression ) +shall be the square root of the expression. The result shall be +truncated in the least significant decimal place. The scale of the +result shall be the scale of the expression or the value of +.BR scale , +whichever is larger. +.P +The result of +.BR length (\c +.IR expression ) +shall be the total number of significant decimal digits in the +expression. The scale of the result shall be zero. +.P +The result of +.BR scale (\c +.IR expression ) +shall be the scale of the expression. The scale of the result shall be +zero. +.P +A numeric constant shall be an expression. The scale shall be the +number of digits that follow the radix point in the input representing +the constant, or zero if no radix point appears. +.P +The sequence (\ \fIexpression\fP\ ) shall be an expression with the +same value and scale as +.IR expression . +The parentheses can be used to alter the normal precedence. +.P +The semantics of the unary and binary operators are as follows: +.IP "\(mi\fIexpression\fP" 6 +.br +The result shall be the negative of the +.IR expression . +The scale of the result shall be the scale of +.IR expression . +.P +The unary increment and decrement operators shall not modify the scale +of the named expression upon which they operate. The scale of the +result shall be the scale of that named expression. +.IP "++\fInamed-expression\fP" 6 +.br +The named expression shall be incremented by one. The result shall be +the value of the named expression after incrementing. +.IP "\(mi\|\(mi\fInamed-expression\fP" 6 +.br +The named expression shall be decremented by one. The result shall be +the value of the named expression after decrementing. +.IP "\fInamed-expression\fP++" 6 +.br +The named expression shall be incremented by one. The result shall be +the value of the named expression before incrementing. +.IP "\fInamed-expression\fP\(mi\|\(mi" 6 +.br +The named expression shall be decremented by one. The result shall be +the value of the named expression before decrementing. +.P +The exponentiation operator, + +(\c +.BR '^' ), +shall bind right to left. +.IP "\fIexpression\fP^\fIexpression\fP" 6 +.br +The result shall be the first +.IR expression +raised to the power of the second +.IR expression . +If the second expression is not an integer, the behavior is undefined. +If +.IR a +is the scale of the left expression and +.IR b +is the absolute value of the right expression, the scale of the result +shall be: +.RS 6 +.sp +.RS 4 +.nf +\fB +if b >= 0 min(a * b, max(scale, a)) if b < 0 scale +.fi \fR +.P +.RE +.RE +The multiplicative operators (\c +.BR '*' , +.BR '/' , +.BR '%' ) +shall bind left to right. +.IP "\fIexpression\fP*\fIexpression\fP" 6 +.br +The result shall be the product of the two expressions. If +.IR a +and +.IR b +are the scales of the two expressions, then the scale of the result +shall be: +.RS 6 +.sp +.RS 4 +.nf +\fB +min(a+b,max(scale,a,b)) +.fi \fR +.P +.RE +.RE +.IP "\fIexpression\fP/\fIexpression\fP" 6 +.br +The result shall be the quotient of the two expressions. The scale of the +result shall be the value of +.BR scale . +.IP "\fIexpression\fP%\fIexpression\fP" 6 +.br +For expressions +.IR a +and +.IR b , +.IR a %\c +.IR b +shall be evaluated equivalent to the steps: +.RS 6 +.IP " 1." 4 +Compute +.IR a /\c +.IR b +to current scale. +.IP " 2." 4 +Use the result to compute: +.RS 4 +.sp +.RS 4 +.nf +\fB +a \(mi (a / b) * b +.fi \fR +.P +.RE +.P +to scale: +.sp +.RS 4 +.nf +\fB +max(scale + scale(b), scale(a)) +.fi \fR +.P +.RE +.RE +The scale of the result shall be: +.sp +.RS 4 +.nf +\fB +max(scale + scale(b), scale(a)) +.fi \fR +.P +.RE +.P +When +.BR scale +is zero, the +.BR '%' +operator is the mathematical remainder operator. +.RE +.P +The additive operators (\c +.BR '\(pl' , +.BR '\(mi' ) +shall bind left to right. +.IP "\fIexpression\fP+\fIexpression\fP" 6 +.br +The result shall be the sum of the two expressions. The scale of the +result shall be the maximum of the scales of the expressions. +.IP "\fIexpression\fP\(mi\fIexpression\fP" 6 +.br +The result shall be the difference of the two expressions. The scale of +the result shall be the maximum of the scales of the expressions. +.P +The assignment operators (\c +.BR '=' , +.BR \(dq+=\(dq , +.BR \(dq\(mi=\(dq , +.BR \(dq*=\(dq , +.BR \(dq/=\(dq , +.BR \(dq%=\(dq , +.BR \(dq^=\(dq ) +shall bind right to left. +.IP "\fInamed-expression\fP=\fIexpression\fP" 6 +.br +This expression shall result in assigning the value of the expression +on the right to the named expression on the left. The scale of both the +named expression and the result shall be the scale of +.IR expression . +.P +The compound assignment forms: +.sp +.RS 4 +.nf +\fB +\fInamed-expression\fR <\fIoperator\fR>= \fIexpression\fR +.fi \fR +.P +.RE +.P +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +\fInamed-expression\fR=\fInamed-expression\fR <\fIoperator\fR> \fIexpression\fR +.fi \fR +.P +.RE +.P +except that the +.IR named-expression +shall be evaluated only once. +.P +Unlike all other operators, the relational operators (\c +.BR '<' , +.BR '>' , +.BR \(dq<=\(dq , +.BR \(dq>=\(dq , +.BR \(dq==\(dq , +.BR \(dq!=\(dq ) +shall be only valid as the object of an +.BR if , +.BR while , +or inside a +.BR for +statement. +.IP "\fIexpression1\fP<\fIexpression2\fR" 6 +.br +The relation shall be true if the value of +.IR expression1 +is strictly less than the value of +.IR expression2 . +.IP "\fIexpression1\fP>\fIexpression2\fP" 6 +.br +The relation shall be true if the value of +.IR expression1 +is strictly greater than the value of +.IR expression2 . +.IP "\fIexpression1\fP<=\fIexpression2\fR" 6 +.br +The relation shall be true if the value of +.IR expression1 +is less than or equal to the value of +.IR expression2 . +.IP "\fIexpression1\fP>=\fIexpression2\fR" 6 +.br +The relation shall be true if the value of +.IR expression1 +is greater than or equal to the value of +.IR expression2 . +.IP "\fIexpression1\fP=\|=\fIexpression2\fR" 6 +.br +The relation shall be true if the values of +.IR expression1 +and +.IR expression2 +are equal. +.IP "\fIexpression1\fP!=\fIexpression2\fR" 6 +.br +The relation shall be true if the values of +.IR expression1 +and +.IR expression2 +are unequal. +.P +There are only two storage classes in +.IR bc : +global and automatic (local). +Only identifiers that are local to a function need be declared +with the +.BR auto +command. The arguments to a function shall be local to the function. +All other identifiers are assumed to be global and available to all +functions. All identifiers, global and local, have initial values of +zero. Identifiers declared as auto shall be allocated on entry to the +function and released on returning from the function. They therefore do +not retain values between function calls. Auto arrays shall be +specified by the array name followed by empty square brackets. On entry +to a function, the old values of the names that appear as parameters +and as automatic variables shall be pushed onto a stack. Until the +function returns, reference to these names shall refer only to the new +values. +.P +References to any of these names from other functions that are called +from this function also refer to the new value until one of those +functions uses the same name for a local variable. +.P +When a statement is an expression, unless the main operator is an +assignment, execution of the statement shall write the value of the +expression followed by a +. +.P +When a statement is a string, execution of the statement shall write +the value of the string. +.P +Statements separated by + +or + +characters shall be executed sequentially. In an interactive invocation of +.IR bc , +each time a + +is read that satisfies the grammatical production: +.sp +.RS 4 +.nf +\fB +input_item : semicolon_list NEWLINE +.fi \fR +.P +.RE +.P +the sequential list of statements making up the +.BR semicolon_list +shall be executed immediately and any output produced by that execution +shall be written without any delay due to buffering. +.P +In an +.BR if +statement (\c +.BR if (\c +.IR relation ) +.IR statement ), +the +.IR statement +shall be executed if the relation is true. +.P +The +.BR while +statement (\c +.BR while (\c +.IR relation ) +.IR statement ) +implements a loop in which the +.IR relation +is tested; each time the +.IR relation +is true, the +.IR statement +shall be executed and the +.IR relation +retested. When the +.IR relation +is false, execution shall resume after +.IR statement . +.P +A +.BR for +statement(\c +.BR for (\c +.IR expression ; +.IR relation ; +.IR expression ) +.IR statement ) +shall be the same as: +.sp +.RS 4 +.nf +\fB +\fIfirst-expression\fP +while (\fIrelation\fP) { + \fIstatement\fP + \fIlast-expression\fR +} +.fi \fR +.P +.RE +The application shall ensure that all three expressions are present. +.P +The +.BR break +statement shall cause termination of a +.BR for +or +.BR while +statement. +.P +The +.BR auto +statement (\c +.BR auto +.IR identifier +.BR [ ,\c +.IR identifier \c +.BR ] +\&.\|.\|.) shall cause the values of the identifiers to be pushed down. +The identifiers can be ordinary identifiers or array identifiers. Array +identifiers shall be specified by following the array name by empty +square brackets. The application shall ensure that the +.BR auto +statement is the first statement in a function definition. +.P +A +.BR define +statement: +.sp +.RS 4 +.nf +\fB +define \fILETTER\fP ( \fIopt_parameter_list\fP ) { + \fIopt_auto_define_list\fP + \fIstatement_list\fR +} +.fi \fR +.P +.RE +.P +defines a function named +.BR LETTER . +If a function named +.BR LETTER +was previously defined, the +.BR define +statement shall replace the previous definition. The expression: +.sp +.RS 4 +.nf +\fB +LETTER ( \fIopt_argument_list\fR ) +.fi \fR +.P +.RE +.P +shall invoke the function named +.BR LETTER . +The behavior is undefined if the number of arguments in the invocation +does not match the number of parameters in the definition. Functions +shall be defined before they are invoked. A function shall be +considered to be defined within its own body, so recursive calls are +valid. The values of numeric constants within a function shall be +interpreted in the base specified by the value of the +.BR ibase +register when the function is invoked. +.P +The +.BR return +statements (\c +.BR return +and +.BR return (\c +.IR expression )) +shall cause termination of a function, popping of its auto variables, +and specification of the result of the function. The first form shall +be equivalent to +.BR return (0). +The value and scale of the result returned by the function shall be the +value and scale of the expression returned. +.P +The +.BR quit +statement (\c +.BR quit ) +shall stop execution of a +.IR bc +program at the point where the statement occurs in the input, even if +it occurs in a function definition, or in an +.BR if , +.BR for , +or +.BR while +statement. +.P +The following functions shall be defined when the +.BR \(mil +option is specified: +.IP "\fBs\fR(\ \fIexpression\fR\ )" 6 +.br +Sine of argument in radians. +.IP "\fBc\fR(\ \fIexpression\fR\ )" 6 +.br +Cosine of argument in radians. +.IP "\fBa\fR(\ \fIexpression\fR\ )" 6 +.br +Arctangent of argument. +.IP "\fBl\fR(\ \fIexpression\fR\ )" 6 +.br +Natural logarithm of argument. +.IP "\fBe\fR(\ \fIexpression\fR\ )" 6 +.br +Exponential function of argument. +.IP "\fBj\fR(\ \fIexpression\fR,\ \fIexpression\fR\ )" 6 +.br +Bessel function of integer order. +.P +The scale of the result returned by these functions shall be the value +of the +.BR scale +register at the time the function is invoked. The value of the +.BR scale +register after these functions have completed their execution shall be +the same value it had upon invocation. The behavior is undefined if +any of these functions is invoked with an argument outside the domain +of the mathematical function. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP 0 10 +All input files were processed successfully. +.IP "\fIunspecified\fR" 10 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If any +.IR file +operand is specified and the named file cannot be accessed, +.IR bc +shall write a diagnostic message to standard error and terminate +without any further action. +.P +In an interactive invocation of +.IR bc , +the utility should print an error message and recover following any +error in the input. In a non-interactive invocation of +.IR bc , +invalid input causes undefined behavior. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Automatic variables in +.IR bc +do not work in exactly the same way as in either C or PL/1. +.P +For historical reasons, the exit status from +.IR bc +cannot be relied upon to indicate that an error has occurred. +Returning zero after an error is possible. Therefore, +.IR bc +should be used primarily by interactive users (who can react to error +messages) or by application programs that can somehow validate the +answers returned as not including error messages. +.P +The +.IR bc +utility always uses the + +(\c +.BR '.' ) +character to represent a radix point, regardless of any decimal-point +character specified as part of the current locale. In languages like C or +.IR awk , +the + +character is used in program source, so it can be portable and +unambiguous, while the locale-specific character is used in input and +output. Because there is no distinction between source and input in +.IR bc , +this arrangement would not be possible. Using the locale-specific +character in +.IR bc 's +input would introduce ambiguities into the language; consider the +following example in a locale with a + +as the decimal-point character: +.sp +.RS 4 +.nf +\fB +define f(a,b) { + ... +} +\&... +.P +f(1,2,3) +.fi \fR +.P +.RE +.P +Because of such ambiguities, the + +character is used in input. Having input follow different conventions +from output would be confusing in either pipeline usage or interactive +usage, so the + +is also used in output. +.SH EXAMPLES +In the shell, the following assigns an approximation of the first ten +digits of +.BR '\(*p' +to the variable +.IR x : +.sp +.RS 4 +.nf +\fB +x=$(printf "%s\en" 'scale = 10; 104348/33215' | bc) +.fi \fR +.P +.RE +.P +The following +.IR bc +program prints the same approximation of +.BR '\(*p' , +with a label, to standard output: +.sp +.RS 4 +.nf +\fB +scale = 10 +"pi equals " +104348 / 33215 +.fi \fR +.P +.RE +.P +The following defines a function to compute an approximate value of the +exponential function (note that such a function is predefined if the +.BR \(mil +option is specified): +.sp +.RS 4 +.nf +\fB +scale = 20 +define e(x){ + auto a, b, c, i, s + a = 1 + b = 1 + s = 1 + for (i = 1; 1 == 1; i++){ + a = a*x + b = b*i + c = a/b + if (c == 0) { + return(s) + } + s = s+c + } +} +.fi \fR +.P +.RE +.P +The following prints approximate values of the exponential function of +the first ten integers: +.sp +.RS 4 +.nf +\fB +for (i = 1; i <= 10; ++i) { + e(i) +} +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR bc +utility is implemented historically as a front-end processor for +.IR dc ; +.IR dc +was not selected to be part of this volume of POSIX.1\(hy2008 because +.IR bc +was thought to have a more intuitive programmatic interface. Current +implementations that implement +.IR bc +using +.IR dc +are expected to be compliant. +.P +The exit status for error conditions has been left unspecified for +several reasons: +.IP " *" 4 +The +.IR bc +utility is used in both interactive and non-interactive situations. +Different exit codes may be appropriate for the two uses. +.IP " *" 4 +It is unclear when a non-zero exit should be given; divide-by-zero, +undefined functions, and syntax errors are all possibilities. +.IP " *" 4 +It is not clear what utility the exit status has. +.IP " *" 4 +In the 4.3 BSD, System V, and Ninth Edition implementations, +.IR bc +works in conjunction with +.IR dc . +The +.IR dc +utility is the parent, +.IR bc +is the child. This was done to cleanly terminate +.IR bc +if +.IR dc +aborted. +.P +The decision to have +.IR bc +exit upon encountering an inaccessible input file is based on the +belief that +.IR bc +.IR file1 +.IR file2 +is used most often when at least +.IR file1 +contains data/function declarations/initializations. Having +.IR bc +continue with prerequisite files missing is probably not useful. There +is no implication in the CONSEQUENCES OF ERRORS section that +.IR bc +must check all its files for accessibility before opening any of them. +.P +There was considerable debate on the appropriateness of the language +accepted by +.IR bc . +Several reviewers preferred to see either a pure subset of the C +language or some changes to make the language more compatible with C. +While the +.IR bc +language has some obvious similarities to C, it has never claimed to be +compatible with any version of C. An interpreter for a subset of C +might be a very worthwhile utility, and it could potentially make +.IR bc +obsolete. However, no such utility is known in historical practice, and +it was not within the scope of this volume of POSIX.1\(hy2008 to define such a language and +utility. If and when they are defined, it may be appropriate to include +them in a future version of this standard. This left the following +alternatives: +.IP " 1." 4 +Exclude any calculator language from this volume of POSIX.1\(hy2008. +.RS 4 +.P +The consensus of the standard developers was that a simple programmatic +calculator language is very useful for both applications and +interactive users. The only arguments for excluding any calculator were +that it would become obsolete if and when a C-compatible one emerged, +or that the absence would encourage the development of such a +C-compatible one. These arguments did not sufficiently address the +needs of current application developers. +.RE +.IP " 2." 4 +Standardize the historical +.IR dc , +possibly with minor modifications. +.RS 4 +.P +The consensus of the standard developers was that +.IR dc +is a fundamentally less usable language and that that would be far too +severe a penalty for avoiding the issue of being similar to but +incompatible with C. +.RE +.IP " 3." 4 +Standardize the historical +.IR bc , +possibly with minor modifications. +.RS 4 +.P +This was the approach taken. Most of the proponents of changing the +language would not have been satisfied until most or all of the +incompatibilities with C were resolved. Since most of the changes +considered most desirable would break historical applications and +require significant modification to historical implementations, almost +no modifications were made. The one significant modification that was +made was the replacement of the historical +.IR bc +assignment operators +.BR \(dq=+\(dq , +and so on, with the more modern +.BR \(dq+=\(dq , +and so on. The older versions are considered to be fundamentally flawed +because of the lexical ambiguity in uses like +.IR a =\(mi1. +.P +In order to permit implementations to deal with backwards-compatibility +as they see fit, the behavior of this one ambiguous construct was made +undefined. (At least three implementations have been known to support +this change already, so the degree of change involved should not be +great.) +.RE +.P +The +.BR '%' +operator is the mathematical remainder operator when +.BR scale +is zero. The behavior of this operator for other values of +.BR scale +is from historical implementations of +.IR bc , +and has been maintained for the sake of historical applications despite +its non-intuitive nature. +.P +Historical implementations permit setting +.BR ibase +and +.BR obase +to a broader range of values. This includes values less than 2, which +were not seen as sufficiently useful to standardize. These +implementations do not interpret input properly for values of +.BR ibase +that are greater than 16. This is because numeric constants are +recognized syntactically, rather than lexically, as described in +\&this volume of POSIX.1\(hy2008. They are built from lexical tokens of single hexadecimal digits +and + +characters. Since + +characters between tokens are not visible at the syntactic level, it is +not possible to recognize the multi-digit ``digits'' used in the higher +bases properly. The ability to recognize input in these bases was not +considered useful enough to require modifying these implementations. +Note that the recognition of numeric constants at the syntactic level +is not a problem with conformance to this volume of POSIX.1\(hy2008, as it does not impact the +behavior of conforming applications (and correct +.IR bc +programs). Historical implementations also accept input with all of the +digits +.BR '0' \(mi\c +.BR '9' +and +.BR 'A' \(mi\c +.BR 'F' +regardless of the value of +.BR ibase ; +since digits with value greater than or equal to +.BR ibase +are not really appropriate, the behavior when they appear is undefined, +except for the common case of: +.sp +.RS 4 +.nf +\fB +ibase=8; + /* Process in octal base. */ +\&... +ibase=A + /* Restore decimal base. */ +.fi \fR +.P +.RE +.P +In some historical implementations, if the expression to be written is +an uninitialized array element, a leading + +and/or up to four leading 0 characters may be output before the +character zero. This behavior is considered a bug; it is unlikely that +any currently conforming application relies on: +.sp +.RS 4 +.nf +\fB +echo 'b[3]' | bc +.fi \fR +.P +.RE +.P +returning 00000 rather than 0. +.P +Exact calculation of the number of fractional digits to output for a +given value in a base other than 10 can be computationally expensive. +Historical implementations use a faster approximation, and this is +permitted. Note that the requirements apply only to values of +.BR obase +that this volume of POSIX.1\(hy2008 requires implementations to support (in particular, not to +1, 0, or negative bases, if an implementation supports them as an +extension). +.P +Historical implementations of +.IR bc +did not allow array parameters to be passed as the last parameter to a +function. New implementations are encouraged to remove this restriction +even though it is not required by the grammar. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.3" ", " "Grammar Conventions", +.IR "\fIawk\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/bg.1p b/man-pages-posix-2013-a/man1p/bg.1p new file mode 100644 index 0000000..44c09d3 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/bg.1p @@ -0,0 +1,222 @@ +'\" et +.TH BG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +bg +\(em run jobs in the background +.SH SYNOPSIS +.LP +.nf +bg \fB[\fIjob_id\fR...\fB]\fR +.fi +.SH DESCRIPTION +If job control is enabled (see the description of +.IR set +.BR \(mim ), +the +.IR bg +utility shall resume suspended jobs from the current environment (see +.IR "Section 2.12" ", " "Shell Execution Environment") +by running them as background jobs. If the job specified by +.IR job_id +is already a running background job, the +.IR bg +utility shall have no effect and shall exit successfully. +.P +Using +.IR bg +to place a job into the background shall cause its process ID to become +``known in the current shell execution environment'', as if it had been +started as an asynchronous list; see +.IR "Section 2.9.3.1" ", " "Examples". +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIjob_id\fR" 10 +Specify the job to be resumed as a background job. If no +.IR job_id +operand is given, the most recently suspended job shall be used. The +format of +.IR job_id +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID". +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR bg : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The output of +.IR bg +shall consist of a line in the format: +.sp +.RS 4 +.nf +\fB +"[%d] %s\en", <\fIjob-number\fR>, <\fIcommand\fR> +.fi \fR +.P +.RE +.P +where the fields are as follows: +.IP "<\fIjob-number\fR>" 10 +A number that can be used to identify the job to the +.IR wait , +.IR fg , +and +.IR kill +utilities. Using these utilities, the job can be identified by +prefixing the job number with +.BR '%' . +.IP "<\fIcommand\fR>" 10 +The associated command that was given to the shell. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If job control is disabled, the +.IR bg +utility shall exit with an error and no job shall be placed in the +background. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +A job is generally suspended by typing the SUSP character +(\(hyZ on most systems); see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +At that point, +.IR bg +can put the job into the background. This is most effective when the +job is expecting no terminal input and its output has been redirected +to non-terminal files. A background job can be forced to stop when it +has terminal output by issuing the command: +.sp +.RS 4 +.nf +\fB +stty tostop +.fi \fR +.P +.RE +.P +A background job can be stopped with the command: +.sp +.RS 4 +.nf +\fB +kill \(mis stop \fIjob ID\fR +.fi \fR +.P +.RE +.P +The +.IR bg +utility does not work as expected when it is operating in its own +utility execution environment because that environment has no suspended +jobs. In the following examples: +.sp +.RS 4 +.nf +\fB +\&... | xargs bg +(bg) +.fi \fR +.P +.RE +.P +each +.IR bg +operates in a different environment and does not share its parent +shell's understanding of jobs. For this reason, +.IR bg +is generally implemented as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +The extensions to the shell specified in this volume of POSIX.1\(hy2008 have mostly been based +on features provided by the KornShell. The job control features +provided by +.IR bg , +.IR fg , +and +.IR jobs +are also based on the KornShell. The standard developers examined the +characteristics of the C shell versions of these utilities and found +that differences exist. Despite widespread use of the C shell, the +KornShell versions were selected for this volume of POSIX.1\(hy2008 to maintain a degree of +uniformity with the rest of the KornShell features selected (such as +the very popular command line editing features). +.P +The +.IR bg +utility is expected to wrap its output if the output exceeds the number +of display columns. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.3.1" ", " "Examples", +.IR "\fIfg\fR\^", +.IR "\fIkill\fR\^", +.IR "\fIjobs\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/break.1p b/man-pages-posix-2013-a/man1p/break.1p new file mode 100644 index 0000000..77cf59a --- /dev/null +++ b/man-pages-posix-2013-a/man1p/break.1p @@ -0,0 +1,134 @@ +'\" et +.TH BREAK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +break +\(em exit from for, while, or until loop +.SH SYNOPSIS +.LP +.nf +break \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The +.IR break +utility shall exit from the smallest enclosing +.BR for , +.BR while , +or +.BR until +loop, if any; or from the +.IR n th +enclosing loop if +.IR n +is specified. The value of +.IR n +is an unsigned decimal integer greater than or equal to 1. The default +shall be equivalent to +.IR n =1. +If +.IR n +is greater than the number of enclosing loops, the outermost enclosing +loop shall be exited. Execution shall continue with the command +immediately following the loop. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.IP "\00" 6 +Successful completion. +.IP >0 6 +The +.IR n +value was not an unsigned decimal integer greater than or equal to 1. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +for i in * +do + if test \(mid "$i" + then break + fi +done +.fi +.SH "RATIONALE" +In early proposals, consideration was given to expanding the syntax of +.IR break +and +.IR continue +to refer to a label associated with the appropriate loop as a +preferable alternative to the +.IR n +method. However, this volume of POSIX.1\(hy2008 does reserve the name space of command names +ending with a +. +It is anticipated that a future implementation could take advantage of +this and provide something like: +.sp +.RS 4 +.nf +\fB +outofloop: for i in a b c d e +do + for j in 0 1 2 3 4 5 6 7 8 9 + do + if test \(mir "${i}${j}" + then break outofloop + fi + done +done +.fi \fR +.P +.RE +.P +and that this might be standardized after implementation experience is +achieved. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/c99.1p b/man-pages-posix-2013-a/man1p/c99.1p new file mode 100644 index 0000000..386b094 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/c99.1p @@ -0,0 +1,1152 @@ +'\" et +.TH C99 "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +c99 +\(em compile standard C programs +.SH SYNOPSIS +.LP +.nf +c99 \fB[\fIoptions\fR...\fB] \fIpathname \fB[[\fIpathname\fB] [\fR\(miI \fIdirectory\fB] + \fB[\fR\(miL \fIdirectory\fB] [\fR\(mil \fIlibrary\fB]]\fR... +.fi +.SH DESCRIPTION +The +.IR c99 +utility is an interface to the standard C compilation system; it shall +accept source code conforming to the ISO\ C standard. The system conceptually +consists of a compiler and link editor. The input files referenced by +.IR pathname +operands and +.BR \(mil +option-arguments shall be compiled and linked to produce an executable +file. (It is unspecified whether the linking occurs entirely within the +operation of +.IR c99 ; +some implementations may produce objects that are not fully resolved +until the file is executed.) +.P +If the +.BR \(mic +option is specified, for all pathname operands of the form +.IR file \c +.BR .c , +the files: +.sp +.RS 4 +.nf +\fB +$(basename \fIpathname\fR .c).o +.fi \fR +.P +.RE +.P +shall be created as the result of successful compilation. If the +.BR \(mic +option is not specified, it is unspecified whether such +.BR .o +files are created or deleted for the +.IR file \c +.BR .c +operands. +.P +If there are no options that prevent link editing (such as +.BR \(mic +or +.BR \(miE ), +and all input files compile and link without error, the resulting +executable file shall be written according to the +.BR \(mio +.IR outfile +option (if present) or to the file +.BR a.out . +.P +The executable file shall be created as specified in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation", +except that the file permission bits shall be set to: +S_IRWXO | S_IRWXG | S_IRWXU +.P +and the bits specified by the +.IR umask +of the process shall be cleared. +.SH OPTIONS +The +.IR c99 +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that: +.IP " *" 4 +Options can be interspersed with operands. +.IP " *" 4 +The order of specifying the +.BR \(miL +and +.BR \(mil +options, and the order of specifying +.BR \(mil +options with respect to +.IR pathname +operands is significant. +.IP " *" 4 +Conforming applications shall specify each option separately; that is, +grouping option letters (for example, +.BR \(micO ) +need not be recognized by all implementations. +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Suppress the link-edit phase of the compilation, and do not remove any +object files that are produced. +.IP "\fB\(miD\ \fIname\fB[=\fIvalue\fB]\fR" 10 +.br +Define +.IR name +as if by a C-language +.BR #define +directive. If no =\c +.IR value +is given, a value of 1 shall be used. The +.BR \(miD +option has lower precedence than the +.BR \(miU +option. That is, if +.IR name +is used in both a +.BR \(miU +and a +.BR \(miD +option, +.IR name +shall be undefined regardless of the order of the options. Additional +implementation-defined +.IR name s +may be provided by the compiler. Implementations shall support at least +2\|048 bytes of +.BR \(miD +definitions and 256 +.IR names . +.IP "\fB\(miE\fP" 10 +Copy C-language source files to standard output, expanding all +preprocessor directives; no compilation shall be performed. If any +operand is not a text file, the effects are unspecified. +.IP "\fB\(mig\fP" 10 +Produce symbolic information in the object or executable files; the +nature of this information is unspecified, and may be modified by +implementation-defined interactions with other options. +.IP "\fB\(miI\ \fIdirectory\fR" 10 +Change the algorithm for searching for headers whose names are not +absolute pathnames to look in the directory named by the +.IR directory +pathname before looking in the usual places. Thus, headers whose names +are enclosed in double-quotes (\c +.BR \(dq\^\(dq ) +shall be searched for first in the directory of the file with the +.BR #include +line, then in directories named in +.BR \(miI +options, and last in the usual places. For headers whose names are +enclosed in angle brackets (\c +.BR \(dq<\|>\(dq ), +the header shall be searched for only in directories named in +.BR \(miI +options and then in the usual places. Directories named in +.BR \(miI +options shall be searched in the order specified. If the +.BR \(miI +option is used to specify a directory that is one of the usual places +searched by default, the results are unspecified. Implementations shall +support at least ten instances of this option in a single +.IR c99 +command invocation. +.IP "\fB\(miL\ \fIdirectory\fR" 10 +Change the algorithm of searching for the libraries named in the +.BR \(mil +objects to look in the directory named by the +.IR directory +pathname before looking in the usual places. Directories named in +.BR \(miL +options shall be searched in the order specified. If the +.BR \(miL +option is used to specify a directory that is one of the usual places +searched by default, the results are unspecified. Implementations shall +support at least ten instances of this option in a single +.IR c99 +command invocation. If a directory specified by a +.BR \(miL +option contains files with names starting with any of the strings +.BR \(dqlibc.\(dq , +.BR \(dqlibl.\(dq , +.BR \(dqlibpthread.\(dq , +.BR \(dqlibm.\(dq , +.BR \(dqlibrt.\(dq , +.BR \(dqlibtrace.\(dq , +.BR \(dqlibxnet.\(dq , +or +.BR \(dqliby.\(dq , +the results are unspecified. +.IP "\fB\(mil\ \fIlibrary\fR" 10 +Search the library named +.BR liblibrary.a . +A library shall be searched when its name is encountered, so the +placement of a +.BR \(mil +option is significant. Several standard libraries can be +specified in this manner, as described in the EXTENDED DESCRIPTION +section. Implementations may recognize implementation-defined +suffixes other than +.BR .a +as denoting libraries. +.IP "\fB\(miO\ \fIoptlevel\fR" 10 +Specify the level of code optimization. If the +.IR optlevel +option-argument is the digit +.BR '0' , +all special code optimizations shall be disabled. If it is the digit +.BR '1' , +the nature of the optimization is unspecified. If the +.BR \(miO +option is omitted, the nature of the system's default optimization is +unspecified. It is unspecified whether code generated in the presence +of the +.BR \(miO +0 option is the same as that generated when +.BR \(miO +is omitted. Other +.IR optlevel +values may be supported. +.IP "\fB\(mio\ \fIoutfile\fR" 10 +Use the pathname +.IR outfile , +instead of the default +.BR a.out , +for the executable file produced. If the +.BR \(mio +option is present with +.BR \(mic +or +.BR \(miE , +the result is unspecified. +.IP "\fB\(mis\fP" 10 +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using the +.IR exec +family defined in the System Interfaces volume of POSIX.1\(hy2008 has been removed (stripped). If both +.BR \(mig +and +.BR \(mis +options are present, the action taken is unspecified. +.IP "\fB\(miU\ \fIname\fR" 10 +Remove any initial definition of +.IR name . +.P +Multiple instances of the +.BR \(miD , +.BR \(miI , +.BR \(miL , +.BR \(mil , +and +.BR \(miU +options can be specified. +.SH OPERANDS +The application shall ensure that at least one +.IR pathname +operand is specified. The following forms for +.IR pathname +operands shall be supported: +.IP "\fIfile.\fBc\fR" 10 +A C-language source file to be compiled and optionally linked. The +application shall ensure that the operand is of this form if the +.BR \(mic +option is used. +.IP "\fIfile.\fBa\fR" 10 +A library of object files typically produced by the +.IR ar +utility, and passed directly to the link editor. Implementations may +recognize implementation-defined suffixes other than +.BR .a +as denoting object file libraries. +.IP "\fIfile.\fBo\fR" 10 +An object file produced by +.IR c99 +.BR \(mic +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .o +as denoting object files. +.P +The processing of other files is implementation-defined. +.SH STDIN +Not used. +.SH "INPUT FILES" +Each input file shall be one of the following: a text file containing a +C-language source program, an object file in the format produced by +.IR c99 +.BR \(mic , +or a library of object files, in the format produced by archiving zero +or more object files, using +.IR ar . +Implementations may supply additional utilities that produce files in +these formats. Additional input file formats are +implementation-defined. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR c99 : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Provide a pathname that should override the default directory for +temporary files, if any. +On XSI-conforming systems, provide a pathname that shall override the +default directory for temporary files, if any. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If more than one +.IR pathname +operand ending in +.BR .c +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +may be written. These messages, if written, shall precede the +processing of each input file; they shall not be written to the +standard output if they are written to the standard error, as described +in the STDERR section. +.P +If the +.BR \(miE +option is specified, the standard output shall be a text file that +represents the results of the preprocessing stage of the language; it +may contain extra information appropriate for subsequent compilation +passes. +.SH STDERR +The standard error shall be used only for diagnostic messages. +If more than one +.IR pathname +operand ending in +.BR .c +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +may be written to allow identification of the diagnostic and warning +messages with the appropriate input file. These messages, if written, +shall precede the processing of each input file; they shall not be +written to the standard error if they are written to the standard +output, as described in the STDOUT section. +.P +This utility may produce warning messages about certain conditions that +do not warrant returning an error (non-zero) exit value. +.SH "OUTPUT FILES" +Object files or executable files or both are produced in unspecified +formats. If the pathname of an object file or executable file to be +created by +.IR c99 +resolves to an existing directory entry for a file that is not a regular +file, it is unspecified whether +.IR c99 +shall attempt to create the file or shall issue a diagnostic and exit +with a non-zero exit status. +.SH "EXTENDED DESCRIPTION" +.SS "Standard Libraries" +.P +The +.IR c99 +utility shall recognize the following +.BR \(mil +options for standard libraries: +.IP "\fB\(mil\ c\fR" 10 +This option shall make available all interfaces referenced in the System Interfaces volume of POSIX.1\(hy2008, +with the possible exception of those interfaces listed as residing in +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +\fIpthread_kill\fR(), +and +\fIpthread_sigmask\fR() +in +.IR , +.IR , +interfaces marked as optional in +.IR , +interfaces marked as ADV (Advisory Information) in +.IR , +and interfaces beginning with the prefix clock_ or time_ in +.IR . +This option shall not be required to be present to cause a search of +this library. +.IP "\fB\(mil\ l\fR" 10 +This option shall make available all interfaces required by the +C-language output of +.IR lex +that are not made available through the +.BR "\(mil\ c" +option. +.IP "\fB\(mil\ pthread\fR" 10 +This option shall make available all interfaces referenced in +.IR +and +\fIpthread_kill\fR() +and +\fIpthread_sigmask\fR() +referenced in +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ m\fR" 10 +This option shall make available all interfaces referenced in +.IR , +.IR , +and +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ rt\fR" 10 +This option shall make available all interfaces referenced in +.IR , +.IR , +.IR , +.IR , +and +.IR , +interfaces marked as optional in +.IR , +interfaces marked as ADV (Advisory Information) in +.IR , +and interfaces beginning with the prefix clock_ and time_ in +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ trace\fR" 10 +This option shall make available all interfaces referenced in +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ xnet\fR" 10 +This option shall make available all interfaces referenced in +.IR , +.IR , +.IR , +.IR , +and +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ y\fR" 10 +This option shall make available all interfaces required by the +C-language output of +.IR yacc +that are not made available through the +.BR "\(mil\ c" +option. +.P +In the absence of options that inhibit invocation of the link editor, +such as +.BR \(mic +or +.BR \(miE , +the +.IR c99 +utility shall cause the equivalent of a +.BR "\(mil\ c" +option to be passed to the link editor after the last +.IR pathname +operand or +.BR \(mil +option, causing it to be searched after all other object files and +libraries are loaded. +.P +It is unspecified whether the libraries +.BR libc.a , +.BR libl.a , +.BR libm.a , +.BR libpthread.a , +.BR librt.a , +.BR libtrace.a , +.BR libxnet.a , +or +.BR liby.a +exist as regular files. The implementation may accept as +.BR \(mil +option-arguments names of objects that do not exist as regular files. +.SS "External Symbols" +.P +The C compiler and link editor shall support the significance of +external symbols up to a length of at least 31 bytes; the action taken +upon encountering symbols exceeding the implementation-defined +maximum symbol length is unspecified. +.P +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4\|095 external +symbols in total. A diagnostic message shall be written to the standard +output if the implementation-defined limit is exceeded; other actions +are unspecified. +.SS "Header Search" +.P +If a file with the same name as one of the standard headers defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 13" ", " "Headers", +not provided as part of the implementation, is placed in any of the +usual places that are searched by default for headers, the results are +unspecified. +.SS "Programming Environments" +.P +All implementations shall support one of the following programming +environments as a default. Implementations may support more than one +of the following programming environments. Applications can use +\fIsysconf\fR() +or +.IR getconf +to determine which programming environments are supported. +.br +.sp +.ce 1 +\fBTable 4-4: Programming Environments: Type Sizes\fR +.TS +center box tab(!); +cB | cB | cB | cB | cB +cB | cB | cB | cB | cB +l | n | n | n | n. +Programming Environment!Bits in!Bits in!Bits in!Bits in +\fIgetconf\fP Name!int!long!pointer!off_t +_ +_POSIX_V7_ILP32_OFF32!32!32!32!32 +_POSIX_V7_ILP32_OFFBIG!32!32!32!\(>=64 +_POSIX_V7_LP64_OFF64!32!64!64!64 +_POSIX_V7_LPBIG_OFFBIG!\(>=32!\(>=64!\(>=64!\(>=64 +.TE +.P +All implementations shall support one or more environments where the +widths of the following types are no greater than the width of type +.BR long : +.TS +tab(!) center; +lB lB lB. +T{ +.nf +blksize_t +cc_t +mode_t +nfds_t +pid_t +T}!T{ +.nf +ptrdiff_t +size_t +speed_t +ssize_t +suseconds_t +T}!T{ +.nf +tcflag_t +wchar_t +wint_t +.fi +T} +.TE +.P +The executable files created when these environments are selected shall +be in a proper format for execution by the +.IR exec +family of functions. Each environment may be one of the ones in +.IR "Table 4-4, Programming Environments: Type Sizes", +or it may be another environment. The names for the environments that +meet this requirement shall be output by a +.IR getconf +command using the POSIX_V7_WIDTH_RESTRICTED_ENVS argument, as a +-separated +list of names suitable for use with the +.IR getconf +.BR \(miv +option. If more than one environment meets the requirement, the names +of all such environments shall be output on separate lines. Any of +these names can then be used in a subsequent +.IR getconf +command to obtain the flags specific to that environment with the +following suffixes added as appropriate: +.IP _CFLAGS 10 +To get the C compiler flags. +.IP _LDFLAGS 10 +To get the linker/loader flags. +.IP _LIBS 10 +To get the libraries. +.P +This requirement may be removed in a future version. +.P +When this utility processes a file containing a function called +\fImain\fR(), +it shall be defined with a return type equivalent to +.BR int . +Using return from the initial call to +\fImain\fR() +shall be equivalent (other than with respect to language scope issues) +to calling +\fIexit\fR() +with the returned value. Reaching the end of the initial call to +\fImain\fR() +shall be equivalent to calling +.IR exit (0). +The implementation shall not declare a prototype for this function. +.P +Implementations provide configuration strings for C compiler flags, +linker/loader flags, and libraries for each supported environment. +When an application needs to use a specific programming environment +rather than the implementation default programming environment while +compiling, the application shall first verify that the implementation +supports the desired environment. If the desired programming +environment is supported, the application shall then invoke +.IR c99 +with the appropriate C compiler flags as the first options for the +compile, the appropriate linker/loader flags after any other options +except +.BR \(mil +but before any operands or +.BR \(mil +options, and the appropriate libraries at the end of the operands +and +.BR \(mil +options. +.P +Conforming applications shall not attempt to link together object files +compiled for different programming models. Applications shall also be +aware that binary data placed in shared memory or in files might not be +recognized by applications built for other programming models. +.br +.sp +.ce 1 +\fBTable 4-5: Programming Environments: \fIc99\fP Arguments\fR +.TS +center box tab(!); +cB | cB | cB +cB | cB | cB +l | l | l. +Programming Environment!!\fIc99\fP Arguments +\fIgetconf\fP Name!Use!\fIgetconf\fP Name +_ +_POSIX_V7_ILP32_OFF32!C Compiler Flags!POSIX_V7_ILP32_OFF32_CFLAGS +!Linker/Loader Flags!POSIX_V7_ILP32_OFF32_LDFLAGS +!Libraries!POSIX_V7_ILP32_OFF32_LIBS +_ +_POSIX_V7_ILP32_OFFBIG!C Compiler Flags!POSIX_V7_ILP32_OFFBIG_CFLAGS +!Linker/Loader Flags!POSIX_V7_ILP32_OFFBIG_LDFLAGS +!Libraries!POSIX_V7_ILP32_OFFBIG_LIBS +_ +_POSIX_V7_LP64_OFF64!C Compiler Flags!POSIX_V7_LP64_OFF64_CFLAGS +!Linker/Loader Flags!POSIX_V7_LP64_OFF64_LDFLAGS +!Libraries!POSIX_V7_LP64_OFF64_LIBS +_ +_POSIX_V7_LPBIG_OFFBIG!C Compiler Flags!POSIX_V7_LPBIG_OFFBIG_CFLAGS +!Linker/Loader Flags!POSIX_V7_LPBIG_OFFBIG_LDFLAGS +!Libraries!POSIX_V7_LPBIG_OFFBIG_LIBS +.TE +.P +In addition to the type size programming environments above, all +implementations also support a multi-threaded programming environment +that is orthogonal to all of the programming environments listed above. +The +.IR getconf +utility can be used to get flags for the threaded programming environment, +as indicated in +.IR "Table 4-6, Threaded Programming Environment: \fIc99\fP Arguments". +.sp +.ce 1 +\fBTable 4-6: Threaded Programming Environment: \fIc99\fP Arguments\fR +.TS +center box tab(!); +cB | cB | cB +cB | cB | cB +l | l | l. +Programming Environment!!\fIc99\fP Arguments +\fIgetconf\fP Name!Use!\fIgetconf\fP Name +_ +_POSIX_THREADS!C Compiler Flags!POSIX_V7_THREADS_CFLAGS +!Linker/Loader Flags!POSIX_V7_THREADS_LDFLAGS +.TE +.P +These programming environment flags may be used in conjunction with any +of the type size programming environments supported by the implementation. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful compilation or link edit. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When +.IR c99 +encounters a compilation error that causes an object file not to be +created, it shall write a diagnostic to standard error and continue to +compile other source code operands, but it shall not perform the link +phase and return a non-zero exit status. If the link edit is +unsuccessful, a diagnostic message shall be written to standard error +and +.IR c99 +exits with a non-zero status. A conforming application shall rely on the +exit status of +.IR c99 , +rather than on the existence or mode of the executable file. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since the +.IR c99 +utility usually creates files in the current directory during the +compilation process, it is typically necessary to run the +.IR c99 +utility in a directory in which a file can be created. +.P +On systems providing POSIX Conformance (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 2" ", " "Conformance"), +.IR c99 +is required only with the C-Language Development option; +XSI-conformant systems always provide +.IR c99 . +.P +Some historical implementations have created +.BR .o +files when +.BR \(mic +is not specified and more than one source file is given. Since this +area is left unspecified, the application cannot rely on +.BR .o +files being created, but it also must be prepared for any related +.BR .o +files that already exist being deleted at the completion of the link +edit. +.P +There is the possible implication that if a user supplies versions of +the standard functions (before they would be encountered by an implicit +.BR "\(mil\ c" +or explicit +.BR "\(mil\ m" ), +that those versions would be used in place of the standard versions. +There are various reasons this might not be true (functions defined as +macros, manipulations for clean name space, and so on), so the +existence of files named in the same manner as the standard libraries +within the +.BR \(miL +directories is explicitly stated to produce unspecified behavior. +.P +All of the functions specified in the System Interfaces volume of POSIX.1\(hy2008 may be made visible by +implementations when the Standard C Library is searched. Conforming +applications must explicitly request searching the other standard +libraries when functions made visible by those libraries are used. +.P +In the ISO\ C standard the mapping from physical source characters to the C +source character set is implementation-defined. Implementations may +strip white-space characters before the terminating + +of a (physical) line as part of this mapping and, as a consequence +of this, one or more white-space characters (and no other characters) +between a + +character and the + +character that terminates the line produces implementation-defined +results. Portable applications should not use such constructs. +.P +Some +.IR c99 +compilers not conforming to POSIX.1\(hy2008 do not support trigraphs by default. +.SH EXAMPLES +.IP " 1." 4 +The following usage example compiles +.BR foo.c +and creates the executable file +.BR foo : +.RS 4 +.sp +.RS 4 +.nf +\fB +c99 \(mio foo foo.c +.fi \fR +.P +.RE +.P +The following usage example compiles +.BR foo.c +and creates the object file +.BR foo.o : +.sp +.RS 4 +.nf +\fB +c99 \(mic foo.c +.fi \fR +.P +.RE +.P +The following usage example compiles +.BR foo.c +and creates the executable file +.BR a.out : +.sp +.RS 4 +.nf +\fB +c99 foo.c +.fi \fR +.P +.RE +.P +The following usage example compiles +.BR foo.c , +links it with +.BR bar.o , +and creates the executable file +.BR a.out . +It may also create and leave +.BR foo.o : +.sp +.RS 4 +.nf +\fB +c99 foo.c bar.o +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following example shows how an application using threads interfaces +can test for support of and use a programming environment supporting +32-bit +.BR int , +.BR long , +and +.BR pointer +types and an +.BR off_t +type using at least 64 bits: +.RS 4 +.sp +.RS 4 +.nf +\fB +offbig_env=$(getconf _POSIX_V7_ILP32_OFFBIG) +if [ $offbig_env != "-1" ] && [ $offbig_env != "undefined" ] +then + c99 $(getconf POSIX_V7_ILP32_OFFBIG_CFLAGS) \e + $(getconf POSIX_V7_THREADS_CFLAGS) -D_XOPEN_SOURCE=700 \e + $(getconf POSIX_V7_ILP32_OFFBIG_LDFLAGS) \e + $(getconf POSIX_V7_THREADS_LDFLAGS) foo.c -o foo \e + $(getconf POSIX_V7_ILP32_OFFBIG_LIBS) \e + -l pthread +else + echo ILP32_OFFBIG programming environment not supported + exit 1 +fi +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +The following examples clarify the use and interactions of +.BR \(miL +and +.BR \(mil +options. +.RS 4 +.P +Consider the case in which module +.BR a.c +calls function +\fIf\fR() +in library +.BR libQ.a , +and module +.BR b.c +calls function +\fIg\fR() +in library +.BR libp.a . +Assume that both libraries reside in +.BR /a/b/c . +The command line to compile and link in the desired way is: +.sp +.RS 4 +.nf +\fB +c99 \(miL /a/b/c main.o a.c \(mil Q b.c \(mil p +.fi \fR +.P +.RE +.P +In this case the +.BR \(miL +option need only precede the first +.BR \(mil +option, since both +.BR libQ.a +and +.BR libp.a +reside in the same directory. +.P +Multiple +.BR \(miL +options can be used when library name collisions occur. Building on +the previous example, suppose that the user wants to use a new +.BR libp.a , +in +.BR /a/a/a , +but still wants +\fIf\fR() +from +.BR /a/b/c/libQ.a : +.sp +.RS 4 +.nf +\fB +c99 \(miL /a/a/a \(miL /a/b/c main.o a.c \(mil Q b.c \(mil p +.fi \fR +.P +.RE +.P +In this example, the linker searches the +.BR \(miL +options in the order specified, and finds +.BR /a/a/a/libp.a +before +.BR /a/b/c/libp.a +when resolving references for +.BR b.c . +The order of the +.BR \(mil +options is still important, however. +.RE +.IP " 4." 4 +The following example shows how an application can use a programming +environment where the widths of the following types: +.BR blksize_t , +.BR cc_t , +.BR mode_t , +.BR nfds_t , +.BR pid_t , +.BR ptrdiff_t , +.BR size_t , +.BR speed_t , +.BR ssize_t , +.BR suseconds_t , +.BR tcflag_t , +.BR wchar_t , +.BR wint_t +.RS 4 +.P +are no greater than the width of type +.BR long : +.sp +.RS 4 +.nf +\fB +# First choose one of the listed environments ... +.P +# ... if there are no additional constraints, the first one will do: +CENV=$(getconf POSIX_V7_WIDTH_RESTRICTED_ENVS | head -n l) +.P +# ... or, if an environment that supports large files is preferred, +# look for names that contain "OFF64" or "OFFBIG". (This chooses +# the last one in the list if none match.) +for CENV in $(getconf POSIX_V7_WIDTH_RESTRICTED_ENVS) +do + case $CENV in + *OFF64*|*OFFBIG*) break ;; + esac +done +.P +# The chosen environment name can now be used like this: +.P +c99 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=200809L \e +$(getconf ${CENV}_LDFLAGS) foo.c -o foo \e +$(getconf ${CENV}_LIBS) +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR c99 +utility is based on the +.IR c89 +utility originally introduced in the ISO\ POSIX\(hy2:\|1993 standard. +.P +Some of the changes from +.IR c89 +include the ability to intersperse options and operands (which many +.IR c89 +implementations allowed despite it not being specified), +the description of +.BR \(mil +as an option instead of an operand, and the modification to the contents +of the Standard Libraries section to account for new headers and options; +for example, +.IR +added to the description of +.BR "\(mil\ rt" , +and +.BR "\(mil\ trace" +added for the Tracing option. +.P +POSIX.1\(hy2008 specifies that the +.IR c99 +utility must be able to use regular files for +.BR *.o +files and for +.BR a.out +files. Implementations are free to overwrite existing files of other +types when attempting to create object files and executable files, but +are not required to do so. If something other than a regular file is +specified and using it fails for any reason, +.IR c99 +is required to issue a diagnostic message and exit with a non-zero exit +status. But for some file types, the problem may not be noticed for a +long time. For example, if a FIFO named +.BR a.out +exists in the current directory, +.IR c99 +may attempt to open +.BR a.out +and will hang in the +\fIopen\fR() +call until another process opens the FIFO for reading. Then +.IR c99 +may write most of the +.BR a.out +to the FIFO and fail when it tries to seek back close to the start of +the file to insert a timestamp (FIFOs are not seekable files). The +.IR c99 +utility is also allowed to issue a diagnostic immediately if it +encounters an +.BR a.out +or +.BR *.o +file that is not a regular file. For portable use, applications should +ensure that any +.BR a.out , +.BR \(mio +option-argument, or +.BR *.o +files corresponding to any +.BR *.c +files do not conflict with names already in use that are not regular +files or symbolic links that point to regular files. +.P +On many systems, multi-threaded applications run in a programming +environment that is distinct from that used by single-threaded +applications. This multi-threaded programming environment (in addition +to needing to specify +.BR "\(mil pthread" +at link time) may require additional flags to be set when headers are +processed at compile time (\c +.BR \(miD_REENTRANT +being common). This programming environment is orthogonal to the type +size programming environments discussed above and listed in +.IR "Table 4-4, Programming Environments: Type Sizes". +This version of the standard adds +.IR getconf +utility calls to provide the C compiler flags and linker/loader flags +needed to support multi-threaded applications. Note that on a system +where single-threaded applications are a special case of a multi-threaded +application, both of these +.IR getconf +calls may return NULL strings; on other implementations both of +these strings may be non-NULL strings. +.P +The C standardization committee invented trigraphs (e.g., +.BR \(dq??!\(dq +to represent +.BR '|' ) +to address character portability problems in development environments +based on national variants of the 7-bit ISO/IEC\ 646:\|1991 standard character set. However, +these environments were already obsolete by the time the first ISO\ C standard was +published, and in practice trigraphs have not been used for their intended +purpose, and usually are intended to have their original meaning in K&R C. +For example, in practice a C-language source string like +.BR \(dqWhat??!\(dq +is usually intended to end in two + +characters and an +, +not in +.BR '|' . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation", +.IR "\fIar\fR\^", +.IR "\fIgetconf\fR\^", +.IR "\fImake\fR\^", +.IR "\fInm\fR\^", +.IR "\fIstrip\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "Chapter 13" ", " "Headers" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^", +.IR "\fIsysconf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cal.1p b/man-pages-posix-2013-a/man1p/cal.1p new file mode 100644 index 0000000..dd71fc7 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cal.1p @@ -0,0 +1,162 @@ +'\" et +.TH CAL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cal +\(em print a calendar +.SH SYNOPSIS +.LP +.nf +cal \fB[[\fImonth\fB] \fIyear\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cal +utility shall write a calendar to standard output using the Julian +calendar for dates from January 1, 1 through September 2, 1752 and the +Gregorian calendar for dates from September 14, 1752 through December +31, 9999 as though the Gregorian calendar had been adopted on September +14, 1752. +.P +If no operands are given, +.IR cal +shall produce a one-month calendar for the current month in the +current year. If only the +.IR year +operand is given, +.IR cal +shall produce a calendar for all twelve months in the given calendar +year. If both +.IR month +and +.IR year +operands are given, +.IR cal +shall produce a one-month calendar for the given month in the given year. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fImonth\fR" 10 +Specify the month to be displayed, represented as a decimal integer +from 1 (January) to 12 (December). +.IP "\fIyear\fR" 10 +Specify the year for which the calendar is displayed, represented as a +decimal integer from 1 to 9999. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cal : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of the calendar. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate the value of the current +month. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used to display the calendar, in an +unspecified format. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Note that: +.sp +.RS 4 +.nf +\fB +cal 83 +.fi \fR +.P +.RE +.P +refers to A.D. 83, not 1983. +.SH EXAMPLES +None. +.SH RATIONALE +Earlier versions of this standard incorrectly required that the command: +.sp +.RS 4 +.nf +\fB +cal 2000 +.fi \fR +.P +.RE +.P +write a one-month calendar for the current calendar month (no matter what +the current year is) in the year 2000 to standard output. This did not +match historic practice in any known version of the +.IR cal +utility. The description has been updated to match historic practice. +When only the +.IR year +operand is given, +.IR cal +writes a twelve-month calendar for the specified year. +.SH "FUTURE DIRECTIONS" +A future version of this standard may support locale-specific +recognition of the date of adoption of the Gregorian calendar. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cat.1p b/man-pages-posix-2013-a/man1p/cat.1p new file mode 100644 index 0000000..1a79146 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cat.1p @@ -0,0 +1,325 @@ +'\" et +.TH CAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cat +\(em concatenate and print files +.SH SYNOPSIS +.LP +.nf +cat \fB[\fR\(miu\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cat +utility shall read files in sequence and shall write their contents +to the standard output in the same sequence. +.SH OPTIONS +The +.IR cat +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miu\fP" 10 +Write bytes from the input file to the standard output without delay as +each is read. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, the standard input shall be used. If a +.IR file +is +.BR '\(mi' , +the +.IR cat +utility shall read from the standard input at that point in the +sequence. The +.IR cat +utility shall not close and reopen standard input when it is referenced +in this way, but shall accept multiple occurrences of +.BR '\(mi' +as a +.IR file +operand. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cat : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall contain the sequence of bytes read from the +input files. Nothing else shall be written to the standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(miu +option has value in prototyping non-blocking reads from FIFOs. The +intent is to support the following sequence: +.sp +.RS 4 +.nf +\fB +mkfifo foo +cat \(miu foo > /dev/tty13 & +cat \(miu > foo +.fi \fR +.P +.RE +.P +It is unspecified whether standard output is or is not buffered in the +default case. This is sometimes of interest when standard output is +associated with a terminal, since buffering may delay the output. The +presence of the +.BR \(miu +option guarantees that unbuffered I/O is available. It is +implementation-defined whether the +.IR cat +utility buffers output if the +.BR \(miu +option is not specified. Traditionally, the +.BR \(miu +option is implemented using the equivalent of the +\fIsetvbuf\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +cat myfile +.fi \fR +.P +.RE +.P +writes the contents of the file +.BR myfile +to standard output. +.P +The following command: +.sp +.RS 4 +.nf +\fB +cat doc1 doc2 > doc.all +.fi \fR +.P +.RE +.P +concatenates the files +.BR doc1 +and +.BR doc2 +and writes the result to +.BR doc.all . +.P +Because of the shell language mechanism used to perform output +redirection, a command such as this: +.sp +.RS 4 +.nf +\fB +cat doc doc.end > doc +.fi \fR +.P +.RE +.P +causes the original data in +.BR doc +to be lost. +.P +The command: +.sp +.RS 4 +.nf +\fB +cat start \(mi middle \(mi end > file +.fi \fR +.P +.RE +.P +when standard input is a terminal, gets two arbitrary pieces of input +from the terminal with a single invocation of +.IR cat . +Note, however, that if standard input is a regular file, this would be +equivalent to the command: +.sp +.RS 4 +.nf +\fB +cat start \(mi middle /dev/null end > file +.fi \fR +.P +.RE +.P +because the entire contents of the file would be consumed by +.IR cat +the first time +.BR '\(mi' +was used as a +.IR file +operand and an end-of-file condition would be detected immediately when +.BR '\(mi' +was referenced the second time. +.SH RATIONALE +Historical versions of the +.IR cat +utility include the +.BR \(mie , +.BR \(mit , +and +.BR \(miv , +options which permit the ends of lines, + +characters, and invisible characters, respectively, to be rendered visible +in the output. The standard developers omitted these options because +they provide too fine a degree of control over what is made visible, +and similar output can be obtained using a command such as: +.sp +.RS 4 +.nf +\fB +sed \(min l pathname +.fi \fR +.P +.RE +.P +The latter also has the advantage that its output is unambiguous, +whereas the output of historical +.IR cat +.BR \(mietv +is not. +.P +The +.BR \(mis +option was omitted because it corresponds to different functions in BSD +and System V-based systems. The BSD +.BR \(mis +option to squeeze blank lines can be accomplished by the shell script +shown in the following example: +.sp +.RS 4 +.nf +\fB +sed \(min ' +# Write non-empty lines. +/./ { + p + d + } +# Write a single empty line, then look for more empty lines. +/^$/ p +# Get next line, discard the held (empty line), +# and look for more empty lines. +:Empty +/^$/ { + N + s/.// + b Empty + } +# Write the non-empty line before going back to search +# for the first in a set of empty lines. + p +\&' +.fi \fR +.P +.RE +.P +The System V +.BR \(mis +option to silence error messages can be accomplished by redirecting the +standard error. Note that the BSD documentation for +.IR cat +uses the term ``blank line'' to mean the same as the POSIX ``empty +line'': a line consisting only of a +. +.P +The BSD +.BR \(min +option was omitted because similar functionality can be obtained from +the +.BR \(min +option of the +.IR pr +utility. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImore\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIsetvbuf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cd.1p b/man-pages-posix-2013-a/man1p/cd.1p new file mode 100644 index 0000000..7d5308e --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cd.1p @@ -0,0 +1,507 @@ +'\" et +.TH CD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cd +\(em change the working directory +.SH SYNOPSIS +.LP +.nf +cd \fB[\fR\(miL|\(miP\fB] [\fIdirectory\fB]\fR +.P +cd \(mi +.fi +.SH DESCRIPTION +The +.IR cd +utility shall change the working directory of the current shell +execution environment (see +.IR "Section 2.12" ", " "Shell Execution Environment") +by executing the following steps in sequence. (In the following steps, +the symbol +.BR curpath +represents an intermediate value used to simplify the description of +the algorithm used by +.IR cd . +There is no requirement that +.BR curpath +be made visible to the application.) +.IP " 1." 4 +If no +.IR directory +operand is given and the +.IR HOME +environment variable is empty or undefined, the default behavior is +implementation-defined and no further steps shall be taken. +.IP " 2." 4 +If no +.IR directory +operand is given and the +.IR HOME +environment variable is set to a non-empty value, the +.IR cd +utility shall behave as if the directory named in the +.IR HOME +environment variable was specified as the +.IR directory +operand. +.IP " 3." 4 +If the +.IR directory +operand begins with a + +character, set +.BR curpath +to the operand and proceed to step 7. +.IP " 4." 4 +If the first component of the +.IR directory +operand is dot or dot-dot, proceed to step 6. +.IP " 5." 4 +Starting with the first pathname in the +-separated +pathnames of +.IR CDPATH +(see the ENVIRONMENT VARIABLES section) if the pathname is non-null, +test if the concatenation of that pathname, a + +character if that pathname did not end with a + +character, and the +.IR directory +operand names a directory. If the pathname is null, test if the +concatenation of dot, a + +character, and the operand names a directory. In either case, if the +resulting string names an existing directory, set +.BR curpath +to that string and proceed to step 7. Otherwise, repeat this step with +the next pathname in +.IR CDPATH +until all pathnames have been tested. +.IP " 6." 4 +Set +.BR curpath +to the +.IR directory +operand. +.IP " 7." 4 +If the +.BR \(miP +option is in effect, proceed to step 10. If +.BR curpath +does not begin with a + +character, set +.BR curpath +to the string formed by the concatenation of the value of +.IR PWD , +a + +character if the value of +.IR PWD +did not end with a + +character, and +.BR curpath . +.IP " 8." 4 +The +.BR curpath +value shall then be converted to canonical form as follows, considering +each component from beginning to end, in sequence: +.RS 4 +.IP " a." 4 +Dot components and any + +characters that separate them from the next component shall be deleted. +.IP " b." 4 +For each dot-dot component, if there is a preceding component and it is +neither root nor dot-dot, then: +.RS 4 +.IP " i." 5 +If the preceding component does not refer (in the context of pathname +resolution with symbolic links followed) to a directory, then the +.IR cd +utility shall display an appropriate error message and no further steps +shall be taken. +.IP ii. 5 +The preceding component, all + +characters separating the preceding component from dot-dot, dot-dot, +and all + +characters separating dot-dot from the following component (if any) +shall be deleted. +.RE +.IP " c." 4 +An implementation may further simplify +.BR curpath +by removing any trailing + +characters that are not also leading + +characters, replacing multiple non-leading consecutive + +characters with a single +, +and replacing three or more leading + +characters with a single +. +If, as a result of this canonicalization, the +.BR curpath +variable is null, no further steps shall be taken. +.RE +.IP " 9." 4 +If +.BR curpath +is longer than +{PATH_MAX} +bytes (including the terminating null) and the +.IR directory +operand was not longer than +{PATH_MAX} +bytes (including the terminating null), then +.BR curpath +shall be converted from an absolute pathname to an equivalent relative +pathname if possible. This conversion shall always be considered +possible if the value of +.IR PWD , +with a trailing + +added if it does not already have one, is an initial substring of +.BR curpath . +Whether or not it is considered possible under other circumstances is +unspecified. Implementations may also apply this conversion if +.BR curpath +is not longer than +{PATH_MAX} +bytes or the +.IR directory +operand was longer than +{PATH_MAX} +bytes. +.IP 10. 4 +The +.IR cd +utility shall then perform actions equivalent to the +\fIchdir\fR() +function called with +.BR curpath +as the +.IR path +argument. If these actions fail for any reason, the +.IR cd +utility shall display an appropriate error message and the remainder of +this step shall not be executed. If the +.BR \(miP +option is not in effect, the +.IR PWD +environment variable shall be set to the value that +.BR curpath +had on entry to step 9 (i.e., before conversion to a relative +pathname). If the +.BR \(miP +option is in effect, the +.IR PWD +environment variable shall be set to the string that would be output by +.IR pwd +.BR \(miP . +If there is insufficient permission on the new directory, or on any +parent of that directory, to determine the current working directory, +the value of the +.IR PWD +environment variable is unspecified. +.P +If, during the execution of the above steps, the +.IR PWD +environment variable +is set, the +.IR OLDPWD +environment variable shall also be set to +the value of the old working directory (that is the current working +directory immediately prior to the call to +.IR cd ). +.SH OPTIONS +The +.IR cd +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(miL\fP" 10 +Handle the operand dot-dot logically; symbolic link components shall +not be resolved before dot-dot components are processed (see steps 8. +and 9. in the DESCRIPTION). +.IP "\fB\(miP\fP" 10 +Handle the operand dot-dot physically; symbolic link components shall +be resolved before dot-dot components are processed (see step 7. in the +DESCRIPTION). +.P +If both +.BR \(miL +and +.BR \(miP +options are specified, the last of these options shall be used and all +others ignored. If neither +.BR \(miL +nor +.BR \(miP +is specified, the operand shall be handled dot-dot logically; see the +DESCRIPTION. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdirectory\fR" 10 +An absolute or relative pathname of the directory that shall become +the new working directory. The interpretation of a relative pathname +by +.IR cd +depends on the +.BR \(miL +option and the +.IR CDPATH +and +.IR PWD +environment variables. If +.IR directory +is an empty string, the results are unspecified. +.IP "\(mi" 10 +When a + +is used as the operand, this shall be equivalent to the command: +.RS 10 +.sp +.RS 4 +.nf +\fB +cd "$OLDPWD" && pwd +.fi \fR +.P +.RE +.P +which changes to the previous working directory and then writes its +name. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cd : +.IP "\fICDPATH\fP" 10 +A +-separated +list of pathnames that refer to directories. The +.IR cd +utility shall use this list in its attempt to change the directory, as +described in the DESCRIPTION. An empty string in place of a directory +pathname represents the current directory. If +.IR CDPATH +is not set, it shall be treated as if it were an empty string. +.IP "\fIHOME\fP" 10 +The name of the directory, used when no +.IR directory +operand is specified. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIOLDPWD\fP" 10 +A pathname of the previous working directory, used by +.IR cd +.BR \(mi . +.IP "\fIPWD\fP" 10 +This variable shall be set as specified in the DESCRIPTION. If an +application sets or unsets the value of +.IR PWD , +the behavior of +.IR cd +is unspecified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If a non-empty directory name from +.IR CDPATH +is used, or if +.IR cd +.BR \(mi +is used, an absolute pathname of the new working directory shall be +written to the standard output as follows: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fInew directory\fR> +.fi \fR +.P +.RE +.P +Otherwise, there shall be no output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The directory was successfully changed. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The working directory shall remain unchanged. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR cd +affects the current shell execution environment, it is always provided +as a shell regular built-in. If it is called in a subshell or separate +utility execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(cd /tmp) +nohup cd +find . \(miexec cd {} \e; +.fi \fR +.P +.RE +.P +it does not affect the working directory of the caller's environment. +.P +The user must have execute (search) permission in +.IR directory +in order to change to it. +.SH EXAMPLES +The following template can be used to perform processing in the directory +specified by +.IR location +and end up in the current working directory in use before the first +.IR cd +command was issued: +.sp +.RS 4 +.nf +\fB +cd \fIlocation\fP +if [ $? -ne 0 ] +then + print error message + exit 1 +fi +\&... do whatever is desired as long as the OLDPWD environment variable + is not modified +cd - +.fi \fR +.P +.RE +.SH RATIONALE +The use of the +.IR CDPATH +was introduced in the System V shell. Its use is analogous to the use +of the +.IR PATH +variable in the shell. The BSD C shell used a shell parameter +.IR cdpath +for this purpose. +.P +A common extension when +.IR HOME +is undefined is to get the login directory from the user database for +the invoking user. This does not occur on System V implementations. +.P +Some historical shells, such as the KornShell, took special actions +when the directory name contained a dot-dot component, selecting the +logical parent of the directory, rather than the actual parent +directory; that is, it moved up one level toward the +.BR '/' +in the pathname, remembering what the user typed, rather than +performing the equivalent of: +.sp +.RS 4 +.nf +\fB +chdir(".."); +.fi \fR +.P +.RE +.P +In such a shell, the following commands would not necessarily produce +equivalent output for all directories: +.sp +.RS 4 +.nf +\fB +cd .. && ls ls .. +.fi \fR +.P +.RE +.P +This behavior is now the default. It is not consistent with the +definition of dot-dot in most historical practice; that is, while this +behavior has been optionally available in the KornShell, other shells +have historically not supported this functionality. The logical +pathname is stored in the +.IR PWD +environment variable when the +.IR cd +utility completes and this value is used to construct the next +directory name if +.IR cd +is invoked with the +.BR \(miL +option. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "\fIpwd\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchdir\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cflow.1p b/man-pages-posix-2013-a/man1p/cflow.1p new file mode 100644 index 0000000..8301c72 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cflow.1p @@ -0,0 +1,278 @@ +'\" et +.TH CFLOW "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cflow +\(em generate a C-language flowgraph (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +cflow \fB[\fR\(mir\fB] [\fR\(mid \fInum\fB] [\fR\(miD \fIname\fB[\fR=\fIdef\fB]]\fR...\fB [\fR\(mii \fIincl\fB] [\fR\(miI \fIdir\fB]\fR... + \fB[\fR\(miU \fIdir\fB]\fR... \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR cflow +utility shall analyze a collection of object files or assembler, +C-language, +.IR lex , +or +.IR yacc +source files, and attempt to build a graph, written to standard output, +charting the external references. +.SH OPTIONS +The +.IR cflow +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of the +.BR \(miD , +.BR \(miI , +and +.BR \(miU +options (which are identical to their interpretation by +.IR c99 ) +is significant. +.P +The following options shall be supported: +.IP "\fB\(mid\ \fInum\fR" 10 +Indicate the depth at which the flowgraph is cut off. The application +shall ensure that the argument +.IR num +is a decimal integer. By default this is a very large number +(typically greater than 32\|000). Attempts to set the cut-off depth to +a non-positive integer shall be ignored. +.IP "\fB\(mii\ \fIincl\fR" 10 +Increase the number of included symbols. The +.IR incl +option-argument is one of the following characters: +.RS 10 +.IP "\fIx\fP" 6 +Include external and static data symbols. The default shall be to +include only functions in the flowgraph. +.IP "\fR_\fP" 6 +(Underscore) Include names that begin with an +. +The default shall be to exclude these functions (and data if +.BR "\(mii\ x" +is used). +.RE +.IP "\fB\(mir\fP" 10 +Reverse the caller:callee relationship, producing an inverted listing +showing the callers of each function. The listing shall also be sorted +in lexicographical order by callee. +.SH OPERANDS +The following operand is supported: +.IP "\fIfile\fR" 10 +The pathname of a file for which a graph is to be generated. +Filenames suffixed by +.BR .l +shall shall be taken to be +.IR lex +input, +.BR .y +as +.IR yacc +input, +.BR .c +as +.IR c99 +input, and +.BR .i +as the output of +.IR c99 +.BR \(miE . +Such files shall be processed as appropriate, determined by their +suffix. +.RS 10 +.P +Files suffixed by +.BR .s +(conventionally assembler source) may have more limited information +extracted from them. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +The input files shall be object files or assembler, C-language, +.IR lex , +or +.IR yacc +source files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cflow : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the ordering of the output when the +.BR \(mir +option is used. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The flowgraph written to standard output shall be formatted as follows: +.sp +.RS 4 +.nf +\fB +"%d %s:%s\en", <\fIreference number\fR>, <\fIglobal\fR>, <\fIdefinition\fR> +.fi \fR +.P +.RE +.P +Each line of output begins with a reference (that is, line) number, +followed by indentation of at least one column position per level. +This is followed by the name of the global, a +, +and its definition. Normally globals are only functions not defined as +an external or beginning with an +; +see the OPTIONS section for the +.BR \(mii +inclusion option. For information extracted from C-language source, the +definition consists of an abstract type declaration (for example, +.BR "char *" ) +and, delimited by angle brackets, the name of the source file and the +line number where the definition was found. Definitions extracted from +object files indicate the filename and location counter under which +the symbol appeared (for example, +.IR text ). +.P +Once a definition of a name has been written, subsequent references to +that name contain only the reference number of the line where the +definition can be found. For undefined references, only +.BR \(dq<\|>\(dq +shall be written. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Files produced by +.IR lex +and +.IR yacc +cause the reordering of line number declarations, and this can confuse +.IR cflow . +To obtain proper results, the input of +.IR yacc +or +.IR lex +must be directed to +.IR cflow . +.SH EXAMPLES +Given the following in +.BR file.c : +.sp +.RS 4 +.nf +\fB +int i; +int f(); +int g(); +int h(); +int +main() +{ + f(); + g(); + f(); +} +int +f() +{ + i = h(); +} +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +cflow \(mii x file.c +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +1 main: int(), +2 f: int(), +3 h: <> +4 i: int, +5 g: <> +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIlex\fR\^", +.IR "\fIyacc\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/chgrp.1p b/man-pages-posix-2013-a/man1p/chgrp.1p new file mode 100644 index 0000000..02b49bf --- /dev/null +++ b/man-pages-posix-2013-a/man1p/chgrp.1p @@ -0,0 +1,235 @@ +'\" et +.TH CHGRP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +chgrp +\(em change the file group ownership +.SH SYNOPSIS +.LP +.nf +chgrp \fB[\fR\(mih\fB] \fIgroup file\fR... +.P +chgrp \(miR \fB[\fR\(miH|\(miL|\(miP\fB] \fIgroup file\fR... +.fi +.SH DESCRIPTION +The +.IR chgrp +utility shall set the group ID of the file named by each +.IR file +operand to the group ID specified by the +.IR group +operand. +.P +For each +.IR file +operand, or, if the +.BR \(miR +option is used, each file encountered while walking the directory +trees specified by the +.IR file +operands, the +.IR chgrp +utility shall perform actions equivalent to the +\fIchown\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " *" 4 +The +.IR file +operand shall be used as the +.IR path +argument. +.IP " *" 4 +The user ID of the file shall be used as the +.IR owner +argument. +.IP " *" 4 +The specified group ID shall be used as the +.IR group +argument. +.P +Unless +.IR chgrp +is invoked by a process with appropriate privileges, the set-user-ID +and set-group-ID bits of a regular file shall be cleared upon successful +completion; the set-user-ID and set-group-ID bits of other file types +may be cleared. +.SH OPTIONS +The +.IR chgrp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mih\fP" 10 +For each +.IR file +operand that names a file of type symbolic link, +.IR chgrp +shall attempt to set the group ID of the symbolic link instead of the +file referenced by the symbolic link. +.IP "\fB\(miH\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link referencing a file of type +directory is specified on the command line, +.IR chgrp +shall change the group of the directory referenced by the symbolic link +and all files in the file hierarchy below it. +.IP "\fB\(miL\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link referencing a file of type +directory is specified on the command line or encountered during the +traversal of a file hierarchy, +.IR chgrp +shall change the group of the directory referenced by the symbolic link +and all files in the file hierarchy below it. +.IP "\fB\(miP\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link is specified on the command +line or encountered during the traversal of a file hierarchy, +.IR chgrp +shall change the group ID of the symbolic link. The +.IR chgrp +utility shall not follow the symbolic link to any other part of the +file hierarchy. +.IP "\fB\(miR\fP" 10 +Recursively change file group IDs. For each +.IR file +operand that names a directory, +.IR chgrp +shall change the group of the directory and all files in the +file hierarchy below it. Unless a +.BR \(miH , +.BR \(miL , +or +.BR \(miP +option is specified, it is unspecified which of these options will be +used as the default. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH , +.BR \(miL , +and +.BR \(miP +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIgroup\fR" 10 +A group name from the group database or a numeric group ID. Either +specifies a group ID to be given to each file named by one of the +.IR file +operands. If a numeric +.IR group +operand exists in the group database as a group name, the group ID +number associated with that group name is used as the group ID. +.IP "\fIfile\fR" 10 +A pathname of a file whose group ID is to be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR chgrp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Only the owner of a file or the user with appropriate privileges may +change the owner or group of a file. +.P +Some implementations restrict the use of +.IR chgrp +to a user with appropriate privileges when the +.IR group +specified is not the effective group ID or one of the supplementary +group IDs of the calling process. +.SH EXAMPLES +None. +.SH RATIONALE +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the number of errors +that occurred; this practice is unworkable since it can overflow the +range of valid exit status values. The standard developers chose to +mask these by specifying only 0 and >0 as exit values. +.P +The functionality of +.IR chgrp +is described substantially through references to +\fIchown\fR(). +In this way, there is no duplication of effort required for describing +the interactions of permissions, multiple groups, and so on. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIchown\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchown\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/chmod.1p b/man-pages-posix-2013-a/man1p/chmod.1p new file mode 100644 index 0000000..3fcee04 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/chmod.1p @@ -0,0 +1,679 @@ +'\" et +.TH CHMOD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +chmod +\(em change the file modes +.SH SYNOPSIS +.LP +.nf +chmod \fB[\fR\(miR\fB] \fImode file\fR... +.fi +.SH DESCRIPTION +The +.IR chmod +utility shall change any or all of the file mode bits of the file named +by each +.IR file +operand in the way specified by the +.IR mode +operand. +.P +It is implementation-defined whether and how the +.IR chmod +utility affects any alternate or additional file access control +mechanism (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions") +being used for the specified file. +.P +Only a process whose effective user ID matches the user ID of the file, +or a process with appropriate privileges, shall be permitted to +change the file mode bits of a file. +.P +Upon successfully changing the file mode bits of a file, the +.IR chmod +utility shall mark for update the last file status change timestamp +of the file. +.SH OPTIONS +The +.IR chmod +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miR\fP" 10 +Recursively change file mode bits. For each +.IR file +operand that names a directory, +.IR chmod +shall change the file mode bits of the directory and all files in the +file hierarchy below it. +.SH OPERANDS +The following operands shall be supported: +.IP "\fImode\fR" 10 +Represents the change to be made to the file mode bits of each +file named by one of the +.IR file +operands; see the EXTENDED DESCRIPTION section. +.IP "\fIfile\fR" 10 +A pathname of a file whose file mode bits shall be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR chmod : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The +.IR mode +operand shall be either a +.IR symbolic_mode +expression or a non-negative octal integer. The +.IR symbolic_mode +form is described by the grammar later in this section. +.P +Each +.BR clause +shall specify an operation to be performed on the current file mode +bits of each +.IR file . +The operations shall be performed on each +.IR file +in the order in which the +.BR clause s +are specified. +.P +The +.BR who +symbols +.BR u , +.BR g , +and +.BR o +shall specify the +.IR user , +.IR group , +and +.IR other +parts of the file mode bits, respectively. A +.BR who +consisting of the symbol +.BR a +shall be equivalent to +.BR ugo . +.P +The +.BR perm +symbols +.BR r , +.BR w , +and +.BR x +represent the +.IR read , +.IR write , +and +.IR execute /\c +.IR search +portions of file mode bits, respectively. The +.BR perm +symbol +.BR s +shall represent the +.IR "set-user-ID-on-execution" +(when +.BR who +contains or implies +.BR u ) +and +.IR "set-group-ID-on-execution" +(when +.BR who +contains or implies +.BR g ) +bits. +.P +The +.BR perm +symbol +.BR X +shall represent the execute/search portion of the file mode bits if the +file is a directory or if the current (unmodified) file mode bits have +at least one of the execute bits (S_IXUSR, S_IXGRP, or S_IXOTH) set. It +shall be ignored if the file is not a directory and none of the execute +bits are set in the current file mode bits. +.P +The +.BR permcopy +symbols +.BR u , +.BR g , +and +.BR o +shall represent the current permissions associated with the user, +group, and other parts of the file mode bits, respectively. For the +remainder of this section, +.BR perm +refers to the non-terminals +.BR perm +and +.BR permcopy +in the grammar. +.P +If multiple +.BR actionlist s +are grouped with a single +.BR wholist +in the grammar, each +.BR actionlist +shall be applied in the order specified with that +.BR wholist . +The +.IR op +symbols shall represent the operation performed, as follows: +.IP "\fR+\fP" 6 +If +.BR perm +is not specified, the +.BR '\(pl' +operation shall not change the file mode bits. +.RS 6 +.P +If +.BR who +is not specified, the file mode bits represented by +.BR perm +for the owner, group, and other permissions, except for those with +corresponding bits in the file mode creation mask of the invoking +process, shall be set. +.P +Otherwise, the file mode bits represented by the specified +.BR who +and +.BR perm +values shall be set. +.RE +.IP "\fR\(mi\fP" 6 +If +.BR perm +is not specified, the +.BR '\(mi' +operation shall not change the file mode bits. +.RS 6 +.P +If +.BR who +is not specified, the file mode bits represented by +.BR perm +for the owner, group, and other permissions, except for those with +corresponding bits in the file mode creation mask of the invoking +process, shall be cleared. +.P +Otherwise, the file mode bits represented by the specified +.BR who +and +.BR perm +values shall be cleared. +.RE +.IP "\fR=\fP" 6 +Clear the file mode bits specified by the +.BR who +value, or, if no +.BR who +value is specified, all of the file mode bits specified in this volume of POSIX.1\(hy2008. +.RS 6 +.P +If +.BR perm +is not specified, the +.BR '=' +operation shall make no further modifications to the file mode bits. +.P +If +.BR who +is not specified, the file mode bits represented by +.BR perm +for the owner, group, and other permissions, except for those with +corresponding bits in the file mode creation mask of the invoking +process, shall be set. +.P +Otherwise, the file mode bits represented by the specified +.BR who +and +.BR perm +values shall be set. +.RE +.P +When using the symbolic mode form on a regular file, it is +implementation-defined whether or not: +.IP " *" 4 +Requests to set the set-user-ID-on-execution or +set-group-ID-on-execution bit when all execute bits are currently clear +and none are being set are ignored. +.IP " *" 4 +Requests to clear all execute bits also clear the +set-user-ID-on-execution and set-group-ID-on-execution bits. +.IP " *" 4 +Requests to clear the set-user-ID-on-execution or +set-group-ID-on-execution bits when all execute bits are currently +clear are ignored. However, if the command +.IR ls +.BR \(mil +.IR file +writes an +.IR s +in the position indicating that the set-user-ID-on-execution or +set-group-ID-on-execution is set, the commands +.IR chmod +.BR u\(mis +.IR file +or +.IR chmod +.BR g\(mis +.IR file , +respectively, shall not be ignored. +.P +When using the symbolic mode form on other file types, it is +implementation-defined whether or not requests to set or clear the +set-user-ID-on-execution or set-group-ID-on-execution bits are +honored. +.P +If the +.BR who +symbol +.BR o +is used in conjunction with the +.BR perm +symbol +.BR s +with no other +.BR who +symbols being specified, the set-user-ID-on-execution and +set-group-ID-on-execution bits shall not be modified. It shall not be +an error to specify the +.BR who +symbol +.BR o +in conjunction with the +.BR perm +symbol +.BR s . +.P +The +.BR perm +symbol +.BR t +shall specify the S_ISVTX bit. When used with a file of type +directory, it can be used with the +.BR who +symbol +.BR a , +or with no +.BR who +symbol. It shall not be an error to specify a +.BR who +symbol of +.BR u , +.BR g , +or +.BR o +in conjunction with the +.BR perm +symbol +.BR t , +but the meaning of these combinations is unspecified. The effect when +using the +.BR perm +symbol +.BR t +with any file type other than directory is unspecified. +.P +For an octal integer +.IR mode +operand, the file mode bits shall be set absolutely. +.P +For each bit set in the octal number, the corresponding file permission +bit shown in the following table shall be set; all other file +permission bits shall be cleared. For regular files, for each bit set +in the octal number corresponding to the set-user-ID-on-execution or +the set-group-ID-on-execution, bits shown in the following table shall +be set; if these bits are not set in the octal number, they are +cleared. For other file types, it is implementation-defined whether +or not requests to set or clear the set-user-ID-on-execution or +set-group-ID-on-execution bits are honored. +.TS +center tab(@) box; +cB cB | cB cB | cB cB | cB cB +nB l | nB l | nB l | nB l. +Octal@Mode Bit@Octal@Mode Bit@Octal@Mode Bit@Octal@Mode Bit +_ +4000@S_ISUID@0400@S_IRUSR@0040@S_IRGRP@0004@S_IROTH +_ +2000@S_ISGID@0200@S_IWUSR@0020@S_IWGRP@0002@S_IWOTH +_ +1000@S_ISVTX@0100@S_IXUSR@0010@S_IXGRP@0001@S_IXOTH +.TE +.P +When bits are set in the octal number other than those listed in the +table above, the behavior is unspecified. +.SS "Grammar for chmod" +.P +The grammar and lexical conventions in this section describe the syntax +for the +.IR symbolic_mode +operand. The general conventions for this style of grammar are +described in +.IR "Section 1.3" ", " "Grammar Conventions". +A valid +.IR symbolic_mode +can be represented as the non-terminal symbol +.IR symbolic_mode +in the grammar. This formal syntax shall take precedence over the +preceding text syntax description. +.P +The lexical processing is based entirely on single characters. +Implementations need not allow + +characters within the single argument being processed. +.sp +.RS 4 +.nf +\fB +%start symbolic_mode +%% +.P +symbolic_mode : clause + | symbolic_mode ',' clause + ; +.P +clause : actionlist + | wholist actionlist + ; +.P +wholist : who + | wholist who + ; +.P +who : 'u' | 'g' | 'o' | 'a' + ; +.P +actionlist : action + | actionlist action + ; +.P +action : op + | op permlist + | op permcopy + ; +.P +permcopy : 'u' | 'g' | 'o' + ; +.P +op : '+' | '\(mi' | '=' + ; +.P +permlist : perm + | perm permlist + ; +.P +perm : 'r' | 'w' | 'x' | 'X' | 's' | 't' + ; +.fi \fR +.P +.RE +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Some implementations of the +.IR chmod +utility change the mode of a directory before the files in the +directory when performing a recursive (\c +.BR \(miR +option) change; others change the directory mode after the files in the +directory. If an application tries to remove read or search permission +for a file hierarchy, the removal attempt fails if the directory is +changed first; on the other hand, trying to re-enable permissions to a +restricted hierarchy fails if directories are changed last. Users +should not try to make a hierarchy inaccessible to themselves. +.P +Some implementations of +.IR chmod +never used the +.IR umask +of the process when changing modes; systems conformant with this volume of POSIX.1\(hy2008 +do so when +.BR who +is not specified. Note the difference between: +.sp +.RS 4 +.nf +\fB +chmod a\(miw file +.fi \fR +.P +.RE +.P +which removes all write permissions, and: +.sp +.RS 4 +.nf +\fB +chmod \(mi\|\(mi \(miw file +.fi \fR +.P +.RE +.P +which removes write permissions that would be allowed if +.BR file +was created with the same +.IR umask . +.P +Conforming applications should never assume that they know how the +set-user-ID and set-group-ID bits on directories are interpreted. +.SH EXAMPLES +.ad l +.TS +center tab(@) box; +cB | cB +l | lw(3i). +Mode@Results +_ +\fIa\fP+=@T{ +Equivalent to +.IR a +,\c +.IR a =; +clears all file mode bits. +T} +\fIgo\fP+\(miw@T{ +Equivalent to +.IR go +,\c +.IR go \(mi\c +.IR w ; +clears group and other write bits. +T} +\fIg\fR=\fIo\fR\(mi\fIw\fR@T{ +Equivalent to +.IR g =\c +.IR o ,\c +.IR g \(mi\c +.IR w ; +sets group bit to match other bits and then clears group write bit. +T} +\fIg\fR\(mi\fIr\fR+\fIw\fR@T{ +Equivalent to +.IR g \(mi\c +.IR r ,\c +.IR g +\c +.IR w ; +clears group read bit and sets group write bit. +T} +\fIuo\fR=\fIg\fR@T{ +Sets owner bits to match group bits and sets other bits to +match group bits. +T} +.TE +.ad b +.SH RATIONALE +The functionality of +.IR chmod +is described substantially through references to concepts defined in +the System Interfaces volume of POSIX.1\(hy2008. In this way, there is less duplication of effort required +for describing the interactions of permissions. However, the behavior +of this utility is not described in terms of the +\fIchmod\fR() +function from the System Interfaces volume of POSIX.1\(hy2008 because that specification requires certain +side-effects upon alternate file access control mechanisms that might +not be appropriate, depending on the implementation. +.P +Implementations that support mandatory file and record locking as +specified +by the 1984 /usr/group standard historically used the combination of set-group-ID bit set +and group execute bit clear to indicate mandatory locking. This +condition is usually set or cleared with the symbolic mode +.BR perm +symbol +.BR l +instead of the +.BR perm +symbols +.BR s +and +.BR x +so that the mandatory locking mode is not changed without explicit +indication that that was what the user intended. Therefore, the details +on how the implementation treats these conditions must be defined in +the documentation. This volume of POSIX.1\(hy2008 does not require mandatory locking (nor does +the System Interfaces volume of POSIX.1\(hy2008), but does allow it as an extension. However, this volume of POSIX.1\(hy2008 does +require that the +.IR ls +and +.IR chmod +utilities work consistently in this area. If +.IR ls +.BR \(mil +.IR file +indicates that the set-group-ID bit is set, +.IR chmod +.BR g\(mis +.IR file +must clear it (assuming appropriate privileges exist to change modes). +.P +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the number of errors +that occurred; this practice is unworkable since it can overflow the +range of valid exit status values. This problem is avoided here by +specifying only 0 and >0 as exit values. +.P +The System Interfaces volume of POSIX.1\(hy2008 indicates that implementation-defined restrictions may cause +the S_ISUID and S_ISGID bits to be ignored. This volume of POSIX.1\(hy2008 allows the +.IR chmod +utility to choose to modify these bits before calling +\fIchmod\fR() +(or some function providing equivalent capabilities) for non-regular +files. Among other things, this allows implementations that use the +set-user-ID and set-group-ID bits on directories to enable extended +features to +handle these extensions in an intelligent manner. +.P +The +.BR X +.BR perm +symbol was adopted from BSD-based systems because it provides commonly +desired functionality when doing recursive (\c +.BR \(miR +option) modifications. Similar functionality is not provided by the +.IR find +utility. Historical BSD versions of +.IR chmod , +however, only supported +.BR X +with +.IR op +; +it has been extended in this volume of POSIX.1\(hy2008 because it is also useful with +.IR op =. +(It has also been added for +.IR op \(mi +even though it duplicates +.BR x , +in this case, because it is intuitive and easier to explain.) +.P +The grammar was extended with the +.IR permcopy +non-terminal to allow historical-practice forms of symbolic modes like +.BR o =\c +.BR u +.BR \(mig +(that is, set the ``other'' permissions to the permissions of ``owner'' +minus the permissions of ``group''). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIls\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchmod\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/chown.1p b/man-pages-posix-2013-a/man1p/chown.1p new file mode 100644 index 0000000..4defb5f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/chown.1p @@ -0,0 +1,301 @@ +'\" et +.TH CHOWN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +chown +\(em change the file ownership +.SH SYNOPSIS +.LP +.nf +chown \fB[\fR\(mih\fB] \fIowner\fB[\fR:\fIgroup\fB] \fIfile\fR... +.P +chown \(miR \fB[\fR\(miH|\(miL|\(miP\fB] \fIowner\fB[\fR:\fIgroup\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR chown +utility shall set the user ID of the file named by each +.IR file +operand to the user ID specified by the +.IR owner +operand. +.P +For each +.IR file +operand, or, if the +.BR \(miR +option is used, each file encountered while walking the directory +trees specified by the +.IR file +operands, the +.IR chown +utility shall perform actions equivalent to the +\fIchown\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " 1." 4 +The +.IR file +operand shall be used as the +.IR path +argument. +.IP " 2." 4 +The user ID indicated by the +.IR owner +portion of the first operand shall be used as the +.IR owner +argument. +.IP " 3." 4 +If the +.IR group +portion of the first operand is given, the group ID indicated by it +shall be used as the +.IR group +argument; otherwise, the group ownership shall not be changed. +.P +Unless +.IR chown +is invoked by a process with appropriate privileges, the set-user-ID +and set-group-ID bits of a regular file shall be cleared upon +successful completion; the set-user-ID and set-group-ID bits of other +file types may be cleared. +.SH OPTIONS +The +.IR chown +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mih\fP" 10 +For each file operand that names a file of type symbolic link, +.IR chown +shall attempt to set the user ID of the symbolic link. If a group ID +was specified, for each file operand that names a file of +type symbolic link, +.IR chown +shall attempt to set the group ID of the symbolic link. +.IP "\fB\(miH\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link referencing a file of type +directory is specified on the command line, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +referenced by the symbolic link and all files in the file hierarchy +below it. +.IP "\fB\(miL\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link referencing a file of type +directory is specified on the command line or encountered during the +traversal of a file hierarchy, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +referenced by the symbolic link and all files in the file hierarchy +below it. +.IP "\fB\(miP\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link is specified on the command +line or encountered during the traversal of a file hierarchy, +.IR chown +shall change the owner ID (and group ID, if specified) of the symbolic +link. The +.IR chown +utility shall not follow the symbolic link to any other part of the +file hierarchy. +.IP "\fB\(miR\fP" 10 +Recursively change file user and group IDs. For each +.IR file +operand that names a directory, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +and all files in the file hierarchy below it. Unless a +.BR \(miH , +.BR \(miL , +or +.BR \(miP +option is specified, it is unspecified which of these options will be +used as the default. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH , +.BR \(miL , +and +.BR \(miP +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIowner\fB[\fR:\fIgroup\fB]\fR" 10 +A user ID and optional group ID to be assigned to +.IR file . +The +.IR owner +portion of this operand shall be a user name from the user database or +a numeric user ID. Either specifies a user ID which shall be given to +each file named by one of the +.IR file +operands. If a numeric +.IR owner +operand exists in the user database as a user name, the user ID number +associated with that user name shall be used as the user ID. Similarly, +if the +.IR group +portion of this operand is present, it shall be a group name from the +group database or a numeric group ID. Either specifies a group ID which +shall be given to each file. If a numeric group operand exists in the +group database as a group name, the group ID number associated with +that group name shall be used as the group ID. +.IP "\fIfile\fR" 10 +A pathname of a file whose user ID is to be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR chown : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Only the owner of a file or the user with appropriate privileges may +change the owner or group of a file. +.P +Some implementations restrict the use of +.IR chown +to a user with appropriate privileges. +.SH EXAMPLES +None. +.SH RATIONALE +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the number of errors +that occurred; this practice is unworkable since it can overflow the +range of valid exit status values. These are masked by specifying only +0 and >0 as exit values. +.P +The functionality of +.IR chown +is described substantially through references to functions in the +System Interfaces volume of POSIX.1\(hy2008. In this way, there is no duplication of effort required for +describing the interactions of permissions, multiple groups, and so +on. +.P +The 4.3 BSD method of specifying both owner and group was included in +\&this volume of POSIX.1\(hy2008 because: +.IP " *" 4 +There are cases where the desired end condition could not be achieved +using the +.IR chgrp +and +.IR chown +(that only changed the user ID) utilities. (If the current owner is not +a member of the desired group and the desired owner is not a member of +the current group, the +\fIchown\fR() +function could fail unless both owner and group are changed at the same +time.) +.IP " *" 4 +Even if they could be changed independently, in cases where both are +being changed, there is a 100% performance penalty caused by being +forced to invoke both utilities. +.P +The BSD syntax +.IR user [.\c +.IR group ] +was changed to +.IR user [:\c +.IR group ] +in this volume of POSIX.1\(hy2008 because the + +is a valid character in login names (as specified by the Base Definitions volume of POSIX.1\(hy2008, login +names consist of characters in the portable filename character set). The + +character was chosen as the replacement for the + +character because it would never be allowed as a character in a user +name or group name on historical implementations. +.P +The +.BR \(miR +option is considered by some observers as an undesirable departure from +the historical UNIX system tools approach; since a tool, +.IR find , +already exists to recurse over directories, there seemed to be no good +reason to require other tools to have to duplicate that functionality. +However, the +.BR \(miR +option was deemed an important user convenience, is far more efficient +than forking a separate process for each element of the directory +hierarchy, and is in widespread historical use. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchgrp\fR\^", +.IR "\fIchmod\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchown\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cksum.1p b/man-pages-posix-2013-a/man1p/cksum.1p new file mode 100644 index 0000000..718ec6a --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cksum.1p @@ -0,0 +1,373 @@ +'\" et +.TH CKSUM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cksum +\(em write file checksums and sizes +.SH SYNOPSIS +.LP +.nf +cksum \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cksum +utility shall calculate and write to standard output a cyclic +redundancy check (CRC) for each input file, and also write to standard +output the number of octets in each file. The CRC used is based on the +polynomial used for CRC error checking in the ISO/IEC\ 8802\(hy3:\|1996 standard (Ethernet). +.P +The encoding for the CRC checksum is defined by the generating +polynomial: +.sp +.RS 4 +.nf +\fB +\fIG\fR(\fIx\fR)=\fIx\fR\u\s-332\s+3\d+\fIx\fR\u\s-326\s+3\d+\fIx\fR\u\s-323\s+3\d+\fIx\fR\u\s-322\s+3\d+\fIx\fR\u\s-316\s+3\d+\fIx\fR\u\s-312\s+3\d+\fIx\fR\u\s-311\s+3\d+\fIx\fR\u\s-310\s+3\d+\fIx\fR\u\s-38\s+3\d+\fIx\fR\u\s-37\s+3\d+\fIx\fR\u\s-35\s+3\d+\fIx\fR\u\s-34\s+3\d+\fIx\fR\u\s-32\s+3\d+\fIx\fR+1 +.fi \fR +.P +.RE +.P +Mathematically, the CRC value corresponding to a given file shall be +defined by the following procedure: +.IP " 1." 4 +The +.IR n +bits to be evaluated are considered to be the coefficients of a mod 2 +polynomial +.IR M (\c +.IR x ) +of degree +.IR n \(mi1. +These +.IR n +bits are the bits from the file, with the most significant bit being +the most significant bit of the first octet of the file and the last +bit being the least significant bit of the last octet, padded with zero +bits (if necessary) to achieve an integral number of octets, followed +by one or more octets representing the length of the file as a binary +value, least significant octet first. The smallest number of octets +capable of representing this integer shall be used. +.IP " 2." 4 +.IR M (\c +.IR x ) +is multiplied by +.IR x \u\s-332\s+3\d +(that is, shifted left 32 bits) and divided by +.IR G (\c +.IR x ) +using mod 2 division, producing a remainder +.IR R (\c +.IR x ) +of degree \(<= 31. +.IP " 3." 4 +The coefficients of +.IR R (\c +.IR x ) +are considered to be a 32-bit sequence. +.IP " 4." 4 +The bit sequence is complemented and the result is the CRC. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be checked. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cksum : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +For each file processed successfully, the +.IR cksum +utility shall write in the following format: +.sp +.RS 4 +.nf +\fB +"%u %d %s\en", <\fIchecksum\fR>, <\fI# of octets\fR>, <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If no +.IR file +operand was specified, the pathname and its leading + +shall be omitted. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR cksum +utility is typically used to quickly compare a suspect file against a +trusted version of the same, such as to ensure that files transmitted +over noisy media arrive intact. However, this comparison cannot be +considered cryptographically secure. The chances of a damaged file +producing the same CRC as the original are small; deliberate deception +is difficult, but probably not impossible. +.P +Although input files to +.IR cksum +can be any type, the results need not be what would be expected on +character special device files or on file types not described by the +System Interfaces volume of POSIX.1\(hy2008. Since this volume of POSIX.1\(hy2008 does not specify the block size used when doing +input, checksums of character special files need not process all of the +data in those files. +.P +The algorithm is expressed in terms of a bitstream divided into octets. +If a file is transmitted between two systems and undergoes any data +transformation (such as changing little-endian byte ordering to +big-endian), identical CRC values cannot be expected. Implementations +performing such transformations may extend +.IR cksum +to handle such situations. +.SH EXAMPLES +None. +.SH RATIONALE +The following C-language program can be used as a model to describe the +algorithm. It assumes that a +.BR char +is one octet. It also assumes that the entire file is available for one +pass through the function. This was done for simplicity in +demonstrating the algorithm, rather than as an implementation model. +.sp +.RS 4 +.nf +\fB +static unsigned long crctab[] = { +0x00000000, +0x04c11db7, 0x09823b6e, 0x0d4326d9, 0x130476dc, 0x17c56b6b, +0x1a864db2, 0x1e475005, 0x2608edb8, 0x22c9f00f, 0x2f8ad6d6, +0x2b4bcb61, 0x350c9b64, 0x31cd86d3, 0x3c8ea00a, 0x384fbdbd, +0x4c11db70, 0x48d0c6c7, 0x4593e01e, 0x4152fda9, 0x5f15adac, +0x5bd4b01b, 0x569796c2, 0x52568b75, 0x6a1936c8, 0x6ed82b7f, +0x639b0da6, 0x675a1011, 0x791d4014, 0x7ddc5da3, 0x709f7b7a, +0x745e66cd, 0x9823b6e0, 0x9ce2ab57, 0x91a18d8e, 0x95609039, +0x8b27c03c, 0x8fe6dd8b, 0x82a5fb52, 0x8664e6e5, 0xbe2b5b58, +0xbaea46ef, 0xb7a96036, 0xb3687d81, 0xad2f2d84, 0xa9ee3033, +0xa4ad16ea, 0xa06c0b5d, 0xd4326d90, 0xd0f37027, 0xddb056fe, +0xd9714b49, 0xc7361b4c, 0xc3f706fb, 0xceb42022, 0xca753d95, +0xf23a8028, 0xf6fb9d9f, 0xfbb8bb46, 0xff79a6f1, 0xe13ef6f4, +0xe5ffeb43, 0xe8bccd9a, 0xec7dd02d, 0x34867077, 0x30476dc0, +0x3d044b19, 0x39c556ae, 0x278206ab, 0x23431b1c, 0x2e003dc5, +0x2ac12072, 0x128e9dcf, 0x164f8078, 0x1b0ca6a1, 0x1fcdbb16, +0x018aeb13, 0x054bf6a4, 0x0808d07d, 0x0cc9cdca, 0x7897ab07, +0x7c56b6b0, 0x71159069, 0x75d48dde, 0x6b93dddb, 0x6f52c06c, +0x6211e6b5, 0x66d0fb02, 0x5e9f46bf, 0x5a5e5b08, 0x571d7dd1, +0x53dc6066, 0x4d9b3063, 0x495a2dd4, 0x44190b0d, 0x40d816ba, +0xaca5c697, 0xa864db20, 0xa527fdf9, 0xa1e6e04e, 0xbfa1b04b, +0xbb60adfc, 0xb6238b25, 0xb2e29692, 0x8aad2b2f, 0x8e6c3698, +0x832f1041, 0x87ee0df6, 0x99a95df3, 0x9d684044, 0x902b669d, +0x94ea7b2a, 0xe0b41de7, 0xe4750050, 0xe9362689, 0xedf73b3e, +0xf3b06b3b, 0xf771768c, 0xfa325055, 0xfef34de2, 0xc6bcf05f, +0xc27dede8, 0xcf3ecb31, 0xcbffd686, 0xd5b88683, 0xd1799b34, +0xdc3abded, 0xd8fba05a, 0x690ce0ee, 0x6dcdfd59, 0x608edb80, +0x644fc637, 0x7a089632, 0x7ec98b85, 0x738aad5c, 0x774bb0eb, +0x4f040d56, 0x4bc510e1, 0x46863638, 0x42472b8f, 0x5c007b8a, +0x58c1663d, 0x558240e4, 0x51435d53, 0x251d3b9e, 0x21dc2629, +0x2c9f00f0, 0x285e1d47, 0x36194d42, 0x32d850f5, 0x3f9b762c, +0x3b5a6b9b, 0x0315d626, 0x07d4cb91, 0x0a97ed48, 0x0e56f0ff, +0x1011a0fa, 0x14d0bd4d, 0x19939b94, 0x1d528623, 0xf12f560e, +0xf5ee4bb9, 0xf8ad6d60, 0xfc6c70d7, 0xe22b20d2, 0xe6ea3d65, +0xeba91bbc, 0xef68060b, 0xd727bbb6, 0xd3e6a601, 0xdea580d8, +0xda649d6f, 0xc423cd6a, 0xc0e2d0dd, 0xcda1f604, 0xc960ebb3, +0xbd3e8d7e, 0xb9ff90c9, 0xb4bcb610, 0xb07daba7, 0xae3afba2, +0xaafbe615, 0xa7b8c0cc, 0xa379dd7b, 0x9b3660c6, 0x9ff77d71, +0x92b45ba8, 0x9675461f, 0x8832161a, 0x8cf30bad, 0x81b02d74, +0x857130c3, 0x5d8a9099, 0x594b8d2e, 0x5408abf7, 0x50c9b640, +0x4e8ee645, 0x4a4ffbf2, 0x470cdd2b, 0x43cdc09c, 0x7b827d21, +0x7f436096, 0x7200464f, 0x76c15bf8, 0x68860bfd, 0x6c47164a, +0x61043093, 0x65c52d24, 0x119b4be9, 0x155a565e, 0x18197087, +0x1cd86d30, 0x029f3d35, 0x065e2082, 0x0b1d065b, 0x0fdc1bec, +0x3793a651, 0x3352bbe6, 0x3e119d3f, 0x3ad08088, 0x2497d08d, +0x2056cd3a, 0x2d15ebe3, 0x29d4f654, 0xc5a92679, 0xc1683bce, +0xcc2b1d17, 0xc8ea00a0, 0xd6ad50a5, 0xd26c4d12, 0xdf2f6bcb, +0xdbee767c, 0xe3a1cbc1, 0xe760d676, 0xea23f0af, 0xeee2ed18, +0xf0a5bd1d, 0xf464a0aa, 0xf9278673, 0xfde69bc4, 0x89b8fd09, +0x8d79e0be, 0x803ac667, 0x84fbdbd0, 0x9abc8bd5, 0x9e7d9662, +0x933eb0bb, 0x97ffad0c, 0xafb010b1, 0xab710d06, 0xa6322bdf, +0xa2f33668, 0xbcb4666d, 0xb8757bda, 0xb5365d03, 0xb1f740b4 +}; +.P +unsigned long memcrc(const unsigned char *b, size_t n) +{ +/* Input arguments: + * const unsigned char* b == byte sequence to checksum + * size_t n == length of sequence + */ +.P + register size_t i; + register unsigned c, s = 0; +.P + for (i = n; i > 0; \(mi\|\(mii) { + c = *b++; + s = (s << 8) ^ crctab[(s >> 24) ^ c]; + } +.P + /* Extend with the length of the string. */ + while (n != 0) { + c = n & 0377; + n >>= 8; + s = (s << 8) ^ crctab[(s >> 24) ^ c]; + } +.P + return ~s; +} +.fi \fR +.P +.RE +.P +The historical practice of writing the number of ``blocks'' has been +changed to writing the number of octets, since the latter is not only +more useful, but also since historical implementations have not been +consistent in defining what a ``block'' meant. +.P +The algorithm used was selected to increase the operational robustness +of +.IR cksum . +Neither the System V nor BSD +.IR sum +algorithm was selected. Since each of these was different and each was +the default behavior on those systems, no realistic compromise was +available if either were selected\(emsome set of historical +applications would break. Therefore, the name was changed to +.IR cksum . +Although the historical +.IR sum +commands will probably continue to be provided for many years, programs +designed for portability across systems should use the new name. +.P +The algorithm selected is based on that used by the ISO/IEC\ 8802\(hy3:\|1996 standard (Ethernet) +for the frame check sequence field. The algorithm used does not match +the technical definition of a +.IR checksum ; +the term is used for historical reasons. The length of the file is +included in the CRC calculation because this parallels inclusion of a +length field by Ethernet in its CRC, but also because it guards against +inadvertent collisions between files that begin with different series +of zero octets. The chance that two different files produce identical +CRCs is much greater when their lengths are not considered. Keeping the +length and the checksum of the file itself separate would yield a +slightly more robust algorithm, but historical usage has always been +that a single number (the checksum as printed) represents the signature +of the file. It was decided that historical usage was the more +important consideration. +.P +Early proposals contained modifications to the Ethernet algorithm that +involved extracting table values whenever an intermediate result became +zero. This was demonstrated to be less robust than the current method +and mathematically difficult to describe or justify. +.P +The calculation used is identical to that given in pseudo-code in the +referenced Sarwate article. The pseudo-code rendition is: +.sp +.RS 4 +.nf +\fB +X <\(mi 0; Y <\(mi 0; +for i <\(mi m \(mi1 step \(mi1 until 0 do + begin + T <\(mi X(1) ^ A[i]; + X(1) <\(mi X(0); X(0) <\(mi Y(1); Y(1) <\(mi Y(0); Y(0) <\(mi 0; + comment: f[T] and f'[T] denote the T-th words in the + table f and f' ; + X <\(mi X ^ f[T]; Y <\(mi Y ^ f'[T]; + end +.fi \fR +.P +.RE +.P +The pseudo-code is reproduced exactly as given; however, note that in +the case of +.IR cksum , +.BR A[i] +represents a byte of the file, the words +.BR X +and +.BR Y +are treated as a single 32-bit value, and the tables +.BR f +and +.BR f' +are a single table containing 32-bit values. +.P +The referenced Sarwate article also discusses generating the table. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cmp.1p b/man-pages-posix-2013-a/man1p/cmp.1p new file mode 100644 index 0000000..1157d60 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cmp.1p @@ -0,0 +1,269 @@ +'\" et +.TH CMP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cmp +\(em compare two files +.SH SYNOPSIS +.LP +.nf +cmp \fB[\fR\(mil|\(mis\fB] \fIfile1 file2\fR +.fi +.SH DESCRIPTION +The +.IR cmp +utility shall compare two files. The +.IR cmp +utility shall write no output if the files are the same. Under default +options, if they differ, it shall write to standard output the byte and +line number at which the first difference occurred. Bytes and lines +shall be numbered beginning with 1. +.SH OPTIONS +The +.IR cmp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mil\fP" 10 +(Lowercase ell.) Write the byte number (decimal) and the differing +bytes (octal) for each difference. +.IP "\fB\(mis\fP" 10 +Write nothing for differing files; return exit status only. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fR" 10 +A pathname of the first file to be compared. If +.IR file1 +is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIfile2\fR" 10 +A pathname of the second file to be compared. If +.IR file2 +is +.BR '\(mi' , +the standard input shall be used. +.P +If both +.IR file1 +and +.IR file2 +refer to standard input or refer to the same FIFO special, block +special, or character special file, the results are undefined. +.SH STDIN +The standard input shall be used only if the +.IR file1 +or +.IR file2 +operand refers to standard input. See the INPUT FILES section. +.SH "INPUT FILES" +The input files can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cmp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +In the POSIX locale, results of the comparison shall be written to +standard output. When no options are used, the format shall be: +.sp +.RS 4 +.nf +\fB +"%s %s differ: char %d, line %d\en", \fIfile1\fR, \fIfile2\fR, + <\fIbyte number\fR>, <\fIline number\fR> +.fi \fR +.P +.RE +.P +When the +.BR \(mil +option is used, the format shall be: +.sp +.RS 4 +.nf +\fB +"%d %o %o\en", <\fIbyte number\fR>, <\fIdiffering byte\fR>, + <\fIdiffering byte\fR> +.fi \fR +.P +.RE +.P +for each byte that differs. The first <\fIdiffering\ byte\fP> number is +from +.IR file1 +while the second is from +.IR file2 . +In both cases, <\fIbyte\ number\fP> shall be relative to the beginning +of the file, beginning with 1. +.P +No output shall be written to standard output when the +.BR \(mis +option is used. +.SH STDERR +The standard error shall be used only for diagnostic messages. If the +.BR \(mil +option is used and +.IR file1 +and +.IR file2 +differ in length, or if the +.BR \(mis +option is not used and +.IR file1 +and +.IR file2 +are identical for the entire length of the shorter file, in the POSIX +locale the following diagnostic message shall be written: +.sp +.RS 4 +.nf +\fB +"cmp: EOF on %s%s\en", <\fIname of shorter file\fR>, <\fIadditional info\fR> +.fi \fR +.P +.RE +.P +The <\fIadditional\ info\fP> field shall either be null or a string +that starts with a + +and contains no + +characters. Some implementations report on the number of lines in +this case. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The files are identical. +.IP "\01" 6 +The files are different; this includes the case where one file is +identical to the first part of the other. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Although input files to +.IR cmp +can be any type, the results might not be what would be expected on +character special device files or on file types not described by the +System Interfaces volume of POSIX.1\(hy2008. Since this volume of POSIX.1\(hy2008 does not specify the block size used when doing +input, comparisons of character special files need not compare all of +the data in those files. +.P +For files which are not text files, line numbers simply reflect the +presence of a +, +without any implication that the file is organized into lines. +.SH EXAMPLES +None. +.SH RATIONALE +The global language in +.IR "Section 1.4" ", " "Utility Description Defaults" +indicates that using two mutually-exclusive options together produces +unspecified results. Some System V implementations consider the option +usage: +.sp +.RS 4 +.nf +\fB +cmp \(mil \(mis ... +.fi \fR +.P +.RE +.P +to be an error. They also treat: +.sp +.RS 4 +.nf +\fB +cmp \(mis \(mil ... +.fi \fR +.P +.RE +.P +as if no options were specified. Both of these behaviors are +considered bugs, but are allowed. +.P +The word +.BR char +in the standard output format comes from historical usage, even though +it is actually a byte number. When +.IR cmp +is supported in other locales, implementations are encouraged to use +the word +.IR byte +or its equivalent in another language. Users should not interpret this +difference to indicate that the functionality of the utility changed +between locales. +.P +Some implementations report on the number of lines in the +identical-but-shorter file case. This is allowed by the inclusion of +the <\fIadditional\ info\fP> fields in the output format. The +restriction on having a leading + +and no + +characters is to make parsing for the filename easier. It is recognized +that some filenames containing white-space characters make parsing +difficult anyway, but the restriction does aid programs used on systems +where the names are predominantly well behaved. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcomm\fR\^", +.IR "\fIdiff\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/colon.1p b/man-pages-posix-2013-a/man1p/colon.1p new file mode 100644 index 0000000..0a4d835 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/colon.1p @@ -0,0 +1,104 @@ +'\" et +.TH COLON "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +colon +\(em null utility +.SH SYNOPSIS +.LP +.nf +: \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +This utility shall only expand command +.IR argument s. +It is used when a command is needed, as in the +.BR then +condition of an +.BR if +command, but nothing is to be done by the command. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +: ${X=abc} +if false +then : +else echo $X +fi +\fBabc\fR +.fi +.P +As with any of the special built-ins, the null utility can also have +variable assignments and redirections associated with it, such as: +.sp +.RS 4 +.nf +\fB +x=y : > z +.fi \fR +.P +.RE +.P +which sets variable +.IR x +to the value +.IR y +(so that it persists after the null utility completes) and creates or +truncates file +.BR z . +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/comm.1p b/man-pages-posix-2013-a/man1p/comm.1p new file mode 100644 index 0000000..86f4ed8 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/comm.1p @@ -0,0 +1,287 @@ +'\" et +.TH COMM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +comm +\(em select or reject lines common to two files +.SH SYNOPSIS +.LP +.nf +comm \fB[\fR\(mi123\fB] \fIfile1 file2\fR +.fi +.SH DESCRIPTION +The +.IR comm +utility shall read +.IR file1 +and +.IR file2 , +which should be ordered in the current collating sequence, and produce +three text columns as output: lines only in +.IR file1 , +lines only in +.IR file2 , +and lines in both files. +.P +If the lines in both files are not ordered according to the collating +sequence of the current locale, the results are unspecified. +.SH OPTIONS +The +.IR comm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mi1\fP" 10 +Suppress the output column of lines unique to +.IR file1 . +.IP "\fB\(mi2\fP" 10 +Suppress the output column of lines unique to +.IR file2 . +.IP "\fB\(mi3\fP" 10 +Suppress the output column of lines duplicated in +.IR file1 +and +.IR file2 . +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fR" 10 +A pathname of the first file to be compared. If +.IR file1 +is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIfile2\fR" 10 +A pathname of the second file to be compared. If +.IR file2 +is +.BR '\(mi' , +the standard input shall be used. +.P +If both +.IR file1 +and +.IR file2 +refer to standard input or to the same FIFO special, block special, or +character special file, the results are undefined. +.SH STDIN +The standard input shall be used only if one of the +.IR file1 +or +.IR file2 +operands refers to standard input. See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR comm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the collating sequence +.IR comm +expects to have been used when the input files were sorted. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR comm +utility shall produce output depending on the options selected. If the +.BR \(mi1 , +.BR \(mi2 , +and +.BR \(mi3 +options are all selected, +.IR comm +shall write nothing to standard output. +.P +If the +.BR \(mi1 +option is not selected, lines contained only in +.IR file1 +shall be written using the format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIline in file1\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mi2 +option is not selected, lines contained only in +.IR file2 +are written using the format: +.sp +.RS 4 +.nf +\fB +"%s%s\en", <\fIlead\fR>, <\fIline in file2\fR> +.fi \fR +.P +.RE +.P +where the string <\fIlead\fP> is as follows: +.IP 10 +The +.BR \(mi1 +option is not selected. +.IP "null\ string" 10 +The +.BR \(mi1 +option is selected. +.P +If the +.BR \(mi3 +option is not selected, lines contained in both files shall be written +using the format: +.sp +.RS 4 +.nf +\fB +"%s%s\en", <\fIlead\fR>, <\fIline in both\fR> +.fi \fR +.P +.RE +.P +where the string <\fIlead\fP> is as follows: +.IP 10 +Neither the +.BR \(mi1 +nor the +.BR \(mi2 +option is selected. +.IP 10 +Exactly one of the +.BR \(mi1 +and +.BR \(mi2 +options is selected. +.IP "null\ string" 10 +Both the +.BR \(mi1 +and +.BR \(mi2 +options are selected. +.P +If the input files were ordered according to the collating sequence of +the current locale, the lines written shall be in the collating +sequence of the original lines. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were successfully output as specified. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If the input files are not properly presorted, the output of +.IR comm +might not be useful. +.SH EXAMPLES +If a file named +.BR xcu +contains a sorted list of the utilities in this volume of POSIX.1\(hy2008, a file named +.BR xpg3 +contains a sorted list of the utilities specified in the X/Open +Portability Guide, Issue 3, and a file named +.BR svid89 +contains a sorted list of the utilities in the System V Interface +Definition Third Edition: +.sp +.RS 4 +.nf +\fB +comm \(mi23 xcu xpg3 | comm \(mi23 \(mi svid89 +.fi \fR +.P +.RE +.P +would print a list of utilities in this volume of POSIX.1\(hy2008 not specified by either of the +other documents: +.sp +.RS 4 +.nf +\fB +comm \(mi12 xcu xpg3 | comm \(mi12 \(mi svid89 +.fi \fR +.P +.RE +.P +would print a list of utilities specified by all three documents, and: +.sp +.RS 4 +.nf +\fB +comm \(mi12 xpg3 svid89 | comm \(mi23 \(mi xcu +.fi \fR +.P +.RE +.P +would print a list of utilities specified by both XPG3 and the SVID, +but not specified in this volume of POSIX.1\(hy2008. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcmp\fR\^", +.IR "\fIdiff\fR\^", +.IR "\fIsort\fR\^", +.IR "\fIuniq\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/command.1p b/man-pages-posix-2013-a/man1p/command.1p new file mode 100644 index 0000000..c8683a2 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/command.1p @@ -0,0 +1,560 @@ +'\" et +.TH COMMAND "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +command +\(em execute a simple command +.SH SYNOPSIS +.LP +.nf +command \fB[\fR\(mip\fB] \fIcommand_name \fB[\fIargument\fR...\fB]\fR +.P +command \fB[\fR\(mip\fB][\fR\(miv|\(miV\fB] \fIcommand_name\fR +.fi +.SH DESCRIPTION +The +.IR command +utility shall cause the shell to treat the arguments as a simple +command, suppressing the shell function lookup that is described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +item 1b. +.P +If the +.IR command_name +is the same as the name of one of the special built-in utilities, the +special properties in the enumerated list at the beginning of +.IR "Section 2.14" ", " "Special Built-In Utilities" +shall not occur. In every other respect, if +.IR command_name +is not the name of a function, the effect of +.IR command +(with no options) shall be the same as omitting +.IR command . +.P +When the +.BR \(miv +or +.BR \(miV +option is used, the +.IR command +utility shall provide information concerning how a command name +is interpreted by the shell. +.SH OPTIONS +The +.IR command +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mip\fP" 10 +Perform the command search using a default value for +.IR PATH +that is guaranteed to find all of the standard utilities. +.IP "\fB\(miv\fP" 10 +Write a string to standard output that indicates the pathname or command +that will be used by the shell, in the current shell execution environment +(see +.IR "Section 2.12" ", " "Shell Execution Environment"), +to invoke +.IR command_name , +but do not invoke +.IR command_name . +.RS 10 +.IP " *" 4 +Utilities, regular built-in utilities, +.IR command_name s +including a + +character, and any implementation-defined functions that are found +using the +.IR PATH +variable (as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution"), +shall be written as absolute pathnames. +.IP " *" 4 +Shell functions, special built-in utilities, regular built-in utilities +not associated with a +.IR PATH +search, and shell reserved words shall be written as just their names. +.IP " *" 4 +An alias shall be written as a command line that represents its alias +definition. +.IP " *" 4 +Otherwise, no output shall be written and the exit status shall reflect +that the name was not found. +.RE +.IP "\fB\(miV\fP" 10 +Write a string to standard output that indicates how the name given in the +.IR command_name +operand will be interpreted by the shell, in the current shell +execution environment (see +.IR "Section 2.12" ", " "Shell Execution Environment"), +but do not invoke +.IR command_name . +Although the format of this string is unspecified, it shall indicate in +which of the following categories +.IR command_name +falls and shall include the information stated: +.RS 10 +.IP " *" 4 +Utilities, regular built-in utilities, and any implementation-defined +functions that are found using the +.IR PATH +variable (as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution"), +shall be identified as such and include the absolute pathname in the +string. +.IP " *" 4 +Other shell functions shall be identified as functions. +.IP " *" 4 +Aliases shall be identified as aliases and their definitions +included in the string. +.IP " *" 4 +Special built-in utilities shall be identified as special built-in +utilities. +.IP " *" 4 +Regular built-in utilities not associated with a +.IR PATH +search shall be identified as regular built-in utilities. (The term +``regular'' need not be used.) +.IP " *" 4 +Shell reserved words shall be identified as reserved words. +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIargument\fR" 10 +One of the strings treated as an argument to +.IR command_name . +.IP "\fIcommand_name\fR" 10 +.br +The name of a utility or a special built-in utility. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR command : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path used during the command search described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +except as described under the +.BR \(mip +option. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(miv +option is specified, standard output shall be formatted as: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname or command\fR> +.fi \fR +.P +.RE +.P +When the +.BR \(miV +option is specified, standard output shall be formatted as: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIunspecified\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +When the +.BR \(miv +or +.BR \(miV +options are specified, the following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +The +.IR command_name +could not be found or an error occurred. +.P +Otherwise, the following exit values shall be returned: +.IP 126 6 +The utility specified by +.IR command_name +was found but could not be invoked. +.IP 127 6 +An error occurred in the +.IR command +utility or the utility specified by +.IR command_name +could not be found. +.P +Otherwise, the exit status of +.IR command +shall be that of the simple command specified by the arguments to +.IR command . +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The order for command search allows functions to override regular +built-ins and path searches. This utility is necessary to allow +functions that have the same name as a utility to call the utility +(instead of a recursive call to the function). +.P +The system default path is available using +.IR getconf ; +however, since +.IR getconf +may need to have the +.IR PATH +set up before it can be called itself, the following can be used: +.sp +.RS 4 +.nf +\fB +command \(mip getconf PATH +.fi \fR +.P +.RE +.P +There are some advantages to suppressing the special characteristics of +special built-ins on occasion. For example: +.sp +.RS 4 +.nf +\fB +command exec > \fIunwritable-file\fR +.fi \fR +.P +.RE +.P +does not cause a non-interactive script to abort, so that the output +status can be checked by the script. +.P +The +.IR command , +.IR env , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.P +Since the +.BR \(miv +and +.BR \(miV +options of +.IR command +produce output in relation to the current shell execution environment, +.IR command +is generally provided as a shell regular built-in. If it is called in a +subshell or separate utility execution environment, such as one of the +following: +.sp +.RS 4 +.nf +\fB +(PATH=foo command \(miv) + nohup command \(miv +.fi \fR +.P +.RE +.P +it does not necessarily produce correct results. For example, when +called with +.IR nohup +or an +.IR exec +function, in a separate utility execution environment, most +implementations are not able to identify aliases, functions, or special +built-ins. +.P +Two types of regular built-ins could be encountered on a system and +these are described separately by +.IR command . +The description of command search in +.IR "Section 2.9.1.1" ", " "Command Search and Execution" +allows for a standard utility to be implemented as a regular built-in +as long as it is found in the appropriate place in a +.IR PATH +search. So, for example, +.IR command +.BR \(miv +.IR true +might yield +.BR /bin/true +or some similar pathname. Other implementation-defined utilities that +are not defined by this volume of POSIX.1\(hy2008 might exist only as built-ins and have no +pathname associated with them. These produce output identified as +(regular) built-ins. Applications encountering these are not able to +count on +.IR exec ing +them, using them with +.IR nohup , +overriding them with a different +.IR PATH , +and so on. +.SH EXAMPLES +.IP " 1." 4 +Make a version of +.IR cd +that always prints out the new working directory exactly once: +.RS 4 +.sp +.RS 4 +.nf +\fB +cd() { + command cd "$@" >/dev/null + pwd +} +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Start off a ``secure shell script'' in which the script avoids +being spoofed by its parent: +.RS 4 +.sp +.RS 4 +.nf +\fB +IFS=' +\&' +# The preceding value should be . +# Set IFS to its default value. +.P +\eunalias \(mia +# Unset all possible aliases. +# Note that unalias is escaped to prevent an alias +# being used for unalias. +.P +unset \(mif command +# Ensure command is not a user function. +.P +PATH="$(command \(mip getconf PATH):$PATH" +# Put on a reliable PATH prefix. +.P +# ... +.fi \fR +.P +.RE +.P +At this point, given correct permissions on the directories called by +.IR PATH , +the script has the ability to ensure that any utility it calls is the +intended one. It is being very cautious because it assumes that +implementation extensions may be present that would allow user +functions to exist when it is invoked; this capability is not specified +by this volume of POSIX.1\(hy2008, but it is not prohibited as an extension. For example, the +.IR ENV +variable precedes the invocation of the script with a user start-up +script. Such a script could define functions to spoof the application. +.RE +.SH RATIONALE +Since +.IR command +is a regular built-in utility it is always found prior to the +.IR PATH +search. +.P +There is nothing in the description of +.IR command +that implies the command line is parsed any differently from that of +any other simple command. For example: +.sp +.RS 4 +.nf +\fB +command a | b ; c +.fi \fR +.P +.RE +.P +is not parsed in any special way that causes +.BR '|' +or +.BR ';' +to be treated other than a pipe operator or + +or that prevents function lookup on +.BR b +or +.BR c . +.P +The +.IR command +utility is somewhat similar to the Eighth Edition shell +.IR builtin +command, but since +.IR command +also goes to the file system to search for utilities, the name +.IR builtin +would not be intuitive. +.P +The +.IR command +utility is most likely to be provided as a regular built-in. It is not +listed as a special built-in +for the following reasons: +.IP " *" 4 +The removal of exportable functions made the special precedence of a +special built-in unnecessary. +.IP " *" 4 +A special built-in has special properties (see +.IR "Section 2.14" ", " "Special Built-In Utilities") +that were inappropriate for invoking other utilities. For example, two +commands such as: +.RS 4 +.sp +.RS 4 +.nf +\fB +date > \fIunwritable-file\fR +.P +command date > \fIunwritable-file\fR +.fi \fR +.P +.RE +.P +would have entirely different results; in a non-interactive script, the +former would continue to execute the next command, the latter would +abort. Introducing this semantic difference along with suppressing +functions was seen to be non-intuitive. +.RE +.P +The +.BR \(mip +option is present because it is useful to be able to ensure a safe path +search that finds all the standard utilities. This search might not be +identical to the one that occurs through one of the +.IR exec +functions (as defined in the System Interfaces volume of POSIX.1\(hy2008) when +.IR PATH +is unset. At the very least, this feature is required to allow the +script to access the correct version of +.IR getconf +so that the value of the default path can be accurately retrieved. +.P +The +.IR command +.BR \(miv +and +.BR \(miV +options were added to satisfy requirements from users that are +currently accomplished by three different historical utilities: +.IR type +in the System V shell, +.IR whence +in the KornShell, and +.IR which +in the C shell. Since there is no historical agreement on how and what +to accomplish here, the POSIX +.IR command +utility was enhanced and the historical utilities were left unmodified. +The C shell +.IR which +merely conducts a path search. The KornShell +.IR whence +is more elaborate\(emin addition to the categories required by POSIX, +it also reports on tracked aliases, exported aliases, and undefined +functions. +.P +The output format of +.BR \(miV +was left mostly unspecified because human users are its only audience. +Applications should not be written to care about this information; they +can use the output of +.BR \(miv +to differentiate between various types of commands, but the additional +information that may be emitted by the more verbose +.BR \(miV +is not needed and should not be arbitrarily constrained in its +verbosity or localization for application parsing reasons. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIsh\fR\^", +.IR "\fItype\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/compress.1p b/man-pages-posix-2013-a/man1p/compress.1p new file mode 100644 index 0000000..8ade608 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/compress.1p @@ -0,0 +1,258 @@ +'\" et +.TH COMPRESS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +compress +\(em compress data +.SH SYNOPSIS +.LP +.nf +compress \fB[\fR\(mifv\fB] [\fR\(mib \fIbits\fB] [\fIfile\fR...\fB]\fR +.P +compress \fB[\fR\(micfv\fB] [\fR\(mib \fIbits\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR compress +utility shall attempt to reduce the size of the named files by using +adaptive Lempel-Ziv coding algorithm. +.TP 10 +.BR Note: +Lempel-Ziv is US Patent 4464650, issued to William Eastman, Abraham +Lempel, Jacob Ziv, Martin Cohn on August 7th, 1984, and assigned to +Sperry Corporation. +.RS 10 +.P +Lempel-Ziv-Welch compression is covered by US Patent 4558302, issued to +Terry A. Welch on December 10th, 1985, and assigned to Sperry +Corporation. +.RE +.P +On systems not supporting adaptive Lempel-Ziv coding algorithm, the +input files shall not be changed and an error value greater than two +shall be returned. Except when the output is to the standard output, +each file shall be replaced by one with the extension +.BR .Z . +If the invoking process has appropriate privileges, the ownership, +modes, access time, and modification time of the original file are +preserved. If appending the +.BR .Z +to the filename would make the name exceed +{NAME_MAX} +bytes, the command shall fail. If no files are specified, the standard +input shall be compressed to the standard output. +.SH OPTIONS +The +.IR compress +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mib\ \fIbits\fR" 10 +Specify the maximum number of bits to use in a code. For a conforming +application, the +.IR bits +argument shall be: +.RS 10 +.sp +.RS 4 +.nf +\fB +9 <= \fIbits\fP <= 14 +.fi \fR +.P +.RE +.P +The implementation may allow +.IR bits +values of greater than 14. The default is 14, 15, or 16. +.RE +.IP "\fB\(mic\fP" 10 +Cause +.IR compress +to write to the standard output; the input file is not changed, and no +.BR .Z +files are created. +.IP "\fB\(mif\fP" 10 +Force compression of +.IR file , +even if it does not actually reduce the size of the file, or if the +corresponding +.IR file \c +.BR .Z +file already exists. If the +.BR \(mif +option is not given, and the process is not running in the background, +the user is prompted as to whether an existing +.IR file \c +.BR .Z +file should be overwritten. If the response is affirmative, the existing +file will be overwritten. +.IP "\fB\(miv\fP" 10 +Write the percentage reduction of each file to standard error. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be compressed. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +If +.IR file +operands are specified, the input files contain the data to be +compressed. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR compress : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of text +data as characters (for example, single-byte as opposed to multi-byte +characters in arguments), the behavior of character classes used in the +extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages, +prompts, and the output from the +.BR \(miv +option written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +or if the +.BR \(mic +option is specified, the standard output contains the compressed +output. +.SH STDERR +The standard error shall be used only for diagnostic and prompt +messages and the output from +.BR \(miv . +.SH "OUTPUT FILES" +The output files shall contain the compressed output. The format of +compressed files is unspecified and interchange of such files between +implementations (including access via unspecified file sharing +mechanisms) is not required by POSIX.1\(hy2008. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP "\01" 6 +An error occurred. +.IP "\02" 6 +One or more files were not compressed because they would have increased +in size (and the +.BR \(mif +option was not specified). +.IP >2 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The input file shall remain unmodified. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The amount of compression obtained depends on the size of the input, +the number of +.IR bits +per code, and the distribution of common substrings. Typically, text +such as source code or English is reduced by 50\(hy60%. Compression is +generally much better than that achieved by Huffman coding +or adaptive Huffman coding (\c +.IR compact ), +and takes less time to compute. +.P +Although +.IR compress +strictly follows the default actions upon receipt of a signal or when +an error occurs, some unexpected results may occur. In some +implementations it is likely that a partially compressed file is left +in place, alongside its uncompressed input file. Since the general +operation of +.IR compress +is to delete the uncompressed file only after the +.BR .Z +file has been successfully filled, an application should always +carefully check the exit status of +.IR compress +before arbitrarily deleting files that have like-named neighbors with +.BR .Z +suffixes. +.P +The limit of 14 on the +.IR bits +option-argument is to achieve portability to all systems (within the +restrictions imposed by the lack of an explicit published file +format). Some implementations based on 16-bit architectures cannot +support 15 or 16-bit uncompression. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIuncompress\fR\^", +.IR "\fIzcat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/continue.1p b/man-pages-posix-2013-a/man1p/continue.1p new file mode 100644 index 0000000..c2cead3 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/continue.1p @@ -0,0 +1,112 @@ +'\" et +.TH CONTINUE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +continue +\(em continue for, while, or until loop +.SH SYNOPSIS +.LP +.nf +continue \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The +.IR continue +utility shall return to the top of the smallest enclosing +.BR for , +.BR while , +or +.BR until +loop, or to the top of the +.IR n th +enclosing loop, if +.IR n +is specified. This involves repeating the condition list of a +.BR while +or +.BR until +loop or performing the next assignment of a +.BR for +loop, and re-executing the loop if appropriate. +.P +The value of +.IR n +is a decimal integer greater than or equal to 1. The default shall be +equivalent to +.IR n =1. +If +.IR n +is greater than the number of enclosing loops, the outermost enclosing +loop shall be used. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.IP "\00" 6 +Successful completion. +.IP >0 6 +The +.IR n +value was not an unsigned decimal integer greater than or equal to 1. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +for i in * +do + if test \(mid "$i" + then continue + fi + printf '"%s" is not a directory.\en' "$i" +done +.fi +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cp.1p b/man-pages-posix-2013-a/man1p/cp.1p new file mode 100644 index 0000000..66193ad --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cp.1p @@ -0,0 +1,806 @@ +'\" et +.TH CP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cp +\(em copy files +.SH SYNOPSIS +.LP +.nf +cp \fB[\fR\(miPfip\fB] \fIsource_file target_file\fR +.P +cp \fB[\fR\(miPfip\fB] \fIsource_file\fR... \fItarget\fR +.P +cp \(miR \fB[\fR\(miH|\(miL|\(miP\fB] [\fR\(mifip\fB] \fIsource_file\fR... \fItarget\fR +.fi +.SH DESCRIPTION +The first synopsis form is denoted by two operands, neither of which +are existing files of type directory. The +.IR cp +utility shall copy the contents of +.IR source_file +(or, if +.IR source_file +is a file of type symbolic link, the contents of the file referenced by +.IR source_file ) +to the destination path named by +.IR target_file. +.P +The second synopsis form is denoted by two or more operands where the +.BR \(miR +option is not specified and the first synopsis form is not +applicable. It shall be an error if any +.IR source_file +is a file of type directory, if +.IR target +does not exist, or if +.IR target +does not name a directory. The +.IR cp +utility shall copy the contents of each +.IR source_file +(or, if +.IR source_file +is a file of type symbolic link, the contents of the file referenced by +.IR source_file ) +to the destination path named by the concatenation of +.IR target , +a single + +character if +.IR target +did not end in a +, +and the last component of +.IR source_file . +.P +The third synopsis form is denoted by two or more operands where the +.BR \(miR +option is specified. The +.IR cp +utility shall copy each file in the file hierarchy rooted in each +.IR source_file +to a destination path named as follows: +.IP " *" 4 +If +.IR target +exists and names an existing directory, the name of the corresponding +destination path for each file in the file hierarchy shall be the +concatenation of +.IR target , +a single + +character if +.IR target +did not end in a +, +and the pathname of the file relative to the directory containing +.IR source_file . +.IP " *" 4 +If +.IR target +does not exist and two operands are specified, the name of the +corresponding destination path for +.IR source_file +shall be +.IR target ; +the name of the corresponding destination path for all other files in +the file hierarchy shall be the concatenation of +.IR target , +a + +character, and the pathname of the file relative to +.IR source_file . +.P +It shall be an error if +.IR target +does not exist and more than two operands are specified, or if +.IR target +exists and does not name a directory. +.P +In the following description, the term +.IR dest_file +refers to the file named by the destination path. The term +.IR source_file +refers to the file that is being copied, whether specified as an +operand or a file in a file hierarchy rooted in a +.IR source_file +operand. If +.IR source_file +is a file of type symbolic link: +.IP " *" 4 +If the +.BR \(miR +option was not specified, +.IR cp +shall take actions based on the type and contents of the file referenced +by the symbolic link, and not by the symbolic link itself, unless the +.BR \(miP +option was specified. +.IP " *" 4 +If the +.BR \(miR +option was specified: +.RS 4 +.IP -- 4 +If none of the options +.BR \(miH , +.BR \(miL , +nor +.BR \(miP +were specified, it is unspecified which of +.BR \(miH , +.BR \(miL , +or +.BR \(miP +will be used as a default. +.IP -- 4 +If the +.BR \(miH +option was specified, +.IR cp +shall take actions based on the type and contents of the +file referenced by any symbolic link specified as a +.IR source_file +operand. +.IP -- 4 +If the +.BR \(miL +option was specified, +.IR cp +shall take actions based on the type and contents of the +file referenced by any symbolic link specified as a +.IR source_file +operand or any symbolic links encountered during traversal of a +file hierarchy. +.IP -- 4 +If the +.BR \(miP +option was specified, +.IR cp +shall copy any symbolic link specified as a +.IR source_file +operand and any symbolic links encountered during traversal of a +file hierarchy, and shall not follow any symbolic links. +.RE +.P +For each +.IR source_file , +the following steps shall be taken: +.IP " 1." 4 +If +.IR source_file +references the same file as +.IR dest_file , +.IR cp +may write a diagnostic message to standard error; it shall do nothing +more with +.IR source_file +and shall go on to any remaining files. +.IP " 2." 4 +If +.IR source_file +is of type directory, the following steps shall be taken: +.RS 4 +.IP " a." 4 +If the +.BR \(miR +option was not specified, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.IP " b." 4 +If +.IR source_file +was not specified as an operand and +.IR source_file +is dot or dot-dot, +.IR cp +shall do nothing more with +.IR source_file +and go on to any remaining files. +.IP " c." 4 +If +.IR dest_file +exists and it is a file type not specified by the System Interfaces volume of POSIX.1\(hy2008, the behavior +is implementation-defined. +.IP " d." 4 +If +.IR dest_file +exists and it is not of type directory, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file +or any files below +.IR source_file +in the file hierarchy, and go on to any remaining files. +.IP " e." 4 +If the directory +.IR dest_file +does not exist, it shall be created with file permission bits set to +the same value as those of +.IR source_file , +modified by the file creation mask of the user if the +.BR \(mip +option was not specified, and then bitwise-inclusively OR'ed with +S_IRWXU. If +.IR dest_file +cannot be created, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. It is unspecified if +.IR cp +attempts to copy files in the file hierarchy rooted in +.IR source_file . +.IP " f." 4 +The files in the directory +.IR source_file +shall be copied to the directory +.IR dest_file , +taking the four steps (1 to 4) listed here with the files as +.IR source_file s. +.IP " g." 4 +If +.IR dest_file +was created, its file permission bits shall be changed (if necessary) +to be the same as those of +.IR source_file , +modified by the file creation mask of the user if the +.BR \(mip +option was not specified. +.IP " h." 4 +The +.IR cp +utility shall do nothing more with +.IR source_file +and go on to any remaining files. +.RE +.IP " 3." 4 +If +.IR source_file +is of type regular file, the following steps shall be taken: +.RS 4 +.IP " a." 4 +The behavior is unspecified if +.IR dest_file +exists and was written by a previous step. Otherwise, if +.IR dest_file +exists, the following steps shall be taken: +.RS 4 +.IP " i." 5 +If the +.BR \(mii +option is in effect, the +.IR cp +utility shall write a prompt to the standard error and read a line from +the standard input. If the response is not affirmative, +.IR cp +shall do nothing more with +.IR source_file +and go on to any remaining files. +.IP ii. 5 +A file descriptor for +.IR dest_file +shall be obtained by performing actions equivalent to the +\fIopen\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called using +.IR dest_file +as the +.IR path +argument, and the bitwise-inclusive OR of O_WRONLY and O_TRUNC as the +.IR oflag +argument. +.IP iii. 5 +If the attempt to obtain a file descriptor fails and the +.BR \(mif +option is in effect, +.IR cp +shall attempt to remove the file by performing actions equivalent to +the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called using +.IR dest_file +as the +.IR path +argument. If this attempt succeeds, +.IR cp +shall continue with step 3b. +.RE +.IP " b." 4 +If +.IR dest_file +does not exist, a file descriptor shall be obtained by performing +actions equivalent to the +\fIopen\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called using +.IR dest_file +as the +.IR path +argument, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as the +.IR oflag +argument. The file permission bits of +.IR source_file +shall be the +.IR mode +argument. +.IP " c." 4 +If the attempt to obtain a file descriptor fails, +.IR cp +shall write a diagnostic message to standard error, do nothing more with +.IR source_file , +and go on to any remaining files. +.IP " d." 4 +The contents of +.IR source_file +shall be written to the file descriptor. Any write errors shall cause +.IR cp +to write a diagnostic message to standard error and continue to step +3e. +.IP " e." 4 +The file descriptor shall be closed. +.IP " f." 4 +The +.IR cp +utility shall do nothing more with +.IR source_file . +If a write error occurred in step 3d, it is unspecified if +.IR cp +continues with any remaining files. If no write error occurred in step +3d, +.IR cp +shall go on to any remaining files. +.RE +.IP " 4." 4 +Otherwise, the +.BR \(miR +option was specified, and the following steps shall be taken: +.RS 4 +.IP " a." 4 +The +.IR dest_file +shall be created with the same file type as +.IR source_file . +.IP " b." 4 +If +.IR source_file +is a file of type FIFO, the file permission bits shall be the same as +those of +.IR source_file, +modified by the file creation mask of the user if the +.BR \(mip +option was not specified. Otherwise, the permissions, owner ID, and +group ID of +.IR dest_file +are implementation-defined. +.RS 4 +.P +If this creation fails for any reason, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.RE +.IP " c." 4 +If +.IR source_file +is a file of type symbolic link, and the options require the symbolic +link itself to be acted upon, the pathname contained in +.IR dest_file +shall be the same as the pathname contained in +.IR source_file . +.RS 4 +.P +If this fails for any reason, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.RE +.RE +.P +If the implementation provides additional or alternate access control +mechanisms (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions"), +their effect on copies of files is implementation-defined. +.SH OPTIONS +The +.IR cp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\fP" 10 +If a file descriptor for a destination file cannot be obtained, as +described in step 3.a.ii., attempt to unlink the destination file and +proceed. +.IP "\fB\(miH\fP" 10 +Take actions based on the type and contents of the file referenced by +any symbolic link specified as a +.IR source_file +operand. +.IP "\fB\(mii\fP" 10 +Write a prompt to standard error before copying to any existing +non-directory destination file. If the response from the standard input +is affirmative, the copy shall be attempted; otherwise, it shall not. +.IP "\fB\(miL\fP" 10 +Take actions based on the type and contents of the file referenced by +any symbolic link specified as a +.IR source_file +operand or any symbolic links encountered during traversal of a +file hierarchy. +.IP "\fB\(miP\fP" 10 +Take actions on any symbolic link specified as a +.IR source_file +operand or any symbolic link encountered during traversal of a +file hierarchy. +.IP "\fB\(mip\fP" 10 +Duplicate the following characteristics of each source file in the +corresponding destination file: +.RS 10 +.IP " 1." 4 +The time of last data modification and time of last access. If this +duplication fails for any reason, +.IR cp +shall write a diagnostic message to standard error. +.IP " 2." 4 +The user ID and group ID. If this duplication fails for any reason, it +is unspecified whether +.IR cp +writes a diagnostic message to standard error. +.IP " 3." 4 +The file permission bits and the S_ISUID and S_ISGID bits. Other, +implementation-defined, bits may be duplicated as well. If this +duplication fails for any reason, +.IR cp +shall write a diagnostic message to standard error. +.P +If the user ID or the group ID cannot be duplicated, the file +permission bits S_ISUID and S_ISGID shall be cleared. If these bits are +present in the source file but are not duplicated in the destination +file, it is unspecified whether +.IR cp +writes a diagnostic message to standard error. +.P +The order in which the preceding characteristics are duplicated is +unspecified. The +.IR dest_file +shall not be deleted if these characteristics cannot be preserved. +.RE +.IP "\fB\(miR\fR" 10 +Copy file hierarchies. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH , +.BR \(miL , +and +.BR \(miP +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIsource_file\fR" 10 +A pathname of a file to be copied. If a +.IR source_file +operand is +.BR '\(mi' , +it shall refer to a file named +.BR \(mi ; +implementations shall not treat it as meaning standard input. +.IP "\fItarget_file\fR" 10 +A pathname of an existing or nonexistent file, used for the output when +a single file is copied. If a +.IR target_file +operand is +.BR '\(mi' , +it shall refer to a file named +.BR \(mi ; +implementations shall not treat it as meaning standard output. +.IP "\fItarget\fR" 10 +A pathname of a directory to contain the copied files. +.SH STDIN +The standard input shall be used to read an input line in response to +each prompt specified in the STDERR section. Otherwise, the standard +input shall not be used. +.SH "INPUT FILES" +The input files specified as operands may be of any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +A prompt shall be written to standard error under the conditions +specified in the DESCRIPTION section. The prompt shall contain the +destination pathname, but its format is otherwise unspecified. +Otherwise, the standard error shall be used only for diagnostic +messages. +.SH "OUTPUT FILES" +The output files may be of any type. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All files were copied successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If +.IR cp +is prematurely terminated by a signal or error, files or file +hierarchies may be only partially copied and files and directories may +have incorrect permissions or access and modification times. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The set-user-ID and set-group-ID bits are explicitly cleared when files +are created. This is to prevent users from creating programs that are +set-user-ID or set-group-ID to them when copying files or to make +set-user-ID or set-group-ID files accessible to new groups of users. +For example, if a file is set-user-ID and the copy has a different +group ID than the source, a new group of users has execute permission +to a set-user-ID program than did previously. In particular, this is a +problem for superusers copying users' trees. +.SH EXAMPLES +None. +.SH RATIONALE +The +.BR \(mii +option exists on BSD systems, giving applications and users a way to +avoid accidentally removing files when copying. Although the 4.3 BSD +version does not prompt if the standard input is not a terminal, the +standard developers decided that use of +.BR \(mii +is a request for interaction, so when the destination path exists, the +utility takes instructions from whatever responds on standard input. +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because +implementations may desire more descriptive prompts than those used on +historical implementations. Therefore, an application using the +.BR \(mii +option relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.P +The +.BR \(mip +option is historical practice on BSD systems, duplicating the time of +last data modification and time of last access. This volume of POSIX.1\(hy2008 extends it to +preserve the user and group IDs, as well as the file permissions. This +requirement has obvious problems in that the directories are almost +certainly modified after being copied. This volume of POSIX.1\(hy2008 requires that the +modification times be preserved. The statement that the order in which +the characteristics are duplicated is unspecified is to permit +implementations to provide the maximum amount of security for the user. +Implementations should take into account the obvious security issues +involved in setting the owner, group, and mode in the wrong order or +creating files with an owner, group, or mode different from the final +value. +.P +It is unspecified whether +.IR cp +writes diagnostic messages when the user and group IDs cannot be set +due to the widespread practice of users using +.BR \(mip +to duplicate some portion of the file characteristics, indifferent to +the duplication of others. Historic implementations only write +diagnostic messages on errors other than +.BR [EPERM] . +.P +Earlier versions of this standard included support for the +.BR \(mir +option to copy file hierarchies. The +.BR \(mir +option is historical practice on BSD and BSD-derived systems. This +option is no longer specified by POSIX.1\(hy2008 but may be present +in some implementations. The +.BR \(miR +option was added as a close synonym to the +.BR \(mir +option, selected for consistency with all other options in this volume of POSIX.1\(hy2008 that +do recursive directory descent. +.P +The difference between +.BR \(miR +and the removed +.BR \(mir +option is in the treatment by +.IR cp +of file types other than regular and directory. It was +implementation-defined how the +.BR \(mi +option treated special files to allow both historical implementations +and those that chose to support +.BR \(mir +with the same abilities as +.BR \(miR +defined by this volume of POSIX.1\(hy2008. The original +.BR \(mir +flag, for historic reasons, did not handle special files any differently +from regular files, but always read the file and copied its contents. This +had obvious problems in the presence of special file types; for example, +character devices, FIFOs, and sockets. +.P +When a failure occurs during the copying of a file hierarchy, +.IR cp +is required to attempt to copy files that are on the same level in the +hierarchy or above the file where the failure occurred. It is +unspecified if +.IR cp +shall attempt to copy files below the file where the failure occurred +(which cannot succeed in any case). +.P +Permissions, owners, and groups of created special file types have been +deliberately left as implementation-defined. This is to allow systems +to satisfy special requirements (for example, allowing users to create +character special devices, but requiring them to be owned by a certain +group). In general, it is strongly suggested that the permissions, +owner, and group be the same as if the user had run the historical +.IR mknod , +.IR ln , +or other utility to create the file. It is also probable that +additional privileges are required to create block, character, or +other implementation-defined special file types. +.P +Additionally, the +.BR \(mip +option explicitly requires that all set-user-ID +and set-group-ID permissions be +discarded if any of the owner or group IDs cannot be set. This is to +keep users from unintentionally giving away special privilege when +copying programs. +.P +When creating regular files, historical versions of +.IR cp +use the mode of the source file as modified by the file mode creation +mask. Other choices would have been to use the mode of the source file +unmodified by the creation mask or to use the same mode as would be +given to a new file created by the user (plus the execution bits of the +source file) and then modify it by the file mode creation mask. In the +absence of any strong reason to change historic practice, it was in +large part retained. +.P +When creating directories, historical versions of +.IR cp +use the mode of the source directory, plus read, write, and search bits +for the owner, as modified by the file mode creation mask. This is done +so that +.IR cp +can copy trees where the user has read permission, but the owner does +not. A side-effect is that if the file creation mask denies the owner +permissions, +.IR cp +fails. Also, once the copy is done, historical versions of +.IR cp +set the permissions on the created directory to be the same as the +source directory, unmodified by the file creation mask. +.P +This behavior has been modified so that +.IR cp +is always able to create the contents of the directory, regardless of +the file creation mask. After the copy is done, the permissions are set +to be the same as the source directory, as modified by the file +creation mask. This latter change from historical behavior is to +prevent users from accidentally creating directories with permissions +beyond those they would normally set and for consistency with the +behavior of +.IR cp +in creating files. +.P +It is not a requirement that +.IR cp +detect attempts to copy a file to itself; however, implementations are +strongly encouraged to do so. Historical implementations have detected +the attempt in most cases. +.P +There are two methods of copying subtrees in this volume of POSIX.1\(hy2008. The other method is +described as part of the +.IR pax +utility (see +.IR "\fIpax\fR\^"). +Both methods are historical practice. The +.IR cp +utility provides a simpler, more intuitive interface, while +.IR pax +offers a finer granularity of control. Each provides additional +functionality to the other; in particular, +.IR pax +maintains the hard-link structure of the hierarchy, while +.IR cp +does not. It is the intention of the standard developers that the +results be similar (using appropriate option combinations in both +utilities). The results are not required to be identical; there seemed +insufficient gain to applications to balance the difficulty of +implementations having to guarantee that the results would be exactly +identical. +.P +The wording allowing +.IR cp +to copy a directory to implementation-defined file types not +specified by the System Interfaces volume of POSIX.1\(hy2008 is provided so that implementations supporting +symbolic links are not required to prohibit copying directories to +symbolic links. Other extensions to the System Interfaces volume of POSIX.1\(hy2008 file types may need to +use this loophole as well. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImv\fR\^", +.IR "\fIfind\fR\^", +.IR "\fIln\fR\^", +.IR "\fIpax\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIopen\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/crontab.1p b/man-pages-posix-2013-a/man1p/crontab.1p new file mode 100644 index 0000000..6a0d791 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/crontab.1p @@ -0,0 +1,360 @@ +'\" et +.TH CRONTAB "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +crontab +\(em schedule periodic background work +.SH SYNOPSIS +.LP +.nf +crontab \fB[\fIfile\fB]\fR +.P +crontab \fB[\fR\(mie\||\(mil|\(mir\fB]\fR +.fi +.SH DESCRIPTION +The +.IR crontab +utility shall create, replace, +or edit a user's crontab entry; +a crontab entry is a list of commands and the times at which they +shall be executed. The new crontab entry can be input by specifying +.IR file +or input from standard input if no +.IR file +operand is specified, +or by using an editor, if +.BR \(mie +is specified. +.P +Upon execution of a command from a crontab entry, the implementation +shall supply a default environment, defining at least the following +environment variables: +.IP "\fIHOME\fP" 10 +A pathname of the user's home directory. +.IP "\fILOGNAME\fP" 10 +The user's login name. +.IP "\fIPATH\fP" 10 +A string representing a search path guaranteed to find all of the +standard utilities. +.IP "\fISHELL\fP" 10 +A pathname of the command interpreter. When +.IR crontab +is invoked as specified by this volume of POSIX.1\(hy2008, the value shall be a pathname for +.IR sh . +.P +The values of these variables when +.IR crontab +is invoked as specified by this volume of POSIX.1\(hy2008 shall not affect the default +values provided when the scheduled command is run. +.P +If standard output and standard error are not redirected by commands +executed from the crontab entry, any generated output or errors shall +be mailed, via an implementation-defined method, to the user. +.P +Users shall be permitted to use +.IR crontab +if their names appear in the file +.BR cron.allow +which is located in an implementation-defined directory. +If that file does not exist, the file +.BR cron.deny , +which is located in an implementation-defined directory, +shall be checked to determine whether the user shall be denied access to +.IR crontab . +If neither file exists, only a process with appropriate privileges shall be +allowed to submit a job. If only +.BR cron.deny +exists and is empty, global usage shall be permitted. The +.BR cron.allow +and +.BR cron.deny +files shall consist of one user name per line. +.SH OPTIONS +The +.IR crontab +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mie\fP" 10 +Edit a copy of the invoking user's crontab entry, or create an empty +entry to edit if the crontab entry does not exist. When editing is +complete, the entry shall be installed as the user's crontab entry. +.IP "\fB\(mil\fP" 10 +(The letter ell.) List the invoking user's crontab entry. +.IP "\fB\(mir\fP" 10 +Remove the invoking user's crontab entry. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a file that contains specifications, in the format +defined in the INPUT FILES section, for crontab entries. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +In the POSIX locale, the user or application shall ensure that a +crontab entry is a text file consisting of lines of six fields each. +The fields shall be separated by + +characters. The first five fields shall be integer patterns that specify +the following: +.IP " 1." 4 +Minute [0,59] +.IP " 2." 4 +Hour [0,23] +.IP " 3." 4 +Day of the month [1,31] +.IP " 4." 4 +Month of the year [1,12] +.IP " 5." 4 +Day of the week ([0,6] with 0=Sunday) +.P +Each of these patterns can be either an + +(meaning all valid values), an element, or a list of elements separated by + +characters. An element shall be either a number or two numbers separated +by a + +(meaning an inclusive range). The specification of days can be made by +two fields (day of the month and day of the week). If month, day of +month, and day of week are all + +characters, every day shall be matched. If either the month or day of +month is specified as an element or list, but the day of week is an +, +the month and day of month fields shall specify the days that match. If +both month and day of month are specified as an +, +but day of week is an element or list, then only the specified days of the +week match. Finally, if either the month or day of month is specified as +an element or list, and the day of week is also specified as an element +or list, then any day matching either the month and day of month, or +the day of week, shall be matched. +.P +The sixth field of a line in a crontab entry is a string that shall be +executed by +.IR sh +at the specified times. A + +character in this field shall be translated to a +. +Any character preceded by a + +(including the +.BR '%' ) +shall cause that character to be treated literally. Only the first line +(up to a +.BR '%' +or end-of-line) of the command field shall be executed by the command +interpreter. The other lines shall be made available to the command as +standard input. +.P +Blank lines and those whose first non-\c + +is +.BR '#' +shall be ignored. +.P +The text files +.BR cron.allow +and +.BR cron.deny , +which are located in an implementation-defined directory, +shall contain zero or more user names, one per line, of users who are, +respectively, authorized or denied access to the service underlying the +.IR crontab +utility. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR crontab : +.IP "\fIEDITOR\fP" 10 +Determine the editor to be invoked when the +.BR \(mie +option is specified. The default editor shall be +.IR vi . +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mil +option is specified, the crontab entry shall be written to the standard +output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The user's crontab entry is not submitted, removed, +edited, +or listed. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The format of the crontab entry shown here is guaranteed only for the +POSIX locale. Other cultures may be supported with substantially +different interfaces, although implementations are encouraged to +provide comparable levels of functionality. +.P +The default settings of the +.IR HOME , +.IR LOGNAME , +.IR PATH , +and +.IR SHELL +variables that are given to the scheduled job are not affected by the +settings of those variables when +.IR crontab +is run; as stated, they are defaults. The text about ``invoked as +specified by this volume of POSIX.1\(hy2008'' means that the implementation may provide +extensions that allow these variables to be affected at runtime, but +that the user has to take explicit action in order to access the +extension, such as give a new option flag or modify the format of the +crontab entry. +.P +A typical user error is to type only +.IR crontab ; +this causes the system to wait for the new crontab entry on standard +input. If end-of-file is typed (generally \(hyD), the crontab +entry is replaced by an empty file. In this case, the user should type +the interrupt character, which prevents the crontab entry from being +replaced. +.SH EXAMPLES +.IP " 1." 4 +Clean up +.BR core +files every weekday morning at 3:15 am: +.RS 4 +.sp +.RS 4 +.nf +\fB +15 3 * * 1-5 find "$HOME" \(miname core \(miexec rm \(mif {} + 2>/dev/null +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Mail a birthday greeting: +.RS 4 +.sp +.RS 4 +.nf +\fB +0 12 14 2 * mailx john%Happy Birthday!%Time for lunch. +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +As an example of specifying the two types of days: +.RS 4 +.sp +.RS 4 +.nf +\fB +0 0 1,15 * 1 +.fi \fR +.P +.RE +.P +would run a command on the first and fifteenth of each month, as well +as on every Monday. To specify days by only one field, the other field +should be set to +.BR '*' ; +for example: +.sp +.RS 4 +.nf +\fB +0 0 * * 1 +.fi \fR +.P +.RE +.P +would run a command only on Mondays. +.RE +.SH RATIONALE +All references to a +.IR cron +daemon and to +.IR cron +.IR files +have been omitted. Although historical implementations have used this +arrangement, there is no reason to limit future implementations. +.P +This description of +.IR crontab +is designed to support only users with normal privileges. The format of +the input is based on the System V +.IR crontab ; +however, there is no requirement here that the actual system database +used by the +.IR cron +daemon (or a similar mechanism) use this format internally. For +example, systems derived from BSD are likely to have an additional +field appended that indicates the user identity to be used when the job +is submitted. +.P +The +.BR \(mie +option was adopted from the SVID as a user convenience, although it +does not exist in all historical implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/csplit.1p b/man-pages-posix-2013-a/man1p/csplit.1p new file mode 100644 index 0000000..6c36dbc --- /dev/null +++ b/man-pages-posix-2013-a/man1p/csplit.1p @@ -0,0 +1,315 @@ +'\" et +.TH CSPLIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +csplit +\(em split files based on context +.SH SYNOPSIS +.LP +.nf +csplit \fB[\fR\(miks\fB] [\fR\(mif \fIprefix\fB] [\fR\(min \fInumber\fB] \fIfile arg\fR... +.fi +.SH DESCRIPTION +The +.IR csplit +utility shall read the file named by the +.IR file +operand, write all or part of that file into other files as directed +by the +.IR arg +operands, and write the sizes of the files. +.SH OPTIONS +The +.IR csplit +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\ \fIprefix\fR" 10 +Name the created files +.IR prefix \c +.BR 00 , +.IR prefix \c +.BR 01 , +\&.\|.\|., +.IR prefixn . +The default is +.BR xx00 +\&.\|.\|. +.BR xx \c +.IR n . +If the +.IR prefix +argument would create a filename exceeding +{NAME_MAX} +bytes, an error shall result, +.IR csplit +shall exit with a diagnostic message, and no files shall be created. +.IP "\fB\(mik\fP" 10 +Leave previously created files intact. By default, +.IR csplit +shall remove created files if an error occurs. +.IP "\fB\(min\ \fInumber\fR" 10 +Use +.IR number +decimal digits to form filenames for the file pieces. The default +shall be 2. +.IP "\fB\(mis\fP" 10 +Suppress the output of file size messages. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a text file to be split. If +.IR file +is +.BR '\(mi' , +the standard input shall be used. +.P +Each +.IR arg +operand can be one of the following: +.IP "/\fIrexp\fR/\fB[\fIoffset\fB]\fR" 10 +.br +A file shall be created using the content of the lines from the current +line up to, but not including, the line that results from the +evaluation of the regular expression with +.IR offset , +if any, applied. The regular expression +.IR rexp +shall follow the rules for basic regular expressions described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +The application shall use the sequence +.BR \(dq\e/\(dq +to specify a + +character within the +.IR rexp . +The optional offset shall be a positive or negative integer value +representing a number of lines. A positive integer value can be +preceded by +.BR '\(pl' . +If the selection of lines from an +.IR offset +expression of this type would create a file with zero lines, or one +with greater than the number of lines left in the input file, the +results are unspecified. After the section is created, the current line +shall be set to the line that results from the evaluation of the +regular expression with any offset applied. If the current line is the +first line in the file and a regular expression operation has not yet +been performed, the pattern match of +.IR rexp +shall be applied from the current line to the end of the file. +Otherwise, the pattern match of +.IR rexp +shall be applied from the line following the current line to the end of +the file. +.IP "%\fIrexp\fR%\fB[\fIoffset\fB]\fR" 10 +.br +Equivalent to /\fIrexp\fR/\fB[\fIoffset\fB]\fR, except that no +file shall be created for the selected section of the input file. The +application shall use the sequence +.BR \(dq\e%\(dq +to specify a + +character within the +.IR rexp . +.IP "\fIline_no\fR" 10 +Create a file from the current line up to (but not including) the line +number +.IR line_no . +Lines in the file shall be numbered starting at one. The current line +becomes +.IR line_no . +.IP "{\fInum\fR}" 10 +Repeat operand. This operand can follow any of the operands described +previously. If it follows a +.IR rexp +type operand, that operand shall be applied +.IR num +more times. If it follows a +.IR line_no +operand, the file shall be split every +.IR line_no +lines, +.IR num +times, from that point. +.P +An error shall be reported if an operand does not reference a line +between the current position and the end of the file. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR csplit : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +If the +.BR \(mik +option is specified, created files shall be retained. Otherwise, the +default action occurs. +.SH STDOUT +Unless the +.BR \(mis +option is used, the standard output shall consist of one line per +file created, with a format as follows: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIfile size in bytes\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files shall contain portions of the original input file; +otherwise, unchanged. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +By default, created files shall be removed if an error occurs. When the +.BR \(mik +option is specified, created files shall not be removed if an error +occurs. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +This example creates four files, +.BR cobol00 +\&.\|.\|. +.BR cobol03 : +.RS 4 +.sp +.RS 4 +.nf +\fB +csplit \(mif cobol file '/procedure division/' /par5./ /par16./ +.fi \fR +.P +.RE +.P +After editing the split files, they can be recombined as follows: +.sp +.RS 4 +.nf +\fB +cat cobol0[0\(mi3] > file +.fi \fR +.P +.RE +.P +Note that this example overwrites the original file. +.RE +.IP " 2." 4 +This example would split the file after the first 99 lines, and every +100 lines thereafter, up to 9\|999 lines; this is because lines in the +file are numbered from 1 rather than zero, for historical reasons: +.RS 4 +.sp +.RS 4 +.nf +\fB +csplit \(mik file 100 {99} +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Assuming that +.BR prog.c +follows the C-language coding convention of ending routines with a +.BR '}' +at the beginning of the line, this example creates a file containing +each separate C routine (up to 21) in +.BR prog.c : +.RS 4 +.sp +.RS 4 +.nf +\fB +csplit \(mik prog.c '%main(%' '/^}/+1' {20} +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.BR \(min +option was added to extend the range of filenames that could be +handled. +.P +Consideration was given to adding a +.BR \(mia +flag to use the alphabetic filename generation used by the historical +.IR split +utility, but the functionality added by the +.BR \(min +option was deemed to make alphabetic naming unnecessary. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^", +.IR "\fIsplit\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ctags.1p b/man-pages-posix-2013-a/man1p/ctags.1p new file mode 100644 index 0000000..aa190b1 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ctags.1p @@ -0,0 +1,477 @@ +'\" et +.TH CTAGS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctags +\(em create a tags file (\fBDEVELOPMENT\fR, \fBFORTRAN\fR) +.SH SYNOPSIS +.LP +.nf +ctags \fB[\fR\(mia\fB] [\fR\(mif \fItagsfile\fB] \fIpathname\fR... +.P +ctags \(mix \fIpathname\fR... +.fi +.SH DESCRIPTION +The +.IR ctags +utility shall be provided on systems that support the the Software +Development Utilities option, and either or both of the C-Language +Development Utilities option and FORTRAN Development Utilities option. On +other systems, it is optional. +.P +The +.IR ctags +utility shall write a +.IR tagsfile +or an index of objects from C-language or FORTRAN source files +specified by the +.IR pathname +operands. The +.IR tagsfile +shall list the locators of language-specific objects within the source +files. A locator consists of a name, pathname, and either a search +pattern +or a line number that can be used in searching for the object +definition. The objects that shall be recognized are specified in the +EXTENDED DESCRIPTION section. +.SH OPTIONS +The +.IR ctags +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Append to +.IR tagsfile . +.IP "\fB\(mif\ \fItagsfile\fR" 10 +Write the object locator lists into +.IR tagsfile +instead of the default file named +.BR tags +in the current directory. +.IP "\fB\(mix\fP" 10 +Produce a list of object names, the line number, and filename in which +each is defined, as well as the text of that line, and write this to +the standard output. A +.IR tagsfile +shall not be created when +.BR \(mix +is specified. +.SH OPERANDS +The following +.IR pathname +operands are supported: +.IP "\fIfile\fB.c\fR" 10 +Files with basenames ending with the +.BR .c +suffix shall be treated as C-language source code. Such files that are +not valid input to +.IR c99 +produce unspecified results. +.IP "\fIfile\fB.h\fR" 10 +Files with basenames ending with the +.BR .h +suffix shall be treated as C-language source code. Such files that are +not valid input to +.IR c99 +produce unspecified results. +.IP "\fIfile\fB.f\fR" 10 +Files with basenames ending with the +.BR .f +suffix shall be treated as FORTRAN-language source code. Such files +that are not valid input to +.IR fort77 +produce unspecified results. +.P +The handling of other files is implementation-defined. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files containing source code in the +language indicated by the operand filename suffixes. +.br +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ctags : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the order in which output is sorted for the +.BR \(mix +option. The POSIX locale determines the order in which the +.IR tagsfile +is written. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). When processing +C-language source code, if the locale is not compatible with the C +locale described by the ISO\ C standard, the results are unspecified. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The list of object name information produced by the +.BR \(mix +option shall be written to standard output in the following format: +.sp +.RS 4 +.nf +\fB +"%s %d %s %s", <\fIobject-name\fR>, <\fIline-number\fR>, <\fIfilename\fR>, <\fItext\fR> +.fi \fR +.P +.RE +.P +where <\fItext\fP> is the text of line <\fIline-number\fP> of file +<\fIfilename\fP>. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +When the +.BR \(mix +option is not specified, the format of the output file shall be: +.sp +.RS 4 +.nf +\fB +"%s\et%s\et/%s/\en", <\fIidentifier\fR>, <\fIfilename\fR>, <\fIpattern\fR> +.fi \fR +.P +.RE +.P +where <\fIpattern\fP> is a search pattern that could be used by an +editor to find the defining instance of <\fIidentifier\fP> in +<\fIfilename\fP> (where +.IR "defining instance" +is indicated by the declarations listed in the EXTENDED DESCRIPTION). +.P +An optional + +(\c +.BR '^' ) +can be added as a prefix to <\fIpattern\fP>, and an optional + +can be appended to <\fIpattern\fP> to indicate that the pattern is +anchored to the beginning (end) of a line of text. Any + +or + +characters in <\fIpattern\fP> shall be preceded by a + +character. The anchoring +, +, +and escaping + +characters shall not be considered part of the search pattern. All other +characters in the search pattern shall be considered literal characters. +.br +.P +An alternative format is: +.sp +.RS 4 +.nf +\fB +"%s\et%s\et?%s?\en", <\fIidentifier\fR>, <\fIfilename\fR>, <\fIpattern\fR> +.fi \fR +.P +.RE +.P +which is identical to the first format except that + +characters in <\fIpattern\fP> shall not be preceded by escaping + +characters, and + +characters in <\fIpattern\fP> shall be preceded by + +characters. +.P +A second alternative format is: +.sp +.RS 4 +.nf +\fB +"%s\et%s\et%d\en", <\fIidentifier\fR>, <\fIfilename\fR>, <\fIlineno\fR> +.fi \fR +.P +.RE +.P +where <\fIlineno\fP> is a decimal line number that could be used by an +editor to find <\fIidentifier\fP> in <\fIfilename\fP>. +.P +Neither alternative format shall be produced by +.IR ctags +when it is used as described by POSIX.1\(hy2008, but the standard utilities that +process tags files shall be able to process those formats as well as +the first format. +.P +In any of these formats, the file shall be sorted by identifier, based +on the collation sequence in the POSIX locale. +.SH "EXTENDED DESCRIPTION" +If the operand identifies C-language source, the +.IR ctags +utility shall attempt to produce an output line for each of the +following objects: +.IP " *" 4 +Function definitions +.IP " *" 4 +Type definitions +.IP " *" 4 +Macros with arguments +.P +It may also produce output for any of the following objects: +.IP " *" 4 +Function prototypes +.IP " *" 4 +Structures +.IP " *" 4 +Unions +.IP " *" 4 +Global variable definitions +.IP " *" 4 +Enumeration types +.IP " *" 4 +Macros without arguments +.IP " *" 4 +.BR #define +statements +.IP " *" 4 +.BR #line +statements +.P +Any +.BR #if +and +.BR #ifdef +statements shall produce no output. The tag +.BR main +is treated specially in C programs. The tag formed shall be created by +prefixing +.BR M +to the name of the file, with the trailing +.BR .c , +and leading pathname components (if any) removed. +.P +On systems that do not support the C-Language Development Utilities +option, +.IR ctags +produces unspecified results for C-language source code files. It should +write to standard error a message identifying this condition and cause +a non-zero exit status to be produced. +.P +If the operand identifies FORTRAN source, the +.IR ctags +utility shall produce an output line for each function definition. It +may also produce output for any of the following objects: +.IP " *" 4 +Subroutine definitions +.IP " *" 4 +COMMON statements +.IP " *" 4 +PARAMETER statements +.IP " *" 4 +DATA and BLOCK DATA statements +.IP " *" 4 +Statement numbers +.P +On systems that do not support the FORTRAN Development Utilities +option, +.IR ctags +produces unspecified results for FORTRAN source code files. It should +write to standard error a message identifying this condition and cause +a non-zero exit status to be produced. +.P +It is implementation-defined what other objects (including duplicate +identifiers) produce output. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The output with +.BR \(mix +is meant to be a simple index that can be written out as an off-line +readable function index. If the input files to +.IR ctags +(such as +.BR .c +files) were not created using the same locale as that in effect when +.IR ctags +.BR \(mix +is run, results might not be as expected. +.P +The description of C-language processing says ``attempts to'' because +the C language can be greatly confused, especially through the use of +.BR #define s, +and this utility would be of no use if the real C preprocessor were run +to identify them. The output from +.IR ctags +may be fooled and incorrect for various constructs. +.SH EXAMPLES +None. +.SH RATIONALE +The option list was significantly reduced from that provided by +historical implementations. The +.BR \(miF +option was omitted as redundant, since it is the default. The +.BR \(miB +option was omitted as being of very limited usefulness. The +.BR \(mit +option was omitted since the recognition of +.BR typedef s +is now required for C source files. The +.BR \(miu +option was omitted because the update function was judged to be not +only inefficient, but also rarely needed. +.P +An early proposal included a +.BR \(miw +option to suppress warning diagnostics. Since the types of such +diagnostics could not be described, the option was omitted as being not +useful. +.P +The text for +.IR LC_CTYPE +about compatibility with the C locale acknowledges that the ISO\ C standard +imposes requirements on the locale used to process C source. This could +easily be a superset of that known as ``the C locale'' by way of +implementation extensions, or one of a few alternative locales for +systems supporting different codesets. No statement is made for FORTRAN +because the ANSI\ X3.9\(hy1978 standard (FORTRAN 77) does not (yet) define a similar locale +concept. However, a general rule in this volume of POSIX.1\(hy2008 is that any time that locales +do not match (preparing a file for one locale and processing it in +another), the results are suspect. +.P +The collation sequence of the tags file is not affected by +.IR LC_COLLATE +because it is typically not used by human readers, but only by programs +such as +.IR vi +to locate the tag within the source files. Using the POSIX locale +eliminates some of the problems of coordinating locales between the +.IR ctags +file creator and the +.IR vi +file reader. +.P +Historically, the tags file has been used only by +.IR ex +and +.IR vi . +However, the format of the tags file has been published to encourage +other programs to use the tags in new ways. The format allows either +patterns or line numbers to find the identifiers because the historical +.IR vi +recognizes either. The +.IR ctags +utility does not produce the format using line numbers because it is +not useful following any source file changes that add or delete lines. +The documented search patterns match historical practice. It should be +noted that literal leading + +or trailing + +characters in the search pattern will only behave correctly if anchored +to the beginning of the line or end of the line by an additional + +or + +character. +.P +Historical implementations also understand the objects used by the +languages Pascal and sometimes LISP, and they understand the C source +output by +.IR lex +and +.IR yacc . +The +.IR ctags +utility is not required to accommodate these languages, although +implementors are encouraged to do so. +.P +The following historical option was not specified, as +.IR vgrind +is not included in this volume of POSIX.1\(hy2008: +.IP "\fB\(miv\fP" 10 +If the +.BR \(miv +flag is given, an index of the form expected by +.IR vgrind +is produced on the standard output. This listing contains the function +name, filename, and page number (assuming 64-line pages). Since the +output is sorted into lexicographic order, it may be desired to run the +output through +.IR sort +.BR \(mif . +Sample use: +.RS 10 +.sp +.RS 4 +.nf +\fB +ctags \(miv files | sort \(mif > index vgrind \(mix index +.fi \fR +.P +.RE +.RE +.P +The special treatment of the tag +.BR main +makes the use of +.IR ctags +practical in directories with more than one program. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIfort77\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cut.1p b/man-pages-posix-2013-a/man1p/cut.1p new file mode 100644 index 0000000..d5cfbc2 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cut.1p @@ -0,0 +1,496 @@ +'\" et +.TH CUT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cut +\(em cut out selected fields of each line of a file +.SH SYNOPSIS +.LP +.nf +cut \(mib \fIlist \fB[\fR\(min\fB] [\fIfile\fR...\fB]\fR +.P +cut \(mic \fIlist \fB[\fIfile\fR...\fB]\fR +.P +cut \(mif \fIlist \fB[\fR\(mid \fIdelim\fB] [\fR\(mis\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cut +utility shall cut out bytes (\c +.BR \(mib +option), characters (\c +.BR \(mic +option), or character-delimited fields (\c +.BR \(mif +option) from each line in one or more files, concatenate them, and +write them to standard output. +.SH OPTIONS +The +.IR cut +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The application shall ensure that the option-argument +.IR list +(see options +.BR \(mib , +.BR \(mic , +and +.BR \(mif +below) is a +-separated +list or +-separated +list of positive numbers and ranges. Ranges can be in three forms. The +first is two positive numbers separated by a + +(\c +.IR low \(mi\c +.IR high ), +which represents all fields from the first number to the second +number. The second is a positive number preceded by a + +(\(mi\c +.IR high ), +which represents all fields from field number 1 to that number. The +third is a positive number followed by a + +(\c +.IR low \(mi), +which represents that number to the last field, inclusive. The elements +in +.IR list +can be repeated, can overlap, and can be specified in any order, but +the bytes, characters, or fields selected shall be written in the order +of the input data. If an element appears in the selection list more +than once, it shall be written exactly once. +.P +The following options shall be supported: +.IP "\fB\(mib\ \fIlist\fR" 10 +Cut based on a +.IR list +of bytes. Each selected byte shall be output unless the +.BR \(min +option is also specified. It shall not be an error to select bytes not +present in the input line. +.IP "\fB\(mic\ \fIlist\fR" 10 +Cut based on a +.IR list +of characters. Each selected character shall be output. It shall not +be an error to select characters not present in the input line. +.IP "\fB\(mid\ \fIdelim\fR" 10 +Set the field delimiter to the character +.IR delim . +The default is the +. +.IP "\fB\(mif\ \fIlist\fR" 10 +Cut based on a +.IR list +of fields, assumed to be separated in the file by a delimiter character +(see +.BR \(mid ). +Each selected field shall be output. Output fields shall be separated +by a single occurrence of the field delimiter character. Lines with no +field delimiters shall be passed through intact, unless +.BR \(mis +is specified. It shall not be an error to select fields not present in +the input line. +.IP "\fB\(min\fP" 10 +Do not split characters. When specified with the +.BR \(mib +option, each element in +.IR list +of the form +.IR low \(mi\c +.IR high +(\c +-separated +numbers) shall be modified as follows: +.RS 10 +.IP " *" 4 +If the byte selected by +.IR low +is not the first byte of a character, +.IR low +shall be decremented to select the first byte of the character +originally selected by +.IR low . +If the byte selected by +.IR high +is not the last byte of a character, +.IR high +shall be decremented to select the last byte of the character prior to +the character originally selected by +.IR high , +or zero if there is no prior character. If the resulting range element +has +.IR high +equal to zero or +.IR low +greater than +.IR high , +the list element shall be dropped from +.IR list +for that input line without causing an error. +.P +Each element in +.IR list +of the form +.IR low \(mi +shall be treated as above with +.IR high +set to the number of bytes in the current line, not including the +terminating +. +Each element in +.IR list +of the form \(mi\c +.IR high +shall be treated as above with +.IR low +set to 1. Each element in +.IR list +of the form +.IR num +(a single number) shall be treated as above with +.IR low +set to +.IR num +and +.IR high +set to +.IR num . +.RE +.IP "\fB\(mis\fP" 10 +Suppress lines with no delimiter characters, when used with the +.BR \(mif +option. Unless specified, lines with no delimiters shall be passed +through untouched. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files, except that line lengths shall be +unlimited. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cut : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR cut +utility output shall be a concatenation of the selected bytes, +characters, or fields (one of the following): +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIconcatenation of bytes\fR> +.P +"%s\en", <\fIconcatenation of characters\fR> +.P +"%s\en", <\fIconcatenation of fields and field delimiters\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR cut +and +.IR fold +utilities can be used to create text files out of files with +arbitrary line lengths. The +.IR cut +utility should be used when the number of lines (or records) needs +to remain constant. The +.IR fold +utility should be used when the contents of long lines need to be +kept contiguous. +.P +Earlier versions of the +.IR cut +utility worked in an environment where bytes and characters were +considered equivalent (modulo + +and + +processing in some implementations). In the extended world of +multi-byte characters, the new +.BR \(mib +option has been added. The +.BR \(min +option (used with +.BR \(mib ) +allows it to be used to act on bytes rounded to character boundaries. +The algorithm specified for +.BR \(min +guarantees that: +.sp +.RS 4 +.nf +\fB +cut \(mib 1\(mi500 \(min file > file1 +cut \(mib 501\(mi \(min file > file2 +.fi \fR +.P +.RE +.P +ends up with all the characters in +.BR file +appearing exactly once in +.BR file1 +or +.BR file2 . +(There is, however, a + +in both +.BR file1 +and +.BR file2 +for each + +in +.BR file .) +.SH EXAMPLES +Examples of the option qualifier list: +.IP 1,4,7 8 +Select the first, fourth, and seventh bytes, characters, or fields and +field delimiters. +.IP "1\(mi3,8" 8 +Equivalent to 1,2,3,8. +.IP "\(mi5,10" 8 +Equivalent to 1,2,3,4,5,10. +.IP "3\(mi" 8 +Equivalent to third to last, inclusive. +.P +The +.IR low \(mi\c +.IR high +forms are not always equivalent when used with +.BR \(mib +and +.BR \(min +and multi-byte characters; see the description of +.BR \(min . +.P +The following command: +.sp +.RS 4 +.nf +\fB +cut \(mid : \(mif 1,6 /etc/passwd +.fi \fR +.P +.RE +.P +reads the System V password file (user database) and produces lines of +the form: +.sp +.RS 4 +.nf +\fB +<\fIuser ID\fR>:<\fIhome directory\fR> +.fi \fR +.P +.RE +.P +Most utilities in this volume of POSIX.1\(hy2008 work on text files. The +.IR cut +utility can be used to turn files with arbitrary line lengths into a +set of text files containing the same data. The +.IR paste +utility can be used to create (or recreate) files with arbitrary line +lengths. For example, if +.BR file +contains long lines: +.sp +.RS 4 +.nf +\fB +cut \(mib 1\(mi500 \(min file > file1 +cut \(mib 501\(mi \(min file > file2 +.fi \fR +.P +.RE +.P +creates +.BR file1 +(a text file) with lines no longer than 500 bytes (plus the +) +and +.BR file2 +that contains the remainder of the data from +.BR file . +(Note that +.BR file2 +is not a text file if there are lines in +.BR file +that are longer than 500 + +{LINE_MAX} +bytes.) The original file can be recreated from +.BR file1 +and +.BR file2 +using the command: +.sp +.RS 4 +.nf +\fB +paste \(mid "\e0" file1 file2 > file +.fi \fR +.P +.RE +.SH RATIONALE +Some historical implementations do not count + +characters in determining character counts with the +.BR \(mic +option. This may be useful for using +.IR cut +for processing +.IR nroff +output. It was deliberately decided not to have the +.BR \(mic +option treat either + +or + +characters in any special fashion. The +.IR fold +utility does treat these characters specially. +.P +Unlike other utilities, some historical implementations of +.IR cut +exit after not finding an input file, rather than continuing to process +the remaining +.IR file +operands. This behavior is prohibited by this volume of POSIX.1\(hy2008, where only the exit +status is affected by this problem. +.P +The behavior of +.IR cut +when provided with either mutually-exclusive options or options that do +not work logically together has been deliberately left unspecified in +favor of global wording in +.IR "Section 1.4" ", " "Utility Description Defaults". +.P +The OPTIONS section was changed in response to IEEE PASC Interpretation +1003.2 #149. The change represents historical practice on all known +systems. The original standard was ambiguous on the nature of the +output. +.P +The +.IR list +option-arguments are historically used to select the portions of the +line to be written, but do not affect the order of the data. For +example: +.sp +.RS 4 +.nf +\fB +echo abcdefghi | cut \(mic6,2,4\(mi7,1 +.fi \fR +.P +.RE +.P +yields +.BR \(dqabdefg\(dq . +.P +A proposal to enhance +.IR cut +with the following option: +.IP "\fB\(mio\fP" 6 +Preserve the selected field order. When this option is specified, each +byte, character, or field (or ranges of such) shall be written in the +order specified by the +.IR list +option-argument, even if this requires multiple outputs of the same +bytes, characters, or fields. +.P +was rejected because this type of enhancement is outside the scope of +the IEEE\ P1003.2b draft standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "\fIfold\fR\^", +.IR "\fIgrep\fR\^", +.IR "\fIpaste\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/cxref.1p b/man-pages-posix-2013-a/man1p/cxref.1p new file mode 100644 index 0000000..a53c599 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/cxref.1p @@ -0,0 +1,180 @@ +'\" et +.TH CXREF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cxref +\(em generate a C-language program cross-reference table +(\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +cxref \fB[\fR\(mics\fB] [\fR\(mio \fIfile\fB] [\fR\(miw \fInum\fB] [\fR\(miD \fIname\fB[\fR=\fIdef\fB]]\fR...\fB [\fR\(miI \fIdir\fB]\fR... + \fB[\fR\(miU \fIname\fB]\fR... \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR cxref +utility shall analyze a collection of C-language +.IR file s +and attempt to build a cross-reference table. Information from +.BR #define +lines shall be included in the symbol table. A sorted listing shall be +written to standard output of all symbols (auto, static, and global) in +each +.IR file +separately, or with the +.BR \(mic +option, in combination. Each symbol shall contain an + +before the declaring reference. +.SH OPTIONS +The +.IR cxref +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of the +.BR \(miD , +.BR \(miI , +and +.BR \(miU +options (which are identical to their interpretation by +.IR c99 ) +is significant. The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Write a combined cross-reference of all input files. +.IP "\fB\(mis\fP" 10 +Operate silently; do not print input filenames. +.IP "\fB\(mio\ \fIfile\fR" 10 +Direct output to named +.IR file . +.IP "\fB\(miw\ \fInum\fR" 10 +Format output no wider than +.IR num +(decimal) columns. This option defaults to 80 if +.IR num +is not specified or is less than 51. +.IP "\fB\(miD\fP" 10 +Equivalent to +.IR c99 . +.IP "\fB\(miI\fP" 10 +Equivalent to +.IR c99 . +.IP "\fB\(miU\fP" 10 +Equivalent to +.IR c99 . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a C-language source file. +.SH STDIN +Not used. +.SH "INPUT FILES" +The input files are C-language source files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cxref : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the ordering of the output. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used for the cross-reference listing, +unless the +.BR \(mio +option is used to select a different output file. +.P +The format of standard output is unspecified, except that the following +information shall be included: +.IP " *" 4 +If the +.BR \(mic +option is not specified, each portion of the listing shall start +with the name of the input file on a separate line. +.IP " *" 4 +The name line shall be followed by a sorted list of symbols, each with +its associated location pathname, the name of the function in which it +appears (if it is not a function name itself), and line number +references. +.IP " *" 4 +Each line number may be preceded by an + +(\c +.BR '*' ) +flag, meaning that this is the declaring reference. Other +single-character flags, with implementation-defined meanings, may be +included. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output file named by the +.BR \(mio +option shall be used instead of standard output. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/date.1p b/man-pages-posix-2013-a/man1p/date.1p new file mode 100644 index 0000000..52d4639 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/date.1p @@ -0,0 +1,627 @@ +'\" et +.TH DATE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +date +\(em write the date and time +.SH SYNOPSIS +.LP +.nf +date \fB[\fR\(miu\fB] [\fR+\fIformat\fB]\fR +.P +date \fB[\fR\(miu\fB] \fImmddhhmm\fB[[\fIcc\fB]\fIyy\fB]\fR +.fi +.SH DESCRIPTION +The +.IR date +utility shall write the date and time to standard output +or attempt to set the system date and time. +By default, the current date and time shall be written. If an operand +beginning with +.BR '\(pl' +is specified, the output format of +.IR date +shall be controlled by the conversion specifications and other text +in the operand. +.SH OPTIONS +The +.IR date +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miu\fP" 10 +Perform operations as if the +.IR TZ +environment variable was set to the string +.BR \(dqUTC0\(dq , +or its equivalent historical value of +.BR \(dqGMT0\(dq . +Otherwise, +.IR date +shall use the timezone indicated by the +.IR TZ +environment variable or the system default if that variable is +unset or null. +.SH OPERANDS +The following operands shall be supported: +.IP "+\fIformat\fR" 10 +When the format is specified, each conversion specifier shall be +replaced in the standard output by its corresponding value. All other +characters shall be copied to the output without change. The output +shall always be terminated with a +. +.SS "Conversion Specifications" +.RS 10 +.IP "\fR%a\fR" 8 +Locale's abbreviated weekday name. +.IP "\fR%A\fR" 8 +Locale's full weekday name. +.IP "\fR%b\fR" 8 +Locale's abbreviated month name. +.IP "\fR%B\fR" 8 +Locale's full month name. +.IP "\fR%c\fR" 8 +Locale's appropriate date and time representation. +.IP "\fR%C\fR" 8 +Century (a year divided by 100 and truncated to an integer) as a +decimal number [00,99]. +.IP "\fR%d\fR" 8 +Day of the month as a decimal number [01,31]. +.IP "\fR%D\fR" 8 +Date in the format \fImm\fP/\fIdd\fP/\fIyy\fR. +.IP "\fR%e\fR" 8 +Day of the month as a decimal number [1,31] in a two-digit field +with leading + +character fill. +.IP "\fR%h\fR" 8 +A synonym for +.BR %b . +.IP "\fR%H\fR" 8 +Hour (24-hour clock) as a decimal number [00,23]. +.IP "\fR%I\fR" 8 +Hour (12-hour clock) as a decimal number [01,12]. +.IP "\fR%j\fR" 8 +Day of the year as a decimal number [001,366]. +.IP "\fR%m\fR" 8 +Month as a decimal number [01,12]. +.IP "\fR%M\fR" 8 +Minute as a decimal number [00,59]. +.IP "\fR%n\fR" 8 +A +. +.IP "\fR%p\fR" 8 +Locale's equivalent of either AM or PM. +.IP "\fR%r\fR" 8 +12-hour clock time [01,12] using the AM/PM notation; in the POSIX +locale, this shall be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fR%S\fR" 8 +Seconds as a decimal number [00,60]. +.IP "\fR%t\fR" 8 +A +. +.IP "\fR%T\fR" 8 +24-hour clock time [00,23] in the format \fIHH\fP:\fIMM\fP:\fISS\fP. +.IP "\fR%u\fR" 8 +Weekday as a decimal number [1,7] (1=Monday). +.IP "\fR%U\fR" 8 +Week of the year (Sunday as the first day of the week) as a decimal +number [00,53]. All days in a new year preceding the first Sunday +shall be considered to be in week 0. +.IP "\fR%V\fR" 8 +Week of the year (Monday as the first day of the week) as a decimal +number [01,53]. If the week containing January 1 has four or more +days in the new year, then it shall be considered week 1; otherwise, it +shall be the last week of the previous year, and the next week shall be +week 1. +.IP "\fR%w\fR" 8 +Weekday as a decimal number [0,6] (0=Sunday). +.IP "\fR%W\fR" 8 +Week of the year (Monday as the first day of the week) as a decimal +number [00,53]. All days in a new year preceding the first Monday +shall be considered to be in week 0. +.IP "\fR%x\fR" 8 +Locale's appropriate date representation. +.IP "\fR%X\fR" 8 +Locale's appropriate time representation. +.IP "\fR%y\fR" 8 +Year within century [00,99]. +.IP "\fR%Y\fR" 8 +Year with century as a decimal number. +.IP "\fR%Z\fR" 8 +Timezone name, or no characters if no timezone is determinable. +.IP "\fR%%\fR" 8 +A + +character. +.P +See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME" +for the conversion specifier values in the POSIX locale. +.SS "Modified Conversion Specifications" +.P +Some conversion specifiers can be modified by the +.BR E +and +.BR O +modifier characters to indicate a different format or specification as +specified in the +.IR LC_TIME +locale description (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME"). +If the corresponding keyword (see +.BR era , +.BR era_year , +.BR era_d_fmt , +and +.BR alt_digits +in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME") +is not specified or not supported for the current locale, +the unmodified conversion specifier value shall be used. +.IP "\fR%Ec\fR" 8 +Locale's alternative appropriate date and time representation. +.IP "\fR%EC\fR" 8 +The name of the base year (period) in the locale's alternative +representation. +.IP "\fR%Ex\fR" 8 +Locale's alternative date representation. +.IP "\fR%EX\fR" 8 +Locale's alternative time representation. +.IP "\fR%Ey\fR" 8 +Offset from +.BR %EC +(year only) in the locale's alternative representation. +.IP "\fR%EY\fR" 8 +Full alternative year representation. +.IP "\fR%Od\fR" 8 +Day of month using the locale's alternative numeric symbols. +.IP "\fR%Oe\fR" 8 +Day of month using the locale's alternative numeric symbols. +.IP "\fR%OH\fR" 8 +Hour (24-hour clock) using the locale's alternative numeric symbols. +.IP "\fR%OI\fR" 8 +Hour (12-hour clock) using the locale's alternative numeric symbols. +.IP "\fR%Om\fR" 8 +Month using the locale's alternative numeric symbols. +.IP "\fR%OM\fR" 8 +Minutes using the locale's alternative numeric symbols. +.IP "\fR%OS\fR" 8 +Seconds using the locale's alternative numeric symbols. +.IP "\fR%Ou\fR" 8 +Weekday as a number in the locale's alternative representation (Monday += 1). +.IP "\fR%OU\fR" 8 +Week number of the year (Sunday as the first day of the week) using the +locale's alternative numeric symbols. +.IP "\fR%OV\fR" 8 +Week number of the year (Monday as the first day of the week, rules +corresponding to +.BR %V ), +using the locale's alternative numeric symbols. +.IP "\fR%Ow\fR" 8 +Weekday as a number in the locale's alternative representation (Sunday += 0). +.IP "\fR%OW\fR" 8 +Week number of the year (Monday as the first day of the week) using the +locale's alternative numeric symbols. +.IP "\fR%Oy\fR" 8 +Year (offset from +.BR %C ) +in alternative representation. +.RE +.IP "\fImmddhhmm\fB[[\fIcc\fB]\fIyy\fB]\fR" 10 +.br +Attempt to set the system date and time from the value given in the +operand. This is only possible if the user has appropriate privileges +and the system permits the setting of the system date and time. The +first +.IR mm +is the month (number); +.IR dd +is the day (number); +.IR hh +is the hour (number, 24-hour system); the second +.IR mm +is the minute (number); +.IR cc +is the century and is the first two digits of the year (this is +optional); +.IR yy +is the last two digits of the year and is optional. If century is not +specified, then values in the range [69,99] shall refer to years +1969 to 1999 inclusive, and values in the range [00,68] shall refer +to years 2000 to 2068 inclusive. The current year is the default if +.IR yy +is omitted. +.RS 10 +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR date : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of date and time strings written by +.IR date . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone in which the time and date are written, unless +the +.BR \(miu +option is specified. If the +.IR TZ +variable is unset or null and +.BR \(miu +is not specified, an unspecified system default timezone is used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When no formatting operand is specified, the output in the POSIX locale +shall be equivalent to specifying: +.sp +.RS 4 +.nf +\fB +date "+%a %b %e %H:%M:%S %Z %Y" +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The date was written successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Conversion specifiers are of unspecified format when not in the POSIX +locale. Some of them can contain + +characters in some locales, so it may be difficult to use the format +shown in standard output for parsing the output of +.IR date +in those locales. +.P +The range of values for +.BR %S +extends from 0 to 60 seconds to accommodate the occasional leap second. +.P +Although certain of the conversion specifiers in the POSIX locale (such +as the name of the month) are shown with initial capital letters, this +need not be the case in other locales. Programs using these fields may +need to adjust the capitalization if the output is going to be used at +the beginning of a sentence. +.P +The date string formatting capabilities are intended for use in +Gregorian-style calendars, possibly with a different starting year (or +years). The +.BR %x +and +.BR %c +conversion specifications, however, are intended for local +representation; these may be based on a different, non-Gregorian +calendar. +.P +The +.BR %C +conversion specification was introduced to allow a fallback for the +.BR %EC +(alternative year format base year); it can be viewed as the base of +the current subdivision in the Gregorian calendar. The century number +is calculated as the year divided by 100 and truncated to an integer; +it should not be confused with the use of ordinal numbers for centuries +(for example, ``twenty-first century''.) Both the +.BR %Ey +and +.BR %y +can then be viewed as the offset from +.BR %EC +and +.BR %C , +respectively. +.P +The +.BR E +and +.BR O +modifiers modify the traditional conversion specifiers, so that they +can always be used, even if the implementation (or the current locale) +does not support the modifier. +.P +The +.BR E +modifier supports alternative date formats, such as the Japanese +Emperor's Era, as long as these are based on the Gregorian calendar +system. Extending the +.BR E +modifiers to other date elements may provide an implementation-defined +extension capable of supporting other calendar systems, especially in +combination with the +.BR O +modifier. +.P +The +.BR O +modifier supports time and date formats using the locale's alternative +numerical symbols, such as Kanji or Hindi digits or ordinal number +representation. +.P +Non-European locales, whether they use Latin digits in computational +items or not, often have local forms of the digits for use in date +formats. This is not totally unknown even in Europe; a variant of dates +uses Roman numerals for the months: the third day of September 1991 +would be written as 3.IX.1991. In Japan, Kanji digits are regularly +used for dates; in Arabic-speaking countries, Hindi digits are used. +The +.BR %d , +.BR %e , +.BR %H , +.BR %I , +.BR %m , +.BR %S , +.BR %U , +.BR %w , +.BR %W , +and +.BR %y +conversion specifications always return the date and time field in +Latin digits (that is, 0 to 9). The +.BR %O +modifier was introduced to support the use for display purposes of +non-Latin digits. In the +.IR LC_TIME +category in +.IR localedef , +the optional +.BR alt_digits +keyword is intended for this purpose. As an example, assume the +following (partial) +.IR localedef +source: +.sp +.RS 4 +.nf +\fB +alt_digits "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \e + "IX";"X";"XI";"XII" +d_fmt "%e.%Om.%Y" +.fi \fR +.P +.RE +.P +With the above date, the command: +.sp +.RS 4 +.nf +\fB +date "+%x" +.fi \fR +.P +.RE +.P +would yield 3.IX.1991. With the same +.BR d_fmt , +but without the +.BR alt_digits , +the command would yield 3.9.1991. +.SH EXAMPLES +.IP " 1." 4 +The following are input/output examples of +.IR date +used at arbitrary times in the POSIX locale: +.RS 4 +.sp +.RS 4 +.nf +\fB +\fB$ \fRdate +\fBTue Jun 26 09:58:10 PDT 1990 +.P +\fB$ \fRdate "+DATE: %m/%d/%y%nTIME: %H:%M:%S" +\fBDATE: 11/02/91 +\fBTIME: 13:36:16 +.P +\fB$ \fRdate "+TIME: %r" +\fBTIME: 01:36:32 PM\fR +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Examples for Denmark, where the default date and time format is +.BR %a +.BR %d +.BR %b +.BR %Y +.BR %T +.BR %Z : +.RS 4 +.sp +.RS 4 +.nf +\fB +\fB$ \fRLANG=da_DK.iso_8859\(mi1 date +\fBons 02 okt 1991 15:03:32 CET +.P +\fB$ \fRLANG=da_DK.iso_8859\(mi1 \e + date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S" +\fBDATO: onsdag den 2. oktober 1991 +\fBKLOKKEN: 15:03:56\fR +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Examples for Germany, where the default date and time format is +.BR %a +.BR %d .\c +.BR %h .\c +.BR %Y , +.BR %T +.BR %Z : +.RS 4 +.sp +.RS 4 +.nf +\fB +\fB$ \fRLANG=De_DE.88591 date +\fBMi 02.Okt.1991, 15:01:21 MEZ +.P +\fB$ \fRLANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S" +\fBDATUM: Mittwoch, 02. Oktober 1991 +\fBZEIT: 15:02:02\fR +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Examples for France, where the default date and time format is +.BR %a +.BR %d +.BR %h +.BR %Y +.BR %Z +.BR %T : +.RS 4 +.sp +.RS 4 +.nf +\fB +\fB$ \fRLANG=Fr_FR.88591 date +\fBMer 02 oct 1991 MET 15:03:32 +.P +\fB$ \fRLANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S" +\fBJOUR: Mercredi 02 octobre 1991 +\fBHEURE: 15:03:56\fR +.fi \fR +.P +.RE +.RE +.SH RATIONALE +Some of the new options for formatting are from the ISO\ C standard. The +.BR \(miu +option was introduced to allow portable access to Coordinated Universal +Time (UTC). +The string +.BR \(dqGMT0\(dq +is allowed as an equivalent +.IR TZ +value to be compatible with all of the systems using the BSD +implementation, where this option originated. +.P +The +.BR %e +format conversion specification (adopted from System V) was added +because the ISO\ C standard conversion specifications did not provide any way to +produce the historical default +.IR date +output during the first nine days of any month. +.P +There are two varieties of day and week numbering supported (in +addition to any others created with the locale-dependent +.BR %E +and +.BR %O +modifier characters): +.IP " *" 4 +The historical variety in which Sunday is the first day of the week and +the weekdays preceding the first Sunday of the year are considered week +0. These are represented by +.BR %w +and +.BR %U . +A variant of this is +.BR %W , +using Monday as the first day of the week, but still referring to week +0. This view of the calendar was retained because so many historical +applications depend on it and the ISO\ C standard +\fIstrftime\fR() +function, on which many +.IR date +implementations are based, was defined in this way. +.IP " *" 4 +The international standard, based on the ISO\ 8601:\|2004 standard where Monday is the +first weekday and the algorithm for the first week number is more +complex: If the week (Monday to Sunday) containing January 1 has four +or more days in the new year, then it is week 1; otherwise, it is week +53 of the previous year, and the next week is week 1. These are +represented by the new conversion specifications +.BR %u +and +.BR %V , +added as a result of international comments. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/dd.1p b/man-pages-posix-2013-a/man1p/dd.1p new file mode 100644 index 0000000..aedaa34 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/dd.1p @@ -0,0 +1,769 @@ +'\" et +.TH DD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dd +\(em convert and copy a file +.SH SYNOPSIS +.LP +.nf +dd \fB[\fIoperand\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR dd +utility shall copy the specified input file to the specified output +file with possible conversions using specific input and output block +sizes. It shall read the input one block at a time, using the +specified input block size; it shall then process the block of data +actually returned, which could be smaller than the requested block +size. It shall apply any conversions that have been specified and write +the resulting data to the output in blocks of the specified output +block size. If the +.BR bs =\c +.IR expr +operand is specified and no conversions other than +.BR sync , +.BR noerror , +or +.BR notrunc +are requested, the data returned from each input block shall be written +as a separate output block; if the read returns less than a full block +and the +.BR sync +conversion is not specified, the resulting output block shall be the +same size as the input block. If the +.BR bs =\c +.IR expr +operand is not specified, or a conversion other than +.BR sync , +.BR noerror , +or +.BR notrunc +is requested, the input shall be processed and collected into +full-sized output blocks until the end of the input is reached. +.P +The processing order shall be as follows: +.IP " 1." 4 +An input block is read. +.IP " 2." 4 +If the input block is shorter than the specified input block size and +the +.BR sync +conversion is specified, null bytes shall be appended to the input data +up to the specified size. (If either +.BR block +or +.BR unblock +is also specified, + +characters shall be appended instead of null bytes.) The remaining +conversions and output shall include the pad characters as if they had +been read from the input. +.IP " 3." 4 +If the +.BR bs =\c +.IR expr +operand is specified and no conversion other than +.BR sync +or +.BR noerror +is requested, the resulting data shall be written to the output as a +single block, and the remaining steps are omitted. +.IP " 4." 4 +If the +.BR swab +conversion is specified, each pair of input data bytes shall be +swapped. If there is an odd number of bytes in the input block, the +last byte in the input record shall not be swapped. +.IP " 5." 4 +Any remaining conversions (\c +.BR block , +.BR unblock , +.BR lcase , +and +.BR ucase ) +shall be performed. These conversions shall operate on the input data +independently of the input blocking; an input or output fixed-length +record may span block boundaries. +.IP " 6." 4 +The data resulting from input or conversion or both shall be aggregated +into output blocks of the specified size. After the end of input is +reached, any remaining output shall be written as a block without +padding if +.BR conv =\c +.BR sync +is not specified; thus, the final output block may be shorter than the +output block size. +.SH OPTIONS +None. +.SH OPERANDS +All of the operands shall be processed before any input is read. +The following operands shall be supported: +.IP "\fBif\fR=\fIfile\fR" 10 +Specify the input pathname; the default is standard input. +.IP "\fBof\fR=\fIfile\fR" 10 +Specify the output pathname; the default is standard output. If the +.BR seek =\c +.IR expr +conversion is not also specified, the output file shall be truncated +before the copy begins if an explicit +.BR of =\c +.IR file +operand is specified, unless +.BR conv =\c +.BR notrunc +is specified. If +.BR seek =\c +.IR expr +is specified, but +.BR conv =\c +.BR notrunc +is not, the effect of the copy shall be to preserve the blocks in the +output file over which +.IR dd +seeks, but no other portion of the output file shall be preserved. (If +the size of the seek plus the size of the input file is less than the +previous size of the output file, the output file shall be shortened by +the copy. If the input file is empty and either the size of the seek is +greater than the previous size of the output file or the output file +did not previously exist, the size of the output file shall be set to +the file offset after the seek.) +.IP "\fBibs\fR=\fIexpr\fR" 10 +Specify the input block size, in bytes, by +.IR expr +(default is 512). +.IP "\fBobs\fR=\fIexpr\fR" 10 +Specify the output block size, in bytes, by +.IR expr +(default is 512). +.IP "\fBbs\fR=\fIexpr\fR" 10 +Set both input and output block sizes to +.IR expr +bytes, superseding +.BR ibs = +and +.BR obs =. +If no conversion other than +.BR sync , +.BR noerror , +and +.BR notrunc +is specified, each input block shall be copied to the output as a +single block without aggregating short blocks. +.IP "\fBcbs\fR=\fIexpr\fR" 10 +Specify the conversion block size for +.BR block +and +.BR unblock +in bytes by +.IR expr +(default is zero). If +.BR cbs = +is omitted or given a value of zero, using +.BR block +or +.BR unblock +produces unspecified results. +.RS 10 +.P +The application shall ensure that this operand is also specified if the +.BR conv = +operand is specified with a value of +.BR ascii , +.BR ebcdic , +or +.BR ibm . +For a +.BR conv = +operand with an +.BR ascii +value, the input is handled as described for the +.BR unblock +value, except that characters are converted to ASCII before any +trailing + +characters are deleted. For +.BR conv = +operands with +.BR ebcdic +or +.BR ibm +values, the input is handled as described for the +.BR block +value except that the characters are converted to EBCDIC or IBM EBCDIC, +respectively, after any trailing + +characters are added. +.RE +.IP "\fBskip\fR=\fIn\fR" 10 +Skip +.IR n +input blocks (using the specified input block size) before starting to +copy. On seekable files, the implementation shall read the blocks or +seek past them; on non-seekable files, the blocks shall be read and the +data shall be discarded. +.IP "\fBseek\fR=\fIn\fR" 10 +Skip +.IR n +blocks (using the specified output block size) from the beginning of the +output file before copying. On non-seekable files, existing blocks +shall be read and space from the current end-of-file to the specified +offset, if any, filled with null bytes; on seekable files, the +implementation shall seek to the specified offset or read the blocks as +described for non-seekable files. +.IP "\fBcount\fR=\fIn\fR" 10 +Copy only +.IR n +input blocks. +.IP "\fBconv\fR=\fIvalue\fB[\fR,\fIvalue\fR\ .\|.\|.\fB]\fR" 10 +.br +Where +.IR value s +are +-separated +symbols from the following list: +.RS 10 +.IP "\fBascii\fR" 9 +Convert EBCDIC to ASCII; see +.IR "Table 4-7, ASCII to EBCDIC Conversion". +.IP "\fBebcdic\fR" 9 +Convert ASCII to EBCDIC; see +.IR "Table 4-7, ASCII to EBCDIC Conversion". +.IP "\fBibm\fR" 9 +Convert ASCII to a different EBCDIC set; see +.IR "Table 4-8, ASCII to IBM EBCDIC Conversion". +.P +The +.BR ascii , +.BR ebcdic , +and +.BR ibm +values are mutually-exclusive. +.IP "\fBblock\fR" 9 +Treat the input as a sequence of +-terminated +or end-of-file-terminated variable-length records independent of the +input block boundaries. Each record shall be converted to a record with +a fixed length specified by the conversion block size. Any + +shall be removed from the input line; + +characters shall be appended to lines that are shorter than their +conversion block size to fill the block. Lines that are longer than +the conversion block size shall be truncated to the largest number of +characters that fit into that size; the number of truncated lines shall +be reported (see the STDERR section). +.RS 9 +.P +The +.BR block +and +.BR unblock +values are mutually-exclusive. +.RE +.IP "\fBunblock\fR" 9 +Convert fixed-length records to variable length. Read a number of bytes +equal to the conversion block size (or the number of bytes remaining in +the input, if less than the conversion block size), delete all trailing + +characters, and append a +. +.IP "\fBlcase\fR" 9 +Map uppercase characters specified by the +.IR LC_CTYPE +keyword +.BR tolower +to the corresponding lowercase character. Characters for which no +mapping is specified shall not be modified by this conversion. +.RS 9 +.P +The +.BR lcase +and +.BR ucase +symbols are mutually-exclusive. +.RE +.IP "\fBucase\fR" 9 +Map lowercase characters specified by the +.IR LC_CTYPE +keyword +.BR toupper +to the corresponding uppercase character. Characters for which no +mapping is specified shall not be modified by this conversion. +.IP "\fBswab\fR" 9 +Swap every pair of input bytes. +.IP "\fBnoerror\fR" 9 +Do not stop processing on an input error. When an input error occurs, a +diagnostic message shall be written on standard error, followed by the +current input and output block counts in the same format as used at +completion (see the STDERR section). If the +.BR sync +conversion is specified, the missing input shall be replaced with null +bytes and processed normally; otherwise, the input block shall be +omitted from the output. +.IP "\fBnotrunc\fR" 9 +Do not truncate the output file. Preserve blocks in the output +file not explicitly written by this invocation of the +.IR dd +utility. (See also the preceding +.BR of =\c +.IR file +operand.) +.IP "\fBsync\fR" 9 +Pad every input block to the size of the +.BR ibs = +buffer, appending null bytes. (If either +.BR block +or +.BR unblock +is also specified, append + +characters, rather than null bytes.) +.RE +.P +The behavior is unspecified if operands other than +.BR conv = +are specified more than once. +.P +For the +.BR bs =, +.BR cbs =, +.BR ibs =, +and +.BR obs = +operands, the application shall supply an expression specifying a size +in bytes. The expression, +.IR expr , +can be: +.IP " 1." 4 +A positive decimal number +.IP " 2." 4 +A positive decimal number followed by +.IR k , +specifying multiplication by 1\|024 +.IP " 3." 4 +A positive decimal number followed by +.IR b , +specifying multiplication by 512 +.IP " 4." 4 +Two or more positive decimal numbers (with or without +.IR k +or +.IR b ) +separated by +.IR x , +specifying the product of the indicated values +.P +All of the operands are processed before any input is read. +.P +The following two tables display the octal number character values used +for the +.BR ascii +and +.BR ebcdic +conversions (first table) and for the +.BR ibm +conversion (second table). In both tables, the ASCII values are the row +and column headers and the EBCDIC values are found at their +intersections. For example, ASCII 0012 (LF) is the second row, third +column, yielding 0045 in EBCDIC. The inverted tables (for EBCDIC to +ASCII conversion) are not shown, but are in one-to-one correspondence +with these tables. The differences between the two tables are +highlighted by small boxes drawn around five entries. +.br +.sp +.ce 1 +\fBTable 4-7: ASCII to EBCDIC Conversion\fR +.bp +.sp +.ce 1 +\fBTable 4-8: ASCII to IBM EBCDIC Conversion\fR +.SH STDIN +If no +.BR if = +operand is specified, the standard input shall be used. See the INPUT +FILES section. +.SH "INPUT FILES" +The input file can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR dd : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the classification +of characters as uppercase or lowercase, and the mapping of characters +from one case to the other. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +For SIGINT, the +.IR dd +utility shall interrupt its current processing, write status +information to standard error, and exit as though terminated by +SIGINT. It shall take the standard action for all other signals; see +the ASYNCHRONOUS EVENTS section in +.IR "Section 1.4" ", " "Utility Description Defaults". +.SH STDOUT +If no +.BR of = +operand is specified, the standard output shall be used. The nature of +the output depends on the operands selected. +.SH STDERR +On completion, +.IR dd +shall write the number of input and output blocks to standard error. In +the POSIX locale the following formats shall be used: +.sp +.RS 4 +.nf +\fB +"%u+%u records in\en", <\fInumber of whole input blocks\fR>, + <\fInumber of partial input blocks\fR> +.P +"%u+%u records out\en", <\fInumber of whole output blocks\fR>, + <\fInumber of partial output blocks\fR> +.fi \fR +.P +.RE +.P +A partial input block is one for which +\fIread\fR() +returned less than the input block size. A partial output block is one +that was written with fewer bytes than specified by the output block +size. +.P +In addition, when there is at least one truncated block, the number of +truncated blocks shall be written to standard error. In the POSIX +locale, the format shall be: +.sp +.RS 4 +.nf +\fB +"%u truncated %s\en", <\fInumber of truncated blocks\fR>, "record" (if + <\fInumber of truncated blocks\fR> is one) "records" (otherwise) +.fi \fR +.P +.RE +.P +Diagnostic messages may also be written to standard error. +.SH "OUTPUT FILES" +If the +.BR of = +operand is used, the output shall be the same as described in the +STDOUT section. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The input file was copied successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If an input error is detected and the +.BR noerror +conversion has not been specified, any partial output block shall be +written to the output file, a diagnostic message shall be written, and +the copy operation shall be discontinued. If some other error is +detected, a diagnostic message shall be written and the copy operation +shall be discontinued. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The input and output block size can be specified to take advantage of +raw physical I/O. +.P +There are many different versions of the EBCDIC codesets. The ASCII and +EBCDIC conversions specified for the +.IR dd +utility perform conversions for the version specified by the tables. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +dd if=/dev/rmt0h of=/dev/rmt1h +.fi \fR +.P +.RE +.P +copies from tape drive 0 to tape drive 1, using a common historical +device naming convention. +.P +The following command: +.sp +.RS 4 +.nf +\fB +dd ibs=10 skip=1 +.fi \fR +.P +.RE +.P +strips the first 10 bytes from standard input. +.P +This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card +images per block into the ASCII file +.BR x : +.sp +.RS 4 +.nf +\fB +dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase +.fi \fR +.P +.RE +.SH RATIONALE +The OPTIONS section is listed as ``None'' because there are no options +recognized by historical +.IR dd +utilities. Certainly, many of the operands could have been designed to +use the Utility Syntax Guidelines, which would have resulted in the +classic hyphenated option letters. In this version of this volume of POSIX.1\(hy2008, +.IR dd +retains its curious JCL-like syntax due to the large number of +applications that depend on the historical implementation. +.P +A suggested implementation technique for +.BR conv =\c +.BR noerror ,\c +.BR sync +is to zero (or +-fill, +if +.BR block ing +or +.BR unblock ing) +the input buffer before each read and to write the contents of the +input buffer to the output even after an error. In this manner, any +data transferred to the input buffer before the error was detected is +preserved. Another point is that a failed read on a regular file or a +disk generally does not increment the file offset, and +.IR dd +must then seek past the block on which the error occurred; otherwise, +the input error occurs repetitively. When the input is a magnetic tape, +however, the tape normally has passed the block containing the error +when the error is reported, and thus no seek is necessary. +.P +The default +.BR ibs = +and +.BR obs = +sizes are specified as 512 bytes because there are historical (largely +portable) scripts that assume these values. If they were left +unspecified, unusual results could occur if an implementation chose an +odd block size. +.P +Historical implementations of +.IR dd +used +\fIcreat\fR() +when processing +.BR of =\c +.IR file . +This makes the +.BR seek = +operand unusable except on special files. The +.BR conv =\c +.BR notrunc +feature was added because more recent BSD-based implementations use +\fIopen\fR() +(without O_TRUNC) instead of +\fIcreat\fR(), +but they fail to delete output file contents after the data copied. +.P +The +.IR w +multiplier (historically meaning +.IR word ), +is used in System V to mean 2 and in 4.2 BSD to mean 4. Since +.IR word +is inherently non-portable, its use is not supported by this volume of POSIX.1\(hy2008. +.P +Standard EBCDIC does not have the characters +.BR '[' +and +.BR ']' . +The values used in the table are taken from a common print train that +does contain them. Other than those characters, the print train values +are not filled in, but appear to provide some of the motivation for the +historical choice of translations reflected here. +.P +The Standard EBCDIC table provides a 1:1 translation for all 256 +bytes. +.P +The IBM EBCDIC table does not provide such a translation. The marked +cells in the tables differ in such a way that: +.IP " 1." 4 +EBCDIC 0112 (\c +.BR '\(ct' ) +and 0152 (broken pipe) do not appear in the table. +.IP " 2." 4 +EBCDIC 0137 (\c +.BR '\(no' ) +translates to/from ASCII 0236 (\c +.BR '^' ). +In the standard table, EBCDIC 0232 (no graphic) is used. +.IP " 3." 4 +EBCDIC 0241 (\c +.BR '~' ) +translates to/from ASCII 0176 (\c +.BR '~' ). +In the standard table, EBCDIC 0137 (\c +.BR '\(no' ) +is used. +.IP " 4." 4 +0255 (\c +.BR '[' ) +and 0275 (\c +.BR ']' ) +appear twice, once in the same place as for the standard table and once +in place of 0112 (\c +.BR '\(ct' ) +and 0241 (\c +.BR '~' ). +.P +In net result: +.sp +.RS +EBCDIC 0275 (\c +.BR ']' ) +displaced EBCDIC 0241 (\c +.BR '~' ) +in cell 0345. +.P +\0\0\0\0That displaced EBCDIC 0137 (\c +.BR '\(no' ) +in cell 0176. +.P +\0\0\0\0That displaced EBCDIC 0232 (no graphic) in cell 0136. +.P +\0\0\0\0That replaced EBCDIC 0152 (broken pipe) in cell 0313. +.P +EBCDIC 0255 (\c +.BR '[' ) +replaced EBCDIC 0112 (\c +.BR '\(ct' ). +.RE +.P +This translation, however, reflects historical practice that (ASCII) +.BR '~' +and +.BR '\(no' +were often mapped to each other, as were +.BR '[' +and +.BR '\(ct' ; +and +.BR ']' +and (EBCDIC) +.BR '~' . +.P +The +.BR cbs +operand is required if any of the +.BR ascii , +.BR ebcdic , +or +.BR ibm +operands are specified. For the +.BR ascii +operand, the input is handled as described for the +.BR unblock +operand except that characters are converted to ASCII before the +trailing + +characters are deleted. For the +.BR ebcdic +and +.BR ibm +operands, the input is handled as described for the +.BR block +operand except that the characters are converted to EBCDIC or IBM +EBCDIC after the trailing + +characters are added. +.P +The +.BR block +and +.BR unblock +keywords are from historical BSD practice. +.P +The consistent use of the word +.BR record +in standard error messages matches most historical practice. An +earlier version of System V used +.BR block , +but this has been updated in more recent releases. +.P +Early proposals only allowed two numbers separated by +.BR x +to be used in a product when specifying +.BR bs =, +.BR cbs =, +.BR ibs =, +and +.BR obs = +sizes. This was changed to reflect the historical practice of allowing +multiple numbers in the product as provided by Version 7 and all +releases of System V and BSD. +.P +A change to the +.BR swab +conversion is required to match historical practice and is the result +of IEEE PASC Interpretations 1003.2 #03 and #04, submitted for the +ISO\ POSIX\(hy2:\|1993 standard. +.P +A change to the handling of SIGINT is required to match historical +practice and is the result of IEEE PASC Interpretation 1003.2 #06 +submitted for the ISO\ POSIX\(hy2:\|1993 standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.4" ", " "Utility Description Defaults", +.IR "\fIsed\fR\^", +.IR "\fItr\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/delta.1p b/man-pages-posix-2013-a/man1p/delta.1p new file mode 100644 index 0000000..2350903 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/delta.1p @@ -0,0 +1,342 @@ +'\" et +.TH DELTA "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +delta +\(em make a delta (change) to an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +delta \fB[\fR\(minps\fB] [\fR\(mig \fIlist\fB] [\fR\(mim \fImrlist\fB] [\fR\(mir \fISID\fB] [\fR\(miy\fB[\fIcomment\fB]] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR delta +utility shall be used to permanently introduce into the named SCCS +files changes that were made to the files retrieved by +.IR get +(called the +.IR g-files , +or generated files). +.SH OPTIONS +The +.IR delta +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the +.BR \(miy +option has an optional option-argument. This optional option-argument +shall not be presented as a separate argument. +.P +The following options shall be supported: +.IP "\fB\(mir\ \fISID\fR" 10 +Uniquely identify which delta is to be made to the SCCS file. The use +of this option shall be necessary only if two or more outstanding +.IR get +commands for editing (\c +.IR get +.BR \(mie ) +on the same SCCS file were done by the same person (login name). The +SID value specified with the +.BR \(mir +option can be either the SID specified on the +.IR get +command line or the SID to be made as reported by the +.IR get +utility; see +.IR "\fIget\fR\^". +.IP "\fB\(mis\fP" 10 +Suppress the report to standard output of the activity associated with +each +.IR file . +See the STDOUT section. +.IP "\fB\(min\fP" 10 +Specify retention of the edited +.IR g-file +(normally removed at completion of delta processing). +.IP "\fB\(mig\ \fIlist\fR" 10 +Specify a +.IR list +(see +.IR "\fIget\fR\^" +for the definition of +.IR list ) +of deltas that shall be ignored when the file is accessed at the +change level (SID) created by this delta. +.IP "\fB\(mim\ \fImrlist\fR" 10 +Specify a modification request (MR) number that the application shall +supply as the reason for creating the new delta. This shall be used if +the SCCS file has the +.BR v +flag set; see +.IR "\fIadmin\fR\^". +.RS 10 +.P +If +.BR \(mim +is not used and +.BR '\(mi' +is not specified as a file argument, and the standard input is a +terminal, the prompt described in the STDOUT section shall be written +to standard output before the standard input is read; if the standard +input is not a terminal, no prompt shall be issued. +.P +MRs in a list shall be separated by + +characters or escaped + +characters. An unescaped + +shall terminate the MR list. The escape character is +. +.P +If the +.BR v +flag has a value, it shall be taken to be the name of a program which +validates the correctness of the MR numbers. If a non-zero exit status +is returned from the MR number validation program, the +.IR delta +utility shall terminate. (It is assumed that the MR numbers were not +all valid.) +.RE +.IP "\fB\(miy\fB[\fIcomment\fB]\fR" 10 +Describe the reason for making the delta. The +.IR comment +shall be an arbitrary group of lines that would meet the definition of +a text file. Implementations shall support +.IR comment s +from zero to 512 bytes and may support longer values. A null string +(specified as either +.BR \(miy , +.BR \(miy \c +.BR \(dq\^\(dq , +or in response to a prompt for a comment) shall be considered a valid +.IR comment . +.RS 10 +.P +If +.BR \(miy +is not specified and +.BR '\(mi' +is not specified as a file argument, and the standard input is a +terminal, the prompt described in the STDOUT section shall be written +to standard output before the standard input is read; if the standard +input is not a terminal, no prompt shall be issued. An unescaped + +shall terminate the comment text. The escape character is +. +.P +The +.BR \(miy +option shall be required if the +.IR file +operand is specified as +.BR '\(mi' . +.RE +.IP "\fB\(mip\fP" 10 +Write (to standard output) the SCCS file differences before and after +the delta is applied in +.IR diff +format; see +.IR "\fIdiff\fR\^". +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR delta +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only in the following +cases: +.IP " *" 4 +To read an +.IR mrlist +or a +.IR comment +(see the +.BR \(mim +and +.BR \(miy +options). +.IP " *" 4 +A +.IR file +operand shall be specified as +.BR '\(mi' . +In this case, the +.BR \(miy +option must be used to specify the comment, and if the SCCS file has +the +.BR v +flag set, the +.BR \(mim +option must also be used to specify the MR list. +.SH "INPUT FILES" +Input files shall be text files whose data is to be included in the +SCCS files. If the first character of any line of an input file is + +in the POSIX locale, the results are unspecified. If this file contains +more than 99\|999 lines, the number of lines recorded in the header for +this file shall be 99\|999 for this delta. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR delta : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone in which the time and date are written in the +SCCS file. If the +.IR TZ +variable is unset or NULL, an unspecified system default timezone is +used. +.SH "ASYNCHRONOUS EVENTS" +If SIGINT is caught, temporary files shall be cleaned up and +.IR delta +shall exit with a non-zero exit code. The standard action shall +be taken for all other signals; see +.IR "Section 1.4" ", " "Utility Description Defaults". +.SH STDOUT +The standard output shall be used only for the following messages in +the POSIX locale: +.IP " *" 4 +Prompts (see the +.BR \(mim +and +.BR \(miy +options) in the following formats: +.RS 4 +.sp +.RS 4 +.nf +\fB +"MRs? " +.P +"comments? " +.fi \fR +.P +.RE +.P +The MR prompt, if written, shall always precede the comments prompt. +.RE +.IP " *" 4 +A report of each file's activities (unless the +.BR \(mis +option is specified) in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en%d inserted\en%d deleted\en%d unchanged\en", <\fINew SID\fR>, + <\fInumber of lines inserted\fR>, <\fInumber of lines deleted\fR>, + <\fInumber of lines unchanged\fR> +.fi \fR +.P +.RE +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Any SCCS files updated shall be files of an unspecified format. +.SH "EXTENDED DESCRIPTION" +.SS "System Date and Time" +.P +When a delta is added to an SCCS file, the system date and time shall +be recorded for the new delta. If a +.IR get +is performed using an SCCS file with a date recorded apparently in the +future, the behavior is unspecified. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Problems can arise if the system date and time have been modified (for +example, put forward and then back again, or unsynchronized clocks +across a network) and can also arise when different values of the +.IR TZ +environment variable are used. +.P +Problems of a similar nature can also arise for the operation of the +.IR get +utility, which records the date and time in the file body. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.4" ", " "Utility Description Defaults", +.IR "\fIadmin\fR\^", +.IR "\fIdiff\fR\^", +.IR "\fIget\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIrmdel\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/df.1p b/man-pages-posix-2013-a/man1p/df.1p new file mode 100644 index 0000000..ef1579d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/df.1p @@ -0,0 +1,332 @@ +'\" et +.TH DF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +df +\(em report free disk space +.SH SYNOPSIS +.LP +.nf +df \fB[\fR\(mik\fB] [\fR\(miP|\(mit\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR df +utility shall write the amount of available space +and file slots +for file systems on which the invoking user has appropriate read +access. File systems shall be specified by the +.IR file +operands; when none are specified, information shall be written for all +file systems. The format of the default output from +.IR df +is unspecified, but all space figures are reported in 512-byte units, +unless the +.BR \(mik +option is specified. This output shall contain at least the file system +names, amount of available space on each of these file systems, +and, if no options other than +.BR \(mit +are specified, the number of free file slots, or +.IR inode s, +available; when +.BR \(mit +is specified, the output shall contain the total allocated space as well. +.SH OPTIONS +The +.IR df +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mik\fP" 10 +Use 1\|024-byte units, instead of the default 512-byte units, when +writing space figures. +.IP "\fB\(miP\fP" 10 +Produce output in the format described in the STDOUT section. +.IP "\fB\(mit\fP" 10 +Include total allocated-space figures in the output. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file within the hierarchy of the desired file system. +If a file other than a FIFO, a regular file, a directory, +or a special file representing the device containing the file system +(for example, +.BR /dev/dsk/0s1 ) +is specified, the results are unspecified. If the +.IR file +operand names a file other than a special file containing a file +system, +.IR df +shall write the amount of free space in the file system containing the +specified +.IR file +operand. +Otherwise, +.IR df +shall write the amount of free space in that file system. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR df : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When both the +.BR \(mik +and +.BR \(miP +options are specified, the following header line shall be written (in +the POSIX locale): +.sp +.RS 4 +.nf +\fB +"Filesystem 1024-blocks Used Available Capacity Mounted on\en" +.fi \fR +.P +.RE +.P +When the +.BR \(miP +option is specified without the +.BR \(mik +option, the following header line shall be written (in the POSIX +locale): +.sp +.RS 4 +.nf +\fB +"Filesystem 512-blocks Used Available Capacity Mounted on\en" +.fi \fR +.P +.RE +.P +The implementation may adjust the spacing of the header line and the +individual data lines so that the information is presented in orderly +columns. +.P +The remaining output with +.BR \(miP +shall consist of one line of information for each specified +file system. These lines shall be formatted as follows: +.sp +.RS 4 +.nf +\fB +"%s %d %d %d %d%% %s\en", <\fIfile system name\fR>, <\fItotal space\fR>, + <\fIspace used\fR>, <\fIspace free\fR>, <\fIpercentage used\fR>, + <\fIfile system root\fR> +.fi \fR +.P +.RE +.P +In the following list, all quantities expressed in 512-byte units +(1\|024-byte when +.BR \(mik +is specified) shall be rounded up to the next higher unit. The fields +are: +.IP "<\fIfile\ system\ name\fP>" 10 +.br +The name of the file system, in an implementation-defined format. +.IP "<\fItotal\ space\fP>" 10 +The total size of the file system in 512-byte units. The exact meaning +of this figure is implementation-defined, but should include +<\fIspace\ used\fP>, <\fIspace\ free\fP>, plus any space reserved by +the system not normally available to a user. +.IP "<\fIspace\ used\fP>" 10 +The total amount of space allocated to existing files in the +file system, in 512-byte units. +.IP "<\fIspace\ free\fP>" 10 +The total amount of space available within the file system for the +creation of new files by unprivileged users, in 512-byte units. When +this figure is less than or equal to zero, it shall not be possible to +create any new files on the file system without first deleting others, +unless the process has appropriate privileges. The figure written may +be less than zero. +.IP "<\fIpercentage\ used\fP>" 10 +.br +The percentage of the normally available space that is currently +allocated to all files on the file system. This shall be calculated +using the fraction: +.RS 10 +.sp +.RS 4 +.nf +\fB +<\fIspace used\fR>/( <\fIspace used\fR>+ <\fIspace free\fR>) +.fi \fR +.P +.RE +.P +expressed as a percentage. This percentage may be greater than 100 if +<\fIspace\ free\fP> is less than zero. The percentage value shall be +expressed as a positive integer, with any fractional result causing it +to be rounded to the next highest integer. +.RE +.IP "<\fIfile\ system\ root\fP>" 10 +.br +The directory below which the file system hierarchy appears. +.P +The output format is unspecified when +.BR \(mit +is used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +On most systems, the ``name of the file system, in an +implementation-defined format'' is the special file on which the +file system is mounted. +.P +On large file systems, the calculation specified for percentage used +can create huge rounding errors. +.SH EXAMPLES +.IP " 1." 4 +The following example writes portable information about the +.BR /usr +file system: +.RS 4 +.sp +.RS 4 +.nf +\fB +df \(miP /usr +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Assuming that +.BR /usr/src +is part of the +.BR /usr +file system, the following produces the same output as the previous +example: +.RS 4 +.sp +.RS 4 +.nf +\fB +df \(miP /usr/src +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The behavior of +.IR df +with the +.BR \(miP +option is the default action of the 4.2 BSD +.IR df +utility. The uppercase +.BR \(miP +was selected to avoid collision with a known industry extension using +.BR \(mip . +.P +Historical +.IR df +implementations vary considerably in their default output. It was +therefore necessary to describe the default output in a loose manner to +accommodate all known historical implementations and to add a portable +option (\c +.BR \(miP ) +to provide information in a portable format. +.P +The use of 512-byte units is historical practice and maintains +compatibility with +.IR ls +and other utilities in this volume of POSIX.1\(hy2008. This does not mandate that the +file system itself be based on 512-byte blocks. The +.BR \(mik +option was added as a compromise measure. It was agreed by the standard +developers that 512 bytes was the best default unit because of its +complete historical consistency on System V (\fIversus\fP the mixed +512/1\|024-byte usage on BSD systems), and that a +.BR \(mik +option to switch to 1\|024-byte units was a good compromise. Users who +prefer the more logical 1\|024-byte quantity can easily alias +.IR df +to +.IR df +.BR \(mik +without breaking many historical scripts relying on the 512-byte +units. +.P +It was suggested that +.IR df +and the various related utilities be modified to access a +.IR BLOCKSIZE +environment variable to achieve consistency and user acceptance. Since +this is not historical practice on any system, it is left as a possible +area for system extensions and will be re-evaluated in a future version +if it is widely implemented. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/diff.1p b/man-pages-posix-2013-a/man1p/diff.1p new file mode 100644 index 0000000..d41c898 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/diff.1p @@ -0,0 +1,1001 @@ +'\" et +.TH DIFF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +diff +\(em compare two files +.SH SYNOPSIS +.LP +.nf +diff \fB[\fR\(mic|\(mie|\(mif|\(miu|\(miC \fIn\fR|\(miU \fIn\fB] [\fR\(mibr\fB] \fIfile1 file2\fR +.fi +.SH DESCRIPTION +The +.IR diff +utility shall compare the contents of +.IR file1 +and +.IR file2 +and write to standard output a list of changes necessary to convert +.IR file1 +into +.IR file2 . +This list should be minimal. No output shall be produced if the files +are identical. +.SH OPTIONS +The +.IR diff +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mib\fP" 10 +Cause any amount of white space at the end of a line to be treated as a +single + +(that is, the white-space characters preceding the + +are ignored) and other strings of white-space characters, not including + +characters, to compare equal. +.IP "\fB\(mic\fP" 10 +Produce output in a form that provides three lines of copied context. +.IP "\fB\(miC\ \fIn\fR" 10 +Produce output in a form that provides +.IR n +lines of copied context (where +.IR n +shall be interpreted as a positive decimal integer). +.IP "\fB\(mie\fP" 10 +Produce output in a form suitable as input for the +.IR ed +utility, which can then be used to convert +.IR file1 +into +.IR file2 . +.IP "\fB\(mif\fP" 10 +Produce output in an alternative form, similar in format to +.BR \(mie , +but not intended to be suitable as input for the +.IR ed +utility, and in the opposite order. +.IP "\fB\(mir\fP" 10 +Apply +.IR diff +recursively to files and directories of the same name when +.IR file1 +and +.IR file2 +are both directories. +.RS 10 +.P +The +.IR diff +utility shall detect infinite loops; that is, entering a previously +visited directory that is an ancestor of the last file encountered. +When it detects an infinite loop, +.IR diff +shall write a diagnostic message to standard error and shall either +recover its position in the hierarchy or terminate. +.RE +.IP "\fB\(miu\fP" 10 +Produce output in a form that provides three lines of unified context. +.IP "\fB\(miU\ \fIn\fR" 10 +Produce output in a form that provides +.IR n +lines of unified context (where +.IR n +shall be interpreted as a non-negative decimal integer). +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fR,\ \fIfile2\fR" 10 +A pathname of a file to be compared. If either the +.IR file1 +or +.IR file2 +operand is +.BR '\(mi' , +the standard input shall be used in its place. +.P +If both +.IR file1 +and +.IR file2 +are directories, +.IR diff +shall not compare block special files, character special files, or FIFO +special files to any files and shall not compare regular files to +directories. +Further details are as specified in +.IR "Diff Directory Comparison Format". +The behavior of +.IR diff +on other file types is implementation-defined when found in directories. +.P +If only one of +.IR file1 +and +.IR file2 +is a directory, +.IR diff +shall be applied to the non-directory file and the file contained in +the directory file with a filename that is the same as the last +component of the non-directory file. +.SH STDIN +The standard input shall be used only if one of the +.IR file1 +or +.IR file2 +operands references standard input. See the INPUT FILES section. +.SH "INPUT FILES" +The input files may be of any type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR diff : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the locale for affecting the format of file timestamps +written with the +.BR \(miC +and +.BR \(mic +options. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used for calculating file timestamps written +with a context format. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +.SS "Diff Directory Comparison Format" +.P +If both +.IR file1 +and +.IR file2 +are directories, the following output formats shall be used. +.P +In the POSIX locale, each file that is present in only one directory +shall be reported using the following format: +.sp +.RS 4 +.nf +\fB +"Only in %s: %s\en", <\fIdirectory pathname\fP>, <\fIfilename\fR> +.fi \fR +.P +.RE +.P +In the POSIX locale, subdirectories that are common to the two +directories may be reported with the following format: +.sp +.RS 4 +.nf +\fB +"Common subdirectories: %s and %s\en", <\fIdirectory1 pathname\fR>, + <\fIdirectory2 pathname\fR> +.fi \fR +.P +.RE +.P +For each file common to the two directories, if the two files are not to +be compared: if the two files have the same device ID and file +serial number, or are both block special files that refer to the +same device, or are both character special files that refer to the +same device, in the POSIX locale the output format is unspecified. +Otherwise, in the POSIX locale an unspecified format shall be used +that contains the pathnames of the two files. +.P +For each file common to the two directories, if the files are +compared and are identical, no output shall be written. If the two +files differ, the following format is written: +.sp +.RS 4 +.nf +\fB +"diff %s %s %s\en", <\fIdiff_options\fR>, <\fIfilename1\fR>, <\fIfilename2\fR> +.fi \fR +.P +.RE +.P +where <\fIdiff_options\fP> are the options as specified on the command +line. +.P +All directory pathnames listed in this section shall be relative to the +original command line arguments. All other names of files listed in +this section shall be filenames (pathname components). +.SS "Diff Binary Output Format" +.P +In the POSIX locale, if one or both of the files being compared are not +text files, it is implementation-defined whether +.IR diff +uses the binary file output format or the other formats as specified +below. The binary file output format shall contain the pathnames of +two files being compared and the string +.BR \(dqdiffer\(dq . +.P +If both files being compared are text files, depending on the options +specified, one of the following formats shall be used to write the +differences. +.SS "Diff Default Output Format" +.P +The default (without +.BR \(mie , +.BR \(mif , +.BR \(mic , +.BR \(miC , +.BR \(miu , +or +.BR \(miU +options) +.IR diff +utility output shall contain lines of these forms: +.sp +.RS 4 +.nf +\fB +"%da%d\en", <\fInum1\fR>, <\fInum2\fR> +.P +"%da%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR> +.P +"%dd%d\en", <\fInum1\fR>, <\fInum2\fR> +.P +"%d,%dd%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR> +.P +"%dc%d\en", <\fInum1\fR>, <\fInum2\fR> +.P +"%d,%dc%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR> +.P +"%dc%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR> +.P +"%d,%dc%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>, <\fInum4\fR> +.fi \fR +.P +.RE +.P +These lines resemble +.IR ed +subcommands to convert +.IR file1 +into +.IR file2 . +The line numbers before the action letters shall pertain to +.IR file1 ; +those after shall pertain to +.IR file2 . +Thus, by exchanging +.IR a +for +.IR d +and reading the line in reverse order, one can also determine how to +convert +.IR file2 +into +.IR file1 . +As in +.IR ed , +identical pairs (where +.IR num1 = +.IR num2 ) +are abbreviated as a single number. +.P +Following each of these lines, +.IR diff +shall write to standard output all lines affected in the first +file using the format: +.sp +.RS 4 +.nf +\fB +"< %s", <\fIline\fR> +.fi \fR +.P +.RE +.P +and all lines affected in the second file using the format: +.sp +.RS 4 +.nf +\fB +"> %s", <\fIline\fR> +.fi \fR +.P +.RE +.P +If there are lines affected in both +.IR file1 +and +.IR file2 +(as with the +.BR c +subcommand), the changes are separated with a line consisting of three + +characters: +.sp +.RS 4 +.nf +\fB +"\(mi\|\(mi\|\(mi\en" +.fi \fR +.P +.RE +.SS "Diff \(mie Output Format" +.P +With the +.BR \(mie +option, a script shall be produced that shall, when provided as input +to +.IR ed , +along with an appended +.BR w +(write) command, convert +.IR file1 +into +.IR file2 . +Only the +.BR a +(append), +.BR c +(change), +.BR d +(delete), +.BR i +(insert), and +.BR s +(substitute) commands of +.IR ed +shall be used in this script. Text lines, except those consisting of +the single character + +(\c +.BR '.' ), +shall be output as they appear in the file. +.SS "Diff \(mif Output Format" +.P +With the +.BR \(mif +option, an alternative format of script shall be produced. It is +similar to that produced by +.BR \(mie , +with the following differences: +.IP " 1." 4 +It is expressed in reverse sequence; the output of +.BR \(mie +orders changes from the end of the file to the beginning; the +.BR \(mif +from beginning to end. +.IP " 2." 4 +The command form <\fIlines\fP> <\fIcommand-letter\fR> used by +.BR \(mie +is reversed. For example, 10\fIc\fP with +.BR \(mie +would be +.IR c 10 +with +.BR \(mif . +.IP " 3." 4 +The form used for ranges of line numbers is +-separated, +rather than +-separated. +.SS "Diff \(mic or \(miC Output Format" +.P +With the +.BR \(mic +or +.BR \(miC +option, the output format shall consist of affected lines along with +surrounding lines of context. The affected lines shall show which ones +need to be deleted or changed in +.IR file1 , +and those added from +.IR file2 . +With the +.BR \(mic +option, three lines of context, if available, shall be written before +and after the affected lines. With the +.BR \(miC +option, the user can specify how many lines of context are written. +The exact format follows. +.P +The name and last modification time of each file shall be output in the +following format: +.sp +.RS 4 +.nf +\fB +"*** %s %s\en", \fIfile1\fR, <\fIfile1 timestamp\fR> +"\(mi\|\(mi\|\(mi %s %s\en", \fIfile2\fR, <\fIfile2 timestamp\fR> +.fi \fR +.P +.RE +.P +Each <\fIfile\fP> field shall be the pathname of the corresponding +file being compared. The pathname written for standard input is +unspecified. +.P +In the POSIX locale, each <\fItimestamp\fP> field shall be equivalent +to the output from the following command: +.sp +.RS 4 +.nf +\fB +date "+%a %b %e %T %Y" +.fi \fR +.P +.RE +.P +without the trailing +, +executed at the time of last modification of the corresponding file (or +the current time, if the file is standard input). +.P +Then, the following output formats shall be applied for every set of +changes. +.P +First, a line shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"***************\en" +.fi \fR +.P +.RE +.P +Next, the range of lines in +.IR file1 +shall be written in the following format if the range contains +two or more lines: +.sp +.RS 4 +.nf +\fB +"*** %d,%d ****\en", <\fIbeginning line number\fR>, <\fIending line number\fR> +.fi \fR +.P +.RE +.P +and the following format otherwise: +.sp +.RS 4 +.nf +\fB +"*** %d ****\en", <\fIending line number\fR> +.fi \fR +.P +.RE +.P +The ending line number of an empty range shall be the number of the +preceding line, or 0 if the range is at the start of the file. +.P +Next, the affected lines along with lines of context (unaffected lines) +shall be written. Unaffected lines shall be written in the following +format: +.sp +.RS 4 +.nf +\fB +" %s", <\fIunaffected_line\fR> +.fi \fR +.P +.RE +.P +Deleted lines shall be written as: +.sp +.RS 4 +.nf +\fB +"\(mi %s", <\fIdeleted_line\fR> +.fi \fR +.P +.RE +.P +Changed lines shall be written as: +.sp +.RS 4 +.nf +\fB +"! %s", <\fIchanged_line\fR> +.fi \fR +.P +.RE +.P +Next, the range of lines in +.IR file2 +shall be written in the following format if the range contains two +or more lines: +.sp +.RS 4 +.nf +\fB +"\(mi\|\(mi\|\(mi %d,%d \(mi\|\(mi\|\(mi\|\(mi\en", <\fIbeginning line number\fR>, <\fIending line number\fR> +.fi \fR +.P +.RE +.P +and the following format otherwise: +.sp +.RS 4 +.nf +\fB +"\(mi\|\(mi\|\(mi %d \(mi\|\(mi\|\(mi\|\(mi\en", <\fIending line number\fR> +.fi \fR +.P +.RE +.P +Then, lines of context and changed lines shall be written as described in +the previous formats. Lines added from +.IR file2 +shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"+ %s", <\fIadded_line\fR> +.fi \fR +.P +.RE +.SS "Diff \(miu or \(miU Output Format" +.P +The +.BR \(miu +or +.BR \(miU +options behave like the +.BR \(mic +or +.BR \(miC +options, except that the context lines are not repeated; instead, +the context, deleted, and added lines are shown together, interleaved. +The exact format follows. +.P +The name and last modification time of each file shall be output +in the following format: +.sp +.RS 4 +.nf +\fB +"--- %s\t%s%s %s\n", file1, , , +"+++ %s\t%s%s %s\n", file2, , , +.fi \fR +.P +.RE +.P +Each <\fIfile\fR> field shall be the pathname of the corresponding file +being compared, or the single character +.BR '\(mi' +if standard input is being compared. However, if the pathname contains +a + +or a +, +or if it does not consist entirely of characters taken +from the portable character set, the behavior is implementation-defined. +.P +Each <\fItimestamp\fR> field shall be equivalent to the output from the +following command: +.sp +.RS 4 +.nf +\fB +date '+%Y-%m-%d %H:%M:%S' +.fi \fR +.P +.RE +.P +without the trailing +, +executed at the time of last modification of the corresponding file +(or the current time, if the file is standard input). +.P +Each <\fIfrac\fR> field shall be either empty, or a decimal point +followed by at least one decimal digit, indicating the +fractional-seconds part (if any) of the file timestamp. The +number of fractional digits shall be at least the number needed to +represent the file's timestamp without loss of information. +.P +Each <\fIzone\fR> field shall be of the form +.BR \(dqshhmm\(dq , +where +.BR \(dqshh\(dq +is a signed two-digit decimal number in the range \(mi24 through +25, and +.BR \(dqmm\(dq +is an unsigned two-digit decimal number in the range 00 through 59. +It represents the timezone of the timestamp as the number of hours +(hh) and minutes (mm) east (+) or west (\(mi) of UTC for the timestamp. +If the hours and minutes are both zero, the sign shall be +.BR '+' . +However, if the timezone is not an integral number of minutes away +from UTC, the <\fIzone\fR> field is implementation-defined. +.P +Then, the following output formats shall be applied for every set +of changes. +.P +First, the range of lines in each file shall be written in the +following format: +.sp +.RS 4 +.nf +\fB +"@@ -%s +%s @@", , +.fi \fR +.P +.RE +.P +Each <\fIrange\fR> field shall be of the form: +.sp +.RS 4 +.nf +\fB +"%1d", +.fi \fR +.P +.RE +.P +if the range contains exactly one line, and: +.sp +.RS 4 +.nf +\fB +"%1d,%1d", , +.fi \fR +.P +.RE +.P +otherwise. If a range is empty, its beginning line number shall be +the number of the line just before the range, or 0 if the empty +range starts the file. +.P +Next, the affected lines along with lines of context shall be written. +Each non-empty unaffected line shall be written in the following format: +.sp +.RS 4 +.nf +\fB +" %s", +.fi \fR +.P +.RE +.P +where the contents of the unaffected line shall be taken from +.IR file1 . +It is implementation-defined whether an empty unaffected line is written +as an empty line or a line containing a single + +character. This line also represents the same line of +.IR file2 , +even though +.IR file2 's +line may contain different contents due to the +.BR \(mib . +Deleted lines shall be written as: +.sp +.RS 4 +.nf +\fB +"-%s", +.fi \fR +.P +.RE +.P +Added lines shall be written as: +.sp +.RS 4 +.nf +\fB +"+%s", +.fi \fR +.P +.RE +.P +The order of lines written shall be the same as that of the +corresponding file. A deleted line shall never be written +immediately after an added line. +.P +If +.BR \(miU +.IR n +is specified, the output shall contain no more than +.IR n +consecutive unaffected lines; and if the output contains an +affected line and this line is adjacent to up to +.IR n +consecutive unaffected lines in the corresponding file, the output shall +contain these unaffected lines. +.BR \(miu +shall act like +.BR \(miU 3. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +No differences were found. +.IP "\01" 6 +Differences were found. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If lines at the end of a file are changed and other lines are added, +.IR diff +output may show this as a delete and add, as a change, or as a change +and add; +.IR diff +is not expected to know which happened and users should not care about +the difference in output as long as it clearly shows the differences +between the files. +.SH EXAMPLES +If +.BR dir1 +is a directory containing a directory named +.BR x , +.BR dir2 +is a directory containing a directory named +.BR x , +.BR dir1/x +and +.BR dir2/x +both contain files named +.BR date.out , +and +.BR dir2/x +contains a file named +.BR y , +the command: +.sp +.RS 4 +.nf +\fB +diff \(mir dir1 dir2 +.fi \fR +.P +.RE +.P +could produce output similar to: +.sp +.RS 4 +.nf +\fB +Common subdirectories: dir1/x and dir2/x +Only in dir2/x: y +diff \(mir dir1/x/date.out dir2/x/date.out +1c1 +< Mon Jul 2 13:12:16 PDT 1990 +\(mi\|\(mi\|\(mi +> Tue Jun 19 21:41:39 PDT 1990 +.fi \fR +.P +.RE +.SH RATIONALE +The +.BR \(mih +option was omitted because it was insufficiently specified and does not +add to applications portability. +.P +Historical implementations employ algorithms that do not always produce +a minimum list of differences; the current language about making every +effort is the best this volume of POSIX.1\(hy2008 can do, as there is no metric that could be +employed to judge the quality of implementations against any and all +file contents. The statement ``This list should be minimal'' clearly +implies that implementations are not expected to provide the following +output when comparing two 100-line files that differ in only one +character on a single line: +.sp +.RS 4 +.nf +\fB +1,100c1,100 +all 100 lines from file1 preceded with "< " +\(mi\|\(mi\|\(mi +all 100 lines from file2 preceded with "> " +.fi \fR +.P +.RE +.P +The ``Only in'' messages required when the +.BR \(mir +option is specified are not used by most historical implementations if +the +.BR \(mie +option is also specified. It is required here because it provides +useful information that must be provided to update a target directory +hierarchy to match a source hierarchy. The ``Common subdirectories'' +messages are written by System V and 4.3 BSD when the +.BR \(mir +option is specified. They are allowed here but are not required because +they are reporting on something that is the same, not reporting a +difference, and are not needed to update a target hierarchy. +.P +The +.BR \(mic +option, which writes output in a format using lines of context, has +been included. The format is useful for a variety of reasons, among +them being much improved readability and the ability to understand +difference changes when the target file has line numbers that differ +from another similar, but slightly different, copy. The +.IR patch +utility is most valuable when working with difference listings using +a context format. The BSD version of +.BR \(mic +takes an optional argument specifying the amount of context. Rather +than overloading +.BR \(mic +and breaking the Utility Syntax Guidelines for +.IR diff , +the standard developers decided to add a separate option for specifying +a context diff with a specified amount of context (\c +.BR \(miC ). +Also, the format for context +.IR diff s +was extended slightly in 4.3 BSD to allow multiple changes that are +within context lines from each other to be merged together. The output +format contains an additional four + +characters after the range of affected lines in the first filename. This +was to provide a flag for old programs (like old versions of +.IR patch ) +that only understand the old context format. The version of context +described here does not require that multiple changes within context +lines be merged, but it does not prohibit it either. The extension is +upwards-compatible, so any vendors that wish to retain the old version +of +.IR diff +can do so by adding the extra four + +characters (that is, utilities that currently use +.IR diff +and understand the new merged format will also understand the old +unmerged format, but not \fIvice versa\fP). +.P +The +.BR \(miu +and +.BR \(miU +options of GNU +.IR diff +have been included. Their output format, designed by Wayne Davison, +takes up less space than +.BR \(mic +and +.BR \(miC +format, and in many cases is easier to read. The format's timestamps +do not vary by locale, so +.IR LC_TIME +does not affect it. The format's line numbers are rendered with the +.BR %1d +format, not +.BR %d , +because the file format notation rules would allow extra + +characters to appear around the numbers. +.P +The substitute command was added as an additional format for the +.BR \(mie +option. This was added to provide implementations with a way to fix the +classic ``dot alone on a line'' bug present in many versions of +.IR diff . +Since many implementations have fixed this bug, the standard developers +decided not to standardize broken behavior, but rather to provide the +necessary tool for fixing the bug. One way to fix this bug is to output +two periods whenever a lone period is needed, then terminate the append +command with a period, and then use the substitute command to convert +the two periods into one period. +.P +The BSD-derived +.BR \(mir +option was added to provide a mechanism for using +.IR diff +to compare two file system trees. This behavior is useful, is standard +practice on all BSD-derived systems, and is not easily reproducible +with the +.IR find +utility. +.P +The requirement that +.IR diff +not compare files in some circumstances, even though they have the same +name, is based on the actual output of historical implementations. +The specified behavior precludes the problems arising from running +into FIFOs and other files that would cause +.IR diff +to hang waiting for input with no indication to the user that +.IR diff +was hung. An earlier version of this standard specified the output +format more precisely, but in practice this requirement was widely +ignored and the benefit of standardization seemed small, so it is now +unspecified. In most common usage, +.IR diff +.BR \(mir +should indicate differences in the file hierarchies, not the difference +of contents of devices pointed to by the hierarchies. +.P +Many early implementations of +.IR diff +require seekable files. Since the System Interfaces volume of POSIX.1\(hy2008 supports named pipes, the +standard developers decided that such a restriction was unreasonable. +Note also that the allowed filename +.BR \(mi +almost always refers to a pipe. +.P +No directory search order is specified for +.IR diff . +The historical ordering is, in fact, not optimal, in that it prints out +all of the differences at the current level, including the statements +about all common subdirectories before recursing into those +subdirectories. +.P +The message: +.sp +.RS 4 +.nf +\fB +"diff %s %s %s\en", <\fIdiff_options\fP>, <\fIfilename1\fP>, <\fIfilename2\fP> +.fi \fR +.P +.RE +.P +does not vary by locale because it is the representation of a command, +not an English sentence. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcmp\fR\^", +.IR "\fIcomm\fR\^", +.IR "\fIed\fR\^", +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/dirname.1p b/man-pages-posix-2013-a/man1p/dirname.1p new file mode 100644 index 0000000..6e1e187 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/dirname.1p @@ -0,0 +1,260 @@ +'\" et +.TH DIRNAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dirname +\(em return the directory portion of a pathname +.SH SYNOPSIS +.LP +.nf +dirname \fIstring\fR +.fi +.SH DESCRIPTION +The +.IR string +operand shall be treated as a pathname, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname". +The string +.IR string +shall be converted to the name of the directory containing the +filename corresponding to the last pathname component in +.IR string , +performing actions equivalent to the following steps in order: +.IP " 1." 4 +If +.IR string +is +.BR // , +skip steps 2 to 5. +.IP " 2." 4 +If +.IR string +consists entirely of + +characters, +.IR string +shall be set to a single + +character. In this case, skip steps 3 to 8. +.IP " 3." 4 +If there are any trailing + +characters in +.IR string , +they shall be removed. +.IP " 4." 4 +If there are no + +characters remaining in +.IR string , +.IR string +shall be set to a single + +character. In this case, skip steps 5 to 8. +.IP " 5." 4 +If there are any trailing non-\c + +characters in +.IR string , +they shall be removed. +.IP " 6." 4 +If the remaining +.IR string +is +.BR // , +it is implementation-defined whether steps 7 and 8 are skipped or +processed. +.IP " 7." 4 +If there are any trailing + +characters in +.IR string , +they shall be removed. +.IP " 8." 4 +If the remaining +.IR string +is empty, +.IR string +shall be set to a single + +character. +.P +The resulting string shall be written to standard output. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIstring\fR" 10 +A string. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR dirname : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR dirname +utility shall write a line to the standard output in the following +format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIresulting string\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The definition of +.IR pathname +specifies implementation-defined behavior for pathnames starting with +two + +characters. Therefore, applications shall not arbitrarily add + +characters to the beginning of a pathname unless they can ensure +that there are more or less than two or are prepared to deal with the +implementation-defined consequences. +.SH EXAMPLES +.TS +center tab(@) box; +cB | cB +l | l. +Command@Results +_ +\fIdirname\fR /@/ +\fIdirname\fR //@/ or // +\fIdirname\fR /\fIa\fR/\fIb\fR/@/\fIa\fR +\fIdirname\fR //\fIa\fR//\fIb\fR//@//\fIa\fR +\fIdirname\fR@Unspecified +\fIdirname a\fR@. ($? = 0) +\fIdirname\fR ""@. ($? = 0) +\fIdirname\fR /\fIa\fR@/ +\fIdirname\fR /\fIa\fR/\fIb\fR@/\fIa\fR +\fIdirname\fR \fIa\fR/\fIb\fR@\fIa\fR +.TE +.P +See also the examples for the +.IR basename +utility. +.SH RATIONALE +The +.IR dirname +utility originated in System III. It has evolved through the System V +releases to a version that matches the requirements specified in this +description in System V Release 3. 4.3 BSD and earlier versions did +not include +.IR dirname . +.P +The behaviors of +.IR basename +and +.IR dirname +in this volume of POSIX.1\(hy2008 have been coordinated so that when +.IR string +is a valid pathname: +.sp +.RS 4 +.nf +\fB +$(basename -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +would be a valid filename for the file in the directory: +.sp +.RS 4 +.nf +\fB +$(dirname -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +This would not work for the versions of these utilities in early proposals +due to the way processing of trailing + +characters was specified. Consideration was given to leaving processing +unspecified if there were trailing + +characters, but this cannot be done; the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname" +allows trailing + +characters. The +.IR basename +and +.IR dirname +utilities have to specify consistent handling for all valid pathnames. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "\fIbasename\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname", +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/dot.1p b/man-pages-posix-2013-a/man1p/dot.1p new file mode 100644 index 0000000..5d2c527 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/dot.1p @@ -0,0 +1,116 @@ +'\" et +.TH DOT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dot +\(em execute commands in the current environment +.SH SYNOPSIS +.LP +.nf +\&. \fIfile\fR +.fi +.SH DESCRIPTION +The shell shall execute commands from the +.IR file +in the current environment. +.P +If +.IR file +does not contain a +, +the shell shall use the search path specified by +.IR PATH +to find the directory containing +.IR file . +Unlike normal command search, however, the file searched for by the +.IR dot +utility need not be executable. If no readable file is found, a +non-interactive shell shall abort; an interactive shell shall write a +diagnostic message to standard error, but this condition shall not be +considered a syntax error. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +See the DESCRIPTION. +.SH "ENVIRONMENT VARIABLES" +See the DESCRIPTION. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If no readable file was found or if the commands in the file could not +be parsed, and the shell is interactive (and therefore does not abort; see +.IR "Section 2.8.1" ", " "Consequences of Shell Errors"), +the exit status shall be non-zero. Otherwise, return the value of the +last command executed, or a zero exit status if no command is executed. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +cat foobar +\fBfoo=hello bar=world\fR +\&. ./foobar +echo $foo $bar +\fBhello world\fR +.fi +.SH "RATIONALE" +Some older implementations searched the current directory for the +.IR file , +even if the value of +.IR PATH +disallowed it. This behavior was omitted from this volume of POSIX.1\(hy2008 due to concerns +about introducing the susceptibility to trojan horses that the user +might be trying to avoid by leaving +.BR dot +out of +.IR PATH . +.P +The KornShell version of +.IR dot +takes optional arguments that are set to the positional parameters. +This is a valid extension that allows a +.IR dot +script to behave identically to a function. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIreturn\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/du.1p b/man-pages-posix-2013-a/man1p/du.1p new file mode 100644 index 0000000..cf0854a --- /dev/null +++ b/man-pages-posix-2013-a/man1p/du.1p @@ -0,0 +1,279 @@ +'\" et +.TH DU "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +du +\(em estimate file space usage +.SH SYNOPSIS +.LP +.nf +du \fB[\fR\(mia|\(mis\fB] [\fR\(mikx\fB] [\fR\(miH|\(miL\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +By default, the +.IR du +utility shall write to standard output the size of the file space +allocated to, and the size of the file space allocated to each +subdirectory of, the file hierarchy rooted in each of the specified +files. By default, when a symbolic link is encountered on the command +line or in the file hierarchy, +.IR du +shall count the size of the symbolic link (rather than the file +referenced by the link), and shall not follow the link to another +portion of the file hierarchy. The size of the file space allocated to +a file of type directory shall be defined as the sum total of space +allocated to all files in the file hierarchy rooted in the directory +plus the space allocated to the directory itself. +.P +When +.IR du +cannot +\fIstat\fR() +files or +\fIstat\fR() +or read directories, it shall report an error condition and the final +exit status is affected. Files with multiple links shall be counted and +written for only one entry. The directory entry that is selected in the +report is unspecified. By default, file sizes shall be written in +512-byte units, rounded up to the next 512-byte unit. +.SH OPTIONS +The +.IR du +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +In addition to the default output, report the size of each file not of +type directory in the file hierarchy rooted in the specified file. +Regardless of the presence of the +.BR \(mia +option, non-directories given as +.IR file +operands shall always be listed. +.IP "\fB\(miH\fP" 10 +If a symbolic link is specified on the command line, +.IR du +shall count the size of the file or file hierarchy referenced by the +link. +.IP "\fB\(mik\fP" 10 +Write the files sizes in units of 1\|024 bytes, rather than the default +512-byte units. +.IP "\fB\(miL\fP" 10 +If a symbolic link is specified on the command line or encountered +during the traversal of a file hierarchy, +.IR du +shall count the size of the file or file hierarchy referenced by the +link. +.IP "\fB\(mis\fP" 10 +Instead of the default output, report only the total sum for each of +the specified files. +.IP "\fB\(mix\fP" 10 +When evaluating file sizes, evaluate only those files that have the +same device as the file specified by the +.IR file +operand. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH +and +.BR \(miL +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a file whose size is to be written. If no +.IR file +is specified, the current directory shall be used. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR du : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The output from +.IR du +shall consist of the amount of space allocated to a file and the +name of the file, in the following format: +.sp +.RS 4 +.nf +\fB +"%d %s\en", <\fIsize\fR>, <\fIpathname\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The use of 512-byte units is historical practice and maintains +compatibility with +.IR ls +and other utilities in this volume of POSIX.1\(hy2008. This does not mandate that the +file system itself be based on 512-byte blocks. The +.BR \(mik +option was added as a compromise measure. It was agreed by the standard +developers that 512 bytes was the best default unit because of its +complete historical consistency on System V (\fIversus\fP the mixed +512/1\|024-byte usage on BSD systems), and that a +.BR \(mik +option to switch to 1\|024-byte units was a good compromise. Users who +prefer the 1\|024-byte quantity can easily alias +.IR du +to +.IR du +.BR \(mik +without breaking the many historical scripts relying on the 512-byte +units. +.P +The +.BR \(mib +option was added to an early proposal to provide a resolution to the +situation where System V and BSD systems give figures for file sizes in +.IR blocks , +which is an implementation-defined concept. (In common usage, the +block size is 512 bytes for System V and 1\|024 bytes for BSD systems.) +However, +.BR \(mib +was later deleted, since the default was eventually decided as 512-byte +units. +.P +Historical file systems provided no way to obtain exact figures for the +space allocation given to files. There are two known areas of +inaccuracies in historical file systems: cases of +.IR "indirect blocks" +being used by the file system or +.IR "sparse" +files yielding incorrectly high values. An indirect block is space used +by the file system in the storage of the file, but that need not be +counted in the space allocated to the file. A +.IR sparse +file is one in which an +\fIlseek\fR() +call has been made to a position beyond the end of the file and data +has subsequently been written at that point. A file system need not +allocate all the intervening zero-filled blocks to such a file. It is +up to the implementation to define exactly how accurate its methods +are. +.P +The +.BR \(mia +and +.BR \(mis +options were mutually-exclusive in the original version of +.IR du . +The POSIX Shell and Utilities description is implied by the language in +the SVID where +.BR \(mis +is described as causing ``only the grand total'' to be reported. Some +systems may produce output for +.BR \(misa , +but a Strictly Conforming POSIX Shell and Utilities Application cannot +use that combination. +.P +The +.BR \(mia +and +.BR \(mis +options were adopted from the SVID except that the System V behavior of +not listing non-directories explicitly given as operands, unless the +.BR \(mia +option is specified, was considered a bug; the BSD-based behavior +(report for all operands) is mandated. The default behavior of +.IR du +in the SVID with regard to reporting the failure to read files (it +produces no messages) was considered counter-intuitive, and thus it was +specified that the POSIX Shell and Utilities default behavior shall be +to produce such messages. These messages can be turned off with shell +redirection to achieve the System V behavior. +.P +The +.BR \(mix +option is historical practice on recent BSD systems. It has been +adopted by this volume of POSIX.1\(hy2008 because there was no other historical method of +limiting the +.IR du +search to a single file hierarchy. This limitation of the search is +necessary to make it possible to obtain file space usage information +about a file system on which other file systems are mounted, without +having to resort to a lengthy +.IR find +and +.IR awk +script. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIls\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfstatat\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/echo.1p b/man-pages-posix-2013-a/man1p/echo.1p new file mode 100644 index 0000000..da31e54 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/echo.1p @@ -0,0 +1,266 @@ +'\" et +.TH ECHO "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +echo +\(em write arguments to standard output +.SH SYNOPSIS +.LP +.nf +echo \fB[\fIstring\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR echo +utility writes its arguments to standard output, followed by a +. +If there are no arguments, only the + +is written. +.SH OPTIONS +The +.IR echo +utility shall not recognize the +.BR \(dq\(mi\|\(mi\(dq +argument in the manner specified by Guideline 10 of the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines"; +.BR \(dq\(mi\|\(mi\(dq +shall be recognized as a string operand. +.P +Implementations shall not support any options. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIstring\fR" 10 +A string to be written to standard output. If the first operand is +.BR \(min , +or if any of the operands contain a + +character, the results are implementation-defined. +.RS 10 +.P +On XSI-conformant systems, if the first operand is +.BR \(min , +it shall be treated as a string, not an option. The following character +sequences shall be recognized on XSI-conformant systems within any of +the arguments: +.IP "\fR\ea\fR" 8 +Write an +. +.IP "\fR\eb\fR" 8 +Write a +. +.IP "\fR\ec\fR" 8 +Suppress the + +that otherwise follows the final argument in the output. All +characters following the +.BR '\ec' +in the arguments shall be ignored. +.IP "\fR\ef\fR" 8 +Write a +. +.IP "\fR\en\fR" 8 +Write a +. +.IP "\fR\er\fR" 8 +Write a +. +.IP "\fR\et\fR" 8 +Write a +. +.IP "\fR\ev\fR" 8 +Write a +. +.IP "\fR\e\e\fR" 8 +Write a + +character. +.IP "\fR\e0\fInum\fR" 8 +Write an 8-bit value that is the zero, one, two, or three-digit octal +number +.IR num . +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR echo : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR echo +utility arguments shall be separated by single + +characters and a + +character shall follow the last argument. +Output transformations shall occur based on the escape sequences in +the input. See the OPERANDS section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +It is not possible to use +.IR echo +portably across all POSIX systems unless both +.BR \(min +(as the first argument) and escape sequences are omitted. +.P +The +.IR printf +utility can be used portably to emulate any of the traditional +behaviors of the +.IR echo +utility as follows (assuming that +.IR IFS +has its standard value or is unset): +.IP " *" 4 +The historic System V +.IR echo +and the requirements on XSI implementations in this volume of POSIX.1\(hy2008 are equivalent to: +.RS 4 +.sp +.RS 4 +.nf +\fB +printf "%b\en$*" +.fi \fR +.P +.RE +.RE +.IP " *" 4 +The BSD +.IR echo +is equivalent to: +.RS 4 +.sp +.RS 4 +.nf +\fB +if [ "X$1" = "X\(min" ] +then + shift + printf "%s$*" +else + printf "%s\en$*" +fi +.fi \fR +.P +.RE +.RE +.P +New applications are encouraged to use +.IR printf +instead of +.IR echo . +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR echo +utility has not been made obsolescent because of its extremely +widespread use in historical applications. Conforming applications that +wish to do prompting without + +characters or that could possibly be expecting to echo a +.BR \(min , +should use the +.IR printf +utility derived from the Ninth Edition system. +.P +As specified, +.IR echo +writes its arguments in the simplest of ways. The two different +historical versions of +.IR echo +vary in fatally incompatible ways. +.P +The BSD +.IR echo +checks the first argument for the string +.BR \(min +which causes it to suppress the + +that would otherwise follow the final argument in the output. +.P +The System V +.IR echo +does not support any options, but allows escape sequences within its +operands, as described for XSI implementations in the OPERANDS section. +.P +The +.IR echo +utility does not support Utility Syntax Guideline 10 because historical +applications depend on +.IR echo +to echo +.IR all +of its arguments, except for the +.BR \(min +option in the BSD version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIprintf\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ed.1p b/man-pages-posix-2013-a/man1p/ed.1p new file mode 100644 index 0000000..dd071cf --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ed.1p @@ -0,0 +1,2097 @@ +'\" et +.TH ED "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ed +\(em edit text +.SH SYNOPSIS +.LP +.nf +ed \fB[\fR\(mip \fIstring\fB] [\fR\(mis\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ed +utility is a line-oriented text editor that uses two modes: +.IR "command mode" +and +.IR "input mode" . +In command mode the input characters shall be interpreted as commands, +and in input mode they shall be interpreted as text. See the EXTENDED +DESCRIPTION section. +.P +If an operand is +.BR '\(mi' , +the results are unspecified. +.SH OPTIONS +The +.IR ed +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mip\ \fIstring\fR" 10 +Use +.IR string +as the prompt string when in command mode. By default, there shall be +no prompt string. +.IP "\fB\(mis\fP" 10 +Suppress the writing of byte counts by +.BR e , +.BR E , +.BR r , +and +.BR w +commands and of the +.BR '!' +prompt after a !\fIcommand\fR. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +If the +.IR file +argument is given, +.IR ed +shall simulate an +.BR e +command on the file named by the pathname, +.IR file , +before accepting commands from the standard input. +.SH STDIN +The standard input shall be a text file consisting of commands, as +described in the EXTENDED DESCRIPTION section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ed : +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +The +.IR ed +utility shall take the standard action for all signals (see the +ASYNCHRONOUS EVENTS section in +.IR "Section 1.4" ", " "Utility Description Defaults") +with the following exceptions: +.IP SIGINT 10 +The +.IR ed +utility shall interrupt its current activity, write the string +.BR \(dq?\en\(dq +to standard output, and return to command mode (see the EXTENDED +DESCRIPTION section). +.IP SIGHUP 10 +If the buffer is not empty and has changed since the last write, the +.IR ed +utility shall attempt to write a copy of the buffer in a file. First, +the file named +.BR ed.hup +in the current directory shall be used; if that fails, the file named +.BR ed.hup +in the directory named by the +.IR HOME +environment variable shall be used. In any case, the +.IR ed +utility shall exit without writing the file to the currently +remembered pathname and without returning to command mode. +.IP SIGQUIT 10 +The +.IR ed +utility shall ignore this event. +.SH STDOUT +Various editing commands and the prompting feature (see +.BR \(mip ) +write to standard output, as described in the EXTENDED DESCRIPTION +section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files shall be text files whose formats are dependent on the +editing commands given. +.SH "EXTENDED DESCRIPTION" +The +.IR ed +utility shall operate on a copy of the file it is editing; changes made +to the copy shall have no effect on the file until a +.BR w +(write) command is given. The copy of the text is called the +.IR buffer . +.P +Commands to +.IR ed +have a simple and regular structure: zero, one, or two +.IR addresses +followed by a single-character +.IR command , +possibly followed by parameters to that command. These addresses +specify one or more lines in the buffer. Every command that requires +addresses has default addresses, so that the addresses very often can +be omitted. If the +.BR \(mip +option is specified, the prompt string shall be written to standard +output before each command is read. +.P +In general, only one command can appear on a line. Certain commands +allow text to be input. This text is placed in the appropriate place in +the buffer. While +.IR ed +is accepting text, it is said to be in \fIinput mode\fR. In this mode, +no commands shall be recognized; all input is merely collected. Input +mode is terminated by entering a line consisting of two characters: a + +(\c +.BR '.' ) +followed by a +. +This line is not considered part of the input text. +.SS "Regular Expressions in ed" +.P +The +.IR ed +utility shall support basic regular expressions, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +Since regular expressions in +.IR ed +are always matched against single lines (excluding the terminating + +characters), never against any larger section of text, there is no way +for a regular expression to match a +. +.P +A null RE shall be equivalent to the last RE encountered. +.P +Regular expressions are used in addresses to specify lines, and in some +commands (for example, the +.BR s +substitute command) to specify portions of a line to be substituted. +.SS "Addresses in ed" +.P +Addressing in +.IR ed +relates to the current line. Generally, the current line is the last +line affected by a command. The current line number is the address of +the current line. If the edit buffer is not empty, the initial value +for the current line shall be the last line in the edit buffer; +otherwise, zero. +.P +Addresses shall be constructed as follows: +.IP " 1." 4 +The + +character (\c +.BR '.' ) +shall address the current line. +.IP " 2." 4 +The + +character (\c +.BR '$' ) +shall address the last line of the edit buffer. +.IP " 3." 4 +The positive decimal number +.IR n +shall address the +.IR n th +line of the edit buffer. +.IP " 4." 4 +The +-x +character pair (\c +.BR \(dq'x\(dq ) +shall address the line marked with the mark name character +.IR x , +which shall be a lowercase letter from the portable character set. It +shall be an error if the character has not been set to mark a line or +if the line that was marked is not currently present in the edit +buffer. +.IP " 5." 4 +A BRE enclosed by + +characters (\c +.BR '/' ) +shall address the first line found by searching forwards from the line +following the current line toward the end of the edit buffer and +stopping at the first line for which the line excluding the +terminating + +matches the BRE. The BRE consisting of a null BRE delimited by a pair of + +characters shall address the next line for which the line excluding +the terminating + +matches the last BRE encountered. In addition, the second + +can be omitted at the end of a command line. Within the BRE, a +-\c + +pair (\c +.BR \(dq\e/\(dq ) +shall represent a literal + +instead of the BRE delimiter. If necessary, the search shall wrap around +to the beginning of the buffer and continue up to and including the +current line, so that the entire buffer is searched. +.IP " 6." 4 +A BRE enclosed by + +characters (\c +.BR '?' ) +shall address the first line found by searching backwards from the line +preceding the current line toward the beginning of the edit buffer and +stopping at the first line for which the line excluding the terminating + +matches the BRE. The BRE consisting of a null BRE delimited by a pair +of + +characters (\c +.BR \(dq??\(dq ) +shall address the previous line for which the line excluding the +terminating + +matches the last BRE encountered. In addition, the second + +can be omitted at the end of a command line. Within the +BRE, a +-\c + +pair (\c +.BR \(dq\e?\(dq ) +shall represent a literal + +instead of the BRE delimiter. If necessary, the search shall wrap around +to the end of the buffer and continue up to and including the current +line, so that the entire buffer is searched. +.IP " 7." 4 +A + +(\c +.BR '\(pl' ) +or + +character (\c +.BR '\(mi' ) +followed by a decimal number shall address the current line plus or +minus the number. A + +or + +character not followed by a decimal number shall address the current +line plus or minus 1. +.P +Addresses can be followed by zero or more address offsets, optionally +-separated. +Address offsets are constructed as follows: +.IP " *" 4 +A + +or + +character followed by a decimal number shall add or subtract, +respectively, the indicated number of lines to or from the address. A + +or + +character not followed by a decimal number shall add or subtract 1 to +or from the address. +.IP " *" 4 +A decimal number shall add the indicated number of lines to the +address. +.P +It shall not be an error for an intermediate address value to be less +than zero or greater than the last line in the edit buffer. It shall be +an error for the final address value to be less than zero or greater +than the last line in the edit buffer. It shall be an error if a search +for a BRE fails to find a matching line. +.P +Commands accept zero, one, or two addresses. If more than the required +number of addresses are provided to a command that requires zero +addresses, it shall be an error. Otherwise, if more than the required +number of addresses are provided to a command, the addresses specified +first shall be evaluated and then discarded until the maximum number of +valid addresses remain, for the specified command. +.P +Addresses shall be separated from each other by a + +(\c +.BR ',' ) +or + +character (\c +.BR ';' ). +In the case of a + +separator, the current line (\c +.BR '.' ) +shall be set to the first address, and only then will the second +address be calculated. This feature can be used to determine the +starting line for forwards and backwards searches; see rules 5. and +6. +.P +Addresses can be omitted on either side of the + +or + +separator, in which case the resulting address pairs shall be as +follows: +.TS +center box tab(!); +cB | cB +lf5 | lf5. +Specified!Resulting +_ +\&,!1 , $ +\&, addr!1 , addr +addr ,!addr , addr +;!. ; $ +; addr!. ; addr +addr ;!addr ; addr +.TE +.P +Any + +characters included between addresses, address separators, or address +offsets shall be ignored. +.SS "Commands in ed" +.P +In the following list of +.IR ed +commands, the default addresses are shown in parentheses. The number of +addresses shown in the default shall be the number expected by the +command. The parentheses are not part of the address; they show that +the given addresses are the default. +.P +It is generally invalid for more than one command to appear on a line. +However, any command (except +.BR e , +.BR E , +.BR f , +.BR q , +.BR Q , +.BR r , +.BR w , +and +.BR ! ) +can be suffixed by the letter +.BR l , +.BR n , +or +.BR p ; +in which case, except for the +.BR l , +.BR n , +and +.BR p +commands, the command shall be executed and then the new current line +shall be written as described below under the +.BR l , +.BR n , +and +.BR p +commands. When an +.BR l , +.BR n , +or +.BR p +suffix is used with an +.BR l , +.BR n , +or +.BR p +command, the command shall write to standard output as described below, +but it is unspecified whether the suffix writes the current line again +in the requested format or whether the suffix has no effect. For +example, the +.BR pl +command (base +.BR p +command with an +.BR l +suffix) shall either write just the current line or write it +twice\(emonce as specified for +.BR p +and once as specified for +.BR l . +Also, the +.BR g , +.BR G , +.BR v , +and +.BR V +commands shall take a command as a parameter. +.P +Each address component can be preceded by zero or more + +characters. The command letter can be preceded by zero or more + +characters. If a suffix letter (\c +.BR l , +.BR n , +or +.BR p ) +is given, the application shall ensure that it immediately follows the +command. +.P +The +.BR e , +.BR E , +.BR f , +.BR r , +and +.BR w +commands shall take an optional +.IR file +parameter, separated from the command letter by one or more + +characters. +.P +If changes have been made in the buffer since the last +.BR w +command that wrote the entire buffer, +.IR ed +shall warn the user if an attempt is made to destroy the editor buffer +via the +.BR e +or +.BR q +commands. The +.IR ed +utility shall write the string: +.sp +.RS 4 +.nf +\fB +"?\en" +.fi \fR +.P +.RE +.P +(followed by an explanatory message if +.IR "help mode" +has been enabled via the +.BR H +command) to standard output and shall continue in command mode with the +current line number unchanged. If the +.BR e +or +.BR q +command is repeated with no intervening command, it shall take effect. +.P +If a terminal disconnect (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +Modem Disconnect and Closing a Device Terminal), is detected: +.IP " *" 4 +If accompanied by a SIGHUP signal, the +.IR ed +utility shall operate as described in the ASYNCHRONOUS EVENTS section +for a SIGHUP signal. +.IP " *" 4 +If not accompanied by a SIGHUP signal, the +.IR ed +utility shall act as if an end-of-file had been detected on standard +input. +.P +If an end-of-file is detected on standard input: +.IP " *" 4 +If the +.IR ed +utility is in input mode, +.IR ed +shall terminate input mode and return to command mode. It is +unspecified if any partially entered lines (that is, input text without +a terminating +) +are discarded from the input text. +.IP " *" 4 +If the +.IR ed +utility is in command mode, it shall act as if a +.BR q +command had been entered. +.P +If the closing delimiter of an RE or of a replacement string (for +example, +.BR '/' ) +in a +.BR g , +.BR G , +.BR s , +.BR v , +or +.BR V +command would be the last character before a +, +that delimiter can be omitted, in which case the addressed line shall +be written. For example, the following pairs of commands are +equivalent: +.sp +.RS 4 +.nf +\fB +s/s1/s2 s/s1/s2/p +g/s1 g/s1/p +?s1 ?s1? +.fi \fR +.P +.RE +.P +If an invalid command is entered, +.IR ed +shall write the string: +.sp +.RS 4 +.nf +\fB +"?\en" +.fi \fR +.P +.RE +.P +(followed by an explanatory message if +.IR "help mode" +has been enabled via the +.BR H +command) to standard output and shall continue in command mode with the +current line number unchanged. +.SS "Append Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.)a +<\fItext\fR> +\&. +.fi \fR +.P +.RE +.RE +.P +The +.BR a +command shall read the given text and append it after the addressed +line; the current line number shall become the address of the last +inserted line or, if there were none, the addressed line. Address 0 +shall be valid for this command; it shall cause the appended text to be +placed at the beginning of the buffer. +.SS "Change Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)c +<\fItext\fR> +\&. +.fi \fR +.P +.RE +.RE +.P +The +.BR c +command shall delete the addressed lines, then accept input text that +replaces these lines; the current line shall be set to the address of +the last line input; or, if there were none, at the line after the last +line deleted; if the lines deleted were originally at the end of the +buffer, the current line number shall be set to the address of the new +last line; if no lines remain in the buffer, the current line number +shall be set to zero. Address 0 shall be valid for this command; it +shall be interpreted as if address 1 were specified. +.SS "Delete Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)d +.fi \fR +.P +.RE +.RE +.P +The +.BR d +command shall delete the addressed lines from the buffer. The address +of the line after the last line deleted shall become the current line +number; if the lines deleted were originally at the end of the buffer, +the current line number shall be set to the address of the new last +line; if no lines remain in the buffer, the current line number shall +be set to zero. +.SS "Edit Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +e \fB[\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR e +command shall delete the entire contents of the buffer and then read in +the file named by the pathname +.IR file . +The current line number shall be set to the address of the last line of +the buffer. If no pathname is given, the currently remembered pathname, +if any, shall be used (see the +.BR f +command). The number of bytes read shall be written to standard output, +unless the +.BR \(mis +option was specified, in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fInumber of bytes read\fR> +.fi \fR +.P +.RE +.P +The name \fIfile\fR shall be remembered for possible use as a default +pathname in subsequent +.BR e , +.BR E , +.BR r , +and +.BR w +commands. If +.IR file +is replaced by +.BR '!' , +the rest of the line shall be taken to be a shell command line whose +output is to be read. Such a shell command line shall not be remembered +as the current +.IR file . +All marks shall be discarded upon the completion of a successful +.BR e +command. If the buffer has changed since the last time the entire +buffer was written, the user shall be warned, as described previously. +.SS "Edit Without Checking Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +E \fB[\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR E +command shall possess all properties and restrictions of the +.BR e +command except that the editor shall not check to see whether any +changes have been made to the buffer since the last +.BR w +command. +.SS "Filename Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +f \fB[\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR file +is given, the +.BR f +command shall change the currently remembered pathname to +.IR file ; +whether the name is changed or not, it shall then write the (possibly +new) currently remembered pathname to the standard output in the +following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +The current line number shall be unchanged. +.SS "Global Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)g/\fIRE\fR/\fIcommand list\fR +.fi \fR +.P +.RE +.RE +.P +In the +.BR g +command, the first step shall be to mark every line for which the +line excluding the terminating + +matches the given RE. Then, going sequentially from the beginning of +the file to the end of the file, the given +.IR "command list" +shall be executed for each marked line, with the current line number +set to the address of that line. Any line modified by the +.IR "command list" +shall be unmarked. When the +.BR g +command completes, the current line number shall have the value +assigned by the last command in the +.IR "command list" . +If there were no matching lines, the current line number shall not be +changed. A single command or the first of a list of commands shall +appear on the same line as the global command. All lines of a +multi-line list except the last line shall be ended with a + +preceding the terminating +; +the +.BR a , +.BR i , +and +.BR c +commands and associated input are permitted. The +.BR '.' +terminating input mode can be omitted if it would be the last line of +the \fIcommand list\fR. An empty \fIcommand list\fR shall be equivalent +to the +.BR p +command. The use of the +.BR g , +.BR G , +.BR v , +.BR V , +and +.BR ! +commands in the +.IR "command list" +produces undefined results. Any character other than + +or + +can be used instead of a + +to delimit the RE. Within the RE, the RE delimiter itself can be used +as a literal character if it is preceded by a +. +.SS "Interactive Global Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)G/\fIRE\fR/ +.fi \fR +.P +.RE +.RE +.P +In the +.BR G +command, the first step shall be to mark every line for which the line +excluding the terminating + +matches the given RE. Then, for every such line, that line shall be +written, the current line number shall be set to the address of that +line, and any one command (other than one of the +.BR a , +.BR c , +.BR i , +.BR g , +.BR G , +.BR v , +and +.BR V +commands) shall be read and executed. A + +shall act as a null command (causing no action to be taken on +the current line); an +.BR '&' +shall cause the re-execution of the most recent non-null command +executed within the current invocation of +.BR G . +Note that the commands input as part of the execution of the +.BR G +command can address and affect any lines in the buffer. Any line +modified by the command shall be unmarked. The final value +of the current line number shall be the value set by the last command +successfully executed. (Note that the last command successfully +executed shall be the +.BR G +command itself if a command fails or the null command is specified.) If +there were no matching lines, the current line number shall not be +changed. The +.BR G +command can be terminated by a SIGINT signal. Any character other than + +or + +can be used instead of a + +to delimit the RE and the replacement. Within the RE, the RE delimiter +itself can be used as a literal character if it is preceded by a +. +.SS "Help Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +h +.fi \fR +.P +.RE +.RE +.P +The +.BR h +command shall write a short message to standard output that explains +the reason for the most recent +.BR '?' +notification. The current line number shall be unchanged. +.SS "Help-Mode Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +H +.fi \fR +.P +.RE +.RE +.P +The +.BR H +command shall cause +.IR ed +to enter a mode in which help messages (see the +.BR h +command) shall be written to standard output for all subsequent +.BR '?' +notifications. The +.BR H +command alternately shall turn this mode on and off; it is initially +off. If the help-mode is being turned on, the +.BR H +command also explains the previous +.BR '?' +notification, if there was one. The current line number shall be +unchanged. +.SS "Insert Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.)i +<\fItext\fR> +\&. +.fi \fR +.P +.RE +.RE +.P +The +.BR i +command shall insert the given text before the addressed line; the +current line is set to the last inserted line or, if there was none, to +the addressed line. This command differs from the +.BR a +command only in the placement of the input text. Address 0 shall be +valid for this command; it shall be interpreted as if address 1 were +specified. +.SS "Join Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.+1)j +.fi \fR +.P +.RE +.RE +.P +The +.BR j +command shall join contiguous lines by removing the appropriate + +characters. If exactly one address is given, this command shall do +nothing. If lines are joined, the current line number shall be set to +the address of the joined line; otherwise, the current line number shall +be unchanged. +.SS "Mark Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.)k\fIx\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR k +command shall mark the addressed line with name +.IR x , +which the application shall ensure is a lowercase letter from the +portable character set. The address +.BR \(dq'x\(dq +shall then refer to this line; the current line number shall be +unchanged. +.SS "List Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)l +.fi \fR +.P +.RE +.RE +.P +The +.BR l +command shall write to standard output the addressed lines in a +visually unambiguous form. The characters listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +shall be written as the corresponding escape sequence; the +.BR '\en' +in that table is not applicable. Non-printable characters not in the +table shall be written as one three-digit octal number (with a +preceding + +character) for each byte in the character (most significant byte first). +.P +Long lines shall be folded, with the point of folding indicated by + +preceded by a +; +the length at which folding occurs is unspecified, but should be +appropriate for the output device. The end of each line shall be marked +with a +.BR '$' , +and +.BR '$' +characters within the text shall be written with a preceding +. +An +.BR l +command can be appended to any other command other than +.BR e , +.BR E , +.BR f , +.BR q , +.BR Q , +.BR r , +.BR w , +or +.BR ! . +The current line number shall be set to the address of the last line +written. +.SS "Move Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)m\fIaddress\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR m +command shall reposition the addressed lines after the line addressed +by +.IR address . +Address 0 shall be valid for +.IR address +and cause the addressed lines to be moved to the beginning of the +buffer. It shall be an error if address +.IR address +falls within the range of moved lines. The current line number shall be +set to the address of the last line moved. +.SS "Number Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)n +.fi \fR +.P +.RE +.RE +.P +The +.BR n +command shall write to standard output the addressed lines, preceding +each line by its line number and a +; +the current line number shall be set to the address of the last line +written. The +.BR n +command can be appended to any command other than +.BR e , +.BR E , +.BR f , +.BR q , +.BR Q , +.BR r , +.BR w , +or +.BR ! . +.SS "Print Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)p +.fi \fR +.P +.RE +.RE +.P +The +.BR p +command shall write to standard output the addressed lines; the current +line number shall be set to the address of the last line written. The +.BR p +command can be appended to any command other than +.BR e , +.BR E , +.BR f , +.BR q , +.BR Q , +.BR r , +.BR w , +or +.BR ! . +.SS "Prompt Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +P +.fi \fR +.P +.RE +.RE +.P +The +.BR P +command shall cause +.IR ed +to prompt with an + +(\c +.BR '*' ) +(or +.IR string , +if +.BR \(mip +is specified) for all subsequent commands. The +.BR P +command alternatively shall turn this mode on and off; it shall be +initially on if the +.BR \(mip +option is specified; otherwise, off. The current line number shall be +unchanged. +.SS "Quit Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q +.fi \fR +.P +.RE +.RE +.P +The +.BR q +command shall cause +.IR ed +to exit. If the buffer has changed since the last time the entire +buffer was written, the user shall be warned, as described previously. +.SS "Quit Without Checking Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +Q +.fi \fR +.P +.RE +.RE +.P +The +.BR Q +command shall cause +.IR ed +to exit without checking whether changes have been made in the buffer +since the last +.BR w +command. +.SS "Read Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +($)r\fB [\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR r +command shall read in the file named by the pathname +.IR file +and append it after the addressed line. If no +.IR file +argument is given, the currently remembered pathname, if any, shall be +used (see the +.BR e +and +.BR f +commands). The currently remembered pathname shall not be changed +unless there is no remembered pathname. Address 0 shall be valid for +.BR r +and shall cause the file to be read at the beginning of the buffer. If +the read is successful, and +.BR \(mis +was not specified, the number of bytes read shall be written to +standard output in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fInumber of bytes read\fR> +.fi \fR +.P +.RE +.P +The current line number shall be set to the address of the last line +read in. If +.IR file +is replaced by +.BR '!' , +the rest of the line shall be taken to be a shell command line whose +output is to be read. Such a shell command line shall not be remembered +as the current pathname. +.SS "Substitute Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)s/\fIRE\fR/\fIreplacement\fR/\fIflags\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR s +command shall search each addressed line for an occurrence of the +specified RE and replace either the first or all (non-overlapped) +matched strings with the +.IR replacement ; +see the following description of the +.BR g +suffix. It is an error if the substitution fails on every addressed +line. Any character other than + +or + +can be used instead of a + +to delimit the RE and the replacement. Within the RE, the RE delimiter +itself can be used as a literal character if it is preceded by a +. +The current line shall be set to the address of the last line on which +a substitution occurred. +.P +An + +(\c +.BR '&' ) +appearing in the +.IR replacement +shall be replaced by the string matching the RE on the current line. +The special meaning of +.BR '&' +in this context can be suppressed by preceding it by +. +As a more general feature, the characters +.BR '\en' , +where +.IR n +is a digit, shall be replaced by the text matched by the corresponding +back-reference expression. If the corresponding back-reference +expression does not match, then the characters +.BR '\en' +shall be replaced by the empty string. When the character +.BR '%' +is the only character in the +.IR replacement , +the +.IR replacement +used in the most recent substitute command shall be used as the +.IR replacement +in the current substitute command; if there was no previous substitute +command, the use of +.BR '%' +in this manner shall be an error. The +.BR '%' +shall lose its special meaning when it is in a replacement string of +more than one character or is preceded by a +. +For each + +encountered in scanning +.IR replacement +from beginning to end, the following character shall lose its special +meaning (if any). It is unspecified what special meaning is given to +any character other than +, +.BR '&' , +.BR '%' , +or digits. +.P +A line can be split by substituting a + +into it. The application shall ensure it escapes the + +in the +.IR replacement +by preceding it by +. +Such substitution cannot be done as part of a +.BR g +or +.BR v +.IR "command list" . +The current line number shall be set to the address of the last line on +which a substitution is performed. If no substitution is performed, the +current line number shall be unchanged. If a line is split, a +substitution shall be considered to have been performed on each of the +new lines for the purpose of determining the new current line number. A +substitution shall be considered to have been performed even if the +replacement string is identical to the string that it replaces. +.P +The application shall ensure that the value of +.IR flags +is zero or more of: +.IP "\fIcount\fR" 8 +Substitute for the +.IR count th +occurrence only of the RE found on each addressed line. +.IP "\fBg\fR" 8 +Globally substitute for all non-overlapping instances of the RE rather +than just the first one. If both +.BR g +and +.IR count +are specified, the results are unspecified. +.IP "\fBl\fR" 8 +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for the +.BR l +command. +.IP "\fBn\fR" 8 +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for the +.BR n +command. +.IP "\fBp\fR" 8 +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for the +.BR p +command. +.SS "Copy Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)t\fIaddress\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR t +command shall be equivalent to the +.BR m +command, except that a copy of the addressed lines shall be placed +after address +.IR address +(which can be 0); the current line number shall be set to the address +of the last line added. +.SS "Undo Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u +.fi \fR +.P +.RE +.RE +.P +The +.BR u +command shall nullify the effect of the most recent command that +modified anything in the buffer, namely the most recent +.BR a , +.BR c , +.BR d , +.BR g , +.BR i , +.BR j , +.BR m , +.BR r , +.BR s , +.BR t , +.BR u , +.BR v , +.BR G , +or +.BR V +command. All changes made to the buffer by a +.BR g , +.BR G , +.BR v , +or +.BR V +global command shall be undone as a single change; if no changes were +made by the global command (such as with +.BR g /RE/\c +.BR p ), +the +.BR u +command shall have no effect. The current line number shall be set to +the value it had immediately before the command being undone started. +.SS "Global Non-Matched Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)v\fR/\fIRE\fR/\fIcommand list\fR +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the global command +.BR g +except that the lines that are marked during the first step shall be +those for which the line excluding the terminating + +does not match the RE. +.SS "Interactive Global Not-Matched Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)V\fR/\fIRE\fR/ +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the interactive global command +.BR G +except that the lines that are marked during the first step shall be +those for which the line excluding the terminating + +does not match the RE. +.SS "Write Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)w\fB [\fIfile\fB] +.fi \fR +.P +.RE +.RE +.P +The +.BR w +command shall write the addressed lines into the file named by the +pathname +.IR file . +The command shall create the file, if it does not exist, or shall +replace the contents of the existing file. The currently remembered +pathname shall not be changed unless there is no remembered pathname. +If no pathname is given, the currently remembered pathname, if any, +shall be used (see the +.BR e +and +.BR f +commands); the current line number shall be unchanged. If the command +is successful, the number of bytes written shall be written to standard +output, unless the +.BR \(mis +option was specified, in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fInumber of bytes written\fR> +.fi \fR +.P +.RE +.P +If +.IR file +begins with +.BR '!' , +the rest of the line shall be taken to be a shell command line whose +standard input shall be the addressed lines. Such a shell command line +shall not be remembered as the current pathname. This usage of the +write command with +.BR '!' +shall not be considered as a ``last +.BR w +command that wrote the entire buffer'', as described previously; thus, +this alone shall not prevent the warning to the user if an attempt is +made to destroy the editor buffer via the +.BR e +or +.BR q +commands. +.SS "Line Number Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +($)= +.fi \fR +.P +.RE +.RE +.P +The line number of the addressed line shall be written to standard +output in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIline number\fR> +.fi \fR +.P +.RE +.P +The current line number shall be unchanged by this command. +.SS "Shell Escape Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +!\fIcommand\fR +.fi \fR +.P +.RE +.RE +.P +The remainder of the line after the +.BR '!' +shall be sent to the command interpreter to be interpreted as a shell +command line. Within the text of that shell command line, the unescaped +character +.BR '%' +shall be replaced with the remembered pathname; if a +.BR '!' +appears as the first character of the command, it shall be replaced +with the text of the previous shell command executed via +.BR '!' . +Thus, +.BR \(dq!!\(dq +shall repeat the previous !\fIcommand\fP. If any replacements of +.BR '%' +or +.BR '!' +are performed, the modified line shall be written to the standard +output before +.IR command +is executed. The +.BR ! +command shall write: +.sp +.RS 4 +.nf +\fB +"!\en" +.fi \fR +.P +.RE +.P +to standard output upon completion, unless the +.BR \(mis +option is specified. The current line number shall be unchanged. +.SS "Null Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.+1) +.fi \fR +.P +.RE +.RE +.P +An address alone on a line shall cause the addressed line to be +written. A + +alone shall be equivalent to +.BR \(dq+1p\(dq . +The current line number shall be set to the address of the written +line. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion without any file or command errors. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When an error in the input script is encountered, or when an error is +detected that is a consequence of the data (not) present in the file or +due to an external condition such as a read or write error: +.IP " *" 4 +If the standard input is a terminal device file, all input shall be +flushed, and a new command read. +.IP " *" 4 +If the standard input is a regular file, +.IR ed +shall terminate with a non-zero exit status. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Because of the extremely terse nature of the default error messages, +the prudent script writer begins the +.IR ed +input commands with an +.BR H +command, so that if any errors do occur at least some clue as to the +cause is made available. +.P +In earlier versions of this standard, an obsolescent +.BR \(mi +option was described. This is no longer specified. Applications should +use the +.BR \(mis +option. Using +.BR \(mi +as a +.IR file +operand now produces unspecified results. This allows implementations +to continue to support the former required behavior. +.SH EXAMPLES +None. +.SH RATIONALE +The initial description of this utility was adapted from the SVID. It +contains some features not found in Version 7 or BSD-derived systems. +Some of the differences between the POSIX and BSD +.IR ed +utilities include, but need not be limited to: +.IP " *" 4 +The BSD +.BR \(mi +option does not suppress the +.BR '!' +prompt after a +.BR ! +command. +.IP " *" 4 +BSD does not support the special meanings of the +.BR '%' +and +.BR '!' +characters within a +.BR ! +command. +.IP " *" 4 +BSD does not support the +.IR addresses +.BR ';' +and +.BR ',' . +.IP " *" 4 +BSD allows the command/suffix pairs +.BR pp , +.BR ll , +and so on, which are unspecified in this volume of POSIX.1\(hy2008. +.IP " *" 4 +BSD does not support the +.BR '!' +character part of the +.BR e , +.BR r , +or +.BR w +commands. +.IP " *" 4 +A failed +.BR g +command in BSD sets the line number to the last line searched if there +are no matches. +.IP " *" 4 +BSD does not default the +.IR "command list" +to the +.BR p +command. +.IP " *" 4 +BSD does not support the +.BR G , +.BR h , +.BR H , +.BR n , +or +.BR V +commands. +.IP " *" 4 +On BSD, if there is no inserted text, the insert command changes the +current line to the referenced line \(mi1; that is, the line before the +specified line. +.IP " *" 4 +On BSD, the +.IR join +command with only a single address changes the current line to that +address. +.IP " *" 4 +BSD does not support the +.BR P +command; moreover, in BSD it is synonymous with the +.BR p +command. +.IP " *" 4 +BSD does not support the +.IR undo +of the commands +.BR j , +.BR m , +.BR r , +.BR s , +or +.BR t . +.IP " *" 4 +The Version 7 +.IR ed +command +.BR W , +and the BSD +.IR ed +commands +.BR W , +.BR wq , +and +.BR z +are not present in this volume of POSIX.1\(hy2008. +.P +The +.BR \(mis +option was added to allow the functionality of the removed +.BR \(mi +option in a manner compatible with the Utility Syntax Guidelines. +.P +In early proposals there was a limit, +{ED_FILE_MAX}, +that described the historical limitations of some +.IR ed +utilities in their handling of large files; some of these have had +problems with files larger than 100\|000 bytes. It was this limitation +that prompted much of the desire to include a +.IR split +command in this volume of POSIX.1\(hy2008. Since this limit was removed, this volume of POSIX.1\(hy2008 requires that +implementations document the file size limits imposed by +.IR ed +in the conformance document. The limit +{ED_LINE_MAX} +was also removed; therefore, the global limit +{LINE_MAX} +is used for input and output lines. +.P +The manner in which the +.BR l +command writes non-printable characters was changed to avoid +the historical backspace-overstrike method. On video display terminals, +the overstrike is ambiguous because most terminals simply replace +overstruck characters, making the +.BR l +format not useful for its intended purpose of unambiguously +understanding the content of the line. The historical +-escapes +were also ambiguous. (The string +.BR \(dqa\e0011\(dq +could represent a line containing those six characters or a line +containing the three characters +.BR 'a' , +a byte with a binary value of 1, and a 1.) In the format required here, +a + +appearing in the line is written as +.BR \(dq\e\e\(dq +so that the output is truly unambiguous. The method of marking the ends +of lines was adopted from the +.IR ex +editor and is required for any line ending in + +characters; the +.BR '$' +is placed on all lines so that a real +.BR '$' +at the end of a line cannot be misinterpreted. +.P +Earlier versions of this standard allowed for implementations +with bytes other than eight bits, but this has been modified in this +version. +.P +The description of how a NUL is written was removed. The NUL character +cannot be in text files, and this volume of POSIX.1\(hy2008 should not dictate behavior in the +case of undefined, erroneous input. +.P +Unlike some of the other editing utilities, the filenames accepted by +the +.BR E , +.BR e , +.BR R , +and +.BR r +commands are not patterns. +.P +Early proposals stated that the +.BR \(mip +option worked only when standard input was associated with a terminal +device. This has been changed to conform to historical implementations, +thereby allowing applications to interpose themselves between a user +and the +.IR ed +utility. +.P +The form of the substitute command that uses the +.BR n +suffix was limited in some historical documentation (where this was +described incorrectly as ``backreferencing''). This limit has been +omitted because there is no reason why an editor processing lines of +{LINE_MAX} +length should have this restriction. The command +.BR "s/x/X/2047" +should be able to substitute the 2\|047th occurrence of +.BR 'x' +on a line. +.P +The use of printing commands with printing suffixes (such as +.BR pn , +.BR lp , +and so on) was made unspecified because BSD-based systems allow this, +whereas System V does not. +.P +Some BSD-based systems exit immediately upon receipt of end-of-file if +all of the lines in the file have been deleted. Since this volume of POSIX.1\(hy2008 refers +to the +.BR q +command in this instance, such behavior is not allowed. +.P +Some historical implementations returned exit status zero even if +command errors had occurred; this is not allowed by this volume of POSIX.1\(hy2008. +.P +Some historical implementations contained a bug that allowed a single + +to be entered in input mode as + + +. +This is not allowed by +.IR ed +because there is no description of escaping any of the characters in +input mode; + +characters are entered into the buffer exactly as typed. The typical +method of entering a single + +has been to precede it with another character and then use the substitute +command to delete that character. +.P +It is difficult under some modes of some versions of historical +operating system terminal drivers to distinguish between an end-of-file +condition and terminal disconnect. POSIX.1\(hy2008 does not require +implementations to distinguish between the two situations, which +permits historical implementations of the +.IR ed +utility on historical platforms to conform. Implementations are +encouraged to distinguish between the two, if possible, and take +appropriate action on terminal disconnect. +.P +Historically, +.IR ed +accepted a zero address for the +.BR a +and +.BR r +commands in order to insert text at the start of the edit buffer. When +the buffer was empty the command +.BR .= +returned zero. POSIX.1\(hy2008 requires conformance to historical practice. +.P +For consistency with the +.BR a +and +.BR r +commands and better user functionality, the +.BR i +and +.BR c +commands must also accept an address of 0, in which case 0\fIi\fP is +treated as 1\fIi\fP and likewise for the +.BR c +command. +.P +All of the following are valid addresses: +.IP "\fR+++\fP" 12 +Three lines after the current line. +.IP "\fR/\fIpattern\fR/\(mi\fR" 12 +One line before the next occurrence of pattern. +.IP "\fR\(mi2\fR" 12 +Two lines before the current line. +.IP "\fR3\ \(mi\|\(mi\|\(mi\|\(mi\ 2\fR" 12 +Line one (note the intermediate negative address). +.IP "\fR1\ 2\ 3\fR" 12 +Line six. +.P +Any number of addresses can be provided to commands taking addresses; +for example, +.BR \(dq1,2,3,4,5p\(dq +prints lines 4 and 5, because two is the greatest valid number of +addresses accepted by the +.BR print +command. This, in combination with the + +delimiter, permits users to create commands based on ordered patterns +in the file. For example, the command +.BR \(dq3;/foo/;+2p\(dq +will display the first line after line 3 that contains the pattern +.IR foo , +plus the next two lines. Note that the address +.BR \(dq3;\(dq +must still be evaluated before being discarded, because the search +origin for the +.BR \(dq/foo/\(dq +command depends on this. +.P +Historically, +.IR ed +disallowed address chains, as discussed above, consisting solely of + +or + +separators; for example, +.BR \(dq,,,\(dq +or +.BR \(dq;;;\(dq +were considered an error. For consistency of address specification, +this restriction is removed. The following table lists some of the +address forms now possible: +.TS +center box tab(!); +cB | cB | cB | cB | cB +lf5 | nf5 | nf5 | l | l. +Address!Addr1!Addr2!Status!Comment +_ +7,!7!7!Historical +7,5,!5!5!Historical +7,5,9!5!9!Historical +7,9!7!9!Historical +7,+!7!8!Historical +\&,!1!$!Historical +\&,7!1!7!Extension +\&,,!$!$!Extension +\&,;!$!$!Extension +7;!7!7!Historical +7;5;!5!5!Historical +7;5;9!5!9!Historical +7;5,9!5!9!Historical +7;$;4!$!4!Historical!Valid, but erroneous. +7;9!7!9!Historical +7;+!7!8!Historical +;!.!$!Historical +;7!.!7!Extension +;;!$!$!Extension +;,!$!$!Extension +.TE +.P +Historically, +.IR ed +accepted the +.BR '^' +character as an address, in which case it was identical to the + +character. POSIX.1\(hy2008 does not require or prohibit this behavior. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.4" ", " "Utility Description Defaults", +.IR "\fIex\fR\^", +.IR "\fIsed\fR\^", +.IR "\fIsh\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/env.1p b/man-pages-posix-2013-a/man1p/env.1p new file mode 100644 index 0000000..14f628e --- /dev/null +++ b/man-pages-posix-2013-a/man1p/env.1p @@ -0,0 +1,330 @@ +'\" et +.TH ENV "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +env +\(em set the environment for command invocation +.SH SYNOPSIS +.LP +.nf +env \fB[\fR\(mii\fB] [\fIname\fR=\fIvalue\fB]\fR... \fB[\fIutility\fB [\fIargument\fR...\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR env +utility shall obtain the current environment, modify it according to +its arguments, then invoke the utility named by the +.IR utility +operand with the modified environment. +.P +Optional arguments shall be passed to +.IR utility . +.P +If no +.IR utility +operand is specified, the resulting environment shall be written to the +standard output, with one +.IR name =\c +.IR value +pair per line. +.P +If the first argument is +.BR '\(mi' , +the results are unspecified. +.SH OPTIONS +The +.IR env +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mii\fP" 10 +Invoke +.IR utility +with exactly the environment specified by the arguments; the inherited +environment shall be ignored completely. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIname\fR=\fIvalue\fR" 10 +Arguments of the form +.IR name =\c +.IR value +shall modify the execution environment, and shall be placed into the +inherited environment before the +.IR utility +is invoked. +.IP "\fIutility\fR" 10 +The name of the utility to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +A string to pass as an argument for the invoked utility. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR env : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of the +.IR utility , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +If +.IR PATH +is specified as a +.IR name =\c +.IR value +operand to +.IR env , +the +.IR value +given shall be used in the search for +.IR utility . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If no +.IR utility +operand is specified, each +.IR name =\c +.IR value +pair in the resulting environment shall be written in the form: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +If the +.IR utility +operand is specified, the +.IR env +utility shall not write to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If +.IR utility +is invoked, the exit status of +.IR env +shall be the exit status of +.IR utility ; +otherwise, the +.IR env +utility shall exit with one of the following values: +.IP "\0\0\0\00" 8 +The +.IR env +utility completed successfully. +.IP "1\(mi125" 8 +An error occurred in the +.IR env +utility. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.P +Historical implementations of the +.IR env +utility use the +\fIexecvp\fR() +or +\fIexeclp\fR() +functions defined in the System Interfaces volume of POSIX.1\(hy2008 to invoke the specified utility; this +provides better performance and keeps users from having to escape +characters with special meaning to the shell. Therefore, shell +functions, special built-ins, and built-ins that are only provided by +the shell are not found. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +env \(mii PATH=/mybin:"$PATH" $(getconf V7_ENV) mygrep xyz myfile +.fi \fR +.P +.RE +.P +invokes the command +.IR mygrep +with a new +.IR PATH +value as the only entry in its environment other than any variables +required by the implementation for conformance. In this case, +.IR PATH +is used to locate +.IR mygrep , +which is expected to reside in +.BR /mybin . +.SH RATIONALE +As with all other utilities that invoke other utilities, this volume of POSIX.1\(hy2008 only +specifies what +.IR env +does with standard input, standard output, standard error, input files, +and output files. If a utility is executed, it is not constrained by +the specification of input and output by +.IR env . +.P +The +.BR \(mii +option was added to allow the functionality of the removed +.BR \(mi +option in a manner compatible with the Utility Syntax Guidelines. It +is possible to create a non-conforming environment using the +.BR \(mii +option, as it may remove environment variables required by the +implementation for conformance. The following will preserve these +environment variables as well as preserve the +.IR PATH +for conforming utilities: +.sp +.RS 4 +.nf +\fB +IFS=' +\&' +# The preceding value should be . +# Set IFS to its default value. +.P +set \(mif +# disable pathname expansion +.P +\eunalias \(mia +# Unset all possible aliases. +# Note that unalias is escaped to prevent an alias +# being used for unalias. +# This step is not strictly necessary, since aliases are not inherited, +# and the ENV environment variable is only used by interactive shells, +# the only way any aliases can exist in a script is if it defines them +# itself. +.P +unset \(mif env getconf +# Ensure env and getconf are not user functions. +.P +env \(mii $(getconf V7_ENV) PATH="$(getconf PATH)" command +.fi \fR +.P +.RE +.P +Some have suggested that +.IR env +is redundant since the same effect is achieved by: +.sp +.RS 4 +.nf +\fB +name=value ... utility \fB[\fR argument ... \fB]\fR +.fi \fR +.P +.RE +.P +The example is equivalent to +.IR env +when an environment variable is being added to the environment of the +command, but not when the environment is being set to the given value. +The +.IR env +utility also writes out the current environment if invoked without +arguments. There is sufficient functionality beyond what the example +provides to justify inclusion of +.IR env . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "Section 2.5" ", " "Parameters and Variables" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/eval.1p b/man-pages-posix-2013-a/man1p/eval.1p new file mode 100644 index 0000000..7414d5b --- /dev/null +++ b/man-pages-posix-2013-a/man1p/eval.1p @@ -0,0 +1,138 @@ +'\" et +.TH EVAL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +eval +\(em construct command by concatenating arguments +.SH SYNOPSIS +.LP +.nf +eval \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR eval +utility shall construct a command by concatenating +.IR argument s +together, separating each with a + +character. +The constructed command shall be read and executed by the shell. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If there are no +.IR argument s, +or only null +.IR argument s, +.IR eval +shall return a zero exit status; otherwise, it shall return the exit +status of the command defined by the string of concatenated +.IR argument s +separated by + +characters, or a non-zero exit status if the concatenation could not +be parsed as a command and the shell is interactive (and therefore did +not abort). +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR eval +is not required to recognize the +.BR \(dq--\(dq +end of options delimiter, in cases where the argument(s) to +.IR eval +might begin with +.BR '-' +it is recommended that the first argument is prefixed by a string that +will not alter the commands to be executed, such as a + +character: +.sp +.RS 4 +.nf +\fB +eval " $commands" +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +eval " $(some_command)" +.fi \fR +.P +.RE +.SH EXAMPLES +.LP +.nf +foo=10 x=foo +y='$'$x +echo $y +\fB$foo\fR +eval y='$'$x +echo $y +\fB10\fR +.fi +.SH "RATIONALE" +This standard allows, but does not require, +.IR eval +to recognize +.BR \(dq--\(dq . +Although this means applications cannot use +.BR \(dq--\(dq +to protect against options supported as an extension (or errors reported +for unsupported options), the nature of the +.IR eval +utility is such that other means can be used to provide this protection +(see APPLICATION USAGE above). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ex.1p b/man-pages-posix-2013-a/man1p/ex.1p new file mode 100644 index 0000000..a3be3e9 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ex.1p @@ -0,0 +1,9025 @@ +'\" et +.TH EX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ex +\(em text editor +.SH SYNOPSIS +.LP +.nf +ex \fB[\fR\(mirR\fB] [\fR\(mis|\(miv\fB] [\fR\(mic \fIcommand\fB] [\fR\(mit \fItagstring\fB] [\fR\(miw \fIsize\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ex +utility is a line-oriented text editor. There are two other modes of +the editor\(emopen and visual\(emin which screen-oriented editing is +available. This is described more fully by the +.IR ex +.BR open +and +.BR visual +commands and in +.IR "\fIvi\fR\^". +.P +If an operand is +.BR '\(mi' , +the results are unspecified. +.P +This section uses the term +.IR "edit buffer" +to describe the current working text. No specific implementation is +implied by this term. All editing changes are performed on the edit +buffer, and no changes to it shall affect any file until an editor +command writes the file. +.P +Certain terminals do not have all the capabilities necessary to support +the complete +.IR ex +definition, such as the full-screen editing commands (\c +.IR "visual mode" +or +.IR "open mode" ). +When these commands cannot be supported on such terminals, this +condition shall not produce an error message such as ``not an editor +command'' or report a syntax error. The implementation may either +accept the commands and produce results on the screen that are the +result of an unsuccessful attempt to meet the requirements of this volume of POSIX.1\(hy2008 or +report an error describing the terminal-related deficiency. +.SH OPTIONS +The +.IR ex +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' , +and that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\ \fIcommand\fR" 10 +Specify an initial command to be executed in the first edit buffer +loaded from an existing file (see the EXTENDED DESCRIPTION section). +Implementations may support more than a single +.BR \(mic +option. In such implementations, the specified commands shall be +executed in the order specified on the command line. +.IP "\fB\(mir\fP" 10 +Recover the named files (see the EXTENDED DESCRIPTION section). +Recovery information for a file shall be saved during an editor or +system crash (for example, when the editor is terminated by a signal +which the editor can catch), or after the use of an +.IR ex +.BR preserve +command. +.RS 10 +.P +A +.IR crash +in this context is an unexpected failure of the system or utility that +requires restarting the failed system or utility. A system crash +implies that any utilities running at the time also crash. In the case +of an editor or system crash, the number of changes to the edit buffer +(since the most recent +.BR preserve +command) that will be recovered is unspecified. +.P +If no +.IR file +operands are given and the +.BR \(mit +option is not specified, all other options, the +.IR EXINIT +variable, and any +.BR .exrc +files shall be ignored; a list of all recoverable files available to +the invoking user shall be written, and the editor shall exit normally +without further action. +.RE +.IP "\fB\(miR\fP" 10 +Set +.BR readonly +edit option. +.IP "\fB\(mis\fP" 10 +Prepare +.IR ex +for batch use by taking the following actions: +.RS 10 +.IP " *" 4 +Suppress writing prompts and informational (but not diagnostic) +messages. +.IP " *" 4 +Ignore the value of +.IR TERM +and any implementation default terminal type and assume the terminal is +a type incapable of supporting open or visual modes; see the +.BR visual +command and the description of +.IR "\fIvi\fR\^". +.IP " *" 4 +Suppress the use of the +.IR EXINIT +environment variable and the reading of any +.BR .exrc +file; see the EXTENDED DESCRIPTION section. +.IP " *" 4 +Suppress autoindentation, ignoring the value of the +.BR autoindent +edit option. +.RE +.IP "\fB\(mit\ \fItagstring\fR" 10 +Edit the file containing the specified +.IR tagstring ; +see +.IR "\fIctags\fR\^". +The tags feature represented by +.BR \(mit +.IR tagstring +and the +.BR tag +command is optional. It shall be provided on any system that also +provides a conforming implementation of +.IR ctags ; +otherwise, the use of +.BR \(mit +produces undefined results. On any system, it shall be an error to +specify more than a single +.BR \(mit +option. +.IP "\fB\(miv\fP" 10 +Begin in visual mode (see +.IR "\fIvi\fR\^"). +.IP "\fB\(miw\ \fIsize\fR" 10 +Set the value of the +.IR window +editor option to +.IR size . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be edited. +.SH STDIN +The standard input consists of a series of commands and input text, as +described in the EXTENDED DESCRIPTION section. The implementation may +limit each line of standard input to a length of +{LINE_MAX}. +.P +If the standard input is not a terminal device, it shall be as if the +.BR \(mis +option had been specified. +.P +If a read from the standard input returns an error, or if the editor +detects an end-of-file condition from the standard input, it shall be +equivalent to a SIGHUP asynchronous event. +.SH "INPUT FILES" +Input files shall be text files or files that would be text files +except for an incomplete last line that is not longer than +{LINE_MAX}\(mi1 +bytes in length and contains no NUL characters. By default, any +incomplete last line shall be treated as if it had a trailing +. +The editing of other forms of files may optionally be allowed by +.IR ex +implementations. +.P +The +.BR .exrc +files and source files shall be text files consisting of +.IR ex +commands; see the EXTENDED DESCRIPTION section. +.P +By default, the editor shall read lines from the files to be edited +without interpreting any of those lines as any form of editor command. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ex : +.IP "\fICOLUMNS\fP" 10 +Override the system-selected horizontal screen size. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fIEXINIT\fP" 10 +Determine a list of +.IR ex +commands that are executed on editor start-up. See the EXTENDED +DESCRIPTION section for more details of the initialization phase. +.IP "\fIHOME\fP" 10 +Determine a pathname of a directory that shall be searched for an +editor start-up file named +.BR .exrc ; +see the EXTENDED DESCRIPTION section. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes within regular expressions, the classification of +characters as uppercase or lowercase letters, the case conversion of +letters, and the detection of word boundaries. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILINES\fP" 10 +Override the system-selected vertical screen size, used as the number +of lines in a screenful and the vertical screen size in visual mode. +See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path for the shell command specified in the +.IR ex +editor commands +.BR ! , +.BR shell , +.BR read , +and +.BR write , +and the open and visual mode command +.BR ! ; +see the description of command search and execution in +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +.IP "\fISHELL\fP" 10 +Determine the preferred command line interpreter for use as the default +value of the +.BR shell +edit option. +.IP "\fITERM\fP" 10 +Determine the name of the terminal type. If this variable is unset or +null, an unspecified default terminal type shall be used. +.SH "ASYNCHRONOUS EVENTS" +The following term is used in this and following sections to specify +command and asynchronous event actions: +.IP "\fIcomplete\ write\fP" 10 +.br +A complete write is a write of the entire contents of the edit buffer +to a file of a type other than a terminal device, or the saving of the +edit buffer caused by the user executing the +.IR ex +.BR preserve +command. Writing the contents of the edit buffer to a temporary file +that will be removed when the editor exits shall not be considered a +complete write. +.P +The following actions shall be taken upon receipt of signals: +.IP SIGINT 10 +If the standard input is not a terminal device, +.IR ex +shall not write the file or return to command or text input mode, and +shall exit with a non-zero exit status. +.RS 10 +.P +Otherwise, if executing an open or visual text input mode command, +.IR ex +in receipt of SIGINT shall behave identically to its receipt of the + +character. +.P +Otherwise: +.IP " 1." 4 +If executing an +.IR ex +text input mode command, all input lines that have been completely +entered shall be resolved into the edit buffer, and any partially +entered line shall be discarded. +.IP " 2." 4 +If there is a currently executing command, it shall be aborted and a +message displayed. Unless otherwise specified by the +.IR ex +or +.IR vi +command descriptions, it is unspecified whether any lines modified by +the executing command appear modified, or as they were before being +modified by the executing command, in the buffer. +.RS 4 +.P +If the currently executing command was a motion command, its associated +command shall be discarded. +.RE +.IP " 3." 4 +If in open or visual command mode, the terminal shall be alerted. +.IP " 4." 4 +The editor shall then return to command mode. +.RE +.IP SIGCONT 10 +The screen shall be refreshed if in open or visual mode. +.IP SIGHUP 10 +If the edit buffer has been modified since the last complete write, +.IR ex +shall attempt to save the edit buffer so that it can be recovered later +using the +.BR \(mir +option or the +.IR ex +.BR recover +command. The editor shall not write the file or return to command or +text input mode, and shall terminate with a non-zero exit status. +.IP SIGTERM 10 +Refer to SIGHUP. +.P +The action taken for all other signals is unspecified. +.SH STDOUT +The standard output shall be used only for writing prompts to the user, +for informational messages, and for writing lines from the file. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output from +.IR ex +shall be text files. +.SH "EXTENDED DESCRIPTION" +Only the +.IR ex +mode of the editor is described in this section. See +.IR "\fIvi\fR\^" +for additional editing capabilities available in +.IR ex . +.P +When an error occurs, +.IR ex +shall write a message. If the terminal supports a standout mode (such +as inverse video), the message shall be written in standout mode. If +the terminal does not support a standout mode, and the edit option +.BR errorbells +is set, an alert action shall precede the error message. +.P +By default, +.IR ex +shall start in command mode, which shall be indicated by a +.BR : +prompt; see the +.BR prompt +command. Text input mode can be entered by the +.BR append , +.BR insert , +or +.BR change +commands; it can be exited (and command mode re-entered) by typing a + +(\c +.BR '.' ) +alone at the beginning of a line. +.SS "Initialization in ex and vi" +.P +The following symbols are used in this and following sections to +specify locations in the edit buffer: +.IP "\fIalternate\ and\ current\ pathnames\fP" 6 +.br +Two pathnames, named +.IR current +and +.IR alternate , +are maintained by the editor. Any +.IR ex +commands that take filenames as arguments shall set them as follows: +.RS 6 +.IP " 1." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR edit , +.BR ex , +or +.BR recover +commands, or if an +.IR ex +.BR tag +command replaces the contents of the edit buffer. +.RS 4 +.IP " a." 4 +If the command replaces the contents of the edit buffer, the current +pathname shall be set to the +.IR file +argument or the file indicated by the tag, and the alternate pathname +shall be set to the previous value of the current pathname. +.IP " b." 4 +Otherwise, the alternate pathname shall be set to the +.IR file +argument. +.RE +.IP " 2." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR next +command: +.RS 4 +.IP " a." 4 +If the command replaces the contents of the edit buffer, the current +pathname shall be set to the first +.IR file +argument, and the alternate pathname shall be set to the previous +value of the current pathname. +.RE +.IP " 3." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR file +command, the current pathname shall be set to the +.IR file +argument, and the alternate pathname shall be set to the previous +value of the current pathname. +.IP " 4." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR read +and +.BR write +commands (that is, when reading or writing a file, and not to the +program named by the +.BR shell +edit option), or a +.IR file +argument is specified to the +.IR ex +.BR xit +command: +.RS 4 +.IP " a." 4 +If the current pathname has no value, the current pathname shall be +set to the +.IR file +argument. +.IP " b." 4 +Otherwise, the alternate pathname shall be set to the +.IR file +argument. +.RE +.P +If the alternate pathname is set to the previous value of the current +pathname when the current pathname had no previous value, then the +alternate pathname shall have no value as a result. +.RE +.IP "\fIcurrent\ line\fP" 6 +.br +The line of the edit buffer referenced by the cursor. Each command +description specifies the current line after the command has been +executed, as the +.IR "current line value" . +When the edit buffer contains no lines, the current line shall be zero; +see +.IR "Addressing in ex". +.IP "\fIcurrent\ column\fP" 6 +.br +The current display line column occupied by the cursor. (The columns +shall be numbered beginning at 1.) Each command description specifies +the current column after the command has been executed, as the +.IR "current column" +value. This column is an +.IR ideal +column that is remembered over the lifetime of the editor. The actual +display line column upon which the cursor rests may be different from +the current column; see the cursor positioning discussion in +.IR "Command Descriptions in vi". +.IP "\fIset\ to\ non-\fP" 6 +.br +A description for a current column value, meaning that the current +column shall be set to the last display line column on which is +displayed any part of the first non-\c + +of the line. If the line has no non-\c + +non-\c + +characters, the current column shall be set to the last display line +column on which is displayed any part of the last non-\c + +character in the line. If the line is empty, the current column shall +be set to column position 1. +.P +The length of lines in the edit buffer may be limited to +{LINE_MAX} +bytes. In open and visual mode, the length of lines in the edit buffer +may be limited to the number of characters that will fit in the +display. If either limit is exceeded during editing, an error message +shall be written. If either limit is exceeded by a line read in from a +file, an error message shall be written and the edit session may be +terminated. +.P +If the editor stops running due to any reason other than a user +command, and the edit buffer has been modified since the last complete +write, it shall be equivalent to a SIGHUP asynchronous event. If the +system crashes, it shall be equivalent to a SIGHUP asynchronous event. +.P +During initialization (before the first file is copied into the edit +buffer or any user commands from the terminal are processed) the +following shall occur: +.IP " 1." 4 +If the environment variable +.IR EXINIT +is set, the editor shall execute the +.IR ex +commands contained in that variable. +.IP " 2." 4 +If the +.IR EXINIT +variable is not set, and all of the following are true: +.RS 4 +.IP " a." 4 +The +.IR HOME +environment variable is not null and not empty. +.IP " b." 4 +The file +.BR .exrc +in the directory referred to by the +.IR HOME +environment variable: +.RS 4 +.IP " i." 5 +Exists +.IP ii. 5 +Is owned by the same user ID as the real user ID of the process or the +process has appropriate privileges +.IP iii. 5 +Is not writable by anyone other than the owner +.RE +.P +the editor shall execute the +.IR ex +commands contained in that file. +.RE +.IP " 3." 4 +If and only if all of the following are true: +.RS 4 +.IP " a." 4 +The current directory is not referred to by the +.IR HOME +environment variable. +.IP " b." 4 +A command in the +.IR EXINIT +environment variable or a command in the +.BR .exrc +file in the directory referred to by the +.IR HOME +environment variable sets the editor option +.BR exrc . +.IP " c." 4 +The +.BR .exrc +file in the current directory: +.RS 4 +.IP " i." 5 +Exists +.IP ii. 5 +Is owned by the same user ID as the real user ID of the process, or by +one of a set of implementation-defined user IDs +.IP iii. 5 +Is not writable by anyone other than the owner +.RE +.P +the editor shall attempt to execute the +.IR ex +commands contained in that file. +.RE +.P +Lines in any +.BR .exrc +file that are blank lines shall be ignored. If any +.BR .exrc +file exists, but is not read for ownership or permission reasons, it +shall be an error. +.P +After the +.IR EXINIT +variable and any +.BR .exrc +files are processed, the first file specified by the user shall be +edited, as follows: +.IP " 1." 4 +If the user specified the +.BR \(mit +option, the effect shall be as if the +.IR ex +.BR tag +command was entered with the specified argument, with the exception +that if tag processing does not result in a file to edit, the effect +shall be as described in step 3. below. +.IP " 2." 4 +Otherwise, if the user specified any command line +.IR file +arguments, the effect shall be as if the +.IR ex +.BR edit +command was entered with the first of those arguments as its +.IR file +argument. +.IP " 3." 4 +Otherwise, the effect shall be as if the +.IR ex +.BR edit +command was entered with a nonexistent filename as its +.IR file +argument. It is unspecified whether this action shall set the current +pathname. In an implementation where this action does not set the +current pathname, any editor command using the current pathname shall +fail until an editor command sets the current pathname. +.P +If the +.BR \(mir +option was specified, the first time a file in the initial argument +list or a file specified by the +.BR \(mit +option is edited, if recovery information has previously been saved +about it, that information shall be recovered and the editor shall +behave as if the contents of the edit buffer have already been +modified. If there are multiple instances of the file to be recovered, +the one most recently saved shall be recovered, and an informational +message that there are previous versions of the file that can be +recovered shall be written. If no recovery information about a file is +available, an informational message to this effect shall be written, +and the edit shall proceed as usual. +.P +If the +.BR \(mic +option was specified, the first time a file that already exists +(including a file that might not exist but for which recovery +information is available, when the +.BR \(mir +option is specified) replaces or initializes the contents of the edit +buffer, the current line shall be set to the last line of the edit +buffer, the current column shall be set to non-\c +, +and the +.IR ex +commands specified with the +.BR \(mic +option shall be executed. In this case, the current line and current +column shall not be set as described for the command associated with +the replacement or initialization of the edit buffer contents. However, +if the +.BR \(mit +option or a +.BR tag +command is associated with this action, the +.BR \(mic +option commands shall be executed and then the movement to the tag +shall be performed. +.P +The current argument list shall initially be set to the filenames +specified by the user on the command line. If no filenames are +specified by the user, the current argument list shall be empty. If the +.BR \(mit +option was specified, it is unspecified whether any filename resulting +from tag processing shall be prepended to the current argument list. In +the case where the filename is added as a prefix to the current +argument list, the current argument list reference shall be set to that +filename. In the case where the filename is not added as a prefix to +the current argument list, the current argument list reference shall +logically be located before the first of the filenames specified on +the command line (for example, a subsequent +.IR ex +.BR next +command shall edit the first filename from the command line). If the +.BR \(mit +option was not specified, the current argument list reference shall be +to the first of the filenames on the command line. +.SS "Addressing in ex" +.P +Addressing in +.IR ex +relates to the current line and the current column; the address of a +line is its 1-based line number, the address of a column is its 1-based +count from the beginning of the line. Generally, the current line is +the last line affected by a command. The current line number is the +address of the current line. In each command description, the effect of +the command on the current line number and the current column is +described. +.P +Addresses are constructed as follows: +.IP " 1." 4 +The character +.BR '.' +(period) shall address the current line. +.IP " 2." 4 +The character +.BR '$' +shall address the last line of the edit buffer. +.IP " 3." 4 +The positive decimal number +.IR n +shall address the +.IR n th +line of the edit buffer. +.IP " 4." 4 +The address +.BR \(dq'x\(dq +refers to the line marked with the mark name character +.BR 'x' , +which shall be a lowercase letter from the portable character set, +the backquote character, or the single-quote character. It shall be an +error if the line that was marked is not currently present in the edit +buffer or the mark has not been set. Lines can be marked with the +.IR ex +.BR mark +or +.BR k +commands, or the +.IR vi +.BR m +command. +.IP " 5." 4 +A regular expression enclosed by + +characters (\c +.BR '/' ) +shall address the first line found by searching forwards from the line +following the current line toward the end of the edit buffer and +stopping at the first line for which the line excluding the terminating + +matches the regular expression. As stated in +.IR "Regular Expressions in ex", +an address consisting of a null regular expression delimited by + +characters (\c +.BR \(dq//\(dq ) +shall address the next line for which the line excluding the +terminating + +matches the last regular expression encountered. In addition, the second + +can be omitted at the end of a command line. If the +.BR wrapscan +edit option is set, the search shall wrap around to the beginning of +the edit buffer and continue up to and including the current line, so +that the entire edit buffer is searched. Within the regular expression, +the sequence +.BR \(dq\e/\(dq +shall represent a literal + +instead of the regular expression delimiter. +.IP " 6." 4 +A regular expression enclosed in + +characters (\c +.BR '?' ) +shall address the first line found by searching backwards from the line +preceding the current line toward the beginning of the edit buffer and +stopping at the first line for which the line excluding the terminating + +matches the regular expression. An address consisting of a null regular +expression delimited by + +characters (\c +.BR \(dq??\(dq ) +shall address the previous line for which the line excluding the +terminating + +matches the last regular expression encountered. In addition, the second + +can be omitted at the end of a command line. If the +.BR wrapscan +edit option is set, the search shall wrap around from the beginning of +the edit buffer to the end of the edit buffer and continue up to and +including the current line, so that the entire edit buffer is +searched. Within the regular expression, the sequence +.BR \(dq\e?\(dq +shall represent a literal + +instead of the RE delimiter. +.IP " 7." 4 +A + +(\c +.BR '\(pl' ) +or a minus-sign (\c +.BR '\(mi' ) +followed by a decimal number shall address the current line plus or +minus the number. A +.BR '\(pl' +or +.BR '\(mi' +not followed by a decimal number shall address the current line plus or +minus 1. +.P +Addresses can be followed by zero or more address offsets, optionally +-separated. +Address offsets are constructed as follows: +.IP " 1." 4 +A +.BR '\(pl' +or +.BR '\(mi' +immediately followed by a decimal number shall add (subtract) the +indicated number of lines to (from) the address. A +.BR '\(pl' +or +.BR '\(mi' +not followed by a decimal number shall add (subtract) 1 to (from) the +address. +.IP " 2." 4 +A decimal number shall add the indicated number of lines to the +address. +.P +It shall not be an error for an intermediate address value to be less +than zero or greater than the last line in the edit buffer. It shall be +an error for the final address value to be less than zero or greater +than the last line in the edit buffer. +.P +Commands take zero, one, or two addresses; see the descriptions of +.IR 1addr +and +.IR 2addr +in +.IR "Command Descriptions in ex". +If more than the required number of addresses are provided to a command +that requires zero addresses, it shall be an error. Otherwise, if more +than the required number of addresses are provided to a command, the +addresses specified first shall be evaluated and then discarded until +the maximum number of valid addresses remain. +.P +Addresses shall be separated from each other by a + +(\c +.BR ',' ) +or a + +(\c +.BR ';' ). +If no address is specified before or after a + +or + +separator, it shall be as if the address of the current line was +specified before or after the separator. In the case of a + +separator, the current line (\c +.BR '.' ) +shall be set to the first address, and only then will the next address +be calculated. This feature can be used to determine the starting line +for forwards and backwards searches (see rules 5. and 6.). +.P +A + +(\c +.BR '%' ) +shall be equivalent to entering the two addresses +.BR \(dq1,$\(dq . +.P +Any delimiting + +characters between addresses, address separators, or address offsets +shall be discarded. +.SS "Command Line Parsing in ex" +.P +The following symbol is used in this and following sections to describe +parsing behavior: +.IP "\fIescape\fP" 10 +If a character is referred to as ``\c +-escaped'' +or ``\c +\(hyV-escaped'', +it shall mean that the character acquired or lost a special +meaning by virtue of being preceded, respectively, by a + +or +\(hyV +character. Unless otherwise specified, the escaping character shall be +discarded at that time and shall not be further considered for any +purpose. +.P +Command-line parsing shall be done in the following steps. For each +step, characters already evaluated shall be ignored; that is, the +phrase ``leading character'' refers to the next character that has not +yet been evaluated. +.IP " 1." 4 +Leading + +characters shall be skipped. +.IP " 2." 4 +Leading + +characters shall be skipped. +.IP " 3." 4 +If the leading character is a double-quote character, the characters up +to and including the next non-\c +-escaped + +shall be discarded, and any subsequent characters shall be parsed as a +separate command. +.IP " 4." 4 +Leading characters that can be interpreted as addresses shall be +evaluated; see +.IR "Addressing in ex". +.IP " 5." 4 +Leading + +characters shall be skipped. +.IP " 6." 4 +If the next character is a + +character or a +: +.RS 4 +.IP " a." 4 +If the next character is a +: +.RS 4 +.IP " i." 5 +If +.IR ex +is in open or visual mode, the current line shall be set to the last +address specified, if any. +.IP ii. 5 +Otherwise, if the last command was terminated by a + +character, no action shall be taken; for example, the command +.BR \(dq||\(dq +shall execute two implied commands, not three. +.IP iii. 5 +Otherwise, step 6.b. shall apply. +.RE +.IP " b." 4 +Otherwise, the implied command shall be the +.BR print +command. The last +.BR # , +.BR p , +and +.BR l +flags specified to any +.IR ex +command shall be remembered and shall apply to this implied command. +Executing the +.IR ex +.BR number , +.BR print , +or +.BR list +command shall set the remembered flags to +.BR # , +nothing, and +.BR l , +respectively, plus any other flags specified for that execution of the +.BR number , +.BR print , +or +.BR list +command. +.RS 4 +.P +If +.IR ex +is not currently performing a +.BR global +or +.BR v +command, and no address or count is specified, the current line shall +be incremented by 1 before the command is executed. If incrementing the +current line would result in an address past the last line in the edit +buffer, the command shall fail, and the increment shall not happen. +.RE +.IP " c." 4 +The + +or + +character shall be discarded and any subsequent characters shall be +parsed as a separate command. +.RE +.IP " 7." 4 +The command name shall be comprised of the next character (if the +character is not alphabetic), or the next character and any subsequent +alphabetic characters (if the character is alphabetic), with the +following exceptions: +.RS 4 +.IP " a." 4 +Commands that consist of any prefix of the characters in the command +name +.BR delete , +followed immediately by any of the characters +.BR 'l' , +.BR 'p' , +.BR '\(pl' , +.BR '\(mi' , +or +.BR '#' +shall be interpreted as a +.BR delete +command, followed by a +, +followed by the characters that were not part of the prefix of the +.BR delete +command. The maximum number of characters shall be matched to the +command name +.BR delete ; +for example, +.BR \(dqdel\(dq +shall not be treated as +.BR \(dqde\(dq +followed by the flag +.BR l . +.IP " b." 4 +Commands that consist of the character +.BR 'k' , +followed by a character that can be used as the name of a mark, shall +be equivalent to the mark command followed by a +, +followed by the character that followed the +.BR 'k' . +.IP " c." 4 +Commands that consist of the character +.BR 's' , +followed by characters that could be interpreted as valid options to +the +.BR s +command, shall be the equivalent of the +.BR s +command, without any pattern or replacement values, followed by a +, +followed by the characters after the +.BR 's' . +.RE +.IP " 8." 4 +The command name shall be matched against the possible command names, +and a command name that contains a prefix matching the characters +specified by the user shall be the executed command. In the case of +commands where the characters specified by the user could be ambiguous, +the executed command shall be as follows: +.TS +center tab(!) box; +lB | lB || lB | lB || lB | lB. +a!append!n!next!t!t +c!change!p!print!u!undo +ch!change!pr!print!un!undo +e!edit!r!read!v!v +m!move!re!read!w!write +ma!mark!s!s +.TE +.RS 4 +.P +Implementation extensions with names causing similar ambiguities shall +not be checked for a match until all possible matches for commands +specified by POSIX.1\(hy2008 have been checked. +.RE +.IP " 9." 4 +If the command is a +.BR ! +command, or if the command is a +.BR read +command followed by zero or more + +characters and a +.BR ! , +or if the command is a +.BR write +command followed by one or more + +characters and a +.BR ! , +the rest of the command shall include all characters up to a non-\c +-escaped +. +The + +shall be discarded and any subsequent characters shall be parsed as a +separate +.IR ex +command. +.IP 10. 4 +Otherwise, if the command is an +.BR edit , +.BR ex , +or +.BR next +command, or a +.BR visual +command while in open or visual mode, the next part of the command +shall be parsed as follows: +.RS 4 +.IP " a." 4 +Any +.BR '!' +character immediately following the command shall be skipped and be +part of the command. +.IP " b." 4 +Any leading + +characters shall be skipped and be part of the command. +.IP " c." 4 +If the next character is a +.BR '\(pl' , +characters up to the first non-\c +-escaped + +or non-\c +-escaped + +shall be skipped and be part of the command. +.IP " d." 4 +The rest of the command shall be determined by the steps specified in +paragraph 12. +.RE +.IP 11. 4 +Otherwise, if the command is a +.BR global , +.BR open , +.BR s , +or +.BR v +command, the next part of the command shall be parsed as follows: +.RS 4 +.IP " a." 4 +Any leading + +characters shall be skipped and be part of the command. +.IP " b." 4 +If the next character is not an alphanumeric, double-quote, +, +, +or + +character: +.RS 4 +.IP " i." 5 +The next character shall be used as a command delimiter. +.IP ii. 5 +If the command is a +.BR global , +.BR open , +or +.BR v +command, characters up to the first non-\c +-escaped +, +or first non-\c +-escaped +delimiter character, shall be skipped and be part of the command. +.IP iii. 5 +If the command is an +.BR s +command, characters up to the first non-\c +-escaped +, +or second non-\c +-escaped +delimiter character, shall be skipped and be part of the command. +.RE +.IP " c." 4 +If the command is a +.BR global +or +.BR v +command, characters up to the first non-\c +-escaped + +shall be skipped and be part of the command. +.IP " d." 4 +Otherwise, the rest of the command shall be determined by the steps +specified in paragraph 12. +.RE +.IP 12. 4 +Otherwise: +.RS 4 +.IP " a." 4 +If the command was a +.BR map , +.BR unmap , +.BR abbreviate , +or +.BR unabbreviate +command, characters up to the first non-\c +\(hyV-escaped +, +, +or double-quote character shall be skipped and be part of the command. +.IP " b." 4 +Otherwise, characters up to the first non-\c +-escaped +, +, +or double-quote character shall be skipped and be part of the command. +.IP " c." 4 +If the command was an +.BR append , +.BR change , +or +.BR insert +command, and the step 12.b. ended at a + +character, any subsequent characters, up to the next non-\c +-escaped + +shall be used as input text to the command. +.IP " d." 4 +If the command was ended by a double-quote character, all subsequent +characters, up to the next non-\c +-escaped +, +shall be discarded. +.IP " e." 4 +The terminating + +or + +character shall be discarded and any subsequent characters shall be +parsed as a separate +.IR ex +command. +.RE +.P +Command arguments shall be parsed as described by the Synopsis and +Description of each individual +.IR ex +command. This parsing shall not be +-sensitive, +except for the +.BR ! +argument, which must follow the command name without intervening + +characters, and where it would otherwise be ambiguous. For example, +.IR count +and +.IR flag +arguments need not be +-separated +because +.BR \(dqd22p\(dq +is not ambiguous, but +.IR file +arguments to the +.IR ex +.BR next +command must be separated by one or more + +characters. Any + +in command arguments for the +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap +commands can be +\(hyV-escaped, +in which case the + +shall not be used as an argument delimiter. Any + +in the command argument for any other command can be +-escaped, +in which case that + +shall not be used as an argument delimiter. +.P +Within command arguments for the +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap +commands, any character can be +\(hyV-escaped. +All such escaped characters shall be treated literally and shall have +no special meaning. Within command arguments for all other +.IR ex +commands that are not regular expressions or replacement strings, any +character that would otherwise have a special meaning can be +-escaped. +Escaped characters shall be treated literally, without special meaning +as shell expansion characters or +.BR '!' , +.BR '%' , +and +.BR '#' +expansion characters. See +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex" +for descriptions of command arguments that are regular expressions or +replacement strings. +.P +Non-\c +-escaped +.BR '%' +characters appearing in +.IR file +arguments to any +.IR ex +command shall be replaced by the current pathname; unescaped +.BR '#' +characters shall be replaced by the alternate pathname. It shall be an +error if +.BR '%' +or +.BR '#' +characters appear unescaped in an argument and their corresponding +values are not set. +.P +Non-\c +-escaped +.BR '!' +characters in the arguments to either the +.IR ex +.BR ! +command or the open and visual mode +.BR ! +command, or in the arguments to the +.IR ex +.BR read +command, where the first non-\c + +after the command name is a +.BR '!' +character, or in the arguments to the +.IR ex +.BR write +command where the command name is followed by one or more + +characters and the first non-\c + +after the command name is a +.BR '!' +character, shall be replaced with the arguments to the last of those +three commands as they appeared after all unescaped +.BR '%' , +.BR '#' , +and +.BR '!' +characters were replaced. It shall be an error if +.BR '!' +characters appear unescaped in one of these commands and there has been +no previous execution of one of these commands. +.P +If an error occurs during the parsing or execution of an +.IR ex +command: +.IP " *" 4 +An informational message to this effect shall be written. Execution of +the +.IR ex +command shall stop, and the cursor (for example, the current line and +column) shall not be further modified. +.IP " *" 4 +If the +.IR ex +command resulted from a map expansion, all characters from that map +expansion shall be discarded, except as otherwise specified by the +.BR map +command. +.IP " *" 4 +Otherwise, if the +.IR ex +command resulted from the processing of an +.IR EXINIT +environment variable, a +.BR .exrc +file, a +.BR :source +command, a +.BR \(mic +option, or a +.BR + \c +.IR command +specified to an +.IR ex +.BR edit , +.BR ex , +.BR next , +or +.BR visual +command, no further commands from the source of the commands shall be +executed. +.IP " *" 4 +Otherwise, if the +.IR ex +command resulted from the execution of a buffer or a +.BR global +or +.BR v +command, no further commands caused by the execution of the buffer or +the +.BR global +or +.BR v +command shall be executed. +.IP " *" 4 +Otherwise, if the +.IR ex +command was not terminated by a +, +all characters up to and including the next non-\c +-escaped + +shall be discarded. +.SS "Input Editing in ex" +.P +The following symbol is used in this and the following sections to +specify command actions: +.IP "\fIword\fP" 10 +In the POSIX locale, a word consists of a maximal sequence of letters, +digits, and underscores, delimited at both ends by characters other +than letters, digits, or underscores, or by the beginning or end of a +line or the edit buffer. +.P +When accepting input characters from the user, in either +.IR ex +command mode or +.IR ex +text input mode, +.IR ex +shall enable canonical mode input processing, as defined in the System Interfaces volume of POSIX.1\(hy2008. +.br +.P +If in +.IR ex +text input mode: +.IP " 1." 4 +If the +.BR number +edit option is set, +.IR ex +shall prompt for input using the line number that would be assigned to +the line if it is entered, in the format specified for the +.IR ex +.BR number +command. +.IP " 2." 4 +If the +.BR autoindent +edit option is set, +.IR ex +shall prompt for input using +.BR autoindent +characters, as described by the +.BR autoindent +edit option. +.BR autoindent +characters shall follow the line number, if any. +.P +If in +.IR ex +command mode: +.IP " 1." 4 +If the +.BR prompt +edit option is set, input shall be prompted for using a single +.BR ':' +character; otherwise, there shall be no prompt. +.P +The input characters in the following sections shall have the following +effects on the input line. +.SS "Scroll" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +eof +.fi \fR +.P +.RE +.RE +.P +See the description of the +.IR stty +.IR eof +character in +.IR "\fIstty\fR\^". +.P +If in +.IR ex +command mode: +.sp +.RS +If the +.IR eof +character is the first character entered on the line, the line shall be +evaluated as if it contained two characters: a +\(hyD +and a +. +.P +Otherwise, the +.IR eof +character shall have no special meaning. +.RE +.br +.P +If in +.IR ex +text input mode: +.sp +.RS +If the cursor follows an +.BR autoindent +character, the +.BR autoindent +characters in the line shall be modified so that a part of the next +text input character will be displayed on the first column in the line +after the previous +.BR shiftwidth +edit option column boundary, and the user shall be prompted again for +input for the same line. +.P +Otherwise, if the cursor follows a +.BR '0' , +which follows an +.BR autoindent +character, and the +.BR '0' +was the previous text input character, the +.BR '0' +and all +.BR autoindent +characters in the line shall be discarded, and the user shall be +prompted again for input for the same line. +.P +Otherwise, if the cursor follows a +.BR '^' , +which follows an +.BR autoindent +character, and the +.BR '^' +was the previous text input character, the +.BR '^' +and all +.BR autoindent +characters in the line shall be discarded, and the user shall be +prompted again for input for the same line. In addition, the +.BR autoindent +level for the next input line shall be derived from the same line from +which the +.BR autoindent +level for the current input line was derived. +.P +Otherwise, if there are no +.BR autoindent +or text input characters in the line, the +.IR eof +character shall be discarded. +.P +Otherwise, the +.IR eof +character shall have no special meaning. +.RE +.SS "" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.br +-J +.fi \fR +.P +.RE +.RE +.P +If in +.IR ex +command mode: +.sp +.RS +Cause the command line to be parsed; +\(hyJ +shall be mapped to the + +for this purpose. +.RE +.br +.P +If in +.IR ex +text input mode: +.sp +.RS +Terminate the current line. If there are no characters other than +.BR autoindent +characters on the line, all characters on the line shall be discarded. +.P +Prompt for text input on a new line after the current line. If the +.BR autoindent +edit option is set, an appropriate number of +.BR autoindent +characters shall be added as a prefix to the line as described by the +.IR ex +.BR autoindent +edit option. +.RE +.SS "" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.fi \fR +.P +.RE +.RE +.P +Allow the entry of a subsequent + +or +\(hyJ +as a literal character, removing any special meaning that it may have +to the editor during text input mode. The + +character shall be retained and evaluated when the command line is +parsed, or retained and included when the input text becomes part of +the edit buffer. +.SS "\(hyV" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-V +.fi \fR +.P +.RE +.RE +.P +Allow the entry of any subsequent character as a literal character, +removing any special meaning that it may have to the editor during text +input mode. The +\(hyV +character shall be discarded before the command line is parsed or the +input text becomes part of the edit buffer. +.P +If the ``literal next'' functionality is performed by the underlying +system, it is implementation-defined whether a character other than +\(hyV +performs this function. +.SS "\(hyW" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-W +.fi \fR +.P +.RE +.RE +.P +Discard the +\(hyW, +and the word previous to it in the input line, including any + +characters following the word and preceding the +\(hyW. +If the ``word erase'' functionality is performed by the underlying +system, it is implementation-defined whether a character other than +\(hyW +performs this function. +.SS "Command Descriptions in ex" +.P +The following symbols are used in this section to represent command +modifiers. Some of these modifiers can be omitted, in which case the +specified defaults shall be used. +.IP "\fI1addr\fR" 10 +A single line address, given in any of the forms described in +.IR "Addressing in ex"; +the default shall be the current line (\c +.BR '.' ), +unless otherwise specified. +.RS 10 +.P +If the line address is zero, it shall be an error, unless otherwise +specified in the following command descriptions. +.P +If the edit buffer is empty, and the address is specified with a +command other than +.BR = , +.BR append , +.BR insert , +.BR open , +.BR put , +.BR read , +or +.BR visual , +or the address is not zero, it shall be an error. +.RE +.IP "\fI2addr\fP" 10 +Two addresses specifying an inclusive range of lines. If no addresses +are specified, the default for +.IR 2addr +shall be the current line only (\c +.BR \(dq.,.\(dq ), +unless otherwise specified in the following command descriptions. If +one address is specified, +.IR 2addr +shall specify that line only, unless otherwise specified in the +following command descriptions. +.RS 10 +.P +It shall be an error if the first address is greater than the second +address. +.P +If the edit buffer is empty, and the two addresses are specified with a +command other than the +.BR ! , +.BR write , +.BR wq , +or +.BR xit +commands, or either address is not zero, it shall be an error. +.RE +.IP "\fIcount\fP" 10 +A positive decimal number. If +.IR count +is specified, it shall be equivalent to specifying an additional +address to the command, unless otherwise specified by the following +command descriptions. The additional address shall be equal to the last +address specified to the command (either explicitly or by default) plus +.IR count \(mi1. +.RS 10 +.P +If this would result in an address greater than the last line of the +edit buffer, it shall be corrected to equal the last line of the edit +buffer. +.RE +.IP "\fIflags\fP" 10 +One or more of the characters +.BR '\(pl' , +.BR '\(mi' , +.BR '#' , +.BR 'p' , +or +.BR 'l' +(ell). The flag characters can be +-separated, +and in any order or combination. The characters +.BR '#' , +.BR 'p' , +and +.BR 'l' +shall cause lines to be written in the format specified by the +.BR print +command with the specified +.IR flags . +.RS 10 +.P +The lines to be written are as follows: +.IP " 1." 4 +All edit buffer lines written during the execution of the +.IR ex +.BR & , +.BR ~ , +.BR list , +.BR number , +.BR open , +.BR print , +.BR s , +.BR visual , +and +.BR z +commands shall be written as specified by +.IR flags . +.IP " 2." 4 +After the completion of an +.IR ex +command with a flag as an argument, the current line shall be written +as specified by +.IR flags , +unless the current line was the last line written by the command. +.P +The characters +.BR '\(pl' +and +.BR '\(mi' +cause the value of the current line after the execution of the +.IR ex +command to be adjusted by the offset address as described in +.IR "Addressing in ex". +This adjustment shall occur before the current line is written as +described in 2. above. +.P +The default for +.IR flags +shall be none. +.RE +.IP "\fIbuffer\fP" 10 +One of a number of named areas for holding text. The named buffers are +specified by the alphanumeric characters of the POSIX locale. There +shall also be one ``unnamed'' buffer. When no buffer is specified for +editor commands that use a buffer, the unnamed buffer shall be used. +Commands that store text into buffers shall store the text as it was +before the command took effect, and shall store text occurring earlier +in the file before text occurring later in the file, regardless of how +the text region was specified. Commands that store text into buffers +shall store the text into the unnamed buffer as well as any specified +buffer. +.RS 10 +.P +In +.IR ex +commands, buffer names are specified as the name by itself. In open or +visual mode commands the name is preceded by a double-quote (\c +.BR '\&"' ) +character. +.P +If the specified buffer name is an uppercase character, and the buffer +contents are to be modified, the buffer shall be appended to rather +than being overwritten. If the buffer is not being modified, specifying +the buffer name in lowercase and uppercase shall have identical +results. +.P +There shall also be buffers named by the numbers 1 through 9. In open +and visual mode, if a region of text including characters from more +than a single line is being modified by the +.IR vi +.BR c +or +.BR d +commands, the motion character associated with the +.BR c +or +.BR d +commands specifies that the buffer text shall be in line mode, or the +commands +.BR % , +.BR ` , +.BR / , +.BR ? , +.BR ( , +.BR ) , +.BR N , +.BR n , +.BR { , +or +.BR } +are used to define a region of text for the +.BR c +or +.BR d +commands, the contents of buffers 1 through 8 shall be moved into the +buffer named by the next numerically greater value, the contents of +buffer 9 shall be discarded, and the region of text shall be copied +into buffer 1. This shall be in addition to copying the text into a +user-specified buffer or unnamed buffer, or both. Numeric buffers can +be specified as a source buffer for open and visual mode commands; +however, specifying a numeric buffer as the write target of an open or +visual mode command shall have unspecified results. +.P +The text of each buffer shall have the characteristic of being in +either line or character mode. Appending text to a non-empty buffer +shall set the mode to match the characteristic of the +text being appended. Appending text to a buffer shall cause the +creation of at least one additional line in the buffer. All text stored +into buffers by +.IR ex +commands shall be in line mode. The +.IR ex +commands that use buffers as the source of text specify individually +how buffers of different modes are handled. Each open or visual mode +command that uses buffers for any purpose specifies individually the +mode of the text stored into the buffer and how buffers of different +modes are handled. +.RE +.IP "\fIfile\fP" 10 +Command text used to derive a pathname. The default shall be the +current pathname, as defined previously, in which case, if no current +pathname has yet been established it shall be an error, except where +specifically noted in the individual command descriptions that follow. +If the command text contains any of the characters +.BR '~' , +.BR '{' , +.BR '[' , +.BR '*' , +.BR '?' , +.BR '$' , +.BR '\&"' , +backquote, single-quote, and +, +it shall be subjected to the process of ``shell expansions'', as +described below; if more than a single pathname results and the +command expects only one, it shall be an error. +.RS 10 +.P +The process of shell expansions in the editor shall be done as +follows. The +.IR ex +utility shall pass two arguments to the program named by the shell edit +option; the first shall be +.BR \(mic , +and the second shall be the string +.BR \(dqecho\(dq +and the command text as a single argument. The standard output and +standard error of that command shall replace the command text. +.RE +.IP "\fB!\fP" 10 +A character that can be appended to the command name to modify its +operation, as detailed in the individual command descriptions. With the +exception of the +.IR ex +.BR read , +.BR write , +and +.BR ! +commands, the +.BR '!' +character shall only act as a modifier if there are no + +characters between it and the command name. +.IP "\fIremembered\ search\ direction\fP" 10 +.br +The +.IR vi +commands +.BR N +and +.BR n +begin searching in a forwards or backwards direction in the edit buffer +based on a remembered search direction, which is initially unset, and +is set by the +.IR ex +.BR global , +.BR v , +.BR s , +and +.BR tag +commands, and the +.IR vi +.BR / +and +.BR ? +commands. +.SS "Abbreviate" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ab\fB[\fIbreviate\fB][\fIlhs rhs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +and +.IR rhs +are not specified, write the current list of abbreviations and do +nothing more. +.P +Implementations may restrict the set of characters accepted in +.IR lhs +or +.IR rhs , +except that printable characters and + +characters shall not be restricted. Additional restrictions shall be +implementation-defined. +.P +In both +.IR lhs +and +.IR rhs , +any character may be escaped with a +\(hyV, +in which case the character shall not be used to delimit +.IR lhs +from +.IR rhs , +and the escaping +\(hyV +shall be discarded. +.P +In open and visual text input mode, if a non-word or + +character that is not escaped by a +\(hyV +character is entered after a word character, a check shall be made for +a set of characters matching +.IR lhs , +in the text input entered during this command. If it is found, the +effect shall be as if +.IR rhs +was entered instead of +.IR lhs . +.P +The set of characters that are checked is defined as follows: +.IP " 1." 4 +If there are no characters inserted before the word and non-word or + +characters that triggered the check, the set of characters shall +consist of the word character. +.IP " 2." 4 +If the character inserted before the word and non-word or + +characters that triggered the check is a word character, the set of +characters shall consist of the characters inserted immediately before +the triggering characters that are word characters, plus the triggering +word character. +.IP " 3." 4 +If the character inserted before the word and non-word or + +characters that triggered the check is not a word character, the set of +characters shall consist of the characters that were inserted before +the triggering characters that are neither + +characters nor word characters, plus the triggering word character. +.P +It is unspecified whether the +.IR lhs +argument entered for the +.IR ex +.BR abbreviate +and +.BR unabbreviate +commands is replaced in this fashion. Regardless of whether or not the +replacement occurs, the effect of the command shall be as if the +replacement had not occurred. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Append" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRa\fB[\fRppend\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR ex +text input mode; the input text shall be placed after the specified +line. If line zero is specified, the text shall be placed at the +beginning of the edit buffer. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "Current line" : +Set to the last input line; if no lines were input, set to the +specified line, or to the first line of the edit buffer if a line of +zero was specified, or zero if the edit buffer is empty. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Arguments" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ar\fB[\fIgs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the current argument list, with the current argument-list entry, +if any, between +.BR '[' +and +.BR ']' +characters. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Change" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRc\fB[\fRhange\fB][\fR!\fB][\fIcount\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR ex +text input mode; the input text shall replace the specified lines. The +specified lines shall be copied into the unnamed buffer, which shall +become a line mode buffer. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "Current line" : +Set to the last input line; if no lines were input, set to the line +before the first address, or to the first line of the edit buffer if +there are no lines preceding the first address, or to zero if the edit +buffer is empty. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Change Directory" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +chd\fB[\fRir\fB][\fR!\fB][\fIdirectory\fB]\fR +cd\fB[\fR!\fB][\fIdirectory\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Change the current working directory to +.IR directory . +.P +If no +.IR directory +argument is specified, and the +.IR HOME +environment variable is set to a non-null and non-empty value, +.IR directory +shall default to the value named in the +.IR HOME +environment variable. If the +.IR HOME +environment variable is empty or is undefined, the default value of +.IR directory +is implementation-defined. +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, and the current pathname does not begin +with a +.BR '/' , +it shall be an error. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Copy" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRco\fB[\fRpy\fB] \fI1addr \fB[\fIflags\fB] +[\fI2addr\fB] \fRt \fI1addr \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Copy the specified lines after the specified destination line; line +zero specifies that the lines shall be placed at the beginning of the +edit buffer. +.P +.IR "Current line" : +Set to the last line copied. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Delete" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRd\fB[\fRelete\fB][\fIbuffer\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Delete the specified lines into a buffer (defaulting to the unnamed +buffer), which shall become a line-mode buffer. +.P +Flags can immediately follow the command name; see +.IR "Command Line Parsing in ex". +.P +.IR "Current line" : +Set to the line following the deleted lines, or to the last line in the +edit buffer if that line is past the end of the edit buffer, or to zero +if the edit buffer is empty. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Edit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +e\fB[\fRdit\fB][\fR!\fB][\fR+\fIcommand\fB][\fIfile\fB]\fR +ex\fB[\fR!\fB][\fR+\fIcommand\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error. +.P +If +.IR file +is specified, replace the current contents of the edit buffer with the +current contents of +.IR file , +and set the current pathname to +.IR file . +If +.IR file +is not specified, replace the current contents of the edit buffer with +the current contents of the file named by the current pathname. If for +any reason the current contents of the file cannot be accessed, the +edit buffer shall be empty. +.P +The +.BR + \c +.IR command +option shall be +-delimited; + +characters within the +.BR + \c +.IR command +can be escaped by preceding them with a + +character. The +.BR + \c +.IR command +shall be interpreted as an +.IR ex +command immediately after the contents of the edit buffer have been +replaced and the current line and column have been set. +.P +If the edit buffer is empty: +.P +.IR "Current line" : +Set to 0. +.P +.IR "Current column" : +Set to 1. +.P +Otherwise, if executed while in +.IR ex +command mode or if the +.BR + \c +.IR command +argument is specified: +.P +.IR "Current line" : +Set to the last line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.P +Otherwise, if +.IR file +is omitted or results in the current pathname: +.P +.IR "Current line" : +Set to the first line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.P +Otherwise, if +.IR file +is the same as the last file edited, the line and column shall be set +as follows; if the file was previously edited, the line and column may +be set as follows: +.P +.IR "Current line" : +Set to the last value held when that file was last edited. If this +value is not a valid line in the new edit buffer, set to the first line +of the edit buffer. +.P +.IR "Current column" : +If the current line was set to the last value held when the file was +last edited, set to the last value held when the file was last edited. +Otherwise, or if the last value is not a valid column in the new edit +buffer, set to non-\c +. +.br +.P +Otherwise: +.P +.IR "Current line" : +Set to the first line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.SS "File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +f\fB[\fRile\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If a +.IR file +argument is specified, the alternate pathname shall be set to the +current pathname, and the current pathname shall be set to +.IR file . +.P +Write an informational message. If the file has a current pathname, it +shall be included in this message; otherwise, the message shall +indicate that there is no current pathname. If the edit buffer +contains lines, the current line number and the number of lines in the +edit buffer shall be included in this message; otherwise, the message +shall indicate that the edit buffer is empty. If the edit buffer has +been modified since the last complete write, this fact shall be +included in this message. If the +.BR readonly +edit option is set, this fact shall be included in this message. The +message may contain other unspecified information. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Global" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRg\fB[\fRlobal\fB] \fR/\fIpattern\fR/ \fB[\fIcommands\fB] +[\fI2addr\fB] \fRv /\fIpattern\fR/ \fB[\fIcommands\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The optional +.BR '!' +character after the +.BR global +command shall be the same as executing the +.BR v +command. +.P +If +.IR pattern +is empty (for example, +.BR \(dq//\(dq ) +or not specified, the last regular expression used in the editor +command shall be used as the +.IR pattern . +The +.IR pattern +can be delimited by + +characters (shown in the Synopsis), as well as any non-alphanumeric +or non-\c + +other than +, +, +, +or double-quote. +.P +If no lines are specified, the lines shall default to the entire file. +.P +The +.BR global +and +.BR v +commands are logically two-pass operations. First, mark the lines +within the specified lines for which the line excluding the terminating + +matches (\c +.BR global ) +or does not match (\c +.BR v +or +.BR global! ) +the specified pattern. Second, execute the +.IR ex +commands given by +.IR commands , +with the current line (\c +.BR '.' ) +set to each marked line. If an error occurs during this process, or the +contents of the edit buffer are replaced (for example, by the +.IR ex +.BR :edit +command) an error message shall be written and no more commands +resulting from the execution of this command shall be processed. +.P +Multiple +.IR ex +commands can be specified by entering multiple commands on a single +line using a + +to delimit them, or one per line, by escaping each + +with a +. +.P +If no commands are specified: +.IP " 1." 4 +If in +.IR ex +command mode, it shall be as if the +.BR print +command were specified. +.IP " 2." 4 +Otherwise, no command shall be executed. +.P +For the +.BR append , +.BR change , +and +.BR insert +commands, the input text shall be included as part of the command, and +the terminating + +can be omitted if the command ends the list of commands. The +.BR open +and +.BR visual +commands can be specified as one of the commands, in which case each +marked line shall cause the editor to enter open or visual mode. If +open or visual mode is exited using the +.IR vi +.BR Q +command, the current line shall be set to the next marked line, and +open or visual mode reentered, until the list of marked lines is +exhausted. +.P +The +.BR global , +.BR v , +and +.BR undo +commands cannot be used in +.IR commands . +Marked lines may be deleted by commands executed for lines occurring +earlier in the file than the marked lines. In this case, no commands +shall be executed for the deleted lines. +.P +If the remembered search direction is not set, the +.BR global +and +.BR v +commands shall set it to forward. +.P +The +.BR autoprint +and +.BR autoindent +edit options shall be inhibited for the duration of the +.BR g +or +.BR v +command. +.P +.IR "Current line" : +If no commands executed, set to the last marked line. Otherwise, as +specified for the executed +.IR ex +commands. +.P +.IR "Current column" : +If no commands are executed, set to non-\c +; +otherwise, as specified for the individual +.IR ex +commands. +.SS "Insert" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRi\fB[\fRnsert\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR ex +text input mode; the input text shall be placed before the specified +line. If the line is zero or 1, the text shall be placed at the +beginning of the edit buffer. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "Current line" : +Set to the last input line; if no lines were input, set to the line +before the specified line, or to the first line of the edit buffer if +there are no lines preceding the specified line, or zero if the edit +buffer is empty. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Join" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRj\fB[\fRoin\fB][\fR!\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is specified: +.sp +.RS +If no address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the current line and the current line plus +.IR count +(.\|,\|. + +.IR count ). +.P +If one address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the specified address and the specified address plus +.IR count +(\c +.IR addr ,\c +.IR addr ++ +.IR count ). +.P +If two addresses were specified, the +.BR join +command shall behave as if an additional address, equal to the last +address plus +.IR count +\(mi1 (\c +.IR addr1 ,\c +.IR addr2 ,\c +.IR addr2 ++ +.IR count +\(mi1), was specified. +.P +If this would result in a second address greater than the last line of +the edit buffer, it shall be corrected to be equal to the last line of +the edit buffer. +.RE +.P +If no +.IR count +is specified: +.sp +.RS +If no address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the current line and the next line (.\|,\|. +1). +.P +If one address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the specified address and the next line (\c +.IR addr ,\c +.IR addr ++1). +.RE +.P +Join the text from the specified lines together into a single line, +which shall replace the specified lines. +.P +If a +.BR '!' +character is appended to the command name, the +.BR join +shall be without modification of any line, independent of the current +locale. +.P +Otherwise, in the POSIX locale, set the current line to the first of +the specified lines, and then, for each subsequent line, proceed as +follows: +.IP " 1." 4 +Discard leading + +characters from the line to be joined. +.IP " 2." 4 +If the line to be joined is now empty, delete it, and skip steps 3 +through 5. +.IP " 3." 4 +If the current line ends in a +, +or the first character of the line to be joined is a +.BR ')' +character, join the lines without further modification. +.IP " 4." 4 +If the last character of the current line is a +.BR '.' , +join the lines with two + +characters between them. +.IP " 5." 4 +Otherwise, join the lines with a single + +between them. +.P +.IR "Current line" : +Set to the first line specified. +.P +.IR "Current column" : +Set to non-\c +. +.SS "List" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRl\fB[\fRist\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +command: +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB] \fRl\fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.P +See +.IR "Print". +.SS "Map" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +map\fB[\fR!\fB][\fIlhs rhs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +and +.IR rhs +are not specified: +.IP " 1." 4 +If +.BR '!' +is specified, write the current list of text input mode maps. +.IP " 2." 4 +Otherwise, write the current list of command mode maps. +.IP " 3." 4 +Do nothing more. +.P +Implementations may restrict the set of characters accepted in +.IR lhs +or +.IR rhs , +except that printable characters and + +characters shall not be restricted. Additional restrictions shall be +implementation-defined. In both +.IR lhs +and +.IR rhs , +any character can be escaped with a +\(hyV, +in which case the character shall not be used to delimit +.IR lhs +from +.IR rhs , +and the escaping +\(hyV +shall be discarded. +.P +If the character +.BR '!' +is appended to the +.BR map +command name, the mapping shall be effective during open or visual text +input mode rather than +.BR open +or +.BR visual +command mode. This allows +.IR lhs +to have two different +.BR map +definitions at the same time: one for command mode and one for text +input mode. +.br +.P +For command mode mappings: +.sp +.RS +When the +.IR lhs +is entered as any part of a +.IR vi +command in open or visual mode (but not as part of the arguments to the +command), the action shall be as if the corresponding +.IR rhs +had been entered. +.P +If any character in the command, other than the first, is escaped using +a +\(hyV +character, that character shall not be part of a match to an +.IR lhs . +.P +It is unspecified whether implementations shall support +.BR map +commands where the +.IR lhs +is more than a single character in length, where the first character of +the +.IR lhs +is printable. +.RE +.P +.sp +.RS +If +.IR lhs +contains more than one character and the first character is +.BR '#' , +followed by a sequence of digits corresponding to a numbered function +key, then when this function key is typed it shall be mapped to +.IR rhs . +Characters other than digits following a +.BR '#' +character also represent the function key named by the characters in +the +.IR lhs +following the +.BR '#' +and may be mapped to +.IR rhs . +It is unspecified how function keys are named or what function keys are +supported. +.RE +.P +For text input mode mappings: +.sp +.RS +When the +.IR lhs +is entered as any part of text entered in open or visual text input +modes, the action shall be as if the corresponding +.IR rhs +had been entered. +.P +If any character in the input text is escaped using a +\(hyV +character, that character shall not be part of a match to an +.IR lhs . +.P +It is unspecified whether the +.IR lhs +text entered for subsequent +.BR map +or +.BR unmap +commands is replaced with the +.IR rhs +text for the purposes of the screen display; regardless of whether or +not the display appears as if the corresponding +.IR rhs +text was entered, the effect of the command shall be as if the +.IR lhs +text was entered. +.RE +.P +If only part of the +.IR lhs +is entered, it is unspecified how long the editor will wait for +additional, possibly matching characters before treating the already +entered characters as not matching the +.IR lhs . +.P +The +.IR rhs +characters shall themselves be subject to remapping, unless otherwise +specified by the +.BR remap +edit option, except that if the characters in +.IR lhs +occur as prefix characters in +.IR rhs , +those characters shall not be remapped. +.P +On block-mode terminals, the mapping need not occur immediately (for +example, it may occur after the terminal transmits a group of +characters to the system), but it shall achieve the same results as if +it occurred immediately. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Mark" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRma\fB[\fRrk\fB] \fIcharacter +\fB[\fI1addr\fB] \fRk \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +Implementations shall support +.IR character +values of a single lowercase letter of the POSIX locale and the +backquote and single-quote characters; support of other characters is +implementation-defined. +.P +If executing the +.IR vi +.BR m +command, set the specified mark to the current line and 1-based +numbered character referenced by the current column, if any; otherwise, +column position 1. +.P +Otherwise, set the specified mark to the specified line and 1-based +numbered first non-\c + +non-\c + +in the line, if any; otherwise, the last non-\c + +in the line, if any; otherwise, column position 1. +.P +The mark shall remain associated with the line until the mark is reset +or the line is deleted. If a deleted line is restored by a subsequent +.BR undo +command, any marks previously associated with the line, which have not +been reset, shall be restored as well. Any use of a mark not associated +with a current line in the edit buffer shall be an error. +.P +The marks +.BR ` +and +.BR ' +shall be set as described previously, immediately before the following +events occur in the editor: +.IP " 1." 4 +The use of +.BR '$' +as an +.IR ex +address +.IP " 2." 4 +The use of a positive decimal number as an +.IR ex +address +.IP " 3." 4 +The use of a search command as an +.IR ex +address +.IP " 4." 4 +The use of a mark reference as an +.IR ex +address +.IP " 5." 4 +The use of the following open and visual mode commands: +\(hy], +.BR % , +.BR ( , +.BR ) , +.BR [ , +.BR ] , +.BR { , +.BR } +.IP " 6." 4 +The use of the following open and visual mode commands: +.BR ' , +.BR G , +.BR H , +.BR L , +.BR M , +.BR z +if the current line will change as a result of the command +.IP " 7." 4 +The use of the open and visual mode commands: +.BR / , +.BR ? , +.BR N , +.BR ` , +.BR n +if the current line or column will change as a result of the command +.IP " 8." 4 +The use of the +.IR ex +mode commands: +.BR z , +.BR undo , +.BR global , +.BR v +.P +For rules 1., 2., 3., and 4., the +.BR ` +and +.BR ' +marks shall not be set if the +.IR ex +command is parsed as specified by rule 6.a. in +.IR "Command Line Parsing in ex". +.P +For rules 5., 6., and 7., the +.BR ` +and +.BR ' +marks shall not be set if the commands are used as motion commands in +open and visual mode. +.P +For rules 1., 2., 3., 4., 5., 6., 7., and 8., the +.BR ` +and +.BR ' +marks shall not be set if the command fails. +.P +The +.BR ` +and +.BR ' +marks shall be set as described previously, each time the contents of +the edit buffer are replaced (including the editing of the initial +buffer), if in open or visual mode, or if in +.BR ex +mode and the edit buffer is not empty, before any commands or movements +(including commands or movements specified by the +.BR \(mic +or +.BR \(mit +options or the +.BR + \c +.IR command +argument) are executed on the edit buffer. If in open or visual mode, +the marks shall be set as if executing the +.IR vi +.BR m +command; otherwise, as if executing the +.IR ex +.BR mark +command. +.P +When changing from +.BR ex +mode to open or visual mode, if the +.BR ` +and +.BR ' +marks are not already set, the +.BR ` +and +.BR ' +marks shall be set as described previously. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Move" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRm\fB[\fRove\fB] \fI1addr\fR \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Move the specified lines after the specified destination line. A +destination of line zero specifies that the lines shall be placed at +the beginning of the edit buffer. It shall be an error if the +destination line is within the range of lines to be moved. +.P +.IR "Current line" : +Set to the last of the moved lines. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Next" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +n\fB[\fRext\fB][\fR!\fB][\fR+\fIcommand\fB][\fIfile \fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error, unless the file is +successfully written as specified by the +.BR autowrite +option. +.br +.P +If one or more files is specified: +.IP " 1." 4 +Set the argument list to the specified filenames. +.IP " 2." 4 +Set the current argument list reference to be the first entry in the +argument list. +.IP " 3." 4 +Set the current pathname to the first filename specified. +.P +Otherwise: +.IP " 1." 4 +It shall be an error if there are no more filenames in the argument +list after the filename currently referenced. +.IP " 2." 4 +Set the current pathname and the current argument list reference to +the filename after the filename currently referenced in the argument +list. +.P +Replace the contents of the edit buffer with the contents of the file +named by the current pathname. If for any reason the contents of the +file cannot be accessed, the edit buffer shall be empty. +.P +This command shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +The +.BR + \c +.IR command +option shall be +-delimited; + +characters can be escaped by preceding them with a + +character. The +.BR + \c +.IR command +shall be interpreted as an +.IR ex +command immediately after the contents of the edit buffer have been +replaced and the current line and column have been set. +.P +.IR "Current line" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Number" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRnu\fB[\fRmber\fB][\fIcount\fB][\fIflags\fB] +[\fI2addr\fB] \fR#\fB[\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +These commands shall be equivalent to the +.IR ex +command: +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB] \fR#\fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.P +See +.IR "Print". +.SS "Open" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRo\fB[\fRpen\fB]\fR /\fIpattern\fR/ \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +This command need not be supported on block-mode terminals or terminals +with insufficient capabilities. If standard input, standard output, or +standard error are not terminal devices, the results are unspecified. +.P +Enter open mode. +.P +The trailing delimiter can be omitted from +.IR pattern +at the end of the command line. If +.IR pattern +is empty (for example, +.BR \(dq//\(dq ) +or not specified, the last regular expression used in the editor shall +be used as the pattern. The pattern can be delimited by + +characters (shown in the Synopsis), as well as any alphanumeric, or non-\c + +other than +, +, +, +or +double-quote. +.P +.IR "Current line" : +Set to the specified line. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Preserve" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +pre\fB[\fRserve\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Save the edit buffer in a form that can later be recovered by using the +.BR \(mir +option or by using the +.IR ex +.BR recover +command. After the file has been preserved, a mail message shall be +sent to the user. This message shall be readable by invoking the +.IR mailx +utility. The message shall contain the name of the file, the time of +preservation, and an +.IR ex +command that could be used to recover the file. Additional information +may be included in the mail message. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Print" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the addressed lines. The behavior is unspecified if the number of +columns on the display is less than the number of columns required to +write any single character in the lines being written. +.P +Non-printable characters, except for the +, +shall be written as implementation-defined multi-character sequences. +.P +If the +.BR # +flag is specified or the +.BR number +edit option is set, each line shall be preceded by its line number in +the following format: +.sp +.RS 4 +.nf +\fB +"%6d ", <\fIline number\fR> +.fi \fR +.P +.RE +.P +If the +.BR l +flag is specified or the +.BR list +edit option is set: +.IP " 1." 4 +The characters listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +shall be written as the corresponding escape sequence. +.IP " 2." 4 +Non-printable characters not in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +shall be written as one three-digit octal number (with a preceding +) +for each byte in the character (most significant byte first). +.IP " 3." 4 +The end of each line shall be marked with a +.BR '$' , +and literal +.BR '$' +characters within the line shall be written with a preceding +. +.P +Long lines shall be folded; the length at which folding occurs is +unspecified, but should be appropriate for the output terminal, +considering the number of columns of the terminal. +.P +If a line is folded, and the +.BR l +flag is not specified and the +.BR list +edit option is not set, it is unspecified whether a multi-column +character at the folding position is separated; it shall not be +discarded. +.P +.IR "Current line" : +Set to the last written line. +.P +.IR "Current column" : +Unchanged if the current line is unchanged; otherwise, set to non-\c +. +.SS "Put" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRpu\fB[\fRt\fB][\fIbuffer\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Append text from the specified buffer (by default, the unnamed buffer) +to the specified line; line zero specifies that the text shall be +placed at the beginning of the edit buffer. Each portion of a line in +the buffer shall become a new line in the edit buffer, regardless of +the mode of the buffer. +.P +.IR "Current line" : +Set to the last line entered into the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Quit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q\fB[\fRuit\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name: +.IP " 1." 4 +If the edit buffer has been modified since the last complete write, it +shall be an error. +.IP " 2." 4 +If there are filenames in the argument list after the filename +currently referenced, and the last command was not a +.BR quit , +.BR wq , +.BR xit , +or +.BR ZZ +(see +.IR "Exit") +command, it shall be an error. +.P +Otherwise, terminate the editing session. +.SS "Read" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRr\fB[\fRead\fB][\fR!\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.BR '!' +is not the first non-\c + +to follow the command name, a copy of the specified file shall be +appended into the edit buffer after the specified line; line zero +specifies that the copy shall be placed at the beginning of the edit +buffer. The number of lines and bytes read shall be written. If no +.IR file +is named, the current pathname shall be the default. If there is no +current pathname, then +.IR file +shall become the current pathname. If there is no current pathname or +.IR file +operand, it shall be an error. Specifying a +.IR file +that is not of type regular shall have unspecified results. +.P +Otherwise, if +.IR file +is preceded by +.BR '!' , +the rest of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +.P +The +.IR ex +utility shall then pass two arguments to the program named by the +shell edit option; the first shall be +.BR \(mic +and the second shall be the expanded arguments to the +.BR read +command as a single argument. The standard input of the program shall +be set to the standard input of the +.IR ex +program when it was invoked. The standard error and standard output of +the program shall be appended into the edit buffer after the specified +line. +.P +Each line in the copied file or program output (as delimited by + +characters or the end of the file or output if it is not immediately +preceded by a +), +shall be a separate line in the edit buffer. Any occurrences of + +and + +pairs in the output shall be treated as single + +characters. +.P +The special meaning of the +.BR '!' +following the +.BR read +command can be overridden by escaping it with a + +character. +.P +.IR "Current line" : +If no lines are added to the edit buffer, unchanged. Otherwise, if in +open or visual mode, set to the first line entered into the edit +buffer. Otherwise, set to the last line entered into the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Recover" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +rec\fB[\fRover\fB][\fR!\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error. +.P +If no +.IR file +operand is specified, then the current pathname shall be used. If +there is no current pathname or +.IR file +operand, it shall be an error. +.P +If no recovery information has previously been saved about +.IR file , +the +.BR recover +command shall behave identically to the +.BR edit +command, and an informational message to this effect shall be written. +.P +Otherwise, set the current pathname to +.IR file , +and replace the current contents of the edit buffer with the recovered +contents of +.IR file . +If there are multiple instances of the file to be recovered, the one +most recently saved shall be recovered, and an informational message +that there are previous versions of the file that can be recovered +shall be written. The editor shall behave as if the contents of the +edit buffer have already been modified. +.P +.IR "Current file" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Rewind" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +rew\fB[\fRind\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error, unless the file is +successfully written as specified by the +.BR autowrite +option. +.P +If the argument list is empty, it shall be an error. +.P +The current argument list reference and the current pathname shall be +set to the first filename in the argument list. +.P +Replace the contents of the edit buffer with the contents of the file +named by the current pathname. If for any reason the contents of the +file cannot be accessed, the edit buffer shall be empty. +.P +This command shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +.IR "Current line" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Set" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +se\fB[\fRt\fB][\fIoption\fB[\fR=\fB[\fIvalue\fB]]\fR ...\fB][\fRno\fIoption\fR ...\fB][\fIoption\fR? ...\fB][\fRall\fB]\fR +.fi \fR +.P +.RE +.RE +.P +When no arguments are specified, write the value of the +.BR term +edit option and those options whose values have been changed from the +default settings; when the argument +.IR all +is specified, write all of the option values. +.P +Giving an option name followed by the character +.BR '?' +shall cause the current value of that option to be written. The +.BR '?' +can be separated from the option name by zero or more + +characters. The +.BR '?' +shall be necessary only for Boolean valued options. Boolean options can +be given values by the form +.BR set +.IR option +to turn them on or +.BR set +.BR no \c +.IR option +to turn them off; string and numeric options can be assigned by the +form +.BR set +.IR option =\c +.IR value . +Any + +characters in strings can be included as is by preceding each + +with an escaping +. +More than one option can be set or listed by a single set command by +specifying multiple arguments, each separated from the next by one or more + +characters. +.P +See +.IR "Edit Options in ex" +for details about specific options. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Shell" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +sh\fB[\fRell\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Invoke the program named in the +.BR shell +edit option with the single argument +.BR \(mii +(interactive mode). Editing shall be resumed when the program exits. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Source" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +so\fB[\fRurce\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +Read and execute +.IR ex +commands from +.IR file . +Lines in the file that are blank lines shall be ignored. +.P +.IR "Current line" : +As specified for the individual +.IR ex +commands. +.P +.IR "Current column" : +As specified for the individual +.IR ex +commands. +.SS "Substitute" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRs\fB[\fRubstitute\fB][\fR/\fIpattern\fR/\fIrepl\fR/\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.br +\fB[\fI2addr\fB] \fR&\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.br +\fB[\fI2addr\fB] \fR~\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.fi \fR +.P +.RE +.RE +.P +Replace the first instance of the pattern +.IR pattern +by the string +.IR repl +on each specified line. (See +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex".) +Any non-alphabetic, non-\c + +delimiter other than +, +.BR '|' , +, +or double-quote +can be used instead of +.BR '/' . + +characters can be used to escape delimiters, + +characters, and other special characters. +.P +The trailing delimiter can be omitted from +.IR pattern +or from +.IR repl +at the end of the command line. If both +.IR pattern +and +.IR repl +are not specified or are empty (for example, +.BR \(dq//\(dq ), +the last +.BR s +command shall be repeated. If only +.IR pattern +is not specified or is empty, the last regular expression used in the +editor shall be used as the pattern. If only +.IR repl +is not specified or is empty, the pattern shall be replaced by nothing. +If the entire replacement pattern is +.BR '%' , +the last replacement pattern to an +.BR s +command shall be used. +.P +Entering a + +in +.IR repl +(which requires an escaping + +in +.IR ex +mode and an escaping +\(hyV +in open or +.IR vi +mode) shall split the line at that point, creating a new line in the +edit buffer. The + +shall be discarded. +.P +If +.IR options +includes the letter +.BR 'g' +(\c +.BR global ), +all non-overlapping instances of the pattern in the line shall be +replaced. +.P +If +.IR options +includes the letter +.BR 'c' +(\c +.BR confirm ), +then before each substitution the line shall be written; the written +line shall reflect all previous substitutions. On the following line, + +characters shall be written beneath the characters from the line that +are before the +.IR pattern +to be replaced, and +.BR '^' +characters written beneath the characters included in the +.IR pattern +to be replaced. The +.IR ex +utility shall then wait for a response from the user. An affirmative +response shall cause the substitution to be done, while any other input +shall not make the substitution. An affirmative response shall consist +of a line with the affirmative response (as defined by the current +locale) at the beginning of the line. This line shall be subject to +editing in the same way as the +.IR ex +command line. +.P +If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications +confirmed by the user shall be preserved in the edit buffer after the +interrupt. +.P +If the remembered search direction is not set, the +.BR s +command shall set it to forward. +.P +In the second Synopsis, the +.BR & +command shall repeat the previous substitution, as if the +.BR & +command were replaced by: +.sp +.RS 4 +.nf +\fB +s/\fIpattern\fR/\fIrepl\fR/ +.fi \fR +.P +.RE +.P +where +.IR pattern +and +.IR repl +are as specified in the previous +.BR s , +.BR & , +or +.BR ~ +command. +.P +In the third Synopsis, the +.BR ~ +command shall repeat the previous substitution, as if the +.BR '~' +were replaced by: +.sp +.RS 4 +.nf +\fB +s/\fIpattern\fR/\fIrepl\fR/ +.fi \fR +.P +.RE +.P +where +.IR pattern +shall be the last regular expression specified to the editor, and +.IR repl +shall be from the previous substitution (including +.BR & +and +.BR ~ ) +command. +.P +These commands shall be affected by the +.IR LC_MESSAGES +environment variable. +.P +.IR "Current line" : +Set to the last line in which a substitution occurred, or, unchanged if +no substitution occurred. +.P +.IR "Current column": +Set to non-\c +. +.SS "Suspend" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +su\fB[\fRspend\fB][\fR!\fB]\fR +st\fB[\fRop\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Allow control to return to the invoking process; +.IR ex +shall suspend itself as if it had received the SIGTSTP signal. The +suspension shall occur only if job control is enabled in the invoking +shell (see the description of +.IR set +.BR \(mim ). +.P +These commands shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +The current +.BR susp +character (see +.IR "\fIstty\fR\^") +shall be equivalent to the +.BR suspend +command. +.SS "Tag" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ta\fB[\fRg\fB][\fR!\fB] \fItagstring\fR +.fi \fR +.P +.RE +.RE +.P +The results are unspecified if the format of a tags file is not as +specified by the +.IR ctags +utility (see +.IR "\fIctags\fR\^") +description. +.P +The +.BR tag +command shall search for +.IR tagstring +in the tag files referred to by the +.BR tag +edit option, in the order they are specified, until a reference to +.IR tagstring +is found. Files shall be searched from beginning to end. If no +reference is found, it shall be an error and an error message to this +effect shall be written. If the reference is not found, or if an error +occurs while processing a file referred to in the +.BR tag +edit option, it shall be an error, and an error message shall be +written at the first occurrence of such an error. +.P +Otherwise, if the tags file contained a pattern, the pattern shall be +treated as a regular expression used in the editor; for example, for +the purposes of the +.BR s +command. +.P +If the +.IR tagstring +is in a file with a different name than the current pathname, set the +current pathname to the name of that file, and replace the contents of +the edit buffer with the contents of that file. In this case, if no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error, unless the file is +successfully written as specified by the +.BR autowrite +option. +.P +This command shall be affected by the +.BR autowrite , +.BR tag , +.BR taglength , +and +.BR writeany +edit options. +.P +.IR "Current line" : +If the tags file contained a line number, set to that line number. If +the line number is larger than the last line in the edit buffer, an +error message shall be written and the current line shall be set as +specified for the +.BR edit +command. +.P +If the tags file contained a pattern, set to the first occurrence of +the pattern in the file. If no matching pattern is found, an error +message shall be written and the current line shall be set as specified +for the +.BR edit +command. +.P +.IR "Current column" : +If the tags file contained a line-number reference and that line-number +was not larger than the last line in the edit buffer, or if the tags +file contained a pattern and that pattern was found, set to non-\c +. +Otherwise, set as specified for the +.BR edit +command. +.SS "Unabbreviate" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +una\fB[\fRbbrev\fB] \fIlhs\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +is not an entry in the current list of abbreviations (see +.IR "Abbreviate"), +it shall be an error. Otherwise, delete +.IR lhs +from the list of abbreviations. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Undo" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u\fB[\fRndo\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Reverse the changes made by the last command that modified the contents +of the edit buffer, including +.BR undo . +For this purpose, the +.BR global , +.BR v , +.BR open , +and +.BR visual +commands, and commands resulting from buffer executions and mapped +character expansions, are considered single commands. +.P +If no action that can be undone preceded the +.BR undo +command, it shall be an error. +.P +If the +.BR undo +command restores lines that were marked, the mark shall also be +restored unless it was reset subsequent to the deletion of the lines. +.P +.IR "Current line" : +.IP " 1." 4 +If lines are added or changed in the file, set to the first line added +or changed. +.IP " 2." 4 +Set to the line before the first line deleted, if it exists. +.IP " 3." 4 +Set to 1 if the edit buffer is not empty. +.IP " 4." 4 +Set to zero. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Unmap" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +unm\fB[\fRap\fB][\fR!\fB] \fIlhs\fR +.fi \fR +.P +.RE +.RE +.P +If +.BR '!' +is appended to the command name, and if +.IR lhs +is not an entry in the list of text input mode map definitions, it +shall be an error. Otherwise, delete +.IR lhs +from the list of text input mode map definitions. +.P +If no +.BR '!' +is appended to the command name, and if +.IR lhs +is not an entry in the list of command mode map definitions, it shall +be an error. Otherwise, delete +.IR lhs +from the list of command mode map definitions. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Version" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ve\fB[\fRrsion\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write a message containing version information for the editor. The +format of the message is unspecified. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Visual" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRvi\fB[\fRsual\fB][\fItype\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR ex +is currently in open or visual mode, the Synopsis and behavior of the +visual command shall be the same as the +.BR edit +command, as specified by +.IR "Edit". +.P +Otherwise, this command need not be supported on block-mode terminals +or terminals with insufficient capabilities. If standard input, +standard output, or standard error are not terminal devices, the +results are unspecified. +.P +If +.IR count +is specified, the value of the +.BR window +edit option shall be set to +.IR count +(as described in +.IR "window"). +If the +.BR '^' +type character was also specified, the +.BR window +edit option shall be set before being used by the type character. +.P +Enter visual mode. If +.IR type +is not specified, it shall be as if a +.IR type +of +.BR '\(pl' +was specified. The +.IR type +shall cause the following effects: +.IP "\fR+\fP" 6 +Place the beginning of the specified line at the top of the display. +.IP "\fR-\fP" 6 +Place the end of the specified line at the bottom of the display. +.IP "\fR.\fP" 6 +Place the beginning of the specified line in the middle of the display. +.IP "\fR^\fP" 6 +If the specified line is less than or equal to the value of the +.BR window +edit option, set the line to 1; otherwise, decrement the line by the +value of the +.BR window +edit option minus 1. Place the beginning of this line as close to the +bottom of the displayed lines as possible, while still displaying the +value of the +.BR window +edit option number of lines. +.P +.IR "Current line" : +Set to the specified line. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Write" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRw\fB[\fRrite\fB][\fR!\fB][\fR>>\fB][\fIfile\fB] +[\fI2addr\fB] \fRw\fB[\fRrite\fB][\fR!\fB][\fIfile\fB] +[\fI2addr\fB] \fRwq\fB[\fR!\fB][\fR>>\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no lines are specified, the lines shall default to the entire file. +.P +The command +.BR wq +shall be equivalent to a +.BR write +command followed by a +.BR quit +command; +.BR wq! +shall be equivalent to +.BR write! +followed by +.BR quit . +In both cases, if the +.BR write +command fails, the +.BR quit +shall not be attempted. +.P +If the command name is not followed by one or more + +characters, or +.IR file +is not preceded by a +.BR '!' +character, the +.BR write +shall be to a file. +.IP " 1." 4 +If the +.BR >> +argument is specified, and the file already exists, the lines shall be +appended to the file instead of replacing its contents. If the +.BR >> +argument is specified, and the file does not already exist, it is +unspecified whether the write shall proceed as if the +.BR >> +argument had not been specified or if the write shall fail. +.IP " 2." 4 +If the +.BR readonly +edit option is set (see +.IR "readonly"), +the +.BR write +shall fail. +.IP " 3." 4 +If +.IR file +is specified, and is not the current pathname, and the file exists, +the +.BR write +shall fail. +.IP " 4." 4 +If +.IR file +is not specified, the current pathname shall be used. If there is no +current pathname, the +.BR write +command shall fail. +.IP " 5." 4 +If the current pathname is used, and the current pathname has been +changed by the +.BR file +or +.BR read +commands, and the file exists, the +.BR write +shall fail. If the +.BR write +is successful, subsequent +.BR write s +shall not fail for this reason (unless the current pathname is changed +again). +.IP " 6." 4 +If the whole edit buffer is not being written, and the file to be +written exists, the +.BR write +shall fail. +.P +For rules 1., 2., 3., and 5., the +.BR write +can be forced by appending the character +.BR '!' +to the command name. +.P +For rules 2., 3., and 5., the +.BR write +can be forced by setting the +.BR writeany +edit option. +.P +Additional, implementation-defined tests may cause the +.BR write +to fail. +.P +If the edit buffer is empty, a file without any contents shall be written. +.P +An informational message shall be written noting the number of lines +and bytes written. +.P +Otherwise, if the command is followed by one or more + +characters, and the file is preceded by +.BR '!' , +the rest of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +.P +The +.IR ex +utility shall then pass two arguments to the program named by the +.BR shell +edit option; the first shall be +.BR \(mic +and the second shall be the expanded arguments to the +.BR write +command as a single argument. The specified lines shall be written to +the standard input of the command. The standard error and standard +output of the program, if any, shall be written as described for the +.BR print +command. If the last character in that output is not a +, +a + +shall be written at the end of the output. +.P +The special meaning of the +.BR '!' +following the +.BR write +command can be overridden by escaping it with a + +character. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Write and Exit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRx\fB[\fRit\fB][\fR!\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If the edit buffer has not been modified since the last complete +.BR write , +.BR xit +shall be equivalent to the +.BR quit +command, or if a +.BR '!' +is appended to the command name, to +.BR quit! . +.P +Otherwise, +.BR xit +shall be equivalent to the +.BR wq +command, or if a +.BR '!' +is appended to the command name, to +.BR wq! . +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Yank" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRya\fB[\fRnk\fB][\fIbuffer\fB][\fIcount\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Copy the specified lines to the specified buffer (by default, the +unnamed buffer), which shall become a line-mode buffer. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Adjust Window" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRz\fB[\fR!\fB][\fItype \fR...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no line is specified, the current line shall be the default; if +.IR type +is omitted as well, the current line value shall first be incremented +by 1. If incrementing the current line would cause it to be greater +than the last line in the edit buffer, it shall be an error. +.P +If there are + +characters between the +.IR type +argument and the preceding +.BR z +command name or optional +.BR '!' +character, it shall be an error. +.P +If +.IR count +is specified, the value of the +.BR window +edit option shall be set to +.IR count +(as described in +.IR "window"). +If +.IR count +is omitted, it shall default to 2 times the value of the +.BR scroll +edit option, or if +.BR ! +was specified, the number of lines in the display minus 1. +.P +If +.IR type +is omitted, then +.IR count +lines starting with the specified line shall be written. Otherwise, +.IR count +lines starting with the line specified by the +.IR type +argument shall be written. +.P +The +.IR type +argument shall change the lines to be written. The possible values of +.IR type +are as follows: +.IP "\fR\(mi\fP" 6 +The specified line shall be decremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``\(mi'' characters) x \fIcount\fR) \(mi1) +.fi \fR +.P +.RE +.P +If the calculation would result in a number less than 1, it shall be an +error. Write lines from the edit buffer, starting at the new value of +line, until +.IR count +lines or the last line in the edit buffer has been written. +.RE +.IP "\fR+\fP" 6 +The specified line shall be incremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``+'' characters) \(mi1) x \fIcount\fR) +1 +.fi \fR +.P +.RE +.P +If the calculation would result in a number greater than the last line +in the edit buffer, it shall be an error. Write lines from the edit +buffer, starting at the new value of line, until +.IR count +lines or the last line in the edit buffer has been written. +.RE +.IP "\fR=\fR,\fR.\fR" 6 +If more than a single +.BR '.' +or +.BR '=' +is specified, it shall be an error. The following steps shall be +taken: +.RS 6 +.IP " 1." 4 +If +.IR count +is zero, nothing shall be written. +.IP " 2." 4 +Write as many of the +.IR N +lines before the current line in the edit buffer as exist. If +.IR count +or +.BR '!' +was specified, +.IR N +shall be: +.RS 4 +.sp +.RS 4 +.nf +\fB +(\fIcount\fR \(mi1) /2 +.fi \fR +.P +.RE +.P +Otherwise, +.IR N +shall be: +.sp +.RS 4 +.nf +\fB +(\fIcount\fP \(mi3) /2 +.fi \fR +.P +.RE +.P +If +.IR N +is a number less than 3, no lines shall be written. +.RE +.IP " 3." 4 +If +.BR '=' +was specified as the type character, write a line consisting of the +smaller of the number of columns in the display divided by two, or 40 +.BR '\(mi' +characters. +.IP " 4." 4 +Write the current line. +.IP " 5." 4 +Repeat step 3. +.IP " 6." 4 +Write as many of the +.IR N +lines after the current line in the edit buffer as exist. +.IR N +shall be defined as in step 2. If +.IR N +is a number less than 3, no lines shall be written. If +.IR count +is less than 3, no lines shall be written. +.RE +.IP "\fR^\fP" 6 +The specified line shall be decremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``^'' characters) +1) x \fIcount\fR) \(mi1 +.fi \fR +.P +.RE +.P +If the calculation would result in a number less than 1, it shall be an +error. Write lines from the edit buffer, starting at the new value of +line, until +.IR count +lines or the last line in the edit buffer has been written. +.RE +.P +.IR "Current line" : +Set to the last line written, unless the type is +.BR = , +in which case, set to the specified line. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Escape" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +! \fIcommand +\fB[\fIaddr\fB]\fR! \fIcommand\fR +.fi \fR +.P +.RE +.RE +.P +The contents of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +If the expansion causes the text of the line to change, it shall be +redisplayed, preceded by a single +.BR '!' +character. +.P +The +.IR ex +utility shall execute the program named by the +.BR shell +edit option. It shall pass two arguments to the program; the first +shall be +.BR \(mic , +and the second shall be the expanded arguments to the +.BR ! +command as a single argument. +.P +If no lines are specified, the standard input, standard output, and +standard error of the program shall be set to the standard input, +standard output, and standard error of the +.IR ex +program when it was invoked. In addition, a warning message shall be +written if the edit buffer has been modified since the last complete +write, and the +.BR warn +edit option is set. +.P +If lines are specified, they shall be passed to the program as standard +input, and the standard output and standard error of the program shall +replace those lines in the edit buffer. Each line in the program output +(as delimited by + +characters or the end of the output if it is not immediately preceded by a +), +shall be a separate line in the edit buffer. Any occurrences of + +and + +pairs in the output shall be treated as single + +characters. The specified lines shall be copied into the unnamed buffer +before they are replaced, and the unnamed buffer shall become a line-mode +buffer. +.P +If in +.IR ex +mode, a single +.BR '!' +character shall be written when the program completes. +.P +This command shall be affected by the +.BR shell +and +.BR warn +edit options. If no lines are specified, this command shall be affected +by the +.BR autowrite +and +.BR writeany +edit options. If lines are specified, this command shall be affected by +the +.BR autoprint +edit option. +.br +.P +.IR "Current line" : +.IP " 1." 4 +If no lines are specified, unchanged. +.IP " 2." 4 +Otherwise, set to the last line read in, if any lines are read in. +.IP " 3." 4 +Otherwise, set to the line before the first line of the lines +specified, if that line exists. +.IP " 4." 4 +Otherwise, set to the first line of the edit buffer if the edit buffer +is not empty. +.IP " 5." 4 +Otherwise, set to zero. +.P +.IR "Current column" : +If no lines are specified, unchanged. Otherwise, set to non-\c +. +.SS "Shift Left" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR <\fB[\fR< ...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Shift the specified lines to the start of the line; the number of +column positions to be shifted shall be the number of command +characters times the value of the +.BR shiftwidth +edit option. Only leading + +characters shall be deleted or changed into other + +characters in shifting; other characters shall not be affected. +.P +Lines to be shifted shall be copied into the unnamed buffer, which +shall become a line-mode buffer. +.P +This command shall be affected by the +.BR autoprint +edit option. +.P +.IR "Current line" : +Set to the last line in the lines specified. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Shift Right" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR >\fB[\fR> ...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Shift the specified lines away from the start of the line; the number +of column positions to be shifted shall be the number of command +characters times the value of the +.BR shiftwidth +edit option. The shift shall be accomplished by adding + +characters as a prefix to the line or changing leading + +characters into other + +characters. Empty lines shall not be changed. +.P +Lines to be shifted shall be copied into the unnamed buffer, which +shall become a line-mode buffer. +.P +This command shall be affected by the +.BR autoprint +edit option. +.P +.IR "Current line" : +Set to the last line in the lines specified. +.P +.IR "Current column" : +Set to non-\c +. +.SS "\(hyD" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-D +.fi \fR +.P +.RE +.RE +.P +Write the next +.IR n +lines, where +.IR n +is the minimum of the values of the +.BR scroll +edit option and the number of lines after the current line in the edit +buffer. If the current line is the last line of the edit buffer it +shall be an error. +.P +.IR "Current line" : +Set to the last line written. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Write Line Number" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fR= \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR line +is not specified, it shall default to the last line in the edit buffer. +Write the line number of the specified line. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Execute" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR @ \fIbuffer\fR +\fB[\fI2addr\fB]\fR * \fIbuffer\fR +.fi \fR +.P +.RE +.RE +.P +If no buffer is specified or is specified as +.BR '@' +or +.BR '*' , +the last buffer executed shall be used. If no previous buffer has been +executed, it shall be an error. +.P +For each line specified by the addresses, set the current line (\c +.BR '.' ) +to the specified line, and execute the contents of the named +.IR buffer +(as they were at the time the +.BR @ +command was executed) as +.IR ex +commands. For each line of a line-mode buffer, and all but the last +line of a character-mode buffer, the +.IR ex +command parser shall behave as if the line was terminated by a +. +.P +If an error occurs during this process, or a line specified by the +addresses does not exist when the current line would be set to it, or +more than a single line was specified by the addresses, and the +contents of the edit buffer are replaced (for example, by the +.IR ex +.BR :edit +command) an error message shall be written, and no more commands +resulting from the execution of this command shall be processed. +.P +.IR "Current line" : +As specified for the individual +.IR ex +commands. +.P +.IR "Current column" : +As specified for the individual +.IR ex +commands. +.SS "Regular Expressions in ex" +.P +The +.IR ex +utility shall support regular expressions that are a superset of the +basic regular expressions described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +A null regular expression (\c +.BR \(dq//\(dq ) +shall be equivalent to the last regular expression encountered. +.P +Regular expressions can be used in addresses to specify lines and, in +some commands (for example, the +.BR substitute +command), to specify portions of a line to be substituted. +.P +The following constructs can be used to enhance the basic regular +expressions: +.IP "\fR\e<\fR" 6 +Match the beginning of a +.IR word . +(See the definition of +.IR word +at the beginning of +.IR "Command Descriptions in ex".) +.IP "\fR\e>\fR" 6 +Match the end of a +.IR word . +.IP "\fR~\fR" 6 +Match the replacement part of the last +.BR substitute +command. The + +(\c +.BR '~' ) +character can be escaped in a regular expression to become a normal +character with no special meaning. The + +shall be discarded. +.P +When the editor option +.BR magic +is not set, the only characters with special meanings shall be +.BR '^' +at the beginning of a pattern, +.BR '$' +at the end of a pattern, and +. +The characters +.BR '.' , +.BR '*' , +.BR '[' , +and +.BR '~' +shall be treated as ordinary characters unless preceded by a +; +when preceded by a + +they shall regain their special meaning, or in the case of +, +be handled as a single +. + +characters used to escape other characters shall be discarded. +.SS "Replacement Strings in ex" +.P +The character +.BR '&' +(\c +.BR '\e&' +if the editor option +.BR magic +is not set) in the replacement string shall stand for the text matched +by the pattern to be replaced. The character +.BR '~' +(\c +.BR '\e~' +if +.BR magic +is not set) shall be replaced by the replacement part of the previous +.BR substitute +command. The sequence +.BR '\en' , +where +.IR n +is an integer, shall be replaced by the text matched by the +corresponding back-reference expression. If the corresponding +back-reference expression does not match, then the characters +.BR '\en' +shall be replaced by the empty string. +.P +The strings +.BR '\el' , +.BR '\eu' , +.BR '\eL' , +and +.BR '\eU' +can be used to modify the case of elements in the replacement string +(using the +.BR '\e&' +or +.BR \(dq\e\(dq digit) +notation. The string +.BR '\el' +(\c +.BR '\eu' ) +shall cause the character that follows to be converted to lowercase +(uppercase). The string +.BR '\eL' +(\c +.BR '\eU' ) +shall cause all characters subsequent to it to be converted to +lowercase (uppercase) as they are inserted by the substitution until +the string +.BR '\ee' +or +.BR '\eE' , +or the end of the replacement string, is encountered. +.P +Otherwise, any character following a + +shall be treated as that literal character, and the escaping + +shall be discarded. +.P +An example of case conversion with the +.BR s +command is as follows: +.sp +.RS 4 +.nf +\fB +\fB:\fRp +\fBThe cat sat on the mat. +\fB:\fRs/\e<.at\e>/\eu&/gp +\fBThe Cat Sat on the Mat. +\fB:\fRs/S\e(.*\e)M/S\eU\e1\eeM/p +\fBThe Cat SAT ON THE Mat.\fR +.fi \fR +.P +.RE +.SS "Edit Options in ex" +.P +The +.IR ex +utility has a number of options that modify its behavior. These options +have default settings, which can be changed using the +.BR set +command. +.P +Options are Boolean unless otherwise specified. +.SS "autoindent, ai" +.P +[Default \fIunset\fR] +.P +If +.BR autoindent +is set, each line in input mode shall be indented (using first as many + +characters as possible, as determined by the editor option +.BR tabstop , +and then using + +characters) to align with another line, as follows: +.IP " 1." 4 +If in open or visual mode and the text input is part of a line-oriented +command (see the EXTENDED DESCRIPTION in +.IR "\fIvi\fR\^"), +align to the first column. +.IP " 2." 4 +Otherwise, if in open or visual mode, indentation for each line shall +be set as follows: +.RS 4 +.IP " a." 4 +If a line was previously inserted as part of this command, it shall be +set to the indentation of the last inserted line by default, or as +otherwise specified for the +\(hyD +character in +.IR "Input Mode Commands in vi". +.IP " b." 4 +Otherwise, it shall be set to the indentation of the previous current +line, if any; otherwise, to the first column. +.RE +.IP " 3." 4 +For the +.IR ex +.BR a , +.BR i , +and +.BR c +commands, indentation for each line shall be set as follows: +.RS 4 +.IP " a." 4 +If a line was previously inserted as part of this command, it shall be +set to the indentation of the last inserted line by default, or as +otherwise specified for the +.IR eof +character in +.IR "Scroll". +.IP " b." 4 +Otherwise, if the command is the +.IR ex +.BR a +command, it shall be set to the line appended after, if any; otherwise +to the first column. +.IP " c." 4 +Otherwise, if the command is the +.IR ex +.BR i +command, it shall be set to the line inserted before, if any; otherwise +to the first column. +.IP " d." 4 +Otherwise, if the command is the +.IR ex +.BR c +command, it shall be set to the indentation of the line replaced. +.RE +.SS "autoprint, ap" +.P +[Default \fIset\fR] +.P +If +.BR autoprint +is set, the current line shall be written after each +.IR ex +command that modifies the contents of the current edit buffer, and +after each +.BR tag +command for which the tag search pattern was found or tag line number +was valid, unless: +.IP " 1." 4 +The command was executed while in open or visual mode. +.IP " 2." 4 +The command was executed as part of a +.BR global +or +.BR v +command or +.BR @ +buffer execution. +.IP " 3." 4 +The command was the form of the +.BR read +command that reads a file into the edit buffer. +.IP " 4." 4 +The command was the +.BR append , +.BR change , +or +.BR insert +command. +.IP " 5." 4 +The command was not terminated by a +. +.IP " 6." 4 +The current line shall be written by a flag specified to the command; +for example, +.BR "delete #" +shall write the current line as specified for the flag modifier to the +.BR delete +command, and not as specified by the +.BR autoprint +edit option. +.SS "autowrite, aw" +.P +[Default \fIunset\fR] +.P +If +.BR autowrite +is set, and the edit buffer has been modified since it was last +completely written to any file, the contents of the edit buffer shall +be written as if the +.IR ex +.BR write +command had been specified without arguments, before each command +affected by the +.BR autowrite +edit option is executed. Appending the character +.BR '!' +to the command name of any of the +.IR ex +commands except +.BR '!' +shall prevent the write. If the write fails, it shall be an error and +the command shall not be executed. +.SS "beautify, bf" +.P +[Default \fIunset\fR] +.P +If +.BR beautify +is set, all non-printable characters, other than +, +, +and + +characters, shall be discarded from text read in from files. +.SS "directory, dir" +.P +[Default \fIimplementation-defined\fR] +.P +The value of this option specifies the directory in which the editor +buffer is to be placed. If this directory is not writable by the user, +the editor shall quit. +.SS "edcompatible, ed" +.P +[Default \fIunset\fR] +.P +Causes the presence of +.BR g +and +.BR c +suffixes on substitute commands to be remembered, and toggled by +repeating the suffixes. +.SS "errorbells, eb" +.P +[Default \fIunset\fR] +.P +If the editor is in +.IR ex +mode, and the terminal does not support a standout mode (such as +inverse video), and +.BR errorbells +is set, error messages shall be preceded by alerting the terminal. +.SS "exrc" +.P +[Default \fIunset\fR] +.P +If +.BR exrc +is set, +.IR ex +shall access any +.BR .exrc +file in the current directory, as described in +.IR "Initialization in ex and vi". +If +.BR exrc +is not set, +.IR ex +shall ignore any +.BR .exrc +file in the current directory during initialization, unless the current +directory is that named by the +.IR HOME +environment variable. +.SS "ignorecase, ic" +.P +[Default \fIunset\fR] +.P +If +.BR ignorecase +is set, characters that have uppercase and lowercase representations +shall have those representations considered as equivalent for purposes +of regular expression comparison. +.P +The +.BR ignorecase +edit option shall affect all remembered regular expressions; for +example, unsetting the +.BR ignorecase +edit option shall cause a subsequent +.IR vi +.BR n +command to search for the last basic regular expression in a +case-sensitive fashion. +.SS "list" +.P +[Default \fIunset\fR] +.P +If +.BR list +is set, edit buffer lines written while in +.IR ex +command mode shall be written as specified for the +.BR print +command with the +.BR l +flag specified. In open or visual mode, each edit buffer line shall be +displayed as specified for the +.IR ex +.BR print +command with the +.BR l +flag specified. In open or visual text input mode, when the cursor +does not rest on any character in the line, it shall rest on the +.BR '$' +marking the end of the line. +.SS "magic" +.P +[Default \fIset\fR] +.P +If +.BR magic +is set, modify the interpretation of characters in regular expressions +and substitution replacement strings (see +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex"). +.SS "mesg" +.P +[Default \fIset\fR] +.P +If +.BR mesg +is set, the permission for others to use the +.BR write +or +.BR talk +commands to write to the terminal shall be turned on while in open or +visual mode. The shell-level command +.IR mesg +.BR n +shall take precedence over any setting of the +.IR ex +.BR mesg +option; that is, if +.BR "mesg y" +was issued before the editor started (or in a shell escape), such as: +.sp +.RS 4 +.nf +\fB +:!mesg y +.fi \fR +.P +.RE +.P +the +.BR mesg +option in +.IR ex +shall suppress incoming messages, but the +.BR mesg +option shall not enable incoming messages if +.BR "mesg n" +was issued. +.SS "number, nu" +.P +[Default \fIunset\fR] +.P +If +.BR number +is set, edit buffer lines written while in +.IR ex +command mode shall be written with line numbers, in the format +specified by the +.BR print +command with the +.BR # +flag specified. In +.IR ex +text input mode, each line shall be preceded by the line number it will +have in the file. +.P +In open or visual mode, each edit buffer line shall be displayed with a +preceding line number, in the format specified by the +.IR ex +.BR print +command with the +.BR # +flag specified. This line number shall not be considered part of the +line for the purposes of evaluating the current column; that is, column +position 1 shall be the first column position after the format +specified by the +.BR print +command. +.SS "paragraphs, para" +.P +[Default in the POSIX locale \fRIPLPPPQPP LIpplpipbp\fR] +.P +The +.BR paragraphs +edit option shall define additional paragraph boundaries for the open +and visual mode commands. The +.BR paragraphs +edit option can be set to a character string consisting of zero or more +character pairs. It shall be an error to set it to an odd number of +characters. +.SS "prompt" +.P +[Default \fIset\fR] +.P +If +.BR prompt +is set, +.IR ex +command mode input shall be prompted for with a + +(\c +.BR ':' ); +when unset, no prompt shall be written. +.SS "readonly" +.P +[Default \fIsee text\fR] +.P +If the +.BR readonly +edit option is set, read-only mode shall be enabled (see +.IR "Write"). +The +.BR readonly +edit option shall be initialized to set if either of the following +conditions are true: +.IP " *" 4 +The command-line option +\(miR +was specified. +.IP " *" 4 +Performing actions equivalent to the +\fIaccess\fR() +function called with the following arguments indicates that the file +lacks write permission: +.RS 4 +.IP " 1." 4 +The current pathname is used as the +.IR path +argument. +.IP " 2." 4 +The constant +.BR W_OK +is used as the +.IR amode +argument. +.RE +.P +The +.BR readonly +edit option may be initialized to set for other, +implementation-defined reasons. The +.BR readonly +edit option shall not be initialized to unset based on any special +privileges of the user or process. The +.BR readonly +edit option shall be reinitialized each time that the contents of the +edit buffer are replaced (for example, by an +.BR edit +or +.BR next +command) unless the user has explicitly set it, in which case it shall +remain set until the user explicitly unsets it. Once unset, it shall +again be reinitialized each time that the contents of the edit buffer +are replaced. +.SS "redraw" +.P +[Default \fIunset\fR] +.P +The editor simulates an intelligent terminal on a dumb terminal. +(Since this is likely to require a large amount of output to the +terminal, it is useful only at high transmission speeds.) +.SS "remap" +.P +[Default \fIset\fR] +.P +If +.BR remap +is set, map translation shall allow for maps defined in terms of other +maps; translation shall continue until a final product is obtained. If +unset, only a one-step translation shall be done. +.SS "report" +.P +[Default 5] +.P +The value of this +.BR report +edit option specifies what number of lines being added, copied, +deleted, or modified in the edit buffer will cause an informational +message to be written to the user. The following conditions shall cause +an informational message. The message shall contain the number of lines +added, copied, deleted, or modified, but is otherwise unspecified. +.IP " *" 4 +An +.IR ex +or +.IR vi +editor command, other than +.BR open , +.BR undo , +or +.BR visual , +that modifies at least the value of the +.BR report +edit option number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +.IP " *" 4 +An +.IR ex +.BR yank +or +.IR vi +.BR y +or +.BR Y +command, that copies at least the value of the +.BR report +edit option plus 1 number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +.IP " *" 4 +An +.IR ex +.BR global , +.BR v , +.BR open , +.BR undo , +or +.BR visual +command or +.IR ex +or +.IR vi +buffer execution, that adds or deletes a total of at least the value of +the +.BR report +edit option number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +(For example, if 3 lines were added and 8 lines deleted during an +.IR ex +.BR visual +command, 5 would be the number compared against the +.BR report +edit option after the command completed.) +.SS "scroll, scr" +.P +[Default (number of lines in the display \(mi1)/2] +.P +The value of the +.BR scroll +edit option shall determine the number of lines scrolled by the +.IR ex +\(hyD +and +.BR z +commands. For the +.IR vi +\(hyD +and +\(hyU +commands, it shall be the initial number of lines to scroll when no +previous +\(hyD +or +\(hyU +command has been executed. +.SS "sections" +.P +[Default in the POSIX locale \fRNHSHH HUnhsh\fR] +.P +The +.BR sections +edit option shall define additional section boundaries for the open and +visual mode commands. The +.BR sections +edit option can be set to a character string consisting of zero or more +character pairs; it shall be an error to set it to an odd number of +characters. +.SS "shell, sh" +.P +[Default from the environment variable +.IR SHELL ] +.P +The value of this option shall be a string. The default shall be taken +from the +.IR SHELL +environment variable. If the +.IR SHELL +environment variable is null or empty, the +.IR sh +(see +.IR "\fIsh\fR\^") +utility shall be the default. +.SS "shiftwidth, sw" +.P +[Default 8] +.P +The value of this option shall give the width in columns of an +indentation level used during autoindentation and by the shift commands +(\c +.BR < +and +.BR > ). +.SS "showmatch, sm" +.P +[Default \fIunset\fR] +.P +The functionality described for the +.BR showmatch +edit option need not be supported on block-mode terminals or terminals +with insufficient capabilities. +.P +If +.BR showmatch +is set, in open or visual mode, when a +.BR ')' +or +.BR '}' +is typed, if the matching +.BR '(' +or +.BR '{' +is currently visible on the display, the matching +.BR '(' +or +.BR '{' +shall be flagged moving the cursor to its location for an unspecified +amount of time. +.SS "showmode" +.P +[Default \fIunset\fP] +.P +If +.BR showmode +is set, in open or visual mode, the current mode that the editor is in +shall be displayed on the last line of the display. Command mode and +text input mode shall be differentiated; other unspecified modes and +implementation-defined information may be displayed. +.SS "slowopen" +.P +[Default \fIunset\fR] +.P +If +.BR slowopen +is set during open and visual text input modes, the editor shall not +update portions of the display other than those display line columns +that display the characters entered by the user (see +.IR "Input Mode Commands in vi"). +.SS "tabstop, ts" +.P +[Default 8] +.P +The value of this edit option shall specify the column boundary used by +a + +in the display (see +.IR "autoprint" ", " "ap" +and +.IR "Input Mode Commands in vi"). +.SS "taglength, tl" +.P +[Default zero] +.P +The value of this edit option shall specify the maximum number of +characters that are considered significant in the user-specified tag +name and in the tag name from the tags file. If the value is zero, all +characters in both tag names shall be significant. +.SS "tags" +.P +[Default \fIsee text\fP] +.P +The value of this edit option shall be a string of +-delimited +pathnames of files used by the +.BR tag +command. The default value is unspecified. +.SS "term" +.P +[Default from the environment variable +.IR TERM ] +.P +The value of this edit option shall be a string. The default shall be +taken from the +.IR TERM +variable in the environment. If the +.IR TERM +environment variable is empty or null, the default is unspecified. The +editor shall use the value of this edit option to determine the type of +the display device. +.P +The results are unspecified if the user changes the value of the term +edit option after editor initialization. +.SS "terse" +.P +[Default \fIunset\fR] +.P +If +.BR terse +is set, error messages may be less verbose. However, except for this +caveat, error messages are unspecified. Furthermore, not all error +messages need change for different settings of this option. +.SS "warn" +.P +[Default \fIset\fR] +.P +If +.BR warn +is set, and the contents of the edit buffer have been modified since +they were last completely written, the editor shall write a warning +message before certain +.BR ! +commands (see +.IR "Escape"). +.SS "window" +.P +[Default \fIsee text\fR] +.P +A value used in open and visual mode, by the +\(hyB +and +\(hyF +commands, and, in visual mode, to specify the number of lines displayed +when the screen is repainted. +.P +If the +.BR \(miw +command-line option is not specified, the default value shall be set to +the value of the +.IR LINES +environment variable. If the +.IR LINES +environment variable is empty or null, the default shall be the number +of lines in the display minus 1. +.P +Setting the +.BR window +edit option to zero or to a value greater than the number of lines in +the display minus 1 (either explicitly or based on the +.BR \(miw +option or the +.IR LINES +environment variable) shall cause the +.BR window +edit option to be set to the number of lines in the display minus 1. +.P +The baud rate of the terminal line may change the default in an +implementation-defined manner. +.SS "wrapmargin, wm" +.P +[Default 0] +.P +If the value of this edit option is zero, it shall have no effect. +.P +If not in the POSIX locale, the effect of this edit option is +implementation-defined. +.P +Otherwise, it shall specify a number of columns from the ending margin +of the terminal. +.P +During open and visual text input modes, for each character for which +any part of the character is displayed in a column that is less than +.BR wrapmargin +columns from the ending margin of the display line, the editor shall +behave as follows: +.IP " 1." 4 +If the character triggering this event is a +, +it, and all immediately preceding + +characters on the current line entered during the execution of the +current text input command, shall be discarded, and the editor shall +behave as if the user had entered a single + +instead. In addition, if the next user-entered character is a +, +it shall be discarded as well. +.IP " 2." 4 +Otherwise, if there are one or more + +characters on the current line immediately preceding the last group of +inserted non-\c + +characters which was entered during the execution of the current text +input command, the + +characters shall be replaced as if the user had entered a single + +instead. +.P +If the +.BR autoindent +edit option is set, and the events described in 1. or 2. are performed, +any + +characters at or after the cursor in the current line shall be discarded. +.P +The ending margin shall be determined by the system or overridden by +the user, as described for +.IR COLUMNS +in the ENVIRONMENT VARIABLES section and the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SS "wrapscan, ws" +.P +[Default \fIset\fR] +.P +If +.BR wrapscan +is set, searches (the +.IR ex +.BR / +or +.BR ? +addresses, or open and visual mode +.BR / , +.BR ? , +.BR N , +and +.BR n +commands) shall wrap around the beginning or end of the edit buffer; +when unset, searches shall stop at the beginning or end of the edit +buffer. +.SS "writeany, wa" +.P +[Default \fIunset\fR] +.P +If +.BR writeany +is set, some of the checks performed when executing the +.IR ex +.BR write +commands shall be inhibited, as described in editor option +.BR autowrite . +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When any error is encountered and the standard input is not a terminal +device file, +.IR ex +shall not write the file or return to command or text input mode, and +shall terminate with a non-zero exit status. +.P +Otherwise, when an unrecoverable error is encountered, it shall be +equivalent to a SIGHUP asynchronous event. +.P +Otherwise, when an error is encountered, the editor shall behave as +specified in +.IR "Command Line Parsing in ex". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If a SIGSEGV signal is received while +.IR ex +is saving a file, the file might not be successfully saved. +.P +The +.BR next +command can accept more than one file, so usage such as: +.sp +.RS 4 +.nf +\fB +next `ls [abc]*` +.fi \fR +.P +.RE +.P +is valid; it would not be valid for the +.BR edit +or +.BR read +commands, for example, because they expect only one file and +unspecified results occur. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR ex /\c +.IR vi +specification is based on the historical practice found in the 4 BSD and +System V implementations of +.IR ex +and +.IR vi . +.P +A +.IR "restricted editor" +(both the historical +.IR red +utility and modifications to +.IR ex ) +were considered and rejected for inclusion. Neither option provided the +level of security that users might expect. +.P +It is recognized that +.IR ex +visual mode and related features would be difficult, if not impossible, +to implement satisfactorily on a block-mode terminal, or a terminal +without any form of cursor addressing; thus, it is not a mandatory +requirement that such features should work on all terminals. It is the +intention, however, that an +.IR ex +implementation should provide the full set of capabilities on all +terminals capable of supporting them. +.SS "Options" +.P +The +.BR \(mic +replacement for +.BR + \c +.IR command +was inspired by the +.BR \(mie +option of +.IR sed . +Historically, all such commands (see +.BR edit +and +.BR next +as well) were executed from the last line of the edit buffer. This +meant, for example, that +.BR \(dq+/pattern\(dq +would fail unless the +.BR wrapscan +option was set. POSIX.1\(hy2008 requires conformance to historical practice. The +.BR \(pl \c +.IR command +option is no longer specified by POSIX.1\(hy2008 but may be present in +some implementations. Historically, some implementations restricted the +.IR ex +commands that could be listed as part of the command line arguments. +For consistency, POSIX.1\(hy2008 does not permit these restrictions. +.P +In historical implementations of the editor, the +.BR \(miR +option (and the +.BR readonly +edit option) only prevented overwriting of files; appending to files +was still permitted, mapping loosely into the +.IR csh +.BR noclobber +variable. Some implementations, however, have not followed this +semantic, and +.BR readonly +does not permit appending either. POSIX.1\(hy2008 follows the latter practice, +believing that it is a more obvious and intuitive meaning of +.BR readonly . +.P +The +.BR \(mis +option suppresses all interactive user feedback and is useful for +editing scripts in batch jobs. The list of specific effects is +historical practice. The terminal type ``incapable of supporting open +and visual modes'' has historically been named ``dumb''. +.P +The +.BR \(mit +option was required because the +.IR ctags +utility appears in POSIX.1\(hy2008 and the option is available in all historical +implementations of +.IR ex . +.P +Historically, the +.IR ex +and +.IR vi +utilities accepted a +.BR \(mix +option, which did encryption based on the algorithm found in the +historical +.IR crypt +utility. The +.BR \(mix +option for encryption, and the associated +.IR crypt +utility, were omitted because the algorithm used was not specifiable +and the export control laws of some nations make it difficult to export +cryptographic technology. In addition, it did not historically provide +the level of security that users might expect. +.SS "Standard Input" +.P +An end-of-file condition is not equivalent to an end-of-file character. +A common end-of-file character, +\(hyD, +is historically an +.IR ex +command. +.P +There was no maximum line length in historical implementations of +.IR ex . +Specifically, as it was parsed in chunks, the addresses had a different +maximum length than the filenames. Further, the maximum line buffer +size was declared as BUFSIZ, which was different lengths on different +systems. This version selected the value of +{LINE_MAX} +to impose a reasonable restriction on portable usage of +.IR ex +and to aid test suite writers in their development of realistic tests +that exercise this limit. +.SS "Input Files" +.P +It was an explicit decision by the standard developers that a + +be added to any file lacking one. It was believed that this feature of +.IR ex +and +.IR vi +was relied on by users in order to make text files lacking a trailing + +more portable. It is recognized that this will require a user-specified +option or extension for implementations that permit +.IR ex +and +.IR vi +to edit files of type other than text if such files are not otherwise +identified by the system. It was agreed that the ability to edit files +of arbitrary type can be useful, but it was not considered necessary to +mandate that an +.IR ex +or +.IR vi +implementation be required to handle files other than text files. +.P +The paragraph in the INPUT FILES section, ``By default, .\|.\|.'', is +intended to close a long-standing security problem in +.IR ex +and +.IR vi ; +that of the ``modeline'' or ``modelines'' edit option. This feature +allows any line in the first or last five lines of the file containing +the strings +.BR \(dqex:\(dq +or +.BR \(dqvi:\(dq +(and, apparently, +.BR \(dqei:\(dq +or +.BR \(dqvx:\(dq ) +to be a line containing editor commands, and +.IR ex +interprets all the text up to the next +.BR ':' +or + +as a command. Consider the consequences, for example, of an +unsuspecting user using +.IR ex +or +.IR vi +as the editor when replying to a mail message in which a line such as: +.sp +.RS 4 +.nf +\fB +ex:! rm \(mirf : +.fi \fR +.P +.RE +.P +appeared in the signature lines. The standard developers believed +strongly that an editor should not by default interpret any lines of a +file. Vendors are strongly urged to delete this feature from their +implementations of +.IR ex +and +.IR vi . +.SS "Asynchronous Events" +.P +The intention of the phrase ``complete write'' is that the entire edit +buffer be written to stable storage. The note regarding temporary files +is intended for implementations that use temporary files to back edit +buffers unnamed by the user. +.P +Historically, SIGQUIT was ignored by +.IR ex , +but was the equivalent of the +.BR Q +command in visual mode; that is, it exited visual mode and entered +.IR ex +mode. POSIX.1\(hy2008 permits, but does not require, this behavior. Historically, +SIGINT was often used by +.IR vi +users to terminate text input mode (\c +\(hyC +is often easier to enter than +). +Some implementations of +.IR vi +alerted the terminal on this event, and some did not. POSIX.1\(hy2008 requires +that SIGINT behave identically to +, +and that the terminal not be alerted. +.P +Historically, suspending the +.IR ex +editor during text input mode was similar to SIGINT, as completed lines +were retained, but any partial line discarded, and the editor returned +to command mode. POSIX.1\(hy2008 is silent on this issue; implementations are +encouraged to follow historical practice, where possible. +.P +Historically, the +.IR vi +editor did not treat SIGTSTP as an asynchronous event, and it was +therefore impossible to suspend the editor in visual text input mode. +There are two major reasons for this. The first is that SIGTSTP is a +broadcast signal on UNIX systems, and the chain of events where the +shell +.IR exec s +an application that then +.IR exec s +.IR vi +usually caused confusion for the terminal state if SIGTSTP was delivered +to the process group in the default manner. The second was that most +implementations of the UNIX +.IR curses +package did not handle SIGTSTP safely, and the receipt of SIGTSTP at +the wrong time would cause them to crash. POSIX.1\(hy2008 is silent on this issue; +implementations are encouraged to treat suspension as an asynchronous +event if possible. +.P +Historically, modifications to the edit buffer made before SIGINT +interrupted an operation were retained; that is, anywhere from zero to +all of the lines to be modified might have been modified by the time +the SIGINT arrived. These changes were not discarded by the arrival of +SIGINT. POSIX.1\(hy2008 permits this behavior, noting that the +.BR undo +command is required to be able to undo these partially completed +commands. +.P +The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and +SIGTERM is unspecified because some implementations attempt to save the +edit buffer in a useful state when other signals are received. +.SS "Standard Error" +.P +For +.IR ex /\c +.IR vi , +diagnostic messages are those messages reported as a result of a failed +attempt to invoke +.IR ex +or +.IR vi , +such as invalid options or insufficient resources, or an abnormal +termination condition. Diagnostic messages should not be confused with +the error messages generated by inappropriate or illegal user +commands. +.SS "Initialization in ex and vi" +.P +If an +.IR ex +command (other than +.BR cd , +.BR chdir , +or +.BR source ) +has a filename argument, one or both of the alternate and current +pathnames will be set. Informally, they are set as follows: +.IP " 1." 4 +If the +.IR ex +command is one that replaces the contents of the edit buffer, and it +succeeds, the current pathname will be set to the filename argument +(the first filename argument in the case of the +.BR next +command) and the alternate pathname will be set to the previous +current pathname, if there was one. +.IP " 2." 4 +In the case of the file read/write forms of the +.BR read +and +.BR write +commands, if there is no current pathname, the current pathname will +be set to the filename argument. +.IP " 3." 4 +Otherwise, the alternate pathname will be set to the filename +argument. +.P +For example, +.BR ":edit foo" +and +.BR ":recover foo" , +when successful, set the current pathname, and, if there was a +previous current pathname, the alternate pathname. The commands +.BR :write , +.BR !command , +and +.BR :edit +set neither the current or alternate pathnames. If the +.BR ":edit foo" +command were to fail for some reason, the alternate pathname would be +set. The +.BR read +and +.BR write +commands set the alternate pathname to their +.IR file +argument, unless the current pathname is not set, in which case they +set the current pathname to their +.IR file +arguments. The alternate pathname was not historically set by the +.BR :source +command. POSIX.1\(hy2008 requires conformance to historical practice. +Implementations adding commands that take filenames as arguments are +encouraged to set the alternate pathname as described here. +.P +Historically, +.IR ex +and +.IR vi +read the +.BR .exrc +file in the +.IR $HOME +directory twice, if the editor was executed in the +.IR $HOME +directory. POSIX.1\(hy2008 prohibits this behavior. +.P +Historically, the 4 BSD +.IR ex +and +.IR vi +read the +.IR $HOME +and local +.BR .exrc +files if they were owned by the real ID of the user, or the +.BR sourceany +option was set, regardless of other considerations. This was a security +problem because it is possible to put normal UNIX system commands +inside a +.BR .exrc +file. POSIX.1\(hy2008 does not specify the +.BR sourceany +option, and historical implementations are encouraged to delete it. +.P +The +.BR .exrc +files must be owned by the real ID of the user, and not writable by +anyone other than the owner. The appropriate privileges exception is +intended to permit users to acquire special privileges, but continue to +use the +.BR .exrc +files in their home directories. +.P +System V Release 3.2 and later +.IR vi +implementations added the option +.BR [no]exrc . +The behavior is that local +.BR .exrc +files are read-only if the +.BR exrc +option is set. The default for the +.BR exrc +option was off, so by default, local +.BR .exrc +files were not read. The problem this was intended to solve was that +System V permitted users to give away files, so there is no possible +ownership or writeability test to ensure that the file is safe. This is +still a security problem on systems where users can give away files, +but there is nothing additional that POSIX.1\(hy2008 can do. The +implementation-defined exception is intended to permit groups to have +local +.BR .exrc +files that are shared by users, by creating pseudo-users to own the +shared files. +.P +POSIX.1\(hy2008 does not mention system-wide +.IR ex +and +.IR vi +start-up files. While they exist in several implementations of +.IR ex +and +.IR vi , +they are not present in any implementations considered historical +practice by POSIX.1\(hy2008. Implementations that have such files should use them +only if they are owned by the real user ID or an appropriate user (for +example, root on UNIX systems) and if they are not writable by any +user other than their owner. System-wide start-up files should be read +before the +.IR EXINIT +variable, +.BR $HOME/.exrc , +or local +.BR .exrc +files are evaluated. +.P +Historically, any +.IR ex +command could be entered in the +.IR EXINIT +variable or the +.BR .exrc +file, although ones requiring that the edit buffer already contain +lines of text generally caused historical implementations of the editor +to drop +.BR core . +POSIX.1\(hy2008 requires that any +.IR ex +command be permitted in the +.IR EXINIT +variable and +.BR .exrc +files, for simplicity of specification and consistency, although many +of them will obviously fail under many circumstances. +.P +The initialization of the contents of the edit buffer uses the phrase +``the effect shall be'' with regard to various +.IR ex +commands. The intent of this phrase is that edit buffer contents loaded +during the initialization phase not be lost; that is, loading the edit +buffer should fail if the +.BR .exrc +file read in the contents of a file and did not subsequently write the +edit buffer. An additional intent of this phrase is to specify that the +initial current line and column is set as specified for the individual +.IR ex +commands. +.P +Historically, the +.BR \(mit +option behaved as if the tag search were a +.BR + \c +.IR command ; +that is, it was executed from the last line of the file specified by +the tag. This resulted in the search failing if the pattern was a +forward search pattern and the +.BR wrapscan +edit option was not set. POSIX.1\(hy2008 does not permit this behavior, requiring +that the search for the tag pattern be performed on the entire file, +and, if not found, that the current line be set to a more reasonable +location in the file. +.P +Historically, the empty edit buffer presented for editing when a file +was not specified by the user was unnamed. This is permitted by POSIX.1\(hy2008; +however, implementations are encouraged to provide users a temporary +filename for this buffer because it permits them the use of +.IR ex +commands that use the current pathname during temporary edit +sessions. +.P +Historically, the file specified using the +.BR \(mit +option was not part of the current argument list. This practice is +permitted by POSIX.1\(hy2008; however, implementations are encouraged to include +its name in the current argument list for consistency. +.P +Historically, the +.BR \(mic +command was generally not executed until a file that already exists was +edited. POSIX.1\(hy2008 requires conformance to this historical practice. +Commands that could cause the +.BR \(mic +command to be executed include the +.IR ex +commands +.BR edit , +.BR next , +.BR recover , +.BR rewind , +and +.BR tag , +and the +.IR vi +commands +\(hy^ +and +\(hy]. +Historically, reading a file into an edit buffer did not cause the +.BR \(mic +command to be executed (even though it might set the current pathname) +with the exception that it did cause the +.BR \(mic +command to be executed if: the editor was in +.IR ex +mode, the edit buffer had no current pathname, the edit buffer was +empty, and no read commands had yet been attempted. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR \(mir +option was the same as a normal edit session if there was no recovery +information available for the file. This allowed users to enter: +.sp +.RS 4 +.nf +\fB +vi \(mir *.c +.fi \fR +.P +.RE +.P +and recover whatever files were recoverable. In some implementations, +recovery was attempted only on the first file named, and the file was +not entered into the argument list; in others, recovery was attempted +for each file named. In addition, some historical implementations +ignored +.BR \(mir +if +.BR \(mit +was specified or did not support command line +.IR file +arguments with the +.BR \(mit +option. For consistency and simplicity of specification, POSIX.1\(hy2008 +disallows these special cases, and requires that recovery be attempted +the first time each file is edited. +.P +Historically, +.IR vi +initialized the +.BR ` +and +.BR ' +marks, but +.IR ex +did not. This meant that if the first command in +.IR ex +mode was +.BR visual +or if an +.IR ex +command was executed first (for example, +.IR vi ++10 +.IR file ), +.IR vi +was entered without the marks being initialized. Because the standard +developers believed the marks to be generally useful, and for +consistency and simplicity of specification, POSIX.1\(hy2008 requires that they +always be initialized if in open or visual mode, or if in +.IR ex +mode and the edit buffer is not empty. Not initializing it in +.IR ex +mode if the edit buffer is empty is historical practice; however, it +has always been possible to set (and use) marks in empty edit buffers +in open and visual mode edit sessions. +.SS "Addressing" +.P +Historically, +.IR ex +and +.IR vi +accepted the additional addressing forms +.BR '\e/' +and +.BR '\e?' . +They were equivalent to +.BR \(dq//\(dq +and +.BR \(dq??\(dq , +respectively. They are not required by POSIX.1\(hy2008, mostly because nobody can +remember whether they ever did anything different historically. +.P +Historically, +.IR ex +and +.IR vi +permitted an address of zero for several commands, and permitted the +.BR % +address in empty files for others. For consistency, POSIX.1\(hy2008 requires +support for the former in the few commands where it makes sense, and +disallows it otherwise. In addition, because POSIX.1\(hy2008 requires that +.BR % +be logically equivalent to +.BR \(dq1,$\(dq , +it is also supported where it makes sense and disallowed otherwise. +.P +Historically, the +.BR % +address could not be followed by further addresses. For consistency and +simplicity of specification, POSIX.1\(hy2008 requires that additional addresses +be supported. +.P +All of the following are valid +.IR addresses : +.IP "\fR+++\fP" 10 +Three lines after the current line. +.IP "\fR/\fIre\fR/\(mi\fR" 10 +One line before the next occurrence of +.IR re . +.IP "\fR\(mi2\fR" 10 +Two lines before the current line. +.IP "\fR3\0\(mi\|\(mi\|\(mi\|\(mi\02\fR" 10 +Line one (note intermediate negative address). +.IP "\fR1\02\03\fR" 10 +Line six. +.P +Any number of addresses can be provided to commands taking addresses; +for example, +.BR \(dq1,2,3,4,5p\(dq +prints lines 4 and 5, because two is the greatest valid number of +addresses accepted by the +.BR print +command. This, in combination with the + +delimiter, permits users to create commands based on ordered patterns +in the file. For example, the command +.BR "3;/foo/;+2print" +will display the first line after line 3 that contains the pattern +.IR foo , +plus the next two lines. Note that the address +.BR "3;" +must be evaluated before being discarded because the search origin for +the +.BR /foo/ +command depends on this. +.P +Historically, values could be added to addresses by including them +after one or more + +characters; for example, +.BR "3\0\(mi\05p" +wrote the seventh line of the file, and +.BR "/foo/\05" +was the same as +.BR "/foo/+5" . +However, only absolute values could be added; for example, +.BR "5\0/foo/" +was an error. POSIX.1\(hy2008 requires conformance to historical practice. +Address offsets are separately specified from addresses because they +could historically be provided to visual mode search commands. +.P +Historically, any missing addresses defaulted to the current line. This +was true for leading and trailing +-delimited +addresses, and for trailing +-delimited +addresses. For consistency, POSIX.1\(hy2008 requires it for leading + +addresses as well. +.P +Historically, +.IR ex +and +.IR vi +accepted the +.BR '^' +character as both an address and as a flag offset for commands. In both +cases it was identical to the +.BR '\(mi' +character. POSIX.1\(hy2008 does not require or prohibit this behavior. +.P +Historically, the enhancements to basic regular expressions could be +used in addressing; for example, +.BR '~' , +.BR '\e<' , +and +.BR '\e>' . +POSIX.1\(hy2008 requires conformance to historical practice; that is, that +regular expression usage be consistent, and that regular expression +enhancements be supported wherever regular expressions are used. +.SS "Command Line Parsing in ex" +.P +Historical +.IR ex +command parsing was even more complex than that described here. POSIX.1\(hy2008 +requires the subset of the command parsing that the standard developers +believed was documented and that users could reasonably be expected to +use in a portable fashion, and that was historically consistent between +implementations. (The discarded functionality is obscure, at best.) +Historical implementations will require changes in order to comply with +POSIX.1\(hy2008; however, users are not expected to notice any of these changes. +Most of the complexity in +.IR ex +parsing is to handle three special termination cases: +.IP " 1." 4 +The +.BR ! , +.BR global , +.BR v , +and the filter versions of the +.BR read +and +.BR write +commands are delimited by + +characters (they can contain + +characters that are usually shell pipes). +.IP " 2." 4 +The +.BR ex , +.BR edit , +.BR next , +and +.BR visual +in open and visual mode commands all take +.IR ex +commands, optionally containing + +characters, as their first arguments. +.IP " 3." 4 +The +.BR s +command takes a regular expression as its first argument, and uses the +delimiting characters to delimit the command. +.P +Historically, + +characters in the +.BR + \c +.IR command +argument of the +.BR ex , +.BR edit , +.BR next , +.BR vi , +and +.BR visual +commands, and in the +.IR pattern +and +.IR replacement +parts of the +.BR s +command, did not delimit the command, and in the filter cases for +.BR read +and +.BR write , +and the +.BR ! , +.BR global , +and +.BR v +commands, they did not delimit the command at all. For example, the +following commands are all valid: +.sp +.RS 4 +.nf +\fB +\fB:\fRedit +25 | s/abc/ABC/ file.c +\fB:\fRs/ | /PIPE/ +\fB:\fRread !spell % | columnate +\fB:\fRglobal/pattern/p | l +\fB:\fRs/a/b/ | s/c/d | set +.fi \fR +.P +.RE +.P +Historically, empty or + +filled lines in +.BR .exrc +files and +.BR source d +files (as well as +.IR EXINIT +variables and +.IR ex +command scripts) were treated as default commands; that is, +.BR print +commands. POSIX.1\(hy2008 specifically requires that they be ignored when +encountered in +.BR .exrc +and +.BR source d +files to eliminate a common source of new user error. +.P +Historically, +.IR ex +commands with multiple adjacent (or +-separated) +vertical lines were handled oddly when executed from +.IR ex +mode. For example, the command +.BR "|||" +, +when the cursor was on line 1, displayed lines 2, 3, and 5 of the file. +In addition, the command +.BR | +would only display the line after the next line, instead of the next +two lines. The former worked more logically when executed from +.IR vi +mode, and displayed lines 2, 3, and 4. POSIX.1\(hy2008 requires the +.IR vi +behavior; that is, a single default command and line number increment +for each command separator, and trailing + +characters after + +separators are discarded. +.P +Historically, +.IR ex +permitted a single extra + +as a leading command character; for example, +.BR ":g/pattern/:p" +was a valid command. POSIX.1\(hy2008 generalizes this to require that any number +of leading + +characters be stripped. +.P +Historically, any prefix of the +.BR delete +command could be followed without intervening + +characters by a flag character because in the command +.BR "d\0p" , +.IR p +is interpreted as the buffer +.IR p . +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR k +command could be followed by the mark name without intervening + +characters. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR s +command could be immediately followed by flag and option characters; +for example, +.BR "s/e/E/|s|sgc3p" +was a valid command. However, flag characters could not stand alone; +for example, the commands +.BR sp +and +.BR s\0l +would fail, while the command +.BR sgp +and +.BR "s\0gl" +would succeed. (Obviously, the +.BR '#' +flag character was used as a delimiter character if it followed the +command.) Another issue was that option characters had to precede flag +characters even when the command was fully specified; for example, the +command +.BR s/e/E/pg +would fail, while the command +.BR s/e/E/gp +would succeed. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the first command name that had a prefix matching the +input from the user was the executed command; for example, +.BR ve , +.BR ver , +and +.BR vers +all executed the +.BR version +command. Commands were in a specific order, however, so that +.BR a +matched +.BR append , +not +.BR abbreviate . +POSIX.1\(hy2008 requires conformance to historical practice. The restriction on +command search order for implementations with extensions is to avoid +the addition of commands such that the historical prefixes would fail +to work portably. +.P +Historical implementations of +.IR ex +and +.IR vi +did not correctly handle multiple +.IR ex +commands, separated by + +characters, that entered or exited visual mode or the editor. Because +implementations of +.IR vi +exist that do not exhibit this failure mode, POSIX.1\(hy2008 does not permit it. +.P +The requirement that alphabetic command names consist of all following +alphabetic characters up to the next non-alphabetic character means +that alphabetic command names must be separated from their arguments by +one or more non-alphabetic characters, normally a + +or +.BR '!' +character, except as specified for the exceptions, the +.BR delete , +.BR k , +and +.BR s +commands. +.P +Historically, the repeated execution of the +.IR ex +default +.BR print +commands (\c +\(hyD, +.IR eof , +, +) +erased any prompting character and displayed the next lines without +scrolling the terminal; that is, immediately below any previously +displayed lines. This provided a cleaner presentation of the lines in +the file for the user. POSIX.1\(hy2008 does not require this behavior because it +may be impossible in some situations; however, implementations are +strongly encouraged to provide this semantic if possible. +.P +Historically, it was possible to change files in the middle of a command, +and have the rest of the command executed in the new file; for example: +.sp +.RS 4 +.nf +\fB +:edit +25 file.c | s/abc/ABC/ | 1 +.fi \fR +.P +.RE +.P +was a valid command, and the substitution was attempted in the newly +edited file. POSIX.1\(hy2008 requires conformance to historical practice. The +following commands are examples that exercise the +.IR ex +parser: +.sp +.RS 4 +.nf +\fB +echo 'foo | bar' > file1; echo 'foo/bar' > file2; +vi +:edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\e//SLASH/ | wq +.fi \fR +.P +.RE +.P +Historically, there was no protection in editor implementations to +avoid +.IR ex +.BR global , +.BR v , +.BR @ , +or +.BR * +commands changing edit buffers during execution of their associated +commands. Because this would almost invariably result in catastrophic +failure of the editor, and implementations exist that do exhibit these +problems, POSIX.1\(hy2008 requires that changing the edit buffer during a +.BR global +or +.BR v +command, or during a +.BR @ +or +.BR * +command for which there will be more than a single execution, be an +error. Implementations supporting multiple edit buffers simultaneously +are strongly encouraged to apply the same semantics to switching +between buffers as well. +.P +The +.IR ex +command quoting required by POSIX.1\(hy2008 is a superset of the quoting in +historical implementations of the editor. For example, it was not +historically possible to escape a + +in a filename; for example, +.BR ":edit\0foo\e\e\e\0bar" +would report that too many filenames had been entered for the edit +command, and there was no method of escaping a + +in the first argument of an +.BR edit , +.BR ex , +.BR next , +or +.BR visual +command at all. POSIX.1\(hy2008 extends historical practice, requiring that +quoting behavior be made consistent across all +.IR ex +commands, except for the +.BR map , +.BR unmap , +.BR abbreviate , +and +.BR unabbreviate +commands, which historically used +\(hyV +instead of + +characters for quoting. For those four commands, POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Backslash quoting in +.IR ex +is non-intuitive. +-escapes +are ignored unless they escape a special character; for example, when +performing +.IR file +argument expansion, the string +.BR \(dq\e\e%\(dq +is equivalent to +.BR '\e%' , +not \fR"\e<\fIcurrent\ pathname\fR>"\fR. +This can be confusing for users because + +is usually one of the characters that causes shell expansion to +be performed, and therefore shell quoting rules must be taken into +consideration. Generally, quoting characters are only considered if they +escape a special character, and a quoting character must be provided +for each layer of parsing for which the character is special. As another +example, only a single + +is necessary for the +.BR '\el' +sequence in substitute replacement patterns, because the character +.BR 'l' +is not special to any parsing layer above it. +.P +\(hyV +quoting in +.IR ex +is slightly different from backslash quoting. In the four commands +where +\(hyV +quoting applies (\c +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap ), +any character may be escaped by a +\(hyV +whether it would have a special meaning or not. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historical implementations of the editor did not require delimiters +within character classes to be escaped; for example, the command +.BR ":s/[/]//" +on the string +.BR \(dqxxx/yyy\(dq +would delete the +.BR '/' +from the string. POSIX.1\(hy2008 disallows this historical practice for +consistency and because it places a large burden on implementations by +requiring that knowledge of regular expressions be built into the +editor parser. +.P +Historically, quoting + +characters in +.IR ex +commands was handled inconsistently. In most cases, the + +character always terminated the command, regardless of any preceding +escape character, because + +characters did not escape + +characters for most +.IR ex +commands. However, some +.IR ex +commands (for example, +.BR s , +.BR map , +and +.BR abbreviation ) +permitted + +characters to be escaped (although in the case of +.BR map +and +.BR abbreviation , +\(hyV +characters escaped them instead of + +characters). This was true in not only the command line, but also +.BR .exrc +and +.BR source d +files. For example, the command: +.sp +.RS 4 +.nf +\fB +map = foobar +.fi \fR +.P +.RE +.P +would succeed, although it was sometimes difficult to get the +\(hyV +and the inserted + +passed to the +.IR ex +parser. For consistency and simplicity of specification, POSIX.1\(hy2008 requires +that it be possible to escape + +characters in +.IR ex +commands at all times, using + +characters for most +.IR ex +commands, and using +\(hyV +characters for the +.BR map +and +.BR abbreviation +commands. For example, the command +.BR print \c +\c +.BR list +is required to be parsed as the single command +.BR print \c +\c +.BR list . +While this differs from historical practice, POSIX.1\(hy2008 developers believed +it unlikely that any script or user depended on the historical +behavior. +.P +Historically, an error in a command specified using the +.BR \(mic +option did not cause the rest of the +.BR \(mic +commands to be discarded. POSIX.1\(hy2008 disallows this for consistency with +mapped keys, the +.BR @ , +.BR global , +.BR source , +and +.BR v +commands, the +.IR EXINIT +environment variable, and the +.BR .exrc +files. +.SS "Input Editing in ex" +.P +One of the common uses of the historical +.IR ex +editor is over slow network connections. Editors that run in canonical +mode can require far less traffic to and from, and far less processing +on, the host machine, as well as more easily supporting block-mode +terminals. For these reasons, POSIX.1\(hy2008 requires that +.IR ex +be implemented using canonical mode input processing, as was done +historically. +.P +POSIX.1\(hy2008 does not require the historical 4 BSD input editing characters +``word erase'' or ``literal next''. For this reason, it is unspecified +how they are handled by +.IR ex , +although they must have the required effect. Implementations that +resolve them after the line has been ended using a + +or +\(hyM +character, and implementations that rely on the underlying system +terminal support for this processing, are both conforming. +Implementations are strongly urged to use the underlying system +functionality, if at all possible, for compatibility with other system +text input interfaces. +.P +Historically, when the +.IR eof +character was used to decrement the +.BR autoindent +level, the cursor moved to display the new end of the +.BR autoindent +characters, but did not move the cursor to a new line, nor did it erase +the +\(hyD +character from the line. POSIX.1\(hy2008 does not specify that the cursor remain +on the same line or that the rest of the line is erased; however, +implementations are strongly encouraged to provide the best possible +user interface; that is, the cursor should remain on the same line, and +any +\(hyD +character on the line should be erased. +.P +POSIX.1\(hy2008 does not require the historical 4 BSD input editing character +``reprint'', traditionally +\(hyR, +which redisplayed the current input from the user. For this reason, and +because the functionality cannot be implemented after the line has been +terminated by the user, POSIX.1\(hy2008 makes no requirements about this +functionality. Implementations are strongly urged to make this +historical functionality available, if possible. +.P +Historically, +\(hyQ +did not perform a literal next function in +.IR ex , +as it did in +.IR vi . +POSIX.1\(hy2008 requires conformance to historical practice to avoid breaking +historical +.IR ex +scripts and +.BR .exrc +files. +.SS "eof" +.P +Whether the +.IR eof +character immediately modifies the +.BR autoindent +characters in the prompt is left unspecified so that implementations +can conform in the presence of systems that do not support this +functionality. Implementations are encouraged to modify the line and +redisplay it immediately, if possible. +.P +The specification of the handling of the +.IR eof +character differs from historical practice only in that +.IR eof +characters are not discarded if they follow normal characters in the +text input. Historically, they were always discarded. +.SS "Command Descriptions in ex" +.P +Historically, several commands (for example, +.BR global , +.BR v , +.BR visual , +.BR s , +.BR write , +.BR wq , +.BR yank , +.BR ! , +.BR < , +.BR > , +.BR & , +and +.BR ~ ) +were executable in empty files (that is, the default address(es) were +0), or permitted explicit addresses of 0 (for example, 0 was a valid +address, or 0,0 was a valid range). Addresses of 0, or command +execution in an empty file, make sense only for commands that add new +text to the edit buffer or write commands (because users may wish to +write empty files). POSIX.1\(hy2008 requires this behavior for such commands and +disallows it otherwise, for consistency and simplicity of +specification. +.P +A count to an +.IR ex +command has been historically corrected to be no greater than the last +line in a file; for example, in a five-line file, the command +.BR "1,6print" +would fail, but the command +.BR "1print300" +would succeed. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the use of flags in +.IR ex +commands could be obscure. General historical practice was as described +by POSIX.1\(hy2008, but there were some special cases. For instance, the +.BR list , +.BR number , +and +.BR print +commands ignored trailing address offsets; for example, +.BR "3p\0+++#" +would display line 3, and 3 would be the current line after the +execution of the command. The +.BR open +and +.BR visual +commands ignored both the trailing offsets and the trailing flags. +Also, flags specified to the +.BR open +and +.BR visual +commands interacted badly with the +.BR list +edit option, and setting and then unsetting it during the open/visual +session would cause +.IR vi +to stop displaying lines in the specified format. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit any of these +exceptions to the general rule. +.P +POSIX.1\(hy2008 uses the word +.IR copy +in several places when discussing buffers. This is not intended to +imply implementation. +.P +Historically, +.IR ex +users could not specify numeric buffers because of the ambiguity this +would cause; for example, in the command +.BR "3\0delete\02" , +it is unclear whether 2 is a buffer name or a +.IR count . +POSIX.1\(hy2008 requires conformance to historical practice by default, but does +not preclude extensions. +.P +Historically, the contents of the unnamed buffer were frequently +discarded after commands that did not explicitly affect it; for +example, when using the +.BR edit +command to switch files. For consistency and simplicity of +specification, POSIX.1\(hy2008 does not permit this behavior. +.P +The +.IR ex +utility did not historically have access to the numeric buffers, and, +furthermore, deleting lines in +.IR ex +did not modify their contents. For example, if, after doing a delete in +.IR vi , +the user switched to +.IR ex , +did another delete, and then switched back to +.IR vi , +the contents of the numeric buffers would not have changed. POSIX.1\(hy2008 +requires conformance to historical practice. Numeric buffers are +described in the +.IR ex +utility in order to confine the description of buffers to a single +location in POSIX.1\(hy2008. +.P +The metacharacters that trigger shell expansion in +.IR file +arguments match historical practice, as does the method for doing shell +expansion. Implementations wishing to provide users with the +flexibility to alter the set of metacharacters are encouraged to +provide a +.BR shellmeta +string edit option. +.P +Historically, +.IR ex +commands executed from +.IR vi +refreshed the screen when it did not strictly need to do so; for +example, +.BR ":!date\0>\0/dev/null" +does not require a screen refresh because the output of the UNIX +.IR date +command requires only a single line of the screen. POSIX.1\(hy2008 requires that +the screen be refreshed if it has been overwritten, but makes no +requirements as to how an implementation should make that +determination. Implementations may prompt and refresh the screen +regardless. +.SS "Abbreviate" +.P +Historical practice was that characters that were entered as part of an +abbreviation replacement were subject to +.BR map +expansions, the +.BR showmatch +edit option, further abbreviation expansions, and so on; that is, they +were logically pushed onto the terminal input queue, and were not a +simple replacement. POSIX.1\(hy2008 requires conformance to historical practice. +Historical practice was that whenever a non-word character (that had +not been escaped by a +\(hyV) +was entered after a word character, +.IR vi +would check for abbreviations. The check was based on the type of the +character entered before the word character of the word/non-word pair +that triggered the check. The word character of the word/non-word pair +that triggered the check and all characters entered before the trigger +pair that were of that type were included in the check, with the +exception of + +characters, which always delimited the abbreviation. +.P +This means that, for the abbreviation to work, the +.IR lhs +must end with a word character, there can be no transitions from word +to non-word characters (or \fIvice versa\fP) other than between the +last and next-to-last characters in the +.IR lhs , +and there can be no + +characters in the +.IR lhs . +In addition, because of the historical quoting rules, it was impossible +to enter a literal +\(hyV +in the +.IR lhs . +POSIX.1\(hy2008 requires conformance to historical practice. Historical +implementations did not inform users when abbreviations that could +never be used were entered; implementations are strongly encouraged to +do so. +.br +.P +For example, the following abbreviations will work: +.sp +.RS 4 +.nf +\fB +:ab (p REPLACE +:ab p REPLACE +:ab ((p REPLACE +.fi \fR +.P +.RE +.P +The following abbreviations will not work: +.sp +.RS 4 +.nf +\fB +:ab ( REPLACE +:ab (pp REPLACE +.fi \fR +.P +.RE +.P +Historical practice is that words on the +.IR vi +colon command line were subject to abbreviation expansion, including +the arguments to the +.BR abbrev +(and more interestingly) the +.BR unabbrev +command. Because there are implementations that do not do abbreviation +expansion for the first argument to those commands, this is permitted, +but not required, by POSIX.1\(hy2008. However, the following sequence: +.sp +.RS 4 +.nf +\fB +:ab foo bar +:ab foo baz +.fi \fR +.P +.RE +.P +resulted in the addition of an abbreviation of +.BR \(dqbaz\(dq +for the string +.BR \(dqbar\(dq +in historical +.IR ex /\c +.IR vi , +and the sequence: +.sp +.RS 4 +.nf +\fB +:ab foo1 bar +:ab foo2 bar +:unabbreviate foo2 +.fi \fR +.P +.RE +.P +deleted the abbreviation +.BR \(dqfoo1\(dq , +not +.BR \(dqfoo2\(dq . +These behaviors are not permitted by POSIX.1\(hy2008 because they clearly violate +the expectations of the user. +.P +It was historical practice that +\(hyV, +not +, +characters be interpreted as escaping subsequent characters in the +.BR abbreviate +command. POSIX.1\(hy2008 requires conformance to historical practice; however, it +should be noted that an abbreviation containing a + +will never work. +.SS "Append" +.P +Historically, any text following a + +command separator after an +.BR append , +.BR change , +or +.BR insert +command became part of the insert text. For example, in the command: +.sp +.RS 4 +.nf +\fB +:g/pattern/append|stuff1 +.fi \fR +.P +.RE +.P +a line containing the text +.BR \(dqstuff1\(dq +would be appended to each line matching pattern. It was also +historically valid to enter: +.sp +.RS 4 +.nf +\fB +:append|stuff1 +stuff2 +\&. +.fi \fR +.P +.RE +.P +and the text on the +.IR ex +command line would be appended along with the text inserted after it. +There was an historical bug, however, that the user had to enter two +terminating lines (the +.BR '.' +lines) to terminate text input mode in this case. POSIX.1\(hy2008 requires +conformance to historical practice, but disallows the historical need +for multiple terminating lines. +.SS "Change" +.P +See the RATIONALE for the +.BR append +command. Historical practice for cursor positioning after the change +command when no text is input, is as described in POSIX.1\(hy2008. However, one +System V implementation is known to have been modified such that the +cursor is positioned on the first address specified, and not on the +line before the first address. POSIX.1\(hy2008 disallows this modification for +consistency. +.P +Historically, the +.BR change +command did not support buffer arguments, although some implementations +allow the specification of an optional buffer. This behavior is neither +required nor disallowed by POSIX.1\(hy2008. +.SS "Change Directory" +.P +A common extension in +.IR ex +implementations is to use the elements of a +.BR cdpath +edit option as prefix directories for +.IR path +arguments to +.BR chdir +that are relative pathnames and that do not have +.BR '.' +or +.BR \(dq..\(dq +as their first component. Elements in the +.BR cdpath +edit option are +-separated. +The initial value of the +.BR cdpath +edit option is the value of the shell +.IR CDPATH +environment variable. This feature was not included in POSIX.1\(hy2008 because it +does not exist in any of the implementations considered historical +practice. +.SS "Copy" +.P +Historical implementations of +.IR ex +permitted copies to lines inside of the specified range; for example, +.BR ":2,5copy3" +was a valid command. POSIX.1\(hy2008 requires conformance to historical +practice. +.SS "Delete" +.P +POSIX.1\(hy2008 requires support for the historical parsing of a +.BR delete +command followed by flags, without any intervening + +characters. For example: +.IP "\fB1dp\fP" 8 +Deletes the first line and prints the line that was second. +.IP "\fB1delep\fP" 8 +As for +.BR 1dp . +.IP "\fB1d\fP" 8 +Deletes the first line, saving it in buffer +.IR p . +.IP "\fB1d\0p1l\fP" 8 +(Pee-one-ell.) Deletes the first line, saving it in buffer +.IR p , +and listing the line that was second. +.SS "Edit" +.P +Historically, any +.IR ex +command could be entered as a +.BR + \c +.IR command +argument to the +.BR edit +command, although some (for example, +.BR insert +and +.BR append ) +were known to confuse historical implementations. For consistency and +simplicity of specification, POSIX.1\(hy2008 requires that any command be +supported as an argument to the +.BR edit +command. +.P +Historically, the command argument was executed with the current line +set to the last line of the file, regardless of whether the +.BR edit +command was executed from visual mode or not. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historically, the +.BR + \c +.IR command +specified to the +.BR edit +and +.BR next +commands was delimited by the first +, +and there was no way to quote them. For consistency, POSIX.1\(hy2008 requires +that the usual +.IR ex +backslash quoting be provided. +.P +Historically, specifying the +.BR + \c +.IR command +argument to the edit command required a filename to be specified as +well; for example, +.BR ":edit\0+100" +would always fail. For consistency and simplicity of specification, +POSIX.1\(hy2008 does not permit this usage to fail for that reason. +.P +Historically, only the cursor position of the last file edited was +remembered by the editor. POSIX.1\(hy2008 requires that this be supported; +however, implementations are permitted to remember and restore the +cursor position for any file previously edited. +.SS "File" +.P +Historical versions of the +.IR ex +editor +.BR file +command displayed a current line and number of lines in the edit buffer +of 0 when the file was empty, while the +.IR vi +\(hyG +command displayed a current line and number of lines in the edit buffer +of 1 in the same situation. POSIX.1\(hy2008 does not permit this discrepancy, +instead requiring that a message be displayed indicating that the file +is empty. +.SS "Global" +.P +The two-pass operation of the +.BR global +and +.BR v +commands is not intended to imply implementation, only the required +result of the operation. +.P +The current line and column are set as specified for the individual +.IR ex +commands. This requirement is cumulative; that is, the current line and +column must track across all the commands executed by the +.BR global +or +.BR v +commands. +.SS "Insert" +.P +See the RATIONALE for the +.BR append +command. +.P +Historically, +.BR insert +could not be used with an address of zero; that is, not when the edit +buffer was empty. POSIX.1\(hy2008 requires that this command behave consistently +with the +.BR append +command. +.SS "Join" +.P +The action of the +.BR join +command in relation to the special characters is only defined for the +POSIX locale because the correct amount of white space after a period +varies; in Japanese none is required, in French only a single space, +and so on. +.SS "List" +.P +The historical output of the +.BR list +command was potentially ambiguous. The standard developers believed +correcting this to be more important than adhering to historical +practice, and POSIX.1\(hy2008 requires unambiguous output. +.SS "Map" +.P +Historically, command mode maps only applied to command names; for +example, if the character +.BR 'x' +was mapped to +.BR 'y' , +the command +.BR fx +searched for the +.BR 'x' +character, not the +.BR 'y' +character. POSIX.1\(hy2008 requires this behavior. Historically, entering +\(hyV +as the first character of a +.IR vi +command was an error. Several implementations have extended the +semantics of +.IR vi +such that +\(hyV +means that the subsequent command character is not mapped. This is +permitted, but not required, by POSIX.1\(hy2008. Regardless, using +\(hyV +to escape the second or later character in a sequence of characters +that might match a +.BR map +command, or any character in text input mode, is historical practice, +and stops the entered keys from matching a map. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historical implementations permitted digits to be used as a +.BR map +command +.IR lhs , +but then ignored the map. POSIX.1\(hy2008 requires that the mapped digits not be +ignored. +.P +The historical implementation of the +.BR map +command did not permit +.BR map +commands that were more than a single character in length if the first +character was printable. This behavior is permitted, but not required, +by POSIX.1\(hy2008. +.P +Historically, mapped characters were remapped unless the +.BR remap +edit option was not set, or the prefix of the mapped characters matched +the mapping characters; for example, in the +.BR map : +.sp +.RS 4 +.nf +\fB +:map ab abcd +.fi \fR +.P +.RE +.P +the characters +.BR \(dqab\(dq +were used as is and were not remapped, but the characters +.BR \(dqcd\(dq +were mapped if appropriate. This can cause infinite loops in the +.IR vi +mapping mechanisms. POSIX.1\(hy2008 requires conformance to historical practice, +and that such loops be interruptible. +.P +Text input maps had the same problems with expanding the +.IR lhs +for the +.IR ex +.BR map! +and +.BR unmap! +command as did the +.IR ex +.BR abbreviate +and +.BR unabbreviate +commands. See the RATIONALE for the +.IR ex +.BR abbreviate +command. POSIX.1\(hy2008 requires similar modification of some historical +practice for the +.BR map +and +.BR unmap +commands, as described for the +.BR abbreviate +and +.BR unabbreviate +commands. +.P +Historically, +.BR map s +that were subsets of other +.BR map s +behaved differently depending on the order in which they were defined. +For example: +.sp +.RS 4 +.nf +\fB +:map! ab short +:map! abc long +.fi \fR +.P +.RE +.P +would always translate the characters +.BR \(dqab\(dq +to +.BR \(dqshort\(dq , +regardless of how fast the characters +.BR \(dqabc\(dq +were entered. If the entry order was reversed: +.sp +.RS 4 +.nf +\fB +:map! abc long +:map! ab short +.fi \fR +.P +.RE +.P +the characters +.BR \(dqab\(dq +would cause the editor to pause, waiting for the completing +.BR 'c' +character, and the characters might never be mapped to +.BR \(dqshort\(dq . +For consistency and simplicity of specification, POSIX.1\(hy2008 requires that +the shortest match be used at all times. +.P +The length of time the editor spends waiting for the characters to +complete the +.IR lhs +is unspecified because the timing capabilities of systems are often +inexact and variable, and it may depend on other factors such as the +speed of the connection. The time should be long enough for the user to +be able to complete the sequence, but not long enough for the user to +have to wait. Some implementations of +.IR vi +have added a +.BR keytime +option, which permits users to set the number of 0,1 seconds the editor +waits for the completing characters. Because mapped terminal function +and cursor keys tend to start with an + +character, and + +is the key ending +.IR vi +text input mode, +.BR map s +starting with + +characters are generally exempted from this timeout period, or, at +least timed out differently. +.SS "Mark" +.P +Historically, users were able to set the ``previous context'' marks +explicitly. In addition, the +.IR ex +commands +.BR '' +and +.BR '` +and the +.IR vi +commands +.BR '' , +.BR `` , +.BR `' , +and +.BR '` +all referred to the same mark. In addition, the previous context marks +were not set if the command, with which the address setting the mark +was associated, failed. POSIX.1\(hy2008 requires conformance to historical +practice. Historically, if marked lines were deleted, the mark was also +deleted, but would reappear if the change was undone. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +The description of the special events that set the +.BR ` +and +.BR ' +marks matches historical practice. For example, historically the +command +.BR "/a/,/b/" +did not set the +.BR ` +and +.BR ' +marks, but the command +.BR "/a/,/b/delete" +did. +.SS "Next" +.P +Historically, any +.IR ex +command could be entered as a +.BR + \c +.IR command +argument to the +.BR next +command, although some (for example, +.BR insert +and +.BR append ) +were known to confuse historical implementations. POSIX.1\(hy2008 requires that +any command be permitted and that it behave as specified. The +.BR next +command can accept more than one file, so usage such as: +.sp +.RS 4 +.nf +\fB +next `ls [abc] ` +.fi \fR +.P +.RE +.P +is valid; it need not be valid for the +.BR edit +or +.BR read +commands, for example, because they expect only one filename. +.P +Historically, the +.BR next +command behaved differently from the +.BR :rewind +command in that it ignored the force flag if the +.BR autowrite +flag was set. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR next +command positioned the cursor as if the file had never been edited +before, regardless. POSIX.1\(hy2008 does not permit this behavior, for +consistency with the +.BR edit +command. +.P +Implementations wanting to provide a counterpart to the +.BR next +command that edited the previous file have used the command +.BR prev[ious], +which takes no +.IR file +argument. POSIX.1\(hy2008 does not require this command. +.SS "Open" +.P +Historically, the +.BR open +command would fail if the +.BR open +edit option was not set. POSIX.1\(hy2008 does not mention the +.BR open +edit option and does not require this behavior. Some historical +implementations do not permit entering open mode from open or visual +mode, only from +.IR ex +mode. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, entering open mode from the command line (that is, +.IR vi +.BR +open ) +resulted in anomalous behaviors; for example, the +.IR ex +file and +.IR set +commands, and the +.IR vi +command +\(hyG +did not work. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR open +command only permitted +.BR '/' +characters to be used as the search pattern delimiter. For consistency, +POSIX.1\(hy2008 requires that the search delimiters used by the +.BR s , +.BR global , +and +.BR v +commands be accepted as well. +.SS "Preserve" +.P +The +.BR preserve +command does not historically cause the file to be considered +unmodified for the purposes of future commands that may exit the +editor. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historical documentation stated that mail was not sent to the user when +preserve was executed; however, historical implementations did send +mail in this case. POSIX.1\(hy2008 requires conformance to the historical +implementations. +.SS "Print" +.P +The writing of NUL by the +.BR print +command is not specified as a special case because the standard +developers did not want to require +.IR ex +to support NUL characters. Historically, characters were displayed +using the ARPA standard mappings, which are as follows: +.IP " 1." 4 +Printable characters are left alone. +.IP " 2." 4 +Control characters less than \e177 are represented as +.BR '^' +followed by the character offset from the +.BR '@' +character in the ASCII map; for example, \e007 is represented as +.BR '^G' . +.IP " 3." 4 +\e177 is represented as +.BR '^' +followed by +.BR '?' . +.P +The display of characters having their eighth bit set was less +standard. Existing implementations use hex (0x00), octal (\e000), and a +meta-bit display. (The latter displayed bytes that had their eighth bit +set as the two characters +.BR \(dqM\(mi\(dq +followed by the seven-bit display as described above.) The latter +probably has the best claim to historical practice because it was used +for the +.BR \(miv +option of 4 BSD and 4 BSD-derived versions of the +.IR cat +utility since 1980. +.P +No specific display format is required by POSIX.1\(hy2008. +.P +Explicit dependence on the ASCII character set has been avoided where +possible, hence the use of the phrase an ``implementation-defined +multi-character sequence'' for the display of non-printable characters +in preference to the historical usage of, for instance, +.BR \(dq^I\(dq +for the +. +Implementations are encouraged to conform to historical practice in the +absence of any strong reason to diverge. +.P +Historically, all +.IR ex +commands beginning with the letter +.BR 'p' +could be entered using capitalized versions of the commands; for +example, +.BR P[rint] , +.BR Pre[serve] , +and +.BR Pu[t] +were all valid command names. POSIX.1\(hy2008 permits, but does not require, this +historical practice because capital forms of the commands are used by +some implementations for other purposes. +.SS "Put" +.P +Historically, an +.IR ex +.BR put +command, executed from open or visual mode, was the same as the open or +visual mode +.BR P +command, if the buffer was named and was cut in character mode, and the +same as the +.BR p +command if the buffer was named and cut in line mode. If the unnamed +buffer was the source of the text, the entire line from which the text +was taken was usually +.BR put , +and the buffer was handled as if in line mode, but it was possible to +get extremely anomalous behavior. In addition, using the +.BR Q +command to switch into +.IR ex +mode, and then doing a +.BR put +often resulted in errors as well, such as appending text that was +unrelated to the (supposed) contents of the buffer. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit these behaviors. All +.IR ex +.BR put +commands are required to operate in line mode, and the contents of the +buffers are not altered by changing the mode of the editor. +.SS "Read" +.P +Historically, an +.IR ex +.BR read +command executed from open or visual mode, executed in an empty file, +left an empty line as the first line of the file. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +Historically, a +.BR read +in open or visual mode from a program left the cursor at the last line +read in, not the first. For consistency, POSIX.1\(hy2008 does not permit this +behavior. +.P +Historical implementations of +.IR ex +were unable to undo +.BR read +commands that read from the output of a program. For consistency, POSIX.1\(hy2008 +does not permit this behavior. +.P +Historically, the +.IR ex +and +.IR vi +message after a successful +.BR read +or +.BR write +command specified ``characters'', not ``bytes''. POSIX.1\(hy2008 requires that +the number of bytes be displayed, not the number of characters, because +it may be difficult in multi-byte implementations to determine the +number of characters read. Implementations are encouraged to clarify +the message displayed to the user. +.P +Historically, reads were not permitted on files other than type +regular, except that FIFO files could be read (probably only because +they did not exist when +.IR ex +and +.IR vi +were originally written). Because the historical +.IR ex +evaluated +.BR read! +and +.BR read\0! +equivalently, there can be no optional way to force the read. POSIX.1\(hy2008 +permits, but does not require, this behavior. +.SS "Recover" +.P +Some historical implementations of the editor permitted users to +recover the edit buffer contents from a previous edit session, and then +exit without saving those contents (or explicitly discarding them). The +intent of POSIX.1\(hy2008 in requiring that the edit buffer be treated as already +modified is to prevent this user error. +.SS "Rewind" +.P +Historical implementations supported the +.BR rewind +command when the user was editing the first file in the list; that is, +the file that the +.BR rewind +command would edit. POSIX.1\(hy2008 requires conformance to historical practice. +.SS "Substitute" +.P +Historically, +.IR ex +accepted an +.BR r +option to the +.BR s +command. The effect of the +.BR r +option was to use the last regular expression used in any command as +the pattern, the same as the +.BR ~ +command. The +.BR r +option is not required by POSIX.1\(hy2008. Historically, the +.BR c +and +.BR g +options were toggled; for example, the command +.BR ":s/abc/def/" +was the same as +.BR "s/abc/def/ccccgggg" . +For simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.P +The tilde command is often used to replace the last search RE. For +example, in the sequence: +.sp +.RS 4 +.nf +\fB +s/red/blue/ +/green +~ +.fi \fR +.P +.RE +.P +the +.BR ~ +command is equivalent to: +.sp +.RS 4 +.nf +\fB +s/green/blue/ +.fi \fR +.P +.RE +.P +Historically, +.IR ex +accepted all of the following forms: +.sp +.RS 4 +.nf +\fB +s/abc/def/ +s/abc/def +s/abc/ +s/abc +.fi \fR +.P +.RE +.P +POSIX.1\(hy2008 requires conformance to this historical practice. +.P +The +.BR s +command presumes that the +.BR '^' +character only occupies a single column in the display. Much of the +.IR ex +and +.IR vi +specification presumes that the + +only occupies a single column in the display. There are no known +character sets for which this is not true. +.P +Historically, the final column position for the substitute commands was +based on previous column movements; a search for a pattern followed by +a substitution would leave the column position unchanged, while a 0 +command followed by a substitution would change the column position to +the first non-\c +. +For consistency and simplicity of specification, POSIX.1\(hy2008 requires that +the final column position always be set to the first non-\c +. +.SS "Set" +.P +Historical implementations redisplayed all of the options for each +occurrence of the +.BR all +keyword. POSIX.1\(hy2008 permits, but does not require, this behavior. +.SS "Tag" +.P +No requirement is made as to where +.IR ex +and +.IR vi +shall look for the file referenced by the tag entry. Historical +practice has been to look for the path found in the +.BR tags +file, based on the current directory. A useful extension found in some +implementations is to look based on the directory containing the tags +file that held the entry, as well. No requirement is made as to which +reference for the tag in the tags file is used. This is deliberate, in +order to permit extensions such as multiple entries in a tags file for +a tag. +.P +Because users often specify many different tags files, some of which +need not be relevant or exist at any particular time, POSIX.1\(hy2008 requires +that error messages about problem tags files be displayed only if the +requested tag is not found, and then, only once for each time that the +.BR tag +edit option is changed. +.P +The requirement that the current edit buffer be unmodified is only +necessary if the file indicated by the tag entry is not the same as the +current file (as defined by the current pathname). Historically, the +file would be reloaded if the filename had changed, as well as if the +filename was different from the current pathname. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior, +requiring that the name be the only factor in the decision. +.P +Historically, +.IR vi +only searched for tags in the current file from the current cursor to +the end of the file, and therefore, if the +.BR wrapscan +option was not set, tags occurring before the current cursor were not +found. POSIX.1\(hy2008 considers this a bug, and implementations are required to +search for the first occurrence in the file, regardless. +.SS "Undo" +.P +The +.BR undo +description deliberately uses the word ``modified''. The +.BR undo +command is not intended to undo commands that replace the contents of +the edit buffer, such as +.BR edit , +.BR next , +.BR tag , +or +.BR recover . +.P +Cursor positioning after the +.BR undo +command was inconsistent in the historical +.IR vi , +sometimes attempting to restore the original cursor position (\c +.BR global , +.BR undo , +and +.BR v +commands), and sometimes, in the presence of maps, placing the cursor +on the last line added or changed instead of the first. POSIX.1\(hy2008 requires +a simplified behavior for consistency and simplicity of specification. +.SS "Version" +.P +The +.BR version +command cannot be exactly specified since there is no widely-accepted +definition of what the version information should contain. +Implementations are encouraged to do something reasonably intelligent. +.SS "Write" +.P +Historically, the +.IR ex +and +.IR vi +message after a successful +.BR read +or +.BR write +command specified ``characters'', not ``bytes''. POSIX.1\(hy2008 requires that +the number of bytes be displayed, not the number of characters because +it may be difficult in multi-byte implementations to determine the +number of characters written. Implementations are encouraged to clarify +the message displayed to the user. +.P +Implementation-defined tests are permitted so that implementations +can make additional checks; for example, for locks or file modification +times. +.P +Historically, attempting to append to a nonexistent file caused an +error. It has been left unspecified in POSIX.1\(hy2008 to permit implementations +to let the +.BR write +succeed, so that the append semantics are similar to those of the +historical +.IR csh . +.P +Historical +.IR vi +permitted empty edit buffers to be written. However, since the way +.IR vi +got around dealing with ``empty'' files was to always have a line in +the edit buffer, no matter what, it wrote them as files of a single, +empty line. POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, +.IR ex +restored standard output and standard error to their values as of when +.IR ex +was invoked, before writes to programs were performed. This could +disturb the terminal configuration as well as be a security issue for +some terminals. POSIX.1\(hy2008 does not permit this, requiring that the program +output be captured and displayed as if by the +.IR ex +.BR print +command. +.SS "Adjust Window" +.P +Historically, the line count was set to the value of the +.BR scroll +option if the type character was end-of-file. This feature was broken +on most historical implementations long ago, however, and is not +documented anywhere. For this reason, POSIX.1\(hy2008 is resolutely silent. +.P +Historically, the +.BR z +command was +-sensitive +and +.BR z\0+ +and +.BR z\0\(mi +did different things than +.BR z+ +and +.BR z\(mi +because the type could not be distinguished from a flag. (The commands +.BR z\0. +and +.BR z\0= +were historically invalid.) POSIX.1\(hy2008 requires conformance to this +historical practice. +.P +Historically, the +.BR z +command was further +-sensitive +in that the +.IR count +could not be +-delimited; +for example, the commands +.BR z=\05 +and +.BR z\(mi\05 +were also invalid. Because the +.IR count +is not ambiguous with respect to either the type character or the +flags, this is not permitted by POSIX.1\(hy2008. +.SS "Escape" +.P +Historically, +.IR ex +filter commands only read the standard output of the commands, letting +standard error appear on the terminal as usual. The +.IR vi +utility, however, read both standard output and standard error. POSIX.1\(hy2008 +requires the latter behavior for both +.IR ex +and +.IR vi , +for consistency. +.SS "Shift Left and Shift Right" +.P +Historically, it was possible to add shift characters to increase the +effect of the command; for example, +.BR <<< +outdented (or +.BR >>> +indented) the lines 3 levels of indentation instead of the default 1. +POSIX.1\(hy2008 requires conformance to historical practice. +.SS "\(hyD" +.P +Historically, the +\(hyD +command erased the prompt, providing the user with an unbroken +presentation of lines from the edit buffer. This is not required by +POSIX.1\(hy2008; implementations are encouraged to provide it if possible. +Historically, the +\(hyD +command took, and then ignored, a +.IR count . +POSIX.1\(hy2008 does not permit this behavior. +.SS "Write Line Number" +.P +Historically, the +.IR ex +.BR = +command, when executed in +.IR ex +mode in an empty edit buffer, reported 0, and from open or visual mode, +reported 1. For consistency and simplicity of specification, POSIX.1\(hy2008 does +not permit this behavior. +.SS "Execute" +.P +Historically, +.IR ex +did not correctly handle the inclusion of text input commands (that is, +.BR append , +.BR insert , +and +.BR change ) +in executed buffers. POSIX.1\(hy2008 does not permit this exclusion for +consistency. +.P +Historically, the logical contents of the buffer being executed did not +change if the buffer itself were modified by the commands being +executed; that is, buffer execution did not support self-modifying +code. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR @ +command took a range of lines, and the +.BR @ +buffer was executed once per line, with the current line (\c +.BR '.' ) +set to each specified line. POSIX.1\(hy2008 requires conformance to historical +practice. +.P +Some historical implementations did not notice if errors occurred +during buffer execution. This, coupled with the ability to specify a +range of lines for the +.IR ex +.BR @ +command, makes it trivial to cause them to drop +.BR core . +POSIX.1\(hy2008 requires that implementations stop buffer execution if any error +occurs, if the specified line doesn't exist, or if the contents of the +edit buffer itself are replaced (for example, the buffer executes the +.IR ex +.BR :edit +command). +.SS "Regular Expressions in ex" +.P +Historical practice is that the characters in the replacement part of +the last +.BR s +command\(emthat is, those matched by entering a +.BR '~' +in the regular expression\(emwere not further expanded by the regular +expression engine. So, if the characters contained the string +.BR \(dqa.,\(dq +they would match +.BR 'a' +followed by +.BR \(dq.,\(dq +and not +.BR 'a' +followed by any character. POSIX.1\(hy2008 requires conformance to historical +practice. +.SS "Edit Options in ex" +.P +The following paragraphs describe the historical behavior of some edit +options that were not, for whatever reason, included in POSIX.1\(hy2008. +Implementations are strongly encouraged to only use these names if the +functionality described here is fully supported. +.IP "\fBextended\fP" 10 +The +.BR extended +edit option has been used in some implementations of +.IR vi +to provide extended regular expressions instead of basic regular +expressions This option was omitted from POSIX.1\(hy2008 because it is not +widespread historical practice. +.IP "\fBflash\fP" 10 +The +.BR flash +edit option historically caused the screen to flash instead of beeping +on error. This option was omitted from POSIX.1\(hy2008 because it is not found in +some historical implementations. +.IP "\fBhardtabs\fP" 10 +The +.BR hardtabs +edit option historically defined the number of columns between hardware +tab settings. This option was omitted from POSIX.1\(hy2008 because it was +believed to no longer be generally useful. +.IP "\fBmodeline\fP" 10 +The +.BR modeline +(sometimes named +.BR modelines ) +edit option historically caused +.IR ex +or +.IR vi +to read the five first and last lines of the file for editor commands. +This option is a security problem, and vendors are strongly encouraged +to delete it from historical implementations. +.IP "\fBopen\fP" 10 +The +.BR open +edit option historically disallowed the +.IR ex +.BR open +and +.BR visual +commands. This edit option was omitted because these commands are +required by POSIX.1\(hy2008. +.IP "\fBoptimize\fP" 10 +The +.BR optimize +edit option historically expedited text throughput by setting the +terminal to not do automatic + +characters when printing more than one logical line of output. This +option was omitted from POSIX.1\(hy2008 because it was intended for terminals +without addressable cursors, which are rarely, if ever, still used. +.IP "\fBruler\fP" 10 +The +.BR ruler +edit option has been used in some implementations of +.IR vi +to present a current row/column ruler for the user. This option was +omitted from POSIX.1\(hy2008 because it is not widespread historical practice. +.IP "\fBsourceany\fP" 10 +The +.BR sourceany +edit option historically caused +.IR ex +or +.IR vi +to source start-up files that were owned by users other than the user +running the editor. This option is a security problem, and vendors are +strongly encouraged to remove it from their implementations. +.IP "\fBtimeout\fP" 10 +The +.BR timeout +edit option historically enabled the (now standard) feature of only +waiting for a short period before returning keys that could be part of +a macro. This feature was omitted from POSIX.1\(hy2008 because its behavior is +now standard, it is not widely useful, and it was rarely documented. +.IP "\fBverbose\fP" 10 +The +.BR verbose +edit option has been used in some implementations of +.IR vi +to cause +.IR vi +to output error messages for common errors; for example, attempting to +move the cursor past the beginning or end of the line instead of only +alerting the screen. (The historical +.IR vi +only alerted the terminal and presented no message for such errors. The +historical editor option +.BR terse +did not select when to present error messages, it only made existing +error messages more or less verbose.) This option was omitted from +POSIX.1\(hy2008 because it is not widespread historical practice; however, +implementors are encouraged to use it if they wish to provide error +messages for naive users. +.IP "\fBwraplen\fP" 10 +The +.BR wraplen +edit option has been used in some implementations of +.IR vi +to specify an automatic margin measured from the left margin instead of +from the right margin. This is useful when multiple screen sizes are +being used to edit a single file. This option was omitted from POSIX.1\(hy2008 +because it is not widespread historical practice; however, implementors +are encouraged to use it if they add this functionality. +.SS "autoindent, ai" +.P +Historically, the command +.BR 0a +did not do any autoindentation, regardless of the current indentation +of line 1. POSIX.1\(hy2008 requires that any indentation present in line 1 be +used. +.SS "autoprint, ap" +.P +Historically, the +.BR autoprint +edit option was not completely consistent or based solely on +modifications to the edit buffer. Exceptions were the +.BR read +command (when reading from a file, but not from a filter), the +.BR append , +.BR change , +.BR insert , +.BR global , +and +.BR v +commands, all of which were not affected by +.BR autoprint , +and the +.BR tag +command, which was affected by +.BR autoprint . +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR autoprint +option only applied to the last of multiple commands entered using + +delimiters; for example, +.BR delete + +was affected by +.BR autoprint , +but +.BR delete|version + +was not. POSIX.1\(hy2008 requires conformance to historical practice. +.SS "autowrite, aw" +.P +Appending the +.BR '!' +character to the +.IR ex +.BR next +command to avoid performing an automatic write was not supported in +historical implementations. POSIX.1\(hy2008 requires that the behavior match the +other +.IR ex +commands for consistency. +.SS "ignorecase, ic" +.P +Historical implementations of case-insensitive matching (the +.BR ignorecase +edit option) lead to counter-intuitive situations when uppercase +characters were used in range expressions. Historically, the process +was as follows: +.IP " 1." 4 +Take a line of text from the edit buffer. +.IP " 2." 4 +Convert uppercase to lowercase in text line. +.IP " 3." 4 +Convert uppercase to lowercase in regular expressions, except in +character class specifications. +.IP " 4." 4 +Match regular expressions against text. +.P +This would mean that, with +.BR ignorecase +in effect, the text: +.sp +.RS 4 +.nf +\fB +The cat sat on the mat +.fi \fR +.P +.RE +.P +would be matched by +.sp +.RS 4 +.nf +\fB +/^the/ +.fi \fR +.P +.RE +.P +but not by: +.sp +.RS 4 +.nf +\fB +/^[A\(miZ]he/ +.fi \fR +.P +.RE +.P +For consistency with other commands implementing regular expressions, +POSIX.1\(hy2008 does not permit this behavior. +.SS "paragraphs, para" +.P +The ISO\ POSIX\(hy2:\|1993 standard made the default +.BR paragraphs +and +.BR sections +edit options implementation-defined, arguing they were historically +oriented to the UNIX system +.IR troff +text formatter, and a ``portable user'' could use the +.BR { , +.BR } , +.BR [[ , +.BR ]] , +.BR ( , +and +.BR ) +commands in open or visual mode and have the cursor stop in unexpected +places. POSIX.1\(hy2008 specifies their values in the POSIX locale because the +unusual grouping (they only work when grouped into two characters at a +time) means that they cannot be used for general-purpose movement, +regardless. +.SS "readonly" +.P +Implementations are encouraged to provide the best possible information +to the user as to the read-only status of the file, with the exception +that they should not consider the current special privileges of the +process. This provides users with a safety net because they must force +the overwrite of read-only files, even when running with additional +privileges. +.P +The +.BR readonly +edit option specification largely conforms to historical practice. The +only difference is that historical implementations did not notice that +the user had set the +.BR readonly +edit option in cases where the file was already marked read-only for +some reason, and would therefore reinitialize the +.BR readonly +edit option the next time the contents of the edit buffer were +replaced. This behavior is disallowed by POSIX.1\(hy2008. +.SS "report" +.P +The requirement that lines copied to a buffer interact differently than +deleted lines is historical practice. For example, if the +.BR report +edit option is set to 3, deleting 3 lines will cause a report to be +written, but 4 lines must be copied before a report is written. +.P +The requirement that the +.IR ex +.BR global , +.BR v , +.BR open , +.BR undo , +and +.BR visual +commands present reports based on the total number of lines added or +deleted during the command execution, and that commands executed by the +.BR global +and +.BR v +commands not present reports, is historical practice. POSIX.1\(hy2008 extends +historical practice by requiring that buffer execution be treated +similarly. The reasons for this are two-fold. Historically, only the +report by the last command executed from the buffer would be seen by +the user, as each new report would overwrite the last. In addition, the +standard developers believed that buffer execution had more in common +with +.BR global +and +.BR v +commands than it did with other +.IR ex +commands, and should behave similarly, for consistency and simplicity +of specification. +.SS "showmatch, sm" +.P +The length of time the cursor spends on the matching character is +unspecified because the timing capabilities of systems are often +inexact and variable. The time should be long enough for the user to +notice, but not long enough for the user to become annoyed. Some +implementations of +.IR vi +have added a +.BR matchtime +option that permits users to set the number of 0,1 second intervals the +cursor pauses on the matching character. +.SS "showmode" +.P +The +.BR showmode +option has been used in some historical implementations of +.IR ex +and +.IR vi +to display the current editing mode when in open or visual mode. The +editing modes have generally included ``command'' and ``input'', and +sometimes other modes such as ``replace'' and ``change''. The string +was usually displayed on the bottom line of the screen at the far +right-hand corner. In addition, a preceding +.BR '*' +character often denoted whether the contents of the edit buffer had +been modified. The latter display has sometimes been part of the +.BR showmode +option, and sometimes based on another option. This option was not +available in the 4 BSD historical implementation of +.IR vi , +but was viewed as generally useful, particularly to novice users, and +is required by POSIX.1\(hy2008. +.P +The +.BR smd +shorthand for the +.BR showmode +option was not present in all historical implementations of the editor. +POSIX.1\(hy2008 requires it, for consistency. +.P +Not all historical implementations of the editor displayed a mode +string for command mode, differentiating command mode from text input +mode by the absence of a mode string. POSIX.1\(hy2008 permits this behavior for +consistency with historical practice, but implementations are +encouraged to provide a display string for both modes. +.SS "slowopen" +.P +Historically, the +.BR slowopen +option was automatically set if the terminal baud rate was less than +1\|200 baud, or if the baud rate was 1\|200 baud and the +.BR redraw +option was not set. The +.BR slowopen +option had two effects. First, when inserting characters in the middle +of a line, characters after the cursor would not be pushed ahead, but +would appear to be overwritten. Second, when creating a new line of +text, lines after the current line would not be scrolled down, but +would appear to be overwritten. In both cases, ending text input mode +would cause the screen to be refreshed to match the actual contents of +the edit buffer. Finally, terminals that were sufficiently intelligent +caused the editor to ignore the +.BR slowopen +option. POSIX.1\(hy2008 permits most historical behavior, extending historical +practice to require +.BR slowopen +behaviors if the edit option is set by the user. +.SS "tags" +.P +The default path for tags files is left unspecified as implementations +may have their own +.BR tags +implementations that do not correspond to the historical ones. The +default +.BR tags +option value should probably at least include the file +.BR ./tags . +.SS "term" +.P +Historical implementations of +.IR ex +and +.IR vi +ignored changes to the +.BR term +edit option after the initial terminal information was loaded. This is +permitted by POSIX.1\(hy2008; however, implementations are encouraged to permit +the user to modify their terminal type at any time. +.SS "terse" +.P +Historically, the +.BR terse +edit option optionally provided a shorter, less descriptive error +message, for some error messages. This is permitted, but not required, +by POSIX.1\(hy2008. Historically, most common visual mode errors (for example, +trying to move the cursor past the end of a line) did not result in an +error message, but simply alerted the terminal. Implementations wishing +to provide messages for novice users are urged to do so based on the +.BR edit +option +.BR verbose , +and not +.BR terse . +.SS "window" +.P +In historical implementations, the default for the +.BR window +edit option was based on the baud rate as follows: +.IP " 1." 4 +If the baud rate was less than 1\|200, the +.BR edit +option +.BR w300 +set the window value; for example, the line: +.RS 4 +.sp +.RS 4 +.nf +\fB +set w300=12 +.fi \fR +.P +.RE +.P +would set the window option to 12 if the baud rate was less than +1\|200. +.RE +.IP " 2." 4 +If the baud rate was equal to 1\|200, the +.BR edit +option +.BR w1200 +set the window value. +.IP " 3." 4 +If the baud rate was greater than 1\|200, the +.BR edit +option +.BR w9600 +set the window value. +.P +The +.BR w300 , +.BR w1200 , +and +.BR w9600 +options do not appear in POSIX.1\(hy2008 because of their dependence on specific +baud rates. +.P +In historical implementations, the size of the window displayed by +various commands was related to, but not necessarily the same as, the +.BR window +edit option. For example, the size of the window was set by the +.IR ex +command +.BR "visual 10" , +but it did not change the value of the +.BR window +edit option. However, changing the value of the +.BR window +edit option did change the number of lines that were displayed when the +screen was repainted. POSIX.1\(hy2008 does not permit this behavior in the +interests of consistency and simplicity of specification, and requires +that all commands that change the number of lines that are displayed do +it by setting the value of the +.BR window +edit option. +.SS "wrapmargin, wm" +.P +Historically, the +.BR wrapmargin +option did not affect maps inserting characters that also had +associated +.IR count s; +for example +.BR ":map\0K\05aABC\0DEF" . +Unfortunately, there are widely used maps that depend on this behavior. +For consistency and simplicity of specification, POSIX.1\(hy2008 does not permit +this behavior. +.P +Historically, +.BR wrapmargin +was calculated using the column display width of all characters on the +screen. For example, an implementation using +.BR \(dq^I\(dq +to represent + +characters when the +.BR list +edit option was set, where +.BR '^' +and +.BR 'I' +each took up a single column on the screen, would calculate the +.BR wrapmargin +based on a value of 2 for each +. +The +.BR number +edit option similarly changed the effective length of the line as well. +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Earlier versions of this standard allowed for implementations +with bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +.IR "\fIctags\fR\^", +.IR "\fIed\fR\^", +.IR "\fIsed\fR\^", +.IR "\fIsh\fR\^", +.IR "\fIstty\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaccess\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/exec.1p b/man-pages-posix-2013-a/man1p/exec.1p new file mode 100644 index 0000000..9b6c976 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/exec.1p @@ -0,0 +1,184 @@ +'\" et +.TH EXEC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +exec +\(em execute commands and open, close, or copy file descriptors +.SH SYNOPSIS +.LP +.nf +exec \fB[\fIcommand \fB[\fIargument\fR...\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR exec +utility shall open, close, and/or copy file descriptors as specified by +any redirections as part of the command. +.P +If +.IR exec +is specified without +.IR command +or +.IR argument s, +and any file descriptors with numbers greater than 2 are opened with +associated redirection statements, it is unspecified whether those file +descriptors remain open when the shell invokes another utility. +Scripts concerned that child shells could misuse open file descriptors +can always close them explicitly, as shown in one of the following +examples. +.P +If +.IR exec +is specified with +.IR command , +it shall replace the shell with +.IR command +without creating a new process. If +.IR argument s +are specified, they shall be arguments to +.IR command . +Redirection affects the current shell execution environment. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If +.IR command +is specified, +.IR exec +shall not return to the shell; rather, the exit status of the process +shall be the exit status of the program implementing +.IR command , +which overlaid the shell. If +.IR command +is not found, the exit status shall be 127. If +.IR command +is found, but it is not an executable utility, the exit status shall be +126. If a redirection error occurs (see +.IR "Section 2.8.1" ", " "Consequences of Shell Errors"), +the shell shall exit with a value in the range 1\(mi125. Otherwise, +.IR exec +shall return a zero exit status. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Open +.IR readfile +as file descriptor 3 for reading: +.sp +.RS 4 +.nf +\fB +exec 3< readfile +.fi \fR +.P +.RE +.P +Open +.IR writefile +as file descriptor 4 for writing: +.sp +.RS 4 +.nf +\fB +exec 4> writefile +.fi \fR +.P +.RE +.P +Make file descriptor 5 a copy of file descriptor 0: +.sp +.RS 4 +.nf +\fB +exec 5<&0 +.fi \fR +.P +.RE +.P +Close file descriptor 3: +.sp +.RS 4 +.nf +\fB +exec 3<&\(mi +.fi \fR +.P +.RE +.P +Cat the file +.BR maggie +by replacing the current shell with the +.IR cat +utility: +.sp +.RS 4 +.nf +\fB +exec cat maggie +.fi \fR +.P +.RE +.SH "RATIONALE" +Most historical implementations were not conformant in that: +.sp +.RS 4 +.nf +\fB +foo=bar exec cmd +.fi \fR +.P +.RE +.P +did not pass +.BR foo +to +.BR cmd . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/exit.1p b/man-pages-posix-2013-a/man1p/exit.1p new file mode 100644 index 0000000..28ebb68 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/exit.1p @@ -0,0 +1,129 @@ +'\" et +.TH EXIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +exit +\(em cause the shell to exit +.SH SYNOPSIS +.LP +.nf +exit \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The +.IR exit +utility shall cause the shell to exit with the exit status specified +by the unsigned decimal integer +.IR n . +If +.IR n +is specified, but its value is not between 0 and 255 inclusively, the +exit status is undefined. +.P +A +.IR trap +on +.BR EXIT +shall be executed before the shell terminates, except when the +.IR exit +utility is invoked in that +.IR trap +itself, in which case the shell shall exit immediately. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The exit status shall be +.IR n , +if specified. Otherwise, the value shall be the exit value of the last +command executed, or zero if no command was executed. When +.IR exit +is executed in a +.IR trap +action, the last command is considered to be the command that executed +immediately preceding the +.IR trap +action. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Exit with a +.IR true +value: +.sp +.RS 4 +.nf +\fB +exit 0 +.fi \fR +.P +.RE +.P +Exit with a +.IR false +value: +.sp +.RS 4 +.nf +\fB +exit 1 +.fi \fR +.P +.RE +.SH "RATIONALE" +As explained in other sections, certain exit status values have been +reserved for special uses and should be used by applications only for +those purposes: +.IP "\0126" 8 +A file to be executed was found, but it was not an executable utility. +.IP "\0127" 8 +A utility to be executed was not found. +.IP >128 8 +A command was interrupted by a signal. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/expand.1p b/man-pages-posix-2013-a/man1p/expand.1p new file mode 100644 index 0000000..6b4e2aa --- /dev/null +++ b/man-pages-posix-2013-a/man1p/expand.1p @@ -0,0 +1,205 @@ +'\" et +.TH EXPAND "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +expand +\(em convert tabs to spaces +.SH SYNOPSIS +.LP +.nf +expand \fB[\fR\(mit \fItablist\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR expand +utility shall write files or the standard input to the standard output +with + +characters replaced with one or more + +characters needed to pad to the next tab stop. Any + +characters shall be copied to the output and cause the column position +count for tab stop calculations to be decremented; the column position +count shall not be decremented below zero. +.SH OPTIONS +The +.IR expand +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mit\ \fItablist\fR" 10 +Specify the tab stops. The application shall ensure that the argument +.IR tablist +consists of either a single positive decimal integer or a list of +tabstops. If a single number is given, tabs shall be set that number of +column positions apart instead of the default 8. +.RS 10 +.P +If a list of tabstops is given, the application shall ensure that it +consists of a list of two or more positive decimal integers, separated +by + +or + +characters, in ascending order. The + +characters shall be set at those specific column positions. Each tab stop +.IR N +shall be an integer value greater than zero, and the list is in +strictly ascending order. This is taken to mean that, from the start of +a line of output, tabbing to position +.IR N +shall cause the next character output to be in the (\c +.IR N +1)th +column position on that line. +.P +In the event of +.IR expand +having to process a + +at a position beyond the last of those specified in a multiple tab-stop +list, the + +shall be replaced by a single + +in the output. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a text file to be used as input. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR expand : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the processing of + +and + +characters, and for the determination of the width in column positions +each character would occupy on an output device. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be equivalent to the input files with + +characters converted into the appropriate number of + +characters. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The +.IR expand +utility shall terminate with an error message and non-zero exit status +upon encountering difficulties accessing one of the +.IR file +operands. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR expand +utility is useful for preprocessing text files (before sorting, looking +at specific columns, and so on) that contain + +characters. +.P +See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.103" ", " "Column Position". +.P +The +.IR tablist +option-argument consists of integers in ascending order. Utility Syntax +Guideline 8 mandates that +.IR expand +shall accept the integers (within the single argument) separated using +either + +or + +characters. +.P +Earlier versions of this standard allowed the following form in +the SYNOPSIS: +.sp +.RS 4 +.nf +\fB +expand \fB[\fR\(mitabstop\fB][\fR\(mitab1,tab2,...,tabn\fB][\fIfile\fR ...\fB]\fR +.fi \fR +.P +.RE +.P +This form is no longer specified by POSIX.1\(hy2008 but may be present +in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItabs\fR\^", +.IR "\fIunexpand\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.103" ", " "Column Position", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/export.1p b/man-pages-posix-2013-a/man1p/export.1p new file mode 100644 index 0000000..d9b6094 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/export.1p @@ -0,0 +1,191 @@ +'\" et +.TH EXPORT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +export +\(em set the export attribute for variables +.SH SYNOPSIS +.LP +.nf +export name\fB[\fR=\fIword\fB]\fR... +.P +export\fR \(mip +.fi +.SH DESCRIPTION +The shell shall give the +.IR export +attribute to the variables corresponding to the specified +.IR name s, +which shall cause them to be in the environment of subsequently +executed commands. If the name of a variable is followed by =\c +.IR word , +then the value of that variable shall be set to +.IR word . +.P +The +.IR export +special built-in shall support the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +When +.BR \(mip +is specified, +.IR export +shall write to the standard output the names and values of all exported +variables, in the following format: +.sp +.RS 4 +.nf +\fB +"export %s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +if +.IR name +is set, and: +.sp +.RS 4 +.nf +\fB +"export %s\en", <\fIname\fR> +.fi \fR +.P +.RE +.P +if +.IR name +is unset. +.P +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as commands that +achieve the same exporting results, except: +.IP " 1." 4 +Read-only variables with values cannot be reset. +.IP " 2." 4 +Variables that were unset at the time they were output need not be +reset to the unset state if a value is assigned to the variable between +the time the state was saved and the time at which the saved output is +reinput to the shell. +.P +When no arguments are given, the results are unspecified. If a variable +assignment precedes the command name of +.IR export +but that variable is not also listed as an operand of +.IR export , +then that variable shall be set in the current shell execution environment +after the completion of the +.IR export +command, but it is unspecified whether that variable is marked for export. +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR S +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Export +.IR PWD +and +.IR HOME +variables: +.sp +.RS 4 +.nf +\fB +export PWD HOME +.fi \fR +.P +.RE +.P +Set and export the +.IR PATH +variable: +.sp +.RS 4 +.nf +\fB +export PATH=/local/bin:$PATH +.fi \fR +.P +.RE +.P +Save and restore all exported variables: +.sp +.RS 4 +.nf +\fB +export \(mip > \fItemp-file\fR +unset \fIa lot of variables\fR +\&... \fIprocessing\fR +\&. \fItemp-file\fR +.fi \fR +.P +.RE +.SH "RATIONALE" +Some historical shells use the no-argument case as the functional +equivalent of what is required here with +.BR \(mip . +This feature was left unspecified because it is not historical practice +in all shells, and some scripts may rely on the now-unspecified results +on their implementations. Attempts to specify the +.BR \(mip +output as the default case were unsuccessful in achieving consensus. +The +.BR \(mip +option was added to allow portable access to the values that can be +saved and then later restored using; for example, a +.IR dot +script. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/expr.1p b/man-pages-posix-2013-a/man1p/expr.1p new file mode 100644 index 0000000..a0be688 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/expr.1p @@ -0,0 +1,440 @@ +'\" et +.TH EXPR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +expr +\(em evaluate arguments as an expression +.SH SYNOPSIS +.LP +.nf +expr \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR expr +utility shall evaluate an expression and write the result to standard +output. +.SH OPTIONS +None. +.SH OPERANDS +The single expression evaluated by +.IR expr +shall be formed from the +.IR operand +operands, as described in the EXTENDED DESCRIPTION section. The +application shall ensure that each of the expression operator symbols: +.sp +.RS 4 +.nf +\fB +( ) | & = > >= < <= != + \(mi * / % : +.fi \fR +.P +.RE +.P +and the symbols +.IR integer +and +.IR string +in the table are provided as separate arguments to +.IR expr . +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR expr : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions and +by the string comparison operators. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments) and the behavior of character +classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR expr +utility shall evaluate the expression and write the result, followed by +a +, +to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The formation of the expression to be evaluated is shown in the +following table. The symbols +.IR expr , +.IR expr1 , +and +.IR expr2 +represent expressions formed from +.IR integer +and +.IR string +symbols and the expression operator symbols (all separate arguments) by +recursive application of the constructs described in the table. The +expressions are listed in order of increasing precedence, with +equal-precedence operators grouped between horizontal lines. All of +the operators shall be left-associative. +.TS +center tab(@) box; +cB | cB +l | lw(4i). +Expression@Description +_ +\fIexpr1\fP\ |\ \fIexpr2\fP@T{ +Returns the evaluation of +.IR expr1 +if it is neither null nor zero; otherwise, returns the evaluation of +.IR expr2 +if it is not null; otherwise, zero. +T} +_ +\fIexpr1\fP\ &\ \fIexpr2\fP@T{ +Returns the evaluation of +.IR expr1 +if neither expression evaluates to null or zero; otherwise, returns zero. +T} +_ +@T{ +Returns the result of a decimal integer comparison if both arguments +are integers; otherwise, returns the result of a string comparison +using the locale-specific collation sequence. The result of each +comparison is 1 if the specified relationship is true, or 0 if the +relationship is false. +T} +\fIexpr1\fP\ =\ \fIexpr2\fR@Equal. +\fIexpr1\fP\ >\ \fIexpr2\fR@Greater than. +\fIexpr1\fP\ >=\ \fIexpr2\fR@Greater than or equal. +\fIexpr1\fP\ <\ \fIexpr2\fR@Less than. +\fIexpr1\fP\ <=\ \fIexpr2\fR@Less than or equal. +\fIexpr1\fP\ !=\ \fIexpr2\fR@Not equal. +_ +\fIexpr1\fP\ +\ \fIexpr2\fP@T{ +Addition of decimal integer-valued arguments. +T} +\fIexpr1\fP\ \(mi\ \fIexpr2\fP@T{ +Subtraction of decimal integer-valued arguments. +T} +_ +\fIexpr1\fP\ *\ \fIexpr2\fP@T{ +Multiplication of decimal integer-valued arguments. +T} +\fIexpr1\fP\ /\ \fIexpr2\fP@T{ +Integer division of decimal integer-valued arguments, producing +an integer result. +T} +\fIexpr1\fP\ %\ \fIexpr2\fP@T{ +Remainder of integer division of decimal integer-valued arguments. +T} +_ +\fIexpr1\fP\ :\ \fIexpr2\fP@T{ +Matching expression; see below. +T} +_ +(\ \fIexpr\fR\ )@T{ +Grouping symbols. Any expression can be placed within parentheses. +Parentheses can be nested to a depth of +{EXPR_NEST_MAX}. +T} +_ +\fIinteger\fP@T{ +An argument consisting only of an (optional) unary minus followed +by digits. +T} +\fIstring\fP@T{ +A string argument; see below. +T} +.TE +.SS "Matching Expression" +.P +The +.BR ':' +matching operator shall compare the string resulting from the +evaluation of +.IR expr1 +with the regular expression pattern resulting from the evaluation of +.IR expr2 . +Regular expression syntax shall be that defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions", +except that all patterns are anchored to the beginning of the string (that +is, only sequences starting at the first character of a string are matched +by the regular expression) and, therefore, it is unspecified whether +.BR '^' +is a special character in that context. Usually, the matching operator +shall return a string representing the number of characters matched (\c +.BR '0' +on failure). Alternatively, if the pattern contains at least one +regular expression subexpression +.BR \(dq[\e(...\e)]\(dq , +the string matched by the back-reference expression +.BR \(dq\e1\(dq +shall be returned. If the back-reference expression +.BR \(dq\e1\(dq +does not match, then the null string shall be returned. +.SS "String Operand" +.P +A string argument is an argument that cannot be identified as an +.IR integer +argument or as one of the expression operator symbols shown in the +OPERANDS section. +.P +The use of string arguments +.BR length , +.BR substr , +.BR index , +or +.BR match +produces unspecified results. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The +.IR expression +evaluates to neither null nor zero. +.IP "\01" 6 +The +.IR expression +evaluates to null or zero. +.IP "\02" 6 +Invalid +.IR expression . +.IP >2 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +After argument processing by the shell, +.IR expr +is not required to be able to tell the difference between an operator +and an operand except by the value. If +.BR \(dq$a\(dq +is +.BR '=' , +the command: +.sp +.RS 4 +.nf +\fB +expr $a = '=' +.fi \fR +.P +.RE +.P +looks like: +.sp +.RS 4 +.nf +\fB +expr = = = +.fi \fR +.P +.RE +.P +as the arguments are passed to +.IR expr +(and they all may be taken as the +.BR '=' +operator). The following works reliably: +.sp +.RS 4 +.nf +\fB +expr X$a = X= +.fi \fR +.P +.RE +.P +Also note that this volume of POSIX.1\(hy2008 permits implementations to extend utilities. The +.IR expr +utility permits the integer arguments to be preceded with a unary +minus. This means that an integer argument could look like an option. +Therefore, the conforming application must employ the +.BR \(dq\(mi\|\(mi\(dq +construct of Guideline 10 of the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +to protect its operands if there is any chance the first operand might +be a negative integer (or any string with a leading minus). +.br +.SH EXAMPLES +The +.IR expr +utility has a rather difficult syntax: +.IP " *" 4 +Many of the operators are also shell control operators or reserved +words, so they have to be escaped on the command line. +.IP " *" 4 +Each part of the expression is composed of separate arguments, so +liberal usage of + +characters is required. For example: +.TS +center tab(@) box; +cB | cB +lf5 | lf5. +Invalid@Valid +_ +\fIexpr\fP 1+2@\fIexpr\fP 1 + 2 +\fIexpr\fP "1 + 2"@\fIexpr\fP 1 + 2 +\fIexpr\fP 1 + (2 * 3)@\fIexpr\fP 1 + \e( 2 \e* 3 \e) +.TE +.P +In many cases, the arithmetic and string features provided as part of +the shell command language are easier to use than their equivalents in +.IR expr . +Newly written scripts should avoid +.IR expr +in favor of the new features within the shell; see +.IR "Section 2.5" ", " "Parameters and Variables" +and +.IR "Section 2.6.4" ", " "Arithmetic Expansion". +.P +The following command: +.sp +.RS 4 +.nf +\fB +a=$(expr $a + 1) +.fi \fR +.P +.RE +.P +adds 1 to the variable +.IR a . +.P +The following command, for +.BR \(dq$a\(dq +equal to either +.BR /usr/abc/file +or just +.BR file : +.sp +.RS 4 +.nf +\fB +expr $a : '.*/\e(.*\e)' \e| $a +.fi \fR +.P +.RE +.P +returns the last segment of a pathname (that is, +.BR file ). +Applications should avoid the character +.BR '/' +used alone as an argument; +.IR expr +may interpret it as the division operator. +.P +The following command: +.sp +.RS 4 +.nf +\fB +expr "//$a" : '.*/\e(.*\e)' +.fi \fR +.P +.RE +.P +is a better representation of the previous example. The addition of +the +.BR \(dq//\(dq +characters eliminates any ambiguity about the division operator and +simplifies the whole expression. Also note that pathnames may contain +characters contained in the +.IR IFS +variable and should be quoted to avoid having +.BR \(dq$a\(dq +expand into multiple arguments. +.P +The following command: +.sp +.RS 4 +.nf +\fB +expr "$VAR" : '.*' +.fi \fR +.P +.RE +.P +returns the number of characters in +.IR VAR . +.SH RATIONALE +In an early proposal, EREs were used in the matching expression syntax. +This was changed to BREs to avoid breaking historical applications. +.P +The use of a leading + +in the BRE is unspecified because many historical implementations have +treated it as a special character, despite their system documentation. For +example: +.sp +.RS 4 +.nf +\fB +expr foo : ^foo expr ^foo : ^foo +.fi \fR +.P +.RE +.P +return 3 and 0, respectively, on those systems; their documentation +would imply the reverse. Thus, the anchoring condition is left +unspecified to avoid breaking historical scripts relying on this +undocumented feature. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "Section 2.6.4" ", " "Arithmetic Expansion" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/false.1p b/man-pages-posix-2013-a/man1p/false.1p new file mode 100644 index 0000000..7fa2366 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/false.1p @@ -0,0 +1,75 @@ +'\" et +.TH FALSE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +false +\(em return false value +.SH SYNOPSIS +.LP +.nf +false +.fi +.SH DESCRIPTION +The +.IR false +utility shall return with a non-zero exit code. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Not used. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The +.IR false +utility shall always exit with a value other than zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItrue\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/fc.1p b/man-pages-posix-2013-a/man1p/fc.1p new file mode 100644 index 0000000..f6e7463 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/fc.1p @@ -0,0 +1,593 @@ +'\" et +.TH FC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fc +\(em process the command history list +.SH SYNOPSIS +.LP +.nf +fc \fB[\fR\(mir\fB] [\fR\(mie \fIeditor\fB] [\fIfirst \fB[\fIlast\fB]]\fR +.P +fc \(mil\fB [\fR\(minr\fB] [\fIfirst \fB[\fIlast\fB]]\fR +.P +fc \(mis\fB [\fIold\fR=\fInew\fB] [\fIfirst\fB]\fR +.fi +.SH DESCRIPTION +The +.IR fc +utility shall list, or shall edit and re-execute, commands previously +entered to an interactive +.IR sh . +.P +The command history list shall reference commands by number. The first +number in the list is selected arbitrarily. The relationship of a +number to its command shall not change except when the user logs in and +no other process is accessing the list, at which time the system may +reset the numbering to start the oldest retained command at another +number (usually 1). When the number reaches an +implementation-defined upper limit, which shall be no smaller than +the value in +.IR HISTSIZE +or 32\|767 (whichever is greater), the shell may wrap the numbers, +starting the next command with a lower number (usually 1). However, +despite this optional wrapping of numbers, +.IR fc +shall maintain the time-ordering sequence of the commands. For +example, if four commands in sequence are given the numbers 32\|766, +32\|767, 1 (wrapped), and 2 as they are executed, command 32\|767 is +considered the command previous to 1, even though its number is +higher. +.P +When commands are edited (when the +.BR \(mil +option is not specified), the resulting lines shall be entered at the +end of the history list and then re-executed by +.IR sh . +The +.IR fc +command that caused the editing shall not be entered into the history +list. If the editor returns a non-zero exit status, this shall +suppress the entry into the history list and the command re-execution. +Any command line variable assignments or redirection operators used +with +.IR fc +shall affect both the +.IR fc +command itself as well as the command that results; for example: +.sp +.RS 4 +.nf +\fB +fc \(mis \(mi\|\(mi \(mi1 2>/dev/null +.fi \fR +.P +.RE +.P +reinvokes the previous command, suppressing standard error for both +.IR fc +and the previous command. +.SH OPTIONS +The +.IR fc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mie\ \fIeditor\fR" 10 +Use the editor named by +.IR editor +to edit the commands. The +.IR editor +string is a utility name, subject to search via the +.IR PATH +variable (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables"). +The value in the +.IR FCEDIT +variable shall be used as a default when +.BR \(mie +is not specified. If +.IR FCEDIT +is null or unset, +.IR ed +shall be used as the editor. +.IP "\fB\(mil\fP" 10 +(The letter ell.) List the commands rather than invoking an editor on +them. The commands shall be written in the sequence indicated by the +.IR first +and +.IR last +operands, as affected by +.BR \(mir , +with each command preceded by the command number. +.IP "\fB\(min\fP" 10 +Suppress command numbers when listing with +.BR \(mil . +.IP "\fB\(mir\fP" 10 +Reverse the order of the commands listed (with +.BR \(mil ) +or edited (with neither +.BR \(mil +nor +.BR \(mis ). +.IP "\fB\(mis\fP" 10 +Re-execute the command without invoking an editor. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfirst\fR,\ \fIlast\fR" 10 +Select the commands to list or edit. The number of previous commands +that can be accessed shall be determined by the value of the +.IR HISTSIZE +variable. The value of +.IR first +or +.IR last +or both shall be one of the following: +.RS 10 +.IP "\fB[+]\fInumber\fR" 10 +A positive number representing a command number; command numbers can be +displayed with the +.BR \(mil +option. +.IP "\fB\(mi\fInumber\fR" 10 +A negative decimal number representing the command that was executed +.IR number +of commands previously. For example, \(mi1 is the immediately previous +command. +.IP "\fIstring\fR" 10 +A string indicating the most recently entered command that begins with +that string. If the +.IR old =\c +.IR new +operand is not also specified with +.BR \(mis , +the string form of the +.IR first +operand cannot contain an embedded +. +.P +When the synopsis form with +.BR \(mis +is used: +.IP " *" 4 +If +.IR first +is omitted, the previous command shall be used. +.P +For the synopsis forms without +.BR \(mis : +.IP " *" 4 +If +.IR last +is omitted, +.IR last +shall default to the previous command when +.BR \(mil +is specified; otherwise, it shall default to +.IR first . +.IP " *" 4 +If +.IR first +and +.IR last +are both omitted, the previous 16 commands shall be listed or the +previous single command shall be edited (based on the +.BR \(mil +option). +.IP " *" 4 +If +.IR first +and +.IR last +are both present, all of the commands from +.IR first +to +.IR last +shall be edited (without +.BR \(mil ) +or listed (with +.BR \(mil ). +Editing multiple commands shall be accomplished by presenting to the +editor all of the commands at one time, each command starting on a new +line. If +.IR first +represents a newer command than +.IR last , +the commands shall be listed or edited in reverse sequence, equivalent +to using +.BR \(mir . +For example, the following commands on the first line are equivalent to +the corresponding commands on the second: +.RS 4 +.sp +.RS 4 +.nf +\fB +fc \(mir 10 20 fc 30 40 +fc 20 10 fc \(mir 40 30 +.fi \fR +.P +.RE +.RE +.IP " *" 4 +When a range of commands is used, it shall not be an error to specify +.IR first +or +.IR last +values that are not in the history list; +.IR fc +shall substitute the value representing the oldest or newest command in +the list, as appropriate. For example, if there are only ten commands +in the history list, numbered 1 to 10: +.RS 4 +.sp +.RS 4 +.nf +\fB +fc \(mil +fc 1 99 +.fi \fR +.P +.RE +.P +shall list and edit, respectively, all ten commands. +.RE +.RE +.IP "\fIold\fP=\fInew\fR" 10 +Replace the first occurrence of string +.IR old +in the commands to be re-executed by the string +.IR new . +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fc : +.IP "\fIFCEDIT\fP" 10 +This variable, when expanded by the shell, shall determine the default +value for the +.BR \(mie +.IR editor +option's +.IR editor +option-argument. If +.IR FCEDIT +is null or unset, +.IR ed +shall be used as the editor. +.IP "\fIHISTFILE\fP" 10 +Determine a pathname naming a command history file. If the +.IR HISTFILE +variable is not set, the shell may attempt to access or create a file +.BR .sh_history +in the directory referred to by the +.IR HOME +environment variable. If the shell cannot obtain both read and write +access to, or create, the history file, it shall use an unspecified +mechanism that allows the history to operate properly. (References to +history ``file'' in this section shall be understood to mean this +unspecified mechanism in such cases.) An implementation may choose to +access this variable only when initializing the history file; this +initialization shall occur when +.IR fc +or +.IR sh +first attempt to retrieve entries from, or add entries to, the file, as +the result of commands issued by the user, the file named by the +.IR ENV +variable, or implementation-defined system start-up files. In some +historical shells, the history file is initialized just after the +.IR ENV +file has been processed. Therefore, it is implementation-defined +whether changes made to +.IR HISTFILE +after the history file has been initialized are effective. +Implementations may choose to disable the history list mechanism for +users with appropriate privileges who do not set +.IR HISTFILE ; +the specific circumstances under which this occurs are +implementation-defined. If more than one instance of the shell is +using the same history file, it is unspecified how updates to the +history file from those shells interact. As entries are deleted from +the history file, they shall be deleted oldest first. It is +unspecified when history file entries are physically removed from the +history file. +.IP "\fIHISTSIZE\fP" 10 +Determine a decimal number representing the limit to the number of +previous commands that are accessible. If this variable is unset, an +unspecified default greater than or equal to 128 shall be used. The +maximum number of commands in the history list is unspecified, but +shall be at least 128. An implementation may choose to access this +variable only when initializing the history file, as described under +.IR HISTFILE . +Therefore, it is unspecified whether changes made to +.IR HISTSIZE +after the history file has been initialized are effective. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mil +option is used to list commands, the format of each command in the list +shall be as follows: +.sp +.RS 4 +.nf +\fB +"%d\et%s\en", <\fIline number\fR>, <\fIcommand\fR> +.fi \fR +.P +.RE +.P +If both the +.BR \(mil +and +.BR \(min +options are specified, the format of each command shall be: +.sp +.RS 4 +.nf +\fB +"\et%s\en", <\fIcommand\fR> +.fi \fR +.P +.RE +.P +If the <\fIcommand\fP> consists of more than one line, the lines after +the first shall be displayed as: +.sp +.RS 4 +.nf +\fB +"\et%s\en", <\fIcontinued-command\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion of the listing. +.IP >0 6 +An error occurred. +.P +Otherwise, the exit status shall be that of the commands executed by +.IR fc . +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since editors sometimes use file descriptors as integral parts of their +editing, redirecting their file descriptors as part of the +.IR fc +command can produce unexpected results. For example, if +.IR vi +is the +.IR FCEDIT +editor, the command: +.sp +.RS 4 +.nf +\fB +fc \(mis | more +.fi \fR +.P +.RE +.P +does not work correctly on many systems. +.P +Users on windowing systems may want to have separate history files for +each window by setting +.IR HISTFILE +as follows: +.sp +.RS 4 +.nf +\fB +HISTFILE=$HOME/.sh_hist$$ +.fi \fR +.P +.RE +.SH "EXAMPLES" +None. +.SH RATIONALE +This utility is based on the +.IR fc +built-in of the KornShell. +.P +An early proposal specified the +.BR \(mie +option as +.BR [\(mie +.IR editor +.BR [ \c +.IR old \c += +.IR new +.BR ]\|] , +which is not historical practice. Historical practice in +.IR fc +of either +.BR [\(mie +.IR editor \c +.BR ] +or +.BR "[\(mie \(mi [" +.IR old \c += +.IR new +.BR ]\|] +is acceptable, but not both together. To clarify this, a new option +.BR \(mis +was introduced replacing the +.BR "[\(mie \(mi]" . +This resolves the conflict and makes +.IR fc +conform to the Utility Syntax Guidelines. +.IP "\fIHISTFILE\fP" 10 +Some implementations of the KornShell check for the superuser +and do not create a history file unless +.IR HISTFILE +is set. This is done primarily to avoid creating unlinked files in the +root file system when logging in during single-user mode. +.IR HISTFILE +must be set for the superuser to have history. +.IP "\fIHISTSIZE\fP" 10 +Needed to limit the size of history files. It is the intent of the +standard developers that when two shells share the same history file, +commands that are entered in one shell shall be accessible by the other +shell. Because of the difficulties of synchronization over a network, +the exact nature of the interaction is unspecified. +.P +The initialization process for the history file can be dependent on the +system start-up files, in that they may contain commands that +effectively preempt the settings the user has for +.IR HISTFILE +and +.IR HISTSIZE . +For example, function definition commands are recorded in the history +file. If the system administrator includes function definitions in some +system start-up file called before the +.IR ENV +file, the history file is initialized before the user can influence its +characteristics. In some historical shells, the history file is +initialized just after the +.IR ENV +file has been processed. Because of these situations, the text requires +the initialization process to be implementation-defined. +.P +Consideration was given to omitting the +.IR fc +utility in favor of the command line editing feature in +.IR sh . +For example, in +.IR vi +editing mode, typing +.BR \(dq v\(dq +is equivalent to: +.sp +.RS 4 +.nf +\fB +EDITOR=vi fc +.fi \fR +.P +.RE +.P +However, the +.IR fc +utility allows the user the flexibility to edit multiple commands +simultaneously (such as +.IR fc +10 20) and to use editors other than those supported by +.IR sh +for command line editing. +.P +In the KornShell, the alias +.BR r +(``re-do'') is preset to +.IR fc +.BR "\(mie \(mi" +(equivalent to the POSIX +.IR fc +.BR \(mis ). +This is probably an easier command name to remember than +.IR fc +(``fix command''), but it does not meet the Utility Syntax Guidelines. +Renaming +.IR fc +to +.IR hist +or +.IR redo +was considered, but since this description closely matches historical +KornShell practice already, such a renaming was seen as gratuitous. +Users are free to create aliases whenever odd historical names such as +.IR fc , +.IR awk , +.IR cat , +.IR grep , +or +.IR yacc +are standardized by POSIX. +.P +Command numbers have no ordering effects; they are like serial numbers. +The +.BR \(mir +option and \(mi\fInumber\fP operand address the sequence of command +execution, regardless of serial numbers. So, for example, if the +command number wrapped back to 1 at some arbitrary point, there would +be no ambiguity associated with traversing the wrap point. For example, +if the command history were: +.sp +.RS 4 +.nf +\fB +32766: echo 1 +32767: echo 2 +1: echo 3 +.fi \fR +.P +.RE +.P +the number \(mi2 refers to command 32\|767 because it is the second +previous command, regardless of serial number. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/fg.1p b/man-pages-posix-2013-a/man1p/fg.1p new file mode 100644 index 0000000..ba1802c --- /dev/null +++ b/man-pages-posix-2013-a/man1p/fg.1p @@ -0,0 +1,162 @@ +'\" et +.TH FG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fg +\(em run jobs in the foreground +.SH SYNOPSIS +.LP +.nf +fg \fB[\fIjob_id\fB]\fR +.fi +.SH DESCRIPTION +If job control is enabled (see the description of +.IR set +.BR \(mim ), +the +.IR fg +utility shall move a background job from the current environment (see +.IR "Section 2.12" ", " "Shell Execution Environment") +into the foreground. +.P +Using +.IR fg +to place a job into the foreground shall remove its process ID from the +list of those ``known in the current shell execution environment''; see +.IR "Section 2.9.3.1" ", " "Examples". +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIjob_id\fR" 10 +Specify the job to be run as a foreground job. If no +.IR job_id +operand is given, the +.IR job_id +for the job that was most recently suspended, placed in the background, +or run as a background job shall be used. The format of +.IR job_id +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID". +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fg : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR fg +utility shall write the command line of the job to standard output +in the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIcommand\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If job control is disabled, the +.IR fg +utility shall exit with an error and no job shall be placed in the +foreground. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR fg +utility does not work as expected when it is operating in its own +utility execution environment because that environment has no +applicable jobs to manipulate. See the APPLICATION USAGE section for +.IR "\fIbg\fR\^". +For this reason, +.IR fg +is generally implemented as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +The extensions to the shell specified in this volume of POSIX.1\(hy2008 have mostly been based +on features provided by the KornShell. The job control features +provided by +.IR bg , +.IR fg , +and +.IR jobs +are also based on the KornShell. The standard developers examined the +characteristics of the C shell versions of these utilities and found +that differences exist. Despite widespread use of the C shell, the +KornShell versions were selected for this volume of POSIX.1\(hy2008 to maintain a degree of +uniformity with the rest of the KornShell features selected (such as +the very popular command line editing features). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.3.1" ", " "Examples", +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "\fIbg\fR\^", +.IR "\fIkill\fR\^", +.IR "\fIjobs\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/file.1p b/man-pages-posix-2013-a/man1p/file.1p new file mode 100644 index 0000000..3353707 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/file.1p @@ -0,0 +1,829 @@ +'\" et +.TH FILE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +file +\(em determine file type +.SH SYNOPSIS +.LP +.nf +file \fB[\fR\(midh\fB] [\fR\(miM \fIfile\fB] [\fR\(mim \fIfile\fB] \fIfile\fR... +.P +file \(mii \fB[\fR\(mih\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR file +utility shall perform a series of tests in sequence on each specified +.IR file +in an attempt to classify it: +.IP " 1." 4 +If +.IR file +does not exist, cannot be read, or its file status could not be +determined, the output shall indicate that the file was processed, but +that its type could not be determined. +.IP " 2." 4 +If the file is not a regular file, its file type shall be identified. +The file types directory, FIFO, socket, block special, and character +special shall be identified as such. Other implementation-defined file +types may also be identified. If +.IR file +is a symbolic link, by default the link shall be resolved and +.IR file +shall test the type of file referenced by the symbolic link. (See the +.BR \(mih +and +.BR \(mii +options below.) +.IP " 3." 4 +If the length of +.IR file +is zero, it shall be identified as an empty file. +.IP " 4." 4 +The +.IR file +utility shall examine an initial segment of +.IR file +and shall make a guess at identifying its contents based on +position-sensitive tests. (The answer is not guaranteed to be correct; +see the +.BR \(mid , +.BR \(miM , +and +.BR \(mim +options below.) +.IP " 5." 4 +The +.IR file +utility shall examine +.IR file +and make a guess at identifying its contents based on context-sensitive +default system tests. (The answer is not guaranteed to be correct.) +.IP " 6." 4 +The file shall be identified as a data file. +.P +If +.IR file +does not exist, cannot be read, or its file status could not be +determined, the output shall indicate that the file was processed, but +that its type could not be determined. +.P +If +.IR file +is a symbolic link, by default the link shall be resolved and +.IR file +shall test the type of file referenced by the symbolic link. +.SH OPTIONS +The +.IR file +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of the +.BR \(mim , +.BR \(mid , +and +.BR \(miM +options shall be significant. +.P +The following options shall be supported by the implementation: +.IP "\fB\(mid\fP" 10 +Apply any position-sensitive default system tests and +context-sensitive default system tests to the file. This is the +default if no +.BR \(miM +or +.BR \(mim +option is specified. +.IP "\fB\(mih\fP" 10 +When a symbolic link is encountered, identify the file as a symbolic +link. If +.BR \(mih +is not specified and +.IR file +is a symbolic link that refers to a nonexistent file, +.IR file +shall identify the file as a symbolic link, as if +.BR \(mih +had been specified. +.IP "\fB\(mii\fP" 10 +If a file is a regular file, do not attempt to classify the type of the +file further, but identify the file as specified in the STDOUT section. +.IP "\fB\(miM\ \fIfile\fR" 10 +Specify the name of a file containing position-sensitive tests that +shall be applied to a file in order to classify it (see the EXTENDED +DESCRIPTION). No position-sensitive default system tests nor +context-sensitive default system tests shall be applied unless the +.BR \(mid +option is also specified. +.IP "\fB\(mim\ \fIfile\fR" 10 +Specify the name of a file containing position-sensitive tests that +shall be applied to a file in order to classify it (see the EXTENDED +DESCRIPTION). +.P +If the +.BR \(mim +option is specified without specifying the +.BR \(mid +option or the +.BR \(miM +option, position-sensitive default system tests shall be applied after +the position-sensitive tests specified by the +.BR \(mim +option. If the +.BR \(miM +option is specified with the +.BR \(mid +option, the +.BR \(mim +option, or both, or the +.BR \(mim +option is specified with the +.BR \(mid +option, the concatenation of the position-sensitive tests specified by +these options shall be applied in the order specified by the appearance +of these options. If a +.BR \(miM +or +.BR \(mim +.IR file +option-argument is +.BR \(mi , +the results are unspecified. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be tested. +.SH STDIN +The standard input shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +.SH "INPUT FILES" +The +.IR file +can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR file : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +In the POSIX locale, the following format shall be used to identify +each operand, +.IR file +specified: +.sp +.RS 4 +.nf +\fB +"%s: %s\en", <\fIfile\fR>, <\fItype\fR> +.fi \fR +.P +.RE +.P +The values for <\fItype\fP> are unspecified, except that in the POSIX +locale, if +.IR file +is identified as one of the types listed in the following table, +<\fItype\fP> shall contain (but is not limited to) the corresponding +string, unless the file is identified by a position-sensitive test +specified by a +.BR \(miM +or +.BR \(mim +option. Each + +shown in the strings shall be exactly one +. +.br +.sp +.ce 1 +\fBTable 4-9: File Utility Output Strings\fR +.TS +center tab(@) box; +cB | cB | cB +l | l | l. +If \fIfile\fP is:@<\fItype\fP> shall contain the string:@Notes +_ +Nonexistent@cannot open +.P +Block special@block special@1 +Character special@character special@1 +Directory@directory@1 +FIFO@fifo@1 +Socket@socket@1 +Symbolic link@symbolic link to@1 +Regular file@regular file@1,2 +Empty regular file@empty@3 +Regular file that cannot be read@cannot open@3 +.P +Executable binary@executable@3,4,6 +\fIar\fR archive library (see \fIar\fP)@archive@3,4,6 +Extended \fIcpio\fP format (see \fIpax\fP)@cpio archive@3,4,6 +Extended \fItar\fP format (see \fBustar\fP in \fIpax\fP)@tar archive@3,4,6 +.P +Shell script@commands text@3,5,6 +C-language source@c program text@3,5,6 +FORTRAN source@fortran program text@3,5,6 +.P +Regular file whose type cannot be determined@data@3 +.TE +.TP 10 +.BR Notes: +.RS 10 +.IP " 1." 4 +This is a file type test. +.IP " 2." 4 +This test is applied only if the +.BR \(mii +option is specified. +.IP " 3." 4 +This test is applied only if the +.BR \(mii +option is not specified. +.IP " 4." 4 +This is a position-sensitive default system test. +.IP " 5." 4 +This is a context-sensitive default system test. +.IP " 6." 4 +Position-sensitive default system tests and context-sensitive +default system tests are not applied if the +.BR \(miM +option is specified unless the +.BR \(mid +option is also specified. +.RE +.P +.P +In the POSIX locale, if +.IR file +is identified as a symbolic link (see the +.BR \(mih +option), the following alternative output format shall be used: +.sp +.RS 4 +.nf +\fB +"%s: %s %s\en", <\fIfile\fR>, <\fItype\fR>, <\fIcontents of link\fR>" +.fi \fR +.P +.RE +.P +If the file named by the +.IR file +operand does not exist, cannot be read, or the type of the file named +by the +.IR file +operand cannot be determined, this shall not be considered an error +that affects the exit status. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +A file specified as an option-argument to the +.BR \(mim +or +.BR \(miM +options shall contain one position-sensitive test per line, which shall +be applied to the file. If the test succeeds, the message field of the +line shall be printed and no further tests shall be applied, with the +exception that tests on immediately following lines beginning with a +single +.BR '>' +character shall be applied. +.P +Each line shall be composed of the following four +-separated +fields. (Implementations may allow any combination of one or more +white-space characters other than + +to act as field separators.) +.IP "\fIoffset\fP" 10 +An unsigned number (optionally preceded by a single +.BR '>' +character) specifying the +.IR offset , +in bytes, of the value in the file that is to be compared against the +.IR value +field of the line. If the file is shorter than the specified offset, +the test shall fail. +.RS 10 +.P +If the +.IR offset +begins with the character +.BR '>' , +the test contained in the line shall not be applied to the file unless +the test on the last line for which the +.IR offset +did not begin with a +.BR '>' +was successful. By default, the +.IR offset +shall be interpreted as an unsigned decimal number. With a leading 0x +or 0X, the +.IR offset +shall be interpreted as a hexadecimal number; otherwise, with a leading +0, the +.IR offset +shall be interpreted as an octal number. +.RE +.IP "\fItype\fP" 10 +The type of the value in the file to be tested. The type shall consist +of the type specification characters +.BR d , +.BR s , +and +.BR u , +specifying signed decimal, string, and unsigned decimal, respectively. +.RS 10 +.P +The +.IR type +string shall be interpreted as the bytes from the file starting at the +specified +.IR offset +and including the same number of bytes specified by the +.IR value +field. If insufficient bytes remain in the file past the +.IR offset +to match the +.IR value +field, the test shall fail. +.P +The type specification characters +.BR d +and +.BR u +can be followed by an optional unsigned decimal integer that specifies +the number of bytes represented by the type. The type specification +characters +.BR d +and +.BR u +can be followed by an optional +.BR C , +.BR S , +.BR I , +or +.BR L , +indicating that the value is of type +.BR char , +.BR short , +.BR int , +or +.BR long , +respectively. +.P +The default number of bytes represented by the type specifiers +.BR d , +.BR f , +and +.BR u +shall correspond to their respective C-language types as follows. If +the system claims conformance to the C-Language Development Utilities +option, those specifiers shall correspond to the default sizes used in +the +.IR c99 +utility. Otherwise, the default sizes shall be implementation-defined. +.P +For the type specifier characters +.BR d +and +.BR u , +the default number of bytes shall correspond to the size of a basic +integer type of the implementation. For these specifier +characters, the implementation shall support values of the optional +number of bytes to be converted corresponding to the number of bytes in +the C-language types +.BR char , +.BR short , +.BR int , +or +.BR long . +These numbers can also be specified by an application as the characters +.BR C , +.BR S , +.BR I , +and +.BR L , +respectively. The byte order used when interpreting numeric values is +implementation-defined, but shall correspond to the order in which a +constant of the corresponding type is stored in memory on the system. +.P +All type specifiers, except for +.BR s , +can be followed by a mask specifier of the form &\fInumber\fP. The mask +value shall be AND'ed with the value of the input file before the +comparison with the +.IR value +field of the line is made. By default, the mask shall be interpreted as +an unsigned decimal number. With a leading 0x or 0X, the mask shall be +interpreted as an unsigned hexadecimal number; otherwise, with a +leading 0, the mask shall be interpreted as an unsigned octal number. +.P +The strings +.BR byte , +.BR short , +.BR long , +and +.BR string +shall also be supported as type fields, being interpreted as +.BR dC , +.BR dS , +.BR dL , +and +.BR s , +respectively. +.RE +.IP "\fIvalue\fP" 10 +The +.IR value +to be compared with the value from the file. +.RS 10 +.P +If the specifier from the type field is +.BR s +or +.BR string , +then interpret the value as a string. Otherwise, interpret it as a +number. If the value is a string, then the test shall succeed only when +a string value exactly matches the bytes from the file. +.P +If the +.IR value +is a string, it can contain the following sequences: +.IP "\e\fIcharacter\fR" 12 +The +-escape +sequences as specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +In addition, the escape sequence +.BR '\e\ ' +(the + +character followed by a + +character) shall be recognized to represent a + +character. The results of using any other character, other than an +octal digit, following the + +are unspecified. +.IP "\e\fIoctal\fR" 12 +Octal sequences that can be used to represent characters with specific +coded values. An octal sequence shall consist of a + +followed by the longest sequence of one, two, or three octal-digit +characters (01234567). +.P +By default, any value that is not a string shall be interpreted as a +signed decimal number. Any such value, with a leading 0x or 0X, shall +be interpreted as an unsigned hexadecimal number; otherwise, with a +leading zero, the value shall be interpreted as an unsigned octal +number. +.P +If the value is not a string, it can be preceded by a character +indicating the comparison to be performed. Permissible characters and +the comparisons they specify are as follows: +.IP "\fR=\fP" 6 +The test shall succeed if the value from the file equals the +.IR value +field. +.IP "\fR<\fP" 6 +The test shall succeed if the value from the file is less than the +.IR value +field. +.IP "\fR>\fP" 6 +The test shall succeed if the value from the file is greater than the +.IR value +field. +.IP "\fR&\fP" 6 +The test shall succeed if all of the set bits in the +.IR value +field are set in the value from the file. +.IP "\fR^\fP" 6 +The test shall succeed if at least one of the set bits in the +.IR value +field is not set in the value from the file. +.IP "\fRx\fP" 6 +The test shall succeed if the file is large enough to contain a value +of the type specified starting at the offset specified. +.RE +.IP "\fImessage\fP" 10 +The +.IR message +to be printed if the test succeeds. The +.IR message +shall be interpreted using the notation for the +.IR printf +formatting specification; see +.IR printf . +If the +.IR value +field was a string, then the value from the file shall be the argument +for the +.IR printf +formatting specification; otherwise, the value from the file shall be +the argument. +.br +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR file +utility can only be required to guess at many of the file types because +only exhaustive testing can determine some types with certainty. For +example, binary data on some implementations might match the initial +segment of an executable or a +.IR tar +archive. +.P +Note that the table indicates that the output contains the stated +string. Systems may add text before or after the string. For +executables, as an example, the machine architecture and various facts +about how the file was link-edited may be included. Note also that on +systems that recognize shell script files starting with +.BR \(dq#!\(dq +as executable files, these may be identified as executable binary files +rather than as shell scripts. +.SH EXAMPLES +Determine whether an argument is a binary executable file: +.sp +.RS 4 +.nf +\fB +file \(mi\|\(mi "$1" | grep \(miq ':.*executable' && + printf "%s is executable.\en$1" +.fi \fR +.P +.RE +.SH RATIONALE +The +.BR \(mif +option was omitted because the same effect can (and should) be obtained +using the +.IR xargs +utility. +.P +Historical versions of the +.IR file +utility attempt to identify the following types of files: symbolic +link, directory, character special, block special, socket, +.IR tar +archive, +.IR cpio +archive, SCCS archive, archive library, empty, +.IR compress +output, +.IR pack +output, binary data, C source, FORTRAN source, assembler source, +.IR nroff /\c +.IR troff /\c +.IR eqn /\c +.IR tbl +source +.IR troff +output, shell script, C shell script, English text, ASCII text, various +executables, APL workspace, compiled terminfo entries, and CURSES +screen images. Only those types that are reasonably well specified in +POSIX or are directly related to POSIX utilities are listed in the +table. +.P +Historical systems have used a ``magic file'' named +.BR /etc/magic +to help identify file types. Because it is generally useful for users +and scripts to be able to identify special file types, the +.BR \(mim +flag and a portable format for user-created magic files has been +specified. No requirement is made that an implementation of +.IR file +use this method of identifying files, only that users be permitted to +add their own classifying tests. +.P +In addition, three options have been added to historical practice. The +.BR \(mid +flag has been added to permit users to cause their tests to follow any +default system tests. The +.BR \(mii +flag has been added to permit users to test portably for regular files +in shell scripts. The +.BR \(miM +flag has been added to permit users to ignore any default system +tests. +.P +The POSIX.1\(hy2008 description of default system tests and the interaction +between the +.BR \(mid , +.BR \(miM , +and +.BR \(mim +options did not clearly indicate that there were two types of ``default +system tests''. The ``position-sensitive tests'' determine file types +by looking for certain string or binary values at specific offsets in +the file being examined. These position-sensitive tests were +implemented in historical systems using the magic file described above. +Some of these tests are now built into the +.IR file +utility itself on some implementations so the output can provide more +detail than can be provided by magic files. For example, a magic file +can easily identify a +.BR core +file on most implementations, but cannot name the program file that +dropped the core. A magic file could produce output such as: +.sp +.RS 4 +.nf +\fB +/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1 +.fi \fR +.P +.RE +.P +but by building the test into the +.IR file +utility, you could get output such as: +.sp +.RS 4 +.nf +\fB +/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1, from 'testprog' +.fi \fR +.P +.RE +.P +These extended built-in tests are still to be treated as +position-sensitive default system tests even if they are not listed in +.BR /etc/magic +or any other magic file. +.P +The context-sensitive default system tests were always built into the +.IR file +utility. These tests looked for language constructs in text files +trying to identify shell scripts, C, FORTRAN, and other computer +language source files, and even plain text files. With the addition of +the +.BR \(mim +and +.BR \(miM +options the distinction between position-sensitive and +context-sensitive default system tests became important because the +order of testing is important. The context-sensitive system default +tests should never be applied before any position-sensitive tests even +if the +.BR \(mid +option is specified before a +.BR \(mim +option or +.BR \(miM +option due to the high probability that the context-sensitive system +default tests will incorrectly identify arbitrary text files as text +files before position-sensitive tests specified by the +.BR \(mim +or +.BR \(miM +option would be applied to give a more accurate identification. +.P +Leaving the meaning of +.BR "\(miM \(mi" +and +.BR "\(mim \(mi" +unspecified allows an existing prototype of these options to continue +to work in a backwards-compatible manner. (In that implementation, +.BR "\(miM \(mi" +was roughly equivalent to +.BR \(mid +in POSIX.1\(hy2008.) +.P +The historical +.BR \(mic +option was omitted as not particularly useful to users or portable +shell scripts. In addition, a reasonable implementation of the +.IR file +utility would report any errors found each time the magic file is +read. +.P +The historical format of the magic file was the same as that specified +by the Rationale in the ISO\ POSIX\(hy2:\|1993 standard for the +.IR offset , +.IR value , +and +.IR message +fields; however, it used less precise type fields than the format +specified by the current normative text. The new type field values are +a superset of the historical ones. +.P +The following is an example magic file: +.sp +.RS 4 +.nf +\fB +0 short 070707 cpio archive +0 short 0143561 Byte-swapped cpio archive +0 string 070707 ASCII cpio archive +0 long 0177555 Very old archive +0 short 0177545 Old archive +0 short 017437 Old packed data +0 string \e037\e036 Packed data +0 string \e377\e037 Compacted data +0 string \e037\e235 Compressed data +>2 byte&0x80 >0 Block compressed +>2 byte&0x1f x %d bits +0 string \e032\e001 Compiled Terminfo Entry +0 short 0433 Curses screen image +0 short 0434 Curses screen image +0 string System V Release 1 archive +0 string !\en__.SYMDEF Archive random library +0 string ! Archive +0 string ARF_BEGARF PHIGS clear text archive +0 long 0x137A2950 Scalable OpenFont binary +0 long 0x137A2951 Encrypted scalable OpenFont binary +.fi \fR +.P +.RE +.P +The use of a basic integer data type is intended to allow the +implementation to choose a word size commonly used by applications +on that architecture. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIls\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIprintf\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/find.1p b/man-pages-posix-2013-a/man1p/find.1p new file mode 100644 index 0000000..5ef0743 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/find.1p @@ -0,0 +1,1126 @@ +'\" et +.TH FIND "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +find +\(em find files +.SH SYNOPSIS +.LP +.nf +find \fB[\fR\(miH|\(miL\fB] \fIpath\fR... \fB[\fIoperand_expression\fR...\fB] +.fi +.SH DESCRIPTION +The +.IR find +utility shall recursively descend the directory hierarchy from each +file specified by +.IR path , +evaluating a Boolean expression composed of the primaries described in +the OPERANDS section for each file encountered. Each +.IR path +operand shall be evaluated unaltered as it was provided, including +all trailing + +characters; all pathnames for other files encountered in the hierarchy +shall consist of the concatenation of the current +.IR path +operand, a + +if the current +.IR path +operand did not end in one, and the filename relative to the +.IR path +operand. The relative portion shall contain no dot or dot-dot components, +no trailing + +characters, and only single + +characters between pathname components. +.P +The +.IR find +utility shall be able to descend to arbitrary depths in a file +hierarchy and shall not fail due to path length limitations (unless a +.IR path +operand specified by the application exceeds +{PATH_MAX} +requirements). +.P +The +.IR find +utility shall detect infinite loops; that is, entering a previously +visited directory that is an ancestor of the last file encountered. +When it detects an infinite loop, +.IR find +shall write a diagnostic message to standard error and shall either +recover its position in the hierarchy or terminate. +.P +If a file is removed from or added to the directory hierarchy being +searched it is unspecified whether or not +.IR find +includes that file in its search. +.SH OPTIONS +The +.IR find +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(miH\fP" 10 +Cause the file information and file type evaluated for each symbolic +link encountered as a +.IR path +operand on the command line to be those of the file referenced by the +link, and not the link itself. If the referenced file does not exist, the +file information and type shall be for the link itself. File information +and type for symbolic links encountered during the traversal of a file +hierarchy shall be that of the link itself. +.IP "\fB\(miL\fP" 10 +Cause the file information and file type evaluated for each symbolic +link encountered as a +.IR path +operand on the command line or encountered during the traversal of +a file hierarchy to be those of the file referenced by the link, and +not the link itself. If the referenced file does not exist, the file +information and type shall be for the link itself. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH +and +.BR \(miL +shall not be considered an error. The last option specified shall +determine the behavior of the utility. If neither the +.BR \(miH +nor the +.BR \(miL +option is specified, then the file information and type for symbolic +links encountered as a +.IR path +operand on the command line or encountered during the traversal of a +file hierarchy shall be that of the link itself. +.SH OPERANDS +The following operands shall be supported: +.P +The first operand and subsequent operands up to but not including the +first operand that starts with a +.BR '\(mi' , +or is a +.BR '!' +or a +.BR '(' , +shall be interpreted as +.IR path +operands. If the first operand starts with a +.BR '\(mi' , +or is a +.BR '!' +or a +.BR '(' , +the behavior is unspecified. Each +.IR path +operand is a pathname of a starting point in the file hierarchy. +.P +The first operand that starts with a +.BR '\(mi' , +or is a +.BR '!' +or a +.BR '(' , +and all subsequent arguments shall be interpreted as an +.IR expression +made up of the following primaries and operators. In the descriptions, +wherever +.IR n +is used as a primary argument, it shall be interpreted as a decimal +integer optionally preceded by a plus (\c +.BR '\(pl' ) +or minus-sign (\c +.BR '\(mi' ) +sign, as follows: +.IP "+\fIn\fR" 10 +More than +.IR n . +.IP "\fIn\fR" 10 +Exactly +.IR n . +.IP "\(mi\fIn\fR" 10 +Less than +.IR n . +.P +The following primaries shall be supported: +.IP "\fB\(miname\ \fIpattern\fR" 10 +.br +The primary shall evaluate as true if the basename of the current +pathname matches +.IR pattern +using the pattern matching notation described in +.IR "Section 2.13" ", " "Pattern Matching Notation". +The additional rules in +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion" +do not apply as this is a matching operation, not an expansion. +.IP "\fB\(mipath\ \fIpattern\fR" 10 +.br +The primary shall evaluate as true if the current pathname matches +.IR pattern +using the pattern matching notation described in +.IR "Section 2.13" ", " "Pattern Matching Notation". +The additional rules in +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion" +do not apply as this is a matching operation, not an expansion. +.IP "\fB\(minouser\fP" 10 +The primary shall evaluate as true if the file belongs to a user ID for +which the +\fIgetpwuid\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 (or equivalent) returns NULL. +.IP "\fB\(minogroup\fP" 10 +The primary shall evaluate as true if the file belongs to a group ID +for which the +\fIgetgrgid\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 (or equivalent) returns NULL. +.IP "\fB\(mixdev\fP" 10 +The primary shall always evaluate as true; it shall cause +.IR find +not to continue descending past directories that have a different +device ID (\c +.IR st_dev , +see the +\fIstat\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008). If any +.BR \(mixdev +primary is specified, it shall apply to the entire expression even if +the +.BR \(mixdev +primary would not normally be evaluated. +.IP "\fB\(miprune\fP" 10 +The primary shall always evaluate as true; it shall cause +.IR find +not to descend the current pathname if it is a directory. If the +.BR \(midepth +primary is specified, the +.BR \(miprune +primary shall have no effect. +.IP "\fB\(miperm\ [\(mi]\fImode\fR" 10 +.br +The +.IR mode +argument is used to represent file mode bits. It shall be identical in +format to the +.IR symbolic_mode +operand described in +.IR chmod , +and shall be interpreted as follows. To start, a template shall be +assumed with all file mode bits cleared. An +.IR op +symbol of +.BR '\(pl' +shall set the appropriate mode bits in the template; +.BR '\(mi' +shall clear the appropriate bits; +.BR '=' +shall set the appropriate mode bits, without regard to the contents of +the file mode creation mask of the process. The +.IR op +symbol of +.BR '\(mi' +cannot be the first character of +.IR mode ; +this avoids ambiguity with the optional leading +. +Since the initial mode is all bits off, there are not any symbolic modes +that need to use +.BR '\(mi' +as the first character. +.RS 10 +.P +If the + +is omitted, the primary shall evaluate as true when the file permission +bits exactly match the value of the resulting template. +.P +Otherwise, if +.IR mode +is prefixed by a +, +the primary shall evaluate as true if at least all the bits in the +resulting template are set in the file permission bits. +.RE +.IP "\fB\(miperm\ [\(mi]\fIonum\fR" 10 +.br +If the + +is omitted, the primary shall evaluate as true when the file mode bits +exactly match the value of the octal number +.IR onum +(see the description of the octal +.IR mode +in +.IR chmod ). +Otherwise, if +.IR onum +is prefixed by a +, +the primary shall evaluate as true if at least all of the bits specified in +.IR onum +are set. In both cases, the behavior is unspecified when +.IR onum +exceeds 07777. +.IP "\fB\(mitype\ \fIc\fR" 10 +The primary shall evaluate as true if the type of the file is +.IR c , +where +.IR c +is +.BR 'b' , +.BR 'c' , +.BR 'd' , +.BR 'l' , +.BR 'p' , +.BR 'f' , +or +.BR 's' +for block special file, character special file, directory, symbolic +link, FIFO, regular file, or socket, respectively. +.IP "\fB\(milinks\ \fIn\fR" 10 +The primary shall evaluate as true if the file has +.IR n +links. +.IP "\fB\(miuser\ \fIuname\fR" 10 +The primary shall evaluate as true if the file belongs to the user +.IR uname. +If +.IR uname +is a decimal integer and the +\fIgetpwnam\fR() +(or equivalent) function does not return a valid user name, +.IR uname +shall be interpreted as a user ID. +.IP "\fB\(migroup\ \fIgname\fR" 10 +.br +The primary shall evaluate as true if the file belongs to the group +.IR gname . +If +.IR gname +is a decimal integer and the +\fIgetgrnam\fR() +(or equivalent) function does not return a valid group name, +.IR gname +shall be interpreted as a group ID. +.IP "\fB\(misize\ \fIn\fB[c]\fR" 10 +The primary shall evaluate as true if the file size in bytes, divided +by 512 and rounded up to the next integer, is +.IR n . +If +.IR n +is followed by the character +.BR 'c' , +the size shall be in bytes. +.IP "\fB\(miatime\ \fIn\fR" 10 +The primary shall evaluate as true if the file access time subtracted +from the initialization time, divided by 86\|400 (with any remainder +discarded), is +.IR n . +.IP "\fB\(mictime\ \fIn\fR" 10 +The primary shall evaluate as true if the time of last change of file +status information subtracted from the initialization time, divided by +86\|400 (with any remainder discarded), is +.IR n . +.IP "\fB\(mimtime\ \fIn\fR" 10 +The primary shall evaluate as true if the file modification time +subtracted from the initialization time, divided by 86\|400 (with any +remainder discarded), is +.IR n . +.IP "\fB\(miexec\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ ;\fR" 10 +.IP "\fB\(miexec\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ \ \fR{\|}\0+" 10 +.br +The end of the primary expression shall be punctuated by a + +or by a +. +Only a + +that immediately follows an argument containing only the two characters +.BR \(dq{}\(dq +shall punctuate the end of the primary expression. Other uses of the + +shall not be treated as special. +.RS 10 +.P +If the primary expression is punctuated by a +, +the utility +.IR utility_name +shall be invoked once for each pathname and the primary shall evaluate +as true if the utility returns a zero value as exit status. A +.IR utility_name +or +.IR argument +containing only the two characters +.BR \(dq{}\(dq +shall be replaced by the current pathname. If a +.IR utility_name +or +.IR argument +string contains the two characters +.BR \(dq{}\(dq , +but not just the two characters +.BR \(dq{}\(dq , +it is implementation-defined whether +.IR find +replaces those two characters or uses the string without change. +.P +If the primary expression is punctuated by a +, +the primary shall always evaluate as true, and the pathnames for which +the primary is evaluated shall be aggregated into sets. The utility +.IR utility_name +shall be invoked once for each set of aggregated pathnames. Each +invocation shall begin after the last pathname in the set is +aggregated, and shall be completed before the +.IR find +utility exits and before the first pathname in the next set (if any) is +aggregated for this primary, but it is otherwise unspecified whether +the invocation occurs before, during, or after the evaluations of other +primaries. If any invocation returns a non-zero value as exit status, +the +.IR find +utility shall return a non-zero exit status. An argument containing +only the two characters +.BR \(dq{}\(dq +shall be replaced by the set of aggregated pathnames, with each +pathname passed as a separate argument to the invoked utility in the +same order that it was aggregated. The size of any set of two or more +pathnames shall be limited such that execution of the utility does not +cause the system's +{ARG_MAX} +limit to be exceeded. If more than one argument containing the two +characters +.BR \(dq{}\(dq +is present, the behavior is unspecified. +.P +The current directory for the invocation of +.IR utility_name +shall be the same as the current directory when the +.IR find +utility was started. If the +.IR utility_name +names any of the special built-in utilities (see +.IR "Section 2.14" ", " "Special Built-In Utilities"), +the results are undefined. +.RE +.IP "\fB\(miok\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ ;\fR" 10 +.br +The +.BR \(miok +primary shall be equivalent to +.BR \(miexec , +except that the use of a + +to punctuate the end of the primary expression need not be supported, and +.IR find +shall request affirmation of the invocation of +.IR utility_name +using the current file as an argument by writing to standard error as +described in the STDERR section. If the response on standard input is +affirmative, the utility shall be invoked. Otherwise, the command +shall not be invoked and the value of the +.BR \(miok +operand shall be false. +.IP "\fB\(miprint\fR" 10 +The primary shall always evaluate as true; it shall cause the current +pathname to be written to standard output. +.IP "\fB\(minewer\ \fIfile\fR" 10 +The primary shall evaluate as true if the modification time of the +current file is more recent than the modification time of the file +named by the pathname +.IR file . +.IP "\fB\(midepth\fR" 10 +The primary shall always evaluate as true; it shall cause descent of +the directory hierarchy to be done so that all entries in a directory +are acted on before the directory itself. If a +.BR \(midepth +primary is not specified, all entries in a directory shall be acted on +after the directory itself. If any +.BR \(midepth +primary is specified, it shall apply to the entire expression even if +the +.BR \(midepth +primary would not normally be evaluated. +.P +The primaries can be combined using the following operators (in order +of decreasing precedence): +.IP "(\ \fIexpression\fR\ )" 10 +True if +.IR expression +is true. +.IP "\fB!\ \fIexpression\fR" 10 +Negation of a primary; the unary NOT operator. +.IP "\fIexpression\ \fB[\(mia]\ \fIexpression\fR" 10 +.br +Conjunction of primaries; the AND operator is implied by the +juxtaposition of two primaries or made explicit by the optional +.BR \(mia +operator. The second expression shall not be evaluated if the first +expression is false. +.IP "\fIexpression\ \fB\(mio\ \fIexpression\fR" 10 +.br +Alternation of primaries; the OR operator. The second expression shall +not be evaluated if the first expression is true. +.P +If no +.IR expression +is present, +.BR \(miprint +shall be used as the expression. Otherwise, if the given expression +does not contain any of the primaries +.BR \(miexec , +.BR \(miok , +or +.BR \(miprint , +the given expression shall be effectively replaced by: +.sp +.RS 4 +.nf +\fB +( \fIgiven_expression\fP ) \(miprint +.fi \fR +.P +.RE +.P +The +.BR \(miuser , +.BR \(migroup , +and +.BR \(minewer +primaries each shall evaluate their respective arguments only once. +.P +When the file type evaluated for the current file is a symbolic link, +the results of evaluating the +.BR \(miperm +primary are implementation-defined. +.SH STDIN +If the +.BR \(miok +primary is used, the response shall be read from the standard input. +An entire line shall be read as the response. Otherwise, the standard +input shall not be used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR find : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the pattern matching +notation for the +.BR \(min +option and in the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +This variable determines the locale for the interpretation of sequences +of bytes of text data as characters (for example, single-byte +as opposed to multi-byte characters in arguments), the behavior of +character classes within the pattern matching notation used for the +.BR \(min +option, and the behavior of character classes within regular +expressions used in the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of the +.IR utility_name +for the +.BR \(miexec +and +.BR \(miok +primaries, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.BR \(miprint +primary shall cause the current pathnames to be written to standard +output. The format shall be: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpath\fR> +.fi \fR +.P +.RE +.SH STDERR +The +.BR \(miok +primary shall write a prompt to standard error containing at least the +.IR utility_name +to be invoked and the current pathname. In the POSIX locale, the last +non-\c + +in the prompt shall be +.BR '?' . +The exact format used is unspecified. +.P +Otherwise, the standard error shall be used only for diagnostic +messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All +.IR path +operands were traversed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +When used in operands, pattern matching notation, +, +, +and + +characters are special to the shell and must be quoted (see +.IR "Section 2.2" ", " "Quoting"). +.P +The bit that is traditionally used for sticky (historically 01000) is +specified in the +.BR \(miperm +primary using the octal number argument form. Since this bit is not +defined by this volume of POSIX.1\(hy2008, applications must not assume that it actually refers +to the traditional sticky bit. +.SH EXAMPLES +.IP " 1." 4 +The following commands are equivalent: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . +find . \(miprint +.fi \fR +.P +.RE +.P +They both write out the entire directory hierarchy from the current +directory. +.RE +.IP " 2." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find / \e( \(miname tmp \(mio \(miname '*.xx' \e) \(miatime +7 \(miexec rm {} \e; +.fi \fR +.P +.RE +.P +removes all files named +.BR tmp +or ending in +.BR .xx +that have not been accessed for seven or more 24-hour periods. +.RE +.IP " 3." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . \(miperm \(mio+w,+s +.fi \fR +.P +.RE +.P +prints (\c +.BR \(miprint +is assumed) the names of all files in or below the current directory, +with all of the file permission bits S_ISUID, S_ISGID, and S_IWOTH set. +.RE +.IP " 4." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . \(miname SCCS \(miprune \(mio \(miprint +.fi \fR +.P +.RE +.P +recursively prints pathnames of all files in the current directory and +below, but skips directories named SCCS and files in them. +.RE +.IP " 5." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . \(miprint \(miname SCCS \(miprune +.fi \fR +.P +.RE +.P +behaves as in the previous example, but prints the names of the SCCS +directories. +.RE +.IP " 6." 4 +The following command is roughly equivalent to the +.BR \(mint +extension to +.IR test : +.RS 4 +.sp +.RS 4 +.nf +\fB +if [ \(min "$(find file1 \(miprune \(minewer file2)" ]; then + printf %s\e\en "file1 is newer than file2" +fi +.fi \fR +.P +.RE +.RE +.IP " 7." 4 +The descriptions of +.BR \(miatime , +.BR \(mictime , +and +.BR \(mimtime +use the terminology +.IR n +``86\|400 second periods (days)''. For example, a file accessed at 23:59 +is selected by: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . \(miatime \(mi1 \(miprint +.fi \fR +.P +.RE +.P +at 00:01 the next day (less than 24 hours later, not more than one day +ago); the midnight boundary between days has no effect on the 24-hour +calculation. +.RE +.IP " 8." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . ! \(miname . \(miprune \(miname '*.old' \(miexec \e + sh \(mic 'mv "$@" ../old/' sh {} + +.fi \fR +.P +.RE +.P +performs the same task as: +.sp +.RS 4 +.nf +\fB +mv ./*.old ./.old ./.*.old ../old/ +.fi \fR +.P +.RE +.P +while avoiding an ``Argument list too long'' error if there are +a large number of files ending with +.BR .old +and without running +.IR mv +if there are no such files (and avoiding ``No such file or directory'' +errors if +.BR ./.old +does not exist or no files match +.BR ./*.old +or +.BR ./.*.old ). +.P +The alternative: +.sp +.RS 4 +.nf +\fB +find . ! \(miname . \(miprune \(miname '*.old' \(miexec mv {} ../old/ \e; +.fi \fR +.P +.RE +.P +is less efficient if there are many files to move because it executes one +.IR mv +command per file. +.RE +.IP " 9." 4 +On systems configured to mount removable media on directories under +.BR /media , +the following command searches the file hierarchy for files larger +than 100\|000 KB without searching any mounted removable media: +.RS 4 +.sp +.RS 4 +.nf +\fB +find / \(mipath /media \(miprune \(mio \(misize +200000 \(miprint +.fi \fR +.P +.RE +.RE +.IP 10. 4 +Except for the root directory, and +.BR \(dq//\(dq +on implementations where +.BR \(dq//\(dq +does not refer to the root directory, no pattern given to +.BR \(miname +will match a +, +because trailing + +characters are ignored when computing the basename of the file under +evaluation. Given two empty directories named +.BR foo +and +.BR bar , +the following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find foo/// bar/// \(miname foo \(mio \(miname 'bar?*' +.fi \fR +.P +.RE +.P +prints only the line +.BR \(dqfoo///\(dq . +.RE +.SH RATIONALE +The +.BR \(mia +operator was retained as an optional operator for compatibility with +historical shell scripts, even though it is redundant with expression +concatenation. +.P +The descriptions of the +.BR '\(mi' +modifier on the +.IR mode +and +.IR onum +arguments to the +.BR \(miperm +primary agree with historical practice on BSD and System V +implementations. System V and BSD documentation both describe it in +terms of checking additional bits; in fact, it uses the same bits, but +checks for having at least all of the matching bits set instead of +having exactly the matching bits set. +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because: +.IP " *" 4 +Implementations may desire more descriptive prompts than those +used on historical implementations. +.IP " *" 4 +Since the historical prompt strings do not terminate with + +characters, there is no portable way for another program to interact +with the prompts of this utility via pipes. +.P +Therefore, an application using this prompting option relies on the +system to provide the most suitable dialog directly with the user, +based on the general guidelines specified. +.P +The +.BR \(miname +.IR file +operand was changed to use the shell pattern matching notation +so that +.IR find +is consistent with other utilities using pattern matching. +.P +The +.BR \(misize +operand refers to the size of a file, rather than the number of blocks +it may occupy in the file system. The intent is that the +.IR st_size +field defined in the System Interfaces volume of POSIX.1\(hy2008 should be used, not the +.IR st_blocks +found in historical implementations. There are at least two reasons for +this: +.IP " 1." 4 +In both System V and BSD, +.IR find +only uses +.IR st_size +in size calculations for the operands specified by this volume of POSIX.1\(hy2008. (BSD uses +.IR st_blocks +only when processing the +.BR \(mils +primary.) +.IP " 2." 4 +Users usually think of file size in terms of bytes, which is also the +unit used by the +.IR ls +utility for the output from the +.BR \(mil +option. (In both System V and BSD, +.IR ls +uses +.IR st_size +for the +.BR \(mil +option size field and uses +.IR st_blocks +for the +.IR ls +.BR \(mis +calculations. This volume of POSIX.1\(hy2008 does not specify +.IR ls +.BR \(mis .) +.P +The descriptions of +.BR \(miatime , +.BR \(mictime , +and +.BR \(mimtime +were changed from the SVID description of +.IR n +``days'' to +.IR n +being the result of the integer division of the time difference in +seconds by 86\|400. The description is also different in terms of the +exact timeframe for the +.IR n +case (\fIversus\fP the +.IR +n +or +.IR \(min ), +but it matches all known historical implementations. It refers to one +86\|400 second period in the past, not any time from the beginning of +that period to the current time. For example, +.BR \(miatime +2 is true if the file was accessed any time in the period from 72 hours +to 48 hours ago. +.P +Historical implementations do not modify +.BR \(dq{}\(dq +when it appears as a substring of an +.BR \(miexec +or +.BR \(miok +.IR utility_name +or argument string. There have been numerous user requests for this +extension, so this volume of POSIX.1\(hy2008 allows the desired behavior. At least one recent +implementation does support this feature, but encountered several +problems in managing memory allocation and dealing with multiple +occurrences of +.BR \(dq{}\(dq +in a string while it was being developed, so it is not yet required +behavior. +.P +Assuming the presence of +.BR \(miprint +was added to correct a historical pitfall that plagues novice users, it +is entirely upwards-compatible from the historical System V +.IR find +utility. In its simplest form (\c +.IR find +.IR directory ), +it could be confused with the historical BSD fast +.IR find . +The BSD developers agreed that adding +.BR \(miprint +as a default expression was the correct decision and have added the +fast +.IR find +functionality within a new utility called +.IR locate . +.P +Historically, the +.BR \(miL +option was implemented using the primary +.BR \(mifollow . +The +.BR \(miH +and +.BR \(miL +options were added for two reasons. First, they offer a finer +granularity of control and consistency with other programs that walk +file hierarchies. Second, the +.BR \(mifollow +primary always evaluated to true. As they were historically really +global variables that took effect before the traversal began, some +valid expressions had unexpected results. An example is the expression +.BR \(miprint +.BR \(mio +.BR \(mifollow . +Because +.BR \(miprint +always evaluates to true, the standard order of evaluation implies that +.BR \(mifollow +would never be evaluated. This was never the case. Historical practice +for the +.BR \(mifollow +primary, however, is not consistent. Some implementations always follow +symbolic links on the command line whether +.BR \(mifollow +is specified or not. Others follow symbolic links on the command line +only if +.BR \(mifollow +is specified. Both behaviors are provided by the +.BR \(miH +and +.BR \(miL +options, but scripts using the current +.BR \(mifollow +primary would be broken if the +.BR \(mifollow +option is specified to work either way. +.P +Since the +.BR \(miL +option resolves all symbolic links and the +.BR \(mitype +.IR l +primary is true for symbolic links that still exist after symbolic +links have been resolved, the command: +.sp +.RS 4 +.nf +\fB +find \(miL . \(mitype l +.fi \fR +.P +.RE +.P +prints a list of symbolic links reachable from the current directory +that do not resolve to accessible files. +.P +A feature of SVR4's +.IR find +utility was the +.BR \(miexec +primary's +.BR + +terminator. This allowed filenames containing special characters +(especially + +characters) to be grouped together without the problems that occur if +such filenames are piped to +.IR xargs . +Other implementations have added other ways to get around this problem, +notably a +.BR \(miprint0 +primary that wrote filenames with a null byte terminator. This was +considered here, but not adopted. Using a null terminator meant that +any utility that was going to process +.IR find 's +.BR \(miprint0 +output had to add a new option to parse the null terminators it would +now be reading. +.P +The +.BR \(dq\(miexec ... {} +\(dq +syntax adopted was a result of IEEE PASC Interpretation 1003.2 #210. It +should be noted that this is an incompatible change to IEEE\ Std 1003.2\(hy1992. For example, +the following command printed all files with a +.BR '\(mi' +after their name if they are regular files, and a +.BR '\(pl' +otherwise: +.sp +.RS 4 +.nf +\fB +find / \(mitype f \(miexec echo {} \(mi ';' \(mio \(miexec echo {} + ';' +.fi \fR +.P +.RE +.P +The change invalidates usage like this. Even though the previous +standard stated that this usage would work, in practice many did not +support it and the standard developers felt it better to now state that +this was not allowable. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.2" ", " "Quoting", +.IR "Section 2.13" ", " "Pattern Matching Notation", +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIchmod\fR\^", +.IR "\fImv\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIsh\fR\^", +.IR "\fItest\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/fold.1p b/man-pages-posix-2013-a/man1p/fold.1p new file mode 100644 index 0000000..2c7469d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/fold.1p @@ -0,0 +1,280 @@ +'\" et +.TH FOLD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fold +\(em filter for folding lines +.SH SYNOPSIS +.LP +.nf +fold \fB[\fR\(mibs\fB] [\fR\(miw \fIwidth\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR fold +utility is a filter that shall fold lines from its input files, +breaking the lines to have a maximum of +.IR width +column positions (or bytes, if the +.BR \(mib +option is specified). Lines shall be broken by the insertion of a + +such that each output line (referred to later in this section +as a \fIsegment\fP) is the maximum width possible that does not exceed +the specified number of column positions (or bytes). A line shall not +be broken in the middle of a character. The behavior is undefined if +.IR width +is less than the number of columns any single character in the input +would occupy. +.P +If the +, +, +or + +characters are encountered in the input, and the +.BR \(mib +option is not specified, they shall be treated specially: +.IP 10 +The current count of line width shall be decremented by one, although +the count never shall become negative. The +.IR fold +utility shall not insert a + +immediately before or after any +, +unless the following character has a width greater than 1 and would +cause the line width to exceed +.IR width . +.IP 10 +.br +The current count of line width shall be set to zero. The +.IR fold +utility shall not insert a + +immediately before or after any +. +.IP 10 +Each + +encountered shall advance the column position pointer to the next tab +stop. Tab stops shall be at each column position +.IR n +such that +.IR n +modulo 8 equals 1. +.SH OPTIONS +The +.IR fold +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mib\fR" 10 +Count +.IR width +in bytes rather than column positions. +.IP "\fB\(mis\fR" 10 +If a segment of a line contains a + +within the first +.IR width +column positions (or bytes), break the line after the last such + +meeting the width constraints. If there is no + +meeting the requirements, the +.BR \(mis +option shall have no effect for that output segment of the input line. +.IP "\fB\(miw\ \fIwidth\fR" 10 +Specify the maximum line length, in column positions (or bytes if +.BR \(mib +is specified). The results are unspecified if +.IR width +is not a positive decimal number. The default value shall be 80. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to be folded. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +If the +.BR \(mib +option is specified, the input files shall be text files except that the +lines are not limited to +{LINE_MAX} +bytes in length. If the +.BR \(mib +option is not specified, the input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fold : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), and for the +determination of the width in column positions each character would +occupy on a constant-width font output device. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be a file containing a sequence of characters +whose order shall be preserved from the input files, possibly with +inserted + +characters. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR cut +and +.IR fold +utilities can be used to create text files out of files with arbitrary +line lengths. The +.IR cut +utility should be used when the number of lines (or records) needs to +remain constant. The +.IR fold +utility should be used when the contents of long lines need to be kept +contiguous. +.P +The +.IR fold +utility is frequently used to send text files to printers that +truncate, rather than fold, lines wider than the printer is able to +print (usually 80 or 132 column positions). +.SH EXAMPLES +An example invocation that submits a file of possibly long lines to the +printer (under the assumption that the user knows the line width of the +printer to be assigned by +.IR lp ): +.sp +.RS 4 +.nf +\fB +fold \(miw 132 bigfile | lp +.fi \fR +.P +.RE +.SH RATIONALE +Although terminal input in canonical processing mode requires the erase +character (frequently set to +) +to erase the previous character (not byte or column position), terminal +output is not buffered and is extremely difficult, if not impossible, +to parse correctly; the interpretation depends entirely on the physical +device that actually displays/prints/stores the output. In all known +internationalized implementations, the utilities producing output for +mixed column-width output assume that a + +character backs up one column position and outputs enough + +characters to return to the start of the character when + +is used to provide local line motions to support underlining and +emboldening operations. Since +.IR fold +without the +.BR \(mib +option is dealing with these same constraints, + +is always treated as backing up one column position rather than backing +up one character. +.P +Historical versions of the +.IR fold +utility assumed 1 byte was one character and occupied one column +position when written out. This is no longer always true. Since the +most common usage of +.IR fold +is believed to be folding long lines for output to limited-length +output devices, this capability was preserved as the default case. The +.BR \(mib +option was added so that applications could +.IR fold +files with arbitrary length lines into text files that could then be +processed by the standard utilities. Note that although the width for +the +.BR \(mib +option is in bytes, a line is never split in the middle of a character. +(It is unspecified what happens if a width is specified that is too +small to hold a single character found in the input followed by a +.) +.P +The tab stops are hardcoded to be every eighth column to meet +historical practice. No new method of specifying other tab stops was +invented. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcut\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/fort77.1p b/man-pages-posix-2013-a/man1p/fort77.1p new file mode 100644 index 0000000..f14ea4f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/fort77.1p @@ -0,0 +1,581 @@ +'\" et +.TH FORT77 "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fort77 +\(em FORTRAN compiler (\fBFORTRAN\fP) +.SH SYNOPSIS +.LP +.nf +fort77 \fB[\fR\(mic\fB] [\fR\(mig\fB] [\fR\(miL \fIdirectory\fB]\fR...\fB [\fR\(miO \fIoptlevel\fB] [\fR\(mio \fIoutfile\fB] [\fR\(mis\fB] + [\fR\(miw\fB] \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR fort77 +utility is the interface to the FORTRAN compilation system; it shall +accept the full FORTRAN-77 language defined by the ANSI\ X3.9\(hy1978 standard. The system +conceptually consists of a compiler and link editor. The files +referenced by +.IR operand s +are compiled and linked to produce an executable file. It is +unspecified whether the linking occurs entirely within the operation of +.IR fort77 ; +some implementations may produce objects that are not fully resolved +until the file is executed. +.P +If the +.BR \(mic +option is present, for all pathname operands of the form +.IR file \c +.BR .f , +the files: +.sp +.RS 4 +.nf +\fB +$(basename \fIpathname\fR.f).o +.fi \fR +.P +.RE +.P +shall be created or overwritten as the result of successful +compilation. If the +.BR \(mic +option is not specified, it is unspecified whether such +.BR .o +files are created or deleted for the +.IR file \c +.BR .f +operands. +.P +If there are no options that prevent link editing (such as +.BR \(mic ) +and all operands compile and link without error, the resulting +executable file shall be written into the file named by the +.BR \(mio +option (if present) or to the file +.BR a.out . +The executable file shall be created as specified in the System Interfaces volume of POSIX.1\(hy2008, except +that the file permissions shall be set to: +S_IRWXO | S_IRWXG | S_IRWXU +.P +and that the bits specified by the +.IR umask +of the process shall be cleared. +.SH OPTIONS +The +.IR fort77 +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that: +.IP " *" 4 +The +.BR \(mil +.IR library +operands have the format of options, but their position within a list +of operands affects the order in which libraries are searched. +.IP " *" 4 +The order of specifying the multiple +.BR \(miL +options is significant. +.IP " *" 4 +Conforming applications shall specify each option separately; that is, +grouping option letters (for example, +.BR \(micg ) +need not be recognized by all implementations. +.P +The following options shall be supported: +.IP "\fB\(mic\fR" 10 +Suppress the link-edit phase of the compilation, and do not remove any +object files that are produced. +.IP "\fB\(mig\fR" 10 +Produce symbolic information in the object or executable files; the +nature of this information is unspecified, and may be modified by +implementation-defined interactions with other options. +.IP "\fB\(mis\fR" 10 +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using the +.IR exec +family of functions defined in the System Interfaces volume of POSIX.1\(hy2008 has been removed (stripped). +If both +.BR \(mig +and +.BR \(mis +options are present, the action taken is unspecified. +.IP "\fB\(mio\ \fIoutfile\fR" 10 +Use the pathname +.IR outfile , +instead of the default +.BR a.out , +for the executable file produced. If the +.BR \(mio +option is present with +.BR \(mic , +the result is unspecified. +.IP "\fB\(miL\ \fIdirectory\fR" 10 +Change the algorithm of searching for the libraries named in +.BR \(mil +operands to look in the directory named by the +.IR directory +pathname before looking in the usual places. Directories named in +.BR \(miL +options shall be searched in the specified order. At least ten +instances of this option shall be supported in a single +.IR fort77 +command invocation. If a directory specified by a +.BR \(miL +option contains a file named +.BR libf.a , +the results are unspecified. +.IP "\fB\(miO\ \fIoptlevel\fR" 10 +Specify the level of code optimization. If the +.IR optlevel +option-argument is the digit +.BR '0' , +all special code optimizations shall be disabled. If it is the digit +.BR '1' , +the nature of the optimization is unspecified. If the +.BR \(miO +option is omitted, the nature of the system's default optimization is +unspecified. It is unspecified whether code generated in the presence +of the +.BR \(miO +0 option is the same as that generated when +.BR \(miO +is omitted. Other +.IR optlevel +values may be supported. +.IP "\fB\(miw\fR" 10 +Suppress warnings. +.P +Multiple instances of +.BR \(miL +options can be specified. +.SH OPERANDS +An +.IR operand +is either in the form of a pathname or the form +.BR \(mil +.IR library . +At least one operand of the pathname form shall be specified. The +following operands shall be supported: +.IP "\fIfile.\fBf\fR" 10 +The pathname of a FORTRAN source file to be compiled and optionally +passed to the link editor. The filename operand shall be of this form +if the +.BR \(mic +option is used. +.IP "\fIfile.\fBa\fR" 10 +A library of object files typically produced by +.IR ar , +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .a +as denoting object file libraries. +.IP "\fIfile.\fBo\fR" 10 +An object file produced by +.IR fort77 +.BR \(mic +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .o +as denoting object files. +.P +The processing of other files is implementation-defined. +.IP "\fB\(mil\ \fIlibrary\fR" 10 +(The letter ell.) Search the library named: +.RS 10 +.sp +.RS 4 +.nf +\fB +lib\fIlibrary\fR.a +.fi \fR +.P +.RE +.P +A library is searched when its name is encountered, so the placement of +a +.BR \(mil +operand is significant. Several standard libraries can be specified in +this manner, as described in the EXTENDED DESCRIPTION section. +Implementations may recognize implementation-defined suffixes other +than +.BR .a +as denoting libraries. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +The input file shall be one of the following: a text file containing +FORTRAN source code; an object file in the format produced by +.IR fort77 +.BR \(mic ; +or a library of object files, in the format produced by archiving zero +or more object files, using +.IR ar . +Implementations may supply additional utilities that produce files in +these formats. Additional input files are implementation-defined. +.P +A + +encountered within the first six characters on a line of source code +shall cause the compiler to interpret the following character as if it +were the seventh character on the line (that is, in column 7). +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fort77 : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that should override the default directory for +temporary files, if any. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +If more than one +.IR file +operand ending in +.BR .f +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +may be written to allow identification of the diagnostic message with +the appropriate input file. +.P +This utility may produce warning messages about certain conditions that +do not warrant returning an error (non-zero) exit value. +.SH "OUTPUT FILES" +Object files, listing files, and executable files shall be produced in +unspecified formats. +.SH "EXTENDED DESCRIPTION" +.SS "Standard Libraries" +.P +The +.IR fort77 +utility shall recognize the following +.BR \(mil +operand for the standard library: +.IP "\fB\(mil\ f\fR" 10 +This library contains all functions referenced in the ANSI\ X3.9\(hy1978 standard. This +operand shall not be required to be present to cause a search of this +library. +.P +In the absence of options that inhibit invocation of the link editor, +such as +.BR \(mic , +the +.IR fort77 +utility shall cause the equivalent of a +.BR "\(mil\ f" +operand to be passed to the link editor as the last +.BR \(mil +operand, causing it to be searched after all other object files and +libraries are loaded. +.P +It is unspecified whether the library +.BR libf.a +exists as a regular file. The implementation may accept as +.BR \(mil +operands names of objects that do not exist as regular files. +.SS "External Symbols" +.P +The FORTRAN compiler and link editor shall support the significance of +external symbols up to a length of at least 31 bytes; case folding is +permitted. The action taken upon encountering symbols exceeding the +implementation-defined maximum symbol length is unspecified. +.P +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4\|095 external +symbols total. A diagnostic message is written to standard output if +the implementation-defined limit is exceeded; other actions are +unspecified. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful compilation or link edit. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When +.IR fort77 +encounters a compilation error, it shall write a diagnostic to standard +error and continue to compile other source code operands. It shall +return a non-zero exit status, but it is implementation-defined +whether an object module is created. If the link edit is unsuccessful, +a diagnostic message shall be written to standard error, and +.IR fort77 +shall exit with a non-zero status. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The following usage example compiles +.BR xyz.f +and creates the executable file +.BR foo : +.sp +.RS 4 +.nf +\fB +fort77 \(mio foo xyz.f +.fi \fR +.P +.RE +.P +The following example compiles +.BR xyz.f +and creates the object file +.BR xyz.o : +.sp +.RS 4 +.nf +\fB +fort77 \(mic xyz.f +.fi \fR +.P +.RE +.P +The following example compiles +.BR xyz.f +and creates the executable file +.BR a.out : +.sp +.RS 4 +.nf +\fB +fort77 xyz.f +.fi \fR +.P +.RE +.P +The following example compiles +.BR xyz.f , +links it with +.BR b.o , +and creates the executable +.BR a.out : +.sp +.RS 4 +.nf +\fB +fort77 xyz.f b.o +.fi \fR +.P +.RE +.SH RATIONALE +The name of this utility was chosen as +.IR fort77 +to parallel the renaming of the C compiler. The name +.IR f77 +was not chosen to avoid problems with historical implementations. The +ANSI\ X3.9\(hy1978 standard was selected as a normative reference because the ISO/IEC version +of FORTRAN-77 has been superseded by the ISO/IEC\ 1539:\|1991 standard. +.P +The file inclusion and symbol definition +.BR #define +mechanisms used by the +.IR c99 +utility were not included in this volume of POSIX.1\(hy2008\(emeven though they are commonly +implemented\(emsince there is no requirement that the FORTRAN compiler +use the C preprocessor. +.P +The +.BR \(mionetrip +option was not included in this volume of POSIX.1\(hy2008, even though many historical compilers +support it, because it is derived from FORTRAN-66; it is an anachronism +that should not be perpetuated. +.P +Some implementations produce compilation listings. This aspect of +FORTRAN has been left unspecified because there was controversy +concerning the various methods proposed for implementing it: a +.BR \(miV +option overlapped with historical vendor practice and a naming +convention of creating files with +.BR .l +suffixes collided with historical +.IR lex +file naming practice. +.P +There is no +.BR \(miI +option in this version of this volume of POSIX.1\(hy2008 to specify a directory for file +inclusion. An INCLUDE directive has been a part of the Fortran-90 +discussions, but an interface supporting that standard is not in the +current scope. +.P +It is noted that many FORTRAN compilers produce an object module even +when compilation errors occur; during a subsequent compilation, the +compiler may patch the object module rather than recompiling all the +code. Consequently, it is left to the implementor whether or not an +object file is created. +.P +A reference to MIL-STD-1753 +was removed from an early proposal in response to a request from the +POSIX FORTRAN-binding standard developers. It was not the intention of +the standard developers to require certification of the FORTRAN +compiler, and IEEE\ Std\ 1003.9\(hy1992 does not specify the military standard or any +special preprocessing requirements. Furthermore, use of that document +would have been inappropriate for an international standard. +.P +The specification of optimization has been subject to changes through +early proposals. At one time, +.BR \(miO +and +.BR \(miN +were Booleans: optimize and do not optimize (with an unspecified +default). Some historical practice led this to be changed to: +.IP "\fB\(miO\fR\ 0" 10 +No optimization. +.IP "\fB\(miO\fR\ 1" 10 +Some level of optimization. +.IP "\fB\(miO\ \fIn\fR" 10 +Other, unspecified levels of optimization. +.P +It is not always clear whether ``good code generation'' is the same +thing as optimization. Simple optimizations of local actions do not +usually affect the semantics of a program. The +.BR \(miO +0 option has been included to accommodate the very particular nature of +scientific calculations in a highly optimized environment; compilers +make errors. Some degree of optimization is expected, even if it is not +documented here, and the ability to shut it off completely could be +important when porting an application. An implementation may treat +.BR \(miO +0 as ``do less than normal'' if it wishes, but this is only meaningful +if any of the operations it performs can affect the semantics of a +program. It is highly dependent on the implementation whether doing +less than normal is logical. It is not the intent of the +.BR \(miO +0 option to ask for inefficient code generation, but rather to assure +that any semantically visible optimization is suppressed. +.P +The specification of standard library access is consistent with the C +compiler specification. Implementations are not required to have +.BR /usr/lib/libf.a , +as many historical implementations do, but if not they are required to +recognize +.BR f +as a token. +.P +External symbol size limits are in normative text; conforming +applications need to know these limits. However, the minimum maximum +symbol length should be taken as a constraint on a conforming +application, not on an implementation, and consequently the action +taken for a symbol exceeding the limit is unspecified. The minimum size +for the external symbol table was added for similar reasons. +.P +The CONSEQUENCES OF ERRORS section clearly specifies the behavior of +the compiler when compilation or link-edit errors occur. The behavior +of several historical implementations was examined, and the choice was +made to be silent on the status of the executable, or +.BR a.out , +file in the face of compiler or linker errors. If a linker writes the +executable file, then links it on disk with +\fIlseek\fR()s +and +\fIwrite\fR()s, +the partially linked executable file can be left on disk and its +execute bits turned off if the link edit fails. However, if the linker +links the image in memory before writing the file to disk, it need not +touch the executable file (if it already exists) because the link edit +fails. Since both approaches are historical practice, a conforming +application shall rely on the exit status of +.IR fort77 , +rather than on the existence or mode of the executable file. +.P +The +.BR \(mig +and +.BR \(mis +options are not specified as mutually-exclusive. Historically, these two +options have been mutually-exclusive, but because both are so loosely +specified, it seemed appropriate to leave their interaction +unspecified. +.P +The requirement that conforming applications specify compiler options +separately is to reserve the multi-character option name space for +vendor-specific compiler options, which are known to exist in many +historical implementations. Implementations are not required to +recognize, for example, +.BR \(migc +as if it were +.BR \(mig +.BR \(mic ; +nor are they forbidden from doing so. The SYNOPSIS shows all of the +options separately to highlight this requirement on applications. +.P +Echoing filenames to standard error is considered a diagnostic message +because it would otherwise be difficult to associate an error message +with the erring file. They are described with ``may'' to allow +implementations to use other methods of identifying files and to +parallel the description in +.IR c99 . +.SH "FUTURE DIRECTIONS" +A compilation system based on the ISO/IEC\ 1539:\|1991 standard may be considered for a +future version; it may have a different utility name from +.IR fort77 . +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIasa\fR\^", +.IR "\fIc99\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/fuser.1p b/man-pages-posix-2013-a/man1p/fuser.1p new file mode 100644 index 0000000..1ded533 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/fuser.1p @@ -0,0 +1,247 @@ +'\" et +.TH FUSER "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fuser +\(em list process IDs of all processes that have one or more files open +.SH SYNOPSIS +.LP +.nf +fuser \fB[\fR\(micfu\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR fuser +utility shall write to standard output the process IDs of processes +running on the local system that have one or more named files open. +For block special devices, all processes using any file on that device +are listed. +.P +The +.IR fuser +utility shall write to standard error additional information about the +named files indicating how the file is being used. +.P +Any output for processes running on remote systems that have a named +file open is unspecified. +.P +A user may need appropriate privileges to invoke the +.IR fuser +utility. +.SH OPTIONS +The +.IR fuser +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fR" 10 +The file is treated as a mount point and the utility shall report +on any files open in the file system. +.IP "\fB\(mif\fR" 10 +The report shall be only for the named files. +.IP "\fB\(miu\fR" 10 +The user name, in parentheses, associated with each process ID written +to standard output shall be written to standard error. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fP" 10 +A pathname on which the file or file system is to be reported. +.SH STDIN +Not used. +.SH "INPUT FILES" +The user database. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fuser : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR fuser +utility shall write the process ID for each process using each file +given as an operand to standard output in the following format: +.sp +.RS 4 +.nf +\fB +"%d", <\fIprocess_id\fR> +.fi \fR +.P +.RE +.SH STDERR +The +.IR fuser +utility shall write diagnostic messages to standard error. +.P +The +.IR fuser +utility also shall write the following to standard error: +.IP " *" 4 +The pathname of each named file is written followed immediately by a +. +.IP " *" 4 +For each process ID written to standard output, the character +.BR 'c' +shall be written to standard error if the process is using the file as +its current directory and the character +.BR 'r' +shall be written to standard error if the process is using the file as +its root directory. Implementations may write other alphabetic +characters to indicate other uses of files. +.IP " *" 4 +When the +.BR \(miu +option is specified, characters indicating the use of the file shall be +followed immediately by the user name, in parentheses, corresponding to +the real user ID of the process. If the user name cannot be resolved from +the real user ID of the process, the real user ID of the process shall +be written instead of the user name. +.P +When standard output and standard error are directed to the same file, +the output shall be interleaved so that the filename appears at the +start of each line, followed by the process ID and characters +indicating the use of the file. Then, if the +.BR \(miu +option is specified, the user name or user ID for each process using +that file shall be written. +.P +A + +shall be written to standard error after the last output +described above for each +.IR file +operand. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The command: +.sp +.RS 4 +.nf +\fB +fuser \(mifu . +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +the current directory and writes to standard error an indication of how +those processes are using the directory and the user names associated +with the processes that are using the current directory. +.sp +.RS 4 +.nf +\fB +fuser \(mic <\fImount point\fR> +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +any file in the file system which is mounted on <\fImount point\fR> +and writes to standard error an indication of how those processes are +using the files. +.sp +.RS 4 +.nf +\fB +fuser <\fImount point\fR> +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +the file which is named by <\fImount point\fR> and writes to standard +error an indication of how those processes are using the file. +.sp +.RS 4 +.nf +\fB +fuser <\fIblock device\fR> +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +any file which is on the device named by <\fIblock device\fR> and +writes to standard error an indication of how those processes are using +the file. +.sp +.RS 4 +.nf +\fB +fuser \(mif <\fIblock device\fR> +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +the file <\fIblock device\fR> itself and writes to standard error an +indication of how those processes are using the file. +.SH RATIONALE +The definition of the +.IR fuser +utility follows existing practice. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/gencat.1p b/man-pages-posix-2013-a/man1p/gencat.1p new file mode 100644 index 0000000..8fa40d2 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/gencat.1p @@ -0,0 +1,289 @@ +'\" et +.TH GENCAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gencat +\(em generate a formatted message catalog +.SH SYNOPSIS +.LP +.nf +gencat \fIcatfile msgfile\fR... +.fi +.SH DESCRIPTION +The +.IR gencat +utility shall merge the message text source file +.IR msgfile +into a formatted message catalog +.IR catfile . +The file +.IR catfile +shall be created if it does not already exist. If +.IR catfile +does exist, its messages shall be included in the new +.IR catfile . +If set and message numbers collide, the new message text defined in +.IR msgfile +shall replace the old message text currently contained in +.IR catfile . +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIcatfile\fR" 10 +A pathname of the formatted message catalog. If +.BR '\(mi' +is specified, standard output shall be used. The format of the message +catalog produced is unspecified. +.IP "\fImsgfile\fR" 10 +A pathname of a message text source file. If +.BR '\(mi' +is specified for an instance of +.IR msgfile , +standard input shall be used. The format of message text source files +is defined in the EXTENDED DESCRIPTION section. +.SH STDIN +The standard input shall not be used unless a +.IR msgfile +operand is specified as +.BR '\(mi' . +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR gencat : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall not be used unless the +.IR catfile +operand is specified as +.BR '\(mi' . +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The content of a message text file shall be in the format defined as +follows. Note that the fields of a message text source line are +separated by a single + +character. Any other + +characters are considered to be part of the subsequent field. +.IP "\fB$set\ \fIn\ comment\fR" 10 +.br +This line specifies the set identifier of the following messages until +the next +.BR $set +or end-of-file appears. The +.IR n +denotes the set identifier, which is defined as a number in the range +[1, +{NL_SETMAX}] +(see the +.IR +header defined in the Base Definitions volume of POSIX.1\(hy2008). The application shall ensure that set +identifiers are presented in ascending order within a single source +file, but need not be contiguous. Any string following the set +identifier shall be treated as a comment. If no +.BR $set +directive is specified in a message text source file, all messages +shall be located in an implementation-defined default message set +NL_SETD (see the +.IR +header defined in the Base Definitions volume of POSIX.1\(hy2008). +.IP "\fB$delset\ \fIn\ comment\fR" 10 +.br +This line deletes message set +.IR n +from an existing message catalog. The +.IR n +denotes the set number [1, +{NL_SETMAX}]. +Any string following the set number shall be treated as a comment. +.IP "\fB$\ \fIcomment\fR" 10 +A line beginning with +.BR '$' +followed by a + +shall be treated as a comment. +.IP "\fIm\ message-text\fR" 10 +.br +The +.IR m +denotes the message identifier, which is defined as a number in the +range [1, +{NL_MSGMAX}] +(see the +.IR +header). The +.IR message-text +shall be stored in the message catalog with the set identifier +specified by the last +.BR $set +directive, and with message identifier +.IR m . +If the +.IR message-text +is empty, and a + +field separator is present, an empty string shall be stored +in the message catalog. If a message source line has a message number, +but neither a field separator nor +.IR message-text , +the existing message with that number (if any) shall be deleted from +the catalog. The application shall ensure that message identifiers are +in ascending order within a single set, but need not be contiguous. The +application shall ensure that the length of +.IR message-text +is in the range [0, +{NL_TEXTMAX}] +(see the +.IR +header). +.IP "\fB$quote\ \fIn\fR" 10 +This line specifies an optional quote character +.IR c , +which can be used to surround +.IR message-text +so that trailing + +characters or null (empty) messages are visible in a message source +line. By default, or if an empty +.BR $quote +directive is supplied, no quoting of +.IR message-text +shall be recognized. +.P +Empty lines in a message text source file shall be ignored. The +effects of lines starting with any character other than those defined +above are implementation-defined. +.P +Text strings can contain the special characters and escape sequences +defined in the following table: +.TS +center tab(@) box; +cB | cB | cB +l | l | lf5. +Description@Symbol@Sequence +_ +@NL(LF)@\en +Horizontal-tab@HT@\et +@VT@\ev +@BS@\eb +@CR@\er +@FF@\ef +Backslash@\fR\e\fP@\e\e +Bit pattern@\fRddd\fP@\eddd +.TE +.P +The escape sequence +.BR \(dq\eddd\(dq +consists of + +followed by one, two, or three octal digits, which shall be taken to +specify the value of the desired character. If the character following a + +is not one of those specified, the + +shall be ignored. +.P +A + +followed by a + +is also used to continue a string on the following line. Thus, the +following two lines describe a single message string: +.sp +.RS 4 +.nf +\fB +1 This line continues \e +to the next line +.fi \fR +.P +.RE +.P +which shall be equivalent to: +.sp +.RS 4 +.nf +\fB +1 This line continues to the next line +.fi \fR +.P +.RE +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Message catalogs produced by +.IR gencat +are binary encoded, meaning that their portability cannot be guaranteed +between different types of machine. Thus, just as C programs need to +be recompiled for each type of machine, so message catalogs must be +recreated via +.IR gencat . +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/get.1p b/man-pages-posix-2013-a/man1p/get.1p new file mode 100644 index 0000000..c1f1e81 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/get.1p @@ -0,0 +1,848 @@ +'\" et +.TH GET "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +get +\(em get a version of an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +get \fB[\fR\(mibegkmnlLpst\fB] [\fR\(mic \fIcutoff\fB] [\fR\(mii \fIlist\fB] [\fR\(mir \fISID\fB] [\fR\(mix \fIlist\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR get +utility shall generate a text file from each named SCCS +.IR file +according to the specifications given by its options. +.P +The generated text shall normally be written into a file called the +.BR g-file +whose name is derived from the SCCS filename by simply removing the +leading +.BR \(dqs.\(dq . +.SH OPTIONS +The +.IR get +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mir\ \fISID\fR" 10 +Indicate the SCCS Identification String (SID) of the version (delta) +of an SCCS file to be retrieved. The table shows, for the most useful +cases, what version of an SCCS file is retrieved (as well as the SID of +the version to be eventually created by +.IR delta +if the +.BR \(mie +option is also used), as a function of the SID specified. +.IP "\fB\(mic\ \fIcutoff\fR" 10 +Indicate the +.IR cutoff +date-time, in the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIYY\fB[\fIMM\fB[\fIDD\fB[\fIHH\fB[\fIMM\fB[\fISS\fB]]]]]\fR +.fi \fR +.P +.RE +.P +For the +.IR YY +component, values in the range [69,99] shall refer to years 1969 to +1999 inclusive, and values in the range [00,68] shall refer to years +2000 to 2068 inclusive. +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.P +No changes (deltas) to the SCCS file that were created after the +specified +.IR cutoff +date-time shall be included in the generated text file. Units omitted +from the date-time default to their maximum possible values; for +example, +.BR \(mic +7502 is equivalent to +.BR \(mic +750228235959. +.P +Any number of non-numeric characters may separate the various 2-digit +pieces of the +.IR cutoff +date-time. This feature allows the user to specify a +.IR cutoff +date in the form: +.BR \(mic +"77/2/2\09:22:25". +.RE +.IP "\fB\(mie\fR" 10 +Indicate that the +.IR get +is for the purpose of editing or making a change (delta) to the SCCS +file via a subsequent use of +.IR delta . +The +.BR \(mie +option used in a +.IR get +for a particular version (SID) of the SCCS file shall prevent further +.IR get +commands from editing on the same SID until +.IR delta +is executed or the +.BR j +(joint edit) flag is set in the SCCS file. Concurrent use of +.IR get +.BR \(mie +for different SIDs is always allowed. +.RS 10 +.P +If the +.BR g-file +generated by +.IR get +with a +.BR \(mie +option is accidentally ruined in the process of editing, it may be +regenerated by re-executing the +.IR get +command with the +.BR \(mik +option in place of the +.BR \(mie +option. +.P +SCCS file protection specified via the ceiling, floor, and authorized +user list stored in the SCCS file shall be enforced when the +.BR \(mie +option is used. +.RE +.IP "\fB\(mib\fR" 10 +Use with the +.BR \(mie +option to indicate that the new delta should have an SID in a new +branch as shown in the table below. This option shall be ignored if the +.BR b +flag is not present in the file or if the retrieved delta is not a leaf +delta. (A leaf delta is one that has no successors on the SCCS file tree.) +.RS 10 +.TP 10 +.BR Note: +A branch delta may always be created from a non-leaf delta. +.P +.RE +.IP "\fB\(mii\ \fIlist\fR" 10 +Indicate a +.IR list +of deltas to be included (forced to be applied) in the creation of the +generated file. The +.IR list +has the following syntax: +.RS 10 +.sp +.RS 4 +.nf +\fB + ::= | , + ::= SID | SID \(mi SID +.fi \fR +.P +.RE +.P +SID, the SCCS Identification of a delta, may be in any form shown in +the ``SID Specified'' column of the table in the EXTENDED DESCRIPTION +section, except that the result of supplying a partial SID is +unspecified. A diagnostic message shall be written if the first SID in +the range is not an ancestor of the second SID in the range. +.RE +.IP "\fB\(mix\ \fIlist\fR" 10 +Indicate a +.IR list +of deltas to be excluded (forced not to be applied) in the creation of +the generated file. See the +.BR \(mii +option for the +.IR list +format. +.IP "\fB\(mik\fR" 10 +Suppress replacement of identification keywords (see below) in the +retrieved text by their value. The +.BR \(mik +option shall be implied by the +.BR \(mie +option. +.IP "\fB\(mil\fR" 10 +Write a delta summary into an +.BR l-file . +.IP "\fB\(miL\fR" 10 +Write a delta summary to standard output. All informative output that +normally is written to standard output shall be written to standard +error instead, unless the +.BR \(mis +option is used, in which case it shall be suppressed. +.IP "\fB\(mip\fR" 10 +Write the text retrieved from the SCCS file to the standard output. No +.BR g-file +shall be created. All informative output that normally goes to the +standard output shall go to standard error instead, unless the +.BR \(mis +option is used, in which case it shall disappear. +.IP "\fB\(mis\fR" 10 +Suppress all informative output normally written to standard output. +However, fatal error messages (which shall always be written to the +standard error) shall remain unaffected. +.IP "\fB\(mim\fR" 10 +Precede each text line retrieved from the SCCS file by the SID of the +delta that inserted the text line in the SCCS file. The format shall be: +.RS 10 +.sp +.RS 4 +.nf +\fB +"%s\et%s", <\fISID\fR>, <\fItext line\fR> +.fi \fR +.P +.RE +.RE +.IP "\fB\(min\fR" 10 +Precede each generated text line with the %\fBM\fP% identification +keyword value (see below). The format shall be: +.RS 10 +.sp +.RS 4 +.nf +\fB +"%s\et%s", <\fI%M% value\fR>, <\fItext line\fR> +.fi \fR +.P +.RE +.P +When both the +.BR \(mim +and +.BR \(min +options are used, the <\fItext\ line\fP> shall be replaced by the +.BR \(mim +option-generated format. +.RE +.IP "\fB\(mig\fR" 10 +Suppress the actual retrieval of text from the SCCS file. It is +primarily used to generate an +.BR l-file , +or to verify the existence of a particular SID. +.IP "\fB\(mit\fR" 10 +Use to access the most recently created (top) delta in a given release +(for example, +.BR "\(mir 1" ), +or release and level (for example, +.BR "\(mir 1.2" ). +.br +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR get +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input is +taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only if the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +The SCCS files shall be files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR get : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output (or standard error, if +the +.BR \(mip +option is used). +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fR" 10 +Determine the timezone in which the times and dates written in the +SCCS file are evaluated. If the +.IR TZ +variable is unset or NULL, an unspecified system default timezone is +used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +For each file processed, +.IR get +shall write to standard output the SID being accessed and the number of +lines retrieved from the SCCS file, in the following format: +.sp +.RS 4 +.nf +\fB +"%s\en%d lines\en", <\fISID\fR>, <\fInumber of lines\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mie +option is used, the SID of the delta to be made shall appear after the +SID accessed and before the number of lines generated, in the POSIX +locale: +.sp +.RS 4 +.nf +\fB +"%s\ennew delta %s\en%d lines\en", <\fISID accessed\fR>, + <\fISID to be made\fR>, <\fInumber of lines\fR> +.fi \fR +.P +.RE +.P +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of the lines +shown in one of the preceding formats: +.sp +.RS 4 +.nf +\fB +"\en%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(miL +option is used, a delta summary shall be written following the format +specified below for +.BR l-files . +.P +If the +.BR \(mii +option is used, included deltas shall be listed following the notation, +in the POSIX locale: +.sp +.RS 4 +.nf +\fB +"Included:\en" +.fi \fR +.P +.RE +.P +If the +.BR \(mix +option is used, excluded deltas shall be listed following the notation, +in the POSIX locale: +.sp +.RS 4 +.nf +\fB +"Excluded:\en" +.fi \fR +.P +.RE +.P +If the +.BR \(mip +or +.BR \(miL +options are specified, the standard output shall consist of the text +retrieved from the SCCS file. +.SH STDERR +The standard error shall be used only for diagnostic messages, except +if the +.BR \(mip +or +.BR \(miL +options are specified, it shall include all informative messages +normally sent to standard output. +.SH "OUTPUT FILES" +Several auxiliary files may be created by +.IR get . +These files are known generically as the +.BR g-file , +.BR l-file , +.BR p-file , +and +.BR z-file . +The letter before the + +is called the +.IR tag . +An auxiliary filename shall be formed from the SCCS filename: the +application shall ensure that the last component of all SCCS filenames +is of the form +.BR s. \c +.IR module-name ; +the auxiliary files shall be named by replacing the leading +.BR s +with the tag. The +.BR g-file +shall be an exception to this scheme: the +.BR g-file +is named by removing the +.BR s. +prefix. For example, for +.BR s.xyz.c , +the auxiliary filenames would be +.BR xyz.c , +.BR l.xyz.c , +.BR p.xyz.c , +and +.BR z.xyz.c , +respectively. +.P +The +.BR g-file , +which contains the generated text, shall be created in the current +directory (unless the +.BR \(mip +option is used). A +.BR g-file +shall be created in all cases, whether or not any lines of text were +generated by the +.IR get . +It shall be owned by the real user. If the +.BR \(mik +option is used or implied, the +.BR g-file +shall be writable by the owner only (read-only for everyone else); +otherwise, it shall be read-only. Only the real user need have write +permission in the current directory. +.P +The +.BR l-file +shall contain a table showing which deltas were applied in generating +the retrieved text. The +.BR l-file +shall be created in the current directory if the +.BR \(mil +option is used; it shall be read-only and it is owned by the real user. +Only the real user need have write permission in the current +directory. +.P +Lines in the +.BR l-file +shall have the following format: +.sp +.RS 4 +.nf +\fB +"%c%c%c %s\et%s %s\en", <\fIcode1\fR>, <\fIcode2\fR>, <\fIcode3\fR>, + <\fISID\fR>, <\fIdate-time\fR>, <\fIlogin\fR> +.fi \fR +.P +.RE +.P +where the entries are: +.IP "<\fIcode1\fP>" 10 +A + +if the delta was applied; +.BR '*' +otherwise. +.IP "<\fIcode2\fP>" 10 +A + +if the delta was applied or was not applied and ignored; +.BR '*' +if the delta was not applied and was not ignored. +.IP "<\fIcode3\fP>" 10 +A character indicating a special reason why the delta was or was not +applied: +.RS 10 +.IP "\fBI\fP" 6 +Included. +.IP "\fBX\fP" 6 +Excluded. +.IP "\fBC\fP" 6 +Cut off (by a +.BR \(mic +option). +.RE +.IP "<\fIdate-time\fP>" 10 +Date and time (using the format of the +.IR date +utility's +.BR %y /\c +.BR %m /\c +.BR %d +.BR %T +conversion specification format) of creation. +.IP "<\fIlogin\fP>" 10 +Login name of person who created +.IR delta . +.P +The comments and MR data shall follow on subsequent lines, indented one +. +A blank line shall terminate each entry. +.P +The +.BR p-file +shall be used to pass information resulting from a +.IR get +with a +.BR \(mie +option along to +.IR delta . +Its contents shall also be used to prevent a subsequent execution of +.IR get +with a +.BR \(mie +option for the same SID until +.IR delta +is executed or the joint edit flag, +.BR j , +is set in the SCCS file. The +.BR p-file +shall be created in the directory containing the SCCS file and the +application shall ensure that the effective user has write permission +in that directory. It shall be writable by owner only, and owned +by the effective user. Each line in the +.BR p-file +shall have the following format: +.sp +.RS 4 +.nf +\fB +"%s %s %s %s%s%s\en", <\fIg-file SID\fR>, + <\fISID of new delta\fR>, <\fIlogin-name of real user\fR>, + <\fIdate-time\fR>, <\fIi-value\fR>, <\fIx-value\fR> +.fi \fR +.P +.RE +.P +where <\fIi\(hyvalue\fP> uses the format +.BR \(dq\^\(dq +if no +.BR \(mii +option was specified, and shall use the format: +.sp +.RS 4 +.nf +\fB +" \(mii%s", <\(mii option \fIoption-argument\fR> +.fi \fR +.P +.RE +.P +if a +.BR \(mii +option was specified and <\fIx\(hyvalue\fP> uses the format +.BR \(dq\^\(dq +if no +.BR \(mix +option was specified, and shall use the format: +.sp +.RS 4 +.nf +\fB +" \(mix%s", <\(mix option \fIoption-argument\fR> +.fi \fR +.P +.RE +.P +if a +.BR \(mix +option was specified. There can be an arbitrary number of lines in the +.BR p-file +at any time; no two lines shall have the same new delta SID. +.P +The +.BR z-file +shall serve as a lock-out mechanism against simultaneous updates. Its +contents shall be the binary process ID of the command (that is, +.IR get ) +that created it. The +.BR z-file +shall be created in the directory containing the SCCS file for the +duration of +.IR get . +The same protection restrictions as those for the +.BR p-file +shall apply for the +.BR z-file . +The +.BR z-file +shall be created read-only. +.br +.SH "EXTENDED DESCRIPTION" +.TS +center tab(@) box; +cB s s s s +cB cB cB cB cB +cB cB cB cB cB +l c lw(4.5c) l l. +Determination of SCCS Identification String += +SID*@\(mib Keyletter@Other@SID@SID of Delta +Specified@Used\(dg@Conditions@Retrieved@to be Created +.sp 1.5p += +none\(dd@no@R defaults to mR@mR.mL@mR.(mL+1) +_ +none\(dd@yes@R defaults to mR@mR.mL@mR.mL.(mB+1).1 +.sp 1.5p += +R@no@R > mR@mR.mL@R.1*** +_ +R@no@R = mR@mR.mL@mR.(mL+1) +_ +R@yes@R > mR@mR.mL@mR.mL.(mB+1).1 +_ +R@yes@R = mR@mR.mL@mR.mL.(mB+1).1 +_ +R@\(mi@T{ +R < mR and +R does not exist +T}@hR.mL**@hR.mL.(mB+1).1 +_ +R@\(mi@T{ +Trunk successor in release > R +and R exists +T}@R.mL@R.mL.(mB+1).1 +.sp 1.5p += +R.L@no@No trunk successor@R.L@R.(L+1) +_ +R.L@yes@No trunk successor@R.L@R.L.(mB+1).1 +_ +R.L@\(mi@T{ +Trunk successor +in release \(>= R +T}@R.L@R.L.(mB+1).1 +.sp 1.5p += +R.L.B@no@No branch successor@R.L.B.mS@R.L.B.(mS+1) +_ +R.L.B@yes@No branch successor@R.L.B.mS@R.L.(mB+1).1 +.sp 1.5p += +R.L.B.S@no@No branch successor@R.L.B.S@R.L.B.(S+1) +_ +R.L.B.S@yes@No branch successor@R.L.B.S@R.L.(mB+1).1 +_ +R.L.B.S@\(mi@Branch successor@R.L.B.S@R.L.(mB+1).1 +.TE +.IP * 8 +R, L, B, and S are the release, level, branch, and sequence components +of the SID, respectively; m means maximum. Thus, for example, R.mL +means ``the maximum level number within release R''; R.L.(mB+1).1 means +``the first sequence number on the new branch (that is, maximum branch +number plus one) of level L within release R''. Note that if the SID +specified is of the form R.L, R.L.B, or R.L.B.S, each of the specified +components shall exist. +.IP ** 8 +hR is the highest existing release that is lower than the specified, +nonexistent, release R. +.IP *** 8 +This is used to force creation of the first delta in a new release. +.IP "\(dg" 8 +The +.BR \(mib +option is effective only if the +.BR b +flag is present in the file. An entry of +.BR '\(mi' +means ``irrelevant''. +.IP "\(dd" 8 +This case applies if the +.BR d +(default SID) flag is not present in the file. If the +.BR d +flag is present in the file, then the SID obtained from the +.BR d +flag is interpreted as if it had been specified on the command line. +Thus, one of the other cases in this table applies. +.SS "System Date and Time" +.P +When a +.BR g-file +is generated, the creation time of deltas in the SCCS file may be taken +into account. If any of these times are apparently in the future, the +behavior is unspecified. +.SS "Identification Keywords" +.P +Identifying information shall be inserted into the text retrieved from +the SCCS file by replacing identification keywords with their value +wherever they occur. The following keywords may be used in the text +stored in an SCCS file: +.IP "%\fBM\fP%" 10 +Module name: either the value of the +.BR m +flag in the file, or if absent, the name of the SCCS file with the +leading +.BR s. +removed. +.IP "%\fBI\fP%" 10 +SCCS identification (SID) (%\fBR\fR%.%\fBL\fR% or +%\fBR\fR%.%\fBL\fR%.%\fBB\fR%.%\fBS\fR%) of the retrieved text. +.IP "%\fBR\fP%" 10 +Release. +.IP "%\fBL\fP%" 10 +Level. +.IP "%\fBB\fP%" 10 +Branch. +.IP "%\fBS\fP%" 10 +Sequence. +.IP "%\fBD\fP%" 10 +Current date (\fIYY\fR/\fIMM\fR/\fIDD\fR). +.IP "%\fBH\fP%" 10 +Current date (\fIMM\fR/\fIDD\fR/\fIYY\fR). +.IP "%\fBT\fP%" 10 +Current time (\fIHH\fR:\fIMM\fR:\fISS\fR). +.IP "%\fBE\fP%" 10 +Date newest applied delta was created (\fIYY\fR/\fIMM\fR/\fIDD\fR). +.IP "%\fBG\fP%" 10 +Date newest applied delta was created (\fIMM\fR/\fIDD\fR/\fIYY\fR). +.IP "%\fBU\fP%" 10 +Time newest applied delta was created (\fIHH\fR:\fIMM\fR:\fISS\fR). +.IP "%\fBY\fP%" 10 +Module type: value of the +.BR t +flag in the SCCS file. +.IP "%\fBF\fP%" 10 +SCCS filename. +.IP "%\fBP\fP%" 10 +SCCS absolute pathname. +.IP "%\fBQ\fP%" 10 +The value of the +.BR q +flag in the file. +.IP "%\fBC\fP%" 10 +Current line number. This keyword is intended for identifying messages +output by the program, such as ``this should not have happened'' type +errors. It is not intended to be used on every line to provide +sequence numbers. +.IP "%\fBZ\fP%" 10 +The four-character string +.BR \(dq@(#)\(dq +recognizable by +.IR what . +.IP "%\fBW\fP%" 10 +A shorthand notation for constructing +.IR what +strings: +.RS 10 +.sp +.RS 4 +.nf +\fB +%\^W\^%=%\^Z\^%%\^M\^%%\^I\^% +.fi \fR +.P +.RE +.RE +.IP "%\fBA\fP%" 10 +Another shorthand notation for constructing +.IR what +strings: +.RS 10 +.sp +.RS 4 +.nf +\fB +%\^A\^%=%\^Z\^%%\^Y\^%%\^M\^%%\^I\^%%\^Z\^% +.fi \fR +.P +.RE +.RE +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Problems can arise if the system date and time have been modified (for +example, put forward and then back again, or unsynchronized clocks +across a network) and can also arise when different values of the +.IR TZ +environment variable are used. +.P +Problems of a similar nature can also arise for the operation of the +.IR delta +utility, which compares the previous file body against the working file +as part of its normal operation. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/getconf.1p b/man-pages-posix-2013-a/man1p/getconf.1p new file mode 100644 index 0000000..484bdf3 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/getconf.1p @@ -0,0 +1,443 @@ +'\" et +.TH GETCONF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getconf +\(em get configuration values +.SH SYNOPSIS +.LP +.nf +getconf \fB[\fR\(miv specification\fB] \fIsystem_var\fR +.P +getconf \fB[\fR\(miv specification\fB] \fIpath_var pathname\fR +.fi +.SH DESCRIPTION +In the first synopsis form, the +.IR getconf +utility shall write to the standard output the value of the variable +specified by the +.IR system_var +operand. +.P +In the second synopsis form, the +.IR getconf +utility shall write to the standard output the value of the variable +specified by the +.IR path_var +operand for the path specified by the +.IR pathname +operand. +.P +The value of each configuration variable shall be determined as if it +were obtained by calling the function from which it is defined to be +available by this volume of POSIX.1\(hy2008 or by the System Interfaces volume of POSIX.1\(hy2008 (see the OPERANDS section). The +value shall reflect conditions in the current operating environment. +.SH OPTIONS +The +.IR getconf +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miv\ \fIspecification\fR" 10 +.br +Indicate a specific specification and version for which configuration +variables shall be determined. If this option is not specified, the +values returned correspond to an implementation default conforming +compilation environment. +.RS 10 +.P +If the command: +.sp +.RS 4 +.nf +\fB +getconf _POSIX_V7_ILP32_OFF32 +.fi \fR +.P +.RE +.P +does not write +.BR \(dq\(mi1\en\(dq +or +.BR \(dqundefined\en\(dq +to standard output, then commands of the form: +.sp +.RS 4 +.nf +\fB +getconf \(miv POSIX_V7_ILP32_OFF32 ... +.fi \fR +.P +.RE +.P +determine values for configuration variables corresponding to the +POSIX_V7_ILP32_OFF32 compilation environment specified in +.IR "\fIc99\fR\^", +the EXTENDED DESCRIPTION. +.P +If the command: +.sp +.RS 4 +.nf +\fB +getconf _POSIX_V7_ILP32_OFFBIG +.fi \fR +.P +.RE +.P +does not write +.BR \(dq\(mi1\en\(dq +or +.BR \(dqundefined\en\(dq +to standard output, then commands of the form: +.sp +.RS 4 +.nf +\fB +getconf \(miv POSIX_V7_ILP32_OFFBIG ... +.fi \fR +.P +.RE +.P +determine values for configuration variables corresponding to the +POSIX_V7_ILP32_OFFBIG compilation environment specified in +.IR "\fIc99\fR\^", +the EXTENDED DESCRIPTION. +.P +If the command: +.sp +.RS 4 +.nf +\fB +getconf _POSIX_V7_LP64_OFF64 +.fi \fR +.P +.RE +.P +does not write +.BR \(dq\(mi1\en\(dq +or +.BR \(dqundefined\en\(dq +to standard output, then commands of the form: +.sp +.RS 4 +.nf +\fB +getconf \(miv POSIX_V7_LP64_OFF64 ... +.fi \fR +.P +.RE +.P +determine values for configuration variables corresponding to the +POSIX_V7_LP64_OFF64 compilation environment specified in +.IR "\fIc99\fR\^", +the EXTENDED DESCRIPTION. +.P +If the command: +.sp +.RS 4 +.nf +\fB +getconf _POSIX_V7_LPBIG_OFFBIG +.fi \fR +.P +.RE +.P +does not write +.BR \(dq\(mi1\en\(dq +or +.BR \(dqundefined\en\(dq +to standard output, then commands of the form: +.sp +.RS 4 +.nf +\fB +getconf \(miv POSIX_V7_LPBIG_OFFBIG ... +.fi \fR +.P +.RE +.P +determine values for configuration variables corresponding to the +POSIX_V7_LPBIG_OFFBIG compilation environment specified in +.IR "\fIc99\fR\^", +the EXTENDED DESCRIPTION. +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIpath_var\fR" 10 +A name of a configuration variable. All of the variables in the +Variable column of the table in the DESCRIPTION of the +\fIfpathconf\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, without the enclosing braces, shall be +supported. The implementation may add other local variables. +.IP "\fIpathname\fR" 10 +A pathname for which the variable specified by +.IR path_var +is to be determined. +.IP "\fIsystem_var\fR" 10 +A name of a configuration variable. All of the following variables +shall be supported: +.RS 10 +.IP " *" 4 +The names in the Variable column of the table in the DESCRIPTION of the +\fIsysconf\fR() +function in the System Interfaces volume of POSIX.1\(hy2008, except for the entries corresponding to +_SC_CLK_TCK, _SC_GETGR_R_SIZE_MAX, and _SC_GETPW_R_SIZE_MAX, without +the enclosing braces. +.RS 4 +.P +For compatibility with earlier versions, the following variable names +shall also be supported: +POSIX2_C_BIND +POSIX2_C_DEV +POSIX2_CHAR_TERM +POSIX2_FORT_DEV +POSIX2_FORT_RUN +POSIX2_LOCALEDEF +POSIX2_SW_DEV +POSIX2_UPE +POSIX2_VERSION +.P +and shall be equivalent to the same name prefixed with an +. +This requirement may be removed in a future version. +.RE +.IP " *" 4 +The names of the symbolic constants used as the +.IR name +argument of the +\fIconfstr\fR() +function in the System Interfaces volume of POSIX.1\(hy2008, without the _CS_ prefix. +.IP " *" 4 +The names of the symbolic constants listed under the headings ``Maximum +Values'' and ``Minimum Values'' in the description of the +.IR +header in the Base Definitions volume of POSIX.1\(hy2008, without the enclosing braces. +.RS 4 +.P +For compatibility with earlier versions, the following variable names +shall also be supported: +POSIX2_BC_BASE_MAX +POSIX2_BC_DIM_MAX +POSIX2_BC_SCALE_MAX +POSIX2_BC_STRING_MAX +POSIX2_COLL_WEIGHTS_MAX +POSIX2_EXPR_NEST_MAX +POSIX2_LINE_MAX +POSIX2_RE_DUP_MAX +.P +and shall be equivalent to the same name prefixed with an +. +This requirement may be removed in a future version. +.RE +.P +The implementation may add other local values. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR getconf : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the specified variable is defined on the system and its value is +described to be available from the +\fIconfstr\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, its value shall be written in the +following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIvalue\fR> +.fi \fR +.P +.RE +.P +Otherwise, if the specified variable is defined on the system, its +value shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIvalue\fR> +.fi \fR +.P +.RE +.P +If the specified variable is valid, but is undefined on the system, +.IR getconf +shall write using the following format: +.sp +.RS 4 +.nf +\fB +"undefined\en" +.fi \fR +.P +.RE +.P +If the variable name is invalid or an error occurs, nothing shall be +written to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The specified variable is valid and information about its current state +was written successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The following example illustrates the value of +{NGROUPS_MAX}: +.sp +.RS 4 +.nf +\fB +getconf NGROUPS_MAX +.fi \fR +.P +.RE +.P +The following example illustrates the value of +{NAME_MAX} +for a specific directory: +.sp +.RS 4 +.nf +\fB +getconf NAME_MAX /usr +.fi \fR +.P +.RE +.P +The following example shows how to deal more carefully with results +that might be unspecified: +.sp +.RS 4 +.nf +\fB +if value=$(getconf PATH_MAX /usr); then + if [ "$value" = "undefined" ]; then + echo PATH_MAX in /usr is indeterminate. + else + echo PATH_MAX in /usr is $value. + fi +else + echo Error in getconf. +fi +.fi \fR +.P +.RE +.SH RATIONALE +The original need for this utility, and for the +\fIconfstr\fR() +function, was to provide a way of finding the configuration-defined +default value for the +.IR PATH +environment variable. Since +.IR PATH +can be modified by the user to include directories that could contain +utilities replacing the standard utilities, shell scripts need +a way to determine the system-supplied +.IR PATH +environment variable value that contains the correct search path for +the standard utilities. It was later suggested that access to the other +variables described in this volume of POSIX.1\(hy2008 could also be useful to applications. +.P +This functionality of +.IR getconf +would not be adequately subsumed by another command such as: +.sp +.RS 4 +.nf +\fB +grep \fIvar\fP /etc/conf +.fi \fR +.P +.RE +.P +because such a strategy would provide correct values for neither those +variables that can vary at runtime, nor those that can vary depending +on the path. +.P +Early proposal versions of +.IR getconf +specified exit status 1 when the specified variable was valid, but not +defined on the system. The output string +.BR \(dqundefined\(dq +is now used to specify this case with exit code 0 because so many +things depend on an exit code of zero when an invoked utility is +successful. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/getopts.1p b/man-pages-posix-2013-a/man1p/getopts.1p new file mode 100644 index 0000000..baf210d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/getopts.1p @@ -0,0 +1,445 @@ +'\" et +.TH GETOPTS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getopts +\(em parse utility options +.SH SYNOPSIS +.LP +.nf +getopts \fIoptstring name \fB[\fIarg\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR getopts +utility shall retrieve options and option-arguments from a list of +parameters. It shall support the Utility Syntax Guidelines 3 to 10, +inclusive, described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +Each time it is invoked, the +.IR getopts +utility shall place the value of the next option in the shell variable +specified by the +.IR name +operand and the index of the next argument to be processed in the shell +variable +.IR OPTIND . +Whenever the shell is invoked, +.IR OPTIND +shall be initialized to 1. +.P +When the option requires an option-argument, the +.IR getopts +utility shall place it in the shell variable +.IR OPTARG . +If no option was found, or if the option that was found does not have +an option-argument, +.IR OPTARG +shall be unset. +.P +If an option character not contained in the +.IR optstring +operand is found where an option character is expected, the shell +variable specified by +.IR name +shall be set to the + +(\c +.BR '?' ) +character. In this case, if the first character in +.IR optstring +is a + +(\c +.BR ':' ), +the shell variable +.IR OPTARG +shall be set to the option character found, but no output shall be +written to standard error; otherwise, the shell variable +.IR OPTARG +shall be unset and a diagnostic message shall be written to standard +error. This condition shall be considered to be an error detected in +the way arguments were presented to the invoking application, but shall +not be an error in +.IR getopts +processing. +.P +If an option-argument is missing: +.IP " *" 4 +If the first character of +.IR optstring +is a +, +the shell variable specified by +.IR name +shall be set to the + +character and the shell variable +.IR OPTARG +shall be set to the option character found. +.IP " *" 4 +Otherwise, the shell variable specified by +.IR name +shall be set to the + +character, the shell variable +.IR OPTARG +shall be unset, and a diagnostic message shall be written to standard +error. This condition shall be considered to be an error detected in +the way arguments were presented to the invoking application, but shall +not be an error in +.IR getopts +processing; a diagnostic message shall be written as stated, but the +exit status shall be zero. +.P +When the end of options is encountered, the +.IR getopts +utility shall exit with a return value greater than zero; the shell +variable +.IR OPTIND +shall be set to the index of the first operand, or the value +.BR \(dq$#\(dq +1 +if there are no operands; the +.IR name +variable shall be set to the + +character. Any of the following shall identify the end of options: +the first +.BR \(dq\(mi\|\(mi\(dq +argument that is not an option-argument, finding an argument that is +not an option-argument and does not begin with a +.BR '\(mi' , +or encountering an error. +.P +The shell variables +.IR OPTIND +and +.IR OPTARG +shall be local to the caller of +.IR getopts +and shall not be exported by default. +.P +The shell variable specified by the +.IR name +operand, +.IR OPTIND , +and +.IR OPTARG +shall affect the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +If the application sets +.IR OPTIND +to the value 1, a new set of parameters can be used: either the +current positional parameters or new +.IR arg +values. Any other attempt to invoke +.IR getopts +multiple times in a single shell execution environment with parameters +(positional parameters or +.IR arg +operands) that are not the same in all invocations, or with an +.IR OPTIND +value modified to be a value other than 1, produces unspecified +results. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIoptstring\fR" 10 +A string containing the option characters recognized by the utility +invoking +.IR getopts . +If a character is followed by a +, +the option shall be expected to have an argument, which should be supplied +as a separate argument. Applications should specify an option character +and its option-argument as separate arguments, but +.IR getopts +shall interpret the characters following an option character requiring +arguments as an argument whether or not this is done. An explicit null +option-argument need not be recognized if it is not supplied as a +separate argument when +.IR getopts +is invoked. (See also the +\fIgetopt\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008.) The characters + +and + +shall not be used as option characters by an application. The use of +other option characters that are not alphanumeric produces unspecified +results. If the option-argument is not supplied as a separate argument +from the option character, the value in +.IR OPTARG +shall be stripped of the option character and the +.BR '\(mi' . +The first character in +.IR optstring +determines how +.IR getopts +behaves if an option character is not known or an option-argument is +missing. +.IP "\fIname\fR" 10 +The name of a shell variable that shall be set by the +.IR getopts +utility to the option character that was found. +.P +The +.IR getopts +utility by default shall parse positional parameters passed to the +invoking shell procedure. If +.IR arg s +are given, they shall be parsed instead of the positional parameters. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR getopts : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIOPTIND\fP" 10 +This variable shall be used by the +.IR getopts +utility as the index of the next argument to be processed. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Whenever an error is detected and the first character in the +.IR optstring +operand is not a + +(\c +.BR ':' ), +a diagnostic message shall be written to standard error with the +following information in an unspecified format: +.IP " *" 4 +The invoking program name shall be identified in the message. The +invoking program name shall be the value of the shell special parameter +0 (see +.IR "Section 2.5.2" ", " "Special Parameters") +at the time the +.IR getopts +utility is invoked. A name equivalent to: +.RS 4 +.sp +.RS 4 +.nf +\fB +basename "$0" +.fi \fR +.P +.RE +.P +may be used. +.RE +.IP " *" 4 +If an option is found that was not specified in +.IR optstring , +this error is identified and the invalid option character shall be +identified in the message. +.IP " *" 4 +If an option requiring an option-argument is found, but an +option-argument is not found, this error shall be identified and the +invalid option character shall be identified in the message. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +An option, specified or unspecified by +.IR optstring , +was found. +.IP >0 6 +The end of options was encountered or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR getopts +affects the current shell execution environment, it is generally +provided as a shell regular built-in. If it is called in a subshell or +separate utility execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(getopts abc value "$@") +nohup getopts ... +find . \(miexec getopts ... \e; +.fi \fR +.P +.RE +.P +it does not affect the shell variables in the caller's environment. +.P +Note that shell functions share +.IR OPTIND +with the calling shell even though the positional parameters are +changed. If the calling shell and any of its functions uses +.IR getopts +to parse arguments, the results are unspecified. +.SH EXAMPLES +The following example script parses and displays its arguments: +.sp +.RS 4 +.nf +\fB +aflag= +bflag= +while getopts ab: name +do + case $name in + a) aflag=1;; + b) bflag=1 + bval="$OPTARG";; + ?) printf "Usage: %s: [\(mia] [\(mib value] args\en" $0 + exit 2;; + esac +done +if [ ! \(miz "$aflag" ]; then + printf "Option \(mia specified\en" +fi +if [ ! \(miz "$bflag" ]; then + printf 'Option \(mib "%s" specified\en' "$bval" +fi +shift $(($OPTIND \(mi 1)) +printf "Remaining arguments are: %s\en$*" +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR getopts +utility was chosen in preference to the System V +.IR getopt +utility because +.IR getopts +handles option-arguments containing + +characters. +.P +The +.IR OPTARG +variable is not mentioned in the ENVIRONMENT VARIABLES section because +it does not affect the execution of +.IR getopts ; +it is one of the few ``output-only'' variables used by the standard +utilities. +.P +The + +is not allowed as an option character because that is not historical +behavior, and it violates the Utility Syntax Guidelines. The + +is now specified to behave as in the KornShell version of the +.IR getopts +utility; when used as the first character in the +.IR optstring +operand, it disables diagnostics concerning missing option-arguments +and unexpected option characters. This replaces the use of the +.IR OPTERR +variable that was specified in an early proposal. +.P +The formats of the diagnostic messages produced by the +.IR getopts +utility and the +\fIgetopt\fR() +function are not fully specified because implementations with superior +(``friendlier'') formats objected to the formats used by some +historical implementations. The standard developers considered it +important that the information in the messages used be uniform between +.IR getopts +and +\fIgetopt\fR(). +Exact duplication of the messages might not be possible, particularly +if a utility is built on another system that has a different +\fIgetopt\fR() +function, but the messages must have specific information included so +that the program name, invalid option character, and type of error can +be distinguished by a user. +.P +Only a rare application program intercepts a +.IR getopts +standard error message and wants to parse it. Therefore, +implementations are free to choose the most usable messages they can +devise. The following formats are used by many historical +implementations: +.sp +.RS 4 +.nf +\fB +"%s: illegal option \(mi\|\(mi %c\en", <\fIprogram name\fP>, <\fIoption character\fP> +.P +"%s: option requires an argument \(mi\|\(mi %c\en", <\fIprogram name\fP>, \e + <\fIoption character\fP> +.fi \fR +.P +.RE +.P +Historical shells with built-in versions of +\fIgetopt\fR() +or +.IR getopts +have used different formats, frequently not even indicating the option +character found in error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5.2" ", " "Special Parameters" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetopt\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/grep.1p b/man-pages-posix-2013-a/man1p/grep.1p new file mode 100644 index 0000000..43374b2 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/grep.1p @@ -0,0 +1,529 @@ +'\" et +.TH GREP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +grep +\(em search a file for a pattern +.SH SYNOPSIS +.LP +.nf +grep \fB[\fR\(miE|\(miF\fB] [\fR\(mic|\(mil|\(miq\fB] [\fR\(miinsvx\fB] \fR\(mie \fIpattern_list + \fB[\fR\(mie \fIpattern_list\fB]\fR... \fB[\fR\(mif \fIpattern_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +grep \fB[\fR\(miE|\(miF\fB] [\fR\(mic|\(mil|\(miq\fB] [\fR\(miinsvx\fB] [\fR\(mie \fIpattern_list\fB]... + \fR\(mif \fIpattern_file \fB[\fR\(mif \fIpattern_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +grep \fB[\fR\(miE|\(miF\fB] [\fR\(mic|\(mil|\(miq\fB] [\fR\(miinsvx\fB] \fIpattern_list\fB [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR grep +utility shall search the input files, selecting lines matching one or +more patterns; the types of patterns are controlled by the options +specified. The patterns are specified by the +.BR \(mie +option, +.BR \(mif +option, or the +.IR pattern_list +operand. The +.IR pattern_list 's +value shall consist of one or more patterns separated by + +characters; the +.IR pattern_file 's +contents shall consist of one or more patterns terminated by a + +character. By default, an input line shall be selected if any +pattern, treated as an entire basic regular expression (BRE) as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions", +matches any part of the line excluding the terminating +; +a null BRE shall match every line. By default, each selected input +line shall be written to the standard output. +.P +Regular expression matching shall be based on text lines. Since a + +separates or terminates patterns (see the +.BR \(mie +and +.BR \(mif +options below), regular expressions cannot contain a +. +Similarly, since patterns are matched against individual lines +(excluding the terminating + +characters) of the input, there is no way for a pattern to match a + +found in the input. +.SH OPTIONS +The +.IR grep +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miE\fP" 10 +Match using extended regular expressions. +Treat each pattern specified as an ERE, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions". +If any entire ERE pattern matches some part of an input line excluding +the terminating +, +the line shall be matched. A null ERE shall match every line. +.IP "\fB\(miF\fP" 10 +Match using fixed strings. Treat each pattern specified as a string +instead of a regular expression. If an input line contains any of the +patterns as a contiguous sequence of bytes, the line shall be matched. +A null string shall match every line. +.IP "\fB\(mic\fP" 10 +Write only a count of selected lines to standard output. +.IP "\fB\(mie\ \fIpattern_list\fR" 10 +.br +Specify one or more patterns to be used during the search for input. +The application shall ensure that patterns in +.IR pattern_list +are separated by a +. +A null pattern can be specified by two adjacent + +characters in +.IR pattern_list . +Unless the +.BR \(miE +or +.BR \(miF +option is also specified, each pattern shall be treated as a BRE, as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +Multiple +.BR \(mie +and +.BR \(mif +options shall be accepted by the +.IR grep +utility. All of the specified patterns shall be used when matching +lines, but the order of evaluation is unspecified. +.IP "\fB\(mif\ \fIpattern_file\fR" 10 +.br +Read one or more patterns from the file named by the pathname +.IR pattern_file . +Patterns in +.IR pattern_file +shall be terminated by a +. +A null pattern can be specified by an empty line in +.IR pattern_file . +Unless the +.BR \(miE +or +.BR \(miF +option is also specified, each pattern shall be treated as a BRE, as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +.IP "\fB\(mii\fP" 10 +Perform pattern matching in searches without regard to case; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.2" ", " "Regular Expression General Requirements". +.IP "\fB\(mil\fP" 10 +(The letter ell.) Write only the names of files containing selected +lines to standard output. Pathnames shall be written once per file +searched. If the standard input is searched, a pathname of +.BR \(dq(standard input)\(dq +shall be written, in the POSIX locale. In other locales, +.BR \(dqstandard input\(dq +may be replaced by something more appropriate in those locales. +.IP "\fB\(min\fP" 10 +Precede each output line by its relative line number in the file, each +file starting at line 1. The line number counter shall be reset for +each file processed. +.IP "\fB\(miq\fP" 10 +Quiet. Nothing shall be written to the standard output, regardless of +matching lines. Exit with zero status if an input line is selected. +.IP "\fB\(mis\fP" 10 +Suppress the error messages ordinarily written for nonexistent or +unreadable files. Other error messages shall not be suppressed. +.IP "\fB\(miv\fP" 10 +Select lines not matching any of the specified patterns. If the +.BR \(miv +option is not specified, selected lines shall be those that match any +of the specified patterns. +.IP "\fB\(mix\fP" 10 +Consider only input lines that use all characters in the line excluding +the terminating + +to match an entire fixed string or regular expression to be matching +lines. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIpattern_list\fR" 10 +Specify one or more patterns to be used during the search for input. +This operand shall be treated as if it were specified as +.BR \(mie +.IR pattern_list . +.IP "\fIfile\fR" 10 +A pathname of a file to be searched for the patterns. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR grep : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mil +option is in effect, the following shall be written for each file +containing at least one selected input line: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +Otherwise, if more than one +.IR file +argument appears, and +.BR \(miq +is not specified, the +.IR grep +utility shall prefix each output line by: +.sp +.RS 4 +.nf +\fB +"%s:", <\fIfile\fR> +.fi \fR +.P +.RE +.P +The remainder of each output line shall depend on the other options +specified: +.IP " *" 4 +If the +.BR \(mic +option is in effect, the remainder of each output line shall contain: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIcount\fR> +.fi \fR +.P +.RE +.RE +.IP " *" 4 +Otherwise, if +.BR \(mic +is not in effect and the +.BR \(min +option is in effect, the following shall be written to standard +output: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%d:", <\fIline number\fR> +.fi \fR +.P +.RE +.RE +.IP " *" 4 +Finally, the following shall be written to standard output: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s", <\fIselected-line contents\fR> +.fi \fR +.P +.RE +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +One or more lines were selected. +.IP "\01" 6 +No lines were selected. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If the +.BR \(miq +option is specified, the exit status shall be zero if an input line is +selected, even if an error was detected. Otherwise, default actions +shall be performed. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Care should be taken when using characters in +.IR pattern_list +that may also be meaningful to the command interpreter. It is safest +to enclose the entire +.IR pattern_list +argument in single-quotes: +.sp +.RS 4 +.nf +\fB +\&'...' +.fi \fR +.P +.RE +.P +The +.BR \(mie +.IR pattern_list +option has the same effect as the +.IR pattern_list +operand, but is useful when +.IR pattern_list +begins with the + +delimiter. It is also useful when it is more convenient to provide +multiple patterns as separate arguments. +.P +Multiple +.BR \(mie +and +.BR \(mif +options are accepted and +.IR grep +uses all of the patterns it is given while matching input text lines. +(Note that the order of evaluation is not specified. If an +implementation finds a null string as a pattern, it is allowed to use +that pattern first, matching every line, and effectively ignore any +other patterns.) +.P +The +.BR \(miq +option provides a means of easily determining whether or not a pattern +(or string) exists in a group of files. When searching several files, +it provides a performance improvement (because it can quit as soon as +it finds the first match) and requires less care by the user in +choosing the set of files to supply as arguments (because it exits zero +if it finds a match even if +.IR grep +detected an access or read error on earlier +.IR file +operands). +.SH EXAMPLES +.IP " 1." 4 +To find all uses of the word +.BR \(dqPosix\(dq +(in any case) in file +.BR text.mm +and write with line numbers: +.RS 4 +.sp +.RS 4 +.nf +\fB +grep \(mii \(min posix text.mm +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +To find all empty lines in the standard input: +.RS 4 +.sp +.RS 4 +.nf +\fB +grep ^$ +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +grep \(miv . +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Both of the following commands print all lines containing strings +.BR \(dqabc\(dq +or +.BR \(dqdef\(dq +or both: +.RS 4 +.sp +.RS 4 +.nf +\fB +grep \(miE 'abc|def' +.P +grep \(miF 'abc +def' +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Both of the following commands print all lines matching exactly +.BR \(dqabc\(dq +or +.BR \(dqdef\(dq : +.RS 4 +.sp +.RS 4 +.nf +\fB +grep \(miE '^abc$|^def$' +.P +grep \(miF \(mix 'abc +def' +.fi \fR +.P +.RE +.RE +.SH RATIONALE +This +.IR grep +has been enhanced in an upwards-compatible way to provide the exact +functionality of the historical +.IR egrep +and +.IR fgrep +commands as well. It was the clear intention of the standard +developers to consolidate the three +.IR grep s +into a single command. +.P +The old +.IR egrep +and +.IR fgrep +commands are likely to be supported for many years to come as +implementation extensions, allowing historical applications to operate +unmodified. +.P +Historical implementations usually silently ignored all but one of +multiply-specified +.BR \(mie +and +.BR \(mif +options, but were not consistent as to which specification was actually +used. +.P +The +.BR \(mib +option was omitted from the OPTIONS section because block numbers are +implementation-defined. +.P +The System V restriction on using +.BR \(mi +to mean standard input was omitted. +.P +A definition of action taken when given a null BRE or ERE is specified. +This is an error condition in some historical implementations. +.P +The +.BR \(mil +option previously indicated that its use was undefined when no files +were explicitly named. This behavior was historical and placed an +unnecessary restriction on future implementations. It has been +removed. +.P +The historical BSD +.IR grep +.BR \(mis +option practice is easily duplicated by redirecting standard output to +.BR /dev/null . +The +.BR \(mis +option required here is from System V. +.P +The +.BR \(mix +option, historically available only with +.IR fgrep , +is available here for all of the non-obsolescent versions. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 9" ", " "Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/hash.1p b/man-pages-posix-2013-a/man1p/hash.1p new file mode 100644 index 0000000..00c2821 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/hash.1p @@ -0,0 +1,189 @@ +'\" et +.TH HASH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +hash +\(em remember or report utility locations +.SH SYNOPSIS +.LP +.nf +hash \fB[\fIutility\fR...\fB]\fR +.P +hash \(mir +.fi +.SH DESCRIPTION +The +.IR hash +utility shall affect the way the current shell environment remembers +the locations of utilities found as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +Depending on the arguments specified, it shall add utility locations to +its list of remembered locations or it shall purge the contents of the +list. When no arguments are specified, it shall report on the contents +of the list. +.P +Utilities provided as built-ins to the shell shall not be reported by +.IR hash . +.SH OPTIONS +The +.IR hash +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mir\fP" 10 +Forget all previously remembered utility locations. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility to be searched for and added to the list of +remembered locations. If +.IR utility +contains one or more + +characters, the results are unspecified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR hash : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of +.IR utility , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output of +.IR hash +shall be used when no arguments are specified. Its format is +unspecified, but includes the pathname of each utility in the list of +remembered locations for the current shell environment. This list +shall consist of those utilities named in previous +.IR hash +invocations that have been invoked, and may contain those invoked and +found through the normal command search process. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR hash +affects the current shell execution environment, it is always provided +as a shell regular built-in. If it is called in a separate utility +execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +nohup hash \(mir +find . \(mitype f | xargs hash +.fi \fR +.P +.RE +.P +it does not affect the command search process of the caller's +environment. +.P +The +.IR hash +utility may be implemented as an alias\(emfor example, +.IR alias +.BR "\(mit\ \(mi" , +in which case utilities found through normal command search are not +listed by the +.IR hash +command. +.P +The effects of +.IR hash +.BR \(mir +can also be achieved portably by resetting the value of +.IR PATH ; +in the simplest form, this can be: +.sp +.RS 4 +.nf +\fB +PATH="$PATH" +.fi \fR +.P +.RE +.P +The use of +.IR hash +with +.IR utility +names is unnecessary for most applications, but may provide a +performance improvement on a few implementations; normally, the hashing +process is included by default. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.1.1" ", " "Command Search and Execution" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/head.1p b/man-pages-posix-2013-a/man1p/head.1p new file mode 100644 index 0000000..477328d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/head.1p @@ -0,0 +1,207 @@ +'\" et +.TH HEAD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +head +\(em copy the first part of files +.SH SYNOPSIS +.LP +.nf +head \fB[\fR\(min \fInumber\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR head +utility shall copy its input files to the standard output, ending the +output for each file at a designated point. +.P +Copying shall end at the point in each input file indicated by the +.BR \(min +.IR number +option. The option-argument +.IR number +shall be counted in units of lines. +.SH OPTIONS +The +.IR head +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(min\ \fInumber\fR" 10 +The first +.IR number +lines of each input file shall be copied to standard output. The +application shall ensure that the +.IR number +option-argument is a positive decimal integer. +.P +When a file contains less than +.IR number +lines, it shall be copied to standard output in its entirety. This +shall not be an error. +.P +If no options are specified, +.IR head +shall act as if +.BR "\(min 10" +had been specified. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +Input files shall be text files, but the line length is not restricted +to +{LINE_MAX} +bytes. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR head : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall contain designated portions of the input +files. +.P +If multiple +.IR file +operands are specified, +.IR head +shall precede the output for each with the header: +.sp +.RS 4 +.nf +\fB +"\en==> %s <==\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +except that the first header written shall not include the initial +. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +To write the first ten lines of all files (except those with a leading +period) in the directory: +.sp +.RS 4 +.nf +\fB +head \(mi\|\(mi * +.fi \fR +.P +.RE +.SH RATIONALE +Although it is possible to simulate +.IR head +with +.IR sed +10q for a single file, the standard developers decided that the +popularity of +.IR head +on historical BSD systems warranted its inclusion alongside +.IR tail . +.P +POSIX.1\(hy2008 version of +.IR head +follows the Utility Syntax Guidelines. The +.BR \(min +option was added to this new interface so that +.IR head +and +.IR tail +would be more logically related. Earlier versions of this standard +allowed a +.BR \(minumber +option. This form is no longer specified by POSIX.1\(hy2008 but may +be present in some implementations. +.P +There is no +.BR \(mic +option (as there is in +.IR tail ) +because it is not historical practice and because other utilities in +\&this volume of POSIX.1\(hy2008 provide similar functionality. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^", +.IR "\fItail\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/iconv.1p b/man-pages-posix-2013-a/man1p/iconv.1p new file mode 100644 index 0000000..41b3b09 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/iconv.1p @@ -0,0 +1,288 @@ +'\" et +.TH ICONV "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iconv +\(em codeset conversion +.SH SYNOPSIS +.LP +.nf +iconv \fB[\fR\(mics\fB]\fR \(mif \fIfrommap\fR \(mit \fItomap \fB[\fIfile\fR...\fB]\fR +.P +iconv \(mif \fIfromcode \fB[\fR\(mics\fB] [\fR\(mit \fItocode\fB] [\fIfile\fR...\fB]\fR +.P +iconv \(mit \fItocode \fB[\fR\(mics\fB] [\fR\(mif \fIfromcode\fB] [\fIfile\fR...\fB]\fR +.P +iconv \(mil +.fi +.SH DESCRIPTION +The +.IR iconv +utility shall convert the encoding of characters in +.IR file +from one codeset to another and write the results to standard output. +.P +When the options indicate that charmap files are used to specify the +codesets (see OPTIONS), the codeset conversion shall be accomplished by +performing a logical join on the symbolic character names in the two +charmaps. The implementation need not support the use of charmap files +for codeset conversion unless the POSIX2_LOCALEDEF symbol is defined on +the system. +.SH OPTIONS +The +.IR iconv +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fR" 10 +Omit any characters that are invalid in the codeset of the input file +from the output. When +.BR \(mic +is not used, the results of encountering invalid characters in the +input stream (either those that are not characters in the codeset of +the input file or that have no corresponding character in the codeset +of the output file) shall be specified in the system documentation. The +presence or absence of +.BR \(mic +shall not affect the exit status of +.IR iconv . +.IP "\fB\(mif\ \fIfromcodeset\fR" 10 +.br +Identify the codeset of the input file. The implementation shall +recognize the following two forms of the +.IR fromcodeset +option-argument: +.RS 10 +.IP "\fIfromcode\fR" 10 +The +.IR fromcode +option-argument must not contain a + +character. It shall be interpreted as the name of one of the codeset +descriptions provided by the implementation in an unspecified +format. Valid values of +.IR fromcode +are implementation-defined. +.IP "\fIfrommap\fR" 10 +The +.IR frommap +option-argument must contain a + +character. It shall be interpreted as the pathname of a charmap file as +defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File". +If the pathname does not represent a valid, readable charmap file, +the results are undefined. +.P +If this option is omitted, the codeset of the current locale shall +be used. +.RE +.IP "\fB\(mil\fR" 10 +Write all supported +.IR fromcode +and +.IR tocode +values to standard output in an unspecified format. +.IP "\fB\(mis\fR" 10 +Suppress any messages written to standard error concerning invalid +characters. When +.BR \(mis +is not used, the results of encountering invalid characters in the +input stream (either those that are not valid characters in the codeset +of the input file or that have no corresponding character in the +codeset of the output file) shall be specified in the system +documentation. The presence or absence of +.BR \(mis +shall not affect the exit status of +.IR iconv . +.IP "\fB\(mit\ \fItocodeset\fR" 10 +Identify the codeset to be used for the output file. The implementation +shall recognize the following two forms of the +.IR tocodeset +option-argument: +.RS 10 +.IP "\fItocode\fR" 10 +The semantics shall be equivalent to the +.BR \(mif +.IR fromcode +option. +.IP "\fItomap\fR" 10 +The semantics shall be equivalent to the +.BR \(mif +.IR frommap +option. +.P +If this option is omitted, the codeset of the current locale shall be +used. +.RE +.P +If either +.BR \(mif +or +.BR \(mit +represents a charmap file, but the other does not (or is omitted), or +both +.BR \(mif +and +.BR \(mit +are omitted, the results are undefined. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR iconv : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). During translation of the file, +this variable is superseded by the use of the +.IR fromcode +option-argument. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mil +option is used, the standard output shall contain all supported +.IR fromcode +and +.IR tocode +values, written in an unspecified format. +.P +When the +.BR \(mil +option is not used, the standard output shall contain the sequence of +characters read from the input files, translated to the specified +codeset. Nothing else shall be written to the standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The user must ensure that both charmap files use the same symbolic +names for characters the two codesets have in common. +.SH EXAMPLES +The following example converts the contents of file +.BR mail.x400 +from the ISO/IEC\ 6937:\|2001 standard codeset to the ISO/IEC\ 8859\(hy1:\|1998 standard codeset, and stores the results in +file +.BR mail.local : +.sp +.RS 4 +.nf +\fB +iconv \(mif IS6937 \(mit IS8859 mail.x400 > mail.local +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR iconv +utility can be used portably only when the user provides two charmap +files as option-arguments. This is because a single charmap provided by +the user cannot reliably be joined with the names in a system-provided +character set description. The valid values for +.IR fromcode +and +.IR tocode +are implementation-defined and do not have to have any relation to +the charmap mechanisms. As an aid to interactive users, the +.BR \(mil +option was adopted from the Plan 9 operating system. It writes +information concerning these implementation-defined values. The +format is unspecified because there are many possible useful formats +that could be chosen, such as a matrix of valid combinations of +.IR fromcode +and +.IR tocode . +The +.BR \(mil +option is not intended for shell script usage; conforming applications +will have to use charmaps. +.P +The +.IR iconv +utility may support the conversion between ASCII and EBCDIC-based +encodings, but is not required to do so. In an XSI-compliant +implementation, the +.IR dd +utility is the only method guaranteed to support conversion between +these two character sets. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdd\fR\^", +.IR "\fIgencat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/id.1p b/man-pages-posix-2013-a/man1p/id.1p new file mode 100644 index 0000000..319f76f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/id.1p @@ -0,0 +1,351 @@ +'\" et +.TH ID "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +id +\(em return user identity +.SH SYNOPSIS +.LP +.nf +id \fB[\fIuser\fB]\fR +.P +id \(miG \fB[\fR\(min\fB] [\fIuser\fB]\fR +.P +id \(mig \fB[\fR\(minr\fB] [\fIuser\fB]\fR +.P +id \(miu \fB[\fR\(minr\fB] [\fIuser\fB]\fR +.fi +.SH DESCRIPTION +If no +.IR user +operand is provided, the +.IR id +utility shall write the user and group IDs and the corresponding user +and group names of the invoking process to standard output. If the +effective and real IDs do not match, both shall be written. If +multiple groups are supported by the underlying system (see the +description of +{NGROUPS_MAX} +in the System Interfaces volume of POSIX.1\(hy2008), the supplementary group affiliations of the invoking +process shall also be written. +.P +If a +.IR user +operand is provided and the process has appropriate privileges, the +user and group IDs of the selected user shall be written. In this +case, effective IDs shall be assumed to be identical to real IDs. If +the selected user has more than one allowable group membership listed +in the group database, these shall be written in the same manner as the +supplementary groups described in the preceding paragraph. +.SH OPTIONS +The +.IR id +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miG\fP" 10 +Output all different group IDs (effective, real, and supplementary) +only, using the format +.BR \(dq%u\en\(dq . +If there is more than one distinct group affiliation, output each such +affiliation, using the format +.BR \(dq\ %u\(dq , +before the + +is output. +.IP "\fB\(mig\fP" 10 +Output only the effective group ID, using the format +.BR \(dq%u\en\(dq . +.IP "\fB\(min\fP" 10 +Output the name in the format +.BR \(dq%s\(dq +instead of the numeric ID using the format +.BR \(dq%u\(dq . +.IP "\fB\(mir\fP" 10 +Output the real ID instead of the effective ID. +.IP "\fB\(miu\fP" 10 +Output only the effective user ID, using the format +.BR \(dq%u\en\(dq . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIuser\fR" 10 +The login name for which information is to be written. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR id : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The following formats shall be used when the +.IR LC_MESSAGES +locale category specifies the POSIX locale. In other locales, the +strings +.IR uid , +.IR gid , +.IR euid , +.IR egid , +and +.IR groups +may be replaced with more appropriate strings corresponding to the +locale. +.sp +.RS 4 +.nf +\fB +"uid=%u(%s) gid=%u(%s)\en", <\fIreal user ID\fR>, <\fIuser-name\fR>, + <\fIreal group ID\fR>, <\fIgroup-name\fR> +.fi \fR +.P +.RE +.P +If the effective and real user IDs do not match, the following shall be +inserted immediately before the +.BR '\en' +character in the previous format: +.sp +.RS 4 +.nf +\fB +" euid=%u(%s)" +.fi \fR +.P +.RE +.P +with the following arguments added at the end of the argument list: +.sp +.RS 4 +.nf +\fB +<\fIeffective user ID\fR>, <\fIeffective user-name\fR> +.fi \fR +.P +.RE +.P +If the effective and real group IDs do not match, the following shall +be inserted directly before the +.BR '\en' +character in the format string (and after any addition resulting from +the effective and real user IDs not matching): +.sp +.RS 4 +.nf +\fB +" egid=%u(%s)" +.fi \fR +.P +.RE +.P +with the following arguments added at the end of the argument list: +.sp +.RS 4 +.nf +\fB +<\fIeffective group-ID\fR>, <\fIeffective group name\fR> +.fi \fR +.P +.RE +.P +If the process has supplementary group affiliations or the selected +user is allowed to belong to multiple groups, the first shall be added +directly before the + +in the format string: +.sp +.RS 4 +.nf +\fB +" groups=%u(%s)" +.fi \fR +.P +.RE +.P +with the following arguments added at the end of the argument list: +.sp +.RS 4 +.nf +\fB +<\fIsupplementary group ID\fR>, <\fIsupplementary group name\fR> +.fi \fR +.P +.RE +.P +and the necessary number of the following added after that for any +remaining supplementary group IDs: +.sp +.RS 4 +.nf +\fB +",%u(%s)" +.fi \fR +.P +.RE +.P +and the necessary number of the following arguments added at the end of +the argument list: +.sp +.RS 4 +.nf +\fB +<\fIsupplementary group ID\fR>, <\fIsupplementary group name\fR> +.fi \fR +.P +.RE +.P +If any of the user ID, group ID, effective user ID, effective group ID, +or supplementary/multiple group IDs cannot be mapped by the system into +printable user or group names, the corresponding +.BR \(dq(%s)\(dq +and +.IR name +argument shall be omitted from the corresponding format string. +.P +When any of the options are specified, the output format shall be as +described in the OPTIONS section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Output produced by the +.BR \(miG +option and by the default case could potentially produce very long +lines on systems that support large numbers of supplementary groups. +(On systems with user and group IDs that are 32-bit integers and with +group names with a maximum of 8 bytes per name, 93 supplementary groups +plus distinct effective and real group and user IDs could theoretically +overflow the 2\|048-byte +{LINE_MAX} +text file line limit on the default output case. It would take about +186 supplementary groups to overflow the 2\|048-byte barrier using +.IR id +.BR \(miG ). +This is not expected to be a problem in practice, but in cases where it +is a concern, applications should consider using +.IR fold +.BR \(mis +before post-processing the output of +.IR id . +.SH EXAMPLES +None. +.SH RATIONALE +The functionality provided by the 4 BSD +.IR groups +utility can be simulated using: +.sp +.RS 4 +.nf +\fB +id \(miGn [ user ] +.fi \fR +.P +.RE +.P +The 4 BSD command +.IR groups +was considered, but it was not included because it did not provide the +functionality of the +.IR id +utility of the SVID. Also, it was thought that it would be easier to +modify +.IR id +to provide the additional functionality necessary to systems with +multiple groups than to invent another command. +.P +The options +.BR \(miu , +.BR \(mig , +.BR \(min , +and +.BR \(mir +were added to ease the use of +.IR id +with shell commands substitution. Without these options it is +necessary to use some preprocessor such as +.IR sed +to select the desired piece of information. Since output such as that +produced by: +.sp +.RS 4 +.nf +\fB +id \(miu \(min +.fi \fR +.P +.RE +.P +is frequently wanted, it seemed desirable to add the options. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfold\fR\^", +.IR "\fIlogname\fR\^", +.IR "\fIwho\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetgroups\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ipcrm.1p b/man-pages-posix-2013-a/man1p/ipcrm.1p new file mode 100644 index 0000000..032e835 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ipcrm.1p @@ -0,0 +1,150 @@ +'\" et +.TH IPCRM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ipcrm +\(em remove an XSI message queue, semaphore set, or shared memory +segment identifier +.SH SYNOPSIS +.LP +.nf +ipcrm \fB[\fR\(miq msgid|\(miQ msgkey|\(mis semid|\(miS semkey|\(mim shmid|\(miM shmkey\fB]\fR... +.fi +.SH DESCRIPTION +The +.IR ipcrm +utility shall remove zero or more message queues, semaphore sets, or +shared memory segments. The interprocess communication facilities to be +removed are specified by the options. +.P +Only a user with appropriate privileges shall be allowed to remove an +interprocess communication facility that was not created by or owned by +the user invoking +.IR ipcrm . +.SH OPTIONS +The +.IR ipcrm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miq\ \fImsgid\fR" 10 +Remove the message queue identifier +.IR msgid +from the system and destroy the message queue and data structure +associated with it. +.IP "\fB\(mim\ \fIshmid\fR" 10 +Remove the shared memory identifier +.IR shmid +from the system. The shared memory segment and data structure +associated with it shall be destroyed after the last detach. +.IP "\fB\(mis\ \fIsemid\fR" 10 +Remove the semaphore identifier +.IR semid +from the system and destroy the set of semaphores and data structure +associated with it. +.IP "\fB\(miQ\ \fImsgkey\fR" 10 +Remove the message queue identifier, created with key +.IR msgkey , +from the system and destroy the message queue and data structure +associated with it. +.IP "\fB\(miM\ \fIshmkey\fR" 10 +Remove the shared memory identifier, created with key +.IR shmkey , +from the system. The shared memory segment and data structure +associated with it shall be destroyed after the last detach. +.IP "\fB\(miS\ \fIsemkey\fR" 10 +Remove the semaphore identifier, created with key +.IR semkey , +from the system and destroy the set of semaphores and data structure +associated with it. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ipcrm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIipcs\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImsgctl\fR\^(\|)", +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ipcs.1p b/man-pages-posix-2013-a/man1p/ipcs.1p new file mode 100644 index 0000000..54456e9 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ipcs.1p @@ -0,0 +1,556 @@ +'\" et +.TH IPCS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ipcs +\(em report XSI interprocess communication facilities status +.SH SYNOPSIS +.LP +.nf +ipcs \fB[\fR\(miqms\fB] [\fR\(mia|\(mibcopt\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ipcs +utility shall write information about active interprocess communication +facilities. +.P +Without options, information shall be written in short format for +message queues, shared memory segments, and semaphore sets that are +currently active in the system. Otherwise, the information that is +displayed is controlled by the options specified. +.SH OPTIONS +The +.IR ipcs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The +.IR ipcs +utility accepts the following options: +.IP "\fB\(miq\fP" 10 +Write information about active message queues. +.IP "\fB\(mim\fP" 10 +Write information about active shared memory segments. +.IP "\fB\(mis\fP" 10 +Write information about active semaphore sets. +.P +If +.BR \(miq , +.BR \(mim , +or +.BR \(mis +are specified, only information about those facilities shall be +written. If none of these three are specified, information about all +three shall be written subject to the following options: +.IP "\fB\(mia\fP" 10 +Use all print options. (This is a shorthand notation for +.BR \(mib , +.BR \(mic , +.BR \(mio , +.BR \(mip , +and +.BR \(mit .) +.IP "\fB\(mib\fP" 10 +Write information on maximum allowable size. (Maximum number of bytes +in messages on queue for message queues, size of segments for shared +memory, and number of semaphores in each set for semaphores.) +.IP "\fB\(mic\fP" 10 +Write creator's user name and group name; see below. +.IP "\fB\(mio\fP" 10 +Write information on outstanding usage. (Number of messages on queue +and total number of bytes in messages on queue for message queues, and +number of processes attached to shared memory segments.) +.IP "\fB\(mip\fP" 10 +Write process number information. (Process ID of the last process to +send a message and process ID of the last process to receive a message +on message queues, process ID of the creating process, and process ID +of the last process to attach or detach on shared memory segments.) +.IP "\fB\(mit\fP" 10 +Write time information. (Time of the last control operation that +changed the access permissions for all facilities, time of the last +\fImsgsnd\fR() +and +\fImsgrcv\fR() +operations on message queues, time of the last +\fIshmat\fR() +and +\fIshmdt\fR() +operations on shared memory, and time of the last +\fIsemop\fR() +operation on semaphores.) +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +.IP " *" 4 +The group database +.IP " *" 4 +The user database +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ipcs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone for the date and time strings written by +.IR ipcs . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +An introductory line shall be written with the format: +.sp +.RS 4 +.nf +\fB +"IPC status from %s as of %s\en", <\fIsource\fP>, <\fIdate\fP> +.fi \fR +.P +.RE +.P +where <\fIsource\fP> indicates the source used to gather the statistics +and <\fIdate\fP> is the information that would be produced by the +.IR date +command when invoked in the POSIX locale. +.P +The +.IR ipcs +utility then shall create up to three reports depending upon the +.BR \(miq , +.BR \(mim , +and +.BR \(mis +options. The first report shall indicate the status of message queues, +the second report shall indicate the status of shared memory segments, +and the third report shall indicate the status of semaphore sets. +.P +If the corresponding facility is not installed or has not been used +since the last reboot, then the report shall be written out in the +format: +.sp +.RS 4 +.nf +\fB +"%s facility not in system.\en", <\fIfacility\fP> +.fi \fR +.P +.RE +.P +where <\fIfacility\fP> is +.IR "Message Queue" , +.IR "Shared Memory" , +or +.IR "Semaphore" , +as appropriate. If the facility has been installed and has been used +since the last reboot, column headings separated by one or more + +characters and followed by a + +shall be written as indicated below followed by the facility name +written out using the format: +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIfacility\fP> +.fi \fR +.P +.RE +.P +where <\fIfacility\fP> is +.IR "Message Queues" , +.IR "Shared Memory" , +or +.IR "Semaphores" , +as appropriate. On the second and third reports the column headings +need not be written if the last column headings written already provide +column headings for all information in that report. +.P +The column headings provided in the first column below and the meaning +of the information in those columns shall be given in order below; the +letters in parentheses indicate the options that shall cause the +corresponding column to appear; ``all'' means that the column shall +always appear. Each column is separated by one or more + +characters. Note that these options only determine what information is +provided for each report; they do not determine which reports are written. +.IP "T (all)" 12 +Type of facility: +.RS 12 +.IP "\fRq\fP" 8 +Message queue. +.IP "\fRm\fP" 8 +Shared memory segment. +.IP "\fRs\fP" 8 +Semaphore. +.P +This field is a single character written using the format +.BR %c . +.RE +.IP "ID (all)" 12 +The identifier for the facility entry. This field shall be written +using the format +.BR %d . +.IP "KEY (all)" 12 +The key used as an argument to +\fImsgget\fR(), +\fIsemget\fR(), +or +\fIshmget\fR() +to create the facility entry. +.RS 12 +.TP 10 +.BR Note: +The key of a shared memory segment is changed to IPC_PRIVATE when the +segment has been removed until all processes attached to the segment +detach it. +.P +This field shall be written using the format \fR0x%x\fR. +.RE +.IP "MODE (all)" 12 +The facility access modes and flags. The mode shall consist of 11 +characters that are interpreted as follows. +.RS 12 +.P +The first character shall be: +.IP "\fRS\fP" 8 +If a process is waiting on a +\fImsgsnd\fR() +operation. +.IP "\fR\(mi\fP" 8 +If the above is not true. +.P +The second character shall be: +.IP "\fRR\fP" 8 +If a process is waiting on a +\fImsgrcv\fR() +operation. +.IP "\fRC\fP\ or\ \fR\(mi\fP" 8 +If the associated shared memory segment is to be cleared when the first +attach operation is executed. +.IP "\fR\(mi\fP" 8 +If none of the above is true. +.P +The next nine characters shall be interpreted as three sets of three +bits each. The first set refers to the owner's permissions; the next +to permissions of others in the usergroup of the facility entry; and +the last to all others. Within each set, the first character indicates +permission to read, the second character indicates permission to write +or alter the facility entry, and the last character is a minus-sign (\c +.BR '\(mi' ). +.P +The permissions shall be indicated as follows: +.IP "\fIr\fP" 8 +If read permission is granted. +.IP "\fIw\fP" 8 +If write permission is granted. +.IP "\fIa\fP" 8 +If alter permission is granted. +.IP "\fR\(mi\fP" 8 +If the indicated permission is not granted. +.P +The first character following the permissions specifies if there is an +alternate or additional access control method associated with the +facility. If there is no alternate or additional access control method +associated with the facility, a single + +shall be written; otherwise, another printable character is +written. +.RE +.IP "OWNER (all)" 12 +The user name of the owner of the facility entry. If the user name of +the owner is found in the user database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the user ID of the owner shall be written using the format +.BR %d . +.IP "GROUP (all)" 12 +The group name of the owner of the facility entry. If the group name +of the owner is found in the group database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the group ID of the owner shall be written using the format +.BR %d . +.P +The following nine columns shall be only written out for message +queues: +.IP "CREATOR (\fBa\fP,\fBc\fP)" 12 +The user name of the creator of the facility entry. If the user name +of the creator is found in the user database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the user ID of the creator shall be written using the format +.BR %d . +.IP "CGROUP (\fBa\fP,\fBc\fP)" 12 +The group name of the creator of the facility entry. If the group name +of the creator is found in the group database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the group ID of the creator shall be written using the format +.BR %d . +.IP "CBYTES (\fBa\fP,\fBo\fP)" 12 +The number of bytes in messages currently outstanding on the associated +message queue. This field shall be written using the format +.BR %d . +.IP "QNUM (\fBa\fP,\fBo\fP)" 12 +The number of messages currently outstanding on the associated message +queue. This field shall be written using the format +.BR %d . +.IP "QBYTES (\fBa\fP,\fBb\fP)" 12 +The maximum number of bytes allowed in messages outstanding on the +associated message queue. This field shall be written using the format +.BR %d . +.IP "LSPID (\fBa\fP,\fBp\fP)" 12 +The process ID of the last process to send a message to the associated +queue. This field shall be written using the format: +.RS 12 +.sp +.RS 4 +.nf +\fB +"%d", <\fIpid\fP> +.fi \fR +.P +.RE +.P +where <\fIpid\fP> is 0 if no message has been sent to the corresponding +message queue; otherwise, <\fIpid\fP> shall be the process ID of the +last process to send a message to the queue. +.RE +.IP "LRPID (\fBa\fP,\fBp\fP)" 12 +The process ID of the last process to receive a message from the +associated queue. This field shall be written using the format: +.RS 12 +.sp +.RS 4 +.nf +\fB +"%d", <\fIpid\fP> +.fi \fR +.P +.RE +.P +where <\fIpid\fP> is 0 if no message has been received from the +corresponding message queue; otherwise, <\fIpid\fP> shall be the +process ID of the last process to receive a message from the queue. +.RE +.IP "STIME (\fBa\fP,\fBt\fP)" 12 +The time the last message was sent to the associated queue. +If a message has been sent to the corresponding message queue, +the hour, minute, and second of the last time a message +was sent to the queue shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.IP "RTIME (\fBa\fP,\fBt\fP)" 12 +The time the last message was received from the associated queue. +If a message has been received from the corresponding message queue, +the hour, minute, and second of the last time a message was received +from the queue shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.P +The following eight columns shall be only written out for shared memory +segments. +.IP "CREATOR (\fBa\fP,\fBc\fP)" 12 +The user of the creator of the facility entry. If the user name of the +creator is found in the user database, at least the first eight column +positions of the name shall be written using the format +.BR %s . +Otherwise, the user ID of the creator shall be written using the format +.BR %d . +.IP "CGROUP (\fBa\fP,\fBc\fP)" 12 +The group name of the creator of the facility entry. If the group name +of the creator is found in the group database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the group ID of the creator shall be written using the format +.BR %d . +.IP "NATTCH (\fBa\fP,\fBo\fP)" 12 +The number of processes attached to the associated shared memory +segment. This field shall be written using the format +.BR %d . +.IP "SEGSZ (\fBa\fP,\fBb\fP)" 12 +The size of the associated shared memory segment. This field shall be +written using the format +.BR %d . +.IP "CPID (\fBa\fP,\fBp\fP)" 12 +The process ID of the creator of the shared memory entry. This field +shall be written using the format +.BR %d . +.IP "LPID (\fBa\fP,\fBp\fP)" 12 +The process ID of the last process to attach or detach the shared +memory segment. This field shall be written using the format: +.RS 12 +.sp +.RS 4 +.nf +\fB +"%d", <\fIpid\fP> +.fi \fR +.P +.RE +.P +where <\fIpid\fP> is 0 if no process has attached the corresponding +shared memory segment; otherwise, <\fIpid\fP> shall be the process ID +of the last process to attach or detach the segment. +.RE +.IP "ATIME (\fBa\fP,\fBt\fP)" 12 +The time the last attach on the associated shared memory segment was +completed. If the corresponding shared memory segment has ever been +attached, the hour, minute, and second of the last time the segment was +attached shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.IP "DTIME (\fBa\fP,\fBt\fP)" 12 +The time the last detach on the associated shared memory segment was +completed. If the corresponding shared memory segment has ever been +detached, the hour, minute, and second of the last time the segment was +detached shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.P +The following four columns shall be only written out for semaphore +sets: +.IP "CREATOR (\fBa\fP,\fBc\fP)" 12 +The user of the creator of the facility entry. If the user name of the +creator is found in the user database, at least the first eight column +positions of the name shall be written using the format +.BR %s . +Otherwise, the user ID of the creator shall be written using the format +.BR %d . +.IP "CGROUP (\fBa\fP,\fBc\fP)" 12 +The group name of the creator of the facility entry. If the group name +of the creator is found in the group database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the group ID of the creator shall be written using the +format +.BR %d . +.IP "NSEMS (\fBa\fP,\fBb\fP)" 12 +The number of semaphores in the set associated with the semaphore +entry. This field shall be written using the format +.BR %d . +.IP "OTIME (\fBa\fP,\fBt\fP)" 12 +The time the last semaphore operation on the set associated with the +semaphore entry was completed. If a semaphore operation has ever been +performed on the corresponding semaphore set, the hour, minute, and +second of the last semaphore operation on the semaphore set shall be +written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.P +The following column shall be written for all three reports when it is +requested: +.IP "CTIME (\fBa\fP,\fBt\fP)" 12 +The time the associated entry was created or changed. The hour, +minute, and second of the time when the associated entry was created +shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Things can change while +.IR ipcs +is running; the information it gives is guaranteed to be accurate +only when it was retrieved. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIipcrm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/jobs.1p b/man-pages-posix-2013-a/man1p/jobs.1p new file mode 100644 index 0000000..96288b4 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/jobs.1p @@ -0,0 +1,343 @@ +'\" et +.TH JOBS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +jobs +\(em display status of jobs in the current session +.SH SYNOPSIS +.LP +.nf +jobs \fB[\fR\(mil|\(mip\fB] [\fIjob_id\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR jobs +utility shall display the status of jobs that were started in the +current shell environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +When +.IR jobs +reports the termination status of a job, the shell shall remove its +process ID from the list of those ``known in the current shell +execution environment''; see +.IR "Section 2.9.3.1" ", " "Examples". +.SH OPTIONS +The +.IR jobs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mil\fP" 10 +(The letter ell.) Provide more information about each job listed. This +information shall include the job number, current job, process group +ID, state, and the command that formed the job. +.IP "\fB\(mip\fP" 10 +Display only the process IDs for the process group leaders of the +selected jobs. +.P +By default, the +.IR jobs +utility shall display the status of all stopped jobs, running +background jobs and all jobs whose status has changed and have not been +reported by the shell. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIjob_id\fR" 10 +Specifies the jobs for which the status is to be displayed. If no +.IR job_id +is given, the status information for all jobs shall be displayed. The +format of +.IR job_id +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID". +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR jobs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mip +option is specified, the output shall consist of one line for each +process ID: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIprocess ID\fR> +.fi \fR +.P +.RE +.P +Otherwise, if the +.BR \(mil +option is not specified, the output shall be a series of lines of the +form: +.sp +.RS 4 +.nf +\fB +"[%d] %c %s %s\en", <\fIjob-number\fR>, <\fIcurrent\fR>, <\fIstate\fR>, <\fIcommand\fR> +.fi \fR +.P +.RE +.P +where the fields shall be as follows: +.IP "<\fIcurrent\fP>" 10 +The character +.BR '\(pl' +identifies the job that would be used as a default for the +.IR fg +or +.IR bg +utilities; this job can also be specified using the +.IR job_id +%+ or +.BR \(dq%%\(dq . +The character +.BR '\(mi' +identifies the job that would become the default if the current default +job were to exit; this job can also be specified using the +.IR job_id +%\(mi. For other jobs, this field is a +. +At most one job can be identified with +.BR '\(pl' +and at most one job can be identified with +.BR '\(mi' . +If there is any suspended job, then the current job shall be a +suspended job. If there are at least two suspended jobs, then the +previous job also shall be a suspended job. +.IP "<\fIjob-number\fP>" 10 +A number that can be used to identify the process group to the +.IR wait , +.IR fg , +.IR bg , +and +.IR kill +utilities. Using these utilities, the job can be identified by +prefixing the job number with +.BR '%' . +.IP "<\fIstate\fP>" 10 +One of the following strings (in the POSIX locale): +.RS 10 +.IP "\fBRunning\fR" 10 +Indicates that the job has not been suspended by a signal and has not +exited. +.IP "\fBDone\fR" 10 +Indicates that the job completed and returned exit status zero. +.IP "\fBDone\fR(\fIcode\fR)" 10 +Indicates that the job completed normally and that it exited with the +specified non-zero exit status, +.IR code , +expressed as a decimal number. +.IP "\fBStopped\fR" 10 +Indicates that the job was suspended by the SIGTSTP signal. +.IP "\fBStopped\fR\ (\fBSIGTSTP\fR)" 10 +.br +Indicates that the job was suspended by the SIGTSTP signal. +.IP "\fBStopped\fR\ (\fBSIGSTOP\fR)" 10 +.br +Indicates that the job was suspended by the SIGSTOP signal. +.IP "\fBStopped\fR\ (\fBSIGTTIN\fR)" 10 +.br +Indicates that the job was suspended by the SIGTTIN signal. +.IP "\fBStopped\fR\ (\fBSIGTTOU\fR)" 10 +.br +Indicates that the job was suspended by the SIGTTOU signal. +.P +The implementation may substitute the string +.BR Suspended +in place of +.BR Stopped . +If the job was terminated by a signal, the format of <\fIstate\fP> is +unspecified, but it shall be visibly distinct from all of the other +<\fIstate\fP> formats shown here and shall indicate the name or +description of the signal causing the termination. +.RE +.IP "<\fIcommand\fR>" 10 +The associated command that was given to the shell. +.P +If the +.BR \(mil +option is specified, a field containing the process group ID shall be +inserted before the <\fIstate\fP> field. Also, more processes in a +process group may be output on separate lines, using only the process +ID and <\fIcommand\fP> fields. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mip +option is the only portable way to find out the process group of a job +because different implementations have different strategies for +defining the process group of the job. Usage such as $(\c +.IR jobs +.BR \(mip ) +provides a way of referring to the process group of the job in an +implementation-independent way. +.P +The +.IR jobs +utility does not work as expected when it is operating in its own +utility execution environment because that environment has no +applicable jobs to manipulate. See the APPLICATION USAGE section for +.IR "\fIbg\fR\^". +For this reason, +.IR jobs +is generally implemented as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +Both +.BR \(dq%%\(dq +and +.BR \(dq%+\(dq +are used to refer to the current job. Both forms are of equal +validity\(emthe +.BR \(dq%%\(dq +mirroring +.BR \(dq$$\(dq +and +.BR \(dq%+\(dq +mirroring the output of +.IR jobs . +Both forms reflect historical practice of the KornShell and the C shell +with job control. +.P +The job control features provided by +.IR bg , +.IR fg , +and +.IR jobs +are based on the KornShell. The standard developers examined the +characteristics of the C shell versions of these utilities and found +that differences exist. Despite widespread use of the C shell, the +KornShell versions were selected for this volume of POSIX.1\(hy2008 to maintain a degree of +uniformity with the rest of the KornShell features selected (such as +the very popular command line editing features). +.P +The +.IR jobs +utility is not dependent on the job control option, as are the +seemingly related +.IR bg +and +.IR fg +utilities because +.IR jobs +is useful for examining background jobs, regardless of the condition of +job control. When the user has invoked a +.IR set +.BR +m +command and job control has been turned off, +.IR jobs +can still be used to examine the background jobs associated with that +current session. Similarly, +.IR kill +can then be used to kill background jobs with +.IR kill +%<\fIbackground job number\fP>. +.P +The output for terminated jobs is left unspecified to accommodate +various historical systems. The following formats have been witnessed: +.IP " 1." 4 +.BR Killed (\c +.IR "signal name" ) +.IP " 2." 4 +.IR "signal name" +.IP " 3." 4 +.IR "signal name" (\c +.BR coredump ) +.IP " 4." 4 +.IR "signal description" \(mi +.BR "core dumped" +.P +Most users should be able to understand these formats, although it +means that applications have trouble parsing them. +.P +The calculation of job IDs was not described since this would suggest +an implementation, which may impose unnecessary restrictions. +.P +In an early proposal, a +.BR \(min +option was included to ``Display the status of jobs that have changed, +exited, or stopped since the last status report''. It was removed +because the shell always writes any changed status of jobs before each +prompt. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "\fIbg\fR\^", +.IR "\fIfg\fR\^", +.IR "\fIkill\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/join.1p b/man-pages-posix-2013-a/man1p/join.1p new file mode 100644 index 0000000..a52a155 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/join.1p @@ -0,0 +1,507 @@ +'\" et +.TH JOIN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +join +\(em relational database operator +.SH SYNOPSIS +.LP +.nf +join \fB[\fR\(mia \fIfile_number\fR|\(miv \fIfile_number\fB] [\fR\(mie \fIstring\fB] [\fR\(mio \fIlist\fB] [\fR\(mit \fIchar\fB] + [\fR\(mi1 \fIfield\fB] [\fR\(mi2 \fIfield\fB]\fI file1 file2\fR +.fi +.SH DESCRIPTION +The +.IR join +utility shall perform an equality join on the files +.IR file1 +and +.IR file2 . +The joined files shall be written to the standard output. +.P +The join field is a field in each file on which the files are +compared. The +.IR join +utility shall write one line in the output for each pair of lines in +.IR file1 +and +.IR file2 +that have identical join fields. The output line by default shall +consist of the join field, then the remaining fields from +.IR file1 , +then the remaining fields from +.IR file2 . +This format can be changed by using the +.BR \(mio +option (see below). The +.BR \(mia +option can be used to add unmatched lines to the output. The +.BR \(miv +option can be used to output only unmatched lines. +.P +The files +.IR file1 +and +.IR file2 +shall be ordered in the collating sequence of +.IR sort +.BR \(mib +on the fields on which they shall be joined, by default the first in +each line. All selected output shall be written in the same collating +sequence. +.P +The default input field separators shall be + +characters. In this case, multiple separators shall count as one field +separator, and leading separators shall be ignored. The default output +field separator shall be a +. +.P +The field separator and collating sequence can be changed by using the +.BR \(mit +option (see below). +.P +If the same key appears more than once in either file, all combinations +of the set of remaining fields in +.IR file1 +and the set of remaining fields in +.IR file2 +are output in the order of the lines encountered. +.P +If the input files are not in the appropriate collating sequence, the +results are unspecified. +.SH OPTIONS +The +.IR join +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\ \fIfile_number\fR" 10 +.br +Produce a line for each unpairable line in file +.IR file_number , +where +.IR file_number +is 1 or 2, in addition to the default output. If both +.BR \(mia 1 +and +.BR \(mia 2 +are specified, all unpairable lines shall be output. +.IP "\fB\(mie\ \fIstring\fR" 10 +Replace empty output fields in the list selected by +.BR \(mio +with the string +.IR string . +.IP "\fB\(mio\ \fIlist\fR" 10 +Construct the output line to comprise the fields specified in +.IR list , +each element of which shall have one of the following two forms: +.RS 10 +.IP " 1." 4 +\fIfile_number.field\fR, where +.IR file_number +is a file number and +.IR field +is a decimal integer field number +.IP " 2." 4 +0 (zero), representing the join field +.P +The elements of +.IR list +shall be either +-separated +or +-separated, +as specified in Guideline 8 of the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +The fields specified by +.IR list +shall be written for all selected output lines. Fields selected by +.IR list +that do not appear in the input shall be treated as empty output +fields. (See the +.BR \(mie +option.) Only specifically requested fields shall be written. The +application shall ensure that +.IR list +is a single command line argument. +.RE +.IP "\fB\(mit\ \fIchar\fR" 10 +Use character +.IR char +as a separator, for both input and output. Every appearance of +.IR char +in a line shall be significant. When this option is specified, the +collating sequence shall be the same as +.IR sort +without the +.BR \(mib +option. +.IP "\fB\(miv\ \fIfile_number\fR" 10 +.br +Instead of the default output, produce a line only for each unpairable +line in +.IR file_number , +where +.IR file_number +is 1 or 2. If both +.BR \(miv 1 +and +.BR \(miv 2 +are specified, all unpairable lines shall be output. +.IP "\fB\(mi1\ \fIfield\fR" 10 +Join on the +.IR field th +field of file 1. Fields are decimal integers starting with 1. +.IP "\fB\(mi2\ \fIfield\fR" 10 +Join on the +.IR field th +field of file 2. Fields are decimal integers starting with 1. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fR,\ \fIfile2\fR" 10 +A pathname of a file to be joined. If either of the +.IR file1 +or +.IR file2 +operands is +.BR '\(mi' , +the standard input shall be used in its place. +.SH STDIN +The standard input shall be used only if the +.IR file1 +or +.IR file2 +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR join : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale of the collating sequence +.IR join +expects to have been used when the input files were sorted. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR join +utility output shall be a concatenation of selected character fields. +When the +.BR \(mio +option is not specified, the output shall be: +.sp +.RS 4 +.nf +\fB +"%s%s%s\en", <\fIjoin field\fR>, <\fIother file1 fields\fR>, + <\fIother file2 fields\fR> +.fi \fR +.P +.RE +.P +If the join field is not the first field in a file, the +<\fIother\ file\ fields\fP> for that file shall be: +.sp +.RS 4 +.nf +\fB +<\fIfields preceding join field\fR>, <\fIfields following join field\fR> +.fi \fR +.P +.RE +.P +When the +.BR \(mio +option is specified, the output format shall be: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIconcatenation of fields\fR> +.fi \fR +.P +.RE +.P +where the concatenation of fields is described by the +.BR \(mio +option, above. +.P +For either format, each field (except the last) shall be written with +its trailing separator character. If the separator is the default (\c + +characters), a single + +shall be written after each field (except the last). +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Pathnames consisting of numeric digits or of the form +.IR string.string +should not be specified directly following the +.BR \(mio +list. +.SH EXAMPLES +The +.BR \(mio +0 field essentially selects the union of the join fields. For example, +given file +.BR phone : +.sp +.RS 4 +.nf +\fB +!Name Phone Number +Don +1 123-456-7890 +Hal +1 234-567-8901 +Yasushi +2 345-678-9012 +.fi \fR +.P +.RE +.P +and file +.BR fax : +.sp +.RS 4 +.nf +\fB +!Name Fax Number +Don +1 123-456-7899 +Keith +1 456-789-0122 +Yasushi +2 345-678-9011 +.fi \fR +.P +.RE +.P +(where the large expanses of white space are meant to each represent a +single +), +the command: +.sp +.RS 4 +.nf +\fB +join \(mit "" \(mia 1 \(mia 2 \(mie '(unknown)' \(mio 0,1.2,2.2 phone fax +.fi \fR +.P +.RE +.P +would produce: +.sp +.RS 4 +.nf +\fB +!Name Phone Number Fax Number +Don +1 123-456-7890 +1 123-456-7899 +Hal +1 234-567-8901 (unknown) +Keith (unknown) +1 456-789-0122 +Yasushi +2 345-678-9012 +2 345-678-9011 +.fi \fR +.P +.RE +.P +Multiple instances of the same key will produce combinatorial results. +The following: +.sp +.RS 4 +.nf +\fB +fa: + a x + a y + a z +fb: + a p +.fi \fR +.P +.RE +.P +will produce: +.sp +.RS 4 +.nf +\fB +a x p +a y p +a z p +.fi \fR +.P +.RE +.P +And the following: +.sp +.RS 4 +.nf +\fB +fa: + a b c + a d e +fb: + a w x + a y z + a o p +.fi \fR +.P +.RE +.P +will produce: +.sp +.RS 4 +.nf +\fB +a b c w x +a b c y z +a b c o p +a d e w x +a d e y z +a d e o p +.fi \fR +.P +.RE +.SH RATIONALE +The +.BR \(mie +option is only effective when used with +.BR \(mio +because, unless specific fields are identified using +.BR \(mio , +.IR join +is not aware of what fields might be empty. The exception to this is +the join field, but identifying an empty join field with the +.BR \(mie +string is not historical practice and some scripts might break if this +were changed. +.P +The 0 field in the +.BR \(mio +list was adopted from the Tenth Edition version of +.IR join +to satisfy international objections that the +.IR join +in the base documents does not support the ``full join'' or ``outer +join'' described in relational database literature. Although it has +been possible to include a join field in the output (by default, or by +field number using +.BR \(mio ), +the join field could not be included for an unpaired line selected by +.BR \(mia . +The +.BR \(mio +0 field essentially selects the union of the join fields. +.P +This sort of outer join was not possible with the +.IR join +commands in the base documents. The +.BR \(mio +0 field was chosen because it is an upwards-compatible change for +applications. An alternative was considered: have the join field +represent the union of the fields in the files (where they are +identical for matched lines, and one or both are null for unmatched +lines). This was not adopted because it would break some historical +applications. +.P +The ability to specify +.IR file2 +as +.BR \(mi +is not historical practice; it was added for completeness. +.P +The +.BR \(miv +option is not historical practice, but was considered necessary because +it permitted the writing of +.IR only +those lines that do not match on the join field, as opposed to the +.BR \(mia +option, which prints both lines that do and do not match. This +additional facility is parallel with the +.BR \(miv +option of +.IR grep . +.P +Some historical implementations have been encountered where a blank +line in one of the input files was considered to be the end of the +file; the description in this volume of POSIX.1\(hy2008 does not cite this as an allowable case. +.P +Earlier versions of this standard allowed +.BR \(mij , +.BR \(mij1 , +.BR \(mij2 +options, and a form of the +.BR \(mio +option that allowed the +.IR list +option-argument to be multiple arguments. These forms are no longer +specified by POSIX.1\(hy2008 but may be present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIawk\fR\^", +.IR "\fIcomm\fR\^", +.IR "\fIsort\fR\^", +.IR "\fIuniq\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/kill.1p b/man-pages-posix-2013-a/man1p/kill.1p new file mode 100644 index 0000000..af6c32b --- /dev/null +++ b/man-pages-posix-2013-a/man1p/kill.1p @@ -0,0 +1,460 @@ +'\" et +.TH KILL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +kill +\(em terminate or signal processes +.SH SYNOPSIS +.LP +.nf +kill \(mis \fIsignal_name pid\fR... +.P +kill \(mil \fB[\fIexit_status\fB]\fR +.P +kill \fB[\fR\(mi\fIsignal_name\fB] \fIpid\fR... +.P +kill \fB[\fR\(mi\fIsignal_number\fB] \fIpid\fR... +.fi +.SH DESCRIPTION +The +.IR kill +utility shall send a signal to the process or processes specified by +each +.IR pid +operand. +.P +For each +.IR pid +operand, the +.IR kill +utility shall perform actions equivalent to the +\fIkill\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called with the following arguments: +.IP " *" 4 +The value of the +.IR pid +operand shall be used as the +.IR pid +argument. +.IP " *" 4 +The +.IR sig +argument is the value specified by the +.BR \(mis +option, +.BR \(mi \c +.IR signal_number +option, or the +.BR \(mi \c +.IR signal_name +option, or by SIGTERM, if none of these options is specified. +.SH OPTIONS +The +.IR kill +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that in the last two SYNOPSIS forms, the +.BR \(mi \c +.IR signal_number +and +.BR \(mi \c +.IR signal_name +options are usually more than a single character. +.P +The following options shall be supported: +.IP "\fB\(mil\fP" 10 +(The letter ell.) Write all values of +.IR signal_name +supported by the implementation, if no operand is given. If an +.IR exit_status +operand is given and it is a value of the +.BR '?' +shell special parameter (see +.IR "Section 2.5.2" ", " "Special Parameters" +and +.IR wait ) +corresponding to a process that was terminated by a signal, the +.IR signal_name +corresponding to the signal that terminated the process shall be +written. If an +.IR exit_status +operand is given and it is the unsigned decimal integer value of a +signal number, the +.IR signal_name +(the symbolic constant name without the +.BR SIG +prefix defined in the Base Definitions volume of POSIX.1\(hy2008) corresponding to that signal shall be +written. Otherwise, the results are unspecified. +.IP "\fB\(mis\ \fIsignal_name\fR" 10 +.br +Specify the signal to send, using one of the symbolic names defined in +the +.IR +header. Values of +.IR signal_name +shall be recognized in a case-independent fashion, without the +.BR SIG +prefix. In addition, the symbolic name 0 shall be recognized, +representing the signal value zero. The corresponding signal shall be +sent instead of SIGTERM. +.IP "\fB\(mi\fIsignal_name\fR" 10 +.br +Equivalent to +.BR \(mis +.IR signal_name . +.IP "\fB\(mi\fIsignal_number\fR" 10 +.br +Specify a non-negative decimal integer, +.IR signal_number , +representing the signal to be used instead of SIGTERM, as the +.IR sig +argument in the effective call to +\fIkill\fR(). +The correspondence between integer values and the +.IR sig +value used is shown in the following list. +.RS 10 +.P +The effects of specifying any +.IR signal_number +other than those listed below are undefined. +.IP 0 6 +0 +.IP 1 6 +SIGHUP +.IP 2 6 +SIGINT +.IP 3 6 +SIGQUIT +.IP 6 6 +SIGABRT +.IP 9 6 +SIGKILL +.IP 14 6 +SIGALRM +.IP 15 6 +SIGTERM +.P +If the first argument is a negative integer, it shall be interpreted as a +.BR \(mi \c +.IR signal_number +option, not as a negative +.IR pid +operand specifying a process group. +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIpid\fR" 10 +One of the following: +.RS 10 +.IP " 1." 4 +A decimal integer specifying a process or process group to be signaled. +The process or processes selected by positive, negative, and zero +values of the +.IR pid +operand shall be as described for the +\fIkill\fR() +function. If process number 0 is specified, all processes in the +current process group shall be signaled. For the effects of negative +.IR pid +numbers, see the +\fIkill\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. If the first +.IR pid +operand is negative, it should be preceded by +.BR \(dq\(mi\|\(mi\(dq +to keep it from being interpreted as an option. +.IP " 2." 4 +A job control job ID (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID") +that identifies a background process group to be signaled. The job +control job ID notation is applicable only for invocations of +.IR kill +in the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.RE +.IP "\fIexit_status\fR" 10 +A decimal integer specifying a signal number or the exit status of a +process terminated by a signal. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR kill : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mil +option is not specified, the standard output shall not be used. +.P +When the +.BR \(mil +option is specified, the symbolic name of each signal shall be written +in the following format: +.sp +.RS 4 +.nf +\fB +"%s%c", <\fIsignal_name\fR>, <\fIseparator\fR> +.fi \fR +.P +.RE +.P +where the <\fIsignal_name\fP> is in uppercase, without the +.BR SIG +prefix, and the <\fIseparator\fP> shall be either a + +or a +. +For the last signal written, <\fIseparator\fP> shall be a +. +.P +When both the +.BR \(mil +option and +.IR exit_status +operand are specified, the symbolic name of the corresponding signal +shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIsignal_name\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +At least one matching process was found for each +.IR pid +operand, and the specified signal was successfully processed for at +least one matching process. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Process numbers can be found by using +.IR ps . +.P +The job control job ID notation is not required to work as expected +when +.IR kill +is operating in its own utility execution environment. In either of +the following examples: +.sp +.RS 4 +.nf +\fB +nohup kill %1 & +system("kill %1"); +.fi \fR +.P +.RE +.P +the +.IR kill +operates in a different environment and does not share the shell's +understanding of job numbers. +.SH EXAMPLES +Any of the commands: +.sp +.RS 4 +.nf +\fB +kill \(mi9 100 \(mi165 +kill \(mis kill 100 \(mi165 +kill \(mis KILL 100 \(mi165 +.fi \fR +.P +.RE +.P +sends the SIGKILL signal to the process whose process ID is 100 and to +all processes whose process group ID is 165, assuming the sending +process has permission to send that signal to the specified processes, +and that they exist. +.P +The System Interfaces volume of POSIX.1\(hy2008 and this volume of POSIX.1\(hy2008 do not require specific signal numbers for any +.IR signal_names . +Even the +.BR \(mi \c +.IR signal_number +option provides symbolic (although numeric) names for signals. If a +process is terminated by a signal, its exit status indicates the signal +that killed it, but the exact values are not specified. The +.IR kill +.BR \(mil +option, however, can be used to map decimal signal numbers and exit +status values into the name of a signal. The following example reports +the status of a terminated job: +.sp +.RS 4 +.nf +\fB +job +stat=$? +if [ $stat \(mieq 0 ] +then + echo job completed successfully. +elif [ $stat \(migt 128 ] +then + echo job terminated by signal SIG$(kill \(mil $stat). +else + echo job terminated with error code $stat. +fi +.fi \fR +.P +.RE +.P +To send the default signal to a process group (say 123), an application +should use a command similar to one of the following: +.sp +.RS 4 +.nf +\fB +kill \(miTERM \(mi123 +kill \(mi\|\(mi \(mi123 +.fi \fR +.P +.RE +.SH RATIONALE +The +.BR \(mil +option originated from the C shell, and is also implemented in the +KornShell. The C shell output can consist of multiple output lines +because the signal names do not always fit on a single line on some +terminal screens. The KornShell output also included the +implementation-defined signal numbers and was considered by the +standard developers to be too difficult for scripts to parse +conveniently. The specified output format is intended not only to +accommodate the historical C shell output, but also to permit an +entirely vertical or entirely horizontal listing on systems for which +this is appropriate. +.P +An early proposal invented the name SIGNULL as a +.IR signal_name +for signal 0 (used by the System Interfaces volume of POSIX.1\(hy2008 to test for the existence of a process +without sending it a signal). Since the +.IR signal_name +0 can be used in this case unambiguously, SIGNULL has been removed. +.P +An early proposal also required symbolic +.IR signal_name s +to be recognized with or without the +.BR SIG +prefix. Historical versions of +.IR kill +have not written the +.BR SIG +prefix for the +.BR \(mil +option and have not recognized the +.BR SIG +prefix on +.IR signal_name s. +Since neither applications portability nor ease-of-use would be improved +by requiring this extension, it is no longer required. +.P +To avoid an ambiguity of an initial negative number argument specifying +either a signal number or a process group, POSIX.1\(hy2008 mandates that it is +always considered the former by implementations that support the XSI +option. It also requires that conforming applications always use the +.BR \(dq\(mi\|\(mi\(dq +options terminator argument when specifying a process group, unless an +option is also specified. +.P +The +.BR \(mis +option was added in response to international interest in providing +some form of +.IR kill +that meets the Utility Syntax Guidelines. +.P +The job control job ID notation is not required to work as expected +when +.IR kill +is operating in its own utility execution environment. In either of +the following examples: +.sp +.RS 4 +.nf +\fB +nohup kill %1 & +system("kill %1"); +.fi \fR +.P +.RE +.P +the +.IR kill +operates in a different environment and does not understand how the +shell has managed its job numbers. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIps\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIkill\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/lex.1p b/man-pages-posix-2013-a/man1p/lex.1p new file mode 100644 index 0000000..dc02c3f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/lex.1p @@ -0,0 +1,1374 @@ +'\" et +.TH LEX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lex +\(em generate programs for lexical tasks (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +lex \fB[\fR\(mit\fB] [\fR\(min|\(miv\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR lex +utility shall generate C programs to be used in lexical processing of +character input, and that can be used as an interface to +.IR yacc . +The C programs shall be generated from +.IR lex +source code and conform to the ISO\ C standard, without depending on any undefined, +unspecified, or implementation-defined behavior, except in cases where +the code is copied directly from the supplied source, or in cases that +are documented by the implementation. Usually, the +.IR lex +utility shall write the program it generates to the file +.BR lex.yy.c ; +the state of this file is unspecified if +.IR lex +exits with a non-zero exit status. See the EXTENDED DESCRIPTION +section for a complete description of the +.IR lex +input language. +.SH OPTIONS +The +.IR lex +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(min\fP" 10 +Suppress the summary of statistics usually written with the +.BR \(miv +option. If no table sizes are specified in the +.IR lex +source code and the +.BR \(miv +option is not specified, then +.BR \(min +is implied. +.IP "\fB\(mit\fP" 10 +Write the resulting program to standard output instead of +.BR lex.yy.c . +.IP "\fB\(miv\fP" 10 +Write a summary of +.IR lex +statistics to the standard output. (See the discussion of +.IR lex +table sizes in +.IR "Definitions in lex".) +If the +.BR \(mit +option is specified and +.BR \(min +is not specified, this report shall be written to standard error. If +table sizes are specified in the +.IR lex +source code, and if the +.BR \(min +option is not specified, the +.BR \(miv +option may be enabled. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If more than one such +.IR file +is specified, all files shall be concatenated to produce a single +.IR lex +program. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See INPUT FILES. +.SH "INPUT FILES" +The input files shall be text files containing +.IR lex +source code, as described in the EXTENDED DESCRIPTION section. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR lex : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. If +this variable is not set to the POSIX locale, the results are +unspecified. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), and the behavior +of character classes within regular expressions. If this variable is +not set to the POSIX locale, the results are unspecified. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mit +option is specified, the text file of C source code output of +.IR lex +shall be written to standard output. +.P +If the +.BR \(mit +option is not specified: +.IP " *" 4 +Implementation-defined informational, error, and warning messages +concerning the contents of +.IR lex +source code input shall be written to either the standard output or +standard error. +.IP " *" 4 +If the +.BR \(miv +option is specified and the +.BR \(min +option is not specified, +.IR lex +statistics shall also be written to either the standard output or +standard error, in an implementation-defined format. These +statistics may also be generated if table sizes are specified with a +.BR '%' +operator in the +.IR Definitions +section, as long as the +.BR \(min +option is not specified. +.SH STDERR +If the +.BR \(mit +option is specified, implementation-defined informational, error, and +warning messages concerning the contents of +.IR lex +source code input shall be written to the standard error. +.P +If the +.BR \(mit +option is not specified: +.IP " 1." 4 +Implementation-defined informational, error, and warning messages +concerning the contents of +.IR lex +source code input shall be written to either the standard output or +standard error. +.IP " 2." 4 +If the +.BR \(miv +option is specified and the +.BR \(min +option is not specified, +.IR lex +statistics shall also be written to either the standard output or +standard error, in an implementation-defined format. These +statistics may also be generated if table sizes are specified with a +.BR '%' +operator in the +.IR Definitions +section, as long as the +.BR \(min +option is not specified. +.SH "OUTPUT FILES" +A text file containing C source code shall be written to +.BR lex.yy.c , +or to the standard output if the +.BR \(mit +option is present. +.SH "EXTENDED DESCRIPTION" +Each input file shall contain +.IR lex +source code, which is a table of regular expressions with corresponding +actions in the form of C program fragments. +.P +When +.BR lex.yy.c +is compiled and linked with the +.IR lex +library (using the +.BR "\(mil\ l" +operand with +.IR c99 ), +the resulting program shall read character input from the standard +input and shall partition it into strings that match the given +expressions. +.br +.P +When an expression is matched, these actions shall occur: +.IP " *" 4 +The input string that was matched shall be left in +.IR yytext +as a null-terminated string; +.IR yytext +shall either be an external character array or a pointer to a +character string. As explained in +.IR "Definitions in lex", +the type can be explicitly selected using the +.BR %array +or +.BR %pointer +declarations, but the default is implementation-defined. +.IP " *" 4 +The external +.BR int +.IR yyleng +shall be set to the length of the matching string. +.IP " *" 4 +The expression's corresponding program fragment, or action, shall be +executed. +.P +During pattern matching, +.IR lex +shall search the set of patterns for the single longest possible +match. Among rules that match the same number of characters, the rule +given first shall be chosen. +.P +The general format of +.IR lex +source shall be: +.sp +.RS +.IR Definitions +.BR %% +.IR Rules +.BR %% +.IR User Subroutines +.RE +.P +The first +.BR \(dq%%\(dq +is required to mark the beginning of the rules (regular expressions and +actions); the second +.BR \(dq%%\(dq +is required only if user subroutines follow. +.P +Any line in the +.IR Definitions +section beginning with a + +shall be assumed to be a C program fragment and shall be copied to the +external definition area of the +.BR lex.yy.c +file. Similarly, anything in the +.IR Definitions +section included between delimiter lines containing only +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +shall also be copied unchanged to the external definition area of the +.BR lex.yy.c +file. +.P +Any such input (beginning with a + +or within +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +delimiter lines) appearing at the beginning of the +.IR Rules +section before any rules are specified shall be written to +.BR lex.yy.c +after the declarations of variables for the +\fIyylex\fR() +function and before the first line of code in +\fIyylex\fR(). +Thus, user variables local to +\fIyylex\fR() +can be declared here, as well as application code to execute upon entry +to +\fIyylex\fR(). +.P +The action taken by +.IR lex +when encountering any input beginning with a + +or within +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +delimiter lines appearing in the +.IR Rules +section but coming after one or more rules is undefined. The presence +of such input may result in an erroneous definition of the +\fIyylex\fR() +function. +.P +C-language code in the input shall not contain C-language trigraphs. +The C-language code within +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +delimiter lines shall not contain any lines consisting only of +.BR \(dq%}\(dq , +or only of +.BR \(dq%%\(dq . +.SS "Definitions in lex" +.P +.IR Definitions +appear before the first +.BR \(dq%%\(dq +delimiter. Any line in this section not contained between +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +lines and not beginning with a + +shall be assumed to define a +.IR lex +substitution string. The format of these lines shall be: +.sp +.RS 4 +.nf +\fB +\fIname substitute\fR +.fi \fR +.P +.RE +.P +If a +.IR name +does not meet the requirements for identifiers in the ISO\ C standard, the result +is undefined. The string +.IR substitute +shall replace the string {\c +.IR name } +when it is used in a rule. The +.IR name +string shall be recognized in this context only when the braces are +provided and when it does not appear within a bracket expression or +within double-quotes. +.P +In the +.IR Definitions +section, any line beginning with a + +(\c +.BR '%' ) +character and followed by an alphanumeric word beginning with either +.BR 's' +or +.BR 'S' +shall define a set of start conditions. Any line beginning with a +.BR '%' +followed by a word beginning with either +.BR 'x' +or +.BR 'X' +shall define a set of exclusive start conditions. When the generated +scanner is in a +.BR %s +state, patterns with no state specified shall be also active; in a +.BR %x +state, such patterns shall not be active. The rest of the line, after +the first word, shall be considered to be one or more +-separated +names of start conditions. Start condition names shall be constructed +in the same way as definition names. Start conditions can be used to +restrict the matching of regular expressions to one or more states as +described in +.IR "Regular Expressions in lex". +.P +Implementations shall accept either of the following two +mutually-exclusive declarations in the +.IR Definitions +section: +.IP "\fB%array\fR" 10 +Declare the type of +.IR yytext +to be a null-terminated character array. +.IP "\fB%pointer\fR" 10 +Declare the type of +.IR yytext +to be a pointer to a null-terminated character string. +.P +The default type of +.IR yytext +is implementation-defined. If an application refers to +.IR yytext +outside of the scanner source file (that is, via an +.BR extern ), +the application shall include the appropriate +.BR %array +or +.BR %pointer +declaration in the scanner source file. +.P +Implementations shall accept declarations in the +.IR Definitions +section for setting certain internal table sizes. The declarations are +shown in the following table. +.sp +.ce 1 +\fBTable: Table Size Declarations in \fIlex\fP\fR +.TS +center tab(!) box; +cB | cB | cB +l | l | n. +Declaration!Description!Minimum Value +_ +%\fBp \fIn\fR!Number of positions!2\|500 +%\fBn \fIn\fR!Number of states!500 +%\fBa \fIn\fR!Number of transitions!2\|000 +%\fBe \fIn\fR!Number of parse tree nodes!1\|000 +%\fBk \fIn\fR!Number of packed character classes!1\|000 +%\fBo \fIn\fR!Size of the output array!3\|000 +.TE +.P +In the table, +.IR n +represents a positive decimal integer, preceded by one or more + +characters. The exact meaning of these table size numbers is +implementation-defined. The implementation shall document how these +numbers affect the +.IR lex +utility and how they are related to any output that may be generated by +the implementation should limitations be encountered during the +execution of +.IR lex . +It shall be possible to determine from this output which of the table +size values needs to be modified to permit +.IR lex +to successfully generate tables for the input language. The values in +the column Minimum Value represent the lowest values conforming +implementations shall provide. +.SS "Rules in lex" +.P +The rules in +.IR lex +source files are a table in which the left column contains regular +expressions and the right column contains actions (C program fragments) +to be executed when the expressions are recognized. +.sp +.RS 4 +.nf +\fB +\fIERE action +ERE action\fP +\&... +.fi \fR +.P +.RE +.P +The extended regular expression (ERE) portion of a row shall be +separated from +.IR action +by one or more + +characters. A regular expression containing + +characters shall be recognized under one of the following conditions: +.IP " *" 4 +The entire expression appears within double-quotes. +.IP " *" 4 +The + +characters appear within double-quotes or square brackets. +.IP " *" 4 +Each + +is preceded by a + +character. +.SS "User Subroutines in lex" +.P +Anything in the user subroutines section shall be copied to +.BR lex.yy.c +following +\fIyylex\fR(). +.SS "Regular Expressions in lex" +.P +The +.IR lex +utility shall support the set of extended regular expressions (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions"), +with the following additions and exceptions to the syntax: +.IP "\fR\&\(dq...\&\(dq\fR" 10 +Any string enclosed in double-quotes shall represent the characters +within the double-quotes as themselves, except that +-escapes +(which appear in the following table) shall be recognized. Any +-escape +sequence shall be terminated by the closing quote. For example, +.BR \(dq\e01\(dq \c +.BR \(dq1\(dq +represents a single string: the octal value 1 followed by the +character +.BR '1' . +.IP "<\fIstate\fR>\fIr\fR,\ <\fIstate1,state2,\fR.\|.\|.>\fIr\fR" 10 +.br +The regular expression +.IR r +shall be matched only when the program is in one of the start +conditions indicated by +.IR state , +.IR state1 , +and so on; see +.IR "Actions in lex". +(As an exception to the typographical conventions of the rest of this volume of POSIX.1\(hy2008, +in this case <\fIstate\fP> does not represent a metavariable, but the +literal angle-bracket characters surrounding a symbol.) The start +condition shall be recognized as such only at the beginning of a +regular expression. +.IP "\fIr\fP/\fIx\fP" 10 +The regular expression +.IR r +shall be matched only if it is followed by an occurrence of regular +expression +.IR x +(\c +.IR x +is the instance of trailing context, further defined below). The token +returned in +.IR yytext +shall only match +.IR r . +If the trailing portion of +.IR r +matches the beginning of +.IR x , +the result is unspecified. The +.IR r +expression cannot include further trailing context or the +.BR '$' +(match-end-of-line) operator; +.IR x +cannot include the +.BR '^' +(match-beginning-of-line) operator, nor trailing context, nor the +.BR '$' +operator. That is, only one occurrence of trailing context is allowed +in a +.IR lex +regular expression, and the +.BR '^' +operator only can be used at the beginning of such an expression. +.IP "{\fIname\fR}" 10 +When +.IR name +is one of the substitution symbols from the +.IR Definitions +section, the string, including the enclosing braces, shall be replaced +by the +.IR substitute +value. The +.IR substitute +value shall be treated in the extended regular expression as if it were +enclosed in parentheses. No substitution shall occur if {\c +.IR name } +occurs within a bracket expression or within double-quotes. +.P +Within an ERE, a + +character shall be considered to begin an escape sequence as specified +in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +In addition, the escape sequences in the following table shall be +recognized. +.P +A literal + +cannot occur within an ERE; the escape sequence +.BR '\en' +can be used to represent a +. +A + +shall not be matched by a period operator. +.br +.sp +.ce 1 +\fBTable: Escape Sequences in \fIlex\fP\fR +.ad l +.TS +center tab(@) box; +cB | cB | cB +cB | cB | cB +lf5 | lw(2.4i) | lw(2.4i). +Escape +Sequence@Description@Meaning +_ +\e\fIdigits\fP@T{ +A + +character followed by the longest sequence of one, two, or three +octal-digit characters (01234567). If all of the digits are 0 (that is, +representation of the NUL character), the behavior is undefined. +T}@T{ +The character whose encoding is represented by the one, two, or +three-digit octal integer. Multi-byte characters require +multiple, concatenated escape sequences of this type, including the +leading + +for each byte. +T} +_ +\ex\fIdigits\fP@T{ +A + +character followed by the longest sequence of hexadecimal-digit +characters (01234567abcdefABCDEF). If all of the digits are 0 (that is, +representation of the NUL character), the behavior is undefined. +T}@T{ +The character whose encoding is represented by the hexadecimal +integer. +T} +_ +\ec@T{ +A + +character followed by any character not described in this +table or in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +T}@T{ +The character +.BR 'c' , +unchanged. +T} +.TE +.ad b +.TP 10 +.BR Note: +If a +.BR '\ex' +sequence needs to be immediately followed by a hexadecimal digit +character, a sequence such as +.BR \(dq\ex1\(dq \c +.BR \(dq1\(dq +can be used, which represents a character containing the value 1, +followed by the character +.BR '1' . +.P +.P +The order of precedence given to extended regular expressions for +.IR lex +differs from that specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions". +The order of precedence for +.IR lex +shall be as shown in the following table, from high to low. +.TP 10 +.BR Note: +The escaped characters entry is not meant to imply that these are +operators, but they are included in the table to show their +relationships to the true operators. The start condition, trailing +context, and anchoring notations have been omitted from the table +because of the placement restrictions described in this section; they +can only appear at the beginning or ending of an ERE. +.P +.br +.sp +.ce 1 +\fBTable: ERE Precedence in \fIlex\fP\fR +.TS +center tab(@) box; +cB | cB +lf2 | lf5. +Extended Regular Expression@Precedence +_ +collation-related bracket symbols@[= =] [: :] [. .] +escaped characters@\e<\fIspecial character\fP> +bracket expression@[ ] +quoting@"..." +grouping@( ) +definition@{\fIname\fP} +single-character RE duplication@* + ? +concatenation +interval expression@{m,n} +alternation@| +.TE +.P +The ERE anchoring operators +.BR '^' +and +.BR '$' +do not appear in the table. With +.IR lex +regular expressions, these operators are restricted in their use: the +.BR '^' +operator can only be used at the beginning of an entire regular +expression, and the +.BR '$' +operator only at the end. The operators apply to the entire regular +expression. Thus, for example, the pattern +.BR \(dq(^abc)|(def$)\(dq +is undefined; it can instead be written as two separate rules, one with +the regular expression +.BR \(dq^abc\(dq +and one with +.BR \(dqdef$\(dq , +which share a common action via the special +.BR '|' +action (see below). If the pattern were written +.BR \(dq^abc|def$\(dq , +it would match either +.BR \(dqabc\(dq +or +.BR \(dqdef\(dq +on a line by itself. +.P +Unlike the general ERE rules, embedded anchoring is not allowed by most +historical +.IR lex +implementations. An example of embedded anchoring would be for +patterns such as +.BR \(dq(^|\ )foo(\ |$)\(dq +to match +.BR \(dqfoo\(dq +when it exists as a complete word. This functionality can be obtained +using existing +.IR lex +features: +.sp +.RS 4 +.nf +\fB +^foo/[ \en] | +" foo"/[ \en] /* Found foo as a separate word. */ +.fi \fR +.P +.RE +.P +Note also that +.BR '$' +is a form of trailing context (it is equivalent to +.BR \(dq/\en\(dq ) +and as such cannot be used with regular expressions containing another +instance of the operator (see the preceding discussion of trailing +context). +.P +The additional regular expressions trailing-context operator +.BR '/' +can be used as an ordinary character if presented within double-quotes, +.BR \(dq/\(dq ; +preceded by a +, +.BR \(dq\e/\(dq ; +or within a bracket expression, +.BR \(dq[/]\(dq . +The start-condition +.BR '<' +and +.BR '>' +operators shall be special only in a start condition at the beginning +of a regular expression; elsewhere in the regular expression they shall +be treated as ordinary characters. +.SS "Actions in lex" +.P +The action to be taken when an ERE is matched can be a C program +fragment or the special actions described below; the program fragment +can contain one or more C statements, and can also include special +actions. The empty C statement +.BR ';' +shall be a valid action; any string in the +.BR lex.yy.c +input that matches the pattern portion of such a rule is effectively +ignored or skipped. However, the absence of an action shall not be +valid, and the action +.IR lex +takes in such a condition is undefined. +.P +The specification for an action, including C statements and special +actions, can extend across several lines if enclosed in braces: +.sp +.RS 4 +.nf +\fB +\fIERE\fP <\fIone or more blanks\fR> { \fIprogram statement + program statement\fP } +.fi \fR +.P +.RE +.P +The program statements shall not contain unbalanced curly brace +preprocessing tokens. +.P +The default action when a string in the input to a +.BR lex.yy.c +program is not matched by any expression shall be to copy the string to +the output. Because the default behavior of a program generated by +.IR lex +is to read the input and copy it to the output, a minimal +.IR lex +source program that has just +.BR \(dq%%\(dq +shall generate a C program that simply copies the input to the output +unchanged. +.P +Four special actions shall be available: +.sp +.RS 4 +.nf +\fB +| ECHO; REJECT; BEGIN +.fi \fR +.P +.RE +.IP "\fR|\fR" 10 +The action +.BR '|' +means that the action for the next rule is the action for this rule. +Unlike the other three actions, +.BR '|' +cannot be enclosed in braces or be +-terminated; +the application shall ensure that it is specified alone, with no other +actions. +.IP "\fBECHO;\fR" 10 +Write the contents of the string +.IR yytext +on the output. +.IP "\fBREJECT;\fR" 10 +Usually only a single expression is matched by a given string in the +input. +.BR REJECT +means ``continue to the next expression that matches the current +input'', and shall cause whatever rule was the second choice after the +current rule to be executed for the same input. Thus, multiple rules +can be matched and executed for one input string or overlapping input +strings. For example, given the regular expressions +.BR \(dqxyz\(dq +and +.BR \(dqxy\(dq +and the input +.BR \(dqxyz\(dq , +usually only the regular expression +.BR \(dqxyz\(dq +would match. The next attempted match would start after +.BR z. +If the last action in the +.BR \(dqxyz\(dq +rule is +.BR REJECT , +both this rule and the +.BR \(dqxy\(dq +rule would be executed. The +.BR REJECT +action may be implemented in such a fashion that flow of control does +not continue after it, as if it were equivalent to a +.BR goto +to another part of +\fIyylex\fR(). +The use of +.BR REJECT +may result in somewhat larger and slower scanners. +.IP "\fBBEGIN\fR" 10 +The action: +.RS 10 +.sp +.RS 4 +.nf +\fB +BEGIN \fInewstate\fP; +.fi \fR +.P +.RE +.P +switches the state (start condition) to +.IR newstate . +If the string +.IR newstate +has not been declared previously as a start condition in the +.IR Definitions +section, the results are unspecified. The initial state is indicated +by the digit +.BR '0' +or the token +.BR INITIAL . +.RE +.P +The functions or macros described below are accessible to user code +included in the +.IR lex +input. It is unspecified whether they appear in the C code output of +.IR lex , +or are accessible only through the +.BR "\(mil\ l" +operand to +.IR c99 +(the +.IR lex +library). +.IP "\fBint\ \fIyylex\fR(\fBvoid\fR)" 6 +.br +Performs lexical analysis on the input; this is the primary function +generated by the +.IR lex +utility. The function shall return zero when the end of input is +reached; otherwise, it shall return non-zero values (tokens) determined +by the actions that are selected. +.IP "\fBint\ \fIyymore\fR(\fBvoid\fR)" 6 +.br +When called, indicates that when the next input string is recognized, +it is to be appended to the current value of +.IR yytext +rather than replacing it; the value in +.IR yyleng +shall be adjusted accordingly. +.IP "\fBint\ \fIyyless\fR(\fBint\ \fIn\fR)" 6 +.br +Retains +.IR n +initial characters in +.IR yytext , +NUL-terminated, and treats the remaining characters as if they had not +been read; the value in +.IR yyleng +shall be adjusted accordingly. +.IP "\fBint\ \fIinput\fR(\fBvoid\fR)" 6 +.br +Returns the next character from the input, or zero on end-of-file. It +shall obtain input from the stream pointer +.IR yyin , +although possibly via an intermediate buffer. Thus, once scanning has +begun, the effect of altering the value of +.IR yyin +is undefined. The character read shall be removed from the input +stream of the scanner without any processing by the scanner. +.IP "\fBint\ \fIunput\fR(\fBint\ \fIc\fR)" 6 +.br +Returns the character +.BR 'c' +to the input; +.IR yytext +and +.IR yyleng +are undefined until the next expression is matched. The result of +using +\fIunput\fR() +for more characters than have been input is unspecified. +.P +The following functions shall appear only in the +.IR lex +library accessible through the +.BR "\(mil\ l" +operand; they can therefore be redefined by a conforming application: +.IP "\fBint\ \fIyywrap\fR(\fBvoid\fR)" 6 +.br +Called by +\fIyylex\fR() +at end-of-file; the default +\fIyywrap\fR() +shall always return 1. If the application requires +\fIyylex\fR() +to continue processing with another source of input, then the +application can include a function +\fIyywrap\fR(), +which associates another file with the external variable +.BR "FILE *" +.IR yyin +and shall return a value of zero. +.IP "\fBint\ \fImain\fR(\fBint\ \fIargc\fR, \fBchar *\fIargv\fR[\|])" 6 +.br +Calls +\fIyylex\fR() +to perform lexical analysis, then exits. The user code can contain +\fImain\fR() +to perform application-specific operations, calling +\fIyylex\fR() +as applicable. +.P +Except for +\fIinput\fR(), +\fIunput\fR(), +and +\fImain\fR(), +all external and static names generated by +.IR lex +shall begin with the prefix +.BR yy +or +.BR YY . +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Conforming applications are warned that in the +.IR Rules +section, an ERE without an action is not acceptable, but need not be +detected as erroneous by +.IR lex . +This may result in compilation or runtime errors. +.P +The purpose of +\fIinput\fR() +is to take characters off the input stream and discard them as far as +the lexical analysis is concerned. A common use is to discard the body +of a comment once the beginning of a comment is recognized. +.P +The +.IR lex +utility is not fully internationalized in its treatment of regular +expressions in the +.IR lex +source code or generated lexical analyzer. It would seem desirable to +have the lexical analyzer interpret the regular expressions given in +the +.IR lex +source according to the environment specified when the lexical analyzer +is executed, but this is not possible with the current +.IR lex +technology. Furthermore, the very nature of the lexical analyzers +produced by +.IR lex +must be closely tied to the lexical requirements of the input language +being described, which is frequently locale-specific anyway. (For +example, writing an analyzer that is used for French text is not +automatically useful for processing other languages.) +.SH EXAMPLES +The following is an example of a +.IR lex +program that implements a rudimentary scanner for a Pascal-like +syntax: +.sp +.RS 4 +.nf +\fB +%{ +/* Need this for the call to atof() below. */ +#include +/* Need this for printf(), fopen(), and stdin below. */ +#include +%} +.P +DIGIT [0\(mi9] +ID [a\(miz][a\(miz0\(mi9]* +.P +%% +.P +{DIGIT}+ { + printf("An integer: %s (%d)\en", yytext, + atoi(yytext)); + } +.P +{DIGIT}+"."{DIGIT}* { + printf("A float: %s (%g)\en", yytext, + atof(yytext)); + } +.P +if|then|begin|end|procedure|function { + printf("A keyword: %s\en", yytext); + } +.P +{ID} printf("An identifier: %s\en", yytext); +.P +"+"|"\(mi"|"*"|"/" printf("An operator: %s\en", yytext); +.P +"{"[^}\en]*"}" /* Eat up one-line comments. */ +.P +[ \et\en]+ /* Eat up white space. */ +.P +\&. printf("Unrecognized character: %s\en", yytext); +.P +%% +.P +int main(int argc, char *argv[]) +{ + ++argv, \(mi\|\(miargc; /* Skip over program name. */ + if (argc > 0) + yyin = fopen(argv[0], "r"); + else + yyin = stdin; +.P + yylex(); +} +.fi \fR +.P +.RE +.SH RATIONALE +Even though the +.BR \(mic +option and references to the C language are retained in this +description, +.IR lex +may be generalized to other languages, as was done at one time for EFL, +the Extended FORTRAN Language. Since the +.IR lex +input specification is essentially language-independent, versions of +this utility could be written to produce Ada, Modula-2, or Pascal code, +and there are known historical implementations that do so. +.P +The current description of +.IR lex +bypasses the issue of dealing with internationalized EREs in the +.IR lex +source code or generated lexical analyzer. If it follows the model used +by +.IR awk +(the source code is assumed to be presented in the POSIX locale, but +input and output are in the locale specified by the environment +variables), then the tables in the lexical analyzer produced by +.IR lex +would interpret EREs specified in the +.IR lex +source in terms of the environment variables specified when +.IR lex +was executed. The desired effect would be to have the lexical analyzer +interpret the EREs given in the +.IR lex +source according to the environment specified when the lexical analyzer +is executed, but this is not possible with the current +.IR lex +technology. +.P +The description of octal and hexadecimal-digit escape sequences agrees +with the ISO\ C standard use of escape sequences. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.P +There is no detailed output format specification. The observed behavior +of +.IR lex +under four different historical implementations was that none of these +implementations consistently reported the line numbers for error and +warning messages. Furthermore, there was a desire that +.IR lex +be allowed to output additional diagnostic messages. Leaving message +formats unspecified avoids these formatting questions and problems with +internationalization. +.P +Although the +.BR %x +specifier for +.IR exclusive +start conditions is not historical practice, it is believed to be a +minor change to historical implementations and greatly enhances the +usability of +.IR lex +programs since it permits an application to obtain the expected +functionality with fewer statements. +.P +The +.BR %array +and +.BR %pointer +declarations were added as a compromise between historical systems. +The System V-based +.IR lex +copies the matched text to a +.IR yytext +array. The +.IR flex +program, supported in BSD and GNU systems, uses a pointer. In the +latter case, significant performance improvements are available for +some scanners. Most historical programs should require no change in +porting from one system to another because the string being referenced +is null-terminated in both cases. (The method used by +.IR flex +in its case is to null-terminate the token in place by remembering the +character that used to come right after the token and replacing it +before continuing on to the next scan.) Multi-file programs with +external references to +.IR yytext +outside the scanner source file should continue to operate on their +historical systems, but would require one of the new declarations to be +considered strictly portable. +.P +The description of EREs avoids unnecessary duplication of ERE details +because their meanings within a +.IR lex +ERE are the same as that for the ERE in this volume of POSIX.1\(hy2008. +.P +The reason for the undefined condition associated with text beginning +with a + +or within +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +delimiter lines appearing in the +.IR Rules +section is historical practice. Both the BSD and System V +.IR lex +copy the indented (or enclosed) input in the +.IR Rules +section (except at the beginning) to unreachable areas of the +\fIyylex\fR() +function (the code is written directly after a +.IR break +statement). In some cases, the System V +.IR lex +generates an error message or a syntax error, depending on the form of +indented input. +.P +The intention in breaking the list of functions into those that may +appear in +.BR lex.yy.c +\fIversus\fR those that only appear in +.BR libl.a +is that only those functions in +.BR libl.a +can be reliably redefined by a conforming application. +.P +The descriptions of standard output and standard error are somewhat +complicated because historical +.IR lex +implementations chose to issue diagnostic messages to standard output +(unless +.BR \(mit +was given). POSIX.1\(hy2008 allows this behavior, but leaves an opening +for the more expected behavior of using standard error for diagnostics. +Also, the System V behavior of writing the statistics when any table +sizes are given is allowed, while BSD-derived systems can avoid it. The +programmer can always precisely obtain the desired results by using +either the +.BR \(mit +or +.BR \(min +options. +.P +The OPERANDS section does not mention the use of +.BR \(mi +as a synonym for standard input; not all historical implementations +support such usage for any of the +.IR file +operands. +.P +A description of the +.IR "translation table" +was deleted from early proposals because of its relatively low usage in +historical applications. +.P +The change to the definition of the +\fIinput\fR() +function that allows buffering of input presents the opportunity for +major performance gains in some applications. +.P +The following examples clarify the differences between +.IR lex +regular expressions and regular expressions appearing elsewhere in +\&this volume of POSIX.1\(hy2008. For regular expressions of the form +.BR \(dqr/x\(dq , +the string matching +.IR r +is always returned; confusion may arise when the beginning of +.IR x +matches the trailing portion of +.IR r . +For example, given the regular expression +.BR \(dqa*b/cc\(dq +and the input +.BR \(dqaaabcc\(dq , +.IR yytext +would contain the string +.BR \(dqaaab\(dq +on this match. But given the regular expression +.BR \(dqx*/xy\(dq +and the input +.BR \(dqxxxy\(dq , +the token +.BR xxx , +not +.BR xx , +is returned by some implementations because +.BR xxx +matches +.BR \(dqx*\(dq . +.P +In the rule +.BR \(dqab*/bc\(dq , +the +.BR \(dqb*\(dq +at the end of +.IR r +extends +.IR r 's +match into the beginning of the trailing context, so the result is +unspecified. If this rule were +.BR \(dqab/bc\(dq , +however, the rule matches the text +.BR \(dqab\(dq +when it is followed by the text +.BR \(dqbc\(dq . +In this latter case, the matching of +.IR r +cannot extend into the beginning of +.IR x , +so the result is specified. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIed\fR\^", +.IR "\fIyacc\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 9" ", " "Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/link.1p b/man-pages-posix-2013-a/man1p/link.1p new file mode 100644 index 0000000..12b08e0 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/link.1p @@ -0,0 +1,122 @@ +'\" et +.TH LINK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +link \(em call +\fIlink\fR() +function +.SH SYNOPSIS +.LP +.nf +link \fIfile1 file2\fR +.fi +.SH DESCRIPTION +The +.IR link +utility shall perform the function call: +.sp +.RS 4 +.nf +\fB +link(\fIfile1\fR, \fIfile2\fR); +.fi \fR +.P +.RE +.P +A user may need appropriate privileges to invoke the +.IR link +utility. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fP" 10 +The pathname of an existing file. +.IP "\fIfile2\fP" 10 +The pathname of the new directory entry to be created. +.SH STDIN +Not used. +.SH "INPUT FILES" +Not used. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR link : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIln\fR\^", +.IR "\fIunlink\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ln.1p b/man-pages-posix-2013-a/man1p/ln.1p new file mode 100644 index 0000000..d3e62a0 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ln.1p @@ -0,0 +1,469 @@ +'\" et +.TH LN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ln +\(em link files +.SH SYNOPSIS +.LP +.nf +ln \fB[\fR\(mifs\fB] [\fR\(miL|\(miP\fB] \fIsource_file target_file\fR +.P +ln \fB[\fR\(mifs\fB] [\fR\(miL|\(miP\fB] \fIsource_file\fR... \fItarget_dir\fR +.fi +.SH DESCRIPTION +In the first synopsis form, the +.IR ln +utility shall create a new directory entry (link) at the +destination path specified by the +.IR target_file +operand. If the +.BR \(mis +option is specified, a symbolic link shall be created for the file +specified by the +.IR source_file +operand. This first synopsis form shall be assumed when the final +operand does not name an existing directory; if more than two operands +are specified and the final is not an existing directory, an error +shall result. +.P +In the second synopsis form, the +.IR ln +utility shall create a new directory entry (link), or if the +.BR \(mis +option is specified a symbolic link, for each file specified by a +.IR source_file +operand, at a destination path in the existing directory named by +.IR target_dir . +.P +If the last operand specifies an existing file of a type not +specified by the System Interfaces volume of POSIX.1\(hy2008, the behavior is implementation-defined. +.P +The corresponding destination path for each +.IR source_file +shall be the concatenation of the target directory pathname, a + +character if the target directory pathname did not end in a +, +and the last pathname component of the +.IR source_file . +The second synopsis form shall be assumed when the final operand names +an existing directory. +.P +For each +.IR source_file : +.IP " 1." 4 +If the destination path exists and was created by a previous step, +it is unspecified whether +.IR ln +shall write a diagnostic message to standard error, do nothing more with +the current +.IR source_file , +and go on to any remaining +.IR source_file s; +or will continue processing the current +.IR source_file . +If the destination path exists: +.RS 4 +.IP " a." 4 +If the +.BR \(mif +option is not specified, +.IR ln +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.IP " b." 4 +If +.IR destination +names the same directory entry as the current +.IR source_file +.IR ln +shall write a diagnostic message to standard error, do nothing more with +the current +.IR source_file , +and go on to any remaining +.IR source_file s . +.IP " c." 4 +Actions shall be performed equivalent to the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called using +.IR destination +as the +.IR path +argument. If this fails for any reason, +.IR ln +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.RE +.IP " 2." 4 +If the +.BR \(mis +option is specified, actions shall be performed equivalent to the +\fIsymlink\fR() +function with +.IR source_file +as the +.IR path1 +argument and the destination path as the +.IR path2 +argument. The +.IR ln +utility shall do nothing more with +.IR source_file +and shall go on to any remaining files. +.IP " 3." 4 +If +.IR source_file +is a symbolic link: +.RS 4 +.IP " a." 4 +If the +.BR \(miP +option is in effect, actions shall be performed equivalent to the +\fIlinkat\fR() +function with +.IR source_file +as the +.IR path1 +argument, the destination path as the +.IR path2 +argument, AT_FDCWD as the +.IR fd1 +and +.IR fd2 +arguments, and zero as the +.IR flag +argument. +.IP " b." 4 +If the +.BR \(miL +option is in effect, actions shall be performed equivalent to the +\fIlinkat\fR() +function with +.IR source_file +as the +.IR path1 +argument, the destination path as the +.IR path2 +argument, AT_FDCWD as the +.IR fd1 +and +.IR fd2 +arguments, and AT_SYMLINK_FOLLOW as the +.IR flag +argument. +.P +The +.IR ln +utility shall do nothing more with +.IR source_file +and shall go on to any remaining files. +.RE +.IP " 4." 4 +Actions shall be performed equivalent to the +\fIlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 using +.IR source_file +as the +.IR path1 +argument, and the destination path as the +.IR path2 +argument. +.SH OPTIONS +The +.IR ln +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\fP" 10 +Force existing destination pathnames to be removed to allow the link. +.IP "\fB\(miL\fP" 10 +For each +.IR source_file +operand that names a file of type symbolic link, create a (hard) +link to the file referenced by the symbolic link. +.IP "\fB\(miP\fP" 10 +For each +.IR source_file +operand that names a file of type symbolic link, create a (hard) +link to the symbolic link itself. +.IP "\fB\(mis\fP" 10 +Create symbolic links instead of hard links. If the +.BR \(mis +option is specified, the +.BR \(miL +and +.BR \(miP +options shall be silently ignored. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miL +and +.BR \(miP +shall not be considered an error. The last option specified shall +determine the behavior of the utility (unless the +.BR \(mis +option causes it to be ignored). +.P +If the +.BR \(mis +option is not specified and neither a +.BR \(miL +nor a +.BR \(miP +option is specified, it is implementation-defined which of the +.BR \(miL +and +.BR \(miP +options will be used as the default. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIsource_file\fR" 10 +A pathname of a file to be linked. If the +.BR \(mis +option is specified, no restrictions on the type of file or on its +existence shall be made. If the +.BR \(mis +option is not specified, whether a directory can be linked is +implementation-defined. +.IP "\fItarget_file\fR" 10 +The pathname of the new directory entry to be created. +.IP "\fItarget_dir\fR" 10 +A pathname of an existing directory in which the new directory entries +are created. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ln : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All the specified files were linked successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The CONSEQUENCES OF ERRORS section does not require +.IR ln +.BR \(mif +.IR "a b" +to remove +.IR b +if a subsequent link operation would fail. +.P +Some historic versions of +.IR ln +(including the one specified by the SVID) unlink the destination file, +if it exists, by default. If the mode does not permit writing, these +versions prompt for confirmation before attempting the unlink. In these +versions the +.BR \(mif +option causes +.IR ln +not to attempt to prompt for confirmation. +.P +This allows +.IR ln +to succeed in creating links when the target file already exists, even +if the file itself is not writable (although the directory must be). +Early proposals specified this functionality. +.P +This volume of POSIX.1\(hy2008 does not allow the +.IR ln +utility to unlink existing destination paths by default for the +following reasons: +.IP " *" 4 +The +.IR ln +utility has historically been used to provide locking for shell +applications, a usage that is incompatible with +.IR ln +unlinking the destination path by default. There was no corresponding +technical advantage to adding this functionality. +.IP " *" 4 +This functionality gave +.IR ln +the ability to destroy the link structure of files, which changes the +historical behavior of +.IR ln . +.IP " *" 4 +This functionality is easily replicated with a combination of +.IR rm +and +.IR ln . +.IP " *" 4 +It is not historical practice in many systems; BSD and BSD-derived +systems do not support this behavior. Unfortunately, whichever behavior +is selected can cause scripts written expecting the other behavior to +fail. +.IP " *" 4 +It is preferable that +.IR ln +perform in the same manner as the +\fIlink\fR() +function, which does not permit the target to exist already. +.P +This volume of POSIX.1\(hy2008 retains the +.BR \(mif +option to provide support for shell scripts depending on the SVID +semantics. It seems likely that shell scripts would not be written to +handle prompting by +.IR ln +and would therefore have specified the +.BR \(mif +option. +.P +The +.BR \(mif +option is an undocumented feature of many historical versions of the +.IR ln +utility, allowing linking to directories. These versions require +modification. +.P +Early proposals of this volume of POSIX.1\(hy2008 also required a +.BR \(mii +option, which behaved like the +.BR \(mii +options in +.IR cp +and +.IR mv , +prompting for confirmation before unlinking existing files. This was +not historical practice for the +.IR ln +utility and has been omitted. +.P +The +.BR \(miL +and +.BR \(miP +options allow for implementing both common behaviors of the +.IR ln +utility. Earlier versions of this standard did not specify these options +and required the behavior now described for the +.BR \(miL +option. Many systems by default or as an alternative provided a +non-conforming +.IR ln +utility with the behavior now described for the +.BR \(miP +option. Since applications could not rely on +.IR ln +following links in practice, the +.BR \(miL +and +.BR \(miP +options were added to specify the desired behavior for the application. +.P +The +.BR \(miL +and +.BR \(miP +options are ignored when +.BR \(mis +is specified in order to allow an alias to be created to alter the +default behavior when creating hard links (for example, +.IR alias +.IR ln ='\c +.IR ln +.BR \(miL '). +They serve no purpose when +.BR \(mis +is specified, since +.IR source_file +is then just a string to be used as the contents of the created symbolic +link and need not exist as a file. +.P +The specification ensures that +.IR ln +.BR a +.BR a +with or without the +.BR \(mif +option will not unlink the file +.BR a . +Earlier versions of this standard were unclear in this case. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIfind\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIrm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIlink\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/locale.1p b/man-pages-posix-2013-a/man1p/locale.1p new file mode 100644 index 0000000..8855008 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/locale.1p @@ -0,0 +1,560 @@ +'\" et +.TH LOCALE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +locale +\(em get locale-specific information +.SH SYNOPSIS +.LP +.nf +locale \fB[\fR\(mia|\(mim\fB]\fR +.P +locale \fB[\fR\(mick\fB] \fIname\fR... +.fi +.SH DESCRIPTION +The +.IR locale +utility shall write information about the current locale environment, +or all public locales, to the standard output. For the purposes of +this section, a +.IR "public locale" +is one provided by the implementation that is accessible to the +application. +.P +When +.IR locale +is invoked without any arguments, it shall summarize the current locale +environment for each locale category as determined by the settings of +the environment variables defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +When invoked with operands, it shall write values that have been +assigned to the keywords in the locale categories, as follows: +.IP " *" 4 +Specifying a keyword name shall select the named keyword and the +category containing that keyword. +.IP " *" 4 +Specifying a category name shall select the named category and all +keywords in that category. +.SH OPTIONS +The +.IR locale +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Write information about all available public locales. The available +locales shall include +.BR POSIX , +representing the POSIX locale. The manner in which the implementation +determines what other locales are available is +implementation-defined. +.IP "\fB\(mic\fP" 10 +Write the names of selected locale categories; see the STDOUT section. +The +.BR \(mic +option increases readability when more than one category is selected +(for example, via more than one keyword name or via a category name). +It is valid both with and without the +.BR \(mik +option. +.IP "\fB\(mik\fP" 10 +Write the names and values of selected keywords. The implementation +may omit values for some keywords; see the OPERANDS section. +.IP "\fB\(mim\fP" 10 +Write names of available charmaps; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set". +.SH OPERANDS +The following operand shall be supported: +.IP "\fIname\fR" 10 +The name of a locale category as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +the name of a keyword in a locale category, or the reserved name +.BR charmap . +The named category or keyword shall be selected for output. If a +single +.IR name +represents both a locale category name and a keyword name in the +current locale, the results are unspecified. Otherwise, both category +and keyword names can be specified as +.IR name +operands, in any sequence. It is implementation-defined whether any +keyword values are written for the categories +.IR LC_CTYPE +and +.IR LC_COLLATE . +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR locale : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.P +The application shall ensure that the +.IR LANG , +.IR LC_* , +and +.IR NLSPATH +environment variables specify the current locale environment to be +written out; they shall be used if the +.BR \(mia +option is not specified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR LANG +variable shall be written first using the format: +.sp +.RS 4 +.nf +\fB +"LANG=%s\en", <\fIvalue\fR> +.fi \fR +.P +.RE +.P +If +.IR LANG +is not set or is an empty string, the value is the empty string. +.P +If +.IR locale +is invoked without any options or operands, the names and values of the +.IR LC_* +environment variables described in this volume of POSIX.1\(hy2008 shall be written to the +standard output, one variable per line, and each line using the +following format. Only those variables set in the environment and not +overridden by +.IR LC_ALL +shall be written using this format: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", <\fIvariable_name\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +The names of those +.IR LC_* +variables associated with locale categories defined in this volume of POSIX.1\(hy2008 that are +not set in the environment or are overridden by +.IR LC_ALL +shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"%s=\e"%s\e"\en", <\fIvariable_name\fR>, <\fIimplied value\fR> +.fi \fR +.P +.RE +.P +The <\fIimplied\ value\fP> shall be the name of the locale that has +been selected for that category by the implementation, based on the +values in +.IR LANG +and +.IR LC_ALL , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +The <\fIvalue\fP> and <\fIimplied\ value\fP> shown above shall be +properly quoted for possible later reentry to the shell. The +<\fIvalue\fP> shall not be quoted using double-quotes (so that it can +be distinguished by the user from the <\fIimplied\ value\fP> case, +which always requires double-quotes). +.P +The +.IR LC_ALL +variable shall be written last, using the first format shown above. If +it is not set, it shall be written as: +.sp +.RS 4 +.nf +\fB +"LC_ALL=\en" +.fi \fR +.P +.RE +.P +If any arguments are specified: +.IP " 1." 4 +If the +.BR \(mia +option is specified, the names of all the public locales shall be +written, each in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIlocale\ name\fR> +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +If the +.BR \(mic +option is specified, the names of all selected categories shall be +written, each in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIcategory\ name\fR> +.fi \fR +.P +.RE +.P +If keywords are also selected for writing (see following items), the +category name output shall precede the keyword output for that +category. +.P +If the +.BR \(mic +option is not specified, the names of the categories shall not be +written; only the keywords, as selected by the <\fIname\fP> operand, +shall be written. +.RE +.IP " 3." 4 +If the +.BR \(mik +option is specified, the names and values of selected keywords shall be +written. If a value is non-numeric and is not a compound keyword +value, it shall be written in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s=\e"%s\e"\en", <\fIkeyword name\fR>, <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +If a value is a non-numeric compound keyword value, it shall either be +written in the format: +.sp +.RS 4 +.nf +\fB +"%s=\e"%s\e"\en", <\fIkeyword name\fR>, <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +where the <\fIkeyword value\fR> is a single string of values separated by + +characters, or it shall be written in the format: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", <\fIkeyword name\fR>, <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +where the <\fIkeyword value\fP> is encoded as a set of strings, each +enclosed in double-quotation-marks, separated by + +characters. +.P +If the keyword was +.BR charmap , +the name of the charmap (if any) that was specified via the +.IR localedef +.BR \(mif +option when the locale was created shall be written, with the word +.BR charmap +as <\fIkeyword\ name\fP>. +.P +If a value is numeric, it shall be written in one of the following +formats: +.sp +.RS 4 +.nf +\fB +"%s=%d\en", <\fIkeyword name\fR>, <\fIkeyword value\fR> +.P +"%s=%c%o\en", <\fIkeyword name\fR>, <\fIescape character\fR>, <\fIkeyword value\fR> +.P +"%s=%cx%x\en", <\fIkeyword name\fR>, <\fIescape character\fR>, <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +where the <\fIescape\ character\fP> is that identified by the +.BR escape_char +keyword in the current locale; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3" ", " "Locale Definition". +.P +Compound keyword values (list entries) shall be separated in the output by + +characters. When included in keyword values, the +, +, +double-quote, and any control character shall be preceded (escaped) +with the escape character. +.RE +.IP " 4." 4 +If the +.BR \(mik +option is not specified, selected keyword values shall be written, each +in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +If the keyword was +.BR charmap , +the name of the charmap (if any) that was specified via the +.IR localedef +.BR \(mif +option when the locale was created shall be written. +.RE +.IP " 5." 4 +If the +.BR \(mim +option is specified, then a list of all available charmaps shall be +written, each in the format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIcharmap\fR> +.fi \fR +.P +.RE +.P +where <\fIcharmap\fP> is in a format suitable for use as the +option-argument to the +.IR localedef +.BR \(mif +option. +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All the requested information was found and output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If the +.IR LANG +environment variable is not set or set to an empty value, or one of the +.IR LC_* +environment variables is set to an unrecognized value, the actual +locales assumed (if any) are implementation-defined as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +Implementations are not required to write out the actual values for +keywords in the categories +.IR LC_CTYPE +and +.IR LC_COLLATE ; +however, they must write out the categories (allowing an application to +determine, for example, which character classes are available). +.SH EXAMPLES +In the following examples, the assumption is that locale environment +variables are set as follows: +.sp +.RS 4 +.nf +\fB +LANG=locale_x +LC_COLLATE=locale_y +.fi \fR +.P +.RE +.P +The command +.IR locale +would result in the following output: +.sp +.RS 4 +.nf +\fB +LANG=locale_x +LC_CTYPE="locale_x" +LC_COLLATE=locale_y +LC_TIME="locale_x" +LC_NUMERIC="locale_x" +LC_MONETARY="locale_x" +LC_MESSAGES="locale_x" +LC_ALL= +.fi \fR +.P +.RE +.P +The order of presentation of the categories is not specified by this volume of POSIX.1\(hy2008. +.P +The command: +.sp +.RS 4 +.nf +\fB +LC_ALL=POSIX locale \(mick decimal_point +.fi \fR +.P +.RE +.P +would produce: +.sp +.RS 4 +.nf +\fB +LC_NUMERIC +decimal_point="." +.fi \fR +.P +.RE +.P +The following command shows an application of +.IR locale +to determine whether a user-supplied response is affirmative: +.sp +.RS 4 +.nf +\fB +if printf "%s\en$response" | grep \(miEq "$(locale yesexpr)" +then + affirmative processing goes here +else + non-affirmative processing goes here +fi +.fi \fR +.P +.RE +.SH RATIONALE +The output for categories +.IR LC_CTYPE +and +.IR LC_COLLATE +has been made implementation-defined because there is a questionable +value in having a shell script receive an entire array of characters. +It is also difficult to return a logical collation description, short +of returning a complete +.IR localedef +source. +.P +The +.BR \(mim +option was included to allow applications to query for the existence of +charmaps. +The output is a list of the charmaps (implementation-supplied and +user-supplied, if any) on the system. +.P +The +.BR \(mic +option was included for readability when more than one category is +selected (for example, via more than one keyword name or via a category +name). It is valid both with and without the +.BR \(mik +option. +.P +The +.BR charmap +keyword, which returns the name of the charmap (if any) that was used +when the current locale was created, was included to allow applications +needing the information to retrieve it. +.P +According to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +the standard requires that all supported locales must have the same +encoding for + +and +, +because these two characters are used within the locale-independent +pathname resolution sequence. Therefore, it would be an error if +.IR locale +.BR \(mia +listed both ASCII and EBCDIC-based locales, since those two encodings +do not share the same representation for either + +or +. +Any system that supports both environments would be expected to provide two +POSIX locales, one in either codeset, where only the locales appropriate +to the current environment can be visible at a time. In an XSI-compliant +implementation, the +.IR dd +utility is the only portable means for performing conversions between +the two character sets. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlocaledef\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/localedef.1p b/man-pages-posix-2013-a/man1p/localedef.1p new file mode 100644 index 0000000..e314661 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/localedef.1p @@ -0,0 +1,327 @@ +'\" et +.TH LOCALEDEF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +localedef \(em define locale environment +.SH SYNOPSIS +.LP +.nf +localedef \fB[\fR\(mic\fB] [\fR\(mif \fIcharmap\fB] [\fR\(mii \fIsourcefile\fB] [\fR\(miu \fIcode_set_name\fB] \fIname\fR +.fi +.SH DESCRIPTION +The +.IR localedef +utility shall convert source definitions for locale categories into a +format usable by the functions and utilities whose operational behavior +is determined by the setting of the locale environment variables +defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +It is implementation-defined whether users have the capability to create +new locales, in addition to those supplied by the implementation. If +the symbolic constant POSIX2_LOCALEDEF is defined, the system supports +the creation of new locales. +On XSI-conformant systems, the symbolic constant POSIX2_LOCALEDEF +shall be defined. +.P +The utility shall read source definitions for one or more locale +categories belonging to the same locale from the file named in the +.BR \(mii +option (if specified) or from standard input. +.P +The +.IR name +operand identifies the target locale. The utility shall support the +creation of +.IR public , +or generally accessible locales, as well as +.IR private , +or restricted-access locales. Implementations may restrict the +capability to create or modify public locales to users with +appropriate privileges. +.P +Each category source definition shall be identified by the +corresponding environment variable name and terminated by an +.BR END +.IR category-name +statement. The following categories shall be supported. In addition, +the input may contain source for implementation-defined categories. +.IP "\fILC_CTYPE\fR" 10 +Defines character classification and case conversion. +.IP "\fILC_COLLATE\fR" 10 +.br +Defines collation rules. +.IP "\fILC_MONETARY\fR" 10 +.br +Defines the format and symbols used in formatting of monetary +information. +.IP "\fILC_NUMERIC\fR" 10 +.br +Defines the decimal delimiter, grouping, and grouping symbol for +non-monetary numeric editing. +.IP "\fILC_TIME\fR" 10 +Defines the format and content of date and time information. +.IP "\fILC_MESSAGES\fR" 10 +.br +Defines the format and values of affirmative and negative responses. +.SH OPTIONS +The +.IR localedef +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Create permanent output even if warning messages have been issued. +.IP "\fB\(mif\ \fIcharmap\fR" 10 +Specify the pathname of a file containing a mapping of character +symbols and collating element symbols to actual character encodings. +The format of the +.IR charmap +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File". +The application shall ensure that this option is specified if symbolic +names (other than collating symbols defined in a +.BR collating-symbol +keyword) are used. If the +.BR \(mif +option is not present, an implementation-defined character mapping +shall be used. +.IP "\fB\(mii\ \fIinputfile\fR" 10 +The pathname of a file containing the source definitions. If this +option is not present, source definitions shall be read from standard +input. The format of the +.IR inputfile +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3" ", " "Locale Definition". +.IP "\fB\(miu\ \fIcode_set_name\fR" 10 +.br +Specify the name of a codeset used as the target mapping of character +symbols and collating element symbols whose encoding values are defined +in terms of the ISO/IEC\ 10646\(hy1:\|2000 standard position constant values. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIname\fR" 10 +Identifies the locale; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale" +for a description of the use of this name. If the name contains one +or more + +characters, +.IR name +shall be interpreted as a pathname where the created locale definitions +shall be stored. If +.IR name +does not contain any + +characters, the interpretation of the name is implementation-defined +and the locale shall be public. The ability to create public locales in +this way may be restricted to users with appropriate privileges. (As a +consequence of specifying one +.IR name , +although several categories can be processed in one execution, only +categories belonging to the same locale can be processed.) +.SH STDIN +Unless the +.BR \(mii +option is specified, the standard input shall be a text file containing +one or more locale category source definitions, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3" ", " "Locale Definition". +When lines are continued using the escape character mechanism, +there is no limit to the length of the accumulated continued line. +.SH "INPUT FILES" +The character set mapping file specified as the +.IR charmap +option-argument is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File". +If a locale category source definition contains a +.BR copy +statement, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +and the +.BR copy +statement names a valid, existing locale, then +.IR localedef +shall behave as if the source definition had contained a valid category +source definition for the named locale. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR localedef : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +(This variable has no affect on +.IR localedef ; +the POSIX locale is used for this category.) +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). This variable has +no affect on the processing of +.IR localedef +input data; the POSIX locale is used for this purpose, regardless of +the value of this variable. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The utility shall report all categories successfully processed, in an +unspecified format. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The format of the created output is unspecified. If the +.IR name +operand does not contain a +, +the existence of an output file for the locale is unspecified. +.SH "EXTENDED DESCRIPTION" +When the +.BR \(miu +option is used, the +.IR code_set_name +option-argument shall be interpreted as an implementation-defined +name of a codeset to which the ISO/IEC\ 10646\(hy1:\|2000 standard position constant values shall be +converted via an implementation-defined method. Both the ISO/IEC\ 10646\(hy1:\|2000 standard +position constant values and other formats (decimal, hexadecimal, or +octal) shall be valid as encoding values within the +.IR charmap +file. The codeset represented by the implementation-defined name can +be any codeset that is supported by the implementation. +.P +When conflicts occur between the +.IR charmap +specification of <\fIcode_set_name\fP>, <\fImb_cur_max\fP>, or +<\fImb_cur_min\fP> and the implementation-defined interpretation of +these respective items for the codeset represented by the +.BR \(miu +option-argument +.IR code_set_name , +the result is unspecified. +.P +When conflicts occur between the +.IR charmap +encoding values specified for symbolic names of characters of the +portable character set and the implementation-defined assignment of +character encoding values, the result is unspecified. +.P +If a non-printable character in the +.IR charmap +has a width specified that is not +.BR \(mi1 , +the result will be undefined. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +No errors occurred and the locales were successfully created. +.IP "\01" 6 +Warnings occurred and the locales were successfully created. +.IP "\02" 6 +The locale specification exceeded implementation limits or the coded +character set or sets used were not supported by the implementation, +and no locale was created. +.IP "\03" 6 +The capability to create new locales is not supported by the +implementation. +.IP >3 6 +Warnings or errors occurred and no output was created. +.SH "CONSEQUENCES OF ERRORS" +If an error is detected, no permanent output shall be created. +.P +If warnings occur, permanent output shall be created if the +.BR \(mic +option was specified. The following conditions shall cause warning +messages to be issued: +.IP " *" 4 +If a symbolic name not found in the +.IR charmap +file is used for the descriptions of the +.IR LC_CTYPE +or +.IR LC_COLLATE +categories (for other categories, this shall be an error condition). +.IP " *" 4 +If the number of operands to the +.BR order +keyword exceeds the +{COLL_WEIGHTS_MAX} +limit. +.IP " *" 4 +If optional keywords not supported by the implementation are present in +the source. +.P +Other implementation-defined conditions may also cause warnings. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR charmap +definition is optional, and is contained outside the locale +definition. This allows both completely self-defined source files, and +generic sources (applicable to more than one codeset). To aid +portability, all +.IR charmap +definitions must use the same symbolic names for the portable character +set. As explained in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File", +it is implementation-defined whether or not users or applications can +provide additional character set description files. Therefore, the +.BR \(mif +option might be operable only when an implementation-defined +.IR charmap +is named. +.SH EXAMPLES +None. +.SH RATIONALE +The output produced by the +.IR localedef +utility is implementation-defined. The +.IR name +operand is used to identify the specific locale. (As a consequence, +although several categories can be processed in one execution, only +categories belonging to the same locale can be processed.) +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlocale\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File", +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/logger.1p b/man-pages-posix-2013-a/man1p/logger.1p new file mode 100644 index 0000000..fffb689 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/logger.1p @@ -0,0 +1,163 @@ +'\" et +.TH LOGGER "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +logger +\(em log messages +.SH SYNOPSIS +.LP +.nf +logger \fIstring\fR... +.fi +.SH DESCRIPTION +The +.IR logger +utility saves a message, in an unspecified manner and format, +containing the +.IR string +operands provided by the user. The messages are expected to be +evaluated later by personnel performing system administration tasks. +.P +It is implementation-defined whether messages written in locales +other than the POSIX locale are effective. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIstring\fR" 10 +One of the string arguments whose contents are concatenated together, +in the order specified, separated by single + +characters. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR logger : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. (This means +diagnostics from +.IR logger +to the user or application, not diagnostic messages that the user is +sending to the system administrator.) +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Unspecified. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility allows logging of information for later use by a system +administrator or programmer in determining why non-interactive +utilities have failed. The locations of the saved messages, their +format, and retention period are all unspecified. There is no method +for a conforming application to read messages, once written. +.SH EXAMPLES +A batch application, running non-interactively, tries to read a +configuration file and fails; it may attempt to notify the system +administrator with: +.sp +.RS 4 +.nf +\fB +logger myname: unable to read file foo. [timestamp] +.fi \fR +.P +.RE +.SH RATIONALE +The standard developers believed strongly that some method of alerting +administrators to errors was necessary. The obvious example is a batch +utility, running non-interactively, that is unable to read its +configuration files or that is unable to create or write its results +file. However, the standard developers did not wish to define the +format or delivery mechanisms as they have historically been (and will +probably continue to be) very system-specific, as well as involving +functionality clearly outside the scope of this volume of POSIX.1\(hy2008. +.P +The text with +.IR LC_MESSAGES +about diagnostic messages means diagnostics from +.IR logger +to the user or application, not diagnostic messages that the user is +sending to the system administrator. +.P +Multiple +.IR string +arguments are allowed, similar to +.IR echo , +for ease-of-use. +.P +Like the utilities +.IR mailx +and +.IR lp , +.IR logger +is admittedly difficult to test. This was not deemed sufficient +justification to exclude these utilities from this volume of POSIX.1\(hy2008. It is also +arguable that they are, in fact, testable, but that the tests +themselves are not portable. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlp\fR\^", +.IR "\fImailx\fR\^", +.IR "\fIwrite\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/logname.1p b/man-pages-posix-2013-a/man1p/logname.1p new file mode 100644 index 0000000..c8fc7aa --- /dev/null +++ b/man-pages-posix-2013-a/man1p/logname.1p @@ -0,0 +1,132 @@ +'\" et +.TH LOGNAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +logname +\(em return the user's login name +.SH SYNOPSIS +.LP +.nf +logname +.fi +.SH DESCRIPTION +The +.IR logname +utility shall write the user's login name to standard output. The +login name shall be the string that would be returned by the +\fIgetlogin\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. Under the conditions where the +\fIgetlogin\fR() +function would fail, the +.IR logname +utility shall write a diagnostic message to standard error and exit +with a non-zero exit status. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR logname : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR logname +utility output shall be a single line consisting of the user's login +name: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIlogin name\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR logname +utility explicitly ignores the +.IR LOGNAME +environment variable because environment changes could produce +erroneous results. +.SH EXAMPLES +None. +.SH RATIONALE +The +.BR passwd +file is not listed as required because the implementation may have +other means of mapping login names. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIid\fR\^", +.IR "\fIwho\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetlogin\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/lp.1p b/man-pages-posix-2013-a/man1p/lp.1p new file mode 100644 index 0000000..2aa2969 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/lp.1p @@ -0,0 +1,480 @@ +'\" et +.TH LP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lp +\(em send files to a printer +.SH SYNOPSIS +.LP +.nf +lp \fB[\fR\(mic\fB] [\fR\(mid \fIdest\fB] [\fR\(min \fIcopies\fB] [\fR\(mimsw\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR\(mit \fItitle\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR lp +utility shall copy the input files to an output destination in an +unspecified manner. The default output destination should be to a +hardcopy device, such as a printer or microfilm recorder, that produces +non-volatile, human-readable documents. If such a device is not +available to the application, or if the system provides no such device, +the +.IR lp +utility shall exit with a non-zero exit status. +.P +The actual writing to the output device may occur some time after the +.IR lp +utility successfully exits. During the portion of the writing that +corresponds to each input file, the implementation shall guarantee +exclusive access to the device. +.P +The +.IR lp +utility shall associate a unique +.IR "request ID" +with each request. +.P +Normally, a banner page is produced to separate and identify each print +job. This page may be suppressed by implementation-defined +conditions, such as an operator command or one of the +.BR \(mio +.IR option +values. +.SH OPTIONS +The +.IR lp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Exit only after further access to any of the input files is no longer +required. The application can then safely delete or modify the files +without affecting the output operation. Normally, files are not +copied, but are linked whenever possible. If the +.BR \(mic +option is not given, then the user should be careful not to remove any +of the files before the request has been printed in its entirety. It +should also be noted that in the absence of the +.BR \(mic +option, any changes made to the named files after the request is made +but before it is printed may be reflected in the printed output. +On some implementations, +.BR \(mic +may be on by default. +.IP "\fB\(mid\ \fIdest\fR" 10 +Specify a string that names the destination (\c +.IR dest ). +If +.IR dest +is a printer, the request shall be printed only on that specific +printer. If +.IR dest +is a class of printers, the request shall be printed on the first +available printer that is a member of the class. Under certain +conditions (printer unavailability, file space limitation, and so on), +requests for specific destinations need not be accepted. Destination +names vary between systems. +.RS 10 +.P +If +.BR \(mid +is not specified, and neither the +.IR LPDEST +nor +.IR PRINTER +environment variable is set, an unspecified destination is used. The +.BR \(mid +.IR dest +option shall take precedence over +.IR LPDEST , +which in turn shall take precedence over +.IR PRINTER . +Results are undefined when +.IR dest +contains a value that is not a valid destination name. +.RE +.IP "\fB\(mim\fP" 10 +Send mail (see +.IR "\fImailx\fR\^") +after the files have been printed. By default, no mail is sent upon +normal completion of the print request. +.IP "\fB\(min\ \fIcopies\fR" 10 +Write +.IR copies +number of copies of the files, where +.IR copies +is a positive decimal integer. The methods for producing multiple +copies and for arranging the multiple copies when multiple +.IR file +operands are used are unspecified, except that each file shall be +output as an integral whole, not interleaved with portions of other +files. +.IP "\fB\(mio\ \fIoption\fR" 10 +Specify printer-dependent or class-dependent +.IR option s. +Several such +.IR option s +may be collected by specifying the +.BR \(mio +option more than once. +.IP "\fB\(mis\fP" 10 +Suppress messages from +.IR lp . +.IP "\fB\(mit\ \fItitle\fR" 10 +Write +.IR title +on the banner page of the output. +.IP "\fB\(miw\fP" 10 +Write a message on the user's terminal after the files have been +printed. If the user is not logged in, then mail shall be sent +instead. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be output. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. If a +.IR file +operand is used, but the +.BR \(mic +option is not specified, the process performing the writing to the +output device may have user and group permissions that differ from that +of the process invoking +.IR lp . +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR lp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of date and time strings displayed in +the +.IR lp +banner page, if any. +.IP "\fILPDEST\fP" 10 +Determine the destination. If the +.IR LPDEST +environment variable is not set, the +.IR PRINTER +environment variable shall be used. The +.BR \(mid +.IR dest +option takes precedence over +.IR LPDEST . +Results are undefined when +.BR \(mid +is not specified and +.IR LPDEST +contains a value that is not a valid destination name. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPRINTER\fP" 10 +Determine the output device or destination. If the +.IR LPDEST +and +.IR PRINTER +environment variables are not set, an unspecified output device is +used. The +.BR \(mid +.IR dest +option and the +.IR LPDEST +environment variable shall take precedence over +.IR PRINTER . +Results are undefined when +.BR \(mid +is not specified, +.IR LPDEST +is unset, and +.IR PRINTER +contains a value that is not a valid device or destination name. +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings +displayed in the +.IR lp +banner page, if any. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR lp +utility shall write a +.IR "request ID" +to the standard output, unless +.BR \(mis +is specified. The format of the message is unspecified. The request +ID can be used on systems supporting the historical +.IR cancel +and +.IR lpstat +utilities. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were processed successfully. +.IP >0 6 +No output device was available, or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR pr +and +.IR fold +utilities can be used to achieve reasonable formatting for the +implementation's default page size. +.P +A conforming application can use one of the +.IR file +operands only with the +.BR \(mic +option or if the file is publicly readable and guaranteed to be +available at the time of printing. This is because POSIX.1\(hy2008 gives +the implementation the freedom to queue up the request for printing at +some later time by a different process that might not be able to access +the file. +.SH EXAMPLES +.IP " 1." 4 +To print file +.IR file : +.RS 4 +.sp +.RS 4 +.nf +\fB +lp \(mic \fIfile\fR +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +To print multiple files with headers: +.RS 4 +.sp +.RS 4 +.nf +\fB +pr \fIfile1 file2\fP | lp +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR lp +utility was designed to be a basic version of a utility that is already +available in many historical implementations. The standard developers +considered that it should be implementable simply as: +.sp +.RS 4 +.nf +\fB +cat "$@" > /dev/lp +.fi \fR +.P +.RE +.P +after appropriate processing of options, if that is how the +implementation chose to do it and if exclusive access could be granted +(so that two users did not write to the device simultaneously). +Although in the future the standard developers may add other options to +this utility, it should always be able to execute with no options or +operands and send the standard input to an unspecified output device. +.P +This volume of POSIX.1\(hy2008 makes no representations concerning the format of the printed +output, except that it must be ``human-readable'' and ``non-volatile''. +Thus, writing by default to a disk or tape drive or a display terminal +would not qualify. (Such destinations are not prohibited when +.BR \(mid +.IR dest , +.IR LPDEST , +or +.IR PRINTER +are used, however.) +.P +This volume of POSIX.1\(hy2008 is worded such that a ``print job'' consisting of multiple input +files, possibly in multiple copies, is guaranteed to print so that any +one file is not intermixed with another, but there is no statement that +all the files or copies have to print out together. +.P +The +.BR \(mic +option may imply a spooling operation, but this is not required. The +utility can be implemented to wait until the printer is ready and then +wait until it is finished. Because of that, there is no attempt to +define a queuing mechanism (priorities, classes of output, and so on). +.P +On some historical systems, the request ID reported on the STDOUT +can be used to later cancel or find the status of a request using +utilities not defined in this volume of POSIX.1\(hy2008. +.P +Although the historical System V +.IR lp +and BSD +.IR lpr +utilities have provided similar functionality, they used different +names for the environment variable specifying the destination printer. +Since the name of the utility here is +.IR lp , +.IR LPDEST +(used by the System V +.IR lp +utility) was given precedence over +.IR PRINTER +(used by the BSD +.IR lpr +utility). Since environments of users frequently contain one or the +other environment variable, the +.IR lp +utility is required to recognize both. If this was not done, many +applications would send output to unexpected output devices when users +moved from system to system. +.P +Some have commented that +.IR lp +has far too little functionality to make it worthwhile. Requests have +proposed additional options or operands or both that added +functionality. The requests included: +.IP " *" 4 +Wording +.IR requiring +the output to be ``hardcopy'' +.IP " *" 4 +A requirement for multiple printers +.IP " *" 4 +Options for supporting various page-description languages +.P +Given that a compliant system is not required to even have a printer, +placing further restrictions upon the behavior of the printer is not +useful. Since hardcopy format is so application-dependent, it is +difficult, if not impossible, to select a reasonable subset of +functionality that should be required on all compliant systems. +.P +The term \fIunspecified\fR is used in this section in lieu of +\fIimplementation-defined\fR as most known implementations would not be +able to make definitive statements in their conformance documents; the +existence and usage of printers is very dependent on how the system +administrator configures each individual system. +.P +Since the default destination, device type, queuing mechanisms, and +acceptable forms of input are all unspecified, usage guidelines for +what a conforming application can do are as follows: +.IP " *" 4 +Use the command in a pipeline, or with +.BR \(mic , +so that there are no permission problems and the files can be safely +deleted or modified. +.IP " *" 4 +Limit output to text files of reasonable line lengths and printable +characters and include no device-specific formatting information, such +as a page description language. The meaning of ``reasonable'' in this +context can only be answered as a quality-of-implementation issue, but +it should be apparent from historical usage patterns in the industry +and the locale. The +.IR pr +and +.IR fold +utilities can be used to achieve reasonable formatting for the default +page size of the implementation. +.P +Alternatively, the application can arrange its installation in such a +way that it requires the system administrator or operator to provide +the appropriate information on +.IR lp +options and environment variable values. +.P +At a minimum, having this utility in this volume of POSIX.1\(hy2008 tells the industry that +conforming applications require a means to print output and provides at +least a command name and +.IR LPDEST +routing mechanism that can be used for discussions between vendors, +application developers, and users. The use of ``should'' in the +DESCRIPTION of +.IR lp +clearly shows the intent of the standard developers, even if they +cannot mandate that all systems (such as laptops) have printers. +.P +This volume of POSIX.1\(hy2008 does not specify what the ownership of the process performing the +writing to the output device may be. If +.BR \(mic +is not used, it is unspecified whether the process performing the +writing to the output device has permission to read +.IR file +if there are any restrictions in place on who may read +.IR file +until after it is printed. Also, if +.BR \(mic +is not used, the results of deleting +.IR file +before it is printed are unspecified. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImailx\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ls.1p b/man-pages-posix-2013-a/man1p/ls.1p new file mode 100644 index 0000000..0131cc3 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ls.1p @@ -0,0 +1,1134 @@ +'\" et +.TH LS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ls +\(em list directory contents +.SH SYNOPSIS +.LP +.nf +ls \fB[\fR\(miikqrs\fB] [\fR\(mig\|lno\|\fB] [\fR\(miA|\(mia\fB] [\fR\(miC|\(mim|\(mix|\(mi1\fB]\fR \e + \fB[\fR\(miF|\(mip\fB] [\fR\(miH|\(miL\fB] [\fR\(miR|\(mid\fB] [\fR\(miS|\(mif|\(mit\fB] [\fR\(mic|\(miu\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +For each operand that names a file of a type other than directory or +symbolic link to a directory, +.IR ls +shall write the name of the file as well as any requested, associated +information. For each operand that names a file of type directory, +.IR ls +shall write the names of files contained within the directory as well +as any requested, associated information. Filenames beginning +with a + +(\c +.BR '.' ) +and any associated information shall not be written out unless +explicitly referenced, the +.BR \(miA +or +.BR \(mia +option is supplied, or an implementation-defined condition causes them +to be written. If one or more of the +.BR \(mid , +.BR \(miF , +or +.BR \(mil +options are specified, and neither the +.BR \(miH +nor the +.BR \(miL +option is specified, for each operand that names a file of type +symbolic link to a directory, +.IR ls +shall write the name of the file as well as any requested, associated +information. If none of the +.BR \(mid , +.BR \(miF , +or +.BR \(mil +options are specified, or the +.BR \(miH +or +.BR \(miL +options are specified, for each operand that names a file of type +symbolic link to a directory, +.IR ls +shall write the names of files contained within the directory as well +as any requested, associated information. In each case where the names +of files contained within a directory are written, if the directory +contains any symbolic links then +.IR ls +shall evaluate the file information and file type to be those of +the symbolic link itself, unless the +.BR \(miL +option is specified. +.P +If no operands are specified, +.IR ls +shall behave as if a single operand of dot (\c +.BR '.' ) +had been specified. If more than one operand is specified, +.IR ls +shall write non-directory operands first; it shall sort directory and +non-directory operands separately according to the collating sequence +in the current locale. +.P +The +.IR ls +utility shall detect infinite loops; that is, entering a previously +visited directory that is an ancestor of the last file encountered. +When it detects an infinite loop, +.IR ls +shall write a diagnostic message to standard error and shall either +recover its position in the hierarchy or terminate. +.SH OPTIONS +The +.IR ls +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miA\fP" 10 +Write out all directory entries, including those whose names begin with a + +(\c +.BR '.' ) +but excluding the entries dot and dot-dot (if they exist). +.IP "\fB\(miC\fP" 10 +Write multi-text-column output with entries sorted down the columns, +according to the collating sequence. The number of text columns and the +column separator characters are unspecified, but should be adapted to +the nature of the output device. This option disables long format output. +.IP "\fB\(miF\fP" 10 +Do not follow symbolic links named as operands unless the +.BR \(miH +or +.BR \(miL +options are specified. Write a + +(\c +.BR '/' ) +immediately after each pathname that is a directory, an + +(\c +.BR '*' ) +after each that is executable, a + +(\c +.BR '|' ) +after each that is a FIFO, and an at-sign (\c +.BR '@' ) +after each that is a symbolic link. For other file types, other +symbols may be written. +.IP "\fB\(miH\fP" 10 +Evaluate the file information and file type for symbolic links specified +on the command line to be those of the file referenced by the link, +and not the link itself; however, +.IR ls +shall write the name of the link itself and not the file referenced by +the link. +.IP "\fB\(miL\fP" 10 +Evaluate the file information and file type for all symbolic links +(whether named on the command line or encountered in a file hierarchy) +to be those of the file referenced by the link, and not the link +itself; however, +.IR ls +shall write the name of the link itself and not the file referenced by +the link. When +.BR \(miL +is used with +.BR \(mil , +write the contents of symbolic links in the long format (see the STDOUT +section). +.IP "\fB\(miR\fP" 10 +Recursively list subdirectories encountered. When a symbolic link to a +directory is encountered, the directory shall not be recursively listed +unless the +.BR \(miL +option is specified. +The use of +.BR \(miR +with +.BR \(mid +or +.BR \(mif +produces unspecified results. +.IP "\fB\(miS\fP" 10 +Sort with the primary key being file size (in decreasing order) and the +secondary key being filename in the collating sequence (in increasing +order). +.IP "\fB\(mia\fP" 10 +Write out all directory entries, including those whose names begin with a + +(\c +.BR '.' ). +.IP "\fB\(mic\fP" 10 +Use time of last modification of the file status information (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +instead of last modification of the file itself for sorting (\c +.BR \(mit ) +or writing (\c +.BR \(mil ). +.IP "\fB\(mid\fP" 10 +Do not follow symbolic links named as operands unless the +.BR \(miH +or +.BR \(miL +options are specified. Do not treat directories differently than other +types of files. The use of +.BR \(mid +with +.BR \(miR +or +.BR \(mif +produces unspecified results. +.IP "\fB\(mif\fP" 10 +List the entries in directory operands in the order they appear in the +directory. The behavior for non-directory operands is unspecified. This +option shall turn on +.BR \(mia . +When +.BR \(mif +is specified, any occurrences of the +.BR \(mir , +.BR \(miS , +and +.BR \(mit +options shall be ignored and any occurrences of the +.BR \(miA , +.BR \(mig , +.BR \(mil , +.BR \(min , +.BR \(mio , +and +.BR \(mis +options may be ignored. The use of +.BR \(mif +with +.BR \(miR +or +.BR \(mid +produces unspecified results. +.IP "\fB\(mig\fP" 10 +Turn on the +.BR \(mil +(ell) option, but disable writing the file's owner name or number. +Disable the +.BR \(miC , +.BR \(mim , +and +.BR \(mix +options. +.IP "\fB\(mii\fP" 10 +For each file, write the file's file serial number (see +\fIstat\fR() +in the System Interfaces volume of POSIX.1\(hy2008). +.IP "\fB\(mik\fP" 10 +Set the block size for the +.BR \(mis +option and the per-directory block count written for the +.BR \(mil , +.BR \(min , +.BR \(mis , +.BR \(mig , +and +.BR \(mio +options (see the STDOUT section) to 1\|024 bytes. +.IP "\fB\(mil\fP" 10 +(The letter ell.) Do not follow symbolic links named as operands unless +the +.BR \(miH +or +.BR \(miL +options are specified. Write out in long format (see the STDOUT +section). Disable the +.BR \(miC , +.BR \(mim , +and +.BR \(mix +options. +.IP "\fB\(mim\fP" 10 +Stream output format; list pathnames across the page, separated by a + +character followed by a + +character. Use a + +character as the list terminator and after the separator sequence when +there is not room on a line for the next list entry. This option disables +long format output. +.IP "\fB\(min\fP" 10 +Turn on the +.BR \(mil +(ell) option, but when writing the file's owner or group, write +the file's numeric UID or GID rather than the user or group name, +respectively. Disable the +.BR \(miC , +.BR \(mim , +and +.BR \(mix +options. +.IP "\fB\(mio\fP" 10 +Turn on the +.BR \(mil +(ell) option, but disable writing the file's group name or number. +Disable the +.BR \(miC , +.BR \(mim , +and +.BR \(mix +options. +.IP "\fB\(mip\fP" 10 +Write a + +(\c +.BR '/' ) +after each filename if that file is a directory. +.IP "\fB\(miq\fP" 10 +Force each instance of non-printable filename characters and + +characters to be written as the + +(\c +.BR '?' ) +character. Implementations may provide this option by default if the +output is to a terminal device. +.IP "\fB\(mir\fP" 10 +Reverse the order of the sort to get reverse collating sequence oldest +first, or smallest file size first depending on the other options +given. +.IP "\fB\(mis\fP" 10 +Indicate the total number of file system blocks consumed by each file +displayed. If the +.BR \(mik +option is also specified, the block size shall be 1\|024 bytes; +otherwise, the block size is implementation-defined. +.IP "\fB\(mit\fP" 10 +Sort with the primary key being time modified (most recently modified +first) and the secondary key being filename in the collating sequence. +For a symbolic link, the time used as the sort key is that of the +symbolic link itself, unless +.IR ls +is evaluating its file information to be that of the file referenced +by the link (see the +.BR \(miH +and +.BR \(miL +options). +.IP "\fB\(miu\fP" 10 +Use time of last access (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +instead of last modification of the file for sorting (\c +.BR \(mit ) +or writing (\c +.BR \(mil ). +.IP "\fB\(mix\fP" 10 +The same as +.BR \(miC , +except that the multi-text-column output is produced with entries sorted +across, rather than down, the columns. This option disables long format +output. +.IP "\fB\(mi1\fP" 10 +(The numeric digit one.) Force output to be one entry per line. +This option does not disable long format output. (Long format output is +enabled by +.BR \(mig , +.BR \(mil +(ell), +.BR \(min , +and +.BR \(mio ; +and disabled by +.BR \(miC , +.BR \(mim , +and +.BR \(mix .) +.P +If an option that enables long format output (\c +.BR \(mig , +.BR \(mil +(ell), +.BR \(min , +and +.BR "\\(mio\|\" ) +is given with an option that disables long format output (\c +.BR \(miC , +.BR \(mim , +and +.BR \(mix ), +this shall not be considered an error. The last of these options +specified shall determine whether long format output is written. +.P +If +.BR \(miR , +.BR \(mid , +or +.BR \(mif +are specified, the results of specifying these mutually-exclusive options +are specified by the descriptions of these options above. If more +than one of any of the other options shown in the SYNOPSIS section in +mutually-exclusive sets are given, this shall not be considered an error; +the last option specified in each set shall determine the output. +.P +Note that if +.BR \(mit +is specified, +.BR \(mic +and +.BR \(miu +are not only mutually-exclusive with each other, they are also +mutually-exclusive with +.BR \(miS +when determining sort order. But even if +.BR \(miS +is specified after all occurrences of +.BR \(mic , +.BR \(mit , +and +.BR \(miu , +the last use of +.BR \(mic +or +.BR \(miu +determines the timestamp printed when producing long format output. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be written. If the file specified is not +found, a diagnostic message shall be output on standard error. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.br +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ls : +.IP "\fICOLUMNS\fP" 10 +Determine the user's preferred column position width for writing +multiple text-column output. If this variable contains a string +representing a decimal integer, the +.IR ls +utility shall calculate how many pathname text columns to write (see +.BR \(miC ) +based on the width provided. If +.IR COLUMNS +is not set or invalid, an implementation-defined number of column +positions shall be assumed, based on the implementation's knowledge of +the output device. The column width chosen to write the names of files +in any given directory shall be constant. Filenames shall not be +truncated to fit into the multiple text-column output. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for character collation information in determining +the pathname collation sequence. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to multi-byte +characters in arguments) and which characters are defined as printable +(character class +.BR print ). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents for date and time strings written by +.IR ls . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone for date and time strings written by +.IR ls . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The default format shall be to list one entry per line to standard +output; the exceptions are to terminals or when one of the +.BR \(miC , +.BR \(mim , +or +.BR \(mix +options is specified. If the output is to a terminal, the format is +implementation-defined. +.P +When +.BR \(mim +is specified, the format used for the last element of the list +shall be: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIfilename\fR> +.fi \fR +.P +.RE +.P +The format used for each other element of the list shall be: +.sp +.RS 4 +.nf +\fB +"%s,%s", <\fIfilename\fR>, <\fIseparator\fR> +.fi \fR +.P +.RE +.P +where, if there is not room for the next element of the list to fit +within the current line length, <\fIseparator\fP> is a string containing +an optional + +character and a mandatory + +character; otherwise it is a single + +character. +.P +If the +.BR \(mii +option is specified, the file's file serial number (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +shall be written in the following format before any other output for +the corresponding entry: +.sp +.RS 4 +.nf +\fB +%u ", <\fIfile serial number\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mil +option is specified, the following information shall be written for +files other than character special and block special files: +.sp +.RS 4 +.nf +\fB +"%s %u %s %s %u %s %s\en", <\fIfile mode\fR>, <\fInumber of links\fR>, + <\fIowner name\fR>, <\fIgroup name\fR>, <\fIsize\fR>, <\fIdate and time\fR>, + <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mil +option is specified, the following information shall be written +for character special and block special files: +.sp +.RS 4 +.nf +\fB +"%s %u %s %s %s %s %s\en", <\fIfile mode\fR>, <\fInumber of links\fR>, + <\fIowner name\fR>, <\fIgroup name\fR>, <\fIdevice info\fR>, <\fIdate and time\fR>, + <\fIpathname\fR> +.fi \fR +.P +.RE +.P +In both cases if the file is a symbolic link and the +.BR \(miL +option is also specified, this information shall be for the file +resolved from the symbolic link, except that the <\fIpathname\fP> field +shall contain the pathname of the symbolic link itself. If the file is +a symbolic link and the +.BR \(miL +option is not specified, this information shall be about the link itself +and the <\fIpathname\fP> field shall be of the form: +.sp +.RS 4 +.nf +\fB +"%s \(mi> %s", <\fIpathname of link\fR>, <\fIcontents of link\fR> +.fi \fR +.P +.RE +.P +The +.BR \(min , +.BR \(mig , +and +.BR \(mio +options use the same format as +.BR \(mil , +but with omitted items and their associated + +characters. See the OPTIONS section. +.P +In both the preceding +.BR \(mil +forms, if <\fIowner name\fR> or <\fIgroup name\fR> cannot be +determined, or if +.BR \(min +is given, they shall be replaced with their associated numeric values +using the format +.BR %u . +.P +The <\fIsize\fP> field shall contain the value that would be returned +for the file in the +.IR st_size +field of +.BR "struct stat" +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP"). +Note that for some file types this value is unspecified. +.P +The <\fIdevice\ info\fP> field shall contain implementation-defined +information associated with the device in question. +.P +The <\fIdate\ and\ time\fP> field shall contain the appropriate date +and timestamp of when the file was last modified. In the POSIX locale, +the field shall be the equivalent of the output of the following +.IR date +command: +.sp +.RS 4 +.nf +\fB +date "+%b %e %H:%M" +.fi \fR +.P +.RE +.P +if the file has been modified in the last six months, or: +.sp +.RS 4 +.nf +\fB +date "+%b %e %Y" +.fi \fR +.P +.RE +.P +(where two + +characters are used between +.BR %e +and +.BR %Y ) +if the file has not been modified in the last six months or if the +modification date is in the future, except that, in both cases, the final + +produced by +.IR date +shall not be included and the output shall be as if the +.IR date +command were executed at the time of the last modification date of the +file rather than the current time. When the +.IR LC_TIME +locale category is not set to the POSIX locale, a different format and +order of presentation of this field may be used. +.P +If the pathname was specified as a +.IR file +operand, it shall be written as specified. +.P +The file mode written under the +.BR \(mil , +.BR \(min , +.BR \(mig , +and +.BR \(mio +options shall consist of the following format: +.sp +.RS 4 +.nf +\fB +"%c%s%s%s%s", <\fIentry type\fR>, <\fIowner permissions\fR>, + <\fIgroup permissions\fR>, <\fIother permissions\fR>, + <\fIoptional alternate access method flag\fR> +.fi \fR +.P +.RE +.P +The <\fIoptional\ alternate\ access\ method\ flag\fP> shall be the +empty string if there is no alternate or additional access control +method associated with the file; otherwise, it shall be a string +containing a single printable character that is not a +. +.P +The <\fIentry\ type\fP> character shall describe the type of file, as +follows: +.IP "\fRd\fP" 8 +Directory. +.IP "\fRb\fP" 8 +Block special file. +.IP "\fRc\fP" 8 +Character special file. +.IP "\fRl\fP\ (ell)" 8 +Symbolic link. +.IP "\fRp\fP" 8 +FIFO. +.IP "\fR\(mi\fP" 8 +Regular file. +.P +Implementations may add other characters to this list to represent +other implementation-defined file types. +.P +The next three fields shall be three characters each: +.IP "<\fIowner permissions\fP>" 6 +.br +Permissions for the file owner class (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions"). +.IP "<\fIgroup permissions\fP>" 6 +.br +Permissions for the file group class. +.IP "<\fIother permissions\fP>" 6 +.br +Permissions for the file other class. +.P +Each field shall have three character positions: +.IP " 1." 4 +If +.BR 'r' , +the file is readable; if +.BR '\(mi' , +the file is not readable. +.IP " 2." 4 +If +.BR 'w' , +the file is writable; if +.BR '\(mi' , +the file is not writable. +.IP " 3." 4 +The first of the following that applies: +.RS 4 +.IP "\fRS\fR" 6 +If in <\fIowner\ permissions\fP>, the file is not executable and +set-user-ID mode is set. If in <\fIgroup\ permissions\fP>, the file is +not executable and set-group-ID mode is set. +.IP "\fRs\fR" 6 +If in <\fIowner\ permissions\fP>, the file is executable and +set-user-ID mode is set. If in <\fIgroup\ permissions\fP>, the file is +executable and set-group-ID mode is set. +.IP "\fRT\fR" 6 +If in <\fIother\ permissions\fP> and the file is a directory, search +permission is not granted to others, and the restricted deletion flag +is set. +.IP "\fRt\fR" 6 +If in <\fIother\ permissions\fP> and the file is a directory, search +permission is granted to others, and the restricted deletion flag +is set. +.IP "\fRx\fR" 6 +The file is executable or the directory is searchable. +.IP "\fR\(mi\fR" 6 +None of the attributes of +.BR 'S' , +.BR 's' , +.BR 'T' , +.BR 't' , +or +.BR 'x' +applies. +.P +Implementations may add other characters to this list for the third +character position. Such additions shall, however, be written in +lowercase if the file is executable or searchable, and in uppercase if +it is not. +.RE +.P +If any of the +.BR \(mil , +.BR \(min , +.BR \(mis , +.BR \(mig , +or +.BR \(mio +options is specified, each list of files within the directory shall be +preceded by a status line indicating the number of file system blocks +occupied by files in the directory in 512-byte units if the +.BR \(mik +option is not specified, or 1\|024-byte units if the +.BR \(mik +option is specified, rounded up to the next integral number of units, +if necessary. In the POSIX locale, the format shall be: +.sp +.RS 4 +.nf +\fB +"total %u\en", <\fInumber of units in the directory\fR> +.fi \fR +.P +.RE +.P +If more than one directory, or a combination of non-directory files and +directories are written, either as a result of specifying multiple +operands, or the +.BR \(miR +option, each list of files within a directory shall be preceded by: +.sp +.RS 4 +.nf +\fB +"\en%s:\en", <\fIdirectory name\fR> +.fi \fR +.P +.RE +.P +If this string is the first thing to be written, the first + +shall not be written. This output shall precede the number of units in +the directory. +.P +If the +.BR \(mis +option is given, each file shall be written with the number of blocks +used by the file. Along with +.BR \(miC , +.BR \(mi1 , +.BR \(mim , +or +.BR \(mix , +the number and a + +shall precede the filename; with +.BR \(mil , +.BR \(min , +.BR \(mig , +or +.BR \(mio , +they shall precede each line describing a file. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Many implementations use the + +(\c +.BR '=' ) +to denote sockets bound to the file system for the +.BR \(miF +option. Similarly, many historical implementations use the +.BR 's' +character to denote sockets as the entry type characters for the +.BR \(mil +option. +.P +It is difficult for an application to use every part of the file modes +field of +.IR ls +.BR \(mil +in a portable manner. Certain file types and executable bits are not +guaranteed to be exactly as shown, as implementations may have +extensions. Applications can use this field to pass directly to a user +printout or prompt, but actions based on its contents should generally +be deferred, instead, to the +.IR test +utility. +.P +The output of +.IR ls +(with the +.BR \(mil +and related options) contains information that logically could be used +by utilities such as +.IR chmod +and +.IR touch +to restore files to a known state. However, this information is +presented in a format that cannot be used directly by those utilities +or be easily translated into a format that can be used. A character +has been added to the end of the permissions string so that +applications at least have an indication that they may be working in an +area they do not understand instead of assuming that they can translate +the permissions string into something that can be used. Future versions +or related documents may define one or more specific characters to be +used based on different standard additional or alternative access +control mechanisms. +.P +As with many of the utilities that deal with filenames, the output of +.IR ls +for multiple files or in one of the long listing formats must be used +carefully on systems where filenames can contain embedded white +space. Systems and system administrators should institute policies and +user training to limit the use of such filenames. +.P +The number of disk blocks occupied by the file that it reports varies +depending on underlying file system type, block size units reported, +and the method of calculating the number of blocks. On some file +system types, the number is the actual number of blocks occupied by the +file (counting indirect blocks and ignoring holes in the file); on +others it is calculated based on the file size (usually making an +allowance for indirect blocks, but ignoring holes). +.SH EXAMPLES +An example of a small directory tree being fully listed with +.IR ls +.BR "\(milaRF\ a" +in the POSIX locale: +.sp +.RS 4 +.nf +\fB +total 11 +drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ./ +drwxrwxrwx 4 fox prog 3264 Jul 4 12:09 ../ +drwxr-xr-x 2 fox prog 48 Jul 4 12:07 b/ +-rwxr--r-- 1 fox prog 572 Jul 4 12:07 foo* +.P +a/b: +total 4 +drwxr-xr-x 2 fox prog 48 Jul 4 12:07 ./ +drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ../ +-rw-r--r-- 1 fox prog 700 Jul 4 12:07 bar +.fi \fR +.P +.RE +.SH RATIONALE +Some historical implementations of the +.IR ls +utility show all entries in a directory except dot and dot-dot when a +superuser invokes +.IR ls +without specifying the +.BR \(mia +option. When ``normal'' users invoke +.IR ls +without specifying +.BR \(mia , +they should not see information about any files with names beginning +with a + +unless they were named as +.IR file +operands. +.P +Implementations are expected to traverse arbitrary depths when +processing the +.BR \(miR +option. The only limitation on depth should be based on running out of +physical storage for keeping track of untraversed directories. +.P +The +.BR \(mi1 +(one) option was historically found in BSD and BSD-derived +implementations only. It is required in this volume of POSIX.1\(hy2008 so that conforming +applications might ensure that output is one entry per line, even if +the output is to a terminal. +.P +The +.BR \(miS +option was added in Issue 7, but had been provided by several +implementations for many years. The description given in the +standard documents historic practice, but does not match much of the +documentation that described its behavior. Historical documentation +typically described it as something like: +.IP "\fB\(miS\fP" 10 +Sort by size (largest size first) instead of by name. Special character +devices (listed last) are sorted by name. +.P +even though the file type was never considered when sorting the output. +Character special files do typically sort close to the end of the list +because their file size on most implementations is zero. But they are +sorted alphabetically with any other files that happen to have the same +file size (zero), not sorted separately and added to the end. +.P +This volume of POSIX.1\(hy2008 is frequently silent about what happens when mutually-exclusive +options are specified. Except for +.BR \(miR , +.BR \(mid , +and +.BR \(mif , +the +.IR ls +utility is required to accept multiple options from each +mutually-exclusive option set without treating them as errors and to use +the behavior specified by the last option given in each mutually-exclusive +set. Since +.IR ls +is one of the most aliased commands, it is important that the +implementation perform intuitively. For example, if the alias were: +.sp +.RS 4 +.nf +\fB +alias ls="ls \(miC" +.fi \fR +.P +.RE +.P +and the user typed +.IR ls +.BR \(mi1 +(one), single-text-column output should result, not an error. +.P +The +.BR \(mig , +.BR \(mil +(ell), +.BR \(min , +and +.BR \(mio +options are not mutually-exclusive options. They all enable long format +output. They work together to determine whether the file's owner is +written (no if +.BR \(mig +is present), file's group is written (no if +.BR \(mio +is present), and if the file's group or owner is written whether it is +written as the name (default) or a string representation of the UID or +GID number (if +.BR \(min +is present). The +.BR \(miC , +.BR \(mim , +.BR \(mix , +and +.BR \(mi1 +(one) are mutually-exclusive options and the first three of these disable +long format output. The +.BR \(mi1 +(one) option does not directly change whether or not long format output +is enabled, but by overriding +.BR \(miC , +.BR \(mim , +and +.BR \(mix , +it can re-enable long format output that had been disabled by one of +these options. +.P +Earlier versions of this standard did not describe the BSD +.BR \(miA +option (like +.BR \(mia , +but dot and dot-dot are not written out). It has been added due to +widespread implementation. +.P +Implementations may make +.BR \(miq +the default for terminals to prevent trojan horse attacks on terminals +with special escape sequences. +This is not required because: +.IP " *" 4 +Some control characters may be useful on some terminals; for example, a +system might write them as +.BR \(dq\e001\(dq +or +.BR \(dq^A\(dq . +.IP " *" 4 +Special behavior for terminals is not relevant to applications +portability. +.P +An early proposal specified that the +<\fIoptional\ alternate\ access\ method\ flag\fR> had to be +.BR '\(pl' +if there was an alternate access method used on the file or + +if there was not. This was changed to be + +if there is not and a single printable character if there is. This was +done for three reasons: +.IP " 1." 4 +There are historical implementations using characters other than +.BR '\(pl' . +.IP " 2." 4 +There are implementations that vary this character used in that +position to distinguish between various alternate access methods in +use. +.IP " 3." 4 +The standard developers did not want to preclude future specifications +that might need a way to specify more than one alternate access +method. +.P +Nonetheless, implementations providing a single alternate access method +are encouraged to use +.BR '\(pl' . +.P +Earlier versions of this standard did not have the +.BR \(mik +option, which meant that the +.BR \(mis +option could not be used portably as its block size was +implementation-defined, and the units used to specify the +number of blocks occupied by files in a directory in an +.IR ls +.BR \(mil +listing were fixed as 512-byte units. The +.BR \(mik +option has been added to provide a way for the +.BR \(mis +option to be used portably, and for consistency it also changes the +aforementioned units from 512-byte to 1\|024-byte. +.P +The <\fIdate\ and\ time\fP> field in the +.BR \(mil +format is specified only for the POSIX locale. As noted, the format can +be different in other locales. No mechanism for defining this is +present in this volume of POSIX.1\(hy2008, as the appropriate vehicle is a messaging system; +that is, the format should be specified as a ``message''. +.SH "FUTURE DIRECTIONS" +Allowing +.BR \(mif +to ignore the +.BR \(miA , +.BR \(mig , +.BR \(mil , +.BR \(min , +.BR \(mio , +and +.BR \(mis +options may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfstatat\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/m4.1p b/man-pages-posix-2013-a/man1p/m4.1p new file mode 100644 index 0000000..3e533cf --- /dev/null +++ b/man-pages-posix-2013-a/man1p/m4.1p @@ -0,0 +1,841 @@ +'\" et +.TH M4 "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +m4 \(em macro processor +.SH SYNOPSIS +.LP +.nf +m4 \fB[\fR\(mis\fB] [\fR\(miD \fIname\fB[\fR=\fIval\fB]]\fR...\fB [\fR\(miU \fIname\fB]\fR... \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR m4 +utility is a macro processor that shall read one or more text files, +process them according to their included macro statements, and write +the results to standard output. +.SH OPTIONS +The +.IR m4 +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of the +.BR \(miD +and +.BR \(miU +options shall be significant, and options can be interspersed with +operands. +.P +The following options shall be supported: +.IP "\fB\(mis\fP" 10 +Enable line synchronization output for the +.IR c99 +preprocessor phase (that is, +.BR #line +directives). +.IP "\fB\(miD\ \fIname\fB[\fR=\fIval\fB]\fR" 10 +.br +Define +.IR name +to +.IR val +or to null if =\c +.IR val +is omitted. +.IP "\fB\(miU\ \fIname\fR" 10 +Undefine +.IR name . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to be processed. If no +.IR file +is given, or if it is +.BR '\(mi' , +the standard input shall be read. +.SH STDIN +The standard input shall be a text file that is used if no +.IR file +operand is given, or if it is +.BR '\(mi' . +.SH "INPUT FILES" +The input file named by the +.IR file +operand shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR m4 : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be the same as the input files, after being +processed for macro expansion. +.SH STDERR +The standard error shall be used to display strings with the +.BR errprint +macro, macro tracing enabled by the +.BR traceon +macro, the defined text for macros written by the +.BR dumpdef +macro, or for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The +.IR m4 +utility shall compare each token from the input against the set of +built-in and user-defined macros. If the token matches the name of a +macro, then the token shall be replaced by the macro's defining text, if +any, and rescanned for matching macro names. Once no portion of the +token matches the name of a macro, it shall be written to standard +output. Macros may have arguments, in which case the arguments shall +be substituted into the defining text before it is rescanned. +.P +Macro calls have the form: +.sp +.RS 4 +.nf +\fB +\fIname\fR(\fIarg1\fR, \fIarg2\fR, ..., \fIargn\fR) +.fi \fR +.P +.RE +.P +Macro names shall consist of letters, digits, and underscores, where +the first character is not a digit. Tokens not of this form shall not +be treated as macros. +.P +The application shall ensure that the + +immediately follows the name of the macro. If a token matching the name +of a macro is not followed by a +, +it is handled as a use of that macro without arguments. +.P +If a macro name is followed by a +, +its arguments are the +-separated +tokens between the + +and the matching +. +Unquoted white-space characters preceding each argument shall be +ignored. All other characters, including trailing white-space characters, +are retained. + +characters enclosed between + +and + +characters do not delimit arguments. +.P +Arguments are positionally defined and referenced. The string +.BR \(dq$1\(dq +in the defining text shall be replaced by the first argument. Systems +shall support at least nine arguments; only the first nine can be +referenced, using the strings +.BR \(dq$1\(dq +to +.BR \(dq$9\(dq , +inclusive. The string +.BR \(dq$0\(dq +is replaced with the name of the macro. The string +.BR \(dq$#\(dq +is replaced by the number of arguments as a string. The string +.BR \(dq$*\(dq +is replaced by a list of all of the arguments, separated by + +characters. The string +.BR \(dq$@\(dq +is replaced by a list of all of the arguments separated by + +characters, and each argument is quoted using the current left and right +quoting strings. The string +.BR \(dq${\(dq +produces unspecified behavior. +.P +If fewer arguments are supplied than are in the macro definition, the +omitted arguments are taken to be null. It is not an error if more +arguments are supplied than are in the macro definition. +.P +No special meaning is given to any characters enclosed between matching +left and right quoting strings, but the quoting strings are themselves +discarded. By default, the left quoting string consists of a grave accent +(backquote) and the right quoting string consists of an acute accent +(single-quote); see also the +.BR changequote +macro. +.P +Comments are written but not scanned for matching macro names; by +default, the begin-comment string consists of the + +character and the end-comment string consists of a +. +See also the +.BR changecom +and +.BR dnl +macros. +.P +The +.IR m4 +utility shall make available the following built-in macros. They can be +redefined, but once this is done the original meaning is lost. Their +values shall be null unless otherwise stated. In the descriptions +below, the term +.IR "defining text" +refers to the value of the macro: the second argument to the +.BR define +macro, among other things. Except for the first argument to the +.BR eval +macro, all numeric arguments to built-in macros shall be interpreted as +decimal values. The string values produced as the defining text of the +.BR decr , +.BR divnum , +.BR incr , +.BR index , +.BR len , +and +.BR sysval +built-in macros shall be in the form of a decimal-constant as defined +in the C language. +.IP "\fBchangecom\fR" 10 +The +.BR changecom +macro shall set the begin-comment and end-comment strings. With no +arguments, the comment mechanism shall be disabled. With a single non-null +argument, that argument shall become the begin-comment and the + +shall become the end-comment string. With two non-null arguments, +the first argument shall become the begin-comment string and the second +argument shall become the end-comment string. The behavior is unspecified +if either argument is provided but null. Systems shall support comment +strings of at least five characters. +.IP "\fBchangequote\fR" 10 +The +.BR changequote +macro shall set the begin-quote and end-quote strings. With no +arguments, the quote strings shall be set to the default values (that +is, \fR`\|'\fP). The behavior is unspecified if there is a single argument +or either argument is null. With two non-null arguments, the first +argument shall become the begin-quote string and the second argument +shall become the end-quote string. Systems shall support quote strings +of at least five characters. +.IP "\fBdecr\fR" 10 +The defining text of the +.BR decr +macro shall be its first argument decremented by 1. It shall be an +error to specify an argument containing any non-numeric characters. +The behavior is unspecified if +.BR decr +is not immediately followed by a +. +.IP "\fBdefine\fR" 10 +The second argument shall become the defining text of the macro +whose name is the first argument. It is unspecified whether the +.BR define +macro deletes all prior definitions of the macro named by its first +argument or preserves all but the current definition of the macro. +The behavior is unspecified if +.BR define +is not immediately followed by a +. +.IP "\fBdefn\fR" 10 +The defining text of the +.BR defn +macro shall be the quoted definition (using the current quoting +strings) of its arguments. The behavior is unspecified if +.BR defn +is not immediately followed by a +. +.IP "\fBdivert\fR" 10 +The +.IR m4 +utility maintains nine temporary buffers, numbered 1 to 9, inclusive. +When the last of the input has been processed, any output that has been +placed in these buffers shall be written to standard output in +buffer-numerical order. The +.BR divert +macro shall divert future output to the buffer specified by its +argument. Specifying no argument or an argument of 0 shall resume the +normal output process. Output diverted to a stream with a negative +number shall be discarded. Behavior is implementation-defined if +a stream number larger than 9 is specified. It shall be an error to +specify an argument containing any non-numeric characters. +.IP "\fBdivnum\fR" 10 +The defining text of the +.BR divnum +macro shall be the number of the current output stream as a string. +.IP "\fBdnl\fR" 10 +The +.BR dnl +macro shall cause +.IR m4 +to discard all input characters up to and including the next +. +.IP "\fBdumpdef\fR" 10 +The +.BR dumpdef +macro shall write the defined text to standard error for each of the +macros specified as arguments, or, if no arguments are specified, for +all macros. +.IP "\fBerrprint\fR" 10 +The +.BR errprint +macro shall write its arguments to standard error. The behavior +is unspecified if +.BR errprint +is not immediately followed by a +. +.IP "\fBeval\fR" 10 +The +.BR eval +macro shall evaluate its first argument as an arithmetic expression, +using signed integer arithmetic with at least 32-bit precision. At least +the following C-language operators shall be supported, with precedence, +associativity, and behavior as described in +.IR "Section 1.1.2.1" ", " "Arithmetic Precision and Operations": +.RS 10 +.sp +.RS 4 +.nf +\fB +() +unary + +unary \(mi +\&~ +.P +\&! +binary * +/ +% +binary + +binary \(mi +<< +>> +< +<= +> +>= +=\|= +!= +binary & +\&^ +| +&& +|| +.fi \fR +.P +.RE +.P +Systems shall support octal and hexadecimal numbers as in the ISO\ C standard. +The second argument, if specified, shall set the radix for the result; +if the argument is blank or unspecified, the default is 10. Behavior is +unspecified if the radix falls outside the range 2 to 36, inclusive. The +third argument, if specified, sets the minimum number of digits in the +result. Behavior is unspecified if the third argument is less than +zero. It shall be an error to specify the second or third argument +containing any non-numeric characters. The behavior is unspecified if +.BR eval +is not immediately followed by a +. +.RE +.IP "\fBifdef\fR" 10 +If the first argument to the +.BR ifdef +macro is defined, the defining text shall be the second argument. +Otherwise, the defining text shall be the third argument, if specified, +or the null string, if not. The behavior is unspecified if +.BR ifdef +is not immediately followed by a +. +.IP "\fBifelse\fR" 10 +The +.BR ifelse +macro takes three or more arguments. If the first two arguments compare +as equal strings (after macro expansion of both arguments), the +defining text shall be the third argument. If the first two arguments +do not compare as equal strings and there are three arguments, the +defining text shall be null. If the first two arguments do not compare +as equal strings and there are four or five arguments, the defining +text shall be the fourth argument. If the first two arguments do not +compare as equal strings and there are six or more arguments, the first +three arguments shall be discarded and processing shall restart with +the remaining arguments. The behavior is unspecified if +.BR ifelse +is not immediately followed by a +. +.IP "\fBinclude\fR" 10 +The defining text for the +.BR include +macro shall be the contents of the file named by the first argument. It +shall be an error if the file cannot be read. The behavior is unspecified if +.BR include +is not immediately followed by a +. +.IP "\fBincr\fR" 10 +The defining text of the +.BR incr +macro shall be its first argument incremented by 1. It shall be an +error to specify an argument containing any non-numeric characters. +The behavior is unspecified if +.BR incr +is not immediately followed by a +. +.IP "\fBindex\fR" 10 +The defining text of the +.BR index +macro shall be the first character position (as a string) in the first +argument where a string matching the second argument begins (zero +origin), or \(mi1 if the second argument does not occur. +The behavior is unspecified if +.BR index +is not immediately followed by a +. +.IP "\fBlen\fR" 10 +The defining text of the +.BR len +macro shall be the length (as a string) of the first argument. +The behavior is unspecified if +.BR len +is not immediately followed by a +. +.IP "\fBm4exit\fR" 10 +Exit from the +.IR m4 +utility. If the first argument is specified, it is the exit code. The +default is zero. It shall be an error to specify an argument containing +any non-numeric characters. +.IP "\fBm4wrap\fR" 10 +The first argument shall be processed when EOF is reached. If the +.BR m4wrap +macro is used multiple times, the arguments specified shall be +processed in the order in which the +.BR m4wrap +macros were processed. The behavior is unspecified if +.BR m4wrap +is not immediately followed by a +. +.IP "\fBmaketemp\fR" 10 +The defining text shall be the first argument, with any trailing +.BR 'X' +characters replaced with the current process ID as a string. +The behavior is unspecified if +.BR maketemp +is not immediately followed by a +. +.IP "\fBmkstemp\fR" 10 +The first argument shall be taken as a template for creating an +empty file, with trailing +.BR 'X' +characters replaced with characters from the portable filename +character set. The behavior is unspecified if the first argument +does not end in at least six +.BR 'X' +characters. If a temporary file is successfully created, then the +defining text of the macro shall be the name of the new file. +The user ID of the file shall be set to the effective user ID +of the process. The group ID of the file shall be set to the group ID +of the file's parent directory or to the effective group ID of the +process. The file access permission bits are set such that +only the owner can both read and write the file, regardless of +the current +.IR umask +of the process. If a file could not be created, the defining text +of the macro shall be the empty string. The behavior is unspecified if +.BR mkstemp +is not immediately followed by a +. +.IP "\fBpopdef\fR" 10 +The +.BR popdef +macro shall delete the current definition of its arguments, replacing +that definition with the previous one. If there is no previous +definition, the macro is undefined. The behavior is unspecified if +.BR popdef +is not immediately followed by a +. +.IP "\fBpushdef\fR" 10 +The +.BR pushdef +macro shall be equivalent to the +.BR define +macro with the exception that it shall preserve any current definition +for future retrieval using the +.BR popdef +macro. The behavior is unspecified if +.BR pushdef +is not immediately followed by a +. +.IP "\fBshift\fR" 10 +The defining text for the +.BR shift +macro shall be a comma-separated list of its arguments except the first +one. Each argument shall be quoted using the current quoting strings. +The behavior is unspecified if +.BR shift +is not immediately followed by a +. +.IP "\fBsinclude\fR" 10 +The +.BR sinclude +macro shall be equivalent to the +.BR include +macro, except that it shall not be an error if the file is inaccessible. +The behavior is unspecified if +.BR sinclude +is not immediately followed by a +. +.IP "\fBsubstr\fR" 10 +The defining text for the +.BR substr +macro shall be the substring of the first argument beginning at the +zero-offset character position specified by the second argument. The +third argument, if specified, shall be the number of characters to +select; if not specified, the characters from the starting point to the +end of the first argument shall become the defining text. It shall not +be an error to specify a starting point beyond the end of the first +argument and the defining text shall be null. It shall be an error to +specify an argument containing any non-numeric characters. +The behavior is unspecified if +.BR substr +is not immediately followed by a +. +.IP "\fBsyscmd\fR" 10 +The +.BR syscmd +macro shall interpret its first argument as a shell command line. The +defining text shall be the string result of that command. The string +result shall not be rescanned for macros while setting the defining +text. No output redirection shall be performed by the +.IR m4 +utility. The exit status value from the command can be retrieved using +the +.BR sysval +macro. The behavior is unspecified if +.BR syscmd +is not immediately followed by a +. +.IP "\fBsysval\fR" 10 +The defining text of the +.BR sysval +macro shall be the exit value of the utility last invoked by the +.BR syscmd +macro (as a string). +.IP "\fBtraceon\fR" 10 +The +.BR traceon +macro shall enable tracing for the macros specified as arguments, or, +if no arguments are specified, for all macros. The trace output shall +be written to standard error in an unspecified format. +.IP "\fBtraceoff\fR" 10 +The +.BR traceoff +macro shall disable tracing for the macros specified as arguments, or, +if no arguments are specified, for all macros. +.IP "\fBtranslit\fR" 10 +The defining text of the +.BR translit +macro shall be the first argument with every character that occurs in +the second argument replaced with the corresponding character from the +third argument. If no replacement character is specified for some +source character because the second argument is longer than the third +argument, that character shall be deleted from the first argument in +.BR translit 's +defining text. The behavior is unspecified if the +.BR '\(mi' +character appears within the second or third argument anywhere besides +the first or last character. The behavior is unspecified if the same +character appears more than once in the second argument. The behavior +is unspecified if +.BR translit +is not immediately followed by a +. +.IP "\fBundefine\fR" 10 +The +.BR undefine +macro shall delete all definitions (including those preserved using the +.BR pushdef +macro) of the macros named by its arguments. The behavior is unspecified if +.BR undefine +is not immediately followed by a +. +.IP "\fBundivert\fR" 10 +The +.BR undivert +macro shall cause immediate output of any text in temporary buffers +named as arguments, or all temporary buffers if no arguments are +specified. Buffers can be undiverted into other temporary buffers. +Undiverting shall discard the contents of the temporary buffer. The +behavior is unspecified if an argument contains any non-numeric +characters. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred +.P +If the +.BR m4exit +macro is used, the exit value can be specified by the input file. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR defn +macro is useful for renaming macros, especially built-ins. +.P +Since +.BR eval +defers to the ISO\ C standard, some operations have undefined behavior. In some +implementations, division or remainder by zero cause a fatal signal, +even if the division occurs on the short-circuited branch of +.BR \(dq&&\(dq +or +.BR \(dq||\(dq . +Any operation that overflows in signed arithmetic produces undefined +behavior. Likewise, using the +.BR shift +operators with a shift amount that is not positive and smaller +than the precision is undefined, as is shifting a negative number to +the right. Historically, not all implementations obeyed C-language +precedence rules: +.BR '~' +and +.BR '!' +were lower than +.BR '==' ; +.BR '==' +and +.BR '!=' +were not lower than +.BR '<' ; +and +.BR '|' +was not lower than +.BR '^' ; +the liberal use of +.BR \(dq()\(dq +can force the desired precedence even with these non-compliant +implementations. Furthermore, some traditional implementations treated +.BR '^' +as an exponentiation operator, although most implementations now use +.BR \(dq**\(dq +as an extension for this purpose. +.P +When a macro has been multiply defined via the +.BR pushdef +macro, it is unspecified whether the +.BR define +macro will alter only the most recent definition (as though by +.BR popdef +and +.BR pushdef ), +or replace the entire stack of definitions with a single definition +(as though by +.BR undefine +and +.BR pushdef ). +An application desiring particular behavior for the +.BR define +macro in this case can redefine it accordingly. +.P +Applications should use the +.BR mkstemp +macro instead of the obsolescent +.BR maketemp +macro for creating temporary files. +.SH EXAMPLES +If the file +.BR m4src +contains the lines: +.sp +.RS 4 +.nf +\fB +The value of `VER' is "VER". +ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.) +ifelse(VER, 1, ``VER'' is `VER'.) +ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.) +end +.fi \fR +.P +.RE +.P +then the command +.sp +.RS 4 +.nf +\fB +m4 m4src +.fi \fR +.P +.RE +.P +or the command: +.sp +.RS 4 +.nf +\fB +m4 \(miU VER m4src +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +The value of VER is "VER". +VER is not defined. +.P +VER is not 2. +end +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +m4 \(miD VER m4src +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +The value of VER is "". +VER is defined to be . +.P +VER is not 2. +end +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +m4 \(miD VER=1 m4src +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +The value of VER is "1". +VER is defined to be 1. +VER is 1. +VER is not 2. +end +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +m4 \(miD VER=2 m4src +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +The value of VER is "2". +VER is defined to be 2. +.P +VER is 2. +end +.fi \fR +.P +.RE +.SH RATIONALE +Historic System V-based behavior treated +.BR \(dq${\(dq +in a macro definition as two literal characters. However, this sequence +is left unspecified so that implementations may offer extensions +such as +.BR \(dq${11}\(dq +meaning the eleventh positional parameter. Macros can still be defined with +appropriate uses of nested quoting to result in a literal +.BR \(dq${\(dq +in the output after rescanning removes the nested quotes. +.P +In the +.BR translit +built-in, historic System V-based behavior treated +.BR '\(mi' +as a literal; GNU behavior treats it as a range. This version of +the standard allows either behavior. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/mailx.1p b/man-pages-posix-2013-a/man1p/mailx.1p new file mode 100644 index 0000000..8657e30 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/mailx.1p @@ -0,0 +1,3090 @@ +'\" et +.TH MAILX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mailx +\(em process messages +.SH SYNOPSIS +.SS "Send Mode" +.sp +.RS 4 +.nf +\fB +mailx \fB[\fR\(mis \fIsubject\fB]\fI address\fR... +.fi \fR +.P +.RE +.SS "Receive Mode" +.sp +.RS 4 +.nf +\fB +mailx \(mie +.P +mailx \fB[\fR\(miHiNn\fB] [\fR\(miF\fB] [\fR\(miu \fIuser\fB]\fR +.P +mailx \(mif \fB[\fR\(miHiNn\fB] [\fR\(miF\fB] [\fIfile\fB]\fR +.fi \fR +.P +.RE +.SH DESCRIPTION +The +.IR mailx +utility provides a message sending and receiving facility. It has two +major modes, selected by the options used: Send Mode and Receive +Mode. +.P +On systems that do not support the User Portability Utilities option, +an application using +.IR mailx +shall have the ability to send messages in an unspecified manner (Send +Mode). Unless the first character of one or more lines is + +(\c +.BR '~' ), +all characters in the input message shall appear in the delivered +message, but additional characters may be inserted in the message +before it is retrieved. +.P +On systems supporting the User Portability Utilities option, +mail-receiving capabilities and other interactive features, Receive +Mode, described below, also shall be enabled. +.SS "Send Mode" +.P +Send Mode can be used by applications or users to send messages from +the text in standard input. +.SS "\*!Receive Mode" +.P +Receive Mode is more oriented towards interactive users. Mail can be read +and sent in this interactive mode. +.P +When reading mail, +.IR mailx +provides commands to facilitate saving, deleting, and responding to +messages. When sending mail, +.IR mailx +allows editing, reviewing, and other modification of the message as it +is entered. +.P +Incoming mail shall be stored in one or more unspecified locations for +each user, collectively called the system +.IR mailbox +for that user. When +.IR mailx +is invoked in Receive Mode, the system mailbox shall be the default +place to find new mail. As messages are read, they shall be marked to +be moved to a secondary file for storage, unless specific action is +taken. This secondary file is called the +.BR mbox +and is normally located in the directory referred to by the +.IR HOME +environment variable (see +.IR MBOX +in the ENVIRONMENT VARIABLES section for a description of this file). +Messages shall remain in this file until explicitly removed. When the +.BR \(mif +option is used to read mail messages from secondary files, messages +shall be retained in those files unless specifically removed. All +three of these locations\(emsystem mailbox, +.BR mbox , +and secondary file\(emare referred to in this section as simply +``mailboxes'', unless more specific identification is required. +.SH OPTIONS +The +.IR mailx +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported. (Only the +.BR \(mis +.IR subject +option shall be required on all systems. The other options are required +only on systems supporting the User Portability Utilities option.) +.IP "\fB\(mie\fP" 10 +Test for the presence of mail in the system mailbox. The +.IR mailx +utility shall write nothing and exit with a successful return code if +there is mail to read. +.IP "\fB\(mif\fP" 10 +Read messages from the file named by the +.IR file +operand instead of the system mailbox. (See also +.BR folder .) +If no +.IR file +operand is specified, read messages from +.BR mbox +instead of the system mailbox. +.IP "\fB\(miF\fP" 10 +Record the message in a file named after the first recipient. The name +is the login-name portion of the address found first on the +.BR To: +line in the mail header. Overrides the +.BR record +variable, if set (see +.IR "Internal Variables in mailx"). +.IP "\fB\(miH\fP" 10 +Write a header summary only. +.IP "\fB\(mii\fP" 10 +Ignore interrupts. (See also +.BR ignore .) +.IP "\fB\(min\fP" 10 +Do not initialize from the system default start-up file. See the +EXTENDED DESCRIPTION section. +.IP "\fB\(miN\fP" 10 +Do not write an initial header summary. +.IP "\fB\(mis\0\fIsubject\fR" 10 +Set the +.BR Subject +header field to +.IR subject . +All characters in the +.IR subject +string shall appear in the delivered message. The results are +unspecified if +.IR subject +is longer than +{LINE_MAX} +\(mi 10 bytes or contains a +. +.IP "\fB\(miu\0\fIuser\fR" 10 +Read the system mailbox of the login name +.IR user . +This shall only be successful if the invoking user has appropriate +privileges to read the system mailbox of that user. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIaddress\fR" 10 +Addressee of message. When +.BR \(min +is specified and no user start-up files are accessed (see the EXTENDED +DESCRIPTION section), the user or application shall ensure this is an +address to pass to the mail delivery system. Any system or user +start-up files may enable aliases (see +.BR alias +under +.IR "Commands in mailx") +that may modify the form of +.IR address +before it is passed to the mail delivery system. +.IP "\fIfile\fR" 10 +A pathname of a file to be read instead of the system mailbox when +.BR \(mif +is specified. The meaning of the +.IR file +option-argument shall be affected by the contents of the +.BR folder +internal variable; see +.IR "Internal Variables in mailx". +.SH STDIN +When +.IR mailx +is invoked in Send Mode (the first synopsis line), standard input shall +be the message to be delivered to the specified addresses. +When in Receive Mode, user commands shall be accepted from +.IR stdin . +If the User Portability Utilities option is not supported, standard +input lines beginning with a + +(\c +.BR '~' ) +character produce unspecified results. +.P +If the User Portability Utilities option is supported, then in both +Send and Receive Modes, standard input lines beginning with the escape +character (usually + +(\c +.BR '~' )) +shall affect processing as described in +.IR "Command Escapes in mailx". +.SH "INPUT FILES" +When +.IR mailx +is used as described by this volume of POSIX.1\(hy2008, the +.IR file +option-argument (see the +.BR \(mif +option) and the +.BR mbox +shall be text files containing mail messages, formatted as described in +the OUTPUT FILES section. The nature of the system mailbox is +unspecified; it need not be a file. +.SH "ENVIRONMENT VARIABLES" +Some of the functionality described in this section shall be provided on +implementations that support the User Portability Utilities option +as described in the text, and is not further shaded for this option. +.P +The following environment variables shall affect the execution of +.IR mailx : +.IP "\fIDEAD\fP" 10 +Determine the pathname of the file in which to save partial messages in +case of interrupts or delivery errors. The default shall be +.BR dead.letter +in the directory named by the +.IR HOME +variable. The behavior of +.IR mailx +in saving partial messages is unspecified if the User Portability +Utilities option is not supported and +.IR DEAD +is not defined with the value +.BR /dev/null . +.IP "\fIEDITOR\fP" 10 +Determine the name of a utility to invoke when the +.BR edit +(see +.IR "Commands in mailx") +or +.BR ~e +(see +.IR "Command Escapes in mailx") +command is used. The default editor is unspecified. +On XSI-conformant systems it is +.IR ed . +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the handling of +case-insensitive address and header-field comparisons. +.IP "\fILC_TIME\fP" 10 +This variable may determine the format and contents of the date and +time strings written by +.IR mailx . +This volume of POSIX.1\(hy2008 specifies the effects of this variable only for systems +supporting the User Portability Utilities option. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILISTER\fP" 10 +Determine a string representing the command for writing the contents of +the +.BR folder +directory to standard output when the +.BR folders +command is given (see +.BR folders +in +.IR "Commands in mailx"). +Any string acceptable as a +.IR command_string +operand to the +.IR sh +.BR \(mic +command shall be valid. If this variable is null or not set, the output +command shall be +.IR ls . +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.IP "\fIMAILRC\fP" 10 +Determine the pathname of the start-up file. The default shall be +.BR .mailrc +in the directory referred to by the +.IR HOME +environment variable. The behavior of +.IR mailx +is unspecified if the User Portability Utilities option is not +supported and +.IR MAILRC +is not defined with the value +.BR /dev/null . +.IP "\fIMBOX\fP" 10 +Determine a pathname of the file to save messages from the system +mailbox that have been read. The +.BR exit +command shall override this function, as shall saving the message +explicitly in another file. The default shall be +.BR mbox +in the directory named by the +.IR HOME +variable. The effects of this variable are unspecified if the User +Portability Utilities option is not supported. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPAGER\fP" 10 +Determine a string representing an output filtering or pagination +command for writing the output to the terminal. Any string acceptable +as a +.IR command_string +operand to the +.IR sh +.BR \(mic +command shall be valid. When standard output is a terminal device, the +message output shall be piped through the command if the +.IR mailx +internal variable +.BR crt +is set to a value less the number of lines in the message; see +.IR "Internal Variables in mailx". +If the +.IR PAGER +variable is null or not set, the paginator shall be either +.IR more +or another paginator utility documented in the system documentation. +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.IP "\fISHELL\fP" 10 +Determine the name of a preferred command interpreter. The default +shall be +.IR sh . +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.IP "\fITERM\fP" 10 +If the internal variable +.BR screen +is not specified, determine the name of the terminal type to indicate +in an unspecified manner the number of lines in a screenful of headers. +If +.IR TERM +is not set or is set to null, an unspecified default terminal type +shall be used and the value of a screenful is unspecified. The effects +of this variable are unspecified if the User Portability Utilities +option is not supported. +.IP "\fITZ\fP" 10 +This variable may determine the timezone used to calculate date and +time strings written by +.IR mailx . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.IP "\fIVISUAL\fP" 10 +Determine a pathname of a utility to invoke when the +.BR visual +command (see +.IR "Commands in mailx") +or +.BR ~v +command-escape (see +.IR "Command Escapes in mailx") +is used. If this variable is null or not set, the full-screen editor +shall be +.IR vi . +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.SH "ASYNCHRONOUS EVENTS" +When +.IR mailx +is in Send Mode and standard input is not a terminal, it shall take the +standard action for all signals. +.P +In +Receive Mode, or in +Send Mode when standard input is a terminal, if a SIGINT signal +is received: +.IP " 1." 4 +If in command mode, the current command, if there is one, shall be +aborted, and a command-mode prompt shall be written. +.IP " 2." 4 +If in input mode: +.RS 4 +.IP " a." 4 +If +.BR ignore +is set, +.IR mailx +shall write +.BR \(dq@\en\(dq , +discard the current input line, and continue processing, bypassing the +message-abort mechanism described in item 2b. +.IP " b." 4 +If the interrupt was received while sending mail, either when in +Receive Mode or in +Send Mode, a message shall be written, and another +subsequent interrupt, with no other intervening characters typed, shall +be required to abort the mail message. +If in Receive Mode and another +interrupt is received, a command-mode prompt shall be written. +If in Send Mode and another interrupt is received, +.IR mailx +shall terminate with a non-zero status. +.RS 4 +.P +In both cases listed in item b, if the message is not empty: +.IP " i." 5 +If +.BR save +is enabled and the file named by +.IR DEAD +can be created, the message shall be written to the file named by +.IR DEAD . +If the file exists, the message shall be written to replace the +contents of the file. +.IP ii. 5 +If +.BR save +is not enabled, or +the file named by +.IR DEAD +cannot be created, the message shall not be saved. +.RE +.RE +.P +The +.IR mailx +utility shall take the standard action for all other signals. +.SH STDOUT +In command and input modes, all output, including prompts and messages, +shall be written to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Various +.IR mailx +commands and command escapes can create or add to files, including the +.BR mbox , +the dead-letter file, and secondary mailboxes. When +.IR mailx +is used as described in this volume of POSIX.1\(hy2008, these files shall be text files, +formatted as follows: +.sp +.RS +\fRline beginning with \fBFrom +.br +[\fRone or more \fIheader-lines\fR; see +.IR "Commands in mailx"] +.br +\fIempty line +.br +\fB[\fRzero or more \fIbody lines +.br +\fIempty line] +.br +\fB[\fRline beginning with \fBFrom...]\fR +.RE +.P +where each message begins with the +.BR "From\0" +line shown, preceded by the beginning of the file or an empty line. +(The +.BR "From " +line is considered to be part of the message header, but not one of the +header-lines referred to in +.IR "Commands in mailx"; +thus, it shall not be affected by the +.BR discard , +.BR ignore , +or +.BR retain +commands.) The formats of the remainder of the +.BR "From " +line and any additional header lines are unspecified, except that none +shall be empty. The format of a message body line is also unspecified, +except that no line following an empty line shall start with +.BR "From " ; +.IR mailx +shall modify any such user-entered message body lines (following an +empty line and beginning with +.BR "From " ) +by adding one or more characters to precede the +.BR 'F' ; +it may add these characters to +.BR "From " +lines that are not preceded by an empty line. +.P +When a message from the system mailbox or entered by the user is not a +text file, it is implementation-defined how such a message is stored +in files written by +.IR mailx . +.SH "EXTENDED DESCRIPTION" +The functionality in the entire EXTENDED DESCRIPTION section shall +be provided on implementations supporting the User Portability +Utilities option. +The functionality described in this section shall be provided on +implementations that support the User Portability Utilities option +(and the rest of this section is not further shaded for this option). +.P +The +.IR mailx +utility need not support for all character encodings in all +circumstances. For example, inter-system mail may be restricted to +7-bit data by the underlying network, 8-bit data need not be portable +to non-internationalized systems, and so on. Under these +circumstances, it is recommended that only characters defined in the +ISO/IEC\ 646:\|1991 standard International Reference Version (equivalent to ASCII) 7-bit range +of characters be used. +.P +When +.IR mailx +is invoked using one of the Receive Mode synopsis forms, it shall write +a page of header-summary lines (if +.BR \(miN +was not specified and there are messages, see below), followed by a +prompt indicating that +.IR mailx +can accept regular commands (see +.IR "Commands in mailx"); +this is termed +.IR "command mode" . +The page of header-summary lines shall contain the first new message if +there are new messages, or the first unread message if there are unread +messages, or the first message. When +.IR mailx +is invoked using the Send Mode synopsis and standard input is a +terminal, if no subject is specified on the command line and the +.BR asksub +variable is set, a prompt for the subject shall be written. At this +point, +.IR mailx +shall be in input mode. This input mode shall also be entered when using +one of the Receive Mode synopsis forms and a reply or new message is +composed using the +.BR reply , +.BR Reply , +.BR followup , +.BR Followup , +or +.BR mail +commands and standard input is a terminal. When the message is typed +and the end of the message is encountered, the message shall be passed to +the mail delivery software. Commands can be entered by beginning a line +with the escape character (by default, + +(\c +.BR '~' )) +followed by a single command letter and optional arguments. See +.IR "Commands in mailx" +for a summary of these commands. It is unspecified what effect these +commands will have if standard input is not a terminal when a message +is entered using either the Send Mode synopsis, or the Read Mode +commands +.BR reply , +.BR Reply , +.BR followup , +.BR Followup , +or +.BR mail . +.TP 10 +.BR Note: +For notational convenience, this section uses the default escape +character, +, +in all references and examples. +.P +.P +At any time, the behavior of +.IR mailx +shall be governed by a set of environmental and internal variables. +These are flags and valued parameters that can be set and cleared via +the +.IR mailx +.BR set +and +.BR unset +commands. +.P +Regular commands are of the form: +.sp +.RS 4 +.nf +\fB +\fB[\fIcommand\fB] [\fImsglist\fB] [\fIargument \fR...\fB] +.fi \fR +.P +.RE +.P +If no +.IR command +is specified in command mode, +.BR next +shall be assumed. In input mode, commands shall be recognized by the +escape character, and lines not treated as commands shall be taken as +input for the message. +.P +In command mode, each message shall be assigned a sequential number, +starting with 1. +.P +All messages have a state that shall affect how they are displayed in +the header summary and how they are retained or deleted upon +termination of +.IR mailx . +There is at any time the notion of a +.IR current +message, which shall be marked by a +.BR '>' +at the beginning of a line in the header summary. When +.IR mailx +is invoked using one of the Receive Mode synopsis forms, the current +message shall be the first new message, if there is a new message, or +the first unread message if there is an unread message, or the first +message if there are any messages, or unspecified if there are no +messages in the mailbox. Each command that takes an optional list of +messages (\fImsglist\fP) or an optional single message (\fImessage\fP) +on which to operate shall leave the current message set to the +highest-numbered message of the messages specified, unless the command +deletes messages, in which case the current message shall be set to the +first undeleted message (that is, a message not in the deleted state) +after the highest-numbered message deleted by the command, if one +exists, or the first undeleted message before the highest-numbered +message deleted by the command, if one exists, or to an unspecified +value if there are no remaining undeleted messages. All messages +shall be in one of the following states: +.IP "\fInew\fR" 10 +The message is present in the system mailbox and has not been viewed by +the user or moved to any other state. Messages in state +.IR new +when +.IR mailx +quits shall be retained in the system mailbox. +.IP "\fIunread\fR" 10 +The message has been present in the system mailbox for more than one +invocation of +.IR mailx +and has not been viewed by the user or moved to any other state. +Messages in state +.IR unread +when +.IR mailx +quits shall be retained in the system mailbox. +.IP "\fIread\fR" 10 +The message has been processed by one of the following commands: +.BR ~f , +.BR ~m , +.BR ~F , +.BR ~M , +.BR copy , +.BR mbox , +.BR next , +.BR pipe , +.BR print , +.BR Print , +.BR top , +.BR type , +.BR Type , +.BR undelete . +The +.BR delete , +.BR dp , +and +.BR dt +commands may also cause the next message to be marked as +.IR read , +depending on the value of the +.BR autoprint +variable. Messages that are in the system mailbox and in state +.IR read +when +.IR mailx +quits shall be saved in the +.BR mbox , +unless the internal variable +.BR hold +was set. Messages that are in the +.BR mbox +or in a secondary mailbox and in state +.IR read +when +.IR mailx +quits shall be retained in their current location. +.IP "\fIdeleted\fR" 10 +The message has been processed by one of the following commands: +.BR delete , +.BR dp , +.BR dt . +Messages in state +.IR deleted +when +.IR mailx +quits shall be deleted. Deleted messages shall be ignored until +.IR mailx +quits or changes mailboxes or they are specified to the undelete +command; for example, the message specification /\c +.IR string +shall only search the subject lines of messages that have not yet been +deleted, unless the command operating on the list of messages is +.BR undelete . +No deleted message or deleted message header shall be displayed by any +.IR mailx +command other than +.BR undelete . +.IP "\fIpreserved\fR" 10 +The message has been processed by a +.BR preserve +command. When +.IR mailx +quits, the message shall be retained in its current location. +.IP "\fIsaved\fR" 10 +The message has been processed by one of the following commands: +.BR save +or +.BR write . +If the current mailbox is the system mailbox, and the internal variable +.BR keepsave +is set, messages in the state saved shall be saved to the file +designated by the +.IR MBOX +variable (see the ENVIRONMENT VARIABLES section). If the current +mailbox is the system mailbox, messages in the state +.IR saved +shall be deleted from the current mailbox, when the +.BR quit +or +.BR file +command is used to exit the current mailbox. +.P +The header-summary line for each message shall indicate the state of +the message. +.P +Many commands take an optional list of messages (\c +.IR msglist ) +on which to operate, which defaults to the current message. A +.IR msglist +is a list of message specifications separated by + +characters, which can include: +.IP "\fRn\fR" 8 +Message number +.IR n . +.IP "\fR+\fR" 8 +The next undeleted message, or the next deleted message for the +.BR undelete +command. +.IP "\fR\(mi\fR" 8 +The next previous undeleted message, or the next previous deleted +message for the +.BR undelete +command. +.IP "\fR.\fR" 8 +The current message. +.IP "\fR^\fR" 8 +The first undeleted message, or the first deleted message for the +.BR undelete +command. +.IP "\fR$\fR" 8 +The last message. +.IP "\fR*\fR" 8 +All messages. +.IP "\fRn\(hym\fR" 8 +An inclusive range of message numbers. +.IP "\fIaddress\fR" 8 +All messages from +.IR address ; +any address as shown in a header summary shall be matchable in this +form. +.IP "/\fIstring\fR" 8 +All messages with +.IR string +in the subject line (case ignored). +.IP "\fR:c\fR" 8 +All messages of type +.IR c , +where +.IR c +shall be one of: +.RS 8 +.IP "\fRd\fR" 6 +Deleted messages. +.IP "\fRn\fR" 6 +New messages. +.IP "\fRo\fR" 6 +Old messages (any not in state +.IR read +or +.IR new ). +.IP "\fRr\fR" 6 +Read messages. +.IP "\fRu\fR" 6 +Unread messages. +.RE +.P +Other commands take an optional message (\c +.IR message ) +on which to operate, which defaults to the current message. All of the +forms allowed for +.IR msglist +are also allowed for +.IR message , +but if more than one message is specified, only the first shall be +operated on. +.P +Other arguments are usually arbitrary strings whose usage depends on +the command involved. +.SS "Start-Up in mailx" +.P +At start-up time, +.IR mailx +shall take the following steps in sequence: +.IP " 1." 4 +Establish all variables at their stated default values. +.IP " 2." 4 +Process command line options, overriding corresponding default values. +.IP " 3." 4 +Import any of the +.IR DEAD , +.IR EDITOR , +.IR MBOX , +.IR LISTER , +.IR PAGER , +.IR SHELL , +or +.IR VISUAL +variables that are present in the environment, overriding the +corresponding default values. +.IP " 4." 4 +Read +.IR mailx +commands from an unspecified system start-up file, unless the +.BR \(min +option is given, to initialize any internal +.IR mailx +variables and aliases. +.IP " 5." 4 +Process the start-up file of +.IR mailx +commands named in the user +.IR MAILRC +variable. +.P +Most regular +.IR mailx +commands are valid inside start-up files, the most common use being to +set up initial display options and alias lists. The following commands +shall be invalid in the start-up file: +.BR ! , +.BR edit , +.BR hold , +.BR mail , +.BR preserve , +.BR reply , +.BR Reply , +.BR shell , +.BR visual , +.BR Copy , +.BR followup , +and +.BR Followup . +Any errors in the start-up file shall either cause +.IR mailx +to terminate with a diagnostic message and a non-zero status or to +continue after writing a diagnostic message, ignoring the remainder of +the lines in the start-up file. +.P +A blank line in a start-up file shall be ignored. +.SS "Internal Variables in mailx" +.P +The following variables are internal +.IR mailx +variables. Each internal variable can be set via the +.IR mailx +.BR set +command at any time. The +.BR unset +and +.BR "set\0no" +.IR name +commands can be used to erase variables. +.P +In the following list, variables shown as: +.sp +.RS 4 +.nf +\fB +variable +.fi \fR +.P +.RE +.P +represent Boolean values. Variables shown as: +.sp +.RS 4 +.nf +\fB +variable=\fIvalue\fP +.fi \fR +.P +.RE +.P +shall be assigned string or numeric values. For string values, the +rules in +.IR "Commands in mailx" +concerning filenames and quoting shall also apply. +.P +The defaults specified here may be changed by the unspecified system +start-up file unless the user specifies the +.BR \(min +option. +.IP "\fBallnet\fP" 10 +All network names whose login name components match shall be treated as +identical. This shall cause the +.IR msglist +message specifications to behave similarly. The default shall be +.BR noallnet . +See also the +.BR alternates +command and the +.BR metoo +variable. +.IP "\fBappend\fR" 10 +Append messages to the end of the +.BR mbox +file upon termination instead of placing them at the beginning. The +default shall be +.BR noappend . +This variable shall not affect the +.BR save +command when saving to +.BR mbox . +.IP "\fBask\fR,\0\fBasksub\fR" 10 +Prompt for a subject line on outgoing mail if one is not specified on +the command line with the +.BR \(mis +option. The +.BR ask +and +.BR asksub +forms are synonyms; the system shall refer to +.BR asksub +and +.BR noasksub +in its messages, but shall accept +.BR ask +and +.BR noask +as user input to mean +.BR asksub +and +.BR noasksub . +It shall not be possible to set both +.BR ask +and +.BR noasksub , +or +.BR noask +and +.BR asksub . +The default shall be +.BR asksub , +but no prompting shall be done if standard input is not a terminal. +.IP "\fBaskbcc\fR" 10 +Prompt for the blind copy list. The default shall be +.BR noaskbcc . +.IP "\fBaskcc\fR" 10 +Prompt for the copy list. The default shall be +.BR noaskcc . +.IP "\fBautoprint\fR" 10 +Enable automatic writing of messages after +.BR delete +and +.BR undelete +commands. The default shall be +.BR noautoprint . +.IP "\fBbang\fR" 10 +Enable the special-case treatment of + +characters (\c +.BR '!' ) +in escape command lines; see the +.BR escape +command and +.IR "Command Escapes in mailx". +The default shall be +.BR nobang , +disabling the expansion of +.BR '!' +in the +.IR command +argument to the +.BR ~! +command and the +.BR ~ +on a line by itself during message input from a terminal shall also +signify end-of-file (in addition to normal end-of-file). The default +shall be +.BR nodot . +If +.BR ignoreeof +is set (see below), a setting of +.BR nodot +shall be ignored and the + +is the only method to terminate input mode. +.IP "\fBescape\fR=\fIc\fR" 10 +Set the command escape character to be the character +.BR 'c' . +By default, the command escape character shall be +. +If +.BR escape +is unset, + +shall be used; if it is set to null, command escaping shall be disabled. +.IP "\fBflipr\fR" 10 +Reverse the meanings of the +.BR R +and +.BR r +commands. The default shall be +.BR noflipr . +.IP "\fBfolder\fR=\fIdirectory\fR" 10 +.br +The default directory for saving mail files. User-specified filenames +beginning with a + +(\c +.BR '\(pl' ) +shall be expanded by preceding the filename with this directory name +to obtain the real pathname. If +.IR directory +does not start with a + +(\c +.BR '/' ), +the contents of +.IR HOME +shall be prefixed to it. The default shall be +.BR nofolder . +If +.BR folder +is unset or set to null, user-specified filenames beginning with +.BR '\(pl' +shall refer to files in the current directory that begin with the +literal +.BR '\(pl' +character. See also +.BR outfolder +below. The +.BR folder +value need not affect the processing of the files named in +.IR MBOX +and +.IR DEAD . +.IP "\fBheader\fR" 10 +Enable writing of the header summary when entering +.IR mailx +in Receive Mode. The default shall be +.BR header . +.IP "\fBhold\fR" 10 +Preserve all messages that are read in the system mailbox instead of +putting them in the +.BR mbox +save file. The default shall be +.BR nohold . +.IP "\fBignore\fR" 10 +Ignore interrupts while entering messages. The default shall be +.BR noignore . +.IP "\fBignoreeof\fR" 10 +Ignore normal end-of-file during message input. Input can be +terminated only by entering a + +(\c +.BR '.' ) +on a line by itself or by the +.BR ~. +command escape. The default shall be +.BR noignoreeof . +See also +.BR dot +above. +.IP "\fBindentprefix\fR=\fIstring\fR" 10 +.br +A string that shall be added as a prefix to each line that is inserted +into the message by the +.BR ~m +command escape. This variable shall default to one +. +.IP "\fBkeep\fR" 10 +When a system mailbox, secondary mailbox, or +.BR mbox +is empty, truncate it to zero length instead of removing it. The +default shall be +.BR nokeep . +.IP "\fBkeepsave\fR" 10 +Keep the messages that have been saved from the system mailbox into +other files in the file designated by the variable +.IR MBOX , +instead of deleting them. The default shall be +.BR nokeepsave . +.IP "\fBmetoo\fR" 10 +Suppress the deletion of the login name of the user from the recipient +list when replying to a message or sending to a group. The default +shall be +.BR nometoo . +.IP "\fBonehop\fR" 10 +When responding to a message that was originally sent to several +recipients, the other recipient addresses are normally forced to be +relative to the originating author's machine for the response. This +flag disables alteration of the recipients' addresses, improving +efficiency in a network where all machines can send directly to all +other machines (that is, one hop away). The default shall be +.BR noonehop . +.IP "\fBoutfolder\fR" 10 +Cause the files used to record outgoing messages to be located in the +directory specified by the +.BR folder +variable unless the pathname is absolute. The default shall be +.BR nooutfolder . +See the +.BR record +variable. +.IP "\fBpage\fR" 10 +Insert a + +after each message sent through the pipe created by the +.BR pipe +command. The default shall be +.BR nopage . +.IP "\fBprompt\fR=\fIstring\fR" 10 +.br +Set the command-mode prompt to +.IR string . +If +.IR string +is null or if +.BR noprompt +is set, no prompting shall occur. The default shall be to prompt with +the string +.BR \(dq?\0\(dq . +.IP "\fBquiet\fR" 10 +Refrain from writing the opening message and version when entering +.IR mailx . +The default shall be +.BR noquiet . +.IP "\fBrecord\fR=\fIfile\fR" 10 +Record all outgoing mail in the file with the pathname +.IR file . +The default shall be +.BR norecord . +See also +.BR outfolder +above. +.IP "\fBsave\fR" 10 +Enable saving of messages in the dead-letter file on interrupt or +delivery error. See the variable +.IR DEAD +for the location of the dead-letter file. The default shall be +.BR save . +.IP "\fBscreen\fR=\fInumber\fR" 10 +.br +Set the number of lines in a screenful of headers for the +.BR headers +and +.BR z +commands. If +.BR screen +is not specified, a value based on the terminal type identified by the +.IR TERM +environment variable, the window size, the baud rate, or some +combination of these shall be used. +.IP "\fBsendwait\fR" 10 +Wait for the background mailer to finish before returning. The default +shall be +.BR nosendwait . +.IP "\fBshowto\fR" 10 +When the sender of the message was the user who is invoking +.IR mailx , +write the information from the +.BR To: +line instead of the +.BR From: +line in the header summary. The default shall be +.BR noshowto . +.IP "\fBsign\fR=\fIstring\fR" 10 +Set the variable inserted into the text of a message when the +.BR ~a +command escape is given. The default shall be +.BR nosign . +The character sequences +.BR '\et' +and +.BR '\en' +shall be recognized in the variable as + +and + +characters, respectively. (See also +.BR ~i +in +.IR "Command Escapes in mailx".) +.IP "\fBSign\fR=\fIstring\fR" 10 +Set the variable inserted into the text of a message when the +.BR ~A +command escape is given. The default shall be +.BR noSign . +The character sequences +.BR '\et' +and +.BR '\en' +shall be recognized in the variable as + +and + +characters, respectively. +.IP "\fBtoplines\fR=\fInumber\fR" 10 +.br +Set the number of lines of the message to write with the +.BR top +command. The default shall be 5. +.SS "Commands in mailx" +.P +The following +.IR mailx +commands shall be provided. In the following list, header refers to +lines from the message header, as shown in the OUTPUT FILES section. +Header-line refers to lines within the header that begin with one or +more non-white-space characters, immediately followed by a + +and white space and continuing until the next line beginning with a +non-white-space character or an empty line. Header-field refers to the +portion of a header line prior to the first + +in that line. +.P +For each of the commands listed below, the command can be entered as +the abbreviation (those characters in the Synopsis command word +preceding the +.BR '[' ), +the full command (all characters shown for the command word, omitting +the +.BR '[' +and +.BR ']' ), +or any truncation of the full command down to the abbreviation. For +example, the +.BR exit +command (shown as \fBex[it]\fR in the Synopsis) can be entered as +.BR ex , +.BR exi , +or +.BR exit . +.P +The arguments to commands can be quoted, using the following methods: +.IP " *" 4 +An argument can be enclosed between paired double-quotes (\c +.BR \(dq\^\(dq ) +or single-quotes (\c +.BR '\^' ); +any white space, shell word expansion, or + +characters within the quotes shall be treated literally as part of the +argument. A double-quote shall be treated literally within single-quotes +and \fIvice versa\fP. These special properties of the + +characters shall occur only when they are paired at the beginning and +end of the argument. +.IP " *" 4 +A + +outside of the enclosing quotes shall be discarded and the following +character treated literally as part of the argument. +.IP " *" 4 +An unquoted + +at the end of a command line shall be discarded and the next line shall +continue the command. +.br +.P +Filenames, where expected, shall be subjected to the following +transformations, in sequence: +.IP " *" 4 +If the filename begins with an unquoted +, +and the +.BR folder +variable is defined (see the +.BR folder +variable), the + +shall be replaced by the value of the +.BR folder +variable followed by a +. +If the +.BR folder +variable is unset or is set to null, the filename shall be unchanged. +.IP " *" 4 +Shell word expansions shall be applied to the filename (see +.IR "Section 2.6" ", " "Word Expansions"). +If more than a single pathname results from this expansion and the +command is expecting one file, the effects are unspecified. +.SS "Declare Aliases" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +a\fB[\fRlias\fB] [\fIalias \fB[\fIaddress\fR...\fB]]\fR +g\fB[\fRroup\fB] [\fIalias \fB[\fIaddress\fR...\fB]]\fR +.fi \fR +.P +.RE +.RE +.P +Add the given addresses to the alias specified by +.IR alias . +The names shall be substituted when +.IR alias +is used as a recipient address specified by the user in an outgoing +message (that is, other recipients addressed indirectly through the +.BR reply +command shall not be substituted in this manner). Mail address alias +substitution shall apply only when the alias string is used as a full +address; for example, when +.BR hlj +is an alias, +.IR hlj@posix.com +does not trigger the alias substitution. If no arguments are given, +write a listing of the current aliases to standard output. If only an +.IR alias +argument is given, write a listing of the specified alias to standard +output. These listings need not reflect the same order of addresses +that were entered. +.SS "Declare Alternatives" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +alt\fB[\fRernates\fB] \fIname\fR... +.fi \fR +.P +.RE +.RE +.P +(See also the +.BR metoo +variable.) Declare a list of alternative names for the user's login. +When responding to a message, these names shall be removed from the +list of recipients for the response. The comparison of names shall be +in a case-insensitive manner. With no arguments, +.BR alternates +shall write the current list of alternative names. +.SS "Change Current Directory" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +cd \fB[\fIdirectory\fB]\fR +ch\fB[\fRdir\fB] [\fIdirectory\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Change directory. If +.IR directory +is not specified, the contents of +.IR HOME +shall be used. +.SS "Copy Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +c\fB[\fRopy\fB] [\fIfile\fB]\fR +c\fB[\fRopy\fB] [\fImsglist\fB] \fIfile\fR +C\fB[\fRopy\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Copy messages to the file named by the pathname +.IR file +without marking the messages as saved. Otherwise, it shall be +equivalent to the +.BR save +command. +.P +In the capitalized form, save the specified messages in a file whose +name is derived from the author of the message to be saved, without +marking the messages as saved. Otherwise, it shall be equivalent to +the +.BR Save +command. +.SS "Delete Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +d\fB[\fRelete\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Mark messages for deletion from the mailbox. The deletions shall not +occur until +.IR mailx +quits (see the +.BR quit +command) or changes mailboxes (see the +.BR folder +command). If +.BR autoprint +is set and there are messages remaining after the +.BR delete +command, the current message shall be written as described for the +.BR print +command (see the +.BR print +command); otherwise, the +.IR mailx +prompt shall be written. +.SS "Discard Header Fields" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +di\fB[\fRscard\fB] [\fIheader-field\fR...\fB]\fR +ig\fB[\fRnore\fB] [\fIheader-field\fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Suppress the specified header fields when writing messages. Specified +.IR header-fields +shall be added to the list of suppressed header fields. Examples of +header fields to ignore are +.BR status +and +.BR cc . +The fields shall be included when the message is saved. The +.BR Print +and +.BR Type +commands shall override this command. The comparison of header fields +shall be in a case-insensitive manner. If no arguments are specified, +write a list of the currently suppressed header fields to standard +output; the listing need not reflect the same order of header fields +that were entered. +.P +If both +.BR retain +and +.BR discard +commands are given, +.BR discard +commands shall be ignored. +.SS "Delete Messages and Display" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +dp \fB[\fImsglist\fB]\fR +dt \fB[\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Delete the specified messages as described for the +.BR delete +command, except that the +.BR autoprint +variable shall have no effect, and the current message shall be written +only if it was set to a message after the last message deleted by the +command. Otherwise, an informational message to the effect that there +are no further messages in the mailbox shall be written, followed by +the +.IR mailx +prompt. +.SS "Echo a String" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ec\fB[\fRho\fB] \fIstring\fR ... +.fi \fR +.P +.RE +.RE +.P +Echo the given strings, equivalent to the shell +.IR echo +utility. +.SS "Edit Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +e\fB[\fRdit\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Edit the given messages. The messages shall be placed in a temporary +file and the utility named by the +.IR EDITOR +variable is invoked to edit each file in sequence. The default +.IR EDITOR +is unspecified. +.P +The +.BR edit +command does not modify the contents of those messages in the mailbox. +.SS "Exit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ex\fB[\fRit\fB]\fR +x\fB[\fRit\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Exit from +.IR mailx +without changing the mailbox. No messages shall be saved in the +.BR mbox +(see also +.BR quit ). +.SS "Change Folder" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +fi\fB[\fRle\fB] [\fIfile\fB]\fR +fold\fB[\fRer\fB] [\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Quit (see the +.BR quit +command) from the current file of messages and read in the file named +by the pathname +.IR file . +If no argument is given, the name and status of the current mailbox +shall be written. +.P +Several unquoted special characters shall be recognized when used as +.IR file +names, with the following substitutions: +.IP "\fR%\fR" 8 +The system mailbox for the invoking user. +.IP "\fR%\fIuser\fR" 8 +The system mailbox for +.IR user . +.IP "\fR#\fR" 8 +The previous file. +.IP "\fR&\fR" 8 +The current +.BR mbox . +.IP "\fR+\fIfile\fR" 8 +The named file in the +.BR folder +directory. (See the +.BR folder +variable.) +.P +The default file shall be the current mailbox. +.SS "Display List of Folders" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fRfolders\fR +.fi \fR +.P +.RE +.RE +.P +Write the names of the files in the directory set by the +.BR folder +variable. The command specified by the +.IR LISTER +environment variable shall be used (see the ENVIRONMENT VARIABLES +section). +.SS "Follow Up Specified Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +fo\fB[\fRllowup\fB] [\fImessage\fB]\fR +F\fB[\fRollowup\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +In the lowercase form, respond to a message, recording the response in +a file whose name is derived from the author of the message. See also +the +.BR save +and +.BR copy +commands and +.BR outfolder . +.P +In the capitalized form, respond to the first message in the +.IR msglist , +sending the message to the author of each message in the +.IR msglist . +The subject line shall be taken from the first message and the response +shall be recorded in a file whose name is derived from the author of +the first message. See also the +.BR Save +and +.BR Copy +commands and +.BR outfolder . +.P +Both forms shall override the +.BR record +variable, if set. +.SS "Display Header Summary for Specified Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +f\fB[\fRrom\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the header summary for the specified messages. +.SS "Display Header Summary" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +h\fB[\fReaders\fB] [\fImessage\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the page of headers that includes the message specified. If the +.IR message +argument is not specified, the current message shall not change. +However, if the +.IR message +argument is specified, the current message shall become the message +that appears at the top of the page of headers that includes the +message specified. The +.BR screen +variable sets the number of headers per page. See also the +.BR z +command. +.SS "Help" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +hel\fB[\fRp\fB]\fR +? +.fi \fR +.P +.RE +.RE +.P +Write a summary of commands. +.SS "Hold Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ho\fB[\fRld\fB] [\fImsglist\fB]\fR +pre\fB[\fRserve\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Mark the messages in +.IR msglist +to be retained in the mailbox when +.IR mailx +terminates. This shall override any commands that might previously +have marked the messages to be deleted. During the current invocation +of +.IR mailx , +only the +.BR delete , +.BR dp , +or +.BR dt +commands shall remove the +.IR preserve +marking of a message. +.SS "Execute Commands Conditionally" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +i\fB[\fRf\fB]\fR s|r +\fImail-command\fRs +el\fB[\fRse\fB] +\fImail-command\fRs +en\fB[\fRdif\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Execute commands conditionally, where +.BR "if\0s" +executes the following +.IR mail-command s, +up to an +.BR else +or +.BR endif , +if the program is in Send Mode, and +.BR "if\0r" +shall cause the +.IR mail-command s +to be executed only in Receive Mode. +.SS "List Available Commands" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +l\fB[\fRist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write a list of all commands available. No explanation shall be +given. +.SS "Mail a Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +m\fB[\fRail\fB] \fIaddress\fR... +.fi \fR +.P +.RE +.RE +.P +Mail a message to the specified addresses or aliases. +.SS "Direct Messages to mbox" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +mb\fB[\fRox\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Arrange for the given messages to end up in the +.BR mbox +save file when +.IR mailx +terminates normally. See +.IR MBOX . +See also the +.BR exit +and +.BR quit +commands. +.SS "Process Next Specified Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +n\fB[\fRext\fB] [\fImessage\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If the current message has not been written (for example, by the +.BR print +command) since +.IR mailx +started or since any other message was the current message, behave as +if the +.BR print +command was entered. Otherwise, if there is an undeleted message after +the current message, make it the current message and behave as if the +.BR print +command was entered. Otherwise, an informational message to the effect +that there are no further messages in the mailbox shall be written, +followed by the +.IR mailx +prompt. Should the current message location be the result of an +immediately preceding +.BR hold , +.BR mbox , +.BR preserve , +or +.BR touch +command, +.BR next +will act as if the current message has already been written. +.SS "Pipe Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +pi\fB[\fRpe\fB] [[\fImsglist\fB] \fIcommand\fB]\fR +| \fB[[\fImsglist\fB] \fIcommand\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Pipe the messages through the given +.IR command +by invoking the command interpreter specified by +.IR SHELL +with two arguments: +.BR \(mic +and +.IR command . +(See also +.IR sh +.BR \(mic .) +The application shall ensure that the command is given as a single +argument. Quoting, described previously, can be used to accomplish +this. If no arguments are given, the current message shall be piped +through the command specified by the value of the +.BR cmd +variable. If the +.BR page +variable is set, a + +shall be inserted after each message. +.SS "Display Message with Headers" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +P\fB[\fRrint\fB] [\fImsglist\fB]\fR +T\fB[\fRype\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the specified messages, including all header lines, to standard +output. Override suppression of lines by the +.BR discard , +.BR ignore , +and +.BR retain +commands. If +.BR crt +is set, the messages longer than the number of lines specified by the +.BR crt +variable shall be paged through the command specified by the +.IR PAGER +environment variable. +.SS "Display Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +p\fB[\fRrint\fB] [\fImsglist\fB]\fR +t\fB[\fRype\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the specified messages to standard output. If +.BR crt +is set, the messages longer than the number of lines specified by the +.BR crt +variable shall be paged through the command specified by the +.IR PAGER +environment variable. +.SS "Quit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q\fB[\fRuit\fB] +\fIend-of-file\fR +.fi \fR +.P +.RE +.RE +.P +Terminate +.IR mailx , +storing messages that were read in +.BR mbox +(if the current mailbox is the system mailbox and unless +.BR hold +is set), deleting messages that have been explicitly saved (unless +.BR keepsave +is set), discarding messages that have been deleted, and saving all +remaining messages in the mailbox. +.SS "Reply to a Message List" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +R\fB[\fReply\fB] [\fImsglist\fB]\fR +R\fB[\fRespond\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Mail a reply message to the sender of each message in the +.IR msglist . +The subject line shall be formed by concatenating +.BR Re: \c + +(unless it already begins with that string) and the subject from the +first message. If +.BR record +is set to a filename, the response shall be saved at the end of that +file. +.P +See also the +.BR flipr +variable. +.SS "Reply to a Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +r\fB[\fReply\fB] [\fImessage\fB]\fR +r\fB[\fRespond\fB] [\fImessage\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Mail a reply message to all recipients included in the header of the +message. The subject line shall be formed by concatenating +.BR Re: \c + +(unless it already begins with that string) and the subject from the +message. If +.BR record +is set to a filename, the response shall be saved at the end of that +file. +.P +See also the +.BR flipr +variable. +.SS "Retain Header Fields" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ret\fB[\fRain\fB] [\fIheader-field\fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Retain the specified header fields when writing messages. This command +shall override all +.BR discard +and +.BR ignore +commands. The comparison of header fields shall be in a +case-insensitive manner. If no arguments are specified, write a list +of the currently retained header fields to standard output; the listing +need not reflect the same order of header fields that were entered. +.SS "Save Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +s\fB[\fRave\fB] [\fIfile\fB]\fR +s\fB[\fRave\fB] [\fImsglist\fB] \fIfile\fR +S\fB[\fRave\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Save the specified messages in the file named by the pathname +.IR file , +or the +.BR mbox +if the +.IR file +argument is omitted. The file shall be created if it does not exist; +otherwise, the messages shall be appended to the file. The message +shall be put in the state +.IR saved , +and shall behave as specified in the description of the +.IR saved +state when the current mailbox is exited by the +.BR quit +or +.BR file +command. +.P +In the capitalized form, save the specified messages in a file whose +name is derived from the author of the first message. The name of the +file shall be taken to be the author's name with all network addressing +stripped off. See also the +.BR Copy , +.BR followup , +and +.BR Followup +commands and +.BR outfolder +variable. +.SS "Set Variables" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +se\fB[\fRt\fB] [\fIname\fB[\fR=\fB[\fIstring\fB]] \fR...\fB] [\fIname\fR=\fInumber \fR...\fB] [\fRno\fIname \fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Define one or more variables called +.IR name . +The variable can be given a null, string, or numeric value. Quoting and +-escapes +can occur anywhere in +.IR string , +as described previously, as if the +.IR string +portion of the argument were the entire argument. The forms +.IR name +and +.IR name = +shall be equivalent to +.IR name ="" +for variables that take string values. The +.BR set +command without arguments shall write a list of all defined variables +and their values. The +.BR no +.IR name +form shall be equivalent to +.BR unset +.IR name . +.SS "Invoke a Shell" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +sh\fB[\fRell\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Invoke an interactive command interpreter (see also +.IR SHELL ). +.SS "Display Message Size" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +si\fB[\fRze\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the size in bytes of each of the specified messages. +.SS "Read mailx Commands From a File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +so\fB[\fRurce\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +Read and execute commands from the file named by the pathname +.IR file +and return to command mode. +.SS "Display Beginning of Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +to\fB[\fRp\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the top few lines of each of the specified messages. If the +.BR toplines +variable is set, it is taken as the number of lines to write. The +default shall be 5. +.SS "Touch Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +tou\fB[\fRch\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Touch the specified messages. If any message in +.IR msglist +is not specifically deleted nor saved in a file, it shall be placed in +the +.BR mbox +upon normal termination. See +.BR exit +and +.BR quit . +.SS "Delete Aliases" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +una\fB[\fRlias\fB] [\fIalias\fB]\fR... +.fi \fR +.P +.RE +.RE +.P +Delete the specified alias names. If a specified alias does not exist, +the results are unspecified. +.SS "Undelete Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u\fB[\fRndelete\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Change the state of the specified messages from deleted to read. If +.BR autoprint +is set, the last message of those restored shall be written. If +.IR msglist +is not specified, the message shall be selected as follows: +.IP " *" 4 +If there are any deleted messages that follow the current message, the +first of these shall be chosen. +.IP " *" 4 +Otherwise, the last deleted message that also precedes the current +message shall be chosen. +.SS "Unset Variables" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +uns\fB[\fRet\fB] \fIname\fR... +.fi \fR +.P +.RE +.RE +.P +Cause the specified variables to be erased. +.SS "Edit Message with Full-Screen Editor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +v\fB[\fRisual\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Edit the given messages with a screen editor. Each message shall be +placed in a temporary file, and the utility named by the +.IR VISUAL +variable shall be invoked to edit each file in sequence. The default +editor shall be +.IR vi . +.P +The +.BR visual +command does not modify the contents of those messages in the mailbox. +.SS "Write Messages to a File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +w\fB[\fRrite\fB] [\fImsglist\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +Write the given messages to the file specified by the pathname +.IR file , +minus the message header. Otherwise, it shall be equivalent to the +.BR save +command. +.SS "Scroll Header Display" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +z\fB[\fR+|\(mi\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Scroll the header display forward (if +.BR '\(pl' +is specified or if no option is specified) or backward (if +.BR '\(mi' +is specified) one screenful. The number of headers written shall be +set by the +.BR screen +variable. +.SS "Invoke Shell Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +!\fIcommand\fR +.fi \fR +.P +.RE +.RE +.P +Invoke the command interpreter specified by +.IR SHELL +with two arguments: +.BR \(mic +and +.IR command . +(See also +.IR sh +.BR \(mic .) +If the +.BR bang +variable is set, each unescaped occurrence of +.BR '!' +in +.IR command +shall be replaced with the command executed by the previous +.BR ! +command or +.BR ~! +command escape. +.SS "Null Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +# \fIcomment\fR +.fi \fR +.P +.RE +.RE +.P +This null command (comment) shall be ignored by +.IR mailx . +.SS "Display Current Message Number" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB += +.fi \fR +.P +.RE +.RE +.P +Write the current message number. +.SS "Command Escapes in mailx" +.P +The following commands can be entered only from input mode, by +beginning a line with the escape character (by default, + +(\c +.BR '~' )). +See the +.BR escape +variable description for changing this special character. The format +for the commands shall be: +.sp +.RS 4 +.nf +\fB +<\fIescape-character\fR><\fIcommand-char\fR><\fIseparator\fR>\fB[\fR<\fIarguments\fR>\fB]\fR +.fi \fR +.P +.RE +.P +where the <\fIseparator\fP> can be zero or more + +characters. +.P +In the following descriptions, the application shall ensure that the +argument +.IR command +(but not +.IR mailx-command) +is a shell command string. Any string acceptable to the command +interpreter specified by the +.IR SHELL +variable when it is invoked as +.IR SHELL +.BR \(mic +.IR command_string +shall be valid. The command can be presented as multiple arguments +(that is, quoting is not required). +.P +Command escapes that are listed with +.IR msglist +or +.IR mailx-command +arguments are invalid in Send Mode and produce unspecified results. +.IP "\fB~!\0\fIcommand\fR" 10 +Invoke the command interpreter specified by +.IR SHELL +with two arguments: +.BR \(mic +and +.IR command ; +and then return to input mode. If the +.BR bang +variable is set, each unescaped occurrence of +.BR '!' +in +.IR command +shall be replaced with the command executed by the previous +.BR ! +command or +.BR ~! +command escape. +.IP "\fB~.\fR" 10 +Simulate end-of-file (terminate message input). +.IP "\fB~:\0\fImailx-command\fR,\0\fB~_\0\fImailx-command\fR" 10 +.br +Perform the command-level request. +.IP "\fB~?\fR" 10 +Write a summary of command escapes. +.IP "\fB~A\fR" 10 +This shall be equivalent to +.BR "~i\0Sign" . +.IP "\fB~a\fR" 10 +This shall be equivalent to +.BR "~i\0sign" . +.IP "\fB~b\0\fIname\fR.\|.\|." 10 +Add the +.IR name s +to the blind carbon copy (\c +.BR Bcc ) +list. +.IP "\fB~c\0\fIname\fR.\|.\|." 10 +Add the +.IR name s +to the carbon copy (\c +.BR Cc ) +list. +.IP "\fB~d\fR" 10 +Read in the dead-letter file. See +.IR DEAD +for a description of this file. +.IP "\fB~e\fR" 10 +Invoke the editor, as specified by the +.IR EDITOR +environment variable, on the partial message. +.IP "\fB~\|f\0[\fImsglist\fB]\fR" 10 +Forward the specified messages. The specified messages shall be +inserted into the current message without alteration. This command +escape also shall insert message headers into the message with field +selection affected by the +.BR discard , +.BR ignore , +and +.BR retain +commands. +.IP "\fB~\|F\0[\fImsglist\fB]\fR" 10 +This shall be the equivalent of the +.BR ~f +command escape, except that all headers shall be included in the +message, regardless of previous +.BR discard , +.BR ignore , +and +.BR retain +commands. +.IP "\fB~h\fR" 10 +If standard input is a terminal, prompt for a +.BR Subject +line and the +.BR To , +.BR Cc , +and +.BR Bcc +lists. Other implementation-defined headers may also be presented +for editing. If the field is written with an initial value, it can be +edited as if it had just been typed. +.IP "\fB~i\0\fIstring\fR" 10 +Insert the value of the named variable, followed by a +, +into the text of the message. If the string is unset or null, the +message shall not be changed. +.IP "\fB~\|m\0[\fImsglist\fB]\fR" 10 +Insert the specified messages into the message, prefixing non-empty +lines with the string in the +.BR indentprefix +variable. This command escape also shall insert message headers into +the message, with field selection affected by the +.BR discard , +.BR ignore , +and +.BR retain +commands. +.IP "\fB~\|M\0[\fImsglist\fB]\fR" 10 +This shall be the equivalent of the +.BR ~m +command escape, except that all headers shall be included in the +message, regardless of previous +.BR discard , +.BR ignore , +and +.BR retain +commands. +.IP "\fB~p\fR" 10 +Write the message being entered. If the message is longer than +.BR crt +lines (see +.IR "Internal Variables in mailx"), +the output shall be paginated as described for the +.IR PAGER +variable. +.IP "\fB~q\fR" 10 +Quit (see the +.BR quit +command) from input mode by simulating an interrupt. If the body of +the message is not empty, the partial message shall be saved in the +dead-letter file. See +.IR DEAD +for a description of this file. +.IP "\fB~r\0\fIfile\fR,\0\fB~<\0\fIfile\fR,\0\fB~r\0!\fIcommand\fR,\0\fB~<\0!\fIcommand\fR" 10 +.br +Read in the file specified by the pathname +.IR file . +If the argument begins with an + +(\c +.BR '!' ), +the rest of the string shall be taken as an arbitrary system command; +the command interpreter specified by +.IR SHELL +shall be invoked with two arguments: +.BR \(mic +and +.IR command . +The standard output of +.IR command +shall be inserted into the message. +.IP "\fB~s\0\fIstring\fR" 10 +Set the subject line to +.IR string . +.IP "\fB~t\0\fIname\fR.\|.\|." 10 +Add the given +.IR name s +to the +.BR To +list. +.IP "\fB~v\fR" 10 +Invoke the full-screen editor, as specified by the +.IR VISUAL +environment variable, on the partial message. +.IP "\fB~w\0\fIfile\fR" 10 +Write the partial message, without the header, onto the file named by +the pathname +.IR file . +The file shall be created or the message shall be appended to it if the +file exists. +.IP "\fB~x\fR" 10 +Exit as with +.BR ~q , +except the message shall not be saved in the dead-letter file. +.IP "\fB~|\0\fIcommand\fR" 10 +Pipe the body of the message through the given +.IR command +by invoking the command interpreter specified by +.IR SHELL +with two arguments: +.BR \(mic +and +.IR command . +If the +.IR command +returns a successful exit status, the standard output of the command +shall replace the message. Otherwise, the message shall remain +unchanged. If the +.IR command +fails, an error message giving the exit status shall be written. +.br +.SH "EXIT STATUS" +When the +.BR \(mie +option is specified, the following exit values are returned: +.IP "\00" 6 +Mail was found. +.IP >0 6 +Mail was not found or an error occurred. +.P +Otherwise, the following exit values are returned: +.IP "\00" 6 +Successful completion; note that this status implies that all messages +were +.IR sent , +but it gives no assurances that any of them were actually +.IR delivered . +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When in +input mode (Receive Mode) +or Send Mode: +.IP " *" 4 +If an error is encountered processing an input line beginning +with a + +(\c +.BR '~' ) +character, +(see +.IR "Command Escapes in mailx"), +a diagnostic message shall be written to standard error, and the +message being composed may be modified, but this condition shall not +prevent the message from being sent. +.IP " *" 4 +Other errors shall prevent the sending of the message. +.P +When in command mode: +.IP " *" 4 +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Delivery of messages to remote systems requires the existence of +communication paths to such systems. These need not exist. +.P +Input lines are limited to +{LINE_MAX} +bytes, but mailers between systems may impose more severe line-length +restrictions. This volume of POSIX.1\(hy2008 does not place any restrictions on the length of +messages handled by +.IR mailx , +and for delivery of local messages the only limitations should be the +normal problems of available disk space for the target mail file. When +sending messages to external machines, applications are advised to +limit messages to less than 100\|000 bytes because some mail gateways +impose message-length restrictions. +.P +The format of the system mailbox is intentionally unspecified. Not all +systems implement system mailboxes as flat files, particularly with the +advent of multimedia mail messages. Some system mailboxes may be +multiple files, others records in a database. The internal format of +the messages themselves is specified with the historical format from +Version\ 7, but only after the messages have been saved in some file +other than the system mailbox. This was done so that many historical +applications expecting text-file mailboxes are not broken. +.P +Some new formats for messages can be expected in the future, probably +including binary data, bit maps, and various multimedia objects. As +described here, +.IR mailx +is not prohibited from handling such messages, but it must store them +as text files in secondary mailboxes (unless some extension, such as a +variable or command line option, is used to change the stored format). +Its method of doing so is implementation-defined and might include +translating the data into text file-compatible or readable form or +omitting certain portions of the message from the stored output. +.P +The +.BR discard +and +.BR ignore +commands are not inverses of the +.BR retain +command. The +.BR retain +command discards all header-fields except those explicitly retained. +The +.BR discard +command keeps all header-fields except those explicitly discarded. If +headers exist on the retained header list, +.BR discard +and +.BR ignore +commands are ignored. +.SH EXAMPLES +None. +.SH RATIONALE +The standard developers felt strongly that a method for applications to +send messages to specific users was necessary. The obvious example is a +batch utility, running non-interactively, that wishes to communicate +errors or results to a user. However, the actual format, delivery +mechanism, and method of reading the message are clearly beyond the +scope of this volume of POSIX.1\(hy2008. +.P +The intent of this command is to provide a simple, portable interface +for sending messages non-interactively. It merely defines a +``front-end'' to the historical mail system. It is suggested that +implementations explicitly denote the sender and recipient in the body +of the delivered message. Further specification of formats for either +the message envelope or the message itself were deliberately not made, +as the industry is in the midst of changing from the current standards +to a more internationalized standard and it is probably incorrect, at +this time, to require either one. +.P +Implementations are encouraged to conform to the various delivery +mechanisms described in the CCITT X.400 standards or to the equivalent +Internet standards, described in Internet Request for Comment (RFC) +documents RFC\ 819, RFC\ 822, RFC\ 920, RFC\ 921, and RFC\ 1123. +.P +Many historical systems modified each body line that started with +.BR "From\0" +by prefixing the +.BR 'F' +with +.BR '>' . +It is unnecessary, but allowed, to do that when the string does not +follow a blank line because it cannot be confused with the next +header. +.P +The +.BR edit +and +.BR visual +commands merely edit the specified messages in a temporary file. They +do not modify the contents of those messages in the mailbox; such a +capability could be added as an extension, such as by using different +command names. +.P +The restriction on a subject line being +{LINE_MAX}\(mi10 +bytes is based on the historical format that consumes 10 bytes for +.BR "Subject:\0" +and the trailing +. +Many historical mailers that a message may encounter on other systems +are not able to handle lines that long, however. +.P +Like the utilities +.IR logger +and +.IR lp , +.IR mailx +admittedly is difficult to test. This was not deemed sufficient +justification to exclude this utility from this volume of POSIX.1\(hy2008. It is also arguable +that it is, in fact, testable, but that the tests themselves are not +portable. +.P +When +.IR mailx +is being used by an application that wishes to receive the results as +if none of the User Portability Utilities option features were +supported, the +.IR DEAD +environment variable must be set to +.BR /dev/null . +Otherwise, it may be subject to the file creations described in +.IR mailx +ASYNCHRONOUS EVENTS. Similarly, if the +.IR MAILRC +environment variable is not set to +.BR /dev/null , +historical versions of +.IR mailx +and +.IR Mail +read initialization commands from a file before processing begins. +Since the initialization that a user specifies could alter the contents +of messages an application is trying to send, such applications must +set +.IR MAILRC +to +.BR /dev/null . +.P +The description of +.IR LC_TIME +uses ``may affect'' because many historical implementations do not or +cannot manipulate the date and time strings in the incoming mail +headers. Some headers found in incoming mail do not have enough +information to determine the timezone in which the mail originated, +and, therefore, +.IR mailx +cannot convert the date and time strings into the internal form that +then is parsed by routines like +\fIstrftime\fR() +that can take +.IR LC_TIME +settings into account. Changing all these times to a user-specified +format is allowed, but not required. +.P +The paginator selected when +.IR PAGER +is null or unset is partially unspecified to allow the System V +historical practice of using +.IR pg +as the default. Bypassing the pagination function, such as by declaring +that +.IR cat +is the paginator, would not meet with the intended meaning of this +description. However, any ``portable user'' would have to set +.IR PAGER +explicitly to get his or her preferred paginator on all systems. The +paginator choice was made partially unspecified, unlike the +.IR VISUAL +editor choice (mandated to be +.IR vi ) +because most historical pagers follow a common theme of user input, +whereas editors differ dramatically. +.P +Options to specify addresses as +.BR cc +(carbon copy) or +.BR bcc +(blind carbon copy) were considered to be format details and were +omitted. +.P +A zero exit status implies that all messages were +.IR sent , +but it gives no assurances that any of them were actually +.IR delivered . +The reliability of the delivery mechanism is unspecified and is an +appropriate marketing distinction between systems. +.P +In order to conform to the Utility Syntax Guidelines, a solution was +required to the optional +.IR file +option-argument to +.BR \(mif . +By making +.IR file +an operand, the guidelines are satisfied and users remain portable. +However, it does force implementations to support usage such as: +.sp +.RS 4 +.nf +\fB +mailx \(mifin mymail.box +.fi \fR +.P +.RE +.P +The +.BR no +.IR name +method of unsetting variables is not present in all historical systems, +but it is in System V and provides a logical set of commands +corresponding to the format of the display of options from the +.IR mailx +.IR set +command without arguments. +.P +The +.BR ask +and +.BR asksub +variables are the names selected by BSD and System V, respectively, for +the same feature. They are synonyms in this volume of POSIX.1\(hy2008. +.P +The +.IR mailx +.IR echo +command was not documented in the BSD version and has been omitted here +because it is not obviously useful for interactive users. +.P +The default prompt on the System V +.IR mailx +is a +, +on BSD +.IR Mail +an +. +Since this volume of POSIX.1\(hy2008 chose the +.IR mailx +name, it kept the System V default, assuming that BSD users would not +have difficulty with this minor incompatibility (that they can +override). +.P +The meanings of +.BR r +and +.BR R +are reversed between System V +.IR mailx +and SunOS +.IR Mail . +Once again, since this volume of POSIX.1\(hy2008 chose the +.IR mailx +name, it kept the System V default, but allows the SunOS user to +achieve the desired results using +.BR flipr , +an internal variable in System V +.IR mailx , +although it has not been documented in the SVID. +.P +The +.BR indentprefix +variable, the +.BR retain +and +.BR unalias +commands, and the +.BR ~F +and +.BR ~M +command escapes were adopted from 4.3 BSD +.IR Mail . +.P +The +.BR version +command was not included because no sufficiently general specification +of the version information could be devised that would still be useful +to a portable user. This command name should be used by suppliers who +wish to provide version information about the +.IR mailx +command. +.P +The ``implementation-specific (unspecified) system start-up file'' +historically has been named +.BR /etc/mailx.rc , +but this specific name and location are not required. +.P +The intent of the wording for the +.BR next +command is that if any command has already displayed the current +message it should display a following message, but, otherwise, it +should display the current message. Consider the command sequence: +.sp +.RS 4 +.nf +\fB +next 3 +delete 3 +next +.fi \fR +.P +.RE +.P +where the +.BR autoprint +option was not set. The normative text specifies that the second +.BR next +command should display a message following the third message, because +even though the current message has not been displayed since it was set +by the +.BR delete +command, it has been displayed since the current message was anything +other than message number 3. This does not always match historical +practice in some implementations, where the command file address +followed by +.BR next +(or the default command) would skip the message for which the user had +searched. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIed\fR\^", +.IR "\fIls\fR\^", +.IR "\fImore\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/make.1p b/man-pages-posix-2013-a/man1p/make.1p new file mode 100644 index 0000000..44f900f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/make.1p @@ -0,0 +1,2487 @@ +'\" et +.TH MAKE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +make +\(em maintain, update, and regenerate groups of programs +(\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +make \fB[\fR\(mieinpqrst\fB] [\fR\(mif \fImakefile\fB]\fR... \fB[\fR\(mik|\(miS\fB] [\fImacro\fR=\fIvalue\fR...\fB] + \fB[\fItarget_name\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR make +utility shall update files that are derived from other files. A typical +case is one where object files are derived from the corresponding +source files. The +.IR make +utility examines time relationships and shall update those derived files +(called targets) that have modified times earlier than the modified +times of the files (called prerequisites) from which they are derived. +A description file (makefile) contains a description of the +relationships between files, and the commands that need to be executed +to update the targets to reflect changes in their prerequisites. Each +specification, or rule, shall consist of a target, optional +prerequisites, and optional commands to be executed when a prerequisite +is newer than the target. There are two types of rule: +.IP " 1." 4 +\fIInference rules\fP, +which have one target name with at least one + +(\c +.BR '.' ) +and no + +(\c +.BR '/' ) +.IP " 2." 4 +\fITarget rules\fP, +which can have more than one target name +.P +In addition, +.IR make +shall have a collection of built-in macros and inference rules that +infer prerequisite relationships to simplify maintenance of programs. +.P +To receive exactly the behavior described in this section, the +user shall ensure that a portable makefile shall: +.IP " *" 4 +Include the special target +.BR .POSIX +.IP " *" 4 +Omit any special target reserved for implementations (a leading period +followed by uppercase letters) that has not been specified by this +section +.P +The behavior of +.IR make +is unspecified if either or both of these conditions are not met. +.SH OPTIONS +The +.IR make +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(mie\fP" 10 +Cause environment variables, including those with null values, to +override macro assignments within makefiles. +.IP "\fB\(mif\ \fImakefile\fR" 10 +Specify a different makefile. The argument +.IR makefile +is a pathname of a description file, which is also referred to as the +.IR makefile . +A pathname of +.BR '\(mi' +shall denote the standard input. There can be multiple instances of +this option, and they shall be processed in the order specified. The +effect of specifying the same option-argument more than once is +unspecified. +.IP "\fB\(mii\fP" 10 +Ignore error codes returned by invoked commands. This mode is the same +as if the special target +.BR .IGNORE +were specified without prerequisites. +.IP "\fB\(mik\fP" 10 +Continue to update other targets that do not depend on the current +target if a non-ignored error occurs while executing the commands to +bring a target up-to-date. +.IP "\fB\(min\fP" 10 +Write commands that would be executed on standard output, but do not +execute them. However, lines with a + +(\c +.BR '\(pl' ) +prefix shall be executed. In this mode, lines with an at-sign (\c +.BR '@' ) +character prefix shall be written to standard output. +.IP "\fB\(mip\fP" 10 +Write to standard output the complete set of macro definitions and +target descriptions. The output format is unspecified. +.IP "\fB\(miq\fP" 10 +Return a zero exit value if the target file is up-to-date; otherwise, +return an exit value of 1. Targets shall not be updated if this option +is specified. However, a makefile command line (associated with the +targets) with a + +(\c +.BR '\(pl' ) +prefix shall be executed. +.IP "\fB\(mir\fP" 10 +Clear the suffix list and do not use the built-in rules. +.IP "\fB\(miS\fP" 10 +Terminate +.IR make +if an error occurs while executing the commands to bring a target +up-to-date. This shall be the default and the opposite of +.BR \(mik . +.IP "\fB\(mis\fP" 10 +Do not write makefile command lines or touch messages (see +.BR \(mit ) +to standard output before executing. This mode shall be the same as if +the special target +.BR .SILENT +were specified without prerequisites. +.IP "\fB\(mit\fP" 10 +Update the modification time of each target as though a +.IR touch +.IR target +had been executed. Targets that have prerequisites but no commands (see +.IR "Target Rules"), +or that are already up-to-date, shall not be touched in this manner. +Write messages to standard output for each target file indicating the +name of the file and that it was touched. Normally, the +.IR makefile +command lines associated with each target are not executed. However, a +command line with a + +(\c +.BR '\(pl' ) +prefix shall be executed. +.P +Any options specified in the +.IR MAKEFLAGS +environment variable shall be evaluated before any options specified on +the +.IR make +utility command line. If the +.BR \(mik +and +.BR \(miS +options are both specified on the +.IR make +utility command line or by the +.IR MAKEFLAGS +environment variable, the last option specified shall take precedence. +If the +.BR \(mif +or +.BR \(mip +options appear in the +.IR MAKEFLAGS +environment variable, the result is undefined. +.SH OPERANDS +The following operands shall be supported: +.IP "\fItarget_name\fR" 10 +Target names, as defined in the EXTENDED DESCRIPTION section. If no +target is specified, while +.IR make +is processing the makefiles, the first target that +.IR make +encounters that is not a special target or an inference rule shall be +used. +.IP "\fImacro\fR=\fIvalue\fR" 10 +Macro definitions, as defined in +.IR "Macros". +.P +If the +.IR target_name +and +.IR macro =\c +.IR value +operands are intermixed on the +.IR make +utility command line, the results are unspecified. +.SH STDIN +The standard input shall be used only if the +.IR makefile +option-argument is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input file, otherwise known as the makefile, is a text file +containing rules, macro definitions, and comments. See the +EXTENDED DESCRIPTION section. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR make : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fIMAKEFLAGS\fP" 10 +.br +This variable shall be interpreted as a character string representing a +series of option characters to be used as the default options. The +implementation shall accept both of the following formats (but need not +accept them when intermixed): +.RS 10 +.IP " *" 4 +The characters are option letters without the leading + +characters or + +separation used on a +.IR make +utility command line. +.IP " *" 4 +The characters are formatted in a manner similar to a portion of the +.IR make +utility command line: options are preceded by + +characters and +-separated +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +The +.IR macro =\c +.IR value +macro definition operands can also be included. The difference between +the contents of +.IR MAKEFLAGS +and the +.IR make +utility command line is that the contents of the variable shall not be +subjected to the word expansions (see +.IR "Section 2.6" ", " "Word Expansions") +associated with parsing the command line values. +.RE +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPROJECTDIR\fP" 10 +.br +Provide a directory to be used to search for SCCS files not found in +the current directory. In all of the following cases, the search for +SCCS files is made in the directory +.BR SCCS +in the identified directory. If the value of +.IR PROJECTDIR +begins with a +, +it shall be considered an absolute pathname; otherwise, the value of +.IR PROJECTDIR +is treated as a user name and that user's initial working directory +shall be examined for a subdirectory +.BR src +or +.BR source . +If such a directory is found, it shall be used. Otherwise, the value +is used as a relative pathname. +.RS 10 +.P +If +.IR PROJECTDIR +is not set or has a null value, the search for SCCS files shall be made +in the directory +.BR SCCS +in the current directory. +.P +The setting of +.IR PROJECTDIR +affects all files listed in the remainder of this utility description +for files with a component named +.BR SCCS . +.RE +.P +The value of the +.IR SHELL +environment variable shall not be used as a macro and shall not be +modified by defining the +.BR SHELL +macro in a makefile or on the command line. All other environment +variables, including those with null values, shall be used as macros, +as defined in +.IR "Macros". +.SH "ASYNCHRONOUS EVENTS" +If not already ignored, +.IR make +shall trap SIGHUP, SIGTERM, SIGINT, and SIGQUIT and remove the current +target unless the target is a directory or the target is a prerequisite +of the special target +.BR .PRECIOUS +or unless one of the +.BR \(min , +.BR \(mip , +or +.BR \(miq +options was specified. Any targets removed in this manner shall be +reported in diagnostic messages of unspecified format, written to +standard error. After this cleanup process, if any, +.IR make +shall take the standard action for all other signals. +.SH STDOUT +The +.IR make +utility shall write all commands to be executed to standard output +unless the +.BR \(mis +option was specified, the command is prefixed with an at-sign, or the +special target +.BR .SILENT +has either the current target as a prerequisite or has no +prerequisites. If +.IR make +is invoked without any work needing to be done, it shall write a +message to standard output indicating that no action was taken. If the +.BR \(mit +option is present and a file is touched, +.IR make +shall write to standard output a message of unspecified format +indicating that the file was touched, including the filename of the +file. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Files can be created when the +.BR \(mit +option is present. Additional files can also be created by the +utilities invoked by +.IR make . +.SH "EXTENDED DESCRIPTION" +The +.IR make +utility attempts to perform the actions required to ensure that the +specified targets are up-to-date. A target is considered out-of-date +if it is older than any of its prerequisites or if it does not exist. +The +.IR make +utility shall treat all prerequisites as targets themselves and +recursively ensure that they are up-to-date, processing them in the +order in which they appear in the rule. The +.IR make +utility shall use the modification times of files to determine whether +the corresponding targets are out-of-date. +.P +After +.IR make +has ensured that all of the prerequisites of a target are up-to-date +and if the target is out-of-date, the commands associated with the +target entry shall be executed. If there are no commands listed for +the target, the target shall be treated as up-to-date. +.SS "Makefile Syntax" +.P +A makefile can contain rules, macro definitions (see +.IR "Macros"), +include lines, and comments. There are two kinds of rules: +.IR "inference rules" +and +.IR "target rules" . +The +.IR make +utility shall contain a set of built-in inference rules. If the +.BR \(mir +option is present, the built-in rules shall not be used and the suffix +list shall be cleared. Additional rules of both types can be specified +in a makefile. If a rule is defined more than once, the value of the +rule shall be that of the last one specified. Macros can also be +defined more than once, and the value of the macro is specified in +.IR "Macros". +Comments start with a + +(\c +.BR '#' ) +and continue until an unescaped + +is reached. +.P +By default, the following files shall be tried in sequence: +.BR ./makefile +and +.BR ./Makefile . +If neither +.BR ./makefile +or +.BR ./Makefile +are found, other implementation-defined files may also be tried. +On XSI-conformant systems, the additional files +.BR ./s.makefile , +.BR SCCS/s.makefile , +.BR ./s.Makefile , +and +.BR SCCS/s.Makefile +shall also be tried. +.P +The +.BR \(mif +option shall direct +.IR make +to ignore any of these default files and use the specified argument as +a makefile instead. If the +.BR '\(mi' +argument is specified, standard input shall be used. +.P +The term +.IR makefile +is used to refer to any rules provided by the user, whether in +.BR ./makefile +or its variants, or specified by the +.BR \(mif +option. +.P +The rules in makefiles shall consist of the following types of lines: +target rules, including special targets (see +.IR "Target Rules"), +inference rules (see +.IR "Inference Rules"), +macro definitions (see +.IR "Macros"), +empty lines, and comments. +.P +Target and Inference Rules may contain +.IR "command lines" . +Command lines can have a prefix that shall be removed before +execution (see +.IR "Makefile Execution"). +.P +When an escaped + +(one preceded by a +) +is found anywhere in the makefile except in a command line, an include +line, or a line immediately preceding an include line, it shall be +replaced, along with any leading white space on the following line, +with a single +. +When an escaped + +is found in a command line in a makefile, the command line shall +contain the +, +the +, +and the next line, except that the first character of the next line +shall not be included if it is a +. +When an escaped + +is found in an include line or in a line immediately preceding an +include line, the behavior is unspecified. +.SS "Include Lines" +.P +If the word +.BR include +appears at the beginning of a line and is followed by one or more + +characters, the string formed by the remainder of the line shall be +processed as follows to produce a pathname: +.IP " *" 4 +The trailing + +and any comment shall be discarded. If the resulting string contains +any double-quote characters (\c +.BR '\&"' ) +the behavior is unspecified. +.IP " *" 4 +The resulting string shall be processed for macro expansion (see +.IR "Macros". +.IP " *" 4 +Any + +characters that appear after the first non-\c + +shall be used as separators to divide the macro-expanded string into +fields. It is unspecified whether any other white-space characters +are also used as separators. It is unspecified whether pathname +expansion (see +.IR "Section 2.13" ", " "Pattern Matching Notation") +is also performed. +.IP " *" 4 +If the processing of separators and optional pathname expansion +results in either zero or two or more non-empty fields, the +behavior is unspecified. If it results in one non-empty field, +that field is taken as the pathname. +.P +If the pathname does not begin with a +.BR '/' +it shall be treated as relative to the current working directory +of the process, not relative to the directory containing the makefile. +If the file does not exist in this location, it is unspecified whether +additional directories are searched. +.P +The contents of the file specified by the pathname shall be read +and processed as if they appeared in the makefile in place of the +include line. If the file ends with an escaped + +the behavior is unspecified. +.P +The file may itself contain further include lines. Implementations +shall support nesting of include files up to a depth of at least 16. +.SS "Makefile Execution" +.P +Makefile command lines shall be processed one at a time. +.P +Makefile command lines can have one or more of the following prefixes: a + +(\c +.BR '-' ), +an at-sign (\c +.BR '@' ), +or a + +(\c +.BR '+' ). +These shall modify the way in which +.IR make +processes the command. +.IP "\fR\(mi\fR" 6 +If the command prefix contains a +, +or the +.BR \(mii +option is present, or the special target +.BR .IGNORE +has either the current target as a prerequisite or has no prerequisites, +any error found while executing the command shall be ignored. +.IP "\fR@\fR" 6 +If the command prefix contains an at-sign and the +.IR make +utility command line +.BR \(min +option is not specified, or the +.BR \(mis +option is present, or the special target +.BR .SILENT +has either the current target as a prerequisite or has no prerequisites, +the command shall not be written to standard output before it is executed. +.IP "\fR+\fR" 6 +If the command prefix contains a +, +this indicates a makefile command line that shall be executed even if +.BR \(min , +.BR \(miq , +or +.BR \(mit +is specified. +.P +An +.IR "execution line" +is built from the command line by removing any prefix characters. Except +as described under the at-sign prefix, the execution line shall be +written to the standard output, optionally preceded by a +. +The execution line shall then be executed by a shell as if it were passed +as the argument to the +\fIsystem\fR() +interface, except that if errors are not being ignored then the shell +.BR \(mie +option shall also be in effect. If errors are being ignored for the +command (as a result of the +.BR \(mii +option, a +.BR '\(mi' +command prefix, or a +.BR .IGNORE +special target), the shell +.BR \(mie +option shall not be in effect. The environment for the command being +executed shall contain all of the variables in the environment of +.IR make . +.P +By default, when +.IR make +receives a non-zero status from the execution of a command, it shall +terminate with an error message to standard error. +.SS "Target Rules" +.P +Target rules are formatted as follows: +.sp +.RS 4 +.nf +\fB +\fItarget \fB[\fItarget\fR...\fB]\fR: \fB[\fIprerequisite\fR...\fB][;\fIcommand\fB] +[\fR\fIcommand\fR +\fIcommand\fR +\&...\fB]\fR +.P +\fIline that does not begin with \fR +.fi \fR +.P +.RE +.P +Target entries are specified by a +-separated, +non-null list of targets, then a +, +then a +-separated, +possibly empty list of prerequisites. Text following a +, +if any, and all following lines that begin with a +, +are makefile command lines to be executed to update the target. The +first non-empty line that does not begin with a + +or +.BR '#' +shall begin a new entry. An empty or blank line, or a line beginning +with +.BR '#' , +may begin a new entry. +.P +Applications shall select target names from the set of characters +consisting solely of periods, underscores, digits, and alphabetics from +the portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +Implementations may allow other characters in target names as +extensions. The interpretation of targets containing the characters +.BR '%' +and +.BR '\&"' +is implementation-defined. +.P +A target that has prerequisites, but does not have any commands, can be +used to add to the prerequisite list for that target. Only one target +rule for any given target can contain commands. +.P +Lines that begin with one of the following are called +.IR "special targets" +and control the operation of +.IR make : +.IP "\&\fB.DEFAULT\fR" 10 +If the makefile uses this special target, the application shall ensure +that it is specified with commands, but without prerequisites. The +commands shall be used by +.IR make +if there are no other rules available to build a target. +.IP "\&\fB.IGNORE\fR" 10 +Prerequisites of this special target are targets themselves; this shall +cause errors from commands associated with them to be ignored in the +same manner as specified by the +.BR \(mii +option. Subsequent occurrences of +.BR .IGNORE +shall add to the list of targets ignoring command errors. If no +prerequisites are specified, +.IR make +shall behave as if the +.BR \(mii +option had been specified and errors from all commands associated with +all targets shall be ignored. +.IP "\&\fB.POSIX\fR" 10 +The application shall ensure that this special target is specified +without prerequisites or commands. If it appears as the first +non-comment line in the makefile, +.IR make +shall process the makefile as specified by this section; otherwise, the +behavior of +.IR make +is unspecified. +.IP "\&\fB.PRECIOUS\fR" 10 +Prerequisites of this special target shall not be removed if +.IR make +receives one of the asynchronous events explicitly described in the +ASYNCHRONOUS EVENTS section. Subsequent occurrences of +.BR .PRECIOUS +shall add to the list of precious files. If no prerequisites are +specified, all targets in the makefile shall be treated as if specified +with +.BR .PRECIOUS . +.IP "\fB.SCCS_GET\fR" 10 +The application shall ensure that this special target is specified +without prerequisites. If this special target is included in a +makefile, the commands specified with this target shall replace the +default commands associated with this special target (see +.IR "Default Rules"). +The commands specified with this target are used to get all SCCS files +that are not found in the current directory. +.RS 10 +.P +When source files are named in a dependency list, +.IR make +shall treat them just like any other target. Because the source file is +presumed to be present in the directory, there is no need to add an +entry for it to the makefile. When a target has no dependencies, but is +present in the directory, +.IR make +shall assume that that file is up-to-date. If, however, an SCCS file +named +.BR SCCS/s. \c +.IR source_file +is found for a target +.IR source_file , +.IR make +compares the timestamp of the target file with that of the +.BR SCCS/s.source_file +to ensure the target is up-to-date. If the target is missing, or if the +SCCS file is newer, +.IR make +shall automatically issue the commands specified for the +.BR .SCCS_GET +special target to retrieve the most recent version. However, if the +target is writable by anyone, +.IR make +shall not retrieve a new version. +.RE +.IP "\&\fB.SILENT\fR" 10 +Prerequisites of this special target are targets themselves; this shall +cause commands associated with them not to be written to the standard +output before they are executed. Subsequent occurrences of +.BR .SILENT +shall add to the list of targets with silent commands. If no +prerequisites are specified, +.IR make +shall behave as if the +.BR \(mis +option had been specified and no commands or touch messages associated +with any target shall be written to standard output. +.IP "\&\fB.SUFFIXES\fR" 10 +Prerequisites of +.BR .SUFFIXES +shall be appended to the list of known suffixes and are used in +conjunction with the inference rules (see +.IR "Inference Rules"). +If +.BR .SUFFIXES +does not have any prerequisites, the list of known suffixes shall be +cleared. +.P +The special targets +.BR .IGNORE , +.BR .POSIX , +.BR .PRECIOUS , +.BR .SILENT , +and +.BR .SUFFIXES +shall be specified without commands. +.P +Targets with names consisting of a leading + +followed by the uppercase letters +.BR \(dqPOSIX\(dq +and then any other characters are reserved for future standardization. +Targets with names consisting of a leading + +followed by one or more uppercase letters are reserved for implementation +extensions. +.SS "Macros" +.P +Macro definitions are in the form: +.sp +.RS 4 +.nf +\fB +\fIstring1\fR = \fB[\fIstring2\fB]\fR +.fi \fR +.P +.RE +.P +The macro named +.IR string1 +is defined as having the value of +.IR string2 , +where +.IR string2 +is defined as all characters, if any, after the +, +up to a comment character (\c +.BR '#' ) +or an unescaped +. +Any + +characters immediately before or after the + +shall be ignored. +.P +Applications shall select macro names from the set of characters +consisting solely of periods, underscores, digits, and alphabetics from +the portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +A macro name shall not contain an +. +Implementations may allow other characters in macro names as extensions. +.P +Macros can appear anywhere in the makefile. Macro expansions using +the forms $(\c +.IR string1 ) +or ${\c +.IR string1 } +shall be replaced by +.IR string2 , +as follows: +.IP " *" 4 +Macros in target lines shall be evaluated when the target line is read. +.IP " *" 4 +Macros in makefile command lines shall be evaluated when the command is +executed. +.IP " *" 4 +Macros in the string before the + +in a macro definition shall be evaluated when the macro assignment +is made. +.IP " *" 4 +Macros after the + +in a macro definition shall not be evaluated until the defined macro +is used in a rule or command, or before the + +in a macro definition. +.P +The parentheses or braces are optional if +.IR string1 +is a single character. The macro $$ shall be replaced by the single +character +.BR '$' . +If +.IR string1 +in a macro expansion contains a macro expansion, the results are +unspecified. +.P +Macro expansions using the forms $(\c +.IR string1 \c +.BR [: \c +.IR subst1 \c +.BR =[ \c +.IR subst2 \c +.BR ]] ) +or ${\c +.IR string1 \c +.BR [: \c +.IR subst1 \c +.BR =[ \c +.IR subst2 \c +.BR ]] } +can be used to replace all occurrences of +.IR subst1 +with +.IR subst2 +when the macro substitution is performed. The +.IR subst1 +to be replaced shall be recognized when it is a suffix at the end of a +word in +.IR string1 +(where a +.IR word , +in this context, is defined to be a string delimited by the beginning +of the line, a +, +or a +). +If +.IR string1 +in a macro expansion contains a macro expansion, the results are +unspecified. +.P +Macro expansions in +.IR string1 +of macro definition lines shall be evaluated when read. Macro +expansions in +.IR string2 +of macro definition lines shall be performed when the macro identified +by +.IR string1 +is expanded in a rule or command. +.P +Macro definitions shall be taken from the following sources, in the +following logical order, before the makefile(s) are read. +.IP " 1." 4 +Macros specified on the +.IR make +utility command line, in the order specified on the command line. It is +unspecified whether the internal macros defined in +.IR "Internal Macros" +are accepted from this source. +.IP " 2." 4 +Macros defined by the +.IR MAKEFLAGS +environment variable, in the order specified in the environment +variable. It is unspecified whether the internal macros defined in +.IR "Internal Macros" +are accepted from this source. +.IP " 3." 4 +The contents of the environment, excluding the +.IR MAKEFLAGS +and +.IR SHELL +variables and including the variables with null values. +.IP " 4." 4 +Macros defined in the inference rules built into +.IR make . +.P +Macro definitions from these sources shall not override macro +definitions from a lower-numbered source. Macro definitions from a +single source (for example, the +.IR make +utility command line, the +.IR MAKEFLAGS +environment variable, or the other environment variables) shall +override previous macro definitions from the same source. +.P +Macros defined in the makefile(s) shall override macro definitions that +occur before them in the makefile(s) and macro definitions from source +4. If the +.BR \(mie +option is not specified, macros defined in the makefile(s) shall +override macro definitions from source 3. Macros defined in the +makefile(s) shall not override macro definitions from source 1 or +source 2. +.P +Before the makefile(s) are read, all of the +.IR make +utility command line options (except +.BR \(mif +and +.BR \(mip ) +and +.IR make +utility command line macro definitions (except any for the +.IR MAKEFLAGS +macro), not already included in the +.IR MAKEFLAGS +macro, shall be added to the +.IR MAKEFLAGS +macro, quoted in an implementation-defined manner such that when +.IR MAKEFLAGS +is read by another instance of the +.IR make +command, the original macro's value is recovered. Other +implementation-defined options and macros may also be added to the +.IR MAKEFLAGS +macro. If this modifies the value of the +.IR MAKEFLAGS +macro, or, if the +.IR MAKEFLAGS +macro is modified at any subsequent time, the +.IR MAKEFLAGS +environment variable shall be modified to match the new value of the +.IR MAKEFLAGS +macro. The result of setting +.IR MAKEFLAGS +in the Makefile is unspecified. +.P +Before the makefile(s) are read, all of the +.IR make +utility command line macro definitions (except the +.IR MAKEFLAGS +macro or the +.IR SHELL +macro) shall be added to the environment of +.IR make . +Other implementation-defined variables may also be added to the +environment of +.IR make . +.P +The +.BR SHELL +macro shall be treated specially. It shall be provided by +.IR make +and set to the pathname of the shell command language interpreter (see +.IR "\fIsh\fR\^"). +The +.IR SHELL +environment variable shall not affect the value of the +.BR SHELL +macro. If +.BR SHELL +is defined in the makefile or is specified on the command line, it +shall replace the original value of the +.BR SHELL +macro, but shall not affect the +.IR SHELL +environment variable. Other effects of defining +.BR SHELL +in the makefile or on the command line are implementation-defined. +.SS "Inference Rules" +.P +Inference rules are formatted as follows: +.sp +.RS 4 +.nf +\fB +\fItarget\fR: +\fIcommand +\fB[\fR\fIcommand\fB]\fR +\&... +.P +\fIline that does not begin with \fR\fI or \fR# +.fi \fR +.P +.RE +.P +The application shall ensure that the +.IR target +portion is a valid target name (see +.IR "Target Rules") +of the form +.BR .s2 +or +.BR .s1.s2 +(where +.BR .s1 +and +.BR .s2 +are suffixes that have been given as prerequisites of the +.BR .SUFFIXES +special target and +.IR s1 +and +.IR s2 +do not contain any + +or + +characters.) If there is only one + +in the target, it is a single-suffix inference rule. Targets with two +periods are double-suffix inference rules. Inference rules can have +only one target before the +. +.P +The application shall ensure that the makefile does not specify +prerequisites for inference rules; no characters other than white space +shall follow the + +in the first line, except when creating the +.IR "empty rule," +described below. Prerequisites are inferred, as described below. +.P +Inference rules can be redefined. A target that matches an existing +inference rule shall overwrite the old inference rule. An empty rule +can be created with a command consisting of simply a + +(that is, the rule still exists and is found during inference rule search, +but since it is empty, execution has no effect). The empty rule can also +be formatted as follows: +.sp +.RS 4 +.nf +\fB +\fIrule\fR: ; +.fi \fR +.P +.RE +.P +where zero or more + +characters separate the + +and +. +.P +The +.IR make +utility uses the suffixes of targets and their prerequisites to infer +how a target can be made up-to-date. A list of inference rules defines +the commands to be executed. By default, +.IR make +contains a built-in set of inference rules. Additional rules can be +specified in the makefile. +.P +The special target +.BR .SUFFIXES +contains as its prerequisites a list of suffixes that shall be used by +the inference rules. The order in which the suffixes are specified +defines the order in which the inference rules for the suffixes are +used. New suffixes shall be appended to the current list by specifying +a +.BR .SUFFIXES +special target in the makefile. A +.BR .SUFFIXES +target with no prerequisites shall clear the list of suffixes. An +empty +.BR .SUFFIXES +target followed by a new +.BR .SUFFIXES +list is required to change the order of the suffixes. +.P +Normally, the user would provide an inference rule for each suffix. +The inference rule to update a target with a suffix +.BR .s1 +from a prerequisite with a suffix +.BR .s2 +is specified as a target +.BR .s2.s1 . +The internal macros provide the means to specify general inference +rules (see +.IR "Internal Macros"). +.P +When no target rule is found to update a target, the inference rules +shall be checked. The suffix of the target (\c +.BR .s1 ) +to be built is compared to the list of suffixes specified by the +.BR .SUFFIXES +special targets. If the +.BR .s1 +suffix is found in +.BR .SUFFIXES , +the inference rules shall be searched in the order defined for the +first +.BR .s2.s1 +rule whose prerequisite file (\c +.BR $*.s2 ) +exists. If the target is out-of-date with respect to this +prerequisite, the commands for that inference rule shall be executed. +.P +If the target to be built does not contain a suffix and there is no +rule for the target, the single suffix inference rules shall be +checked. The single-suffix inference rules define how to build a +target if a file is found with a name that matches the target name with +one of the single suffixes appended. A rule with one suffix +.BR .s2 +is the definition of how to build +.IR target +from +.BR target.s2 . +The other suffix (\c +.BR .s1 ) +is treated as null. +.P +A + +(\c +.BR '~' ) +in the above rules refers to an SCCS file in the current directory. +Thus, the rule +.BR .c~.o +would transform an SCCS C-language source file into an object file (\c +.BR .o ). +Because the +.BR s. +of the SCCS files is a prefix, it is incompatible with +.IR make 's +suffix point of view. Hence, the +.BR '~' +is a way of changing any file reference into an SCCS file reference. +.SS "Libraries" +.P +If a target or prerequisite contains parentheses, it shall be treated +as a member of an archive library. For the +.IR lib (\c +.IR member \c +.BR .o ) +expression +.IR lib +refers to the name of the archive library and +.IR member \c +.BR .o +to the member name. The application shall ensure that the member is an +object file with the +.BR .o +suffix. The modification time of the expression is the modification +time for the member as kept in the archive library; see +.IR "\fIar\fR\^". +The +.BR .a +suffix shall refer to an archive library. The +.BR .s2.a +rule shall be used to update a member in the library from a file +with a suffix +.BR .s2 . +.SS "Internal Macros" +.P +The +.IR make +utility shall maintain five internal macros that can be used in target +and inference rules. In order to clearly define the meaning of these +macros, some clarification of the terms +.IR "target rule" , +.IR "inference rule" , +.IR target , +and +.IR prerequisite +is necessary. +.P +Target rules are specified by the user in a makefile for a particular +target. Inference rules are user-specified or +.IR make -specified +rules for a particular class of target name. Explicit prerequisites +are those prerequisites specified in a makefile on target lines. +Implicit prerequisites are those prerequisites that are generated when +inference rules are used. Inference rules are applied to implicit +prerequisites or to explicit prerequisites that do not have target +rules defined for them in the makefile. Target rules are applied to +targets specified in the makefile. +.P +Before any target in the makefile is updated, each of its prerequisites +(both explicit and implicit) shall be updated. This shall be +accomplished by recursively processing each prerequisite. Upon +recursion, each prerequisite shall become a target itself. Its +prerequisites in turn shall be processed recursively until a target is +found that has no prerequisites, at which point the recursion stops. +The recursion shall then back up, updating each target as it goes. +.P +In the definitions that follow, the word +.IR target +refers to one of: +.IP " *" 4 +A target specified in the makefile +.IP " *" 4 +An explicit prerequisite specified in the makefile that becomes the +target when +.IR make +processes it during recursion +.IP " *" 4 +An implicit prerequisite that becomes a target when +.IR make +processes it during recursion +.P +In the definitions that follow, the word +.IR prerequisite +refers to one of the following: +.IP " *" 4 +An explicit prerequisite specified in the makefile for a particular +target +.IP " *" 4 +An implicit prerequisite generated as a result of locating an +appropriate inference rule and corresponding file that matches the +suffix of the target +.P +The five internal macros are: +.IP $@ 8 +The $@ shall evaluate to the full target name of the current target, or +the archive filename part of a library archive target. It shall be +evaluated for both target and inference rules. +.RS 8 +.P +For example, in the +.BR .c.a +inference rule, $@ represents the out-of-date +.BR .a +file to be built. Similarly, in a makefile target rule to build +.BR lib.a +from +.BR file.c , +$@ represents the out-of-date +.BR lib.a . +.RE +.IP $% 8 +The $% macro shall be evaluated only when the current target is an +archive library member of the form +.IR libname (\c +.IR member \c +.BR .o ). +In these cases, $@ shall evaluate to +.IR libname +and $% shall evaluate to +.IR member \c +.BR .o . +The $% macro shall be evaluated for both target and inference rules. +.RS 8 +.P +For example, in a makefile target rule to build +.BR lib.a (\c +.BR file.o ), +$% represents +.BR file.o , +as opposed to $@, which represents +.BR lib.a . +.RE +.IP $? 8 +The $? macro shall evaluate to the list of prerequisites that are +newer than the current target. It shall be evaluated for both target +and inference rules. +.RS 8 +.P +For example, in a makefile target rule to build +.IR prog +from +.BR file1.o , +.BR file2.o , +and +.BR file3.o , +and where +.IR prog +is not out-of-date with respect to +.BR file1.o , +but is out-of-date with respect to +.BR file2.o +and +.BR file3.o , +$? represents +.BR file2.o +and +.BR file3.o . +.RE +.IP $< 8 +In an inference rule, the $< macro shall evaluate to the filename +whose existence allowed the inference rule to be chosen for the target. +In the +.BR .DEFAULT +rule, the $< macro shall evaluate to the current target name. The +meaning of the $< macro shall be otherwise unspecified. +.RS 8 +.P +For example, in the +.BR .c.a +inference rule, $< represents the prerequisite +.BR .c +file. +.RE +.IP $* 8 +The $* macro shall evaluate to the current target name with its suffix +deleted. It shall be evaluated at least for inference rules. +.RS 8 +.P +For example, in the +.BR .c.a +inference rule, $*.o represents the out-of-date +.BR .o +file that corresponds to the prerequisite +.BR .c +file. +.RE +.P +Each of the internal macros has an alternative form. When an uppercase +.BR 'D' +or +.BR 'F' +is appended to any of the macros, the meaning shall be changed to the +.IR "directory part" +for +.BR 'D' +and +.IR "filename part" +for +.BR 'F' . +The directory part is the path prefix of the file without a trailing +; +for the current directory, the directory part is +.BR '.' . +When the $? macro contains more than one prerequisite filename, the +$(?D) and $(?F) (or ${?D} and ${?F}) macros expand to a list of +directory name parts and filename parts respectively. +.P +For the target +.IR lib (\c +.IR member \c +.BR .o ) +and the +.BR s2.a +rule, the internal macros shall be defined as: +.IP $< 8 +.IR member \c +.BR .s2 +.IP $* 8 +.IR member +.IP $@ 8 +.IR lib +.IP $? 8 +.IR member \c +.BR .s2 +.IP $% 8 +.IR member \c +.BR .o +.SS "Default Rules" +.P +The default rules for +.IR make +shall achieve results that are the same as if the following were used. +Implementations that do not support the C-Language Development +Utilities option may omit +.BR CC , +.BR CFLAGS , +.BR YACC , +.BR YFLAGS , +.BR LEX , +.BR LFLAGS , +.BR LDFLAGS , +and the +.BR .c , +.BR .y , +and +.BR .l +inference rules. Implementations that do not support FORTRAN may omit +.BR FC , +.BR FFLAGS , +and the +.BR .f +inference rules. Implementations may provide additional macros and +rules. +.sp +.RS 4 +.nf +\fB +\fISPECIAL TARGETS\fP +.P +\&.SCCS_GET: sccs $(SCCSFLAGS) get $(SCCSGETFLAGS) $@ +.P +\&.SUFFIXES: .o .c .y .l .a .sh .f .c~ .y~ .l~ .sh~ .f~ +.P +.IR MACROS +.P +MAKE=make +AR=ar +ARFLAGS=\(mirv +YACC=yacc +YFLAGS= +LEX=lex +LFLAGS= +LDFLAGS= +CC=c99 +CFLAGS=\(miO +FC=fort77 +FFLAGS=\(miO 1 +GET=get +GFLAGS= +SCCSFLAGS= +SCCSGETFLAGS=\(mis +.P +\fISINGLE SUFFIX RULES\fP +.P +\&.c: + $(CC) $(CFLAGS) $(LDFLAGS) \(mio $@ $< +.P +\&.f: + $(FC) $(FFLAGS) $(LDFLAGS) \(mio $@ $< +.P +\&.sh: + cp $< $@ + chmod a+x $@ +.P +\&.c~: + $(GET) $(GFLAGS) \(mip $< > $*.c + $(CC) $(CFLAGS) $(LDFLAGS) \(mio $@ $*.c +.P +\&.f~: + $(GET) $(GFLAGS) \(mip $< > $*.f + $(FC) $(FFLAGS) $(LDFLAGS) \(mio $@ $*.f +.P +\&.sh~: + $(GET) $(GFLAGS) \(mip $< > $*.sh + cp $*.sh $@ + chmod a+x $@ +.P +\fIDOUBLE SUFFIX RULES\fP +.P +\&.c.o: + $(CC) $(CFLAGS) \(mic $< +.P +\&.f.o: + $(FC) $(FFLAGS) \(mic $< +.P +\&.y.o: + $(YACC) $(YFLAGS) $< + $(CC) $(CFLAGS) \(mic y.tab.c + rm \(mif y.tab.c + mv y.tab.o $@ +.P +\&.l.o: + $(LEX) $(LFLAGS) $< + $(CC) $(CFLAGS) \(mic lex.yy.c + rm \(mif lex.yy.c + mv lex.yy.o $@ +.P +\&.y.c: + $(YACC) $(YFLAGS) $< + mv y.tab.c $@ +.P +\&.l.c: + $(LEX) $(LFLAGS) $< + mv lex.yy.c $@ +.P +\&.c~.o: + $(GET) $(GFLAGS) \(mip $< > $*.c + $(CC) $(CFLAGS) \(mic $*.c +.P +\&.f~.o: + $(GET) $(GFLAGS) \(mip $< > $*.f + $(FC) $(FFLAGS) \(mic $*.f +.P +\&.y~.o: + $(GET) $(GFLAGS) \(mip $< > $*.y + $(YACC) $(YFLAGS) $*.y + $(CC) $(CFLAGS) \(mic y.tab.c + rm \(mif y.tab.c + mv y.tab.o $@ +.P +\&.l~.o: + $(GET) $(GFLAGS) \(mip $< > $*.l + $(LEX) $(LFLAGS) $*.l + $(CC) $(CFLAGS) \(mic lex.yy.c + rm \(mif lex.yy.c + mv lex.yy.o $@ +.P +\&.y~.c: + $(GET) $(GFLAGS) \(mip $< > $*.y + $(YACC) $(YFLAGS) $*.y + mv y.tab.c $@ +.P +\&.l~.c: + $(GET) $(GFLAGS) \(mip $< > $*.l + $(LEX) $(LFLAGS) $*.l + mv lex.yy.c $@ +.P +\&.c.a: + $(CC) \(mic $(CFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm \(mif $*.o +.P +\&.f.a: + $(FC) \(mic $(FFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm \(mif $*.o +.fi \fR +.P +.RE +.SH "EXIT STATUS" +When the +.BR \(miq +option is specified, the +.IR make +utility shall exit with one of the following values: +.IP "\00" 6 +Successful completion. +.IP "\01" 6 +The target was not up-to-date. +.IP >1 6 +An error occurred. +.P +When the +.BR \(miq +option is not specified, the +.IR make +utility shall exit with one of the following values: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If there is a source file (such as +.BR ./source.c ) +and there are two SCCS files corresponding to it (\c +.BR ./s.source.c +and +.BR ./SCCS/s.source.c ), +on XSI-conformant systems +.IR make +uses the SCCS file in the current directory. However, users are +advised to use the underlying SCCS utilities (\c +.IR admin , +.IR delta , +.IR get , +and so on) or the +.IR sccs +utility for all source files in a given directory. If both forms are +used for a given source file, future developers are very likely to be +confused. +.P +It is incumbent upon portable makefiles to specify the +.BR .POSIX +special target in order to guarantee that they are not affected by +local extensions. +.P +The +.BR \(mik +and +.BR \(miS +options are both present so that the relationship between the command +line, the +.IR MAKEFLAGS +variable, and the makefile can be controlled precisely. If the +.BR k +flag is passed in +.IR MAKEFLAGS +and a command is of the form: +.sp +.RS 4 +.nf +\fB +$(MAKE) \(miS foo +.fi \fR +.P +.RE +.P +then the default behavior is restored for the child +.IR make . +.P +When the +.BR \(min +option is specified, it is always added to +.IR MAKEFLAGS . +This allows a recursive +.IR make +.BR \(min +.IR target +to be used to see all of the action that would be taken to update +.IR target . +.P +Because of widespread historical practice, interpreting a + +(\c +.BR '#' ) +inside a variable as the start of a comment has the unfortunate +side-effect of making it impossible to place a + +in a variable, thus forbidding something like: +.sp +.RS 4 +.nf +\fB +CFLAGS = "\(miD COMMENT_CHAR='#'" +.fi \fR +.P +.RE +.P +Many historical +.IR make +utilities stop chaining together inference rules when an intermediate +target is nonexistent. For example, it might be possible for a +.IR make +to determine that both +.BR .y.c +and +.BR .c.o +could be used to convert a +.BR .y +to a +.BR .o . +Instead, in this case, +.IR make +requires the use of a +.BR .y.o +rule. +.P +The best way to provide portable makefiles is to include all of the +rules needed in the makefile itself. The rules provided use only +features provided by other parts of this volume of POSIX.1\(hy2008. The default rules include +rules for optional commands in this volume of POSIX.1\(hy2008. Only rules pertaining to commands +that are provided are needed in an implementation's default set. +.P +Macros used within other macros are evaluated when the new macro is +used rather than when the new macro is defined. Therefore: +.sp +.RS 4 +.nf +\fB +MACRO = \fIvalue1\fP +NEW = $(MACRO) +MACRO = \fIvalue2\fP +.P +target: + echo $(NEW) +.fi \fR +.P +.RE +.P +would produce +.IR value2 +and not +.IR value1 +since +.BR NEW +was not expanded until it was needed in the +.IR echo +command line. +.P +Some historical applications have been known to intermix +.IR target_name +and +.IR macro=name +operands on the command line, expecting that all of the macros are +processed before any of the targets are dealt with. Conforming +applications do not do this, although some backwards-compatibility +support may be included in some implementations. +.P +The following characters in filenames may give trouble: +.BR '=' , +.BR ':' , +.BR '`' , +single-quote, and +.BR '@' . +In include filenames, pattern matching characters and +.BR '\&"' +should also be avoided, as they may be treated as special by some +implementations. +.P +For inference rules, the description of $< and $? seem similar. However, +an example shows the minor difference. In a makefile containing: +.sp +.RS 4 +.nf +\fB +foo.o: foo.h +.fi \fR +.P +.RE +.P +if +.BR foo.h +is newer than +.BR foo.o , +yet +.BR foo.c +is older than +.BR foo.o , +the built-in rule to make +.BR foo.o +from +.BR foo.c +is used, with $< equal to +.BR foo.c +and $? equal to +.BR foo.h . +If +.BR foo.c +is also newer than +.BR foo.o , +$< is equal to +.BR foo.c +and $? is equal to +.BR "foo.h foo.c" . +.SH EXAMPLES +.IP " 1." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +make +.fi \fR +.P +.RE +.P +makes the first target found in the makefile. +.RE +.IP " 2." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +make junk +.fi \fR +.P +.RE +.P +makes the target +.BR junk . +.RE +.IP " 3." 4 +The following makefile says that +.BR pgm +depends on two files, +.BR a.o +and +.BR b.o , +and that they in turn depend on their corresponding source files (\c +.BR a.c +and +.BR b.c ), +and a common file +.BR incl.h : +.RS 4 +.sp +.RS 4 +.nf +\fB +pgm: a.o b.o + c99 a.o b.o \(mio pgm +a.o: incl.h a.c + c99 \(mic a.c +b.o: incl.h b.c + c99 \(mic b.c +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +An example for making optimized +.BR .o +files from +.BR .c +files is: +.RS 4 +.sp +.RS 4 +.nf +\fB +\&.c.o: + c99 \(mic \(miO $*.c +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +\&.c.o: + c99 \(mic \(miO $< +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +The most common use of the archive interface follows. Here, it is +assumed that the source files are all C-language source: +.RS 4 +.sp +.RS 4 +.nf +\fB +lib: lib(file1.o) lib(file2.o) lib(file3.o) + @echo lib is now up-to-date +.fi \fR +.P +.RE +.P +The +.BR .c.a +rule is used to make +.BR file1.o , +.BR file2.o , +and +.BR file3.o +and insert them into +.BR lib . +.P +The treatment of escaped + +characters throughout the makefile is historical practice. For example, +the inference rule: +.sp +.RS 4 +.nf +\fB +\&.c.o\e +: +.fi \fR +.P +.RE +.P +works, and the macro: +.sp +.RS 4 +.nf +\fB +f= bar baz\e + biz +a: + echo ==$f== +.fi \fR +.P +.RE +.P +echoes +.BR \(dq==bar\ baz\ biz==\(dq . +.P +If $? were: +.sp +.RS 4 +.nf +\fB +/usr/include/stdio.h /usr/include/unistd.h foo.h +.fi \fR +.P +.RE +.P +then $(?D) would be: +.sp +.RS 4 +.nf +\fB +/usr/include /usr/include . +.fi \fR +.P +.RE +.P +and $(?F) would be: +.sp +.RS 4 +.nf +\fB +stdio.h unistd.h foo.h +.fi \fR +.P +.RE +.RE +.IP " 6." 4 +The contents of the built-in rules can be viewed by running: +.RS 4 +.sp +.RS 4 +.nf +\fB +make \(mip \(mif /dev/null 2>/dev/null +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR make +utility described in this volume of POSIX.1\(hy2008 is intended to provide the means for +changing portable source code into executables that can be run on an +POSIX.1\(hy2008-conforming system. It reflects the most common features present +in System V and BSD +.IR make s. +.P +Historically, the +.IR make +utility has been an especially fertile ground for vendor and research +organization-specific syntax modifications and extensions. Examples +include: +.IP " *" 4 +Syntax supporting parallel execution (such as from various +multi-processor vendors, GNU, and others) +.IP " *" 4 +Additional ``operators'' separating targets and their prerequisites +(System V, BSD, and others) +.IP " *" 4 +Specifying that command lines containing the strings +.BR \(dq${MAKE}\(dq +and +.BR \(dq$(MAKE)\(dq +are executed when the +.BR \(min +option is specified (GNU and System V) +.IP " *" 4 +Modifications of the meaning of internal macros when referencing +libraries (BSD and others) +.IP " *" 4 +Using a single instance of the shell for all of the command lines of +the target (BSD and others) +.IP " *" 4 +Allowing + +characters as well as + +characters to delimit command lines (BSD) +.IP " *" 4 +Adding C preprocessor-style ``include'' and ``ifdef'' constructs +(System V, GNU, BSD, and others) +.IP " *" 4 +Remote execution of command lines (Sprite and others) +.IP " *" 4 +Specifying additional special targets (BSD, System V, and most others) +.P +Additionally, many vendors and research organizations have rethought +the basic concepts of +.IR make , +creating vastly extended, as well as completely new, syntaxes. Each of +these versions of +.IR make +fulfills the needs of a different community of users; it is +unreasonable for this volume of POSIX.1\(hy2008 to require behavior that would be incompatible +(and probably inferior) to historical practice for such a community. +.P +In similar circumstances, when the industry has enough sufficiently +incompatible formats as to make them irreconcilable, this volume of POSIX.1\(hy2008 has followed +one or both of two courses of action. Commands have been renamed (\c +.IR cksum , +.IR echo , +and +.IR pax ) +and/or command line options have been provided to select the desired +behavior (\c +.IR grep , +.IR od , +and +.IR pax ). +.P +Because the syntax specified for the +.IR make +utility is, by and large, a subset of the syntaxes accepted by almost +all versions of +.IR make , +it was decided that it would be counter-productive to change the name. +And since the makefile itself is a basic unit of portability, it would +not be completely effective to reserve a new option letter, such as +.IR make +.BR \(miP , +to achieve the portable behavior. Therefore, the special target +.BR .POSIX +was added to the makefile, allowing users to specify ``standard'' +behavior. This special target does not preclude extensions in the +.IR make +utility, nor does it preclude such extensions being used by the +makefile specifying the target; it does, however, preclude any +extensions from being applied that could alter the behavior of +previously valid syntax; such extensions must be controlled via +command line options or new special targets. It is incumbent upon +portable makefiles to specify the +.BR .POSIX +special target in order to guarantee that they are not affected by +local extensions. +.P +The portable version of +.IR make +described in this reference page is not intended to be the +state-of-the-art software generation tool and, as such, some newer and +more leading-edge features have not been included. An attempt has been +made to describe the portable makefile in a manner that does not +preclude such extensions as long as they do not disturb the portable +behavior described here. +.P +When the +.BR \(min +option is specified, it is always added to +.IR MAKEFLAGS . +This allows a recursive +.IR make +.BR \(min +.IR target +to be used to see all of the action that would be taken to update +.IR target . +.P +The definition of +.IR MAKEFLAGS +allows both the System V letter string and the BSD command line +formats. The two formats are sufficiently different to allow +implementations to support both without ambiguity. +.P +Early proposals stated that an ``unquoted'' + +was treated as the start of a comment. The +.IR make +utility does not pay any attention to quotes. A + +starts a comment regardless of its surroundings. +.P +The text about ``other implementation-defined pathnames may also be +tried'' in addition to +.BR ./makefile +and +.BR ./Makefile +is to allow such extensions as +.BR SCCS/s.Makefile +and other variations. It was made an implementation-defined +requirement (as opposed to unspecified behavior) to highlight +surprising implementations that might select something unexpected like +.BR /etc/Makefile . +XSI-conformant systems also try +.BR ./s.makefile , +.BR SCCS/s.makefile , +.BR ./s.Makefile , +and +.BR SCCS/s.Makefile . +.P +Early proposals contained the macro +.BR NPROC +as a means of specifying that +.IR make +should use +.IR n +processes to do the work required. While this feature is a valuable +extension for many systems, it is not common usage and could require +other non-trivial extensions to makefile syntax. This extension is not +required by this volume of POSIX.1\(hy2008, but could be provided as a compatible extension. The +macro +.BR PARALLEL +is used by some historical systems with essentially the same meaning +(but without using a name that is a common system limit value). It is +suggested that implementors recognize the existing use of +.BR NPROC +and/or +.BR PARALLEL +as extensions to +.IR make . +.P +The default rules are based on System V. The default +.BR CC= +value is +.IR c99 +instead of +.IR cc +because this volume of POSIX.1\(hy2008 does not standardize the utility named +.IR cc . +Thus, every conforming application would be required to define +.BR CC= \c +.IR c99 +to expect to run. There is no advantage conferred by the hope that the +makefile might hit the ``preferred'' compiler because this cannot be +guaranteed to work. Also, since the portable makescript can only use +the +.IR c99 +options, no advantage is conferred in terms of what the script can do. +It is a quality-of-implementation issue as to whether +.IR c99 +is as valuable as +.IR cc . +.P +The +.BR \(mid +option to +.IR make +is frequently used to produce debugging information, but is too +implementation-defined to add to this volume of POSIX.1\(hy2008. +.P +The +.BR \(mip +option is not passed in +.IR MAKEFLAGS +on most historical implementations and to change this would cause many +implementations to break without sufficiently increased portability. +.P +Commands that begin with a + +(\c +.BR '\(pl' ) +are executed even if the +.BR \(min +option is present. Based on the GNU version of +.IR make , +the behavior of +.BR \(min +when the + +prefix is encountered has been extended to apply to +.BR \(miq +and +.BR \(mit +as well. However, the System V convention of forcing command execution +with +.BR \(min +when the command line of a target contains either of the strings +.BR \(dq$(MAKE)\(dq +or +.BR \(dq${MAKE}\(dq +has not been adopted. This functionality appeared in early proposals, +but the danger of this approach was pointed out with the following +example of a portion of a makefile: +.sp +.RS 4 +.nf +\fB +subdir: + cd subdir; rm all_the_files; $(MAKE) +.fi \fR +.P +.RE +.P +The loss of the System V behavior in this case is well-balanced by the +safety afforded to other makefiles that were not aware of this +situation. In any event, the command line + +prefix can provide the desired functionality. +.P +The double + +in the target rule format is supported in BSD systems to allow more +than one target line containing the same target name to have commands +associated with it. Since this is not functionality described in the +SVID or XPG3 it has been allowed as an extension, but not mandated. +.P +The default rules are provided with text specifying that the built-in +rules shall be the same as if the listed set were used. The intent is +that implementations should be able to use the rules without change, +but will be allowed to alter them in ways that do not affect the +primary behavior. +.P +The best way to provide portable makefiles is to include all of the +rules needed in the makefile itself. The rules provided use only +features provided by other portions of this volume of POSIX.1\(hy2008. The default rules include +rules for optional commands in this volume of POSIX.1\(hy2008. Only rules pertaining to commands +that are provided are needed in the default set of an implementation. +.P +One point of discussion was whether to drop the default rules list from +\&this volume of POSIX.1\(hy2008. They provide convenience, but do not enhance portability of +applications. The prime benefit is in portability of users who wish to +type +.IR make +.IR command +and have the command build from a +.BR command.c +file. +.P +The historical +.IR MAKESHELL +feature was omitted. In some implementations it is used to let a user +override the shell to be used to run +.IR make +commands. This was confusing; for a portable +.IR make , +the shell should be chosen by the makefile writer or specified on the +.IR make +command line and not by a user running +.IR make . +.P +The +.IR make +utilities in most historical implementations process the prerequisites +of a target in left-to-right order, and the makefile format +requires this. It supports the standard idiom used in many makefiles +that produce +.IR yacc +programs; for example: +.sp +.RS 4 +.nf +\fB +foo: y.tab.o lex.o main.o + $(CC) $(CFLAGS) \(mio $\fR@\fP t.tab.o lex.o main.o +.fi \fR +.P +.RE +.P +In this example, if +.IR make +chose any arbitrary order, the +.BR lex.o +might not be made with the correct +.BR y.tab.h . +Although there may be better ways to express this relationship, it is +widely used historically. Implementations that desire to update +prerequisites in parallel should require an explicit extension to +.IR make +or the makefile format to accomplish it, as described previously. +.P +The algorithm for determining a new entry for target rules is partially +unspecified. Some historical +.IR make s +allow blank, empty, or comment lines within the collection of commands +marked by leading + +characters. A conforming makefile must ensure that each command starts +with a +, +but implementations are free to ignore blank, empty, and comment lines +without triggering the start of a new entry. +.P +The ASYNCHRONOUS EVENTS section includes having SIGTERM and SIGHUP, +along with the more traditional SIGINT and SIGQUIT, remove the current +target unless directed not to do so. SIGTERM and SIGHUP were added to +parallel other utilities that have historically cleaned up their work +as a result of these signals. When +.IR make +receives any signal other than SIGQUIT, it is required to resend itself +the signal it received so that it exits with a status that reflects the +signal. The results from SIGQUIT are partially unspecified because, on +systems that create +.BR core +files upon receipt of SIGQUIT, the +.BR core +from +.IR make +would conflict with a +.BR core +file from the command that was running when the SIGQUIT arrived. The +main concern was to prevent damaged files from appearing up-to-date when +.IR make +is rerun. +.P +The +.BR .PRECIOUS +special target was extended to affect all targets globally (by +specifying no prerequisites). The +.BR .IGNORE +and +.BR .SILENT +special targets were extended to allow prerequisites; it was judged to +be more useful in some cases to be able to turn off errors or echoing +for a list of targets than for the entire makefile. These extensions +to +.IR make +in System V were made to match historical practice from the BSD +.IR make . +.P +Macros are not exported to the environment of commands to be run. This +was never the case in any historical +.IR make +and would have serious consequences. The environment is the same as +the environment to +.IR make +except that +.IR MAKEFLAGS +and macros defined on the +.IR make +command line are added. +.P +Some implementations do not use +\fIsystem\fR() +for all command lines, as required by the portable makefile +format; as a performance enhancement, they select lines without shell +metacharacters for direct execution by +\fIexecve\fR(). +There is no requirement that +\fIsystem\fR() +be used specifically, but merely that the same results be achieved. +The metacharacters typically used to bypass the direct +\fIexecve\fR() +execution have been any of: +.sp +.RS 4 +.nf +\fB += | ^ ( ) ; & < > * ? [ ] : $ ` ' " \e \en +.fi \fR +.P +.RE +.P +The default in some advanced versions of +.IR make +is to group all the command lines for a target and execute them using a +single shell invocation; the System V method is to pass each line +individually to a separate shell. The single-shell method has the +advantages in performance and the lack of a requirement for many +continued lines. However, converting to this newer method has caused +portability problems with many historical makefiles, so the behavior +with the POSIX makefile is specified to be the same as that of System +V. It is suggested that the special target +.BR .ONESHELL +be used as an implementation extension to achieve the single-shell +grouping for a target or group of targets. +.P +Novice users of +.IR make +have had difficulty with the historical need to start commands with a +. +Since it is often difficult to discern differences between + +and + +characters on terminals or printed listings, confusing bugs can arise. In +early proposals, an attempt was made to correct this problem by allowing +leading + +characters instead of + +characters. However, implementors reported many makefiles that failed +in subtle ways following this change, and it is difficult to implement a +.IR make +that unambiguously can differentiate between macro and command lines. +There is extensive historical practice of allowing leading + +characters before macro definitions. Forcing macro lines into column 1 +would be a significant backwards-compatibility problem for some makefiles. +Therefore, historical practice was restored. +.P +There is substantial variation in the handling of include lines by +different implementations. However, there is enough commonality for the +standard to be able to specify a minimum set of requirements that allow +the feature to be used portably. Known variations have been explicitly +called out as unspecified behavior in the description. +.P +The System V dynamic dependency feature was not included. It would +support: +.sp +.RS 4 +.nf +\fB +cat: $$@.c +.fi \fR +.P +.RE +.P +that would expand to; +.sp +.RS 4 +.nf +\fB +cat: cat.c +.fi \fR +.P +.RE +.P +This feature exists only in the new version of System V +.IR make +and, while useful, is not in wide usage. This means that macros are +expanded twice for prerequisites: once at makefile parse time and once +at target update time. +.P +Consideration was given to adding metarules to the POSIX +.IR make . +This would make +.BR "%.o:\ %.c" +the same as +.BR .c.o: . +This is quite useful and available from some vendors, but it would +cause too many changes to this +.IR make +to support. It would have introduced rule chaining and new substitution +rules. However, the rules for target names have been set to reserve the +.BR '%' +and +.BR '\&"' +characters. These are traditionally used to implement metarules and +quoting of target names, respectively. Implementors are strongly +encouraged to use these characters only for these purposes. +.P +A request was made to extend the suffix delimiter character from a + +to any character. The metarules feature in newer +.IR make s +solves this problem in a more general way. This volume of POSIX.1\(hy2008 is staying with the +more conservative historical definition. +.P +The standard output format for the +.BR \(mip +option is not described because it is primarily a debugging option and +because the format is not generally useful to programs. In historical +implementations the output is not suitable for use in generating +makefiles. The +.BR \(mip +format has been variable across historical implementations. Therefore, +the definition of +.BR \(mip +was only to provide a consistently named option for obtaining +.IR make +script debugging information. +.P +Some historical implementations have not cleared the suffix list with +.BR \(mir . +.P +Implementations should be aware that some historical applications have +intermixed +.IR target_name +and +.IR macro =\c +.IR value +operands on the command line, expecting that all of the macros are +processed before any of the targets are dealt with. Conforming +applications do not do this, but some backwards-compatibility support +may be warranted. +.P +Empty inference rules are specified with a + +command rather than omitting all commands, as described in an early +proposal. The latter case has no traditional meaning and is reserved +for implementation extensions, such as in GNU +.IR make . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIar\fR\^", +.IR "\fIc99\fR\^", +.IR "\fIget\fR\^", +.IR "\fIlex\fR\^", +.IR "\fIsccs\fR\^", +.IR "\fIsh\fR\^", +.IR "\fIyacc\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^", +.IR "\fIsystem\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/man.1p b/man-pages-posix-2013-a/man1p/man.1p new file mode 100644 index 0000000..ee4ba2b --- /dev/null +++ b/man-pages-posix-2013-a/man1p/man.1p @@ -0,0 +1,267 @@ +'\" et +.TH MAN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +man +\(em display system documentation +.SH SYNOPSIS +.LP +.nf +man \fB[\fR\(mik\fB] \fIname\fR... +.fi +.SH DESCRIPTION +The +.IR man +utility shall write information about each of the +.IR name +operands. If +.IR name +is the name of a standard utility, +.IR man +at a minimum shall write a message describing the syntax used by the +standard utility, its options, and operands. If more information is +available, the +.IR man +utility shall provide it in an implementation-defined manner. +.P +An implementation may provide information for values of +.IR name +other than the standard utilities. Standard utilities that are listed +as optional and that are not supported by the implementation either +shall cause a brief message indicating that fact to be displayed or +shall cause a full display of information as described previously. +.SH OPTIONS +The +.IR man +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mik\fP" 8 +Interpret +.IR name +operands as keywords to be used in searching a utilities summary +database that contains a brief purpose entry for each standard utility +and write lines from the summary database that match any of the +keywords. The keyword search shall produce results that are the +equivalent of the output of the following command: +.RS 8 +.sp +.RS 4 +.nf +\fB +grep \(miEi ' +\fIname +name\fP +\&... +\&' \fIsummary-database\fR +.fi \fR +.P +.RE +.P +This assumes that the +.IR summary-database +is a text file with a single entry per line; this organization is not +required and the example using +.IR grep +.BR \(miEi +is merely illustrative of the type of search intended. The purpose +entry to be included in the database shall consist of a terse +description of the purpose of the utility. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIname\fR" 10 +A keyword or the name of a standard utility. When +.BR \(mik +is not specified and +.IR name +does not represent one of the standard utilities, the results are +unspecified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR man : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and in the summary database). The +value of +.IR LC_CTYPE +need not affect the format of the information written about the +.IR name +operands. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPAGER\fP" 10 +Determine an output filtering command for writing the output to a +terminal. Any string acceptable as a +.IR command_string +operand to the +.IR sh +.BR \(mic +command shall be valid. When standard output is a terminal device, the +reference page output shall be piped through the command. If the +.IR PAGER +variable is null or not set, the command shall be either +.IR more +or another paginator utility documented in the system documentation. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR man +utility shall write text describing the syntax of the utility +.IR name , +its options and its operands, or, when +.BR \(mik +is specified, lines from the summary database. The format of this text +is implementation-defined. +.SH STDERR +The standard error shall be used for diagnostic messages, and may also +be used for informational messages of unspecified format. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +It is recognized that the +.IR man +utility is only of minimal usefulness as specified. The opinion of the +standard developers was strongly divided as to how much or how little +information +.IR man +should be required to provide. They considered, however, that the +provision of some portable way of accessing documentation would aid +user portability. The arguments against a fuller specification were: +.IP " *" 4 +Large quantities of documentation should not be required on a system +that does not have excess disk space. +.IP " *" 4 +The current manual system does not present information in a manner that +greatly aids user portability. +.IP " *" 4 +A ``better help system'' is currently an area in which vendors feel +that they can add value to their POSIX implementations. +.P +The +.BR \(mif +option was considered, but due to implementation differences, it was +not included in this volume of POSIX.1\(hy2008. +.P +The description was changed to be more specific about what has to be +displayed for a utility. The standard developers considered it +insufficient to allow a display of only the synopsis without giving a +short description of what each option and operand does. +.P +The ``purpose'' entry to be included in the database can be similar to +the section title (less the numeric prefix) from this volume of POSIX.1\(hy2008 for each utility. +These titles are similar to those used in historical systems for this +purpose. +.P +See +.IR mailx +for rationale concerning the default paginator. +.P +The caveat in the +.IR LC_CTYPE +description was added because it is not a requirement that an +implementation provide reference pages for all of its supported locales +on each system; changing +.IR LC_CTYPE +does not necessarily translate the reference page into another +language. This is equivalent to the current state of +.IR LC_MESSAGES +in POSIX.1\(hy2008\(emlocale-specific messages are not yet a requirement. +.P +The historical +.IR MANPATH +variable is not included in POSIX because no attempt is made to specify +naming conventions for reference page files, nor even to mandate that +they are files at all. On some implementations they could be a true +database, a hypertext file, or even fixed strings within the +.IR man +executable. The standard developers considered the portability of +reference pages to be outside their scope of work. However, users +should be aware that +.IR MANPATH +is implemented on a number of historical systems and that it can be +used to tailor the search pattern for reference pages from the various +categories (utilities, functions, file formats, and so on) when the +system administrator reveals the location and conventions for reference +pages on the system. +.P +The keyword search can rely on at least the text of the section titles +from these utility descriptions, and the implementation may add more +keywords. The term ``section titles'' refers to the strings such as: +.sp +.RS 4 +.nf +\fB +man \(em Display system documentation +ps \(em Report process status +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImore\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/mesg.1p b/man-pages-posix-2013-a/man1p/mesg.1p new file mode 100644 index 0000000..89ba318 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/mesg.1p @@ -0,0 +1,167 @@ +'\" et +.TH MESG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mesg +\(em permit or deny messages +.SH SYNOPSIS +.LP +.nf +mesg \fB[\fRy|n\fB]\fR +.fi +.SH DESCRIPTION +The +.IR mesg +utility shall control whether other users are allowed to send messages +via +.IR write , +.IR talk , +or other utilities to a terminal device. The terminal device affected +shall be determined by searching for the first terminal in the sequence +of devices associated with standard input, standard output, and +standard error, respectively. With no arguments, +.IR mesg +shall report the current state without changing it. Processes with +appropriate privileges may be able to send messages to the terminal +independent of the current state. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported in the POSIX locale: +.IP "\fIy\fR" 10 +Grant permission to other users to send messages to the terminal +device. +.IP "\fIn\fR" 10 +Deny permission to other users to send messages to the terminal +device. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mesg : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written (by +.IR mesg ) +to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If no operand is specified, +.IR mesg +shall display the current terminal state in an unspecified format. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Receiving messages is allowed. +.IP "\01" 6 +Receiving messages is not allowed. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The mechanism by which the message status of the terminal is changed is +unspecified. Therefore, unspecified actions may cause the status of +the terminal to change after +.IR mesg +has successfully completed. These actions may include, but are not +limited to: another invocation of the +.IR mesg +utility, login procedures; invocation of the +.IR stty +utility, invocation of the +.IR chmod +utility or +\fIchmod\fR() +function, and so on. +.SH EXAMPLES +None. +.SH RATIONALE +The terminal changed by +.IR mesg +is that associated with the standard input, output, or error, rather +than the controlling terminal for the session. This is because users +logged in more than once should be able to change any of their login +terminals without having to stop the job running in those sessions. +This is not a security problem involving the terminals of other users +because appropriate privileges would +be required to affect the terminal of another user. +.P +The method of checking each of the first three file descriptors in +sequence until a terminal is found was adopted from System V. +.P +The file +.BR /dev/tty +is not specified for the terminal device because it was thought to be +too restrictive. Typical environment changes for the +.IR n +operand are that write permissions are removed for +.IR others +and +.IR group +from the appropriate device. It was decided to leave the actual +description of what is done as unspecified because of potential +differences between implementations. +.P +The format for standard output is unspecified because of differences +between historical implementations. This output is generally not +useful to shell scripts (they can use the exit status), so exact +parsing of the output is unnecessary. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItalk\fR\^", +.IR "\fIwrite\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/mkdir.1p b/man-pages-posix-2013-a/man1p/mkdir.1p new file mode 100644 index 0000000..51a773f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/mkdir.1p @@ -0,0 +1,261 @@ +'\" et +.TH MKDIR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mkdir +\(em make directories +.SH SYNOPSIS +.LP +.nf +mkdir \fB[\fR\(mip\fB] [\fR\(mim \fImode\fB] \fIdir\fR... +.fi +.SH DESCRIPTION +The +.IR mkdir +utility shall create the directories specified by the operands, in the +order specified. +.P +For each +.IR dir +operand, the +.IR mkdir +utility shall perform actions equivalent to the +\fImkdir\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " 1." 4 +The +.IR dir +operand is used as the +.IR path +argument. +.IP " 2." 4 +The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO +is used as the +.IR mode +argument. (If the +.BR \(mim +option is specified, the value of the +\fImkdir\fR() +.IR mode +argument is unspecified, but the directory shall at no time +have permissions less restrictive than the +.BR \(mim +.IR mode +option-argument.) +.SH OPTIONS +The +.IR mkdir +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mim\ \fImode\fR" 10 +Set the file permission bits of the newly-created directory to the +specified +.IR mode +value. The +.IR mode +option-argument shall be the same as the +.IR mode +operand defined for the +.IR chmod +utility. In the +.IR symbolic_mode +strings, the +.IR op +characters +.BR '\(pl' +and +.BR '\(mi' +shall be interpreted relative to an assumed initial mode of +.IR a =\c +.IR rwx ; +.BR '\(pl' +shall add permissions to the default mode, +.BR '\(mi' +shall delete permissions from the default mode. +.IP "\fB\(mip\fP" 10 +Create any missing intermediate pathname components. +.RS 10 +.P +For each +.IR dir +operand that does not name an existing directory, before performing the +actions described in the DESCRIPTION above, the +.IR mkdir +utility shall create any pathname components of the path prefix of +.IR dir +that do not name an existing directory by performing actions equivalent +to first calling the +\fImkdir\fR() +function with the following arguments: +.IP " 1." 4 +A pathname naming the missing pathname component, ending with a trailing + +character, as the +.IR path +argument +.IP " 2." 4 +The value zero as the +.IR mode +argument +.P +and then calling the +\fIchmod\fR() +function with the following arguments: +.IP " 1." 4 +The same +.IR path +argument as in the +\fImkdir\fR() +call +.IP " 2." 4 +The value +.IR "(S_IWUSR|S_IXUSR|~\fIfilemask\fP)&0777" \fR +as the +.IR mode +argument, where +.IR filemask +is the file mode creation mask of the process (see the System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIumask\fR\^(\|)") +.P +Each +.IR dir +operand that names an existing directory shall be ignored without +error. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIdir\fR" 10 +A pathname of a directory to be created. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mkdir : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All the specified directories were created successfully or the +.BR \(mip +option was specified and all the specified directories now exist. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The default file mode for directories is +.IR a =\c +.IR rwx +(777 on most systems) with selected permissions removed in accordance +with the file mode creation mask. For intermediate pathname components +created by +.IR mkdir , +the mode is the default modified by +.IR u +\c +.IR wx +so that the subdirectories can always be created regardless of the file +mode creation mask; if different ultimate permissions are desired for +the intermediate directories, they can be changed afterwards with +.IR chmod . +.P +Note that some of the requested directories may have been created even +if an error occurs. +.SH EXAMPLES +None. +.SH RATIONALE +The System V +.BR \(mim +option was included to control the file mode. +.P +The System V +.BR \(mip +option was included to create any needed intermediate directories and +to complement the functionality provided by +.IR rmdir +for removing directories in the path prefix as they become empty. +Because no error is produced if any path component already exists, the +.BR \(mip +option is also useful to ensure that a particular directory exists. +.P +The functionality of +.IR mkdir +is described substantially through a reference to the +\fImkdir\fR() +function in the System Interfaces volume of POSIX.1\(hy2008. For example, by default, the mode of the +directory is affected by the file mode creation mask in accordance with +the specified behavior of the +\fImkdir\fR() +function. In this way, there is less duplication of effort required for +describing details of the directory creation. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIrm\fR\^", +.IR "\fIrmdir\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImkdir\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/mkfifo.1p b/man-pages-posix-2013-a/man1p/mkfifo.1p new file mode 100644 index 0000000..c5501a5 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/mkfifo.1p @@ -0,0 +1,190 @@ +'\" et +.TH MKFIFO "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mkfifo +\(em make FIFO special files +.SH SYNOPSIS +.LP +.nf +mkfifo \fB[\fR\(mim \fImode\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR mkfifo +utility shall create the FIFO special files specified by the operands, +in the order specified. +.P +For each +.IR file +operand, the +.IR mkfifo +utility shall perform actions equivalent to the +\fImkfifo\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " 1." 4 +The +.IR file +operand is used as the +.IR path +argument. +.IP " 2." 4 +The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP, +S_IWGRP, S_IROTH, and S_IWOTH is used as the +.IR mode +argument. (If the +.BR \(mim +option is specified, the value of the +\fImkfifo\fR() +.IR mode +argument is unspecified, but the FIFO shall at no time have permissions +less restrictive than the +.BR \(mim +.IR mode +option-argument.) +.SH OPTIONS +The +.IR mkfifo +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mim\ \fImode\fR" 10 +Set the file permission bits of the newly-created FIFO to the specified +.IR mode +value. The +.IR mode +option-argument shall be the same as the +.IR mode +operand defined for the +.IR chmod +utility. In the +.IR symbolic_mode +strings, the +.IR op +characters +.BR '\(pl' +and +.BR '\(mi' +shall be interpreted relative to an assumed initial mode of +.IR a =\c +.IR rw . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of the FIFO special file to be created. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mkfifo : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All the specified FIFO special files were created successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +This utility was added to permit shell applications to create FIFO +special files. +.P +The +.BR \(mim +option was added to control the file mode, for consistency with the +similar functionality provided by the +.IR mkdir +utility. +.P +Early proposals included a +.BR \(mip +option similar to the +.IR mkdir +.BR \(mip +option that created intermediate directories leading up to the FIFO +specified by the final component. This was removed because it is not +commonly needed and is not common practice with similar utilities. +.P +The functionality of +.IR mkfifo +is described substantially through a reference to the +\fImkfifo\fR() +function in the System Interfaces volume of POSIX.1\(hy2008. For example, by default, the mode of the FIFO +file is affected by the file mode creation mask in accordance with the +specified behavior of the +\fImkfifo\fR() +function. In this way, there is less duplication of effort required for +describing details of the file creation. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImkfifo\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/more.1p b/man-pages-posix-2013-a/man1p/more.1p new file mode 100644 index 0000000..5e56f88 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/more.1p @@ -0,0 +1,1382 @@ +'\" et +.TH MORE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +more +\(em display files on a page-by-page basis +.SH SYNOPSIS +.LP +.nf +more \fB[\fR\(miceisu\fB] [\fR\(min \fInumber\fB] [\fR\(mip \fIcommand\fB] [\fR\(mit \fItagstring\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR more +utility shall read files and either write them to the terminal on a +page-by-page basis or filter them to standard output. If standard +output is not a terminal device, all input files shall be copied to +standard output in their entirety, without modification, except as +specified for the +.BR \(mis +option. If standard output is a terminal device, the files shall be +written a number of lines (one screenful) at a time under the control +of user commands. See the EXTENDED DESCRIPTION section. +.P +Certain block-mode terminals do not have all the capabilities necessary +to support the complete +.IR more +definition; they are incapable of accepting commands that are not +terminated with a +. +Implementations that support such terminals shall provide an +operating mode to +.IR more +in which all commands can be terminated with a + +on those terminals. This mode: +.IP " *" 4 +Shall be documented in the system documentation +.IP " *" 4 +Shall, at invocation, inform the user of the terminal deficiency that +requires the + +usage and provide instructions on how this warning can be suppressed in +future invocations +.IP " *" 4 +Shall not be required for implementations supporting only fully capable +terminals +.IP " *" 4 +Shall not affect commands already requiring + +characters +.IP " *" 4 +Shall not affect users on the capable terminals from using +.IR more +as described in this volume of POSIX.1\(hy2008 +.SH OPTIONS +The +.IR more +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +If a screen is to be written that has no lines in common with the +current screen, or +.IR more +is writing its first screen, +.IR more +shall not scroll the screen, but instead shall redraw each line of the +screen in turn, from the top of the screen to the bottom. In addition, +if +.IR more +is writing its first screen, the screen shall be cleared. This option +may be silently ignored on devices with insufficient terminal +capabilities. +.IP "\fB\(mie\fP" 10 +Exit immediately after writing the last line of the last file in the +argument list; see the EXTENDED DESCRIPTION section. +.IP "\fB\(mii\fP" 10 +Perform pattern matching in searches without regard to case; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.2" ", " "Regular Expression General Requirements". +.IP "\fB\(min\ \fInumber\fR" 10 +Specify the number of lines per screenful. The +.IR number +argument is a positive decimal integer. The +.BR \(min +option shall override any values obtained from any other source. +.IP "\fB\(mip\ \fIcommand\fR" 10 +Each time a screen from a new file is displayed or redisplayed +(including as a result of +.IR more +commands; for example, +.BR :p ), +execute the +.IR more +command(s) in the command arguments in the order specified, as if +entered by the user after the first screen has been displayed. No +intermediate results shall be displayed (that is, if the command is a +movement to a screen different from the normal first screen, only the +screen resulting from the command shall be displayed.) If any of the +commands fail for any reason, an informational message to this effect +shall be written, and no further commands specified using the +.BR \(mip +option shall be executed for this file. +.IP "\fB\(mis\fP" 10 +Behave as if consecutive empty lines were a single empty line. +.IP "\fB\(mit\ \fItagstring\fR" 10 +Write the screenful of the file containing the tag named by the +.IR tagstring +argument. See the +.IR "\fIctags\fR\^" +utility. The tags feature represented by +.BR \(mit +.IR tagstring +and the +.BR :t +command is optional. It shall be provided on any system that also +provides a conforming implementation of +.IR ctags ; +otherwise, the use of +.BR \(mit +produces undefined results. +.RS 10 +.P +The filename resulting from the +.BR \(mit +option shall be logically added as a prefix to the list of command line +files, as if specified by the user. If the tag named by the +.IR tagstring +argument is not found, it shall be an error, and +.IR more +shall take no further action. +.P +If the tag specifies a line number, the first line of the display shall +contain the beginning of that line. If the tag specifies a pattern, the +first line of the display shall contain the beginning of the matching +text from the first line of the file that contains that pattern. If the +line does not exist in the file or matching text is not found, an +informational message to this effect shall be displayed, and +.IR more +shall display the default screen as if +.BR \(mit +had not been specified. +.P +If both the +.BR \(mit +.IR tagstring +and +.BR \(mip +.IR command +options are given, the +.BR \(mit +.IR tagstring +shall be processed first; that is, the file and starting line for the +display shall be as specified by +.BR \(mit , +and then the +.BR \(mip +.IR more +command shall be executed. If the line (matching text) specified by the +.BR \(mit +command does not exist (is not found), no +.BR \(mip +.IR more +command shall be executed for this file at any time. +.RE +.IP "\fB\(miu\fP" 10 +Treat a + +as a printable control character, displayed as an +implementation-defined character sequence (see the EXTENDED DESCRIPTION +section), suppressing backspacing and the special handling that +produces underlined or standout mode text on some terminal types. +Also, do not ignore a + +at the end of a line. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, the standard input shall be used. If a +.IR file +is +.BR '\(mi' , +the standard input shall be read at that point in the sequence. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +The input files being examined shall be text files. If standard output +is a terminal, standard error shall be used to read commands from the +user. If standard output is a terminal, standard error is not readable, +and command input is needed, +.IR more +may attempt to obtain user commands from the controlling terminal (for +example, +.BR /dev/tty ); +otherwise, +.IR more +shall terminate with an error indicating that it was unable to read +user commands. If standard output is not a terminal, no error shall +result if standard error cannot be opened for reading. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR more : +.IP "\fICOLUMNS\fP" 10 +Override the system-selected horizontal display line size. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fIEDITOR\fP" 10 +Used by the +.BR v +command to select an editor. See the EXTENDED DESCRIPTION section. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fILINES\fP" 10 +Override the system-selected vertical screen size, used as the number +of lines in a screenful. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. The +.BR \(min +option shall take precedence over the +.IR LINES +variable for determining the number of lines in a screenful. +.IP "\fIMORE\fP" 10 +Determine a string containing options described in the OPTIONS section +preceded with + +characters and +-separated +as on the command line. Any command line options shall be processed +after those in the +.IR MORE +variable, as if the command line were: +.RS 10 +.sp +.RS 4 +.nf +\fB +more $MORE \fIoptions operands\fR +.fi \fR +.P +.RE +.P +The +.IR MORE +variable shall take precedence over the +.IR TERM +and +.IR LINES +variables for determining the number of lines in a screenful. +.RE +.IP "\fITERM\fP" 10 +Determine the name of the terminal type. If this variable is unset or +null, an unspecified default terminal type is used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used to write the contents of the input +files. +.SH STDERR +The standard error shall be used for diagnostic messages and user +commands (see the INPUT FILES section), and, if standard output is a +terminal device, to write a prompting string. The prompting string +shall appear on the screen line below the last line of the file +displayed in the current screenful. The prompt shall contain the name +of the file currently being examined and shall contain an end-of-file +indication and the name of the next file, if any, when prompting at the +end-of-file. If an error or informational message is displayed, it is +unspecified whether it is contained in the prompt. If it is not +contained in the prompt, it shall be displayed and then the user shall +be prompted for a continuation character, at which point another +message or the user prompt may be displayed. The prompt is otherwise +unspecified. It is unspecified whether informational messages are +written for other user commands. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The following section describes the behavior of +.IR more +when the standard output is a terminal device. If the standard output +is not a terminal device, no options other than +.BR \(mis +shall have any effect, and all input files shall be copied to standard +output otherwise unmodified, at which time +.IR more +shall exit without further action. +.P +The number of lines available per screen shall be determined by the +.BR \(min +option, if present, or by examining values in the environment (see the +ENVIRONMENT VARIABLES section). If neither method yields a number, an +unspecified number of lines shall be used. +.P +The maximum number of lines written shall be one less than this number, +because the screen line after the last line written shall be used to +write a user prompt and user input. If the number of lines in the +screen is less than two, the results are undefined. It is unspecified +whether user input is permitted to be longer than the remainder of the +single line where the prompt has been written. +.P +The number of columns available per line shall be determined by +examining values in the environment (see the ENVIRONMENT VARIABLES +section), with a default value as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +Lines that are longer than the display shall be folded; the length at +which folding occurs is unspecified, but should be appropriate for the +output device. Folding may occur between glyphs of single characters +that take up multiple display columns. +.P +When standard output is a terminal and +.BR \(miu +is not specified, +.IR more +shall treat + +and + +characters specially: +.IP " *" 4 +A character, followed first by a sequence of +.IR n + +characters (where +.IR n +is the same as the number of column positions that the character +occupies), then by +.IR n + +characters (\c +.BR '_' ), +shall cause that character to be written as underlined text, if the +terminal type supports that. The +.IR n + +characters, followed first by +.IR n + +characters, then any character with +.IR n +column positions, shall also cause that character to be written as +underlined text, if the terminal type supports that. +.IP " *" 4 +A sequence of +.IR n + +characters (where +.IR n +is the same as the number of column positions that the previous +character occupies) that appears between two identical printable +characters shall cause the first of those two characters to be written +as emboldened text (that is, visually brighter, standout mode, or +inverse-video mode), if the terminal type supports that, and the second +to be discarded. Immediately subsequent occurrences of +/\c +character pairs for that same character shall also be discarded. (For +example, the sequence +.BR \(dqa\eba\eba\eba\(dq +is interpreted as a single emboldened +.BR 'a' .) +.IP " *" 4 +The +.IR more +utility shall logically discard all other + +characters from the line as well as the character which precedes them, +if any. +.IP " *" 4 +A + +at the end of a line shall be ignored, rather than being written as a +non-printable character, as described in the next paragraph. +.P +It is implementation-defined how other non-printable characters are +written. Implementations should use the same format that they use for +the +.IR ex +.BR print +command; see the OPTIONS section within the +.IR ed +utility. It is unspecified whether a multi-column character shall be +separated if it crosses a display line boundary; it shall not be +discarded. The behavior is unspecified if the number of columns on the +display is less than the number of columns any single character in the +line being displayed would occupy. +.P +When each new file is displayed (or redisplayed), +.IR more +shall write the first screen of the file. Once the initial screen has +been written, +.IR more +shall prompt for a user command. If the execution of the user command +results in a screen that has lines in common with the current screen, +and the device has sufficient terminal capabilities, +.IR more +shall scroll the screen; otherwise, it is unspecified whether the +screen is scrolled or redrawn. +.P +For all files but the last (including standard input if no file was +specified, and for the last file as well, if the +.BR \(mie +option was not specified), when +.IR more +has written the last line in the file, +.IR more +shall prompt for a user command. This prompt shall contain the name of +the next file as well as an indication that +.IR more +has reached end-of-file. If the user command is +.BR f , +\(hyF, +, +.BR j , +, +.BR d , +\(hyD, +or +.BR s , +.IR more +shall display the next file. Otherwise, if displaying the last file, +.IR more +shall exit. Otherwise, +.IR more +shall execute the user command specified. +.P +Several of the commands described in this section display a previous +screen from the input stream. In the case that text is being taken from +a non-rewindable stream, such as a pipe, it is implementation-defined +how much backwards motion is supported. If a command cannot be executed +because of a limitation on backwards motion, an error message to this +effect shall be displayed, the current screen shall not change, and the +user shall be prompted for another command. +.P +If a command cannot be performed because there are insufficient lines +to display, +.IR more +shall alert the terminal. If a command cannot be performed because +there are insufficient lines to display or a +.BR / +command fails: if the input is the standard input, the last screen in +the file may be displayed; otherwise, the current file and screen shall +not change, and the user shall be prompted for another command. +.P +The interactive commands in the following sections shall be supported. +Some commands can be preceded by a decimal integer, called +.IR count +in the following descriptions. If not specified with the command, +.IR count +shall default to 1. In the following descriptions, +.IR pattern +is a basic regular expression, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +The term ``examine'' is historical usage meaning ``open the +file for viewing''; for example, +.IR more +.BR foo +would be expressed as examining file +.BR foo . +.P +In the following descriptions, unless otherwise specified, +.IR line +is a line in the +.IR more +display, not a line from the file being examined. +.P +In the following descriptions, the +.IR "current position" +refers to two things: +.IP " 1." 4 +The position of the current line on the screen +.IP " 2." 4 +The line number (in the file) of the current line on the screen +.P +Usually, the line on the screen corresponding to the current position +is the third line on the screen. If this is not possible (there are +fewer than three lines to display or this is the first page of the +file, or it is the last page of the file), then the current position is +either the first or last line on the screen as described later. +.SS "Help" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +h +.fi \fR +.P +.RE +.RE +.P +Write a summary of these commands and other implementation-defined +commands. The behavior shall be as if the +.IR more +utility were executed with the +.BR \(mie +option on a file that contained the summary information. The user shall +be prompted as described earlier in this section when end-of-file is +reached. If the user command is one of those specified to continue to +the next file, +.IR more +shall return to the file and screen state from which the +.BR h +command was executed. +.SS "Scroll Forward One Screenful" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRf +\fB[\fIcount\fB]\fR-F +.fi \fR +.P +.RE +.RE +.P +Scroll forward +.IR count +lines, with a default of one screenful. If +.IR count +is more than the screen size, only the final screenful shall be +written. +.SS "Scroll Backward One Screenful" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRb +\fB[\fIcount\fB]\fR-B +.fi \fR +.P +.RE +.RE +.P +Scroll backward +.IR count +lines, with a default of one screenful (see the +.BR \(min +option). If +.IR count +is more than the screen size, only the final screenful shall be +written. +.SS "Scroll Forward One Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR +\fB[\fIcount\fB]\fRj +\fB[\fIcount\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Scroll forward +.IR count +lines. The default +.IR count +for the + +shall be one screenful; for +.BR j +and +, +one line. The entire +.IR count +lines shall be written, even if +.IR count +is more than the screen size. +.SS "Scroll Backward One Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRk +.fi \fR +.P +.RE +.RE +.P +Scroll backward +.IR count +lines. The entire +.IR count +lines shall be written, even if +.IR count +is more than the screen size. +.SS "Scroll Forward One Half Screenful" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRd +\fB[\fIcount\fB]\fR-D +.fi \fR +.P +.RE +.RE +.P +Scroll forward +.IR count +lines, with a default of one half of the screen size. If +.IR count +is specified, it shall become the new default for subsequent +.BR d , +\(hyD, +and +.BR u +commands. +.SS "Skip Forward One Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRs +.fi \fR +.P +.RE +.RE +.P +Display the screenful beginning with the line +.IR count +lines after the last line on the current screen. If +.IR count +would cause the current position to be such that less than one +screenful would be written, the last screenful in the file shall be +written. +.SS "Scroll Backward One Half Screenful" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRu +\fB[\fIcount\fB]\fR-U +.fi \fR +.P +.RE +.RE +.P +Scroll backward +.IR count +lines, with a default of one half of the screen size. If +.IR count +is specified, it shall become the new default for subsequent +.BR d , +\(miD, +.BR u , +and +\(miU +commands. The entire +.IR count +lines shall be written, even if +.IR count +is more than the screen size. +.SS "Go to Beginning of File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRg +.fi \fR +.P +.RE +.RE +.P +Display the screenful beginning with line +.IR count . +.SS "Go to End-of-File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRG +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is specified, display the screenful beginning with the line +.IR count . +Otherwise, display the last screenful of the file. +.SS "Refresh the Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +r +-L +.fi \fR +.P +.RE +.RE +.P +Refresh the screen. +.SS "Discard and Refresh" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +R +.fi \fR +.P +.RE +.RE +.P +Refresh the screen, discarding any buffered input. If the current file +is non-seekable, buffered input shall not be discarded and the +.BR R +command shall be equivalent to the +.BR r +command. +.SS "Mark Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +m\fIletter\fR +.fi \fR +.P +.RE +.RE +.P +Mark the current position with the letter named by +.IR letter , +where +.IR letter +represents the name of one of the lowercase letters of the portable +character set. When a new file is examined, all marks may be lost. +.SS "Return to Mark" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&'\fIletter\fR +.fi \fR +.P +.RE +.RE +.P +Return to the position that was previously marked with the letter named +by +.IR letter , +making that line the current position. +.SS "Return to Previous Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&'' +.fi \fR +.P +.RE +.RE +.P +Return to the position from which the last large movement command was +executed (where a ``large movement'' is defined as any movement of more +than a screenful of lines). If no such movements have been made, return +to the beginning of the file. +.SS "Search Forward for Pattern" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR/\fB[\fR!\fB]\fIpattern\fR +.fi \fR +.P +.RE +.RE +.P +Display the screenful beginning with the +.IR count th +line containing the pattern. The search shall start after the first +line currently displayed. The null regular expression (\c +.BR '/' +followed by a +) +shall repeat the search using the previous regular expression, with a +default +.IR count . +If the character +.BR '!' +is included, the matching lines shall be those that do not contain the +.IR pattern . +If no match is found for the +.IR pattern , +a message to that effect shall be displayed. +.SS "Search Backward for Pattern" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR?\fB[\fR!\fB]\fIpattern\fR +.fi \fR +.P +.RE +.RE +.P +Display the screenful beginning with the +.IR count th +previous line containing the pattern. The search shall start on the +last line before the first line currently displayed. The null regular +expression (\c +.BR '?' +followed by a +) +shall repeat the search using the previous regular expression, with a +default +.IR count . +If the character +.BR '!' +is included, matching lines shall be those that do not contain the +.IR pattern . +If no match is found for the +.IR pattern , +a message to that effect shall be displayed. +.SS "Repeat Search" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRn +.fi \fR +.P +.RE +.RE +.P +Repeat the previous search for +.IR count th +line containing the last +.IR pattern +(or not containing the last +.IR pattern , +if the previous search was +.BR \(dq/!\(dq +or +.BR \(dq?!\(dq ). +.SS "Repeat Search in Reverse" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRN +.fi \fR +.P +.RE +.RE +.P +Repeat the search in the opposite direction of the previous search for +the +.IR count th +line containing the last +.IR pattern +(or not containing the last +.IR pattern , +if the previous search was +.BR \(dq/!\(dq +or +.BR \(dq?!\(dq ). +.SS "Examine New File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +:e \fB[\fIfilename\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Examine a new file. If the +.IR filename +argument is not specified, the current file (see the +.BR :n +and +.BR :p +commands below) shall be re-examined. The +.IR filename +shall be subjected to the process of shell word expansions (see +.IR "Section 2.6" ", " "Word Expansions"); +if more than a single pathname results, the effects are unspecified. +If +.IR filename +is a + +(\c +.BR '#' ), +the previously examined file shall be re-examined. If +.IR filename +is not accessible for any reason (including that it is a non-seekable +file), an error message to this effect shall be displayed and the +current file and screen shall not change. +.SS "Examine Next File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR:n +.fi \fR +.P +.RE +.RE +.P +Examine the next file. If a number +.IR count +is specified, the +.IR count th +next file shall be examined. If +.IR filename +refers to a non-seekable file, the results are unspecified. +.SS "Examine Previous File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR:p +.fi \fR +.P +.RE +.RE +.P +Examine the previous file. If a number +.IR count +is specified, the +.IR count th +previous file shall be examined. If +.IR filename +refers to a non-seekable file, the results are unspecified. +.SS "Go to Tag" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +:t \fItagstring\fR +.fi \fR +.P +.RE +.RE +.P +If the file containing the tag named by the +.IR tagstring +argument is not the current file, examine the file, as if the +.BR :e +command was executed with that file as the argument. Otherwise, or in +addition, display the screenful beginning with the tag, as described +for the +.BR \(mit +option (see the OPTIONS section). If the +.IR ctags +utility is not supported by the system, the use of +.BR :t +produces undefined results. +.SS "Invoke Editor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +v +.fi \fR +.P +.RE +.RE +.P +Invoke an editor to edit the current file being examined. If standard +input is being examined, the results are unspecified. The name of the +editor shall be taken from the environment variable +.IR EDITOR , +or shall default to +.IR vi . +If the last pathname component in +.IR EDITOR +is either +.IR vi +or +.IR ex , +the editor shall be invoked with a +.BR \(mic +.IR linenumber +command line argument, where +.IR linenumber +is the line number of the file line containing the display line +currently displayed as the first line of the screen. It is +implementation-defined whether line-setting options are passed to +editors other than +.IR vi +and +.IR ex . +.P +When the editor exits, +.IR more +shall resume with the same file and screen as when the editor was +invoked. +.SS "Display Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB += +-G +.fi \fR +.P +.RE +.RE +.P +Write a message for which the information references the first byte of +the line after the last line of the file on the screen. This message +shall include the name of the file currently being examined, its number +relative to the total number of files there are to examine, the line +number in the file, the byte number and the total bytes in the file, +and what percentage of the file precedes the current position. If +.IR more +is reading from standard input, or the file is shorter than a single +screen, the line number, the byte number, the total bytes, and the +percentage need not be written. +.SS "Quit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q +:q +ZZ +.fi \fR +.P +.RE +.RE +.P +Exit +.IR more . +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If an error is encountered accessing a file when using the +.BR :n +command, +.IR more +shall attempt to examine the next file in the argument list, but the +final exit status shall be affected. If an error is encountered +accessing a file via the +.BR :p +command, +.IR more +shall attempt to examine the previous file in the argument list, but +the final exit status shall be affected. If an error is encountered +accessing a file via the +.BR :e +command, +.IR more +shall remain in the current file and the final exit status shall not be +affected. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +When the standard output is not a terminal, only the +.BR \(mis +filter-modification option is effective. This is based on historical +practice. For example, a typical implementation of +.IR man +pipes its output through +.IR more +.BR \(mis +to squeeze excess white space for terminal users. When +.IR man +is piped to +.IR lp , +however, it is undesirable for this squeezing to happen. +.SH EXAMPLES +The +.BR \(mip +allows arbitrary commands to be executed at the start of each file. +Examples are: +.IP "\fImore\ \fB\(mip\ G\ \fIfile1\ file2\fR" 6 +.br +Examine each file starting with its last screenful. +.IP "\fImore\ \fB\(mip\ \fR100\ \fIfile1\ file2\fR" 6 +.br +Examine each file starting with line 100 in the current position +(usually the third line, so line 98 would be the first line written). +.IP "\fImore\ \fB\(mip\ \fR/100\ \fIfile1\ file2\fR" 6 +.br +Examine each file starting with the first line containing the string +.BR \(dq100\(dq +in the current position +.SH RATIONALE +The +.IR more +utility, available in BSD and BSD-derived systems, was chosen as the +prototype for the POSIX file display program since it is more widely +available than either the public-domain program +.IR less +or than +.IR pg , +a pager provided in System V. The 4.4 BSD +.IR more +is the model for the features selected; it is almost fully +upwards-compatible from the 4.3 BSD version in wide use and has become +more amenable for +.IR vi +users. Several features originally derived from various file editors, +found in both +.IR less +and +.IR pg , +have been added to this volume of POSIX.1\(hy2008 as they have proved extremely popular with +users. +.P +There are inconsistencies between +.IR more +and +.IR vi +that result from historical practice. For example, the single-character +commands +.BR h , +.BR f , +.BR b , +and + +are screen movers in +.IR more , +but cursor movers in +.IR vi . +These inconsistencies were maintained because the cursor movements are +not applicable to +.IR more +and the powerful functionality achieved without the use of the control +key justifies the differences. +.P +The tags interface has been included in a program that is not a text +editor because it promotes another degree of consistent operation with +.IR vi . +It is conceivable that the paging environment of +.IR more +would be superior for browsing source code files in some +circumstances. +.P +The operating mode referred to for block-mode terminals effectively +adds a + +to each Synopsis line that currently has none. So, for example, +.BR d \c + +would page one screenful. The mode could be triggered by a command +line option, environment variable, or some other method. The details +are not imposed by this volume of POSIX.1\(hy2008 because there are so few systems known to +support such terminals. Nevertheless, it was considered that all +systems should be able to support +.IR more +given the exception cited for this small community of terminals +because, in comparison to +.IR vi , +the cursor movements are few and the command set relatively amenable to +the optional + +characters. +.P +Some versions of +.IR more +provide a shell escaping mechanism similar to the +.IR ex +.BR ! +command. The standard developers did not consider that this was +necessary in a paginator, particularly given the wide acceptance of +multiple window terminals and job control features. (They chose to +retain such features in the editors and +.IR mailx +because the shell interaction also gives an opportunity to modify the +editing buffer, which is not applicable to +.IR more .) +.P +The +.BR \(mip +(position) option replaces the +.BR + +command because of the Utility Syntax Guidelines. The +.BR \(pl \c +.IR command +option is no longer specified by POSIX.1\(hy2008 but may be present +in some implementations. In early proposals, it took a +.IR pattern +argument, but historical +.IR less +provided the +.IR more +general facility of a command. It would have been desirable to use the +same +.BR \(mic +as +.IR ex +and +.IR vi , +but the letter was already in use. +.P +The text stating ``from a non-rewindable stream .\|.\|. implementations +may limit the amount of backwards motion supported'' would allow an +implementation that permitted no backwards motion beyond text already +on the screen. It was not possible to require a minimum amount of +backwards motion that would be effective for all conceivable device +types. The implementation should allow the user to back up as far as +possible, within device and reasonable memory allocation constraints. +.P +Historically, non-printable characters were displayed using the ARPA +standard mappings, which are as follows: +.IP " 1." 4 +Printable characters are left alone. +.IP " 2." 4 +Control characters less than \e177 are represented as followed by the +character offset from the +.BR '@' +character in the ASCII map; for example, \e007 is represented as +.BR 'G' . +.IP " 3." 4 +\e177 is represented as followed by +.BR '?' . +.P +The display of characters having their eighth bit set was less +standard. Existing implementations use hex (0x00), octal (\e000), and a +meta-bit display. (The latter displayed characters with their eighth +bit set as the two characters +.BR \(dqM\(mi\(dq , +followed by the seven-bit display as described previously.) The latter +probably has the best claim to historical practice because it was used +with the +.BR \(miv +option of 4 BSD and 4 BSD-derived versions of the +.IR cat +utility since 1980. +.P +No specific display format is required by POSIX.1\(hy2008. Implementations are +encouraged to conform to historic practice in the absence of any strong +reason to diverge. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIctags\fR\^", +.IR "\fIed\fR\^", +.IR "\fIex\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.2" ", " "Regular Expression General Requirements", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/mv.1p b/man-pages-posix-2013-a/man1p/mv.1p new file mode 100644 index 0000000..d8e4dde --- /dev/null +++ b/man-pages-posix-2013-a/man1p/mv.1p @@ -0,0 +1,529 @@ +'\" et +.TH MV "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mv +\(em move files +.SH SYNOPSIS +.LP +.nf +mv \fB[\fR\(miif\fB] \fIsource_file target_file\fR +.P +mv \fB[\fR\(miif\fB] \fIsource_file\fR... \fItarget_dir\fR +.fi +.SH DESCRIPTION +In the first synopsis form, the +.IR mv +utility shall move the file named by the +.IR source_file +operand to the destination specified by the +.IR target_file . +This first synopsis form is assumed when the final operand does not +name an existing directory and is not a symbolic link referring to +an existing directory. In this case, if +.IR source_file +names a non-directory file and +.IR target_file +ends with a trailing + +character, +.IR mv +shall treat this as an error and no +.IR source_file +operands will be processed. +.P +In the second synopsis form, +.IR mv +shall move each file named by a +.IR source_file +operand to a destination file in the existing directory named by the +.IR target_dir +operand, or referenced if +.IR target_dir +is a symbolic link referring to an existing directory. The +destination path for each +.IR source_file +shall be the concatenation of the target directory, a single + +character if the target did not end in a +, +and the last pathname component of the +.IR source_file . +This second form is assumed when the final operand names an existing +directory. +.P +If any operand specifies an existing file of a type not +specified by the System Interfaces volume of POSIX.1\(hy2008, the behavior is implementation-defined. +.P +For each +.IR source_file +the following steps shall be taken: +.IP " 1." 4 +If the destination path exists, the +.BR \(mif +option is not specified, and either of the following conditions is +true: +.RS 4 +.IP " a." 4 +The permissions of the destination path do not permit writing and the +standard input is a terminal. +.IP " b." 4 +The +.BR \(mii +option is specified. +.P +the +.IR mv +utility shall write a prompt to standard error and read a line from +standard input. If the response is not affirmative, +.IR mv +shall do nothing more with the current +.IR source_file +and go on to any remaining +.IR source_file s. +.RE +.IP " 2." 4 +If the +.IR source_file +operand and destination path name the same existing file, then the +destination path shall not be removed, and one of the following shall +occur: +.RS 4 +.IP " a." 4 +No change is made to +.IR source_file , +no error occurs, and no diagnostic is issued. +.IP " b." 4 +No change is made to +.IR source_file , +a diagnostic is issued to standard error identifying the two names, +and the exit status is affected. +.IP " c." 4 +If the +.IR source_file +operand and destination path name distinct directory entries, then the +.IR source_file +operand is removed, no error occurs, and no diagnostic is issued. +.P +The +.IR mv +utility shall do nothing more with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.RE +.IP " 3." 4 +The +.IR mv +utility shall perform actions equivalent to the +\fIrename\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.RS 4 +.IP " a." 4 +The +.IR source_file +operand is used as the +.IR old +argument. +.IP " b." 4 +The destination path is used as the +.IR new +argument. +.P +If this succeeds, +.IR mv +shall do nothing more with the current +.IR source_file +and go on to any remaining +.IR source_file s. +If this fails for any reasons other than those described for the +.IR errno +.BR [EXDEV] +in the System Interfaces volume of POSIX.1\(hy2008, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.RE +.IP " 4." 4 +If the destination path exists, and it is a file of type directory and +.IR source_file +is not a file of type directory, or it is a file not of type directory +and +.IR source_file +is a file of type directory, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +If the destination path exists and was created by a previous step, it +is unspecified whether this will treated as an error or the destination +path will be overwritten. +.IP " 5." 4 +If the destination path exists, +.IR mv +shall attempt to remove it. If this fails for any reason, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.IP " 6." 4 +The file hierarchy rooted in +.IR source_file +shall be duplicated as a file hierarchy rooted in the destination path. If +.IR source_file +or any of the files below it in the hierarchy are symbolic links, the +links themselves shall be duplicated, including their contents, rather +than any files to which they refer. The following characteristics of +each file in the file hierarchy shall be duplicated: +.RS 4 +.IP " *" 4 +The time of last data modification and time of last access +.IP " *" 4 +The user ID and group ID +.IP " *" 4 +The file mode +.P +If the user ID, group ID, or file mode of a regular file cannot be +duplicated, the file mode bits S_ISUID and S_ISGID shall not be +duplicated. +.P +When files are duplicated to another file system, the implementation +may require that the process invoking +.IR mv +has read access to each file being duplicated. +.P +If files being duplicated to another file system have hard links to +other files, it is unspecified whether the files copied to the new +file system have the hard links preserved or separate copies are created +for the linked files. +.P +If the duplication of the file hierarchy fails for any reason, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.P +If the duplication of the file characteristics fails for any reason, +.IR mv +shall write a diagnostic message to standard error, but this failure +shall not cause +.IR mv +to modify its exit status. +.RE +.IP " 7." 4 +The file hierarchy rooted in +.IR source_file +shall be removed. If this fails for any reason, +.IR mv +shall write a diagnostic message to the standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.SH OPTIONS +The +.IR mv +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\fP" 10 +Do not prompt for confirmation if the destination path exists. Any +previous occurrence of the +.BR \(mii +option is ignored. +.IP "\fB\(mii\fP" 10 +Prompt for confirmation if the destination path exists. Any previous +occurrence of the +.BR \(mif +option is ignored. +.P +Specifying more than one of the +.BR \(mif +or +.BR \(mii +options shall not be considered an error. The last option specified +shall determine the behavior of +.IR mv . +.SH OPERANDS +The following operands shall be supported: +.IP "\fIsource_file\fR" 10 +A pathname of a file or directory to be moved. +.IP "\fItarget_file\fR" 10 +A new pathname for the file or directory being moved. +.IP "\fItarget_dir\fR" 10 +A pathname of an existing directory into which to move the input +files. +.SH STDIN +The standard input shall be used to read an input line in response to +each prompt specified in the STDERR section. Otherwise, the standard +input shall not be used. +.SH "INPUT FILES" +The input files specified by each +.IR source_file +operand can be of any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mv : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Prompts shall be written to the standard error under the conditions +specified in the DESCRIPTION section. The prompts shall contain the +destination pathname, but their format is otherwise unspecified. +Otherwise, the standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files may be of any file type. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were moved successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If the copying or removal of +.IR source_file +is prematurely terminated by a signal or error, +.IR mv +may leave a partial copy of +.IR source_file +at the source or destination. The +.IR mv +utility shall not modify both +.IR source_file +and the destination path simultaneously; termination at any point shall +leave either +.IR source_file +or the destination path complete. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Some implementations mark for update the last file status change timestamp +of renamed files and some do not. Applications which make use of the +last file status change timestamp may behave differently with respect +to renamed files unless they are designed to allow for either behavior. +.P +The specification ensures that +.IR mv +.BR a +.BR a +will not alter the contents of file +.BR a , +and allows the implementation to issue an error that a file cannot be +moved onto itself. Likewise, when +.BR a +and +.BR b +are hard links to the same file, +.IR mv +.BR a +.BR b +will not alter +.BR b , +but if a diagnostic is not issued, then it is unspecified whether +.BR a +is left untouched (as it would be by the +\fIrename\fR() +function) or unlinked (reducing the link count of +.BR b ). +.SH EXAMPLES +If the current directory contains only files +.BR a +(of any type defined by the System Interfaces volume of POSIX.1\(hy2008), +.BR b +(also of any type), and a directory +.BR c : +.sp +.RS 4 +.nf +\fB +mv a b c +mv c d +.fi \fR +.P +.RE +.P +results with the original files +.BR a +and +.BR b +residing in the directory +.BR d +in the current directory. +.SH RATIONALE +Early proposals diverged from the SVID and BSD historical practice in +that they required that when the destination path exists, the +.BR \(mif +option is not specified, and input is not a terminal, +.IR mv +fails. This was done for compatibility with +.IR cp . +The current text returns to historical practice. It should be noted +that this is consistent with the +\fIrename\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, which does not require write permission +on the target. +.P +For absolute clarity, paragraph (1), describing the behavior of +.IR mv +when prompting for confirmation, should be interpreted in the following +manner: +.sp +.RS 4 +.nf +\fB +if (exists AND (NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +.fi \fR +.P +.RE +.P +The +.BR \(mii +option exists on BSD systems, giving applications and users a way to +avoid accidentally unlinking files when moving others. When the +standard input is not a terminal, the 4.3 BSD +.IR mv +deletes all existing destination paths without prompting, even when +.BR \(mii +is specified; this is inconsistent with the behavior of the 4.3 BSD +.IR cp +utility, which always generates an error when the file is unwritable +and the standard input is not a terminal. The standard developers +decided that use of +.BR \(mii +is a request for interaction, so when the destination +path exists, the utility takes instructions from whatever responds to +standard input. +.P +The +\fIrename\fR() +function is able to move directories within the same file system. Some +historical versions of +.IR mv +have been able to move directories, but not to a different file system. +The standard developers considered that this was an annoying +inconsistency, so this volume of POSIX.1\(hy2008 requires directories to be able to be moved +even across file systems. There is no +.BR \(miR +option to confirm that moving a directory is actually intended, since +such an option was not required for moving directories in historical +practice. Requiring the application to specify it sometimes, depending +on the destination, seemed just as inconsistent. The semantics of the +\fIrename\fR() +function were preserved as much as possible. For example, +.IR mv +is not permitted to ``rename'' files to or from directories, even +though they might be empty and removable. +.P +Historic implementations of +.IR mv +did not exit with a non-zero exit status if they were unable to +duplicate any file characteristics when moving a file across file +systems, nor did they write a diagnostic message for the user. The +former behavior has been preserved to prevent scripts from breaking; a +diagnostic message is now required, however, so that users are alerted +that the file characteristics have changed. +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because +implementations may desire more descriptive prompts than those used on +historical implementations. Therefore, an application not using the +.BR \(mif +option or using the +.BR \(mii +option relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.P +When +.IR mv +is dealing with a single file system and +.IR source_file +is a symbolic link, the link itself is moved as a consequence of the +dependence on the +\fIrename\fR() +functionality, per the DESCRIPTION. Across file systems, this has to be +made explicit. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcp\fR\^", +.IR "\fIln\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIrename\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/newgrp.1p b/man-pages-posix-2013-a/man1p/newgrp.1p new file mode 100644 index 0000000..c747daf --- /dev/null +++ b/man-pages-posix-2013-a/man1p/newgrp.1p @@ -0,0 +1,296 @@ +'\" et +.TH NEWGRP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +newgrp +\(em change to a new group +.SH SYNOPSIS +.LP +.nf +newgrp \fB[\fR\(mil\fB] [\fIgroup\fB]\fR +.fi +.SH DESCRIPTION +The +.IR newgrp +utility shall create a new shell execution environment with a new real +and effective group identification. Of the attributes listed in +.IR "Section 2.12" ", " "Shell Execution Environment", +the new shell execution environment shall retain the working directory, +file creation mask, and exported variables from the previous +environment (that is, open files, traps, unexported variables, alias +definitions, shell functions, and +.IR set +options may be lost). All other aspects of the process environment +that are preserved by the +.IR exec +family of functions defined in the System Interfaces volume of POSIX.1\(hy2008 shall also be preserved by +.IR newgrp ; +whether other aspects are preserved is unspecified. +.P +A failure to assign the new group identifications (for example, for +security or password-related reasons) shall not prevent the new shell +execution environment from being created. +.P +The +.IR newgrp +utility shall affect the supplemental groups for the process as +follows: +.IP " *" 4 +On systems where the effective group ID is normally in the +supplementary group list (or whenever the old effective group ID +actually is in the supplementary group list): +.RS 4 +.IP -- 4 +If the new effective group ID is also in the supplementary group list, +.IR newgrp +shall change the effective group ID. +.IP -- 4 +If the new effective group ID is not in the supplementary group list, +.IR newgrp +shall add the new effective group ID to the list, if there is room to +add it. +.RE +.IP " *" 4 +On systems where the effective group ID is not normally in the +supplementary group list (or whenever the old effective group ID is not +in the supplementary group list): +.RS 4 +.IP -- 4 +If the new effective group ID is in the supplementary group list, +.IR newgrp +shall delete it. +.IP -- 4 +If the old effective group ID is not in the supplementary list, +.IR newgrp +shall add it if there is room. +.RE +.TP 10 +.BR Note: +The System Interfaces volume of POSIX.1\(hy2008 does not specify whether the effective group ID of a process +is included in its supplementary group list. +.P +.P +With no operands, +.IR newgrp +shall change the effective group back to the groups identified in the +user's user entry, and shall set the list of supplementary groups to +that set in the user's group database entries. +.P +If the first argument is +.BR '\(mi' , +the results are unspecified. +.P +If a password is required for the specified group, and the user is not +listed as a member of that group in the group database, the user shall +be prompted to enter the correct password for that group. If the user +is listed as a member of that group, no password shall be requested. +If no password is required for the specified group, it is +implementation-defined whether users not listed as members of that +group can change to that group. Whether or not a password is required, +implementation-defined system accounting or security mechanisms may +impose additional authorization restrictions that may cause +.IR newgrp +to write a diagnostic message and suppress the changing of the group +identification. +.SH OPTIONS +The +.IR newgrp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' . +.P +The following option shall be supported: +.IP "\fB\(mil\fP" 10 +(The letter ell.) Change the environment to what would be expected if +the user actually logged in again. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIgroup\fR" 10 +A group name from the group database or a non-negative numeric group +ID. Specifies the group ID to which the real and effective group IDs +shall be set. If +.IR group +is a non-negative numeric string and exists in the group database as a +group name (see +\fIgetgrnam\fR()), +the numeric group ID associated with that group name shall be used as +the group ID. +.SH STDIN +Not used. +.SH "INPUT FILES" +The file +.BR /dev/tty +shall be used to read a single line of text for password checking, when +one is required. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR newgrp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic messages and a prompt +string for a password, if one is required. Diagnostic messages may be +written in cases where the exit status is not available. See the EXIT +STATUS section. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If +.IR newgrp +succeeds in creating a new shell execution environment, whether or not +the group identification was changed successfully, the exit status +shall be the exit status of the shell. Otherwise, the following exit +value shall be returned: +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The invoking shell may terminate. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +There is no convenient way to enter a password into the group +database. Use of group passwords is not encouraged, because by their +very nature they encourage poor security practices. Group passwords +may disappear in the future. +.P +A common implementation of +.IR newgrp +is that the current shell uses +.IR exec +to overlay itself with +.IR newgrp , +which in turn overlays itself with a new shell after changing group. +On some implementations, however, this may not occur and +.IR newgrp +may be invoked as a subprocess. +.P +The +.IR newgrp +command is intended only for use from an interactive terminal. It does +not offer a useful interface for the support of applications. +.P +The exit status of +.IR newgrp +is generally inapplicable. If +.IR newgrp +is used in a script, in most cases it successfully invokes a new shell +and the rest of the original shell script is bypassed when the new +shell exits. Used interactively, +.IR newgrp +displays diagnostic messages to indicate problems. But usage such as: +.sp +.RS 4 +.nf +\fB +newgrp foo +echo $? +.fi \fR +.P +.RE +.P +is not useful because the new shell might not have access to any status +.IR newgrp +may have generated (and most historical systems do not provide this +status). A zero status echoed here does not necessarily indicate that +the user has changed to the new group successfully. Following +.IR newgrp +with the +.IR id +command provides a portable means of determining whether the group +change was successful or not. +.SH EXAMPLES +None. +.SH RATIONALE +Most historical implementations use one of the +.IR exec +functions to implement the behavior of +.IR newgrp . +Errors detected before the +.IR exec +leave the environment unchanged, while errors detected after the +.IR exec +leave the user in a changed environment. While it would be useful to +have +.IR newgrp +issue a diagnostic message to tell the user that the environment +changed, it would be inappropriate to require this change to some +historical implementations. +.P +The password mechanism is allowed in the group database, but how this +would be implemented is not specified. +.P +The +.IR newgrp +utility was retained in this volume of POSIX.1\(hy2008, even given the existence of the multiple +group permissions feature in the System Interfaces volume of POSIX.1\(hy2008, for several reasons. First, in +some implementations, the group ownership of a newly created file is +determined by the group of the directory in which the file is created, +as allowed by the System Interfaces volume of POSIX.1\(hy2008; on other implementations, the group ownership +of a newly created file is determined by the effective group ID. On +implementations of the latter type, +.IR newgrp +allows files to be created with a specific group ownership. Finally, +many implementations use the real group ID in accounting, and on such +systems, +.IR newgrp +allows the accounting identity of the user to be changed. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^", +.IR "\fIgetgrnam\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/nice.1p b/man-pages-posix-2013-a/man1p/nice.1p new file mode 100644 index 0000000..fa1baaa --- /dev/null +++ b/man-pages-posix-2013-a/man1p/nice.1p @@ -0,0 +1,287 @@ +'\" et +.TH NICE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nice +\(em invoke a utility with an altered nice value +.SH SYNOPSIS +.LP +.nf +nice \fB[\fR\(min \fIincrement\fB] \fIutility \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR nice +utility shall invoke a utility, requesting that it be run with a +different nice value (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.240" ", " "Nice Value"). +With no options, the executed utility shall be run with a nice value +that is some implementation-defined quantity greater than or equal to +the nice value of the current process. If the user lacks appropriate +privileges to affect the nice value in the requested manner, the +.IR nice +utility shall not affect the nice value; in this case, a warning +message may be written to standard error, but this shall not prevent +the invocation of +.IR utility +or affect the exit status. +.SH OPTIONS +The +.IR nice +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option is supported: +.IP "\fB\(min\ \fIincrement\fR" 10 +A positive or negative decimal integer which shall have the same +effect on the execution of the utility as if the utility had +called the +\fInice\fR() +function with the numeric value of the +.IR increment +option-argument. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility that is to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +Any string to be supplied as an argument when invoking the utility +named by the +.IR utility +operand. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nice : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path used to locate the utility to be invoked. +See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If +.IR utility +is invoked, the exit status of +.IR nice +shall be the exit status of +.IR utility ; +otherwise, the +.IR nice +utility shall exit with one of the following values: +.IP "1\(hy125" 8 +An error occurred in the +.IR nice +utility. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The only guaranteed portable uses of this utility are: +.IP "\fInice\ utility\fR" 6 +.br +Run +.IR utility +with the default higher or equal nice value. +.IP "\fInice\ \fB\(min\ \fR<\fIpositive\ integer\fR>\fI\ utility\fR" 6 +.br +Run +.IR utility +with a higher nice value. +.P +On some implementations they have no discernible effect on the invoked +utility and on some others they are exactly equivalent. +.P +Historical systems have frequently supported the <\fIpositive +integer\fP> up to 20. Since there is no error penalty associated with +guessing a number that is too high, users without access to the system +conformance document (to see what limits are actually in place) could +use the historical 1 to 20 range or attempt to use very large numbers +if the job should be truly low priority. +.P +The nice value of a process can be displayed using the command: +.sp +.RS 4 +.nf +\fB +ps \(mio nice +.fi \fR +.P +.RE +.P +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +None. +.SH RATIONALE +The 4.3 BSD version of +.IR nice +does not check whether +.IR increment +is a valid decimal integer. The command +.IR nice +.BR \(mix +.IR utility , +for example, would be treated the same as the command +.IR nice +.BR \(mi\|\(mi1 +.IR utility . +If the user does not have appropriate privileges, this results in a +``permission denied'' error. +This is considered a bug. +.P +When a user without appropriate privileges gives a negative +.IR increment , +System V treats it like the command +.IR nice +.BR \(mi0 +.IR utility , +while 4.3 BSD writes a ``permission denied'' message and does not run +the utility. The standard specifies the System V behavior together +with an optional BSD-style ``permission denied'' message. +.P +The C shell has a built-in version of +.IR nice +that has a different interface from the one described in this volume of POSIX.1\(hy2008. +.P +The term ``utility'' is used, rather than ``command'', to highlight the +fact that shell compound commands, pipelines, and so on, cannot be +used. Special built-ins also cannot be used. +However, ``utility'' includes user application programs and shell +scripts, not just utilities defined in this volume of POSIX.1\(hy2008. +.P +Historical implementations of +.IR nice +provide a nice value range of 40 or 41 discrete steps, with the default +nice value being the midpoint of that range. By default, they raise the +nice value of the executed utility by 10. +.P +Some historical documentation states that the +.IR increment +value must be within a fixed range. This is misleading; the valid +.IR increment +values on any invocation are determined by the current process +nice value, which is not always the default. +.P +The definition of nice value is not intended to suggest that all +processes in a system have priorities that are comparable. Scheduling +policy extensions such as the realtime priorities in the System Interfaces volume of POSIX.1\(hy2008 make the +notion of a single underlying priority for all scheduling policies +problematic. Some implementations may implement the +.IR nice -related +features to affect all processes on the system, others to affect just +the general time-sharing activities implied by this volume of POSIX.1\(hy2008, and others may +have no effect at all. Because of the use of +``implementation-defined'' in +.IR nice +and +.IR renice , +a wide range of implementation strategies are possible. +.P +Earlier versions of this standard allowed a +.BR \(mi \c +.IR increment +option. This form is no longer specified by POSIX.1\(hy2008 but may +be present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIrenice\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.240" ", " "Nice Value", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fInice\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/nl.1p b/man-pages-posix-2013-a/man1p/nl.1p new file mode 100644 index 0000000..b5633e1 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/nl.1p @@ -0,0 +1,312 @@ +'\" et +.TH NL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nl +\(em line numbering filter +.SH SYNOPSIS +.LP +.nf +nl \fB[\fR\(mip\fB] [\fR\(mib \fItype\fB] [\fR\(mid \fIdelim\fB] [\fR\(mif \fItype\fB] [\fR\(mih \fItype\fB] [\fR\(mii \fIincr\fB] [\fR\(mil \fInum\fB] + [\fR\(min \fIformat\fB] [\fR\(mis \fIsep\fB] [\fR\(miv \fIstartnum\fB] [\fR\(miw \fIwidth\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR nl +utility shall read lines from the named +.IR file +or the standard input if no +.IR file +is named and shall reproduce the lines to standard output. Lines shall +be numbered on the left. Additional functionality may be provided in +accordance with the command options in effect. +.P +The +.IR nl +utility views the text it reads in terms of logical pages. Line +numbering shall be reset at the start of each logical page. A logical +page consists of a header, a body, and a footer section. Empty sections +are valid. Different line numbering options are independently available +for header, body, and footer (for example, no numbering of header and +footer lines while numbering blank lines only in the body). +.P +The starts of logical page sections shall be signaled by input lines +containing nothing but the following delimiter characters: +.TS +center box tab(@); +cB | cB +lw(1i)f5 | lw(1i). +Line@Start of +_ +\e:\e:\e:@Header +\e:\e:@Body +\e:@Footer +.TE +.P +Unless otherwise specified, +.IR nl +shall assume the text being read is in a single logical page body. +.SH OPTIONS +The +.IR nl +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +Only one file can be named. +.P +The following options shall be supported: +.IP "\fB\(mib\ \fItype\fR" 10 +Specify which logical page body lines shall be numbered. Recognized +.IR types +and their meaning are: +.RS 10 +.IP "\fBa\fP" 8 +Number all lines. +.IP "\fBt\fP" 8 +Number only non-empty lines. +.IP "\fBn\fP" 8 +No line numbering. +.IP "\fBp\fIstring\fR" 8 +Number only lines that contain the basic regular expression +specified in +.IR string . +.P +The default +.IR type +for logical page body shall be +.BR t +(text lines numbered). +.RE +.IP "\fB\(mid\ \fIdelim\fR" 10 +Specify the delimiter characters that indicate the start of a logical +page section. These can be changed from the default characters +.BR \(dq\e:\(dq +to two user-specified characters. If only one character is entered, +the second character shall remain the default character +.BR ':' . +.IP "\fB\(mif\ \fItype\fR" 10 +Specify the same as +.BR b +.IR type +except for footer. The default for logical page footer shall be +.BR n +(no lines numbered). +.IP "\fB\(mih\ \fItype\fR" 10 +Specify the same as +.BR b +.IR type +except for header. The default +.IR type +for logical page header shall be +.BR n +(no lines numbered). +.IP "\fB\(mii\ \fIincr\fR" 10 +Specify the increment value used to number logical page lines. The +default shall be 1. +.IP "\fB\(mil\ \fInum\fR" 10 +Specify the number of blank lines to be considered as one. For +example, +.BR "\(mil\ 2" +results in only the second adjacent blank line being numbered (if the +appropriate +.BR "\(mih\ a" , +.BR "\(mib\ a" , +or +.BR "\(mif\ a" +option is set). The default shall be 1. +.IP "\fB\(min\ \fIformat\fR" 10 +Specify the line numbering format. Recognized values are: +.BR ln , +left justified, leading zeros suppressed; +.BR rn , +right justified, leading zeros suppressed; +.BR rz , +right justified, leading zeros kept. The default +.IR format +shall be +.BR rn +(right justified). +.IP "\fB\(mip\fP" 10 +Specify that numbering should not be restarted at logical page +delimiters. +.IP "\fB\(mis\ \fIsep\fR" 10 +Specify the characters used in separating the line number and the +corresponding text line. The default +.IR sep +shall be a +. +.IP "\fB\(miv\ \fIstartnum\fR" 10 +Specify the initial value used to number logical page lines. The +default shall be 1. +.IP "\fB\(miw\ \fIwidth\fR" 10 +Specify the number of characters to be used for the line number. The +default +.IR width +shall be 6. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to be line-numbered. +.SH STDIN +The standard input shall be used if no +.IR file +operand is specified, and shall be used if the +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nl : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes within regular expressions, and for deciding which +characters are in character class +.BR graph +(for the +.BR "\(mib\ t" , +.BR "\(mif\ t" , +and +.BR "\(mih\ t" +options). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be a text file in the following format: +.sp +.RS 4 +.nf +\fB +"%s%s%s", <\fIline number\fR>, <\fIseparator\fR>, <\fIinput line\fR> +.fi \fR +.P +.RE +.P +where <\fIline\ number\fP> is one of the following numeric formats: +.IP "\fR%6d\fP" 10 +When the +.BR rn +format is used (the default; see +.BR \(min ). +.IP "\fR%06d\fP" 10 +When the +.BR rz +format is used. +.IP "\fR%\(mi6d\fP" 10 +When the +.BR ln +format is used. +.IP 10 +When line numbers are suppressed for a portion of the page; the +<\fIseparator\fP> is also suppressed. +.P +In the preceding list, the number 6 is the default width; the +.BR \(miw +option can change this value. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +In using the +.BR \(mid +.IR delim +option, care should be taken to escape characters that have special +meaning to the command interpreter. +.SH EXAMPLES +The command: +.sp +.RS 4 +.nf +\fB +nl \(miv 10 \(mii 10 \(mid \e!+ file1 +.fi \fR +.P +.RE +.P +numbers +.IR file1 +starting at line number 10 with an increment of 10. The logical page +delimiter is +.BR \(dq!+\(dq . +Note that the +.BR '!' +has to be escaped when using +.IR csh +as a command interpreter because of its history substitution syntax. +For +.IR ksh +and +.IR sh +the escape is not necessary, but does not do any harm. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpr\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/nm.1p b/man-pages-posix-2013-a/man1p/nm.1p new file mode 100644 index 0000000..149a908 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/nm.1p @@ -0,0 +1,405 @@ +'\" et +.TH NM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nm +\(em write the name list of an object file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +nm \fB[\fR\(miAPv\fB] [\fR\(mig|\(miu\fB] [\fR\(mit \fIformat\fB] \fIfile\fR... +nm \fB[\fR\(miAPv\fB] [\fR\(miefox\fB] [\fR\(mig|\(miu\fB] [\fR\(mit \fIformat\fB]\fI file\fR... +.fi +.SH DESCRIPTION +The +.IR nm +utility shall display symbolic information appearing in the object +file, executable file, or object-file library named by +.IR file . +If no symbolic information is available for a valid input file, the +.IR nm +utility shall report that fact, but not consider it an error +condition. +.P +The default base used when numeric values are written is unspecified. +On XSI-conformant systems, it shall be decimal. +.SH OPTIONS +The +.IR nm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miA\fP" 10 +Write the full pathname or library name of an object on each line. +.IP "\fB\(mie\fP" 10 +Write only external (global) and static symbol information. +.IP "\fB\(mif\fP" 10 +Produce full output. Write redundant symbols (\c +.BR .text , +.BR .data , +and +.BR .bss ), +normally suppressed. +.IP "\fB\(mig\fP" 10 +Write only external (global) symbol information. +.IP "\fB\(mio\fP" 10 +Write numeric values in octal (equivalent to +.BR "\(mit\ o" ). +.IP "\fB\(miP\fP" 10 +Write information in a portable output format, as specified in the +STDOUT section. +.IP "\fB\(mit\ \fIformat\fR" 10 +Write each numeric value in the specified format. The format shall be +dependent on the single character used as the +.IR format +option-argument: +.RS 10 +.IP "\fRd\fR" 6 +The offset is written in decimal +(default). +.IP "\fRo\fR" 6 +The offset is written in octal. +.IP "\fRx\fR" 6 +The offset is written in hexadecimal. +.RE +.IP "\fB\(miu\fP" 10 +Write only undefined symbols. +.IP "\fB\(miv\fP" 10 +Sort output by value instead of by symbol name. +.IP "\fB\(mix\fP" 10 +Write numeric values in hexadecimal (equivalent to +.BR "\(mit\ x" ). +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an object file, executable file, or object-file library. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be an object file, an object-file library whose +format is the same as those produced by the +.IR ar +utility for link editing, or an executable file. The +.IR nm +utility may accept additional implementation-defined object library +formats for the input file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for character collation information for the +symbol-name and symbol-value collation sequences. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If symbolic information is present in the input files, then for each +file or for each member of an archive, the +.IR nm +utility shall write the following information to standard output. By +default, the format is unspecified, but the output shall be sorted by +symbol name according to the collation sequence in the current locale. +.IP " *" 4 +Library or object name, if +.BR \(miA +is specified +.IP " *" 4 +Symbol name +.IP " *" 4 +Symbol type, which shall either be one of the following single +characters or an implementation-defined type represented by a single +character: +.RS 4 +.IP "\fRA\fR" 6 +Global absolute symbol. +.IP "\fRa\fR" 6 +Local absolute symbol. +.IP "\fRB\fR" 6 +Global ``bss'' (that is, uninitialized data space) symbol. +.IP "\fRb\fR" 6 +Local bss symbol. +.IP "\fRD\fR" 6 +Global data symbol. +.IP "\fRd\fR" 6 +Local data symbol. +.IP "\fRT\fR" 6 +Global text symbol. +.IP "\fRt\fR" 6 +Local text symbol. +.IP "\fRU\fR" 6 +Undefined symbol. +.RE +.IP " *" 4 +Value of the symbol +.IP " *" 4 +The size associated with the symbol, if applicable +.P +This information may be supplemented by additional information specific +to the implementation. +.P +If the +.BR \(miP +option is specified, the previous information shall be displayed using +the following portable format. The three versions differ depending on +whether +.BR "\(mit\ d" , +.BR "\(mit\ o" , +or +.BR "\(mit\ x" +was specified, respectively: +.sp +.RS 4 +.nf +\fB +"%s%s %s %d %d\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.P +"%s%s %s %o %o\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.P +"%s%s %s %x %x\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.fi \fR +.P +.RE +where <\fIlibrary/object\ name\fP> shall be formatted as follows: +.IP " *" 4 +If +.BR \(miA +is not specified, <\fIlibrary/object\ name\fP> shall be an empty string. +.IP " *" 4 +If +.BR \(miA +is specified and the corresponding +.IR file +operand does not name a library: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s: ", <\fIfile\fR> +.fi \fR +.P +.RE +.RE +.IP " *" 4 +If +.BR \(miA +is specified and the corresponding +.IR file +operand names a library. In this case, <\fIobject\ file\fP> shall name +the object file in the library containing the symbol being described: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s[%s]: ", <\fIfile\fR>, <\fIobject file\fR> +.fi \fR +.P +.RE +.RE +.P +If +.BR \(miA +is not specified, then if more than one +.IR file +operand is specified or if only one +.IR file +operand is specified and it names a library, +.IR nm +shall write a line identifying the object containing the following +symbols before the lines containing those symbols, in the form: +.IP " *" 4 +If the corresponding +.IR file +operand does not name a library: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIfile\fR> +.fi \fR +.P +.RE +.RE +.IP " *" 4 +If the corresponding +.IR file +operand names a library; in this case, <\fIobject\ file\fP> shall be +the name of the file in the library containing the following symbols: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s[%s]:\en", <\fIfile\fR>, <\fIobject file\fR> +.fi \fR +.P +.RE +.RE +.P +If +.BR \(miP +is specified, but +.BR \(mit +is not, the format shall be as if +.BR "\(mit\ x" +had been specified. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Mechanisms for dynamic linking make this utility less meaningful when +applied to an executable file because a dynamically linked executable +may omit numerous library routines that would be found in a statically +linked executable. +.SH EXAMPLES +None. +.SH RATIONALE +Historical implementations of +.IR nm +have used different bases for numeric output and supplied different +default types of symbols that were reported. The +.BR \(mit +.IR format +option, similar to that used in +.IR od +and +.IR strings , +can be used to specify the numeric base; +.BR \(mig +and +.BR \(miu +can be used to restrict the amount of output or the types of symbols +included in the output. +.P +The compromise of using +.BR \(mit +.IR format +\fIversus\fP using +.BR \(mid , +.BR \(mio , +and other similar options was necessary because of differences in the +meaning of +.BR \(mio +between implementations. The +.BR \(mio +option from BSD has been provided here as +.BR \(miA +to avoid confusion with the +.BR \(mio +from System V (which has been provided here as +.BR \(mit +and as +.BR \(mio +on XSI-conformant systems). +.P +The option list was significantly reduced from that provided by +historical implementations. +.P +The +.IR nm +description is a subset of both the System V and BSD +.IR nm +utilities with no specified default output. +.P +It was recognized that mechanisms for dynamic linking make this utility +less meaningful when applied to an executable file (because a +dynamically linked executable file may omit numerous library routines +that would be found in a statically linked executable file), but the +value of +.IR nm +during software development was judged to outweigh other limitations. +.P +The default output format of +.IR nm +is not specified because of differences in historical implementations. +The +.BR \(miP +option was added to allow some type of portable output format. After a +comparison of the different formats used in SunOS, BSD, SVR3, and SVR4, +it was decided to create one that did not match the current format of +any of these four systems. The format devised is easy to parse by +humans, easy to parse in shell scripts, and does not need to vary +depending on locale (because no English descriptions are included). +All of the systems currently have the information available to use this +format. +.P +The format given in +.IR nm +STDOUT uses + +characters between the fields, which may be any number of + +characters required to align the columns. The single-character types +were selected to match historical practice, and the requirement that +implementation additions also be single characters made parsing the +information easier for shell scripts. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/nohup.1p b/man-pages-posix-2013-a/man1p/nohup.1p new file mode 100644 index 0000000..13e18f5 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/nohup.1p @@ -0,0 +1,311 @@ +'\" et +.TH NOHUP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nohup +\(em invoke a utility immune to hangups +.SH SYNOPSIS +.LP +.nf +nohup \fIutility \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR nohup +utility shall invoke the utility named by the +.IR utility +operand with arguments supplied as the +.IR argument +operands. At the time the named +.IR utility +is invoked, the SIGHUP signal shall be set to be ignored. +.P +If standard input is associated with a terminal, the +.IR nohup +utility may redirect standard input from an unspecified file. +.P +If the standard output is a terminal, all output written by the named +.IR utility +to its standard output shall be appended to the end of the file +.BR nohup.out +in the current directory. If +.BR nohup.out +cannot be created or opened for appending, the output shall be appended +to the end of the file +.BR nohup.out +in the directory specified by the +.IR HOME +environment variable. If neither file can be created or opened for +appending, +.IR utility +shall not be invoked. If a file is created, the file's permission bits +shall be set to S_IRUSR | S_IWUSR. +.P +If standard error is a terminal and standard output is open but is not +a terminal, all output written by the named utility to its standard +error shall be redirected to the same open file description as the +standard output. If standard error is a terminal and standard output +either is a terminal or is closed, the same output shall instead be +appended to the end of the +.BR nohup.out +file as described above. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility that is to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +Any string to be supplied as an argument when invoking the utility +named by the +.IR utility +operand. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nohup : +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory: if the output +file +.BR nohup.out +cannot be created in the current directory, the +.IR nohup +utility shall use the directory named by +.IR HOME +to create the file. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path that is used to locate the utility to be +invoked. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +The +.IR nohup +utility shall take the standard action for all signals except that +SIGHUP shall be ignored. +.SH STDOUT +If the standard output is not a terminal, the standard output of +.IR nohup +shall be the standard output generated by the execution of the +.IR utility +specified by the operands. Otherwise, nothing shall be written to the +standard output. +.SH STDERR +If the standard output is a terminal, a message shall be written to the +standard error, indicating the name of the file to which the output is +being appended. The name of the file shall be either +.BR nohup.out +or +.BR $HOME/nohup.out . +.SH "OUTPUT FILES" +Output written by the named utility is appended to the file +.BR nohup.out +(or +.BR $HOME/nohup.out ), +if the conditions hold as described in the DESCRIPTION. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP 126 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP 127 8 +An error occurred in the +.IR nohup +utility or the utility specified by +.IR utility +could not be found. +.P +Otherwise, the exit status of +.IR nohup +shall be that of the utility specified by the +.IR utility +operand. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +It is frequently desirable to apply +.IR nohup +to pipelines or lists of commands. This can be done by placing +pipelines and command lists in a single file; this file can then be +invoked as a utility, and the +.IR nohup +applies to everything in the file. +.P +Alternatively, the following command can be used to apply +.IR nohup +to a complex command: +.sp +.RS 4 +.nf +\fB +nohup sh \(mic '\fIcomplex-command-line\fP' +(\c +.BR '*' ). +.IP "\fB\(mix\fP" 10 +Interpret +.IR word s +(two-byte units) in hexadecimal. This shall be equivalent to +.BR "\(mit\ x2" . +.P +Multiple types can be specified by using multiple +.BR \(mibcdostx +options. Output lines are written for each type specified in the order +in which the types are specified. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be read. If no +.IR file +operands are specified, the standard input shall be used. +.RS 10 +.P +If there are no more than two operands, none of the +.BR \(miA , +.BR \(mij , +.BR \(miN , +.BR \(mit , +or +.BR \(miv +options is specified, and either of the following is true: the first +character of the last operand is a + +(\c +.BR '\(pl' ), +or there are two operands and the first character of the last operand +is numeric; +the last operand shall be interpreted as an offset operand on +XSI-conformant systems. +Under these conditions, the results are unspecified on systems that are +not XSI-conformant systems. +.RE +.IP "\fB[+]\fIoffset\fB[.][b]\fR" 10 +The +.IR offset +operand specifies the offset in the file where dumping is to commence. +This operand is normally interpreted as octal bytes. If +.BR '.' +is appended, the offset shall be interpreted in decimal. If +.BR 'b' +is appended, the offset shall be interpreted in units of 512 bytes. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR od : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for selecting the radix character used when +writing floating-point formatted output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the EXTENDED DESCRIPTION section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The +.IR od +utility shall copy sequentially each input file to standard output, +transforming the input data according to the output types specified by +the +.BR \(mit +option +or the +.BR \(mibcdosx +options. +If no output type is specified, the default output shall be as if +.BR "\(mit\ oS" +had been specified. +.P +The number of bytes transformed by the output type specifier +.BR c +may be variable depending on the +.IR LC_CTYPE +category. +.P +The default number of bytes transformed by output type specifiers +.BR d , +.BR f , +.BR o , +.BR u , +and +.BR x +corresponds to the various C-language types as follows. If the +.IR c99 +compiler is present on the system, these specifiers shall correspond to +the sizes used by default in that compiler. Otherwise, these sizes +may vary among systems that conform to POSIX.1\(hy2008. +.IP " *" 4 +For the type specifier characters +.BR d , +.BR o , +.BR u , +and +.BR x , +the default number of bytes shall correspond to the size of the +underlying implementation's basic integer type. For these specifier +characters, the implementation shall support values of the optional +number of bytes to be converted corresponding to the number of bytes in +the C-language types +.BR char , +.BR short , +.BR int , +and +.BR long . +These numbers can also be specified by an application as the characters +.BR 'C' , +.BR 'S' , +.BR 'I' , +and +.BR 'L' , +respectively. The implementation shall also support the values 1, 2, 4, +and 8, even if it provides no C-Language types of those sizes. The +implementation shall support the decimal value corresponding to the +C-language type +.BR "long long" . +The byte order used when interpreting numeric values is +implementation-defined, but shall correspond to the order in which a +constant of the corresponding type is stored in memory on the system. +.IP " *" 4 +For the type specifier character +.BR f , +the default number of bytes shall correspond to the number of bytes in +the underlying implementation's basic double precision floating-point +data type. The implementation shall support values of the optional +number of bytes to be converted corresponding to the number of bytes in +the C-language types +.BR float, +.BR double , +and +.BR "long double" . +These numbers can also be specified by an application as the characters +.BR 'F' , +.BR 'D' , +and +.BR 'L' , +respectively. +.P +The type specifier character +.BR a +specifies that bytes shall be interpreted as named characters from the +International Reference Version (IRV) of the ISO/IEC\ 646:\|1991 standard. Only the least +significant seven bits of each byte shall be used for this type +specification. Bytes with the values listed in the following table +shall be written using the corresponding names for those characters. +.br +.sp +.ce 1 +\fBTable: Named Characters in \fIod\fP\fR +.TS +center box tab(@); +cB cB | cB cB | cB cB | cB cB +l lb | l lb | l lb | l lb. +Value@Name@Value@Name@Value@Name@Value@Name +_ +\e000@nul@\e001@soh@\e002@stx@\e003@etx +\e004@eot@\e005@enq@\e006@ack@\e007@bel +\e010@bs@\e011@ht@\e012@lf \fRor\fP nl\u\s-3*\s+3\d@\e013@vt +\e014@ff@\e015@cr@\e016@so@\e017@si +\e020@dle@\e021@dc1@\e022@dc2@\e023@dc3 +\e024@dc4@\e025@nak@\e026@syn@\e027@etb +\e030@can@\e031@em@\e032@sub@\e033@esc +\e034@fs@\e035@gs@\e036@rs@\e037@us +\e040@sp@\e177@del +.TE +.TP 10 +.BR Note: +The +.BR \(dq\e012\(dq +value may be written either as +.BR lf +or +.BR nl . +.P +.P +The type specifier character +.BR c +specifies that bytes shall be interpreted as characters specified by +the current setting of the +.IR LC_CTYPE +locale category. Characters listed in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +shall be written as the corresponding escape sequences, except that + +shall be written as a single + +and a NUL shall be written as +.BR '\e0' . +Other non-printable characters shall be written as one three-digit +octal number for each byte in the character. Printable multi-byte +characters shall be written in the area corresponding to the first byte +of the character; the two-character sequence +.BR \(dq**\(dq +shall be written in the area corresponding to each remaining byte in +the character, as an indication that the character is continued. When +either the +.BR \(mij +.IR skip +or +.BR \(miN +.IR count +option is specified along with the +.BR c +type specifier, and this results in an attempt to start or finish in +the middle of a multi-byte character, the result is +implementation-defined. +.P +The input data shall be manipulated in blocks, where a block is defined +as a multiple of the least common multiple of the number of bytes +transformed by the specified output types. If the least common +multiple is greater than 16, the results are unspecified. Each input +block shall be written as transformed by each output type, one per +written line, in the order that the output types were specified. If +the input block size is larger than the number of bytes transformed by +the output type, the output type shall sequentially transform the parts +of the input block, and the output from each of the transformations +shall be separated by one or more + +characters. +.P +If, as a result of the specification of the +.BR \(miN +option or end-of-file being reached on the last input file, input data +only partially satisfies an output type, the input shall be extended +sufficiently with null bytes to write the last byte of the input. +.P +Unless +.BR "\(miA\ n" +is specified, the first output line produced for each input block shall +be preceded by the input offset, cumulative across input files, of the +next byte to be written. The format of the input offset is unspecified; +however, it shall not contain any + +characters, shall start at the first character of the output line, +and shall be followed by one or more + +characters. In addition, the offset of the byte following the last byte +written shall be written after all the input data has been processed, +but shall not be followed by any + +characters. +.P +If no +.BR \(miA +option is specified, the input offset base is unspecified. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +XSI-conformant applications are warned not to use filenames starting +with +.BR '\(pl' +or a first operand starting with a numeric character so that the old +functionality can be maintained by implementations, unless they specify +one of the +.BR \(miA , +.BR \(mij , +or +.BR \(miN +options. To guarantee that one of these filenames is always +interpreted as a filename, an application could always specify the +address base format with the +.BR \(miA +option. +.SH EXAMPLES +If a file containing 128 bytes with decimal values zero to 127, in +increasing order, is supplied as standard input to the command: +.sp +.RS 4 +.nf +\fB +od \(miA d \(mit a +.fi \fR +.P +.RE +.P +on an implementation using an input block size of 16 bytes, the +standard output, independent of the current locale setting, would be +similar to: +.sp +.RS 4 +.nf +\fB +0000000 nul soh stx etx eot enq ack bel bs ht nl vt ff cr so si +0000016 dle dc1 dc2 dc3 dc4 nak syn etb can em sub esc fs gs rs us +0000032 sp ! " # $ % & ' ( ) * + , \(mi . / +0000048 0 1 2 3 4 5 6 7 8 9 : ; < = > ? +0000064 @ A B C D E F G H I J K L M N O +0000080 P Q R S T U V W X Y Z [ \e ] ^ _ +0000096 ` a b c d e f g h i j k l m n o +0000112 p q r s t u v w x y z { | } ~ del +0000128 +.fi \fR +.P +.RE +.P +Note that this volume of POSIX.1\(hy2008 allows +.BR nl +or +.BR lf +to be used as the name for the ISO/IEC\ 646:\|1991 standard IRV character with decimal value +10. The IRV names this character +.BR lf +(line feed), but traditional implementations have referred to this +character as newline +(\c +.BR nl ) +and the POSIX locale character set symbolic name for the corresponding +character is a +. +.P +The command: +.sp +.RS 4 +.nf +\fB +od \(miA o \(mit o2x2x \(miN 18 +.fi \fR +.P +.RE +.P +on a system with 32-bit words and an implementation using an input +block size of 16 bytes could write 18 bytes in approximately the +following format: +.sp +.RS 4 +.nf +\fB +0000000 032056 031440 041123 042040 052516 044530 020043 031464 + 342e 3320 4253 4420 554e 4958 2023 3334 + 342e3320 42534420 554e4958 20233334 +0000020 032472 + 353a + 353a0000 +0000022 +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +od \(miA d \(mit f \(mit o4 \(mit x4 \(miN 24 \(mij 0x15 +.fi \fR +.P +.RE +.P +on a system with 64-bit doubles (for example, IEEE\ Std\ 754\(hy1985 double +precision floating-point format) would skip 21 bytes of input data and +then write 24 bytes in approximately the following format: +.sp +.RS 4 +.nf +\fB +0000000 1.00000000000000e+00 1.57350000000000e+01 + 07774000000 00000000000 10013674121 35341217270 + 3ff00000 00000000 402f3851 eb851eb8 +0000016 1.40668230000000e+02 + 10030312542 04370303230 + 40619562 23e18698 +0000024 +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR od +utility went through several names in early proposals, including +.IR hd , +.IR xd , +and most recently +.IR hexdump . +There were several objections to all of these based on the following +reasons: +.IP " *" 4 +The +.IR hd +and +.IR xd +names conflicted with historical utilities that behaved differently. +.IP " *" 4 +The +.IR hexdump +description was much more complex than needed for a simple dump +utility. +.IP " *" 4 +The +.IR od +utility has been available on all historical implementations and there +was no need to create a new name for a utility so similar to the +historical +.IR od +utility. +.P +The original reasons for not standardizing historical +.IR od +were also fairly widespread. Those reasons are given below along with +rationale explaining why the standard developers believe that this +version does not suffer from the indicated problem: +.IP " *" 4 +The BSD and System V versions of +.IR od +have diverged, and the intersection of features provided by both does +not meet the needs of the user community. In fact, the System V +version only provides a mechanism for dumping octal bytes and +.BR short s, +signed and unsigned decimal +.BR short s, +hexadecimal +.BR short s, +and ASCII characters. BSD added the ability to dump +.BR float s, +.BR double s, +named ASCII characters, and octal, signed decimal, unsigned decimal, +and hexadecimal +.BR long s. +The version presented here provides more normalized forms for dumping +bytes, +.BR short s, +.BR int s, +and +.BR long s +in octal, signed decimal, unsigned decimal, and hexadecimal; +.BR float , +.BR double , +and +.BR "long double" ; +and named ASCII as well as current locale characters. +.IP " *" 4 +It would not be possible to come up with a compatible superset of the +BSD and System V flags that met the requirements of the standard +developers. The historical default +.IR od +output is the specified default output of this utility. None of the +option letters chosen for this version of +.IR od +conflict with any of the options to historical versions of +.IR od . +.IP " *" 4 +On systems with different sizes for +.BR short , +.BR int , +and +.BR long , +there was no way to ask for dumps of +.BR int s, +even in the BSD version. Because of the way options are named, the +name space could not be extended to solve these problems. This is why +the +.BR \(mit +option was added (with type specifiers more closely matched to the +\fIprintf\fR() +formats used in the rest of this volume of POSIX.1\(hy2008) and the optional field sizes were +added to the +.BR d , +.BR f , +.BR o , +.BR u , +and +.BR x +type specifiers. It is also one of the reasons why the historical +practice was not mandated as a required obsolescent form of +.IR od . +(Although the old versions of +.IR od +are not listed as an obsolescent form, implementations are urged to +continue to recognize the older forms for several more years.) The +.BR a , +.BR c , +.BR f , +.BR o , +and +.BR x +types match the meaning of the corresponding format characters in the +historical implementations of +.IR od +except for the default sizes of the fields converted. The +.BR d +format is signed in this volume of POSIX.1\(hy2008 to match the +\fIprintf\fR() +notation. (Historical versions of +.IR od +used +.BR d +as a synonym for +.BR u +in this version. The System V implementation uses +.BR s +for signed decimal; BSD uses +.BR i +for signed decimal and +.BR s +for null-terminated strings.) Other than +.BR d +and +.BR u , +all of the type specifiers match format characters in the historical +BSD version of +.BR od . +.RS 4 +.P +The sizes of the C-language types +.BR char , +.BR short , +.BR int , +.BR long , +.BR float , +.BR double , +and +.BR "long double" +are used even though it is recognized that there may be zero or more +than one compiler for the C language on an implementation and that they +may use different sizes for some of these types. (For example, one +compiler might use 2 bytes +.BR short s, +2 bytes +.BR int s, +and 4 bytes +.BR long s, +while another compiler (or an option to the same compiler) uses 2 bytes +.BR short s, +4 bytes +.BR int s, +and 4 bytes +.BR long s.) +Nonetheless, there has to be a basic size known by the implementation +for these types, corresponding to the values reported by invocations of +the +.IR getconf +utility when called with +.IR system_var +operands +{UCHAR_MAX}, +{USHORT_MAX}, +{UINT_MAX}, +and +{ULONG_MAX} +for the types +.BR char , +.BR short , +.BR int , +and +.BR long , +respectively. There are similar constants required by the ISO\ C standard, but +not required by the System Interfaces volume of POSIX.1\(hy2008 or this volume of POSIX.1\(hy2008. They are +{FLT_MANT_DIG}, +{DBL_MANT_DIG}, +and +{LDBL_MANT_DIG} +for the types +.BR float , +.BR double , +and +.BR "long double" , +respectively. If the optional +.IR c99 +utility is provided by the implementation and used as specified by +\&this volume of POSIX.1\(hy2008, these are the sizes that would be provided. If an option is used +that specifies different sizes for these types, there is no guarantee +that the +.IR od +utility is able to interpret binary data output by such a program +correctly. +.P +This volume of POSIX.1\(hy2008 requires that the numeric values of these lengths be recognized +by the +.IR od +utility and that symbolic forms also be recognized. Thus, a conforming +application can always look at an array of +.BR "unsigned long" +data elements using +.IR od +.BR \(mit +.IR uL . +.RE +.IP " *" 4 +The method of specifying the format for the address field based on +specifying a starting offset in a file unnecessarily tied the two +together. The +.BR \(miA +option now specifies the address base and the +.BR \(miS +option specifies a starting offset. +.IP " *" 4 +It would be difficult to break the dependence on US ASCII to achieve +an internationalized utility. It does not seem to be any harder for +.IR od +to dump characters in the current locale than it is for the +.IR ed +or +.IR sed +.BR l +commands. The +.BR c +type specifier does this without difficulty and is completely +compatible with the historical implementations of the +.BR c +format character when the current locale uses a superset of the ISO/IEC\ 646:\|1991 standard +as a codeset. The +.BR a +type specifier (from the BSD +.BR a +format character) was left as a portable means to dump ASCII (or more +correctly ISO/IEC\ 646:\|1991 standard (IRV)) so that headers produced by +.IR pax +could be deciphered even on systems that do not use the ISO/IEC\ 646:\|1991 standard as a +subset of their base codeset. +.P +The use of +.BR \(dq**\(dq +as an indication of continuation of a multi-byte character in +.BR c +specifier output was chosen based on seeing an implementation that uses +this method. The continuation bytes have to be marked in a way that is +not ambiguous with another single-byte or multi-byte character. +.P +An early proposal used +.BR \(miS +and +.BR \(min , +respectively, for the +.BR \(mij +and +.BR \(miN +options eventually selected. These were changed to avoid conflicts with +historical implementations. +.P +The original standard specified +.BR "\(mit o2" +as the default when no output type was given. This was changed to +.BR "\(mit oS" +(the length of a +.BR short ) +to accommodate a supercomputer implementation that historically used 64 +bits as its default (and that defined shorts as 64 bits). This change +should not affect conforming applications. The requirement to support +lengths of 1, 2, and 4 was added at the same time to address an +historical implementation that had no two-byte data types in its C +compiler. +.P +The use of a basic integer data type is intended to allow the +implementation to choose a word size commonly used by applications +on that architecture. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +All option and operand interfaces marked XSI may be removed +in a future version. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/paste.1p b/man-pages-posix-2013-a/man1p/paste.1p new file mode 100644 index 0000000..10e9e64 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/paste.1p @@ -0,0 +1,365 @@ +'\" et +.TH PASTE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +paste +\(em merge corresponding or subsequent lines of files +.SH SYNOPSIS +.LP +.nf +paste \fB[\fR\(mis\fB] [\fR\(mid \fIlist\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR paste +utility shall concatenate the corresponding lines of the given input +files, and write the resulting lines to standard output. +.P +The default operation of +.IR paste +shall concatenate the corresponding lines of the input files. The + +of every line except the line from the last input file shall be +replaced with a +. +.P +If an end-of-file condition is detected on one or more input files, but +not all input files, +.IR paste +shall behave as though empty lines were read from the files on which +end-of-file was detected, unless the +.BR \(mis +option is specified. +.SH OPTIONS +The +.IR paste +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mid\ \fIlist\fR" 10 +Unless a + +character appears in +.IR list , +each character in +.IR list +is an element specifying a delimiter character. If a + +character appears in +.IR list , +the + +character and one or more characters following it are an element +specifying a delimiter character as described below. These elements +specify one or more delimiters to use, instead of the default +, +to replace the + +of the input lines. The elements in +.IR list +shall be used circularly; that is, when the list is exhausted the first +element from the list is reused. When the +.BR \(mis +option is specified: +.RS 10 +.IP " *" 4 +The last + +in a file shall not be modified. +.IP " *" 4 +The delimiter shall be reset to the first element of +.IR list +after each +.IR file +operand is processed. +.P +When the +.BR \(mis +option is not specified: +.IP " *" 4 +The + +characters in the file specified by the last +.IR file +operand shall not be modified. +.IP " *" 4 +The delimiter shall be reset to the first element of list each time a +line is processed from each file. +.P +If a + +character appears in +.IR list , +it and the character following it shall be used to represent the +following delimiter characters: +.IP "\fR\en\fR" 6 +. +.IP "\fR\et\fR" 6 +. +.IP "\fR\e\e\fR" 6 + +character. +.IP "\fR\e0\fR" 6 +Empty string (not a null character). If +.BR '\e0' +is immediately followed by the character +.BR 'x' , +the character +.BR 'X' , +or any character defined by the +.IR LC_CTYPE +.BR digit +keyword (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale"), +the results are unspecified. +.P +If any other characters follow the +, +the results are unspecified. +.RE +.IP "\fB\(mis\fP" 10 +Concatenate all of the lines of each separate input file in command +line order. The + +of every line except the last line in each input file shall be replaced +with the +, +unless otherwise specified by the +.BR \(mid +option. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If +.BR '\(mi' +is specified for one or more of the +.IR file s, +the standard input shall be used; the standard input shall be read one +line at a time, circularly, for each instance of +.BR '\(mi' . +Implementations shall support pasting of at least 12 +.IR file +operands. +.SH STDIN +The standard input shall be used only if one or more +.IR file +operands is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files, except that line lengths shall be +unlimited. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR paste : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Concatenated lines of input files shall be separated by the + +(or other characters under the control of the +.BR \(mid +option) and terminated by a +. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If one or more input files cannot be opened when the +.BR \(mis +option is not specified, a diagnostic message shall be written to +standard error, but no output is written to standard output. If the +.BR \(mis +option is specified, the +.IR paste +utility shall provide the default behavior described in +.IR "Section 1.4" ", " "Utility Description Defaults". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +When the escape sequences of the +.IR list +option-argument are used in a shell script, they must be quoted; +otherwise, the shell treats the + +as a special character. +.P +Conforming applications should only use the specific +-escaped +delimiters presented in this volume of POSIX.1\(hy2008. Historical implementations treat +.BR '\ex' , +where +.BR 'x' +is not in this list, as +.BR 'x' , +but future implementations are free to expand this list to recognize +other common escapes similar to those accepted by +.IR printf +and other standard utilities. +.P +Most of the standard utilities work on text files. The +.IR cut +utility can be used to turn files with arbitrary line lengths into a +set of text files containing the same data. The +.IR paste +utility can be used to create (or recreate) files with arbitrary line +lengths. For example, if +.IR file +contains long lines: +.sp +.RS 4 +.nf +\fB +cut \(mib 1\(mi500 \(min file > file1 +cut \(mib 501\(mi \(min file > file2 +.fi \fR +.P +.RE +.P +creates +.BR file1 +(a text file) with lines no longer than 500 bytes (plus the +) +and +.BR file2 +that contains the remainder of the data from +.IR file . +Note that +.BR file2 +is not a text file if there are lines in +.IR file +that are longer than 500 + +{LINE_MAX} +bytes. The original file can be recreated from +.BR file1 +and +.BR file2 +using the command: +.sp +.RS 4 +.nf +\fB +paste \(mid "\e0" file1 file2 > file +.fi \fR +.P +.RE +.P +The commands: +.sp +.RS 4 +.nf +\fB +paste \(mid "\e0" ... +paste \(mid "" ... +.fi \fR +.P +.RE +.P +are not necessarily equivalent; the latter is not specified by this volume of POSIX.1\(hy2008 +and may result in an error. The construct +.BR '\e0' +is used to mean ``no separator'' because historical versions of +.IR paste +did not follow the syntax guidelines, and the command: +.sp +.RS 4 +.nf +\fB +paste \(mid"" ... +.fi \fR +.P +.RE +.P +could not be handled properly by +\fIgetopt\fR(). +.SH EXAMPLES +.IP " 1." 4 +Write out a directory in four columns: +.RS 4 +.sp +.RS 4 +.nf +\fB +ls | paste \(mi \(mi \(mi \(mi +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Combine pairs of lines from a file into single lines: +.RS 4 +.sp +.RS 4 +.nf +\fB +paste \(mis \(mid "\et\en" file +.fi \fR +.P +.RE +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.4" ", " "Utility Description Defaults", +.IR "\fIcut\fR\^", +.IR "\fIgrep\fR\^", +.IR "\fIpr\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/patch.1p b/man-pages-posix-2013-a/man1p/patch.1p new file mode 100644 index 0000000..67243ba --- /dev/null +++ b/man-pages-posix-2013-a/man1p/patch.1p @@ -0,0 +1,713 @@ +'\" et +.TH PATCH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +patch +\(em apply changes to files +.SH SYNOPSIS +.LP +.nf +patch \fB[\fR\(miblNR\fB] [\fR\(mic|\(mie|\(min|\(miu\fB] [\fR\(mid \fIdir\fB] [\fR\(miD \fIdefine\fB] [\fR\(mii \fIpatchfile\fB] + [\fR\(mio \fIoutfile\fB] [\fR\(mip \fInum\fB] [\fR\(mir \fIrejectfile\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR patch +utility shall read a source (patch) file containing any of four +forms of difference (diff) listings produced by the +.IR diff +utility (normal, copied context, unified context, or in the style of +.IR ed ) +and apply those differences to a file. By default, +.IR patch +shall read from the standard input. +.P +The +.IR patch +utility shall attempt to determine the type of the +.IR diff +listing, unless overruled by a +.BR \(mic , +.BR \(mie , +.BR \(min , +or +.BR \(miu +option. +.P +If the patch file contains more than one patch, +.IR patch +shall attempt to apply each of them as if they came from separate patch +files. (In this case, the application shall ensure that the name of the +patch file is determinable for each +.IR diff +listing.) +.SH OPTIONS +The +.IR patch +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mib\fP" 10 +Save a copy of the original contents of each modified file, before the +differences are applied, in a file of the same name with the suffix +.BR .orig +appended to it. If the file already exists, it shall be overwritten; +if multiple patches are applied to the same file, the +.BR .orig +file shall be written only for the first patch. When the +.BR \(mio +.IR outfile +option is also specified, +.IR file \c +.BR .orig +shall not be created but, if +.IR outfile +already exists, +.IR outfile \c +.BR .orig +shall be created. +.IP "\fB\(mic\fP" 10 +Interpret the patch file as a copied context difference (the output +of the utility +.IR diff +when the +.BR \(mic +or +.BR \(miC +options are specified). +.IP "\fB\(mid\ \fIdir\fR" 10 +Change the current directory to +.IR dir +before processing as described in the EXTENDED DESCRIPTION section. +.IP "\fB\(miD\ \fIdefine\fR" 10 +Mark changes with one of the following C preprocessor constructs: +.RS 10 +.sp +.RS 4 +.nf +\fB +#ifdef define +\&... +#endif +.P +#ifndef define +\&... +#endif +.fi \fR +.P +.RE +.P +optionally combined with the C preprocessor construct +.BR #else . +If the patched file is processed with the C preprocessor, where the +macro +.IR define +is defined, the output shall contain the changes from the patch file; +otherwise, the output shall not contain the patches specified in the +patch file. +.RE +.IP "\fB\(mie\fP" 10 +Interpret the patch file as an +.IR ed +script, rather than a +.IR diff +script. +.IP "\fB\(mii\ \fIpatchfile\fR" 10 +Read the patch information from the file named by the pathname +.IR patchfile , +rather than the standard input. +.IP "\fB\(mil\fP" 10 +(The letter ell.) Cause any sequence of + +characters in the difference script to match any sequence of + +characters in the input file. Other characters shall be matched exactly. +.IP "\fB\(min\fP" 10 +Interpret the script as a normal difference. +.IP "\fB\(miN\fP" 10 +Ignore patches where the differences have already been applied to the +file; by default, already-applied patches shall be rejected. +.IP "\fB\(mio\ \fIoutfile\fR" 10 +Instead of modifying the files (specified by the +.IR file +operand or the difference listings) directly, write a copy of the file +referenced by each patch, with the appropriate differences applied, to +.IR outfile . +Multiple patches for a single file shall be applied to the intermediate +versions of the file created by any previous patches, and shall result +in multiple, concatenated versions of the file being written to +.IR outfile . +.IP "\fB\(mip\ \fInum\fR" 10 +For all pathnames in the patch file that indicate the names of files to +be patched, delete +.IR num +pathname components from the beginning of each pathname. If the +pathname in the patch file is absolute, any leading + +characters shall be considered the first component (that is, +.BR "\(mip\ 1" +shall remove the leading + +characters). Specifying +.BR "\(mip\ 0" +shall cause the full pathname to be used. If +.BR \(mip +is not specified, only the basename (the final pathname component) +shall be used. +.IP "\fB\(miR\fP" 10 +Reverse the sense of the patch script; that is, assume that the +difference script was created from the new version to the old version. +The +.BR \(miR +option cannot be used with +.IR ed +scripts. The +.IR patch +utility shall attempt to reverse each portion of the script before +applying it. Rejected differences shall be saved in swapped format. If +this option is not specified, and until a portion of the patch file is +successfully applied, +.IR patch +attempts to apply each portion in its reversed sense as well as in its +normal sense. If the attempt is successful, the user shall be prompted +to determine whether the +.BR \(miR +option should be set. +.IP "\fB\(mir\ \fIrejectfile\fR" 10 +Override the default reject filename. In the default case, the reject +file shall have the same name as the output file, with the suffix +.BR .rej +appended to it; see +.IR "Patch Application". +.IP "\fB\(miu\fR" 10 +Interpret the patch file as a unified context difference (the output +of the +.IR diff +utility when the +.BR \(miu +or +.BR \(miU +options are specified). +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to patch. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR patch : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of text +data as characters (for example, single-byte as opposed to multi-byte +characters in arguments and input files), and the behavior of character +classes used in the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fILC_TIME\fP" 10 +Determine the locale for recognizing the format of file timestamps +written by the +.IR diff +utility in a context-difference input file. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic and informational +messages. +.SH "OUTPUT FILES" +The output of the +.IR patch +utility, the save files (\c +.BR .orig +suffixes), and the reject files (\c +.BR .rej +suffixes) shall be text files. +.SH "EXTENDED DESCRIPTION" +A patch file may contain patching instructions for more than one file; +filenames shall be determined as specified in +.IR "Filename Determination". +When the +.BR \(mib +option is specified, for each patched file, the original shall be saved +in a file of the same name with the suffix +.BR .orig +appended to it. +.P +For each patched file, a reject file may also be created as noted in +.IR "Patch Application". +In the absence of a +.BR \(mir +option, the name of this file shall be formed by appending the suffix +.BR .rej +to the original filename. +.SS "Patch File Format" +.P +The patch file shall contain zero or more lines of header information +followed by one or more patches. Each patch shall contain zero or more +lines of filename identification in the format produced by the +.BR \(mic , +.BR \(miC , +.BR \(miu , +or +.BR \(miU +options of the +.IR diff +utility, and one or more sets of +.IR diff +output, which are customarily called \fIhunks\fP. +.P +The +.IR patch +utility shall recognize the following expression in the header +information: +.IP "\fBIndex:\ \fIpathname\fR" 6 +.br +The file to be patched is named +.IR pathname . +.P +If all lines (including headers) within a patch begin with the same +leading sequence of + +characters, the +.IR patch +utility shall remove this sequence before proceeding. Within each +patch, if the type of difference is common context, the +.IR patch +utility shall recognize the following expressions: +.IP "***\ \fIfilename\ timestamp\fR" 6 +.br +The patches arose from +.IR filename . +.IP "\(mi\|\(mi\|\(mi\ \fIfilename\ timestamp\fR" 6 +.br +The patches should be applied to +.IR filename . +.P +If the type of difference is unified context, the +.IR patch +utility shall recognize the following expressions: +.IP "\(mi\|\(mi\|\(mi\ \fIfilename\ timestamp\fR" 6 +.br +The patches arose from +.IR filename . +.IP "+\|+\|+\ \fIfilename\ timestamp\fR" 6 +.br +The patches should be applied to +.IR filename . +.P +Each hunk within a patch shall be the +.IR diff +output to change a line range within the original file. The line +numbers for successive hunks within a patch shall occur in ascending +order. +.SS "Filename Determination" +.P +If no +.IR file +operand is specified, +.IR patch +shall perform the following steps to determine the filename to use: +.IP " 1." 4 +If the type of +.IR diff +is context, the +.IR patch +utility shall delete pathname components (as specified by the +.BR \(mip +option) from the filename on the line beginning with +.BR \(dq***\(dq +(if copied context) or +.BR \(dq\(mi\|\(mi\|\(mi\(dq +(if unified context), then test for the existence of this file relative +to the current directory (or the directory specified with the +.BR \(mid +option). If the file exists, the +.IR patch +utility shall use this filename. +.IP " 2." 4 +If the type of +.IR diff +is context, the +.IR patch +utility shall delete the pathname components (as specified by the +.BR \(mip +option) from the filename on the line beginning with +.BR \(dq\(mi\|\(mi\|\(mi\(dq +(if copied context) or +.BR \(dq+\|+\|+\(dq +(if unified context), then test for the existence of this file relative +to the current directory (or the directory specified with the +.BR \(mid +option). If the file exists, the +.IR patch +utility shall use this filename. +.IP " 3." 4 +If the header information contains a line beginning with the string +.BR Index: , +the +.IR patch +utility shall delete pathname components (as specified by the +.BR \(mip +option) from this line, then test for the existence of this file +relative to the current directory (or the directory specified with the +.BR \(mid +option). If the file exists, the +.IR patch +utility shall use this filename. +.IP " 4." 4 +If an +.BR SCCS +directory exists in the current directory, +.IR patch +shall attempt to perform a +.IR get +.BR \(mie +.BR SCCS/s. \c +.IR filename +command to retrieve an editable version of the file. If the file +exists, the +.IR patch +utility shall use this filename. +.IP " 5." 4 +The +.IR patch +utility shall write a prompt to standard output and request a filename +interactively from the controlling terminal (for example, +.BR /dev/tty ). +.SS "Patch Application" +.P +If the +.BR \(mic , +.BR \(mie , +.BR \(min , +or +.BR \(miu +option is present, the +.IR patch +utility shall interpret information within each hunk as a copied context +difference, an +.IR ed +difference, a normal difference, or a unified context difference, +respectively. In the absence of any of these options, the +.IR patch +utility shall determine the type of difference based on the format of +information within the hunk. +.P +For each hunk, the +.IR patch +utility shall begin to search for the place to apply the patch at the +line number at the beginning of the hunk, plus or minus any offset used +in applying the previous hunk. If lines matching the hunk context are +not found, +.IR patch +shall scan both forwards and backwards at least 1\|000 bytes for a set +of lines that match the hunk context. +.P +If no such place is found and it is a context difference, then another +scan shall take place, ignoring the first and last line of context. If +that fails, the first two and last two lines of context shall be +ignored and another scan shall be made. Implementations may search +more extensively for installation locations. +.P +If no location can be found, the +.IR patch +utility shall append the hunk to the reject file. A rejected hunk that +is a copied context difference, an +.IR ed +difference, or a normal difference shall be written in +copied-context-difference format regardless of the format of the patch +file. It is implementation-defined whether a rejected hunk that is +a unified context difference is written in copied-context-difference +format or in unified-context-difference format. +If the input was a normal or +.IR ed -style +difference, the reject file may contain differences with zero lines of +context. The line numbers on the hunks in the reject file may be +different from the line numbers in the patch file since they shall +reflect the approximate locations for the failed hunks in the new file +rather than the old one. +.P +If the type of patch is an +.IR ed +diff, the implementation may accomplish the patching by invoking the +.IR ed +utility. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP "\01" 6 +One or more lines were written to a reject file. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Patches that cannot be correctly placed in the file shall be written to +a reject file. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(miR +option does not work with +.IR ed +scripts because there is too little information to reconstruct the +reverse operation. +.P +The +.BR \(mip +option makes it possible to customize a patch file to local user +directory structures without manually editing the patch file. For +example, if the filename in the patch file was: +.sp +.RS 4 +.nf +\fB +/curds/whey/src/blurfl/blurfl.c +.fi \fR +.P +.RE +.P +Setting +.BR "\(mip\ 0" +gives the entire pathname unmodified; +.BR "\(mip\ 1" +gives: +.sp +.RS 4 +.nf +\fB +curds/whey/src/blurfl/blurfl.c +.fi \fR +.P +.RE +.P +without the leading +, +.BR "\(mip\ 4" +gives: +.sp +.RS 4 +.nf +\fB +blurfl/blurfl.c +.fi \fR +.P +.RE +.P +and not specifying +.BR \(mip +at all gives: +.sp +.RS 4 +.nf +\fB +blurfl.c . +.fi \fR +.P +.RE +.SH EXAMPLES +None. +.SH RATIONALE +Some of the functionality in historical +.IR patch +implementations was not specified. The following documents those +features present in historical implementations that have not been +specified. +.P +A deleted piece of functionality was the +.BR '\(pl' +pseudo-option allowing an additional set of options and a patch file +operand to be given. This was seen as being insufficiently useful to +standardize. +.P +In historical implementations, if the string +.BR \(dqPrereq:\(dq +appeared in the header, the +.IR patch +utility would search for the corresponding version information (the +string specified in the header, delimited by + +characters or the beginning or end of a line or the file) anywhere in +the original file. This was deleted as too simplistic and insufficiently +trustworthy a mechanism to standardize. For example, if: +.sp +.RS 4 +.nf +\fB +Prereq: 1.2 +.fi \fR +.P +.RE +.P +were in the header, the presence of a delimited 1.2 anywhere in the +file would satisfy the prerequisite. +.P +The following options were dropped from historical implementations of +.IR patch +as insufficiently useful to standardize: +.IP "\fB\(mib\fP" 10 +The +.BR \(mib +option historically provided a method for changing the name extension +of the backup file from the default +.BR .orig . +This option has been modified and retained in this volume of POSIX.1\(hy2008. +.IP "\fB\(miF\fP" 10 +The +.BR \(miF +option specified the number of lines of a context diff to ignore when +searching for a place to install a patch. +.IP "\fB\(mif\fP" 10 +The +.BR \(mif +option historically caused +.IR patch +not to request additional information from the user. +.IP "\fB\(mir\fP" 10 +The +.BR \(mir +option historically provided a method of overriding the extension of +the reject file from the default +.BR .rej . +.IP "\fB\(mis\fP" 10 +The +.BR \(mis +option historically caused +.IR patch +to work silently unless an error occurred. +.IP "\fB\(mix\fP" 10 +The +.BR \(mix +option historically set internal debugging flags. +.P +In some file system implementations, the saving of a +.BR .orig +file may produce unwanted results. In the case of 12, 13, or +14-character filenames (on file systems supporting 14-character +maximum filenames), the +.BR .orig +file overwrites the new file. The reject file may also exceed this +filename limit. It was suggested, due to some historical practice, +that a + +(\c +.BR '~' ) +suffix be used instead of +.BR .orig +and some other character instead of the +.BR .rej +suffix. This was rejected because it is not obvious to the user which +file is which. The suffixes +.BR .orig +and +.BR .rej +are clearer and more understandable. +.P +The +.BR \(mib +option has the opposite sense in some historical implementations\(emdo +not save the +.BR .orig +file. The default case here is not to save the files, making +.IR patch +behave more consistently with the other standard utilities. +.P +The +.BR \(miw +option in early proposals was changed to +.BR \(mil +to match historical practice. +.P +The +.BR \(miN +option was included because without it, a non-interactive application +cannot reject previously applied patches. For example, if a user is +piping the output of +.IR diff +into the +.IR patch +utility, and the user only wants to patch a file to a newer version +non-interactively, the +.BR \(miN +option is required. +.P +Changes to the +.BR \(mil +option description were proposed to allow matching across + +characters in addition to just + +characters. Since this is not historical practice, and since some +ambiguities could result, it is suggested that future developments in +this area utilize another option letter, such as +.BR \(miL . +.P +The +.BR \(miu +option of GNU +.IR patch +has been added, along with support for unified context formats. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdiff\fR\^", +.IR "\fIed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/pathchk.1p b/man-pages-posix-2013-a/man1p/pathchk.1p new file mode 100644 index 0000000..ce6862b --- /dev/null +++ b/man-pages-posix-2013-a/man1p/pathchk.1p @@ -0,0 +1,426 @@ +'\" et +.TH PATHCHK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pathchk +\(em check pathnames +.SH SYNOPSIS +.LP +.nf +pathchk \fB[\fR\(mip\fB] [\fR\(miP\fB] \fIpathname\fR... +.fi +.SH DESCRIPTION +The +.IR pathchk +utility shall check that one or more pathnames are valid (that is, they +could be used to access or create a file without causing syntax errors) +and portable (that is, no filename truncation results). More +extensive portability checks are provided by the +.BR \(mip +and +.BR \(miP +options. +.P +By default, the +.IR pathchk +utility shall check each component of each +.IR pathname +operand based on the underlying file system. A diagnostic shall be +written for each +.IR pathname +operand that: +.IP " *" 4 +Is longer than +{PATH_MAX} +bytes (see +.BR "Pathname Variable Values" +in the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +.IP " *" 4 +Contains any component longer than +{NAME_MAX} +bytes in its containing directory +.IP " *" 4 +Contains any component in a directory that is not searchable +.IP " *" 4 +Contains any byte sequence that is not valid in its +containing directory +.P +The format of the diagnostic message is not specified, but shall +indicate the error detected and the corresponding +.IR pathname +operand. +.P +It shall not be considered an error if one or more components of a +.IR pathname +operand do not exist as long as a file matching the pathname specified +by the missing components could be created that does not violate any of +the checks specified above. +.SH OPTIONS +The +.IR pathchk +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mip\fP" 10 +Instead of performing checks based on the underlying file system, write +a diagnostic for each +.IR pathname +operand that: +.RS 10 +.IP " *" 4 +Is longer than +{_POSIX_PATH_MAX} +bytes (see +.BR "Minimum Values" +in the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +.IP " *" 4 +Contains any component longer than +{_POSIX_NAME_MAX} +bytes +.IP " *" 4 +Contains any character in any component that is not in the portable +filename character set +.RE +.IP "\fB\(miP\fP" 10 +Write a diagnostic for each +.IR pathname +operand that: +.RS 10 +.IP " *" 4 +Contains a component whose first character is the + +character +.IP " *" 4 +Is empty +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIpathname\fR" 10 +A pathname to be checked. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pathchk : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All +.IR pathname +operands passed all of the checks. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR test +utility can be used to determine whether a given pathname names an +existing file; it does not, however, give any indication of whether or +not any component of the pathname was truncated in a directory where +the _POSIX_NO_TRUNC feature is not in effect. The +.IR pathchk +utility does not check for file existence; it performs checks to +determine whether a pathname does exist or could be created with no +pathname component truncation. +.P +The +.IR noclobber +option in the shell (see the +.IR "\fIset\fR\^" +special built-in) can be used to atomically create a file. As with all +file creation semantics in the System Interfaces volume of POSIX.1\(hy2008, it guarantees atomic creation, +but still depends on applications to agree on conventions and cooperate +on the use of files after they have been created. +.P +To verify that a pathname meets the requirements of filename +portability, applications should use both the +.BR \(mip +and +.BR \(miP +options together. +.SH EXAMPLES +To verify that all pathnames in an imported data interchange archive +are legitimate and unambiguous on the current system: +.sp +.RS 4 +.nf +\fB +# This example assumes that no pathnames in the archive +# contain characters. +pax \(mif archive | sed \(mie 's/[^[:alnum:]]/\e\e&/g' | xargs pathchk \(mi\|\(mi +if [ $? \(mieq 0 ] +then + pax \(mir \(mif archive +else + echo Investigate problems before importing files. + exit 1 +fi +.fi \fR +.P +.RE +.P +To verify that all files in the current directory hierarchy could be +moved to any system conforming to the System Interfaces volume of POSIX.1\(hy2008 that also supports the +.IR pax +utility: +.sp +.RS 4 +.nf +\fB +find . \(miexec pathchk \(mip \(miP {} + +if [ $? \(mieq 0 ] +then + pax \(miw \(mif ../archive . +else + echo Portable archive cannot be created. + exit 1 +fi +.fi \fR +.P +.RE +.P +To verify that a user-supplied pathname names a readable file and that +the application can create a file extending the given path without +truncation and without overwriting any existing file: +.sp +.RS 4 +.nf +\fB +case $\(mi in + *C*) reset="";; + *) reset="set +C" + set \(miC;; +esac +test \(mir "$path" && pathchk "$path.out" && + rm "$path.out" > "$path.out" +if [ $? \(mine 0 ]; then + printf "%s: %s not found or %s.out fails \e +creation checks.\en" $0 "$path$path" + $reset # Reset the noclobber option in case a trap + # on EXIT depends on it. + exit 1 +fi +$reset +PROCESSING < "$path" > "$path.out" +.fi \fR +.P +.RE +.P +The following assumptions are made in this example: +.IP " 1." 4 +.BR PROCESSING +represents the code that is used by the application to use +.BR $path +once it is verified that +.BR $path.out +works as intended. +.IP " 2." 4 +The state of the +.IR noclobber +option is unknown when this code is invoked and should be set on exit +to the state it was in when this code was invoked. (The +.BR reset +variable is used in this example to restore the initial state.) +.IP " 3." 4 +Note the usage of: +.RS 4 +.sp +.RS 4 +.nf +\fB +rm "$path.out" > "$path.out" +.fi \fR +.P +.RE +.IP " a." 4 +The +.IR pathchk +command has already verified, at this point, that +.BR $path.out +is not truncated. +.IP " b." 4 +With the +.IR noclobber +option set, the shell verifies that +.BR $path.out +does not already exist before invoking +.IR rm . +.IP " c." 4 +If the shell succeeded in creating +.BR $path.out , +.IR rm +removes it so that the application can create the file again in the +.BR PROCESSING +step. +.IP " d." 4 +If the +.BR PROCESSING +step wants the file to exist already when it is invoked, the: +.RS 4 +.sp +.RS 4 +.nf +\fB +rm "$path.out" > "$path.out" +.fi \fR +.P +.RE +.P +should be replaced with: +.sp +.RS 4 +.nf +\fB +> "$path.out" +.fi \fR +.P +.RE +.P +which verifies that the file did not already exist, but leaves +.BR $path.out +in place for use by +.BR PROCESSING . +.RE +.RE +.SH RATIONALE +The +.IR pathchk +utility was new for the ISO\ POSIX\(hy2:\|1993 standard. It, along with the +.IR set +.BR \(miC (\c +.IR noclobber ) +option added to the shell, replaces the +.IR mktemp , +.IR validfnam , +and +.IR create +utilities that appeared in early proposals. All of these utilities were +attempts to solve several common problems: +.IP " *" 4 +Verify the validity (for several different definitions of ``valid'') of +a pathname supplied by a user, generated by an application, or imported +from an external source. +.IP " *" 4 +Atomically create a file. +.IP " *" 4 +Perform various string handling functions to generate a temporary +filename. +.P +The +.IR create +utility, included in an early proposal, provided checking and atomic +creation in a single invocation of the utility; these are orthogonal +issues and need not be grouped into a single utility. Note that the +.IR noclobber +option also provides a way of creating a lock for process +synchronization; since it provides an atomic +.IR create , +there is no race between a test for existence and the following +creation if it did not exist. +.P +Having a function like +\fItmpnam\fR() +in the ISO\ C standard is important in many high-level languages. The shell +programming language, however, has built-in string manipulation +facilities, making it very easy to construct temporary filenames. The +names needed obviously depend on the application, but are frequently of +a form similar to: +.sp +.RS 4 +.nf +\fB +\fB$TMPDIR/\fIapplication_abbreviation\fB$$.\fIsuffix\fR +.fi \fR +.P +.RE +.P +In cases where there is likely to be contention for a given suffix, a +simple shell +.BR for +or +.BR while +loop can be used with the shell +.IR noclobber +option to create a file without risk of collisions, as long as +applications trying to use the same filename name space are cooperating +on the use of files after they have been created. +.P +For historical purposes, +.BR \(mip +does not check for the use of the + +character as the first character in a component of the pathname, or for +an empty +.IR pathname +operand. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "Redirection", +.IR "\fIset\fR\^", +.IR "\fItest\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/pax.1p b/man-pages-posix-2013-a/man1p/pax.1p new file mode 100644 index 0000000..788756b --- /dev/null +++ b/man-pages-posix-2013-a/man1p/pax.1p @@ -0,0 +1,4153 @@ +'\" et +.TH PAX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pax +\(em portable archive interchange +.SH SYNOPSIS +.LP +.nf +pax \fB[\fR\(midv\fB] [\fR\(mic|\(min\fB] [\fR\(miH|\(miL\fB] [\fR\(mio \fIoptions\fB] [\fR\(mif \fIarchive\fB] [\fR\(mis \fIreplstr\fB]\fR... + \fB[\fIpattern\fR...\fB]\fR +.P +pax \(mir\fB[\fR\(mic|\(min\fB] [\fR\(midikuv\fB] [\fR\(miH|\(miL\fB] [\fR\(mif \fIarchive\fB] [\fR\(mio \fIoptions\fB]\fR... \fB[\fR\(mip \fIstring\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fIpattern\fR...\fB]\fR +.P +pax \(miw \fB[\fR\(midituvX\fB] [\fR\(miH|\(miL\fB] [\fR\(mib \fIblocksize\fB] [[\fR\(mia\fB] [\fR\(mif \fIarchive\fB]] [\fR\(mio \fIoptions\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fR\(mix \fIformat\fB] [\fIfile\fR...\fB]\fR +.P +pax \(mir \(miw \fB[\fR\(midiklntuvX\fB] [\fR\(miH|\(miL\fB] [\fR\(mio \fIoptions\fB]\fR... \fB[\fR\(mip \fIstring\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fIfile\fR...\fB] \fIdirectory\fR +.fi +.SH DESCRIPTION +The +.IR pax +utility shall read, write, and write lists of the members of archive +files and copy directory hierarchies. A variety of archive formats +shall be supported; see the +.BR \(mix +.IR format +option. +.P +The action to be taken depends on the presence of the +.BR \(mir +and +.BR \(miw +options. The four combinations of +.BR \(mir +and +.BR \(miw +are referred to as the four modes of operation: +.BR list , +.BR read , +.BR write , +and +.BR copy +modes, corresponding respectively to the four forms shown in the +SYNOPSIS section. +.IP "\fBlist\fP" 10 +In +.BR list +mode (when neither +.BR \(mir +nor +.BR \(miw +are specified), +.IR pax +shall write the names of the members of the archive file read from the +standard input, with pathnames matching the specified patterns, to +standard output. If a named file is of type directory, the file +hierarchy rooted at that file shall be listed as well. +.IP "\fBread\fP" 10 +In +.BR read +mode (when +.BR \(mir +is specified, but +.BR \(miw +is not), +.IR pax +shall extract the members of the archive file read from the standard +input, with pathnames matching the specified patterns. If an extracted +file is of type directory, the file hierarchy rooted at that file shall +be extracted as well. The extracted files shall be created performing +pathname resolution with the directory in which +.IR pax +was invoked as the current working directory. +.RS 10 +.P +If an attempt is made to extract a directory when the directory +already exists, this shall not be considered an error. If +an attempt is made to extract a FIFO when the FIFO already exists, +this shall not be considered an error. +.P +The ownership, access, and modification times, and file mode of the +restored files are discussed under the +.BR \(mip +option. +.RE +.IP "\fBwrite\fP" 10 +In +.BR write +mode (when +.BR \(miw +is specified, but +.BR \(mir +is not), +.IR pax +shall write the contents of the +.IR file +operands to the standard output in an archive format. If no +.IR file +operands are specified, a list of files to copy, one per line, shall be +read from the standard input and each entry in this list shall be +processed as if it had been a +.IR file +operand on the command line. A file of type directory shall include +all of the files in the file hierarchy rooted at the file. +.IP "\fBcopy\fP" 10 +In +.BR copy +mode (when both +.BR \(mir +and +.BR \(miw +are specified), +.IR pax +shall copy the +.IR file +operands to the destination directory. +.RS 10 +.P +If no +.IR file +operands are specified, a list of files to copy, one per line, shall be +read from the standard input. A file of type directory shall include +all of the files in the file hierarchy rooted at the file. +.P +The effect of the +.BR copy +shall be as if the copied files were written to a +.IR pax +format archive file and then subsequently extracted, except that there +may be hard links between the original and the copied files. If the +destination directory is a subdirectory of one of the files to be +copied, the results are unspecified. If the destination directory is a +file of a type not defined by the System Interfaces volume of POSIX.1\(hy2008, the results are +implementation-defined; otherwise, it shall be an error for the file +named by the +.IR directory +operand not to exist, not be writable by the user, or not be a file of +type directory. +.RE +.P +In +.BR read +or +.BR copy +modes, if intermediate directories are necessary to extract an archive +member, +.IR pax +shall perform actions equivalent to the +\fImkdir\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " *" 4 +The intermediate directory used as the +.IR path +argument +.IP " *" 4 +The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO +as the +.IR mode +argument +.P +If any specified +.IR pattern +or +.IR file +operands are not matched by at least one file or archive member, +.IR pax +shall write a diagnostic message to standard error for each one that +did not match and exit with a non-zero exit status. +.P +The archive formats described in the EXTENDED DESCRIPTION section shall +be automatically detected on input. The default output archive format +shall be implementation-defined. +.P +A single archive can span multiple files. The +.IR pax +utility shall determine, in an implementation-defined manner, what +file to read or write as the next file. +.P +If the selected archive format supports the specification of linked files, +it shall be an error if these files cannot be linked when the archive +is extracted. For archive formats that do not store file contents with +each name that causes a hard link, if the file that contains the data +is not extracted during this +.IR pax +session, either the data shall be restored from the original file, or a +diagnostic message shall be displayed with the name of a file that can +be used to extract the data. In traversing directories, +.IR pax +shall detect infinite loops; that is, entering a previously visited +directory that is an ancestor of the last file visited. When it detects +an infinite loop, +.IR pax +shall write a diagnostic message to standard error and shall +terminate. +.SH OPTIONS +The +.IR pax +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of presentation of the +.BR \(mio , +.BR \(mip , +and +.BR \(mis +options is significant. +.P +The following options shall be supported: +.IP "\fB\(mir\fP" 10 +Read an archive file from standard input. +.IP "\fB\(miw\fP" 10 +Write files to the standard output in the specified archive format. +.IP "\fB\(mia\fP" 10 +Append files to the end of the archive. It is implementation-defined +which devices on the system support appending. Additional file formats +unspecified by this volume of POSIX.1\(hy2008 may impose restrictions on appending. +.IP "\fB\(mib\ \fIblocksize\fR" 10 +Block the output at a positive decimal integer number of bytes per +write to the archive file. Devices and archive formats may impose +restrictions on blocking. Blocking shall be automatically determined on +input. Conforming applications shall not specify a +.IR blocksize +value larger than 32\|256. Default blocking when creating archives +depends on the archive format. (See the +.BR \(mix +option below.) +.IP "\fB\(mic\fP" 10 +Match all file or archive members except those specified by the +.IR pattern +or +.IR file +operands. +.IP "\fB\(mid\fP" 10 +Cause files of type directory being copied or archived or archive +members of type directory being extracted or listed to match only the +file or archive member itself and not the file hierarchy rooted at the +file. +.IP "\fB\(mif\ \fIarchive\fR" 10 +Specify the pathname of the input or output archive, overriding the +default standard input (in +.BR list +or +.BR read +modes) or standard output (\c +.BR write +mode). +.IP "\fB\(miH\fP" 10 +If a symbolic link referencing a file of type directory is specified on +the command line, +.IR pax +shall archive the file hierarchy rooted in the file referenced by the +link, using the name of the link as the root of the file hierarchy. +Otherwise, if a symbolic link referencing a file of any other file type +which +.IR pax +can normally archive is specified on the command line, then +.IR pax +shall archive the file referenced by the link, using the name of the +link. The default behavior, when neither +.BR \(miH +or +.BR \(miL +are specified, shall be to archive the symbolic link itself. +.IP "\fB\(mii\fP" 10 +Interactively rename files or archive members. For each archive member +matching a +.IR pattern +operand or file matching a +.IR file +operand, a prompt shall be written to the file +.BR /dev/tty . +The prompt shall contain the name of the file or archive member, but +the format is otherwise unspecified. A line shall then be read from +.BR /dev/tty . +If this line is blank, the file or archive member shall be skipped. If +this line consists of a single period, the file or archive member shall +be processed with no modification to its name. Otherwise, its name +shall be replaced with the contents of the line. The +.IR pax +utility shall immediately exit with a non-zero exit status if +end-of-file is encountered when reading a response or if +.BR /dev/tty +cannot be opened for reading and writing. +.RS 10 +.P +The results of extracting a hard link to a file that has been renamed +during extraction are unspecified. +.RE +.IP "\fB\(mik\fP" 10 +Prevent the overwriting of existing files. +.IP "\fB\(mil\fP" 10 +(The letter ell.) In +.BR copy +mode, hard links shall be made between the source and destination file +hierarchies whenever possible. If specified in conjunction with +.BR \(miH +or +.BR \(miL , +when a symbolic link is encountered, the hard link created in the +destination file hierarchy shall be to the file referenced by the +symbolic link. If specified when neither +.BR \(miH +nor +.BR \(miL +is specified, when a symbolic link is encountered, the implementation +shall create a hard link to the symbolic link in the source file +hierarchy or copy the symbolic link to the destination. +.IP "\fB\(miL\fP" 10 +If a symbolic link referencing a file of type directory is specified on +the command line or encountered during the traversal of a file +hierarchy, +.IR pax +shall archive the file hierarchy rooted in the file referenced by the +link, using the name of the link as the root of the file hierarchy. +Otherwise, if a symbolic link referencing a file of any other file type +which +.IR pax +can normally archive is specified on the command line or encountered +during the traversal of a file hierarchy, +.IR pax +shall archive the file referenced by the link, using the name of the +link. The default behavior, when neither +.BR \(miH +or +.BR \(miL +are specified, shall be to archive the symbolic link itself. +.IP "\fB\(min\fP" 10 +Select the first archive member that matches each +.IR pattern +operand. No more than one archive member shall be matched for each +pattern (although members of type directory shall still match the file +hierarchy rooted at that file). +.IP "\fB\(mio\ \fIoptions\fR" 10 +Provide information to the implementation to modify the algorithm for +extracting or writing files. The value of +.IR options +shall consist of one or more +-separated +keywords of the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIkeyword\fB[[\fR:\fB]\fR=\fIvalue\fB][\fR,\fIkeyword\fB[[\fR:\fB]\fR=\fIvalue\fB]\fR, ...\fB]\fR +.fi \fR +.P +.RE +.P +Some keywords apply only to certain file formats, as indicated with +each description. Use of keywords that are inapplicable to the file +format being processed produces undefined results. +.P +Keywords in the +.IR options +argument shall be a string that would be a valid portable filename as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.278" ", " "Portable Filename Character Set". +.TP 10 +.BR Note: +Keywords are not expected to be filenames, merely to follow the same +character composition rules as portable filenames. +.P +.P +Keywords can be preceded with white space. The +.IR value +field shall consist of zero or more characters; within +.IR value , +the application shall precede any literal + +with a +, +which shall be ignored, but preserves the + +as part of +.IR value . +A + +as the final character, or a + +followed solely by white space as the final characters, in +.IR options +shall be ignored. Multiple +.BR \(mio +options can be specified; if keywords given to these multiple +.BR \(mio +options conflict, the keywords and values appearing later in command +line sequence shall take precedence and the earlier shall be silently +ignored. The following keyword values of +.IR options +shall be supported for the file formats as indicated: +.IP "\fBdelete\fR=\fIpattern\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) When used in +.BR write +or +.BR copy +mode, +.IR pax +shall omit from extended header records that it produces any keywords +matching the string pattern. When used in +.BR read +or +.BR list +mode, +.IR pax +shall ignore any keywords matching the string pattern in the extended +header records. In both cases, matching shall be performed using the +pattern matching notation described in +.IR "Section 2.13.1" ", " "Patterns Matching a Single Character" +and +.IR "Section 2.13.2" ", " "Patterns Matching Multiple Characters". +For example: +.RS 6 +.sp +.RS 4 +.nf +\fB +\(mio \fBdelete\fR=\fIsecurity\fR.* +.fi \fR +.P +.RE +.P +would suppress security-related information. See +.IR "pax Extended Header" +for extended header record keyword usage. +.P +When multiple +.BR \(mio \c +.BR delete=pattern +options are specified, the patterns shall be additive; all keywords +matching the specified string patterns shall be omitted from extended +header records that +.IR pax +produces. +.RE +.IP "\fBexthdr.name\fR=\fIstring\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) This keyword allows user control over the name that is written +into the +.BR ustar +header blocks for the extended header produced under the circumstances +described in +.IR "pax Header Block". +The name shall be the contents of +.IR string , +after the following character substitutions have been made: +.TS +center box tab(!); +cB | cB +cB | cB +lf5 | lw(3.8i). +\fIstring\fP +Includes:!Replaced by: +_ +%d!T{ +The directory name of the file, equivalent to the result of the +.IR dirname +utility on the translated pathname. +T} +%f!T{ +The filename of the file, equivalent to the result of the +.IR basename +utility on the translated pathname. +T} +%p!T{ +The process ID of the +.IR pax +process. +T} +%%!T{ +A +.BR '%' +character. +T} +.TE +.RS 6 +.P +Any other +.BR '%' +characters in +.IR string +produce undefined results. +.P +If no +.BR \(mio +.BR exthdr.name=string +is specified, +.IR pax +shall use the following default value: +.sp +.RS 4 +.nf +\fB +%d/PaxHeaders.%p/%f +.fi \fR +.P +.RE +.RE +.IP "\fBglobexthdr.name\fR=\fIstring\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) When used in +.BR write +or +.BR copy +mode with the appropriate options, +.IR pax +shall create global extended header records with +.BR ustar +header blocks that will be treated as regular files by previous +versions of +.IR pax . +This keyword allows user control over the name that is written into the +.BR ustar +header blocks for global extended header records. The name shall be the +contents of string, after the following character substitutions have +been made: +.TS +center box tab(!); +cB | cB +cB | cB +lf5 | lw(3.8i). +\fIstring\fP +Includes:!Replaced by: +_ +%n!T{ +An integer that represents the sequence number of the global extended +header record in the archive, starting at 1. +T} +%p!T{ +The process ID of the +.IR pax +process. +T} +%%!T{ +A +.BR '%' +character. +T} +.TE +.RS 6 +.P +Any other +.BR '%' +characters in +.IR string +produce undefined results. +.P +If no +.BR \(mio +.BR globexthdr.name=string +is specified, +.IR pax +shall use the following default value: +.sp +.RS 4 +.nf +\fB +$TMPDIR/GlobalHead.%p.%n +.fi \fR +.P +.RE +.P +where $\c +.IR TMPDIR +represents the value of the +.IR TMPDIR +environment variable. If +.IR TMPDIR +is not set, +.IR pax +shall use +.BR /tmp . +.RE +.IP "\fBinvalid\fR=\fIaction\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) This keyword allows user control over the action +.IR pax +takes upon encountering values in an extended header record that, in +.BR read +or +.BR copy +mode, are invalid in the destination hierarchy or, in +.BR list +mode, cannot be written in the codeset and current locale of the +implementation. The following are invalid values that shall be +recognized by +.IR pax : +.RS 6 +.IP -- 4 +In +.BR read +or +.BR copy +mode, a filename or link name that contains character encodings +invalid in the destination hierarchy. (For example, the name may +contain embedded NULs.) +.IP -- 4 +In +.BR read +or +.BR copy +mode, a filename or link name that is longer than the maximum allowed +in the destination hierarchy (for either a pathname component or the +entire pathname). +.IP -- 4 +In +.BR list +mode, any character string value (filename, link name, user name, and +so on) that cannot be written in the codeset and current locale of the +implementation. +.P +The following mutually-exclusive values of the +.IR action +argument are supported: +.IP "\fBbinary\fR" 10 +In +.BR write +mode, +.IR pax +shall generate a +.BR hdrcharset = BINARY +extended header record for each file with a filename, link name, group +name, owner name, or any other field in an extended header record that +cannot be translated to the UTF\(hy8 codeset, allowing the archive to +contain the files with unencoded extended header record values. In +.BR read +or +.BR copy +mode, +.IR pax +shall use the values specified in the header without translation, +regardless of whether this may overwrite an existing file with a valid +name. In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.IP "\fBbypass\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall bypass the file, causing no change to the destination hierarchy. +In +.BR list +mode, +.IR pax +shall write all requested valid values for the file, but its method for +writing invalid values is unspecified. +.IP "\fBrename\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall act as if the +.BR \(mii +option were in effect for each file with invalid filename or link name +values, allowing the user to provide a replacement name interactively. +In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.IP "\fBUTF\(hy8\fR" 10 +When used in +.BR read , +.BR copy , +or +.BR list +mode and a filename, link name, owner name, or any other field in an +extended header record cannot be translated from the +.BR pax +UTF\(hy8 codeset format to the codeset and current locale of the +implementation, +.IR pax +shall use the actual UTF\(hy8 encoding for the name. If a +.BR hdrcharset +extended header record is in effect for this file, the character set +specified by that record shall be used instead of UTF\(hy8. If a +.BR hdrcharset = BINARY +extended header record is in effect for this file, no translation shall +be performed. +.IP "\fBwrite\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall write the file, translating the name, regardless of whether this +may overwrite an existing file with a valid name. In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.P +If no +.BR \(mio +.BR invalid=option +is specified, +.IR pax +shall act as if +.BR \(mio \c +.BR invalid=bypass +were specified. Any overwriting of existing files that may be allowed +by the +.BR \(mio \c +.BR invalid= +actions shall be subject to permission (\c +.BR \(mip ) +and modification time (\c +.BR \(miu ) +restrictions, and shall be suppressed if the +.BR \(mik +option is also specified. +.RE +.IP "\fBlinkdata\fP" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) In +.BR write +mode, +.IR pax +shall write the contents of a file to the archive even when that file +is merely a hard link to a file whose contents have already been +written to the archive. +.IP "\fBlistopt\fR=\fIformat\fP" 6 +.br +This keyword specifies the output format of the table of contents +produced when the +.BR \(miv +option is specified in +.BR list +mode. See +.IR "List Mode Format Specifications". +To avoid ambiguity, the +.BR listopt=format +shall be the only or final +.BR keyword=value +pair in a +.BR \(mio +option-argument; all characters in the remainder of the option-argument +shall be considered part of the format string. When multiple +.BR \(mio \c +.BR listopt=format +options are specified, the format strings shall be considered a single, +concatenated string, evaluated in command line order. +.IP "\fBtimes\fR" 6 +.br +(Applicable only to the +.BR \(mix +.IR pax +format.) When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include +.BR atime +and +.BR mtime +extended header records for each file. See +.IR "pax Extended Header File Times". +.P +In addition to these keywords, if the +.BR \(mix +.IR pax +format is specified, any of the keywords and values defined in +.IR "pax Extended Header", +including implementation extensions, can be used in +.BR \(mio +option-arguments, in either of two modes: +.IP "\fBkeyword\fR=\fIvalue\fR" 6 +.br +When used in +.BR write +or +.BR copy +mode, these keyword/value pairs shall be included at the beginning of +the archive as +.BR typeflag +.BR g +global extended header records. When used in +.BR read +or +.BR list +mode, these keyword/value pairs shall act as if they had been at the +beginning of the archive as +.BR typeflag +.BR g +global extended header records. +.IP "\fBkeyword\fR:=\fIvalue\fR" 6 +.br +When used in +.BR write +or +.BR copy +mode, these keyword/value pairs shall be included as records at the +beginning of a +.BR typeflag +.BR x +extended header for each file. (This shall be equivalent to the + +form except that it creates no +.BR typeflag +.BR g +global extended header records.) When used in +.BR read +or +.BR list +mode, these keyword/value pairs shall act as if they were included as +records at the end of each extended header; thus, they shall override +any global or file-specific extended header record keywords of the same +names. For example, in the command: +.RS 6 +.sp +.RS 4 +.nf +\fB +pax \(mir \(mio " +gname:=mygroup, +" , +.BR '\en' +(where +.IR n +is a digit) back-references, or subexpression matching. The +.IR old +string shall also be permitted to contain + +characters. +.P +Any non-null character can be used as a delimiter (\c +.BR '/' +shown here). Multiple +.BR \(mis +expressions can be specified; the expressions shall be applied in the +order specified, terminating with the first successful substitution. +The optional trailing +.BR 'g' +is as defined in the +.IR ed +utility. The optional trailing +.BR 'p' +shall cause successful substitutions to be written to standard error. +File or archive member names that substitute to the empty string shall +be ignored when reading and writing archives. +.RE +.IP "\fB\(mit\fP" 10 +When reading files from the file system, and if the user has the +permissions required by +\fIutime\fR() +to do so, set the access time of each file read to the access time that +it had before being read by +.IR pax . +.IP "\fB\(miu\fP" 10 +Ignore files that are older (having a less recent file modification +time) than a pre-existing file or archive member with the same name. +In +.BR read +mode, an archive member with the same name as a file in the file system +shall be extracted if the archive member is newer than the file. In +.BR write +mode, an archive file member with the same name as a file in the file +system shall be superseded if the file is newer than the archive +member. If +.BR \(mia +is also specified, this is accomplished by appending to the archive; +otherwise, it is unspecified whether this is accomplished by actual +replacement in the archive or by appending to the archive. In +.BR copy +mode, the file in the destination hierarchy shall be replaced by the +file in the source hierarchy or by a link to the file in the source +hierarchy if the file in the source hierarchy is newer. +.IP "\fB\(miv\fP" 10 +In +.BR list +mode, produce a verbose table of contents (see the STDOUT section). +Otherwise, write archive member pathnames to standard error (see the +STDERR section). +.IP "\fB\(mix\ \fIformat\fR" 10 +Specify the output archive format. The +.IR pax +utility shall support the following formats: +.RS 10 +.IP "\fBcpio\fR" 10 +The +.BR cpio +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 5\|120. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.IP "\fBpax\fR" 10 +The +.BR pax +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 5\|120. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.IP "\fBustar\fR" 10 +The +.BR tar +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 10\|240. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.P +Implementation-defined formats shall specify a default block size as +well as any other block sizes supported for character special archive +files. +.P +Any attempt to append to an archive file in a format different from the +existing archive format shall cause +.IR pax +to exit immediately with a non-zero exit status. +.RE +.IP "\fB\(miX\fP" 10 +When traversing the file hierarchy specified by a pathname, +.IR pax +shall not descend into directories that have a different device ID (\c +.IR st_dev ; +see the System Interfaces volume of POSIX.1\(hy2008, +\fIstat\fR()). +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH +and +.BR \(miL +shall not be considered an error and the last option specified shall +determine the behavior of the utility. +.P +The options that operate on the names of files or archive members (\c +.BR \(mic , +.BR \(mii , +.BR \(min , +.BR \(mis , +.BR \(miu , +and +.BR \(miv ) +shall interact as follows. In +.BR read +mode, the archive members shall be selected based on the user-specified +.IR pattern +operands as modified by the +.BR \(mic , +.BR \(min , +and +.BR \(miu +options. Then, any +.BR \(mis +and +.BR \(mii +options shall modify, in that order, the names of the selected files. +The +.BR \(miv +option shall write names resulting from these modifications. +.P +In +.BR write +mode, the files shall be selected based on the user-specified +pathnames as modified by the +.BR \(min +and +.BR \(miu +options. Then, any +.BR \(mis +and +.BR \(mii +options shall modify, in that order, the names of these selected files. +The +.BR \(miv +option shall write names resulting from these modifications. +.P +If both the +.BR \(miu +and +.BR \(min +options are specified, +.IR pax +shall not consider a file selected unless it is newer than the file to +which it is compared. +.SS "List Mode Format Specifications" +.P +In +.BR list +mode with the +.BR \(mio +.BR listopt=format +option, the +.IR format +argument shall be applied for each selected file. The +.IR pax +utility shall append a + +to the +.BR listopt +output for each selected file. The +.IR format +argument shall be used as the +.IR format +string described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +with the exceptions 1. through 6. defined in the EXTENDED DESCRIPTION +section of +.IR printf , +plus the following exceptions: +.IP 7. 6 +The sequence (\c +.IR keyword ) +can occur before a format conversion specifier. The conversion +argument is defined by the value of +.IR keyword . +The implementation shall support the following keywords: +.RS 6 +.IP -- 4 +Any of the Field Name entries in +.IR "Table 4-14, ustar Header Block" +and +.IR "Table 4-16, Octet-Oriented cpio Archive Entry". +The implementation may support the +.IR cpio +keywords without the leading +.BR c_ +in addition to the form required by +.IR "Table 4-16, Octet-Oriented cpio Archive Entry". +.IP -- 4 +Any keyword defined for the extended header in +.IR "pax Extended Header". +.IP -- 4 +Any keyword provided as an implementation-defined extension within +the extended header defined in +.IR "pax Extended Header". +.P +For example, the sequence +.BR \(dq%(charset)s\(dq +is the string value of the name of the character set in the extended +header. +.P +The result of the keyword conversion argument shall be the value from +the applicable header field or extended header, without any trailing +NULs. +.P +All keyword values used as conversion arguments shall be translated +from the UTF\(hy8 encoding (or alternative encoding specified by any +.BR hdrcharset +extended header record) to the character set appropriate for the local +file system, user database, and so on, as applicable. +.RE +.IP 8. 6 +An additional conversion specifier character, +.BR T , +shall be used to specify time formats. The +.BR T +conversion specifier character can be preceded by the sequence (\c +.IR keyword= \c +.IR subformat ), +where +.IR subformat +is a date format as defined by +.IR date +operands. The default +.IR keyword +shall be +.BR mtime +and the default subformat shall be: +.RS 6 +.sp +.RS 4 +.nf +\fB +%b %e %H:%M %Y +.fi \fR +.P +.RE +.RE +.IP 9. 6 +An additional conversion specifier character, +.BR M , +shall be used to specify the file mode string as defined in +.IR ls +Standard Output. If (\c +.IR keyword ) +is omitted, the +.BR mode +keyword shall be used. For example, +.BR %.1M +writes the single character corresponding to the <\fIentry\ type\fP> +field of the +.IR ls +.BR \(mil +command. +.IP 10. 6 +An additional conversion specifier character, +.BR D , +shall be used to specify the device for block or special files, if +applicable, in an implementation-defined format. If not applicable, +and (\c +.IR keyword ) +is specified, then this conversion shall be equivalent to +\fR%(\fIkeyword\fR)u\fR. If not applicable, and (\c +.IR keyword ) +is omitted, then this conversion shall be equivalent to +. +.IP 11. 6 +An additional conversion specifier character, +.BR F , +shall be used to specify a pathname. The +.BR F +conversion character can be preceded by a sequence of +-separated +keywords: +.RS 6 +.sp +.RS 4 +.nf +\fB +(\fIkeyword\fB[\fR,\fIkeyword\fB]\fR ... ) +.fi \fR +.P +.RE +.P +The values for all the keywords that are non-null shall be concatenated +together, each separated by a +.BR '/' . +The default shall be (\c +.BR path ) +if the keyword +.BR path +is defined; otherwise, the default shall be (\c +.BR prefix ,\c +.BR name ). +.RE +.IP 12. 6 +An additional conversion specifier character, +.BR L , +shall be used to specify a symbolic link expansion. If the current +file is a symbolic link, then +.BR %L +shall expand to: +.RS 6 +.sp +.RS 4 +.nf +\fB +"%s \(mi> %s", <\fIvalue of keyword\fR>, <\fIcontents of link\fR> +.fi \fR +.P +.RE +.P +Otherwise, the +.BR %L +conversion specification shall be the equivalent of +.BR %F . +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdirectory\fR" 10 +The destination directory pathname for +.BR copy +mode. +.IP "\fIfile\fR" 10 +A pathname of a file to be copied or archived. +.IP "\fIpattern\fR" 10 +A pattern matching one or more pathnames of archive members. A pattern +must be given in the name-generating notation of the pattern matching +notation in +.IR "Section 2.13" ", " "Pattern Matching Notation", +including the filename expansion rules in +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion". +The default, if no +.IR pattern +is specified, is to select all members in the archive. +.SH STDIN +In +.BR write +mode, the standard input shall be used only if no +.IR file +operands are specified. It shall be a file containing a list of +pathnames, each terminated by a + +character. +.P +In +.BR list +and +.BR read +modes, if +.BR \(mif +is not specified, the standard input shall be an archive file. +.P +Otherwise, the standard input shall not be used. +.SH "INPUT FILES" +The input file named by the +.IR archive +option-argument, or standard input when the archive is read from there, +shall be a file formatted according to one of the specifications in the +EXTENDED DESCRIPTION section or some other implementation-defined +format. +.P +The file +.BR /dev/tty +shall be used to write prompts and read responses. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pax : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the pattern matching +expressions for the +.IR pattern +operand, the basic regular expression for the +.BR \(mis +option, and the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category, and pattern matching. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of date and time strings when the +.BR \(miv +option is specified. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that provides part of the default global +extended header record file, as described for the +.BR \(mio +.BR globexthdr= +keyword in the OPTIONS section. +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings when the +.BR \(miv +option is specified. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +In +.BR write +mode, if +.BR \(mif +is not specified, the standard output shall be the archive formatted +according to one of the specifications in the EXTENDED DESCRIPTION +section, or some other implementation-defined format (see +.BR \(mix +.IR format ). +.P +In +.BR list +mode, when the +.BR \(mio \c +.BR listopt =\c +.IR format +has been specified, the selected archive members shall be written to +standard output using the format described under +.IR "List Mode Format Specifications". +In +.BR list +mode without the +.BR \(mio \c +.BR listopt =\c +.IR format +option, the table of contents of the selected archive members shall +be written to standard output using the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(miv +option is specified in +.BR list +mode, the table of contents of the selected archive members shall be +written to standard output using the following formats. +.P +For pathnames representing hard links to previous members of the +archive: +.sp +.RS 4 +.nf +\fB +"%s == %s\en", <\fIls\fR \(mil \fIlisting\fR>, <\fIlinkname\fR> +.fi \fR +.P +.RE +.P +For all other pathnames: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIls\fR \(mil \fIlisting\fR> +.fi \fR +.P +.RE +.P +where <\fIls\ \fR\(mil\ \fIlisting\fR> shall be the format specified by +the +.IR ls +utility with the +.BR \(mil +option. When writing pathnames in this format, it is unspecified what +is written for fields for which the underlying archive format does not +have the correct information, although the correct number of +-separated +fields shall be written. +.P +In +.BR list +mode, standard output shall not be buffered more than a pathname +(plus any associated information and a + +terminator) at a time. +.SH STDERR +If +.BR \(miv +is specified in +.BR read , +.BR write , +or +.BR copy +modes, +.IR pax +shall write the pathnames it processes to the standard error output +using the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +These pathnames shall be written as soon as processing is begun on the +file or archive member, and shall be flushed to standard error. The +trailing +, +which shall not be buffered, is written when the file has been read or +written. +.P +If the +.BR \(mis +option is specified, and the replacement string has a trailing +.BR 'p' , +substitutions shall be written to standard error in the following +format: +.sp +.RS 4 +.nf +\fB +"%s >> %s\en", <\fIoriginal pathname\fR>, <\fInew pathname\fR> +.fi \fR +.P +.RE +.P +In all operating modes of +.IR pax , +optional messages of unspecified format concerning the input archive +format and volume number, the number of files, blocks, volumes, and +media parts as well as other diagnostic messages may be written to +standard error. +.P +In all formats, for both standard output and standard error, it is +unspecified how non-printable characters in pathnames or link names +are written. +.P +When using the +.BR \(mix \c +.BR pax +archive format, if a filename, link name, group name, owner name, or +any other field in an extended header record cannot be translated +between the codeset in use for that extended header record and the +character set of the current locale, +.IR pax +shall write a diagnostic message to standard error, shall process the +file as described for the +.BR \(mio +.BR invalid= +option, and then shall continue processing with the next file. +.SH "OUTPUT FILES" +In +.BR read +mode, the extracted output files shall be of the archived file type. +In +.BR copy +mode, the copied output files shall be the type of the file being +copied. In either mode, existing files in the destination hierarchy +shall be overwritten only when all permission (\c +.BR \(mip ), +modification time (\c +.BR \(miu ), +and invalid-value (\c +.BR \(mio \c +.BR invalid= ) +tests allow it. +.P +In +.BR write +mode, the output file named by the +.BR \(mif +option-argument shall be a file formatted according to one of the +specifications in the EXTENDED DESCRIPTION section, or some other +implementation-defined format. +.SH "EXTENDED DESCRIPTION" +.SS "pax Interchange Format" +.P +A +.IR pax +archive tape or file produced in the +.BR \(mix \c +.BR pax +format shall contain a series of blocks. The physical layout of the +archive shall be identical to the +.BR ustar +format described in +.IR "ustar Interchange Format". +Each file archived shall be represented by the following sequence: +.IP " *" 4 +An optional header block with extended header records. This header +block is of the form described in +.IR "pax Header Block", +with a +.IR typeflag +value of +.BR x +or +.BR g . +The extended header records, described in +.IR "pax Extended Header", +shall be included as the data for this header block. +.IP " *" 4 +A header block that describes the file. Any fields in the preceding +optional extended header shall override the associated fields in +this header block for this file. +.IP " *" 4 +Zero or more blocks that contain the contents of the file. +.P +At the end of the archive file there shall be two 512-byte blocks +filled with binary zeros, interpreted as an end-of-archive indicator. +.P +A schematic of an example archive with global extended header records +and two actual files is shown in +.IR "Figure 4-1, pax Format Archive Example". +In the example, the second file in the archive has no extended header +preceding it, presumably because it has no need for extended +attributes. +.sp +.ce 1 +\fBFigure 4-1: pax Format Archive Example\fR +.SS "pax Header Block" +.P +The +.BR pax +header block shall be identical to the +.BR ustar +header block described in +.IR "ustar Interchange Format", +except that two additional +.IR typeflag +values are defined: +.IP "\fRx\fP" 6 +Represents extended header records for the following file in the +archive (which shall have its own +.BR ustar +header block). The format of these extended header records shall be as +described in +.IR "pax Extended Header". +.IP "\fRg\fR" 6 +Represents global extended header records for the following files in +the archive. The format of these extended header records shall be as +described in +.IR "pax Extended Header". +Each value shall affect all subsequent files that do not override that +value in their own extended header record and until another global +extended header record is reached that provides another value for the +same field. The +.IR typeflag +.BR g +global headers should not be used with interchange media that could +suffer partial data loss in transporting the archive. +.P +For both of these types, the +.IR size +field shall be the size of the extended header records in octets. The +other fields in the header block are not meaningful to this version of +the +.IR pax +utility. However, if this archive is read by a +.IR pax +utility conforming to the ISO\ POSIX\(hy2:\|1993 standard, the header block fields are used to +create a regular file that contains the extended header records as +data. Therefore, header block field values should be selected to +provide reasonable file access to this regular file. +.P +A further difference from the +.BR ustar +header block is that data blocks for files of +.IR typeflag +1 (the digit one) (hard link) may be included, which means that the +size field may be greater than zero. Archives created by +.IR pax +.BR \(mio +.BR linkdata +shall include these data blocks with the hard links. +.SS "pax Extended Header" +.P +A +.BR pax +extended header contains values that are inappropriate for the +.BR ustar +header block because of limitations in that format: fields requiring a +character encoding other than that described in the ISO/IEC\ 646:\|1991 standard, fields +representing file attributes not described in the +.BR ustar +header, and fields whose format or length do not fit the requirements +of the +.BR ustar +header. The values in an extended header add attributes to the +following file (or files; see the description of the +.IR typeflag +.BR g +header block) or override values in the following header block(s), as +indicated in the following list of keywords. +.P +An extended header shall consist of one or more records, each +constructed as follows: +.sp +.RS 4 +.nf +\fB +"%d %s=%s\en", <\fIlength\fR>, <\fIkeyword\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +The extended header records shall be encoded according to the ISO/IEC\ 10646\(hy1:\|2000 standard +UTF\(hy8 encoding. The <\fIlength\fP> field, +, +, +and + +shown shall be limited to the portable character set, as encoded in +UTF\(hy8. The <\fIkeyword\fP> fields can be any UTF\(hy8 characters. +The <\fIlength\fP> field shall be the decimal length of the extended +header record in octets, including the trailing +. +If there is a +.BR hdrcharset +extended header in effect for a file, the +.IR value +field for any +.BR gname , +.BR linkpath , +.BR path , +and +.BR uname +extended header records shall be encoded using the character set +specified by the +.BR hdrcharset +extended header record; otherwise, the +.IR value +field shall be encoded using UTF\(hy8. The +.IR value +field for all other keywords specified by POSIX.1\(hy2008 shall be +encoded using UTF\(hy8. +.P +The <\fIkeyword\fP> field shall be one of the entries from the +following list or a keyword provided as an implementation extension. +Keywords consisting entirely of lowercase letters, digits, and periods +are reserved for future standardization. A keyword shall not include an +. +(In the following list, the notations ``file(s)'' or ``block(s)'' is used +to acknowledge that a keyword affects the following single file after a +.IR typeflag +.BR x +extended header, but possibly multiple files after +.IR typeflag +.BR g . +Any requirements in the list for +.IR pax +to include a record when in +.BR write +or +.BR copy +mode shall apply only when such a record has not already been provided +through the use of the +.BR \(mio +option. When used in +.BR copy +mode, +.IR pax +shall behave as if an archive had been created with applicable extended +header records and then extracted.) +.IP "\fBatime\fP" 10 +The file access time for the following file(s), equivalent to the value +of the +.IR st_atime +member of the +.BR stat +structure for a file, as described by the +\fIstat\fR() +function. The access time shall be restored if the process has +appropriate privileges required to do so. The format of the +<\fIvalue\fP> shall be as described in +.IR "pax Extended Header File Times". +.IP "\fBcharset\fP" 10 +The name of the character set used to encode the data in the following +file(s). The entries in the following table are defined to refer to +known standards; additional names may be agreed on between the +originator and recipient. +.TS +center box tab(!); +cB | cB +lf5 | l. +!Formal Standard +_ +ISO-IR 646 1990!ISO/IEC 646:\|1990 +ISO-IR 8859 1 1998!ISO/IEC 8859\(hy1:\|1998 +ISO-IR 8859 2 1999!ISO/IEC 8859\(hy2:\|1999 +ISO-IR 8859 3 1999!ISO/IEC 8859\(hy3:\|1999 +ISO-IR 8859 4 1998!ISO/IEC 8859\(hy4:\|1998 +ISO-IR 8859 5 1999!ISO/IEC 8859\(hy5:\|1999 +ISO-IR 8859 6 1999!ISO/IEC 8859\(hy6:\|1999 +ISO-IR 8859 7 1987!ISO/IEC 8859\(hy7:\|1987 +ISO-IR 8859 8 1999!ISO/IEC 8859\(hy8:\|1999 +ISO-IR 8859 9 1999!ISO/IEC 8859\(hy9:\|1999 +ISO-IR 8859 10 1998!ISO/IEC 8859\(hy10:\|1998 +ISO-IR 8859 13 1998!ISO/IEC 8859\(hy13:\|1998 +ISO-IR 8859 14 1998!ISO/IEC 8859\(hy14:\|1998 +ISO-IR 8859 15 1999!ISO/IEC 8859\(hy15:\|1999 +ISO-IR 10646 2000!ISO/IEC 10646:\|2000 +ISO-IR 10646 2000 UTF-8!ISO/IEC 10646, UTF-8 encoding +BINARY!None. +.TE +.RS 10 +.P +The encoding is included in an extended header for information only; +when +.IR pax +is used as described in POSIX.1\(hy2008, it shall not translate the file data +into any other encoding. The +.BR BINARY +entry indicates unencoded binary data. +.P +When used in +.BR write +or +.BR copy +mode, it is implementation-defined whether +.IR pax +includes a +.BR charset +extended header record for a file. +.RE +.IP "\fBcomment\fP" 10 +A series of characters used as a comment. All characters in the +<\fIvalue\fP> field shall be ignored by +.IR pax . +.IP "\fBgid\fP" 10 +The group ID of the group that owns the file, expressed as a decimal +number using digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR gid +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR gid +extended header record for each file whose group ID is greater than +2\|097\|151 (octal 7\|777\|777). +.IP "\fBgname\fP" 10 +The group of the file(s), formatted as a group name in the group +database. This record shall override the +.IR gid +and +.IR gname +fields in the following header block(s), and any +.IR gid +extended header record. When used in +.BR read , +.BR copy , +or +.BR list +mode, +.IR pax +shall translate the name from the encoding in the header record to +the character set appropriate for the group database on the +receiving system. If any of the characters cannot be +translated, and if neither the +.BR \(mio \c +.BR invalid=UTF\(hy8 +option nor the +.BR \(mio \c +.BR invalid=binary +option is specified, the results are implementation-defined. +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR gname +extended header record for each file whose group name cannot be +represented entirely with the letters and digits of the portable +character set. +.IP "\fBhdrcharset\fR" 10 +The name of the character set used to encode the value field of the +.BR gname , +.BR linkpath , +.BR path , +and +.BR uname +.IR pax +extended header records. The entries in the following table are defined +to refer to known standards; additional names may be agreed between the +originator and the recipient. +.TS +center box tab(!); +cB | cB +lf5 | l. +!Formal Standard +_ +ISO-IR 10646 2000 UTF-8!ISO/IEC 10646, UTF-8 encoding +BINARY!None. +.TE +.RS 10 +.P +If no +.BR hdrcharset +extended header record is specified, the default character set used to +encode all values in extended header records shall be the ISO/IEC\ 10646\(hy1:\|2000 standard +UTF\(hy8 encoding. +.P +The +.BR BINARY +entry indicates that all values recorded in extended headers for +affected files are unencoded binary data from the underlying system. +.RE +.IP "\fBlinkpath\fP" 10 +The pathname of a link being created to another file, of any type, +previously archived. This record shall override the +.IR linkname +field in the following +.BR ustar +header block(s). The following +.BR ustar +header block shall determine the type of link created. If +.IR typeflag +of the following header block is 1, it shall be a hard link. If +.IR typeflag +is 2, it shall be a symbolic link and the +.BR linkpath +value shall be the contents of the symbolic link. The +.IR pax +utility shall translate the name of the link (contents of the symbolic +link) from the encoding in the header to the character set appropriate +for the local file system. When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR linkpath +extended header record for each link whose pathname cannot be +represented entirely with the members of the portable character set +other than NUL. +.IP "\fBmtime\fP" 10 +The file modification time of the following file(s), equivalent to the +value of the +.IR st_mtime +member of the +.BR stat +structure for a file, as described in the +\fIstat\fR() +function. This record shall override the +.IR mtime +field in the following header block(s). The modification time shall be +restored if the process has appropriate privileges required to do +so. The format of the <\fIvalue\fP> shall be as described in +.IR "pax Extended Header File Times". +.IP "\fBpath\fP" 10 +The pathname of the following file(s). This record shall override the +.IR name +and +.IR prefix +fields in the following header block(s). The +.IR pax +utility shall translate the pathname of the file from the encoding in +the header to the character set appropriate for the local file system. +.RS 10 +.P +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR path +extended header record for each file whose pathname cannot be +represented entirely with the members of the portable character set +other than NUL. +.RE +.IP "\fBrealtime.\fIany\fR" 10 +The keywords prefixed by ``realtime.'' are reserved for future +standardization. +.IP "\fBsecurity.\fIany\fR" 10 +The keywords prefixed by ``security.'' are reserved for future +standardization. +.IP "\fBsize\fP" 10 +The size of the file in octets, expressed as a decimal number using +digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR size +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR size +extended header record for each file with a size value greater than +8\|589\|934\|591 (octal 77\|777\|777\|777). +.IP "\fBuid\fP" 10 +The user ID of the file owner, expressed as a decimal number using +digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR uid +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR uid +extended header record for each file whose owner ID is greater than +2\|097\|151 (octal 7\|777\|777). +.IP "\fBuname\fP" 10 +The owner of the following file(s), formatted as a user name in the +user database. This record shall override the +.IR uid +and +.IR uname +fields in the following header block(s), and any +.IR uid +extended header record. When used in +.BR read , +.BR copy , +or +.BR list +mode, +.IR pax +shall translate the name from the encoding in the header record to the +character set appropriate for the user database on the receiving +system. If any of the characters cannot be translated, and if neither +the +.BR \(mio \c +.BR invalid=UTF\(hy8 +option nor the +.BR \(mio \c +.BR invalid=binary +option is specified, the results are implementation-defined. +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR uname +extended header record for each file whose user name cannot be +represented entirely with the letters and digits of the portable +character set. +.P +If the <\fIvalue\fP> field is zero length, it shall delete any header +block field, previously entered extended header value, or global +extended header value of the same name. +.P +If a keyword in an extended header record (or in a +.BR \(mio +option-argument) overrides or deletes a corresponding field in the +.BR ustar +header block, +.IR pax +shall ignore the contents of that header block field. +.P +Unlike the +.BR ustar +header block fields, NULs shall not delimit <\fIvalue\fP>s; all +characters within the <\fIvalue\fP> field shall be considered data for +the field. None of the length limitations of the +.BR ustar +header block fields in +.IR "Table 4-14, ustar Header Block" +shall apply to the extended header records. +.SS "pax Extended Header Keyword Precedence" +.P +This section describes the precedence in which the various header +records and fields and command line options are selected to apply to a +file in the archive. When +.IR pax +is used in +.BR read +or +.BR list +modes, it shall determine a file attribute in the following sequence: +.IP " 1." 4 +If +.BR \(mio \c +.BR delete=keyword-prefix +is used, the affected attributes shall be determined from step 7., if +applicable, or ignored otherwise. +.IP " 2." 4 +If +.BR \(mio \c +.IR keyword := +is used, the affected attributes shall be ignored. +.IP " 3." 4 +If +.BR \(mio \c +.BR keyword:=value +is used, the affected attribute shall be assigned the value. +.IP " 4." 4 +If there is a +.IR typeflag +.BR x +extended header record, the affected attribute shall be assigned the +<\fIvalue\fP>. When extended header records conflict, the last one +given in the header shall take precedence. +.IP " 5." 4 +If +.BR \(mio \c +.BR keyword=value +is used, the affected attribute shall be assigned the value. +.IP " 6." 4 +If there is a +.IR typeflag +.BR g +global extended header record, the affected attribute shall be assigned +the <\fIvalue\fP>. When global extended header records conflict, the +last one given in the global header shall take precedence. +.IP " 7." 4 +Otherwise, the attribute shall be determined from the +.BR ustar +header block. +.SS "pax Extended Header File Times" +.P +The +.IR pax +utility shall write an +.BR mtime +record for each file in +.BR write +or +.BR copy +modes if the file's modification time cannot be represented exactly in +the +.BR ustar +header logical record described in +.IR "ustar Interchange Format". +This can occur if the time is out of +.BR ustar +range, or if the file system of the underlying implementation supports +non-integer time granularities and the time is not an integer. All of +these time records shall be formatted as a decimal representation of +the time in seconds since the Epoch. If a + +(\c +.BR '.' ) +decimal point character is present, the digits to the right of the +point shall represent the units of a subsecond timing granularity, +where the first digit is tenths of a second and each subsequent digit +is a tenth of the previous digit. In +.BR read +or +.BR copy +mode, the +.IR pax +utility shall truncate the time of a file to the greatest value that is +not greater than the input header file time. In +.BR write +or +.BR copy +mode, the +.IR pax +utility shall output a time exactly if it can be represented exactly as +a decimal number, and otherwise shall generate only enough digits so +that the same time shall be recovered if the file is extracted on a +system whose underlying implementation supports the same time +granularity. +.SS "ustar Interchange Format" +.P +A +.BR ustar +archive tape or file shall contain a series of logical records. Each +logical record shall be a fixed-size logical record of 512 octets (see +below). Although this format may be thought of as being stored on +9-track industry-standard 12.7 mm (0.5 in) magnetic tape, other types of +transportable media are not excluded. Each file archived shall be +represented by a header logical record that describes the file, +followed by zero or more logical records that give the contents of the +file. At the end of the archive file there shall be two 512-octet +logical records filled with binary zeros, interpreted as an +end-of-archive indicator. +.P +The logical records may be grouped for physical I/O operations, as +described under the +.BR \(mib \c +.IR blocksize +and +.BR \(mix +.BR ustar +options. Each group of logical records may be written with a single +operation equivalent to the +\fIwrite\fR() +function. On magnetic tape, the result of this write shall be a single +tape physical block. The last physical block shall always be the full +size, so logical records after the two zero logical records may contain +undefined data. +.P +The header logical record shall be structured as shown in the following +table. All lengths and offsets are in decimal. +.br +.sp +.ce 1 +\fBTable 4-14: ustar Header Block\fR +.TS +center box tab(@); +cB | cB | cB +lI | n | n. +Field Name@Octet Offset@Length (in Octets) +_ +name@0@100 +mode@100@8 +uid@108@8 +gid@116@8 +size@124@12 +mtime@136@12 +chksum@148@8 +typeflag@156@1 +linkname@157@100 +magic@257@6 +version@263@2 +uname@265@32 +gname@297@32 +devmajor@329@8 +devminor@337@8 +prefix@345@155 +.TE +.P +All characters in the header logical record shall be represented in the +coded character set of the ISO/IEC\ 646:\|1991 standard. For maximum portability between +implementations, names should be selected from characters represented +by the portable filename character set as octets with the most +significant bit zero. If an implementation supports the use of +characters outside of + +and the portable filename character set in names for files, users, and +groups, one or more implementation-defined encodings of these characters +shall be provided for interchange purposes. +.P +However, the +.IR pax +utility shall never create filenames on the local system that cannot +be accessed via the procedures described in POSIX.1\(hy2008. If a filename is +found on the medium that would create an invalid filename, it is +implementation-defined whether the data from the file is stored on the +file hierarchy and under what name it is stored. The +.IR pax +utility may choose to ignore these files as long as it produces an +error indicating that the file is being ignored. +.P +Each field within the header logical record is contiguous; that is, +there is no padding used. Each character on the archive medium shall be +stored contiguously. +.P +The fields +.IR magic , +.IR uname , +and +.IR gname +are character strings each terminated by a NUL character. The fields +.IR name , +.IR linkname , +and +.IR prefix +are NUL-terminated character strings except when all characters in the +array contain non-NUL characters including the last character. The +.IR version +field is two octets containing the characters +.BR \(dq00\(dq +(zero-zero). The +.IR typeflag +contains a single character. All other fields are leading zero-filled +octal numbers using digits from the ISO/IEC\ 646:\|1991 standard IRV. Each numeric field is +terminated by one or more + +or NUL characters. +.P +The +.IR name +and the +.IR prefix +fields shall produce the pathname of the file. A new pathname shall +be formed, if +.IR prefix +is not an empty string (its first character is not NUL), by +concatenating +.IR prefix +(up to the first NUL character), a + +character, and +.IR name ; +otherwise, +.IR name +is used alone. In either case, +.IR name +is terminated at the first NUL character. If +.IR prefix +begins with a NUL character, it shall be ignored. In this manner, +pathnames of at most 256 characters can be supported. If a pathname +does not fit in the space provided, +.IR pax +shall notify the user of the error, and shall not store any part of the +file\(emheader or data\(emon the medium. +.P +The +.IR linkname +field, described below, shall not use the +.IR prefix +to produce a pathname. As such, a +.IR linkname +is limited to 100 characters. If the name does not fit in the space +provided, +.IR pax +shall notify the user of the error, and shall not attempt to store the +link on the medium. +.P +The +.IR mode +field provides 12 bits encoded in the ISO/IEC\ 646:\|1991 standard octal digit representation. +The encoded bits shall represent the following values: +.br +.sp +.ce 1 +\fBTable: ustar \fImode\fP Field\fR +.TS +tab(!) center box; +cB | cB | cB +n | l | l. +Bit Value!POSIX.1\(hy2008 Bit!Description +_ +04\|000!S_ISUID!Set UID on execution. +02\|000!S_ISGID!Set GID on execution. +01\|000!!Reserved for future standardization. +00\|400!S_IRUSR!Read permission for file owner class. +00\|200!S_IWUSR!Write permission for file owner class. +00\|100!S_IXUSR!Execute/search permission for file owner class. +00\|040!S_IRGRP!Read permission for file group class. +00\|020!S_IWGRP!Write permission for file group class. +00\|010!S_IXGRP!Execute/search permission for file group class. +00\|004!S_IROTH!Read permission for file other class. +00\|002!S_IWOTH!Write permission for file other class. +00\|001!S_IXOTH!Execute/search permission for file other class. +.TE +.P +When appropriate privileges are required to set one of these mode bits, +and the user restoring the files from the archive does not have +appropriate privileges, the mode bits for which the user does not have +appropriate privileges shall be ignored. Some of the mode bits in the +archive format are not mentioned elsewhere in this volume of POSIX.1\(hy2008. If the +implementation does not support those bits, they may be ignored. +.P +The +.IR uid +and +.IR gid +fields are the user and group ID of the owner and group of the file, +respectively. +.P +The +.IR size +field is the size of the file in octets. If the +.IR typeflag +field is set to specify a file to be of type 1 (a link) or 2 (a +symbolic link), the +.IR size +field shall be specified as zero. If the +.IR typeflag +field is set to specify a file of type 5 (directory), the +.IR size +field shall be interpreted as described under the definition of that +record type. No data logical records are stored for types 1, 2, or 5. +If the +.IR typeflag +field is set to 3 (character special file), 4 (block special file), or +6 (FIFO), the meaning of the +.IR size +field is unspecified by this volume of POSIX.1\(hy2008, and no data logical records shall be +stored on the medium. Additionally, for type 6, the +.IR size +field shall be ignored when reading. If the +.IR typeflag +field is set to any other value, the number of logical records written +following the header shall be (\c +.IR size +511)/512, +ignoring any fraction in the result of the division. +.P +The +.IR mtime +field shall be the modification time of the file at the time it was +archived. It is the ISO/IEC\ 646:\|1991 standard representation of the octal value of the +modification time obtained from the +\fIstat\fR() +function. +.P +The +.IR chksum +field shall be the ISO/IEC\ 646:\|1991 standard IRV representation of the octal value of the +simple sum of all octets in the header logical record. Each octet in +the header shall be treated as an unsigned value. These values shall be +added to an unsigned integer, initialized to zero, the precision of +which is not less than 17 bits. When calculating the checksum, the +.IR chksum +field is treated as if it were all + +characters. +.P +The +.IR typeflag +field specifies the type of file archived. If a particular +implementation does not recognize the type, or the user does not have +appropriate privileges to create that type, the file shall be extracted +as if it were a regular file if the file type is defined to have a +meaning for the +.IR size +field that could cause data logical records to be written on the medium +(see the previous description for +.IR size ). +If conversion to a regular file occurs, the +.IR pax +utility shall produce an error indicating that the conversion took +place. All of the +.IR typeflag +fields shall be coded in the ISO/IEC\ 646:\|1991 standard IRV: +.IP "\fR0\fR" 8 +Represents a regular file. For backwards-compatibility, a +.IR typeflag +value of binary zero (\c +.BR '\e0' ) +should be recognized as meaning a regular file when extracting files +from the archive. Archives written with this version of the archive +file format create regular files with a +.IR typeflag +value of the ISO/IEC\ 646:\|1991 standard IRV +.BR '0' . +.IP "\fR1\fR" 8 +Represents a file linked to another file, of any type, previously +archived. Such files are identified by having the same device +and file serial numbers, and pathnames that refer to different +directory entries. All such files shall be archived as linked files. +The linked-to name is specified in the +.IR linkname +field with a NUL-character terminator if it is less than 100 octets in +length. +.IP "\fR2\fR" 8 +Represents a symbolic link. The contents of the symbolic link shall be +stored in the +.IR linkname +field. +.IP "\fR3,4\fR" 8 +Represent character special files and block special files respectively. +In this case the +.IR devmajor +and +.IR devminor +fields shall contain information defining the device, the format of +which is unspecified by this volume of POSIX.1\(hy2008. Implementations may map the device +specifications to their own local specification or may ignore the +entry. +.IP "\fR5\fR" 8 +Specifies a directory or subdirectory. On systems where disk allocation +is performed on a directory basis, the +.IR size +field shall contain the maximum number of octets (which may be rounded +to the nearest disk block allocation unit) that the directory may hold. +A +.IR size +field of zero indicates no such limiting. Systems that do not support +limiting in this manner should ignore the +.IR size +field. +.IP "\fR6\fR" 8 +Specifies a FIFO special file. Note that the archiving of a FIFO file +archives the existence of this file and not its contents. +.IP "\fR7\fR" 8 +Reserved to represent a file to which an implementation has associated +some high-performance attribute. Implementations without such +extensions should treat this file as a regular file (type 0). +.IP "\fRA\(hyZ\fR" 8 +The letters +.BR 'A' +to +.BR 'Z' , +inclusive, are reserved for custom implementations. All other values +are reserved for future versions of this standard. +.P +It is unspecified whether files with pathnames that refer to the same +directory entry are archived as linked files or as separate files. If +they are archived as linked files, this means that attempting to +extract both pathnames from the resulting archive will always cause an +error (unless the +.BR \(miu +option is used) because the link cannot be created. +.P +It is unspecified whether files with the same device and file serial +numbers being appended to an archive are treated as linked files to +members that were in the archive before the append. +.P +Attempts to archive a socket using +.BR ustar +interchange format shall produce a diagnostic message. Handling of +other file types is implementation-defined. +.P +The +.IR magic +field is the specification that this archive was output in this archive +format. If this field contains +.BR ustar +(the five characters from the ISO/IEC\ 646:\|1991 standard IRV shown followed by NUL), the +.IR uname +and +.IR gname +fields shall contain the ISO/IEC\ 646:\|1991 standard IRV representation of the owner and +group of the file, respectively (truncated to fit, if necessary). When +the file is restored by a privileged, protection-preserving version of +the utility, the user and group databases shall be scanned for these +names. If found, the user and group IDs contained within these files +shall be used rather than the values contained within the +.IR uid +and +.IR gid +fields. +.SS "cpio Interchange Format" +.P +The octet-oriented +.BR cpio +archive format shall be a series of entries, each comprising a header +that describes the file, the name of the file, and then the contents of +the file. +.P +An archive may be recorded as a series of fixed-size blocks of octets. +This blocking shall be used only to make physical I/O more efficient. +The last group of blocks shall always be at the full size. +.P +For the octet-oriented +.BR cpio +archive format, the individual entry information shall be in the order +indicated and described by the following table; see also the +.IR +header. +.br +.sp +.ce 1 +\fBTable 4-16: Octet-Oriented cpio Archive Entry\fR +.TS +center box tab(!); +cB | cB | cB +lI | n | l. +Header Field Name!Length (in Octets)!Interpreted as +_ +c_magic!6!Octal number +c_dev!6!Octal number +c_ino!6!Octal number +c_mode!6!Octal number +c_uid!6!Octal number +c_gid!6!Octal number +c_nlink!6!Octal number +c_rdev!6!Octal number +c_mtime!11!Octal number +c_namesize!6!Octal number +c_filesize!11!Octal number +_ +.T& +cB | cB | cB +lI lI l. +Filename Field Name!Length!Interpreted as +_ +c_name!c_namesize!Pathname string +_ +.T& +cB | cB | cB +lI lI l. +File Data Field Name!Length!Interpreted as +_ +c_filedata!c_filesize!Data +.TE +.SS "cpio Header" +.P +For each file in the archive, a header as defined previously shall be +written. The information in the header fields is written as streams of +the ISO/IEC\ 646:\|1991 standard characters interpreted as octal numbers. The octal numbers +shall be extended to the necessary length by appending the ISO/IEC\ 646:\|1991 standard IRV +zeros at the most-significant-digit end of the number; the result is +written to the most-significant digit of the stream of octets first. +The fields shall be interpreted as follows: +.IP "\fIc_magic\fR" 10 +Identify the archive as being a transportable archive by containing the +identifying value +.BR \(dq070707\(dq . +.IP "\fIc_dev\fR,\ \fIc_ino\fR" 10 +Contains values that uniquely identify the file within the archive +(that is, no files contain the same pair of +.IR c_dev +and +.IR c_ino +values unless they are links to the same file). The values shall be +determined in an unspecified manner. +.IP "\fIc_mode\fR" 10 +Contains the file type and access permissions as defined in the +following table. +.br +.sp +.ce 1 +\fBTable 4-17: Values for cpio c_mode Field\fR +.TS +center box tab(@); +cB | cB | cB +l | n | l. +File Permissions Name@Value@Indicates +_ +C_IRUSR@000\|400@Read by owner +C_IWUSR@000\|200@Write by owner +C_IXUSR@000\|100@Execute by owner +C_IRGRP@000\|040@Read by group +C_IWGRP@000\|020@Write by group +C_IXGRP@000\|010@Execute by group +C_IROTH@000\|004@Read by others +C_IWOTH@000\|002@Write by others +C_IXOTH@000\|001@Execute by others +C_ISUID@004\|000@Set \fIuid\fP +C_ISGID@002\|000@Set \fIgid\fP +C_ISVTX@001\|000@Reserved +_ +.T& +cB | cB | cB +l | n | l. +File Type Name@Value@Indicates +_ +C_ISDIR@040\|000@Directory +C_ISFIFO@010\|000@FIFO +C_ISREG@0100\|000@Regular file +C_ISLNK@0120\|000@Symbolic link +.RS 10 +.P +C_ISBLK@060\|000@Block special file +C_ISCHR@020\|000@Character special file +C_ISSOCK@0140\|000@Socket +.P +C_ISCTG@0110\|000@Reserved +.TE +.P +Directories, FIFOs, symbolic links, and regular files shall be +supported on a system conforming to this volume of POSIX.1\(hy2008; additional values defined +previously are reserved for compatibility with existing systems. +Additional file types may be supported; however, such files should not +be written to archives intended to be transported to other systems. +.RE +.IP "\fIc_uid\fR" 10 +Contains the user ID of the owner. +.IP "\fIc_gid\fR" 10 +Contains the group ID of the group. +.IP "\fIc_nlink\fR" 10 +Contains a number greater than or equal to the number of links in the +archive referencing the file. If the +.BR \(mia +option is used to append to a +.IR cpio +archive, then the +.IR pax +utility need not account for the files in the existing part of the +archive when calculating the +.IR c_nlink +values for the appended part of the archive, and need not alter the +.IR c_nlink +values in the existing part of the archive if additional files with the +same +.IR c_dev +and +.IR c_ino +values are appended to the archive. +.IP "\fIc_rdev\fR" 10 +Contains implementation-defined information for character or block +special files. +.IP "\fIc_mtime\fR" 10 +Contains the latest time of modification of the file at the time the +archive was created. +.IP "\fIc_namesize\fR" 10 +Contains the length of the pathname, including the terminating NUL +character. +.IP "\fIc_filesize\fR" 10 +Contains the length in octets of the data section following the +header structure. +.SS "cpio Filename" +.P +The +.IR c_name +field shall contain the pathname of the file. The length of this field +in octets is the value of +.IR c_namesize . +.P +If a filename is found on the medium that would create an invalid +pathname, it is implementation-defined whether the data from the file +is stored on the file hierarchy and under what name it is stored. +.P +All characters shall be represented in the ISO/IEC\ 646:\|1991 standard IRV. For maximum +portability between implementations, names should be selected from +characters represented by the portable filename character set as +octets with the most significant bit zero. If an implementation +supports the use of characters outside the portable filename character +set in names for files, users, and groups, one or more +implementation-defined encodings of these characters shall be provided +for interchange purposes. However, the +.IR pax +utility shall never create filenames on the local system that cannot +be accessed via the procedures described previously in this volume of POSIX.1\(hy2008. If a +filename is found on the medium that would create an invalid filename, +it is implementation-defined whether the data from the file is stored on +the local file system and under what name it is stored. The +.IR pax +utility may choose to ignore these files as long as it produces an +error indicating that the file is being ignored. +.SS "cpio File Data" +.P +Following +.IR c_name , +there shall be +.IR c_filesize +octets of data. Interpretation of such data occurs in a manner +dependent on the file. For regular files, the data shall consist +of the contents of the file. For symbolic links, the data shall +consist of the contents of the symbolic link. If +.IR c_filesize +is zero, no data shall be contained in +.IR c_filedata . +.P +When restoring from an archive: +.IP " *" 4 +If the user does not have appropriate privileges to create a file of +the specified type, +.IR pax +shall ignore the entry and write an error message to standard error. +.IP " *" 4 +Only regular files and symbolic links have data to be restored. Presuming +a regular file meets any selection criteria that might be imposed on +the format-reading utility by the user, such data shall be restored. +.IP " *" 4 +If a user does not have appropriate privileges to set a particular mode +flag, the flag shall be ignored. Some of the mode flags in the archive +format are not mentioned elsewhere in this volume of POSIX.1\(hy2008. If the implementation does +not support those flags, they may be ignored. +.SS "cpio Special Entries" +.P +FIFO special files, directories, and the trailer shall be recorded with +.IR c_filesize +equal to zero. Symbolic links shall be recorded with +.IR c_filesize +equal to the length of the contents of the symbolic link. +For other special files, +.IR c_filesize +is unspecified by this volume of POSIX.1\(hy2008. The header for the next file entry in the +archive shall be written directly after the last octet of the file +entry preceding it. A header denoting the filename +.BR TRAILER!!! +shall indicate the end of the archive; the contents of octets in the +last block of the archive following such a header are undefined. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If +.IR pax +cannot create a file or a link when reading an archive or cannot find a +file when writing an archive, or cannot preserve the user ID, group ID, +or file mode when the +.BR \(mip +option is specified, a diagnostic message shall be written to standard +error and a non-zero exit status shall be returned, but processing +shall continue. In the case where +.IR pax +cannot create a link to a file, +.IR pax +shall not, by default, create a second copy of the file. +.P +If the extraction of a file from an archive is prematurely terminated +by a signal or error, +.IR pax +may have only partially extracted the file or (if the +.BR \(min +option was not specified) may have extracted a file of the same name as +that specified by the user, but which is not the file the user wanted. +Additionally, the file modes of extracted directories may have +additional bits from the S_IRWXU mask set as well as incorrect +modification and access times. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Caution is advised when using the +.BR \(mia +option to append to a +.IR cpio +format archive. If any of the files being appended happen to be given +the same +.IR c_dev +and +.IR c_ino +values as a file in the existing part of the archive, then they may be +treated as links to that file on extraction. Thus, it is risky to use +.BR \(mia +with +.IR cpio +format except when it is done on the same system that the original +archive was created on, and with the same +.IR pax +utility, and in the knowledge that there has been little or no file +system activity since the original archive was created that could lead +to any of the files appended being given the same +.IR c_dev +and +.IR c_ino +values as an unrelated file in the existing part of the archive. Also, +when (intentionally) appending additional links to a file in the +existing part of the archive, the +.IR c_nlink +values in the modified archive can be smaller than the number of links +to the file in the archive, which may mean that the links are not +preserved on extraction. +.P +The +.BR \(mip +(privileges) option was invented to reconcile differences between +historical +.IR tar +and +.IR cpio +implementations. In particular, the two utilities use +.BR \(mim +in diametrically opposed ways. The +.BR \(mip +option also provides a consistent means of extending the ways in which +future file attributes can be addressed, such as for enhanced security +systems or high-performance files. Although it may seem complex, there +are really two modes that are most commonly used: +.IP "\fB\(mip\ e\fR" 8 +``Preserve everything''. This would be used by the historical +superuser, someone with all appropriate privileges, to preserve all +aspects of the files as they are recorded in the archive. The +.BR e +flag is the sum of +.BR o +and +.BR p , +and other implementation-defined attributes. +.IP "\fB\(mip\ p\fR" 8 +``Preserve'' the file mode bits. This would be used by the user with +regular privileges who wished to preserve aspects of the file other +than the ownership. The file times are preserved by default, but two +other flags are offered to disable these and use the time of +extraction. +.P +The one pathname per line format of standard input precludes +pathnames containing + +characters. Although such pathnames violate the portable filename +guidelines, they may exist and their presence may inhibit usage of +.IR pax +within shell scripts. This problem is inherited from historical archive +programs. The problem can be avoided by listing filename arguments on +the command line instead of on standard input. +.P +It is almost certain that appropriate privileges are required for +.IR pax +to accomplish parts of this volume of POSIX.1\(hy2008. Specifically, creating files of type +block special or character special, restoring file access times unless +the files are owned by the user (the +.BR \(mit +option), or preserving file owner, group, and mode (the +.BR \(mip +option) all probably require appropriate privileges. +.P +In +.BR read +mode, implementations are permitted to overwrite files when the archive +has multiple members with the same name. This may fail if permissions +on the first version of the file do not permit it to be overwritten. +.P +The +.BR cpio +and +.BR ustar +formats can only support files up to 8\|589\|934\|592 bytes +(8 \(** 2^30) in size. +.P +When archives containing binary header information are listed , the +filenames printed may cause strange behavior on some terminals. +.P +When all of the following are true: +.IP " 1." 4 +A file of type directory is being placed into an archive. +.IP " 2." 4 +The +.BR ustar +archive format is being used. +.IP " 3." 4 +The pathname of the directory is less than or equal to 155 bytes long +(it will fit in the +.IR prefix +field in the +.BR ustar +header block). +.IP " 4." 4 +The last component of the pathname of the directory is longer than 100 +bytes long (it will not fit in the +.IR name +field in the +.BR ustar +header block). +.P +some implementations of the +.IR pax +utility will place the entire directory pathname in the +.IR prefix +field, set the +.IR name +field to an empty string, and place the directory in the archive. +Other implementations of the +.IR pax +utility will give an error under these conditions because the +.IR name +field is not large enough to hold the last component of the directory name. +This standard allows either behavior. However, when extracting a directory +from a +.BR ustar +format archive, this standard requires that all implementations be able +to extract a directory even if the +.IR name +field contains an empty string as long as the +.IR prefix +field does not also contain an empty string. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +pax \(miw \(mif /dev/rmt/1m . +.fi \fR +.P +.RE +.P +copies the contents of the current directory to tape drive 1, medium +density (assuming historical System V device naming procedures\(emthe +historical BSD device name would be +.BR /dev/rmt9 ). +.P +The following commands: +.sp +.RS 4 +.nf +\fB +mkdir \fInewdir\fR +pax \(mirw \fIolddir newdir\fR +.fi \fR +.P +.RE +.P +copy the +.IR olddir +directory hierarchy to +.IR newdir . +.sp +.RS 4 +.nf +\fB +pax \(mir \(mis ',^//*usr//*,,' \(mif a.pax +.fi \fR +.P +.RE +.P +reads the archive +.BR a.pax , +with all files rooted in +.BR /usr +in the archive extracted relative to the current directory. +.P +Using the option: +.sp +.RS 4 +.nf +\fB +\(mio listopt="%M %(atime)T %(size)D %(name)s" +.fi \fR +.P +.RE +.P +overrides the default output description in Standard Output and instead +writes: +.sp +.RS 4 +.nf +\fB +\(mirw\(mirw\(mi\|\(mi\|\(mi Jan 12 15:53 2003 1492 /usr/foo/bar +.fi \fR +.P +.RE +.P +Using the options: +.sp +.RS 4 +.nf +\fB +\(mio listopt='%L\et%(size)D\en%.7' \e +\(mio listopt='(name)s\en%(atime)T\en%T' +.fi \fR +.P +.RE +.P +overrides the default output description in Standard Output and instead +writes: +.sp +.RS 4 +.nf +\fB +/usr/foo/bar \(mi> /tmp 1492 +/usr/fo +Jan 12 15:53 1991 +Jan 31 15:53 2003 +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR pax +utility was new for the ISO\ POSIX\(hy2:\|1993 standard. It represents a peaceful +compromise between advocates of the historical +.IR tar +and +.IR cpio +utilities. +.P +A fundamental difference between +.IR cpio +and +.IR tar +was in the way directories were treated. The +.IR cpio +utility did not treat directories differently from other files, and to +select a directory and its contents required that each file in the +hierarchy be explicitly specified. For +.IR tar , +a directory matched every file in the file hierarchy it rooted. +.P +The +.IR pax +utility offers both interfaces; by default, directories map into the +file hierarchy they root. The +.BR \(mid +option causes +.IR pax +to skip any file not explicitly referenced, as +.IR cpio +historically did. The +.IR tar +.BR \(mi \c +.IR style +behavior was chosen as the default because it was believed that this +was the more common usage and because +.IR tar +is the more commonly available interface, as it was historically +provided on both System V and BSD implementations. +.P +The data interchange format specification in this volume of POSIX.1\(hy2008 requires that +processes with ``appropriate privileges'' shall always restore the +ownership and permissions of extracted files exactly as archived. If +viewed from the historic equivalence between superuser and +``appropriate privileges'', there are two problems +with this requirement. First, users running as superusers may +unknowingly set dangerous permissions on extracted files. Second, it is +needlessly limiting, in that superusers cannot extract files and own +them as superuser unless the archive was created by the superuser. (It +should be noted that restoration of ownerships and permissions for the +superuser, by default, is historical practice in +.IR cpio , +but not in +.Im tar .) +In order to avoid these two problems, the +.IR pax +specification has an additional ``privilege'' mechanism, the +.BR \(mip +option. Only a +.IR pax +invocation with the privileges needed, and which has the +.BR \(mip +option set using the +.BR e +specification character, has appropriate privileges to restore +full ownership and permission information. +.P +Note also that this volume of POSIX.1\(hy2008 requires that the file ownership and access +permissions shall be set, on extraction, in the same fashion as the +\fIcreat\fR() +function when provided with the mode stored in the archive. This means +that the file creation mask of the user is applied to the file +permissions. +.P +Users should note that directories may be created by +.IR pax +while extracting files with permissions that are different from those +that existed at the time the archive was created. When extracting +sensitive information into a directory hierarchy that no longer exists, +users are encouraged to set their file creation mask appropriately to +protect these files during extraction. +.P +The table of contents output is written to standard output to +facilitate pipeline processing. +.P +An early proposal had hard links displaying for all pathnames. This +was removed because it complicates the output of the case where +.BR \(miv +is not specified and does not match historical +.IR cpio +usage. The hard-link information is available in the +.BR \(miv +display. +.P +The description of the +.BR \(mil +option allows implementations to make hard links to symbolic links. +Earlier versions of this standard did not specify any way to create a +hard link to a symbolic link, but many implementations provided this +capability as an extension. If there are hard links to symbolic links +when an archive is created, the implementation is required to archive +the hard link in the archive (unless +.BR \(miH +or +.BR \(miL +is specified). When in +.BR read +mode and in +.BR copy +mode, implementations supporting hard links to symbolic links should +use them when appropriate. +.P +The archive formats inherited from the POSIX.1\(hy1990 standard have certain restrictions +that have been brought along from historical usage. For example, there +are restrictions on the length of pathnames stored in the archive. +When +.IR pax +is used in +.BR copy (\c +.BR \(mirw ) +mode (copying directory hierarchies), the ability to use extensions +from the +.BR \(mix \c +.BR pax +format overcomes these restrictions. +.P +The default +.IR blocksize +value of 5\|120 bytes for +.IR cpio +was selected because it is one of the standard block-size values for +.IR cpio , +set when the +.BR \(miB +option is specified. (The other default block-size value for +.IR cpio +is 512 bytes, and this was considered to be too small.) The default +block value of 10\|240 bytes for +.IR tar +was selected because that is the standard block-size value for BSD +.IR tar . +The maximum block size of 32\|256 bytes (2\s-3\u15\d\s+3\(mi512 bytes) +is the largest multiple of 512 bytes that fits into a signed 16-bit +tape controller transfer register. There are known limitations in some +historical systems that would prevent larger blocks from being +accepted. Historical values were chosen to improve compatibility with +historical scripts using +.IR dd +or similar utilities to manipulate archives. Also, default block sizes +for any file type other than character special file has been deleted +from this volume of POSIX.1\(hy2008 as unimportant and not likely to affect the structure of the +resulting archive. +.P +Implementations are permitted to modify the block-size value based on +the archive format or the device to which the archive is being +written. This is to provide implementations with the opportunity to +take advantage of special types of devices, and it should not be used +without a great deal of consideration as it almost certainly decreases +archive portability. +.P +The intended use of the +.BR \(min +option was to permit extraction of one or more files from the archive +without processing the entire archive. This was viewed by the standard +developers as offering significant performance advantages over +historical implementations. The +.BR \(min +option in early proposals had three effects; the first was to cause +special characters in patterns to not be treated specially. The second +was to cause only the first file that matched a pattern to be +extracted. The third was to cause +.IR pax +to write a diagnostic message to standard error when no file was found +matching a specified pattern. Only the second behavior is retained by +this volume of POSIX.1\(hy2008, for many reasons. First, it is in general not acceptable for a +single option to have multiple effects. Second, the ability to make +pattern matching characters act as normal characters +is useful for parts of +.IR pax +other than file extraction. Third, a finer degree of control over the +special characters is useful because users may wish to normalize only a +single special character in a single filename. Fourth, given a more +general escape mechanism, the previous behavior of the +.BR \(min +option can be easily obtained using the +.BR \(mis +option or a +.IR sed +script. Finally, writing a diagnostic message when a pattern specified +by the user is unmatched by any file is useful behavior in all cases. +.P +In this version, the +.BR \(min +was removed from the +.BR copy +mode synopsis of +.IR pax ; +it is inapplicable because there are no pattern operands specified in +this mode. +.P +There is another method than +.IR pax +for copying subtrees in POSIX.1\(hy2008 described as part of the +.IR cp +utility. Both methods are historical practice: +.IR cp +provides a simpler, more intuitive interface, while +.IR pax +offers a finer granularity of control. Each provides additional +functionality to the other; in particular, +.IR pax +maintains the hard-link structure of the hierarchy while +.IR cp +does not. It is the intention of the standard developers that the +results be similar (using appropriate option combinations in both +utilities). The results are not required to be identical; there seemed +insufficient gain to applications to balance the difficulty of +implementations having to guarantee that the results would be exactly +identical. +.P +A single archive may span more than one file. It is suggested that +implementations provide informative messages to the user on standard +error whenever the archive file is changed. +.P +The +.BR \(mid +option (do not create intermediate directories not listed in the +archive) found in early proposals was originally provided as a +complement to the historic +.BR \(mid +option of +.IR cpio . +It has been deleted. +.P +The +.BR \(mis +option in early proposals specified a subset of the substitution +command from the +.IR ed +utility. As there was no reason for only a subset to be supported, the +.BR \(mis +option is now compatible with the current +.IR ed +specification. Since the delimiter can be any non-null character, the +following usage with single + +characters is valid: +.sp +.RS 4 +.nf +\fB +pax \(mis " foo bar " ... +.fi \fR +.P +.RE +.P +The +.BR \(mit +description is worded so as to note that this may cause the access time +update caused by some other activity (which occurs while the file is +being read) to be overwritten. +.P +The default behavior of +.IR pax +with regard to file modification times is the same as historical +implementations of +.IR tar . +It is not the historical behavior of +.IR cpio . +.P +Because the +.BR \(mii +option uses +.BR /dev/tty , +utilities without a controlling terminal are not able to use this +option. +.P +The +.BR \(miy +option, found in early proposals, has been deleted because a line +containing a single + +for the +.BR \(mii +option has equivalent functionality. The special lines for the +.BR \(mii +option (a single + +and the empty line) are historical practice in +.IR cpio . +.P +In early drafts, a +.BR \(mie \c +.IR charmap +option was included to increase portability of files between systems +using different coded character sets. This option was omitted because +it was apparent that consensus could not be formed for it. In this +version, the use of UTF\(hy8 should be an adequate substitute. +.P +The ISO\ POSIX\(hy2:\|1993 standard and ISO\ POSIX\(hy1 standard requirements for +.IR pax , +however, made it very difficult to create a single archive containing +files created using extended characters provided by different locales. +This version adds the +.BR hdrcharset +keyword to make it possible to archive files in these cases without +dropping files due to translation errors. +.P +Translating filenames and other attributes from a locale's encoding to +UTF\(hy8 and then back again can lose information, as the resulting +filename might not be byte-for-byte equivalent to the original. To +avoid this problem, users can specify the +.BR \(mio +.BR hdrcharset=binary +option, which will cause the resulting archive to use binary +format for all names and attributes. Such archives are not portable +among hosts that use different native encodings (e.g., EBCDIC +\fIversus\fR ASCII-based encodings), but they will allow interchange +among the vast majority of POSIX file systems in practical use. Also, +the +.BR \(mio +.BR hdrcharset=binary +option will cause +.IR pax +in +.BR copy +mode to behave more like other standard utilities such as +.IR cp . +.P +If the values specified by the +.BR \(mio +.BR exthdr.name=value , +.BR \(mio +.BR globexthdr.name=value , +or by +.BR $TMPDIR +(if +.BR \(mio +.BR globexthdr.name +is not specified) require a character encoding other than that +described in the ISO/IEC\ 646:\|1991 standard, a +.BR path +extended header record will have to be created for the file. If a +.BR hdrcharset +extended header record is active for such headers, it will determine +the codeset used for the value field in these extended +.BR path +header records. These +.BR path +extended header records always need to be created when writing an +archive even if +.BR hdrcharset=binary +has been specified and would contain the same (binary) data that +appears in the +.BR ustar +header record prefix and +.IR name +fields. (In other words, an extended header +.BR path +record is always required to be generated if the +.IR prefix +or +.IR name +fields contain non-ASCII characters even when +.BR hdrcharset=binary +is also in effect for that file.) +.P +The +.BR \(mik +option was added to address international concerns about the dangers +involved in the character set transformations of +.BR \(mie +(if the target character set were different from the source, the +filenames might be transformed into names matching existing files) and +also was made more general to protect files transferred between file +systems with different +{NAME_MAX} +values (truncating a filename on a smaller system might also +inadvertently overwrite existing files). As stated, it prevents any +overwriting, even if the target file is older than the source. This +version adds more granularity of options to solve this problem by +introducing the +.BR \(mio \c +.BR invalid=option \c +\(emspecifically the +.BR UTF\(hy8 +and +.BR binary +actions. (Note that an existing file is still subject to overwriting in +this case. The +.BR \(mik +option closes that loophole.) +.P +Some of the file characteristics referenced in this volume of POSIX.1\(hy2008 might not be +supported by some archive formats. For example, neither the +.BR tar +nor +.BR cpio +formats contain the file access time. For this reason, the +.BR e +specification character has been provided, intended to cause all file +characteristics specified in the archive to be retained. +.P +It is required that extracted directories, by default, have their +access and modification times and permissions set to the values +specified in the archive. This has obvious problems in that the +directories are almost certainly modified after being extracted and +that directory permissions may not permit file creation. One possible +solution is to create directories with the mode specified in the +archive, as modified by the +.IR umask +of the user, with sufficient permissions to allow file creation. After +all files have been extracted, +.IR pax +would then reset the access and modification times and permissions as +necessary. +.P +The list-mode formatting description borrows heavily from the one +defined by the +.IR printf +utility. However, since there is no separate operand list to get +conversion arguments, the format was extended to allow specifying the +name of the conversion argument as part of the conversion +specification. +.P +The +.BR T +conversion specifier allows time fields to be displayed in any of +the date formats. Unlike the +.IR ls +utility, +.IR pax +does not adjust the format when the date is less than six months in the +past. This makes parsing the output more predictable. +.P +The +.BR D +conversion specifier handles the ability to display the major/minor +or file size, as with +.IR ls , +by using \fR%\(mi8(\fIsize\fR)D\fR. +.P +The +.BR L +conversion specifier handles the +.IR ls +display for symbolic links. +.P +Conversion specifiers were added to generate existing known types used +for +.IR ls . +.SS "pax Interchange Format" +.P +The new POSIX data interchange format was developed primarily to +satisfy international concerns that the +.BR ustar +and +.BR cpio +formats did not provide for file, user, and group names encoded in +characters outside a subset of the ISO/IEC\ 646:\|1991 standard. The standard developers +realized that this new POSIX data interchange format should be very +extensible because there were other requirements they foresaw in the +near future: +.IP " *" 4 +Support international character encodings and locale information +.IP " *" 4 +Support security information (ACLs, and so on) +.IP " *" 4 +Support future file types, such as realtime or contiguous files +.IP " *" 4 +Include data areas for implementation use +.IP " *" 4 +Support systems with words larger than 32 bits and timers with +subsecond granularity +.P +The following were not goals for this format because these are better +handled by separate utilities or are inappropriate for a portable +format: +.IP " *" 4 +Encryption +.IP " *" 4 +Compression +.IP " *" 4 +Data translation between locales and codesets +.IP " *" 4 +.IR inode +storage +.P +The format chosen to support the goals is an extension of the +.BR ustar +format. Of the two formats previously available, only the +.BR ustar +format was selected for extensions because: +.IP " *" 4 +It was easier to extend in an upwards-compatible way. It offered version +flags and header block type fields with room for future +standardization. The +.BR cpio +format, while possessing a more flexible file naming methodology, could +not be extended without breaking some theoretical implementation +or using a dummy filename that could be a legitimate filename. +.IP " *" 4 +Industry experience since the original ``\c +.IR tar +wars'' fought in developing the ISO\ POSIX\(hy1 standard has clearly been in favor of the +.BR ustar +format, which is generally the default output format selected for +.IR pax +implementations on new systems. +.P +The new format was designed with one additional goal in mind: +reasonable behavior when an older +.IR tar +or +.IR pax +utility happened to read an archive. Since the POSIX.1\(hy1990 standard mandated that a +``format-reading utility'' had to treat unrecognized +.IR typeflag +values as regular files, this allowed the format to include all the +extended information in a pseudo-regular file that preceded each real +file. An option is given that allows the archive creator to set up +reasonable names for these files on the older systems. Also, the +normative text suggests that reasonable file access values be used for +this +.BR ustar +header block. Making these header files inaccessible for convenient +reading and deleting would not be reasonable. File permissions of 600 +or 700 are suggested. +.P +The +.BR ustar +.IR typeflag +field was used to accommodate the additional functionality of the new +format rather than magic or version because the POSIX.1\(hy1990 standard (and, by +reference, the previous version of +.IR pax ), +mandated the behavior of the format-reading utility when it encountered +an unknown +.IR typeflag , +but was silent about the other two fields. +.P +Early proposals for the first version of this standard contained a proposed +archive format that was based on compatibility with the standard for +tape files (ISO\ 1001, similar to the format used historically on many +mainframes and minicomputers). This format was overly complex and required +considerable overhead in volume and header records. Furthermore, the +standard developers felt that it would not be acceptable to the community +of POSIX developers, so it was later changed to be a format more closely +related to historical practice on POSIX systems. +.P +The prefix and name split of pathnames in +.BR ustar +was replaced by the single path extended header record for simplicity. +.P +The concept of a global extended header (\c +.IR typeflag \c +.BR g ) +was controversial. If this were applied to an archive being recorded on +magnetic tape, a few unreadable blocks at the beginning of the tape +could be a serious problem; a utility attempting to extract as many +files as possible from a damaged archive could lose a large percentage +of file header information in this case. However, if the archive were +on a reliable medium, such as a CD\(hyROM, the global extended header +offers considerable potential size reductions by eliminating redundant +information. Thus, the text warns against using the global method for +unreliable media and provides a method for implanting global +information in the extended header for each file, rather than in the +.IR typeflag +.BR g +records. +.P +No facility for data translation or filtering on a per-file basis is +included because the standard developers could not invent an interface +that would allow this in an efficient manner. If a filter, such as +encryption or compression, is to be applied to all the files, it is +more efficient to apply the filter to the entire archive as a single +file. The standard developers considered interfaces that would invoke a +shell script for each file going into or out of the archive, but the +system overhead in this approach was considered to be too high. +.P +One such approach would be to have +.BR filter= +records that give a pathname for an executable. When the program is +invoked, the file and archive would be open for standard input/output +and all the header fields would be available as environment variables +or command-line arguments. The standard developers did discuss such +schemes, but they were omitted from POSIX.1\(hy2008 due to concerns about +excessive overhead. Also, the program itself would need to be in the +archive if it were to be used portably. +.P +There is currently no portable means of identifying the character +set(s) used for a file in the file system. Therefore, +.IR pax +has not been given a mechanism to generate charset records +automatically. The only portable means of doing this is for the user to +write the archive using the +.BR \(mio \c +.BR charset=string +command line option. This assumes that all of the files in the archive +use the same encoding. The ``implementation-defined'' text is +included to allow for a system that can identify the encodings used for +each of its files. +.P +The table of standards that accompanies the charset record description +is acknowledged to be very limited. Only a limited number of character +set standards is reasonable for maximal interchange. Any character set +is, of course, possible by prior agreement. It was suggested that +EBCDIC be listed, but it was omitted because it is not defined by a +formal standard. Formal standards, and then only those with reasonably +large followings, can be included here, simply as a matter of +practicality. The <\fIvalue\fP>s represent names of officially +registered character sets in the format required by the ISO\ 2375:\|1985 standard. +.P +The normal + +or +-separated +list rules are not followed in the case of keyword options to allow +ease of argument parsing for +.IR getopts . +.P +Further information on character encodings is in +.IR "pax Archive Character Set Encoding/Decoding". +.P +The standard developers have reserved keyword name space for vendor +extensions. It is suggested that the format to be used is: +.sp +.RS 4 +.nf +\fB +\fIVENDOR.keyword\fR +.fi \fR +.P +.RE +.P +where +.IR VENDOR +is the name of the vendor or organization in all uppercase letters. It +is further suggested that the keyword following the + +be named differently than any of the standard keywords so that it could +be used for future standardization, if appropriate, by omitting the +.IR VENDOR +prefix. +.P +The <\fIlength\fP> field in the extended header record was included to +make it simpler to step through the records, even if a record contains +an unknown format (to a particular +.IR pax ) +with complex interactions of special characters. It also provides a +minor integrity checkpoint within the records to aid a program +attempting to recover files from a damaged archive. +.P +There are no extended header versions of the +.IR devmajor +and +.IR devminor +fields because the unspecified format +.BR ustar +header field should be sufficient. If they are not, vendor-specific +extended keywords (such as +.IR VENDOR.devmajor ) +should be used. +.P +Device and +.IR i -number +labeling of files was not adopted from +.IR cpio ; +files are interchanged strictly on a symbolic name basis, as in +.BR ustar . +.P +Just as with the +.BR ustar +format descriptions, the new format makes no special arrangements for +multi-volume archives. Each of the +.IR pax +archive types is assumed to be inside a single POSIX file and splitting +that file over multiple volumes (diskettes, tape cartridges, and so +on), processing their labels, and mounting each in the proper sequence +are considered to be implementation details that cannot be described +portably. +.P +The +.BR pax +format is intended for interchange, not only for backup on a single +(family of) systems. It is not as densely packed as might be possible +for backup: +.IP " *" 4 +It contains information as coded characters that could be coded in +binary. +.IP " *" 4 +It identifies extended records with name fields that could be omitted +in favor of a fixed-field layout. +.IP " *" 4 +It translates names into a portable character set and identifies +locale-related information, both of which are probably unnecessary for +backup. +.P +The requirements on restoring from an archive are slightly different +from the historical wording, allowing for non-monolithic privilege to +bring forward as much as possible. In particular, attributes such as +``high performance file'' might be broadly but not universally granted +while set-user-ID or +\fIchown\fR() +might be much more restricted. There is no implication in POSIX.1\(hy2008 that +the security information be honored after it is restored to the file +hierarchy, in spite of what might be improperly inferred by the silence +on that topic. That is a topic for another standard. +.P +Links are recorded in the fashion described here because a link can be +to any file type. It is desirable in general to be able to restore part +of an archive selectively and restore all of those files completely. If +the data is not associated with each link, it is not possible to do +this. However, the data associated with a file can be large, and when +selective restoration is not needed, this can be a significant burden. +The archive is structured so that files that have no associated data +can always be restored by the name of any link name of any link, and +the user may choose whether data is recorded with each instance of a +file that contains data. The format permits mixing of both types of +links in a single archive; this can be done for special needs, and +.IR pax +is expected to interpret such archives on input properly, despite the +fact that there is no +.IR pax +option that would force this mixed case on output. (When +.BR \(mio +.BR linkdata +is used, the output must contain the duplicate data, but the +implementation is free to include it or omit it when +.BR \(mio +.BR linkdata +is not used.) +.P +The time values are included as extended header records for those +implementations needing more than the eleven octal digits allowed by +the +.BR ustar +format. Portable file timestamps cannot be negative. If +.IR pax +encounters a file with a negative timestamp in +.BR copy +or +.BR write +mode, it can reject the file, substitute a non-negative timestamp, or +generate a non-portable timestamp with a leading +.BR '\(mi' . +Even though some implementations can support finer file-time +granularities than seconds, the normative text requires support only +for seconds since the Epoch because the ISO\ POSIX\(hy1 standard states them that way. The +.BR ustar +format includes only +.IR mtime ; +the new format adds +.IR atime +and +.IR ctime +for symmetry. The +.IR atime +access time restored to the file system will be affected by the +.BR \(mip +.BR a +and +.BR \(mip +.BR e +options. The +.IR ctime +creation time (actually +.IR inode +modification time) is described with appropriate privileges so that +it can be ignored when writing to the file system. POSIX does not +provide a portable means to change file creation time. Nothing is +intended to prevent a non-portable implementation of +.IR pax +from restoring the value. +.P +The +.IR gid , +.IR size , +and +.IR uid +extended header records were included to allow expansion beyond the +sizes specified in the regular +.IR tar +header. New file system architectures are emerging that will exhaust +the 12-digit size field. There are probably not many systems requiring +more than 8 digits for user and group IDs, but the extended header +values were included for completeness, allowing overrides for all of +the decimal values in the +.IR tar +header. +.P +The standard developers intended to describe the effective results of +.IR pax +with regard to file ownerships and permissions; implementations are not +restricted in timing or sequencing the restoration of such, provided +the results are as specified. +.P +Much of the text describing the extended headers refers to use in ``\c +.BR write +or +.BR copy +modes''. The +.BR copy +mode references are due to the normative text: ``The effect of the +copy shall be as if the copied files were written to an archive file +and then subsequently extracted .\|.\|.''. There is certainly no way to +test whether +.IR pax +is actually generating the extended headers in +.BR copy +mode, but the effects must be as if it had. +.SS "pax Archive Character Set Encoding/Decoding" +.P +There is a need to exchange archives of files between systems of +different native codesets. Filenames, group names, and user names must +be preserved to the fullest extent possible when an archive is read on +the receiving platform. Translation of the contents of files is not +within the scope of the +.IR pax +utility. +.P +There will also be the need to represent characters that are not +available on the receiving platform. These unsupported characters +cannot be automatically folded to the local set of characters due to +the chance of collisions. This could result in overwriting previous +extracted files from the archive or pre-existing files on the system. +.P +For these reasons, the codeset used to represent characters within the +extended header records of the +.IR pax +archive must be sufficiently rich to handle all commonly used character +sets. The fields requiring translation include, at a minimum, +filenames, user names, group names, and link pathnames. Implementations +may wish to have localized extended keywords that use non-portable +characters. +.P +The standard developers considered the following options: +.IP " *" 4 +The archive creator specifies the well-defined name of the source +codeset. The receiver must then recognize the codeset name and perform +the appropriate translations to the destination codeset. +.IP " *" 4 +The archive creator includes within the archive the character mapping +table for the source codeset used to encode extended header records. +The receiver must then read the character mapping table and perform the +appropriate translations to the destination codeset. +.IP " *" 4 +The archive creator translates the extended header records in the +source codeset into a canonical form. The receiver must then perform +the appropriate translations to the destination codeset. +.P +The approach that incorporates the name of the source codeset poses the +problem of codeset name registration, and makes the archive useless to +.IR pax +archive decoders that do not recognize that codeset. +.P +Because parts of an archive may be corrupted, the standard developers +felt that including the character map of the source codeset was too +fragile. The loss of this one key component could result in making the +entire archive useless. (The difference between this and the global +extended header decision was that the latter has a +workaround\(emduplicating extended header records on unreliable +media\(embut this would be too burdensome for large character set +maps.) +.P +Both of the above approaches also put an undue burden on the +.IR pax +archive receiver to handle the cross-product of all source and +destination codesets. +.P +To simplify the translation from the source codeset to the canonical +form and from the canonical form to the destination codeset, the +standard developers decided that the internal representation should be +a stateless encoding. A stateless encoding is one where each codepoint +has the same meaning, without regard to the decoder being in a specific +state. An example of a stateful encoding would be the Japanese +Shift-JIS; an example of a stateless encoding would be the ISO/IEC\ 646:\|1991 standard +(equivalent to 7-bit ASCII). +.P +For these reasons, the standard developers decided to adopt a canonical +format for the representation of file information strings. The obvious, +well-endorsed candidate is the ISO/IEC\ 10646\(hy1:\|2000 standard (based in part on Unicode), which +can be used to represent the characters of virtually all standardized +character sets. The standard developers initially agreed upon using +UCS2 (16-bit Unicode) as the internal representation. This repertoire +of characters provides a sufficiently rich set to represent all +commonly-used codesets. +.P +However, the standard developers found that the 16-bit Unicode +representation had some problems. It forced the issue of standardizing +byte ordering. The 2-byte length of each character made the extended +header records twice as long for the case of strings coded entirely +from historical 7-bit ASCII. For these reasons, the standard developers +chose the UTF\(hy8 defined in the ISO/IEC\ 10646\(hy1:\|2000 standard. This multi-byte representation +encodes UCS2 or UCS4 characters reliably and deterministically, +eliminating the need for a canonical byte ordering. In addition, NUL +octets and other characters possibly confusing to POSIX file systems do +not appear, except to represent themselves. It was realized that +certain national codesets take up more space after the encoding, due to +their placement within the UCS range; it was felt that the usefulness +of the encoding of the names outweighs the disadvantage of size +increase for file, user, and group names. +.P +The encoding of UTF\(hy8 is as follows: +.sp +.RS 4 +.nf +\fB +UCS4 Hex Encoding UTF-8 Binary Encoding +.P +00000000-0000007F 0xxxxxxx +00000080-000007FF 110xxxxx 10xxxxxx +00000800-0000FFFF 1110xxxx 10xxxxxx 10xxxxxx +00010000-001FFFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx +00200000-03FFFFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +04000000-7FFFFFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +.fi \fR +.P +.RE +.P +where each +.BR 'x' +represents a bit value from the character being translated. +.SS "ustar Interchange Format" +.P +The description of the +.BR ustar +format reflects numerous enhancements over pre-1988 versions of the +historical +.IR tar +utility. The goal of these changes was not only to provide the +functional enhancements desired, but also to retain compatibility +between new and old versions. This compatibility has been retained. +Archives written using the old archive format are compatible with the +new format. +.P +Implementors should be aware that the previous file format did not +include a mechanism to archive directory type files. For this reason, +the convention of using a filename ending with + +was adopted to specify a directory on the archive. +.P +The total size of the +.IR name +and +.IR prefix +fields have been set to meet the minimum requirements for +{PATH_MAX}. +If a pathname will fit within the +.IR name +field, it is recommended that the pathname be stored there without the +use of the +.IR prefix +field. Although the name field is known to be too small to contain +{PATH_MAX} +characters, the value was not changed in this version of the archive +file format to retain backwards-compatibility, and instead the prefix +was introduced. Also, because of the earlier version of the format, +there is no way to remove the restriction on the +.IR linkname +field being limited in size to just that of the +.IR name +field. +.P +The +.IR size +field is required to be meaningful in all implementation extensions, +although it could be zero. This is required so that the data blocks can +always be properly counted. +.P +It is suggested that if device special files need to be represented +that cannot be represented in the standard format, that one of the +extension types (\c +.BR A \(hy\c +.BR Z ) +be used, and that the additional information for the special file be +represented as data and be reflected in the +.IR size +field. +.P +Attempting to restore a special file type, where it is converted to +ordinary data and conflicts with an existing filename, need not be +specially detected by the utility. If run as an ordinary user, +.IR pax +should not be able to overwrite the entries in, for example, +.BR /dev +in any case (whether the file is converted to another type or not). If +run as a privileged user, it should be able to do so, and it would be +considered a bug if it did not. The same is true of ordinary data files +and similarly named special files; it is impossible to anticipate the +needs of the user (who could really intend to overwrite the file), so +the behavior should be predictable (and thus regular) and rely on the +protection system as required. +.P +The value 7 in the +.IR typeflag +field is intended to define how contiguous files can be stored in a +.BR ustar +archive. POSIX.1\(hy2008 does not require the contiguous file extension, but does +define a standard way of archiving such files so that all conforming +systems can interpret these file types in a meaningful and consistent +manner. On a system that does not support extended file types, the +.IR pax +utility should do the best it can with the file and go on to the next. +.P +The file protection modes are those conventionally used by the +.IR ls +utility. This is extended beyond the usage in the ISO\ POSIX\(hy2 standard to support the +``shared text'' or ``sticky'' bit. It is intended that the conformance +document should not document anything beyond the existence of and +support of such a mode. Further extensions are expected to these bits, +particularly with overloading the set-user-ID and set-group-ID flags. +.SS "cpio Interchange Format" +.P +The reference to appropriate privileges in the +.BR cpio +format refers to an error on standard output; the +.BR ustar +format does not make comparable statements. +.P +The model for this format was the historical System V +.IR cpio \c +.BR \(mic +data interchange format. This model documents the portable version of +the +.BR cpio +format and not the binary version. It has the flexibility to transfer +data of any type described within POSIX.1\(hy2008, yet is extensible to transfer +data types specific to extensions beyond POSIX.1\(hy2008 (for example, contiguous +files). Because it describes existing practice, there is no question of +maintaining upwards-compatibility. +.SS "cpio Header" +.P +There has been some concern that the size of the +.IR c_ino +field of the header is too small to handle those systems that have very +large +.IR inode +numbers. However, the +.IR c_ino +field in the header is used strictly as a hard-link resolution +mechanism for archives. It is not necessarily the same value as the +.IR inode +number of the file in the location from which that file is extracted. +.P +The name +.IR c_magic +is based on historical usage. +.SS "cpio Filename" +.P +For most historical implementations of the +.IR cpio +utility, +{PATH_MAX} +octets can be used to describe the pathname without the addition of +any other header fields (the NUL character would be included in this +count). +{PATH_MAX} +is the minimum value for pathname size, documented as 256 bytes. +However, an implementation may use +.IR c_namesize +to determine the exact length of the pathname. With the current +description of the +.IR +header, this pathname size can be as large as a number that is +described in six octal digits. +.P +Two values are documented under the +.IR c_mode +field values to provide for extensibility for known file types: +.IP "\fB0110\ 000\fP" 10 +Reserved for contiguous files. The implementation may treat the rest of +the information for this archive like a regular file. If this file type +is undefined, the implementation may create the file as a regular +file. +.P +This provides for extensibility of the +.BR cpio +format while allowing for the ability to read old archives. Files of an +unknown type may be read as ``regular files'' on some implementations. +On a system that does not support extended file types, the +.IR pax +utility should do the best it can with the file and go on to the next. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIcp\fR\^", +.IR "\fIed\fR\^", +.IR "\fIgetopts\fR\^", +.IR "\fIls\fR\^", +.IR "\fIprintf\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.169" ", " "File Mode Bits", +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchown\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fIutime\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/pr.1p b/man-pages-posix-2013-a/man1p/pr.1p new file mode 100644 index 0000000..7280c6d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/pr.1p @@ -0,0 +1,569 @@ +'\" et +.TH PR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pr +\(em print files +.SH SYNOPSIS +.LP +.nf +pr \fB[\fR+\fIpage\fB] [\fR\(mi\fIcolumn\fB] [\fR\(miadFmrt\fB] [\fR\(mie\fB[\fIchar\fB][\fIgap\fB]] [\fR\(mih \fIheader\fB] [\fR\(mii\fB[\fIchar\fB][\fIgap\fB]] + [\fR\(mil \fIlines\fB] [\fR\(min\fB[\fIchar\fB][\fIwidth\fB]] [\fR\(mio \fIoffset\fB] [\fR\(mis\fB[\fIchar\fB]] [\fR\(miw \fIwidth\fB] [\fR\(mifp\fB] + [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR pr +utility is a printing and pagination filter. If multiple input files +are specified, each shall be read, formatted, and written to standard +output. By default, the input shall be separated into 66-line pages, +each with: +.IP " *" 4 +A 5-line header that includes the page number, date, time, and +the pathname of the file +.IP " *" 4 +A 5-line trailer consisting of blank lines +.P +If standard output is associated with a terminal, diagnostic messages +shall be deferred until the +.IR pr +utility has completed processing. +.P +When options specifying multi-column output are specified, output text +columns shall be of equal width; input lines that do not fit into a +text column shall be truncated. By default, text columns shall be +separated with at least one +. +.SH OPTIONS +The +.IR pr +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that: the +.IR page +option has a +.BR '\(pl' +delimiter; +.IR page +and +.IR column +can be multi-digit numbers; some of the option-arguments are optional; +and some of the option-arguments cannot be specified as separate +arguments from the preceding option letter. In particular, the +.BR \(mis +option does not allow the option letter to be separated from its +argument, and the options +.BR \(mie , +.BR \(mii , +and +.BR \(min +require that both arguments, if present, not be separated from the +option letter. +.P +The following options shall be supported. In the following option +descriptions, +.IR column , +.IR lines , +.IR offset , +.IR page , +and +.IR width +are positive decimal integers; +.IR gap +is a non-negative decimal integer. +.IP "\fB+\fIpage\fR" 10 +Begin output at page number +.IR page +of the formatted input. +.IP "\fB\(mi\fIcolumn\fR" 10 +Produce multi-column output that is arranged in +.IR column +columns (the default shall be 1) and is written down each column in the +order in which the text is received from the input file. This option +should not be used with +.BR \(mim . +The options +.BR \(mie +and +.BR \(mii +shall be assumed for multiple text-column output. Whether or not text +columns are produced with identical vertical lengths is unspecified, +but a text column shall never exceed the length of the page (see the +.BR \(mil +option). When used with +.BR \(mit , +use the minimum number of lines to write the output. +.IP "\fB\(mia\fP" 10 +Modify the effect of the +.BR \(mi \c +.IR column +option so that the columns are filled across the page in a round-robin +order (for example, when +.IR column +is 2, the first input line heads column 1, the second heads column 2, +the third is the second line in column 1, and so on). +.IP "\fB\(mid\fP" 10 +Produce output that is double-spaced; append an extra + +following every + +found in the input. +.IP "\fB\(mie[\fIchar\fB][\fIgap\fB]\fR" 10 +.br +Expand each input + +to the next greater column position specified by the formula +.IR n *\c +.IR gap +1, +where +.IR n +is an integer > 0. If +.IR gap +is zero or is omitted, it shall default to 8. All + +characters in the input shall be expanded into the appropriate number of + +characters. If any non-digit character, +.IR char , +is specified, it shall be used as the input +. +If the first character of the +.BR \(mie +option-argument is a digit, the entire option-argument shall be assumed +to be +.IR gap . +.IP "\fB\(mif\fP" 10 +Use a + +for new pages, instead of the default behavior that uses a sequence of + +characters. Pause before beginning the first page if the standard output +is associated with a terminal. +.IP "\fB\(miF\fP" 10 +Use a + +for new pages, instead of the default behavior that uses a sequence of + +characters. +.IP "\fB\(mih\ \fIheader\fR" 10 +Use the string +.IR header +to replace the contents of the +.IR file +operand in the page header. +.IP "\fB\(mii[\fIchar\fB][\fIgap\fB]\fR" 10 +In output, replace + +characters with + +characters wherever one or more adjacent + +characters reach column positions +.IR gap +1, +2* +.IR gap +1, +3* +.IR gap +1, +and so on. If +.IR gap +is zero or is omitted, default tab settings at every eighth column +position shall be assumed. If any non-digit character, +.IR char , +is specified, it shall be used as the output +. +If the first character of the +.BR \(mii +option-argument is a digit, the entire option-argument shall be assumed +to be +.IR gap . +.IP "\fB\(mil\ \fIlines\fR" 10 +Override the 66-line default and reset the page length to +.IR lines . +If +.IR lines +is not greater than the sum of both the header and trailer depths (in +lines), the +.IR pr +utility shall suppress both the header and trailer, as if the +.BR \(mit +option were in effect. +.IP "\fB\(mim\fP" 10 +Merge files. Standard output shall be formatted so the +.IR pr +utility writes one line from each file specified by a +.IR file +operand, side by side into text columns of equal fixed widths, in terms +of the number of column positions. Implementations shall support +merging of at least nine +.IR file +operands. +.IP "\fB\(min[\fIchar\fB][\fIwidth\fB]\fR" 10 +.br +Provide +.IR width -digit +line numbering (default for +.IR width +shall be 5). The number shall occupy the first +.IR width +column positions of each text column of default output or each line of +.BR \(mim +output. If +.IR char +(any non-digit character) is given, it shall be appended to the line +number to separate it from whatever follows (default for +.IR char +is a +). +.IP "\fB\(mio\ \fIoffset\fR" 10 +Each line of output shall be preceded by offset + +characters. If the +.BR \(mio +option is not specified, the default offset shall be zero. The space +taken is in addition to the output line width (see the +.BR \(miw +option below). +.IP "\fB\(mip\fP" 10 +Pause before beginning each page if the standard output is directed to +a terminal (\c +.IR pr +shall write an + +to standard error and wait for a + +to be read on +.BR /dev/tty ). +.IP "\fB\(mir\fP" 10 +Write no diagnostic reports on failure to open files. +.IP "\fB\(mis[\fIchar\fB]\fR" 10 +Separate text columns by the single character +.IR char +instead of by the appropriate number of + +characters (default for +.IR char +shall be +). +.IP "\fB\(mit\fP" 10 +Write neither the five-line identifying header nor the five-line +trailer usually supplied for each page. Quit writing after the last +line of each file without spacing to the end of the page. +.IP "\fB\(miw\ \fIwidth\fR" 10 +Set the width of the line to +.IR width +column positions for multiple text-column output only. If the +.BR \(miw +option is not specified and the +.BR \(mis +option is not specified, the default width shall be 72. If the +.BR \(miw +option is not specified and the +.BR \(mis +option is specified, the default width shall be 512. +.RS 10 +.P +For single column output, input lines shall not be truncated. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be written. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.P +The file +.BR /dev/tty +shall be used to read responses required by the +.BR \(mip +option. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pr : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and which +characters are defined as printable (character class +.BR print ). +Non-printable characters are still written to standard output, but are +not counted for the purpose for column-width and line-length +calculations. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format of the date and time for use in writing header +lines. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings written +in header lines. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +If +.IR pr +receives an interrupt while writing to a terminal, it shall flush all +accumulated error messages to the screen before terminating. +.SH STDOUT +The +.IR pr +utility output shall be a paginated version of the original file (or +files). This pagination shall be accomplished using either + +characters or a sequence of + +characters, as controlled by the +.BR \(miF +or +.BR \(mif +option. Page headers shall be generated unless the +.BR \(mit +option is specified. The page headers shall be of the form: +.sp +.RS 4 +.nf +\fB +"\en\en%s %s Page %d\en\en\en", <\fIoutput of date\fP>, <\fIfile\fR>, <\fIpage number\fR> +.fi \fR +.P +.RE +.P +In the POSIX locale, the <\fIoutput\ of\ date\fR> field, representing +the date and time of last modification of the input file (or the +current date and time if the input file is standard input), shall be +equivalent to the output of the following command as it would appear if +executed at the given time: +.sp +.RS 4 +.nf +\fB +date "+%b %e %H:%M %Y" +.fi \fR +.P +.RE +.P +without the trailing +, +if the page being written is from standard input. If the page being +written is not from standard input, in the POSIX locale, the same +format shall be used, but the time used shall be the modification time +of the file corresponding to +.IR file +instead of the current time. When the +.IR LC_TIME +locale category is not set to the POSIX locale, a different format and +order of presentation of this field may be used. +.P +If the standard input is used instead of a +.IR file +operand, the <\fIfile\fP> field shall be replaced by a null string. +.P +If the +.BR \(mih +option is specified, the <\fIfile\fP> field shall be replaced by the +.IR header +argument. +.SH STDERR +The standard error shall be used for diagnostic messages and +for alerting the terminal when +.BR \(mip +is specified. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +A conforming application must protect its first operand, if it starts +with a +, +by preceding it with the +.BR \(dq\(mi\|\(mi\(dq +argument that denotes the end of the options. For example, +.IR pr \(pl\c +.IR x +could be interpreted as an invalid page number or a +.IR file +operand. +.SH EXAMPLES +.IP " 1." 4 +Print a numbered list of all files in the current directory: +.RS 4 +.sp +.RS 4 +.nf +\fB +ls \(mia | pr \(min \(mih "Files in $(pwd)." +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Print +.BR file1 +and +.BR file2 +as a double-spaced, three-column listing headed by ``file list'': +.RS 4 +.sp +.RS 4 +.nf +\fB +pr \(mi3d \(mih "file list" file1 file2 +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Write +.BR file1 +on +.BR file2 , +expanding tabs to columns 10, 19, 28, .\|.\|.: +.RS 4 +.sp +.RS 4 +.nf +\fB +pr \(mie9 \(mit file2 +.fi \fR +.P +.RE +.RE +.SH RATIONALE +This utility is one of those that does not follow the Utility Syntax +Guidelines because of its historical origins. The standard developers +could have added new options that obeyed the guidelines (and marked the +old options obsolescent) or devised an entirely new utility; there are +examples of both actions in this volume of POSIX.1\(hy2008. Because of its widespread use by +historical applications, the standard developers decided to exempt this +version of +.IR pr +from many of the guidelines. +.P +Implementations are required to accept option-arguments to the +.BR \(mih , +.BR \(mil , +.BR \(mio , +and +.BR \(miw +options whether presented as part of the same argument or as a separate +argument to +.IR pr , +as suggested by the Utility Syntax Guidelines. The +.BR \(min +and +.BR \(mis +options, however, are specified as in historical practice because they +are frequently specified without their optional arguments. If a + +were allowed before the option-argument in these cases, a +.IR file +operand could mistakenly be interpreted as an option-argument in +historical applications. +.P +The text about the minimum number of lines in multi-column output was +included to ensure that a best effort is made in balancing the length +of the columns. There are known historical implementations in which, +for example, 60-line files are listed by +.IR pr +\(mi2 as one column of 56 lines and a second of 4. Although this is not +a problem when a full page with headers and trailers is produced, it +would be relatively useless when used with +.BR \(mit . +.P +Historical implementations of the +.IR pr +utility have differed in the action taken for the +.BR \(mif +option. BSD uses it as described here for the +.BR \(miF +option; System V uses it to change trailing + +characters on each page to a + +and, if standard output is a TTY device, sends an + +to standard error and reads a line from +.BR /dev/tty +before the first page. There were strong arguments from both sides of +this issue concerning historical practice and as a result the +.BR \(miF +option was added. XSI-conformant systems support the System V +historical actions for the +.BR \(mif +option. +.P +The <\fIoutput\ of\ date\fP> field in the +.BR \(mil +format is specified only for the POSIX locale. As noted, the format can +be different in other locales. No mechanism for defining this is +present in this volume of POSIX.1\(hy2008, as the appropriate vehicle is a message catalog; +that is, the format should be specified as a ``message''. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexpand\fR\^", +.IR "\fIlp\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/printf.1p b/man-pages-posix-2013-a/man1p/printf.1p new file mode 100644 index 0000000..716fb08 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/printf.1p @@ -0,0 +1,576 @@ +'\" et +.TH PRINTF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +printf +\(em write formatted output +.SH SYNOPSIS +.LP +.nf +printf \fIformat\fB [\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR printf +utility shall write formatted operands to the standard output. The +.IR argument +operands shall be formatted under control of the +.IR format +operand. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIformat\fR" 10 +A string describing the format to use to write the remaining operands. +See the EXTENDED DESCRIPTION section. +.IP "\fIargument\fR" 10 +The strings to be written to standard output, under the control of +.IR format . +See the EXTENDED DESCRIPTION section. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR printf : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for numeric formatting. It shall affect the +format of numbers written using the +.BR e , +.BR E , +.BR f , +.BR g , +and +.BR G +conversion specifier characters (if supported). +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the EXTENDED DESCRIPTION section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The +.IR format +operand shall be used as the +.IR format +string described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +with the following exceptions: +.IP " 1." 4 +A + +in the format string, in any context other than a flag of a conversion +specification, shall be treated as an ordinary character that is copied +to the output. +.IP " 2." 4 +A +.BR ' ' +character in the format string shall be treated as a +.BR ' ' +character, not as a +. +.IP " 3." 4 +In addition to the escape sequences shown in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ), +.BR \(dq\eddd\(dq , +where +.IR ddd +is a one, two, or three-digit octal number, shall be written as a byte +with the numeric value specified by the octal number. +.IP " 4." 4 +The implementation shall not precede or follow output from the +.BR d +or +.BR u +conversion specifiers with + +characters not specified by the +.IR format +operand. +.IP " 5." 4 +The implementation shall not precede output from the +.BR o +conversion specifier with zeros not specified by the +.IR format +operand. +.IP " 6." 4 +The +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers need not be supported. +.IP " 7." 4 +An additional conversion specifier character, +.BR b , +shall be supported as follows. The argument shall be taken to be a +string that may contain +-escape +sequences. The following +-escape +sequences shall be supported: +.RS 4 +.IP -- 4 +The escape sequences listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ), +which shall be converted to the characters they represent +.IP -- 4 +.BR \(dq\e0ddd\(dq , +where +.IR ddd +is a zero, one, two, or three-digit octal number that shall be +converted to a byte with the numeric value specified by the octal +number +.IP -- 4 +.BR '\ec' , +which shall not be written and shall cause +.IR printf +to ignore any remaining characters in the string operand containing it, +any remaining string operands, and any additional characters in the +.IR format +operand +.P +The interpretation of a + +followed by any other sequence of characters is unspecified. +.P +Bytes from the converted string shall be written until the end of the +string or the number of bytes indicated by the precision specification +is reached. If the precision is omitted, it shall be taken to be +infinite, so all bytes up to the end of the converted string shall be +written. +.RE +.IP " 8." 4 +For each conversion specification that consumes an argument, the next +argument operand shall be evaluated and converted to the appropriate +type for the conversion as specified below. +.IP " 9." 4 +The +.IR format +operand shall be reused as often as necessary to satisfy the argument +operands. Any extra +.BR c +or +.BR s +conversion specifiers shall be evaluated as if a null string +argument were supplied; other extra conversion specifications shall be +evaluated as if a zero argument were supplied. If the +.IR format +operand contains no conversion specifications and +.IR argument +operands are present, the results are unspecified. +.IP 10. 4 +If a character sequence in the +.IR format +operand begins with a +.BR '%' +character, but does not form a valid conversion specification, the +behavior is unspecified. +.IP 11. 4 +The argument to the +.BR c +conversion specifier can be a string containing zero or more bytes. If +it contains one or more bytes, the first byte shall be written and any +additional bytes shall be ignored. If the argument is an empty string, +it is unspecified whether nothing is written or a null byte is written. +.P +The +.IR argument +operands shall be treated as strings if the corresponding conversion +specifier is +.BR b , +.BR c , +or +.BR s , +and shall be evaluated as if by the +\fIstrtod\fR() +function if the corresponding conversion specifier is +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G . +Otherwise, they shall be evaluated as unsuffixed C integer constants, +as described by the ISO\ C standard, with the following extensions: +.IP " *" 4 +A leading + +or minus-sign shall be allowed. +.IP " *" 4 +If the leading character is a single-quote or double-quote, the value +shall be the numeric value in the underlying codeset of the character +following the single-quote or double-quote. +.IP " *" 4 +Suffixed integer constants may be allowed. +.P +If an argument operand cannot be completely converted into an internal +value appropriate to the corresponding conversion specification, a +diagnostic message shall be written to standard error and the utility +shall not exit with a zero exit status, but shall continue processing +any remaining operands and shall write the value accumulated at the +time the error was detected to standard output. +.P +It is not considered an error if an argument operand is not completely +used for a +.BR c +or +.BR s +conversion. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The floating-point formatting conversion specifications of +\fIprintf\fR() +are not required because all arithmetic in the shell is integer +arithmetic. The +.IR awk +utility performs floating-point calculations and provides its own +.BR printf +function. The +.IR bc +utility can perform arbitrary-precision floating-point arithmetic, but +does not provide extensive formatting capabilities. (This +.IR printf +utility cannot really be used to format +.IR bc +output; it does not support arbitrary precision.) Implementations are +encouraged to support the floating-point conversions as an extension. +.P +Note that this +.IR printf +utility, like the +\fIprintf\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 on which it is based, makes no special +provision for dealing with multi-byte characters when using the +.BR %c +conversion specification or when a precision is specified in a +.BR %b +or +.BR %s +conversion specification. Applications should be extremely cautious +using either of these features when there are multi-byte characters in +the character set. +.P +No provision is made in this volume of POSIX.1\(hy2008 which allows field widths and precisions +to be specified as +.BR '*' +since the +.BR '*' +can be replaced directly in the +.IR format +operand using shell variable substitution. Implementations can also +provide this feature as an extension if they so choose. +.P +Hexadecimal character constants as defined in the ISO\ C standard are not +recognized in the +.IR format +operand because there is no consistent way to detect the end of the +constant. Octal character constants are limited to, at most, three +octal digits, but hexadecimal character constants are only terminated +by a non-hex-digit character. In the ISO\ C standard, the +.BR \(dq##\(dq +concatenation operator can be used to terminate a constant and follow +it with a hexadecimal character to be written. In the shell, +concatenation occurs before the +.IR printf +utility has a chance to parse the end of the hexadecimal constant. +.P +The +.BR %b +conversion specification is not part of the ISO\ C standard; it has been added +here as a portable way to process +-escapes +expanded in string operands as provided by the +.IR echo +utility. See also the APPLICATION USAGE section of +.IR "\fIecho\fR\^" +for ways to use +.IR printf +as a replacement for all of the traditional versions of the +.IR echo +utility. +.P +If an argument cannot be parsed correctly for the corresponding +conversion specification, the +.IR printf +utility is required to report an error. Thus, overflow and extraneous +characters at the end of an argument being used for a numeric +conversion shall be reported as errors. +.SH EXAMPLES +To alert the user and then print and read a series of prompts: +.sp +.RS 4 +.nf +\fB +printf "\eaPlease fill in the following: \enName: " +read name +printf "Phone number: " +read phone +.fi \fR +.P +.RE +.P +To read out a list of right and wrong answers from a file, calculate +the percentage correctly, and print them out. The numbers are +right-justified and separated by a single +. +The percentage is written to one decimal place of accuracy: +.sp +.RS 4 +.nf +\fB +while read right wrong ; do + percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc) + printf "%2d right\et%2d wrong\et(%s%%)\en" \e + $right $wrong $percent +done < database_file +.fi \fR +.P +.RE +The command: +.sp +.RS 4 +.nf +\fB +printf "%5d%4d\en" 1 21 321 4321 54321 +.fi \fR +.P +.RE +.P +produces: +.sp +.RS 4 +.nf +\fB + 1 21 + 3214321 +54321 0 +.fi \fR +.P +.RE +.P +Note that the +.IR format +operand is used three times to print all of the given strings and that +a +.BR '0' +was supplied by +.IR printf +to satisfy the last +.BR %4d +conversion specification. +.P +The +.IR printf +utility is required to notify the user when conversion errors are +detected while producing numeric output; thus, the following results +would be expected on an implementation with 32-bit twos-complement +integers when +.BR %d +is specified as the +.IR format +operand: +.br +.TS +center tab(@) box; +cB | cB | cB +cB | cB | cB +lf5 | lf5 | lf7. +@Standard +Argument@Output@Diagnostic Output +_ +5a@5@printf: "5a" not completely converted +9999999999@2147483647@printf: "9999999999" arithmetic overflow +\(mi9999999999@\(mi2147483648@printf: "\(mi9999999999" arithmetic overflow +ABC@0@printf: "ABC" expected numeric value +.TE +.P +The diagnostic message format is not specified, but these examples +convey the type of information that should be reported. Note that the +value shown on standard output is what would be expected as the return +value from the +\fIstrtol\fR() +function as defined in the System Interfaces volume of POSIX.1\(hy2008. A similar correspondence exists +between +.BR %u +and +\fIstrtoul\fR() +and +.BR %e , +.BR %f , +and +.BR %g +(if the implementation supports floating-point conversions) and +\fIstrtod\fR(). +.P +In a locale using the ISO/IEC\ 646:\|1991 standard as the underlying codeset, the command: +.sp +.RS 4 +.nf +\fB +printf "%d\en" 3 +3 \(mi3 \e'3 \e"+3 "'\(mi3" +.fi \fR +.P +.RE +.P +produces: +.IP 3 6 +Numeric value of constant 3 +.IP 3 6 +Numeric value of constant 3 +.IP "\(mi3" 6 +Numeric value of constant \(mi3 +.IP 51 6 +Numeric value of the character +.BR '3' +in the ISO/IEC\ 646:\|1991 standard codeset +.IP 43 6 +Numeric value of the character +.BR '\(pl' +in the ISO/IEC\ 646:\|1991 standard codeset +.IP 45 6 +Numeric value of the character +.BR '\(mi' +in the ISO/IEC\ 646:\|1991 standard codeset +.P +Note that in a locale with multi-byte characters, the value of a +character is intended to be the value of the equivalent of the +.BR wchar_t +representation of the character as described in the System Interfaces volume of POSIX.1\(hy2008. +.SH RATIONALE +The +.IR printf +utility was added to provide functionality that has historically been +provided by +.IR echo . +However, due to irreconcilable differences in the various versions of +.IR echo +extant, the version has few special features, leaving those to this new +.IR printf +utility, which is based on one in the Ninth Edition system. +.P +The EXTENDED DESCRIPTION section almost exactly matches the +\fIprintf\fR() +function in the ISO\ C standard, although it is described in terms of the file +format notation in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation". +.P +Earlier versions of this standard specified that arguments for all +conversions other than +.BR b , +.BR c , +and +.BR s +were evaluated in the same way (as C constants, but with stated +exceptions). For implementations supporting the floating-point conversions +it was not clear whether integer conversions need only accept integer +constants and floating-point conversions need only accept floating-point +constants, or whether both types of conversions should accept both +types of constants. Also by not distinguishing between them, the +requirement relating to a leading single-quote or double-quote applied +to floating-point conversions even though this provided no useful +functionality to applications that was not already available through +the integer conversions. The current standard clarifies the situation +by specifying that the arguments for floating-point conversions are +evaluated as if by +\fIstrtod\fR(), +and the arguments for integer conversions are evaluated as C integer +constants, with the special treatment of leading single-quote and +double-quote applying only to integer conversions. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIawk\fR\^", +.IR "\fIbc\fR\^", +.IR "\fIecho\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/prs.1p b/man-pages-posix-2013-a/man1p/prs.1p new file mode 100644 index 0000000..aa268a6 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/prs.1p @@ -0,0 +1,445 @@ +'\" et +.TH PRS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +prs +\(em print an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +prs \fB[\fR\(mia\fB] [\fR\(mid \fIdataspec\fB] [\fR\(mir\fB[\fISID\fB]]\fI file\fR... +.P +prs \fB[\fR\(mie|\(mil\fB]\fR \(mic \fIcutoff \fB[\fR\(mid \fIdataspec\fB]\fI file\fR... +.P +prs \fB[\fR\(mie|\(mil\fB]\fR \(mir\fB[\fISID\fB] [\fR\(mid \fIdataspec\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR prs +utility shall write to standard output parts or all of an SCCS file in +a user-supplied format. +.SH OPTIONS +The +.IR prs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the +.BR \(mir +option has an optional option-argument. This optional option-argument +cannot be presented as a separate argument. The following options +shall be supported: +.IP "\fB\(mid\ \fIdataspec\fR" 10 +Specify the output data specification. The +.IR dataspec +shall be a string consisting of SCCS file +.IR data +.IR keywords +(see +.IR "Data Keywords") +interspersed with optional user-supplied text. +.IP "\fB\(mir[\fISID\fB]\fR" 10 +Specify the SCCS identification string (SID) of a delta for which +information is desired. If no +.IR SID +option-argument is specified, the SID of the most recently created +delta shall be assumed. +.IP "\fB\(mie\fP" 10 +Request information for all deltas created earlier than and including +the delta designated via the +.BR \(mir +option or the date-time given by the +.BR \(mic +option. +.IP "\fB\(mil\fP" 10 +Request information for all deltas created later than and including the +delta designated via the +.BR \(mir +option or the date-time given by the +.BR \(mic +option. +.IP "\fB\(mic\ \fIcutoff\fR" 10 +Indicate the +.IR cutoff +date-time, in the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIYY\fB[\fIMM\fB[\fIDD\fB[\fIHH\fB[\fIMM\fB[\fISS\fB]]]]]\fR +.fi \fR +.P +.RE +.P +For the +.IR YY +component, values in the range [69,99] shall refer to years 1969 to +1999 inclusive, and values in the range [00,68] shall refer to years +2000 to 2068 inclusive. +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply to +all commands accepting a 2-digit year as input.) +.P +.P +No changes (deltas) to the SCCS file that were created after the +specified +.IR cutoff +date-time shall be included in the output. Units omitted from the +date-time default to their maximum possible values; for example, +.BR \(mic\07502 +is equivalent to +.BR \(mic\0750228235959 . +.RE +.IP "\fB\(mia\fP" 10 +Request writing of information for both removed\(emthat is, +.IR delta +.IR type =\c +.IR R +(see +.IR "\fIrmdel\fR\^")\(em\c +and existing\(emthat is, +.IR delta +.IR type =\c +.IR D ,\(em\c +deltas. If the +.BR \(mia +option is not specified, information for existing deltas only shall be +provided. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR prs +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS +files and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +Any SCCS files displayed are files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR prs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be a text file whose format is dependent on +the data keywords specified with the +.BR \(mid +option. +.SS "Data Keywords" +.P +Data keywords specify which parts of an SCCS file shall be retrieved +and output. All parts of an SCCS file have an associated data +keyword. A data keyword may appear in a +.IR dataspec +multiple times. +.P +The information written by +.IR prs +shall consist of: +.IP " 1." 4 +The user-supplied text +.IP " 2." 4 +Appropriate values (extracted from the SCCS file) substituted for the +recognized data keywords in the order of appearance in the +.IR dataspec +.P +The format of a data keyword value shall either be simple (\c +.BR 'S' ), +in which keyword substitution is direct, or multi-line (\c +.BR 'M' ). +.P +User-supplied text shall be any text other than recognized data +keywords. A + +shall be specified by +.BR '\et' +and + +by +.BR '\en' . +When the +.BR \(mir +option is not specified, the default +.IR dataspec +shall be: +.sp +.RS 4 +.nf +\fB +:PN::\en\en +.fi \fR +.P +.RE +.P +and the following +.IR dataspec +shall be used for each selected delta: +.sp +.RS 4 +.nf +\fB +:Dt:\et:DL:\enMRs:\en:MR:COMMENTS:\en:C: +.fi \fR +.P +.RE +.TS +center box tab(!); +cB s s s s +cB | cB | cB | cB | cB +lB | l | c | lB | c. +SCCS File Data Keywords +_ +Keyword!Data Item!File Section!Value!Format +_ +:Dt:!Delta information!Delta Table!\fRSee below*\fP!S +:DL:!Delta line statistics!"!:Li:/:Ld:/:Lu:!S +:Li:!Lines inserted by Delta!"!\fInnnnn\fR***!S +:Ld:!Lines deleted by Delta!"!\fInnnnn\fR***!S +:Lu:!Lines unchanged by Delta!"!\fInnnnn\fR***!S +:DT:!Delta type!"!D or R!S +:I:!SCCS ID string (SID)!"!\fRSee below**\fP!S +:R:!Release number!"!\fInnnn\fR!S +:L:!Level number!"!\fInnnn\fR!S +:B:!Branch number!"!\fInnnn\fR!S +:S:!Sequence number!"!\fInnnn\fR!S +:D:!Date delta created!"!:Dy:/:Dm:/:Dd:!S +:Dy:!Year delta created!"!\fInn\fR!S +:Dm:!Month delta created!"!\fInn\fR!S +:Dd:!Day delta created!"!\fInn\fR!S +:T:!Time delta created!"!:Th:::Tm:::Ts:!S +:Th:!Hour delta created!"!\fInn\fR!S +:Tm:!Minutes delta created!"!\fInn\fR!S +:Ts:!Seconds delta created!"!\fInn\fR!S +:P:!Programmer who created Delta!"!\fIlogname\fR!S +:DS:!Delta sequence number!"!\fInnnn\fR!S +:DP:!Predecessor Delta sequence!"!\fInnnn\fR!S +!number +:DI:!Sequence number of deltas!"!:Dn:/:Dx:/:Dg:!S +!included, excluded, or ignored +:Dn:!Deltas included (sequence #)!"!:DS: :DS: .\|.\|.!S +:Dx:!Deltas excluded (sequence #)!"!:DS: :DS: .\|.\|.!S +:Dg:!Deltas ignored (sequence #)!"!:DS: :DS: .\|.\|.!S +:MR:!MR numbers for delta!"!\fItext\fR!M +:C:!Comments for delta!"!\fItext\fR!M +:UN:!User names!User Names!\fItext\fR!M +:FL:!Flag list!Flags!\fItext\fP!M +:Y:!Module type flag!"!\fItext\fR!S +:MF:!MR validation flag!"!yes \fRor\fP no!S +:MP:!MR validation program name!"!\fItext\fR!S +:KF:!Keyword error, warning flag!"!yes \fRor\fP no!S +:KV:!Keyword validation string!"!\fItext\fR!S +:BF:!Branch flag!"!yes \fRor\fP no!S +:J:!Joint edit flag!"!yes \fRor\fP no!S +:LK:!Locked releases!"!:R: .\|.\|.!S +:Q:!User-defined keyword!"!\fItext\fR!S +:M:!Module name!"!\fItext\fR!S +:FB:!Floor boundary!"!:R:!S +:CB:!Ceiling boundary!"!:R:!S +:Ds:!Default SID!"!:I:!S +:ND:!Null delta flag!"!yes \fRor\fP no!S +:FD:!File descriptive text!Comments!\fItext\fR!M +:BD:!Body!Body!\fItext\fR!M +:GB:!Gotten body!"!\fItext\fR!M +:W:!A form of \fIwhat\fP string!N/A!:Z::M:\et:I:!S +:A:!A form of \fIwhat\fP string!N/A!:Z::Y: :M: :I::Z:!S +:Z:!\fIwhat\fP string delimiter!N/A!\fR@(#)\fR!S +:F:!SCCS filename!N/A!\fItext\fR!S +:PN:!SCCS file pathname!N/A!\fItext\fR!S +.TE +.IP * 6 +.BR :Dt: =\c +.BR ":DT: :I: :D: :T: :P: :DS: :DP:" +.IP ** 6 +.BR ":R:.:L:.:B:.:S:" +if the delta is a branch delta (\c +.BR :BF: =\|=\c +.BR yes ) +.br +.BR ":R:.:L:" +if the delta is not a branch delta (\c +.BR :BF: =\|=\c +.BR no ) +.IP *** 6 +The line statistics are capped at 99\|999. For example, if 100\|000 +lines were unchanged in a certain revision, +.BR :Lu: +shall produce the value 99\|999. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +The following example: +.RS 4 +.sp +.RS 4 +.nf +\fB +prs \(mid "User Names for :F: are:\en:UN:" s.file +.fi \fR +.P +.RE +.P +might write to standard output: +.sp +.RS 4 +.nf +\fB +User Names for s.file are: +xyz +131 +abc +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following example: +.RS 4 +.sp +.RS 4 +.nf +\fB +prs \(mid "Delta for pgm :M:: :I: \(mi :D: By :P:" \(mir s.file +.fi \fR +.P +.RE +.P +might write to standard output: +.sp +.RS 4 +.nf +\fB +Delta for pgm main.c: 3.7 \(mi 77/12/01 By cas +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +As a special case: +.RS 4 +.sp +.RS 4 +.nf +\fB +prs s.file +.fi \fR +.P +.RE +.P +might write to standard output: +.sp +.RS 4 +.nf +\fB +s.file: +<\fIblank line\fP> +D 1.1 77/12/01 00:00:00 cas 1 000000/00000/00000 +MRs: +bl78\(mi12345 +bl79\(mi54321 +COMMENTS: +this is the comment line for s.file initial delta +<\fIblank line\fP> +.fi \fR +.P +.RE +.P +for each delta table entry of the +.BR D +type. The only option allowed to be used with this special case is the +.BR \(mia +option. +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ps.1p b/man-pages-posix-2013-a/man1p/ps.1p new file mode 100644 index 0000000..05757a2 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ps.1p @@ -0,0 +1,671 @@ +'\" et +.TH PS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ps +\(em report process status +.SH SYNOPSIS +.LP +.nf +ps \fB[\fR\(miaA\fB] \*![\fR\(midefl\fB] [\fR\(mig \fIgrouplist\fB]\*? [\fR\(miG \fIgrouplist\fB] + \*![\fR\(min \fInamelist\fB]\*? [\fR\(mio \fIformat\fB]\fR... \fB[\fR\(mip \fIproclist\fB] [\fR\(mit \fItermlist\fB] + \*![\fR\(miu \fIuserlist\fB]\*? [\fR\(miU \fIuserlist\fB] +.fi +.SH DESCRIPTION +The +.IR ps +utility shall write information about processes, subject to having +appropriate privileges to obtain information about those processes. +.P +By default, +.IR ps +shall select all processes with the same effective user ID as the +current user and the same controlling terminal as the invoker. +.SH OPTIONS +The +.IR ps +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Write information for all processes associated with terminals. +Implementations may omit session leaders from this list. +.IP "\fB\(miA\fP" 10 +Write information for all processes. +.IP "\fB\(mid\fP" 10 +Write information for all processes, except session leaders. +.IP "\fB\(mie\fP" 10 +Write information for all processes. +(Equivalent to +.BR \(miA .) +.IP "\fB\(mif\fP" 10 +Generate a +.BR full +listing. (See the STDOUT section for the contents of a +.BR full +listing.) +.IP "\fB\(mig\ \fIgrouplist\fR" 10 +Write information for processes whose session leaders are given in +.IR grouplist . +The application shall ensure that the +.IR grouplist +is a single argument in the form of a + +or +-separated +list. +.IP "\fB\(miG\ \fIgrouplist\fR" 10 +Write information for processes whose real group ID numbers are given +in +.IR grouplist . +The application shall ensure that the +.IR grouplist +is a single argument in the form of a + +or +-separated +list. +.IP "\fB\(mil\fP" 10 +Generate a +.BR long +listing. (See STDOUT for the contents of a +.BR long +listing.) +.IP "\fB\(min\ \fInamelist\fR" 10 +Specify the name of an alternative system +.IR namelist +file in place of the default. The name of the default file and the +format of a +.IR namelist +file are unspecified. +.IP "\fB\(mio\ \fIformat\fR" 10 +Write information according to the format specification given in +.IR format . +This is fully described in the STDOUT section. Multiple +.BR \(mio +options can be specified; the format specification shall be interpreted +as the +-separated +concatenation of all the +.IR format +option-arguments. +.IP "\fB\(mip\ \fIproclist\fR" 10 +Write information for processes whose process ID numbers are given in +.IR proclist . +The application shall ensure that the +.IR proclist +is a single argument in the form of a + +or +-separated +list. +.IP "\fB\(mit\ \fItermlist\fR" 10 +Write information for processes associated with terminals given in +.IR termlist . +The application shall ensure that the +.IR termlist +is a single argument in the form of a + +or +-separated +list. Terminal identifiers shall be given in an implementation-defined +format. +On XSI-conformant systems, they shall be given in one of two forms: +the device's filename (for example, +.BR tty04 ) +or, if the device's filename starts with +.BR tty , +just the identifier following the characters +.BR tty +(for example, +.BR \(dq04\(dq ). +.IP "\fB\(miu\ \fIuserlist\fR" 10 +Write information for processes whose user ID numbers or login names +are given in +.IR userlist . +The application shall ensure that the +.IR userlist +is a single argument in the form of a + +or +-separated +list. In the listing, the numerical user ID shall be written unless the +.BR \(mif +option is used, in which case the login name shall be written. +.IP "\fB\(miU\ \fIuserlist\fR" 10 +Write information for processes whose real user ID numbers or login +names are given in +.IR userlist . +The application shall ensure that the +.IR userlist +is a single argument in the form of a + +or +-separated +list. +.P +With the exception of +.BR \(mif , +.BR \(mil , +.BR \(min +.IR namelist , +and +.BR \(mio +.IR format , +all of the options shown are used to select processes. If any are +specified, the default list shall be ignored and +.IR ps +shall select the processes represented by the inclusive OR of +all the selection-criteria options. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ps : +.IP "\fICOLUMNS\fP" 10 +Override the system-selected horizontal display line size, used to +determine the number of text columns to display. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of the date and time strings +displayed. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings +displayed. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mio +option is not specified, the standard output format is unspecified. +.br +.P +On XSI-conformant systems, the output format shall be as follows. +The column headings and descriptions of the columns in a +.IR ps +listing are given below. The precise meanings of these fields are +implementation-defined. The letters +.BR 'f' +and +.BR 'l' +(below) indicate the option (\c +.BR full +or +.BR long ) +that shall cause the corresponding heading to appear; +.BR all +means that the heading always appears. Note that these two options +determine only what information is provided for a process; they do not +determine which processes are listed. +.TS +tab(@); +lB l lw(11c). +F@(l)@T{ +Flags (octal and additive) associated with the process. +T} +S@(l)@The state of the process. +UID@(f,l)@T{ +The user ID number of the process owner; the login name is printed +under the +.BR \(mif +option. +T} +PID@(all)@T{ +The process ID of the process; it is possible to kill a process if this +datum is known. +T} +PPID@(f,l)@The process ID of the parent process. +C@(f,l)@Processor utilization for scheduling. +PRI@(l)@T{ +The priority of the process; higher numbers mean lower priority. +T} +NI@(l)@T{ +Nice value; used in priority computation. +T} +ADDR@(l)@The address of the process. +SZ@(l)@T{ +The size in blocks of the core image of the process. +T} +WCHAN@(l)@T{ +The event for which the process is waiting or sleeping; if blank, the +process is running. +T} +STIME@(f)@Starting time of the process. +TTY@(all)@The controlling terminal for the process. +TIME@(all)@T{ +The cumulative execution time for the process. +T} +CMD@(all)@T{ +The command name; the full command name and its arguments are written +under the +.BR \(mif +option. +T} +.TE +.P +A process that has exited and has a parent, but has not yet been waited +for by the parent, shall be marked +.BR defunct . +.P +Under the option +.BR \(mif , +.IR ps +tries to determine the command name and arguments given when the +process was created by examining memory or the swap area. Failing +this, the command name, as it would appear without the option +.BR \(mif , +is written in square brackets. +.P +The +.BR \(mio +option allows the output format to be specified under user control. +.P +The application shall ensure that the format specification is a list of +names presented as a single argument, + +or +-separated. +Each variable has a default header. The default header can be overridden +by appending an + +and the new text of the header. The rest of the characters in the +argument shall be used as the header text. The fields specified shall +be written in the order specified on the command line, and should be +arranged in columns in the output. The field widths shall be selected +by the system to be at least as wide as the header text (default or +overridden value). If the header text is null, such as +.BR \(mio +.IR user =, +the field width shall be at least as wide as the default header text. +If all header text fields are null, no header line shall be written. +.P +The following names are recognized in the POSIX locale: +.IP "\fBruser\fR" 8 +The real user ID of the process. This shall be the textual user ID, if +it can be obtained and the field width permits, or a decimal +representation otherwise. +.IP "\fBuser\fR" 8 +The effective user ID of the process. This shall be the textual user +ID, if it can be obtained and the field width permits, or a decimal +representation otherwise. +.IP "\fBrgroup\fR" 8 +The real group ID of the process. This shall be the textual group ID, +if it can be obtained and the field width permits, or a decimal +representation otherwise. +.IP "\fBgroup\fR" 8 +The effective group ID of the process. This shall be the textual group +ID, if it can be obtained and the field width permits, or a decimal +representation otherwise. +.IP "\fBpid\fR" 8 +The decimal value of the process ID. +.IP "\fBppid\fR" 8 +The decimal value of the parent process ID. +.IP "\fBpgid\fR" 8 +The decimal value of the process group ID. +.IP "\fBpcpu\fR" 8 +The ratio of CPU time used recently to CPU time available in the same +period, expressed as a percentage. The meaning of ``recently'' in this +context is unspecified. The CPU time available is determined in an +unspecified manner. +.IP "\fBvsz\fR" 8 +The size of the process in (virtual) memory in 1\|024 byte units as a +decimal integer. +.IP "\fBnice\fR" 8 +The decimal value of the nice value of the process; see +.IR nice . +.IP "\fBetime\fR" 8 +In the POSIX locale, the elapsed time since the process was started, in +the form: +.RS 8 +.sp +.RS 4 +.nf +\fB +\fB[[\fIdd\fR\(mi\fB]\fIhh\fR:\fB]\fImm\fR:\fIss\fR +.fi \fR +.P +.RE +.P +where +.IR dd +shall represent the number of days, +.IR hh +the number of hours, +.IR mm +the number of minutes, and +.IR ss +the number of seconds. The +.IR dd +field shall be a decimal integer. The +.IR hh , +.IR mm , +and +.IR ss +fields shall be two-digit decimal integers padded on the left with +zeros. +.RE +.IP "\fBtime\fR" 8 +In the POSIX locale, the cumulative CPU time of the process in the +form: +.RS 8 +.sp +.RS 4 +.nf +\fB +\fB[\fIdd\fR\(mi\fB]\fIhh\fR:\fImm\fR:\fIss\fR +.fi \fR +.P +.RE +.P +The +.IR dd , +.IR hh , +.IR mm , +and +.IR ss +fields shall be as described in the +.BR etime +specifier. +.RE +.IP "\fBtty\fR" 8 +The name of the controlling terminal of the process (if any) in the +same format used by the +.IR who +utility. +.IP "\fBcomm\fR" 8 +The name of the command being executed (\c +.IR argv [0] +value) as a string. +.IP "\fBargs\fR" 8 +The command with all its arguments as a string. The implementation may +truncate this value to the field width; it is implementation-defined +whether any further truncation occurs. It is unspecified whether the +string represented is a version of the argument list as it was passed +to the command when it started, or is a version of the arguments as +they may have been modified by the application. Applications cannot +depend on being able to modify their argument list and having that +modification be reflected in the output of +.IR ps . +.P +Any field need not be meaningful in all implementations. In such a +case a + +(\c +.BR '\(mi' ) +should be output in place of the field value. +.P +Only +.BR comm +and +.BR args +shall be allowed to contain + +characters; all others shall not. Any implementation-defined variables +shall be specified in the system documentation along with the default +header and indicating whether the field may contain + +characters. +.P +The following table specifies the default header to be used in the +POSIX locale corresponding to each format specifier. +.br +.sp +.ce 1 +\fBTableNames: Variable\fR +.TS +center tab(@) box; +cB cB | cB cB +lB lB | lB lB. +Format Specifier@Default Header@Format Specifier@Default Header +_ +args@COMMAND@ppid@PPID +comm@COMMAND@rgroup@RGROUP +etime@ELAPSED@ruser@RUSER +group@GROUP@time@TIME +nice@NI@tty@TT +pcpu@%CPU@user@USER +pgid@PGID@vsz@VSZ +pid@PID +.TE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Things can change while +.IR ps +is running; the snapshot it gives is only true for an instant, and +might not be accurate by the time it is displayed. +.P +The +.BR args +format specifier is allowed to produce a truncated version of the +command arguments. In some implementations, this information is no +longer available when the +.IR ps +utility is executed. +.P +If the field width is too narrow to display a textual ID, the system +may use a numeric version. Normally, the system would be expected to +choose large enough field widths, but if a large number of fields were +selected to write, it might squeeze fields to their minimum sizes to +fit on one line. One way to ensure adequate width for the textual IDs +is to override the default header for a field to make it larger than +most or all user or group names. +.P +There is no special quoting mechanism for header text. The header text +is the rest of the argument. If multiple header changes are needed, +multiple +.BR \(mio +options can be used, such as: +.sp +.RS 4 +.nf +\fB +ps \(mio "user=User Name" \(mio pid=Process\e ID +.fi \fR +.P +.RE +.P +On some implementations, especially multi-level secure systems, +.IR ps +may be severely restricted and produce information only about child +processes owned by the user. +.SH EXAMPLES +The command: +.sp +.RS 4 +.nf +\fB +ps \(mio user,pid,ppid=MOM \(mio args +.fi \fR +.P +.RE +.P +writes at least the following in the POSIX locale: +.sp +.RS 4 +.nf +\fB + USER PID MOM COMMAND +helene 34 12 ps \(mio uid,pid,ppid=MOM \(mio args +.fi \fR +.P +.RE +.P +The contents of the +.BR COMMAND +field need not be the same in all implementations, due to possible +truncation. +.SH RATIONALE +There is very little commonality between BSD and System V +implementations of +.IR ps . +Many options conflict or have subtly different usages. The standard +developers attempted to select a set of options for the base standard +that were useful on a wide range of systems and selected options that +either can be implemented on both BSD and System V-based systems +without breaking the current implementations or where the options are +sufficiently similar that any changes would not be unduly problematic +for users or implementors. +.P +It is recognized that on some implementations, especially multi-level +secure systems, +.IR ps +may be nearly useless. The default output has therefore been chosen +such that it does not break historical implementations and also is +likely to provide at least some useful information on most systems. +.P +The major change is the addition of the format specification +capability. The motivation for this invention is to provide a mechanism +for users to access a wider range of system information, if the system +permits it, in a portable manner. The fields chosen to appear in this volume of POSIX.1\(hy2008 +were arrived at after considering what concepts were likely to be both +reasonably useful to the ``average'' user and had a reasonable chance +of being implemented on a wide range of systems. Again it is recognized +that not all systems are able to provide all the information and, +conversely, some may wish to provide more. It is hoped that the +approach adopted will be sufficiently flexible and extensible to +accommodate most systems. Implementations may be expected to introduce +new format specifiers. +.P +The default output should consist of a short listing containing the +process ID, terminal name, cumulative execution time, and command name +of each process. +.P +The preference of the standard developers would have been to make the +format specification an operand of the +.IR ps +command. Unfortunately, BSD usage precluded this. +.P +At one time a format was included to display the environment array of +the process. This was deleted because there is no portable way to +display it. +.P +The +.BR \(miA +option is equivalent to the BSD +.BR \(mig +and the SVID +.BR \(mie . +Because the two systems differed, a mnemonic compromise was selected. +.P +The +.BR \(mia +option is described with some optional behavior because the SVID omits +session leaders, but BSD does not. +.P +In an early proposal, format specifiers appeared for priority and start +time. The former was not defined adequately in this volume of POSIX.1\(hy2008 and was removed in +deference to the defined nice value; the latter because elapsed time +was considered to be more useful. +.P +In a new BSD version of +.IR ps , +a +.BR \(miO +option can be used to write all of the default information, followed by +additional format specifiers. This was not adopted because the default +output is implementation-defined. Nevertheless, this is a useful +option that should be reserved for that purpose. In the +.BR \(mio +option for the POSIX Shell and Utilities +.IR ps , +the format is the concatenation of each +.BR \(mio . +Therefore, the user can have an alias or function that defines the +beginning of their desired format and add more fields to the end of the +output in certain cases where that would be useful. +.P +The format of the terminal name is unspecified, but the descriptions of +.IR ps , +.IR talk , +.IR who , +and +.IR write +require that they all use the same format. +.P +The +.BR pcpu +field indicates that the CPU time available is determined in an +unspecified manner. This is because it is difficult to express an +algorithm that is useful across all possible machine architectures. +Historical counterparts to this value have attempted to show percentage +of use in the recent past, such as the preceding minute. Frequently, +these values for all processes did not add up to 100%. Implementations +are encouraged to provide data in this field to users that will help +them identify processes currently affecting the performance of the +system. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIkill\fR\^", +.IR "\fInice\fR\^", +.IR "\fIrenice\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/pwd.1p b/man-pages-posix-2013-a/man1p/pwd.1p new file mode 100644 index 0000000..6284794 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/pwd.1p @@ -0,0 +1,210 @@ +'\" et +.TH PWD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pwd +\(em return working directory name +.SH SYNOPSIS +.LP +.nf +pwd \fB[\fR\(miL|\(miP\fB]\fR +.fi +.SH DESCRIPTION +The +.IR pwd +utility shall write to standard output an absolute pathname of the +current working directory, which does not contain the filenames dot or +dot-dot. +.SH OPTIONS +The +.IR pwd +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(miL\fP" 10 +If the +.IR PWD +environment variable contains an absolute pathname of the current +directory that does not contain the filenames dot or dot-dot, +.IR pwd +shall write this pathname to standard output. Otherwise, if the +.IR PWD +environment variable contains a pathname of the current directory +that is longer than +{PATH_MAX} +bytes including the terminating null, and the pathname does not contain +any components that are dot or dot-dot, it is unspecified whether +.IR pwd +writes this pathname to standard output or behaves as if the +.BR \(miP +option had been specified. Otherwise, the +.BR \(miL +option shall behave as the +.BR \(miP +option. +.IP "\fB\(miP\fP" 10 +The pathname written to standard output shall not contain any components +that refer to files of type symbolic link. If there are multiple pathnames +that the +.IR pwd +utility could write to standard output, one beginning with a single + +character and one or more beginning with two + +characters, then it shall write the pathname beginning with a single + +character. The pathname shall not contain any unnecessary + +characters after the leading one or two + +characters. +.P +If both +.BR \(miL +and +.BR \(miP +are specified, the last one shall apply. If neither +.BR \(miL +nor +.BR \(miP +is specified, the +.IR pwd +utility shall behave as if +.BR \(miL +had been specified. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pwd : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPWD\fP" 10 +An absolute pathname of the current working directory. If an +application sets or unsets the value of +.IR PWD , +the behavior of +.IR pwd +is unspecified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR pwd +utility output is an absolute pathname of the current working +directory: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIdirectory pathname\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If an error is detected, output shall not be written to standard +output, a diagnostic message shall be written to standard error, and +the exit status is not zero. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If the pathname obtained from +.IR pwd +is longer than +{PATH_MAX} +bytes, it could produce an error if passed to +.IR cd . +Therefore, in order to return to that directory it may be necessary to +break the pathname into sections shorter than +{PATH_MAX} +and call +.IR cd +on each section in turn (the first section being an absolute pathname +and subsequent sections being relative pathnames). +.SH EXAMPLES +None. +.SH RATIONALE +Some implementations have historically provided +.IR pwd +as a shell special built-in command. +.P +In most utilities, if an error occurs, partial output may be written to +standard output. This does not happen in historical implementations of +.IR pwd . +Because +.IR pwd +is frequently used in historical shell scripts without checking the +exit status, it is important that the historical behavior is required +here; therefore, the CONSEQUENCES OF ERRORS section specifically +disallows any partial output being written to standard output. +.P +An earlier version of this standard stated that the +.IR PWD +environment variable was affected when the +.BR \(miP +option was in effect. This was incorrect; conforming implementations +do not do this. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcd\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetcwd\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qalter.1p b/man-pages-posix-2013-a/man1p/qalter.1p new file mode 100644 index 0000000..668d277 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qalter.1p @@ -0,0 +1,1093 @@ +'\" et +.TH QALTER "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qalter +\(em alter batch job +.SH SYNOPSIS +.LP +.nf +qalter \fB[\fR\(mia \fIdate_time\fB] [\fR\(miA \fIaccount_string\fB] [\fR\(mic \fIinterval\fB] [\fR\(mie \fIpath_name\fB] + [\fR\(mih \fIhold_list\fB] [\fR\(mij \fIjoin_list\fB] [\fR\(mik \fIkeep_list\fB] [\fR\(mil \fIresource_list\fB] + [\fR\(mim \fImail_options\fB] [\fR\(miM \fImail_list\fB] [\fR\(miN \fIname\fB] [\fR\(mio \fIpath_name\fB] + [\fR\(mip \fIpriority\fB] [\fR\(mir \fIy\fR|\fIn\fB] [\fR\(miS \fIpath_name_list\fB] [\fR\(miu \fIuser_list\fB] + \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +The attributes of a batch job are altered by a request to the batch +server that manages the batch job. The +.IR qalter +utility is a user-accessible batch client that requests the alteration +of the attributes of one or more batch jobs. +.P +The +.IR qalter +utility shall alter the attributes of those batch jobs, and only those +batch jobs, for which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qalter +utility shall alter the attributes of batch jobs in the order in which +the batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qalter +utility fails to process a batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +For each batch +.IR job_identifier +for which the +.IR qalter +utility succeeds, each attribute of the identified batch job shall be +altered as indicated by all the options presented to the utility. +.P +For each identified batch job for which the +.IR qalter +utility fails, the utility shall not alter any attribute of the batch +job. +.P +For each batch job that the +.IR qalter +utility processes, the utility shall not modify any attribute other +than those required by the options and option-arguments presented to +the utility. +.P +The +.IR qalter +utility shall alter batch jobs by sending a +.IR "Modify Job Request" +to the batch server that manages each batch job. At the time the +.IR qalter +utility exits, it shall have modified the batch job corresponding to +each successfully processed batch +.IR job_identifier . +An attempt to alter the attributes of a batch job in the RUNNING state +is implementation-defined. +.SH OPTIONS +The +.IR qalter +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mia\ \fIdate_time\fR" 10 +Redefine the time at which the batch job becomes eligible for +execution. +.RS 10 +.P +The +.IR date_time +argument shall be in the same form and represent the same time as for +the +.IR touch +utility. The time so represented shall be set into the +.IR Execution_Time +attribute of the batch job. If the time specified is earlier than the +current time, the +.BR \(mia +option shall have no effect. +.RE +.IP "\fB\(miA\ \fIaccount_string\fR" 10 +.br +Redefine the account to which the resource consumption of the batch job +should be charged. +.RS 10 +.P +The syntax of the +.IR account_string +option-argument is unspecified. +.P +The +.IR qalter +utility shall set the +.IR Account_Name +attribute of the batch job to the value of the +.IR account_string +option-argument. +.RE +.IP "\fB\(mic\ \fIinterval\fR" 10 +Redefine whether the batch job should be checkpointed, and if so, how +often. +.RS 10 +.P +The +.IR qalter +utility shall accept a value for the interval option-argument that is +one of the following: +.IP "\fRn\fP" 10 +No checkpointing is to be performed on the batch job +(NO_CHECKPOINT). +.IP "\fRs\fP" 10 +Checkpointing is to be performed only when the batch server is shut +down (CHECKPOINT_AT_SHUTDOWN). +.IP "\fRc\fP" 10 +Automatic periodic checkpointing is to be performed at the +.IR Minimum_Cpu_Interval +attribute of the batch queue, in units of CPU minutes +(CHECKPOINT_AT_MIN_CPU_INTERVAL). +.IP "\fRc\fR=\fIminutes\fR" 10 +Automatic periodic checkpointing is to be performed every +.IR minutes +of CPU time, or every +.IR Minimum_Cpu_Interval +minutes, whichever is greater. The +.IR minutes +argument shall conform to the syntax for unsigned integers and shall be +greater than zero. +.P +An implementation may define other checkpoint intervals. The +conformance document for an implementation shall describe any +alternative checkpoint intervals, how they are specified, their +internal behavior, and how they affect the behavior of the utility. +.P +The +.IR qalter +utility shall set the +.IR Checkpoint +attribute of the batch job to the value of the +.IR interval +option-argument. +.RE +.IP "\fB\(mie\ \fIpath_name\fR" 10 +.br +Redefine the path to be used for the standard error stream of the batch +job. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR path_name +option-argument that conforms to the syntax of the +.IR path_name +element defined in the System Interfaces volume of POSIX.1\(hy2008, which can be preceded by a host name +element of the form +.IR hostname :. +.P +If the +.IR path_name +option-argument constitutes an absolute pathname, the +.IR qalter +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the +.IR path_name +option-argument, including the host name element, if present. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and no host name +element is specified, the +.IR qalter +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the absolute pathname +derived by expanding the +.IR path_name +option-argument relative to the current directory of the process that +executes the +.IR qalter +utility. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and a host name +element is specified, the +.IR qalter +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the option-argument without +expansion. +.P +If the +.IR path_name +option-argument does not include a host name element, the +.IR qalter +utility shall prefix the pathname in the +.IR Error_Path +attribute with +.IR hostname :, +where +.IR hostname +is the name of the host upon which the +.IR qalter +utility is being executed. +.RE +.IP "\fB\(mih\ \fIhold_list\fR" 10 +Redefine the types of holds, if any, on the batch job. The +.IR qalter +.BR \(mih +option shall accept a value for the +.IR hold_list +option-argument that is a string of alphanumeric characters in the +portable character set. +.RS 10 +.P +The +.IR qalter +utility shall accept a value for the +.IR hold_list +option-argument that is a string of one or more of the characters +.BR 'u' , +.BR 's' , +or +.BR 'o' , +or the single character +.BR 'n' . +For each unique character in the +.IR hold_list +option-argument, the +.IR qalter +utility shall add a value to the +.IR Hold_Types +attribute of the batch job as follows, each representing a different +hold type: +.IP "\fRu\fP" 6 +USER +.IP "\fRs\fP" 6 +SYSTEM +.IP "\fRo\fP" 6 +OPERATOR +.P +If any of these characters are duplicated in the +.IR hold_list +option-argument, the duplicates shall be ignored. An existing +.IR Hold_Types +attribute can be cleared by the hold type: +.IP "\fRn\fP" 6 +NO_HOLD +.P +The +.IR qalter +utility shall consider it an error if any hold type other than +.BR 'n' +is combined with hold type +.BR 'n' . +Strictly conforming applications shall not repeat any of the characters +.BR 'u' , +.BR 's' , +.BR 'o' , +or +.BR 'n' +within the +.IR hold_list +option-argument. The +.IR qalter +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. An implementation may +define other hold types. The conformance document for an implementation +shall describe any additional hold types, how they are specified, their +internal behavior, and how they affect the behavior of the utility. +.RE +.IP "\fB\(mij\ \fIjoin_list\fR" 10 +Redefine which streams of the batch job are to be merged. The +.IR qalter +.BR \(mij +option shall accept a value for the +.IR join_list +option-argument that is a string of alphanumeric characters in the +portable character set. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR join_list +option-argument that consists of one or more of the characters +.BR 'e' +and +.BR 'o' , +or the single character +.BR 'n' . +.P +All of the other batch job output streams specified shall be merged +into the output stream represented by the character listed first in the +.IR join_list +option-argument. +.P +For each unique character in the +.IR join_list +option-argument, the +.IR qalter +utility shall add a value to the +.IR Join_Path +attribute of the batch job as follows, each representing a different +batch job stream to join: +.IP "\fRe\fP" 6 +The standard error of the batch job (JOIN_STD_ERROR). +.IP "\fRo\fP" 6 +The standard output of the batch job (JOIN_STD_OUTPUT). +.P +An existing +.IR Join_Path +attribute can be cleared by the join type: +.IP "\fRn\fP" 6 +NO_JOIN +.P +If +.BR 'n' +is specified, then no files are joined. The +.IR qalter +utility shall consider it an error if any join type other than +.BR 'n' +is combined with join type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'o' , +or +.BR 'n' +within the +.IR join_list +option-argument. The +.IR qalter +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other join types. The conformance document +for an implementation shall describe any additional batch job streams, +how they are specified, their internal behavior, and how they affect +the behavior of the utility. +.RE +.IP "\fB\(mik\ \fIkeep_list\fR" 10 +Redefine which output of the batch job to retain on the execution host. +.RS 10 +.P +The +.IR qalter +.BR \(mik +option shall accept a value for the +.IR keep_list +option-argument that is a string of alphanumeric characters in the +portable character set. +.P +The +.IR qalter +utility shall accept a +.IR keep_list +option-argument that consists of one or more of the characters +.BR 'e' +and +.BR 'o' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR keep_list +option-argument, the +.IR qalter +utility shall add a value to the +.IR Keep_Files +attribute of the batch job as follows, each representing a different +batch job stream to keep: +.IP "\fRe\fP" 6 +The standard error of the batch job (KEEP_STD_ERROR). +.IP "\fRo\fP" 6 +The standard output of the batch job (KEEP_STD_OUTPUT). +.P +If both +.BR 'e' +and +.BR 'o' +are specified, then both files are retained. An existing +.IR Keep_Files +attribute can be cleared by the keep type: +.IP "\fRn\fP" 6 +NO_KEEP +.P +If +.BR 'n' +is specified, then no files are retained. The +.IR qalter +utility shall consider it an error if any keep type other than +.BR 'n' +is combined with keep type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'o' , +or +.BR 'n' +within the +.IR keep_list +option-argument. The +.IR qalter +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. An implementation may +define other keep types. The conformance document for an implementation +shall describe any additional keep types, how they are specified, their +internal behavior, and how they affect the behavior of the utility. +.RE +.IP "\fB\(mil\ \fIresource_list\fR" 10 +.br +Redefine the resources that are allowed or required by the batch job. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR resource_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +resource=value[,,resource=value,,...] +.fi \fR +.P +.RE +.P +The +.IR qalter +utility shall set one entry in the value of the +.IR Resource_List +attribute of the batch job for each resource listed in the +.IR resource_list +option-argument. +.P +Because the list of supported resource names might vary by batch +server, the +.IR qalter +utility shall rely on the batch server to validate the resource names +and associated values. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(mim\ \fImail_options\fR" 10 +.br +Redefine the points in the execution of the batch job at which the +batch server is to send mail about a change in the state of the batch +job. +.RS 10 +.P +The +.IR qalter +.BR \(mim +option shall accept a value for the +.IR mail_options +option-argument that is a string of alphanumeric characters in the +portable character set. +.P +The +.IR qalter +utility shall accept a value for the +.IR mail_options +option-argument that is a string of one or more of the characters +.BR 'e' , +.BR 'b' , +and +.BR 'a' , +or the single character +.BR 'n' . +For each unique character in the +.IR mail_options +option-argument, the +.IR qalter +utility shall add a value to the +.IR Mail_Users +attribute of the batch job as follows, each representing a different +time during the life of a batch job at which to send mail: +.IP "\fRe\fP" 6 +MAIL_AT_EXIT +.IP "\fRb\fP" 6 +MAIL_AT_BEGINNING +.IP "\fRa\fP" 6 +MAIL_AT_ABORT +.P +If any of these characters are duplicated in the +.IR mail_options +option-argument, the duplicates shall be ignored. +.P +An existing +.IR Mail_Points +attribute can be cleared by the mail type: +.IP "\fRn\fP" 6 +NO_MAIL +.P +If +.BR 'n' +is specified, then mail is not sent. The +.IR qalter +utility shall consider it an error if any mail type other than +.BR 'n' +is combined with mail type +.BR 'n' . +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'b' , +.BR 'a' , +or +.BR 'n' +within the +.IR mail_options +option-argument. The +.IR qalter +utility shall permit the repetition of characters but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other mail types. The conformance document +for an implementation shall describe any additional mail types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. +.RE +.IP "\fB\(miM\ \fImail_list\fR" 10 +Redefine the list of users to which the batch server that executes the +batch job is to send mail, if the batch server sends mail about the +batch job. +.RS 10 +.P +The syntax of the +.IR mail_list +option-argument is unspecified. If the implementation of the +.IR qalter +utility uses a name service to locate users, the utility shall accept +the syntax used by the name service. +.P +If the implementation of the +.IR qalter +utility does not use a name service to locate users, the implementation +shall accept the following syntax for user names: +.sp +.RS 4 +.nf +\fB +mail_address[,,mail_address,,...] +.fi \fR +.P +.RE +.P +The interpretation of +.IR mail_address +is implementation-defined. +.P +The +.IR qalter +utility shall set the +.IR Mail_Users +attribute of the batch job to the value of the +.IR mail_list +option-argument. +.RE +.IP "\fB\(miN\ \fIname\fR" 10 +Redefine the name of the batch job. +.RS 10 +.P +The +.IR qalter +.BR \(miN +option shall accept a value for the +.IR name +option-argument that is a string of up to 15 alphanumeric characters in +the portable character set where the first character is alphabetic. +.P +The syntax of the +.IR name +option-argument is unspecified. +.P +The +.IR qalter +utility shall set the +.IR Job_Name +attribute of the batch job to the value of the +.IR name +option-argument. +.RE +.IP "\fB\(mio\ \fIpath_name\fR" 10 +.br +Redefine the path for the standard output of the batch job. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR path_name +option-argument that conforms to the syntax of the +.IR path_name +element defined in the System Interfaces volume of POSIX.1\(hy2008, which can be preceded by a host name +element of the form +.IR hostname :. +.P +If the +.IR path_name +option-argument constitutes an absolute pathname, the +.IR qalter +utility shall set the +.IR Output_Path +attribute of the batch job to the value of the +.IR path_name +option-argument. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and no host name +element is specified, the +.IR qalter +utility shall set the +.IR Output_Path +attribute of the batch job to the absolute pathname derived by +expanding the +.IR path_name +option-argument relative to the current directory of the process that +executes the +.IR qalter +utility. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and a host name +element is specified, the +.IR qalter +utility shall set the +.IR Output_Path +attribute of the batch job to the value of the +.IR path_name +option-argument without any expansion of the pathname. +.P +If the +.IR path_name +option-argument does not include a host name element, the +.IR qalter +utility shall prefix the pathname in the +.IR Output_Path +attribute with +.IR hostname :, +where +.IR hostname +is the name of the host upon which the +.IR qalter +utility is being executed. +.RE +.IP "\fB\(mip\ \fIpriority\fR" 10 +Redefine the priority of the batch job. +.RS 10 +.P +The +.IR qalter +utility shall accept a value for the priority option-argument that +conforms to the syntax for signed decimal integers, and which is not +less than \(mi1\|024 and not greater than 1\|023. +.P +The +.IR qalter +utility shall set the +.IR Priority +attribute of the batch job to the value of the +.IR priority +option-argument. +.RE +.IP "\fB\(mir\ \fRy\fR|\fRn\fR" 10 +Redefine whether the batch job is rerunnable. +.RS 10 +.P +If the value of the option-argument is +.BR 'y' , +the +.IR qalter +utility shall set the +.IR Rerunable +attribute of the batch job to TRUE. +.P +If the value of the option-argument is +.BR 'n' , +the +.IR qalter +utility shall set the +.IR Rerunable +attribute of the batch job to FALSE. +.P +The +.IR qalter +utility shall consider it an error if any character other than +.BR 'y' +or +.BR 'n' +is specified in the option-argument. +.RE +.IP "\fB\(miS\ \fIpath_name_list\fR" 10 +.br +Redefine the shell that interprets the script at the destination +system. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR path_name_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +pathname[@host][,pathname[@host],...] +.fi \fR +.P +.RE +.P +The +.IR qalter +utility shall accept only one pathname that is missing a corresponding +host name. The +.IR qalter +utility shall allow only one pathname per named host. +.P +The +.IR qalter +utility shall add a value to the +.IR Shell_Path_List +attribute of the batch job for each entry in the +.IR path_name_list +option-argument. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(miu\ \fIuser_list\fR" 10 +Redefine the user name under which the batch job is to run at the +destination system. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR user_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +username[@host][,,username[@host],,...] +.fi \fR +.P +.RE +.P +The +.IR qalter +utility shall accept only one user name that is missing a corresponding +host name. The +.IR qalter +utility shall accept only one user name per named host. +.P +The +.IR qalter +utility shall add a value to the +.IR User_List +attribute of the batch job for each entry in the +.IR user_list +option-argument. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.SH OPERANDS +The +.IR qalter +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qalter : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.IP "\fITZ\fP" 10 +Determine the timezone used to interpret the +.IR date-time +option-argument. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qalter +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qalter +utility attempts to locate the batch job on other batch servers is +implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qalter +utility allows users to change the attributes of a batch job. +.P +As a means of altering a queued job, the +.IR qalter +utility is superior to deleting and requeuing the batch job insofar as +an altered job retains its place in the queue with some traditional +selection algorithms. In addition, the +.IR qalter +utility is both shorter and simpler than a sequence of +.IR qdel +and +.IR qsub +utilities. +.P +The result of an attempt on the part of a user to alter a batch job in +a RUNNING state is implementation-defined because a batch job in the +RUNNING state will already have opened its output files and otherwise +performed any actions indicated by the options in effect at the time +the batch job began execution. +.P +The options processed by the +.IR qalter +utility are identical to those of the +.IR qsub +utility, with a few exceptions: +.BR \(miV , +.BR \(miv , +and +.BR \(miq . +The +.BR \(miV +and +.BR \(miv +are inappropriate for the +.IR qalter +utility, since they capture potentially transient environment +information from the submitting process. The +.BR \(miq +option would specify a new queue, which would largely negate the +previously stated advantage of using +.IR qalter ; +furthermore, the +.IR qmove +utility provides a superior means of moving jobs. +.P +Each of the following paragraphs provides the rationale for a +.IR qalter +option. +.P +Additional rationale concerning these options can be found in the +rationale for the +.IR qsub +utility. +.P +The +.BR \(mia +option allows users to alter the date and time at which a batch job +becomes eligible to run. +.P +The +.BR \(miA +option allows users to change the account that will be charged for the +resources consumed by the batch job. Support for the +.BR \(miA +option is mandatory for conforming implementations of +.IR qalter , +even though support of accounting is optional for servers. Whether or +not to support accounting is left to the implementor of the server, but +mandatory support of the +.BR \(miA +option assures users of a consistent interface and allows them to +control accounting on servers that support accounting. +.P +The +.BR \(mic +option allows users to alter the checkpointing interval of a batch +job. A checkpointing system, which is not defined by POSIX.1\(hy2008, allows +recovery of a batch job at the most recent checkpoint in the event of a +crash. Checkpointing is typically used for jobs that consume expensive +computing time or must meet a critical schedule. Users should be +allowed to make the tradeoff between the overhead of checkpointing and +the risk to the timely completion of the batch job; therefore, this volume of POSIX.1\(hy2008 +provides the checkpointing interval option. Support for checkpointing +is optional for servers. +.P +The +.BR \(mie +option allows users to alter the name and location of the standard +error stream written by a batch job. However, the path of the standard +error stream is meaningless if the value of the +.IR Join_Path +attribute of the batch job is TRUE. +.P +The +.BR \(mih +option allows users to set the hold type in the +.IR Hold_Types +attribute of a batch job. The +.IR qhold +and +.IR qrls +utilities add or remove hold types to the +.IR Hold_Types +attribute, respectively. The +.BR \(mih +option has been modified to allow for implementation-defined hold +types. +.P +The +.BR \(mij +option allows users to alter the decision to join (merge) the standard +error stream of the batch job with the standard output stream of the +batch job. +.P +The +.BR \(mil +option allows users to change the resource limits imposed on a batch +job. +.P +The +.BR \(mim +option allows users to modify the list of points in the life of a batch +job at which the designated users will receive mail notification. +.P +The +.BR \(miM +option allows users to alter the list of users who will receive +notification about events in the life of a batch job. +.P +The +.BR \(miN +option allows users to change the name of a batch job. +.P +The +.BR \(mio +option allows users to alter the name and path to which the standard +output stream of the batch job will be written. +.P +The +.BR \(miP +option allows users to modify the priority of a batch job. Support for +priority is optional for batch servers. +.P +The +.BR \(mir +option allows users to alter the rerunability status of a batch job. +.P +The +.BR \(miS +option allows users to change the name and location of the shell image +that will be invoked to interpret the script of the batch job. This +option has been modified to allow a list of shell name and locations +associated with different hosts. +.P +The +.BR \(miu +option allows users to change the user identifier under which the batch +job will execute. +.P +The +.IR job_identifier +operand syntax is provided so that the user can differentiate between +the originating and destination (or executing) batch server. These may +or may not be the same. The .\c +.IR server_name +portion identifies the originating batch server, while the @\c +.IR server +portion identifies the destination batch server. +.P +Historically, the +.IR qalter +utility has been a component of the Network Queuing System (NQS), the +existing practice from which this utility has been derived. +.SH "FUTURE DIRECTIONS" +The +.IR qalter +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqdel\fR\^", +.IR "\fIqhold\fR\^", +.IR "\fIqmove\fR\^", +.IR "\fIqrls\fR\^", +.IR "\fIqsub\fR\^", +.IR "\fItouch\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qdel.1p b/man-pages-posix-2013-a/man1p/qdel.1p new file mode 100644 index 0000000..322db96 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qdel.1p @@ -0,0 +1,208 @@ +'\" et +.TH QDEL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qdel +\(em delete batch jobs +.SH SYNOPSIS +.LP +.nf +qdel \fIjob_identifier\fP... +.fi +.SH DESCRIPTION +A batch job is deleted by sending a request to the batch server that +manages the batch job. A batch job that has been deleted is no longer +subject to management by batch services. +.P +The +.IR qdel +utility is a user-accessible client of batch services that requests the +deletion of one or more batch jobs. +.P +The +.IR qdel +utility shall request a batch server to delete those batch jobs for +which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qdel +utility shall delete batch jobs in the order in which their batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qdel +utility fails to process any batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qdel +utility shall delete each batch job by sending a +.IR "Delete Job Request" +to the batch server that manages the batch job. +.P +The +.IR qdel +utility shall not exit until the batch job corresponding to each +successfully processed batch +.IR job_identifier +has been deleted. +.SH OPTIONS +None. +.SH OPERANDS +The +.IR qdel +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qdel : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +An implementation of the +.IR qdel +utility may write informative messages to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qdel +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qdel +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qdel +utility allows users and administrators to delete jobs. +.P +The +.IR qdel +utility provides functionality that is not otherwise available. For +example, the +.IR kill +utility of the operating system does not suffice. First, to use the +.IR kill +utility, the user might have to log in on a remote node, because the +.IR kill +utility does not operate across the network. Second, unlike +.IR qdel , +.IR kill +cannot remove jobs from queues. Lastly, the arguments of the +.IR qdel +utility are job identifiers rather than process identifiers, and so +this utility can be passed the output of the +.IR qselect +utility, thus providing users with a means of deleting a list of jobs. +.P +Because a set of jobs can be selected using the +.IR qselect +utility, the +.IR qdel +utility has not been complicated with options that provide for +selection of jobs. Instead, the batch jobs to be deleted are identified +individually by their job identifiers. +.P +Historically, the +.IR qdel +utility has been a component of NQS, the existing practice on which it +is based. However, the +.IR qdel +utility defined in this volume of POSIX.1\(hy2008 does not provide an option for specifying a +signal number to send to the batch job prior to the killing of the +process; that capability has been subsumed by the +.IR qsig +utility. +.P +A discussion was held about the delays of networking and the +possibility that the batch server may never respond, due to a down +router, down batch server, or other network mishap. The DESCRIPTION +records this under the words ``fails to process any job identifier''. +In the broad sense, the network problem is also an error, which causes +the failure to process the batch job identifier. +.SH "FUTURE DIRECTIONS" +The +.IR qdel +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIkill\fR\^", +.IR "\fIqselect\fR\^", +.IR "\fIqsig\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qhold.1p b/man-pages-posix-2013-a/man1p/qhold.1p new file mode 100644 index 0000000..c1f0088 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qhold.1p @@ -0,0 +1,270 @@ +'\" et +.TH QHOLD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qhold +\(em hold batch jobs +.SH SYNOPSIS +.LP +.nf +qhold \fB[\fR\(mih \fIhold_list\fB] \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +A hold is placed on a batch job by a request to the batch server that +manages the batch job. A batch job that has one or more holds is not +eligible for execution. The +.IR qhold +utility is a user-accessible client of batch services that requests one +or more types of hold to be placed on one or more batch jobs. +.P +The +.IR qhold +utility shall place holds on those batch jobs for which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qhold +utility shall place holds on batch jobs in the order in which their +batch +.IR job_identifier s +are presented to the utility. If the +.IR qhold +utility fails to process any batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qhold +utility shall place holds on each batch job by sending a +.IR "Hold Job Request" +to the batch server that manages the batch job. +.P +The +.IR qhold +utility shall not exit until holds have been placed on the batch job +corresponding to each successfully processed batch +.IR job_identifier . +.SH OPTIONS +The +.IR qhold +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mih\ \fIhold_list\fR" 10 +Define the types of holds to be placed on the batch job. +.RS 10 +.P +The +.IR qhold +.BR \(mih +option shall accept a value for the +.IR hold_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qhold +utility shall accept a value for the +.IR hold_list +option-argument that is a string of one or more of the characters +.BR 'u' , +.BR 's' , +or +.BR 'o' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR hold_list +option-argument, the +.IR qhold +utility shall add a value to the +.IR Hold_Types +attribute of the batch job as follows, each representing a different +hold type: +.IP "\fRu\fP" 6 +USER +.IP "\fRs\fP" 6 +SYSTEM +.IP "\fRo\fP" 6 +OPERATOR +.P +If any of these characters are duplicated in the +.IR hold_list +option-argument, the duplicates shall be ignored. +.P +An existing +.IR Hold_Types +attribute can be cleared by the following hold type: +.IP "\fRn\fP" 6 +NO_HOLD +.P +The +.IR qhold +utility shall consider it an error if any hold type other than +.BR 'n' +is combined with hold type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'u' , +.BR 's' , +.BR 'o' , +or +.BR 'n' +within the +.IR hold_list +option-argument. The +.IR qhold +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. +.P +If the +.BR \(mih +option is not presented to the +.IR qhold +utility, the implementation shall set the +.IR Hold_Types +attribute to USER. +.RE +.SH OPERANDS +The +.IR qhold +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qhold : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.br +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qhold +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qhold +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qhold +utility allows users to place a hold on one or more jobs. A hold makes +a batch job ineligible for execution. +.P +The +.IR qhold +utility has options that allow the user to specify the type of hold. +Should the user wish to place a hold on a set of jobs that meet a +selection criteria, such a list of jobs can be acquired using the +.IR qselect +utility. +.P +The +.BR \(mih +option allows the user to specify the type of hold that is to be placed +on the job. This option allows for USER, SYSTEM, OPERATOR, and +implementation-defined hold types. The USER and OPERATOR holds are +distinct. The batch server that manages the batch job will verify that +the user is authorized to set the specified hold for the batch job. +.P +Mail is not required on hold because the administrator has the tools +and libraries to build this option if he or she wishes. +.P +Historically, the +.IR qhold +utility has been a part of some existing batch systems, although it has +not traditionally been a part of the NQS. +.SH "FUTURE DIRECTIONS" +The +.IR qhold +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qmove.1p b/man-pages-posix-2013-a/man1p/qmove.1p new file mode 100644 index 0000000..a64e98e --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qmove.1p @@ -0,0 +1,187 @@ +'\" et +.TH QMOVE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qmove +\(em move batch jobs +.SH SYNOPSIS +.LP +.nf +qmove \fIdestination job_identifier\fP... +.fi +.SH DESCRIPTION +To move a batch job is to remove the batch job from the batch queue in +which it resides and instantiate the batch job in another batch queue. +A batch job is moved by a request to the batch server that manages the +batch job. The +.IR qmove +utility is a user-accessible batch client that requests the movement of +one or more batch jobs. +.P +The +.IR qmove +utility shall move those batch jobs, and only those batch jobs, for +which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qmove +utility shall move batch jobs in the order in which the corresponding +batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qmove +utility fails to process a batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qmove +utility shall move batch jobs by sending a +.IR "Move Job Request" +to the batch server that manages each batch job. The +.IR qmove +utility shall not exit before the batch jobs corresponding to all +successfully processed batch +.IR job_identifier s +have been moved. +.SH OPTIONS +None. +.SH OPERANDS +The +.IR qmove +utility shall accept one operand that conforms to the syntax for a +destination (see +.IR "Section 3.3.2" ", " "Destination"). +.P +The +.IR qmove +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qmove : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qmove +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qmove +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qmove +utility allows users to move jobs between queues. +.P +The alternative to using the +.IR qmove +utility\(emdeleting the batch job and requeuing it\(ementails +considerably more typing. +.P +Since the means of selecting jobs based on attributes has been +encapsulated in the +.IR qselect +utility, the only option of the +.IR qmove +utility concerns authorization. The +.BR \(miu +option provides the user with the convenience of changing the user +identifier under which the batch job will execute. Minimalism and +consistency have taken precedence over convenience; the +.BR \(miu +option has been deleted because the equivalent capability exists with +the +.BR \(miu +option of the +.IR qalter +utility. +.SH "FUTURE DIRECTIONS" +The +.IR qmove +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqalter\fR\^", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qmsg.1p b/man-pages-posix-2013-a/man1p/qmsg.1p new file mode 100644 index 0000000..0a8d237 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qmsg.1p @@ -0,0 +1,265 @@ +'\" et +.TH QMSG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qmsg +\(em send message to batch jobs +.SH SYNOPSIS +.LP +.nf +qmsg \fB[\fR\(miEO\fB] \fImessage_string job_identifier\fR... +.fi +.SH DESCRIPTION +To send a message to a batch job is to request that a server write a +message string into one or more output files of the batch job. A +message is sent to a batch job by a request to the batch server that +manages the batch job. The +.IR qmsg +utility is a user-accessible batch client that requests the sending of +messages to one or more batch jobs. +.P +The +.IR qmsg +utility shall write messages into the files of batch jobs by sending a +.IR "Job Message Request" +to the batch server that manages the batch job. The +.IR qmsg +utility shall not directly write the message into the files of the +batch job. +.P +The +.IR qmsg +utility shall send a +.IR "Job Message Request" +for those batch jobs, and only those batch jobs, for which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qmsg +utility shall send +.IR "Job Message Request" s +for batch jobs in the order in which their batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qmsg +utility fails to process any batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qmsg +utility shall not exit before a +.IR "Job Message Request" +has been sent to the server that manages the batch job that corresponds +to each successfully processed batch +.IR job_identifier . +.SH OPTIONS +The +.IR qmsg +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(miE\fP" 10 +Specify that the message is written to the standard error of each batch +job. +.RS 10 +.P +The +.IR qmsg +utility shall write the message into the standard error of the batch +job. +.RE +.IP "\fB\(miO\fP" 10 +Specify that the message is written to the standard output of each +batch job. +.RS 10 +.P +The +.IR qmsg +utility shall write the message into the standard output of the batch +job. +.RE +.P +If neither the +.BR \(miO +nor the +.BR \(miE +option is presented to the +.IR qmsg +utility, the utility shall write the message into an +implementation-defined file. The conformance document for the +implementation shall describe the name and location of the +implementation-defined file. If both the +.BR \(miO +and the +.BR \(miE +options are presented to the +.IR qmsg +utility, then the utility shall write the messages to both standard +output and standard error. +.SH OPERANDS +The +.IR qmsg +utility shall accept a minimum of two operands, +.IR message_string +and one or more batch +.IR job_identifier s. +.P +The +.IR message_string +operand shall be the string to be written to one or more output files +of the batch job followed by a +. +If the string contains + +characters, then the application shall ensure that the string is +quoted. The +.IR message_string +shall be encoded in the portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +All remaining operands are batch +.IR job_identifier s +that conform to the syntax for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qmsg : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qmsg +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qmsg +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qmsg +utility allows users to write messages into the output files of running +jobs. Users, including operators and administrators, have a number of +occasions when they want to place messages in the output files of a +batch job. For example, if a disk that is being used by a batch job is +showing errors, the operator might note this in the standard error +stream of the batch job. +.P +The options of the +.IR qmsg +utility provide users with the means of placing the message in the +output stream of their choice. The default output stream for the +message\(emif the user does not designate an output stream\(emis +implementation-defined, since many implementations will provide, as +an extension to this volume of POSIX.1\(hy2008, a log file that shows the history of utility +execution. +.P +If users wish to send a message to a set of jobs that meet a selection +criteria, the +.IR qselect +utility can be used to acquire the appropriate list of job +identifiers. +.P +The +.BR \(miE +option allows users to place the message in the standard error stream +of the batch job. +.P +The +.BR \(miO +option allows users to place the message in the standard output stream +of the batch job. +.P +Historically, the +.IR qmsg +utility is an existing practice in the offerings of one or more +implementors of an NQS-derived batch system. The utility has been found +to be useful enough that it deserves to be included in this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +The +.IR qmsg +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qrerun.1p b/man-pages-posix-2013-a/man1p/qrerun.1p new file mode 100644 index 0000000..537bc8e --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qrerun.1p @@ -0,0 +1,163 @@ +'\" et +.TH QRERUN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qrerun +\(em rerun batch jobs +.SH SYNOPSIS +.LP +.nf +qrerun \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +To rerun a batch job is to terminate the session leader of the batch +job, delete any associated checkpoint files, and return the batch job +to the batch queued state. A batch job is rerun by a request to the +batch server that manages the batch job. The +.IR qrerun +utility is a user-accessible batch client that requests the rerunning +of one or more batch jobs. +.P +The +.IR qrerun +utility shall rerun those batch jobs for which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qrerun +utility shall rerun batch jobs in the order in which their batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qrerun +utility fails to process any batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qrerun +utility shall rerun batch jobs by sending a +.IR "Rerun Job Request" +to the batch server that manages each batch job. +.P +For each successfully processed batch +.IR job_identifier , +the +.IR qrerun +utility shall have rerun the corresponding batch job at the time +the utility exits. +.SH OPTIONS +None. +.SH OPERANDS +The +.IR qrerun +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qrerun : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qrerun +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qrerun +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qrerun +utility allows users to cause jobs in the running state to exit and +rerun. +.P +The +.IR qrerun +utility is a new utility, \fIvis-a-vis\fP existing practice, that has +been defined in this volume of POSIX.1\(hy2008 to correct user-perceived deficiencies in the +existing practice. +.SH "FUTURE DIRECTIONS" +The +.IR qrerun +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qrls.1p b/man-pages-posix-2013-a/man1p/qrls.1p new file mode 100644 index 0000000..dfc78df --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qrls.1p @@ -0,0 +1,279 @@ +'\" et +.TH QRLS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qrls +\(em release batch jobs +.SH SYNOPSIS +.LP +.nf +qrls \fB[\fR\(mih \fIhold_list\fB] \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +A batch job might have one or more holds, which prevent the batch job +from executing. A batch job from which all the holds have been removed +becomes eligible for execution and is said to have been released. A +batch job hold is removed by sending a request to the batch server that +manages the batch job. The +.IR qrls +utility is a user-accessible client of batch services that requests +holds be removed from one or more batch jobs. +.P +The +.IR qrls +utility shall remove one or more holds from those batch jobs for which +a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qrls +utility shall remove holds from batch jobs in the order in which their +batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qrls +utility fails to process a batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qrls +utility shall remove holds on each batch job by sending a +.IR "Release Job Request" +to the batch server that manages the batch job. +.P +The +.IR qrls +utility shall not exit until the holds have been removed from the batch +job corresponding to each successfully processed batch +.IR job_identifier . +.SH OPTIONS +The +.IR qrls +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mih\ \fIhold_list\fR" 10 +Define the types of holds to be removed from the batch job. +.RS 10 +.P +The +.IR qrls +.BR \(mih +option shall accept a value for the +.IR hold_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qrls +utility shall accept a value for the +.IR hold_list +option-argument that is a string of one or more of the characters +.BR 'u' , +.BR 's' , +or +.BR 'o' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR hold_list +option-argument, the +.IR qrls +utility shall add a value to the +.IR Hold_Types +attribute of the batch job as follows, each representing a different +hold type: +.IP "\fRu\fP" 6 +USER +.IP "\fRs\fP" 6 +SYSTEM +.IP "\fRo\fP" 6 +OPERATOR +.P +If any of these characters are duplicated in the +.IR hold_list +option-argument, the duplicates shall be ignored. +.P +An existing +.IR Hold_Types +attribute can be cleared by the following hold type: +.IP "\fRn\fP" 6 +NO_HOLD +.P +The +.IR qrls +utility shall consider it an error if any hold type other than +.BR 'n' +is combined with hold type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'u' , +.BR 's' , +.BR 'o' , +or +.BR 'n' +within the +.IR hold_list +option-argument. The +.IR qrls +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. +.P +If the +.BR \(mih +option is not presented to the +.IR qrls +utility, the implementation shall remove the USER hold in the +.IR Hold_Types +attribute. +.RE +.SH OPERANDS +The +.IR qrls +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qrls : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qrls +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qrls +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qrls +utility allows users, operators, and administrators to remove holds +from jobs. +.P +The +.IR qrls +utility does not support any job selection options or wildcard +arguments. Users may acquire a list of jobs selected by attributes +using the +.IR qselect +utility. For example, a user could select all of their held jobs. +.P +The +.BR \(mih +option allows the user to specify the type of hold that is to be +removed. This option allows for USER, SYSTEM, OPERATOR, and +implementation-defined hold types. The batch server that manages the +batch job will verify whether the user is authorized to remove the +specified hold for the batch job. If more than one type of hold has +been placed on the batch job, a user may wish to remove only some of +them. +.P +Mail is not required on release because the administrator has the tools +and libraries to build this option if required. +.P +The +.IR qrls +utility is a new utility \fIvis-a-vis\fP existing practice; it has been +defined in this volume of POSIX.1\(hy2008 as the natural complement to the +.IR qhold +utility. +.SH "FUTURE DIRECTIONS" +The +.IR qrls +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqhold\fR\^", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qselect.1p b/man-pages-posix-2013-a/man1p/qselect.1p new file mode 100644 index 0000000..6d9e6bb --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qselect.1p @@ -0,0 +1,918 @@ +'\" et +.TH QSELECT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qselect +\(em select batch jobs +.SH SYNOPSIS +.LP +.nf +qselect \fB[\fR\(mia \fB[\fIop\fB]\fIdate_time\fB] [\fR\(miA \fIaccount_string\fB] [\fR\(mic \fB[\fIop\fB]\fIinterval\fB] + [\fR\(mih \fIhold_list\fB] [\fR\(mil \fIresource_list\fB] [\fR\(miN \fIname\fB] [\fR\(mip \fB[\fIop\fB]\fIpriority\fB] + [\fR\(miq \fIdestination\fB] [\fR\(mir \fIy\fR|\fIn\fB] [\fR\(mis \fIstates\fB] [\fR\(miu \fIuser_list\fB]\fR +.fi +.SH DESCRIPTION +To select a set of batch jobs is to return the batch +.IR job_identifier s +for each batch job that meets a list of selection criteria. A set of +batch jobs is selected by a request to a batch server. The +.IR qselect +utility is a user-accessible batch client that requests the selection +of batch jobs. +.P +Upon successful completion, the +.IR qselect +utility shall have returned a list of zero or more batch +.IR job_identifier s +that meet the criteria specified by the options and option-arguments +presented to the utility. +.P +The +.IR qselect +utility shall select batch jobs by sending a +.IR "Select Jobs Request" +to a batch server. The +.IR qselect +utility shall not exit until the server replies to each request +generated. +.P +For each option presented to the +.IR qselect +utility, the utility shall restrict the set of selected batch jobs as +described in the OPTIONS section. +.P +The +.IR qselect +utility shall not restrict selection of batch jobs except by +authorization and as required by the options presented to the utility. +.P +When an option is specified with a mandatory or optional +.IR op +component to the option-argument, then +.IR op +shall specify a relation between the value of a certain batch job +attribute and the +.IR value +component of the option-argument. If an +.IR op +is allowable on an option, then the description of the option letter +indicates the +.IR op +as either mandatory or optional. Acceptable strings for the +.IR op +component, and the relation the string indicates, are shown in the +following list: +.IP "\fR.eq.\fR" 8 +The value represented by the attribute of the batch job is equal to the +value represented by the option-argument. +.IP "\fR.ge.\fR" 8 +The value represented by the attribute of the batch job is greater than +or equal to the value represented by the option-argument. +.IP "\fR.gt.\fR" 8 +The value represented by the attribute of the batch job is greater than +the value represented by the option-argument. +.IP "\fR.lt.\fR" 8 +The value represented by the attribute of the batch job is less than +the value represented by the option-argument. +.IP "\fR.le.\fR" 8 +The value represented by the attribute of the batch job is less than or +equal to the value represented by the option-argument. +.IP "\fR.ne.\fR" 8 +The value represented by the attribute of the batch job is not equal to +the value represented by the option-argument. +.SH OPTIONS +The +.IR qselect +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mia\ [\fIop\fB]\fIdate_time\fR" 10 +.br +Restrict selection to a specific time, or a range of times. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Execution_Time +attribute is related to the Epoch equivalent of the local time +expressed by the value of the +.IR date_time +component of the option-argument in the manner indicated by the value +of the +.IR op +component of the option-argument. +.P +The +.IR qselect +utility shall accept a +.IR date_time +component of the option-argument that conforms to the syntax of the +.IR time +operand of the +.IR touch +utility. +.P +If the +.IR op +component of the option-argument is not presented to the +.IR qselect +utility, the utility shall select batch jobs for which the +.IR Execution_Time +attribute is equal to the +.IR date_time +component of the option-argument. +.P +When comparing times, the +.IR qselect +utility shall use the following definitions for the +.IR op +component of the option-argument: +.IP "\fR.eq.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is equal to the time represented by the +.IR date_time +component of the option-argument. +.IP "\fR.ge.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is after or equal to the time represented by +the +.IR date_time +component of the option-argument. +.IP "\fR.gt.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is after the time represented by the +.IR date_time +component of the option-argument. +.IP "\fR.lt.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is before the time represented by the +.IR date_time +component of the option-argument. +.IP "\fR.le.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is before or equal to the time represented +by the +.IR date_time +component of the option-argument. +.IP "\fR.ne.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is not equal to the time represented by the +.IR date_time +component of the option-argument. +.P +The +.IR qselect +utility shall accept the defined character strings for the +.IR op +component of the option-argument. +.RE +.IP "\fB\(miA\ \fIaccount_string\fR" 10 +.br +Restrict selection to the batch jobs charging a specified account. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Account_Name +attribute of the batch job matches the value of the +.IR account_string +option-argument. +.P +The syntax of the +.IR account_string +option-argument is unspecified. +.RE +.IP "\fB\(mic\ [\fIop\fB]\fIinterval\fR" 10 +.br +Restrict selection to batch jobs within a range of checkpoint +intervals. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Checkpoint +attribute relates to the value of the +.IR interval +component of the option-argument in the manner indicated by the value +of the +.IR op +component of the option-argument. +.P +If the +.IR op +component of the option-argument is omitted, the +.IR qselect +utility shall select batch jobs for which the value of the +.IR Checkpoint +attribute is equal to the value of the +.IR interval +component of the option-argument. +.P +When comparing checkpoint intervals, the +.IR qselect +utility shall use the following definitions for the +.IR op +component of the option-argument: +.IP "\fR.eq.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job equals the value of the +.IR interval +component of the option-argument. +.IP "\fR.ge.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job is greater than or equal to the value of the +.IR interval +component option-argument. +.IP "\fR.gt.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job is greater than the value of the +.IR interval +component option-argument. +.IP "\fR.lt.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job is less than the value of the +.IR interval +component option-argument. +.IP "\fR.le.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job is less than or equal to the value of the +.IR interval +component option-argument. +.IP "\fR.ne.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job does not equal the value of the +.IR interval +component option-argument. +.P +The +.IR qselect +utility shall accept the defined character strings for the +.IR op +component of the option-argument. +.P +The ordering relationship for the values of the interval +option-argument is defined to be: +.sp +.RS 4 +.nf +\fB +\&`n' .gt. `s' .gt. `c=\fIminutes\fR' .ge. `c' +.fi \fR +.P +.RE +When comparing +.IR Checkpoint +attributes with an interval having the value of the single character +.BR 'u' , +only equality or inequality are valid comparisons. +.RE +.IP "\fB\(mih\ \fIhold_list\fR" 10 +Restrict selection to batch jobs that have a specific type of hold. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Hold_Types +attribute matches the value of the +.IR hold_list +option-argument. +.P +The +.IR qselect +.BR \(mih +option shall accept a value for the +.IR hold_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qselect +utility shall accept a value for the +.IR hold_list +option-argument that is a string of one or more of the characters +.BR 'u' , +.BR 's' , +or +.BR 'o' , +or the single character +.BR 'n' . +.P +Each unique character in the +.IR hold_list +option-argument of the +.IR qselect +utility is defined as follows, each representing a different hold type: +.IP "\fRu\fP" 6 +USER +.IP "\fRs\fP" 6 +SYSTEM +.IP "\fRo\fP" 6 +OPERATOR +.P +If any of these characters are duplicated in the +.IR hold_list +option-argument, the duplicates shall be ignored. +.P +The +.IR qselect +utility shall consider it an error if any hold type other than +.BR 'n' +is combined with hold type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'u' , +.BR 's' , +.BR 'o' , +or +.BR 'n' +within the +.IR hold_list +option-argument. The +.IR qselect +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. +.RE +.IP "\fB\(mil\ \fIresource_list\fR" 10 +.br +Restrict selection to batch jobs with specified resource limits and +attributes. +.RS 10 +.P +The +.IR qselect +utility shall accept a +.IR resource_list +option-argument with the following syntax: +.sp +.RS 4 +.nf +\fB +\fIresource_name op value \fB[\fR,,\fIresource_name op value\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +When comparing resource values, the +.IR qselect +utility shall use the following definitions for the +.IR op +component of the option-argument: +.IP "\fR.eq.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job equals the value of the value component of +the option-argument. +.IP "\fR.ge.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job is greater than or equal to the value of the +.IR value +component of the option-argument. +.IP "\fR.gt.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job is greater than the value of the value +component of the option-argument. +.IP "\fR.lt.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job is less than the value of the value +component of the option-argument. +.IP "\fR.ne.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job does not equal the value of the value +component of the option-argument. +.IP "\fR.le.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job is less than or equal to the value of the +.IR value +component of the option-argument. +.P +When comparing the limit of a +.IR Resource_List +attribute with the +.IR value +component of the option-argument, if the limit, the value, or both are +non-numeric, only equality or inequality are valid comparisons. +.P +The +.IR qselect +utility shall select only batch jobs for which the values of the +.IR resource_name s +listed in the +.IR resource_list +option-argument match the corresponding limits of the +.IR Resource_List +attribute of the batch job. +.P +Limits of +.IR resource_name s +present in the +.IR Resource_List +attribute of the batch job that have no corresponding values in the +.IR resource_list +option-argument shall not be considered when selecting batch jobs. +.RE +.IP "\fB\(miN\ \fIname\fR" 10 +Restrict selection to batch jobs with a specified name. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Job_Name +attribute matches the value of the +.IR name +option-argument. The string specified in the +.IR name +option-argument shall be passed, uninterpreted, to the server. This +allows an implementation to match ``wildcard'' patterns against batch +job names. +.P +An implementation shall describe in the conformance document the format +it supports for matching against the +.IR Job_Name +attribute. +.RE +.IP "\fB\(mip\ [\fIop\fB]\fIpriority\fR" 10 +.br +Restrict selection to batch jobs of the specified priority or range of +priorities. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Priority +attribute of the batch job relates to the value of the +.IR priority +component of the option-argument in the manner indicated by the value +of the +.IR op +component of the option-argument. +.P +If the +.IR op +component of the option-argument is omitted, the +.IR qselect +utility shall select batch jobs for which the value of the +.IR Priority +attribute of the batch job is equal to the value of the +.IR priority +component of the option-argument. +.P +When comparing priority values, the +.IR qselect +utility shall use the following definitions for the +.IR op +component of the option-argument: +.IP "\fR.eq.\fR" 8 +The value of the +.IR Priority +attribute of the batch job equals the value of the +.IR priority +component of the option-argument. +.IP "\fR.ge.\fR" 8 +The value of the +.IR Priority +attribute of the batch job is greater than or equal to the value of the +.IR priority +component option-argument. +.IP "\fR.gt.\fR" 8 +The value of the +.IR Priority +attribute of the batch job is greater than the value of the +.IR priority +component option-argument. +.IP "\fR.lt.\fR" 8 +The value of the +.IR Priority +attribute of the batch job is less than the value of the +.IR priority +component option-argument. +.IP "\fR.lt.\fR" 8 +The value of the +.IR Priority +attribute of the batch job is less than or equal to the value of the +.IR priority +component option-argument. +.IP "\fR.ne.\fR" 8 +The value of the +.IR Priority +attribute of the batch job does not equal the value of the +.IR priority +component option-argument. +.RE +.IP "\fB\(miq\ \fIdestination\fR" 10 +.br +Restrict selection to the specified batch queue or server, or both. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs that are located at the +destination indicated by the value of the +.IR destination +option-argument. +.P +The destination defines a batch queue, a server, or a batch queue at a +server. +.P +The +.IR qselect +utility shall accept an option-argument for the +.BR \(miq +option that conforms to the syntax for a destination. If the +.BR \(miq +option is not presented to the +.IR qselect +utility, the utility shall select batch jobs from all batch queues at +the default batch server. +.P +If the option-argument describes only a batch queue, the +.IR qselect +utility shall select only batch jobs from the batch queue of the +specified name at the default batch server. The means by which +.IR qselect +determines the default server is implementation-defined. +.P +If the option-argument describes only a batch server, the +.IR qselect +utility shall select batch jobs from all the batch queues at that batch +server. +.P +If the option-argument describes both a batch queue and a batch server, +the +.IR qselect +utility shall select only batch jobs from the specified batch queue at +the specified server. +.RE +.IP "\fB\(mir\ \fRy\fR|\fRn\fR" 10 +Restrict selection to batch jobs with the specified rerunability +status. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Rerunable +attribute of the batch job matches the value of the option-argument. +.P +The +.IR qselect +utility shall accept a value for the option-argument that consists of +either the single character +.BR 'y' +or the single character +.BR 'n' . +The character +.BR 'y' +represents the value TRUE, and the character +.BR 'n' +represents the value FALSE. +.RE +.IP "\fB\(mis\ \fIstates\fR" 10 +Restrict selection to batch jobs in the specified states. +.RS 10 +.P +The +.IR qselect +utility shall accept an option-argument that consists of any +combination of the characters +.BR 'e' , +.BR 'q' , +.BR 'r' , +.BR 'w' , +.BR 'h' , +and +.BR 't' . +.P +Conforming applications shall not repeat any character in the +option-argument. The +.IR qselect +utility shall permit the repetition of characters in the +option-argument, but shall not assign additional meaning to repeated +characters. +.P +The +.IR qselect +utility shall interpret the characters in the +.IR states +option-argument as follows: +.IP "\fRe\fR" 6 +Represents the EXITING state. +.IP "\fRq\fR" 6 +Represents the QUEUED state. +.IP "\fRr\fR" 6 +Represents the RUNNING state. +.IP "\fRt\fR" 6 +Represents the TRANSITING state. +.IP "\fRh\fR" 6 +Represents the HELD state. +.IP "\fRw\fR" 6 +Represents the WAITING state. +.P +For each character in the +.IR states +option-argument, the +.IR qselect +utility shall select batch jobs in the corresponding state. +.RE +.IP "\fB\(miu\ \fIuser_list\fR" 10 +Restrict selection to batch jobs owned by the specified user names. +.RS 10 +.P +The +.IR qselect +utility shall select only the batch jobs of those users specified in +the +.IR user_list +option-argument. +.P +The +.IR qselect +utility shall accept a +.IR user_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +\fIusername\fB[\fR@\fIhost\fB][\fR,,\fIusername\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +The +.IR qselect +utility shall accept only one user name that is missing a corresponding +host name. The +.IR qselect +utility shall accept only one user name per named host. +.RE +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qselect : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.IP "\fITZ\fP" 10 +Determine the timezone used to interpret the +.IR date-time +option-argument. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR qselect +utility shall write zero or more batch +.IR job_identifier s +to standard output. +.P +The +.IR qselect +utility shall separate the batch +.IR job_identifier s +written to standard output by white space. +.P +The +.IR qselect +utility shall write batch +.IR job_identifier s +in the following format: +.sp +.RS 4 +.nf +\fB +\fIsequence_number.server_name\fR@\fIserver\fR +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The following example shows how a user might use the +.IR qselect +utility in conjunction with the +.IR qdel +utility to delete all of his or her jobs in the queued state without +affecting any jobs that are already running: +.sp +.RS 4 +.nf +\fB +qdel $(qselect \(mis q) +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +qselect \(mis q || xargs qdel +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR qselect +utility allows users to acquire a list of job identifiers that match +user-specified selection criteria. The list of identifiers returned by +the +.IR qselect +utility conforms to the syntax of the batch job identifier list +processed by a utility such as +.IR qmove , +.IR qdel , +and +.IR qrls . +The +.IR qselect +utility is thus a powerful tool for causing another batch system +utility to act upon a set of jobs that match a list of selection +criteria. +.P +The options of the +.IR qselect +utility let the user apply a number of useful filters for selecting +jobs. Each option further restricts the selection of jobs. Many of the +selection options allow the specification of a relational operator. The +FORTRAN-like syntax of the operator\(emthat is, +.BR \(dq.lt.\(dq \(em\c +was chosen rather than the C-like +.BR \(dq<=\(dq +meta-characters. +.P +The +.BR \(mia +option allows users to restrict the selected jobs to those that have +been submitted (or altered) to wait until a particular time. The time +period is determined by the argument of this option, which includes +both a time and an operator\(emit is thus possible to select jobs +waiting until a specific time, jobs waiting until after a certain time, +or those waiting for a time before the specified time. +.P +The +.BR \(miA +option allows users to restrict the selected jobs to those that have +been submitted (or altered) to charge a particular account. +.P +The +.BR \(mic +option allows users to restrict the selected jobs to those whose +checkpointing interval falls within the specified range. +.P +The +.BR \(mil +option allows users to select those jobs whose resource limits fall +within the range indicated by the value of the option. For example, a +user could select those jobs for which the CPU time limit is greater +than two hours. +.P +The +.BR \(miN +option allows users to select jobs by job name. For instance, all the +parts of a task that have been divided in parallel jobs might be given +the same name, and thus manipulated as a group by means of this +option. +.P +The +.BR \(miq +option allows users to select jobs in a specified queue. +.P +The +.BR \(mir +option allows users to select only those jobs with a specified rerun +criteria. For instance, a user might select only those jobs that can be +rerun for use with the +.IR qrerun +utility. +.P +The +.BR \(mis +option allows users to select only those jobs that are in a certain +state. +.P +The +.BR \(miu +option allows users to select jobs that have been submitted to execute +under a particular account. +.P +The selection criteria provided by the options of the +.IR qselect +utility allow users to select jobs based on all the appropriate +attributes that can be assigned to jobs by the +.IR qsub +utility. +.P +Historically, the +.IR qselect +utility has not been a part of existing practice; it is an improvement +that has been introduced in this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +The +.IR qselect +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqdel\fR\^", +.IR "\fIqrerun\fR\^", +.IR "\fIqrls\fR\^", +.IR "\fIqselect\fR\^", +.IR "\fIqsub\fR\^", +.IR "\fItouch\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qsig.1p b/man-pages-posix-2013-a/man1p/qsig.1p new file mode 100644 index 0000000..e4e77f0 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qsig.1p @@ -0,0 +1,235 @@ +'\" et +.TH QSIG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qsig +\(em signal batch jobs +.SH SYNOPSIS +.LP +.nf +qsig \fB[\fR\(mis \fIsignal\fB] \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +To signal a batch job is to send a signal to the session leader of the +batch job. A batch job is signaled by sending a request to the batch +server that manages the batch job. The +.IR qsig +utility is a user-accessible batch client that requests the signaling +of a batch job. +.P +The +.IR qsig +utility shall signal those batch jobs for which a batch +.IR job_identifier +is presented to the utility. The +.IR qsig +utility shall not signal any batch jobs whose batch +.IR job_identifier s +are not presented to the utility. +.P +The +.IR qsig +utility shall signal batch jobs in the order in which the corresponding +batch +.IR job_identifier s +are presented to the utility. If the +.IR qsig +utility fails to process a batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qsig +utility shall signal batch jobs by sending a +.IR "Signal Job Request" +to the batch server that manages the batch job. +.P +For each successfully processed batch +.IR job_identifier , +the +.IR qsig +utility shall have received a completion reply to each +.IR "Signal Job Request" +sent to a batch server at the time the utility exits. +.SH OPTIONS +The +.IR qsig +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mis\ \fIsignal\fR" 10 +Define the signal to be sent to the batch job. +.RS 10 +.P +The +.IR qsig +utility shall accept a +.IR signal +option-argument that is either a symbolic signal name or an unsigned +integer signal number (see the POSIX.1\(hy1990 standard, Section 3.3.1.1). The +.IR qsig +utility shall accept signal names for which the SIG prefix has been +omitted. +.P +If the +.IR signal +option-argument is a signal name, the +.IR qsig +utility shall send that name. +.P +If the +.IR signal +option-argument is a number, the +.IR qsig +utility shall send the signal value represented by the number. +.P +If the +.BR \(mis +option is not presented to the +.IR qsig +utility, the utility shall send the signal SIGTERM to each signaled +batch job. +.RE +.SH OPERANDS +The +.IR qsig +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qsig : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +An implementation of the +.IR qsig +utility may write informative messages to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qsig +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qsig +utility waits to output the diagnostic message while attempting to +locate the batch job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qsig +utility allows users to signal batch jobs. +.P +A user may be unable to signal a batch job with the +.IR kill +utility of the operating system for a number of reasons. First, the +process ID of the batch job may be unknown to the user. Second, the +processes of the batch job may be on a remote node. However, by virtue +of communication between batch nodes, the +.IR qsig +utility can arrange for the signaling of a process. +.P +Because a batch job that is not running cannot be signaled, and because +the signal may not terminate the batch job, the +.IR qsig +utility is not a substitute for the +.IR qdel +utility. +.P +The options of the +.IR qsig +utility allow the user to specify the signal that is to be sent to the +batch job. +.P +The +.BR \(mis +option allows users to specify a signal by name or by number, and thus +override the default signal. The POSIX.1\(hy1990 standard defines signals by both name and +number. +.P +The +.IR qsig +utility is a new utility, \fIvis-a-vis\fP existing practice; it has +been defined in this volume of POSIX.1\(hy2008 in response to user-perceived shortcomings in +existing practice. +.SH "FUTURE DIRECTIONS" +The +.IR qsig +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIkill\fR\^", +.IR "\fIqdel\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qstat.1p b/man-pages-posix-2013-a/man1p/qstat.1p new file mode 100644 index 0000000..be3a39e --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qstat.1p @@ -0,0 +1,404 @@ +'\" et +.TH QSTAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qstat +\(em show status of batch jobs +.SH SYNOPSIS +.LP +.nf +qstat \fB[\fR\(mif\fB] \fIjob_identifier\fR... +.P +qstat \(miQ \fB[\fR\(mif\fB] \fIdestination\fR... +.P +qstat \(miB \fB[\fR\(mif\fB] \fIserver_name\fR... +.fi +.SH DESCRIPTION +The status of a batch job, batch queue, or batch server is obtained by +a request to the server. The +.IR qstat +utility is a user-accessible batch client that requests the status of +one or more batch jobs, batch queues, or servers, and writes the status +information to standard output. +.P +For each successfully processed batch +.IR job_identifier , +the +.IR qstat +utility shall display information about the corresponding batch job. +.P +For each successfully processed destination, the +.IR qstat +utility shall display information about the corresponding batch queue. +.P +For each successfully processed server name, the +.IR qstat +utility shall display information about the corresponding server. +.P +The +.IR qstat +utility shall acquire batch job status information by sending a +.IR "Job Status Request" +to a batch server. The +.IR qstat +utility shall acquire batch queue status information by sending a +.IR "Queue Status Request" +to a batch server. The +.IR qstat +utility shall acquire server status information by sending a +.IR "Server Status Request" +to a batch server. +.SH OPTIONS +The +.IR qstat +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mif\fR" 10 +Specify that a full display is produced. +.RS 10 +.P +The minimum contents of a full display are specified in the STDOUT +section. +.P +Additional contents and format of a full display are +implementation-defined. +.RE +.IP "\fB\(miQ\fR" 10 +Specify that the operand is a destination. +.RS 10 +.P +The +.IR qstat +utility shall display information about each batch queue at each +destination identified as an operand. +.RE +.IP "\fB\(miB\fR" 10 +Specify that the operand is a server name. +.RS 10 +.P +The +.IR qstat +utility shall display information about each server identified as an +operand. +.RE +.SH OPERANDS +If the +.BR \(miQ +option is presented to the +.IR qstat +utility, the utility shall accept one or more operands that conform to +the syntax for a destination (see +.IR "Section 3.3.2" ", " "Destination"). +.P +If the +.BR \(miB +option is presented to the +.IR qstat +utility, the utility shall accept one or more +.IR server_name +operands. +.P +If neither the +.BR \(miB +nor the +.BR \(miQ +option is presented to the +.IR qstat +utility, the utility shall accept one or more operands that conform to +the syntax for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qstat : +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for selecting the radix character used when +writing floating-point formatted output. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If an operand presented to the +.IR qstat +utility is a batch +.IR job_identifier +and the +.BR \(mif +option is not specified, the +.IR qstat +utility shall display the following items on a single line, in the +stated order, with white space between each item, for each successfully +processed operand: +.IP " *" 4 +The batch +.IR job_identifier +.IP " *" 4 +The batch job name +.IP " *" 4 +The +.IR Job_Owner +attribute +.IP " *" 4 +The CPU time used by the batch job +.IP " *" 4 +The batch job state +.IP " *" 4 +The batch job location +.P +If an operand presented to the +.IR qstat +utility is a batch +.IR job_identifier +and the +.BR \(mif +option is specified, the +.IR qstat +utility shall display the following items for each success fully +processed operand: +.IP " *" 4 +The batch +.IR job_identifier +.IP " *" 4 +The batch job name +.IP " *" 4 +The +.IR Job_Owner +attribute +.IP " *" 4 +The execution user ID +.IP " *" 4 +The CPU time used by the batch job +.IP " *" 4 +The batch job state +.IP " *" 4 +The batch job location +.IP " *" 4 +Additional implementation-defined information, if any, about the +batch job or batch queue +.P +If an operand presented to the +.IR qstat +utility is a destination, the +.BR \(miQ +option is specified, and the +.BR \(mif +option is not specified, the +.IR qstat +utility shall display the following items on a single line, in the +stated order, with white space between each item, for each successfully +processed operand: +.IP " *" 4 +The batch queue name +.IP " *" 4 +The maximum number of batch jobs that shall be run in the batch +queue concurrently +.IP " *" 4 +The total number of batch jobs in the batch queue +.IP " *" 4 +The status of the batch queue +.IP " *" 4 +For each state, the number of batch jobs in that state in the batch +queue and the name of the state +.IP " *" 4 +The type of batch queue (execution or routing) +.P +If the operands presented to the +.IR qstat +utility are destinations, the +.BR \(miQ +option is specified, and the +.BR \(mif +option is specified, the +.IR qstat +utility shall display the following items for each successfully +processed operand: +.IP " *" 4 +The batch queue name +.IP " *" 4 +The maximum number of batch jobs that shall be run in the batch +queue concurrently +.IP " *" 4 +The total number of batch jobs in the batch queue +.IP " *" 4 +The status of the batch queue +.IP " *" 4 +For each state, the number of batch jobs in that state in the batch +queue and the name of the state +.IP " *" 4 +The type of batch queue (execution or routing) +.IP " *" 4 +Additional implementation-defined information, if any, about +the batch queue +.P +If the operands presented to the +.IR qstat +utility are batch server names, the +.BR \(miB +option is specified, and the +.BR \(mif +option is not specified, the +.IR qstat +utility shall display the following items on a single line, in the +stated order, with white space between each item, for each successfully +processed operand: +.IP " *" 4 +The batch server name +.IP " *" 4 +The maximum number of batch jobs that shall be run in the batch +queue concurrently +.IP " *" 4 +The total number of batch jobs managed by the batch server +.IP " *" 4 +The status of the batch server +.IP " *" 4 +For each state, the number of batch jobs in that state and the name of +the state +.P +If the operands presented to the +.IR qstat +utility are server names, the +.BR \(miB +option is specified, and the +.BR \(mif +option is specified, the +.IR qstat +utility shall display the following items for each successfully +processed operand: +.IP " *" 4 +The server name +.IP " *" 4 +The maximum number of batch jobs that shall be run in the batch +queue concurrently +.IP " *" 4 +The total number of batch jobs managed by the server +.IP " *" 4 +The status of the server +.IP " *" 4 +For each state, the number of batch jobs in that state and the name of +the state +.IP " *" 4 +Additional implementation-defined information, if any, about the server +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qstat +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qstat +utility waits to output the diagnostic message while attempting to +locate the batch job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qstat +utility allows users to display the status of jobs and list the +batch jobs in queues. +.P +The operands of the +.IR qstat +utility may be either job identifiers, queues (specified as destination +identifiers), or batch server names. The +.BR \(miQ +and +.BR \(miB +options, or absence thereof, indicate the nature of the operands. +.P +The other options of the +.IR qstat +utility allow the user to control the amount of information displayed +and the format in which it is displayed. Should a user wish to display +the status of a set of jobs that match a selection criteria, the +.IR qselect +utility may be used to acquire such a list. +.P +The +.BR \(mif +option allows users to request a ``full'' display in an +implementation-defined format. +.P +Historically, the +.IR qstat +utility has been a part of the NQS and its derivatives, the existing +practice on which it is based. +.SH "FUTURE DIRECTIONS" +The +.IR qstat +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/qsub.1p b/man-pages-posix-2013-a/man1p/qsub.1p new file mode 100644 index 0000000..daa7898 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/qsub.1p @@ -0,0 +1,1472 @@ +'\" et +.TH QSUB "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qsub +\(em submit a script +.SH SYNOPSIS +.LP +.nf +qsub \fB[\fR\(mia \fIdate_time\fB] [\fR\(miA \fIaccount_string\fB] [\fR\(mic \fIinterval\fB] + [\fR\(miC \fIdirective_prefix\fB] [\fR\(mie \fIpath_name\fB] [\fR\(mih\fB] [\fR\(mij \fIjoin_list\fB] + [\fR\(mik \fIkeep_list\fB] [\fR\(mim \fImail_options\fB] [\fR\(miM \fImail_list\fB] [\fR\(miN \fIname\fB] + [\fR\(mio \fIpath_name\fB] [\fR\(mip \fIpriority\fB] [\fR\(miq \fIdestination\fB] [\fR\(mir \fIy\fR|\fIn\fB] + [\fR\(miS \fIpath_name_list\fB] [\fR\(miu \fIuser_list\fB] [\fR\(miv \fIvariable_list\fB] [\fR\(miV\fB] + [\fR\(miz\fB] [\fIscript\fB]\fR +.fi +.SH DESCRIPTION +To submit a script is to create a batch job that executes the script. A +script is submitted by a request to a batch server. The +.IR qsub +utility is a user-accessible batch client that submits a script. +.P +Upon successful completion, the +.IR qsub +utility shall have created a batch job that will execute the submitted +script. +.P +The +.IR qsub +utility shall submit a script by sending a +.IR "Queue Job Request" +to a batch server. +.P +The +.IR qsub +utility shall place the value of the following environment variables in +the +.IR Variable_List +attribute of the batch job: +.IR HOME , +.IR LANG , +.IR LOGNAME , +.IR PATH , +.IR MAIL , +.IR SHELL , +and +.IR TZ . +The name of the environment variable shall be the current name prefixed +with the string PBS_O_. +.TP 10 +.BR Note: +If the current value of the +.IR HOME +variable in the environment space of the +.IR qsub +utility is +.BR /aa/bb/cc , +then +.IR qsub +shall place +.IR PBS_O_HOME =\c +.BR /aa/bb/cc +in the +.IR Variable_List +attribute of the batch job. +.P +.P +In addition to the variables described above, the +.IR qsub +utility shall add the following variables with the indicated values to +the variable list: +.IP "\fIPBS_O_WORKDIR\fP" 14 +The absolute path of the current working directory of the +.IR qsub +utility process. +.IP "\fIPBS_O_HOST\fP" 14 +The name of the host on which the +.IR qsub +utility is running. +.SH OPTIONS +The +.IR qsub +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mia\ \fIdate_time\fR" 10 +Define the time at which a batch job becomes eligible for execution. +.RS 10 +.P +The +.IR qsub +utility shall accept an option-argument that conforms to the syntax of +the +.IR time +operand of the +.IR touch +utility. +.br +.sp +.ce 1 +\fBTable 4-19: Environment Variable Values (Utilities)\fR +.TS +center box tab(!); +cB | cB +lI | lI. +Variable Name!Value at qsub Time +_ +PBS_O_HOME!HOME +PBS_O_HOST!\fRClient host name\fP +PBS_O_LANG!LANG +PBS_O_LOGNAME!LOGNAME +PBS_O_PATH!PATH +PBS_O_MAIL!MAIL +PBS_O_SHELL!SHELL +PBS_O_TZ!TZ +PBS_O_WORKDIR!\fRCurrent working directory\fP +.TE +.TP 10 +.BR Note: +The server that initiates execution of the batch job will add other +variables to the batch job's environment; see +.IR "Section 3.2.2.1" ", " "Batch Job Execution". +.P +.P +The +.IR qsub +utility shall set the +.IR Execution_Time +attribute of the batch job to the number of seconds since the Epoch +that is equivalent to the local time expressed by the value of the +.IR date_time +option-argument. The Epoch is defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.150" ", " "Epoch". +.P +If the +.BR \(mia +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Execution_Time +attribute of the batch job to a time (number of seconds since the +Epoch) that is earlier than the time at which the utility exits. +.RE +.IP "\fB\(miA\ \fIaccount_string\fR" 10 +.br +Define the account to which the resource consumption of the batch job +should be charged. +.RS 10 +.P +The syntax of the +.IR account_string +option-argument is unspecified. +.P +The +.IR qsub +utility shall set the +.IR Account_Name +attribute of the batch job to the value of the +.IR account_string +option-argument. +.P +If the +.BR \(miA +option is not presented to the +.IR qsub +utility, the utility shall omit the +.IR Account_Name +attribute from the attributes of the batch job. +.RE +.IP "\fB\(mic\ \fIinterval\fR" 10 +Define whether the batch job should be checkpointed, and if so, how +often. +.RS 10 +.P +The +.IR qsub +utility shall accept a value for the interval option-argument that is +one of the following: +.IP "\fRn\fR" 10 +No checkpointing shall be performed on the batch job +(NO_CHECKPOINT). +.IP "\fRs\fR" 10 +Checkpointing shall be performed only when the batch server is shut +down (CHECKPOINT_AT_SHUTDOWN). +.IP "\fRc\fR" 10 +Automatic periodic checkpointing shall be performed at the +.IR Minimum_Cpu_Interval +attribute of the batch queue, in units of CPU minutes +(CHECKPOINT_AT_MIN_CPU_INTERVAL). +.IP "\fRc\fR=\fIminutes\fR" 10 +Automatic periodic checkpointing shall be performed every +.IR minutes +of CPU time, or every +.IR Minimum_Cpu_Interval +minutes, whichever is greater. The +.IR minutes +argument shall conform to the syntax for unsigned integers and shall be +greater than zero. +.P +The +.IR qsub +utility shall set the +.IR Checkpoint +attribute of the batch job to the value of the +.IR interval +option-argument. +.P +If the +.BR \(mic +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Checkpoint +attribute of the batch job to the single character +.BR 'u' +(CHECKPOINT_UNSPECIFIED). +.RE +.IP "\fB\(miC\ \fIdirective_prefix\fR" 10 +.br +Define the prefix that declares a directive to the +.IR qsub +utility within the script. +.RS 10 +.P +The +.IR directive_prefix +is not a batch job attribute; it affects the behavior of the +.IR qsub +utility. +.P +If the +.BR \(miC +option is presented to the +.IR qsub +utility, and the value of the +.IR directive_prefix +option-argument is the null string, the utility shall not scan the +script file for directives. If the +.BR \(miC +option is not presented to the +.IR qsub +utility, then the value of the +.IR PBS_DPREFIX +environment variable is used. If the environment variable is not +defined, then #PBS encoded in the portable character set is the +default. +.RE +.IP "\fB\(mie\ \fIpath_name\fR" 10 +.br +Define the path to be used for the standard error stream of the batch +job. +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR path_name +option-argument which can be preceded by a host name element of the +form +.IR hostname :. +.P +If the +.IR path_name +option-argument constitutes an absolute pathname, the +.IR qsub +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the +.IR path_name +option-argument. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and no host name +element is specified, the +.IR qsub +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the absolute pathname +derived by expanding the +.IR path_name +option-argument relative to the current directory of the process +executing +.IR qsub . +.P +If the +.IR path_name +option-argument constitutes a relative pathname and a host name +element is specified, the +.IR qsub +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the +.IR path_name +option-argument without expansion. The host name element shall be +included. +.P +If the +.IR path_name +option-argument does not include a host name element, the +.IR qsub +utility shall prefix the pathname with +.IR hostname :, +where +.IR hostname +is the name of the host upon which the +.IR qsub +utility is being executed. +.P +If the +.BR \(mie +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Error_Path +attribute of the batch job to the host name and path of the current +directory of the submitting process and the default filename. +.P +The default filename for standard error has the following format: +.sp +.RS 4 +.nf +\fB +\fIjob_name\fR.e\fIsequence_number\fR +.fi \fR +.P +.RE +.RE +.IP "\fB\(mih\fR" 10 +Specify that a USER hold is applied to the batch job. +.RS 10 +.P +The +.IR qsub +utility shall set the value of the +.IR Hold_Types +attribute of the batch job to the value USER. +.P +If the +.BR \(mih +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Hold_Types +attribute of the batch job to the value NO_HOLD. +.RE +.IP "\fB\(mij\ \fIjoin_list\fR" 10 +Define which streams of the batch job are to be merged. The +.IR qsub +.BR \(mij +option shall accept a value for the +.IR join_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR join_list +option-argument that consists of one or more of the characters +.BR 'e' +and +.BR 'o' , +or the single character +.BR 'n' . +.P +All of the other batch job output streams specified will be merged into +the output stream represented by the character listed first in the +.IR join_list +option-argument. +.P +For each unique character in the +.IR join_list +option-argument, the +.IR qsub +utility shall add a value to the +.IR Join_Path +attribute of the batch job as follows, each representing a different +batch job stream to join: +.IP "\fRe\fR" 6 +The standard error of the batch job (JOIN_STD_ERROR). +.IP "\fRo\fR" 6 +The standard output of the batch job (JOIN_STD_OUTPUT). +.P +An existing +.IR Join_Path +attribute can be cleared by the following join type: +.IP "\fRn\fR" 6 +NO_JOIN +.P +If +.BR 'n' +is specified, then no files are joined. The +.IR qsub +utility shall consider it an error if any join type other than +.BR 'n' +is combined with join type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'o' , +or +.BR 'n' +within the +.IR join_list +option-argument. The +.IR qsub +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other join types. The conformance document +for an implementation shall describe any additional batch job streams, +how they are specified, their internal behavior, and how they affect +the behavior of the utility. +.P +If the +.BR \(mij +option is not presented to the +.IR qsub +utility, the utility shall set the value of the +.IR Join_Path +attribute of the batch job to NO_JOIN. +.RE +.IP "\fB\(mik\ \fIkeep_list\fR" 10 +Define which output of the batch job to retain on the execution host. +.RS 10 +.P +The +.IR qsub +.BR \(mik +option shall accept a value for the +.IR keep_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qsub +utility shall accept a +.IR keep_list +option-argument that consists of one or more of the characters +.BR 'e' +and +.BR 'o' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR keep_list +option-argument, the +.IR qsub +utility shall add a value to the +.IR Keep_Files +attribute of the batch job as follows, each representing a different +batch job stream to keep: +.IP "\fRe\fR" 6 +The standard error of the batch job (KEEP_STD_ERROR). +.IP "\fRo\fR" 6 +The standard output of the batch job (KEEP_STD_OUTPUT). +.P +If both +.BR 'e' +and +.BR 'o' +are specified, then both files are retained. An existing +.IR Keep_Files +attribute can be cleared by the following keep type: +.IP "\fRn\fR" 6 +NO_KEEP +.P +If +.BR 'n' +is specified, then no files are retained. The +.IR qsub +utility shall consider it an error if any keep type other than +.BR 'n' +is combined with keep type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'o' , +or +.BR 'n' +within the +.IR keep_list +option-argument. The +.IR qsub +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other keep types. The conformance document +for an implementation shall describe any additional keep types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. If the +.BR \(mik +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Keep_Files +attribute of the batch job to the value NO_KEEP. +.RE +.IP "\fB\(mim\ \fImail_options\fR" 10 +.br +Define the points in the execution of the batch job at which the batch +server that manages the batch job shall send mail about a change in the +state of the batch job. +.RS 10 +.P +The +.IR qsub +.BR \(mim +option shall accept a value for the +.IR mail_options +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qsub +utility shall accept a value for the +.IR mail_options +option-argument that is a string of one or more of the characters +.BR 'e' , +.BR 'b' , +and +.BR 'a' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR mail_options +option-argument, the +.IR qsub +utility shall add a value to the +.IR Mail_Users +attribute of the batch job as follows, each representing a different +time during the life of a batch job at which to send mail: +.IP "\fRe\fR" 6 +MAIL_AT_EXIT +.IP "\fRb\fR" 6 +MAIL_AT_BEGINNING +.IP "\fRa\fR" 6 +MAIL_AT_ABORT +.P +If any of these characters are duplicated in the +.IR mail_options +option-argument, the duplicates shall be ignored. +.P +An existing +.IR Mail_Points +attribute can be cleared by the following mail type: +.IP "\fRn\fR" 6 +NO_MAIL +.P +If +.BR 'n' +is specified, then mail is not sent. The +.IR qsub +utility shall consider it an error if any mail type other than +.BR 'n' +is combined with mail type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'b' , +.BR 'a' , +or +.BR 'n' +within the +.IR mail_options +option-argument. +.P +The +.IR qsub +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. An implementation may +define other mail types. The conformance document for an implementation +shall describe any additional mail types, how they are specified, their +internal behavior, and how they affect the behavior of the utility. +.P +If the +.BR \(mim +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Mail_Points +attribute to the value MAIL_AT_ABORT. +.RE +.IP "\fB\(miM\ \fImail_list\fR" 10 +Define the list of users to which a batch server that executes the +batch job shall send mail, if the server sends mail about the batch +job. +.RS 10 +.P +The syntax of the +.IR mail_list +option-argument is unspecified. +.P +If the implementation of the +.IR qsub +utility uses a name service to locate users, the utility should accept +the syntax used by the name service. +.P +If the implementation of the +.IR qsub +utility does not use a name service to locate users, the implementation +should accept the following syntax for user names: +.sp +.RS 4 +.nf +\fB +\fImail_address\fB[\fR,,\fImail_address\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +The interpretation of +.IR mail_address +is implementation-defined. +.P +The +.IR qsub +utility shall set the +.IR Mail_Users +attribute of the batch job to the value of the +.IR mail_list +option-argument. +.P +If the +.BR \(miM +option is not presented to the +.IR qsub +utility, the utility shall place only the user name and host name for +the current process in the +.IR Mail_Users +attribute of the batch job. +.RE +.IP "\fB\(miN\ \fIname\fR" 10 +Define the name of the batch job. +.RS 10 +.P +The +.IR qsub +.BR \(miN +option shall accept a value for the +.IR name +option-argument that is a string of up to 15 alphanumeric characters in +the portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set") +where the first character is alphabetic. +.P +The +.IR qsub +utility shall set the value of the +.IR Job_Name +attribute of the batch job to the value of the +.IR name +option-argument. +.P +If the +.BR \(miN +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Job_Name +attribute of the batch job to the name of the +.IR script +argument from which the directory specification if any, has been +removed. +.P +If the +.BR \(miN +option is not presented to the +.IR qsub +utility, and the script is read from standard input, the utility shall +set the +.IR Job_Name +attribute of the batch job to the value STDIN. +.RE +.IP "\fB\(mio\ \fIpath_name\fR" 10 +.br +Define the path for the standard output of the batch job. +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR path_name +option-argument that conforms to the syntax of the +.IR path_name +element defined in the System Interfaces volume of POSIX.1\(hy2008, which can be preceded by a host name +element of the form +.IR hostname :. +.P +If the +.IR path_name +option-argument constitutes an absolute pathname, the +.IR qsub +utility shall set the +.IR Output_Path +attribute of the batch job to the value of the +.IR path_name +option-argument without expansion. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and no host name +element is specified, the +.IR qsub +utility shall set the +.IR Output_Path +attribute of the batch job to the pathname derived by expanding the +value of the +.IR path_name +option-argument relative to the current directory of the process +executing the +.IR qsub . +.P +If the +.IR path_name +option-argument constitutes a relative pathname and a host name +element is specified, the +.IR qsub +utility shall set the +.IR Output_Path +attribute of the batch job to the value of the +.IR path_name +option-argument without expansion. +.P +If the +.IR path_name +option-argument does not specify a host name element, the +.IR qsub +utility shall prefix the pathname with +.IR hostname :, +where +.IR hostname +is the name of the host upon which the +.IR qsub +utility is executing. +.P +If the +.BR \(mio +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Output_Path +attribute of the batch job to the host name and path of the current +directory of the submitting process and the default filename. +.P +The default filename for standard output has the following format: +.sp +.RS 4 +.nf +\fB +\fIjob_name\fR.o\fIsequence_number\fR +.fi \fR +.P +.RE +.RE +.IP "\fB\(mip\ \fIpriority\fR" 10 +Define the priority the batch job should have relative to other batch +jobs owned by the batch server. +.RS 10 +.P +The +.IR qsub +utility shall set the +.IR Priority +attribute of the batch job to the value of the +.IR priority +option-argument. +.P +If the +.BR \(mip +option is not presented to the +.IR qsub +utility, the value of the +.IR Priority +attribute is implementation-defined. +.P +The +.IR qsub +utility shall accept a value for the +.IR priority +option-argument that conforms to the syntax for signed decimal +integers, and which is not less than \(mi1\|024 and not greater than +1\|023. +.RE +.IP "\fB\(miq\ \fIdestination\fR" 10 +.br +Define the destination of the batch job. +.RS 10 +.P +The destination is not a batch job attribute; it determines the batch +server, and possibly the batch queue, to which the +.IR qsub +utility batch queues the batch job. +.P +The +.IR qsub +utility shall submit the script to the batch server named by the +.IR destination +option-argument or the server that owns the batch queue named in the +.IR destination +option-argument. +.P +The +.IR qsub +utility shall accept an option-argument for the +.BR \(miq +option that conforms to the syntax for a destination (see +.IR "Section 3.3.2" ", " "Destination"). +.P +If the +.BR \(miq +option is not presented to the +.IR qsub +utility, the +.IR qsub +utility shall submit the batch job to the default destination. The +mechanism for determining the default destination is +implementation-defined. +.RE +.IP "\fB\(mir\ \fIy\fR|\fIn\fR" 10 +Define whether the batch job is rerunnable. +.RS 10 +.P +If the value of the option-argument is +.IR y , +the +.IR qsub +utility shall set the +.IR Rerunable +attribute of the batch job to TRUE. +.P +If the value of the option-argument is +.IR n , +the +.IR qsub +utility shall set the +.IR Rerunable +attribute of the batch job to FALSE. +.P +If the +.BR \(mir +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Rerunable +attribute of the batch job to TRUE. +.RE +.IP "\fB\(miS\ \fIpath_name_list\fR" 10 +.br +Define the pathname to the shell under which the batch job is to +execute. +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR path_name_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +\fIpathname\fB[\fR@\fIhost\fB][\fR,,\fIpathname\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +The +.IR qsub +utility shall allow only one pathname for a given host name. The +.IR qsub +utility shall allow only one pathname that is missing a corresponding +host name. +.P +The +.IR qsub +utility shall add a value to the +.IR Shell_Path_List +attribute of the batch job for each entry in the +.IR path_name_list +option-argument. +.P +If the +.BR \(miS +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Shell_Path_List +attribute of the batch job to the null string. +.P +The conformance document for an implementation shall describe the +mechanism used to set the default shell and determine the current value +of the default shell. An implementation shall provide a means for the +installation to set the default shell to the login shell of the user +under which the batch job is to execute. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(miu\ \fIuser_list\fR" 10 +Define the user name under which the batch job is to execute. +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR user_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +\fIusername\fB[\fR@\fIhost\fB][\fR,,\fIusername\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +The +.IR qsub +utility shall accept only one user name that is missing a corresponding +host name. The +.IR qsub +utility shall accept only one user name per named host. +.P +The +.IR qsub +utility shall add a value to the +.IR User_List +attribute of the batch job for each entry in the +.IR user_list +option-argument. +.P +If the +.BR \(miu +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR User_List +attribute of the batch job to the user name from which the utility is +executing. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(miv\ \fIvariable_list\fR" 10 +.br +Add to the list of variables that are exported to the session leader of +the batch job. +.RS 10 +.P +A +.IR variable_list +is a set of strings of either the form <\c +.IR variable > +or <\c +.IR variable =\c +.IR value >, +delimited by + +characters. +.P +If the +.BR \(miv +option is presented to the +.IR qsub +utility, the utility shall also add, to the environment +.IR Variable_List +attribute of the batch job, every variable named in the environment +.IR variable_list +option-argument and, optionally, values of specified variables. +.P +If a value is not provided on the command line, the +.IR qsub +utility shall set the value of each variable in the environment +.IR Variable_List +attribute of the batch job to the value of the corresponding +environment variable for the process in which the utility is executing; +see +.IR "Table 4-19, Environment Variable Values (Utilities)". +.P +A conforming application shall not repeat a variable in the environment +.IR variable_list +option-argument. +.P +The +.IR qsub +utility shall not repeat a variable in the environment +.IR Variable_List +attribute of the batch job. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(miV\fR" 10 +Specify that all of the environment variables of the process are +exported to the context of the batch job. +.RS 10 +.P +The +.IR qsub +utility shall place every environment variable in the process in which +the utility is executing in the list and shall set the value of each +variable in the attribute to the value of that variable in the +process. +.RE +.IP "\fB\(miz\fR" 10 +Specify that the utility does not write the batch +.IR job_identifier +of the created batch job to standard output. +.RS 10 +.P +If the +.BR \(miz +option is presented to the +.IR qsub +utility, the utility shall not write the batch +.IR job_identifier +of the created batch job to standard output. +.P +If the +.BR \(miz +option is not presented to the +.IR qsub +utility, the utility shall write the identifier of the created batch +job to standard output. +.RE +.SH OPERANDS +The +.IR qsub +utility shall accept a +.IR script +operand that indicates the path to the script of the batch job. +.P +If the +.IR script +operand is not presented to the +.IR qsub +utility, or if the operand is the single-character string +.BR '\(mi' , +the utility shall read the script from standard input. +.P +If the script represents a partial path, the +.IR qsub +utility shall expand the path relative to the current directory of the +process executing the utility. +.SH STDIN +The +.IR qsub +utility reads the script of the batch job from standard input if the +script operand is omitted or is the single character +.BR '\(mi' . +.SH "INPUT FILES" +In addition to binding the file indicated by the +.IR script +operand to the batch job, the +.IR qsub +utility reads the script file and acts on directives in the script. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qsub : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.IP "\fIPBS_DPREFIX\fP" 10 +.br +Determine the default prefix for directives within the script. +.IP "\fISHELL\fP" 10 +Determine the pathname of the preferred command language interpreter +of the user. +.IP "\fITZ\fP" 10 +Determine the timezone used to interpret the +.IR date-time +option-argument. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Once created, a batch job exists until it exits, aborts, or is +deleted. +.P +After a batch job is created by the +.IR qsub +utility, batch servers might route, execute, modify, or delete the +batch job. +.SH STDOUT +The +.IR qsub +utility writes the batch +.IR job_identifier +assigned to the batch job to standard output, unless the +.BR \(miz +option is specified. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +.SS "Script Preservation" +.P +The +.IR qsub +utility shall make the script available to the server executing the +batch job in such a way that the server executes the script as it +exists at the time of submission. +.P +The +.IR qsub +utility can send a copy of the script to the server with the +.IR "Queue Job Request" +or store a temporary copy of the script in a location specified to the +server. +.SS "Option Specification" +.P +A script can contain directives to the +.IR qsub +utility. +.P +The +.IR qsub +utility shall scan the lines of the script for directives, skipping +blank lines, until the first line that begins with a string other than +the directive string; if directives occur on subsequent lines, the +utility shall ignore those directives. +.P +Lines are separated by a +. +If the first line of the script begins with +.BR \(dq#!\(dq +or a + +(\c +.BR ':' ), +then it is skipped. The +.IR qsub +utility shall process a line in the script as a directive if and only +if the string of characters from the first non-white-space character on +the line until the first + +or + +on the line match the directive prefix. If a line in the script +contains a directive and the final characters of the line are + +and +, +then the next line shall be interpreted as a continuation of that +directive. +.P +The +.IR qsub +utility shall process the options and option-arguments contained on the +directive prefix line using the same syntax as if the options were +input on the +.IR qsub +utility. +.P +The +.IR qsub +utility shall continue to process a directive prefix line until after a + +is encountered. An implementation may ignore lines which, according to +the syntax of the shell that will interpret the script, are comments. +An implementation shall describe in the conformance document the format +of any shell comments that it will recognize. +.P +If an option is present in both a directive and the arguments to the +.IR qsub +utility, the utility shall ignore the option and the corresponding +option-argument, if any, in the directive. +.P +If an option that is present in the directive is not present in the +arguments to the +.IR qsub +utility, the utility shall process the option and the option-argument, +if any. +.P +In order of preference, the +.IR qsub +utility shall select the directive prefix from one of the following +sources: +.IP " *" 4 +If the +.BR \(miC +option is presented to the utility, the value of the +.IR directive_prefix +option-argument +.IP " *" 4 +If the environment variable +.IR PBS_DPREFIX +is defined, the value of that variable +.IP " *" 4 +The four-character string +.BR \(dq#PBS\(dq +encoded in the portable character set +.P +If the +.BR \(miC +option is present in the script file it shall be ignored. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qsub +utility allows users to create a batch job that will process the script +specified as the operand of the utility. +.P +The options of the +.IR qsub +utility allow users to control many aspects of the queuing and +execution of a batch job. +.P +The +.BR \(mia +option allows users to designate the time after which the batch job +will become eligible to run. By specifying an execution time, users can +take advantage of resources at off-peak hours, synchronize jobs with +chronologically predictable events, and perhaps take advantage of +off-peak pricing of computing time. For these reasons and others, a +timing option is existing practice on the part of almost every batch +system, including NQS. +.P +The +.BR \(miA +option allows users to specify the account that will be charged for the +batch job. Support for account is not mandatory for conforming batch +servers. +.P +The +.BR \(miC +option allows users to prescribe the prefix for directives within the +script file. The default prefix +.BR \(dq#PBS\(dq +may be inappropriate if the script will be interpreted with an +alternate shell, as specified by the +.BR \(miS +option. +.P +The +.BR \(mic +option allows users to establish the checkpointing interval for their +jobs. A checkpointing system, which is not defined by this volume of POSIX.1\(hy2008, allows +recovery of a batch job at the most recent checkpoint in the event of a +crash. Checkpointing is typically used for jobs that consume expensive +computing time or must meet a critical schedule. Users should be +allowed to make the tradeoff between the overhead of checkpointing and +the risk to the timely completion of the batch job; therefore, this volume of POSIX.1\(hy2008 +provides the checkpointing interval option. Support for checkpointing +is optional for batch servers. +.P +The +.BR \(mie +option allows users to redirect the standard error streams of their +jobs to a non-default path. For example, if the submitted script +generally produces a great deal of useless error output, a user might +redirect the standard error output to the null device. Or, if the file +system holding the default location (the home directory of the user) +has too little free space, the user might redirect the standard error +stream to a file in another file system. +.P +The +.BR \(mih +option allows users to create a batch job that is held until explicitly +released. The ability to create a held job is useful when some external +event must complete before the batch job can execute. For example, the +user might submit a held job and release it when the system load has +dropped. +.P +The +.BR \(mij +option allows users to merge the standard error of a batch job into its +standard output stream, which has the advantage of showing the +sequential relationship between output and error messages. +.P +The +.BR \(mim +option allows users to designate those points in the execution of a +batch job at which mail will be sent to the submitting user, or to the +account(s) indicated by the +.BR \(miM +option. By requesting mail notification at points of interest in the +life of a job, the submitting user, or other designated users, can +track the progress of a batch job. +.P +The +.BR \(miN +option allows users to associate a name with the batch job. The job +name in no way affects the processing of the batch job, but rather +serves as a mnemonic handle for users. For example, the batch job name +can help the user distinguish between multiple jobs listed by the +.IR qstat +utility. +.P +The +.BR \(mio +option allows users to redirect the standard output stream. A user +might, for example, wish to redirect to the null device the standard +output stream of a job that produces copious yet superfluous output. +.P +The +.BR \(miP +option allows users to designate the relative priority of a batch job +for selection from a queue. +.P +The +.BR \(miq +option allows users to specify an initial queue for the batch job. If +the user specifies a routing queue, the batch server routes the +batch job to another queue for execution or further routing. If the +user specifies a non-routing queue, the batch server of the queue +eventually executes the batch job. +.P +The +.BR \(mir +option allows users to control whether the submitted job will be rerun +if the controlling batch node fails during execution of the batch job. +The +.BR \(mir +option likewise allows users to indicate whether or not the batch job +is eligible to be rerun by the +.IR qrerun +utility. Some jobs cannot be correctly rerun because of changes they +make in the state of databases or other aspects of their environment. +This volume of POSIX.1\(hy2008 specifies that the default, if the +.BR \(mir +option is not presented to the utility, will be that the batch job +cannot be rerun, since the result of rerunning a non-rerunnable job +might be catastrophic. +.P +The +.BR \(miS +option allows users to specify the program (usually a shell) that will +be invoked to process the script of the batch job. This option has been +modified to allow a list of shell names and locations associated with +different hosts. +.P +The +.BR \(miu +option is useful when the submitting user is authorized to use more +than one account on a given host, in which case the +.BR \(miu +option allows the user to select from among those accounts. The +option-argument is a list of user-host pairs, so that the submitting +user can provide different user identifiers for different nodes in the +event the batch job is routed. The +.BR \(miu +option provides a lot of flexibility to accommodate sites with complex +account structures. Users that have the same user identifier on all the +hosts they are authorized to use will not need to use the +.BR \(miu +option. +.P +The +.BR \(miV +option allows users to export all their current environment variables, +as of the time the batch job is submitted, to the context of the +processes of the batch job. +.P +The +.BR \(miv +option allows users to export specific environment variables from their +current process to the processes of the batch job. +.P +The +.BR \(miz +option allows users to suppress the writing of the batch job identifier +to standard output. The +.BR \(miz +option is an existing NQS practice that has been standardized. +.P +Historically, the +.IR qsub +utility has served the batch job-submission function in the NQS system, +the existing practice on which it is based. Some changes and additions +have been made to the +.IR qsub +utility in this volume of POSIX.1\(hy2008, \fIvis-a-vis\fP NQS, as a result of the growing pool +of experience with distributed batch systems. +.P +The set of features of the +.IR qsub +utility as defined in this volume of POSIX.1\(hy2008 appears to incorporate all the common +existing practice on potentially conforming platforms. +.SH "FUTURE DIRECTIONS" +The +.IR qsub +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqrerun\fR\^", +.IR "\fIqstat\fR\^", +.IR "\fItouch\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.150" ", " "Epoch", +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/read.1p b/man-pages-posix-2013-a/man1p/read.1p new file mode 100644 index 0000000..9896542 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/read.1p @@ -0,0 +1,272 @@ +'\" et +.TH READ "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +read +\(em read a line from standard input +.SH SYNOPSIS +.LP +.nf +read \fB[\fR\(mir\fB] \fIvar\fR... +.fi +.SH DESCRIPTION +The +.IR read +utility shall read a single line from standard input. +.P +By default, unless the +.BR \(mir +option is specified, + +shall act as an escape character. An unescaped + +shall preserve the literal value of the following character, with the +exception of a +. +If a + +follows the +, +the +.IR read +utility shall interpret this as line continuation. The + +and + +shall be removed before splitting the input into fields. All other +unescaped + +characters shall be removed after splitting the input into fields. +.P +If standard input is a terminal device and the invoking shell is +interactive, +.IR read +shall prompt for a continuation line when it reads an input line ending +with a + +, +unless the +.BR \(mir +option is specified. +.P +The terminating + +(if any) shall be removed from the input and the results shall be split +into fields as in the shell for the results of parameter expansion (see +.IR "Section 2.6.5" ", " "Field Splitting"); +the first field shall be assigned to the first variable +.IR var , +the second field to the second variable +.IR var , +and so on. If there are fewer fields than there are +.IR var +operands, the remaining +.IR var s +shall be set to empty strings. If there are fewer +.IR var s +than fields, the last +.IR var +shall be set to a value comprising the following elements: +.IP " *" 4 +The field that corresponds to the last +.IR var +in the normal assignment sequence described above +.IP " *" 4 +The delimiter(s) that follow the field corresponding to the last +.IR var +.IP " *" 4 +The remaining fields and their delimiters, with trailing +.IR IFS +white space ignored +.P +The setting of variables specified by the +.IR var +operands shall affect the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +If it is called in a subshell or separate utility execution +environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(read foo) +nohup read ... +find . \(miexec read ... \e; +.fi \fR +.P +.RE +.P +it shall not affect the shell variables in the caller's environment. +.SH OPTIONS +The +.IR read +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option is supported: +.IP "\fB\(mir\fP" 10 +Do not treat a + +character in any special way. Consider each + +to be part of the input line. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIvar\fR" 10 +The name of an existing or nonexisting shell variable. +.SH STDIN +The standard input shall be a text file. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR read : +.IP "\fIIFS\fP" 10 +Determine the internal field separators used to delimit fields; see +.IR "Section 2.5.3" ", " "Shell Variables". +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPS2\fP" 10 +Provide the prompt string that an interactive shell shall write to +standard error when a line ending with a + + +is read and the +.BR \(mir +option was not specified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic messages and +prompts for continued input. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +End-of-file was detected or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mir +option is included to enable +.IR read +to subsume the purpose of the +.IR line +utility, which is not included in POSIX.1\(hy2008. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +while read \(mir xx yy +do + printf "%s %s\en$yy$xx" +done < \fIinput_file\fR +.fi \fR +.P +.RE +.P +prints a file with the first field of each line moved to the end of the +line. +.SH RATIONALE +The +.IR read +utility historically has been a shell built-in. It was separated off +into its own utility to take advantage of the richer description of +functionality introduced by this volume of POSIX.1\(hy2008. +.P +Since +.IR read +affects the current shell execution environment, +it is generally provided as a shell regular built-in. If it is called +in a subshell or separate utility execution environment, such as one of +the following: +.sp +.RS 4 +.nf +\fB +(read foo) +nohup read ... +find . \(miexec read ... \e; +.fi \fR +.P +.RE +.P +it does not affect the shell variables in the environment of the +caller. +.P +Although the standard input is required to be a text file, and +therefore will always end with a + +(unless it is an empty file), the processing of continuation lines +when the +.BR \(mir +option is not used can result in the input not ending with a +. +This occurs if the last line of the input file ends with a + +. +It is for this reason that ``if any'' is used in ``The terminating + +(if any) shall be removed from the input'' in the description. +It is not a relaxation of the requirement for standard input to +be a text file. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/readonly.1p b/man-pages-posix-2013-a/man1p/readonly.1p new file mode 100644 index 0000000..f00a71a --- /dev/null +++ b/man-pages-posix-2013-a/man1p/readonly.1p @@ -0,0 +1,164 @@ +'\" et +.TH READONLY "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +readonly +\(em set the readonly attribute for variables +.SH SYNOPSIS +.LP +.nf +readonly name\fB[\fR=\fIword\fB]\fR... +.P +readonly\fR \(mip +.fi +.SH DESCRIPTION +The variables whose +.IR name s +are specified shall be given the +.IR readonly +attribute. The values of variables with the +.IR readonly +attribute cannot be changed by subsequent assignment, nor can those +variables be unset by the +.IR unset +utility. If the name of a variable is followed by =\c +.IR word , +then the value of that variable shall be set to +.IR word . +.P +The +.IR readonly +special built-in shall support the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +When +.BR \(mip +is specified, +.IR readonly +writes to the standard output the names and values of all read-only +variables, in the following format: +.sp +.RS 4 +.nf +\fB +"readonly %s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +if +.IR name +is set, and +.sp +.RS 4 +.nf +\fB +"readonly %s\en", <\fIname\fR> +.fi \fR +.P +.RE +.P +if +.IR name +is unset. +.P +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as commands that +achieve the same value and +.IR readonly +attribute-setting results in a shell execution environment in which: +.IP " 1." 4 +Variables with values at the time they were output do not have the +.IR readonly +attribute set. +.IP " 2." 4 +Variables that were unset at the time they were output do not have a +value at the time at which the saved output is reinput to the shell. +.P +When no arguments are given, the results are unspecified. +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +readonly HOME PWD +.fi +.SH "RATIONALE" +Some historical shells preserve the +.IR readonly +attribute across separate invocations. This volume of POSIX.1\(hy2008 allows this behavior, +but does not require it. +.P +The +.BR \(mip +option allows portable access to the values that can be saved and then +later restored using, for example, a +.IR dot +script. Also see the RATIONALE for +.IR "\fIexport\fR\^" +for a description of the no-argument and +.BR \(mip +output cases and a related example. +.P +Read-only functions were considered, but they were omitted as not being +historical practice or particularly useful. Furthermore, functions must +not be read-only across invocations to preclude ``spoofing'' +(spoofing is the term for the practice of creating a program that acts +like a well-known utility with the intent of subverting the real intent +of the user) of administrative or security-relevant (or +security-conscious) shell scripts. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/renice.1p b/man-pages-posix-2013-a/man1p/renice.1p new file mode 100644 index 0000000..993773f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/renice.1p @@ -0,0 +1,280 @@ +'\" et +.TH RENICE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +renice +\(em set nice values of running processes +.SH SYNOPSIS +.LP +.nf +renice \fB[\fR\(mig|\(mip|\(miu\fB] \fR\(min \fIincrement ID\fR... +.fi +.SH DESCRIPTION +The +.IR renice +utility shall request that the nice values (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.240" ", " "Nice Value") +of one or more running processes be changed. By default, the applicable +processes are specified by their process IDs. When a process group is +specified (see +.BR \(mig ), +the request shall apply to all processes in the process group. +.P +The nice value shall be bounded in an implementation-defined manner. +If the requested +.IR increment +would raise or lower the nice value of the executed utility beyond +implementation-defined limits, then the limit whose value was +exceeded shall be used. +.P +When a user is +.IR renice d, +the request applies to all processes whose saved set-user-ID matches +the user ID corresponding to the user. +.P +Regardless of which options are supplied or any other factor, +.IR renice +shall not alter the nice values of any process unless the user +requesting such a change has appropriate privileges to do so for the +specified process. If the user lacks appropriate privileges to perform +the requested action, the utility shall return an error status. +.P +The saved set-user-ID of the user's process shall be checked instead of +its effective user ID when +.IR renice +attempts to determine the user ID of the process in order to determine +whether the user has appropriate privileges. +.SH OPTIONS +The +.IR renice +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(mig\fP" 10 +Interpret the following operands as unsigned decimal integer process +group IDs. +.IP "\fB\(min\ \fIincrement\fR" 10 +Specify how the nice value of the specified process or processes is to +be adjusted. The +.IR increment +option-argument is a positive or negative decimal integer that shall be +used to modify the nice value of the specified process or processes. +.RS 10 +.P +Positive +.IR increment +values shall cause a lower nice value. Negative +.IR increment +values may require appropriate privileges and shall cause a higher +nice value. +.RE +.IP "\fB\(mip\fP" 10 +Interpret the following operands as unsigned decimal integer process +IDs. The +.BR \(mip +option is the default if no options are specified. +.IP "\fB\(miu\fP" 10 +Interpret the following operands as users. If a user exists with a user +name equal to the operand, then the user ID of that user is used in +further processing. Otherwise, if the operand represents an unsigned +decimal integer, it shall be used as the numeric user ID of the user. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIID\fR" 10 +A process ID, process group ID, or user name/user ID, depending on the +option selected. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR renice : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +Adjust the nice value so that process IDs 987 and 32 would have a lower +nice value: +.RS 4 +.sp +.RS 4 +.nf +\fB +renice \(min 5 \(mip 987 32 +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Adjust the nice value so that group IDs 324 and 76 would have a higher +nice value, if the user has appropriate privileges to do so: +.RS 4 +.sp +.RS 4 +.nf +\fB +renice \(min \(mi4 \(mig 324 76 +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Adjust the nice value so that numeric user ID 8 and user +.BR sas +would have a lower nice value: +.RS 4 +.sp +.RS 4 +.nf +\fB +renice \(min 4 \(miu 8 sas +.fi \fR +.P +.RE +.RE +.P +Useful nice value increments on historical systems include 19 or 20 +(the affected processes run only when nothing else in the system +attempts to run) and any negative number (to make processes run +faster). +.SH RATIONALE +The +.IR gid , +.IR pid , +and +.IR user +specifications do not fit either the definition of operand or +option-argument. However, for clarity, they have been included in the +OPTIONS section, rather than the OPERANDS section. +.P +The definition of nice value is not intended to suggest that all +processes in a system have priorities that are comparable. Scheduling +policy extensions such as the realtime priorities in the System Interfaces volume of POSIX.1\(hy2008 make the +notion of a single underlying priority for all scheduling policies +problematic. Some implementations may implement the +.IR nice -related +features to affect all processes on the system, others to affect just +the general time-sharing activities implied by this volume of POSIX.1\(hy2008, and others may +have no effect at all. Because of the use of +``implementation-defined'' in +.IR nice +and +.IR renice , +a wide range of implementation strategies are possible. +.P +Originally, this utility was written in the historical manner, using +the term ``nice value''. This was always a point of concern with users +because it was never intuitively obvious what this meant. With a newer +version of +.IR renice , +which used the term ``system scheduling priority'', it was hoped that +novice users could better understand what this utility was meant to +do. Also, it would be easier to document what the utility was meant to +do. Unfortunately, the addition of the POSIX realtime scheduling +capabilities introduced the concepts of process and thread scheduling +priorities that were totally unaffected by the +.IR nice /\c +.IR renice +utilities or the +\fInice\fR()/\c +\fIsetpriority\fR() +functions. Continuing to use the term ``system scheduling priority'' +would have incorrectly suggested that these utilities and functions +were indeed affecting these realtime priorities. It was decided to +revert to the historical term ``nice value'' to reference this +unrelated process attribute. +.P +Although this utility has use by system administrators (and in fact +appears in the system administration portion of the BSD documentation), +the standard developers considered that it was very useful for +individual end users to control their own processes. +.P +Earlier versions of this standard allowed the following forms in the +SYNOPSIS: +.sp +.RS 4 +.nf +\fB +renice \fInice_value\fB[\fR\(mip\fB] \fIpid\fR...\fB[\fR\(mig \fIgid\fR...\fB][\fR\(mip \fIpid\fR...\fB][\fR\(miu \fIuser\fR...\fB]\fR +renice \fInice_value \(mig \fIgid\fR...\fB[\fR\(mig \fIgid\fR...\fB]\fR\(mip \fIpid\fR...\fB][\fR\(miu \fIuser\fR...\fB]\fR +renice \fInice_value \(miu \fIuser\fR...\fB[\fR\(mig \fIgid\fR...\fB]\fR\(mip \fIpid\fR...\fB][\fR\(miu \fIuser\fR...\fB]\fR +.fi \fR +.P +.RE +.P +These forms are no longer specified by POSIX.1\(hy2008 but may be +present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fInice\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.240" ", " "Nice Value", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/return.1p b/man-pages-posix-2013-a/man1p/return.1p new file mode 100644 index 0000000..ba20275 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/return.1p @@ -0,0 +1,110 @@ +'\" et +.TH RETURN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +return +\(em return from a function or dot script +.SH SYNOPSIS +.LP +.nf +return \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The +.IR return +utility shall cause the shell to stop executing the current function or +.IR dot +script. If the shell is not currently executing a function or +.IR dot +script, the results are unspecified. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The value of the special parameter +.BR '?' +shall be set to +.IR n , +an unsigned decimal integer, or to the exit status of the last command +executed if +.IR n +is not specified. If the value of +.IR n +is greater than 255, the results are undefined. When +.IR return +is executed in a +.IR trap +action, the last command is considered to be the command that +executed immediately preceding the +.IR trap +action. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "EXAMPLES" +None. +.SH "RATIONALE" +The behavior of +.IR return +when not in a function or +.IR dot +script differs between the System V shell and the KornShell. In the +System V shell this is an error, whereas in the KornShell, the effect +is the same as +.IR exit . +.P +The results of returning a number greater than 255 are undefined +because of differing practices in the various historical +implementations. Some shells AND out all but the low-order 8 bits; +others allow larger values, but not of unlimited size. +.P +See the discussion of appropriate exit status values under +.IR "\fIexit\fR\^". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.5" ", " "Function Definition Command", +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIdot\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/rm.1p b/man-pages-posix-2013-a/man1p/rm.1p new file mode 100644 index 0000000..2a8c94d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/rm.1p @@ -0,0 +1,447 @@ +'\" et +.TH RM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rm +\(em remove directory entries +.SH SYNOPSIS +.LP +.nf +rm \fB[\fR\(mifiRr\fB]\fI file\fR... +.fi +.SH DESCRIPTION +The +.IR rm +utility shall remove the directory entry specified by each +.IR file +argument. +.P +If either of the files dot or dot-dot are specified as the basename +portion of an operand (that is, the final pathname component) or if an +operand resolves to the root directory, +.IR rm +shall write a diagnostic message to standard error and do nothing more +with such operands. +.P +For each +.IR file +the following steps shall be taken: +.IP " 1." 4 +If the +.IR file +does not exist: +.RS 4 +.IP " a." 4 +If the +.BR \(mif +option is not specified, +.IR rm +shall write a diagnostic message to standard error. +.IP " b." 4 +Go on to any remaining +.IR files . +.RE +.IP " 2." 4 +If +.IR file +is of type directory, the following steps shall be taken: +.RS 4 +.IP " a." 4 +If neither the +.BR \(miR +option nor the +.BR \(mir +option is specified, +.IR rm +shall write a diagnostic message to standard error, do nothing more +with +.IR file , +and go on to any remaining files. +.IP " b." 4 +If the +.BR \(mif +option is not specified, and either the permissions of +.IR file +do not permit writing and the standard input is a terminal or the +.BR \(mii +option is specified, +.IR rm +shall write a prompt to standard error and read a line from the +standard input. If the response is not affirmative, +.IR rm +shall do nothing more with the current file and go on to any remaining +files. +.IP " c." 4 +For each entry contained in +.IR file , +other than dot or dot-dot, the four steps listed here (1 to 4) shall be +taken with the entry as if it were a +.IR file +operand. The +.IR rm +utility shall not traverse directories by following symbolic links into +other parts of the hierarchy, but shall remove the links themselves. +.IP " d." 4 +If the +.BR \(mii +option is specified, +.IR rm +shall write a prompt to standard error and read a line from the +standard input. If the response is not affirmative, +.IR rm +shall do nothing more with the current file, and go on to any remaining +files. +.RE +.IP " 3." 4 +If +.IR file +is not of type directory, the +.BR \(mif +option is not specified, and either the permissions of +.IR file +do not permit writing and the standard input is a terminal or the +.BR \(mii +option is specified, +.IR rm +shall write a prompt to the standard error and read a line from the +standard input. If the response is not affirmative, +.IR rm +shall do nothing more with the current file and go on to any remaining +files. +.IP " 4." 4 +If the current file is a directory, +.IR rm +shall perform actions equivalent to the +\fIrmdir\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called with a pathname of the current +file used as the +.IR path +argument. If the current file is not a directory, +.IR rm +shall perform actions equivalent to the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called with a pathname of the current +file used as the +.IR path +argument. +.RS 4 +.P +If this fails for any reason, +.IR rm +shall write a diagnostic message to standard error, do nothing more +with the current file, and go on to any remaining files. +.RE +.P +The +.IR rm +utility shall be able to descend to arbitrary depths in a file +hierarchy, and shall not fail due to path length limitations (unless an +operand specified by the user exceeds system limitations). +.SH OPTIONS +The +.IR rm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\fP" 10 +Do not prompt for confirmation. Do not write diagnostic messages or +modify the exit status in the case of nonexistent operands. Any +previous occurrences of the +.BR \(mii +option shall be ignored. +.IP "\fB\(mii\fP" 10 +Prompt for confirmation as described previously. Any previous +occurrences of the +.BR \(mif +option shall be ignored. +.IP "\fB\(miR\fP" 10 +Remove file hierarchies. See the DESCRIPTION. +.IP "\fB\(mir\fP" 10 +Equivalent to +.BR \(miR . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a directory entry to be removed. +.SH STDIN +The standard input shall be used to read an input line in response to +each prompt specified in the STDOUT section. Otherwise, the standard +input shall not be used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR rm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments) and the behavior of character +classes within regular expressions used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Prompts shall be written to standard error under the conditions +specified in the DESCRIPTION and OPTIONS sections. The prompts shall +contain the +.IR file +pathname, but their format is otherwise unspecified. The standard +error also shall be used for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Each directory entry was successfully removed, unless its removal was +canceled by a non-affirmative response to a prompt for confirmation. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR rm +utility is forbidden to remove the names dot and dot-dot in order to +avoid the consequences of inadvertently doing something like: +.sp +.RS 4 +.nf +\fB +rm \(mir .* +.fi \fR +.P +.RE +.P +Some implementations do not permit the removal of the last link to an +executable binary file that is being executed; see the +.BR [EBUSY] +error in the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. Thus, the +.IR rm +utility can fail to remove such files. +.P +The +.BR \(mii +option causes +.IR rm +to prompt and read the standard input even if the standard input is not +a terminal, but in the absence of +.BR \(mii +the mode prompting is not done when the standard input is not a +terminal. +.SH EXAMPLES +.IP " 1." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +rm a.out core +.fi \fR +.P +.RE +.P +removes the directory entries: +.BR a.out +and +.BR core . +.RE +.IP " 2." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +rm \(miRf junk +.fi \fR +.P +.RE +.P +removes the directory +.BR junk +and all its contents, without prompting. +.RE +.SH RATIONALE +For absolute clarity, paragraphs (2b) and (3) in the DESCRIPTION of +.IR rm +describing the behavior when prompting for confirmation, should be +interpreted in the following manner: +.sp +.RS 4 +.nf +\fB +if ((NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +.fi \fR +.P +.RE +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because +implementations may desire more descriptive prompts than those used on +historical implementations. Therefore, an application not using the +.BR \(mif +option, or using the +.BR \(mii +option, relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.P +The +.BR \(mir +option is historical practice on all known systems. The synonym +.BR \(miR +option is provided for consistency with the other utilities in this volume of POSIX.1\(hy2008 +that provide options requesting recursive descent through the file +hierarchy. +.P +The behavior of the +.BR \(mif +option in historical versions of +.IR rm +is inconsistent. In general, along with ``forcing'' the unlink without +prompting for permission, it always causes diagnostic messages to be +suppressed and the exit status to be unmodified for nonexistent +operands and files that cannot be unlinked. In some versions, however, +the +.BR \(mif +option suppresses usage messages and system errors as well. +Suppressing such messages is not a service to either shell scripts or +users. +.P +It is less clear that error messages regarding files that cannot be +unlinked (removed) should be suppressed. Although this is historical +practice, this volume of POSIX.1\(hy2008 does not permit the +.BR \(mif +option to suppress such messages. +.P +When given the +.BR \(mir +and +.BR \(mii +options, historical versions of +.IR rm +prompt the user twice for each directory, once before removing its +contents and once before actually attempting to delete the directory +entry that names it. This allows the user to ``prune'' the file +hierarchy walk. Historical versions of +.IR rm +were inconsistent in that some did not do the former prompt for +directories named on the command line and others had obscure prompting +behavior when the +.BR \(mii +option was specified and the permissions of the file did not permit +writing. The POSIX Shell and Utilities +.IR rm +differs little from historic practice, but does require that prompts be +consistent. Historical versions of +.IR rm +were also inconsistent in that prompts were done to both standard +output and standard error. This volume of POSIX.1\(hy2008 requires that prompts be done to +standard error, for consistency with +.IR cp +and +.IR mv , +and to allow historical extensions to +.IR rm +that provide an option to list deleted files on standard output. +.P +The +.IR rm +utility is required to descend to arbitrary depths so that any file +hierarchy may be deleted. This means, for example, that the +.IR rm +utility cannot run out of file descriptors during its descent (that is, +if the number of file descriptors is limited, +.IR rm +cannot be implemented in the historical fashion where one file +descriptor is used per directory level). Also, +.IR rm +is not permitted to fail because of path length restrictions, unless an +operand specified by the user is longer than +{PATH_MAX}. +.P +The +.IR rm +utility removes symbolic links themselves, not the files they refer to, +as a consequence of the dependence on the +\fIunlink\fR() +functionality, per the DESCRIPTION. When removing hierarchies with +.BR \(mir +or +.BR \(miR , +the prohibition on following symbolic links has to be made explicit. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrmdir\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIremove\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/rmdel.1p b/man-pages-posix-2013-a/man1p/rmdel.1p new file mode 100644 index 0000000..08d0578 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/rmdel.1p @@ -0,0 +1,167 @@ +'\" et +.TH RMDEL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rmdel +\(em remove a delta from an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +rmdel \(mir \fISID file\fR... +.fi +.SH DESCRIPTION +The +.IR rmdel +utility shall remove the delta specified by the SID from each named +SCCS file. The delta to be removed shall be the most recent delta in +its branch in the delta chain of each named SCCS file. In addition, the +application shall ensure that the SID specified is not that of a +version being edited for the purpose of making a delta; that is, if a +.IR p-file +(see +.IR "\fIget\fR\^") +exists for the named SCCS file, the SID specified shall not appear in +any entry of the +.IR p-file . +.P +Removal of a delta shall be restricted to: +.IP " 1." 4 +The user who made the delta +.IP " 2." 4 +The owner of the SCCS file +.IP " 3." 4 +The owner of the directory containing the SCCS file +.SH OPTIONS +The +.IR rmdel +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mir\ \fISID\fR" 10 +Specify the SCCS identification string (\c +.IR SID ) +of the delta to be deleted. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR rmdel +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input is +taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +The SCCS files shall be files of unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR rmdel : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The SCCS files shall be files of unspecified format. During processing +of a +.IR file , +a temporary +.IR x-file , +as described in +.IR "\fIadmin\fR\^", +may be created and deleted; a locking +.IR z-file , +as described in +.IR "\fIget\fR\^", +may be created and deleted. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIprs\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/rmdir.1p b/man-pages-posix-2013-a/man1p/rmdir.1p new file mode 100644 index 0000000..753d854 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/rmdir.1p @@ -0,0 +1,195 @@ +'\" et +.TH RMDIR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rmdir +\(em remove directories +.SH SYNOPSIS +.LP +.nf +rmdir \fB[\fR\(mip\fB]\fI dir\fR... +.fi +.SH DESCRIPTION +The +.IR rmdir +utility shall remove the directory entry specified by each +.IR dir +operand. +.P +For each +.IR dir +operand, the +.IR rmdir +utility shall perform actions equivalent to the +\fIrmdir\fR() +function called with the +.IR dir +operand as its only argument. +.P +Directories shall be processed in the order specified. If a directory +and a subdirectory of that directory are specified in a single +invocation of the +.IR rmdir +utility, the application shall specify the subdirectory before the +parent directory so that the parent directory will be empty when the +.IR rmdir +utility tries to remove it. +.SH OPTIONS +The +.IR rmdir +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mip\fP" 10 +Remove all directories in a pathname. For each +.IR dir +operand: +.RS 10 +.IP " 1." 4 +The directory entry it names shall be removed. +.IP " 2." 4 +If the +.IR dir +operand includes more than one pathname component, effects equivalent +to the following command shall occur: +.RS 4 +.sp +.RS 4 +.nf +\fB +rmdir \(mip $(dirname \fIdir\fP) +.fi \fR +.P +.RE +.RE +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIdir\fR" 10 +A pathname of an empty directory to be removed. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR rmdir : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Each directory entry specified by a +.IR dir +operand was removed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The definition of an empty directory is one that contains, at most, +directory entries for dot and dot-dot. +.SH EXAMPLES +If a directory +.BR a +in the current directory is empty except it contains a directory +.BR b +and +.BR a/b +is empty except it contains a directory +.BR c : +.sp +.RS 4 +.nf +\fB +rmdir \(mip a/b/c +.fi \fR +.P +.RE +.P +removes all three directories. +.SH RATIONALE +On historical System V systems, the +.BR \(mip +option also caused a message to be written to the standard output. The +message indicated whether the whole path was removed or whether part of +the path remained for some reason. The STDERR section requires this +diagnostic when the entire path specified by a +.IR dir +operand is not removed, but does not allow the status message reporting +success to be written as a diagnostic. +.P +The +.IR rmdir +utility on System V also included a +.BR \(mis +option that suppressed the informational message output by the +.BR \(mip +option. This option has been omitted because the informational message +is not specified by this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIremove\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/sact.1p b/man-pages-posix-2013-a/man1p/sact.1p new file mode 100644 index 0000000..fe3e7b1 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/sact.1p @@ -0,0 +1,186 @@ +'\" et +.TH SACT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sact +\(em print current SCCS file-editing activity (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +sact \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR sact +utility shall inform the user of any impending deltas to a named SCCS +file by writing a list to standard output. This situation occurs when +.IR get +.BR \(mie +has been executed previously without a subsequent execution of +.IR delta , +.IR unget , +or +.IR sccs +.BR unedit . +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR sact +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +Any SCCS files interrogated are files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sact : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The output for each named file shall consist of a line in the following +format: +.sp +.RS 4 +.nf +\fB +"%s %s %s %s %s\en", <\fISID\fR>, <\fInew SID\fR>, <\fIlogin\fR>, <\fIdate\fR>, <\fItime\fR> +.fi \fR +.P +.RE +.IP "<\fISID\fR>" 10 +Specifies the SID of a delta that currently exists in the SCCS file to +which changes are made to make the new delta. +.IP "<\fInew\ SID\fR>" 10 +Specifies the SID for the new delta to be created. +.IP "<\fIlogin\fR>" 10 +Contains the login name of the user who makes the delta (that is, who +executed a +.IR get +for editing). +.IP "<\fIdate\fR>" 10 +Contains the date that +.IR get +.BR \(mie +was executed, in the format used by the +.IR prs +.BR :D: +data keyword. +.IP "<\fItime\fR>" 10 +Contains the time that +.IR get +.BR \(mie +was executed, in the format used by the +.IR prs +.BR :T: +data keyword. +.P +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of the +preceding lines: +.sp +.RS 4 +.nf +\fB +"\en%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for optional informative +messages concerning SCCS files with no impending deltas, and for +diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIsccs\fR\^", +.IR "\fIunget\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/sccs.1p b/man-pages-posix-2013-a/man1p/sccs.1p new file mode 100644 index 0000000..765bf08 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/sccs.1p @@ -0,0 +1,542 @@ +'\" et +.TH SCCS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sccs +\(em front end for the SCCS subsystem (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +sccs \fB[\fR\(mir\fB] [\fR\(mid \fIpath\fB] [\fR\(mip \fIpath\fB] \fIcommand \fB[\fIoptions\fR...\fB] [\fIoperands\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR sccs +utility is a front end to the SCCS programs. It also includes the +capability to run set-user-id to another user to provide additional +protection. +.P +The +.IR sccs +utility shall invoke the specified +.IR command +with the specified +.IR options +and +.IR operands . +By default, each of the +.IR operands +shall be modified by prefixing it with the string +.BR \(dqSCCS/s.\(dq . +.P +The +.IR command +can be the name of one of the SCCS utilities in this volume of POSIX.1\(hy2008 (\c +.IR admin , +.IR delta , +.IR get , +.IR prs , +.IR rmdel , +.IR sact , +.IR unget , +.IR val , +or +.IR what ) +or one of the pseudo-utilities listed in the EXTENDED DESCRIPTION +section. +.SH OPTIONS +The +.IR sccs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that +.IR options +operands are actually options to be passed to the utility named by +.IR command . +When the portion of the command: +.sp +.RS 4 +.nf +\fB +\fIcommand \fB[\fIoptions\fR ... \fB] [\fIoperands\fR ... \fB]\fR +.fi \fR +.P +.RE +.P +is considered, all of the pseudo-utilities used as +.IR command +shall support the Utility Syntax Guidelines. Any of the other SCCS +utilities that can be invoked in this manner support the Guidelines to +the extent indicated by their individual OPTIONS sections. +.P +The following options shall be supported preceding the +.IR command +operand: +.IP "\fB\(mid\ \fIpath\fR" 10 +A pathname of a directory to be used as a root directory for the SCCS +files. The default shall be the current directory. The +.BR \(mid +option shall take precedence over the +.IR PROJECTDIR +variable. See +.BR \(mip . +.IP "\fB\(mip\ \fIpath\fR" 10 +A pathname of a directory in which the SCCS files are located. The +default shall be the +.BR SCCS +directory. +.RS 10 +.P +The +.BR \(mip +option differs from the +.BR \(mid +option in that the +.BR \(mid +option-argument shall be prefixed to the entire pathname and the +.BR \(mip +option-argument shall be inserted before the final component of the +pathname. For example: +.sp +.RS 4 +.nf +\fB +sccs \(mid /x \(mip y get a/b +.fi \fR +.P +.RE +.P +converts to: +.sp +.RS 4 +.nf +\fB +get /x/a/y/s.b +.fi \fR +.P +.RE +.P +This allows the creation of aliases such as: +.sp +.RS 4 +.nf +\fB +alias syssccs="sccs \(mid /usr/src" +.fi \fR +.P +.RE +.P +which is used as: +.sp +.RS 4 +.nf +\fB +syssccs get cmd/who.c +.fi \fR +.P +.RE +.RE +.IP "\fB\(mir\fP" 10 +Invoke +.IR command +with the real user ID of the process, not any effective user ID that +the +.IR sccs +utility is set to. Certain commands (\c +.IR admin , +.BR check , +.BR clean , +.BR diffs , +.BR info , +.IR rmdel , +and +.BR tell ) +cannot be run set-user-ID by all users, since this would allow anyone +to change the authorizations. These commands are always run as the +real user. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIcommand\fR" 10 +An SCCS utility name or the name of one of the pseudo-utilities listed +in the EXTENDED DESCRIPTION section. +.IP "\fIoptions\fR" 10 +An option or option-argument to be passed to +.IR command . +.IP "\fIoperands\fR" 10 +An operand to be passed to +.IR command . +.SH STDIN +See the utility description for the specified +.IR command . +.SH "INPUT FILES" +See the utility description for the specified +.IR command . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sccs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPROJECTDIR\fP" 10 +.br +Provide a default value for the +.BR \(mid +.IR path +option. If the value of +.IR PROJECTDIR +begins with a +, +it shall be considered an absolute pathname; otherwise, the value of +.IR PROJECTDIR +is treated as a user name and that user's initial working directory +shall be examined for a subdirectory +.BR src +or +.BR source . +If such a directory is found, it shall be used. Otherwise, the value +shall be used as a relative pathname. +.P +Additional environment variable effects may be found in the utility +description for the specified +.IR command . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the utility description for the specified +.IR command . +.SH STDERR +See the utility description for the specified +.IR command . +.SH "OUTPUT FILES" +See the utility description for the specified +.IR command . +.SH "EXTENDED DESCRIPTION" +The following pseudo-utilities shall be supported as +.IR command +operands. All options referred to in the following list are values +given in the +.IR options +operands following +.IR command . +.IP "\fBcheck\fR" 8 +Equivalent to +.BR info , +except that nothing shall be printed if nothing is being edited, and a +non-zero exit status shall be returned if anything is being edited. The +intent is to have this included in an ``install'' entry in a makefile +to ensure that everything is included into the SCCS file before a +version is installed. +.IP "\fBclean\fR" 8 +Remove everything from the current directory that can be recreated from +SCCS files, but do not remove any files being edited. If the +.BR \(mib +option is given, branches shall be ignored in the determination of +whether they are being edited; this is dangerous if branches are kept +in the same directory. +.IP "\fBcreate\fR" 8 +Create an SCCS file, taking the initial contents from the file of the +same name. Any options to +.IR admin +are accepted. If the creation is successful, the original files shall +be renamed by prefixing the basenames with a comma. These renamed files +should be removed after it has been verified that the SCCS files have +been created successfully. +.IP "\fBdelget\fR" 8 +Perform a +.IR delta +on the named files and then +.IR get +new versions. The new versions shall have ID keywords expanded and +shall not be editable. Any +.BR \(mim , +.BR \(mip , +.BR \(mir , +.BR \(mis , +and +.BR \(miy +options shall be passed to +.IR delta , +and any +.BR \(mib , +.BR \(mic , +.BR \(mie , +.BR \(mii , +.BR \(mik , +.BR \(mil , +.BR \(mis , +and +.BR \(mix +options shall be passed to +.IR get . +.IP "\fBdeledit\fR" 8 +Equivalent to +.BR delget , +except that the +.IR get +phase shall include the +.BR \(mie +option. This option is useful for making a checkpoint of the current +editing phase. The same options shall be passed to +.IR delta +as described above, and all the options listed for +.IR get +above except +.BR \(mie +shall be passed to +.BR edit . +.IP "\fBdiffs\fR" 8 +Write a difference listing between the current version of the files +checked out for editing and the versions in SCCS format. Any +.BR \(mir , +.BR \(mic , +.BR \(mii , +.BR \(mix , +and +.BR \(mit +options shall be passed to +.IR get ; +any +.BR \(mil , +.BR \(mis , +.BR \(mie , +.BR \(mif , +.BR \(mih , +and +.BR \(mib +options shall be passed to +.IR diff . +A +.BR \(miC +option shall be passed to +.IR diff +as +.BR \(mic . +.IP "\fBedit\fR" 8 +Equivalent to +.IR get +.BR \(mie . +.IP "\fBfix\fR" 8 +Remove the named delta, but leave a copy of the delta with the changes +that were in it. It is useful for fixing small compiler bugs, and so +on. The application shall ensure that it is followed by a +.BR \(mir +.IR SID +option. Since +.BR fix +does not leave audit trails, it should be used carefully. +.IP "\fBinfo\fR" 8 +Write a listing of all files being edited. If the +.BR \(mib +option is given, branches (that is, SIDs with two or fewer components) +shall be ignored. If a +.BR \(miu +.IR user +option is given, then only files being edited by the named user shall +be listed. A +.BR \(miU +option shall be equivalent to +.BR \(miu <\c +.IR "current\ user" >. +.IP "\fBprint\fR" 8 +Write out verbose information about the named files, equivalent to +.IR sccs +.IR prs . +.IP "\fBtell\fR" 8 +Write a +-separated +list of the files being edited to standard output. Takes the +.BR \(mib , +.BR \(miu , +and +.BR \(miU +options like +.BR info +and +.BR check . +.IP "\fBunedit\fR" 8 +This is the opposite of an +.BR edit +or a +.IR get +.BR \(mie . +It should be used with caution, since any changes made since the +.IR get +are lost. +.br +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Many of the SCCS utilities take directory names as operands as well as +specific filenames. The pseudo-utilities supported by +.IR sccs +are not described as having this capability, but are not prohibited +from doing so. +.SH EXAMPLES +.IP " 1." 4 +To get a file for editing, edit it and produce a new delta: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs get \(mie file.c +ex file.c +sccs delta file.c +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +To get a file from another directory: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs \(mip /usr/src/sccs/s. get cc.c +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +sccs get /usr/src/sccs/s.cc.c +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +To make a delta of a large number of files in the current directory: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs delta *.c +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +To get a list of files being edited that are not on branches: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs info \(mib +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +To delta everything being edited by the current user: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs delta $(sccs tell \(miU) +.fi \fR +.P +.RE +.RE +.IP " 6." 4 +In a makefile, to get source files from an SCCS file if it does not +already exist: +.RS 4 +.sp +.RS 4 +.nf +\fB +SRCS = <\fIlist of source files\fP> +$(SRCS): + sccs get $(REL) $@ +.fi \fR +.P +.RE +.RE +.SH RATIONALE +.IR sccs +and its associated utilities are part of the XSI Development +Utilities option within the XSI option. +.P +SCCS is an abbreviation for Source Code Control System. It is a +maintenance and enhancement tracking tool. When a file is put under +SCCS, the source code control system maintains the file and, when +changes are made, identifies and stores them in the file with the +original source code and/or documentation. As other changes are made, +they too are identified and retained in the file. +.P +Retrieval of the original and any set of changes is possible. Any +version of the file as it develops can be reconstructed for inspection +or additional modification. History data can be stored with each +version, documenting why the changes were made, who made them, and when +they were made. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fImake\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIrmdel\fR\^", +.IR "\fIsact\fR\^", +.IR "\fIunget\fR\^", +.IR "\fIval\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/sed.1p b/man-pages-posix-2013-a/man1p/sed.1p new file mode 100644 index 0000000..90428f4 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/sed.1p @@ -0,0 +1,1067 @@ +'\" et +.TH SED "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sed +\(em stream editor +.SH SYNOPSIS +.LP +.nf +sed \fB[\fR\(min\fB] \fIscript \fB[\fIfile\fR...\fB]\fR +.P +sed \fB[\fR\(min\fB] \fR\(mie \fIscript \fB[\fR\(mie \fIscript\fB]\fR... \fB[\fR\(mif \fIscript_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +sed \fB[\fR\(min\fB] [\fR\(mie \fIscript\fB]\fR... \(mif \fIscript_file\fR \fB[\fR\(mif \fIscript_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR sed +utility is a stream editor that shall read one or more text files, make +editing changes according to a script of editing commands, and write +the results to standard output. The script shall be obtained from +either the +.IR script +operand string or a combination of the option-arguments from the +.BR \(mie +.IR script +and +.BR \(mif +.IR script_file +options. +.SH OPTIONS +The +.IR sed +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of presentation of the +.BR \(mie +and +.BR \(mif +options is significant. +.P +The following options shall be supported: +.IP "\fB\(mie\ \fIscript\fR" 10 +Add the editing commands specified by the +.IR script +option-argument to the end of the script of editing commands. +.IP "\fB\(mif\ \fIscript_file\fR" 10 +Add the editing commands in the file +.IR script_file +to the end of the script of editing commands. +.IP "\fB\(min\fP" 10 +Suppress the default output (in which each line, after it is examined +for editing, is written to standard output). Only lines explicitly +selected for output are written. +.P +If any +.BR \(mie +or +.BR \(mif +options are specified, the script of editing commands shall initially +be empty. The commands specified by each +.BR \(mie +or +.BR \(mif +option shall be added to the script in the order specified. When each +addition is made, if the previous addition (if any) was from a +.BR \(mie +option, a + +shall be inserted before the new addition. The resulting script shall +have the same properties as the +.IR script +operand, described in the OPERANDS section. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file whose contents are read and edited. If multiple +.IR file +operands are specified, the named files shall be read in the order +specified and the concatenation shall be edited. If no +.IR file +operands are specified, the standard input shall be used. +.IP "\fIscript\fR" 10 +A string to be used as the script of editing commands. The application +shall not present a +.IR script +that violates the restrictions of a text file except that the final +character need not be a +. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. The +.IR script_file s +named by the +.BR \(mif +option shall consist of editing commands. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sed : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), and the behavior +of character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The input files shall be written to standard output, with the editing +commands specified in the script applied. If the +.BR \(min +option is specified, only those input lines selected by the script +shall be written to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files shall be text files whose formats are dependent on the +editing commands given. +.SH "EXTENDED DESCRIPTION" +The +.IR script +shall consist of editing commands of the following form: +.sp +.RS 4 +.nf +\fB +\fB[\fIaddress\fB[\fR,\fIaddress\fB]]\fIfunction\fR +.fi \fR +.P +.RE +.P +where +.IR function +represents a single-character command verb from the list in +.IR "Editing Commands in sed", +followed by any applicable arguments. +.P +The command can be preceded by + +characters and/or + +characters. The function can be preceded by + +characters. These optional characters shall have no effect. +.P +In default operation, +.IR sed +cyclically shall append a line of input, less its terminating + +character, into the pattern space. Reading from input shall be skipped +if a + +was in the pattern space prior to a +.BR D +command ending the previous cycle. The +.IR sed +utility shall then apply in sequence all commands whose addresses select +that pattern space, until a command starts the next cycle or quits. If +no commands explicitly started a new cycle, then at the end of the script +the pattern space shall be copied to standard output (except when +.BR \(min +is specified) and the pattern space shall be deleted. Whenever the +pattern space is written to standard output or a named file, +.IR sed +shall immediately follow it with a +. +.P +Some of the editing commands use a hold space to save all or part of +the pattern space for subsequent retrieval. The pattern and hold spaces +shall each be able to hold at least 8\|192 bytes. +.SS "Addresses in sed" +.P +An address is either a decimal number that counts input lines +cumulatively across files, a +.BR '$' +character that addresses the last line of input, or a context address +(which consists of a BRE, as described in +.IR "Regular Expressions in sed", +preceded and followed by a delimiter, usually a +). +.P +An editing command with no addresses shall select every pattern space. +.P +An editing command with one address shall select each pattern space +that matches the address. +.P +An editing command with two addresses shall select the inclusive range +from the first pattern space that matches the first address through the +next pattern space that matches the second. (If the second address is a +number less than or equal to the line number first selected, only one +line shall be selected.) Starting at the first line following the +selected range, +.IR sed +shall look again for the first address. Thereafter, the process shall +be repeated. Omitting either or both of the address components in the +following form produces undefined results: +.sp +.RS 4 +.nf +\fB +\fB[\fIaddress\fB[\fR,\fIaddress\fB]]\fR +.fi \fR +.P +.RE +.SS "Regular Expressions in sed" +.P +The +.IR sed +utility shall support the BREs described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions", +with the following additions: +.IP " *" 4 +In a context address, the construction +.BR \(dq\ecBREc\(dq , +where +.IR c +is any character other than + +or +, +shall be identical to +.BR \(dq/BRE/\(dq . +If the character designated by +.IR c +appears following a +, +then it shall be considered to be that literal character, which shall +not terminate the BRE. For example, in the context address +.BR \(dq\exabc\exdefx\(dq , +the second +.IR x +stands for itself, so that the BRE is +.BR \(dqabcxdef\(dq . +.IP " *" 4 +The escape sequence +.BR '\en' +shall match a + +embedded in the pattern space. A literal + +shall not be used in the BRE of a context address or in the substitute +function. +.IP " *" 4 +If an RE is empty (that is, no pattern is specified) +.IR sed +shall behave as if the last RE used in the last command applied (either +as an address or as part of a substitute command) was specified. +.SS "Editing Commands in sed" +.P +In the following list of editing commands, the maximum number of +permissible addresses for each function is indicated by [\c +.IR 0addr ], +[\c +.IR 1addr ], +or [\c +.IR 2addr ], +representing zero, one, or two addresses. +.P +The argument +.IR text +shall consist of one or more lines. Each embedded + +in the text shall be preceded by a +. +Other + +characters in text shall be removed, and the following character shall +be treated literally. +.P +The +.BR r +and +.BR w +command verbs, and the +.IR w +flag to the +.BR s +command, take an +.IR rfile +(or +.IR wfile ) +parameter, separated from the command verb letter or flag by one or +more + +characters; implementations may allow zero separation as an extension. +.P +The argument +.IR rfile +or the argument +.IR wfile +shall terminate the editing command. Each +.IR wfile +shall be created before processing begins. Implementations shall +support at least ten +.IR wfile +arguments in the script; the actual number (greater than or equal to +10) that is supported by the implementation is unspecified. The +use of the +.IR wfile +parameter shall cause that file to be initially created, if it does not +exist, or shall replace the contents of an existing file. +.P +The +.BR b , +.BR r , +.BR s , +.BR t , +.BR w , +.BR y , +and +.BR : +command verbs shall accept additional arguments. The following synopses +indicate which arguments shall be separated from the command verbs by a +single +. +.P +The +.BR a +and +.BR r +commands schedule text for later output. The text specified for the +.BR a +command, and the contents of the file specified for the +.BR r +command, shall be written to standard output just before the next +attempt to fetch a line of input when executing the +.BR N +or +.BR n +commands, or when reaching the end of the script. If written when +reaching the end of the script, and the +.BR \(min +option was not specified, the text shall be written after copying the +pattern space to standard output. The contents of the file specified +for the +.BR r +command shall be as of the time the output is written, not the time the +.BR r +command is applied. The text shall be output in the order in which the +.BR a +and +.BR r +commands were applied to the input. +.P +Command verbs other than +.BR { , +.BR a , +.BR b , +.BR c , +.BR i , +.BR r , +.BR t , +.BR w , +.BR : , +and +.BR # +can be followed by a +, +optional + +characters, and another command verb. However, when the +.BR s +command verb is used with the +.IR w +flag, following it with another command in this manner produces +undefined results. +.P +A function can be preceded by one or more +.BR '!' +characters, in which case the function shall be applied if the +addresses do not select the pattern space. Zero or more + +characters shall be accepted before the first +.BR '!' +character. It is unspecified whether + +characters can follow a +.BR '!' +character, and conforming applications shall not follow a +.BR '!' +character with + +characters. +.IP "\fB[\fI2addr\fB]\ {\fIediting command\fR" 10 +.IP "\fIediting command\fR" 10 +.IP ".\|.\|." 10 +.IP "\fB}\fR" 10 +Execute a list of +.IR sed +editing commands only when the pattern space is selected. The list of +.IR sed +editing commands shall be surrounded by braces and separated by + +characters, and conform to the following rules. The braces can be preceded +or followed by + +characters. The editing commands can be preceded by + +characters, but shall not be followed by + +characters. The + +shall be preceded by a + +and can be preceded or followed by + +characters. +.IP "\fB[\fI1addr\fB]a\e\fR" 10 +.IP "\fItext\fR" 10 +Write text to standard output as described previously. +.IP "\fB[\fI2addr\fB]b\ [\fIlabel\fB]\fR" 10 +.br +Branch to the +.BR : +function bearing the +.IR label . +If +.IR label +is not specified, branch to the end of the script. The implementation +shall support +.IR label s +recognized as unique up to at least 8 characters; the actual length +(greater than or equal to 8) that shall be supported by the +implementation is unspecified. It is unspecified whether exceeding a +label length causes an error or a silent truncation. +.IP "\fB[\fI2addr\fB]c\e\fR" 10 +.IP "\fItext\fR" 10 +Delete the pattern space. With a 0 or 1 address or at the end of a +2-address range, place +.IR text +on the output and start the next cycle. +.IP "\fB[\fI2addr\fB]d\fR" 10 +Delete the pattern space and start the next cycle. +.IP "\fB[\fI2addr\fB]D\fR" 10 +If the pattern space contains no +, +delete the pattern space and start a normal new cycle as if the +.BR d +command was issued. Otherwise, delete the initial segment of the +pattern space through the first +, +and start the next cycle with the resultant pattern space and without +reading any new input. +.IP "\fB[\fI2addr\fB]g\fR" 10 +Replace the contents of the pattern space by the contents of the hold +space. +.IP "\fB[\fI2addr\fB]G\fR" 10 +Append to the pattern space a + +followed by the contents of the hold space. +.IP "\fB[\fI2addr\fB]h\fR" 10 +Replace the contents of the hold space with the contents of the pattern +space. +.IP "\fB[\fI2addr\fB]H\fR" 10 +Append to the hold space a + +followed by the contents of the pattern space. +.IP "\fB[\fI1addr\fB]i\e\fR" 10 +.IP "\fItext\fR" 10 +Write +.IR text +to standard output. +.IP "\fB[\fI2addr\fB]l\fR" 10 +(The letter ell.) Write the pattern space to standard output in a +visually unambiguous form. The characters listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +shall be written as the corresponding escape sequence; the +.BR '\en' +in that table is not applicable. Non-printable characters not in that +table shall be written as one three-digit octal number (with a +preceding +) +for each byte in the character (most significant byte first). +.RS 10 +.P +Long lines shall be folded, with the point of folding indicated by +writing a + +followed by a +; +the length at which folding occurs is unspecified, but should be +appropriate for the output device. The end of each line shall be marked +with a +.BR '$' . +.RE +.IP "\fB[\fI2addr\fB]n\fR" 10 +Write the pattern space to standard output if the default output has +not been suppressed, and replace the pattern space with the next line +of input, less its terminating +. +.RS 10 +.P +If no next line of input is available, the +.BR n +command verb shall branch to the end of the script and quit without +starting a new cycle. +.RE +.IP "\fB[\fI2addr\fB]N\fR" 10 +Append the next line of input, less its terminating +, +to the pattern space, using an embedded + +to separate the appended material from the original material. Note that +the current line number changes. +.RS 10 +.P +If no next line of input is available, the +.BR N +command verb shall branch to the end of the script and quit without +starting a new cycle or copying the pattern space to standard output. +.RE +.IP "\fB[\fI2addr\fB]p\fR" 10 +Write the pattern space to standard output. +.IP "\fB[\fI2addr\fB]P\fR" 10 +Write the pattern space, up to the first +, +to standard output. +.IP "\fB[\fI1addr\fB]q\fR" 10 +Branch to the end of the script and quit without starting a new cycle. +.IP "\fB[\fI1addr\fB]r\ \fIrfile\fR" 10 +Copy the contents of +.IR rfile +to standard output as described previously. If +.IR rfile +does not exist or cannot be read, it shall be treated as if it were an +empty file, causing no error condition. +.IP "\fB[\fI2addr\fB]s/\fIBRE\fB/\fIreplacement\fB/\fIflags\fR" 10 +.br +Substitute the replacement string for instances of the BRE in the +pattern space. Any character other than + +or + +can be used instead of a + +to delimit the BRE and the replacement. Within the BRE and the +replacement, the BRE delimiter itself can be used as a literal character +if it is preceded by a +. +.RS 10 +.P +The replacement string shall be scanned from beginning to end. An + +(\c +.BR '&' ) +appearing in the replacement shall be replaced by the string matching +the BRE. The special meaning of +.BR '&' +in this context can be suppressed by preceding it by a +. +The characters \fR"\e\fIn"\fR, where +.IR n +is a digit, shall be replaced by the text matched by the corresponding +back-reference expression. If the corresponding back-reference expression +does not match, then the characters \fR"\e\fIn"\fR shall be replaced +by the empty string. The special meaning of \fR"\e\fIn"\fR where +.IR n +is a digit in this context, can be suppressed by preceding it by a +. +For each other + +encountered, the following character shall lose its special meaning (if +any). The meaning of a + +immediately followed by any character other than +.BR '&' , +, +a digit, or the delimiter character used for this command, is +unspecified. +.P +A line can be split by substituting a + +into it. The application shall escape the + +in the replacement by preceding it by a +. +A substitution shall be considered to have been performed even if the +replacement string is identical to the string that it replaces. Any + +used to alter the default meaning of a subsequent character shall be +discarded from the BRE or the replacement before evaluating the BRE or +using the replacement. +.P +The value of +.IR flags +shall be zero or more of: +.IP "\fIn\fR" 10 +Substitute for the +.IR n th +occurrence only of the BRE found within the pattern space. +.IP "\fBg\fR" 10 +Globally substitute for all non-overlapping instances of the BRE rather +than just the first one. If both +.BR g +and +.IR n +are specified, the results are unspecified. +.IP "\fBp\fR" 10 +Write the pattern space to standard output if a replacement was made. +.IP "\fBw\ \fIwfile\fR" 10 +Write. Append the pattern space to +.IR wfile +if a replacement was made. A conforming application shall precede the +.IR wfile +argument with one or more + +characters. If the +.BR w +flag is not the last flag value given in a concatenation of multiple +flag values, the results are undefined. +.RE +.IP "\fB[\fI2addr\fB]t\ [\fIlabel\fB]\fR" 10 +.br +Test. Branch to the +.BR : +command verb bearing the +.IR label +if any substitutions have been made since the most recent reading of an +input line or execution of a +.BR t . +If +.IR label +is not specified, branch to the end of the script. +.IP "\fB[\fI2addr\fB]w\ \fIwfile\fR" 10 +.br +Append (write) the pattern space to +.IR wfile . +.IP "\fB[\fI2addr\fB]x\fR" 10 +Exchange the contents of the pattern and hold spaces. +.IP "\fB[\fI2addr\fB]y/\fIstring1\fB/\fIstring2\fB/\fR" 10 +.br +Replace all occurrences of characters in +.IR string1 +with the corresponding characters in +.IR string2 . +If a + +followed by an +.BR 'n' +appear in +.IR string1 +or +.IR string2 , +the two characters shall be handled as a single +. +If the number of characters in +.IR string1 +and +.IR string2 +are not equal, or if any of the characters in +.IR string1 +appear more than once, the results are undefined. Any character other +than + +or + +can be used instead of + +to delimit the strings. If the delimiter is not +.BR 'n' , +within +.IR string1 +and +.IR string2 , +the delimiter itself can be used as a literal character if it is +preceded by a +. +If a + +character is immediately followed by a + +character in +.IR string1 +or +.IR string2 , +the two + +characters shall be counted as a single literal + +character. The meaning of a + +followed by any character that is not +.BR 'n' , +a +, +or the delimiter character is undefined. +.IP "\fB[\fI0addr\fB]:\fIlabel\fR" 10 +Do nothing. This command bears a +.IR label +to which the +.BR b +and +.BR t +commands branch. +.IP "\fB[\fI1addr\fB]=\fR" 10 +Write the following to standard output: +.RS 10 +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIcurrent line number\fR> +.fi \fR +.P +.RE +.RE +.IP "\fB[\fI0addr\fB]\fR" 10 +Ignore this empty command. +.IP "\fB[\fI0addr\fB]#\fR" 10 +Ignore the +.BR '#' +and the remainder of the line (treat them as a comment), with the +single exception that if the first two characters in the script are +.BR \(dq#n\(dq , +the default output shall be suppressed; this shall be the equivalent of +specifying +.BR \(min +on the command line. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Regular expressions match entire strings, not just individual lines, +but a + +is matched by +.BR '\en' +in a +.IR sed +RE; a + +is not allowed by the general definition of regular expression in +POSIX.1\(hy2008. Also note that +.BR '\en' +cannot be used to match a + +at the end of an arbitrary input line; + +characters appear in the pattern space as a result of the +.BR N +editing command. +.SH EXAMPLES +This +.IR sed +script simulates the BSD +.IR cat +.BR \(mis +command, squeezing excess empty lines from standard input. +.sp +.RS 4 +.nf +\fB +sed \(min ' +# Write non-empty lines. +/./ { + p + d + } +# Write a single empty line, then look for more empty lines. +/^$/ p +# Get next line, discard the held (empty line), +# and look for more empty lines. +:Empty +/^$/ { + N + s/.// + b Empty + } +# Write the non-empty line before going back to search +# for the first in a set of empty lines. + p +\&' +.fi \fR +.P +.RE +.P +The following +.IR sed +command is a much simpler method of squeezing empty lines, although +it is not quite the same as +.IR cat +.BR \(mis +since it removes any initial empty lines: +.sp +.RS 4 +.nf +\fB +sed \(min '/./,/^$/p' +.fi \fR +.P +.RE +.SH RATIONALE +This volume of POSIX.1\(hy2008 requires implementations to support at least ten distinct +.IR wfile s, +matching historical practice on many implementations. Implementations +are encouraged to support more, but conforming applications should not +exceed this limit. +.P +The exit status codes specified here are different from those in System +V. System V returns 2 for garbled +.IR sed +commands, but returns zero with its usage message or if the input file +could not be opened. The standard developers considered this to be a +bug. +.P +The manner in which the +.BR l +command writes non-printable characters was changed to avoid +the historical backspace-overstrike method, and other requirements to +achieve unambiguous output were added. See the RATIONALE for +.IR "\fIed\fR\^" +for details of the format chosen, which is the same as that chosen for +.IR sed . +.P +This volume of POSIX.1\(hy2008 requires implementations to provide pattern and hold spaces of at +least 8\|192 bytes, larger than the 4\|000 bytes spaces used by some +historical implementations, but less than the 20\|480 bytes limit used +in an early proposal. Implementations are encouraged to allocate +dynamically larger pattern and hold spaces as needed. +.P +The requirements for acceptance of + +and + +characters in command lines has been made more explicit than in early +proposals to describe clearly the historical practice and to remove +confusion about the phrase ``protect initial blanks [\fIsic\fP] and tabs +from the stripping that is done on every script line'' that appears in +much of the historical documentation of the +.IR sed +utility description of text. (Not all implementations are known to have +stripped + +characters from text lines, although they all have allowed leading + +characters preceding the address on a command line.) +.P +The treatment of +.BR '#' +comments differs from the SVID which only allows a comment as the first +line of the script, but matches BSD-derived implementations. The +comment character is treated as a command, and it has the same +properties in terms of being accepted with leading + +characters; the BSD implementation has historically supported this. +.P +Early proposals required that a +.IR script_file +have at least one non-comment line. Some historical implementations +have behaved in unexpected ways if this were not the case. The standard +developers considered that this was incorrect behavior and that +application developers should not have to avoid this feature. A correct +implementation of this volume of POSIX.1\(hy2008 shall permit +.IR script_file s +that consist only of comment lines. +.P +Early proposals indicated that if +.BR \(mie +and +.BR \(mif +options were intermixed, all +.BR \(mie +options were processed before any +.BR \(mif +options. This has been changed to process them in the order presented +because it matches historical practice and is more intuitive. +.P +The treatment of the +.BR p +flag to the +.BR s +command differs between System V and BSD-based systems when the default +output is suppressed. In the two examples: +.sp +.RS 4 +.nf +\fB +echo a | sed 's/a/A/p' +echo a | sed \(min 's/a/A/p' +.fi \fR +.P +.RE +.P +this volume of POSIX.1\(hy2008, BSD, System V documentation, and the SVID indicate that the +first example should write two lines with +.BR A , +whereas the second should write one. Some System V systems write the +.BR A +only once in both examples because the +.BR p +flag is ignored if the +.BR \(min +option is not specified. +.P +This is a case of a diametrical difference between systems that could +not be reconciled through the compromise of declaring the behavior to +be unspecified. The SVID/BSD/System V documentation behavior was +adopted for this volume of POSIX.1\(hy2008 because: +.IP " *" 4 +No known documentation for any historic system describes the +interaction between the +.BR p +flag and the +.BR \(min +option. +.IP " *" 4 +The selected behavior is more correct as there is no technical +justification for any interaction between the +.BR p +flag and the +.BR \(min +option. A relationship between +.BR \(min +and the +.BR p +flag might imply that they are only used together, but this ignores +valid scripts that interrupt the cyclical nature of the processing +through the use of the +.BR D , +.BR d , +.BR q , +or branching commands. Such scripts rely on the +.BR p +suffix to write the pattern space because they do not make use of the +default output at the ``bottom'' of the script. +.IP " *" 4 +Because the +.BR \(min +option makes the +.BR p +flag unnecessary, any interaction would only be useful if +.IR sed +scripts were written to run both with and without the +.BR \(min +option. This is believed to be unlikely. It is even more unlikely that +programmers have coded the +.BR p +flag expecting it to be unnecessary. Because the interaction was not +documented, the likelihood of a programmer discovering the interaction +and depending on it is further decreased. +.IP " *" 4 +Finally, scripts that break under the specified behavior produce too +much output instead of too little, which is easier to diagnose and +correct. +.P +The form of the substitute command that uses the +.BR n +suffix was limited to the first 512 matches in an early proposal. This +limit has been removed because there is no reason an editor processing +lines of +{LINE_MAX} +length should have this restriction. The command +.BR "s/a/A/2047" +should be able to substitute the 2\|047th occurrence of +.BR a +on a line. +.P +The +.BR b , +.BR t , +and +.BR : +commands are documented to ignore leading white space, but no mention +is made of trailing white space. Historical implementations of +.IR sed +assigned different locations to the labels +.BR 'x' +and +.BR \(dqx\ \(dq . +This is not useful, and leads to subtle programming errors, but it is +historical practice, and changing it could theoretically break working +scripts. Implementors are encouraged to provide warning messages about +labels that are never used or jumps to labels that do not exist. +.P +Historically, the +.IR sed +.BR ! +and +.BR } +editing commands did not permit multiple commands on a single line +using a + +as a command delimiter. Implementations are permitted, but not required, +to support this extension. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIawk\fR\^", +.IR "\fIed\fR\^", +.IR "\fIgrep\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/set.1p b/man-pages-posix-2013-a/man1p/set.1p new file mode 100644 index 0000000..8db4db1 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/set.1p @@ -0,0 +1,806 @@ +'\" et +.TH SET "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +set +\(em set or unset options and positional parameters +.SH SYNOPSIS +.LP +.nf +set \fB[\fR\(miabCefhmnuvx\fB] [\fR\(mio \fIoption\fB] [\fIargument\fR...\fB]\fR +.P +set \fB[\fR+abCefhmnuvx\fB] [\fR+o \fIoption\fB] [\fIargument\fR...\fB]\fR +.P +set \(mi\|\(mi\fB [\fIargument\fR...\fB]\fR +.P +set \(mio +.P +set +o +.fi +.SH DESCRIPTION +If no +.IR option s +or +.IR argument s +are specified, +.IR set +shall write the names and values of all shell variables in the collation +sequence of the current locale. Each +.IR name +shall start on a separate line, using the format: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +The +.IR value +string shall be written with appropriate quoting; see the description +of shell quoting in +.IR "Section 2.2" ", " "Quoting". +The output shall be suitable for reinput to the shell, setting or +resetting, as far as possible, the variables that are currently set; +read-only variables cannot be reset. +.P +When options are specified, they shall set or unset attributes of the +shell, as described below. When +.IR argument s +are specified, they cause positional parameters to be set or unset, as +described below. Setting or unsetting attributes and positional +parameters are not necessarily related actions, but they can be +combined in a single invocation of +.IR set . +.P +The +.IR set +special built-in shall support the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +except that options can be specified with either a leading + +(meaning enable the option) or + +(meaning disable it) unless otherwise specified. +.P +Implementations shall support the options in the following list in both +their + +and + +forms. These options can also be specified as options to +.IR sh . +.IP "\fB\(mia\fP" 6 +When this option is on, the +.IR export +attribute shall be set for each variable to which an assignment is +performed; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.22" ", " "Variable Assignment". +If the assignment precedes a utility name in a command, the +.IR export +attribute shall not persist in the current execution environment after +the utility completes, with the exception that preceding one of the +special built-in utilities causes the +.IR export +attribute to persist after the built-in has completed. If the +assignment does not precede a utility name in the command, or if the +assignment is a result of the operation of the +.IR getopts +or +.IR read +utilities, the +.IR export +attribute shall persist until the variable is unset. +.IP "\fB\(mib\fP" 6 +This option shall be supported if the implementation supports the User +Portability Utilities option. It shall cause the shell to notify the +user asynchronously of background job completions. The following +message is written to standard error: +.RS 6 +.sp +.RS 4 +.nf +\fB +"[%d]%c %s%s\en", <\fIjob-number\fR>, <\fIcurrent\fR>, <\fRstatus\fR>, <\fRjob-name\fR> +.fi \fR +.P +.RE +.P +where the fields shall be as follows: +.IP "<\fIcurrent\fR>" 12 +The character +.BR '+' +identifies the job that would be used as a default for the +.IR fg +or +.IR bg +utilities; this job can also be specified using the +.IR job_id +.BR \(dq%+\(dq +or +.BR \(dq%%\(dq . +The character +.BR '\(mi' +identifies the job that would become the +default if the current default job were to exit; this job can also be +specified using the +.IR job_id +.BR \(dq%\(mi\(dq . +For other jobs, this field is a +. +At most one job can be identified with +.BR '+' +and at most one job can be identified with +.BR '\(mi' . +If there is any suspended job, then the current job shall be a +suspended job. If there are at least two suspended jobs, then the +previous job also shall be a suspended job. +.IP "<\fIjob-number\fR>" 12 +A number that can be used to identify the process group to the +.IR wait , +.IR fg , +.IR bg , +and +.IR kill +utilities. Using these utilities, the job can be identified by +prefixing the job number with +.BR '%' . +.IP "<\fIstatus\fR>" 12 +Unspecified. +.IP "<\fIjob-name\fR>" 12 +Unspecified. +.P +When the shell notifies the user a job has been completed, it may +remove the job's process ID from the list of those known in the current +shell execution environment; see +.IR "Section 2.9.3.1" ", " "Examples". +Asynchronous notification shall not be enabled by default. +.RE +.IP "\fB\(miC\fP" 6 +(Uppercase C.) Prevent existing files from being overwritten by the +shell's +.BR '>' +redirection operator (see +.IR "Section 2.7.2" ", " "Redirecting Output"); +the +.BR \(dq>|\(dq +redirection operator shall override this +.IR noclobber +option for an individual file. +.IP "\fB\(mie\fP" 6 +When this option is on, when any command fails (for any of the reasons +listed in +.IR "Section 2.8.1" ", " "Consequences of Shell Errors" +or by returning an exit status greater than zero), the shell immediately +shall exit with the following exceptions: +.RS 6 +.IP " 1." 4 +The failure of any individual command in a multi-command pipeline shall +not cause the shell to exit. Only the failure of the pipeline itself +shall be considered. +.IP " 2." 4 +The +.BR \(mie +setting shall be ignored when executing the compound list following the +.BR while , +.BR until , +.BR if , +or +.BR elif +reserved word, a pipeline beginning with the +.BR ! +reserved word, or any command of an AND-OR list other than the last. +.IP " 3." 4 +If the exit status of a compound command other than a subshell command +was the result of a failure while +.BR \(mie +was being ignored, then +.BR \(mie +shall not apply to this command. +.P +This requirement applies to the shell environment and each subshell +environment separately. For example, in: +.sp +.RS 4 +.nf +\fB +set -e; (false; echo one) | cat; echo two +.fi \fR +.P +.RE +.P +the +.IR false +command causes the subshell to exit without executing +.IR "echo one" ; +however, +.IR "echo two" +is executed because the exit status of the pipeline +.IR "(false; echo one) | cat" +is zero. +.RE +.IP "\fB\(mif\fP" 6 +The shell shall disable pathname expansion. +.IP "\fB\(mih\fP" 6 +Locate and remember utilities invoked by functions as those functions +are defined (the utilities are normally located when the function is +executed). +.IP "\fB\(mim\fP" 6 +This option shall be supported if the implementation supports the User +Portability Utilities option. All jobs shall be run in their own +process groups. Immediately before the shell issues a prompt after +completion of the background job, a message reporting the exit status +of the background job shall be written to standard error. If a +foreground job stops, the shell shall write a message to standard error +to that effect, formatted as described by the +.IR jobs +utility. In addition, if a job changes status other than exiting (for +example, if it stops for input or output or is stopped by a SIGSTOP +signal), the shell shall write a similar message immediately prior to +writing the next prompt. This option is enabled by default for +interactive shells. +.IP "\fB\(min\fP" 6 +The shell shall read commands but does not execute them; this can be +used to check for shell script syntax errors. An interactive shell may +ignore this option. +.IP "\fB\(mio\fP" 6 +Write the current settings of the options to standard output in an +unspecified format. +.IP "\fB+o\fP" 6 +Write the current option settings to standard output in a format that +is suitable for reinput to the shell as commands that achieve the same +options settings. +.IP "\fB\(mio\ \fIoption\fR" 6 +.br +This option is supported if the system supports the User Portability +Utilities option. It shall set various options, many of which shall be +equivalent to the single option letters. The following values of +.IR option +shall be supported: +.RS 6 +.IP "\fIallexport\fR" 10 +Equivalent to +.BR \(mia . +.IP "\fIerrexit\fR" 10 +Equivalent to +.BR \(mie . +.IP "\fIignoreeof\fR" 10 +Prevent an interactive shell from exiting on end-of-file. This setting +prevents accidental logouts when +\(hyD +is entered. A user shall explicitly +.IR exit +to leave the interactive shell. +.IP "\fImonitor\fR" 10 +Equivalent to +.BR \(mim . +This option is supported if the system supports the User Portability +Utilities option. +.IP "\fInoclobber\fR" 10 +Equivalent to +.BR \(miC +(uppercase C). +.IP "\fInoglob\fR" 10 +Equivalent to +.BR \(mif . +.IP "\fInoexec\fR" 10 +Equivalent to +.BR \(min . +.IP "\fInolog\fR" 10 +Prevent the entry of function definitions into the command history; see +.IR "Command History List". +.IP "\fInotify\fR" 10 +Equivalent to +.BR \(mib . +.IP "\fInounset\fR" 10 +Equivalent to +.BR \(miu . +.IP "\fIverbose\fR" 10 +Equivalent to +.BR \(miv . +.IP "\fIvi\fR" 10 +Allow shell command line editing using the built-in +.IR vi +editor. Enabling +.IR vi +mode shall disable any other command line editing mode provided as an +implementation extension. +.RS 10 +.P +It need not be possible to set +.IR vi +mode on for certain block-mode terminals. +.RE +.IP "\fIxtrace\fR" 10 +Equivalent to +.BR \(mix . +.RE +.IP "\fB\(miu\fP" 6 +When the shell tries to expand an unset parameter other than the +.BR '@' +and +.BR '*' +special parameters, it shall write a message to standard error and shall +not execute the command containing the expansion, but for the purposes +of setting the +.BR '?' +special parameter and the exit status of the shell the command shall be +treated as having been executed and returned an exit status of between +1 and 125 inclusive. A non-interactive shell shall immediately exit. An +interactive shell shall not exit. +.IP "\fB\(miv\fP" 6 +The shell shall write its input to standard error as it is read. +.IP "\fB\(mix\fP" 6 +The shell shall write to standard error a trace for each command after +it expands the command and before it executes it. It is unspecified +whether the command that turns tracing off is traced. +.P +The default for all these options shall be off (unset) unless stated +otherwise in the description of the option or unless the shell was +invoked with them on; see +.IR sh . +.P +The remaining arguments shall be assigned in order to the positional +parameters. The special parameter +.BR '#' +shall be set to reflect the number of positional parameters. All +positional parameters shall be unset before any new values are +assigned. +.P +If the first argument is +.BR '\(mi' , +the results are unspecified. +.P +The special argument +.BR \(dq\(mi\|\(mi\(dq +immediately following the +.IR set +command name can be used to delimit the arguments if the first argument +begins with +.BR '+' +or +.BR '\(mi' , +or to prevent inadvertent listing of all shell variables when there are +no arguments. The command +.IR set +.BR \(mi\|\(mi +without +.IR argument +shall unset all positional parameters and set the special parameter +.BR '#' +to zero. +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Application writers should avoid relying on +.IR set +.BR \(mie +within functions. For example, in the following script: +.sp +.RS 4 +.nf +\fB +set -e +start() { + some_server + echo some_server started successfully +} +start || echo >&2 some_server failed +.fi \fR +.P +.RE +.P +the +.BR \(mie +setting is ignored within the function body (because the function is a +command in an AND-OR list other than the last). Therefore, if +.IR some_server +fails, the function carries on to echo +.BR \(dqsome_server started successfully\(dq , +and the exit status of the function is zero (which means +.BR \(dqsome_server failed\(dq +is not output). +.SH EXAMPLES +Write out all variables and their values: +.sp +.RS 4 +.nf +\fB +set +.fi \fR +.P +.RE +.P +Set $1, $2, and $3 and set +.BR \(dq$#\(dq +to 3: +.sp +.RS 4 +.nf +\fB +set c a b +.fi \fR +.P +.RE +.P +Turn on the +.BR \(mix +and +.BR \(miv +options: +.sp +.RS 4 +.nf +\fB +set \(mixv +.fi \fR +.P +.RE +.P +Unset all positional parameters: +.sp +.RS 4 +.nf +\fB +set \(mi\|\(mi +.fi \fR +.P +.RE +.P +Set $1 to the value of +.IR x , +even if it begins with +.BR '\(mi' +or +.BR '+' : +.sp +.RS 4 +.nf +\fB +set \(mi\|\(mi "$x" +.fi \fR +.P +.RE +.P +Set the positional parameters to the expansion of +.IR x , +even if +.IR x +expands with a leading +.BR '\(mi' +or +.BR '+' : +.sp +.RS 4 +.nf +\fB +set \(mi\|\(mi $x +.fi \fR +.P +.RE +.SH "RATIONALE" +The +.IR set +\(mi\|\(mi form is listed specifically in the SYNOPSIS even though this +usage is implied by the Utility Syntax Guidelines. The explanation of +this feature removes any ambiguity about whether the +.IR set +\(mi\|\(mi form might be misinterpreted as being equivalent to +.IR set +without any options or arguments. The functionality of this form has +been adopted from the KornShell. In System V, +.IR set +\(mi\|\(mi only unsets parameters if there is at least one argument; +the only way to unset all parameters is to use +.IR shift . +Using the KornShell version should not affect System V scripts because +there should be no reason to issue it without arguments deliberately; +if it were issued as, for example: +.sp +.RS 4 +.nf +\fB +set \(mi\|\(mi "$@" +.fi \fR +.P +.RE +.P +and there were in fact no arguments resulting from +.BR \(dq$@\(dq , +unsetting the parameters would have no result. +.P +The +.IR set ++ form in early proposals was omitted as being an unnecessary +duplication of +.IR set +alone and not widespread historical practice. +.P +The +.IR noclobber +option was changed to allow +.IR set +.BR \(miC +as well as the +.IR set +.BR \(mio +.IR noclobber +option. The single-letter version was added so that the historical +.BR \(dq$\(mi\(dq +paradigm would not be broken; see +.IR "Section 2.5.2" ", " "Special Parameters". +.P +The description of the +.BR \(mie +option is intended to match the behavior of the 1988 version of the +KornShell. +.P +The +.BR \(mih +flag is related to command name hashing. See +.IR "\fIhash\fR\^". +.P +The following +.IR set +flags were omitted intentionally with the following rationale: +.IP "\fB\(mik\fP" 6 +The +.BR \(mik +flag was originally added by the author of the Bourne shell to make it +easier for users of pre-release versions of the shell. In early +versions of the Bourne shell the construct +.IR set +.IR name =\c +.IR value +had to be used to assign values to shell variables. The problem with +.BR \(mik +is that the behavior affects parsing, virtually precluding writing any +compilers. To explain the behavior of +.BR \(mik , +it is necessary to describe the parsing algorithm, which is +implementation-defined. For example: +.RS 6 +.sp +.RS 4 +.nf +\fB +set \(mik; echo \fIname\fR=\fIvalue\fR +.fi \fR +.P +.RE +.P +and: +.sp +.RS 4 +.nf +\fB +set \(mik +echo \fIname\fP=\fIvalue\fR +.fi \fR +.P +.RE +.P +behave differently. The interaction with functions is even more +complex. What is more, the +.BR \(mik +flag is never needed, since the command line could have been +reordered. +.RE +.IP "\fB\(mit\fP" 6 +The +.BR \(mit +flag is hard to specify and almost never used. The only known use could +be done with here-documents. Moreover, the behavior with +.IR ksh +and +.IR sh +differs. The reference page says that it exits after reading and +executing one command. What is one command? If the input is +.IR date ;\c +.IR date , +.IR sh +executes both +.IR date +commands while +.IR ksh +does only the first. +.P +Consideration was given to rewriting +.IR set +to simplify its confusing syntax. A specific suggestion was that the +.IR unset +utility should be used to unset options instead of using the non-\c +\fIgetopt\fR()\c +-able +\c +.IR option +syntax. However, the conclusion was reached that the historical +practice of using +\c +.IR option +was satisfactory and that there was no compelling reason to modify such +widespread historical practice. +.P +The +.BR \(mio +option was adopted from the KornShell to address user needs. In +addition to its generally friendly interface, +.BR \(mio +is needed to provide the +.IR vi +command line editing mode, for which historical practice yields no +single-letter option name. (Although it might have been possible to +invent such a letter, it was recognized that other editing modes would +be developed and +.BR \(mio +provides ample name space for describing such extensions.) +.P +Historical implementations are inconsistent in the format used for +.BR \(mio +option status reporting. The +.BR +o +format without an option-argument was added to allow portable access to +the options that can be saved and then later restored using, for +instance, a dot script. +.P +Historically, +.IR sh +did trace the command +.IR set +.BR +x , +but +.IR ksh +did not. +.P +The +.IR ignoreeof +setting prevents accidental logouts when the end-of-file character +(typically +\(hyD) +is entered. A user shall explicitly +.IR exit +to leave the interactive shell. +.P +The +.IR set +.BR \(mim +option was added to apply only to the UPE because it applies primarily +to interactive use, not shell script applications. +.P +The ability to do asynchronous notification became available in the +1988 version of the KornShell. To have it occur, the user had to issue +the command: +.sp +.RS 4 +.nf +\fB +trap "jobs \(min" CLD +.fi \fR +.P +.RE +.P +The C shell provides two different levels of an asynchronous +notification capability. The environment variable +.IR notify +is analogous to what is done in +.IR set +.BR \(mib +or +.IR set +.BR \(mio +.IR notify . +When set, it notifies the user immediately of background job +completions. When unset, this capability is turned off. +.P +The other notification ability comes through the built-in utility +.IR notify . +The syntax is: +.sp +.RS 4 +.nf +\fB +notify \fB[\fR%job ... \fB]\fR +.fi \fR +.P +.RE +.P +By issuing +.IR notify +with no operands, it causes the C shell to notify the user +asynchronously when the state of the current job changes. If given +operands, +.IR notify +asynchronously informs the user of changes in the states of the +specified jobs. +.P +To add asynchronous notification to the POSIX shell, neither the +KornShell extensions to +.IR trap , +nor the C shell +.IR notify +environment variable seemed appropriate (\c +.IR notify +is not a proper POSIX environment variable name). +.P +The +.IR set +.BR \(mib +option was selected as a compromise. +.P +The +.IR notify +built-in was considered to have more functionality than was required +for simple asynchronous notification. +.P +Historically, some shells applied the +.BR \(miu +option to all parameters including +.IR $@ +and +.IR $* . +The standard developers felt that this was a misfeature since it is +normal and common for +.IR $@ +and +.IR $* +to be used in shell scripts regardless of whether they were passed any +arguments. Treating these uses as an error when no arguments are passed +reduces the value of +.BR \(miu +for its intended purpose of finding spelling mistakes in variable names +and uses of unset positional parameters. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIhash\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.22" ", " "Variable Assignment", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/sh.1p b/man-pages-posix-2013-a/man1p/sh.1p new file mode 100644 index 0000000..d280223 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/sh.1p @@ -0,0 +1,1729 @@ +'\" et +.TH SH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sh +\(em shell, the standard command language interpreter +.SH SYNOPSIS +.LP +.nf +sh \fB[\fR\(miabCefhimnuvx\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR... + \fB[\fIcommand_file \fB[\fIargument\fR...\fB]]\fR +.P +sh \(mic \fB[\fR\(miabCefhimnuvx\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR... + \fIcommand_string \fB[\fIcommand_name \fB[\fIargument\fR...\fB]]\fR +.P +sh \(mis \fB[\fR\(miabCefhimnuvx\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR... + \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR sh +utility is a command language interpreter that shall execute commands +read from a command line string, the standard input, or a specified +file. The application shall ensure that the commands to be executed are +expressed in the language described in +.IR "Chapter 2" ", " "Shell Command Language". +.P +Pathname expansion shall not fail due to the size of a file. +.P +Shell input and output redirections have an implementation-defined +offset maximum that is established in the open file description. +.SH OPTIONS +The +.IR sh +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +with an extension for support of a leading + +(\c +.BR '\(pl' ) +as noted below. +.P +The +.BR \(mia , +.BR \(mib , +.BR \(miC , +.BR \(mie , +.BR \(mif , +.BR \(mim , +.BR \(min , +.BR \(mio +.IR option , +.BR \(miu , +.BR \(miv , +and +.BR \(mix +options are described as part of the +.IR set +utility in +.IR "Section 2.14" ", " "Special Built-In Utilities". +The option letters derived from the +.IR set +special built-in shall also be accepted with a leading + +(\c +.BR '\(pl' ) +instead of a leading + +(meaning the reverse case of the option as described in this volume of POSIX.1\(hy2008). +.P +The following additional options shall be supported: +.IP "\fB\(mic\fP" 10 +Read commands from the +.IR command_string +operand. Set the value of special parameter 0 (see +.IR "Section 2.5.2" ", " "Special Parameters") +from the value of the +.IR command_name +operand and the positional parameters ($1, $2, and so on) in sequence +from the remaining +.IR argument +operands. No commands shall be read from the standard input. +.IP "\fB\(mii\fP" 10 +Specify that the shell is +.IR interactive ; +see below. An implementation may treat specifying the +.BR \(mii +option as an error if the real user ID of the calling process does not +equal the effective user ID or if the real group ID does not equal the +effective group ID. +.IP "\fB\(mis\fP" 10 +Read commands from the standard input. +.P +If there are no operands and the +.BR \(mic +option is not specified, the +.BR \(mis +option shall be assumed. +.P +If the +.BR \(mii +option is present, or if there are no operands and the shell's standard +input and standard error are attached to a terminal, the shell is +considered to be +.IR interactive . +.SH OPERANDS +The following operands shall be supported: +.IP "\fR\(mi\fR" 10 +A single + +shall be treated as the first operand and then ignored. If both +.BR '\(mi' +and +.BR \(dq\(mi\|\(mi\(dq +are given as arguments, or if other operands precede the single +, +the results are undefined. +.IP "\fIargument\fR" 10 +The positional parameters ($1, $2, and so on) shall be set to +.IR arguments , +if any. +.IP "\fIcommand_file\fR" 10 +The pathname of a file containing commands. If the pathname contains +one or more + +characters, the implementation attempts to read that file; the file need +not be executable. If the pathname does not contain a + +character: +.RS 10 +.IP " *" 4 +The implementation shall attempt to read that file from the current +working directory; the file need not be executable. +.IP " *" 4 +If the file is not in the current working directory, the implementation +may perform a search for an executable file using the value of +.IR PATH , +as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +.P +Special parameter 0 (see +.IR "Section 2.5.2" ", " "Special Parameters") +shall be set to the value of +.IR command_file . +If +.IR sh +is called using a synopsis form that omits +.IR command_file , +special parameter 0 shall be set to the value of the first argument +passed to +.IR sh +from its parent (for example, +.IR argv [0] +for a C program), which is normally a pathname used to execute the +.IR sh +utility. +.RE +.IP "\fIcommand_name\fR" 10 +.br +A string assigned to special parameter 0 when executing the commands in +.IR command_string . +If +.IR command_name +is not specified, special parameter 0 shall be set to the value of the +first argument passed to +.IR sh +from its parent (for example, +.IR argv [0] +for a C program), which is normally a pathname used to execute the +.IR sh +utility. +.IP "\fIcommand_string\fR" 10 +.br +A string that shall be interpreted by the shell as one or more +commands, as if the string were the argument to the +\fIsystem\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. If the +.IR command_string +operand is an empty string, +.IR sh +shall exit with a zero exit status. +.SH STDIN +The standard input shall be used only if one of the following is true: +.IP " *" 4 +The +.BR \(mis +option is specified. +.IP " *" 4 +The +.BR \(mic +option is not specified and no operands are specified. +.IP " *" 4 +The script executes one or more commands that require input from +standard input (such as a +.IR read +command that does not redirect its input). +.P +See the INPUT FILES section. +.P +When the shell is using standard input and it invokes a command that +also uses standard input, the shell shall ensure that the standard +input file pointer points directly after the command it has read when +the command begins execution. It shall not read ahead in such a manner +that any characters intended to be read by the invoked command are +consumed by the shell (whether interpreted by the shell or not) or that +characters that are not read by the invoked command are not seen by the +shell. When the command expecting to read standard input is started +asynchronously by an interactive shell, it is unspecified whether +characters are read by the command or interpreted by the shell. +.P +If the standard input to +.IR sh +is a FIFO or terminal device and is set to non-blocking reads, then +.IR sh +shall enable blocking reads on standard input. This shall remain in +effect when the command completes. +.SH "INPUT FILES" +The input file shall be a text file, except that line lengths shall be +unlimited. If the input file is empty or consists solely of blank +lines or comments, or both, +.IR sh +shall exit with a zero exit status. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sh : +.IP "\fIENV\fP" 10 +This variable, when and only when an interactive shell is invoked, +shall be subjected to parameter expansion (see +.IR "Section 2.6.2" ", " "Parameter Expansion") +by the shell, and the resulting value shall be used as a pathname of a +file containing shell commands to execute in the current environment. +The file need not be executable. If the expanded value of +.IR ENV +is not an absolute pathname, the results are unspecified. +.IR ENV +shall be ignored if the real and effective user IDs or real and +effective group IDs of the process are different. +.IP "\fIFCEDIT\fP" 10 +This variable, when expanded by the shell, shall determine the default +value for the +.BR \(mie +.IR editor +option's +.IR editor +option-argument. If +.IR FCEDIT +is null or unset, +.IR ed +shall be used as the editor. +.IP "\fIHISTFILE\fP" 10 +Determine a pathname naming a command history file. If the +.IR HISTFILE +variable is not set, the shell may attempt to access or create a file +.BR .sh_history +in the directory referred to by the +.IR HOME +environment variable. If the shell cannot obtain both read and +write access to, or create, the history file, it shall use an +unspecified mechanism that allows the history to operate properly. +(References to history ``file'' in this section shall be understood to +mean this unspecified mechanism in such cases.) An implementation may +choose to access this variable only when initializing the history file; +this initialization shall occur when +.IR fc +or +.IR sh +first attempt to retrieve entries from, or add entries to, the file, as +the result of commands issued by the user, the file named by the +.IR ENV +variable, or implementation-defined system start-up files. +Implementations may choose to disable the history list mechanism for +users with appropriate privileges who do not set +.IR HISTFILE ; +the specific circumstances under which this occurs are +implementation-defined. If more than one instance of the shell is +using the same history file, it is unspecified how updates to the +history file from those shells interact. As entries are deleted from +the history file, they shall be deleted oldest first. It is +unspecified when history file entries are physically removed from the +history file. +.IP "\fIHISTSIZE\fP" 10 +Determine a decimal number representing the limit to the number of +previous commands that are accessible. If this variable is unset, an +unspecified default greater than or equal to 128 shall be used. The +maximum number of commands in the history list is unspecified, but +shall be at least 128. An implementation may choose to access this +variable only when initializing the history file, as described under +.IR HISTFILE . +Therefore, it is unspecified whether changes made to +.IR HISTSIZE +after the history file has been initialized are effective. +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory. The contents of +.IR HOME +are used in tilde expansion as described in +.IR "Section 2.6.1" ", " "Tilde Expansion". +.IP "\fIIFS\fP" 10 +A string treated as a list of characters that is used for field +splitting and to split lines into fields with the +.IR read +command. +.RS 10 +.P +If +.IR IFS +is not set, it shall behave as normal for an unset variable, except +that field splitting by the shell and line splitting by the +.IR read +command shall be performed as if the value of +.IR IFS +is +\c +\c +; +see +.IR "Section 2.6.5" ", " "Field Splitting". +.P +Implementations may ignore the value of +.IR IFS +in the environment, or the absence of +.IR IFS +from the environment, at the time the shell is invoked, in which case +the shell shall set +.IR IFS +to +\c +\c + +when it is invoked. +.RE +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the behavior of range expressions, equivalence classes, and +multi-character collating elements within pattern matching. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), which characters +are defined as letters (character class +.BR alpha ), +and the behavior of character classes within pattern matching. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fIMAIL\fP" 10 +Determine a pathname of the user's mailbox file for purposes of +incoming mail notification. If this variable is set, the shell shall +inform the user if the file named by the variable is created or if its +modification time has changed. Informing the user shall be accomplished +by writing a string of unspecified format to standard error prior to +the writing of the next primary prompt string. Such check shall be +performed only after the completion of the interval defined by the +.IR MAILCHECK +variable after the last such check. The user shall be informed only if +.IR MAIL +is set and +.IR MAILPATH +is not set. +.IP "\fIMAILCHECK\fP" 10 +.br +Establish a decimal integer value that specifies how often (in seconds) +the shell shall check for the arrival of mail in the files specified by +the +.IR MAILPATH +or +.IR MAIL +variables. The default value shall be 600 seconds. If set to zero, +the shell shall check before issuing each primary prompt. +.IP "\fIMAILPATH\fP" 10 +Provide a list of pathnames and optional messages separated by + +characters. If this variable is set, the shell shall inform the user if +any of the files named by the variable are created or if any of their +modification times change. (See the preceding entry for +.IR MAIL +for descriptions of mail arrival and user informing.) Each pathname can +be followed by +.BR '%' +and a string that shall be subjected to parameter expansion and written +to standard error when the modification time changes. If a +.BR '%' +character in the pathname is preceded by a +, +it shall be treated as a literal +.BR '%' +in the pathname. The default message is unspecified. +.RS 10 +.P +The +.IR MAILPATH +environment variable takes precedence over the +.IR MAIL +variable. +.RE +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Establish a string formatted as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +used to effect command interpretation; see +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +.IP "\fIPWD\fP" 10 +This variable shall represent an absolute pathname of the current +working directory. Assignments to this variable may be ignored. +.SH "ASYNCHRONOUS EVENTS" +The +.IR sh +utility shall take the standard action for all signals (see +.IR "Section 1.4" ", " "Utility Description Defaults") +with the following exceptions. +.P +If the shell is interactive, SIGINT signals received during command +line editing shall be handled as described in the EXTENDED DESCRIPTION, +and SIGINT signals received at other times shall be caught but no action +performed. +.P +If the shell is interactive: +.IP " *" 4 +SIGQUIT and SIGTERM signals shall be ignored. +.IP " *" 4 +If the +.BR \(mim +option is in effect, SIGTTIN, SIGTTOU, and SIGTSTP signals shall be +ignored. +.IP " *" 4 +If the +.BR \(mim +option is not in effect, it is unspecified whether SIGTTIN, SIGTTOU, +and SIGTSTP signals are ignored, set to the default action, or caught. +If they are caught, the shell shall, in the signal-catching function, +set the signal to the default action and raise the signal (after taking +any appropriate steps, such as restoring terminal settings). +.P +The standard actions, and the actions described above for interactive +shells, can be overridden by use of the +.IR trap +special built-in utility (see +.IR "\fItrap\fR\^" +and +.IR "Section 2.11" ", " "Signals and Error Handling"). +.SH STDOUT +See the STDERR section. +.SH STDERR +Except as otherwise stated (by the descriptions of any invoked +utilities or in interactive mode), standard error shall be used +only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +See +.IR "Chapter 2" ", " "Shell Command Language". +The functionality described in the rest of the EXTENDED DESCRIPTION +section shall be provided on implementations that support the User +Portability Utilities option +(and the rest of this section is not further shaded for this option). +.SS "Command History List" +.P +When the +.IR sh +utility is being used interactively, it shall maintain a list of +commands previously entered from the terminal in the file named by the +.IR HISTFILE +environment variable. The type, size, and internal format of this file +are unspecified. Multiple +.IR sh +processes can share access to the file for a user, if file access +permissions allow this; see the description of the +.IR HISTFILE +environment variable. +.SS "Command Line Editing" +.P +When +.IR sh +is being used interactively from a terminal, the current command and +the command history (see +.IR "\fIfc\fR\^") +can be edited using +.IR vi -mode +command line editing. This mode uses commands, described below, +similar to a subset of those described in the +.IR vi +utility. Implementations may offer other command line editing modes +corresponding to other editing utilities. +.P +The command +.IR set +.BR \(mio +.IR vi +shall enable +.IR vi -mode +editing and place +.IR sh +into +.IR vi +insert mode (see +.IR "Command Line Editing (vi-mode)"). +This command also shall disable any other editing mode that the +implementation may provide. The command +.IR set +.BR +o +.IR vi +disables +.IR vi -mode +editing. +.P +Certain block-mode terminals may be unable to support shell command +line editing. If a terminal is unable to provide either edit mode, it +need not be possible to +.IR set +.BR \(mio +.IR vi +when using the shell on this terminal. +.P +In the following sections, the characters +.IR erase , +.IR interrupt , +.IR kill , +and +.IR end-of-file +are those set by the +.IR stty +utility. +.SS "Command Line Editing (vi-mode)" +.P +In +.IR vi +editing mode, there shall be a distinguished line, the edit line. All +the editing operations which modify a line affect the edit line. The +edit line is always the newest line in the command history buffer. +.P +With +.IR vi -mode +enabled, +.IR sh +can be switched between insert mode and command mode. +.P +When in insert mode, an entered character shall be inserted into the +command line, except as noted in +.IR "vi Line Editing Insert Mode". +Upon entering +.IR sh +and after termination of the previous command, +.IR sh +shall be in insert mode. +.P +Typing an escape character shall switch +.IR sh +into command mode (see +.IR "vi Line Editing Command Mode"). +In command mode, an entered character shall either invoke a defined +operation, be used as part of a multi-character operation, or be +treated as an error. A character that is not recognized as part of an +editing command shall terminate any specific editing command and shall +alert the terminal. If +.IR sh +receives a SIGINT signal in command mode (whether generated by typing the +.IR interrupt +character or by other means), it shall terminate command line editing +on the current command line, reissue the prompt on the next line of the +terminal, and reset the command history (see +.IR "\fIfc\fR\^") +so that the most recently executed command is the previous command +(that is, the command that was being edited when it was interrupted is +not re-entered into the history). +.P +In the following sections, the phrase ``move the cursor to the +beginning of the word'' shall mean ``move the cursor to the first +character of the current word'' and the phrase ``move the cursor to the +end of the word'' shall mean ``move the cursor to the last character of +the current word''. The phrase ``beginning of the command line'' +indicates the point between the end of the prompt string issued by the +shell (or the beginning of the terminal line, if there is no prompt +string) and the first character of the command text. +.SS "vi Line Editing Insert Mode" +.P +While in insert mode, any character typed shall be inserted in the +current command line, unless it is from the following set. +.IP 10 +Execute the current command line. If the current command line is not +empty, this line shall be entered into the command history (see +.IR "\fIfc\fR\^"). +.IP "\fIerase\fR" 10 +Delete the character previous to the current cursor position and move +the current cursor position back one character. In insert mode, +characters shall be erased from both the screen and the buffer when +backspacing. +.IP "\fIinterrupt\fR" 10 +If +.IR sh +receives a SIGINT signal in insert mode (whether generated by typing +the +.IR interrupt +character or by other means), it shall terminate command line editing +with the same effects as described for interrupting command mode; see +.IR "Command Line Editing (vi-mode)". +.IP "\fIkill\fR" 10 +Clear all the characters from the input line. +.IP "\(hyV" 10 +Insert the next character input, even if the character is otherwise a +special insert mode character. +.IP "\(hyW" 10 +Delete the characters from the one preceding the cursor to the +preceding word boundary. The word boundary in this case is the closer +to the cursor of either the beginning of the line or a character that +is in neither the +.BR blank +nor +.BR punct +character classification of the current locale. +.IP "\fIend-of-file\fR" 10 +Interpreted as the end of input in +.IR sh . +This interpretation shall occur only at the beginning of an input +line. If +.IR end-of-file +is entered other than at the beginning of the line, the results are +unspecified. +.IP 10 +Place +.IR sh +into command mode. +.SS "vi Line Editing Command Mode" +.P +In command mode for the command line editing feature, decimal digits +not beginning with 0 that precede a command letter shall be +remembered. Some commands use these decimal digits as a count number +that affects the operation. +.P +The term +.IR "motion command" +represents one of the commands: +.sp +.RS 4 +.nf +\fB + 0 b F l W ^ $ ; E f T w | , B e h t +.fi \fR +.P +.RE +.P +If the current line is not the edit line, any command that modifies the +current line shall cause the content of the current line to replace the +content of the edit line, and the current line shall become the edit +line. This replacement cannot be undone (see the +.BR u +and +.BR U +commands below). The modification requested shall then be performed to +the edit line. When the current line is the edit line, the modification +shall be done directly to the edit line. +.P +Any command that is preceded by +.IR count +shall take a count (the numeric value of any preceding decimal +digits). Unless otherwise noted, this count shall cause the specified +operation to repeat by the number of times specified by the count. +Also unless otherwise noted, a +.IR count +that is out of range is considered an error condition and shall alert +the terminal, but neither the cursor position, nor the command line, +shall change. +.P +The terms +.IR word +and +.IR bigword +are used as defined in the +.IR vi +description. The term +.IR "save buffer" +corresponds to the term +.IR "unnamed buffer" +in +.IR vi . +.P +The following commands shall be recognized in command mode: +.IP 10 +Execute the current command line. If the current command line is not +empty, this line shall be entered into the command history (see +.IR "\fIfc\fR\^"). +.IP "\(hyL" 10 +Redraw the current command line. Position the cursor at the same +location on the redrawn line. +.IP "\fB#\fP" 10 +Insert the character +.BR '#' +at the beginning of the current command line and treat the resulting +edit line as a comment. This line shall be entered into the command +history; see +.IR "\fIfc\fR\^". +.IP "\fB=\fP" 10 +Display the possible shell word expansions (see +.IR "Section 2.6" ", " "Word Expansions") +of the bigword at the current command line position. +.RS 10 +.TP 10 +.BR Note: +This does not modify the content of the current line, and therefore +does not cause the current line to become the edit line. +.P +.P +These expansions shall be displayed on subsequent terminal lines. If +the bigword contains none of the characters +.BR '?' , +.BR '*' , +or +.BR '[' , +an + +(\c +.BR '*' ) +shall be implicitly assumed at the end. If any directories are +matched, these expansions shall have a +.BR '/' +character appended. After the expansion, the line shall be redrawn, +the cursor repositioned at the current cursor position, and +.IR sh +shall be placed in command mode. +.RE +.IP "\fB\e\fR" 10 +Perform pathname expansion (see +.IR "Section 2.6.6" ", " "Pathname Expansion") +on the current bigword, up to the largest set of characters that can be +matched uniquely. If the bigword contains none of the characters +.BR '?' , +.BR '*' , +or +.BR '[' , +an + +(\c +.BR '*' ) +shall be implicitly assumed at the end. This maximal expansion then +shall replace the original bigword in the command line, and the cursor +shall be placed after this expansion. If the resulting bigword +completely and uniquely matches a directory, a +.BR '/' +character shall be inserted directly after the bigword. If some other +file is completely matched, a single + +shall be inserted after the bigword. After this operation, +.IR sh +shall be placed in insert mode. +.IP "\fB*\fR" 10 +Perform pathname expansion on the current bigword and insert all +expansions into the command to replace the current bigword, with each +expansion separated by a single +. +If at the end of the line, the current cursor position shall be moved +to the first column position following the expansions and +.IR sh +shall be placed in insert mode. Otherwise, the current cursor position +shall be the last column position of the first character after the +expansions and +.IR sh +shall be placed in insert mode. If the current bigword contains none +of the characters +.BR '?' , +.BR '*' , +or +.BR '[' , +before the operation, an + +(\c +.BR '*' ) +shall be implicitly assumed at the end. +.IP "\fB@\fIletter\fR" 10 +Insert the value of the alias named +.IR _letter . +The symbol +.IR letter +represents a single alphabetic character from the portable character +set; implementations may support additional characters as an +extension. If the alias +.IR _letter +contains other editing commands, these commands shall be performed as +part of the insertion. If no alias +.IR _letter +is enabled, this command shall have no effect. +.IP "\fB[\fIcount\fB]~\fR" 10 +Convert, if the current character is a lowercase letter, to the +equivalent uppercase letter and +.IR "vice versa" , +as prescribed by the current locale. The current cursor position then +shall be advanced by one character. If the cursor was positioned on +the last character of the line, the case conversion shall occur, but +the cursor shall not advance. If the +.BR '~' +command is preceded by a +.IR count , +that number of characters shall be converted, and the cursor shall be +advanced to the character position after the last character converted. +If the +.IR count +is larger than the number of characters after the cursor, this shall +not be considered an error; the cursor shall advance to the last +character on the line. +.IP "\fB[\fIcount\fB].\fR" 10 +Repeat the most recent non-motion command, even if it was executed on +an earlier command line. If the previous command was preceded by a +.IR count , +and no count is given on the +.BR '.' +command, the count from the previous command shall be included as part +of the repeated command. If the +.BR '.' +command is preceded by a +.IR count , +this shall override any +.IR count +argument to the previous command. The +.IR count +specified in the +.BR '.' +command shall become the count for subsequent +.BR '.' +commands issued without a count. +.IP "\fB[\fInumber\fB]v\fR" 10 +Invoke the +.IR vi +editor to edit the current command line in a temporary file. When the +editor exits, the commands in the temporary file shall be executed and +placed in the command history. If a +.IR number +is included, it specifies the command number in the command history to +be edited, rather than the current command line. +.IP "\fB[\fIcount\fB]l\fR\0\0\0(ell)" 10 +.sp -0.5v +.IP "\fB[\fIcount\fB]\fR" 10 +.br +Move the current cursor position to the next character position. If +the cursor was positioned on the last character of the line, the +terminal shall be alerted and the cursor shall not be advanced. If the +.IR count +is larger than the number of characters after the cursor, this shall +not be considered an error; the cursor shall advance to the last +character on the line. +.IP "\fB[\fIcount\fB]h\fR" 10 +Move the current cursor position to the +.IR count th +(default 1) previous character position. If the cursor was positioned +on the first character of the line, the terminal shall be alerted and +the cursor shall not be moved. If the count is larger than the number +of characters before the cursor, this shall not be considered an error; +the cursor shall move to the first character on the line. +.IP "\fB[\fIcount\fB]w\fR" 10 +Move to the start of the next word. If the cursor was positioned on +the last character of the line, the terminal shall be alerted and the +cursor shall not be advanced. If the +.IR count +is larger than the number of words after the cursor, this shall not be +considered an error; the cursor shall advance to the last character on +the line. +.IP "\fB[\fIcount\fB]W\fR" 10 +Move to the start of the next bigword. If the cursor was positioned on +the last character of the line, the terminal shall be alerted and the +cursor shall not be advanced. If the +.IR count +is larger than the number of bigwords after the cursor, this shall not +be considered an error; the cursor shall advance to the last character +on the line. +.IP "\fB[\fIcount\fB]e\fR" 10 +Move to the end of the current word. If at the end of a word, move to +the end of the next word. If the cursor was positioned on the last +character of the line, the terminal shall be alerted and the cursor +shall not be advanced. If the +.IR count +is larger than the number of words after the cursor, this shall not be +considered an error; the cursor shall advance to the last character on +the line. +.IP "\fB[\fIcount\fB]E\fR" 10 +Move to the end of the current bigword. If at the end of a bigword, +move to the end of the next bigword. If the cursor was positioned on +the last character of the line, the terminal shall be alerted and the +cursor shall not be advanced. If the +.IR count +is larger than the number of bigwords after the cursor, this shall not +be considered an error; the cursor shall advance to the last character +on the line. +.IP "\fB[\fIcount\fB]b\fR" 10 +Move to the beginning of the current word. If at the beginning of a +word, move to the beginning of the previous word. If the cursor was +positioned on the first character of the line, the terminal shall be +alerted and the cursor shall not be moved. If the +.IR count +is larger than the number of words preceding the cursor, this shall not +be considered an error; the cursor shall return to the first character +on the line. +.IP "\fB[\fIcount\fB]B\fR" 10 +Move to the beginning of the current bigword. If at the beginning of a +bigword, move to the beginning of the previous bigword. If the cursor +was positioned on the first character of the line, the terminal shall +be alerted and the cursor shall not be moved. If the +.IR count +is larger than the number of bigwords preceding the cursor, this shall +not be considered an error; the cursor shall return to the first +character on the line. +.IP "\fB^\fR" 10 +Move the current cursor position to the first character on the input +line that is not a +. +.IP "\fB$\fR" 10 +Move to the last character position on the current command line. +.IP "\fB0\fR" 10 +(Zero.) Move to the first character position on the current command +line. +.IP "\fB[\fIcount\fB]\||\fR" 10 +Move to the +.IR count th +character position on the current command line. If no number is +specified, move to the first position. The first character position +shall be numbered 1. If the count is larger than the number of +characters on the line, this shall not be considered an error; the +cursor shall be placed on the last character on the line. +.IP "\fB[\fIcount\fB]f\fIc\fR" 10 +Move to the first occurrence of the character +.BR 'c' +that occurs after the current cursor position. If the cursor was +positioned on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the character +.BR 'c' +does not occur in the line after the current cursor position, the +terminal shall be alerted and the cursor shall not be moved. +.IP "\fB[\fIcount\fB]F\fIc\fR" 10 +Move to the first occurrence of the character +.BR 'c' +that occurs before the current cursor position. If the cursor was +positioned on the first character of the line, the terminal shall be +alerted and the cursor shall not be moved. If the character +.BR 'c' +does not occur in the line before the current cursor position, the +terminal shall be alerted and the cursor shall not be moved. +.IP "\fB[\fIcount\fB]t\fIc\fR" 10 +Move to the character before the first occurrence of the character +.BR 'c' +that occurs after the current cursor position. If the cursor was +positioned on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the character +.BR 'c' +does not occur in the line after the current cursor position, the +terminal shall be alerted and the cursor shall not be moved. +.IP "\fB[\fIcount\fB]T\fIc\fR" 10 +Move to the character after the first occurrence of the character +.BR 'c' +that occurs before the current cursor position. If the cursor was +positioned on the first character of the line, the terminal shall be +alerted and the cursor shall not be moved. If the character +.BR 'c' +does not occur in the line before the current cursor position, the +terminal shall be alerted and the cursor shall not be moved. +.IP "\fB[\fIcount\fB];\fR" 10 +Repeat the most recent +.BR f , +.BR F , +.BR t , +or +.BR T +command. Any number argument on that previous command shall be +ignored. Errors are those described for the repeated command. +.IP "\fB[\fIcount\fB],\fR" 10 +Repeat the most recent +.BR f , +.BR F , +.BR t , +or +.BR T +command. Any number argument on that previous command shall be +ignored. However, reverse the direction of that command. +.IP "\fBa\fR" 10 +Enter insert mode after the current cursor position. Characters that +are entered shall be inserted before the next character. +.IP "\fBA\fR" 10 +Enter insert mode after the end of the current command line. +.IP "\fBi\fR" 10 +Enter insert mode at the current cursor position. Characters that are +entered shall be inserted before the current character. +.IP "\fBI\fR" 10 +Enter insert mode at the beginning of the current command line. +.IP "\fBR\fR" 10 +Enter insert mode, replacing characters from the command line beginning +at the current cursor position. +.IP "\fB[\fIcount\fB]c\fImotion\fR" 10 +.br +Delete the characters between the current cursor position and the +cursor position that would result from the specified motion +command. Then enter insert mode before the first character following +any deleted characters. If +.IR count +is specified, it shall be applied to the motion command. A +.IR count +shall be ignored for the following motion commands: +.RS 10 +.sp +.RS 4 +.nf +\fB +0 ^ $ c +.fi \fR +.P +.RE +.P +If the motion command is the character +.BR 'c' , +the current command line shall be cleared and insert mode shall be +entered. If the motion command would move the current cursor position +toward the beginning of the command line, the character under the +current cursor position shall not be deleted. If the motion command +would move the current cursor position toward the end of the command +line, the character under the current cursor position shall be deleted. +If the +.IR count +is larger than the number of characters between the current cursor +position and the end of the command line toward which the motion +command would move the cursor, this shall not be considered an error; +all of the remaining characters in the aforementioned range shall be +deleted and insert mode shall be entered. If the motion command is +invalid, the terminal shall be alerted, the cursor shall not be moved, +and no text shall be deleted. +.RE +.IP "\fBC\fR" 10 +Delete from the current character to the end of the line and enter +insert mode at the new end-of-line. +.IP "\fBS\fR" 10 +Clear the entire edit line and enter insert mode. +.IP "\fB[\fIcount\fB]r\fIc\fR" 10 +Replace the current character with the character +.BR 'c' . +With a number +.IR count , +replace the current and the following +.IR count \(mi1 +characters. After this command, the current cursor position shall be +on the last character that was changed. If the +.IR count +is larger than the number of characters after the cursor, this shall +not be considered an error; all of the remaining characters shall be +changed. +.IP "\fB[\fIcount\fB]_\fR" 10 +Append a + +after the current character position and then append the last bigword +in the previous input line after the +. +Then enter insert mode after the last character just appended. With a +number +.IR count , +append the +.IR count th +bigword in the previous line. +.IP "\fB[\fIcount\fB]x\fR" 10 +Delete the character at the current cursor position and place the +deleted characters in the save buffer. If the cursor was positioned on +the last character of the line, the character shall be deleted and the +cursor position shall be moved to the previous character (the new last +character). If the +.IR count +is larger than the number of characters after the cursor, this shall +not be considered an error; all the characters from the cursor to the +end of the line shall be deleted. +.IP "\fB[\fIcount\fB]X\fR" 10 +Delete the character before the current cursor position and place the +deleted characters in the save buffer. The character under the current +cursor position shall not change. If the cursor was positioned on the +first character of the line, the terminal shall be alerted, and the +.BR X +command shall have no effect. If the line contained a single +character, the +.BR X +command shall have no effect. If the line contained no characters, the +terminal shall be alerted and the cursor shall not be moved. If the +.IR count +is larger than the number of characters before the cursor, this shall +not be considered an error; all the characters from before the cursor +to the beginning of the line shall be deleted. +.IP "\fB[\fIcount\fB]d\fImotion\fR" 10 +.br +Delete the characters between the current cursor position and the +character position that would result from the motion command. A number +.IR count +repeats the motion command +.IR count +times. If the motion command would move toward the beginning of the +command line, the character under the current cursor position shall not +be deleted. If the motion command is +.BR d , +the entire current command line shall be cleared. If the +.IR count +is larger than the number of characters between the current cursor +position and the end of the command line toward which the motion +command would move the cursor, this shall not be considered an error; +all of the remaining characters in the aforementioned range shall be +deleted. The deleted characters shall be placed in the save buffer. +.IP "\fBD\fR" 10 +Delete all characters from the current cursor position to the end of +the line. The deleted characters shall be placed in the save buffer. +.IP "\fB[\fIcount\fB]y\fImotion\fR" 10 +.br +Yank (that is, copy) the characters from the current cursor position to +the position resulting from the motion command into the save buffer. A +number +.IR count +shall be applied to the motion command. If the motion command would +move toward the beginning of the command line, the character under the +current cursor position shall not be included in the set of yanked +characters. If the motion command is +.BR y , +the entire current command line shall be yanked into the save buffer. +The current cursor position shall be unchanged. If the +.IR count +is larger than the number of characters between the current cursor +position and the end of the command line toward which the motion +command would move the cursor, this shall not be considered an error; +all of the remaining characters in the aforementioned range shall be +yanked. +.IP "\fBY\fR" 10 +Yank the characters from the current cursor position to the end of the +line into the save buffer. The current character position shall be +unchanged. +.IP "\fB[\fIcount\fB]p\fR" 10 +Put a copy of the current contents of the save buffer after the current +cursor position. The current cursor position shall be advanced to the +last character put from the save buffer. A +.IR count +shall indicate how many copies of the save buffer shall be put. +.IP "\fB[\fIcount\fB]P\fR" 10 +Put a copy of the current contents of the save buffer before the +current cursor position. The current cursor position shall be moved to +the last character put from the save buffer. A +.IR count +shall indicate how many copies of the save buffer shall be put. +.IP "\fBu\fR" 10 +Undo the last command that changed the edit line. This operation shall +not undo the copy of any command line to the edit line. +.IP "\fBU\fR" 10 +Undo all changes made to the edit line. This operation shall not undo +the copy of any command line to the edit line. +.IP "\fB[\fIcount\fB]k\fR" 10 +.sp -0.5v +.IP "\fB[\fIcount\fB]\(mi\fR" 10 +Set the current command line to be the +.IR count th +previous command line in the shell command history. If +.IR count +is not specified, it shall default to 1. The cursor shall be positioned +on the first character of the new command. If a +.BR k +or +.BR \(mi +command would retreat past the maximum number of commands in effect for +this shell (affected by the +.IR HISTSIZE +environment variable), the terminal shall be alerted, and the command +shall have no effect. +.IP "\fB[\fIcount\fB]j\fR" 10 +.sp -0.5v +.IP "\fB[\fIcount\fB]+\fR" 10 +Set the current command line to be the +.IR count th +next command line in the shell command history. If +.IR count +is not specified, it shall default to 1. The cursor shall be positioned +on the first character of the new command. If a +.BR j +or +.BR + +command advances past the edit line, the current command line shall be +restored to the edit line and the terminal shall be alerted. +.IP "\fB[\fInumber\fB]G\fR" 10 +Set the current command line to be the oldest command line stored in +the shell command history. With a number +.IR number , +set the current command line to be the command line +.IR number +in the history. If command line +.IR number +does not exist, the terminal shall be alerted and the command line +shall not be changed. +.IP "\fB/\fIpattern\fR" 10 +.br +Move backwards through the command history, searching for the specified +pattern, beginning with the previous command line. Patterns use the +pattern matching notation described in +.IR "Section 2.13" ", " "Pattern Matching Notation", +except that the +.BR '^' +character shall have special meaning when it appears as the first +character of +.IR pattern . +In this case, the +.BR '^' +is discarded and the characters after the +.BR '^' +shall be matched only at the beginning of a line. Commands in the +command history shall be treated as strings, not as filenames. If the +pattern is not found, the current command line shall be unchanged and +the terminal is alerted. If it is found in a previous line, the current +command line shall be set to that line and the cursor shall be set to +the first character of the new command line. +.RS 10 +.P +If +.IR pattern +is empty, the last non-empty pattern provided to +.BR / +or +.BR ? +shall be used. If there is no previous non-empty pattern, the terminal +shall be alerted and the current command line shall remain unchanged. +.RE +.IP "\fB?\fIpattern\fR" 10 +.br +Move forwards through the command history, searching for the specified +pattern, beginning with the next command line. Patterns use the pattern +matching notation described in +.IR "Section 2.13" ", " "Pattern Matching Notation", +except that the +.BR '^' +character shall have special meaning when it appears as the first +character of +.IR pattern . +In this case, the +.BR '^' +is discarded and the characters after the +.BR '^' +shall be matched only at the beginning of a line. Commands in the +command history shall be treated as strings, not as filenames. If the +pattern is not found, the current command line shall be unchanged and +the terminal alerted. If it is found in a following line, the current +command line shall be set to that line and the cursor shall be set to +the fist character of the new command line. +.RS 10 +.P +If +.IR pattern +is empty, the last non-empty pattern provided to +.BR / +or +.BR ? +shall be used. If there is no previous non-empty pattern, the terminal +shall be alerted and the current command line shall remain unchanged. +.RE +.IP "\fBn\fR" 10 +Repeat the most recent +.BR / +or +.BR ? +command. If there is no previous +.BR / +or +.BR ? , +the terminal shall be alerted and the current command line shall remain +unchanged. +.IP "\fBN\fR" 10 +Repeat the most recent +.BR / +or +.BR ? +command, reversing the direction of the search. If there is no previous +.BR / +or +.BR ? , +the terminal shall be alerted and the current command line shall remain +unchanged. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\0\0\0\00" 8 +The script to be executed consisted solely of zero or more blank lines +or comments, or both. +.IP "1\(hy125" 8 +A non-interactive shell detected an error other than +.IR command_file +not found, including but not limited to syntax, redirection, or variable +assignment errors. +.IP "\0\0127" 8 +A specified +.IR command_file +could not be found by a non-interactive shell. +.P +Otherwise, the shell shall return the exit status of the last command +it invoked or attempted to invoke (see also the +.IR exit +utility in +.IR "Section 2.14" ", " "Special Built-In Utilities"). +.SH "CONSEQUENCES OF ERRORS" +See +.IR "Section 2.8.1" ", " "Consequences of Shell Errors". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Standard input and standard error are the files that +determine whether a shell is interactive when +.BR \(mii +is not specified. For example: +.sp +.RS 4 +.nf +\fB +sh > file +.fi \fR +.P +.RE +.P +and: +.sp +.RS 4 +.nf +\fB +sh 2> file +.fi \fR +.P +.RE +.P +create interactive and non-interactive shells, respectively. Although +both accept terminal input, the results of error conditions are +different, as described in +.IR "Section 2.8.1" ", " "Consequences of Shell Errors"; +in the second example a redirection error encountered by a special +built-in utility aborts the shell. +.P +A conforming application must protect its first operand, if it starts +with a +, +by preceding it with the +.BR \(dq\(mi\|\(mi\(dq +argument that denotes the end of the options. +.P +Applications should note that the standard +.IR PATH +to the shell cannot be assumed to be either +.BR /bin/sh +or +.BR /usr/bin/sh , +and should be determined by interrogation of the +.IR PATH +returned by +.IR getconf +.IR PATH , +ensuring that the returned pathname is an absolute pathname and not a +shell built-in. +.P +For example, to determine the location of the standard +.IR sh +utility: +.sp +.RS 4 +.nf +\fB +command \(miv sh +.fi \fR +.P +.RE +.P +On some implementations this might return: +.sp +.RS 4 +.nf +\fB +/usr/xpg4/bin/sh +.fi \fR +.P +.RE +.P +Furthermore, on systems that support executable scripts (the +.BR \(dq#!\(dq +construct), it is recommended that applications using executable +scripts install them using +.IR getconf +.IR PATH +to determine the shell pathname and update the +.BR \(dq#!\(dq +script appropriately as it is being installed (for example, with +.IR sed ). +For example: +.sp +.RS 4 +.nf +\fB +# +# Installation time script to install correct POSIX shell pathname +# +# Get list of paths to check +# +Sifs=$IFS +Sifs_set=${IFS+y} +IFS=: +set \(mi\|\(mi $(getconf PATH) +if [ "$Sifs_set" = y ] +then + IFS=$Sifs +else + unset IFS +fi +# +# Check each path for 'sh' +# +for i +do + if [ \(mix "${i}"/sh ] + then + Pshell=${i}/sh + fi +done +# +# This is the list of scripts to update. They should be of the +# form '${name}.source' and will be transformed to '${name}'. +# Each script should begin: +# +# #!INSTALLSHELLPATH +# +scripts="a b c" +# +# Transform each script +# +for i in ${scripts} +do + sed \(mie "s|INSTALLSHELLPATH|${Pshell}|" < ${i}.source > ${i} +done +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +Execute a shell command from a string: +.RS 4 +.sp +.RS 4 +.nf +\fB +sh \(mic "cat myfile" +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Execute a shell script from a file in the current directory: +.RS 4 +.sp +.RS 4 +.nf +\fB +sh my_shell_cmds +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR sh +utility and the +.IR set +special built-in utility share a common set of options. +.P +The name +.IR IFS +was originally an abbreviation of ``Input Field Separators''; however, +this name is misleading as the +.IR IFS +characters are actually used as field terminators. The KornShell +ignores the contents of +.IR IFS +upon entry to the script. A conforming application cannot rely on +importing +.IR IFS . +One justification for this, beyond security considerations, is to +assist possible future shell compilers. Allowing +.IR IFS +to be imported from the environment prevents many optimizations that +might otherwise be performed via dataflow analysis of the script +itself. +.P +The text in the STDIN section about non-blocking reads concerns an +instance of +.IR sh +that has been invoked, probably by a C-language program, with standard +input that has been opened using the O_NONBLOCK flag; see +\fIopen\fR() +in the System Interfaces volume of POSIX.1\(hy2008. If the shell did not reset this flag, it would +immediately terminate because no input data would be available yet and +that would be considered the same as end-of-file. +.P +The options associated with a +.IR "restricted shell" +(command name +.IR rsh +and the +.BR \(mir +option) were excluded because the standard developers considered that +the implied level of security could not be achieved and they did not +want to raise false expectations. +.P +On systems that support set-user-ID scripts, +a historical trapdoor has been to link a script to the name +.BR \(mii . +When it is called by a sequence such as: +.sp +.RS 4 +.nf +\fB +sh \(mi +.fi \fR +.P +.RE +.P +or by: +.sp +.RS 4 +.nf +\fB +#!\ usr/bin/sh\ \(mi +.fi \fR +.P +.RE +.P +the historical systems have assumed that no option letters follow. +Thus, this volume of POSIX.1\(hy2008 allows the single + +to mark the end of the options, in addition to the use of the regular +.BR \(dq\(mi\|\(mi\(dq +argument, because it was considered that the older practice was so +pervasive. An alternative approach is taken by the KornShell, where +real and effective user/group IDs must match for an interactive shell; +this behavior is specifically allowed by this volume of POSIX.1\(hy2008. +.TP 10 +.BR Note: +There are other problems with set-user-ID scripts that the two +approaches described here do not resolve. +.P +.P +The initialization process for the history file can be dependent on the +system start-up files, in that they may contain commands that +effectively preempt the user's settings of +.IR HISTFILE +and +.IR HISTSIZE . +For example, function definition commands are recorded in the history +file, unless the +.IR set +.BR \(mio +.IR nolog +option is set. If the system administrator includes function +definitions in some system start-up file called before the +.IR ENV +file, the history file is initialized before the user gets a chance to +influence its characteristics. In some historical shells, the history +file is initialized just after the +.IR ENV +file has been processed. Therefore, it is implementation-defined +whether changes made to +.IR HISTFILE +after the history file has been initialized are effective. +.P +The default messages for the various +.IR MAIL -related +messages are unspecified because they vary across implementations. +Typical messages are: +.sp +.RS 4 +.nf +\fB +"you have mail\en" +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +"you have new mail\en" +.fi \fR +.P +.RE +.P +It is important that the descriptions of command line editing refer to +the same shell as that in POSIX.1\(hy2008 so that interactive users can also be +application programmers without having to deal with programmatic +differences in their two environments. It is also essential that the +utility name +.IR sh +be specified because this explicit utility name is too firmly rooted in +historical practice of application programs for it to change. +.P +Consideration was given to mandating a diagnostic message when +attempting to set +.IR vi -mode +on terminals that do not support command line editing. However, it is +not historical practice for the shell to be cognizant of all terminal +types and thus be able to detect inappropriate terminals in all cases. +Implementations are encouraged to supply diagnostics in this case +whenever possible, rather than leaving the user in a state where +editing commands work incorrectly. +.P +In early proposals, the KornShell-derived +.IR emacs +mode of command line editing was included, even though the +.IR emacs +editor itself was not. The community of +.IR emacs +proponents was adamant that the full +.IR emacs +editor not be standardized because they were concerned that an attempt +to standardize this very powerful environment would encourage vendors +to ship strictly conforming versions lacking the extensibility required +by the community. The author of the original +.IR emacs +program also expressed his desire to omit the program. Furthermore, +there were a number of historical systems that did not include +.IR emacs , +or included it without supporting it, but there were very few that did +not include and support +.IR vi . +The shell +.IR emacs +command line editing mode was finally omitted because it became +apparent that the KornShell version and the editor being distributed +with the GNU system had diverged in some respects. The author of +.IR emacs +requested that the POSIX +.IR emacs +mode either be deleted or have a significant number of unspecified +conditions. Although the KornShell author agreed to consider changes to +bring the shell into alignment, the standard developers decided to +defer specification at that time. At the time, it was assumed that +convergence on an acceptable definition would occur for a subsequent +draft, but that has not happened, and there appears to be no impetus to +do so. In any case, implementations are free to offer additional +command line editing modes based on the exact models of editors their +users are most comfortable with. +.P +Early proposals had the following list entry in +.IR "vi Line Editing Insert Mode": +.IP "\fR\e\fR" 6 +If followed by the +.IR erase +or +.IR kill +character, that character shall be inserted into the input line. +Otherwise, the + +itself shall be inserted into the input line. +.P +However, this is not actually a feature of +.IR sh +command line editing insert mode, but one of some historical terminal +line drivers. Some conforming implementations continue to do this when +the +.IR stty +.BR iexten +flag is set. +.P +In interactive shells, SIGTERM is ignored so that +.IR "kill 0" +does not kill the shell, and SIGINT is caught so that +.IR wait +is interruptible. If the shell does not ignore SIGTTIN, SIGTTOU, and +SIGTSTP signals when it is interactive and the +.BR \(mim +option is not in effect, these signals suspend the shell if it is not +a session leader. If it is a session leader, the signals are discarded +if they would stop the process, as required by the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.4.3" ", " "Signal Actions" +for orphaned process groups. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIcd\fR\^", +.IR "\fIecho\fR\^", +.IR "\fIexit\fR\^", +.IR "\fIfc\fR\^", +.IR "\fIpwd\fR\^", +.IR "invalid", +.IR "\fIset\fR\^", +.IR "\fIstty\fR\^", +.IR "\fItest\fR\^", +.IR "\fItrap\fR\^", +.IR "\fIumask\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIumask\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/shift.1p b/man-pages-posix-2013-a/man1p/shift.1p new file mode 100644 index 0000000..0194fa0 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/shift.1p @@ -0,0 +1,103 @@ +'\" et +.TH SHIFT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shift +\(em shift positional parameters +.SH SYNOPSIS +.LP +.nf +shift \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The positional parameters shall be shifted. Positional parameter 1 +shall be assigned the value of parameter (1+\fIn\fP), parameter 2 shall +be assigned the value of parameter (2+\fIn\fP), and so on. The +parameters represented by the numbers +.BR \(dq$#\(dq +down to +.BR \(dq$#\(min+1\(dq +shall be unset, and the parameter +.BR '#' +is updated to reflect the new number of positional parameters. +.P +The value +.IR n +shall be an unsigned decimal integer less than or equal to the value of +the special parameter +.BR '#' . +If +.IR n +is not given, it shall be assumed to be 1. If +.IR n +is 0, the positional and special parameters are not changed. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If the +.IR n +operand is invalid or is greater than +.BR \(dq$#\(dq , +this may be considered a syntax error and a non-interactive shell may +exit; if the shell does not exit in this case, a non-zero exit status +shall be returned. Otherwise, zero shall be returned. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +\fB$\fR set a b c d e +\fB$\fR shift 2 +\fB$\fR echo $* +\fBc d e\fR +.fi +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/sleep.1p b/man-pages-posix-2013-a/man1p/sleep.1p new file mode 100644 index 0000000..a86781f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/sleep.1p @@ -0,0 +1,173 @@ +'\" et +.TH SLEEP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sleep +\(em suspend execution for an interval +.SH SYNOPSIS +.LP +.nf +sleep \fItime\fR +.fi +.SH DESCRIPTION +The +.IR sleep +utility shall suspend execution for at least the integral number of +seconds specified by the +.IR time +operand. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fItime\fR" 10 +A non-negative decimal integer specifying the number of seconds for +which to suspend execution. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sleep : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +If the +.IR sleep +utility receives a SIGALRM signal, one of the following actions shall +be taken: +.IP " 1." 4 +Terminate normally with a zero exit status. +.IP " 2." 4 +Effectively ignore the signal. +.IP " 3." 4 +Provide the default behavior for signals described in the ASYNCHRONOUS +EVENTS section of +.IR "Section 1.4" ", " "Utility Description Defaults". +This could include terminating with a non-zero exit status. +.P +The +.IR sleep +utility shall take the standard action for all other signals. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The execution was successfully suspended for at least +.IR time +seconds, or a SIGALRM signal was received. See the ASYNCHRONOUS EVENTS +section. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The +.IR sleep +utility can be used to execute a command after a certain amount of +time, as in: +.sp +.RS 4 +.nf +\fB +(sleep 105; \fIcommand\fP) & +.fi \fR +.P +.RE +.P +or to execute a command every so often, as in: +.sp +.RS 4 +.nf +\fB +while true +do + \fIcommand\fP + sleep 37 +done +.fi \fR +.P +.RE +.SH RATIONALE +The exit status is allowed to be zero when +.IR sleep +is interrupted by the SIGALRM signal because most implementations of +this utility rely on the arrival of that signal to notify them that the +requested finishing time has been successfully attained. Such +implementations thus do not distinguish this situation from the +successful completion case. Other implementations are allowed to catch +the signal and go back to sleep until the requested time expires or to +provide the normal signal termination procedures. +.P +As with all other utilities that take integral operands and do not +specify subranges of allowed values, +.IR sleep +is required by this volume of POSIX.1\(hy2008 to deal with +.IR time +requests of up to 2\|147\|483\|647 seconds. This may mean that some +implementations have to make multiple calls to the delay mechanism of +the underlying operating system if its argument range is less than +this. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIalarm\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/sort.1p b/man-pages-posix-2013-a/man1p/sort.1p new file mode 100644 index 0000000..a8cde07 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/sort.1p @@ -0,0 +1,776 @@ +'\" et +.TH SORT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sort +\(em sort, merge, or sequence check text files +.SH SYNOPSIS +.LP +.nf +sort \fB[\fR\(mim\fB] [\fR\(mio \fIoutput\fB] [\fR\(mibdfinru\fB] [\fR\(mit \fIchar\fB] [\fR\(mik \fIkeydef\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +sort \fB[\fR\(mic|\(miC\fB] [\fR\(mibdfinru\fB] [\fR\(mit \fIchar\fB] [\fR\(mik \fIkeydef\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR sort +utility shall perform one of the following functions: +.IP " 1." 4 +Sort lines of all the named files together and write the result to +the specified output. +.IP " 2." 4 +Merge lines of all the named (presorted) files together and write the +result to the specified output. +.IP " 3." 4 +Check that a single input file is correctly presorted. +.P +Comparisons shall be based on one or more sort keys extracted from each +line of input (or, if no sort keys are specified, the entire line up +to, but not including, the terminating +), +and shall be performed using the collating sequence of the current +locale. +.SH OPTIONS +The +.IR sort +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9, and the +.BR \(mik +.IR keydef +option should follow the +.BR \(mib , +.BR \(mid , +.BR \(mif , +.BR \(mii , +.BR \(min , +and +.BR \(mir +options. In addition, +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Check that the single input file is ordered as specified by the +arguments and the collating sequence of the current locale. Output +shall not be sent to standard output. The exit code shall indicate +whether or not disorder was detected or an error occurred. If +disorder (or, with +.BR \(miu , +a duplicate key) is detected, a warning message shall be sent to +standard error indicating where the disorder or duplicate key +was found. +.IP "\fB\(miC\fP" 10 +Same as +.BR \(mic , +except that a warning message shall not be sent to standard error +if disorder or, with +.BR \(miu , +a duplicate key is detected. +.IP "\fB\(mim\fP" 10 +Merge only; the input file shall be assumed to be already sorted. +.IP "\fB\(mio\ \fIoutput\fR" 10 +Specify the name of an output file to be used instead of the standard +output. This file can be the same as one of the input +.IR file s. +.IP "\fB\(miu\fP" 10 +Unique: suppress all but one in each set of lines having equal keys. +If used with the +.BR \(mic +option, check that there are no lines with duplicate keys, in addition +to checking that the input file is sorted. +.P +The following options shall override the default ordering rules. When +ordering options appear independent of any key field specifications, +the requested field ordering rules shall be applied globally to all +sort keys. When attached to a specific key (see +.BR \(mik ), +the specified ordering options shall override all global ordering +options for that key. +.IP "\fB\(mid\fP" 10 +Specify that only + +characters and alphanumeric characters, according to the current +setting of +.IR LC_CTYPE , +shall be significant in comparisons. The behavior is undefined for a +sort key to which +.BR \(mii +or +.BR \(min +also applies. +.IP "\fB\(mif\fP" 10 +Consider all lowercase characters that have uppercase equivalents, +according to the current setting of +.IR LC_CTYPE , +to be the uppercase equivalent for the purposes of comparison. +.IP "\fB\(mii\fP" 10 +Ignore all characters that are non-printable, according to the current +setting of +.IR LC_CTYPE . +The behavior is undefined for a sort key for which +.BR \(min +also applies. +.IP "\fB\(min\fP" 10 +Restrict the sort key to an initial numeric string, consisting of +optional + +characters, optional minus-sign, and zero or more digits with an +optional radix character and thousands separators (as defined in the +current locale), which shall be sorted by arithmetic value. An empty +digit string shall be treated as zero. Leading zeros and signs on zeros +shall not affect ordering. +.IP "\fB\(mir\fP" 10 +Reverse the sense of comparisons. +.P +The treatment of field separators can be altered using the options: +.IP "\fB\(mib\fP" 10 +Ignore leading + +characters when determining the starting and ending positions of a +restricted sort key. If the +.BR \(mib +option is specified before the first +.BR \(mik +option, it shall be applied to all +.BR \(mik +options. Otherwise, the +.BR \(mib +option can be attached independently to each +.BR \(mik +.IR field_start +or +.IR field_end +option-argument (see below). +.IP "\fB\(mit\ \fIchar\fR" 10 +Use +.IR char +as the field separator character; +.IR char +shall not be considered to be part of a field (although it can be +included in a sort key). Each occurrence of +.IR char +shall be significant (for example, <\fIchar\fR><\fIchar\fR> delimits an +empty field). If +.BR \(mit +is not specified, + +characters shall be used as default field separators; each maximal +non-empty sequence of + +characters that follows a non-\c + +shall be a field separator. +.P +Sort keys can be specified using the options: +.IP "\fB\(mik\ \fIkeydef\fR" 10 +The +.IR keydef +argument is a restricted sort key field definition. The format of this +definition is: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIfield_start\fB[\fItype\fB][\fR,\fIfield_end\fB[\fItype\fB]]\fR +.fi \fR +.P +.RE +.P +where +.IR field_start +and +.IR field_end +define a key field restricted to a portion of the line (see the +EXTENDED DESCRIPTION section), and +.IR type +is a modifier from the list of characters +.BR 'b' , +.BR 'd' , +.BR 'f' , +.BR 'i' , +.BR 'n' , +.BR 'r' . +The +.BR 'b' +modifier shall behave like the +.BR \(mib +option, but shall apply only to the +.IR field_start +or +.IR field_end +to which it is attached. The other modifiers shall behave like the +corresponding options, but shall apply only to the key field to which +they are attached; they shall have this effect if specified with +.IR field_start , +.IR field_end , +or both. If any modifier is attached to a +.IR field_start +or to a +.IR field_end , +no option shall apply to either. Implementations shall support at +least nine occurrences of the +.BR \(mik +option, which shall be significant in command line order. If no +.BR \(mik +option is specified, a default sort key of the entire line shall be +used. +.P +When there are multiple key fields, later keys shall be compared only +after all earlier keys compare equal. Except when the +.BR \(miu +option is specified, lines that otherwise compare equal shall be +ordered as if none of the options +.BR \(mid , +.BR \(mif , +.BR \(mii , +.BR \(min , +or +.BR \(mik +were present (but with +.BR \(mir +still in effect, if it was specified) and with all bytes in the lines +significant to the comparison. The order in which lines that still +compare equal are written is unspecified. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be sorted, merged, or checked. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files, except that the +.IR sort +utility shall add a + +to the end of a file ending with an incomplete last line. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sort : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for ordering rules. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classification for the +.BR \(mib , +.BR \(mid , +.BR \(mif , +.BR \(mii , +and +.BR \(min +options. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for the definition of the radix character and +thousands separator for the +.BR \(min +option. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Unless the +.BR \(mio +or +.BR \(mic +options are in effect, the standard output shall contain the sorted +input. +.SH STDERR +The standard error shall be used for diagnostic messages. When +.BR \(mic +is specified, if disorder is detected (or if +.BR \(miu +is also specified and a duplicate key is detected), a message shall +be written to the standard error which identifies the input line at +which disorder (or a duplicate key) was detected. A warning +message about correcting an incomplete last line of an input file +may be generated, but need not affect the final exit status. +.SH "OUTPUT FILES" +If the +.BR \(mio +option is in effect, the sorted input shall be written to the file +.IR output . +.SH "EXTENDED DESCRIPTION" +The notation: +.sp +.RS 4 +.nf +\fB +\(mik \fIfield_start\fB[\fItype\fB][\fR,\fIfield_end\fB[\fItype\fB]]\fR +.fi \fR +.P +.RE +.P +shall define a key field that begins at +.IR field_start +and ends at +.IR field_end +inclusive, unless +.IR field_start +falls beyond the end of the line or after +.IR field_end , +in which case the key field is empty. A missing +.IR field_end +shall mean the last character of the line. +.P +A field comprises a maximal sequence of non-separating characters and, +in the absence of option +.BR \(mit , +any preceding field separator. +.P +The +.IR field_start +portion of the +.IR keydef +option-argument shall have the form: +.sp +.RS 4 +.nf +\fB +\fIfield_number\fB[\fR.\fIfirst_character\fB]\fR +.fi \fR +.P +.RE +.P +Fields and characters within fields shall be numbered starting with 1. +The +.IR field_number +and +.IR first_character +pieces, interpreted as positive decimal integers, shall specify the +first character to be used as part of a sort key. If +.IR .first_character +is omitted, it shall refer to the first character of the field. +.P +The +.IR field_end +portion of the +.IR keydef +option-argument shall have the form: +.sp +.RS 4 +.nf +\fB +\fIfield_number\fB[\fR.\fIlast_character\fB]\fR +.fi \fR +.P +.RE +.P +The +.IR field_number +shall be as described above for +.IR field_start. +The +.IR last_character +piece, interpreted as a non-negative decimal integer, shall specify the +last character to be used as part of the sort key. If +.IR last_character +evaluates to zero or +.IR .last_character +is omitted, it shall refer to the last character of the field specified +by +.IR field_number . +.P +If the +.BR \(mib +option or +.BR b +type modifier is in effect, characters within a field shall be counted +from the first non-\c + +in the field. (This shall apply separately to +.IR first_character +and +.IR last_character .) +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully, or +.BR \(mic +was specified and the input file was correctly sorted. +.IP "\01" 6 +Under the +.BR \(mic +option, the file was not ordered as specified, or if the +.BR \(mic +and +.BR \(miu +options were both specified, two input lines were found with equal +keys. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The default value for +.BR \(mit , +, +has different properties from, for example, +.BR \(mit \c +"". If a line contains: +.sp +.RS 4 +.nf +\fB +foo +.fi \fR +.P +.RE +.P +the following treatment would occur with default separation as opposed +to specifically selecting a +: +.TS +center box tab(@); +cB | cB | cB +n | l | l. +Field@Default@\(mit "" +_ +1@foo@\fIempty\fP +2@\fIempty\fP@\fIempty\fP +3@\fIempty\fP@foo +.TE +.P +The leading field separator itself is included in a field when +.BR \(mit +is not used. For example, this command returns an exit status of zero, +meaning the input was already sorted: +.sp +.RS 4 +.nf +\fB +sort \(mic \(mik 2 <b +xa +eof +.fi \fR +.P +.RE +.P +(assuming that a + +precedes the + +in the current collating sequence). The field separator is not included +in a field when it is explicitly set via +.BR \(mit . +This is historical practice and allows usage such as: +.sp +.RS 4 +.nf +\fB +sort \(mit "|" \(mik 2n < +of the second field as the sort key: +.RS 4 +.sp +.RS 4 +.nf +\fB +sort \(mik 2.2b,2.2b infile1 infile2 +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +The following command prints the System\ V password file (user +database) sorted by the numeric user ID (the third +-separated +field): +.RS 4 +.sp +.RS 4 +.nf +\fB +sort \(mit : \(mik 3,3n /etc/passwd +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +The following command prints the lines of the already sorted file +.BR infile , +suppressing all but one occurrence of lines having the same third +field: +.RS 4 +.sp +.RS 4 +.nf +\fB +sort \(mium \(mik 3.1,3.0 infile +.fi \fR +.P +.RE +.RE +.SH RATIONALE +Examples in some historical documentation state that options +.BR \(mium +with one input file keep the first in each set of lines with equal +keys. This behavior was deemed to be an implementation artifact and +was not standardized. +.P +The +.BR \(miz +option was omitted; it is not standard practice on most systems and is +inconsistent with using +.IR sort +to sort several files individually and then merge them together. The +text concerning +.BR \(miz +in historical documentation appeared to require implementations to +determine the proper buffer length during the sort phase of operation, +but not during the merge. +.P +The +.BR \(miy +option was omitted because of non-portability. The +.BR \(miM +option, present in System V, was omitted because of non-portability in +international usage. +.P +An undocumented +.BR \(miT +option exists in some implementations. It is used to specify a +directory for intermediate files. Implementations are encouraged to +support the use of the +.IR TMPDIR +environment variable instead of adding an option to support this +functionality. +.P +The +.BR \(mik +option was added to satisfy two objections. First, the zero-based +counting used by +.IR sort +is not consistent with other utility conventions. Second, it did not +meet syntax guideline requirements. +.P +Historical documentation indicates that ``setting +.BR \(min +implies +.BR \(mib ''. +The description of +.BR \(min +already states that optional leading s are tolerated in doing +the comparison. If +.BR \(mib +is enabled, rather than implied, by +.BR \(min , +this has unusual side-effects. When a character offset is used in a +column of numbers (for example, to sort modulo 100), that offset is +measured relative to the most significant digit, not to the column. +Based upon a recommendation from the author of the original +.IR sort +utility, the +.BR \(mib +implication has been omitted from this volume of POSIX.1\(hy2008, and an application wishing to +achieve the previously mentioned side-effects has to code the +.BR \(mib +flag explicitly. +.P +Earlier versions of this standard allowed the +.BR \(mio +option to appear after operands. Historical practice allowed all +options to be interspersed with operands. This version of the +standard allows implementations to accept options after operands +but conforming applications should not use this form. +.P +Earlier versions of this standard also allowed the +.BR \(mi \c +.IR number +and +.BR \(pl \c +.IR number +options. These options are no longer specified by POSIX.1\(hy2008 but may +be present in some implementations. +.P +Historical implementations produced a message on standard error when +.BR \(mic +was specified and disorder was detected, and when +.BR \(mic +and +.BR \(miu +were specified and a duplicate key was detected. An earlier version of +this standard contained wording that did not make it clear that this +message was allowed and some implementations removed this message to +be sure that they conformed to the standard's requirements. Confronted +with this difference in behavior, interactive users that wanted to be +sure that they got visual feedback instead of just exit code 1 could +have used a command like: +.sp +.RS 4 +.nf +\fB +sort \(mic file || echo disorder +.fi \fR +.P +.RE +.P +whether or not the +.IR sort +utility provided a message in this case. But, it was not easy for a user +to find where the disorder or duplicate key occurred on implementations +that do not produce a message, especially when some parts of the input +line were not part of the key and when one or more of the +.BR \(mib , +.BR \(mid , +.BR \(mif , +.BR \(mii , +.BR \(min , +or +.BR \(mi r +options or +.IR keydef +type modifiers were in use. POSIX.1\(hy2008 requires a message to be +produced in this case. POSIX.1\(hy2008 also contains the +.BR \(miC +option giving users the ability to choose either behavior. +.P +When a disorder or duplicate is found when the +.BR \(mic +option is specified, some implementations print a message containing +the first line that is out of order or contains a duplicate key; others +print a message specifying the line number of the offending line. This +standard allows either type of message. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcomm\fR\^", +.IR "\fIjoin\fR\^", +.IR "\fIuniq\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fItoupper\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/split.1p b/man-pages-posix-2013-a/man1p/split.1p new file mode 100644 index 0000000..a8269f0 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/split.1p @@ -0,0 +1,318 @@ +'\" et +.TH SPLIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +split +\(em split files into pieces +.SH SYNOPSIS +.LP +.nf +split \fB[\fR\(mil \fIline_count\fB] [\fR\(mia \fIsuffix_length\fB] [\fIfile\fB[\fIname\fB]]\fR +.P +split \(mib \fIn\fB[\fRk|m\fB] [\fR\(mia \fIsuffix_length\fB] [\fIfile\fB[\fIname\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR split +utility shall read an input file and write one or more output files. +The default size of each output file shall be 1\|000 lines. The size +of the output files can be modified by specification of the +.BR \(mib +or +.BR \(mil +options. Each output file shall be created with a unique suffix. The +suffix shall consist of exactly +.IR suffix_length +lowercase letters from the POSIX locale. The letters of the suffix +shall be used as if they were a base-26 digit system, with the first +suffix to be created consisting of all +.BR 'a' +characters, the second with a +.BR 'b' +replacing the last +.BR 'a' , +and so on, until a name of all +.BR 'z' +characters is created. By default, the names of the output files shall +be +.BR 'x' , +followed by a two-character suffix from the character set as described +above, starting with +.BR \(dqaa\(dq , +.BR \(dqab\(dq , +.BR \(dqac\(dq , +and so on, and continuing until the suffix +.BR \(dqzz\(dq , +for a maximum of 676 files. +.P +If the number of files required exceeds the maximum allowed by the +suffix length provided, such that the last allowable file would be +larger than the requested size, the +.IR split +utility shall fail after creating the last file with a valid suffix; +.IR split +shall not delete the files it created with valid suffixes. If the file +limit is not exceeded, the last file created shall contain the +remainder of the input file, and may be smaller than the requested +size. +.SH OPTIONS +The +.IR split +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\ \fIsuffix_length\fR" 10 +.br +Use +.IR suffix_length +letters to form the suffix portion of the filenames of the split +file. If +.BR \(mia +is not specified, the default suffix length shall be two. If the sum +of the +.IR name +operand and the +.IR suffix_length +option-argument would create a filename exceeding +{NAME_MAX} +bytes, an error shall result; +.IR split +shall exit with a diagnostic message and no files shall be created. +.IP "\fB\(mib\ \fIn\fR" 10 +Split a file into pieces +.IR n +bytes in size. +.IP "\fB\(mib\ \fIn\fBk\fR" 10 +Split a file into pieces +.IR n *1\|024 +bytes in size. +.IP "\fB\(mib\ \fIn\fBm\fR" 10 +Split a file into pieces +.IR n *1\|048\|576 +bytes in size. +.IP "\fB\(mil\ \fIline_count\fR" 10 +Specify the number of lines in each resulting file piece. The +.IR line_count +argument is an unsigned decimal integer. The default is 1\|000. If +the input does not end with a +, +the partial line shall be included in the last output file. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +The pathname of the ordinary file to be split. If no input file is +given or +.IR file +is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIname\fR" 10 +The prefix to be used for each of the files resulting from the split +operation. If no +.IR name +argument is given, +.BR 'x' +shall be used as the prefix of the output files. The combined length +of the basename of +.IR prefix +and +.IR suffix_length +cannot exceed +{NAME_MAX} +bytes. See the OPTIONS section. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Any file can be used as input. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR split : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files contain portions of the original input file; otherwise, +unchanged. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +In the following examples +.BR foo +is a text file that contains 5\|000 lines. +.IP " 1." 4 +Create five files, +.BR xaa , +.BR xab , +.BR xac , +.BR xad , +and +.BR xae : +.RS 4 +.sp +.RS 4 +.nf +\fB +split foo +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Create five files, but the suffixed portion of the created +files consists of three letters, +.BR xaaa , +.BR xaab , +.BR xaac , +.BR xaad , +and +.BR xaae : +.RS 4 +.sp +.RS 4 +.nf +\fB +split \(mia 3 foo +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Create three files with four-letter suffixes and a supplied prefix, +.BR bar_aaaa , +.BR bar_aaab , +and +.BR bar_aaac : +.RS 4 +.sp +.RS 4 +.nf +\fB +split \(mia 4 \(mil 2000 foo bar_ +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Create as many files as are necessary to contain at most 20*1\|024 +bytes, each with the default prefix of +.BR x +and a five-letter suffix: +.RS 4 +.sp +.RS 4 +.nf +\fB +split \(mia 5 \(mib 20k foo +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.BR \(mib +option was added to provide a mechanism for splitting files other than +by lines. While most uses of the +.BR \(mib +option are for transmitting files over networks, some believed it would +have additional uses. +.P +The +.BR \(mia +option was added to overcome the limitation of being able to create +only 676 files. +.P +Consideration was given to deleting this utility, using the rationale +that the functionality provided by this utility is available via the +.IR csplit +utility (see +.IR "\fIcsplit\fR\^"). +Upon reconsideration of the purpose of the User Portability Utilities +option, it was decided to retain both this utility and the +.IR csplit +utility because users use both utilities and have historical +expectations of their behavior. Furthermore, the splitting on byte +boundaries in +.IR split +cannot be duplicated with the historical +.IR csplit . +.P +The text ``\c +.IR split +shall not delete the files it created with valid suffixes'' would +normally be assumed, but since the related utility, +.IR csplit , +does delete files under some circumstances, the historical behavior of +.IR split +is made explicit to avoid misinterpretation. +.P +Earlier versions of this standard allowed a +.BR \(mi \c +.IR line_count +option. This form is no longer specified by POSIX.1\(hy2008 but may be +present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcsplit\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/strings.1p b/man-pages-posix-2013-a/man1p/strings.1p new file mode 100644 index 0000000..eaaaf0b --- /dev/null +++ b/man-pages-posix-2013-a/man1p/strings.1p @@ -0,0 +1,244 @@ +'\" et +.TH STRINGS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strings +\(em find printable strings in files +.SH SYNOPSIS +.LP +.nf +strings \fB[\fR\(mia\fB] [\fR\(mit \fIformat\fB] [\fR\(min \fInumber\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR strings +utility shall look for printable strings in regular files and shall +write those strings to standard output. A printable string is any +sequence of four (by default) or more printable characters terminated +by a + +or NUL character. Additional implementation-defined strings may be +written; see +.IR localedef . +.P +If the first argument is +.BR '\(mi' , +the results are unspecified. +.SH OPTIONS +The +.IR strings +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Scan files in their entirety. If +.BR \(mia +is not specified, it is implementation-defined what portion of each +file is scanned for strings. +.IP "\fB\(min\ \fInumber\fR" 10 +Specify the minimum string length, where the +.IR number +argument is a positive decimal integer. The default shall be 4. +.IP "\fB\(mit\ \fIformat\fR" 10 +Write each string preceded by its byte offset from the start of the +file. The format shall be dependent on the single character used as +the +.IR format +option-argument: +.RS 10 +.IP "\fRd\fR" 6 +The offset shall be written in decimal. +.IP "\fRo\fR" 6 +The offset shall be written in octal. +.IP "\fRx\fR" 6 +The offset shall be written in hexadecimal. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a regular file to be used as input. If no +.IR file +operand is specified, the +.IR strings +utility shall read from the standard input. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input files named by the utility arguments or the standard input +shall be regular files of any format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR strings : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and to identify +printable strings. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Strings found shall be written to the standard output, one per line. +.P +When the +.BR \(mit +option is not specified, the format of the output shall be: +.sp +.RS 4 +.nf +\fB +"%s", <\fIstring\fR> +.fi \fR +.P +.RE +.P +With the +.BR "\(mit\ o" +option, the format of the output shall be: +.sp +.RS 4 +.nf +\fB +"%o %s", <\fIbyte offset\fR>, <\fIstring\fR> +.fi \fR +.P +.RE +.P +With the +.BR "\(mit\ x" +option, the format of the output shall be: +.sp +.RS 4 +.nf +\fB +"%x %s", <\fIbyte offset\fR>, <\fIstring\fR> +.fi \fR +.P +.RE +.P +With the +.BR "\(mit\ d" +option, the format of the output shall be: +.sp +.RS 4 +.nf +\fB +"%d %s", <\fIbyte offset\fR>, <\fIstring\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +By default the data area (as opposed to the text, ``bss'', or header +areas) of a binary executable file is scanned. Implementations +document which areas are scanned. +.P +Some historical implementations do not require NUL or + +terminators for strings to permit those languages that do not use NUL +as a string terminator to have their strings written. +.SH EXAMPLES +None. +.SH RATIONALE +Apart from rationalizing the option syntax and slight difficulties with +object and executable binary files, +.IR strings +is specified to match historical practice closely. The +.BR \(mia +and +.BR \(min +options were introduced to replace the non-conforming +.BR \(mi +and +.BR \(mi \c +.IR number +options. These options are no longer specified by POSIX.1\(hy2008 but +may be present in some implementations. +.P +The +.BR \(mio +option historically means different things on different +implementations. Some use it to mean ``\c +.IR offset +in decimal'', while others use it as ``\c +.IR offset +in octal''. Instead of trying to decide which way would be least +objectionable, the +.BR \(mit +option was added. It was originally named +.BR \(miO +to mean ``offset'', but was changed to +.BR \(mit +to be consistent with +.IR od . +.P +The ISO\ C standard function +\fIisprint\fR() +is restricted to a domain of +.BR "unsigned char" . +This volume of POSIX.1\(hy2008 requires implementations to write strings as defined by the +current locale. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlocaledef\fR\^", +.IR "\fInm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/strip.1p b/man-pages-posix-2013-a/man1p/strip.1p new file mode 100644 index 0000000..1b9eea9 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/strip.1p @@ -0,0 +1,153 @@ +'\" et +.TH STRIP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strip +\(em remove unnecessary information from strippable files +(\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +strip \fIfile\fR... +.fi +.SH DESCRIPTION +A strippable file is defined as a relocatable, object, or executable +file. +On XSI-conformant systems, a strippable file can also be an archive +of object or relocatable files. +.P +The +.IR strip +utility shall remove from strippable files named by the +.IR file +operands any information the implementor deems unnecessary for +execution of those files. The nature of that information is +unspecified. The effect of +.IR strip +on object and executable files shall be similar to the use of the +.BR \(mis +option to +.IR c99 +or +.IR fort77 . +The effect of +.IR strip +on an archive of object files shall be similar to the use of the +.BR \(mis +option to +.IR c99 +or +.IR fort77 +for each object file in the archive. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname referring to a strippable file. +.SH STDIN +Not used. +.SH "INPUT FILES" +The input files shall be in the form of strippable files successfully +produced by any compiler defined by this volume of POSIX.1\(hy2008 +or produced by creating or updating an archive of such files +using the +.IR ar +utility. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR strip : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The +.IR strip +utility shall produce strippable files of unspecified format. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +Historically, this utility has been used to remove the symbol table +from a strippable file. It was included since it is known that the +amount of symbolic information can amount to several megabytes; the +ability to remove it in a portable manner was deemed important, +especially for smaller systems. +.P +The behavior of +.IR strip +on object and executable files is said to be the same as the +.BR \(mis +option to a compiler. While the end result is essentially the same, +it is not required to be identical. +.P +XSI-conformant systems support use of +.IR strip +on archive files containing object files or relocatable files. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIc99\fR\^", +.IR "\fIfort77\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/stty.1p b/man-pages-posix-2013-a/man1p/stty.1p new file mode 100644 index 0000000..bd707d1 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/stty.1p @@ -0,0 +1,807 @@ +'\" et +.TH STTY "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stty +\(em set the options for a terminal +.SH SYNOPSIS +.LP +.nf +stty \fB[\fR\(mia|\(mig\fB]\fR +.P +stty \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR stty +utility shall set or report on terminal I/O characteristics for the +device that is its standard input. Without options or operands +specified, it shall report the settings of certain characteristics, +usually those that differ from implementation-defined defaults. +Otherwise, it shall modify the terminal state according to the +specified operands. Detailed information about the modes listed in the +first five groups below are described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +Operands in the Combination Modes group (see +.IR "Combination Modes") +are implemented using operands in the previous groups. Some +combinations of operands are mutually-exclusive on some terminal types; +the results of using such combinations are unspecified. +.P +Typical implementations of this utility require a communications line +configured to use the +.BR termios +interface defined in the System Interfaces volume of POSIX.1\(hy2008. On systems where none of these lines +are available, and on lines not currently configured to support the +.BR termios +interface, some of the operands need not affect terminal +characteristics. +.SH OPTIONS +The +.IR stty +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Write to standard output all the current settings for the terminal. +.IP "\fB\(mig\fP" 10 +Write to standard output all the current settings in an unspecified +form that can be used as arguments to another invocation of the +.IR stty +utility on the same system. The form used shall not contain any +characters that would require quoting to avoid word expansion by the +shell; see +.IR "Section 2.6" ", " "Word Expansions". +.SH OPERANDS +The following operands shall be supported to set the terminal +characteristics. +.SS "Control Modes" +.IP "\fBparenb\ \fR(\fB\(miparenb\fR)" 12 +Enable (disable) parity generation and detection. This shall have +the effect of setting (not setting) PARENB in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBparodd\ \fR(\fB\(miparodd\fR)" 12 +.br +Select odd (even) parity. This shall have the effect of setting (not +setting) PARODD in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBcs5\ cs6\ cs7\ cs8\fR" 12 +Select character size, if possible. This shall have the effect of +setting CS5, CS6, CS7, and CS8, respectively, in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fInumber\fR" 12 +Set terminal baud rate to the number given, if possible. If the baud +rate is set to zero, the modem control lines shall no longer be +asserted. This shall have the effect of setting the input and output +.BR termios +baud rate values as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBispeed\ \fInumber\fR" 12 +Set terminal input baud rate to the number given, if possible. If the +input baud rate is set to zero, the input baud rate shall be specified +by the value of the output baud rate. This shall have the effect of +setting the input +.BR termios +baud rate values as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBospeed\ \fInumber\fR" 12 +Set terminal output baud rate to the number given, if possible. If the +output baud rate is set to zero, the modem control lines shall no +longer be asserted. This shall have the effect of setting the output +.BR termios +baud rate values as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBhupcl\ \fR(\fB\(mihupcl\fR)" 12 +Stop asserting modem control lines (do not stop asserting modem control +lines) on last close. This shall have the effect of setting (not +setting) HUPCL in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBhup\ \fR(\fB\(mihup\fR)" 12 +Equivalent to +.BR hupcl (\c +.BR \(mihupcl ). +.IP "\fBcstopb\ \fR(\fB\(micstopb\fR)" 12 +Use two (one) stop bits per character. This shall have the effect of +setting (not setting) CSTOPB in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBcread\ \fR(\fB\(micread\fR)" 12 +Enable (disable) the receiver. This shall have the effect of setting +(not setting) CREAD in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBclocal\ \fR(\fB\(miclocal\fR)" 12 +Assume a line without (with) modem control. This shall have the effect +of setting (not setting) CLOCAL in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.P +It is unspecified whether +.IR stty +shall report an error if an attempt to set a Control Mode fails. +.SS "Input Modes" +.IP "\fBignbrk\ \fR(\fB\(miignbrk\fR)" 12 +Ignore (do not ignore) break on input. This shall have the effect of +setting (not setting) IGNBRK in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBbrkint\ \fR(\fB\(mibrkint\fR)" 12 +Signal (do not signal) INTR on break. This shall have the effect of +setting (not setting) BRKINT in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBignpar\ \fR(\fB\(miignpar\fR)" 12 +Ignore (do not ignore) bytes with parity errors. This shall have the +effect of setting (not setting) IGNPAR in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBparmrk\ \fR(\fB\(miparmrk\fR)" 12 +.br +Mark (do not mark) parity errors. This shall have the effect of +setting (not setting) PARMRK in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBinpck\ \fR(\fB\(miinpck\fR)" 12 +Enable (disable) input parity checking. This shall have the effect of +setting (not setting) INPCK in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBistrip\ \fR(\fB\(miistrip\fR)" 12 +Strip (do not strip) input characters to seven bits. This shall have +the effect of setting (not setting) ISTRIP in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBinlcr\ \fR(\fB\(miinlcr\fR)" 12 +Map (do not map) NL to CR on input. This shall have the effect of +setting (not setting) INLCR in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBigncr\ (\(miigncr)\fR" 12 +Ignore (do not ignore) CR on input. This shall have the effect of +setting (not setting) IGNCR in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBicrnl\ \fR(\fB\(miicrnl\fR)" 12 +Map (do not map) CR to NL on input. This shall have the effect of +setting (not setting) ICRNL in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBixon\ \fR(\fB\(miixon\fR)" 12 +Enable (disable) START/STOP output control. Output from the system is +stopped when the system receives STOP and started when the system +receives START. This shall have the effect of setting (not setting) +IXON in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBixany\ \fR(\fB\(miixany\fR)" 12 +Allow any character to restart output. This shall have the effect of +setting (not setting) IXANY in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBixoff\ \fR(\fB\(miixoff\fR)" 12 +Request that the system send (not send) STOP characters when the input +queue is nearly full and START characters to resume data transmission. +This shall have the effect of setting (not setting) IXOFF in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.SS "Output Modes" +.IP "\fBopost\ \fR(\fB\(miopost\fR)" 12 +Post-process output (do not post-process output; ignore all other +output modes). This shall have the effect of setting (not setting) +OPOST in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBocrnl\ \fR(\fB\(miocrnl\fR)" 12 +Map (do not map) CR to NL on output This shall have the effect of +setting (not setting) OCRNL in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBonocr\ \fR(\fB\(mionocr\fR)" 12 +Do not (do) output CR at column zero. This shall have the effect of +setting (not setting) ONOCR in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBonlret\ \fR(\fB\(mionlret\fR)" 12 +The terminal newline key performs (does not perform) the CR function. +This shall have the effect of setting (not setting) ONLRET in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBofill\ \fR(\fB\(miofill\fR)" 12 +Use fill characters (use timing) for delays. This shall have the +effect of setting (not setting) OFILL in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBofdel\ \fR(\fB\(miofdel\fR)" 12 +Fill characters are DELs (NULs). This shall have the effect of setting +(not setting) OFDEL in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBcr0\ cr1\ cr2\ cr3\fR" 12 +Select the style of delay for CRs. This shall have the effect of +setting CRDLY to CR0, CR1, CR2, or CR3, respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBnl0\ nl1\fR" 12 +Select the style of delay for NL. This shall have the effect of +setting NLDLY to NL0 or NL1, respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBtab0\ tab1\ tab2\ tab3\fR" 12 +.br +Select the style of delay for horizontal tabs. This shall have the +effect of setting TABDLY to TAB0, TAB1, TAB2, or TAB3, respectively, +in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +Note that TAB3 has the effect of expanding + +characters to + +characters. +.IP "\fBtabs\ \fR(\fB\(mitabs\fR)" 12 +Synonym for +.BR tab0 +(\c +.BR tab3 ). +.IP "\fBbs0\ bs1\fR" 12 +Select the style of delay for + +characters. This shall have the effect of setting BSDLY to BS0 or BS1, +respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBff0\ ff1\fR" 12 +Select the style of delay for + +characters. This shall have the effect of setting FFDLY to FF0 or FF1, +respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBvt0\ vt1\fR" 12 +Select the style of delay for + +characters. This shall have the effect of setting VTDLY to VT0 or VT1, +respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.SS "Local Modes" +.IP "\fBisig\ \fR(\fB\(miisig\fR)" 12 +Enable (disable) the checking of characters against the special control +characters INTR, QUIT, and SUSP. This shall have the effect of setting +(not setting) ISIG in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBicanon\ \fR(\fB\(miicanon\fR)" 12 +Enable (disable) canonical input (ERASE and KILL processing). This +shall have the effect of setting (not setting) ICANON in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBiexten\ \fR(\fB\(miiexten\fR)" 12 +Enable (disable) any implementation-defined special control +characters not currently controlled by +.BR icanon , +.BR isig , +.BR ixon , +or +.BR ixoff . +This shall have the effect of setting (not setting) IEXTEN in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBecho\ \fR(\fB\(miecho\fR)" 12 +Echo back (do not echo back) every character typed. This shall have +the effect of setting (not setting) ECHO in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBechoe\ \fR(\fB\(miechoe\fR)" 12 +The ERASE character visually erases (does not erase) the last character +in the current line from the display, if possible. This shall have the +effect of setting (not setting) ECHOE in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBechok\ \fR(\fB\(miechok\fR)" 12 +Echo (do not echo) NL after KILL character. This shall have the effect +of setting (not setting) ECHOK in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBechonl\ \fR(\fB\(miechonl\fR)" 12 +Echo (do not echo) NL, even if +.BR echo +is disabled. This shall have the effect of setting (not setting) +ECHONL in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBnoflsh\ \fR(\fB\(minoflsh\fR)" 12 +Disable (enable) flush after INTR, QUIT, SUSP. This shall have the +effect of setting (not setting) NOFLSH in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBtostop\ \fR(\fB\(mitostop\fR)" 12 +Send SIGTTOU for background output. This shall have the effect of +setting (not setting) TOSTOP in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.SS "Special Control Character Assignments" +.IP "<\fIcontrol\fR>\(hy\fIcharacter\ string\fR" 6 +.br +Set <\fIcontrol\fP>\(hy\fIcharacter\fR to +.IR string . +If <\fIcontrol\fP>\(hy\fIcharacter\fR is one of the character sequences +in the first column of the following table, the corresponding the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface" +control character from the second column shall be recognized. This has +the effect of setting the corresponding element of the +.BR termios +.IR c_cc +array (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 13" ", " "Headers", +.IR ). +.br +.sp +.ce 1 +\fBTable: Control Character Names in \fIstty\fP\fR +.TS +center tab(@) box; +cB | cB | cB +lB | l | l. +Control Character@c_cc Subscript@Description +_ +eof@VEOF@EOF character +eol@VEOL@EOL character +erase@VERASE@ERASE character +intr@VINTR@INTR character +kill@VKILL@KILL character +quit@VQUIT@QUIT character +susp@VSUSP@SUSP character +start@VSTART@START character +stop@VSTOP@STOP character +.TE +.RS 6 +.P +If +.IR string +is a single character, the control character shall be set to that +character. If +.IR string +is the two-character sequence +.BR \(dq^\(mi\(dq +or the string +.IR undef , +the control character shall be set to _POSIX_VDISABLE , if it is in +effect for the device; if _POSIX_VDISABLE is not in effect for the +device, it shall be treated as an error. In the POSIX locale, if +.IR string +is a two-character sequence beginning with + +(\c +.BR '^' ), +and the second character is one of those listed in the +.BR \(dq^c\(dq +column of the following table, the control character shall be set to +the corresponding character value in the Value column of the table. +.sp +.ce 1 +\fBTable: Circumflex Control Characters in \fIstty\fP\fR +.TS +center tab(@) box; +cB cB | cB cB | cB cB +lf5 2 l 6 | lf5 2 l 6 | lf5 2 l. +\&^c@Value@^c@Value@^c@Value +_ +a\fR,\fP A@@l\fR,\fP L@@w\fR,\fP W@ +b\fR,\fP B@@m\fR,\fP M@@x\fR,\fP X@ +c\fR,\fP C@@n\fR,\fP N@@y\fR,\fP Y@ +d\fR,\fP D@@o\fR,\fP O@@z\fR,\fP Z@ +e\fR,\fP E@@p\fR,\fP P@@[@ +f\fR,\fP F@@q\fR,\fP Q@@\e@ +g\fR,\fP G@@r\fR,\fP R@@]@ +h\fR,\fP H@@s\fR,\fP S@@\&^@ +i\fR,\fP I@@t\fR,\fP T@@\&_@ +j\fR,\fP J@@u\fR,\fP U@@?@ +k\fR,\fP K@@v\fR,\fP V@ +.TE +.RE +.IP "\fBmin\ \fInumber\fR" 6 +.br +Set the value of MIN to +.IR number . +MIN is used in non-canonical mode input processing (\c +.BR icanon ). +.IP "\fBtime\ \fInumber\fR" 6 +.br +Set the value of TIME to +.IR number . +TIME is used in non-canonical mode input processing (\c +.BR icanon ). +.SS "Combination Modes" +.IP "\fIsaved\ settings\fR" 6 +.br +Set the current terminal characteristics to the saved settings produced +by the +.BR \(mig +option. +.IP "\fBevenp\fR\ or\ \fBparity\fR" 6 +.br +Enable +.BR parenb +and +.BR cs7 ; +disable +.BR parodd . +.IP "\fBoddp\fR" 6 +.br +Enable +.BR parenb , +.BR cs7 , +and +.BR parodd . +.IP "\fB\(miparity\fR, \fB\(mievenp\fR, or \fB\(mioddp\fR" 6 +.br +Disable +.BR parenb , +and set +.BR cs8 . +.IP "\fBraw\ \fR(\fB\(miraw\fR\ or\ \fBcooked\fR)" 6 +.br +Enable (disable) raw input and output. Raw mode shall be equivalent to +setting: +.RS 6 +.sp +.RS 4 +.nf +\fB +stty cs8 erase ^\(mi kill ^\(mi intr ^\(mi \e + quit ^\(mi eof ^\(mi eol ^\(mi \(mipost \(miinpck +.fi \fR +.P +.RE +.RE +.IP "\fBnl\ \fR(\fB\(minl\fR)" 6 +.br +Disable (enable) +.BR icrnl . +In addition, +.BR \(minl +unsets +.BR inlcr +and +.BR igncr . +.IP "\fBek\fR" 6 +Reset ERASE and KILL characters back to system defaults. +.IP "\fBsane\fR" 6 +.br +Reset all modes to some reasonable, unspecified, values. +.SH STDIN +Although no input is read from standard input, standard input shall be +used to get the current terminal I/O characteristics and to set new +terminal I/O characteristics. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR stty : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +This variable determines the locale for the interpretation of sequences +of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and which characters are +in the class +.BR print . +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If operands are specified, no output shall be produced. +.P +If the +.BR \(mig +option is specified, +.IR stty +shall write to standard output the current settings in a form that can +be used as arguments to another instance of +.IR stty +on the same system. +.P +If the +.BR \(mia +option is specified, all of the information as described in the +OPERANDS section shall be written to standard output. Unless otherwise +specified, this information shall be written as +-separated +tokens in an unspecified format, on one or more lines, with an +unspecified number of tokens per line. Additional information may be +written. +.P +If no options or operands are specified, an unspecified subset of the +information written for the +.BR \(mia +option shall be written. +.P +If speed information is written as part of the default output, or if +the +.BR \(mia +option is specified and if the terminal input speed and output speed +are the same, the speed information shall be written as follows: +.sp +.RS 4 +.nf +\fB +"speed %d baud;", <\fIspeed\fR> +.fi \fR +.P +.RE +.P +Otherwise, speeds shall be written as: +.sp +.RS 4 +.nf +\fB +"ispeed %d baud; ospeed %d baud;", <\fIispeed\fR>, <\fIospeed\fR> +.fi \fR +.P +.RE +.P +In locales other than the POSIX locale, the word +.BR baud +may be changed to something more appropriate in those locales. +.P +If control characters are written as part of the default output, or if +the +.BR \(mia +option is specified, control characters shall be written as: +.sp +.RS 4 +.nf +\fB +"%s = %s;", <\fIcontrol-character name\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +where <\fIvalue\fP> is either the character, or some visual +representation of the character if it is non-printable, or the string +.IR undef +if the character is disabled. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The terminal options were read or set successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mig +flag is designed to facilitate the saving and restoring of terminal +state from the shell level. For example, a program may: +.sp +.RS 4 +.nf +\fB +saveterm="$(stty \(mig)" # save terminal state +stty \fI(new settings)\fR # set new state +\&... # ... +stty $saveterm # restore terminal state +.fi \fR +.P +.RE +.P +Since the format is unspecified, the saved value is not portable across +systems. +.P +Since the +.BR \(mia +format is so loosely specified, scripts that save and restore terminal +settings should use the +.BR \(mig +option. +.SH EXAMPLES +None. +.SH RATIONALE +The original +.IR stty +description was taken directly from System V and reflected the System V +terminal driver +.BR termio . +It has been modified to correspond to the terminal driver +.BR termios . +.P +Output modes are specified only for XSI-conformant systems. All +implementations are expected to provide +.IR stty +operands corresponding to all of the output modes they support. +.P +The +.IR stty +utility is primarily used to tailor the user interface of the terminal, +such as selecting the preferred ERASE and KILL characters. As an +application programming utility, +.IR stty +can be used within shell scripts to alter the terminal settings for the +duration of the script. +.P +The +.BR termios +section states that individual disabling of control characters is +possible through the option _POSIX_VDISABLE. +If enabled, two conventions currently exist for specifying this: System +V uses +.BR \(dq^\(mi\(dq , +and BSD uses +.IR undef . +Both are accepted by +.IR stty +in this volume of POSIX.1\(hy2008. The other BSD convention of using the letter +.BR 'u' +was rejected because it conflicts with the actual letter +.BR 'u' , +which is an acceptable value for a control character. +.P +Early proposals did not specify the mapping of +.BR \(dq^c\(dq +to control characters because the control characters were not specified +in the POSIX locale character set description file requirements. The +control character set is now specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 3" ", " "Definitions", +so the historical mapping is specified. Note that although the mapping +corresponds to control-character key assignments on many terminals that +use the ISO/IEC\ 646:\|1991 standard (or ASCII) character encodings, the mapping specified +here is to the control characters, not their keyboard encodings. +.P +Since +.BR termios +supports separate speeds for input and output, two new options were +added to specify each distinctly. +.P +Some historical implementations use standard input to get and set +terminal characteristics; others use standard output. Since input from +a login TTY is usually restricted to the owner while output to a TTY is +frequently open to anyone, using standard input provides fewer chances +of accidentally (or maliciously) altering the terminal settings of +other users. Using standard input also allows +.IR stty +.BR \(mia +and +.IR stty +.BR \(mig +output to be redirected for later use. Therefore, usage of standard +input is required by this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/tabs.1p b/man-pages-posix-2013-a/man1p/tabs.1p new file mode 100644 index 0000000..e323b9c --- /dev/null +++ b/man-pages-posix-2013-a/man1p/tabs.1p @@ -0,0 +1,291 @@ +'\" et +.TH TABS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tabs +\(em set terminal tabs +.SH SYNOPSIS +.LP +.nf +tabs \fB[\fR\(mi\fIn\fP|\(mia|\(mia2|\(mic|\(mic2|\(mic3|\(mif|\(mip|\(mis|\(miu\fB] [\fR\(miT \fItype\fB]\fR +.P +tabs \fB[\fR\(miT \fItype\fB] \fIn\fB[[\fIsep\fB[\fR+\fB]\fIn\fB]\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR tabs +utility shall display a series of characters that first clears the +hardware terminal tab settings and then initializes the tab stops at +the specified positions +and optionally adjusts the margin. +.P +The phrase ``tab-stop position +.IR N '' +shall be taken to mean that, from the start of a line of output, +tabbing to position +.IR N +shall cause the next character output to be in the (\c +.IR N +1)th +column position on that line. The maximum number of tab stops allowed +is terminal-dependent. +.P +It need not be possible to implement +.IR tabs +on certain terminals. If the terminal type obtained from the +.IR TERM +environment variable or +.BR \(miT +option represents such a terminal, an appropriate diagnostic message +shall be written to standard error and +.IR tabs +shall exit with a status greater than zero. +.SH OPTIONS +The +.IR tabs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for various extensions: the options +.BR \(mia2 , +.BR \(mic2 , +and +.BR \(mic3 +are multi-character. +.P +The following options shall be supported: +.IP "\fB\(mi\fIn\fR" 10 +Specify repetitive tab stops separated by a uniform number of column +positions, +.IR n , +where +.IR n +is a single-digit decimal number. The default usage of +.IR tabs +with no arguments shall be equivalent to +.IR tabs +\(mi8. When +.BR \(mi0 +is used, the tab stops shall be cleared and no new ones set. +.IP "\fB\(mia\fP" 10 +1,10,16,36,72 +.br +Assembler, applicable to some mainframes. +.IP "\fB\(mia2\fP" 10 +1,10,16,40,72 +.br +Assembler, applicable to some mainframes. +.IP "\fB\(mic\fP" 10 +1,8,12,16,20,55 +.br +COBOL, normal format. +.IP "\fB\(mic2\fP" 10 +1,6,10,14,49 +.br +COBOL, compact format (columns 1 to 6 omitted). +.IP "\fB\(mic3\fP" 10 +1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67 +.br +COBOL compact format (columns 1 to 6 omitted), with more tabs than +.BR \(mic2 . +.IP "\fB\(mif\fP" 10 +1,7,11,15,19,23 +.br +FORTRAN +.IP "\fB\(mip\fP" 10 +1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61 +.br +PL/1 +.IP "\fB\(mis\fP" 10 +1,10,55 +.br +SNOBOL +.IP "\fB\(miu\fP" 10 +1,12,20,44 +.br +Assembler, applicable to some mainframes. +.IP "\fB\(miT\ \fItype\fR" 10 +Indicate the type of terminal. If this option is not supplied and the +.IR TERM +variable is unset or null, an unspecified default terminal type shall +be used. The setting of +.IR type +shall take precedence over the value in +.IR TERM . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIn\fB[[\fIsep\fB[\fR+\fB]\fIn\fB]\fR...\fB]\fR" 10 +A single command line argument that consists of one or more tab-stop +values (\c +.IR n ) +separated by a separator character (\c +.IR sep ) +which is either a + +or a + +character. The application shall ensure that the tab-stop values are +positive decimal integers in strictly ascending order. If any tab-stop +value (except the first one) is preceded by a +, +it is taken as an increment to be added to the previous value. For +example, the tab lists 1,10,20,30 and +.BR \(dq1 10 +10 +10\(dq +are considered to be identical. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tabs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITERM\fP" 10 +Determine the terminal type. If this variable is unset or null, and if +the +.BR \(miT +option is not specified, an unspecified default terminal type shall be +used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If standard output is a terminal, the appropriate sequence to clear and +set the tab stops may be written to standard output in an unspecified +format. If standard output is not a terminal, undefined results +occur. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility makes use of the terminal's hardware tabs and the +.IR stty +.IR tabs +option. +.P +This utility is not recommended for application use. +.P +Some integrated display units might not have escape sequences to set +tab stops, but may be set by internal system calls. On these +terminals, +.IR tabs +works if standard output is directed to the terminal; if output is +directed to another file, however, +.IR tabs +fails. +.SH EXAMPLES +None. +.SH RATIONALE +Consideration was given to having the +.IR tput +utility handle all of the functions described in +.IR tabs . +However, the separate +.IR tabs +utility was retained because it seems more intuitive to use a command +named +.IR tabs +than +.IR tput +with a new option. The +.IR tput +utility does not support setting or clearing tabs, and no known +historical version of +.IR tabs +supports the capability of setting arbitrary tab stops. +.P +The System V +.IR tabs +interface is very complex; the version in this volume of POSIX.1\(hy2008 has a reduced feature +list, but many of the features omitted were restored as part of the +XSI option even though the supported languages and coding styles are +primarily historical. +.P +There was considerable sentiment for specifying only a means of +resetting the tabs back to a known state\(empresumably the ``standard'' +of tabs every eight positions. The following features were omitted: +.IP " *" 4 +Setting tab stops via the first line in a file, using \(mi\|\(mi\c +.IR file . +Since even the SVID has no complete explanation of this feature, it is +doubtful that it is in widespread use. +.P +In an early proposal, a +.BR \(mit +.IR tablist +option was added for consistency with +.IR expand ; +this was later removed when inconsistencies with the historical list of +tabs were identified. +.P +Consideration was given to adding a +.BR \(mip +option that would output the current tab settings so that they could be +saved and then later restored. This was not accepted because querying +the tab stops of the terminal is not a capability in historical +.IR terminfo +or +.IR termcap +facilities and might not be supported on a wide range of terminals. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexpand\fR\^", +.IR "\fIstty\fR\^", +.IR "\fItput\fR\^", +.IR "\fIunexpand\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/tail.1p b/man-pages-posix-2013-a/man1p/tail.1p new file mode 100644 index 0000000..28f5976 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/tail.1p @@ -0,0 +1,348 @@ +'\" et +.TH TAIL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tail +\(em copy the last part of a file +.SH SYNOPSIS +.LP +.nf +tail \fB[\fR\(mif\fB] [\fR\(mic \fInumber\fR|\(min \fInumber\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR tail +utility shall copy its input file to the standard output beginning at a +designated place. +.P +Copying shall begin at the point in the file indicated by the +.BR \(mic +.IR number +or +.BR \(min +.IR number +options. The option-argument +.IR number +shall be counted in units of lines or bytes, according to the options +.BR \(min +and +.BR \(mic . +Both line and byte counts start from 1. +.P +Tails relative to the end of the file may be saved in an internal +buffer, and thus may be limited in length. Such a buffer, if any, +shall be no smaller than +{LINE_MAX}*10 +bytes. +.SH OPTIONS +The +.IR tail +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\ \fInumber\fR" 10 +The application shall ensure that the +.IR number +option-argument is a decimal integer, optionally including a sign. +The sign shall affect the location in the file, measured in bytes, +to begin the copying: +.TS +center tab(@) box; +cB | cB +cf5 | l. +Sign@Copying Starts +_ ++@Relative to the beginning of the file. +\(mi@Relative to the end of the file. +\fInone\fP@Relative to the end of the file. +.TE +.RS 10 +.P +The application shall ensure that if the sign of the +.IR number +option-argument is +.BR '\(pl' , +the +.IR number +option-argument is a non-zero decimal integer. +.P +The origin for counting shall be 1; that is, +.BR \(mic ++1 represents the first byte of the file, +.BR \(mic +\(mi1 the last. +.RE +.IP "\fB\(mif\fP" 10 +If the input file is a regular file or if the +.IR file +operand specifies a FIFO, do not terminate after the last line of the +input file has been copied, but read and copy further bytes from the +input file when they become available. If no +.IR file +operand is specified and standard input is a pipe or FIFO, the +.BR \(mif +option shall be ignored. If the input file is not a FIFO, pipe, or +regular file, it is unspecified whether or not the +.BR \(mif +option shall be ignored. +.IP "\fB\(min\ \fInumber\fR" 10 +This option shall be equivalent to +.BR \(mic +.IR number , +except the starting location in the file shall be measured in lines +instead of bytes. The origin for counting shall be 1; that is, +.BR \(min ++1 represents the first line of the file, +.BR \(min +\(mi1 the last. +.P +If neither +.BR \(mic +nor +.BR \(min +is specified, +.BR \(min +10 shall be assumed. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operand is specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operand is specified, and shall be used if the +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +If the +.BR \(mic +option is specified, the input file can contain arbitrary data; +otherwise, the input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tail : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The designated portion of the input file shall be written to standard +output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mic +option should be used with caution when the input is a text file +containing multi-byte characters; it may produce output that does not +start on a character boundary. +.P +Although the input file to +.IR tail +can be any type, the results might not be what would be expected on +some character special device files or on file types not described by +the System Interfaces volume of POSIX.1\(hy2008. Since this volume of POSIX.1\(hy2008 does not specify the block size used when doing +input, +.IR tail +need not read all of the data from devices that only perform block +transfers. +.SH EXAMPLES +The +.BR \(mif +option can be used to monitor the growth of a file that is being +written by some other process. For example, the command: +.sp +.RS 4 +.nf +\fB +tail \(mif fred +.fi \fR +.P +.RE +.P +prints the last ten lines of the file +.BR fred , +followed by any lines that are appended to +.BR fred +between the time +.IR tail +is initiated and killed. As another example, the command: +.sp +.RS 4 +.nf +\fB +tail \(mif \(mic 15 fred +.fi \fR +.P +.RE +.P +prints the last 15 bytes of the file +.BR fred , +followed by any bytes that are appended to +.BR fred +between the time +.IR tail +is initiated and killed. +.SH RATIONALE +This version of +.IR tail +was created to allow conformance to the Utility Syntax Guidelines. The +historical +.BR \(mib +option was omitted because of the general non-portability of block-sized +units of text. The +.BR \(mic +option historically meant ``characters'', but this volume of POSIX.1\(hy2008 indicates +that it means ``bytes''. This was selected to allow reasonable +implementations when multi-byte characters are possible; it was not +named +.BR \(mib +to avoid confusion with the historical +.BR \(mib . +.P +The origin of counting both lines and bytes is 1, matching all +widespread historical implementations. Hence +.IR tail +.BR \(min ++0 is not conforming usage because it attempts to output line zero; but +note that +.IR tail +.BR \(min +0 does conform, and outputs nothing. +.P +Earlier versions of this standard allowed the following forms in the +SYNOPSIS: +.sp +.RS 4 +.nf +\fB +tail \(mi\fB[\fRnumber\fB][\fRb|c|l\fB][\fRf\fB] [\fIfile\fB]\fR +tail \(pl\fB[\fRnumber\fB][\fRb|c|l\fB][\fRf\fB] [\fIfile\fB]\fR +.fi \fR +.P +.RE +.P +These forms are no longer specified by POSIX.1\(hy2008, but may be +present in some implementations. +.P +The restriction on the internal buffer is a compromise between the +historical System V implementation of 4\|096 bytes and the BSD 32\|768 +bytes. +.P +The +.BR \(mif +option has been implemented as a loop that sleeps for 1 second and +copies any bytes that are available. This is sufficient, but if more +efficient methods of determining when new data are available are +developed, implementations are encouraged to use them. +.P +Historical documentation indicates that +.IR tail +ignores the +.BR \(mif +option if the input file is a pipe (pipe and FIFO on systems that +support FIFOs). On BSD-based systems, this has been true; on System +V-based systems, this was true when input was taken from standard +input, but it did not ignore the +.BR \(mif +flag if a FIFO was named as the +.IR file +operand. Since the +.BR \(mif +option is not useful on pipes and all historical implementations ignore +.BR \(mif +if no +.IR file +operand is specified and standard input is a pipe, this volume of POSIX.1\(hy2008 requires this +behavior. However, since the +.BR \(mif +option is useful on a FIFO, this volume of POSIX.1\(hy2008 also requires that +if a FIFO is named, the +.BR \(mif +option shall not be ignored. Earlier versions of this standard did +not state any requirement for the case where no +.IR file +operand is specified and standard input is a FIFO. The standard has +been updated to reflect current practice which is to treat this case +the same as a pipe on standard input. +Although historical behavior does not ignore the +.BR \(mif +option for other file types, this is unspecified so that +implementations are allowed to ignore the +.BR \(mif +option if it is known that the file cannot be extended. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIhead\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/talk.1p b/man-pages-posix-2013-a/man1p/talk.1p new file mode 100644 index 0000000..f622d55 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/talk.1p @@ -0,0 +1,309 @@ +'\" et +.TH TALK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +talk +\(em talk to another user +.SH SYNOPSIS +.LP +.nf +talk \fIaddress \fB[\fIterminal\fB]\fR +.fi +.SH DESCRIPTION +The +.IR talk +utility is a two-way, screen-oriented communication program. +.P +When first invoked, +.IR talk +shall send a message similar to: +.sp +.RS 4 +.nf +\fB +Message from <\fIunspecified string\fP> +talk: connection requested by \fIyour_address\fP +talk: respond with: talk \fIyour_address\fP +.fi \fR +.P +.RE +.P +to the specified +.IR address . +At this point, the recipient of the message can reply by typing: +.sp +.RS 4 +.nf +\fB +talk \fIyour_address\fR +.fi \fR +.P +.RE +.P +Once communication is established, the two parties can type +simultaneously, with their output displayed in separate regions of the +screen. Characters shall be processed as follows: +.IP " *" 4 +Typing the + +character shall alert the recipient's terminal. +.IP " *" 4 +Typing \(hyL shall cause the sender's screen regions to be +refreshed. +.IP " *" 4 +Typing the erase and kill characters shall affect the sender's terminal +in the manner described by the +.BR termios +interface in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP " *" 4 +Typing the interrupt or end-of-file characters shall terminate the +local +.IR talk +utility. Once the +.IR talk +session has been terminated on one side, the other side of the +.IR talk +session shall be notified that the +.IR talk +session has been terminated and shall be able to do nothing except +exit. +.IP " *" 4 +Typing characters from +.IR LC_CTYPE +classifications +.BR print +or +.BR space +shall cause those characters to be sent to the recipient's terminal. +.IP " *" 4 +When and only when the +.IR stty +.BR iexten +local mode is enabled, the existence and processing of additional +special control characters and multi-byte or single-byte functions +shall be implementation-defined. +.IP " *" 4 +Typing other non-printable characters shall cause +implementation-defined sequences of printable characters to be sent +to the recipient's terminal. +.P +Permission to be a recipient of a +.IR talk +message can be denied or granted by use of the +.IR mesg +utility. However, a user's privilege may further constrain the domain +of accessibility of other users' terminals. The +.IR talk +utility shall fail when the user lacks appropriate privileges to +perform the requested action. +.P +Certain block-mode terminals do not have all the capabilities necessary +to support the simultaneous exchange of messages required for +.IR talk . +When this type of exchange cannot be supported on such terminals, the +implementation may support an exchange with reduced levels of +simultaneous interaction or it may report an error describing the +terminal-related deficiency. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIaddress\fR" 10 +The recipient of the +.IR talk +session. One form of +.IR address +is the <\fIuser\ name\fP>, as returned by the +.IR who +utility. Other address formats and how they are handled are +unspecified. +.IP "\fIterminal\fR" 10 +If the recipient is logged in more than once, the +.IR terminal +argument can be used to indicate the appropriate terminal name. If +.IR terminal +is not specified, the +.IR talk +message shall be displayed on one or more accessible terminals in use +by the recipient. The format of +.IR terminal +shall be the same as that returned by the +.IR who +utility. +.SH STDIN +Characters read from standard input shall be copied to the recipient's +terminal in an unspecified manner. If standard input is not a +terminal, talk shall write a diagnostic message and exit with a +non-zero status. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR talk : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). If the +recipient's locale does not use an +.IR LC_CTYPE +equivalent to the sender's, the results are undefined. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITERM\fP" 10 +Determine the name of the invoker's terminal type. If this variable is +unset or null, an unspecified default terminal type shall be used. +.SH "ASYNCHRONOUS EVENTS" +When the +.IR talk +utility receives a SIGINT signal, the utility shall terminate and exit +with a zero status. It shall take the standard action for all other +signals. +.SH STDOUT +If standard output is a terminal, characters copied from the +recipient's standard input may be written to standard output. Standard +output also may be used for diagnostic messages. If standard output is +not a terminal, +.IR talk +shall exit with a non-zero status. +.SH STDERR +None. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred or +.IR talk +was invoked on a terminal incapable of supporting it. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Because the handling of non-printable, non-\c + +characters is tied to the +.IR stty +description of +.BR iexten , +implementation extensions within the terminal driver can be accessed. +For example, some implementations provide line editing functions with +certain control character sequences. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR write +utility was included in this volume of POSIX.1\(hy2008 since it can be implemented on all +terminal types. The +.IR talk +utility, which cannot be implemented on certain terminals, was +considered to be a ``better'' communications interface. Both of these +programs are in widespread use on historical implementations. +Therefore, both utilities have been specified. +.P +All references to networking abilities (\fItalk\fPing to a user on +another system) were removed as being outside the scope of this volume of POSIX.1\(hy2008. +.P +Historical BSD and System V versions of +.IR talk +terminate both of the conversations when either user breaks out of the +session. This can lead to adverse consequences if a user unwittingly +continues to enter text that is interpreted by the shell when the other +terminates the session. Therefore, the version of +.IR talk +specified by this volume of POSIX.1\(hy2008 requires both users to terminate their end of the +session explicitly. +.P +Only messages sent to the terminal of the invoking user can be +internationalized in any way: +.IP " *" 4 +The original ``Message from <\fIunspecified string\fP> .\|.\|.'' +message sent to the terminal of the recipient cannot be +internationalized because the environment of the recipient is as yet +inaccessible to the +.IR talk +utility. The environment of the invoking party is irrelevant. +.IP " *" 4 +Subsequent communication between the two parties cannot be +internationalized because the two parties may specify different +languages in their environment (and non-portable characters cannot be +mapped from one language to another). +.IP " *" 4 +Neither party can be required to communicate in a language other than C +and/or the one specified by their environment because unavailable +terminal hardware support (for example, fonts) may be required. +.P +The text in the STDOUT section reflects the usage of the verb +``display'' in this section; some +.IR talk +implementations actually use standard output to write to the terminal, +but this volume of POSIX.1\(hy2008 does not require that to be the case. +.P +The format of the terminal name is unspecified, but the descriptions of +.IR ps , +.IR talk , +.IR who , +and +.IR write +require that they all use or accept the same format. +.P +The handling of non-printable characters is partially +implementation-defined +because the details of mapping them to printable sequences is not +needed by the user. Historical implementations, for security reasons, +disallow the transmission of non-printable characters that may send +commands to the other terminal. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImesg\fR\^", +.IR "\fIstty\fR\^", +.IR "\fIwho\fR\^", +.IR "\fIwrite\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/tee.1p b/man-pages-posix-2013-a/man1p/tee.1p new file mode 100644 index 0000000..4f8dfde --- /dev/null +++ b/man-pages-posix-2013-a/man1p/tee.1p @@ -0,0 +1,196 @@ +'\" et +.TH TEE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tee +\(em duplicate standard input +.SH SYNOPSIS +.LP +.nf +tee \fB[\fR\(miai\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR tee +utility shall copy standard input to standard output, making a copy in +zero or more files. The +.IR tee +utility shall not buffer output. +.P +If the +.BR \(mia +option is not specified, output files shall be written (see +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +.SH OPTIONS +The +.IR tee +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Append the output to the files. +.IP "\fB\(mii\fP" 10 +Ignore the SIGINT signal. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an output file. If a +.IR file +operand is +.BR '\(mi' , +it shall refer to a file named +.BR \(mi ; +implementations shall not treat it as meaning standard output. +Processing of at least 13 +.IR file +operands shall be supported. +.SH STDIN +The standard input can be of any type. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tee : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default, except that if the +.BR \(mii +option was specified, SIGINT shall be ignored. +.SH STDOUT +The standard output shall be a copy of the standard input. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +If any +.IR file +operands are specified, the standard input shall be copied to each +named file. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The standard input was successfully copied to all output files. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If a write to any successfully opened +.IR file +operand fails, writes to other successfully opened +.IR file +operands and standard output shall continue, but the exit status shall +be non-zero. Otherwise, the default actions specified in +.IR "Section 1.4" ", " "Utility Description Defaults" +apply. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR tee +utility is usually used in a pipeline, to make a copy of the output of +some utility. +.P +The +.IR file +operand is technically optional, but +.IR tee +is no more useful than +.IR cat +when none is specified. +.SH EXAMPLES +Save an unsorted intermediate form of the data in a pipeline: +.sp +.RS 4 +.nf +\fB +\&... | tee unsorted | sort > sorted +.fi \fR +.P +.RE +.SH RATIONALE +The buffering requirement means that +.IR tee +is not allowed to use ISO\ C standard fully buffered or line-buffered writes. It +does not mean that +.IR tee +has to do 1-byte reads followed by 1-byte writes. +.P +It should be noted that early versions of BSD ignore any invalid +options and accept a single +.BR '\(mi' +as an alternative to +.BR \(mii . +They also print a message if unable to open a file: +.sp +.RS 4 +.nf +\fB +"tee: cannot access %s\en", <\fIpathname\fP> +.fi \fR +.P +.RE +.P +Historical implementations ignore write errors. This is explicitly not +permitted by this volume of POSIX.1\(hy2008. +.P +Some historical implementations use O_APPEND when providing append +mode; others use the +\fIlseek\fR() +function to seek to the end-of-file after opening the file without +O_APPEND. This volume of POSIX.1\(hy2008 requires functionality equivalent to using O_APPEND; +see +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 1" ", " "Introduction", +.IR "\fIcat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIlseek\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/test.1p b/man-pages-posix-2013-a/man1p/test.1p new file mode 100644 index 0000000..f9779dd --- /dev/null +++ b/man-pages-posix-2013-a/man1p/test.1p @@ -0,0 +1,1058 @@ +'\" et +.TH TEST "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +test +\(em evaluate expression +.SH SYNOPSIS +.LP +.nf +test \fB[\fIexpression\fB]\fR +.P +[ \fB[\fIexpression\fB]\fR ] +.fi +.SH DESCRIPTION +The +.IR test +utility shall evaluate the +.IR expression +and indicate the result of the evaluation by its exit status. An exit +status of zero indicates that the expression evaluated as true and an +exit status of 1 indicates that the expression evaluated as false. +.P +In the second form of the utility, which uses +.BR \(dq[]\(dq +rather than +.IR test , +the application shall ensure that the square brackets are separate +arguments. +.SH OPTIONS +The +.IR test +utility shall not recognize the +.BR \(dq\(mi\|\(mi\(dq +argument in the manner specified by Guideline 10 in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +No options shall be supported. +.SH OPERANDS +The application shall ensure that all operators and elements of +primaries are presented as separate arguments to the +.IR test +utility. +.P +The following primaries can be used to construct +.IR expression : +.IP "\fB\(mib\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to en existing directory entry for a block special file. +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a block +special file. +.IP "\fB\(mic\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a character special file. +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a character +special file. +.IP "\fB\(mid\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a directory. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a +directory. +.IP "\fB\(mie\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry. False if +.IR pathname +cannot be resolved. +.IP "\fB\(mif\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a regular file. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a +regular file. +.IP "\fB\(mig\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file that has its +set-group-ID flag set. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that does not have +its set-group-ID flag set. +.IP "\fB\(mih\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a symbolic link. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a symbolic +link. If the final component of +.IR pathname +is a symbolic link, that symbolic link is not followed. +.IP "\fB\(miL\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a symbolic link. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a symbolic +link. If the final component of +.IR pathname +is a symbolic link, that symbolic link is not followed. +.IP "\fB\(min\ \fIstring\fR" 10 +True if the length of +.IR string +is non-zero; otherwise, false. +.IP "\fB\(mip\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a FIFO. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a FIFO. +.IP "\fB\(mir\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file for which permission +to read from the file will be granted, as defined in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file for which permission +to read from the file will not be granted. +.IP "\fB\(miS\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a socket. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a socket. +.IP "\fB\(mis\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file that has a size +greater than zero. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that does not have +a size greater than zero. +.IP "\fB\(mit\ \fIfile_descriptor\fR" 10 +.br +True if file descriptor number +.IR file_descriptor +is open and is associated with a terminal. False if +.IR file_descriptor +is not a valid file descriptor number, or if file descriptor number +.IR file_descriptor +is not open, or if it is open but is not associated with a terminal. +.IP "\fB\(miu\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file that has its +set-user-ID flag set. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that does not have +its set-user-ID flag set. +.IP "\fB\(miw\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file for which permission +to write to the file will be granted, as defined in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file for which permission +to write to the file will not be granted. +.IP "\fB\(mix\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file for which permission +to execute the file (or search it, if it is a directory) will be granted, +as defined in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file for which permission +to execute (or search) the file will not be granted. +.IP "\fB\(miz\ \fIstring\fR" 10 +True if the length of string +.IR string +is zero; otherwise, false. +.IP "\fIstring\fR" 10 +True if the string +.IR string +is not the null string; otherwise, false. +.IP "\fIs1\fB\ \(eq\ \fIs2\fR" 10 +True if the strings +.IR s1 +and +.IR s2 +are identical; otherwise, false. +.IP "\fIs1\fB\ !=\ \fIs2\fR" 10 +True if the strings +.IR s1 +and +.IR s2 +are not identical; otherwise, false. +.IP "\fIn1\fB\ \(mieq\ \fIn2\fR" 10 +True if the integers +.IR n1 +and +.IR n2 +are algebraically equal; otherwise, false. +.IP "\fIn1\fB\ \(mine\ \fIn2\fR" 10 +True if the integers +.IR n1 +and +.IR n2 +are not algebraically equal; otherwise, false. +.IP "\fIn1\fB\ \(migt\ \fIn2\fR" 10 +True if the integer +.IR n1 +is algebraically greater than the integer +.IR n2 ; +otherwise, false. +.IP "\fIn1\fB\ \(mige\ \fIn2\fR" 10 +True if the integer +.IR n1 +is algebraically greater than or equal to the integer +.IR n2 ; +otherwise, false. +.IP "\fIn1\fB\ \(milt\ \fIn2\fR" 10 +True if the integer +.IR n1 +is algebraically less than the integer +.IR n2 ; +otherwise, false. +.IP "\fIn1\fB\ \(mile\ \fIn2\fR" 10 +True if the integer +.IR n1 +is algebraically less than or equal to the integer +.IR n2 ; +otherwise, false. +.IP "\fIexpression1\fB\ \(mia\ \fIexpression2\fR" 10 +.br +True if both +.IR expression1 +and +.IR expression2 +are true; otherwise, false. The +.BR \(mia +binary primary is left associative. It has a higher precedence than +.BR \(mio . +.IP "\fIexpression1\fB\ \(mio\ \fIexpression2\fR" 10 +.br +True if either +.IR expression1 +or +.IR expression2 +is true; otherwise, false. The +.BR \(mio +binary primary is left associative. +.P +With the exception of the +.BR \(mih +.IR pathname +and +.BR \(miL +.IR pathname +primaries, if a +.IR pathname +argument is a symbolic link, +.IR test +shall evaluate the expression by resolving the symbolic link and using +the file referenced by the link. +.P +These primaries can be combined with the following operators: +.IP "\fB!\ \fIexpression\fR" 10 +True if +.IR expression +is false. False if +.IR expression +is true. +.IP "\fB(\ \fIexpression\ \fB)\fR" 10 +True if +.IR expression +is true. False if +.IR expression +is false. The parentheses can be used to alter the normal precedence +and associativity. +.P +The primaries with two elements of the form: +.sp +.RS 4 +.nf +\fB +\(mi\fIprimary_operator primary_operand\fR +.fi \fR +.P +.RE +.P +are known as +.IR "unary primaries" . +The primaries with three elements in either of the two forms: +.sp +.RS 4 +.nf +\fB +\fIprimary_operand \fR\(mi\fIprimary_operator primary_operand +.P +primary_operand primary_operator primary_operand\fR +.fi \fR +.P +.RE +.P +are known as +.IR "binary primaries" . +Additional implementation-defined operators and +.IR primary_operator s +may be provided by implementations. They shall be of the form \(mi\c +.IR operator +where the first character of +.IR operator +is not a digit. +.P +The algorithm for determining the precedence of the operators and the +return value that shall be generated is based on the number of +arguments presented to +.IR test . +(However, when using the +.BR \(dq[...]\(dq +form, the + +final argument shall not be counted in this algorithm.) +.P +In the following list, $1, $2, $3, and $4 represent the arguments +presented to +.IR test : +.IP "0\ arguments:" 12 +Exit false (1). +.IP "1\ argument:" 12 +Exit true (0) if $1 is not null; otherwise, exit false. +.IP "2\ arguments:" 12 +.sp -1v +.RS 12 +.IP " *" 4 +If $1 is +.BR '!' , +exit true if $2 is null, false if $2 is not null. +.IP " *" 4 +If $1 is a unary primary, exit true if the unary test is true, false if +the unary test is false. +.IP " *" 4 +Otherwise, produce unspecified results. +.RE +.IP "3\ arguments:" 12 +.sp -1v +.RS 12 +.IP " *" 4 +If $2 is a binary primary, perform the binary test of $1 and $3. +.IP " *" 4 +If $1 is +.BR '!' , +negate the two-argument test of $2 and $3. +.IP " *" 4 +If $1 is +.BR '(' +and $3 is +.BR ')' , +perform the unary test of $2. +On systems that do not support the XSI option, the results are +unspecified if $1 is +.BR '(' +and $3 is +.BR ')' . +.IP " *" 4 +Otherwise, produce unspecified results. +.RE +.IP "4\ arguments:" 12 +.sp -1v +.RS 12 +.IP " *" 4 +If $1 is +.BR '!' , +negate the three-argument test of $2, $3, and $4. +.IP " *" 4 +If $1 is +.BR '(' +and $4 is +.BR ')' , +perform the two-argument test of $2 and $3. +On systems that do not support the XSI option, the results are +unspecified if $1 is +.BR '(' +and $4 is +.BR ')' . +.IP " *" 4 +Otherwise, the results are unspecified. +.RE +.IP ">4\ arguments:" 12 +The results are unspecified. +.RS 12 +.P +On XSI-conformant systems, combinations of primaries and operators +shall be evaluated using the precedence and associativity rules +described previously. In addition, the string comparison binary +primaries +.BR '=' +and +.BR \(dq!=\(dq +shall have a higher precedence than any unary primary. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR test : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +.IR expression +evaluated to true. +.IP "\01" 6 +.IR expression +evaluated to false or +.IR expression +was missing. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The XSI extensions specifying the +.BR \(mia +and +.BR \(mio +binary primaries and the +.BR '(' +and +.BR ')' +operators have been marked obsolescent. (Many expressions using them +are ambiguously defined by the grammar depending on the specific +expressions being evaluated.) Scripts using these expressions should be +converted to the forms given below. Even though many implementations +will continue to support these obsolescent forms, scripts should be +extremely careful when dealing with user-supplied input that could be +confused with these and other primaries and operators. Unless the +application developer knows all the cases that produce input to the +script, invocations like: +.sp +.RS 4 +.nf +\fB +test "$1" \(mia "$2" +.fi \fR +.P +.RE +.P +should be written as: +.sp +.RS 4 +.nf +\fB +test "$1" && test "$2" +.fi \fR +.P +.RE +.P +to avoid problems if a user supplied values such as $1 set to +.BR '!' +and $2 set to the null string. That is, in cases where maximal +portability is of concern, replace: +.sp +.RS 4 +.nf +\fB +test expr1 \(mia expr2 +.fi \fR +.P +.RE +.P +with: +.sp +.RS 4 +.nf +\fB +test expr1 && test expr2 +.fi \fR +.P +.RE +.P +and replace: +.sp +.RS 4 +.nf +\fB +test expr1 \(mio expr2 +.fi \fR +.P +.RE +.P +with: +.sp +.RS 4 +.nf +\fB +test expr1 || test expr2 +.fi \fR +.P +.RE +.P +but note that, in +.IR test , +.BR \(mia +has higher precedence than +.BR \(mio +while +.BR \(dq&&\(dq +and +.BR \(dq||\(dq +have equal precedence in the shell. +.P +Parentheses or braces can be used in the shell command language to +effect grouping. +.P +Parentheses must be escaped when using +.IR sh ; +for example: +.sp +.RS 4 +.nf +\fB +test \e( expr1 \(mia expr2 \e) \(mio expr3 +.fi \fR +.P +.RE +.P +This command is not always portable even on XSI-conformant systems +depending on the expressions specified by +.IR expr 1, +.IR expr 2, +and +.IR expr 3. +The following form can be used instead: +.sp +.RS 4 +.nf +\fB +( test expr1 && test expr2 ) || test expr3 +.fi \fR +.P +.RE +.P +The two commands: +.sp +.RS 4 +.nf +\fB +test "$1" +test ! "$1" +.fi \fR +.P +.RE +.P +could not be used reliably on some historical systems. Unexpected +results would occur if such a +.IR string +expression were used and $1 expanded to +.BR '!' , +.BR '(' , +or a known unary primary. Better constructs are: +.sp +.RS 4 +.nf +\fB +test \(min "$1" +test \(miz "$1" +.fi \fR +.P +.RE +respectively. +.P +Historical systems have also been unreliable given the common +construct: +.sp +.RS 4 +.nf +\fB +test "$response" = "expected string" +.fi \fR +.P +.RE +.P +One of the following is a more reliable form: +.sp +.RS 4 +.nf +\fB +test "X$response" = "Xexpected string" +test "expected string" = "$response" +.fi \fR +.P +.RE +.P +Note that the second form assumes that +.IR "expected string" +could not be confused with any unary primary. If +.IR "expected string" +starts with +.BR '\(mi' , +.BR '(' , +.BR '!' , +or even +.BR '=' , +the first form should be used instead. Using the preceding rules +without the XSI marked extensions, any of the three comparison forms is +reliable, given any input. (However, note that the strings are quoted +in all cases.) +.P +Because the string comparison binary primaries, +.BR '=' +and +.BR \(dq!=\(dq , +have a higher precedence than any unary primary in the greater than 4 +argument case, unexpected results can occur if arguments are not +properly prepared. For example, in: +.sp +.RS 4 +.nf +\fB +test \(mid $1 \(mio \(mid $2 +.fi \fR +.P +.RE +.P +If $1 evaluates to a possible directory name of +.BR '=' , +the first three arguments are considered a string comparison, which +shall cause a syntax error when the second +.BR \(mid +is encountered. One of the following forms prevents this; the second +is preferred: +.sp +.RS 4 +.nf +\fB +test \e( \(mid "$1" \e) \(mio \e( \(mid "$2" \e) +test \(mid "$1" || test \(mid "$2" +.fi \fR +.P +.RE +.P +Also in the greater than 4 argument case: +.sp +.RS 4 +.nf +\fB +test "$1" = "bat" \(mia "$2" = "ball" +.fi \fR +.P +.RE +.P +syntax errors occur if $1 evaluates to +.BR '(' +or +.BR '!' . +One of the following forms prevents this; the third is preferred: +.sp +.RS 4 +.nf +\fB +test "X$1" = "Xbat" \(mia "X$2" = "Xball" +test "$1" = "bat" && test "$2" = "ball" +test "X$1" = "Xbat" && test "X$2" = "Xball" +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +Exit if there are not two or three arguments (two variations): +.RS 4 +.sp +.RS 4 +.nf +\fB +if [ $# \(mine 2 ] && [ $# \(mine 3 ]; then exit 1; fi +if [ $# \(milt 2 ] || [ $# \(migt 3 ]; then exit 1; fi +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Perform a +.IR mkdir +if a directory does not exist: +.RS 4 +.sp +.RS 4 +.nf +\fB +test ! \(mid tempdir && mkdir tempdir +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Wait for a file to become non-readable: +.RS 4 +.sp +.RS 4 +.nf +\fB +while test \(mir thefile +do + sleep 30 +done +echo '"thefile" is no longer readable' +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Perform a command if the argument is one of three strings (two +variations): +.RS 4 +.sp +.RS 4 +.nf +\fB +if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ] +then + \fIcommand\fP +fi +.P +case "$1" in + pear|grape|apple) \fIcommand\fP ;; +esac +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The KornShell-derived conditional command (double bracket +.BR [[\|]] ) +was removed from the shell command language description in an early +proposal. Objections were raised that the real problem is misuse of the +.IR test +command (\c +.BR [ ), +and putting it into the shell is the wrong way to fix the problem. +Instead, proper documentation and a new shell reserved word (\c +.BR ! ) +are sufficient. +.P +Tests that require multiple +.IR test +operations can be done at the shell level using individual invocations +of the +.IR test +command and shell logicals, rather than using the error-prone +.BR \(mio +flag of +.IR test . +.P +XSI-conformant systems support more than four arguments. +.P +XSI-conformant systems support the combining of primaries with the +following constructs: +.IP "\fIexpression1\fB \(mia \fIexpression2\fR" 6 +.br +True if both +.IR expression1 +and +.IR expression2 +are true. +.IP "\fIexpression1\fB \(mio \fIexpression2\fR" 6 +.br +True if at least one of +.IR expression1 +and +.IR expression2 +are true. +.IP "\fB( \fIexpression \fB)\fR" 6 +.br +True if +.IR expression +is true. +.P +In evaluating these more complex combined expressions, the following +precedence rules are used: +.IP " *" 4 +The unary primaries have higher precedence than the algebraic binary +primaries. +.IP " *" 4 +The unary primaries have lower precedence than the string binary +primaries. +.IP " *" 4 +The unary and binary primaries have higher precedence than the unary +.IR string +primary. +.IP " *" 4 +The +.BR ! +operator has higher precedence than the +.BR \(mia +operator, and the +.BR \(mia +operator has higher precedence than the +.BR \(mio +operator. +.IP " *" 4 +The +.BR \(mia +and +.BR \(mio +operators are left associative. +.IP " *" 4 +The parentheses can be used to alter the normal precedence and +associativity. +.P +The BSD and System V versions of +.BR \(mif +are not the same. The BSD definition was: +.IP "\fB\(mif\ \fIfile\fR" 10 +True if +.IR file +exists and is not a directory. +.P +The SVID version (true if the file exists and is a regular file) was +chosen for this volume of POSIX.1\(hy2008 because its use is consistent with the +.BR \(mib , +.BR \(mic , +.BR \(mid , +and +.BR \(mip +operands (\c +.IR file +exists and is a specific file type). +.P +The +.BR \(mie +primary, possessing similar functionality to that provided by the C +shell, was added because it provides the only way for a shell script to +find out if a file exists without trying to open the file. Since +implementations are allowed to add additional file types, a portable +script cannot use: +.sp +.RS 4 +.nf +\fB +test \(mib foo \(mio \(mic foo \(mio \(mid foo \(mio \(mif foo \(mio \(mip foo +.fi \fR +.P +.RE +.P +to find out if +.BR foo +is an existing file. On historical BSD systems, the existence of a +file could be determined by: +.sp +.RS 4 +.nf +\fB +test \(mif foo \(mio \(mid foo +.fi \fR +.P +.RE +.P +but there was no easy way to determine that an existing file was a +regular file. An early proposal used the KornShell +.BR \(mia +primary (with the same meaning), but this was changed to +.BR \(mie +because there were concerns about the high probability of humans +confusing the +.BR \(mia +primary with the +.BR \(mia +binary operator. +.P +The following options were not included in this volume of POSIX.1\(hy2008, although they are +provided by some implementations. These operands should not be used by +new implementations for other purposes: +.IP "\fB\(mik\ \fIfile\fR" 10 +True if +.IR file +exists and its sticky bit is set. +.IP "\fB\(miC\ \fIfile\fR" 10 +True if +.IR file +is a contiguous file. +.IP "\fB\(miV\ \fIfile\fR" 10 +True if +.IR file +is a version file. +.P +The following option was not included because it was undocumented in +most implementations, has been removed from some implementations +(including System V), and the functionality is provided by the shell +(see +.IR "Section 2.6.2" ", " "Parameter Expansion". +.IP "\fB\(mil\ \fIstring\fR" 10 +The length of the string +.IR string . +.P +The +.BR \(mib , +.BR \(mic , +.BR \(mig , +.BR \(mip , +.BR \(miu , +and +.BR \(mix +operands are derived from the SVID; historical BSD does not provide +them. The +.BR \(mik +operand is derived from System V; historical BSD does not provide it. +.P +On historical BSD systems, +.IR test +.BR \(miw +.IR directory +always returned false because +.IR test +tried to open the directory for writing, which always fails. +.P +Some additional primaries newly invented or from the KornShell appeared +in an early proposal as part of the conditional command (\c +.BR [[\|]] ): +.IR s1 +.BR > +.IR s2 , +.IR s1 +.BR < +.IR s2 , +.IR str +.BR = +.IR pattern , +.IR str +.BR != +.IR pattern , +.IR f1 +.BR \(mint +.IR f2 , +.IR f1 +.BR \(miot +.IR f2 , +and +.IR f1 +.BR \(mief +.IR f2 . +They were not carried forward into the +.IR test +utility when the conditional command was removed from the shell because +they have not been included in the +.IR test +utility built into historical implementations of the +.IR sh +utility. +.P +The +.BR \(mit +.IR file_descriptor +primary is shown with a mandatory argument because the grammar is +ambiguous if it can be omitted. Historical implementations have allowed +it to be omitted, providing a default of 1. +.P +It is noted that +.BR '[' +is not part of the portable filename character set; however, since it +is required to be encoded by a single byte, and is part of the portable +character set, the name of this utility forms a character string across +all supported locales. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation", +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/time.1p b/man-pages-posix-2013-a/man1p/time.1p new file mode 100644 index 0000000..7dc70ab --- /dev/null +++ b/man-pages-posix-2013-a/man1p/time.1p @@ -0,0 +1,320 @@ +'\" et +.TH TIME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +time +\(em time a simple command +.SH SYNOPSIS +.LP +.nf +time \fB[\fR\(mip\fB] \fIutility \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR time +utility shall invoke the utility named by the +.IR utility +operand with arguments supplied as the +.IR argument +operands and write a message to standard error that lists timing +statistics for the utility. The message shall include the following +information: +.IP " *" 4 +The elapsed (real) time between invocation of +.IR utility +and its termination. +.IP " *" 4 +The User CPU time, equivalent to the sum of the +.IR tms_utime +and +.IR tms_cutime +fields returned by the +\fItimes\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 for the process in which +.IR utility +is executed. +.IP " *" 4 +The System CPU time, equivalent to the sum of the +.IR tms_stime +and +.IR tms_cstime +fields returned by the +\fItimes\fR() +function for the process in which +.IR utility +is executed. +.P +The precision of the timing shall be no less than the granularity +defined for the size of the clock tick unit on the system, but the +results shall be reported in terms of standard time units (for example, +0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), not numbers of +clock ticks. +.P +When +.IR time +is used as part of a pipeline, the times reported are unspecified, +except when it is the sole command within a grouping command (see +.IR "Section 2.9.4.1" ", " "Grouping Commands") +in that pipeline. For example, the commands on the left are +unspecified; those on the right report on utilities +.BR a +and +.BR c , +respectively: +.sp +.RS 4 +.nf +\fB +time a | b | c { time a; } | b | c +a | b | time c a | b | (time c) +.fi \fR +.P +.RE +.SH OPTIONS +The +.IR time +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mip\fP" 10 +Write the timing output to standard error in the format shown in the +STDERR section. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility that is to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +Any string to be supplied as an argument when invoking the utility +named by the +.IR utility +operand. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR time : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic and informative messages written to standard +error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for numeric formatting. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path that shall be used to locate the utility to +be invoked; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used to write the timing statistics. If +.BR \(mip +is specified, the following format shall be used in the POSIX locale: +.sp +.RS 4 +.nf +\fB +"real %f\enuser %f\ensys %f\en", <\fIreal seconds\fR>, <\fIuser seconds\fR>, + <\fIsystem seconds\fR> +.fi \fR +.P +.RE +.P +where each floating-point number shall be expressed in seconds. The +precision used may be less than the default six digits of +.BR %f , +but shall be sufficiently precise to accommodate the size of the clock +tick on the system (for example, if there were 60 clock ticks per +second, at least two digits shall follow the radix character). The +number of digits following the radix character shall be no less than +one, even if this always results in a trailing zero. The implementation +may append white space and additional information following the format +shown here. The implementation may also prepend a single empty line +before the format shown here. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If the +.IR utility +utility is invoked, the exit status of +.IR time +shall be the exit status of +.IR utility ; +otherwise, the +.IR time +utility shall exit with one of the following values: +.IP "1\(hy125" 8 +An error occurred in the +.IR time +utility. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +It is frequently desirable to apply +.IR time +to pipelines or lists of commands. This can be done by placing +pipelines and command lists in a single file; this file can then be +invoked as a utility, and the +.IR time +applies to everything in the file. +.P +Alternatively, the following command can be used to apply +.IR time +to a complex command: +.sp +.RS 4 +.nf +\fB +time sh \(mic '\fIcomplex-command-line\fP' +.fi \fR +.P +.RE +.SH RATIONALE +When the +.IR time +utility was originally proposed to be included in the ISO\ POSIX\(hy2:\|1993 standard, +questions were raised about its suitability for inclusion on +the grounds that it was not useful for conforming applications, +specifically: +.IP " *" 4 +The underlying CPU definitions from the System Interfaces volume of POSIX.1\(hy2008 are +vague, so the numeric output could not be compared accurately between +systems or even between invocations. +.IP " *" 4 +The creation of portable benchmark programs was outside the scope this volume of POSIX.1\(hy2008. +.P +However, +.IR time +does fit in the scope of user portability. Human judgement can be +applied to the analysis of the output, and it could be very useful in +hands-on debugging of applications or in providing subjective measures +of system performance. Hence it has been included in this volume of POSIX.1\(hy2008. +.P +The default output format has been left unspecified because historical +implementations differ greatly in their style of depicting this numeric +output. The +.BR \(mip +option was invented to provide scripts with a common means of obtaining +this information. +.P +In the KornShell, +.IR time +is a shell reserved word that can be used to time an entire pipeline, +rather than just a simple command. The POSIX definition has been +worded to allow this implementation. Consideration was given to +invalidating this approach because of the historical model from the C +shell and System V shell. However, since the System V +.IR time +utility historically has not produced accurate results in pipeline +timing (because the constituent processes are not all owned by the same +parent process, as allowed by POSIX), it did not seem worthwhile to +break historical KornShell usage. +.P +The term +.IR utility +is used, rather than +.IR command , +to highlight the fact that shell compound commands, pipelines, special +built-ins, and so on, cannot be used directly. +However, +.IR utility +includes user application programs and shell scripts, not just the +standard utilities. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fItimes\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/times.1p b/man-pages-posix-2013-a/man1p/times.1p new file mode 100644 index 0000000..79cb57a --- /dev/null +++ b/man-pages-posix-2013-a/man1p/times.1p @@ -0,0 +1,112 @@ +'\" et +.TH TIMES "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +times +\(em write process times +.SH SYNOPSIS +.LP +.nf +times\fR +.fi +.SH DESCRIPTION +The +.IR times +utility shall write the accumulated user and system times for the shell +and for all of its child processes, in the following POSIX locale +format: +.sp +.RS 4 +.nf +\fB +"%dm%fs %dm%fs\en%dm%fs %dm%fs\en", <\fIshell user minutes\fR>, + <\fIshell user seconds\fR>, <\fIshell system minutes\fR>, + <\fIshell system seconds\fR>, <\fIchildren user minutes\fR>, + <\fIchildren user seconds\fR>, <\fIchildren system minutes\fR>, + <\fIchildren system seconds\fR> +.fi \fR +.P +.RE +.P +The four pairs of times shall correspond to the members of the +.IR +.BR tms +structure (defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 13" ", " "Headers") +as returned by +\fItimes\fR(): +.IR tms_utime , +.IR tms_stime , +.IR tms_cutime , +and +.IR tms_cstime , +respectively. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +\fB$\fP times +\fB0m0.43s 0m1.11s +8m44.18s 1m43.23s\fR +.fi +.SH "RATIONALE" +The +.IR times +special built-in from the Single UNIX Specification is now required +for all conforming shells. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/touch.1p b/man-pages-posix-2013-a/man1p/touch.1p new file mode 100644 index 0000000..a9fca6f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/touch.1p @@ -0,0 +1,646 @@ +'\" et +.TH TOUCH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +touch +\(em change file access and modification times +.SH SYNOPSIS +.LP +.nf +touch \fB[\fR\(miacm\fB] [\fR\(mir \fIref_file\fR|\(mit \fItime\fR|\(mid \fIdate_time\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR touch +utility shall change the last data modification timestamps, the +last data access timestamps, or both. +.P +The time used can be specified by the +.BR \(mit +.IR time +option-argument, the corresponding +.IR time +fields of the file referenced by the +.BR \(mir +.IR ref_file +option-argument, or the +.BR \(mid +.IR date_time +option-argument, as specified in the following sections. If none of +these are specified, +.IR touch +shall use the current time. +.P +For each +.IR file +operand, +.IR touch +shall perform actions equivalent to the following functions defined in +the System Interfaces volume of POSIX.1\(hy2008: +.IP " 1." 4 +If +.IR file +does not exist: +.RS 4 +.IP " a." 4 +The +\fIcreat\fR() +function is called with the following arguments: +.RS 4 +.IP -- 4 +The +.IR file +operand is used as the +.IR path +argument. +.IP -- 4 +The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, +S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH is used as the +.IR mode +argument. +.RE +.IP " b." 4 +The +\fIfutimens\fR() +function is called with the following arguments: +.RS 4 +.IP -- 4 +The file descriptor opened in step 1a. +.IP -- 4 +The access time and the modification time, set as described in the +OPTIONS section, are used as the first and second elements of the +.IR times +array argument, respectively. +.RE +.RE +.IP " 2." 4 +If +.IR file +exists, the +\fIutimensat\fR() +function is called with the following arguments: +.RS 4 +.IP " a." 4 +The AT_FDCWD special value is used as the +.IR fd +argument. +.IP " b." 4 +The +.IR file +operand is used as the +.IR path +argument. +.IP " c." 4 +The access time and the modification time, set as described in the +OPTIONS section, are used as the first and second elements of the +.IR times +array argument, respectively. +.IP " d." 4 +The +.IR flag +argument is set to zero. +.RE +.SH OPTIONS +The +.IR touch +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Change the access time of +.IR file . +Do not change the modification time unless +.BR \(mim +is also specified. +.IP "\fB\(mic\fP" 10 +Do not create a specified +.IR file +if it does not exist. Do not write any diagnostic messages concerning +this condition. +.IP "\fB\(mid\ \fIdate_time\fR" 10 +Use the specified +.IR date_time +instead of the current time. The option-argument shall be a string of +the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIYYYY\fR\(mi\fIMM\fR\(mi\fIDD\fRT\fIhh\fR:\fImm\fR:\fISS\fB[\fR.\fIfrac\fB][\fItz\fB]\fR +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +\fIYYYY\fR\(mi\fIMM\fR\(mi\fIDD\fRT\fIhh\fR:\fImm\fR:\fISS\fB[\fR,\fIfrac\fB][\fItz\fB]\fR +.fi \fR +.P +.RE +.P +where: +.IP " *" 4 +.IR YYYY +are at least four decimal digits giving the year. +.IP " *" 4 +.IR MM , +.IR DD , +.IR hh , +.IR mm , +and +.IR SS +are as with +.BR \(mit +.IR time . +.IP " *" 4 +\fRT\fR is the time designator, and can be replaced by a single +. +.IP " *" 4 +\fR[.\fIfrac\fR]\fR and \fR[,\fIfrac\fR]\fR are either empty, or a + +(\c +.BR '.' ) +or a + +(\c +.BR ',' ) +respectively, followed by one or more decimal digits, specifying +a fractional second. +.IP " *" 4 +\fR[\fItz\fR]\fR is either empty, signifying local time, or the letter +.BR 'Z' , +signifying UTC. If \fR[\fItz\fR]\fR is empty, the resulting time shall +be affected by the value of the +.IR TZ +environment variable. +.P +If the resulting time precedes the Epoch, the behavior is +implementation-defined. If the time cannot be represented as the file's +timestamp, +.IR touch +shall exit immediately with an error status. +.RE +.IP "\fB\(mim\fP" 10 +Change the modification time of +.IR file . +Do not change the access time unless +.BR \(mia +is also specified. +.IP "\fB\(mir\ \fIref_file\fR" 10 +Use the corresponding time of the file named by the pathname +.IR ref_file +instead of the current time. +.IP "\fB\(mit\ \fItime\fR" 10 +Use the specified +.IR time +instead of the current time. The option-argument shall be a decimal +number of the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[[\fICC\fB]\fIYY\fB]\fIMMDDhhmm\fB[\fR.\fISS\fB]\fR +.fi \fR +.P +.RE +.P +where each two digits represents the following: +.IP "\fIMM\fR" 8 +The month of the year [01,12]. +.IP "\fIDD\fR" 8 +The day of the month [01,31]. +.IP "\fIhh\fR" 8 +The hour of the day [00,23]. +.IP "\fImm\fR" 8 +The minute of the hour [00,59]. +.IP "\fICC\fR" 8 +The first two digits of the year (the century). +.IP "\fIYY\fR" 8 +The second two digits of the year. +.IP "\fISS\fR" 8 +The second of the minute [00,60]. +.P +Both +.IR CC +and +.IR YY +shall be optional. If neither is given, the current year shall be +assumed. If +.IR YY +is specified, but +.IR CC +is not, +.IR CC +shall be derived as follows: +.TS +center tab(@) box; +cB | cB +c | n. +If \fIYY\fP is:@\fICC\fP becomes: +_ +[69,99]@19 +[00,68]@20 +.TE +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.P +The resulting time shall be affected by the value of the +.IR TZ +environment variable. If the resulting time value precedes the Epoch, +the behavior is implementation-defined. If the time is out of range for +the file's timestamp, +.IR touch +shall exit immediately with an error status. The range of valid times +past the Epoch is implementation-defined, but it shall extend to at +least the time 0 hours, 0 minutes, 0 seconds, January 1, 2038, +Coordinated Universal Time. Some implementations may not be able to +represent dates beyond January 18, 2038, because they use +.BR "signed int" +as a time holder. +.P +The range for +.IR SS +is [00,60] rather than [00,59] because of leap seconds. If +.IR SS +is 60, and the resulting time, as affected by the +.IR TZ +environment variable, does not refer to a leap second, the resulting +time shall be one second after a time where +.IR SS +is 59. If +.IR SS +is not given a value, it is assumed to be zero. +.RE +.P +If neither the +.BR \(mia +nor +.BR \(mim +options were specified, +.IR touch +shall behave as if both the +.BR \(mia +and +.BR \(mim +options were specified. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file whose times shall be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR touch : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone to be used for interpreting the +.IR time +option-argument. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The interpretation of time is taken to be +.IR "seconds since the Epoch" +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch"). +It should be noted that implementations conforming to the System Interfaces volume of POSIX.1\(hy2008 do +not take leap seconds into account when computing seconds since the +Epoch. When +.IR SS =60 +is used, the resulting time always refers to 1 plus +.IR "seconds since the Epoch" +for a time when +.IR SS =59. +.P +Although the +.BR \(mit +.IR time +option-argument specifies values in 1969, the access time and +modification time fields are defined in terms of seconds since the +Epoch (00:00:00 on 1 January 1970 UTC). Therefore, depending on the +value of +.IR TZ +when +.IR touch +is run, there is never more than a few valid hours in 1969 and there +need not be any valid times in 1969. +.P +One ambiguous situation occurs if +.BR \(mit +.IR time +is not specified, +.BR \(mir +.IR ref_file +is not specified, and the first operand is an eight or ten-digit +decimal number. A portable script can avoid this problem by using: +.sp +.RS 4 +.nf +\fB +touch \(mi\|\(mi file +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +touch ./file +.fi \fR +.P +.RE +.P +in this case. +.P +If the +.IR T +time designator is replaced by a + +for the +.BR \(mid +.IR date_time +option-argument, the + +must be quoted to prevent the shell from splitting the argument. +.SH EXAMPLES +Create or update a file called +.BR dwc ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time: +.sp +.RS 4 +.nf +\fB +touch \(mid 2007-11-12T10:15:30 dwc +.fi \fR +.P +.RE +.P +Create or update a file called +.BR nick ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 UTC: +.sp +.RS 4 +.nf +\fB +touch \(mid 2007-11-12T10:15:30Z nick +.fi \fR +.P +.RE +.P +Create or update a file called +.BR gwc ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time with +a fractional second timestamp of .002 seconds: +.sp +.RS 4 +.nf +\fB +touch \(mid 2007-11-12T10:15:30,002 gwc +.fi \fR +.P +.RE +.P +Create or update a file called +.BR ajosey ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 UTC with a +fractional second timestamp of .002 seconds: +.sp +.RS 4 +.nf +\fB +touch \(mid "2007-11-12 10:15:30.002Z" ajosey +.fi \fR +.P +.RE +.P +Create or update a file called +.BR cathy ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:00 local time: +.sp +.RS 4 +.nf +\fB +touch \(mit 200711121015 cathy +.fi \fR +.P +.RE +.P +Create or update a file called +.BR drepper ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time: +.sp +.RS 4 +.nf +\fB +touch \(mit 200711121015.30 drepper +.fi \fR +.P +.RE +.P +Create or update a file called +.BR ebb9 ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time: +.sp +.RS 4 +.nf +\fB +touch \(mit 0711121015.30 ebb9 +.fi \fR +.P +.RE +.P +Create or update a file called +.BR eggert ; +the resulting file has the last data access timestamp set to the +corresponding time of the file named +.BR mark +instead of the current time. If the file exists, the last data +modification time is not changed: +.sp +.RS 4 +.nf +\fB +touch \(mia \(mir mark eggert +.fi \fR +.P +.RE +.SH RATIONALE +The functionality of +.IR touch +is described almost entirely through references to functions in +the System Interfaces volume of POSIX.1\(hy2008. In this way, there is no duplication of effort required for +describing such side-effects as the relationship of user IDs to the +user database, permissions, and so on. +.P +There are some significant differences between the +.IR touch +utility in this volume of POSIX.1\(hy2008 and those in System V and BSD systems. They are +upwards-compatible for historical applications from both +implementations: +.IP " 1." 4 +In System V, an ambiguity exists when a pathname that is a decimal +number leads the operands; it is treated as a time value. In BSD, no +.IR time +value is allowed; files may only be +.IR touch ed +to the current time. The +.BR \(mit +.IR time +construct solves these problems for future conforming applications (note +that the +.BR \(mit +option is not historical practice). +.IP " 2." 4 +The inclusion of the century digits, +.IR CC , +is also new. Note that a ten-digit +.IR time +value is treated as if +.IR YY , +and not +.IR CC , +were specified. The caveat about the range of dates following the +Epoch was included as recognition that some implementations are not +able to represent dates beyond 18 January 2038 because they use +.BR "signed int" +as a time holder. +.P +The +.BR \(mir +option was added because several comments requested this capability. +This option was named +.BR \(mif +in an early proposal, but was changed because the +.BR \(mif +option is used in the BSD version of +.IR touch +with a different meaning. +.P +At least one historical implementation of +.IR touch +incremented the exit code if +.BR \(mic +was specified and the file did not exist. This volume of POSIX.1\(hy2008 requires exit status +zero if no errors occur. +.P +In previous version of the standard, if at least two operands are +specified, and the first operand is an eight or ten-digit decimal +integer, the first operand was assumed to be a +.IR date_time +operand. This usage was removed in this version of the standard since +it had been marked obsolescent previously. +.P +The +.BR \(mid +.IR date_time +format is an ISO\ 8601:\|2004 standard complete representation of date and time extended +format with an optional decimal point or + +followed by a string of digits following the seconds portion to specify +fractions of a second. It is not necessary to recognize +.BR \(dq[+/-]hh:mm\(dq +and +.BR \(dq[+/-]hh\(dq +to specify timezones other than local time and UTC. The +.IR T +time designator in the ISO\ 8601:\|2004 standard extended format may be replaced by +. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdate\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/tput.1p b/man-pages-posix-2013-a/man1p/tput.1p new file mode 100644 index 0000000..0ec6ad2 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/tput.1p @@ -0,0 +1,222 @@ +'\" et +.TH TPUT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tput +\(em change terminal characteristics +.SH SYNOPSIS +.LP +.nf +tput \fB[\fR\(miT \fItype\fB] \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR tput +utility shall display terminal-dependent information. The manner in +which this information is retrieved is unspecified. The information +displayed shall clear the terminal screen, initialize the user's +terminal, or reset the user's terminal, depending on the operand +given. The exact consequences of displaying this information are +unspecified. +.SH OPTIONS +The +.IR tput +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miT\ \fItype\fR" 10 +Indicate the type of terminal. If this option is not supplied and the +.IR TERM +variable is unset or null, an unspecified default terminal type shall +be used. The setting of +.IR type +shall take precedence over the value in +.IR TERM . +.SH OPERANDS +The following strings shall be supported as operands by the +implementation in the POSIX locale: +.IP "\fBclear\fR" 10 +Display the clear-screen sequence. +.IP "\fBinit\fR" 10 +Display the sequence that initializes the user's terminal in an +implementation-defined manner. +.IP "\fBreset\fR" 10 +Display the sequence that resets the user's terminal in an +implementation-defined manner. +.P +If a terminal does not support any of the operations described by these +operands, this shall not be considered an error condition. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tput : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITERM\fP" 10 +Determine the terminal type. If this variable is unset or null, and if +the +.BR \(miT +option is not specified, an unspecified default terminal type shall be +used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If standard output is a terminal device, it may be used for writing the +appropriate sequence to clear the screen or reset or initialize the +terminal. If standard output is not a terminal device, undefined +results occur. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The requested string was written successfully. +.IP "\01" 6 +Unspecified. +.IP "\02" 6 +Usage error. +.IP "\03" 6 +No information is available about the specified terminal type. +.IP "\04" 6 +The specified operand is invalid. +.IP >4 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If one of the operands is not available for the terminal, +.IR tput +continues processing the remaining operands. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The difference between resetting and initializing a terminal is left +unspecified, as they vary greatly based on hardware types. In general, +resetting is a more severe action. +.P +Some terminals use control characters to perform the stated functions, +and on such terminals it might make sense to use +.IR tput +to store the initialization strings in a file or environment variable +for later use. However, because other terminals might rely on system +calls to do this work, the standard output cannot be used in a portable +manner, such as the following non-portable constructs: +.sp +.RS 4 +.nf +\fB +ClearVar=`tput clear` +tput reset | mailx \(mis "Wake Up" ddg +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +Initialize the terminal according to the type of terminal in the +environmental variable +.IR TERM . +This command can be included in a +.BR .profile +file. +.RS 4 +.sp +.RS 4 +.nf +\fB +tput init +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Reset a 450 terminal. +.RS 4 +.sp +.RS 4 +.nf +\fB +tput \(miT 450 reset +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The list of operands was reduced to a minimum for the following +reasons: +.IP " *" 4 +The only features chosen were those that were likely to be used by +human users interacting with a terminal. +.IP " *" 4 +Specifying the full +.IR terminfo +set was not considered desirable, but the standard developers did not +want to select among operands. +.IP " *" 4 +This volume of POSIX.1\(hy2008 does not attempt to provide applications with sophisticated +terminal handling capabilities, as that falls outside of its assigned +scope and intersects with the responsibilities of other standards +bodies. +.P +The difference between resetting and initializing a terminal is left +unspecified as this varies greatly based on hardware types. In +general, resetting is a more severe action. +.P +The exit status of 1 is historically reserved for finding out if a +Boolean operand is not set. Although the operands were reduced to a +minimum, the exit status of 1 should still be reserved for the Boolean +operands, for those sites that wish to support them. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstty\fR\^", +.IR "\fItabs\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/tr.1p b/man-pages-posix-2013-a/man1p/tr.1p new file mode 100644 index 0000000..8706a0e --- /dev/null +++ b/man-pages-posix-2013-a/man1p/tr.1p @@ -0,0 +1,699 @@ +'\" et +.TH TR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tr +\(em translate characters +.SH SYNOPSIS +.LP +.nf +tr \fB[\fR\(mic|\(miC\fB] [\fR\(mis\fB] \fIstring1 string2\fR +.P +tr \(mis \fB[\fR\(mic|\(miC\fB] \fIstring1\fR +.P +tr \(mid \fB[\fR\(mic|\(miC\fB] \fIstring1\fR +.P +tr \(mids \fB[\fR\(mic|\(miC\fB] \fIstring1 string2\fR +.fi +.SH DESCRIPTION +The +.IR tr +utility shall copy the standard input to the standard output with +substitution or deletion of selected characters. The options specified +and the +.IR string1 +and +.IR string2 +operands shall control translations that occur while copying characters +and single-character collating elements. +.SH OPTIONS +The +.IR tr +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Complement the set of values specified by +.IR string1 . +See the EXTENDED DESCRIPTION section. +.IP "\fB\(miC\fP" 10 +Complement the set of characters specified by +.IR string1 . +See the EXTENDED DESCRIPTION section. +.IP "\fB\(mid\fP" 10 +Delete all occurrences of input characters that are specified by +.IR string1 . +.IP "\fB\(mis\fP" 10 +Replace instances of repeated characters with a single character, as +described in the EXTENDED DESCRIPTION section. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIstring1\fR,\ \fIstring2\fR" 10 +.br +Translation control strings. Each string shall represent a set of +characters to be converted into an array of characters used for the +translation. For a detailed description of how the strings are +interpreted, see the EXTENDED DESCRIPTION section. +.SH STDIN +The standard input can be any type of file. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tr : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of range expressions and +equivalence classes. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments) and the behavior of character +classes. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR tr +output shall be identical to the input, with the exception of the +specified transformations. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The operands +.IR string1 +and +.IR string2 +(if specified) define two arrays of characters. The constructs in the +following list can be used to specify characters or single-character +collating elements. If any of the constructs result in multi-character +collating elements, +.IR tr +shall exclude, without a diagnostic, those multi-character elements +from the resulting array. +.IP "\fIcharacter\fR" 10 +Any character not described by one of the conventions below shall +represent itself. +.IP "\e\fIoctal\fR" 10 +Octal sequences can be used to represent characters with specific coded +values. An octal sequence shall consist of a + +followed by the longest sequence of one, two, or three-octal-digit +characters (01234567). The sequence shall cause the value whose encoding +is represented by the one, two, or three-digit octal integer to be placed +into the array. Multi-byte characters require multiple, concatenated +escape sequences of this type, including the leading + +for each byte. +.IP "\e\fIcharacter\fR" 10 +The +-escape +sequences in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +shall be supported. The results of using any other character, other +than an octal digit, following the + +are unspecified. Also, if there is no character following the +, +the results are unspecified. +.IP "\fIc\fR\(mi\fIc\fR" 10 +In the POSIX locale, this construct shall represent the range of +collating elements between the range endpoints (as long as neither +endpoint is an octal sequence of the form \e\fIoctal\fP), inclusive, as +defined by the collation sequence. The characters or collating elements +in the range shall be placed in the array in ascending collation +sequence. If the second endpoint precedes the starting endpoint in the +collation sequence, it is unspecified whether the range of collating +elements is empty, or this construct is treated as invalid. In locales +other than the POSIX locale, this construct has unspecified behavior. +.RS 10 +.P +If either or both of the range endpoints are octal sequences of the +form \e\fIoctal\fP, this shall represent the range of specific coded +values between the two range endpoints, inclusive. +.RE +.IP "[:\fIclass\fR:]" 10 +Represents all characters belonging to the defined character class, as +defined by the current setting of the +.IR LC_CTYPE +locale category. The following character class names shall be accepted +when specified in +.IR string1 : +.TS +tab(@); +lB lB lB lB lB lB. +alnum@blank@digit@lower@punct@upper +alpha@cntrl@graph@print@space@xdigit +.TE +.RS 10 +.P +In addition, character class expressions of the form [:\c +.IR name :] +shall be recognized in those locales where the +.IR name +keyword has been given a +.BR charclass +definition in the +.IR LC_CTYPE +category. +.P +When both the +.BR \(mid +and +.BR \(mis +options are specified, any of the character class names shall be +accepted in +.IR string2 . +Otherwise, only character class names +.BR lower +or +.BR upper +are valid in +.IR string2 +and then only if the corresponding character class (\c +.BR upper +and +.BR lower , +respectively) is specified in the same relative position in +.IR string1 . +Such a specification shall be interpreted as a request for case +conversion. When [:\c +.IR lower :] +appears in +.IR string1 +and [:\c +.IR upper :] +appears in +.IR string2 , +the arrays shall contain the characters from the +.BR toupper +mapping in the +.IR LC_CTYPE +category of the current locale. When [:\c +.IR upper :] +appears in +.IR string1 +and [:\c +.IR lower :] +appears in +.IR string2 , +the arrays shall contain the characters from the +.BR tolower +mapping in the +.IR LC_CTYPE +category of the current locale. The first character from each mapping +pair shall be in the array for +.IR string1 +and the second character from each mapping pair shall be in the array +for +.IR string2 +in the same relative position. +.P +Except for case conversion, the characters specified by a character +class expression shall be placed in the array in an unspecified order. +.P +If the name specified for +.IR class +does not define a valid character class in the current locale, the +behavior is undefined. +.RE +.IP "[=\fIequiv\fR=]" 10 +Represents all characters or collating elements belonging to the same +equivalence class as +.IR equiv , +as defined by the current setting of the +.IR LC_COLLATE +locale category. An equivalence class expression shall be allowed only +in +.IR string1 , +or in +.IR string2 +when it is being used by the combined +.BR \(mid +and +.BR \(mis +options. The characters belonging to the equivalence class shall be +placed in the array in an unspecified order. +.IP "[\fIx\fR*\fIn\fR]" 10 +Represents +.IR n +repeated occurrences of the character +.IR x . +Because this expression is used to map multiple characters to one, it +is only valid when it occurs in +.IR string2 . +If +.IR n +is omitted or is zero, it shall be interpreted as large enough to +extend the +.IR string2 -based +sequence to the length of the +.IR string1 -based +sequence. If +.IR n +has a leading zero, it shall be interpreted as an octal value. +Otherwise, it shall be interpreted as a decimal value. +.P +When the +.BR \(mid +option is not specified: +.IP " *" 4 +If +.IR string2 +is present, each input character found in the array specified by +.IR string1 +shall be replaced by the character in the same relative position in the +array specified by +.IR string2 . +If the array specified by +.IR string2 +is shorter that the one specified by +.IR string1 , +or if a character occurs more than once in +.IR string1 , +the results are unspecified. +.IP " *" 4 +If the +.BR \(miC +option is specified, the complements of the characters specified by +.IR string1 +(the set of all characters in the current character set, as defined by +the current setting of +.IR LC_CTYPE , +except for those actually specified in the +.IR string1 +operand) shall be placed in the array in ascending collation sequence, +as defined by the current setting of +.IR LC_COLLATE . +.IP " *" 4 +If the +.BR \(mic +option is specified, the complement of the values specified by +.IR string1 +shall be placed in the array in ascending order by binary value. +.IP " *" 4 +Because the order in which characters specified by character class +expressions or equivalence class expressions is undefined, such +expressions should only be used if the intent is to map several +characters into one. An exception is case conversion, as described +previously. +.P +When the +.BR \(mid +option is specified: +.IP " *" 4 +Input characters found in the array specified by +.IR string1 +shall be deleted. +.IP " *" 4 +When the +.BR \(miC +option is specified with +.BR \(mid , +all characters except those specified by +.IR string1 +shall be deleted. The contents of +.IR string2 +are ignored, unless the +.BR \(mis +option is also specified. +.IP " *" 4 +When the +.BR \(mic +option is specified with +.BR \(mid , +all values except those specified by +.IR string1 +shall be deleted. The contents of +.IR string2 +shall be ignored, unless the +.BR \(mis +option is also specified. +.IP " *" 4 +The same string cannot be used for both the +.BR \(mid +and the +.BR \(mis +option; when both options are specified, both +.IR string1 +(used for deletion) and +.IR string2 +(used for squeezing) shall be required. +.P +When the +.BR \(mis +option is specified, after any deletions or translations have taken +place, repeated sequences of the same character shall be replaced by +one occurrence of the same character, if the character is found in the +array specified by the last operand. If the last operand contains a +character class, such as the following example: +.sp +.RS 4 +.nf +\fB +tr \(mis '[:space:]' +.fi \fR +.P +.RE +.P +the last operand's array shall contain all of the characters in that +character class. However, in a case conversion, as described +previously, such as: +.sp +.RS 4 +.nf +\fB +tr \(mis '[:upper:]' '[:lower:]' +.fi \fR +.P +.RE +.P +the last operand's array shall contain only those characters defined as +the second characters in each of the +.BR toupper +or +.BR tolower +character pairs, as appropriate. +.P +An empty string used for +.IR string1 +or +.IR string2 +produces undefined results. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input was processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If necessary, +.IR string1 +and +.IR string2 +can be quoted to avoid pattern matching by the shell. +.P +If an ordinary digit (representing itself) is to follow an octal +sequence, the octal sequence must use the full three digits to avoid +ambiguity. +.P +When +.IR string2 +is shorter than +.IR string1 , +a difference results between historical System\ V and BSD systems. A +BSD system pads +.IR string2 +with the last character found in +.IR string2 . +Thus, it is possible to do the following: +.sp +.RS 4 +.nf +\fB +tr 0123456789 d +.fi \fR +.P +.RE +.P +which would translate all digits to the letter +.BR 'd' . +Since this area is specifically unspecified in this volume of POSIX.1\(hy2008, both the BSD and +System\ V behaviors are allowed, but a conforming application cannot rely +on the BSD behavior. It would have to code the example in the +following way: +.sp +.RS 4 +.nf +\fB +tr 0123456789 '[d*]' +.fi \fR +.P +.RE +.P +It should be noted that, despite similarities in appearance, the string +operands used by +.IR tr +are not regular expressions. +.P +Unlike some historical implementations, this definition of the +.IR tr +utility correctly processes NUL characters in its input stream. NUL +characters can be stripped by using: +.sp +.RS 4 +.nf +\fB +tr \(mid '\e000' +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +The following example creates a list of all words in +.BR file1 +one per line in +.BR file2 , +where a word is taken to be a maximal string of letters. +.RS 4 +.sp +.RS 4 +.nf +\fB +tr \(mics "[:alpha:]" "[\en*]" file2 +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The next example translates all lowercase characters in +.BR file1 +to uppercase and writes the results to standard output. +.RS 4 +.sp +.RS 4 +.nf +\fB +tr "[:lower:]" "[:upper:]" file2 +.fi \fR +.P +.RE +.RE +.SH RATIONALE +In some early proposals, an explicit option +.BR \(min +was added to disable the historical behavior of stripping NUL +characters from the input. It was considered that automatically +stripping NUL characters from the input was not correct functionality. +However, the removal of +.BR \(min +in a later proposal does not remove the requirement that +.IR tr +correctly process NUL characters in its input stream. NUL characters +can be stripped by using +.IR tr +.BR \(mid +\&'\e000'. +.P +Historical implementations of +.IR tr +differ widely in syntax and behavior. For example, the BSD version has +not needed the bracket characters for the repetition sequence. The +.IR tr +utility syntax is based more closely on the System V and XPG3 model +while attempting to accommodate historical BSD implementations. In the +case of the short +.IR string2 +padding, the decision was to unspecify the behavior and preserve System +V and XPG3 scripts, which might find difficulty with the BSD method. +The assumption was made that BSD users of +.IR tr +have to make accommodations to meet the syntax defined here. Since it +is possible to use the repetition sequence to duplicate the desired +behavior, whereas there is no simple way to achieve the System V +method, this was the correct, if not desirable, approach. +.P +The use of octal values to specify control characters, while having +historical precedents, is not portable. The introduction of escape +sequences for control characters should provide the necessary +portability. It is recognized that this may cause some historical +scripts to break. +.P +An early proposal included support for multi-character collating elements. +It was pointed out that, while +.IR tr +does employ some syntactical elements from REs, the aim of +.IR tr +is quite different; ranges, for example, do not have a similar meaning +(``any of the chars in the range matches'', \fIversus\fP ``translate +each character in the range to the output counterpart''). As a result, +the previously included support for multi-character collating elements +has been removed. What remains are ranges in current collation order +(to support, for example, accented characters), character classes, and +equivalence classes. +.P +In XPG3 the [:\c +.IR class :] +and [=\c +.IR equiv =] +conventions are shown with double brackets, as in RE syntax. However, +.IR tr +does not implement RE principles; it just borrows part of the syntax. +Consequently, [:\c +.IR class :] +and [=\c +.IR equiv =] +should be regarded as syntactical elements on a par with [\c +.IR x *\c +.IR n ], +which is not an RE bracket expression. +.P +The standard developers will consider changes to +.IR tr +that allow it to translate characters between different character +encodings, or they will consider providing a new utility to accomplish +this. +.P +On historical System V systems, a range expression requires enclosing +square-brackets, such as: +.sp +.RS 4 +.nf +\fB +tr '[a-z]' '[A-Z]' +.fi \fR +.P +.RE +.P +However, BSD-based systems did not require the brackets, and this +convention is used here to avoid breaking large numbers of BSD scripts: +.sp +.RS 4 +.nf +\fB +tr a-z A-Z +.fi \fR +.P +.RE +.P +The preceding System V script will continue to work because the +brackets, treated as regular characters, are translated to themselves. +However, any System V script that relied on +.BR \(dqa\(hyz\(dq +representing the three characters +.BR 'a' , +.BR '\(mi' , +and +.BR 'z' +have to be rewritten as +.BR \(dqaz\(mi\(dq . +.P +The ISO\ POSIX\(hy2:\|1993 standard had a +.BR \(mic +option that behaved similarly to the +.BR \(miC +option, but did not supply functionality equivalent to the +.BR \(mic +option specified in POSIX.1\(hy2008. This meant that historical practice of being +able to specify +.IR tr +.BR \(micd \e000\(mi\e177 +(which would delete all bytes with the top bit set) would have no +effect because, in the C locale, bytes with the values octal 200 to +octal 377 are not characters. +.P +The earlier version also said that octal sequences referred to +collating elements and could be placed adjacent to each other to +specify multi-byte characters. However, it was noted that this caused +ambiguities because +.IR tr +would not be able to tell whether adjacent octal sequences were +intending to specify multi-byte characters or multiple single byte +characters. POSIX.1\(hy2008 specifies that octal sequences always refer to single +byte binary values when used to specify an endpoint of a range of +collating elements. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/trap.1p b/man-pages-posix-2013-a/man1p/trap.1p new file mode 100644 index 0000000..264ce1f --- /dev/null +++ b/man-pages-posix-2013-a/man1p/trap.1p @@ -0,0 +1,362 @@ +'\" et +.TH TRAP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +trap +\(em trap signals +.SH SYNOPSIS +.LP +.nf +trap \fIn \fB[\fIcondition\fR...\fB]\fR +trap \fB[\fIaction condition\fR...\fB]\fR +.fi +.SH DESCRIPTION +If the first operand is an unsigned decimal integer, the shell shall +treat all operands as conditions, and shall reset each condition to +the default value. Otherwise, if there are operands, the first is +treated as an action and the remaining as conditions. +.P +If +.IR action +is +.BR '\(mi' , +the shell shall reset each +.IR condition +to the default value. If +.IR action +is null (\c +.BR \(dq\^\(dq ), +the shell shall ignore each specified +.IR condition +if it arises. Otherwise, the argument +.IR action +shall be read and executed by the shell when one of the corresponding +conditions arises. The action of +.IR trap +shall override a previous action (either default action or one +explicitly set). The value of +.BR \(dq$?\(dq +after the +.IR trap +action completes shall be the value it had before +.IR trap +was invoked. +.P +The condition can be EXIT, 0 (equivalent to EXIT), or a signal +specified using a symbolic name, without the SIG prefix, as listed in +the tables of signal names in the +.IR +header defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 13" ", " "Headers"; +for example, HUP, INT, QUIT, TERM. Implementations may permit names with +the SIG prefix or ignore case in signal names as an extension. Setting +a trap for SIGKILL or SIGSTOP produces undefined results. +.P +The environment in which the shell executes a +.IR trap +on EXIT shall be identical to the environment immediately after the +last command executed before the +.IR trap +on EXIT was taken. +.P +Each time +.IR trap +is invoked, the +.IR action +argument shall be processed in a manner equivalent to: +.sp +.RS 4 +.nf +\fB +eval \fIaction\fR +.fi \fR +.P +.RE +.P +Signals that were ignored on entry to a non-interactive shell cannot be +trapped or reset, although no error need be reported when attempting to +do so. An interactive shell may reset or catch signals ignored on +entry. Traps shall remain in place for a given shell until explicitly +changed with another +.IR trap +command. +.P +When a subshell is entered, traps that are not being ignored shall be +set to the default actions, except in the case of a command substitution +containing only a single +.IR trap +command, when the traps need not be altered. Implementations may check +for this case using only lexical analysis; for example, if +.IR `trap` +and +.IR "$( trap -- )" +do not alter the traps in the subshell, cases such as assigning +.IR var=trap +and then using +.IR $($var) +may still alter them. This does not imply that the +.IR trap +command cannot be used within the subshell to set new traps. +.P +The +.IR trap +command with no operands shall write to standard output a list of commands +associated with each condition. If the command is executed in a subshell, +the implementation does not perform the optional check described above +for a command substitution containing only a single +.IR trap +command, and no +.IR trap +commands with operands have been executed since entry to the subshell, +the list shall contain the commands that were associated with each +condition immediately before the subshell environment was entered. +Otherwise, the list shall contain the commands currently associated with +each condition. The format shall be: +.sp +.RS 4 +.nf +\fB +"trap \(mi\|\(mi %s %s ...\en", <\fIaction\fR>, <\fIcondition\fR> ... +.fi \fR +.P +.RE +.P +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as commands that +achieve the same trapping results. For example: +.sp +.RS 4 +.nf +\fB +save_traps=$(trap) +\&... +eval "$save_traps" +.fi \fR +.P +.RE +.P +XSI-conformant systems also allow numeric signal numbers for the +conditions corresponding to the following signal names: +.IP 1 6 +SIGHUP +.IP 2 6 +SIGINT +.IP 3 6 +SIGQUIT +.IP 6 6 +SIGABRT +.IP 9 6 +SIGKILL +.IP 14 6 +SIGALRM +.IP 15 6 +SIGTERM +.P +The +.IR trap +special built-in shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If the trap name +or number +is invalid, a non-zero exit status shall be returned; otherwise, zero +shall be returned. For both interactive and non-interactive shells, +invalid signal names +or numbers +shall not be considered a syntax error and do not cause the shell to +abort. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Write out a list of all traps and actions: +.sp +.RS 4 +.nf +\fB +trap +.fi \fR +.P +.RE +.P +Set a trap so the +.IR logout +utility in the directory referred to by the +.IR HOME +environment variable executes when the shell terminates: +.sp +.RS 4 +.nf +\fB +trap '"$HOME"/logout' EXIT +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +trap '"$HOME"/logout' 0 +.fi \fR +.P +.RE +.P +Unset traps on INT, QUIT, TERM, and EXIT: +.sp +.RS 4 +.nf +\fB +trap \(mi INT QUIT TERM EXIT +.fi \fR +.P +.RE +.SH "RATIONALE" +Implementations may permit lowercase signal names as an extension. +Implementations may also accept the names with the SIG prefix; no known +historical shell does so. The +.IR trap +and +.IR kill +utilities in this volume of POSIX.1\(hy2008 are now consistent in their omission of the SIG +prefix for signal names. Some +.IR kill +implementations do not allow the prefix, and +.IR kill +.BR \(mil +lists the signals without prefixes. +.P +Trapping SIGKILL or SIGSTOP is syntactically accepted by some +historical implementations, but it has no effect. Portable POSIX +applications cannot attempt to trap these signals. +.P +The output format is not historical practice. Since the output of +historical +.IR trap +commands is not portable (because numeric signal values are not +portable) and had to change to become so, an opportunity was taken to +format the output in a way that a shell script could use to save and +then later reuse a trap if it wanted. +.P +The KornShell uses an +.BR ERR +trap that is triggered whenever +.IR set +.BR \(mie +would cause an exit. This is allowable as an extension, but was not +mandated, as other shells have not used it. +.P +The text about the environment for the EXIT trap invalidates the +behavior of some historical versions of interactive shells which, for +example, close the standard input before executing a trap on 0. For +example, in some historical interactive shell sessions the following +trap on 0 would always print +.BR \(dq\(mi\|\(mi\(dq : +.sp +.RS 4 +.nf +\fB +trap 'read foo; echo "\(mi$foo\(mi"' 0 +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +trap 'eval " $cmd"' 0 +.fi \fR +.P +.RE +.P +causes the contents of the shell variable +.IR cmd +to be executed as a command when the shell exits. Using: +.sp +.RS 4 +.nf +\fB +trap '$cmd' 0 +.fi \fR +.P +.RE +.P +does not work correctly if +.IR cmd +contains any special characters such as quoting or redirections. Using: +.sp +.RS 4 +.nf +\fB +trap " $cmd" 0 +.fi \fR +.P +.RE +.P +also works (the leading + +character protects against unlikely cases where +.IR cmd +is a decimal integer or begins with +.BR '\(mi' ), +but it expands the +.IR cmd +variable when the +.IR trap +command is executed, not when the exit action is executed. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/true.1p b/man-pages-posix-2013-a/man1p/true.1p new file mode 100644 index 0000000..99c5fdd --- /dev/null +++ b/man-pages-posix-2013-a/man1p/true.1p @@ -0,0 +1,97 @@ +'\" et +.TH TRUE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +true +\(em return true value +.SH SYNOPSIS +.LP +.nf +true +.fi +.SH DESCRIPTION +The +.IR true +utility shall return with exit code zero. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Not used. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +None. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility is typically used in shell scripts, as shown in the +EXAMPLES section. The special built-in utility +.BR : +is sometimes more efficient than +.IR true . +.SH EXAMPLES +This command is executed forever: +.sp +.RS 4 +.nf +\fB +while true +do + command +done +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR true +utility has been retained in this volume of POSIX.1\(hy2008, even though the shell special +built-in +.BR : +provides similar functionality, because +.IR true +is widely used in historical scripts and is less cryptic to novice +script readers. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9" ", " "Shell Commands", +.IR "\fIfalse\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/tsort.1p b/man-pages-posix-2013-a/man1p/tsort.1p new file mode 100644 index 0000000..a1519f2 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/tsort.1p @@ -0,0 +1,156 @@ +'\" et +.TH TSORT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tsort +\(em topological sort +.SH SYNOPSIS +.LP +.nf +tsort \fB[\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR tsort +utility shall write to standard output a totally ordered list of items +consistent with a partial ordering of items contained in the input. +.P +The application shall ensure that the input consists of pairs of items +(non-empty strings) separated by + +characters. Pairs of different items indicate ordering. Pairs of +identical items indicate presence, but not ordering. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to order. If no +.IR file +operand is given, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operand is specified, and shall be used if the +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tsort : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be a text file consisting of the order list +produced from the partially ordered input. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR LC_COLLATE +variable need not affect the actions of +.IR tsort . +The output ordering is not lexicographic, but depends on the pairs of +items given as input. +.SH EXAMPLES +The command: +.sp +.RS 4 +.nf +\fB +tsort < +.fi \fR +.P +.RE +.P +Otherwise, a message shall be written indicating that standard input is +not connected to a terminal. In the POSIX locale, the +.IR tty +utility shall use the format: +.sp +.RS 4 +.nf +\fB +"not a tty\en" +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Standard input is a terminal. +.IP "\01" 6 +Standard input is not a terminal. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility checks the status of the file open as standard input +against that of an implementation-defined set of files. It is possible +that no match can be found, or that the match found need not be the +same file as that which was opened for standard input (although they +are the same device). +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIisatty\fR\^(\|)", +.IR "\fIttyname\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/type.1p b/man-pages-posix-2013-a/man1p/type.1p new file mode 100644 index 0000000..d1f3d69 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/type.1p @@ -0,0 +1,133 @@ +'\" et +.TH TYPE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +type +\(em write a description of command type +.SH SYNOPSIS +.LP +.nf +type \fIname\fR... +.fi +.SH DESCRIPTION +The +.IR type +utility shall indicate how each argument would be interpreted if used +as a command name. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIname\fR" 10 +A name to be interpreted. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR type : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of +.IR name , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output of +.IR type +contains information about each operand in an unspecified format. The +information provided typically identifies the operand as a shell +built-in, function, alias, or keyword, and where applicable, may +display the operand's pathname. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR type +must be aware of the contents of the current shell execution +environment (such as the lists of commands, functions, and built-ins +processed by +.IR hash ), +it is always provided as a shell regular built-in. If it is called in +a separate utility execution environment, such as one of the +following: +.sp +.RS 4 +.nf +\fB +nohup type writer +find . \(mitype f | xargs type +.fi \fR +.P +.RE +it might not produce accurate results. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcommand\fR\^", +.IR "\fIhash\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/ulimit.1p b/man-pages-posix-2013-a/man1p/ulimit.1p new file mode 100644 index 0000000..f14b213 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/ulimit.1p @@ -0,0 +1,169 @@ +'\" et +.TH ULIMIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ulimit +\(em set or report file size limit +.SH SYNOPSIS +.LP +.nf +ulimit \fB[\fR\(mif\fB] [\fIblocks\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ulimit +utility shall set or report the file-size writing limit imposed on +files written by the shell and its child processes (files of any size +may be read). Only a process with appropriate privileges can increase +the limit. +.SH OPTIONS +The +.IR ulimit +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mif\fP" 10 +Set (or report, if no +.IR blocks +operand is present), the file size limit in blocks. The +.BR \(mif +option shall also be the default case. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIblocks\fR" 10 +The number of 512-byte blocks to use as the new file size limit. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ulimit : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used when no +.IR blocks +operand is present. If the current number of blocks is limited, the +number of blocks in the current limit shall be written in the following +format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fInumber of 512-byte blocks\fR> +.fi \fR +.P +.RE +.P +If there is no current limit on the number of blocks, in the POSIX +locale the following format shall be used: +.sp +.RS 4 +.nf +\fB +"unlimited\en" +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +A request for a higher limit was rejected or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR ulimit +affects the current shell execution environment, it is always provided +as a shell regular built-in. If it is called in a separate utility +execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +nohup ulimit \(mif 10000 +env ulimit 10000 +.fi \fR +.P +.RE +.P +it does not affect the file size limit of the caller's environment. +.P +Once a limit has been decreased by a process, it cannot be increased +(unless appropriate privileges are involved), even back to the original +system limit. +.SH EXAMPLES +Set the file size limit to 51\|200 bytes: +.sp +.RS 4 +.nf +\fB +ulimit \(mif 100 +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIulimit\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/umask.1p b/man-pages-posix-2013-a/man1p/umask.1p new file mode 100644 index 0000000..128c265 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/umask.1p @@ -0,0 +1,372 @@ +'\" et +.TH UMASK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +umask +\(em get or set the file mode creation mask +.SH SYNOPSIS +.LP +.nf +umask \fB[\fR\(miS\fB] [\fImask\fB]\fR +.fi +.SH DESCRIPTION +The +.IR umask +utility shall set the file mode creation mask of the current shell +execution environment (see +.IR "Section 2.12" ", " "Shell Execution Environment") +to the value specified by the +.IR mask +operand. This mask shall affect the initial value of the file +permission bits of subsequently created files. If +.IR umask +is called in a subshell or separate utility execution environment, such +as one of the following: +.sp +.RS 4 +.nf +\fB +(umask 002) +nohup umask ... +find . \(miexec umask ... \e; +.fi \fR +.P +.RE +.P +it shall not affect the file mode creation mask of the caller's +environment. +.P +If the +.IR mask +operand is not specified, the +.IR umask +utility shall write to standard output the value of the +file mode creation mask of the invoking process. +.SH OPTIONS +The +.IR umask +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miS\fP" 10 +Produce symbolic output. +.P +The default output style is unspecified, but shall be recognized on a +subsequent invocation of +.IR umask +on the same system as a +.IR mask +operand to restore the previous file mode creation mask. +.SH OPERANDS +The following operand shall be supported: +.IP "\fImask\fR" 10 +A string specifying the new file mode creation mask. The string is +treated in the same way as the +.IR mode +operand described in the EXTENDED DESCRIPTION section for +.IR chmod . +.RS 10 +.P +For a +.IR symbolic_mode +value, the new value of the file mode creation mask shall be the +logical complement of the file permission bits portion of the file mode +specified by the +.IR symbolic_mode +string. +.P +In a +.IR symbolic_mode +value, the permissions +.IR op +characters +.BR '\(pl' +and +.BR '\(mi' +shall be interpreted relative to the current file mode creation mask; +.BR '\(pl' +shall cause the bits for the indicated permissions to be cleared in the +mask; +.BR '\(mi' +shall cause the bits for the indicated permissions to be set in the +mask. +.P +The interpretation of +.IR mode +values that specify file mode bits other than the file permission bits +is unspecified. +.P +In the octal integer form of +.IR mode , +the specified bits are set in the file mode creation mask. +.P +The file mode creation mask shall be set to the resulting numeric +value. +.P +The default output of a prior invocation of +.IR umask +on the same system with no operand also shall be recognized as a +.IR mask +operand. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR umask : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.IR mask +operand is not specified, the +.IR umask +utility shall write a message to standard output that can later be used +as a +.IR umask +.IR mask +operand. +.P +If +.BR \(miS +is specified, the message shall be in the following format: +.sp +.RS 4 +.nf +\fB +"u=%s,g=%s,o=%s\en", <\fIowner permissions\fR>, <\fIgroup permissions\fR>, + <\fIother permissions\fR> +.fi \fR +.P +.RE +.P +where the three values shall be combinations of letters from the set +{\c +.IR r , +.IR w , +.IR x }; +the presence of a letter shall indicate that the corresponding bit is +clear in the file mode creation mask. +.P +If a +.IR mask +operand is specified, there shall be no output written to standard +output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The file mode creation mask was successfully changed, or no +.IR mask +operand was supplied. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR umask +affects the current shell execution environment, it is generally +provided as a shell regular built-in. +.P +In contrast to the negative permission logic provided by the file mode +creation mask and the octal number form of the +.IR mask +argument, the symbolic form of the +.IR mask +argument specifies those permissions that are left alone. +.SH EXAMPLES +Either of the commands: +.sp +.RS 4 +.nf +\fB +umask a=rx,ug+w +.P +umask 002 +.fi \fR +.P +.RE +.P +sets the mode mask so that subsequently created files have their +S_IWOTH bit cleared. +.P +After setting the mode mask with either of the above commands, the +.IR umask +command can be used to write out the current value of the mode mask: +.sp +.RS 4 +.nf +\fB +\fB$ \fRumask +\fB0002\fR +.fi \fR +.P +.RE +.P +(The output format is unspecified, but historical implementations use +the octal integer mode format.) +.sp +.RS 4 +.nf +\fB +\fB$ \fRumask \(miS +\fBu=rwx,g=rwx,o=rx\fR +.fi \fR +.P +.RE +.P +Either of these outputs can be used as the mask operand to a subsequent +invocation of the +.IR umask +utility. +.P +Assuming the mode mask is set as above, the command: +.sp +.RS 4 +.nf +\fB +umask g\(miw +.fi \fR +.P +.RE +.P +sets the mode mask so that subsequently created files have their +S_IWGRP and S_IWOTH bits cleared. +.P +The command: +.sp +.RS 4 +.nf +\fB +umask \(mi\|\(mi \(miw +.fi \fR +.P +.RE +.P +sets the mode mask so that subsequently created files have all their +write bits cleared. Note that +.IR mask +operands +.BR \(mir , +.BR \(miw , +.BR \(mix +or anything beginning with a +, +must be preceded by +.BR \(dq\(mi\|\(mi\(dq +to keep it from being interpreted as an option. +.SH RATIONALE +Since +.IR umask +affects the current shell execution environment, +it is generally provided as a shell regular built-in. If it is called +in a subshell or separate utility execution environment, such as one of +the following: +.sp +.RS 4 +.nf +\fB +(umask 002) +nohup umask ... +find . \(miexec umask ... \e; +.fi \fR +.P +.RE +.P +it does not affect the file mode creation mask of the environment of +the caller. +.P +The description of the historical utility was modified to allow it to +use the symbolic modes of +.IR chmod . +The +.BR \(mis +option used in early proposals was changed to +.BR \(miS +because +.BR \(mis +could be confused with a +.IR symbolic_mode +form of mask referring to the S_ISUID and S_ISGID bits. +.P +The default output style is unspecified to permit implementors to +provide migration to the new symbolic style at the time most +appropriate to their users. A +.BR \(mio +flag to force octal mode output was omitted because the octal mode may +not be sufficient to specify all of the information that may be present +in the file mode creation mask when more secure file access permission +checks are implemented. +.P +It has been suggested that trusted systems developers might appreciate +ameliorating the requirement that the mode mask ``affects'' the file +access permissions, since it seems access control lists might replace +the mode mask to some degree. The wording has been changed to say that +it affects the file permission bits, and it leaves the details of the +behavior of how they affect the file access permissions to the +description in the System Interfaces volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIchmod\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIumask\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/unalias.1p b/man-pages-posix-2013-a/man1p/unalias.1p new file mode 100644 index 0000000..78602cb --- /dev/null +++ b/man-pages-posix-2013-a/man1p/unalias.1p @@ -0,0 +1,150 @@ +'\" et +.TH UNALIAS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unalias +\(em remove alias definitions +.SH SYNOPSIS +.LP +.nf +unalias \fIalias-name\fR... +.P +unalias \(mia +.fi +.SH DESCRIPTION +The +.IR unalias +utility shall remove the definition for each alias name specified. See +.IR "Section 2.3.1" ", " "Alias Substitution". +The aliases shall be removed from the current shell execution +environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.SH OPTIONS +The +.IR unalias +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mia\fP" 10 +Remove all alias definitions from the current shell execution +environment. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIalias-name\fR" 10 +The name of an alias to be removed. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR unalias : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +One of the +.IR alias-name +operands specified did not represent a valid alias definition, or an +error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR unalias +affects the current shell execution environment, it is generally +provided as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR unalias +description is based on that from historical KornShell implementations. +Known differences exist between that and the C shell. The KornShell +version was adopted to be consistent with all the other KornShell +features in this volume of POSIX.1\(hy2008, such as command line editing. +.P +The +.BR \(mia +option is the equivalent of the +.IR unalias +* form of the C shell and is provided to address security concerns +about unknown aliases entering the environment of a user (or +application) through the allowable implementation-defined predefined +alias route or as a result of an +.IR ENV +file. (Although +.IR unalias +could be used to simplify the ``secure'' shell script shown in the +.IR command +rationale, it does not obviate the need to quote all command names. An +initial call to +.IR unalias +.BR \(mia +would have to be quoted in case there was an alias for +.IR unalias .) +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIalias\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/uname.1p b/man-pages-posix-2013-a/man1p/uname.1p new file mode 100644 index 0000000..511d53c --- /dev/null +++ b/man-pages-posix-2013-a/man1p/uname.1p @@ -0,0 +1,201 @@ +'\" et +.TH UNAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uname +\(em return system name +.SH SYNOPSIS +.LP +.nf +uname \fB[\fR\(miamnrsv\fB]\fR +.fi +.SH DESCRIPTION +By default, the +.IR uname +utility shall write the operating system name to standard output. When +options are specified, symbols representing one or more system +characteristics shall be written to the standard output. The format +and contents of the symbols are implementation-defined. On systems +conforming to the System Interfaces volume of POSIX.1\(hy2008, the symbols written shall be those supported +by the +\fIuname\fR() +function as defined in the System Interfaces volume of POSIX.1\(hy2008. +.SH OPTIONS +The +.IR uname +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Behave as though all of the options +.BR \(mimnrsv +were specified. +.IP "\fB\(mim\fP" 10 +Write the name of the hardware type on which the system is running to +standard output. +.IP "\fB\(min\fP" 10 +Write the name of this node within an implementation-defined +communications network. +.IP "\fB\(mir\fP" 10 +Write the current release level of the operating system +implementation. +.IP "\fB\(mis\fP" 10 +Write the name of the implementation of the operating system. +.IP "\fB\(miv\fP" 10 +Write the current version level of this release of the operating system +implementation. +.P +If no options are specified, the +.IR uname +utility shall write the operating system name, as if the +.BR \(mis +option had been specified. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uname : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +By default, the output shall be a single line of the following form: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIsysname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mia +option is specified, the output shall be a single line of the following +form: +.sp +.RS 4 +.nf +\fB +"%s %s %s %s %s\en", <\fIsysname\fR>, <\fInodename\fR>, <\fIrelease\fR>, + <\fIversion\fR>, <\fImachine\fR> +.fi \fR +.P +.RE +.P +Additional implementation-defined symbols may be written; all such +symbols shall be written at the end of the line of output before the +. +.P +If options are specified to select different combinations of the +symbols, only those symbols shall be written, in the order shown above +for the +.BR \(mia +option. If a symbol is not selected for writing, its corresponding +trailing + +characters also shall not be written. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The requested information was successfully written. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Note that any of the symbols could include embedded + +characters, which may affect parsing algorithms if multiple options are +selected for output. +.P +The node name is typically a name that the system uses to identify +itself for inter-system communication addressing. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +uname \(misr +.fi \fR +.P +.RE +.P +writes the operating system name and release level, separated by one or +more + +characters. +.SH RATIONALE +It was suggested that this utility cannot be used portably since the +format of the symbols is implementation-defined. The POSIX.1 working +group could not achieve consensus on defining these formats in the +underlying +\fIuname\fR() +function, and there was no expectation that this volume of POSIX.1\(hy2008 would be any more +successful. Some applications may still find this historical utility of +value. For example, the symbols could be used for system log entries or +for comparison with operator or user input. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIuname\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/uncompress.1p b/man-pages-posix-2013-a/man1p/uncompress.1p new file mode 100644 index 0000000..7ab1245 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/uncompress.1p @@ -0,0 +1,186 @@ +'\" et +.TH UNCOMPRESS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uncompress +\(em expand compressed data +.SH SYNOPSIS +.LP +.nf +uncompress \fB[\fR\(micfv\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR uncompress +utility shall restore files to their original state after they have +been compressed using the +.IR compress +utility. If no files are specified, the standard input shall be +uncompressed to the standard output. If the invoking process has +appropriate privileges, the ownership, modes, access time, and +modification time of the original file shall be preserved. +.P +This utility shall support the uncompressing of any files produced by +the +.IR compress +utility on the same implementation. For files produced by +.IR compress +on other systems, +.IR uncompress +supports 9 to 14-bit compression (see +.IR "\fIcompress\fR\^", +.BR \(mib ); +it is implementation-defined whether values of +.BR \(mib +greater than 14 are supported. +.SH OPTIONS +The +.IR uncompress +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that Guideline 1 does apply since the utility name has ten letters. +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Write to standard output; no files are changed. +.IP "\fB\(mif\fP" 10 +Do not prompt for overwriting files. Except when run in the +background, if +.BR \(mif +is not given the user shall be prompted as to whether an existing file +should be overwritten. If the standard input is not a terminal and +.BR \(mif +is not given, +.IR uncompress +shall write a diagnostic message to standard error and exit with a +status greater than zero. +.IP "\fB\(miv\fP" 10 +Write messages to standard error concerning the expansion of each file. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file. If +.IR file +already has the +.BR .Z +suffix specified, it shall be used as the input file and the output +file shall be named +.BR file +with the +.BR .Z +suffix removed. Otherwise, +.IR file +shall be used as the name of the output file and +.BR file +with the +.BR .Z +suffix appended shall be used as the input file. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +Input files shall be in the format produced by the +.IR compress +utility. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uncompress : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When there are no +.IR file +operands or the +.BR \(mic +option is specified, the uncompressed output is written to standard +output. +.SH STDERR +Prompts shall be written to the standard error output under the +conditions specified in the DESCRIPTION and OPTIONS sections. The +prompts shall contain the +.IR file +pathname, but their format is otherwise unspecified. Otherwise, the +standard error output shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Output files are the same as the respective input files to +.IR compress . +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The input file remains unmodified. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The limit of 14 on the +.IR compress +.BR \(mib +.IR bits +argument is to achieve portability to all systems (within the +restrictions imposed by the lack of an explicit published file +format). Some implementations based on 16-bit architectures cannot +support 15 or 16-bit uncompression. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcompress\fR\^", +.IR "\fIzcat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/unexpand.1p b/man-pages-posix-2013-a/man1p/unexpand.1p new file mode 100644 index 0000000..c65a979 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/unexpand.1p @@ -0,0 +1,238 @@ +'\" et +.TH UNEXPAND "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unexpand +\(em convert spaces to tabs +.SH SYNOPSIS +.LP +.nf +unexpand \fB[\fR\(mia|\(mit \fItablist\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR unexpand +utility shall copy files or standard input to standard output, +converting + +characters at the beginning of each line into the maximum number of + +characters followed by the minimum number of + +characters needed to fill the same column positions originally filled +by the translated + +characters. By default, tabstops shall be set at every eighth column +position. Each + +shall be copied to the output, and shall cause the column position +count for tab calculations to be decremented; the count shall never be +decremented to a value less than one. +.SH OPTIONS +The +.IR unexpand +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +In addition to translating + +characters at the beginning of each line, translate all sequences of +two or more + +characters immediately preceding a tab stop to the maximum number of + +characters followed by the minimum number of + +characters needed to fill the same column positions originally filled +by the translated + +characters. +.IP "\fB\(mit\ \fItablist\fR" 10 +Specify the tab stops. The application shall ensure that the +.IR tablist +option-argument is a single argument consisting of a single positive +decimal integer or multiple positive decimal integers, separated by + +or + +characters, in ascending order. If a single number is given, tabs shall +be set +.IR tablist +column positions apart instead of the default 8. If multiple numbers +are given, the tabs shall be set at those specific column positions. +.RS 10 +.P +The application shall ensure that each tab-stop position +.IR N +is an integer value greater than zero, and the list shall be in +strictly ascending order. This is taken to mean that, from the start of +a line of output, tabbing to position +.IR N +shall cause the next character output to be in the (\c +.IR N +1)th +column position on that line. When the +.BR \(mit +option is not specified, the default shall be the equivalent of +specifying +.BR "\(mit\ 8" +(except for the interaction with +.BR \(mia , +described below). +.P +No +-to-\c + +conversions shall occur for characters at positions beyond the last of +those specified in a multiple tab-stop list. +.P +When +.BR \(mit +is specified, the presence or absence of the +.BR \(mia +option shall be ignored; conversion shall not be limited to the +processing of leading + +characters. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to be used as input. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR unexpand : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the processing of + +and + +characters, and for the determination of the width in column positions +each character would occupy on an output device. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be equivalent to the input files with +the specified +-to-\c + +conversions. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +One non-intuitive aspect of +.IR unexpand +is its restriction to leading + +characters when neither +.BR \(mia +nor +.BR \(mit +is specified. Users who always want to convert all + +characters in a file can easily alias +.IR unexpand +to use the +.BR \(mia +or +.BR "\(mit\ 8" +option. +.SH EXAMPLES +None. +.SH RATIONALE +On several occasions, consideration was given to adding a +.BR \(mit +option to the +.IR unexpand +utility to complement the +.BR \(mit +in +.IR expand +(see +.IR "\fIexpand\fR\^"). +The historical intent of +.IR unexpand +was to translate multiple + +characters into tab stops, where tab stops were a multiple of eight +column positions on most UNIX systems. An early proposal omitted +.BR \(mit +because it seemed outside the scope of the User Portability Utilities +option; it was not described in any of the base documents. However, +hard-coding tab stops every eight columns was not suitable for the +international community and broke historical precedents for some +vendors in the FORTRAN community, so +.BR \(mit +was restored in conjunction with the list of valid extension categories +considered by the standard developers. Thus, +.IR unexpand +is now the logical converse of +.IR expand . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexpand\fR\^", +.IR "\fItabs\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/unget.1p b/man-pages-posix-2013-a/man1p/unget.1p new file mode 100644 index 0000000..7a0a579 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/unget.1p @@ -0,0 +1,189 @@ +'\" et +.TH UNGET "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unget +\(em undo a previous get of an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +unget \fB[\fR\(mins\fB] [\fR\(mir \fISID\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR unget +utility shall reverse the effect of a +.IR get +.BR \(mie +done prior to creating the intended new delta. +.SH OPTIONS +The +.IR unget +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mir\ \fISID\fR" 10 +Uniquely identify which delta is no longer intended. (This would have +been specified by +.IR get +as the new delta.) The use of this option is necessary only if two or +more outstanding +.IR get +commands for editing on the same SCCS file were done by the same person +(login name). +.IP "\fB\(mis\fP" 10 +Suppress the writing to standard output of the intended delta's SID. +.IP "\fB\(min\fP" 10 +Retain the file that was obtained by +.IR get , +which would normally be removed from the current directory. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR unget +utility shall behave as though each file in the directory were specified as a named +file, except that non-SCCS files (last component of the pathname does +not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +Any SCCS files processed shall be files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR unget : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall consist of a line for each file, in the +following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fISID removed from file\fR> +.fi \fR +.P +.RE +.P +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of the +preceding lines: +.sp +.RS 4 +.nf +\fB +"\en%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Any SCCS files updated shall be files of an unspecified format. +During processing of a +.IR file , +a locking +.IR z-file , +as described in +.IR get , +and a +.IR q-file +(a working copy of the +.IR p-file ), +may be created and deleted. The +.IR p-file +and +.IR g-file , +as described in +.IR get , +shall be deleted. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIsact\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/uniq.1p b/man-pages-posix-2013-a/man1p/uniq.1p new file mode 100644 index 0000000..47a3d2b --- /dev/null +++ b/man-pages-posix-2013-a/man1p/uniq.1p @@ -0,0 +1,355 @@ +'\" et +.TH UNIQ "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uniq +\(em report or filter out repeated lines in a file +.SH SYNOPSIS +.LP +.nf +uniq \fB[\fR\(mic|\(mid|\(miu\fB] [\fR\(mif \fIfields\fB] [\fR\(mis \fIchar\fB] [\fIinput_file \fB[\fIoutput_file\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR uniq +utility shall read an input file comparing adjacent lines, and write +one copy of each input line on the output. The second and succeeding +copies of repeated adjacent input lines shall not be written. +The trailing + +of each line in the input shall be ignored when doing comparisons. +.P +Repeated lines in the input shall not be detected if they are not +adjacent. +.SH OPTIONS +The +.IR uniq +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Precede each output line with a count of the number of times the line +occurred in the input. +.IP "\fB\(mid\fP" 10 +Suppress the writing of lines that are not repeated in the input. +.IP "\fB\(mif\ \fIfields\fR" 10 +Ignore the first +.IR fields +fields on each input line when doing comparisons, where +.IR fields +is a positive decimal integer. A field is the maximal string matched +by the basic regular expression: +.RS 10 +.sp +.RS 4 +.nf +\fB +[[:blank:]]*[^[:blank:]]* +.fi \fR +.P +.RE +.P +If the +.IR fields +option-argument specifies more fields than appear on an input line, a +null string shall be used for comparison. +.RE +.IP "\fB\(mis\ \fIchars\fR" 10 +Ignore the first +.IR chars +characters when doing comparisons, where +.IR chars +shall be a positive decimal integer. If specified in conjunction with +the +.BR \(mif +option, the first +.IR chars +characters after the first +.IR fields +fields shall be ignored. If the +.IR chars +option-argument specifies more characters than remain on an input line, +a null string shall be used for comparison. +.IP "\fB\(miu\fP" 10 +Suppress the writing of lines that are repeated in the input. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIinput_file\fR" 10 +A pathname of the input file. If the +.IR input_file +operand is not specified, or if the +.IR input_file +is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIoutput_file\fR" 10 +A pathname of the output file. If the +.IR output_file +operand is not specified, the standard output shall be used. The +results are unspecified if the file named by +.IR output_file +is the file named by +.IR input_file . +.SH STDIN +The standard input shall be used only if no +.IR input_file +operand is specified or if +.IR input_file +is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uniq : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for ordering rules. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and which +characters constitute a + +in the current locale. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used if no +.IR output_file +operand is specified, and shall be used if the +.IR output_file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard output. Otherwise, the standard output shall +not be used. +See the OUTPUT FILES section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +If the +.BR \(mic +option is specified, the output file shall be empty or each line +shall be of the form: +.sp +.RS 4 +.nf +\fB +"%d %s", <\fInumber of duplicates\fR>, <\fIline\fR> +.fi \fR +.P +.RE +.P +otherwise, the output file shall be empty or each line shall be +of the form: +.sp +.RS 4 +.nf +\fB +"%s", <\fIline\fR> +.fi \fR +.P +.RE +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR sort +utility can be used to cause repeated lines to be adjacent in the input +file. +.SH EXAMPLES +The following input file data (but flushed left) was used for a test +series on +.IR uniq : +.sp +.RS 4 +.nf +\fB +#01 foo0 bar0 foo1 bar1 +#02 bar0 foo1 bar1 foo1 +#03 foo0 bar0 foo1 bar1 +#04 +#05 foo0 bar0 foo1 bar1 +#06 foo0 bar0 foo1 bar1 +#07 bar0 foo1 bar1 foo0 +.fi \fR +.P +.RE +.P +What follows is a series of test invocations of the +.IR uniq +utility that use a mixture of +.IR uniq +options against the input file data. These tests verify the meaning of +.IR adjacent . +The +.IR uniq +utility views the input data as a sequence of strings delimited by +.BR '\en' . +Accordingly, for the +.IR fields th +member of the sequence, +.IR uniq +interprets unique or repeated adjacent lines strictly relative to the +.IR fields +1th +member. +.IP " 1." 4 +This first example tests the line counting option, comparing each line +of the input file data starting from the second field: +.RS 4 +.sp +.RS 4 +.nf +\fB +uniq \(mic \(mif 1 uniq_0I.t + 1 #01 foo0 bar0 foo1 bar1 + 1 #02 bar0 foo1 bar1 foo1 + 1 #03 foo0 bar0 foo1 bar1 + 1 #04 + 2 #05 foo0 bar0 foo1 bar1 + 1 #07 bar0 foo1 bar1 foo0 +.fi \fR +.P +.RE +.P +The number +.BR '2' , +prefixing the fifth line of output, signifies that the +.IR uniq +utility detected a pair of repeated lines. Given the input data, this +can only be true when +.IR uniq +is run using the +.BR "\(mif\ 1" +option (which shall cause +.IR uniq +to ignore the first field on each input line). +.RE +.IP " 2." 4 +The second example tests the option to suppress unique lines, comparing +each line of the input file data starting from the second field: +.RS 4 +.sp +.RS 4 +.nf +\fB +uniq \(mid \(mif 1 uniq_0I.t +#05 foo0 bar0 foo1 bar1 +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +This test suppresses repeated lines, comparing each line of the input +file data starting from the second field: +.RS 4 +.sp +.RS 4 +.nf +\fB +uniq \(miu \(mif 1 uniq_0I.t +#01 foo0 bar0 foo1 bar1 +#02 bar0 foo1 bar1 foo1 +#03 foo0 bar0 foo1 bar1 +#04 +#07 bar0 foo1 bar1 foo0 +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +This suppresses unique lines, comparing each line of the input file +data starting from the third character: +.RS 4 +.sp +.RS 4 +.nf +\fB +uniq \(mid \(mis 2 uniq_0I.t +.fi \fR +.P +.RE +.P +In the last example, the +.IR uniq +utility found no input matching the above criteria. +.RE +.SH RATIONALE +Some historical implementations have limited lines to be 1\|080 bytes +in length, which does not meet the implied +{LINE_MAX} +limit. +.P +Earlier versions of this standard allowed the +.BR \(mi \c +.IR number +and +.BR \(pl \c +.IR number +options. These options are no longer specified by POSIX.1\(hy2008 but +may be present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcomm\fR\^", +.IR "\fIsort\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/unlink.1p b/man-pages-posix-2013-a/man1p/unlink.1p new file mode 100644 index 0000000..54884d4 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/unlink.1p @@ -0,0 +1,121 @@ +'\" et +.TH UNLINK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unlink +\(em call the +\fIunlink\fR() +function +.SH SYNOPSIS +.LP +.nf +unlink \fIfile\fP +.fi +.SH DESCRIPTION +The +.IR unlink +utility shall perform the function call: +.sp +.RS 4 +.nf +\fB +unlink(\fIfile\fP); +.fi \fR +.P +.RE +.P +A user may need appropriate privileges to invoke the +.IR unlink +utility. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fP" 10 +The pathname of an existing file. +.SH STDIN +Not used. +.SH "INPUT FILES" +Not used. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR unlink : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlink\fR\^", +.IR "\fIrm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/unset.1p b/man-pages-posix-2013-a/man1p/unset.1p new file mode 100644 index 0000000..cabb5c3 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/unset.1p @@ -0,0 +1,177 @@ +'\" et +.TH UNSET "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unset +\(em unset values and attributes of variables and functions +.SH SYNOPSIS +.LP +.nf +unset \fB[\fR\(mifv\fB] \fIname\fR... +.fi +.SH DESCRIPTION +Each variable or function specified by +.IR name +shall be unset. +.P +If +.BR \(miv +is specified, +.IR name +refers to a variable name and the shell shall unset it and remove it +from the environment. Read-only variables cannot be unset. +.P +If +.BR \(mif +is specified, +.IR name +refers to a function and the shell shall unset the function definition. +.P +If neither +.BR \(mif +nor +.BR \(miv +is specified, +.IR name +refers to a variable; if a variable by that name does not exist, it is +unspecified whether a function by that name, if any, shall be unset. +.P +Unsetting a variable or function that was not previously set shall not +be considered an error and does not cause the shell to abort. +.P +The +.IR unset +special built-in shall support the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +Note that: +.sp +.RS 4 +.nf +\fB +VARIABLE= +.fi \fR +.P +.RE +.P +is not equivalent to an +.IR unset +of +.BR VARIABLE ; +in the example, +.BR VARIABLE +is set to +.BR \(dq\^\(dq . +Also, the variables that can be +.IR unset +should not be misinterpreted to include the special parameters (see +.IR "Section 2.5.2" ", " "Special Parameters"). +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.IP "\00" 6 +All +.IR name +operands were successfully unset. +.IP >0 6 +At least one +.IR name +could not be unset. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Unset +.IR VISUAL +variable: +.sp +.RS 4 +.nf +\fB +unset \(miv VISUAL +.fi \fR +.P +.RE +.P +Unset the functions +.BR foo +and +.BR bar : +.sp +.RS 4 +.nf +\fB +unset \(mif foo bar +.fi \fR +.P +.RE +.SH "RATIONALE" +Consideration was given to omitting the +.BR \(mif +option in favor of an +.IR unfunction +utility, but the standard developers decided to retain historical +practice. +.P +The +.BR \(miv +option was introduced because System V historically used one name space +for both variables and functions. When +.IR unset +is used without options, System V historically unset either a function +or a variable, and there was no confusion about which one was intended. +A portable POSIX application can use +.IR unset +without an option to unset a variable, but not a function; the +.BR \(mif +option must be used. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/uucp.1p b/man-pages-posix-2013-a/man1p/uucp.1p new file mode 100644 index 0000000..05c753c --- /dev/null +++ b/man-pages-posix-2013-a/man1p/uucp.1p @@ -0,0 +1,292 @@ +'\" et +.TH UUCP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uucp +\(em system-to-system copy +.SH SYNOPSIS +.LP +.nf +uucp \fB[\fR\(micCdfjmr\fB] [\fR\(min \fIuser\fB] \fIsource-file\fR... \fIdestination-file\fR +.fi +.SH DESCRIPTION +The +.IR uucp +utility shall copy files named by the +.IR source-file +argument to the +.IR destination-file +argument. The files named can be on local or remote systems. +.P +The +.IR uucp +utility cannot guarantee support for all character encodings in all +circumstances. For example, transmission data may be restricted to 7 +bits by the underlying network, 8-bit data and filenames need not be +portable to non-internationalized systems, and so on. Under these +circumstances, it is recommended that only characters defined in the +ISO/IEC\ 646:\|1991 standard International Reference Version (equivalent to ASCII) 7-bit range +of characters be used, and that only characters defined in the portable +filename character set be used for naming files. The protocol for +transfer of files is unspecified by POSIX.1\(hy2008. +.P +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +but other communications means may be used. On systems where there are +no available communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.SH OPTIONS +The +.IR uucp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Do not copy local file to the spool directory for transfer to the +remote machine (default). +.IP "\fB\(miC\fP" 10 +Force the copy of local files to the spool directory for transfer. +.IP "\fB\(mid\fP" 10 +Make all necessary directories for the file copy (default). +.IP "\fB\(mif\fP" 10 +Do not make intermediate directories for the file copy. +.IP "\fB\(mij\fP" 10 +Write the job identification string to standard output. This job +identification can be used by +.IR uustat +to obtain the status or terminate a job. +.IP "\fB\(mim\fP" 10 +Send mail to the requester when the copy is completed. +.IP "\fB\(min\ \fIuser\fR" 10 +Notify +.IR user +on the remote system that a file was sent. +.IP "\fB\(mir\fP" 10 +Do not start the file transfer; just queue the job. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdestination-file\fR,\ \fIsource-file\fR" 10 +.br +A pathname of a file to be copied to, or from, respectively. Either +name can be a pathname on the local machine, or can have the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIsystem-name\fR!\fIpathname\fR +.fi \fR +.P +.RE +.P +where +.IR system-name +is taken from a list of system names that +.IR uucp +knows about. +The destination +.IR system-name +can also be a list of names such as: +.sp +.RS 4 +.nf +\fB +\fIsystem-name\fR!\fIsystem-name\fR!...!\fIsystem-name\fR!\fIpathname\fR +.fi \fR +.P +.RE +.P +in which case, an attempt is made to send the file via the specified +route to the destination. Care should be taken to ensure that +intermediate nodes in the route are willing to forward information. +.P +The shell pattern matching notation characters +.BR '?' , +.BR '*' , +and +.BR \(dq[...]\(dq +appearing in +.IR pathname +shall be expanded on the appropriate system. +.P +Pathnames can be one of: +.IP " 1." 4 +An absolute pathname. +.IP " 2." 4 +A pathname preceded by ~\c +.IR user +where +.IR user +is a login name on the specified system and is replaced by that user's +login directory. Note that if an invalid login is specified, the +default is to the public directory (called +.IR PUBDIR ; +the actual location of +.IR PUBDIR +is implementation-defined). +.IP " 3." 4 +A pathname preceded by ~/\c +.IR destination +where +.IR destination +is appended to +.IR PUBDIR . +.RS 4 +.TP 10 +.BR Note: +This destination is treated as a filename unless more than one file is +being transferred by this request or the destination is already a +directory. To ensure that it is a directory, follow the destination +with a +.BR '/' . +For example, +.BR ~/dan/ +as the destination makes the directory +.BR PUBDIR/dan +if it does not exist and puts the requested files in that directory. +.P +.RE +.IP " 4." 4 +Anything else shall be prefixed by the current directory. +.P +If the result is an erroneous pathname for the remote system, the copy +shall fail. If the +.IR destination-file +is a directory, the last part of the +.IR source-file +name shall be used. +.P +The read, write, and execute permissions given by +.IR uucp +are implementation-defined. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +The files to be copied are regular files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uucp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within bracketed filename +patterns. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within bracketed filename patterns (for example, +.BR \(dq'[[:lower:]]*'\(dq ). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files (which may be on other systems) are copies of the +input files. +.P +If +.BR \(mim +is used, mail files are modified. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility is part of the UUCP Utilities option and need not be +supported by all implementations. +.P +The domain of remotely accessible files can (and for obvious security +reasons usually should) be severely restricted. +.P +Note that the +.BR '!' +character in addresses has to be escaped when using +.IR csh +as a command interpreter because of its history substitution syntax. +For +.IR ksh +and +.IR sh +the escape is not necessary, but may be used. +.P +As noted above, shell metacharacters appearing in pathnames are +expanded on the appropriate system. On an internationalized system, +this is done under the control of local settings of +.IR LC_COLLATE +and +.IR LC_CTYPE . +Thus, care should be taken when using bracketed filename patterns, as +collation and typing rules may vary from one system to another. Also +be aware that certain types of expression (that is, equivalence +classes, character classes, and collating symbols) need not be +supported on non-internationalized systems. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImailx\fR\^", +.IR "\fIuuencode\fR\^", +.IR "\fIuustat\fR\^", +.IR "\fIuux\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/uudecode.1p b/man-pages-posix-2013-a/man1p/uudecode.1p new file mode 100644 index 0000000..f93cd87 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/uudecode.1p @@ -0,0 +1,215 @@ +'\" et +.TH UUDECODE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uudecode +\(em decode a binary file +.SH SYNOPSIS +.LP +.nf +uudecode \fB[\fR\(mio \fIoutfile\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR uudecode +utility shall read a file, or standard input if no file is specified, +that includes data created by the +.IR uuencode +utility. The +.IR uudecode +utility shall scan the input file, searching for data compatible with +one of the formats specified in +.IR uuencode , +and attempt to create or overwrite the file described by the data (or +overridden by the +.BR \(mio +option). The pathname shall be contained in the data or specified by +the +.BR \(mio +option. The file access permission bits and contents for the file to be +produced shall be contained in that data. The mode bits of the created +file (other than standard output) shall be set from the file access +permission bits contained in the data; that is, other attributes of the +mode, including the file mode creation mask (see +.IR umask ), +shall not affect the file being produced. If either of the +.IR op +characters +.BR '\(pl' +and +.BR '\(mi' +(see +.IR chmod ) +are specified in symbolic mode, the initial mode on which those +operations are based is unspecified. +.P +If the pathname of the file to be produced exists, and the user does +not have write permission on that file, +.IR uudecode +shall terminate with an error. If the pathname of the file to be +produced exists, and the user has write permission on that file, the +existing file shall be overwritten. +.P +If the input data was produced by +.IR uuencode +on a system with a different number of bits per byte than on the target +system, the results of +.IR uudecode +are unspecified. +.SH OPTIONS +The +.IR uudecode +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mio\ \fIoutfile\fR" 10 +A pathname of a file that shall be used instead of any pathname +contained in the input data. Specifying an +.IR outfile +option-argument of +.BR /dev/stdout +shall indicate standard output. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a file containing the output of +.IR uuencode . +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be files containing the output of +.IR uuencode . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uudecode : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the file data header encoded by +.IR uuencode +is +.BR \(mi +or +.BR /dev/stdout , +or the +.BR \(mio +.BR /dev/stdout +option overrides the file data, the standard output shall be in the +same format as the file originally encoded by +.IR uuencode . +Otherwise, the standard output shall not be used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output file shall be in the same format as the file originally +encoded by +.IR uuencode . +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The user who is invoking +.IR uudecode +must have write permission on any file being created. +.P +The output of +.IR uuencode +is essentially an encoded bit stream that is not cognizant of byte +boundaries. It is possible that a 9-bit byte target machine can +process input from an 8-bit source, if it is aware of the requirement, +but the reverse is unlikely to be satisfying. Of course, the only data +that is meaningful for such a transfer between architectures is +generally character data. +.SH EXAMPLES +None. +.SH RATIONALE +Input files are not necessarily text files, as stated by an early +proposal. Although the +.IR uuencode +output is a text file, that output could have been wrapped within +another file or mail message that is not a text file. +.P +The +.BR \(mio +option is not historical practice, but was added at the request of WG15 +so that the user could override the target pathname without having to +edit the input data itself. +.P +In early drafts, the [\c +.BR \(mio +.IR outfile ] +option-argument allowed the use of +.BR \(mi +to mean standard output. The symbol +.BR \(mi +has only been used previously in POSIX.1\(hy2008 as a standard input indicator. +The standard developers did not wish to overload the meaning of +.BR \(mi +in this manner. The +.BR /dev/stdout +concept exists on most modern systems. The +.BR /dev/stdout +syntax does not refer to a new special file. It is just a magic cookie +to specify standard output. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIumask\fR\^", +.IR "\fIuuencode\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/uuencode.1p b/man-pages-posix-2013-a/man1p/uuencode.1p new file mode 100644 index 0000000..f307713 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/uuencode.1p @@ -0,0 +1,378 @@ +'\" et +.TH UUENCODE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uuencode +\(em encode a binary file +.SH SYNOPSIS +.LP +.nf +uuencode \fB[\fR\(mim\fB] [\fIfile\fB] \fIdecode_pathname\fR +.fi +.SH DESCRIPTION +The +.IR uuencode +utility shall write an encoded version of the named input file, or +standard input if no +.IR file +is specified, to standard output. The output shall be encoded using +one of the algorithms described in the STDOUT section and shall +include the file access permission bits (in +.IR chmod +octal or symbolic notation) of the input file and the +.IR decode_pathname , +for re-creation of the file on another system that conforms to this volume of POSIX.1\(hy2008. +.SH OPTIONS +The +.IR uuencode +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mim\fP" 10 +Encode the output using the MIME Base64 algorithm described in STDOUT. +If +.BR \(mim +is not specified, the historical algorithm described in STDOUT shall be +used. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdecode_pathname\fR" 10 +.br +The pathname of the file into which the +.IR uudecode +utility shall place the decoded file. Specifying a +.IR decode_pathname +operand of +.BR /dev/stdout +shall indicate that +.IR uudecode +is to use standard output. If there are characters in +.IR decode_pathname +that are not in the portable filename character set the results are +unspecified. +.IP "\fIfile\fR" 10 +A pathname of the file to be encoded. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Input files can be files of any type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uuencode : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +.SS "uuencode Base64 Algorithm" +.P +The standard output shall be a text file (encoded in the character set +of the current locale) that begins with the line: +.sp +.RS 4 +.nf +\fB +"begin-base64 %s %s\en", <\fImode\fR>, <\fIdecode_pathname\fR> +.fi \fR +.P +.RE +.P +and ends with the line: +.sp +.RS 4 +.nf +\fB +"====\en" +.fi \fR +.P +.RE +.P +In both cases, the lines shall have no preceding or trailing + +characters. +.P +The encoding process represents 24-bit groups of input bits as output +strings of four encoded characters. Proceeding from left to right, a +24-bit input group shall be formed by concatenating three 8-bit input +groups. Each 24-bit input group then shall be treated as four +concatenated 6-bit groups, each of which shall be translated into a +single digit in the Base64 alphabet. When encoding a bit stream via the +Base64 encoding, the bit stream shall be presumed to be ordered with +the most-significant bit first. That is, the first bit in the stream +shall be the high-order bit in the first byte, and the eighth bit shall +be the low-order bit in the first byte, and so on. Each 6-bit group is +used as an index into an array of 64 printable characters, as shown in +.IR "Table 4-22, uuencode Base64 Values". +.sp +.ce 1 +\fBTable 4-22: uuencode Base64 Values\fR +.TS +center box tab(!); +cB | cB || cB | cB || cB | cB || cB | cB +n | cf5 || n | cf5 || n | cf5 || n | cf5. +Value!Encoding!Value!Encoding!Value!Encoding!Value!Encoding +_ +0!A!17!R!34!i!51!z +1!B!18!S!35!j!52!0 +2!C!19!T!36!k!53!1 +3!D!20!U!37!l!54!2 +4!E!21!V!38!m!55!3 +5!F!22!W!39!n!56!4 +6!G!23!X!40!o!57!5 +7!H!24!Y!41!p!58!6 +8!I!25!Z!42!q!59!7 +9!J!26!a!43!r!60!8 +10!K!27!b!44!s!61!9 +11!L!28!c!45!t!62!+ +12!M!29!d!46!u!63!/ +13!N!30!e!47!v +14!O!31!f!48!w!(pad)!\&= +15!P!32!g!49!x +16!Q!33!h!50!y +.TE +.P +The character referenced by the index shall be placed in the output +string. +.P +The output stream (encoded bytes) shall be represented in lines of no +more than 76 characters each. All line breaks or other characters not +found in the table shall be ignored by decoding software (see +.IR "\fIuudecode\fR\^"). +.P +Special processing shall be performed if fewer than 24 bits are +available at the end of a message or encapsulated part of a message. A +full encoding quantum shall always be completed at the end of a +message. When fewer than 24 input bits are available in an input group, +zero bits shall be added (on the right) to form an integral number of +6-bit groups. Output character positions that are not required to +represent actual input data shall be set to the character +.BR '=' . +Since all Base64 input is an integral number of octets, only the +following cases can arise: +.IP " 1." 4 +The final quantum of encoding input is an integral multiple of 24 bits; +here, the final unit of encoded output shall be an integral multiple of +4 characters with no +.BR '=' +padding. +.IP " 2." 4 +The final quantum of encoding input is exactly 16 bits; here, the final +unit of encoded output shall be three characters followed by one +.BR '=' +padding character. +.IP " 3." 4 +The final quantum of encoding input is exactly 8 bits; here, the final +unit of encoded output shall be two characters followed by two +.BR '=' +padding characters. +.P +A terminating +.BR \(dq====\(dq +evaluates to nothing and denotes the end of the encoded data. +.SS "uuencode Historical Algorithm" +.P +The standard output shall be a text file (encoded in the character set +of the current locale) that begins with the line: +.sp +.RS 4 +.nf +\fB +"begin %s %s\en" <\fImode\fR>, <\fIdecode_pathname\fR> +.fi \fR +.P +.RE +.P +and ends with the line: +.sp +.RS 4 +.nf +\fB +"end\en" +.fi \fR +.P +.RE +.P +In both cases, the lines shall have no preceding or trailing + +characters. +.P +The algorithm that shall be used for lines in between +.BR begin +and +.BR end +takes three octets as input and writes four characters of output by +splitting the input at six-bit intervals into four octets, containing +data in the lower six bits only. These octets shall be converted to +characters by adding a value of 0x20 to each octet, so that each octet +is in the range [0x20,0x5f], and then it shall be assumed to represent +a printable character in the ISO/IEC\ 646:\|1991 standard encoded character set. It then +shall be translated into the corresponding character codes for the +codeset in use in the current locale. (For example, the octet 0x41, +representing +.BR 'A' , +would be translated to +.BR 'A' +in the current codeset, such as 0xc1 if it were EBCDIC.) +.P +Where the bits of two octets are combined, the least significant bits +of the first octet shall be shifted left and combined with the most +significant bits of the second octet shifted right. Thus the three +octets +.IR A , +.IR B , +.IR C +shall be converted into the four octets: +.sp +.RS 4 +.nf +\fB +0x20 + (( A >> 2 ) & 0x3F) +0x20 + (((A << 4) |\h'\n(XX' ((B >> 4) & 0xF)) & 0x3F) +0x20 + (((B << 2) |\h'\n(XX' ((C >> 6) & 0x3)) & 0x3F) +0x20 + (( C ) & 0x3F) +.fi \fR +.P +.RE +.P +These octets then shall be translated into the local character set. +.P +Each encoded line contains a length character, equal to the number of +characters to be decoded plus 0x20 translated to the local character +set as described above, followed by the encoded characters. The +maximum number of octets to be encoded on each line shall be 45. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The file is expanded by 35 percent (each three octets become four, plus +control information) causing it to take longer to transmit. +.P +Since this utility is intended to create files to be used for data +interchange between systems with possibly different codesets, and to +represent binary data as a text file, the ISO/IEC\ 646:\|1991 standard was chosen for a +midpoint in the algorithm as a known reference point. The output from +.IR uuencode +is a text file on the local system. If the output were in the ISO/IEC\ 646:\|1991 standard +codeset, it might not be a text file (at least because the + +characters might not match), and the goal of creating a text file would +be defeated. If this text file was then carried to another machine with +the same codeset, it would be perfectly compatible with that system's +.IR uudecode . +If it was transmitted over a mail system or sent to a machine with a +different codeset, it is assumed that, as for every other text file, +some translation mechanism would convert it (by the time it reached a +user on the other system) into an appropriate codeset. This +translation only makes sense from the local codeset, not if the file +has been put into a ISO/IEC\ 646:\|1991 standard representation first. Similarly, files +processed by +.IR uuencode +can be placed in +.IR pax +archives, intermixed with other text files in the same codeset. +.SH EXAMPLES +None. +.SH RATIONALE +A new algorithm was added at the request of the international community +to parallel work in RFC\ 2045 (MIME). As with the historical +.IR uuencode +format, the Base64 Content-Transfer-Encoding is designed to represent +arbitrary sequences of octets in a form that is not humanly readable. A +65-character subset of the ISO/IEC\ 646:\|1991 standard is used, enabling 6 bits to be +represented per printable character. (The extra 65th character, +.BR '=' , +is used to signify a special processing function.) +.P +This subset has the important property that it is represented +identically in all versions of the ISO/IEC\ 646:\|1991 standard, including US ASCII, and all +characters in the subset are also represented identically in all +versions of EBCDIC. The historical +.IR uuencode +algorithm does not share this property, which is the reason that a +second algorithm was added to the ISO\ POSIX\(hy2 standard. +.P +The string +.BR \(dq====\(dq +was used for the termination instead of the end used in the original +format because the latter is a string that could be valid encoded +input. +.P +In an early draft, the +.BR \(mim +option was named +.BR \(mib +(for Base64), but it was renamed to reflect its relationship to the +RFC\ 2045. A +.BR \(miu +was also present to invoke the default algorithm, but since this was +not historical practice, it was omitted as being unnecessary. +.P +See the RATIONALE section in +.IR "\fIuudecode\fR\^" +for the derivation of the +.BR /dev/stdout +symbol. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fImailx\fR\^", +.IR "\fIuudecode\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/uustat.1p b/man-pages-posix-2013-a/man1p/uustat.1p new file mode 100644 index 0000000..dcab76d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/uustat.1p @@ -0,0 +1,162 @@ +'\" et +.TH UUSTAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uustat +\(em uucp status enquiry and job control +.SH SYNOPSIS +.LP +.nf +uustat \fB[\fR\(miq|\(mik \fIjobid\fR|\(mir \fIjobid\fB]\fR +.P +uustat \fB[\fR\(mis \fIsystem\fB] [\fR\(miu \fIuser\fB]\fR +.fi +.SH DESCRIPTION +The +.IR uustat +utility shall display the status of, or cancel, previously specified +.IR uucp +requests, or provide general status on +.IR uucp +connections to other systems. +.P +When no options are given, +.IR uustat +shall write to standard output the status of all +.IR uucp +requests issued by the current user. +.P +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +but other communications means may be used. On systems where there are +no available communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.SH OPTIONS +The +.IR uustat +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miq\fP" 10 +Write the jobs queued for each machine. +.IP "\fB\(mik\ \fIjobid\fR" 10 +Kill the +.IR uucp +request whose job identification is +.IR jobid . +The application shall ensure that the killed +.IR uucp +request belongs to the person invoking +.IR uustat +unless that user has appropriate privileges. +.IP "\fB\(mir\ \fIjobid\fR" 10 +Rejuvenate +.IR jobid . +The files associated with +.IR jobid +are touched so that their modification time is set to the current +time. This prevents the cleanup program from deleting the job until +the jobs modification time reaches the limit imposed by the program. +.IP "\fB\(mis\ \fIsystem\fR" 10 +Write the status of all +.IR uucp +requests for remote system +.IR system . +.IP "\fB\(miu\ \fIuser\fR" 10 +Write the status of all +.IR uucp +requests issued by +.IR user . +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uustat : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall consist of information about each job +selected, in an unspecified format. The information shall include at +least the job ID, the user ID or name, and the remote system name. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility is part of the UUCP Utilities option and need not be +supported by all implementations. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIuucp\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/uux.1p b/man-pages-posix-2013-a/man1p/uux.1p new file mode 100644 index 0000000..903f6cc --- /dev/null +++ b/man-pages-posix-2013-a/man1p/uux.1p @@ -0,0 +1,361 @@ +'\" et +.TH UUX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uux +\(em remote command execution +.SH SYNOPSIS +.LP +.nf +uux \fB[\fR\(mijnp\fB] \fIcommand\(mistring\fR +.fi +.SH DESCRIPTION +The +.IR uux +utility shall gather zero or more files from various systems, execute a +shell pipeline (see +.IR "Section 2.9" ", " "Shell Commands") +on a specified system, and then send the standard output of the command +to a file on a specified system. Only the first command of a pipeline +can have a +.IR system-name ! +prefix. All other commands in the pipeline shall be executed on the +system of the first command. +.P +The following restrictions are applicable to the shell pipeline +processed by +.IR uux : +.IP " *" 4 +In gathering files from different systems, pathname expansion shall +not be performed by +.IR uux . +Thus, a request such as: +.RS 4 +.sp +.RS 4 +.nf +\fB +uux "c99 remsys!~/*.c" +.fi \fR +.P +.RE +.P +would attempt to copy the file named literally +.BR *.c +to the local system. +.RE +.IP " *" 4 +The redirection operators +.BR \(dq>>\(dq , +.BR \(dq<<\(dq , +.BR \(dq>|\(dq , +and +.BR \(dq>&\(dq +shall not be accepted. Any use of these redirection operators shall +cause this utility to write an error message describing the problem +and exit with a non-zero exit status. +.IP " *" 4 +The reserved word +.BR ! +cannot be used at the head of the pipeline to modify the exit status. +(See the +.IR command-string +operand description below.) +.IP " *" 4 +Alias substitution shall not be performed. +.P +A filename can be specified as for +.IR uucp ; +it can be an absolute pathname, a pathname preceded by ~\c +.IR name +(which is replaced by the corresponding login directory), a pathname +specified as ~/\^\c +.IR dest +(\c +.IR dest +is prefixed by the public directory called +.IR PUBDIR ; +the actual location of +.IR PUBDIR +is implementation-defined), or a simple filename (which is prefixed +by +.IR uux +with the current directory). See +.IR "\fIuucp\fR\^" +for the details. +.P +The execution of commands on remote systems shall take place in an +execution directory known to the +.IR uucp +system. All files required for the execution shall be put into this +directory unless they already reside on that machine. Therefore, the +application shall ensure that non-local filenames (without path or +machine reference) are unique within the +.IR uux +request. +.P +The +.IR uux +utility shall attempt to get all files to the execution system. For +files that are output files, the application shall ensure that the +filename is escaped using parentheses. +.P +The remote system shall notify the user by mail if the requested +command on the remote system was disallowed or the files were not +accessible. This notification can be turned off by the +.BR \(min +option. +.P +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +but other communications means may be used. On systems where there are +no available communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.P +The +.IR uux +utility cannot guarantee support for all character encodings in all +circumstances. For example, transmission data may be restricted to 7 +bits by the underlying network, 8-bit data and filenames need not be +portable to non-internationalized systems, and so on. Under these +circumstances, it is recommended that only characters defined in the +ISO/IEC\ 646:\|1991 standard International Reference Version (equivalent to ASCII) 7-bit range +of characters be used and that only characters defined in the portable +filename character set be used for naming files. +.SH OPTIONS +The +.IR uux +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mij\fP" 10 +Write the job identification string to standard output. This job +identification can be used by +.IR uustat +to obtain the status or terminate a job. +.IP "\fB\(min\fP" 10 +Do not notify the user if the command fails. +.IP "\fB\(mip\fP" 10 +Make the standard input to +.IR uux +the standard input to the +.IR command-string . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIcommand-string\fR" 10 +.br +A string made up of one or more arguments that are similar to normal +command arguments, except that the command and any filenames can be +prefixed by +.IR system-name !. +A null +.IR system-name +shall be interpreted as the local system. +.SH STDIN +The standard input shall not be used unless the +.BR '\(mi' +or +.BR \(mip +option is specified; in those cases, the standard input shall be made +the standard input of the +.IR command-string . +.SH "INPUT FILES" +Input files shall be selected according to the contents of +.IR command-string . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uux : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall not be used unless the +.BR \(mij +option is specified; in that case, the job identification string shall +be written to standard output in the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIjobid\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Output files shall be created or written, or both, according to the +contents of +.IR command-string . +.P +If +.BR \(min +is not used, mail files shall be modified following any command or +file-access failures on the remote system. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility is part of the UUCP Utilities option and need not be +supported by all implementations. +.P +Note that, for security reasons, many installations limit the list of +commands executable on behalf of an incoming request from +.IR uux . +Many sites permit little more than the receipt of mail via +.IR uux . +.P +Any characters special to the command interpreter should be quoted +either by quoting the entire +.IR command-string +or quoting the special characters as individual arguments. +.P +As noted in +.IR uucp , +shell pattern matching notation +characters appearing in pathnames are expanded on the appropriate local +system. This is done under the control of local settings of +.IR LC_COLLATE +and +.IR LC_CTYPE . +Thus, care should be taken when using bracketed filename patterns, as +collation and typing rules may vary from one system to another. Also +be aware that certain types of expression (that is, equivalence +classes, character classes, and collating symbols) need not be +supported on non-internationalized systems. +.SH EXAMPLES +.IP " 1." 4 +The following command gets +.BR file1 +from system +.BR a +and +.BR file2 +from system +.BR b , +executes +.IR diff +on the local system, and puts the results in +.BR file.diff +in the local +.IR PUBDIR +directory. (\c +.IR PUBDIR +is the +.IR uucp +public directory on the local system.) +.RS 4 +.sp +.RS 4 +.nf +\fB +uux "!diff a!/usr/file1 b!/a4/file2 >!~/file.diff" +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following command fails because +.IR uux +places all files copied to a system in the same working directory. +Although the files +.BR xyz +are from two different systems, their filenames are the same and +conflict. +.RS 4 +.sp +.RS 4 +.nf +\fB +uux "!diff a!/usr1/xyz b!/usr2/xyz >!~/xyz.diff" +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +The following command succeeds (assuming +.IR diff +is permitted on system +.BR a ) +because the file local to system +.BR a +is not copied to the working directory, and hence does not conflict with +the file from system +.BR c . +.RS 4 +.sp +.RS 4 +.nf +\fB +uux "a!diff a!/usr/xyz c!/usr/xyz >!~/xyz.diff" +.fi \fR +.P +.RE +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIuucp\fR\^", +.IR "\fIuuencode\fR\^", +.IR "\fIuustat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/val.1p b/man-pages-posix-2013-a/man1p/val.1p new file mode 100644 index 0000000..0a83f4d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/val.1p @@ -0,0 +1,248 @@ +'\" et +.TH VAL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +val +\(em validate SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +val \(mi +.P +val \fB[\fR\(mis\fB] [\fR\(mim \fIname\fB] [\fR\(mir \fISID\fB] [\fR\(miy \fItype\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR val +utility shall determine whether the specified +.IR file +is an SCCS file meeting the characteristics specified by the options. +.SH OPTIONS +The +.IR val +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the usage of the +.BR '\(mi' +operand is not strictly as intended by the guidelines (that is, reading +options and operands from standard input). +.P +The following options shall be supported: +.IP "\fB\(mim\ \fIname\fR" 10 +Specify a +.IR name , +which is compared with the SCCS %\fBM\fP% keyword in +.IR file ; +see +.IR "\fIget\fR\^". +.IP "\fB\(mir\ \fISID\fR" 10 +Specify a +.IR SID +(SCCS Identification String), an SCCS delta number. A check shall be +made to determine whether the +.IR SID +is ambiguous (for example, +.BR "\(mir\ 1" +is ambiguous because it physically does not exist but implies 1.1, 1.2, +and so on, which may exist) or invalid (for example, +.BR "\(mir\ 1.0" +or +.BR "\(mir\ 1.1.0" +are invalid because neither case can exist as a valid delta number). +If the +.IR SID +is valid and not ambiguous, a check shall be made to determine whether +it actually exists. +.IP "\fB\(mis\fP" 10 +Silence the diagnostic message normally written to standard output for +any error that is detected while processing each named file on a given +command line. +.IP "\fB\(miy\ \fItype\fR" 10 +Specify a +.IR type , +which shall be compared with the SCCS %\fBY\fP% keyword in +.IR file ; +see +.IR "\fIget\fR\^". +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file. If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read: each line shall be independently +processed as if it were a command line argument list. (However, the +line is not subjected to any of the shell word expansions, such as +parameter expansion or quote removal.) +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +.SH "INPUT FILES" +Any SCCS files processed shall be files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR val : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall consist of informative messages about either: +.IP " 1." 4 +Each file processed +.IP " 2." 4 +Each command line read from standard input +.P +If the standard input is not used, for each +.IR file +operand yielding a discrepancy, the output line shall have the +following format: +.sp +.RS 4 +.nf +\fB +"%s: %s\en", <\fIpathname\fR>, <\fIunspecified string\fR> +.fi \fR +.P +.RE +.P +If the standard input is used, for each input line yielding a discrepancy, +the output shall have the following format: +.sp +.RS 4 +.nf +\fB +"%s\en\en %s: %s\en", <\fIinput\fR>, <\fIpathname\fR>, <\fIunspecified string\fR> +.fi \fR +.P +.RE +.P +where <\fIinput\fP> is the input line minus its terminating +. +.SH STDERR +Not used. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The 8-bit code returned by +.IR val +shall be a disjunction of the possible errors; that is, it can be +interpreted as a bit string where set bits are interpreted as follows: +.TS +tab(@); +l c l. +0x80@\&=@Missing file argument. +0x40@\&=@Unknown or duplicate option. +0x20@\&=@Corrupted SCCS file. +0x10@\&=@Cannot open file or file not SCCS. +0x08@\&=@\fISID\fR is invalid or ambiguous. +0x04@\&=@\fISID\fR does not exist. +0x02@\&=@%\fBY\fR%, \fB\(miy\fR mismatch. +0x01@\&=@%\fBM\fR%, \fB\(mim\fR mismatch. +.TE +.P +Note that +.IR val +can process two or more files on a given command line and can process +multiple command lines (when reading the standard input). In these +cases an aggregate code shall be returned: a logical OR of the codes +generated for each command line and file processed. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since the +.IR val +exit status sets the 0x80 bit, shell applications checking +.BR \(dq$?\(dq +cannot tell if it terminated due to a missing file argument or receipt +of a signal. +.SH EXAMPLES +In a directory with three SCCS files\(em\c +.BR s.x +(of +.BR t +type ``text''), +.BR s.y , +and +.BR s.z +(a corrupted file)\(emthe following command could produce the output +shown: +.sp +.RS 4 +.nf +\fB +val \(mi < +can be used to return to command mode; other uses of + +are described later in this section; see +.IR "Terminate Command or Input Mode". +.SS "Initialization in ex and vi" +.P +See +.IR "Initialization in ex and vi" +for a description of +.IR ex +and +.IR vi +initialization for the +.IR vi +utility. +.SS "Command Descriptions in vi" +.P +The following symbols are used in this reference page to represent +arguments to commands. +.IP "\fIbuffer\fR" 8 +See the description of +.IR buffer +in the EXTENDED DESCRIPTION section of the +.IR ex +utility; see +.IR "Command Descriptions in ex". +.RS 8 +.P +In open and visual mode, when a command synopsis shows both [\c +.IR buffer ] +and [\c +.IR count ] +preceding the command name, they can be specified in either order. +.RE +.IP "\fIcount\fR" 8 +A positive integer used as an optional argument to most commands, +either to give a repeat count or as a size. This argument is optional +and shall default to 1 unless otherwise specified. +.RS 8 +.P +The Synopsis lines for the +.IR vi +commands +\(hyG, +\(hyL, +\(hyR, +\(hy], +.BR % , +.BR & , +.BR ^ , +.BR D , +.BR m , +.BR M , +.BR Q , +.BR u , +.BR U , +and +.BR ZZ +do not have +.IR count +as an optional argument. Regardless, it shall not be an error to +specify a +.IR count +to these commands, and any specified +.IR count +shall be ignored. +.RE +.IP "\fImotion\fR" 8 +An optional trailing argument used by the +.BR ! , +.BR < , +.BR > , +.BR c , +.BR d , +and +.BR y +commands, which is used to indicate the region of text that shall be +affected by the command. The motion can be either one of the command +characters repeated or one of several other +.IR vi +commands (listed in the following table). Each of the applicable +commands specifies the region of text matched by repeating the command; +each command that can be used as a motion command specifies the region +of text it affects. +.RS 8 +.P +Commands that take +.IR motion +arguments operate on either lines or characters, depending on the +circumstances. When operating on lines, all lines that fall partially +or wholly within the text region specified for the command shall be +affected. When operating on characters, only the exact characters in +the specified text region shall be affected. Each motion command +specifies this individually. +.P +When commands that may be motion commands are not used as motion +commands, they shall set the current position to the current line and +column as specified. +.P +The following commands shall be valid cursor motion commands: +.sp +.RS 4 +.nf +\fB + ( - j H + ) $ k L + [[ % l M +-H ]] _ n N +-N { ; t T +-P } ? w W + ^ b B + + e E + | f F + / h G +.fi \fR +.P +.RE +.P +Any +.IR count +that is specified to a command that has an associated motion command +shall be applied to the motion command. If a +.IR count +is applied to both the command and its associated motion command, the +effect shall be multiplicative. +.RE +.P +The following symbols are used in this section to specify locations +in the edit buffer: +.IP "\fIcurrent\ character\fP" 8 +.br +The character that is currently indicated by the cursor. +.IP "\fIend\ of\ a\ line\fP" 8 +.br +The point located between the last non-\c + +(if any) and the terminating + +of a line. For an empty line, this location coincides with the +beginning of the line. +.IP "\fIend\ of\ the\ edit\ buffer\fP" 8 +.br +The location corresponding to the end of the last line in the edit +buffer. +.P +The following symbols are used in this section to specify command +actions: +.IP "\fIbigword\fP" 8 +In the POSIX locale, +.IR vi +shall recognize four kinds of +.IR bigwords : +.RS 8 +.IP " 1." 4 +A maximal sequence of non-\c + +characters preceded and followed by + +characters or the beginning or end of a line or the edit buffer +.IP " 2." 4 +One or more sequential blank lines +.IP " 3." 4 +The first character in the edit buffer +.IP " 4." 4 +The last non-\c + +in the edit buffer +.RE +.IP "\fIword\fP" 8 +In the POSIX locale, +.IR vi +shall recognize five kinds of words: +.RS 8 +.IP " 1." 4 +A maximal sequence of letters, digits, and underscores, delimited at +both ends by: +.RS 4 +.IP -- 4 +Characters other than letters, digits, or underscores +.IP -- 4 +The beginning or end of a line +.IP -- 4 +The beginning or end of the edit buffer +.RE +.IP " 2." 4 +A maximal sequence of characters other than letters, digits, underscores, or + +characters, delimited at both ends by: +.RS 4 +.IP -- 4 +A letter, digit, underscore +.IP -- 4 + +characters +.IP -- 4 +The beginning or end of a line +.IP -- 4 +The beginning or end of the edit buffer +.RE +.IP " 3." 4 +One or more sequential blank lines +.IP " 4." 4 +The first character in the edit buffer +.IP " 5." 4 +The last non-\c + +in the edit buffer +.RE +.IP "\fIsection\ boundary\fR" 8 +.br +A +.IR "section boundary" +is one of the following: +.RS 8 +.IP " 1." 4 +A line whose first character is a + +.IP " 2." 4 +A line whose first character is an open curly brace (\c +.BR '{' ) +.IP " 3." 4 +A line whose first character is a + +and whose second and third characters match a two-character pair in the +.BR sections +edit option (see +.IR ed ) +.IP " 4." 4 +A line whose first character is a + +and whose only other character matches the first character of a +two-character pair in the +.BR sections +edit option, where the second character of the two-character pair is a + +.IP " 5." 4 +The first line of the edit buffer +.IP " 6." 4 +The last line of the edit buffer if the last line of the edit buffer is +empty or if it is a +.BR ]] +or +.BR } +command; otherwise, the last non-\c + +of the last line of the edit buffer +.RE +.IP "\fIparagraph\ boundary\fR" 8 +.br +A +.IR "paragraph boundary" +is one of the following: +.RS 8 +.IP " 1." 4 +A section boundary +.IP " 2." 4 +A line whose first character is a + +and whose second and third characters match a two-character pair in the +.BR paragraphs +edit option (see +.IR ed ) +.IP " 3." 4 +A line whose first character is a + +and whose only other character matches the first character of a +two-character pair in the +.IR paragraphs +edit option, where the second character of the two-character pair is a + +.IP " 4." 4 +One or more sequential blank lines +.RE +.IP "\fIremembered\ search\ direction\fR" 8 +.br +See the description of \fIremembered search direction\fP in +.IR ed . +.IP "\fIsentence\ boundary\fR" 8 +.br +A +.IR "sentence boundary" +is one of the following: +.RS 8 +.IP " 1." 4 +A paragraph boundary +.IP " 2." 4 +The first non-\c + +that occurs after a paragraph boundary +.IP " 3." 4 +The first non-\c + +that occurs after a + +(\c +.BR '.' ), + +(\c +.BR '!' ), +or + +(\c +.BR '?' ), +followed by two + +characters or the end of a line; any number of closing parenthesis (\c +.BR ')' ), +closing brackets (\c +.BR ']' ), +double-quote (\c +.BR '\&"' ), +or single-quote (\c +) +characters can appear between the punctuation mark and the two + +characters or end-of-line +.RE +.P +In the remainder of the description of the +.IR vi +utility, the term ``buffer line'' refers to a line in the edit buffer +and the term ``display line'' refers to the line or lines on the +display screen used to display one buffer line. The term ``current +line'' refers to a specific ``buffer line''. +.P +If there are display lines on the screen for which there are no +corresponding buffer lines because they correspond to lines that would +be after the end of the file, they shall be displayed as a single + +(\c +.BR '~' ) +character, plus the terminating +. +.P +The last line of the screen shall be used to report errors or display +informational messages. It shall also be used to display the input for +``line-oriented commands'' (\c +.BR / , +.BR ? , +.BR : , +and +.BR ! ). +When a line-oriented command is executed, the editor shall enter text +input mode on the last line on the screen, using the respective command +characters as prompt characters. (In the case of the +.BR ! +command, the associated motion shall be entered by the user before the +editor enters text input mode.) The line entered by the user shall be +terminated by a +, +a non-\c +\(hyV-escaped +, +or unescaped +. +It is unspecified if more characters than require a display width minus +one column number of screen columns can be entered. +.P +If any command is executed that overwrites a portion of the screen +other than the last line of the screen (for example, the +.IR ex +.BR suspend +or +.BR ! +commands), other than the +.IR ex +.BR shell +command, the user shall be prompted for a character before the screen +is refreshed and the edit session continued. +.P + +characters shall take up the number of columns on the screen set by the +.BR tabstop +edit option (see +.IR ed ), +unless there are less than that number of columns before the display +margin that will cause the displayed line to be folded; in this case, +they shall only take up the number of columns up to that boundary. +.P +The cursor shall be placed on the current line and relative to the +current column as specified by each command described in the following +sections. +.P +In open mode, if the current line is not already displayed, then it +shall be displayed. +.P +In visual mode, if the current line is not displayed, then the lines +that are displayed shall be expanded, scrolled, or redrawn to cause an +unspecified portion of the current line to be displayed. If the screen +is redrawn, no more than the number of display lines specified by the +value of the +.BR window +edit option shall be displayed (unless the current line cannot be +completely displayed in the number of display lines specified by the +.BR window +edit option) and the current line shall be positioned as close to the +center of the displayed lines as possible (within the constraints +imposed by the distance of the line from the beginning or end of the +edit buffer). If the current line is before the first line in the +display and the screen is scrolled, an unspecified portion of the +current line shall be placed on the first line of the display. If the +current line is after the last line in the display and the screen is +scrolled, an unspecified portion of the current line shall be placed on +the last line of the display. +.P +In visual mode, if a line from the edit buffer (other than the current +line) does not entirely fit into the lines at the bottom of the display +that are available for its presentation, the editor may choose not to +display any portion of the line. The lines of the display that do not +contain text from the edit buffer for this reason shall each consist of +a single +.BR '@' +character. +.P +In visual mode, the editor may choose for unspecified reasons to not +update lines in the display to correspond to the underlying edit buffer +text. The lines of the display that do not correctly correspond to text +from the edit buffer for this reason shall consist of a single +.BR '@' +character (plus the terminating +), +and the +\(hyR +command shall cause the editor to update the screen to correctly +represent the edit buffer. +.P +Open and visual mode commands that set the current column set it to a +column position in the display, and not a character position in the +line. In this case, however, the column position in the display shall +be calculated for an infinite width display; for example, the column +related to a character that is part of a line that has been folded onto +additional screen lines will be offset from the display line column +where the buffer line begins, not from the beginning of a particular +display line. +.P +The display cursor column in the display is based on the value of the +current column, as follows, with each rule applied in turn: +.IP " 1." 4 +If the current column is after the last display line column used by the +displayed line, the display cursor column shall be set to the last +display line column occupied by the last non-\c + +in the current line; otherwise, the display cursor column shall be set +to the current column. +.IP " 2." 4 +If the character of which some portion is displayed in the display line +column specified by the display cursor column requires more than a +single display line column: +.RS 4 +.IP " a." 4 +If in text input mode, the display cursor column shall be adjusted to +the first display line column in which any portion of that character is +displayed. +.IP " b." 4 +Otherwise, the display cursor column shall be adjusted to the last +display line column in which any portion of that character is +displayed. +.RE +.P +The current column shall not be changed by these adjustments to the +display cursor column. +.P +If an error occurs during the parsing or execution of a +.IR vi +command: +.IP " *" 4 +The terminal shall be alerted. Execution of the +.IR vi +command shall stop, and the cursor (for example, the current line and +column) shall not be further modified. +.IP " *" 4 +Unless otherwise specified by the following command sections, it is +unspecified whether an informational message shall be displayed. +.IP " *" 4 +Any partially entered +.IR vi +command shall be discarded. +.IP " *" 4 +If the +.IR vi +command resulted from a +.BR map +expansion, all characters from that +.BR map +expansion shall be discarded, except as otherwise specified by the +.BR map +command (see +.IR ed ). +.IP " *" 4 +If the +.IR vi +command resulted from the execution of a buffer, no further commands +caused by the execution of the buffer shall be executed. +.SS "Page Backwards" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -B +.fi \fR +.P +.RE +.RE +.P +If in open mode, the +\(hyB +command shall behave identically to the +.BR z +command. Otherwise, if the current line is the first line of the edit +buffer, it shall be an error. +.P +If the +.BR window +edit option is less than 3, display a screen where the last line of the +display shall be some portion of: +.sp +.RS 4 +.nf +\fB +(\fIcurrent first line\fR) \(mi1 +.fi \fR +.P +.RE +.P +otherwise, display a screen where the first line of the display shall +be some portion of: +.sp +.RS 4 +.nf +\fB +(\fIcurrent first line\fR) \(mi \fIcount\fR x ((window edit option) \(mi2) +.fi \fR +.P +.RE +.P +If this calculation would result in a line that is before the first +line of the edit buffer, the first line of the display shall display +some portion of the first line of the edit buffer. +.P +.IR "Current line" : +If no lines from the previous display remain on the screen, set to the +last line of the display; otherwise, set to (\c +.IR line +\(mi the number of new lines displayed on this screen). +.P +.IR "Current column" : +Set to non-\c +. +.SS "Scroll Forward" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -D +.fi \fR +.P +.RE +.RE +.P +If the current line is the last line of the edit buffer, it shall be an +error. +.P +If no +.IR count +is specified, +.IR count +shall default to the +.IR count +associated with the previous +\(hyD +or +\(hyU +command. If there was no previous +\(hyD +or +\(hyU +command, +.IR count +shall default to the value of the +.BR scroll +edit option. +.P +If in open mode, write lines starting with the line after the current +line, until +.IR count +lines or the last line of the file have been written. +.P +.IR "Current line" : +If the current line + +.IR count +is past the last line of the edit buffer, set to the last line of the +edit buffer; otherwise, set to the current line + +.IR count . +.P +.IR "Current column" : +Set to non-\c +. +.SS "Scroll Forward by Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -E +.fi \fR +.P +.RE +.RE +.P +Display the line count lines after the last line currently displayed. +.P +If the last line of the edit buffer is displayed, it shall be an error. +If there is no line +.IR count +lines after the last line currently displayed, the last line of the +display shall display some portion of the last line of the edit +buffer. +.P +.IR "Current line" : +Unchanged if the previous current character is displayed; otherwise, +set to the first line displayed. +.P +.IR "Current column" : +Unchanged. +.SS "Page Forward" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -F +.fi \fR +.P +.RE +.RE +.P +If in open mode, the +\(hyF +command shall behave identically to the +.BR z +command. Otherwise, if the current line is the last line of the edit +buffer, it shall be an error. +.P +If the +.BR window +edit option is less than 3, display a screen where the first line of +the display shall be some portion of: +.sp +.RS 4 +.nf +\fB +(\fIcurrent last line\fR) +1 +.fi \fR +.P +.RE +.P +otherwise, display a screen where the first line of the display shall +be some portion of: +.sp +.RS 4 +.nf +\fB +(\fIcurrent first line\fR) + \fIcount\fR x ((window edit option) \(mi2) +.fi \fR +.P +.RE +.P +If this calculation would result in a line that is after the last line +of the edit buffer, the last line of the display shall display some +portion of the last line of the edit buffer. +.P +.IR "Current line" : +If no lines from the previous display remain on the screen, set to the +first line of the display; otherwise, set to (\c +.IR line ++ the number of new lines displayed on this screen). +.P +.IR "Current column" : +Set to non-\c +. +.SS "Display Information" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-G +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +.BR file +command. +.SS "Move Cursor Backwards" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -H +.br +\fB[\fIcount\fB]\fR h +.br +the current \fIerase\fP character (see stty) +.fi \fR +.P +.RE +.RE +.P +If there are no characters before the current character on the current +line, it shall be an error. If there are less than +.IR count +previous characters on the current line, +.IR count +shall be adjusted to the number of previous characters on the line. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the character before the starting cursor +up to and including the +.IR count th +character before the starting cursor. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to (\c +.IR column +\(mi the number of columns occupied by +.IR count +characters ending with the previous current column). +.SS "Move Down" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR +.br +\fB[\fIcount\fB]\fR -J +.br +\fB[\fIcount\fB]\fR -M +.br +\fB[\fIcount\fB]\fR -N +.br +\fB[\fIcount\fB]\fR j +.br +\fB[\fIcount\fB]\fR +.br +\fB[\fIcount\fB]\fR + +.fi \fR +.P +.RE +.RE +.P +If there are less than +.IR count +lines after the current line in the edit buffer, it shall be an error. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall include the starting line and the next +.IR count +\(mi 1 lines. +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to +.IR "current line" + +.IR count . +.P +.IR "Current column" : +Set to non-\c + +for the +, +\(hyM, +and +.BR + +commands; otherwise, unchanged. +.SS "Clear and Redisplay" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-L +.fi \fR +.P +.RE +.RE +.P +If in open mode, clear the screen and redisplay the current line. +Otherwise, clear and redisplay the screen. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Move Up" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -P +.br +\fB[\fIcount\fB]\fR k +.br +\fB[\fIcount\fB]\fR \(mi +.fi \fR +.P +.RE +.RE +.P +If there are less than +.IR count +lines before the current line in the edit buffer, it shall be an +error. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall include the starting line and the previous +.IR count +lines. +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to +.IR "current line" +\(mi +.IR count . +.P +.IR "Current column" : +Set to non-\c + +for the +.BR \(mi +command; otherwise, unchanged. +.SS "Redraw Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-R +.fi \fR +.P +.RE +.RE +.P +If any lines have been deleted from the display screen and flagged as +deleted on the terminal using the +.BR @ +convention (see the beginning of the EXTENDED DESCRIPTION section), +they shall be redisplayed to match the contents of the edit buffer. +.P +It is unspecified whether lines flagged with +.BR @ +because they do not fit on the terminal display shall be affected. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Scroll Backward" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -U +.fi \fR +.P +.RE +.RE +.P +If the current line is the first line of the edit buffer, it shall be +an error. +.P +If no +.IR count +is specified, +.IR count +shall default to the +.IR count +associated with the previous +\(hyD +or +\(hyU +command. If there was no previous +\(hyD +or +\(hyU +command, +.IR count +shall default to the value of the +.BR scroll +edit option. +.P +.IR "Current line" : +If +.IR count +is greater than the current line, set to 1; otherwise, set to the +current line \(mi +.IR count . +.P +.IR "Current column" : +Set to non-\c +. +.SS "Scroll Backward by Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -Y +.fi \fR +.P +.RE +.RE +.P +Display the line +.IR count +lines before the first line currently displayed. +.P +If the current line is the first line of the edit buffer, it shall be +an error. If this calculation would result in a line that is before the +first line of the edit buffer, the first line of the display shall +display some portion of the first line of the edit buffer. +.P +.IR "Current line" : +Unchanged if the previous current character is displayed; otherwise, +set to the first line displayed. +.P +.IR "Current column" : +Unchanged. +.SS "Edit the Alternate File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-^ +.fi \fR +.P +.RE +.RE +This command shall be equivalent to the +.IR ex +.BR edit +command, with the alternate pathname as its argument. +.SS "Terminate Command or Input Mode" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.fi \fR +.P +.RE +.RE +.P +If a partial +.IR vi +command (as defined by at least one, non-\c +.IR count +character) has been entered, discard the +.IR count +and the command character(s). +.P +Otherwise, if no command characters have been entered, and the + +was the result of a map expansion, the terminal shall be alerted and +the + +character shall be discarded, but it shall not be an error. +.P +Otherwise, it shall be an error. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Search for tagstring" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-] +.fi \fR +.P +.RE +.RE +.P +If the current character is not a word or +, +it shall be an error. +.P +This command shall be equivalent to the +.IR ex +.BR tag +command, with the argument to that command defined as follows. +.P +If the current character is a +: +.IP " 1." 4 +Skip all + +characters after the cursor up to the end of the line. +.IP " 2." 4 +If the end of the line is reached, it shall be an error. +.P +Then, the argument to the +.IR ex +.BR tag +command shall be the current character and all subsequent characters, +up to the first non-word character or the end of the line. +.SS "Move Cursor Forward" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR +.br +\fB[\fIcount\fB]\fR l\fR (ell)\fR +.fi \fR +.P +.RE +.RE +.P +If there are less than +.IR count +non-\c + +characters after the cursor on the current line, +.IR count +shall be adjusted to the number of non-\c + +characters after the cursor on the line. +.P +If used as a motion command: +.IP " 1." 4 +If the current or +.IR count th +character after the cursor is the last non-\c + +in the line, the text region shall be comprised of the current +character up to and including the last non-\c + +in the line. Otherwise, the text region shall be from the current +character up to, but not including, the +.IR count th +character after the cursor. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +If there are no non-\c + +characters after the current character on the current line, it shall be +an error. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column that displays any portion of the +.IR count th +character after the current character. +.SS "Replace Text with Results from Shell Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ! \fImotion shell-commands\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR ! +command repeated: +.IP " 1." 4 +If the edit buffer is empty and no +.IR count +was supplied, the command shall be the equivalent of the +.IR ex +.BR :read +.BR ! +command, with the text input, and no text shall be copied to any +buffer. +.IP " 2." 4 +Otherwise: +.RS 4 +.IP " a." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " b." 4 +The text region shall be from the current line up to and including the +next +.IR count +\(mi1 lines. +.RE +.P +Otherwise, the text region shall be the lines in which any character of +the text region specified by the motion command appear. +.P +Any text copied to a buffer shall be in line mode. +.P +This command shall be equivalent to the +.IR ex +.BR ! +command for the specified lines. +.SS "Move Cursor to End-of-Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR $ +.fi \fR +.P +.RE +.RE +.P +It shall be an error if there are less than (\c +.IR count +\(mi1) lines after the current line in the edit buffer. +.P +If used as a motion command: +.IP " 1." 4 +If +.IR count +is 1: +.RS 4 +.IP " a." 4 +It shall be an error if the line is empty. +.IP " b." 4 +Otherwise, the text region shall consist of all characters from the +starting cursor to the last non-\c + +in the line, inclusive, and any text copied to a buffer shall be in +character mode. +.RE +.IP " 2." 4 +Otherwise, if the starting cursor position is at or before the first +non-\c + +in the line, the text region shall consist of the current and the next +.IR count +\(mi1 lines, and any text saved to a buffer shall be in line mode. +.IP " 3." 4 +Otherwise, the text region shall consist of all characters from the +starting cursor to the last non-\c + +in the line that is +.IR count +\(mi1 lines forward from the current line, and any text copied to a +buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the +.IR "current line" ++ +.IR count \(mi1. +.P +.IR "Current column" : +The current column is set to the last display line column of the last +non-\c + +in the line, or column position 1 if the line is empty. +.P +The current column shall be adjusted to be on the last display line +column of the last non-\c + +of the current line as subsequent commands change the current line, +until a command changes the current column. +.SS "Move to Matching Character" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +% +.fi \fR +.P +.RE +.RE +.P +If the character at the current position is not a parenthesis, bracket, +or curly brace, search forward in the line to the first one of those +characters. If no such character is found, it shall be an error. +.P +The matching character shall be the parenthesis, bracket, or curly +brace matching the parenthesis, bracket, or curly brace, respectively, +that was at the current position or that was found on the current +line. +.P +Matching shall be determined as follows, for an open parenthesis: +.IP " 1." 4 +Set a counter to 1. +.IP " 2." 4 +Search forwards until a parenthesis is found or the end of the edit +buffer is reached. +.IP " 3." 4 +If the end of the edit buffer is reached, it shall be an error. +.IP " 4." 4 +If an open parenthesis is found, increment the counter by 1. +.IP " 5." 4 +If a close parenthesis is found, decrement the counter by 1. +.IP " 6." 4 +If the counter is zero, the current character is the matching +character. +.P +Matching for a close parenthesis shall be equivalent, except that the +search shall be backwards, from the starting character to the beginning +of the buffer, a close parenthesis shall increment the counter by 1, +and an open parenthesis shall decrement the counter by 1. +.P +Matching for brackets and curly braces shall be equivalent, except that +searching shall be done for open and close brackets or open and close +curly braces. It is implementation-defined whether other characters +are searched for and matched as well. +.P +If used as a motion command: +.IP " 1." 4 +If the matching cursor was after the starting cursor in the edit +buffer, and the starting cursor position was at or before the first +non-\c + +non-\c + +in the starting line, and the matching cursor position was at or after +the last non-\c + +non-\c + +in the matching line, the text region shall consist of the current line +to the matching line, inclusive, and any text copied to a buffer shall +be in line mode. +.IP " 2." 4 +If the matching cursor was before the starting cursor in the edit +buffer, and the starting cursor position was at or after the last +non-\c + +non-\c + +in the starting line, and the matching cursor position was at or before +the first non-\c + +non-\c + +in the matching line, the text region shall consist of the current line +to the matching line, inclusive, and any text copied to a buffer shall +be in line mode. +.IP " 3." 4 +Otherwise, the text region shall consist of the starting character to +the matching character, inclusive, and any text copied to a buffer +shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line where the matching character is located. +.P +.IR "Current column" : +Set to the last column where any portion of the matching character is +displayed. +.SS "Repeat Substitution" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +& +.fi \fR +.P +.RE +.RE +.P +Repeat the previous substitution command. This command shall be +equivalent to the +.IR ex +.BR & +command with the current line as its addresses, and without +.IR options , +.IR count , +or +.IR flags . +.SS "Return to Previous Context at Beginning of Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&' \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if there is no line in the edit buffer marked by +.IR character . +.P +If used as a motion command: +.IP " 1." 4 +If the starting cursor is after the marked cursor, then the locations +of the starting cursor and the marked cursor in the edit buffer shall +be logically swapped. +.IP " 2." 4 +The text region shall consist of the starting line up to and including +the marked line, and any text copied to a buffer shall be in line +mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line referenced by the mark. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Return to Previous Context" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&` \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if the marked line is no longer in the edit +buffer. If the marked line no longer contains a character in the saved +numbered character position, it shall be as if the marked position is +the first non-\c +. +.P +If used as a motion command: +.IP " 1." 4 +It shall be an error if the marked cursor references the same character +in the edit buffer as the starting cursor. +.IP " 2." 4 +If the starting cursor is after the marked cursor, then the locations +of the starting cursor and the marked cursor in the edit buffer shall +be logically swapped. +.IP " 3." 4 +If the starting line is empty or the starting cursor is at or before +the first non-\c + +non-\c + +of the starting line, and the marked cursor line is empty or the marked +cursor references the first character of the marked cursor line, the +text region shall consist of all lines containing characters from the +starting cursor to the line before the marked cursor line, inclusive, +and any text copied to a buffer shall be in line mode. +.IP " 4." 4 +Otherwise, if the marked cursor line is empty or the marked cursor +references a character at or before the first non-\c + +non-\c + +of the marked cursor line, the region of text shall be from the +starting cursor to the last non-\c + +of the line before the marked cursor line, inclusive, and any text +copied to a buffer shall be in character mode. +.IP " 5." 4 +Otherwise, the region of text shall be from the starting cursor +(inclusive), to the marked cursor (exclusive), and any text copied to a +buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line referenced by the mark. +.P +.IR "Current column" : +Set to the last column in which any portion of the character referenced +by the mark is displayed. +.SS "Return to Previous Section" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR [[ +.fi \fR +.P +.RE +.RE +.P +Move the cursor backward through the edit buffer to the first character +of the previous section boundary, +.IR count +times. +.P +If used as a motion command: +.IP " 1." 4 +If the starting cursor was at the first character of the starting line +or the starting line was empty, and the first character of the boundary +was the first character of the boundary line, the text region shall +consist of the current line up to and including the line where the +.IR count th +next boundary starts, and any text copied to a buffer shall be in line +mode. +.IP " 2." 4 +If the boundary was the last line of the edit buffer or the last non-\c + +of the last line of the edit buffer, the text region shall consist of +the last character in the edit buffer up to and including the starting +character, and any text saved to a buffer shall be in character mode. +.IP " 3." 4 +Otherwise, the text region shall consist of the starting character up +to but not including the first character in the +.IR count th +next boundary, and any text copied to a buffer shall be in character +mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line where the +.IR count th +next boundary in the edit buffer starts. +.P +.IR "Current column" : +Set to the last column in which any portion of the first character of +the +.IR count th +next boundary is displayed, or column position 1 if the line is empty. +.SS "Move to Next Section" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ]] +.fi \fR +.P +.RE +.RE +.P +Move the cursor forward through the edit buffer to the first character +of the next section boundary, +.IR count +times. +.P +If used as a motion command: +.IP " 1." 4 +If the starting cursor was at the first character of the starting line +or the starting line was empty, and the first character of the boundary +was the first character of the boundary line, the text region shall +consist of the current line up to and including the line where the +.IR count th +previous boundary starts, and any text copied to a buffer shall be in +line mode. +.IP " 2." 4 +If the boundary was the first line of the edit buffer, the text region +shall consist of the first character in the edit buffer up to but not +including the starting character, and any text copied to a buffer shall +be in character mode. +.IP " 3." 4 +Otherwise, the text region shall consist of the first character in the +.IR count th +previous section boundary up to but not including the starting +character, and any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line where the +.IR count th +previous boundary in the edit buffer starts. +.P +.IR "Current column" : +Set to the last column in which any portion of the first character of +the +.IR count th +previous boundary is displayed, or column position 1 if the line is +empty. +.SS "Move to First Non- Position on Current Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&^ +.fi \fR +.P +.RE +.RE +If used as a motion command: +.IP " 1." 4 +If the line has no non-\c + +non-\c + +characters, or if the cursor is at the first non-\c + +non-\c + +of the line, it shall be an error. +.IP " 2." 4 +If the cursor is before the first non-\c + +non-\c + +of the line, the text region shall be comprised of the current +character, up to, but not including, the first non-\c + +non-\c + +of the line. +.IP " 3." 4 +If the cursor is after the first non-\c + +non-\c + +of the line, the text region shall be from the character before the +starting cursor up to and including the first non-\c + +non-\c + +of the line. +.IP " 4." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Current and Line Above" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR _ +.fi \fR +.P +.RE +.RE +.P +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.P +If used as a motion command: +.IP " 1." 4 +If +.IR count +is less than 2, the text region shall be the current line. +.IP " 2." 4 +Otherwise, the text region shall include the starting line and the next +.IR count +\(mi1 lines. +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to current line + +.IR count +\(mi1. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Move Back to Beginning of Sentence" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ( +.fi \fR +.P +.RE +.RE +.P +Move backward to the beginning of a sentence. This command shall be +equivalent to the +.BR [[ +command, with the exception that sentence boundaries shall be used +instead of section boundaries. +.SS "Move Forward to Beginning of Sentence" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ) +.fi \fR +.P +.RE +.RE +.P +Move forward to the beginning of a sentence. This command shall be +equivalent to the +.BR ]] +command, with the exception that sentence boundaries shall be used +instead of section boundaries. +.SS "Move Back to Preceding Paragraph" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR { +.fi \fR +.P +.RE +.RE +.P +Move back to the beginning of the preceding paragraph. This command +shall be equivalent to the +.BR [[ +command, with the exception that paragraph boundaries shall be used +instead of section boundaries. +.SS "Move Forward to Next Paragraph" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR } +.fi \fR +.P +.RE +.RE +.P +Move forward to the beginning of the next paragraph. This command +shall be equivalent to the +.BR ]] +command, with the exception that paragraph boundaries shall be used +instead of section boundaries. +.SS "Move to Specific Column Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR | +.fi \fR +.P +.RE +.RE +.P +For the purposes of this command, lines that are too long for the +current display and that have been folded shall be treated as having a +single, 1\(mibased, number of columns. +.P +If there are less than +.IR count +columns in which characters from the current line are displayed on the +screen, +.IR count +shall be adjusted to be the last column in which any portion of the +line is displayed on the screen. +.P +If used as a motion command: +.IP " 1." 4 +If the line is empty, or the cursor character is the same as the +character on the +.IR count th +column of the line, it shall be an error. +.IP " 2." 4 +If the cursor is before the +.IR count th +column of the line, the text region shall be comprised of the current +character, up to but not including the character on the +.IR count th +column of the line. +.IP " 3." 4 +If the cursor is after the +.IR count th +column of the line, the text region shall be from the character before +the starting cursor up to and including the character on the +.IR count th +column of the line. +.IP " 4." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the character that is +displayed in the +.IR count +column of the line is displayed. +.SS "Reverse Find Character" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR , +.fi \fR +.P +.RE +.RE +.P +If the last +.BR F , +.BR f , +.BR T , +or +.BR t +command was +.BR F , +.BR f , +.BR T , +or +.BR t , +this command shall be equivalent to an +.BR f , +.BR F , +.BR t , +or +.BR T +command, respectively, with the specified +.IR count +and the same search character. +.P +If there was no previous +.BR F , +.BR f , +.BR T , +or +.BR t +command, it shall be an error. +.SS "Repeat" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR . +.fi \fR +.P +.RE +.RE +.P +Repeat the last +.BR ! , +.BR < , +.BR > , +.BR A , +.BR C , +.BR D , +.BR I , +.BR J , +.BR O , +.BR P , +.BR R , +.BR S , +.BR X , +.BR Y , +.BR a , +.BR c , +.BR d , +.BR i , +.BR o , +.BR p , +.BR r , +.BR s , +.BR x , +.BR y , +or +.BR ~ +command. It shall be an error if none of these commands have been +executed. Commands (other than commands that enter text input mode) +executed as a result of map expansions, shall not change the value of +the last repeatable command. +.P +Repeated commands with associated motion commands shall repeat the +motion command as well; however, any specified +.IR count +shall replace the +.IR count (s) +that were originally specified to the repeated command or its +associated motion command. +.P +If the motion component of the repeated command is +.BR f , +.BR F , +.BR t , +or +.BR T , +the repeated command shall not set the remembered search character for +the +.BR ; +and +.BR , +commands. +.P +If the repeated command is +.BR p +or +.BR P , +and the buffer associated with that command was a numeric buffer named +with a number less than 9, the buffer associated with the repeated +command shall be set to be the buffer named by the name of the previous +buffer logically incremented by 1. +.P +If the repeated character is a text input command, the input text +associated with that command is repeated literally: +.IP " *" 4 +Input characters are neither macro or abbreviation-expanded. +.IP " *" 4 +Input characters are not interpreted in any special way with the +exception that +, +, +and +\(hyT +behave as described in +.IR "Input Mode Commands in vi". +.P +.IR "Current line" : +Set as described for the repeated command. +.P +.IR "Current column" : +Set as described for the repeated command. +.SS "Find Regular Expression" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +/ +.fi \fR +.P +.RE +.RE +.P +If the input line contains no non-\c + +characters, it shall be equivalent to a line containing only the +last regular expression encountered. The enhanced regular expressions +supported by +.IR vi +are described in +.IR "Regular Expressions in ex". +.P +Otherwise, the line shall be interpreted as one or more regular +expressions, optionally followed by an address offset or a +.IR vi +.BR z +command. +.P +If the regular expression is not the last regular expression on the +line, or if a line offset or +.BR z +command is specified, the regular expression shall be terminated by an +unescaped +.BR '/' +character, which shall not be used as part of the regular expression. +If the regular expression is not the first regular expression on the +line, it shall be preceded by zero or more + +characters, a +, +zero or more + +characters, and a leading +.BR '/' +character, which shall not be interpreted as part of the regular +expression. It shall be an error to precede any regular expression with +any characters other than these. +.P +Each search shall begin from the character after the first character of +the last match (or, if it is the first search, after the cursor). If +the +.BR wrapscan +edit option is set, the search shall continue to the character before +the starting cursor character; otherwise, to the end of the edit +buffer. It shall be an error if any search fails to find a match, and +an informational message to this effect shall be displayed. +.P +An optional address offset (see +.IR "Addressing in ex") +can be specified after the last regular expression by including a +trailing +.BR '/' +character after the regular expression and specifying the address +offset. This offset will be from the line containing the match for the +last regular expression specified. It shall be an error if the line +offset would indicate a line address less than 1 or greater than the +last line in the edit buffer. An address offset of zero shall be +supported. It shall be an error to follow the address offset with any +other characters than + +characters. +.P +If not used as a motion command, an optional +.BR z +command (see +.IR "Redraw Window") +can be specified after the last regular expression by including a +trailing +.BR '/' +character after the regular expression, zero or more + +characters, a +.BR 'z' , +zero or more + +characters, an optional new +.BR window +edit option value, zero or more + +characters, and a location character. The effect shall be as if the +.BR z +command was executed after the +.BR / +command. It shall be an error to follow the +.BR z +command with any other characters than + +characters. +.P +The remembered search direction shall be set to forward. +.P +If used as a motion command: +.IP " 1." 4 +It shall be an error if the last match references the same character in +the edit buffer as the starting cursor. +.IP " 2." 4 +If any address offset is specified, the last match shall be adjusted by +the specified offset as described previously. +.IP " 3." 4 +If the starting cursor is after the last match, then the locations of +the starting cursor and the last match in the edit buffer shall be +logically swapped. +.IP " 4." 4 +If any address offset is specified, the text region shall consist of +all lines containing characters from the starting cursor to the last +match line, inclusive, and any text copied to a buffer shall be in line +mode. +.IP " 5." 4 +Otherwise, if the starting line is empty or the starting cursor is at +or before the first non-\c + +non-\c + +of the starting line, and the last match line is empty or the last +match starts at the first character of the last match line, the text +region shall consist of all lines containing characters from the +starting cursor to the line before the last match line, inclusive, and +any text copied to a buffer shall be in line mode. +.IP " 6." 4 +Otherwise, if the last match line is empty or the last match begins at +a character at or before the first non-\c + +non-\c + +of the last match line, the region of text shall be from the current +cursor to the last non-\c + +of the line before the last match line, inclusive, and any text copied +to a buffer shall be in character mode. +.IP " 7." 4 +Otherwise, the region of text shall be from the current cursor +(inclusive), to the first character of the last match (exclusive), and +any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +If a match is found, set to the last matched line plus the address +offset, if any; otherwise, unchanged. +.P +.IR "Current column" : +Set to the last column on which any portion of the first character in +the last matched string is displayed, if a match is found; otherwise, +unchanged. +.SS "Move to First Character in Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +0 \fR(zero)\fR +.fi \fR +.P +.RE +.RE +.P +Move to the first character on the current line. The character +.BR '0' +shall not be interpreted as a command if it is immediately preceded by +a digit. +.P +If used as a motion command: +.IP " 1." 4 +If the cursor character is the first character in the line, it shall be +an error. +.IP " 2." 4 +The text region shall be from the character before the cursor character +up to and including the first character in the line. +.IP " 3." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +The last column in which any portion of the first character in the line +is displayed, or if the line is empty, unchanged. +.SS "Execute an ex Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +: +.fi \fR +.P +.RE +.RE +.P +Execute one or more +.IR ex +commands. +.P +If any portion of the screen other than the last line of the screen was +overwritten by any +.IR ex +command (except +.BR shell ), +.IR vi +shall display a message indicating that it is waiting for an input from +the user, and shall then read a character. This action may also be +taken for other, unspecified reasons. +.P +If the next character entered is a +.BR ':' , +another +.IR ex +command shall be accepted and executed. Any other character shall cause +the screen to be refreshed and +.IR vi +shall return to command mode. +.P +.IR "Current line" : +As specified for the +.IR ex +command. +.P +.IR "Current column" : +As specified for the +.IR ex +command. +.SS "Repeat Find" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ; +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the last +.BR F , +.BR f , +.BR T , +or +.BR t +command, with the specified +.IR count , +and with the same search character used for the last +.BR F , +.BR f , +.BR T , +or +.BR t +command. If there was no previous +.BR F , +.BR f , +.BR T , +or +.BR t +command, it shall be an error. +.SS "Shift Left" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR < \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR < +command repeated: +.IP " 1." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 2." 4 +The text region shall be from the current line, up to and including the +next +.IR count +\(mi1 lines. +.P +Shift any line in the text region specified by the +.IR count +and motion command one shiftwidth (see the +.IR ex +.BR shiftwidth +option) toward the start of the line, as described by the +.IR ex +.BR < +command. The unshifted lines shall be copied to the unnamed buffer in +line mode. +.P +.IR "Current line" : +If the motion was from the current cursor position toward the end of +the edit buffer, unchanged. Otherwise, set to the first line in the +edit buffer that is part of the text region specified by the motion +command. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Shift Right" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR > \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR > +command repeated: +.IP " 1." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 2." 4 +The text region shall be from the current line, up to and including the +next +.IR count +\(mi1 lines. +.P +Shift any line with characters in the text region specified by the +.IR count +and motion command one shiftwidth (see the +.IR ex +.BR shiftwidth +option) away from the start of the line, as described by the +.IR ex +.BR > +command. The unshifted lines shall be copied into the unnamed buffer in +line mode. +.P +.IR "Current line" : +If the motion was from the current cursor position toward the end of +the edit buffer, unchanged. Otherwise, set to the first line in the +edit buffer that is part of the text region specified by the +motion command. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Scan Backwards for Regular Expression" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +? +.fi \fR +.P +.RE +.RE +.P +Scan backwards; the +.BR ? +command shall be equivalent to the +.BR / +command (see +.IR "Find Regular Expression") +with the following exceptions: +.IP " 1." 4 +The input prompt shall be a +.BR '?' . +.IP " 2." 4 +Each search shall begin from the character before the first character +of the last match (or, if it is the first search, the character before +the cursor character). +.IP " 3." 4 +The search direction shall be from the cursor toward the beginning of +the edit buffer, and the +.BR wrapscan +edit option shall affect whether the search wraps to the end of the +edit buffer and continues. +.IP " 4." 4 +The remembered search direction shall be set to backward. +.SS "Execute" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +@\fIbuffer\fR +.fi \fR +.P +.RE +.RE +.P +If the +.IR buffer +is specified as +.BR @ , +the last buffer executed shall be used. If no previous buffer has been +executed, it shall be an error. +.P +Behave as if the contents of the named buffer were entered as standard +input. After each line of a line-mode buffer, and all but the last line +of a character mode buffer, behave as if a + +were entered as standard input. +.P +If an error occurs during this process, an error message shall be +written, and no more characters resulting from the execution of this +command shall be processed. +.P +If a +.IR count +is specified, behave as if that count were entered as user input before +the characters from the +.BR @ +buffer were entered. +.P +.IR "Current line" : +As specified for the individual commands. +.P +.IR "Current column" : +As specified for the individual commands. +.SS "Reverse Case" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ~ +.fi \fR +.P +.RE +.RE +.P +Reverse the case of the current character and the next +.IR count +\(mi1 characters, such that lowercase characters that have uppercase +counterparts shall be changed to uppercase characters, and uppercase +characters that have lowercase counterparts shall be changed to +lowercase characters, as prescribed by the current locale. No other +characters shall be affected by this command. +.P +If there are less than +.IR count +\(mi1 characters after the cursor in the edit buffer, +.IR count +shall be adjusted to the number of characters after the cursor in the +edit buffer minus 1. +.P +For the purposes of this command, the next character after the last +non-\c + +on the line shall be the next character in the edit buffer. +.P +.IR "Current line" : +Set to the line including the (\c +.IR count \(mi1)th +character after the cursor. +.P +.IR "Current column" : +Set to the last column in which any portion of the (\c +.IR count \(mi1)th +character after the cursor is displayed. +.SS "Append" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR a +.fi \fR +.P +.RE +.RE +.P +Enter text input mode after the current cursor position. No characters +already in the edit buffer shall be affected by this command. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the input. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Append at End-of-Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR A +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fR$\fB [ \fIcount \fB]\fR a +.fi \fR +.P +.RE +.P +(see +.IR "Append"). +.SS "Move Backward to Preceding Word" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR b +.fi \fR +.P +.RE +.RE +.P +With the exception that words are used as the delimiter instead of +bigwords, this command shall be equivalent to the +.BR B +command. +.SS "Move Backward to Preceding Bigword" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR B +.fi \fR +.P +.RE +.RE +.P +If the edit buffer is empty or the cursor is on the first character of +the edit buffer, it shall be an error. If less than +.IR count +bigwords begin between the cursor and the start of the edit buffer, +.IR count +shall be adjusted to the number of bigword beginnings between the +cursor and the start of the edit buffer. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the first character of the +.IR count th +previous bigword beginning up to but not including the cursor +character. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line containing the +.IR "current column" . +.P +.IR "Current column" : +Set to the last column upon which any part of the first character of +the +.IR count th +previous bigword is displayed. +.SS "Change" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR c \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR c +command repeated: +.IP " 1." 4 +The buffer text shall be in line mode. +.IP " 2." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 3." 4 +The text region shall be from the current line up to and including the +next +.IR count +\(mi1 lines. +.P +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.P +The replaced text shall be copied into +.IR buffer , +if specified, and into the unnamed buffer. If the text to be replaced +contains characters from more than a single line, or the buffer text is +in line mode, the replaced text shall be copied into the numeric +buffers as well. +.P +If the buffer text is in line mode: +.IP " 1." 4 +Any lines that contain characters in the region shall be deleted, and +the editor shall enter text input mode at the beginning of a new line +which shall replace the first line deleted. +.IP " 2." 4 +If the +.BR autoindent +edit option is set, +.BR autoindent +characters equal to the +.BR autoindent +characters on the first line deleted shall be inserted as if entered by +the user. +.P +Otherwise, if characters from more than one line are in the region of +text: +.IP " 1." 4 +The text shall be deleted. +.IP " 2." 4 +Any text remaining in the last line in the text region shall be +appended to the first line in the region, and the last line in the +region shall be deleted. +.IP " 3." 4 +The editor shall enter text input mode after the last character not +deleted from the first line in the text region, if any; otherwise, on +the first column of the first line in the region. +.br +.P +Otherwise: +.IP " 1." 4 +If the glyph for +.BR '$' +is smaller than the region, the end of the region shall be marked with +a +.BR '$' . +.IP " 2." 4 +The editor shall enter text input mode, overwriting the region of +text. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Change to End-of-Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR C +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR c$ +.fi \fR +.P +.RE +.P +See the +.BR c +command. +.SS "Delete" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR d \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR d +command repeated: +.IP " 1." 4 +The buffer text shall be in line mode. +.IP " 2." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 3." 4 +The text region shall be from the current line up to and including the +next +.IR count +\(mi1 lines. +.P +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.P +If in open mode, and the current line is deleted, and the line remains +on the display, an +.BR '@' +character shall be displayed as the first glyph of that line. +.P +Delete the region of text into +.IR buffer , +if specified, and into the unnamed buffer. If the text to be deleted +contains characters from more than a single line, or the buffer text is +in line mode, the deleted text shall be copied into the numeric +buffers, as well. +.P +.IR "Current line" : +Set to the first text region line that appears in the edit buffer, +unless that line has been deleted, in which case it shall be set to the +last line in the edit buffer, or line 1 if the edit buffer is empty. +.P +.IR "Current column" : +.IP " 1." 4 +If the line is empty, set to column position 1. +.IP " 2." 4 +Otherwise, if the buffer text is in line mode or the motion was from +the cursor toward the end of the edit buffer: +.RS 4 +.IP " a." 4 +If a character from the current line is displayed in the current +column, set to the last column that displays any portion of that +character. +.IP " b." 4 +Otherwise, set to the last column in which any portion of any character +in the line is displayed. +.RE +.IP " 3." 4 +Otherwise, if a character is displayed in the column that began the +text region, set to the last column that displays any portion of that +character. +.IP " 4." 4 +Otherwise, set to the last column in which any portion of any character +in the line is displayed. +.SS "Delete to End-of-Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB]\fR D +.fi \fR +.P +.RE +.RE +.P +Delete the text from the current position to the end of the current +line; equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB]\fR d$ +.fi \fR +.P +.RE +.SS "Move to End-of-Word" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR e +.fi \fR +.P +.RE +.RE +.P +With the exception that words are used instead of bigwords as the +delimiter, this command shall be equivalent to the +.BR E +command. +.SS "Move to End-of-Bigword" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR E +.fi \fR +.P +.RE +.RE +.P +If the edit buffer is empty it shall be an error. If less than +.IR count +bigwords end between the cursor and the end of the edit buffer, +.IR count +shall be adjusted to the number of bigword endings between the cursor +and the end of the edit buffer. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the last character of the +.IR count th +next bigword up to and including the cursor character. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line containing the current column. +.P +.IR "Current column" : +Set to the last column upon which any part of the last character of the +.IR count th +next bigword is displayed. +.SS "Find Character in Current Line (Forward)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR f \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if +.IR count +occurrences of the character do not occur after the cursor in the +line. +.P +If used as a motion command: +.IP " 1." 4 +The text range shall be from the cursor character up to and including +the +.IR count th +occurrence of the specified character after the cursor. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the +.IR count th +occurrence of the specified character after the cursor appears in the +line. +.SS "Find Character in Current Line (Reverse)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR F \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if +.IR count +occurrences of the character do not occur before the cursor in the +line. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the +.IR count th +occurrence of the specified character before the cursor, up to, but not +including the cursor character. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the +.IR count th +occurrence of the specified character before the cursor appears in the +line. +.SS "Move to Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR G +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is not specified, it shall default to the last line of the edit buffer. +If +.IR count +is greater than the last line of the edit buffer, it shall be an +error. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the cursor line up to and including the +specified line. +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to +.IR count +if +.IR count +is specified; otherwise, the last line. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Move to Top of Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR H +.fi \fR +.P +.RE +.RE +.P +If the beginning of the line +.IR count +greater than the first line of which any portion appears on the display +does not exist, it shall be an error. +.P +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.IP " 2." 4 +Otherwise, the text region shall be from the starting line up to and +including (the first line of the display + +.IR count +\(mi1). +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +If in open mode, this command shall set the current column to non-\c + +and do nothing else. +.P +Otherwise, it shall set the current line and current column as +follows. +.P +.IR "Current line" : +Set to (the first line of the display + +.IR count +\(mi1). +.P +.IR "Current column" : +Set to non-\c +. +.SS "Insert Before Cursor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR i +.fi \fR +.P +.RE +.RE +.P +Enter text input mode before the current cursor position. No characters +already in the edit buffer shall be affected by this command. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the input. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Insert at Beginning of Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR I +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command ^[\c +.IR count ]\c +.BR i . +.SS "Join" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR J +.fi \fR +.P +.RE +.RE +.P +If the current line is the last line in the edit buffer, it shall be an +error. +.P +This command shall be equivalent to the +.IR ex +.BR join +command with no addresses, and an +.IR ex +command +.IR count +value of 1 if +.IR count +was not specified or if a +.IR count +of 1 was specified, and an +.IR ex +command +.IR count +value of +.IR count +\(mi1 for any other value of +.IR count , +except that the current line and column shall be set as follows. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +The last column in which any portion of the character following the +last character in the initial line is displayed, or the last non-\c + +in the line if no characters were appended. +.SS "Move to Bottom of Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR L +.fi \fR +.P +.RE +.RE +.P +If the beginning of the line +.IR count +less than the last line of which any portion appears on the display +does not exist, it shall be an error. +.P +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.IP " 2." 4 +Otherwise, the text region shall include all lines from the starting +cursor line to (the last line of the display \(mi(\c +.IR count +\(mi1)). +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.IP " 1." 4 +If in open mode, this command shall set the current column to non-\c + +and do nothing else. +.IP " 2." 4 +Otherwise, it shall set the current line and current column as follows. +.P +.IR "Current line" : +Set to (the last line of the display \(mi(\c +.IR count +\(mi1)). +.P +.IR "Current column" : +Set to non-\c +. +.SS "Mark Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +m \fIletter\fR +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +.BR mark +command with the specified character as an argument. +.SS "Move to Middle of Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +M +.fi \fR +.P +.RE +.RE +.P +The middle line of the display shall be calculated as follows: +.sp +.RS 4 +.nf +\fB +(the top line of the display) + (((number of lines displayed) +1) /2) \(mi1 +.fi \fR +.P +.RE +.P +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.IP " 2." 4 +Otherwise, the text region shall include all lines from the starting +cursor line up to and including the middle line of the display. +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +If in open mode, this command shall set the current column to non-\c + +and do nothing else. +.P +Otherwise, it shall set the current line and current column as +follows. +.P +.IR "Current line" : +Set to the middle line of the display. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Repeat Regular Expression Find (Forward)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +n +.fi \fR +.P +.RE +.RE +.P +If the remembered search direction was forward, the +.BR n +command shall be equivalent to the +.IR vi +.BR / +command with no characters entered by the user. Otherwise, it shall be +equivalent to the +.IR vi +.BR ? +command with no characters entered by the user. +.P +If the +.BR n +command is used as a motion command for the +.BR ! +command, the editor shall not enter text input mode on the last line on +the screen, and shall behave as if the user entered a single +.BR '!' +character as the text input. +.SS "Repeat Regular Expression Find (Reverse)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +N +.fi \fR +.P +.RE +.RE +.P +Scan for the next match of the last pattern given to +.BR / +or +.BR ? , +but in the reverse direction; this is the reverse of +.BR n . +.P +If the remembered search direction was forward, the +.BR N +command shall be equivalent to the +.IR vi +.BR ? +command with no characters entered by the user. Otherwise, it shall be +equivalent to the +.IR vi +.BR / +command with no characters entered by the user. If the +.BR N +command is used as a motion command for the +.BR ! +command, the editor shall not enter text input mode on the last line on +the screen, and shall behave as if the user entered a single +.BR ! +character as the text input. +.SS "Insert Empty Line Below" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +o +.fi \fR +.P +.RE +.RE +.P +Enter text input mode in a new line appended after the current line. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting on a new, appended line. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Insert Empty Line Above" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +O +.fi \fR +.P +.RE +.RE +.P +Enter text input mode in a new line inserted before the current line. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting on a new, appended line. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Put from Buffer Following" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB]\fR p +.fi \fR +.P +.RE +.RE +.P +If no +.IR buffer +is specified, the unnamed buffer shall be used. +.P +If the buffer text is in line mode, the text shall be appended below +the current line, and each line of the buffer shall become a new line +in the edit buffer. A +.IR count +shall cause the buffer text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting on a new, appended line. +.P +If the buffer text is in character mode, the text shall be appended +into the current line after the cursor, and each line of the buffer +other than the first and last shall become a new line in the edit +buffer. A +.IR count +shall cause the buffer text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting after the last added character. +.P +.IR "Current line" : +If the buffer text is in line mode, set the line to line +1; otherwise, +unchanged. +.P +.IR "Current column" : +If the buffer text is in line mode: +.IP " 1." 4 +If there is a non-\c + +in the first line of the buffer, set to the last column on which any +portion of the first non-\c + +in the line is displayed. +.IP " 2." 4 +If there is no non-\c + +in the first line of the buffer, set to the last column on which any +portion of the last non-\c + +in the first line of the buffer is displayed. +.P +If the buffer text is in character mode: +.IP " 1." 4 +If the text in the buffer is from more than a single line, then set to +the last column on which any portion of the first character from the +buffer is displayed. +.IP " 2." 4 +Otherwise, if the buffer is the unnamed buffer, set to the last column +on which any portion of the last character from the buffer is +displayed. +.IP " 3." 4 +Otherwise, set to the first column on which any portion of the first +character from the buffer is displayed. +.SS "Put from Buffer Before" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB]\fR P +.fi \fR +.P +.RE +.RE +.P +If no +.IR buffer +is specified, the unnamed buffer shall be used. +.P +If the buffer text is in line mode, the text shall be inserted above +the current line, and each line of the buffer shall become a new line +in the edit buffer. A +.IR count +shall cause the buffer text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting on a new, appended line. +.P +If the buffer text is in character mode, the text shall be inserted +into the current line before the cursor, and each line of the buffer +other than the first and last shall become a new line in the edit +buffer. A +.IR count +shall cause the buffer text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting after the last added character. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +If the buffer text is in line mode: +.IP " 1." 4 +If there is a non-\c + +in the first line of the buffer, set to the last column on which any +portion of that character is displayed. +.IP " 2." 4 +If there is no non-\c + +in the first line of the buffer, set to the last column on which any +portion of the last non-\c + +in the first line of the buffer is displayed. +.P +If the buffer text is in character mode: +.IP " 1." 4 +If the text in the buffer is from more than a single line, then set to +the last column on which any portion of the first character from the +buffer is displayed. +.IP " 2." 4 +Otherwise, if the buffer is the unnamed buffer, set to the last column +on which any portion of the last character from the buffer is displayed. +.IP " 3." 4 +Otherwise, set to the first column on which any portion of the first +character from the buffer is displayed. +.SS "Enter ex Mode" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +Q +.fi \fR +.P +.RE +.RE +.P +Leave visual or open mode and enter +.IR ex +command mode. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Replace Character" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR r \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +Replace the +.IR count +characters at and after the cursor with the specified character. If +there are less than +.IR count +non-\c + +characters at and after the cursor on the line, it shall be an error. +.P +If character is +\(hyV, +any next character other than the + +shall be stripped of any special meaning and used as a literal +character. +.P +If character is +, +no replacement shall be made and the current line and current column +shall be unchanged. +.P +If character is + +or +, +.IR count +new lines shall be appended to the current line. All but the last of +these lines shall be empty. +.IR count +characters at and after the cursor shall be discarded, and any +remaining characters after the cursor in the current line shall be +moved to the last of the new lines. If the +.BR autoindent +edit option is set, they shall be preceded by the same number of +.BR autoindent +characters found on the line from which the command was executed. +.P +.IR "Current line" : +Unchanged unless the replacement character is a + +or +, +in which case it shall be set to line + +.IR count . +.P +.IR "Current column" : +Set to the last column position on which a portion of the last replaced +character is displayed, or if the replacement character caused new +lines to be created, set to non-\c +. +.SS "Replace Characters" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +R +.fi \fR +.P +.RE +.RE +.P +Enter text input mode at the current cursor position possibly +replacing text on the current line. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the input. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Substitute Character" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR s +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR c +.fi \fR +.P +.RE +.SS "Substitute Lines" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR S +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR c_ +.fi \fR +.P +.RE +.SS "Move Cursor to Before Character (Forward)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR t \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if +.IR count +occurrences of the character do not occur after the cursor in the +line. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the cursor up to but not including the +.IR count th +occurrence of the specified character after the cursor. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the character before the +.IR count th +occurrence of the specified character after the cursor appears in the +line. +.SS "Move Cursor to After Character (Reverse)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR T \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if +.IR count +occurrences of the character do not occur before the cursor in the +line. +.P +If used as a motion command: +.IP " 1." 4 +If the character before the cursor is the specified character, it shall +be an error. +.IP " 2." 4 +The text region shall be from the character before the cursor up to but +not including the +.IR count th +occurrence of the specified character before the cursor. +.IP " 3." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the character after the +.IR count th +occurrence of the specified character before the cursor appears in the +line. +.SS "Undo" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +.BR undo +command except that the current line and current column shall be set as +follows: +.P +.IR "Current line" : +Set to the first line added or changed if any; otherwise, move to the +line preceding any deleted text if one exists; otherwise, move to line 1. +.P +.IR "Current column" : +If undoing an +.IR ex +command, set to the first non-\c +. +.P +Otherwise, if undoing a text input command: +.IP " 1." 4 +If the command was a +.BR C , +.BR c , +.BR O , +.BR o , +.BR R , +.BR S , +or +.BR s +command, the current column shall be set to the value it held when the +text input command was entered. +.IP " 2." 4 +Otherwise, set to the last column in which any portion of the first +character after the deleted text is displayed, or, if no non-\c + +characters follow the text deleted from this line, set to the last column +in which any portion of the last non-\c + +in the line is displayed, or 1 if the line is empty. +.P +Otherwise, if a single line was modified (that is, not added or +deleted) by the +.BR u +command: +.IP " 1." 4 +If text was added or changed, set to the last column in which any +portion of the first character added or changed is displayed. +.IP " 2." 4 +If text was deleted, set to the last column in which any portion of the +first character after the deleted text is displayed, or, if no non-\c + +characters follow the deleted text, set to the last column in which any +portion of the last non-\c + +in the line is displayed, or 1 if the line is empty. +.P +Otherwise, set to non-\c +. +.SS "Undo Current Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +U +.fi \fR +.P +.RE +.RE +.P +Restore the current line to its state immediately before the most +recent time that it became the current line. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the first column in the line in which any portion of the first +character in the line is displayed. +.SS "Move to Beginning of Word" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR w +.fi \fR +.P +.RE +.RE +.P +With the exception that words are used as the delimiter instead of +bigwords, this command shall be equivalent to the +.BR W +command. +.SS "Move to Beginning of Bigword" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR W +.fi \fR +.P +.RE +.RE +.P +If the edit buffer is empty, it shall be an error. If there are less +than +.IR count +bigwords between the cursor and the end of the edit buffer, +.IR count +shall be adjusted to move the cursor to the last bigword in the edit +buffer. +.P +If used as a motion command: +.IP " 1." 4 +If the associated command is +.BR c , +.IR count +is 1, and the cursor is on a +, +the region of text shall be the current character and no further action +shall be taken. +.IP " 2." 4 +If there are less than +.IR count +bigwords between the cursor and the end of the edit buffer, then the +command shall succeed, and the region of text shall include the last +character of the edit buffer. +.IP " 3." 4 +If there are + +characters or an end-of-line that precede the +.IR count th +bigword, and the associated command is +.BR c , +the region of text shall be up to and including the last character +before the preceding + +characters or end-of-line. +.IP " 4." 4 +If there are + +characters or an end-of-line that precede the bigword, and the associated +command is +.BR d +or +.BR y , +the region of text shall be up to and including the last + +before the start of the bigword or end-of-line. +.IP " 5." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.IP " 1." 4 +If the cursor is on the last character of the edit buffer, it shall be +an error. +.P +.IR "Current line" : +Set to the line containing the current column. +.P +.IR "Current column" : +Set to the last column in which any part of the first character of the +.IR count th +next bigword is displayed. +.SS "Delete Character at Cursor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR x +.fi \fR +.P +.RE +.RE +.P +Delete the +.IR count +characters at and after the current character into +.IR buffer , +if specified, and into the unnamed buffer. +.P +If the line is empty, it shall be an error. If there are less than +.IR count +non-\c + +characters at and after the cursor on the current line, +.IR count +shall be adjusted to the number of non-\c + +characters at and after the cursor. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +If the line is empty, set to column position 1. Otherwise, if there +were +.IR count +or less non-\c + +characters at and after the cursor on the current line, set to the last +column that displays any part of the last non-\c + +of the line. Otherwise, unchanged. +.SS "Delete Character Before Cursor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR X +.fi \fR +.P +.RE +.RE +.P +Delete the +.IR count +characters before the current character into +.IR buffer , +if specified, and into the unnamed buffer. +.P +If there are no characters before the current character on the current +line, it shall be an error. If there are less than +.IR count +previous characters on the current line, +.IR count +shall be adjusted to the number of previous characters on the line. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to (current column \(mi the width of the deleted characters). +.SS "Yank" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR y \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +Copy (yank) the region of text into +.IR buffer , +if specified, and into the unnamed buffer. +.P +If the motion command is the +.BR y +command repeated: +.IP " 1." 4 +The buffer shall be in line mode. +.IP " 2." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 3." 4 +The text region shall be from the current line up to and including the +next +.IR count +\(mi1 lines. +.P +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.P +.IR "Current line" : +If the motion was from the current cursor position toward the end of +the edit buffer, unchanged. Otherwise, set to the first line in the +edit buffer that is part of the text region specified by the +motion command. +.P +.IR "Current column" : +.IP " 1." 4 +If the motion was from the current cursor position toward the end of +the edit buffer, unchanged. +.IP " 2." 4 +Otherwise, if the current line is empty, set to column position 1. +.IP " 3." 4 +Otherwise, set to the last column that displays any part of the first +character in the file that is part of the text region specified by the +motion command. +.SS "Yank Current Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR Y +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR y_ +.fi \fR +.P +.RE +.SS "Redraw Window" +.P +If in open mode, the +.BR z +command shall have the Synopsis: +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR z +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is not specified, it shall default to the +.BR window +edit option \(mi1. The +.BR z +command shall be equivalent to the +.IR ex +.BR z +command, with a type character of +.BR = +and a +.IR count +of +.IR count +\(mi2, except that the current line and current column shall be set as +follows, and the +.BR window +edit option shall not be affected. If the calculation for the +.IR count +argument would result in a negative number, the +.IR count +argument to the +.IR ex +.BR z +command shall be zero. A blank line shall be written after the last +line is written. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.P +If not in open mode, the +.BR z +command shall have the following Synopsis: +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIline\fB]\fR z \fB[\fIcount\fB] \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR line +is not specified, it shall default to the current line. If +.IR line +is specified, but is greater than the number of lines in the edit +buffer, it shall default to the number of lines in the edit buffer. +.P +If +.IR count +is specified, the value of the +.BR window +edit option shall be set to +.IR count +(as described in the +.IR ex +.BR window +command), and the screen shall be redrawn. +.P +.IR line +shall be placed as specified by the following characters: +.IP ",\ " 6 +.br +Place the beginning of the line on the first line of the display. +.IP "\fR.\fP" 6 +Place the beginning of the line in the center of the display. The +middle line of the display shall be calculated as described for the +.BR M +command. +.IP "\fR\(mi\fP" 6 +Place an unspecified portion of the line on the last line of the +display. +.IP "\fR+\fP" 6 +If +.IR line +was specified, equivalent to the + +case. If +.IR line +was not specified, display a screen where the first line of the display +shall be (current last line) +1. If there are no lines after the last +line in the display, it shall be an error. +.IP "\fR^\fP" 6 +If +.IR line +was specified, display a screen where the last line of the display +shall contain an unspecified portion of the first line of a display +that had an unspecified portion of the specified line on the last line +of the display. If this calculation results in a line before the +beginning of the edit buffer, display the first screen of the edit +buffer. +.RS 6 +.P +Otherwise, display a screen where the last line of the display shall +contain an unspecified portion of (current first line \(mi1). If this +calculation results in a line before the beginning of the edit buffer, +it shall be an error. +.RE +.br +.P +.IR "Current line" : +If +.IR line +and the +.BR '^' +character were specified: +.IP " 1." 4 +If the first screen was displayed as a result of the command attempting +to display lines before the beginning of the edit buffer: if the first +screen was already displayed, unchanged; otherwise, set to (current +first line \(mi1). +.IP " 2." 4 +Otherwise, set to the last line of the display. +.P +If +.IR line +and the +.BR '\(pl' +character were specified, set to the first line of the display. +.P +Otherwise, if +.IR line +was specified, set to +.IR line . +.P +Otherwise, unchanged. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Exit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ZZ +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +.BR xit +command with no addresses, trailing +.BR ! , +or filename (see the +.IR ex +.BR xit +command). +.SS "Input Mode Commands in vi" +.P +In text input mode, the current line shall consist of zero or more of +the following categories, plus the terminating +: +.IP " 1." 4 +Characters preceding the text input entry point +.RS 4 +.P +Characters in this category shall not be modified during text input +mode. +.RE +.IP " 2." 4 +.BR autoindent +characters +.RS 4 +.P +.BR autoindent +characters shall be automatically inserted into each line that is +created in text input mode, either as a result of entering a + +or + +while in text input mode, or as an effect of the command itself; for +example, +.BR O +or +.BR o +(see the +.IR ex +.BR autoindent +command), as if entered by the user. +.P +It shall be possible to erase +.BR autoindent +characters with the +\(hyD +command; it is unspecified whether they can be erased by +\(hyH, +\(hyU, +and +\(hyW +characters. Erasing any +.BR autoindent +character turns the glyph into erase-columns and deletes the character +from the edit buffer, but does not change its representation on the +screen. +.RE +.IP " 3." 4 +Text input characters +.RS 4 +.P +Text input characters are the characters entered by the user. Erasing +any text input character turns the glyph into erase-columns and deletes +the character from the edit buffer, but does not change its +representation on the screen. +.P +Each text input character entered by the user (that does not have a +special meaning) shall be treated as follows: +.IP " a." 4 +The text input character shall be appended to the last character in the +edit buffer from the first, second, or third categories. +.IP " b." 4 +If there are no erase-columns on the screen, the text input command was +the +.BR R +command, and characters in the fifth category from the original line +follow the cursor, the next such character shall be deleted from the +edit buffer. If the +.BR slowopen +edit option is not set, the corresponding glyph on the screen shall +become erase-columns. +.IP " c." 4 +If there are erase-columns on the screen, as many columns as they +occupy, or as are necessary, shall be overwritten to display the text +input character. (If only part of a multi-column glyph is overwritten, +the remainder shall be left on the screen, and continue to be treated +as erase-columns; it is unspecified whether the remainder of the glyph +is modified in any way.) +.IP " d." 4 +If additional display line columns are needed to display the text input +character: +.RS 4 +.IP " i." 5 +If the +.BR slowopen +edit option is set, the text input characters shall be displayed on +subsequent display line columns, overwriting any characters displayed +in those columns. +.IP ii. 5 +Otherwise, any characters currently displayed on or after the column on +the display line where the text input character is to be displayed +shall be pushed ahead the number of display line columns necessary to +display the rest of the text input character. +.RE +.RE +.IP " 4." 4 +Erase-columns +.RS 4 +.P +Erase-columns are not logically part of the edit buffer, appearing only +on the screen, and may be overwritten on the screen by subsequent text +input characters. When text input mode ends, all erase-columns shall no +longer appear on the screen. +.P +Erase-columns are initially the region of text specified by the +.BR c +command (see +.IR "Change"); +however, erasing +.BR autoindent +or text input characters causes the glyphs of the erased characters to +be treated as erase-columns. +.RE +.IP " 5." 4 +Characters following the text region for the +.BR c +command, or the text input entry point for all other commands +.RS 4 +.P +Characters in this category shall not be modified during text input +mode, except as specified in category 3.b. for the +.BR R +text input command, or as + +characters deleted when a + +or + +is entered. +.RE +.P +It is unspecified whether it is an error to attempt to erase past the +beginning of a line that was created by the entry of a + +or + +during text input mode. If it is not an error, the editor shall behave +as if the erasing character was entered immediately after the last text +input character entered on the previous line, and all of the non-\c + +characters on the current line shall be treated as erase-columns. +.P +When text input mode is entered, or after a text input mode character +is entered (except as specified for the special characters below), the +cursor shall be positioned as follows: +.IP " 1." 4 +On the first column that displays any part of the first erase-column, +if one exists +.IP " 2." 4 +Otherwise, if the +.BR slowopen +edit option is set, on the first display line column after the last +character in the first, second, or third categories, if one exists +.IP " 3." 4 +Otherwise, the first column that displays any part of the first +character in the fifth category, if one exists +.IP " 4." 4 +Otherwise, the display line column after the last character in the +first, second, or third categories, if one exists +.IP " 5." 4 +Otherwise, on column position 1 +.P +The characters that are updated on the screen during text input mode +are unspecified, other than that the last text input character shall +always be updated, and, if the +.BR slowopen +edit option is not set, the current cursor character shall always be +updated. +.P +The following specifications are for command characters entered during +text input mode. +.SS "NUL" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +NUL +.fi \fR +.P +.RE +.RE +.P +If the first character of the text input is a NUL, the most recently +input text shall be input as if entered by the user, and then text +input mode shall be exited. The text shall be input literally; that is, +characters are neither macro or abbreviation expanded, nor are any +characters interpreted in any special manner. It is unspecified whether +implementations shall support more than 256 bytes of remembered input +text. +.SS "-D" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-D +.fi \fR +.P +.RE +.RE +.P +The +\(hyD +character shall have no special meaning when in text input +mode for a line-oriented command (see +.IR "Command Descriptions in vi"). +.P +This command need not be supported on block-mode terminals. +.P +If the cursor does not follow an +.BR autoindent +character, or an +.BR autoindent +character and a +.BR '0' +or +.BR '^' +character: +.IP " 1." 4 +If the cursor is in column position 1, the +\(hyD +character shall be discarded and no further action taken. +.IP " 2." 4 +Otherwise, the +\(hyD +character shall have no special meaning. +.P +If the last input character was a +.BR '0' , +the cursor shall be moved to column position 1. +.P +Otherwise, if the last input character was a +.BR '^' , +the cursor shall be moved to column position 1. In addition, the +.BR autoindent +level for the next input line shall be derived from the same line from +which the +.BR autoindent +level for the current input line was derived. +.P +Otherwise, the cursor shall be moved back to the column after the +previous shiftwidth (see the +.IR ex +.BR shiftwidth +command) boundary. +.P +All of the glyphs on columns between the starting cursor position and +(inclusively) the ending cursor position shall become erase-columns as +described in +.IR "Input Mode Commands in vi". +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to 1 if the +\(hyD +was preceded by a +.BR '^' +or +.BR '0' ; +otherwise, set to (column \(mi1) \(mi((column \(mi2) % +.BR shiftwidth ). +.SS "-H" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-H +.fi \fR +.P +.RE +.RE +.P +If in text input mode for a line-oriented command, and there are no +characters to erase, text input mode shall be terminated, no further +action shall be done for this command, and the current line and column +shall be unchanged. +.P +If there are characters other than +.BR autoindent +characters that have been input on the current line before the cursor, +the cursor shall move back one character. +.P +Otherwise, if there are +.BR autoindent +characters on the current line before the cursor, it is +implementation-defined whether the +\(hyH +command is an error or if the cursor moves back one +.BR autoindent +character. +.P +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined whether the +\(hyH +command is an error or if it is equivalent to entering +\(hyH +after the last input character on the previous input line. +.P +Otherwise, it shall be an error. +.P +All of the glyphs on columns between the starting cursor position and +(inclusively) the ending cursor position shall become erase-columns as +described in +.IR "Input Mode Commands in vi". +.P +The current erase character (see +.IR stty ) +shall cause an equivalent action to the +\(hyH +command, unless the previously inserted character was a +, +in which case it shall be as if the literal current erase character had +been inserted instead of the +. +.P +.IR "Current line" : +Unchanged, unless previously input lines are erased, in which case it +shall be set to line \(mi1. +.P +.IR "Current column" : +Set to the first column that displays any portion of the character +backed up over. +.SS "" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.br + +.br +-J +.br +-M +.fi \fR +.P +.RE +.RE +.P +If input was part of a line-oriented command, text input mode shall be +terminated and the command shall continue execution with the input +provided. +.P +Otherwise, terminate the current line. If there are no characters other +than +.BR autoindent +characters on the line, all characters on the line shall be discarded. +Otherwise, it is unspecified whether the +.BR autoindent +characters in the line are modified by entering these characters. +.P +Continue text input mode on a new line appended after the current line. +If the +.BR slowopen +edit option is set, the lines on the screen below the current line +shall not be pushed down, but the first of them shall be cleared and +shall appear to be overwritten. Otherwise, the lines of the screen +below the current line shall be pushed down. +.P +If the +.BR autoindent +edit option is set, an appropriate number of +.BR autoindent +characters shall be added as a prefix to the line as described by the +.IR ex +.BR autoindent +edit option. +.P +All columns after the cursor that are erase-columns (as described in +.IR "Input Mode Commands in vi") +shall be discarded. +.P +If the +.BR autoindent +edit option is set, all + +characters immediately following the cursor shall be discarded. +.P +All remaining characters after the cursor shall be transferred to the +new line, positioned after any +.BR autoindent +characters. +.P +.IR "Current line" : +Set to current line +1. +.P +.IR "Current column" : +Set to the first column that displays any portion of the first +character after the +.BR autoindent +characters on the new line, if any, or the first column position after +the last +.BR autoindent +character, if any, or column position 1. +.SS "-T" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-T +.fi \fR +.P +.RE +.RE +.P +The +\(hyT +character shall have no special meaning when in text input mode for a +line-oriented command (see +.IR "Command Descriptions in vi"). +.P +This command need not be supported on block-mode terminals. +.P +Behave as if the user entered the minimum number of + +characters necessary to move the cursor forward to the column position +after the next +.BR shiftwidth +(see the +.IR ex +.BR shiftwidth +command) boundary. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to +.IR column ++ +.BR shiftwidth +\(mi ((column \(mi1) % +.BR shiftwidth ). +.SS "-U" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-U +.fi \fR +.P +.RE +.RE +.P +If there are characters other than +.BR autoindent +characters that have been input on the current line before the cursor, +the cursor shall move to the first character input after the +.BR autoindent +characters. +.P +Otherwise, if there are +.BR autoindent +characters on the current line before the cursor, it is +implementation-defined whether the +\(hyU +command is an error or if the cursor moves to the first column position +on the line. +.P +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined whether the +\(hyU +command is an error or if it is equivalent to entering +\(hyU +after the last input character on the previous input line. +.P +Otherwise, it shall be an error. +.P +All of the glyphs on columns between the starting cursor position and +(inclusively) the ending cursor position shall become erase-columns as +described in +.IR "Input Mode Commands in vi". +.P +The current +.IR kill +character (see +.IR stty ) +shall cause an equivalent action to the +\(hyU +command, unless the previously inserted character was a +, +in which case it shall be as if the literal current +.IR kill +character had been inserted instead of the +. +.P +.IR "Current line" : +Unchanged, unless previously input lines are erased, in which case it +shall be set to line \(mi1. +.P +.IR "Current column" : +Set to the first column that displays any portion of the last character +backed up over. +.SS "-V" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-V +.br +-Q +.fi \fR +.P +.RE +.RE +.P +Allow the entry of any subsequent character, other than +\(hyJ +or the +, +as a literal character, removing any special meaning that it may have +to the editor in text input mode. If a +\(hyV +or +\(hyQ +is entered before a +\(hyJ +or +, +the +\(hyV +or +\(hyQ +character shall be discarded, and the +\(hyJ +or + +shall behave as described in the + +command character during input mode. +.P +For purposes of the display only, the editor shall behave as if a +.BR '^' +character was entered, and the cursor shall be positioned as if +overwriting the +.BR '^' +character. When a subsequent character is entered, the editor shall +behave as if that character was entered instead of the original +\(hyV +or +\(hyQ +character. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "-W" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-W +.fi \fR +.P +.RE +.RE +.P +If there are characters other than +.BR autoindent +characters that have been input on the current line before the cursor, +the cursor shall move back over the last word preceding the cursor +(including any + +characters between the end of the last word and the current cursor); the +cursor shall not move to before the first character after the end of any +.BR autoindent +characters. +.P +Otherwise, if there are +.BR autoindent +characters on the current line before the cursor, it is +implementation-defined whether the +\(hyW +command is an error or if the cursor moves to the first column position +on the line. +.P +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined whether the +\(hyW +command is an error or if it is equivalent to entering +\(hyW +after the last input character on the previous input line. +.P +Otherwise, it shall be an error. +.P +All of the glyphs on columns between the starting cursor position and +(inclusively) the ending cursor position shall become erase-columns as +described in +.IR "Input Mode Commands in vi". +.P +.IR "Current line" : +Unchanged, unless previously input lines are erased, in which case it +shall be set to line \(mi1. +.P +.IR "Current column" : +Set to the first column that displays any portion of the last character +backed up over. +.SS "" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.fi \fR +.P +.RE +.RE +.P +If input was part of a line-oriented command: +.IP " 1." 4 +If +.IR interrupt +was entered, text input mode shall be terminated and the editor shall +return to command mode. The terminal shall be alerted. +.IP " 2." 4 +If + +was entered, text input mode shall be terminated and the command shall +continue execution with the input provided. +.P +Otherwise, terminate text input mode and return to command mode. +.P +Any +.BR autoindent +characters entered on newly created lines that have no other non-\c + +characters shall be deleted. +.P +Any leading +.BR autoindent +and + +characters on newly created lines shall be rewritten to be the minimum +number of + +characters possible. +.P +The screen shall be redisplayed as necessary to match the contents of +the edit buffer. +.P +.IR "Current line" : +Unchanged. +.br +.P +.IR "Current column" : +.IP " 1." 4 +If there are text input characters on the current line, the column +shall be set to the last column where any portion of the last text +input character is displayed. +.IP " 2." 4 +Otherwise, if a character is displayed in the current column, +unchanged. +.IP " 3." 4 +Otherwise, set to column position 1. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When any error is encountered and the standard input is not a terminal +device file, +.IR vi +shall not write the file or return to command or text input mode, and +shall terminate with a non-zero exit status. +.P +Otherwise, when an unrecoverable error is encountered it shall be +equivalent to a SIGHUP asynchronous event. +.P +Otherwise, when an error is encountered, the editor shall behave as +specified in +.IR "Command Descriptions in vi". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +See the RATIONALE for +.IR "\fIex\fR\^" +for more information on +.IR vi . +Major portions of the +.IR vi +utility specification point to +.IR ex +to avoid inadvertent divergence. While +.IR ex +and +.IR vi +have historically been implemented as a single utility, this is not +required by POSIX.1\(hy2008. +.P +It is recognized that portions of +.IR vi +would be difficult, if not impossible, to implement satisfactorily on a +block-mode terminal, or a terminal without any form of cursor +addressing, thus it is not a mandatory requirement that such features +should work on all terminals. It is the intention, however, that a +.IR vi +implementation should provide the full set of capabilities on all +terminals capable of supporting them. +.P +Historically, +.IR vi +exited immediately if the standard input was not a terminal. POSIX.1\(hy2008 +permits, but does not require, this behavior. An end-of-file condition +is not equivalent to an end-of-file character. A common end-of-file +character, +\(hyD, +is historically a +.IR vi +command. +.P +The text in the STDOUT section reflects the usage of the verb +.IR display +in this section; some implementations of +.IR vi +use standard output to write to the terminal, but POSIX.1\(hy2008 does not +require that to be the case. +.P +Historically, implementations reverted to open mode if the terminal was +incapable of supporting full visual mode. POSIX.1\(hy2008 requires this +behavior. Historically, the open mode of +.IR vi +behaved roughly equivalently to the visual mode, with the exception +that only a single line from the edit buffer (one ``buffer line'') was +kept current at any time. This line was normally displayed on the +next-to-last line of a terminal with cursor addressing (and the last +line performed its normal visual functions for line-oriented commands +and messages). In addition, some few commands behaved differently in +open mode than in visual mode. POSIX.1\(hy2008 requires conformance to historical +practice. +.P +Historically, +.IR ex +and +.IR vi +implementations have expected text to proceed in the usual +European/Latin order of left to right, top to bottom. There is no +requirement in POSIX.1\(hy2008 that this be the case. The specification was +deliberately written using words like ``before'', ``after'', ``first'', +and ``last'' in order to permit implementations to support the natural +text order of the language. +.P +Historically, lines past the end of the edit buffer were marked with +single + +(\c +.BR '~' ) +characters; that is, if the one-based display was 20 lines in length, +and the last line of the file was on line one, then lines 2-20 would +contain only a single +.BR '~' +character. +.P +Historically, the +.IR vi +editor attempted to display only complete lines at the bottom of the +screen (it did display partial lines at the top of the screen). If a +line was too long to fit in its entirety at the bottom of the screen, +the screen lines where the line would have been displayed were +displayed as single +.BR '@' +characters, instead of displaying part of the line. POSIX.1\(hy2008 permits, but +does not require, this behavior. Implementations are encouraged to +attempt always to display a complete line at the bottom of the screen +when doing scrolling or screen positioning by buffer lines. +.P +Historically, lines marked with +.BR '@' +were also used to minimize output to dumb terminals over slow lines; +that is, changes local to the cursor were updated, but changes to lines +on the screen that were not close to the cursor were simply marked with +an +.BR '@' +sign instead of being updated to match the current text. POSIX.1\(hy2008 permits, +but does not require this feature because it is used ever less +frequently as terminals become smarter and connections are faster. +.SS "Initialization in ex and vi" +.P +Historically, +.IR vi +always had a line in the edit buffer, even if the edit buffer was +``empty''. For example: +.IP " 1." 4 +The +.IR ex +command +.BR = +executed from visual mode wrote ``1'' when the buffer was empty. +.IP " 2." 4 +Writes from visual mode of an empty edit buffer wrote files of a single +character (a +), +while writes from +.IR ex +mode of an empty edit buffer wrote empty files. +.IP " 3." 4 +Put and read commands into an empty edit buffer left an empty line at +the top of the edit buffer. +.P +For consistency, POSIX.1\(hy2008 does not permit any of these behaviors. +.P +Historically, +.IR vi +did not always return the terminal to its original modes; for example, +ICRNL was modified if it was not originally set. POSIX.1\(hy2008 does not permit +this behavior. +.SS "Command Descriptions in vi" +.P +Motion commands are among the most complicated aspects of +.IR vi +to describe. With some exceptions, the text region and buffer type +effect of a motion command on a +.IR vi +command are described on a case-by-case basis. The descriptions of text +regions in POSIX.1\(hy2008 are not intended to imply direction; that is, an +inclusive region from line +.IR n +to line +.IR n +5 +is identical to a region from line +.IR n +5 +to line +.IR n . +This is of more than academic interest\(emmovements to marks can be in +either direction, and, if the +.BR wrapscan +option is set, so can movements to search points. Historically, lines +are always stored into buffers in text order; that is, from the start +of the edit buffer to the end. POSIX.1\(hy2008 requires conformance to historical +practice. +.P +Historically, command counts were applied to any associated motion, and +were multiplicative to any supplied motion count. For example, +.BR 2cw +is the same as +.BR c2w , +and +.BR 2c3w +is the same as +.BR c6w . +POSIX.1\(hy2008 requires this behavior. Historically, +.IR vi +commands that used bigwords, words, paragraphs, and sentences as +objects treated groups of empty lines, or lines that contained only + +characters, inconsistently. Some commands treated them as a single entity, +while others treated each line separately. For example, the +.BR w , +.BR W , +and +.BR B +commands treated groups of empty lines as individual words; that is, +the command would move the cursor to each new empty line. The +.BR e +and +.BR E +commands treated groups of empty lines as a single word; that is, the +first use would move past the group of lines. The +.BR b +command would just beep at the user, or if done from the start of the +line as a motion command, fail in unexpected ways. If the lines +contained only (or ended with) + +characters, the +.BR w +and +.BR W +commands would just beep at the user, the +.BR E +and +.BR e +commands would treat the group as a single word, and the +.BR B +and +.BR b +commands would treat the lines as individual words. For consistency and +simplicity of specification, POSIX.1\(hy2008 requires that all +.IR vi +commands treat groups of empty or blank lines as a single entity, and +that movement through lines ending with + +characters be consistent with other movements. +.P +Historically, +.IR vi +documentation indicated that any number of double-quotes were skipped +after punctuation marks at sentence boundaries; however, +implementations only skipped single-quotes. POSIX.1\(hy2008 requires both to be +skipped. +.P +Historically, the first and last characters in the edit buffer were +word boundaries. This historical practice is required by POSIX.1\(hy2008. +.P +Historically, +.IR vi +attempted to update the minimum number of columns on the screen +possible, which could lead to misleading information being displayed. +POSIX.1\(hy2008 makes no requirements other than that the current character being +entered is displayed correctly, leaving all other decisions in this +area up to the implementation. +.P +Historically, lines were arbitrarily folded between columns of any +characters that required multiple column positions on the screen, with +the exception of tabs, which terminated at the right-hand margin. POSIX.1\(hy2008 +permits the former and requires the latter. Implementations that do not +arbitrarily break lines between columns of characters that occupy +multiple column positions should not permit the cursor to rest on a +column that does not contain any part of a character. +.P +The historical +.IR vi +had a problem in that all movements were by buffer lines, not by +display or screen lines. This is often the right thing to do; for +example, single line movements, such as +.BR j +or +.BR k , +should work on buffer lines. Commands like +.BR dj , +or +.BR j. , +where +.BR . +is a change command, only make sense for buffer lines. It is not, +however, the right thing to do for screen motion or scrolling commands +like +\(hyD, +\(hyF, +and +.BR H . +If the window is fairly small, using buffer lines in these cases can +result in completely random motion; for example, +.BR 1 \c +\c +.BR \(hyD +can result in a completely changed screen, without any overlap. This is +clearly not what the user wanted. The problem is even worse in the case +of the +.BR H , +.BR L , +and +.BR M +commands\(emas they position the cursor at the first non-\c + +of the line, they may all refer to the same location in large lines, +and will result in no movement at all. +.P +In addition, if the line is larger than the screen, using buffer +lines can make it impossible to display parts of the line\(emthere are +not any commands that do not display the beginning of the line in +historical +.IR vi , +and if both the beginning and end of the line cannot be on the screen +at the same time, the user suffers. Finally, the page and half-page +scrolling commands historically moved to the first non-\c + +in the new line. If the line is approximately the same size as the +screen, this is inadequate because the cursor before and after a +\(hyD +command will refer to the same location on the screen. +.P +Implementations of +.IR ex +and +.IR vi +exist that do not have these problems because the relevant commands (\c +\(hyB, +\(hyD, +\(hyF, +\(hyU, +\(hyY, +\(hyE, +.BR H , +.BR L , +and +.BR M) +operate on display (screen) lines, not (edit) buffer lines. +.P +POSIX.1\(hy2008 does not permit this behavior by default because the standard +developers believed that users would find it too confusing. However, +historical practice has been relaxed. For example, +.IR ex +and +.IR vi +historically attempted, albeit sometimes unsuccessfully, to never put +part of a line on the last lines of a screen; for example, if a line +would not fit in its entirety, no part of the line was displayed, and +the screen lines corresponding to the line contained single +.BR '@' +characters. This behavior is permitted, but not required by POSIX.1\(hy2008, so +that it is possible for implementations to support long lines in small +screens more reasonably without changing the commands to be oriented to +the display (instead of oriented to the buffer). POSIX.1\(hy2008 also permits +implementations to refuse to edit any edit buffer containing a line +that will not fit on the screen in its entirety. +.P +The display area (for example, the value of the +.BR window +edit option) has historically been ``grown'', or expanded, to display +new text when local movements are done in displays where the number of +lines displayed is less than the maximum possible. Expansion has +historically been the first choice, when the target line is less than +the maximum possible expansion value away. Scrolling has historically +been the next choice, done when the target line is less than half a +display away, and otherwise, the screen was redrawn. There were +exceptions, however, in that +.IR ex +commands generally always caused the screen to be redrawn. POSIX.1\(hy2008 does +not specify a standard behavior because there may be external issues, +such as connection speed, the number of characters necessary to redraw +as opposed to scroll, or terminal capabilities that implementations +will have to accommodate. +.P +The current line in POSIX.1\(hy2008 maps one-to-one to a buffer line in the +file. The current column does not. There are two different column +values that are described by POSIX.1\(hy2008. The first is the current column +value as set by many of the +.IR vi +commands. This value is remembered for the lifetime of the editor. The +second column value is the actual position on the screen where the +cursor rests. The two are not always the same. For example, when the +cursor is backed by a multi-column character, the actual cursor +position on the screen has historically been the last column of the +character in command mode, and the first column of the character in +input mode. +.P +Commands that set the current line, but that do not set the current +cursor value (for example, +.BR j +and +.BR k ) +attempt to get as close as possible to the remembered column position, +so that the cursor tends to restrict itself to a vertical column as the +user moves around in the edit buffer. POSIX.1\(hy2008 requires conformance to +historical practice, requiring that the display location of the cursor +on the display line be adjusted from the current column value as +necessary to support this historical behavior. +.P +Historically, only a single line (and for some terminals, a single line +minus 1 column) of characters could be entered by the user for the +line-oriented commands; that is, +.BR : , +.BR ! , +.BR / , +or +.BR ? . +POSIX.1\(hy2008 permits, but does not require, this limitation. +.P +Historically, ``soft'' errors in +.IR vi +caused the terminal to be alerted, but no error message was displayed. +As a general rule, no error message was displayed for errors in command +execution in +.IR vi , +when the error resulted from the user attempting an invalid or +impossible action, or when a searched-for object was not found. +Examples of soft errors included +.BR h +at the left margin, +\(hyB +or +.BR [[ +at the beginning of the file, +.BR 2G +at the end of the file, and so on. In addition, errors such as +.BR % , +.BR ]] , +.BR } , +.BR ) , +.BR N , +.BR n , +.BR f , +.BR F , +.BR t , +and +.BR T +failing to find the searched-for object were soft as well. Less +consistently, +.BR / +and +.BR ? +displayed an error message if the pattern was not found, +.BR / , +.BR ? , +.BR N , +and +.BR n +displayed an error message if no previous regular expression had been +specified, and +.BR ; +did not display an error message if no previous +.BR f , +.BR F , +.BR t , +or +.BR T +command had occurred. Also, behavior in this area might reasonably be +based on a runtime evaluation of the speed of a network connection. +Finally, some implementations have provided error messages for soft +errors in order to assist naive users, based on the value of a verbose +edit option. POSIX.1\(hy2008 does not list specific errors for which an error +message shall be displayed. Implementations should conform to +historical practice in the absence of any strong reason to diverge. +.SS "Page Backwards" +.P +The +\(hyB +and +\(hyF +commands historically considered it an error to attempt to page past +the beginning or end of the file, whereas the +\(hyD +and +\(hyU +commands simply moved to the beginning or end of the file. For +consistency, POSIX.1\(hy2008 requires the latter behavior for all four commands. +All four commands still consider it an error if the current line is at +the beginning (\c +\(hyB, +\(hyU) +or end (\c +\(hyF, +\(hyD) +of the file. Historically, the +\(hyB +and +\(hyF +commands skip two lines in order to include overlapping lines when a +single command is entered. This makes less sense in the presence of a +.IR count , +as there will be, by definition, no overlapping lines. The actual +calculation used by historical implementations of the +.IR vi +editor for +\(hyB +was: +.sp +.RS 4 +.nf +\fB +((current first line) \(mi count x (window edit option)) +2 +.fi \fR +.P +.RE +.P +and for +\(hyF +was: +.sp +.RS 4 +.nf +\fB +((current first line) + count x (window edit option)) \(mi2 +.fi \fR +.P +.RE +.P +This calculation does not work well when intermixing commands with and +without counts; for example, +.BR 3\c +\(hyF +is not equivalent to entering the +\(hyF +command three times, and is not reversible by entering the +\(hyB +command three times. For consistency with other +.IR vi +commands that take counts, POSIX.1\(hy2008 requires a different calculation. +.SS "Scroll Forward" +.P +The 4BSD and System V implementations of +.IR vi +differed on the initial value used by the +.BR scroll +command. 4BSD used: +.sp +.RS 4 +.nf +\fB +((window edit option) +1) /2 +.fi \fR +.P +.RE +.P +while System V used the value of the +.BR scroll +edit option. The System V version is specified by POSIX.1\(hy2008 because the +standard developers believed that it was more intuitive and permitted +the user a method of setting the scroll value initially without also +setting the number of lines that are displayed. +.SS "Scroll Forward by Line" +.P +Historically, the +\(hyE +and +\(hyY +commands considered it an error if the last and first lines, +respectively, were already on the screen. POSIX.1\(hy2008 requires conformance to +historical practice. Historically, the +\(hyE +and +\(hyY +commands had no effect in open mode. For simplicity and consistency of +specification, POSIX.1\(hy2008 requires that they behave as usual, albeit with a +single line screen. +.SS "Clear and Redisplay" +.P +The historical +\(hyL +command refreshed the screen exactly as it was supposed to be currently +displayed, replacing any +.BR '@' +characters for lines that had been deleted but not updated on the +screen with refreshed +.BR '@' +characters. The intent of the +\(hyL +command is to refresh when the screen has been accidentally +overwritten; for example, by a +.BR write +command from another user, or modem noise. +.SS "Redraw Screen" +.P +The historical +\(hyR +command redisplayed only when necessary to update lines that had been +deleted but not updated on the screen and that were flagged with +.BR '@' +characters. There is no requirement that the screen be in any way +refreshed if no lines of this form are currently displayed. POSIX.1\(hy2008 +permits implementations to extend this command to refresh lines on the +screen flagged with +.BR '@' +characters because they are too long to be displayed in the current +framework; however, the current line and column need not be modified. +.SS "Search for tagstring" +.P +Historically, the first non-\c + +at or after the cursor was the first character, and all subsequent +characters that were word characters, up to the end of the line, were +included. For example, with the cursor on the leading + +or on the +.BR '#' +character in the text +.BR \(dq#bar@\(dq , +the tag was +.BR \(dq#bar\(dq . +On the character +.BR 'b' +it was +.BR \(dqbar\(dq , +and on the +.BR 'a' +it was +.BR \(dqar\(dq . +POSIX.1\(hy2008 requires this behavior. +.SS "Replace Text with Results from Shell Command" +.P +Historically, the +.BR < , +.BR > , +and +.BR ! +commands considered most cursor motions other than line-oriented +motions an error; for example, the command +.BR ">/foo" +succeeded, while the command +.BR ">l" +failed, even though the text region described by the two commands might +be identical. For consistency, all three commands only consider entire +lines and not partial lines, and the region is defined as any line that +contains a character that was specified by the motion. +.SS "Move to Matching Character" +.P +Other matching characters have been left implementation-defined in +order to allow extensions such as matching +.BR '<' +and +.BR '>' +for searching HTML, or +.BR #ifdef , +.BR #else , +and +.BR #endif +for searching C source. +.SS "Repeat Substitution" +.P +POSIX.1\(hy2008 requires that any +.BR c +and +.BR g +flags specified to the previous substitute command be ignored; however, +the +.BR r +flag may still apply, if supported by the implementation. +.SS "Return to Previous (Context or Section)" +.P +The +.BR [[ , +.BR ]] , +.BR ( , +.BR ) , +.BR { , +and +.BR } +commands are all affected by ``section boundaries'', but in some +historical implementations not all of the commands recognize the same +section boundaries. This is a bug, not a feature, and a unique +section-boundary algorithm was not described for each command. One +special case that is preserved is that the sentence command moves to +the end of the last line of the edit buffer while the other commands go +to the beginning, in order to preserve the traditional character cut +semantics of the sentence command. Historically, +.IR vi +section boundaries at the beginning and end of the edit buffer were the +first non-\c + +on the first and last lines of the edit buffer if one exists; +otherwise, the last character of the first and last lines of the edit +buffer if one exists. To increase consistency with other section +locations, this has been simplified by POSIX.1\(hy2008 to the first character of +the first and last lines of the edit buffer, or the first and the last +lines of the edit buffer if they are empty. +.P +Sentence boundaries were problematic in the historical +.IR vi . +They were not only the boundaries as defined for the section and +paragraph commands, but they were the first non-\c + +that occurred after those boundaries, as well. Historically, the +.IR vi +section commands were documented as taking an optional window size as a +.IR count +preceding the command. This was not implemented in historical versions, +so POSIX.1\(hy2008 requires that the +.IR count +repeat the command, for consistency with other +.IR vi +commands. +.SS "Repeat" +.P +Historically, mapped commands other than text input commands could not +be repeated using the +.BR period +command. POSIX.1\(hy2008 requires conformance to historical practice. +.P +The restrictions on the interpretation of special characters (for +example, +\(hyH) +in the repetition of text input mode commands is intended to match +historical practice. For example, given the input sequence: +.sp +.RS 4 +.nf +\fB +iab-H-H-Hdef +.fi \fR +.P +.RE +.P +the user should be informed of an error when the sequence is first +entered, but not during a command repetition. The character +\(hyT +is specifically exempted from this restriction. Historical +implementations of +.IR vi +ignored +\(hyT +characters that were input in the original command during command +repetition. POSIX.1\(hy2008 prohibits this behavior. +.SS "Find Regular Expression" +.P +Historically, commands did not affect the line searched to or from if +the motion command was a search (\c +.BR / , +.BR ? , +.BR N , +.BR n ) +and the final position was the start/end of the line. There were some +special cases and +.IR vi +was not consistent. POSIX.1\(hy2008 does not permit this behavior, for +consistency. Historical implementations permitted but were unable to +handle searches as motion commands that wrapped (that is, due to the +edit option +.BR wrapscan ) +to the original location. POSIX.1\(hy2008 requires that this behavior be treated +as an error. +.P +Historically, the syntax +.BR \(dq/RE/0\(dq +was used to force the command to cut text in line mode. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historically, in open mode, a +.BR z +specified to a search command redisplayed the current line instead of +displaying the current screen with the current line highlighted. For +consistency and simplicity of specification, POSIX.1\(hy2008 does not permit this +behavior. +.P +Historically, trailing +.BR z +commands were permitted and ignored if entered as part of a search used +as a motion command. For consistency and simplicity of specification, +POSIX.1\(hy2008 does not permit this behavior. +.SS "Execute an ex Command" +.P +Historically, +.IR vi +implementations restricted the commands that could be entered on the +colon command line (for example, +.BR append +and +.BR change ), +and some other commands were known to cause them to fail +catastrophically. For consistency, POSIX.1\(hy2008 does not permit these +restrictions. When executing an +.IR ex +command by entering +.BR : , +it is not possible to enter a + +as part of the command because it is considered the end of the command. +A different approach is to enter +.IR ex +command mode by using the +.IR vi +.BR Q +command (and later resuming visual mode with the +.IR ex +.BR vi +command). In +.IR ex +command mode, the single-line limitation does not exist. So, for +example, the following is valid: +.sp +.RS 4 +.nf +\fB +Q +s/break here/break\e +here/ +vi +.fi \fR +.P +.RE +.P +POSIX.1\(hy2008 requires that, if the +.IR ex +command overwrites any part of the screen that would be erased by a +refresh, +.IR vi +pauses for a character from the user. Historically, this character +could be any character; for example, a character input by the user +before the message appeared, or even a mapped character. This is +probably a bug, but implementations that have tried to be more rigorous +by requiring that the user enter a specific character, or that the user +enter a character after the message was displayed, have been forced by +user indignation back into historical behavior. POSIX.1\(hy2008 requires +conformance to historical practice. +.SS "Shift Left (Right)" +.P +Refer to the Rationale for the +.BR ! +and +.BR / +commands. Historically, the +.BR < +and +.BR > +commands sometimes moved the cursor to the first non-\c + +(for example if the command was repeated or with +.BR _ +as the motion command), and sometimes left it unchanged. POSIX.1\(hy2008 does not +permit this inconsistency, requiring instead that the cursor always +move to the first non-\c +. +Historically, the +.BR < +and +.BR > +commands did not support buffer arguments, although some +implementations allow the specification of an optional buffer. This +behavior is neither required nor disallowed by POSIX.1\(hy2008. +.SS "Execute" +.P +Historically, buffers could execute other buffers, and loops, infinite +and otherwise, were possible. POSIX.1\(hy2008 requires conformance to historical +practice. The *\c +.IR buffer +syntax of +.IR ex +is not required in +.IR vi , +because it is not historical practice and has been used in some +.IR vi +implementations to support additional scripting languages. +.SS "Reverse Case" +.P +Historically, the +.BR ~ +command ignored any associated +.IR count , +and acted only on the characters in the current line. For consistency +with other +.IR vi +commands, POSIX.1\(hy2008 requires that an associated +.IR count +act on the next +.IR count +characters, and that the command move to subsequent lines if warranted +by +.IR count , +to make it possible to modify large pieces of text in a reasonably +efficient manner. There exist +.IR vi +implementations that optionally require an associated motion command +for the +.BR ~ +command. Implementations supporting this functionality are encouraged +to base it on the +.BR tildedop +edit option and handle the text regions and cursor positioning +identically to the +.BR yank +command. +.SS "Append" +.P +Historically, +.IR count s +specified to the +.BR A , +.BR a , +.BR I , +and +.BR i +commands repeated the input of the first line +.IR count +times, and did not repeat the subsequent lines of the input text. POSIX.1\(hy2008 +requires that the entire text input be repeated +.IR count +times. +.SS "Move Backward to Preceding Word" +.P +Historically, +.IR vi +became confused if word commands were used as motion commands in empty +files. POSIX.1\(hy2008 requires that this be an error. Historical implementations +of +.IR vi +had a large number of bugs in the word movement commands, and they +varied greatly in behavior in the presence of empty lines, ``words'' +made up of a single character, and lines containing only + +characters. For consistency and simplicity of specification, POSIX.1\(hy2008 does +not permit this behavior. +.SS "Change to End-of-Line" +.P +Some historical implementations of the +.BR C +command did not behave as described by POSIX.1\(hy2008 when the +.BR $ +key was remapped because they were implemented by pushing the +.BR $ +key onto the input queue and reprocessing it. POSIX.1\(hy2008 does not permit +this behavior. Historically, the +.BR C , +.BR S , +and +.BR s +commands did not copy replaced text into the numeric buffers. For +consistency and simplicity of specification, POSIX.1\(hy2008 requires that they +behave like their respective +.BR c +commands in all respects. +.SS "Delete" +.P +Historically, lines in open mode that were deleted were scrolled up, +and an +.BR @ +glyph written over the beginning of the line. In the case of terminals +that are incapable of the necessary cursor motions, the editor erased +the deleted line from the screen. POSIX.1\(hy2008 requires conformance to +historical practice; that is, if the terminal cannot display the +.BR '@' +character, the line cannot remain on the screen. +.SS "Delete to End-of-Line" +.P +Some historical implementations of the +.BR D +command did not behave as described by POSIX.1\(hy2008 when the +.BR $ +key was remapped because they were implemented by pushing the +.BR $ +key onto the input queue and reprocessing it. POSIX.1\(hy2008 does not permit +this behavior. +.SS "Join" +.P +An historical oddity of +.IR vi +is that the commands +.BR J , +.BR 1J , +and +.BR 2J +are all equivalent. POSIX.1\(hy2008 requires conformance to historical practice. +The +.IR vi +.BR J +command is specified in terms of the +.IR ex +.BR join +command with an +.IR ex +command +.IR count +value. The address correction for a +.IR count +that is past the end of the edit buffer is necessary for historical +compatibility for both +.IR ex +and +.IR vi . +.SS "Mark Position" +.P +Historical practice is that only lowercase letters, plus backquote and +single-quote, could be used to mark a cursor position. POSIX.1\(hy2008 requires +conformance to historical practice, but encourages implementations to +support other characters as marks as well. +.SS "Repeat Regular Expression Find (Forward and Reverse)" +.P +Historically, the +.BR N +and +.BR n +commands could not be used as motion components for the +.BR c +command. With the exception of the +.BR cN +command, which worked if the search crossed a line boundary, the text +region would be discarded, and the user would not be in text input +mode. For consistency and simplicity of specification, POSIX.1\(hy2008 does not +permit this behavior. +.SS "Insert Empty Line (Below and Above)" +.P +Historically, counts to the +.BR O +and +.BR o +commands were used as the number of physical lines to open, if the +terminal was dumb and the +.BR slowopen +option was not set. This was intended to minimize traffic over slow +connections and repainting for dumb terminals. POSIX.1\(hy2008 does not permit +this behavior, requiring that a +.IR count +to the open command behave as for other text input commands. This +change to historical practice was made for consistency, and because a +superset of the functionality is provided by the +.BR slowopen +edit option. +.SS "Put from Buffer (Following and Before)" +.P +Historically, +.IR count s +to the +.BR p +and +.BR P +commands were ignored if the buffer was a line mode buffer, but were +(mostly) implemented as described in POSIX.1\(hy2008 if the buffer was a +character mode buffer. Because implementations exist that do not have +this limitation, and because pasting lines multiple times is generally +useful, POSIX.1\(hy2008 requires that +.IR count +be supported for all +.BR p +and +.BR P +commands. +.P +Historical implementations of +.IR vi +were widely known to have major problems in the +.BR p +and +.BR P +commands, particularly when unusual regions of text were copied into +the edit buffer. The standard developers viewed these as bugs, and they +are not permitted for consistency and simplicity of specification. +.P +Historically, a +.BR P +or +.BR p +command (or an +.IR ex +.BR put +command executed from open or visual mode) executed in an empty file, +left an empty line as the first line of the file. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.SS "Replace Character" +.P +Historically, the +.BR r +command did not correctly handle the +.IR erase +and +.IR "word erase" +characters as arguments, nor did it handle an associated +.IR count +greater than 1 with a + +argument, for which it replaced +.IR count +characters with a single +. +POSIX.1\(hy2008 does not permit these inconsistencies. +.P +Historically, the +.BR r +command permitted the +\(hyV +escaping of entered characters, such as + +and the +; +however, it required two leading +\(hyV +characters instead of one. POSIX.1\(hy2008 requires that this be changed for +consistency with the other text input commands of +.IR vi . +.P +Historically, it is an error to enter the +.BR r +command if there are less than +.IR count +characters at or after the cursor in the line. While a reasonable and +unambiguous extension would be to permit the +.BR r +command on empty lines, it would require that too large a +.IR count +be adjusted to match the number of characters at or after the cursor +for consistency, which is sufficiently different from historical +practice to be avoided. POSIX.1\(hy2008 requires conformance to historical +practice. +.SS "Replace Characters" +.P +Historically, if there were +.BR autoindent +characters in the line on which the +.BR R +command was run, and +.BR autoindent +was set, the first + +would be properly indented and no characters would be replaced by the +. +Each additional + +would replace +.IR n +characters, where +.IR n +was the number of characters that were needed to indent the rest of the +line to the proper indentation level. This behavior is a bug and is not +permitted by POSIX.1\(hy2008. +.SS "Undo" +.P +Historical practice for cursor positioning after undoing commands was +mixed. In most cases, when undoing commands that affected a single +line, the cursor was moved to the start of added or changed text, or +immediately after deleted text. However, if the user had moved from the +line being changed, the column was either set to the first non-\c +, +returned to the origin of the command, or remained unchanged. When +undoing commands that affected multiple lines or entire lines, the +cursor was moved to the first character in the first line restored. As +an example of how inconsistent this was, a search, followed by an +.BR o +text input command, followed by an +.BR undo +would return the cursor to the location where the +.BR o +command was entered, but a +.BR cw +command followed by an +.BR o +command followed by an +.BR undo +would return the cursor to the first non-\c + +of the line. POSIX.1\(hy2008 requires the most useful of these behaviors, and +discards the least useful, in the interest of consistency and +simplicity of specification. +.SS "Yank" +.P +Historically, the +.BR yank +command did not move to the end of the motion if the motion was in the +forward direction. It moved to the end of the motion if the motion was +in the backward direction, except for the +.BR _ +command, or for the +.BR G +and +.BR ' +commands when the end of the motion was on the current line. This was +further complicated by the fact that for a number of motion commands, +the +.BR yank +command moved the cursor but did not update the screen; for example, a +subsequent command would move the cursor from the end of the motion, +even though the cursor on the screen had not reflected the cursor +movement for the +.BR yank +command. POSIX.1\(hy2008 requires that all +.BR yank +commands associated with backward motions move the cursor to the end of +the motion for consistency, and specifically, to make +.BR ' +commands as motions consistent with search patterns as motions. +.SS "Yank Current Line" +.P +Some historical implementations of the +.BR Y +command did not behave as described by POSIX.1\(hy2008 when the +.BR '_' +key was remapped because they were implemented by pushing the +.BR '_' +key onto the input queue and reprocessing it. POSIX.1\(hy2008 does not permit +this behavior. +.SS "Redraw Window" +.P +Historically, the +.BR z +command always redrew the screen. This is permitted but not required by +POSIX.1\(hy2008, because of the frequent use of the +.BR z +command in macros such as +.BR "map n nz." +for screen positioning, instead of its use to change the screen size. +The standard developers believed that expanding or scrolling the screen +offered a better interface for users. The ability to redraw the screen +is preserved if the optional new window size is specified, and in the +\(hyL +and +\(hyR +commands. +.P +The semantics of +.BR z^ +are confusing at best. Historical practice is that the screen before +the screen that ended with the specified line is displayed. POSIX.1\(hy2008 +requires conformance to historical practice. +.P +Historically, the +.BR z +command would not display a partial line at the top or bottom of the +screen. If the partial line would normally have been displayed at the +bottom of the screen, the command worked, but the partial line was +replaced with +.BR '@' +characters. If the partial line would normally have been displayed at +the top of the screen, the command would fail. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR z +command with a line specification of 1 ignored the command. For +consistency and simplicity of specification, POSIX.1\(hy2008 does not permit this +behavior. +.P +Historically, the +.BR z +command did not set the cursor column to the first non-\c + +for the character if the first screen was to be displayed, and was +already displayed. For consistency and simplicity of specification, +POSIX.1\(hy2008 does not permit this behavior. +.SS "Input Mode Commands in vi" +.P +Historical implementations of +.IR vi +did not permit the user to erase more than a single line of input, +or to use normal erase characters such as +.IR "line erase" , +.IR worderase , +and +.IR erase +to erase +.BR autoindent +characters. As there exist implementations of +.IR vi +that do not have these limitations, both behaviors are permitted, but +only historical practice is required. In the case of these extensions, +.IR vi +is required to pause at the +.BR autoindent +and previous line boundaries. +.P +Historical implementations of +.IR vi +updated only the portion of the screen where the current cursor +character was displayed. For example, consider the +.IR vi +input keystrokes: +.sp +.RS 4 +.nf +\fB +iabcd0C +.fi \fR +.P +.RE +.P +Historically, the + +would overwrite the characters +.BR \(dqabcd\(dq +when it was displayed. Other implementations replace only the +.BR 'a' +character with the +, +and then push the rest of the characters ahead of the cursor. Both +implementations have problems. The historical implementation is +probably visually nicer for the above example; however, for the +keystrokes: +.sp +.RS 4 +.nf +\fB +iabcd0R +.fi \fR +.P +.RE +.P +the historical implementation results in the string +.BR \(dqbcd\(dq +disappearing and then magically reappearing when the + +character is entered. POSIX.1\(hy2008 requires the former behavior when +overwriting erase-columns\(emthat is, overwriting characters that are no +longer logically part of the edit buffer\(emand the latter behavior +otherwise. +.P +Historical implementations of +.IR vi +discarded the +\(hyD +and +\(hyT +characters when they were entered at places where their command +functionality was not appropriate. POSIX.1\(hy2008 requires that the +\(hyT +functionality always be available, and that +\(hyD +be treated as any other key when not operating on +.BR autoindent +characters. +.SS "NUL" +.P +Some historical implementations of +.IR vi +limited the number of characters entered using the NUL input character +to 256 bytes. POSIX.1\(hy2008 permits this limitation; however, implementations +are encouraged to remove this limit. +.SS "\(hyD" +.P +See also Rationale for the input mode command +. +The hidden assumptions in the +\(hyD +command (and in the +.IR vi +.BR autoindent +specification in general) is that + +characters take up a single column on the screen and that + +characters are comprised of an integral number of + +characters. +.SS "" +.P +Implementations are permitted to rewrite +.BR autoindent +characters in the line when +, +, +\(hyD, +and +\(hyT +are entered, or when the +.BR shift +commands are used, because historical implementations have both done so +and found it necessary to do so. For example, a +\(hyD +when the cursor is preceded by a single +, +with +.BR tabstop +set to 8, and +.BR shiftwidth +set to 3, will result in the + +being replaced by several + +characters. +.SS "\(hyT" +.P +See also the Rationale for the input mode command +. +Historically, +\(hyT +only worked if no non-\c + +characters had yet been input in the current input line. In addition, +the characters inserted by +\(hyT +were treated as +.BR autoindent +characters, and could not be erased using normal user erase characters. +Because implementations exist that do not have these limitations, and +as moving to a column boundary is generally useful, POSIX.1\(hy2008 requires that +both limitations be removed. +.SS "\(hyV" +.P +Historically, +.IR vi +used +.BR ^V , +regardless of the value of the literal-next character of the terminal. +POSIX.1\(hy2008 requires conformance to historical practice. +.P +The uses described for +\(hyV +can also be accomplished with +\(hyQ, +which is useful on terminals that use +\(hyV +for the down-arrow function. However, most historical implementations +use +\(hyQ +for the +.IR termios +START character, so the editor will generally not receive the +\(hyQ +unless +.BR "stty ixon" +mode is set to off. (In addition, some historical implementations of +.IR vi +explicitly set +.BR ixon +mode to on, so it was difficult for the user to set it to off.) Any of +the command characters described in POSIX.1\(hy2008 can be made ineffective by +their selection as +.IR termios +control characters, using the +.IR stty +utility or other methods described in the System Interfaces volume of POSIX.1\(hy2008. +.SS "" +.P +Historically, SIGINT alerted the terminal when used to end input +mode. This behavior is permitted, but not required, by POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIed\fR\^", +.IR "\fIex\fR\^", +.IR "\fIstty\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/wait.1p b/man-pages-posix-2013-a/man1p/wait.1p new file mode 100644 index 0000000..6c7fe6b --- /dev/null +++ b/man-pages-posix-2013-a/man1p/wait.1p @@ -0,0 +1,346 @@ +'\" et +.TH WAIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wait +\(em await process completion +.SH SYNOPSIS +.LP +.nf +wait \fB[\fIpid\fR...\fB]\fR +.fi +.SH DESCRIPTION +When an asynchronous list (see +.IR "Section 2.9.3.1" ", " "Examples") +is started by the shell, the process ID of the last command in each +element of the asynchronous list shall become known in the current +shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +If the +.IR wait +utility is invoked with no operands, it shall wait until all process +IDs known to the invoking shell have terminated and exit with a zero +exit status. +.P +If one or more +.IR pid +operands are specified that represent known process IDs, the +.IR wait +utility shall wait until all of them have terminated. If one or more +.IR pid +operands are specified that represent unknown process IDs, +.IR wait +shall treat them as if they were known process IDs that exited with +exit status 127. The exit status returned by the +.IR wait +utility shall be the exit status of the process requested by the last +.IR pid +operand. +.P +The known process IDs are applicable only for invocations of +.IR wait +in the current shell execution environment. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIpid\fR" 10 +One of the following: +.RS 10 +.IP " 1." 4 +The unsigned decimal integer process ID of a command, for which the +utility is to wait for the termination. +.IP " 2." 4 +A job control job ID (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID") +that identifies a background process group to be waited for. The job +control job ID notation is applicable only for invocations of +.IR wait +in the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +The exit status of +.IR wait +shall be determined by the last command in the pipeline. +.RS 4 +.TP 10 +.BR Note: +The job control job ID type of +.IR pid +is only available on systems supporting the User Portability Utilities +option. +.P +.RE +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR wait : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If one or more operands were specified, all of them have terminated or +were not known by the invoking shell, and the status of the last +operand specified is known, then the exit status of +.IR wait +shall be the exit status information of the command indicated by the +last operand specified. If the process terminated abnormally due to +the receipt of a signal, the exit status shall be greater than 128 and +shall be distinct from the exit status generated by other signals, but +the exact value is unspecified. (See the +.IR kill +.BR \(mil +option.) Otherwise, the +.IR wait +utility shall exit with one of the following values: +.IP "\0\0\0\00" 8 +The +.IR wait +utility was invoked with no operands and all process IDs known by the +invoking shell have terminated. +.IP "1\(hy126" 8 +The +.IR wait +utility detected an error. +.IP "\0\0127" 8 +The command identified by the last +.IR pid +operand specified is unknown. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +On most implementations, +.IR wait +is a shell built-in. If it is called in a subshell or separate utility +execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(wait) +nohup wait ... +find . \(miexec wait ... \e; +.fi \fR +.P +.RE +.P +it returns immediately because there are no known process IDs to wait +for in those environments. +.P +Historical implementations of interactive shells have discarded the +exit status of terminated background processes before each shell +prompt. Therefore, the status of background processes was usually lost +unless it terminated while +.IR wait +was waiting for it. This could be a serious problem when a job that +was expected to run for a long time actually terminated quickly with a +syntax or initialization error because the exit status returned was +usually zero if the requested process ID was not found. This volume of POSIX.1\(hy2008 requires +the implementation to keep the status of terminated jobs available +until the status is requested, so that scripts like: +.sp +.RS 4 +.nf +\fB +j1& +p1=$! +j2& +wait $p1 +echo Job 1 exited with status $? +wait $! +echo Job 2 exited with status $? +.fi \fR +.P +.RE +.P +work without losing status on any of the jobs. The shell is allowed to +discard the status of any process if it determines that the application +cannot get the process ID for that process from the shell. It is also +required to remember only +{CHILD_MAX} +number of processes in this way. Since the only way to get the process +ID from the shell is by using the +.BR '!' +shell parameter, the shell is allowed to discard the status of an +asynchronous list if +.BR \(dq$!\(dq +was not referenced before another asynchronous list was started. (This +means that the shell only has to keep the status of the last +asynchronous list started if the application did not reference +.BR \(dq$!\(dq . +If the implementation of the shell is smart enough to determine that a +reference to +.BR \(dq$!\(dq +was not saved anywhere that the application can retrieve it later, it +can use this information to trim the list of saved information. Note +also that a successful call to +.IR wait +with no operands discards the exit status of all asynchronous lists.) +.P +If the exit status of +.IR wait +is greater than 128, there is no way for the application to know if the +waited-for process exited with that value or was killed by a signal. +Since most utilities exit with small values, there is seldom any +ambiguity. Even in the ambiguous cases, most applications just need to +know that the asynchronous job failed; it does not matter whether it +detected an error and failed or was killed and did not complete its job +normally. +.SH EXAMPLES +Although the exact value used when a process is terminated by a signal +is unspecified, if it is known that a signal terminated a process, a +script can still reliably determine which signal by using +.IR kill +as shown by the following script: +.sp +.RS 4 +.nf +\fB +sleep 1000& +pid=$! +kill \(mikill $pid +wait $pid +echo $pid was terminated by a SIG$(kill \(mil $?) signal. +.fi \fR +.P +.RE +.P +If the following sequence of commands is run in less than 31 seconds: +.sp +.RS 4 +.nf +\fB +sleep 257 | sleep 31 & +jobs \(mil %% +.fi \fR +.P +.RE +.P +either of the following commands returns the exit status of the second +.IR sleep +in the pipeline: +.sp +.RS 4 +.nf +\fB +wait \fI\fP +wait %% +.fi \fR +.P +.RE +.SH RATIONALE +The description of +.IR wait +does not refer to the +\fIwaitpid\fR() +function from the System Interfaces volume of POSIX.1\(hy2008 because that would needlessly overspecify this +interface. However, the wording means that +.IR wait +is required to wait for an explicit process when it is given an +argument so that the status information of other processes is not +consumed. Historical implementations use the +\fIwait\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 until +\fIwait\fR() +returns the requested process ID or finds that the requested process +does not exist. Because this means that a shell script could not +reliably get the status of all background children if a second +background job was ever started before the first job finished, it is +recommended that the +.IR wait +utility use a method such as the functionality provided by the +\fIwaitpid\fR() +function. +.P +The ability to wait for multiple +.IR pid +operands was adopted from the KornShell. +.P +This new functionality was added because it is needed to determine the +exit status of any asynchronous list accurately. The only +compatibility problem that this change creates is for a script like +.sp +.RS 4 +.nf +\fB +while sleep 60 do + job& echo Job started $(date) as $! done +.fi \fR +.P +.RE +.P +which causes the shell to monitor all of the jobs started until the +script terminates or runs out of memory. This would not be a problem +if the loop did not reference +.BR \(dq$!\(dq +or if the script would occasionally +.IR wait +for jobs it started. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIkill\fR\^", +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIwait\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/wc.1p b/man-pages-posix-2013-a/man1p/wc.1p new file mode 100644 index 0000000..2de8551 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/wc.1p @@ -0,0 +1,264 @@ +'\" et +.TH WC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wc +\(em word, line, and byte or character count +.SH SYNOPSIS +.LP +.nf +wc \fB[\fR\(mic|\(mim\fB] [\fR\(milw\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR wc +utility shall read one or more input files and, by default, write the +number of + +characters, words, and bytes contained in each input file to the standard +output. +.P +The utility also shall write a total count for all named files, if more +than one input file is specified. +.P +The +.IR wc +utility shall consider a +.IR word +to be a non-zero-length string of characters delimited by white space. +.SH OPTIONS +The +.IR wc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Write to the standard output the number of bytes in each input file. +.IP "\fB\(mil\fP" 10 +Write to the standard output the number of + +characters in each input file. +.IP "\fB\(mim\fP" 10 +Write to the standard output the number of characters in each input +file. +.IP "\fB\(miw\fP" 10 +Write to the standard output the number of words in each input file. +.P +When any option is specified, +.IR wc +shall report only the information requested by the specified options. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files may be of any type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR wc : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and which +characters are defined as white-space characters. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +By default, the standard output shall contain an entry for each input +file of the form: +.sp +.RS 4 +.nf +\fB +"%d %d %d %s\en", <\fInewlines\fR>, <\fIwords\fR>, <\fIbytes\fR>, <\fIfile\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mim +option is specified, the number of characters shall replace the +<\fIbytes\fP> field in this format. +.P +If any options are specified and the +.BR \(mil +option is not specified, the number of + +characters shall not be written. +.P +If any options are specified and the +.BR \(miw +option is not specified, the number of words shall not be written. +.P +If any options are specified and neither +.BR \(mic +nor +.BR \(mim +is specified, the number of bytes or characters shall not be written. +.P +If no input +.IR file +operands are specified, no name shall be written and no + +characters preceding the pathname shall be written. +.P +If more than one input +.IR file +operand is specified, an additional line shall be written, of the same +format as the other lines, except that the word +.BR total +(in the POSIX locale) shall be written instead of a pathname and the +total of each column shall be written as appropriate. Such an +additional line, if any, is written at the end of the output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mim +option is not a switch, but an option at the same level as +.BR \(mic . +Thus, to produce the full default output with character counts instead +of bytes, the command required is: +.sp +.RS 4 +.nf +\fB +wc \(mimlw +.fi \fR +.P +.RE +.SH EXAMPLES +None. +.SH RATIONALE +The output file format pseudo-\c +\fIprintf\fR() +string differs from the System V version of +.IR wc : +.sp +.RS 4 +.nf +\fB +"%7d%7d%7d %s\en" +.fi \fR +.P +.RE +.P +which produces possibly ambiguous and unparsable results for very large +files, as it assumes no number shall exceed six digits. +.P +Some historical implementations use only +, +, +and + +as word separators. The equivalent of the ISO\ C standard +\fIisspace\fR() +function is more appropriate. +.P +The +.BR \(mic +option stands for ``character'' count, even though it counts bytes. +This stems from the sometimes erroneous historical view that bytes and +characters are the same size. Due to international requirements, the +.BR \(mim +option (reminiscent of ``multi-byte'') was added to obtain actual +character counts. +.P +Early proposals only specified the results when input files were text +files. The current specification more closely matches historical +practice. (Bytes, words, and + +characters are counted separately and the results are written when an +end-of-file is detected.) +.P +Historical implementations of the +.IR wc +utility only accepted one argument to specify the options +.BR \(mic , +.BR \(mil , +and +.BR \(miw . +Some of them also had multiple occurrences of an option cause the +corresponding count to be written multiple times and had the order of +specification of the options affect the order of the fields on output, +but did not document either of these. Because common usage either +specifies no options or only one option, and because none of this was +documented, the changes required by this volume of POSIX.1\(hy2008 should not break many +historical applications (and do not break any historical conforming +applications). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcksum\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/what.1p b/man-pages-posix-2013-a/man1p/what.1p new file mode 100644 index 0000000..b8fbf3e --- /dev/null +++ b/man-pages-posix-2013-a/man1p/what.1p @@ -0,0 +1,193 @@ +'\" et +.TH WHAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +what +\(em identify SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +what \fB[\fR\(mis\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR what +utility shall search the given files for all occurrences of the pattern +that +.IR get +(see +.IR "\fIget\fR\^") +substitutes for the %\fBZ\fP% keyword (\c +.BR \(dq@(#)\(dq ) +and shall write to standard output what follows until the first +occurrence of one of the following: +.sp +.RS 4 +.nf +\fB +\&" > newline \e NUL +.fi \fR +.P +.RE +.SH OPTIONS +The +.IR what +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mis\fP" 10 +Quit after finding the first occurrence of the pattern in each file. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to search. +.SH STDIN +Not used. +.SH "INPUT FILES" +The input files shall be of any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR what : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall consist of the following for each +.IR file +operand: +.sp +.RS 4 +.nf +\fB +"%s:\en\et%s\en", <\fIpathname\fR>, <\fIidentification string\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP 0 6 +Any matches were found. +.IP 1 6 +Otherwise. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR what +utility is intended to be used in conjunction with the SCCS command +.IR get , +which automatically inserts identifying information, but it can also be +used where the information is inserted by any other means. +.P +When the string +.BR \(dq@(#)\(dq +is included in a library routine in a shared library, it might not be +found in an +.BR a.out +file using that library routine. +.SH EXAMPLES +If the C-language program in file +.BR f.c +contains: +.sp +.RS 4 +.nf +\fB +char ident[] = "@(#)identification information"; +.fi \fR +.P +.RE +.P +and +.BR f.c +is compiled to yield +.BR f.o +and +.BR a.out , +then the command: +.sp +.RS 4 +.nf +\fB +what f.c f.o a.out +.fi \fR +.P +.RE +.P +writes: +.sp +.RS 4 +.nf +\fB +f.c: + identification information + ... +f.o: + identification information + ... +a.out: + identification information + ... +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIget\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/who.1p b/man-pages-posix-2013-a/man1p/who.1p new file mode 100644 index 0000000..1bdfeb1 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/who.1p @@ -0,0 +1,315 @@ +'\" et +.TH WHO "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +who +\(em display who is on the system +.SH SYNOPSIS +.LP +.nf +who \fB[\fR\(mimTu\fB] [\fR\(miabdHlprt\fB] [\fIfile\fB]\fR +.P +who \fB[\fR\(mimu\fB] \fR\(mis\fB [\fR\(mibHlprt\fB] [\fIfile\fB]\fR +.P +who \(miq \fB[\fIfile\fB]\fR +.P +who am i +.P +who am I +.fi +.SH DESCRIPTION +The +.IR who +utility shall list various pieces of information about accessible +users. The domain of accessibility is implementation-defined. +.P +Based on the options given, +.IR who +can also list the user's name, terminal line, login time, elapsed time +since activity occurred on the line, and the process ID of the command +interpreter for each current system user. +.SH OPTIONS +The +.IR who +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported. The metavariables, such as +<\fIline\fP>, refer to fields described in the STDOUT section. +.IP "\fB\(mia\fP" 10 +Process the implementation-defined database or named file with the +.BR \(mib , +.BR \(mid , +.BR \(mil , +.BR \(mip , +.BR \(mir , +.BR \(mit , +.BR \(miT +and +.BR \(miu +options turned on. +.IP "\fB\(mib\fP" 10 +Write the time and date of the last system reboot. The system reboot +time is the time at which the implementation is able to commence +running processes. +.IP "\fB\(mid\fP" 10 +Write a list of all processes that have expired and not been respawned +by the +.IR init +system process. The <\fIexit\fP> field shall appear for dead processes +and contain the termination and exit values of the dead process. This +can be useful in determining why a process terminated. +.IP "\fB\(miH\fP" 10 +Write column headings above the regular output. +.IP "\fB\(mil\fP" 10 +(The letter ell.) List only those lines on which the system is waiting +for someone to login. The <\fIname\fP> field shall be +.BR LOGIN +in such cases. Other fields shall be the same as for user entries +except that the <\fIstate\fP> field does not exist. +.IP "\fB\(mim\fP" 10 +Output only information about the current terminal. +.IP "\fB\(mip\fP" 10 +List any other process that is currently active and has been previously +spawned by +.IR init . +.IP "\fB\(miq\fP" 10 +(Quick.) List only the names and the number of users currently logged +on. When this option is used, all other options shall be ignored. +.IP "\fB\(mir\fP" 10 +Write the current +.IR run-level +of the +.IR init +process. +.IP "\fB\(mis\fP" 10 +List only the <\fIname\fR>, <\fIline\fR>, and <\fItime\fR> fields. +This is the default case. +.IP "\fB\(mit\fP" 10 +Indicate the last change to the system clock. +.IP "\fB\(miT\fP" 10 +Show the state of each terminal, as described in the STDOUT section. +.IP "\fB\(miu\fP" 10 +Write ``idle time'' for each displayed user in addition to any other +information. The idle time is the time since any activity occurred on +the user's terminal. The method of determining this is unspecified. +This option shall list only those users who are currently logged in. +The <\fIname\fP> is the user's login name. The <\fIline\fP> is the name +of the line as found in the directory +.BR /dev . +The <\fItime\fP> is the time that the user logged in. The +<\fIactivity\fP> is the number of hours and minutes since activity last +occurred on that particular line. A dot indicates that the terminal has +seen activity in the last minute and is therefore ``current''. If more +than twenty-four hours have elapsed or the line has not been used since +boot time, the entry shall be marked <\fIold\fP>. This field is useful +when trying to determine whether a person is working at the terminal or +not. The <\fIpid\fP> is the process ID of the user's login process. +.SH OPERANDS +The following operands shall be supported: +.IP "\fBam\ i\fR,\ \fBam\ I\fR" 10 +In the POSIX locale, limit the output to describing the invoking user, +equivalent to the +.BR \(mim +option. The +.BR am +and +.BR i +or +.BR I +must be separate arguments. +.IP "\fIfile\fR" 10 +Specify a pathname of a file to substitute for the +implementation-defined database of logged-on users that +.IR who +uses by default. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR who : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the locale used for the format and contents of the date and +time strings. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used when writing date and time information. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR who +utility shall write its default format to the standard output in an +implementation-defined format, subject only to the requirement of +containing the information described above. +.P +XSI-conformant systems shall write the default information to the +standard output in the following general format: +.sp +.RS 4 +.nf +\fB +<\fIname\fR>\fB[\fR<\fIstate\fR>\fB]\fR<\fIline\fR><\fItime\fR>\fB[\fR<\fIactivity\fR>\fB][\fR<\fIpid\fR>\fB][\fR<\fIcomment\fR>\fB][\fR<\fIexit\fR>\fB]\fR +.fi \fR +.P +.RE +.P +For the +.BR \(mib +option, <\fIline\fP> shall be +.BR \(dqsystem boot\(dq . +The <\fIname\fP> is unspecified. +.P +The following format shall be used for the +.BR \(miT +option: +.sp +.RS 4 +.nf +\fB +"%s %c %s %s\en" <\fIname\fR>, <\fIterminal state\fR>, <\fIterminal name\fR>, + <\fItime of login\fR> +.fi \fR +.P +.RE +.P +where <\fIterminal\ state\fP> is one of the following characters: +.IP "\fR+\fR" 8 +The terminal allows write access to other users. +.IP "\fR\(mi\fR" 8 +The terminal denies write access to other users. +.IP "\fR?\fR" 8 +The terminal write-access state cannot be determined. +.IP "\fR\fR" 8 +This entry is not associated with a terminal. +.P +In the POSIX locale, the <\fItime\ of\ login\fP> shall be equivalent in +format to the output of: +.sp +.RS 4 +.nf +\fB +date +"%b %e %H:%M" +.fi \fR +.P +.RE +.P +If the +.BR \(miu +option is used with +.BR \(miT , +the idle time shall be added to the end of the previous format in an +unspecified format. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The name +.IR init +used for the system process is the most commonly used on historical +systems, but it may vary. +.P +The ``domain of accessibility'' referred to is a broad concept that +permits interpretation either on a very secure basis or even to allow a +network-wide implementation like the historical +.IR rwho . +.SH EXAMPLES +None. +.SH RATIONALE +Due to differences between historical implementations, the base options +provided were a compromise to allow users to work with those +functions. The standard developers also considered removing all the +options, but felt that these options offered users valuable +functionality. Additional options to match historical systems are +available on XSI-conformant systems. +.P +It is recognized that the +.IR who +command may be of limited usefulness, especially in a multi-level +secure environment. The standard developers considered, however, that +having some standard method of determining the ``accessibility'' of +other users would aid user portability. +.P +No format was specified for the default +.IR who +output for systems not supporting the XSI option. In such a +user-oriented command, designed only for human use, this was not +considered to be a deficiency. +.P +The format of the terminal name is unspecified, but the descriptions of +.IR ps , +.IR talk , +and +.IR write +require that they use the same format. +.P +It is acceptable for an implementation to produce no output for +an invocation of +.IR who +.BR mil . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImesg\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/write.1p b/man-pages-posix-2013-a/man1p/write.1p new file mode 100644 index 0000000..c2f1a75 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/write.1p @@ -0,0 +1,232 @@ +'\" et +.TH WRITE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +write +\(em write to another user +.SH SYNOPSIS +.LP +.nf +write \fIuser_name \fB[\fIterminal\fB]\fR +.fi +.SH DESCRIPTION +The +.IR write +utility shall read lines from the standard input and write them +to the terminal of the specified user. When first invoked, it shall +write the message: +.sp +.RS 4 +.nf +\fB +\fBMessage from \fIsender-login-id\fR (\fIsending-terminal\fR) \fB[\fIdate\fB]\fR... +.fi \fR +.P +.RE +.P +to +.IR user_name . +When it has successfully completed the connection, the sender's +terminal shall be alerted twice to indicate that what the sender is +typing is being written to the recipient's terminal. +.P +If the recipient wants to reply, this can be accomplished by typing: +.sp +.RS 4 +.nf +\fB +write \fIsender-login-id \fB[\fIsending-terminal\fB]\fR +.fi \fR +.P +.RE +.P +upon receipt of the initial message. Whenever a line of input as +delimited by an NL, EOF, or EOL special character (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface") +is accumulated while in canonical input mode, the accumulated data shall +be written on the other user's terminal. Characters shall be processed +as follows: +.IP " *" 4 +Typing + +shall write the + +character to the recipient's terminal. +.IP " *" 4 +Typing the erase and kill characters shall affect the sender's terminal +in the manner described by the +.BR termios +interface in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP " *" 4 +Typing the interrupt or end-of-file characters shall cause +.IR write +to write an appropriate message (\c +.BR \(dqEOT\en\(dq +in the POSIX locale) to the recipient's terminal and exit. +.IP " *" 4 +Typing characters from +.IR LC_CTYPE +classifications +.BR print +or +.BR space +shall cause those characters to be sent to the recipient's terminal. +.IP " *" 4 +When and only when the +.IR stty +.BR iexten +local mode is enabled, the existence and processing of additional +special control characters and multi-byte or single-byte functions is +implementation-defined. +.IP " *" 4 +Typing other non-printable characters shall cause +implementation-defined sequences of printable characters to be +written to the recipient's terminal. +.P +To write to a user who is logged in more than once, the +.IR terminal +argument can be used to indicate which terminal to write to; otherwise, +the recipient's terminal is selected in an implementation-defined +manner and an informational message is written to the sender's standard +output, indicating which terminal was chosen. +.P +Permission to be a recipient of a +.IR write +message can be denied or granted by use of the +.IR mesg +utility. However, a user's privilege may further constrain the domain +of accessibility of other users' terminals. The +.IR write +utility shall fail when the user lacks appropriate privileges to +perform the requested action. +.SH OPTIONS +None. +.SH OPERANDS +.br +The following operands shall be supported: +.IP "\fIuser_name\fR" 10 +Login name of the person to whom the message shall be written. The +application shall ensure that this operand is of the form returned by +the +.IR who +utility. +.IP "\fIterminal\fR" 10 +Terminal identification in the same format provided by the +.IR who +utility. +.SH STDIN +Lines to be copied to the recipient's terminal are read from standard +input. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR write : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). If the +recipient's locale does not use an +.IR LC_CTYPE +equivalent to the sender's, the results are undefined. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +If an interrupt signal is received, +.IR write +shall write an appropriate message on the recipient's terminal and +exit with a status of zero. It shall take the standard action for all +other signals. +.SH STDOUT +An informational message shall be written to standard output if a +recipient is logged in more than once. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The recipient's terminal is used for output. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +The addressed user is not logged on or the addressed user denies +permission. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR talk +utility is considered by some users to be a more usable utility on +full-screen terminals. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR write +utility was included in this volume of POSIX.1\(hy2008 since it can be implemented on all +terminal types. The standard developers considered the +.IR talk +utility, which cannot be implemented on certain terminals, to be a +``better'' communications interface. Both of these programs are in +widespread use on historical implementations. Therefore, the standard +developers decided that both utilities should be specified. +.P +The format of the terminal name is unspecified, but the descriptions of +.IR ps , +.IR talk , +.IR who , +and +.IR write +require that they all use or accept the same format. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImesg\fR\^", +.IR "\fItalk\fR\^", +.IR "\fIwho\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/xargs.1p b/man-pages-posix-2013-a/man1p/xargs.1p new file mode 100644 index 0000000..507e93d --- /dev/null +++ b/man-pages-posix-2013-a/man1p/xargs.1p @@ -0,0 +1,749 @@ +'\" et +.TH XARGS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +xargs +\(em construct argument lists and invoke utility +.SH SYNOPSIS +.LP +.nf +xargs \fB[\fR\(miptx\fB] [\fR\(miE \fIeofstr\fB] [\fR\(miI \fIreplstr\fR|\(miL \fInumber\fR|\(min \fInumber\fB]\fR + \fB[\fR\(mis \fIsize\fB] [\fIutility \fB[\fIargument\fR...\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR xargs +utility shall construct a command line consisting of the +.IR utility +and +.IR argument +operands specified followed by as many arguments read in sequence from +standard input as fit in length and number constraints specified by the +options. The +.IR xargs +utility shall then invoke the constructed command line and wait for its +completion. This sequence shall be repeated until one of the following +occurs: +.IP " *" 4 +An end-of-file condition is detected on standard input. +.IP " *" 4 +An argument consisting of just the logical end-of-file string +(see the +.BR \(miE +.IR eofstr +option) is found on standard input after double-quote processing, + +processing, and +-escape +processing (see next paragraph). All arguments up to but not including +the argument consisting of just the logical end-of-file string shall be +used as arguments in constructed command lines. +.IP " *" 4 +An invocation of a constructed command line returns an exit status of +255. +.P +The application shall ensure that arguments in the standard input are +separated by unquoted + +characters, unescaped + +characters, or + +characters. A string of zero or more non-double-quote (\c +.BR '\&"' ) +characters and non-\c + +characters can be quoted by enclosing them in double-quotes. A string +of zero or more non-\c + +(\c +.BR '\e'' ) +characters and non-\c + +characters can be quoted by enclosing them in + +characters. Any unquoted character can be escaped by preceding it with a +. +The utility named by +.IR utility +shall be executed one or more times until the end-of-file is reached or +the logical end-of file string is found. The results are unspecified if +the utility named by +.IR utility +attempts to read from its standard input. +.P +The generated command line length shall be the sum of the size in bytes +of the utility name and each argument treated as strings, including a +null byte terminator for each of these strings. The +.IR xargs +utility shall limit the command line length such that when the command +line is invoked, the combined argument and environment lists (see the +.IR exec +family of functions in the System Interfaces volume of POSIX.1\(hy2008) shall not exceed +{ARG_MAX}\(mi2\|048 +bytes. Within this constraint, if neither the +.BR \(min +nor the +.BR \(mis +option is specified, the default command line length shall be at least +{LINE_MAX}. +.SH OPTIONS +The +.IR xargs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miE\ \fIeofstr\fR" 10 +Use +.IR eofstr +as the logical end-of-file string. If +.BR \(miE +is not specified, it is unspecified whether the logical end-of-file +string is the + +character (\c +.BR '_' ) +or the end-of-file string capability is disabled. When +.IR eofstr +is the null string, the logical end-of-file string capability shall be +disabled and + +characters shall be taken literally. +.IP "\fB\(miI\ \fIreplstr\fR" 10 +Insert mode: +.IR utility +is executed for each logical line from standard input. Arguments in the +standard input shall be separated only by unescaped + +characters, not by + +characters. Any unquoted unescaped + +characters at the beginning of each line shall be ignored. The resulting +argument shall be inserted in +.IR arguments +in place of each occurrence of +.IR replstr . +At least five arguments in +.IR arguments +can each contain one or more instances of +.IR replstr . +Each of these constructed arguments cannot grow larger than an +implementation-defined limit greater than or equal to 255 bytes. Option +.BR \(mix +shall be forced on. +.IP "\fB\(miL\ \fInumber\fR" 10 +The +.IR utility +shall be executed for each non-empty +.IR number +lines of arguments from standard input. The last invocation of +.IR utility +shall be with fewer lines of arguments if fewer than +.IR number +remain. A line is considered to end with the first + +unless the last character of the line is a +; +a trailing + +signals continuation to the next non-empty line, inclusive. +.IP "\fB\(min\ \fInumber\fR" 10 +Invoke +.IR utility +using as many standard input arguments as possible, up to +.IR number +(a positive decimal integer) arguments maximum. Fewer arguments shall +be used if: +.RS 10 +.IP " *" 4 +The command line length accumulated exceeds the size specified by the +.BR \(mis +option (or +{LINE_MAX} +if there is no +.BR \(mis +option). +.IP " *" 4 +The last iteration has fewer than +.IR number , +but not zero, operands remaining. +.RE +.IP "\fB\(mip\fP" 10 +Prompt mode: the user is asked whether to execute +.IR utility +at each invocation. Trace mode (\c +.BR \(mit ) +is turned on to write the command instance to be executed, followed by +a prompt to standard error. An affirmative response read from +.BR /dev/tty +shall execute the command; otherwise, that particular invocation of +.IR utility +shall be skipped. +.IP "\fB\(mis\ \fIsize\fR" 10 +Invoke +.IR utility +using as many standard input arguments as possible yielding a command +line length less than +.IR size +(a positive decimal integer) bytes. Fewer arguments shall be used if: +.RS 10 +.IP " *" 4 +The total number of arguments exceeds that specified by the +.BR \(min +option. +.IP " *" 4 +The total number of lines exceeds that specified by the +.BR \(miL +option. +.IP " *" 4 +End-of-file is encountered on standard input before +.IR size +bytes are accumulated. +.P +Values of +.IR size +up to at least +{LINE_MAX} +bytes shall be supported, provided that the constraints specified in +the DESCRIPTION are met. It shall not be considered an error if a +value larger than that supported by the implementation or exceeding the +constraints specified in the DESCRIPTION is given; +.IR xargs +shall use the largest value it supports within the constraints. +.RE +.IP "\fB\(mit\fP" 10 +Enable trace mode. Each generated command line shall be written to +standard error just prior to invocation. +.IP "\fB\(mix\fP" 10 +Terminate if a constructed command line will not fit in the +implied or specified size (see the +.BR \(mis +option above). +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of the utility to be invoked, found by search path using the +.IR PATH +environment variable, described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +If +.IR utility +is omitted, the default shall be the +.IR echo +utility. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +An initial option or operand for the invocation of +.IR utility . +.SH STDIN +The standard input shall be a text file. The results are unspecified if +an end-of-file condition is detected immediately following an escaped +. +.SH "INPUT FILES" +The file +.BR /dev/tty +shall be used to read responses required by the +.BR \(mip +option. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR xargs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of +.IR utility , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic messages and the +.BR \(mit +and +.BR \(mip +options. If the +.BR \(mit +option is specified, the +.IR utility +and its constructed argument list shall be written to standard error, +as it will be invoked, prior to invocation. If +.BR \(mip +is specified, a prompt of the following format shall be written (in the +POSIX locale): +.sp +.RS 4 +.nf +\fB +"?..." +.fi \fR +.P +.RE +.P +at the end of the line of the output from +.BR \(mit . +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\0\0\0\00" 8 +All invocations of +.IR utility +returned exit status zero. +.IP "1\(hy125" 8 +A command line meeting the specified requirements could not be +assembled, one or more of the invocations of +.IR utility +returned a non-zero exit status, or some other error occurred. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +If a command line meeting the specified requirements cannot be +assembled, the utility cannot be invoked, an invocation of the utility +is terminated by a signal, or an invocation of the utility exits with +exit status 255, the +.IR xargs +utility shall write a diagnostic message and exit without processing +any remaining input. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The 255 exit status allows a utility being used by +.IR xargs +to tell +.IR xargs +to terminate if it knows no further invocations using the current data +stream will succeed. Thus, +.IR utility +should explicitly +.IR exit +with an appropriate value to avoid accidentally returning with 255. +.P +Note that since input is parsed as lines, + +characters separate arguments, and +, +, +and double-quote characters are used for quoting, if +.IR xargs +is used to bundle the output of commands like +.IR find +.IR dir +.BR \(miprint +or +.IR ls +into commands to be executed, unexpected results are likely if any +filenames contain +, +, +or quoting characters. This can be solved by using find to call a script +that converts each file found into a quoted string that is then piped to +.IR xargs , +but in most cases it is preferable just to have +.IR find +do the argument aggregation itself by using +.BR \(miexec +with a +.BR '+' +terminator instead of +.BR ';' . +Note that the quoting rules used by +.IR xargs +are not the same as in the shell. They were not made consistent here +because existing applications depend on the current rules. An easy (but +inefficient) method that can be used to transform input consisting of +one argument per line into a quoted form that +.IR xargs +interprets correctly is to precede each non-\c + +character with a +. +More efficient alternatives are shown in Example 2 and Example 5 below. +.P +On implementations with a large value for +{ARG_MAX}, +.IR xargs +may produce command lines longer than +{LINE_MAX}. +For invocation of utilities, this is not a problem. If +.IR xargs +is being used to create a text file, users should explicitly set the +maximum command line length with the +.BR \(mis +option. +.P +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +.IP " 1." 4 +The following command combines the output of the parenthesized +commands (minus the + +characters) onto one line, which is then appended to the file log. It +assumes that the expansion of +.BR \(dq$0 $*\(dq +does not include any + +or + +characters. +.RS 4 +.sp +.RS 4 +.nf +\fB +(logname; date; printf "'%s'\en$0 $*") | xargs \(miE "" >>log +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following command invokes +.IR diff +with successive pairs of arguments originally typed as command line +arguments. It assumes there are no embedded + +characters in the elements of the original argument list. +.RS 4 +.sp +.RS 4 +.nf +\fB +printf "%s\en$@" | sed 's/[^[:alnum:]]/\e\e&/g' | + xargs \(miE "" \(min 2 \(mix diff +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +In the following commands, the user is asked which files in the current +directory (excluding dotfiles) are to be archived. The files are +archived into +.BR arch ; +.IR a , +one at a time or +.IR b , +many at a time. The commands assume that no filenames contain +, +, +, +, +or double-quote characters. +.RS 4 +.sp +.RS 4 +.nf +\fB +a. ls | xargs \(miE "" \(mip \(miL 1 ar \(mir arch +.P +b. ls | xargs \(miE "" \(mip \(miL 1 | xargs \(miE "" ar \(mir arch +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +The following command invokes +.IR command1 +one or more times with multiple arguments, stopping if an invocation of +.IR command1 +has a non-zero exit status. +.RS 4 +.sp +.RS 4 +.nf +\fB +xargs \(miE "" sh \(mic 'command1 "$@" || exit 255' sh < xargs_input +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +On XSI-conformant systems, the following command moves all files +from directory +.BR $1 +to directory +.BR $2 , +and echoes each move command just before doing it. It assumes no +filenames contain + +characters and that neither +.BR $1 +nor +.BR $2 +contains the sequence +.BR \(dq{}\(dq . +.RS 4 +.sp +.RS 4 +.nf +\fB +ls \(miA "$1" | sed \(mie 's/"/"\e\e""/g' \(mie 's/.*/"&"/' | + xargs \(miE "" \(miI {} \(mit mv "$1"/{} "$2"/{} +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR xargs +utility was usually found only in System V-based systems; BSD systems +included an +.IR apply +utility that provided functionality similar to +.IR xargs +.BR \(min +.IR number . +The SVID lists +.IR xargs +as a software development extension. This volume of POSIX.1\(hy2008 does not share the view that +it is used only for development, and therefore it is not optional. +.P +The classic application of the +.IR xargs +utility is in conjunction with the +.IR find +utility to reduce the number of processes launched by a simplistic use +of the +.IR find +.BR \(miexec +combination. The +.IR xargs +utility is also used to enforce an upper limit on memory required to +launch a process. With this basis in mind, this volume of POSIX.1\(hy2008 selected only the +minimal features required. +.P +Although the 255 exit status is mostly an accident of historical +implementations, it allows a utility being used by +.IR xargs +to tell +.IR xargs +to terminate if it knows no further invocations using the current data +stream shall succeed. Any non-zero exit status from a utility falls +into the 1\(hy125 range when +.IR xargs +exits. There is no statement of how the various non-zero utility exit +status codes are accumulated by +.IR xargs . +The value could be the addition of all codes, their highest value, the +last one received, or a single value such as 1. Since no algorithm is +arguably better than the others, and since many of the standard +utilities say little more (portably) than ``pass/fail'', no new +algorithm was invented. +.P +Several other +.IR xargs +options were removed because simple alternatives already exist within +\&this volume of POSIX.1\(hy2008. For example, the +.BR \(mii +.IR replstr +option can be just as efficiently performed using a shell +.BR for +loop. Since +.IR xargs +calls an +.IR exec +function with each input line, the +.BR \(mii +option does not usually exploit the grouping capabilities of +.IR xargs . +.P +The requirement that +.IR xargs +never produces command lines such that invocation of +.IR utility +is within 2\|048 bytes of hitting the POSIX +.IR exec +{ARG_MAX} +limitations is intended to guarantee that the invoked utility has room +to modify its environment variables and command line arguments and +still be able to invoke another utility. Note that the minimum +{ARG_MAX} +allowed by the System Interfaces volume of POSIX.1\(hy2008 is 4\|096 bytes and the minimum +value allowed by this volume of POSIX.1\(hy2008 is 2\|048 bytes; therefore, +the 2\|048 bytes difference seems reasonable. Note, however, that +.IR xargs +may never be able to invoke a utility if the environment passed in to +.IR xargs +comes close to using +{ARG_MAX} +bytes. +.P +The version of +.IR xargs +required by this volume of POSIX.1\(hy2008 is required to wait for the completion of the invoked +command before invoking another command. This was done because +historical scripts using +.IR xargs +assumed sequential execution. Implementations wanting to provide +parallel operation of the invoked utilities are encouraged to add an +option enabling parallel invocation, but should still wait for +termination of all of the children before +.IR xargs +terminates normally. +.P +The +.BR \(mie +option was omitted from the ISO\ POSIX\(hy2:\|1993 standard in the belief that the +.IR eofstr +option-argument was recognized only when it was on a line by itself and +before quote and escape processing were performed, and that the logical +end-of-file processing was only enabled if a +.BR \(mie +option was specified. In that case, a simple +.IR sed +script could be used to duplicate the +.BR \(mie +functionality. Further investigation revealed that: +.IP " *" 4 +The logical end-of-file string was checked for after quote and escape +processing, making a +.IR sed +script that provided equivalent functionality much more difficult to +write. +.IP " *" 4 +The default was to perform logical end-of-file processing with an + +as the logical end-of-file string. +.P +To correct this misunderstanding, the +.BR \(miE +.IR eofstr +option was adopted from the X/Open Portability Guide. Users should +note that the description of the +.BR \(miE +option matches historical documentation of the +.BR \(mie +option (which was not adopted because it did not support the Utility +Syntax Guidelines), by +saying that if +.IR eofstr +is the null string, logical end-of-file processing is disabled. +Historical implementations of +.IR xargs +actually did not disable logical end-of-file processing; they treated a +null argument found in the input as a logical end-of-file string. (A +null +.IR string +argument could be generated using single or double-quotes (\c +.BR '\^' +or +.BR \(dq\^\(dq ). +Since this behavior was not documented historically, it is considered +to be a bug. +.P +The +.BR \(miI , +.BR \(miL , +and +.BR \(min +options are mutually-exclusive. Some implementations use the last one +specified if more than one is given on a command line; other +implementations treat combinations of the options in different ways. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIdiff\fR\^", +.IR "\fIecho\fR\^", +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/yacc.1p b/man-pages-posix-2013-a/man1p/yacc.1p new file mode 100644 index 0000000..cd62644 --- /dev/null +++ b/man-pages-posix-2013-a/man1p/yacc.1p @@ -0,0 +1,1597 @@ +'\" et +.TH YACC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +yacc +\(em yet another compiler compiler (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +yacc \fB[\fR\(midltv\fB] [\fR\(mib \fIfile_prefix\fB] [\fR\(mip \fIsym_prefix\fB]\fI grammar\fR +.fi +.SH DESCRIPTION +The +.IR yacc +utility shall read a description of a context-free grammar in +.IR grammar +and write C source code, conforming to the ISO\ C standard, to a code file, +and optionally header information into a header file, in the current +directory. The generated source code shall not depend on any undefined, +unspecified, or implementation-defined behavior, except in cases where +it is copied directly from the supplied grammar, or in cases that are +documented by the implementation. The C code shall define a function +and related routines and macros for an automaton that executes a parsing +algorithm meeting the requirements in +.IR "Algorithms". +.P +The form and meaning of the grammar are described in the EXTENDED +DESCRIPTION section. +.P +The C source code and header file shall be produced in a form suitable +as input for the C compiler (see +.IR "\fIc99\fR\^"). +.SH OPTIONS +The +.IR yacc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(mib\ \fIfile_prefix\fR" 10 +Use +.IR file_prefix +instead of +.BR y +as the prefix for all output filenames. The code file +.BR y.tab.c , +the header file +.BR y.tab.h +(created when +.BR \(mid +is specified), and the description file +.BR y.output +(created when +.BR \(miv +is specified), shall be changed to +.IR file_prefix \c +.BR .tab.c , +.IR file_prefix \c +.BR .tab.h , +and +.IR file_prefix \c +.BR .output , +respectively. +.IP "\fB\(mid\fP" 10 +Write the header file; by default only the code file is written. The +.BR #define +statements associate the token codes assigned by +.IR yacc +with the user-declared token names. This allows source files other +than +.BR y.tab.c +to access the token codes. +.IP "\fB\(mil\fP" 10 +Produce a code file that does not contain any +.BR #line +constructs. If this option is not present, it is unspecified whether +the code file or header file contains +.BR #line +directives. This should only be used after the grammar and the +associated actions are fully debugged. +.IP "\fB\(mip\ \fIsym_prefix\fR" 10 +.br +Use +.IR sym_prefix +instead of +.BR yy +as the prefix for all external names produced by +.IR yacc . +The names affected shall include the functions +\fIyyparse\fR(), +\fIyylex\fR(), +and +\fIyyerror\fR(), +and the variables +.IR yylval , +.IR yychar , +and +.IR yydebug . +(In the remainder of this section, the six symbols cited are referenced +using their default names only as a notational convenience.) Local +names may also be affected by the +.BR \(mip +option; however, the +.BR \(mip +option shall not affect +.BR #define +symbols generated by +.IR yacc . +.IP "\fB\(mit\fP" 10 +Modify conditional compilation directives to permit compilation of +debugging code in the code file. Runtime debugging statements shall +always be contained in the code file, but by default conditional +compilation directives prevent their compilation. +.IP "\fB\(miv\fP" 10 +Write a file containing a description of the parser and a report of +conflicts generated by ambiguities in the grammar. +.br +.SH OPERANDS +The following operand is required: +.IP "\fIgrammar\fR" 10 +A pathname of a file containing instructions, hereafter called +.IR grammar , +for which a parser is to be created. The format for the grammar is +described in the EXTENDED DESCRIPTION section. +.SH STDIN +Not used. +.SH "INPUT FILES" +The file +.IR grammar +shall be a text file formatted as specified in the EXTENDED DESCRIPTION +section. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR yacc : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.P +The +.IR LANG +and +.IR LC_* +variables affect the execution of the +.IR yacc +utility as stated. The +\fImain\fR() +function defined in +.IR "Yacc Library" +shall call: +.sp +.RS 4 +.nf +\fB +setlocale(LC_ALL, "") +.fi \fR +.P +.RE +.P +and thus the program generated by +.IR yacc +shall also be affected by the contents of these variables at runtime. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +If shift/reduce or reduce/reduce conflicts are detected in +.IR grammar , +.IR yacc +shall write a report of those conflicts to the standard error in an +unspecified format. +.P +Standard error shall also be used for diagnostic messages. +.SH "OUTPUT FILES" +The code file, the header file, and the description file shall be text +files. All are described in the following sections. +.SS "Code File" +.P +This file shall contain the C source code for the +\fIyyparse\fR() +function. It shall contain code for the various semantic actions with +macro substitution performed on them as described in the EXTENDED +DESCRIPTION section. It also shall contain a copy of the +.BR #define +statements in the header file. If a +.BR %union +declaration is used, the declaration for YYSTYPE shall also be included +in this file. +.SS "Header File" +.P +The header file shall contain +.BR #define +statements that associate the token numbers with the token names. This +allows source files other than the code file to access the token +codes. If a +.BR %union +declaration is used, the declaration for YYSTYPE and an +.IR "extern YYSTYPE yylval" +declaration shall also be included in this file. +.SS "Description File" +.P +The description file shall be a text file containing a description of +the state machine corresponding to the parser, using an unspecified +format. Limits for internal tables (see +.IR "Limits") +shall also be reported, in an implementation-defined manner. (Some +implementations may use dynamic allocation techniques and have no +specific limit values to report.) +.SH "EXTENDED DESCRIPTION" +The +.IR yacc +command accepts a language that is used to define a grammar for a +target language to be parsed by the tables and code generated by +.IR yacc . +The language accepted by +.IR yacc +as a grammar for the target language is described below using the +.IR yacc +input language itself. +.P +The input +.IR grammar +includes rules describing the input structure of the target language +and code to be invoked when these rules are recognized to provide the +associated semantic action. The code to be executed shall appear as bodies +of text that are intended to be C-language code. These bodies of text +shall not contain C-language trigraphs. The C-language inclusions are +presumed to form a correct function when processed by +.IR yacc +into its output files. The code included in this way shall be executed +during the recognition of the target language. +.P +Given a grammar, the +.IR yacc +utility generates the files described in the OUTPUT FILES section. The +code file can be compiled and linked using +.IR c99 . +If the declaration and programs sections of the grammar file did not +include definitions of +\fImain\fR(), +\fIyylex\fR(), +and +\fIyyerror\fR(), +the compiled output requires linking with externally supplied versions +of those functions. Default versions of +\fImain\fR() +and +\fIyyerror\fR() +are supplied in the +.IR yacc +library and can be linked in by using the +.BR "\(mil\ y" +operand to +.IR c99 . +The +.IR yacc +library interfaces need not support interfaces with other than the +default +.BR yy +symbol prefix. The application provides the lexical analyzer function, +\fIyylex\fR(); +the +.IR lex +utility is specifically designed to generate such a routine. +.SS "Input Language" +.P +The application shall ensure that every specification file consists of +three sections in order: +.IR declarations , +.IR "grammar rules" , +and +.IR programs , +separated by double + +characters (\c +.BR \(dq%%\(dq ). +The declarations and programs sections can be empty. If the latter is +empty, the preceding +.BR \(dq%%\(dq +mark separating it from the rules section can be omitted. +.P +The input is free form text following the structure of the grammar +defined below. +.SS "Lexical Structure of the Grammar" +.P +The +, +, +and + +character shall be ignored, except that the application shall ensure that +they do not appear in names or multi-character reserved symbols. Comments +shall be enclosed in +.BR \(dq/*\ ...\ */\(dq , +and can appear wherever a name is valid. +.P +Names are of arbitrary length, made up of letters, periods (\c +.BR '.' ), +underscores (\c +.BR '_' ), +and non-initial digits. Uppercase and lowercase letters are distinct. +Conforming applications shall not use names beginning in +.BR yy +or +.BR YY +since the +.IR yacc +parser uses such names. Many of the names appear in the final output +of +.IR yacc , +and thus they should be chosen to conform with any additional rules +created by the C compiler to be used. In particular they appear in +.BR #define +statements. +.P +A literal shall consist of a single character enclosed in single-quote +characters. All of the escape sequences supported for character constants +by the ISO\ C standard shall be supported by +.IR yacc . +.P +The relationship with the lexical analyzer is discussed in detail below. +.P +The application shall ensure that the NUL character is not used in +grammar rules or literals. +.SS "Declarations Section" +.P +The declarations section is used to define the symbols used to define +the target language and their relationship with each other. In +particular, much of the additional information required to resolve +ambiguities in the context-free grammar for the target language is +provided here. +.P +Usually +.IR yacc +assigns the relationship between the symbolic names it generates and +their underlying numeric value. The declarations section makes it +possible to control the assignment of these values. +.P +It is also possible to keep semantic information associated with the +tokens currently on the parse stack in a user-defined C-language +.BR union , +if the members of the union are associated with the various names in +the grammar. The declarations section provides for this as well. +.P +The first group of declarators below all take a list of names as +arguments. That list can optionally be preceded by the name of a C +union member (called a +.IR tag +below) appearing within +.BR '<' +and +.BR '>' . +(As an exception to the typographical conventions of the rest of this volume of POSIX.1\(hy2008, +in this case <\fItag\fP> does not represent a metavariable, but the +literal angle bracket characters surrounding a symbol.) The use of +.IR tag +specifies that the tokens named on this line shall be of the same C +type as the union member referenced by +.IR tag . +This is discussed in more detail below. +.P +For lists used to define tokens, the first appearance of a given token +can be followed by a positive integer (as a string of decimal digits). +If this is done, the underlying value assigned to it for lexical +purposes shall be taken to be that number. +.P +The following declares +.IR name +to be a token: +.sp +.RS 4 +.nf +\fB +%token \fB[\fR<\fItag\fR>\fB] \fIname \fB[\fInumber\fB] [\fIname \fB[\fInumber\fB]]\fR... +.fi \fR +.P +.RE +.P +If +.IR tag +is present, the C type for all tokens on this line shall be declared to +be the type referenced by +.IR tag . +If a positive integer, +.IR number , +follows a +.IR name , +that value shall be assigned to the token. +.P +The following declares +.IR name +to be a token, and assigns precedence to it: +.sp +.RS 4 +.nf +\fB +%left \fB[\fR<\fItag\fR>\fB] \fIname \fB[\fInumber\fB] [\fIname \fB[\fInumber\fB]]\fR... +%right \fB[\fR<\fItag\fR>\fB] \fIname \fB[\fInumber\fB] [\fIname \fB[\fInumber\fB]]\fR... +.fi \fR +.P +.RE +.P +One or more lines, each beginning with one of these symbols, can appear +in this section. All tokens on the same line have the same precedence +level and associativity; the lines are in order of increasing +precedence or binding strength. +.BR %left +denotes that the operators on that line are left associative, and +.BR %right +similarly denotes right associative operators. If +.IR tag +is present, it shall declare a C type for +.IR name s +as described for +.BR %token . +.P +The following declares +.IR name +to be a token, and indicates that this cannot be used associatively: +.sp +.RS 4 +.nf +\fB +%nonassoc \fB[\fR<\fItag\fR>\fB] \fIname \fB[\fInumber\fB] [\fIname \fB[\fInumber\fB]]\fR... +.fi \fR +.P +.RE +.P +If the parser encounters associative use of this token it reports an +error. If +.IR tag +is present, it shall declare a C type for +.IR name s +as described for +.BR %token . +.P +The following declares that union member +.IR name s +are non-terminals, and thus it is required to have a +.IR tag +field at its beginning: +.sp +.RS 4 +.nf +\fB +%type <\fItag\fR> \fIname\fR... +.fi \fR +.P +.RE +.P +Because it deals with non-terminals only, assigning a token number or +using a literal is also prohibited. If this construct is present, +.IR yacc +shall perform type checking; if this construct is not present, the +parse stack shall hold only the +.BR int +type. +.P +Every name used in +.IR grammar +not defined by a +.BR %token , +.BR %left , +.BR %right , +or +.BR %nonassoc +declaration is assumed to represent a non-terminal symbol. The +.IR yacc +utility shall report an error for any non-terminal symbol that does not +appear on the left side of at least one grammar rule. +.P +Once the type, precedence, or token number of a name is specified, it +shall not be changed. If the first declaration of a token does not +assign a token number, +.IR yacc +shall assign a token number. Once this assignment is made, the token +number shall not be changed by explicit assignment. +.P +The following declarators do not follow the previous pattern. +.P +The following declares the non-terminal +.IR name +to be the +.IR "start symbol" , +which represents the largest, most general structure described by the +grammar rules: +.sp +.RS 4 +.nf +\fB +%start \fIname\fR +.fi \fR +.P +.RE +.P +By default, it is the left-hand side of the first grammar rule; this +default can be overridden with this declaration. +.P +The following declares the +.IR yacc +value stack to be a union of the various types of values desired. +.sp +.RS 4 +.nf +\fB +%union { \fIbody of union\fR (\fIin C\fR) } +.fi \fR +.P +.RE +.P +The body of the union shall not contain unbalanced curly brace +preprocessing tokens. +.P +By default, the values returned by actions (see below) and the lexical +analyzer shall be of type +.BR int . +The +.IR yacc +utility keeps track of types, and it shall insert corresponding union +member names in order to perform strict type checking of the resulting +parser. +.P +Alternatively, given that at least one <\fItag\fP> construct is used, +the union can be declared in a header file (which shall be included in +the declarations section by using a +.BR #include +construct within +.BR %{ +and +.BR %} ), +and a +.BR typedef +used to define the symbol YYSTYPE to represent this union. The effect +of +.BR %union +is to provide the declaration of YYSTYPE directly from the +.IR yacc +input. +.P +C-language declarations and definitions can appear in the declarations +section, enclosed by the following marks: +.sp +.RS 4 +.nf +\fB +%{ ... %} +.fi \fR +.P +.RE +.P +These statements shall be copied into the code file, and have global +scope within it so that they can be used in the rules and program +sections. The statements shall not contain +.BR \(dq%}\(dq +outside a comment, string literal, or multi-character constant. +.P +The application shall ensure that the declarations section is +terminated by the token +.BR %% . +.SS "Grammar Rules in yacc" +.P +The rules section defines the context-free grammar to be accepted by +the function +.IR yacc +generates, and associates with those rules C-language actions and +additional precedence information. The grammar is described below, and +a formal definition follows. +.P +The rules section is comprised of one or more grammar rules. A grammar +rule has the form: +.sp +.RS 4 +.nf +\fB +A : BODY ; +.fi \fR +.P +.RE +.P +The symbol +.BR A +represents a non-terminal name, and +.BR BODY +represents a sequence of zero or more +.IR name s, +.IR literal s, +and +.IR "semantic action" s +that can then be followed by optional +.IR "precedence rule" s. +Only the names and literals participate in the formation of the +grammar; the semantic actions and precedence rules are used in other +ways. The + +and the + +are +.IR yacc +punctuation. If there are several successive grammar rules with the +same left-hand side, the + +(\c +.BR '|' ) +can be used to avoid rewriting the left-hand side; in this case the + +appears only after the last rule. The BODY part can be empty +(or empty of names and literals) to indicate that the non-terminal +symbol matches the empty string. +.P +The +.IR yacc +utility assigns a unique number to each rule. Rules using the vertical +bar notation are distinct rules. The number assigned to the rule +appears in the description file. +.P +The elements comprising a BODY are: +.IP "\fIname\fR,\ \fIliteral\fR" 10 +These form the rules of the grammar: +.IR name +is either a +.IR token +or a +.IR non-terminal ; +.IR literal +stands for itself (less the lexically required quotation marks). +.IP "\fIsemantic action\fR" 10 +.br +With each grammar rule, the user can associate actions to be performed +each time the rule is recognized in the input process. (Note that the +word ``action'' can also refer to the actions of the parser\(emshift, +reduce, and so on.) +.RS 10 +.P +These actions can return values and can obtain the values returned by +previous actions. These values are kept in objects of type YYSTYPE +(see +.BR %union ). +The result value of the action shall be kept on the parse stack with +the left-hand side of the rule, to be accessed by other reductions as +part of their right-hand side. By using the <\fItag\fP> information +provided in the declarations section, the code generated by +.IR yacc +can be strictly type checked and contain arbitrary information. In +addition, the lexical analyzer can provide the same kinds of values for +tokens, if desired. +.P +An action is an arbitrary C statement and as such can do input or +output, call subprograms, and alter external variables. An action is +one or more C statements enclosed in curly braces +.BR '{' +and +.BR '}' . +The statements shall not contain unbalanced curly brace preprocessing +tokens. +.P +Certain pseudo-variables can be used in the action. These are macros +for access to data structures known internally to +.IR yacc . +.IP $$ 10 +The value of the action can be set by assigning it to $$. If type +checking is enabled and the type of the value to be assigned cannot be +determined, a diagnostic message may be generated. +.IP "$\fInumber\fR" 10 +This refers to the value returned by the component specified by the +token +.IR number +in the right side of a rule, reading from left to right; +.IR number +can be zero or negative. If +.IR number +is zero or negative, it refers to the data associated with the name on +the parser's stack preceding the leftmost symbol of the current rule. +(That is, +.BR \(dq$0\(dq +refers to the name immediately preceding the leftmost name in the +current rule to be found on the parser's stack and +.BR \(dq$\(mi1\(dq +refers to the symbol to +.IR its +left.) If +.IR number +refers to an element past the current point in the rule, or beyond the +bottom of the stack, the result is undefined. If type checking is +enabled and the type of the value to be assigned cannot be determined, +a diagnostic message may be generated. +.IP "$<\fItag\fR>\fInumber\fR" 10 +.br +These correspond exactly to the corresponding symbols without the +.IR tag +inclusion, but allow for strict type checking (and preclude unwanted +type conversions). The effect is that the macro is expanded to use +.IR tag +to select an element from the YYSTYPE union (using +.IR dataname.tag ). +This is particularly useful if +.IR number +is not positive. +.IP "$<\fItag\fR>$" 10 +This imposes on the reference the type of the union member referenced +by +.IR tag . +This construction is applicable when a reference to a left context +value occurs in the grammar, and provides +.IR yacc +with a means for selecting a type. +.P +Actions can occur anywhere in a rule (not just at the end); an +action can access values returned by actions to its left, and in turn +the value it returns can be accessed by actions to its right. An +action appearing in the middle of a rule shall be equivalent to +replacing the action with a new non-terminal symbol and adding an empty +rule with that non-terminal symbol on the left-hand side. The semantic +action associated with the new rule shall be equivalent to the original +action. The use of actions within rules might introduce conflicts that +would not otherwise exist. +.P +By default, the value of a rule shall be the value of the first element +in it. If the first element does not have a type (particularly in the +case of a literal) and type checking is turned on by +.BR %type , +an error message shall result. +.RE +.IP "\fIprecedence\fR" 10 +The keyword +.BR %prec +can be used to change the precedence level associated with a particular +grammar rule. Examples of this are in cases where a unary and binary +operator have the same symbolic representation, but need to be given +different precedences, or where the handling of an ambiguous if-else +construction is necessary. The reserved symbol +.BR %prec +can appear immediately after the body of the grammar rule and can be +followed by a token name or a literal. It shall cause the precedence +of the grammar rule to become that of the following token name or +literal. The action for the rule as a whole can follow +.BR %prec . +.P +If a program section follows, the application shall ensure that the +grammar rules are terminated by +.BR %% . +.SS "Programs Section" +.P +The +.IR programs +section can include the definition of the lexical analyzer +\fIyylex\fR(), +and any other functions; for example, those used in the actions +specified in the grammar rules. It is unspecified whether the programs +section precedes or follows the semantic actions in the output file; +therefore, if the application contains any macro definitions and +declarations intended to apply to the code in the semantic actions, it +shall place them within +.BR \(dq%{\ ...\ %}\(dq +in the declarations section. +.SS "Input Grammar" +.P +The following input to +.IR yacc +yields a parser for the input to +.IR yacc . +This formal syntax takes precedence over the preceding text syntax +description. +.P +The lexical structure is defined less precisely; +.IR "Lexical Structure of the Grammar" +defines most terms. The correspondence between the previous terms and +the tokens below is as follows. +.IP "\fBIDENTIFIER\fR" 12 +This corresponds to the concept of +.IR name , +given previously. It also includes literals as defined previously. +.IP "\fBC_IDENTIFIER\fR" 12 +This is a name, and additionally it is known to be followed by a +. +A literal cannot yield this token. +.IP "\fBNUMBER\fR" 12 +A string of digits (a non-negative decimal integer). +.IP "\fBTYPE\fR,\ \fBLEFT\fR,\ \fBMARK\fR,\ \fBLCURL\fR,\ \fBRCURL\fR" 12 +.br +These correspond directly to +.BR %type , +.BR %left , +.BR %% , +.BR %{ , +and +.BR %} . +.IP "\fB{\ .\|.\|.\ }\fR" 12 +This indicates C-language source code, with the possible inclusion of +.BR '$' +macros as discussed previously. +.sp +.RS 4 +.nf +\fB +/* Grammar for the input to yacc. */ +/* Basic entries. */ +/* The following are recognized by the lexical analyzer. */ +.P +%token IDENTIFIER /* Includes identifiers and literals */ +%token C_IDENTIFIER /* identifier (but not literal) + followed by a :. */ +%token NUMBER /* [0-9][0-9]* */ +.P +/* Reserved words : %type=>TYPE %left=>LEFT, and so on */ +.P +%token LEFT RIGHT NONASSOC TOKEN PREC TYPE START UNION +.P +%token MARK /* The %% mark. */ +%token LCURL /* The %{ mark. */ +%token RCURL /* The %} mark. */ +.P +/* 8-bit character literals stand for themselves; */ +/* tokens have to be defined for multi-byte characters. */ +.P +%start spec +.P +%% +.P +spec : defs MARK rules tail + ; +tail : MARK + { + /* In this action, set up the rest of the file. */ + } + | /* Empty; the second MARK is optional. */ + ; +defs : /* Empty. */ + | defs def + ; +def : START IDENTIFIER + | UNION + { + /* Copy union definition to output. */ + } + | LCURL + { + /* Copy C code to output file. */ + } + RCURL + | rword tag nlist + ; +rword : TOKEN + | LEFT + | RIGHT + | NONASSOC + | TYPE + ; +tag : /* Empty: union tag ID optional. */ + | '<' IDENTIFIER '>' + ; +nlist : nmno + | nlist nmno + ; +nmno : IDENTIFIER /* Note: literal invalid with % type. */ + | IDENTIFIER NUMBER /* Note: invalid with % type. */ + ; +.P +/* Rule section */ +.P +rules : C_IDENTIFIER rbody prec + | rules rule + ; +rule : C_IDENTIFIER rbody prec + | '|' rbody prec + ; +rbody : /* empty */ + | rbody IDENTIFIER + | rbody act + ; +act : '{' + { + /* Copy action, translate $$, and so on. */ + } + '}' + ; +prec : /* Empty */ + | PREC IDENTIFIER + | PREC IDENTIFIER act + | prec ';' + ; +.fi \fR +.P +.RE +.sp +.SS "Conflicts" +.P +The parser produced for an input grammar may contain states in which +conflicts occur. The conflicts occur because the grammar is not +LALR(1). An ambiguous grammar always contains at least one LALR(1) +conflict. The +.IR yacc +utility shall resolve all conflicts, using either default rules or +user-specified precedence rules. +.P +Conflicts are either shift/reduce conflicts or reduce/reduce +conflicts. A shift/reduce conflict is where, for a given state and +lookahead symbol, both a shift action and a reduce action are +possible. A reduce/reduce conflict is where, for a given state and +lookahead symbol, reductions by two different rules are possible. +.P +The rules below describe how to specify what actions to take when a +conflict occurs. Not all shift/reduce conflicts can be successfully +resolved this way because the conflict may be due to something other +than ambiguity, so incautious use of these facilities can cause the +language accepted by the parser to be much different from that which +was intended. The description file shall contain sufficient +information to understand the cause of the conflict. Where ambiguity +is the reason either the default or explicit rules should be adequate +to produce a working parser. +.P +The declared precedences and associativities (see +.IR "Declarations Section") +are used to resolve parsing conflicts as follows: +.IP " 1." 4 +A precedence and associativity is associated with each grammar rule; it +is the precedence and associativity of the last token or literal in the +body of the rule. If the +.BR %prec +keyword is used, it overrides this default. Some grammar rules might +not have both precedence and associativity. +.IP " 2." 4 +If there is a shift/reduce conflict, and both the grammar rule and the +input symbol have precedence and associativity associated with them, +then the conflict is resolved in favor of the action (shift or reduce) +associated with the higher precedence. If the precedences are the +same, then the associativity is used; left associative implies reduce, +right associative implies shift, and non-associative implies an error +in the string being parsed. +.IP " 3." 4 +When there is a shift/reduce conflict that cannot be resolved by rule +2, the shift is done. Conflicts resolved this way are counted in the +diagnostic output described in +.IR "Error Handling". +.IP " 4." 4 +When there is a reduce/reduce conflict, a reduction is done by the +grammar rule that occurs earlier in the input sequence. Conflicts +resolved this way are counted in the diagnostic output described in +.IR "Error Handling". +.P +Conflicts resolved by precedence or associativity shall not be counted +in the shift/reduce and reduce/reduce conflicts reported by +.IR yacc +on either standard error or in the description file. +.SS "Error Handling" +.P +The token +.BR error +shall be reserved for error handling. The name +.BR error +can be used in grammar rules. It indicates places where the parser can +recover from a syntax error. The default value of +.BR error +shall be 256. Its value can be changed using a +.BR %token +declaration. The lexical analyzer should not return the value of +.BR error . +.P +The parser shall detect a syntax error when it is in a state where the +action associated with the lookahead symbol is +.BR error . +A semantic action can cause the parser to initiate error handling by +executing the macro YYERROR. When YYERROR is executed, the semantic +action passes control back to the parser. YYERROR cannot be used +outside of semantic actions. +.P +When the parser detects a syntax error, it normally calls +\fIyyerror\fR() +with the character string +.BR \(dqsyntax\ error\(dq +as its argument. The call shall not be made if the parser is still +recovering from a previous error when the error is detected. The +parser is considered to be recovering from a previous error until the +parser has shifted over at least three normal input symbols since the +last error was detected or a semantic action has executed the macro +.IR yyerrok . +The parser shall not call +\fIyyerror\fR() +when YYERROR is executed. +.P +The macro function YYRECOVERING shall return 1 if a syntax error +has been detected and the parser has not yet fully recovered from it. +Otherwise, zero shall be returned. +.P +When a syntax error is detected by the parser, the parser shall check +if a previous syntax error has been detected. If a previous error was +detected, and if no normal input symbols have been shifted since the +preceding error was detected, the parser checks if the lookahead symbol +is an endmarker (see +.IR "Interface to the Lexical Analyzer"). +If it is, the parser shall return with a non-zero value. Otherwise, +the lookahead symbol shall be discarded and normal parsing shall +resume. +.P +When YYERROR is executed or when the parser detects a syntax error and +no previous error has been detected, or at least one normal input +symbol has been shifted since the previous error was detected, the +parser shall pop back one state at a time until the parse stack is +empty or the current state allows a shift over +.BR error . +If the parser empties the parse stack, it shall return with a non-zero +value. Otherwise, it shall shift over +.BR error +and then resume normal parsing. If the parser reads a lookahead symbol +before the error was detected, that symbol shall still be the lookahead +symbol when parsing is resumed. +.P +The macro +.IR yyerrok +in a semantic action shall cause the parser to act as if it has fully +recovered from any previous errors. The macro +.IR yyclearin +shall cause the parser to discard the current lookahead token. If the +current lookahead token has not yet been read, +.IR yyclearin +shall have no effect. +.P +The macro YYACCEPT shall cause the parser to return with the value +zero. The macro YYABORT shall cause the parser to return with a +non-zero value. +.SS "Interface to the Lexical Analyzer" +.P +The +\fIyylex\fR() +function is an integer-valued function that returns a +.IR "token number" +representing the kind of token read. If there is a value associated +with the token returned by +\fIyylex\fR() +(see the discussion of +.IR tag +above), it shall be assigned to the external variable +.IR yylval . +.P +If the parser and +\fIyylex\fR() +do not agree on these token numbers, reliable communication between +them cannot occur. For (single-byte character) literals, the token is +simply the numeric value of the character in the current character set. +The numbers for other tokens can either be chosen by +.IR yacc , +or chosen by the user. In either case, the +.BR #define +construct of C is used to allow +\fIyylex\fR() +to return these numbers symbolically. The +.BR #define +statements are put into the code file, and the header file if that file +is requested. The set of characters permitted by +.IR yacc +in an identifier is larger than that permitted by C. Token names found +to contain such characters shall not be included in the +.BR #define +declarations. +.P +If the token numbers are chosen by +.IR yacc , +the tokens other than literals shall be assigned numbers greater than +256, although no order is implied. A token can be explicitly assigned a +number by following its first appearance in the declarations section +with a number. Names and literals not defined this way retain their +default definition. All token numbers assigned by +.IR yacc +shall be unique and distinct from the token numbers used for literals +and user-assigned tokens. If duplicate token numbers cause conflicts in +parser generation, +.IR yacc +shall report an error; otherwise, it is unspecified whether the token +assignment is accepted or an error is reported. +.P +The end of the input is marked by a special token called the +.IR endmarker , +which has a token number that is zero or negative. (These values are +invalid for any other token.) All lexical analyzers shall return zero +or negative as a token number upon reaching the end of their input. If +the tokens up to, but excluding, the endmarker form a structure that +matches the start symbol, the parser shall accept the input. If the +endmarker is seen in any other context, it shall be considered an +error. +.SS "Completing the Program" +.P +In addition to +\fIyyparse\fR() +and +\fIyylex\fR(), +the functions +\fIyyerror\fR() +and +\fImain\fR() +are required to make a complete program. The application can supply +\fImain\fR() +and +\fIyyerror\fR(), +or those routines can be obtained from the +.IR yacc +library. +.SS "Yacc Library" +.P +The following functions shall appear only in the +.IR yacc +library accessible through the +.BR "\(mil\ y" +operand to +.IR c99 ; +they can therefore be redefined by a conforming application: +.IP "\fBint\ \fImain\fR(\fBvoid\fR)" 6 +.br +This function shall call +\fIyyparse\fR() +and exit with an unspecified value. Other actions within this function +are unspecified. +.IP "\fBint\ \fIyyerror\fR(\fBconst\ char\fR\ *\fIs\fR)" 6 +.br +This function shall write the NUL-terminated argument to standard +error, followed by a +. +.P +The order of the +.BR "\(mil\ y" +and +.BR "\(mil\ l" +operands given to +.IR c99 +is significant; the application shall either provide its own +\fImain\fR() +function or ensure that +.BR "\(mil\ y" +precedes +.BR "\(mil\ l" . +.SS "Debugging the Parser" +.P +The parser generated by +.IR yacc +shall have diagnostic facilities in it that can be optionally enabled +at either compile time or at runtime (if enabled at compile time). +The compilation of the runtime debugging code is under the control of +YYDEBUG, a preprocessor symbol. If YYDEBUG has a non-zero value, the +debugging code shall be included. If its value is zero, the code shall +not be included. +.P +In parsers where the debugging code has been included, the external +.BR int +.IR yydebug +can be used to turn debugging on (with a non-zero value) and off (zero +value) at runtime. The initial value of +.IR yydebug +shall be zero. +.P +When +.BR \(mit +is specified, the code file shall be built such that, if YYDEBUG is not +already defined at compilation time (using the +.IR c99 +.BR \(miD +YYDEBUG option, for example), YYDEBUG shall be set explicitly to 1. +When +.BR \(mit +is not specified, the code file shall be built such that, if YYDEBUG is +not already defined, it shall be set explicitly to zero. +.P +The format of the debugging output is unspecified but includes at least +enough information to determine the shift and reduce actions, and the +input symbols. It also provides information about error recovery. +.SS "Algorithms" +.P +The parser constructed by +.IR yacc +implements an LALR(1) parsing algorithm as documented in the +literature. It is unspecified whether the parser is table-driven or +direct-coded. +.P +A parser generated by +.IR yacc +shall never request an input symbol from +\fIyylex\fR() +while in a state where the only actions other than the error action are +reductions by a single rule. +.P +The literature of parsing theory defines these concepts. +.SS "Limits" +.P +The +.IR yacc +utility may have several internal tables. The minimum maximums for +these tables are shown in the following table. The exact meaning of +these values is implementation-defined. The implementation shall +define the relationship between these values and between them and any +error messages that the implementation may generate should it run out +of space for any internal structure. An implementation may combine +groups of these resources into a single pool as long as the total +available to the user does not fall below the sum of the sizes +specified by this section. +.br +.sp +.ce 1 +\fBTable: Internal Limits in \fIyacc\fP\fR +.ad l +.TS +center box tab(@); +cB | cB | cB +cB | cB | cB +l | n | lw(3i). +@Minimum +Limit@Maximum@Description +_ +{NTERMS}@126@Number of tokens. +{NNONTERM}@200@Number of non-terminals. +{NPROD}@300@Number of rules. +{NSTATES}@600@Number of states. +{MEMSIZE}@5\|200@T{ +Length of rules. The total length, in names (tokens and +non-terminals), of all the rules of the grammar. The left-hand side is +counted for each rule, even if it is not explicitly repeated, as +specified in +.IR "Grammar Rules in yacc". +T} +{ACTSIZE}@4\|000@T{ +Number of actions. ``Actions'' here (and in the description file) +refer to parser actions (shift, reduce, and so on) not to semantic +actions defined in +.IR "Grammar Rules in yacc". +T} +.TE +.ad b +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If any errors are encountered, the run is aborted and +.IR yacc +exits with a non-zero status. Partial code files and header files +may be produced. The summary information in the description file +shall always be produced if the +.BR \(miv +flag is present. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Historical implementations experience name conflicts on the names +.BR yacc.tmp , +.BR yacc.acts , +.BR yacc.debug , +.BR y.tab.c , +.BR y.tab.h , +and +.BR y.output +if more than one copy of +.IR yacc +is running in a single directory at one time. The +.BR \(mib +option was added to overcome this problem. The related problem of +allowing multiple +.IR yacc +parsers to be placed in the same file was addressed by adding a +.BR \(mip +option to override the previously hard-coded +.BR yy +variable prefix. +.P +The description of the +.BR \(mip +option specifies the minimal set of function and variable names that +cause conflict when multiple parsers are linked together. YYSTYPE does +not need to be changed. Instead, the programmer can use +.BR \(mib +to give the header files for different parsers different names, and +then the file with the +\fIyylex\fR() +for a given parser can include the header for that parser. Names such +as +.IR yyclearerr +do not need to be changed because they are used only in the actions; +they do not have linkage. It is possible that an implementation has +other names, either internal ones for implementing things such as +.IR yyclearerr , +or providing non-standard features that it wants to change with +.BR \(mip . +.P +Unary operators that are the same token as a binary operator in general +need their precedence adjusted. This is handled by the +.BR %prec +advisory symbol associated with the particular grammar rule defining +that unary operator. (See +.IR "Grammar Rules in yacc".) +Applications are not required to use this operator for unary operators, +but the grammars that do not require it are rare. +.SH EXAMPLES +Access to the +.IR yacc +library is obtained with library search operands to +.IR c99 . +To use the +.IR yacc +library +\fImain\fR(): +.sp +.RS 4 +.nf +\fB +c99 y.tab.c \(mil y +.fi \fR +.P +.RE +.P +Both the +.IR lex +library and the +.IR yacc +library contain +\fImain\fR(). +To access the +.IR yacc +\fImain\fR(): +.sp +.RS 4 +.nf +\fB +c99 y.tab.c lex.yy.c \(mil y \(mil l +.fi \fR +.P +.RE +.P +This ensures that the +.IR yacc +library is searched first, so that its +\fImain\fR() +is used. +.P +The historical +.IR yacc +libraries have contained two simple functions that are normally coded +by the application programmer. These functions are similar to the +following code: +.sp +.RS 4 +.nf +\fB +#include +int main(void) +{ + extern int yyparse(); +.P + setlocale(LC_ALL, ""); +.P + /* If the following parser is one created by lex, the + application must be careful to ensure that LC_CTYPE + and LC_COLLATE are set to the POSIX locale. */ + (void) yyparse(); + return (0); +} +.P +#include +.P +int yyerror(const char *msg) +{ + (void) fprintf(stderr, "%s\en", msg); + return (0); +} +.fi \fR +.P +.RE +.SH RATIONALE +The references in +.BR "Referenced Documents" +may be helpful in constructing the parser generator. The referenced DeRemer and Pennello article (along +with the works it references) describes a technique to generate parsers +that conform to this volume of POSIX.1\(hy2008. Work in this area continues to be done, so +implementors should consult current literature before doing any new +implementations. The original Knuth article is the theoretical basis for this +kind of parser, but the tables it generates are impractically large for +reasonable grammars and should not be used. The ``equivalent to'' +wording is intentional to assure that the best tables that are LALR(1) +can be generated. +.P +There has been confusion between the class of grammars, the algorithms +needed to generate parsers, and the algorithms needed to parse the +languages. They are all reasonably orthogonal. In particular, a parser +generator that accepts the full range of LR(1) grammars need not +generate a table any more complex than one that accepts SLR(1) (a +relatively weak class of LR grammars) for a grammar that happens to be +SLR(1). Such an implementation need not recognize the case, either; +table compression can yield the SLR(1) table (or one even smaller than +that) without recognizing that the grammar is SLR(1). +The speed of an LR(1) parser for any class is dependent more upon the +table representation and compression (or the code generation if a +direct parser is generated) than upon the class of grammar that the +table generator handles. +.P +The speed of the parser generator is somewhat dependent upon the class +of grammar it handles. However, the original Knuth article algorithms for +constructing LR parsers were judged by its author to be impractically +slow at that time. Although full LR is more complex than LALR(1), as +computer speeds and algorithms improve, the difference (in terms of +acceptable wall-clock execution time) is becoming less significant. +.P +Potential authors are cautioned that the referenced DeRemer and Pennello article previously cited +identifies a bug (an over-simplification of the computation of LALR(1) +lookahead sets) in some of the LALR(1) algorithm statements that +preceded it to publication. They should take the time to seek out that +paper, as well as current relevant work, particularly Aho's. +.P +The +.BR \(mib +option was added to provide a portable method for permitting +.IR yacc +to work on multiple separate parsers in the same directory. If a +directory contains more than one +.IR yacc +grammar, and both grammars are constructed at the same time (by, for +example, a parallel +.IR make +program), conflict results. While the solution is not historical +practice, it corrects a known deficiency in historical implementations. +Corresponding changes were made to all sections that referenced the +filenames +.BR y.tab.c +(now ``the code file''), +.BR y.tab.h +(now ``the header file''), and +.BR y.output +(now ``the description file''). +.P +The grammar for +.IR yacc +input is based on System V documentation. The textual description shows +there that the +.BR ';' +is required at the end of the rule. The grammar and the implementation +do not require this. (The use of +.BR C_IDENTIFIER +causes a reduce to occur in the right place.) +.P +Also, in that implementation, the constructs such as +.BR %token +can be terminated by a +, +but this is not permitted by the grammar. The keywords such as +.BR %token +can also appear in uppercase, which is again not discussed. In most +places where +.BR '%' +is used, + +can be substituted, and there are alternate spellings for some of the +symbols (for example, +.BR %LEFT +can be +.BR \(dq%<\(dq +or even +.BR \(dq\e<\(dq ). +.P +Historically, <\fItag\fP> can contain any characters except +.BR '>' , +including white space, in the implementation. However, since the +.IR tag +must reference an ISO\ C standard union member, in practice conforming +implementations need to support only the set of characters for ISO\ C standard +identifiers in this context. +.P +Some historical implementations are known to accept actions that are +terminated by a period. Historical implementations often allow +.BR '$' +in names. A conforming implementation does not need to support either +of these behaviors. +.P +Deciding when to use +.BR %prec +illustrates the difficulty in specifying the behavior of +.IR yacc . +There may be situations in which the +.IR grammar +is not, strictly speaking, in error, and yet +.IR yacc +cannot interpret it unambiguously. The resolution of ambiguities in the +grammar can in many instances be resolved by providing additional +information, such as using +.BR %type +or +.BR %union +declarations. It is often easier and it usually yields a smaller parser +to take this alternative when it is appropriate. +.P +The size and execution time of a program produced without the runtime +debugging code is usually smaller and slightly faster in historical +implementations. +.P +Statistics messages from several historical implementations include the +following types of information: +.sp +.RS 4 +.nf +\fB +\fIn\fR/512 terminals, \fIn\fR/300 non-terminals +\fIn\fR/600 grammar rules, \fIn\fR/1\|500 states +\fIn\fR shift/reduce, \fIn\fR reduce/reduce conflicts reported +\fIn\fR/350 working sets used +Memory: states, etc. \fIn\fR/15\|000, parser \fIn\fR/15\|000 +\fIn\fR/600 distinct lookahead sets +\fIn\fR extra closures +\fIn\fR shift entries, \fIn\fR exceptions +\fIn\fR goto entries +\fIn\fR entries saved by goto default +Optimizer space used: input \fIn\fR/15\|000, output \fIn\fR/15\|000 +\fIn\fR table entries, \fIn\fR zero +Maximum spread: \fIn\fR, Maximum offset: \fIn\fR +.fi \fR +.P +.RE +.P +The report of internal tables in the description file is left +implementation-defined because all aspects of these limits are also +implementation-defined. Some implementations may use dynamic +allocation techniques and have no specific limit values to report. +.P +The format of the +.BR y.output +file is not given because specification of the format was not seen to +enhance applications portability. The listing is primarily intended to +help human users understand and debug the parser; use of +.BR y.output +by a conforming application script would be unusual. Furthermore, +implementations have not produced consistent output and no popular +format was apparent. The format selected by the implementation should +be human-readable, in addition to the requirement that it be a text +file. +.P +Standard error reports are not specifically described because they are +seldom of use to conforming applications and there was no reason to +restrict implementations. +.P +Some implementations recognize +.BR \(dq={\(dq +as equivalent to +.BR '{' +because it appears in historical documentation. This construction was +recognized and documented as obsolete as long ago as 1978, in the +referenced \fIYacc: Yet Another Compiler-Compiler\fP. This volume of POSIX.1\(hy2008 chose to leave it as obsolete and omit it. +.P +Multi-byte characters should be recognized by the lexical analyzer and +returned as tokens. They should not be returned as multi-byte +character literals. The token +.BR error +that is used for error recovery is normally assigned the value 256 in +the historical implementation. Thus, the token value 256, which is used +in many multi-byte character sets, is not available for use as the +value of a user-defined token. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIlex\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man1p/zcat.1p b/man-pages-posix-2013-a/man1p/zcat.1p new file mode 100644 index 0000000..e5c78cc --- /dev/null +++ b/man-pages-posix-2013-a/man1p/zcat.1p @@ -0,0 +1,127 @@ +'\" et +.TH ZCAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +zcat +\(em expand and concatenate data +.SH SYNOPSIS +.LP +.nf +zcat \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR zcat +utility shall write to standard output the uncompressed form of files +that have been compressed using the +.IR compress +utility. It is the equivalent of +.IR uncompress +.BR \(mic . +Input files are not affected. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a file previously processed by the +.IR compress +utility. If +.IR file +already has the +.BR .Z +suffix specified, it is used as submitted. Otherwise, the +.BR .Z +suffix is appended to the filename prior to processing. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +Input files shall be compressed files that are in the format produced by +the +.IR compress +utility. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR zcat : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The compressed files given as input shall be written on standard output +in their uncompressed form. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcompress\fR\^", +.IR "\fIuncompress\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/FD_CLR.3p b/man-pages-posix-2013-a/man3p/FD_CLR.3p new file mode 100644 index 0000000..499063a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/FD_CLR.3p @@ -0,0 +1,41 @@ +'\" et +.TH FD_CLR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +FD_CLR +\(em macros for synchronous I/O multiplexing +.SH SYNOPSIS +.LP +.nf +#include +.P +void FD_CLR(int \fIfd\fP, fd_set *\fIfdset\fP); +int FD_ISSET(int \fIfd\fP, fd_set *\fIfdset\fP); +void FD_SET(int \fIfd\fP, fd_set *\fIfdset\fP); +void FD_ZERO(fd_set *\fIfdset\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpselect\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/_Exit.3p b/man-pages-posix-2013-a/man3p/_Exit.3p new file mode 100644 index 0000000..67bf8b8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/_Exit.3p @@ -0,0 +1,451 @@ +'\" et +.TH _EXIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +_Exit, +_exit +\(em terminate a process +.SH SYNOPSIS +.LP +.nf +#include +.P +void _Exit(int \fIstatus\fP); +.P +#include +.P +void _exit(int \fIstatus\fP); +.fi +.SH DESCRIPTION +For +\fI_Exit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The value of +.IR status +may be 0, EXIT_SUCCESS, EXIT_FAILURE, +or any other value, though only the least significant 8 bits (that is, +.IR status +& 0377) shall be available to a waiting parent process. +.P +The +\fI_Exit\fR() +and +\fI_exit\fR() +functions shall be functionally equivalent. +.P +The +\fI_Exit\fR() +and +\fI_exit\fR() +functions shall not call functions registered with +\fIatexit\fR() +nor any registered signal handlers. +Open streams shall not be flushed. +Whether open streams are closed (without flushing) is +implementation-defined. Finally, the calling process shall be +terminated with the consequences described below. +.SS "Consequences of Process Termination" +.P +Process termination caused by any reason shall have the following +consequences: +.TP 10 +.BR Note: +These consequences are all extensions to the ISO\ C standard and are not further +CX shaded. However, functionality relating to the XSI option is shaded. +.P +.IP " *" 4 +All of the file descriptors, directory streams, +conversion descriptors, and message catalog descriptors +open in the calling process shall be closed. +.IP " *" 4 +If the parent process of the calling process is executing a +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(), +and has neither set its SA_NOCLDWAIT flag nor set SIGCHLD to SIG_IGN, +it shall be notified of termination of the calling process and the +low-order eight bits (that is, bits 0377) of +.IR status +shall be made available to it. If the parent is not waiting, the child's +status shall be made available to it when the parent subsequently +executes +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(). +.RS 4 +.P +The semantics of the +\fIwaitid\fR() +function shall be equivalent to +\fIwait\fR(). +.RE +.IP " *" 4 +If the parent process of the calling process is not executing a +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(), +and has neither set its SA_NOCLDWAIT flag nor set SIGCHLD to SIG_IGN, +the calling process shall be transformed into a \fIzombie process\fP. +A \fIzombie process\fP is an inactive process and it shall be deleted +at some later time when its parent process executes +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(). +.RS 4 +.P +The semantics of the +\fIwaitid\fR() +function shall be equivalent to +\fIwait\fR(). +.RE +.IP " *" 4 +Termination of a process does not directly terminate its children. The +sending of a SIGHUP +signal as described below indirectly terminates children in some +circumstances. +.IP " *" 4 +Either: +.RS 4 +.P +If the implementation supports the SIGCHLD +signal, a SIGCHLD shall be sent to the parent process. +.P +Or: +.P +If the parent process has set its SA_NOCLDWAIT flag, +or set SIGCHLD to SIG_IGN, the status shall be +discarded, and the lifetime of the calling process shall end +immediately. If SA_NOCLDWAIT is set, it is implementation-defined +whether a SIGCHLD signal is sent to the parent process. +.RE +.IP " *" 4 +The parent process ID of all of the existing child processes and +zombie processes of the calling process shall be set to the process ID +of an implementation-defined system process. That is, these processes +shall be inherited by a special system process. +.IP " *" 4 +Each attached shared-memory segment is detached and the value of +.IR shm_nattch +(see +\fIshmget\fR()) +in the data structure associated with its shared memory ID +shall be decremented by 1. +.IP " *" 4 +For each semaphore for which the calling process has set a +.IR semadj +value (see +\fIsemop\fR()), +that value shall be added to the +.IR semval +of the specified semaphore. +.IP " *" 4 +If the process is a controlling process, the SIGHUP +signal shall be sent to each process in the foreground process group of +the controlling terminal belonging to the calling process. +.IP " *" 4 +If the process is a controlling process, the controlling terminal +associated with the session shall be disassociated from the session, +allowing it to be acquired by a new controlling process. +.IP " *" 4 +If the exit of the process causes a process group to become orphaned, +and if any member of the newly-orphaned process group is stopped, then +a SIGHUP signal followed by a SIGCONT signal shall be sent to each +process in the newly-orphaned process group. +.IP " *" 4 +All open named semaphores in the calling process shall be closed as +if by appropriate calls to +\fIsem_close\fR(). +.IP " *" 4 +Any memory locks established by the process via calls to +\fImlockall\fR() +or +\fImlock\fR() +shall be removed. If locked pages in the address space of the calling +process are also mapped into the address spaces of other processes and +are locked by those processes, the locks established by the other +processes shall be unaffected by the call by this process to +\fI_Exit\fR() +or +\fI_exit\fR(). +.IP " *" 4 +Memory mappings that were created in the process shall be unmapped +before the process is destroyed. +.IP " *" 4 +Any blocks of typed memory that were mapped in the calling process +shall be unmapped, as if +\fImunmap\fR() +was implicitly called to unmap them. +.IP " *" 4 +All open message queue descriptors in the calling process shall be +closed as if by appropriate calls to +\fImq_close\fR(). +.IP " *" 4 +Any outstanding cancelable asynchronous I/O operations may be +canceled. Those asynchronous I/O operations that are not canceled +shall complete as if the +\fI_Exit\fR() +or +\fI_exit\fR() +operation had not yet occurred, but any associated signal notifications +shall be suppressed. The +\fI_Exit\fR() +or +\fI_exit\fR() +operation may block awaiting such I/O completion. Whether any +I/O is canceled, and which I/O may be canceled upon +\fI_Exit\fR() +or +\fI_exit\fR(), +is implementation-defined. +.IP " *" 4 +Threads terminated by a call to +\fI_Exit\fR() +or +\fI_exit\fR() +shall not invoke their cancellation cleanup handlers or per-thread data +destructors. +.IP " *" 4 +If the calling process is a trace controller process, any trace streams +that were created by the calling process shall be shut down as +described by the +\fIposix_trace_shutdown\fR() +function, and mapping of trace event names to trace event type identifiers +of any process built for these trace streams may be deallocated. +.SH "RETURN VALUE" +These functions do not return. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Normally applications should use +\fIexit\fR() +rather than +\fI_Exit\fR() +or +\fI_exit\fR(). +.SH RATIONALE +.SS "Process Termination" +.P +Early proposals drew a distinction between normal and abnormal process +termination. Abnormal termination was caused only by certain signals +and resulted in implementation-defined ``actions'', as discussed below. +Subsequent proposals distinguished three types of termination: +\fInormal termination\fP (as in the current specification), \fIsimple +abnormal termination\fP, and \fIabnormal termination with actions\fP. +Again the distinction between the two types of abnormal termination was +that they were caused by different signals and that +implementation-defined actions would result in the latter case. Given +that these actions were completely implementation-defined, the early +proposals were only saying when the actions could occur and how their +occurrence could be detected, but not what they were. This was of +little or no use to conforming applications, and thus the distinction is +not made in this volume of POSIX.1\(hy2008. +.P +The implementation-defined actions usually include, in most +historical implementations, the creation of a file named +.BR core +in the current working directory of the process. This file contains an +image of the memory of the process, together with descriptive +information about the process, perhaps sufficient to reconstruct the +state of the process at the receipt of the signal. +.P +There is a potential security problem in creating a +.BR core +file if the process was set-user-ID +and the current user is not the owner of the program, if the process +was set-group-ID +and none of the user's groups match the group of the program, or if the +user does not have permission to write in the current directory. In +this situation, an implementation either should not create a +.BR core +file or should make it unreadable by the user. +.P +Despite the silence of this volume of POSIX.1\(hy2008 on this feature, applications are +advised not to create files named +.BR core +because of potential conflicts in many implementations. Some +implementations use a name other than +.BR core +for the file; for example, by appending the process ID to the filename. +.SS "Terminating a Process" +.P +It is important that the consequences of process termination as +described occur regardless of whether the process called +\fI_exit\fR() +(perhaps indirectly through +\fIexit\fR()) +or instead was terminated due to a signal or for some other reason. +Note that in the specific case of +\fIexit\fR() +this means that the +.IR status +argument to +\fIexit\fR() +is treated in the same way as the +.IR status +argument to +\fI_exit\fR(). +.P +A language other than C may have other termination primitives than the +C-language +\fIexit\fR() +function, and programs written in such a language should use its native +termination primitives, but those should have as part of their function +the behavior of +\fI_exit\fR() +as described. Implementations in languages other than C are outside +the scope of this version of this volume of POSIX.1\(hy2008, however. +.P +As required by the ISO\ C standard, using +.BR return +from +\fImain\fR() +has the same behavior (other than with respect to language scope +issues) as calling +\fIexit\fR() +with the returned value. Reaching the end of the +\fImain\fR() +function has the same behavior as calling +.IR exit (0). +.P +A value of zero (or EXIT_SUCCESS, which is required to be zero) +for the argument +.IR status +conventionally indicates successful termination. This corresponds to +the specification for +\fIexit\fR() +in the ISO\ C standard. The convention is followed by utilities such as +.IR make +and various shells, which interpret a zero status +from a child process as success. For this reason, applications should +not call \fIexit\fP(0) or \fI_exit\fP(0) when they terminate +unsuccessfully; for example, in signal-catching functions. +.P +Historically, the implementation-defined process that inherits +children whose parents have terminated without waiting on them is +called +.IR init +and has a process ID of 1. +.P +The sending of a SIGHUP +to the foreground process group when a controlling process terminates +corresponds to somewhat different historical implementations. In System +V, the kernel sends a +SIGHUP on termination of (essentially) a controlling process. In 4.2 BSD, +the kernel does not send SIGHUP in a case like this, but the termination +of a controlling process is usually noticed by a system daemon, which +arranges to send a SIGHUP to the foreground process group with the +\fIvhangup\fR() +function. However, in 4.2 BSD, due to the behavior of the shells that +support job control, +the controlling process is usually a shell with no other processes in +its process group. Thus, a change to make +\fI_exit\fR() +behave this way in such systems should not cause problems with existing +applications. +.P +The termination of a process may cause a process group to become +orphaned in either of two ways. +The connection of a process group to its parent(s) outside of the group +depends on both the parents and their children. Thus, a process group +may be orphaned by the termination of the last connecting parent +process outside of the group or by the termination of the last direct +descendant of the parent process(es). In either case, if the +termination of a process causes a process group to become orphaned, +processes within the group are disconnected from their job control +shell, which no longer has any information on the existence of the +process group. Stopped processes within the group would languish +forever. In order to avoid this problem, newly orphaned process groups +that contain stopped processes are sent a SIGHUP signal and a SIGCONT +signal to indicate that they have been disconnected from their +session. +The SIGHUP signal causes the process group members to terminate unless +they are catching or ignoring SIGHUP. Under most circumstances, all of +the members of the process group are stopped if any of them are +stopped. +.P +The action of sending a SIGHUP and a SIGCONT signal to members of a +newly orphaned process group is similar to the action of 4.2 BSD, which +sends SIGHUP and SIGCONT to each stopped child of an exiting process. +If such children exit in response to the SIGHUP, any additional +descendants receive similar treatment at that time. In this volume of POSIX.1\(hy2008, the +signals are sent to the entire process group at the same time. Also, +in this volume of POSIX.1\(hy2008, but not in 4.2 BSD, stopped processes may be orphaned, but +may be members of a process group that is not orphaned; therefore, the +action taken at +\fI_exit\fR() +must consider processes other than child processes. +.P +It is possible for a process group to be orphaned by a call to +\fIsetpgid\fR() +or +\fIsetsid\fR(), +as well as by process termination. This volume of POSIX.1\(hy2008 does not require sending +SIGHUP and SIGCONT in those cases, because, unlike process termination, +those cases are not caused accidentally by applications that are +unaware of job control. An implementation can choose to send SIGHUP +and SIGCONT in those cases as an extension; such an extension must be +documented as required in +.IR . +.P +The ISO/IEC\ 9899:\|1999 standard adds the +\fI_Exit\fR() +function that results in immediate program termination without +triggering signals or +\fIatexit\fR()-registered +functions. In POSIX.1\(hy2008, this is equivalent to the +\fI_exit\fR() +function. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatexit\fR\^(\|)", +.IR "\fIexit\fR\^(\|)", +.IR "\fImlock\fR\^(\|)", +.IR "\fImlockall\fR\^(\|)", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/_longjmp.3p b/man-pages-posix-2013-a/man3p/_longjmp.3p new file mode 100644 index 0000000..9b155d2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/_longjmp.3p @@ -0,0 +1,130 @@ +'\" et +.TH _LONGJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +_longjmp, +_setjmp +\(em non-local goto +.SH SYNOPSIS +.LP +.nf +#include +.P +void _longjmp(jmp_buf \fIenv\fP, int \fIval\fP); +int _setjmp(jmp_buf \fIenv\fP); +.fi +.SH DESCRIPTION +The +\fI_longjmp\fR() +and +\fI_setjmp\fR() +functions shall be equivalent to +\fIlongjmp\fR() +and +\fIsetjmp\fR(), +respectively, with the additional restriction that +\fI_longjmp\fR() +and +\fI_setjmp\fR() +shall not manipulate the signal mask. +.P +If +\fI_longjmp\fR() +is called even though +.IR env +was never initialized by a call to +\fI_setjmp\fR(), +or when the last such call was in a function that has since returned, +the results are undefined. +.SH "RETURN VALUE" +Refer to +.IR "\fIlongjmp\fR\^(\|)" +and +.IR "\fIsetjmp\fR\^(\|)". +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If +\fI_longjmp\fR() +is executed and the environment in which +\fI_setjmp\fR() +was executed no longer exists, errors can occur. The conditions under +which the environment of the +\fI_setjmp\fR() +no longer exists include exiting the function that contains the +\fI_setjmp\fR() +call, and exiting an inner block with temporary storage. This +condition might not be detectable, in which case the +\fI_longjmp\fR() +occurs and, if the environment no longer exists, the contents of the +temporary storage of an inner block are unpredictable. This condition +might also cause unexpected process termination. If the function has +returned, the results are undefined. +.P +Passing +\fIlongjmp\fR() +a pointer to a buffer not created by +\fIsetjmp\fR(), +passing +\fI_longjmp\fR() +a pointer to a buffer not created by +\fI_setjmp\fR(), +passing +\fIsiglongjmp\fR() +a pointer to a buffer not created by +\fIsigsetjmp\fR(), +or passing any of these three functions a buffer that has been modified +by the user can cause all the problems listed above, and more. +.P +The +\fI_longjmp\fR() +and +\fI_setjmp\fR() +functions are included to support programs written to historical system +interfaces. New applications should use +\fIsiglongjmp\fR() +and +\fIsigsetjmp\fR() +respectively. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fI_longjmp\fR() +and +\fI_setjmp\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIsetjmp\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/_tolower.3p b/man-pages-posix-2013-a/man3p/_tolower.3p new file mode 100644 index 0000000..db6a857 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/_tolower.3p @@ -0,0 +1,72 @@ +'\" et +.TH _TOLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +_tolower +\(em transliterate uppercase characters to lowercase +.SH SYNOPSIS +.LP +.nf +#include +.P +int _tolower(int \fIc\fP); +.fi +.SH DESCRIPTION +The +\fI_tolower\fR() +macro shall be equivalent to \fItolower\fP(\fIc\fP) except that the +application shall ensure that the argument +.IR c +is an uppercase letter. +.SH "RETURN VALUE" +Upon successful completion, +\fI_tolower\fR() +shall return the lowercase letter corresponding to the argument +passed. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications should use the +\fItolower\fR() +function instead of the obsolescent +\fI_tolower\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fI_tolower\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fItolower\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/_toupper.3p b/man-pages-posix-2013-a/man3p/_toupper.3p new file mode 100644 index 0000000..bbdceae --- /dev/null +++ b/man-pages-posix-2013-a/man3p/_toupper.3p @@ -0,0 +1,72 @@ +'\" et +.TH _TOUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +_toupper +\(em transliterate lowercase characters to uppercase +.SH SYNOPSIS +.LP +.nf +#include +.P +int _toupper(int \fIc\fP); +.fi +.SH DESCRIPTION +The +\fI_toupper\fR() +macro shall be equivalent to +\fItoupper\fR() +except that the application shall ensure that the argument +.IR c +is a lowercase letter. +.SH "RETURN VALUE" +Upon successful completion, +\fI_toupper\fR() +shall return the uppercase letter corresponding to the argument passed. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications should use the +\fItoupper\fR() +function instead of the obsolescent +\fI_toupper\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fI_toupper\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIislower\fR\^(\|)", +.IR "\fItoupper\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/a64l.3p b/man-pages-posix-2013-a/man3p/a64l.3p new file mode 100644 index 0000000..e5632ae --- /dev/null +++ b/man-pages-posix-2013-a/man3p/a64l.3p @@ -0,0 +1,159 @@ +'\" et +.TH A64L "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +a64l, +l64a +\(em convert between a 32-bit integer and a radix-64 ASCII string +.SH SYNOPSIS +.LP +.nf +#include +.P +long a64l(const char *\fIs\fP); +char *l64a(long \fIvalue\fP); +.fi +.SH DESCRIPTION +These functions maintain numbers stored in radix-64 ASCII +characters. This is a notation by which 32-bit integers can be +represented by up to six characters; each character represents a digit +in radix-64 notation. If the type +.BR long +contains more than 32 bits, only the low-order 32 bits shall be used for +these operations. +.P +The characters used to represent digits are +.BR '.' +(dot) for 0, +.BR '/' +for 1, +.BR '0' +through +.BR '9' +for [2,11], +.BR 'A' +through +.BR 'Z' +for [12,37], and +.BR 'a' +through +.BR 'z' +for [38,63]. +.P +The +\fIa64l\fR() +function shall take a pointer to a radix-64 representation, in which +the first digit is the least significant, and return the corresponding +.BR long +value. If the string pointed to by +.IR s +contains more than six characters, +\fIa64l\fR() +shall use the first six. If the first six characters of the string +contain a null terminator, +\fIa64l\fR() +shall use only characters preceding the null terminator. The +\fIa64l\fR() +function shall scan the character string from left to right with the +least significant digit on the left, decoding each character as a 6-bit +radix-64 number. If the type +.BR long +contains more than 32 bits, the resulting value is sign-extended. The +behavior of +\fIa64l\fR() +is unspecified if +.IR s +is a null pointer or the string pointed to by +.IR s +was not generated by a previous call to +\fIl64a\fR(). +.P +The +\fIl64a\fR() +function shall take a +.BR long +argument and return a pointer to the corresponding radix-64 +representation. The behavior of +\fIl64a\fR() +is unspecified if +.IR value +is negative. +.P +The value returned by +\fIl64a\fR() +may be a pointer into a static buffer. Subsequent calls to +\fIl64a\fR() +may overwrite the buffer. +.P +The +\fIl64a\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIa64l\fR() +shall return the +.BR long +value resulting from conversion of the input string. If a string +pointed to by +.IR s +is an empty string, +\fIa64l\fR() +shall return 0L. +.P +The +\fIl64a\fR() +function shall return a pointer to the radix-64 representation. If +.IR value +is 0L, +\fIl64a\fR() +shall return a pointer to an empty string. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the type +.BR long +contains more than 32 bits, the result of +\fIa64l\fP(\fIl64a\fP(\fIx\fP)) is +.IR x +in the low-order 32 bits. +.SH RATIONALE +This is not the same encoding as used by either encoding variant +of the +.IR uuencode +utility. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtoul\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIuuencode\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/abort.3p b/man-pages-posix-2013-a/man3p/abort.3p new file mode 100644 index 0000000..56caedb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/abort.3p @@ -0,0 +1,134 @@ +'\" et +.TH ABORT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +abort +\(em generate an abnormal process abort +.SH SYNOPSIS +.LP +.nf +#include +.P +void abort(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIabort\fR() +function shall cause abnormal process termination to occur, unless the +signal SIGABRT is being caught and the signal handler does not return. +.P +The abnormal termination processing shall include the default actions +defined for SIGABRT and may include an attempt to effect +\fIfclose\fR() +on all open streams. +.P +The SIGABRT signal shall be sent to the calling process as if by means +of +\fIraise\fR() +with the argument SIGABRT. +.P +The status made available to +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +by +\fIabort\fR() +shall be that of a process terminated by the SIGABRT signal. +The +\fIabort\fR() +function shall override blocking or ignoring the SIGABRT signal. +.SH "RETURN VALUE" +The +\fIabort\fR() +function shall not return. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Catching the signal is intended to provide the application developer with +a portable means to abort processing, free from possible interference +from any implementation-supplied functions. +.SH RATIONALE +The ISO/IEC\ 9899:\|1999 standard requires the +\fIabort\fR() +function to be async-signal-safe. Since POSIX.1\(hy2008 defers to the ISO\ C standard, +this required a change to the DESCRIPTION from ``shall include the +effect of +\fIfclose\fR()'' +to ``may include an attempt to effect +\fIfclose\fR().'' +.P +The revised wording permits some backwards-compatibility and avoids a +potential deadlock situation. +.P +The Open Group Base Resolution bwg2002\(hy003 is applied, removing the +following XSI shaded paragraph from the DESCRIPTION: +.P +``On XSI-conformant systems, in addition the abnormal termination +processing shall include the effect of +\fIfclose\fR() +on message catalog descriptors.'' +.P +There were several reasons to remove this paragraph: +.IP " *" 4 +No special processing of open message catalogs needs to be performed +prior to abnormal process termination. +.IP " *" 4 +The main reason to specifically mention that +\fIabort\fR() +includes the effect of +\fIfclose\fR() +on open streams is to flush output queued on the stream. Message +catalogs in this context are read-only and, therefore, do not need to +be flushed. +.IP " *" 4 +The effect of +\fIfclose\fR() +on a message catalog descriptor is unspecified. Message catalog +descriptors are allowed, but not required to be implemented using a +file descriptor, but there is no mention in POSIX.1\(hy2008 of a message catalog +descriptor using a standard I/O stream FILE object as would be expected +by +\fIfclose\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexit\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/abs.3p b/man-pages-posix-2013-a/man3p/abs.3p new file mode 100644 index 0000000..ebad567 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/abs.3p @@ -0,0 +1,70 @@ +'\" et +.TH ABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +abs +\(em return an integer absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +int abs(int \fIi\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIabs\fR() +function shall compute the absolute value of its integer operand, +.IR i . +If the result cannot be represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIabs\fR() +function shall return the absolute value of its integer operand. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +In two's-complement representation, the absolute value of the negative +integer with largest magnitude +{INT_MIN} +might not be representable. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfabs\fR\^(\|)", +.IR "\fIlabs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/accept.3p b/man-pages-posix-2013-a/man3p/accept.3p new file mode 100644 index 0000000..b4a7a3e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/accept.3p @@ -0,0 +1,190 @@ +'\" et +.TH ACCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +accept +\(em accept a new connection on a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +int accept(int \fIsocket\fP, struct sockaddr *restrict \fIaddress\fP, + socklen_t *restrict \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIaccept\fR() +function shall extract the first connection on the queue of pending +connections, create a new socket with the same socket type protocol +and address family as the specified socket, and allocate a new file +descriptor for that socket. +.P +The +\fIaccept\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies a socket that was created with +\fIsocket\fR(), +has been bound to an address with +\fIbind\fR(), +and has issued a successful call to +\fIlisten\fR(). +.IP "\fIaddress\fR" 12 +Either a null pointer, or a pointer to a +.BR sockaddr +structure where the address of the connecting socket shall be returned. +.IP "\fIaddress_len\fR" 12 +Either a null pointer, if +.IR address +is a null pointer, or a pointer to a +.BR socklen_t +object which on input specifies the length of the supplied +.BR sockaddr +structure, and on output specifies the length of the stored address. +.P +If +.IR address +is not a null pointer, the address of the peer for the accepted +connection shall be stored in the +.BR sockaddr +structure pointed to by +.IR address , +and the length of this address shall be stored in the object pointed to +by +.IR address_len . +.P +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. +.P +If the protocol permits connections by unbound clients, and the peer is +not bound, then the value stored in the object pointed to by +.IR address +is unspecified. +.P +If the listen queue is empty of connection requests and O_NONBLOCK is +not set on the file descriptor for the socket, +\fIaccept\fR() +shall block until a connection is present. If the +\fIlisten\fR() +queue is empty of connection requests and O_NONBLOCK is set on the file +descriptor for the socket, +\fIaccept\fR() +shall fail and set +.IR errno +to +.BR [EAGAIN] +or +.BR [EWOULDBLOCK] . +.P +The accepted socket cannot itself accept more connections. The original +socket remains open and can accept more connections. +.SH "RETURN VALUE" +Upon successful completion, +\fIaccept\fR() +shall return the non-negative file descriptor of the accepted socket. +Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIaccept\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +O_NONBLOCK is set for the socket file descriptor and no connections are +present to be accepted. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNABORTED +.br +A connection has been aborted. +.TP +.BR EINTR +The +\fIaccept\fR() +function was interrupted by a signal that was caught before a valid +connection arrived. +.TP +.BR EINVAL +The +.IR socket +is not accepting connections. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum number of file descriptors in the system are already open. +.TP +.BR ENOBUFS +No buffer space is available. +.TP +.BR ENOMEM +There was insufficient memory available to complete the operation. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The socket type of the specified socket does not support accepting +connections. +.P +The +\fIaccept\fR() +function may fail if: +.TP +.BR EPROTO +A protocol error has occurred; +for example, the STREAMS protocol stack has not been initialized. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +When a connection is available, +\fIselect\fR() +indicates that the file descriptor for the socket is ready for reading. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbind\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIlisten\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/access.3p b/man-pages-posix-2013-a/man3p/access.3p new file mode 100644 index 0000000..955556d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/access.3p @@ -0,0 +1,294 @@ +'\" et +.TH ACCESS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +access, faccessat +\(em determine accessibility of a file relative to directory file +descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int access(const char *\fIpath\fP, int \fIamode\fP); +int faccessat(int \fIfd\fP, const char *\fIpath\fP, int \fIamode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIaccess\fR() +function shall check the file named by the pathname pointed to by the +.IR path +argument for accessibility according to the bit pattern contained in +.IR amode , +using the real user ID in place of the effective user ID and the real +group ID in place of the effective group ID. +.P +The value of +.IR amode +is either the bitwise-inclusive OR of the access permissions to be +checked (R_OK, W_OK, X_OK) or the existence test (F_OK). +.P +If any access permissions are checked, each shall be checked +individually, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions", +except that where that description refers to execute permission for +a process with appropriate privileges, an implementation may indicate +success for X_OK even if execute permission is not granted to any user. +.P +The +\fIfaccessat\fR() +function shall be equivalent to the +\fIaccess\fR() +function, except in the case where +.IR path +specifies a relative path. In this case the file whose accessibility is +to be determined shall be located relative to the directory associated +with the file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +If +\fIfaccessat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIaccess\fR(). +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_EACCESS 12 +The checks for accessibility are performed using the effective user and +group IDs instead of the real user and group ID as required in a call +to +\fIaccess\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. Otherwise, +these functions shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Permission bits of the file mode do not permit the requested access, or +search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EROFS +Write access is requested for a file on a read-only file system. +.P +The +\fIfaccessat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EINVAL +The value of the \fIamode\fP argument is invalid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +Write access is requested for a pure procedure (shared text) file that +is being executed. +.P +The +\fIfaccessat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Testing for the Existence of a File" +.P +The following example tests whether a file named +.BR myfile +exists in the +.BR /tmp +directory. +.sp +.RS 4 +.nf +\fB +#include +\&... +int result; +const char *pathname = "/tmp/myfile"; +.P +result = access (pathname, F_OK); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Additional values of +.IR amode +other than the set defined in the description may be valid; for +example, if a system has extended access controls. +.P +The use of the AT_EACCESS value for +.IR flag +enables functionality not available in +\fIaccess\fR(). +.SH RATIONALE +In early proposals, some inadequacies in the +\fIaccess\fR() +function led to the creation of an +\fIeaccess\fR() +function because: +.IP " 1." 4 +Historical implementations of +\fIaccess\fR() +do not test file access correctly when the process' +real user ID is +superuser. In particular, they always return zero when testing execute +permissions without regard to whether the file is executable. +.IP " 2." 4 +The superuser has complete access to all files on a system. As a +consequence, programs started by the superuser and switched to the +effective user ID +with lesser privileges cannot use +\fIaccess\fR() +to test their file access permissions. +.P +However, the historical model of +\fIeaccess\fR() +does not resolve problem (1), so this volume of POSIX.1\(hy2008 now allows +\fIaccess\fR() +to behave in the desired way because several implementations have +corrected the problem. It was also argued that problem (2) is more +easily solved by using +\fIopen\fR(), +\fIchdir\fR(), +or one of the +.IR exec +functions as appropriate and responding to the error, rather than +creating a new function that would not be as reliable. Therefore, +\fIeaccess\fR() +is not included in this volume of POSIX.1\(hy2008. +.P +The sentence concerning appropriate privileges and execute permission +bits +reflects the two possibilities implemented by historical +implementations when checking superuser access for X_OK. +.P +New implementations are discouraged from returning X_OK unless at least +one execution permission bit is set. +.P +The purpose of the +\fIfaccessat\fR() +function is to enable the checking of the accessibility of files in +directories other than the current working directory without exposure +to race conditions. Any part of the path of a file could be changed in +parallel to a call to +\fIaccess\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIfaccessat\fR() +function it can be guaranteed that the file tested for accessibility is +located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/acos.3p b/man-pages-posix-2013-a/man3p/acos.3p new file mode 100644 index 0000000..16df697 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/acos.3p @@ -0,0 +1,120 @@ +'\" et +.TH ACOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +acos, +acosf, +acosl +\(em arc cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double acos(double \fIx\fP); +float acosf(float \fIx\fP); +long double acosl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the principal value of the arc cosine of +their argument +.IR x . +The value of +.IR x +should be in the range [\(mi1,1]. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the arc +cosine of +.IR x , +in the range [0,\(*p] radians. +.P +For finite values of +.IR x +not in the range [\(mi1,1], a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is +1, +0 shall be returned. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is finite and is not in the range [\(mi1,1], +or is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcos\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/acosh.3p b/man-pages-posix-2013-a/man3p/acosh.3p new file mode 100644 index 0000000..f5cecba --- /dev/null +++ b/man-pages-posix-2013-a/man3p/acosh.3p @@ -0,0 +1,118 @@ +'\" et +.TH ACOSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +acosh, +acoshf, +acoshl +\(em inverse hyperbolic cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double acosh(double \fIx\fP); +float acoshf(float \fIx\fP); +long double acoshl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the inverse hyperbolic cosine of their +argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the inverse +hyperbolic cosine of their argument. +.P +For finite values of +.IR x +< 1, a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is +1, +0 shall be returned. +.P +If +.IR x +is +Inf, +Inf shall be returned. +.P +If +.IR x +is \(miInf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is finite and less than +1.0, +or is \(miInf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcosh\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/acosl.3p b/man-pages-posix-2013-a/man3p/acosl.3p new file mode 100644 index 0000000..dfba44b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/acosl.3p @@ -0,0 +1,38 @@ +'\" et +.TH ACOSL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +acosl +\(em arc cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double acosl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIacos\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/aio_cancel.3p b/man-pages-posix-2013-a/man3p/aio_cancel.3p new file mode 100644 index 0000000..25b8388 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/aio_cancel.3p @@ -0,0 +1,118 @@ +'\" et +.TH AIO_CANCEL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +aio_cancel +\(em cancel an asynchronous I/O request +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_cancel(int \fIfildes\fP, struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_cancel\fR() +function shall attempt to cancel one or more asynchronous I/O requests +currently outstanding against file descriptor +.IR fildes . +The +.IR aiocbp +argument points to the asynchronous I/O control block for a particular +request to be canceled. If +.IR aiocbp +is NULL, then all outstanding cancelable asynchronous I/O requests +against +.IR fildes +shall be canceled. +.P +Normal asynchronous notification shall occur for asynchronous I/O +operations that are successfully canceled. If there are requests that +cannot be canceled, then the normal asynchronous completion process +shall take place for those requests when they are completed. +.P +For requested operations that are successfully canceled, the associated +error status shall be set to +.BR [ECANCELED] +and the return status shall be \(mi1. For requested operations that are +not successfully canceled, the +.IR aiocbp +shall not be modified by +\fIaio_cancel\fR(). +.P +If +.IR aiocbp +is not NULL, then if +.IR fildes +does not have the same value as the file descriptor with which the +asynchronous operation was initiated, unspecified results occur. +.P +Which operations are cancelable is implementation-defined. +.SH "RETURN VALUE" +The +\fIaio_cancel\fR() +function shall return the value AIO_CANCELED +if the requested operation(s) were canceled. +The value AIO_NOTCANCELED +shall be returned if at least one of the requested operation(s) cannot +be canceled because it is in progress. In this case, the state of the +other operations, if any, referenced in the call to +\fIaio_cancel\fR() +is not indicated by the return value of +\fIaio_cancel\fR(). +The application may determine the state of affairs for these operations +by using +\fIaio_error\fR(). +The value AIO_ALLDONE +is returned if all of the operations have already completed. +Otherwise, the function shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_cancel\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/aio_error.3p b/man-pages-posix-2013-a/man3p/aio_error.3p new file mode 100644 index 0000000..69a04fe --- /dev/null +++ b/man-pages-posix-2013-a/man3p/aio_error.3p @@ -0,0 +1,117 @@ +'\" et +.TH AIO_ERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +aio_error +\(em retrieve errors status for an asynchronous I/O operation +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_error(const struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_error\fR() +function shall return the error status associated with the +.BR aiocb +structure referenced by the +.IR aiocbp +argument. The error status for an asynchronous I/O operation is the +.IR errno +value that would be set by the corresponding +\fIread\fR(), +\fIwrite\fR(), +\fIfdatasync\fR(), +or +\fIfsync\fR() +operation. If the operation has not yet completed, then the error +status shall be equal to +.BR [EINPROGRESS] . +.P +If the +.BR aiocb +structure pointed to by +.IR aiocbp +is not associated with an operation that has been scheduled, the +results are undefined. +.SH "RETURN VALUE" +If the asynchronous I/O operation has completed successfully, then 0 +shall be returned. If the asynchronous operation has completed +unsuccessfully, then the error status, as described for +\fIread\fR(), +\fIwrite\fR(), +\fIfdatasync\fR(), +and +\fIfsync\fR(), +shall be returned. If the asynchronous I/O operation has not yet +completed, then +.BR [EINPROGRESS] +shall be returned. +.P +If the +\fIaio_error\fR() +function fails, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_error\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR aiocbp +argument does not refer to an asynchronous operation whose return +status has not yet been retrieved. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_fsync\fR\^(\|)", +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/aio_fsync.3p b/man-pages-posix-2013-a/man3p/aio_fsync.3p new file mode 100644 index 0000000..5b2435e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/aio_fsync.3p @@ -0,0 +1,191 @@ +'\" et +.TH AIO_FSYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +aio_fsync +\(em asynchronous file synchronization +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_fsync(int \fIop\fP, struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_fsync\fR() +function shall asynchronously perform a file synchronization operation, +as specified by the +.IR op +argument, for I/O operations associated with the file indicated by the +file descriptor +.IR aio_fildes +member of the +.BR aiocb +structure referenced by the +.IR aiocbp +argument and queued at the time of the call to +\fIaio_fsync\fR(). +The function call shall return when the synchronization request has been +initiated or queued to the file or device (even when the data cannot be +synchronized immediately). +.P +If +.IR op +is O_DSYNC, +all currently queued I/O operations shall be completed as if by a call to +\fIfdatasync\fR(); +that is, as defined for synchronized I/O data integrity completion. +.P +If +.IR op +is O_SYNC, +all currently queued I/O operations shall be completed as if by a call to +\fIfsync\fR(); +that is, as defined for synchronized I/O file integrity completion. +If the +\fIaio_fsync\fR() +function fails, or if the operation queued by +\fIaio_fsync\fR() +fails, then outstanding I/O operations are not guaranteed to have been +completed. +.P +If +\fIaio_fsync\fR() +succeeds, then it is only the I/O that was queued at the time of the +call to +\fIaio_fsync\fR() +that is guaranteed to be forced to the relevant completion state. The +completion of subsequent I/O on the file descriptor is not guaranteed +to be completed in a synchronized fashion. +.P +The +.IR aiocbp +argument refers to an asynchronous I/O control block. The +.IR aiocbp +value may be used as an argument to +\fIaio_error\fR() +and +\fIaio_return\fR() +in order to determine the error status and return status, respectively, +of the asynchronous operation while it is proceeding. When the request +is queued, the error status for the operation is +.BR [EINPROGRESS] . +When all data has been successfully transferred, the error status shall +be reset to reflect the success or failure of the operation. If the +operation does not complete successfully, the error status for the +operation shall be set to indicate the error. The +.IR aio_sigevent +member determines the asynchronous notification to occur as specified +in +.IR "Section 2.4.1" ", " "Signal Generation and Delivery" +when all operations have achieved synchronized I/O completion. All +other members of the structure referenced by +.IR aiocbp +are ignored. If the control block referenced by +.IR aiocbp +becomes an illegal address prior to asynchronous I/O completion, then +the behavior is undefined. +.P +If the +\fIaio_fsync\fR() +function fails or +.IR aiocbp +indicates an error condition, data is not guaranteed to have been +successfully transferred. +.SH "RETURN VALUE" +The +\fIaio_fsync\fR() +function shall return the value 0 if the I/O operation is successfully +queued; otherwise, the function shall return the value \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_fsync\fR() +function shall fail if: +.TP +.BR EAGAIN +The requested asynchronous operation was not queued due to +temporary resource limitations. +.TP +.BR EBADF +The +.IR aio_fildes +member of the +.BR aiocb +structure referenced by the +.IR aiocbp +argument is not a valid file descriptor open for writing. +.TP +.BR EINVAL +This implementation does not support synchronized I/O for this file. +.TP +.BR EINVAL +The +.IR aio_fildes +member of the +.BR aiocb +structure refers to a file on which an +\fIfsync\fR() +operation is not possible. +.TP +.BR EINVAL +A value of +.IR op +other than O_DSYNC or O_SYNC was specified, or O_DSYNC was specified and +the implementation does not provide runtime support for the Synchronized +Input and Output option, or O_SYNC was specified and the implementation +does not provide runtime support for the File Synchronization option. +.P +In the event that any of the queued I/O operations fail, +\fIaio_fsync\fR() +shall return the error condition defined for +\fIread\fR() +and +\fIwrite\fR(). +The error is returned in the error status for the asynchronous operation, +which can be retrieved using +\fIaio_error\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfdatasync\fR\^(\|)", +.IR "\fIfsync\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/aio_read.3p b/man-pages-posix-2013-a/man3p/aio_read.3p new file mode 100644 index 0000000..2ff7112 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/aio_read.3p @@ -0,0 +1,208 @@ +'\" et +.TH AIO_READ "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +aio_read +\(em asynchronous read from a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_read(struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_read\fR() +function shall read \fIaiocbp\fP\->\fIaio_nbytes\fR from the file +associated with \fIaiocbp\fP\->\fIaio_fildes\fR into the buffer pointed +to by \fIaiocbp\fP\->\fIaio_buf\fR. The function call shall return when +the read request has been initiated or queued to the file or device +(even when the data cannot be delivered immediately). +.P +If prioritized I/O is supported for this file, then the asynchronous +operation shall be submitted at a priority equal to a base scheduling +priority minus \fIaiocbp\fP\->\fIaio_reqprio\fR. If Thread Execution +Scheduling is not supported, then the base scheduling priority is that +of the calling process; +.br +otherwise, the base scheduling priority is that of the calling thread. +.P +The +.IR aiocbp +value may be used as an argument to +\fIaio_error\fR() +and +\fIaio_return\fR() +in order to determine the error status and return status, respectively, +of the asynchronous operation while it is proceeding. If an error +condition is encountered during queuing, the function call shall return +without having initiated or queued the request. The requested +operation takes place at the absolute position in the file as given by +.IR aio_offset , +as if +\fIlseek\fR() +were called immediately prior to the operation with an +.IR offset +equal to +.IR aio_offset +and a +.IR whence +equal to SEEK_SET. +After a successful call to enqueue an asynchronous I/O operation, the +value of the file offset for the file is unspecified. +.P +The +.IR aio_sigevent +member specifies the notification which occurs when the request is +completed. +.P +The \fIaiocbp\fP\->\fIaio_lio_opcode\fR field shall be ignored by +\fIaio_read\fR(). +.P +The +.IR aiocbp +argument points to an +.BR aiocb +structure. If the buffer pointed to by \fIaiocbp\fP\->\fIaio_buf\fR or +the control block pointed to by +.IR aiocbp +becomes an illegal address prior to asynchronous I/O completion, then +the behavior is undefined. +.P +Simultaneous asynchronous operations using the same +.IR aiocbp +produce undefined results. +.P +If synchronized I/O is enabled on the file associated with +\fIaiocbp\fP\->\fIaio_fildes\fR, the behavior of this function shall +be according to the definitions of synchronized I/O data integrity +completion and synchronized I/O file integrity completion. +.P +For any system action that changes the process memory space while an +asynchronous I/O is outstanding to the address range being changed, the +result of that action is undefined. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP\->\fIaio_fildes\fR. +.SH "RETURN VALUE" +The +\fIaio_read\fR() +function shall return the value zero if the I/O operation is +successfully queued; otherwise, the function shall return the value +\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_read\fR() +function shall fail if: +.TP +.BR EAGAIN +The requested asynchronous I/O operation was not queued due to system +resource limitations. +.P +Each of the following conditions may be detected synchronously at the +time of the call to +\fIaio_read\fR(), +or asynchronously. If any of the conditions below are detected +synchronously, the +\fIaio_read\fR() +function shall return \(mi1 and set +.IR errno +to the corresponding value. If any of the conditions below are +detected asynchronously, the return status of the asynchronous +operation is set to \(mi1, and the error status of the asynchronous +operation is set to the corresponding value. +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fP argument is not a valid file +descriptor open for reading. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid, +.br +\fIaiocbp\fP\->\fIaio_reqprio\fR is not a valid value, +or \fIaiocbp\fP\->\fIaio_nbytes\fR is an invalid value. +.P +In the case that the +\fIaio_read\fR() +successfully queues the I/O operation but the operation is subsequently +canceled or encounters an error, the return status of the asynchronous +operation is one of the values normally returned by the +\fIread\fR() +function call. In addition, the error status of the asynchronous +operation is set to one of the error statuses normally set by the +\fIread\fR() +function call, or one of the following values: +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file +descriptor open for reading. +.TP +.BR ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit +\fIaio_cancel\fR() +request. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid. +.P +The following condition may be detected synchronously or asynchronously: +.TP +.BR EOVERFLOW +The file is a regular file, \fIaiobcp\fP\->\fIaio_nbytes\fR is greater +than 0, and the starting offset in \fIaiobcp\fP\->\fIaio_offset\fR is +before the end-of-file and is at or beyond the offset maximum in the +open file description associated with \fIaiocbp\fP\->\fIaio_fildes\fR. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/aio_return.3p b/man-pages-posix-2013-a/man3p/aio_return.3p new file mode 100644 index 0000000..9bfafbf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/aio_return.3p @@ -0,0 +1,120 @@ +'\" et +.TH AIO_RETURN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +aio_return +\(em retrieve return status of an asynchronous I/O operation +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t aio_return(struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_return\fR() +function shall return the return status associated with the +.BR aiocb +structure referenced by the +.IR aiocbp +argument. The return status for an asynchronous I/O operation is the +value that would be returned by the corresponding +\fIread\fR(), +\fIwrite\fR(), +or +\fIfsync\fR() +function call. If the error status for the operation is equal to +.BR [EINPROGRESS] , +then the return status for the operation is undefined. The +\fIaio_return\fR() +function may be called exactly once to retrieve the return status of a +given asynchronous operation; thereafter, if the same +.BR aiocb +structure is used in a call to +\fIaio_return\fR() +or +\fIaio_error\fR(), +an error may be returned. When the +.BR aiocb +structure referred to by +.IR aiocbp +is used to submit another asynchronous operation, then +\fIaio_return\fR() +may be successfully used to retrieve the return status of that +operation. +.SH "RETURN VALUE" +If the asynchronous I/O operation has completed, then the return +status, as described for +\fIread\fR(), +\fIwrite\fR(), +and +\fIfsync\fR(), +shall be returned. If the asynchronous I/O operation has not yet +completed, the results of +\fIaio_return\fR() +are undefined. +.P +If the +\fIaio_return\fR() +function fails, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_return\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR aiocbp +argument does not refer to an asynchronous operation whose return +status has not yet been retrieved. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_fsync\fR\^(\|)", +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/aio_suspend.3p b/man-pages-posix-2013-a/man3p/aio_suspend.3p new file mode 100644 index 0000000..fda1d0f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/aio_suspend.3p @@ -0,0 +1,132 @@ +'\" et +.TH AIO_SUSPEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +aio_suspend +\(em wait for an asynchronous I/O request +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_suspend(const struct aiocb *const \fIlist\fP[], int \fInent\fP, + const struct timespec *\fItimeout\fP); +.fi +.SH DESCRIPTION +The +\fIaio_suspend\fR() +function shall suspend the calling thread until at least one of the +asynchronous I/O operations referenced by the +.IR list +argument has completed, until a signal interrupts the function, or, if +.IR timeout +is not NULL, until the time interval specified by +.IR timeout +has passed. If any of the +.BR aiocb +structures in the list correspond to completed asynchronous I/O +operations (that is, the error status for the operation is not equal to +.BR [EINPROGRESS] ) +at the time of the call, the function shall return without suspending +the calling thread. The +.IR list +argument is an array of pointers to asynchronous I/O control blocks. +The +.IR nent +argument indicates the number of elements in the array. Each +.BR aiocb +structure pointed to has been used in initiating an asynchronous +I/O request via +\fIaio_read\fR(), +\fIaio_write\fR(), +or +\fIlio_listio\fR(). +This array may contain null pointers, which are ignored. If this array +contains pointers that refer to +.BR aiocb +structures that have not been used in submitting asynchronous I/O, the +effect is undefined. +.P +If the time interval indicated in the +.BR timespec +structure pointed to by +.IR timeout +passes before any of the I/O operations referenced by +.IR list +are completed, then +\fIaio_suspend\fR() +shall return with an error. +If the Monotonic Clock option is supported, the clock that shall be +used to measure this time interval shall be the CLOCK_MONOTONIC clock. +.SH "RETURN VALUE" +If the +\fIaio_suspend\fR() +function returns after one or more asynchronous I/O operations have +completed, the function shall return zero. Otherwise, the function shall +return a value of \(mi1 and set +.IR errno +to indicate the error. +.P +The application may determine which asynchronous I/O completed by +scanning the associated error and return status using +\fIaio_error\fR() +and +\fIaio_return\fR(), +respectively. +.SH ERRORS +The +\fIaio_suspend\fR() +function shall fail if: +.TP +.BR EAGAIN +No asynchronous I/O indicated in the list referenced by +.IR list +completed in the time interval indicated by +.IR timeout . +.TP +.BR EINTR +A signal interrupted the +\fIaio_suspend\fR() +function. Note that, since each asynchronous I/O operation may +possibly provoke a signal when it completes, this error return may be +caused by the completion of one (or more) of the very I/O operations +being awaited. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/aio_write.3p b/man-pages-posix-2013-a/man3p/aio_write.3p new file mode 100644 index 0000000..e3bbb1b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/aio_write.3p @@ -0,0 +1,218 @@ +'\" et +.TH AIO_WRITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +aio_write +\(em asynchronous write to a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_write(struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_write\fR() +function shall write \fIaiocbp\fP\->\fIaio_nbytes\fR to the file +associated with \fIaiocbp\fP\->\fIaio_fildes\fR from the buffer pointed +to by \fIaiocbp\fP\->\fIaio_buf\fR. The function shall return when +the write request has been initiated or, at a minimum, queued to the +file or device. +.P +If prioritized I/O is supported for this file, then the asynchronous +operation shall be submitted at a priority equal to a base scheduling +priority minus \fIaiocbp\fP\->\fIaio_reqprio\fR. If Thread Execution +Scheduling is not supported, then the base scheduling priority is that +of the calling process; +.br +otherwise, the base scheduling priority is that of the calling thread. +.P +The +.IR aiocbp +argument may be used as an argument to +\fIaio_error\fR() +and +\fIaio_return\fR() +in order to determine the error status and return status, respectively, +of the asynchronous operation while it is proceeding. +.P +The +.IR aiocbp +argument points to an +.BR aiocb +structure. If the buffer pointed to by \fIaiocbp\fP\->\fIaio_buf\fR or +the control block pointed to by +.IR aiocbp +becomes an illegal address prior to asynchronous I/O completion, then +the behavior is undefined. +.P +If O_APPEND is not set for the file descriptor +.IR aio_fildes , +then the requested operation shall take place at the absolute +position in the file as given by +.IR aio_offset , +as if +\fIlseek\fR() +were called immediately prior to the operation with an +.IR offset +equal to +.IR aio_offset +and a +.IR whence +equal to SEEK_SET. +If O_APPEND is set for the file descriptor, or if +.IR aio_fildes +is associated with a device that is incapable of seeking, write operations +append to the file in the same order as the calls were made, except +under circumstances described in +.IR "Section 2.8.2" ", " "Asynchronous I/O". +After a successful call to enqueue an asynchronous I/O operation, the +value of the file offset for the file is unspecified. +.P +The +.IR aio_sigevent +member specifies the notification which occurs when the request is +completed. +.P +The \fIaiocbp\fP\->\fIaio_lio_opcode\fR field shall be ignored by +\fIaio_write\fR(). +.P +Simultaneous asynchronous operations using the same +.IR aiocbp +produce undefined results. +.P +If synchronized I/O is enabled on the file associated with +\fIaiocbp\fP\->\fIaio_fildes\fR, the behavior of this function shall +be according to the definitions of synchronized I/O data integrity +completion, and synchronized I/O file integrity completion. +.P +For any system action that changes the process memory space while an +asynchronous I/O is outstanding to the address range being changed, the +result of that action is undefined. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP\->\fIaio_fildes\fR. +.SH "RETURN VALUE" +The +\fIaio_write\fR() +function shall return the value zero if the I/O operation is +successfully queued; otherwise, the function shall return the value +\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_write\fR() +function shall fail if: +.TP +.BR EAGAIN +The requested asynchronous I/O operation was not queued due to system +resource limitations. +.P +Each of the following conditions may be detected synchronously at the +time of the call to +\fIaio_write\fR(), +or asynchronously. If any of the conditions below are detected +synchronously, the +\fIaio_write\fR() +function shall return \(mi1 and set +.IR errno +to the corresponding value. If any of the conditions below are detected +asynchronously, the return status of the asynchronous operation shall +be set to \(mi1, and the error status of the asynchronous operation +is set to the corresponding value. +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file +descriptor open for writing. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid, +.br +\fIaiocbp\fP\->\fIaio_reqprio\fR is not a valid value, +or \fIaiocbp\fP\->\fIaio_nbytes\fR is an invalid value. +.P +In the case that the +\fIaio_write\fR() +successfully queues the I/O operation, the return status of the +asynchronous operation shall be one of the values normally returned +by the +\fIwrite\fR() +function call. If the operation is successfully queued but is +subsequently canceled or encounters an error, the error status for the +asynchronous operation contains one of the values normally set by the +\fIwrite\fR() +function call, or one of the following: +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file +descriptor open for writing. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid. +.TP +.BR ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit +\fIaio_cancel\fR() +request. +.P +The following condition may be detected synchronously or asynchronously: +.TP +.BR EFBIG +The file is a regular file, \fIaiobcp\fP\->\fIaio_nbytes\fR is greater +than 0, and the starting offset in \fIaiobcp\fP\->\fIaio_offset\fR is +at or beyond the offset maximum in the open file description associated +with \fIaiocbp\fP\->\fIaio_fildes\fR. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.8.2" ", " "Asynchronous I/O", +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/alarm.3p b/man-pages-posix-2013-a/man3p/alarm.3p new file mode 100644 index 0000000..00e93c6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/alarm.3p @@ -0,0 +1,163 @@ +'\" et +.TH ALARM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +alarm +\(em schedule an alarm signal +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned alarm(unsigned \fIseconds\fP); +.fi +.SH DESCRIPTION +The +\fIalarm\fR() +function shall cause the system to generate a SIGALRM signal for the +process after the number of realtime seconds specified by +.IR seconds +have elapsed. Processor scheduling delays may prevent the process from +handling the signal as soon as it is generated. +.P +If +.IR seconds +is 0, a pending alarm request, if any, is canceled. +.P +Alarm requests are not stacked; only one SIGALRM generation can be +scheduled in this manner. If the SIGALRM signal has not yet been +generated, the call shall result in rescheduling the time at which the +SIGALRM signal is generated. +.P +Interactions between +\fIalarm\fR() +and +\fIsetitimer\fR() +are unspecified. +.SH "RETURN VALUE" +If there is a previous +\fIalarm\fR() +request with time remaining, +\fIalarm\fR() +shall return a non-zero value that is the number of seconds until the +previous request would have generated a SIGALRM signal. Otherwise, +\fIalarm\fR() +shall return 0. +.SH ERRORS +The +\fIalarm\fR() +function is always successful, and no return value is reserved to +indicate an error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIfork\fR() +function clears pending alarms in the child process. A new process +image created by one of the +.IR exec +functions inherits the time left to an alarm signal in the +image of the old process. +.P +Application developers should note that the type of the argument +.IR seconds +and the return value of +\fIalarm\fR() +is +.BR unsigned . +That means that a Strictly Conforming POSIX System Interfaces +Application cannot pass a value greater than the minimum guaranteed +value for +{UINT_MAX}, +which the ISO\ C standard +sets as 65\|535, and any application passing a larger value is +restricting its portability. A different type was considered, but +historical implementations, including those with a 16-bit +.BR int +type, consistently use either +.BR unsigned +or +.BR int . +.P +Application developers should be aware of possible interactions when +the same process uses both the +\fIalarm\fR() +and +\fIsleep\fR() +functions. +.SH RATIONALE +Many historical implementations (including Version 7 +and System V) allow an alarm to occur up to a second early. +Other implementations allow alarms up to half a second or one clock +tick early or do not +allow them to occur early at all. The latter is considered most +appropriate, since it gives the most predictable behavior, especially +since the signal can always be delayed for an indefinite amount of time +due to scheduling. Applications can thus choose the +.IR seconds +argument as the minimum amount of time they wish to have elapse before +the signal. +.P +The term ``realtime'' here and elsewhere (\c +\fIsleep\fR(), +\fItimes\fR()) +is intended to mean ``wall clock'' time as common English usage, and +has nothing to do with ``realtime operating systems''. It is in +contrast to \fIvirtual time\fP, which could be misinterpreted if just +\fItime\fP were used. +.P +In some implementations, including 4.3 BSD, very large values of the +.IR seconds +argument are silently rounded down to an implementation-specific maximum +value. This maximum is large enough (to the order of several months) +that the effect is not noticeable. +.P +There were two possible choices for alarm generation in multi-threaded +applications: generation for the calling thread or generation for the +process. The first option would not have been particularly useful +since the alarm state is maintained on a per-process basis and the +alarm that is established by the last invocation of +\fIalarm\fR() +is the only one that would be active. +.P +Furthermore, allowing generation of an asynchronous signal for a thread +would have introduced an exception to the overall signal model. This +requires a compelling reason in order to be justified. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIpause\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/alphasort.3p b/man-pages-posix-2013-a/man3p/alphasort.3p new file mode 100644 index 0000000..0865014 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/alphasort.3p @@ -0,0 +1,266 @@ +'\" et +.TH ALPHASORT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +alphasort, scandir +\(em scan a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int alphasort(const struct dirent **\fId1\fP, const struct dirent **\fId2\fP); +int scandir(const char *\fIdir\fP, struct dirent ***\fInamelist\fP, + int (*\fIsel\fP)(const struct dirent *), + int (*\fIcompar\fP)(const struct dirent **, const struct dirent **)); +.fi +.SH DESCRIPTION +The +\fIalphasort\fR() +function can be used as the comparison function for the +\fIscandir\fR() +function to sort the directory entries, +.IR d1 +and +.IR d2 , +into alphabetical order. Sorting happens as if by calling the +\fIstrcoll\fR() +function on the +.IR d_name +element of the +.BR dirent +structures passed as the two parameters. If the +\fIstrcoll\fR() +function fails, the return value of +\fIalphasort\fR() +is unspecified. +.P +The +\fIalphasort\fR() +function shall not change the setting of +.IR errno +if successful. Since no return value is reserved to indicate an error, +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIalphasort\fR(), +then check +.IR errno . +.P +The +\fIscandir\fR() +function shall scan the directory +.IR dir , +calling the function referenced by +.IR sel +on each directory entry. Entries for which the function referenced by +.IR sel +returns non-zero shall be stored in strings allocated as if by +a call to +\fImalloc\fR(), +and sorted as if by a call to +\fIqsort\fR() +with the comparison function +.IR compar , +except that +.IR compar +need not provide total ordering. The strings are collected in +array +.IR namelist +which shall be allocated as if by a call to +\fImalloc\fR(). +If +.IR sel +is a null pointer, all entries shall be selected. +If the comparison function +.IR compar +does not provide total ordering, the order in which the directory +entries are stored is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the +\fIalphasort\fR() +function shall return an integer greater than, equal to, or less than 0, +according to whether the name of the directory entry pointed to by +.IR d1 +is lexically greater than, equal to, or less than the directory pointed +to by +.IR d2 +when both are interpreted as appropriate to the current locale. There +is no return value reserved to indicate an error. +.P +Upon successful completion, the +\fIscandir\fR() +function shall return the number of entries in the array and a pointer +to the array through the parameter +.IR namelist . +Otherwise, the +\fIscandir\fR() +function shall return \(mi1. +.SH ERRORS +The +\fIscandir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for the component of the path prefix of +.IR dir +or read permission is denied for +.IR dir . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR dir +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR dir +does not name an existing directory or +.IR dir +is an empty string. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENOTDIR +A component of +.IR dir +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EOVERFLOW +One of the values to be returned or passed to a callback function cannot +be represented correctly. +.P +The +\fIscandir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR dir +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +An example to print the files in the current directory: +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +struct dirent **namelist; +int i,n; +.P + n = scandir(".", &namelist, 0, alphasort); + if (n < 0) + perror("scandir"); + else { + for (i = 0; i < n; i++) { + printf("%s\en", namelist[i]->d_name); + free(namelist[i]); + } + } + free(namelist); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +If +.IR dir +contains filenames that do not form character strings, or which contain +characters outside the domain of the collating sequence of the current +locale, the +\fIalphasort\fR() +function need not provide a total ordering. This condition is not possible +if all filenames within the directory consist only of characters from +the portable filename character set. +.P +The +\fIscandir\fR() +function may allocate dynamic storage during its operation. If +\fIscandir\fR() +is forcibly terminated, such as by +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +being executed by the function pointed to by +.IR sel +or +.IR compar , +or by an interrupt routine, +\fIscandir\fR() +does not have a chance to free that storage, so it remains permanently +allocated. A safe way to handle interrupts is to store the fact that +an interrupt has occurred, then wait until +\fIscandir\fR() +returns to act on the interrupt. +.P +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIscandir\fR(), +this is +.IR namelist +(including all of the individual strings in +.IR namelist ). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIqsort\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/asctime.3p b/man-pages-posix-2013-a/man3p/asctime.3p new file mode 100644 index 0000000..7ef2731 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/asctime.3p @@ -0,0 +1,197 @@ +'\" et +.TH ASCTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +asctime, +asctime_r +\(em convert date and time to a string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *asctime(const struct tm *\fItimeptr\fP); +char *asctime_r(const struct tm *restrict \fItm\fP, char *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +For +\fIasctime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIasctime\fR() +function shall convert the broken-down time in the structure pointed +to by +.IR timeptr +into a string in the form: +.sp +.RS 4 +.nf +\fB +Sun Sep 16 01:03:52 1973\en\e0 +.fi \fR +.P +.RE +.P +using the equivalent of the following algorithm: +.sp +.RS 4 +.nf +\fB +char *asctime(const struct tm *timeptr) +{ + static char wday_name[7][3] = { + "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" + }; + static char mon_name[12][3] = { + "Jan", "Feb", "Mar", "Apr", "May", "Jun", + "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" + }; + static char result[26]; +.P + sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\en", + wday_name[timeptr->tm_wday], + mon_name[timeptr->tm_mon], + timeptr->tm_mday, timeptr->tm_hour, + timeptr->tm_min, timeptr->tm_sec, + 1900 + timeptr->tm_year); + return result; +} +.fi \fR +.P +.RE +.P +However, the behavior is undefined if \fItimeptr\fR\->\fItm_wday\fR or +\fItimeptr\fR\->\fItm_mon\fR are not within the normal ranges as +defined in +.IR , +or if \fItimeptr\fR\->\fItm_year\fR exceeds +{INT_MAX}\(mi1990, +or if the above algorithm would attempt to generate more than 26 bytes +of output (including the terminating null). +.P +The +.BR tm +structure is defined in the +.IR +header. +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of type +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIasctime\fR() +function need not be thread-safe. +.P +The +\fIasctime_r\fR() +function shall convert the broken-down time in the structure pointed to +by +.IR tm +into a string (of the same form as that returned by +\fIasctime\fR(), +and with the same undefined behavior when input or output is out of +range) that is placed in the user-supplied buffer pointed to by +.IR buf +(which shall contain at least 26 bytes) and then return +.IR buf . +.SH "RETURN VALUE" +Upon successful completion, +\fIasctime\fR() +shall return a pointer to the string. +If the function is unsuccessful, it shall return NULL. +.P +Upon successful completion, +\fIasctime_r\fR() +shall return a pointer to a character string containing the date and +time. This string is pointed to by the argument +.IR buf . +If the function is unsuccessful, it shall return NULL. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are included only for compatibility with older +implementations. They have undefined behavior if the resulting string +would be too long, so the use of these functions should be +discouraged. On implementations that do not detect output string +length overflow, it is possible to overflow the output buffers in such +a way as to cause applications to fail, or possible system security +violations. Also, these functions do not support localized date and +time formats. To avoid these problems, applications should use +\fIstrftime\fR() +to generate strings from broken-down times. +.P +Values for the broken-down time structure can be obtained by calling +\fIgmtime\fR() +or +\fIlocaltime\fR(). +.P +The +\fIasctime_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.SH RATIONALE +The standard developers decided to mark the +\fIasctime\fR() +and +\fIasctime_r\fR() +functions obsolescent even though +\fIasctime\fR() +is in the ISO\ C standard due to the possibility of buffer overflow. The ISO\ C standard +also provides the +\fIstrftime\fR() +function which can be used to avoid these problems. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/asin.3p b/man-pages-posix-2013-a/man3p/asin.3p new file mode 100644 index 0000000..815fbbc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/asin.3p @@ -0,0 +1,156 @@ +'\" et +.TH ASIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +asin, +asinf, +asinl +\(em arc sine function +.SH SYNOPSIS +.LP +.nf +#include +.P +double asin(double \fIx\fP); +float asinf(float \fIx\fP); +long double asinl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the principal value of the arc sine of +their argument +.IR x . +The value of +.IR x +should be in the range [\(mi1,1]. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the arc sine +of +.IR x , +in the range [\(mi\(*p/2,\(*p/2] radians. +.P +For finite values of +.IR x +not in the range [\(mi1,1], a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIasin\fR(), +\fIasinf\fR(), +and +\fIasinl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is finite and is not in the range [\(mi1,1], +or is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/asinh.3p b/man-pages-posix-2013-a/man3p/asinh.3p new file mode 100644 index 0000000..c19fe56 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/asinh.3p @@ -0,0 +1,123 @@ +'\" et +.TH ASINH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +asinh, +asinhf, +asinhl +\(em inverse hyperbolic sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double asinh(double \fIx\fP); +float asinhf(float \fIx\fP); +long double asinhl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the inverse hyperbolic sine of their +argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the inverse +hyperbolic sine of their argument. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, or \(+-Inf, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIasinh\fR(), +\fIasinhf\fR(), +and +\fIasinhl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIsinh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/asinl.3p b/man-pages-posix-2013-a/man3p/asinl.3p new file mode 100644 index 0000000..7bdd691 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/asinl.3p @@ -0,0 +1,38 @@ +'\" et +.TH ASINL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +asinl +\(em arc sine function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double asinl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIasin\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/assert.3p b/man-pages-posix-2013-a/man3p/assert.3p new file mode 100644 index 0000000..5d3c7ba --- /dev/null +++ b/man-pages-posix-2013-a/man3p/assert.3p @@ -0,0 +1,92 @@ +'\" et +.TH ASSERT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +assert +\(em insert program diagnostics +.SH SYNOPSIS +.LP +.nf +#include +.P +void assert(scalar \fIexpression\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIassert\fR() +macro shall insert diagnostics into programs; it shall expand to a +.BR void +expression. When it is executed, if +.IR expression +(which shall have a +.BR scalar +type) is false (that is, compares equal to 0), +\fIassert\fR() +shall write information about the particular call that failed on +.IR stderr +and shall call +\fIabort\fR(). +.P +The information written about the call that failed shall include the +text of the argument, the name of the source file, the source file line +number, and the name of the enclosing function; the latter are, +respectively, the values of the preprocessing macros _\|_FILE_\|_ and +_\|_LINE_\|_ +and of the identifier _\|_func_\|_. +.P +Forcing a definition of the name NDEBUG, +either from the compiler command line or with the preprocessor control +statement +.BR #define +NDEBUG ahead of the +.BR #include +.IR +statement, shall stop assertions from being compiled into the program. +.SH "RETURN VALUE" +The +\fIassert\fR() +macro shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIabort\fR\^(\|)", +.IR "\fIstdin\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atan.3p b/man-pages-posix-2013-a/man3p/atan.3p new file mode 100644 index 0000000..5860afc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atan.3p @@ -0,0 +1,131 @@ +'\" et +.TH ATAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atan, +atanf, +atanl +\(em arc tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +double atan(double \fIx\fP); +float atanf(float \fIx\fP); +long double atanl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the principal value of the arc tangent of +their argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the arc +tangent of +.IR x +in the range [\(mi\(*p/2,\(*p/2] radians. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is \(+-Inf, \(+-\(*p/2 shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIatan\fR(), +\fIatanf\fR(), +and +\fIatanl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatan2\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fItan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atan2.3p b/man-pages-posix-2013-a/man3p/atan2.3p new file mode 100644 index 0000000..643a33c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atan2.3p @@ -0,0 +1,239 @@ +'\" et +.TH ATAN2 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atan2, +atan2f, +atan2l +\(em arc tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double atan2(double \fIy\fP, double \fIx\fP); +float atan2f(float \fIy\fP, float \fIx\fP); +long double atan2l(long double \fIy\fP, long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the principal value of the arc tangent of +.IR y /\c +.IR x , +using the signs of both arguments to determine the quadrant of the +return value. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the arc +tangent of +.IR y /\c +.IR x +in the range [\(mi\(*p,\(*p] radians. +.P +If +.IR y +is \(+-0 and +.IR x +is < 0, \(+-\(*p shall be returned. +.P +If +.IR y +is \(+-0 and +.IR x +is > 0, \(+-0 shall be returned. +.P +If +.IR y +is < 0 and +.IR x +is \(+-0, \(mi\(*p/2 shall be returned. +.P +If +.IR y +is > 0 and +.IR x +is \(+-0, \(*p/2 shall be returned. +.P +If +.IR x +is 0, a pole error shall not occur. +.P +If either +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If the correct value would cause underflow, a range error may occur, and +\fIatan\fR(), +\fIatan2f\fR(), +and +\fIatan2l\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.P +If the IEC 60559 Floating-Point option is supported, +.IR y /\c +.IR x +should be returned. +.P +If +.IR y +is \(+-0 and +.IR x +is \(mi0, \(+-\(*p shall be returned. +.P +If +.IR y +is \(+-0 and +.IR x +is +0, \(+-0 shall be returned. +.P +For finite values of \(+-\c +.IR y +> 0, if +.IR x +is \(miInf, \(+-\(*p shall be returned. +.P +For finite values of \(+-\c +.IR y +> 0, if +.IR x +is +Inf, \(+-0 shall be returned. +.P +For finite values of +.IR x , +if +.IR y +is \(+-Inf, \(+-\(*p/2 shall be returned. +.P +If +.IR y +is \(+-Inf and +.IR x +is \(miInf, \(+-3\(*p/4 shall be returned. +.P +If +.IR y +is \(+-Inf and +.IR x +is +Inf, \(+-\(*p/4 shall be returned. +.P +If both arguments are 0, a domain error shall not occur. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Converting Cartesian to Polar Coordinates System" +.P +The function below uses +\fIatan2\fR() +to convert a 2d vector expressed in cartesian coordinates +(\fIx\fR,\fIy\fR) to the polar coordinates (\fIrho\fR,\fItheta\fR). +There are other ways to compute the angle +.IR theta , +using +\fIasin\fR() +\fIacos\fR(), +or +\fIatan\fR(). +However, +\fIatan2\fR() +presents here two advantages: +.IP " *" 4 +The angle's quadrant is automatically determined. +.IP " *" 4 +The singular cases (0,\fIy\fR) are taken into account. +.P +Finally, this example uses +\fIhypot\fR() +rather than +\fIsqrt\fR() +since it is better for special cases; see +\fIhypot\fR() +for more information. +.sp +.RS 4 +.nf +\fB +#include +.P +void +cartesian_to_polar(const double x, const double y, + double *rho, double *theta + ) +{ + *rho = hypot (x,y); /* better than sqrt(x*x+y*y) */ + *theta = atan2 (y,x); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIacos\fR\^(\|)", +.IR "\fIasin\fR\^(\|)", +.IR "\fIatan\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIhypot\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsqrt\fR\^(\|)", +.IR "\fItan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atanf.3p b/man-pages-posix-2013-a/man3p/atanf.3p new file mode 100644 index 0000000..acfc87a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atanf.3p @@ -0,0 +1,38 @@ +'\" et +.TH ATANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atanf +\(em arc tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +float atanf(float \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIatan\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atanh.3p b/man-pages-posix-2013-a/man3p/atanh.3p new file mode 100644 index 0000000..6ecdf2f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atanh.3p @@ -0,0 +1,174 @@ +'\" et +.TH ATANH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atanh, +atanhf, +atanhl +\(em inverse hyperbolic tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double atanh(double \fIx\fP); +float atanhf(float \fIx\fP); +long double atanhl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the inverse hyperbolic tangent of their +argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the inverse +hyperbolic tangent of their argument. +.P +If +.IR x +is \(+-1, a pole error shall occur, and +\fIatanh\fR(), +\fIatanhf\fR(), +and +\fIatanhl\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively, with the same sign as the correct value of the function. +.P +For finite |\fIx\fR|>1, a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIatanh\fR(), +\fIatanhf\fR(), +and +\fIatanhl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is finite and not in the range [\(mi1,1], +or is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The +.IR x +argument is \(+-1. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.br +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fItanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atanl.3p b/man-pages-posix-2013-a/man3p/atanl.3p new file mode 100644 index 0000000..c68741c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atanl.3p @@ -0,0 +1,38 @@ +'\" et +.TH ATANL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atanl +\(em arc tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double atanl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIatan\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atexit.3p b/man-pages-posix-2013-a/man3p/atexit.3p new file mode 100644 index 0000000..144837c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atexit.3p @@ -0,0 +1,131 @@ +'\" et +.TH ATEXIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atexit +\(em register a function to run at process termination +.SH SYNOPSIS +.LP +.nf +#include +.P +int atexit(void (*\fIfunc\fP)(void)); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIatexit\fR() +function shall register the function pointed to by +.IR func , +to be called without arguments at normal program termination. At normal +program termination, all functions registered by the +\fIatexit\fR() +function shall be called, in the reverse order of their registration, +except that a function is called after any previously registered +functions that had already been called at the time it was registered. +Normal termination occurs either by a call to +\fIexit\fR() +or a return from +\fImain\fR(). +.P +At least 32 functions can be registered with +\fIatexit\fR(). +.P +After a successful call to any of the +.IR exec +functions, any functions previously registered by +\fIatexit\fR() +shall no longer be registered. +.SH "RETURN VALUE" +Upon successful completion, +\fIatexit\fR() +shall return 0; otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The functions registered by a call to +\fIatexit\fR() +must return to ensure that all registered functions are called. +.P +The application should call +\fIsysconf\fR() +to obtain the value of +{ATEXIT_MAX}, +the number of functions that can be registered. There is no way for an +application to tell how many functions have already been registered +with +\fIatexit\fR(). +.P +Since the behavior is undefined if the +\fIexit\fR() +function is called more than once, portable applications calling +\fIatexit\fR() +must ensure that the +\fIexit\fR() +function is not called at normal process termination when all functions +registered by the +\fIatexit\fR() +function are called. +.P +All functions registered by the +\fIatexit\fR() +function are called at normal process termination, which occurs by a +call to the +\fIexit\fR() +function or a return from +\fImain\fR() +or on the last thread termination, when the behavior is as if the +implementation called +\fIexit\fR() +with a zero argument at thread termination time. +.P +If, at normal process termination, a function registered by the +\fIatexit\fR() +function is called and a portable application needs to stop further +\fIexit\fR() +processing, it must call the +\fI_exit\fR() +function or the +\fI_Exit\fR() +function or one of the functions which cause abnormal process +termination. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atof.3p b/man-pages-posix-2013-a/man3p/atof.3p new file mode 100644 index 0000000..1440493 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atof.3p @@ -0,0 +1,85 @@ +'\" et +.TH ATOF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atof +\(em convert a string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +double atof(const char *\fIstr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The call +.IR atof ( str ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtod(\fIstr\fP,(char **)NULL), +.fi \fR +.P +.RE +.P +except that the handling of errors may differ. If the value cannot be +represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIatof\fR() +function shall return the converted value if the value can be +represented. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIatof\fR() +function is subsumed by +\fIstrtod\fR() +but is retained because it is used extensively in existing code. If the +number is not known to be in range, +\fIstrtod\fR() +should be used because +\fIatof\fR() +is not required to perform any error checking. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtod\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atoi.3p b/man-pages-posix-2013-a/man3p/atoi.3p new file mode 100644 index 0000000..5535ea6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atoi.3p @@ -0,0 +1,108 @@ +'\" et +.TH ATOI "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atoi +\(em convert a string to an integer +.SH SYNOPSIS +.LP +.nf +#include +.P +int atoi(const char *\fIstr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The call +.IR atoi ( str ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +(int) strtol(str, (char **)NULL, 10) +.fi \fR +.P +.RE +.P +except that the handling of errors may differ. If the value cannot be +represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIatoi\fR() +function shall return the converted value if the value can be +represented. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Converting an Argument" +.P +The following example checks for proper usage of the program. If there +is an argument and the decimal conversion of this argument (obtained +using +\fIatoi\fR()) +is greater than 0, then the program has a valid number of minutes to +wait for an event. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +int minutes_to_event; +\&... +if (argc < 2 || ((minutes_to_event = atoi (argv[1]))) <= 0) { + fprintf(stderr, "Usage: %s minutes\en", argv[0]); exit(1); +} +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIatoi\fR() +function is subsumed by +\fIstrtol\fR() +but is retained because it is used extensively in existing code. If the +number is not known to be in range, +\fIstrtol\fR() +should be used because +\fIatoi\fR() +is not required to perform any error checking. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/atol.3p b/man-pages-posix-2013-a/man3p/atol.3p new file mode 100644 index 0000000..65c7bb9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/atol.3p @@ -0,0 +1,97 @@ +'\" et +.TH ATOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +atol, +atoll +\(em convert a string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long atol(const char *\fIstr\fP); +long long atoll(const char *\fInptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The call +.IR atol ( str ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtol(str, (char **)NULL, 10) +.fi \fR +.P +.RE +.P +The call +.IR atoll ( nptr ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtoll(nptr, (char **)NULL, 10) +.fi \fR +.P +.RE +.P +except that the handling of errors may differ. If the value cannot be +represented, the behavior is undefined. +.SH "RETURN VALUE" +These functions shall return the converted value if the value can be +represented. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIatol\fR() +function is subsumed by +\fIstrtol\fR() +but is retained because it is used extensively in existing code. If the +number is not known to be in range, +\fIstrtol\fR() +should be used because +\fIatol\fR() +is not required to perform any error checking. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/basename.3p b/man-pages-posix-2013-a/man3p/basename.3p new file mode 100644 index 0000000..9d81c23 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/basename.3p @@ -0,0 +1,144 @@ +'\" et +.TH BASENAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +basename +\(em return the last component of a pathname +.SH SYNOPSIS +.LP +.nf +#include +.P +char *basename(char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIbasename\fR() +function shall take the pathname pointed to by +.IR path +and return a pointer to the final component of the pathname, deleting +any trailing +.BR '/' +characters. +.P +If the string pointed to by +.IR path +consists entirely of the +.BR '/' +character, +\fIbasename\fR() +shall return a pointer to the string +.BR \(dq/\(dq . +If the string pointed to by +.IR path +is exactly +.BR \(dq//\(dq , +it is implementation-defined whether +.BR '/' +or +.BR \(dq//\(dq +is returned. +.P +If +.IR path +is a null pointer or points to an empty string, +\fIbasename\fR() +shall return a pointer to the string +.BR \(dq.\(dq . +.P +The +\fIbasename\fR() +function may modify the string pointed to by +.IR path , +and may return a pointer to internal storage. The returned pointer might +be invalidated or the storage might be overwritten by a subsequent call to +\fIbasename\fR(). +.P +The +\fIbasename\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIbasename\fR() +function shall return a pointer to the final component of +.IR path . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using basename(\|)" +.P +The following program fragment returns a pointer to the value +.IR lib , +which is the base name of +.BR /usr/lib . +.sp +.RS 4 +.nf +\fB +#include +\&... +char *name = "/usr/lib"; +char *base; +.P +base = basename(name); +\&... +.fi \fR +.P +.RE +.SS "Sample Input and Output Strings for basename(\|)" +.P +In the following table, the input string is the value pointed to by +.IR path , +and the output string is the return value of the +\fIbasename\fR() +function. +.TS +center box tab(!); +cB | cB +lf5 | lf5. +Input String!Output String +_ +"/usr/lib"!"lib" +"/usr/"!"usr" +"/"!"/" +"///"!"/" +"//usr//lib//"!"lib" +.TE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdirname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIbasename\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/bind.3p b/man-pages-posix-2013-a/man3p/bind.3p new file mode 100644 index 0000000..8af6d9e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/bind.3p @@ -0,0 +1,290 @@ +'\" et +.TH BIND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +bind +\(em bind a name to a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +int bind(int \fIsocket\fP, const struct sockaddr *\fIaddress\fP, + socklen_t \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIbind\fR() +function shall assign a local socket address +.IR address +to a socket identified by descriptor +.IR socket +that has no local socket address assigned. Sockets created with the +\fIsocket\fR() +function are initially unnamed; they are identified only by their +address family. +.P +The +\fIbind\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the file descriptor of the socket to be bound. +.IP "\fIaddress\fR" 12 +Points to a +.BR sockaddr +structure containing the address to be bound to the socket. The length +and format of the address depend on the address family of the socket. +.IP "\fIaddress_len\fR" 12 +Specifies the length of the +.BR sockaddr +structure pointed to by the +.IR address +argument. +.P +The socket specified by +.IR socket +may require the process to have appropriate privileges to use the +\fIbind\fR() +function. +.P +If the address family of the socket is AF_UNIX and the pathname in +.IR address +names a symbolic link, +\fIbind\fR() +shall fail and set +.IR errno +to +.BR [EADDRINUSE] . +.P +If the socket address cannot be assigned immediately and O_NONBLOCK is +set for the file descriptor for the socket, +\fIbind\fR() +shall fail and set +.IR errno +to +.BR [EINPROGRESS] , +but the assignment request shall not be aborted, and the assignment +shall be completed asynchronously. Subsequent calls to +\fIbind\fR() +for the same socket, before the assignment is completed, shall fail +and set +.IR errno +to +.BR [EALREADY] . +.P +When the assignment has been performed asynchronously, +\fIpselect\fR(), +\fIselect\fR(), +and +\fIpoll\fR() +shall indicate that the file descriptor for the socket is ready for +reading and writing. +.SH "RETURN VALUE" +Upon successful completion, +\fIbind\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIbind\fR() +function shall fail if: +.TP +.BR EADDRINUSE +The specified address is already in use. +.TP +.BR EADDRNOTAVAIL +.br +The specified address is not available from the local machine. +.TP +.BR EAFNOSUPPORT +.br +The specified address is not a valid address for the address family of +the specified socket. +.TP +.BR EALREADY +An assignment request is already in progress for the specified socket. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EINPROGRESS +O_NONBLOCK is set for the file descriptor for the socket and the +assignment cannot be immediately performed; the assignment shall be +performed asynchronously. +.TP +.BR EINVAL +The socket is already bound to an address, and the protocol does not +support binding to a new address; or the socket has been shut down. +.TP +.BR ENOBUFS +Insufficient resources were available to complete the call. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The socket type of the specified socket does not support binding to an +address. +.P +If the address family of the socket is AF_UNIX, then +\fIbind\fR() +shall fail if: +.TP +.BR EACCES +A component of the path prefix denies search permission, or the +requested name requires writing in a directory with a mode that denies +write permission. +.TP +.BR EDESTADDRREQ " or " EISDIR +.br +The +.IR address +argument is a null pointer. +.TP +.BR EIO +An I/O error occurred. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in +.IR address . +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix of the pathname in +.IR address +does not name an existing file or the pathname is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The pathname in +.IR address +contains at least one non-\c + +character and ends with one or more trailing + +characters. If the pathname names an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOTDIR +A component of the path prefix of the pathname in +.IR address +names an existing file that is neither a directory nor a symbolic link +to a directory, or the pathname in +.IR address +contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The name would reside on a read-only file system. +.P +The +\fIbind\fR() +function may fail if: +.TP +.BR EACCES +The specified address is protected and the current user does not have +permission to bind to it. +.TP +.BR EINVAL +The +.IR address_len +argument is not a valid length for the address family. +.TP +.BR EISCONN +The socket is already connected. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the pathname in +.IR address . +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following code segment shows how to create a socket and +bind it to a name in the AF_UNIX domain. +.sp +.RS 4 +.nf +\fB +#define MY_SOCK_PATH "/somepath" +.P +int sfd; +struct sockaddr_un my_addr; +.P +sfd = socket(AF_UNIX, SOCK_STREAM, 0); +if (sfd == \(mi1) + /* Handle error */; +.P +memset(&my_addr, '\e0', sizeof(struct sockaddr_un)); + /* Clear structure */ +my_addr.sun_family = AF_UNIX; +strncpy(my_addr.sun_path, MY_SOCK_PATH, sizeof(my_addr.sun_path) \(mi1); +.P +if (bind(sfd, (struct sockaddr *) &my_addr, + sizeof(struct sockaddr_un)) == \(mi1) + /* Handle error */; +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +An application program can retrieve the assigned socket name with the +\fIgetsockname\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIlisten\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/bsearch.3p b/man-pages-posix-2013-a/man3p/bsearch.3p new file mode 100644 index 0000000..bff1b94 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/bsearch.3p @@ -0,0 +1,193 @@ +'\" et +.TH BSEARCH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +bsearch +\(em binary search a sorted table +.SH SYNOPSIS +.LP +.nf +#include +.P +void *bsearch(const void *\fIkey\fP, const void *\fIbase\fP, size_t \fInel\fP, + size_t \fIwidth\fP, int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIbsearch\fR() +function shall search an array of +.IR nel +objects, the initial element of which is pointed to by +.IR base , +for an element that matches the object pointed to by +.IR key . +The size of each element in the array is specified by +.IR width . +If the +.IR nel +argument has the value zero, the comparison function pointed to by +.IR compar +shall not be called and no match shall be found. +.P +The comparison function pointed to by +.IR compar +shall be called with two arguments that point to the +.IR key +object and to an array element, in that order. +.P +The application shall ensure that the comparison function pointed to by +.IR compar +does not alter the contents of the array. The implementation may +reorder elements of the array between calls to the comparison function, +but shall not alter the contents of any individual element. +.P +The implementation shall ensure that the first argument is always a +pointer to the key. +.P +When the same objects (consisting of width bytes, irrespective of their +current positions in the array) are passed more than once to the +comparison function, the results shall be consistent with one another. +That is, the same object shall always compare the same way with the +key. +.P +The application shall ensure that the function returns an integer less +than, equal to, or greater than 0 if the +.IR key +object is considered, respectively, to be less than, to match, or to be +greater than the array element. The application shall ensure that the +array consists of all the elements that compare less than, all the +elements that compare equal to, and all the elements that compare +greater than the +.IR key +object, in that order. +.SH "RETURN VALUE" +The +\fIbsearch\fR() +function shall return a pointer to a matching member of the array, or a +null pointer if no match is found. If two or more members compare +equal, which member is returned is unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The example below searches a table containing pointers to nodes +consisting of a string and its length. The table is ordered +alphabetically on the string in the node pointed to by each entry. +.P +The code fragment below reads in strings and either finds the +corresponding node and prints out the string and its length, or prints +an error message. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +#define\ TABSIZE 1000 +.P +struct node { /* These are stored in the table. */ + char *string; + int length; +}; +struct node table[TABSIZE]; /* Table to be searched. */ + . + . + . +{ + struct node *node_ptr, node; + /* Routine to compare 2 nodes. */ + int node_compare(const void *, const void *); + . + . + . + while (scanf("%ms", &node.string) != EOF) { + node_ptr = (struct node *)bsearch((void *)(&node), + (void *)table, TABSIZE, + sizeof(struct node), node_compare); + if (node_ptr != NULL) { + (void)printf("string = %20s, length = %d\en", + node_ptr->string, node_ptr->length); + } else { + (void)printf("not found: %s\en", node.string); + } + free(node.string); + } +} +/* + This routine compares two nodes based on an + alphabetical ordering of the string field. +*/ +int +node_compare(const void *node1, const void *node2) +{ + return strcoll(((const struct node *)node1)->string, + ((const struct node *)node2)->string); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The pointers to the key and the element at the base of the table should +be of type pointer-to-element. +.P +The comparison function need not compare every byte, so arbitrary data +may be contained in the elements in addition to the values being +compared. +.P +In practice, the array is usually sorted according to the comparison +function. +.SH RATIONALE +The requirement that the second argument (hereafter referred to as +.IR p ) +to the comparison function is a pointer to an element of the array +implies that for every call all of the following expressions are +non-zero: +.sp +.RS 4 +.nf +\fB +((char *)p \(mi (char *(base) % width == 0 +(char *)p >= (char *)base +(char *)p < (char *)base + nel * width +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIhcreate\fR\^(\|)", +.IR "\fIlsearch\fR\^(\|)", +.IR "\fIqsort\fR\^(\|)", +.IR "\fItdelete\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/btowc.3p b/man-pages-posix-2013-a/man3p/btowc.3p new file mode 100644 index 0000000..8065db0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/btowc.3p @@ -0,0 +1,79 @@ +'\" et +.TH BTOWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +btowc +\(em single byte to wide character conversion +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t btowc(int \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIbtowc\fR() +function shall determine whether +.IR c +constitutes a valid (one-byte) character in the initial shift state. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +.SH "RETURN VALUE" +The +\fIbtowc\fR() +function shall return WEOF if +.IR c +has the value EOF or if +.BR "(unsigned char)" +.IR c +does not constitute a valid (one-byte) character in the initial shift +state. Otherwise, it shall return the wide-character representation of +that character. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwctob\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cabs.3p b/man-pages-posix-2013-a/man3p/cabs.3p new file mode 100644 index 0000000..1ee6a6d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cabs.3p @@ -0,0 +1,64 @@ +'\" et +.TH CABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cabs, +cabsf, +cabsl +\(em return a complex absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +double cabs(double complex \fIz\fP); +float cabsf(float complex \fIz\fP); +long double cabsl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex absolute value (also called +norm, modulus, or magnitude) of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex absolute value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cacos.3p b/man-pages-posix-2013-a/man3p/cacos.3p new file mode 100644 index 0000000..3a7f79f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cacos.3p @@ -0,0 +1,69 @@ +'\" et +.TH CACOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cacos, +cacosf, +cacosl +\(em complex arc cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cacos(double complex \fIz\fP); +float complex cacosf(float complex \fIz\fP); +long double complex cacosl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc cosine of +.IR z , +with branch cuts outside the interval [\(mi1,\ +1] along the real +axis. +.SH "RETURN VALUE" +These functions shall return the complex arc cosine value, in the range +of a strip mathematically unbounded along the imaginary axis and in the +interval [0,\ \(*p] along the real axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIccos\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cacosh.3p b/man-pages-posix-2013-a/man3p/cacosh.3p new file mode 100644 index 0000000..ef3866f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cacosh.3p @@ -0,0 +1,69 @@ +'\" et +.TH CACOSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cacosh, +cacoshf, +cacoshl +\(em complex arc hyperbolic cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cacosh(double complex \fIz\fP); +float complex cacoshf(float complex \fIz\fP); +long double complex cacoshl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc hyperbolic cosine of +.IR z , +with a branch cut at values less than 1 along the real axis. +.SH "RETURN VALUE" +These functions shall return the complex arc hyperbolic cosine value, +in the range of a half-strip of non-negative values along the real axis +and in the interval [\(mi\fIi\fR\(*p,\ +\fIi\fR\(*p] along the +imaginary axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIccosh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cacosl.3p b/man-pages-posix-2013-a/man3p/cacosl.3p new file mode 100644 index 0000000..281ccc2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cacosl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CACOSL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cacosl +\(em complex arc cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex cacosl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcacos\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/calloc.3p b/man-pages-posix-2013-a/man3p/calloc.3p new file mode 100644 index 0000000..aa27402 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/calloc.3p @@ -0,0 +1,104 @@ +'\" et +.TH CALLOC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +calloc +\(em a memory allocator +.SH SYNOPSIS +.LP +.nf +#include +.P +void *calloc(size_t \fInelem\fP, size_t \fIelsize\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIcalloc\fR() +function shall allocate unused space for an array of +.IR nelem +elements each of whose size in bytes is +.IR elsize . +The space shall be initialized to all bits 0. +.P +The order and contiguity of storage allocated by successive calls to +\fIcalloc\fR() +is unspecified. The pointer returned if the allocation succeeds shall +be suitably aligned so that it may be assigned to a pointer to any type +of object and then used to access such an object or an array of such +objects in the space allocated (until the space is explicitly freed or +reallocated). Each such allocation shall yield a pointer to an object +disjoint from any other object. The pointer returned shall point to the +start (lowest byte address) of the allocated space. If the space cannot +be allocated, a null pointer shall be returned. If the size of the +space requested is 0, the behavior is implementation-defined: the value +returned shall be either a null pointer or a unique pointer. +.SH "RETURN VALUE" +Upon successful completion with both +.IR nelem +and +.IR elsize +non-zero, +\fIcalloc\fR() +shall return a pointer to the allocated space. If either +.IR nelem +or +.IR elsize +is 0, then either a null pointer or a unique pointer value that can be +successfully passed to +\fIfree\fR() +shall be returned. Otherwise, it shall return a null pointer +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIcalloc\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +There is now no requirement for the implementation to support the +inclusion of +.IR . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/carg.3p b/man-pages-posix-2013-a/man3p/carg.3p new file mode 100644 index 0000000..0fbe9dc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/carg.3p @@ -0,0 +1,69 @@ +'\" et +.TH CARG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +carg, +cargf, +cargl +\(em complex argument functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double carg(double complex \fIz\fP); +float cargf(float complex \fIz\fP); +long double cargl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the argument (also called phase angle) of +.IR z , +with a branch cut along the negative real axis. +.SH "RETURN VALUE" +These functions shall return the value of the argument in the interval +[\(mi\(*p,\ +\(*p]. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcimag\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/casin.3p b/man-pages-posix-2013-a/man3p/casin.3p new file mode 100644 index 0000000..d5c35b8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/casin.3p @@ -0,0 +1,69 @@ +'\" et +.TH CASIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +casin, +casinf, +casinl +\(em complex arc sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex casin(double complex \fIz\fP); +float complex casinf(float complex \fIz\fP); +long double complex casinl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc sine of +.IR z , +with branch cuts outside the interval [\(mi1,\ +1] along the real +axis. +.SH "RETURN VALUE" +These functions shall return the complex arc sine value, in the range +of a strip mathematically unbounded along the imaginary axis and in the +interval [\(mi\(*p/2,\ +\(*p/2] along the real axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcsin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/casinh.3p b/man-pages-posix-2013-a/man3p/casinh.3p new file mode 100644 index 0000000..e3cd49b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/casinh.3p @@ -0,0 +1,70 @@ +'\" et +.TH CASINH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +casinh, +casinhf, +casinhl +\(em complex arc hyperbolic sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex casinh(double complex \fIz\fP); +float complex casinhf(float complex \fIz\fP); +long double complex casinhl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc hyperbolic sine of +.IR z , +with branch cuts outside the interval [\(mi\fIi\fR,\ +\fIi\fR] along +the imaginary axis. +.SH "RETURN VALUE" +These functions shall return the complex arc hyperbolic sine value, in +the range of a strip mathematically unbounded along the real axis and +in the interval [\(mi\fIi\fR\(*p/2,\ +\fIi\fR\(*p/2] along the +imaginary axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcsinh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/casinl.3p b/man-pages-posix-2013-a/man3p/casinl.3p new file mode 100644 index 0000000..6305a23 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/casinl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CASINL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +casinl +\(em complex arc sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex casinl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcasin\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/catan.3p b/man-pages-posix-2013-a/man3p/catan.3p new file mode 100644 index 0000000..bb01b0a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/catan.3p @@ -0,0 +1,69 @@ +'\" et +.TH CATAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +catan, +catanf, +catanl +\(em complex arc tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex catan(double complex \fIz\fP); +float complex catanf(float complex \fIz\fP); +long double complex catanl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc tangent of +.IR z , +with branch cuts outside the interval [\(mi\fIi\fR,\ +\fIi\fR] along +the imaginary axis. +.SH "RETURN VALUE" +These functions shall return the complex arc tangent value, in the +range of a strip mathematically unbounded along the imaginary axis and +in the interval [\(mi\(*p/2,\ +\(*p/2] along the real axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIctan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/catanh.3p b/man-pages-posix-2013-a/man3p/catanh.3p new file mode 100644 index 0000000..5135f5c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/catanh.3p @@ -0,0 +1,70 @@ +'\" et +.TH CATANH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +catanh, +catanhf, +catanhl +\(em complex arc hyperbolic tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex catanh(double complex \fIz\fP); +float complex catanhf(float complex \fIz\fP); +long double complex catanhl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc hyperbolic tangent of +.IR z , +with branch cuts outside the interval [\(mi1,\ +1] along the real +axis. +.SH "RETURN VALUE" +These functions shall return the complex arc hyperbolic tangent value, +in the range of a strip mathematically unbounded along the real axis +and in the interval [\(mi\fIi\fR\(*p/2,\ +\fIi\fR\(*p/2] along the +imaginary axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIctanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/catanl.3p b/man-pages-posix-2013-a/man3p/catanl.3p new file mode 100644 index 0000000..b0bfce8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/catanl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CATANL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +catanl +\(em complex arc tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex catanl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcatan\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/catclose.3p b/man-pages-posix-2013-a/man3p/catclose.3p new file mode 100644 index 0000000..45aeb20 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/catclose.3p @@ -0,0 +1,77 @@ +'\" et +.TH CATCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +catclose +\(em close a message catalog descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int catclose(nl_catd \fIcatd\fP); +.fi +.SH DESCRIPTION +The +\fIcatclose\fR() +function shall close the message catalog identified by +.IR catd . +If a file descriptor is used to implement the type +.BR nl_catd , +that file descriptor shall be closed. +.SH "RETURN VALUE" +Upon successful completion, +\fIcatclose\fR() +shall return 0; otherwise, \(mi1 shall be returned, and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIcatclose\fR() +function may fail if: +.TP +.BR EBADF +The catalog descriptor is not valid. +.TP +.BR EINTR +The +\fIcatclose\fR() +function was interrupted by a signal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatgets\fR\^(\|)", +.IR "\fIcatopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/catgets.3p b/man-pages-posix-2013-a/man3p/catgets.3p new file mode 100644 index 0000000..9a136b0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/catgets.3p @@ -0,0 +1,125 @@ +'\" et +.TH CATGETS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +catgets +\(em read a program message +.SH SYNOPSIS +.LP +.nf +#include +.P +char *catgets(nl_catd \fIcatd\fP, int \fIset_id\fP, int \fImsg_id\fP, const char *\fIs\fP); +.fi +.SH DESCRIPTION +The +\fIcatgets\fR() +function shall attempt to read message +.IR msg_id , +in set +.IR set_id , +from the message catalog identified by +.IR catd . +The +.IR catd +argument is a message catalog descriptor returned from an earlier call +to +\fIcatopen\fR(). +The results are undefined if +.IR catd +is not a value returned by +\fIcatopen\fR() +for a message catalog still open in the process. The +.IR s +argument points to a default message string which shall be returned by +\fIcatgets\fR() +if it cannot retrieve the identified message. +.P +The +\fIcatgets\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If the identified message is retrieved successfully, +\fIcatgets\fR() +shall return a pointer to an internal buffer area containing the +null-terminated message string. If the call is unsuccessful for any +reason, +.IR s +shall be returned and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIcatgets\fR() +function shall fail if: +.TP +.BR EINTR +The read operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR ENOMSG +The message identified by +.IR set_id +and +.IR msg_id +is not in the message catalog. +.P +The +\fIcatgets\fR() +function may fail if: +.TP +.BR EBADF +The +.IR catd +argument is not a valid message catalog descriptor open for reading. +.TP +.BR EBADMSG +The message identified by +.IR set_id +and +.IR msg_id +in the specified message catalog did not satisfy implementation-defined +security criteria. +.TP +.BR EINVAL +The message catalog identified by +.IR catd +is corrupted. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatclose\fR\^(\|)", +.IR "\fIcatopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/catopen.3p b/man-pages-posix-2013-a/man3p/catopen.3p new file mode 100644 index 0000000..a53908f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/catopen.3p @@ -0,0 +1,195 @@ +'\" et +.TH CATOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +catopen +\(em open a message catalog +.SH SYNOPSIS +.LP +.nf +#include +.P +nl_catd catopen(const char *\fIname\fP, int \fIoflag\fP); +.fi +.SH DESCRIPTION +The +\fIcatopen\fR() +function shall open a message catalog and return a message catalog +descriptor. The +.IR name +argument specifies the name of the message catalog to be opened. If +.IR name +contains a +.BR '/' , +then +.IR name +specifies a complete name for the message catalog. Otherwise, the +environment variable +.IR NLSPATH +is used with +.IR name +substituted for the +.BR %N +conversion specification (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables"). +If +.IR NLSPATH +exists in the environment when the process starts, then if the process +has appropriate privileges, the behavior of +\fIcatopen\fR() +is undefined. If +.IR NLSPATH +does not exist in the environment, or if a message catalog cannot be +found in any of the components specified by +.IR NLSPATH , +then an implementation-defined default path shall be used. This default +may be affected by the setting of +.IR LC_MESSAGES +if the value of +.IR oflag +is NL_CAT_LOCALE, or the +.IR LANG +environment variable if +.IR oflag +is 0. +.P +A message catalog descriptor shall remain valid in a process until that +process closes it, or a successful call to one of the +.IR exec +functions. A change in the setting of the +.IR LC_MESSAGES +category may invalidate existing open catalogs. +.P +If a file descriptor is used to implement message catalog descriptors, +the FD_CLOEXEC flag shall be set; see +.IR . +.P +If the value of the +.IR oflag +argument is 0, the +.IR LANG +environment variable is used to locate the catalog without regard to +the +.IR LC_MESSAGES +category. If the +.IR oflag +argument is NL_CAT_LOCALE, the +.IR LC_MESSAGES +category is used to locate the message catalog (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables"). +.SH "RETURN VALUE" +Upon successful completion, +\fIcatopen\fR() +shall return a message catalog descriptor for use on subsequent calls to +\fIcatgets\fR() +and +\fIcatclose\fR(). +Otherwise, +\fIcatopen\fR() +shall return (\c +.BR nl_catd ) +\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIcatopen\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for the component of the path prefix of the +message catalog or read permission is denied for the message catalog. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.TP +.BR ENOENT +The message catalog does not exist or the +.IR name +argument points to an empty string. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENOTDIR +A component of the path prefix of the message catalog names an existing +file that is neither a directory nor a symbolic link to a directory, +or the pathname of the message catalog contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Some implementations of +\fIcatopen\fR() +use +\fImalloc\fR() +to allocate space for internal buffer areas. The +\fIcatopen\fR() +function may fail if there is insufficient storage space available to +accommodate these buffers. +.P +Conforming applications must assume that message catalog descriptors are +not valid after a call to one of the +.IR exec +functions. +.P +Application developers should be aware that guidelines for the location +of message catalogs have not yet been developed. Therefore they should +take care to avoid conflicting with catalogs used by other applications +and the standard utilities. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatclose\fR\^(\|)", +.IR "\fIcatgets\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP", +.IR "\fB\fP", +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cbrt.3p b/man-pages-posix-2013-a/man3p/cbrt.3p new file mode 100644 index 0000000..813f263 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cbrt.3p @@ -0,0 +1,81 @@ +'\" et +.TH CBRT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cbrt, +cbrtf, +cbrtl +\(em cube root functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double cbrt(double \fIx\fP); +float cbrtf(float \fIx\fP); +long double cbrtl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the real cube root of their argument +.IR x . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the cube root +of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +For some applications, a true cube root function, which returns +negative results for negative arguments, is more appropriate than +.IR pow (\c +.IR x , +1.0/3.0), which returns a NaN for +.IR x +less than 0. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ccos.3p b/man-pages-posix-2013-a/man3p/ccos.3p new file mode 100644 index 0000000..727ed37 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ccos.3p @@ -0,0 +1,65 @@ +'\" et +.TH CCOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ccos, +ccosf, +ccosl +\(em complex cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex ccos(double complex \fIz\fP); +float complex ccosf(float complex \fIz\fP); +long double complex ccosl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex cosine of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex cosine value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcacos\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ccosh.3p b/man-pages-posix-2013-a/man3p/ccosh.3p new file mode 100644 index 0000000..d3f3cb2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ccosh.3p @@ -0,0 +1,65 @@ +'\" et +.TH CCOSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ccosh, +ccoshf, +ccoshl +\(em complex hyperbolic cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex ccosh(double complex \fIz\fP); +float complex ccoshf(float complex \fIz\fP); +long double complex ccoshl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex hyperbolic cosine of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex hyperbolic cosine value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcacosh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ccosl.3p b/man-pages-posix-2013-a/man3p/ccosl.3p new file mode 100644 index 0000000..bebfe75 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ccosl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CCOSL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ccosl +\(em complex cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex ccosl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIccos\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ceil.3p b/man-pages-posix-2013-a/man3p/ceil.3p new file mode 100644 index 0000000..7ae4304 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ceil.3p @@ -0,0 +1,101 @@ +'\" et +.TH CEIL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ceil, +ceilf, +ceill +\(em ceiling value function +.SH SYNOPSIS +.LP +.nf +#include +.P +double ceil(double \fIx\fP); +float ceilf(float \fIx\fP); +long double ceill(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the smallest integral value not less than +.IR x . +.SH "RETURN VALUE" +The result shall have the same sign as +.IR x . +.P +Upon successful completion, +\fIceil\fR(), +\fIceilf\fR(), +and +\fIceill\fR() +shall return the smallest integral value not less than +.IR x , +expressed as a type +.BR double , +.BR float , +or +.BR "long double" , +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer +type to avoid the undefined results of an integer overflow. +.P +These functions may raise the inexact floating-point exception if the +result differs in value from the argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfloor\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cexp.3p b/man-pages-posix-2013-a/man3p/cexp.3p new file mode 100644 index 0000000..18a10f8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cexp.3p @@ -0,0 +1,67 @@ +'\" et +.TH CEXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cexp, +cexpf, +cexpl +\(em complex exponential functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cexp(double complex \fIz\fP); +float complex cexpf(float complex \fIz\fP); +long double complex cexpl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex exponent of +.IR z , +defined as \fIe\s-3\uz\d\s+3\fR. +.SH "RETURN VALUE" +These functions shall return the complex exponential value of +.IR z . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cfgetispeed.3p b/man-pages-posix-2013-a/man3p/cfgetispeed.3p new file mode 100644 index 0000000..20b1192 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cfgetispeed.3p @@ -0,0 +1,126 @@ +'\" et +.TH CFGETISPEED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cfgetispeed +\(em get input baud rate +.SH SYNOPSIS +.LP +.nf +#include +.P +speed_t cfgetispeed(const struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fIcfgetispeed\fR() +function shall extract the input baud rate from the +.BR termios +structure to which the +.IR termios_p +argument points. +.P +This function shall return exactly the value in the +.BR termios +data structure, without interpretation. +.SH "RETURN VALUE" +Upon successful completion, +\fIcfgetispeed\fR() +shall return a value of type +.BR speed_t +representing the input baud rate. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The term ``baud'' is used historically here, but is not technically +correct. This is properly ``bits per second'', which may not be the +same as baud. However, the term is used because of the historical +usage and understanding. +.P +The +\fIcfgetospeed\fR(), +\fIcfgetispeed\fR(), +\fIcfsetospeed\fR(), +and +\fIcfsetispeed\fR() +functions do not take arguments as numbers, but rather as symbolic +names. There are two reasons for this: +.IP " 1." 4 +Historically, numbers were not used because of the way the rate was +stored in the data structure. This is retained even though a +function is now used. +.IP " 2." 4 +More importantly, only a limited set of possible rates is at all +portable, and this constrains the application to that set. +.P +There is nothing to prevent an implementation accepting as an extension +a number (such as 126), and since the encoding of the Bxxx symbols is +not specified, this can be done to avoid introducing ambiguity. +.P +Setting the input baud rate to zero was a mechanism to allow for split +baud rates. Clarifications in this volume of POSIX.1\(hy2008 have made it possible to determine +whether split rates are supported and to support them without having to +treat zero as a special case. Since this functionality is also +confusing, it has been declared obsolescent. +The 0 argument referred to is the literal constant 0, not the symbolic +constant B0. This volume of POSIX.1\(hy2008 does not preclude B0 from being defined as the value +0; in fact, implementations would likely benefit from the two being +equivalent. This volume of POSIX.1\(hy2008 does not fully specify whether the previous +\fIcfsetispeed\fR() +value is retained after a +\fItcgetattr\fR() +as the actual value or as zero. Therefore, conforming applications should +always set both the input speed and output speed when setting either. +.P +In historical implementations, the baud rate information is +traditionally kept in +.BR c_cflag . +Applications should be written to presume that this might be the case +(and thus not blindly copy +.BR c_cflag ), +but not to rely on it in case it is in some other field of the +structure. Setting the +.BR c_cflag +field absolutely after setting a baud rate is a non-portable action +because of this. In general, the unused parts of the flag fields might +be used by the implementation and should not be blindly copied from the +descriptions of one terminal device to another. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcfgetospeed\fR\^(\|)", +.IR "\fIcfsetispeed\fR\^(\|)", +.IR "\fIcfsetospeed\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cfgetospeed.3p b/man-pages-posix-2013-a/man3p/cfgetospeed.3p new file mode 100644 index 0000000..0c53117 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cfgetospeed.3p @@ -0,0 +1,75 @@ +'\" et +.TH CFGETOSPEED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cfgetospeed +\(em get output baud rate +.SH SYNOPSIS +.LP +.nf +#include +.P +speed_t cfgetospeed(const struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fIcfgetospeed\fR() +function shall extract the output baud rate from the +.BR termios +structure to which the +.IR termios_p +argument points. +.P +This function shall return exactly the value in the +.BR termios +data structure, without interpretation. +.SH "RETURN VALUE" +Upon successful completion, +\fIcfgetospeed\fR() +shall return a value of type +.BR speed_t +representing the output baud rate. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIcfgetispeed\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fIcfsetispeed\fR\^(\|)", +.IR "\fIcfsetospeed\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cfsetispeed.3p b/man-pages-posix-2013-a/man3p/cfsetispeed.3p new file mode 100644 index 0000000..e028f07 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cfsetispeed.3p @@ -0,0 +1,94 @@ +'\" et +.TH CFSETISPEED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cfsetispeed +\(em set input baud rate +.SH SYNOPSIS +.LP +.nf +#include +.P +int cfsetispeed(struct termios *\fItermios_p\fP, speed_t \fIspeed\fP); +.fi +.SH DESCRIPTION +The +\fIcfsetispeed\fR() +function shall set the input baud rate stored in the structure pointed +to by +.IR termios_p +to +.IR speed. +.P +There shall be no effect on the baud rates set in the hardware until a +subsequent successful call to +\fItcsetattr\fR() +with the same +.BR termios +structure. Similarly, errors resulting from attempts to set baud rates +not supported by the terminal device need not be detected until the +\fItcsetattr\fR() +function is called. +.SH "RETURN VALUE" +Upon successful completion, +\fIcfsetispeed\fR() +shall return 0; otherwise, \(mi1 shall be returned, and +.IR errno +may be set to indicate the error. +.SH ERRORS +The +\fIcfsetispeed\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR speed +value is not a valid baud rate. +.TP +.BR EINVAL +The value of +.IR speed +is outside the range of possible speed values as specified in +.IR . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIcfgetispeed\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fIcfgetospeed\fR\^(\|)", +.IR "\fIcfsetospeed\fR\^(\|)", +.IR "\fItcsetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cfsetospeed.3p b/man-pages-posix-2013-a/man3p/cfsetospeed.3p new file mode 100644 index 0000000..be606b0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cfsetospeed.3p @@ -0,0 +1,94 @@ +'\" et +.TH CFSETOSPEED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cfsetospeed +\(em set output baud rate +.SH SYNOPSIS +.LP +.nf +#include +.P +int cfsetospeed(struct termios *\fItermios_p\fP, speed_t \fIspeed\fP); +.fi +.SH DESCRIPTION +The +\fIcfsetospeed\fR() +function shall set the output baud rate stored in the structure pointed +to by +.IR termios_p +to +.IR speed . +.P +There shall be no effect on the baud rates set in the hardware until a +subsequent successful call to +\fItcsetattr\fR() +with the same +.BR termios +structure. Similarly, errors resulting from attempts to set baud rates +not supported by the terminal device need not be detected until the +\fItcsetattr\fR() +function is called. +.SH "RETURN VALUE" +Upon successful completion, +\fIcfsetospeed\fR() +shall return 0; otherwise, it shall return \(mi1 and +.IR errno +may be set to indicate the error. +.SH ERRORS +The +\fIcfsetospeed\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR speed +value is not a valid baud rate. +.TP +.BR EINVAL +The value of +.IR speed +is outside the range of possible speed values as specified in +.IR . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIcfgetispeed\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fIcfgetospeed\fR\^(\|)", +.IR "\fIcfsetispeed\fR\^(\|)", +.IR "\fItcsetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/chdir.3p b/man-pages-posix-2013-a/man3p/chdir.3p new file mode 100644 index 0000000..a09c219 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/chdir.3p @@ -0,0 +1,131 @@ +'\" et +.TH CHDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +chdir +\(em change working directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int chdir(const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIchdir\fR() +function shall cause the directory named by the pathname pointed to +by the +.IR path +argument to become the current working directory; that is, the starting +point for path searches for pathnames not beginning with +.BR '/' . +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 shall +be returned, the current working directory shall remain unchanged, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIchdir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for any component of the pathname. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing directory or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the pathname names an existing file that is neither +a directory nor a symbolic link to a directory. +.P +The +\fIchdir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Current Working Directory" +.P +The following example makes the value pointed to by +.BR directory , +.BR /tmp , +the current working directory. +.sp +.RS 4 +.nf +\fB +#include +\&... +char *directory = "/tmp"; +int ret; +.P +ret = chdir (directory); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIchdir\fR() +function only affects the working directory of the current process. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetcwd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/chmod.3p b/man-pages-posix-2013-a/man3p/chmod.3p new file mode 100644 index 0000000..181c01d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/chmod.3p @@ -0,0 +1,365 @@ +'\" et +.TH CHMOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +chmod, fchmodat +\(em change mode of a file relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int chmod(const char *\fIpath\fP, mode_t \fImode\fP); +int fchmodat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIchmod\fR() +function shall change S_ISUID, S_ISGID, +S_ISVTX, +and the file permission bits of the file named by the pathname pointed +to by the +.IR path +argument to the corresponding bits in the +.IR mode +argument. The application shall ensure that the effective user ID +of the process matches the owner of the file or the process has +appropriate privileges in order to do this. +.P +S_ISUID, S_ISGID, +S_ISVTX, +and the file permission bits +are described in +.IR . +.P +If the calling process does not have appropriate privileges, and if the +group ID of the file does not match the effective group ID or one of +the supplementary group IDs and if the file is a regular file, bit +S_ISGID (set-group-ID on execution) in the file's mode shall be cleared +upon successful return from +\fIchmod\fR(). +.P +Additional implementation-defined restrictions may cause the S_ISUID +and S_ISGID bits in +.IR mode +to be ignored. +.P +Upon successful completion, +\fIchmod\fR() +shall mark for update the last file status change timestamp of the file. +.P +The +\fIfchmodat\fR() +function shall be equivalent to the +\fIchmod\fR() +function except in the case where +.IR path +specifies a relative path. In this case the file to be changed is +determined relative to the directory associated with the file +descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, then the mode of the symbolic link is changed. +.P +If +\fIfchmodat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used. If also +.IR flag +is zero, the behavior shall be identical to a call to +\fIchmod\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, no change to the +file mode occurs. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP +.BR EROFS +The named file resides on a read-only file system. +.P +The +\fIfchmodat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR EINVAL +The value of the +.IR mode +argument is invalid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.P +The +\fIfchmodat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is invalid. +.TP +.BR EOPNOTSUPP +The AT_SYMLINK_NOFOLLOW bit is set in the +.IR flag +argument, +.IR path +names a symbolic link, and the system does not support changing the +mode of a symbolic link. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Setting Read Permissions for User, Group, and Others" +.P +The following example sets read permissions for the owner, group, and +others. +.sp +.RS 4 +.nf +\fB +#include +.P +const char *path; +\&... +chmod(path, S_IRUSR|S_IRGRP|S_IROTH); +.fi \fR +.P +.RE +.SS "Setting Read, Write, and Execute Permissions for the Owner Only" +.P +The following example sets read, write, and execute permissions for the +owner, and no permissions for group and others. +.sp +.RS 4 +.nf +\fB +#include +.P +const char *path; +\&... +chmod(path, S_IRWXU); +.fi \fR +.P +.RE +.SS "Setting Different Permissions for Owner, Group, and Other" +.P +The following example sets owner permissions for CHANGEFILE to read, +write, and execute, group permissions to read and execute, and other +permissions to read. +.sp +.RS 4 +.nf +\fB +#include +.P +#define CHANGEFILE "/etc/myfile" +\&... +chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH); +.fi \fR +.P +.RE +.SS "Setting and Checking File Permissions" +.P +The following example sets the file permission bits for a file named +.BR /home/cnd/mod1 , +then calls the +\fIstat\fR() +function to verify the permissions. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int status; +struct stat buffer +\&... +chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH); +status = stat("home/cnd/mod1", &buffer;); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +In order to ensure that the S_ISUID and S_ISGID +bits are set, an application requiring this should use +\fIstat\fR() +after a successful +\fIchmod\fR() +to verify this. +.P +Any file descriptors currently open by any process on the file could +possibly become invalid if the mode of the file is changed to a value +which would deny access to that process. One situation where this could +occur is on a stateless file system. This behavior will not occur in a +conforming environment. +.SH RATIONALE +This volume of POSIX.1\(hy2008 specifies that the S_ISGID bit is cleared by +\fIchmod\fR() +on a regular file under certain conditions. This is specified on the +assumption that regular files may be executed, and the system should +prevent users from making executable +\fIsetgid\fR() +files perform with privileges that the caller does not have. On +implementations that support execution of other file types, the S_ISGID +bit should be cleared for those file types under the same +circumstances. +.P +Implementations that use the S_ISUID bit to indicate some other +function (for example, mandatory record locking) on non-executable +files need not clear this bit on writing. They should clear the bit +for executable files and any other cases where the bit grants special +powers to processes that change the file contents. Similar comments +apply to the S_ISGID bit. +.P +The purpose of the +\fIfchmodat\fR() +function is to enable changing the mode of files in directories other +than the current working directory without exposure to race conditions. +Any part of the path of a file could be changed in parallel to a call +to +\fIchmod\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIfchmodat\fR() +function it can be guaranteed that the changed file is located relative +to the desired directory. Some implementations might allow changing +the mode of symbolic links. This is not supported by the interfaces in +the POSIX specification. Systems with such support provide an +interface named +.IR lchmod (\|). +To support such implementations +\fIfchmodat\fR() +has a +.IR flag +parameter. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccess\fR\^(\|)", +.IR "\fIchown\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIfstatvfs\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/chown.3p b/man-pages-posix-2013-a/man3p/chown.3p new file mode 100644 index 0000000..5dc8ed6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/chown.3p @@ -0,0 +1,323 @@ +'\" et +.TH CHOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +chown, fchownat +\(em change owner and group of a file relative to directory +file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int chown(const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +int fchownat(int \fIfd\fP, const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP, + int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIchown\fR() +function shall change the user and group ownership of a file. +.P +The +.IR path +argument points to a pathname naming a file. The user ID and group ID +of the named file shall be set to the numeric values contained in +.IR owner +and +.IR group , +respectively. +.P +Only processes with an effective user ID equal to the user ID of the +file or with appropriate privileges may change the ownership of a +file. If _POSIX_CHOWN_RESTRICTED is in effect for +.IR path : +.IP " *" 4 +Changing the user ID is restricted to processes with appropriate +privileges. +.IP " *" 4 +Changing the group ID is permitted to a process with an effective user +ID equal to the user ID of the file, but without appropriate +privileges, if and only if +.IR owner +is equal to the file's user ID or (\c +.BR uid_t )\(mi1 +and +.IR group +is equal either to the calling process' effective group ID or to one of +its supplementary group IDs. +.P +If the specified file is a regular file, one or more of the S_IXUSR, +S_IXGRP, or S_IXOTH bits of the file mode are set, and the process does +not have appropriate privileges, the set-user-ID (S_ISUID) and +set-group-ID (S_ISGID) bits of the file mode shall be cleared upon +successful return from +\fIchown\fR(). +If the specified file is a regular file, one or more of the S_IXUSR, +S_IXGRP, or S_IXOTH bits of the file mode are set, and the process has +appropriate privileges, it is implementation-defined whether the +set-user-ID and set-group-ID bits are altered. If the +\fIchown\fR() +function is successfully invoked on a file that is not a regular file +and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file +mode are set, the set-user-ID and set-group-ID bits may be cleared. +.P +If +.IR owner +or +.IR group +is specified as (\c +.BR uid_t )\(mi1 +or (\c +.BR gid_t )\(mi1, +respectively, the corresponding ID of the file shall not be changed. +If both owner and group are \(mi1, the times need not be updated. +.P +Upon successful completion, +\fIchown\fR() +shall mark for update the last file status change timestamp of the file. +.P +The +\fIfchownat\fR() +function shall be equivalent to the +\fIchown\fR() +and +\fIlchown\fR() +functions except in the case where +.IR path +specifies a relative path. In this case the file to be changed is +determined relative to the directory associated with the file +descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, ownership of the symbolic link is changed. +.P +If +\fIfchownat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIchown\fR() +or +\fIlchown\fR() +respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit +is set in the +.IR flag +argument. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, no changes are +made in the user ID and group ID of the file. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID does not match the owner of the file, or the +calling process does not have appropriate privileges and +_POSIX_CHOWN_RESTRICTED indicates that such privilege is required. +.TP +.BR EROFS +The named file resides on a read-only file system. +.P +The +\fIfchownat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EIO +An I/O error occurred while reading or writing to the file system. +.TP +.BR EINTR +The +\fIchown\fR() +function was interrupted by a signal which was caught. +.TP +.BR EINVAL +The owner or group ID supplied is not a value supported by the +implementation. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.br +.P +The +\fIfchownat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Although +\fIchown\fR() +can be used on some implementations by the file owner to change the owner +and group to any desired values, the only portable use of this function +is to change the group of a file to the effective GID of the calling +process or to a member of its group set. +.SH RATIONALE +System III and System V allow a user to give away files; +that is, the owner of a file may change its user ID to anything. This +is a serious problem for implementations that are intended to meet +government security regulations. +Version 7 and 4.3 BSD permit only the superuser +to change the user ID of a file. Some government agencies (usually not +ones concerned directly with security) find this limitation too +confining. This volume of POSIX.1\(hy2008 uses \fImay\fP to permit secure implementations +while not disallowing System V. +.P +System III and System V allow the owner of a file to change the +group ID to anything. Version 7 permits only the superuser to change +the group ID of a file. +4.3 BSD permits the owner to change the group ID of a file +to its effective group ID +or to any of the groups in the list of supplementary group IDs, but to +no others. +.P +The POSIX.1\(hy1990 standard requires that the +\fIchown\fR() +function invoked by a non-appropriate privileged process clear the +S_ISGID and the S_ISUID bits for regular files, and permits them to be +cleared for other types of files. This is so that changes in +accessibility do not accidentally cause files to become security holes. +Unfortunately, requiring these bits to be cleared on non-executable +data files also clears the mandatory file locking bit (shared with +S_ISGID), which is an extension on many implementations (it first +appeared in System V). These bits should only be required to be +cleared on regular files that have one or more of their execute bits +set. +.P +The purpose of the +\fIfchownat\fR() +function is to enable changing ownership of files in directories other +than the current working directory without exposure to race +conditions. Any part of the path of a file could be changed in +parallel to a call to +\fIchown\fR() +or +\fIlchown\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIfchownat\fR() +function it can be guaranteed that the changed file is located relative +to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIlchown\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cimag.3p b/man-pages-posix-2013-a/man3p/cimag.3p new file mode 100644 index 0000000..5f96a6d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cimag.3p @@ -0,0 +1,78 @@ +'\" et +.TH CIMAG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cimag, +cimagf, +cimagl +\(em complex imaginary functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double cimag(double complex \fIz\fP); +float cimagf(float complex \fIz\fP); +long double cimagl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the imaginary part of +.IR z . +.SH "RETURN VALUE" +These functions shall return the imaginary part value (as a real). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For a variable +.IR z +of complex type: +.sp +.RS 4 +.nf +\fB +z == creal(z) + cimag(z)*I +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcarg\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)", +.IR "\fIcreal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/clearerr.3p b/man-pages-posix-2013-a/man3p/clearerr.3p new file mode 100644 index 0000000..2460d64 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/clearerr.3p @@ -0,0 +1,73 @@ +'\" et +.TH CLEARERR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +clearerr +\(em clear indicators on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +void clearerr(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIclearerr\fR() +function shall clear the end-of-file and error indicators for the +stream to which +.IR stream +points. +.P +The +\fIclearerr\fR() +function shall not change the setting of +.IR errno +if +.IR stream +is valid. +.SH "RETURN VALUE" +The +\fIclearerr\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/clock.3p b/man-pages-posix-2013-a/man3p/clock.3p new file mode 100644 index 0000000..8e5853c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/clock.3p @@ -0,0 +1,95 @@ +'\" et +.TH CLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +clock +\(em report CPU time used +.SH SYNOPSIS +.LP +.nf +#include +.P +clock_t clock(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIclock\fR() +function shall return the implementation's best approximation to the +processor time used by the process since the beginning of an +implementation-defined era related only to the process invocation. +.SH "RETURN VALUE" +To determine the time in seconds, the value returned by +\fIclock\fR() +should be divided by the value of the macro CLOCKS_PER_SEC. +CLOCKS_PER_SEC is defined to be one million in +.IR . +If the processor time used is not available or its value cannot be +represented, the function shall return the value (\c +.BR clock_t )\(mi1. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +In order to measure the time spent in a program, +\fIclock\fR() +should be called at the start of the program and its return value +subtracted from the value returned by subsequent calls. The value +returned by +\fIclock\fR() +is defined for compatibility across systems that have clocks with +different resolutions. The resolution on any particular system need +not be to microsecond accuracy. +.P +The value returned by +\fIclock\fR() +may wrap around on some implementations. For example, on a machine with +32-bit values for +.BR clock_t , +it wraps after 2\|147 seconds or 36 minutes. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/clock_getcpuclockid.3p b/man-pages-posix-2013-a/man3p/clock_getcpuclockid.3p new file mode 100644 index 0000000..4b3eb73 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/clock_getcpuclockid.3p @@ -0,0 +1,98 @@ +'\" et +.TH CLOCK_GETCPUCLOCKID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +clock_getcpuclockid +\(em access a process CPU-time clock +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int clock_getcpuclockid(pid_t \fIpid\fP, clockid_t *\fIclock_id\fP); +.fi +.SH DESCRIPTION +The +\fIclock_getcpuclockid\fR() +function shall return the clock ID of the CPU-time clock of the process +specified by +.IR pid . +If the process described by +.IR pid +exists and the calling process has permission, the clock ID of this +clock shall be returned in +.IR clock_id . +.P +If +.IR pid +is zero, the +\fIclock_getcpuclockid\fR() +function shall return the clock ID of the CPU-time clock of the process +making the call, in +.IR clock_id . +.P +The conditions under which one process has permission to obtain the +CPU-time clock ID of other processes are implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, +\fIclock_getcpuclockid\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIclock_getcpuclockid\fR() +function shall fail if: +.TP +.BR EPERM +The requesting process does not have permission to access the CPU-time +clock for the process. +.P +The +\fIclock_getcpuclockid\fR() +function may fail if: +.TP +.BR ESRCH +No process can be found corresponding to the process specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIclock_getcpuclockid\fR() +function is part of the Process CPU-Time Clocks option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/clock_getres.3p b/man-pages-posix-2013-a/man3p/clock_getres.3p new file mode 100644 index 0000000..58c42f6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/clock_getres.3p @@ -0,0 +1,284 @@ +'\" et +.TH CLOCK_GETRES "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +clock_getres, +clock_gettime, +clock_settime +\(em clock and timer functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int clock_getres(clockid_t \fIclock_id\fP, struct timespec *\fIres\fP); +int clock_gettime(clockid_t \fIclock_id\fP, struct timespec *\fItp\fP); +int clock_settime(clockid_t \fIclock_id\fP, const struct timespec *\fItp\fP); +.fi +.SH DESCRIPTION +The +\fIclock_getres\fR() +function shall return the resolution of any clock. Clock resolutions +are implementation-defined and cannot be set by a process. If the +argument +.IR res +is not NULL, the resolution of the specified clock shall be stored in the +location pointed to by +.IR res . +If +.IR res +is NULL, the clock resolution is not returned. If the +.IR time +argument of +\fIclock_settime\fR() +is not a multiple of +.IR res , +then the value is truncated to a multiple of +.IR res . +.P +The +\fIclock_gettime\fR() +function shall return the current value +.IR tp +for the specified clock, +.IR clock_id . +.P +The +\fIclock_settime\fR() +function shall set the specified clock, +.IR clock_id , +to the value specified by +.IR tp . +Time values that are between two consecutive non-negative integer +multiples of the resolution of the specified clock shall be truncated +down to the smaller multiple of the resolution. +.P +A clock may be system-wide (that is, visible to all processes) or +per-process (measuring time that is meaningful only within a process). +All implementations shall support a +.IR clock_id +of CLOCK_REALTIME as defined in +.IR . +This clock represents the clock measuring real time for the system. +For this clock, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +represent the amount of time (in seconds and nanoseconds) since the +Epoch. An implementation may also support additional clocks. The +interpretation of time values for these clocks is unspecified. +.P +If the value of the CLOCK_REALTIME clock is set via +\fIclock_settime\fR(), +the new value of the clock shall be used to determine the time of +expiration for absolute time services based upon the CLOCK_REALTIME +clock. This applies to the time at which armed absolute timers expire. +If the absolute time requested at the invocation of such a time service +is before the new value of the clock, the time service shall expire +immediately as if the clock had reached the requested time normally. +.P +Setting the value of the CLOCK_REALTIME clock via +\fIclock_settime\fR() +shall have no effect on threads that are blocked waiting for a relative +time service based upon this clock, including the +\fInanosleep\fR() +function; nor on the expiration of relative timers based upon this +clock. Consequently, these time services shall expire when the +requested relative interval elapses, independently of the new or old +value of the clock. +.P +If the Monotonic Clock option is supported, all implementations shall +support a +.IR clock_id +of CLOCK_MONOTONIC defined in +.IR . +This clock represents the monotonic clock for the system. For this +clock, the value returned by +\fIclock_gettime\fR() +represents the amount of time (in seconds and nanoseconds) since an +unspecified point in the past (for example, system start-up time, or the +Epoch). This point does not change after system start-up time. The value +of the CLOCK_MONOTONIC clock cannot be set via +\fIclock_settime\fR(). +This function shall fail if it is invoked with a +.IR clock_id +argument of CLOCK_MONOTONIC. +.P +The effect of setting a clock via +\fIclock_settime\fR() +on armed per-process timers associated with a clock other than +CLOCK_REALTIME is implementation-defined. +.P +If the value of the CLOCK_REALTIME clock is set via +\fIclock_settime\fR(), +the new value of the clock shall be used to determine the time at which +the system shall awaken a thread blocked on an absolute +\fIclock_nanosleep\fR() +call based upon the CLOCK_REALTIME clock. If the absolute time +requested at the invocation of such a time service is before the new +value of the clock, the call shall return immediately as if the clock +had reached the requested time normally. +.P +Setting the value of the CLOCK_REALTIME clock via +\fIclock_settime\fR() +shall have no effect on any thread that is blocked on a relative +\fIclock_nanosleep\fR() +call. Consequently, the call shall return when the requested relative +interval elapses, independently of the new or old value of the clock. +.P +Appropriate privileges to set a particular clock are +implementation-defined. +.P +If _POSIX_CPUTIME is defined, implementations shall support clock ID +values obtained by invoking +\fIclock_getcpuclockid\fR(), +which represent the CPU-time clock of a given process. Implementations +shall also support the special +.BR clockid_t +value CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of +the calling process when invoking one of the +.IR clock_* (\|) +or +.IR timer_* (\|) +functions. For these clock IDs, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +represent the amount of execution time of the process associated with +the clock. Changing the value of a CPU-time clock via +\fIclock_settime\fR() +shall have no effect on the behavior of the sporadic server scheduling +policy (see +.IR "Scheduling Policies"). +.P +If _POSIX_THREAD_CPUTIME is defined, implementations shall support +clock ID values obtained by invoking +\fIpthread_getcpuclockid\fR(), +which represent the CPU-time clock of a given thread. Implementations +shall also support the special +.BR clockid_t +value CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of +the calling thread when invoking one of the +.IR clock_* (\|) +or +.IR timer_* (\|) +functions. For these clock IDs, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +shall represent the amount of execution time of the thread associated +with the clock. Changing the value of a CPU-time clock via +\fIclock_settime\fR() +shall have no effect on the behavior of the sporadic server scheduling +policy (see +.IR "Scheduling Policies"). +.SH "RETURN VALUE" +A return value of 0 shall indicate that the call succeeded. A return +value of \(mi1 shall indicate that an error occurred, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIclock_getres\fR(), +\fIclock_gettime\fR(), +and +\fIclock_settime\fR() +functions shall fail if: +.TP +.BR EINVAL +The +.IR clock_id +argument does not specify a known clock. +.P +The +\fIclock_gettime\fR() +function shall fail if: +.TP +.BR EOVERFLOW +The number of seconds will not fit in an object of type +.BR time_t . +.P +The +\fIclock_settime\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR tp +argument to +\fIclock_settime\fR() +is outside the range for the given clock ID. +.TP +.BR EINVAL +The +.IR tp +argument specified a nanosecond value less than zero or greater than or +equal to 1\|000 million. +.TP +.BR EINVAL +The value of the +.IR clock_id +argument is CLOCK_MONOTONIC. +.P +The +\fIclock_settime\fR() +function may fail if: +.TP +.BR EPERM +The requesting process does not have appropriate privileges +to set the specified clock. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Note that the absolute value of the monotonic clock is meaningless +(because its origin is arbitrary), and thus there is no need to set it. +Furthermore, realtime applications can rely on the fact that the value +of this clock is never set and, therefore, that time intervals measured +with this clock will not be affected by calls to +\fIclock_settime\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "Scheduling Policies", +.IR "\fIclock_getcpuclockid\fR\^(\|)", +.IR "\fIclock_nanosleep\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/clock_nanosleep.3p b/man-pages-posix-2013-a/man3p/clock_nanosleep.3p new file mode 100644 index 0000000..000d3b2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/clock_nanosleep.3p @@ -0,0 +1,261 @@ +'\" et +.TH CLOCK_NANOSLEEP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +clock_nanosleep +\(em high resolution sleep with specifiable clock +.SH SYNOPSIS +.LP +.nf +#include +.P +int clock_nanosleep(clockid_t \fIclock_id\fP, int \fIflags\fP, + const struct timespec *\fIrqtp\fP, struct timespec *\fIrmtp\fP); +.fi +.SH DESCRIPTION +If the flag TIMER_ABSTIME +is not set in the +.IR flags +argument, the +\fIclock_nanosleep\fR() +function shall cause the current thread to be suspended from execution +until either the time interval specified by the +.IR rqtp +argument has elapsed, or a signal is delivered to the calling thread +and its action is to invoke a signal-catching function, or the process +is terminated. The clock used to measure the time shall be the clock +specified by +.IR clock_id . +.P +If the flag TIMER_ABSTIME is set in the +.IR flags +argument, the +\fIclock_nanosleep\fR() +function shall cause the current thread to be suspended from execution +until either the time value of the clock specified by +.IR clock_id +reaches the absolute time specified by the +.IR rqtp +argument, or a signal is delivered to the calling thread and its action +is to invoke a signal-catching function, or the process is terminated. +If, at the time of the call, the time value specified by +.IR rqtp +is less than or equal to the time value of the specified clock, then +\fIclock_nanosleep\fR() +shall return immediately and the calling process shall not be +suspended. +.P +The suspension time caused by this function may be longer than +requested because the argument value is rounded up to an integer +multiple of the sleep resolution, or because of the scheduling of other +activity by the system. But, except for the case of being interrupted +by a signal, the suspension time for the relative +\fIclock_nanosleep\fR() +function (that is, with the TIMER_ABSTIME flag not set) shall not be +less than the time interval specified by +.IR rqtp , +as measured by the corresponding clock. The suspension for the absolute +\fIclock_nanosleep\fR() +function (that is, with the TIMER_ABSTIME flag set) shall be in effect +at least until the value of the corresponding clock reaches the +absolute time specified by +.IR rqtp , +except for the case of being interrupted by a signal. +.P +The use of the +\fIclock_nanosleep\fR() +function shall have no effect on the action or blockage of any signal. +.P +The +\fIclock_nanosleep\fR() +function shall fail if the +.IR clock_id +argument refers to the CPU-time clock of the calling thread. It is +unspecified whether +.IR clock_id +values of other CPU-time clocks are allowed. +.SH "RETURN VALUE" +If the +\fIclock_nanosleep\fR() +function returns because the requested time has elapsed, its return +value shall be zero. +.P +If the +\fIclock_nanosleep\fR() +function returns because it has been interrupted by a signal, it shall +return the corresponding error value. For the relative +\fIclock_nanosleep\fR() +function, if the +.IR rmtp +argument is non-NULL, the +.BR timespec +structure referenced by it shall be updated to contain the amount of +time remaining in the interval (the requested time minus the time +actually slept). If the +.IR rmtp +argument is NULL, the remaining time is not returned. The absolute +\fIclock_nanosleep\fR() +function has no effect on the structure referenced by +.IR rmtp . +.P +If +\fIclock_nanosleep\fR() +fails, it shall return the corresponding error value. +.SH ERRORS +The +\fIclock_nanosleep\fR() +function shall fail if: +.TP +.BR EINTR +The +\fIclock_nanosleep\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +.IR rqtp +argument specified a nanosecond value less than zero or greater than or +equal to 1\|000 million; or the TIMER_ABSTIME flag was specified in +flags and the +.IR rqtp +argument is outside the range for the clock specified by +.IR clock_id ; +or the +.IR clock_id +argument does not specify a known clock, or specifies the CPU-time +clock of the calling thread. +.TP +.BR ENOTSUP +The +.IR clock_id +argument specifies a clock for which +\fIclock_nanosleep\fR() +is not supported, such as a CPU-time clock. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Calling +\fIclock_nanosleep\fR() +with the value TIMER_ABSTIME not set in the +.IR flags +argument and with a +.IR clock_id +of CLOCK_REALTIME is equivalent to calling +\fInanosleep\fR() +with the same +.IR rqtp +and +.IR rmtp +arguments. +.SH RATIONALE +The +\fInanosleep\fR() +function specifies that the system-wide clock CLOCK_REALTIME is used to +measure the elapsed time for this time service. However, with the +introduction of the monotonic clock CLOCK_MONOTONIC a new relative +sleep function is needed to allow an application to take advantage of +the special characteristics of this clock. +.P +There are many applications in which a process needs to be suspended +and then activated multiple times in a periodic way; for example, to +poll the status of a non-interrupting device or to refresh a display +device. For these cases, it is known that precise periodic activation +cannot be achieved with a relative +\fIsleep\fR() +or +\fInanosleep\fR() +function call. Suppose, for example, a periodic process that is +activated at time +.IR T 0, +executes for a while, and then wants to suspend itself until time +.IR T 0+\c +.IR T , +the period being +.IR T . +If this process wants to use the +\fInanosleep\fR() +function, it must first call +\fIclock_gettime\fR() +to get the current time, then calculate the difference between the +current time and +.IR T 0+\c +.IR T +and, finally, call +\fInanosleep\fR() +using the computed interval. However, the process could be preempted by +a different process between the two function calls, and in this case +the interval computed would be wrong; the process would wake up later +than desired. This problem would not occur with the absolute +\fIclock_nanosleep\fR() +function, since only one function call would be necessary to suspend +the process until the desired time. In other cases, however, a relative +sleep is needed, and that is why both functionalities are required. +.P +Although it is possible to implement periodic processes using the +timers interface, this implementation would require the use of signals, +and the reservation of some signal numbers. In this regard, the reasons +for including an absolute version of the +\fIclock_nanosleep\fR() +function in POSIX.1\(hy2008 are the same as for the inclusion of the relative +\fInanosleep\fR(). +.P +It is also possible to implement precise periodic processes using +\fIpthread_cond_timedwait\fR(), +in which an absolute timeout is specified that takes effect if the +condition variable involved is never signaled. However, the use of this +interface is unnatural, and involves performing other operations on +mutexes and condition variables that imply an unnecessary overhead. +Furthermore, +\fIpthread_cond_timedwait\fR() +is not available in implementations that do not support threads. +.P +Although the interface of the relative and absolute versions of the new +high resolution sleep service is the same +\fIclock_nanosleep\fR() +function, the +.IR rmtp +argument is only used in the relative sleep. This argument is needed in +the relative +\fIclock_nanosleep\fR() +function to reissue the function call if it is interrupted by a signal, +but it is not needed in the absolute +\fIclock_nanosleep\fR() +function call; if the call is interrupted by a signal, the absolute +\fIclock_nanosleep\fR() +function can be invoked again with the same +.IR rqtp +argument used in the interrupted call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/clock_settime.3p b/man-pages-posix-2013-a/man3p/clock_settime.3p new file mode 100644 index 0000000..1a03aac --- /dev/null +++ b/man-pages-posix-2013-a/man3p/clock_settime.3p @@ -0,0 +1,38 @@ +'\" et +.TH CLOCK_SETTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +clock_settime +\(em clock and timer functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int clock_settime(clockid_t \fIclock_id\fP, const struct timespec *\fItp\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIclock_getres\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/clog.3p b/man-pages-posix-2013-a/man3p/clog.3p new file mode 100644 index 0000000..3fe3620 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/clog.3p @@ -0,0 +1,71 @@ +'\" et +.TH CLOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +clog, +clogf, +clogl +\(em complex natural logarithm functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex clog(double complex \fIz\fP); +float complex clogf(float complex \fIz\fP); +long double complex clogl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex natural (base +.IR e ) +logarithm of +.IR z , +with a branch cut along the negative real axis. +.SH "RETURN VALUE" +These functions shall return the complex natural logarithm value, in +the range of a strip mathematically unbounded along the real axis and +in the interval [\(mi\fIi\fR\(*p,\ +\fIi\fR\(*p] along the imaginary +axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcexp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/close.3p b/man-pages-posix-2013-a/man3p/close.3p new file mode 100644 index 0000000..98910e8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/close.3p @@ -0,0 +1,329 @@ +'\" et +.TH CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +close +\(em close a file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int close(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIclose\fR() +function shall deallocate the file descriptor indicated by +.IR fildes . +To deallocate means to make the file descriptor available for return by +subsequent calls to +\fIopen\fR() +or other functions that allocate file descriptors. All outstanding +record locks owned by the process on the file associated with the file +descriptor shall be removed (that is, unlocked). +.P +If +\fIclose\fR() +is interrupted by a signal that is to be caught, it shall return +\(mi1 with +.IR errno +set to +.BR [EINTR] +and the state of +.IR fildes +is unspecified. If an I/O error occurred while reading from or writing +to the file system during +\fIclose\fR(), +it may return \(mi1 with +.IR errno +set to +.BR [EIO] ; +if this error is returned, the state of +.IR fildes +is unspecified. +.P +When all file descriptors associated with a pipe or FIFO special file +are closed, any data remaining in the pipe or FIFO shall be discarded. +.P +When all file descriptors associated with an open file description have +been closed, the open file description shall be freed. +.P +If the link count of the file is 0, when all file descriptors +associated with the file are closed, the space occupied by the file +shall be freed and the file shall no longer be accessible. +.P +If a STREAMS-based +.IR fildes +is closed and the calling process was previously registered to receive +a SIGPOLL signal +for events associated with that STREAM, the calling process shall be +unregistered for events associated with the STREAM. The last +\fIclose\fR() +for a STREAM shall cause the STREAM associated with +.IR fildes +to be dismantled. If O_NONBLOCK is not set and there have been no +signals posted for the STREAM, +and if there is data on the module's write queue, +\fIclose\fR() +shall wait for an unspecified time (for each module and driver) for +any output to drain before dismantling the STREAM. The time delay +can be changed via an I_SETCLTIME +\fIioctl\fR() +request. If the O_NONBLOCK flag is set, or if there are any pending +signals, +\fIclose\fR() +shall not wait for output to drain, and shall dismantle the STREAM +immediately. +.P +If the implementation supports STREAMS-based pipes, and +.IR fildes +is associated with one end of a pipe, the last +\fIclose\fR() +shall cause a hangup to occur on the other end of the pipe. In +addition, if the other end of the pipe has been named by +\fIfattach\fR(), +then the last +\fIclose\fR() +shall force the named end to be detached by +\fIfdetach\fR(). +If the named end has no open file descriptors associated with it and +gets detached, the STREAM associated with that end shall also be +dismantled. +.P +If +.IR fildes +refers to the master side of a pseudo-terminal, and this is the last +close, a SIGHUP signal shall be sent to the +controlling process, if any, for which the slave side of the +pseudo-terminal is the controlling terminal. It is unspecified whether +closing the master side of the pseudo-terminal flushes all queued input +and output. +.P +If +.IR fildes +refers to the slave side of a STREAMS-based pseudo-terminal, a +zero-length message may be sent to the master. +.P +When there is an outstanding cancelable asynchronous I/O operation +against +.IR fildes +when +\fIclose\fR() +is called, that I/O operation may be canceled. An I/O operation that +is not canceled completes as if the +\fIclose\fR() +operation had not yet occurred. All operations that are not canceled +shall complete as if the +\fIclose\fR() +blocked until the operations completed. The +\fIclose\fR() +operation itself need not block awaiting such I/O completion. Whether +any I/O operation is canceled, and which I/O operation may be +canceled upon +\fIclose\fR(), +is implementation-defined. +.P +If a memory mapped file +or a shared memory object +remains referenced at the last close (that is, a process has +it mapped), then the entire contents of the memory object shall +persist until the memory object becomes unreferenced. +If this is the last close of a memory mapped file +or a shared memory object +and the close results in the memory object becoming unreferenced, +and the memory object has been unlinked, then the memory object +shall be removed. +.P +If +.IR fildes +refers to a socket, +\fIclose\fR() +shall cause the socket to be destroyed. If the socket is in +connection-mode, and the SO_LINGER option is set for the socket with +non-zero linger time, and the socket has untransmitted data, then +\fIclose\fR() +shall block for up to the current linger interval until all data is +transmitted. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIclose\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a open file descriptor. +.TP +.BR EINTR +The +\fIclose\fR() +function was interrupted by a signal. +.P +The +\fIclose\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reassigning a File Descriptor" +.P +The following example closes the file descriptor associated with +standard output for the current process, re-assigns standard output to +a new file descriptor, and closes the original file descriptor to clean +up. This example assumes that the file descriptor 0 (which is the +descriptor for standard input) is not closed. +.sp +.RS 4 +.nf +\fB +#include +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +.fi \fR +.P +.RE +.P +Incidentally, this is exactly what could be achieved using: +.sp +.RS 4 +.nf +\fB +dup2(pfd, 1); +close(pfd); +.fi \fR +.P +.RE +.SS "Closing a File Descriptor" +.P +In the following example, +\fIclose\fR() +is used to close +a file descriptor after an unsuccessful attempt is made to associate that +file descriptor with a stream. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; +FILE *fpfd; +\&... +if ((fpfd = fdopen (pfd, "w")) == NULL) { + close(pfd); + unlink(LOCKFILE); + exit(1); +} +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +An application that had used the +.IR stdio +routine +\fIfopen\fR() +to open a file should use the corresponding +\fIfclose\fR() +routine rather than +\fIclose\fR(). +Once a file is closed, the file descriptor no longer exists, since the +integer corresponding to it no longer refers to a file. +.P +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIclose\fR() +on an arbitrary integer risks non-conforming behavior, and +\fIclose\fR() +can only portably be used on file descriptor values that the application +has obtained through explicit actions, as well as the three file +descriptors corresponding to the standard file streams. In multi-threaded +parent applications, the practice of calling +\fIclose\fR() +in a loop after +\fIfork\fR() +and before an +.IR exec +call in order to avoid a race condition of leaking an unintended file +descriptor into a child process, is therefore unsafe, and the race should +instead be combatted by opening all file descriptors with the FD_CLOEXEC +bit set unless the file descriptor is intended to be inherited across +.IR exec . +.SH RATIONALE +The use of interruptible device close routines should be discouraged to +avoid problems with the implicit closes of file descriptors by +.IR exec +and +\fIexit\fR(). +This volume of POSIX.1\(hy2008 only intends to permit such behavior by specifying the +.BR [EINTR] +error condition. +.P +Note that the requirement for +\fIclose\fR() +on a socket to block for up to the current linger interval is not +conditional on the O_NONBLOCK setting. +.P +The standard developers rejected a proposal to add +\fIclosefrom\fR() +to the standard. Because the standard permits implementations to +use inherited file descriptors as a means of providing a conforming +environment for the child process, it is not possible to standardize an +interface that closes arbitrary file descriptors above a certain value +while still guaranteeing a conforming environment. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIexec\fR\^", +.IR "\fIfattach\fR\^(\|)", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdetach\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/closedir.3p b/man-pages-posix-2013-a/man3p/closedir.3p new file mode 100644 index 0000000..3a27757 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/closedir.3p @@ -0,0 +1,108 @@ +'\" et +.TH CLOSEDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +closedir +\(em close a directory stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int closedir(DIR *\fIdirp\fP); +.fi +.SH DESCRIPTION +The +\fIclosedir\fR() +function shall close the directory stream referred to by the argument +.IR dirp . +Upon return, the value of +.IR dirp +may no longer point to an accessible object of the type +.BR DIR . +If a file descriptor is used to implement type +.BR DIR , +that file descriptor shall be closed. +.SH "RETURN VALUE" +Upon successful completion, +\fIclosedir\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIclosedir\fR() +function may fail if: +.TP +.BR EBADF +The +.IR dirp +argument does not refer to an open directory stream. +.TP +.BR EINTR +The +\fIclosedir\fR() +function was interrupted by a signal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Closing a Directory Stream" +.P +The following program fragment demonstrates how the +\fIclosedir\fR() +function is used. +.sp +.RS 4 +.nf +\fB +\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { +\&... + } +.P + while ((dp = readdir (dir)) != NULL) { +\&... + } +.P + closedir(dir); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/closelog.3p b/man-pages-posix-2013-a/man3p/closelog.3p new file mode 100644 index 0000000..e29a69e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/closelog.3p @@ -0,0 +1,291 @@ +'\" et +.TH CLOSELOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +closelog, +openlog, +setlogmask, +syslog +\(em control system log +.SH SYNOPSIS +.LP +.nf +#include +.P +void closelog(void); +void openlog(const char *\fIident\fP, int \fIlogopt\fP, int \fIfacility\fP); +int setlogmask(int \fImaskpri\fP); +void syslog(int \fIpriority\fP, const char *\fImessage\fP, ... /* \fIarguments\fP */); +.fi +.SH DESCRIPTION +The +\fIsyslog\fR() +function shall send a message to an implementation-defined logging +facility, which may log it in an implementation-defined system log, +write it to the system console, forward it to a list of users, or +forward it to the logging facility on another host over the network. +The logged message shall include a message header and a message body. +The message header contains at least a timestamp and a tag string. +.P +The message body is generated from the +.IR message +and following arguments in the same manner as if these were arguments +to +\fIprintf\fR(), +except that the additional conversion specification +.BR %m +shall be recognized; it shall convert no arguments, shall cause the +output of the error message string associated with the value of +.IR errno +on entry to +\fIsyslog\fR(), +and may be mixed with argument specifications of the \fR"%\fIn\fR$"\fR +form. If a complete conversion specification with the +.BR m +conversion specifier character is not just +.BR %m , +the behavior is undefined. A trailing + +may be added if needed. +.P +Values of the +.IR priority +argument are formed by OR'ing together a severity-level value and an +optional facility value. If no facility value is specified, the current +default facility value is used. +.P +Possible values of severity level include: +.IP LOG_EMERG 12 +A panic condition. +.IP LOG_ALERT 12 +A condition that should be corrected immediately, such as a corrupted +system database. +.IP LOG_CRIT 12 +Critical conditions, such as hard device errors. +.IP LOG_ERR 12 +Errors. +.IP LOG_WARNING 12 +.br +Warning messages. +.IP LOG_NOTICE 12 +Conditions that are not error conditions, but that may require special +handling. +.IP LOG_INFO 12 +Informational messages. +.IP LOG_DEBUG 12 +Messages that contain information normally of use only when debugging a +program. +.P +The facility indicates the application or system component generating +the message. Possible facility values include: +.IP LOG_USER 12 +Messages generated by arbitrary processes. This is the default facility +identifier if none is specified. +.IP LOG_LOCAL0 12 +Reserved for local use. +.IP LOG_LOCAL1 12 +Reserved for local use. +.IP LOG_LOCAL2 12 +Reserved for local use. +.IP LOG_LOCAL3 12 +Reserved for local use. +.IP LOG_LOCAL4 12 +Reserved for local use. +.IP LOG_LOCAL5 12 +Reserved for local use. +.IP LOG_LOCAL6 12 +Reserved for local use. +.IP LOG_LOCAL7 12 +Reserved for local use. +.P +The +\fIopenlog\fR() +function shall set process attributes that affect subsequent calls to +\fIsyslog\fR(). +The +.IR ident +argument is a string that is prepended to every message. The +.IR logopt +argument indicates logging options. Values for +.IR logopt +are constructed by a bitwise-inclusive OR of zero or more of the +following: +.IP LOG_PID 12 +Log the process ID with each message. This is useful for identifying +specific processes. +.IP LOG_CONS 12 +Write messages to the system console if they cannot be sent to the +logging facility. The +\fIsyslog\fR() +function ensures that the process does not acquire the console as a +controlling terminal in the process of writing the message. +.IP LOG_NDELAY 12 +Open the connection to the logging facility immediately. Normally the +open is delayed until the first message is logged. This is useful for +programs that need to manage the order in which file descriptors are +allocated. +.IP LOG_ODELAY 12 +Delay open until +\fIsyslog\fR() +is called. +.IP LOG_NOWAIT 12 +Do not wait for child processes that may have been created during the +course of logging the message. This option should be used by processes +that enable notification of child termination using SIGCHLD, since +\fIsyslog\fR() +may otherwise block waiting for a child whose exit status has already +been collected. +.P +The +.IR facility +argument encodes a default facility to be assigned to all messages that +do not have an explicit facility already encoded. The initial default +facility is LOG_USER. +.P +The +\fIopenlog\fR() +and +\fIsyslog\fR() +functions may allocate a file descriptor. It is not necessary to call +\fIopenlog\fR() +prior to calling +\fIsyslog\fR(). +.P +The +\fIcloselog\fR() +function shall close any open file descriptors allocated by previous +calls to +\fIopenlog\fR() +or +\fIsyslog\fR(). +.P +The +\fIsetlogmask\fR() +function shall set the log priority mask for the current process to +.IR maskpri +and return the previous mask. If the +.IR maskpri +argument is 0, the current log mask is not modified. Calls by the +current process to +\fIsyslog\fR() +with a priority not set in +.IR maskpri +shall be rejected. The default log mask allows all priorities to be +logged. A call to +\fIopenlog\fR() +is not required prior to calling +\fIsetlogmask\fR(). +.P +Symbolic constants for use as values of the +.IR logopt , +.IR facility , +.IR priority , +and +.IR maskpri +arguments are defined in the +.IR +header. +.SH "RETURN VALUE" +The +\fIsetlogmask\fR() +function shall return the previous log priority mask. The +\fIcloselog\fR(), +\fIopenlog\fR(), +and +\fIsyslog\fR() +functions shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using openlog(\|)" +.P +The following example causes subsequent calls to +\fIsyslog\fR() +to log the process ID with each message, and to write messages to the +system console if they cannot be sent to the logging facility. +.sp +.RS 4 +.nf +\fB +#include +.P +char *ident = "Process demo"; +int logopt = LOG_PID | LOG_CONS; +int facility = LOG_USER; +\&... +openlog(ident, logopt, facility); +.fi \fR +.P +.RE +.SS "Using setlogmask(\|)" +.P +The following example causes subsequent calls to +\fIsyslog\fR() +to accept error messages, and to reject all other messages. +.sp +.RS 4 +.nf +\fB +#include +.P +int result; +int mask = LOG_MASK (LOG_ERR); +\&... +result = setlogmask(mask); +.fi \fR +.P +.RE +.SS "Using syslog" +.P +The following example sends the message +.BR \(dqThis is a message\(dq +to the default logging facility, marking the message as an error +message generated by random processes. +.sp +.RS 4 +.nf +\fB +#include +.P +char *message = "This is a message"; +int priority = LOG_ERR | LOG_USER; +\&... +syslog(priority, message); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/confstr.3p b/man-pages-posix-2013-a/man3p/confstr.3p new file mode 100644 index 0000000..01f2f3d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/confstr.3p @@ -0,0 +1,278 @@ +'\" et +.TH CONFSTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +confstr +\(em get configurable variables +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t confstr(int \fIname\fP, char *\fIbuf\fP, size_t \fIlen\fP); +.fi +.SH DESCRIPTION +The +\fIconfstr\fR() +function shall return configuration-defined string values. Its use and +purpose are similar to +\fIsysconf\fR(), +but it is used where string values rather than numeric values are +returned. +.P +The +.IR name +argument represents the system variable to be queried. The +implementation shall support the following name values, defined in +.IR . +It may support others: +.P +.nf +_CS_PATH +_CS_POSIX_V7_ILP32_OFF32_CFLAGS +_CS_POSIX_V7_ILP32_OFF32_LDFLAGS +_CS_POSIX_V7_ILP32_OFF32_LIBS +_CS_POSIX_V7_ILP32_OFFBIG_CFLAGS +_CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS +_CS_POSIX_V7_ILP32_OFFBIG_LIBS +_CS_POSIX_V7_LP64_OFF64_CFLAGS +_CS_POSIX_V7_LP64_OFF64_LDFLAGS +_CS_POSIX_V7_LP64_OFF64_LIBS +_CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS +_CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS +_CS_POSIX_V7_LPBIG_OFFBIG_LIBS +_CS_POSIX_V7_THREADS_CFLAGS +_CS_POSIX_V7_THREADS_LDFLAGS +_CS_POSIX_V7_WIDTH_RESTRICTED_ENVS +_CS_V7_ENV +_CS_POSIX_V6_ILP32_OFF32_CFLAGS +_CS_POSIX_V6_ILP32_OFF32_LDFLAGS +_CS_POSIX_V6_ILP32_OFF32_LIBS +_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS +_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS +_CS_POSIX_V6_ILP32_OFFBIG_LIBS +_CS_POSIX_V6_LP64_OFF64_CFLAGS +_CS_POSIX_V6_LP64_OFF64_LDFLAGS +_CS_POSIX_V6_LP64_OFF64_LIBS +_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS +_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS +_CS_POSIX_V6_LPBIG_OFFBIG_LIBS +_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS +_CS_V6_ENV +.fi +.P +If +.IR len +is not 0, and if +.IR name +has a configuration-defined value, +\fIconfstr\fR() +shall copy that value into the +.IR len -byte +buffer pointed to by +.IR buf . +If the string to be returned is longer than +.IR len +bytes, including the terminating null, then +\fIconfstr\fR() +shall truncate the string to +.IR len \(mi1 +bytes and null-terminate the result. The application can detect that +the string was truncated by comparing the value returned by +\fIconfstr\fR() +with +.IR len . +.P +If +.IR len +is 0 and +.IR buf +is a null pointer, then +\fIconfstr\fR() +shall still return the integer value as defined below, but shall not +return a string. If +.IR len +is 0 but +.IR buf +is not a null pointer, the result is unspecified. +.P +After a call to: +.sp +.RS 4 +.nf +\fB +confstr(_CS_V7_ENV, buf, sizeof(buf)) +.fi \fR +.P +.RE +.P +the string stored in +.IR buf +will contain the +-separated +list of variable=value environment variable pairs required by the +implementation to create a conforming environment, as described in the +implementations' conformance documentation. +.P +If the implementation supports the POSIX shell option, the string +stored in +.IR buf +after a call to: +.sp +.RS 4 +.nf +\fB +confstr(_CS_PATH, buf, sizeof(buf)) +.fi \fR +.P +.RE +.P +can be used as a value of the +.IR PATH +environment variable that accesses all of the standard utilities of +POSIX.1\(hy2008, if the return value is less than or equal to +.IR sizeof (\c +.IR buf ). +.SH "RETURN VALUE" +If +.IR name +has a configuration-defined value, +\fIconfstr\fR() +shall return the size of buffer that would be needed to hold the entire +configuration-defined value including the terminating null. If this +return value is greater than +.IR len , +the string returned in +.IR buf +is truncated. +.P +If +.IR name +is invalid, +\fIconfstr\fR() +shall return 0 and set +.IR errno +to indicate the error. +.P +If +.IR name +does not have a configuration-defined value, +\fIconfstr\fR() +shall return 0 and leave +.IR errno +unchanged. +.SH ERRORS +The +\fIconfstr\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR name +argument is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +An application can distinguish between an invalid +.IR name +parameter value and one that corresponds to a configurable variable +that has no configuration-defined value by checking if +.IR errno +is modified. This mirrors the behavior of +\fIsysconf\fR(). +.P +The original need for this function was to provide a way of finding the +configuration-defined default value for the environment variable +.IR PATH . +Since +.IR PATH +can be modified by the user to include directories that could contain +utilities replacing the standard utilities in the Shell and Utilities volume of POSIX.1\(hy2008, applications +need a way to determine the system-supplied +.IR PATH +environment variable value that contains the correct search path for +the standard utilities. +.P +An application could use: +.sp +.RS 4 +.nf +\fB +confstr(name, (char *)NULL, (size_t)0) +.fi \fR +.P +.RE +.P +to find out how big a buffer is needed for the string value; use +\fImalloc\fR() +to allocate a buffer to hold the string; and call +\fIconfstr\fR() +again to get the string. Alternately, it could allocate a fixed, static +buffer that is big enough to hold most answers (perhaps 512 or 1\|024 +bytes), but then use +\fImalloc\fR() +to allocate a larger buffer if it finds that this is too small. +.SH RATIONALE +Application developers can normally determine any configuration +variable by means of reading from the stream opened by a call to: +.sp +.RS 4 +.nf +\fB +popen("command -p getconf variable", "r"); +.fi \fR +.P +.RE +.P +The +\fIconfstr\fR() +function with a +.IR name +argument of _CS_PATH returns a string that can be used as a +.IR PATH +environment variable setting that will reference the standard shell and +utilities as described in the Shell and Utilities volume of POSIX.1\(hy2008. +.P +The +\fIconfstr\fR() +function copies the returned string into a buffer supplied by the +application instead of returning a pointer to a string. This allows a +cleaner function in some implementations (such as those with +lightweight threads) and resolves questions about when the application +must copy the string returned. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIc99\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/conj.3p b/man-pages-posix-2013-a/man3p/conj.3p new file mode 100644 index 0000000..f15209f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/conj.3p @@ -0,0 +1,69 @@ +'\" et +.TH CONJ "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +conj, +conjf, +conjl +\(em complex conjugate functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex conj(double complex \fIz\fP); +float complex conjf(float complex \fIz\fP); +long double complex conjl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex conjugate of +.IR z , +by reversing the sign of its imaginary part. +.SH "RETURN VALUE" +These functions return the complex conjugate value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcarg\fR\^(\|)", +.IR "\fIcimag\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)", +.IR "\fIcreal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/connect.3p b/man-pages-posix-2013-a/man3p/connect.3p new file mode 100644 index 0000000..bff7364 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/connect.3p @@ -0,0 +1,301 @@ +'\" et +.TH CONNECT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +connect +\(em connect a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +int connect(int \fIsocket\fP, const struct sockaddr *\fIaddress\fP, + socklen_t \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIconnect\fR() +function shall attempt to make a connection on a connection-mode +socket or to set or reset the peer address of a connectionless-mode +socket. The function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the file descriptor associated with the socket. +.IP "\fIaddress\fR" 12 +Points to a +.BR sockaddr +structure containing the peer address. The length and format of the +address depend on the address family of the socket. +.IP "\fIaddress_len\fR" 12 +Specifies the length of the +.BR sockaddr +structure pointed to by the +.IR address +argument. +.P +If the socket has not already been bound to a local address, +\fIconnect\fR() +shall bind it to an address which, unless the socket's address family +is AF_UNIX, is an unused local address. +.P +If the initiating socket is not connection-mode, then +\fIconnect\fR() +shall set the socket's peer address, and no connection is made. For +SOCK_DGRAM sockets, the peer address identifies where all datagrams are +sent on subsequent +\fIsend\fR() +functions, and limits the remote sender for subsequent +\fIrecv\fR() +functions. If the +.IR sa_family +member of +.IR address +is AF_UNSPEC, the socket's peer address shall be reset. Note that despite +no connection being made, the term ``connected'' is used to describe a +connectionless-mode socket for which a peer address has been set. +.P +If the initiating socket is connection-mode, then +\fIconnect\fR() +shall attempt to establish a connection to the address specified by the +.IR address +argument. If the connection cannot be established immediately and +O_NONBLOCK is not set for the file descriptor for the socket, +\fIconnect\fR() +shall block for up to an unspecified timeout interval until the +connection is established. If the timeout interval expires before the +connection is established, +\fIconnect\fR() +shall fail and the connection attempt shall be aborted. If +\fIconnect\fR() +is interrupted by a signal that is caught while blocked waiting to +establish a connection, +\fIconnect\fR() +shall fail and set +.IR errno +to +.BR [EINTR] , +but the connection request shall not be aborted, and the connection +shall be established asynchronously. +.P +If the connection cannot be established immediately and O_NONBLOCK is +set for the file descriptor for the socket, +\fIconnect\fR() +shall fail and set +.IR errno +to +.BR [EINPROGRESS] , +but the connection request shall not be aborted, and the connection +shall be established asynchronously. Subsequent calls to +\fIconnect\fR() +for the same socket, before the connection is established, shall fail +and set +.IR errno +to +.BR [EALREADY] . +.P +When the connection has been established asynchronously, +\fIpselect\fR(), +\fIselect\fR(), +and +\fIpoll\fR() +shall indicate that the file descriptor for the socket is ready for +writing. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIconnect\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, +\fIconnect\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIconnect\fR() +function shall fail if: +.TP +.BR EADDRNOTAVAIL +.br +The specified address is not available from the local machine. +.TP +.BR EAFNOSUPPORT +.br +The specified address is not a valid address for the address family of +the specified socket. +.TP +.BR EALREADY +A connection request is already in progress for the specified socket. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNREFUSED +.br +The target address was not listening for connections or refused the +connection request. +.TP +.BR EINPROGRESS +O_NONBLOCK is set for the file descriptor for the socket and the +connection cannot be immediately established; the connection shall be +established asynchronously. +.TP +.BR EINTR +The attempt to establish a connection was interrupted by delivery of a +signal that was caught; the connection shall be established +asynchronously. +.TP +.BR EISCONN +The specified socket is connection-mode and is already connected. +.TP +.BR ENETUNREACH +.br +No route to the network is present. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EPROTOTYPE +The specified address has a different type than the socket bound to the +specified peer address. +.TP +.BR ETIMEDOUT +The attempt to connect timed out before a connection was made. +.P +If the address family of the socket is AF_UNIX, then +\fIconnect\fR() +shall fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in +.IR address . +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the pathname does not name an existing file or the +pathname is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix of the pathname in +.IR address +names an existing file that is neither a directory nor a symbolic link +to a directory, or the pathname in +.IR address +contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.P +The +\fIconnect\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP +.BR EADDRINUSE +Attempt to establish a connection that uses addresses that are already +in use. +.TP +.BR ECONNRESET +Remote host reset the connection request. +.TP +.BR EHOSTUNREACH +.br +The destination host cannot be reached (probably because the host is +down or a remote router cannot reach it). +.TP +.BR EINVAL +The +.IR address_len +argument is not a valid length for the address family; or invalid +address family in the +.BR sockaddr +structure. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the pathname in +.IR address . +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENETDOWN +The local network interface used to reach the destination is down. +.TP +.BR ENOBUFS +No buffer space is available. +.TP +.BR EOPNOTSUPP +The socket is listening and cannot be connected. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If +\fIconnect\fR() +fails, the state of the socket is unspecified. Conforming applications +should close the file descriptor and create a new socket before +attempting to reconnect. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/copysign.3p b/man-pages-posix-2013-a/man3p/copysign.3p new file mode 100644 index 0000000..082437a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/copysign.3p @@ -0,0 +1,74 @@ +'\" et +.TH COPYSIGN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +copysign, +copysignf, +copysignl +\(em number manipulation function +.SH SYNOPSIS +.LP +.nf +#include +.P +double copysign(double \fIx\fP, double \fIy\fP); +float copysignf(float \fIx\fP, float \fIy\fP); +long double copysignl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall produce a value with the magnitude of +.IR x +and the sign of +.IR y . +On implementations that represent a signed zero but do not treat +negative zero consistently in arithmetic operations, these functions +regard the sign of zero as positive. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value with +the magnitude of +.IR x +and the sign of +.IR y . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cos.3p b/man-pages-posix-2013-a/man3p/cos.3p new file mode 100644 index 0000000..e4c2fd1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cos.3p @@ -0,0 +1,126 @@ +'\" et +.TH COS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cos, +cosf, +cosl +\(em cosine function +.SH SYNOPSIS +.LP +.nf +#include +.P +double cos(double \fIx\fP); +float cosf(float \fIx\fP); +long double cosl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the cosine of their argument +.IR x , +measured in radians. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the cosine of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, the value 1.0 shall be returned. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Taking the Cosine of a 45-Degree Angle" +.sp +.RS 4 +.nf +\fB +#include +\&... +double radians = 45 * M_PI / 180; +double result; +\&... +result = cos(radians); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +These functions may lose accuracy when their argument is near an odd +multiple of \(*p/2 or is far from 0. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIacos\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsin\fR\^(\|)", +.IR "\fItan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cosh.3p b/man-pages-posix-2013-a/man3p/cosh.3p new file mode 100644 index 0000000..73d8350 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cosh.3p @@ -0,0 +1,124 @@ +'\" et +.TH COSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cosh, +coshf, +coshl +\(em hyperbolic cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double cosh(double \fIx\fP); +float coshf(float \fIx\fP); +long double coshl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the hyperbolic cosine of their argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the hyperbolic +cosine of +.IR x . +.P +If the correct value would cause overflow, a range error shall occur +and +\fIcosh\fR(), +\fIcoshf\fR(), +and +\fIcoshl\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, the value 1.0 shall be returned. +.P +If +.IR x +is \(+-Inf, +Inf shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result would cause an overflow. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.P +For IEEE\ Std\ 754\(hy1985 +.BR double , +710.5 < |\fIx\fP| implies that +.IR cosh (\c +.IR x ) +has overflowed. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIacosh\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsinh\fR\^(\|)", +.IR "\fItanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cosl.3p b/man-pages-posix-2013-a/man3p/cosl.3p new file mode 100644 index 0000000..2ee1234 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cosl.3p @@ -0,0 +1,38 @@ +'\" et +.TH COSL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cosl +\(em cosine function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double cosl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcos\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cpow.3p b/man-pages-posix-2013-a/man3p/cpow.3p new file mode 100644 index 0000000..34eb021 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cpow.3p @@ -0,0 +1,68 @@ +'\" et +.TH CPOW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cpow, +cpowf, +cpowl +\(em complex power functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cpow(double complex \fIx\fP, double complex \fIy\fP); +float complex cpowf(float complex \fIx\fP, float complex \fIy\fP); +long double complex cpowl(long double complex \fIx\fP, + long double complex \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex power function +\fIx\s-3\uy\d\s+3\fR, with a branch cut for the first parameter along +the negative real axis. +.SH "RETURN VALUE" +These functions shall return the complex power function value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcabs\fR\^(\|)", +.IR "\fIcsqrt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/cproj.3p b/man-pages-posix-2013-a/man3p/cproj.3p new file mode 100644 index 0000000..f521162 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/cproj.3p @@ -0,0 +1,104 @@ +'\" et +.TH CPROJ "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cproj, +cprojf, +cprojl +\(em complex projection functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cproj(double complex \fIz\fP); +float complex cprojf(float complex \fIz\fP); +long double complex cprojl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute a projection of +.IR z +onto the Riemann sphere: +.IR z +projects to +.IR z , +except that all complex infinities (even those with one infinite part +and one NaN part) project to positive infinity on the real axis. If +.IR z +has an infinite part, then +.IR cproj (\c +.IR z ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +INFINITY + I * copysign(0.0, cimag(z)) +.fi \fR +.P +.RE +.SH "RETURN VALUE" +These functions shall return the value of the projection onto the +Riemann sphere. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Two topologies are commonly used in complex mathematics: the complex +plane with its continuum of infinities, and the Riemann sphere with its +single infinity. The complex plane is better suited for transcendental +functions, the Riemann sphere for algebraic functions. The complex +types with their multiplicity of infinities provide a useful (though +imperfect) model for the complex plane. The +\fIcproj\fR() +function helps model the Riemann sphere by mapping all infinities to +one, and should be used just before any operation, especially +comparisons, that might give spurious results for any of the other +infinities. Note that a complex value with one infinite part and one +NaN part is regarded as an infinity, not a NaN, because if one part is +infinite, the complex value is infinite independent of the value of the +other part. For the same reason, +\fIcabs\fR() +returns an infinity if its argument has an infinite part and a NaN +part. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcarg\fR\^(\|)", +.IR "\fIcimag\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcreal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/creal.3p b/man-pages-posix-2013-a/man3p/creal.3p new file mode 100644 index 0000000..0953fd7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/creal.3p @@ -0,0 +1,79 @@ +'\" et +.TH CREAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +creal, +crealf, +creall +\(em complex real functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double creal(double complex \fIz\fP); +float crealf(float complex \fIz\fP); +long double creall(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the real part of +.IR z . +.SH "RETURN VALUE" +These functions shall return the real part value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For a variable +.IR z +of type +.BR complex : +.sp +.RS 4 +.nf +\fB +z == creal(z) + cimag(z)*I +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcarg\fR\^(\|)", +.IR "\fIcimag\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/creat.3p b/man-pages-posix-2013-a/man3p/creat.3p new file mode 100644 index 0000000..e97c847 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/creat.3p @@ -0,0 +1,104 @@ +'\" et +.TH CREAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +creat +\(em create a new file or rewrite an existing one +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int creat(const char *\fIpath\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIcreat\fR() +function shall behave as if it is implemented as follows: +.sp +.RS 4 +.nf +\fB +int creat(const char *path, mode_t mode) +{ + return open(path, O_WRONLY|O_CREAT|O_TRUNC, mode); +} +.fi \fR +.P +.RE +.SH "RETURN VALUE" +Refer to +.IR "\fIopen\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIopen\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a File" +.P +The following example creates the file +.BR /tmp/file +with read and write permissions for the file owner and read permission +for group and others. The resulting file descriptor is assigned to the +.IR fd +variable. +.sp +.RS 4 +.nf +\fB +#include +\&... +int fd; +mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; +char *pathname = "/tmp/file"; +\&... +fd = creat(pathname, mode); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIcreat\fR() +function is redundant. Its services are also provided by the +\fIopen\fR() +function. It has been included primarily for historical purposes since +many existing applications depend on it. It is best considered a part +of the C binding rather than a function that should be provided in +other languages. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImknod\fR\^(\|)", +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/crypt.3p b/man-pages-posix-2013-a/man3p/crypt.3p new file mode 100644 index 0000000..697bed3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/crypt.3p @@ -0,0 +1,155 @@ +'\" et +.TH CRYPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +crypt +\(em string encoding function +(\fBCRYPT\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +char *crypt(const char *\fIkey\fP, const char *\fIsalt\fP); +.fi +.SH DESCRIPTION +The +\fIcrypt\fR() +function is a string encoding function. The algorithm is +implementation-defined. +.P +The +.IR key +argument points to a string to be encoded. The +.IR salt +argument shall be a string of at least two bytes in length not +including the null character chosen from the set: +.sp +.RS 4 +.nf +\fB +a b c d e f g h i j k l m n o p q r s t u v w x y z +A B C D E F G H I J K L M N O P Q R S T U V W X Y Z +0 1 2 3 4 5 6 7 8 9 . / +.fi \fR +.P +.RE +.P +The first two bytes of this string may be used to perturb the +encoding algorithm. +.P +The return value of +\fIcrypt\fR() +points to static data that is overwritten by each call. +.P +The +\fIcrypt\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIcrypt\fR() +shall return a pointer to the encoded string. The first two bytes +of the returned value shall be those of the +.IR salt +argument. Otherwise, it shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIcrypt\fR() +function shall fail if: +.TP +.BR ENOSYS +The functionality is not supported on this implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Encoding Passwords" +.P +The following example finds a user database entry matching a particular +user name and changes the current password to a new password. The +\fIcrypt\fR() +function generates an encoded version of each password. The +first call to +\fIcrypt\fR() +produces an encoded version of the old password; that encoded password +is then compared to the password stored in the user database. The +second call to +\fIcrypt\fR() +encodes the new password before it is stored. +.P +The +\fIputpwent\fR() +function, used in the following example, is not part of POSIX.1\(hy2008. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +\&... +int valid_change; +int pfd; /* Integer for file descriptor returned by open(). */ +FILE *fpfd; /* File pointer for use in putpwent(). */ +struct passwd *p; +char user[100]; +char oldpasswd[100]; +char newpasswd[100]; +char savepasswd[100]; +\&... +valid_change = 0; +while ((p = getpwent()) != NULL) { + /* Change entry if found. */ + if (strcmp(p->pw_name, user) == 0) { + if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { + strcpy(savepasswd, crypt(newpasswd, user)); + p->pw_passwd = savepasswd; + valid_change = 1; + } + else { + fprintf(stderr, "Old password is not valid\en"); + } + } + /* Put passwd entry into ptmp. */ + putpwent(p, fpfd); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The values returned by this function need not be portable among +XSI-conformant systems. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIencrypt\fR\^(\|)", +.IR "\fIsetkey\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/csin.3p b/man-pages-posix-2013-a/man3p/csin.3p new file mode 100644 index 0000000..98c185c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/csin.3p @@ -0,0 +1,65 @@ +'\" et +.TH CSIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +csin, +csinf, +csinl +\(em complex sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex csin(double complex \fIz\fP); +float complex csinf(float complex \fIz\fP); +long double complex csinl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex sine of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex sine value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcasin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/csinh.3p b/man-pages-posix-2013-a/man3p/csinh.3p new file mode 100644 index 0000000..9cd401d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/csinh.3p @@ -0,0 +1,65 @@ +'\" et +.TH CSINH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +csinh, +csinhf, +csinhl +\(em complex hyperbolic sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex csinh(double complex \fIz\fP); +float complex csinhf(float complex \fIz\fP); +long double complex csinhl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex hyperbolic sine of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex hyperbolic sine value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcasinh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/csinl.3p b/man-pages-posix-2013-a/man3p/csinl.3p new file mode 100644 index 0000000..2c78758 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/csinl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CSINL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +csinl +\(em complex sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex csinl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcsin\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/csqrt.3p b/man-pages-posix-2013-a/man3p/csqrt.3p new file mode 100644 index 0000000..947a09a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/csqrt.3p @@ -0,0 +1,68 @@ +'\" et +.TH CSQRT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +csqrt, +csqrtf, +csqrtl +\(em complex square root functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex csqrt(double complex \fIz\fP); +float complex csqrtf(float complex \fIz\fP); +long double complex csqrtl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex square root of +.IR z , +with a branch cut along the negative real axis. +.SH "RETURN VALUE" +These functions shall return the complex square root value, in the +range of the right half-plane (including the imaginary axis). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcabs\fR\^(\|)", +.IR "\fIcpow\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ctan.3p b/man-pages-posix-2013-a/man3p/ctan.3p new file mode 100644 index 0000000..67525a0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ctan.3p @@ -0,0 +1,65 @@ +'\" et +.TH CTAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctan, +ctanf, +ctanl +\(em complex tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex ctan(double complex \fIz\fP); +float complex ctanf(float complex \fIz\fP); +long double complex ctanl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex tangent of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex tangent value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ctanh.3p b/man-pages-posix-2013-a/man3p/ctanh.3p new file mode 100644 index 0000000..f174d10 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ctanh.3p @@ -0,0 +1,65 @@ +'\" et +.TH CTANH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctanh, +ctanhf, +ctanhl +\(em complex hyperbolic tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex ctanh(double complex \fIz\fP); +float complex ctanhf(float complex \fIz\fP); +long double complex ctanhl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex hyperbolic tangent of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex hyperbolic tangent value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ctanl.3p b/man-pages-posix-2013-a/man3p/ctanl.3p new file mode 100644 index 0000000..ba2ee73 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ctanl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CTANL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctanl +\(em complex tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex ctanl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIctan\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ctermid.3p b/man-pages-posix-2013-a/man3p/ctermid.3p new file mode 100644 index 0000000..4fd8f2d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ctermid.3p @@ -0,0 +1,144 @@ +'\" et +.TH CTERMID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctermid +\(em generate a pathname for the controlling terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +char *ctermid(char *\fIs\fP); +.fi +.SH DESCRIPTION +The +\fIctermid\fR() +function shall generate a string that, when used as a pathname, +refers to the current controlling terminal for the current process. If +\fIctermid\fR() +returns a pathname, access to the file is not guaranteed. +.P +The +\fIctermid\fR() +function need not be thread-safe if called with a NULL parameter. +.SH "RETURN VALUE" +If +.IR s +is a null pointer, the string shall be generated in an area that may be +static, the address of which shall be returned. The application shall +not modify the string returned. The returned pointer might be invalidated +or the string content might be overwritten by a subsequent call to +\fIctermid\fR(). +If +.IR s +is not a null pointer, +.IR s +is assumed to point to a character array of at least L_ctermid bytes; +the string is placed in this array and the value of +.IR s +shall be returned. The symbolic constant L_ctermid is defined in +.IR , +and shall have a value greater than 0. +.P +The +\fIctermid\fR() +function shall return an empty string if the pathname that would refer +to the controlling terminal cannot be determined, or if the function is +unsuccessful. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Determining the Controlling Terminal for the Current Process" +.P +The following example returns a pointer to a string that identifies the +controlling terminal for the current process. The pathname for the +terminal is stored in the array pointed to by the +.IR ptr +argument, which has a size of L_ctermid bytes, as indicated by the +.IR term +argument. +.sp +.RS 4 +.nf +\fB +#include +\&... +char term[L_ctermid]; +char *ptr; +.P +ptr = ctermid(term); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The difference between +\fIctermid\fR() +and +\fIttyname\fR() +is that +\fIttyname\fR() +must be handed a file descriptor and return a path of the terminal +associated with that file descriptor, while +\fIctermid\fR() +returns a string (such as +.BR \(dq/dev/tty\(dq ) +that refers to the current controlling terminal if used as a +pathname. +.SH RATIONALE +L_ctermid +must be defined appropriately for a given implementation and must be +greater than zero so that array declarations using it are accepted by +the compiler. The value includes the terminating null byte. +.P +Conforming applications that use multiple threads cannot call +\fIctermid\fR() +with NULL as the parameter. If +.IR s +is not NULL, the +\fIctermid\fR() +function generates a string that, when used as a pathname, refers to +the current controlling terminal for the current process. If +.IR s +is NULL, the return value of +\fIctermid\fR() +is undefined. +.P +There is no additional burden on the programmer\(emchanging to use a +hypothetical thread-safe version of +\fIctermid\fR() +along with allocating a buffer is more of a burden than merely +allocating a buffer. Application code should not assume that the +returned string is short, as some implementations have more than two +pathname components before reaching a logical device name. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIttyname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ctime.3p b/man-pages-posix-2013-a/man3p/ctime.3p new file mode 100644 index 0000000..00681b8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ctime.3p @@ -0,0 +1,173 @@ +'\" et +.TH CTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctime, +ctime_r +\(em convert a time value to a date and time string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *ctime(const time_t *\fIclock\fP); +char *ctime_r(const time_t *\fIclock\fP, char *\fIbuf\fP); +.fi +.SH DESCRIPTION +For +\fIctime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIctime\fR() +function shall convert the time pointed to by +.IR clock , +representing time in seconds since the Epoch, to local time in the form +of a string. It shall be equivalent to: +.sp +.RS 4 +.nf +\fB +asctime(localtime(clock)) +.fi \fR +.P +.RE +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIctime\fR() +function need not be thread-safe. +.P +The +\fIctime_r\fR() +function shall convert the calendar time pointed to by +.IR clock +to local time in exactly the same form as +\fIctime\fR() +and put the string into the array pointed to by +.IR buf +(which shall be at least 26 bytes in size) and return +.IR buf . +.P +Unlike +\fIctime\fR(), +the +\fIctime_r\fR() +function is not required to set +.IR tzname . +If +\fIctime_r\fR() +does not set +.IR tzname , +it shall not set +.IR daylight +and shall not set +.IR timezone . +.SH "RETURN VALUE" +The +\fIctime\fR() +function shall return the pointer returned by +\fIasctime\fR() +with that broken-down time as an argument. +.P +Upon successful completion, +\fIctime_r\fR() +shall return a pointer to the string pointed to by +.IR buf . +When an error is encountered, a null pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are included only for compatibility with older +implementations. They have undefined behavior if the resulting string +would be too long, so the use of these functions should be discouraged. +On implementations that do not detect output string length overflow, it +is possible to overflow the output buffers in such a way as to cause +applications to fail, or possible system security violations. Also, +these functions do not support localized date and time formats. To +avoid these problems, applications should use +\fIstrftime\fR() +to generate strings from broken-down times. +.P +Values for the broken-down time structure can be obtained by calling +\fIgmtime\fR() +or +\fIlocaltime\fR(). +.P +The +\fIctime_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.P +Attempts to use +\fIctime\fR() +or +\fIctime_r\fR() +for times before the Epoch or for times beyond the year 9999 produce +undefined results. Refer to +.IR "\fIasctime\fR\^(\|)". +.SH RATIONALE +The standard developers decided to mark the +\fIctime\fR() +and +\fIctime_r\fR() +functions obsolescent even though they are in the ISO\ C standard due to the +possibility of buffer overflow. The ISO\ C standard also provides the +\fIstrftime\fR() +function which can be used to avoid these problems. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/daylight.3p b/man-pages-posix-2013-a/man3p/daylight.3p new file mode 100644 index 0000000..e5a0836 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/daylight.3p @@ -0,0 +1,38 @@ +'\" et +.TH DAYLIGHT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +daylight +\(em daylight savings time flag +.SH SYNOPSIS +.LP +.nf +#include +.P +extern int daylight; +.fi +.SH DESCRIPTION +Refer to +.IR "\fItzset\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dbm_clearerr.3p b/man-pages-posix-2013-a/man3p/dbm_clearerr.3p new file mode 100644 index 0000000..4047ec5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dbm_clearerr.3p @@ -0,0 +1,403 @@ +'\" et +.TH DBM_CLEARERR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dbm_clearerr, +dbm_close, +dbm_delete, +dbm_error, +dbm_fetch, +dbm_firstkey, +dbm_nextkey, +dbm_open, +dbm_store +\(em database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int dbm_clearerr(DBM *\fIdb\fP); +void dbm_close(DBM *\fIdb\fP); +int dbm_delete(DBM *\fIdb\fP, datum \fIkey\fP); +int dbm_error(DBM *\fIdb\fP); +datum dbm_fetch(DBM *\fIdb\fP, datum \fIkey\fP); +datum dbm_firstkey(DBM *\fIdb\fP); +datum dbm_nextkey(DBM *\fIdb\fP); +DBM *dbm_open(const char *\fIfile\fP, int \fIopen_flags\fP, mode_t \fIfile_mode\fP); +int dbm_store(DBM *\fIdb\fP, datum \fIkey\fP, datum \fIcontent\fP, int \fIstore_mode\fP); +.fi +.SH DESCRIPTION +These functions create, access, and modify a database. +.P +A +.BR datum +consists of at least two members, +.IR dptr +and +.IR dsize . +The +.IR dptr +member points to an object that is +.IR dsize +bytes in length. Arbitrary binary data, as well as character strings, +may be stored in the object pointed to by +.IR dptr . +.P +A database shall be stored in one or two files. When one file is used, +the name of the database file shall be formed by appending the suffix +.BR .db +to the +.IR file +argument given to +\fIdbm_open\fR(). +When two files are used, the names of the database files shall be +formed by appending the suffixes +.BR .dir +and +.BR .pag +respectively to the +.IR file +argument. +.P +The +\fIdbm_open\fR() +function shall open a database. The +.IR file +argument to the function is the pathname of the database. The +.IR open_flags +argument has the same meaning as the +.IR flags +argument of +\fIopen\fR() +except that a database opened for write-only access opens the files for +read and write access and the behavior of the O_APPEND flag +is unspecified. The +.IR file_mode +argument has the same meaning as the third argument of +\fIopen\fR(). +.P +The +\fIdbm_open\fR() +function need not accept pathnames longer than +{PATH_MAX}\(mi4 +bytes (including the terminating null), or pathnames with a last +component longer than +{NAME_MAX}\(mi4 +bytes (excluding the terminating null). +.P +The +\fIdbm_close\fR() +function shall close a database. The application shall ensure that +argument +.IR db +is a pointer to a +.BR dbm +structure that has been returned from a call to +\fIdbm_open\fR(). +.P +These database functions shall support an internal block size large +enough to support key/content pairs of at least 1\|023 bytes. +.P +The +\fIdbm_fetch\fR() +function shall read a record from a database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +The argument +.IR key +is a +.BR datum +that has been initialized by the application to the value of +the key that matches the key of the record the program is fetching. +.P +The +\fIdbm_store\fR() +function shall write a record to a database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +The argument +.IR key +is a +.BR datum +that has been initialized by the application to the value of the key +that identifies (for subsequent reading, writing, or deleting) the +record the application is writing. The argument +.IR content +is a +.BR datum +that has been initialized by the application to the value of the record +the program is writing. The argument +.IR store_mode +controls whether +\fIdbm_store\fR() +replaces any pre-existing record that has the same key that is +specified by the +.IR key +argument. The application shall set +.IR store_mode +to either DBM_INSERT or DBM_REPLACE. If the database contains a record +that matches the +.IR key +argument and +.IR store_mode +is DBM_REPLACE, the existing record shall be replaced with the new +record. If the database contains a record that matches the +.IR key +argument and +.IR store_mode +is DBM_INSERT, the existing record shall be left unchanged and the new +record ignored. If the database does not contain a record that matches +the +.IR key +argument and +.IR store_mode +is either DBM_INSERT or DBM_REPLACE, the new record shall be inserted +in the database. +.P +If the sum of a key/content pair exceeds the internal block size, the +result is unspecified. Moreover, the application shall ensure that all +key/content pairs that hash together fit on a single block. The +\fIdbm_store\fR() +function shall return an error in the event that a disk block fills +with inseparable data. +.P +The +\fIdbm_delete\fR() +function shall delete a record and its key from the database. The +argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +The argument +.IR key +is a +.BR datum +that has been initialized by the application to the value of +the key that identifies the record the program is deleting. +.P +The +\fIdbm_firstkey\fR() +function shall return the first key in the database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +.P +The +\fIdbm_nextkey\fR() +function shall return the next key in the database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +The application shall ensure that the +\fIdbm_firstkey\fR() +function is called before calling +\fIdbm_nextkey\fR(). +Subsequent calls to +\fIdbm_nextkey\fR() +return the next key until all of the keys in the database have been +returned. +.P +The +\fIdbm_error\fR() +function shall return the error condition of the database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +.P +The +\fIdbm_clearerr\fR() +function shall clear the error condition of the database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +.P +The +.IR dptr +pointers returned by these functions may point into static storage that +may be changed by subsequent calls. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +The +\fIdbm_store\fR() +and +\fIdbm_delete\fR() +functions shall return 0 when they succeed and a negative value when +they fail. +.P +The +\fIdbm_store\fR() +function shall return 1 if it is called with a +.IR flags +value of DBM_INSERT and the function finds an existing record with the +same key. +.P +The +\fIdbm_error\fR() +function shall return 0 if the error condition is not set and return a +non-zero value if the error condition is set. +.P +The return value of +\fIdbm_clearerr\fR() +is unspecified. +.P +The +\fIdbm_firstkey\fR() +and +\fIdbm_nextkey\fR() +functions shall return a key +.BR datum . +When the end of the database is reached, the +.IR dptr +member of the key is a null pointer. If an error is detected, the +.IR dptr +member of the key shall be a null pointer and the error condition of +the database shall be set. +.P +The +\fIdbm_fetch\fR() +function shall return a content +.BR datum . +If no record in the database matches the key or if an error condition +has been detected in the database, the +.IR dptr +member of the content shall be a null pointer. +.P +The +\fIdbm_open\fR() +function shall return a pointer to a database structure. If an error +is detected during the operation, +\fIdbm_open\fR() +shall return a (\c +.BR "DBM *" )0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The following code can be used to traverse the database: +.sp +.RS 4 +.nf +\fB +for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) +.fi \fR +.P +.RE +.P +The +.IR dbm_ * +functions provided in this library should not be confused in any way +with those of a general-purpose database management system. These +functions do not provide for multiple search keys per entry, they do +not protect against multi-user access (in other words they do not lock +records or files), and they do not provide the many other useful +database functions that are found in more robust database management +systems. Creating and updating databases by use of these functions is +relatively slow because of data copies that occur upon hash +collisions. These functions are useful for applications requiring fast +lookup of relatively static information that is to be indexed by a +single key. +.P +Note that a strictly conforming application is extremely limited by +these functions: since there is no way to determine that the keys in +use do not all hash to the same value (although that would be rare), a +strictly conforming application cannot be guaranteed that it can store +more than one block's worth of data in the database. As long as a key +collision does not occur, additional data may be stored, but because +there is no way to determine whether an error is due to a key collision +or some other error condition (\c +\fIdbm_error\fR() +being effectively a Boolean), once an error is detected, the +application is effectively limited to guessing what the error might be +if it wishes to continue using these functions. +.P +The +\fIdbm_delete\fR() +function need not physically reclaim file space, although it does make +it available for reuse by the database. +.P +After calling +\fIdbm_store\fR() +or +\fIdbm_delete\fR() +during a pass through the keys by +\fIdbm_firstkey\fR() +and +\fIdbm_nextkey\fR(), +the application should reset the database by calling +\fIdbm_firstkey\fR() +before again calling +\fIdbm_nextkey\fR(). +The contents of these files are unspecified and may not be portable. +.P +Applications should take care that database pathname arguments +specified to +\fIdbm_open\fR() +are not prefixes of unrelated files. This might be done, for example, +by placing databases in a separate directory. +.P +Since some implementations use three characters for a suffix and others +use four characters for a suffix, applications should ensure that the +maximum portable pathname length passed to +\fIdbm_open\fR() +is no greater than +{PATH_MAX}\(mi4 +bytes, with the last component of the pathname no greater than +{NAME_MAX}\(mi4 +bytes. +.SH RATIONALE +Previously the standard required the database to be stored in two +files, one file being a directory containing a bitmap of keys and +having +.BR .dir +as its suffix. The second file containing all data and having +.BR .pag +as its suffix. This has been changed not to specify the use of the +files and to allow newer implementations of the Berkeley DB interface +using a single file that have evolved while remaining compatible with +the application programming interface. The standard developers +considered removing the specific suffixes altogether but decided to +retain them so as not to pollute the application file name space more +than necessary and to allow for portable backups of the database. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/difftime.3p b/man-pages-posix-2013-a/man3p/difftime.3p new file mode 100644 index 0000000..7027e44 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/difftime.3p @@ -0,0 +1,78 @@ +'\" et +.TH DIFFTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +difftime +\(em compute the difference between two calendar time values +.SH SYNOPSIS +.LP +.nf +#include +.P +double difftime(time_t \fItime1\fP, time_t \fItime0\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIdifftime\fR() +function shall compute the difference between two calendar times (as +returned by +\fItime\fR()): +.IR time 1\(mi +.IR time 0. +.SH "RETURN VALUE" +The +\fIdifftime\fR() +function shall return the difference expressed in seconds as a type +.BR double . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dirfd.3p b/man-pages-posix-2013-a/man3p/dirfd.3p new file mode 100644 index 0000000..a3f1b5d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dirfd.3p @@ -0,0 +1,130 @@ +'\" et +.TH DIRFD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dirfd +\(em extract the file descriptor used by a DIR stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int dirfd(DIR *\fIdirp\fP); +.fi +.SH DESCRIPTION +The +\fIdirfd\fR() +function shall return a file descriptor referring to the same directory +as the +.IR dirp +argument. This file descriptor shall be closed by a call to +\fIclosedir\fR(). +If any attempt is made to close the file descriptor, or to modify the +state of the associated description, other than by means of +\fIclosedir\fR(), +\fIreaddir\fR(), +\fIreaddir_r\fR(), +\fIrewinddir\fR(), +or +\fIseekdir\fR(), +the behavior is undefined. +.SH "RETURN VALUE" +Upon successful completion, the +\fIdirfd\fR() +function shall return an integer which contains a file descriptor for +the stream pointed to by +.IR dirp . +Otherwise, it shall return \(mi1 and may set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIdirfd\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR dirp +argument does not refer to a valid directory stream. +.TP +.BR ENOTSUP +The implementation does not support the association of a file +descriptor with a directory. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIdirfd\fR() +function is intended to be a mechanism by which an application may +obtain a file descriptor to use for the +\fIfchdir\fR() +function. +.SH RATIONALE +This interface was introduced because the Base Definitions volume of POSIX.1\(hy2008 does not make public +the +.BR DIR +data structure. Applications tend to use the +\fIfchdir\fR() +function on the file descriptor returned by this interface, and this +has proven useful for security reasons; in particular, it is a better +technique than others where directory names might change. +.P +The description uses the term ``a file descriptor'' rather than ``the +file descriptor''. The implication intended is that an implementation +that does not use an +.IR fd +for +\fIopendir\fR() +could still +\fIopen\fR() +the directory to implement the +\fIdirfd\fR() +function. Such a descriptor must be closed later during a call to +\fIclosedir\fR(). +.P +An implementation that does not support file descriptors referring to +directories may fail with +.BR [ENOTSUP] . +.P +If it is necessary to allocate an +.IR fd +to be returned by +\fIdirfd\fR(), +it should be done at the time of a call to +\fIopendir\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIfchdir\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfileno\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dirname.3p b/man-pages-posix-2013-a/man3p/dirname.3p new file mode 100644 index 0000000..41e8bd5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dirname.3p @@ -0,0 +1,162 @@ +'\" et +.TH DIRNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dirname +\(em report the parent directory name of a file pathname +.SH SYNOPSIS +.LP +.nf +#include +.P +char *dirname(char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIdirname\fR() +function shall take a pointer to a character string that contains a +pathname, and return a pointer to a string that is a pathname of the +parent directory of that file. Trailing +.BR '/' +characters in the path are not counted as part of the path. +.P +If +.IR path +does not contain a +.BR '/' , +then +\fIdirname\fR() +shall return a pointer to the string +.BR \(dq.\(dq . +If +.IR path +is a null pointer or points to an empty string, +\fIdirname\fR() +shall return a pointer to the string +.BR \(dq.\(dq . +.P +The +\fIdirname\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIdirname\fR() +function shall return a pointer to a string that is the parent +directory of +.IR path . +If +.IR path +is a null pointer or points to an empty string, a pointer to a string +.BR \(dq.\(dq +is returned. +.P +The +\fIdirname\fR() +function may modify the string pointed to by +.IR path , +and may return a pointer to internal storage. The returned pointer might +be invalidated or the storage might be overwritten by a subsequent call to +\fIdirname\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following code fragment reads a pathname, changes the current +working directory to the parent directory, and opens the file. +.sp +.RS 4 +.nf +\fB +char *path = NULL, *pathcopy; +size_t buflen = 0; +ssize_t linelen = 0; +int fd; +.P +linelen = getline(&path, &buflen, stdin); +.P +path[linelen-1] = 0; +pathcopy = strdup(path); +if (chdir(dirname(pathcopy)) < 0) { + ... +} +if ((fd = open(basename(path), O_RDONLY)) >= 0) { + ... + close (fd); +} +\&... +free (pathcopy); +free (path); +.fi \fR +.P +.RE +.SS "Sample Input and Output Strings for dirname(\|)" +.P +In the following table, the input string is the value pointed to by +.IR path , +and the output string is the return value of the +\fIdirname\fR() +function. +.TS +center tab(!) box; +cB | cB +lf5 | lf5. +Input String!Output String +_ +"/usr/lib"!"/usr" +"/usr/"!"/" +"usr"!"." +"/"!"/" +"."!"." +".."!"." +.TE +.SH "APPLICATION USAGE" +The +\fIdirname\fR() +and +\fIbasename\fR() +functions together yield a complete pathname. The expression +\fIdirname\fP\^(\fIpath\fP) obtains the pathname of the directory where +\fIbasename\fP\^(\fIpath\fP) is found. +.P +Since the meaning of the leading +.BR \(dq//\(dq +is implementation-defined, +.IR dirname ("\c +.BR //foo ") +may return either +.BR \(dq//\(dq +or +.BR '/' +(but nothing else). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbasename\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/div.3p b/man-pages-posix-2013-a/man3p/div.3p new file mode 100644 index 0000000..5dc211d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/div.3p @@ -0,0 +1,88 @@ +'\" et +.TH DIV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +div +\(em compute the quotient and remainder of an integer division +.SH SYNOPSIS +.LP +.nf +#include +.P +div_t div(int \fInumer\fP, int \fIdenom\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIdiv\fR() +function shall compute the quotient and remainder of the division +of the numerator +.IR numer +by the denominator +.IR denom . +If the division is inexact, the resulting quotient is the integer of +lesser magnitude that is the nearest to the algebraic quotient. If the +result cannot be represented, the behavior is undefined; otherwise, +.IR quot *\c +.IR denom +\c +.IR rem +shall equal +.IR numer . +.SH "RETURN VALUE" +The +\fIdiv\fR() +function shall return a structure of type +.BR div_t , +comprising both the quotient and the remainder. The structure includes +the following members, in any order: +.sp +.RS 4 +.nf +\fB +int quot; /* quotient */ +int rem; /* remainder */ +.fi \fR +.P +.RE +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIldiv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dlclose.3p b/man-pages-posix-2013-a/man3p/dlclose.3p new file mode 100644 index 0000000..063ab5e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dlclose.3p @@ -0,0 +1,141 @@ +'\" et +.TH DLCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dlclose +\(em close a symbol table handle +.SH SYNOPSIS +.LP +.nf +#include +.P +int dlclose(void *\fIhandle\fP); +.fi +.SH DESCRIPTION +The +\fIdlclose\fR() +function shall inform the system that the symbol table handle specified by +.IR handle +is no longer needed by the application. +.P +An application writer may use +\fIdlclose\fR() +to make a statement of intent on the part of the process, but this +statement does not create any requirement upon the implementation. When +the symbol table handle is closed, the implementation may unload the +executable object files that were loaded by +\fIdlopen\fR() +when the symbol table handle was opened and those that were loaded by +\fIdlsym\fR() +when using the symbol table handle identified by +.IR handle . +.P +Once a symbol table handle has been closed, an application should assume +that any symbols (function identifiers and data object identifiers) +made visible using +.IR handle , +are no longer available to the process. +.P +Although a +\fIdlclose\fR() +operation is not required to remove any functions or data objects from +the address space, neither is an implementation prohibited from doing +so. The only restriction on such a removal is that no function nor data +object shall be removed to which references have been relocated, until +or unless all such references are removed. For instance, an executable +object file that had been loaded with a +\fIdlopen\fR() +operation specifying the RTLD_GLOBAL flag might provide a target for +dynamic relocations performed in the processing of other relocatable +objects\(emin such environments, an application may assume that no +relocation, once made, shall be undone or remade unless the executable +object file containing the relocated object has itself been removed. +.SH "RETURN VALUE" +If the referenced symbol table handle was successfully closed, +\fIdlclose\fR() +shall return 0. If +.IR handle +does not refer to an open symbol table handle or if the symbol table +handle could not be closed, +\fIdlclose\fR() +shall return a non-zero value. More detailed diagnostic information +shall be available through +\fIdlerror\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example illustrates use of +\fIdlopen\fR() +and +\fIdlclose\fR(): +.sp +.RS 4 +.nf +\fB +#include +int eret; +void *mylib; +\&... +/* Open a dynamic library and then close it ... */ +mylib = dlopen("mylib.so", RTLD_LOCAL | RTLD_LAZY); +\&... +eret = dlclose(mylib); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +A conforming application should employ a symbol table handle returned +from a +\fIdlopen\fR() +invocation only within a given scope bracketed by a +\fIdlopen\fR() +operation and the corresponding +\fIdlclose\fR() +operation. Implementations are free to use reference counting or other +techniques such that multiple calls to +\fIdlopen\fR() +referencing the same executable object file may return a pointer to the +same data object as the symbol table handle. +.P +Implementations are also free to re-use a handle. For these reasons, +the value of a handle must be treated as an opaque data type by the +application, used only in calls to +\fIdlsym\fR() +and +\fIdlclose\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdlerror\fR\^(\|)", +.IR "\fIdlopen\fR\^(\|)", +.IR "\fIdlsym\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dlerror.3p b/man-pages-posix-2013-a/man3p/dlerror.3p new file mode 100644 index 0000000..dce70ff --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dlerror.3p @@ -0,0 +1,109 @@ +'\" et +.TH DLERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dlerror +\(em get diagnostic information +.SH SYNOPSIS +.LP +.nf +#include +.P +char *dlerror(void); +.fi +.SH DESCRIPTION +The +\fIdlerror\fR() +function shall return a null-terminated character string (with no +trailing +) +that describes the last error that occurred during dynamic linking +processing. If no dynamic linking errors have occurred since the last +invocation of +\fIdlerror\fR(), +\fIdlerror\fR() +shall return NULL. +Thus, invoking +\fIdlerror\fR() +a second time, immediately following a prior invocation, shall result +in NULL being returned. +.P +It is implementation-defined whether or not the +\fIdlerror\fR() +function is thread-safe. A thread-safe implementation shall return only +errors that occur on the current thread. +.SH "RETURN VALUE" +If successful, +\fIdlerror\fR() +shall return a null-terminated character string; otherwise, NULL +shall be returned. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIdlerror\fR() +in the same thread (if +\fIdlerror\fR() +is thread-safe) or in any thread (if +\fIdlerror\fR() +is not thread-safe). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example prints out the last dynamic linking error: +.sp +.RS 4 +.nf +\fB +\&... +#include +.P +char *errstr; +.P +errstr = dlerror(); +if (errstr != NULL) + printf ("A dynamic linking error occurred: (%s)\en", errstr); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Depending on the application environment with respect to asynchronous +execution events, such as signals or other asynchronous computation +sharing the address space, conforming applications should use a critical +section to retrieve the error pointer and buffer. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdlclose\fR\^(\|)", +.IR "\fIdlopen\fR\^(\|)", +.IR "\fIdlsym\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dlopen.3p b/man-pages-posix-2013-a/man3p/dlopen.3p new file mode 100644 index 0000000..18f854c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dlopen.3p @@ -0,0 +1,268 @@ +'\" et +.TH DLOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dlopen +\(em open a symbol table handle +.SH SYNOPSIS +.LP +.nf +#include +.P +void *dlopen(const char *\fIfile\fP, int \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIdlopen\fR() +function shall make the symbols (function identifiers and data object +identifiers) in the executable object file specified by +.IR file +available to the calling program. +.P +The class of executable object files eligible for this operation and +the manner of their construction are implementation-defined, though +typically such files are shared libraries or programs. +.P +Implementations may permit the construction of embedded dependencies in +executable object files. In such cases, a +\fIdlopen\fR() +operation shall load those dependencies in addition to the executable +object file specified by +.IR file . +Implementations may also impose specific constraints on the construction +of programs that can employ +\fIdlopen\fR() +and its related services. +.P +A successful +\fIdlopen\fR() +shall return a symbol table handle which the caller may use on subsequent +calls to +\fIdlsym\fR() +and +\fIdlclose\fR(). +.P +The value of this symbol table handle should not be interpreted in any +way by the caller. +.P +The +.IR file +argument is used to construct a pathname to the executable object file. If +.IR file +contains a + +character, the +.IR file +argument is used as the pathname for the file. Otherwise, +.IR file +is used in an implementation-defined manner to yield a pathname. +.P +If +.IR file +is a null pointer, +\fIdlopen\fR() +shall return a global symbol table handle for the currently running +process image. This symbol table handle shall provide access to the +symbols from an ordered set of executable object files consisting of +the original program image file, any executable object files loaded +at program start-up as specified by that process file (for example, +shared libraries), and the set of executable object files loaded using +\fIdlopen\fR() +operations with the RTLD_GLOBAL flag. As the latter set of executable +object files can change during execution, the set of symbols made +available by this symbol table handle can also change dynamically. +.P +Only a single copy of an executable object file shall be brought into +the address space, even if +\fIdlopen\fR() +is invoked multiple times in reference to the executable object file, +and even if different pathnames are used to reference the executable +object file. +.P +The +.IR mode +parameter describes how +\fIdlopen\fR() +shall operate upon +.IR file +with respect to the processing of relocations and the scope of visibility +of the symbols provided within +.IR file . +When an executable object file is brought into the address space of a +process, it may contain references to symbols whose addresses are not +known until the executable object file is loaded. +.P +These references shall be relocated before the symbols can be accessed. The +.IR mode +parameter governs when these relocations take place and may have the +following values: +.IP RTLD_LAZY 12 +Relocations shall be performed at an implementation-defined time, +ranging from the time of the +\fIdlopen\fR() +call until the first reference to a given symbol occurs. Specifying +RTLD_LAZY should improve performance on implementations supporting dynamic +symbol binding since a process might not reference all of the symbols +in an executable object file. And, for systems supporting dynamic symbol +resolution for normal process execution, this behavior mimics the normal +handling of process execution. +.IP RTLD_NOW 12 +All necessary relocations shall be performed when the executable object +file is first loaded. This may waste some processing if relocations are +performed for symbols that are never referenced. This behavior may be +useful for applications that need to know that all symbols referenced +during execution will be available before +\fIdlopen\fR() +returns. +.P +Any executable object file loaded by +\fIdlopen\fR() +that requires relocations against global symbols can reference the symbols +in the original process image file, any executable object files loaded +at program start-up, from the initial process image itself, from any +other executable object file included in the same +\fIdlopen\fR() +invocation, and any executable object files that were loaded in any +\fIdlopen\fR() +invocation and which specified the RTLD_GLOBAL flag. To determine the +scope of visibility for the symbols loaded with a +\fIdlopen\fR() +invocation, the +.IR mode +parameter should be a bitwise-inclusive OR with one of the following +values: +.IP RTLD_GLOBAL 12 +The executable object file's symbols shall be made available for +relocation processing of any other executable object file. In addition, +symbol lookup using +.IR dlopen (NULL, mode ) +and an associated +\fIdlsym\fR() +allows executable object files loaded with this mode to be searched. +.IP RTLD_LOCAL 12 +The executable object file's symbols shall not be made available for +relocation processing of any other executable object file. +.P +If neither RTLD_GLOBAL nor RTLD_LOCAL is specified, the default behavior +is unspecified. +.P +If an executable object file is specified in multiple +\fIdlopen\fR() +invocations, +.IR mode +is interpreted at each invocation. +.P +If RTLD_NOW has been specified, all relocations shall have been completed +rendering further RTLD_NOW operations redundant and any further RTLD_LAZY +operations irrelevant. +.P +If RTLD_GLOBAL has been specified, the executable object file shall +maintain the RTLD_GLOBAL status regardless of any previous or future +specification of RTLD_LOCAL, as long as the executable object file +remains in the address space (see +.IR "\fIdlclose\fR\^(\|)"). +.P +Symbols introduced into the process image through calls to +\fIdlopen\fR() +may be used in relocation activities. Symbols so introduced may duplicate +symbols already defined by the program or previous +\fIdlopen\fR() +operations. To resolve the ambiguities such a situation might present, +the resolution of a symbol reference to symbol definition is based on a +symbol resolution order. Two such resolution orders are defined: load +order and dependency order. Load order establishes an ordering among +symbol definitions, such that the first definition loaded (including +definitions from the process image file and any dependent executable +object files loaded with it) has priority over executable object files +added later (by +\fIdlopen\fR()). +Load ordering is used in relocation processing. Dependency ordering uses +a breadth-first order starting with a given executable object file, +then all of its dependencies, then any dependents of those, iterating +until all dependencies are satisfied. With the exception of the global +symbol table handle obtained via a +\fIdlopen\fR() +operation with a null pointer as the +.IR file +argument, dependency ordering is used by the +\fIdlsym\fR() +function. Load ordering is used in +\fIdlsym\fR() +operations upon the global symbol table handle. +.P +When an executable object file is first made accessible via +\fIdlopen\fR(), +it and its dependent executable object files are added in dependency +order. Once all the executable object files are added, relocations are +performed using load order. Note that if an executable object file or +its dependencies had been previously loaded, the load and dependency +orders may yield different resolutions. +.P +The symbols introduced by +\fIdlopen\fR() +operations and available through +\fIdlsym\fR() +are at a minimum those which are exported as identifiers of global +scope by the executable object file. Typically, such identifiers shall +be those that were specified in (for example) C source code as having +.BR extern +linkage. The precise manner in which an implementation constructs +the set of exported symbols for an executable object file is +implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, +\fIdlopen\fR() +shall return a symbol table handle. If +.IR file +cannot be found, cannot be opened for reading, is not of an appropriate +executable object file format for processing by +\fIdlopen\fR(), +or if an error occurs during the process of loading +.IR file +or relocating its symbolic references, +\fIdlopen\fR() +shall return a null pointer. More detailed diagnostic information shall +be available through +\fIdlerror\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Refer to +.IR "\fIdlsym\fR\^(\|)". +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdlclose\fR\^(\|)", +.IR "\fIdlerror\fR\^(\|)", +.IR "\fIdlsym\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dlsym.3p b/man-pages-posix-2013-a/man3p/dlsym.3p new file mode 100644 index 0000000..f9c6692 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dlsym.3p @@ -0,0 +1,190 @@ +'\" et +.TH DLSYM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dlsym +\(em get the address of a symbol from a symbol table handle +.SH SYNOPSIS +.LP +.nf +#include +.P +void *dlsym(void *restrict \fIhandle\fP, const char *restrict \fIname\fP); +.fi +.SH DESCRIPTION +The +\fIdlsym\fR() +function shall obtain the address of a symbol (a function identifier or +a data object identifier) defined in the symbol table identified by the +.IR handle +argument. The +.IR handle +argument is a symbol table handle returned from a call to +\fIdlopen\fR() +(and which has not since been released by a call to +\fIdlclose\fR()), +and +.IR name +is the symbol's name as a character string. The return value from +\fIdlsym\fR(), +cast to a pointer to the type of the named symbol, can be used to call +(in the case of a function) or access the contents of (in the case of +a data object) the named symbol. +.P +The +\fIdlsym\fR() +function shall search for the named symbol in the symbol table +referenced by +.IR handle . +If the symbol table was created with lazy loading +(see RTLD_LAZY in +\fIdlopen\fR()), +load ordering shall be used in +\fIdlsym\fR() +operations to relocate executable object files needed to resolve the +symbol. The symbol resolution algorithm used shall be dependency order +as described in +\fIdlopen\fR(). +.P +The RTLD_DEFAULT and RTLD_NEXT symbolic constants (which may be defined in +.IR ) +are reserved for future use as special values that applications may be +allowed to use for +.IR handle . +.SH "RETURN VALUE" +Upon successful completion, if +.IR name +names a function identifier, +\fIdlsym\fR() +shall return the address of the function converted from type pointer to +function to type pointer to +.BR void ; +otherwise, +\fIdlsym\fR() +shall return the address of the data object associated with the data +object identifier named by +.IR name +converted from a pointer to the type of the data object to a pointer to +.BR void . +If +.IR handle +does not refer to a valid symbol table handle or if the symbol named by +.IR name +cannot be found in the symbol table associated with +.IR handle , +\fIdlsym\fR() +shall return a null pointer. +.P +More detailed diagnostic information shall be available through +\fIdlerror\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following example shows how +\fIdlopen\fR() +and +\fIdlsym\fR() +can be used to access either a function or a data object. For simplicity, +error checking has been omitted. +.sp +.RS 4 +.nf +\fB +void *handle; +int (*fptr)(int), *iptr, result; +/* open the needed symbol table */ +handle = dlopen("/usr/home/me/libfoo.so", RTLD_LOCAL | RTLD_LAZY); +/* find the address of the function my_function */ +fptr = (int (*)(int))dlsym(handle, "my_function"); +/* find the address of the data object my_object */ +iptr = (int *)dlsym(handle, "my_OBJ"); +/* invoke my_function, passing the value of my_OBJ as the parameter */ +result = (*fptr)(*iptr); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The following special purpose values for +.IR handle +are reserved for future use and have the indicated meanings: +.IP RTLD_DEFAULT 12 +The identifier lookup happens in the normal global scope; that is, +a search for an identifier using +.IR handle +would find the same definition as a direct use of this identifier in +the program code. +.IP RTLD_NEXT 12 +Specifies the next executable object file after this one that defines +.IR name . +This one refers to the executable object file containing the invocation of +\fIdlsym\fR(). +The next executable object file is the one found upon the application +of a load order symbol resolution algorithm (see +\fIdlopen\fR()). +The next symbol is either one of global scope (because it was introduced +as part of the original process image or because it was added with a +\fIdlopen\fR() +operation including the RTLD_GLOBAL flag), or is in an executable object +file that was included in the same +\fIdlopen\fR() +operation that loaded this one. +.P +The RTLD_NEXT flag is useful to navigate an intentionally created +hierarchy of multiply-defined symbols created through interposition. For +example, if a program wished to create an implementation of +\fImalloc\fR() +that embedded some statistics gathering about memory allocations, such +an implementation could use the real +\fImalloc\fR() +definition to perform the memory allocation \(em and itself only embed +the necessary logic to implement the statistics gathering function. +.P +Note that conversion from a +.BR "void *" +pointer to a function pointer as in: +.sp +.RS 4 +.nf +\fB +fptr = (int (*)(int))dlsym(handle, "my_function"); +.fi \fR +.P +.RE +.P +is not defined by the ISO\ C standard. This standard requires this conversion to +work correctly on conforming implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdlclose\fR\^(\|)", +.IR "\fIdlerror\fR\^(\|)", +.IR "\fIdlopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dprintf.3p b/man-pages-posix-2013-a/man3p/dprintf.3p new file mode 100644 index 0000000..7007d8e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dprintf.3p @@ -0,0 +1,37 @@ +'\" et +.TH DPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dprintf \(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int dprintf(int \fIfildes\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/drand48.3p b/man-pages-posix-2013-a/man3p/drand48.3p new file mode 100644 index 0000000..72e7546 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/drand48.3p @@ -0,0 +1,240 @@ +'\" et +.TH DRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.EQ +delim $$ +.EN +.SH NAME +drand48, +erand48, +jrand48, +lcong48, +lrand48, +mrand48, +nrand48, +seed48, +srand48 +\(em generate uniformly distributed pseudo-random numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double drand48(void); +double erand48(unsigned short \fIxsubi\fP[3]); +long jrand48(unsigned short \fIxsubi\fP[3]); +void lcong48(unsigned short \fIparam\fP[7]); +long lrand48(void); +long mrand48(void); +long nrand48(unsigned short \fIxsubi\fP[3]); +unsigned short *seed48(unsigned short \fIseed16v\fP[3]); +void srand48(long \fIseedval\fP); +.fi +.SH DESCRIPTION +This family of functions shall generate pseudo-random numbers using +a linear congruential algorithm and 48-bit integer arithmetic. +.P +The +\fIdrand48\fR() +and +\fIerand48\fR() +functions shall return non-negative, double-precision, floating-point +values, uniformly distributed over the interval [0.0,1.0). +.P +The +\fIlrand48\fR() +and +\fInrand48\fR() +functions shall return non-negative, long integers, uniformly +distributed over the interval [0,2\u\s-331\s+3\d). +.P +The +\fImrand48\fR() +and +\fIjrand48\fR() +functions shall return signed long integers uniformly distributed over +the interval [\(mi2\u\s-331\s+3\d,2\u\s-331\s+3\d). +.P +The +\fIsrand48\fR(), +\fIseed48\fR(), +and +\fIlcong48\fR() +functions are initialization entry points, one of which should be +invoked before either +\fIdrand48\fR(), +\fIlrand48\fR(), +or +\fImrand48\fR() +is called. (Although it is not recommended practice, constant default +initializer values shall be supplied automatically if +\fIdrand48\fR(), +\fIlrand48\fR(), +or +\fImrand48\fR() +is called without a prior call to an initialization entry point.) The +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +functions do not require an initialization entry point to be called +first. +.P +All the routines work by generating a sequence of 48-bit integer +values, $X_ i" " ,$ according to the linear congruential formula: +.sp +.RS +$X sub{n+1} " " = " " (aX_ n" "^+^c) sub{roman mod " " m} " " " " " " " " " " " " " " " " n>= " " 0$ +.RE +.P +The parameter $m^=^2"^" 48$; hence 48-bit integer arithmetic is +performed. Unless +\fIlcong48\fR() +is invoked, the multiplier value $a$ and the addend value $c$ are given +by: +.sp +.RS +$a " " mark = " " roman "5DEECE66D"^sub 16 " " = " " roman 273673163155^sub 8$ +.P +$c " " lineup = " " roman B^sub 16 " " = " " roman 13^sub 8$ +.RE +.P +The value returned by any of the +\fIdrand48\fR(), +\fIerand48\fR(), +\fIjrand48\fR(), +\fIlrand48\fR(), +\fImrand48\fR(), +or +\fInrand48\fR() +functions is computed by first generating the next 48-bit $X_ i$ in +the sequence. Then the appropriate number of bits, according to the +type of data item to be returned, are copied from the high-order +(leftmost) bits of $X_ i$ and transformed into the returned value. +.P +The +\fIdrand48\fR(), +\fIlrand48\fR(), +and +\fImrand48\fR() +functions store the last 48-bit $X_ i$ generated in an internal +buffer; that is why the application shall ensure that these are +initialized prior to being invoked. The +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +functions require the calling program to provide storage for the +successive $X_ i$ values in the array specified as an argument when +the functions are invoked. That is why these routines do not have to +be initialized; the calling program merely has to place the desired +initial value of $X_ i$ into the array and pass it as an argument. +By using different arguments, +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +allow separate modules of a large program to generate several +.IR independent +streams of pseudo-random numbers; that is, the sequence of numbers in +each stream shall +.IR not +depend upon how many times the routines are called to generate numbers +for the other streams. +.P +The initializer function +\fIsrand48\fR() +sets the high-order 32 bits of $X_ i$ to the low-order 32 bits +contained in its argument. The low-order 16 bits of $X_ i$ are set +to the arbitrary value $roman 330E_ 16" " .$ +.P +The initializer function +\fIseed48\fR() +sets the value of $X_ i$ to the 48-bit value specified in the +argument array. The low-order 16 bits of $X_ i$ are set to the +low-order 16 bits of +.IR seed16v [ 0 ]. +The mid-order 16 bits of $X_ i$ are set to the low-order 16 bits of +.IR seed16v [ 1 ]. +The high-order 16 bits of $X_ i$ are set to the low-order 16 bits of +.IR seed16v [ 2 ]. +In addition, the previous value of $X_ i$ is copied into a 48-bit +internal buffer, used only by +\fIseed48\fR(), +and a pointer to this buffer is the value returned by +\fIseed48\fR(). +This returned pointer, which can just be ignored if not needed, is +useful if a program is to be restarted from a given point at some +future time\(emuse the pointer to get at and store the last $X_ i$ +value, and then use this value to reinitialize via +\fIseed48\fR() +when the program is restarted. +.P +The initializer function +\fIlcong48\fR() +allows the user to specify the initial $X_ i" " ,$ the multiplier value +$a,$ and the addend value $c.$ Argument array elements +.IR param [ 0-2 ] +specify $X_ i" " ,$ +.IR param [ 3-5 ] +specify the multiplier $a,$ and +.IR param [ 6 ] +specifies the 16-bit addend $c.$ After +\fIlcong48\fR() +is called, a subsequent call to either +\fIsrand48\fR() +or +\fIseed48\fR() +shall restore the standard multiplier and addend values, +.IR a +and +.IR c, +specified above. +.P +The +\fIdrand48\fR(), +\fIlrand48\fR(), +and +\fImrand48\fR() +functions need not be thread-safe. +.SH "RETURN VALUE" +As described in the DESCRIPTION above. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrand\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/dup.3p b/man-pages-posix-2013-a/man3p/dup.3p new file mode 100644 index 0000000..744f320 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/dup.3p @@ -0,0 +1,262 @@ +'\" et +.TH DUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dup, +dup2 +\(em duplicate an open file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int dup(int \fIfildes\fP); +int dup2(int \fIfildes\fP, int \fIfildes2\fP); +.fi +.SH DESCRIPTION +The +\fIdup\fR() +function provides an alternative interface to the service provided by +\fIfcntl\fR() +using the F_DUPFD command. The call +.IR dup ( fildes ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +fcntl(fildes, F_DUPFD, 0); +.fi \fR +.P +.RE +.P +The +\fIdup2\fR() +function shall cause the file descriptor +.IR fildes2 +to refer to the same open file description as the file descriptor +.IR fildes +and to share any locks, and shall return +.IR fildes2 . +If +.IR fildes2 +is already a valid open file descriptor, it shall be closed first, unless +.IR fildes +is equal to +.IR fildes2 +in which case +\fIdup2\fR() +shall return +.IR fildes2 +without closing it. If the close operation fails to close +.IR fildes2 , +\fIdup2\fR() +shall return \(mi1 without changing the open file description to which +.IR fildes2 +refers. If +.IR fildes +is not a valid file descriptor, +\fIdup2\fR() +shall return \(mi1 and shall not close +.IR fildes2 . +If +.IR fildes2 +is less than 0 or greater than or equal to +{OPEN_MAX}, +\fIdup2\fR() +shall return \(mi1 with +.IR errno +set to +.BR [EBADF] . +.P +Upon successful completion, if +.IR fildes +is not equal to +.IR fildes2 , +the FD_CLOEXEC flag associated with +.IR fildes2 +shall be cleared. If +.IR fildes +is equal to +.IR fildes2 , +the FD_CLOEXEC flag associated with +.IR fildes2 +shall not be changed. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIdup2\fR() +function is unspecified. +.SH "RETURN VALUE" +Upon successful completion a non-negative integer, namely the file +descriptor, shall be returned; otherwise, \(mi1 shall be returned +and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIdup\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.P +The +\fIdup2\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor or the argument +.IR fildes2 +is negative or greater than or equal to +{OPEN_MAX}. +.TP +.BR EINTR +The +\fIdup2\fR() +function was interrupted by a signal. +.P +The +\fIdup2\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while attempting to close +.IR fildes2 . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Redirecting Standard Output to a File" S +.P +The following example closes standard output for the current processes, +re-assigns standard output to go to the file referenced by +.IR pfd , +and closes the original file descriptor to clean up. +.sp +.RS 4 +.nf +\fB +#include +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +.fi \fR +.P +.RE +.SS "Redirecting Error Messages" +.P +The following example redirects messages from +.IR stderr +to +.IR stdout . +.sp +.RS 4 +.nf +\fB +#include +\&... +dup2(1, 2); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIdup2\fR() +with an arbitrary integer for +.IR fildes2 +risks non-conforming behavior, and +\fIdup2\fR() +can only portably be used to overwrite file descriptor values that the +application has obtained through explicit actions, or for the three file +descriptors corresponding to the standard file streams. In order to avoid +a race condition of leaking an unintended file descriptor into a child +process, an application should consider opening all file descriptors +with the FD_CLOEXEC bit set unless the file descriptor is intended to +be inherited across +.IR exec . +.SH RATIONALE +The +\fIdup\fR() +function is redundant. Its services are also provided by the +\fIfcntl\fR() +function. It has been included in this volume of POSIX.1\(hy2008 primarily for historical reasons, +since many existing applications use it. On the other hand, the +\fIdup2\fR() +function provides unique services, as no other interface is able to +atomically replace an existing file descriptor. +.P +The +\fIdup2\fR() +function is not marked obsolescent because it presents a type-safe +version of functionality provided in a type-unsafe version by +\fIfcntl\fR(). +It is used in the POSIX Ada binding. +.P +The +\fIdup2\fR() +function is not intended for use in critical regions as a +synchronization mechanism. +.P +In the description of +.BR [EBADF] , +the case of +.IR fildes +being out of range is covered by the given case of +.IR fildes +not being valid. The descriptions for +.IR fildes +and +.IR fildes2 +are different because the only kind of invalidity that is relevant for +.IR fildes2 +is whether it is out of range; that is, it does not matter whether +.IR fildes2 +refers to an open file when the +\fIdup2\fR() +call is made. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclose\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/duplocale.3p b/man-pages-posix-2013-a/man3p/duplocale.3p new file mode 100644 index 0000000..c3e1a74 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/duplocale.3p @@ -0,0 +1,150 @@ +'\" et +.TH DUPLOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +duplocale +\(em duplicate a locale object +.SH SYNOPSIS +.LP +.nf +#include +.P +locale_t duplocale(locale_t \fIlocobj\fP); +.fi +.SH DESCRIPTION +The +\fIduplocale\fR() +function shall create a duplicate copy of the locale object referenced +by the +.IR locobj +argument. +.P +If the +.IR locobj +argument is LC_GLOBAL_LOCALE, +\fIduplocale\fR() +shall create a new locale object containing a copy of the global locale +determined by the +\fIsetlocale\fR() +function. +.P +The behavior is undefined if the +.IR locobj +argument is not a valid locale object handle. +.SH "RETURN VALUE" +Upon successful completion, the +\fIduplocale\fR() +function shall return a handle for a new locale object. Otherwise, +\fIduplocale\fR() +shall return (\c +.BR locale_t )0 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIduplocale\fR() +function shall fail if: +.TP +.BR ENOMEM +There is not enough memory available to create the locale object or +load the locale data. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Constructing an Altered Version of an Existing Locale Object" +.P +The following example shows a code fragment to create a slightly +altered version of an existing locale object. The function takes a +locale object and a locale name and it replaces the +.IR LC_TIME +category data in the locale object with that from the named locale. +.sp +.RS 4 +.nf +\fB +#include +\&... +.P +locale_t +with_changed_lc_time (locale_t obj, const char *name) +{ +.P + locale_t retval = duplocale (obj); + if (retval != (locale_t) 0) + { + locale_t changed = newlocale (LC_TIME_MASK, name, retval); + if (changed == (locale_t) 0) + /* An error occurred. Free all allocated resources. */ + freelocale (retval); + retval = changed; + } + return retval; } +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The use of the +\fIduplocale\fR() +function is recommended for situations where a locale object is being +used in multiple places, and it is possible that the lifetime of the +locale object might end before all uses are finished. Another reason to +duplicate a locale object is if a slightly modified form is needed. +This can be achieved by a call to +\fInewlocale\fR() +following the +\fIduplocale\fR() +call. +.P +As with the +\fInewlocale\fR() +function, handles for locale objects created by the +\fIduplocale\fR() +function should be released by a corresponding call to +\fIfreelocale\fR(). +.P +The +\fIduplocale\fR() +function can also be used in conjunction with +.IR uselocale ((\c +.BR locale_t )0). +This returns the locale in effect for the calling thread, but can have +the value LC_GLOBAL_LOCALE. Passing LC_GLOBAL_LOCALE to functions such as +\fIisalnum_l\fR() +results in undefined behavior, but applications can convert it into a +usable locale object by using +\fIduplocale\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfreelocale\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/encrypt.3p b/man-pages-posix-2013-a/man3p/encrypt.3p new file mode 100644 index 0000000..d15534a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/encrypt.3p @@ -0,0 +1,118 @@ +'\" et +.TH ENCRYPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +encrypt +\(em encoding function +(\fBCRYPT\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +void encrypt(char \fIblock\fP[64], int \fIedflag\fP); +.fi +.SH DESCRIPTION +The +\fIencrypt\fR() +function shall provide access to an implementation-defined encoding +algorithm. The key generated by +\fIsetkey\fR() +is used to encrypt the string +.IR block +with +\fIencrypt\fR(). +.P +The +.IR block +argument to +\fIencrypt\fR() +shall be an array of length 64 bytes containing only the bytes with +values of 0 and 1. The array is modified in place to a similar +array using the key set by +\fIsetkey\fR(). +If +.IR edflag +is 0, the argument is encoded. If +.IR edflag +is 1, the argument may be decoded (see the APPLICATION USAGE section); +if the argument is not decoded, +.IR errno +shall be set to +.BR [ENOSYS] . +.P +The +\fIencrypt\fR() +function shall not change the setting of +.IR errno +if successful. An application wishing to check for error situations +should set +.IR errno +to 0 before calling +\fIencrypt\fR(). +If +.IR errno +is non-zero on return, an error has occurred. +.P +The +\fIencrypt\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIencrypt\fR() +function shall not return a value. +.SH ERRORS +The +\fIencrypt\fR() +function shall fail if: +.TP +.BR ENOSYS +The functionality is not supported on this implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Historical implementations of the +\fIencrypt\fR() +function used a rather primitive encoding algorithm. +.P +In some environments, decoding might not be implemented. This is +related to some Government restrictions on encryption and decryption +routines. Historical practice has been to ship a different version of +the encryption library without the decryption feature in the routines +supplied. Thus the exported version of +\fIencrypt\fR() +does encoding but not decoding. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcrypt\fR\^(\|)", +.IR "\fIsetkey\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/endgrent.3p b/man-pages-posix-2013-a/man3p/endgrent.3p new file mode 100644 index 0000000..89e9189 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/endgrent.3p @@ -0,0 +1,132 @@ +'\" et +.TH ENDGRENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +endgrent, +getgrent, +setgrent +\(em group database entry functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endgrent(void); +struct group *getgrent(void); +void setgrent(void); +.fi +.SH DESCRIPTION +The +\fIgetgrent\fR() +function shall return a pointer to a structure containing the broken-out +fields of an entry in the group database. When first called, +\fIgetgrent\fR() +shall return a pointer to a +.BR group +structure containing the first entry in the group database. Thereafter, +it shall return a pointer to a +.BR group +structure containing the next group structure in the group database, so +successive calls may be used to search the entire database. +.P +An implementation that provides extended security controls may impose +further implementation-defined restrictions on accessing the group +database. In particular, the system may deny the existence of some or +all of the group database entries associated with groups other than +those groups associated with the caller and may omit users other than +the caller from the list of members of groups in database entries that +are returned. +.P +The +\fIsetgrent\fR() +function shall rewind the group database to allow repeated searches. +.P +The +\fIendgrent\fR() +function may be called to close the group database when processing is +complete. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +When first called, +\fIgetgrent\fR() +shall return a pointer to the first group structure in the group +database. Upon subsequent calls it shall return the next group +structure in the group database. The +\fIgetgrent\fR() +function shall return a null pointer on end-of-file or an error and +.IR errno +may be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetgrgid\fR(), +\fIgetgrnam\fR(), +or +\fIgetgrent\fR(). +.SH ERRORS +The +\fIgetgrent\fR() +function may fail if: +.TP +.BR EINTR +A signal was caught during the operation. +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are provided due to their historical usage. +Applications should avoid dependencies on fields in the group database, +whether the database is a single file, or where in the file system +name space the database resides. Applications should use +\fIgetgrnam\fR() +and +\fIgetgrgid\fR() +whenever possible because it avoids these dependencies. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendpwent\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIgetgrnam\fR\^(\|)", +.IR "\fIgetlogin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/endhostent.3p b/man-pages-posix-2013-a/man3p/endhostent.3p new file mode 100644 index 0000000..45b54e1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/endhostent.3p @@ -0,0 +1,109 @@ +'\" et +.TH ENDHOSTENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +endhostent, +gethostent, +sethostent +\(em network host database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endhostent(void); +struct hostent *gethostent(void); +void sethostent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +These functions shall retrieve information about hosts. This +information is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.TP 10 +.BR Note: +In many cases this database is implemented by the Domain Name System, +as documented in RFC\ 1034, RFC\ 1035, and RFC\ 1886. +.P +.P +The +\fIsethostent\fR() +function shall open a connection to the database and set the next entry +for retrieval to the first entry in the database. If the +.IR stayopen +argument is non-zero, the connection shall not be closed by a call to +\fIgethostent\fR(), +and the implementation may maintain an open file descriptor. +.P +The +\fIgethostent\fR() +function shall read the next entry in the database, opening and closing +a connection to the database as necessary. +.P +Entries shall be returned in +.BR hostent +structures. +.P +The +\fIendhostent\fR() +function shall close the connection to the database, releasing any open +file descriptor. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, the +\fIgethostent\fR() +function shall return a pointer to a +.BR hostent +structure if the requested entry was found, and a null pointer if the +end of the database was reached or the requested entry was not found. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgethostent\fR(). +.SH ERRORS +No errors are defined for +\fIendhostent\fR(), +\fIgethostent\fR(), +and +\fIsethostent\fR(). +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendservent\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/endnetent.3p b/man-pages-posix-2013-a/man3p/endnetent.3p new file mode 100644 index 0000000..b0a3fdb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/endnetent.3p @@ -0,0 +1,143 @@ +'\" et +.TH ENDNETENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +endnetent, +getnetbyaddr, +getnetbyname, +getnetent, +setnetent +\(em network database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endnetent(void); +struct netent *getnetbyaddr(uint32_t \fInet\fP, int \fItype\fP); +struct netent *getnetbyname(const char *\fIname\fP); +struct netent *getnetent(void); +void setnetent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +These functions shall retrieve information about networks. This +information is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.P +The +\fIsetnetent\fR() +function shall open and rewind the database. If the +.IR stayopen +argument is non-zero, the connection to the +.IR net +database shall not be closed after each call to +\fIgetnetent\fR() +(either directly, or indirectly through one of the other +.IR getnet* (\|) +functions), and the implementation may maintain an open file descriptor +to the database. +.P +The +\fIgetnetent\fR() +function shall read the next entry of the database, opening and +closing a connection to the database as necessary. +.P +The +\fIgetnetbyaddr\fR() +function shall search the database from the beginning, and find the +first entry for which the address family specified by +.IR type +matches the +.IR n_addrtype +member and the network number +.IR net +matches the +.IR n_net +member, opening and closing a connection to the database as necessary. +The +.IR net +argument shall be the network number in host byte order. +.P +The +\fIgetnetbyname\fR() +function shall search the database from the beginning and find the +first entry for which the network name specified by +.IR name +matches the +.IR n_name +member, opening and closing a connection to the database as necessary. +.P +The +\fIgetnetbyaddr\fR(), +\fIgetnetbyname\fR(), +and +\fIgetnetent\fR() +functions shall each return a pointer to a +.BR netent +structure, the members of which shall contain the fields of an entry in +the network database. +.P +The +\fIendnetent\fR() +function shall close the database, releasing any open file descriptor. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetnetbyaddr\fR(), +\fIgetnetbyname\fR(), +and +\fIgetnetent\fR() +shall return a pointer to a +.BR netent +structure if the requested entry was found, and a null pointer if the +end of the database was reached or the requested entry was not found. +Otherwise, a null pointer shall be returned. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetnetbyaddr\fR(), +\fIgetnetbyname\fR(), +or +\fIgetnetent\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/endprotoent.3p b/man-pages-posix-2013-a/man3p/endprotoent.3p new file mode 100644 index 0000000..7cfaee8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/endprotoent.3p @@ -0,0 +1,137 @@ +'\" et +.TH ENDPROTOENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +endprotoent, +getprotobyname, +getprotobynumber, +getprotoent, +setprotoent +\(em network protocol database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endprotoent(void); +struct protoent *getprotobyname(const char *\fIname\fP); +struct protoent *getprotobynumber(int \fIproto\fP); +struct protoent *getprotoent(void); +void setprotoent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +These functions shall retrieve information about protocols. This +information is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.P +The +\fIsetprotoent\fR() +function shall open a connection to the database, and set the next +entry to the first entry. If the +.IR stayopen +argument is non-zero, the connection to the network protocol database +shall not be closed after each call to +\fIgetprotoent\fR() +(either directly, or indirectly through one of the other +.IR getproto* (\|) +functions), and the implementation may maintain an open file descriptor +for the database. +.P +The +\fIgetprotobyname\fR() +function shall search the database from the beginning and find the +first entry for which the protocol name specified by +.IR name +matches the +.IR p_name +member, opening and closing a connection to the database as necessary. +.P +The +\fIgetprotobynumber\fR() +function shall search the database from the beginning and find the +first entry for which the protocol number specified by +.IR proto +matches the +.IR p_proto +member, opening and closing a connection to the database as necessary. +.P +The +\fIgetprotoent\fR() +function shall read the next entry of the database, opening and closing +a connection to the database as necessary. +.P +The +\fIgetprotobyname\fR(), +\fIgetprotobynumber\fR(), +and +\fIgetprotoent\fR() +functions shall each return a pointer to a +.BR protoent +structure, the members of which shall contain the fields of an entry in +the network protocol database. +.P +The +\fIendprotoent\fR() +function shall close the connection to the database, releasing any +open file descriptor. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetprotobyname\fR(), +\fIgetprotobynumber\fR(), +and +\fIgetprotoent\fR() +return a pointer to a +.BR protoent +structure if the requested entry was found, and a null pointer if the +end of the database was reached or the requested entry was not found. +Otherwise, a null pointer is returned. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetprotobyname\fR(), +\fIgetprotobynumber\fR(), +or +\fIgetprotoent\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/endpwent.3p b/man-pages-posix-2013-a/man3p/endpwent.3p new file mode 100644 index 0000000..547d930 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/endpwent.3p @@ -0,0 +1,165 @@ +'\" et +.TH ENDPWENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +endpwent, +getpwent, +setpwent +\(em user database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endpwent(void); +struct passwd *getpwent(void); +void setpwent(void); +.fi +.SH DESCRIPTION +These functions shall retrieve information about users. +.P +The +\fIgetpwent\fR() +function shall return a pointer to a structure containing the broken-out +fields of an entry in the user database. Each entry in the user +database contains a +.BR passwd +structure. When first called, +\fIgetpwent\fR() +shall return a pointer to a +.BR passwd +structure containing the first entry in the user database. Thereafter, +it shall return a pointer to a +.BR passwd +structure containing the next entry in the user database. Successive +calls can be used to search the entire user database. +.P +If an end-of-file or an error is encountered on reading, +\fIgetpwent\fR() +shall return a null pointer. +.P +An implementation that provides extended security controls may impose +further implementation-defined restrictions on accessing the user +database. In particular, the system may deny the existence of some or +all of the user database entries associated with users other than the +caller. +.P +The +\fIsetpwent\fR() +function effectively rewinds the user database to allow repeated +searches. +.P +The +\fIendpwent\fR() +function may be called to close the user database when processing is +complete. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +The +\fIgetpwent\fR() +function shall return a null pointer on end-of-file or error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetpwuid\fR(), +\fIgetpwnam\fR(), +or +\fIgetpwent\fR(). +.SH ERRORS +These functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.P +In addition, +\fIgetpwent\fR() +and +\fIsetpwent\fR() +may fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Searching the User Database" +.P +The following example uses the +\fIgetpwent\fR() +function to get successive entries in the user database, returning a +pointer to a +.BR passwd +structure that contains information about each user. The call to +\fIendpwent\fR() +closes the user database and cleans up. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +void printname(uid_t uid) +{ + struct passwd *pwd; +.P + setpwent(); + while((pwd = getpwent()) != NULL) { + if (pwd->pw_uid == uid) { + printf("name=%s\en",pwd->pw_name); + break; + } + } + endpwent(); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +These functions are provided due to their historical usage. +Applications should avoid dependencies on fields in the password +database, whether the database is a single file, or where in the +file system name space the database resides. Applications should use +\fIgetpwuid\fR() +whenever possible because it avoids these dependencies. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetlogin\fR\^(\|)", +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/endservent.3p b/man-pages-posix-2013-a/man3p/endservent.3p new file mode 100644 index 0000000..386a7b3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/endservent.3p @@ -0,0 +1,169 @@ +'\" et +.TH ENDSERVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +endservent, +getservbyname, +getservbyport, +getservent, +setservent +\(em network services database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endservent(void); +struct servent *getservbyname(const char *\fIname\fP, const char *\fIproto\fP); +struct servent *getservbyport(int \fIport\fP, const char *\fIproto\fP); +struct servent *getservent(void); +void setservent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +These functions shall retrieve information about network services. This +information is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.P +The +\fIsetservent\fR() +function shall open a connection to the database, and set the next +entry to the first entry. If the +.IR stayopen +argument is non-zero, the +.IR net +database shall not be closed after each call to the +\fIgetservent\fR() +function (either directly, or indirectly through one of the other +.IR getserv* (\|) +functions), and the implementation may maintain an open file descriptor +for the database. +.P +The +\fIgetservent\fR() +function shall read the next entry of the database, opening and closing +a connection to the database as necessary. +.P +The +\fIgetservbyname\fR() +function shall search the database from the beginning and find the +first entry for which the service name specified by +.IR name +matches the +.IR s_name +member and the protocol name specified by +.IR proto +matches the +.IR s_proto +member, opening and closing a connection to the database as necessary. +If +.IR proto +is a null pointer, any value of the +.IR s_proto +member shall be matched. +.P +The +\fIgetservbyport\fR() +function shall search the database from the beginning and find the +first entry for which the port specified by +.IR port +matches the +.IR s_port +member and the protocol name specified by +.IR proto +matches the +.IR s_proto +member, opening and closing a connection to the database as necessary. +If +.IR proto +is a null pointer, any value of the +.IR s_proto +member shall be matched. The +.IR port +argument shall be a value obtained by converting a +.BR uint16_t +in network byte order to +.BR int . +.P +The +\fIgetservbyname\fR(), +\fIgetservbyport\fR(), +and +\fIgetservent\fR() +functions shall each return a pointer to a +.BR servent +structure, the members of which shall contain the fields of an entry in +the network services database. +.P +The +\fIendservent\fR() +function shall close the database, releasing any open file descriptor. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetservbyname\fR(), +\fIgetservbyport\fR(), +and +\fIgetservent\fR() +return a pointer to a +.BR servent +structure if the requested entry was found, and a null pointer if the +end of the database was reached or the requested entry was not found. +Otherwise, a null pointer is returned. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetservbyname\fR(), +\fIgetservbyport\fR(), +or +\fIgetservent\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +.IR port +argument of +\fIgetservbyport\fR() +need not be compatible with the port values of all address families. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendhostent\fR\^(\|)", +.IR "\fIendprotoent\fR\^(\|)", +.IR "\fIhtonl\fR\^(\|)", +.IR "\fIinet_addr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/endutxent.3p b/man-pages-posix-2013-a/man3p/endutxent.3p new file mode 100644 index 0000000..9739c4a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/endutxent.3p @@ -0,0 +1,238 @@ +'\" et +.TH ENDUTXENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +endutxent, +getutxent, +getutxid, +getutxline, +pututxline, +setutxent +\(em user accounting database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endutxent(void); +struct utmpx *getutxent(void); +struct utmpx *getutxid(const struct utmpx *\fIid\fP); +struct utmpx *getutxline(const struct utmpx *\fIline\fP); +struct utmpx *pututxline(const struct utmpx *\fIutmpx\fP); +void setutxent(void); +.fi +.SH DESCRIPTION +These functions shall provide access to the user accounting database. +.P +The +\fIgetutxent\fR() +function shall read the next entry from the user accounting database. +If the database is not already open, it shall open it. If it reaches +the end of the database, it shall fail. +.P +The +\fIgetutxid\fR() +function shall search forward from the current point in the database. +If the +.IR ut_type +value of the +.BR utmpx +structure pointed to by +.IR id +is BOOT_TIME, OLD_TIME, or NEW_TIME, then it shall stop when it finds +an +entry with a matching +.IR ut_type +value. If the +.IR ut_type +value is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, +or DEAD_PROCESS, then it shall stop when it finds an entry whose type +is one of these four and whose +.IR ut_id +member matches the +.IR ut_id +member of the +.BR utmpx +structure pointed to by +.IR id . +If the end of the database is reached without a match, +\fIgetutxid\fR() +shall fail. +.P +The +\fIgetutxline\fR() +function shall search forward from the current point in the database +until it finds an entry of the type LOGIN_PROCESS or USER_PROCESS which +also has a +.IR ut_line +value matching that in the +.BR utmpx +structure pointed to by +.IR line . +If the end of the database is reached without a match, +\fIgetutxline\fR() +shall fail. +.P +The +\fIgetutxid\fR() +or +\fIgetutxline\fR() +function may cache data. For this reason, to use +\fIgetutxline\fR() +to search for multiple occurrences, the application shall zero out the +static data after each success, or +\fIgetutxline\fR() +may return a pointer to the same +.BR utmpx +structure. +.P +There is one exception to the rule about clearing the structure before +further reads are done. The implicit read done by +\fIpututxline\fR() +(if it finds that it is not already at the correct place in the user +accounting database) shall not modify the static structure returned by +\fIgetutxent\fR(), +\fIgetutxid\fR(), +or +\fIgetutxline\fR(), +if the application has modified this structure and passed the +pointer back to +\fIpututxline\fR(). +.P +For all entries that match a request, the +.IR ut_type +member indicates the type of the entry. Other members of the entry +shall contain meaningful data based on the value of the +.IR ut_type +member as follows: +.TS +box center tab(!); +cB | cB +l | l. +ut_type Member!Other Members with Meaningful Data +_ +EMPTY!No others +BOOT_TIME!\fIut_tv\fP +OLD_TIME!\fIut_tv\fP +NEW_TIME!\fIut_tv\fP +USER_PROCESS!\fIut_id\fP, \fIut_user\fP (login name of the user), \fIut_line\fP, \fIut_pid\fP, \fIut_tv\fP +INIT_PROCESS!\fIut_id\fP, \fIut_pid\fP, \fIut_tv\fP +LOGIN_PROCESS!T{ +.IR ut_id , +.IR ut_user +(implementation-defined name of the login process), +.IR ut_line , +.IR ut_pid , +.IR ut_tv +T} +DEAD_PROCESS!\fIut_id\fP, \fIut_pid\fP, \fIut_tv\fP +.TE +.P +An implementation that provides extended security controls may impose +implementation-defined restrictions on accessing the user accounting +database. In particular, the system may deny the existence of some or +all of the user accounting database entries associated with users other +than the caller. +.P +If the process has appropriate privileges, the +\fIpututxline\fR() +function shall write out the structure into the user accounting +database. It shall search for a record as if by +\fIgetutxid\fR() +that satisfies the request. If this search succeeds, then the entry +shall be replaced. Otherwise, a new entry shall be made at the end of +the user accounting database. +.P +The +\fIendutxent\fR() +function shall close the user accounting database. +.P +The +\fIsetutxent\fR() +function shall reset the input to the beginning of the database. This +should be done before each search for a new entry if it is desired that +the entire database be examined. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetutxent\fR(), +\fIgetutxid\fR(), +and +\fIgetutxline\fR() +shall return a pointer to a +.BR utmpx +structure containing a copy of the requested entry in the user +accounting database. Otherwise, a null pointer shall be returned. +.P +The return value may point to a static area which is overwritten by a +subsequent call to +\fIgetutxid\fR() +or +\fIgetutxline\fR(). +.P +Upon successful completion, +\fIpututxline\fR() +shall return a pointer to a +.BR utmpx +structure containing a copy of the entry added to the user accounting +database. Otherwise, a null pointer shall be returned. +.P +The +\fIendutxent\fR() +and +\fIsetutxent\fR() +functions shall not return a value. +.SH ERRORS +No errors are defined for the +\fIendutxent\fR(), +\fIgetutxent\fR(), +\fIgetutxid\fR(), +\fIgetutxline\fR(), +and +\fIsetutxent\fR() +functions. +.P +The +\fIpututxline\fR() +function may fail if: +.TP +.BR EPERM +The process does not have appropriate privileges. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The sizes of the arrays in the structure can be found using the +.IR sizeof +operator. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/environ.3p b/man-pages-posix-2013-a/man3p/environ.3p new file mode 100644 index 0000000..bf8d9bb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/environ.3p @@ -0,0 +1,38 @@ +'\" et +.TH ENVIRON "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +environ +\(em array of character pointers to the environment strings +.SH SYNOPSIS +.LP +.nf +extern char **environ; +.fi +.SH DESCRIPTION +Refer to +.IR "\fIexec\fR\^" +and the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/erand48.3p b/man-pages-posix-2013-a/man3p/erand48.3p new file mode 100644 index 0000000..3c6d421 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/erand48.3p @@ -0,0 +1,38 @@ +'\" et +.TH ERAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +erand48 +\(em generate uniformly distributed pseudo-random numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double erand48(unsigned short \fIxsubi\fP[3]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/erf.3p b/man-pages-posix-2013-a/man3p/erf.3p new file mode 100644 index 0000000..0563e1b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/erf.3p @@ -0,0 +1,151 @@ +'\" et +.TH ERF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.EQ +delim $$ +.EN +.SH NAME +erf, +erff, +erfl +\(em error functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double erf(double \fIx\fP); +float erff(float \fIx\fP); +long double erfl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the error function of their argument +.IR x , +defined as: +.sp +.RS +${2 over sqrt pi} int from 0 to x e"^" " "{- t"^" 2" "} dt$ +.RE +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the value of +the error function. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, \(+-0 shall be returned. +.P +If +.IR x +is \(+-Inf, \(+-1 shall be returned. +.P +If the correct value would cause underflow, a range error may occur, and +\fIerf\fR(), +\fIerff\fR(), +and +\fIerfl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.P +If the IEC 60559 Floating-Point option is supported, 2 * +.IR x /\c +.IR sqrt (\(*p) +should be returned. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.br +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Computing the Probability for a Normal Variate" +.P +This example shows how to use +\fIerf\fR() +to compute the probability that a normal variate assumes a value in the +range [\fIx\fR1,\fIx\fR2] with \fIx\fR1\(<=\fIx\fR2. +.P +This example uses the constant M_SQRT1_2 which is part of the XSI option. +.sp +.RS 4 +.nf +\fB +#include +.P +double +Phi(const double x1, const double x2) +{ + return ( erf(x2*M_SQRT1_2) \(mi erf(x1*M_SQRT1_2) ) / 2; +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Underflow occurs when |\fIx\fP| < DBL_MIN * (\c +.IR sqrt (\(*p)/2). +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIerfc\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/erfc.3p b/man-pages-posix-2013-a/man3p/erfc.3p new file mode 100644 index 0000000..1a9b738 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/erfc.3p @@ -0,0 +1,143 @@ +'\" et +.TH ERFC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +erfc, +erfcf, +erfcl +\(em complementary error functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double erfc(double \fIx\fP); +float erfcf(float \fIx\fP); +long double erfcl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complementary error function 1.0 \(mi +.IR erf ( x ). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the value of +the complementary error function. +.P +If the correct value would cause underflow, +and is not +representable, +a range error may occur, and +\fIerfc\fR(), +\fIerfcf\fR(), +and +\fIerfcl\fR() +shall return +0.0, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +1 shall be returned. +.P +If +.IR x +is \(miInf, +2 shall be returned. +.P +If +.IR x +is +Inf, +0 shall be returned. +.P +If the correct value would cause underflow and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIerfc\fR() +function is provided because of the extreme loss of relative accuracy if +.IR erf ( x ) +is called for large +.IR x +and the result subtracted from 1.0. +.P +Note for IEEE\ Std\ 754\(hy1985 +.BR double , +26.55 < +.IR x +implies +.IR erfc (\c +.IR x ) +has underflowed. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIerf\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/erff.3p b/man-pages-posix-2013-a/man3p/erff.3p new file mode 100644 index 0000000..52cd8f9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/erff.3p @@ -0,0 +1,40 @@ +'\" et +.TH ERFF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +erff, +erfl +\(em error functions +.SH SYNOPSIS +.LP +.nf +#include +.P +float erff(float \fIx\fP); +long double erfl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIerf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/errno.3p b/man-pages-posix-2013-a/man3p/errno.3p new file mode 100644 index 0000000..8a3f9b3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/errno.3p @@ -0,0 +1,106 @@ +'\" et +.TH ERRNO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +errno +\(em error return value +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The lvalue +.IR errno +is used by many functions to return error values. +.P +Many functions provide an error number in +.IR errno , +which has type +.BR int +and is defined in +.IR . +The value of +.IR errno +shall be defined only after a call to a function for which it is +explicitly stated to be set and until it is changed by the next +function call or if the application assigns it a value. The value of +.IR errno +should only be examined when it is indicated to be valid by a +function's return value. Applications shall obtain the definition of +.IR errno +by the inclusion of +.IR . +No function in this volume of POSIX.1\(hy2008 shall set +.IR errno +to 0. The setting of +.IR errno +after a successful call to a function is unspecified unless the +description of that function specifies that +.IR errno +shall not be modified. +.P +It is unspecified whether +.IR errno +is a macro or an identifier declared with external linkage. If a macro +definition is suppressed in order to access an actual object, or a +program defines an identifier with the name +.IR errno , +the behavior is undefined. +.P +The symbolic values stored in +.IR errno +are documented in the ERRORS sections on all relevant pages. +.SH "RETURN VALUE" +None. +.SH ERRORS +None. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Previously both POSIX and X/Open documents were more restrictive than +the ISO\ C standard in that they required +.IR errno +to be defined as an external variable, whereas the ISO\ C standard required only +that +.IR errno +be defined as a modifiable lvalue with type +.BR int . +.P +An application that needs to examine the value of +.IR errno +to determine the error should set it to 0 before a function call, then +inspect it before a subsequent function call. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.3" ", " "Error Numbers" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/exec.3p b/man-pages-posix-2013-a/man3p/exec.3p new file mode 100644 index 0000000..7ef839d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/exec.3p @@ -0,0 +1,1344 @@ +'\" et +.TH EXEC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +environ, +execl, +execle, +execlp, +execv, +execve, +execvp, +fexecve +\(em execute a file +.SH SYNOPSIS +.LP +.nf +#include +.P +extern char **environ; +int execl(const char *\fIpath\fP, const char *\fIarg0\fP, ... /*, (char *)0 */); +int execle(const char *\fIpath\fP, const char *\fIarg0\fP, ... /*, + (char *)0, char *const \fIenvp\fP[]*/); +int execlp(const char *\fIfile\fP, const char *\fIarg0\fP, ... /*, (char *)0 */); +int execv(const char *\fIpath\fP, char *const \fIargv\fP[]); +int execve(const char *\fIpath\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]); +int execvp(const char *\fIfile\fP, char *const \fIargv\fP[]); +int fexecve(int \fIfd\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]); +.fi +.SH DESCRIPTION +The +.IR exec +family of functions shall replace the current process image with a new +process image. The new image shall be constructed from a regular, +executable file called the +.IR "new process image file" . +There shall be no return from a successful +.IR exec , +because the calling process image is overlaid by the new process +image. +.P +The +\fIfexecve\fR() +function shall be equivalent to the +\fIexecve\fR() +function except that the file to be executed is determined by the file +descriptor +.IR fd +instead of a pathname. The file offset of +.IR fd +is ignored. +.P +When a C-language program is executed as a result of a call to one +of the +.IR exec +family of functions, it shall be entered as a C-language function call +as follows: +.sp +.RS 4 +.nf +\fB +int main (\fIint argc, char *argv\fP[]); +.fi \fR +.P +.RE +.P +where +.IR argc +is the argument count and +.IR argv +is an array of character pointers to the arguments themselves. +In addition, the following variable, which must be declared by the user +if it is to be used directly: +.sp +.RS 4 +.nf +\fB +extern char **environ; +.fi \fR +.P +.RE +.P +is initialized as a pointer to an array of character pointers to the +environment strings. The +.IR argv +and +.IR environ +arrays are each terminated by a null pointer. The null pointer +terminating the +.IR argv +array is not counted in +.IR argc . +.P +Applications can change the entire environment in a single operation by +assigning the +.IR environ +variable to point to an array of character pointers to the new environment +strings. After assigning a new value to +.IR environ , +applications should not rely on the new environment strings remaining +part of the environment, as a call to +\fIgetenv\fR(), +\fIputenv\fR(), +\fIsetenv\fR(), +\fIunsetenv\fR(), +or any function that is dependent on an environment variable may, on +noticing that +.IR environ +has changed, copy the environment strings to a new array and assign +.IR environ +to point to it. +.P +Any application that directly modifies the pointers to which the +.IR environ +variable points has undefined behavior. +.P +Conforming multi-threaded applications shall not use the +.IR environ +variable to access or modify any environment variable while any other +thread is concurrently modifying any environment variable. A call to +any function dependent on any environment variable shall be considered +a use of the +.IR environ +variable to access that environment variable. +.P +The arguments specified by a program with one of the +.IR exec +functions shall be passed on to the new process image in the +corresponding +\fImain\fR() +arguments. +.P +The argument +.IR path +points to a pathname that identifies the new process image file. +.P +The argument +.IR file +is used to construct a pathname that identifies the new process image +file. If the +.IR file +argument contains a + +character, the +.IR file +argument shall be used as the pathname for this file. Otherwise, the +path prefix for this file is obtained by a search of the directories +passed as the environment variable +.IR PATH +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables"). +If this environment variable is not present, the results +of the search are implementation-defined. +.P +There are two distinct ways in which the contents of the process image +file may cause the execution to fail, distinguished by the setting of +.IR errno +to either +.BR [ENOEXEC] +or +.BR [EINVAL] +(see the ERRORS section). In the cases where the other members of the +.IR exec +family of functions would fail and set +.IR errno +to +.BR [ENOEXEC] , +the +\fIexeclp\fR() +and +\fIexecvp\fR() +functions shall execute a command interpreter and the environment of the +executed command shall be as if the process invoked the +.IR sh +utility using +\fIexecl\fR() +as follows: +.sp +.RS 4 +.nf +\fB +execl(, arg0, file, arg1, ..., (char *)0); +.fi \fR +.P +.RE +.P +where <\fIshell\ path\fP> is an unspecified pathname for the +.IR sh +utility, +.IR file +is the process image file, and for +\fIexecvp\fR(), +where +.IR arg 0, +.IR arg 1, +and so on correspond to the values passed to +\fIexecvp\fR() +in +.IR argv [0], +.IR argv [1], +and so on. +.P +The arguments represented by +.IR arg0 ,\|.\|.\|. +are pointers to null-terminated character strings. These strings +shall constitute the argument list available to the new process +image. The list is terminated by a null pointer. The argument +.IR arg0 +should point to a filename string that is associated with the process +being started by one of the +.IR exec +functions. +.P +The argument +.IR argv +is an array of character pointers to null-terminated strings. The +application shall ensure that the last member of this array is a null +pointer. These strings shall constitute the argument list available to +the new process image. The value in +.IR argv [0] +should point to a filename string that is associated with the process +being started by one of the +.IR exec +functions. +.P +The argument +.IR envp +is an array of character pointers to null-terminated strings. These +strings shall constitute the environment for the new process image. +The +.IR envp +array is terminated by a null pointer. +.P +For those forms not containing an +.IR envp +pointer (\c +\fIexecl\fR(), +\fIexecv\fR(), +\fIexeclp\fR(), +and +\fIexecvp\fR()), +the environment for the new process image shall be taken from the +external variable +.IR environ +in the calling process. +.P +The number of bytes available for the new process' combined argument +and environment lists is +{ARG_MAX}. +It is implementation-defined whether null terminators, pointers, +and/or any alignment bytes are included in this total. +.P +File descriptors open in the calling process image shall remain open in +the new process image, except for those whose close-on-\c +.IR exec +flag FD_CLOEXEC is set. +For those file descriptors that remain open, all attributes of the open +file description remain unchanged. For any file descriptor that is +closed for this reason, file locks are removed as a result of the close +as described in +\fIclose\fR(). +Locks that are not removed by closing of file descriptors remain +unchanged. +.P +If file descriptor 0, 1, or 2 would otherwise be closed after a successful +call to one of the +.IR exec +family of functions, implementations may open an unspecified file for +the file descriptor in the new process image. If a standard utility +or a conforming application is executed with file descriptor 0 not +open for reading or with file descriptor 1 or 2 not open for writing, +the environment in which the utility or application is executed shall +be deemed non-conforming, and consequently the utility or application +might not behave as described in this standard. +.P +Directory streams open in the calling process image shall be closed +in the new process image. +.P +The state of the floating-point environment in the initial thread +of the new process image shall be set to the default. +.P +The state of conversion descriptors +and message catalog descriptors in the new process image is undefined. +.P +For the new process image, the equivalent of: +.sp +.RS 4 +.nf +\fB +setlocale(LC_ALL, "C") +.fi \fR +.P +.RE +.P +shall be executed at start-up. +.P +Signals set to the default action (SIG_DFL) in the calling process +image shall be set to the default action in the new process image. +Except for SIGCHLD, signals set to be ignored (SIG_IGN) by the calling +process image shall be set to be +ignored by the new process image. Signals set to be caught by the +calling process image shall be set to the default action in the new +process image (see +.IR ). +.P +If the SIGCHLD signal is set to be ignored by the calling process +image, it is unspecified whether the SIGCHLD signal is set to be +ignored or to the default action in the new process image. +.P +After a successful call to any of the +.IR exec +functions, alternate signal stacks are not preserved and the SA_ONSTACK +flag +shall be cleared for all signals. +.P +After a successful call to any of the +.IR exec +functions, any functions previously registered by the +\fIatexit\fR() +or +\fIpthread_atfork\fR() +functions are no longer registered. +.P +If the ST_NOSUID bit is set for the file system containing the new +process +image file, then the effective user ID, effective group ID, saved +set-user-ID, and saved set-group-ID are unchanged in the new process +image. Otherwise, +if the set-user-ID mode bit of the new process image file is set, the +effective user ID of the new process image shall be set to the user ID +of the new process image file. Similarly, if the set-group-ID mode bit +of the new process image file is set, the effective group ID of the new +process image shall be set to the group ID of the new process image +file. The real user ID, real group ID, and supplementary group IDs of +the new process image shall remain the same as those of the calling +process image. The effective user ID and effective group ID of the new +process image shall be saved (as the saved set-user-ID and the saved +set-group-ID) for use by +\fIsetuid\fR(). +.P +Any shared memory segments attached to the calling process image +shall not be attached to the new process image. +.P +Any named semaphores open in the calling process shall be closed as +if by appropriate calls to +\fIsem_close\fR(). +.P +Any blocks of typed memory that were mapped in the calling process are +unmapped, as if +\fImunmap\fR() +was implicitly called to unmap them. +.P +Memory locks established by the calling process via calls to +\fImlockall\fR() +or +\fImlock\fR() +shall be removed. If locked pages in the address space of the calling +process are also mapped into the address spaces of other processes and +are locked by those processes, the locks established by the other +processes shall be unaffected by the call by this process to the +.IR exec +function. If the +.IR exec +function fails, the effect on memory locks is unspecified. +.P +Memory mappings created in the process are unmapped before the address +space is rebuilt for the new process image. +.P +When the calling process image does not use the SCHED_FIFO, SCHED_RR, +or SCHED_SPORADIC +scheduling policies, the scheduling policy and parameters of the +new process image and the initial thread in that new process image are +implementation-defined. +.P +When the calling process image uses the SCHED_FIFO, SCHED_RR, or +SCHED_SPORADIC scheduling policies, the process policy and scheduling +parameter settings shall not be changed by a call to an +.IR exec +function. +The initial thread in the new process image shall inherit the +process scheduling policy and parameters. It shall have the default +system contention scope, but shall inherit its allocation domain +from the calling process image. +.P +Per-process timers created by the calling process shall be deleted before +replacing the current process image with the new process image. +.P +All open message queue descriptors in the calling process shall be closed, +as described in +\fImq_close\fR(). +.P +Any outstanding asynchronous I/O operations may be canceled. Those +asynchronous I/O operations that are not canceled shall complete as if +the +.IR exec +function had not yet occurred, but any associated signal notifications +shall be suppressed. It is unspecified whether the +.IR exec +function itself blocks awaiting such I/O completion. In no event, +however, shall the new process image created by the +.IR exec +function be affected by the presence of outstanding asynchronous I/O +operations at the time the +.IR exec +function is called. Whether any I/O is canceled, and which I/O may be +canceled upon +.IR exec , +is implementation-defined. +.P +The new process image shall inherit the CPU-time clock of the calling +process image. This inheritance means that the process CPU-time clock +of the process being +.IR exec -ed +shall not be reinitialized or altered as a result of the +.IR exec +function other than to reflect the time spent by the process executing +the +.IR exec +function itself. +.P +The initial value of the CPU-time clock of the initial thread of the +new process image shall be set to zero. +.P +If the calling process is being traced, the new process image shall +continue to be traced into the same trace stream as the original +process image, but the new process image shall not inherit the mapping +of trace event names to trace event type identifiers that was defined +by calls to the +\fIposix_trace_eventid_open\fR() +or the +\fIposix_trace_trid_eventid_open\fR() +functions in the calling process image. +.P +If the calling process is a trace controller process, any trace streams +that were created by the calling process shall be shut down as +described in the +\fIposix_trace_shutdown\fR() +function. +.P +The thread ID of the initial thread in the new process image is +unspecified. +.P +The size and location of the stack on which the initial thread in the +new process image runs is unspecified. +.P +The initial thread in the new process image shall have its cancellation +type set to PTHREAD_CANCEL_DEFERRED and its cancellation state set to +PTHREAD_CANCEL_ENABLED. +.P +The initial thread in the new process image shall have all +thread-specific data values set to NULL and all thread-specific data +keys shall be removed by the call to +.IR exec +without running destructors. +.P +The initial thread in the new process image shall be joinable, as if +created with the +.IR detachstate +attribute set to PTHREAD_CREATE_JOINABLE. +.P +The new process shall inherit at least the following attributes from +the calling process image: +.IP " *" 4 +Nice value (see +\fInice\fR()) +.IP " *" 4 +\fIsemadj\fP values (see +\fIsemop\fR()) +.IP " *" 4 +Process ID +.IP " *" 4 +Parent process ID +.IP " *" 4 +Process group ID +.IP " *" 4 +Session membership +.IP " *" 4 +Real user ID +.IP " *" 4 +Real group ID +.IP " *" 4 +Supplementary group IDs +.IP " *" 4 +Time left until an alarm clock signal (see +\fIalarm\fR()) +.IP " *" 4 +Current working directory +.IP " *" 4 +Root directory +.IP " *" 4 +File mode creation mask (see +\fIumask\fR()) +.IP " *" 4 +File size limit (see +\fIgetrlimit\fR() +and +\fIsetrlimit\fR()) +.IP " *" 4 +Process signal mask (see +\fIpthread_sigmask\fR()) +.IP " *" 4 +Pending signal (see +\fIsigpending\fR()) +.IP " *" 4 +.IR tms_utime , +.IR tms_stime , +.IR tms_cutime , +and +.IR tms_cstime +(see +\fItimes\fR()) +.IP " *" 4 +Resource limits +.IP " *" 4 +Controlling terminal +.IP " *" 4 +Interval timers +.P +The initial thread of the new process shall inherit at least the +following attributes from the calling thread: +.IP " *" 4 +Signal mask (see +\fIsigprocmask\fR() +and +\fIpthread_sigmask\fR()) +.IP " *" 4 +Pending signals (see +\fIsigpending\fR()) +.P +All other process attributes defined in this volume of POSIX.1\(hy2008 shall be inherited in the +new process image from the old process image. All other thread +attributes defined in this volume of POSIX.1\(hy2008 shall be inherited in the initial thread in +the new process image from the calling thread in the old process image. +The inheritance of process or thread attributes not defined by this volume of POSIX.1\(hy2008 is +implementation-defined. +.P +A call to any +.IR exec +function from a process with more than one thread shall result in all +threads being terminated and the new executable image being loaded and +executed. No destructor functions or cleanup handlers shall be called. +.P +Upon successful completion, the +.IR exec +functions shall mark for update the last data access timestamp +of the file. If an +.IR exec +function failed but was able to locate the process image file, whether the +last data access timestamp is marked for update is unspecified. Should the +.IR exec +function succeed, the process image file shall be considered to have been +opened with +\fIopen\fR(). +The corresponding +\fIclose\fR() +shall be considered to occur at a time after this open, but before process +termination or successful completion of a subsequent call to one of the +.IR exec +functions, +\fIposix_spawn\fR(), +or +\fIposix_spawnp\fR(). +The +.IR argv [\|] +and +.IR envp [\|] +arrays of pointers and the strings to which those arrays point shall +not be modified by a call to one of the +.IR exec +functions, except as a consequence of replacing the process image. +.P +The saved resource limits in the new process image are set to be a copy +of the process' corresponding hard and soft limits. +.SH "RETURN VALUE" +If one of the +.IR exec +functions returns to the calling process image, an error has occurred; +the return value shall be \(mi1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +.IR exec +functions shall fail if: +.TP +.BR E2BIG +The number of bytes used by the new process image's argument list and +environment list is greater than the system-imposed limit of +{ARG_MAX} +bytes. +.TP +.BR EACCES +The new process image file is not a regular file and the implementation +does not support execution of files of its type. +.TP +.BR EINVAL +The new process image file has appropriate privileges and has a +recognized executable binary format, but the system does not support +execution of a file with this format. +.P +The +.IR exec +functions, except for +\fIfexecve\fR(), +shall fail if: +.TP +.BR EACCES +Search permission is denied for a directory listed in the new process +image file's path prefix, or the new process image file denies execution +permission. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +or +.IR file +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +or +.IR file +does not name an existing file or +.IR path +or +.IR file +is an empty string. +.TP +.BR ENOTDIR +A component of the new process image file's path prefix names an existing +file that is neither a directory nor a symbolic link to a directory, +or the new process image file's pathname contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.P +The +.IR exec +functions, except for +\fIexeclp\fR() +and +\fIexecvp\fR(), +shall fail if: +.TP +.BR ENOEXEC +The new process image file has the appropriate access permission but +has an unrecognized format. +.P +The +\fIfexecve\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor open for executing. +.P +The +.IR exec +functions may fail if: +.TP +.BR ENOMEM +The new process image requires more memory than is allowed by +the hardware or system-imposed memory management constraints. +.P +The +.IR exec +functions, except for +\fIfexecve\fR(), +may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +or +.IR file +argument. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR path +argument or the length of the pathname constructed from the +.IR file +argument exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate result +with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +The new process image file is a pure procedure (shared text) file that +is currently open for writing by some process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using execl(\|)" +.P +The following example executes the +.IR ls +command, specifying the pathname of the executable (\c +.BR /bin/ls ) +and using arguments supplied directly to the command to produce +single-column output. +.sp +.RS 4 +.nf +\fB +#include +.P +int ret; +\&... +ret = execl ("/bin/ls", "ls", "-1", (char *)0); +.fi \fR +.P +.RE +.SS "Using execle(\|)" +.P +The following example is similar to +.IR "Using execl(\|)". +In addition, it specifies the environment for the new process image +using the +.IR env +argument. +.sp +.RS 4 +.nf +\fB +#include +.P +int ret; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execle ("/bin/ls", "ls", "-l", (char *)0, env); +.fi \fR +.P +.RE +.SS "Using execlp(\|)" +.P +The following example searches for the location of the +.IR ls +command among the directories specified by the +.IR PATH +environment variable. +.sp +.RS 4 +.nf +\fB +#include +.P +int ret; +\&... +ret = execlp ("ls", "ls", "-l", (char *)0); +.fi \fR +.P +.RE +.SS "Using execv(\|)" +.P +The following example passes arguments to the +.IR ls +command in the +.IR cmd +array. +.sp +.RS 4 +.nf +\fB +#include +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execv ("/bin/ls", cmd); +.fi \fR +.P +.RE +.SS "Using execve(\|)" +.P +The following example passes arguments to the +.IR ls +command in the +.IR cmd +array, and specifies the environment for the new process image using the +.IR env +argument. +.sp +.RS 4 +.nf +\fB +#include +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execve ("/bin/ls", cmd, env); +.fi \fR +.P +.RE +.SS "Using execvp(\|)" +.P +The following example searches for the location of the +.IR ls +command among the directories specified by the +.IR PATH +environment variable, and passes arguments to the +.IR ls +command in the +.IR cmd +array. +.sp +.RS 4 +.nf +\fB +#include +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execvp ("ls", cmd); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +As the state of conversion descriptors and message catalog +descriptors in the new process image is undefined, conforming +applications should not rely on their use and should close them prior +to calling one of the +.IR exec +functions. +.P +Applications that require other than the default POSIX locale as the +global locale in the new process image should call +\fIsetlocale\fR() +with the appropriate parameters. +.P +When assigning a new value to the +.IR environ +variable, applications should ensure that the environment to which it +will point contains at least the following: +.IP " 1." 4 +Any implementation-defined variables required by the implementation to +provide a conforming environment. See the _CS_V7_ENV entry in +.IR +and +\fIconfstr\fR() +for details. +.IP " 2." 4 +A value for +.IR PATH +which finds conforming versions of all standard utilities before any +other versions. +.P +The same constraint applies to the +.IR envp +array passed to +\fIexecle\fR() +or +\fIexecve\fR(), +in order to ensure that the new process image is invoked in a conforming +environment. +.P +Applications should not execute programs with file descriptor 0 not open +for reading or with file descriptor 1 or 2 not open for writing, as this +might cause the executed program to misbehave. In order not to pass on +these file descriptors to an executed program, applications should not +just close them but should reopen them on, for example, +.BR /dev/null . +Some implementations may reopen them automatically, but applications +should not rely on this being done. +.P +If an application wants to perform a checksum test of the file being +executed before executing it, the file will need to be opened with read +permission to perform the checksum test. +.P +Since execute permission is checked by +\fIfexecve\fR(), +the file description +.IR fd +need not have been opened with the O_EXEC flag. However, if the file +to be executed denies read and write permission for the process +preparing to do the +.IR exec , +the only way to provide the +.IR fd +to +\fIfexecve\fR() +will be to use the O_EXEC flag when opening +.IR fd . +In this case, the application will not be able to perform a checksum +test since it will not be able to read the contents of the file. +.P +Note that when a file descriptor is opened with O_RDONLY, O_RDWR, or +O_WRONLY mode, the file descriptor can be used to read, read and write, +or write the file, respectively, even if the mode of the file changes +after the file was opened. Using the O_EXEC open mode is different; +\fIfexecve\fR() +will ignore the mode that was used when the file descriptor was opened +and the +.IR exec +will fail if the mode of the file associated with +.IR fd +does not grant execute permission to the calling process at the time +\fIfexecve\fR() +is called. +.SH RATIONALE +Early proposals required that the value of +.IR argc +passed to +\fImain\fR() +be ``one or greater''. This was driven by the same requirement in +drafts of the ISO\ C standard. +In fact, historical implementations have passed a value of zero when no +arguments are supplied to the caller of the +.IR exec +functions. This requirement was removed from the ISO\ C standard and subsequently +removed from this volume of POSIX.1\(hy2008 as well. The wording, in particular the use of the +word \fIshould\fP, requires a Strictly Conforming POSIX Application +to pass at least one argument to the +.IR exec +function, thus guaranteeing that +.IR argc +be one or greater when invoked by such an application. In fact, this is +good practice, since many existing applications reference +.IR argv [0] +without first checking the value of +.IR argc . +.P +The requirement on a Strictly Conforming POSIX Application also states +that the value passed as the first argument be a filename string +associated with the process being started. Although some existing +applications pass a pathname rather than a filename string in some +circumstances, a filename string is more generally useful, since the +common usage of +.IR argv [0] +is in printing diagnostics. In some cases the filename passed is not +the actual filename of the file; for example, many implementations of the +.IR login +utility use a convention of prefixing a + +(\c +.BR '\(hy' ) +to the actual filename, which indicates to the command interpreter being +invoked that it is a ``login shell''. +.P +Historically, there have been two ways that implementations can +.IR exec +shell scripts. +.P +One common historical implementation is that the +\fIexecl\fR(), +\fIexecv\fR(), +\fIexecle\fR(), +and +\fIexecve\fR() +functions return an +.BR [ENOEXEC] +error for any file not recognizable as executable, including a shell +script. When the +\fIexeclp\fR() +and +\fIexecvp\fR() +functions encounter such a file, they assume the file to be a shell +script and invoke a known command interpreter to interpret such files. +This is now required by POSIX.1\(hy2008. These implementations of +\fIexecvp\fR() +and +\fIexeclp\fR() +only give the +.BR [ENOEXEC] +error in the rare case of a problem with the command interpreter's +executable file. Because of these implementations, the +.BR [ENOEXEC] +error is not mentioned for +\fIexeclp\fR() +or +\fIexecvp\fR(), +although implementations can still give it. +.P +Another way that some historical implementations handle shell scripts +is by recognizing the first two bytes of the file as the character +string +.BR \(dq#!\(dq +and using the remainder of the first line of the file as the name of +the command interpreter to execute. +.P +One potential source of confusion noted by the standard developers +is over how the contents of a process image file affect the behavior +of the +.IR exec +family of functions. The following is a description of the actions +taken: +.IP " 1." 4 +If the process image file is a valid executable (in a format that is +executable and valid and having appropriate privileges) for this +system, then the system executes the file. +.IP " 2." 4 +If the process image file has appropriate privileges and is in a format +that is executable but not valid for this system (such as a recognized +binary for another architecture), then this is an error and +.IR errno +is set to +.BR [EINVAL] +(see later RATIONALE on +.BR [EINVAL] ). +.IP " 3." 4 +If the process image file has appropriate privileges but is not +otherwise recognized: +.RS 4 +.IP " a." 4 +If this is a call to +\fIexeclp\fR() +or +\fIexecvp\fR(), +then they invoke a command interpreter assuming that the process image +file is a shell script. +.IP " b." 4 +If this is not a call to +\fIexeclp\fR() +or +\fIexecvp\fR(), +then an error occurs and +.IR errno +is set to +.BR [ENOEXEC] . +.RE +.P +Applications that do not require to access their arguments may use +the form: +.sp +.RS 4 +.nf +\fB +main(void) +.fi \fR +.P +.RE +as specified in the ISO\ C standard. However, the implementation will always +provide the two arguments +.IR argc +and +.IR argv , +even if they are not used. +.P +Some implementations provide a third argument to +\fImain\fR() +called +.IR envp . +This is defined as a pointer to the environment. The ISO\ C standard +specifies invoking +\fImain\fR() +with two arguments, so implementations must support applications +written this way. Since this volume of POSIX.1\(hy2008 defines the global variable +.IR environ , +which is also provided by historical implementations and can be used +anywhere that +.IR envp +could be used, there is no functional need for the +.IR envp +argument. Applications should use the +\fIgetenv\fR() +function rather than accessing the environment directly via either +.IR envp +or +.IR environ . +Implementations are required to support the two-argument calling +sequence, but this does not prohibit an implementation from supporting +.IR envp +as an optional third argument. +.P +This volume of POSIX.1\(hy2008 specifies that signals set to SIG_IGN +remain set to SIG_IGN, and that the new process image inherits the +signal mask of the thread that called +.IR exec +in the old process image. This is consistent with historical +implementations, and it permits some useful functionality, such as the +.IR nohup +command. However, it should be noted that many existing applications +wrongly assume that they start with certain signals set to the default +action and/or unblocked. In particular, applications written with a +simpler signal model that does not include blocking of signals, such as +the one in the ISO\ C standard, may not behave properly if invoked with some +signals blocked. Therefore, it is best not to block or ignore signals +across +.IR exec s +without explicit reason to do so, and especially not to block signals +across +.IR exec s +of arbitrary (not closely cooperating) programs. +.P +The +.IR exec +functions always save the value of the effective user ID +and effective group ID +of the process at the completion of the +.IR exec , +whether or not the set-user-ID +or the set-group-ID +bit of the process image file is set. +.P +The statement about +.IR argv [\|] +and +.IR envp [\|] +being constants is included to make explicit to future writers of +language bindings that these objects are completely constant. Due to a +limitation of the ISO\ C standard, it is not possible to state that idea in +standard C. Specifying two levels of +.IR const \(mi\c +.IR qualification +for the +.IR argv [\|] +and +.IR envp [\|] +parameters for the +.IR exec +functions may seem to be the natural choice, given that these functions +do not modify either the array of pointers or the characters to which +the function points, but this would disallow existing correct code. +Instead, only the array of pointers is noted as constant. The table of +assignment compatibility for +.IR dst =\c +.IR src +derived from the ISO\ C standard summarizes the compatibility: +.TS +box tab(!) center; +r | lB | lB | lB | lB +lB | c | c | c | c. +\fIdst\fP:!char *[\|]!const char *[\|]!char *const[\|]!const char *const[\|] +_ +\fIsrc\fP: +char *[\|]!VALID!\(em!VALID!\(em +const char *[\|]!\(em!VALID!\(em!VALID +char * const [\|]!\(em!\(em!VALID!\(em +const char *const[\|]!\(em!\(em!\(em!VALID +.TE +.P +Since all existing code has a source type matching the first row, the +column that gives the most valid combinations is the third column. The +only other possibility is the fourth column, but using it would require +a cast on the +.IR argv +or +.IR envp +arguments. It is unfortunate that the fourth column cannot be used, +because the declaration a non-expert would naturally use would be that +in the second row. +.P +The ISO\ C standard and this volume of POSIX.1\(hy2008 do not conflict on the use of +.IR environ , +but some historical implementations of +.IR environ +may cause a conflict. As long as +.IR environ +is treated in the same way as an entry point (for example, +\fIfork\fR()), +it conforms to both standards. A library can contain +\fIfork\fR(), +but if there is a user-provided +\fIfork\fR(), +that +\fIfork\fR() +is given precedence and no problem ensues. The situation is similar +for +.IR environ : +the definition in this volume of POSIX.1\(hy2008 is to be used if there is no user-provided +.IR environ +to take precedence. At least three implementations are known to exist +that solve this problem. +.TP +.BR E2BIG +The limit +{ARG_MAX} +applies not just to the size of the argument list, but to the sum of +that and the size of the environment list. +.TP +.BR EFAULT +Some historical systems return +.BR [EFAULT] +rather than +.BR [ENOEXEC] +when the new process image file is corrupted. They are non-conforming. +.TP +.BR EINVAL +This error condition was added to POSIX.1\(hy2008 to allow an implementation to +detect executable files generated for different architectures, and +indicate this situation to the application. Historical implementations +of shells, +\fIexecvp\fR(), +and +\fIexeclp\fR() +that encounter an +.BR [ENOEXEC] +error will execute a shell on the assumption that the file is a shell +script. This will not produce the desired effect when the file is a +valid executable for a different architecture. An implementation may +now choose to avoid this problem by returning +.BR [EINVAL] +when a valid executable for a different architecture is encountered. +Some historical implementations return +.BR [EINVAL] +to indicate that the +.IR path +argument contains a character with the high order bit set. The +standard developers chose to deviate from historical practice for the +following reasons: +.RS 12 +.IP " 1." 4 +The new utilization of +.BR [EINVAL] +will provide some measure of utility to the user community. +.IP " 2." 4 +Historical use of +.BR [EINVAL] +is not acceptable in an internationalized operating environment. +.RE +.TP +.BR ENAMETOOLONG +.br +Since the file pathname may be constructed by taking elements in the +.IR PATH +variable and putting them together with the filename, the +.BR [ENAMETOOLONG] +error condition could also be reached this way. +.TP +.BR ETXTBSY +System V returns this error when the executable file is currently open +for writing by some process. This volume of POSIX.1\(hy2008 neither requires nor prohibits this +behavior. +.P +Other systems (such as System V) may return +.BR [EINTR] +from +.IR exec . +This is not addressed by this volume of POSIX.1\(hy2008, but implementations may have a +window between the call to +.IR exec +and the time that a signal could cause one of the +.IR exec +calls to return with +.BR [EINTR] . +.P +An explicit statement regarding the floating-point environment (as +defined in the +.IR +header) was added to make it clear that the floating-point environment +is set to its default when a call to one of the +.IR exec +functions succeeds. The requirements for inheritance or setting to the +default for other process and thread start-up functions is covered by +more generic statements in their descriptions and can be summarized as +follows: +.IP "\fIposix_spawn\fR\^(\|)" 14 +Set to default. +.IP "\fIfork\fR\^(\|)" 14 +Inherit. +.IP "\fIpthread_create\fR\^(\|)" 14 +Inherit. +.P +The purpose of the +\fIfexecve\fR() +function is to enable executing a file which has been verified to be +the intended file. It is possible to actively check the file by reading +from the file descriptor and be sure that the file is not exchanged for +another between the reading and the execution. Alternatively, an +function like +\fIopenat\fR() +can be used to open a file which has been found by reading the content +of a directory using +\fIreaddir\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIalarm\fR\^(\|)", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIfstatvfs\fR\^(\|)", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fInice\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/exit.3p b/man-pages-posix-2013-a/man3p/exit.3p new file mode 100644 index 0000000..bcfb671 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/exit.3p @@ -0,0 +1,101 @@ +'\" et +.TH EXIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +exit +\(em terminate a process +.SH SYNOPSIS +.LP +.nf +#include +.P +void exit(int \fIstatus\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The value of +.IR status +may be 0, EXIT_SUCCESS, EXIT_FAILURE, +or any other value, though only the least significant 8 bits (that is, +.IR status +& 0377) shall be available to a waiting parent process. +.P +The +\fIexit\fR() +function shall first call all functions registered by +\fIatexit\fR(), +in the reverse order of their registration, except that a function is +called after any previously registered functions that had already been +called at the time it was registered. Each function is called as many +times as it was registered. If, during the call to any such function, a +call to the +\fIlongjmp\fR() +function is made that would terminate the call to the registered +function, the behavior is undefined. +.P +If a function registered by a call to +\fIatexit\fR() +fails to return, the remaining registered functions shall not be called +and the rest of the +\fIexit\fR() +processing shall not be completed. If +\fIexit\fR() +is called more than once, the behavior is undefined. +.P +The +\fIexit\fR() +function shall then flush all open streams with unwritten buffered data +and close all open streams. Finally, the process shall be terminated +with the same consequences as described in +.IR "Consequences of Process Termination". +.SH "RETURN VALUE" +The +\fIexit\fR() +function does not return. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See +\fI_Exit\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fI_Exit\fR\^(\|)", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/exp.3p b/man-pages-posix-2013-a/man3p/exp.3p new file mode 100644 index 0000000..b487627 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/exp.3p @@ -0,0 +1,187 @@ +'\" et +.TH EXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +exp, +expf, +expl +\(em exponential function +.SH SYNOPSIS +.LP +.nf +#include +.P +double exp(double \fIx\fP); +float expf(float \fIx\fP); +long double expl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the base-\c +.IR e +exponential of +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the +exponential value of +.IR x . +.P +If the correct value would cause overflow, a range error shall occur +and +\fIexp\fR(), +\fIexpf\fR(), +and +\fIexpl\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIexp\fR(), +\fIexpf\fR(), +and +\fIexpl\fR() +shall return +0.0, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, 1 shall be returned. +.P +If +.IR x +is \(miInf, +0 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Computing the Density of the Standard Normal Distribution" +.P +This function shows an implementation for the density of the standard +normal distribution using +\fIexp\fR(). +This example uses the constant M_PI which is part of the XSI option. +.sp +.RS 4 +.nf +\fB +#include +.P +double +normal_density (double x) +{ + return exp(\(mix*x/2) / sqrt (2*M_PI); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Note that for IEEE\ Std\ 754\(hy1985 +.BR double , +709.8 < +.IR x +implies +.IR exp (\c +.IR x ) +has overflowed. The value +.IR x \c +<\ \(mi708.4 +implies +.IR exp (\c +.IR x ) +has underflowed. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/exp2.3p b/man-pages-posix-2013-a/man3p/exp2.3p new file mode 100644 index 0000000..56aeb7b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/exp2.3p @@ -0,0 +1,165 @@ +'\" et +.TH EXP2 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +exp2, +exp2f, +exp2l +\(em exponential base 2 functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double exp2(double \fIx\fP); +float exp2f(float \fIx\fP); +long double exp2l(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the base-2 exponential of +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +2\fI\s-3\ux\d\s+3\fR. +.P +If the correct value would cause overflow, a range error shall occur +and +\fIexp2\fR(), +\fIexp2f\fR(), +and +\fIexp2l\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIexp2\fR(), +\fIexp2f\fR(), +and +\fIexp2l\fR() +shall return +0.0, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, 1 shall be returned. +.P +If +.IR x +is \(miInf, +0 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For IEEE\ Std\ 754\(hy1985 +.BR double , +1024 <= +.IR x +implies +.IR exp2 (\c +.IR x ) +has overflowed. The value +.IR x \c +<\ \(mi1022 implies +.IR exp (\c +.IR x ) +has underflowed. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/expm1.3p b/man-pages-posix-2013-a/man3p/expm1.3p new file mode 100644 index 0000000..3e0afa4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/expm1.3p @@ -0,0 +1,191 @@ +'\" et +.TH EXPM1 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +expm1, +expm1f, +expm1l +\(em compute exponential functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double expm1(double \fIx\fP); +float expm1f(float \fIx\fP); +long double expm1l(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute \fIe\u\s-3x\s+3\d\fR\(mi1.0. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions return +\fIe\s-3\ux\d\s+3\fR\(mi1.0. +.P +If the correct value would cause overflow, a range error shall occur +and +\fIexpm1\fR(), +\fIexpm1f\fR(), +and +\fIexpm1l\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, \(+-0 shall be returned. +.P +If +.IR x +is \(miInf, \(mi1 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIexpm1\fR(), +\fIexpm1f\fR(), +and +\fIexpm1l\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The value of +.IR expm1 ( x ) +may be more accurate than +.IR exp ( x )\(mi1.0 +for small values of +.IR x . +.P +The +\fIexpm1\fR() +and +\fIlog1p\fR() +functions are useful for financial calculations of +((1+\fIx\fR)\u\s-3\fIn\fR\s+3\d\(mi1)/\fIx\fR, namely: +.sp +.RS 4 +.nf +\fB +expm1(\fIn\fP * log1p(\fIx\fP))/\fIx\fP +.fi \fR +.P +.RE +.P +when +.IR x +is very small (for example, when calculating small daily interest +rates). These functions also simplify writing accurate inverse +hyperbolic functions. +.P +For IEEE\ Std\ 754\(hy1985 +.BR double , +709.8 < +.IR x +implies +.IR expm1 (\c +.IR x ) +has overflowed. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIilogb\fR\^(\|)", +.IR "\fIlog1p\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fabs.3p b/man-pages-posix-2013-a/man3p/fabs.3p new file mode 100644 index 0000000..e3ebcb4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fabs.3p @@ -0,0 +1,119 @@ +'\" et +.TH FABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fabs, +fabsf, +fabsl +\(em absolute value function +.SH SYNOPSIS +.LP +.nf +#include +.P +double fabs(double \fIx\fP); +float fabsf(float \fIx\fP); +long double fabsl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the absolute value of their argument +.IR x ,|\c +.IR x |. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the absolute +value of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +0 shall be returned. +.P +If +.IR x +is \(+-Inf, +Inf shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Computing the 1-Norm of a Floating-Point Vector" +.P +This example shows the use of +\fIfabs\fR() +to compute the 1-norm of a vector defined as follows: +.sp +.RS 4 +.nf +\fB +norm1(v) = |v[0]| + |v[1]| + ... + |v[n\(mi1]| +.fi \fR +.P +.RE +.P +where |\fIx\fR| denotes the absolute value of \fIx\fR, \fIn\fR denotes +the vector's dimension \fIv\fR[\fIi\fR] denotes the +.IR i -th +component of \fIv\fR (0\(<=\fIi\fR<\fIn\fR). +.sp +.RS 4 +.nf +\fB +#include +.P +double +norm1(const double v[], const int n) +{ + int i; + double n1_v; /* 1-norm of v */ +.P + n1_v = 0; + for (i=0; i\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/faccessat.3p b/man-pages-posix-2013-a/man3p/faccessat.3p new file mode 100644 index 0000000..e8368cc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/faccessat.3p @@ -0,0 +1,39 @@ +'\" et +.TH FACCESSAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +faccessat +\(em determine accessibility of a file relative to directory file +descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int faccessat(int \fIfd\fP, const char *\fIpath\fP, int \fIamode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIaccess\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fattach.3p b/man-pages-posix-2013-a/man3p/fattach.3p new file mode 100644 index 0000000..726e7ee --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fattach.3p @@ -0,0 +1,234 @@ +'\" et +.TH FATTACH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fattach +\(em attach a STREAMS-based file descriptor to a file in the +file system name space (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int fattach(int \fIfildes\fP, const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIfattach\fR() +function shall attach a STREAMS-based file descriptor to a file, +effectively associating a pathname with +.IR fildes . +The application shall ensure that the +.IR fildes +argument is a valid open file descriptor associated with a STREAMS +file. The +.IR path +argument points to a pathname of an existing file. The application +shall have appropriate privileges or be the owner of the file +named by +.IR path +and have write permission. A successful call to +\fIfattach\fR() +shall cause all pathnames that name the file named by +.IR path +to name the STREAMS file associated with +.IR fildes , +until the STREAMS file is detached from the file. A STREAMS file can be +attached to more than one file and can have several pathnames +associated with it. +.P +The attributes of the named STREAMS file shall be initialized as follows: +the permissions, user ID, group ID, and times are set to those of the +file named by +.IR path , +the number of links is set to 1, and the size and device identifier are +set to those of the STREAMS file associated with +.IR fildes . +If any attributes of the named STREAMS file are subsequently changed +(for example, by +\fIchmod\fR()), +neither the attributes of the underlying file nor the attributes of the +STREAMS file to which +.IR fildes +refers shall be affected. +.P +File descriptors referring to the underlying file, opened prior to an +\fIfattach\fR() +call, shall continue to refer to the underlying file. +.SH "RETURN VALUE" +Upon successful completion, +\fIfattach\fR() +shall return 0. Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfattach\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix, or the +process is the owner of +.IR path +but does not have write permissions on the file named by +.IR path . +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EBUSY +The file named by +.IR path +is currently a mount point or has a STREAMS file attached to it. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. +.TP +.BR EPERM +The effective user ID of the process is not the owner of the file named +by +.IR path +and the process does not have appropriate privileges. +.br +.P +The +\fIfattach\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR fildes +argument does not refer to a STREAMS file. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR EXDEV +A link to a file on another file system was attempted. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Attaching a File Descriptor to a File" +.P +In the following example, +.IR fd +refers to an open STREAMS file. The call to +\fIfattach\fR() +associates this STREAM with the file +.BR /tmp/named-STREAM , +such that any future calls to open +.BR /tmp/named-STREAM , +prior to breaking the attachment via a call to +\fIfdetach\fR(), +will instead create a new file handle referring to the STREAMS file +associated with +.IR fd . +.sp +.RS 4 +.nf +\fB +#include +\&... + int fd; + char *pathname = "/tmp/named-STREAM"; + int ret; +.P + ret = fattach(fd, pathname); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIfattach\fR() +function behaves similarly to the traditional +\fImount\fR() +function in the way a file is temporarily replaced by the root +directory of the mounted file system. In the case of +\fIfattach\fR(), +the replaced file need not be a directory and the replacing file is a +STREAMS file. +.SH RATIONALE +The file attributes of a file which has been the subject of an +\fIfattach\fR() +call are specifically set because of an artifact of the original +implementation. The internal mechanism was the same as for the +\fImount\fR() +function. Since +\fImount\fR() +is typically only applied to directories, the effects when applied to +a regular file are a little surprising, especially as regards the link +count which rigidly remains one, even if there were several links +originally and despite the fact that all original links refer to the +STREAM as long as the +\fIfattach\fR() +remains in effect. +.SH "FUTURE DIRECTIONS" +The +\fIfattach\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfdetach\fR\^(\|)", +.IR "\fIisastream\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fchdir.3p b/man-pages-posix-2013-a/man3p/fchdir.3p new file mode 100644 index 0000000..2277715 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fchdir.3p @@ -0,0 +1,101 @@ +'\" et +.TH FCHDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fchdir +\(em change working directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchdir(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIfchdir\fR() +function shall be equivalent to +\fIchdir\fR() +except that the directory that is to be the new current working +directory is specified by the file descriptor +.IR fildes . +.P +A conforming application can obtain a file descriptor for a file of +type directory using +\fIopen\fR(), +provided that the file status flags and access modes do not contain +O_WRONLY or O_RDWR. +.SH "RETURN VALUE" +Upon successful completion, +\fIfchdir\fR() +shall return 0. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. On failure the current working directory +shall remain unchanged. +.SH ERRORS +The +\fIfchdir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for the directory referenced by +.IR fildes . +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR ENOTDIR +The open file descriptor +.IR fildes +does not refer to a directory. +.P +The +\fIfchdir\fR() +may fail if: +.TP +.BR EINTR +A signal was caught during the execution of +\fIfchdir\fR(). +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchdir\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fchmod.3p b/man-pages-posix-2013-a/man3p/fchmod.3p new file mode 100644 index 0000000..20c00e3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fchmod.3p @@ -0,0 +1,159 @@ +'\" et +.TH FCHMOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fchmod +\(em change mode of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchmod(int \fIfildes\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIfchmod\fR() +function shall be equivalent to +\fIchmod\fR() +except that the file whose permissions are changed is specified +by the file descriptor +.IR fildes . +.P +If +.IR fildes +references a shared memory object, the +\fIfchmod\fR() +function need only affect the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, +S_IROTH, and S_IWOTH file permission bits. +.P +If +.IR fildes +references a typed memory object, the behavior of +\fIfchmod\fR() +is unspecified. +.P +If +.IR fildes +refers to a socket, the behavior of +\fIfchmod\fR() +is unspecified. +.P +If +.IR fildes +refers to a STREAM (which is +\fIfattach\fR()-ed +into the file system name space) the call returns successfully, doing +nothing. +.SH "RETURN VALUE" +Upon successful completion, +\fIfchmod\fR() +shall return 0. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfchmod\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP +.BR EROFS +The file referred to by +.IR fildes +resides on a read-only file system. +.P +The +\fIfchmod\fR() +function may fail if: +.TP +.BR EINTR +The +\fIfchmod\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The value of the +.IR mode +argument is invalid. +.TP +.BR EINVAL +The +.IR fildes +argument refers to a pipe and the implementation disallows execution of +\fIfchmod\fR() +on a pipe. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Current Permissions for a File" +.P +The following example shows how to change the permissions for a +file named +.BR /home/cnd/mod1 +so that the owner and group have read/write/execute permissions, but +the world only has read/write permissions. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +mode_t mode; +int fildes; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +fchmod(fildes, S_IRWXU | S_IRWXG | S_IROTH | S_IWOTH); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIchown\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIfstatvfs\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fchmodat.3p b/man-pages-posix-2013-a/man3p/fchmodat.3p new file mode 100644 index 0000000..d8231f0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fchmodat.3p @@ -0,0 +1,38 @@ +'\" et +.TH FCHMODAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fchmodat +\(em change mode of a file relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchmodat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIchmod\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fchown.3p b/man-pages-posix-2013-a/man3p/fchown.3p new file mode 100644 index 0000000..98dbcc0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fchown.3p @@ -0,0 +1,138 @@ +'\" et +.TH FCHOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fchown +\(em change owner and group of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchown(int \fIfildes\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +.fi +.SH DESCRIPTION +The +\fIfchown\fR() +function shall be equivalent to +\fIchown\fR() +except that the file whose owner and group are changed is +specified by the file descriptor +.IR fildes . +.SH "RETURN VALUE" +Upon successful completion, +\fIfchown\fR() +shall return 0. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfchown\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR EPERM +The effective user ID does not match the owner of the file or the +process does not have appropriate privileges and _POSIX_CHOWN_RESTRICTED +indicates that such privilege is required. +.TP +.BR EROFS +The file referred to by +.IR fildes +resides on a read-only file system. +.P +The +\fIfchown\fR() +function may fail if: +.TP +.BR EINVAL +The owner or group ID is not a value supported by the implementation. +The +.IR fildes +argument refers to a pipe or socket +or an +\fIfattach\fR()-ed +STREAM +and the implementation disallows execution of +\fIfchown\fR() +on a pipe. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR EINTR +The +\fIfchown\fR() +function was interrupted by a signal which was caught. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Current Owner of a File" +.P +The following example shows how to change the owner of a file named +.BR /home/cnd/mod1 +to ``jones'' and the group to ``cnd''. +.P +The numeric value for the user ID is obtained by extracting the user ID +from the user database entry associated with ``jones''. Similarly, the +numeric value for the group ID is obtained by extracting the group ID +from the group database entry associated with ``cnd''. This example +assumes the calling program has appropriate privileges. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +.P +struct passwd *pwd; +struct group *grp; +int fildes; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +pwd = getpwnam("jones"); +grp = getgrnam("cnd"); +fchown(fildes, pwd->pw_uid, grp->gr_gid); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchown\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fchownat.3p b/man-pages-posix-2013-a/man3p/fchownat.3p new file mode 100644 index 0000000..444c5cc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fchownat.3p @@ -0,0 +1,40 @@ +'\" et +.TH FCHOWNAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fchownat +\(em change owner and group of a file relative to directory +file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchownat(int \fIfd\fP, const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP, + int \fIflag\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIchown\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fclose.3p b/man-pages-posix-2013-a/man3p/fclose.3p new file mode 100644 index 0000000..c5f6171 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fclose.3p @@ -0,0 +1,166 @@ +'\" et +.TH FCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fclose +\(em close a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fclose(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfclose\fR() +function shall cause the stream pointed to by +.IR stream +to be flushed and the associated file to be closed. Any unwritten +buffered data for the stream shall be written to the file; any unread +buffered data shall be discarded. Whether or not the call succeeds, +the stream shall be disassociated from the file and any buffer set by +the +\fIsetbuf\fR() +or +\fIsetvbuf\fR() +function shall be disassociated from the stream. If the associated +buffer was automatically allocated, it shall be deallocated. +.P +If the file is not already at EOF, and the file is one capable of seeking, +the file offset of the underlying open file description shall be set to +the file position of the stream if the stream is the active handle to +the underlying file description. +.P +The +\fIfclose\fR() +function shall mark for update the last data modification and last +file status change timestamps of the underlying file, if the stream was +writable, and if buffered data remains that has not yet been written to +the file. The +\fIfclose\fR() +function shall perform the equivalent of a +\fIclose\fR() +on the file descriptor that is associated with the stream pointed to by +.IR stream . +.P +After the call to +\fIfclose\fR(), +any use of +.IR stream +results in undefined behavior. +.SH "RETURN VALUE" +Upon successful completion, +\fIfclose\fR() +shall return 0; otherwise, it shall return EOF +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfclose\fR() +function shall fail if: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying stream is not valid. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the maximum file size. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the file size +limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or beyond +the offset maximum associated with the corresponding stream. +.TP +.BR EINTR +The +\fIfclose\fR() +function was interrupted by a signal. +.TP +.BR EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the calling thread +is not blocking SIGTTOU, the process is not ignoring SIGTTOU, and the +process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOMEM +The underlying stream was created by +\fIopen_memstream\fR() +or +\fIopen_wmemstream\fR() +and insufficient memory is available. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file or +in the buffer used by the +\fIfmemopen\fR() +function. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process. A SIGPIPE signal shall also be sent to the +thread. +.P +The +\fIfclose\fR() +function may fail if: +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIclose\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fcntl.3p b/man-pages-posix-2013-a/man3p/fcntl.3p new file mode 100644 index 0000000..5977fe8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fcntl.3p @@ -0,0 +1,690 @@ +'\" et +.TH FCNTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fcntl +\(em file control +.SH SYNOPSIS +.LP +.nf +#include +.P +int fcntl(int \fIfildes\fP, int \fIcmd\fP, ...); +.fi +.SH DESCRIPTION +The +\fIfcntl\fR() +function shall perform the operations described below on open files. The +.IR fildes +argument is a file descriptor. +.P +The available values for +.IR cmd +are defined in +.IR +and are as follows: +.IP F_DUPFD 14 +Return a new file descriptor which shall be the lowest numbered +available (that is, not already open) file descriptor greater than or +equal to the third argument, +.IR arg , +taken as an integer of type +.BR int . +The new file descriptor shall refer to the same open file description as +the original file descriptor, and shall share any locks. The FD_CLOEXEC +flag associated with the new file descriptor shall be cleared to keep +the file open across calls to one of the +.IR exec +functions. +.IP F_DUPFD_CLOEXEC 14 +.br +Like F_DUPFD, but the FD_CLOEXEC flag associated with the new file +descriptor shall be set. +.IP F_GETFD 14 +Get the file descriptor flags defined in +.IR +that are associated with the file descriptor +.IR fildes . +File descriptor flags are associated with a single file descriptor and +do not affect other file descriptors that refer to the same file. +.IP F_SETFD 14 +Set the file descriptor flags defined in +.IR , +that are associated with +.IR fildes , +to the third argument, +.IR arg , +taken as type +.BR int . +If the FD_CLOEXEC flag in the third argument +is 0, the file descriptor shall remain open across the +.IR exec +functions; otherwise, the file descriptor shall be closed upon +successful execution of one of the +.IR exec +functions. +.IP F_GETFL 14 +Get the file status flags and file access modes, defined in +.IR , +for the file description associated with +.IR fildes . +The file access modes can be extracted from the return value using the +mask O_ACCMODE, which is defined in +.IR . +File status flags and file access modes are associated with the file +description and do not affect other file descriptors that refer to the +same file with different open file descriptions. The flags returned may +include non-standard file status flags which the application did not +set, provided that these additional flags do not alter the behavior of +a conforming application. +.IP F_SETFL 14 +Set the file status flags, defined in +.IR , +for the file description associated with +.IR fildes +from the corresponding bits in the third argument, +.IR arg , +taken as type +.BR int . +Bits corresponding to the file access mode and the file creation +flags, as defined in +.IR , +that are set in +.IR arg +shall be ignored. If any bits in +.IR arg +other than those mentioned here are changed by the application, the +result is unspecified. If +.IR fildes +does not support non-blocking operations, it is unspecified whether the +O_NONBLOCK flag will be ignored. +.IP F_GETOWN 14 +If +.IR fildes +refers to a socket, get the process or process group ID specified to +receive SIGURG signals when out-of-band data is available. Positive +values indicate a process ID; negative values, other than \(mi1, +indicate a process group ID. If +.IR fildes +does not refer to a socket, the results are unspecified. +.IP F_SETOWN 14 +If +.IR fildes +refers to a socket, set the process or process group ID specified to +receive SIGURG signals when out-of-band data is available, using the +value of the third argument, +.IR arg , +taken as type +.BR int . +Positive values indicate a process ID; negative values, other than +\(mi1, indicate a process group ID. If +.IR fildes +does not refer to a socket, the results are unspecified. +.P +The following values for +.IR cmd +are available for advisory record locking. Record locking shall be +supported for regular files, and may be supported for other files. +.IP F_GETLK 14 +Get the first lock which blocks the lock description pointed to by the +third argument, +.IR arg , +taken as a pointer to type +.BR "struct flock" , +defined in +.IR . +The information retrieved shall overwrite the information passed to +\fIfcntl\fR() +in the structure +.BR flock . +If no lock is found that would prevent this lock from being created, +then the structure shall be left unchanged except for the lock type +which shall be set to F_UNLCK. +.IP F_SETLK 14 +Set or clear a file segment lock according to the lock description +pointed to by the third argument, +.IR arg , +taken as a pointer to type +.BR "struct flock" , +defined in +.IR . +F_SETLK can establish shared (or read) locks (F_RDLCK) or +exclusive (or write) locks (F_WRLCK), as well as to remove either type +of lock (F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK are defined in +.IR . +If a shared or exclusive lock cannot be set, +\fIfcntl\fR() +shall return immediately with a return value of \(mi1. +.IP F_SETLKW 14 +This command shall be equivalent to F_SETLK except that if a shared or +exclusive lock is blocked by other locks, the thread shall wait until +the request can be satisfied. If a signal that is to be caught is +received while +\fIfcntl\fR() +is waiting for a region, +\fIfcntl\fR() +shall be interrupted. Upon return from the signal handler, +\fIfcntl\fR() +shall return \(mi1 with +.IR errno +set to +.BR [EINTR] , +and the lock operation shall not be done. +.P +Additional implementation-defined values for +.IR cmd +may be defined in +.IR . +Their names shall start with F_. +.P +When a shared lock is set on a segment of a file, other processes shall +be able to set shared locks on that segment or a portion of it. A +shared lock prevents any other process from setting an exclusive lock +on any portion of the protected area. A request for a shared lock +shall fail if the file descriptor was not opened with read access. +.P +An exclusive lock shall prevent any other process from setting a shared +lock or an exclusive lock on any portion of the protected area. A +request for an exclusive lock shall fail if the file descriptor was not +opened with write access. +.P +The structure +.BR flock +describes the type (\c +.IR l_type ), +starting offset (\c +.IR l_whence ), +relative offset (\c +.IR l_start ), +size (\c +.IR l_len ), +and process ID (\c +.IR l_pid ) +of the segment of the file to be affected. +.P +The value of +.IR l_whence +is SEEK_SET, SEEK_CUR, or SEEK_END, +to indicate that the relative offset +.IR l_start +bytes shall be measured from the start of the file, current position, +or end of the file, respectively. The value of +.IR l_len +is the number of consecutive bytes to be locked. The value of +.IR l_len +may be negative (where the definition of +.BR off_t +permits negative values of +.IR l_len ). +The +.IR l_pid +field is only used with F_GETLK to return the process ID of the process +holding a blocking lock. After a successful F_GETLK request, when a +blocking lock is found, the values returned in the +.BR flock +structure shall be as follows: +.IP "\fIl_type\fP" 10 +Type of blocking lock found. +.IP "\fIl_whence\fP" 10 +SEEK_SET. +.IP "\fIl_start\fP" 10 +Start of the blocking lock. +.IP "\fIl_len\fP" 10 +Length of the blocking lock. +.IP "\fIl_pid\fP" 10 +Process ID of the process that holds the blocking lock. +.P +If the command is F_SETLKW and the process must wait for another +process to release a lock, then the range of bytes to be locked shall +be determined before the +\fIfcntl\fR() +function blocks. If the file size or file descriptor seek offset change +while +\fIfcntl\fR() +is blocked, this shall not affect the range of bytes locked. +.P +If +.IR l_len +is positive, the area affected shall start at +.IR l_start +and end at +.IR l_start +\c +.IR l_len \(mi1. +If +.IR l_len +is negative, the area affected shall start at +.IR l_start +\c +.IR l_len +and end at +.IR l_start \(mi1. +Locks may start and extend beyond the current end of a file, but shall +not extend before the beginning of the file. A lock shall be set to +extend to the largest possible value of the file offset for that file +by setting +.IR l_len +to 0. If such a lock also has +.IR l_start +set to 0 and +.IR l_whence +is set to SEEK_SET, the whole file shall be locked. +.P +There shall be at most one type of lock set for each byte in the file. +Before a successful return from an F_SETLK or an F_SETLKW request when +the calling process has previously existing locks on bytes in the +region specified by the request, the previous lock type for each byte +in the specified region shall be replaced by the new lock type. As +specified above under the descriptions of shared locks and exclusive +locks, an F_SETLK or an F_SETLKW request (respectively) shall fail or +block when another process has existing locks on bytes in the specified +region and the type of any of those locks conflicts with the type +specified in the request. +.P +All locks associated with a file for a given process shall be removed +when a file descriptor for that file is closed by that process or the +process holding that file descriptor terminates. Locks are not +inherited by a child process. +.P +A potential for deadlock occurs if a process controlling a locked +region is put to sleep by attempting to lock the locked region of +another process. If the system detects that sleeping until a locked +region is unlocked would cause a deadlock, +\fIfcntl\fR() +shall fail with an +.BR [EDEADLK] +error. +.P +An unlock (F_UNLCK) request in which +.IR l_len +is non-zero and the offset of the last byte of the requested segment is +the maximum value for an object of type +.BR off_t , +when the process has an existing lock in which +.IR l_len +is 0 and which includes the last byte of the requested segment, shall be +treated as a request to unlock from the start of the requested segment +with an +.IR l_len +equal to 0. Otherwise, an unlock (F_UNLCK) request shall attempt to +unlock only the requested segment. +.P +When the file descriptor +.IR fildes +refers to a shared memory object, the behavior of +\fIfcntl\fR() +shall be the same as for a regular file except the effect of the +following values for the argument +.IR cmd +shall be unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIfcntl\fR() +function is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the value returned shall depend on +.IR cmd +as follows: +.IP F_DUPFD 12 +A new file descriptor. +.IP F_DUPFD_CLOEXEC 12 +.br +A new file descriptor. +.IP F_GETFD 12 +Value of flags defined in +.IR . +The return value shall not be negative. +.IP F_SETFD 12 +Value other than \(mi1. +.IP F_GETFL 12 +Value of file status flags and access modes. The return value is not +negative. +.IP F_SETFL 12 +Value other than \(mi1. +.IP F_GETLK 12 +Value other than \(mi1. +.IP F_SETLK 12 +Value other than \(mi1. +.IP F_SETLKW 12 +Value other than \(mi1. +.IP F_GETOWN 12 +Value of the socket owner process or process group; this will not be +\(mi1. +.IP F_SETOWN 12 +Value other than \(mi1. +.P +Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfcntl\fR() +function shall fail if: +.TP +.BR EACCES " or " EAGAIN +.br +The +.IR cmd +argument is F_SETLK; the type of lock (\c +.IR l_type ) +is a shared (F_RDLCK) or exclusive (F_WRLCK) lock and the segment of a +file to be locked is already exclusive-locked by another process, or the +type is an exclusive lock and some portion of the segment of a file to +be locked is already shared-locked or exclusive-locked by another process. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor, or the argument +.IR cmd +is F_SETLK or F_SETLKW, the type of lock, +.IR l_type , +is a shared lock (F_RDLCK), and +.IR fildes +is not a valid file descriptor open for reading, or the type of lock, +.IR l_type , +is an exclusive lock (F_WRLCK), and +.IR fildes +is not a valid file descriptor open for writing. +.TP +.BR EINTR +The +.IR cmd +argument is F_SETLKW and the function was interrupted by a signal. +.TP +.BR EINVAL +The +.IR cmd +argument is invalid, or the +.IR cmd +argument is F_DUPFD or F_DUPFD_CLOEXEC and +.IR arg +is negative or greater than or equal to +{OPEN_MAX}, +or the +.IR cmd +argument is F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by +.IR arg +is not valid, or +.IR fildes +refers to a file that does not support locking. +.TP +.BR EMFILE +The argument +.IR cmd +is F_DUPFD or F_DUPFD_CLOEXEC and all file descriptors available to +the process are currently open, or no file descriptors greater than or +equal to +.IR arg +are available. +.TP +.BR ENOLCK +The argument +.IR cmd +is F_SETLK or F_SETLKW and satisfying the lock or unlock request would +result in the number of locked regions in the system exceeding a +system-imposed limit. +.TP +.BR EOVERFLOW +One of the values to be returned cannot be represented correctly. +.TP +.BR EOVERFLOW +The +.IR cmd +argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, if +.IR l_len +is non-zero, the largest offset of any byte in the requested segment +cannot be represented correctly in an object of type +.BR off_t . +.br +.P +The +\fIfcntl\fR() +function may fail if: +.TP +.BR EDEADLK +The +.IR cmd +argument is F_SETLKW, the lock is blocked by a lock from another +process, and putting the calling process to sleep to wait for that lock +to become free would cause a deadlock. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Locking and Unlocking a File" +.P +The following example demonstrates how to place a lock on bytes 100 to +109 of a file and then later remove it. F_SETLK is used to perform a +non-blocking lock request so that the process does not have to wait if +an incompatible lock is held by another process; instead the process +can take some other action. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +.P +int +main(int argc, char *argv[]) +{ + int fd; + struct flock fl; +.P + fd = open("testfile", O_RDWR); + if (fd == -1) + /* Handle error */; +.P + /* Make a non-blocking request to place a write lock + on bytes 100-109 of testfile */ +.P + fl.l_type = F_WRLCK; + fl.l_whence = SEEK_SET; + fl.l_start = 100; + fl.l_len = 10; +.P + if (fcntl(fd, F_SETLK, &fl) == \(mi1) { + if (errno == EACCES || errno == EAGAIN) { + printf("Already locked by another process\en"); +.P + /* We can't get the lock at the moment */ +.P + } else { + /* Handle unexpected error */; + } + } else { /* Lock was granted... */ +.P + /* Perform I/O on bytes 100 to 109 of file */ +.P + /* Unlock the locked bytes */ +.P + fl.l_type = F_UNLCK; + fl.l_whence = SEEK_SET; + fl.l_start = 100; + fl.l_len = 10; + if (fcntl(fd, F_SETLK, &fl) == \(mi1) + /* Handle error */; + } + exit(EXIT_SUCCESS); +} /* main */ +.fi \fR +.P +.RE +.SS "Setting the Close-on-Exec Flag" +.P +The following example demonstrates how to set the close-on-exec flag +for the file descriptor +.IR fd . +.sp +.RS 4 +.nf +\fB +#include +#include +\&... + int flags; +.P + flags = fcntl(fd, F_GETFD); + if (flags == \(mi1) + /* Handle error */; + flags |= FD_CLOEXEC; + if (fcntl(fd, F_SETFD, flags) == \(mi1) + /* Handle error */;" +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +.IR arg +values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag +values to allow for future growth. Applications using these functions +should do a read-modify-write operation on them, rather than assuming +that only the values defined by this volume of POSIX.1\(hy2008 are valid. It is a common error to +forget this, particularly in the case of F_SETFD. Some implementations +set additional file status flags to advise the application of default +behavior, even though the application did not request these flags. +.SH RATIONALE +The ellipsis in the SYNOPSIS is the syntax specified by the ISO\ C standard +for a variable number of arguments. It is used because System V uses +pointers for the implementation of file locking functions. +.P +This volume of POSIX.1\(hy2008 permits concurrent read and write access to file data using the +\fIfcntl\fR() +function; this is a change from the 1984 /usr/group standard and early proposals. Without +concurrency controls, this feature may not be fully utilized without +occasional loss of data. +.P +Data losses occur in several ways. One case occurs when several +processes try to update the same record, without sequencing controls; +several updates may occur in parallel and the last writer ``wins''. +Another case is a bit-tree or other internal list-based database that +is undergoing reorganization. Without exclusive use to the tree segment +by the updating process, other reading processes chance getting lost in +the database when the index blocks are split, condensed, inserted, or +deleted. While +\fIfcntl\fR() +is useful for many applications, it is not intended to be overly +general and does not handle the bit-tree example well. +.P +This facility is only required for regular files because it is not +appropriate for many devices such as terminals and network +connections. +.P +Since +\fIfcntl\fR() +works with ``any file descriptor associated with that file, however it +is obtained'', the file descriptor may have been inherited through a +\fIfork\fR() +or +.IR exec +operation and thus may affect a file that another process also has +open. +.P +The use of the open file description to identify what to lock requires +extra calls and presents problems if several processes are sharing an +open file description, but there are too many implementations of the +existing mechanism for this volume of POSIX.1\(hy2008 to use different specifications. +.P +Another consequence of this model is that closing any file descriptor +for a given file (whether or not it is the same open file description +that created the lock) causes the locks on that file to be relinquished +for that process. Equivalently, any close for any file/process pair +relinquishes the locks owned on that file for that process. But note +that while an open file description may be shared through +\fIfork\fR(), +locks are not inherited through +\fIfork\fR(). +Yet locks may be inherited through one of the +.IR exec +functions. +.P +The identification of a machine in a network environment is outside +the scope of this volume of POSIX.1\(hy2008. Thus, an +.IR l_sysid +member, such as found in System V, is not included in the locking +structure. +.P +Changing of lock types can result in a previously locked region being +split into smaller regions. +.P +Mandatory locking was a major feature of the 1984 /usr/group standard. +.P +For advisory file record locking to be effective, all processes that +have access to a file must cooperate and use the advisory mechanism +before doing I/O on the file. Enforcement-mode record locking is +important when it cannot be assumed that all processes are cooperating. +For example, if one user uses an editor to update a file at the same +time that a second user executes another process that updates the same +file and if only one of the two processes is using advisory locking, +the processes are not cooperating. Enforcement-mode record locking +would protect against accidental collisions. +.P +Secondly, advisory record locking requires a process using locking to +bracket each I/O operation with lock (or test) and unlock operations. +With enforcement-mode file and record locking, a process can lock the +file once and unlock when all I/O operations have been completed. +Enforcement-mode record locking provides a base that can be enhanced; +for example, with sharable locks. That is, the mechanism could be +enhanced to allow a process to lock a file so other processes could +read it, but none of them could write it. +.P +Mandatory locks were omitted for several reasons: +.IP " 1." 4 +Mandatory lock setting was done by multiplexing the set-group-ID +bit in most implementations; this was confusing, at best. +.IP " 2." 4 +The relationship to file truncation as supported in 4.2 BSD +was not well specified. +.IP " 3." 4 +Any publicly readable file could be locked by anyone. Many historical +implementations keep the password database in a publicly readable +file. A malicious user could thus prohibit logins. Another +possibility would be to hold open a long-distance telephone line. +.IP " 4." 4 +Some demand-paged historical implementations offer memory mapped files, +and enforcement cannot be done on that type of file. +.P +Since sleeping on a region is interrupted with any signal, +\fIalarm\fR() +may be used to provide a timeout facility in applications requiring +it. This is useful in deadlock detection. Since implementation of +full deadlock detection is not always feasible, the +.BR [EDEADLK] +error was made optional. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIopen\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fdatasync.3p b/man-pages-posix-2013-a/man3p/fdatasync.3p new file mode 100644 index 0000000..728367a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fdatasync.3p @@ -0,0 +1,98 @@ +'\" et +.TH FDATASYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fdatasync +\(em synchronize the data of a file +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int fdatasync(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIfdatasync\fR() +function shall force all currently queued I/O operations associated +with the file indicated by file descriptor +.IR fildes +to the synchronized I/O completion state. +.P +The functionality shall be equivalent to +\fIfsync\fR() +with the symbol _POSIX_SYNCHRONIZED_IO defined, +with the exception that all I/O operations shall be completed as +defined for synchronized I/O data integrity completion. +.SH "RETURN VALUE" +If successful, the +\fIfdatasync\fR() +function shall return the value 0; otherwise, the function shall return +the value \(mi1 and set +.IR errno +to indicate the error. If the +\fIfdatasync\fR() +function fails, outstanding I/O operations are not guaranteed to have +been completed. +.SH ERRORS +The +\fIfdatasync\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor open for writing. +.TP +.BR EINVAL +This implementation does not support synchronized I/O for this file. +.P +In the event that any of the queued I/O operations fail, +\fIfdatasync\fR() +shall return the error conditions defined for +\fIread\fR() +and +\fIwrite\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_fsync\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfsync\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fdetach.3p b/man-pages-posix-2013-a/man3p/fdetach.3p new file mode 100644 index 0000000..198423f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fdetach.3p @@ -0,0 +1,174 @@ +'\" et +.TH FDETACH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fdetach +\(em detach a name from a STREAMS-based file descriptor (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int fdetach(const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIfdetach\fR() +function shall detach a STREAMS-based file from the file to which +it was attached by a previous call to +\fIfattach\fR(). +The +.IR path +argument points to the pathname of the attached STREAMS file. The +process shall have appropriate privileges or be the owner of the file. +A successful call to +\fIfdetach\fR() +shall cause all pathnames that named the attached STREAMS file to again +name the file to which the STREAMS file was attached. All subsequent +operations on +.IR path +shall operate on the underlying file and not on the STREAMS file. +.P +All open file descriptions established while the STREAMS file was +attached to the file referenced by +.IR path +shall still refer to the STREAMS file after the +\fIfdetach\fR() +has taken effect. +.P +If there are no open file descriptors or other references to the +STREAMS file, then a successful call to +\fIfdetach\fR() +shall be equivalent to performing the last +\fIclose\fR() +on the attached file. +.SH "RETURN VALUE" +Upon successful completion, +\fIfdetach\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfdetach\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR EINVAL +The +.IR path +argument names a file that is not currently attached. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID is not the owner of +.IR path +and the process does not have appropriate privileges. +.P +The +\fIfdetach\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Detaching a File" +.P +The following example detaches the STREAMS-based file +.BR /tmp/named-STREAM +from the file to which it was attached by a previous, successful call +to +\fIfattach\fR(). +Subsequent calls to open this file refer to the underlying file, not to +the STREAMS file. +.sp +.RS 4 +.nf +\fB +#include +\&... + char *pathname = "/tmp/named-STREAM"; + int ret; +.P + ret = fdetach(pathname); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIfdetach\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfattach\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fdim.3p b/man-pages-posix-2013-a/man3p/fdim.3p new file mode 100644 index 0000000..44ea76b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fdim.3p @@ -0,0 +1,148 @@ +'\" et +.TH FDIM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fdim, +fdimf, +fdiml +\(em compute positive difference between two floating-point numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double fdim(double \fIx\fP, double \fIy\fP); +float fdimf(float \fIx\fP, float \fIy\fP); +long double fdiml(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall determine the positive difference between their +arguments. If +.IR x +is greater than +.IR y , +.IR x \(mi\c +.IR y +is returned. If +.IR x +is less than or equal to +.IR y , ++0 is returned. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the positive +difference value. +.P +If +.IR x \(mi\c +.IR y +is positive and overflows, a range error shall occur and +\fIfdim\fR(), +\fIfdimf\fR(), +and +\fIfdiml\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If the correct value would cause underflow, a range error may occur, and +\fIfdim\fR(), +\fIfdimf\fR(), +and +\fIfdiml\fR() +shall return +the correct value, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.SH ERRORS +The +\fIfdim\fR() +function shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +The +\fIfdim\fR() +function may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfmax\fR\^(\|)", +.IR "\fIfmin\fR\^(\|)" +.P +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fdopen.3p b/man-pages-posix-2013-a/man3p/fdopen.3p new file mode 100644 index 0000000..cf1779e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fdopen.3p @@ -0,0 +1,194 @@ +'\" et +.TH FDOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fdopen +\(em associate a stream with a file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *fdopen(int \fIfildes\fP, const char *\fImode\fP); +.fi +.SH DESCRIPTION +The +\fIfdopen\fR() +function shall associate a stream with a file descriptor. +.P +The +.IR mode +argument is a character string having one of the following values: +.IP "\fIr\fP\ or\ \fIrb\fP" 14 +Open a file for reading. +.IP "\fIw\fP\ or\ \fIwb\fP" 14 +Open a file for writing. +.IP "\fIa\fP\ or\ \fIab\fP" 14 +Open a file for writing at end-of-file. +.IP "\fIr\fP+\ or\ \fIrb\fP+\ or\ \fIr\fP+\fIb\fP" 14 +Open a file for update (reading and writing). +.IP "\fIw\fP+\ or\ \fIwb\fP+\ or\ \fIw\fP+\fIb\fP" 14 +Open a file for update (reading and writing). +.IP "\fIa\fP+\ or\ \fIab\fP+\ or\ \fIa\fP+\fIb\fP" 14 +Open a file for update (reading and writing) at end-of-file. +.P +The meaning of these flags is exactly as specified in +\fIfopen\fR(), +except that modes beginning with +.IR w +shall not cause truncation of the file. +.P +Additional values for the +.IR mode +argument may be supported by an implementation. +.P +The application shall ensure that the mode of the stream as expressed +by the +.IR mode +argument is allowed by the file access mode of the open file +description to which +.IR fildes +refers. The file position indicator associated with the new stream is +set to the position indicated by the file offset associated with the +file descriptor. +.P +The error and end-of-file indicators for the stream shall be cleared. +The +\fIfdopen\fR() +function may cause the last data access timestamp of the underlying +file to be marked for update. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIfdopen\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIfdopen\fR() +function is unspecified. +.P +The +\fIfdopen\fR() +function shall preserve the offset maximum previously set for the +open file description corresponding to +.IR fildes . +.SH "RETURN VALUE" +Upon successful completion, +\fIfdopen\fR() +shall return a pointer to a stream; otherwise, a null pointer shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfdopen\fR() +function shall fail if: +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.P +The +\fIfdopen\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The +.IR mode +argument is not a valid mode. +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR ENOMEM +Insufficient space to allocate a buffer. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +File descriptors are obtained from calls like +\fIopen\fR(), +\fIdup\fR(), +\fIcreat\fR(), +or +\fIpipe\fR(), +which open files but do not return streams. +.SH RATIONALE +The file descriptor may have been obtained from +\fIopen\fR(), +\fIcreat\fR(), +\fIpipe\fR(), +\fIdup\fR(), +\fIfcntl\fR(), +or +\fIsocket\fR(); +inherited through +\fIfork\fR(), +\fIposix_spawn\fR(), +or +.IR exec ; +or perhaps obtained by other means. +.P +The meanings of the +.IR mode +arguments of +\fIfdopen\fR() +and +\fIfopen\fR() +differ. With +\fIfdopen\fR(), +open for write (\fIw\fP or \fIw+\fP) does not truncate, and append +(\fIa\fP or \fIa+\fP) cannot create for writing. The +.IR mode +argument formats that include a \fIb\fP are allowed for consistency +with the ISO\ C standard function +\fIfopen\fR(). +The \fIb\fP has no effect on the resulting stream. Although not +explicitly required by this volume of POSIX.1\(hy2008, a good implementation of append (\fIa\fP) +mode would cause the O_APPEND flag to be set. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fdopendir.3p b/man-pages-posix-2013-a/man3p/fdopendir.3p new file mode 100644 index 0000000..8e221e4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fdopendir.3p @@ -0,0 +1,314 @@ +'\" et +.TH FDOPENDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fdopendir, opendir +\(em open directory associated with file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +DIR *fdopendir(int \fIfd\fP); +DIR *opendir(const char *\fIdirname\fP); +.fi +.SH DESCRIPTION +The +\fIfdopendir\fR() +function shall be equivalent to the +\fIopendir\fR() +function except that the directory is specified by a file descriptor +rather than by a name. The file offset associated with the file +descriptor at the time of the call determines which entries are +returned. +.P +Upon successful return from +\fIfdopendir\fR(), +the file descriptor is under the control of the system, and if any +attempt is made to close the file descriptor, or to modify the state of +the associated description, other than by means of +\fIclosedir\fR(), +\fIreaddir\fR(), +\fIreaddir_r\fR(), +\fIrewinddir\fR(), +or +\fIseekdir\fR(), +the behavior is undefined. Upon calling +\fIclosedir\fR() +the file descriptor shall be closed. +.P +It is unspecified whether the FD_CLOEXEC flag will be set on the file +descriptor by a successful call to +\fIfdopendir\fR(). +.P +The +\fIopendir\fR() +function shall open a directory stream corresponding to the directory +named by the +.IR dirname +argument. The directory stream is positioned at the first entry. If +the type +.BR DIR +is implemented using a file descriptor, applications shall only be +able to open up to a total of +{OPEN_MAX} +files and directories. +.P +If the type +.BR DIR +is implemented using a file descriptor, the descriptor shall be +obtained as if the O_DIRECTORY flag was passed to +\fIopen\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +a pointer to an object of type +.BR DIR . +Otherwise, these functions shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfdopendir\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor open for reading. +.TP +.BR ENOTDIR +The descriptor +.IR fd +is not associated with a directory. +.P +The +\fIopendir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for the component of the path prefix of +.IR dirname +or read permission is denied for +.IR dirname . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR dirname +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR dirname +does not name an existing directory or +.IR dirname +is an empty string. +.TP +.BR ENOTDIR +A component of +.IR dirname +names an existing file that is neither a directory nor a symbolic link +to a directory. +.br +.P +The +\fIopendir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR dirname +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Open a Directory Stream" +.P +The following program fragment demonstrates how the +\fIopendir\fR() +function is used. +.sp +.RS 4 +.nf +\fB +#include +\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { + perror ("Cannot open ."); + exit (1); + } +.P + while ((dp = readdir (dir)) != NULL) { +\&... +.fi \fR +.P +.RE +.SS "Find And Open a File" +.P +The following program searches through a given directory looking +for files whose name does not begin with a dot and whose size is +larger than 1 MiB. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +#include +.P +int +main(int argc, char *argv[]) +{ + struct stat statbuf; + DIR *d; + struct dirent *dp; + int dfd, ffd; +.P + if ((d = fdopendir((dfd = open("./tmp", O_RDONLY)))) == NULL) { + fprintf(stderr, "Cannot open ./tmp directory\en"); + exit(1); + } + while ((dp = readdir(d)) != NULL) { + if (dp->d_name[0] == '.') + continue; + /* there is a possible race condition here as the file + * could be renamed between the readdir and the open */ + if ((ffd = openat(dfd, dp->d_name, O_RDONLY)) == -1) { + perror(dp->d_name); + continue; + } + if (fstat(ffd, &statbuf) == 0 && statbuf.st_size > (1024*1024)) { + /* found it ... */ + printf("%s: %jdK\en", dp->d_name, + (intmax_t)(statbuf.st_size / 1024)); + } + close(ffd); + } + closedir(d); // note this implicitly closes dfd + return 0; +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIopendir\fR() +function should be used in conjunction with +\fIreaddir\fR(), +\fIclosedir\fR(), +and +\fIrewinddir\fR() +to examine the contents of the directory (see the EXAMPLES section in +.IR "\fIreaddir\fR\^(\|)"). +This method is recommended for portability. +.SH RATIONALE +The purpose of the +\fIfdopendir\fR() +function is to enable opening files in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIopendir\fR(), +resulting in unspecified behavior. +.P +Based on historical implementations, the rules about file descriptors +apply to directory streams as well. However, this volume of POSIX.1\(hy2008 does not +mandate that the directory stream be implemented using file +descriptors. The description of +\fIclosedir\fR() +clarifies that if a file descriptor is used for the directory stream, +it is mandatory that +\fIclosedir\fR() +deallocate the file descriptor. When a file descriptor is used to +implement the directory stream, it behaves as if the FD_CLOEXEC +had been set for the file descriptor. +.P +The directory entries for dot +and dot-dot +are optional. This volume of POSIX.1\(hy2008 does not provide a way to test +.IR "a priori" +for their existence because an application that is portable must be +written to look for (and usually ignore) those entries. Writing code +that presumes that they are the first two entries does not always work, +as many implementations permit them to be other than the first two +entries, with a ``normal'' entry preceding them. There is negligible +value in providing a way to determine what the implementation does +because the code to deal with dot and dot-dot must be written in any +case and because such a flag would add to the list of those flags +(which has proven in itself to be objectionable) and might be abused. +.P +Since the structure and buffer allocation, if any, for directory +operations are defined by the implementation, this volume of POSIX.1\(hy2008 imposes no +portability requirements for erroneous program constructs, erroneous +data, or the use of unspecified values such as the use or referencing +of a +.IR dirp +value or a +.BR dirent +structure value after a directory stream has been closed or after a +\fIfork\fR() +or one of the +.IR exec +function calls. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIrewinddir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/feclearexcept.3p b/man-pages-posix-2013-a/man3p/feclearexcept.3p new file mode 100644 index 0000000..7daac9c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/feclearexcept.3p @@ -0,0 +1,69 @@ +'\" et +.TH FECLEAREXCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +feclearexcept +\(em clear floating-point exception +.SH SYNOPSIS +.LP +.nf +#include +.P +int feclearexcept(int \fIexcepts\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfeclearexcept\fR() +function shall attempt to clear the supported floating-point +exceptions represented by +.IR excepts . +.SH "RETURN VALUE" +If the argument is zero or if all the specified exceptions were +successfully cleared, +\fIfeclearexcept\fR() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfegetexceptflag\fR\^(\|)", +.IR "\fIferaiseexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fegetenv.3p b/man-pages-posix-2013-a/man3p/fegetenv.3p new file mode 100644 index 0000000..f396fe9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fegetenv.3p @@ -0,0 +1,89 @@ +'\" et +.TH FEGETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fegetenv, +fesetenv +\(em get and set current floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int fegetenv(fenv_t *\fIenvp\fP); +int fesetenv(const fenv_t *\fIenvp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfegetenv\fR() +function shall attempt to store the current floating-point environment +in the object pointed to by +.IR envp . +.P +The +\fIfesetenv\fR() +function shall attempt to establish the floating-point environment +represented by the object pointed to by +.IR envp . +The argument +.IR envp +shall point to an object set by a call to +\fIfegetenv\fR() +or +\fIfeholdexcept\fR(), +or equal a floating-point environment macro. The +\fIfesetenv\fR() +function does not raise floating-point exceptions, but only installs +the state of the floating-point status flags represented through its +argument. +.SH "RETURN VALUE" +If the representation was successfully stored, +\fIfegetenv\fR() +shall return zero. Otherwise, it shall return a non-zero value. +If the environment was successfully established, +\fIfesetenv\fR() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeholdexcept\fR\^(\|)", +.IR "\fIfeupdateenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fegetexceptflag.3p b/man-pages-posix-2013-a/man3p/fegetexceptflag.3p new file mode 100644 index 0000000..7e86259 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fegetexceptflag.3p @@ -0,0 +1,94 @@ +'\" et +.TH FEGETEXCEPTFLAG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fegetexceptflag, +fesetexceptflag +\(em get and set floating-point status flags +.SH SYNOPSIS +.LP +.nf +#include +.P +int fegetexceptflag(fexcept_t *\fIflagp\fP, int \fIexcepts\fP); +int fesetexceptflag(const fexcept_t *\fIflagp\fP, int \fIexcepts\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfegetexceptflag\fR() +function shall attempt to store an implementation-defined representation +of the states of the floating-point status flags indicated by the argument +.IR excepts +in the object pointed to by the argument +.IR flagp . +.P +The +\fIfesetexceptflag\fR() +function shall attempt to set the floating-point status flags indicated +by the argument +.IR excepts +to the states stored in the object pointed to by +.IR flagp . +The value pointed to by +.IR flagp +shall have been set by a previous call to +\fIfegetexceptflag\fR() +whose second argument represented at least those floating-point +exceptions represented by the argument +.IR excepts . +This function does not raise floating-point exceptions, but only sets +the state of the flags. +.SH "RETURN VALUE" +If the representation was successfully stored, +\fIfegetexceptflag\fR() +shall return zero. Otherwise, it shall return a non-zero value. If the +.IR excepts +argument is zero or if all the specified exceptions were successfully +set, +\fIfesetexceptflag\fR() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIferaiseexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fegetround.3p b/man-pages-posix-2013-a/man3p/fegetround.3p new file mode 100644 index 0000000..f3ba4a5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fegetround.3p @@ -0,0 +1,103 @@ +'\" et +.TH FEGETROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fegetround, +fesetround +\(em get and set current rounding direction +.SH SYNOPSIS +.LP +.nf +#include +.P +int fegetround(void); +int fesetround(int \fIround\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfegetround\fR() +function shall get the current rounding direction. +.P +The +\fIfesetround\fR() +function shall establish the rounding direction represented by its +argument +.IR round . +If the argument is not equal to the value of a rounding direction +macro, the rounding direction is not changed. +.SH "RETURN VALUE" +The +\fIfegetround\fR() +function shall return the value of the rounding direction macro +representing the current rounding direction or a negative value if +there is no such rounding direction macro or the current rounding +direction is not determinable. +.P +The +\fIfesetround\fR() +function shall return a zero value if and only if the requested +rounding direction was established. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example saves, sets, and restores the rounding direction, +reporting an error and aborting if setting the rounding direction +fails: +.sp +.RS 4 +.nf +\fB +#include +#include +void f(int round_dir) +{ + #pragma STDC FENV_ACCESS ON + int save_round; + int setround_ok; + save_round = fegetround(); + setround_ok = fesetround(round_dir); + assert(setround_ok == 0); + /* ... */ + fesetround(save_round); + /* ... */ +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/feholdexcept.3p b/man-pages-posix-2013-a/man3p/feholdexcept.3p new file mode 100644 index 0000000..26ee32b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/feholdexcept.3p @@ -0,0 +1,76 @@ +'\" et +.TH FEHOLDEXCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +feholdexcept +\(em save current floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int feholdexcept(fenv_t *\fIenvp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfeholdexcept\fR() +function shall save the current floating-point environment in the +object pointed to by +.IR envp , +clear the floating-point status flags, and then install a non-stop +(continue on floating-point exceptions) mode, if available, for all +floating-point exceptions. +.SH "RETURN VALUE" +The +\fIfeholdexcept\fR() +function shall return zero if and only if non-stop floating-point +exception handling was successfully installed. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIfeholdexcept\fR() +function should be effective on typical IEC\ 60559:\|1989 standard implementations which +have the default non-stop mode and at least one other mode for trap +handling or aborting. If the implementation provides only the non-stop +mode, then installing the non-stop mode is trivial. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfegetenv\fR\^(\|)", +.IR "\fIfeupdateenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/feof.3p b/man-pages-posix-2013-a/man3p/feof.3p new file mode 100644 index 0000000..5ffc49f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/feof.3p @@ -0,0 +1,78 @@ +'\" et +.TH FEOF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +feof +\(em test end-of-file indicator on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int feof(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfeof\fR() +function shall test the end-of-file indicator for the stream pointed +to by +.IR stream . +.P +The +\fIfeof\fR() +function shall not change the setting of +.IR errno +if +.IR stream +is valid. +.SH "RETURN VALUE" +The +\fIfeof\fR() +function shall return non-zero if and only if the end-of-file +indicator is set for +.IR stream . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclearerr\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/feraiseexcept.3p b/man-pages-posix-2013-a/man3p/feraiseexcept.3p new file mode 100644 index 0000000..8a9aff3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/feraiseexcept.3p @@ -0,0 +1,82 @@ +'\" et +.TH FERAISEEXCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +feraiseexcept +\(em raise floating-point exception +.SH SYNOPSIS +.LP +.nf +#include +.P +int feraiseexcept(int \fIexcepts\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIferaiseexcept\fR() +function shall attempt to raise the supported floating-point exceptions +represented by the argument +.IR excepts . +The order in which these floating-point exceptions are raised is +unspecified. Whether the +\fIferaiseexcept\fR() +function additionally raises the inexact floating-point exception +whenever it raises the overflow or underflow floating-point exception +is implementation-defined. +.SH "RETURN VALUE" +If the argument is zero or if all the specified exceptions were +successfully raised, +\fIferaiseexcept\fR() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The effect is intended to be similar to that of floating-point +exceptions raised by arithmetic operations. Hence, enabled traps for +floating-point exceptions raised by this function are taken. +.SH RATIONALE +Raising overflow or underflow is allowed to also raise inexact because +on some architectures the only practical way to raise an exception is +to execute an instruction that has the exception as a side-effect. The +function is not restricted to accept only valid coincident expressions +for atomic operations, so the function can be used to raise exceptions +accrued over several operations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfegetexceptflag\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ferror.3p b/man-pages-posix-2013-a/man3p/ferror.3p new file mode 100644 index 0000000..7228256 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ferror.3p @@ -0,0 +1,77 @@ +'\" et +.TH FERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ferror +\(em test error indicator on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int ferror(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIferror\fR() +function shall test the error indicator for the stream pointed to by +.IR stream . +.P +The +\fIferror\fR() +function shall not change the setting of +.IR errno +if +.IR stream +is valid. +.SH "RETURN VALUE" +The +\fIferror\fR() +function shall return non-zero if and only if the error indicator is +set for +.IR stream . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclearerr\fR\^(\|)", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fesetenv.3p b/man-pages-posix-2013-a/man3p/fesetenv.3p new file mode 100644 index 0000000..4fb238c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fesetenv.3p @@ -0,0 +1,38 @@ +'\" et +.TH FESETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fesetenv +\(em set current floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int fesetenv(const fenv_t *\fIenvp\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfegetenv\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fesetexceptflag.3p b/man-pages-posix-2013-a/man3p/fesetexceptflag.3p new file mode 100644 index 0000000..c452f55 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fesetexceptflag.3p @@ -0,0 +1,38 @@ +'\" et +.TH FESETEXCEPTFLAG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fesetexceptflag +\(em set floating-point status flags +.SH SYNOPSIS +.LP +.nf +#include +.P +int fesetexceptflag(const fexcept_t *\fIflagp\fP, int \fIexcepts\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfegetexceptflag\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fesetround.3p b/man-pages-posix-2013-a/man3p/fesetround.3p new file mode 100644 index 0000000..7578f8b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fesetround.3p @@ -0,0 +1,38 @@ +'\" et +.TH FESETROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fesetround +\(em set current rounding direction +.SH SYNOPSIS +.LP +.nf +#include +.P +int fesetround(int \fIround\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfegetround\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fetestexcept.3p b/man-pages-posix-2013-a/man3p/fetestexcept.3p new file mode 100644 index 0000000..f2b7b1a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fetestexcept.3p @@ -0,0 +1,95 @@ +'\" et +.TH FETESTEXCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fetestexcept +\(em test floating-point exception flags +.SH SYNOPSIS +.LP +.nf +#include +.P +int fetestexcept(int \fIexcepts\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfetestexcept\fR() +function shall determine which of a specified subset of the +floating-point exception flags are currently set. The +.IR excepts +argument specifies the floating-point status flags to be queried. +.SH "RETURN VALUE" +The +\fIfetestexcept\fR() +function shall return the value of the bitwise-inclusive OR of the +floating-point exception macros corresponding to the currently set +floating-point exceptions included in +.IR excepts . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example calls function +\fIf\fR() +if an invalid exception is set, and then function +\fIg\fR() +if an overflow exception is set: +.sp +.RS 4 +.nf +\fB +#include +/* ... */ +{ + #pragma STDC FENV_ACCESS ON + int set_excepts; + feclearexcept(FE_INVALID | FE_OVERFLOW); + // maybe raise exceptions + set_excepts = fetestexcept(FE_INVALID | FE_OVERFLOW); + if (set_excepts & FE_INVALID) f(); + if (set_excepts & FE_OVERFLOW) g(); + /* ... */ +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfegetexceptflag\fR\^(\|)", +.IR "\fIferaiseexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/feupdateenv.3p b/man-pages-posix-2013-a/man3p/feupdateenv.3p new file mode 100644 index 0000000..df6c78f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/feupdateenv.3p @@ -0,0 +1,98 @@ +'\" et +.TH FEUPDATEENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +feupdateenv +\(em update floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int feupdateenv(const fenv_t *\fIenvp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfeupdateenv\fR() +function shall attempt to save the currently raised floating-point +exceptions in its automatic storage, attempt to install the +floating-point environment represented by the object pointed to by +.IR envp , +and then attempt to raise the saved floating-point exceptions. The +argument +.IR envp +shall point to an object set by a call to +\fIfeholdexcept\fR() +or +\fIfegetenv\fR(), +or equal a floating-point environment macro. +.SH "RETURN VALUE" +The +\fIfeupdateenv\fR() +function shall return a zero value if and only if all the required +actions were successfully carried out. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example shows sample code to hide spurious underflow +floating-point exceptions: +.sp +.RS 4 +.nf +\fB +#include +double f(double x) +{ + #pragma STDC FENV_ACCESS ON + double result; + fenv_t save_env; + feholdexcept(&save_env); + // compute result + if (/* test spurious underflow */) + feclearexcept(FE_UNDERFLOW); + feupdateenv(&save_env); + return result; +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfegetenv\fR\^(\|)", +.IR "\fIfeholdexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fexecve.3p b/man-pages-posix-2013-a/man3p/fexecve.3p new file mode 100644 index 0000000..b866db7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fexecve.3p @@ -0,0 +1,37 @@ +'\" et +.TH FEXECVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fexecve \(em execute a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int fexecve(int \fIfd\fP, char *const \fIargv[]\fP, char *const \fIenvp[]\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIexec\fR\^". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fflush.3p b/man-pages-posix-2013-a/man3p/fflush.3p new file mode 100644 index 0000000..3ddfe4a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fflush.3p @@ -0,0 +1,214 @@ +'\" et +.TH FFLUSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fflush +\(em flush a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fflush(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If +.IR stream +points to an output stream or an update stream in which the most recent +operation was not input, +\fIfflush\fR() +shall cause any unwritten data for that stream to be written to the +file, +and the last data modification and last file status change timestamps +of the underlying file shall be marked for update. +.P +If +.IR stream +is a null pointer, +\fIfflush\fR() +shall perform this flushing action on all streams for which the +behavior is defined above. +.P +For a stream open for reading, if the file is not already at EOF, and +the file is one capable of seeking, the file offset of the underlying +open file description shall be set to the file position of the stream, +and any characters pushed back onto the stream by +\fIungetc\fR() +or +\fIungetwc\fR() +that have not subsequently been read from the stream shall be discarded +(without further changing the file offset). +.SH "RETURN VALUE" +Upon successful completion, +\fIfflush\fR() +shall return 0; otherwise, it shall set the error indicator for +the stream, return EOF, +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfflush\fR() +function shall fail if: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not valid. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the maximum file size. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the file size +limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding stream. +.TP +.BR EINTR +The +\fIfflush\fR() +function was interrupted by a signal. +.TP +.BR EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the calling thread +is not blocking SIGTTOU, the process is not ignoring SIGTTOU, and the +process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOMEM +The underlying stream was created by +\fIopen_memstream\fR() +or +\fIopen_wmemstream\fR() +and insufficient memory is available. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file or +in the buffer used by the +\fIfmemopen\fR() +function. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process. A SIGPIPE signal shall also be sent to the thread. +.P +The +\fIfflush\fR() +function may fail if: +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was +outside the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Sending Prompts to Standard Output" +.P +The following example uses +\fIprintf\fR() +calls to print a series of prompts for information the user must enter +from standard input. The +\fIfflush\fR() +calls force the output to standard output. The +\fIfflush\fR() +function is used because standard output is usually buffered and the +prompt may not immediately be printed on the output or terminal. The +\fIgetline\fR() +function calls read strings from standard input and place the +results in variables, for use later in the program. +.sp +.RS 4 +.nf +\fB +char *user; +char *oldpasswd; +char *newpasswd; +ssize_t llen; +size_t blen; +struct termios term; +tcflag_t saveflag; +.P +printf("User name: "); +fflush(stdout); +blen = 0; +llen = getline(&user, &blen, stdin); +user[llen-1] = 0; +tcgetattr(fileno(stdin), &term); +saveflag = term.c_lflag; +term.c_lflag &= ~ECHO; +tcsetattr(fileno(stdin), TCSANOW, &term); +printf("Old password: "); +fflush(stdout); +blen = 0; +llen = getline(&oldpasswd, &blen, stdin); +oldpasswd[llen-1] = 0; +.P +printf("\enNew password: "); +fflush(stdout); +blen = 0; +llen = getline(&newpasswd, &blen, stdin); +newpasswd[llen-1] = 0; +term.c_lflag = saveflag; +tcsetattr(fileno(stdin), TCSANOW, &term); +free(user); +free(oldpasswd); +free(newpasswd); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Data buffered by the system may make determining the validity of the +position of the current file descriptor impractical. Thus, enforcing +the repositioning of the file descriptor after +\fIfflush\fR() +on streams open for +\fIread\fR() +is not mandated by POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ffs.3p b/man-pages-posix-2013-a/man3p/ffs.3p new file mode 100644 index 0000000..4b41368 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ffs.3p @@ -0,0 +1,66 @@ +'\" et +.TH FFS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ffs +\(em find first set bit +.SH SYNOPSIS +.LP +.nf +#include +.P +int ffs(int \fIi\fP); +.fi +.SH DESCRIPTION +The +\fIffs\fR() +function shall find the first bit set (beginning with the least +significant bit) in +.IR i , +and return the index of that bit. Bits are numbered starting at one +(the least significant bit). +.SH "RETURN VALUE" +The +\fIffs\fR() +function shall return the index of the first bit set. If +.IR i +is 0, then +\fIffs\fR() +shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fgetc.3p b/man-pages-posix-2013-a/man3p/fgetc.3p new file mode 100644 index 0000000..fbc8008 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fgetc.3p @@ -0,0 +1,175 @@ +'\" et +.TH FGETC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fgetc +\(em get a byte from a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fgetc(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If the end-of-file indicator for the input stream pointed to by +.IR stream +is not set and a next byte is present, the +\fIfgetc\fR() +function shall obtain the next byte as an +.BR "unsigned char" +converted to an +.BR int , +from the input stream pointed to by +.IR stream , +and advance the associated file position indicator for the stream (if +defined). Since +\fIfgetc\fR() +operates on bytes, reading a character consisting of multiple bytes (or +``a multi-byte character'') may require multiple calls to +\fIfgetc\fR(). +.P +The +\fIfgetc\fR() +function may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be marked for +update by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfgetc\fR() +shall return the next byte from the input stream pointed to by +.IR stream . +If the end-of-file indicator for the stream is set, or if the +stream is at end-of-file, the end-of-file indicator for the +stream shall be set and +\fIfgetc\fR() +shall return EOF. If a read error occurs, the error indicator for the +stream shall be set, +\fIfgetc\fR() +shall return EOF, +and shall set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfgetc\fR() +function shall fail if data needs to be read and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the +\fIfgetc\fR() +operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor open for reading. +.TP +.BR EINTR +The read operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is in a background +process group attempting to read from its controlling terminal, and +either the calling thread is blocking SIGTTIN or the process is ignoring +SIGTTIN or the process group of the process is orphaned. +This error may also be generated for implementation-defined reasons. +.TP +.BR EOVERFLOW +The file is a regular file and an attempt was made to read at or beyond +the offset maximum associated with the corresponding stream. +.P +The +\fIfgetc\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the integer value returned by +\fIfgetc\fR() +is stored into a variable of type +.BR char +and then compared against the integer constant EOF, the comparison may +never succeed, because sign-extension of a variable of type +.BR char +on widening to integer is implementation-defined. +.P +The +\fIferror\fR() +or +\fIfeof\fR() +functions must be used to distinguish between an error condition and an +end-of-file condition. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fgetpos.3p b/man-pages-posix-2013-a/man3p/fgetpos.3p new file mode 100644 index 0000000..913d90c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fgetpos.3p @@ -0,0 +1,101 @@ +'\" et +.TH FGETPOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fgetpos +\(em get current file position information +.SH SYNOPSIS +.LP +.nf +#include +.P +int fgetpos(FILE *restrict \fIstream\fP, fpos_t *restrict \fIpos\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfgetpos\fR() +function shall store the current values of the parse state (if any) +and file position indicator for the stream pointed to by +.IR stream +in the object pointed to by +.IR pos . +The value stored contains unspecified information usable by +\fIfsetpos\fR() +for repositioning the stream to its position at the time of the call to +\fIfgetpos\fR(). +.P +The +\fIfgetpos\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +Upon successful completion, +\fIfgetpos\fR() +shall return 0; otherwise, it shall return a non-zero value and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfgetpos\fR() +function shall fail if: +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not valid. +.TP +.BR EOVERFLOW +The current value of the file position cannot be represented correctly +in an object of type +.BR fpos_t . +.TP +.BR ESPIPE +The file descriptor underlying +.IR stream +is associated with a pipe, FIFO, or socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIftell\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fgets.3p b/man-pages-posix-2013-a/man3p/fgets.3p new file mode 100644 index 0000000..bad0ccf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fgets.3p @@ -0,0 +1,176 @@ +'\" et +.TH FGETS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fgets +\(em get a string from a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +char *fgets(char *restrict \fIs\fP, int \fIn\fP, FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfgets\fR() +function shall read bytes from +.IR stream +into the array pointed to by +.IR s , +until +.IR n \(mi1 +bytes are read, or a + +is read and transferred to +.IR s , +or an end-of-file condition is encountered. The string is then +terminated with a null byte. +.P +The +\fIfgets\fR() +function may mark the last data access timestamp of the file associated +with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfgets\fR() +shall return +.IR s . +If the stream is at end-of-file, the end-of-file indicator for +the stream shall be set and +\fIfgets\fR() +shall return a null pointer. +If a read error occurs, the error indicator for the stream shall be set, +\fIfgets\fR() +shall return a null pointer, +and shall set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading Input" +.P +The following example uses +\fIfgets\fR() +to read lines of input. It assumes that the file it is reading is a text +file and that lines in this text file are no longer than 16384 (or +{LINE_MAX} +if it is less than 16384 on the implementation where it is running) +bytes long. (Note that the standard utilities have no line length limit if +.IR sysconf (_SC_LINE_MAX) +returns \(mi1 without setting +.IR errno . +This example assumes that +.IR sysconf (_SC_LINE_MAX) +will not fail.) +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#define MYLIMIT 16384 +.P +char *line; +int line_max; +if (LINE_MAX >= MYLIMIT) { + // Use maximum line size of MYLIMIT. If LINE_MAX is + // bigger than our limit, sysconf() can't report a + // smaller limit. + line_max = MYLIMIT; +} else { + long limit = sysconf(_SC_LINE_MAX); + line_max = (limit < 0 || limit > MYLIMIT) ? MYLIMIT : (int)limit; +} +.P +// line_max + 1 leaves room for the null byte added by fgets(). +line = malloc(line_max + 1); +if (line == NULL) { + // out of space + ... + return error; +} +.P +while (fgets(line, line_max + 1, fp) != NULL) { + // Verify that a full line has been read ... + // If not, report an error or prepare to treat the + // next time through the loop as a read of a + // continuation of the current line. + ... + // Process line ... + ... +} +free(line); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIgetdelim\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fgetwc.3p b/man-pages-posix-2013-a/man3p/fgetwc.3p new file mode 100644 index 0000000..3aa1dc7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fgetwc.3p @@ -0,0 +1,174 @@ +'\" et +.TH FGETWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fgetwc +\(em get a wide-character code from a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t fgetwc(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfgetwc\fR() +function shall obtain the next character (if present) from the input +stream pointed to by +.IR stream , +convert that to the corresponding wide-character code, and advance the +associated file position indicator for the stream (if defined). +.P +If an error occurs, the resulting value of the file position indicator +for the stream is unspecified. +.P +The +\fIfgetwc\fR() +function may mark the last data access timestamp of the file associated +with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetwc\fR(), +\fIfgetws\fR(), +\fIfwscanf\fR(), +\fIgetwc\fR(), +\fIgetwchar\fR(), +\fIvfwscanf\fR(), +\fIvwscanf\fR(), +or +\fIwscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetwc\fR(). +.P +The +\fIfgetwc\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +Upon successful completion, the +\fIfgetwc\fR() +function shall return the wide-character code of the character read from the +input stream pointed to by +.IR stream +converted to a type +.BR wint_t . +If the end-of-file indicator for the stream is set, or if the stream is +at end-of-file, the end-of-file indicator for the stream shall be set +and +\fIfgetwc\fR() +shall return WEOF. If a read error occurs, the error indicator for the +stream shall be set, +\fIfgetwc\fR() +shall return WEOF, +and shall set +.IR errno +to indicate the error. +If an encoding error occurs, the error indicator for the stream +shall be set, +\fIfgetwc\fR() +shall return WEOF, and shall set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfgetwc\fR() +function shall fail if data needs to be read and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the +\fIfgetwc\fR() +operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor open for reading. +.TP +.BR EILSEQ +The data obtained from the input stream does not form a valid +character. +.TP +.BR EINTR +The read operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is in a background +process group attempting to read from its controlling terminal, and +either the calling thread is blocking SIGTTIN or the process is ignoring +SIGTTIN or the process group of the process is orphaned. +This error may also be generated for implementation-defined reasons. +.TP +.BR EOVERFLOW +The file is a regular file and an attempt was made to read at or beyond +the offset maximum associated with the corresponding stream. +.br +.P +The +\fIfgetwc\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIferror\fR() +or +\fIfeof\fR() +functions must be used to distinguish between an error condition and an +end-of-file condition. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fgetws.3p b/man-pages-posix-2013-a/man3p/fgetws.3p new file mode 100644 index 0000000..96e442a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fgetws.3p @@ -0,0 +1,121 @@ +'\" et +.TH FGETWS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fgetws +\(em get a wide-character string from a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wchar_t *fgetws(wchar_t *restrict \fIws\fP, int \fIn\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfgetws\fR() +function shall read characters from the +.IR stream , +convert these to the corresponding wide-character codes, place them +in the +.BR wchar_t +array pointed to by +.IR ws , +until +.IR n \(mi1 +characters are read, or a + +is read, converted, and transferred to +.IR ws , +or an end-of-file condition is encountered. The wide-character string, +.IR ws , +shall then be terminated with a null wide-character code. +.P +If an error occurs, the resulting value of the file position indicator +for the stream is unspecified. +.P +The +\fIfgetws\fR() +function may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetwc\fR(), +\fIfgetws\fR(), +\fIfwscanf\fR(), +\fIgetwc\fR(), +\fIgetwchar\fR(), +\fIvfwscanf\fR(), +\fIvwscanf\fR(), +or +\fIwscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetwc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfgetws\fR() +shall return +.IR ws . +If the end-of-file indicator for the stream is set, or if the stream +is at end-of-file, the end-of-file indicator for the +stream shall be set and +\fIfgetws\fR() +shall return a null pointer. If a read error occurs, the error +indicator for the stream shall be set, +\fIfgetws\fR() +shall return a null pointer, +and shall set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fileno.3p b/man-pages-posix-2013-a/man3p/fileno.3p new file mode 100644 index 0000000..c47a132 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fileno.3p @@ -0,0 +1,88 @@ +'\" et +.TH FILENO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fileno +\(em map a stream pointer to a file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int fileno(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The +\fIfileno\fR() +function shall return the integer file descriptor associated with +the stream pointed to by +.IR stream . +.SH "RETURN VALUE" +Upon successful completion, +\fIfileno\fR() +shall return the integer value of the file descriptor associated with +.IR stream . +Otherwise, the value \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfileno\fR() +function may fail if: +.TP +.BR EBADF +The +.IR stream +argument is not a valid stream, or the stream is not associated +with a file. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Without some specification of which file descriptors are associated +with these streams, it is impossible for an application to set up the +streams for another application it starts with +\fIfork\fR() +and +.IR exec . +In particular, it would not be possible to write a portable version of +the +.IR sh +command interpreter (although there may be other constraints that would +prevent that portability). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIstdin\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/flockfile.3p b/man-pages-posix-2013-a/man3p/flockfile.3p new file mode 100644 index 0000000..4c2293c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/flockfile.3p @@ -0,0 +1,190 @@ +'\" et +.TH FLOCKFILE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +flockfile, +ftrylockfile, +funlockfile +\(em stdio locking functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void flockfile(FILE *\fIfile\fP); +int ftrylockfile(FILE *\fIfile\fP); +void funlockfile(FILE *\fIfile\fP); +.fi +.SH DESCRIPTION +These functions shall provide for explicit application-level locking of +stdio (\c +.BR "FILE *" ) +objects. These functions can be used by a thread to delineate a +sequence of I/O statements that are executed as a unit. +.P +The +\fIflockfile\fR() +function shall acquire for a thread ownership of a (\c +.BR "FILE *" ) +object. +.P +The +\fIftrylockfile\fR() +function shall acquire for a thread ownership of a (\c +.BR "FILE *" ) +object if the object is available; +\fIftrylockfile\fR() +is a non-blocking version of +\fIflockfile\fR(). +.P +The +\fIfunlockfile\fR() +function shall relinquish the ownership granted to the thread. +The behavior is undefined if a thread other than the current owner +calls the +\fIfunlockfile\fR() +function. +.P +The functions shall behave as if there is a lock count associated with +each (\c +.BR "FILE *" ) +object. This count is implicitly initialized to zero when the (\c +.BR "FILE *" ) +object is created. The (\c +.BR "FILE *" ) +object is unlocked when the count is zero. When the count is positive, +a single thread owns the (\c +.BR "FILE *" ) +object. When the +\fIflockfile\fR() +function is called, if the count is zero or if the count is positive +and the caller owns the (\c +.BR "FILE *" ) +object, the count shall be incremented. Otherwise, the calling thread +shall be suspended, waiting for the count to return to zero. Each call +to +\fIfunlockfile\fR() +shall decrement the count. This allows matching calls to +\fIflockfile\fR() +(or successful calls to +\fIftrylockfile\fR()) +and +\fIfunlockfile\fR() +to be nested. +.P +All functions that reference (\c +.BR "FILE *" ) +objects, except those with names ending in +.IR _unlocked , +shall behave as if they use +\fIflockfile\fR() +and +\fIfunlockfile\fR() +internally to obtain ownership of these (\c +.BR "FILE *" ) +objects. +.SH "RETURN VALUE" +None for +\fIflockfile\fR() +and +\fIfunlockfile\fR(). +.P +The +\fIftrylockfile\fR() +function shall return zero for success and non-zero to indicate +that the lock cannot be acquired. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +The +\fIflockfile\fR() +and +\fIfunlockfile\fR() +functions provide an orthogonal mutual-exclusion lock for each +.BR FILE . +The +\fIftrylockfile\fR() +function provides a non-blocking attempt to acquire a file lock, +analogous to +\fIpthread_mutex_trylock\fR(). +.P +These locks behave as if they are the same as those used internally by +.IR stdio +for thread-safety. +This both provides thread-safety of these functions without requiring a +second level of internal locking and allows functions in +.IR stdio +to be implemented in terms of other +.IR stdio +functions. +.P +Application developers and implementors should be aware that there are +potential deadlock problems on +.BR FILE +objects. For example, the line-buffered flushing semantics of +.IR stdio +(requested via {_IOLBF}) +require that certain input operations sometimes cause the buffered +contents of implementation-defined line-buffered output streams to be +flushed. If two threads each hold the lock on the other's +.BR FILE , +deadlock ensues. This type of deadlock can be avoided by acquiring +.BR FILE +locks in a consistent order. In particular, the line-buffered output +stream deadlock can typically be avoided by acquiring locks on input +streams before locks on output streams if a thread would be acquiring +both. +.P +In summary, threads sharing +.IR stdio +streams with other threads can use +\fIflockfile\fR() +and +\fIfunlockfile\fR() +to cause sequences of I/O performed by a single thread to be kept +bundled. The only case where the use of +\fIflockfile\fR() +and +\fIfunlockfile\fR() +is required is to provide a scope protecting uses of the +.IR *_unlocked +functions/macros. This moves the cost/performance tradeoff to the +optimal point. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetc_unlocked\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/floor.3p b/man-pages-posix-2013-a/man3p/floor.3p new file mode 100644 index 0000000..569f1d3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/floor.3p @@ -0,0 +1,97 @@ +'\" et +.TH FLOOR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +floor, +floorf, +floorl +\(em floor function +.SH SYNOPSIS +.LP +.nf +#include +.P +double floor(double \fIx\fP); +float floorf(float \fIx\fP); +long double floorl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the largest integral value not greater +than +.IR x . +.SH "RETURN VALUE" +The result shall have the same sign as +.IR x . +.P +Upon successful completion, these functions shall return the largest +integral value not greater than +.IR x , +expressed as a +.BR double , +.BR float , +or +.BR "long double" , +as appropriate for the return type of the function. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions might not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer +type to avoid the undefined results of an integer overflow. +.P +These functions may raise the inexact floating-point exception if the +result differs in value from the argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIceil\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fma.3p b/man-pages-posix-2013-a/man3p/fma.3p new file mode 100644 index 0000000..75ae21e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fma.3p @@ -0,0 +1,209 @@ +'\" et +.TH FMA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fma, +fmaf, +fmal +\(em floating-point multiply-add +.SH SYNOPSIS +.LP +.nf +#include +.P +double fma(double \fIx\fP, double \fIy\fP, double \fIz\fP); +float fmaf(float \fIx\fP, float \fIy\fP, float \fIz\fP); +long double fmal(long double \fIx\fP, long double \fIy\fP, long double \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute (\fIx\fR\ *\ \fIy\fR)\ +\ \fIz\fR, +rounded as one ternary operation: they shall compute the value (as if) +to infinite precision and round once to the result format, according to +the rounding mode characterized by the value of FLT_ROUNDS. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +(\fIx\fR\ *\ \fIy\fR)\ + \fIz\fR, rounded as one ternary operation. +.P +If the result overflows or underflows, a range error may occur. +On systems that support the IEC 60559 Floating-Point option, if the +result overflows a range error shall occur. +.P +If +.IR x +or +.IR y +are NaN, a NaN shall be returned. +.P +If +.IR x +multiplied by +.IR y +is an exact infinity and +.IR z +is also an infinity but with the opposite sign, a domain error shall +occur, and either a NaN (if supported), or an implementation-defined +value shall be returned. +.P +If one of +.IR x +and +.IR y +is infinite, the other is zero, and +.IR z +is not a NaN, a domain error shall occur, and either a NaN (if +supported), or an implementation-defined value shall be returned. +.P +If one of +.IR x +and +.IR y +is infinite, the other is zero, and +.IR z +is a NaN, a NaN shall be returned and a domain error may occur. +.P +If +.IR x *\c +.IR y +is not 0*Inf nor Inf*0 and +.IR z +is a NaN, a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The value of +.IR x *\c +.IR y +\c +.IR z +is invalid, or the value +.IR x *\c +.IR y +is invalid and +.IR z +is not a NaN. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.br +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The value +.IR x *\c +.IR y +is invalid and +.IR z +is a NaN. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +In many cases, clever use of floating (\fIfused\fR) multiply-add leads +to much improved code; but its unexpected use by the compiler can +undermine carefully written code. The FP_CONTRACT macro can be used to +disallow use of floating multiply-add; and the +\fIfma\fR() +function guarantees its use where desired. Many current machines +provide hardware floating multiply-add instructions; software +implementation can be used for others. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fmax.3p b/man-pages-posix-2013-a/man3p/fmax.3p new file mode 100644 index 0000000..151663a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fmax.3p @@ -0,0 +1,78 @@ +'\" et +.TH FMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fmax, +fmaxf, +fmaxl +\(em determine maximum numeric value of two floating-point numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double fmax(double \fIx\fP, double \fIy\fP); +float fmaxf(float \fIx\fP, float \fIy\fP); +long double fmaxl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall determine the maximum numeric value of their +arguments. +NaN arguments shall be treated as missing data: if one argument +is a NaN and the other numeric, then these functions shall +choose the numeric value. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the maximum +numeric value of their arguments. +.P +If just one argument is a NaN, the other argument shall be returned. +.P +If +.IR x +and +.IR y +are NaN, a NaN shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdim\fR\^(\|)", +.IR "\fIfmin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fmemopen.3p b/man-pages-posix-2013-a/man3p/fmemopen.3p new file mode 100644 index 0000000..fa3b384 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fmemopen.3p @@ -0,0 +1,280 @@ +'\" et +.TH FMEMOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fmemopen +\(em open a memory buffer stream +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *fmemopen(void *restrict \fIbuf\fP, size_t \fIsize\fP, + const char *restrict \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIfmemopen\fR() +function shall associate the buffer given by the +.IR buf +and +.IR size +arguments with a stream. The +.IR buf +argument shall be either a null pointer or point to a buffer that is at +least +.IR size +bytes long. +.P +The +.IR mode +argument points to a string. If the string is one of the following, +the stream shall be opened in the indicated mode. Otherwise, the behavior +is undefined. +.IP "\fIr\fP" 8 +Open the stream for reading. +.IP "\fIw\fP" 8 +Open the stream for writing. +.IP "\fIa\fP" 8 +Append; open the stream for writing at the first null byte. +.IP "\fIr\fP+" 8 +Open the stream for update (reading and writing). +.IP "\fIw\fP+" 8 +Open the stream for update (reading and writing). Truncate the +buffer contents. +.IP "\fIa\fP+" 8 +Append; open the stream for update (reading and writing); +the initial position is at the first null byte. +.P +Implementations shall accept all mode strings allowed by +\fIfopen\fR(), +but the use of the character +.BR 'b' +shall produce implementation-defined results, where the resulting +.BR "FILE *" +need not behave the same as if +.BR 'b' +were omitted. +.P +If a null pointer is specified as the +.IR buf +argument, +\fIfmemopen\fR() +shall allocate +.IR size +bytes of memory as if by a call to +\fImalloc\fR(). +This buffer shall be automatically freed when the stream is closed. +Because this feature is only useful when the stream is opened for +updating (because there is no way to get a pointer to the buffer) the +\fIfmemopen\fR() +call may fail if the +.IR mode +argument does not include a +.BR '+' . +.P +The stream shall maintain a current position in the buffer. This position +shall be initially set to either the beginning of the buffer (for +.IR r +and +.IR w +modes) or to the first null byte in the buffer (for +.IR a +modes). If no null byte is found in append mode, the initial position +shall be set to one byte after the end of the buffer. +.P +If +.IR buf +is a null pointer, the initial position shall always be set to the +beginning of the buffer. +.P +The stream shall also maintain the size of the current buffer contents; +use of +\fIfseek\fR() +or +\fIfseeko\fR() +on the stream with SEEK_END shall seek relative to this size. For modes +.IR r +and +.IR r+ +the size shall be set to the value given by the +.IR size +argument. For modes +.IR w +and +.IR w+ +the initial size shall be zero and for modes +.IR a +and +.IR a+ +the initial size shall be either the position of the first null byte in +the buffer or the value of the +.IR size +argument if no null byte is found. +.P +A read operation on the stream shall not advance the current buffer +position beyond the current buffer size. Reaching the buffer size in a +read operation shall count as ``end-of-file''. Null bytes in the buffer +shall have no special meaning for reads. The read operation shall start +at the current buffer position of the stream. +.P +A write operation shall start either at the current position of the stream +(if +.IR mode +has not specified +.BR 'a' +as the first character) or at the current size of the stream (if +.IR mode +had +.BR 'a' +as the first character). If the current position at the end of the write +is larger than the current buffer size, the current buffer size shall +be set to the current position. A write operation on the stream shall +not advance the current buffer size beyond the size given in the +.IR size +argument. +.P +When a stream open for writing is flushed or closed, a null byte shall be +written at the current position or at the end of the buffer, depending +on the size of the contents. If a stream open for update is flushed or +closed and the last write has advanced the current buffer size, a null +byte shall be written at the end of the buffer if it fits. +.P +An attempt to seek a memory buffer stream to a negative position or to +a position larger than the buffer size given in the +.IR size +argument shall fail. +.SH "RETURN VALUE" +Upon successful completion, +\fIfmemopen\fR() +shall return a pointer to the object controlling the stream. Otherwise, +a null pointer shall be returned, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfmemopen\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR size +argument specifies a buffer size of zero. +.P +The +\fIfmemopen\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR mode +argument is not valid. +.TP +.BR EINVAL +The +.IR buf +argument is a null pointer and the +.IR mode +argument does not include a +.BR '+' +character. +.TP +.BR ENOMEM +The +.IR buf +argument is a null pointer and the allocation of a buffer of length +.IR size +has failed. +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf +\fB +#include +#include +.P +static char buffer[] = "foobar"; +.P +int +main (void) +{ + int ch; + FILE *stream; +.P + stream = fmemopen(buffer, strlen (buffer), "r"); + if (stream == NULL) + /* handle error */; +.P + while ((ch = fgetc(stream)) != EOF) + printf("Got %c\en", ch); +.P + fclose(stream); + return (0); +} +.fi \fR +.P +.RE +.P +This program produces the following output: +.sp +.RS 4 +.nf +\fB +Got f +Got o +Got o +Got b +Got a +Got r +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +This interface has been introduced to eliminate many of the errors +encountered in the construction of strings, notably overflowing of +strings. This interface prevents overflow. +.SH "FUTURE DIRECTIONS" +A future revision of this standard may mandate specific behavior when the +.IR mode +argument includes +.BR 'b' . +.SH "SEE ALSO" +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)", +.IR "\fIfseek\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fmin.3p b/man-pages-posix-2013-a/man3p/fmin.3p new file mode 100644 index 0000000..f64ddf8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fmin.3p @@ -0,0 +1,78 @@ +'\" et +.TH FMIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fmin, +fminf, +fminl +\(em determine minimum numeric value of two floating-point numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double fmin(double \fIx\fP, double \fIy\fP); +float fminf(float \fIx\fP, float \fIy\fP); +long double fminl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall determine the minimum numeric value of their +arguments. +NaN arguments shall be treated as missing data: if one argument +is a NaN and the other numeric, then these functions shall +choose the numeric value. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the minimum +numeric value of their arguments. +.P +If just one argument is a NaN, the other argument shall be returned. +.P +If +.IR x +and +.IR y +are NaN, a NaN shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdim\fR\^(\|)", +.IR "\fIfmax\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fmod.3p b/man-pages-posix-2013-a/man3p/fmod.3p new file mode 100644 index 0000000..eedc0b6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fmod.3p @@ -0,0 +1,167 @@ +'\" et +.TH FMOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fmod, +fmodf, +fmodl +\(em floating-point remainder value function +.SH SYNOPSIS +.LP +.nf +#include +.P +double fmod(double \fIx\fP, double \fIy\fP); +float fmodf(float \fIx\fP, float \fIy\fP); +long double fmodl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall return the floating-point remainder of the +division of +.IR x +by +.IR y . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +These functions shall return the value +.IR x \(mi\c +.IR i *\c +.IR y , +for some integer +.IR i +such that, if +.IR y +is non-zero, the result has the same sign as +.IR x +and magnitude less than the magnitude of +.IR y . +.P +If the correct value would cause underflow, +and is not +representable, +a range error may occur, and +\fIfmod\fR(), +\fImodf\fR(), +and +\fIfmodl\fR() +shall return +0.0, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If +.IR y +is zero, a domain error shall occur, and a NaN shall be returned. +.P +If +.IR x +is infinite, a domain error shall occur, and a NaN shall be returned. +.P +If +.IR x +is \(+-0 and +.IR y +is not zero, \(+-0 shall be returned. +.P +If +.IR x +is not infinite and +.IR y +is \(+-Inf, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is infinite or +.IR y +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fmtmsg.3p b/man-pages-posix-2013-a/man3p/fmtmsg.3p new file mode 100644 index 0000000..1cb1c57 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fmtmsg.3p @@ -0,0 +1,247 @@ +'\" et +.TH FMTMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fmtmsg +\(em display a message in the specified format on standard +error and/or a system console +.SH SYNOPSIS +.LP +.nf +#include +.P +int fmtmsg(long \fIclassification\fP, const char *\fIlabel\fP, int \fIseverity\fP, + const char *\fItext\fP, const char *\fIaction\fP, const char *\fItag\fP); +.fi +.SH DESCRIPTION +The +\fIfmtmsg\fR() +function shall display messages in a specified format instead +of the traditional +\fIprintf\fR() +function. +.P +Based on a message's classification component, +\fIfmtmsg\fR() +shall write a formatted message either to standard error, to the +console, or to both. +.P +A formatted message consists of up to five components as defined +below. The component \fIclassification\fR is not part of a message +displayed to the user, but defines the source of the message and +directs the display of the formatted message. +.IP "\fIclassification\fP" 12 +Contains the sum of identifying values constructed from the constants +defined below. Any one identifier from a subclass may be used in +combination with a single identifier from a different subclass. Two or +more identifiers from the same subclass should not be used together, +with the exception of identifiers from the display subclass. (Both +display subclass identifiers may be used so that messages can be +displayed to both standard error and the system console.) +.RS 12 +.IP "\fBMajor Classifications\fP" 6 +.br +Identifies the source of the condition. Identifiers are: MM_HARD +(hardware), MM_SOFT (software), and MM_FIRM (firmware). +.IP "\fBMessage Source Subclassifications\fP" 6 +.br +Identifies the type of software in which the problem is detected. +Identifiers are: MM_APPL (application), MM_UTIL (utility), and MM_OPSYS +(operating system). +.IP "\fBDisplay Subclassifications\fP" 6 +.br +Indicates where the message is to be displayed. Identifiers are: +MM_PRINT to display the message on the standard error stream, +MM_CONSOLE to display the message on the system console. One or both +identifiers may be used. +.IP "\fBStatus Subclassifications\fP" 6 +.br +Indicates whether the application can recover from the condition. +Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV +(non-recoverable). +.P +An additional identifier, MM_NULLMC, indicates that no classification +component is supplied for the message. +.RE +.IP "\fIlabel\fP" 12 +Identifies the source of the message. The format is two fields +separated by a +. +The first field is up to 10 bytes, the second is up to 14 bytes. +.IP "\fIseverity\fP" 12 +Indicates the seriousness of the condition. Identifiers for the levels +of \fIseverity\fR are: +.RS 12 +.IP MM_HALT 12 +Indicates that the application has encountered a severe fault and is +halting. Produces the string +.BR \(dqHALT\(dq . +.IP MM_ERROR 12 +Indicates that the application has detected a fault. Produces the +string +.BR \(dqERROR\(dq . +.IP MM_WARNING 12 +Indicates a condition that is out of the ordinary, that might be a +problem, and should be watched. Produces the string +.BR \(dqWARNING\(dq . +.IP MM_INFO 12 +Provides information about a condition that is not in error. Produces +the string +.BR \(dqINFO\(dq . +.IP MM_NOSEV 12 +Indicates that no severity level is supplied for the message. +.RE +.IP "\fItext\fP" 12 +Describes the error condition that produced the message. The character +string is not limited to a specific size. If the character string is +empty, then the text produced is unspecified. +.IP "\fIaction\fP" 12 +Describes the first step to be taken in the error-recovery process. +The +\fIfmtmsg\fR() +function precedes the action string with the prefix: +.BR \(dqTO FIX:\(dq . +The \fIaction\fR string is not limited to a specific size. +.IP "\fItag\fP" 12 +An identifier that references on-line documentation for the message. +Suggested usage is that \fItag\fR includes the \fIlabel\fR and a unique +identifying number. A sample \fItag\fR is +.BR \(dqXSI:cat:146\(dq . +.P +The +.IR MSGVERB +environment variable (for message verbosity) shall determine for +\fIfmtmsg\fR() +which message components it is to select when writing messages to +standard error. The value of +.IR MSGVERB +shall be a +-separated +list of optional keywords. Valid keywords are: \fIlabel\fR, +\fIseverity\fR, \fItext\fR, \fIaction\fR, and \fItag\fR. If +.IR MSGVERB +contains a keyword for a component and the component's value is not the +component's null value, +\fIfmtmsg\fR() +shall include that component in the message when writing the message to +standard error. If +.IR MSGVERB +does not include a keyword for a message component, that component +shall not be included in the display of the message. The keywords may +appear in any order. If +.IR MSGVERB +is not defined, if its value is the null string, if its value is not of +the correct format, or if it contains keywords other than the valid +ones listed above, +\fIfmtmsg\fR() +shall select all components. +.P +.IR MSGVERB +shall determine which components are selected for display to standard +error. All message components shall be included in console messages. +.SH "RETURN VALUE" +The +\fIfmtmsg\fR() +function shall return one of the following values: +.IP MM_OK 12 +The function succeeded. +.IP MM_NOTOK 12 +The function failed completely. +.IP MM_NOMSG 12 +The function was unable to generate a message on standard error, +but otherwise succeeded. +.IP MM_NOCON 12 +The function was unable to generate a console message, but otherwise +succeeded. +.SH ERRORS +None. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.IP " 1." 4 +The following example of +\fIfmtmsg\fR(): +.RS 4 +.sp +.RS 4 +.nf +\fB +fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option", +"refer to cat in user's reference manual", "XSI:cat:001") +.fi \fR +.P +.RE +.P +produces a complete message in the specified message format: +.sp +.RS 4 +.nf +\fB +XSI:cat: ERROR: illegal option +TO FIX: refer to cat in user's reference manual XSI:cat:001 +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +When the environment variable +.IR MSGVERB +is set as follows: +.RS 4 +.sp +.RS 4 +.nf +\fB +MSGVERB=severity:text:action +.fi \fR +.P +.RE +.P +and Example 1 is used, +\fIfmtmsg\fR() +produces: +.sp +.RS 4 +.nf +\fB +ERROR: illegal option +TO FIX: refer to cat in user's reference manual +.fi \fR +.P +.RE +.RE +.SH "APPLICATION USAGE" +One or more message components may be systematically omitted from +messages generated by an application by using the null value of the +argument for that component. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fnmatch.3p b/man-pages-posix-2013-a/man3p/fnmatch.3p new file mode 100644 index 0000000..d7ab403 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fnmatch.3p @@ -0,0 +1,196 @@ +'\" et +.TH FNMATCH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fnmatch +\(em match a filename string or a pathname +.SH SYNOPSIS +.LP +.nf +#include +.P +int fnmatch(const char *\fIpattern\fP, const char *\fIstring\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIfnmatch\fR() +function shall match patterns as described in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.13.1" ", " "Patterns Matching a Single Character" +and +.IR "Section 2.13.2" ", " "Patterns Matching Multiple Characters". +It checks the string specified by the +.IR string +argument to see if it matches the pattern specified by the +.IR pattern +argument. +.P +The +.IR flags +argument shall modify the interpretation of +.IR pattern +and +.IR string . +It is the bitwise-inclusive OR of zero or more of the flags defined in +.IR . +If the FNM_PATHNAME flag is set in +.IR flags , +then a + +character (\c +.BR '/' ) +in +.IR string +shall be explicitly matched by a + +in +.IR pattern ; +it shall not be matched by either the + +or + +special characters, nor by a bracket expression. If the FNM_PATHNAME flag +is not set, the + +character shall be treated as an ordinary character. +.P +If FNM_NOESCAPE is not set in +.IR flags , +a + +character in +.IR pattern +followed by any other character shall match that second character in +.IR string . +In particular, +.BR \(dq\e\e\(dq +shall match a + +in +.IR string . +If FNM_NOESCAPE is set, a + +character shall be treated as an ordinary character. +.P +If FNM_PERIOD is set in +.IR flags , +then a leading + +(\c +.BR '.' ) +in +.IR string +shall match a + +in +.IR pattern ; +as described by rule 2 in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion" +where the location of ``leading'' is indicated by the value +of FNM_PATHNAME: +.IP " *" 4 +If FNM_PATHNAME is set, a + +is ``leading'' if it is the first character in +.IR string +or if it immediately follows a +. +.IP " *" 4 +If FNM_PATHNAME is not set, a + +is ``leading'' only if it is the first character of +.IR string . +.P +If FNM_PERIOD is not set, then no special restrictions are placed on +matching a period. +.SH "RETURN VALUE" +If +.IR string +matches the pattern specified by +.IR pattern , +then +\fIfnmatch\fR() +shall return 0. If there is no match, +\fIfnmatch\fR() +shall return FNM_NOMATCH, which is defined in +.IR . +If an error occurs, +\fIfnmatch\fR() +shall return another non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIfnmatch\fR() +function has two major uses. It could be used by an application or +utility that needs to read a directory and apply a pattern against each +entry. The +.IR find +utility is an example of this. It can also be used by the +.IR pax +utility to process its +.IR pattern +operands, or by applications that need to match strings in a similar +manner. +.P +The name +\fIfnmatch\fR() +is intended to imply +.IR "filename" +match, rather than +.IR "pathname" +match. The default action of this function is to match filename strings, +rather than pathnames, since it gives no special significance to the + +character. With the FNM_PATHNAME flag, +\fIfnmatch\fR() +does match pathnames, but without tilde expansion, parameter +expansion, or special treatment for a + +at the beginning of a filename. +.SH RATIONALE +This function replaced the REG_FILENAME flag of +\fIregcomp\fR() +in early proposals of this volume of POSIX.1\(hy2008. It provides virtually the same functionality +as the +\fIregcomp\fR() +and +\fIregexec\fR() +functions using the REG_FILENAME and REG_FSLASH flags (the REG_FSLASH +flag was proposed for +\fIregcomp\fR(), +and would have had the opposite effect from FNM_PATHNAME), but with a +simpler function and less system overhead. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIglob\fR\^(\|)", +.IR "Section 2.6" ", " "Word Expansions" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fopen.3p b/man-pages-posix-2013-a/man3p/fopen.3p new file mode 100644 index 0000000..65a1f7d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fopen.3p @@ -0,0 +1,354 @@ +'\" et +.TH FOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fopen +\(em open a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *fopen(const char *restrict \fIpathname\fP, const char *restrict \fImode\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfopen\fR() +function shall open the file whose pathname is the string pointed to by +.IR pathname , +and associates a stream with it. +.P +The +.IR mode +argument points to a string. If the string is one of the following, the +file shall be opened in the indicated mode. Otherwise, the behavior is +undefined. +.IP "\fIr\fP\ or\ \fIrb\fP" 14 +Open file for reading. +.IP "\fIw\fP\ or\ \fIwb\fP" 14 +Truncate to zero length or create file for writing. +.IP "\fIa\fP\ or\ \fIab\fP" 14 +Append; open or create file for writing at end-of-file. +.IP "\fIr+\fP\ or\ \fIrb+\fP\ or\ \fIr+b\fP" 14 +Open file for update (reading and writing). +.IP "\fIw+\fP\ or\ \fIwb+\fP\ or\ \fIw+b\fP" 14 +Truncate to zero length or create file for update. +.IP "\fIa+\fP\ or\ \fIab+\fP\ or\ \fIa+b\fP" 14 +Append; open or create file for update, writing at end-of-file. +.P +The character +.BR 'b' +shall have no effect, but is allowed for ISO\ C standard conformance. +Opening a file with read mode (\fIr\fP as the first character in the +.IR mode +argument) shall fail if the file does not exist or cannot be read. +.P +Opening a file with append mode (\fIa\fP as the first character in the +.IR mode +argument) shall cause all subsequent writes to the file to be forced to +the then current end-of-file, regardless of intervening calls to +\fIfseek\fR(). +.P +When a file is opened with update mode (\c +.BR '+' +as the second or third character in the +.IR mode +argument), both input and output may be performed on the associated +stream. However, the application shall ensure that output is not +directly followed by input without an intervening call to +\fIfflush\fR() +or to a file positioning function (\c +\fIfseek\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR()), +and input is not directly followed by output without an intervening +call to a file positioning function, unless the input operation +encounters end-of-file. +.P +When opened, a stream is fully buffered if and only if it can be +determined not to refer to an interactive device. The error and +end-of-file indicators for the stream shall be cleared. +.P +If +.IR mode +is \fIw\fR, \fIwb\fR, \fIa\fR, \fIab\fR, \fIw\fR+, \fIwb\fR+, +\fIw\fR+\fIb\fR, \fIa\fP+, \fIab\fR+, or \fIa\fR+\fIb\fR, and the file +did not previously exist, upon successful completion, +\fIfopen\fR() +shall mark for update the last data access, last data modification, and +last file status change timestamps of the file and the last file status +change and last data modification timestamps of the parent directory. +.P +If +.IR mode +is \fIw\fR, \fIwb\fR, \fIa\fR, \fIab\fR, \fIw\fR+, \fIwb\fR+, +\fIw\fR+\fIb\fR, \fIa\fP+, \fIab\fR+, or \fIa\fR+\fIb\fR, and the file +did not previously exist, the +\fIfopen\fR() +function shall create a file as if it called the +\fIcreat\fR() +function with a value appropriate for the +.IR path +argument interpreted from +.IR pathname +and a value of S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | +S_IWOTH for the +.IR mode +argument. +.P +If +.IR mode +is \fIw\fR, \fIwb\fR, \fIw\fR+, \fIwb\fR+, or \fIw\fR+\fIb\fR, and the +file did previously exist, upon successful completion, +\fIfopen\fR() +shall mark for update the last data modification and last file +status change timestamps of the file. +.P +After a successful call to the +\fIfopen\fR() +function, the orientation of the stream shall be cleared, +the encoding rule shall be cleared, +and the associated +.BR mbstate_t +object shall be set to describe an initial conversion state. +.P +The file descriptor associated with the opened stream shall be allocated +and opened as if by a call to +\fIopen\fR() +with the following flags: +.TS +center box tab(!); +cB | cB +l | l. +\fIfopen\fP(\^) Mode!\fIopen\fP(\^) Flags +_ +\fIr\fR or \fIrb\fR!O_RDONLY +\fIw\fR or \fIwb\fR!O_WRONLY|O_CREAT|O_TRUNC +\fIa\fR or \fIab\fR!O_WRONLY|O_CREAT|O_APPEND +\fIr+\fR or \fIrb+\fR or \fIr+b\fR!O_RDWR +\fIw+\fR or \fIwb+\fR or \fIw+b\fR!O_RDWR|O_CREAT|O_TRUNC +\fIa+\fR or \fIab+\fR or \fIa+b\fR!O_RDWR|O_CREAT|O_APPEND +.TE +.SH "RETURN VALUE" +Upon successful completion, +\fIfopen\fR() +shall return a pointer to the object controlling the stream. Otherwise, +a null pointer shall be returned, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfopen\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or the +file exists and the permissions specified by +.IR mode +are denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created. +.TP +.BR EINTR +A signal was caught during +\fIfopen\fR(). +.TP +.BR EISDIR +The named file is a directory and +.IR mode +requires write access. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOENT +The +.IR mode +string begins with +.BR 'r' +and a component of +.IR pathname +does not name an existing file, or +.IR mode +begins with +.BR 'w' +or +.BR 'a' +and a component of the path prefix of +.IR pathname +does not name an existing file, or +.IR pathname +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR pathname +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR pathname +names an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory or file system that would contain the new file cannot be +expanded, the file does not exist, and the file was to be created. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR pathname +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.TP +.BR ENXIO +The named file is a character special or block special file, +and the device associated with this special file does not exist. +.TP +.BR EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type +.BR off_t . +.TP +.BR EROFS +The named file resides on a read-only file system and +.IR mode +requires write access. +.P +The +\fIfopen\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR mode +argument is not valid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and +.IR mode +requires write access. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Opening a File" +.P +The following example tries to open the file named +.BR file +for reading. The +\fIfopen\fR() +function returns a file pointer that is used in subsequent +\fIfgets\fR() +and +\fIfclose\fR() +calls. If the program cannot open the file, it just ignores it. +.sp +.RS 4 +.nf +\fB +#include +\&... +FILE *fp; +\&... +void rgrep(const char *file) +{ +\&... + if ((fp = fopen(file, "r")) == NULL) + return; +\&... +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fork.3p b/man-pages-posix-2013-a/man3p/fork.3p new file mode 100644 index 0000000..c9dcf0e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fork.3p @@ -0,0 +1,435 @@ +'\" et +.TH FORK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fork +\(em create a new process +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t fork(void); +.fi +.SH DESCRIPTION +The +\fIfork\fR() +function shall create a new process. The new process (child process) +shall be an exact copy of the calling process (parent process) except +as detailed below: +.IP " *" 4 +The child process shall have a unique process ID. +.IP " *" 4 +The child process ID also shall not match any active process group ID. +.IP " *" 4 +The child process shall have a different parent process ID, which shall +be the process ID of the calling process. +.IP " *" 4 +The child process shall have its own copy of the parent's file +descriptors. Each of the child's file descriptors shall refer to the +same open file description with the corresponding file descriptor of +the parent. +.IP " *" 4 +The child process shall have its own copy of the parent's open directory +streams. Each open directory stream in the child process may share +directory stream positioning with the corresponding directory stream of +the parent. +.IP " *" 4 +The child process shall have its own copy of the parent's message +catalog descriptors. +.IP " *" 4 +The child process values of +.IR tms_utime , +.IR tms_stime , +.IR tms_cutime , +and +.IR tms_cstime +shall be set to 0. +.IP " *" 4 +The time left until an alarm clock signal shall be reset to zero, and +the alarm, if any, shall be canceled; see +.IR "\fIalarm\fR\^(\|)". +.IP " *" 4 +All +.IR semadj +values shall be cleared. +.IP " *" 4 +File locks set by the parent process shall not be inherited by the +child process. +.IP " *" 4 +The set of signals pending for the child process shall be initialized +to the empty set. +.IP " *" 4 +Interval timers shall be reset in the child process. +.IP " *" 4 +Any semaphores that are open in the parent process shall also be open +in the child process. +.IP " *" 4 +The child process shall not inherit any address space memory locks +established by the parent process via calls to +\fImlockall\fR() +or +\fImlock\fR(). +.IP " *" 4 +Memory mappings created in the parent shall be retained in the child +process. MAP_PRIVATE mappings inherited from the parent shall also be +MAP_PRIVATE mappings in the child, and any modifications to the data in +these mappings made by the parent prior to calling +\fIfork\fR() +shall be visible to the child. Any modifications to the data in +MAP_PRIVATE mappings made by the parent after +\fIfork\fR() +returns shall be visible only to the parent. Modifications to the data +in MAP_PRIVATE mappings made by the child shall be visible only to the +child. +.IP " *" 4 +For the SCHED_FIFO and SCHED_RR scheduling policies, +the child process shall inherit the policy and priority settings of the +parent process during a +\fIfork\fR() +function. For other scheduling policies, the policy and priority +settings on +\fIfork\fR() +are implementation-defined. +.IP " *" 4 +Per-process timers created by the parent shall not be inherited by +the child process. +.IP " *" 4 +The child process shall have its own copy of the message queue +descriptors of the parent. Each of the message descriptors of the child +shall refer to the same open message queue description as the +corresponding message descriptor of the parent. +.IP " *" 4 +No asynchronous input or asynchronous output operations shall be +inherited by the child process. Any use of asynchronous control blocks +created by the parent produces undefined behavior. +.IP " *" 4 +A process shall be created with a single thread. If a multi-threaded +process calls +\fIfork\fR(), +the new process shall contain a replica of the calling thread and its +entire address space, possibly including the states of mutexes and +other resources. Consequently, to avoid errors, the child process may +only execute async-signal-safe operations until such time as one of the +.IR exec +functions is called. Fork handlers may be established by means of the +\fIpthread_atfork\fR() +function in order to maintain application invariants across +\fIfork\fR() +calls. +.RS 4 +.P +When the application calls +\fIfork\fR() +from a signal handler and any of the fork handlers registered by +\fIpthread_atfork\fR() +calls a function that is not async-signal-safe, the behavior is +undefined. +.RE +.IP " *" 4 +If the Trace option and the Trace Inherit option are both supported: +.RS 4 +.P +If the calling process was being traced in a trace stream that had its +inheritance policy set to POSIX_TRACE_INHERITED, the child process shall +be traced into that trace stream, and the child process shall inherit +the parent's mapping of trace event names to trace event type +identifiers. If the trace stream in which the calling process was being +traced had its inheritance policy set to POSIX_TRACE_CLOSE_FOR_CHILD, +the child process shall not be traced into that trace stream. The +inheritance policy is set by a call to the +\fIposix_trace_attr_setinherited\fR() +function. +.RE +.IP " *" 4 +If the Trace option is supported, but the Trace Inherit option is not +supported: +.RS 4 +.P +The child process shall not be traced into any of the trace streams +of its parent process. +.RE +.IP " *" 4 +If the Trace option is supported, the child process of a trace +controller process shall not control the trace streams controlled by +its parent process. +.IP " *" 4 +The initial value of the CPU-time clock of the child process shall be +set to zero. +.IP " *" 4 +The initial value of the CPU-time clock of the single thread of the +child process shall be set to zero. +.P +All other process characteristics defined by POSIX.1\(hy2008 shall be the same in +the parent and child processes. The inheritance of process +characteristics not defined by POSIX.1\(hy2008 is unspecified by POSIX.1\(hy2008. +.P +After +\fIfork\fR(), +both the parent and the child processes shall be capable of executing +independently before either one terminates. +.SH "RETURN VALUE" +Upon successful completion, +\fIfork\fR() +shall return 0 to the child process and shall return the process ID +of the child process to the parent process. Both processes shall +continue to execute from the +\fIfork\fR() +function. Otherwise, \(mi1 shall be +returned to the parent process, no child process shall be created, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfork\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources to create another process, or +the system-imposed limit on the total number of processes under +execution system-wide or by a single user +{CHILD_MAX} +would be exceeded. +.br +.P +The +\fIfork\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Many historical implementations have timing windows where a signal sent +to a process group (for example, an interactive SIGINT) +just prior to or during execution of +\fIfork\fR() +is delivered to the parent following the +\fIfork\fR() +but not to the child because the +\fIfork\fR() +code clears the child's set of pending signals. This volume of POSIX.1\(hy2008 does not require, +or even permit, this behavior. However, it is pragmatic to expect that +problems of this nature may continue to exist in implementations that +appear to conform to this volume of POSIX.1\(hy2008 and pass available verification suites. This +behavior is only a consequence of the implementation failing to make +the interval between signal generation and delivery totally invisible. +From the application's perspective, a +\fIfork\fR() +call should appear atomic. A signal that is generated prior to the +\fIfork\fR() +should be delivered prior to the +\fIfork\fR(). +A signal sent to the process group after the +\fIfork\fR() +should be delivered to both parent and child. The implementation may +actually initialize internal data structures corresponding to the +child's set of pending signals to include signals sent to the process +group during the +\fIfork\fR(). +Since the +\fIfork\fR() +call can be considered as atomic from the application's perspective, +the set would be initialized as empty and such signals would have +arrived after the +\fIfork\fR(); +see also +.IR . +.P +One approach that has been suggested to address the problem of signal +inheritance across +\fIfork\fR() +is to add an +.BR [EINTR] +error, which would be returned when a signal is detected during the +call. While this is preferable to losing signals, it was not +considered an optimal solution. Although it is not recommended for +this purpose, such an error would be an allowable extension for an +implementation. +.P +The +.BR [ENOMEM] +error value is reserved for those implementations that detect and +distinguish such a condition. This condition occurs when an +implementation detects that there is not enough memory to create the +process. This is intended to be returned when +.BR [EAGAIN] +is inappropriate because there can never be enough memory (either +primary or secondary storage) to perform the operation. Since +\fIfork\fR() +duplicates an existing process, this must be a condition where there is +sufficient memory for one such process, but not for two. Many +historical implementations actually return +.BR [ENOMEM] +due to temporary lack of memory, a case that is not generally distinct +from +.BR [EAGAIN] +from the perspective of a conforming application. +.P +Part of the reason for including the optional error +.BR [ENOMEM] +is because the SVID specifies it and it should be reserved for the +error condition specified there. The condition is not applicable on +many implementations. +.P +IEEE\ Std\ 1003.1\(hy1988 neglected to require concurrent execution of the parent and child +of +\fIfork\fR(). +A system that single-threads processes was clearly not intended and is +considered an unacceptable ``toy implementation'' of this volume of POSIX.1\(hy2008. +The only objection anticipated to the phrase ``executing +independently'' is testability, but this assertion should be testable. +Such tests require that both the parent and child can block on a +detectable action of the other, such as a write to a pipe or a signal. +An interactive exchange of such actions should be possible for the +system to conform to the intent of this volume of POSIX.1\(hy2008. +.P +The +.BR [EAGAIN] +error exists to warn applications that such a condition might occur. +Whether it occurs or not is not in any practical sense under the +control of the application because the condition is usually a +consequence of the user's use of the system, not of the application's +code. Thus, no application can or should rely upon its occurrence +under any circumstances, nor should the exact semantics of what concept +of ``user'' is used be of concern to the application developer. +Validation writers should be cognizant of this limitation. +.P +There are two reasons why POSIX programmers call +\fIfork\fR(). +One reason is to create a new thread of control within the same program +(which was originally only possible in POSIX by creating a new +process); the other is to create a new process running a different +program. In the latter case, the call to +\fIfork\fR() +is soon followed by a call to one of the +.IR exec +functions. +.P +The general problem with making +\fIfork\fR() +work in a multi-threaded world is what to do with all of the threads. +There are two alternatives. One is to copy all of the threads into the +new process. This causes the programmer or implementation to deal with +threads that are suspended on system calls or that might be about to +execute system calls that should not be executed in the new process. +The other alternative is to copy only the thread that calls +\fIfork\fR(). +This creates the difficulty that the state of process-local resources +is usually held in process memory. If a thread that is not calling +\fIfork\fR() +holds a resource, that resource is never released in the child process +because the thread whose job it is to release the resource does not +exist in the child process. +.P +When a programmer is writing a multi-threaded program, the first +described use of +\fIfork\fR(), +creating new threads in the same program, is provided by the +\fIpthread_create\fR() +function. The +\fIfork\fR() +function is thus used only to run new programs, and the effects of +calling functions that require certain resources between the call to +\fIfork\fR() +and the call to an +.IR exec +function are undefined. +.P +The addition of the +\fIforkall\fR() +function to the standard was considered and rejected. The +\fIforkall\fR() +function lets all the threads in the parent be duplicated in the +child. This essentially duplicates the state of the parent in the +child. This allows threads in the child to continue processing and +allows locks and the state to be preserved without explicit +\fIpthread_atfork\fR() +code. The calling process has to ensure that the threads processing +state that is shared between the parent and child (that is, file +descriptors or MAP_SHARED +memory) behaves properly after +\fIforkall\fR(). +For example, if a thread is reading a file descriptor in the parent +when +\fIforkall\fR() +is called, then two threads (one in the parent and one in the child) +are reading the file descriptor after the +\fIforkall\fR(). +If this is not desired behavior, the parent process has to synchronize +with such threads before calling +\fIforkall\fR(). +.P +While the +\fIfork\fR() +function is async-signal-safe, there is no way for an implementation to +determine whether the fork handlers established by +\fIpthread_atfork\fR() +are async-signal-safe. The fork handlers may attempt to execute +portions of the implementation that are not async-signal-safe, such as +those that are protected by mutexes, leading to a deadlock condition. +It is therefore undefined for the fork handlers to execute functions +that are not async-signal-safe when +\fIfork\fR() +is called from a signal handler. +.P +When +\fIforkall\fR() +is called, threads, other than the calling thread, that are in +functions that can return with an +.BR [EINTR] +error may have those functions return +.BR [EINTR] +if the implementation cannot ensure that the function behaves correctly +in the parent and child. In particular, +\fIpthread_cond_wait\fR() +and +\fIpthread_cond_timedwait\fR() +need to return in order to ensure that the condition has not changed. +These functions can be awakened by a spurious condition wakeup rather +than returning +.BR [EINTR] . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fItimes\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fpathconf.3p b/man-pages-posix-2013-a/man3p/fpathconf.3p new file mode 100644 index 0000000..6aa368a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fpathconf.3p @@ -0,0 +1,509 @@ +'\" et +.TH FPATHCONF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fpathconf, +pathconf +\(em get configurable pathname variables +.SH SYNOPSIS +.LP +.nf +#include +.P +long fpathconf(int \fIfildes\fP, int \fIname\fP); +long pathconf(const char *\fIpath\fP, int \fIname\fP); +.fi +.SH DESCRIPTION +The +\fIfpathconf\fR() +and +\fIpathconf\fR() +functions shall determine the current value of a configurable limit or +option (\fIvariable\fP) that is associated with a file or directory. +.P +For +\fIpathconf\fR(), +the +.IR path +argument points to the pathname of a file or directory. +.P +For +\fIfpathconf\fR(), +the +.IR fildes +argument is an open file descriptor. +.P +The +.IR name +argument represents the variable to be queried relative to that file or +directory. Implementations shall support all of the variables listed in +the following table and may support others. The variables in the +following table come from +.IR +or +.IR +and the symbolic constants, defined in +.IR , +are the corresponding values used for +.IR name . +.TS +center box tab(!); +cB | cB | cB +l | l | l. +Variable!Value of \fIname\fP!Requirements +_ +{FILESIZEBITS}!_PC_FILESIZEBITS!4,\|7 +{LINK_MAX}!_PC_LINK_MAX!1 +{MAX_CANON}!_PC_MAX_CANON!2 +{MAX_INPUT}!_PC_MAX_INPUT!2 +{NAME_MAX}!_PC_NAME_MAX!3,\|4 +{PATH_MAX}!_PC_PATH_MAX!4,\|5 +{PIPE_BUF}!_PC_PIPE_BUF!6 +{POSIX2_SYMLINKS}!_PC_2_SYMLINKS!4 +{POSIX_ALLOC_SIZE_MIN}!_PC_ALLOC_SIZE_MIN!10 +{POSIX_REC_INCR_XFER_SIZE}!_PC_REC_INCR_XFER_SIZE!10 +{POSIX_REC_MAX_XFER_SIZE}!_PC_REC_MAX_XFER_SIZE!10 +{POSIX_REC_MIN_XFER_SIZE}!_PC_REC_MIN_XFER_SIZE!10 +{POSIX_REC_XFER_ALIGN}!_PC_REC_XFER_ALIGN!10 +{SYMLINK_MAX}!_PC_SYMLINK_MAX!4,\|9 +_POSIX_CHOWN_RESTRICTED!_PC_CHOWN_RESTRICTED!7 +_POSIX_NO_TRUNC!_PC_NO_TRUNC!3,\|4 +_POSIX_VDISABLE!_PC_VDISABLE!2 +_POSIX_ASYNC_IO!_PC_ASYNC_IO!8 +_POSIX_PRIO_IO!_PC_PRIO_IO!8 +_POSIX_SYNC_IO!_PC_SYNC_IO!8 +_POSIX_TIMESTAMP_RESOLUTION!_PC_TIMESTAMP_RESOLUTION!1 +.TE +.SS "Requirements" +.IP " 1." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to the directory +itself. +.IP " 2." 4 +If +.IR path +or +.IR fildes +does not refer to a terminal file, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.IP " 3." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to filenames +within the directory. +.IP " 4." 4 +If +.IR path +or +.IR fildes +does not refer to a directory, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.IP " 5." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall be the maximum length +of a relative pathname that would not cross any mount points when the +specified directory is the working directory. +.IP " 6." 4 +If +.IR path +refers to a FIFO, or +.IR fildes +refers to a pipe or FIFO, the value returned shall apply to the +referenced object. If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to any FIFO that +exists or can be created within the directory. If +.IR path +or +.IR fildes +refers to any other type of file, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.IP " 7." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to any files, +other than directories, that exist or can be created within the +directory. +.IP " 8." 4 +If +.IR path +or +.IR fildes +refers to a directory, it is unspecified whether an implementation +supports an association of the variable name with the specified file. +.IP " 9." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall be the maximum length +of the string that a symbolic link in that directory can contain. +.IP 10. 4 +If +.IR path +or +.IR fildes +des does not refer to a regular file, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. If an implementation supports such an association for +other than a regular file, the value returned is unspecified. +.SH "RETURN VALUE" +If +.IR name +is an invalid value, both +\fIpathconf\fR() +and +\fIfpathconf\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.P +If the variable corresponding to +.IR name +is described in +.IR +as a maximum or minimum value and the variable has no limit for the +path or file descriptor, both +\fIpathconf\fR() +and +\fIfpathconf\fR() +shall return \(mi1 without changing +.IR errno . +Note that indefinite limits do not imply infinite limits; see +.IR . +.P +If the implementation needs to use +.IR path +to determine the value of +.IR name +and the implementation does not support the association of +.IR name +with the file specified by +.IR path , +or if the process did not have appropriate privileges to query the +file specified by +.IR path , +or +.IR path +does not exist, +\fIpathconf\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.P +If the implementation needs to use +.IR fildes +to determine the value of +.IR name +and the implementation does not support the association of +.IR name +with the file specified by +.IR fildes , +or if +.IR fildes +is an invalid file descriptor, +\fIfpathconf\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.P +Otherwise, +\fIpathconf\fR() +or +\fIfpathconf\fR() +shall return the current variable value for the file or directory +without changing +.IR errno . +The value returned shall not be more restrictive than the corresponding +value available to the application when it was compiled with the +implementation's +.IR +or +.IR . +.P +If the variable corresponding to +.IR name +is dependent on an unsupported option, the results are unspecified. +.SH ERRORS +The +\fIpathconf\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR name +is not valid. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EOVERFLOW +The value of +.IR name +is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than +{LONG_MAX}. +.br +.P +The +\fIpathconf\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix. +.TP +.BR EINVAL +The implementation does not support an association of the variable +.IR name +with the specified file. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.P +The +\fIfpathconf\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR name +is not valid. +.TP +.BR EOVERFLOW +The value of +.IR name +is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than +{LONG_MAX}. +.P +The +\fIfpathconf\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The implementation does not support an association of the variable +.IR name +with the specified file. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Application developers should check whether an option, such as +_POSIX_ADVISORY_INFO, is supported prior to obtaining and using values +for related variables such as +{POSIX_ALLOC_SIZE_MIN}. +.SH RATIONALE +The +\fIpathconf\fR() +function was proposed immediately after the +\fIsysconf\fR() +function when it was realized that some configurable values may differ +across file system, directory, or device boundaries. +.P +For example, +{NAME_MAX} +frequently changes between System V and +BSD-based file systems; System V uses a maximum of 14, BSD 255. On an +implementation that provides both types of file systems, an application +would be forced to limit all pathname components to 14 bytes, as this +would be the value specified in +.IR +on such a system. +.P +Therefore, various useful values can be queried on any pathname or file +descriptor, assuming that appropriate privileges +are in place. +.P +The value returned for the variable +{PATH_MAX} +indicates the longest relative pathname that could be given if the +specified directory is the current working directory of the process. A +process may not always be able to generate a name that long and use it +if a subdirectory in the pathname crosses into a more restrictive file +system. Note that implementations are allowed to accept pathnames +longer than +{PATH_MAX} +bytes long, but are not allowed to return pathnames longer than this +unless the user specifies a larger buffer using a function that provides +a buffer size argument. +.P +The value returned for the variable _POSIX_CHOWN_RESTRICTED +also applies to directories that do not have file systems mounted on +them. The value may change when crossing a mount point, so +applications that need to know should check for each directory. (An +even easier check is to try the +\fIchown\fR() +function and look for an error in case it happens.) +.P +Unlike the values returned by +\fIsysconf\fR(), +the pathname-oriented variables are potentially more volatile and are +not guaranteed to remain constant throughout the lifetime of the process. +For example, in between two calls to +\fIpathconf\fR(), +the file system in question may have been unmounted and remounted with +different characteristics. +.P +Also note that most of the errors are optional. If one of the +variables always has the same value on an implementation, the +implementation need not look at +.IR path +or +.IR fildes +to return that value and is, therefore, not required to detect any of +the errors except the meaning of +.BR [EINVAL] +that indicates that the value of +.IR name +is not valid for that variable. +.P +If the value of any of the limits is unspecified (logically +infinite), they will not be defined in +.IR +and the +\fIpathconf\fR() +and +\fIfpathconf\fR() +functions return \(mi1 without changing +.IR errno . +This can be distinguished from the case of giving an unrecognized +.IR name +argument because +.IR errno +is set to +.BR [EINVAL] +in this case. +.P +Since \(mi1 is a valid return value for the +\fIpathconf\fR() +and +\fIfpathconf\fR() +functions, applications should set +.IR errno +to zero before calling them and check +.IR errno +only if the return value is \(mi1. +.P +For the case of +{SYMLINK_MAX}, +since both +\fIpathconf\fR() +and +\fIopen\fR() +follow symbolic links, there is no way that +.IR path +or +.IR fildes +could refer to a symbolic link. +.P +It was the intention of IEEE\ Std 1003.1d\(hy1999 that the following variables: +.sp +.RS +{POSIX_ALLOC_SIZE_MIN} +{POSIX_REC_INCR_XFER_SIZE} +{POSIX_REC_MAX_XFER_SIZE} +{POSIX_REC_MIN_XFER_SIZE} +{POSIX_REC_XFER_ALIGN} +.RE +.P +only applied to regular files, but Note 10 also permits implementation +of the advisory semantics on other file types unique to an +implementation (for example, a character special device). +.P +The +.BR [EOVERFLOW] +error for _PC_TIMESTAMP_RESOLUTION cannot occur on POSIX-compliant +file systems because POSIX requires a timestamp resolution no +larger than one second. Even on 32-bit systems, this can be +represented without overflow. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchown\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fpclassify.3p b/man-pages-posix-2013-a/man3p/fpclassify.3p new file mode 100644 index 0000000..6f01154 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fpclassify.3p @@ -0,0 +1,73 @@ +'\" et +.TH FPCLASSIFY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fpclassify +\(em classify real floating type +.SH SYNOPSIS +.LP +.nf +#include +.P +int fpclassify(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfpclassify\fR() +macro shall classify its argument value as NaN, infinite, normal, +subnormal, zero, or into another implementation-defined category. +First, an argument represented in a format wider than its semantic type +is converted to its semantic type. Then classification is based on the +type of the argument. +.SH "RETURN VALUE" +The +\fIfpclassify\fR() +macro shall return the value of the number classification macro +appropriate to the value of its argument. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fprintf.3p b/man-pages-posix-2013-a/man3p/fprintf.3p new file mode 100644 index 0000000..63f2c95 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fprintf.3p @@ -0,0 +1,1490 @@ +'\" et +.TH FPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dprintf, +fprintf, +printf, +snprintf, +sprintf +\(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int dprintf(int \fIfildes\fP, const char *restrict \fIformat\fP, ...); +int fprintf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, ...); +int printf(const char *restrict \fIformat\fP, ...); +int snprintf(char *restrict \fIs\fP, size_t \fIn\fP, + const char *restrict \fIformat\fP, ...); +int sprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Excluding +\fIdprintf\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfprintf\fR() +function shall place output on the named output +.IR stream . +The +\fIprintf\fR() +function shall place output on the standard output stream +.IR stdout . +The +\fIsprintf\fR() +function shall place output followed by the null byte, +.BR '\e0' , +in consecutive bytes starting at *\fIs\fP; it is the user's +responsibility to ensure that enough space is available. +.P +The +\fIdprintf\fR() +function shall be equivalent to the +\fIfprintf\fR() +function, except that +\fIdprintf\fR() +shall write output to the file associated with the file descriptor +specified by the +.IR fildes +argument rather than place output on a stream. +.P +The +\fIsnprintf\fR() +function shall be equivalent to +\fIsprintf\fR(), +with the addition of the +.IR n +argument which states the size of the buffer referred to by +.IR s . +If +.IR n +is zero, nothing shall be written and +.IR s +may be a null pointer. Otherwise, output bytes beyond the +.IR n \(hy1st +shall be discarded instead of being written to the array, and a null +byte is written at the end of the bytes actually written into the +array. +.P +If copying takes place between objects that overlap as a result of a +call to +\fIsprintf\fR() +or +\fIsnprintf\fR(), +the results are undefined. +.P +Each of these functions converts, formats, and prints its arguments +under control of the +.IR format . +The +.IR format +is a character string, beginning and ending in its initial shift state, +if any. The +.IR format +is composed of zero or more directives: +.IR "ordinary characters" , +which are simply copied to the output stream, and +.IR "conversion specifications" , +each of which shall result in the fetching of zero or more arguments. +The results are undefined if there are insufficient arguments for the +.IR format . +If the +.IR format +is exhausted while arguments remain, the excess arguments shall be +evaluated but are otherwise ignored. +.P +Conversions can be applied to the +.IR n th +argument after the +.IR format +in the argument list, rather than to the next unused argument. In this +case, the conversion specifier character +.BR % +(see below) is replaced by the sequence \fR"%\fIn\fR$"\fR, where +.IR n +is a decimal integer in the range [1,{NL_ARGMAX}], +giving the position of the argument in the argument list. This feature +provides for the definition of format strings that select arguments in +an order appropriate to specific languages (see the EXAMPLES section). +.P +The +.IR format +can contain either numbered argument conversion specifications (that +is, \fR"%\fIn\fR$"\fR and \fR"*\fIm\fR$"\fR), or unnumbered argument +conversion specifications (that is, +.BR % +and +.BR * ), +but not both. The only exception to this is that +.BR %% +can be mixed with the \fR"%\fIn\fR$"\fR form. The results of mixing +numbered and unnumbered argument specifications in a +.IR format +string are undefined. When numbered argument specifications are used, +specifying the +.IR N th +argument requires that all the leading arguments, from the first to the +(\fIN\(mi1\fP)th, are specified in the format string. +.P +In format strings containing the \fR"%\fIn\fR$"\fR form of conversion +specification, numbered arguments in the argument list can be +referenced from the format string as many times as required. +.P +In format strings containing the +.BR % +form of conversion specification, each conversion specification uses +the first unused argument in the argument list. +.P +All forms of the +\fIfprintf\fR() +functions allow for the insertion of a language-dependent radix +character in the output string. The radix character is defined in the +current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +Each conversion specification is introduced by the +.BR '%' +character +or by the character sequence \fR"%\fIn\fR$"\fR, +after which the following appear in sequence: +.IP " *" 4 +Zero or more +.IR flags +(in any order), which modify the meaning of the conversion +specification. +.IP " *" 4 +An optional minimum +.IR "field width" . +If the converted value has fewer bytes than the field width, it shall +be padded with + +characters by default on the left; it shall be padded on the right if +the left-adjustment flag (\c +.BR '\(mi' ), +described below, is given to the field width. The field width takes the +form of an + +(\c +.BR '*' ), +described below, or a decimal integer. +.IP " *" 4 +An optional +.IR precision +that gives the minimum number of digits to appear for the +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversion specifiers; the number of digits to appear after the radix +character for the +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +and +.BR F +conversion specifiers; the maximum number of significant digits for the +.BR g +and +.BR G +conversion specifiers; or the maximum number of bytes to be printed +from a string in the +.BR s +and +.BR S +conversion specifiers. The precision takes the form of a + +(\c +.BR '.' ) +followed either by an + +(\c +.BR '*' ), +described below, or an optional decimal digit string, where a null +digit string is treated as zero. If a precision appears with any other +conversion specifier, the behavior is undefined. +.IP " *" 4 +An optional length modifier that specifies the size of the argument. +.IP " *" 4 +A +.IR "conversion specifier" +character that indicates the type of conversion to be applied. +.P +A field width, or precision, or both, may be indicated by an + +(\c +.BR '*' ). +In this case an argument of type +.BR int +supplies the field width or precision. Applications shall ensure that +arguments specifying field width, or precision, or both appear in that +order before the argument, if any, to be converted. A negative field +width is taken as a +.BR '\(mi' +flag followed by a positive field width. A negative precision is taken +as if the precision were omitted. +In +.IR format +strings containing the \fR"%\fIn\fR$"\fR form of a +conversion specification, a field width or precision may be indicated +by the sequence \fR"*\fIm\fR$"\fR, where +.IR m +is a decimal integer in the range [1,{NL_ARGMAX}] giving the position +in the argument list (after the +.IR format +argument) of an integer argument containing the field width or +precision, for example: +.sp +.RS 4 +.nf +\fB +printf("%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); +.fi \fR +.P +.RE +.P +The flag characters and their meanings are: +.IP "\fR'\fR" 8 +(The +.) +The integer portion of the result of a decimal conversion (\c +.BR %i , +.BR %d , +.BR %u , +.BR %f , +.BR %F , +.BR %g , +or +.BR %G ) +shall be formatted with thousands' grouping characters. For other +conversions the behavior is undefined. The non-monetary grouping +character is used. +.IP "\fR\(mi\fR" 8 +The result of the conversion shall be left-justified within the field. +The conversion is right-justified if this flag is not specified. +.IP "\fR+\fR" 8 +The result of a signed conversion shall always begin with a sign (\c +.BR '+' +or +.BR '\(mi' ). +The conversion shall begin with a sign only when a negative value is +converted if this flag is not specified. +.IP 8 +If the first character of a signed conversion is not a sign or if a +signed conversion results in no characters, a + +shall be prefixed to the result. This means that if the + +and +.BR '+' +flags both appear, the + +flag shall be ignored. +.IP "\fR#\fR" 8 +Specifies that the value is to be converted to an alternative +form. For +.BR o +conversion, it increases the precision (if necessary) to force the +first digit of the result to be zero. For +.BR x +or +.BR X +conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed +to it. For +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, the result shall always contain a radix +character, even if no digits follow the radix character. Without this +flag, a radix character appears in the result of these conversions only +if a digit follows it. For +.BR g +and +.BR G +conversion specifiers, trailing zeros shall +.IR not +be removed from the result as they normally are. For other conversion +specifiers, the behavior is undefined. +.IP "\fR0\fR" 8 +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, leading zeros (following any indication of sign +or base) are used to pad to the field width rather than performing +space padding, except when converting an infinity or NaN. If the +.BR '0' +and +.BR '\(mi' +flags both appear, the +.BR '0' +flag is ignored. For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversion specifiers, if a precision is specified, the +.BR '0' +flag shall be ignored. +If the +.BR '0' +and + +flags both appear, the grouping characters are inserted before zero +padding. For other conversions, the behavior is undefined. +.P +The length modifiers and their meanings are: +.IP "\fRhh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "signed char" +or +.BR "unsigned char" +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to +.BR "signed char" +or +.BR "unsigned char" +before printing); or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "signed char" +argument. +.IP "\fRh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "short" +or +.BR "unsigned short" +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to +.BR "short" +or +.BR "unsigned short" +before printing); or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "short" +argument. +.IP "\fRl\fR\ (ell)" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "long" +or +.BR "unsigned long" +argument; that a following +.BR n +conversion specifier applies to a pointer to a +.BR "long" +argument; that a following +.BR c +conversion specifier applies to a +.BR wint_t +argument; that a following +.BR s +conversion specifier applies to a pointer to a +.BR wchar_t +argument; or has no effect on a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier. +.IP "\fRll\fR\ (ell-ell)" 8 +.br +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "long long" +or +.BR "unsigned long long" +argument; or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "long long" +argument. +.IP "\fRj\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to an +.BR intmax_t +or +.BR uintmax_t +argument; or that a following +.BR n +conversion specifier applies to a pointer to an +.BR intmax_t +argument. +.IP "\fRz\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR size_t +or the corresponding signed integer type argument; or that a following +.BR n +conversion specifier applies to a pointer to a signed integer type +corresponding to a +.BR size_t +argument. +.IP "\fRt\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR ptrdiff_t +or the corresponding +.BR unsigned +type argument; or that a following +.BR n +conversion specifier applies to a pointer to a +.BR ptrdiff_t +argument. +.IP "\fRL\fR" 8 +Specifies that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to a +.BR "long double" +argument. +.P +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.P +The conversion specifiers and their meanings are: +.IP "\fRd\fR,\ \fRi\fR" 8 +The +.BR int +argument shall be converted to a signed decimal in the style +\fR"[\(mi]\fIdddd\fR"\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in +fewer digits, it shall be expanded with leading zeros. The default +precision is 1. The result of converting zero with an explicit +precision of zero shall be no characters. +.IP "\fRo\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned octal format in the style +\fR"\fIdddd\fR"\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in +fewer digits, it shall be expanded with leading zeros. The default +precision is 1. The result of converting zero with an explicit +precision of zero shall be no characters. +.IP "\fRu\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned decimal format in the style +\fR"\fIdddd\fR"\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in +fewer digits, it shall be expanded with leading zeros. The default +precision is 1. The result of converting zero with an explicit +precision of zero shall be no characters. +.IP "\fRx\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned hexadecimal format in the +style \fR"\fIdddd\fR"\fR; the letters +.BR \(dqabcdef\(dq +are used. The precision specifies the minimum number of digits to +appear; if the value being converted can be represented in fewer +digits, it shall be expanded with leading zeros. The default precision +is 1. The result of converting zero with an explicit precision of zero +shall be no characters. +.IP "\fRX\fP" 8 +Equivalent to the +.BR x +conversion specifier, except that letters +.BR \(dqABCDEF\(dq +are used instead of +.BR \(dqabcdef\(dq . +.IP "\fRf\fR,\ \fRF\fR" 8 +The +.BR double +argument shall be converted to decimal notation in the style +\fR"[\(mi]\fIddd\fR.\fIddd\fR"\fR, where the number of digits after the +radix character is equal to the precision specification. If the +precision is missing, it shall be taken as 6; if the precision is +explicitly zero and no +.BR '#' +flag is present, no radix character shall appear. If a radix character +appears, at least one digit appears before it. The low-order digit +shall be rounded in an implementation-defined manner. +.RS 8 +.P +A +.BR double +argument representing an infinity shall be converted in one of the +styles +.BR \(dq[\(mi]inf\(dq +or +.BR \(dq[\(mi]infinity\(dq ; +which style is implementation-defined. A +.BR double +argument representing a NaN shall be converted in one of the styles +\fR"[\(mi]nan(\fIn-char-sequence\fR)"\fR or +.BR \(dq[\(mi]nan\(dq ; +which style, and the meaning of any +.IR n-char-sequence , +is implementation-defined. The +.BR F +conversion specifier produces +.BR \(dqINF\(dq , +.BR \(dqINFINITY\(dq , +or +.BR \(dqNAN\(dq +instead of +.BR \(dqinf\(dq , +.BR \(dqinfinity\(dq , +or +.BR \(dqnan\(dq , +respectively. +.RE +.IP "\fRe\fR,\ \fRE\fR" 8 +The +.BR double +argument shall be converted in the style +\fR"[\(mi]\fId\fR.\fIddd\fRe\(+-\fIdd\fR"\fR, where there is one digit +before the radix character (which is non-zero if the argument is +non-zero) and the number of digits after it is equal to the precision; +if the precision is missing, it shall be taken as 6; if the precision +is zero and no +.BR '#' +flag is present, no radix character shall appear. The low-order digit +shall be rounded in an implementation-defined manner. The +.BR E +conversion specifier shall produce a number with +.BR 'E' +instead of +.BR 'e' +introducing the exponent. The exponent shall always contain at least +two digits. If the value is zero, the exponent shall be zero. +.RS 8 +.P +A +.BR double +argument representing an infinity or NaN shall be converted in +the style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRg\fR,\ \fRG\fR" 8 +The +.BR double +argument representing a floating-point number shall be converted in the +style +.BR f +or +.BR e +(or in the style +.BR F +or +.BR E +in the case of a +.BR G +conversion specifier), depending on the value converted and the precision. +Let +.BR P +equal the precision if non-zero, 6 if the precision is omitted, or 1 if the +precision is zero. Then, if a conversion with style +.BR E +would have an exponent of +.IR X : +.RS 8 +.IP -- 4 +If +.BR P >\c +.IR X \(>=\(mi4, +the conversion shall be with style +.BR f +(or +.BR F ) +and precision +.BR P \(mi(\c +.IR X +1). +.IP -- 4 +Otherwise, the conversion shall be with style +.BR e +(or +.BR E ) +and precision +.BR P \(mi1. +.P +Finally, unless the +.BR '#' +flag is used, any trailing zeros shall be removed from the fractional +portion of the result and the decimal-point character shall be removed +if there is no fractional portion remaining. +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRa\fR,\ \fRA\fR" 8 +A +.BR double +argument representing a floating-point number shall be converted in the +style \fR"[\(mi]0x\fIh\fR.\fIhhhh\fRp\(+-\fId\fR"\fR, where there is +one hexadecimal digit (which shall be non-zero if the argument is a +normalized floating-point number and is otherwise unspecified) before +the decimal-point character and the number of hexadecimal digits after +it is equal to the precision; if the precision is missing and FLT_RADIX +is a power of 2, then the precision shall be sufficient for an exact +representation of the value; if the precision is missing and FLT_RADIX +is not a power of 2, then the precision shall be sufficient to +distinguish values of type +.BR double , +except that trailing zeros may be omitted; if the precision is zero and +the +.BR '#' +flag is not specified, no decimal-point character shall appear. The +letters +.BR \(dqabcdef\(dq +shall be used for +.BR a +conversion and the letters +.BR \(dqABCDEF\(dq +for +.BR A +conversion. The +.BR A +conversion specifier produces a number with +.BR 'X' +and +.BR 'P' +instead of +.BR 'x' +and +.BR 'p' . +The exponent shall always contain at least one digit, and only as many +more digits as necessary to represent the decimal exponent of 2. If the +value is zero, the exponent shall be zero. +.RS 8 +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRc\fP" 8 +The +.BR int +argument shall be converted to an +.BR "unsigned char" , +and the resulting byte shall be written. +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the +.BR wint_t +argument shall be converted as if by an +.BR ls +conversion specification with no precision and an argument that points +to a two-element array of type +.BR wchar_t , +the first element of which contains the +.BR wint_t +argument to the +.BR ls +conversion specification and the second element contains a null wide +character. +.RE +.IP "\fRs\fP" 8 +The argument shall be a pointer to an array of +.BR char . +Bytes from the array shall be written up to (but not including) any +terminating null byte. If the precision is specified, no more than that +many bytes shall be written. If the precision is not specified or is +greater than the size of the array, the application shall ensure that +the array contains a null byte. +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the argument shall be a pointer to an array +of type +.BR wchar_t . +Wide characters from the array shall be converted to characters (each +as if by a call to the +\fIwcrtomb\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first wide character is +converted) up to and including a terminating null wide character. The +resulting characters shall be written up to (but not including) the +terminating null character (byte). If no precision is specified, the +application shall ensure that the array contains a null wide character. +If a precision is specified, no more than that many characters (bytes) +shall be written (including shift sequences, if any), and the array +shall contain a null wide character if, to equal the character sequence +length given by the precision, the function would need to access a wide +character one past the end of the array. In no case shall a partial +character be written. +.RE +.IP "\fRp\fP" 8 +The argument shall be a pointer to +.BR void . +The value of the pointer is converted to a sequence of printable +characters, in an implementation-defined manner. +.IP "\fRn\fP" 8 +The argument shall be a pointer to an integer into which is written the +number of bytes written to the output so far by this call to one of the +\fIfprintf\fR() +functions. No argument is converted. +.IP "\fRC\fP" 8 +Equivalent to +.BR lc . +.IP "\fRS\fP" 8 +Equivalent to +.BR ls . +.IP "\fR%\fR" 8 +Print a +.BR '%' +character; no argument is converted. The complete conversion +specification shall be +.BR %% . +.P +If a conversion specification does not match one of the above forms, +the behavior is undefined. If any argument is not the correct type for +the corresponding conversion specification, the behavior is undefined. +.P +In no case shall a nonexistent or small field width cause truncation of +a field; if the result of a conversion is wider than the field width, +the field shall be expanded to contain the conversion result. +Characters generated by +\fIfprintf\fR() +and +\fIprintf\fR() +are printed as if +\fIfputc\fR() +had been called. +.P +For the +.BR a +and +.BR A +conversion specifiers, if FLT_RADIX is a power of 2, the value shall be +correctly rounded to a hexadecimal floating number with the given +precision. +.P +For +.BR a +and +.BR A +conversions, if FLT_RADIX is not a power of 2 and the result is not +exactly representable in the given precision, the result should be one +of the two adjacent numbers in hexadecimal floating style with the +given precision, with the extra stipulation that the error should have +a correct sign for the current rounding direction. +.P +For the +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, if the number of significant decimal digits is +at most DECIMAL_DIG, then the result should be correctly rounded. If +the number of significant decimal digits is more than DECIMAL_DIG but +the source value is exactly representable with DECIMAL_DIG digits, then +the result should be an exact representation with trailing zeros. +Otherwise, the source value is bounded by two adjacent decimal strings +.IR L +< +.IR U , +both having DECIMAL_DIG significant digits; the value of the resultant +decimal string +.IR D +should satisfy +.IR L +<= +.IR D +<= +.IR U , +with the extra stipulation that the error should have a correct sign +for the current rounding direction. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update: +.IP " 1." 4 +Between the call to a successful execution of +\fIfprintf\fR() +or +\fIprintf\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR() +.IP " 2." 4 +Upon successful completion of a call to +\fIdprintf\fR() +.SH "RETURN VALUE" +Upon successful completion, the +\fIdprintf\fR(), +\fIfprintf\fR(), +and +\fIprintf\fR() +functions shall return the number of bytes transmitted. +.P +Upon successful completion, the +\fIsprintf\fR() +function shall return the number of bytes written to +.IR s , +excluding the terminating null byte. +.P +Upon successful completion, the +\fIsnprintf\fR() +function shall return the number of bytes that would be written to +.IR s +had +.IR n +been sufficiently large excluding the terminating null byte. +.P +If an output error was encountered, these functions shall return a +negative value +and set +.IR errno +to indicate the error. +.P +If the value of +.IR n +is zero on a call to +\fIsnprintf\fR(), +nothing shall be written, the number of bytes that would have been +written had +.IR n +been sufficiently large excluding the terminating null shall be +returned, and +.IR s +may be a null pointer. +.SH ERRORS +For the conditions under which +\fIdprintf\fR(), +\fIfprintf\fR(), +and +\fIprintf\fR() +fail and may fail, refer to +.IR "\fIfputc\fR\^(\|)" +or +.IR "\fIfputwc\fR\^(\|)". +.P +In addition, all forms of +\fIfprintf\fR() +shall fail if: +.TP +.BR EILSEQ +A wide-character code that does not correspond to a valid character +has been detected. +.TP +.BR EOVERFLOW +The value to be returned is greater than +{INT_MAX}. +.P +In addition, all forms of +\fIfprintf\fR() +may fail if: +.TP +.BR EINVAL +There are insufficient arguments. +.P +The +\fIdprintf\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.P +The +\fIdprintf\fR(), +\fIfprintf\fR(), +and +\fIprintf\fR() +functions may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.P +The +\fIsnprintf\fR() +function shall fail if: +.TP +.BR EOVERFLOW +The value of +.IR n +is greater than +{INT_MAX}. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +.SS "Printing Language-Independent Date and Time" +.P +The following statement can be used to print date and time using a +language-independent format: +.sp +.RS 4 +.nf +\fB +printf(format, weekday, month, day, hour, min); +.fi \fR +.P +.RE +.P +For American usage, +.IR format +could be a pointer to the following string: +.sp +.RS 4 +.nf +\fB +"%s, %s %d, %d:%.2d\en" +.fi \fR +.P +.RE +.P +This example would produce the following message: +.sp +.RS 4 +.nf +\fB +Sunday, July 3, 10:02 +.fi \fR +.P +.RE +.P +For German usage, +.IR format +could be a pointer to the following string: +.sp +.RS 4 +.nf +\fB +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi \fR +.P +.RE +.P +This definition of +.IR format +would produce the following message: +.sp +.RS 4 +.nf +\fB +Sonntag, 3. Juli, 10:02 +.fi \fR +.P +.RE +.SS "Printing File Information" +.P +The following example prints information about the type, permissions, +and number of links of a specific file in a directory. +.P +The first two calls to +\fIprintf\fR() +use data decoded from a previous +\fIstat\fR() +call. The user-defined +\fIstrperm\fR() +function shall return a string similar to the one at the beginning of the +output for the following command: +.sp +.RS 4 +.nf +\fB +ls \(mil +.fi \fR +.P +.RE +.P +The next call to +\fIprintf\fR() +outputs the owner's name if it is found using +\fIgetpwuid\fR(); +the +\fIgetpwuid\fR() +function shall return a +.BR passwd +structure from which the name of the user is extracted. If the user +name is not found, the program instead prints out the numeric value of +the user ID. +.P +The next call prints out the group name if it is found using +\fIgetgrgid\fR(); +\fIgetgrgid\fR() +is very similar to +\fIgetpwuid\fR() +except that it shall return group information based on the group number. +Once again, if the group is not found, the program prints the numeric +value of the group for the entry. +.P +The final call to +\fIprintf\fR() +prints the size of the file. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +.P +char *strperm (mode_t); +\&... +struct stat statbuf; +struct passwd *pwd; +struct group *grp; +\&... +printf("%10.10s", strperm (statbuf.st_mode)); +printf("%4d", statbuf.st_nlink); +.P +if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %\(mi8.8s", pwd->pw_name); +else + printf(" %\(mi8ld", (long) statbuf.st_uid); +.P +if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %\(mi8.8s", grp->gr_name); +else + printf(" %\(mi8ld", (long) statbuf.st_gid); +.P +printf("%9jd", (intmax_t) statbuf.st_size); +\&... +.fi \fR +.P +.RE +.SS "Printing a Localized Date String" +.P +The following example gets a localized date string. The +\fInl_langinfo\fR() +function shall return the localized date string, which specifies the +order and layout of the date. The +\fIstrftime\fR() +function takes this information and, using the +.BR tm +structure for values, places the date and time information into +.IR datestring . +The +\fIprintf\fR() +function then outputs +.IR datestring +and the name of the entry. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +struct dirent *dp; +struct tm *tm; +char datestring[256]; +\&... +strftime(datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); +.P +printf(" %s %s\en", datestring, dp->d_name); +\&... +.fi \fR +.P +.RE +.SS "Printing Error Information" +.P +The following example uses +\fIfprintf\fR() +to write error information to standard error. +.P +In the first group of calls, the program tries to open the password +lock file named +.BR LOCKFILE . +If the file already exists, this is an error, as indicated by the +O_EXCL flag on the +\fIopen\fR() +function. If the call fails, the program assumes that someone else is +updating the password file, and the program exits. +.P +The next group of calls saves a new password file as the current +password file by creating a link between +.BR LOCKFILE +and the new password file +.BR PASSWDFILE . +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +\&... +int pfd; +\&... +if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == \(mi1) +{ + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en"); + exit(1); +} +\&... +if (link(LOCKFILE,PASSWDFILE) == -1) { + fprintf(stderr, "Link error: %s\en", strerror(errno)); + exit(1); +} +\&... +.fi \fR +.P +.RE +.SS "Printing Usage Information" +.P +The following example checks to make sure the program has the necessary +arguments, and uses +\fIfprintf\fR() +to print usage information if the expected number of arguments is not +present. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +char *Options = "hdbtl"; +\&... +if (argc < 2) { + fprintf(stderr, "Usage: %s -%s +(\c +.BR '*' ) +in the format string; this ensures the correct number of decimal places +for the element based on the number of elements requested. +.sp +.RS 4 +.nf +\fB +#include +\&... +long i; +char *keystr; +int elementlen, len; +\&... +while (len < elementlen) { +\&... + printf("%s Element%0*ld\en", keystr, elementlen, i); +\&... +} +.fi \fR +.P +.RE +.SS "Creating a Pathname" +.P +The following example creates a pathname using information from a previous +\fIgetpwnam\fR() +function that returned the password database entry of the user. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +\&... +char *pathname; +struct passwd *pw; +size_t len; +\&... +// digits required for pid_t is number of bits times +// log2(10) = approx 10/33 +len = strlen(pw->pw_dir) + 1 + 1+(sizeof(pid_t)*80+32)/33 + + sizeof ".out"; +pathname = malloc(len); +if (pathname != NULL) +{ + snprintf(pathname, len, "%s/%jd.out", pw->pw_dir, + (intmax_t)getpid()); + ... +} +.fi \fR +.P +.RE +.SS "Reporting an Event" +.P +The following example loops until an event has timed out. The +\fIpause\fR() +function waits forever unless it receives a signal. The +\fIfprintf\fR() +statement should never occur due to the possible return values of +\fIpause\fR(). +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +\&... +while (!event_complete) { +\&... + if (pause() != \(mi1 || errno != EINTR) + fprintf(stderr, "pause: unknown error: %s\en", strerror(errno)); +} +\&... +.fi \fR +.P +.RE +.SS "Printing Monetary Information" +.P +The following example uses +\fIstrfmon\fR() +to convert a number and store it as a formatted monetary string named +.IR convbuf . +If the first number is printed, the program prints the format and the +description; otherwise, it just prints the number. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +struct tblfmt { + char *format; + char *description; +}; +.P +struct tblfmt table[] = { + { "%n", "default formatting" }, + { "%11n", "right align within an 11 character field" }, + { "%#5n", "aligned columns for values up to 99\|999" }, + { "%=*#5n", "specify a fill character" }, + { "%=0#5n", "fill characters do not use grouping" }, + { "%^#5n", "disable the grouping separator" }, + { "%^#5.0n", "round off to whole units" }, + { "%^#5.4n", "increase the precision" }, + { "%(#5n", "use an alternative pos/neg style" }, + { "%!(#5n", "disable the currency symbol" }, +}; +\&... +float input[3]; +int i, j; +char convbuf[100]; +\&... +strfmon(convbuf, sizeof(convbuf), table[i].format, input[j]); +.P +if (j == 0) { + printf("%s\t%s\t%s\en", table[i].format, + convbuf, table[i].description); +} +else { + printf("\t%s\en", convbuf); +} +\&... +.fi \fR +.P +.RE +.SS "Printing Wide Characters" +.P +The following example prints a series of wide characters. Suppose that +.BR \(dqL`@`\(dq +expands to three bytes: +.sp +.RS 4 +.nf +\fB +wchar_t wz [3] = L"@@"; // Zero-terminated +wchar_t wn [3] = L"@@@"; // Unterminated +.P +fprintf (stdout,"%ls", wz); // Outputs 6 bytes +fprintf (stdout,"%ls", wn); // Undefined because wn has no terminator +fprintf (stdout,"%4ls", wz); // Outputs 3 bytes +fprintf (stdout,"%4ls", wn); // Outputs 3 bytes; no terminator needed +fprintf (stdout,"%9ls", wz); // Outputs 6 bytes +fprintf (stdout,"%9ls", wn); // Outputs 9 bytes; no terminator needed +fprintf (stdout,"%10ls", wz); // Outputs 6 bytes +fprintf (stdout,"%10ls", wn); // Undefined because wn has no terminator +.fi \fR +.P +.RE +.P +In the last line of the example, after processing three characters, +nine bytes have been output. The fourth character must then be examined +to determine whether it converts to one byte or more. If it converts +to more than one byte, the output is only nine bytes. Since there is +no fourth character in the array, the behavior is undefined. +.SH "APPLICATION USAGE" +If the application calling +\fIfprintf\fR() +has any objects of type +.BR wint_t +or +.BR wchar_t , +it must also include the +.IR +header to have these objects defined. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfputc\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrfmon\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fputc.3p b/man-pages-posix-2013-a/man3p/fputc.3p new file mode 100644 index 0000000..280900d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fputc.3p @@ -0,0 +1,157 @@ +'\" et +.TH FPUTC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fputc +\(em put a byte on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fputc(int \fIc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfputc\fR() +function shall write the byte specified by +.IR c +(converted to an +.BR "unsigned char" ) +to the output stream pointed to by +.IR stream , +at the position indicated by the associated file-position indicator for +the stream (if defined), and shall advance the indicator appropriately. +If the file cannot support positioning requests, or if the stream was +opened with append mode, the byte shall be appended to the output +stream. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfputc\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfputc\fR() +shall return the value it has written. Otherwise, it shall return EOF, +the error indicator for the stream shall be set, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfputc\fR() +function shall fail if either the +.IR stream +is unbuffered or the +.IR stream 's +buffer needs to be flushed, and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor open for writing. +.TP +.BR EFBIG +An attempt was made to write to a file that exceeds the maximum file +size. +.TP +.BR EFBIG +An attempt was made to write to a file that exceeds the file +size limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum. +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is a member of a +background process group attempting to write to its controlling terminal, +TOSTOP is set, the calling thread is not blocking SIGTTOU, the process +is not ignoring SIGTTOU, and the process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process. A SIGPIPE signal shall also be sent to the +thread. +.br +.P +The +\fIfputc\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was +outside the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputs\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fputs.3p b/man-pages-posix-2013-a/man3p/fputs.3p new file mode 100644 index 0000000..a9e2453 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fputs.3p @@ -0,0 +1,154 @@ +'\" et +.TH FPUTS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fputs +\(em put a string on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fputs(const char *restrict \fIs\fP, FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfputs\fR() +function shall write the null-terminated string pointed to by +.IR s +to the stream pointed to by +.IR stream . +The terminating null byte shall not be written. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfputs\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfputs\fR() +shall return a non-negative number. Otherwise, it shall return EOF, +set an error indicator for the stream, +and set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Printing to Standard Output" +.P +The following example gets the current time, converts it to a string +using +\fIlocaltime\fR() +and +\fIasctime\fR(), +and prints it to standard output using +\fIfputs\fR(). +It then prints the number of minutes to an event for which it is +waiting. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +fputs(asctime(localtime(&now)), stdout); +printf("There are still %d minutes to the event.\en", + minutes_to_event); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIputs\fR() +function appends a + +while +\fIfputs\fR() +does not. +.P +This volume of POSIX.1\(hy2008 requires that successful completion simply return a non-negative +integer. There are at least three known different implementation +conventions for this requirement: +.IP " *" 4 +Return a constant value. +.IP " *" 4 +Return the last character written. +.IP " *" 4 +Return the number of bytes written. Note that this implementation +convention cannot be adhered to for strings longer than +{INT_MAX} +bytes as the value would not be representable in the return type of the +function. For backwards-compatibility, implementations can return the +number of bytes for strings of up to +{INT_MAX} +bytes, and return +{INT_MAX} +for all longer strings. +.SH RATIONALE +The +\fIfputs\fR() +function is one whose source code was specified in the referenced \fIThe C Programming Language\fP. In the +original edition, the function had no defined return value, yet many +practical implementations would, as a side-effect, return the value of the +last character written as that was the value remaining in the accumulator +used as a return value. In the second edition of the book, either the +fixed value 0 or EOF would be returned depending upon the return value of +\fIferror\fR(); +however, for compatibility with extant implementations, several +implementations would, upon success, return a positive value representing +the last byte written. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fputwc.3p b/man-pages-posix-2013-a/man3p/fputwc.3p new file mode 100644 index 0000000..cca9f1d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fputwc.3p @@ -0,0 +1,162 @@ +'\" et +.TH FPUTWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fputwc +\(em put a wide-character code on a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t fputwc(wchar_t \fIwc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfputwc\fR() +function shall write the character corresponding to the wide-character +code +.IR wc +to the output stream pointed to by +.IR stream , +at the position indicated by the associated file-position indicator for +the stream (if defined), and advances the indicator appropriately. If +the file cannot support positioning requests, or if the stream was +opened with append mode, the character is appended to the output +stream. If an error occurs while writing the character, the shift +state of the output file is left in an undefined state. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfputwc\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.P +The +\fIfputwc\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +Upon successful completion, +\fIfputwc\fR() +shall return +.IR wc . +Otherwise, it shall return WEOF, the error indicator for the stream shall +be set, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfputwc\fR() +function shall fail if either the stream is unbuffered or data in the +.IR stream 's +buffer needs to be written, and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor open for writing. +.TP +.BR EFBIG +An attempt was made to write to a file that exceeds the maximum file +size or the file size limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding stream. +.TP +.BR EILSEQ +The wide-character code +.IR wc +does not correspond to a valid character. +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is a member of a +background process group attempting to write to its controlling terminal, +TOSTOP is set, the calling thread is not blocking SIGTTOU, the process +is not ignoring SIGTTOU, and the process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process. A SIGPIPE signal shall also be sent to the +thread. +.P +The +\fIfputwc\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was +outside the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fputws.3p b/man-pages-posix-2013-a/man3p/fputws.3p new file mode 100644 index 0000000..ea418e0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fputws.3p @@ -0,0 +1,113 @@ +'\" et +.TH FPUTWS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fputws +\(em put a wide-character string on a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fputws(const wchar_t *restrict \fIws\fP, FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfputws\fR() +function shall write a character string corresponding to the +(null-terminated) wide-character string pointed to by +.IR ws +to the stream pointed to by +.IR stream . +No character corresponding to the terminating null wide-character code +shall be written. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfputws\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfputws\fR() +shall return a non-negative number. Otherwise, +it shall return \(mi1, set an error indicator for the stream, +and set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfputwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIfputws\fR() +function does not append a +. +.P +This volume of POSIX.1\(hy2008 requires that successful completion simply return a non-negative +integer. There are at least three known different implementation +conventions for this requirement: +.IP " *" 4 +Return a constant value. +.IP " *" 4 +Return the last character written. +.IP " *" 4 +Return the number of bytes written. Note that this implementation +convention cannot be adhered to for strings longer than +{INT_MAX} +bytes as the value would not be representable in the return type of the +function. For backwards-compatibility, implementations can return the +number of bytes for strings of up to +{INT_MAX} +bytes, and return +{INT_MAX} +for all longer strings. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fread.3p b/man-pages-posix-2013-a/man3p/fread.3p new file mode 100644 index 0000000..18baec6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fread.3p @@ -0,0 +1,190 @@ +'\" et +.TH FREAD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fread +\(em binary input +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t fread(void *restrict \fIptr\fP, size_t \fIsize\fP, size_t \fInitems\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfread\fR() +function shall read into the array pointed to by +.IR ptr +up to +.IR nitems +elements whose size is specified by +.IR size +in bytes, from the stream pointed to by +.IR stream . +For each object, +.IR size +calls shall be made to the +\fIfgetc\fR() +function and the results stored, in the order read, in an array of +.BR "unsigned char" +exactly overlaying the object. The file position indicator for the +stream (if defined) shall be advanced by the number of bytes +successfully read. If an error occurs, the resulting value of the file +position indicator for the stream is unspecified. If a partial element +is read, its value is unspecified. +.P +The +\fIfread\fR() +function may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be +marked for update by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfread\fR() +shall return the number of elements successfully read which is less than +.IR nitems +only if a read error or end-of-file is encountered. If +.IR size +or +.IR nitems +is 0, +\fIfread\fR() +shall return 0 and the contents of the array and the state of the +stream remain unchanged. Otherwise, if a read error occurs, the error +indicator for the stream shall be set, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading from a Stream" +.P +The following example reads a single element from the +.IR fp +stream into the array pointed to by +.IR buf . +.sp +.RS 4 +.nf +\fB +#include +\&... +size_t elements_read; +char buf[100]; +FILE *fp; +\&... +elements_read = fread(buf, sizeof(buf), 1, fp); +\&... +.fi \fR +.P +.RE +.P +If a read error occurs, +.IR elements_read +will be zero but the number of bytes read from the stream could be +anything from zero to +.IR sizeof ( buf )\(mi1. +.P +The following example reads multiple single-byte elements from the +.IR fp +stream into the array pointed to by +.IR buf . +.sp +.RS 4 +.nf +\fB +#include +\&... +size_t bytes_read; +char buf[100]; +FILE *fp; +\&... +bytes_read = fread(buf, 1, sizeof(buf), fp); +\&... +.fi \fR +.P +.RE +.P +If a read error occurs, +.IR bytes_read +will contain the number of bytes read from the stream. +.SH "APPLICATION USAGE" +The +\fIferror\fR() +or +\fIfeof\fR() +functions must be used to distinguish between an error condition and an +end-of-file condition. +.P +Because of possible differences in element length and byte ordering, +files written using +\fIfwrite\fR() +are application-dependent, and possibly cannot be read using +\fIfread\fR() +by a different application or by the same application on a different +processor. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgets\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/free.3p b/man-pages-posix-2013-a/man3p/free.3p new file mode 100644 index 0000000..5ec34e1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/free.3p @@ -0,0 +1,84 @@ +'\" et +.TH FREE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +free +\(em free allocated memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void free(void *\fIptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfree\fR() +function shall cause the space pointed to by +.IR ptr +to be deallocated; that is, made available for further allocation. If +.IR ptr +is a null pointer, no action shall occur. Otherwise, if the argument +does not match a pointer earlier returned by a function in POSIX.1\(hy2008 that +allocates memory as if by +\fImalloc\fR(), +or if the space has been deallocated by a call to +\fIfree\fR() +or +\fIrealloc\fR(), +the behavior is undefined. +.P +Any use of a pointer that refers to freed space results in undefined +behavior. +.SH "RETURN VALUE" +The +\fIfree\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +There is now no requirement for the implementation to support the +inclusion of +.IR . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcalloc\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIposix_memalign\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/freeaddrinfo.3p b/man-pages-posix-2013-a/man3p/freeaddrinfo.3p new file mode 100644 index 0000000..4dcfcbe --- /dev/null +++ b/man-pages-posix-2013-a/man3p/freeaddrinfo.3p @@ -0,0 +1,504 @@ +'\" et +.TH FREEADDRINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +freeaddrinfo, +getaddrinfo +\(em get address information +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +void freeaddrinfo(struct addrinfo *\fIai\fP); +int getaddrinfo(const char *restrict \fInodename\fP, + const char *restrict \fIservname\fP, + const struct addrinfo *restrict \fIhints\fP, + struct addrinfo **restrict \fIres\fP); +.fi +.SH DESCRIPTION +The +\fIfreeaddrinfo\fR() +function shall free one or more +.BR addrinfo +structures returned by +\fIgetaddrinfo\fR(), +along with any additional storage associated with those structures. If +the +.IR ai_next +field of the structure is not null, the entire list of structures shall +be freed. The +\fIfreeaddrinfo\fR() +function shall support the freeing of arbitrary sublists of an +.BR addrinfo +list originally returned by +\fIgetaddrinfo\fR(). +.P +The +\fIgetaddrinfo\fR() +function shall translate the name of a service location (for example, a +host name) and/or a service name +and shall return a set of socket addresses and associated information +to be used in creating a socket with which to address the specified +service. +.TP 10 +.BR Note: +In many cases it is implemented by the Domain Name System, +as documented in RFC\ 1034, RFC\ 1035, and RFC\ 1886. +.P +.P +The +\fIfreeaddrinfo\fR() +and +\fIgetaddrinfo\fR() +functions shall be thread-safe. +.P +The +.IR nodename +and +.IR servname +arguments are either null pointers or pointers to null-terminated +strings. One or both of these two arguments shall be supplied by the +application as a non-null pointer. +.P +The format of a valid name depends on the address family or families. +If a specific family is not given and the name could be interpreted as +valid within multiple supported families, the implementation shall +attempt to resolve the name in all supported families and, in absence +of errors, one or more results shall be returned. +.P +If the +.IR nodename +argument is not null, it can be a descriptive name or can be an address +string. +If the specified address family is AF_INET, +AF_INET6, +or AF_UNSPEC, valid descriptive names include host names. If the +specified address family is AF_INET or AF_UNSPEC, address strings using +Internet standard dot notation as specified in +.IR "\fIinet_addr\fR\^(\|)" +are valid. +.P +If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 +text forms described in +.IR "\fIinet_ntop\fR\^(\|)" +are valid. +.P +If +.IR nodename +is not null, the requested service location is named by +.IR nodename ; +otherwise, the requested service location is local to the caller. +.P +If +.IR servname +is null, the call shall return network-level addresses for the +specified +.IR nodename. +If +.IR servname +is not null, it is a null-terminated character string identifying the +requested service. This can be either a descriptive name or a numeric +representation suitable for use with the address family or families. +If the specified address family is AF_INET, +AF_INET6, +or AF_UNSPEC, the service can be specified as a string specifying a +decimal port number. +.P +If the +.IR hints +argument is not null, it refers to a structure containing input values +that directs the operation by providing options and by limiting the +returned information to a specific socket type, address family, and/or +protocol, as described below. In this +.IR hints +structure every member other than +.IR ai_flags , +.IR ai_family , +.IR ai_socktype , +and +.IR ai_protocol +shall be set to zero or a null pointer. A value of AF_UNSPEC for +.IR ai_family +means that the caller shall accept any address family. A value of zero +for +.IR ai_socktype +means that the caller shall accept any socket type. A value of zero for +.IR ai_protocol +means that the caller shall accept any protocol. If +.IR hints +is a null pointer, the behavior shall be as if it referred to a +structure containing the value zero for the +.IR ai_flags , +.IR ai_socktype , +and +.IR ai_protocol +fields, and AF_UNSPEC for the +.IR ai_family +field. +.P +The +.IR ai_flags +field to which the +.IR hints +parameter points shall be set to zero or be the bitwise-inclusive +OR of one or more of the values AI_PASSIVE, AI_CANONNAME, +AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. +.P +If the AI_PASSIVE flag is specified, the returned address information +shall be suitable for use in binding a socket for accepting incoming +connections for the specified service. In this case, if the +.IR nodename +argument is null, then the IP address portion of the socket address +structure shall be set to INADDR_ANY for an IPv4 address or +IN6ADDR_ANY_INIT for an IPv6 address. If the AI_PASSIVE flag is not +specified, the returned address information shall be suitable for a call +to +\fIconnect\fR() +(for a connection-mode protocol) or for a call to +\fIconnect\fR(), +\fIsendto\fR(), +or +\fIsendmsg\fR() +(for a connectionless protocol). In this case, if the +.IR nodename +argument is null, then the IP address portion of the socket address +structure shall be set to the loopback address. The AI_PASSIVE flag shall +be ignored if the +.IR nodename +argument is not null. +.P +If the AI_CANONNAME flag is specified and the +.IR nodename +argument is not null, the function shall attempt to determine the +canonical name corresponding to +.IR nodename +(for example, if +.IR nodename +is an alias or shorthand notation for a complete name). +.TP 10 +.BR Note: +Since different implementations use different conceptual models, the +terms ``canonical name'' and ``alias'' cannot be precisely defined for +the general case. However, Domain Name System implementations are +expected to interpret them as they are used in RFC\ 1034. +.RS 10 +.P +A numeric host address string is not a ``name'', and thus does not have +a ``canonical name'' form; no address to host name translation is +performed. See below for handling of the case where a canonical name +cannot be obtained. +.RE +.P +.P +If the AI_NUMERICHOST flag is specified, then a non-null +.IR nodename +string supplied shall be a numeric host address string. Otherwise, an +.BR [EAI_NONAME] +error is returned. This flag shall prevent any type of name resolution +service (for example, the DNS) from being invoked. +.P +If the AI_NUMERICSERV flag is specified, then a non-null +.IR servname +string supplied shall be a numeric port string. Otherwise, an +.BR [EAI_NONAME] +error shall be returned. This flag shall prevent any type of name +resolution service (for example, NIS+) from being invoked. +.P +If the AI_V4MAPPED flag is specified along with an +.IR ai_family +of AF_INET6, then +\fIgetaddrinfo\fR() +shall return IPv4-mapped IPv6 addresses on finding no matching IPv6 +addresses (\c +.IR ai_addrlen +shall be 16). The AI_V4MAPPED flag shall be ignored unless +.IR ai_family +equals AF_INET6. If the AI_ALL flag is used with the AI_V4MAPPED flag, +then +\fIgetaddrinfo\fR() +shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag +without the AI_V4MAPPED flag is ignored. +.P +If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be +returned only if an IPv4 address is configured on the local system, +and IPv6 addresses shall be returned only if an IPv6 address is +configured on the local system. +.P +The +.IR ai_socktype +field to which argument +.IR hints +points specifies the socket type for the service, as defined in +.IR "\fIsocket\fR\^(\|)". +If a specific socket type is not given (for example, a value of zero) +and the service name could be interpreted as valid with multiple +supported socket types, the implementation shall attempt to resolve the +service name for all supported socket types and, in the absence of +errors, all possible results shall be returned. A non-zero socket type +value shall limit the returned information to values with the specified +socket type. +.P +If the +.IR ai_family +field to which +.IR hints +points has the value AF_UNSPEC, addresses shall be returned for use +with any address family that can be used with the specified +.IR nodename +and/or +.IR servname . +Otherwise, addresses shall be returned for use only with the specified +address family. If +.IR ai_family +is not AF_UNSPEC and +.IR ai_protocol +is not zero, then addresses shall be returned for use only with the +specified address family and protocol; the value of +.IR ai_protocol +shall be interpreted as in a call to the +\fIsocket\fR() +function with the corresponding values of +.IR ai_family +and +.IR ai_protocol . +.SH "RETURN VALUE" +A zero return value for +\fIgetaddrinfo\fR() +indicates successful completion; a non-zero return value indicates +failure. The possible values for the failures are listed in the +ERRORS section. +.P +Upon successful return of +\fIgetaddrinfo\fR(), +the location to which +.IR res +points shall refer to a linked list of +.BR addrinfo +structures, each of which shall specify a socket address and +information for use in creating a socket with which to use that socket +address. The list shall include at least one +.BR addrinfo +structure. The +.IR ai_next +field of each structure contains a pointer to the next structure on the +list, or a null pointer if it is the last structure on the list. Each +structure on the list shall include values for use with a call to the +\fIsocket\fR() +function, and a socket address for use with the +\fIconnect\fR() +function or, if the AI_PASSIVE flag was specified, for use with the +\fIbind\fR() +function. The fields +.IR ai_family , +.IR ai_socktype , +and +.IR ai_protocol +shall be usable as the arguments to the +\fIsocket\fR() +function to create a socket suitable for use with the returned +address. The fields +.IR ai_addr +and +.IR ai_addrlen +are usable as the arguments to the +\fIconnect\fR() +or +\fIbind\fR() +functions with such a socket, according to the AI_PASSIVE flag. +.P +If +.IR nodename +is not null, and if requested by the AI_CANONNAME flag, the +.IR ai_canonname +field of the first returned +.BR addrinfo +structure shall point to a null-terminated string containing the +canonical name corresponding to the input +.IR nodename ; +if the canonical name is not available, then +.IR ai_canonname +shall refer to the +.IR nodename +argument or a string with the same contents. The contents of the +.IR ai_flags +field of the returned structures are undefined. +.P +All fields in socket address structures returned by +\fIgetaddrinfo\fR() +that are not filled in through an explicit argument (for example, +.IR sin6_flowinfo ) +shall be set to zero. +.TP 10 +.BR Note: +This makes it easier to compare socket address structures. +.P +.SH ERRORS +The +\fIgetaddrinfo\fR() +function shall fail and return the corresponding error value if: +.IP [EAI_AGAIN] 12 +The name could not be resolved at this time. Future attempts may +succeed. +.IP [EAI_BADFLAGS] 12 +.br +The +.IR flags +parameter had an invalid value. +.IP [EAI_FAIL] 12 +A non-recoverable error occurred when attempting to resolve the name. +.IP [EAI_FAMILY] 12 +The address family was not recognized. +.IP [EAI_MEMORY] 12 +There was a memory allocation failure when trying to allocate storage +for the return value. +.IP [EAI_NONAME] 12 +The name does not resolve for the supplied parameters. +.RS 12 +.P +Neither +.IR nodename +nor +.IR servname +were supplied. At least one of these shall be supplied. +.RE +.IP [EAI_SERVICE] 12 +The service passed was not recognized for the specified socket type. +.IP [EAI_SOCKTYPE] 12 +.br +The intended socket type was not recognized. +.IP [EAI_SYSTEM] 12 +A system error occurred; the error code can be found in +.IR errno . +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following (incomplete) program demonstrates the use of +\fIgetaddrinfo\fR() +to obtain the socket address structure(s) for the service named in the +program's command-line argument. The program then loops through each +of the address structures attempting to create and bind a socket to the +address, until it performs a successful +\fIbind\fR(). +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +.P +int +main(int argc, char *argv[]) +{ + struct addrinfo *result, *rp; + int sfd, s; +.P + if (argc != 2) { + fprintf(stderr, "Usage: %s port\en", argv[0]); + exit(EXIT_FAILURE); + } +.P + struct addrinfo hints = {}; + hints.ai_family = AF_UNSPEC; + hints.ai_socktype = SOCK_DGRAM; + hints.ai_flags = AI_PASSIVE; + hints.ai_protocol = 0; +.P + s = getaddrinfo(NULL, argv[1], &hints, &result); + if (s != 0) { + fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s)); + exit(EXIT_FAILURE); + } +.P + /* getaddrinfo() returns a list of address structures. + Try each address until a successful bind(). + If socket(2) (or bind(2)) fails, close the socket + and try the next address. */ +.P + for (rp = result; rp != NULL; rp = rp->ai_next) { + sfd = socket(rp->ai_family, rp->ai_socktype, + rp->ai_protocol); + if (sfd == -1) + continue; +.P + if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0) + break; /* Success */ +.P + close(sfd); + } +.P + if (rp == NULL) { /* No address succeeded */ + fprintf(stderr, "Could not bind\en"); + exit(EXIT_FAILURE); + } +.P + freeaddrinfo(result); /* No longer needed */ +.P + /* ... use socket bound to sfd ... */ +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +If the caller handles only TCP and not UDP, for example, then the +.IR ai_protocol +member of the +.IR hints +structure should be set to IPPROTO_TCP when +\fIgetaddrinfo\fR() +is called. +.P +If the caller handles only IPv4 and not IPv6, then the +.IR ai_family +member of the +.IR hints +structure should be set to AF_INET when +\fIgetaddrinfo\fR() +is called. +.P +The term ``canonical name'' is misleading; it is taken from the Domain +Name System (RFC\ 2181). It should be noted that the canonical name is +a result of alias processing, and not necessarily a unique attribute of +a host, address, or set of addresses. See RFC\ 2181 for more discussion +of this in the Domain Name System context. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIconnect\fR\^(\|)", +.IR "\fIendservent\fR\^(\|)", +.IR "\fIgai_strerror\fR\^(\|)", +.IR "\fIgetnameinfo\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/freelocale.3p b/man-pages-posix-2013-a/man3p/freelocale.3p new file mode 100644 index 0000000..1ef3cea --- /dev/null +++ b/man-pages-posix-2013-a/man3p/freelocale.3p @@ -0,0 +1,102 @@ +'\" et +.TH FREELOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +freelocale +\(em free resources allocated for a locale object +.SH SYNOPSIS +.LP +.nf +#include +.P +void freelocale(locale_t \fIlocobj\fP); +.fi +.SH DESCRIPTION +The +\fIfreelocale\fR() +function shall cause the resources allocated for a locale object +returned by a call to the +\fInewlocale\fR() +or +\fIduplocale\fR() +functions to be released. +.P +The behavior is undefined if the +.IR locobj +argument is the special locale object LC_GLOBAL_LOCALE or is not a valid +locale object handle. +.P +Any use of a locale object that has been freed results in undefined +behavior. +.SH "RETURN VALUE" +None. +.SH ERRORS +None. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Freeing Up a Locale Object" +.P +The following example shows a code fragment to free a locale object +created by +\fInewlocale\fR(): +.sp +.RS 4 +.nf +\fB +#include +\&... +.P +/* Every locale object allocated with newlocale() should be + * freed using freelocale(): + */ +.P +locale_t loc; +.P +/* Get the locale. */ +.P +loc = newlocale (LC_CTYPE_MASK | LC_TIME_MASK, "locname", NULL); +.P +/* ... Use the locale object ... */ +\&... +.P +/* Free the locale object resources. */ +freelocale (loc); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIduplocale\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/freopen.3p b/man-pages-posix-2013-a/man3p/freopen.3p new file mode 100644 index 0000000..9132e43 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/freopen.3p @@ -0,0 +1,361 @@ +'\" et +.TH FREOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +freopen +\(em open a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *freopen(const char *restrict \fIpathname\fP, const char *restrict \fImode\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfreopen\fR() +function shall first attempt to flush the stream associated with +.IR stream +as if by a call to +.IR fflush ( stream ). +Failure to flush the stream successfully shall be ignored. If +.IR pathname +is not a null pointer, +\fIfreopen\fR() +shall close any file descriptor associated with +.IR stream . +Failure to close the file descriptor successfully shall be ignored. +The error and end-of-file indicators for the stream shall be +cleared. +.P +The +\fIfreopen\fR() +function shall open the file whose pathname is the string pointed to by +.IR pathname +and associate the stream pointed to by +.IR stream +with it. The +.IR mode +argument shall be used just as in +\fIfopen\fR(). +.P +The original stream shall be closed regardless of whether the +subsequent open succeeds. +.P +If +.IR pathname +is a null pointer, the +\fIfreopen\fR() +function shall attempt to change the mode of the stream to that +specified by +.IR mode , +as if the name of the file currently associated with the stream had +been used. In this case, the file descriptor associated with the stream +need not be closed if the call to +\fIfreopen\fR() +succeeds. It is implementation-defined which changes of mode are +permitted (if any), and under what circumstances. +.P +After a successful call to the +\fIfreopen\fR() +function, the orientation of the stream shall be cleared, +the encoding rule shall be cleared, +and the associated +.BR mbstate_t +object shall be set to describe an initial conversion state. +.P +If +.IR pathname +is not a null pointer, or if +.IR pathname +is a null pointer and the specified mode change necessitates the file +descriptor associated with the stream to be closed and reopened, the +file descriptor associated with the reopened stream shall be allocated +and opened as if by a call to +\fIopen\fR() +with the following flags: +.TS +center box tab(!); +cB | cB +l | l. +\fIfreopen\fP(\^) Mode!\fIopen\fP(\^) Flags +_ +\fIr\fR or \fIrb\fR!O_RDONLY +\fIw\fR or \fIwb\fR!O_WRONLY|O_CREAT|O_TRUNC +\fIa\fR or \fIab\fR!O_WRONLY|O_CREAT|O_APPEND +\fIr+\fR or \fIrb+\fR or \fIr+b\fR!O_RDWR +\fIw+\fR or \fIwb+\fR or \fIw+b\fR!O_RDWR|O_CREAT|O_TRUNC +\fIa+\fR or \fIab+\fR or \fIa+b\fR!O_RDWR|O_CREAT|O_APPEND +.TE +.SH "RETURN VALUE" +Upon successful completion, +\fIfreopen\fR() +shall return the value of +.IR stream . +Otherwise, a null pointer shall be returned, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfreopen\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or the +file exists and the permissions specified by +.IR mode +are denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created. +.TP +.BR EBADF +The file descriptor underlying the stream is not a valid file +descriptor when +.IR pathname +is a null pointer. +.TP +.BR EINTR +A signal was caught during +\fIfreopen\fR(). +.TP +.BR EISDIR +The named file is a directory and +.IR mode +requires write access. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOENT +The +.IR mode +string begins with +.BR 'r' +and a component of +.IR pathname +does not name an existing file, or +.IR mode +begins with +.BR 'w' +or +.BR 'a' +and a component of the path prefix of +.IR pathname +does not name an existing file, or +.IR pathname +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR pathname +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR pathname +names an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory or file system that would contain the new file cannot be +expanded, the file does not exist, and it was to be created. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR pathname +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.TP +.BR ENXIO +The named file is a character special or block special file, and the +device associated with this special file does not exist. +.TP +.BR EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type +.BR off_t . +.TP +.BR EROFS +The named file resides on a read-only file system and +.IR mode +requires write access. +.P +The +\fIfreopen\fR() +function may fail if: +.TP +.BR EBADF +The mode with which the file descriptor underlying the stream was +opened does not support the requested mode when +.IR pathname +is a null pointer. +.TP +.BR EINVAL +The value of the +.IR mode +argument is not valid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.TP +.BR ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and +.IR mode +requires write access. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Directing Standard Output to a File" +.P +The following example logs all standard output to the +.BR /tmp/logfile +file. +.sp +.RS 4 +.nf +\fB +#include +\&... +FILE *fp; +\&... +fp = freopen ("/tmp/logfile", "a+", stdout); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIfreopen\fR() +function is typically used to attach the pre-opened +.IR streams +associated with +.IR stdin , +.IR stdout , +and +.IR stderr +to other files. +.P +Since implementations are not required to support any stream mode changes +when the +.IR pathname +argument is NULL, portable applications cannot rely on the use of +\fIfreopen\fR() +to change the stream mode, and use of this feature is discouraged. The +feature was originally added to the ISO\ C standard in order to facilitate changing +.IR stdin +and +.IR stdout +to binary mode. Since a +.BR 'b' +character in the mode has no effect on POSIX systems, this use of the +feature is unnecessary in POSIX applications. However, even though the +.BR 'b' +is ignored, a successful call to +.IR freopen \c +(NULL, "\fIwb\fR", \fIstdout\fR) does have an effect. In particular, +for regular files it truncates the file and sets the file-position +indicator for the stream to the start of the file. It is possible that +these side-effects are an unintended consequence of the way the feature +is specified in the ISO/IEC\ 9899:\|1999 standard, but unless or until the ISO\ C standard is changed, +applications which successfully call +.IR freopen \c +(NULL, "\fIwb\fR", \fIstdout\fR) will behave in unexpected ways on +conforming systems in situations such as: +.sp +.RS 4 +.nf +\fB +{ appl file1; appl file2; } > file3 +.fi \fR +.P +.RE +.P +which will result in +.BR file3 +containing only the output from the second invocation of +.IR appl . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfflush\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fImbsinit\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/frexp.3p b/man-pages-posix-2013-a/man3p/frexp.3p new file mode 100644 index 0000000..d7af0ea --- /dev/null +++ b/man-pages-posix-2013-a/man3p/frexp.3p @@ -0,0 +1,97 @@ +'\" et +.TH FREXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +frexp, +frexpf, +frexpl +\(em extract mantissa and exponent from a double precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +double frexp(double \fInum\fP, int *\fIexp\fP); +float frexpf(float \fInum\fP, int *\fIexp\fP); +long double frexpl(long double \fInum\fP, int *\fIexp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall break a floating-point number +.IR num +into a normalized fraction and an integral power of 2. The integer +exponent shall be stored in the +.BR int +object pointed to by +.IR exp . +.SH "RETURN VALUE" +For finite arguments, these functions shall return the value +.IR x , +such that +.IR x +has a magnitude in the interval [\(12,1) or 0, and +.IR num +equals +.IR x +times 2 raised to the power *\fIexp\fP. +.P +If +.IR num +is NaN, a NaN shall be returned, and the value of *\fIexp\fP is +unspecified. +.P +If +.IR num +is \(+-0, \(+-0 shall be returned, and the value of *\fIexp\fP shall be +0. +.P +If +.IR num +is \(+-Inf, +.IR num +shall be returned, and the value of *\fIexp\fP is unspecified. +.SH ERRORS +No errors are defined. +.P +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisnan\fR\^(\|)", +.IR "\fIldexp\fR\^(\|)", +.IR "\fImodf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fscanf.3p b/man-pages-posix-2013-a/man3p/fscanf.3p new file mode 100644 index 0000000..8681c90 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fscanf.3p @@ -0,0 +1,880 @@ +'\" et +.TH FSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fscanf, +scanf, +sscanf +\(em convert formatted input +.SH SYNOPSIS +.LP +.nf +#include +.P +int fscanf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, ...); +int scanf(const char *restrict \fIformat\fP, ...); +int sscanf(const char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfscanf\fR() +function shall read from the named input +.IR stream . +The +\fIscanf\fR() +function shall read from the standard input stream +.IR stdin . +The +\fIsscanf\fR() +function shall read from the string +.IR s . +Each function reads bytes, interprets them according to a format, and +stores the results in its arguments. Each expects, as arguments, a +control string +.IR format +described below, and a set of +.IR pointer +arguments indicating where the converted input should be stored. The +result is undefined if there are insufficient arguments for the +format. If the format is exhausted while arguments remain, the excess +arguments shall be evaluated but otherwise ignored. +.P +Conversions can be applied to the +.IR n th +argument after the +.IR format +in the argument list, rather than to the next unused argument. In this +case, the conversion specifier character +.BR % +(see below) is replaced by the sequence \fR"%\fIn\fR$"\fR, where +.IR n +is a decimal integer in the range [1,{NL_ARGMAX}]. +This feature provides for the definition of format strings that select +arguments in an order appropriate to specific languages. In format +strings containing the \fR"%\fIn\fR$"\fR form of conversion +specifications, +it is unspecified whether numbered arguments in the argument list can +be referenced from the format string more than once. +.P +The +.IR format +can contain either form of a conversion specification\(emthat is, +.BR % +or \fR"%\fIn\fR$"\fR\(embut the two forms cannot be mixed +within a single +.IR format +string. The only exception to this is that +.BR %% +or +.BR %* +can be mixed with the \fR"%\fIn\fR$"\fR form. When numbered argument +specifications are used, specifying the +.IR N th +argument requires that all the leading arguments, from the first to +the (\c +.IR N \(mi1)th, +are pointers. +.P +The +\fIfscanf\fR() +function in all its forms shall allow detection of a language-dependent +radix character in the input string. The radix character is defined in +the current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +The format is a character string, beginning and ending in its initial +shift state, if any, composed of zero or more directives. Each +directive is composed of one of the following: +one or more white-space characters (\c +, +, +, +, +or +); +an ordinary character (neither +.BR '%' +nor a white-space character); or a conversion specification. Each +conversion specification is introduced by the character +.BR '%' +or the character sequence \fR"%\fIn\fR$"\fR, +after which the following appear in sequence: +.IP " *" 4 +An optional assignment-suppressing character +.BR '*' . +.IP " *" 4 +An optional non-zero decimal integer that specifies the maximum field +width. +.IP " *" 4 +An optional assignment-allocation character +.BR 'm' . +.IP " *" 4 +An option length modifier that specifies the size of the receiving +object. +.IP " *" 4 +A +.IR "conversion specifier" +character that specifies the type of conversion to be applied. The +valid conversion specifiers are described below. +.P +The +\fIfscanf\fR() +functions shall execute each directive of the format in turn. If a +directive fails, as detailed below, the function shall return. Failures +are described as input failures (due to the unavailability of input +bytes) or matching failures (due to inappropriate input). +.P +A directive composed of one or more white-space characters shall be +executed by reading input until no more valid input can be read, or up +to the first byte which is not a white-space character, which remains +unread. +.P +A directive that is an ordinary character shall be executed as follows: +the next byte shall be read from the input and compared with the byte +that comprises the directive; if the comparison shows that they are not +equivalent, the directive shall fail, and the differing and subsequent +bytes shall remain unread. Similarly, if end-of-file, an encoding +error, or a read error prevents a character from being read, the +directive shall fail. +.P +A directive that is a conversion specification defines a set of +matching input sequences, as described below for each conversion +character. A conversion specification shall be executed in the +following steps. +.P +Input white-space characters (as specified by +.IR "\fIisspace\fR\^(\|)") +shall be skipped, unless the conversion specification includes a +.BR [ , +.BR c , +.BR C , +or +.BR n +conversion specifier. +.P +An item shall be read from the input, unless the conversion +specification includes an +.BR n +conversion specifier. An input item shall be defined as the longest +sequence of input bytes (up to any specified maximum field width, which +may be measured in characters or bytes dependent on the conversion +specifier) which is an initial subsequence of a matching sequence. The +first byte, if any, after the input item shall remain unread. If the +length of the input item is 0, the execution of the conversion +specification shall fail; this condition is a matching failure, unless +end-of-file, an encoding error, or a read error prevented input from +the stream, in which case it is an input failure. +.P +Except in the case of a +.BR % +conversion specifier, the input item (or, in the case of a +.BR %n +conversion specification, the count of input bytes) shall be converted +to a type appropriate to the conversion character. If the input item is +not a matching sequence, the execution of the conversion specification +fails; this condition is a matching failure. Unless assignment +suppression was indicated by a +.BR '*' , +the result of the conversion shall be placed in the object pointed to +by the first argument following the +.IR format +argument that has not already received a conversion result if the +conversion specification is introduced by +.BR % , +or in the +.IR n th +argument if introduced by the character sequence \fR"%\fIn\fR$"\fR. +If this object does not have an appropriate type, or if the result of +the conversion cannot be represented in the space provided, the +behavior is undefined. +.P +The +.BR %c , +.BR %s , +and +.BR %[ +conversion specifiers shall accept an optional assignment-allocation +character +.BR 'm' , +which shall cause a memory buffer to be allocated to hold the string +converted including a terminating null character. In such a case, +the argument corresponding to the conversion specifier should be a +reference to a pointer variable that will receive a pointer to the +allocated buffer. The system shall allocate a buffer as if +\fImalloc\fR() +had been called. The application shall be responsible for freeing the +memory after usage. If there is insufficient memory to allocate a buffer, +the function shall set +.IR errno +to +.BR [ENOMEM] +and a conversion error shall result. If the function returns EOF, any +memory successfully allocated for parameters using assignment-allocation +character +.BR 'm' +by this call shall be freed before the function returns. +.br +.P +The length modifiers and their meanings are: +.IP "\fRhh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "signed char" +or +.BR "unsigned char" . +.IP "\fRh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "short" +or +.BR "unsigned short" . +.IP "\fRl\fR\ (ell)" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "long" +or +.BR "unsigned long" ; +that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to an argument with type pointer to +.BR double ; +or that a following +.BR c , +.BR s , +or +.BR [ +conversion specifier applies to an argument with type pointer to +.BR wchar_t . +If the +.BR 'm' +assignment-allocation character is specified, the conversion applies +to an argument with the type pointer to a pointer to +.BR wchar_t . +.IP "\fRll\fR\ (ell-ell)" 8 +.br +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "long long" +or +.BR "unsigned long long" . +.IP "\fRj\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR intmax_t +or +.BR uintmax_t . +.IP "\fRz\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR size_t +or the corresponding signed integer type. +.IP "\fRt\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR ptrdiff_t +or the corresponding +.BR unsigned +type. +.IP "\fRL\fR" 8 +Specifies that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to an argument with type pointer to +.BR "long double" . +.P +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.P +The following conversion specifiers are valid: +.IP "\fRd\fP" 8 +Matches an optionally signed decimal integer, whose format is the same +as expected for the subject sequence of +\fIstrtol\fR() +with the value 10 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR int . +.IP "\fRi\fP" 8 +Matches an optionally signed integer, whose format is the same as +expected for the subject sequence of +\fIstrtol\fR() +with 0 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR int . +.IP "\fRo\fP" 8 +Matches an optionally signed octal integer, whose format is the same as +expected for the subject sequence of +\fIstrtoul\fR() +with the value 8 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRu\fP" 8 +Matches an optionally signed decimal integer, whose format is the same +as expected for the subject sequence of +\fIstrtoul\fR() +with the value 10 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRx\fP" 8 +Matches an optionally signed hexadecimal integer, whose format is the +same as expected for the subject sequence of +\fIstrtoul\fR() +with the value 16 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRa\fR,\ \fRe\fR,\ \fRf\fR,\ \fRg\fR" 8 +.br +Matches an optionally signed floating-point number, infinity, or NaN, +whose format is the same as expected for the subject sequence of +\fIstrtod\fR(). +In the absence of a size modifier, the application shall ensure that +the corresponding argument is a pointer to +.BR float . +.RS 8 +.P +If the +\fIfprintf\fR() +family of functions generates character string representations for +infinity and NaN (a symbolic entity encoded in floating-point +format) to support IEEE\ Std\ 754\(hy1985, the +\fIfscanf\fR() +family of functions shall recognize them as input. +.RE +.IP "\fRs\fP" 8 +Matches a sequence of bytes that are not white-space characters. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to the initial byte +of an array of +.BR char , +.BR "signed char" , +or +.BR "unsigned char" +large enough to accept the sequence and a terminating null character +code, which shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR char . +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the input is a sequence of characters that +begins in the initial shift state. Each character shall be converted to +a wide character as if by a call to the +\fImbrtowc\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first character is converted. +If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the sequence and the terminating null wide +character, which shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.RE +.IP "\fR[\fR" 8 +Matches a non-empty sequence of bytes from a set of expected bytes (the +.IR scanset ). +The normal skip over white-space characters shall be suppressed in this +case. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to the initial byte +of an array of +.BR char , +.BR "signed char" , +or +.BR "unsigned char" +large enough to accept the sequence and a terminating null byte, which +shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR char . +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the input is a sequence of characters that +begins in the initial shift state. Each character in the sequence shall +be converted to a wide character as if by a call to the +\fImbrtowc\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first character is converted. +If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the sequence and the terminating null wide +character, which shall be added automatically. +.br +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.P +The conversion specification includes all subsequent bytes in the +.IR format +string up to and including the matching + +(\c +.BR ']' ). +The bytes between the square brackets (the +.IR scanlist ) +comprise the scanset, unless the byte after the + +is a + +(\c +.BR '^' ), +in which case the scanset contains all bytes that do not appear in the +scanlist between the + +and the +. +If the conversion specification begins with +.BR \(dq[\|]\(dq +or +.BR \(dq[^]\(dq , +the + +is included in the scanlist and the next + +is the matching + +that ends the conversion specification; otherwise, the first + +is the one that ends the conversion specification. If a +.BR '\(mi' +is in the scanlist and is not the first character, nor the second where +the first character is a +.BR '^' , +nor the last character, the behavior is implementation-defined. +.RE +.IP "\fRc\fP" 8 +Matches a sequence of bytes of the number specified by the field width +(1 if no field width is present in the conversion specification). No +null byte is added. The normal skip over white-space characters +shall be suppressed in this case. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to the initial byte +of an array of +.BR char , +.BR "signed char" , +or +.BR "unsigned char" +large enough to accept the sequence. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR char . +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the input shall be a sequence of characters +that begins in the initial shift state. Each character in the sequence +is converted to a wide character as if by a call to the +\fImbrtowc\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first character is converted. +No null wide character is added. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the resulting sequence of wide characters. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.RE +.IP "\fRp\fP" 8 +Matches an implementation-defined set of sequences, which shall be the +same as the set of sequences that is produced by the +.BR %p +conversion specification of the corresponding +\fIfprintf\fR() +functions. The application shall ensure that the corresponding argument +is a pointer to a pointer to +.BR void . +The interpretation of the input item is implementation-defined. If +the input item is a value converted earlier during the same program +execution, the pointer that results shall compare equal to that value; +otherwise, the behavior of the +.BR %p +conversion specification is undefined. +.IP "\fRn\fP" 8 +No input is consumed. The application shall ensure that the +corresponding argument is a pointer to the integer into which shall be +written the number of bytes read from the input so far by this call to +the +\fIfscanf\fR() +functions. Execution of a +.BR %n +conversion specification shall not increment the assignment count +returned at the completion of execution of the function. No argument +shall be converted, but one shall be consumed. If the conversion +specification includes an assignment-suppressing character or a field +width, the behavior is undefined. +.IP "\fRC\fP" 8 +Equivalent to +.BR lc . +.IP "\fRS\fP" 8 +Equivalent to +.BR ls . +.IP "\fR%\fR" 8 +Matches a single +.BR '%' +character; no conversion or assignment occurs. The complete conversion +specification shall be +.BR %% . +.P +If a conversion specification is invalid, the behavior is undefined. +.P +The conversion specifiers +.BR A , +.BR E , +.BR F , +.BR G , +and +.BR X +are also valid and shall be equivalent to +.BR a , +.BR e , +.BR f , +.BR g , +and +.BR x , +respectively. +.P +If end-of-file is encountered during input, conversion shall be +terminated. If end-of-file occurs before any bytes matching the current +conversion specification (except for +.BR %n ) +have been read (other than leading white-space characters, where +permitted), execution of the current conversion specification shall +terminate with an input failure. Otherwise, unless execution of the +current conversion specification is terminated with a matching failure, +execution of the following conversion specification (if any) shall be +terminated with an input failure. +.P +Reaching the end of the string in +\fIsscanf\fR() +shall be equivalent to encountering end-of-file for +\fIfscanf\fR(). +.P +If conversion terminates on a conflicting input, the offending input is +left unread in the input. Any trailing white space (including + +characters) shall be left unread unless matched by a conversion +specification. The success of literal matches and suppressed assignments +is only directly determinable via the +.BR %n +conversion specification. +.P +The +\fIfscanf\fR() +and +\fIscanf\fR() +functions may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be +marked for update by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +\fIfscanf\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the number of +successfully matched and assigned input items; this number can be zero +in the event of an early matching failure. If the input ends before the +first conversion (if any) has completed, and without a matching failure +having occurred, EOF shall be returned. If an error occurs before the +first conversion (if any) has completed, and without a matching failure +having occurred, EOF shall be returned +and +.IR errno +shall be set to indicate the error. +If a read error occurs, the error indicator for the stream shall be set. +.SH ERRORS +For the conditions under which the +\fIfscanf\fR() +functions fail and may fail, refer to +.IR "\fIfgetc\fR\^(\|)" +or +.IR "\fIfgetwc\fR\^(\|)". +.P +In addition, the +\fIfscanf\fR() +function shall fail if: +.TP +.BR EILSEQ +Input byte sequence does not form a valid character. +.TP +.BR ENOMEM +Insufficient storage space is available. +.P +In addition, the +\fIfscanf\fR() +function may fail if: +.TP +.BR EINVAL +There are insufficient arguments. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The call: +.sp +.RS 4 +.nf +\fB +int i, n; float x; char name[50]; +n = scanf("%d%f%s", &i, &x, name); +.fi \fR +.P +.RE +.P +with the input line: +.sp +.RS 4 +.nf +\fB +25 54.32E\(mi1 Hamster +.fi \fR +.P +.RE +.P +assigns to +.IR n +the value 3, to +.IR i +the value 25, to +.IR x +the value 5.432, and +.IR name +contains the string +.BR \(dqHamster\(dq . +.P +The call: +.sp +.RS 4 +.nf +\fB +int i; float x; char name[50]; +(void) scanf("%2d%f%*d %[0123456789]", &i, &x, name); +.fi \fR +.P +.RE +.P +with input: +.sp +.RS 4 +.nf +\fB +56789 0123 56a72 +.fi \fR +.P +.RE +.P +assigns 56 to +.IR i , +789.0 to +.IR x , +skips 0123, and places the string +.BR \(dq56\e0\(dq +in +.IR name . +The next call to +\fIgetchar\fR() +shall return the character +.BR 'a' . +.SS "Reading Data into an Array" +.P +The following call uses +\fIfscanf\fR() +to read three floating-point numbers from standard input into the +.IR input +array. +.sp +.RS 4 +.nf +\fB +float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +If the application calling +\fIfscanf\fR() +has any objects of type +.BR wint_t +or +.BR wchar_t , +it must also include the +.IR +header to have these objects defined. +.P +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIfscanf\fR(), +this is memory allocated via use of the +.BR 'm' +assignment-allocation character. +.SH RATIONALE +This function is aligned with the ISO/IEC\ 9899:\|1999 standard, and in doing so a few +``obvious'' things were not included. Specifically, the set of +characters allowed in a scanset is limited to single-byte characters. +In other similar places, multi-byte characters have been permitted, but +for alignment with the ISO/IEC\ 9899:\|1999 standard, it has not been done here. Applications +needing this could use the corresponding wide-character functions to +achieve the desired results. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIstrtol\fR\^(\|)", +.IR "\fIstrtoul\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fseek.3p b/man-pages-posix-2013-a/man3p/fseek.3p new file mode 100644 index 0000000..93eb0b1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fseek.3p @@ -0,0 +1,250 @@ +'\" et +.TH FSEEK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fseek, +fseeko +\(em reposition a file-position indicator in a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fseek(FILE *\fIstream\fP, long \fIoffset\fP, int \fIwhence\fP); +int fseeko(FILE *\fIstream\fP, off_t \fIoffset\fP, int \fIwhence\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfseek\fR() +function shall set the file-position indicator for the stream pointed +to by +.IR stream . +If a read or write error occurs, the error indicator for the stream +shall be set and +\fIfseek\fR() +fails. +.P +The new position, measured in bytes from the beginning of the file, +shall be obtained by adding +.IR offset +to the position specified by +.IR whence . +The specified point is the beginning of the file for SEEK_SET, the +current value of the file-position indicator for SEEK_CUR, or +end-of-file for SEEK_END. +.P +If the stream is to be used with wide-character input/output functions, +the application shall ensure that +.IR offset +is either 0 or a value returned by an earlier call to +\fIftell\fR() +on the same stream and +.IR whence +is SEEK_SET. +.P +A successful call to +\fIfseek\fR() +shall clear the end-of-file indicator for the stream and undo any +effects of +\fIungetc\fR() +and +\fIungetwc\fR() +on the same stream. After an +\fIfseek\fR() +call, the next operation on an update stream may be either input or +output. +.P +If the most recent operation, other than +\fIftell\fR(), +on a given stream is +\fIfflush\fR(), +the file offset in the underlying open file description shall be +adjusted to reflect the location specified by +\fIfseek\fR(). +.P +The +\fIfseek\fR() +function shall allow the file-position indicator to be set beyond the +end of existing data in the file. If data is later written at this +point, subsequent reads of data in the gap shall return bytes with the +value 0 until data is actually written into the gap. +.P +The behavior of +\fIfseek\fR() +on devices which are incapable of seeking is implementation-defined. +The value of the file offset associated with such a device is +undefined. +.P +If the stream is writable and buffered data had not been written to the +underlying file, +\fIfseek\fR() +shall cause the unwritten data to be written to the file and shall mark +the last data modification and last file status change timestamps +of the file for update. +.P +In a locale with state-dependent encoding, whether +\fIfseek\fR() +restores the stream's shift state is implementation-defined. +.P +The +\fIfseeko\fR() +function shall be equivalent to the +\fIfseek\fR() +function except that the +.IR offset +argument is of type +.BR off_t . +.SH "RETURN VALUE" +The +\fIfseek\fR() +and +\fIfseeko\fR() +functions shall return 0 if they succeed. +.P +Otherwise, they shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfseek\fR() +and +\fIfseeko\fR() +functions shall fail if, +either the +.IR stream +is unbuffered or the +.IR stream 's +buffer needed to be flushed, and the call to +\fIfseek\fR() +or +\fIfseeko\fR() +causes an underlying +\fIlseek\fR() +or +\fIwrite\fR() +to be invoked, and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor and the thread +would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying the stream file is not open for writing +or the stream's buffer needed to be flushed and the file is not open. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the maximum file size. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the file size +limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding stream. +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP +.BR EINVAL +The +.IR whence +argument is invalid. The resulting file-position indicator would be +set to a negative value. +.TP +.BR EIO +A physical I/O error has occurred, or the process is a member of a +background process group attempting to perform a +\fIwrite\fR() +to its controlling terminal, TOSTOP is set, the calling thread is not +blocking SIGTTOU, the process is not ignoring SIGTTOU, and the process +group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR EOVERFLOW +For +\fIfseek\fR(), +the resulting file offset would be a value which cannot be represented +correctly in an object of type +.BR long . +.TP +.BR EOVERFLOW +For +\fIfseeko\fR(), +the resulting file offset would be a value which cannot be represented +correctly in an object of type +.BR off_t . +.TP +.BR EPIPE +An attempt was made to write to a pipe or FIFO that is not open for +reading by any process; a SIGPIPE +signal shall also be sent to the thread. +.TP +.BR ESPIPE +The file descriptor underlying +.IR stream +is associated with a pipe, FIFO, or socket. +.P +The +\fIfseek\fR() +and +\fIfseeko\fR() +functions may fail if: +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfsetpos\fR\^(\|)", +.IR "\fIftell\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fsetpos.3p b/man-pages-posix-2013-a/man3p/fsetpos.3p new file mode 100644 index 0000000..b9a5f45 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fsetpos.3p @@ -0,0 +1,172 @@ +'\" et +.TH FSETPOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fsetpos +\(em set current file position +.SH SYNOPSIS +.LP +.nf +#include +.P +int fsetpos(FILE *\fIstream\fP, const fpos_t *\fIpos\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfsetpos\fR() +function shall set the file position and state indicators for the +stream pointed to by +.IR stream +according to the value of the object pointed to by +.IR pos , +which the application shall ensure is a value obtained from an earlier +call to +\fIfgetpos\fR() +on the same stream. If a read or write error occurs, the error +indicator for the stream shall be set and +\fIfsetpos\fR() +fails. +.P +A successful call to the +\fIfsetpos\fR() +function shall clear the end-of-file indicator for the stream and +undo any effects of +\fIungetc\fR() +on the same stream. After an +\fIfsetpos\fR() +call, the next operation on an update stream may be either input or +output. +.P +The behavior of +\fIfsetpos\fR() +on devices which are incapable of seeking is implementation-defined. +The value of the file offset associated with such a device is +undefined. +.P +The +\fIfsetpos\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +The +\fIfsetpos\fR() +function shall return 0 if it succeeds; otherwise, it shall return +a non-zero value and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfsetpos\fR() +function shall fail if, +either the +.IR stream +is unbuffered or the +.IR stream 's +buffer needed to be flushed, and the call to +\fIfsetpos\fR() +causes an underlying +\fIlseek\fR() +or +\fIwrite\fR() +to be invoked, and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor and the thread +would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying the stream file is not open for writing +or the stream's buffer needed to be flushed and the file is not open. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the maximum file size. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the file size +limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding stream. +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is a member of a +background process group attempting to perform a +\fIwrite\fR() +to its controlling terminal, TOSTOP is set, the calling thread is not +blocking SIGTTOU, the process is not ignoring SIGTTOU, and the process +group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR EPIPE +An attempt was made to write to a pipe or FIFO that is not open for +reading by any process; a SIGPIPE +signal shall also be sent to the thread. +.TP +.BR ESPIPE +The file descriptor underlying +.IR stream +is associated with a pipe, FIFO, or socket. +.P +The +\fIfsetpos\fR() +function may fail if: +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIftell\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fstat.3p b/man-pages-posix-2013-a/man3p/fstat.3p new file mode 100644 index 0000000..abc8c2b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fstat.3p @@ -0,0 +1,192 @@ +'\" et +.TH FSTAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fstat +\(em get file status +.SH SYNOPSIS +.LP +.nf +#include +.P +int fstat(int \fIfildes\fP, struct stat *\fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fIfstat\fR() +function shall obtain information about an open file associated with +the file descriptor +.IR fildes , +and shall write it to the area pointed to by +.IR buf . +.P +If +.IR fildes +references a shared memory object, the implementation shall update in +the +.BR stat +structure pointed to by the +.IR buf +argument the +.IR st_uid , +.IR st_gid , +.IR st_size , +and +.IR st_mode +fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and +S_IWOTH file permission bits need be valid. +The implementation may update other fields and flags. +.P +If +.IR fildes +references a typed memory object, the implementation shall update in +the +.BR stat +structure pointed to by the +.IR buf +argument the +.IR st_uid , +.IR st_gid , +.IR st_size , +and +.IR st_mode +fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and +S_IWOTH file permission bits need be valid. The implementation +may update other fields and flags. +.P +The +.IR buf +argument is a pointer to a +.BR stat +structure, as defined in +.IR , +into which information is placed concerning the file. +.P +For all other file types defined in this volume of POSIX.1\(hy2008, the structure members +.IR st_mode , +.IR st_ino , +.IR st_dev , +.IR st_uid , +.IR st_gid , +.IR st_atim , +.IR st_ctim , +and +.IR st_mtim +shall have meaningful values and the value of the +.IR st_nlink +member shall be set to the number of links to the file. +.P +An implementation that provides additional or alternative file access +control mechanisms may, under implementation-defined conditions, +cause +\fIfstat\fR() +to fail. +.P +The +\fIfstat\fR() +function shall update any time-related fields (as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.8" ", " "File Times Update"), +before writing into the +.BR stat +structure. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfstat\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EIO +An I/O error occurred while reading from the file system. +.TP +.BR EOVERFLOW +The file size in bytes or the number of blocks allocated to the file or +the file serial number cannot be represented correctly in the structure +pointed to by +.IR buf . +.P +The +\fIfstat\fR() +function may fail if: +.TP +.BR EOVERFLOW +One of the values is too large to store into the structure pointed to +by the +.IR buf +argument. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Obtaining File Status Information " +.P +The following example shows how to obtain file status information for a +file named +.BR /home/cnd/mod1 . +The structure variable +.IR buffer +is defined for the +.BR stat +structure. The +.BR /home/cnd/mod1 +file is opened with read/write privileges and is passed to the open +file descriptor +.IR fildes . +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +struct stat buffer; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = fstat(fildes, &buffer); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfstatat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.8" ", " "File Times Update", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fstatat.3p b/man-pages-posix-2013-a/man3p/fstatat.3p new file mode 100644 index 0000000..8b6e2a7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fstatat.3p @@ -0,0 +1,493 @@ +'\" et +.TH FSTATAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fstatat, +lstat, +stat +\(em get file status +.SH SYNOPSIS +.LP +.nf +#include +.P +int fstatat(int fd, const char *restrict \fIpath\fP, + struct stat *restrict \fIbuf\fP, int \fIflag\fP); +int lstat(const char *restrict \fIpath\fP, struct stat *restrict \fIbuf\fP); +int stat(const char *restrict \fIpath\fP, struct stat *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fIstat\fR() +function shall obtain information about the named file and write it +to the area pointed to by the +.IR buf +argument. The +.IR path +argument points to a pathname naming a file. Read, write, or execute +permission of the named file is not required. An implementation that +provides additional or alternate file access control mechanisms may, +under implementation-defined conditions, cause +\fIstat\fR() +to fail. In particular, the system may deny the existence of the file +specified by +.IR path . +.P +If the named file is a symbolic link, the +\fIstat\fR() +function shall continue pathname resolution using the contents of the +symbolic link, and shall return information pertaining to the resulting +file if the file exists. +.P +The +.IR buf +argument is a pointer to a +.BR stat +structure, as defined in the +.IR +header, into which information is placed concerning the file. +.P +The +\fIstat\fR() +function shall update any time-related fields (as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.8" ", " "File Times Update"), +before writing into the +.BR stat +structure. +.P +If the named file is a shared memory object, the implementation +shall update in the +.BR stat +structure pointed to by the +.IR buf +argument the +.IR st_uid , +.IR st_gid , +.IR st_size , +and +.IR st_mode +fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and +S_IWOTH file permission bits need be valid. The implementation may +update other fields and flags. +.P +If the named file is a typed memory object, the implementation +shall update in the +.BR stat +structure pointed to by the +.IR buf +argument the +.IR st_uid , +.IR st_gid , +.IR st_size , +and +.IR st_mode +fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and +S_IWOTH file permission bits need be valid. The implementation may +update other fields and flags. +.P +For all other file types defined in this volume of POSIX.1\(hy2008, the structure members +.IR st_mode , +.IR st_ino , +.IR st_dev , +.IR st_uid , +.IR st_gid , +.IR st_atim , +.IR st_ctim , +and +.IR st_mtim +shall have meaningful values and the value of the member +.IR st_nlink +shall be set to the number of links to the file. +.P +The +\fIlstat\fR() +function shall be equivalent to +\fIstat\fR(), +except when +.IR path +refers to a symbolic link. In that case +\fIlstat\fR() +shall return information about the link, while +\fIstat\fR() +shall return information about the file the link references. +.P +For symbolic links, the +.IR st_mode +member shall contain meaningful information when used with the file +type macros. The file mode bits in +.IR st_mode +are unspecified. The structure members +.IR st_ino , +.IR st_dev , +.IR st_uid , +.IR st_gid , +.IR st_atim , +.IR st_ctim , +and +.IR st_mtim +shall have meaningful values and the value of the +.IR st_nlink +member shall be set to the number of (hard) links to the symbolic link. +The value of the +.IR st_size +member shall be set to the length of the pathname contained in the +symbolic link not including any terminating null byte. +.P +The +\fIfstatat\fR() +function shall be equivalent to the +\fIstat\fR() +or +\fIlstat\fR() +function, depending on the value of +.IR flag +(see below), except in the case where +.IR path +specifies a relative path. In this case the status shall be retrieved +from a file relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, the status of the symbolic link is returned. +.P +If +\fIfstatat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIstat\fR() +or +\fIlstat\fR() +respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit +is set in +.IR flag . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix. +.TP +.BR EIO +An error occurred while reading from the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EOVERFLOW +The file size in bytes or the number of blocks allocated to the file or +the file serial number cannot be represented correctly in the structure +pointed to by +.IR buf . +.P +The +\fIfstatat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR EOVERFLOW +A value to be stored would overflow one of the members of the +.BR stat +structure. +.br +.P +The +\fIfstatat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Obtaining File Status Information" +.P +The following example shows how to obtain file status information for a +file named +.BR /home/cnd/mod1 . +The structure variable +.IR buffer +is defined for the +.BR stat +structure. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +struct stat buffer; +int status; +\&... +status = stat("/home/cnd/mod1", &buffer); +.fi \fR +.P +.RE +.SS "Getting Directory Information" +.P +The following example fragment gets status information for each entry +in a directory. The call to the +\fIstat\fR() +function stores file information in the +.BR stat +structure pointed to by +.IR statbuf . +The lines that follow the +\fIstat\fR() +call format the fields in the +.BR stat +structure for presentation to the user of the program. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +.P +struct dirent *dp; +struct stat statbuf; +struct passwd *pwd; +struct group *grp; +struct tm *tm; +char datestring[256]; +\&... +/* Loop through directory entries. */ +while ((dp = readdir(dir)) != NULL) { +.P + /* Get entry's information. */ + if (stat(dp->d_name, &statbuf) == -1) + continue; +.P + /* Print out type, permissions, and number of links. */ + printf("%10.10s", sperm (statbuf.st_mode)); + printf("%4d", statbuf.st_nlink); +.P + /* Print out owner's name if it is found using getpwuid(). */ + if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); + else + printf(" %-8d", statbuf.st_uid); +.P + /* Print out group name if it is found using getgrgid(). */ + if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); + else + printf(" %-8d", statbuf.st_gid); +.P + /* Print size of file. */ + printf(" %9jd", (intmax_t)statbuf.st_size); +.P + tm = localtime(&statbuf.st_mtime); +.P + /* Get localized date string. */ + strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); +.P + printf(" %s %s\en", datestring, dp->d_name); +} +.fi \fR +.P +.RE +.SS "Obtaining Symbolic Link Status Information" +.P +The following example shows how to obtain status information for a +symbolic link named +.BR /modules/pass1 . +The structure variable +.IR buffer +is defined for the +.BR stat +structure. If the +.IR path +argument specified the pathname for the file pointed to by the symbolic +link (\c +.BR /home/cnd/mod1 ), +the results of calling the function would be the same as those returned +by a call to the +\fIstat\fR() +function. +.sp +.RS 4 +.nf +\fB +#include +.P +struct stat buffer; +int status; +\&... +status = lstat("/modules/pass1", &buffer); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The intent of the paragraph describing ``additional or alternate file +access control mechanisms'' is to allow a secure implementation where a +process +with a label that does not dominate the file's label cannot perform a +\fIstat\fR() +function. This is not related to read permission; a process with a +label that dominates the file's label does not need read permission. +An implementation that supports write-up operations could fail +\fIfstat\fR() +function calls even though it has a valid file descriptor open for +writing. +.P +The +\fIlstat\fR() +function is not required to update the time-related fields if the named +file is not a symbolic link. While the +.IR st_uid , +.IR st_gid , +.IR st_atim , +.IR st_mtim , +and +.IR st_ctim +members of the +.BR stat +structure may apply to a symbolic link, they are not required to do so. +No functions in POSIX.1\(hy2008 are required to maintain any of these time +fields. +.P +The purpose of the +\fIfstatat\fR() +function is to obtain the status of files in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIstat\fR(), +resulting in unspecified behavior. By opening a file descriptor for the +target directory and using the +\fIfstatat\fR() +function it can be guaranteed that the file for which status is returned +is located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccess\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstat\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIreadlink\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.8" ", " "File Times Update", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fstatvfs.3p b/man-pages-posix-2013-a/man3p/fstatvfs.3p new file mode 100644 index 0000000..73184a8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fstatvfs.3p @@ -0,0 +1,233 @@ +'\" et +.TH FSTATVFS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fstatvfs, +statvfs +\(em get file system information +.SH SYNOPSIS +.LP +.nf +#include +.P +int fstatvfs(int \fIfildes\fP, struct statvfs *\fIbuf\fP); +int statvfs(const char *restrict \fIpath\fP, struct statvfs *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fIfstatvfs\fR() +function shall obtain information about the file system containing +the file referenced by +.IR fildes . +.P +The +\fIstatvfs\fR() +function shall obtain information about the file system +containing the file named by +.IR path . +.P +For both functions, the +.IR buf +argument is a pointer to a +.BR statvfs +structure that shall be filled. Read, write, or execute permission of +the named file is not required. +.P +The following flags can be returned in the +.IR f_flag +member: +.IP ST_RDONLY 12 +Read-only file system. +.IP ST_NOSUID 12 +Setuid/setgid bits ignored by +.IR exec . +.P +It is unspecified whether all members of the +.BR statvfs +structure have meaningful values on all file systems. +.SH "RETURN VALUE" +Upon successful completion, +\fIstatvfs\fR() +shall return 0. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfstatvfs\fR() +and +\fIstatvfs\fR() +functions shall fail if: +.TP +.BR EIO +An I/O error occurred while reading the file system. +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR EOVERFLOW +One of the values to be returned cannot be represented correctly in +the structure pointed to by +.IR buf . +.P +The +\fIfstatvfs\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.P +The +\fIstatvfs\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIstatvfs\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Obtaining File System Information Using fstatvfs(\|)" +.P +The following example shows how to obtain file system information for +the file system upon which the file named +.BR /home/cnd/mod1 +resides, using the +\fIfstatvfs\fR() +function. The +.BR /home/cnd/mod1 +file is opened with read/write privileges and the open file descriptor +is passed to the +\fIfstatvfs\fR() +function. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +struct statvfs buffer; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = fstatvfs(fildes, &buffer); +.fi \fR +.P +.RE +.SS "Obtaining File System Information Using statvfs(\|)" +.P +The following example shows how to obtain file system information for +the file system upon which the file named +.BR /home/cnd/mod1 +resides, using the +\fIstatvfs\fR() +function. +.sp +.RS 4 +.nf +\fB +#include +.P +struct statvfs buffer; +int status; +\&... +status = statvfs("/home/cnd/mod1", &buffer); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIchown\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)", +.IR "\fIutime\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fsync.3p b/man-pages-posix-2013-a/man3p/fsync.3p new file mode 100644 index 0000000..10f3736 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fsync.3p @@ -0,0 +1,152 @@ +'\" et +.TH FSYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fsync +\(em synchronize changes to a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int fsync(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIfsync\fR() +function shall request that all data for the open file descriptor +named by +.IR fildes +is to be transferred to the storage device associated with the file +described by +.IR fildes . +The nature of the transfer is implementation-defined. The +\fIfsync\fR() +function shall not return until the system has completed that action +or until an error is detected. +.P +If _POSIX_SYNCHRONIZED_IO is defined, the +\fIfsync\fR() +function shall force all currently queued I/O operations associated +with the file indicated by file descriptor +.IR fildes +to the synchronized I/O completion state. All I/O operations shall be +completed as defined for synchronized I/O file integrity completion. +.SH "RETURN VALUE" +Upon successful completion, +\fIfsync\fR() +shall return 0. Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. If the +\fIfsync\fR() +function fails, outstanding I/O operations are not guaranteed to have +been completed. +.SH ERRORS +The +\fIfsync\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid descriptor. +.TP +.BR EINTR +The +\fIfsync\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +.IR fildes +argument does not refer to a file on which this operation is possible. +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.P +In the event that any of the queued I/O operations fail, +\fIfsync\fR() +shall return the error conditions defined for +\fIread\fR() +and +\fIwrite\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIfsync\fR() +function should be used by programs which require modifications to a +file to be completed before continuing; for example, a program which +contains a simple transaction facility might use it to ensure that all +modifications to a file or files caused by a transaction are recorded. +.SH RATIONALE +The +\fIfsync\fR() +function is intended to force a physical write of data from the buffer +cache, and to assure that after a system crash or other failure that +all data up to the time of the +\fIfsync\fR() +call is recorded on the disk. Since the concepts of ``buffer cache'', +``system crash'', ``physical write'', and ``non-volatile storage'' +are not defined here, the wording has to be more abstract. +.P +If _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily on +the conformance document to tell the user what can be expected from the +system. It is explicitly intended that a null implementation is +permitted. This could be valid in the case where the system cannot +assure non-volatile storage under any circumstances or when the system +is highly fault-tolerant and the functionality is not required. In the +middle ground between these extremes, +\fIfsync\fR() +might or might not actually cause data to be written where it is safe +from a power failure. The conformance document should identify at least +that one configuration exists (and how to obtain that configuration) +where this can be assured for at least some files that the user can +select to use for critical data. It is not intended that an exhaustive +list is required, but rather sufficient information is provided so that +if critical data needs to be saved, the user can determine how the +system is to be configured to allow the data to be written to +non-volatile storage. +.P +It is reasonable to assert that the key aspects of +\fIfsync\fR() +are unreasonable to test in a test suite. That does not make the +function any less valuable, just more difficult to test. A formal +conformance test should probably force a system crash (power shutdown) +during the test for this condition, but it needs to be done in such a +way that automated testing does not require this to be done except when +a formal record of the results is being made. It would also not be +unreasonable to omit testing for +\fIfsync\fR(), +allowing it to be treated as a quality-of-implementation issue. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsync\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ftell.3p b/man-pages-posix-2013-a/man3p/ftell.3p new file mode 100644 index 0000000..fed666a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ftell.3p @@ -0,0 +1,129 @@ +'\" et +.TH FTELL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ftell, +ftello +\(em return a file offset in a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +long ftell(FILE *\fIstream\fP); +off_t ftello(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIftell\fR() +function shall obtain the current value of the file-position indicator +for the stream pointed to by +.IR stream . +.P +The +\fIftell\fR() +function shall not change the setting of +.IR errno +if successful. +.P +The +\fIftello\fR() +function shall be equivalent to +\fIftell\fR(), +except that the return value is of type +.BR off_t +and the +\fIftello\fR() +function may change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +Upon successful completion, +\fIftell\fR() +and +\fIftello\fR() +shall return the current value of the file-position indicator for the +stream measured in bytes from the beginning of the file. +.P +Otherwise, +\fIftell\fR() +and +\fIftello\fR() +shall return \(mi1, and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIftell\fR() +and +\fIftello\fR() +functions shall fail if: +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not an open file descriptor. +.TP +.BR EOVERFLOW +For +\fIftell\fR(), +the current file offset cannot be represented correctly in an object of +type +.BR long . +.TP +.BR EOVERFLOW +For +\fIftello\fR(), +the current file offset cannot be represented correctly in an object of +type +.BR off_t . +.TP +.BR ESPIPE +The file descriptor underlying +.IR stream +is associated with a pipe, FIFO, or socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetpos\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ftok.3p b/man-pages-posix-2013-a/man3p/ftok.3p new file mode 100644 index 0000000..7b30e2e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ftok.3p @@ -0,0 +1,193 @@ +'\" et +.TH FTOK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ftok +\(em generate an IPC key +.SH SYNOPSIS +.LP +.nf +#include +.P +key_t ftok(const char *\fIpath\fP, int \fIid\fP); +.fi +.SH DESCRIPTION +The +\fIftok\fR() +function shall return a key based on +.IR path +and +.IR id +that is usable in subsequent calls to +\fImsgget\fR(), +\fIsemget\fR(), +and +\fIshmget\fR(). +The application shall ensure that the +.IR path +argument is the pathname of an existing file that the process is +able to +\fIstat\fR(), +with the exception that if +\fIstat\fR() +would fail with +.BR [EOVERFLOW] +due to file size, +\fIftok\fR() +shall still succeed. +.P +The +\fIftok\fR() +function shall return the same key value for all paths that name the +same file, when called with the same +.IR id +value, and should return different key values when called with different +.IR id +values or with paths that name different files existing on the same +file system at the same time. It is unspecified whether +\fIftok\fR() +shall return the same key value when called again after the file named +by +.IR path +is removed and recreated with the same name. +.P +Only the low-order 8-bits of +.IR id +are significant. The behavior of +\fIftok\fR() +is unspecified if these bits are 0. +.SH "RETURN VALUE" +Upon successful completion, +\fIftok\fR() +shall return a key. Otherwise, +\fIftok\fR() +shall return (\fBkey_t\fP)\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIftok\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix. +.TP +.BR EIO +An error occurred while reading from the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.P +The +\fIftok\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting an IPC Key" +.P +The following example gets a key based on the pathname +.BR /tmp +and the ID value +.IR a . +It also assigns the value of the resulting key to the +.IR semkey +variable so that it will be available to a later call to +\fIsemget\fR(), +\fImsgget\fR(), +or +\fIshmget\fR(). +.sp +.RS 4 +.nf +\fB +#include +\&... +key_t semkey; +.P +if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { + perror("IPC error: ftok"); exit(1); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +For maximum portability, +.IR id +should be a single-byte character. +.P +Applications should not assume that the resulting key value is unique. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +Future versions of this standard may add new interfaces to provide +unique keys. +.SH "SEE ALSO" +.IR "\fImsgget\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ftruncate.3p b/man-pages-posix-2013-a/man3p/ftruncate.3p new file mode 100644 index 0000000..e24175a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ftruncate.3p @@ -0,0 +1,161 @@ +'\" et +.TH FTRUNCATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ftruncate +\(em truncate a file to a specified length +.SH SYNOPSIS +.LP +.nf +#include +.P +int ftruncate(int \fIfildes\fP, off_t \fIlength\fP); +.fi +.SH DESCRIPTION +If +.IR fildes +is not a valid file descriptor open for writing, the +\fIftruncate\fR() +function shall fail. +.P +If +.IR fildes +refers to a regular file, the +\fIftruncate\fR() +function shall cause the size of the file to be truncated to +.IR length . +If the size of the file previously exceeded +.IR length , +the extra data shall no longer be available to reads on the file. If +the file previously was smaller than this size, +\fIftruncate\fR() +shall increase the size of the file. If the file size is increased, +the extended area shall appear as if it were zero-filled. The value of +the seek pointer shall not be modified by a call to +\fIftruncate\fR(). +.P +Upon successful completion, if +.IR fildes +refers to a regular file, +\fIftruncate\fR() +shall mark for update the last data modification and last file +status change timestamps of the file and the S_ISUID and S_ISGID bits +of the file mode may be cleared. If the +\fIftruncate\fR() +function is unsuccessful, the file is unaffected. +.P +If the request would cause the file size to exceed the soft file size +limit for the process, the request shall fail and the implementation +shall generate the SIGXFSZ signal for the thread. +.P +If +.IR fildes +refers to a directory, +\fIftruncate\fR() +shall fail. +.P +If +.IR fildes +refers to any other file type, except a shared memory object, the +result is unspecified. +.P +If +.IR fildes +refers to a shared memory object, +\fIftruncate\fR() +shall set the size of the shared memory object to +.IR length . +.P +If the effect of +\fIftruncate\fR() +is to decrease the size of a memory mapped file +or a shared memory object +and whole pages beyond the new end were previously mapped, then the +whole pages beyond the new end shall be discarded. +.P +References to discarded pages shall result in the generation of a +SIGBUS signal. +.P +If the effect of +\fIftruncate\fR() +is to increase the size of a memory object, it is unspecified +whether the contents of any mapped pages between the old end-of-file +and the new are flushed to the underlying object. +.SH "RETURN VALUE" +Upon successful completion, +\fIftruncate\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIftruncate\fR() +function shall fail if: +.TP +.BR EINTR +A signal was caught during execution. +.TP +.BR EINVAL +The +.IR length +argument was less than 0. +.TP +.BR EFBIG " or " EINVAL +.br +The +.IR length +argument was greater than the maximum file size. +.TP +.BR EFBIG +The file is a regular file and +.IR length +is greater than the offset maximum established in the open file +description associated with +.IR fildes . +.TP +.BR EIO +An I/O error occurred while reading from or writing to a file system. +.TP +.BR EBADF " or " EINVAL +.br +The +.IR fildes +argument is not a file descriptor open for writing. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)", +.IR "\fItruncate\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ftrylockfile.3p b/man-pages-posix-2013-a/man3p/ftrylockfile.3p new file mode 100644 index 0000000..5fa236a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ftrylockfile.3p @@ -0,0 +1,38 @@ +'\" et +.TH FTRYLOCKFILE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ftrylockfile +\(em stdio locking functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int ftrylockfile(FILE *\fIfile\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIflockfile\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ftw.3p b/man-pages-posix-2013-a/man3p/ftw.3p new file mode 100644 index 0000000..2befe8f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ftw.3p @@ -0,0 +1,284 @@ +'\" et +.TH FTW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ftw +\(em traverse (walk) a file tree +.SH SYNOPSIS +.LP +.nf +#include +.P +int ftw(const char *\fIpath\fP, int (*\fIfn\fP)(const char *, + const struct stat *\fIptr\fP, int \fIflag\fP), int \fIndirs\fP); +.fi +.SH DESCRIPTION +The +\fIftw\fR() +function shall recursively descend the directory hierarchy rooted in +.IR path . +For each object in the hierarchy, +\fIftw\fR() +shall call the function pointed to by +.IR fn , +passing it a pointer to a null-terminated character string containing +the name of the object, a pointer to a +.BR stat +structure containing information about the object, filled in as if +\fIstat\fR() +or +\fIlstat\fR() +had been called to retrieve the information. Possible values of the +integer, defined in the +.IR +header, are: +.IP FTW_D 10 +For a directory. +.IP FTW_DNR 10 +For a directory that cannot be read. +.IP FTW_F 10 +For a non-directory file. +.IP FTW_SL 10 +For a symbolic link (but see also FTW_NS below). +.IP FTW_NS 10 +For an object other than a symbolic link on which +\fIstat\fR() +could not successfully be executed. If the object is a symbolic link +and +\fIstat\fR() +failed, it is unspecified whether +\fIftw\fR() +passes FTW_SL or FTW_NS to the user-supplied function. +.P +If the integer is FTW_DNR, descendants of that directory shall not be +processed. If the integer is FTW_NS, the +.BR stat +structure contains undefined values. An example of an object that +would cause FTW_NS to be passed to the function pointed to by +.IR fn +would be a file in a directory with read but without execute (search) +permission. +.P +The +\fIftw\fR() +function shall visit a directory before visiting any of its +descendants. +.P +The +\fIftw\fR() +function shall use at most one file descriptor for each level in +the tree. +.P +The argument +.IR ndirs +should be in the range [1,\c +{OPEN_MAX}]. +.P +The tree traversal shall continue until either the tree is exhausted, +an invocation of +.IR fn +returns a non-zero value, or some error, other than +.BR [EACCES] , +is detected within +\fIftw\fR(). +.P +The +.IR ndirs +argument shall specify the maximum number of directory streams or file +descriptors or both available for use by +\fIftw\fR() +while traversing the tree. When +\fIftw\fR() +returns it shall close any directory streams and file descriptors it +uses not counting any opened by the application-supplied +.IR fn +function. +.P +The results are unspecified if the application-supplied +.IR fn +function does not preserve the current working directory. +.P +The +\fIftw\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If the tree is exhausted, +\fIftw\fR() +shall return 0. If the function pointed to by +.IR fn +returns a non-zero value, +\fIftw\fR() +shall stop its tree traversal and return whatever value was returned +by the function pointed to by +.IR fn . +If +\fIftw\fR() +detects an error, it shall return \(mi1 and set +.IR errno +to indicate the error. +.P +If +\fIftw\fR() +encounters an error other than +.BR [EACCES] +(see FTW_DNR and FTW_NS above), it shall return \(mi1 and set +.IR errno +to indicate the error. The external variable +.IR errno +may contain any error value that is possible when a directory is opened +or when one of the +.IR stat +functions is executed on a directory or file. +.SH ERRORS +The +\fIftw\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for any component of +.IR path +or read permission is denied for +.IR path . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of +.IR path +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EOVERFLOW +A field in the +.BR stat +structure cannot be represented correctly in the current programming +environment for one or more files found in the file hierarchy. +.P +The +\fIftw\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR ndirs +argument is invalid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.P +In addition, if the function pointed to by +.IR fn +encounters system errors, +.IR errno +may be set accordingly. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Walking a Directory Structure" +.P +The following example walks the current directory structure, calling +the +.IR fn +function for every directory entry, using at most 10 file descriptors: +.sp +.RS 4 +.nf +\fB +#include +\&... +if (ftw(".", fn, 10) != 0) { + perror("ftw"); exit(2); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIftw\fR() +function may allocate dynamic storage during its operation. If +\fIftw\fR() +is forcibly terminated, such as by +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +being executed by the function pointed to by +.IR fn +or an interrupt routine, +\fIftw\fR() +does not have a chance to free that storage, so it remains +permanently allocated. A safe way to handle interrupts is to store the +fact that an interrupt has occurred, and arrange to have the function +pointed to by +.IR fn +return a non-zero value at its next invocation. +.P +Applications should use the +\fInftw\fR() +function instead of the obsolescent +\fIftw\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIftw\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fInftw\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/funlockfile.3p b/man-pages-posix-2013-a/man3p/funlockfile.3p new file mode 100644 index 0000000..ed048b1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/funlockfile.3p @@ -0,0 +1,38 @@ +'\" et +.TH FUNLOCKFILE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +funlockfile +\(em stdio locking functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void funlockfile(FILE *\fIfile\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIflockfile\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/futimens.3p b/man-pages-posix-2013-a/man3p/futimens.3p new file mode 100644 index 0000000..e270c19 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/futimens.3p @@ -0,0 +1,383 @@ +'\" et +.TH FUTIMENS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +futimens, utimensat, utimes +\(em set file access and modification times +.SH SYNOPSIS +.LP +.nf +#include +.P +int futimens(int \fIfd\fP, const struct timespec \fItimes\fP[2]); +int utimensat(int \fIfd\fP, const char *\fIpath\fP, const struct timespec \fItimes\fP[2], + int \fIflag\fP); +.P +#include +.P +int utimes(const char *\fIpath\fP, const struct timeval \fItimes\fP[2]); +.fi +.SH DESCRIPTION +The +\fIfutimens\fR() +and +\fIutimensat\fR() +functions shall set the access and modification times of a file +to the values of the +.IR times +argument. The +\fIfutimens\fR() +function changes the times of the file associated with the file +descriptor +.IR fd . +The +\fIutimensat\fR() +function changes the times of the file pointed to by the +.IR path +argument, relative to the directory associated with the file +descriptor +.IR fd . +Both functions allow time specifications accurate to the nanosecond. +.P +For +\fIfutimens\fR() +and +\fIutimensat\fR(), +the +.IR times +argument is an array of two +.BR timespec +structures. The first array member represents the date and time of +last access, and the second member represents the date and time of last +modification. The times in the +.BR timespec +structure are measured in seconds and nanoseconds since the Epoch. The +file's relevant timestamp shall be set to the greatest value supported +by the file system that is not greater than the specified time. +.P +If the +.IR tv_nsec +field of a +.BR timespec +structure has the special value UTIME_NOW, the file's relevant timestamp +shall be set to the greatest value supported by the file system that is +not greater than the current time. If the +.IR tv_nsec +field has the special value UTIME_OMIT, the file's relevant timestamp +shall not be changed. In either case, the +.IR tv_sec +field shall be ignored. +.P +If the +.IR times +argument is a null pointer, both the access and modification timestamps +shall be set to the greatest value supported by the file system that is +not greater than the current time. If +\fIutimensat\fR() +is passed a relative path in the +.IR path +argument, the file to be used shall be relative to the directory +associated with the file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +If +\fIutimensat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used. +.P +Only a process with the effective user ID equal to the user ID of the +file, or with write access to the file, or with appropriate privileges +may use +\fIfutimens\fR() +or +\fIutimensat\fR() +with a null pointer as the +.IR times +argument or with both +.IR tv_nsec +fields set to the special value UTIME_NOW. Only a process with the +effective user ID equal to the user ID of the file or with appropriate +privileges may use +\fIfutimens\fR() +or +\fIutimensat\fR() +with a non-null +.IR times +argument that does not have both +.IR tv_nsec +fields set to UTIME_NOW and does not have both +.IR tv_nsec +fields set to UTIME_OMIT. If both +.IR tv_nsec +fields are set to UTIME_OMIT, no ownership or permissions check shall be +performed for the file, but other error conditions may still be detected +(including +.BR [EACCES] +errors related to the path prefix). +.P +Values for the +.IR flag +argument of +\fIutimensat\fR() +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, then the access and modification times +of the symbolic link are changed. +.br +.P +Upon completion, +\fIfutimens\fR() +and +\fIutimensat\fR() +shall mark the last file status change timestamp for update. +.P +The +\fIutimes\fR() +function shall be equivalent to the +\fIutimensat\fR() +function with the special value AT_FDCWD as the +.IR fd +argument and the +.IR flag +argument set to zero, except that the +.IR times +argument is a +.BR timeval +structure rather than a +.BR timespec +structure, and accuracy is only to the microsecond, not nanosecond, +and rounding towards the nearest second may occur. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, the file times shall +not be affected. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +The +.IR times +argument is a null pointer, or both +.IR tv_nsec +values are UTIME_NOW, and the effective user ID of the process +does not match the owner of the file and write access is denied. +.TP +.BR EINVAL +Either of the +.IR times +argument structures specified a +.IR tv_nsec +value that was neither UTIME_NOW nor UTIME_OMIT, and was a value less +than zero or greater than or equal to 1\|000 million. +.TP +.BR EINVAL +A new file timestamp would be a value whose +.IR tv_sec +component is not a value supported by the file system. +.TP +.BR EPERM +The +.IR times +argument is not a null pointer, does not have both +.IR tv_nsec +fields set to UTIME_NOW, does not have both +.IR tv_nsec +fields set to UTIME_OMIT, the calling process' effective user ID does +not match the owner of the file, and the calling process does not have +appropriate privileges. +.TP +.BR EROFS +The file system containing the file is read-only. +.P +The +\fIfutimens\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor. +.P +The +\fIutimensat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +The +\fIutimensat\fR() +and +\fIutimes\fR() +functions shall fail if: +.TP +.BR EACCES +Search permission is denied by a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.P +The +\fIutimensat\fR() +and +\fIutimes\fR() +functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.P +The +\fIutimensat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The purpose of the +\fIutimensat\fR() +function is to set the access and modification time of files in +directories other than the current working directory without exposure +to race conditions. Any part of the path of a file could be changed in +parallel to a call to +\fIutimes\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIutimensat\fR() +function it can be guaranteed that the changed file is located relative +to the desired directory. +.P +The standard developers considered including a special case for the +permissions required by +\fIutimensat\fR() +when one +.IR tv_nsec +field is UTIME_NOW and the other is UTIME_OMIT. One possibility would +be to include this case in with the cases where +.IR times +is a null pointer or both fields are UTIME_NOW, where the call is allowed +if the process has write permission for the file. However, associating +write permission with an update to just the last data access timestamp +(which is normally updated by +\fIread\fR()) +did not seem appropriate. The other possibility would be to specify that +this one case is allowed if the process has read permission, but this +was felt to be too great a departure from the +\fIutime\fR() +and +\fIutimes\fR() +functions on which +\fIutimensat\fR() +is based. If an application needs to set the last data access timestamp +to the current time for a file on which it has read permission but is not +the owner, it can do so by opening the file, reading one or more bytes +(or reading a directory entry, if the file is a directory), and then +closing it. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIread\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fwide.3p b/man-pages-posix-2013-a/man3p/fwide.3p new file mode 100644 index 0000000..b1527aa --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fwide.3p @@ -0,0 +1,107 @@ +'\" et +.TH FWIDE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fwide +\(em set stream orientation +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fwide(FILE *\fIstream\fP, int \fImode\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfwide\fR() +function shall determine the orientation of the stream pointed to by +.IR stream . +If +.IR mode +is greater than zero, the function first attempts to make the stream +wide-oriented. If +.IR mode +is less than zero, the function first attempts to make the stream +byte-oriented. Otherwise, +.IR mode +is zero and the function does not alter the orientation of the stream. +.P +If the orientation of the stream has already been determined, +\fIfwide\fR() +shall not change it. +.P +The +\fIfwide\fR() +function shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIfwide\fR(), +then check +.IR errno , +and if it is non-zero, assume an error has occurred. +.SH "RETURN VALUE" +The +\fIfwide\fR() +function shall return a value greater than zero if, after the call, the +stream has wide-orientation, a value less than zero if the stream has +byte-orientation, or zero if the stream has no orientation. +.SH ERRORS +The +\fIfwide\fR() +function may fail if: +.TP +.BR EBADF +The +.IR stream +argument is not a valid stream. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +A call to +\fIfwide\fR() +with +.IR mode +set to zero can be used to determine the current orientation of a +stream. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fwprintf.3p b/man-pages-posix-2013-a/man3p/fwprintf.3p new file mode 100644 index 0000000..fb0dc7f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fwprintf.3p @@ -0,0 +1,1040 @@ +'\" et +.TH FWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fwprintf, +swprintf, +wprintf +\(em print formatted wide-character output +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fwprintf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, ...); +int swprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP, + const wchar_t *restrict \fIformat\fP, ...); +int wprintf(const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfwprintf\fR() +function shall place output on the named output +.IR stream . +The +\fIwprintf\fR() +function shall place output on the standard output stream +.IR stdout . +The +\fIswprintf\fR() +function shall place output followed by the null wide character in +consecutive wide characters starting at *\fIws\fP; no more than +.IR n +wide characters shall be written, including a terminating null wide +character, which is always added (unless +.IR n +is zero). +.P +Each of these functions shall convert, format, and print its arguments +under control of the +.IR format +wide-character string. The +.IR format +is composed of zero or more directives: +.IR "ordinary wide-characters" , +which are simply copied to the output stream, and +.IR "conversion specifications" , +each of which results in the fetching of zero or more arguments. The +results are undefined if there are insufficient arguments for the +.IR format . +If the +.IR format +is exhausted while arguments remain, the excess arguments are evaluated +but are otherwise ignored. +.P +Conversions can be applied to the +.IR n th +argument after the +.IR format +in the argument list, rather than to the next unused argument. In this +case, the conversion specifier wide character +.BR % +(see below) is replaced by the +sequence +.BR \(dq%n$\(dq , +where +.IR n +is a decimal integer in the range [1,{NL_ARGMAX}], +giving the position of the argument in the argument list. This feature +provides for the definition of +.IR format +wide-character strings that select arguments in an order appropriate to +specific languages (see the EXAMPLES section). +.P +The +.IR format +can contain either numbered argument specifications (that is, +\fR"%\fIn\fR$"\fR and \fR"*\fIm\fR$"\fR), or unnumbered argument +conversion specifications (that is, +.BR % +and +.BR * ), +but not both. The only exception to this is that +.BR %% +can be mixed with the \fR"%\fIn\fR$"\fR form. The results of mixing +numbered and unnumbered argument specifications in a +.IR format +wide-character string are undefined. When numbered argument +specifications are used, specifying the +.IR N th +argument requires that all the leading arguments, from the first to the +(\fIN\fP\(mi1)th, are specified in the +.IR format +wide-character string. +.P +In +.IR format +wide-character strings containing the \fR"%\fIn\fR$"\fR form of +conversion specification, numbered arguments in the argument list can +be referenced from the +.IR format +wide-character string as many times as required. +.P +In +.IR format +wide-character strings containing the +.BR % +form of conversion specification, each argument in the argument list +shall be used exactly once. +.P +All forms of the +\fIfwprintf\fR() +function allow for the insertion of a locale-dependent radix +character in the output string, output as a wide-character value. The +radix character is defined in the current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.br +.P +Each conversion specification is introduced by the +.BR '%' +wide character +or by the wide-character sequence \fR"%\fIn\fR$"\fR, +after which the following appear in sequence: +.IP " *" 4 +Zero or more +.IR flags +(in any order), which modify the meaning of the conversion +specification. +.IP " *" 4 +An optional minimum +.IR "field width" . +If the converted value has fewer wide characters than the field width, +it shall be padded with + +characters by default on the left; it shall be padded on the right, +if the left-adjustment flag (\c +.BR '\(mi' ), +described below, is given to the field width. The field width takes the +form of an + +(\c +.BR '*' ), +described below, or a decimal integer. +.IP " *" 4 +An optional +.IR precision +that gives the minimum number of digits to appear for the +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversion specifiers; the number of digits to appear after the radix +character for the +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +and +.BR F +conversion specifiers; the maximum number of significant digits for the +.BR g +and +.BR G +conversion specifiers; or the maximum number of wide characters to be +printed from a string in the +.BR s +conversion specifiers. The precision takes the form of a + +(\c +.BR '.' ) +followed either by an + +(\c +.BR '*' ), +described below, or an optional decimal digit string, where a null +digit string is treated as 0. If a precision appears with any other +conversion wide character, the behavior is undefined. +.IP " *" 4 +An optional length modifier that specifies the size of the argument. +.IP " *" 4 +A +.IR "conversion specifier" +wide character that indicates the type of conversion to be applied. +.P +A field width, or precision, or both, may be indicated by an + +(\c +.BR '*' ). +In this case an argument of type +.BR int +supplies the field width or precision. Applications shall ensure that +arguments specifying field width, or precision, or both appear in that +order before the argument, if any, to be converted. A negative field +width is taken as a +.BR '\(mi' +flag followed by a positive field width. A negative precision is taken +as if the precision were omitted. +In +.IR format +wide-character strings containing the \fR"%\fIn\fR$"\fR form +of a conversion specification, a field width or precision may be +indicated by the sequence \fR"*\fIm\fR$"\fR, where +.IR m +is a decimal integer in the range [1,{NL_ARGMAX}] giving the position +in the argument list (after the +.IR format +argument) of an integer argument containing the field width or +precision, for example: +.sp +.RS 4 +.nf +\fB +wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); \*? +.fi \fR +.P +.RE +.P +The flag wide characters and their meanings are: +.IP "\fR'\fR" 8 +(The +.) +The integer portion of the result of a decimal conversion (\c +.BR %i , +.BR %d , +.BR %u , +.BR %f , +.BR %F , +.BR %g , +or +.BR %G ) +shall be formatted with thousands' grouping wide characters. For other +conversions, the behavior is undefined. The numeric grouping wide +character is used. +.IP "\fR\(mi\fR" 8 +The result of the conversion shall be left-justified within the field. +The conversion shall be right-justified if this flag is not specified. +.IP "\fR+\fR" 8 +The result of a signed conversion shall always begin with a sign (\c +.BR '+' +or +.BR '\(mi' ). +The conversion shall begin with a sign only when a negative value is +converted if this flag is not specified. +.IP 8 +If the first wide character of a signed conversion is not a sign, or if +a signed conversion results in no wide characters, a + +shall be prefixed to the result. This means that if the + +and +.BR '+' +flags both appear, the + +flag shall be ignored. +.IP "\fR#\fR" 8 +Specifies that the value is to be converted to an alternative form. +For +.BR o +conversion, it increases the precision (if necessary) to force the +first digit of the result to be 0. For +.BR x +or +.BR X +conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed +to it. For +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, the result shall always contain a radix +character, even if no digits follow it. Without this flag, a radix +character appears in the result of these conversions only if a digit +follows it. For +.BR g +and +.BR G +conversion specifiers, trailing zeros shall +.IR not +be removed from the result as they normally are. For other conversion +specifiers, the behavior is undefined. +.IP "\fR0\fR" 8 +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, leading zeros (following any indication of sign +or base) are used to pad to the field width rather than performing +space padding, except when converting an infinity or NaN. If the +.BR '0' +and +.BR '\(mi' +flags both appear, the +.BR '0' +flag shall be ignored. For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversion specifiers, if a precision is specified, the +.BR '0' +flag shall be ignored. +If the +.BR '0' +and + +flags both appear, the grouping wide characters are inserted before +zero padding. For other conversions, the behavior is undefined. +.P +The length modifiers and their meanings are: +.IP "\fRhh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "signed char" +or +.BR "unsigned char" +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to +.BR "signed char" +or +.BR "unsigned char" +before printing); or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "signed char" +argument. +.IP "\fRh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "short" +or +.BR "unsigned short" +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to +.BR "short" +or +.BR "unsigned short" +before printing); or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "short" +argument. +.IP "\fRl\fR\ (ell)" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "long" +or +.BR "unsigned long" +argument; that a following +.BR n +conversion specifier applies to a pointer to a +.BR "long" +argument; that a following +.BR c +conversion specifier applies to a +.BR wint_t +argument; that a following +.BR s +conversion specifier applies to a pointer to a +.BR wchar_t +argument; or has no effect on a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier. +.IP "\fRll\fR\ (ell-ell)" 8 +.br +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "long long" +or +.BR "unsigned long long" +argument; or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "long long" +argument. +.IP "\fRj\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to an +.BR intmax_t +or +.BR uintmax_t +argument; or that a following +.BR n +conversion specifier applies to a pointer to an +.BR intmax_t +argument. +.IP "\fRz\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR size_t +or the corresponding signed integer type argument; or that a following +.BR n +conversion specifier applies to a pointer to a signed integer type +corresponding to a +.BR size_t +argument. +.IP "\fRt\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR ptrdiff_t +or the corresponding +.BR unsigned +type argument; or that a following +.BR n +conversion specifier applies to a pointer to a +.BR ptrdiff_t +argument. +.IP "\fRL\fR" 8 +Specifies that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to a +.BR "long double" +argument. +.br +.P +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.P +The conversion specifiers and their meanings are: +.IP "\fRd\fR,\ \fRi\fR" 8 +The +.BR int +argument shall be converted to a signed decimal in the style +\fR"[\(mi]\fIdddd"\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in +fewer digits, it shall be expanded with leading zeros. The default +precision shall be 1. The result of converting zero with an explicit +precision of zero shall be no wide characters. +.IP "\fRo\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned octal format in the style +.BR \(dqdddd\(dq . +The precision specifies the minimum number of digits to appear; if the +value being converted can be represented in fewer digits, it shall be +expanded with leading zeros. The default precision shall be 1. The +result of converting zero with an explicit precision of zero shall be +no wide characters. +.IP "\fRu\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned decimal format in the style +.BR \(dqdddd\(dq . +The precision specifies the minimum number of digits to appear; if the +value being converted can be represented in fewer digits, it shall be +expanded with leading zeros. The default precision shall be 1. The +result of converting zero with an explicit precision of zero shall be +no wide characters. +.IP "\fRx\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned hexadecimal format in the style +.BR \(dqdddd\(dq ; +the letters +.BR \(dqabcdef\(dq +are used. The precision specifies the minimum number of digits to +appear; if the value being converted can be represented in fewer +digits, it shall be expanded with leading zeros. The default precision +shall be 1. The result of converting zero with an explicit precision of +zero shall be no wide characters. +.IP "\fRX\fP" 8 +Equivalent to the +.BR x +conversion specifier, except that letters +.BR \(dqABCDEF\(dq +are used instead of +.BR \(dqabcdef\(dq . +.IP "\fRf\fR,\ \fRF\fR" 8 +The +.BR double +argument shall be converted to decimal notation in the style +\fR"[\(mi]\fIddd.ddd"\fR, where the number of digits after the radix +character shall be equal to the precision specification. If the +precision is missing, it shall be taken as 6; if the precision is +explicitly zero and no +.BR '#' +flag is present, no radix character shall appear. If a radix character +appears, at least one digit shall appear before it. The value shall be +rounded in an implementation-defined manner to the appropriate number +of digits. +.RS 8 +.P +A +.BR double +argument representing an infinity shall be converted in one of the +styles +.BR \(dq[\(mi]inf\(dq +or +.BR \(dq[\(mi]infinity\(dq ; +which style is implementation-defined. A +.BR double +argument representing a NaN shall be converted in one of the styles +.BR \(dq[\(mi]nan\(dq +or \fR"[\(mi]nan(\fIn-char-sequence\fR)"\fR; which style, and the +meaning of any \fIn-char-sequence\fR, is implementation-defined. The +.BR F +conversion specifier produces +.BR \(dqINF\(dq , +.BR \(dqINFINITY\(dq , +or +.BR \(dqNAN\(dq +instead of +.BR \(dqinf\(dq , +.BR \(dqinfinity\(dq , +or +.BR \(dqnan\(dq , +respectively. +.RE +.IP "\fRe\fR,\ \fRE\fR" 8 +The +.BR double +argument shall be converted in the style +\fR"[\(mi]\fId.ddd\fRe\fR\(+-dd"\fR, where there shall be one digit +before the radix character (which is non-zero if the argument is +non-zero) and the number of digits after it shall be equal to the +precision; if the precision is missing, it shall be taken as 6; if the +precision is zero and no +.BR '#' +flag is present, no radix character shall appear. The value shall be +rounded in an implementation-defined manner to the appropriate number +of digits. The +.BR E +conversion wide character shall produce a number with +.BR 'E' +instead of +.BR 'e' +introducing the exponent. The exponent shall always contain at least +two digits. If the value is zero, the exponent shall be zero. +.RS 8 +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRg\fR,\ \fRG\fR" 8 +The +.BR double +argument representing a floating-point number shall be converted in the +style +.BR f +or +.BR e +(or in the style +.BR F +or +.BR E +in the case of a +.BR G +conversion specifier), depending on the value converted and the precision. +Let +.BR P +equal the precision if non-zero, 6 if the precision is omitted, or 1 if the +precision is zero. Then, if a conversion with style +.BR E +would have an exponent of +.IR X : +.RS 8 +.IP -- 4 +If +.BR P >\c +.IR X \(>=\(mi4, +the conversion shall be with style +.BR f +(or +.BR F ) +and precision +.BR P \(mi(\c +.IR X +1). +.IP -- 4 +Otherwise, the conversion shall be with style +.BR e +(or +.BR E ) +and precision +.BR P \(mi1. +.P +Finally, unless the +.BR '#' +flag is used, any trailing zeros shall be removed from the fractional +portion of the result and the decimal-point character shall be removed +if there is no fractional portion remaining. +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRa\fR,\ \fRA\fR" 8 +A +.BR double +argument representing a floating-point number shall be converted in +the style \fR"[\(mi]0x\fIh\fR.\fIhhhh\fRp\(+-\fId\fR"\fR, where there +shall be one hexadecimal digit (which is non-zero if the argument is a +normalized floating-point number and is otherwise unspecified) before +the decimal-point wide character and the number of hexadecimal digits +after it shall be equal to the precision; if the precision is missing +and FLT_RADIX is a power of 2, then the precision shall be sufficient +for an exact representation of the value; if the precision is missing +and FLT_RADIX is not a power of 2, then the precision shall be sufficient +to distinguish values of type +.BR double , +except that trailing zeros may be omitted; if the precision is zero and +the +.BR '#' +flag is not specified, no decimal-point wide character shall appear. +The letters +.BR \(dqabcdef\(dq +are used for +.BR a +conversion and the letters +.BR \(dqABCDEF\(dq +for +.BR A +conversion. The +.BR A +conversion specifier produces a number with +.BR 'X' +and +.BR 'P' +instead of +.BR 'x' +and +.BR 'p' . +The exponent shall always contain at least one digit, and only as many +more digits as necessary to represent the decimal exponent of 2. If the +value is zero, the exponent shall be zero. +.RS 8 +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRc\fP" 8 +If no +.BR l +(ell) qualifier is present, the +.BR int +argument shall be converted to a wide character as if by calling the +\fIbtowc\fR() +function and the resulting wide character shall be written. Otherwise, +the +.BR wint_t +argument shall be converted to +.BR wchar_t , +and written. +.IP "\fRs\fP" 8 +If no +.BR l +(ell) qualifier is present, the application shall ensure that the +argument is a pointer to a character array containing a character +sequence beginning in the initial shift state. Characters from the +array shall be converted as if by repeated calls to the +\fImbrtowc\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first character is converted, and +written up to (but not including) the terminating null wide character. +If the precision is specified, no more than that many wide characters +shall be written. If the precision is not specified, or is greater than +the size of the array, the application shall ensure that the array +contains a null wide character. +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the application shall ensure that the +argument is a pointer to an array of type +.BR wchar_t . +Wide characters from the array shall be written up to (but not +including) a terminating null wide character. If no precision is +specified, or is greater than the size of the array, the application +shall ensure that the array contains a null wide character. If a +precision is specified, no more than that many wide characters shall be +written. +.RE +.IP "\fRp\fP" 8 +The application shall ensure that the argument is a pointer to +.BR void . +The value of the pointer shall be converted to a sequence of printable +wide characters in an implementation-defined manner. +.IP "\fRn\fP" 8 +The application shall ensure that the argument is a pointer to an +integer into which is written the number of wide characters written to +the output so far by this call to one of the +\fIfwprintf\fR() +functions. No argument shall be converted, but one shall be consumed. +If the conversion specification includes any flags, a field width, or a +precision, the behavior is undefined. +.IP "\fRC\fP" 8 +Equivalent to +.BR lc . +.IP "\fRS\fP" 8 +Equivalent to +.BR ls . +.IP "\fR%\fR" 8 +Output a +.BR '%' +wide character; no argument shall be converted. The entire conversion +specification shall be +.BR %% . +.P +If a conversion specification does not match one of the above forms, +the behavior is undefined. +.P +In no case does a nonexistent or small field width cause truncation of +a field; if the result of a conversion is wider than the field width, +the field shall be expanded to contain the conversion result. +Characters generated by +\fIfwprintf\fR() +and +\fIwprintf\fR() +shall be printed as if +\fIfputwc\fR() +had been called. +.P +For +.BR a +and +.BR A +conversions, if FLT_RADIX is not a power of 2 and the result is not +exactly representable in the given precision, the result should be one +of the two adjacent numbers in hexadecimal floating style with the +given precision, with the extra stipulation that the error should have +a correct sign for the current rounding direction. +.P +For +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, if the number of significant decimal digits is +at most DECIMAL_DIG, then the result should be correctly rounded. If +the number of significant decimal digits is more than DECIMAL_DIG but +the source value is exactly representable with DECIMAL_DIG digits, then +the result should be an exact representation with trailing zeros. +Otherwise, the source value is bounded by two adjacent decimal strings +.IR L +< +.IR U , +both having DECIMAL_DIG significant digits; the value of the resultant +decimal string +.IR D +should satisfy +.IR L +<= +.IR D +<= +.IR U , +with the extra stipulation that the error should have a correct sign +for the current rounding direction. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the call to a +successful execution of +\fIfwprintf\fR() +or +\fIwprintf\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream, or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the number of +wide characters transmitted, excluding the terminating null wide character +in the case of +\fIswprintf\fR(), +or a negative value if an output error was encountered, +and set +.IR errno +to indicate the error. +.P +If +.IR n +or more wide characters were requested to be written, +\fIswprintf\fR() +shall return a negative value, +and set +.IR errno +to indicate the error. +.SH ERRORS +For the conditions under which +\fIfwprintf\fR() +and +\fIwprintf\fR() +fail and may fail, refer to +.IR "\fIfputwc\fR\^(\|)". +.P +In addition, all forms of +\fIfwprintf\fR() +shall fail if: +.TP +.BR EILSEQ +A wide-character code that does not correspond to a valid character has +been detected. +.br +.P +In addition, all forms of +\fIfwprintf\fR() +may fail if: +.TP +.BR EINVAL +There are insufficient arguments. +.br +.P +In addition, +\fIfwprintf\fR() +and +\fIwprintf\fR() +may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.P +The +\fIswprintf\fR() +shall fail if: +.TP +.BR EOVERFLOW +The value of +.IR n +is greater than +{INT_MAX} +or the number of bytes needed to hold the output excluding the +terminating null is greater than +{INT_MAX}. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +To print the language-independent date and time format, the following +statement could be used: +.sp +.RS 4 +.nf +\fB +wprintf(format, weekday, month, day, hour, min); +.fi \fR +.P +.RE +.P +For American usage, +.IR format +could be a pointer to the wide-character string: +.sp +.RS 4 +.nf +\fB +L"%s, %s %d, %d:%.2d\en" +.fi \fR +.P +.RE +.P +producing the message: +.sp +.RS 4 +.nf +\fB +Sunday, July 3, 10:02 +.fi \fR +.P +.RE +.P +whereas for German usage, +.IR format +could be a pointer to the wide-character string: +.sp +.RS 4 +.nf +\fB +L"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi \fR +.P +.RE +.P +producing the message: +.sp +.RS 4 +.nf +\fB +Sonntag, 3. Juli, 10:02 +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIbtowc\fR\^(\|)", +.IR "\fIfputwc\fR\^(\|)", +.IR "\fIfwscanf\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fwrite.3p b/man-pages-posix-2013-a/man3p/fwrite.3p new file mode 100644 index 0000000..5a9a12e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fwrite.3p @@ -0,0 +1,121 @@ +'\" et +.TH FWRITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fwrite +\(em binary output +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t fwrite(const void *restrict \fIptr\fP, size_t \fIsize\fP, size_t \fInitems\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfwrite\fR() +function shall write, from the array pointed to by +.IR ptr , +up to +.IR nitems +elements whose size is specified by +.IR size , +to the stream pointed to by +.IR stream . +For each object, +.IR size +calls shall be made to the +\fIfputc\fR() +function, taking the values (in order) from an array of +.BR "unsigned char" +exactly overlaying the object. The file-position indicator for the +stream (if defined) shall be advanced by the number of bytes +successfully written. If an error occurs, the resulting value of the +file-position indicator for the stream is unspecified. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfwrite\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream, or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +The +\fIfwrite\fR() +function shall return the number of elements successfully written, +which may be less than +.IR nitems +if a write error is encountered. If +.IR size +or +.IR nitems +is 0, +\fIfwrite\fR() +shall return 0 and the state of the stream remains unchanged. Otherwise, +if a write error occurs, the error indicator for the stream shall be set, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Because of possible differences in element length and byte ordering, +files written using +\fIfwrite\fR() +are application-dependent, and possibly cannot be read using +\fIfread\fR() +by a different application or by the same application on a different +processor. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputs\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/fwscanf.3p b/man-pages-posix-2013-a/man3p/fwscanf.3p new file mode 100644 index 0000000..a9fcd3b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/fwscanf.3p @@ -0,0 +1,862 @@ +'\" et +.TH FWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fwscanf, +swscanf, +wscanf +\(em convert formatted wide-character input +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fwscanf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, ...); +int swscanf(const wchar_t *restrict \fIws\fP, + const wchar_t *restrict \fIformat\fP, ...); +int wscanf(const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIfwscanf\fR() +function shall read from the named input +.IR stream . +The +\fIwscanf\fR() +function shall read from the standard input stream +.IR stdin . +The +\fIswscanf\fR() +function shall read from the wide-character string +.IR ws . +Each function reads wide characters, interprets them according to a +format, and stores the results in its arguments. Each expects, as +arguments, a control wide-character string +.IR format +described below, and a set of +.IR pointer +arguments indicating where the converted input should be stored. The +result is undefined if there are insufficient arguments for the +format. If the +.IR format +is exhausted while arguments remain, the excess arguments are +evaluated but are otherwise ignored. +.P +Conversions can be applied to the +.IR n th +argument after the +.IR format +in the argument list, rather than to the next unused argument. In this +case, the conversion specifier wide character +.BR % +(see below) is replaced by the sequence +.BR \(dq%n$\(dq , +where +.IR n +is a decimal integer in the range [1,{NL_ARGMAX}]. +This feature provides for the definition of +.IR format +wide-character strings that select arguments in an order appropriate +to specific languages. In +.IR format +wide-character strings containing the \fR"%\fIn\fR$"\fR form of +conversion specifications, +it is unspecified whether numbered arguments in the argument list can +be referenced from the +.IR format +wide-character string more than once. +.P +The +.IR format +can contain either form of a conversion specification\(emthat is, +.BR % +or \fR"%\fIn\fR$"\fR\(em but the two forms cannot normally be mixed +within a single +.IR format +wide-character string. The only exception to this is that +.BR %% +or +.BR %* +can be mixed with the \fR"%\fIn\fR$"\fR form. When numbered argument +specifications are used, specifying the +.IR N th +argument requires that all the leading arguments, from the first to +the (\c +.IR N \(mi1)th, +are pointers. +.P +The +\fIfwscanf\fR() +function in all its forms allows for detection of a language-dependent +radix character in the input string, encoded as a wide-character +value. The radix character is defined in the current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +The +.IR format +is a wide-character string composed of zero or more directives. Each +directive is composed of one of the following: +one or more white-space wide characters (\c +, +, +, +, +or +); +an ordinary wide character (neither +.BR '%' +nor a white-space character); or a conversion specification. +.P +Each conversion specification is introduced by the +.BR '%' +or by the character sequence \fR"%\fIn\fR$"\fR, +after which the following appear in sequence: +.IP " *" 4 +An optional assignment-suppressing character +.BR '*' . +.IP " *" 4 +An optional non-zero decimal integer that specifies the maximum field +width. +.IP " *" 4 +An optional assignment-allocation character +.BR 'm' . +.IP " *" 4 +An optional length modifier that specifies the size of the receiving +object. +.IP " *" 4 +A conversion specifier wide character that specifies the type of +conversion to be applied. The valid conversion specifiers are described +below. +.P +The +\fIfwscanf\fR() +functions shall execute each directive of the format in turn. If a +directive fails, as detailed below, the function shall return. Failures +are described as input failures (due to the unavailability of input +bytes) or matching failures (due to inappropriate input). +.P +A directive composed of one or more white-space wide characters is +executed by reading input until no more valid input can be read, or up +to the first wide character which is not a white-space wide character, +which remains unread. +.P +A directive that is an ordinary wide character shall be executed as +follows. The next wide character is read from the input and compared +with the wide character that comprises the directive; if the comparison +shows that they are not equivalent, the directive shall fail, and the +differing and subsequent wide characters remain unread. Similarly, if +end-of-file, an encoding error, or a read error prevents a wide +character from being read, the directive shall fail. +.P +A directive that is a conversion specification defines a set of +matching input sequences, as described below for each conversion wide +character. A conversion specification is executed in the following +steps. +.P +Input white-space wide characters (as specified by +.IR "\fIiswspace\fR\^(\|)") +shall be skipped, unless the conversion specification includes a +.BR [ , +.BR c , +or +.BR n +conversion specifier. +.P +An item shall be read from the input, unless the conversion +specification includes an +.BR n +conversion specifier wide character. An input item is defined as the +longest sequence of input wide characters, not exceeding any specified +field width, which is an initial subsequence of a matching sequence. +The first wide character, if any, after the input item shall remain +unread. If the length of the input item is zero, the execution of the +conversion specification shall fail; this condition is a matching +failure, unless end-of-file, an encoding error, or a read error +prevented input from the stream, in which case it is an input failure. +.P +Except in the case of a +.BR % +conversion specifier, the input item (or, in the case of a +.BR %n +conversion specification, the count of input wide characters) shall be +converted to a type appropriate to the conversion wide character. If +the input item is not a matching sequence, the execution of the +conversion specification shall fail; this condition is a matching +failure. Unless assignment suppression was indicated by a +.BR '*' , +the result of the conversion shall be placed in the object pointed to +by the first argument following the +.IR format +argument that has not already received a conversion result if the +conversion specification is introduced by +.BR % , +or in the +.IR n th +argument if introduced by the wide-character sequence +\fR"%\fIn\fR$"\fR. +If this object does not have an appropriate type, or if the result +of the conversion cannot be represented in the space provided, the +behavior is undefined. +.P +The +.BR %c , +.BR %s , +and +.BR %[ +conversion specifiers shall accept an optional assignment-allocation +character +.BR 'm' , +which shall cause a memory buffer to be allocated to hold the +wide-character string converted including a terminating null wide +character. In such a case, the argument corresponding to the conversion +specifier should be a reference to a pointer value that will receive a +pointer to the allocated buffer. The system shall allocate a buffer as if +\fImalloc\fR() +had been called. The application shall be responsible for freeing the +memory after usage. If there is insufficient memory to allocate a buffer, +the function shall set +.IR errno +to +.BR [ENOMEM] +and a conversion error shall result. If the function returns EOF, any +memory successfully allocated for parameters using assignment-allocation +character +.BR 'm' +by this call shall be freed before the function returns. +.br +.P +The length modifiers and their meanings are: +.IP "\fRhh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "signed char" +or +.BR "unsigned char" . +.IP "\fRh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "short" +or +.BR "unsigned short" . +.IP "\fRl\fR\ (ell)" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "long" +or +.BR "unsigned long" ; +that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to an argument with type pointer to +.BR double ; +or that a following +.BR c , +.BR s , +or +.BR [ +conversion specifier applies to an argument with type pointer to +.BR wchar_t . +If the +.BR 'm' +assignment-allocation character is specified, the conversion applies +to an argument with the type pointer to a pointer to +.BR wchar_t . +.IP "\fRll\fR\ (ell-ell)" 8 +.br +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "long long" +or +.BR "unsigned long long" . +.IP "\fRj\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR intmax_t +or +.BR uintmax_t . +.IP "\fRz\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR size_t +or the corresponding signed integer type. +.IP "\fRt\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR ptrdiff_t +or the corresponding +.BR unsigned +type. +.IP "\fRL\fR" 8 +Specifies that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to an argument with type pointer to +.BR "long double" . +.P +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.P +The following conversion specifier wide characters are valid: +.IP "\fRd\fP" 8 +Matches an optionally signed decimal integer, whose format is the same +as expected for the subject sequence of +\fIwcstol\fR() +with the value 10 for the +.IR base +argument. In the absence of a size modifier, the application shall ensure +that the corresponding argument is a pointer to +.BR int . +.IP "\fRi\fP" 8 +Matches an optionally signed integer, whose format is the same as +expected for the subject sequence of +\fIwcstol\fR() +with 0 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR int . +.IP "\fRo\fP" 8 +Matches an optionally signed octal integer, whose format is the same as +expected for the subject sequence of +\fIwcstoul\fR() +with the value 8 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRu\fP" 8 +Matches an optionally signed decimal integer, whose format is the same +as expected for the subject sequence of +\fIwcstoul\fR() +with the value 10 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRx\fP" 8 +Matches an optionally signed hexadecimal integer, whose format is the +same as expected for the subject sequence of +\fIwcstoul\fR() +with the value 16 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRa\fR,\ \fRe\fP,\ \fRf\fP,\ \fRg\fP" 8 +.br +Matches an optionally signed floating-point number, infinity, or NaN +whose format is the same as expected for the subject sequence of +\fIwcstod\fR(). +In the absence of a size modifier, the application shall ensure that +the corresponding argument is a pointer to +.BR float . +.RS 8 +.P +If the +\fIfwprintf\fR() +family of functions generates character string representations for +infinity and NaN (a symbolic entity encoded in floating-point +format) to support IEEE\ Std\ 754\(hy1985, the +\fIfwscanf\fR() +family of functions shall recognize them as input. +.RE +.IP "\fRs\fP" 8 +Matches a sequence of non-white-space wide characters. If no +.BR l +(ell) qualifier is present, characters from the input field shall be +converted as if by repeated calls to the +\fIwcrtomb\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first wide character is +converted. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to a character array +large enough to accept the sequence and the terminating null character, +which shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.RS 8 +.P +If the +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the sequence and the terminating null wide +character, which shall be added automatically. +If the +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is present, the application shall +ensure that the corresponding argument is a pointer to a pointer +to a +.BR wchar_t . +.RE +.IP "\fR[\fR" 8 +Matches a non-empty sequence of wide characters from a set of expected +wide characters (the +.IR scanset ). +If no +.BR l +(ell) qualifier is present, wide characters from the input field shall +be converted as if by repeated calls to the +\fIwcrtomb\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first wide character is +converted. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to a character array +large enough to accept the sequence and the terminating null character, +which shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.RS 8 +.P +If an +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the sequence and the terminating null +wide character. +If an +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is specified, the application shall +ensure that the corresponding argument is a pointer to a pointer +to a +.BR wchar_t . +.P +The conversion specification includes all subsequent wide characters in +the +.IR format +string up to and including the matching + +(\c +.BR ']' ). +The wide characters between the square brackets (the +.IR scanlist ) +comprise the scanset, unless the wide character after the + +is a + +(\c +.BR '^' ), +in which case the scanset contains all wide characters that do not +appear in the scanlist between the + +and the +. +If the conversion specification begins with +.BR \(dq[\|]\(dq +or +.BR \(dq[^]\(dq , +the + +is included in the scanlist and the next + +is the matching + +that ends the conversion specification; otherwise, the first + +is the one that ends the conversion specification. If a +.BR '\(mi' +is in the scanlist and is not the first wide character, nor the second +where the first wide character is a +.BR '^' , +nor the last wide character, the behavior is implementation-defined. +.RE +.IP "\fRc\fP" 8 +Matches a sequence of wide characters of exactly the number specified +by the field width (1 if no field width is present in the conversion +specification). +.RS 8 +.P +If no +.BR l +(ell) length modifier is present, characters from the input field shall +be converted as if by repeated calls to the +\fIwcrtomb\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first wide character is +converted. No null character is added. If the +.BR 'm' +assignment-allocation character is not specified, the application +shall ensure that the corresponding argument is a pointer to the +initial element of a character array large enough to accept the sequence. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR char . +.P +No null wide character is added. If an +.BR l +(ell) length modifier is present and the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument shall be a pointer to the initial +element of an array of +.BR wchar_t +large enough to accept the sequence. +If an +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is specified, the application shall +ensure that the corresponding argument is a pointer to a pointer +to a +.BR wchar_t . +.RE +.IP "\fRp\fP" 8 +Matches an implementation-defined set of sequences, which shall be +the same as the set of sequences that is produced by the +.BR %p +conversion specification of the corresponding +\fIfwprintf\fR() +functions. The application shall ensure that the corresponding argument +is a pointer to a pointer to +.BR void . +The interpretation of the input item is implementation-defined. If +the input item is a value converted earlier during the same program +execution, the pointer that results shall compare equal to that value; +otherwise, the behavior of the +.BR %p +conversion is undefined. +.IP "\fRn\fP" 8 +No input is consumed. The application shall ensure that the +corresponding argument is a pointer to the integer into which is to be +written the number of wide characters read from the input so far by +this call to the +\fIfwscanf\fR() +functions. Execution of a +.BR %n +conversion specification shall not increment the assignment count +returned at the completion of execution of the function. No argument +shall be converted, but one shall be consumed. If the conversion +specification includes an assignment-suppressing wide character or a +field width, the behavior is undefined. +.IP "\fRC\fP" 8 +Equivalent to +.BR lc . +.IP "\fRS\fP" 8 +Equivalent to +.BR ls . +.IP "\fR%\fR" 8 +Matches a single +.BR '%' +wide character; no conversion or assignment shall occur. The complete +conversion specification shall be +.BR %% . +.P +If a conversion specification is invalid, the behavior is undefined. +.P +The conversion specifiers +.BR A , +.BR E , +.BR F , +.BR G , +and +.BR X +are also valid and shall be equivalent to, respectively, +.BR a , +.BR e , +.BR f , +.BR g , +and +.BR x . +.P +If end-of-file is encountered during input, conversion is terminated. +If end-of-file occurs before any wide characters matching the current +conversion specification (except for +.BR %n ) +have been read (other than leading white-space, where permitted), +execution of the current conversion specification shall terminate with +an input failure. Otherwise, unless execution of the current conversion +specification is terminated with a matching failure, execution of the +following conversion specification (if any) shall be terminated with an +input failure. +.P +Reaching the end of the string in +\fIswscanf\fR() +shall be equivalent to encountering end-of-file for +\fIfwscanf\fR(). +.P +If conversion terminates on a conflicting input, the offending input +shall be left unread in the input. Any trailing white space (including +) +shall be left unread unless matched by a conversion specification. The +success of literal matches and suppressed assignments is only directly +determinable via the +.BR %n +conversion specification. +.P +The +\fIfwscanf\fR() +and +\fIwscanf\fR() +functions may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetwc\fR(), +\fIfgetws\fR(), +\fIfwscanf\fR(), +\fIgetwc\fR(), +\fIgetwchar\fR(), +\fIvfwscanf\fR(), +\fIvwscanf\fR(), +or +\fIwscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetwc\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the number of +successfully matched and assigned input items; this number can be zero +in the event of an early matching failure. If the input ends before the +first matching failure or conversion, EOF shall be returned. +If any error occurs, EOF shall be returned, +and +.IR errno +shall be set to indicate the error. +If a read error occurs, the error indicator for the stream shall be set. +.SH ERRORS +For the conditions under which the +\fIfwscanf\fR() +functions shall fail and may fail, refer to +.IR "\fIfgetwc\fR\^(\|)". +.P +In addition, the +\fIfwscanf\fR() +function shall fail if: +.TP +.BR EILSEQ +Input byte sequence does not form a valid character. +.TP +.BR ENOMEM +Insufficient storage space is available. +.P +In addition, the +\fIfwscanf\fR() +function may fail if: +.TP +.BR EINVAL +There are insufficient arguments. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The call: +.sp +.RS 4 +.nf +\fB +int i, n; float x; char name[50]; +n = wscanf(L"%d%f%s", &i, &x, name); +.fi \fR +.P +.RE +.P +with the input line: +.sp +.RS 4 +.nf +\fB +25 54.32E\(mi1 Hamster +.fi \fR +.P +.RE +.P +assigns to +.IR n +the value 3, to +.IR i +the value 25, to +.IR x +the value 5.432, and +.IR name +contains the string +.BR \(dqHamster\(dq . +.P +The call: +.sp +.RS 4 +.nf +\fB +int i; float x; char name[50]; +(void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name); +.fi \fR +.P +.RE +.P +with input: +.sp +.RS 4 +.nf +\fB +56789 0123 56a72 +.fi \fR +.P +.RE +.P +assigns 56 to +.IR i , +789.0 to +.IR x , +skips 0123, and places the string +.BR \(dq56\e0\(dq +in +.IR name . +The next call to +\fIgetchar\fR() +shall return the character +.BR 'a' . +.SH "APPLICATION USAGE" +In format strings containing the +.BR '%' +form of conversion specifications, each argument in the argument +list is used exactly once. +.P +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIfwscanf\fR(), +this is memory allocated via use of the +.BR 'm' +assignment-allocation character. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIgetwc\fR\^(\|)", +.IR "\fIfwprintf\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)", +.IR "\fIwcstoul\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/gai_strerror.3p b/man-pages-posix-2013-a/man3p/gai_strerror.3p new file mode 100644 index 0000000..53c7b0d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/gai_strerror.3p @@ -0,0 +1,96 @@ +'\" et +.TH GAI_STRERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gai_strerror +\(em address and name information error description +.SH SYNOPSIS +.LP +.nf +#include +.P +const char *gai_strerror(int \fIecode\fP); +.fi +.SH DESCRIPTION +The +\fIgai_strerror\fR() +function shall return a text string describing an error value for the +\fIgetaddrinfo\fR() +and +\fIgetnameinfo\fR() +functions listed in the +.IR +header. +.P +When the +.IR ecode +argument is one of the following values listed in the +.IR +header: +.TS +tab(!); +le le. +T{ +.nf +.BR [EAI_AGAIN] +.BR [EAI_BADFLAGS] +.BR [EAI_FAIL] +.BR [EAI_FAMILY] +.BR [EAI_MEMORY] +T}!T{ +.nf +.BR [EAI_NONAME] +.BR [EAI_OVERFLOW] +.BR [EAI_SERVICE] +.BR [EAI_SOCKTYPE] +.BR [EAI_SYSTEM] +.fi +T} +.TE +.P +the function return value shall point to a string describing the error. +If the argument is not one of those values, the function shall return a +pointer to a string whose contents indicate an unknown error. +.SH "RETURN VALUE" +Upon successful completion, +\fIgai_strerror\fR() +shall return a pointer to an implementation-defined string. +.SH "ERRORS" +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfreeaddrinfo\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getaddrinfo.3p b/man-pages-posix-2013-a/man3p/getaddrinfo.3p new file mode 100644 index 0000000..97be9cf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getaddrinfo.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETADDRINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getaddrinfo +\(em get address information +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int getaddrinfo(const char *restrict \fInodename\fP, + const char *restrict \fIservname\fP, + const struct addrinfo *restrict \fIhints\fP, + struct addrinfo **restrict \fIres\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfreeaddrinfo\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getc.3p b/man-pages-posix-2013-a/man3p/getc.3p new file mode 100644 index 0000000..a96e11f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getc.3p @@ -0,0 +1,90 @@ +'\" et +.TH GETC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getc +\(em get a byte from a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int getc(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIgetc\fR() +function shall be equivalent to +.IR "\fIfgetc\fR\^(\|)", +except that if it is implemented as a macro it may evaluate +.IR stream +more than once, so the argument should never be an expression with +side-effects. +.SH "RETURN VALUE" +Refer to +.IR "\fIfgetc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the integer value returned by +\fIgetc\fR() +is stored into a variable of type +.BR char +and then compared against the integer constant EOF, the comparison may +never succeed, because sign-extension of a variable of type +.BR char +on widening to integer is implementation-defined. +.P +Since it may be implemented as a macro, +\fIgetc\fR() +may treat incorrectly a +.IR stream +argument with side-effects. In particular, +.IR getc (* f \(pl\(pl) +does not necessarily work as expected. Therefore, use of this function +should be preceded by +.BR \(dq#undef getc\(dq +in such situations; +\fIfgetc\fR() +could also be used. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getc_unlocked.3p b/man-pages-posix-2013-a/man3p/getc_unlocked.3p new file mode 100644 index 0000000..166c155 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getc_unlocked.3p @@ -0,0 +1,233 @@ +'\" et +.TH GETC_UNLOCKED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getc_unlocked, +getchar_unlocked, +putc_unlocked, +putchar_unlocked +\(em stdio with explicit client locking +.SH SYNOPSIS +.LP +.nf +#include +.P +int getc_unlocked(FILE *\fIstream\fP); +int getchar_unlocked(void); +int putc_unlocked(int \fIc\fP, FILE *\fIstream\fP); +int putchar_unlocked(int \fIc\fP); +.fi +.SH DESCRIPTION +Versions of the functions +\fIgetc\fR(), +\fIgetchar\fR(), +\fIputc\fR(), +and +\fIputchar\fR() +respectively named +\fIgetc_unlocked\fR(), +\fIgetchar_unlocked\fR(), +\fIputc_unlocked\fR(), +and +\fIputchar_unlocked\fR() +shall be provided which are functionally equivalent to the original +versions, with the exception that they are not required to be +implemented in a thread-safe manner. They may only safely be used +within a scope protected by +\fIflockfile\fR() +(or +\fIftrylockfile\fR()) +and +\fIfunlockfile\fR(). +These functions may safely be used in a multi-threaded program if and +only if they are called while the invoking thread owns the (\c +.BR "FILE *" ) +object, as is the case after a successful call to the +\fIflockfile\fR() +or +\fIftrylockfile\fR() +functions. +.P +If +\fIgetc_unlocked\fR() +or +\fIputc_unlocked\fR() +are implemented as macros they may evaluate +.IR stream +more than once, so the +.IR stream +argument should never be an expression with side-effects. +.SH "RETURN VALUE" +See +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +and +.IR "\fIputchar\fR\^(\|)". +.SH ERRORS +See +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +and +.IR "\fIputchar\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since they may be implemented as macros, +\fIgetc_unlocked\fR() +and +\fIputc_unlocked\fR() +may treat incorrectly a +.IR stream +argument with side-effects. In particular, \fIgetc_unlocked\fP(*f++) +and \fIputc_unlocked\fP(c,*f++) do not necessarily work as expected. +Therefore, use of these functions in such situations should be preceded +by the following statement as appropriate: +.sp +.RS 4 +.nf +\fB +#undef getc_unlocked +#undef putc_unlocked +.fi \fR +.P +.RE +.SH RATIONALE +Some I/O functions are typically implemented as macros for performance +reasons (for example, +\fIputc\fR() +and +\fIgetc\fR()). +For safety, they need to be synchronized, but it is often too expensive +to synchronize on every character. Nevertheless, it was felt that the +safety concerns were more important; consequently, the +\fIgetc\fR(), +\fIgetchar\fR(), +\fIputc\fR(), +and +\fIputchar\fR() +functions are required to be thread-safe. However, unlocked versions +are also provided with names that clearly indicate the unsafe nature of +their operation but can be used to exploit their higher performance. +These unlocked versions can be safely used only within explicitly +locked program regions, using exported locking primitives. In +particular, a sequence such as: +.sp +.RS 4 +.nf +\fB +flockfile(fileptr); +putc_unlocked('1', fileptr); +putc_unlocked('\en', fileptr); +fprintf(fileptr, "Line 2\en"); +funlockfile(fileptr); +.fi \fR +.P +.RE +.br +.P +is permissible, and results in the text sequence: +.sp +.RS 4 +.nf +\fB +1 +Line 2 +.fi \fR +.P +.RE +.P +being printed without being interspersed with output from other +threads. +.P +It would be wrong to have the standard names such as +\fIgetc\fR(), +\fIputc\fR(), +and so on, map to the ``faster, but unsafe'' rather than the ``slower, +but safe'' versions. In either case, you would still want to inspect +all uses of +\fIgetc\fR(), +\fIputc\fR(), +and so on, by hand when converting existing code. Choosing the safe +bindings as the default, at least, results in correct code and +maintains the ``atomicity at the function'' invariant. To do otherwise +would introduce gratuitous synchronization errors into converted code. +Other routines that modify the +.IR stdio +(\c +.BR "FILE *" ) +structures or buffers are also safely synchronized. +.P +Note that there is no need for functions of the form +\fIgetc_locked\fR(), +\fIputc_locked\fR(), +and so on, since this is the functionality of +\fIgetc\fR(), +\fIputc\fR(), +.IR "et al" . +It would be inappropriate to use a feature test macro to +switch a macro definition of +\fIgetc\fR() +between +\fIgetc_locked\fR() +and +\fIgetc_unlocked\fR(), +since the ISO\ C standard requires an actual function to exist, +a function whose behavior could not be changed by the +feature test macro. Also, providing both the +\fIxxx_locked\fR() +and +\fIxxx_unlocked\fR() +forms leads to the confusion of whether the suffix describes the +behavior of the function or the circumstances under which it should be +used. +.P +Three additional routines, +\fIflockfile\fR(), +\fIftrylockfile\fR(), +and +\fIfunlockfile\fR() +(which may be macros), are provided to allow the user to delineate a +sequence of I/O statements that are executed synchronously. +.P +The +\fIungetc\fR() +function is infrequently called relative to the other functions/macros +so no unlocked variation is needed. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIflockfile\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputchar\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getchar.3p b/man-pages-posix-2013-a/man3p/getchar.3p new file mode 100644 index 0000000..a6c8ea2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getchar.3p @@ -0,0 +1,74 @@ +'\" et +.TH GETCHAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getchar +\(em get a byte from a +.IR stdin +stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int getchar(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIgetchar\fR() +function shall be equivalent to \fIgetc\fP(\fIstdin\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIfgetc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the integer value returned by +\fIgetchar\fR() +is stored into a variable of type +.BR char +and then compared against the integer constant EOF, the comparison may +never succeed, because sign-extension of a variable of type +.BR char +on widening to integer is implementation-defined. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIgetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getchar_unlocked.3p b/man-pages-posix-2013-a/man3p/getchar_unlocked.3p new file mode 100644 index 0000000..f2d5130 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getchar_unlocked.3p @@ -0,0 +1,38 @@ +'\" et +.TH GETCHAR_UNLOCKED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getchar_unlocked +\(em stdio with explicit client locking +.SH SYNOPSIS +.LP +.nf +#include +.P +int getchar_unlocked(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetc_unlocked\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getcwd.3p b/man-pages-posix-2013-a/man3p/getcwd.3p new file mode 100644 index 0000000..2cf9a50 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getcwd.3p @@ -0,0 +1,292 @@ +'\" et +.TH GETCWD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getcwd +\(em get the pathname of the current working directory +.SH SYNOPSIS +.LP +.nf +#include +.P +char *getcwd(char *\fIbuf\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIgetcwd\fR() +function shall place an absolute pathname of the current working directory +in the array pointed to by +.IR buf , +and return +.IR buf . +The pathname shall contain no components that are dot or dot-dot, or +are symbolic links. +.P +If there are multiple pathnames that +\fIgetcwd\fR() +could place in the array pointed to by +.IR buf , +one beginning with a single + +character and one or more beginning with two + +characters, then +\fIgetcwd\fR() +shall place the pathname beginning with a single + +character in the array. The pathname shall not contain any unnecessary + +characters after the leading one or two + +characters. +.P +The +.IR size +argument is the size in bytes of the character array pointed to by the +.IR buf +argument. If +.IR buf +is a null pointer, the behavior of +\fIgetcwd\fR() +is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetcwd\fR() +shall return the +.IR buf +argument. Otherwise, +\fIgetcwd\fR() +shall return a null pointer and set +.IR errno +to indicate the error. The contents of the array pointed to by +.IR buf +are then undefined. +.SH ERRORS +The +\fIgetcwd\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR size +argument is 0. +.TP +.BR ERANGE +The +.IR size +argument is greater than 0, but is smaller than the length of +the string +1. +.P +The +\fIgetcwd\fR() +function may fail if: +.TP +.BR EACCES +Search permission was denied for the current directory, or read or search +permission was denied for a directory above the current directory in +the file hierarchy. +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example uses +{PATH_MAX} +as the initial buffer size (unless it is indeterminate or very large), +and calls +\fIgetcwd\fR() +with progressively larger buffers until it does not give an +.BR [ERANGE] +error. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +\&... +.P +long path_max; +size_t size; +char *buf; +char *ptr; +.P +path_max = pathconf(".", _PC_PATH_MAX); +if (path_max == -1) + size = 1024; +else if (path_max > 10240) + size = 10240; +else + size = path_max; +.P +for (buf = ptr = NULL; ptr == NULL; size *= 2) +{ + if ((buf = realloc(buf, size)) == NULL) + { + ... handle error ... + } +.P + ptr = getcwd(buf, size); + if (ptr == NULL && errno != ERANGE) + { + ... handle error ... + } +} +\&... +free (buf); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +If the pathname obtained from +\fIgetcwd\fR() +is longer than +{PATH_MAX} +bytes, it could produce an +.BR [ENAMETOOLONG] +error if passed to +\fIchdir\fR(). +Therefore, in order to return to that directory it may be necessary to +break the pathname into sections shorter than +{PATH_MAX} +bytes and call +\fIchdir\fR() +on each section in turn (the first section being an absolute pathname and +subsequent sections being relative pathnames). A simpler way to handle +saving and restoring the working directory when it may be deeper than +{PATH_MAX} +bytes in the file hierarchy is to use a file descriptor and +\fIfchdir\fR(), +rather than +\fIgetcwd\fR() +and +\fIchdir\fR(). +However, the two methods do have some differences. The +\fIfchdir\fR() +approach causes the program to restore a working directory even +if it has been renamed in the meantime, whereas the +\fIchdir\fR() +approach restores to a directory with the same name as the original, +even if the directories were renamed in the meantime. Since the +\fIfchdir\fR() +approach does not access parent directories, it can succeed when +\fIgetcwd\fR() +would fail due to permissions problems. In applications conforming to +earlier versions of this standard, it was not possible to use the +\fIfchdir\fR() +approach when the working directory is searchable but not readable, +as the only way to open a directory was with O_RDONLY, whereas the +\fIgetcwd\fR() +approach can succeed in this case. +.SH RATIONALE +Having +\fIgetcwd\fR() +take no arguments and instead use the +\fImalloc\fR() +function to produce space for the returned argument was considered. +The advantage is that +\fIgetcwd\fR() +knows how big the working directory pathname is and can allocate an +appropriate amount of space. But the programmer would have to use the +\fIfree\fR() +function to free the resulting object, or each use of +\fIgetcwd\fR() +would further reduce the available memory. Finally, +\fIgetcwd\fR() +is taken from the SVID where it has the two arguments used in this volume of POSIX.1\(hy2008. +.P +The older function +.IR getwd (\|) +was rejected for use in this context because it had only a buffer +argument and no +.IR size +argument, and thus had no way to prevent overwriting the buffer, except +to depend on the programmer to provide a large enough buffer. +.P +On some implementations, if +.IR buf +is a null pointer, +\fIgetcwd\fR() +may obtain +.IR size +bytes of memory using +\fImalloc\fR(). +In this case, the pointer returned by +\fIgetcwd\fR() +may be used as the argument in a subsequent call to +\fIfree\fR(). +Invoking +\fIgetcwd\fR() +with +.IR buf +as a null pointer is not recommended in conforming applications. +.P +Earlier implementations of +\fIgetcwd\fR() +sometimes generated pathnames like +.BR \(dq../../../subdirname\(dq +internally, using them to explore the path of ancestor directories back +to the root. If one of these internal pathnames exceeded +{PATH_MAX} +in length, the implementation could fail with +.IR errno +set to +.BR [ENAMETOOLONG] . +This is no longer allowed. +.P +If a program is operating in a directory where some (grand)parent +directory does not permit reading, +\fIgetcwd\fR() +may fail, as in most implementations it must read the directory to +determine the name of the file. This can occur if search, but not read, +permission is granted in an intermediate directory, or if the program +is placed in that directory by some more privileged process (for +example, login). Including the +.BR [EACCES] +error condition makes the reporting of the error consistent and warns +the application developer that +\fIgetcwd\fR() +can fail for reasons beyond the control of the application developer or +user. Some implementations can avoid this occurrence (for example, by +implementing +\fIgetcwd\fR() +using +.IR pwd , +where +.IR pwd +is a set-user-root process), +thus the error was made optional. Since this volume of POSIX.1\(hy2008 permits the addition of +other errors, this would be a common addition and yet one that +applications could not be expected to deal with without this addition. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImalloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getdate.3p b/man-pages-posix-2013-a/man3p/getdate.3p new file mode 100644 index 0000000..698f10b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getdate.3p @@ -0,0 +1,399 @@ +'\" et +.TH GETDATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getdate +\(em convert user format date and time +.SH SYNOPSIS +.LP +.nf +#include +.P +struct tm *getdate(const char *\fIstring\fP); +.fi +.SH DESCRIPTION +The +\fIgetdate\fR() +function shall convert a string representation of a date or time +into a broken-down time. +.P +The external variable or macro +.IR getdate_err , +which has type +.BR int , +is used by +\fIgetdate\fR() +to return error values. It is unspecified whether +.IR getdate_err +is a macro or an identifier declared with external linkage, and whether +or not it is a modifiable lvalue. If a macro definition is suppressed +in order to access an actual object, or a program defines an identifier +with the name +.IR getdate_err , +the behavior is undefined. +.P +Templates are used to parse and interpret the input string. The +templates are contained in a text file identified by the environment +variable +.IR DATEMSK . +The +.IR DATEMSK +variable should be set to indicate the full pathname of the file that +contains the templates. The first line in the template that matches +the input specification is used for interpretation and conversion into +the internal time format. +.P +The following conversion specifications shall be supported: +.IP "\fR%%\fR" 8 +Equivalent to +.BR % . +.IP "\fR%a\fR" 8 +Abbreviated weekday name. +.IP "\fR%A\fR" 8 +Full weekday name. +.IP "\fR%b\fR" 8 +Abbreviated month name. +.IP "\fR%B\fR" 8 +Full month name. +.IP "\fR%c\fR" 8 +Locale's appropriate date and time representation. +.IP "\fR%C\fR" 8 +Century number [00,99]; leading zeros are permitted but not required. +.IP "\fR%d\fR" 8 +Day of month [01,31]; the leading 0 is optional. +.IP "\fR%D\fR" 8 +Date as +.BR %m /\c +.BR %d /\c +.BR %y . +.IP "\fR%e\fR" 8 +Equivalent to +.BR %d . +.IP "\fR%h\fR" 8 +Abbreviated month name. +.IP "\fR%H\fR" 8 +Hour [00,23]. +.IP "\fR%I\fR" 8 +Hour [01,12]. +.IP "\fR%m\fR" 8 +Month number [01,12]. +.IP "\fR%M\fR" 8 +Minute [00,59]. +.IP "\fR%n\fR" 8 +Equivalent to +. +.IP "\fR%p\fR" 8 +Locale's equivalent of either AM or PM. +.IP "\fR%r\fR" 8 +The locale's appropriate representation of time in AM and PM notation. +In the POSIX locale, this shall be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fR%R\fR" 8 +Time as +.BR %H :\c +.BR %M . +.IP "\fR%S\fR" 8 +Seconds [00,60]. The range goes to 60 (rather than stopping at 59) +to allow positive leap seconds to be expressed. Since leap seconds +cannot be predicted by any algorithm, leap second data must come from +some external source. +.IP "\fR%t\fR" 8 +Equivalent to +. +.IP "\fR%T\fR" 8 +Time as +.BR %H :\c +.BR %M :\c +.BR %S . +.IP "\fR%w\fR" 8 +Weekday number (Sunday = [0,6]). +.IP "\fR%x\fR" 8 +Locale's appropriate date representation. +.IP "\fR%X\fR" 8 +Locale's appropriate time representation. +.IP "\fR%y\fR" 8 +Year within century. When a century is not otherwise specified, values +in the range [69,99] shall refer to years 1969 to 1999 inclusive, +and values in the range [00,68] shall refer to years 2000 to 2068 +inclusive. +.RS 8 +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.RE +.IP "\fR%Y\fR" 8 +Year as +.BR \(dqccyy\(dq +(for example, 2001). +.IP "\fR%Z\fR" 8 +Timezone name or no characters if no timezone exists. If the +timezone supplied by +.BR %Z +is not the timezone that +\fIgetdate\fR() +expects, an invalid input specification error shall result. The +\fIgetdate\fR() +function calculates an expected timezone based on information supplied +to the function (such as the hour, day, and month). +.P +The match between the template and input specification performed by +\fIgetdate\fR() +shall be case-insensitive. +.P +The month and weekday names can consist of any combination of upper and +lowercase letters. The process can request that the input date or time +specification be in a specific language by setting the +.IR LC_TIME +category +(see +.IR "\fIsetlocale\fR\^(\|)"). +.P +Leading zeros are not necessary for the descriptors that allow leading +zeros. However, at most two digits are allowed for those descriptors, +including leading zeros. Extra white space in either the template file +or in +.IR string +shall be ignored. +.P +The results are undefined if the conversion specifications +.BR %c , +.BR %x , +and +.BR %X +include unsupported conversion specifications. +.P +The following rules apply for converting the input specification into +the internal format: +.IP " *" 4 +If +.BR %Z +is being scanned, then +\fIgetdate\fR() +shall initialize the broken-down time to be the current time in the +scanned timezone. Otherwise, it shall initialize the broken-down time +based on the current local time as if +\fIlocaltime\fR() +had been called. +.IP " *" 4 +If only the weekday is given, the day chosen shall be the day, starting +with today and moving into the future, which first matches the named +day. +.IP " *" 4 +If only the month (and no year) is given, the month chosen shall be the +month, starting with the current month and moving into the future, +which first matches the named month. The first day of the month shall +be assumed if no day is given. +.IP " *" 4 +If no hour, minute, and second are given, the current hour, minute, and +second shall be assumed. +.IP " *" 4 +If no date is given, the hour chosen shall be the hour, starting with +the current hour and moving into the future, which first matches the +named hour. +.P +If a conversion specification in the DATEMSK file does not correspond +to one of the conversion specifications above, the behavior is +unspecified. +.P +The +\fIgetdate\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetdate\fR() +shall return a pointer to a +.BR "struct tm" . +Otherwise, it shall return a null pointer and set +.IR getdate_err +to indicate the error. +.SH ERRORS +The +\fIgetdate\fR() +function shall fail in the following cases, setting +.IR getdate_err +to the value shown in the list below. Any changes to +.IR errno +are unspecified. +.IP " 1." 4 +The +.IR DATEMSK +environment variable is null or undefined. +.IP " 2." 4 +The template file cannot be opened for reading. +.IP " 3." 4 +Failed to get file status information. +.IP " 4." 4 +The template file is not a regular file. +.IP " 5." 4 +An I/O error is encountered while reading the template file. +.IP " 6." 4 +Memory allocation failed (not enough memory available). +.IP " 7." 4 +There is no line in the template that matches the input. +.IP " 8." 4 +Invalid input specification. For example, February 31; or a time is +specified that cannot be represented in a +.BR time_t +(representing the time in seconds since the Epoch). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.IP " 1." 4 +The following example shows the possible contents of a template: +.RS 4 +.sp +.RS 4 +.nf +\fB +%m +%A %B %d, %Y, %H:%M:%S +%A +%B +%m/%d/%y %I %p +%d,%m,%Y %H:%M +at %A the %dst of %B in %Y +run job at %I %p,%B %dnd +%A den %d. %B %Y %H.%M Uhr +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following are examples of valid input specifications for the +template in Example 1: +.RS 4 +.sp +.RS 4 +.nf +\fB +getdate("10/1/87 4 PM"); +getdate("Friday"); +getdate("Friday September 18, 1987, 10:30:30"); +getdate("24,9,1986 10:30"); +getdate("at monday the 1st of december in 1986"); +getdate("run job at 3 PM, december 2nd"); +.fi \fR +.P +.RE +.P +If the +.IR LC_TIME +category is set to a German locale that includes +.IR freitag +as a weekday name and +.IR oktober +as a month name, the following would be valid: +.sp +.RS 4 +.nf +\fB +getdate("freitag den 10. oktober 1986 10.30 Uhr"); +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +The following example shows how local date and time specification can +be defined in the template: +.TS +box tab(!) center; +cB | cB +lf5 | lf5. +Invocation!Line in Template +_ +getdate("11/27/86")!%m/%d/%y +getdate("27.11.86")!%d.%m.%y +getdate("86-11-27")!%y-%m-%d +getdate("Friday 12:00:00")!%A %H:%M:%S +.TE +.IP " 4." 4 +The following examples help to illustrate the above rules assuming that +the current date is Mon Sep 22 12:19:47 EDT 1986 and the +.IR LC_TIME +category is set to the default C locale: +.TS +box tab(!) center; +cB | cB | cB +lf5 | lf5 | l. +Input!Line in Template!Date +_ +Mon!%a!Mon Sep 22 12:19:47 EDT 1986 +Sun!%a!Sun Sep 28 12:19:47 EDT 1986 +Fri!%a!Fri Sep 26 12:19:47 EDT 1986 +September!%B!Mon Sep 1 12:19:47 EDT 1986 +January!%B!Thu Jan 1 12:19:47 EST 1987 +December!%B!Mon Dec 1 12:19:47 EST 1986 +Sep Mon!%b %a!Mon Sep 1 12:19:47 EDT 1986 +Jan Fri!%b %a!Fri Jan 2 12:19:47 EST 1987 +Dec Mon!%b %a!Mon Dec 1 12:19:47 EST 1986 +Jan Wed 1989!%b %a %Y!Wed Jan 4 12:19:47 EST 1989 +Fri 9!%a %H!Fri Sep 26 09:00:00 EDT 1986 +Feb 10:30!%b %H:%S!Sun Feb 1 10:00:30 EST 1987 +10:30!%H:%M!Tue Sep 23 10:30:00 EDT 1986 +13:30!%H:%M!Mon Sep 22 13:30:00 EDT 1986 +.TE +.SH "APPLICATION USAGE" +Although historical versions of +\fIgetdate\fR() +did not require that +.IR +declare the external variable +.IR getdate_err , +this volume of POSIX.1\(hy2008 does require it. The standard developers encourage applications +to remove declarations of +.IR getdate_err +and instead incorporate the declaration by including +.IR . +.P +Applications should use +.BR %Y +(4-digit years) in preference to +.BR %y +(2-digit years). +.SH RATIONALE +In standard locales, the conversion specifications +.BR %c , +.BR %x , +and +.BR %X +do not include unsupported conversion specifiers and so the text +regarding results being undefined is not a problem in that case. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIctime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fItimes\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getdelim.3p b/man-pages-posix-2013-a/man3p/getdelim.3p new file mode 100644 index 0000000..92e8255 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getdelim.3p @@ -0,0 +1,221 @@ +'\" et +.TH GETDELIM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getdelim, getline +\(em read a delimited record from +.IR stream +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t getdelim(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP, + int \fIdelimiter\fP, FILE *restrict \fIstream\fP); +ssize_t getline(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The +\fIgetdelim\fR() +function shall read from +.IR stream +until it encounters a character matching the +.IR delimiter +character. The +.IR delimiter +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +of equal value that terminates the read process. If the +.IR delimiter +argument has any other value, the behavior is undefined. +.P +The application shall ensure that +.IR *lineptr +is a valid argument that could be passed to the +\fIfree\fR() +function. If +.IR *n +is non-zero, the application shall ensure that +.IR *lineptr +either points to an object of size at least +.IR *n +bytes, or is a null pointer. +.P +The size of the object pointed to by +.IR *lineptr +shall be increased to fit the incoming line, if it isn't already large +enough, including room for the delimiter and a terminating NUL. The +characters read, including any delimiter, shall be stored in the string +pointed to by the +.IR lineptr +argument, and a terminating NUL added when the delimiter or end of file is +encountered. +.P +The +\fIgetline\fR() +function shall be equivalent to the +\fIgetdelim\fR() +function with the +.IR delimiter +character equal to the + +character. +.P +The +\fIgetdelim\fR() +and +\fIgetline\fR() +functions may mark the last data access timestamp of the file associated +with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fIgetline\fR() +and +\fIgetdelim\fR() +functions shall return the number of characters written into the buffer, +including the delimiter character if one was encountered before EOF, +but excluding the terminating NUL character. If no characters were read, +and the end-of-file indicator for the stream is set, or if the stream is +at end-of-file, the end-of-file indicator for the stream shall be set and +the function shall return \(mi1. If an error occurs, the error indicator +for the stream shall be set, and the function shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +For the conditions under which the +\fIgetdelim\fR() +and +\fIgetline\fR() +functions shall fail and may fail, refer to +.IR "\fIfgetc\fR\^(\|)". +.P +In addition, these functions shall fail if: +.TP +.BR EINVAL +.IR lineptr +or +.IR n +is a null pointer. +.TP +.BR ENOMEM +Insufficient memory is available. +.P +These functions may fail if: +.TP +.BR EOVERFLOW +More than +{SSIZE_MAX} +characters were read without encountering the +.IR delimiter +character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int main(void) +{ + FILE *fp; + char *line = NULL; + size_t len = 0; + ssize_t read; + fp = fopen("/etc/motd", "r"); + if (fp == NULL) + exit(1); + while ((read = getline(&line, &len, fp)) != -1) { + printf("Retrieved line of length %zu :\en", read); + printf("%s", line); + } + if (ferror(fp)) { + /* handle error */ + } + free(line); + fclose(fp); + return 0; +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Setting +.IR *lineptr +to a null pointer and +.IR *n +to zero are allowed and a recommended way to start parsing a file. +.P +The +\fIferror\fR() +or +\fIfeof\fR() +functions should be used to distinguish between an error condition and +an end-of-file condition. +.P +Although a NUL terminator is always supplied after the line, note that +.IR strlen (* lineptr ) +will be smaller than the return value if the line contains embedded +NUL characters. +.SH RATIONALE +These functions are widely used to solve the problem that the +\fIfgets\fR() +function has with long lines. The functions automatically enlarge the +target buffers if needed. These are especially useful since they reduce +code needed for applications. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)", +.IR "\fIfree\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getegid.3p b/man-pages-posix-2013-a/man3p/getegid.3p new file mode 100644 index 0000000..62008be --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getegid.3p @@ -0,0 +1,70 @@ +'\" et +.TH GETEGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getegid +\(em get the effective group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +gid_t getegid(void); +.fi +.SH DESCRIPTION +The +\fIgetegid\fR() +function shall return the effective group ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetegid\fR() +function shall always be successful and no return value is reserved to +indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getenv.3p b/man-pages-posix-2013-a/man3p/getenv.3p new file mode 100644 index 0000000..99c8cfd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getenv.3p @@ -0,0 +1,220 @@ +'\" et +.TH GETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getenv +\(em get value of an environment variable +.SH SYNOPSIS +.LP +.nf +#include +.P +char *getenv(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIgetenv\fR() +function shall search the environment of the calling process (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables") +for the environment variable +.IR name +if it exists and return a pointer to the value of the environment +variable. If the specified environment variable cannot be found, a null +pointer shall be returned. The application shall ensure that it does +not modify the string pointed to by the +\fIgetenv\fR() +function. +.P +The returned string pointer might be invalidated or +the string content might be overwritten by a subsequent call to +\fIgetenv\fR(), +\fIsetenv\fR(), +\fIunsetenv\fR(), +or (if supported) +\fIputenv\fR() +but they shall not be affected by a call to any other function in this volume of POSIX.1\(hy2008. +.P +The +\fIgetenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetenv\fR() +shall return a pointer to a string containing the +.IR value +for the specified +.IR name . +If the specified +.IR name +cannot be found in the environment of the calling process, a null +pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the Value of an Environment Variable" +.P +The following example gets the value of the +.IR HOME +environment variable. +.sp +.RS 4 +.nf +\fB +#include +\&... +const char *name = "HOME"; +char *value; +.P +value = getenv(name); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIclearenv\fR() +function was considered but rejected. The +\fIputenv\fR() +function has now been included for alignment with the Single UNIX +Specification. +.P +The +\fIgetenv\fR() +function is inherently not thread-safe because it returns a value +pointing to static data. +.P +Conforming applications are required not to directly modify the pointers +to which +.IR environ +points, but to use only the +\fIsetenv\fR(), +\fIunsetenv\fR(), +and +\fIputenv\fR() +functions, or assignment to +.IR environ +itself, to manipulate the process environment. This constraint allows +the implementation to properly manage the memory it allocates. This +enables the implementation to free any space it has allocated to strings +(and perhaps the pointers to them) stored in +.IR environ +when +\fIunsetenv\fR() +is called. A C runtime start-up procedure (that which invokes +\fImain\fR() +and perhaps initializes +.IR environ ) +can also initialize a flag indicating that none of the environment has +yet been copied to allocated storage, or that the separate table has +not yet been initialized. If the application switches to a complete new +environment by assigning a new value to +.IR environ , +this can be detected by +\fIgetenv\fR(), +\fIsetenv\fR(), +\fIunsetenv\fR(), +or +\fIputenv\fR() +and the implementation can at that point reinitialize based on the new +environment. (This may include copying the environment strings into a +new array and assigning +.IR environ +to point to it.) +.P +In fact, for higher performance of +\fIgetenv\fR(), +implementations that do not provide +\fIputenv\fR() +could also maintain a separate copy of the environment in a data structure +that could be searched much more quickly (such as an indexed hash table, +or a binary tree), and update both it and the linear list at +.IR environ +when +\fIsetenv\fR() +or +\fIunsetenv\fR() +is invoked. On implementations that do provide +\fIputenv\fR(), +such a copy might still be worthwhile but would need to allow for the +fact that applications can directly modify the content of environment +strings added with +\fIputenv\fR(). +For example, if an environment string found by searching the copy is +one that was added using +\fIputenv\fR(), +the implementation would need to check that the string in +.IR environ +still has the same name (and value, if the copy includes values), and +whenever searching the copy produces no match the implementation would +then need to search each environment string in +.IR environ +that was added using +\fIputenv\fR() +in case any of them have changed their names and now match. Thus, each +use of +\fIputenv\fR() +to add to the environment would reduce the speed advantage of having +the copy. +.P +Performance of +\fIgetenv\fR() +can be important for applications which have large numbers of +environment variables. Typically, applications like this use the +environment as a resource database of user-configurable parameters. +The fact that these variables are in the user's shell environment +usually means that any other program that uses environment variables +(such as +.IR ls , +which attempts to use +.IR COLUMNS ), +or really almost any utility (\c +.IR LANG , +.IR LC_ALL , +and so on) is similarly slowed down by the linear search through the +variables. +.P +An implementation that maintains separate data structures, or even one +that manages the memory it consumes, is not currently required as it +was thought it would reduce consensus among implementors who do not +want to change their historical implementations. +.SH "FUTURE DIRECTIONS" +A future version may add one or more functions to access and modify the +environment in a thread-safe manner. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIsetenv\fR\^(\|)", +.IR "\fIunsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/geteuid.3p b/man-pages-posix-2013-a/man3p/geteuid.3p new file mode 100644 index 0000000..4ec16bc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/geteuid.3p @@ -0,0 +1,70 @@ +'\" et +.TH GETEUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +geteuid +\(em get the effective user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +uid_t geteuid(void); +.fi +.SH DESCRIPTION +The +\fIgeteuid\fR() +function shall return the effective user ID of the calling process. +.SH "RETURN VALUE" +The +\fIgeteuid\fR() +function shall always be successful and no return value is reserved to +indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getgid.3p b/man-pages-posix-2013-a/man3p/getgid.3p new file mode 100644 index 0000000..a1901e7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getgid.3p @@ -0,0 +1,70 @@ +'\" et +.TH GETGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getgid +\(em get the real group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +gid_t getgid(void); +.fi +.SH DESCRIPTION +The +\fIgetgid\fR() +function shall return the real group ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetgid\fR() +function shall always be successful and no return value is reserved +to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getgrent.3p b/man-pages-posix-2013-a/man3p/getgrent.3p new file mode 100644 index 0000000..1ae72e2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getgrent.3p @@ -0,0 +1,38 @@ +'\" et +.TH GETGRENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getgrent +\(em get the group database entry +.SH SYNOPSIS +.LP +.nf +#include +.P +struct group *getgrent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendgrent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getgrgid.3p b/man-pages-posix-2013-a/man3p/getgrgid.3p new file mode 100644 index 0000000..7d4b51e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getgrgid.3p @@ -0,0 +1,235 @@ +'\" et +.TH GETGRGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getgrgid, +getgrgid_r +\(em get group database entry for a group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +struct group *getgrgid(gid_t \fIgid\fP); +int getgrgid_r(gid_t \fIgid\fP, struct group *\fIgrp\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct group **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetgrgid\fR() +function shall search the group database for an entry with a matching +.IR gid . +.P +The +\fIgetgrgid\fR() +function need not be thread-safe. +.P +The +\fIgetgrgid_r\fR() +function shall update the +.BR group +structure pointed to by +.IR grp +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the group database with a +matching +.IR gid . +Storage referenced by the group structure is allocated from the memory +provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +returns either \(mi1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer shall be returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetgrgid\fR() +shall return a pointer to a +.BR "struct group" +with the structure defined in +.IR +with a matching entry if one is found. The +\fIgetgrgid\fR() +function shall return a null pointer if either the requested entry was +not found, or an error occurred. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetgrent\fR(), +\fIgetgrgid\fR(), +or +\fIgetgrnam\fR(). +.P +If successful, the +\fIgetgrgid_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIgetgrgid\fR() +and +\fIgetgrgid_r\fR() +functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetgrgid\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIgetgrgid_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR group +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +may return \(mi1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetgrid_r\fR(). +.sp +.RS 4 +.nf +\fB +long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct group result; +struct group *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getgrgid_r(42, &result, buffer, len, &resultp)) =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi \fR +.P +.RE +.SS "Finding an Entry in the Group Database" +.P +The following example uses +\fIgetgrgid\fR() +to search the group database for a group ID that was previously stored +in a +.BR stat +structure, then prints out the group name if it is found. If the group +is not found, the program prints the numeric value of the group for the +entry. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +struct stat statbuf; +struct group *grp; +\&... +if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); +else + printf(" %-8d", statbuf.st_gid); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetgrgid\fR(). +If +.IR errno +is set on return, an error occurred. +.P +The +\fIgetgrgid_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \(mi1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetgrnam\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getgrnam.3p b/man-pages-posix-2013-a/man3p/getgrnam.3p new file mode 100644 index 0000000..aa6ab98 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getgrnam.3p @@ -0,0 +1,210 @@ +'\" et +.TH GETGRNAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getgrnam, +getgrnam_r +\(em search group database for a name +.SH SYNOPSIS +.LP +.nf +#include +.P +struct group *getgrnam(const char *\fIname\fP); +int getgrnam_r(const char *\fIname\fP, struct group *\fIgrp\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct group **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetgrnam\fR() +function shall search the group database for an entry with a matching +.IR name . +.P +The +\fIgetgrnam\fR() +function need not be thread-safe. +.P +The +\fIgetgrnam_r\fR() +function shall update the +.BR group +structure pointed to by +.IR grp +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the group database with a +matching +.IR name . +Storage referenced by the +.BR group +structure is allocated from the memory provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +returns either \(mi1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer is returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +The +\fIgetgrnam\fR() +function shall return a pointer to a +.BR "struct group" +with the structure defined in +.IR +with a matching entry if one is found. The +\fIgetgrnam\fR() +function shall return a null pointer if either the requested entry +was not found, or an error occurred. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetgrent\fR(), +\fIgetgrgid\fR(), +or +\fIgetgrnam\fR(). +.P +The +\fIgetgrnam_r\fR() +function shall return zero on success or if the requested entry was not +found and no error has occurred. If any error has occurred, an error +number shall be returned to indicate the error. +.SH ERRORS +The +\fIgetgrnam\fR() +and +\fIgetgrnam_r\fR() +functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetgrnam\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the +system. +.P +The +\fIgetgrnam_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR group +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +may return \(mi1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetgrnam_r\fR(). +.sp +.RS 4 +.nf +\fB +long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct group result; +struct group *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getgrnam_r("somegroup", &result, buffer, len, &resultp)) + =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetgrnam\fR(). +If +.IR errno +is set on return, an error occurred. +.P +The +\fIgetgrnam_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \(mi1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getgroups.3p b/man-pages-posix-2013-a/man3p/getgroups.3p new file mode 100644 index 0000000..28f14a8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getgroups.3p @@ -0,0 +1,145 @@ +'\" et +.TH GETGROUPS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getgroups +\(em get supplementary group IDs +.SH SYNOPSIS +.LP +.nf +#include +.P +int getgroups(int \fIgidsetsize\fP, gid_t \fIgrouplist\fP[]); +.fi +.SH DESCRIPTION +The +\fIgetgroups\fR() +function shall fill in the array +.IR grouplist +with the current supplementary group IDs of the calling process. It is +implementation-defined whether +\fIgetgroups\fR() +also returns the effective group ID in the +.IR grouplist +array. +.P +The +.IR gidsetsize +argument specifies the number of elements in the array +.IR grouplist . +The actual number of group IDs stored in the array shall be returned. +The values of array entries with indices greater than or equal to the +value returned are undefined. +.P +If +.IR gidsetsize +is 0, +\fIgetgroups\fR() +shall return the number of group IDs that it would otherwise return +without modifying the array pointed to by +.IR grouplist . +.P +If the effective group ID of the process is returned with the +supplementary group IDs, the value returned shall always be greater +than or equal to one and less than or equal to the value of +{NGROUPS_MAX}+1. +.SH "RETURN VALUE" +Upon successful completion, the number of supplementary group IDs shall +be returned. A return value of \(mi1 indicates failure and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIgetgroups\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR gidsetsize +argument is non-zero and less than the number of group IDs that would +have been returned. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the Supplementary Group IDs of the Calling Process" +.P +The following example places the current supplementary group IDs of the +calling process into the +.IR group +array. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +gid_t *group; +int nogroups; +long ngroups_max; +.P +ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1; +group = (gid_t *)malloc(ngroups_max *sizeof(gid_t)); +.P +ngroups = getgroups(ngroups_max, group); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The related function +\fIsetgroups\fR() +is a privileged operation and therefore is not covered by this volume of POSIX.1\(hy2008. +.P +As implied by the definition of supplementary groups, the effective +group ID +may appear in the array returned by +\fIgetgroups\fR() +or it may be returned only by +\fIgetegid\fR(). +Duplication may exist, but the application needs to call +\fIgetegid\fR() +to be sure of getting all of the information. Various implementation +variations and administrative sequences cause the set of groups +appearing in the result of +\fIgetgroups\fR() +to vary in order and as to whether the effective group ID is included, +even when the set of groups is the same (in the mathematical sense of +``set''). (The history of a process and its parents could affect the +details of the result.) +.P +Application developers should note that +{NGROUPS_MAX} +is not necessarily a constant on all implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/gethostent.3p b/man-pages-posix-2013-a/man3p/gethostent.3p new file mode 100644 index 0000000..835f4d0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/gethostent.3p @@ -0,0 +1,38 @@ +'\" et +.TH GETHOSTENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gethostent +\(em network host database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +struct hostent *gethostent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendhostent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/gethostid.3p b/man-pages-posix-2013-a/man3p/gethostid.3p new file mode 100644 index 0000000..386d6d1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/gethostid.3p @@ -0,0 +1,60 @@ +'\" et +.TH GETHOSTID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gethostid +\(em get an identifier for the current host +.SH SYNOPSIS +.LP +.nf +#include +.P +long gethostid(void); +.fi +.SH DESCRIPTION +The +\fIgethostid\fR() +function shall retrieve a 32-bit identifier for the current host. +.SH "RETURN VALUE" +Upon successful completion, +\fIgethostid\fR() +shall return an identifier for the current host. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +This volume of POSIX.1\(hy2008 does not define the domain in which the return value is unique. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIinitstate\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/gethostname.3p b/man-pages-posix-2013-a/man3p/gethostname.3p new file mode 100644 index 0000000..93e4c39 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/gethostname.3p @@ -0,0 +1,73 @@ +'\" et +.TH GETHOSTNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gethostname +\(em get name of current host +.SH SYNOPSIS +.LP +.nf +#include +.P +int gethostname(char *\fIname\fP, size_t \fInamelen\fP); +.fi +.SH DESCRIPTION +The +\fIgethostname\fR() +function shall return the standard host name for the current machine. +The +.IR namelen +argument shall specify the size of the array pointed to by the +.IR name +argument. The returned name shall be null-terminated, except that if +.IR namelen +is an insufficient length to hold the host name, then the returned name +shall be truncated and it is unspecified whether the returned name is +null-terminated. +.P +Host names are limited to +{HOST_NAME_MAX} +bytes. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \(mi1 shall +be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgethostid\fR\^(\|)", +.IR "\fIuname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getitimer.3p b/man-pages-posix-2013-a/man3p/getitimer.3p new file mode 100644 index 0000000..cd48ace --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getitimer.3p @@ -0,0 +1,167 @@ +'\" et +.TH GETITIMER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getitimer, +setitimer +\(em get and set value of interval timer +.SH SYNOPSIS +.LP +.nf +#include +.P +int getitimer(int \fIwhich\fP, struct itimerval *\fIvalue\fP); +int setitimer(int \fIwhich\fP, const struct itimerval *restrict \fIvalue\fP, + struct itimerval *restrict \fIovalue\fP); +.fi +.SH DESCRIPTION +The +\fIgetitimer\fR() +function shall store the current value of the timer specified by +.IR which +into the structure pointed to by +.IR value . +The +\fIsetitimer\fR() +function shall set the timer specified by +.IR which +to the value specified in the structure pointed to by +.IR value , +and if +.IR ovalue +is not a null pointer, store the previous value of the timer in the +structure pointed to by +.IR ovalue . +.P +A timer value is defined by the +.BR itimerval +structure, specified in +.IR . +If +.IR it_value +is non-zero, it shall indicate the time to the next timer expiration. +If +.IR it_interval +is non-zero, it shall specify a value to be used in reloading +.IR it_value +when the timer expires. Setting +.IR it_value +to 0 shall disable a timer, regardless of the value of +.IR it_interval . +Setting +.IR it_interval +to 0 shall disable a timer after its next expiration (assuming +.IR it_value +is non-zero). +.P +Implementations may place limitations on the granularity of timer +values. For each interval timer, if the requested timer value requires +a finer granularity than the implementation supports, the actual timer +value shall be rounded up to the next supported value. +.P +An XSI-conforming implementation provides each process with at least +three interval timers, which are indicated by the +.IR which +argument: +.IP ITIMER_PROF 14 +Decrements both in process virtual time and when the system is running +on behalf of the process. It is designed to be used by interpreters in +statistically profiling the execution of interpreted programs. Each +time the ITIMER_PROF timer expires, the SIGPROF signal is delivered. +.IP ITIMER_REAL 14 +Decrements in real time. A SIGALRM signal is delivered when this timer +expires. +.IP ITIMER_VIRTUAL 14 +Decrements in process virtual time. It runs only when the process is +executing. A SIGVTALRM signal is delivered when it expires. +.P +The interaction between +\fIsetitimer\fR() +and +\fIalarm\fR() +or +\fIsleep\fR() +is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetitimer\fR() +or +\fIsetitimer\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetitimer\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR value +argument is not in canonical form. (In canonical form, the number of +microseconds is a non-negative integer less than 1\|000\|000 and the +number of seconds is a non-negative integer.) +.P +The +\fIgetitimer\fR() +and +\fIsetitimer\fR() +functions may fail if: +.TP +.BR EINVAL +The +.IR which +argument is not recognized. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications should use the +\fItimer_gettime\fR() +and +\fItimer_settime\fR() +functions instead of the obsolescent +\fIgetitimer\fR() +and +\fIsetitimer\fR() +functions, respectively. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIgetitimer\fR() +and +\fIsetitimer\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIsleep\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getline.3p b/man-pages-posix-2013-a/man3p/getline.3p new file mode 100644 index 0000000..3081a23 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getline.3p @@ -0,0 +1,40 @@ +'\" et +.TH GETLINE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getline +\(em read a delimited record from +.IR stream +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t getline(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetdelim\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getlogin.3p b/man-pages-posix-2013-a/man3p/getlogin.3p new file mode 100644 index 0000000..4d42edc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getlogin.3p @@ -0,0 +1,225 @@ +'\" et +.TH GETLOGIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getlogin, +getlogin_r +\(em get login name +.SH SYNOPSIS +.LP +.nf +#include +.P +char *getlogin(void); +int getlogin_r(char *\fIname\fP, size_t \fInamesize\fP); +.fi +.SH DESCRIPTION +The +\fIgetlogin\fR() +function shall return a pointer to a string containing the user name +associated by the login activity with the controlling terminal of the +current process. If +\fIgetlogin\fR() +returns a non-null pointer, then that pointer points to the name that +the user logged in under, even if there are several login names with +the same user ID. +.P +The +\fIgetlogin\fR() +function need not be thread-safe. +.P +The +\fIgetlogin_r\fR() +function shall put the name associated by the login activity with the +controlling terminal of the current process in the character array +pointed to by +.IR name . +The array is +.IR namesize +characters long and should have space for the name and the terminating +null character. The maximum size of the login name is +{LOGIN_NAME_MAX}. +.P +If +\fIgetlogin_r\fR() +is successful, +.IR name +points to the name the user used at login, even if there are several +login names with the same user ID. +.P +The +\fIgetlogin\fR() +and +\fIgetlogin_r\fR() +functions may make use of file descriptors 0, 1, and 2 to find the +controlling terminal of the current process, examining each in turn +until the terminal is found. If in this case none of these three file +descriptors is open to the controlling terminal, these functions may +fail. The method used to find the terminal associated with a file +descriptor may depend on the file descriptor being open to the actual +terminal device, not +.BR /dev/tty . +.SH "RETURN VALUE" +Upon successful completion, +\fIgetlogin\fR() +shall return a pointer to the login name or a null pointer if the +user's login name cannot be found. Otherwise, it shall return a null +pointer and set +.IR errno +to indicate the error. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIgetlogin\fR(). +.P +If successful, the +\fIgetlogin_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOTTY +None of the file descriptors 0, 1, or 2 is open to the controlling +terminal of the current process. +.TP +.BR ENXIO +The calling process has no controlling terminal. +.P +The +\fIgetlogin_r\fR() +function may fail if: +.TP +.BR ERANGE +The value of +.IR namesize +is smaller than the length of the string to be returned including the +terminating null character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the User Login Name" S +.P +The following example calls the +\fIgetlogin\fR() +function to obtain the name of the user associated with the calling +process, and passes this information to the +\fIgetpwnam\fR() +function to get the associated user database information. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +\&... +char *lgn; +struct passwd *pw; +\&... +if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { + fprintf(stderr, "Get of user information failed.\en"); exit(1); + } +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Three names associated with the current process can be determined: +.IR getpwuid (\c +\fIgeteuid\fR()) +shall return the name associated with the effective user ID of the +process; +\fIgetlogin\fR() +shall return the name associated with the current login activity; and +.IR getpwuid (\c +\fIgetuid\fR()) +shall return the name associated with the real user ID of the process. +.P +The +\fIgetlogin_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.SH RATIONALE +The +\fIgetlogin\fR() +function returns a pointer to the user's login name. The same user ID +may be shared by several login names. If it is desired to get the user +database entry that is used during login, the result of +\fIgetlogin\fR() +should be used to provide the argument to the +\fIgetpwnam\fR() +function. (This might be used to determine the user's login shell, +particularly where a single user has multiple login shells with +distinct login names, but the same user ID.) +.P +The information provided by the +.IR cuserid (\|) +function, which was originally defined in the POSIX.1\(hy1988 standard and subsequently +removed, can be obtained by the following: +.sp +.RS 4 +.nf +\fB +getpwuid(geteuid()) +.fi \fR +.P +.RE +.P +while the information provided by historical implementations of +.IR cuserid (\|) +can be obtained by: +.sp +.RS 4 +.nf +\fB +getpwuid(getuid()) +.fi \fR +.P +.RE +.P +The thread-safe version of this function places the user name in a +user-supplied buffer and returns a non-zero value if it fails. The +non-thread-safe version may return the name in a static data area that +may be overwritten by each call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getmsg.3p b/man-pages-posix-2013-a/man3p/getmsg.3p new file mode 100644 index 0000000..b660d1c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getmsg.3p @@ -0,0 +1,410 @@ +'\" et +.TH GETMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getmsg, +getpmsg +\(em receive next message from a STREAMS file (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int getmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP, + struct strbuf *restrict \fIdataptr\fP, int *restrict \fIflagsp\fP); +int getpmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP, + struct strbuf *restrict \fIdataptr\fP, int *restrict \fIbandp\fP, + int *restrict \fIflagsp\fP); +.fi +.SH DESCRIPTION +The +\fIgetmsg\fR() +function shall retrieve the contents of a message located at the head +of the STREAM head read queue associated with a STREAMS file and place +the contents into one or more buffers. The message contains either a +data part, a control part, or both. The data and control parts of the +message shall be placed into separate buffers, as described below. The +semantics of each part are defined by the originator of the message. +.P +The +\fIgetpmsg\fR() +function shall be equivalent to +\fIgetmsg\fR(), +except that it provides finer control over the priority of the messages +received. Except where noted, all requirements on +\fIgetmsg\fR() +also pertain to +\fIgetpmsg\fR(). +.P +The +.IR fildes +argument specifies a file descriptor referencing a STREAMS-based file. +.P +The +.IR ctlptr +and +.IR dataptr +arguments each point to a +.BR strbuf +structure, in which the +.IR buf +member points to a buffer in which the data or control information is +to be placed, and the +.IR maxlen +member indicates the maximum number of bytes this buffer can hold. On +return, the +.IR len +member shall contain the number of bytes of data or control information +actually received. The +.IR len +member shall be set to 0 if there is a zero-length control or data part +and +.IR len +shall be set to \(mi1 if no data or control information is present in +the message. +.P +When +\fIgetmsg\fR() +is called, +.IR flagsp +should point to an integer that indicates the type of message the +process is able to receive. This is described further below. +.P +The +.IR ctlptr +argument is used to hold the control part of the message, and +.IR dataptr +is used to hold the data part of the message. If +.IR ctlptr +(or +.IR dataptr ) +is a null pointer or the +.IR maxlen +member is \(mi1, the control (or data) part of the message shall not be +processed and shall be left on the STREAM head read queue, and if the +.IR ctlptr +(or +.IR dataptr ) +is not a null pointer, +.IR len +shall be set to \(mi1. If the +.IR maxlen +member is set to 0 and there is a zero-length control (or data) part, +that zero-length part shall be removed from the read queue and +.IR len +shall be set to 0. If the +.IR maxlen +member is set to 0 and there are more than 0 bytes of control (or data) +information, that information shall be left on the read queue and +.IR len +shall be set to 0. If the +.IR maxlen +member in +.IR ctlptr +(or +.IR dataptr ) +is less than the control (or data) part of the message, +.IR maxlen +bytes shall be retrieved. In this case, the remainder of the message +shall be left on the STREAM head read queue and a non-zero return value +shall be provided. +.P +By default, +\fIgetmsg\fR() +shall process the first available message on the STREAM head read +queue. However, a process may choose to retrieve only high-priority +messages by setting the integer pointed to by +.IR flagsp +to RS_HIPRI. In this case, +\fIgetmsg\fR() +shall only process the next message if it is a high-priority message. +When the integer pointed to by +.IR flagsp +is 0, any available message shall be retrieved. In this case, on +return, the integer pointed to by +.IR flagsp +shall be set to RS_HIPRI if a high-priority message was retrieved, or 0 +otherwise. +.P +For +\fIgetpmsg\fR(), +the flags are different. The +.IR flagsp +argument points to a bitmask with the following mutually-exclusive +flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. +Like +\fIgetmsg\fR(), +\fIgetpmsg\fR() +shall process the first available message on the STREAM head read +queue. A process may choose to retrieve only high-priority messages by +setting the integer pointed to by +.IR flagsp +to MSG_HIPRI and the integer pointed to by +.IR bandp +to 0. In this case, +\fIgetpmsg\fR() +shall only process the next message if it is a high-priority message. +In a similar manner, a process may choose to retrieve a message from a +particular priority band by setting the integer pointed to by +.IR flagsp +to MSG_BAND and the integer pointed to by +.IR bandp +to the priority band of interest. In this case, +\fIgetpmsg\fR() +shall only process the next message if it is in a priority band equal +to, or greater than, the integer pointed to by +.IR bandp , +or if it is a high-priority message. If a process wants to get the +first message off the queue, the integer pointed to by +.IR flagsp +should be set to MSG_ANY and the integer pointed to by +.IR bandp +should be set to 0. On return, if the message retrieved was a +high-priority message, the integer pointed to by +.IR flagsp +shall be set to MSG_HIPRI and the integer pointed to by +.IR bandp +shall be set to 0. Otherwise, the integer pointed to by +.IR flagsp +shall be set to MSG_BAND and the integer pointed to by +.IR bandp +shall be set to the priority band of the message. +.P +If O_NONBLOCK is not set, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall block until a message of the type specified by +.IR flagsp +is available at the front of the STREAM head read queue. If O_NONBLOCK +is set and a message of the specified type is not present at the front +of the read queue, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall fail and set +.IR errno +to +.BR [EAGAIN] . +.P +If a hangup occurs on the STREAM from which messages are retrieved, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall continue to operate normally, as described above, until the +STREAM head read queue is empty. Thereafter, they shall return 0 in the +.IR len +members of +.IR ctlptr +and +.IR dataptr . +.SH "RETURN VALUE" +Upon successful completion, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall return a non-negative value. A value of 0 indicates that a full +message was read successfully. A return value of MORECTL indicates +that more control +information is waiting for retrieval. A return value of MOREDATA +indicates that more data is waiting for retrieval. A return value of +the bitwise-logical OR of MORECTL and MOREDATA indicates that both +types of information remain. Subsequent +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +calls shall retrieve the remainder of the message. However, if a message +of higher priority has come in on the STREAM head read queue, the next +call to +\fIgetmsg\fR() +or +\fIgetpmsg\fR() +shall retrieve that higher-priority message before retrieving the +remainder of the previous message. +.P +If the high priority control part of the message is consumed, the +message shall be placed back on the queue as a normal message of band +0. Subsequent +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +calls shall retrieve the remainder of the message. If, however, a +priority message arrives or already exists on the STREAM head, the +subsequent call to +\fIgetmsg\fR() +or +\fIgetpmsg\fR() +shall retrieve the higher-priority message before retrieving the +remainder of the message that was put back. +.P +Upon failure, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +functions shall fail if: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set and no messages are available. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor open for reading. +.TP +.BR EBADMSG +The queued message to be read is not valid for +\fIgetmsg\fR() +or +\fIgetpmsg\fR() +or a pending file descriptor is at the STREAM head. +.TP +.BR EINTR +A signal was caught during +\fIgetmsg\fR() +or +\fIgetpmsg\fR(). +.TP +.BR EINVAL +An illegal value was specified by +.IR flagsp , +or the STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.TP +.BR ENOSTR +A STREAM is not associated with +.IR fildes . +.P +In addition, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall fail if the STREAM head had processed an asynchronous error +before the call. In this case, the value of +.IR errno +does not reflect the result of +\fIgetmsg\fR() +or +\fIgetpmsg\fR() +but reflects the prior error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting Any Message" +.P +In the following example, the value of +.IR fd +is assumed to refer to an open STREAMS file. The call to +\fIgetmsg\fR() +retrieves any available message on the associated STREAM-head read +queue, returning control and data information to the buffers pointed to +by +.IR ctrlbuf +and +.IR databuf , +respectively. +.sp +.RS 4 +.nf +\fB +#include +\&... +int fd; +char ctrlbuf[128]; +char databuf[512]; +struct strbuf ctrl; +struct strbuf data; +int flags = 0; +int ret; +.P +ctrl.buf = ctrlbuf; +ctrl.maxlen = sizeof(ctrlbuf); +.P +data.buf = databuf; +data.maxlen = sizeof(databuf); +.P +ret = getmsg (fd, &ctrl, &data, &flags); +.fi \fR +.P +.RE +.SS "Getting the First Message off the Queue" +.P +In the following example, the call to +\fIgetpmsg\fR() +retrieves the first available message on the associated STREAM-head +read queue. +.sp +.RS 4 +.nf +\fB +#include +\&... +.P +int fd; +char ctrlbuf[128]; +char databuf[512]; +struct strbuf ctrl; +struct strbuf data; +int band = 0; +int flags = MSG_ANY; +int ret; +.P +ctrl.buf = ctrlbuf; +ctrl.maxlen = sizeof(ctrlbuf); +.P +data.buf = databuf; +data.maxlen = sizeof(databuf); +.P +ret = getpmsg (fd, &ctrl, &data, &band, &flags); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getnameinfo.3p b/man-pages-posix-2013-a/man3p/getnameinfo.3p new file mode 100644 index 0000000..14f21fa --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getnameinfo.3p @@ -0,0 +1,234 @@ +'\" et +.TH GETNAMEINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getnameinfo +\(em get name information +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int getnameinfo(const struct sockaddr *restrict \fIsa\fP, socklen_t \fIsalen\fP, + char *restrict \fInode\fP, socklen_t \fInodelen\fP, char *restrict \fIservice\fP, + socklen_t \fIservicelen\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIgetnameinfo\fR() +function shall translate a socket address to a node name and service +location, all of which are defined as in +.IR "\fIfreeaddrinfo\fR\^(\|)". +.P +The +.IR sa +argument points to a socket address structure to be translated. The +.IR salen +argument contains the length of the address pointed to by +.IR sa . +.P +If the socket address structure contains an IPv4-mapped IPv6 address or +an IPv4-compatible IPv6 address, the implementation shall extract the +embedded IPv4 address and lookup the node name for that IPv4 address. +.P +If the address is the IPv6 unspecified address (\c +.BR \(dq::\(dq ), +a lookup shall not be performed and the behavior shall be the same as +when the node's name cannot be located. +.P +If the +.IR node +argument is non-NULL and the +.IR nodelen +argument is non-zero, then the +.IR node +argument points to a buffer able to contain up to +.IR nodelen +bytes that receives the node name as a null-terminated string. If the +.IR node +argument is NULL or the +.IR nodelen +argument is zero, the node name shall not be returned. If the node's +name cannot be located, the numeric form of the address contained +in the socket address structure pointed to by the +.IR sa +argument is returned instead of its name. +.P +If the +.IR service +argument is non-NULL and the +.IR servicelen +argument is non-zero, then the +.IR service +argument points to a buffer able to contain up to +.IR servicelen +bytes that receives the service name as a null-terminated string. +If the +.IR service +argument is NULL or the +.IR servicelen +argument is zero, the service name shall not be returned. If the +service's name cannot be located, the numeric form of the service +address (for example, its port number) shall be returned instead of +its name. +.P +The +.IR flags +argument is a flag that changes the default actions of the function. By +default the fully-qualified domain name (FQDN) for the +host shall be returned, but: +.IP " *" 4 +If the flag bit NI_NOFQDN is set, only the node name portion of the +FQDN shall be returned for local hosts. +.IP " *" 4 +If the flag bit NI_NUMERICHOST is set, the numeric form of the address +contained in the socket address structure pointed to by the +.IR sa +argument shall be returned instead of its name. +.IP " *" 4 +If the flag bit NI_NAMEREQD is set, an error shall be returned if the +host's name cannot be located. +.IP " *" 4 +If the flag bit NI_NUMERICSERV is set, the numeric form of the service +address shall be returned (for example, its port number) instead of its +name. +.IP " *" 4 +If the flag bit NI_NUMERICSCOPE is set, the numeric form of the scope +identifier shall be returned (for example, interface index) instead of +its name. This flag shall be ignored if the +.IR sa +argument is not an IPv6 address. +.IP " *" 4 +If the flag bit NI_DGRAM is set, this indicates that the service is a +datagram service (SOCK_DGRAM). The default behavior shall assume that +the service is a stream service (SOCK_STREAM). +.TP 10 +.BR Notes: +.RS 10 +.IP " 1." 4 +The two NI_NUMERICxxx flags are required to support the +.BR \(min +flag that many commands provide. +.IP " 2." 4 +The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port +numbers (for example, [512,514]) that represent different services for +UDP and TCP. +.RE +.P +.P +The +\fIgetnameinfo\fR() +function shall be thread-safe. +.SH "RETURN VALUE" +A zero return value for +\fIgetnameinfo\fR() +indicates successful completion; a non-zero return value indicates +failure. The possible values for the failures are listed in the +ERRORS section. +.P +Upon successful completion, +\fIgetnameinfo\fR() +shall return the +.IR node +and +.IR service +names, if requested, in the buffers provided. The returned names are +always null-terminated strings. +.SH ERRORS +The +\fIgetnameinfo\fR() +function shall fail and return the corresponding value if: +.IP [EAI_AGAIN] 12 +The name could not be resolved at this time. Future attempts may +succeed. +.IP [EAI_BADFLAGS] 12 +.br +The +.IR flags +had an invalid value. +.IP [EAI_FAIL] 12 +A non-recoverable error occurred. +.IP [EAI_FAMILY] 12 +The address family was not recognized or the address length was invalid +for the specified family. +.IP [EAI_MEMORY] 12 +There was a memory allocation failure. +.IP [EAI_NONAME] 12 +The name does not resolve for the supplied parameters. +.RS 12 +.P +NI_NAMEREQD is set and the host's name cannot be located, or both +.IR nodename +and +.IR servname +were null. +.RE +.IP [EAI_OVERFLOW] 12 +.br +An argument buffer overflowed. The buffer pointed to by the +.IR node +argument or the +.IR service +argument was too small. +.IP [EAI_SYSTEM] 12 +A system error occurred. The error code can be found in +.IR errno . +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +If the returned values are to be used as part of any further name +resolution (for example, passed to +\fIgetaddrinfo\fR()), +applications should provide buffers large enough to store any result +possible on the system. +.P +Given the IPv4-mapped IPv6 address +.BR \(dq::ffff:1.2.3.4\(dq , +the implementation performs a lookup as if the socket address structure +contains the IPv4 address +.BR \(dq1.2.3.4\(dq . +.P +The IPv6 unspecified address (\c +.BR \(dq::\(dq ) +and the IPv6 loopback address (\c +.BR \(dq::1\(dq ) +are not IPv4-compatible addresses. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendservent\fR\^(\|)", +.IR "\fIfreeaddrinfo\fR\^(\|)", +.IR "\fIgai_strerror\fR\^(\|)", +.IR "\fIinet_ntop\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getnetbyaddr.3p b/man-pages-posix-2013-a/man3p/getnetbyaddr.3p new file mode 100644 index 0000000..c7ab1ae --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getnetbyaddr.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETNETBYADDR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getnetbyaddr, +getnetbyname, +getnetent +\(em network database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +struct netent *getnetbyaddr(uint32_t \fInet\fP, int \fItype\fP); +struct netent *getnetbyname(const char *\fIname\fP); +struct netent *getnetent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendnetent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getopt.3p b/man-pages-posix-2013-a/man3p/getopt.3p new file mode 100644 index 0000000..4abec74 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getopt.3p @@ -0,0 +1,445 @@ +'\" et +.TH GETOPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getopt, +optarg, +opterr, +optind, +optopt +\(em command option parsing +.SH SYNOPSIS +.LP +.nf +#include +.P +int getopt(int \fIargc\fP, char * const \fIargv\fP[], const char *\fIoptstring\fP); +extern char *optarg; +extern int opterr, optind, optopt; +.fi +.SH DESCRIPTION +The +\fIgetopt\fR() +function is a command-line parser that shall follow Utility Syntax +Guidelines 3, 4, 5, 6, 7, 9, and 10 in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The parameters +.IR argc +and +.IR argv +are the argument count and argument array as passed to +\fImain\fR() +(see +\fIexec\fR()). +The argument +.IR optstring +is a string of recognized option characters; if a character is followed +by a +, +the option takes an argument. All option characters allowed by Utility +Syntax Guideline 3 are allowed in +.IR optstring . +The implementation may accept other characters as an extension. +.P +The variable +.IR optind +is the index of the next element of the +.IR argv [\^] +vector to be processed. It shall be initialized to 1 by the system, and +\fIgetopt\fR() +shall update it when it finishes with each element of +.IR argv [\|]. +If the application sets +.IR optind +to zero before calling +\fIgetopt\fR(), +the behavior is unspecified. When an element of +.IR argv [\|] +contains multiple option characters, it is unspecified how +\fIgetopt\fR() +determines which options have already been processed. +.P +The +\fIgetopt\fR() +function shall return the next option character (if one is found) from +.IR argv +that matches a character in +.IR optstring , +if there is one that matches. If the option takes an argument, +\fIgetopt\fR() +shall set the variable +.IR optarg +to point to the option-argument as follows: +.IP " 1." 4 +If the option was the last character in the string pointed to by an +element of +.IR argv , +then +.IR optarg +shall contain the next element of +.IR argv , +and +.IR optind +shall be incremented by 2. If the resulting value of +.IR optind +is greater than +.IR argc , +this indicates a missing option-argument, and +\fIgetopt\fR() +shall return an error indication. +.IP " 2." 4 +Otherwise, +.IR optarg +shall point to the string following the option character in that +element of +.IR argv , +and +.IR optind +shall be incremented by 1. +.P +If, when +\fIgetopt\fR() +is called: +.sp +.RS 4 +.nf +\fB + \fIargv\fP[optind] \fRis a null pointer\fP +*\fIargv\fP[optind] \fRis not the character\fP \(mi + \fIargv\fP[optind] \fRpoints to the string\fP "\(mi" +.fi \fR +.P +.RE +.P +\fIgetopt\fR() +shall return \(mi1 without changing +.IR optind . +If: +.sp +.RS 4 +.nf +\fB +\fIargv\fP[optind] \fRpoints to the string\fP "\(mi\|\(mi" +.fi \fR +.P +.RE +.P +\fIgetopt\fR() +shall return \(mi1 after incrementing +.IR optind . +.P +If +\fIgetopt\fR() +encounters an option character that is not contained in +.IR optstring , +it shall return the + +(\c +.BR '?' ) +character. If it detects a missing option-argument, it shall return the + +character (\c +.BR ':' ) +if the first character of +.IR optstring +was a +, +or a + +character (\c +.BR '?' ) +otherwise. In either case, +\fIgetopt\fR() +shall set the variable +.IR optopt +to the option character that caused the error. If the application has +not set the variable +.IR opterr +to 0 and the first character of +.IR optstring +is not a +, +\fIgetopt\fR() +shall also print a diagnostic message to +.IR stderr +in the format specified for the +.IR getopts +utility. +.P +The +\fIgetopt\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIgetopt\fR() +function shall return the next option character specified on the command +line. +.P +A + +(\c +.BR ':' ) +shall be returned if +\fIgetopt\fR() +detects a missing argument and the first character of +.IR optstring +was a + +(\c +.BR ':' ). +.P +A + +(\c +.BR '?' ) +shall be returned if +\fIgetopt\fR() +encounters an option character not in +.IR optstring +or detects a missing argument and the first character of +.IR optstring +was not a + +(\c +.BR ':' ). +.P +Otherwise, +\fIgetopt\fR() +shall return \(mi1 when all command line options are parsed. +.SH ERRORS +If the application has not set the variable +.IR opterr +to 0, the first character of +.IR optstring +is not a +, +and a write error occurs while +\fIgetopt\fR() +is printing a diagnostic message to +.IR stderr , +then the error indicator for +.IR stderr +shall be set; but +\fIgetopt\fR() +shall still succeed and the value of +.IR errno +after +\fIgetopt\fR() +is unspecified. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Parsing Command Line Options" +.P +The following code fragment shows how you might process the arguments +for a utility that can take the mutually-exclusive options +.IR a +and +.IR b +and the options +.IR f +and +.IR o , +both of which require arguments: +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +int +main(int argc, char *argv[ ]) +{ + int c; + int bflg = 0, aflg = 0, errflg = 0; + char *ifile; + char *ofile; + . . . + while ((c = getopt(argc, argv, ":abf:o:")) != -1) { + switch(c) { + case 'a': + if (bflg) + errflg++; + else + aflg++; + break; + case 'b': + if (aflg) + errflg++; + else + bflg++; + break; + case 'f': + ifile = optarg; + break; + case 'o': + ofile = optarg; + break; + case ':': /* -f or -o without operand */ + fprintf(stderr, + "Option -%c requires an operand\en", optopt); + errflg++; + break; + case '?': + fprintf(stderr, + "Unrecognized option: '-%c'\en", optopt); + errflg++; + } + } + if (errflg) { + fprintf(stderr, "usage: . . . "); + exit(2); + } + for ( ; optind < argc; optind++) { + if (access(argv[optind], R_OK)) { + . . . +} +.fi \fR +.P +.RE +.P +This code accepts any of the following as equivalent: +.sp +.RS 4 +.nf +\fB +cmd \(miao arg path path +cmd \(mia \(mio arg path path +cmd \(mio arg \(mia path path +cmd \(mia \(mio arg \(mi\|\(mi path path +cmd \(mia \(mioarg path path +cmd \(miaoarg path path +.fi \fR +.P +.RE +.SS "Selecting Options from the Command Line" +.P +The following example selects the type of database routines the user +wants to use based on the +.IR Options +argument. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +const char *Options = "hdbtl"; +\&... +int dbtype, c; +char *st; +\&... +dbtype = 0; +while ((c = getopt(argc, argv, Options)) != \(mi1) { + if ((st = strchr(Options, c)) != NULL) { + dbtype = st - Options; + break; + } +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIgetopt\fR() +function is only required to support option characters included in +Utility Syntax Guideline 3. Many historical implementations of +\fIgetopt\fR() +support other characters as options. This is an allowed extension, but +applications that use extensions are not maximally portable. Note that +support for multi-byte option characters is only possible when such +characters can be represented as type +.BR int . +.P +While +.IR ferror ( stderr ) +may be used to detect failures to write a diagnostic to +.IR stderr +when +\fIgetopt\fR() +returns +.BR '?' , +the value of +.IR errno +is unspecified in such a condition. Applications desiring more control +over handling write failures should set +.IR opterr +to 0 and independently perform output to +.IR stderr , +rather than relying on +\fIgetopt\fR() +to do the output. +.SH RATIONALE +The +.IR optopt +variable represents historical practice and allows the application to +obtain the identity of the invalid option. +.P +The description has been written to make it clear that +\fIgetopt\fR(), +like the +.IR getopts +utility, deals with option-arguments whether separated from the option +by + +characters or not. Note that the requirements on +\fIgetopt\fR() +and +.IR getopts +are more stringent than the Utility Syntax Guidelines. +.P +The +\fIgetopt\fR() +function shall return \(mi1, rather than EOF, so that +.IR +is not required. +.P +The special significance of a + +as the first character of +.IR optstring +makes +\fIgetopt\fR() +consistent with the +.IR getopts +utility. It allows an application to make a distinction between a +missing argument and an incorrect option letter without having to +examine the option letter. It is true that a missing argument can only +be detected in one case, but that is a case that has to be considered. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetopts\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpeername.3p b/man-pages-posix-2013-a/man3p/getpeername.3p new file mode 100644 index 0000000..399c22e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpeername.3p @@ -0,0 +1,121 @@ +'\" et +.TH GETPEERNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpeername +\(em get the name of the peer socket +.SH SYNOPSIS +.LP +.nf +#include +.P +int getpeername(int \fIsocket\fP, struct sockaddr *restrict \fIaddress\fP, + socklen_t *restrict \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIgetpeername\fR() +function shall retrieve the peer address of the specified socket, +store this address in the +.BR sockaddr +structure pointed to by the +.IR address +argument, and store the length of this address in the object pointed +to by the +.IR address_len +argument. +.P +The +.IR address_len +argument points to a +.BR socklen_t +object which on input specifies the length of the supplied +.BR sockaddr +structure, and on output specifies the length of the stored address. +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. +.P +If the protocol permits connections by unbound clients, and the peer is +not bound, then the value stored in the object pointed to by +.IR address +is unspecified. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIgetpeername\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EINVAL +The socket has been shut down. +.TP +.BR ENOTCONN +The socket is not connected or otherwise has not had the peer +pre-specified. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The operation is not supported for the socket protocol. +.P +The +\fIgetpeername\fR() +function may fail if: +.TP +.BR ENOBUFS +Insufficient resources were available in the system to complete the +call. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.br +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpgid.3p b/man-pages-posix-2013-a/man3p/getpgid.3p new file mode 100644 index 0000000..43e6db2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpgid.3p @@ -0,0 +1,98 @@ +'\" et +.TH GETPGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpgid +\(em get the process group ID for a process +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getpgid(pid_t \fIpid\fP); +.fi +.SH DESCRIPTION +The +\fIgetpgid\fR() +function shall return the process group ID of the process whose process +ID is equal to +.IR pid . +If +.IR pid +is equal to 0, +\fIgetpgid\fR() +shall return the process group ID of the calling process. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetpgid\fR() +shall return a process group ID. Otherwise, it shall return +(\fBpid_t\fP)\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgetpgid\fR() +function shall fail if: +.TP +.BR EPERM +The process whose process ID is equal to +.IR pid +is not in the same session as the calling process, and the +implementation does not allow access to the process group ID of that +process from the calling process. +.TP +.BR ESRCH +There is no process with a process ID equal to +.IR pid . +.P +The +\fIgetpgid\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR pid +argument is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetsid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpgrp.3p b/man-pages-posix-2013-a/man3p/getpgrp.3p new file mode 100644 index 0000000..a2da4c9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpgrp.3p @@ -0,0 +1,80 @@ +'\" et +.TH GETPGRP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpgrp +\(em get the process group ID of the calling process +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getpgrp(void); +.fi +.SH DESCRIPTION +The +\fIgetpgrp\fR() +function shall return the process group ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetpgrp\fR() +function shall always be successful and no return value is reserved +to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +4.3 BSD provides a +\fIgetpgrp\fR() +function that returns the process group ID +for a specified process. Although this function supports job +control, all +known job control shells always specify the calling +process with this function. Thus, the simpler System V +\fIgetpgrp\fR() +suffices, and the added complexity of the 4.3 BSD +\fIgetpgrp\fR() +is provided by the XSI extension +\fIgetpgid\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetppid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpid.3p b/man-pages-posix-2013-a/man3p/getpid.3p new file mode 100644 index 0000000..6f81d0e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpid.3p @@ -0,0 +1,69 @@ +'\" et +.TH GETPID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpid +\(em get the process ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getpid(void); +.fi +.SH DESCRIPTION +The +\fIgetpid\fR() +function shall return the process ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetpid\fR() +function shall always be successful and no return value is reserved to +indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIgetppid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpmsg.3p b/man-pages-posix-2013-a/man3p/getpmsg.3p new file mode 100644 index 0000000..7f0b0a1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpmsg.3p @@ -0,0 +1,40 @@ +'\" et +.TH GETPMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpmsg +\(em receive next message from a STREAMS file +.SH SYNOPSIS +.LP +.nf +#include +.P +int getpmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP, + struct strbuf *restrict \fIdataptr\fP, int *restrict \fIbandp\fP, + int *restrict \fIflagsp\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetmsg\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getppid.3p b/man-pages-posix-2013-a/man3p/getppid.3p new file mode 100644 index 0000000..5cdcab7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getppid.3p @@ -0,0 +1,69 @@ +'\" et +.TH GETPPID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getppid +\(em get the parent process ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getppid(void); +.fi +.SH DESCRIPTION +The +\fIgetppid\fR() +function shall return the parent process ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetppid\fR() +function shall always be successful and no return value is reserved to +indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpriority.3p b/man-pages-posix-2013-a/man3p/getpriority.3p new file mode 100644 index 0000000..247d18a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpriority.3p @@ -0,0 +1,235 @@ +'\" et +.TH GETPRIORITY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpriority, +setpriority +\(em get and set the nice value +.SH SYNOPSIS +.LP +.nf +#include +.P +int getpriority(int \fIwhich\fP, id_t \fIwho\fP); +int setpriority(int \fIwhich\fP, id_t \fIwho\fP, int \fIvalue\fP); +.fi +.SH DESCRIPTION +The +\fIgetpriority\fR() +function shall obtain the nice value of a process, process group, or +user. The +\fIsetpriority\fR() +function shall set the nice value of a process, process group, or user +to +.IR value +\c +{NZERO}. +.P +Target processes are specified by the values of the +.IR which +and +.IR who +arguments. The +.IR which +argument may be one of the following values: PRIO_PROCESS, PRIO_PGRP, +or PRIO_USER, indicating that the +.IR who +argument +is to be interpreted as a process ID, a process group ID, or an +effective user ID, respectively. A 0 value for the +.IR who +argument specifies the current process, process group, or user. +.P +The nice value set with +\fIsetpriority\fR() +shall be applied to the process. If the process is multi-threaded, +the nice value shall affect all system scope threads in the process. +.P +If more than one process is specified, +\fIgetpriority\fR() +shall return value +{NZERO} +less than the lowest nice value pertaining to any of the specified +processes, and +\fIsetpriority\fR() +shall set the nice values of all of the specified processes to +.IR value +\c +{NZERO}. +.P +The default nice value is +{NZERO}; +lower nice values shall cause more favorable scheduling. While the +range of valid nice values is [0,{NZERO}*2\(mi1], implementations may +enforce more restrictive limits. If +.IR value +\c +{NZERO} +is less than the system's lowest supported nice value, +\fIsetpriority\fR() +shall set the nice value to the lowest supported value; if +.IR value +\c +{NZERO} +is greater than the system's highest supported nice value, +\fIsetpriority\fR() +shall set the nice value to the highest supported value. +.P +Only a process with appropriate privileges can lower its nice value. +.P +Any processes or threads using SCHED_FIFO or SCHED_RR shall be +unaffected by a call to +\fIsetpriority\fR(). +This is not considered an error. A process which subsequently reverts +to SCHED_OTHER need not have its priority affected by such a +\fIsetpriority\fR() +call. +.P +The effect of changing the nice value may vary depending on the +process-scheduling algorithm in effect. +.P +Since +\fIgetpriority\fR() +can return the value \(mi1 upon successful completion, it is necessary to +set +.IR errno +to 0 prior to a call to +\fIgetpriority\fR(). +If +\fIgetpriority\fR() +returns the value \(mi1, then +.IR errno +can be checked to see if an error occurred or if the value is a +legitimate nice value. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetpriority\fR() +shall return an integer in the range \(mi{NZERO} to +{NZERO}\(mi1. +Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.P +Upon successful completion, +\fIsetpriority\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.br +.SH ERRORS +The +\fIgetpriority\fR() +and +\fIsetpriority\fR() +functions shall fail if: +.TP +.BR ESRCH +No process could be located using the +.IR which +and +.IR who +argument values specified. +.TP +.BR EINVAL +The value of the +.IR which +argument was not recognized, or the value of the +.IR who +argument is not a valid process ID, process group ID, or user ID. +.P +In addition, +\fIsetpriority\fR() +may fail if: +.TP +.BR EPERM +A process was located, but neither the real nor effective user ID of +the executing process match the effective user ID of the process whose +nice value is being changed. +.TP +.BR EACCES +A request was made to change the nice value to a lower numeric value +and the current process does not have appropriate privileges. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using getpriority(\|)" +.P +The following example returns the current scheduling priority for the +process ID returned by the call to +\fIgetpid\fR(). +.sp +.RS 4 +.nf +\fB +#include +\&... +int which = PRIO_PROCESS; +id_t pid; +int ret; +.P +pid = getpid(); +ret = getpriority(which, pid); +.fi \fR +.P +.RE +.SS "Using setpriority(\|)" +.P +The following example sets the priority for the current process ID to +\(mi20. +.sp +.RS 4 +.nf +\fB +#include +\&... +int which = PRIO_PROCESS; +id_t pid; +int priority = -20; +int ret; +.P +pid = getpid(); +ret = setpriority(which, pid, priority); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIgetpriority\fR() +and +\fIsetpriority\fR() +functions work with an offset nice value (nice value \(mi{NZERO}). The +nice value is in the range [0,2*{NZERO} \(mi1], while the return value +for +\fIgetpriority\fR() +and the third parameter for +\fIsetpriority\fR() +are in the range [\(mi{NZERO},{NZERO} \(mi1]. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fInice\fR\^(\|)", +.IR "\fIsched_get_priority_max\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getprotobyname.3p b/man-pages-posix-2013-a/man3p/getprotobyname.3p new file mode 100644 index 0000000..05d135b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getprotobyname.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETPROTOBYNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getprotobyname, +getprotobynumber, +getprotent +\(em network protocol database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +struct protoent *getprotobyname(const char *\fIname\fP); +struct protoent *getprotobynumber(int \fIproto\fP); +struct protoent *getprotoent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendprotoent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpwent.3p b/man-pages-posix-2013-a/man3p/getpwent.3p new file mode 100644 index 0000000..f46fe7d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpwent.3p @@ -0,0 +1,38 @@ +'\" et +.TH GETPWENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpwent +\(em get user database entry +.SH SYNOPSIS +.LP +.nf +#include +.P +struct passwd *getpwent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendpwent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpwnam.3p b/man-pages-posix-2013-a/man3p/getpwnam.3p new file mode 100644 index 0000000..5d47101 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpwnam.3p @@ -0,0 +1,241 @@ +'\" et +.TH GETPWNAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpwnam, +getpwnam_r +\(em search user database for a name +.SH SYNOPSIS +.LP +.nf +#include +.P +struct passwd *getpwnam(const char *\fIname\fP); +int getpwnam_r(const char *\fIname\fP, struct passwd *\fIpwd\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct passwd **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetpwnam\fR() +function shall search the user database for an entry with a matching +.IR name . +.P +The +\fIgetpwnam\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetpwnam\fR(). +If +\fIgetpwnam\fR() +returns a null pointer and +.IR errno +is non-zero, an error occurred. +.P +The +\fIgetpwnam_r\fR() +function shall update the +.BR passwd +structure pointed to by +.IR pwd +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the user database with a +matching +.IR name . +Storage referenced by the structure is allocated from the memory +provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +returns either \(mi1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer shall be returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +The +\fIgetpwnam\fR() +function shall return a pointer to a +.BR "struct passwd" +with the structure as defined in +.IR +with a matching entry if found. A null pointer shall be returned if the +requested entry is not found, or an error occurs. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetpwent\fR(), +\fIgetpwnam\fR(), +or +\fIgetpwuid\fR(). +.P +The +\fIgetpwnam_r\fR() +function shall return zero on success or if the requested entry +was not found and no error has occurred. If an error has +occurred, an error number shall be returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetpwnam\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIgetpwnam_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR passwd +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +may return \(mi1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetpwnam_r\fR(). +.sp +.RS 4 +.nf +\fB +long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct passwd result; +struct passwd *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getpwnam_r("someuser", &result, buffer, len, &resultp)) + =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi \fR +.P +.RE +.SS "Getting an Entry for the Login Name" +.P +The following example uses the +\fIgetlogin\fR() +function to return the name of the user who logged in; this information +is passed to the +\fIgetpwnam\fR() +function to get the user database entry for that user. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +\&... +char *lgn; +struct passwd *pw; +\&... +if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { + fprintf(stderr, "Get of user information failed.\en"); exit(1); +} +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Three names associated with the current process can be determined: +.IR getpwuid (\c +\fIgeteuid\fR()) +returns the name associated with the effective user ID of the process; +\fIgetlogin\fR() +returns the name associated with the current login activity; and +.IR getpwuid (\c +\fIgetuid\fR()) +returns the name associated with the real user ID of the process. +.P +The +\fIgetpwnam_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \(mi1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETPW_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpwuid\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getpwuid.3p b/man-pages-posix-2013-a/man3p/getpwuid.3p new file mode 100644 index 0000000..e333a04 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getpwuid.3p @@ -0,0 +1,290 @@ +'\" et +.TH GETPWUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getpwuid, +getpwuid_r +\(em search user database for a user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +struct passwd *getpwuid(uid_t \fIuid\fP); +int getpwuid_r(uid_t \fIuid\fP, struct passwd *\fIpwd\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct passwd **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetpwuid\fR() +function shall search the user database for an entry with a matching +.IR uid . +.P +The +\fIgetpwuid\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetpwuid\fR(). +If +\fIgetpwuid\fR() +returns a null pointer and +.IR errno +is set to non-zero, an error occurred. +.P +The +\fIgetpwuid_r\fR() +function shall update the +.BR passwd +structure pointed to by +.IR pwd +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the user database with a +matching +.IR uid . +Storage referenced by the structure is allocated from the memory +provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +returns either \(mi1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer shall be returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +The +\fIgetpwuid\fR() +function shall return a pointer to a +.BR "struct passwd" +with the structure as defined in +.IR +with a matching entry if found. A null pointer shall be returned if the +requested entry is not found, or an error occurs. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetpwent\fR(), +\fIgetpwnam\fR(), +or +\fIgetpwuid\fR(). +.P +If successful, the +\fIgetpwuid_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetpwuid\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIgetpwuid_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR passwd +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +may return \(mi1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetpwuid_r\fR(). +.sp +.RS 4 +.nf +\fB +long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct passwd result; +struct passwd *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getpwuid_r(42, &result, buffer, len, &resultp)) =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi \fR +.P +.RE +.SS "Getting an Entry for the Root User" +.P +The following example gets the user database entry for the user with +user ID 0 (root). +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +uid_t id = 0; +struct passwd *pwd; +.P +pwd = getpwuid(id); +.fi \fR +.P +.RE +.SS "Finding the Name for the Effective User ID" +.P +The following example defines +.IR pws +as a pointer to a structure of type +.BR passwd , +which is used to store the structure pointer returned by the call to +the +\fIgetpwuid\fR() +function. The +\fIgeteuid\fR() +function shall return the effective user ID of the calling process; +this is used as the search criteria for the +\fIgetpwuid\fR() +function. The call to +\fIgetpwuid\fR() +shall return a pointer to the structure containing that user ID value. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +struct passwd *pws; +pws = getpwuid(geteuid()); +.fi \fR +.P +.RE +.SS "Finding an Entry in the User Database" +.P +The following example uses +\fIgetpwuid\fR() +to search the user database for a user ID that was previously stored in +a +.BR stat +structure, then prints out the user name if it is found. If the user +is not found, the program prints the numeric value of the user ID for +the entry. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +struct stat statbuf; +struct passwd *pwd; +\&... +if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); +else + printf(" %-8d", statbuf.st_uid); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Three names associated with the current process can be determined: +.IR getpwuid (\c +\fIgeteuid\fR()) +returns the name associated with the effective user ID of the process; +\fIgetlogin\fR() +returns the name associated with the current login activity; and +.IR getpwuid (\c +\fIgetuid\fR()) +returns the name associated with the real user ID of the process. +.P +The +\fIgetpwuid_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \(mi1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETPW_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIgetlogin\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getrlimit.3p b/man-pages-posix-2013-a/man3p/getrlimit.3p new file mode 100644 index 0000000..8ced3f4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getrlimit.3p @@ -0,0 +1,250 @@ +'\" et +.TH GETRLIMIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getrlimit, +setrlimit +\(em control maximum resource consumption +.SH SYNOPSIS +.LP +.nf +#include +.P +int getrlimit(int \fIresource\fP, struct rlimit *\fIrlp\fP); +int setrlimit(int \fIresource\fP, const struct rlimit *\fIrlp\fP); +.fi +.SH DESCRIPTION +The +\fIgetrlimit\fR() +function shall get, and the +\fIsetrlimit\fR() +function shall set, limits on the consumption of a variety of +resources. +.P +Each call to either +\fIgetrlimit\fR() +or +\fIsetrlimit\fR() +identifies a specific resource to be operated upon as well as a +resource limit. A resource limit is represented by an +.BR rlimit +structure. The +.IR rlim_cur +member specifies the current or soft limit and the +.IR rlim_max +member specifies the maximum or hard limit. Soft limits may be changed +by a process to any value that is less than or equal to the hard +limit. A process may (irreversibly) lower its hard limit to any value +that is greater than or equal to the soft limit. Only a process with +appropriate privileges can raise a hard limit. Both hard and soft +limits can be changed in a single call to +\fIsetrlimit\fR() +subject to the constraints described above. +.P +The value RLIM_INFINITY, defined in +.IR , +shall be considered to be larger than any other limit value. If a +call to +\fIgetrlimit\fR() +returns RLIM_INFINITY for a resource, it means the implementation shall +not enforce limits on that resource. Specifying RLIM_INFINITY as any +resource limit value on a successful call to +\fIsetrlimit\fR() +shall inhibit enforcement of that resource limit. +.P +The following resources are defined: +.IP RLIMIT_CORE 14 +This is the maximum size of a +.BR core +file, in bytes, that may be created by a process. A limit of 0 shall +prevent the creation of a +.BR core +file. If this limit is exceeded, the writing of a +.BR core +file shall terminate at this size. +.IP RLIMIT_CPU 14 +This is the maximum amount of CPU time, in seconds, used by a process. +If this limit is exceeded, SIGXCPU shall be generated for the process. If +the process is catching or ignoring SIGXCPU, or all threads belonging +to that process are blocking SIGXCPU, the behavior is unspecified. +.IP RLIMIT_DATA 14 +This is the maximum size of a data segment of the process, in bytes. +If this limit is exceeded, the +\fImalloc\fR() +function shall fail with +.IR errno +set to +.BR [ENOMEM] . +.IP RLIMIT_FSIZE 14 +This is the maximum size of a file, in bytes, that may be created by a +process. If a write or truncate operation would cause this limit to be +exceeded, SIGXFSZ shall be generated for the thread. If the thread is +blocking, or +the process is catching or ignoring SIGXFSZ, continued attempts to +increase the size of a file from end-of-file to beyond the limit +shall fail with +.IR errno +set to +.BR [EFBIG] . +.IP RLIMIT_NOFILE 14 +This is a number one greater than the maximum value that the system may +assign to a newly-created descriptor. If this limit is exceeded, +functions that allocate a file descriptor shall fail with +.IR errno +set to +.BR [EMFILE] . +This limit constrains the number of file descriptors that a process may +allocate. +.IP RLIMIT_STACK 14 +This is the maximum size of the initial thread's stack, in bytes. The +implementation does not automatically grow the stack beyond this +limit. If this limit is exceeded, SIGSEGV shall be generated for the +thread. If the thread is blocking SIGSEGV, or the process is ignoring +or catching SIGSEGV and has not made arrangements to use an alternate +stack, the disposition of SIGSEGV shall be set to SIG_DFL before it is +generated. +.IP RLIMIT_AS 14 +This is the maximum size of total available memory of the process, in +bytes. If this limit is exceeded, the +\fImalloc\fR() +and +\fImmap\fR() +functions shall fail with +.IR errno +set to +.BR [ENOMEM] . +In addition, the automatic stack growth fails with the effects outlined +above. +.P +When using the +\fIgetrlimit\fR() +function, if a resource limit can be represented correctly in an object +of type +.BR rlim_t , +then its representation is returned; otherwise, if the value of the +resource limit is equal to that of the corresponding saved hard limit, +the value returned shall be RLIM_SAVED_MAX; otherwise, the value +returned shall be RLIM_SAVED_CUR. +.P +When using the +\fIsetrlimit\fR() +function, if the requested new limit is RLIM_INFINITY, the new limit +shall be ``no limit''; otherwise, if the +requested new limit is RLIM_SAVED_MAX, the new limit shall be the +corresponding saved hard limit; otherwise, if the requested new limit +is RLIM_SAVED_CUR, the new limit shall be the corresponding saved soft +limit; otherwise, the new limit shall be the requested value. In +addition, if the corresponding saved limit can be represented correctly +in an object of type +.BR rlim_t +then it shall be overwritten with the new limit. +.P +The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR is +unspecified unless a previous call to +\fIgetrlimit\fR() +returned that value as the soft or hard limit for the corresponding +resource limit. +.P +The determination of whether a limit can be correctly represented in an +object of type +.BR rlim_t +is implementation-defined. For example, some implementations permit a +limit whose value is greater than RLIM_INFINITY and others do not. +.P +The +.IR exec +family of functions shall cause resource limits to be saved. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetrlimit\fR() +and +\fIsetrlimit\fR() +shall return 0. Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgetrlimit\fR() +and +\fIsetrlimit\fR() +functions shall fail if: +.TP +.BR EINVAL +An invalid +.IR resource +was specified; or in a +\fIsetrlimit\fR() +call, the new +.IR rlim_cur +exceeds the new +.IR rlim_max . +.TP +.BR EPERM +The limit specified to +\fIsetrlimit\fR() +would have raised the maximum limit value, and the calling process does +not have appropriate privileges. +.P +The +\fIsetrlimit\fR() +function may fail if: +.TP +.BR EINVAL +The limit specified cannot be lowered because current usage is already +higher than the limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If a process attempts to set the hard limit or soft limit for +RLIMIT_NOFILE to less than the value of +{_POSIX_OPEN_MAX} +from +.IR , +unexpected behavior may occur. +.P +If a process attempts to set the hard limit or soft limit for +RLIMIT_NOFILE to less than the highest currently open file descriptor ++1, unexpected behavior may occur. +.SH RATIONALE +It should be noted that RLIMIT_STACK applies ``at least'' to the stack +of the initial thread in the process, and not to the sum of all the +stacks in the process, as that would be very limiting unless the value +is so big as to provide no value at all with a single thread. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getrusage.3p b/man-pages-posix-2013-a/man3p/getrusage.3p new file mode 100644 index 0000000..5635a6f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getrusage.3p @@ -0,0 +1,110 @@ +'\" et +.TH GETRUSAGE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getrusage +\(em get information about resource utilization +.SH SYNOPSIS +.LP +.nf +#include +.P +int getrusage(int \fIwho\fP, struct rusage *\fIr_usage\fP); +.fi +.SH DESCRIPTION +The +\fIgetrusage\fR() +function shall provide measures of the resources used by the current +process or its terminated and waited-for child processes. If the value +of the +.IR who +argument is RUSAGE_SELF, information shall be returned about resources +used by the current process. If the value of the +.IR who +argument is RUSAGE_CHILDREN, +information shall be returned about resources used by the terminated and +waited-for children of the current process. If the child is never +waited for (for example, if the parent has SA_NOCLDWAIT set or sets +SIGCHLD to SIG_IGN), the resource +information for the child process is discarded and not included in the +resource information provided by +\fIgetrusage\fR(). +.P +The +.IR r_usage +argument is a pointer to an object of type +.BR "struct rusage" +in which the returned information is stored. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetrusage\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIgetrusage\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR who +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using getrusage(\|)" +.P +The following example returns information about the resources used by +the current process. +.sp +.RS 4 +.nf +\fB +#include +\&... +int who = RUSAGE_SELF; +struct rusage usage; +int ret; +.P +ret = getrusage(who, &usage); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexit\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/gets.3p b/man-pages-posix-2013-a/man3p/gets.3p new file mode 100644 index 0000000..d97dfda --- /dev/null +++ b/man-pages-posix-2013-a/man3p/gets.3p @@ -0,0 +1,135 @@ +'\" et +.TH GETS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gets +\(em get a string from a +.IR stdin +stream +.SH SYNOPSIS +.LP +.nf +#include +.P +char *gets(char *\fIs\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIgets\fR() +function shall read bytes from the standard input stream, +.IR stdin , +into the array pointed to by +.IR s , +until a + +is read or an end-of-file condition is encountered. Any + +shall be discarded and a null byte shall be placed immediately +after the last byte read into the array. +.P +The +\fIgets\fR() +function may mark the last data access timestamp of +the file associated with +.IR stream +for update. The last data access timestamp shall be +marked for update by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIgets\fR() +shall return +.IR s . +If the end-of-file indicator for the stream is set, or if the stream +is at end-of-file, the end-of-file indicator for the +stream shall be set and +\fIgets\fR() +shall return a null pointer. If a read error occurs, the error indicator +for the stream shall be set, +\fIgets\fR() +shall return a null pointer, +and set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Reading a line that overflows the array pointed to by +.IR s +results in undefined behavior. The use of +\fIfgets\fR() +is recommended. +.P +Since the user cannot specify the length of the buffer passed to +\fIgets\fR(), +use of this function is discouraged. The length of the string read is +unlimited. It is possible to overflow this buffer in such a way as to +cause applications to fail, or possible system security violations. +.P +Applications should use the +\fIfgets\fR() +function instead of the obsolescent +\fIgets\fR() +function. +.SH RATIONALE +The standard developers decided to mark the +\fIgets\fR() +function as obsolescent even though it is in the ISO\ C standard due to the +possibility of buffer overflow. +.SH "FUTURE DIRECTIONS" +The +\fIgets\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getservbyname.3p b/man-pages-posix-2013-a/man3p/getservbyname.3p new file mode 100644 index 0000000..2fe3564 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getservbyname.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETSERVBYNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getservbyname, +getservbyport, +getservent +\(em network services database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +struct servent *getservbyname(const char *\fIname\fP, const char *\fIproto\fP); +struct servent *getservbyport(int \fIport\fP, const char *\fIproto\fP); +struct servent *getservent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendservent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getsid.3p b/man-pages-posix-2013-a/man3p/getsid.3p new file mode 100644 index 0000000..752cc06 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getsid.3p @@ -0,0 +1,86 @@ +'\" et +.TH GETSID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getsid +\(em get the process group ID of a session leader +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getsid(pid_t \fIpid\fP); +.fi +.SH DESCRIPTION +The +\fIgetsid\fR() +function shall obtain the process group ID of the process that is the +session leader of the process specified by +.IR pid . +If +.IR pid +is (\fBpid_t\fR)0, it specifies the calling process. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetsid\fR() +shall return the process group ID of the session leader of the specified +process. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgetsid\fR() +function shall fail if: +.TP +.BR EPERM +The process specified by +.IR pid +is not in the same session as the calling process, and the +implementation does not allow access to the process group ID of the +session leader of that process from the calling process. +.TP +.BR ESRCH +There is no process with a process ID equal to +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getsockname.3p b/man-pages-posix-2013-a/man3p/getsockname.3p new file mode 100644 index 0000000..c2530fe --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getsockname.3p @@ -0,0 +1,121 @@ +'\" et +.TH GETSOCKNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getsockname +\(em get the socket name +.SH SYNOPSIS +.LP +.nf +#include +.P +int getsockname(int \fIsocket\fP, struct sockaddr *restrict \fIaddress\fP, + socklen_t *restrict \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIgetsockname\fR() +function shall retrieve the locally-bound name of the specified socket, +store this address in the +.BR sockaddr +structure pointed to by the +.IR address +argument, and store the length of this address in the object pointed +to by the +.IR address_len +argument. +.P +The +.IR address_len +argument points to a +.BR socklen_t +object which on input specifies the length of the supplied +.BR sockaddr +structure, and on output specifies the length of the stored address. +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. +.P +If the socket has not been bound to a local name, the value stored in +the object pointed to by +.IR address +is unspecified. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned, the +.IR address +argument shall point to the address of the socket, and the +.IR address_len +argument shall point to the length of the address. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIgetsockname\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The operation is not supported for this socket's protocol. +.P +The +\fIgetsockname\fR() +function may fail if: +.TP +.BR EINVAL +The socket has been shut down. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to complete the +function. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIgetpeername\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.br +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getsockopt.3p b/man-pages-posix-2013-a/man3p/getsockopt.3p new file mode 100644 index 0000000..0266a12 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getsockopt.3p @@ -0,0 +1,144 @@ +'\" et +.TH GETSOCKOPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getsockopt +\(em get the socket options +.SH SYNOPSIS +.LP +.nf +#include +.P +int getsockopt(int \fIsocket\fP, int \fIlevel\fP, int \fIoption_name,\fP + void *restrict \fIoption_value\fP, socklen_t *restrict \fIoption_len\fP); +.fi +.SH DESCRIPTION +The +\fIgetsockopt\fR() +function manipulates options associated with a socket. +.P +The +\fIgetsockopt\fR() +function shall retrieve the value for the option specified by the +.IR option_name +argument for the socket specified by the +.IR socket +argument. If the size of the option value is greater than +.IR option_len , +the value stored in the object pointed to by the +.IR option_value +argument shall be silently truncated. Otherwise, the object pointed to +by the +.IR option_len +argument shall be modified to indicate the actual length of the value. +.P +The +.IR level +argument specifies the protocol level at which the option resides. To +retrieve options at the socket level, specify the +.IR level +argument as SOL_SOCKET. To retrieve options at other levels, supply the +appropriate level identifier for the protocol controlling the option. +For example, to indicate that an option is interpreted by the TCP +(Transmission Control Protocol), set +.IR level +to IPPROTO_TCP as defined in the +.IR +header. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIgetsockopt\fR() +function. +.P +The +.IR option_name +argument specifies a single option to be retrieved. It can be one of +the socket-level options defined in +.IR "\fB\fP" +and described in +.IR "Section 2.10.16" ", " "Use of Options". +.SH "RETURN VALUE" +Upon successful completion, +\fIgetsockopt\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIgetsockopt\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EINVAL +The specified option is invalid at the specified socket level. +.TP +.BR ENOPROTOOPT +.br +The option is not supported by the protocol. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.P +The +\fIgetsockopt\fR() +function may fail if: +.TP +.BR EACCES +The calling process does not have appropriate privileges. +.TP +.BR EINVAL +The socket has been shut down. +.TP +.BR ENOBUFS +Insufficient resources are available in the system to complete the +function. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.10.16" ", " "Use of Options", +.IR "\fIbind\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIendprotoent\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getsubopt.3p b/man-pages-posix-2013-a/man3p/getsubopt.3p new file mode 100644 index 0000000..3cff22e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getsubopt.3p @@ -0,0 +1,296 @@ +'\" et +.TH GETSUBOPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getsubopt +\(em parse suboption arguments from a string +.SH SYNOPSIS +.LP +.nf +#include +.P +int getsubopt(char **\fIoptionp\fP, char * const *\fIkeylistp\fP, char **\fIvaluep\fP); +.fi +.SH DESCRIPTION +The +\fIgetsubopt\fR() +function shall parse suboption arguments in a flag argument. Such +options often result from the use of +\fIgetopt\fR(). +.P +The +\fIgetsubopt\fR() +argument +.IR optionp +is a pointer to a pointer to the option argument string. The suboption +arguments shall be separated by + +characters and each may consist of either a single token, or a token-value +pair separated by an +. +.P +The +.IR keylistp +argument shall be a pointer to a vector of strings. The end of the +vector is identified by a null pointer. Each entry in the vector is one +of the possible tokens that might be found in *\fIoptionp\fP. Since + +characters delimit suboption arguments in +.IR optionp , +they should not appear in any of the strings pointed to by +.IR keylistp . +Similarly, because an + +separates a token from its value, the application should not include an + +in any of the strings pointed to by +.IR keylistp . +The +\fIgetsubopt\fR() +function shall not modify the +.IR keylistp +vector. +.P +The +.IR valuep +argument is the address of a value string pointer. +.P +If a + +appears in +.IR optionp , +it shall be interpreted as a suboption separator. After + +characters have been processed, if there are one or more + +characters in a suboption string, the first + +in any suboption string shall be interpreted as a separator between a +token and a value. Subsequent + +characters in a suboption string shall be interpreted as part of the +value. +.P +If the string at *\fIoptionp\fP contains only one suboption argument +(equivalently, no + +characters), +\fIgetsubopt\fR() +shall update *\fIoptionp\fP to point to the null character at the end of +the string. Otherwise, it shall isolate the suboption argument by +replacing the + +separator with a null character, and shall update *\fIoptionp\fP to point +to the start of the next suboption argument. If the suboption argument +has an associated value (equivalently, contains an +), +\fIgetsubopt\fR() +shall update *\fIvaluep\fP to point to the value's first character. +Otherwise, it shall set *\fIvaluep\fP to a null pointer. The calling +application may use this information to determine whether the presence +or absence of a value for the suboption is an error. +.P +Additionally, when +\fIgetsubopt\fR() +fails to match the suboption argument with a token in the +.IR keylistp +array, the calling application should decide if this is an error, or if +the unrecognized option should be processed in another way. +.SH "RETURN VALUE" +The +\fIgetsubopt\fR() +function shall return the index of the matched token string, or \(mi1 +if no token strings were matched. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Parsing Suboptions" +.P +The following example uses the +\fIgetsubopt\fR() +function to parse a +.IR value +argument in the +.IR optarg +external variable returned by a call to +\fIgetopt\fR(). +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +int do_all; +const char *type; +int read_size; +int write_size; +int read_only; +.P +enum +{ + RO_OPTION = 0, + RW_OPTION, + READ_SIZE_OPTION, + WRITE_SIZE_OPTION +}; +.P +const char *mount_opts[] = +{ + [RO_OPTION] = "ro", + [RW_OPTION] = "rw", + [READ_SIZE_OPTION] = "rsize", + [WRITE_SIZE_OPTION] = "wsize", + NULL +}; +.P +int +main(int argc, char *argv[]) +{ + char *subopts, *value; + int opt; +.P + while ((opt = getopt(argc, argv, "at:o:")) != -1) + switch(opt) + { + case 'a': + do_all = 1; + break; + case 't': + type = optarg; + break; + case 'o': + subopts = optarg; + while (*subopts != '\0') + { + char *saved = subopts; + switch(getsubopt(&subopts, (char **)mount_opts, + &value)) + { + case RO_OPTION: + read_only = 1; + break; + case RW_OPTION: + read_only = 0; + break; + case READ_SIZE_OPTION: + if (value == NULL) + abort(); + read_size = atoi(value); + break; + case WRITE_SIZE_OPTION: + if (value == NULL) + abort(); + write_size = atoi(value); + break; + default: + /* Unknown suboption. */ + printf("Unknown suboption `%s'\en", saved); + abort(); + } + } + break; + default: + abort(); + } +.P + /* Do the real work. */ +.P + return 0; +} +.fi \fR +.P +.RE +.P +If the above example is invoked with: +.sp +.RS 4 +.nf +\fB +program -o ro,rsize=512 +.fi \fR +.P +.RE +.P +then after option parsing, the variable +.IR do_all +will be 0, +.IR type +will be a null pointer, +.IR read_size +will be 512, +.IR write_size +will be 0, and +.IR read_only +will be 1. If it is invoked with: +.sp +.RS 4 +.nf +\fB +program -o oops +.fi \fR +.P +.RE +.P +it will print: +.sp +.RS 4 +.nf +\fB +"Unknown suboption `oops'" +.fi \fR +.P +.RE +.P +before aborting. +.SH "APPLICATION USAGE" +The value of *\fIvaluep\fR when +\fIgetsubopt\fR() +returns \(mi1 is unspecified. Historical implementations provide various +incompatible extensions to allow an application to access the suboption +text that was not found in the +.IR keylistp +array. +.SH RATIONALE +The +.IR keylistp +argument of +\fIgetsubopt\fR() +is typed as +.BR "char * const *" +to match historical practice. However, the standard is clear that +implementations will not modify either the array or the strings contained +in the array, as if the argument had been typed +.BR "const char * const *" . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/gettimeofday.3p b/man-pages-posix-2013-a/man3p/gettimeofday.3p new file mode 100644 index 0000000..b0a449a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/gettimeofday.3p @@ -0,0 +1,77 @@ +'\" et +.TH GETTIMEOFDAY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gettimeofday +\(em get the date and time +.SH SYNOPSIS +.LP +.nf +#include +.P +int gettimeofday(struct timeval *restrict \fItp\fP, void *restrict \fItzp\fP); +.fi +.SH DESCRIPTION +The +\fIgettimeofday\fR() +function shall obtain the current time, expressed as seconds and +microseconds since the Epoch, and store it in the +.BR timeval +structure pointed to by +.IR tp . +The resolution of the system clock is unspecified. +.P +If +.IR tzp +is not a null pointer, the behavior is unspecified. +.SH "RETURN VALUE" +The +\fIgettimeofday\fR() +function shall return 0 and no value shall be reserved to indicate +an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications should use the +\fIclock_gettime\fR() +function instead of the obsolescent +\fIgettimeofday\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIgettimeofday\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIctime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getuid.3p b/man-pages-posix-2013-a/man3p/getuid.3p new file mode 100644 index 0000000..6fafbf9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getuid.3p @@ -0,0 +1,85 @@ +'\" et +.TH GETUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getuid +\(em get a real user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +uid_t getuid(void); +.fi +.SH DESCRIPTION +The +\fIgetuid\fR() +function shall return the real user ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetuid\fR() +function shall always be successful and no return value is reserved to +indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Setting the Effective User ID to the Real User ID" +.P +The following example sets the effective user ID and the real user ID +of the current process to the real user ID of the caller. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +setreuid(getuid(), getuid()); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getutxent.3p b/man-pages-posix-2013-a/man3p/getutxent.3p new file mode 100644 index 0000000..e2d55de --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getutxent.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETUTXENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getutxent, +getutxid, +getutxline +\(em get user accounting database entries +.SH SYNOPSIS +.LP +.nf +#include +.P +struct utmpx *getutxent(void); +struct utmpx *getutxid(const struct utmpx *\fIid\fP); +struct utmpx *getutxline(const struct utmpx *\fIline\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendutxent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getwc.3p b/man-pages-posix-2013-a/man3p/getwc.3p new file mode 100644 index 0000000..2024fb8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getwc.3p @@ -0,0 +1,80 @@ +'\" et +.TH GETWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getwc +\(em get a wide character from a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t getwc(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIgetwc\fR() +function shall be equivalent to +\fIfgetwc\fR(), +except that if it is implemented as a macro it may evaluate +.IR stream +more than once, so the argument should never be an expression with +side-effects. +.SH "RETURN VALUE" +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since it may be implemented as a macro, +\fIgetwc\fR() +may treat incorrectly a +.IR stream +argument with side-effects. In particular, +\fIgetwc\fR(*\fIf\fR\(pl\(pl) does not necessarily work as expected. +Therefore, use of this function is not recommended; +\fIfgetwc\fR() +should be used instead. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetwc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/getwchar.3p b/man-pages-posix-2013-a/man3p/getwchar.3p new file mode 100644 index 0000000..9096e17 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/getwchar.3p @@ -0,0 +1,79 @@ +'\" et +.TH GETWCHAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getwchar +\(em get a wide character from a +.IR stdin +stream +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t getwchar(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIgetwchar\fR() +function shall be equivalent to \fIgetwc\fP(\fIstdin\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the +.BR wint_t +value returned by +\fIgetwchar\fR() +is stored into a variable of type +.BR wchar_t +and then compared against the +.BR wint_t +macro WEOF, the result may be incorrect. Only the +.BR wint_t +type is guaranteed to be able to represent any wide character and +WEOF. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetwc\fR\^(\|)", +.IR "\fIgetwc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/glob.3p b/man-pages-posix-2013-a/man3p/glob.3p new file mode 100644 index 0000000..ad08152 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/glob.3p @@ -0,0 +1,448 @@ +'\" et +.TH GLOB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +glob, +globfree +\(em generate pathnames matching a pattern +.SH SYNOPSIS +.LP +.nf +#include +.P +int glob(const char *restrict \fIpattern\fP, int \fIflags\fP, + int(*\fIerrfunc\fP)(const char *\fIepath\fP, int \fIeerrno\fP), + glob_t *restrict \fIpglob\fP); +void globfree(glob_t *\fIpglob\fP); +.fi +.SH DESCRIPTION +The +\fIglob\fR() +function is a pathname generator that shall implement the rules +defined in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.13" ", " "Pattern Matching Notation", +with optional support for rule 3 in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion". +.P +The structure type +.BR glob_t +is defined in +.IR +and includes at least the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +size_t!gl_pathc!Count of paths matched by \fIpattern\fP. +char **!gl_pathv!Pointer to a list of matched pathnames. +size_t!gl_offs!T{ +Slots to reserve at the beginning of \fIgl_pathv\fP. +T} +.TE +.P +The argument +.IR pattern +is a pointer to a pathname pattern to be expanded. The +\fIglob\fR() +function shall match all accessible pathnames against this pattern and +develop a list of all pathnames that match. In order to have access to +a pathname, +\fIglob\fR() +requires search permission on every component of a path except the +last, and read permission on each directory of any filename component +of +.IR pattern +that contains any of the following special characters: +.BR '*' , +.BR '?' , +and +.BR '[' . +.P +The +\fIglob\fR() +function shall store the number of matched pathnames into +\fIpglob\fP\->\fIgl_pathc\fP and a pointer to a list of pointers to +pathnames into \fIpglob\fP\->\fIgl_pathv\fP. The pathnames shall be in +sort order as defined by the current setting of the +.IR LC_COLLATE +category; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.2" ", " "LC_COLLATE". +The first pointer after the last pathname shall be a null pointer. If +the pattern does not match any pathnames, the returned number of matched +paths is set to 0, and the contents of \fIpglob\fP\->\fIgl_pathv\fP +are implementation-defined. +.P +It is the caller's responsibility to create the structure pointed to by +.IR pglob . +The +\fIglob\fR() +function shall allocate other space as needed, including the memory +pointed to by +.IR gl_pathv . +The +\fIglobfree\fR() +function shall free any space associated with +.IR pglob +from a previous call to +\fIglob\fR(). +.P +The +.IR flags +argument is used to control the behavior of +\fIglob\fR(). +The value of +.IR flags +is a bitwise-inclusive OR of zero or more of the following +constants, which are defined in +.IR : +.IP GLOB_APPEND 14 +Append pathnames generated to the ones from a previous call to +\fIglob\fR(). +.IP GLOB_DOOFFS 14 +Make use of \fIpglob\fP\->\fIgl_offs\fP. If this flag is set, +\fIpglob\fP\->\fIgl_offs\fP is used to specify how many null pointers +to add to the beginning of \fIpglob\fP\->\fIgl_pathv\fP. In other +words, \fIpglob\fP\->\fIgl_pathv\fP shall point to +\fIpglob\fP\->\fIgl_offs\fP null pointers, followed by +\fIpglob\fP\->\fIgl_pathc\fP pathname pointers, followed by a null +pointer. +.IP GLOB_ERR 14 +Cause +\fIglob\fR() +to return when it encounters a directory that it cannot open or read. +Ordinarily, +\fIglob\fR() +continues to find matches. +.IP GLOB_MARK 14 +Each pathname that is a directory that matches +.IR pattern +shall have a + +appended. +.IP GLOB_NOCHECK 14 +Supports rule 3 in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion". +If +.IR pattern +does not match any pathname, then +\fIglob\fR() +shall return a list consisting of only +.IR pattern , +and the number of matched pathnames is 1. +.IP GLOB_NOESCAPE 14 +Disable backslash escaping. +.IP GLOB_NOSORT 14 +Ordinarily, +\fIglob\fR() +sorts the matching pathnames according to the current setting of the +.IR LC_COLLATE +category; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.2" ", " "LC_COLLATE". +When this flag is used, the order of pathnames returned is unspecified. +.P +The GLOB_APPEND +flag can be used to append a new set of pathnames to those found in a +previous call to +\fIglob\fR(). +The following rules apply to applications when two or more calls to +\fIglob\fR() +are made with the same value of +.IR pglob +and without intervening calls to +\fIglobfree\fR(): +.IP " 1." 4 +The first such call shall not set GLOB_APPEND. All subsequent calls +shall set it. +.IP " 2." 4 +All the calls shall set GLOB_DOOFFS, or all shall not set it. +.IP " 3." 4 +After the second call, \fIpglob\fP\->\fIgl_pathv\fP points to a list +containing the following: +.RS 4 +.IP " a." 4 +Zero or more null pointers, as specified by GLOB_DOOFFS and +\fIpglob\fP\->\fIgl_offs\fP. +.IP " b." 4 +Pointers to the pathnames that were in the +\fIpglob\fP\->\fIgl_pathv\fP list before the call, in the same order +as before. +.IP " c." 4 +Pointers to the new pathnames generated by the second call, in the +specified order. +.RE +.IP " 4." 4 +The count returned in \fIpglob\fP\->\fIgl_pathc\fP shall be the total +number of pathnames from the two calls. +.IP " 5." 4 +The application can change any of the fields after a call to +\fIglob\fR(). +If it does, the application shall reset them to the original value +before a subsequent call, using the same +.IR pglob +value, to +\fIglobfree\fR() +or +\fIglob\fR() +with the GLOB_APPEND flag. +.P +If, during the search, a directory is encountered that cannot be opened +or read and +.IR errfunc +is not a null pointer, +\fIglob\fR() +calls +\fI(\fR()*errfunc ) +with two arguments: +.IP " 1." 4 +The +.IR epath +argument is a pointer to the path that failed. +.IP " 2." 4 +The +.IR eerrno +argument is the value of +.IR errno +from the failure, as set by +\fIopendir\fR(), +\fIreaddir\fR(), +or +\fIstat\fR(). +(Other values may be used to report other errors not explicitly +documented for those functions.) +.P +If +\fI(\fR()*errfunc ) +is called and returns non-zero, or if the GLOB_ERR flag is set in +.IR flags , +\fIglob\fR() +shall stop the scan and return GLOB_ABORTED after setting +.IR gl_pathc +and +.IR gl_pathv +in +.IR pglob +to reflect the paths already scanned. If GLOB_ERR is not set and +either +.IR errfunc +is a null pointer or +\fI(\fR()*errfunc ) +returns 0, the error shall be ignored. +.P +The +\fIglob\fR() +function shall not fail because of large files. +.SH "RETURN VALUE" +Upon successful completion, +\fIglob\fR() +shall return 0. The argument \fIpglob\fP\->\fIgl_pathc\fP shall +return the number of matched pathnames and the argument +\fIpglob\fP\->\fIgl_pathv\fP shall contain a pointer to a +null-terminated list of matched and sorted pathnames. However, if +\fIpglob\fP\->\fIgl_pathc\fP is 0, the content of +\fIpglob\fP\->\fIgl_pathv\fP is undefined. +.P +The +\fIglobfree\fR() +function shall not return a value. +.P +If +\fIglob\fR() +terminates due to an error, it shall return one of the non-zero +constants defined in +.IR . +The arguments \fIpglob\fP\->\fIgl_pathc\fP and +\fIpglob\fP\->\fIgl_pathv\fP are still set as defined above. +.SH ERRORS +The +\fIglob\fR() +function shall fail and return the corresponding value if: +.IP GLOB_ABORTED 14 +The scan was stopped because GLOB_ERR was set or +\fI(\fR()*errfunc ) +returned non-zero. +.IP GLOB_NOMATCH 14 +The pattern does not match any existing pathname, and GLOB_NOCHECK was +not set in flags. +.IP GLOB_NOSPACE 14 +An attempt to allocate memory failed. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +One use of the GLOB_DOOFFS flag is by applications that +build an argument list for use with +\fIexecv\fR(), +\fIexecve\fR(), +or +\fIexecvp\fR(). +Suppose, for example, that an application wants to do the equivalent of: +.sp +.RS 4 +.nf +\fB +ls -l *.c +.fi \fR +.P +.RE +.P +but for some reason: +.sp +.RS 4 +.nf +\fB +system("ls -l *.c") +.fi \fR +.P +.RE +.P +is not acceptable. The application could obtain approximately the same +result using the sequence: +.sp +.RS 4 +.nf +\fB +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +globbuf.gl_pathv[0] = "ls"; +globbuf.gl_pathv[1] = "-l"; +execvp("ls", &globbuf.gl_pathv[0]); +.fi \fR +.P +.RE +.P +Using the same example: +.sp +.RS 4 +.nf +\fB +ls -l *.c *.h +.fi \fR +.P +.RE +.P +could be approximately simulated using GLOB_APPEND as follows: +.sp +.RS 4 +.nf +\fB +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +This function is not provided for the purpose of enabling utilities to +perform pathname expansion on their arguments, as this operation is +performed by the shell, and utilities are explicitly not expected to +redo this. Instead, it is provided for applications that need to do +pathname expansion on strings obtained from other sources, such as a +pattern typed by a user or read from a file. +.P +If a utility needs to see if a pathname matches a given pattern, it can +use +\fIfnmatch\fR(). +.P +Note that +.IR gl_pathc +and +.IR gl_pathv +have meaning even if +\fIglob\fR() +fails. This allows +\fIglob\fR() +to report partial results in the event of an error. However, if +.IR gl_pathc +is 0, +.IR gl_pathv +is unspecified even if +\fIglob\fR() +did not return an error. +.P +The GLOB_NOCHECK option could be used when an application wants to +expand a pathname if wildcards are specified, but wants to treat the +pattern as just a string otherwise. The +.IR sh +utility might use this for option-arguments, for example. +.P +The new pathnames generated by a subsequent call with GLOB_APPEND are +not sorted together with the previous pathnames. This mirrors the way +that the shell handles pathname expansion when multiple expansions are +done on a command line. +.P +Applications that need tilde and parameter expansion should use +\fIwordexp\fR(). +.SH RATIONALE +It was claimed that the GLOB_DOOFFS flag is unnecessary because it +could be simulated using: +.sp +.RS 4 +.nf +\fB +new = (char **)malloc((n + pglob->gl_pathc + 1) + * sizeof(char *)); +(void) memcpy(new+n, pglob->gl_pathv, + pglob->gl_pathc * sizeof(char *)); +(void) memset(new, 0, n * sizeof(char *)); +free(pglob->gl_pathv); +pglob->gl_pathv = new; +.fi \fR +.P +.RE +.P +However, this assumes that the memory pointed to by +.IR gl_pathv +is a block that was separately created using +\fImalloc\fR(). +This is not necessarily the case. An application should make no +assumptions about how the memory referenced by fields in +.IR pglob +was allocated. It might have been obtained from +\fImalloc\fR() +in a large chunk and then carved up within +\fIglob\fR(), +or it might have been created using a different memory allocator. It +is not the intent of the standard developers to specify or imply how +the memory used by +\fIglob\fR() +is managed. +.P +The GLOB_APPEND flag would be used when an application wants to expand +several different patterns into a single list. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfnmatch\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "Section 2.6" ", " "Word Expansions" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.2" ", " "LC_COLLATE", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/gmtime.3p b/man-pages-posix-2013-a/man3p/gmtime.3p new file mode 100644 index 0000000..9943ae8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/gmtime.3p @@ -0,0 +1,152 @@ +'\" et +.TH GMTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gmtime, +gmtime_r +\(em convert a time value to a broken-down UTC time +.SH SYNOPSIS +.LP +.nf +#include +.P +struct tm *gmtime(const time_t *\fItimer\fP); +struct tm *gmtime_r(const time_t *restrict \fItimer\fP, + struct tm *restrict \fIresult\fP); +.fi +.SH DESCRIPTION +For +\fIgmtime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIgmtime\fR() +function shall convert the time in seconds since the Epoch pointed to by +.IR timer +into a broken-down time, expressed as Coordinated Universal Time +(UTC). +.P +The relationship between a time in seconds since the Epoch used as an +argument to +\fIgmtime\fR() +and the +.BR tm +structure (defined in the +.IR +header) is that the result shall be as specified in the expression +given in the definition of seconds since the Epoch (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch"), +where the names in the structure and in the expression correspond. +.P +The same relationship shall apply for +\fIgmtime_r\fR(). +.P +The +\fIgmtime\fR() +function need not be thread-safe. +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of type +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIgmtime_r\fR() +function shall convert the time in seconds since the Epoch pointed to by +.IR timer +into a broken-down time expressed as Coordinated Universal Time (UTC). +The broken-down time is stored in the structure referred to by +.IR result . +The +\fIgmtime_r\fR() +function shall also return the address of the same structure. +.SH "RETURN VALUE" +Upon successful completion, the +\fIgmtime\fR() +function shall return a pointer to a +.BR "struct tm" . +If an error is detected, +\fIgmtime\fR() +shall return a null pointer +and set +.IR errno +to indicate the error. +.P +Upon successful completion, +\fIgmtime_r\fR() +shall return the address of the structure pointed to by the argument +.IR result . +If an error is detected, +\fIgmtime_r\fR() +shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgmtime\fR() +and +\fIgmtime_r\fR() +functions shall fail if: +.TP +.BR EOVERFLOW +The result cannot be represented. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIgmtime_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/grantpt.3p b/man-pages-posix-2013-a/man3p/grantpt.3p new file mode 100644 index 0000000..227e71d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/grantpt.3p @@ -0,0 +1,93 @@ +'\" et +.TH GRANTPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +grantpt +\(em grant access to the slave pseudo-terminal device +.SH SYNOPSIS +.LP +.nf +#include +.P +int grantpt(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIgrantpt\fR() +function shall change the mode and ownership of the slave pseudo-terminal +device associated with its master pseudo-terminal counterpart. The +.IR fildes +argument is a file descriptor that refers to a master +pseudo-terminal device. The user ID of the slave shall be set to the real +UID of the calling process and the group ID shall be set to an unspecified +group ID. The permission mode of the slave pseudo-terminal shall be set to +readable and writable by the owner, and writable by the group. +.P +The behavior of the +\fIgrantpt\fR() +function is unspecified if the application has installed a signal +handler to catch SIGCHLD signals. +.SH "RETURN VALUE" +Upon successful completion, +\fIgrantpt\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgrantpt\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument is not associated with a master pseudo-terminal device. +.TP +.BR EACCES +The corresponding slave pseudo-terminal device could not be accessed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIposix_openpt\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_openpt\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/hcreate.3p b/man-pages-posix-2013-a/man3p/hcreate.3p new file mode 100644 index 0000000..f989f19 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/hcreate.3p @@ -0,0 +1,211 @@ +'\" et +.TH HCREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +hcreate, +hdestroy, +hsearch +\(em manage hash search table +.SH SYNOPSIS +.LP +.nf +#include +.P +int hcreate(size_t \fInel\fP); +void hdestroy(void); +ENTRY *hsearch(ENTRY \fIitem\fP, ACTION \fIaction\fP); +.fi +.SH DESCRIPTION +The +\fIhcreate\fR(), +\fIhdestroy\fR(), +and +\fIhsearch\fR() +functions shall manage hash search tables. +.P +The +\fIhcreate\fR() +function shall allocate sufficient space for the table, and the +application shall ensure it is called before +\fIhsearch\fR() +is used. The +.IR nel +argument is an estimate of the maximum number of entries that the table +shall contain. This number may be adjusted upward by the algorithm in +order to obtain certain mathematically favorable circumstances. +.P +The +\fIhdestroy\fR() +function shall dispose of the search table, and may be followed by +another call to +\fIhcreate\fR(). +After the call to +\fIhdestroy\fR(), +the data can no longer be considered accessible. +.P +The +\fIhsearch\fR() +function is a hash-table search routine. It shall return a pointer into a +hash table indicating the location at which an entry can be found. The +.IR item +argument is a structure of type +.BR ENTRY +(defined in the +.IR +header) containing two pointers: +.IR item.key +points to the comparison key (a +.BR "char *" ), +and +.IR item.data +(a +.BR "void *" ) +points to any other data to be associated with that key. The +comparison function used by +\fIhsearch\fR() +is +\fIstrcmp\fR(). +The +.IR action +argument is a member of an enumeration type +.BR ACTION +indicating the disposition of the entry if it cannot be found in the +table. ENTER indicates that the item should be inserted in the table +at an appropriate point. FIND indicates that no entry should be made. +Unsuccessful resolution is indicated by the return of a null pointer. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +The +\fIhcreate\fR() +function shall return 0 if it cannot allocate sufficient space for the +table; otherwise, it shall return non-zero. +.P +The +\fIhdestroy\fR() +function shall not return a value. +.P +The +\fIhsearch\fR() +function shall return a null pointer if either the action is FIND and +the item could not be found or the action is ENTER and the table is +full. +.SH ERRORS +The +\fIhcreate\fR() +and +\fIhsearch\fR() +functions may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following example reads in strings followed by two numbers and +stores them in a hash table, discarding duplicates. It then reads in +strings and finds the matching entry in the hash table and prints it +out. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +struct info { /* This is the info stored in the table */ + int age, room; /* other than the key. */ +}; +.P +#define NUM_EMPL 5000 /* # of elements in search table. */ +.P +int main(void) +{ + char string_space[NUM_EMPL*20]; /* Space to store strings. */ + struct info info_space[NUM_EMPL]; /* Space to store employee info. */ + char *str_ptr = string_space; /* Next space in string_space. */ + struct info *info_ptr = info_space; + /* Next space in info_space. */ + ENTRY item; + ENTRY *found_item; /* Name to look for in table. */ + char name_to_find[30]; +.P + int i = 0; +.P + /* Create table; no error checking is performed. */ + (void) hcreate(NUM_EMPL); + while (scanf("%s%d%d", str_ptr, &info_ptr\(mi>age, + &info_ptr\(mi>room) != EOF && i++ < NUM_EMPL) { +.P + /* Put information in structure, and structure in item. */ + item.key = str_ptr; + item.data = info_ptr; + str_ptr += strlen(str_ptr) + 1; + info_ptr++; +.P + /* Put item into table. */ + (void) hsearch(item, ENTER); + } +.P + /* Access table. */ + item.key = name_to_find; + while (scanf("%s", item.key) != EOF) { + if ((found_item = hsearch(item, FIND)) != NULL) { +.P + /* If item is in the table. */ + (void)printf("found %s, age = %d, room = %d\en", + found_item\(mi>key, + ((struct info *)found_item\(mi>data)\(mi>age, + ((struct info *)found_item\(mi>data)\(mi>room); + } else + (void)printf("no such employee %s\en", name_to_find); + } + return 0; +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIhcreate\fR() +and +\fIhsearch\fR() +functions may use +\fImalloc\fR() +to allocate space. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbsearch\fR\^(\|)", +.IR "\fIlsearch\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fItdelete\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/htonl.3p b/man-pages-posix-2013-a/man3p/htonl.3p new file mode 100644 index 0000000..cb78329 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/htonl.3p @@ -0,0 +1,90 @@ +'\" et +.TH HTONL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +htonl, +htons, +ntohl, +ntohs +\(em convert values between host and network byte order +.SH SYNOPSIS +.LP +.nf +#include +.P +uint32_t htonl(uint32_t \fIhostlong\fP); +uint16_t htons(uint16_t \fIhostshort\fP); +uint32_t ntohl(uint32_t \fInetlong\fP); +uint16_t ntohs(uint16_t \fInetshort\fP); +.fi +.SH DESCRIPTION +These functions shall convert 16-bit and 32-bit quantities between +network byte order and host byte order. +.P +On some implementations, these functions are defined as macros. +.P +The +.BR uint32_t +and +.BR uint16_t +types are defined in +.IR . +.SH "RETURN VALUE" +The +\fIhtonl\fR() +and +\fIhtons\fR() +functions shall return the argument value converted from host to +network byte order. +.P +The +\fIntohl\fR() +and +\fIntohs\fR() +functions shall return the argument value converted from network to +host byte order. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +These functions are most often used in conjunction with IPv4 addresses +and ports as returned by +\fIgethostent\fR() +and +\fIgetservent\fR(). +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendhostent\fR\^(\|)", +.IR "\fIendservent\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/hypot.3p b/man-pages-posix-2013-a/man3p/hypot.3p new file mode 100644 index 0000000..ac67427 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/hypot.3p @@ -0,0 +1,156 @@ +'\" et +.TH HYPOT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +hypot, +hypotf, +hypotl +\(em Euclidean distance function +.SH SYNOPSIS +.LP +.nf +#include +.P +double hypot(double \fIx\fP, double \fIy\fP); +float hypotf(float \fIx\fP, float \fIy\fP); +long double hypotl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the value of the square root of +.IR x \s-3\u2\d\s+3+\c +.IR y \s-3\u2\d\s+3 +without undue overflow or underflow. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the length of +the hypotenuse of a right-angled triangle with sides of length +.IR x +and +.IR y . +.P +If the correct value would cause overflow, a range error shall occur +and +\fIhypot\fR(), +\fIhypotf\fR(), +and +\fIhypotl\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If +.IR x +or +.IR y +is \(+-Inf, +Inf shall be returned (even if one of +.IR x +or +.IR y +is NaN). +.P +If +.IR x +or +.IR y +is NaN, and the other is not \(+-Inf, a NaN shall be returned. +.P +If both arguments are subnormal and the correct result is subnormal, +a range error may occur and the correct result shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +See the EXAMPLES section in +\fIatan2\fR(). +.SH "APPLICATION USAGE" +\fIhypot\fR(\fIx\fR,\fIy\fR), \fIhypot\fR(\fIy\fR,\fIx\fR), and +\fIhypot\fR(\fIx\fR, \(mi\fIy\fR) are equivalent. +.P +\fIhypot\fR(\fIx\fR, \(+-0) is equivalent to \fIfabs\fR(\fIx\fR). +.P +Underflow only happens when both +.IR x +and +.IR y +are subnormal and the (inexact) result is also subnormal. +.P +These functions take precautions against overflow during intermediate +steps of the computation. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatan2\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsqrt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iconv.3p b/man-pages-posix-2013-a/man3p/iconv.3p new file mode 100644 index 0000000..a7c14b5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iconv.3p @@ -0,0 +1,235 @@ +'\" et +.TH ICONV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iconv +\(em codeset conversion function +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t iconv(iconv_t \fIcd\fP, char **restrict \fIinbuf\fP, + size_t *restrict \fIinbytesleft\fP, char **restrict \fIoutbuf\fP, + size_t *restrict \fIoutbytesleft\fP); +.fi +.SH DESCRIPTION +The +\fIiconv\fR() +function shall convert the sequence of characters from one codeset, +in the array specified by +.IR inbuf , +into a sequence of corresponding characters in another codeset, in the +array specified by +.IR outbuf . +The codesets are those specified in the +\fIiconv_open\fR() +call that returned the conversion descriptor, +.IR cd . +The +.IR inbuf +argument points to a variable that points to the first character in the +input buffer and +.IR inbytesleft +indicates the number of bytes to the end of the buffer to be +converted. The +.IR outbuf +argument points to a variable that points to the first available byte +in the output buffer and +.IR outbytesleft +indicates the number of the available bytes to the end of the buffer. +.P +For state-dependent encodings, the conversion descriptor +.IR cd +is placed into its initial shift state by a call for which +.IR inbuf +is a null pointer, or for which +.IR inbuf +points to a null pointer. When +\fIiconv\fR() +is called in this way, and if +.IR outbuf +is not a null pointer or a pointer to a null pointer, and +.IR outbytesleft +points to a positive value, +\fIiconv\fR() +shall place, into the output buffer, the byte sequence to change the +output buffer to its initial shift state. If the output buffer is not +large enough to hold the entire reset sequence, +\fIiconv\fR() +shall fail and set +.IR errno +to +.BR [E2BIG] . +Subsequent calls with +.IR inbuf +as other than a null pointer or a pointer to a null pointer cause the +conversion to take place from the current state of the conversion +descriptor. +.P +If a sequence of input bytes does not form a valid character in the +specified codeset, conversion shall stop after the previous +successfully converted character. If the input buffer ends with an +incomplete character or shift sequence, conversion shall stop after the +previous successfully converted bytes. If the output buffer is not +large enough to hold the entire converted input, conversion shall stop +just prior to the input bytes that would cause the output buffer to +overflow. The variable pointed to by +.IR inbuf +shall be updated to point to the byte following the last byte +successfully used in the conversion. The value pointed to by +.IR inbytesleft +shall be decremented to reflect the number of bytes still not converted +in the input buffer. The variable pointed to by +.IR outbuf +shall be updated to point to the byte following the last byte of +converted output data. The value pointed to by +.IR outbytesleft +shall be decremented to reflect the number of bytes still available in +the output buffer. For state-dependent encodings, the conversion +descriptor shall be updated +to reflect the shift state in effect at the end of the last +successfully converted byte sequence. +.P +If +\fIiconv\fR() +encounters a character in the input buffer that is valid, but for which +an identical character does not exist in the target codeset, +\fIiconv\fR() +shall perform an implementation-defined conversion on this character. +.SH "RETURN VALUE" +The +\fIiconv\fR() +function shall update the variables pointed to by the arguments to +reflect the extent of the conversion and return the number of +non-identical conversions performed. If the entire string in the input +buffer is converted, the value pointed to by +.IR inbytesleft +shall be 0. If the input conversion is stopped due to any conditions +mentioned above, the value pointed to by +.IR inbytesleft +shall be non-zero and +.IR errno +shall be set to indicate the condition. If an error occurs, +\fIiconv\fR() +shall return (\fBsize_t\fP)\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIiconv\fR() +function shall fail if: +.TP +.BR EILSEQ +Input conversion stopped due to an input byte that does not belong to +the input codeset. +.TP +.BR E2BIG +Input conversion stopped due to lack of space in the output buffer. +.TP +.BR EINVAL +Input conversion stopped due to an incomplete character or shift +sequence at the end of the input buffer. +.P +The +\fIiconv\fR() +function may fail if: +.TP +.BR EBADF +The +.IR cd +argument is not a valid open conversion descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +.IR inbuf +argument indirectly points to the memory area which contains the +conversion input data. The +.IR outbuf +argument indirectly points to the memory area which is to contain the +result of the conversion. The objects indirectly pointed to by +.IR inbuf +and +.IR outbuf +are not restricted to containing data that is directly representable in +the ISO\ C standard language +.BR char +data type. The type of +.IR inbuf +and +.IR outbuf , +.BR "char **" , +does not imply that the objects pointed to are interpreted as +null-terminated C strings or arrays of characters. Any interpretation +of a byte sequence that represents a character in a given character set +encoding scheme is done internally within the codeset converters. For +example, the area pointed to indirectly by +.IR inbuf +and/or +.IR outbuf +can contain all zero octets that are not interpreted as string +terminators but as coded character data according to the respective +codeset encoding scheme. The type of the data (\c +.BR char , +.BR short , +.BR long , +and so on) read or stored in the objects is not specified, but may be +inferred for both the input and output data by the converters +determined by the +.IR fromcode +and +.IR tocode +arguments of +\fIiconv_open\fR(). +.P +Regardless of the data type inferred by the converter, the size of the +remaining space in both input and output objects (the +.IR intbytesleft +and +.IR outbytesleft +arguments) is always measured in bytes. +.P +For implementations that support the conversion of state-dependent +encodings, the conversion descriptor must be able to accurately reflect +the shift-state in effect at the end of the last successful +conversion. It is not required that the conversion descriptor itself +be updated, which would require it to be a pointer type. Thus, +implementations are free to implement the descriptor as a handle (other +than a pointer type) by which the conversion information can be +accessed and updated. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv_open\fR\^(\|)", +.IR "\fIiconv_close\fR\^(\|)", +.IR "\fImbsrtowcs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iconv_close.3p b/man-pages-posix-2013-a/man3p/iconv_close.3p new file mode 100644 index 0000000..dd04975 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iconv_close.3p @@ -0,0 +1,74 @@ +'\" et +.TH ICONV_CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iconv_close +\(em codeset conversion deallocation function +.SH SYNOPSIS +.LP +.nf +#include +.P +int iconv_close(iconv_t \fIcd\fP); +.fi +.SH DESCRIPTION +The +\fIiconv_close\fR() +function shall deallocate the conversion descriptor +.IR cd +and all other associated resources allocated by +\fIiconv_open\fR(). +.P +If a file descriptor is used to implement the type +.BR iconv_t , +that file descriptor shall be closed. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIiconv_close\fR() +function may fail if: +.TP +.BR EBADF +The conversion descriptor is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv\fR\^(\|)", +.IR "\fIiconv_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iconv_open.3p b/man-pages-posix-2013-a/man3p/iconv_open.3p new file mode 100644 index 0000000..f6d5536 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iconv_open.3p @@ -0,0 +1,124 @@ +'\" et +.TH ICONV_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iconv_open +\(em codeset conversion allocation function +.SH SYNOPSIS +.LP +.nf +#include +.P +iconv_t iconv_open(const char *\fItocode\fP, const char *\fIfromcode\fP); +.fi +.SH DESCRIPTION +The +\fIiconv_open\fR() +function shall return a conversion descriptor +that describes a conversion from the codeset specified by the string +pointed to by the +.IR fromcode +argument to the codeset specified by the string pointed to by the +.IR tocode +argument. For state-dependent encodings, the conversion descriptor +shall be in a codeset-dependent initial shift state, ready for +immediate use with +\fIiconv\fR(). +.P +Settings of +.IR fromcode +and +.IR tocode +and their permitted combinations are implementation-defined. +.P +A conversion descriptor shall remain valid until it is closed by +\fIiconv_close\fR() +or an implicit close. +.P +If a file descriptor is used to implement conversion descriptors, the +FD_CLOEXEC flag shall be set; see +.IR . +.SH "RETURN VALUE" +Upon successful completion, +\fIiconv_open\fR() +shall return a conversion descriptor for use on subsequent calls to +\fIiconv\fR(). +Otherwise, +\fIiconv_open\fR() +shall return (\fBiconv_t\fP)\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIiconv_open\fR() +function may fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +Too many files are currently open in the system. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR EINVAL +The conversion specified by +.IR fromcode +and +.IR tocode +is not supported by the implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Some implementations of +\fIiconv_open\fR() +use +\fImalloc\fR() +to allocate space for internal buffer areas. The +\fIiconv_open\fR() +function may fail if there is insufficient storage space to accommodate +these buffers. +.P +Conforming applications must assume that conversion descriptors are not +valid after a call to one of the +.IR exec +functions. +.P +Application developers should consult the system documentation to +determine the supported codesets and their naming schemes. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv\fR\^(\|)", +.IR "\fIiconv_close\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/if_freenameindex.3p b/man-pages-posix-2013-a/man3p/if_freenameindex.3p new file mode 100644 index 0000000..d04be2b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/if_freenameindex.3p @@ -0,0 +1,72 @@ +'\" et +.TH IF_FREENAMEINDEX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +if_freenameindex +\(em free memory allocated by if_nameindex +.SH SYNOPSIS +.LP +.nf +#include +.P +void if_freenameindex(struct if_nameindex *\fIptr\fP); +.fi +.SH DESCRIPTION +The +\fIif_freenameindex\fR() +function shall free the memory allocated by +\fIif_nameindex\fR(). +The +.IR ptr +argument shall be a pointer that was returned by +\fIif_nameindex\fR(). +After +\fIif_freenameindex\fR() +has been called, the application shall not use the array of which +.IR ptr +is the address. +.SH "RETURN VALUE" +None. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIif_indextoname\fR\^(\|)", +.IR "\fIif_nameindex\fR\^(\|)", +.IR "\fIif_nametoindex\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/if_indextoname.3p b/man-pages-posix-2013-a/man3p/if_indextoname.3p new file mode 100644 index 0000000..eb34a00 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/if_indextoname.3p @@ -0,0 +1,82 @@ +'\" et +.TH IF_INDEXTONAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +if_indextoname +\(em map a network interface index to its corresponding name +.SH SYNOPSIS +.LP +.nf +#include +.P +char *if_indextoname(unsigned \fIifindex\fP, char *\fIifname\fP); +.fi +.SH DESCRIPTION +The +\fIif_indextoname\fR() +function shall map an interface index to its corresponding name. +.P +When this function is called, +.IR ifname +shall point to a buffer of at least +{IF_NAMESIZE} +bytes. The function shall place in this buffer the name of the interface +with index +.IR ifindex . +.SH "RETURN VALUE" +If +.IR ifindex +is an interface index, then the function shall return the value supplied in +.IR ifname , +which points to a buffer now containing the interface name. Otherwise, +the function shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIif_indextoname\fR() +function shall fail if: +.TP +.BR ENXIO +The interface does not exist. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIif_freenameindex\fR\^(\|)", +.IR "\fIif_nameindex\fR\^(\|)", +.IR "\fIif_nametoindex\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/if_nameindex.3p b/man-pages-posix-2013-a/man3p/if_nameindex.3p new file mode 100644 index 0000000..36b3b2c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/if_nameindex.3p @@ -0,0 +1,82 @@ +'\" et +.TH IF_NAMEINDEX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +if_nameindex +\(em return all network interface names and indexes +.SH SYNOPSIS +.LP +.nf +#include +.P +struct if_nameindex *\fIif_nameindex\fP(void); +.fi +.SH DESCRIPTION +The +\fIif_nameindex\fR() +function shall return an array of +.IR if_nameindex +structures, one structure per interface. The end of the array is +indicated by a structure with an +.IR if_index +field of zero and an +.IR if_name +field of NULL. +.P +Applications should call +\fIif_freenameindex\fR() +to release the memory that may be dynamically allocated by this +function, after they have finished using it. +.SH "RETURN VALUE" +An array of structures identifying local interfaces. A null pointer is +returned upon an error, with +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIif_nameindex\fR() +function may fail if: +.TP +.BR ENOBUFS +Insufficient resources are available to complete the function. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIif_freenameindex\fR\^(\|)", +.IR "\fIif_indextoname\fR\^(\|)", +.IR "\fIif_nametoindex\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/if_nametoindex.3p b/man-pages-posix-2013-a/man3p/if_nametoindex.3p new file mode 100644 index 0000000..5b44d03 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/if_nametoindex.3p @@ -0,0 +1,65 @@ +'\" et +.TH IF_NAMETOINDEX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +if_nametoindex +\(em map a network interface name to its corresponding index +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned if_nametoindex(const char *\fIifname\fP); +.fi +.SH DESCRIPTION +The +\fIif_nametoindex\fR() +function shall return the interface index corresponding to name +.IR ifname . +.SH "RETURN VALUE" +The corresponding index if +.IR ifname +is the name of an interface; otherwise, zero. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIif_freenameindex\fR\^(\|)", +.IR "\fIif_indextoname\fR\^(\|)", +.IR "\fIif_nameindex\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ilogb.3p b/man-pages-posix-2013-a/man3p/ilogb.3p new file mode 100644 index 0000000..386ce58 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ilogb.3p @@ -0,0 +1,193 @@ +'\" et +.TH ILOGB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.EQ +delim $$ +.EN +.SH NAME +ilogb, +ilogbf, +ilogbl +\(em return an unbiased exponent +.SH SYNOPSIS +.LP +.nf +#include +.P +int ilogb(double \fIx\fP); +int ilogbf(float \fIx\fP); +int ilogbl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall return the exponent part of their argument +.IR x . +Formally, the return value is the integral part of $log sub{r}|x|$ as a +signed integral value, for non-zero +.IR x , +where +.IR r +is the radix of the machine's floating-point arithmetic, which is the +value of FLT_RADIX defined in +.IR . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the exponent +part of +.IR x +as a signed integer value. They are equivalent to calling the +corresponding +\fIlogb\fR() +function and casting the returned value to type +.BR int . +.P +If +.IR x +is 0, the value FP_ILOGB0 shall be returned. +On XSI-conformant systems, a domain error shall occur; +.br +otherwise, a +domain +error may occur. +.P +If +.IR x +is \(+-Inf, the value +{INT_MAX} +shall be returned. +On XSI-conformant systems, a domain error shall occur; +.br +otherwise, a +domain +error may occur. +.P +If +.IR x +is a NaN, the value FP_ILOGBNAN shall be returned. +On XSI-conformant systems, a domain error shall occur; +.br +otherwise, a +domain +error may occur. +.P +If the correct value is greater than +{INT_MAX}, +a domain error shall occur and +an unspecified value shall be returned. +On XSI-conformant systems, a domain error shall occur and +{INT_MAX} +shall be returned. +.P +If the correct value is less than +{INT_MIN}, +a domain error shall occur and +an unspecified value shall be returned. +On XSI-conformant systems, a domain error shall occur and +{INT_MIN} +shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +The +.IR x +argument is zero, NaN, or \(+-Inf. +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is zero, NaN, or \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +The errors come from taking the expected floating-point value and +converting it to +.BR int , +which is an invalid operation in IEEE\ Std\ 754\(hy1985 (since overflow, infinity, and +NaN are not representable in a type +.BR int ), +so should be a domain error. +.P +There are no known implementations that overflow. For overflow to +happen, +{INT_MAX} +must be less than LDBL_MAX_EXP*\fIlog2\fP(FLT_RADIX) or +{INT_MIN} +must be greater than LDBL_MIN_EXP*\fIlog2\fP(FLT_RADIX) if subnormals +are not supported, or +{INT_MIN} +must be greater than (LDBL_MIN_EXP-LDBL_MANT_DIG)*\fIlog2\fP(FLT_RADIX) +if subnormals are supported. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlogb\fR\^(\|)", +.IR "\fIscalbln\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/imaxabs.3p b/man-pages-posix-2013-a/man3p/imaxabs.3p new file mode 100644 index 0000000..a78a412 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/imaxabs.3p @@ -0,0 +1,67 @@ +'\" et +.TH IMAXABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +imaxabs +\(em return absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +intmax_t imaxabs(intmax_t \fIj\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIimaxabs\fR() +function shall compute the absolute value of an integer +.IR j . +If the result cannot be represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIimaxabs\fR() +function shall return the absolute value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The absolute value of the most negative number cannot be represented in +two's complement. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIimaxdiv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/imaxdiv.3p b/man-pages-posix-2013-a/man3p/imaxdiv.3p new file mode 100644 index 0000000..c5bc147 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/imaxdiv.3p @@ -0,0 +1,76 @@ +'\" et +.TH IMAXDIV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +imaxdiv +\(em return quotient and remainder +.SH SYNOPSIS +.LP +.nf +#include +.P +imaxdiv_t imaxdiv(intmax_t \fInumer\fP, intmax_t \fIdenom\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIimaxdiv\fR() +function shall compute \fInumer\fR\ /\ \fIdenom\fR and +\fInumer\fR\ %\ \fIdenom\fR in a single operation. +.SH "RETURN VALUE" +The +\fIimaxdiv\fR() +function shall return a structure of type +.BR imaxdiv_t , +comprising both the quotient and the remainder. The structure shall +contain (in either order) the members +.IR quot +(the quotient) and +.IR rem +(the remainder), each of which has type +.BR intmax_t . +.P +If either part of the result cannot be represented, the behavior is +undefined. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIimaxabs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/inet_addr.3p b/man-pages-posix-2013-a/man3p/inet_addr.3p new file mode 100644 index 0000000..565770e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/inet_addr.3p @@ -0,0 +1,116 @@ +'\" et +.TH INET_ADDR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +inet_addr, +inet_ntoa +\(em IPv4 address manipulation +.SH SYNOPSIS +.LP +.nf +#include +.P +in_addr_t inet_addr(const char *\fIcp\fP); +char *inet_ntoa(struct in_addr \fIin\fP); +.fi +.SH DESCRIPTION +The +\fIinet_addr\fR() +function shall convert the string pointed to by +.IR cp , +in the standard IPv4 dotted decimal notation, to an integer value +suitable for use as an Internet address. +.P +The +\fIinet_ntoa\fR() +function shall convert the Internet host address specified by +.IR in +to a string in the Internet standard dot notation. +.P +The +\fIinet_ntoa\fR() +function need not be thread-safe. +.P +All Internet addresses shall be returned in network order (bytes +ordered from left to right). +.P +Values specified using IPv4 dotted decimal notation take one of the +following forms: +.IP "\fRa.b.c.d\fP" 10 +When four parts are specified, each shall be interpreted as a byte of +data and assigned, from left to right, to the four bytes of an Internet +address. +.IP "\fRa.b.c\fP" 10 +When a three-part address is specified, the last part shall be +interpreted as a 16-bit quantity and placed in the rightmost two bytes +of the network address. This makes the three-part address format +convenient for specifying Class B network addresses as +.BR \(dq128.net.host\(dq . +.IP "\fRa.b\fP" 10 +When a two-part address is supplied, the last part shall be interpreted +as a 24-bit quantity and placed in the rightmost three bytes of the +network address. This makes the two-part address format convenient for +specifying Class A network addresses as +.BR \(dqnet.host\(dq . +.IP "\fRa\fP" 10 +When only one part is given, the value shall be stored directly in the +network address without any byte rearrangement. +.P +All numbers supplied as parts in IPv4 dotted decimal notation may be +decimal, octal, or hexadecimal, as specified in the ISO\ C standard (that is, a +leading 0x or 0X implies hexadecimal; otherwise, a leading +.BR '0' +implies octal; otherwise, the number is interpreted as decimal). +.SH "RETURN VALUE" +Upon successful completion, +\fIinet_addr\fR() +shall return the Internet address. Otherwise, it shall return (\c +.BR in_addr_t )(\(mi1). +.P +The +\fIinet_ntoa\fR() +function shall return a pointer to the network address in Internet +standard dot notation. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The return value of +\fIinet_ntoa\fR() +may point to static data that may be overwritten by subsequent calls to +\fIinet_ntoa\fR(). +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendhostent\fR\^(\|)", +.IR "\fIendnetent\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/inet_ntop.3p b/man-pages-posix-2013-a/man3p/inet_ntop.3p new file mode 100644 index 0000000..f1d1adc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/inet_ntop.3p @@ -0,0 +1,200 @@ +'\" et +.TH INET_NTOP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +inet_ntop, +inet_pton +\(em convert IPv4 and IPv6 addresses between binary and text form +.SH SYNOPSIS +.LP +.nf +#include +.P +const char *inet_ntop(int \fIaf\fP, const void *restrict \fIsrc\fP, + char *restrict \fIdst\fP, socklen_t \fIsize\fP); +int inet_pton(int \fIaf\fP, const char *restrict \fIsrc\fP, void *restrict \fIdst\fP); +.fi +.SH DESCRIPTION +The +\fIinet_ntop\fR() +function shall convert a numeric address into a text string suitable +for presentation. The +.IR af +argument shall specify the family of the address. This can be AF_INET +or AF_INET6. +The +.IR src +argument points to a buffer holding an IPv4 address if the +.IR af +argument is AF_INET, +or an IPv6 address if the +.IR af +argument is AF_INET6; +the address must be in network byte order. The +.IR dst +argument points to a buffer where the function stores the resulting +text string; it shall not be NULL. The +.IR size +argument specifies the size of this buffer, which shall be large enough +to hold the text string (INET_ADDRSTRLEN characters for IPv4, +INET6_ADDRSTRLEN characters for IPv6). +.P +The +\fIinet_pton\fR() +function shall convert an address in its standard text presentation +form into its numeric binary form. The +.IR af +argument shall specify the family of the address. The AF_INET +and AF_INET6 +address families shall be supported. The +.IR src +argument points to the string being passed in. The +.IR dst +argument points to a buffer into which the function stores the numeric +address; this shall be large enough to hold the numeric address (32 bits +for AF_INET, +128 bits for AF_INET6). +.P +If the +.IR af +argument of +\fIinet_pton\fR() +is AF_INET, the +.IR src +string shall be in the standard IPv4 dotted-decimal form: +.sp +.RS 4 +.nf +\fB +ddd.ddd.ddd.ddd +.fi \fR +.P +.RE +.P +where +.BR \(dqddd\(dq +is a one to three digit decimal number between 0 and 255 (see +.IR "\fIinet_addr\fR\^(\|)"). +The +\fIinet_pton\fR() +function does not accept other formats (such as the octal numbers, +hexadecimal numbers, and fewer than four numbers that +\fIinet_addr\fR() +accepts). +.P +If the +.IR af +argument of +\fIinet_pton\fR() +is AF_INET6, the +.IR src +string shall be in one of the following standard IPv6 text forms: +.IP " 1." 4 +The preferred form is +.BR \(dqx:x:x:x:x:x:x:x\(dq , +where the +.BR 'x' s +are the hexadecimal values of the eight 16-bit pieces of the address. +Leading zeros in individual fields can be omitted, but there shall be at +least one numeral in every field. +.IP " 2." 4 +A string of contiguous zero fields in the preferred form can be shown +as +.BR \(dq::\(dq . +The +.BR \(dq::\(dq +can only appear once in an address. Unspecified addresses (\c +.BR \(dq0:0:0:0:0:0:0:0\(dq ) +may be represented simply as +.BR \(dq::\(dq . +.IP " 3." 4 +A third form that is sometimes more convenient when dealing with a +mixed environment of IPv4 and IPv6 nodes is +.BR \(dqx:x:x:x:x:x:d.d.d.d\(dq , +where the +.BR 'x' s +are the hexadecimal values of the six high-order 16-bit pieces of the +address, and the +.BR 'd' s +are the decimal values of the four low-order 8-bit pieces of the +address (standard IPv4 representation). +.TP 10 +.BR Note: +A more extensive description of the standard representations of IPv6 +addresses can be found in RFC\ 2373. +.P +.SH "RETURN VALUE" +The +\fIinet_ntop\fR() +function shall return a pointer to the buffer containing the text +string if the conversion succeeds, and NULL otherwise, and set +.IR errno +to indicate the error. +.P +The +\fIinet_pton\fR() +function shall return 1 if the conversion succeeds, with the address +pointed to by +.IR dst +in network byte order. It shall return 0 if the input is not a valid +IPv4 dotted-decimal string +or a valid IPv6 address string, +or \(mi1 with +.IR errno +set to +.BR [EAFNOSUPPORT] +if the +.IR af +argument is unknown. +.SH ERRORS +The +\fIinet_ntop\fR() +and +\fIinet_pton\fR() +functions shall fail if: +.TP +.BR EAFNOSUPPORT +.br +The +.IR af +argument is invalid. +.TP +.BR ENOSPC +The size of the +\fIinet_ntop\fR() +result buffer is inadequate. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/initstate.3p b/man-pages-posix-2013-a/man3p/initstate.3p new file mode 100644 index 0000000..99559c4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/initstate.3p @@ -0,0 +1,189 @@ +'\" et +.TH INITSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +initstate, +random, +setstate, +srandom +\(em pseudo-random number functions +.SH SYNOPSIS +.LP +.nf +#include +.P +char *initstate(unsigned \fIseed\fP, char *\fIstate\fP, size_t \fIsize\fP); +long random(void); +char *setstate(char *\fIstate\fP); +void srandom(unsigned \fIseed\fP); +.fi +.SH DESCRIPTION +The +\fIrandom\fR() +function shall use a non-linear additive feedback random-number +generator employing a default state array size of 31 +.BR long +integers to return successive pseudo-random numbers in the range from 0 +to 2\u\s-331\s+3\d\(mi1. The period of this random-number generator is +approximately 16 x (2\s-3\u31\d\s+3\(mi\fR1). The size of the state +array determines the period of the random-number generator. Increasing +the state array size shall increase the period. +.P +With 256 bytes of state information, the period of the random-number +generator shall be greater than 2\s-3\u69\d\s+3. +.P +Like +\fIrand\fR(), +\fIrandom\fR() +shall produce by default a sequence of numbers that can be duplicated +by calling +\fIsrandom\fR() +with 1 as the seed. +.P +The +\fIsrandom\fR() +function shall initialize the current state array using the value of +.IR seed . +.P +The +\fIinitstate\fR() +and +\fIsetstate\fR() +functions handle restarting and changing random-number generators. The +\fIinitstate\fR() +function allows a state array, pointed to by the +.IR state +argument, to be initialized for future use. The +.IR size +argument, which specifies the size in bytes of the state array, shall +be used by +\fIinitstate\fR() +to decide what type of random-number generator to use; the larger the +state array, the more random the numbers. Values for the amount of +state information are 8, 32, 64, 128, and 256 bytes. Other values +greater than 8 bytes are rounded down to the nearest one of these +values. If +\fIinitstate\fR() +is called with 8\(<=\fIsize\fR<32, then +\fIrandom\fR() +shall use a simple linear congruential random number generator. The +.IR seed +argument specifies a starting point for the random-number sequence and +provides for restarting at the same point. The +\fIinitstate\fR() +function shall return a pointer to the previous state information array. +.P +If +\fIinitstate\fR() +has not been called, then +\fIrandom\fR() +shall behave as though +\fIinitstate\fR() +had been called with +.IR seed =1 +and +.IR size =128. +.P +Once a state has been initialized, +\fIsetstate\fR() +allows switching between state arrays. The array defined by the +.IR state +argument shall be used for further random-number generation until +\fIinitstate\fR() +is called or +\fIsetstate\fR() +is called again. The +\fIsetstate\fR() +function shall return a pointer to the previous state array. +.SH "RETURN VALUE" +If +\fIinitstate\fR() +is called with +.IR size +less than 8, it shall return NULL. +.P +The +\fIrandom\fR() +function shall return the generated pseudo-random number. +.P +The +\fIsrandom\fR() +function shall not return a value. +.P +Upon successful completion, +\fIinitstate\fR() +and +\fIsetstate\fR() +shall return a pointer to the previous state array; otherwise, a null +pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After initialization, a state array can be restarted at a different +point in one of two ways: +.IP " 1." 4 +The +\fIinitstate\fR() +function can be used, with the desired seed, state array, and size of +the array. +.IP " 2." 4 +The +\fIsetstate\fR() +function, with the desired state, can be used, followed by +\fIsrandom\fR() +with the desired seed. The advantage of using both of these functions +is that the size of the state array does not have to be saved once it +is initialized. +.P +Although some implementations of +\fIrandom\fR() +have written messages to standard error, such implementations do not +conform to POSIX.1\(hy2008. +.P +Issue 5 restored the historical behavior of this function. +.P +Threaded applications should use +\fIerand48\fR(), +\fInrand48\fR(), +or +\fIjrand48\fR() +instead of +\fIrandom\fR() +when an independent random number sequence in multiple threads is +required. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdrand48\fR\^(\|)", +.IR "\fIrand\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/insque.3p b/man-pages-posix-2013-a/man3p/insque.3p new file mode 100644 index 0000000..81fd05b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/insque.3p @@ -0,0 +1,214 @@ +'\" et +.TH INSQUE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +insque, +remque +\(em insert or remove an element in a queue +.SH SYNOPSIS +.LP +.nf +#include +.P +void insque(void *\fIelement\fP, void *\fIpred\fP); +void remque(void *\fIelement\fP); +.fi +.SH DESCRIPTION +The +\fIinsque\fR() +and +\fIremque\fR() +functions shall manipulate queues built from doubly-linked lists. +The queue can be either circular or linear. An application using +\fIinsque\fR() +or +\fIremque\fR() +shall ensure it defines a structure in which the first two members of +the structure are pointers to the same type of structure, and any +further members are application-specific. The first member of the +structure is a forward pointer to the next entry in the queue. The +second member is a backward pointer to the previous entry in the queue. +If the queue is linear, the queue is terminated with null pointers. The +names of the structure and of the pointer members are not subject to +any special restriction. +.P +The +\fIinsque\fR() +function shall insert the element pointed to by +.IR element +into a queue immediately after the element pointed to by +.IR pred . +.P +The +\fIremque\fR() +function shall remove the element pointed to by +.IR element +from a queue. +.P +If the queue is to be used as a linear list, invoking +\fIinsque\fP(&\fIelement\fP, NULL), where +.IR element +is the initial element of the queue, shall initialize the forward +and backward pointers of +.IR element +to null pointers. +.P +If the queue is to be used as a circular list, the application shall +ensure it initializes the forward pointer and the backward pointer of +the initial element of the queue to the element's own address. +.SH "RETURN VALUE" +The +\fIinsque\fR() +and +\fIremque\fR() +functions do not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a Linear Linked List" +.P +The following example creates a linear linked list. +.sp +.RS 4 +.nf +\fB +#include +\&... +struct myque element1; +struct myque element2; +.P +char *data1 = "DATA1"; +char *data2 = "DATA2"; +\&... +element1.data = data1; +element2.data = data2; +.P +insque (&element1, NULL); +insque (&element2, &element1); +.fi \fR +.P +.RE +.SS "Creating a Circular Linked List" +.P +The following example creates a circular linked list. +.sp +.RS 4 +.nf +\fB +#include +\&... +struct myque element1; +struct myque element2; +.P +char *data1 = "DATA1"; +char *data2 = "DATA2"; +\&... +element1.data = data1; +element2.data = data2; +.P +element1.fwd = &element1; +element1.bck = &element1; +.P +insque (&element2, &element1); +.fi \fR +.P +.RE +.SS "Removing an Element" +.P +The following example removes the element pointed to by +.IR element1 . +.sp +.RS 4 +.nf +\fB +#include +\&... +struct myque element1; +\&... +remque (&element1); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The historical implementations of these functions described the +arguments as being of type +.BR "struct qelem *" +rather than as being of type +.BR "void *" +as defined here. In those implementations, +.BR "struct qelem" +was commonly defined in +.IR +as: +.sp +.RS 4 +.nf +\fB +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; +}; +.fi \fR +.P +.RE +.P +Applications using these functions, however, were never able to use +this structure directly since it provided no room for the actual data +contained in the elements. Most applications defined structures that +contained the two pointers as the initial elements and also provided +space for, or pointers to, the object's data. Applications that used +these functions to update more than one type of table also had the +problem of specifying two or more different structures with the same +name, if they literally used +.BR "struct qelem" +as specified. +.P +As described here, the implementations were actually expecting a +structure type where the first two members were forward and backward +pointers to structures. With C compilers that didn't provide function +prototypes, applications used structures as specified in the +DESCRIPTION above and the compiler did what the application expected. +.P +If this method had been carried forward with an ISO\ C standard compiler and the +historical function prototype, most applications would have to be +modified to cast pointers to the structures actually used to be +pointers to +.BR "struct qelem" +to avoid compilation warnings. By specifying +.BR "void *" +as the argument type, applications do not need to change (unless +they specifically referenced +.BR "struct qelem" +and depended on it being defined in +.IR ). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ioctl.3p b/man-pages-posix-2013-a/man3p/ioctl.3p new file mode 100644 index 0000000..122712e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ioctl.3p @@ -0,0 +1,1214 @@ +'\" et +.TH IOCTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ioctl +\(em control a STREAMS device (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int ioctl(int \fIfildes\fP, int \fIrequest\fP, ... /* arg */); +.fi +.SH DESCRIPTION +The +\fIioctl\fR() +function shall perform a variety of control functions on STREAMS +devices. For non-STREAMS devices, the functions performed by this call +are unspecified. The +.IR request +argument and an optional third argument (with varying type) shall be +passed to and interpreted by the appropriate part of the STREAM +associated with +.IR fildes . +.P +The +.IR fildes +argument is an open file descriptor that refers to a device. +.P +The +.IR request +argument selects the control function to be performed and shall +depend on the STREAMS device being addressed. +.P +The +.IR arg +argument represents additional information that is needed by this +specific STREAMS device to perform the requested function. The type of +.IR arg +depends upon the particular control request, but it shall be either an +integer or a pointer to a device-specific data structure. +.P +The +\fIioctl\fR() +commands applicable to STREAMS, their arguments, and error conditions +that apply to each individual command are described below. +.P +The following +\fIioctl\fR() +commands, with error values indicated, are applicable to all STREAMS +files: +.IP I_PUSH 12 +Pushes the module whose name is pointed to by +.IR arg +onto the top of the current STREAM, just below the STREAM head. It then +calls the +\fIopen\fR() +function of the newly-pushed module. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PUSH command shall fail if: +.TP +.BR EINVAL +Invalid module name. +.TP +.BR ENXIO +Open function of new module failed. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_POP 12 +Removes the module just below the STREAM head of the STREAM pointed to +by +.IR fildes . +The +.IR arg +argument should be 0 in an I_POP request. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_POP command shall fail if: +.TP +.BR EINVAL +No module present in the STREAM. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_LOOK 12 +Retrieves the name of the module just below the STREAM head of the +STREAM pointed to by +.IR fildes , +and places it in a character string pointed to by +.IR arg . +The buffer pointed to by +.IR arg +should be at least FMNAMESZ+1 +bytes long, where FMNAMESZ is defined in +.IR . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_LOOK command shall fail if: +.TP +.BR EINVAL +No module present in the STREAM. +.RE +.IP I_FLUSH 12 +Flushes read and/or write queues, depending on the value of +.IR arg . +Valid +.IR arg +values are: +.RS 12 +.IP FLUSHR 12 +Flush all read queues. +.IP FLUSHW 12 +Flush all write queues. +.IP FLUSHRW 12 +Flush all read and all write queues. +.P +The +\fIioctl\fR() +function with the I_FLUSH command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for flush message. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_FLUSHBAND 12 +Flushes a particular band of messages. The +.IR arg +argument points to a +.BR bandinfo +structure. The +.IR bi_flag +member may be one of FLUSHR, FLUSHW, or FLUSHRW as described above. The +.IR bi_pri +member determines the priority band to be flushed. +.IP I_SETSIG 12 +Requests that the STREAMS implementation send the SIGPOLL signal to the +calling process when a particular event has occurred on +the STREAM associated with +.IR fildes . +I_SETSIG supports an asynchronous processing capability in STREAMS. The +value of +.IR arg +is a bitmask that specifies the events for which the process should be +signaled. It is the bitwise-inclusive OR of any combination of the +following constants: +.RS 12 +.IP S_RDNORM 12 +A normal (priority band set to 0) message has arrived at the head of a +STREAM head read queue. A signal shall be generated even if the message +is of zero length. +.IP S_RDBAND 12 +A message with a non-zero priority band has arrived at the head of a +STREAM head read queue. A signal shall be generated even if the message +is of zero length. +.IP S_INPUT 12 +A message, other than a high-priority message, has arrived at the head +of a STREAM head read queue. A signal shall be generated even if the +message is of zero length. +.IP S_HIPRI 12 +A high-priority message is present on a STREAM head read queue. A +signal shall be generated even if the message is of zero length. +.IP S_OUTPUT 12 +The write queue for normal data (priority band 0) just below the STREAM +head is no longer full. This notifies the process that there is room +on the queue for sending (or writing) normal data downstream. +.IP S_WRNORM 12 +Equivalent to S_OUTPUT. +.IP S_WRBAND 12 +The write queue for a non-zero priority band just below the STREAM head +is no longer full. This notifies the process that there is room on the +queue for sending (or writing) priority data downstream. +.IP S_MSG 12 +A STREAMS signal message that contains the SIGPOLL signal has reached +the front of the STREAM head read queue. +.IP S_ERROR 12 +Notification of an error condition has reached the STREAM head. +.IP S_HANGUP 12 +Notification of a hangup has reached the STREAM head. +.IP S_BANDURG 12 +When used in conjunction with S_RDBAND, SIGURG is generated instead of +SIGPOLL when a priority message reaches the front of the STREAM head +read queue. +.P +If +.IR arg +is 0, the calling process shall be unregistered and shall not receive +further SIGPOLL signals for the stream associated with +.IR fildes . +.P +Processes that wish to receive SIGPOLL signals shall ensure that they +explicitly register to receive them using I_SETSIG. If several +processes register to receive this +signal for the same event on the same STREAM, each process shall be +signaled when the event occurs. +.P +The +\fIioctl\fR() +function with the I_SETSIG command shall fail if: +.TP +.BR EINVAL +The value of +.IR arg +is invalid. +.TP +.BR EINVAL +The value of +.IR arg +is 0 and the calling process is not registered to receive +the SIGPOLL signal. +.TP +.BR EAGAIN +There were insufficient resources to store the signal request. +.RE +.IP I_GETSIG 12 +Returns the events for which the calling process is currently +registered to be sent a SIGPOLL signal. The events are returned as a +bitmask in an +.BR int +pointed to by +.IR arg , +where the events are those specified in the description of +I_SETSIG above. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_GETSIG command shall fail if: +.TP +.BR EINVAL +Process is not registered to receive the SIGPOLL signal. +.RE +.IP I_FIND 12 +Compares the names of all modules currently present in the STREAM to +the name pointed to by +.IR arg , +and returns 1 if the named module is present in the STREAM, or returns +0 if the named module is not present. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_FIND command shall fail if: +.TP +.BR EINVAL +.IR arg +does not contain a valid module name. +.RE +.IP I_PEEK 12 +Retrieves the information in the first message on the STREAM head read +queue without taking the message off the queue. It is analogous to +\fIgetmsg\fR() +except that this command does not remove the message from the queue. +The +.IR arg +argument points to a +.BR strpeek +structure. +.RS 12 +.P +The application shall ensure that the +.IR maxlen +member in the +.BR ctlbuf +and +.BR "databuf strbuf" +structures is set to the number of bytes of control information and/or +data information, respectively, to retrieve. The +.IR flags +member may be marked RS_HIPRI or 0, as described by +\fIgetmsg\fR(). +If the process sets +.IR flags +to RS_HIPRI, for example, I_PEEK shall only look for a high-priority +message on the STREAM head read queue. +.P +I_PEEK returns 1 if a message was retrieved, and returns 0 if no +message was found on the STREAM head read queue, or if the RS_HIPRI +flag was set in +.IR flags +and a high-priority message was not present on the STREAM head read +queue. It does not wait for a message to arrive. On return, +.BR ctlbuf +specifies information in the control buffer, +.BR databuf +specifies information in the data buffer, and +.IR flags +contains the value RS_HIPRI or 0. +.RE +.IP I_SRDOPT 12 +Sets the read mode using the value of the argument +.IR arg . +Read modes are described in +\fIread\fR(). +Valid +.IR arg +flags are: +.RS 12 +.IP RNORM 12 +Byte-stream mode, the default. +.IP RMSGD 12 +Message-discard mode. +.IP RMSGN 12 +Message-nondiscard mode. +.P +The bitwise-inclusive OR of RMSGD and RMSGN shall return +.BR [EINVAL] . +The bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall +result in the other flag overriding RNORM which is the default. +.P +In addition, treatment of control messages by the STREAM head may be +changed by setting any of the following flags in +.IR arg : +.IP RPROTNORM 12 +Fail +\fIread\fR() +with +.BR [EBADMSG] +if a message containing a control part is at the front of the +STREAM head read queue. +.IP RPROTDAT 12 +Deliver the control part of a message as data when a process issues a +\fIread\fR(). +.IP RPROTDIS 12 +Discard the control part of a message, delivering any data portion, +when a process issues a +\fIread\fR(). +.P +The +\fIioctl\fR() +function with the I_SRDOPT command shall fail if: +.TP +.BR EINVAL +The +.IR arg +argument is not valid. +.RE +.IP I_GRDOPT 12 +Returns the current read mode setting, as described above, in an +.BR int +pointed to by the argument +.IR arg . +Read modes are described in +\fIread\fR(). +.IP I_NREAD 12 +Counts the number of data bytes in the data part of the first message +on the STREAM head read queue and places this value in the +.BR int +pointed to by +.IR arg . +The return value for the command shall be the number of messages on the +STREAM head read queue. For example, if 0 is returned in +.IR arg , +but the +\fIioctl\fR() +return value is greater than 0, this indicates that a zero-length +message is next on the queue. +.IP I_FDINSERT 12 +Creates a message from specified buffer(s), adds information about +another STREAM, and sends the message downstream. The message contains +a control part and an optional data part. The data and control parts to +be sent are distinguished by placement in separate buffers, as +described below. The +.IR arg +argument points to a +.BR strfdinsert +structure. +.RS 12 +.P +The application shall ensure that the +.IR len +member in the +.BR "ctlbuf strbuf" +structure is set to the size of a +.BR t_uscalar_t +plus the number of bytes of control information to be sent with the +message. The +.IR fildes +member specifies the file descriptor of the other STREAM, and the +.IR offset +member, which must be suitably aligned for use as a +.BR t_uscalar_t , +specifies the offset from the start of the control buffer where +I_FDINSERT shall store a +.BR t_uscalar_t +whose interpretation is specific to the STREAM end. The application +shall ensure that the +.IR len +member in the +.BR "databuf strbuf" +structure is set to the number of bytes of data information to be sent +with the message, or to 0 if no data part is to be sent. +.P +The +.IR flags +member specifies the type of message to be created. A normal message is +created if +.IR flags +is set to 0, and a high-priority message is created if +.IR flags +is set to RS_HIPRI. For non-priority messages, I_FDINSERT shall block if +the STREAM write queue is full due to internal flow control conditions. +For priority messages, I_FDINSERT does not block on this condition. For +non-priority messages, I_FDINSERT does not block when the write queue +is full and O_NONBLOCK is set. Instead, it fails and sets +.IR errno +to +.BR [EAGAIN] . +.P +I_FDINSERT also blocks, unless prevented by lack of internal resources, +waiting for the availability of message blocks in the STREAM, +regardless of priority or whether O_NONBLOCK has been specified. No +partial message is sent. +.P +The +\fIioctl\fR() +function with the I_FDINSERT command shall fail if: +.TP +.BR EAGAIN +A non-priority message is specified, the O_NONBLOCK flag is set, and +the STREAM write queue is full due to internal flow control +conditions. +.TP +.BR EAGAIN " or " ENOSR +.br +Buffers cannot be allocated for the message that is to be created. +.TP +.BR EINVAL +One of the following: +.RS 12 +.IP -- 4 +The +.IR fildes +member of the +.BR strfdinsert +structure is not a valid, open STREAM file descriptor. +.IP -- 4 +The size of a +.BR t_uscalar_t +plus +.IR offset +is greater than the +.IR len +member for the buffer specified through +.BR ctlbuf . +.IP -- 4 +The +.IR offset +member does not specify a properly-aligned location in the data buffer. +.IP -- 4 +An undefined value is stored in +.IR flags . +.RE +.TP +.BR ENXIO +Hangup received on the STREAM identified by either the +.IR fildes +argument or the +.IR fildes +member of the +.BR strfdinsert +structure. +.TP +.BR ERANGE +The +.IR len +member for the buffer specified through +.BR databuf +does not fall within the range specified by the maximum and minimum +packet sizes of the topmost STREAM module; or the +.IR len +member for the buffer specified through +.BR databuf +is larger than the maximum configured size of the data part of a +message; or the +.IR len +member for the buffer specified through +.BR ctlbuf +is larger than the maximum configured size of the control part of a +message. +.RE +.IP I_STR 12 +Constructs an internal STREAMS +\fIioctl\fR() +message from the data pointed to by +.IR arg , +and sends that message downstream. +.RS 12 +.P +This mechanism is provided to send +\fIioctl\fR() +requests to downstream modules and drivers. It allows information to be +sent with +\fIioctl\fR(), +and returns to the process any information sent upstream by the +downstream recipient. I_STR shall block until the system responds with +either a positive or negative acknowledgement message, or until the +request times out after some period of time. If the request times out, +it shall fail with +.IR errno +set to +.BR [ETIME] . +.P +At most, one I_STR can be active on a STREAM. Further I_STR calls shall +block until the active I_STR completes at the STREAM head. The default +timeout interval for these requests is 15 seconds. The O_NONBLOCK flag +has no effect on this call. +.P +To send requests downstream, the application shall ensure that +.IR arg +points to a +.BR strioctl +structure. +.P +The +.IR ic_cmd +member is the internal +\fIioctl\fR() +command intended for a downstream module or driver and +.IR ic_timout +is the number of seconds (\(mi1=infinite, 0=use +implementation-defined timeout interval, >0=as specified) an I_STR +request shall wait for acknowledgement before timing out. +.IR ic_len +is the number of bytes in the data argument, and +.IR ic_dp +is a pointer to the data argument. The +.IR ic_len +member has two uses: on input, it contains the length of the data +argument passed in, and on return from the command, it contains the +number of bytes being returned to the process (the buffer pointed to by +.IR ic_dp +should be large enough to contain the maximum amount of data that any +module or the driver in the STREAM can return). +.P +The STREAM head shall convert the information pointed to by the +.BR strioctl +structure to an internal +\fIioctl\fR() +command message and send it downstream. +.P +The +\fIioctl\fR() +function with the I_STR command shall fail if: +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the +\fIioctl\fR() +message. +.TP +.BR EINVAL +The +.IR ic_len +member is less than 0 or larger than the maximum configured size of the +data part of a message, or +.IR ic_timout +is less than \(mi1. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +A downstream +\fIioctl\fR() +timed out before acknowledgement was received. +.P +An I_STR can also fail while waiting for an acknowledgement if a +message indicating an error or a hangup is received at the STREAM head. +In addition, an error code can be returned in the positive or negative +acknowledgement message, in the event the +\fIioctl\fR() +command sent downstream fails. For these cases, I_STR shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_SWROPT 12 +Sets the write mode using the value of the argument +.IR arg . +Valid bit settings for +.IR arg +are: +.RS 12 +.IP SNDZERO 12 +Send a zero-length message downstream when a +\fIwrite\fR() +of 0 bytes occurs. To not send a zero-length message when a +\fIwrite\fR() +of 0 bytes occurs, the application shall ensure that this bit is not +set in +.IR arg +(for example, +.IR arg +would be set to 0). +.P +The +\fIioctl\fR() +function with the I_SWROPT command shall fail if: +.TP +.BR EINVAL +.IR arg +is not the above value. +.RE +.IP I_GWROPT 12 +Returns the current write mode setting, as described above, in the +.BR int +that is pointed to by the argument +.IR arg . +.IP I_SENDFD 12 +Creates a new reference to the open file description associated with +the file descriptor +.IR arg , +and writes a message on the STREAMS-based pipe +.IR fildes +containing this reference, together with the user ID and group ID of +the calling process. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_SENDFD command shall fail if: +.TP +.BR EAGAIN +The sending STREAM is unable to allocate a message block to contain the +file pointer; or the read queue of the receiving STREAM head is full +and cannot accept the message sent by I_SENDFD. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument is not connected to a STREAM pipe. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.P +The +\fIioctl\fR() +function with the I_SENDFD command may fail if: +.TP +.BR EINVAL +The +.IR arg +argument is equal to the +.IR fildes +argument. +.RE +.IP I_RECVFD 12 +Retrieves the reference to an open file description from a message +written to a STREAMS-based pipe using the I_SENDFD command, and +allocates a new file descriptor in the calling process that refers to +this open file description. The +.IR arg +argument is a pointer to a +.BR strrecvfd +data structure as defined in +.IR . +.RS 12 +.P +The +.IR fd +member is a file descriptor. The +.IR uid +and +.IR gid +members are the effective user ID and effective group ID, respectively, +of the sending process. +.P +If O_NONBLOCK is not set, I_RECVFD shall block until a message is +present at the STREAM head. If O_NONBLOCK is set, I_RECVFD shall fail +with +.IR errno +set to +.BR [EAGAIN] +if no message is present at the STREAM head. +.P +If the message at the STREAM head is a message sent by an I_SENDFD, a +new file +descriptor shall be allocated for the open file descriptor referenced +in the message. The new file descriptor is placed in the +.IR fd +member of the +.BR strrecvfd +structure pointed to by +.IR arg . +.P +The +\fIioctl\fR() +function with the I_RECVFD command shall fail if: +.TP +.BR EAGAIN +A message is not present at the STREAM head read queue and the +O_NONBLOCK flag is set. +.TP +.BR EBADMSG +The message at the STREAM head read queue is not a message containing a +passed file descriptor. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_LIST 12 +Allows the process to list all the module names on the STREAM, up to +and including the topmost driver name. If +.IR arg +is a null pointer, the return value shall be the number of modules, +including the driver, that are on the STREAM pointed to by +.IR fildes . +This lets the process allocate enough space for the module names. +Otherwise, it should point to a +.BR str_list +structure. +.RS 12 +.P +The +.IR sl_nmods +member indicates the number of entries the process has allocated in the +array. Upon return, the +.IR sl_modlist +member of the +.BR str_list +structure shall contain the list of module names, and the number of +entries that have been filled into the +.IR sl_modlist +array is found in the +.IR sl_nmods +member (the number includes the number of modules including the +driver). The return value from +\fIioctl\fR() +shall be 0. The entries are filled in starting at the top of the STREAM +and continuing downstream until either the end of the STREAM is +reached, or the number of requested modules (\c +.IR sl_nmods ) +is satisfied. +.P +The +\fIioctl\fR() +function with the I_LIST command shall fail if: +.TP +.BR EINVAL +The +.IR sl_nmods +member is less than 1. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers. +.RE +.IP I_ATMARK 12 +Allows the process to see if the message at the head of the STREAM head +read queue is marked by some module downstream. The +.IR arg +argument determines how the checking is done when there may be multiple +marked messages on the STREAM head read queue. It may take on the +following values: +.RS 12 +.IP ANYMARK 12 +Check if the message is marked. +.IP LASTMARK 12 +Check if the message is the last one marked on the queue. +.P +The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted. +.P +The return value shall be 1 if the mark condition is satisfied; +otherwise, the value shall be 0. +.P +The +\fIioctl\fR() +function with the I_ATMARK command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_CKBAND 12 +Checks if the message of a given priority band exists on the STREAM +head read queue. This shall return 1 if a message of the given priority +exists, 0 if no such message exists, or \(mi1 on error. +.IR arg +should be of type +.BR int . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_CKBAND command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_GETBAND 12 +Returns the priority band of the first message on the STREAM head read +queue in the integer referenced by +.IR arg . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_GETBAND command shall fail if: +.TP +.BR ENODATA +No message on the STREAM head read queue. +.RE +.IP I_CANPUT 12 +Checks if a certain band is writable. +.IR arg +is set to the priority band in question. The return value shall be 0 if +the band is flow-controlled, 1 if the band is writable, or \(mi1 on +error. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_CANPUT command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_SETCLTIME 12 +This request allows the process to set the time the STREAM head shall +delay when a STREAM is closing and there is data on the write queues. +Before closing each module or driver, if there is data on its write +queue, the STREAM head shall delay for the specified amount of time to +allow the data to drain. If, after the delay, data is still present, it +shall be flushed. The +.IR arg +argument is a pointer to an integer specifying the number of +milliseconds to delay, rounded up to the nearest valid value. If +I_SETCLTIME is not performed on a STREAM, an implementation-defined +default timeout interval is used. +.br +.RS 12 +.P +The +\fIioctl\fR() +function with the I_SETCLTIME command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_GETCLTIME 12 +Returns the close time delay in the integer pointed to by +.IR arg . +.SS "Multiplexed STREAMS Configurations" +.P +The following commands are used for connecting and disconnecting +multiplexed STREAMS configurations. These commands use an +implementation-defined default timeout interval. +.IP I_LINK 12 +Connects two STREAMs, where +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver, and +.IR arg +is the file descriptor of the STREAM connected to another driver. The +STREAM designated by +.IR arg +is connected below the multiplexing driver. I_LINK requires the +multiplexing driver to send an acknowledgement message to the STREAM +head regarding the connection. This call shall return a multiplexer ID +number (an identifier used to disconnect the multiplexer; see I_UNLINK) +on success, and \(mi1 on failure. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_LINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate STREAMS storage to perform the I_LINK. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument does not support multiplexing; or +.IR arg +is not a STREAM or is already connected downstream from a multiplexer; +or the specified I_LINK operation would connect the STREAM head in more +than one place in the multiplexed STREAM. +.P +An I_LINK can also fail while waiting for the multiplexing driver to +acknowledge the request, if a message indicating an error or a hangup +is received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_LINK fails with +.IR errno +set to the value in the message. +.RE +.IP I_UNLINK 12 +Disconnects the two STREAMs specified by +.IR fildes +and +.IR arg . +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver. The +.IR arg +argument is the multiplexer ID number that was returned by the I_LINK +\fIioctl\fR() +command when a STREAM was connected downstream from the multiplexing +driver. If +.IR arg +is MUXID_ALL, then all STREAMs that were connected to +.IR fildes +shall be disconnected. As in I_LINK, this command requires +acknowledgement. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_UNLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the acknowledgement message. +.TP +.BR EINVAL +Invalid multiplexer ID number. +.P +An I_UNLINK can also fail while waiting for the multiplexing driver to +acknowledge the request if a message indicating an error or a hangup is +received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_UNLINK shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_PLINK 12 +Creates a +.IR "persistent connection" +between two STREAMs, where +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver, and +.IR arg +is the file descriptor of the STREAM connected to another driver. This +call shall create a persistent connection which can exist even if the +file descriptor +.IR fildes +associated with the upper STREAM to the multiplexing driver is closed. +The STREAM designated by +.IR arg +gets connected via a persistent connection below the multiplexing +driver. I_PLINK requires the multiplexing driver to send an +acknowledgement message to the STREAM head. This call shall return a +multiplexer ID number (an identifier that may be used to disconnect the +multiplexer; see I_PUNLINK) on success, and \(mi1 on failure. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate STREAMS storage to perform the I_PLINK. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument does not support multiplexing; or +.IR arg +is not a STREAM or is already connected downstream from a multiplexer; +or the specified I_PLINK operation would connect the STREAM head in +more than one place in the multiplexed STREAM. +.P +An I_PLINK can also fail while waiting for the multiplexing driver to +acknowledge the request, if a message indicating an error or a hangup +is received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_PLINK shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_PUNLINK 12 +Disconnects the two STREAMs specified by +.IR fildes +and +.IR arg +from a persistent connection. The +.IR fildes +argument is the file descriptor of the STREAM connected to the +multiplexing driver. The +.IR arg +argument is the multiplexer ID number that was returned by the I_PLINK +\fIioctl\fR() +command when a STREAM was connected downstream from the multiplexing +driver. If +.IR arg +is MUXID_ALL, then all STREAMs which are persistent connections +to +.IR fildes +shall be disconnected. As in I_PLINK, this command requires the +multiplexing driver to acknowledge the request. +.br +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PUNLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the acknowledgement message. +.TP +.BR EINVAL +Invalid multiplexer ID number. +.P +An I_PUNLINK can also fail while waiting for the multiplexing driver to +acknowledge the request if a message indicating an error or a hangup is +received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_PUNLINK shall fail with +.IR errno +set to the value in the message. +.RE +.SH "RETURN VALUE" +Upon successful completion, +\fIioctl\fR() +shall return a value other than \(mi1 that depends upon the STREAMS device +control function. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +Under the following general conditions, +\fIioctl\fR() +shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EINTR +A signal was caught during the +\fIioctl\fR() +operation. +.TP +.BR EINVAL +The STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.P +If an underlying device driver detects an error, then +\fIioctl\fR() +shall fail if: +.TP +.BR EINVAL +The +.IR request +or +.IR arg +argument is not valid for this device. +.TP +.BR EIO +Some physical I/O error has occurred. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a STREAMS device that accepts control functions. +.TP +.BR ENXIO +The +.IR request +and +.IR arg +arguments are valid for this device driver, but the service requested +cannot be performed on this particular sub-device. +.TP +.BR ENODEV +The +.IR fildes +argument refers to a valid STREAMS device, but the corresponding device +driver does not support the +\fIioctl\fR() +function. +.P +If a STREAM is connected downstream from a multiplexer, any +\fIioctl\fR() +command except I_UNLINK and I_PUNLINK shall set +.IR errno +to +.BR [EINVAL] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The implementation-defined timeout interval for STREAMS has +historically been 15 seconds. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIioctl\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIclose\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isalnum.3p b/man-pages-posix-2013-a/man3p/isalnum.3p new file mode 100644 index 0000000..2ca7a96 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isalnum.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISALNUM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isalnum, +isalnum_l +\(em test for an alphanumeric character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isalnum(int \fIc\fP); +int isalnum_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisalnum\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisalnum\fR() +and +\fIisalnum_l\fR() +functions shall test whether +.IR c +is a character of class +.BR alpha +or +.BR digit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisalnum_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisalnum\fR() +and +\fIisalnum_l\fR() +functions shall return non-zero if +.IR c +is an alphanumeric character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isalpha.3p b/man-pages-posix-2013-a/man3p/isalpha.3p new file mode 100644 index 0000000..c750350 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isalpha.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISALPHA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isalpha, +isalpha_l +\(em test for an alphabetic character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isalpha(int \fIc\fP); +int isalpha_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisalpha\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisalpha\fR() +and +\fIisalpha_l\fR() +functions shall test whether +.IR c +is a character of class +.BR alpha +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisalpha_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisalpha\fR() +and +\fIisalpha_l\fR() +functions shall return non-zero if +.IR c +is an alphabetic character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isascii.3p b/man-pages-posix-2013-a/man3p/isascii.3p new file mode 100644 index 0000000..844a2d3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isascii.3p @@ -0,0 +1,71 @@ +'\" et +.TH ISASCII "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isascii +\(em test for a 7-bit US-ASCII character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isascii(int \fIc\fP); +.fi +.SH DESCRIPTION +The +\fIisascii\fR() +function shall test whether +.IR c +is a 7-bit US-ASCII character code. +.P +The +\fIisascii\fR() +function is defined on all integer values. +.SH "RETURN VALUE" +The +\fIisascii\fR() +function shall return non-zero if +.IR c +is a 7-bit US-ASCII character code between 0 and octal 0177 inclusive; +otherwise, it shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIisascii\fR() +function cannot be used portably in a localized application. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIisascii\fR() +function may be removed in a future version. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isastream.3p b/man-pages-posix-2013-a/man3p/isastream.3p new file mode 100644 index 0000000..649c0fc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isastream.3p @@ -0,0 +1,75 @@ +'\" et +.TH ISASTREAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isastream +\(em test a file descriptor (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int isastream(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIisastream\fR() +function shall test whether +.IR fildes , +an open file descriptor, is associated with a STREAMS-based file. +.SH "RETURN VALUE" +Upon successful completion, +\fIisastream\fR() +shall return 1 if +.IR fildes +refers to a STREAMS-based file and 0 if not. Otherwise, +\fIisastream\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIisastream\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIisastream\fR() +function may be removed in a future version. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isatty.3p b/man-pages-posix-2013-a/man3p/isatty.3p new file mode 100644 index 0000000..babe7dc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isatty.3p @@ -0,0 +1,82 @@ +'\" et +.TH ISATTY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isatty +\(em test for a terminal device +.SH SYNOPSIS +.LP +.nf +#include +.P +int isatty(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIisatty\fR() +function shall test whether +.IR fildes , +an open file descriptor, is associated with a terminal device. +.SH "RETURN VALUE" +The +\fIisatty\fR() +function shall return 1 if +.IR fildes +is associated with a terminal; otherwise, it shall return 0 and may set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIisatty\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIisatty\fR() +function does not necessarily indicate that a human being is available +for interaction via +.IR fildes . +It is quite possible that non-terminal devices are connected to the +communications line. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isblank.3p b/man-pages-posix-2013-a/man3p/isblank.3p new file mode 100644 index 0000000..91ac531 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isblank.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISBLANK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isblank, +isblank_l +\(em test for a blank character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isblank(int \fIc\fP); +int isblank_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisblank\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisblank\fR() +and +\fIisblank_l\fR() +functions shall test whether +.IR c +is a character of class +.BR blank +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is a type +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisblank_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisblank\fR() +and +\fIisblank_l\fR() +functions shall return non-zero if +.IR c +is a +; +otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iscntrl.3p b/man-pages-posix-2013-a/man3p/iscntrl.3p new file mode 100644 index 0000000..b5ebc3d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iscntrl.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISCNTRL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iscntrl, +iscntrl_l +\(em test for a control character +.SH SYNOPSIS +.LP +.nf +#include +.P +int iscntrl(int \fIc\fP); +int iscntrl_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiscntrl\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiscntrl\fR() +and +\fIiscntrl_l\fR() +functions shall test whether +.IR c +is a character of class +.BR cntrl +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is a type +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiscntrl_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiscntrl\fR() +and +\fIiscntrl_l\fR() +functions shall return non-zero if +.IR c +is a control character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isdigit.3p b/man-pages-posix-2013-a/man3p/isdigit.3p new file mode 100644 index 0000000..96fa995 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isdigit.3p @@ -0,0 +1,113 @@ +'\" et +.TH ISDIGIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isdigit, +isdigit_l +\(em test for a decimal digit +.SH SYNOPSIS +.LP +.nf +#include +.P +int isdigit(int \fIc\fP); +int isdigit_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisdigit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisdigit\fR() +and +\fIisdigit_l\fR() +functions shall test whether +.IR c +is a character of class +.BR digit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisdigit_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisdigit\fR() +and +\fIisdigit_l\fR() +functions shall return non-zero if +.IR c +is a decimal digit; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isfinite.3p b/man-pages-posix-2013-a/man3p/isfinite.3p new file mode 100644 index 0000000..7ffed3b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isfinite.3p @@ -0,0 +1,73 @@ +'\" et +.TH ISFINITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isfinite +\(em test for finite value +.SH SYNOPSIS +.LP +.nf +#include +.P +int isfinite(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisfinite\fR() +macro shall determine whether its argument has a finite value (zero, +subnormal, or normal, and not infinite or NaN). First, an argument +represented in a format wider than its semantic type is converted to +its semantic type. Then determination is based on the type of the +argument. +.SH "RETURN VALUE" +The +\fIisfinite\fR() +macro shall return a non-zero value if and only if its argument has a +finite value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isgraph.3p b/man-pages-posix-2013-a/man3p/isgraph.3p new file mode 100644 index 0000000..f9f03ca --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isgraph.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISGRAPH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isgraph, +isgraph_l +\(em test for a visible character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isgraph(int \fIc\fP); +int isgraph_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisgraph\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisgraph\fR() +and +\fIisgraph_l\fR() +functions shall test whether +.IR c +is a character of class +.BR graph +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisgraph_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisgraph\fR() +and +\fIisgraph_l\fR() +functions shall return non-zero if +.IR c +is a character with a visible representation; otherwise, they shall +return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isgreater.3p b/man-pages-posix-2013-a/man3p/isgreater.3p new file mode 100644 index 0000000..609d49e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isgreater.3p @@ -0,0 +1,101 @@ +'\" et +.TH ISGREATER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isgreater +\(em test if x greater than y +.SH SYNOPSIS +.LP +.nf +#include +.P +int isgreater(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisgreater\fR() +macro shall determine whether its first argument is greater than its +second argument. The value of +.IR isgreater (\c +.IR x , +.IR y ) +shall be equal to (\fIx\fR)\ >\ (\fIy\fR); however, unlike +(\fIx\fR)\ >\ (\fIy\fR), +.IR isgreater (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIisgreater\fR() +macro shall return the value of (\fIx\fR)\ >\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isgreaterequal.3p b/man-pages-posix-2013-a/man3p/isgreaterequal.3p new file mode 100644 index 0000000..ee329ec --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isgreaterequal.3p @@ -0,0 +1,101 @@ +'\" et +.TH ISGREATEREQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isgreaterequal +\(em test if x is greater than or equal to y +.SH SYNOPSIS +.LP +.nf +#include +.P +int isgreaterequal(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisgreaterequal\fR() +macro shall determine whether its first argument is greater than or +equal to its second argument. The value of +.IR isgreaterequal (\c +.IR x , +.IR y ) +shall be equal to (\fIx\fR)\ \(>=\ (\fIy\fR); however, unlike +(\fIx\fR)\ \(>=\ (\fIy\fR), +.IR isgreaterequal (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIisgreaterequal\fR() +macro shall return the value of (\fIx\fR)\ \(>=\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isinf.3p b/man-pages-posix-2013-a/man3p/isinf.3p new file mode 100644 index 0000000..67dff48 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isinf.3p @@ -0,0 +1,72 @@ +'\" et +.TH ISINF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isinf +\(em test for infinity +.SH SYNOPSIS +.LP +.nf +#include +.P +int isinf(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisinf\fR() +macro shall determine whether its argument value is an infinity +(positive or negative). First, an argument represented in a format +wider than its semantic type is converted to its semantic type. Then +determination is based on the type of the argument. +.SH "RETURN VALUE" +The +\fIisinf\fR() +macro shall return a non-zero value if and only if its argument has an +infinite value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isless.3p b/man-pages-posix-2013-a/man3p/isless.3p new file mode 100644 index 0000000..76e857e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isless.3p @@ -0,0 +1,101 @@ +'\" et +.TH ISLESS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isless +\(em test if x is less than y +.SH SYNOPSIS +.LP +.nf +#include +.P +int isless(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisless\fR() +macro shall determine whether its first argument is less than its +second argument. The value of +.IR isless (\c +.IR x , +.IR y ) +shall be equal to (\fIx\fR)\ <\ (\fIy\fR); however, unlike +(\fIx\fR)\ <\ (\fIy\fR), +.IR isless (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIisless\fR() +macro shall return the value of (\fIx\fR)\ <\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/islessequal.3p b/man-pages-posix-2013-a/man3p/islessequal.3p new file mode 100644 index 0000000..0b30c95 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/islessequal.3p @@ -0,0 +1,101 @@ +'\" et +.TH ISLESSEQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +islessequal +\(em test if x is less than or equal to y +.SH SYNOPSIS +.LP +.nf +#include +.P +int islessequal(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIislessequal\fR() +macro shall determine whether its first argument is less than or equal +to its second argument. The value of +.IR islessequal (\c +.IR x , +.IR y ) +shall be equal to (\fIx\fR)\ <=\ (\fIy\fR); however, unlike +(\fIx\fR)\ <=\ (\fIy\fR), +.IR islessequal (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIislessequal\fR() +macro shall return the value of (\fIx\fR)\ <=\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/islessgreater.3p b/man-pages-posix-2013-a/man3p/islessgreater.3p new file mode 100644 index 0000000..e7b953d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/islessgreater.3p @@ -0,0 +1,106 @@ +'\" et +.TH ISLESSGREATER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +islessgreater +\(em test if x is less than or greater than y +.SH SYNOPSIS +.LP +.nf +#include +.P +int islessgreater(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIislessgreater\fR() +macro shall determine whether its first argument is less than or +greater than its second argument. The +.IR islessgreater (\c +.IR x , +.IR y ) +macro is similar to +(\fIx\fR)\ <\ (\fIy\fR)\ ||\ (\fIx\fR)\ >\ (\fIy\fR); however, +.IR islessgreater (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered (nor shall it evaluate +.IR x +and +.IR y +twice). +.SH "RETURN VALUE" +Upon successful completion, the +\fIislessgreater\fR() +macro shall return the value of +(\fIx\fR)\ <\ (\fIy\fR)\ ||\ (\fIx\fR)\ >\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/islower.3p b/man-pages-posix-2013-a/man3p/islower.3p new file mode 100644 index 0000000..97efc15 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/islower.3p @@ -0,0 +1,169 @@ +'\" et +.TH ISLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +islower, +islower_l +\(em test for a lowercase letter +.SH SYNOPSIS +.LP +.nf +#include +.P +int islower(int \fIc\fP); +int islower_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIislower\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIislower\fR() +and +\fIislower_l\fR() +functions shall test whether +.IR c +is a character of class +.BR lower +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIislower_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIislower\fR() +and +\fIislower_l\fR() +functions shall return non-zero if +.IR c +is a lowercase letter; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Testing for a Lowercase Letter" +.P +Two examples follow, the first using +\fIislower\fR(), +the second using multiple concurrent locales and +\fIislower_l\fR(). +.P +The examples test whether the value is a lowercase letter, +based on the current locale, then use it as part of a key value. +.sp +.RS 4 +.nf +\fB +/* Example 1 -- using islower() */ +#include +#include +#include +\&... +char *keystr; +int elementlen, len; +unsigned char c; +\&... +setlocale(LC_ALL, ""); +\&... +len = 0; +while (len < elementlen) { + c = (unsigned char) (rand() % 256); +\&... + if (islower(c)) + keystr[len++] = c; + } +\&... +.P +/* Example 2 -- using islower_l() */ +#include +#include +#include +\&... +char *keystr; +int elementlen, len; +unsigned char c; +\&... +locale_t loc = newlocale (LC_ALL_MASK, "", (locale_t) 0); +\&... +len = 0; +while (len < elementlen) { + c = (unsigned char) (rand() % 256); +\&... + if (islower_l(c, loc)) + keystr[len++] = c; + } +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isnan.3p b/man-pages-posix-2013-a/man3p/isnan.3p new file mode 100644 index 0000000..9c56483 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isnan.3p @@ -0,0 +1,72 @@ +'\" et +.TH ISNAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isnan +\(em test for a NaN +.SH SYNOPSIS +.LP +.nf +#include +.P +int isnan(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisnan\fR() +macro shall determine whether its argument value is a NaN. First, an +argument represented in a format wider than its semantic type is +converted to its semantic type. Then determination is based on the type +of the argument. +.SH "RETURN VALUE" +The +\fIisnan\fR() +macro shall return a non-zero value if and only if its argument has a +NaN value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isnormal.3p b/man-pages-posix-2013-a/man3p/isnormal.3p new file mode 100644 index 0000000..7d874d7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isnormal.3p @@ -0,0 +1,72 @@ +'\" et +.TH ISNORMAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isnormal +\(em test for a normal value +.SH SYNOPSIS +.LP +.nf +#include +.P +int isnormal(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisnormal\fR() +macro shall determine whether its argument value is normal (neither +zero, subnormal, infinite, nor NaN). First, an argument represented in +a format wider than its semantic type is converted to its semantic +type. Then determination is based on the type of the argument. +.SH "RETURN VALUE" +The +\fIisnormal\fR() +macro shall return a non-zero value if and only if its argument has a +normal value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isprint.3p b/man-pages-posix-2013-a/man3p/isprint.3p new file mode 100644 index 0000000..9953947 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isprint.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISPRINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isprint, +isprint_l +\(em test for a printable character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isprint(int \fIc\fP); +int isprint_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisprint\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisprint\fR() +and +\fIisprint_l\fR() +functions shall test whether +.IR c +is a character of class +.BR print +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisprint_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisprint\fR() +and +\fIisprint_l\fR() +functions shall return non-zero if +.IR c +is a printable character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ispunct.3p b/man-pages-posix-2013-a/man3p/ispunct.3p new file mode 100644 index 0000000..e65e349 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ispunct.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISPUNCT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ispunct, +ispunct_l +\(em test for a punctuation character +.SH SYNOPSIS +.LP +.nf +#include +.P +int ispunct(int \fIc\fP); +int ispunct_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIispunct\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIispunct\fR() +and +\fIispunct_l\fR() +functions shall test whether +.IR c +is a character of class +.BR punct +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIispunct_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIispunct\fR() +and +\fIispunct_l\fR() +functions shall return non-zero if +.IR c +is a punctuation character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isspace.3p b/man-pages-posix-2013-a/man3p/isspace.3p new file mode 100644 index 0000000..7cb6c43 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isspace.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISSPACE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isspace, +isspace_l +\(em test for a white-space character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isspace(int \fIc\fP); +int isspace_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisspace\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisspace\fR() +and +\fIisspace_l\fR() +functions shall test whether +.IR c +is a character of class +.BR space +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisspace_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisspace\fR() +and +\fIisspace_l\fR() +functions shall return non-zero if +.IR c +is a white-space character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isunordered.3p b/man-pages-posix-2013-a/man3p/isunordered.3p new file mode 100644 index 0000000..959a93a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isunordered.3p @@ -0,0 +1,87 @@ +'\" et +.TH ISUNORDERED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isunordered +\(em test if arguments are unordered +.SH SYNOPSIS +.LP +.nf +#include +.P +int isunordered(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisunordered\fR() +macro shall determine whether its arguments are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIisunordered\fR() +macro shall return 1 if its arguments are unordered, and 0 otherwise. +.P +If +.IR x +or +.IR y +is NaN, 1 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isupper.3p b/man-pages-posix-2013-a/man3p/isupper.3p new file mode 100644 index 0000000..be0e50c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isupper.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isupper, +isupper_l +\(em test for an uppercase letter +.SH SYNOPSIS +.LP +.nf +#include +.P +int isupper(int \fIc\fP); +int isupper_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisupper\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisupper\fR() +and +\fIisupper_l\fR() +functions shall test whether +.IR c +is a character of class +.BR upper +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisupper_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisupper\fR() +and +\fIisupper_l\fR() +functions shall return non-zero if +.IR c +is an uppercase letter; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswalnum.3p b/man-pages-posix-2013-a/man3p/iswalnum.3p new file mode 100644 index 0000000..20bb894 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswalnum.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISWALNUM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswalnum, +iswalnum_l +\(em test for an alphanumeric wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswalnum(wint_t \fIwc\fP); +int iswalnum_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswalnum\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswalnum\fR() +and +\fIiswalnum_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR alpha +or +.BR digit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or +equal to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswalnum_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswalnum\fR() +and +\fIiswalnum_l\fR() +functions shall return non-zero if +.IR wc +is an alphanumeric wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswalpha.3p b/man-pages-posix-2013-a/man3p/iswalpha.3p new file mode 100644 index 0000000..a39c3a1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswalpha.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWALPHA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswalpha, +iswalpha_l +\(em test for an alphabetic wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswalpha(wint_t \fIwc\fP); +int iswalpha_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswalpha\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswalpha\fR() +and +\fIiswalpha_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR alpha +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or +equal to the value of the macro WEOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswalpha_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswalpha\fR() +and +\fIiswalpha_l\fR() +functions shall return non-zero if +.IR wc +is an alphabetic wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswblank.3p b/man-pages-posix-2013-a/man3p/iswblank.3p new file mode 100644 index 0000000..2b29770 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswblank.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISWBLANK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswblank, +iswblank_l +\(em test for a blank wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswblank(wint_t \fIwc\fP); +int iswblank_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswblank\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswblank\fR() +and +\fIiswblank\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR blank +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswblank_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswblank\fR() +and +\fIiswblank_l\fR() +functions shall return non-zero if +.IR wc +is a blank wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswcntrl.3p b/man-pages-posix-2013-a/man3p/iswcntrl.3p new file mode 100644 index 0000000..aaba885 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswcntrl.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWCNTRL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswcntrl, +iswcntrl_l +\(em test for a control wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswcntrl(wint_t \fIwc\fP); +int iswcntrl_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswcntrl\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswcntrl\fR() +and +\fIiswcntrl_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR cntrl +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswcntrl_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswcntrl\fR() +and +\fIiswcntrl_l\fR() +functions shall return non-zero if +.IR wc +is a control wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswctype.3p b/man-pages-posix-2013-a/man3p/iswctype.3p new file mode 100644 index 0000000..2d83a4b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswctype.3p @@ -0,0 +1,188 @@ +'\" et +.TH ISWCTYPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswctype, +iswctype_l +\(em test character for a specified class +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswctype(wint_t \fIwc\fP, wctype_t \fIcharclass\fP); +int iswctype_l(wint_t \fIwc\fP, wctype_t \fIcharclass\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswctype\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswctype\fR() +and +\fIiswctype_l\fR() +functions shall determine whether the wide-character code +.IR wc +has the character class +.IR charclass , +returning true or false. The +\fIiswctype\fR() +and +\fIiswctype_l\fR() +functions are defined on WEOF and wide-character codes corresponding to +the valid character encodings in the current locale, or +in the locale represented by +.IR locale , +respectively. If the +.IR wc +argument is not in the domain of the function, the result is undefined. +If the value of +.IR charclass +is invalid (that is, not obtained by a call to +\fIwctype\fR() +or +.IR charclass +is invalidated by a subsequent call to +\fIsetlocale\fR() +that has affected category +.IR LC_CTYPE ) +the result is unspecified. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswctype_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswctype\fR() +and +\fIiswctype_l\fR() +functions shall return non-zero (true) if and only if +.IR wc +has the property described by +.IR charclass . +If +.IR charclass +is 0, these functions shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Testing for a Valid Character" +.sp +.RS 4 +.nf +\fB +#include +\&... +int yes_or_no; +wint_t wc; +wctype_t valid_class; +\&... +if ((valid_class=wctype("vowel")) == (wctype_t)0) + /* Invalid character class. */ +yes_or_no=iswctype(wc,valid_class); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The twelve strings +.BR \(dqalnum\(dq , +.BR \(dqalpha\(dq , +.BR \(dqblank\(dq , +.BR \(dqcntrl\(dq , +.BR \(dqdigit\(dq , +.BR \(dqgraph\(dq , +.BR \(dqlower\(dq , +.BR \(dqprint\(dq , +.BR \(dqpunct\(dq , +.BR \(dqspace\(dq , +.BR \(dqupper\(dq , +and +.BR \(dqxdigit\(dq +are reserved for the standard character classes. In the table below, +the functions in the left column are equivalent to the functions in the +right column. +.sp +.RS 4 +.nf +\fB +iswalnum(\fIwc\fP) iswctype(\fIwc\fP, wctype("alnum")) +iswalnum_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("alnum"), \fIlocale\fP) +iswalpha(\fIwc\fP) iswctype(\fIwc\fP, wctype("alpha")) +iswalpha_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("alpha"), \fIlocale\fP) +iswblank(\fIwc\fP) iswctype(\fIwc\fP, wctype("blank")) +iswblank_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("blank"), \fIlocale\fP) +iswcntrl(\fIwc\fP) iswctype(\fIwc\fP, wctype("cntrl")) +iswcntrl_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("cntrl"), \fIlocale\fP) +iswdigit(\fIwc\fP) iswctype(\fIwc\fP, wctype("digit")) +iswdigit_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("digit"), \fIlocale\fP) +iswgraph(\fIwc\fP) iswctype(\fIwc\fP, wctype("graph")) +iswgraph_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("graph"), \fIlocale\fP) +iswlower(\fIwc\fP) iswctype(\fIwc\fP, wctype("lower")) +iswlower_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("lower"), \fIlocale\fP) +iswprint(\fIwc\fP) iswctype(\fIwc\fP, wctype("print")) +iswprint_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("print"), \fIlocale\fP) +iswpunct(\fIwc\fP) iswctype(\fIwc\fP, wctype("punct")) +iswpunct_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("punct"), \fIlocale\fP) +iswspace(\fIwc\fP) iswctype(\fIwc\fP, wctype("space")) +iswspace_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("space"), \fIlocale\fP) +iswupper(\fIwc\fP) iswctype(\fIwc\fP, wctype("upper")) +iswupper_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("upper"), \fIlocale\fP) +iswxdigit(\fIwc\fP) iswctype(\fIwc\fP, wctype("xdigit")) +iswxdigit_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("xdigit"), \fIlocale\fP) +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)", +.IR "\fIwctype\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswdigit.3p b/man-pages-posix-2013-a/man3p/iswdigit.3p new file mode 100644 index 0000000..5e6a646 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswdigit.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWDIGIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswdigit, +iswdigit_l +\(em test for a decimal digit wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswdigit(wint_t \fIwc\fP); +int iswdigit_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswdigit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswdigit\fR() +and +\fIiswdigit_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR digit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswdigit_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswdigit\fR() +and +\fIiswdigit_l\fR() +functions shall return non-zero if +.IR wc +is a decimal digit wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswgraph.3p b/man-pages-posix-2013-a/man3p/iswgraph.3p new file mode 100644 index 0000000..15850fa --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswgraph.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISWGRAPH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswgraph, +iswgraph_l +\(em test for a visible wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswgraph(wint_t \fIwc\fP); +int iswgraph_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswgraph\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswgraph\fR() +and +\fIiswgraph_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR graph +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswgraph_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswgraph\fR() +and +\fIiswgraph_l\fR() +functions shall return non-zero if +.IR wc +is a wide-character code with a visible representation; otherwise, they +shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswlower.3p b/man-pages-posix-2013-a/man3p/iswlower.3p new file mode 100644 index 0000000..47dca63 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswlower.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswlower, +iswlower_l +\(em test for a lowercase letter wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswlower(wint_t \fIwc\fP); +int iswlower_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswlower\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswlower\fR() +and +\fIiswlower_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR lower +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswlower_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswlower\fR() +and +\fIiswlower_l\fR() +functions shall return non-zero if +.IR wc +is a lowercase letter wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)"1 +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswprint.3p b/man-pages-posix-2013-a/man3p/iswprint.3p new file mode 100644 index 0000000..68234d5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswprint.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWPRINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswprint, +iswprint_l +\(em test for a printable wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswprint(wint_t \fIwc\fP); +int iswprint_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswprint\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswprint\fR() +and +\fIiswprint_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR print +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswprint_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswprint\fR() +and +\fIiswprint_l\fR() +functions shall return non-zero if +.IR wc +is a printable wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswpunct.3p b/man-pages-posix-2013-a/man3p/iswpunct.3p new file mode 100644 index 0000000..cc52b7e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswpunct.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWPUNCT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswpunct, +iswpunct_l +\(em test for a punctuation wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswpunct(wint_t \fIwc\fP); +int iswpunct_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswpunct\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswpunct\fR() +and +\fIiswpunct_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR punct +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswpunct_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswpunct\fR() +and +\fIiswpunct_l\fR() +functions shall return non-zero if +.IR wc +is a punctuation wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswspace.3p b/man-pages-posix-2013-a/man3p/iswspace.3p new file mode 100644 index 0000000..098bd49 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswspace.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWSPACE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswspace, +iswspace_l +\(em test for a white-space wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswspace(wint_t \fIwc\fP); +int iswspace_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswspace\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswspace\fR() +and +\fIiswspace_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR space +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswspace_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswspace\fR() +and +\fIiswspace_l\fR() +functions shall return non-zero if +.IR wc +is a white-space wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswupper.3p b/man-pages-posix-2013-a/man3p/iswupper.3p new file mode 100644 index 0000000..625be1a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswupper.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswupper, +iswupper_l +\(em test for an uppercase letter wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswupper(wint_t \fIwc\fP); +int iswupper_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswupper\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswupper\fR() +and +\fIiswupper_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR upper +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswupper_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswupper\fR() +and +\fIiswupper_l\fR() +functions shall return non-zero if +.IR wc +is an uppercase letter wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/iswxdigit.3p b/man-pages-posix-2013-a/man3p/iswxdigit.3p new file mode 100644 index 0000000..98d59c9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/iswxdigit.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWXDIGIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iswxdigit, +iswxdigit_l +\(em test for a hexadecimal digit wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswxdigit(wint_t \fIwc\fP); +int iswxdigit_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswxdigit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIiswxdigit\fR() +and +\fIiswxdigit_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR xdigit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the current locale, or equal +to the value of the macro WEOF. If the argument has any other value, +the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswxdigit_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswxdigit\fR() +and +\fIiswxdigit_l\fR() +functions shall return non-zero if +.IR wc +is a hexadecimal digit wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/isxdigit.3p b/man-pages-posix-2013-a/man3p/isxdigit.3p new file mode 100644 index 0000000..8ac1b15 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/isxdigit.3p @@ -0,0 +1,112 @@ +'\" et +.TH ISXDIGIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +isxdigit, +isxdigit_l +\(em test for a hexadecimal digit +.SH SYNOPSIS +.LP +.nf +#include +.P +int isxdigit(int \fIc\fP); +int isxdigit_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisxdigit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIisxdigit\fR() +and +\fIisxdigit_l\fR() +functions shall test whether +.IR c +is a character of class +.BR xdigit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisxdigit_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisxdigit\fR() +and +\fIisxdigit_l\fR() +functions shall return non-zero if +.IR c +is a hexadecimal digit; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/j0.3p b/man-pages-posix-2013-a/man3p/j0.3p new file mode 100644 index 0000000..c038be0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/j0.3p @@ -0,0 +1,112 @@ +'\" et +.TH J0 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +j0, +j1, +jn +\(em Bessel functions of the first kind +.SH SYNOPSIS +.LP +.nf +#include +.P +double j0(double \fIx\fP); +double j1(double \fIx\fP); +double jn(int \fIn\fP, double \fIx\fP); +.fi +.SH DESCRIPTION +The +\fIj0\fR(), +\fIj1\fR(), +and +\fIjn\fR() +functions shall compute Bessel functions of +.IR x +of the first kind of orders 0, 1, and +.IR n , +respectively. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the relevant +Bessel value of +.IR x +of the first kind. +.P +If the +.IR x +argument is too large in magnitude, or the correct result would cause +underflow, 0 shall be returned and a range error may occur. +.P +If +.IR x +is NaN, a NaN shall be returned. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +was too large in magnitude, or an underflow occurred. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.P +No other errors shall occur. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIy0\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/jrand48.3p b/man-pages-posix-2013-a/man3p/jrand48.3p new file mode 100644 index 0000000..745ecf1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/jrand48.3p @@ -0,0 +1,38 @@ +'\" et +.TH JRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +jrand48 +\(em generate a uniformly distributed pseudo-random long signed integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long jrand48(unsigned short \fIxsubi\fR[3]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/kill.3p b/man-pages-posix-2013-a/man3p/kill.3p new file mode 100644 index 0000000..bf47e0e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/kill.3p @@ -0,0 +1,287 @@ +'\" et +.TH KILL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +kill +\(em send a signal to a process or a group of processes +.SH SYNOPSIS +.LP +.nf +#include +.P +int kill(pid_t \fIpid\fP, int \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIkill\fR() +function shall send a signal to a process or a group of processes +specified by +.IR pid . +The signal to be sent is specified by +.IR sig +and is either one from the list given in +.IR +or 0. If +.IR sig +is 0 (the null signal), error checking is performed but no signal is +actually sent. The null signal can be used to check the validity of +.IR pid . +.P +For a process to have permission to send a signal to a process +designated by +.IR pid , +unless the sending process has appropriate privileges, the real or +effective user ID of the sending process shall match the real or saved +set-user-ID of the receiving process. +.P +If +.IR pid +is greater than 0, +.IR sig +shall be sent to the process whose process ID is equal to +.IR pid . +.P +If +.IR pid +is 0, +.IR sig +shall be sent to all processes (excluding an unspecified set of system +processes) whose process group ID is equal to the process group ID of +the sender, and for which the process has permission to send a signal. +.P +If +.IR pid +is \(mi1, +.IR sig +shall be sent to all processes (excluding an unspecified set of system +processes) for which the process has permission to send that signal. +.P +If +.IR pid +is negative, but not \(mi1, +.IR sig +shall be sent to all processes (excluding an unspecified set of system +processes) whose process group ID is equal to the absolute value of +.IR pid , +and for which the process has permission to send a signal. +.P +If the value of +.IR pid +causes +.IR sig +to be generated for the sending process, and if +.IR sig +is not blocked for the calling thread and if no other thread has +.IR sig +unblocked or is waiting in a +\fIsigwait\fR() +function for +.IR sig , +either +.IR sig +or at least one pending unblocked signal shall be delivered to the +sending thread before +\fIkill\fR() +returns. +.P +The user ID tests described above shall not be applied when sending +SIGCONT to a process that is a member of the same session as the +sending process. +.P +An implementation that provides extended security controls may impose +further implementation-defined restrictions on the sending of +signals, including the null signal. In particular, the system may deny +the existence of some or all of the processes specified by +.IR pid . +.P +The +\fIkill\fR() +function is successful if the process has permission to send +.IR sig +to any of the processes specified by +.IR pid . +If +\fIkill\fR() +fails, no signal shall be sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIkill\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR sig +argument is an invalid or unsupported signal number. +.TP +.BR EPERM +The process does not have permission to send the signal to any +receiving process. +.TP +.BR ESRCH +No process or process group can be found corresponding to that +specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The semantics for permission checking for +\fIkill\fR() +differed between System V and most other implementations, such as +Version 7 or +4.3 BSD. The semantics chosen for this volume of POSIX.1\(hy2008 agree with System V. +Specifically, a set-user-ID +process cannot protect itself against signals (or at least not against +SIGKILL) +unless it changes its real user ID. +This choice allows the user who starts an application to send it +signals even if it changes its effective user ID. +The other semantics give more power to an application that wants to +protect itself from the user who ran it. +.P +Some implementations provide semantic extensions to the +\fIkill\fR() +function when the absolute value of +.IR pid +is greater than some maximum, or otherwise special, value. Negative +values are a flag to +\fIkill\fR(). +Since most implementations return +.BR [ESRCH] +in this case, this behavior is not included in this volume of POSIX.1\(hy2008, although +a conforming implementation could provide such an extension. +.P +The unspecified processes to which a signal cannot be sent +may include the scheduler or +.IR init . +.P +There was initially strong sentiment to specify that, if +.IR pid +specifies that a signal be sent to the calling process and that signal +is not blocked, that signal would be delivered before +\fIkill\fR() +returns. This would permit a process to call +\fIkill\fR() +and be guaranteed that the call never return. However, historical +implementations that provide only the +\fIsignal\fR() +function make only the weaker guarantee in this volume of POSIX.1\(hy2008, because they +only deliver one signal each time a process enters the kernel. +Modifications to such implementations to support the +\fIsigaction\fR() +function generally require entry to the kernel following return from a +signal-catching function, in order to restore the signal mask. Such +modifications have the effect of satisfying the stronger requirement, +at least when +\fIsigaction\fR() +is used, but not necessarily when +\fIsignal\fR() +is used. The standard developers considered making the +stronger requirement except when +\fIsignal\fR() +is used, but felt this would be unnecessarily complex. Implementors +are encouraged to meet the stronger requirement whenever possible. In +practice, the weaker requirement is the same, except in the rare case +when two signals arrive during a very short window. This reasoning +also applies to a similar requirement for +\fIsigprocmask\fR(). +.P +In 4.2 BSD, the SIGCONT +signal can be sent to any descendant process regardless of user-ID +security checks. +This allows a job control shell to continue a job even if processes in +the +job have altered their user IDs (as in the +.IR su +command). In keeping with the addition of the concept of sessions, +similar functionality is provided by allowing the SIGCONT +signal to be sent to any process in the same session regardless of user +ID security checks. This is less restrictive than BSD in the sense +that ancestor processes (in the same session) can now be the recipient. +It is more restrictive than BSD in the sense that descendant processes +that form new sessions are now subject to the user ID checks. A similar +relaxation of security is not necessary for the other job control +signals since those signals are typically sent by the terminal driver +in recognition of special characters being typed; the terminal driver +bypasses all security checks. +.P +In secure implementations, a process may be restricted +from sending a signal to a process having a different security label. +In order to prevent the existence or nonexistence of a process from +being used as a covert channel, +such processes should appear nonexistent to the sender; that is, +.BR [ESRCH] +should be returned, rather than +.BR [EPERM] , +if +.IR pid +refers only to such processes. +.P +Existing implementations vary on the result of a +\fIkill\fR() +with +.IR pid +indicating an inactive process (a terminated process that has not been +waited for by its parent). Some indicate success on such a call +(subject to permission checking), while others give an error of +.BR [ESRCH] . +Since the definition of process lifetime in this volume of POSIX.1\(hy2008 +covers inactive processes, the +.BR [ESRCH] +error as described is inappropriate in this case. In particular, this +means that an application cannot have a parent process check for +termination of a particular child with +\fIkill\fR(). +(Usually this is done with the null signal; this can be done reliably +with +\fIwaitpid\fR().) +.P +There is some belief that the name +\fIkill\fR() +is misleading, since the function is not always intended to cause +process termination. However, the name is common to all historical +implementations, and any change would be in conflict with the goal of +minimal changes to existing application code. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigqueue\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/killpg.3p b/man-pages-posix-2013-a/man3p/killpg.3p new file mode 100644 index 0000000..b578f59 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/killpg.3p @@ -0,0 +1,95 @@ +'\" et +.TH KILLPG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +killpg +\(em send a signal to a process group +.SH SYNOPSIS +.LP +.nf +#include +.P +int killpg(pid_t \fIpgrp\fP, int \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIkillpg\fR() +function shall send the signal specified by +.IR sig +to the process group specified by +.IR pgrp . +.P +If +.IR pgrp +is greater than 1, \fIkillpg\fP(\fIpgrp\fP,\ \fIsig\fR) shall be +equivalent to \fIkill\fP(\(mi\fIpgrp\fP,\ \fIsig\fR). If +.IR pgrp +is less than or equal to 1, the behavior of +\fIkillpg\fR() +is undefined. +.SH "RETURN VALUE" +Refer to +.IR "\fIkill\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIkill\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Sending a Signal to All Other Members of a Process Group" +.P +The following example shows how the calling process could send a signal +to all other members of its process group. To prevent itself from +receiving the signal it first makes itself immune to the signal by +ignoring it. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... + if (signal(SIGUSR1, SIG_IGN) == SIG_ERR) + /* Handle error */; +.P + if (killpg(getpgrp(), SIGUSR1) == \(mi1) + /* Handle error */;" +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIraise\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/l64a.3p b/man-pages-posix-2013-a/man3p/l64a.3p new file mode 100644 index 0000000..0f5e77f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/l64a.3p @@ -0,0 +1,38 @@ +'\" et +.TH L64A "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +l64a +\(em convert a 32-bit integer to a radix-64 ASCII string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *l64a(long \fIvalue\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIa64l\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/labs.3p b/man-pages-posix-2013-a/man3p/labs.3p new file mode 100644 index 0000000..f7f92ec --- /dev/null +++ b/man-pages-posix-2013-a/man3p/labs.3p @@ -0,0 +1,84 @@ +'\" et +.TH LABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +labs, +llabs +\(em return a long integer absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +long labs(long \fIi\fP); +long long llabs(long long \fIi\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIlabs\fR() +function shall compute the absolute value of the +.BR long +integer operand +.IR i . +The +\fIllabs\fR() +function shall compute the absolute value of the +.BR "long long" +integer operand +.IR i . +If the result cannot be represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIlabs\fR() +function shall return the absolute value of the +.BR long +integer operand. +.P +The +\fIllabs\fR() +function shall return the absolute value of the +.BR "long long" +integer operand. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIabs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lchown.3p b/man-pages-posix-2013-a/man3p/lchown.3p new file mode 100644 index 0000000..9528113 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lchown.3p @@ -0,0 +1,174 @@ +'\" et +.TH LCHOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lchown +\(em change the owner and group of a symbolic link +.SH SYNOPSIS +.LP +.nf +#include +.P +int lchown(const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +.fi +.SH DESCRIPTION +The +\fIlchown\fR() +function shall be equivalent to +\fIchown\fR(), +except in the case where the named file is a symbolic link. In this +case, +\fIlchown\fR() +shall change the ownership of the symbolic link file itself, while +\fIchown\fR() +changes the ownership of the file or directory to which the symbolic +link refers. +.SH "RETURN VALUE" +Upon successful completion, +\fIlchown\fR() +shall return 0. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate an error. +.SH ERRORS +The +\fIlchown\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix of +.IR path . +.TP +.BR EINVAL +The owner or group ID is not a value supported by the implementation. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP +.BR EROFS +The file resides on a read-only file system. +.P +The +\fIlchown\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading or writing to the file system. +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Current Owner of a File" +.P +The following example shows how to change the ownership of the symbolic +link named +.BR /modules/pass1 +to the user ID associated with ``jones'' and the group ID associated +with ``cnd''. +.P +The numeric value for the user ID is obtained by using the +\fIgetpwnam\fR() +function. The numeric value for the group ID is obtained by using the +\fIgetgrnam\fR() +function. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +.P +struct passwd *pwd; +struct group *grp; +char *path = "/modules/pass1"; +\&... +pwd = getpwnam("jones"); +grp = getgrnam("cnd"); +lchown(path, pwd->pw_uid, grp->gr_gid); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +On implementations which support symbolic links as directory entries +rather than files, +\fIlchown\fR() +may fail. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchown\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lcong48.3p b/man-pages-posix-2013-a/man3p/lcong48.3p new file mode 100644 index 0000000..123c84c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lcong48.3p @@ -0,0 +1,39 @@ +'\" et +.TH LCONG48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lcong48 +\(em seed a uniformly distributed pseudo-random signed long +integer generator +.SH SYNOPSIS +.LP +.nf +#include +.P +void lcong48(unsigned short \fIparam\fP[7]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ldexp.3p b/man-pages-posix-2013-a/man3p/ldexp.3p new file mode 100644 index 0000000..9355f53 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ldexp.3p @@ -0,0 +1,151 @@ +'\" et +.TH LDEXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ldexp, +ldexpf, +ldexpl +\(em load exponent of a floating-point number +.SH SYNOPSIS +.LP +.nf +#include +.P +double ldexp(double \fIx\fP, int \fIexp\fP); +float ldexpf(float \fIx\fP, int \fIexp\fP); +long double ldexpl(long double \fIx\fP, int \fIexp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the quantity +\fIx\fR\ *\ 2\u\s-3\fIexp\fR\s+3\d. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +.IR x +multiplied by 2, raised to the power +.IR exp . +.P +If these functions would cause overflow, a range error shall occur and +\fIldexp\fR(), +\fIldexpf\fR(), +and +\fIldexpl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (according +to the sign of +.IR x ), +respectively. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIldexp\fR(), +\fIldexpf\fR(), +and +\fIldexpl\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, and LDBL_MIN, +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.P +If +.IR exp +is 0, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfrexp\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ldiv.3p b/man-pages-posix-2013-a/man3p/ldiv.3p new file mode 100644 index 0000000..986e658 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ldiv.3p @@ -0,0 +1,108 @@ +'\" et +.TH LDIV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ldiv, +lldiv +\(em compute quotient and remainder of a long division +.SH SYNOPSIS +.LP +.nf +#include +.P +ldiv_t ldiv(long \fInumer\fP, long \fIdenom\fP); +lldiv_t lldiv(long long \fInumer\fP, long long \fIdenom\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the quotient and remainder of the +division of the numerator +.IR numer +by the denominator +.IR denom . +If the division is inexact, the resulting quotient is the +.BR long +integer (for the +\fIldiv\fR() +function) or +.BR "long long" +integer (for the +\fIlldiv\fR() +function) of lesser magnitude that is the nearest to the algebraic +quotient. If the result cannot be represented, the behavior is +undefined; otherwise, \fIquot\fP\ *\ \fIdenom\fP+\fIrem\fP shall equal +.IR numer . +.SH "RETURN VALUE" +The +\fIldiv\fR() +function shall return a structure of type +.BR ldiv_t , +comprising both the quotient and the remainder. The structure shall +include the following members, in any order: +.sp +.RS 4 +.nf +\fB +long quot; /* Quotient */ +long rem; /* Remainder */ +.fi \fR +.P +.RE +.P +The +\fIlldiv\fR() +function shall return a structure of type +.BR lldiv_t , +comprising both the quotient and the remainder. The structure shall +include the following members, in any order: +.sp +.RS 4 +.nf +\fB +long long quot; /* Quotient */ +long long rem; /* Remainder */ +.fi \fR +.P +.RE +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdiv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lfind.3p b/man-pages-posix-2013-a/man3p/lfind.3p new file mode 100644 index 0000000..37b088b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lfind.3p @@ -0,0 +1,39 @@ +'\" et +.TH LFIND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lfind +\(em find entry in a linear search table +.SH SYNOPSIS +.LP +.nf +#include +.P +void *lfind(const void *\fIkey\fP, const void *\fIbase\fP, size_t *\fInelp\fP, + size_t \fIwidth\fP, int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIlsearch\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lgamma.3p b/man-pages-posix-2013-a/man3p/lgamma.3p new file mode 100644 index 0000000..1714bb1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lgamma.3p @@ -0,0 +1,158 @@ +'\" et +.TH LGAMMA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.EQ +delim $$ +.EN +.SH NAME +lgamma, +lgammaf, +lgammal, +signgam +\(em log gamma function +.SH SYNOPSIS +.LP +.nf +#include +.P +double lgamma(double \fIx\fP); +float lgammaf(float \fIx\fP); +long double lgammal(long double \fIx\fP); +extern int signgam; +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute +$log_ e" " \(br \(*G ( ^ x ) \(br$ +where $\(*G ( ^ x )$ is defined as +$int from 0 to inf e"^" " "{ - t } t"^" " "{ x - 1 } dt$. +The argument +.IR x +need not be a non-positive integer ($\(*G( ^ x )$ is defined over +the reals, except the non-positive integers). +.P +If +.IR x +is NaN, \(miInf, or a negative integer, the value of +.IR signgam +is unspecified. +.P +These functions need not be thread-safe. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the +logarithmic gamma of +.IR x . +.P +If +.IR x +is a non-positive integer, a pole error shall occur and +\fIlgamma\fR(), +\fIlgammaf\fR(), +and +\fIlgammal\fR() +shall return +HUGE_VAL, +HUGE_VALF, and +HUGE_VALL, respectively. +.P +If the correct value would cause overflow, a range error shall occur +and +\fIlgamma\fR(), +\fIlgammaf\fR(), +and +\fIlgammal\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (having the +same sign as the correct value), respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is 1 or 2, +0 shall be returned. +.P +If +.IR x +is \(+-Inf, +Inf shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Pole\ Error" 12 +The +.IR x +argument is a negative integer or zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/link.3p b/man-pages-posix-2013-a/man3p/link.3p new file mode 100644 index 0000000..ba58b85 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/link.3p @@ -0,0 +1,437 @@ +'\" et +.TH LINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +link, linkat +\(em link one file to another file relative to two directory +file descriptors +.SH SYNOPSIS +.LP +.nf +#include +.P +int link(const char *\fIpath1\fP, const char *\fIpath2\fP); +int linkat(int \fIfd1\fP, const char *\fIpath1\fP, int \fIfd2\fP, + const char *\fIpath2\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIlink\fR() +function shall create a new link (directory entry) for the existing file, +.IR path1 . +.P +The +.IR path1 +argument points to a pathname naming an existing file. The +.IR path2 +argument points to a pathname naming the new directory entry to be +created. The +\fIlink\fR() +function shall atomically create a new link for the existing file and +the link count of the file shall be incremented by one. +.P +If +.IR path1 +names a directory, +\fIlink\fR() +shall fail unless the process has appropriate privileges and the +implementation supports using +\fIlink\fR() +on directories. +.P +If +.IR path1 +names a symbolic link, it is implementation-defined whether +\fIlink\fR() +follows the symbolic link, or creates a new link to the symbolic +link itself. +.P +Upon successful completion, +\fIlink\fR() +shall mark for update the last file status change timestamp of the +file. Also, the last data modification and last file status change +timestamps of the directory that contains the new entry shall be marked +for update. +.P +If +\fIlink\fR() +fails, no link shall be created and the link count of the file shall +remain unchanged. +.P +The implementation may require that the calling process has permission +to access the existing file. +.P +The +\fIlinkat\fR() +function shall be equivalent to the +\fIlink\fR() +function except that symbolic links shall be handled as specified by +the value of +.IR flag +(see below) and except in the case where either +.IR path1 +or +.IR path2 +or both are relative paths. In this case a relative path +.IR path1 +is interpreted relative to the directory associated with the file +descriptor +.IR fd1 +instead of the current working directory and similarly for +.IR path2 +and the file descriptor +.IR fd2 . +If the file descriptor was opened without O_SEARCH, the function +shall check whether directory searches are permitted using the current +permissions of the directory underlying the file descriptor. If the +file descriptor was opened with O_SEARCH, the function shall not perform +the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_FOLLOW 6 +.br +If +.IR path1 +names a symbolic link, a new link for the target of the symbolic link +is created. +.P +If +\fIlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd1 +or +.IR fd2 +parameter, the current working directory shall be used for the respective +.IR path +argument. If both +.IR fd1 +and +.IR fd2 +have value AT_FDCWD, the behavior shall be identical to a call to +\fIlink\fR(), +except that symbolic links shall be handled as specified by the value of +.IR flag . +.P +If the AT_SYMLINK_FOLLOW flag is clear in the +.IR flag +argument and the +.IR path1 +argument names a symbolic link, a new link is created for the symbolic +link +.IR path1 +and not its target. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. Otherwise, +these functions shall return \(mi1 and set +.IR errno +to indicate the error. +.br +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +A component of either path prefix denies search permission, or the +requested link requires writing in a directory that denies write +permission, or the calling process does not have permission to access +the existing file and this is required by the implementation. +.TP +.BR EEXIST +The +.IR path2 +argument resolves to an existing directory entry or refers to a symbolic +link. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path1 +or +.IR path2 +argument. +.TP +.BR EMLINK +The number of links to the file named by +.IR path1 +would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of either path prefix does not exist; the file named by +.IR path1 +does not exist; or +.IR path1 +or +.IR path2 +points to an empty string. +.TP +.BR ENOSPC +The directory to contain the link cannot be extended. +.TP +.BR ENOTDIR +A component of either path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path1 +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory, or the +.IR path1 +argument names an existing non-directory file and the +.IR path2 +argument names a nonexistent file, contains at least one non-\c + +character, and ends with one or more trailing + +characters. +.TP +.BR EPERM +The file named by +.IR path1 +is a directory and either the calling process does not have appropriate +privileges or the implementation prohibits using +\fIlink\fR() +on directories. +.TP +.BR EROFS +The requested link requires writing in a directory on a read-only file +system. +.TP +.BR EXDEV +The link named by +.IR path2 +and the file named by +.IR path1 +are on different file systems and the implementation does not support +links between file systems. +.TP +.BR EXDEV +.IR path1 +refers to a named STREAM. +.P +The +\fIlinkat\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR path1 +or +.IR path2 +argument does not specify an absolute path and the +.IR fd1 +or +.IR fd2 +argument, respectively, is neither AT_FDCWD nor a valid file descriptor +open for reading or searching. +.TP +.BR ENOTDIR +The +.IR path1 +or +.IR path2 +argument is not an absolute path and +.IR fd1 +or +.IR fd2 , +respectively, is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path1 +or +.IR path2 +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.br +.P +The +\fIlinkat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a Link to a File" +.P +The following example shows how to create a link to a file named +.BR /home/cnd/mod1 +by creating a new directory entry named +.BR /modules/pass1 . +.sp +.RS 4 +.nf +\fB +#include +.P +char *path1 = "/home/cnd/mod1"; +char *path2 = "/modules/pass1"; +int status; +\&... +status = link (path1, path2); +.fi \fR +.P +.RE +.SS "Creating a Link to a File Within a Program" +.P +In the following program example, the +\fIlink\fR() +function links the +.BR /etc/passwd +file (defined as +.BR PASSWDFILE ) +to a file named +.BR /etc/opasswd +(defined as +.BR SAVEFILE ), +which is used to save the current password file. Then, after removing +the current password file (defined as +.BR PASSWDFILE ), +the new password file is saved as the current password file using the +\fIlink\fR() +function again. +.sp +.RS 4 +.nf +\fB +#include +.P +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +#define SAVEFILE "/etc/opasswd" +\&... +/* Save current password file */ +link (PASSWDFILE, SAVEFILE); +.P +/* Remove current password file. */ +unlink (PASSWDFILE); +.P +/* Save new password file as current password file. */ +link (LOCKFILE,PASSWDFILE); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Some implementations do allow links between file systems. +.P +If +.IR path1 +refers to a symbolic link, application developers should use +\fIlinkat\fR() +with appropriate flags to select whether or not the symbolic link should +be resolved. +.SH RATIONALE +Linking to a directory is restricted to the superuser +in most historical implementations because this capability may produce +loops in the file hierarchy or otherwise corrupt the file system. This volume of POSIX.1\(hy2008 +continues that philosophy by prohibiting +\fIlink\fR() +and +\fIunlink\fR() +from doing this. Other functions could do it if the implementor designed +such an extension. +.P +Some historical implementations allow linking of files on different file +systems. Wording was added to explicitly allow this optional behavior. +.P +The exception for cross-file system links is intended to apply only to +links that are programmatically indistinguishable from ``hard'' links. +.P +The purpose of the +\fIlinkat\fR() +function is to link files in directories other than the current working +directory without exposure to race conditions. Any part of the path of +a file could be changed in parallel to a call to +\fIlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for the +directory of both the existing file and the target location and using the +\fIlinkat\fR() +function it can be guaranteed that the both filenames are in the desired +directories. +.P +The AT_SYMLINK_FOLLOW flag allows for implementing both common behaviors +of the +\fIlink\fR() +function. The POSIX specification requires that if +.IR path1 +is a symbolic link, a new link for the target of the symbolic link is +created. Many systems by default or as an alternative provide a mechanism +to avoid the implicit symbolic link lookup and create a new link for +the symbolic link itself. +.P +Earlier versions of this standard specified only the +\fIlink\fR() +function, and required it to behave like +\fIlinkat\fR() +with the AT_SYMLINK_FOLLOW flag. However, historical practice from SVR4 +and Linux kernels had +\fIlink\fR() +behaving like +\fIlinkat\fR() +with no flags, and many systems that attempted to provide a conforming +\fIlink\fR() +function did so in a way that was rarely used, and when it was used +did not conform to the standard (e.g., by not being atomic, or by +dereferencing the symbolic link incorrectly). Since applications could +not rely on +\fIlink\fR() +following links in practice, the +\fIlinkat\fR() +function was added taking a flag to specify the desired behavior +for the application. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrename\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lio_listio.3p b/man-pages-posix-2013-a/man3p/lio_listio.3p new file mode 100644 index 0000000..5d0dd3f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lio_listio.3p @@ -0,0 +1,354 @@ +'\" et +.TH LIO_LISTIO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lio_listio +\(em list directed I/O +.SH SYNOPSIS +.LP +.nf +#include +.P +int lio_listio(int \fImode\fP, struct aiocb *restrict const \fIlist\fP[restrict], + int \fInent\fP, struct sigevent *restrict \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIlio_listio\fR() +function shall initiate a list of I/O requests with a single +function call. +.P +The +.IR mode +argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in +.IR +and determines whether the function returns when the I/O operations +have been completed, or as soon as the operations have been queued. If +the +.IR mode +argument is LIO_WAIT, the function shall wait until all I/O is +complete and the +.IR sig +argument shall be ignored. +.P +If the +.IR mode +argument is LIO_NOWAIT, the function shall return immediately, and +asynchronous notification shall occur, according to the +.IR sig +argument, when all the I/O operations complete. If +.IR sig +is NULL, then no asynchronous notification shall occur. If +.IR sig +is not NULL, asynchronous notification occurs as specified in +.IR "Section 2.4.1" ", " "Signal Generation and Delivery" +when all the requests in +.IR list +have completed. +.P +The I/O requests enumerated by +.IR list +are submitted in an unspecified order. +.P +The +.IR list +argument is an array of pointers to +.BR aiocb +structures. The array contains +.IR nent +elements. The array may contain NULL elements, which shall be ignored. +.P +If the buffer pointed to by +.IR list +or the +.BR aiocb +structures pointed to by the elements of the array +.IR list +become illegal addresses before all asynchronous I/O completed and, if +necessary, the notification is sent, then the behavior is undefined. If +the buffers pointed to by the +.IR aio_buf +member of the +.BR aiocb +structure pointed to by the elements of the array +.IR list +become illegal addresses prior to the asynchronous I/O associated with +that +.BR aiocb +structure being completed, the behavior is undefined. +.P +The +.IR aio_lio_opcode +field of each +.BR aiocb +structure specifies the operation to be performed. The supported +operations are LIO_READ, LIO_WRITE, and LIO_NOP; +these symbols are defined in +.IR . +The LIO_NOP operation causes the list entry to be ignored. If the +.IR aio_lio_opcode +element is equal to LIO_READ, then an I/O operation is submitted as if +by a call to +\fIaio_read\fR() +with the +.IR aiocbp +equal to the address of the +.BR aiocb +structure. If the +.IR aio_lio_opcode +element is equal to LIO_WRITE, then an I/O operation is submitted as if +by a call to +\fIaio_write\fR() +with the +.IR aiocbp +equal to the address of the +.BR aiocb +structure. +.P +The +.IR aio_fildes +member specifies the file descriptor on which the operation is to be +performed. +.P +The +.IR aio_buf +member specifies the address of the buffer to or from which the data is +transferred. +.P +The +.IR aio_nbytes +member specifies the number of bytes of data to be transferred. +.P +The members of the +.BR aiocb +structure further describe the I/O operation to be performed, in a +manner identical to that of the corresponding +.BR aiocb +structure when used by the +\fIaio_read\fR() +and +\fIaio_write\fR() +functions. +.P +The +.IR nent +argument specifies how many elements are members of the list; that is, +the length of the array. +.P +The behavior of this function is altered according to the definitions +of synchronized I/O data integrity completion and synchronized I/O file +integrity completion if synchronized I/O is enabled on the file +associated with +.IR aio_fildes . +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fR\->\fIaio_fildes\fR. +.P +If \fIsig\fR\->\fIsigev_notify\fR is SIGEV_THREAD and +\fIsig\fR\->\fIsigev_notify_attributes\fR is a non-null pointer and the +block pointed to by this pointer becomes an illegal address prior to +all asynchronous I/O being completed, then the behavior is undefined. +.SH "RETURN VALUE" +If the +.IR mode +argument has the value LIO_NOWAIT, the +\fIlio_listio\fR() +function shall return the value zero if the I/O operations are +successfully queued; otherwise, the function shall return the value +\(mi1 and set +.IR errno +to indicate the error. +.P +If the +.IR mode +argument has the value LIO_WAIT, the +\fIlio_listio\fR() +function shall return the value zero when all the indicated I/O has +completed successfully. Otherwise, +\fIlio_listio\fR() +shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.P +In either case, the return value only indicates the success or failure +of the +\fIlio_listio\fR() +call itself, not the status of the individual I/O requests. In some +cases one or more of the I/O requests contained in the list may fail. +Failure of an individual request does not prevent completion of any +other individual request. To determine the outcome of each I/O +request, the application shall examine the error status associated with +each +.BR aiocb +control block. The error statuses so returned are identical to those +returned as the result of an +\fIaio_read\fR() +or +\fIaio_write\fR() +function. +.SH ERRORS +The +\fIlio_listio\fR() +function shall fail if: +.TP +.BR EAGAIN +The resources necessary to queue all the I/O requests were not +available. The application may check the error status for each +.BR aiocb +to determine the individual request(s) that failed. +.TP +.BR EAGAIN +The number of entries indicated by +.IR nent +would cause the system-wide limit +{AIO_MAX} +to be exceeded. +.TP +.BR EINVAL +The +.IR mode +argument is not a proper value, or the value of +.IR nent +was greater than +{AIO_LISTIO_MAX}. +.TP +.BR EINTR +A signal was delivered while waiting for all I/O requests to complete +during an LIO_WAIT operation. Note that, since each I/O operation +invoked by +\fIlio_listio\fR() +may possibly provoke a signal when it completes, this error return may +be caused by the completion of one (or more) of the very I/O operations +being awaited. Outstanding I/O requests are not canceled, and the +application shall examine each list element to determine whether the +request was initiated, canceled, or completed. +.TP +.BR EIO +One or more of the individual I/O operations failed. The application +may check the error status for each +.BR aiocb +structure to determine the individual request(s) that failed. +.P +In addition to the errors returned by the +\fIlio_listio\fR() +function, if the +\fIlio_listio\fR() +function succeeds or fails with errors of +.BR [EAGAIN] , +.BR [EINTR] , +or +.BR [EIO] , +then some of the I/O specified by the list may have been initiated. If +the +\fIlio_listio\fR() +function fails with an error code other than +.BR [EAGAIN] , +.BR [EINTR] , +or +.BR [EIO] , +no operations from the list shall have been initiated. The I/O operation +indicated by each list element can encounter errors specific to the +individual read or write function being performed. In this event, the +error status for each +.BR aiocb +control block contains the associated error code. The error codes that +can be set are the same as would be set by a +\fIread\fR() +or +\fIwrite\fR() +function, with the following additional error codes possible: +.TP +.BR EAGAIN +The requested I/O operation was not queued due to resource limitations. +.TP +.BR ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit +\fIaio_cancel\fR() +request. +.TP +.BR EFBIG +The \fIaiocbp\fP\->\fIaio_lio_opcode\fP is LIO_WRITE, the file is a +regular file, \fIaiocbp\fP\->\fIaio_nbytes\fP is greater than 0, and +the \fIaiocbp\fP\->\fIaio_offset\fP is greater than or equal to the +offset maximum in the open file description associated with +\fIaiocbp\fP\->\fIaio_fildes\fP. +.TP +.BR EINPROGRESS +The requested I/O is in progress. +.TP +.BR EOVERFLOW +The \fIaiocbp\fP\->\fIaio_lio_opcode\fP is LIO_READ, the file is a +regular file, \fIaiocbp\fP\->\fIaio_nbytes\fP is greater than 0, and +the \fIaiocbp\fP\->\fIaio_offset\fP is before the end-of-file and is +greater than or equal to the offset maximum in the open file +description associated with \fIaiocbp\fP\->\fIaio_fildes\fP. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Although it may appear that there are inconsistencies in the specified +circumstances for error codes, the +.BR [EIO] +error condition applies when any circumstance relating to an individual +operation makes that operation fail. This might be due to a badly +formulated request (for example, the +.IR aio_lio_opcode +field is invalid, and +\fIaio_error\fR() +returns +.BR [EINVAL] ) +or might arise from application behavior (for example, the file +descriptor is closed before the operation is initiated, and +\fIaio_error\fR() +returns +.BR [EBADF] ). +.P +The limitation on the set of error codes returned when operations from +the list shall have been initiated enables applications to know when +operations have been started and whether +\fIaio_error\fR() +is valid for a specific operation. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/listen.3p b/man-pages-posix-2013-a/man3p/listen.3p new file mode 100644 index 0000000..15196c6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/listen.3p @@ -0,0 +1,153 @@ +'\" et +.TH LISTEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +listen +\(em listen for socket connections and limit the queue of incoming +connections +.SH SYNOPSIS +.LP +.nf +#include +.P +int listen(int \fIsocket\fP, int \fIbacklog\fP); +.fi +.SH DESCRIPTION +The +\fIlisten\fR() +function shall mark a connection-mode socket, specified by the +.IR socket +argument, as accepting connections. +.P +The +.IR backlog +argument provides a hint to the implementation which the implementation +shall use to limit the number of outstanding connections in the +socket's listen queue. Implementations may impose a limit on +.IR backlog +and silently reduce the specified value. Normally, a larger +.IR backlog +argument value shall result in a larger or equal length of the listen +queue. Implementations shall support values of +.IR backlog +up to SOMAXCONN, defined in +.IR . +.P +The implementation may include incomplete connections in its listen +queue. The limits on the number of incomplete connections and completed +connections queued may be different. +.P +The implementation may have an upper limit on the length of the listen +queue\(emeither global or per accepting socket. If +.IR backlog +exceeds this limit, the length of the listen queue is set to the +limit. +.P +If +\fIlisten\fR() +is called with a +.IR backlog +argument value that is less than 0, the function behaves as if it had +been called with a +.IR backlog +argument value of 0. +.P +A +.IR backlog +argument of 0 may allow the socket to accept connections, in which case +the length of the listen queue may be set to an +implementation-defined minimum value. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIlisten\fR() +function. +.SH "RETURN VALUE" +Upon successful completions, +\fIlisten\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIlisten\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EDESTADDRREQ +.br +The socket is not bound to a local address, and the protocol does not +support listening on an unbound socket. +.TP +.BR EINVAL +The +.IR socket +is already connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The socket protocol does not support +\fIlisten\fR(). +.P +The +\fIlisten\fR() +function may fail if: +.TP +.BR EACCES +The calling process does not have appropriate privileges. +.TP +.BR EINVAL +The +.IR socket +has been shut down. +.TP +.BR ENOBUFS +Insufficient resources are available in the system to complete the +call. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/llabs.3p b/man-pages-posix-2013-a/man3p/llabs.3p new file mode 100644 index 0000000..2752bfc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/llabs.3p @@ -0,0 +1,38 @@ +'\" et +.TH LLABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +llabs +\(em return a long integer absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +long long llabs(long long \fIi\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIlabs\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lldiv.3p b/man-pages-posix-2013-a/man3p/lldiv.3p new file mode 100644 index 0000000..4aa646d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lldiv.3p @@ -0,0 +1,38 @@ +'\" et +.TH LLDIV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lldiv +\(em compute quotient and remainder of a long division +.SH SYNOPSIS +.LP +.nf +#include +.P +lldiv_t lldiv(long long \fInumer\fP, long long \fIdenom\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIldiv\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/llrint.3p b/man-pages-posix-2013-a/man3p/llrint.3p new file mode 100644 index 0000000..94eaa85 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/llrint.3p @@ -0,0 +1,147 @@ +'\" et +.TH LLRINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +llrint, +llrintf, +llrintl +\(em round to the nearest integer value using current rounding direction +.SH SYNOPSIS +.LP +.nf +#include +.P +long long llrint(double \fIx\fP); +long long llrintf(float \fIx\fP); +long long llrintl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer +value, rounding according to the current rounding direction. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +.P +If +.IR x +is NaN, a domain error shall occur, and an unspecified value is +returned. +.P +If +.IR x +is +Inf, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is \(miInf, a domain error shall occur and an unspecified value is +returned. +.P +If the correct value is positive and too large to represent as a +.BR "long long" , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, +a domain error shall occur; +otherwise, a +domain +error may occur. +.P +If the correct value is negative and too large to represent as a +.BR "long long" , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, +a domain error shall occur; +otherwise, a +domain +error may occur. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is NaN or \(+-Inf, or the correct value is not representable +as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions provide floating-to-integer conversions. They round +according to the current rounding direction. If the rounded value is +outside the range of the return type, the numeric result is unspecified +and the invalid floating-point exception is raised. When they raise no +other floating-point exception and the result differs from the +argument, they raise the inexact floating-point exception. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlrint\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/llround.3p b/man-pages-posix-2013-a/man3p/llround.3p new file mode 100644 index 0000000..0c04972 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/llround.3p @@ -0,0 +1,149 @@ +'\" et +.TH LLROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +llround, +llroundf, +llroundl +\(em round to nearest integer value +.SH SYNOPSIS +.LP +.nf +#include +.P +long long llround(double \fIx\fP); +long long llroundf(float \fIx\fP); +long long llroundl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer +value, rounding halfway cases away from zero, regardless of the current +rounding direction. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +.P +If +.IR x +is NaN, a domain error shall occur, and an unspecified value is +returned. +.P +If +.IR x +is +Inf, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is \(miInf, a domain error shall occur and an unspecified value is +returned. +.P +If the correct value is positive and too large to represent as a +.BR "long long" , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur; +otherwise, a +domain +error may occur. +.P +If the correct value is negative and too large to represent as a +.BR "long long" , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur; +otherwise, a +domain +error may occur. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is NaN or \(+-Inf, or the correct value is not representable +as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions differ from the +\fIllrint\fR() +functions in that the default rounding direction for the +\fIllround\fR() +functions round halfway cases away from zero and need not raise the +inexact floating-point exception for non-integer arguments that round +to within the range of the return type. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlround\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/localeconv.3p b/man-pages-posix-2013-a/man3p/localeconv.3p new file mode 100644 index 0000000..61fbb0e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/localeconv.3p @@ -0,0 +1,362 @@ +'\" et +.TH LOCALECONV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +localeconv +\(em return locale-specific information +.SH SYNOPSIS +.LP +.nf +#include +.P +struct lconv *localeconv(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIlocaleconv\fR() +function shall set the components of an object with the type +.BR "struct lconv" +with the values appropriate for the formatting of numeric quantities +(monetary and otherwise) according to the rules of the current locale. +.P +The members of the structure with type +.BR "char *" +are pointers to strings, any of which (except +.BR decimal_point ) +can point to +.BR \(dq\^\(dq , +to indicate that the value is not available in the current locale or is +of zero length. The members with type +.BR char +are non-negative numbers, any of which can be +{CHAR_MAX} +to indicate that the value is not available in the current locale. +.P +The members include the following: +.IP "\fBchar\ *decimal_point\fP" 6 +.br +The radix character used to format non-monetary quantities. +.IP "\fBchar\ *thousands_sep\fP" 6 +.br +The character used to separate groups of digits before the +decimal-point character in formatted non-monetary quantities. +.IP "\fBchar\ *grouping\fP" 6 +.br +A string whose elements taken as one-byte integer values indicate the +size of each group of digits in formatted non-monetary quantities. +.IP "\fBchar\ *int_curr_symbol\fP" 6 +.br +The international currency symbol applicable to the current locale. +The first three characters contain the alphabetic international +currency symbol in accordance with those specified in the ISO\ 4217:\|2001 standard. The +fourth character (immediately preceding the null byte) is the character +used to separate the international currency symbol from the monetary +quantity. +.IP "\fBchar\ *currency_symbol\fP" 6 +.br +The local currency symbol applicable to the current locale. +.IP "\fBchar\ *mon_decimal_point\fP" 6 +.br +The radix character used to format monetary quantities. +.IP "\fBchar\ *mon_thousands_sep\fP" 6 +.br +The separator for groups of digits before the decimal-point in +formatted monetary quantities. +.IP "\fBchar\ *mon_grouping\fP" 6 +.br +A string whose elements taken as one-byte integer values indicate the +size of each group of digits in formatted monetary quantities. +.IP "\fBchar\ *positive_sign\fP" 6 +.br +The string used to indicate a non-negative valued formatted monetary +quantity. +.IP "\fBchar\ *negative_sign\fP" 6 +.br +The string used to indicate a negative valued formatted monetary +quantity. +.IP "\fBchar\ int_frac_digits\fP" 6 +.br +The number of fractional digits (those after the decimal-point) to be +displayed in an internationally formatted monetary quantity. +.IP "\fBchar\ frac_digits\fP" 6 +.br +The number of fractional digits (those after the decimal-point) to be +displayed in a formatted monetary quantity. +.IP "\fBchar\ p_cs_precedes\fP" 6 +.br +Set to 1 if the +.BR currency_symbol +precedes the value for a non-negative formatted monetary quantity. Set +to 0 if the symbol succeeds the value. +.IP "\fBchar\ p_sep_by_space\fP" 6 +.br +Set to a value indicating the separation of the +.BR currency_symbol , +the sign string, and the value for a non-negative formatted monetary +quantity. +.IP "\fBchar\ n_cs_precedes\fP" 6 +.br +Set to 1 if the +.BR currency_symbol +precedes the value for a negative formatted monetary quantity. Set +to 0 if the symbol succeeds the value. +.IP "\fBchar\ n_sep_by_space\fP" 6 +.br +Set to a value indicating the separation of the +.BR currency_symbol , +the sign string, and the value for a negative formatted monetary +quantity. +.IP "\fBchar\ p_sign_posn\fP" 6 +.br +Set to a value indicating the positioning of the +.BR positive_sign +for a non-negative formatted monetary quantity. +.IP "\fBchar\ n_sign_posn\fP" 6 +.br +Set to a value indicating the positioning of the +.BR negative_sign +for a negative formatted monetary quantity. +.IP "\fBchar\ int_p_cs_precedes\fP" 6 +.br +Set to 1 or 0 if the +.BR int_curr_symbol +respectively precedes or succeeds the value for a non-negative +internationally formatted monetary quantity. +.IP "\fBchar\ int_n_cs_precedes\fP" 6 +.br +Set to 1 or 0 if the +.BR int_curr_symbol +respectively precedes or succeeds the value for a negative +internationally formatted monetary quantity. +.IP "\fBchar\ int_p_sep_by_space\fP" 6 +.br +Set to a value indicating the separation of the +.BR int_curr_symbol , +the sign string, and the value for a non-negative internationally +formatted monetary quantity. +.IP "\fBchar\ int_n_sep_by_space\fP" 6 +.br +Set to a value indicating the separation of the +.BR int_curr_symbol , +the sign string, and the value for a negative internationally formatted +monetary quantity. +.IP "\fBchar\ int_p_sign_posn\fP" 6 +.br +Set to a value indicating the positioning of the +.BR positive_sign +for a non-negative internationally formatted monetary quantity. +.IP "\fBchar\ int_n_sign_posn\fP" 6 +.br +Set to a value indicating the positioning of the +.BR negative_sign +for a negative internationally formatted monetary quantity. +.P +The elements of +.BR grouping +and +.BR mon_grouping +are interpreted according to the following: +.IP {CHAR_MAX} 12 +No further grouping is to be performed. +.IP 0 12 +The previous element is to be repeatedly used for the remainder of the +digits. +.IP "\fIother\fP" 12 +The integer value is the number of digits that comprise the current +group. The next element is examined to determine the size of the next +group of digits before the current group. +.P +The values of +.BR p_sep_by_space , +.BR n_sep_by_space , +.BR int_p_sep_by_space , +and +.BR int_n_sep_by_space +are interpreted according to the following: +.IP 0 6 +No space separates the currency symbol and value. +.IP 1 6 +If the currency symbol and sign string are adjacent, a space separates +them from the value; otherwise, a space separates the currency symbol +from the value. +.IP 2 6 +If the currency symbol and sign string are adjacent, a space separates +them; otherwise, a space separates the sign string from the value. +.P +For +.BR int_p_sep_by_space +and +.BR int_n_sep_by_space , +the fourth character of +.BR int_curr_symbol +is used instead of a space. +.P +The values of +.BR p_sign_posn , +.BR n_sign_posn , +.BR int_p_sign_posn , +and +.BR int_n_sign_posn +are interpreted according to the following: +.IP 0 6 +Parentheses surround the quantity and +.BR currency_symbol +or +.BR int_curr_symbol . +.IP 1 6 +The sign string precedes the quantity and +.BR currency_symbol +or +.BR int_curr_symbol . +.IP 2 6 +The sign string succeeds the quantity and +.BR currency_symbol +or +.BR int_curr_symbol . +.IP 3 6 +The sign string immediately precedes the +.BR currency_symbol +or +.BR int_curr_symbol . +.IP 4 6 +The sign string immediately succeeds the +.BR currency_symbol +or +.BR int_curr_symbol . +.P +The implementation shall behave as if no function in this volume of POSIX.1\(hy2008 calls +\fIlocaleconv\fR(). +.P +The +\fIlocaleconv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIlocaleconv\fR() +function shall return a pointer to the filled-in object. The application +shall not modify the structure to which the return value points, +nor any storage areas pointed to by pointers within the structure. The +returned pointer, and pointers within the structure, might be +invalidated or +the structure +or the storage areas +might be overwritten by a subsequent call to +\fIlocaleconv\fR(). +In addition, +the returned pointer, and pointers within the structure, might be +invalidated or +the structure +or the storage areas +might be overwritten by subsequent calls to +\fIsetlocale\fR() +with the categories LC_ALL, LC_MONETARY, or LC_NUMERIC, +or by calls to +\fIuselocale\fR() +which change the categories LC_MONETARY or LC_NUMERIC. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The following table illustrates the rules which may be used by four +countries to format monetary quantities. +.TS +center box tab(!); +cB | cB | cB | cB +l | l | l | l. +Country!Positive Format!Negative Format!International Format +_ +Italy!\(eu.1.230!\(mi\(eu.1.230!EUR.1.230 +Netherlands!\(eu 1.234,56!\(eu \(mi1.234,56!EUR 1.234,56 +Norway!kr1.234,56!kr1.234,56\(mi!NOK 1.234,56 +Switzerland!SFrs.1,234.56!SFrs.1,234.56C!CHF 1,234.56 +.TE +.P +For these four countries, the respective values for the monetary +members of the structure returned by +\fIlocaleconv\fR() +are: +.TS +center box tab(!); +cB | cB | cB | cB | cB +lb | cf5 | cf5 | cf5 | cf5. +!Italy!Netherlands!Norway!Switzerland +_ +int_curr_symbol!"EUR."!"EUR "!"NOK "!"CHF " +currency_symbol!"\(eu."!"\(eu"!"kr"!"SFrs." +mon_decimal_point!""!","!","!"." +mon_thousands_sep!"."!"."!"."!"," +mon_grouping!"\e3"!"\e3"!"\e3"!"\e3" +positive_sign!""!""!""!"" +negative_sign!"-"!"-"!"-"!"C" +int_frac_digits!0!2!2!2 +frac_digits!0!2!2!2 +p_cs_precedes!1!1!1!1 +p_sep_by_space!0!1!0!0 +n_cs_precedes!1!1!1!1 +n_sep_by_space!0!1!0!0 +p_sign_posn!1!1!1!1 +n_sign_posn!1!4!2!2 +int_p_cs_precedes!1!1!1!1 +int_n_cs_precedes!1!1!1!1 +int_p_sep_by_space!0!0!0!0 +int_n_sep_by_space!0!0!0!0 +int_p_sign_posn!1!1!1!1 +int_n_sign_posn!1!4!4!2 +.TE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisascii\fR\^(\|)", +.IR "\fInl_langinfo\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrcat\fR\^(\|)", +.IR "\fIstrchr\fR\^(\|)", +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)", +.IR "\fIstrcpy\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrlen\fR\^(\|)", +.IR "\fIstrpbrk\fR\^(\|)", +.IR "\fIstrspn\fR\^(\|)", +.IR "\fIstrtok\fR\^(\|)", +.IR "\fIstrxfrm\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/localtime.3p b/man-pages-posix-2013-a/man3p/localtime.3p new file mode 100644 index 0000000..3459412 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/localtime.3p @@ -0,0 +1,276 @@ +'\" et +.TH LOCALTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +localtime, +localtime_r +\(em convert a time value to a broken-down local time +.SH SYNOPSIS +.LP +.nf +#include +.P +struct tm *localtime(const time_t *\fItimer\fP); +struct tm *localtime_r(const time_t *restrict \fItimer\fP, + struct tm *restrict \fIresult\fP); +.fi +.SH DESCRIPTION +For +\fIlocaltime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIlocaltime\fR() +function shall convert the time in seconds since the Epoch pointed +to by +.IR timer +into a broken-down time, expressed as a local time. The function +corrects for the timezone and any seasonal time adjustments. +Local timezone information is used as though +\fIlocaltime\fR() +calls +\fItzset\fR(). +.P +The relationship between a time in seconds since the Epoch used as an +argument to +\fIlocaltime\fR() +and the +.BR tm +structure (defined in the +.IR +header) is that the result shall be as specified in the expression +given in the definition of seconds since the Epoch (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch") +corrected for timezone and any seasonal time adjustments, where the +names in the structure and in the expression correspond. +.P +The same relationship shall apply for +\fIlocaltime_r\fR(). +.P +The +\fIlocaltime\fR() +function need not be thread-safe. +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of type +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIlocaltime_r\fR() +function shall convert the time in seconds since the Epoch pointed +to by +.IR timer +into a broken-down time stored in the structure to which +.IR result +points. The +\fIlocaltime_r\fR() +function shall also return a pointer to that same structure. +.P +Unlike +\fIlocaltime\fR(), +the +\fIlocaltime_r\fR() +function is not required to set +.IR tzname . +If +\fIlocaltime_r\fR() +does not set +.IR tzname , +it shall not set +.IR daylight +and shall not set +.IR timezone . +.SH "RETURN VALUE" +Upon successful completion, the +\fIlocaltime\fR() +function shall return a pointer to the broken-down time structure. +If an error is detected, +\fIlocaltime\fR() +shall return a null pointer +and set +.IR errno +to indicate the error. +.P +Upon successful completion, +\fIlocaltime_r\fR() +shall return a pointer to the structure pointed to by the argument +.IR result . +If an error is detected, +\fIlocaltime_r\fR() +shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIlocaltime\fR() +and +\fIlocaltime_r\fR() +functions shall fail if: +.TP +.BR EOVERFLOW +The result cannot be represented. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the Local Date and Time" +.P +The following example uses the +\fItime\fR() +function to calculate the time elapsed, in seconds, since January 1, +1970 0:00 UTC (the Epoch), +\fIlocaltime\fR() +to convert that value to a broken-down time, and +\fIasctime\fR() +to convert the broken-down time values into a printable string. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int main(void) +{ + time_t result; +.P + result = time(NULL); + printf("%s%ju secs since the Epoch\en", + asctime(localtime(&result)), + (uintmax_t)result); + return(0); +} +.fi \fR +.P +.RE +.P +This example writes the current time to +.IR stdout +in a form like this: +.sp +.RS 4 +.nf +\fB +Wed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +.fi \fR +.P +.RE +.SS "Getting the Modification Time for a File" +.P +The following example prints the last data modification timestamp +in the local timezone for a given file. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +int +print_file_time(const char *pathname) +{ + struct stat statbuf; + struct tm *tm; + char timestr[BUFSIZ]; +.P + if(stat(pathname, &statbuf) =\|= \(mi1) + return \(mi1; + if((tm = localtime(&statbuf.st_mtime)) =\|= NULL) + return \(mi1; + if(strftime(timestr, sizeof(timestr), "%Y-%m-%d %H:%M:%S", tm) =\|= 0) + return \(mi1; + printf("%s: %s.%09ld\en", pathname, timestr, statbuf.st_mtim.tv_nsec); + return 0; +} +.fi \fR +.P +.RE +.SS "Timing an Event" +.P +The following example gets the current time, converts it to a string +using +\fIlocaltime\fR() +and +\fIasctime\fR(), +and prints it to standard output using +\fIfputs\fR(). +It then prints the number of minutes to an event being timed. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +fputs(asctime(localtime(&now)), stdout); +printf("There are still %d minutes to the event.\en", + minutes_to_event); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIlocaltime_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgetdate\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lockf.3p b/man-pages-posix-2013-a/man3p/lockf.3p new file mode 100644 index 0000000..870fb59 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lockf.3p @@ -0,0 +1,291 @@ +'\" et +.TH LOCKF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lockf +\(em record locking on files +.SH SYNOPSIS +.LP +.nf +#include +.P +int lockf(int \fIfildes\fP, int \fIfunction\fP, off_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIlockf\fR() +function shall lock sections of a file with advisory-mode locks. Calls +to +\fIlockf\fR() +from threads in other processes which attempt to lock the locked file +section shall either return an error value or block until the section +becomes unlocked. All the locks for a process are removed when the +process terminates. Record locking with +\fIlockf\fR() +shall be supported for regular files and may be supported for other +files. +.P +The +.IR fildes +argument is an open file descriptor. To establish a lock with this +function, the file descriptor shall be opened with write-only +permission (O_WRONLY) or with read/write permission (O_RDWR). +.P +The +.IR function +argument is a control value which specifies the action to be taken. The +permissible values for +.IR function +are defined in +.IR +as follows: +.TS +box tab(!) center; +cB | cB +l | l. +Function!Description +_ +F_ULOCK!Unlock locked sections. +F_LOCK!Lock a section for exclusive use. +F_TLOCK!Test and lock a section for exclusive use. +F_TEST!Test a section for locks by other processes. +.TE +.P +F_TEST shall detect if a lock by another process is present on the +specified section. +.P +F_LOCK and F_TLOCK shall both lock a section of a file if the section +is available. +.P +F_ULOCK shall remove locks from a section of the file. +.P +The +.IR size +argument is the number of contiguous bytes to be locked or unlocked. +The section to be locked or unlocked starts at the current offset in +the file and extends forward for a positive size or backward for a +negative size (the preceding bytes up to but not including the current +offset). If +.IR size +is 0, the section from the current offset through the largest possible +file offset shall be locked (that is, from the current offset through +the present or any future end-of-file). An area need not be allocated +to the file to be locked because locks may exist past the end-of-file. +.P +The sections locked with F_LOCK or F_TLOCK may, in whole or in part, +contain or be contained by a previously locked section for the same +process. When this occurs, or if adjacent locked sections would occur, +the sections shall be combined into a single locked section. If the +request would cause the number of locks to exceed a system-imposed +limit, the request shall fail. +.P +F_LOCK and F_TLOCK requests differ only by the action taken if the +section is not available. F_LOCK shall block the calling thread until +the section is available. F_TLOCK shall cause the function to fail if +the section is already locked by another process. +.P +File locks shall be released on first close by the locking process of +any file descriptor for the file. +.P +F_ULOCK requests may release (wholly or in part) one or more locked +sections controlled by the process. Locked sections shall be unlocked +starting at the current file offset through +.IR size +bytes or to the end-of-file if +.IR size +is (\fBoff_t\fR)0. When all of a locked section is not released (that +is, when the beginning or end of the area to be unlocked falls within a +locked section), the remaining portions of that section shall remain +locked by the process. Releasing the center portion of a locked section +shall cause the remaining locked beginning and end portions to become two +separate locked sections. If the request would cause the number of +locks in the system to exceed a system-imposed limit, the request +shall fail. +.P +A potential for deadlock occurs if the threads of a process controlling +a locked section are blocked by accessing a locked section of +another process. If the system detects that deadlock would occur, +\fIlockf\fR() +shall fail with an +.BR [EDEADLK] +error. +.P +The interaction between +\fIfcntl\fR() +and +\fIlockf\fR() +locks is unspecified. +.P +Blocking on a section shall be interrupted by any signal. +.P +An F_ULOCK request in which +.IR size +is non-zero and the offset of the last byte of the requested section is +the maximum value for an object of type +.BR off_t , +when the process has an existing lock in which +.IR size +is 0 and which includes the last byte of the requested section, shall be +treated as a request to unlock from the start of the requested section +with a size equal to 0. Otherwise, an F_ULOCK request shall attempt to +unlock only the requested section. +.P +Attempting to lock a section of a file that is associated with a +buffered stream produces unspecified results. +.SH "RETURN VALUE" +Upon successful completion, +\fIlockf\fR() +shall return 0. Otherwise, it shall return \(mi1, set +.IR errno +to indicate an error, and existing locks shall not be changed. +.SH ERRORS +The +\fIlockf\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor; or +.IR function +is F_LOCK or F_TLOCK and +.IR fildes +is not a valid file descriptor open for writing. +.TP +.BR EACCES " or " EAGAIN +.br +The +.IR function +argument is F_TLOCK or F_TEST and the section is already locked by +another process. +.TP +.BR EDEADLK +The +.IR function +argument is F_LOCK and a deadlock is detected. +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR EINVAL +The +.IR function +argument is not one of F_LOCK, F_TLOCK, F_TEST, or F_ULOCK; or +.IR size +plus the current file offset is less than 0. +.TP +.BR EOVERFLOW +The offset of the first, or if +.IR size +is not 0 then the last, byte in the requested section cannot be +represented correctly in an object of type +.BR off_t . +.P +The +\fIlockf\fR() +function may fail if: +.TP +.BR EAGAIN +The +.IR function +argument is F_LOCK or F_TLOCK and the file is mapped with +\fImmap\fR(). +.TP +.BR EDEADLK " or " ENOLCK +.br +The +.IR function +argument is F_LOCK, F_TLOCK, or F_ULOCK, and the request would cause +the number of locks to exceed a system-imposed limit. +.TP +.BR EOPNOTSUPP " or " EINVAL +.br +The implementation does not support the locking of files of the type +indicated by the +.IR fildes +argument. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Locking a Portion of a File" +.P +In the following example, a file named +.BR /home/cnd/mod1 +is being modified. Other processes that use locking are prevented from +changing it during this process. Only the first 10\|000 bytes are +locked, and the lock call fails if another process has any part of this +area locked already. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int fildes; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = lockf(fildes, F_TLOCK, (off_t)10000); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Record-locking should not be used in combination with the +\fIfopen\fR(), +\fIfread\fR(), +\fIfwrite\fR(), +and other +.IR stdio +functions. Instead, the more primitive, non-buffered functions (such as +\fIopen\fR()) +should be used. Unexpected results may occur in processes that do +buffering in the user address space. The process may later read/write +data which is/was locked. The +.IR stdio +functions are the most common source of unexpected buffering. +.P +The +\fIalarm\fR() +function may be used to provide a timeout facility in applications +requiring it. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/log.3p b/man-pages-posix-2013-a/man3p/log.3p new file mode 100644 index 0000000..0d68316 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/log.3p @@ -0,0 +1,151 @@ +'\" et +.TH LOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +log, +logf, +logl +\(em natural logarithm function +.SH SYNOPSIS +.LP +.nf +#include +.P +double log(double \fIx\fP); +float logf(float \fIx\fP); +long double logl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the natural logarithm of their argument +.IR x , +log\d\s-3\fIe\fR\s+3\u(\fIx\fR). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the natural +logarithm of +.IR x . +.P +If +.IR x +is \(+-0, a pole error shall occur and +\fIlog\fR(), +\fIlogf\fR(), +and +\fIlogl\fR() +shall return \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \(miInf, +a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is 1, +0 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is negative, +or +.IR x +is \(miInf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog10\fR\^(\|)", +.IR "\fIlog1p\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/log10.3p b/man-pages-posix-2013-a/man3p/log10.3p new file mode 100644 index 0000000..502f3be --- /dev/null +++ b/man-pages-posix-2013-a/man3p/log10.3p @@ -0,0 +1,149 @@ +'\" et +.TH LOG10 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +log10, +log10f, +log10l +\(em base 10 logarithm function +.SH SYNOPSIS +.LP +.nf +#include +.P +double log10(double \fIx\fP); +float log10f(float \fIx\fP); +long double log10l(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the base 10 logarithm of their argument +.IR x , +log\d\s-310\s+3\u(\fIx\fR). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the base 10 +logarithm of +.IR x . +.P +If +.IR x +is \(+-0, a pole error shall occur and +\fIlog10\fR(), +\fIlog10f\fR(), +and +\fIlog10l\fR() +shall return \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \(miInf, +a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is 1, +0 shall be returned. +.P +If +.IR x +is +Inf, +Inf shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is negative, +or +.IR x +is \(miInf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.P +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog\fR\^(\|)", +.IR "\fIpow\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/log1p.3p b/man-pages-posix-2013-a/man3p/log1p.3p new file mode 100644 index 0000000..b8a2e13 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/log1p.3p @@ -0,0 +1,177 @@ +'\" et +.TH LOG1P "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +log1p, +log1pf, +log1pl +\(em compute a natural logarithm +.SH SYNOPSIS +.LP +.nf +#include +.P +double log1p(double \fIx\fP); +float log1pf(float \fIx\fP); +long double log1pl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute log\d\s-3e\s+3\u(1.0 + \fIx\fP). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the natural +logarithm of 1.0 + +.IR x . +.P +If +.IR x +is \(mi1, a pole error shall occur and +\fIlog1p\fR(), +\fIlog1pf\fR(), +and +\fIlog1pl\fR() +shall return \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than \(mi1, +or if +.IR x +is \(miInf, +a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, or +Inf, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIlog1p\fR(), +\fIlog1pf\fR(), +and +\fIlog1pl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is less than \(mi1, +or +.IR x +is \(miInf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is \(mi1. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.br +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/log2.3p b/man-pages-posix-2013-a/man3p/log2.3p new file mode 100644 index 0000000..2f20c80 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/log2.3p @@ -0,0 +1,148 @@ +'\" et +.TH LOG2 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +log2, +log2f, +log2l +\(em compute base 2 logarithm functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double log2(double \fIx\fP); +float log2f(float \fIx\fP); +long double log2l(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the base 2 logarithm of their argument +.IR x , +log\s-3\d2\u\s+3(\fIx\fR). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the base 2 +logarithm of +.IR x . +.P +If +.IR x +is \(+-0, a pole error shall occur and +\fIlog2\fR(), +\fIlog2f\fR(), +and +\fIlog2l\fR() +shall return \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \(miInf, +a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is 1, +0 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is less than zero, +or +.IR x +is \(miInf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/logb.3p b/man-pages-posix-2013-a/man3p/logb.3p new file mode 100644 index 0000000..1f26022 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/logb.3p @@ -0,0 +1,163 @@ +'\" et +.TH LOGB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +logb, +logbf, +logbl +\(em radix-independent exponent +.SH SYNOPSIS +.LP +.nf +#include +.P +double logb(double \fIx\fP); +float logbf(float \fIx\fP); +long double logbl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the exponent of +.IR x , +which is the integral part of log\fI\d\s-3r\s+3\u\fR +|\|\fIx\fR\||, as a signed floating-point value, for non-zero +.IR x , +where +.IR r +is the radix of the machine's floating-point arithmetic, which is the +value of FLT_RADIX defined in the +.IR +header. +.P +If +.IR x +is subnormal it is treated as though it were normalized; thus for +finite positive +.IR x : +.sp +.RS 4 +.nf +\fB +1 <= \fIx\fP * FLT_RADIX\s-3\u\(milogb(x)\d\s+3 < FLT_RADIX +.fi \fR +.P +.RE +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the exponent +of +.IR x . +.P +If +.IR x +is \(+-0, +\fIlogb\fR(), +\fIlogbf\fR(), +and +\fIlogbl\fR() +shall return \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +On systems that support the IEC 60559 Floating-Point option, a pole +error shall occur; +.br +otherwise, a +pole +error may occur. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-Inf, +Inf shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Pole\ Error" 12 +The value of +.IR x +is \(+-0. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.P +These functions may fail if: +.IP "Pole\ Error" 12 +The value of +.IR x +is 0. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIilogb\fR\^(\|)", +.IR "\fIscalbln\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/logf.3p b/man-pages-posix-2013-a/man3p/logf.3p new file mode 100644 index 0000000..700bfb4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/logf.3p @@ -0,0 +1,40 @@ +'\" et +.TH LOGF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +logf, +logl +\(em natural logarithm function +.SH SYNOPSIS +.LP +.nf +#include +.P +float logf(float \fIx\fP); +long double logl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIlog\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/longjmp.3p b/man-pages-posix-2013-a/man3p/longjmp.3p new file mode 100644 index 0000000..1b5b180 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/longjmp.3p @@ -0,0 +1,146 @@ +'\" et +.TH LONGJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +longjmp +\(em non-local goto +.SH SYNOPSIS +.LP +.nf +#include +.P +void longjmp(jmp_buf \fIenv\fP, int \fIval\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIlongjmp\fR() +function shall restore the environment saved by the most recent +invocation of +\fIsetjmp\fR() +in the same process, with the corresponding +.BR jmp_buf +argument. If the most recent invocation of +\fIsetjmp\fR() +with the corresponding +.BR jmp_buf +occurred in another thread, or if there is no such invocation, or if +the function containing the invocation of +\fIsetjmp\fR() +has terminated execution in the interim, or if the invocation of +\fIsetjmp\fR() +was within the scope of an identifier with variably modified type and +execution has left that scope in the interim, the behavior is undefined. +It is unspecified whether +\fIlongjmp\fR() +restores the signal mask, leaves the signal mask unchanged, or restores +it to its value at the time +\fIsetjmp\fR() +was called. +.P +All accessible objects have values, and all other components of the +abstract machine have state (for example, floating-point status flags +and open files), as of the time +\fIlongjmp\fR() +was called, except that the values of objects of automatic storage +duration are unspecified if they meet all the following conditions: +.IP " *" 4 +They are local to the function containing the corresponding +\fIsetjmp\fR() +invocation. +.IP " *" 4 +They do not have volatile-qualified type. +.IP " *" 4 +They are changed between the +\fIsetjmp\fR() +invocation and +\fIlongjmp\fR() +call. +.P +As it bypasses the usual function call and return mechanisms, +\fIlongjmp\fR() +shall execute correctly in contexts of interrupts, signals, and any +of their associated functions. However, if +\fIlongjmp\fR() +is invoked from a nested signal handler (that is, from a function +invoked as a result of a signal raised during the handling of another +signal), the behavior is undefined. +.P +The effect of a call to +\fIlongjmp\fR() +where initialization of the +.BR jmp_buf +structure was not performed in the calling thread is undefined. +.SH "RETURN VALUE" +After +\fIlongjmp\fR() +is completed, program execution continues as if the corresponding +invocation of +\fIsetjmp\fR() +had just returned the value specified by +.IR val . +The +\fIlongjmp\fR() +function shall not cause +\fIsetjmp\fR() +to return 0; if +.IR val +is 0, +\fIsetjmp\fR() +shall return 1. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications whose behavior depends on the value of the signal mask +should not use +\fIlongjmp\fR() +and +\fIsetjmp\fR(), +since their effect on the signal mask is unspecified, but should +instead use the +\fIsiglongjmp\fR() +and +\fIsigsetjmp\fR() +functions (which can save and restore the signal mask under application +control). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetjmp\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lrand48.3p b/man-pages-posix-2013-a/man3p/lrand48.3p new file mode 100644 index 0000000..10759b7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lrand48.3p @@ -0,0 +1,39 @@ +'\" et +.TH LRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lrand48 +\(em generate uniformly distributed pseudo-random non-negative +long integers +.SH SYNOPSIS +.LP +.nf +#include +.P +long lrand48(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lrint.3p b/man-pages-posix-2013-a/man3p/lrint.3p new file mode 100644 index 0000000..74b5aec --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lrint.3p @@ -0,0 +1,147 @@ +'\" et +.TH LRINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lrint, +lrintf, +lrintl +\(em round to nearest integer value using current rounding direction +.SH SYNOPSIS +.LP +.nf +#include +.P +long lrint(double \fIx\fP); +long lrintf(float \fIx\fP); +long lrintl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer +value, rounding according to the current rounding direction. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +.P +If +.IR x +is NaN, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is +Inf, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is \(miInf, a domain error shall occur and an unspecified value is +returned. +.P +If the correct value is positive and too large to represent as a +.BR long , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur; +otherwise, a +domain +error may occur. +.P +If the correct value is negative and too large to represent as a +.BR long , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur; +otherwise, a +domain +error may occur. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is NaN or \(+-Inf, or the correct value is not representable +as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions provide floating-to-integer conversions. They round +according to the current rounding direction. If the rounded value is +outside the range of the return type, the numeric result is unspecified +and the invalid floating-point exception is raised. When they raise no +other floating-point exception and the result differs from the +argument, they raise the inexact floating-point exception. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIllrint\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lround.3p b/man-pages-posix-2013-a/man3p/lround.3p new file mode 100644 index 0000000..ed2259a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lround.3p @@ -0,0 +1,149 @@ +'\" et +.TH LROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lround, +lroundf, +lroundl +\(em round to nearest integer value +.SH SYNOPSIS +.LP +.nf +#include +.P +long lround(double \fIx\fP); +long lroundf(float \fIx\fP); +long lroundl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer +value, rounding halfway cases away from zero, regardless of the current +rounding direction. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +.P +If +.IR x +is NaN, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is +Inf, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is \(miInf, a domain error shall occur and an unspecified value is +returned. +.P +If the correct value is positive and too large to represent as a +.BR long , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +shall occur; +otherwise, a +domain +error may occur. +.P +If the correct value is negative and too large to represent as a +.BR long , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +shall occur; +otherwise, a +domain +error may occur. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is NaN or \(+-Inf, or the correct value is not representable +as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions differ from the +\fIlrint\fR() +functions in the default rounding direction, with the +\fIlround\fR() +functions rounding halfway cases away from zero and needing not to +raise the inexact floating-point exception for non-integer arguments +that round to within the range of the return type. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIllround\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lsearch.3p b/man-pages-posix-2013-a/man3p/lsearch.3p new file mode 100644 index 0000000..a4d8838 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lsearch.3p @@ -0,0 +1,154 @@ +'\" et +.TH LSEARCH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lsearch, +lfind +\(em linear search and update +.SH SYNOPSIS +.LP +.nf +#include +.P +void *lsearch(const void *\fIkey\fP, void *\fIbase\fP, size_t *\fInelp\fP, size_t \fIwidth\fP, + int (*\fIcompar\fP)(const void *, const void *)); +void *lfind(const void *\fIkey\fP, const void *\fIbase\fP, size_t *\fInelp\fP, + size_t width, int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +The +\fIlsearch\fR() +function shall linearly search the table and return a pointer into the +table for the matching entry. If the entry does not occur, it shall be +added at the end of the table. The +.IR key +argument points to the entry to be sought in the table. The +.IR base +argument points to the first element in the table. The +.IR width +argument is the size of an element in bytes. The +.IR nelp +argument points to an integer containing the current number of elements +in the table. The integer to which +.IR nelp +points shall be incremented if the entry is added to the table. The +.IR compar +argument points to a comparison function which the application shall +supply (for example, +\fIstrcmp\fR()). +It is called with two arguments that point to the elements being +compared. The application shall ensure that the function returns 0 +if the elements are equal, and non-zero otherwise. +.P +The +\fIlfind\fR() +function shall be equivalent to +\fIlsearch\fR(), +except that if the entry is not found, it is not added to the table. +Instead, a null pointer is returned. +.SH "RETURN VALUE" +If the searched for entry is found, both +\fIlsearch\fR() +and +\fIlfind\fR() +shall return a pointer to it. Otherwise, +\fIlfind\fR() +shall return a null pointer and +\fIlsearch\fR() +shall return a pointer to the newly added element. +.P +Both functions shall return a null pointer in case of error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +.SS "Storing Strings in a Table" +.P +This fragment reads in less than or equal to TABSIZE +strings of length less than or equal to ELSIZE and stores them in a +table, eliminating duplicates. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +#define TABSIZE 50 +#define ELSIZE 120 +.P +\&... + char line[ELSIZE], tab[TABSIZE][ELSIZE]; + size_t nel = 0; + ... + while (fgets(line, ELSIZE, stdin) != NULL && nel < TABSIZE) + (void) lsearch(line, tab, &nel, + ELSIZE, (int (*)(const void *, const void *)) strcmp); + ... +.fi \fR +.P +.RE +.SS "Finding a Matching Entry" +.P +The following example finds any line that reads +.BR \(dqThis is a test.\(dq . +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +char line[ELSIZE], tab[TABSIZE][ELSIZE]; +size_t nel = 0; +char *findline; +void *entry; +.P +findline = "This is a test.\en"; +.P +entry = lfind(findline, tab, &nel, ELSIZE, ( + int (*)(const void *, const void *)) strcmp); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The comparison function need not compare every byte, so arbitrary +data may be contained in the elements in addition to the values +being compared. +.P +Undefined results can occur if there is not enough room in the table to +add a new item. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIhcreate\fR\^(\|)", +.IR "\fItdelete\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lseek.3p b/man-pages-posix-2013-a/man3p/lseek.3p new file mode 100644 index 0000000..38d3bd5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lseek.3p @@ -0,0 +1,183 @@ +'\" et +.TH LSEEK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lseek +\(em move the read/write file offset +.SH SYNOPSIS +.LP +.nf +#include +.P +off_t lseek(int \fIfildes\fP, off_t \fIoffset\fP, int \fIwhence\fP); +.fi +.SH DESCRIPTION +The +\fIlseek\fR() +function shall set the file offset for the open file description +associated with the file descriptor +.IR fildes, +as follows: +.IP " *" 4 +If +.IR whence +is SEEK_SET, the file offset shall be set to +.IR offset +bytes. +.IP " *" 4 +If +.IR whence +is SEEK_CUR, the file offset shall be set to its current location plus +.IR offset . +.IP " *" 4 +If +.IR whence +is SEEK_END, the file offset shall be set to the size of the file plus +.IR offset . +.P +The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END +are defined in +.IR . +.P +The behavior of +\fIlseek\fR() +on devices which are incapable of seeking is implementation-defined. +The value of the file offset associated with such a device is +undefined. +.P +The +\fIlseek\fR() +function shall allow the file offset to be set beyond the end of the +existing data in the file. If data is later written at this point, +subsequent reads of data in the gap shall return bytes with the value 0 +until data is actually written into the gap. +.P +The +\fIlseek\fR() +function shall not, by itself, extend the size of a file. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIlseek\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIlseek\fR() +function is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the resulting offset, as measured in bytes +from the beginning of the file, shall be returned. Otherwise, \(mi1 +shall be returned, +.IR errno +shall be set to indicate the error, and the file offset shall remain +unchanged. +.SH ERRORS +The +\fIlseek\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR EINVAL +The +.IR whence +argument is not a proper value, or the resulting file offset would be +negative for a regular file, block special file, or directory. +.TP +.BR EOVERFLOW +The resulting file offset would be a value which cannot be represented +correctly in an object of type +.BR off_t . +.TP +.BR ESPIPE +The +.IR fildes +argument is associated with a pipe, FIFO, or socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The ISO\ C standard includes the functions +\fIfgetpos\fR() +and +\fIfsetpos\fR(), +which work on very large files by use of a special positioning type. +.P +Although +\fIlseek\fR() +may position the file offset beyond the end of the file, this function +does not itself extend the size of the file. While the only function +in POSIX.1\(hy2008 that may directly extend the size of the file is +\fIwrite\fR(), +\fItruncate\fR(), +and +\fIftruncate\fR(), +several functions originally derived from the ISO\ C standard, such as +\fIfwrite\fR(), +\fIfprintf\fR(), +and so on, may do so (by causing calls on +\fIwrite\fR()). +.P +An invalid file offset that would cause +.BR [EINVAL] +to be returned may be both implementation-defined and +device-dependent (for example, memory may have few invalid values). A +negative file offset may be valid for some devices in some +implementations. +.P +The POSIX.1\(hy1990 standard did not specifically prohibit +\fIlseek\fR() +from returning a negative offset. Therefore, an application was +required to clear +.IR errno +prior to the call and check +.IR errno +upon return to determine whether a return value of (\c +.BR off_t )\(mi1 +is a negative offset or an indication of an error condition. The +standard developers did not wish to require this action on the part of +a conforming application, and chose to require that +.IR errno +be set to +.BR [EINVAL] +when the resulting file offset would be negative for a regular file, +block special file, or directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/lstat.3p b/man-pages-posix-2013-a/man3p/lstat.3p new file mode 100644 index 0000000..fdfee8c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/lstat.3p @@ -0,0 +1,38 @@ +'\" et +.TH LSTAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lstat +\(em get file status +.SH SYNOPSIS +.LP +.nf +#include +.P +int lstat(const char *restrict \fIpath\fP, struct stat *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfstatat\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/malloc.3p b/man-pages-posix-2013-a/man3p/malloc.3p new file mode 100644 index 0000000..f9c0f1f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/malloc.3p @@ -0,0 +1,99 @@ +'\" et +.TH MALLOC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +malloc +\(em a memory allocator +.SH SYNOPSIS +.LP +.nf +#include +.P +void *malloc(size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImalloc\fR() +function shall allocate unused space for an object whose size in +bytes is specified by +.IR size +and whose value is unspecified. +.P +The order and contiguity of storage allocated by successive calls to +\fImalloc\fR() +is unspecified. The pointer returned if the allocation succeeds shall +be suitably aligned so that it may be assigned to a pointer to any type +of object and then used to access such an object in the space allocated +(until the space is explicitly freed or reallocated). Each such +allocation shall yield a pointer to an object disjoint from any other +object. The pointer returned points to the start (lowest byte address) +of the allocated space. If the space cannot be allocated, a null +pointer shall be returned. If the size of the space requested is 0, the +behavior is implementation-defined: the value returned shall be either +a null pointer or a unique pointer. +.SH "RETURN VALUE" +Upon successful completion with +.IR size +not equal to 0, +\fImalloc\fR() +shall return a pointer to the allocated space. If +.IR size +is 0, either a null pointer or a unique pointer that can be +successfully passed to +\fIfree\fR() +shall be returned. Otherwise, it shall return a null pointer +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImalloc\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcalloc\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIposix_memalign\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mblen.3p b/man-pages-posix-2013-a/man3p/mblen.3p new file mode 100644 index 0000000..3361050 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mblen.3p @@ -0,0 +1,135 @@ +'\" et +.TH MBLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mblen +\(em get number of bytes in a character +.SH SYNOPSIS +.LP +.nf +#include +.P +int mblen(const char *\fIs\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If +.IR s +is not a null pointer, +\fImblen\fR() +shall determine the number of bytes constituting the character +pointed to by +.IR s . +Except that the shift state of +\fImbtowc\fR() +is not affected, it shall be equivalent to: +.sp +.RS 4 +.nf +\fB +mbtowc((wchar_t *)0, \fIs\fP, \fIn\fP); +.fi \fR +.P +.RE +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 +calls +\fImblen\fR(). +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. For a state-dependent encoding, this +function shall be placed into its initial state by a call for which its +character pointer argument, +.IR s , +is a null pointer. Subsequent calls with +.IR s +as other than a null pointer shall cause the internal state of the +function to be altered as necessary. A call with +.IR s +as a null pointer shall cause this function to return a non-zero value +if encodings have state dependency, and 0 otherwise. If the +implementation employs special bytes to change the shift state, these +bytes shall not produce separate wide-character codes, but shall be +grouped with an adjacent character. Changing the +.IR LC_CTYPE +category causes the shift state of this function to be unspecified. +.P +The +\fImblen\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If +.IR s +is a null pointer, +\fImblen\fR() +shall return a non-zero or 0 value, if character encodings, +respectively, do or do not have state-dependent encodings. If +.IR s +is not a null pointer, +\fImblen\fR() +shall either return 0 (if +.IR s +points to the null byte), or return the number of bytes that +constitute the character (if the next +.IR n +or fewer bytes form a valid character), or return \(mi1 (if they do +not form a valid character) +and may set +.IR errno +to indicate the error. +In no case shall the value returned be greater than +.IR n +or the value of the +{MB_CUR_MAX} +macro. +.SH ERRORS +The +\fImblen\fR() +function may fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbtowc\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mbrlen.3p b/man-pages-posix-2013-a/man3p/mbrlen.3p new file mode 100644 index 0000000..166e1f0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mbrlen.3p @@ -0,0 +1,158 @@ +'\" et +.TH MBRLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mbrlen +\(em get number of bytes in a character (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t mbrlen(const char *restrict \fIs\fP, size_t \fIn\fP, + mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If +.IR s +is not a null pointer, +\fImbrlen\fR() +shall determine the number of bytes constituting the character pointed +to by +.IR s . +It shall be equivalent to: +.sp +.RS 4 +.nf +\fB +mbstate_t internal; +mbrtowc(NULL, s, n, ps != NULL ? ps : &internal); +.fi \fR +.P +.RE +.P +If +.IR ps +is a null pointer, the +\fImbrlen\fR() +function shall use its own internal +.BR mbstate_t +object, which is initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. The implementation shall behave as +if no function defined in this volume of POSIX.1\(hy2008 calls +\fImbrlen\fR(). +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. +.P +The +\fImbrlen\fR() +function need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The +\fImbrlen\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +The +\fImbrlen\fR() +function shall return the first of the following that applies: +.IP 0 12 +If the next +.IR n +or fewer bytes complete the character that corresponds to the null +wide character. +.IP "\fIpositive\fP" 12 +If the next +.IR n +or fewer bytes complete a valid character; the value returned shall +be the number of bytes that complete the character. +.IP "(\fBsize_t\fP)\(mi2" 12 +If the next +.IR n +bytes contribute to an incomplete but potentially valid character, and +all +.IR n +bytes have been processed. When +.IR n +has at least the value of the +{MB_CUR_MAX} +macro, this case can only occur if +.IR s +points at a sequence of redundant shift sequences (for implementations +with state-dependent encodings). +.IP "(\fBsize_t\fP)\(mi1" 12 +If an encoding error occurs, in which case the next +.IR n +or fewer bytes do not contribute to a complete and valid character. In +this case, +.BR [EILSEQ] +shall be stored in +.IR errno +and the conversion state is undefined. +.SH ERRORS +The +\fImbrlen\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. +.P +The +\fImbrlen\fR() +function may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbsinit\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mbrtowc.3p b/man-pages-posix-2013-a/man3p/mbrtowc.3p new file mode 100644 index 0000000..4bc37de --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mbrtowc.3p @@ -0,0 +1,180 @@ +'\" et +.TH MBRTOWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mbrtowc +\(em convert a character to a wide-character code (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t mbrtowc(wchar_t *restrict \fIpwc\fP, const char *restrict \fIs\fP, + size_t \fIn\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If +.IR s +is a null pointer, the +\fImbrtowc\fR() +function shall be equivalent to the call: +.sp +.RS 4 +.nf +\fB +mbrtowc(NULL, "", 1, ps) +.fi \fR +.P +.RE +.P +In this case, the values of the arguments +.IR pwc +and +.IR n +are ignored. +.P +If +.IR s +is not a null pointer, the +\fImbrtowc\fR() +function shall inspect at most +.IR n +bytes beginning at the byte pointed to by +.IR s +to determine the number of bytes needed to complete the next character +(including any shift sequences). If the function determines that the +next character is completed, it shall determine the value of the +corresponding wide character and then, if +.IR pwc +is not a null pointer, shall store that value in the object pointed to by +.IR pwc . +If the corresponding wide character is the null wide character, the +resulting state described shall be the initial conversion state. +.P +If +.IR ps +is a null pointer, the +\fImbrtowc\fR() +function shall use its own internal +.BR mbstate_t +object, which shall be initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. The implementation shall behave as +if no function defined in this volume of POSIX.1\(hy2008 calls +\fImbrtowc\fR(). +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. +.P +The +\fImbrtowc\fR() +function need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The +\fImbrtowc\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +The +\fImbrtowc\fR() +function shall return the first of the following that applies: +.IP 0 12 +If the next +.IR n +or fewer bytes complete the character that corresponds to the null wide +character (which is the value stored). +.IP "between 1 and \fIn\fR inclusive" 12 +.br +If the next +.IR n +or fewer bytes complete a valid character (which is the value stored); +the value returned shall be the number of bytes that complete the +character. +.IP "(\fBsize_t\fP)\(mi2" 12 +If the next +.IR n +bytes contribute to an incomplete but potentially valid character, and +all +.IR n +bytes have been processed (no value is stored). When +.IR n +has at least the value of the +{MB_CUR_MAX} +macro, this case can only occur if +.IR s +points at a sequence of redundant shift sequences (for implementations +with state-dependent encodings). +.IP "(\fBsize_t\fP)\(mi1" 12 +If an encoding error occurs, in which case the next +.IR n +or fewer bytes do not contribute to a complete and valid character (no +value is stored). In this case, +.BR [EILSEQ] +shall be stored in +.IR errno +and the conversion state is undefined. +.SH ERRORS +The +\fImbrtowc\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. +.P +The +\fImbrtowc\fR() +function may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbsinit\fR\^(\|)", +.IR "\fImbsrtowcs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mbsinit.3p b/man-pages-posix-2013-a/man3p/mbsinit.3p new file mode 100644 index 0000000..fc02d2f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mbsinit.3p @@ -0,0 +1,101 @@ +'\" et +.TH MBSINIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mbsinit +\(em determine conversion object status +.SH SYNOPSIS +.LP +.nf +#include +.P +int mbsinit(const mbstate_t *\fIps\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If +.IR ps +is not a null pointer, the +\fImbsinit\fR() +function shall determine whether the object pointed to by +.IR ps +describes an initial conversion state. +.SH "RETURN VALUE" +The +\fImbsinit\fR() +function shall return non-zero if +.IR ps +is a null pointer, or if the pointed-to object describes an initial +conversion state; otherwise, it shall return zero. +.P +If an +.BR mbstate_t +object is altered by any of the functions described as ``restartable'', +and is then used with a different character sequence, or in the other +conversion direction, or with a different +.IR LC_CTYPE +category setting than on earlier function calls, the behavior is undefined. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +.BR mbstate_t +object is used to describe the current conversion state from a +particular character sequence to a wide-character sequence (or \fIvice +versa\fP) under the rules of a particular setting of the +.IR LC_CTYPE +category of the current locale. +.P +The initial conversion state corresponds, for a conversion in either +direction, to the beginning of a new character sequence in the initial +shift state. A zero valued +.BR mbstate_t +object is at least one way to describe an initial conversion state. A +zero valued +.BR mbstate_t +object can be used to initiate conversion involving any character +sequence, in any +.IR LC_CTYPE +category setting. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbrlen\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fImbsrtowcs\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)", +.IR "\fIwcsrtombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mbsrtowcs.3p b/man-pages-posix-2013-a/man3p/mbsrtowcs.3p new file mode 100644 index 0000000..c9afaca --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mbsrtowcs.3p @@ -0,0 +1,168 @@ +'\" et +.TH MBSRTOWCS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mbsnrtowcs, mbsrtowcs +\(em convert a character string to a wide-character string (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t mbsnrtowcs(wchar_t *restrict \fIdst\fP, const char **restrict \fIsrc\fP, + size_t \fInmc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +size_t mbsrtowcs(wchar_t *restrict \fIdst\fP, const char **restrict \fIsrc\fP, + size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +For +\fImbsrtowcs\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImbsrtowcs\fR() +function shall convert a sequence of characters, beginning in the +conversion state described by the object pointed to by +.IR ps , +from the array indirectly pointed to by +.IR src +into a sequence of corresponding wide characters. If +.IR dst +is not a null pointer, the converted characters shall be stored into +the array pointed to by +.IR dst . +Conversion continues up to and including a terminating null character, +which shall also be stored. Conversion shall stop early in either of +the following cases: +.IP " *" 4 +A sequence of bytes is encountered that does not form a valid character. +.IP " *" 4 +.IR len +codes have been stored into the array pointed to by +.IR dst +(and +.IR dst +is not a null pointer). +.P +Each conversion shall take place as if by a call to the +\fImbrtowc\fR() +function. +.P +If +.IR dst +is not a null pointer, the pointer object pointed to by +.IR src +shall be assigned either a null pointer (if conversion stopped due to +reaching a terminating null character) or the address just past the +last character converted (if any). If conversion stopped due to +reaching a terminating null character, and if +.IR dst +is not a null pointer, the resulting state described shall be the +initial conversion state. +.P +If +.IR ps +is a null pointer, the +\fImbsrtowcs\fR() +function shall use its own internal +.BR mbstate_t +object, which is initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. +.P +The +\fImbsnrtowcs\fR() +function shall be equivalent to the +\fImbsrtowcs\fR() +function, except that the conversion of characters pointed to by +.IR src +is limited to at most +.IR nmc +bytes (the size of the input buffer). +.P +The behavior of these functions shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 +calls these functions. +.P +The +\fImbsnrtowcs\fR() +and +\fImbsrtowcs\fR() +functions need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The +\fImbsrtowcs\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +If the input conversion encounters a sequence of bytes that do not form +a valid character, an encoding error occurs. In this case, these +functions shall store the value of the macro +.BR [EILSEQ] +in +.IR errno +and shall return (\fBsize_t\fP)\(mi1; the conversion state is undefined. +Otherwise, these functions shall return the number of characters +successfully converted, not including the terminating null (if any). +.SH ERRORS +These functions shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. +.P +These functions may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fImbsinit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mbstowcs.3p b/man-pages-posix-2013-a/man3p/mbstowcs.3p new file mode 100644 index 0000000..0c8c54d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mbstowcs.3p @@ -0,0 +1,119 @@ +'\" et +.TH MBSTOWCS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mbstowcs +\(em convert a character string to a wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t mbstowcs(wchar_t *restrict \fIpwcs\fP, const char *restrict \fIs\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImbstowcs\fR() +function shall convert a sequence of characters that begins in the +initial shift state from the array pointed to by +.IR s +into a sequence of corresponding wide-character codes and shall store +not more than +.IR n +wide-character codes into the array pointed to by +.IR pwcs . +No characters that follow a null byte (which is converted into a +wide-character code with value 0) shall be examined or converted. Each +character shall be converted as if by a call to +\fImbtowc\fR(), +except that the shift state of +\fImbtowc\fR() +is not affected. +.P +No more than +.IR n +elements shall be modified in the array pointed to by +.IR pwcs . +If copying takes place between objects that overlap, the behavior is +undefined. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +If +.IR pwcs +is a null pointer, +\fImbstowcs\fR() +shall return the length required to convert the entire array regardless +of the value of +.IR n , +but no values are stored. +.SH "RETURN VALUE" +If an invalid character is encountered, +\fImbstowcs\fR() +shall return (\fBsize_t\fP)\(mi1 +and shall set +.IR errno +to indicate the error. +.P +Otherwise, +\fImbstowcs\fR() +shall return the number of the array elements modified +(or required if +.IR pwcs +is null), +not including a terminating 0 code, if any. The array shall +not be zero-terminated if the value returned is +.IR n . +.SH ERRORS +The +\fImbstowcs\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid byte sequence is detected. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImblen\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mbtowc.3p b/man-pages-posix-2013-a/man3p/mbtowc.3p new file mode 100644 index 0000000..b1488cf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mbtowc.3p @@ -0,0 +1,139 @@ +'\" et +.TH MBTOWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mbtowc +\(em convert a character to a wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int mbtowc(wchar_t *restrict \fIpwc\fP, const char *restrict \fIs\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If +.IR s +is not a null pointer, +\fImbtowc\fR() +shall determine the number of bytes that constitute the character +pointed to by +.IR s . +It shall then determine the wide-character code for the value of type +.BR wchar_t +that corresponds to that character. (The value of the wide-character +code corresponding to the null byte is 0.) If the character is valid +and +.IR pwc +is not a null pointer, +\fImbtowc\fR() +shall store the wide-character code in the object pointed to by +.IR pwc . +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. For a state-dependent encoding, this +function is placed into its initial state by a call for which its +character pointer argument, +.IR s , +is a null pointer. Subsequent calls with +.IR s +as other than a null pointer shall cause the internal state of the +function to be altered as necessary. A call with +.IR s +as a null pointer shall cause this function to return a non-zero value +if encodings have state dependency, and 0 otherwise. If the +implementation employs special bytes to change the shift state, these +bytes shall not produce separate wide-character codes, but shall be +grouped with an adjacent character. Changing the +.IR LC_CTYPE +category causes the shift state of this function to be unspecified. At +most +.IR n +bytes of the array pointed to by +.IR s +shall be examined. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 calls +\fImbtowc\fR(). +.P +The +\fImbtowc\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If +.IR s +is a null pointer, +\fImbtowc\fR() +shall return a non-zero or 0 value, if character encodings, respectively, +do or do not have state-dependent encodings. If +.IR s +is not a null pointer, +\fImbtowc\fR() +shall either return 0 (if +.IR s +points to the null byte), or return the number of bytes that constitute +the converted character (if the next +.IR n +or fewer bytes form a valid character), or return \(mi1 +and shall set +.IR errno +to indicate the error +(if they do not form a valid character). +.P +In no case shall the value returned be greater than +.IR n +or the value of the +{MB_CUR_MAX} +macro. +.SH ERRORS +The +\fImbtowc\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImblen\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/memccpy.3p b/man-pages-posix-2013-a/man3p/memccpy.3p new file mode 100644 index 0000000..e286dc3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/memccpy.3p @@ -0,0 +1,81 @@ +'\" et +.TH MEMCCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +memccpy +\(em copy bytes in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memccpy(void *restrict \fIs1\fP, const void *restrict \fIs2\fP, + int \fIc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The +\fImemccpy\fR() +function shall copy bytes from memory area +.IR s2 +into +.IR s1 , +stopping after the first occurrence of byte +.IR c +(converted to an +.BR "unsigned char" ) +is copied, or after +.IR n +bytes are copied, whichever comes first. If copying takes place +between objects that overlap, the behavior is undefined. +.SH "RETURN VALUE" +The +\fImemccpy\fR() +function shall return a pointer to the byte after the copy of +.IR c +in +.IR s1 , +or a null pointer if +.IR c +was not found in the first +.IR n +bytes of +.IR s2 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fImemccpy\fR() +function does not check for the overflow of the receiving memory area. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/memchr.3p b/man-pages-posix-2013-a/man3p/memchr.3p new file mode 100644 index 0000000..5cf2c49 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/memchr.3p @@ -0,0 +1,81 @@ +'\" et +.TH MEMCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +memchr +\(em find byte in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memchr(const void *\fIs\fP, int \fIc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImemchr\fR() +function shall locate the first occurrence of +.IR c +(converted to an +.BR "unsigned char" ) +in the initial +.IR n +bytes (each interpreted as +.BR "unsigned char" ) +pointed to by +.IR s . +.P +Implementations shall behave as if they read the memory byte by byte +from the beginning of the bytes pointed to by +.IR s +and stop at the first occurrence of +.IR c +(if it is found in the initial +.IR n +bytes). +.SH "RETURN VALUE" +The +\fImemchr\fR() +function shall return a pointer to the located byte, or a null pointer +if the byte is not found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/memcmp.3p b/man-pages-posix-2013-a/man3p/memcmp.3p new file mode 100644 index 0000000..283b6a0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/memcmp.3p @@ -0,0 +1,82 @@ +'\" et +.TH MEMCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +memcmp +\(em compare bytes in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +int memcmp(const void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImemcmp\fR() +function shall compare the first +.IR n +bytes (each interpreted as +.BR "unsigned char" ) +of the object pointed to by +.IR s1 +to the first +.IR n +bytes of the object pointed to by +.IR s2 . +.P +The sign of a non-zero return value shall be determined by the sign of +the difference between the values of the first pair of bytes (both +interpreted as type +.BR "unsigned char" ) +that differ in the objects being compared. +.SH "RETURN VALUE" +The +\fImemcmp\fR() +function shall return an integer greater than, equal to, or less than +0, if the object pointed to by +.IR s1 +is greater than, equal to, or less than the object pointed to by +.IR s2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/memcpy.3p b/man-pages-posix-2013-a/man3p/memcpy.3p new file mode 100644 index 0000000..1cfb70f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/memcpy.3p @@ -0,0 +1,74 @@ +'\" et +.TH MEMCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +memcpy +\(em copy bytes in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memcpy(void *restrict \fIs1\fP, const void *restrict \fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImemcpy\fR() +function shall copy +.IR n +bytes from the object pointed to by +.IR s2 +into the object pointed to by +.IR s1 . +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fImemcpy\fR() +function shall return +.IR s1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fImemcpy\fR() +function does not check for the overflow of the receiving memory +area. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/memmove.3p b/man-pages-posix-2013-a/man3p/memmove.3p new file mode 100644 index 0000000..05275f7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/memmove.3p @@ -0,0 +1,83 @@ +'\" et +.TH MEMMOVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +memmove +\(em copy bytes in memory with overlapping areas +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memmove(void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImemmove\fR() +function shall copy +.IR n +bytes from the object pointed to by +.IR s2 +into the object pointed to by +.IR s1 . +Copying takes place as if the +.IR n +bytes from the object pointed to by +.IR s2 +are first copied into a temporary array of +.IR n +bytes that does not overlap the objects pointed to by +.IR s1 +and +.IR s2 , +and then the +.IR n +bytes from the temporary array are copied into the object pointed to by +.IR s1 . +.SH "RETURN VALUE" +The +\fImemmove\fR() +function shall return +.IR s1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/memset.3p b/man-pages-posix-2013-a/man3p/memset.3p new file mode 100644 index 0000000..d6fb0e8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/memset.3p @@ -0,0 +1,71 @@ +'\" et +.TH MEMSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +memset +\(em set bytes in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memset(void *\fIs\fP, int \fIc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImemset\fR() +function shall copy +.IR c +(converted to an +.BR "unsigned char" ) +into each of the first +.IR n +bytes of the object pointed to by +.IR s . +.SH "RETURN VALUE" +The +\fImemset\fR() +function shall return +.IR s ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mkdir.3p b/man-pages-posix-2013-a/man3p/mkdir.3p new file mode 100644 index 0000000..3eafad1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mkdir.3p @@ -0,0 +1,250 @@ +'\" et +.TH MKDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mkdir, mkdirat +\(em make a directory relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int mkdir(const char *\fIpath\fP, mode_t \fImode\fP); +int mkdirat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fImkdir\fR() +function shall create a new directory with name +.IR path . +The file permission bits of the new directory shall be initialized from +.IR mode . +These file permission bits of the +.IR mode +argument shall be modified by the process' file creation mask. +.P +When bits in +.IR mode +other than the file permission bits are set, the meaning of these +additional bits is implementation-defined. +.P +The directory's user ID shall be set to the process' effective user ID. +The directory's group ID shall be set to the group ID of the parent +directory or to the effective group ID of the process. Implementations +shall provide a way to initialize the directory's group ID to the group +ID of the parent directory. Implementations may, but need not, provide +an implementation-defined way to initialize the directory's group ID to +the effective group ID of the calling process. +.P +The newly created directory shall be an empty directory. +.P +If +.IR path +names a symbolic link, +\fImkdir\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +Upon successful completion, +\fImkdir\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the directory. Also, the last +data modification and last file status change timestamps of the directory +that contains the new entry shall be marked for update. +.P +The +\fImkdirat\fR() +function shall be equivalent to the +\fImkdir\fR() +function except in the case where +.IR path +specifies a relative path. In this case the newly created directory is +created relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +If +\fImkdirat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fImkdir\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, no directory shall be created. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or write +permission is denied on the parent directory of the directory to be +created. +.TP +.BR EEXIST +The named file exists. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMLINK +The link count of the parent directory would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix specified by +.IR path +does not name an existing directory or +.IR path +is an empty string. +.TP +.BR ENOSPC +The file system does not contain enough space to hold the contents of +the new directory or to extend the parent directory of the new +directory. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The parent directory resides on a read-only file system. +.P +In addition, the +\fImkdirat\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a Directory" +.P +The following example shows how to create a directory named +.BR /home/cnd/mod1 , +with read/write/search permissions for owner and group, and with +read/search permissions for others. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int status; +\&... +status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fImkdir\fR() +function originated in 4.2 BSD and was added to System V in Release 3.0. +.P +4.3 BSD detects +.BR [ENAMETOOLONG] . +.P +The POSIX.1\(hy1990 standard required that the group ID of a newly created directory be +set to the group ID of its parent directory or to the effective group +ID of the creating process. FIPS 151\(hy2 required that implementations provide +a way to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the directory is created, or determine under +what conditions the implementation will set the desired group ID. +.P +The purpose of the +\fImkdirat\fR() +function is to create a directory in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to the call to +\fImkdir\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fImkdirat\fR() +function it can be guaranteed that the newly created directory is +located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mkdtemp.3p b/man-pages-posix-2013-a/man3p/mkdtemp.3p new file mode 100644 index 0000000..0a6b2bd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mkdtemp.3p @@ -0,0 +1,215 @@ +'\" et +.TH MKDTEMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mkdtemp, mkstemp +\(em create a unique directory or file +.SH SYNOPSIS +.LP +.nf +#include +.P +char *mkdtemp(char *\fItemplate\fP); +int mkstemp(char *\fItemplate\fP); +.fi +.SH DESCRIPTION +The +\fImkdtemp\fR() +function uses the contents of +.IR template +to construct a unique directory name. The string provided in +.IR template +shall be a pathname ending with six trailing +.BR 'X' s. +The +\fImkdtemp\fR() +function shall replace each +.BR 'X' +with a character from the portable filename character set. The +characters are chosen such that the resulting name does not duplicate +the name of an existing file at the time of a call to +\fImkdtemp\fR(). +The unique directory name is used to attempt to create the directory +using mode 0700 as modified by the file creation mask. +.P +The +\fImkstemp\fR() +function shall replace the contents of the string pointed to by +.IR template +by a unique pathname, and return a file descriptor for the file open +for reading and writing. The +\fImkstemp\fR() +function shall create the file, and obtain a file descriptor for it, +as if by a call to: +.sp +.RS 4 +.nf +\fB +open(pathname, O_RDWR|O_CREAT|O_EXCL, S_IRUSR|S_IWUSR) +.fi \fR +.P +.RE +.P +The function thus prevents any possible race condition between testing +whether the file exists and opening it for use. The string in +.IR template +should look like a pathname with six trailing +.BR 'X' s; +\fImkstemp\fR() +replaces each +.BR 'X' +with a character from the portable filename character set. The +characters are chosen such that the resulting name does not duplicate +the name of an existing file at the time of a call to +\fImkstemp\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fImkdtemp\fR() +function shall return a pointer to the string containing the directory +name if it was created. Otherwise, it shall return a null pointer and +shall set +.IR errno +to indicate the error. +.P +Upon successful completion, the +\fImkstemp\fR() +function shall return an open file descriptor. Otherwise, it shall +return \(mi1 if no suitable file could be created. +.SH ERRORS +The +\fImkdtemp\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or write +permission is denied on the parent directory of the directory to be +created. +.TP +.BR EINVAL +The string pointed to by +.IR template +does not end in +.BR \(dqXXXXXX\(dq . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +path of the directory to be created. +.TP +.BR EMLINK +The link count of the parent directory would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix specified by the +.IR template +argument does not name an existing directory. +.TP +.BR ENOSPC +The file system does not contain enough space to hold the contents of +the new directory or to extend the parent directory of the new +directory. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The parent directory resides on a read-only file system. +.P +The +\fImkdtemp\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the path of the +directory to be created. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.P +The error conditions for the +\fImkstemp\fR() +function are defined in +.IR "\fIopen\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating a Pathname" +.P +The following example creates a file with a 10-character name beginning +with the characters +.BR \(dqfile\(dq +and opens the file for reading and writing. The value returned as the +value of +.IR fd +is a file descriptor that identifies the file. +.sp +.RS 4 +.nf +\fB +#include +\&... +char template[] = "/tmp/fileXXXXXX"; +int fd; +.P +fd = mkstemp(template); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +It is possible to run out of letters. +.P +The +\fImkdtemp\fR() +and +\fImkstemp\fR() +functions need not check to determine whether the filename part of +.IR template +exceeds the maximum allowable filename length. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpid\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fItmpnam\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mkfifo.3p b/man-pages-posix-2013-a/man3p/mkfifo.3p new file mode 100644 index 0000000..2f7917b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mkfifo.3p @@ -0,0 +1,273 @@ +'\" et +.TH MKFIFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mkfifo, mkfifoat +\(em make a FIFO special file relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int mkfifo(const char *\fIpath\fP, mode_t \fImode\fP); +int mkfifoat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fImkfifo\fR() +function shall create a new FIFO special file named by the pathname +pointed to by +.IR path . +The file permission bits of the new FIFO shall be initialized from +.IR mode . +The file permission bits of the +.IR mode +argument shall be modified by the process' file creation mask. +.P +When bits in +.IR mode +other than the file permission bits are set, the effect is +implementation-defined. +.P +If +.IR path +names a symbolic link, +\fImkfifo\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +The FIFO's user ID shall be set to the process' effective user ID. The +FIFO's group ID shall be set to the group ID of the parent directory or +to the effective group ID of the process. Implementations shall provide +a way to initialize the FIFO's group ID to the group ID of the parent +directory. Implementations may, but need not, provide an +implementation-defined way to initialize the FIFO's group ID to the +effective group ID of the calling process. +.P +Upon successful completion, +\fImkfifo\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the file. Also, the last +data modification and last file status change timestamps of the directory +that contains the new entry shall be marked for update. +.P +The +\fImkfifoat\fR() +function shall be equivalent to the +\fImkfifo\fR() +function except in the case where +.IR path +specifies a relative path. In this case the newly created FIFO is +created relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +If +\fImkfifoat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fImkfifo\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, no FIFO shall be created. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +A component of the path prefix denies search permission, or write +permission is denied on the parent directory of the FIFO to be +created. +.TP +.BR EEXIST +The named file already exists. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR path +names an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory that would contain the new file cannot be extended or the +file system is out of file-allocation resources. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The named file resides on a read-only file system. +.P +The +\fImkfifoat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a FIFO File" +.P +The following example shows how to create a FIFO file named +.BR /home/cnd/mod_done , +with read/write permissions for owner, and with read permissions for +group and others. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int status; +\&... +status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR | + S_IRGRP | S_IROTH); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The syntax of this function is intended to maintain compatibility with +historical implementations of +\fImknod\fR(). +The latter function was included in the 1984 /usr/group standard but only for use in +creating FIFO special files. The +\fImknod\fR() +function was originally excluded from the POSIX.1\(hy1988 standard as +implementation-defined and replaced by +\fImkdir\fR() +and +\fImkfifo\fR(). +The +\fImknod\fR() +function is now included for alignment with the Single UNIX Specification. +.P +The POSIX.1\(hy1990 standard required that the group ID of a newly created FIFO be +set to the group ID of its parent directory or to the effective group +ID of the creating process. FIPS 151\(hy2 required that implementations provide +a way to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the FIFO is created, or determine under +what conditions the implementation will set the desired group ID. +.P +The purpose of the +\fImkfifoat\fR() +function is to create a FIFO special file in directories other than +the current working directory without exposure to race conditions. Any +part of the path of a file could be changed in parallel to a call to +\fImkfifo\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fImkfifoat\fR() +function it can be guaranteed that the newly created FIFO is located +relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mknod.3p b/man-pages-posix-2013-a/man3p/mknod.3p new file mode 100644 index 0000000..e05d447 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mknod.3p @@ -0,0 +1,336 @@ +'\" et +.TH MKNOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mknod, mknodat +\(em make directory, special file, or regular file +.SH SYNOPSIS +.LP +.nf +#include +.P +int mknod(const char *\fIpath\fP, mode_t \fImode\fP, dev_t \fIdev\fP); +int mknodat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP, dev_t \fIdev\fP); +.fi +.SH DESCRIPTION +The +\fImknod\fR() +function shall create a new file named by the pathname to which the +argument +.IR path +points. +.P +The file type for +.IR path +is OR'ed into the +.IR mode +argument, and the application shall select one of the following +symbolic constants: +.TS +tab(!) box center; +cB | cB +lw(1i) | lw(3i). +Name!Description +_ +S_IFIFO!FIFO-special +S_IFCHR!Character-special (non-portable) +S_IFDIR!Directory (non-portable) +S_IFBLK!Block-special (non-portable) +S_IFREG!Regular (non-portable) +.TE +.P +The only portable use of +\fImknod\fR() +is to create a FIFO-special file. If +.IR mode +is not S_IFIFO or +.IR dev +is not 0, the behavior of +\fImknod\fR() +is unspecified. +.P +The permissions for the new file are OR'ed into the +.IR mode +argument, and may be selected from any combination of the following +symbolic constants: +.TS +tab(!) box center; +cB | cB +lw(1i) | lw(3i). +Name!Description +_ +S_ISUID!Set user ID on execution. +S_ISGID!Set group ID on execution. +S_IRWXU!Read, write, or execute (search) by owner. +S_IRUSR!Read by owner. +S_IWUSR!Write by owner. +S_IXUSR!Execute (search) by owner. +S_IRWXG!Read, write, or execute (search) by group. +S_IRGRP!Read by group. +S_IWGRP!Write by group. +S_IXGRP!Execute (search) by group. +S_IRWXO!Read, write, or execute (search) by others. +S_IROTH!Read by others. +S_IWOTH!Write by others. +S_IXOTH!Execute (search) by others. +S_ISVTX!On directories, restricted deletion flag. +.TE +.P +The user ID of the file shall be initialized to the effective user ID +of the process. The group ID of the file shall be initialized to either +the effective group ID of the process or the group ID of the parent +directory. Implementations shall provide a way to initialize the file's +group ID to the group ID of the parent directory. Implementations may, +but need not, provide an implementation-defined way to initialize the +file's group ID to the effective group ID of the calling process. The +owner, group, and other permission bits of +.IR mode +shall be modified by the file mode creation mask of the process. The +\fImknod\fR() +function shall clear each bit whose corresponding bit in the file mode +creation mask of the process is set. +.P +If +.IR path +names a symbolic link, +\fImknod\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +Upon successful completion, +\fImknod\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the file. Also, the last +data modification and last file status change timestamps of the directory +that contains the new entry shall be marked for update. +.P +Only a process with appropriate privileges may invoke +\fImknod\fR() +for file types other than FIFO-special. +.P +The +\fImknodat\fR() +function shall be equivalent to the +\fImknod\fR() +function except in the case where +.IR path +specifies a relative path. In this case the newly created +directory, special file, or regular file is located relative to the +directory associated with the file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +If +\fImknodat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fImknod\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, the new file shall +not be created. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +A component of the path prefix denies search permission, or write +permission is denied on the parent directory. +.TP +.BR EEXIST +The named file exists. +.TP +.BR EINVAL +An invalid argument exists. +.TP +.BR EIO +An I/O error occurred while accessing the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR path +names an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory that would contain the new file cannot be extended or the +file system is out of file allocation resources. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The invoking process does not have appropriate privileges and the +file type is not FIFO-special. +.TP +.BR EROFS +The directory in which the file is to be created is located on a +read-only file system. +.br +.P +The +\fImknodat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a FIFO Special File" +.P +The following example shows how to create a FIFO special file named +.BR /home/cnd/mod_done , +with read/write permissions for owner, and with read permissions for +group and others. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +dev_t dev; +int status; +\&... +status = mknod("/home/cnd/mod_done", S_IFIFO | S_IWUSR | + S_IRUSR | S_IRGRP | S_IROTH, dev); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fImkfifo\fR() +function is preferred over this function for making FIFO special files. +.SH RATIONALE +The POSIX.1\(hy1990 standard required that the group ID of a newly created file be +set to the group ID of its parent directory or to the effective group +ID of the creating process. FIPS 151\(hy2 required that implementations provide +a way to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the file is created, or determine under +what conditions the implementation will set the desired group ID. +.P +The purpose of the +\fImknodat\fR() +function is to create directories, special files, or regular files in +directories other than the current working directory without exposure +to race conditions. Any part of the path of a file could be changed in +parallel to a call to +\fImknod\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fImknodat\fR() +function it can be guaranteed that the newly created directory, special +file, or regular file is located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mkstemp.3p b/man-pages-posix-2013-a/man3p/mkstemp.3p new file mode 100644 index 0000000..64d0fa6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mkstemp.3p @@ -0,0 +1,38 @@ +'\" et +.TH MKSTEMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mkstemp +\(em create a unique directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int mkstemp(char *\fItemplate\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImkdtemp\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mktime.3p b/man-pages-posix-2013-a/man3p/mktime.3p new file mode 100644 index 0000000..f8f673a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mktime.3p @@ -0,0 +1,175 @@ +'\" et +.TH MKTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mktime +\(em convert broken-down time into time since the Epoch +.SH SYNOPSIS +.LP +.nf +#include +.P +time_t mktime(struct tm *\fItimeptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fImktime\fR() +function shall convert the broken-down time, expressed as local time, +in the structure pointed to by +.IR timeptr , +into a time since the Epoch value with the same encoding as that of the +values returned by +\fItime\fR(). +The original values of the +.IR tm_wday +and +.IR tm_yday +components of the structure are ignored, and the original values +of the other components are not restricted to the ranges +described in +.IR . +.P +A positive or 0 value for +.IR tm_isdst +shall cause +\fImktime\fR() +to presume initially that Daylight Savings Time, respectively, is or is +not in effect for the specified time. A negative value for +.IR tm_isdst +shall cause +\fImktime\fR() +to attempt to determine whether Daylight Savings Time is in effect for +the specified time. +.P +Local timezone information shall be set as though +\fImktime\fR() +called +\fItzset\fR(). +.P +The relationship between the +.BR tm +structure (defined in the +.IR +header) and the time in seconds since the Epoch is that the result +shall be as specified in the expression given in the definition of +seconds since the Epoch (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch") +corrected for timezone and any seasonal time adjustments, where the +names in the structure and in the expression correspond. +.P +Upon successful completion, the values of the +.IR tm_wday +and +.IR tm_yday +components of the structure shall be set appropriately, and the other +components are set to represent the specified time since the Epoch, but +with their values forced to the ranges indicated in the +.IR +entry; the final value of +.IR tm_mday +shall not be set until +.IR tm_mon +and +.IR tm_year +are determined. +.SH "RETURN VALUE" +The +\fImktime\fR() +function shall return the specified time since the Epoch encoded as +a value of type +.BR time_t . +If the time since the Epoch cannot be represented, the function shall +return the value (\fBtime_t\fP)\(mi1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImktime\fR() +function shall fail if: +.TP +.BR EOVERFLOW +The result cannot be represented. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +What day of the week is July 4, 2001? +.sp +.RS 4 +.nf +\fB +#include +#include +.P +struct tm time_str; +.P +char daybuf[20]; +.P +int main(void) +{ + time_str.tm_year = 2001 \(em 1900; + time_str.tm_mon = 7 \(em 1; + time_str.tm_mday = 4; + time_str.tm_hour = 0; + time_str.tm_min = 0; + time_str.tm_sec = 1; + time_str.tm_isdst = \(mi1; + if (mktime(&time_str) == -1) + (void)puts("-unknown-"); + else { + (void)strftime(daybuf, sizeof(daybuf), "%A", &time_str); + (void)puts(daybuf); + } + return 0; +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mlock.3p b/man-pages-posix-2013-a/man3p/mlock.3p new file mode 100644 index 0000000..2eb4888 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mlock.3p @@ -0,0 +1,168 @@ +'\" et +.TH MLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mlock, +munlock +\(em lock or unlock a range of process address space +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mlock(const void *\fIaddr\fP, size_t \fIlen\fP); +int munlock(const void *\fIaddr\fP, size_t \fIlen\fP); +.fi +.SH DESCRIPTION +The +\fImlock\fR() +function shall cause those whole pages containing any part of the +address space of the process starting at address +.IR addr +and continuing for +.IR len +bytes to be memory-resident until unlocked or until the process exits +or +.IR exec s +another process image. The implementation may require that +.IR addr +be a multiple of +{PAGESIZE}. +.P +The +\fImunlock\fR() +function shall unlock those whole pages containing any part of the +address space of the process starting at address +.IR addr +and continuing for +.IR len +bytes, regardless of how many times +\fImlock\fR() +has been called by the process for any of the pages in the specified +range. The implementation may require that +.IR addr +be a multiple of +{PAGESIZE}. +.P +If any of the pages in the range specified to a call to +\fImunlock\fR() +are also mapped into the address spaces of other processes, any locks +established on those pages by another process are unaffected by the +call of this process to +\fImunlock\fR(). +If any of the pages in the range specified by a call to +\fImunlock\fR() +are also mapped into other portions of the address space of the calling +process outside the range specified, any locks established on those +pages via the other mappings are also unaffected by this call. +.P +Upon successful return from +\fImlock\fR(), +pages in the specified range shall be locked and memory-resident. Upon +successful return from +\fImunlock\fR(), +pages in the specified range shall be unlocked with respect to the +address space of the process. Memory residency of unlocked pages is +unspecified. +.P +Appropriate privileges are required to lock process memory with +\fImlock\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fImlock\fR() +and +\fImunlock\fR() +functions shall return a value of zero. Otherwise, no change is made to +any locks in the address space of the process, and the function shall +return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImlock\fR() +and +\fImunlock\fR() +functions shall fail if: +.TP +.BR ENOMEM +Some or all of the address range specified by the +.IR addr +and +.IR len +arguments does not correspond to valid mapped pages in the address +space of the process. +.P +The +\fImlock\fR() +function shall fail if: +.TP +.BR EAGAIN +Some or all of the memory identified by the operation could not be +locked when the call was made. +.P +The +\fImlock\fR() +and +\fImunlock\fR() +functions may fail if: +.TP +.BR EINVAL +The +.IR addr +argument is not a multiple of +{PAGESIZE}. +.P +The +\fImlock\fR() +function may fail if: +.TP +.BR ENOMEM +Locking the pages mapped by the specified range would exceed an +implementation-defined limit on the amount of memory that the process +may lock. +.TP +.BR EPERM +The calling process does not have appropriate privileges to perform +the requested operation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fImlockall\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mlockall.3p b/man-pages-posix-2013-a/man3p/mlockall.3p new file mode 100644 index 0000000..df4158a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mlockall.3p @@ -0,0 +1,158 @@ +'\" et +.TH MLOCKALL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mlockall, +munlockall +\(em lock/unlock the address space of a process +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mlockall(int \fIflags\fP); +int munlockall(void); +.fi +.SH DESCRIPTION +The +\fImlockall\fR() +function shall cause all of the pages mapped by the address space of a +process to be memory-resident until unlocked or until the process exits +or +.IR exec s +another process image. The +.IR flags +argument determines whether the pages to be locked are those currently +mapped by the address space of the process, those that are mapped +in the future, or both. The +.IR flags +argument is constructed from the bitwise-inclusive OR of one or more +of the following symbolic constants, defined in +.IR : +.IP MCL_CURRENT 12 +Lock all of the pages currently mapped into the address space of the +process. +.IP MCL_FUTURE 12 +Lock all of the pages that become mapped into the address space of the +process in the future, when those mappings are established. +.P +If MCL_FUTURE is specified, and the automatic locking of future +mappings eventually causes the amount of locked memory to exceed the +amount of available physical memory or any other +implementation-defined limit, the behavior is +implementation-defined. The manner in which the implementation +informs the application of these situations is also +implementation-defined. +.P +The +\fImunlockall\fR() +function shall unlock all currently mapped pages of the address space +of the process. Any pages that become mapped into the address space of +the process after a call to +\fImunlockall\fR() +shall not be locked, unless there is an intervening call to +\fImlockall\fR() +specifying MCL_FUTURE or a subsequent call to +\fImlockall\fR() +specifying MCL_CURRENT. If pages mapped into the address space of the +process are also mapped into the address spaces of other processes and +are locked by those processes, the locks established by the other +processes shall be unaffected by a call by this process to +\fImunlockall\fR(). +.P +Upon successful return from the +\fImlockall\fR() +function that specifies MCL_CURRENT, all currently mapped pages of the +address space of the process shall be memory-resident and locked. +Upon return from the +\fImunlockall\fR() +function, all currently mapped pages of the address space of the process +shall be unlocked with respect to the address space of the process. +The memory residency of unlocked pages is unspecified. +.P +Appropriate privileges are required to lock process memory with +\fImlockall\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fImlockall\fR() +function shall return a value of zero. Otherwise, no additional memory +shall be locked, and the function shall return a value of \(mi1 and set +.IR errno +to indicate the error. The effect of failure of +\fImlockall\fR() +on previously existing locks in the address space is unspecified. +.P +If it is supported by the implementation, the +\fImunlockall\fR() +function shall always return a value of zero. Otherwise, the function +shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImlockall\fR() +function shall fail if: +.TP +.BR EAGAIN +Some or all of the memory identified by the operation could not be +locked when the call was made. +.TP +.BR EINVAL +The +.IR flags +argument is zero, or includes unimplemented flags. +.P +The +\fImlockall\fR() +function may fail if: +.TP +.BR ENOMEM +Locking all of the pages currently mapped into the address space of the +process would exceed an implementation-defined limit on the amount of +memory that the process may lock. +.TP +.BR EPERM +The calling process does not have appropriate privileges to perform +the requested operation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fImlock\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mmap.3p b/man-pages-posix-2013-a/man3p/mmap.3p new file mode 100644 index 0000000..a065f5c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mmap.3p @@ -0,0 +1,729 @@ +'\" et +.TH MMAP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mmap +\(em map pages of memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *mmap(void *\fIaddr\fP, size_t \fIlen\fP, int \fIprot\fP, int \fIflags\fP, + int \fIfildes\fP, off_t \fIoff\fP); +.fi +.SH DESCRIPTION +The +\fImmap\fR() +function shall establish a mapping between an address space +of a process and a memory object. +.P +The +\fImmap\fR() +function shall be supported for the following memory objects: +.IP " *" 4 +Regular files +.IP " *" 4 +Shared memory objects +.IP " *" 4 +Typed memory objects +.P +Support for any other type of file is unspecified. +.P +The format of the call is as follows: +.sp +.RS 4 +.nf +\fB +\fIpa\fR=\fImmap\fR(\fIaddr\fP, \fIlen\fP, \fIprot\fP, \fIflags\fP, \fIfildes\fP, \fIoff\fP); +.fi \fR +.P +.RE +.P +The +\fImmap\fR() +function shall establish a mapping between the address space of the +process at an address +.IR pa +for +.IR len +bytes to the memory object represented by the file descriptor +.IR fildes +at offset +.IR off +for +.IR len +bytes. The value of +.IR pa +is an implementation-defined function of the parameter +.IR addr +and the values of +.IR flags , +further described below. A successful +\fImmap\fR() +call shall return +.IR pa +as its result. The address range starting at +.IR pa +and continuing for +.IR len +bytes shall be legitimate for the possible (not necessarily current) +address space of the process. The range of bytes starting at +.IR off +and continuing for +.IR len +bytes shall be legitimate for the possible (not necessarily current) +offsets in the memory object represented by +.IR fildes . +.P +If +.IR fildes +represents a typed memory object opened with either the +POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG +flag, the memory object to be mapped +shall be that portion of the typed memory object allocated by the +implementation as specified below. In this case, if +.IR off +is non-zero, the behavior of +\fImmap\fR() +is undefined. If +.IR fildes +refers to a valid typed memory object that is not accessible from the +calling process, +\fImmap\fR() +shall fail. +.P +The mapping established by +\fImmap\fR() +shall replace any previous mappings for those whole pages containing +any part of the address space of the process starting at +.IR pa +and continuing for +.IR len +bytes. +.P +If the size of the mapped file changes after the call to +\fImmap\fR() +as a result of some other operation on the mapped file, the effect of +references to portions of the mapped region that correspond to added or +removed portions of the file is unspecified. +.P +If +.IR len +is zero, +\fImmap\fR() +shall fail and no mapping shall be established. +.P +The parameter +.IR prot +determines whether read, write, execute, or some combination of +accesses are permitted to the data being mapped. The +.IR prot +shall be either PROT_NONE +or the bitwise-inclusive OR of one or more of the other flags in +the following table, defined in the +.IR +header. +.TS +center box tab(!); +cB | cB +lw(1.5i) | lw(2i). +Symbolic Constant!Description +_ +PROT_READ!Data can be read. +PROT_WRITE!Data can be written. +PROT_EXEC!Data can be executed. +PROT_NONE!Data cannot be accessed. +.TE +.P +If an implementation cannot support the combination of access types +specified by +.IR prot , +the call to +\fImmap\fR() +shall fail. +.P +An implementation may permit accesses other than those specified by +.IR prot ; +however, the implementation shall not permit a write to succeed +where PROT_WRITE has not been set and shall not permit any access where +PROT_NONE alone has been set. The implementation shall support at least +the following values of +.IR prot : +PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of +PROT_READ and PROT_WRITE. The file descriptor +.IR fildes +shall have been opened with read permission, regardless of the +protection options specified. If PROT_WRITE is specified, the +application shall ensure that it has opened the file descriptor +.IR fildes +with write permission unless MAP_PRIVATE is specified in the +.IR flags +parameter as described below. +.P +The parameter +.IR flags +provides other information about the handling of the mapped data. +The value of +.IR flags +is the bitwise-inclusive OR of these options, defined in +.IR : +.TS +center box tab(!); +cB | cB +lw(1.5i) | lw(2i). +Symbolic Constant!Description +_ +MAP_SHARED!Changes are shared. +MAP_PRIVATE!Changes are private. +MAP_FIXED!Interpret \fIaddr\fP exactly. +.TE +.P +It is implementation-defined whether MAP_FIXED shall be supported. +MAP_FIXED shall be supported on XSI-conformant systems. +.P +MAP_SHARED and MAP_PRIVATE describe the disposition of write references +to the memory object. If MAP_SHARED is specified, write references +shall change the underlying object. If MAP_PRIVATE is specified, +modifications to the mapped data by the calling process shall be visible +only to the calling process and shall not change the underlying object. +It is unspecified whether modifications to the underlying object done +after the MAP_PRIVATE mapping is established are visible through the +MAP_PRIVATE mapping. Either MAP_SHARED or MAP_PRIVATE can be +specified, but not both. The mapping type is retained across +\fIfork\fR(). +.P +The state of synchronization objects such as mutexes, semaphores, +barriers, and conditional variables placed in shared memory mapped with +MAP_SHARED becomes undefined when the last region in any process +containing the synchronization object is unmapped. +.P +When +.IR fildes +represents a typed memory object opened with either the +POSIX_TYPED_MEM_ALLOCATE flag or the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, +\fImmap\fR() +shall, if there are enough resources available, map +.IR len +bytes allocated from the corresponding typed memory object which were +not previously allocated to any process in any processor that may +access that typed memory object. If there are not enough resources +available, the function shall fail. If +.IR fildes +represents a typed memory object opened with the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these allocated bytes shall be +contiguous within the typed memory object. If +.IR fildes +represents a typed memory object opened with the +POSIX_TYPED_MEM_ALLOCATE flag, these allocated bytes may be composed of +non-contiguous fragments within the typed memory object. If +.IR fildes +represents a typed memory object opened with neither the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the POSIX_TYPED_MEM_ALLOCATE +flag, +.IR len +bytes starting at offset +.IR off +within the typed memory object are mapped, exactly as when mapping a +file or shared memory object. In this case, if two processes map an +area of typed memory using the same +.IR off +and +.IR len +values and using file descriptors that refer to the same memory pool +(either from the same port or from a different port), both processes +shall map the same region of storage. +.P +When MAP_FIXED is set in the +.IR flags +argument, the implementation is informed that the value of +.IR pa +shall be +.IR addr , +exactly. If MAP_FIXED is set, +\fImmap\fR() +may return MAP_FAILED and set +.IR errno +to +.BR [EINVAL] . +If a MAP_FIXED request is successful, the mapping established by +\fImmap\fR() +replaces any previous mappings for the pages in the range +[\fIpa\fP,\fIpa\fP+\fIlen\fR) of the process. +.P +When MAP_FIXED is not set, the implementation uses +.IR addr +in an implementation-defined manner to arrive at +.IR pa . +The +.IR pa +so chosen shall be an area of the address space that the implementation +deems suitable for a mapping of +.IR len +bytes to the file. All implementations interpret an +.IR addr +value of 0 as granting the implementation complete freedom in selecting +.IR pa , +subject to constraints described below. A non-zero value of +.IR addr +is taken to be a suggestion of a process address near which the mapping +should be placed. When the implementation selects a value for +.IR pa , +it never places a mapping at address 0, nor does it replace any extant +mapping. +.P +If MAP_FIXED is specified and +.IR addr +is non-zero, it shall have the same remainder as the +.IR off +parameter, modulo the page size as returned by +\fIsysconf\fR() +when passed _SC_PAGESIZE or _SC_PAGE_SIZE. The implementation may +require that off is a multiple of the page size. If MAP_FIXED is +specified, the implementation may require that +.IR addr +is a multiple of the page size. The system performs mapping operations +over whole pages. Thus, while the parameter +.IR len +need not meet a size or alignment constraint, the system shall include, +in any mapping operation, any partial page specified by the address +range starting at +.IR pa +and continuing for +.IR len +bytes. +.P +The system shall always zero-fill any partial page at the end of an +object. Further, the system shall never write out any modified +portions of the last page of an object which are beyond its end. +References within the address range starting at +.IR pa +and continuing for +.IR len +bytes to whole pages following the end of an object shall result in +delivery of a SIGBUS signal. +.P +An implementation may generate SIGBUS signals when a reference would +cause an error in the mapped object, such as out-of-space condition. +.P +The +\fImmap\fR() +function shall add an extra reference to the file associated with the +file descriptor +.IR fildes +which is not removed by a subsequent +\fIclose\fR() +on that file descriptor. This reference shall be removed when there are +no more mappings to the file. +.P +The last data access timestamp of the mapped file may be marked for +update at any time between the +\fImmap\fR() +call and the corresponding +\fImunmap\fR() +call. The initial read or write reference to a mapped region shall cause +the file's last data access timestamp to be marked for update if it has +not already been marked for update. +.P +The last data modification and last file status change timestamps +of a file that is mapped with MAP_SHARED and PROT_WRITE shall be +marked +for update at some point in the interval between a write reference to +the mapped region and the next call to +\fImsync\fR() +with MS_ASYNC or MS_SYNC for that portion of the file by any process. +If there is no such call and if the underlying file is modified +as a result of a write reference, then these timestamps shall be marked +for update at some time after the write reference. +.P +There may be implementation-defined limits on the number of memory +regions that can be mapped (per process or per system). +.P +If such a limit is imposed, whether the number of memory regions that +can be mapped by a process is decreased by the use of +\fIshmat\fR() +is implementation-defined. +.P +If +\fImmap\fR() +fails for reasons other than +.BR [EBADF] , +.BR [EINVAL] , +or +.BR [ENOTSUP] , +some of the mappings in the address range starting at +.IR addr +and continuing for +.IR len +bytes may have been unmapped. +.SH "RETURN VALUE" +Upon successful completion, the +\fImmap\fR() +function shall return the address at which the mapping was placed (\c +.IR pa ); +otherwise, it shall return a value of MAP_FAILED and set +.IR errno +to indicate the error. The symbol MAP_FAILED is defined in the +.IR +header. No successful return from +\fImmap\fR() +shall return the value MAP_FAILED. +.SH ERRORS +The +\fImmap\fR() +function shall fail if: +.TP +.BR EACCES +The +.IR fildes +argument is not open for read, regardless of the protection specified, +or +.IR fildes +is not open for write and PROT_WRITE was specified for a MAP_SHARED +type mapping. +.TP +.BR EAGAIN +The mapping could not be locked in memory, if required by +\fImlockall\fR(), +due to a lack of resources. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EINVAL +The value of +.IR len +is zero. +.TP +.BR EINVAL +The value of +.IR flags +is invalid (neither MAP_PRIVATE nor MAP_SHARED is set). +.TP +.BR EMFILE +The number of mapped regions would exceed an implementation-defined +limit (per process or per system). +.TP +.BR ENODEV +The +.IR fildes +argument refers to a file whose type is not supported by +\fImmap\fR(). +.TP +.BR ENOMEM +MAP_FIXED was specified, and the range +[\fIaddr\fP,\fIaddr\fP+\fIlen\fR) exceeds that allowed for the +address space of a process; or, if MAP_FIXED was not specified and +there is insufficient room in the address space to effect the mapping. +.TP +.BR ENOMEM +The mapping could not be locked in memory, if required by +\fImlockall\fR(), +because it would require more space than the system is able to supply. +.TP +.BR ENOMEM +Not enough unallocated memory resources remain in the typed memory +object designated by +.IR fildes +to allocate +.IR len +bytes. +.TP +.BR ENOTSUP +MAP_FIXED or MAP_PRIVATE was specified in the +.IR flags +argument and the implementation does not support this functionality. +.RS 12 +.P +The implementation does not support the combination of accesses +requested in the +.IR prot +argument. +.RE +.TP +.BR ENXIO +Addresses in the range [\fIoff\fP,\fIoff\fP+\fIlen\fR) are invalid +for the object specified by +.IR fildes . +.TP +.BR ENXIO +MAP_FIXED was specified in +.IR flags +and the combination of +.IR addr , +.IR len , +and +.IR off +is invalid for the object specified by +.IR fildes . +.TP +.BR ENXIO +The +.IR fildes +argument refers to a typed memory object that is not accessible from +the calling process. +.TP +.BR EOVERFLOW +The file is a regular file and the value of +.IR off +plus +.IR len +exceeds the offset maximum established in the open file description +associated with +.IR fildes . +.br +.P +The +\fImmap\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR addr +argument (if MAP_FIXED was specified) or +.IR off +is not a multiple of the page size as returned by +\fIsysconf\fR(), +or is considered invalid by the implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Use of +\fImmap\fR() +may reduce the amount of memory available to other memory allocation +functions. +.P +Use of MAP_FIXED may result in unspecified behavior in further use of +\fImalloc\fR() +and +\fIshmat\fR(). +The use of MAP_FIXED is discouraged, as it may prevent an +implementation from making the most effective use of resources. Most +implementations require that +.IR off +and +.IR addr +are multiples of the page size as returned by +\fIsysconf\fR(). +.P +The application must ensure correct synchronization when using +\fImmap\fR() +in conjunction with any other file access method, such as +\fIread\fR() +and +\fIwrite\fR(), +standard input/output, and +\fIshmat\fR(). +.P +The +\fImmap\fR() +function allows access to resources via address space manipulations, +instead of +\fIread\fR()/\c +\fIwrite\fR(). +Once a file is mapped, all a process has to do to access it is use the +data at the address to which the file was mapped. So, using +pseudo-code to illustrate the way in which an existing program might be +changed to use +\fImmap\fR(), +the following: +.sp +.RS 4 +.nf +\fB +fildes = open(...) +lseek(fildes, some_offset) +read(fildes, buf, len) +/* Use data in buf. */ +.fi \fR +.P +.RE +.P +becomes: +.sp +.RS 4 +.nf +\fB +fildes = open(...) +address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) +/* Use data at address. */ +.fi \fR +.P +.RE +.SH RATIONALE +After considering several other alternatives, it was decided to adopt +the +\fImmap\fR() +definition found in SVR4 for mapping memory objects into process +address spaces. The SVR4 definition is minimal, in that it describes +only what has been built, and what appears to be necessary for a +general and portable mapping facility. +.P +Note that while +\fImmap\fR() +was first designed for mapping files, it is actually a general-purpose +mapping facility. It can be used to map any appropriate object, such +as memory, files, devices, and so on, into the address space of a +process. +.P +When a mapping is established, it is possible that the implementation +may need to map more than is requested into the address space of the +process because of hardware requirements. An application, however, +cannot count on this behavior. Implementations that do not use a paged +architecture may simply allocate a common memory region and return the +address of it; such implementations probably do not allocate any more +than is necessary. References past the end of the requested area are +unspecified. +.P +If an application requests a mapping that would overlay existing +mappings in the process, it might be desirable that an implementation +detect this and inform the application. However, the default, portable +(not MAP_FIXED) +operation does not overlay existing mappings. On the other hand, if the +program specifies a fixed address mapping (which requires some +implementation knowledge to determine a suitable address, if the +function is supported at all), then the program is presumed to be +successfully managing its own address space and should be trusted when +it asks to map over existing data structures. Furthermore, it is also +desirable to make as few system calls as possible, and it might be +considered onerous to require an +\fImunmap\fR() +before an +\fImmap\fR() +to the same address range. This volume of POSIX.1\(hy2008 specifies that the new mappings +replace any existing mappings, following existing practice in this +regard. +.P +It is not expected that all hardware implementations are able to +support all combinations of permissions at all addresses. +Implementations are required to disallow write +access to mappings without write permission and to disallow access to +mappings without any access permission. Other than these restrictions, +implementations may allow access types other than those requested by +the application. For example, if the application requests only +PROT_WRITE, the implementation may also allow read access. A call to +\fImmap\fR() +fails if the implementation cannot support allowing all the access +requested by the application. For example, some implementations +cannot support a request for both write access and execute access +simultaneously. All implementations must support requests for no access, +read access, write access, and both read and write access. Strictly +conforming code must only rely on the required checks. These restrictions +allow for portability across a wide range of hardware. +.P +The MAP_FIXED address treatment is likely to fail for non-page-aligned +values and for certain architecture-dependent address ranges. +Conforming implementations cannot count on being able to choose address +values for MAP_FIXED without utilizing non-portable, +implementation-defined knowledge. Nonetheless, MAP_FIXED is provided +as a standard interface conforming to existing practice for utilizing +such knowledge when it is available. +.P +Similarly, in order to allow implementations that do not support +virtual addresses, support for directly specifying any mapping +addresses via MAP_FIXED is not required and thus a conforming +application may not count on it. +.P +The MAP_PRIVATE +function can be implemented efficiently when memory protection hardware +is available. When such hardware is not available, implementations can +implement such ``mappings'' +by simply making a real copy of the relevant data into process private +memory, though this tends to behave similarly to +\fIread\fR(). +.P +The function has been defined to allow for many different models of +using shared memory. However, all uses are not equally portable across +all machine architectures. In particular, the +\fImmap\fR() +function allows the system as well as the application to specify the +address at which to map a specific region of a memory object. The most +portable way to use the function is always to let the system choose +the address, specifying NULL as the value for the argument +.IR addr +and not to specify MAP_FIXED. +.P +If it is intended that a particular region of a memory object be mapped +at the same address in a group of processes (on machines where this is +even possible), then MAP_FIXED can be used to pass in the desired +mapping address. The system can still be used to choose the desired +address if the first such mapping is made without specifying MAP_FIXED, +and then the resulting mapping address can be passed to subsequent +processes for them to pass in via MAP_FIXED. The availability of a +specific address range cannot be guaranteed, in general. +.P +The +\fImmap\fR() +function can be used to map a region of memory that is larger than the +current size of the object. Memory access within the mapping but +beyond the current end of the underlying objects may result in SIGBUS +signals being sent to the process. The reason for this is that the +size of the object can be manipulated by other processes and can change +at any moment. The implementation should tell the application that a +memory reference is outside the object where this can be detected; +otherwise, written data may be lost and read data may not reflect +actual data in the object. +.P +Note that references beyond the end of the object do not extend the +object as the new end cannot be determined precisely by most virtual +memory hardware. Instead, the size can be directly manipulated by +\fIftruncate\fR(). +.P +Process memory locking does apply to shared memory regions, and the +MEMLOCK_FUTURE argument to +\fImlockall\fR() +can be relied upon to cause new shared memory regions to be +automatically locked. +.P +Existing implementations of +\fImmap\fR() +return the value \(mi1 when unsuccessful. Since the casting of this +value to type +.BR "void *" +cannot be guaranteed by the ISO\ C standard to be distinct from a successful +value, this volume of POSIX.1\(hy2008 defines the symbol MAP_FAILED, +which a conforming implementation does not return as the result of a +successful call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlockf\fR\^(\|)", +.IR "\fImsync\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)", +.IR "\fImprotect\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/modf.3p b/man-pages-posix-2013-a/man3p/modf.3p new file mode 100644 index 0000000..52c31d9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/modf.3p @@ -0,0 +1,107 @@ +'\" et +.TH MODF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +modf, +modff, +modfl +\(em decompose a floating-point number +.SH SYNOPSIS +.LP +.nf +#include +.P +double modf(double \fIx\fP, double *\fIiptr\fP); +float modff(float \fIvalue\fP, float *\fIiptr\fP); +long double modfl(long double \fIvalue\fP, long double *\fIiptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall break the argument +.IR x +into integral and fractional parts, each of which has the same sign as +the argument. It stores the integral part as a +.BR double +(for the +\fImodf\fR() +function), a +.BR float +(for the +\fImodff\fR() +function), or a +.BR "long double" +(for the +\fImodfl\fR() +function), in the object pointed to by +.IR iptr . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the signed +fractional part of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned, and *\fIiptr\fP shall be set to a +NaN. +.P +If +.IR x +is \(+-Inf, \(+-0 shall be returned, and *\fIiptr\fP shall be set to +\(+-Inf. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fImodf\fR() +function computes the function result and *\fIiptr\fP such that: +.sp +.RS 4 +.nf +\fB +a = modf(x, iptr) ; +x == a+*iptr ; +.fi \fR +.P +.RE +.P +allowing for the usual floating-point inaccuracies. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfrexp\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIldexp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mprotect.3p b/man-pages-posix-2013-a/man3p/mprotect.3p new file mode 100644 index 0000000..3b4ad01 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mprotect.3p @@ -0,0 +1,158 @@ +'\" et +.TH MPROTECT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mprotect +\(em set protection of memory mapping +.SH SYNOPSIS +.LP +.nf +#include +.P +int mprotect(void *\fIaddr\fP, size_t \fIlen\fP, int \fIprot\fP); +.fi +.SH DESCRIPTION +The +\fImprotect\fR() +function shall change the access protections to be that specified by +.IR prot +for those whole pages containing any part of the address space of the +process starting at address +.IR addr +and continuing for +.IR len +bytes. The parameter +.IR prot +determines whether read, write, execute, or some combination of +accesses are permitted to the data being mapped. The +.IR prot +argument should be either PROT_NONE or the bitwise-inclusive OR of one +or more of PROT_READ, PROT_WRITE, and PROT_EXEC. +.P +If an implementation cannot support the combination of access types +specified by +.IR prot , +the call to +\fImprotect\fR() +shall fail. +.P +An implementation may permit accesses other than those specified by +.IR prot ; +however, no implementation shall permit a write to succeed where +PROT_WRITE has not been set or shall permit any access where PROT_NONE +alone has been set. Implementations shall support at least the +following values of +.IR prot : +PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of +PROT_READ and PROT_WRITE. If PROT_WRITE is specified, the application +shall ensure that it has opened the mapped objects in the specified +address range with write permission, unless MAP_PRIVATE +was specified in the original mapping, regardless of whether the file +descriptors used to map the objects have since been closed. +.P +The implementation may require that +.IR addr +be a multiple of the page size as returned by +\fIsysconf\fR(). +.P +The behavior of this function is unspecified if the mapping was not +established by a call to +\fImmap\fR(). +.P +When +\fImprotect\fR() +fails for reasons other than +.BR [EINVAL] , +the protections on some of the pages in the range +[\fIaddr\fP,\fIaddr\fP+\fIlen\fR) may have been changed. +.SH "RETURN VALUE" +Upon successful completion, +\fImprotect\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImprotect\fR() +function shall fail if: +.TP +.BR EACCES +The +.IR prot +argument specifies a protection that violates the access permission the +process has to the underlying memory object. +.TP +.BR EAGAIN +The +.IR prot +argument specifies PROT_WRITE over a MAP_PRIVATE mapping and there are +insufficient memory resources to reserve for locking the private page. +.TP +.BR ENOMEM +Addresses in the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fR) are invalid +for the address space of a process, or specify one or more pages which +are not mapped. +.TP +.BR ENOMEM +The +.IR prot +argument specifies PROT_WRITE on a MAP_PRIVATE mapping, and it would +require more space than the system is able to supply for locking the +private pages, if required. +.TP +.BR ENOTSUP +The implementation does not support the combination of accesses +requested in the +.IR prot +argument. +.P +The +\fImprotect\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR addr +argument is not a multiple of the page size as returned by +\fIsysconf\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Most implementations require that +.IR addr +is a multiple of the page size as returned by +\fIsysconf\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImmap\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_close.3p b/man-pages-posix-2013-a/man3p/mq_close.3p new file mode 100644 index 0000000..6d979e8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_close.3p @@ -0,0 +1,90 @@ +'\" et +.TH MQ_CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_close +\(em close a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_close(mqd_t \fImqdes\fP); +.fi +.SH DESCRIPTION +The +\fImq_close\fR() +function shall remove the association between the message queue +descriptor, +.IR mqdes , +and its message queue. The results of using this message queue +descriptor after successful return from this +\fImq_close\fR(), +and until the return of this message queue descriptor from a subsequent +\fImq_open\fR(), +are undefined. +.P +If the process has successfully attached a notification request to the +message queue via this +.IR mqdes , +this attachment shall be removed, and the message queue is available +for another process to attach for notification. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_close\fR() +function shall return a value of zero; otherwise, the function shall +return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_close\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_getattr.3p b/man-pages-posix-2013-a/man3p/mq_getattr.3p new file mode 100644 index 0000000..b6399a8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_getattr.3p @@ -0,0 +1,111 @@ +'\" et +.TH MQ_GETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_getattr +\(em get message queue attributes +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_getattr(mqd_t \fImqdes\fP, struct mq_attr *\fImqstat\fP); +.fi +.SH DESCRIPTION +The +\fImq_getattr\fR() +function shall obtain status information and attributes of the message +queue and the open message queue description associated with the +message queue descriptor. +.P +The +.IR mqdes +argument specifies a message queue descriptor. +.P +The results shall be returned in the +.BR mq_attr +structure referenced by the +.IR mqstat +argument. +.P +Upon return, the following members shall have the values associated +with the open message queue description as set when the message queue +was opened and as modified by subsequent +\fImq_setattr\fR() +calls: +.IR mq_flags . +.P +The following attributes of the message queue shall be returned as set +at message queue creation: +.IR mq_maxmsg , +.IR mq_msgsize . +.P +Upon return, the following members within the +.BR mq_attr +structure referenced by the +.IR mqstat +argument shall be set to the current state of the message queue: +.IP "\fImq_curmsgs\fP" 10 +The number of messages currently on the queue. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_getattr\fR() +function shall return zero. Otherwise, the function shall return +\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_getattr\fR() +function may fail if: +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +See +.IR "\fImq_notify\fR\^(\|)". +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_notify.3p b/man-pages-posix-2013-a/man3p/mq_notify.3p new file mode 100644 index 0000000..f0895d5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_notify.3p @@ -0,0 +1,196 @@ +'\" et +.TH MQ_NOTIFY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_notify +\(em notify process that a message is available +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_notify(mqd_t \fImqdes\fP, const struct sigevent *\fInotification\fP); +.fi +.SH DESCRIPTION +If the argument +.IR notification +is not NULL, this function shall register the calling process to be +notified of message arrival at an empty message queue associated with +the specified message queue descriptor, +.IR mqdes . +The notification specified by the +.IR notification +argument shall be sent to the process when the message queue transitions +from empty to non-empty. At any time, only one process may be +registered for notification by a message queue. If the calling process +or any other process has already registered for notification of message +arrival at the specified message queue, subsequent attempts to register +for that message queue shall fail. +.P +If +.IR notification +is NULL and the process is currently registered for notification by the +specified message queue, the existing registration shall be removed. +.P +When the notification is sent to the registered process, its +registration shall be removed. The message queue shall then be available +for registration. +.P +If a process has registered for notification of message arrival at a +message queue and some thread is blocked in +\fImq_receive\fR() +or +\fImq_timedreceive\fR() +waiting to receive a message when a message arrives at the queue, the +arriving message shall satisfy the appropriate +\fImq_receive\fR() +or +\fImq_timedreceive\fR(), +respectively. The resulting behavior is as if the message queue remains +empty, and no notification shall be sent. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_notify\fR() +function shall return a value of zero; otherwise, the function shall +return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_notify\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor. +.TP +.BR EBUSY +A process is already registered for notification by the message queue. +.P +The +\fImq_notify\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR notification +argument is NULL and the process is currently not registered. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following program registers a notification request for the message +queue named in its command-line argument. Notification is performed +by creating a thread. The thread executes a function which reads one +message from the queue and then terminates the process. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +.P +static void /* Thread start function */ +tfunc(union sigval sv) +{ + struct mq_attr attr; + ssize_t nr; + void *buf; + mqd_t mqdes = *((mqd_t *) sv.sival_ptr); +.P + /* Determine maximum msg size; allocate buffer to receive msg */ +.P + if (mq_getattr(mqdes, &attr) == -1) { + perror("mq_getattr"); + exit(EXIT_FAILURE); + } + buf = malloc(attr.mq_msgsize); +.P + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +.P + nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); + if (nr == -1) { + perror("mq_receive"); + exit(EXIT_FAILURE); + } +.P + printf("Read %ld bytes from message queue\en", (long) nr); + free(buf); + exit(EXIT_SUCCESS); /* Terminate the process */ +} +.P +int +main(int argc, char *argv[]) +{ + mqd_t mqdes; + struct sigevent not; +.P + assert(argc == 2); +.P + mqdes = mq_open(argv[1], O_RDONLY); + if (mqdes == (mqd_t) -1) { + perror("mq_open"); + exit(EXIT_FAILURE); + } +.P + not.sigev_notify = SIGEV_THREAD; + not.sigev_notify_function = tfunc; + not.sigev_notify_attributes = NULL; + not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */ + if (mq_notify(mqdes, ¬) == -1) { + perror("mq_notify"); + exit(EXIT_FAILURE); + } +.P + pause(); /* Process will be terminated by thread function */ +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_open.3p b/man-pages-posix-2013-a/man3p/mq_open.3p new file mode 100644 index 0000000..4c610bb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_open.3p @@ -0,0 +1,317 @@ +'\" et +.TH MQ_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_open +\(em open a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +mqd_t mq_open(const char *\fIname\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +The +\fImq_open\fR() +function shall establish the connection between a process and a message +queue with a message queue descriptor. It shall create an open message +queue description that refers to the message queue, and a message queue +descriptor that refers to that open message queue description. The +message queue descriptor is used by other functions to refer to that +message queue. The +.IR name +argument points to a string naming a message queue. It is unspecified +whether the name appears in the file system and is visible to other +functions that take pathnames as arguments. The +.IR name +argument conforms to the construction rules for a pathname, except that +the interpretation of + +characters other than the leading + +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as the +pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the + +character, then processes calling +\fImq_open\fR() +with the same value of +.IR name +shall refer to the same message queue object, as long as that name +has not been removed. If +.IR name +does not begin with the + +character, the effect is implementation-defined. If the +.IR name +argument is not the name of an existing message queue and creation is +not requested, +\fImq_open\fR() +shall fail and return an error. +.P +A message queue descriptor may be implemented using a file +descriptor, in which case applications can open up to at least +{OPEN_MAX} +file and message queues. +.P +The +.IR oflag +argument requests the desired receive and/or send access to the message +queue. The requested access permission to receive messages or send +messages shall be granted if the calling process would be granted read +or write access, respectively, to an equivalently protected file. +.P +The value of +.IR oflag +is the bitwise-inclusive OR of values from the following list. +Applications shall specify exactly one of the first three values +(access modes) below in the value of +.IR oflag : +.IP O_RDONLY 12 +Open the message queue for receiving messages. The process can use the +returned message queue descriptor with +\fImq_receive\fR(), +but not +\fImq_send\fR(). +A message queue may be open multiple times in the same or different +processes for receiving messages. +.IP O_WRONLY 12 +Open the queue for sending messages. The process can use the returned +message queue descriptor with +\fImq_send\fR() +but not +\fImq_receive\fR(). +A message queue may be open multiple times in the same or different +processes for sending messages. +.IP O_RDWR 12 +Open the queue for both receiving and sending messages. The process +can use any of the functions allowed for O_RDONLY and O_WRONLY. A +message queue may be open multiple times in the same or different +processes for sending messages. +.P +Any combination of the remaining flags may be specified in the value of +.IR oflag : +.IP O_CREAT 12 +Create a message queue. It requires two additional arguments: +.IR mode , +which shall be of type +.BR mode_t , +and +.IR attr , +which shall be a pointer to an +.BR mq_attr +structure. If the pathname +.IR name +has already been used to create a message queue that still exists, then +this flag shall have no effect, except as noted under O_EXCL. +Otherwise, a message queue shall be created without any messages in +it. The user ID of the message queue shall be set to the effective +user ID of the process. The group ID of the message queue shall be +set to the effective group ID of the process; however, if the +.IR name +argument is visible in the file system, the group ID may be set +to the group ID of the containing directory. When bits in +.IR mode +other than the file permission bits are specified, the effect is +unspecified. If +.IR attr +is NULL, the message queue shall be created with implementation-defined +default message queue attributes. If +.IR attr +is non-NULL and the calling process has appropriate privileges on +.IR name , +the message queue +.IR mq_maxmsg +and +.IR mq_msgsize +attributes shall be set to the values of the corresponding members in the +.BR mq_attr +structure referred to by +.IR attr . +The values of the +.IR mq_flags +and +.IR mq_curmsgs +members of the +.BR mq_attr +structure shall be ignored. If +.IR attr +is non-NULL, but the calling process does not have appropriate +privileges on +.IR name , +the +\fImq_open\fR() +function shall fail and return an error without creating the message +queue. +.IP O_EXCL 12 +If O_EXCL and O_CREAT are set, +\fImq_open\fR() +shall fail if the message queue +.IR name +exists. The check for the existence of the message queue and the +creation of the message queue if it does not exist shall be atomic with +respect to other threads executing +\fImq_open\fR() +naming the same +.IR name +with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, +the result is undefined. +.IP O_NONBLOCK 12 +Determines whether an +\fImq_send\fR() +or +\fImq_receive\fR() +waits for resources or messages that are not currently available, or +fails with +.IR errno +set to +.BR [EAGAIN] ; +see +.IR "\fImq_send\fR\^(\|)" +and +.IR "\fImq_receive\fR\^(\|)" +for details. +.P +The +\fImq_open\fR() +function does not add or remove messages from the queue. +.SH "RETURN VALUE" +Upon successful completion, the function shall return a message queue +descriptor; otherwise, the function shall return (\fBmqd_t\fP)\(mi1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_open\fR() +function shall fail if: +.TP +.BR EACCES +The message queue exists and the permissions specified by +.IR oflag +are denied, or the message queue does not exist and permission to +create the message queue is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set and the named message queue already exists. +.TP +.BR EINTR +The +\fImq_open\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +\fImq_open\fR() +function is not supported for the given name. +.TP +.BR EINVAL +O_CREAT was specified in +.IR oflag , +the value of +.IR attr +is not NULL, and either +.IR mq_maxmsg +or +.IR mq_msgsize +was less than or equal to zero. +.TP +.BR EMFILE +Too many message queue descriptors or file descriptors are currently in +use by this process. +.TP +.BR ENFILE +Too many message queues are currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and the named message queue does not exist. +.TP +.BR ENOSPC +There is insufficient space for the creation of the new message queue. +.br +.P +If any of the following conditions occur, the +\fImq_open\fR() +function may return (\c +.BR mqd_t )\(mi1 +and set +.IR errno +to the corresponding value. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fImq_open\fR() +and +\fImq_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_receive.3p b/man-pages-posix-2013-a/man3p/mq_receive.3p new file mode 100644 index 0000000..71624f0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_receive.3p @@ -0,0 +1,201 @@ +'\" et +.TH MQ_RECEIVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_receive, +mq_timedreceive +\(em receive a message from a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t mq_receive(mqd_t \fImqdes\fP, char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned *\fImsg_prio\fP); +.P +#include +#include +.P +ssize_t mq_timedreceive(mqd_t \fImqdes\fP, char *restrict \fImsg_ptr\fP, + size_t \fImsg_len\fP, unsigned *restrict \fImsg_prio\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fImq_receive\fR() +function shall receive the oldest of the highest priority +message(s) from the message queue specified by +.IR mqdes . +If the size of the buffer in bytes, specified by the +.IR msg_len +argument, is less than the +.IR mq_msgsize +attribute of the message queue, the function shall fail and return an +error. Otherwise, the selected message shall be removed from the queue +and copied to the buffer pointed to by the +.IR msg_ptr +argument. +.P +If the value of +.IR msg_len +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +If the argument +.IR msg_prio +is not NULL, the priority of the selected message shall be stored in the +location referenced by +.IR msg_prio . +.P +If the specified message queue is empty and O_NONBLOCK +is not set in the message queue description associated with +.IR mqdes , +\fImq_receive\fR() +shall block until a message is enqueued on the message queue or until +\fImq_receive\fR() +is interrupted by a signal. If more than one thread is waiting to +receive a message when a message arrives at an empty queue and the +Priority Scheduling option is supported, then the thread of highest +priority that has been waiting the longest shall be selected to receive +the message. Otherwise, it is unspecified which waiting thread receives +the message. If the specified message queue is empty and O_NONBLOCK is +set in the message queue description associated with +.IR mqdes , +no message shall be removed from the queue, and +\fImq_receive\fR() +shall return an error. +.P +The +\fImq_timedreceive\fR() +function shall receive the oldest of the highest priority messages +from the message queue specified by +.IR mqdes +as described for the +\fImq_receive\fR() +function. However, if O_NONBLOCK was not specified when the message +queue was opened via the +\fImq_open\fR() +function, and no message exists on the queue to satisfy the receive, +the wait for such a message shall be terminated when the specified +timeout expires. If O_NONBLOCK is set, this function is equivalent to +\fImq_receive\fR(). +.P +The timeout expires when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock on +which it is based. The +.IR timespec +argument is defined in the +.IR +header. +.P +Under no circumstance shall the operation fail with a timeout if a +message can be removed from the message queue immediately. The validity +of the +.IR abstime +parameter need not be checked if a message can be removed from the +message queue immediately. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_receive\fR() +and +\fImq_timedreceive\fR() +functions shall return the length of the selected message in bytes and +the message shall be removed from the queue. Otherwise, no message +shall be removed from the queue, the functions shall return a value of +\(mi1, and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EAGAIN +O_NONBLOCK was set in the message description associated with +.IR mqdes , +and the specified message queue is empty. +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor open for reading. +.TP +.BR EMSGSIZE +The specified message buffer size, +.IR msg_len , +is less than the message size attribute of the message queue. +.TP +.BR EINTR +The +\fImq_receive\fR() +or +\fImq_timedreceive\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR ETIMEDOUT +The O_NONBLOCK flag was not set when the message queue was opened, but +no message arrived on the queue before the specified timeout expired. +.P +These functions may fail if: +.TP +.BR EBADMSG +The implementation has detected a data corruption problem with the +message. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_send.3p b/man-pages-posix-2013-a/man3p/mq_send.3p new file mode 100644 index 0000000..eb430cc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_send.3p @@ -0,0 +1,210 @@ +'\" et +.TH MQ_SEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_send, +mq_timedsend +\(em send a message to a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_send(mqd_t \fImqdes\fP, const char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned \fImsg_prio\fP); +.P +#include +#include +.P +int mq_timedsend(mqd_t \fImqdes\fP, const char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned \fImsg_prio\fP, const struct timespec *\fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fImq_send\fR() +function shall add the message pointed to by the argument +.IR msg_ptr +to the message queue specified by +.IR mqdes . +The +.IR msg_len +argument specifies the length of the message, in bytes, pointed to by +.IR msg_ptr . +The value of +.IR msg_len +shall be less than or equal to the +.IR mq_msgsize +attribute of the message queue, or +\fImq_send\fR() +shall fail. +.P +If the specified message queue is not full, +\fImq_send\fR() +shall behave as if the message is inserted into the message queue at +the position indicated by the +.IR msg_prio +argument. A message with a larger numeric value of +.IR msg_prio +shall be inserted before messages with lower values of +.IR msg_prio . +A message shall be inserted after other messages in the queue, if any, +with equal +.IR msg_prio . +The value of +.IR msg_prio +shall be less than +{MQ_PRIO_MAX}. +.P +If the specified message queue is full and O_NONBLOCK +is not set in the message queue description associated with +.IR mqdes , +\fImq_send\fR() +shall block until space becomes available to enqueue the message, or +until +\fImq_send\fR() +is interrupted by a signal. If more than one thread is waiting to send +when space becomes available in the message queue and the Priority +Scheduling option is supported, then the thread of the highest priority +that has been waiting the longest shall be unblocked to send its +message. Otherwise, it is unspecified which waiting thread is +unblocked. If the specified message queue is full and O_NONBLOCK is +set in the message queue description associated with +.IR mqdes , +the message shall not be queued and +\fImq_send\fR() +shall return an error. +.P +The +\fImq_timedsend\fR() +function shall add a message to the message queue specified by +.IR mqdes +in the manner defined for the +\fImq_send\fR() +function. However, if the specified message queue is full and +O_NONBLOCK is not set in the message queue description associated with +.IR mqdes , +the wait for sufficient room in the queue shall be terminated when the +specified timeout expires. If O_NONBLOCK is set in the message queue +description, this function shall be equivalent to +\fImq_send\fR(). +.P +The timeout shall expire when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock on +which it is based. The +.IR timespec +argument is defined in the +.IR +header. +.P +Under no circumstance shall the operation fail with a timeout if there +is sufficient room in the queue to add the message immediately. The +validity of the +.IR abstime +parameter need not be checked when there is sufficient room in the +queue. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_send\fR() +and +\fImq_timedsend\fR() +functions shall return a value of zero. Otherwise, no message shall be +enqueued, the functions shall return \(mi1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fImq_send\fR() +and +\fImq_timedsend\fR() +functions shall fail if: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set in the message queue description associated +with +.IR mqdes , +and the specified message queue is full. +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor open for writing. +.TP +.BR EINTR +A signal interrupted the call to +\fImq_send\fR() +or +\fImq_timedsend\fR(). +.TP +.BR EINVAL +The value of +.IR msg_prio +was outside the valid range. +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR EMSGSIZE +The specified message length, +.IR msg_len , +exceeds the message size attribute of the message queue. +.TP +.BR ETIMEDOUT +The O_NONBLOCK flag was not set when the message queue was opened, but +the timeout expired before the message could be added to the queue. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The value of the symbol +{MQ_PRIO_MAX} +limits the number of priority levels supported by the application. +Message priorities range from 0 to +{MQ_PRIO_MAX}\(mi1. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_setattr.3p b/man-pages-posix-2013-a/man3p/mq_setattr.3p new file mode 100644 index 0000000..7d3e311 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_setattr.3p @@ -0,0 +1,112 @@ +'\" et +.TH MQ_SETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_setattr +\(em set message queue attributes +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_setattr(mqd_t \fImqdes\fP, const struct mq_attr *restrict \fImqstat\fP, + struct mq_attr *restrict \fIomqstat\fP); +.fi +.SH DESCRIPTION +The +\fImq_setattr\fR() +function shall set attributes associated with the open message queue +description referenced by the message queue descriptor specified by +.IR mqdes . +.P +The message queue attributes corresponding to the following members +defined in the +.BR mq_attr +structure shall be set to the specified values upon successful +completion of +\fImq_setattr\fR(): +.IP "\fImq_flags\fP" 12 +The value of this member is the bitwise-logical OR of zero or more of +O_NONBLOCK and any implementation-defined flags. +.P +The values of the +.IR mq_maxmsg , +.IR mq_msgsize , +and +.IR mq_curmsgs +members of the +.BR mq_attr +structure shall be ignored by +\fImq_setattr\fR(). +.P +If +.IR omqstat +is non-NULL, the +\fImq_setattr\fR() +function shall store, in the location referenced by +.IR omqstat , +the previous message queue attributes and the current queue status. +These values shall be the same as would be returned by a call to +\fImq_getattr\fR() +at that point. +.SH "RETURN VALUE" +Upon successful completion, the function shall return a value of zero +and the attributes of the message queue shall have been changed as +specified. +.P +Otherwise, the message queue attributes shall be unchanged, and the +function shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_setattr\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_timedreceive.3p b/man-pages-posix-2013-a/man3p/mq_timedreceive.3p new file mode 100644 index 0000000..02f351c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_timedreceive.3p @@ -0,0 +1,42 @@ +'\" et +.TH MQ_TIMEDRECEIVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_timedreceive +\(em receive a message from a message queue +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +ssize_t mq_timedreceive(mqd_t \fImqdes\fP, char *restrict \fImsg_ptr\fP, + size_t \fImsg_len\fP, unsigned *restrict \fImsg_prio\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImq_receive\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_timedsend.3p b/man-pages-posix-2013-a/man3p/mq_timedsend.3p new file mode 100644 index 0000000..483c3e0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_timedsend.3p @@ -0,0 +1,41 @@ +'\" et +.TH MQ_TIMEDSEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_timedsend +\(em send a message to a message queue +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int mq_timedsend(mqd_t \fImqdes\fP, const char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned \fImsg_prio\fP, const struct timespec *\fIabstime\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImq_send\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mq_unlink.3p b/man-pages-posix-2013-a/man3p/mq_unlink.3p new file mode 100644 index 0000000..c3c5efb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mq_unlink.3p @@ -0,0 +1,127 @@ +'\" et +.TH MQ_UNLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mq_unlink +\(em remove a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_unlink(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fImq_unlink\fR() +function shall remove the message queue named by the string name. +If one or more processes have the message queue open when +\fImq_unlink\fR() +is called, destruction of the message queue shall be postponed until +all references to the message queue have been closed. However, the +\fImq_unlink\fR() +call need not block until all references have been closed; it may return +immediately. +.P +After a successful call to +\fImq_unlink\fR(), +reuse of the name shall subsequently cause +\fImq_open\fR() +to behave as if no message queue of this name exists (that is, +\fImq_open\fR() +will fail if O_CREAT is not set, or will create a new message queue if +O_CREAT is set). +.SH "RETURN VALUE" +Upon successful completion, the function shall return a value of zero. +Otherwise, the named message queue shall be unchanged by this function +call, and the function shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_unlink\fR() +function shall fail if: +.TP +.BR EACCES +Permission is denied to unlink the named message queue. +.TP +.BR ENOENT +The named message queue does not exist. +.P +The +\fImq_unlink\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +A call to +\fImq_unlink\fR() +with a +.IR name +argument that contains the same message queue name as was previously +used in a successful +\fImq_open\fR() +call shall not give an +.BR [ENAMETOOLONG] +error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fImq_open\fR() +and +\fImq_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/mrand48.3p b/man-pages-posix-2013-a/man3p/mrand48.3p new file mode 100644 index 0000000..f295641 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/mrand48.3p @@ -0,0 +1,38 @@ +'\" et +.TH MRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mrand48 +\(em generate uniformly distributed pseudo-random signed long integers +.SH SYNOPSIS +.LP +.nf +#include +.P +long mrand48(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/msgctl.3p b/man-pages-posix-2013-a/man3p/msgctl.3p new file mode 100644 index 0000000..558b1b9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/msgctl.3p @@ -0,0 +1,188 @@ +'\" et +.TH MSGCTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +msgctl +\(em XSI message control operations +.SH SYNOPSIS +.LP +.nf +#include +.P +int msgctl(int \fImsqid\fP, int \fIcmd\fP, struct msqid_ds *\fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fImsgctl\fR() +function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.225" ", " "Message Queue"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fImsgctl\fR() +function shall provide message control operations as specified by +.IR cmd . +The following values for +.IR cmd , +and the message control operations they specify, are: +.IP IPC_STAT 12 +Place the current value of each member of the +.BR msqid_ds +data structure associated with +.IR msqid +into the structure pointed to by +.IR buf . +The contents of this structure are defined in +.IR . +.IP IPC_SET 12 +Set the value of the following members of the +.BR msqid_ds +data structure associated with +.IR msqid +to the corresponding value found in the structure pointed to by +.IR buf : +.RS 12 +.sp +.RS 4 +.nf +\fB +msg_perm.uid +msg_perm.gid +msg_perm.mode +msg_qbytes +.fi \fR +.P +.RE +.P +Also, the +.IR msg_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +IPC_SET can only be executed by a process with appropriate privileges +or that has an effective user ID equal to the value of +.BR msg_perm.cuid +or +.BR msg_perm.uid +in the +.BR msqid_ds +data structure associated with +.IR msqid . +Only a process with appropriate privileges can raise the value of +.BR msg_qbytes . +.RE +.IP IPC_RMID 12 +Remove the message queue identifier specified by +.IR msqid +from the system and destroy the message queue and +.BR msqid_ds +data structure associated with it. IPC_RMD can only be executed by a +process with appropriate privileges or one that has an effective user +ID equal to the value of +.BR msg_perm.cuid +or +.BR msg_perm.uid +in the +.BR msqid_ds +data structure associated with +.IR msqid . +.SH "RETURN VALUE" +Upon successful completion, +\fImsgctl\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImsgctl\fR() +function shall fail if: +.TP +.BR EACCES +The argument +.IR cmd +is IPC_STAT and the calling process does not have read permission; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EINVAL +The value of +.IR msqid +is not a valid message queue identifier; or the value of +.IR cmd +is not a valid command. +.TP +.BR EPERM +The argument +.IR cmd +is IPC_RMID or IPC_SET +and the effective user ID of the calling process is not equal to that +of a process with appropriate privileges and it is not equal to the +value of +.BR msg_perm.cuid +or +.BR msg_perm.uid +in the data structure associated with +.IR msqid . +.TP +.BR EPERM +The argument +.IR cmd +is IPC_SET, an attempt is being made to increase to the value of +.BR msg_qbytes , +and the effective user ID of the calling process does not have +appropriate privileges. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess communication +(IPC). Application developers who need to use IPC should design their +applications so that modules using the IPC routines described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.225" ", " "Message Queue", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/msgget.3p b/man-pages-posix-2013-a/man3p/msgget.3p new file mode 100644 index 0000000..a3ccdd6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/msgget.3p @@ -0,0 +1,164 @@ +'\" et +.TH MSGGET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +msgget +\(em get the XSI message queue identifier +.SH SYNOPSIS +.LP +.nf +#include +.P +int msgget(key_t \fIkey\fP, int \fImsgflg\fP); +.fi +.SH DESCRIPTION +The +\fImsgget\fR() +function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.225" ", " "Message Queue"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fImsgget\fR() +function shall return the message queue identifier associated with the +argument +.IR key . +.P +A message queue identifier, associated message queue, and data +structure (see +.IR ), +shall be created for the argument +.IR key +if one of the following is true: +.IP " *" 4 +The argument +.IR key +is equal to IPC_PRIVATE. +.IP " *" 4 +The argument +.IR key +does not already have a message queue identifier associated with it, +and (\fImsgflg\fP & IPC_CREAT) is non-zero. +.P +Upon creation, the data structure associated with the new message queue +identifier shall be initialized as follows: +.IP " *" 4 +.BR msg_perm.cuid , +.BR msg_perm.uid , +.BR msg_perm.cgid , +and +.BR msg_perm.gid +shall be set to the effective user ID and effective group ID, +respectively, of the calling process. +.IP " *" 4 +The low-order 9 bits of +.BR msg_perm.mode +shall be set to the low-order 9 bits of +.IR msgflg . +.IP " *" 4 +.BR msg_qnum , +.BR msg_lspid , +.BR msg_lrpid , +.BR msg_stime , +and +.BR msg_rtime +shall be set to 0. +.IP " *" 4 +.BR msg_ctime +shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.IP " *" 4 +.BR msg_qbytes +shall be set to the system limit. +.SH "RETURN VALUE" +Upon successful completion, +\fImsgget\fR() +shall return a non-negative integer, namely a message queue identifier. +Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImsgget\fR() +function shall fail if: +.TP +.BR EACCES +A message queue identifier exists for the argument +.IR key , +but operation permission as specified by the low-order 9 bits of +.IR msgflg +would not be granted; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EEXIST +A message queue identifier exists for the argument +.IR key +but ((\fImsgflg\fP & IPC_CREAT) && (\fImsgflg\fP & IPC_EXCL)) is +non-zero. +.TP +.BR ENOENT +A message queue identifier does not exist for the argument +.IR key +and (\fImsgflg\fP & IPC_CREAT) is 0. +.TP +.BR ENOSPC +A message queue identifier is to be created but the system-imposed +limit on the maximum number of allowed message queue identifiers +system-wide would be exceeded. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess communication +(IPC). Application developers who need to use IPC should design their +applications so that modules using the IPC routines described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIftok\fR\^(\|)", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.225" ", " "Message Queue", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/msgrcv.3p b/man-pages-posix-2013-a/man3p/msgrcv.3p new file mode 100644 index 0000000..ef29b1f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/msgrcv.3p @@ -0,0 +1,272 @@ +'\" et +.TH MSGRCV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +msgrcv +\(em XSI message receive operation +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t msgrcv(int \fImsqid\fP, void *\fImsgp\fP, size_t \fImsgsz\fP, long \fImsgtyp\fP, + int \fImsgflg\fP); +.fi +.SH DESCRIPTION +The +\fImsgrcv\fR() +function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.225" ", " "Message Queue"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fImsgrcv\fR() +function shall read a message from the queue associated with the message +queue identifier specified by +.IR msqid +and place it in the user-defined buffer pointed to by +.IR msgp . +.P +The application shall ensure that the argument +.IR msgp +points to a user-defined buffer that contains first a field of type +.BR long +specifying the type of the message, and then a data portion that holds +the data bytes of the message. The structure below is an example of +what this user-defined buffer might look like: +.sp +.RS 4 +.nf +\fB +struct mymsg { + long mtype; /* Message type. */ + char mtext[1]; /* Message text. */ +} +.fi \fR +.P +.RE +.P +The structure member +.IR mtype +is the received message's type as specified by the sending process. +.P +The structure member +.IR mtext +is the text of the message. +.P +The argument +.IR msgsz +specifies the size in bytes of +.IR mtext . +The received message shall be truncated to +.IR msgsz +bytes if it is larger than +.IR msgsz +and (\fImsgflg\fP & MSG_NOERROR) is non-zero. +The truncated part of the message shall be lost and no indication of +the truncation shall be given to the calling process. +.P +If the value of +.IR msgsz +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +The argument +.IR msgtyp +specifies the type of message requested as follows: +.IP " *" 4 +If +.IR msgtyp +is 0, the first message on the queue shall be received. +.IP " *" 4 +If +.IR msgtyp +is greater than 0, the first message of type +.IR msgtyp +shall be received. +.IP " *" 4 +If +.IR msgtyp +is less than 0, the first message of the lowest type that is less than +or equal to the absolute value of +.IR msgtyp +shall be received. +.P +The argument +.IR msgflg +specifies the action to be taken if a message of the desired type is +not on the queue. These are as follows: +.IP " *" 4 +If (\fImsgflg\fP & IPC_NOWAIT) +is non-zero, the calling thread shall return immediately with a return +value of \(mi1 and +.IR errno +set to +.BR [ENOMSG] . +.IP " *" 4 +If (\fImsgflg\fP & IPC_NOWAIT) is 0, the calling thread shall suspend +execution until one of the following occurs: +.RS 4 +.IP -- 4 +A message of the desired type is placed on the queue. +.IP -- 4 +The message queue identifier +.IR msqid +is removed from the system; when this occurs, +.IR errno +shall be set to +.BR [EIDRM] +and \(mi1 shall be returned. +.IP -- 4 +The calling thread receives a signal that is to be caught; in this case +a message is not received and the calling thread resumes execution in +the manner prescribed in +.IR "\fIsigaction\fR\^(\|)". +.RE +.P +Upon successful completion, the following actions are taken with +respect to the data structure associated with +.IR msqid : +.IP " *" 4 +.BR msg_qnum +shall be decremented by 1. +.IP " *" 4 +.BR msg_lrpid +shall be set to the process ID of the calling process. +.IP " *" 4 +.BR msg_rtime +shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.SH "RETURN VALUE" +Upon successful completion, +\fImsgrcv\fR() +shall return a value equal to the number of bytes actually placed +into the buffer +.IR mtext . +Otherwise, no message shall be received, +\fImsgrcv\fR() +shall return \(mi1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fImsgrcv\fR() +function shall fail if: +.TP +.BR E2BIG +The value of +.IR mtext +is greater than +.IR msgsz +and (\fImsgflg\fP & MSG_NOERROR) is 0. +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EIDRM +The message queue identifier +.IR msqid +is removed from the system. +.TP +.BR EINTR +The +\fImsgrcv\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +.IR msqid +is not a valid message queue identifier. +.TP +.BR ENOMSG +The queue does not contain a message of the desired type and +(\fImsgflg\fP & IPC_NOWAIT) is non-zero. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Receiving a Message" +.P +The following example receives the first message on the queue (based on +the value of the +.IR msgtyp +argument, 0). The queue is identified by the +.IR msqid +argument (assuming that the value has previously been set). This call +specifies that an error should be reported if no message is available, +but not if the message is too large. The message size is calculated +directly using the +.IR sizeof +operator. +.sp +.RS 4 +.nf +\fB +#include +\&... +int result; +int msqid; +struct message { + long type; + char text[20]; +} msg; +long msgtyp = 0; +\&... +result = msgrcv(msqid, (void *) &msg, sizeof(msg.text), + msgtyp, MSG_NOERROR | IPC_NOWAIT); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess communication +(IPC). Application developers who need to use IPC should design their +applications so that modules using the IPC routines described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.225" ", " "Message Queue", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/msgsnd.3p b/man-pages-posix-2013-a/man3p/msgsnd.3p new file mode 100644 index 0000000..8c1c5b2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/msgsnd.3p @@ -0,0 +1,239 @@ +'\" et +.TH MSGSND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +msgsnd +\(em XSI message send operation +.SH SYNOPSIS +.LP +.nf +#include +.P +int msgsnd(int \fImsqid\fP, const void *\fImsgp\fP, size_t \fImsgsz\fP, int \fImsgflg\fP); +.fi +.SH DESCRIPTION +The +\fImsgsnd\fR() +function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.225" ", " "Message Queue"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fImsgsnd\fR() +function shall send a message to the queue associated with the +message queue identifier specified by +.IR msqid . +.P +The application shall ensure that the argument +.IR msgp +points to a user-defined buffer that contains first a field of type +.BR long +specifying the type of the message, and then a data portion that holds +the data bytes of the message. The structure below is an example of +what this user-defined buffer might look like: +.sp +.RS 4 +.nf +\fB +struct mymsg { + long mtype; /* Message type. */ + char mtext[1]; /* Message text. */ +} +.fi \fR +.P +.RE +.P +The structure member +.IR mtype +is a non-zero positive type +.BR long +that can be used by the receiving process for message selection. +.P +The structure member +.IR mtext +is any text of length +.IR msgsz +bytes. The argument +.IR msgsz +can range from 0 to a system-imposed maximum. +.P +The argument +.IR msgflg +specifies the action to be taken if one or more of the following is +true: +.IP " *" 4 +The number of bytes already on the queue is equal to +.BR msg_qbytes ; +see +.IR . +.IP " *" 4 +The total number of messages on all queues system-wide is equal to the +system-imposed limit. +.P +These actions are as follows: +.IP " *" 4 +If (\fImsgflg\fP & IPC_NOWAIT) +is non-zero, the message shall not be sent and the calling thread +shall return immediately. +.IP " *" 4 +If (\fImsgflg\fP & IPC_NOWAIT) is 0, the calling thread shall suspend +execution until one of the following occurs: +.RS 4 +.IP -- 4 +The condition responsible for the suspension no longer exists, in which +case the message is sent. +.IP -- 4 +The message queue identifier +.IR msqid +is removed from the system; when this occurs, +.IR errno +shall be set to +.BR [EIDRM] +and \(mi1 shall be returned. +.IP -- 4 +The calling thread receives a signal that is to be caught; in this case +the message is not sent and the calling thread resumes execution in the +manner prescribed in +.IR "\fIsigaction\fR\^(\|)". +.RE +.br +.P +Upon successful completion, the following actions are taken with +respect to the data structure associated with +.IR msqid ; +see +.IR : +.IP " *" 4 +.BR msg_qnum +shall be incremented by 1. +.IP " *" 4 +.BR msg_lspid +shall be set to the process ID of the calling process. +.IP " *" 4 +.BR msg_stime +shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.SH "RETURN VALUE" +Upon successful completion, +\fImsgsnd\fR() +shall return 0; otherwise, no message shall be sent, +\fImsgsnd\fR() +shall return \(mi1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fImsgsnd\fR() +function shall fail if: +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EAGAIN +The message cannot be sent for one of the reasons cited above and +(\fImsgflg\fP & IPC_NOWAIT) is non-zero. +.TP +.BR EIDRM +The message queue identifier +.IR msqid +is removed from the system. +.TP +.BR EINTR +The +\fImsgsnd\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The value of +.IR msqid +is not a valid message queue identifier, or the value of +.IR mtype +is less than 1; or the value of +.IR msgsz +is greater than the system-imposed limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Sending a Message" +.P +The following example sends a message to the queue identified by the +.IR msqid +argument (assuming that value has previously been set). This call +specifies that an error should be reported if no message is available. +The message size is calculated directly using the +.IR sizeof +operator. +.sp +.RS 4 +.nf +\fB +#include +\&... +int result; +int msqid; +struct message { + long type; + char text[20]; +} msg; +.P +msg.type = 1; +strcpy(msg.text, "This is message 1"); +\&... +result = msgsnd(msqid, (void *) &msg, sizeof(msg.text), IPC_NOWAIT); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess communication +(IPC). Application developers who need to use IPC should design their +applications so that modules using the IPC routines described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.225" ", " "Message Queue", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/msync.3p b/man-pages-posix-2013-a/man3p/msync.3p new file mode 100644 index 0000000..833a4ba --- /dev/null +++ b/man-pages-posix-2013-a/man3p/msync.3p @@ -0,0 +1,191 @@ +'\" et +.TH MSYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +msync +\(em synchronize memory with physical storage +.SH SYNOPSIS +.LP +.nf +#include +.P +int msync(void *\fIaddr\fP, size_t \fIlen\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fImsync\fR() +function shall write all modified data to permanent storage locations, +if any, in those whole pages containing any part of the address space of +the process starting at address +.IR addr +and continuing for +.IR len +bytes. If no such storage exists, +\fImsync\fR() +need not have any effect. If requested, the +\fImsync\fR() +function shall then invalidate cached copies of data. +.P +The implementation may require that +.IR addr +be a multiple of the page size as returned by +\fIsysconf\fR(). +.P +For mappings to files, the +\fImsync\fR() +function shall ensure that all write operations are completed as +defined for synchronized I/O data integrity completion. It is +unspecified whether the implementation also writes out other file +attributes. When the +\fImsync\fR() +function is called on MAP_PRIVATE mappings, any modified data shall +not be written to the underlying object and shall not cause such data +to be made visible to other processes. It is unspecified whether data +in MAP_PRIVATE mappings has any permanent storage locations. +The effect of +\fImsync\fR() +on a shared memory object or a typed memory object is unspecified. +The behavior of this function is unspecified if the mapping was not +established by a call to +\fImmap\fR(). +.P +The +.IR flags +argument is constructed from the bitwise-inclusive OR of one or more of +the following flags defined in the +.IR +header: +.TS +center box tab(!); +cB | cB +lw(1.5i) | lw(2i). +Symbolic Constant!Description +_ +MS_ASYNC!Perform asynchronous writes. +MS_SYNC!Perform synchronous writes. +MS_INVALIDATE!Invalidate cached data. +.TE +.P +When MS_ASYNC is specified, +\fImsync\fR() +shall return immediately once all the write operations are initiated or +queued for servicing; when MS_SYNC is specified, +\fImsync\fR() +shall not return until all write operations are completed as defined for +synchronized I/O data integrity completion. Either MS_ASYNC or MS_SYNC +shall be specified, but not both. +.P +When MS_INVALIDATE is specified, +\fImsync\fR() +shall invalidate all cached copies of mapped data that are inconsistent +with the permanent storage locations such that subsequent references +shall obtain data that was consistent with the permanent storage +locations sometime between the call to +\fImsync\fR() +and the first subsequent memory reference to the data. +.P +If +\fImsync\fR() +causes any write to a file, the file's last data modification and +last file status change timestamps shall be marked for update. +.SH "RETURN VALUE" +Upon successful completion, +\fImsync\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImsync\fR() +function shall fail if: +.TP +.BR EBUSY +Some or all of the addresses in the range starting at +.IR addr +and continuing for +.IR len +bytes are locked, and MS_INVALIDATE is specified. +.TP +.BR EINVAL +The value of +.IR flags +is invalid. +.TP +.BR ENOMEM +The addresses in the range starting at +.IR addr +and continuing for +.IR len +bytes are outside the range allowed for the address space of a process +or specify one or more pages that are not mapped. +.P +The +\fImsync\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR addr +is not a multiple of the page size as returned by +\fIsysconf\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fImsync\fR() +function is only supported if the Synchronized Input and Output +option is supported, and thus need not be available on all implementations. +.P +The +\fImsync\fR() +function should be used by programs that require a memory object to be +in a known state; for example, in building transaction facilities. +.P +Normal system activity can cause pages to be written to disk. +Therefore, there are no guarantees that +\fImsync\fR() +is the only control over when pages are or are not written to disk. +.SH RATIONALE +The +\fImsync\fR() +function writes out data in a mapped region to the permanent +storage for the underlying object. The call to +\fImsync\fR() +ensures data integrity of the file. +.P +After the data is written out, any cached data may be invalidated if +the MS_INVALIDATE +flag was specified. This is useful on systems that do not support +read/write consistency. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImmap\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/munlock.3p b/man-pages-posix-2013-a/man3p/munlock.3p new file mode 100644 index 0000000..fbb27e7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/munlock.3p @@ -0,0 +1,38 @@ +'\" et +.TH MUNLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +munlock +\(em unlock a range of process address space +.SH SYNOPSIS +.LP +.nf +#include +.P +int munlock(const void *\fIaddr\fP, size_t \fIlen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImlock\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/munlockall.3p b/man-pages-posix-2013-a/man3p/munlockall.3p new file mode 100644 index 0000000..b746eda --- /dev/null +++ b/man-pages-posix-2013-a/man3p/munlockall.3p @@ -0,0 +1,38 @@ +'\" et +.TH MUNLOCKALL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +munlockall +\(em unlock the address space of a process +.SH SYNOPSIS +.LP +.nf +#include +.P +int munlockall(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImlockall\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/munmap.3p b/man-pages-posix-2013-a/man3p/munmap.3p new file mode 100644 index 0000000..e737a96 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/munmap.3p @@ -0,0 +1,143 @@ +'\" et +.TH MUNMAP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +munmap +\(em unmap pages of memory +.SH SYNOPSIS +.LP +.nf +#include +.P +int munmap(void *\fIaddr\fP, size_t \fIlen\fP); +.fi +.SH DESCRIPTION +The +\fImunmap\fR() +function shall remove any mappings for those entire pages containing +any part of the address space of the process starting at +.IR addr +and continuing for +.IR len +bytes. Further references to these pages shall result in the +generation of a SIGSEGV signal to the process. +If there are no mappings in the specified address range, then +\fImunmap\fR() +has no effect. +.P +The implementation may require that +.IR addr +be a multiple of the page size as returned by +\fIsysconf\fR(). +.P +If a mapping to be removed was private, any modifications made in this +address range shall be discarded. +.P +Any memory locks (see +.IR "\fImlock\fR\^(\|)" +and +.IR "\fImlockall\fR\^(\|)") +associated with this address range shall be removed, as if by an +appropriate call to +\fImunlock\fR(). +.P +If a mapping removed from a typed memory object causes the +corresponding address range of the memory pool to be inaccessible by +any process in the system except through allocatable mappings (that is, +mappings of typed memory objects opened with the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag), then that range of the memory +pool shall become deallocated and may become available to satisfy +future typed memory allocation requests. +.P +A mapping removed from a typed memory object opened with the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag shall not affect in any way the +availability of that typed memory for allocation. +.P +The behavior of this function is unspecified if the mapping was not +established by a call to +\fImmap\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fImunmap\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImunmap\fR() +function shall fail if: +.TP +.BR EINVAL +Addresses in the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fR) are outside +the valid range for the address space of a process. +.TP +.BR EINVAL +The +.IR len +argument is 0. +.P +The +\fImunmap\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR addr +argument is not a multiple of the page size as returned by +\fIsysconf\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fImunmap\fR() +function corresponds to SVR4, just as the +\fImmap\fR() +function does. +.P +It is possible that an application has applied process memory locking +to a region that contains shared memory. If this has occurred, the +\fImunmap\fR() +call ignores those locks and, if necessary, causes those locks to be +removed. +.P +Most implementations require that +.IR addr +is a multiple of the page size as returned by +\fIsysconf\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImlock\fR\^(\|)", +.IR "\fImlockall\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/nan.3p b/man-pages-posix-2013-a/man3p/nan.3p new file mode 100644 index 0000000..a287256 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/nan.3p @@ -0,0 +1,112 @@ +'\" et +.TH NAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nan, +nanf, +nanl +\(em return quiet NaN +.SH SYNOPSIS +.LP +.nf +#include +.P +double nan(const char *\fItagp\fP); +float nanf(const char *\fItagp\fP); +long double nanl(const char *\fItagp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The function call \fInan\fR("\fIn-char-sequence\fR") shall be +equivalent to: +.sp +.RS 4 +.nf +\fB +strtod("NAN(\fIn-char-sequence\fP)", (char **) NULL); +.fi \fR +.P +.RE +.P +The function call \fInan\fR("\|") shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtod("NAN()", (char **) NULL) +.fi \fR +.P +.RE +.P +If +.IR tagp +does not point to an +.IR n -\c +.BR char +sequence or an empty string, the function call shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtod("NAN", (char **) NULL) +.fi \fR +.P +.RE +.P +Function calls to +\fInanf\fR() +and +\fInanl\fR() +are equivalent to the corresponding function calls to +\fIstrtof\fR() +and +\fIstrtold\fR(). +.SH "RETURN VALUE" +These functions shall return a quiet NaN, if available, with content +indicated through +.IR tagp . +.P +If the implementation does not support quiet NaNs, these functions +shall return zero. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtod\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/nanosleep.3p b/man-pages-posix-2013-a/man3p/nanosleep.3p new file mode 100644 index 0000000..5d03044 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/nanosleep.3p @@ -0,0 +1,145 @@ +'\" et +.TH NANOSLEEP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nanosleep +\(em high resolution sleep +.SH SYNOPSIS +.LP +.nf +#include +.P +int nanosleep(const struct timespec *\fIrqtp\fP, struct timespec *\fIrmtp\fP); +.fi +.SH DESCRIPTION +The +\fInanosleep\fR() +function shall cause the current thread to be suspended from execution +until either the time interval specified by the +.IR rqtp +argument has elapsed or a signal is delivered to the calling thread, +and its action is to invoke a signal-catching function or to terminate +the process. The suspension time may be longer than requested because +the argument value is rounded up to an integer multiple of the sleep +resolution or because of the scheduling of other activity by the +system. But, except for the case of being interrupted by a signal, the +suspension time shall not be less than the time specified by +.IR rqtp , +as measured by the system clock CLOCK_REALTIME. +.P +The use of the +\fInanosleep\fR() +function has no effect on the action or blockage of any signal. +.SH "RETURN VALUE" +If the +\fInanosleep\fR() +function returns because the requested time has elapsed, its return +value shall be zero. +.P +If the +\fInanosleep\fR() +function returns because it has been interrupted by a signal, it +shall return a value of \(mi1 and set +.IR errno +to indicate the interruption. If the +.IR rmtp +argument is non-NULL, the +.BR timespec +structure referenced by it is updated to contain the amount of time +remaining in the interval (the requested time minus the time actually +slept). The +.IR rqtp +and +.IR rmtp +arguments may point to the same object. If the +.IR rmtp +argument is NULL, the remaining time is not returned. +.P +If +\fInanosleep\fR() +fails, it shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fInanosleep\fR() +function shall fail if: +.TP +.BR EINTR +The +\fInanosleep\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +.IR rqtp +argument specified a nanosecond value less than zero or greater than or +equal to 1\|000 million. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +It is common to suspend execution of a thread for an interval in order +to poll the status of a non-interrupting function. A large number of +actual needs can be met with a simple extension to +\fIsleep\fR() +that provides finer resolution. +.P +In the POSIX.1\(hy1990 standard and SVR4, it is possible to implement such a routine, +but the frequency of wakeup is limited by the resolution of the +\fIalarm\fR() +and +\fIsleep\fR() +functions. In 4.3 BSD, it is possible to write such a routine using +no static storage and reserving no system facilities. Although it is +possible to write a function with similar functionality to +\fIsleep\fR() +using the remainder of the +.IR timer_* (\|) +functions, such a function requires the use of signals and the +reservation of some signal number. This volume of POSIX.1\(hy2008 requires that +\fInanosleep\fR() +be non-intrusive of the signals function. +.P +The +\fInanosleep\fR() +function shall return a value of 0 on success and \(mi1 on failure or if +interrupted. This latter case is different from +\fIsleep\fR(). +This was done because the remaining time is returned via an argument +structure pointer, +.IR rmtp , +instead of as the return value. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_nanosleep\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/nearbyint.3p b/man-pages-posix-2013-a/man3p/nearbyint.3p new file mode 100644 index 0000000..a913672 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/nearbyint.3p @@ -0,0 +1,89 @@ +'\" et +.TH NEARBYINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nearbyint, +nearbyintf, +nearbyintl +\(em floating-point rounding functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double nearbyint(double \fIx\fP); +float nearbyintf(float \fIx\fP); +long double nearbyintl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall round their argument to an integer value in +floating-point format, using the current rounding direction and without +raising the inexact floating-point exception. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +The result shall have the same sign as +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, \(+-0 shall be returned. +.P +If +.IR x +is \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer +type to avoid the undefined results of an integer overflow. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/newlocale.3p b/man-pages-posix-2013-a/man3p/newlocale.3p new file mode 100644 index 0000000..32b1fe8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/newlocale.3p @@ -0,0 +1,267 @@ +'\" et +.TH NEWLOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +newlocale +\(em create or modify a locale object +.SH SYNOPSIS +.LP +.nf +#include +.P +locale_t newlocale(int \fIcategory_mask\fP, const char *\fIlocale\fP, + locale_t \fIbase\fP); +.fi +.SH DESCRIPTION +The +\fInewlocale\fR() +function shall create a new locale object or modify an existing one. +If the +.IR base +argument is (\c +.BR locale_t )0, +a new locale object shall be created. It is unspecified whether the +locale object pointed to by +.IR base +shall be modified, or freed and a new locale object created. +.P +The +.IR category_mask +argument specifies the locale categories to be set or modified. +Values for +.IR category_mask +shall be constructed by a bitwise-inclusive OR of the symbolic +constants +.IR LC_CTYPE_MASK , +.IR LC_NUMERIC_MASK , +.IR LC_TIME_MASK , +.IR LC_COLLATE_MASK , +.IR LC_MONETARY_MASK , +and +.IR LC_MESSAGES_MASK , +or any of the other implementation-defined +.IR LC_*_MASK +values defined in +.IR . +.P +For each category with the corresponding bit set in +.IR category_mask +the data from the locale named by +.IR locale +shall be used. In the case of modifying an existing locale object, the +data from the locale named by +.IR locale +shall replace the existing data within the locale object. If a completely +new locale object is created, the data for all sections not requested by +.IR category_mask +shall be taken from the default locale. +.P +The following preset values of +.IR locale +are defined for all settings of +.IR category_mask : +.IP "\&\(dqPOSIX\(dq" 12 +Specifies the minimal environment for C-language translation called +the POSIX locale. +.IP "\&\(dqC\(dq" 12 +Equivalent to +.BR \(dqPOSIX\(dq . +.IP "\&\(dq\|\(dq" 12 +Specifies an implementation-defined native environment. This corresponds +to the value of the associated environment variables, +.IR LC_* +and +.IR LANG ; +see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale" +and +.IR "Chapter 8" ", " "Environment Variables". +.P +If the +.IR base +argument is not (\c +.BR locale_t )0 +and the +\fInewlocale\fR() +function call succeeds, the contents of +.IR base +are unspecified. Applications shall ensure that they stop using +.IR base +as a locale object before calling +\fInewlocale\fR(). +If the function call fails and the +.IR base +argument is not (\c +.BR locale_t )0, +the contents of +.IR base +shall remain valid and unchanged. +.P +The behavior is undefined if the +.IR base +argument is the special locale object LC_GLOBAL_LOCALE, or is not a +valid locale object handle and is not (\c +.BR locale_t )0. +.SH "RETURN VALUE" +Upon successful completion, the +\fInewlocale\fR() +function shall return a handle which the caller may use on subsequent +calls to +\fIduplocale\fR(), +\fIfreelocale\fR(), +and other functions taking a +.BR locale_t +argument. +.P +Upon failure, the +\fInewlocale\fR() +function shall return (\c +.BR locale_t )0 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fInewlocale\fR() +function shall fail if: +.TP +.BR ENOMEM +There is not enough memory available to create the locale object or +load the locale data. +.TP +.BR EINVAL +The +.IR category_mask +contains a bit that does not correspond to a valid category. +.TP +.BR ENOENT +For any of the categories in +.IR category_mask , +the locale data is not available. +.P +The +\fInewlocale\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR locale +argument is not a valid string pointer. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Constructing a Locale Object from Different Locales" +.P +The following example shows the construction of a locale where the +.IR LC_CTYPE +category data comes from a locale +.IR loc1 +and the +.IR LC_TIME +category data from a locale +.IR tok2 : +.sp +.RS 4 +.nf +\fB +#include +\&... +locale_t loc, new_loc; +.P +/* Get the "loc1" data. */ +.P +loc = newlocale (LC_CTYPE_MASK, "loc1", (locale_t)0); +if (loc == (locale_t) 0) + abort (); +.P +/* Get the "loc2" data. */ +.P +new_loc = newlocale (LC_TIME_MASK, "loc2", loc); +if (new_loc != (locale_t) 0) + /* We don t abort if this fails. In this case this + simply used to unchanged locale object. */ + loc = new_loc; +.P +\&... +.fi \fR +.P +.RE +.SS "Freeing up a Locale Object" +.P +The following example shows a code fragment to free a locale object +created by +\fInewlocale\fR(): +.sp +.RS 4 +.nf +\fB +#include +\&... +.P +/* Every locale object allocated with newlocale() should be + * freed using freelocale(): + */ +.P +locale_t loc; +.P +/* Get the locale. */ +.P +loc = newlocale (LC_CTYPE_MASK | LC_TIME_MASK, "locname", (locale_t)0); +.P +/* ... Use the locale object ... */ +\&... +.P +/* Free the locale object resources. */ +freelocale (loc); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Handles for locale objects created by the +\fInewlocale\fR() +function should either be released by a corresponding call to +\fIfreelocale\fR(), +or be used as a base locale to another +\fInewlocale\fR() +call. +.P +The special locale object LC_GLOBAL_LOCALE must not be passed for the +.IR base +argument, even when returned by the +\fIuselocale\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIduplocale\fR\^(\|)", +.IR "\fIfreelocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/nextafter.3p b/man-pages-posix-2013-a/man3p/nextafter.3p new file mode 100644 index 0000000..ce9758a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/nextafter.3p @@ -0,0 +1,196 @@ +'\" et +.TH NEXTAFTER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nextafter, +nextafterf, +nextafterl, +nexttoward, +nexttowardf, +nexttowardl +\(em next representable floating-point number +.SH SYNOPSIS +.LP +.nf +#include +.P +double nextafter(double \fIx\fP, double \fIy\fP); +float nextafterf(float \fIx\fP, float \fIy\fP); +long double nextafterl(long double \fIx\fP, long double \fIy\fP); +double nexttoward(double \fIx\fP, long double \fIy\fP); +float nexttowardf(float \fIx\fP, long double \fIy\fP); +long double nexttowardl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fInextafter\fR(), +\fInextafterf\fR(), +and +\fInextafterl\fR() +functions shall compute the next representable floating-point value +following +.IR x +in the direction of +.IR y . +Thus, if +.IR y +is less than +.IR x , +\fInextafter\fR() +shall return the largest representable floating-point number less than +.IR x . +The +\fInextafter\fR(), +\fInextafterf\fR(), +and +\fInextafterl\fR() +functions shall return +.IR y +if +.IR x +equals +.IR y . +.P +The +\fInexttoward\fR(), +\fInexttowardf\fR(), +and +\fInexttowardl\fR() +functions shall be equivalent to the corresponding +\fInextafter\fR() +functions, except that the second parameter shall have type +.BR "long double" +and the functions shall return +.IR y +converted to the type of the function if +.IR x +equals +.IR y . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the next +representable floating-point value following +.IR x +in the direction of +.IR y . +.P +If +.IR x ==\c +.IR y , +.IR y +(of the type +.IR x ) +shall be returned. +.P +If +.IR x +is finite and the correct function value would overflow, a range error +shall occur and \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (with +the same sign as +.IR x ) +shall be returned as appropriate for the return type of the function. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If +.IR x !=\c +.IR y +and the correct function value is subnormal, zero, or underflows, +a range error shall occur, and +.br +the correct function value (if representable) or +.br +0.0 shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The correct value overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The correct value is subnormal or underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.P +When +.IR +is included, note that the return type of +\fInextafter\fR() +depends on the generic typing deduced from both arguments, while the +return type of +\fInexttoward\fR() +depends only on the generic typing of the first argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/nftw.3p b/man-pages-posix-2013-a/man3p/nftw.3p new file mode 100644 index 0000000..c571f1e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/nftw.3p @@ -0,0 +1,358 @@ +'\" et +.TH NFTW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nftw +\(em walk a file tree +.SH SYNOPSIS +.LP +.nf +#include +.P +int nftw(const char *\fIpath\fP, int (*\fIfn\fP)(const char *, + const struct stat *, int, struct FTW *), int \fIfd_limit\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fInftw\fR() +function shall recursively descend the directory hierarchy rooted in +.IR path . +The +\fInftw\fR() +function has a similar effect to +\fIftw\fR() +except that it takes an additional argument +.IR flags , +which is a bitwise-inclusive OR of zero or more of the following flags: +.IP FTW_CHDIR 12 +If set, +\fInftw\fR() +shall change the current working directory to each directory as it +reports files in that directory. If clear, +\fInftw\fR() +shall not change the current working directory. +.IP FTW_DEPTH 12 +If set, +\fInftw\fR() +shall report all files in a directory before reporting the directory +itself. If clear, +\fInftw\fR() +shall report any directory before reporting the files in that directory. +.IP FTW_MOUNT 12 +If set, +\fInftw\fR() +shall only report files in the same file system as +.IR path . +If clear, +\fInftw\fR() +shall report all files encountered during the walk. +.IP FTW_PHYS 12 +If set, +\fInftw\fR() +shall perform a physical walk and shall not follow symbolic links. +.P +If FTW_PHYS is clear and FTW_DEPTH is set, +\fInftw\fR() +shall follow links instead of reporting them, but shall not report any +directory that would be a descendant of itself. If FTW_PHYS is clear +and FTW_DEPTH is clear, +\fInftw\fR() +shall follow links instead of reporting them, but shall not report the +contents of any directory that would be a descendant of itself. +.P +At each file it encounters, +\fInftw\fR() +shall call the user-supplied function +.IR fn +with four arguments: +.IP " *" 4 +The first argument is the pathname of the object. +.IP " *" 4 +The second argument is a pointer to the +.BR stat +buffer containing information on the object, filled in as if +\fIfstatat\fR(), +\fIstat\fR(), +or +\fIlstat\fR() +had been called to retrieve the information. +.IP " *" 4 +The third argument is an integer giving additional information. Its +value is one of the following: +.RS 4 +.IP FTW_D 10 +The object is a directory. +.IP FTW_DNR 10 +The object is a directory that cannot be read. The +.IR fn +function shall not be called for any of its descendants. +.IP FTW_DP 10 +The object is a directory and subdirectories have been visited. (This +condition shall only occur if the FTW_DEPTH flag is included in +.IR flags .) +.IP FTW_F 10 +The object is a non-directory file. +.IP FTW_NS 10 +The +\fIstat\fR() +function failed on the object because of lack of appropriate +permission. The +.BR stat +buffer passed to +.IR fn +is undefined. Failure of +\fIstat\fR() +for any other reason is considered an error and +\fInftw\fR() +shall return \(mi1. +.IP FTW_SL 10 +The object is a symbolic link. (This condition shall only occur if the +FTW_PHYS flag is included in +.IR flags .) +.IP FTW_SLN 10 +The object is a symbolic link that does not name an existing file. +(This condition shall only occur if the FTW_PHYS flag is not included in +.IR flags .) +.RE +.IP " *" 4 +The fourth argument is a pointer to an +.BR FTW +structure. +The value of +.BR base +is the offset of the object's filename in the pathname passed as the +first argument to +.IR fn . +The value of +.BR level +indicates depth relative to the root of the walk, where the root level +is 0. +.P +The results are unspecified if the application-supplied +.IR fn +function does not preserve the current working directory. +.P +The argument +.IR fd_limit +sets the maximum number of file descriptors that shall be used by +\fInftw\fR() +while traversing the file tree. At most one file descriptor shall be +used for each directory level. +.P +The +\fInftw\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fInftw\fR() +function shall continue until the first of the following conditions +occurs: +.IP " *" 4 +An invocation of +.IR fn +shall return a non-zero value, in which case +\fInftw\fR() +shall return that value. +.IP " *" 4 +The +\fInftw\fR() +function detects an error other than +.BR [EACCES] +(see FTW_DNR and FTW_NS above), +in which case +\fInftw\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.IP " *" 4 +The tree is exhausted, in which case +\fInftw\fR() +shall return 0. +.SH ERRORS +The +\fInftw\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for any component of +.IR path +or read permission is denied for +.IR path , +or +.IR fn +returns \(mi1 and does not reset +.IR errno . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of +.IR path +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EOVERFLOW +A field in the +.BR stat +structure cannot be represented correctly in the current programming +environment for one or more files found in the file hierarchy. +.P +The +\fInftw\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.P +In addition, +.IR errno +may be set if the function pointed to by +.IR fn +causes +.IR errno +to be set. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following program traverses the directory tree under the path named +in its first command-line argument, or under the current directory if +no argument is supplied. It displays various information about each +file. The second command-line argument can be used to specify characters +that control the value assigned to the +.IR flags +argument when calling +\fInftw\fR(). +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +.P +static int +display_info(const char *fpath, const struct stat *sb, + int tflag, struct FTW *ftwbuf) +{ + printf("%-3s %2d %7jd %-40s %d %s\en", + (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : + (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? + (S_ISBLK(sb->st_mode) ? "f b" : + S_ISCHR(sb->st_mode) ? "f c" : + S_ISFIFO(sb->st_mode) ? "f p" : + S_ISREG(sb->st_mode) ? "f r" : + S_ISSOCK(sb->st_mode) ? "f s" : "f ?") : + (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : + (tflag == FTW_SLN) ? "sln" : "?", + ftwbuf->level, (intmax_t) sb->st_size, + fpath, ftwbuf->base, fpath + ftwbuf->base); + return 0; /* To tell nftw() to continue */ +} +.P +int +main(int argc, char *argv[]) +{ + int flags = 0; +.P + if (argc > 2 && strchr(argv[2], 'd') != NULL) + flags |= FTW_DEPTH; + if (argc > 2 && strchr(argv[2], 'p') != NULL) + flags |= FTW_PHYS; +.P + if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == -1) + { + perror("nftw"); + exit(EXIT_FAILURE); + } +.P + exit(EXIT_SUCCESS); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fInftw\fR() +function may allocate dynamic storage during its operation. If +\fInftw\fR() +is forcibly terminated, such as by +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +being executed by the function pointed to by +.IR fn +or an interrupt routine, +\fInftw\fR() +does not have a chance to free that storage, so it remains permanently +allocated. A safe way to handle interrupts is to store the fact that an +interrupt has occurred, and arrange to have the function pointed to by +.IR fn +return a non-zero value at its next invocation. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/nice.3p b/man-pages-posix-2013-a/man3p/nice.3p new file mode 100644 index 0000000..76e04c6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/nice.3p @@ -0,0 +1,122 @@ +'\" et +.TH NICE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nice +\(em change the nice value of a process +.SH SYNOPSIS +.LP +.nf +#include +.P +int nice(int \fIincr\fP); +.fi +.SH DESCRIPTION +The +\fInice\fR() +function shall add the value of +.IR incr +to the nice value of the calling process. A nice value of a process is +a non-negative number for which a more positive value shall result in +less favorable scheduling. +.P +A maximum nice value of 2*{NZERO}\(mi1 and a minimum nice value of 0 +shall be imposed by the system. Requests for values above or below +these limits shall result in the nice value being set to the +corresponding limit. Only a process with appropriate privileges can +lower the nice value. +.P +Calling the +\fInice\fR() +function has no effect on the priority of processes or threads with +policy SCHED_FIFO or SCHED_RR. +The effect on processes or threads with other scheduling policies is +implementation-defined. +.P +The nice value set with +\fInice\fR() +shall be applied to the process. If the process is multi-threaded, +the nice value shall affect all system scope threads in the process. +.P +As \(mi1 is a permissible return value in a successful situation, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fInice\fR(), +and if it returns \(mi1, check to see whether +.IR errno +is non-zero. +.SH "RETURN VALUE" +Upon successful completion, +\fInice\fR() +shall return the new nice value \(mi{NZERO}. +Otherwise, \(mi1 shall be returned, the nice value of the process +shall not be changed, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fInice\fR() +function shall fail if: +.TP +.BR EPERM +The +.IR incr +argument is negative and the calling process does not have appropriate +privileges. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Nice Value" +.P +The following example adds the value of the +.IR incr +argument, \(mi20, to the nice value of the calling process. +.sp +.RS 4 +.nf +\fB +#include +\&... +int incr = -20; +int ret; +.P +ret = nice(incr); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetpriority\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/nl_langinfo.3p b/man-pages-posix-2013-a/man3p/nl_langinfo.3p new file mode 100644 index 0000000..f98b5c6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/nl_langinfo.3p @@ -0,0 +1,205 @@ +'\" et +.TH NL_LANGINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nl_langinfo, +nl_langinfo_l +\(em language information +.SH SYNOPSIS +.LP +.nf +#include +.P +char *nl_langinfo(nl_item \fIitem\fP); +char *nl_langinfo_l(nl_item \fIitem\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +The +\fInl_langinfo\fR() +and +\fInl_langinfo_l\fR() +functions shall return a pointer to a string containing information +relevant to the particular language or cultural area defined in the +current locale, or in the locale represented by +.IR locale , +respectively (see +.IR ). +The manifest constant names and values of +.IR item +are defined in +.IR . +For example: +.sp +.RS 4 +.nf +\fB +nl_langinfo(ABDAY_1) +.fi \fR +.P +.RE +.P +would return a pointer to the string +.BR \(dqDom\(dq +if the identified language was Portuguese, and +.BR \(dqSun\(dq +if the identified language was English. +.sp +.RS 4 +.nf +\fB +nl_langinfo_l(ABDAY_1, loc) +.fi \fR +.P +.RE +.P +would return a pointer to the string +.BR \(dqDom\(dq +if the identified language of the locale represented by +.IR loc +was Portuguese, and +.BR \(dqSun\(dq +if the identified language of the locale represented by +.IR loc +was English. +.P +The +\fInl_langinfo\fR() +function need not be thread-safe. +.P +The behavior is undefined if the +.IR locale +argument to +\fInl_langinfo_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +In a locale where +.IR langinfo +data is not defined, these functions shall return a pointer to the +corresponding string in the POSIX locale. In all locales, these functions +shall return a pointer to an empty string if +.IR item +contains an invalid setting. +.P +The application shall not modify the string returned. The pointer +returned by +\fInl_langinfo\fR() +might be invalidated or the string content might be overwritten by a +subsequent call to +\fInl_langinfo\fR() +in any thread or to +\fInl_langinfo_l\fR() +in the same thread or the initial thread, by subsequent calls to +\fIsetlocale\fR() +with a category corresponding to the category of +.IR item +(see +.IR ) +or the category LC_ALL, or by subsequent calls to +\fIuselocale\fR() +which change the category corresponding to the category of +.IR item . +The pointer returned by +\fInl_langinfo_l\fR() +might be invalidated or the string content might be overwritten by a +subsequent call to +\fInl_langinfo_l\fR() +in the same thread or to +\fInl_langinfo\fR() +in any thread, or by subsequent calls to +\fIfreelocale\fR() +or +\fInewlocale\fR() +which free or modify the locale object that was passed to +\fInl_langinfo_l\fR(). +.SH "ERRORS" +No errors are defined. +.br +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting Date and Time Formatting Information" +.P +The following example returns a pointer to a string containing date and +time formatting information, as defined in the +.IR LC_TIME +category of the current locale. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The array pointed to by the return value should not be modified by the +program, but may be modified by further calls to these functions. +.SH RATIONALE +The possible interactions between internal data used by +\fInl_langinfo\fR() +and +\fInl_langinfo_l\fR() +are complicated by the fact that +\fInl_langinfo_l\fR() +must be thread-safe but +\fInl_langinfo\fR() +need not be. The various implementation choices are: +.IP " 1." 4 +\fInl_langinfo_l\fR() +and +\fInl_langinfo\fR() +use separate buffers, or at least one of them does not use an internal +string buffer. In this case there are no interactions. +.IP " 2." 4 +\fInl_langinfo_l\fR() +and +\fInl_langinfo\fR() +share an internal per-thread buffer. There can be interactions, but +only in the same thread. +.IP " 3." 4 +\fInl_langinfo_l\fR() +uses an internal per-thread buffer, and +\fInl_langinfo\fR() +uses (in all threads) the same buffer that +\fInl_langinfo_l\fR() +uses in the initial thread. There can be interactions, but only when +\fInl_langinfo_l\fR() +is called in the initial thread. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/nrand48.3p b/man-pages-posix-2013-a/man3p/nrand48.3p new file mode 100644 index 0000000..62ad737 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/nrand48.3p @@ -0,0 +1,38 @@ +'\" et +.TH NRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nrand48 +\(em generate uniformly distributed pseudo-random non-negative long integers +.SH SYNOPSIS +.LP +.nf +#include +.P +long nrand48(unsigned short \fIxsubi\fP[3]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ntohl.3p b/man-pages-posix-2013-a/man3p/ntohl.3p new file mode 100644 index 0000000..c7ca169 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ntohl.3p @@ -0,0 +1,40 @@ +'\" et +.TH NTOHL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ntohl, +ntohs +\(em convert values between host and network byte order +.SH SYNOPSIS +.LP +.nf +#include +.P +uint32_t ntohl(uint32_t \fInetlong\fP); +uint16_t ntohs(uint16_t \fInetshort\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIhtonl\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/open.3p b/man-pages-posix-2013-a/man3p/open.3p new file mode 100644 index 0000000..f56a01b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/open.3p @@ -0,0 +1,779 @@ +'\" et +.TH OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +open, openat +\(em open file relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int open(const char *\fIpath\fP, int \fIoflag\fP, ...); +int openat(int \fIfd\fP, const char *\fIpath\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +The +\fIopen\fR() +function shall establish the connection between a file and a file +descriptor. It shall create an open file description that refers to a +file and a file descriptor that refers to that open file description. +The file descriptor is used by other I/O functions to refer to that +file. The +.IR path +argument points to a pathname naming the file. +.P +The +\fIopen\fR() +function shall return a file descriptor for the named file that is the +lowest file descriptor not currently open for that process. The open +file description is new, and therefore the file descriptor shall not +share it with any other process in the +system. The FD_CLOEXEC file descriptor flag associated with the new +file descriptor shall be cleared unless the O_CLOEXEC flag is set in +.IR oflag . +.P +The file offset used to mark the current position within the file shall +be set to the beginning of the file. +.P +The file status flags and file access modes of the open file +description shall be set according to the value of +.IR oflag . +.P +Values for +.IR oflag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR . +Applications shall specify exactly one of the first five values +(file access modes) below in the value of +.IR oflag : +.IP O_EXEC 14 +Open for execute only (non-directory files). The result is unspecified +if this flag is applied to a directory. +.IP O_RDONLY 14 +Open for reading only. +.IP O_RDWR 14 +Open for reading and writing. The result is undefined if this flag is +applied to a FIFO. +.IP O_SEARCH 14 +Open directory for search only. The result is unspecified if this flag +is applied to a non-directory file. +.IP O_WRONLY 14 +Open for writing only. +.P +Any combination of the following may be used: +.IP O_APPEND 14 +If set, the file offset shall be set to the end of the file prior +to each write. +.IP O_CLOEXEC 14 +If set, the FD_CLOEXEC flag for the new file descriptor shall be set. +.IP O_CREAT 14 +If the file exists, this flag has no effect except as noted under O_EXCL +below. Otherwise, the file shall be created; the user ID of the file shall +be set to the effective user ID of the process; the group ID of the file +shall be set to the group ID of the file's parent directory or to the +effective group ID of the process; and the access permission bits (see +.IR ) +of the file mode shall be set to the value of the argument following the +.IR oflag +argument taken as type +.BR mode_t +modified as follows: a bitwise AND is performed on the file-mode bits +and the corresponding bits in the complement of the process' file mode +creation mask. Thus, all bits in the file mode whose corresponding bit +in the file mode creation mask is set are cleared. When bits other than +the file permission bits are set, the effect is unspecified. The argument +following the +.IR oflag +argument does not affect whether the file is open for reading, writing, +or for both. Implementations shall provide a way to initialize the file's +group ID to the group ID of the parent directory. Implementations may, +but need not, provide an implementation-defined way to initialize the +file's group ID to the effective group ID of the calling process. +.IP O_DIRECTORY 14 +If +.IR path +resolves to a non-directory file, fail and set +.IR errno +to +.BR [ENOTDIR] . +.IP O_DSYNC 14 +Write I/O operations on the file descriptor shall complete as defined +by synchronized I/O data integrity completion. +.IP O_EXCL 14 +If O_CREAT and O_EXCL are set, +\fIopen\fR() +shall fail if the file exists. The check for the existence of the file +and the creation of the file if it does not exist shall be atomic with +respect to other threads executing +\fIopen\fR() +naming the same filename in the same directory with O_EXCL and O_CREAT +set. If O_EXCL and O_CREAT are set, and +.IR path +names a symbolic link, +\fIopen\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] , +regardless of the contents of the symbolic link. If O_EXCL is set and +O_CREAT is not set, the result is undefined. +.IP O_NOCTTY 14 +If set and +.IR path +identifies a terminal device, +\fIopen\fR() +shall not cause the terminal device to become the controlling terminal +for the process. If +.IR path +does not identify a terminal device, O_NOCTTY shall be ignored. +.IP O_NOFOLLOW 14 +If +.IR path +names a symbolic link, fail and set +.IR errno +to +.BR [ELOOP] . +.IP O_NONBLOCK 14 +When opening a FIFO with O_RDONLY or O_WRONLY set: +.RS 14 +.IP " *" 4 +If O_NONBLOCK is set, an +\fIopen\fR() +for reading-only shall return without delay. An +\fIopen\fR() +for writing-only shall return an error if no process currently has the +file open for reading. +.IP " *" 4 +If O_NONBLOCK is clear, an +\fIopen\fR() +for reading-only shall block the calling thread until a thread opens +the file for writing. An +\fIopen\fR() +for writing-only shall block the calling thread until a thread opens +the file for reading. +.P +When opening a block special or character special file that supports +non-blocking opens: +.IP " *" 4 +If O_NONBLOCK is set, the +\fIopen\fR() +function shall return without blocking for the device to be ready or +available. Subsequent behavior of the device is device-specific. +.IP " *" 4 +If O_NONBLOCK is clear, the +\fIopen\fR() +function shall block the calling thread until the device is ready or +available before returning. +.P +Otherwise, the O_NONBLOCK flag shall not cause an error, but it is +unspecified whether the file status flags will include the O_NONBLOCK +flag. +.RE +.IP O_RSYNC 14 +Read I/O operations on the file descriptor shall complete at the same +level of integrity as specified by the O_DSYNC and +O_SYNC flags. If both O_DSYNC and O_RSYNC are set in +.IR oflag , +all I/O operations on the file descriptor shall complete as defined by +synchronized I/O data integrity completion. If both O_SYNC and O_RSYNC +are set in flags, all I/O operations on the file descriptor shall +complete as defined by synchronized I/O file integrity completion. +.IP O_SYNC 14 +Write I/O operations on the file descriptor shall complete as defined +by synchronized I/O file integrity completion. +.RS 14 +.P +The O_SYNC flag shall be supported for regular files, even if the +Synchronized Input and Output option is not supported. +.RE +.IP O_TRUNC 14 +If the file exists and is a regular file, and the file is successfully +opened O_RDWR or O_WRONLY, its length shall be truncated to 0, and +the mode and owner shall be unchanged. It shall have no effect on FIFO +special files or terminal device files. Its effect on other file types +is implementation-defined. The result of using O_TRUNC without either +O_RDWR or O_WRONLY is undefined. +.IP O_TTY_INIT 14 +If +.IR path +identifies a terminal device other than a pseudo-terminal, the device +is not already open in any process, and either O_TTY_INIT is set in +.IR oflag +or O_TTY_INIT has the value zero, +\fIopen\fR() +shall set any non-standard +.BR termios +structure terminal parameters to a state that provides conforming +behavior; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 11.2" ", " "Parameters that Can be Set". +It is unspecified whether O_TTY_INIT has any effect if the device is +already open in any process. If +.IR path +identifies the slave side of a pseudo-terminal that is not already open +in any process, +\fIopen\fR() +shall set any non-standard +.BR termios +structure terminal parameters to a state that provides conforming +behavior, regardless of whether O_TTY_INIT is set. If +.IR path +does not identify a terminal device, O_TTY_INIT shall be ignored. +.P +If O_CREAT is set and the file did not previously exist, upon successful +completion, +\fIopen\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the file and the last data +modification and last file status change timestamps of the parent +directory. +.P +If O_TRUNC is set and the file did previously exist, upon successful +completion, +\fIopen\fR() +shall mark for update the last data modification and last file status +change timestamps of the file. +.P +If both the O_SYNC and O_DSYNC flags are set, the effect is as if only +the O_SYNC flag was set. +.P +If +.IR path +refers to a STREAMS file, +.IR oflag +may be constructed from O_NONBLOCK OR'ed with either O_RDONLY, O_WRONLY, +or O_RDWR. Other flag values are not applicable to STREAMS devices and +shall have no effect on them. The value O_NONBLOCK affects the operation +of STREAMS drivers and certain functions applied to file descriptors +associated with STREAMS files. For STREAMS drivers, the implementation +of O_NONBLOCK is device-specific. +.P +The application shall ensure that it specifies the O_TTY_INIT flag on the +first open of a terminal device since system boot or since the device +was closed by the process that last had it open. The application need +not specify the O_TTY_INIT flag when opening pseudo-terminals. +If +.IR path +names the master side of a pseudo-terminal device, then it is unspecified +whether +\fIopen\fR() +locks the slave side so that it cannot be opened. Conforming applications +shall call +\fIunlockpt\fR() +before opening the slave side. +.P +The largest value that can be represented correctly in an object of type +.BR off_t +shall be established as the offset maximum in the open file description. +.P +The +\fIopenat\fR() +function shall be equivalent to the +\fIopen\fR() +function except in the case where +.IR path +specifies a relative path. In this case the file to be opened is +determined relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +The +.IR oflag +parameter and the optional fourth parameter correspond exactly to the +parameters of +\fIopen\fR(). +.P +If +\fIopenat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIopen\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall open the file and +return a non-negative integer representing the lowest numbered unused +file descriptor. Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, no files shall be created +or modified. +.br +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or the +file exists and the permissions specified by +.IR oflag +are denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created, or O_TRUNC is +specified and write permission is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set, and the named file exists. +.TP +.BR EINTR +A signal was caught during +\fIopen\fR(). +.TP +.BR EINVAL +The implementation does not support synchronized I/O for this file. +.TP +.BR EIO +The +.IR path +argument names a STREAMS file and a hangup or error occurred during the +\fIopen\fR(). +.TP +.BR EISDIR +The named file is a directory and +.IR oflag +includes O_WRONLY or O_RDWR. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument, or O_NOFOLLOW was specified and the +.IR path +argument names a symbolic link. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and a component of +.IR path +does not name an existing file, or O_CREAT is set and a component of +the path prefix of +.IR path +does not name an existing file, or +.IR path +points to an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +O_CREAT is set, and the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR path +names an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSR +The +.IR path +argument names a STREAMS-based file and the system is unable to +allocate a STREAM. +.TP +.BR ENOSPC +The directory or file system that would contain the new file cannot be +expanded, the file does not exist, and O_CREAT is specified. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory; or O_CREAT and O_EXCL +are not specified, the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters, and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory; or O_DIRECTORY +was specified and the +.IR path +argument resolves to a non-directory file. +.TP +.BR ENXIO +O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is set, and no +process has the file open for reading. +.TP +.BR ENXIO +The named file is a character special or block special file, and the +device associated with this special file does not exist. +.TP +.BR EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type +.BR off_t . +.TP +.BR EROFS +The named file resides on a read-only file system and either O_WRONLY, +O_RDWR, O_CREAT (if the file does not exist), or O_TRUNC is set in the +.IR oflag +argument. +.P +The +\fIopenat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for +reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EAGAIN +The +.IR path +argument names the slave side of a pseudo-terminal device that is locked. +.TP +.BR EINVAL +The value of the +.IR oflag +argument is not valid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENOMEM +The +.IR path +argument names a STREAMS file and the system is unable to allocate +resources. +.TP +.BR ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and +.IR oflag +is O_WRONLY or O_RDWR. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Opening a File for Writing by the Owner" +.P +The following example opens the file +.BR /tmp/file , +either by creating it (if it does not already exist), or by truncating +its length to 0 (if it does exist). In the former case, if the call +creates a new file, the access permission bits in the file mode of the +file are set to permit reading and writing by the owner, and to permit +reading only by group members and others. +.P +If the call to +\fIopen\fR() +is successful, the file is opened for writing. +.sp +.RS 4 +.nf +\fB +#include +\&... +int fd; +mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; +char *pathname = "/tmp/file"; +\&... +fd = open(pathname, O_WRONLY | O_CREAT | O_TRUNC, mode); +\&... +.fi \fR +.P +.RE +.SS "Opening a File Using an Existence Check" +.P +The following example uses the +\fIopen\fR() +function to try to create the +.BR LOCKFILE +file and open it for writing. Since the +\fIopen\fR() +function specifies the O_EXCL flag, the call fails if the file already +exists. In that case, the program assumes that someone else is updating +the password file and exits. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; /* Integer for file descriptor returned by open() call. */ +\&... +if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) +{ + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en"); + exit(1); +} +\&... +.fi \fR +.P +.RE +.SS "Opening a File for Writing" +.P +The following example opens a file for writing, creating the file if it +does not already exist. If the file does exist, the system truncates +the file to zero bytes. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; +char pathname[PATH_MAX+1]; +\&... +if ((pfd = open(pathname, O_WRONLY | O_CREAT | O_TRUNC, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) +{ + perror("Cannot open output file\en"); exit(1); +} +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +POSIX.1\(hy2008 does not require that terminal parameters be automatically set to +any state on first open, nor that they be reset after the last close. It +is possible for a non-conforming application to leave a terminal device +in a state where the next process to use that device finds it in a +non-conforming state, but has no way of determining this. To ensure +that the device is set to a conforming initial state, applications which +perform a first open of a terminal (other than a pseudo-terminal) should +do so using the O_TTY_INIT flag to set the parameters associated with +the terminal to a conforming state. +.P +Except as specified in this volume of POSIX.1\(hy2008, the flags allowed in +.IR oflag +are not mutually-exclusive and any number of them may be used +simultaneously. Not all combinations of flags make sense. For example, +using O_SEARCH | O_CREAT will successfully open a pre-existing directory +for searching, but if there is no existing file by that name, then +it is unspecified whether a regular file will be created. Likewise, +if a non-directory file descriptor is successfully returned, it is +unspecified whether that descriptor will have execute permissions as if +by O_EXEC (note that it is unspecified whether O_EXEC and O_SEARCH have +the same value). +.SH RATIONALE +Some implementations permit opening FIFOs with O_RDWR. Since FIFOs could +be implemented in other ways, and since two file descriptors can be used +to the same effect, this possibility is left as undefined. +.P +See +.IR "\fIgetgroups\fR\^(\|)" +about the group of a newly created file. +.P +The use of +\fIopen\fR() +to create a regular file is preferable to the use of +\fIcreat\fR(), +because the latter is redundant and included only for historical +reasons. +.P +The use of the O_TRUNC flag on FIFOs and directories (pipes cannot be +\fIopen\fR()-ed) +must be permissible without unexpected side-effects (for example, +\fIcreat\fR() +on a FIFO must not remove data). Since terminal special files might have +type-ahead data stored in the buffer, O_TRUNC should not affect their +content, particularly if a program that normally opens a regular file +should open the current controlling terminal instead. Other file types, +particularly implementation-defined ones, are left implementation-defined. +.P +POSIX.1\(hy2008 permits +.BR [EACCES] +to be returned for conditions other than those explicitly listed. +.P +The O_NOCTTY flag was added to allow applications to avoid unintentionally +acquiring a controlling terminal as a side-effect of opening a terminal +file. This volume of POSIX.1\(hy2008 does not specify how a controlling terminal is acquired, +but it allows an implementation to provide this on +\fIopen\fR() +if the O_NOCTTY flag is not set and other conditions specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface" +are met. +.P +In historical implementations the value of O_RDONLY is zero. Because of +that, it is not possible to detect the presence of O_RDONLY and another +option. Future implementations should encode O_RDONLY and O_WRONLY as +bit flags so that: +.sp +.RS 4 +.nf +\fB +O_RDONLY | O_WRONLY == O_RDWR +.fi \fR +.P +.RE +.P +O_EXEC and O_SEARCH are specified as two of the five file access modes. +Since O_EXEC does not apply to directories, and O_SEARCH only applies +to directories, their values need not be distinct. Since O_RDONLY +has historically had the value zero, implementations are not able to +distinguish between O_SEARCH and O_SEARCH | O_RDONLY, and similarly +for O_EXEC. +.P +In general, the +\fIopen\fR() +function follows the symbolic link if +.IR path +names a symbolic link. However, the +\fIopen\fR() +function, when called with O_CREAT and O_EXCL, is required to fail with +.BR [EEXIST] +if +.IR path +names an existing symbolic link, even if the symbolic link refers +to a nonexistent file. This behavior is required so that privileged +applications can create a new file in a known location without the +possibility that a symbolic link might cause the file to be created in +a different location. +.P +For example, a privileged application that must create a file with a +predictable name in a user-writable directory, such as the user's home +directory, could be compromised if the user creates a symbolic link +with that name that refers to a nonexistent file in a system +directory. If the user can influence the contents of a file, the user +could compromise the system by creating a new system configuration or +spool file that would then be interpreted by the system. The test for a +symbolic link which refers to a nonexisting file must be atomic with +the creation of a new file. +.P +In addition, the +\fIopen\fR() +function refuses to open non-directories if the O_DIRECTORY flag is +set. This avoids race conditions whereby a user might compromise the +system by substituting a hard link to a sensitive file (e.g., a device +or a FIFO) while a privileged application is running, where opening a +file even for read access might have undesirable side-effects. +.P +In addition, the +\fIopen\fR() +function does not follow symbolic links if the O_NOFOLLOW flag is set. +This avoids race conditions whereby a user might compromise the system +by substituting a symbolic link to a sensitive file (e.g., a device) +while a privileged application is running, where opening a file even +for read access might have undesirable side-effects. +.P +The POSIX.1\(hy1990 standard required that the group ID of a newly created file be set to +the group ID of its parent directory or to the effective group ID of +the creating process. FIPS 151\(hy2 required that implementations provide a way +to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the file is created, or determine under what +conditions the implementation will set the desired group ID. +.P +The purpose of the +\fIopenat\fR() +function is to enable opening files in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIopen\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIopenat\fR() +function it can be guaranteed that the opened file is located relative +to the desired directory. Some implementations use the +\fIopenat\fR() +function for other purposes as well. In some cases, if the +.IR oflag +parameter has the O_XATTR bit set, the returned file descriptor provides +access to extended attributes. This functionality is not standardized +here. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIumask\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/open_memstream.3p b/man-pages-posix-2013-a/man3p/open_memstream.3p new file mode 100644 index 0000000..7e1a648 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/open_memstream.3p @@ -0,0 +1,189 @@ +'\" et +.TH OPEN_MEMSTREAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +open_memstream, open_wmemstream +\(em open a dynamic memory buffer stream +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *open_memstream(char **\fIbufp\fP, size_t *\fIsizep\fP); +.P +#include +.P +FILE *open_wmemstream(wchar_t **\fIbufp\fP, size_t *\fIsizep\fP); +.fi +.SH DESCRIPTION +The +\fIopen_memstream\fR() +and +\fIopen_wmemstream\fR() +functions shall create an I/O stream associated with a dynamically +allocated memory buffer. The stream shall be opened for writing and +shall be seekable. +.P +The stream associated with a call to +\fIopen_memstream\fR() +shall be byte-oriented. +.P +The stream associated with a call to +\fIopen_wmemstream\fR() +shall be wide-oriented. +.P +The stream shall maintain a current position in the allocated buffer +and a current buffer length. The position shall be initially set to +zero (the start of the buffer). Each write to the stream shall start at +the current position and move this position by the number of +successfully written bytes for +\fIopen_memstream\fR() +or the number of successfully written wide characters for +\fIopen_wmemstream\fR(). +The length shall be initially set to zero. If a write moves the +position to a value larger than the current length, the current length +shall be set to this position. In this case a null character for +\fIopen_memstream\fR() +or a null wide character for +\fIopen_wmemstream\fR() +shall be appended to the current buffer. For both functions the +terminating null is not included in the calculation of the buffer +length. +.P +After a successful +\fIfflush\fR() +or +\fIfclose\fR(), +the pointer referenced by +.IR bufp +shall contain the address of the buffer, and the variable pointed to by +.IR sizep +shall contain the smaller of the current buffer length and the +number of bytes for +\fIopen_memstream\fR(), +or the number of wide characters for +\fIopen_wmemstream\fR(), +between the beginning of the buffer and the current file position indicator. +.P +After a successful +\fIfflush\fR() +the pointer referenced by +.IR bufp +and the variable referenced by +.IR sizep +remain valid only until the next write operation on the stream or a +call to +\fIfclose\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a pointer to +the object controlling the stream. Otherwise, a null pointer shall be +returned, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +.IR bufp +or +.IR sizep +are NULL. +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR ENOMEM +Memory for the stream or the buffer could not be allocated. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int +main (void) +{ + FILE *stream; + char *buf; + size_t len; + off_t eob; +.P + stream = open_memstream (&buf, &len); + if (stream == NULL) + /* handle error */ ; + fprintf (stream, "hello my world"); + fflush (stream); + printf ("buf=%s, len=%zu\en", buf, len); + eob = ftello(stream); + fseeko (stream, 0, SEEK_SET); + fprintf (stream, "good-bye"); + fseeko (stream, eob, SEEK_SET); + fclose (stream); + printf ("buf=%s, len=%zu\en", buf, len); + free (buf); + return 0; +} +.fi \fR +.P +.RE +.P +This program produces the following output: +.sp +.RS 4 +.nf +\fB +buf=hello my world, len=14 +buf=good-bye world, len=14 +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The buffer created by these functions should be freed by the +application after closing the stream, by means of a call to +\fIfree\fR(). +.SH RATIONALE +These functions are similar to +\fIfmemopen\fR() +except that the memory is always allocated dynamically by the function, +and the stream is opened only for output. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfflush\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/openat.3p b/man-pages-posix-2013-a/man3p/openat.3p new file mode 100644 index 0000000..a2c718d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/openat.3p @@ -0,0 +1,38 @@ +'\" et +.TH OPENAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +openat +\(em open file relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int openat(int \fIfd\fP, const char *\fIpath\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIopen\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/opendir.3p b/man-pages-posix-2013-a/man3p/opendir.3p new file mode 100644 index 0000000..1eaac54 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/opendir.3p @@ -0,0 +1,38 @@ +'\" et +.TH OPENDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +opendir +\(em open directory associated with file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +DIR *opendir(const char *\fIdirname\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfdopendir\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/openlog.3p b/man-pages-posix-2013-a/man3p/openlog.3p new file mode 100644 index 0000000..7a14430 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/openlog.3p @@ -0,0 +1,38 @@ +'\" et +.TH OPENLOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +openlog +\(em open a connection to the logging facility +.SH SYNOPSIS +.LP +.nf +#include +.P +void openlog(const char *\fIident\fP, int \fIlogopt\fP, int \fIfacility\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcloselog\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/optarg.3p b/man-pages-posix-2013-a/man3p/optarg.3p new file mode 100644 index 0000000..ba63b21 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/optarg.3p @@ -0,0 +1,42 @@ +'\" et +.TH OPTARG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +optarg, +opterr, +optind, +optopt +\(em options parsing variables +.SH SYNOPSIS +.LP +.nf +#include +.P +extern char *optarg; +extern int opterr, optind, optopt; +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetopt\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pathconf.3p b/man-pages-posix-2013-a/man3p/pathconf.3p new file mode 100644 index 0000000..ab1759c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pathconf.3p @@ -0,0 +1,38 @@ +'\" et +.TH PATHCONF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pathconf +\(em get configurable pathname variables +.SH SYNOPSIS +.LP +.nf +#include +.P +long pathconf(const char *\fIpath\fP, int \fIname\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfpathconf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pause.3p b/man-pages-posix-2013-a/man3p/pause.3p new file mode 100644 index 0000000..cbbeb51 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pause.3p @@ -0,0 +1,91 @@ +'\" et +.TH PAUSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pause +\(em suspend the thread until a signal is received +.SH SYNOPSIS +.LP +.nf +#include +.P +int pause(void); +.fi +.SH DESCRIPTION +The +\fIpause\fR() +function shall suspend the calling thread until delivery of a signal +whose action is either to execute a signal-catching function or to +terminate the process. +.P +If the action is to terminate the process, +\fIpause\fR() +shall not return. +.P +If the action is to execute a signal-catching function, +\fIpause\fR() +shall return after the signal-catching function returns. +.SH "RETURN VALUE" +Since +\fIpause\fR() +suspends thread execution indefinitely unless interrupted by a signal, +there is no successful completion return value. A value of \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIpause\fR() +function shall fail if: +.TP +.BR EINTR +A signal is caught by the calling process and control is returned from +the signal-catching function. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Many common uses of +\fIpause\fR() +have timing windows. The scenario involves checking a condition +related to a signal and, if the signal has not occurred, calling +\fIpause\fR(). +When the signal occurs between the check and the call to +\fIpause\fR(), +the process often blocks indefinitely. The +\fIsigprocmask\fR() +and +\fIsigsuspend\fR() +functions can be used to avoid this type of problem. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pclose.3p b/man-pages-posix-2013-a/man3p/pclose.3p new file mode 100644 index 0000000..b764d57 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pclose.3p @@ -0,0 +1,221 @@ +'\" et +.TH PCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pclose +\(em close a pipe stream to or from a process +.SH SYNOPSIS +.LP +.nf +#include +.P +int pclose(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The +\fIpclose\fR() +function shall close a stream that was opened by +\fIpopen\fR(), +wait for the command to terminate, and return the termination status +of the process that was running the command language interpreter. +However, if a call caused the termination status to be unavailable to +\fIpclose\fR(), +then +\fIpclose\fR() +shall return \(mi1 with +.IR errno +set to +.BR [ECHILD] +to report this situation. This can happen if the application calls one +of the following functions: +.IP " *" 4 +\fIwait\fR() +.IP " *" 4 +\fIwaitpid\fR() +with a +.IR pid +argument less than or equal to 0 or equal to the process ID of the +command line interpreter +.IP " *" 4 +Any other function not defined in this volume of POSIX.1\(hy2008 that could do one of the above +.P +In any case, +\fIpclose\fR() +shall not return before the child process created by +\fIpopen\fR() +has terminated. +.P +If the command language interpreter cannot be executed, the child +termination status returned by +\fIpclose\fR() +shall be as if the command language interpreter terminated using +.IR exit (127) +or +.IR _exit (127). +.P +The +\fIpclose\fR() +function shall not affect the termination status of any child of the +calling process other than the one created by +\fIpopen\fR() +for the associated stream. +.P +If the argument +.IR stream +to +\fIpclose\fR() +is not a pointer to a stream created by +\fIpopen\fR(), +the result of +\fIpclose\fR() +is undefined. +.SH "RETURN VALUE" +Upon successful return, +\fIpclose\fR() +shall return the termination status of the command language +interpreter. Otherwise, +\fIpclose\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIpclose\fR() +function shall fail if: +.TP +.BR ECHILD +The status of the child process could not be obtained, as described +above. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +There is a requirement that +\fIpclose\fR() +not return before the child process terminates. This is intended to +disallow implementations that return +.BR [EINTR] +if a signal is received while waiting. If +\fIpclose\fR() +returned before the child terminated, there would be no way for the +application to discover which child used to be associated with the +stream, and it could not do the cleanup itself. +.P +If the stream pointed to by +.IR stream +was not created by +\fIpopen\fR(), +historical implementations of +\fIpclose\fR() +return \(mi1 without setting +.IR errno . +To avoid requiring +\fIpclose\fR() +to set +.IR errno +in this case, POSIX.1\(hy2008 makes the behavior unspecified. An application +should not use +\fIpclose\fR() +to close any stream that was not created by +\fIpopen\fR(). +.P +Some historical implementations of +\fIpclose\fR() +either block or ignore the signals SIGINT, SIGQUIT, and SIGHUP while +waiting for the child process to terminate. Since this behavior is not +described for the +\fIpclose\fR() +function in POSIX.1\(hy2008, such implementations are not conforming. Also, some +historical implementations return +.BR [EINTR] +if a signal is received, even though the child process has not +terminated. Such implementations are also considered non-conforming. +.P +Consider, for example, an application that uses: +.sp +.RS 4 +.nf +\fB +popen("command", "r") +.fi \fR +.P +.RE +.P +to start +.IR command , +which is part of the same application. The parent writes a prompt to +its standard output (presumably the terminal) and then reads from the +\fIpopen\fR()ed +stream. The child reads the response from the user, does some +transformation on the response (pathname expansion, perhaps) and +writes the result to its standard output. The parent process reads the +result from the pipe, does something with it, and prints another +prompt. The cycle repeats. Assuming that both processes do appropriate +buffer flushing, this would be expected to work. +.P +To conform to POSIX.1\(hy2008, +\fIpclose\fR() +must use +\fIwaitpid\fR(), +or some similar function, instead of +\fIwait\fR(). +.P +The code sample below illustrates how the +\fIpclose\fR() +function might be implemented on a system conforming to POSIX.1\(hy2008. +.sp +.RS 4 +.nf +\fB +int pclose(FILE *stream) +{ + int stat; + pid_t pid; +.P + pid = + (void) fclose(stream); + while (waitpid(pid, &stat, 0) == -1) { + if (errno != EINTR){ + stat = -1; + break; + } + } + return(stat); +} +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfork\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/perror.3p b/man-pages-posix-2013-a/man3p/perror.3p new file mode 100644 index 0000000..820f09c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/perror.3p @@ -0,0 +1,156 @@ +'\" et +.TH PERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +perror +\(em write error messages to standard error +.SH SYNOPSIS +.LP +.nf +#include +.P +void perror(const char *\fIs\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIperror\fR() +function shall map the error number accessed through the symbol +.IR errno +to a language-dependent error message, which shall be written to the +standard error stream as follows: +.IP " *" 4 +First (if +.IR s +is not a null pointer and the character pointed to by +.IR s +is not the null byte), the string pointed to by +.IR s +followed by a + +and a +. +.IP " *" 4 +Then an error message string followed by a +. +.P +The contents of the error message strings shall be the same as those +returned by +\fIstrerror\fR() +with argument +.IR errno . +.P +The +\fIperror\fR() +function shall mark for update the last data modification and last file +status change timestamps of the file associated with the standard error +stream at some time between its successful completion and +\fIexit\fR(), +\fIabort\fR(), +or the completion of +\fIfflush\fR() +or +\fIfclose\fR() +on +.IR stderr . +.P +The +\fIperror\fR() +function shall not change the orientation of the standard error stream. +.P +On error, +\fIperror\fR() +shall set the error indicator for the stream to which +.IR stderr +points, and shall set +.IR errno +to indicate the error. +.P +Since no value is returned, an application wishing to check for error +situations should call +.IR clearerr ( stderr ) +before calling +\fIperror\fR(), +then if +.IR ferror ( stderr ) +returns non-zero, the value of +.IR errno +indicates which error occurred. +.SH "RETURN VALUE" +The +\fIperror\fR() +function shall not return a value. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Printing an Error Message for a Function" +.P +The following example replaces +.IR bufptr +with a buffer that is the necessary size. If an error occurs, the +\fIperror\fR() +function prints a message and the program exits. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +char *bufptr; +size_t szbuf; +\&... +if ((bufptr = malloc(szbuf)) == NULL) { + perror("malloc"); exit(2); +} +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Application writers may prefer to use alternative interfaces instead of +\fIperror\fR(), +such as +\fIstrerror_r\fR() +in combination with +\fIfprintf\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfputc\fR\^(\|)", +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIstrerror\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pipe.3p b/man-pages-posix-2013-a/man3p/pipe.3p new file mode 100644 index 0000000..b31b682 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pipe.3p @@ -0,0 +1,169 @@ +'\" et +.TH PIPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pipe +\(em create an interprocess channel +.SH SYNOPSIS +.LP +.nf +#include +.P +int pipe(int \fIfildes\fP[2]); +.fi +.SH DESCRIPTION +The +\fIpipe\fR() +function shall create a pipe and place two file descriptors, one +each into the arguments +.IR fildes [0] +and +.IR fildes [1], +that refer to the open file descriptions for the read and write ends of +the pipe. Their integer values shall be the two lowest available at the +time of the +\fIpipe\fR() +call. The O_NONBLOCK and FD_CLOEXEC flags shall be clear on both file +descriptors. (The +\fIfcntl\fR() +function can be used to set both these flags.) +.P +Data can be written to the file descriptor +.IR fildes [1] +and read from the file descriptor +.IR fildes [0]. +A read on the file descriptor +.IR fildes [0] +shall access data written to the file descriptor +.IR fildes [1] +on a first-in-first-out basis. It is unspecified whether +.IR fildes [0] +is also open for writing and whether +.IR fildes [1] +is also open for reading. +.P +A process has the pipe open for reading (correspondingly writing) if it +has a file descriptor open that refers to the read end, +.IR fildes [0] +(write end, +.IR fildes [1]). +.P +The pipe's user ID shall be set to the effective user ID of the +calling process. +.P +The pipe's group ID shall be set to the effective group ID of the +calling process. +.P +Upon successful completion, +\fIpipe\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the pipe. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIpipe\fR() +function shall fail if: +.TP +.BR EMFILE +All, or all but one, of the file descriptors available to the process +are currently open. +.TP +.BR ENFILE +The number of simultaneously open files in the system would exceed a +system-imposed limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using a Pipe to Pass Data Between a Parent Process and a Child Process" +.P +The following example demonstrates the use of a pipe to transfer data +between a parent process and a child process. Error handling is +excluded, but otherwise this code demonstrates good practice when using +pipes: after the +\fIfork\fR() +the two processes close the unused ends of the pipe before they +commence transferring data. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +.P +int fildes[2]; +const int BSIZE = 100; +char buf[BSIZE]; +ssize_t nbytes; +int status; +.P +status = pipe(fildes); +if (status == \(mi1 ) { + /* an error occurred */ + ... +} +.P +switch (fork()) { +case \(mi1: /* Handle error */ + break; +.P +case 0: /* Child - reads from pipe */ + close(fildes[1]); /* Write end is unused */ + nbytes = read(fildes[0], buf, BSIZE); /* Get data from pipe */ + /* At this point, a further read would see end of file ... */ + close(fildes[0]); /* Finished with pipe */ + exit(EXIT_SUCCESS); +.P +default: /* Parent - writes to pipe */ + close(fildes[0]); /* Read end is unused */ + write(fildes[1], "Hello world\en", 12); /* Write data on pipe */ + close(fildes[1]); /* Child will see EOF */ + exit(EXIT_SUCCESS); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The wording carefully avoids using the verb ``to open'' in order to +avoid any implication of use of +\fIopen\fR(); +see also +\fIwrite\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/poll.3p b/man-pages-posix-2013-a/man3p/poll.3p new file mode 100644 index 0000000..796e431 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/poll.3p @@ -0,0 +1,388 @@ +'\" et +.TH POLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +poll +\(em input/output multiplexing +.SH SYNOPSIS +.LP +.nf +#include +.P +int poll(struct pollfd \fIfds\fP[], nfds_t \fInfds\fP, int \fItimeout\fP); +.fi +.SH DESCRIPTION +The +\fIpoll\fR() +function provides applications with a mechanism for multiplexing +input/output over a set of file descriptors. For each member of the +array pointed to by +.IR fds , +\fIpoll\fR() +shall examine the given file descriptor for the event(s) specified in +.IR events . +The number of +.BR pollfd +structures in the +.IR fds +array is specified by +.IR nfds . +The +\fIpoll\fR() +function shall identify those file descriptors on which an application +can read or write data, or on which certain events have occurred. +.P +The +.IR fds +argument specifies the file descriptors to be examined +and the events of interest for each file descriptor. It is a pointer to +an array with one member for each open file descriptor of interest. The +array's members are +.BR pollfd +structures within which +.IR fd +specifies an open file descriptor and +.IR events +and +.IR revents +are bitmasks constructed by OR'ing a combination of the following event +flags: +.IP POLLIN 12 +Data other than high-priority data may be read without blocking. +.RS 12 +.P +For STREAMS, this flag is set in +.IR revents +even if the message is of zero length. This flag shall be equivalent +to POLLRDNORM | POLLRDBAND. +.RE +.IP POLLRDNORM 12 +Normal data may be read without blocking. +.RS 12 +.P +For STREAMS, data on priority band 0 may be read without blocking. This +flag is set in +.IR revents +even if the message is of zero length. +.RE +.IP POLLRDBAND 12 +Priority data may be read without blocking. +.RS 12 +.P +For STREAMS, data on priority bands greater than 0 may be read without +blocking. This flag is set in +.IR revents +even if the message is of zero length. +.RE +.IP POLLPRI 12 +High-priority data may be read without blocking. +.RS 12 +.P +For STREAMS, this flag is set in +.IR revents +even if the message is of zero length. +.RE +.IP POLLOUT 12 +Normal data may be written without blocking. +.RS 12 +.P +For STREAMS, data on priority band 0 may be written without blocking. +.RE +.IP POLLWRNORM 12 +Equivalent to POLLOUT. +.IP POLLWRBAND 12 +Priority data may be written. +.RS 12 +.P +For STREAMS, data on priority bands greater than 0 may be written +without blocking. If any priority band has been written to on this +STREAM, this event only examines bands that have been written +to at least once. +.RE +.IP POLLERR 12 +An error has occurred on the device or stream. This flag is only valid +in the +.IR revents +bitmask; it shall be ignored in the +.IR events +member. +.IP POLLHUP 12 +A device has been disconnected, or a pipe or FIFO has been closed by the +last process that had it open for writing. Once set, the hangup state of a +FIFO shall persist until some process opens the FIFO for writing or until +all read-only file descriptors for the FIFO are closed. This event and +POLLOUT are mutually-exclusive; a stream can never be writable if a hangup +has occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, +or POLLPRI are not mutually-exclusive. This flag is only valid in the +.IR revents +bitmask; it shall be ignored in the +.IR events +member. +.IP POLLNVAL 12 +The specified +.IR fd +value is invalid. This flag is only valid in the +.IR revents +member; it shall ignored in the +.IR events +member. +.P +The significance and semantics of normal, priority, and high-priority +data are file and device-specific. +.P +If the value of +.IR fd +is less than 0, +.IR events +shall be ignored, and +.IR revents +shall be set to 0 in that entry on return from +\fIpoll\fR(). +.P +In each +.BR pollfd +structure, +\fIpoll\fR() +shall clear the +.IR revents +member, except that where the application requested a report on a +condition by setting one of the bits of +.IR events +listed above, +\fIpoll\fR() +shall set the corresponding bit in +.IR revents +if the requested condition is true. In addition, +\fIpoll\fR() +shall set the POLLHUP, POLLERR, and POLLNVAL flag in +.IR revents +if the condition is true, even if the application did not set the +corresponding bit in +.IR events . +.P +If none of the defined events have occurred on any selected file +descriptor, +\fIpoll\fR() +shall wait at least +.IR timeout +milliseconds for an event to occur on any of the selected file +descriptors. If the value of +.IR timeout +is 0, +\fIpoll\fR() +shall return immediately. If the value of +.IR timeout +is \(mi1, +\fIpoll\fR() +shall block until a requested event occurs or until the call is +interrupted. +.P +Implementations may place limitations on the granularity of timeout +intervals. If the requested timeout interval requires a finer +granularity than the implementation supports, the actual timeout +interval shall be rounded up to the next supported value. +.P +The +\fIpoll\fR() +function shall not be affected by the O_NONBLOCK flag. +.P +The +\fIpoll\fR() +function shall support regular files, terminal and pseudo-terminal +devices, FIFOs, pipes, sockets and +STREAMS-based files. +The behavior of +\fIpoll\fR() +on elements of +.IR fds +that refer to other types of file is unspecified. +.P +Regular files shall always poll TRUE for reading and writing. +.P +A file descriptor for a socket that is listening for connections shall +indicate that it is ready for reading, once connections are available. +A file descriptor for a socket that is connecting asynchronously shall +indicate that it is ready for writing, once a connection has been +established. +.SH "RETURN VALUE" +Upon successful completion, +\fIpoll\fR() +shall return a non-negative value. A positive value indicates the total +number of file descriptors that have been selected (that is, file +descriptors for which the +.IR revents +member is non-zero). A value of 0 indicates that the call timed out and +no file descriptors have been selected. Upon failure, +\fIpoll\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIpoll\fR() +function shall fail if: +.TP +.BR EAGAIN +The allocation of internal data structures failed but a subsequent +request may succeed. +.TP +.BR EINTR +A signal was caught during +\fIpoll\fR(). +.TP +.BR EINVAL +The +.IR nfds +argument is greater than +{OPEN_MAX}, +or one of the +.IR fd +members refers to a STREAM or multiplexer that is linked (directly or +indirectly) downstream from a multiplexer. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Checking for Events on a Stream" +.P +The following example opens a pair of STREAMS devices and then waits +for either one to become writable. This example proceeds as follows: +.IP " 1." 4 +Sets the +.IR timeout +parameter to 500 milliseconds. +.IP " 2." 4 +Opens the STREAMS devices +.BR /dev/dev0 +and +.BR /dev/dev1 , +and then polls them, specifying POLLOUT and POLLWRBAND as the events of +interest. +.RS 4 +.P +The STREAMS device names +.BR /dev/dev0 +and +.BR /dev/dev1 +are only examples of how STREAMS devices can be named; STREAMS naming +conventions may vary among systems conforming to the POSIX.1\(hy2008. +.RE +.IP " 3." 4 +Uses the +.IR ret +variable to determine whether an event has occurred on either of the +two STREAMS. The +\fIpoll\fR() +function is given 500 milliseconds to wait for an event to occur (if it +has not occurred prior to the +\fIpoll\fR() +call). +.IP " 4." 4 +Checks the returned value of +.IR ret . +If a positive value is returned, one of the following can be done: +.RS 4 +.IP " a." 4 +Priority data can be written to the open STREAM on priority bands +greater than 0, because the POLLWRBAND event occurred on the open +STREAM (\c +.IR fds [0] +or +.IR fds [1]). +.IP " b." 4 +Data can be written to the open STREAM on priority-band 0, because the +POLLOUT event occurred on the open STREAM (\c +.IR fds [0] +or +.IR fds [1]). +.RE +.IP " 5." 4 +If the returned value is not a positive value, permission to write data +to the open STREAM (on any priority band) is denied. +.IP " 6." 4 +If the POLLHUP event occurs on the open STREAM (\c +.IR fds [0] +or +.IR fds [1]), +the device on the open STREAM has disconnected. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +struct pollfd fds[2]; +int timeout_msecs = 500; +int ret; + int i; +.P +/* Open STREAMS device. */ +fds[0].fd = open("/dev/dev0", ...); +fds[1].fd = open("/dev/dev1", ...); +fds[0].events = POLLOUT | POLLWRBAND; +fds[1].events = POLLOUT | POLLWRBAND; +.P +ret = poll(fds, 2, timeout_msecs); +.P +if (ret > 0) { + /* An event on one of the fds has occurred. */ + for (i=0; i<2; i++) { + if (fds[i].revents & POLLWRBAND) { + /* Priority data may be written on device number i. */ +\&... + } + if (fds[i].revents & POLLOUT) { + /* Data may be written on device number i. */ +\&... + } + if (fds[i].revents & POLLHUP) { + /* A hangup has occurred on device number i. */ +\&... + } + } +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The POLLHUP event does not occur for FIFOs just because the FIFO is not +open for writing. It only occurs when the FIFO is closed by the last +writer and persists until some process opens the FIFO for writing or +until all read-only file descriptors for the FIFO are closed. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/popen.3p b/man-pages-posix-2013-a/man3p/popen.3p new file mode 100644 index 0000000..5d6f2cd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/popen.3p @@ -0,0 +1,312 @@ +'\" et +.TH POPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +popen +\(em initiate pipe streams to or from a process +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *popen(const char *\fIcommand\fP, const char *\fImode\fP); +.fi +.SH DESCRIPTION +The +\fIpopen\fR() +function shall execute the command specified by the string +.IR command . +It shall create a pipe between the calling program and the executed +command, and shall return a pointer to a stream that can be used to +either read from or write to the pipe. +.P +The environment of the executed command shall be as if a child process +were created within the +\fIpopen\fR() +call using the +\fIfork\fR() +function, and the child invoked the +.IR sh +utility using the call: +.sp +.RS 4 +.nf +\fB +execl(\fIshell path\fP, "sh", "-c", \fIcommand\fP, (char *)0); +.fi \fR +.P +.RE +.P +where +.IR "shell path" +is an unspecified pathname for the +.IR sh +utility. +.P +The +\fIpopen\fR() +function shall ensure that any streams from previous +\fIpopen\fR() +calls that remain open in the parent process are closed in the new +child process. +.P +The +.IR mode +argument to +\fIpopen\fR() +is a string that specifies I/O mode: +.IP " 1." 4 +If +.IR mode +is +.IR r , +when the child process is started, its file descriptor STDOUT_FILENO +shall be the writable end of the pipe, and the file descriptor +\fIfileno\fR(\fIstream\fR) in the calling process, where +.IR stream +is the stream pointer returned by +\fIpopen\fR(), +shall be the readable end of the pipe. +.IP " 2." 4 +If +.IR mode +is +.IR w , +when the child process is started its file descriptor STDIN_FILENO +shall be the readable end of the pipe, and the file descriptor +\fIfileno\fR(\fIstream\fR) in the calling process, where +.IR stream +is the stream pointer returned by +\fIpopen\fR(), +shall be the writable end of the pipe. +.IP " 3." 4 +If +.IR mode +is any other value, the result is unspecified. +.P +After +\fIpopen\fR(), +both the parent and the child process shall be capable of executing +independently before either terminates. +.P +Pipe streams are byte-oriented. +.SH "RETURN VALUE" +Upon successful completion, +\fIpopen\fR() +shall return a pointer to an open stream that can be used to read +or write to the pipe. Otherwise, it shall return a null pointer and +may set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIpopen\fR() +function shall fail if: +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.P +The +\fIpopen\fR() +function may fail if: +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR EINVAL +The +.IR mode +argument is invalid. +.P +The +\fIpopen\fR() +function may also set +.IR errno +values as described by +.IR "\fIfork\fR\^(\|)" +or +.IR "\fIpipe\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using popen(\|) to Obtain a List of Files from the ls Utility" +.P +The following example demonstrates the use of +\fIpopen\fR() +and +\fIpclose\fR() +to execute the command +.IR ls * +in order to obtain a list of files in the current directory: +.sp +.RS 4 +.nf +\fB +#include +\&... +.P +FILE *fp; +int status; +char path[PATH_MAX]; +.P +fp = popen("ls *", "r"); +if (fp == NULL) + /* Handle error */; +.P +while (fgets(path, PATH_MAX, fp) != NULL) + printf("%s", path); +.P +status = pclose(fp); +if (status == \(mi1) { + /* Error reported by pclose() */ + ... +} else { + /* Use macros described under wait() to inspect `status' in order + to determine success/failure of command executed by popen() */ + ... +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Since open files are shared, a mode +.IR r +command can be used as an input filter and a mode +.IR w +command as an output filter. +.P +Buffered reading before opening an input filter may leave the standard +input of that filter mispositioned. Similar problems with an output +filter may be prevented by careful buffer flushing; for example, with +.IR "\fIfflush\fR\^(\|)". +.P +A stream opened by +\fIpopen\fR() +should be closed by +\fIpclose\fR(). +.P +The behavior of +\fIpopen\fR() +is specified for values of +.IR mode +of +.IR r +and +.IR w . +Other modes such as +.IR rb +and +.IR wb +might be supported by specific implementations, but these would not be +portable features. Note that historical implementations of +\fIpopen\fR() +only check to see if the first character of +.IR mode +is +.IR r . +Thus, a +.IR mode +of +.IR "robert the robot" +would be treated as +.IR mode +.IR r , +and a +.IR mode +of +.IR "anything else" +would be treated as +.IR mode +.IR w . +.P +If the application calls +\fIwaitpid\fR() +or +\fIwaitid\fR() +with a +.IR pid +argument greater than 0, and it still has a stream that was called with +\fIpopen\fR() +open, it must ensure that +.IR pid +does not refer to the process started by +\fIpopen\fR(). +.P +To determine whether or not the environment specified in the Shell and Utilities volume of POSIX.1\(hy2008 is +present, use the function call: +.sp +.RS 4 +.nf +\fB +sysconf(_SC_2_VERSION) +.fi \fR +.P +.RE +.P +(See +.IR "\fIsysconf\fR\^(\|)"). +.SH RATIONALE +The +\fIpopen\fR() +function should not be used by programs that have set user (or group) +ID privileges. The +\fIfork\fR() +and +.IR exec +family of functions (except +\fIexeclp\fR() +and +\fIexecvp\fR()), +should be used instead. This prevents any unforeseen manipulation of +the environment of the user that could cause execution of commands not +anticipated by the calling program. +.P +If the original and +\fIpopen\fR()ed +processes both intend to read or write or read and write a common file, +and either will be using FILE-type C functions (\c +\fIfread\fR(), +\fIfwrite\fR(), +and so on), the rules for sharing file handles must be observed (see +.IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams"). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfork\fR\^(\|)", +.IR "\fIpclose\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIsh\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_fadvise.3p b/man-pages-posix-2013-a/man3p/posix_fadvise.3p new file mode 100644 index 0000000..bc6b3fb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_fadvise.3p @@ -0,0 +1,133 @@ +'\" et +.TH POSIX_FADVISE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_fadvise +\(em file advisory information +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_fadvise(int \fIfd\fP, off_t \fIoffset\fP, off_t \fIlen\fP, int \fIadvice\fP); +.fi +.SH DESCRIPTION +The +\fIposix_fadvise\fR() +function shall advise the implementation on the expected behavior +of the application with respect to the data in the file associated with +the open file descriptor, +.IR fd , +starting at +.IR offset +and continuing for +.IR len +bytes. The specified range need not currently exist in the file. If +.IR len +is zero, all data following +.IR offset +is specified. The implementation may use this information to optimize +handling of the specified data. The +\fIposix_fadvise\fR() +function shall have no effect on the semantics of other operations on +the specified data, although it may affect the performance of other +operations. +.P +The advice to be applied to the data is specified by the +.IR advice +parameter and may be one of the following values: +.IP POSIX_FADV_NORMAL 6 +.br +Specifies that the application has no advice to give on its behavior +with respect to the specified data. It is the default characteristic if +no advice is given for an open file. +.IP POSIX_FADV_SEQUENTIAL 6 +.br +Specifies that the application expects to access the specified data +sequentially from lower offsets to higher offsets. +.IP POSIX_FADV_RANDOM 6 +.br +Specifies that the application expects to access the specified data in +a random order. +.IP POSIX_FADV_WILLNEED 6 +.br +Specifies that the application expects to access the specified data in +the near future. +.IP POSIX_FADV_DONTNEED 6 +.br +Specifies that the application expects that it will not access the +specified data in the near future. +.IP POSIX_FADV_NOREUSE 6 +.br +Specifies that the application expects to access the specified data +once and then not reuse it thereafter. +.P +These values are defined in +.IR . +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_fadvise\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_fadvise\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor. +.TP +.BR EINVAL +The value of +.IR advice +is invalid, or the value of +.IR len +is less than zero. +.TP +.BR ESPIPE +The +.IR fd +argument is associated with a pipe or FIFO. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_fadvise\fR() +function is part of the Advisory Information option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIposix_madvise\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_fallocate.3p b/man-pages-posix-2013-a/man3p/posix_fallocate.3p new file mode 100644 index 0000000..f4fde58 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_fallocate.3p @@ -0,0 +1,160 @@ +'\" et +.TH POSIX_FALLOCATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_fallocate +\(em file space control +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_fallocate(int \fIfd\fP, off_t \fIoffset\fP, off_t \fIlen\fP); +.fi +.SH DESCRIPTION +The +\fIposix_fallocate\fR() +function shall ensure that any required storage for regular file data +starting at +.IR offset +and continuing for +.IR len +bytes is allocated on the file system storage media. If +\fIposix_fallocate\fR() +returns successfully, subsequent writes to the specified file data +shall not fail due to the lack of free space on the file system storage +media. +.P +If the +.IR offset +\c +.IR len +is beyond the current file size, then +\fIposix_fallocate\fR() +shall adjust the file size to +.IR offset +\c +.IR len . +Otherwise, the file size shall not be changed. +.P +It is implementation-defined whether a previous +\fIposix_fadvise\fR() +call influences allocation strategy. +.P +Space allocated via +\fIposix_fallocate\fR() +shall be freed by a successful call to +\fIcreat\fR() +or +\fIopen\fR() +that truncates the size of the file. Space allocated via +\fIposix_fallocate\fR() +may be freed by a successful call to +\fIftruncate\fR() +that reduces the file size to a size smaller than +.IR offset +\c +.IR len . +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_fallocate\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_fallocate\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor. +.TP +.BR EBADF +The +.IR fd +argument references a file that was opened without write permission. +.TP +.BR EFBIG +The value of +.IR offset +\c +.IR len +is greater than the maximum file size. +.TP +.BR EINTR +A signal was caught during execution. +.TP +.BR EINVAL +The +.IR len +argument is less than zero, or the +.IR offset +argument is less than zero, or the underlying file system does not +support this operation. +.TP +.BR EIO +An I/O error occurred while reading from or writing to a file system. +.TP +.BR ENODEV +The +.IR fd +argument does not refer to a regular file. +.TP +.BR ENOSPC +There is insufficient free space remaining on the file system storage +media. +.TP +.BR ESPIPE +The +.IR fd +argument is associated with a pipe or FIFO. +.P +The +\fIposix_fallocate\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR len +argument is zero. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_fallocate\fR() +function is part of the Advisory Information option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcreat\fR\^(\|)", +.IR "\fIftruncate\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_madvise.3p b/man-pages-posix-2013-a/man3p/posix_madvise.3p new file mode 100644 index 0000000..6a78275 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_madvise.3p @@ -0,0 +1,144 @@ +'\" et +.TH POSIX_MADVISE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_madvise +\(em memory advisory information and alignment control +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_madvise(void *\fIaddr\fP, size_t \fIlen\fP, int \fIadvice\fP); +.fi +.SH DESCRIPTION +The +\fIposix_madvise\fR() +function shall advise the implementation on the expected behavior of +the application with respect to the data in the memory starting at +address +.IR addr , +and continuing for +.IR len +bytes. The implementation may use this information to optimize handling +of the specified data. The +\fIposix_madvise\fR() +function shall have no effect on the semantics of access to memory in +the specified range, although it may affect the performance of access. +.P +The implementation may require that +.IR addr +be a multiple of the page size, which is the value returned by +\fIsysconf\fR() +when the name value _SC_PAGESIZE is used. +.P +The advice to be applied to the memory range is specified by the +.IR advice +parameter and may be one of the following values: +.IP POSIX_MADV_NORMAL 6 +.br +Specifies that the application has no advice to give on its behavior +with respect to the specified range. It is the default characteristic +if no advice is given for a range of memory. +.IP POSIX_MADV_SEQUENTIAL 6 +.br +Specifies that the application expects to access the specified range +sequentially from lower addresses to higher addresses. +.IP POSIX_MADV_RANDOM 6 +.br +Specifies that the application expects to access the specified range in +a random order. +.IP POSIX_MADV_WILLNEED 6 +.br +Specifies that the application expects to access the specified range in +the near future. +.IP POSIX_MADV_DONTNEED 6 +.br +Specifies that the application expects that it will not access the +specified range in the near future. +.P +These values are defined in the +.IR +header. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_madvise\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_madvise\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR advice +is invalid. +.TP +.BR ENOMEM +Addresses in the range starting at +.IR addr +and continuing for +.IR len +bytes are partly or completely outside the range allowed for the +address space of the calling process. +.br +.P +The +\fIposix_madvise\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR addr +is not a multiple of the value returned by +\fIsysconf\fR() +when the name value _SC_PAGESIZE is used. +.TP +.BR EINVAL +The value of +.IR len +is zero. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_madvise\fR() +function is part of the Advisory Information option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImmap\fR\^(\|)", +.IR "\fIposix_fadvise\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_mem_offset.3p b/man-pages-posix-2013-a/man3p/posix_mem_offset.3p new file mode 100644 index 0000000..f4b3884 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_mem_offset.3p @@ -0,0 +1,125 @@ +'\" et +.TH POSIX_MEM_OFFSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_mem_offset +\(em find offset and length of a mapped typed memory block +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_mem_offset(const void *restrict \fIaddr\fP, size_t \fIlen\fP, + off_t *restrict \fIoff\fP, size_t *restrict \fIcontig_len\fP, + int *restrict \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIposix_mem_offset\fR() +function shall return in the variable pointed to by +.IR off +a value that identifies the offset (or location), within a memory +object, of the memory block currently mapped at +.IR addr . +The function shall return in the variable pointed to by +.IR fildes , +the descriptor used (via +\fImmap\fR()) +to establish the mapping which contains +.IR addr . +If that descriptor was closed since the mapping was established, the +returned value of +.IR fildes +shall be \(mi1. The +.IR len +argument specifies the length of the block of the memory object the +user wishes the offset for; upon return, the value pointed to by +.IR contig_len +shall equal either +.IR len , +or the length of the largest contiguous block of the memory object that +is currently mapped to the calling process starting at +.IR addr , +whichever is smaller. +.P +If the memory object mapped at +.IR addr +is a typed memory object, then if the +.IR off +and +.IR contig_len +values obtained by calling +\fIposix_mem_offset\fR() +are used in a call to +\fImmap\fR() +with a file descriptor that refers to the same memory pool as +.IR fildes +(either through the same port or through a different port), and that +was opened with neither the POSIX_TYPED_MEM_ALLOCATE nor the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, +the typed memory area that is mapped shall be exactly the same area +that was mapped at +.IR addr +in the address space of the process that called +\fIposix_mem_offset\fR(). +.P +If the memory object specified by +.IR fildes +is not a typed memory object, then the behavior of this function is +implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_mem_offset\fR() +function shall return zero; otherwise, the corresponding error status +value shall be returned. +.SH ERRORS +The +\fIposix_mem_offset\fR() +function shall fail if: +.TP +.BR EACCES +The process has not mapped a memory object supported by this function +at the given address +.IR addr . +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImmap\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_memalign.3p b/man-pages-posix-2013-a/man3p/posix_memalign.3p new file mode 100644 index 0000000..605e086 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_memalign.3p @@ -0,0 +1,101 @@ +'\" et +.TH POSIX_MEMALIGN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_memalign +\(em aligned memory allocation +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_memalign(void **\fImemptr\fP, size_t \fIalignment\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIposix_memalign\fR() +function shall allocate +.IR size +bytes aligned on a boundary specified by +.IR alignment , +and shall return a pointer to the allocated memory in +.IR memptr . +The value of +.IR alignment +shall be a power of two multiple of +.IR sizeof (\c +.BR "void *" ). +.P +Upon successful completion, the value pointed to by +.IR memptr +shall be a multiple of +.IR alignment . +.P +If the size of the space requested is 0, the behavior is +implementation-defined; the value returned in +.IR memptr +shall be either a null pointer or a unique pointer. +.P +The +\fIfree\fR() +function shall deallocate memory that has previously been allocated by +\fIposix_memalign\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_memalign\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_memalign\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the alignment parameter is not a power of two multiple of +.IR sizeof (\c +.BR "void *" ). +.TP +.BR ENOMEM +There is insufficient memory available with the requested alignment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_memalign\fR() +function is part of the Advisory Information option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_openpt.3p b/man-pages-posix-2013-a/man3p/posix_openpt.3p new file mode 100644 index 0000000..24668b6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_openpt.3p @@ -0,0 +1,172 @@ +'\" et +.TH POSIX_OPENPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_openpt +\(em open a pseudo-terminal device +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_openpt(int \fIoflag\fP); +.fi +.SH DESCRIPTION +The +\fIposix_openpt\fR() +function shall establish a connection between a master device for a +pseudo-terminal and a file descriptor. The file descriptor is used by +other I/O functions that refer to that pseudo-terminal. +.P +The file status flags and file access modes of the open file +description shall be set according to the value of +.IR oflag . +.P +Values for +.IR oflag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP O_RDWR 12 +Open for reading and writing. +.IP O_NOCTTY 12 +If set +\fIposix_openpt\fR() +shall not cause the terminal device to become the controlling terminal +for the process. +.P +The behavior of other values for the +.IR oflag +argument is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_openpt\fR() +function shall open a master pseudo-terminal device and return a +non-negative integer representing the lowest numbered unused file +descriptor. Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIposix_openpt\fR() +function shall fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIposix_openpt\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR oflag +is not valid. +.TP +.BR EAGAIN +Out of pseudo-terminal resources. +.TP +.BR ENOSR +Out of STREAMS resources. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Opening a Pseudo-Terminal and Returning the Name of the Slave Device and a File Descriptor" +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int masterfd, slavefd; +char *slavedevice; +.P +masterfd = posix_openpt(O_RDWR|O_NOCTTY); +.P +if (masterfd == -1 + || grantpt (masterfd) == -1 + || unlockpt (masterfd) == -1 + || (slavedevice = ptsname (masterfd)) == NULL) + return -1; +.P +printf("slave device is: %s\en", slavedevice); +.P +slavefd = open(slavedevice, O_RDWR|O_NOCTTY); +if (slavefd < 0) + return -1; +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +This function is a method for portably obtaining a file descriptor of a +master terminal device for a pseudo-terminal. The +\fIgrantpt\fR() +and +\fIptsname\fR() +functions can be used to manipulate mode and ownership permissions, and +to obtain the name of the slave device, respectively. +.SH RATIONALE +The standard developers considered the matter of adding a special +device for cloning master pseudo-terminals: the +.BR /dev/ptmx +device. However, consensus could not be reached, and it was felt that +adding a new function would permit other implementations. The +\fIposix_openpt\fR() +function is designed to complement the +\fIgrantpt\fR(), +\fIptsname\fR(), +and +\fIunlockpt\fR() +functions. +.P +On implementations supporting the +.BR /dev/ptmx +clone device, opening the master device of a pseudo-terminal is simply: +.sp +.RS 4 +.nf +\fB +mfdp = open("/dev/ptmx", oflag ); +if (mfdp < 0) + return -1; +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawn.3p b/man-pages-posix-2013-a/man3p/posix_spawn.3p new file mode 100644 index 0000000..e71ca14 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawn.3p @@ -0,0 +1,932 @@ +'\" et +.TH POSIX_SPAWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawn, +posix_spawnp +\(em spawn a process +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn(pid_t *restrict \fIpid\fP, const char *restrict \fIpath\fP, + const posix_spawn_file_actions_t *\fIfile_actions\fP, + const posix_spawnattr_t *restrict \fIattrp\fP, + char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]); +int posix_spawnp(pid_t *restrict \fIpid\fP, const char *restrict \fIfile\fP, + const posix_spawn_file_actions_t *\fIfile_actions\fP, + const posix_spawnattr_t *restrict \fIattrp\fP, + char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]); +.fi +.SH DESCRIPTION +The +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions shall create a new process (child process) from the specified +process image. The new process image shall be constructed from a regular +executable file called the new process image file. +.P +When a C program is executed as the result of this call, it shall be +entered as a C-language function call as follows: +.sp +.RS 4 +.nf +\fB +int main(int \fIargc\fP, char *\fIargv\fP[]); +.fi \fR +.P +.RE +.P +where +.IR argc +is the argument count and +.IR argv +is an array of character pointers to the arguments themselves. In +addition, the following variable: +.sp +.RS 4 +.nf +\fB +extern char **environ; +.fi \fR +.P +.RE +.P +shall be initialized as a pointer to an array of character pointers to +the environment strings. +.P +The argument +.IR argv +is an array of character pointers to null-terminated strings. The last +member of this array shall be a null pointer and is not +counted in +.IR argc . +These strings constitute the argument list available to the new process +image. The value in +.IR argv [0] +should point to a filename string that is associated with the process +image being started by the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +function. +.P +The argument +.IR envp +is an array of character pointers to null-terminated strings. These +strings constitute the environment for the new process image. The +environment array is terminated by a null pointer. +.P +The number of bytes available for the combined argument +and environment lists of the child process is +{ARG_MAX}. +The implementation shall specify in the system documentation (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 2" ", " "Conformance") +whether any list overhead, such as length words, null +terminators, pointers, or alignment bytes, is included in this total. +.P +The +.IR path +argument to +\fIposix_spawn\fR() +is a pathname that identifies the new process image file to execute. +.P +The +.IR file +parameter to +\fIposix_spawnp\fR() +shall be used to construct a pathname that identifies the new process +image file. If the +.IR file +parameter contains a + +character, the +.IR file +parameter shall be used as the pathname for the new process image +file. Otherwise, the path prefix for this file shall be obtained by a +search of the directories passed as the environment variable +.IR PATH +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables"). +If this environment variable is not defined, the results of the search +are implementation-defined. +.P +If +.IR file_actions +is a null pointer, then file descriptors open in the calling process +shall remain open in the child process, except for those whose +close-on-\c +.IR exec +flag FD_CLOEXEC is set (see +.IR "\fIfcntl\fR\^(\|)"). +For those file descriptors that remain open, all attributes of the +corresponding open file descriptions, including file locks (see +.IR "\fIfcntl\fR\^(\|)"), +shall remain unchanged. +.P +If +.IR file_actions +is not NULL, then the file descriptors open in the child process shall +be those open in the calling process as modified by the spawn file +actions object pointed to by +.IR file_actions +and the FD_CLOEXEC flag of each remaining open file descriptor after +the spawn file actions have been processed. The effective order of +processing the spawn file actions shall be: +.IP " 1." 4 +The set of open file descriptors for the child process shall initially +be the same set as is open for the calling process. All attributes of +the corresponding open file descriptions, including file locks (see +.IR "\fIfcntl\fR\^(\|)"), +shall remain unchanged. +.IP " 2." 4 +The signal mask, signal default actions, and the effective user and +group IDs for the child process shall be changed as specified in the +attributes object referenced by +.IR attrp . +.IP " 3." 4 +The file actions specified by the spawn file actions object shall be +performed in the order in which they were added to the spawn file +actions object. +.IP " 4." 4 +Any file descriptor that has its FD_CLOEXEC flag set (see +.IR "\fIfcntl\fR\^(\|)") +shall be closed. +.P +If file descriptor 0, 1, or 2 would otherwise be closed in the new +process image created by +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(), +implementations may open an unspecified file for the file descriptor in +the new process image. If a standard utility or a conforming application +is executed with file descriptor 0 not open for reading or with file +descriptor 1 or 2 not open for writing, the environment in which the +utility or application is executed shall be deemed non-conforming, and +consequently the utility or application might not behave as described +in this standard. +.P +The +.BR posix_spawnattr_t +spawn attributes object type is defined in +.IR . +It shall contain at least the attributes defined below. +.P +If the POSIX_SPAWN_SETPGROUP flag is set in the +.IR spawn-flags +attribute +of the object referenced by +.IR attrp , +and the +.IR spawn-pgroup +attribute of the same object is non-zero, then the child's process +group shall be as specified in the +.IR spawn-pgroup +attribute of the object referenced by +.IR attrp . +.P +As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +and the +.IR spawn-pgroup +attribute of the same object is set to zero, then the child shall be in +a new process group with a process group ID equal to its process ID. +.P +If the POSIX_SPAWN_SETPGROUP flag is not set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +the new child process shall inherit the parent's process group. +.P +If the POSIX_SPAWN_SETSCHEDPARAM flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +but POSIX_SPAWN_SETSCHEDULER is not set, the new process image shall +initially have the scheduling policy of the calling process with the +scheduling parameters specified in the +.IR spawn-schedparam +attribute of the object referenced by +.IR attrp . +.P +If the POSIX_SPAWN_SETSCHEDULER flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp +(regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), the +new process image shall initially have the scheduling policy specified +in the +.IR spawn-schedpolicy +attribute of the object referenced by +.IR attrp +and the scheduling parameters specified in the +.IR spawn-schedparam +attribute of the same object. +.P +The POSIX_SPAWN_RESETIDS flag in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp +governs the effective user ID of the child process. If this flag is +not set, the child process shall inherit the effective user ID of the +parent process. If this flag is set, the effective user ID of the child +process shall be reset to the parent's real user ID. In either case, +if the set-user-ID mode bit of the new process image file is set, the +effective user ID of the child process shall become that file's owner +ID before the new process image begins execution. +.P +The POSIX_SPAWN_RESETIDS flag in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp +also governs the effective group ID of the child process. If this flag +is not set, the child process shall inherit the effective group ID of the +parent process. If this flag is set, the effective group ID of the child +process shall be reset to the parent's real group ID. In either case, +if the set-group-ID mode bit of the new process image file is set, the +effective group ID of the child process shall become that file's group +ID before the new process image begins execution. +.P +If the POSIX_SPAWN_SETSIGMASK flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +the child process shall initially have the signal mask specified in the +.IR spawn-sigmask +attribute of the object referenced by +.IR attrp . +.P +If the POSIX_SPAWN_SETSIGDEF flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +the signals specified in the +.IR spawn-sigdefault +attribute of the same object shall be set to their default actions in +the child process. Signals set to the default action in the parent +process shall be set to the default action in the child process. +.P +Signals set to be caught by the calling process shall be set to the +default action in the child process. +.P +Except for SIGCHLD, signals set to be ignored by the calling process +image shall be set to be ignored by the child process, unless otherwise +specified by the POSIX_SPAWN_SETSIGDEF flag being set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp +and the signals being indicated in the +.IR spawn-sigdefault +attribute of the object referenced by +.IR attrp . +.P +If the SIGCHLD signal is set to be ignored by the calling process, it +is unspecified whether the SIGCHLD signal is set to be ignored or to +the default action in the child process, unless otherwise specified by +the POSIX_SPAWN_SETSIGDEF flag being set in the +.IR spawn_flags +attribute of the object referenced by +.IR attrp +and the SIGCHLD signal being indicated in the +.IR spawn_sigdefault +attribute of the object referenced by +.IR attrp . +.P +If the value of the +.IR attrp +pointer is NULL, then the default values are used. +.P +All process attributes, other than those influenced by the attributes +set in the object referenced by +.IR attrp +as specified above or by the file descriptor manipulations specified in +.IR file_actions , +shall appear in the new process image as though +\fIfork\fR() +had been called to create a child process and then a member of the +.IR exec +family of functions had been called by the child process to execute the +new process image. +.P +It is implementation-defined whether the fork handlers are run when +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +is called. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +shall return the process ID of the child process to the parent process, +in the variable pointed to by a non-NULL +.IR pid +argument, and shall return zero as the function return value. +Otherwise, no child process shall be created, the value stored into the +variable pointed to by a non-NULL +.IR pid +is unspecified, and an error number shall be returned as the function +return value to indicate the error. If the +.IR pid +argument is a null pointer, the process ID of the child is not returned +to the caller. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR file_actions +or +.IR attrp +is invalid. +.P +If this error occurs after the calling process successfully returns +from the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +function, the child process may exit with exit status 127. +.P +If +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fail for any of the reasons that would cause +\fIfork\fR() +or one of the +.IR exec +family of functions to fail, an error value shall be returned as +described by +\fIfork\fR() +and +.IR exec , +respectively (or, if the error occurs after the calling process +successfully returns, the child process shall exit with exit status 127). +.P +If POSIX_SPAWN_SETPGROUP is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +and +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fails while changing the child's process group, an error value shall be +returned as described by +\fIsetpgid\fR() +(or, if the error occurs after the calling process successfully +returns, the child process shall exit with exit status 127). +.P +If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not +set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +then if +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fails for any of the reasons that would cause +\fIsched_setparam\fR() +to fail, an error value shall be returned as described by +\fIsched_setparam\fR() +(or, if the error occurs after the calling process successfully +returns, the child process shall exit with exit status 127). +.P +If POSIX_SPAWN_SETSCHEDULER is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +and if +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fails for any of the reasons that would cause +\fIsched_setscheduler\fR() +to fail, an error value shall be returned as described by +\fIsched_setscheduler\fR() +(or, if the error occurs after the calling process successfully +returns, the child process shall exit with exit status 127). +.P +If the +.IR file_actions +argument is not NULL, and specifies any +.IR close , +.IR dup2 , +or +.IR open +actions to be performed, and if +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fails for any of the reasons that would cause +\fIclose\fR(), +\fIdup2\fR(), +or +\fIopen\fR() +to fail, an error value shall be returned as described by +\fIclose\fR(), +\fIdup2\fR(), +and +\fIopen\fR(), +respectively (or, if the error occurs after the calling process +successfully returns, the child process shall exit with exit status +127). An open file action may, by itself, result in any of the errors +described by +\fIclose\fR() +or +\fIdup2\fR(), +in addition to those described by +\fIopen\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.P +See also the APPLICATION USAGE section for +.IR "\fIexec\fR\^". +.SH RATIONALE +The +\fIposix_spawn\fR() +function and its close relation +\fIposix_spawnp\fR() +have been introduced to overcome the following perceived difficulties +with +\fIfork\fR(): +the +\fIfork\fR() +function is difficult or impossible to implement without swapping or +dynamic address translation. +.IP " *" 4 +Swapping is generally too slow for a realtime environment. +.IP " *" 4 +Dynamic address translation is not available everywhere that POSIX +might be useful. +.IP " *" 4 +Processes are too useful to simply option out of POSIX whenever it must +run without address translation or other MMU services. +.P +Thus, POSIX needs process creation and file execution primitives that +can be efficiently implemented without address translation or other MMU +services. +.P +The +\fIposix_spawn\fR() +function is implementable as a library routine, but both +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +are designed as kernel operations. Also, although they may be an +efficient replacement for many +\fIfork\fR()/\c +.IR exec +pairs, their goal is to provide useful process creation primitives for +systems that have difficulty with +\fIfork\fR(), +not to provide drop-in replacements for +\fIfork\fR()/\c +.IR exec . +.P +This view of the role of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +influenced the design of their API. It does not attempt to provide the +full functionality of +\fIfork\fR()/\c +.IR exec +in which arbitrary user-specified operations of any sort are permitted +between the creation of the child process and the execution of the new +process image; any attempt to reach that level would need to provide a +programming language as parameters. Instead, +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +are process creation primitives like the +.IR Start_Process +and +.IR Start_Process_Search +Ada language bindings package +.IR POSIX_Process_Primitives +and also like those in many operating systems that are not UNIX +systems, but with some POSIX-specific additions. +.P +To achieve its coverage goals, +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +have control of six types of inheritance: file descriptors, process +group ID, user and group ID, signal mask, scheduling, and whether each +signal ignored in the parent will remain ignored in the child, or be +reset to its default action in the child. +.P +Control of file descriptors is required to allow an independently +written child process image to access data streams opened by and even +generated or read by the parent process without being specifically +coded to know which parent files and file descriptors are to be used. +Control of the process group ID is required to control how the +job control of the child process relates to that of the parent. +.P +Control of the signal mask and signal defaulting is sufficient to +support the implementation of +\fIsystem\fR(). +Although support for +\fIsystem\fR() +is not explicitly one of the goals for +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR(), +it is covered under the ``at least 50%'' coverage goal. +.P +The intention is that the normal file descriptor inheritance across +\fIfork\fR(), +the subsequent effect of the specified spawn file actions, and the +normal file descriptor inheritance across one of the +.IR exec +family of functions should fully specify open file inheritance. The +implementation need make no decisions regarding the set of open file +descriptors when the child process image begins execution, those +decisions having already been made by the caller and expressed as the +set of open file descriptors and their FD_CLOEXEC flags at the time of +the call and the spawn file actions object specified in the call. We +have been assured that in cases where the POSIX +.IR Start_Process +Ada primitives have been implemented in a library, this method of +controlling file descriptor inheritance may be implemented very easily. +.P +We can identify several problems with +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR(), +but there does not appear to be a solution that introduces fewer +problems. Environment modification for child process attributes not +specifiable via the +.IR attrp +or +.IR file_actions +arguments must be done in the parent process, and since the parent +generally wants to save its context, it is more costly than similar +functionality with +\fIfork\fR()/\c +.IR exec . +It is also complicated to modify the environment of a multi-threaded +process temporarily, since all threads must agree when it is safe for +the environment to be changed. However, this cost is only borne by +those invocations of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +that use the additional functionality. Since extensive modifications +are not the usual case, and are particularly unlikely in time-critical +code, keeping much of the environment control out of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +is appropriate design. +.P +The +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions do not have all the power of +\fIfork\fR()/\c +.IR exec . +This is to be expected. The +\fIfork\fR() +function is a wonderfully powerful operation. We do not expect to +duplicate its functionality in a simple, fast function with no special +hardware requirements. It is worth noting that +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +are very similar to the process creation operations on many operating +systems that are not UNIX systems. +.SS "Requirements" +.P +The requirements for +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +are: +.IP " *" 4 +They must be implementable without an MMU or unusual hardware. +.IP " *" 4 +They must be compatible with existing POSIX standards. +.P +Additional goals are: +.IP " *" 4 +They should be efficiently implementable. +.IP " *" 4 +They should be able to replace at least 50% of typical executions of +\fIfork\fR(). +.IP " *" 4 +A system with +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +and without +\fIfork\fR() +should be useful, at least for realtime applications. +.IP " *" 4 +A system with +\fIfork\fR() +and the +.IR exec +family should be able to implement +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +as library routines. +.SS "Two-Syntax" +.P +POSIX +.IR exec +has several calling sequences with approximately the same +functionality. These appear to be required for compatibility with +existing practice. Since the existing practice for the +.IR posix_spawn* (\|) +functions is otherwise substantially unlike POSIX, we feel that +simplicity outweighs compatibility. There are, therefore, only two +names for the +.IR posix_spawn* (\|) +functions. +.P +The parameter list does not differ between +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR(); +\fIposix_spawnp\fR() +interprets the second parameter more elaborately than +\fIposix_spawn\fR(). +.SS "Compatibility with POSIX.5 (Ada)" +.P +The +.IR Start_Process +and +.IR Start_Process_Search +procedures from the +.IR POSIX_Process_Primitives +package from the Ada language binding to POSIX.1 encapsulate +\fIfork\fR() +and +.IR exec +functionality in a manner similar to that of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR(). +Originally, in keeping with our simplicity goal, the standard +developers had limited the capabilities of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +to a subset of the capabilities of +.IR Start_Process +and +.IR Start_Process_Search ; +certain non-default capabilities were not supported. However, based on +suggestions by the ballot group to improve file descriptor mapping or +drop it, and on the advice of an Ada Language Bindings working group +member, the standard developers decided that +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +should be sufficiently powerful to implement +.IR Start_Process +and +.IR Start_Process_Search . +The rationale is that if the Ada language binding to such a primitive +had already been approved as an IEEE standard, there can be little +justification for not approving the functionally-equivalent parts of a +C binding. The only three capabilities provided by +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +that are not provided by +.IR Start_Process +and +.IR Start_Process_Search +are optionally specifying the child's process group ID, the set of +signals to be reset to default signal handling in the child process, +and the child's scheduling policy and parameters. +.P +For the Ada language binding for +.IR Start_Process +to be implemented with +\fIposix_spawn\fR(), +that binding would need to explicitly pass an empty signal mask and the +parent's environment to +\fIposix_spawn\fR() +whenever the caller of +.IR Start_Process +allowed these arguments to default, since +\fIposix_spawn\fR() +does not provide such defaults. The ability of +.IR Start_Process +to mask user-specified signals during its execution is functionally +unique to the Ada language binding and must be dealt with in the +binding separately from the call to +\fIposix_spawn\fR(). +.SS "Process Group" +.P +The process group inheritance field can be used to join the child +process with an existing process group. By assigning a value of zero to +the +.IR spawn-pgroup +attribute of the object referenced by +.IR attrp , +the +\fIsetpgid\fR() +mechanism will place the child process in a new process group. +.SS "Threads" +.P +Without the +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions, systems without address translation can still use threads to +give an abstraction of concurrency. In many cases, thread creation +suffices, but it is not always a good substitute. The +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions are considerably ``heavier'' than thread creation. Processes +have several important attributes that threads do not. Even without +address translation, a process may have base-and-bound memory +protection. Each process has a process environment including security +attributes and file capabilities, and powerful scheduling attributes. +Processes abstract the behavior of non-uniform-memory-architecture +multi-processors better than threads, and they are more convenient to +use for activities that are not closely linked. +.P +The +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions may not bring support for multiple processes to every +configuration. Process creation is not the only piece of operating +system support required to support multiple processes. The total cost +of support for multiple processes may be quite high in some +circumstances. Existing practice shows that support for multiple +processes is uncommon and threads are common among ``tiny kernels''. +There should, therefore, probably continue to be AEPs for operating +systems with only one process. +.SS "Asynchronous Error Notification" +.P +A library implementation of +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +may not be able to detect all possible errors before it forks the child +process. POSIX.1\(hy2008 provides for an error indication returned from a child +process which could not successfully complete the spawn operation via a +special exit status which may be detected using the status value +returned by +\fIwait\fR(), +\fIwaitid\fR(), +and +\fIwaitpid\fR(). +.P +The +.IR stat_val +interface and the macros used to interpret it are not well suited to +the purpose of returning API errors, but they are the only path +available to a library implementation. Thus, an implementation may +cause the child process to exit with exit status 127 for any error +detected during the spawn process after the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +function has successfully returned. +.P +The standard developers had proposed using two additional macros to +interpret +.IR stat_val . +The first, WIFSPAWNFAIL, would have detected a status that indicated +that the child exited because of an error detected during the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operations rather than during actual execution of the child process +image; the second, WSPAWNERRNO, would have extracted the error value if +WIFSPAWNFAIL indicated a failure. Unfortunately, the ballot group +strongly opposed this because it would make a library implementation of +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +dependent on kernel modifications to +\fIwaitpid\fR() +to be able to embed special information in +.IR stat_val +to indicate a spawn failure. +.P +The 8 bits of child process exit status that are guaranteed by POSIX.1\(hy2008 to +be accessible to the waiting parent process are insufficient to +disambiguate a spawn error from any other kind of error that may be +returned by an arbitrary process image. No other bits of the exit +status are required to be visible in +.IR stat_val , +so these macros could not be strictly implemented at the library level. +Reserving an exit status of 127 for such spawn errors is consistent +with the use of this value by +\fIsystem\fR() +and +\fIpopen\fR() +to signal failures in these operations that occur after the function +has returned but before a shell is able to execute. The exit status of +127 does not uniquely identify this class of error, nor does it provide +any detailed information on the nature of the failure. Note that a +kernel implementation of +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +is permitted (and encouraged) to return any possible error as the +function value, thus providing more detailed failure information to the +parent process. +.P +Thus, no special macros are available to isolate asynchronous +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +errors. Instead, errors detected by the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operations in the context of the child process before the new process +image executes are reported by setting the child's exit status to 127. +The calling process may use the WIFEXITED and WEXITSTATUS macros on the +.IR stat_val +stored by the +\fIwait\fR() +or +\fIwaitpid\fR() +functions to detect spawn failures to the extent that other status +values with which the child process image may exit (before the parent +can conclusively determine that the child process image has begun +execution) are distinct from exit status 127. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIalarm\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_adddup2\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_addclose.3p b/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_addclose.3p new file mode 100644 index 0000000..d72ee5e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_addclose.3p @@ -0,0 +1,328 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawn_file_actions_addclose, +posix_spawn_file_actions_addopen +\(em add close or open action to spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t + *\fIfile_actions\fP, int \fIfildes\fP); +int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t + *restrict \fIfile_actions\fP, int \fIfildes\fP, + const char *restrict \fIpath\fP, int \fIoflag\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +These functions shall add or delete a close or open action to a +spawn file actions object. +.P +A spawn file actions object is of type +.BR posix_spawn_file_actions_t +(defined in +.IR ) +and is used to specify a series of actions to be performed by a +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operation in order to arrive at the set of open file descriptors for +the child process given the set of open file descriptors of the parent. +POSIX.1\(hy2008 does not define comparison or assignment operators for the type +.BR posix_spawn_file_actions_t . +.P +A spawn file actions object, when passed to +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(), +shall specify how the set of open file descriptors in the calling +process is transformed into a set of potentially open file descriptors +for the spawned process. This transformation shall be as if the +specified sequence of actions was performed exactly once, in the +context of the spawned process (prior to execution of the new process +image), in the order in which the actions were added to the object; +additionally, when the new process image is executed, any file +descriptor (from this new set) which has its FD_CLOEXEC +flag set shall be closed (see +.IR "\fIposix_spawn\fR\^(\|)"). +.P +The +\fIposix_spawn_file_actions_addclose\fR() +function shall add a +.IR close +action to the object referenced by +.IR file_actions +that shall cause the file descriptor +.IR fildes +to be closed (as if +.IR close (\c +.IR fildes ) +had been called) when a new process is spawned using this file actions +object. +.P +The +\fIposix_spawn_file_actions_addopen\fR() +function shall add an +.IR open +action to the object referenced by +.IR file_actions +that shall cause the file named by +.IR path +to be opened (as if +.IR open (\c +.IR path , +.IR oflag , +.IR mode ) +had been called, and the returned file descriptor, if not +.IR fildes , +had been changed to +.IR fildes ) +when a new process is spawned using this file actions object. If +.IR fildes +was already an open file descriptor, it shall be closed before the new +file is opened. +.P +The string described by +.IR path +shall be copied by the +\fIposix_spawn_file_actions_addopen\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIposix_spawn_file_actions_addopen\fR() +function shall fail if: +.TP +.BR EBADF +The value specified by +.IR fildes +is negative or greater than or equal to +{OPEN_MAX}. +.P +The +\fIposix_spawn_file_actions_addclose\fR() +function shall fail if: +.TP +.BR EBADF +The value specified by +.IR fildes +is negative. +.br +.P +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR file_actions +is invalid. +.TP +.BR ENOMEM +Insufficient memory exists to add to the spawn file actions object. +.P +It shall not be considered an error for the +.IR fildes +argument passed to these functions to specify a file descriptor for +which the specified operation could not be performed at the time of the +call. Any such error will be detected when the associated file actions +object is later used during a +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be provided +on all implementations. +.P +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIposix_spawn_file_actions_addclose\fR() +with an arbitrary integer risks non-conforming behavior, and this +function can only portably be used to close file descriptor values that +the application has obtained through explicit actions, or for the three +file descriptors corresponding to the standard file streams. In order +to avoid a race condition of leaking an unintended file descriptor +into a child process, an application should consider opening all file +descriptors with the FD_CLOEXEC bit set unless the file descriptor is +intended to be inherited across +.IR exec . +.SH RATIONALE +A spawn file actions object may be initialized to contain an ordered +sequence of +\fIclose\fR(), +\fIdup2\fR(), +and +\fIopen\fR() +operations to be used by +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +to arrive at the set of open file descriptors inherited by the spawned +process from the set of open file descriptors in the parent at the time +of the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +call. It had been suggested that the +\fIclose\fR() +and +\fIdup2\fR() +operations alone are sufficient to rearrange file descriptors, and that +files which need to be opened for use by the spawned process can be +handled either by having the calling process open them before the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +call (and close them after), or by passing pathnames to the spawned +process (in +.IR argv ) +so that it may open them itself. The standard developers recommend that +applications use one of these two methods when practical, since +detailed error status on a failed open operation is always available to +the application this way. However, the standard developers feel that +allowing a spawn file actions object to specify open operations is +still appropriate because: +.IP " 1." 4 +It is consistent with equivalent POSIX.5 (Ada) functionality. +.IP " 2." 4 +It supports the I/O redirection paradigm commonly employed by POSIX +programs designed to be invoked from a shell. When such a program is +the child process, it may not be designed to open files on its own. +.IP " 3." 4 +It allows file opens that might otherwise fail or violate file +ownership/access rights if executed by the parent process. +.P +Regarding 2. above, note that the spawn open file action provides to +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +the same capability that the shell redirection operators provide to +\fIsystem\fR(), +only without the intervening execution of a shell; for example: +.sp +.RS 4 +.nf +\fB +system ("myprog \fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_adddup2.3p b/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_adddup2.3p new file mode 100644 index 0000000..80e6de3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_adddup2.3p @@ -0,0 +1,135 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDDUP2 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawn_file_actions_adddup2 +\(em add dup2 action to spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t + *\fIfile_actions\fP, int \fIfildes\fP, int \fInewfildes\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawn_file_actions_adddup2\fR() +function shall add a +\fIdup2\fR() +action to the object referenced by +.IR file_actions +that shall cause the file descriptor +.IR fildes +to be duplicated as +.IR newfildes +(as if +.IR dup2 (\c +.IR fildes , +.IR newfildes ) +had been called) when a new process is spawned using this file actions +object. +.P +A spawn file actions object is as defined in +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_spawn_file_actions_adddup2\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIposix_spawn_file_actions_adddup2\fR() +function shall fail if: +.TP +.BR EBADF +The value specified by +.IR fildes +or +.IR newfildes +is negative or greater than or equal to +{OPEN_MAX}. +.TP +.BR ENOMEM +Insufficient memory exists to add to the spawn file actions object. +.P +The +\fIposix_spawn_file_actions_adddup2\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by +.IR file_actions +is invalid. +.P +It shall not be considered an error for the +.IR fildes +argument passed to the +\fIposix_spawn_file_actions_adddup2\fR() +function to specify a file descriptor for which the specified operation +could not be performed at the time of the call. Any such error will be +detected when the associated file actions object is later used during a +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_spawn_file_actions_adddup2\fR() +function is part of the Spawn option and need not be +provided on all implementations. +.P +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIposix_spawn_file_actions_adddup2\fR() +with an arbitrary integer for +.IR newfildes +risks non-conforming behavior, and this function can only portably be +used to overwrite file descriptor values that the application has obtained +through explicit actions, or for the three file descriptors corresponding +to the standard file streams. In order to avoid a race condition of +leaking an unintended file descriptor into a child process, an application +should consider opening all file descriptors with the FD_CLOEXEC bit +set unless the file descriptor is intended to be inherited across +.IR exec . +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdup\fR\^(\|)", +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_addopen.3p b/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_addopen.3p new file mode 100644 index 0000000..e7657f6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_addopen.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawn_file_actions_addopen +\(em add open action to spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t + *restrict \fIfile_actions\fP, int \fIfildes\fP, + const char *restrict \fIpath\fP, int \fIoflag\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_destroy.3p b/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_destroy.3p new file mode 100644 index 0000000..0039435 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawn_file_actions_destroy.3p @@ -0,0 +1,109 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawn_file_actions_destroy, +posix_spawn_file_actions_init +\(em destroy and initialize spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t + *\fIfile_actions\fP); +int posix_spawn_file_actions_init(posix_spawn_file_actions_t + *\fIfile_actions\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawn_file_actions_destroy\fR() +function shall destroy the object referenced by +.IR file_actions ; +the object becomes, in effect, uninitialized. An implementation may +cause +\fIposix_spawn_file_actions_destroy\fR() +to set the object referenced by +.IR file_actions +to an invalid value. A destroyed spawn file actions object can be +reinitialized using +\fIposix_spawn_file_actions_init\fR(); +the results of otherwise referencing the object after it has been +destroyed are undefined. +.P +The +\fIposix_spawn_file_actions_init\fR() +function shall initialize the object referenced by +.IR file_actions +to contain no file actions for +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +to perform. +.P +A spawn file actions object is as defined in +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.P +The effect of initializing an already initialized spawn file actions +object is undefined. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIposix_spawn_file_actions_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the spawn file actions object. +.P +The +\fIposix_spawn_file_actions_destroy\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by +.IR file_actions +is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.br +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_destroy.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_destroy.3p new file mode 100644 index 0000000..4643049 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_destroy.3p @@ -0,0 +1,151 @@ +'\" et +.TH POSIX_SPAWNATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_destroy, +posix_spawnattr_init +\(em destroy and initialize spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_destroy(posix_spawnattr_t *\fIattr\fP); +int posix_spawnattr_init(posix_spawnattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_destroy\fR() +function shall destroy a spawn attributes object. A destroyed +.IR attr +attributes object can be reinitialized using +\fIposix_spawnattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. An implementation may cause +\fIposix_spawnattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +The +\fIposix_spawnattr_init\fR() +function shall initialize a spawn attributes object +.IR attr +with the default value for all of the individual attributes used by the +implementation. Results are undefined if +\fIposix_spawnattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +A spawn attributes object is of type +.BR posix_spawnattr_t +(defined in +.IR ) +and is used to specify the inheritance of process attributes across a +spawn operation. POSIX.1\(hy2008 does not define comparison or assignment +operators for the type +.BR posix_spawnattr_t . +.P +Each implementation shall document the individual attributes it uses +and their default values unless these values are defined by POSIX.1\(hy2008. +Attributes not defined by POSIX.1\(hy2008, their default values, and the names of +the associated functions to get and set those attribute values are +implementation-defined. +.P +The resulting spawn attributes object (possibly modified by setting +individual attribute values), is used to modify the behavior of +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(). +After a spawn attributes object has been used to spawn a process by a +call to a +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(), +any function affecting the attributes object (including destruction) +shall not affect any process that has been spawned in this way. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_destroy\fR() +and +\fIposix_spawnattr_init\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_spawnattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the spawn attributes object. +.P +The +\fIposix_spawnattr_destroy\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by attr is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +The original spawn interface proposed in POSIX.1\(hy2008 defined the attributes +that specify the inheritance of process attributes across a spawn +operation as a structure. In order to be able to separate optional +individual attributes under their appropriate options (that is, the +.IR spawn-schedparam +and +.IR spawn-schedpolicy +attributes depending upon the Process Scheduling option), and also for +extensibility and consistency with the newer POSIX interfaces, the +attributes interface has been changed to an opaque data type. This +interface now consists of the type +.BR posix_spawnattr_t , +representing a spawn attributes object, together with associated +functions to initialize or destroy the attributes object, and to set or +get each individual attribute. Although the new object-oriented +interface is more verbose than the original structure, it is simple to +use, more extensible, and easy to implement. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_getflags.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_getflags.3p new file mode 100644 index 0000000..e8c2f62 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_getflags.3p @@ -0,0 +1,129 @@ +'\" et +.TH POSIX_SPAWNATTR_GETFLAGS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_getflags, +posix_spawnattr_setflags +\(em get and set the spawn-flags attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_getflags(const posix_spawnattr_t *restrict \fIattr\fP, + short *restrict \fIflags\fP); +int posix_spawnattr_setflags(posix_spawnattr_t *\fIattr\fP, short \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getflags\fR() +function shall obtain the value of the +.IR spawn-flags +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setflags\fR() +function shall set the +.IR spawn-flags +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-flags +attribute is used to indicate which process attributes are to be +changed in the new process image when invoking +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(). +It is the bitwise-inclusive OR of zero or more of the following flags: +.P +.nf +POSIX_SPAWN_RESETIDS +POSIX_SPAWN_SETPGROUP +POSIX_SPAWN_SETSIGDEF +POSIX_SPAWN_SETSIGMASK +POSIX_SPAWN_SETSCHEDPARAM +POSIX_SPAWN_SETSCHEDULER +.fi +.P +These flags are defined in +.IR . +The default value of this attribute shall be as if no flags were set. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getflags\fR() +shall return zero and store the value of the +.IR spawn-flags +attribute of +.IR attr +into the object referenced by the +.IR flags +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setflags\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setflags\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_getpgroup.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_getpgroup.3p new file mode 100644 index 0000000..536077a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_getpgroup.3p @@ -0,0 +1,114 @@ +'\" et +.TH POSIX_SPAWNATTR_GETPGROUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_getpgroup, +posix_spawnattr_setpgroup +\(em get and set the spawn-pgroup attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict \fIattr\fP, + pid_t *restrict \fIpgroup\fP); +int posix_spawnattr_setpgroup(posix_spawnattr_t *\fIattr\fP, pid_t \fIpgroup\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getpgroup\fR() +function shall obtain the value of the +.IR spawn-pgroup +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setpgroup\fR() +function shall set the +.IR spawn-pgroup +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-pgroup +attribute represents the process group to be joined by the new process +image in a spawn operation (if POSIX_SPAWN_SETPGROUP is set in the +.IR spawn-flags +attribute). The default value of this attribute shall be zero. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getpgroup\fR() +shall return zero and store the value of the +.IR spawn-pgroup +attribute of +.IR attr +into the object referenced by the +.IR pgroup +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setpgroup\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setpgroup\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_getschedparam.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_getschedparam.3p new file mode 100644 index 0000000..74c0412 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_getschedparam.3p @@ -0,0 +1,119 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_getschedparam, +posix_spawnattr_setschedparam +\(em get and set the spawn-schedparam attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_getschedparam(const posix_spawnattr_t + *restrict \fIattr\fP, struct sched_param *restrict \fIschedparam\fP); +int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict \fIattr\fP, + const struct sched_param *restrict \fIschedparam\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getschedparam\fR() +function shall obtain the value of the +.IR spawn-schedparam +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setschedparam\fR() +function shall set the +.IR spawn-schedparam +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-schedparam +attribute represents the scheduling parameters to be assigned to the +new process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER or +POSIX_SPAWN_SETSCHEDPARAM is set +in the +.IR spawn-flags +attribute). The default value of this attribute is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getschedparam\fR() +shall return zero and store the value of the +.IR spawn-schedparam +attribute of +.IR attr +into the object referenced by the +.IR schedparam +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setschedparam\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setschedparam\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn and Process Scheduling options +and need not be provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_getschedpolicy.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_getschedpolicy.3p new file mode 100644 index 0000000..8f1262c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_getschedpolicy.3p @@ -0,0 +1,118 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSCHEDPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_getschedpolicy, +posix_spawnattr_setschedpolicy +\(em get and set the spawn-schedpolicy attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_getschedpolicy(const posix_spawnattr_t + *restrict \fIattr\fP, int *restrict \fIschedpolicy\fP); +int posix_spawnattr_setschedpolicy(posix_spawnattr_t *\fIattr\fP, + int \fIschedpolicy\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getschedpolicy\fR() +function shall obtain the value of the +.IR spawn-schedpolicy +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setschedpolicy\fR() +function shall set the +.IR spawn-schedpolicy +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-schedpolicy +attribute represents the scheduling policy to be assigned to the new +process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER is set +in the +.IR spawn-flags +attribute). The default value of this attribute is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getschedpolicy\fR() +shall return zero and store the value of the +.IR spawn-schedpolicy +attribute of +.IR attr +into the object referenced by the +.IR schedpolicy +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setschedpolicy\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setschedpolicy\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn and Process Scheduling options +and need not be provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_getsigdefault.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_getsigdefault.3p new file mode 100644 index 0000000..6aef458 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_getsigdefault.3p @@ -0,0 +1,119 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSIGDEFAULT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_getsigdefault, +posix_spawnattr_setsigdefault +\(em get and set the spawn-sigdefault attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_getsigdefault(const posix_spawnattr_t + *restrict \fIattr\fP, sigset_t *restrict \fIsigdefault\fP); +int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict \fIattr\fP, + const sigset_t *restrict \fIsigdefault\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getsigdefault\fR() +function shall obtain the value of the +.IR spawn-sigdefault +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setsigdefault\fR() +function shall set the +.IR spawn-sigdefault +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-sigdefault +attribute represents the set of signals to be forced to default signal +handling in the new process image (if POSIX_SPAWN_SETSIGDEF is set in +the +.IR spawn-flags +attribute) by a spawn operation. The default value of this attribute +shall be an empty signal set. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getsigdefault\fR() +shall return zero and store the value of the +.IR spawn-sigdefault +attribute of +.IR attr +into the object referenced by the +.IR sigdefault +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setsigdefault\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setsigdefault\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_getsigmask.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_getsigmask.3p new file mode 100644 index 0000000..0a43b27 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_getsigmask.3p @@ -0,0 +1,117 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSIGMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_getsigmask, +posix_spawnattr_setsigmask +\(em get and set the spawn-sigmask attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict \fIattr\fP, + sigset_t *restrict \fIsigmask\fP); +int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict \fIattr\fP, + const sigset_t *restrict \fIsigmask\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getsigmask\fR() +function shall obtain the value of the +.IR spawn-sigmask +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setsigmask\fR() +function shall set the +.IR spawn-sigmask +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-sigmask +attribute represents the signal mask in effect in the new process image +of a spawn operation (if POSIX_SPAWN_SETSIGMASK is set in the +.IR spawn-flags +attribute). The default value of this attribute is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getsigmask\fR() +shall return zero and store the value of the +.IR spawn-sigmask +attribute of +.IR attr +into the object referenced by the +.IR sigmask +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setsigmask\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setsigmask\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_init.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_init.3p new file mode 100644 index 0000000..a088a07 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_init.3p @@ -0,0 +1,39 @@ +'\" et +.TH POSIX_SPAWNATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_init +\(em initialize the spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_init(posix_spawnattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_destroy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_setflags.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_setflags.3p new file mode 100644 index 0000000..43afdb4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_setflags.3p @@ -0,0 +1,39 @@ +'\" et +.TH POSIX_SPAWNATTR_SETFLAGS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_setflags +\(em set the spawn-flags attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_setflags(posix_spawnattr_t *\fIattr\fP, short \fIflags\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getflags\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_setpgroup.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_setpgroup.3p new file mode 100644 index 0000000..cac176e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_setpgroup.3p @@ -0,0 +1,39 @@ +'\" et +.TH POSIX_SPAWNATTR_SETPGROUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_setpgroup +\(em set the spawn-pgroup attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_setpgroup(posix_spawnattr_t *\fIattr\fP, pid_t \fIpgroup\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_setschedparam.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_setschedparam.3p new file mode 100644 index 0000000..e90734c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_setschedparam.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_setschedparam +\(em set the spawn-schedparam attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict \fIattr\fP, + const struct sched_param *restrict \fIschedparam\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_setschedpolicy.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_setschedpolicy.3p new file mode 100644 index 0000000..7aed806 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_setschedpolicy.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSCHEDPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_setschedpolicy +\(em set the spawn-schedpolicy attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_setschedpolicy(posix_spawnattr_t *\fIattr\fP, + int \fIschedpolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_setsigdefault.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_setsigdefault.3p new file mode 100644 index 0000000..c239cec --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_setsigdefault.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSIGDEFAULT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_setsigdefault +\(em set the spawn-sigdefault attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict \fIattr\fP, + const sigset_t *restrict \fIsigdefault\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnattr_setsigmask.3p b/man-pages-posix-2013-a/man3p/posix_spawnattr_setsigmask.3p new file mode 100644 index 0000000..585a103 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnattr_setsigmask.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSIGMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnattr_setsigmask +\(em set the spawn-sigmask attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict \fIattr\fP, + const sigset_t *restrict \fIsigmask\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_spawnp.3p b/man-pages-posix-2013-a/man3p/posix_spawnp.3p new file mode 100644 index 0000000..13db80e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_spawnp.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_SPAWNP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_spawnp +\(em spawn a process +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnp(pid_t *restrict \fIpid\fP, const char *restrict \fIfile\fP, + const posix_spawn_file_actions_t *\fIfile_actions\fP, + const posix_spawnattr_t *restrict \fIattrp\fP, + char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawn\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_destroy.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_destroy.3p new file mode 100644 index 0000000..a17d322 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_destroy.3p @@ -0,0 +1,125 @@ +'\" et +.TH POSIX_TRACE_ATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_destroy, +posix_trace_attr_init +\(em destroy and initialize the trace stream attributes object +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_destroy(trace_attr_t *\fIattr\fP); +int posix_trace_attr_init(trace_attr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_attr_destroy\fR() +function shall destroy an initialized trace attributes object. +A destroyed +.IR attr +attributes object can be reinitialized using +\fIposix_trace_attr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIposix_trace_attr_init\fR() +function shall initialize a trace attributes object +.IR attr +with the default value for all of the individual attributes used by a +given implementation. The read-only +.IR generation-version +and +.IR clock-resolution +attributes of the newly initialized trace attributes object shall be +set to their appropriate values (see +.IR "Section 2.11.1.2" ", " "posix_trace_status_info Structure"). +.P +Results are undefined if +\fIposix_trace_attr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +Implementations may add extensions to the trace attributes object +structure as permitted in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 2" ", " "Conformance". +.P +The resulting attributes object (possibly modified by setting +individual attributes values), when used by +\fIposix_trace_create\fR(), +defines the attributes of the trace stream created. A single +attributes object can be used in multiple calls to +\fIposix_trace_create\fR(). +After one or more trace streams have been created using an attributes +object, any function affecting that attributes object, including +destruction, shall not affect any trace stream previously created. An +initialized attributes object also serves to receive the attributes of +an existing trace stream or trace log when calling the +\fIposix_trace_get_attr\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.SH ERRORS +The +\fIposix_trace_attr_destroy\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR attr +is invalid. +.P +The +\fIposix_trace_attr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the trace attributes object. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_attr_destroy\fR() +and +\fIposix_trace_attr_init\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIuname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_getclockres.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_getclockres.3p new file mode 100644 index 0000000..0806982 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_getclockres.3p @@ -0,0 +1,190 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETCLOCKRES "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_getclockres, +posix_trace_attr_getcreatetime, +posix_trace_attr_getgenversion, +posix_trace_attr_getname, +posix_trace_attr_setname +\(em retrieve and set information about a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_getclockres(const trace_attr_t *\fIattr\fP, + struct timespec *\fIresolution\fP); +int posix_trace_attr_getcreatetime(const trace_attr_t *\fIattr\fP, + struct timespec *\fIcreatetime\fP); +.P +#include +.P +int posix_trace_attr_getgenversion(const trace_attr_t *\fIattr\fP, + char *\fIgenversion\fP); +int posix_trace_attr_getname(const trace_attr_t *\fIattr\fP, + char *\fItracename\fP); +int posix_trace_attr_setname(trace_attr_t *\fIattr\fP, + const char *\fItracename\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_attr_getclockres\fR() +function shall copy the clock resolution of the clock used to generate +timestamps from the +.IR clock-resolution +attribute of the attributes object pointed to by the +.IR attr +argument into the structure pointed to by the +.IR resolution +argument. +.P +The +\fIposix_trace_attr_getcreatetime\fR() +function shall copy the trace stream creation time from the +.IR creation-time +attribute of the attributes object pointed to by the +.IR attr +argument into the structure pointed to by the +.IR createtime +argument. The +.IR creation-time +attribute shall represent the time of creation of the trace stream. +.P +The +\fIposix_trace_attr_getgenversion\fR() +function shall copy the string containing version information from the +.IR generation-version +attribute of the attributes object pointed to by the +.IR attr +argument into the string pointed to by the +.IR genversion +argument. The +.IR genversion +argument shall be the address of a character array which can store at +least +{TRACE_NAME_MAX} +characters. +.P +The +\fIposix_trace_attr_getname\fR() +function shall copy the string containing the trace name from the +.IR trace-name +attribute of the attributes object pointed to by the +.IR attr +argument into the string pointed to by the +.IR tracename +argument. The +.IR tracename +argument shall be the address of a character array which can store at +least +{TRACE_NAME_MAX} +characters. +.P +The +\fIposix_trace_attr_setname\fR() +function shall set the name in the +.IR trace-name +attribute of the attributes object pointed to by the +.IR attr +argument, using the trace name string supplied by the +.IR tracename +argument. If the supplied string contains more than +{TRACE_NAME_MAX} +characters, the name copied into the +.IR trace-name +attribute may be truncated to one less than the length of +{TRACE_NAME_MAX} +characters. The default value is a null string. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +If successful, the +\fIposix_trace_attr_getclockres\fR() +function stores the +.IR clock-resolution +attribute value in the object pointed to by +.IR resolution . +Otherwise, the content of this object is unspecified. +.P +If successful, the +\fIposix_trace_attr_getcreatetime\fR() +function stores the trace stream creation time in the object pointed to +by +.IR createtime . +Otherwise, the content of this object is unspecified. +.P +If successful, the +\fIposix_trace_attr_getgenversion\fR() +function stores the trace version information in the string pointed to +by +.IR genversion . +Otherwise, the content of this string is unspecified. +.P +If successful, the +\fIposix_trace_attr_getname\fR() +function stores the trace name in the string pointed to by +.IR tracename . +Otherwise, the content of this string is unspecified. +.SH ERRORS +The +\fIposix_trace_attr_getclockres\fR(), +\fIposix_trace_attr_getcreatetime\fR(), +\fIposix_trace_attr_getgenversion\fR(), +and +\fIposix_trace_attr_getname\fR() +functions may fail if: +.TP +.BR EINVAL +The value specified by one of the arguments is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_attr_getclockres\fR(), +\fIposix_trace_attr_getcreatetime\fR(), +\fIposix_trace_attr_getgenversion\fR(), +\fIposix_trace_attr_getname\fR(), +and +\fIposix_trace_attr_setname\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIuname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_getinherited.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_getinherited.3p new file mode 100644 index 0000000..ed4c3a0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_getinherited.3p @@ -0,0 +1,277 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETINHERITED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +.ad l +posix_trace_attr_getinherited, +posix_trace_attr_getlogfullpolicy, +posix_trace_attr_getstreamfullpolicy, +posix_trace_attr_setinherited, +posix_trace_attr_setlogfullpolicy, +posix_trace_attr_setstreamfullpolicy +\(em retrieve and set the behavior of a trace stream +(\fBTRACING\fP) +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_getinherited(const trace_attr_t *restrict \fIattr\fP, + int *restrict \fIinheritancepolicy\fP); +int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict \fIattr\fP, + int *restrict \fIlogpolicy\fP); +int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict + \fIattr\fP, int *restrict \fIstreampolicy\fP); +int posix_trace_attr_setinherited(trace_attr_t *\fIattr\fP, + int \fIinheritancepolicy\fP); +int posix_trace_attr_setlogfullpolicy(trace_attr_t *\fIattr\fP, + int \fIlogpolicy\fP); +int posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fIattr\fP, + int \fIstreampolicy\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_attr_getinherited\fR() +and +\fIposix_trace_attr_setinherited\fR() +functions, respectively, shall get and set the inheritance policy +stored in the +.IR inheritance +attribute for traced processes across the +\fIfork\fR() +and +\fIspawn\fR() +operations. The +.IR inheritance +attribute of the attributes object pointed to by the +.IR attr +argument shall be set to one of the following values defined by +manifest constants in the +.IR +header: +.IP POSIX_TRACE_CLOSE_FOR_CHILD 6 +.br +After a +\fIfork\fR() +or +\fIspawn\fR() +operation, the child shall not be traced, and tracing of the parent +shall continue. +.IP POSIX_TRACE_INHERITED 6 +.br +After a +\fIfork\fR() +or +\fIspawn\fR() +operation, if the parent is being traced, its child shall be +concurrently traced using the same trace stream. +.P +The default value for the +.IR inheritance +attribute is POSIX_TRACE_CLOSE_FOR_CHILD. +.P +The +\fIposix_trace_attr_getlogfullpolicy\fR() +and +\fIposix_trace_attr_setlogfullpolicy\fR() +functions, respectively, shall get and set the trace log full policy +stored in the +.IR log-full-policy +attribute of the attributes object pointed to by the +.IR attr +argument. +.P +The +.IR log-full-policy +attribute shall be set to one of the following values defined by +manifest constants in the +.IR +header: +.IP POSIX_TRACE_LOOP 6 +.br +The trace log shall loop until the associated trace stream is stopped. +This policy means that when the trace log gets full, the file system +shall reuse the resources allocated to the oldest trace events that +were recorded. In this way, the trace log will always contain the most +recent trace events flushed. +.IP POSIX_TRACE_UNTIL_FULL 6 +.br +The trace stream shall be flushed to the trace log until the trace log +is full. This condition can be deduced from the +.IR posix_log_full_status +member status (see the +.BR posix_trace_status_info +structure defined in +.IR ). +The last recorded trace event shall be the POSIX_TRACE_STOP trace event. +.IP POSIX_TRACE_APPEND 6 +.br +The associated trace stream shall be flushed to the trace log without +log size limitation. If the application specifies POSIX_TRACE_APPEND, +the implementation shall ignore the +.IR log-max-size +attribute. +.P +The default value for the +.IR log-full-policy +attribute is POSIX_TRACE_LOOP. +.P +The +\fIposix_trace_attr_getstreamfullpolicy\fR() +and +\fIposix_trace_attr_setstreamfullpolicy\fR() +functions, respectively, shall get and set the trace stream full policy +stored in the +.IR stream-full-policy +attribute of the attributes object pointed to by the +.IR attr +argument. +.P +The +.IR stream-full-policy +attribute shall be set to one of the following values defined by +manifest constants in the +.IR +header: +.IP POSIX_TRACE_LOOP 6 +.br +The trace stream shall loop until explicitly stopped by the +\fIposix_trace_stop\fR() +function. This policy means that when the trace stream is full, the +trace system shall reuse the resources allocated to the oldest trace +events recorded. In this way, the trace stream will always contain the +most recent trace events recorded. +.IP POSIX_TRACE_UNTIL_FULL 6 +.br +The trace stream will run until the trace stream resources are +exhausted. Then the trace stream will stop. This condition can be +deduced from +.IR posix_stream_status +and +.IR posix_stream_full_status +(see the +.BR posix_trace_status_info +structure defined in +.IR ). +When this trace stream is read, a POSIX_TRACE_STOP trace +event shall be reported after reporting the last recorded trace event. +The trace system shall reuse the resources allocated to any trace +events already reported\(emsee the +\fIposix_trace_getnext_event\fR(), +\fIposix_trace_trygetnext_event\fR(), +and +\fIposix_trace_timedgetnext_event\fR() +functions\(emor already flushed for an active trace stream with log if +the Trace Log option is supported; see the +\fIposix_trace_flush\fR() +function. The trace system shall restart the trace stream when it is +empty and may restart it sooner. A POSIX_TRACE_START trace event shall +be reported before reporting the next recorded trace event. +.IP POSIX_TRACE_FLUSH 6 +.br +If the Trace Log option is supported, this policy is identical to the +POSIX_TRACE_UNTIL_FULL trace stream full policy except that the trace +stream shall be flushed regularly as if +\fIposix_trace_flush\fR() +had been explicitly called. Defining this policy for an active trace +stream without log shall be invalid. +.P +The default value for the +.IR stream-full-policy +attribute shall be POSIX_TRACE_LOOP for an active trace stream without +log. +.P +If the Trace Log option is supported, the default value for the +.IR stream-full-policy +attribute shall be POSIX_TRACE_FLUSH for an active trace stream with +log. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +If successful, the +\fIposix_trace_attr_getinherited\fR() +function shall store the +.IR inheritance +attribute value in the object pointed to by +.IR inheritancepolicy . +Otherwise, the content of this object is undefined. +.P +If successful, the +\fIposix_trace_attr_getlogfullpolicy\fR() +function shall store the +.IR log-full-policy +attribute value in the object pointed to by +.IR logpolicy . +Otherwise, the content of this object is undefined. +.P +If successful, the +\fIposix_trace_attr_getstreamfullpolicy\fR() +function shall store the +.IR stream-full-policy +attribute value in the object pointed to by +.IR streampolicy . +Otherwise, the content of this object is undefined. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by at least one of the arguments is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The following functions: +.sp +.RS +.nf +\fIposix_trace_attr_getinherited\fR() +\fIposix_trace_attr_getlogfullpolicy\fR() +\fIposix_trace_attr_getstreamfullpolicy\fR() +\fIposix_trace_attr_setinherited\fR() +\fIposix_trace_attr_setlogfullpolicy\fR() +\fIposix_trace_attr_setstreamfullpolicy\fR() +.fi +.RE +.P +may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIfork\fR\^(\|)", +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_getlogsize.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_getlogsize.3p new file mode 100644 index 0000000..35eb2ca --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_getlogsize.3p @@ -0,0 +1,265 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETLOGSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +.ad l +posix_trace_attr_getlogsize, +posix_trace_attr_getmaxdatasize, +posix_trace_attr_getmaxsystemeventsize, +posix_trace_attr_getmaxusereventsize, +posix_trace_attr_getstreamsize, +posix_trace_attr_setlogsize, +posix_trace_attr_setmaxdatasize, +posix_trace_attr_setstreamsize +\(em retrieve and set trace stream size attributes +(\fBTRACING\fP) +.ad b +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_getlogsize(const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fIlogsize\fP); +int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fImaxdatasize\fP); +int posix_trace_attr_getmaxsystemeventsize( + const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fIeventsize\fP); +int posix_trace_attr_getmaxusereventsize( + const trace_attr_t *restrict \fIattr\fP, + size_t \fIdata_len\fP, size_t *restrict \fIeventsize\fP); +int posix_trace_attr_getstreamsize(const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fIstreamsize\fP); +int posix_trace_attr_setlogsize(trace_attr_t *\fIattr\fP, + size_t \fIlogsize\fP); +int posix_trace_attr_setmaxdatasize(trace_attr_t *\fIattr\fP, + size_t \fImaxdatasize\fP); +int posix_trace_attr_setstreamsize(trace_attr_t *\fIattr\fP, + size_t \fIstreamsize\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_attr_getlogsize\fR() +function shall copy the log size, in bytes, from the +.IR log-max-size +attribute of the attributes object pointed to by the +.IR attr +argument into the variable pointed to by the +.IR logsize +argument. This log size is the maximum total of bytes that shall be +allocated for system and user trace events in the trace log. The +default value for the +.IR log-max-size +attribute is implementation-defined. +.P +The +\fIposix_trace_attr_setlogsize\fR() +function shall set the maximum allowed size, in bytes, in the +.IR log-max-size +attribute of the attributes object pointed to by the +.IR attr +argument, using the size value supplied by the +.IR logsize +argument. +.P +The trace log size shall be used if the +.IR log-full-policy +attribute is set to POSIX_TRACE_LOOP or POSIX_TRACE_UNTIL_FULL. If the +.IR log-full-policy +attribute is set to POSIX_TRACE_APPEND, the implementation shall ignore +the +.IR log-max-size +attribute. +.P +The +\fIposix_trace_attr_getmaxdatasize\fR() +function shall copy the maximum user trace event data size, in bytes, +from the +.IR max-data-size +attribute of the attributes object pointed to by the +.IR attr +argument into the variable pointed to by the +.IR maxdatasize +argument. The default value for the +.IR max-data-size +attribute is implementation-defined. +.P +The +\fIposix_trace_attr_getmaxsystemeventsize\fR() +function shall calculate the maximum memory size, in bytes, required to +store a single system trace event. This value is calculated for the +trace stream attributes object pointed to by the +.IR attr +argument and is returned in the variable pointed to by the +.IR eventsize +argument. +.P +The values returned as the maximum memory sizes of the user and system +trace events shall be such that if the sum of the maximum memory sizes +of a set of the trace events that may be recorded in a trace stream is +less than or equal to the +.IR stream-min-size +attribute of that trace stream, the system provides the necessary +resources for recording all those trace events, without loss. +.P +The +\fIposix_trace_attr_getmaxusereventsize\fR() +function shall calculate the maximum memory size, in bytes, required to +store a single user trace event generated by a call to +\fIposix_trace_event\fR() +with a +.IR data_len +parameter equal to the +.IR data_len +value specified in this call. This value is calculated for the trace +stream attributes object pointed to by the +.IR attr +argument and is returned in the variable pointed to by the +.IR eventsize +argument. +.P +The +\fIposix_trace_attr_getstreamsize\fR() +function shall copy the stream size, in bytes, from the +.IR stream-min-size +attribute of the attributes object pointed to by the +.IR attr +argument into the variable pointed to by the +.IR streamsize +argument. +.P +This stream size is the current total memory size reserved for system +and user trace events in the trace stream. The default value for the +.IR stream-min-size +attribute is implementation-defined. The stream size refers to memory +used to store trace event records. Other stream data (for example, +trace attribute values) shall not be included in this size. +.P +The +\fIposix_trace_attr_setmaxdatasize\fR() +function shall set the maximum allowed size, in bytes, in the +.IR max-data-size +attribute of the attributes object pointed to by the +.IR attr +argument, using the size value supplied by the +.IR maxdatasize +argument. This maximum size is the maximum allowed size for the user +data argument which may be passed to +\fIposix_trace_event\fR(). +The implementation shall be allowed to truncate data passed to +.IR trace_user_event +which is longer than +.IR maxdatasize . +.P +The +\fIposix_trace_attr_setstreamsize\fR() +function shall set the minimum allowed size, in bytes, in the +.IR stream-min-size +attribute of the attributes object pointed to by the +.IR attr +argument, using the size value supplied by the +.IR streamsize +argument. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_attr_getlogsize\fR() +function stores the maximum trace log allowed size in the object +pointed to by +.IR logsize , +if successful. +.P +The +\fIposix_trace_attr_getmaxdatasize\fR() +function stores the maximum trace event record memory size in the +object pointed to by +.IR maxdatasize , +if successful. +.P +The +\fIposix_trace_attr_getmaxsystemeventsize\fR() +function stores the maximum memory size to store a single system trace +event in the object pointed to by +.IR eventsize , +if successful. +.P +The +\fIposix_trace_attr_getmaxusereventsize\fR() +function stores the maximum memory size to store a single user trace +event in the object pointed to by +.IR eventsize , +if successful. +.P +The +\fIposix_trace_attr_getstreamsize\fR() +function stores the maximum trace stream allowed size in the object +pointed to by +.IR streamsize , +if successful. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by one of the arguments is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The following functions: +.sp +.RS +.nf +\fIposix_trace_attr_getlogsize\fR() +\fIposix_trace_attr_getmaxdatasize\fR() +\fIposix_trace_attr_getmaxsystemeventsize\fR() +\fIposix_trace_attr_getmaxusereventsize\fR() +\fIposix_trace_attr_getstreamsize\fR() +\fIposix_trace_attr_setlogsize\fR() +\fIposix_trace_attr_setmaxdatasize\fR() +\fIposix_trace_attr_setstreamsize\fR() +.fi +.RE +.P +may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_getname.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_getname.3p new file mode 100644 index 0000000..c18693e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_getname.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_getname +\(em retrieve and set information about a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_getname(const trace_attr_t *\fIattr\fP, + char *\fItracename\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getclockres\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_getstreamfullpolicy.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_getstreamfullpolicy.3p new file mode 100644 index 0000000..24a7b0c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_getstreamfullpolicy.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETSTREAMFULLPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_getstreamfullpolicy +\(em retrieve and set the behavior of a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict + \fIattr\fP, int *restrict \fIstreampolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_getstreamsize.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_getstreamsize.3p new file mode 100644 index 0000000..97dccee --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_getstreamsize.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETSTREAMSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_getstreamsize +\(em retrieve and set trace stream size attributes +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_getstreamsize(const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fIstreamsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getlogsize\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_init.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_init.3p new file mode 100644 index 0000000..9603b4f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_init.3p @@ -0,0 +1,39 @@ +'\" et +.TH POSIX_TRACE_ATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_init +\(em initialize the trace stream attributes object +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_init(trace_attr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_destroy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_setinherited.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_setinherited.3p new file mode 100644 index 0000000..ac33c81 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_setinherited.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETINHERITED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_setinherited, +posix_trace_attr_setlogfullpolicy +\(em retrieve and set the behavior of a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_setinherited(trace_attr_t *\fIattr\fP, + int \fIinheritancepolicy\fP); +int posix_trace_attr_setlogfullpolicy(trace_attr_t *\fIattr\fP, + int \fIlogpolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_setlogsize.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_setlogsize.3p new file mode 100644 index 0000000..c5b7ab1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_setlogsize.3p @@ -0,0 +1,44 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETLOGSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_setlogsize, +posix_trace_attr_setmaxdatasize +\(em retrieve and set trace stream size attributes +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_setlogsize(trace_attr_t *\fIattr\fP, + size_t \fIlogsize\fP); +int posix_trace_attr_setmaxdatasize(trace_attr_t *\fIattr\fP, + size_t \fImaxdatasize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getlogsize\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_setname.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_setname.3p new file mode 100644 index 0000000..23b93fb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_setname.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_setname +\(em retrieve and set information about a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_setname(trace_attr_t *\fIattr\fP, + const char *\fItracename\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getclockres\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_setstreamfullpolicy.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_setstreamfullpolicy.3p new file mode 100644 index 0000000..81c52aa --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_setstreamfullpolicy.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETSTREAMFULLPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_setstreamfullpolicy +\(em retrieve and set the behavior of a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fIattr\fP, + int \fIstreampolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_attr_setstreamsize.3p b/man-pages-posix-2013-a/man3p/posix_trace_attr_setstreamsize.3p new file mode 100644 index 0000000..d08dec9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_attr_setstreamsize.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETSTREAMSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_attr_setstreamsize +\(em retrieve and set trace stream size attributes +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_setstreamsize(trace_attr_t *\fIattr\fP, + size_t \fIstreamsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getlogsize\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_clear.3p b/man-pages-posix-2013-a/man3p/posix_trace_clear.3p new file mode 100644 index 0000000..37669b6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_clear.3p @@ -0,0 +1,125 @@ +'\" et +.TH POSIX_TRACE_CLEAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_clear +\(em clear trace stream and trace log +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_clear(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_clear\fR() +function shall reinitialize the trace stream identified by the argument +.IR trid +as if it were returning from the +\fIposix_trace_create\fR() +function, except that the same allocated resources shall be reused, the +mapping of trace event type identifiers to trace event names shall be +unchanged, and the trace stream status shall remain unchanged (that is, +if it was running, it remains running and if it was suspended, it +remains suspended). +.P +All trace events in the trace stream recorded before the call to +\fIposix_trace_clear\fR() +shall be lost. The +.IR posix_stream_full_status +status shall be set to POSIX_TRACE_NOT_FULL. +There is no guarantee that all trace events that occurred during the +\fIposix_trace_clear\fR() +call are recorded; the behavior with respect to trace points that may +occur during this call is unspecified. +.P +If the Trace Log option is supported and the trace stream has been +created with a log, the +\fIposix_trace_clear\fR() +function shall reinitialize the trace stream with the same behavior as +if the trace stream was created without the log, plus it shall +reinitialize the trace log associated with the trace stream identified +by the argument +.IR trid +as if it were returning from the +\fIposix_trace_create_withlog\fR() +function, except that the same allocated resources, for the trace log, +may be reused and the associated trace stream status remains unchanged. +The first trace event recorded in the trace log after the call to +\fIposix_trace_clear\fR() +shall be the same as the first trace event recorded in the active trace +stream after the call to +\fIposix_trace_clear\fR(). +The +.IR posix_log_full_status +status shall be set to POSIX_TRACE_NOT_FULL. There is no guarantee +that all trace events that occurred during the +\fIposix_trace_clear\fR() +call are recorded in the trace log; the behavior with respect to trace +points that may occur during this call is unspecified. If the log full +policy is POSIX_TRACE_APPEND, the effect of a call to this function is +unspecified for the trace log associated with the trace stream +identified by the +.IR trid +argument. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_trace_clear\fR() +function shall return a value of zero. Otherwise, it shall return the +corresponding error number. +.SH ERRORS +The +\fIposix_trace_clear\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR trid +argument does not correspond to an active trace stream. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_clear\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_close.3p b/man-pages-posix-2013-a/man3p/posix_trace_close.3p new file mode 100644 index 0000000..30d87d1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_close.3p @@ -0,0 +1,173 @@ +'\" et +.TH POSIX_TRACE_CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_close, +posix_trace_open, +posix_trace_rewind +\(em trace log management +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_close(trace_id_t \fItrid\fP); +int posix_trace_open(int \fIfile_desc\fP, trace_id_t *\fItrid\fP); +int posix_trace_rewind(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_close\fR() +function shall deallocate the trace log identifier indicated by +.IR trid , +and all of its associated resources. If there is no valid trace log +pointed to by the +.IR trid , +this function shall fail. +.P +The +\fIposix_trace_open\fR() +function shall allocate the necessary resources and establish the +connection between a trace log identified by the +.IR file_desc +argument and a trace stream identifier identified by the object pointed +to by the +.IR trid +argument. The +.IR file_desc +argument should be a valid open file descriptor that corresponds to a +trace log. The +.IR file_desc +argument shall be open for reading. The current trace event timestamp, +which specifies the timestamp of the trace event that will be read by +the next call to +\fIposix_trace_getnext_event\fR(), +shall be set to the timestamp of the oldest trace event recorded in the +trace log identified by +.IR trid . +.P +The +\fIposix_trace_open\fR() +function shall return a trace stream identifier in the variable +pointed to by the +.IR trid +argument, that may only be used by the following functions: +.TS +tab(!); +l l. +T{ +.nf +\fIposix_trace_close\fR() +\fIposix_trace_eventid_equal\fR() +\fIposix_trace_eventid_get_name\fR() +\fIposix_trace_eventtypelist_getnext_id\fR() +\fIposix_trace_eventtypelist_rewind\fR() +T}!T{ +.nf +\fIposix_trace_get_attr\fR() +\fIposix_trace_get_status\fR() +\fIposix_trace_getnext_event\fR() +\fIposix_trace_rewind\fR() +.fi +T} +.TE +.P +In particular, notice that the operations normally used by a trace +controller process, such as +\fIposix_trace_start\fR(), +\fIposix_trace_stop\fR(), +or +\fIposix_trace_shutdown\fR(), +cannot be invoked using the trace stream identifier returned by the +\fIposix_trace_open\fR() +function. +.P +The +\fIposix_trace_rewind\fR() +function shall reset the current trace event timestamp, which specifies +the timestamp of the trace event that will be read by the next call to +\fIposix_trace_getnext_event\fR(), +to the timestamp of the oldest trace event recorded in the trace log +identified by +.IR trid . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +If successful, the +\fIposix_trace_open\fR() +function stores the trace stream identifier value in the object pointed +to by +.IR trid . +.SH ERRORS +The +\fIposix_trace_open\fR() +function shall fail if: +.TP +.BR EINTR +The operation was interrupted by a signal and thus no trace log was +opened. +.TP +.BR EINVAL +The object pointed to by +.IR file_desc +does not correspond to a valid trace log. +.br +.P +The +\fIposix_trace_close\fR() +and +\fIposix_trace_rewind\fR() +functions may fail if: +.TP +.BR EINVAL +The object pointed to by +.IR trid +does not correspond to a valid trace log. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_close\fR(), +\fIposix_trace_open\fR(), +and +\fIposix_trace_rewind\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIposix_trace_get_filter\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_create.3p b/man-pages-posix-2013-a/man3p/posix_trace_create.3p new file mode 100644 index 0000000..5426601 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_create.3p @@ -0,0 +1,450 @@ +'\" et +.TH POSIX_TRACE_CREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_create, +posix_trace_create_withlog, +posix_trace_flush, +posix_trace_shutdown +\(em trace stream initialization, flush, and shutdown from a process +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_create(pid_t \fIpid\fP, + const trace_attr_t *restrict \fIattr\fP, + trace_id_t *restrict \fItrid\fP); +int posix_trace_create_withlog(pid_t \fIpid\fP, + const trace_attr_t *restrict \fIattr\fP, int \fIfile_desc\fP, + trace_id_t *restrict \fItrid\fP); +int posix_trace_flush(trace_id_t \fItrid\fP); +int posix_trace_shutdown(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_create\fR() +function shall create an active trace stream. It allocates all the +resources needed by the trace stream being created for tracing the +process specified by +.IR pid +in accordance with the +.IR attr +argument. The +.IR attr +argument represents the initial attributes of the trace stream and +shall have been initialized by the function +\fIposix_trace_attr_init\fR() +prior to the +\fIposix_trace_create\fR() +call. If the argument +.IR attr +is NULL, the default attributes shall be used. The +.IR attr +attributes object shall be manipulated through a set of functions +described in the +.IR posix_trace_attr +family of functions. If the attributes of the object pointed to by +.IR attr +are modified later, the attributes of the trace stream shall not be +affected. The +.IR creation-time +attribute of the newly created trace stream shall be set to the value +of the system clock, if the Timers option is not supported, or to the +value of the CLOCK_REALTIME clock, if the Timers option is supported. +.P +The +.IR pid +argument represents the target process to be traced. If the process +executing this function does not have appropriate privileges to trace +the process identified by +.IR pid , +an error shall be returned. If the +.IR pid +argument is zero, the calling process shall be traced. +.P +The +\fIposix_trace_create\fR() +function shall store the trace stream identifier of the new trace +stream in the object pointed to by the +.IR trid +argument. This trace stream identifier shall be used in subsequent +calls to control tracing. The +.IR trid +argument may only be used by the following functions: +.TS +tab(!); +l l. +T{ +.nf +\fIposix_trace_clear\fR() +\fIposix_trace_eventid_equal\fR() +\fIposix_trace_eventid_get_name\fR() +\fIposix_trace_eventtypelist_getnext_id\fR() +\fIposix_trace_eventtypelist_rewind\fR() +\fIposix_trace_get_attr\fR() +\fIposix_trace_get_status\fR() +T}!T{ +.nf +\fIposix_trace_getnext_event\fR() +\fIposix_trace_shutdown\fR() +\fIposix_trace_start\fR() +\fIposix_trace_stop\fR() +\fIposix_trace_timedgetnext_event\fR() +\fIposix_trace_trid_eventid_open\fR() +\fIposix_trace_trygetnext_event\fR() +.fi +T} +.TE +.P +If the Trace Event Filter option is supported, the following additional +functions may use the +.IR trid +argument: +.TS +tab(!); +l l. +T{ +\fIposix_trace_get_filter\fR() +T}!T{ +\fIposix_trace_set_filter\fR() +T} +.TE +.P +In particular, notice that the operations normally used by a trace +analyzer process, such as +\fIposix_trace_rewind\fR() +or +\fIposix_trace_close\fR(), +cannot be invoked using the trace stream identifier returned by the +\fIposix_trace_create\fR() +function. +.P +A trace stream shall be created in a suspended state. +If the Trace Event Filter option is supported, its trace event type +filter shall be empty. +.P +The +\fIposix_trace_create\fR() +function may be called multiple times from the same or different +processes, with the system-wide limit indicated by the runtime +invariant value +{TRACE_SYS_MAX}, +which has the minimum value +{_POSIX_TRACE_SYS_MAX}. +.P +The trace stream identifier returned by the +\fIposix_trace_create\fR() +function in the argument pointed to by +.IR trid +is valid only in the process that made the function call. If it is +used from another process, that is a child process, in functions +defined in POSIX.1\(hy2008, these functions shall return with the error +.BR [EINVAL] . +.P +The +\fIposix_trace_create_withlog\fR() +function shall be equivalent to +\fIposix_trace_create\fR(), +except that it associates a trace log with this stream. The +.IR file_desc +argument shall be the file descriptor designating the trace log +destination. The function shall fail if this file descriptor refers to +a file with a file type that is not compatible with the log policy +associated with the trace log. The list of the appropriate file types +that are compatible with each log policy is implementation-defined. +.P +The +\fIposix_trace_create_withlog\fR() +function shall return in the parameter pointed to by +.IR trid +the trace stream identifier, which uniquely identifies the newly +created trace stream, and shall be used in subsequent calls to control +tracing. The +.IR trid +argument may only be used by the following functions: +.TS +tab(!); +l l. +T{ +.nf +\fIposix_trace_clear\fR() +\fIposix_trace_eventid_equal\fR() +\fIposix_trace_eventid_get_name\fR() +\fIposix_trace_eventtypelist_getnext_id\fR() +\fIposix_trace_eventtypelist_rewind\fR() +\fIposix_trace_flush\fR() +\fIposix_trace_get_attr\fR() +T}!T{ +.nf +\fIposix_trace_get_status\fR() +\fIposix_trace_getnext_event\fR() +\fIposix_trace_shutdown\fR() +\fIposix_trace_start\fR() +\fIposix_trace_stop\fR() +\fIposix_trace_timedgetnext_event\fR() +\fIposix_trace_trid_eventid_open\fR() +.fi +T} +.TE +.P +If the Trace Event Filter option is supported, the following additional +functions may use the +.IR trid +argument: +.TS +tab(!); +l l. +T{ +\fIposix_trace_get_filter\fR() +T}!T{ +\fIposix_trace_set_filter\fR() +T} +.TE +.P +In particular, notice that the operations normally used by a trace +analyzer process, such as +\fIposix_trace_rewind\fR() +or +\fIposix_trace_close\fR(), +cannot be invoked using the trace stream identifier returned by the +\fIposix_trace_create_withlog\fR() +function. +.P +The +\fIposix_trace_flush\fR() +function shall initiate a flush operation which copies the contents of +the trace stream identified by the argument +.IR trid +into the trace log associated with the trace stream at the creation +time. If no trace log has been associated with the trace stream +pointed to by +.IR trid , +this function shall return an error. The termination of the flush +operation can be polled by the +\fIposix_trace_get_status\fR() +function. During the flush operation, it shall be possible to trace +new trace events up to the point when the trace stream becomes full. +After flushing is completed, the space used by the flushed trace events +shall be available for tracing new trace events. +.P +If flushing the trace stream causes the resulting trace log to become +full, the trace log full policy shall be applied. If the trace +.IR log-full-policy +attribute is set, the following occurs: +.IP POSIX_TRACE_UNTIL_FULL 6 +.br +The trace events that have not yet been flushed shall be discarded. +.IP POSIX_TRACE_LOOP 6 +.br +The trace events that have not yet been flushed shall be written to the +beginning of the trace log, overwriting previous trace events stored +there. +.IP POSIX_TRACE_APPEND 6 +.br +The trace events that have not yet been flushed shall be appended to the +trace log. +.P +The +\fIposix_trace_shutdown\fR() +function shall stop the tracing of trace events in the trace stream +identified by +.IR trid , +as if +\fIposix_trace_stop\fR() +had been invoked. The +\fIposix_trace_shutdown\fR() +function shall free all the resources associated with the trace +stream. +.P +The +\fIposix_trace_shutdown\fR() +function shall not return until all the resources associated with the +trace stream have been freed. When the +\fIposix_trace_shutdown\fR() +function returns, the +.IR trid +argument becomes an invalid trace stream identifier. A call to this +function shall unconditionally deallocate the resources regardless of +whether all trace events have been retrieved by the analyzer process. +Any thread blocked on one of the +\fItrace_getnext_event\fR() +functions (which specified this +.IR trid ) +before this call is unblocked with the error +.BR [EINVAL] . +.P +If the process exits, invokes a member of the +.IR exec +family of functions, or is terminated, the trace streams that the +process had created and that have not yet been shut down, shall be +automatically shut down as if an explicit call were made to the +\fIposix_trace_shutdown\fR() +function. +.P +For an active trace stream with log, when the +\fIposix_trace_shutdown\fR() +function is called, all trace events that have not yet been flushed to +the trace log shall be flushed, as in the +\fIposix_trace_flush\fR() +function, and the trace log shall be closed. +.P +When a trace log is closed, all the information that may be retrieved +later from the trace log through the trace interface shall have been +written to the trace log. This information includes the trace +attributes, the list of trace event types (with the mapping between +trace event names and trace event type identifiers), and the trace +status. +.P +In addition, unspecified information shall be written to the trace +log to allow detection of a valid trace log during the +\fIposix_trace_open\fR() +operation. +.P +The +\fIposix_trace_shutdown\fR() +function shall not return until all trace events have been flushed. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_create\fR() +and +\fIposix_trace_create_withlog\fR() +functions store the trace stream identifier value in the object +pointed to by +.IR trid , +if successful. +.SH ERRORS +The +\fIposix_trace_create\fR() +and +\fIposix_trace_create_withlog\fR() +functions shall fail if: +.TP +.BR EAGAIN +No more trace streams can be started now. +{TRACE_SYS_MAX} +has been exceeded. +.TP +.BR EINTR +The operation was interrupted by a signal. No trace stream was +created. +.TP +.BR EINVAL +One or more of the trace parameters specified by the +.IR attr +parameter is invalid. +.TP +.BR ENOMEM +The implementation does not currently have sufficient memory to create +the trace stream with the specified parameters. +.TP +.BR EPERM +The caller does not have appropriate privileges to trace the process +specified by +.IR pid . +.TP +.BR ESRCH +The +.IR pid +argument does not refer to an existing process. +.P +The +\fIposix_trace_create_withlog\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR file_desc +argument is not a valid file descriptor open for writing. +.TP +.BR EINVAL +The +.IR file_desc +argument refers to a file with a file type that does not support the +log policy associated with the trace log. +.TP +.BR ENOSPC +No space left on device. The device corresponding to the argument +.IR file_desc +does not contain the space required to create this trace log. +.P +The +\fIposix_trace_flush\fR() +and +\fIposix_trace_shutdown\fR() +functions shall fail if: +.TP +.BR EINVAL +The value of the +.IR trid +argument does not correspond to an active trace stream with log. +.TP +.BR EFBIG +The trace log file has attempted to exceed an implementation-defined +maximum file size. +.TP +.BR ENOSPC +No space left on device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_create\fR(), +\fIposix_trace_create_withlog\fR(), +\fIposix_trace_flush\fR(), +and +\fIposix_trace_shutdown\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_clear\fR\^(\|)", +.IR "\fIposix_trace_close\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_eventtypelist_getnext_id\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIposix_trace_get_filter\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_event.3p b/man-pages-posix-2013-a/man3p/posix_trace_event.3p new file mode 100644 index 0000000..2210a16 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_event.3p @@ -0,0 +1,178 @@ +'\" et +.TH POSIX_TRACE_EVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_event, +posix_trace_eventid_open +\(em trace functions for instrumenting application code +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +void posix_trace_event(trace_event_id_t \fIevent_id\fP, + const void *restrict \fIdata_ptr\fP, size_t \fIdata_len\fP); +int posix_trace_eventid_open(const char *restrict \fIevent_name\fP, + trace_event_id_t *restrict \fIevent_id\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_event\fR() +function shall record the +.IR event_id +and the user data pointed to by +.IR data_ptr +in the trace stream into which the calling process is being traced and +in which +.IR event_id +is not filtered out. If the total size of the user trace event data +represented by +.IR data_len +is not greater than the declared maximum size for user trace event +data, then the +.IR truncation-status +attribute of the trace event recorded is POSIX_TRACE_NOT_TRUNCATED. +Otherwise, the user trace event data is truncated to this declared +maximum size and the +.IR truncation-status +attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD. +.P +If there is no trace stream created for the process or if the created +trace stream is not running, or if the trace event specified by +.IR event_id +is filtered out in the trace stream, the +\fIposix_trace_event\fR() +function shall have no effect. +.P +The +\fIposix_trace_eventid_open\fR() +function shall associate a user trace event name with a trace +event type identifier for the calling process. The trace event name is +the string pointed to by the argument +.IR event_name . +It shall have a maximum of +{TRACE_EVENT_NAME_MAX} +characters (which has the minimum value +{_POSIX_TRACE_EVENT_NAME_MAX}). +The number of user trace event type identifiers that can be defined for +any given process is limited by the maximum value +{TRACE_USER_EVENT_MAX}, +which has the minimum value +{POSIX_TRACE_USER_EVENT_MAX}. +.P +If the Trace Inherit option is not supported, the +\fIposix_trace_eventid_open\fR() +function shall associate the user trace event name pointed to by the +.IR event_name +argument with a trace event type identifier that is unique for the +traced process, and is returned in the variable pointed to by the +.IR event_id +argument. If the user trace event name has already been mapped for the +traced process, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace event name +limit represented by +{TRACE_USER_EVENT_MAX} +has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see +.IR "Table 2-7" ", " "Trace Option: User Trace Event") +user trace event shall be returned. +.P +If the Trace Inherit option is supported, the +\fIposix_trace_eventid_open\fR() +function shall associate the user trace event name pointed to by the +.IR event_name +argument with a trace event type identifier that is unique for all the +processes being traced in this same trace stream, and is returned in +the variable pointed to by the +.IR event_id +argument. If the user trace event name has already been mapped for the +traced processes, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace event name +limit represented by +{TRACE_USER_EVENT_MAX} +has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (\c +.IR "Table 2-7" ", " "Trace Option: User Trace Event") +user trace event shall be returned. +.TP 10 +.BR Note: +The above procedure, together with the fact that multiple processes can +only be traced into the same trace stream by inheritance, ensure that +all the processes that are traced into a trace stream have the same +mapping of trace event names to trace event type identifiers. +.P +.P +If there is no trace stream created, the +\fIposix_trace_eventid_open\fR() +function shall store this information for future trace streams created +for this process. +.SH "RETURN VALUE" +No return value is defined for the +\fIposix_trace_event\fR() +function. +.P +Upon successful completion, the +\fIposix_trace_eventid_open\fR() +function shall return a value of zero. Otherwise, it shall return the +corresponding error number. The +\fIposix_trace_eventid_open\fR() +function stores the trace event type identifier value in the object +pointed to by +.IR event_id , +if successful. +.SH ERRORS +The +\fIposix_trace_eventid_open\fR() +function shall fail if: +.TP +.BR ENAMETOOLONG +.br +The size of the name pointed to by the +.IR event_name +argument was longer than the implementation-defined value +{TRACE_EVENT_NAME_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_event\fR() +and +\fIposix_trace_eventid_open\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "Table 2-7" ", " "Trace Option: User Trace Event", +.IR "\fIexec\fR\^", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_eventid_equal.3p b/man-pages-posix-2013-a/man3p/posix_trace_eventid_equal.3p new file mode 100644 index 0000000..959708c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_eventid_equal.3p @@ -0,0 +1,225 @@ +'\" et +.TH POSIX_TRACE_EVENTID_EQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_eventid_equal, +posix_trace_eventid_get_name, +posix_trace_trid_eventid_open +\(em manipulate the trace event type identifier +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_eventid_equal(trace_id_t \fItrid\fP, trace_event_id_t \fIevent1\fP, + trace_event_id_t \fIevent2\fP); +int posix_trace_eventid_get_name(trace_id_t \fItrid\fP, + trace_event_id_t \fIevent\fP, char *\fIevent_name\fP); +int posix_trace_trid_eventid_open(trace_id_t \fItrid\fP, + const char *restrict \fIevent_name\fP, + trace_event_id_t *restrict \fIevent\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_eventid_equal\fR() +function shall compare the trace event type identifiers +.IR event1 +and +.IR event2 +from the same trace stream or the same trace log identified by the +.IR trid +argument. If the trace event type identifiers +.IR event1 +and +.IR event2 +are from different trace streams, the return value shall be +unspecified. +.P +The +\fIposix_trace_eventid_get_name\fR() +function shall return, in the argument pointed to by +.IR event_name , +the trace event name associated with the trace event type identifier +identified by the argument +.IR event , +for the trace stream or for the trace log identified by the +.IR trid +argument. The name of the trace event shall have a maximum of +{TRACE_EVENT_NAME_MAX} +characters (which has the minimum value +{_POSIX_TRACE_EVENT_NAME_MAX}). +Successive calls to this function with the same trace event type +identifier and the same trace stream identifier shall return the same +event name. +.P +The +\fIposix_trace_trid_eventid_open\fR() +function shall associate a user trace event name with a trace +event type identifier for a given trace stream. The trace stream is +identified by the +.IR trid +argument, and it shall be an active trace stream. The trace event name +is the string pointed to by the argument +.IR event_name . +It shall have a maximum of +{TRACE_EVENT_NAME_MAX} +characters (which has the minimum value +{_POSIX_TRACE_EVENT_NAME_MAX}). +The number of user trace event type identifiers that can be defined for +any given process is limited by the maximum value +{TRACE_USER_EVENT_MAX}, +which has the minimum value +{_POSIX_TRACE_USER_EVENT_MAX}. +.P +If the Trace Inherit option is not supported, the +\fIposix_trace_trid_eventid_open\fR() +function shall associate the user trace event name pointed to by the +.IR event_name +argument with a trace event type identifier that is unique for the +process being traced in the trace stream identified by the +.IR trid +argument, and is returned in the variable pointed to by the +.IR event +argument. If the user trace event name has already been mapped for the +traced process, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace event name +limit represented by +{TRACE_USER_EVENT_MAX} +has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see +.IR "Table 2-7" ", " "Trace Option: User Trace Event") +user trace event shall be returned. +.P +If the Trace Inherit option is supported, the +\fIposix_trace_trid_eventid_open\fR() +function shall associate the user trace event name pointed to by the +.IR event_name +argument with a trace event type identifier that is unique for all the +processes being traced in the trace stream identified by the +.IR trid +argument, and is returned in the variable pointed to by the +.IR event +argument. If the user trace event name has already been mapped for the +traced processes, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace event name +limit represented by +{TRACE_USER_EVENT_MAX} +has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see +.IR "Table 2-7" ", " "Trace Option: User Trace Event") +user trace event shall be returned. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_trace_eventid_get_name\fR() +and +\fIposix_trace_trid_eventid_open\fR() +functions shall return a value of zero. Otherwise, they shall return +the corresponding error number. +.P +The +\fIposix_trace_eventid_equal\fR() +function shall return a non-zero value if +.IR event1 +and +.IR event2 +are equal; otherwise, a value of zero shall be returned. No errors are +defined. If either +.IR event1 +or +.IR event2 +are not valid trace event type identifiers for the trace stream +specified by +.IR trid +or if the +.IR trid +is invalid, the behavior shall be unspecified. +.P +The +\fIposix_trace_eventid_get_name\fR() +function stores the trace event name value in the object pointed to by +.IR event_name , +if successful. +.P +The +\fIposix_trace_trid_eventid_open\fR() +function stores the trace event type identifier value in the object +pointed to by +.IR event , +if successful. +.SH ERRORS +The +\fIposix_trace_eventid_get_name\fR() +and +\fIposix_trace_trid_eventid_open\fR() +functions shall fail if: +.TP +.BR EINVAL +The +.IR trid +argument was not a valid trace stream identifier. +.P +The +\fIposix_trace_trid_eventid_open\fR() +function shall fail if: +.TP +.BR ENAMETOOLONG +.br +The size of the name pointed to by the +.IR event_name +argument was longer than the implementation-defined value +{TRACE_EVENT_NAME_MAX}. +.P +The +\fIposix_trace_eventid_get_name\fR() +function shall fail if: +.TP +.BR EINVAL +The trace event type identifier +.IR event +was not associated with any name. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_eventid_equal\fR(), +\fIposix_trace_eventid_get_name\fR(), +and +\fIposix_trace_trid_eventid_open\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "Table 2-7" ", " "Trace Option: User Trace Event", +.IR "\fIexec\fR\^", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_eventid_open.3p b/man-pages-posix-2013-a/man3p/posix_trace_eventid_open.3p new file mode 100644 index 0000000..1f95039 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_eventid_open.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_EVENTID_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_eventid_open +\(em trace functions for instrumenting application code +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_eventid_open(const char *restrict \fIevent_name\fP, + trace_event_id_t *restrict \fIevent_id\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_event\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_eventset_add.3p b/man-pages-posix-2013-a/man3p/posix_trace_eventset_add.3p new file mode 100644 index 0000000..90598e5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_eventset_add.3p @@ -0,0 +1,155 @@ +'\" et +.TH POSIX_TRACE_EVENTSET_ADD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +.ad l +posix_trace_eventset_add, +posix_trace_eventset_del, +posix_trace_eventset_empty, +posix_trace_eventset_fill, +posix_trace_eventset_ismember +\(em manipulate trace event type sets +(\fBTRACING\fP) +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_eventset_add(trace_event_id_t \fIevent_id\fP, + trace_event_set_t *\fIset\fP); +int posix_trace_eventset_del(trace_event_id_t \fIevent_id\fP, + trace_event_set_t *\fIset\fP); +int posix_trace_eventset_empty(trace_event_set_t *\fIset\fP); +int posix_trace_eventset_fill(trace_event_set_t *\fIset\fP, int \fIwhat\fP); +int posix_trace_eventset_ismember(trace_event_id_t \fIevent_id\fP, + const trace_event_set_t *restrict \fIset\fP, int *restrict \fIismember\fP); +.fi +.SH DESCRIPTION +These primitives manipulate sets of trace event types. They operate on +data objects addressable by the application, not on the current trace +event filter of any trace stream. +.P +The +\fIposix_trace_eventset_add\fR() +and +\fIposix_trace_eventset_del\fR() +functions, respectively, shall add or delete the individual trace event +type specified by the value of the argument +.IR event_id +to or from the trace event type set pointed to by the argument +.IR set . +Adding a trace event type already in the set or deleting a trace event +type not in the set shall not be considered an error. +.P +The +\fIposix_trace_eventset_empty\fR() +function shall initialize the trace event type set pointed to by the +.IR set +argument such that all trace event types defined, both system and user, +shall be excluded from the set. +.P +The +\fIposix_trace_eventset_fill\fR() +function shall initialize the trace event type set pointed to by the +argument +.IR set , +such that the set of trace event types defined by the argument +.IR what +shall be included in the set. The value of the argument +.IR what +shall consist of one of the following values, as defined in the +.IR +header: +.IP POSIX_TRACE_WOPID_EVENTS 6 +.br +All the process-independent implementation-defined system trace event +types are included in the set. +.IP POSIX_TRACE_SYSTEM_EVENTS 6 +.br +All the implementation-defined system trace event types are included in +the set, as are those defined in POSIX.1\(hy2008. +.IP POSIX_TRACE_ALL_EVENTS 6 +.br +All trace event types defined, both system and user, are included in +the set. +.P +Applications shall call either +\fIposix_trace_eventset_empty\fR() +or +\fIposix_trace_eventset_fill\fR() +at least once for each object of type +.BR trace_event_set_t +prior to any other use of that object. If such an object is not +initialized in this way, but is nonetheless supplied as an argument to +any of the +\fIposix_trace_eventset_add\fR(), +\fIposix_trace_eventset_del\fR(), +or +\fIposix_trace_eventset_ismember\fR() +functions, the results are undefined. +.P +The +\fIposix_trace_eventset_ismember\fR() +function shall test whether the trace event type specified by the value +of the argument +.IR event_id +is a member of the set pointed to by the argument +.IR set . +The value returned in the object pointed to by +.IR ismember +argument is zero if the trace event type identifier is not a member of +the set and a value different from zero if it is a member of the set. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value of one of the arguments is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_eventset_add\fR(), +\fIposix_trace_eventset_del\fR(), +\fIposix_trace_eventset_empty\fR(), +\fIposix_trace_eventset_fill\fR(), +and +\fIposix_trace_eventset_ismember\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_get_filter\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_eventtypelist_getnext_id.3p b/man-pages-posix-2013-a/man3p/posix_trace_eventtypelist_getnext_id.3p new file mode 100644 index 0000000..bb2340a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_eventtypelist_getnext_id.3p @@ -0,0 +1,109 @@ +'\" et +.TH POSIX_TRACE_EVENTTYPELIST_GETNEXT_ID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_eventtypelist_getnext_id, +posix_trace_eventtypelist_rewind +\(em iterate over a mapping of trace event types +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_eventtypelist_getnext_id(trace_id_t \fItrid\fP, + trace_event_id_t *restrict \fIevent\fP, int *restrict \fIunavailable\fP); +int posix_trace_eventtypelist_rewind(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The first time +\fIposix_trace_eventtypelist_getnext_id\fR() +is called, the function shall return in the variable pointed to by +.IR event +the first trace event type identifier of the list of trace events of +the trace stream identified by the +.IR trid +argument. Successive calls to +\fIposix_trace_eventtypelist_getnext_id\fR() +return in the variable pointed to by +.IR event +the next trace event type identifier in that same list. Each time a +trace event type identifier is successfully written into the variable +pointed to by the +.IR event +argument, the variable pointed to by the +.IR unavailable +argument shall be set to zero. When no more trace event type +identifiers are available, and so none is returned, the variable +pointed to by the +.IR unavailable +argument shall be set to a value different from zero. +.P +The +\fIposix_trace_eventtypelist_rewind\fR() +function shall reset the next trace event type identifier to be read to +the first trace event type identifier from the list of trace events +used in the trace stream identified by +.IR trid . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_eventtypelist_getnext_id\fR() +function stores the trace event type identifier value in the object +pointed to by +.IR event , +if successful. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The +.IR trid +argument was not a valid trace stream identifier. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_eventtypelist_getnext_id\fR() +and +\fIposix_trace_eventtypelist_rewind\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_flush.3p b/man-pages-posix-2013-a/man3p/posix_trace_flush.3p new file mode 100644 index 0000000..023c4cf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_flush.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_FLUSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_flush +\(em trace stream flush from a process +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_flush(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_create\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_get_attr.3p b/man-pages-posix-2013-a/man3p/posix_trace_get_attr.3p new file mode 100644 index 0000000..2ad5e72 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_get_attr.3p @@ -0,0 +1,138 @@ +'\" et +.TH POSIX_TRACE_GET_ATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_get_attr, +posix_trace_get_status +\(em retrieve the trace attributes or trace status +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_get_attr(trace_id_t \fItrid\fP, trace_attr_t *\fIattr\fP); +int posix_trace_get_status(trace_id_t \fItrid\fP, + struct posix_trace_status_info *\fIstatusinfo\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_get_attr\fR() +function shall copy the attributes of the active trace stream +identified by +.IR trid +into the object pointed to by the +.IR attr +argument. +If the Trace Log option is supported, +.IR trid +may represent a pre-recorded trace log. +.P +The +\fIposix_trace_get_status\fR() +function shall return, in the structure pointed to by the +.IR statusinfo +argument, the current trace status for the trace stream identified by +the +.IR trid +argument. These status values returned in the structure pointed to by +.IR statusinfo +shall have been appropriately read to ensure that the returned values +are consistent. +If the Trace Log option is supported and the +.IR trid +argument refers to a pre-recorded trace stream, the status shall be the +status of the completed trace stream. +.P +Each time the +\fIposix_trace_get_status\fR() +function is used, the overrun status of the trace stream shall be reset +to POSIX_TRACE_NO_OVERRUN +immediately after the call completes. +If the Trace Log option is supported, the +\fIposix_trace_get_status\fR() +function shall behave the same as when the option is not supported +except for the following differences: +.IP " *" 4 +If the +.IR trid +argument refers to a trace stream with log, each time the +\fIposix_trace_get_status\fR() +function is used, the log overrun status of the trace stream shall be +reset to POSIX_TRACE_NO_OVERRUN and the +.IR flush_error +status shall be reset to zero immediately after the call completes. +.IP " *" 4 +If the +.IR trid +argument refers to a pre-recorded trace stream, the status returned +shall be the status of the completed trace stream and the status values +of the trace stream shall not be reset. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_get_attr\fR() +function stores the trace attributes in the object pointed to by +.IR attr , +if successful. +.P +The +\fIposix_trace_get_status\fR() +function stores the trace status in the object pointed to by +.IR statusinfo , +if successful. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The trace stream argument +.IR trid +does not correspond to a valid active trace stream or a valid trace +log. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_get_attr\fR() +and +\fIposix_trace_get_status\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_close\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_get_filter.3p b/man-pages-posix-2013-a/man3p/posix_trace_get_filter.3p new file mode 100644 index 0000000..1e92c37 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_get_filter.3p @@ -0,0 +1,143 @@ +'\" et +.TH POSIX_TRACE_GET_FILTER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_get_filter, +posix_trace_set_filter +\(em retrieve and set the filter of an initialized trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_get_filter(trace_id_t \fItrid\fP, trace_event_set_t *\fIset\fP); +int posix_trace_set_filter(trace_id_t \fItrid\fP, + const trace_event_set_t *\fIset\fP, int \fIhow\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_get_filter\fR() +function shall retrieve, into the argument pointed to by +.IR set , +the actual trace event filter from the trace stream specified by +.IR trid . +.P +The +\fIposix_trace_set_filter\fR() +function shall change the set of filtered trace event types after a +trace stream identified by the +.IR trid +argument is created. This function may be called prior to starting the +trace stream, or while the trace stream is active. By default, if no +call is made to +\fIposix_trace_set_filter\fR(), +all trace events shall be recorded (that is, none of the trace event +types are filtered out). +.P +If this function is called while the trace is in progress, a special +system trace event, POSIX_TRACE_FILTER, +shall be recorded in the trace indicating both the old and the new sets +of filtered trace event types (see +.IR "Table 2-4" ", " "Trace and Trace Event Filter Options: System Trace Events" +and +.IR "Table 2-6" ", " "Trace" ", " "Trace Log" ", " "and Trace Event Filter Options: System Trace Events"). +.P +If the +\fIposix_trace_set_filter\fR() +function is interrupted by a signal, an error shall be returned and the +filter shall not be changed. In this case, the state of the trace +stream shall not be changed. +.P +The value of the argument +.IR how +indicates the manner in which the set is to be changed and shall have +one of the following values, as defined in the +.IR +header: +.IP POSIX_TRACE_SET_EVENTSET 6 +.br +The resulting set of trace event types to be filtered shall be the +trace event type set pointed to by the argument +.IR set . +.IP POSIX_TRACE_ADD_EVENTSET 6 +.br +The resulting set of trace event types to be filtered shall be the +union of the current set and the trace event type set pointed to by the +argument +.IR set . +.IP POSIX_TRACE_SUB_EVENTSET 6 +.br +The resulting set of trace event types to be filtered shall be all +trace event types in the current set that are not in the set pointed to +by the argument +.IR set ; +that is, remove each element of the specified set from the current +filter. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_get_filter\fR() +function stores the set of filtered trace event types in +.IR set , +if successful. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of the +.IR trid +argument does not correspond to an active trace stream or the value of +the argument pointed to by +.IR set +is invalid. +.TP +.BR EINTR +The operation was interrupted by a signal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_get_filter\fR() +and +\fIposix_trace_set_filter\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "Table 2-4" ", " "Trace and Trace Event Filter Options: System Trace Events", +.IR "Table 2-6" ", " "Trace" ", " "Trace Log" ", " "and Trace Event Filter Options: System Trace Events", +.IR "\fIposix_trace_eventset_add\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_get_status.3p b/man-pages-posix-2013-a/man3p/posix_trace_get_status.3p new file mode 100644 index 0000000..df67bdd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_get_status.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_GET_STATUS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_get_status +\(em retrieve the trace status +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_get_status(trace_id_t \fItrid\fP, + struct posix_trace_status_info *\fIstatusinfo\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_get_attr\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_getnext_event.3p b/man-pages-posix-2013-a/man3p/posix_trace_getnext_event.3p new file mode 100644 index 0000000..581ed23 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_getnext_event.3p @@ -0,0 +1,265 @@ +'\" et +.TH POSIX_TRACE_GETNEXT_EVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_getnext_event, +posix_trace_timedgetnext_event, +posix_trace_trygetnext_event +\(em retrieve a trace event +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_getnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP); +int posix_trace_timedgetnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP, + const struct timespec *restrict \fIabstime\fP); +int posix_trace_trygetnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_getnext_event\fR() +function shall report a recorded trace event either from an +active trace stream without log +or a pre-recorded trace stream identified by the +.IR trid +argument. +The +\fIposix_trace_trygetnext_event\fR() +function shall report a recorded trace event from an active +trace stream without log identified by the +.IR trid +argument. +.P +The trace event information associated with the recorded trace event +shall be copied by the function into the structure pointed to by the +argument +.IR event +and the data associated with the trace event shall be copied into the +buffer pointed to by the +.IR data +argument. +.P +The +\fIposix_trace_getnext_event\fR() +function shall block if the +.IR trid +argument identifies an active trace stream and there is currently no +trace event ready to be retrieved. When returning, if a recorded trace +event was reported, the variable pointed to by the +.IR unavailable +argument shall be set to zero. Otherwise, the variable pointed to by +the +.IR unavailable +argument shall be set to a value different from zero. +.P +The +\fIposix_trace_timedgetnext_event\fR() +function shall attempt to get another trace event from an active trace +stream without log, as in the +\fIposix_trace_getnext_event\fR() +function. However, if no trace event is available from the trace +stream, the implied wait shall be terminated when the timeout specified +by the argument +.IR abstime +expires, and the function shall return the error +.BR [ETIMEDOUT] . +.P +The timeout shall expire when the absolute time specified by +.IR abstime +passes, as measured by the clock upon which timeouts are based (that +is, when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock +on which it is based. The +.BR timespec +data type is defined in the +.IR +header. +.P +Under no circumstance shall the function fail with a timeout if a trace +event is immediately available from the trace stream. The validity of +the +.IR abstime +argument need not be checked if a trace event is immediately available +from the trace stream. +.P +The behavior of this function for a pre-recorded trace stream is +unspecified. +.P +The +\fIposix_trace_trygetnext_event\fR() +function shall not block. +This function shall return an error if the +.IR trid +argument identifies a pre-recorded trace stream. +If a recorded trace event was reported, the variable pointed to by the +.IR unavailable +argument shall be set to zero. Otherwise, if no trace event was +reported, the variable pointed to by the +.IR unavailable +argument shall be set to a value different from zero. +.P +The argument +.IR num_bytes +shall be the size of the buffer pointed to by the +.IR data +argument. The argument +.IR data_len +reports to the application the length in bytes of the data record just +transferred. If +.IR num_bytes +is greater than or equal to the size of the data associated with the +trace event pointed to by the +.IR event +argument, all the recorded data shall be transferred. In this case, +the +.IR truncation-status +member of the trace event structure shall be either +POSIX_TRACE_NOT_TRUNCATED, +if the trace event data was recorded without truncation while tracing, +or POSIX_TRACE_TRUNCATED_RECORD, +if the trace event data was truncated when it was recorded. If the +.IR num_bytes +argument is less than the length of recorded trace event data, the data +transferred shall be truncated to a length of +.IR num_bytes , +the value stored in the variable pointed to by +.IR data_len +shall be equal to +.IR num_bytes , +and the +.IR truncation-status +member of the +.IR event +structure argument shall be set to POSIX_TRACE_TRUNCATED_READ +(see the +.BR posix_trace_event_info +structure defined in +.IR ). +.P +The report of a trace event shall be sequential starting from the +oldest recorded trace event. Trace events shall be reported in the +order in which they were generated, up to an implementation-defined +time resolution that causes the ordering of trace events occurring very +close to each other to be unknown. Once reported, a trace event cannot +be reported again from an active trace stream. Once a trace event is +reported from an active trace stream without log, the trace stream +shall make the resources associated with that trace event available to +record future generated trace events. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +If successful, these functions store: +.IP " *" 4 +The recorded trace event in the object pointed to by +.IR event +.IP " *" 4 +The trace event information associated with the recorded trace event in +the object pointed to by +.IR data +.IP " *" 4 +The length of this trace event information in the object pointed to by +.IR data_len +.IP " *" 4 +The value of zero in the object pointed to by +.IR unavailable +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The trace stream identifier argument +.IR trid +is invalid. +.P +The +\fIposix_trace_getnext_event\fR() +and +\fIposix_trace_timedgetnext_event\fR() +functions shall fail if: +.TP +.BR EINTR +The operation was interrupted by a signal, and so the call had no +effect. +.P +The +\fIposix_trace_trygetnext_event\fR() +function shall fail if: +.TP +.BR EINVAL +The trace stream identifier argument +.IR trid +does not correspond to an active trace stream. +.br +.P +The +\fIposix_trace_timedgetnext_event\fR() +function shall fail if: +.TP +.BR EINVAL +There is no trace event immediately available from the trace stream, +and the +.IR timeout +argument is invalid. +.TP +.BR ETIMEDOUT +No trace event was available from the trace stream before the specified +timeout +.IR timeout +expired. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_close\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_open.3p b/man-pages-posix-2013-a/man3p/posix_trace_open.3p new file mode 100644 index 0000000..651daa6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_open.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_open, +posix_trace_rewind +\(em trace log management +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_open(int \fIfile_desc\fP, trace_id_t *\fItrid\fP); +int posix_trace_rewind(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_close\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_set_filter.3p b/man-pages-posix-2013-a/man3p/posix_trace_set_filter.3p new file mode 100644 index 0000000..100175c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_set_filter.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_SET_FILTER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_set_filter +\(em set filter of an initialized trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_set_filter(trace_id_t \fItrid\fP, + const trace_event_set_t *\fIset\fP, int \fIhow\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_get_filter\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_shutdown.3p b/man-pages-posix-2013-a/man3p/posix_trace_shutdown.3p new file mode 100644 index 0000000..834f182 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_shutdown.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_SHUTDOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_shutdown +\(em trace stream shutdown from a process +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_shutdown(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_create\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_start.3p b/man-pages-posix-2013-a/man3p/posix_trace_start.3p new file mode 100644 index 0000000..4f7b14a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_start.3p @@ -0,0 +1,103 @@ +'\" et +.TH POSIX_TRACE_START "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_start, +posix_trace_stop +\(em trace start and stop +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_start(trace_id_t \fItrid\fP); +int posix_trace_stop (trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_start\fR() +and +\fIposix_trace_stop\fR() +functions, respectively, shall start and stop the trace stream +identified by the argument +.IR trid . +.P +The effect of calling the +\fIposix_trace_start\fR() +function shall be recorded in the trace stream as the POSIX_TRACE_START +system trace event and the status of the trace stream shall become +POSIX_TRACE_RUNNING. +If the trace stream is in progress when this function is called, the +POSIX_TRACE_START +system trace event shall not be recorded and the trace stream shall +continue to run. If the trace stream is full, the POSIX_TRACE_START +system trace event shall not be recorded and the status of the trace +stream shall not be changed. +.P +The effect of calling the +\fIposix_trace_stop\fR() +function shall be recorded in the trace stream as the POSIX_TRACE_STOP +system trace event and the status of the trace stream shall become +POSIX_TRACE_SUSPENDED. +If the trace stream is suspended when this function is called, the +POSIX_TRACE_STOP system trace event shall not be recorded and the trace +stream shall remain suspended. If the trace stream is full, the +POSIX_TRACE_STOP system trace event shall not be recorded and the +status of the trace stream shall not be changed. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of the argument +.IR trid +does not correspond to an active trace stream and thus no trace stream +was started or stopped. +.TP +.BR EINTR +The operation was interrupted by a signal and thus the trace stream was +not necessarily started or stopped. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_start\fR() +and +\fIposix_trace_stop\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_timedgetnext_event.3p b/man-pages-posix-2013-a/man3p/posix_trace_timedgetnext_event.3p new file mode 100644 index 0000000..7d37ac6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_timedgetnext_event.3p @@ -0,0 +1,44 @@ +'\" et +.TH POSIX_TRACE_TIMEDGETNEXT_EVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_timedgetnext_event +\(em retrieve a trace event +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_timedgetnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_getnext_event\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_trid_eventid_open.3p b/man-pages-posix-2013-a/man3p/posix_trace_trid_eventid_open.3p new file mode 100644 index 0000000..1021014 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_trid_eventid_open.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_TRID_EVENTID_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_trid_eventid_open +\(em open a trace event type identifier +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_trid_eventid_open(trace_id_t \fItrid\fP, + const char *restrict \fIevent_name\fP, + trace_event_id_t *restrict \fIevent\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_eventid_equal\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_trace_trygetnext_event.3p b/man-pages-posix-2013-a/man3p/posix_trace_trygetnext_event.3p new file mode 100644 index 0000000..6e55b78 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_trace_trygetnext_event.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_TRYGETNEXT_EVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_trace_trygetnext_event +\(em retrieve a trace event +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_trygetnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_getnext_event\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_typed_mem_get_info.3p b/man-pages-posix-2013-a/man3p/posix_typed_mem_get_info.3p new file mode 100644 index 0000000..218ffbb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_typed_mem_get_info.3p @@ -0,0 +1,142 @@ +'\" et +.TH POSIX_TYPED_MEM_GET_INFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_typed_mem_get_info +\(em query typed memory information +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_typed_mem_get_info(int \fIfildes\fP, + struct posix_typed_mem_info *\fIinfo\fP); +.fi +.SH DESCRIPTION +The +\fIposix_typed_mem_get_info\fR() +function shall return, in the +.IR posix_tmi_length +field of the +.BR posix_typed_mem_info +structure pointed to by +.IR info , +the maximum length which may be successfully allocated by the typed +memory object designated by +.IR fildes . +This maximum length shall take into account the flag +POSIX_TYPED_MEM_ALLOCATE or POSIX_TYPED_MEM_ALLOCATE_CONTIG specified +when the typed memory object represented by +.IR fildes +was opened. The maximum length is dynamic; therefore, the value +returned is valid only while the current mapping of the corresponding +typed memory pool remains unchanged. +.P +If +.IR fildes +represents a typed memory object opened with neither the +POSIX_TYPED_MEM_ALLOCATE flag nor the POSIX_TYPED_MEM_ALLOCATE_CONTIG +flag specified, the returned value of \fIinfo\fR->\fIposix_tmi_length\fR +is unspecified. +.P +The +\fIposix_typed_mem_get_info\fR() +function may return additional implementation-defined information in +other fields of the +.BR posix_typed_mem_info +structure pointed to by +.IR info . +.P +If the memory object specified by +.IR fildes +is not a typed memory object, then the behavior of this function is +undefined. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_typed_mem_get_info\fR() +function shall return zero; otherwise, the corresponding error status +value shall be returned. +.SH ERRORS +The +\fIposix_typed_mem_get_info\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR ENODEV +The +.IR fildes +argument is not connected to a memory object supported by this +function. +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +An application that needs to allocate a block of typed memory with +length dependent upon the amount of memory currently available must +either query the typed memory object to obtain the amount available, or +repeatedly invoke +\fImmap\fR() +attempting to guess an appropriate length. While the latter method is +existing practice with +\fImalloc\fR(), +it is awkward and imprecise. The +\fIposix_typed_mem_get_info\fR() +function allows an application to immediately determine available +memory. This is particularly important for typed memory objects that +may in some cases be scarce resources. Note that when a typed memory +pool is a shared resource, some form of mutual-exclusion or +synchronization may be required while typed memory is being queried and +allocated to prevent race conditions. +.P +The existing +\fIfstat\fR() +function is not suitable for this purpose. We realize that +implementations may wish to provide other attributes of typed memory +objects (for example, alignment requirements, page size, and so on). +The +\fIfstat\fR() +function returns a structure which is not extensible and, furthermore, +contains substantial information that is inappropriate for typed memory +objects. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfstat\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/posix_typed_mem_open.3p b/man-pages-posix-2013-a/man3p/posix_typed_mem_open.3p new file mode 100644 index 0000000..8b27a8f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/posix_typed_mem_open.3p @@ -0,0 +1,275 @@ +'\" et +.TH POSIX_TYPED_MEM_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +posix_typed_mem_open +\(em open a typed memory object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_typed_mem_open(const char *\fIname\fP, int \fIoflag\fP, int \fItflag\fP); +.fi +.SH DESCRIPTION +The +\fIposix_typed_mem_open\fR() +function shall establish a connection between the typed memory object +specified by the string pointed to by +.IR name +and a file descriptor. It shall create an open file description that +refers to the typed memory object and a file descriptor that refers to +that open file description. The file descriptor is used by other functions +to refer to that typed memory object. It is unspecified whether the name +appears in the file system and is visible to other functions that take +pathnames as arguments. The +.IR name +argument conforms to the construction rules for a pathname, except that +the interpretation of + +characters other than the leading + +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as the +pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the + +character, then processes calling +\fIposix_typed_mem_open\fR() +with the same value of +.IR name +shall refer to the same typed memory object. If +.IR name +does not begin with the + +character, the effect is implementation-defined. +.P +Each typed memory object supported in a system shall be identified by a name +which specifies not only its associated typed memory pool, but also the +path or port by which it is accessed. That is, the same typed memory +pool accessed via several different ports shall have several different +corresponding names. The binding between names and typed memory objects +is established in an implementation-defined manner. Unlike shared +memory objects, there is no way within POSIX.1\(hy2008 for a program to create a +typed memory object. +.P +The value of +.IR tflag +shall determine how the typed memory object behaves when subsequently +mapped by calls to +\fImmap\fR(). +At most, one of the following flags defined in +.IR +may be specified: +.IP POSIX_TYPED_MEM_ALLOCATE 6 +.br +Allocate on +\fImmap\fR(). +.IP POSIX_TYPED_MEM_ALLOCATE_CONTIG 6 +.br +Allocate contiguously on +\fImmap\fR(). +.IP POSIX_TYPED_MEM_MAP_ALLOCATABLE 6 +.br +Map on +\fImmap\fR(), +without affecting allocatability. +.P +If +.IR tflag +has the flag POSIX_TYPED_MEM_ALLOCATE specified, any subsequent call to +\fImmap\fR() +using the returned file descriptor shall result in allocation and +mapping of typed memory from the specified typed memory pool. The +allocated memory may be a contiguous previously unallocated area of the +typed memory pool or several non-contiguous previously unallocated +areas (mapped to a contiguous portion of the process address space). If +.IR tflag +has the flag POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent +call to +\fImmap\fR() +using the returned file descriptor shall result in allocation and +mapping of a single contiguous previously unallocated area of the typed +memory pool (also mapped to a contiguous portion of the process address +space). If +.IR tflag +has none of the flags POSIX_TYPED_MEM_ALLOCATE or +POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent call to +\fImmap\fR() +using the returned file descriptor shall map an application-chosen area +from the specified typed memory pool such that this mapped area becomes +unavailable for allocation until unmapped by all processes. If +.IR tflag +has the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE specified, any subsequent +call to +\fImmap\fR() +using the returned file descriptor shall map an application-chosen area +from the specified typed memory pool without an effect on the +availability of that area for allocation; that is, mapping such an +object leaves each byte of the mapped area unallocated if it was +unallocated prior to the mapping or allocated if it was allocated prior +to the mapping. Appropriate privileges to specify the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag are implementation-defined. +.P +If successful, +\fIposix_typed_mem_open\fR() +shall return a file descriptor for the typed memory object that is the +lowest numbered file descriptor not currently open for that process. +The open file description is new, and therefore the file descriptor +shall not share it with any other processes. It is unspecified whether +the file offset is set. The FD_CLOEXEC file descriptor flag associated +with the new file descriptor shall be cleared. +.P +The behavior of +\fImsync\fR(), +\fIftruncate\fR(), +and all file operations other than +\fImmap\fR(), +\fIposix_mem_offset\fR(), +\fIposix_typed_mem_get_info\fR(), +\fIfstat\fR(), +\fIdup\fR(), +\fIdup2\fR(), +and +\fIclose\fR(), +is unspecified when passed a file descriptor connected to a typed +memory object by this function. +.P +The file status flags of the open file description shall be set +according to the value of +.IR oflag . +Applications shall specify exactly one of the three access mode values +described below and defined in the +.IR +header, as the value of +.IR oflag . +.IP O_RDONLY 12 +Open for read access only. +.IP O_WRONLY 12 +Open for write access only. +.IP O_RDWR 12 +Open for read or write access. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_typed_mem_open\fR() +function shall return a non-negative integer representing the lowest +numbered unused file descriptor. Otherwise, it shall return \(mi1 and +set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIposix_typed_mem_open\fR() +function shall fail if: +.TP +.BR EACCES +The typed memory object exists and the permissions specified by +.IR oflag +are denied. +.TP +.BR EINTR +The +\fIposix_typed_mem_open\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +.ad l +The flags specified in +.IR tflag +are invalid (more than one of POSIX_TYPED_MEM_ALLOCATE, +POSIX_TYPED_MEM_ALLOCATE_CONTIG, or POSIX_TYPED_MEM_MAP_ALLOCATABLE is +specified). +.ad b +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +Too many file descriptors are currently open in the system. +.TP +.BR ENOENT +The named typed memory object does not exist. +.TP +.BR EPERM +The caller lacks appropriate privileges to specify the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag in the +.IR tflag +argument. +.P +The +\fIposix_typed_mem_open\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclose\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfstat\fR\^(\|)", +.IR "\fIftruncate\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fImsync\fR\^(\|)", +.IR "\fIposix_mem_offset\fR\^(\|)", +.IR "\fIposix_typed_mem_get_info\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pow.3p b/man-pages-posix-2013-a/man3p/pow.3p new file mode 100644 index 0000000..e91ba28 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pow.3p @@ -0,0 +1,315 @@ +'\" et +.TH POW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pow, +powf, +powl +\(em power function +.SH SYNOPSIS +.LP +.nf +#include +.P +double pow(double \fIx\fP, double \fIy\fP); +float powf(float \fIx\fP, float \fIy\fP); +long double powl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the value of +.IR x +raised to the power +.IR y , +.IR x\u\s-3y\s+3\d . +If +.IR x +is negative, the application shall ensure that +.IR y +is an integer value. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the value of +.IR x +raised to the power +.IR y . +.P +For finite values of +.IR x +< 0, and finite non-integer values of +.IR y , +a domain error shall occur and +either a NaN (if representable), or +an implementation-defined value shall be returned. +.P +If the correct value would cause overflow, a range error shall occur +and +\fIpow\fR(), +\fIpowf\fR(), +and +\fIpowl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, +respectively, with the same sign as the correct value of the function. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIpow\fR(), +\fIpowf\fR(), +and +\fIpowl\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, and LDBL_MIN, +respectively. +.P +For +.IR y +< 0, if +.IR x +is zero, a +pole +error may occur and +\fIpow\fR(), +\fIpowf\fR(), +and +\fIpowl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, respectively. +On systems that support the IEC 60559 Floating-Point option, if +.IR x +is \(+-0, a pole error shall occur and +\fIpow\fR(), +\fIpowf\fR(), +and +\fIpowl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, respectively +if +.IR y +is an odd integer, or HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively if +.IR y +is not an odd integer. +.P +If +.IR x +or +.IR y +is a NaN, a NaN shall be returned (unless specified elsewhere in this +description). +.P +For any value of +.IR y +(including NaN), if +.IR x +is +1, 1.0 shall be returned. +.P +For any value of +.IR x +(including NaN), if +.IR y +is \(+-0, 1.0 shall be returned. +.P +For any odd integer value of +.IR y +> 0, if +.IR x +is \(+-0, \(+-0 shall be returned. +.P +For +.IR y +> 0 and not an odd integer, if +.IR x +is \(+-0, +0 shall be returned. +.P +If +.IR x +is \(mi1, and +.IR y +is \(+-Inf, 1.0 shall be returned. +.P +For |\fIx\fP| < 1, if +.IR y +is \(miInf, +Inf shall be returned. +.P +For |\fIx\fP| > 1, if +.IR y +is \(miInf, +0 shall be returned. +.P +For |\fIx\fP| < 1, if +.IR y +is +Inf, +0 shall be returned. +.P +For |\fIx\fP| > 1, if +.IR y +is +Inf, +Inf shall be returned. +.P +For +.IR y +an odd integer < 0, if +.IR x +is \(miInf, \(mi0 shall be returned. +.P +For +.IR y +< 0 and not an odd integer, if +.IR x +is \(miInf, +0 shall be returned. +.P +For +.IR y +an odd integer > 0, if +.IR x +is \(miInf, \(miInf shall be returned. +.P +For +.IR y +> 0 and not an odd integer, if +.IR x +is \(miInf, +Inf shall be returned. +.P +For +.IR y +< 0, if +.IR x +is +Inf, +0 shall be returned. +.P +For +.IR y +> 0, if +.IR x +is +Inf, +Inf shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is negative and +.IR y +is a finite non-integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero and +.IR y +is negative. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Pole\ Error" 12 +The value of +.IR x +is zero and +.IR y +is negative. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pread.3p b/man-pages-posix-2013-a/man3p/pread.3p new file mode 100644 index 0000000..8f6ff64 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pread.3p @@ -0,0 +1,38 @@ +'\" et +.TH PREAD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pread +\(em read from a file +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t pread(int \fIfildes\fP, void *\fIbuf\fP, size_t \fInbyte\fP, off_t \fIoffset\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIread\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/printf.3p b/man-pages-posix-2013-a/man3p/printf.3p new file mode 100644 index 0000000..743c4be --- /dev/null +++ b/man-pages-posix-2013-a/man3p/printf.3p @@ -0,0 +1,38 @@ +'\" et +.TH PRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +printf +\(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int printf(const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pselect.3p b/man-pages-posix-2013-a/man3p/pselect.3p new file mode 100644 index 0000000..5a74faa --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pselect.3p @@ -0,0 +1,504 @@ +'\" et +.TH PSELECT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pselect, +select +\(em synchronous I/O multiplexing +.SH SYNOPSIS +.LP +.nf +#include +.P +int pselect(int \fInfds\fP, fd_set *restrict \fIreadfds\fP, + fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP, + const struct timespec *restrict \fItimeout\fP, + const sigset_t *restrict \fIsigmask\fP); +int select(int \fInfds\fP, fd_set *restrict \fIreadfds\fP, + fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP, + struct timeval *restrict \fItimeout\fP); +void FD_CLR(int \fIfd\fP, fd_set *\fIfdset\fP); +int FD_ISSET(int \fIfd\fP, fd_set *\fIfdset\fP); +void FD_SET(int \fIfd\fP, fd_set *\fIfdset\fP); +void FD_ZERO(fd_set *\fIfdset\fP); +.fi +.SH DESCRIPTION +The +\fIpselect\fR() +function shall examine the file descriptor sets whose addresses are +passed in the +.IR readfds , +.IR writefds , +and +.IR errorfds +parameters to see whether some of their descriptors are ready for reading, +are ready for writing, or have an exceptional condition pending, +respectively. +.P +The +\fIselect\fR() +function shall be equivalent to the +\fIpselect\fR() +function, except as follows: +.IP " *" 4 +For the +\fIselect\fR() +function, the timeout period is given in seconds and microseconds in an +argument of type +.BR "struct timeval" , +whereas for the +\fIpselect\fR() +function the timeout period is given in seconds and nanoseconds in an +argument of type +.BR "struct timespec" . +.IP " *" 4 +The +\fIselect\fR() +function has no +.IR sigmask +argument; it shall behave as +\fIpselect\fR() +does when +.IR sigmask +is a null pointer. +.IP " *" 4 +Upon successful completion, the +\fIselect\fR() +function may modify the object pointed to by the +.IR timeout +argument. +.P +The +\fIpselect\fR() +and +\fIselect\fR() +functions shall support regular files, terminal and pseudo-terminal +devices, +STREAMS-based files, +FIFOs, pipes, and sockets. The behavior of +\fIpselect\fR() +and +\fIselect\fR() +on file descriptors that refer to other types of file is unspecified. +.P +The +.IR nfds +argument specifies the range of descriptors to be tested. The first +.IR nfds +descriptors shall be checked in each set; that is, the descriptors from +zero through +.IR nfds \(mi1 +in the descriptor sets shall be examined. +.P +If the +.IR readfds +argument is not a null pointer, it points to an object of type +.BR fd_set +that on input specifies the file descriptors to be checked for being +ready to read, and on output indicates which file descriptors are ready +to read. +.P +If the +.IR writefds +argument is not a null pointer, it points to an object of type +.BR fd_set +that on input specifies the file descriptors to be checked for being +ready to write, and on output indicates which file descriptors are +ready to write. +.P +If the +.IR errorfds +argument is not a null pointer, it points to an object of type +.BR fd_set +that on input specifies the file descriptors to be checked for error +conditions pending, and on output indicates which file descriptors have +error conditions pending. +.P +Upon successful completion, the +\fIpselect\fR() +or +\fIselect\fR() +function shall modify the objects pointed to by the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments to indicate which file descriptors are ready for reading, +ready for writing, or have an error condition pending, respectively, +and shall return the total number of ready descriptors in all the +output sets. For each file descriptor less than +.IR nfds , +the corresponding bit shall be set upon successful completion if it +was set on input and the associated condition is true for that file +descriptor. +.P +If none of the selected descriptors are ready for the requested +operation, the +\fIpselect\fR() +or +\fIselect\fR() +function shall block until at least one of the requested operations +becomes ready, until the +.IR timeout +occurs, or until interrupted by a signal. +The +.IR timeout +parameter controls how long the +\fIpselect\fR() +or +\fIselect\fR() +function shall take before timing out. If the +.IR timeout +parameter is not a null pointer, it specifies a maximum interval to +wait for the selection to complete. If the specified time interval +expires without any requested operation becoming ready, the function +shall return. If the +.IR timeout +parameter is a null pointer, then the call to +\fIpselect\fR() +or +\fIselect\fR() +shall block indefinitely until at least one descriptor meets the +specified criteria. To effect a poll, the +.IR timeout +parameter should not be a null pointer, and should point to a +zero-valued +.BR timespec +structure. +.P +The use of a timeout does not affect any pending timers set up by +\fIalarm\fR() +or +\fIsetitimer\fR(). +.P +Implementations may place limitations on the maximum timeout interval +supported. All implementations shall support a maximum timeout interval +of at least 31 days. If the +.IR timeout +argument specifies a timeout interval greater than the +implementation-defined maximum value, the maximum value shall be used +as the actual timeout value. Implementations may also place limitations +on the granularity of timeout intervals. If the requested timeout +interval requires a finer granularity than the implementation supports, +the actual timeout interval shall be rounded up to the next supported +value. +.P +If +.IR sigmask +is not a null pointer, then the +\fIpselect\fR() +function shall replace the signal mask of the caller by the set of +signals pointed to by +.IR sigmask +before examining the descriptors, and shall restore the signal mask of +the calling thread before returning. +.P +A descriptor shall be considered ready for reading when a call to an +input function with O_NONBLOCK clear would not block, whether or not +the function would transfer data successfully. (The function might +return data, an end-of-file indication, or an error other than one +indicating that it is blocked, and in each of these cases the +descriptor shall be considered ready for reading.) +.P +A descriptor shall be considered ready for writing when a call to an +output function with O_NONBLOCK clear would not block, whether or not +the function would transfer data successfully. +.P +If a socket has a pending error, it shall be considered to have an +exceptional condition pending. Otherwise, what constitutes an +exceptional condition is file type-specific. For a file descriptor for +use with a socket, it is protocol-specific except as noted below. For +other file types it is implementation-defined. If the operation is +meaningless for a particular file type, +\fIpselect\fR() +or +\fIselect\fR() +shall indicate that the descriptor is ready for read or write +operations, and shall indicate that the descriptor has no exceptional +condition pending. +.P +If a descriptor refers to a socket, the implied input function is the +\fIrecvmsg\fR() +function with parameters requesting normal and ancillary data, such +that the presence of either type shall cause the socket to be marked as +readable. The presence of out-of-band data shall be checked if the +socket option SO_OOBINLINE has been enabled, as out-of-band data is +enqueued with normal data. If the socket is currently listening, then +it shall be marked as readable if an incoming connection request has +been received, and a call to the +\fIaccept\fR() +function shall complete without blocking. +.P +If a descriptor refers to a socket, the implied output function is the +\fIsendmsg\fR() +function supplying an amount of normal data equal to the current value +of the SO_SNDLOWAT option for the socket. If a non-blocking call to +the +\fIconnect\fR() +function has been made for a socket, and the connection attempt has +either succeeded or failed leaving a pending error, the socket shall be +marked as writable. +.P +A socket shall be considered to have an exceptional condition pending +if a receive operation with O_NONBLOCK clear for the open file +description and with the MSG_OOB flag set would return out-of-band data +without blocking. (It is protocol-specific whether the MSG_OOB flag +would be used to read out-of-band data.) A socket shall also be +considered to have an exceptional condition pending if an out-of-band +data mark is present in the receive queue. Other circumstances under +which a socket may be considered to have an exceptional condition +pending are protocol-specific and implementation-defined. +.P +If the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments are all null pointers and the +.IR timeout +argument is not a null pointer, the +\fIpselect\fR() +or +\fIselect\fR() +function shall block for the time specified, or until interrupted by +a signal. If the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments are all null pointers and the +.IR timeout +argument is a null pointer, the +\fIpselect\fR() +or +\fIselect\fR() +function shall block until interrupted by a signal. +.P +File descriptors associated with regular files shall always select true +for ready to read, ready to write, and error conditions. +.P +On failure, the objects pointed to by the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments shall not be modified. If the timeout interval expires +without the specified condition being true for any of the specified +file descriptors, the objects pointed to by the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments shall have all bits set to 0. +.P +File descriptor masks of type +.BR fd_set +can be initialized and tested with +\fIFD_CLR\fR(), +\fIFD_ISSET\fR(), +\fIFD_SET\fR(), +and +\fIFD_ZERO\fR(). +It is unspecified whether each of these is a macro or a function. If a +macro definition is suppressed in order to access an actual function, +or a program defines an external identifier with any of these names, +the behavior is undefined. +.P +\fIFD_CLR\fR(\fIfd\fR, \fIfdsetp\fR) shall remove the file descriptor +.IR fd +from the set pointed to by +.IR fdsetp . +If +.IR fd +is not a member of this set, there shall be no effect on the set, nor +will an error be returned. +.P +\fIFD_ISSET\fR(\fIfd\fR, \fIfdsetp\fR) shall evaluate to non-zero if +the file descriptor +.IR fd +is a member of the set pointed to by +.IR fdsetp , +and shall evaluate to zero otherwise. +.P +\fIFD_SET\fR(\fIfd\fR, \fIfdsetp\fR) shall add the file descriptor +.IR fd +to the set pointed to by +.IR fdsetp . +If the file descriptor +.IR fd +is already in this set, there shall be no effect on the set, nor will +an error be returned. +.P +\fIFD_ZERO\fR(\fIfdsetp\fR) shall initialize the descriptor set pointed +to by +.IR fdsetp +to the null set. No error is returned if the set is not empty at the +time +\fIFD_ZERO\fR() +is invoked. +.P +The behavior of these macros is undefined if the +.IR fd +argument is less than 0 or greater than or equal to FD_SETSIZE, or if +.IR fd +is not a valid file descriptor, or if any of the arguments are +expressions with side-effects. +.P +If a thread gets canceled during a +\fIpselect\fR() +call, the signal mask in effect when executing the registered cleanup +functions is either the original signal mask or the signal mask +installed as part of the +\fIpselect\fR() +call. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpselect\fR() +and +\fIselect\fR() +functions shall return the total number of bits set in the bit masks. +Otherwise, \(mi1 shall be returned, and +.IR errno +shall be set to indicate the error. +.P +\fIFD_CLR\fR(), +\fIFD_SET\fR(), +and +\fIFD_ZERO\fR() +do not return a value. +\fIFD_ISSET\fR() +shall return a non-zero value if the bit for the file descriptor +.IR fd +is set in the file descriptor set pointed to by +.IR fdset , +and 0 otherwise. +.SH ERRORS +Under the following conditions, +\fIpselect\fR() +and +\fIselect\fR() +shall fail and set +.IR errno +to: +.TP +.BR EBADF +One or more of the file descriptor sets specified a file descriptor +that is not a valid open file descriptor. +.TP +.BR EINTR +The function was interrupted before any of the selected events occurred +and before the timeout interval expired. +.RS 12 +.P +If SA_RESTART has been set for the interrupting signal, it is +implementation-defined whether the function restarts or returns with +.BR [EINTR] . +.RE +.TP +.BR EINVAL +An invalid timeout interval was specified. +.TP +.BR EINVAL +The +.IR nfds +argument is less than 0 or greater than FD_SETSIZE. +.TP +.BR EINVAL +One of the specified file descriptors refers to a STREAM or multiplexer +that is linked (directly or indirectly) downstream from a multiplexer. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +In earlier versions of the Single UNIX Specification, the +\fIselect\fR() +function was defined in the +.IR +header. This is now changed to +.IR . +The rationale for this change was as follows: the introduction of the +\fIpselect\fR() +function included the +.IR +header and the +.IR +header defines all the related definitions for the +\fIpselect\fR() +and +\fIselect\fR() +functions. Backwards-compatibility to existing XSI implementations is +handled by allowing +.IR +to include +.IR . +.P +Code which wants to avoid the ambiguity of the signal mask for thread +cancellation handlers can install an additional cancellation handler +which resets the signal mask to the expected value. +.sp +.RS 4 +.nf +\fB +void cleanup(void *arg) +{ + sigset_t *ss = (sigset_t *) arg; + pthread_sigmask(SIG_SETMASK, ss, NULL); +} +.P +int call_pselect(int nfds, fd_set *readfds, fd_set *writefds, + fd_set errorfds, const struct timespec *timeout, + const sigset_t *sigmask) +{ + sigset_t oldmask; + int result; + pthread_sigmask(SIG_SETMASK, NULL, &oldmask); + pthread_cleanup_push(cleanup, &oldmask); + result = pselect(nfds, readfds, writefds, errorfds, timeout, sigmask); + pthread_cleanup_pop(0); + return result; +} +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIalarm\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/psiginfo.3p b/man-pages-posix-2013-a/man3p/psiginfo.3p new file mode 100644 index 0000000..723d9cd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/psiginfo.3p @@ -0,0 +1,175 @@ +'\" et +.TH PSIGINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +psiginfo, psignal +\(em print signal information to standard error +.SH SYNOPSIS +.LP +.nf +#include +.P +void psiginfo(const siginfo_t *\fIpinfo\fP, const char *\fImessage\fP); +void psignal(int \fIsignum\fP, const char *\fImessage\fP); +.fi +.SH DESCRIPTION +The +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall print a message out on +.IR stderr +associated with a signal number. If +.IR message +is not null and is not the empty string, then the string pointed to by +the +.IR message +argument shall be printed first, followed by a +, +a +, +and the signal description string indicated by +.IR signum , +or by the signal associated with +.IR pinfo . +If the +.IR message +argument is null or points to an empty string, then only the signal +description shall be printed. For +\fIpsiginfo\fR(), +the argument +.IR pinfo +references a valid +.BR siginfo_t +structure. For +\fIpsignal\fR(), +if +.IR signum +is not a valid signal number, the behavior is implementation-defined. +.P +The +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall not change the orientation of the standard error stream. +.P +The +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall mark for update the last data modification and last file +status change timestamps of the file associated with the standard error +stream at some time between their successful completion and +\fIexit\fR(), +\fIabort\fR(), +or the completion of +\fIfflush\fR() +or +\fIfclose\fR() +on +.IR stderr . +.P +The +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +On error, the +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall set the error indicator for the stream to which +.IR stderr +points, and shall set +.IR errno +to indicate the error. +.P +Since no value is returned, an application wishing to check for error +situations should set +.IR errno +to 0, then call +\fIpsiginfo\fR() +or +\fIpsignal\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +These functions shall not return a value. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +As an alternative to setting +.IR errno +to zero before the call and checking if it is non-zero afterwards, +applications can use +\fIferror\fR() +to detect whether +\fIpsiginfo\fR() +or +\fIpsignal\fR() +encountered an error. +.P +An application wishing to use this method to check for error situations +should call +.IR clearerr ( stderr ) +before calling +\fIpsiginfo\fR() +or +\fIpsignal\fR(), +then if +.IR ferror ( stderr ) +returns non-zero, the value of +.IR errno +indicates which error occurred. +.SH RATIONALE +System V historically has +\fIpsignal\fR() +and +\fIpsiginfo\fR() +in +.IR . +However, the +.IR +header is not specified in the Base Definitions volume of POSIX.1\(hy2008, and the type +.BR siginfo_t +is defined in +.IR . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfputc\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIstrsignal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_atfork.3p b/man-pages-posix-2013-a/man3p/pthread_atfork.3p new file mode 100644 index 0000000..20dafcb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_atfork.3p @@ -0,0 +1,237 @@ +'\" et +.TH PTHREAD_ATFORK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_atfork +\(em register fork handlers +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_atfork(void (*\fIprepare\fP)(void), void (*\fIparent\fP)(void), + void (*\fIchild\fP)(void)); +.fi +.SH DESCRIPTION +The +\fIpthread_atfork\fR() +function shall declare fork handlers to be called before and after +\fIfork\fR(), +in the context of the thread that called +\fIfork\fR(). +The +.IR prepare +fork handler shall be called before +\fIfork\fR() +processing commences. The +.IR parent +fork handle shall be called after +\fIfork\fR() +processing completes in the parent process. The +.IR child +fork handler shall be called after +\fIfork\fR() +processing completes in the child process. If no handling is desired +at one or more of these three points, the corresponding fork handler +address(es) may be set to NULL. +.P +The order of calls to +\fIpthread_atfork\fR() +is significant. The +.IR parent +and +.IR child +fork handlers shall be called in the order in which they were +established by calls to +\fIpthread_atfork\fR(). +The +.IR prepare +fork handlers shall be called in the opposite order. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_atfork\fR() +shall return a value of zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_atfork\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient table space exists to record the fork handler addresses. +.P +The +\fIpthread_atfork\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +There are at least two serious problems with the semantics of +\fIfork\fR() +in a multi-threaded program. One problem has to do with state (for +example, memory) covered by mutexes. Consider the case where one +thread has a mutex locked and the state covered by that mutex is +inconsistent while another thread calls +\fIfork\fR(). +In the child, the mutex is in the locked state (locked by a nonexistent +thread and thus can never be unlocked). Having the child simply +reinitialize the mutex is unsatisfactory since this approach does not +resolve the question about how to correct or otherwise deal with the +inconsistent state in the child. +.P +It is suggested that programs that use +\fIfork\fR() +call an +.IR exec +function very soon afterwards in the child process, thus resetting all +states. In the meantime, only a short list of async-signal-safe +library routines are promised to be available. +.P +Unfortunately, this solution does not address the needs of +multi-threaded libraries. Application programs may not be aware that a +multi-threaded library is in use, and they feel free to call any number +of library routines between the +\fIfork\fR() +and +.IR exec +calls, just as they always have. Indeed, they may be extant +single-threaded programs and cannot, therefore, be expected to obey new +restrictions imposed by the threads library. +.P +On the other hand, the multi-threaded library needs a way to protect +its internal state during +\fIfork\fR() +in case it is re-entered later in the child process. The problem +arises especially in multi-threaded I/O libraries, which are almost +sure to be invoked between the +\fIfork\fR() +and +.IR exec +calls to effect I/O redirection. The solution may require locking +mutex variables during +\fIfork\fR(), +or it may entail simply resetting the state in the child after the +\fIfork\fR() +processing completes. +.P +The +\fIpthread_atfork\fR() +function was intended to provide multi-threaded libraries with a means +to protect themselves from innocent application programs that call +\fIfork\fR(), +and to provide multi-threaded application programs with a standard +mechanism for protecting themselves from +\fIfork\fR() +calls in a library routine or the application itself. +.P +The expected usage was that the prepare handler would acquire all mutex +locks and the other two fork handlers would release them. +.P +For example, an application could have supplied a prepare routine that +acquires the necessary mutexes the library maintains and supplied child +and parent routines that release those mutexes, thus ensuring that the +child would have got a consistent snapshot of the state of the library +(and that no mutexes would have been left stranded). This is good in +theory, but in reality not practical. Each and every mutex and lock +in the process must be located and locked. Every component of a program +including third-party components must participate and they must agree who +is responsible for which mutex or lock. This is especially problematic +for mutexes and locks in dynamically allocated memory. All mutexes and +locks internal to the implementation must be locked, too. This possibly +delays the thread calling +\fIfork\fR() +for a long time or even indefinitely since uses of these synchronization +objects may not be under control of the application. A final problem +to mention here is the problem of locking streams. At least the streams +under control of the system (like +.IR stdin , +.IR stdout , +.IR stderr ) +must be protected by locking the stream with +\fIflockfile\fR(). +But the application itself could have done that, possibly in the same +thread calling +\fIfork\fR(). +In this case, the process will deadlock. +.P +Alternatively, some libraries might have been able to supply just a +.IR child +routine that reinitializes the mutexes in the library and all associated +states to some known value (for example, what it was when the image +was originally executed). This approach is not possible, though, +because implementations are allowed to fail +.IR *_init (\|) +and +.IR *_destroy (\|) +calls for mutexes and locks if the mutex or lock is still locked. In +this case, the +.IR child +routine is not able to reinitialize the mutexes and locks. +.P +When +\fIfork\fR() +is called, only the calling thread is duplicated in the child process. +Synchronization variables remain in the same state in the child as they +were in the parent at the time +\fIfork\fR() +was called. Thus, for example, mutex locks may be held by threads that +no longer exist in the child process, and any associated states may +be inconsistent. The intention was that the parent process could have +avoided this by explicit code that acquires and releases locks critical +to the child via +\fIpthread_atfork\fR(). +In addition, any critical threads would have needed to be recreated and +reinitialized to the proper state in the child (also via +\fIpthread_atfork\fR()). +.P +A higher-level package may acquire locks on its own data structures +before invoking lower-level packages. Under this scenario, the order +specified for fork handler calls allows a simple rule of initialization +for avoiding package deadlock: a package initializes all packages on +which it depends before it calls the +\fIpthread_atfork\fR() +function for itself. +.P +As explained, there is no suitable solution for functionality which +requires non-atomic operations to be protected through mutexes and +locks. This is why the POSIX.1 standard since the 1996 release requires +that the child process after +\fIfork\fR() +in a multi-threaded process only calls async-signal-safe interfaces. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatexit\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_attr_destroy.3p new file mode 100644 index 0000000..430cfb6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_destroy.3p @@ -0,0 +1,237 @@ +'\" et +.TH PTHREAD_ATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_destroy, +pthread_attr_init +\(em destroy and initialize the thread attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_destroy(pthread_attr_t *\fIattr\fP); +int pthread_attr_init(pthread_attr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_destroy\fR() +function shall destroy a thread attributes object. An implementation +may cause +\fIpthread_attr_destroy\fR() +to set +.IR attr +to an implementation-defined invalid value. A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_attr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIpthread_attr_init\fR() +function shall initialize a thread attributes object +.IR attr +with the default value for all of the individual attributes used by a +given implementation. +.P +The resulting attributes object (possibly modified by setting +individual attribute values) when used by +\fIpthread_create\fR() +defines the attributes of the thread created. A single attributes +object can be used in multiple simultaneous calls to +\fIpthread_create\fR(). +Results are undefined if +\fIpthread_attr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_destroy\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_attr_destroy\fR() +and +\fIpthread_attr_init\fR() +shall return a value of 0; otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +The +\fIpthread_attr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the thread attributes object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Attributes objects are provided for threads, mutexes, and condition +variables as a mechanism to support probable future standardization in +these areas without requiring that the function itself be changed. +.P +Attributes objects provide clean isolation of the configurable aspects +of threads. For example, ``stack size'' +is an important attribute of a thread, but it cannot be expressed +portably. When porting a threaded program, stack sizes often need to +be adjusted. The use of attributes objects can help by allowing the +changes to be isolated in a single place, rather than being spread +across every instance of thread creation. +.P +Attributes objects can be used to set up ``classes' of threads with +similar attributes; for example, ``threads with large stacks and high +priority'' or ``threads with minimal stacks''. These classes can be +defined in a single place and then referenced wherever threads need to +be created. Changes to ``class'' decisions become straightforward, and +detailed analysis of each +\fIpthread_create\fR() +call is not required. +.P +The attributes objects are defined as opaque types as an aid to +extensibility. If these objects had been specified as structures, +adding new attributes would force recompilation of all multi-threaded +programs when the attributes objects are extended; this might not be +possible if different program components were supplied by different +vendors. +.P +Additionally, opaque attributes objects present opportunities for +improving performance. Argument validity can be checked once when +attributes are set, rather than each time a thread is created. +Implementations often need to cache kernel objects that are expensive +to create. Opaque attributes objects provide an efficient mechanism to +detect when cached objects become invalid due to attribute changes. +.P +Since assignment is not necessarily defined on a given opaque type, +implementation-defined default values cannot be defined in a portable +way. The solution to this problem is to allow attributes objects to be +initialized dynamically by attributes object initialization functions, +so that default values can be supplied automatically by the +implementation. +.P +The following proposal was provided as a suggested alternative to the +supplied attributes: +.IP " 1." 4 +Maintain the style of passing a parameter formed by the +bitwise-inclusive OR of flags to the initialization routines (\c +\fIpthread_create\fR(), +\fIpthread_mutex_init\fR(), +\fIpthread_cond_init\fR()). +The parameter containing the flags should be an opaque type for +extensibility. If no flags are set in the parameter, then the objects +are created with default characteristics. An implementation may +specify implementation-defined flag values and associated behavior. +.IP " 2." 4 +If further specialization of mutexes and condition variables is +necessary, implementations may specify additional procedures that +operate on the +.BR pthread_mutex_t +and +.BR pthread_cond_t +objects (instead of on attributes objects). +.P +The difficulties with this solution are: +.IP " 1." 4 +A bitmask is not opaque if bits have to be set into bitvector +attributes objects using explicitly-coded bitwise-inclusive OR +operations. If the set of options exceeds an +.BR int , +application programmers need to know the location of each bit. If bits +are set or read by encapsulation (that is, get and set functions), then +the bitmask is merely an implementation of attributes objects as +currently defined and should not be exposed to the programmer. +.IP " 2." 4 +Many attributes are not Boolean or very small integral values. For +example, scheduling policy may be placed in 3-bit or 4-bit, but +priority requires 5-bit or more, thereby taking up at least 8 bits out +of a possible 16 bits on machines with 16-bit integers. Because of +this, the bitmask can only reasonably control whether particular +attributes are set or not, and it cannot serve as the repository of the +value itself. The value needs to be specified as a function parameter +(which is non-extensible), or by setting a structure field (which is +non-opaque), or by get and set functions (making the bitmask a +redundant addition to the attributes objects). +.P +Stack size is defined as an optional attribute because the very notion +of a stack is inherently machine-dependent. Some implementations may +not be able to change the size of the stack, for example, and others +may not need to because stack pages may be discontiguous and can be +allocated and released on demand. +.P +The attribute mechanism has been designed in large measure for +extensibility. Future extensions to the attribute mechanism or to any +attributes object defined in this volume of POSIX.1\(hy2008 has to be done with care so +as not to affect binary-compatibility. +.P +Attributes objects, even if allocated by means of dynamic allocation +functions such as +\fImalloc\fR(), +may have their size fixed at compile time. This means, for example, a +\fIpthread_create\fR() +in an implementation with extensions to +.BR pthread_attr_t +cannot look beyond the area that the binary application assumes is +valid. This suggests that implementations should maintain a size field +in the attributes object, as well as possibly version information, if +extensions in different directions (possibly by different vendors) are +to be accommodated. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_destroy\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_init\fR() +refers to an already initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EBUSY] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_getstacksize\fR\^(\|)", +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_getdetachstate.3p b/man-pages-posix-2013-a/man3p/pthread_attr_getdetachstate.3p new file mode 100644 index 0000000..9a04312 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_getdetachstate.3p @@ -0,0 +1,173 @@ +'\" et +.TH PTHREAD_ATTR_GETDETACHSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +.ad l +pthread_attr_getdetachstate, +pthread_attr_setdetachstate +\(em get and set the detachstate attribute +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getdetachstate(const pthread_attr_t *\fIattr\fP, + int *\fIdetachstate\fP); +int pthread_attr_setdetachstate(pthread_attr_t *\fIattr\fP, int \fIdetachstate\fP); +.fi +.SH DESCRIPTION +The +.IR detachstate +attribute controls whether the thread is created in a detached state. +If the thread is created detached, then use of the ID of the newly +created thread by the +\fIpthread_detach\fR() +or +\fIpthread_join\fR() +function is an error. +.P +The +\fIpthread_attr_getdetachstate\fR() +and +\fIpthread_attr_setdetachstate\fR() +functions, respectively, shall get and set the +.IR detachstate +attribute in the +.IR attr +object. +.P +For +\fIpthread_attr_getdetachstate\fR(), +.IR detachstate +shall be set to either PTHREAD_CREATE_DETACHED or +PTHREAD_CREATE_JOINABLE. +.P +For +\fIpthread_attr_setdetachstate\fR(), +the application shall set +.IR detachstate +to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. +.P +A value of PTHREAD_CREATE_DETACHED shall cause all threads created with +.IR attr +to be in the detached state, whereas using a value of +PTHREAD_CREATE_JOINABLE shall cause all threads created with +.IR attr +to be in the joinable state. The default value of the +.IR detachstate +attribute shall be PTHREAD_CREATE_JOINABLE. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getdetachstate\fR() +or +\fIpthread_attr_setdetachstate\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_attr_getdetachstate\fR() +and +\fIpthread_attr_setdetachstate\fR() +shall return a value of 0; otherwise, an error number shall be +returned to indicate the error. +.P +The +\fIpthread_attr_getdetachstate\fR() +function stores the value of the +.IR detachstate +attribute in +.IR detachstate +if successful. +.SH ERRORS +The +\fIpthread_attr_setdetachstate\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR detachstate +was not valid +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Retrieving the detachstate Attribute" +.P +This example shows how to obtain the +.IR detachstate +attribute of a thread attribute object. +.sp +.RS 4 +.nf +\fB +#include +.P +pthread_attr_t thread_attr; +int detachstate; +int rc; +.P +/* code initializing thread_attr */ +\&... +.P +rc = pthread_attr_getdetachstate (&thread_attr, &detachstate); +if (rc!=0) { + /* handle error */ + ... +} +else { + /* legal values for detachstate are: + * PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE + */ + ... +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getdetachstate\fR() +or +\fIpthread_attr_setdetachstate\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getstacksize\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_getguardsize.3p b/man-pages-posix-2013-a/man3p/pthread_attr_getguardsize.3p new file mode 100644 index 0000000..21bde70 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_getguardsize.3p @@ -0,0 +1,215 @@ +'\" et +.TH PTHREAD_ATTR_GETGUARDSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +.ad l +pthread_attr_getguardsize, +pthread_attr_setguardsize +\(em get and set the thread guardsize attribute +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getguardsize(const pthread_attr_t *restrict \fIattr\fP, + size_t *restrict \fIguardsize\fP); +int pthread_attr_setguardsize(pthread_attr_t *\fIattr\fP, + size_t \fIguardsize\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getguardsize\fR() +function shall get the +.IR guardsize +attribute in the +.IR attr +object. This attribute shall be returned in the +.IR guardsize +parameter. +.P +The +\fIpthread_attr_setguardsize\fR() +function shall set the +.IR guardsize +attribute in the +.IR attr +object. The new value of this attribute shall be obtained from the +.IR guardsize +parameter. If +.IR guardsize +is zero, a guard area shall not be provided for threads created with +.IR attr . +If +.IR guardsize +is greater than zero, a guard area of at least size +.IR guardsize +bytes shall be provided for each thread created with +.IR attr . +.P +The +.IR guardsize +attribute controls the size of the guard area for the created thread's +stack. The +.IR guardsize +attribute provides protection against overflow of the stack pointer. If +a thread's stack is created with guard protection, the implementation +allocates extra memory at the overflow end of the stack as a buffer +against stack overflow of the stack pointer. If an application +overflows into this buffer an error shall result (possibly in a SIGSEGV +signal being delivered to the thread). +.P +A conforming implementation may round up the value contained in +.IR guardsize +to a multiple of the configurable system variable +{PAGESIZE} +(see +.IR ). +If an implementation rounds up the value of +.IR guardsize +to a multiple of +{PAGESIZE}, +a call to +\fIpthread_attr_getguardsize\fR() +specifying +.IR attr +shall store in the +.IR guardsize +parameter the guard size specified by the previous +\fIpthread_attr_setguardsize\fR() +function call. +.P +The default value of the +.IR guardsize +attribute is implementation-defined. +.P +If the +.IR stackaddr +attribute has been set (that is, the caller is allocating and managing +its own thread stacks), the +.IR guardsize +attribute shall be ignored and no protection shall be provided by the +implementation. It is the responsibility of the application to manage +stack overflow along with stack allocation and management in this +case. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getguardsize\fR() +or +\fIpthread_attr_setguardsize\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getguardsize\fR() +and +\fIpthread_attr_setguardsize\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The parameter +.IR guardsize +is invalid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Retrieving the guardsize Attribute" +.P +This example shows how to obtain the +.IR guardsize +attribute of a thread attribute object. +.sp +.RS 4 +.nf +\fB +#include +.P +pthread_attr_t thread_attr; +size_t guardsize; +int rc; +.P +/* code initializing thread_attr */ +\&... +.P +rc = pthread_attr_getguardsize (&thread_attr, &guardsize); +if (rc != 0) { + /* handle error */ + ... +} +else { + if (guardsize > 0) { + /* a guard area of at least guardsize bytes is provided */ + ... + } + else { + /* no guard area provided */ + ... + } +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +.IR guardsize +attribute is provided to the application for two reasons: +.IP " 1." 4 +Overflow protection can potentially result in wasted system resources. +An application that creates a large number of threads, and which knows +its threads never overflow their stack, can save system resources by +turning off guard areas. +.IP " 2." 4 +When threads allocate large data structures on the stack, large guard +areas may be needed to detect stack overflow. +.P +The default size of the guard area is left implementation-defined +since on systems supporting very large page sizes, the overhead +might be substantial if at least one guard page is required by default. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getguardsize\fR() +or +\fIpthread_attr_setguardsize\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_getinheritsched.3p b/man-pages-posix-2013-a/man3p/pthread_attr_getinheritsched.3p new file mode 100644 index 0000000..4dfc74c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_getinheritsched.3p @@ -0,0 +1,159 @@ +'\" et +.TH PTHREAD_ATTR_GETINHERITSCHED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_getinheritsched, +pthread_attr_setinheritsched +\(em get and set the inheritsched attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getinheritsched(const pthread_attr_t *restrict \fIattr\fP, + int *restrict \fIinheritsched\fP); +int pthread_attr_setinheritsched(pthread_attr_t *\fIattr\fP, + int \fIinheritsched\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getinheritsched\fR() +and +\fIpthread_attr_setinheritsched\fR() +functions, respectively, shall get and set the +.IR inheritsched +attribute in the +.IR attr +argument. +.P +When the attributes objects are used by +\fIpthread_create\fR(), +the +.IR inheritsched +attribute determines how the other scheduling attributes of the created +thread shall be set. +.P +The supported values of +.IR inheritsched +shall be: +.IP PTHREAD_INHERIT_SCHED 6 +.br +Specifies that the thread scheduling attributes shall be inherited from +the creating thread, and the scheduling attributes in this +.IR attr +argument shall be ignored. +.IP PTHREAD_EXPLICIT_SCHED 6 +.br +Specifies that the thread scheduling attributes shall be set to the +corresponding values from this attributes object. +.P +The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are +defined in the +.IR +header. +.P +The following thread scheduling attributes defined by POSIX.1\(hy2008 are +affected by the +.IR inheritsched +attribute: scheduling policy (\c +.IR schedpolicy ), +scheduling parameters (\c +.IR schedparam ), +and scheduling contention scope (\c +.IR contentionscope ). +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getinheritsched\fR() +or +\fIpthread_attr_setinheritsched\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getinheritsched\fR() +and +\fIpthread_attr_setinheritsched\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_attr_setinheritsched\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.P +The +\fIpthread_attr_setinheritsched\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR inheritsched +is not valid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After these attributes have been set, a thread can be created with the +specified attributes using +\fIpthread_create\fR(). +Using these routines does not affect the current running thread. +.P +See +.IR "Section 2.9.4" ", " "Thread Scheduling" +for further details on thread scheduling attributes and their default +settings. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getinheritsched\fR() +or +\fIpthread_attr_setinheritsched\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getscope\fR\^(\|)", +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)", +.IR "\fIpthread_attr_getschedparam\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_getschedparam.3p b/man-pages-posix-2013-a/man3p/pthread_attr_getschedparam.3p new file mode 100644 index 0000000..d7e14e6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_getschedparam.3p @@ -0,0 +1,150 @@ +'\" et +.TH PTHREAD_ATTR_GETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_getschedparam, +pthread_attr_setschedparam +\(em get and set the schedparam attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getschedparam(const pthread_attr_t *restrict \fIattr\fP, + struct sched_param *restrict \fIparam\fP); +int pthread_attr_setschedparam(pthread_attr_t *restrict \fIattr\fP, + const struct sched_param *restrict \fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getschedparam\fR() +and +\fIpthread_attr_setschedparam\fR() +functions, respectively, shall get and set the scheduling parameter +attributes in the +.IR attr +argument. The contents of the +.IR param +structure are defined in the +.IR +header. For the SCHED_FIFO and SCHED_RR policies, +the only required member of +.IR param +is +.IR sched_priority . +.P +For the SCHED_SPORADIC policy, the required members of the +.IR param +structure are +.IR sched_priority , +.IR sched_ss_low_priority , +.IR sched_ss_repl_period , +.IR sched_ss_init_budget , +and +.IR sched_ss_max_repl . +The specified +.IR sched_ss_repl_period +must be greater than or equal to the specified +.IR sched_ss_init_budget +for the function to succeed; if it is not, then the function shall +fail. The value of +.IR sched_ss_max_repl +shall be within the inclusive range [1,\c +{SS_REPL_MAX}] +for the function to succeed; if not, the function shall fail. +It is unspecified whether the +.IR sched_ss_repl_period +and +.IR sched_ss_init_budget +values are stored as provided by this function or are rounded to +align with the resolution of the clock being used. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getschedparam\fR() +or +\fIpthread_attr_setschedparam\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getschedparam\fR() +and +\fIpthread_attr_setschedparam\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_attr_setschedparam\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.P +The +\fIpthread_attr_setschedparam\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR param +is not valid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After these attributes have been set, a thread can be created with the +specified attributes using +\fIpthread_create\fR(). +Using these routines does not affect the current running thread. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getschedparam\fR() +or +\fIpthread_attr_setschedparam\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getscope\fR\^(\|)", +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)", +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_getschedpolicy.3p b/man-pages-posix-2013-a/man3p/pthread_attr_getschedpolicy.3p new file mode 100644 index 0000000..044f606 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_getschedpolicy.3p @@ -0,0 +1,133 @@ +'\" et +.TH PTHREAD_ATTR_GETSCHEDPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_getschedpolicy, +pthread_attr_setschedpolicy +\(em get and set the schedpolicy attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getschedpolicy(const pthread_attr_t *restrict \fIattr\fP, + int *restrict \fIpolicy\fP); +int pthread_attr_setschedpolicy(pthread_attr_t *\fIattr\fP, int \fIpolicy\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getschedpolicy\fR() +and +\fIpthread_attr_setschedpolicy\fR() +functions, respectively, shall get and set the +.IR schedpolicy +attribute in the +.IR attr +argument. +.P +The supported values of +.IR policy +shall include SCHED_FIFO, SCHED_RR, and SCHED_OTHER, +which are defined in the +.IR +header. When threads executing with the scheduling policy SCHED_FIFO, +SCHED_RR, +or SCHED_SPORADIC +are waiting on a mutex, they shall acquire the mutex in priority order +when the mutex is unlocked. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getschedpolicy\fR() +or +\fIpthread_attr_setschedpolicy\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getschedpolicy\fR() +and +\fIpthread_attr_setschedpolicy\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_attr_setschedpolicy\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.P +The +\fIpthread_attr_setschedpolicy\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR policy +is not valid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After these attributes have been set, a thread can be created with the +specified attributes using +\fIpthread_create\fR(). +Using these routines does not affect the current running thread. +.P +See +.IR "Section 2.9.4" ", " "Thread Scheduling" +for further details on thread scheduling attributes and their +default settings. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getschedpolicy\fR() +or +\fIpthread_attr_setschedpolicy\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getscope\fR\^(\|)", +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)", +.IR "\fIpthread_attr_getschedparam\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_getscope.3p b/man-pages-posix-2013-a/man3p/pthread_attr_getscope.3p new file mode 100644 index 0000000..f003b5b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_getscope.3p @@ -0,0 +1,132 @@ +'\" et +.TH PTHREAD_ATTR_GETSCOPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_getscope, +pthread_attr_setscope +\(em get and set the contentionscope attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getscope(const pthread_attr_t *restrict \fIattr\fP, + int *restrict \fIcontentionscope\fP); +int pthread_attr_setscope(pthread_attr_t *\fIattr\fP, int \fIcontentionscope\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getscope\fR() +and +\fIpthread_attr_setscope\fR() +functions, respectively, shall get and set the +.IR contentionscope +attribute in the +.IR attr +object. +.P +The +.IR contentionscope +attribute may have the values PTHREAD_SCOPE_SYSTEM, +signifying system scheduling contention scope, or +PTHREAD_SCOPE_PROCESS, +signifying process scheduling contention scope. The symbols +PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS are defined in the +.IR +header. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getscope\fR() +or +\fIpthread_attr_setscope\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getscope\fR() +and +\fIpthread_attr_setscope\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_attr_setscope\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.P +The +\fIpthread_attr_setscope\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR contentionscope +is not valid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After these attributes have been set, a thread can be created with the +specified attributes using +\fIpthread_create\fR(). +Using these routines does not affect the current running thread. +.P +See +.IR "Section 2.9.4" ", " "Thread Scheduling" +for further details on thread scheduling attributes and their default +settings. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getscope\fR() +or +\fIpthread_attr_setscope\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)", +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)", +.IR "\fIpthread_attr_getschedparam\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_getstack.3p b/man-pages-posix-2013-a/man3p/pthread_attr_getstack.3p new file mode 100644 index 0000000..d545375 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_getstack.3p @@ -0,0 +1,201 @@ +'\" et +.TH PTHREAD_ATTR_GETSTACK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_getstack, +pthread_attr_setstack +\(em get and set stack attributes +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getstack(const pthread_attr_t *restrict \fIattr\fP, + void **restrict \fIstackaddr\fP, size_t *restrict \fIstacksize\fP); +int pthread_attr_setstack(pthread_attr_t *\fIattr\fP, void *\fIstackaddr\fP, + size_t \fIstacksize\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getstack\fR() +and +\fIpthread_attr_setstack\fR() +functions, respectively, shall get and set the thread creation stack +attributes +.IR stackaddr +and +.IR stacksize +in the +.IR attr +object. +.P +The stack attributes specify the area of storage to be used for the +created thread's stack. The base (lowest addressable byte) of the +storage shall be +.IR stackaddr , +and the size of the storage shall be +.IR stacksize +bytes. The +.IR stacksize +shall be at least +{PTHREAD_STACK_MIN}. +The +\fIpthread_attr_setstack\fR() +function may fail with +.BR [EINVAL] +if +.IR stackaddr +does not meet implementation-defined alignment requirements. +All pages within the stack described by +.IR stackaddr +and +.IR stacksize +shall be both readable and writable by the thread. +.P +If the +\fIpthread_attr_getstack\fR() +function is called before the +.IR stackaddr +attribute has been set, the behavior is unspecified. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getstack\fR() +or +\fIpthread_attr_setstack\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of 0; +otherwise, an error number shall be returned to indicate the error. +.P +The +\fIpthread_attr_getstack\fR() +function shall store the stack attribute values in +.IR stackaddr +and +.IR stacksize +if successful. +.SH ERRORS +.P +The +\fIpthread_attr_setstack\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR stacksize +is less than +{PTHREAD_STACK_MIN} +or exceeds an implementation-defined limit. +.P +The +\fIpthread_attr_setstack\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR stackaddr +does not have proper alignment to be used as a stack, or ((\c +.BR "char *" )\c +.IR stackaddr ++ +.IR stacksize ) +lacks proper alignment. +.TP +.BR EACCES +The stack page(s) described by +.IR stackaddr +and +.IR stacksize +are not both readable and writable by the thread. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are appropriate for use by applications in an +environment where the stack for a thread must be placed in some +particular region of memory. +.P +While it might seem that an application could detect stack overflow by +providing a protected page outside the specified stack region, this +cannot be done portably. Implementations are free to place the thread's +initial stack pointer anywhere within the specified region to +accommodate the machine's stack pointer behavior and allocation +requirements. Furthermore, on some architectures, such as the IA\(hy64, +``overflow'' might mean that two separate stack pointers allocated +within the region will overlap somewhere in the middle of the region. +.P +After a successful call to +\fIpthread_attr_setstack\fR(), +the storage area specified by the +.IR stackaddr +parameter is under the control of the implementation, as described in +.IR "Section 2.9.8" ", " "Use of Application-Managed Thread Stacks". +.P +The specification of the +.IR stackaddr +attribute presents several ambiguities that make portable use of these +functions impossible. For example, the standard allows implementations +to impose arbitrary alignment requirements on +.IR stackaddr . +Applications cannot assume that a buffer obtained from +\fImalloc\fR() +is suitably aligned. Note that although the +.IR stacksize +value passed to +\fIpthread_attr_setstack\fR() +must satisfy alignment requirements, the same is not true for +\fIpthread_attr_setstacksize\fR() +where the implementation must increase the specified size if +necessary to achieve the proper alignment. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getstack\fR() +or +\fIpthread_attr_setstack\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)", +.IR "\fIpthread_attr_getstacksize\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_getstacksize.3p b/man-pages-posix-2013-a/man3p/pthread_attr_getstacksize.3p new file mode 100644 index 0000000..bd1427d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_getstacksize.3p @@ -0,0 +1,119 @@ +'\" et +.TH PTHREAD_ATTR_GETSTACKSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +.ad l +pthread_attr_getstacksize, +pthread_attr_setstacksize +\(em get and set the stacksize attribute +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getstacksize(const pthread_attr_t *restrict \fIattr\fP, + size_t *restrict \fIstacksize\fP); +int pthread_attr_setstacksize(pthread_attr_t *\fIattr\fP, size_t \fIstacksize\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getstacksize\fR() +and +\fIpthread_attr_setstacksize\fR() +functions, respectively, shall get and set the thread creation +.IR stacksize +attribute in the +.IR attr +object. +.P +The +.IR stacksize +attribute shall define the minimum stack size (in bytes) allocated +for the created threads stack. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getstacksize\fR() +or +\fIpthread_attr_setstacksize\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_attr_getstacksize\fR() +and +\fIpthread_attr_setstacksize\fR() +shall return a value of 0; otherwise, an error number shall be +returned to indicate the error. +.P +The +\fIpthread_attr_getstacksize\fR() +function stores the +.IR stacksize +attribute value in +.IR stacksize +if successful. +.SH ERRORS +The +\fIpthread_attr_setstacksize\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR stacksize +is less than +{PTHREAD_STACK_MIN} +or exceeds a system-imposed limit. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getstacksize\fR() +or +\fIpthread_attr_setstacksize\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_init.3p b/man-pages-posix-2013-a/man3p/pthread_attr_init.3p new file mode 100644 index 0000000..a15e4a1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_ATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_init +\(em initialize the thread attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_init(pthread_attr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_destroy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_setdetachstate.3p b/man-pages-posix-2013-a/man3p/pthread_attr_setdetachstate.3p new file mode 100644 index 0000000..51bc552 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_setdetachstate.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_ATTR_SETDETACHSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_setdetachstate +\(em set the detachstate attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setdetachstate(pthread_attr_t *\fIattr\fP, int \fIdetachstate\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_setguardsize.3p b/man-pages-posix-2013-a/man3p/pthread_attr_setguardsize.3p new file mode 100644 index 0000000..9c07af5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_setguardsize.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETGUARDSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_setguardsize +\(em set the thread guardsize attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setguardsize(pthread_attr_t *\fIattr\fP, + size_t \fIguardsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getguardsize\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_setinheritsched.3p b/man-pages-posix-2013-a/man3p/pthread_attr_setinheritsched.3p new file mode 100644 index 0000000..f259b7a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_setinheritsched.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_ATTR_SETINHERITSCHED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_setinheritsched +\(em set the inheritsched attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setinheritsched(pthread_attr_t *\fIattr\fP, + int \fIinheritsched\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_setschedparam.3p b/man-pages-posix-2013-a/man3p/pthread_attr_setschedparam.3p new file mode 100644 index 0000000..dfb4fe9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_setschedparam.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_setschedparam +\(em set the schedparam attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setschedparam(pthread_attr_t *restrict \fIattr\fP, + const struct sched_param *restrict \fIparam\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getschedparam\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_setschedpolicy.3p b/man-pages-posix-2013-a/man3p/pthread_attr_setschedpolicy.3p new file mode 100644 index 0000000..3f9e446 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_setschedpolicy.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETSCHEDPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_setschedpolicy +\(em set the schedpolicy attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setschedpolicy(pthread_attr_t *\fIattr\fP, int \fIpolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_setscope.3p b/man-pages-posix-2013-a/man3p/pthread_attr_setscope.3p new file mode 100644 index 0000000..721f267 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_setscope.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETSCOPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_setscope +\(em set the contentionscope attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setscope(pthread_attr_t *\fIattr\fP, int \fIcontentionscope\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getscope\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_setstack.3p b/man-pages-posix-2013-a/man3p/pthread_attr_setstack.3p new file mode 100644 index 0000000..a6ef250 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_setstack.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETSTACK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_setstack +\(em set the stack attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setstack(pthread_attr_t *\fIattr\fP, void *\fIstackaddr\fP, + size_t \fIstacksize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getstack\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_attr_setstacksize.3p b/man-pages-posix-2013-a/man3p/pthread_attr_setstacksize.3p new file mode 100644 index 0000000..676ac3e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_attr_setstacksize.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_ATTR_SETSTACKSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_attr_setstacksize +\(em set the stacksize attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setstacksize(pthread_attr_t *\fIattr\fP, size_t \fIstacksize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getstacksize\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_barrier_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_barrier_destroy.3p new file mode 100644 index 0000000..124b447 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_barrier_destroy.3p @@ -0,0 +1,168 @@ +'\" et +.TH PTHREAD_BARRIER_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_barrier_destroy, +pthread_barrier_init +\(em destroy and initialize a barrier object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrier_destroy(pthread_barrier_t *\fIbarrier\fP); +int pthread_barrier_init(pthread_barrier_t *restrict \fIbarrier\fP, + const pthread_barrierattr_t *restrict \fIattr\fP, unsigned \fIcount\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_barrier_destroy\fR() +function shall destroy the barrier referenced by +.IR barrier +and release any resources used by the barrier. The effect of +subsequent use of the barrier is undefined until the barrier is +reinitialized by another call to +\fIpthread_barrier_init\fR(). +An implementation may use this function to set +.IR barrier +to an invalid value. The results are undefined if +\fIpthread_barrier_destroy\fR() +is called when any thread is blocked on the barrier, or if this +function is called with an uninitialized barrier. +.P +The +\fIpthread_barrier_init\fR() +function shall allocate any resources required to use the barrier +referenced by +.IR barrier +and shall initialize the barrier with attributes referenced by +.IR attr . +If +.IR attr +is NULL, the default barrier attributes shall be used; the effect is +the same as passing the address of a default barrier attributes +object. The results are undefined if +\fIpthread_barrier_init\fR() +is called when any thread is blocked on the barrier (that is, has not +returned from the +\fIpthread_barrier_wait\fR() +call). The results are undefined if a barrier is used without first +being initialized. The results are undefined if +\fIpthread_barrier_init\fR() +is called specifying an already initialized barrier. +.P +The +.IR count +argument specifies the number of threads that must call +\fIpthread_barrier_wait\fR() +before any of them successfully return from the call. The value +specified by +.IR count +must be greater than zero. +.P +If the +\fIpthread_barrier_init\fR() +function fails, the barrier shall not be initialized and the contents +of +.IR barrier +are undefined. +.P +Only the object referenced by +.IR barrier +may be used for performing synchronization. The result of referring to +copies of that object in calls to +\fIpthread_barrier_destroy\fR() +or +\fIpthread_barrier_wait\fR() +is undefined. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIpthread_barrier_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacks the necessary resources to initialize another barrier. +.TP +.BR EINVAL +The value specified by +.IR count +is equal to zero. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the barrier. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR barrier +argument to +\fIpthread_barrier_destroy\fR() +does not refer to an initialized barrier object, it is recommended that +the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_barrier_init\fR() +does not refer to an initialized barrier attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR barrier +argument to +\fIpthread_barrier_destroy\fR() +or +\fIpthread_barrier_init\fR() +refers to a barrier that is in use (for example, in a +\fIpthread_barrier_wait\fR() +call) by another thread, or detects that the value specified by the +.IR barrier +argument to +\fIpthread_barrier_init\fR() +refers to an already initialized barrier object, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_barrier_wait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_barrier_wait.3p b/man-pages-posix-2013-a/man3p/pthread_barrier_wait.3p new file mode 100644 index 0000000..48735fe --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_barrier_wait.3p @@ -0,0 +1,112 @@ +'\" et +.TH PTHREAD_BARRIER_WAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_barrier_wait +\(em synchronize at a barrier +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrier_wait(pthread_barrier_t *\fIbarrier\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_barrier_wait\fR() +function shall synchronize participating threads at the barrier +referenced by +.IR barrier . +The calling thread shall block until the required number of +threads have called +\fIpthread_barrier_wait\fR() +specifying the barrier. +.P +When the required number of threads have called +\fIpthread_barrier_wait\fR() +specifying the barrier, the constant PTHREAD_BARRIER_SERIAL_THREAD +shall be returned to one unspecified thread and zero shall be returned +to each of the remaining threads. At this point, the barrier shall be +reset to the state it had as a result of the most recent +\fIpthread_barrier_init\fR() +function that referenced it. +.P +The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in +.IR +and its value shall be distinct from any other value returned by +\fIpthread_barrier_wait\fR(). +.P +The results are undefined if this function is called with an +uninitialized barrier. +.P +If a signal is delivered to a thread blocked on a barrier, upon return +from the signal handler the thread shall resume waiting at the barrier +if the barrier wait has not completed (that is, if the required number +of threads have not arrived at the barrier during the execution of the +signal handler); otherwise, the thread shall continue as normal from +the completed barrier wait. Until the thread in the signal handler +returns from it, it is unspecified whether other threads may proceed +past the barrier once they have all reached it. +.P +A thread that has blocked on a barrier shall not prevent any unblocked +thread that is eligible to use the same processing resources from +eventually making forward progress in its execution. Eligibility for +processing resources shall be determined by the scheduling policy. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_barrier_wait\fR() +function shall return PTHREAD_BARRIER_SERIAL_THREAD for a single +(arbitrary) thread synchronized at the barrier and zero for each of the +other threads. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR barrier +argument to +\fIpthread_barrier_wait\fR() +does not refer to an initialized barrier object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_barrier_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_barrierattr_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_barrierattr_destroy.3p new file mode 100644 index 0000000..b83baf9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_barrierattr_destroy.3p @@ -0,0 +1,113 @@ +'\" et +.TH PTHREAD_BARRIERATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_barrierattr_destroy, +pthread_barrierattr_init +\(em destroy and initialize the barrier attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrierattr_destroy(pthread_barrierattr_t *\fIattr\fP); +int pthread_barrierattr_init(pthread_barrierattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_barrierattr_destroy\fR() +function shall destroy a barrier attributes object. A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_barrierattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. An implementation may cause +\fIpthread_barrierattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +The +\fIpthread_barrierattr_init\fR() +function shall initialize a barrier attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +If +\fIpthread_barrierattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object, the results are undefined. +.P +After a barrier attributes object has been used to initialize one or +more barriers, any function affecting the attributes object (including +destruction) shall not affect any previously initialized barrier. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_barrierattr_destroy\fR() +does not refer to an initialized barrier attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_barrierattr_destroy\fR() +and +\fIpthread_barrierattr_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_barrierattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the barrier attributes +object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_barrierattr_destroy\fR() +does not refer to an initialized barrier attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_barrierattr_getpshared\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_barrierattr_getpshared.3p b/man-pages-posix-2013-a/man3p/pthread_barrierattr_getpshared.3p new file mode 100644 index 0000000..3592976 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_barrierattr_getpshared.3p @@ -0,0 +1,141 @@ +'\" et +.TH PTHREAD_BARRIERATTR_GETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_barrierattr_getpshared, +pthread_barrierattr_setpshared +\(em get and set the process-shared attribute of the barrier +attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrierattr_getpshared(const pthread_barrierattr_t + *restrict \fIattr\fP, int *restrict \fIpshared\fP); +int pthread_barrierattr_setpshared(pthread_barrierattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_barrierattr_getpshared\fR() +function shall obtain the value of the +.IR process-shared +attribute from the attributes object referenced by +.IR attr . +The +\fIpthread_barrierattr_setpshared\fR() +function shall set the +.IR process-shared +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR process-shared +attribute is set to PTHREAD_PROCESS_SHARED to +permit a barrier to be operated upon by any thread that has access to +the memory where the barrier is allocated. If the +.IR process-shared +attribute is PTHREAD_PROCESS_PRIVATE, the barrier shall only be +operated upon by +threads created within the same process as the thread that initialized +the barrier; if threads of different processes attempt to operate on +such a barrier, the behavior is undefined. The default value of the +attribute shall be PTHREAD_PROCESS_PRIVATE. Both constants +PTHREAD_PROCESS_SHARED and PTHREAD_PROCESS_PRIVATE are defined in +.IR . +.P +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_barrierattr_getpshared\fR() +or +\fIpthread_barrierattr_setpshared\fR() +does not refer to an initialized barrier attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_barrierattr_getpshared\fR() +function shall return zero and store the value of the +.IR process-shared +attribute of +.IR attr +into the object referenced by the +.IR pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +.P +If successful, the +\fIpthread_barrierattr_setpshared\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_barrierattr_setpshared\fR() +function may fail if: +.TP +.BR EINVAL +The new value specified for the +.IR process-shared +attribute is not one of the legal values PTHREAD_PROCESS_SHARED +or PTHREAD_PROCESS_PRIVATE. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_barrierattr_getpshared\fR() +and +\fIpthread_barrierattr_setpshared\fR() +functions are part of the Thread Process-Shared Synchronization +option and need not be provided on all implementations. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_barrierattr_getpshared\fR() +or +\fIpthread_barrierattr_setpshared\fR() +does not refer to an initialized barrier attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_barrier_destroy\fR\^(\|)", +.IR "\fIpthread_barrierattr_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_barrierattr_init.3p b/man-pages-posix-2013-a/man3p/pthread_barrierattr_init.3p new file mode 100644 index 0000000..e9ac123 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_barrierattr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_BARRIERATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_barrierattr_init +\(em initialize the barrier attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrierattr_init(pthread_barrierattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_barrierattr_destroy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_barrierattr_setpshared.3p b/man-pages-posix-2013-a/man3p/pthread_barrierattr_setpshared.3p new file mode 100644 index 0000000..7f853cb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_barrierattr_setpshared.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_BARRIERATTR_SETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_barrierattr_setpshared +\(em set the process-shared attribute of the barrier attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrierattr_setpshared(pthread_barrierattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_barrierattr_getpshared\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_cancel.3p b/man-pages-posix-2013-a/man3p/pthread_cancel.3p new file mode 100644 index 0000000..2b417a3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_cancel.3p @@ -0,0 +1,121 @@ +'\" et +.TH PTHREAD_CANCEL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_cancel +\(em cancel execution of a thread +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cancel(pthread_t \fIthread\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_cancel\fR() +function shall request that +.IR thread +be canceled. The target thread's cancelability state and type +determines when the cancellation takes effect. When the cancellation +is acted on, the cancellation cleanup handlers for +.IR thread +shall be called. When the last cancellation cleanup handler returns, +the thread-specific data destructor functions shall be called for +.IR thread . +When the last destructor function returns, +.IR thread +shall be terminated. +.P +The cancellation processing in the target thread shall run +asynchronously with respect to the calling thread returning from +\fIpthread_cancel\fR(). +.SH "RETURN VALUE" +If successful, the +\fIpthread_cancel\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_cancel\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Two alternative functions were considered for sending the cancellation +notification to a thread. One would be to define a new SIGCANCEL +signal that had the cancellation semantics when delivered; the other was +to define the new +\fIpthread_cancel\fR() +function, which would trigger the cancellation semantics. +.P +The advantage of a new signal was that so much of the delivery criteria +were identical to that used when trying to deliver a signal that making +cancellation notification a signal was seen as consistent. Indeed, many +implementations implement cancellation using a special signal. On the +other hand, there would be no signal functions that could be used with +this signal except +\fIpthread_kill\fR(), +and the behavior of the delivered cancellation signal would be unlike +any previously existing defined signal. +.P +The benefits of a special function include the recognition that this +signal would be defined because of the similar delivery criteria and +that this is the only common behavior between a cancellation request and +a signal. In addition, the cancellation delivery mechanism does not +have to be implemented as a signal. There are also strong, if not +stronger, parallels with language exception mechanisms than with +signals that are potentially obscured if the delivery mechanism is +visibly closer to signals. +.P +In the end, it was considered that as there were so many exceptions to +the use of the new signal with existing signals functions it +would be misleading. A special function has resolved this problem. +This function was carefully defined so that an implementation wishing +to provide the cancellation functions on top of signals could do so. +The special function also means that implementations are not obliged +to implement cancellation with signals. +.P +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_exit\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_join\fR\^(\|)", +.IR "\fIpthread_setcancelstate\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_cleanup_pop.3p b/man-pages-posix-2013-a/man3p/pthread_cleanup_pop.3p new file mode 100644 index 0000000..19c80c6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_cleanup_pop.3p @@ -0,0 +1,335 @@ +'\" et +.TH PTHREAD_CLEANUP_POP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_cleanup_pop, +pthread_cleanup_push +\(em establish cancellation handlers +.SH SYNOPSIS +.LP +.nf +#include +.P +void pthread_cleanup_pop(int \fIexecute\fP); +void pthread_cleanup_push(void (*\fIroutine\fP)(void*), void *\fIarg\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_cleanup_pop\fR() +function shall remove the routine at the top of the calling thread's +cancellation cleanup stack and optionally invoke it (if +.IR execute +is non-zero). +.P +The +\fIpthread_cleanup_push\fR() +function shall push the specified cancellation cleanup handler +.IR routine +onto the calling thread's cancellation cleanup stack. The cancellation +cleanup handler shall be popped from the cancellation cleanup stack and +invoked with the argument +.IR arg +when: +.IP " *" 4 +The thread exits (that is, calls +\fIpthread_exit\fR()). +.IP " *" 4 +The thread acts upon a cancellation request. +.IP " *" 4 +The thread calls +\fIpthread_cleanup_pop\fR() +with a non-zero +.IR execute +argument. +.P +These functions may be implemented as macros. The application shall +ensure that they appear as statements, and in pairs within the same +lexical scope (that is, the +\fIpthread_cleanup_push\fR() +macro may be thought to expand to a token list whose first token is +.BR '{' +with +\fIpthread_cleanup_pop\fR() +expanding to a token list whose last token is the corresponding +.BR '}' ). +.P +The effect of calling +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +is undefined if there have been any calls to +\fIpthread_cleanup_push\fR() +or +\fIpthread_cleanup_pop\fR() +made without the matching call since the jump buffer was filled. The +effect of calling +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +from inside a cancellation cleanup handler is also undefined unless the +jump buffer was also filled in the cancellation cleanup handler. +.P +The effect of the use of +.BR return , +.BR break , +.BR continue , +and +.BR goto +to prematurely leave a code block described by a pair of +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR() +functions calls is undefined. +.SH "RETURN VALUE" +The +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR() +functions shall not return a value. +.SH ERRORS +No errors are defined. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following is an example using thread primitives to implement a +cancelable, writers-priority read-write lock: +.sp +.RS 4 +.nf +\fB +typedef struct { + pthread_mutex_t lock; + pthread_cond_t rcond, + wcond; + int lock_count; /* < 0 .. Held by writer. */ + /* > 0 .. Held by lock_count readers. */ + /* = 0 .. Held by nobody. */ + int waiting_writers; /* Count of waiting writers. */ +} rwlock; +.P +void +waiting_reader_cleanup(void *arg) +{ + rwlock *l; +.P + l = (rwlock *) arg; + pthread_mutex_unlock(&l->lock); +} +.P +void +lock_for_read(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + pthread_cleanup_push(waiting_reader_cleanup, l); + while ((l->lock_count < 0) || (l->waiting_writers != 0)) + pthread_cond_wait(&l->rcond, &l->lock); + l->lock_count++; + /* + * Note the pthread_cleanup_pop executes + * waiting_reader_cleanup. + */ + pthread_cleanup_pop(1); +} +.P +void +release_read_lock(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + if (-\|-l->lock_count == 0) + pthread_cond_signal(&l->wcond); + pthread_mutex_unlock(&l->lock); +} +.P +void +waiting_writer_cleanup(void *arg) +{ + rwlock *l; +.P + l = (rwlock *) arg; + if ((-\|-l->waiting_writers == 0) && (l->lock_count >= 0)) { + /* + * This only happens if we have been canceled. If the + * lock is not held by a writer, there may be readers who + * were blocked because waiting_writers was positive; they + * can now be unblocked. + */ + pthread_cond_broadcast(&l->rcond); + } + pthread_mutex_unlock(&l->lock); +} +.P +void +lock_for_write(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + l->waiting_writers++; + pthread_cleanup_push(waiting_writer_cleanup, l); + while (l->lock_count != 0) + pthread_cond_wait(&l->wcond, &l->lock); + l->lock_count = \(mi1; + /* + * Note the pthread_cleanup_pop executes + * waiting_writer_cleanup. + */ + pthread_cleanup_pop(1); +} +.P +void +release_write_lock(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + l->lock_count = 0; + if (l->waiting_writers == 0) + pthread_cond_broadcast(&l->rcond); + else + pthread_cond_signal(&l->wcond); + pthread_mutex_unlock(&l->lock); +} +.P +/* + * This function is called to initialize the read/write lock. + */ +void +initialize_rwlock(rwlock *l) +{ + pthread_mutex_init(&l->lock, pthread_mutexattr_default); + pthread_cond_init(&l->wcond, pthread_condattr_default); + pthread_cond_init(&l->rcond, pthread_condattr_default); + l->lock_count = 0; + l->waiting_writers = 0; +} +.P +reader_thread() +{ + lock_for_read(&lock); + pthread_cleanup_push(release_read_lock, &lock); + /* + * Thread has read lock. + */ + pthread_cleanup_pop(1); +} +.P +writer_thread() +{ + lock_for_write(&lock); + pthread_cleanup_push(release_write_lock, &lock); + /* + * Thread has write lock. + */ +pthread_cleanup_pop(1); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The two routines that push and pop cancellation cleanup handlers, +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR(), +can be thought of as left and right-parentheses. They always need to +be matched. +.SH RATIONALE +The restriction that the two routines that push and pop +cancellation cleanup handlers, +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR(), +have to appear in the same lexical scope allows for efficient macro or +compiler implementations and efficient storage management. A sample +implementation of these routines as macros might look like this: +.sp +.RS 4 +.nf +\fB +#define pthread_cleanup_push(rtn,arg) { \e + struct _pthread_handler_rec __cleanup_handler, **__head; \e + __cleanup_handler.rtn = rtn; \e + __cleanup_handler.arg = arg; \e + (void) pthread_getspecific(_pthread_handler_key, &__head); \e + __cleanup_handler.next = *__head; \e + *__head = &__cleanup_handler; +.P +#define pthread_cleanup_pop(ex) \e + *__head = __cleanup_handler.next; \e + if (ex) (*__cleanup_handler.rtn)(__cleanup_handler.arg); \e +} +.fi \fR +.P +.RE +.P +A more ambitious implementation of these routines might do even better +by allowing the compiler to note that the +cancellation cleanup handler is a constant and can be expanded inline. +.P +This volume of POSIX.1\(hy2008 currently leaves unspecified the effect of calling +\fIlongjmp\fR() +from a signal handler executing in a POSIX System Interfaces function. +If an implementation wants to allow this and give the programmer +reasonable behavior, the +\fIlongjmp\fR() +function has to call all cancellation cleanup handlers that have been +pushed but not popped since the time +\fIsetjmp\fR() +was called. +.P +Consider a multi-threaded function called by a thread that uses +signals. If a signal were delivered to a signal handler during the +operation of +\fIqsort\fR() +and that handler were to call +\fIlongjmp\fR() +(which, in turn, did +.IR not +call the cancellation cleanup handlers) the helper threads created by +the +\fIqsort\fR() +function would not be canceled. Instead, they would continue to execute +and write into the argument array even though the array might have been +popped off the stack. +.P +Note that the specified cleanup handling mechanism is especially tied +to the C language and, while the requirement for a uniform mechanism +for expressing cleanup is language-independent, the mechanism used in +other languages may be quite different. In addition, this mechanism is +really only necessary due to the lack of a real exception mechanism in +the C language, which would be the ideal solution. +.P +There is no notion of a cancellation cleanup-safe function. If an +application has no cancellation points in its signal handlers, blocks +any signal whose handler may have cancellation points while calling +async-unsafe functions, or disables cancellation while calling +async-unsafe functions, all functions may be safely called from +cancellation cleanup routines. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cancel\fR\^(\|)", +.IR "\fIpthread_setcancelstate\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_cond_broadcast.3p b/man-pages-posix-2013-a/man3p/pthread_cond_broadcast.3p new file mode 100644 index 0000000..dd92468 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_cond_broadcast.3p @@ -0,0 +1,238 @@ +'\" et +.TH PTHREAD_COND_BROADCAST "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_cond_broadcast, +pthread_cond_signal +\(em broadcast or signal a condition +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cond_broadcast(pthread_cond_t *\fIcond\fP); +int pthread_cond_signal(pthread_cond_t *\fIcond\fP); +.fi +.SH DESCRIPTION +These functions shall unblock threads blocked on a condition variable. +.P +The +\fIpthread_cond_broadcast\fR() +function shall unblock all threads currently blocked on the specified +condition variable +.IR cond . +.P +The +\fIpthread_cond_signal\fR() +function shall unblock at least one of the threads that are blocked +on the specified condition variable +.IR cond +(if any threads are blocked on +.IR cond ). +.P +If more than one thread is blocked on a condition variable, the +scheduling policy shall determine the order in which threads are +unblocked. When each thread unblocked as a result of a +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +returns from its call to +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR(), +the thread shall own the mutex with which it called +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR(). +The thread(s) that are unblocked shall contend for the mutex according +to the scheduling policy (if applicable), and as if each had called +\fIpthread_mutex_lock\fR(). +.P +The +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +functions may be called by a thread whether or not it currently owns +the mutex that threads calling +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR() +have associated with the condition variable during their waits; +however, if predictable scheduling behavior is required, then that +mutex shall be locked by the thread calling +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR(). +.P +The +\fIpthread_cond_broadcast\fR() +and +\fIpthread_cond_signal\fR() +functions shall have no effect if there are no threads currently +blocked on +.IR cond . +.P +The behavior is undefined if the value specified by the +.IR cond +argument to +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +does not refer to an initialized condition variable. +.SH "RETURN VALUE" +If successful, the +\fIpthread_cond_broadcast\fR() +and +\fIpthread_cond_signal\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_cond_broadcast\fR() +function is used whenever the shared-variable state has been changed in +a way that more than one thread can proceed with its task. Consider a +single producer/multiple consumer problem, where the producer can +insert multiple items on a list that is accessed one item at a time by +the consumers. By calling the +\fIpthread_cond_broadcast\fR() +function, the producer would notify all consumers that might be +waiting, and thereby the application would receive more throughput on a +multi-processor. In addition, +\fIpthread_cond_broadcast\fR() +makes it easier to implement a read-write lock. The +\fIpthread_cond_broadcast\fR() +function is needed in order to wake up all waiting readers when a +writer releases its lock. Finally, the two-phase commit algorithm can +use this broadcast function to notify all clients of an impending +transaction commit. +.P +It is not safe to use the +\fIpthread_cond_signal\fR() +function in a signal handler that is invoked asynchronously. Even if +it were safe, there would still be a race between the test of the +Boolean +\fIpthread_cond_wait\fR() +that could not be efficiently eliminated. +.P +Mutexes and condition variables are thus not suitable for releasing a +waiting thread by signaling from code running in a signal handler. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +does not refer to an initialized condition variable, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.SS "Multiple Awakenings by Condition Signal" +.P +On a multi-processor, it may be impossible for an implementation of +\fIpthread_cond_signal\fR() +to avoid the unblocking of more than one thread blocked on a condition +variable. For example, consider the following partial implementation +of +\fIpthread_cond_wait\fR() +and +\fIpthread_cond_signal\fR(), +executed by two threads in the order given. One thread is trying to +wait on the condition variable, another is concurrently executing +\fIpthread_cond_signal\fR(), +while a third thread is already waiting. +.sp +.RS 4 +.nf +\fB +pthread_cond_wait(mutex, cond): + value = cond->value; /* 1 */ + pthread_mutex_unlock(mutex); /* 2 */ + pthread_mutex_lock(cond->mutex); /* 10 */ + if (value == cond->value) { /* 11 */ + me->next_cond = cond->waiter; + cond->waiter = me; + pthread_mutex_unlock(cond->mutex); + unable_to_run(me); + } else + pthread_mutex_unlock(cond->mutex); /* 12 */ + pthread_mutex_lock(mutex); /* 13 */ +.P +pthread_cond_signal(cond): + pthread_mutex_lock(cond->mutex); /* 3 */ + cond->value++; /* 4 */ + if (cond->waiter) { /* 5 */ + sleeper = cond->waiter; /* 6 */ + cond->waiter = sleeper->next_cond; /* 7 */ + able_to_run(sleeper); /* 8 */ + } + pthread_mutex_unlock(cond->mutex); /* 9 */ +.fi \fR +.P +.RE +.P +The effect is that more than one thread can return from its call to +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR() +as a result of one call to +\fIpthread_cond_signal\fR(). +This effect is called ``spurious wakeup''. +Note that the situation is self-correcting in that the number of +threads that are so awakened is finite; for example, the next thread to +call +\fIpthread_cond_wait\fR() +after the sequence of events above blocks. +.P +While this problem could be resolved, the loss of efficiency for a +fringe condition that occurs only rarely is unacceptable, especially +given that one has to check the predicate associated with a condition +variable anyway. Correcting this problem would unnecessarily reduce +the degree of concurrency in this basic building block for all +higher-level synchronization operations. +.P +An added benefit of allowing spurious wakeups is that applications are +forced to code a predicate-testing-loop around the condition wait. +This also makes the application tolerate superfluous condition +broadcasts or signals on the same condition variable that may be coded +in some other part of the application. The resulting applications are +thus more robust. Therefore, POSIX.1\(hy2008 explicitly documents that +spurious wakeups may occur. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_cond_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_cond_destroy.3p new file mode 100644 index 0000000..ec8e263 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_cond_destroy.3p @@ -0,0 +1,236 @@ +'\" et +.TH PTHREAD_COND_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_cond_destroy, +pthread_cond_init +\(em destroy and initialize condition variables +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cond_destroy(pthread_cond_t *\fIcond\fP); +int pthread_cond_init(pthread_cond_t *restrict \fIcond\fP, + const pthread_condattr_t *restrict \fIattr\fP); +pthread_cond_t \fIcond\fP = PTHREAD_COND_INITIALIZER; +.fi +.SH DESCRIPTION +The +\fIpthread_cond_destroy\fR() +function shall destroy the given condition variable specified by +.IR cond ; +the object becomes, in effect, uninitialized. An implementation may +cause +\fIpthread_cond_destroy\fR() +to set the object referenced by +.IR cond +to an invalid value. A destroyed condition variable object can be +reinitialized using +\fIpthread_cond_init\fR(); +the results of otherwise referencing the object after it has been +destroyed are undefined. +.P +It shall be safe to destroy an initialized condition variable upon which +no threads are currently blocked. Attempting to destroy a condition +variable upon which other threads are currently blocked results in +undefined behavior. +.P +The +\fIpthread_cond_init\fR() +function shall initialize the condition variable referenced by +.IR cond +with attributes referenced by +.IR attr . +If +.IR attr +is NULL, the default condition variable attributes shall be used; the +effect is the same as passing the address of a default condition +variable attributes object. Upon successful initialization, the state +of the condition variable shall become initialized. +.P +Only +.IR cond +itself may be used for performing synchronization. The result of +referring to copies of +.IR cond +in calls to +\fIpthread_cond_wait\fR(), +\fIpthread_cond_timedwait\fR(), +\fIpthread_cond_signal\fR(), +\fIpthread_cond_broadcast\fR(), +and +\fIpthread_cond_destroy\fR() +is undefined. +.P +Attempting to initialize an already initialized condition variable +results in undefined behavior. +.P +In cases where default condition variable attributes are appropriate, +the macro PTHREAD_COND_INITIALIZER can be used to initialize condition +variables. The effect shall be equivalent to dynamic initialization by +a call to +\fIpthread_cond_init\fR() +with parameter +.IR attr +specified as NULL, except that no error checks are performed. +.P +The behavior is undefined if the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +does not refer to an initialized condition variable. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_cond_init\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_cond_destroy\fR() +and +\fIpthread_cond_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_cond_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources (other than memory) to +initialize another condition variable. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the condition variable. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +A condition variable can be destroyed immediately after all the threads +that are blocked on it are awakened. For example, consider the +following code: +.sp +.RS 4 +.nf +\fB +struct list { + pthread_mutex_t lm; + ... +} +.P +struct elt { + key k; + int busy; + pthread_cond_t notbusy; + ... +} +.P +/* Find a list element and reserve it. */ +struct elt * +list_find(struct list *lp, key k) +{ + struct elt *ep; +.P + pthread_mutex_lock(&lp->lm); + while ((ep = find_elt(l, k) != NULL) && ep->busy) + pthread_cond_wait(&ep->notbusy, &lp->lm); + if (ep != NULL) + ep->busy = 1; + pthread_mutex_unlock(&lp->lm); + return(ep); +} +.P +delete_elt(struct list *lp, struct elt *ep) +{ + pthread_mutex_lock(&lp->lm); + assert(ep->busy); + ... remove ep from list ... + ep->busy = 0; /* Paranoid. */ +(A) pthread_cond_broadcast(&ep->notbusy); + pthread_mutex_unlock(&lp->lm); +(B) pthread_cond_destroy(&rp->notbusy); + free(ep); +} +.fi \fR +.P +.RE +.P +In this example, the condition variable and its list element may be +freed (line B) immediately after all threads waiting for it are +awakened (line A), since the mutex and the code ensure that no other +thread can touch the element to be deleted. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +does not refer to an initialized condition variable, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +or +\fIpthread_cond_init\fR() +refers to a condition variable that is in use (for example, in a +\fIpthread_cond_wait\fR() +call) by another thread, or detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_init\fR() +refers to an already initialized condition variable, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_cond_init\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +See also +.IR "\fIpthread_mutex_destroy\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_broadcast\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_cond_signal.3p b/man-pages-posix-2013-a/man3p/pthread_cond_signal.3p new file mode 100644 index 0000000..c9af451 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_cond_signal.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_COND_SIGNAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_cond_signal +\(em signal a condition +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cond_signal(pthread_cond_t *\fIcond\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_cond_broadcast\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_cond_timedwait.3p b/man-pages-posix-2013-a/man3p/pthread_cond_timedwait.3p new file mode 100644 index 0000000..8dc4ba4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_cond_timedwait.3p @@ -0,0 +1,459 @@ +'\" et +.TH PTHREAD_COND_TIMEDWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_cond_timedwait, +pthread_cond_wait +\(em wait on a condition +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cond_timedwait(pthread_cond_t *restrict \fIcond\fP, + pthread_mutex_t *restrict \fImutex\fP, + const struct timespec *restrict \fIabstime\fP); +int pthread_cond_wait(pthread_cond_t *restrict \fIcond\fP, + pthread_mutex_t *restrict \fImutex\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_cond_timedwait\fR() +and +\fIpthread_cond_wait\fR() +functions shall block on a condition variable. The application shall +ensure that these functions are called with +.IR mutex +locked by the calling thread; otherwise, an error (for +PTHREAD_MUTEX_ERRORCHECK and robust mutexes) or undefined behavior +(for other mutexes) results. +.P +These functions atomically release +.IR mutex +and cause the calling thread to block on the condition variable +.IR cond ; +atomically here means ``atomically with respect to access by another +thread to the mutex and then the condition variable''. That is, if +another thread is able to acquire the mutex after the about-to-block +thread has released it, then a subsequent call to +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +in that thread shall behave as if it were issued after the +about-to-block thread has blocked. +.P +Upon successful return, the mutex shall have been locked and shall be +owned by the calling thread. If +.IR mutex +is a robust mutex where an owner terminated while holding the lock and +the state is recoverable, the mutex shall be acquired even though the +function returns an error code. +.P +When using condition variables there is always a Boolean predicate +involving shared variables associated with each condition wait that is +true if the thread should proceed. Spurious wakeups from the +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +functions may occur. Since the return from +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +does not imply anything about the value of this predicate, the +predicate should be re-evaluated upon such return. +.P +When a thread waits on a condition variable, having specified a +particular mutex to either the +\fIpthread_cond_timedwait\fR() +or the +\fIpthread_cond_wait\fR() +operation, a dynamic binding is formed between that mutex and condition +variable that remains in effect as long as at least one thread is +blocked on the condition variable. During this time, the effect of an +attempt by any thread to wait on that condition variable using a +different mutex is undefined. Once all waiting threads have been +unblocked (as by the +\fIpthread_cond_broadcast\fR() +operation), the next wait operation on that condition variable shall +form a new dynamic binding with the mutex specified by that wait +operation. Even though the dynamic binding between condition variable +and mutex may be removed or replaced between the time a thread is +unblocked from a wait on the condition variable and the time that it +returns to the caller or begins cancellation cleanup, the unblocked +thread shall always re-acquire the mutex specified in the condition +wait operation call from which it is returning. +.P +A condition wait (whether timed or not) is a cancellation point. When +the cancelability type of a thread is set to PTHREAD_CANCEL_DEFERRED, +a side-effect of acting upon a cancellation request while in a +condition wait is that the mutex is (in effect) re-acquired before +calling the first cancellation cleanup handler. The effect is as if +the thread were unblocked, allowed to execute up to the point of +returning from the call to +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR(), +but at that point notices the cancellation request and instead of +returning to the caller of +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR(), +starts the thread cancellation activities, which includes calling +cancellation cleanup handlers. +.P +A thread that has been unblocked because it has been canceled while +blocked in a call to +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +shall not consume any condition signal that may be directed concurrently +at the condition variable if there are other threads blocked on the +condition variable. +.P +The +\fIpthread_cond_timedwait\fR() +function shall be equivalent to +\fIpthread_cond_wait\fR(), +except that an error is returned if the absolute time specified by +.IR abstime +passes (that is, system time equals or exceeds +.IR abstime ) +before the condition +.IR cond +is signaled or broadcasted, or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. When such timeouts +occur, +\fIpthread_cond_timedwait\fR() +shall nonetheless release and re-acquire the mutex referenced by +.IR mutex , +and may consume a condition signal directed concurrently at the condition +variable. +.P +The condition variable shall have a clock attribute which specifies +the clock that shall be used to measure the time specified by the +.IR abstime +argument. The +\fIpthread_cond_timedwait\fR() +function is also a cancellation point. +.P +If a signal is delivered to a thread waiting for a condition variable, +upon return from the signal handler the thread resumes waiting for the +condition variable as if it was not interrupted, or it shall return +zero due to spurious wakeup. +.P +The behavior is undefined if the value specified by the +.IR cond +or +.IR mutex +argument to these functions does not refer to an initialized +condition variable or an initialized mutex object, respectively. +.SH "RETURN VALUE" +Except in the case of +.BR [ETIMEDOUT] , +all these error checks shall act as if they were performed immediately +at the beginning of processing for the function and shall cause an +error return, in effect, prior to modifying the state of the mutex +specified by +.IR mutex +or the condition variable specified by +.IR cond . +.P +Upon successful completion, a value of zero shall be returned; otherwise, +an error number shall be returned to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR ENOTRECOVERABLE +.br +The state protected by the mutex is not recoverable. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the process containing the previous +owning thread terminated while holding the mutex lock. The mutex lock +shall be acquired by the calling thread and it is up to the new owner +to make the state consistent. +.TP +.BR EPERM +The mutex type is PTHREAD_MUTEX_ERRORCHECK or the mutex +is a robust mutex, and the current thread does not own the mutex. +.P +The +\fIpthread_cond_timedwait\fR() +function shall fail if: +.TP +.BR ETIMEDOUT +The time specified by +.IR abstime +to +\fIpthread_cond_timedwait\fR() +has passed. +.TP +.BR EINVAL +The +.IR abstime +argument specified a nanosecond value less than zero or greater than +or equal to 1000 million. +.br +.P +These functions may fail if: +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the previous owning thread terminated +while holding the mutex lock. The mutex lock shall be acquired by the +calling thread and it is up to the new owner to make the state consistent. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications that have assumed that non-zero return values are errors +will need updating for use with robust mutexes, since a valid return +for a thread acquiring a mutex which is protecting a currently +inconsistent state is +.BR [EOWNERDEAD] . +Applications that do not check the error returns, due to ruling out the +possibility of such errors arising, should not use robust mutexes. If +an application is supposed to work with normal and robust mutexes, it +should check all return values for error conditions and if necessary +take appropriate action. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +does not refer to an initialized condition variable, or detects that +the value specified by the +.IR mutex +argument to +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +does not refer to an initialized mutex object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.SS "Condition Wait Semantics" +.P +It is important to note that when +\fIpthread_cond_wait\fR() +and +\fIpthread_cond_timedwait\fR() +return without error, the associated predicate may still be false. +Similarly, when +\fIpthread_cond_timedwait\fR() +returns with the timeout error, the associated predicate may be true +due to an unavoidable race between the expiration of the timeout and +the predicate state change. +.P +The application needs to recheck the predicate on any return because it +cannot be sure there is another thread waiting on the thread to handle +the signal, and if there is not then the signal is lost. The burden is +on the application to check the predicate. +.P +Some implementations, particularly on a multi-processor, may sometimes +cause multiple threads to wake up when the condition variable is +signaled simultaneously on different processors. +.P +In general, whenever a condition wait returns, the thread has to +re-evaluate the predicate associated with the condition wait to +determine whether it can safely proceed, should wait again, or should +declare a timeout. A return from the wait does not imply that the +associated predicate is either true or false. +.P +It is thus recommended that a condition wait be enclosed in the +equivalent of a ``while loop'' that checks the predicate. +.SS "Timed Wait Semantics" +.P +An absolute time measure was chosen for specifying the timeout +parameter for two reasons. First, a relative time measure can be +easily implemented on top of a function that specifies absolute time, +but there is a race condition associated with specifying an absolute +timeout on top of a function that specifies relative timeouts. For +example, assume that +\fIclock_gettime\fR() +returns the current time and +\fIcond_relative_timed_wait\fR() +uses relative timeouts: +.sp +.RS 4 +.nf +\fB +clock_gettime(CLOCK_REALTIME, &now) +reltime = sleep_til_this_absolute_time -now; +cond_relative_timed_wait(c, m, &reltime); +.fi \fR +.P +.RE +.P +If the thread is preempted between the first statement and the last +statement, +the thread blocks for too long. Blocking, however, is irrelevant if an +absolute timeout is used. An absolute timeout also need not be +recomputed if it is used multiple times in a loop, such as that +enclosing a condition wait. +.P +For cases when the system clock is advanced discontinuously by an +operator, it is expected that implementations process any timed wait +expiring at an intervening time as if that time had actually occurred. +.SS "Cancellation and Condition Wait" +.P +A condition wait, whether timed or not, is a cancellation point. That +is, the functions +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR() +are points where a pending (or concurrent) cancellation request is +noticed. The reason for this is that an indefinite wait is possible at +these points\(emwhatever event is being waited for, even if the program +is totally correct, might never occur; for example, some input data +being awaited might never be sent. By making condition wait a +cancellation point, the thread can be canceled and perform its +cancellation cleanup handler even though it may be stuck in some +indefinite wait. +.P +A side-effect of acting on a cancellation request while a thread is +blocked on a condition variable is to re-acquire the mutex before +calling any of the cancellation cleanup handlers. This is done in order +to ensure that the cancellation cleanup handler is executed in the same +state as the critical code that lies both before and after the call to +the condition wait function. This rule is also required when +interfacing to POSIX threads from languages, such as Ada or C++, which +may choose to map cancellation onto a language exception; this rule +ensures that each exception handler guarding a critical section can +always safely depend upon the fact that the associated mutex has +already been locked regardless of exactly where within the critical +section the exception was raised. Without this rule, there would not be +a uniform rule that exception handlers could follow regarding the lock, +and so coding would become very cumbersome. +.P +Therefore, since +.IR some +statement has to be made regarding the state of the lock when a +cancellation is delivered during a wait, a definition has been chosen +that makes application coding most convenient and error free. +.P +When acting on a cancellation request while a thread is blocked on a +condition variable, the implementation is required to ensure that the +thread does not consume any condition signals directed at that +condition variable if there are any other threads waiting on that +condition variable. This rule is specified in order to avoid deadlock +conditions that could occur if these two independent requests (one +acting on a thread and the other acting on the condition variable) were +not processed independently. +.SS "Performance of Mutexes and Condition Variables" +.P +Mutexes are expected to be locked only for a few instructions. This +practice is almost automatically enforced by the desire of programmers +to avoid long serial regions of execution (which would reduce total +effective parallelism). +.P +When using mutexes and condition variables, one tries to ensure that +the usual case is to lock the mutex, access shared data, and unlock the +mutex. Waiting on a condition variable should be a relatively rare +situation. For example, when implementing a read-write lock, code +that acquires a read-lock typically needs only to increment the count +of readers (under mutual-exclusion) and return. The calling thread +would actually wait on the condition variable only when there is +already an active writer. So the efficiency of a synchronization +operation is bounded by the cost of mutex lock/unlock and not by +condition wait. Note that in the usual case there is no context +switch. +.P +This is not to say that the efficiency of condition waiting is +unimportant. Since there needs to be at least one context switch per +Ada rendezvous, the efficiency of waiting on a condition variable is +important. The cost of waiting on a condition variable should be +little more than the minimal cost for a context switch plus the time to +unlock and lock the mutex. +.SS "Features of Mutexes and Condition Variables" +.P +It had been suggested that the mutex acquisition and release be +decoupled from condition wait. This was rejected because it is the +combined nature of the operation that, in fact, facilitates realtime +implementations. Those implementations can atomically move a +high-priority thread between the condition variable and the mutex in a +manner that is transparent to the caller. This can prevent extra +context switches and provide more deterministic acquisition of a mutex +when the waiting thread is signaled. Thus, fairness and priority +issues can be dealt with directly by the scheduling discipline. +Furthermore, the current condition wait operation matches existing +practice. +.SS "Scheduling Behavior of Mutexes and Condition Variables" +.P +Synchronization primitives that attempt to interfere with scheduling +policy by specifying an ordering rule are considered undesirable. +Threads waiting on mutexes and condition variables are selected to +proceed in an order dependent upon the scheduling policy rather than in +some fixed order (for example, FIFO or priority). Thus, the scheduling +policy determines which thread(s) are awakened and allowed to proceed. +.SS "Timed Condition Wait" +.P +The +\fIpthread_cond_timedwait\fR() +function allows an application to give up waiting for a particular +condition after a given amount of time. An example of its use +follows: +.sp +.RS 4 +.nf +\fB +(void) pthread_mutex_lock(&t.mn); + t.waiters++; + clock_gettime(CLOCK_REALTIME, &ts); + ts.tv_sec += 5; + rc = 0; + while (! mypredicate(&t) && rc == 0) + rc = pthread_cond_timedwait(&t.cond, &t.mn, &ts); + t.waiters-\|-; + if (rc == 0 || mypredicate(&t)) + setmystate(&t); +(void) pthread_mutex_unlock(&t.mn); +.fi \fR +.P +.RE +.P +By making the timeout parameter absolute, it does not need to be +recomputed each time the program checks its blocking predicate. If the +timeout was relative, it would have to be recomputed before each call. +This would be especially difficult since such code would need to take +into account the possibility of extra wakeups that result from extra +broadcasts or signals on the condition variable that occur before +either the predicate is true or the timeout is due. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_broadcast\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_condattr_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_condattr_destroy.3p new file mode 100644 index 0000000..ff58ec9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_condattr_destroy.3p @@ -0,0 +1,141 @@ +'\" et +.TH PTHREAD_CONDATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_condattr_destroy, +pthread_condattr_init +\(em destroy and initialize the condition variable attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_destroy(pthread_condattr_t *\fIattr\fP); +int pthread_condattr_init(pthread_condattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_condattr_destroy\fR() +function shall destroy a condition variable attributes object; the +object becomes, in effect, uninitialized. An implementation may cause +\fIpthread_condattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_condattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIpthread_condattr_init\fR() +function shall initialize a condition variable attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +Results are undefined if +\fIpthread_condattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +After a condition variable attributes object has been used to +initialize one or more condition variables, any function affecting the +attributes object (including destruction) shall not affect any +previously initialized condition variables. +.P +This volume of POSIX.1\(hy2008 requires two attributes, the +.IR clock +attribute and the +.IR process-shared +attribute. +.P +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_condattr_destroy\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_condattr_destroy\fR() +and +\fIpthread_condattr_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_condattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the condition variable +attributes object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +A +.IR process-shared +attribute has been defined for condition variables for the same reason +it has been defined for mutexes. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_condattr_destroy\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +See also +.IR "\fIpthread_attr_destroy\fR\^(\|)" +and +.IR "\fIpthread_mutex_destroy\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_condattr_getpshared\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_condattr_getclock.3p b/man-pages-posix-2013-a/man3p/pthread_condattr_getclock.3p new file mode 100644 index 0000000..40d71ed --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_condattr_getclock.3p @@ -0,0 +1,133 @@ +'\" et +.TH PTHREAD_CONDATTR_GETCLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_condattr_getclock, +pthread_condattr_setclock +\(em get and set the clock selection condition variable attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_getclock(const pthread_condattr_t *restrict \fIattr\fP, + clockid_t *restrict \fIclock_id\fP); +int pthread_condattr_setclock(pthread_condattr_t *\fIattr\fP, + clockid_t \fIclock_id\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_condattr_getclock\fR() +function shall obtain the value of the +.IR clock +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIpthread_condattr_setclock\fR() +function shall set the +.IR clock +attribute in an initialized attributes object referenced by +.IR attr . +If +\fIpthread_condattr_setclock\fR() +is called with a +.IR clock_id +argument that refers to a CPU-time clock, the call shall fail. +.P +The +.IR clock +attribute is the clock ID of the clock that shall be used to +measure the timeout service of +\fIpthread_cond_timedwait\fR(). +The default value of the +.IR clock +attribute shall refer to the system clock. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_condattr_getclock\fR() +or +\fIpthread_condattr_setclock\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_condattr_getclock\fR() +function shall return zero and store the value of the clock attribute +of +.IR attr +into the object referenced by the +.IR clock_id +argument. Otherwise, an error number shall be returned to indicate the +error. +.P +If successful, the +\fIpthread_condattr_setclock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_condattr_setclock\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by +.IR clock_id +does not refer to a known clock, or is a CPU-time clock. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_condattr_getclock\fR() +or +\fIpthread_condattr_setclock\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_condattr_destroy\fR\^(\|)", +.IR "\fIpthread_condattr_getpshared\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_condattr_getpshared.3p b/man-pages-posix-2013-a/man3p/pthread_condattr_getpshared.3p new file mode 100644 index 0000000..9fa1907 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_condattr_getpshared.3p @@ -0,0 +1,132 @@ +'\" et +.TH PTHREAD_CONDATTR_GETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_condattr_getpshared, +pthread_condattr_setpshared +\(em get and set the process-shared condition variable attributes +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_getpshared(const pthread_condattr_t *restrict \fIattr\fP, + int *restrict \fIpshared\fP); +int pthread_condattr_setpshared(pthread_condattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_condattr_getpshared\fR() +function shall obtain the value of the +.IR process-shared +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIpthread_condattr_setpshared\fR() +function shall set the +.IR process-shared +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR process-shared +attribute is set to PTHREAD_PROCESS_SHARED +to permit a condition variable to be operated upon by any thread that +has access to the memory where the condition variable is allocated, +even if the condition variable is allocated in memory that is shared by +multiple processes. If the +.IR process-shared +attribute is PTHREAD_PROCESS_PRIVATE, the condition variable +shall only be operated upon by threads created within the same process +as the thread that initialized the condition variable; if threads of +differing processes attempt to operate on such a condition variable, +the behavior is undefined. The default value of the attribute is +PTHREAD_PROCESS_PRIVATE. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_condattr_getpshared\fR() +or +\fIpthread_condattr_setpshared\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_condattr_setpshared\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.P +If successful, the +\fIpthread_condattr_getpshared\fR() +function shall return zero and store the value of the +.IR process-shared +attribute of +.IR attr +into the object referenced by the +.IR pshared +parameter. Otherwise, an error number shall be returned to indicate the +error. +.SH ERRORS +The +\fIpthread_condattr_setpshared\fR() +function may fail if: +.TP +.BR EINVAL +The new value specified for the attribute is outside the range of legal +values for that attribute. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_condattr_getpshared\fR() +or +\fIpthread_condattr_setpshared\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_condattr_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_condattr_init.3p b/man-pages-posix-2013-a/man3p/pthread_condattr_init.3p new file mode 100644 index 0000000..a6d63fb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_condattr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_CONDATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_condattr_init +\(em initialize the condition variable attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_init(pthread_condattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_condattr_destroy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_condattr_setclock.3p b/man-pages-posix-2013-a/man3p/pthread_condattr_setclock.3p new file mode 100644 index 0000000..b68bbc0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_condattr_setclock.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_CONDATTR_SETCLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_condattr_setclock +\(em set the clock selection condition variable attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_setclock(pthread_condattr_t *\fIattr\fP, + clockid_t \fIclock_id\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_condattr_getclock\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_condattr_setpshared.3p b/man-pages-posix-2013-a/man3p/pthread_condattr_setpshared.3p new file mode 100644 index 0000000..c2f85a2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_condattr_setpshared.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_CONDATTR_SETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_condattr_setpshared +\(em set the process-shared condition variable attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_setpshared(pthread_condattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_condattr_getpshared\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_create.3p b/man-pages-posix-2013-a/man3p/pthread_create.3p new file mode 100644 index 0000000..69bec24 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_create.3p @@ -0,0 +1,234 @@ +'\" et +.TH PTHREAD_CREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_create +\(em thread creation +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_create(pthread_t *restrict \fIthread\fP, + const pthread_attr_t *restrict \fIattr\fP, + void *(*\fIstart_routine\fP)(void*), void *restrict \fIarg\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_create\fR() +function shall create a new thread, with attributes specified by +.IR attr , +within a process. If +.IR attr +is NULL, the default attributes shall be used. If the attributes +specified by +.IR attr +are modified later, the thread's attributes shall not be affected. +Upon successful completion, +\fIpthread_create\fR() +shall store the ID of the created thread in the location referenced by +.IR thread . +.P +The thread is created executing +.IR start_routine +with +.IR arg +as its sole argument. If the +.IR start_routine +returns, the effect shall be as if there was an implicit call to +\fIpthread_exit\fR() +using the return value of +.IR start_routine +as the exit status. Note that the thread in which +\fImain\fR() +was originally invoked differs from this. When it returns from +\fImain\fR(), +the effect shall be as if there was an implicit call to +\fIexit\fR() +using the return value of +\fImain\fR() +as the exit status. +.P +The signal state of the new thread shall be initialized as follows: +.IP " *" 4 +The signal mask shall be inherited from the creating thread. +.IP " *" 4 +The set of signals pending for the new thread shall be empty. +.P +The thread-local current locale +and the alternate stack +shall not be inherited. +.P +The floating-point environment shall be inherited from the creating +thread. +.P +If +\fIpthread_create\fR() +fails, no new thread is created and the contents of the location +referenced by +.IR thread +are undefined. +.P +If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a +CPU-time clock accessible, and the initial value of this clock shall +be set to zero. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_create\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_create\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_create\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources to create another thread, or +the system-imposed limit on the total number of threads in a process +{PTHREAD_THREADS_MAX} +would be exceeded. +.TP +.BR EPERM +The caller does not have appropriate privileges to set the required +scheduling parameters or scheduling policy. +.P +The +\fIpthread_create\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +There is no requirement on the implementation that the ID of the +created thread be available before the newly created thread starts +executing. The calling thread can obtain the ID of the created thread +through the return value of the +\fIpthread_create\fR() +function, and the newly created thread can obtain its ID by a call to +\fIpthread_self\fR(). +.SH RATIONALE +A suggested alternative to +\fIpthread_create\fR() +would be to define two separate operations: create and start. Some +applications would find such behavior more natural. Ada, in +particular, separates the ``creation'' of a task from its +``activation''. +.P +Splitting the operation was rejected by the standard developers for +many reasons: +.IP " *" 4 +The number of calls required to start a thread would increase from one +to two and thus place an additional burden on applications that do not +require the additional synchronization. The second call, however, +could be avoided by the additional complication of a start-up state +attribute. +.IP " *" 4 +An extra state would be introduced: ``created but not started''. This +would require the standard to specify the behavior of the thread +operations when the target has not yet started executing. +.IP " *" 4 +For those applications that require such behavior, it is possible to +simulate the two separate steps with the facilities that are currently +provided. The +\fIstart_routine\fR() +can synchronize by waiting on a condition variable that is signaled by +the start operation. +.P +An Ada implementor can choose to create the thread at either of two +points in the Ada program: when the task object is created, or when +the task is activated (generally at a ``begin''). If the first +approach is adopted, the +\fIstart_routine\fR() +needs to wait on a condition variable to receive the order to begin +``activation''. The second approach requires no such condition +variable or extra synchronization. In either approach, a separate Ada +task control block would need to be created when the task object is +created to hold rendezvous queues, and so on. +.P +An extension of the preceding model would be to allow the state of the +thread to be modified between the create and start. This would allow +the thread attributes object to be eliminated. This has been rejected +because: +.IP " *" 4 +All state in the thread attributes object has to be able to be set for +the thread. This would require the definition of functions to modify +thread attributes. There would be no reduction in the number of +function calls required to set up the thread. In fact, for an +application that creates all threads using identical attributes, the +number of function calls required to set up the threads would be +dramatically increased. Use of a thread attributes object permits the +application to make one set of attribute setting function calls. +Otherwise, the set of attribute setting function calls needs to be made +for each thread creation. +.IP " *" 4 +Depending on the implementation architecture, functions to set thread +state would require kernel calls, or for other implementation reasons +would not be able to be implemented as macros, thereby increasing the +cost of thread creation. +.IP " *" 4 +The ability for applications to segregate threads by class would be +lost. +.P +Another suggested alternative uses a model similar to that for process +creation, such as ``thread fork''. The fork semantics would provide +more flexibility and the ``create'' function can be implemented simply +by doing a thread fork followed immediately by a call to the desired +``start routine'' for the thread. This alternative has these +problems: +.IP " *" 4 +For many implementations, the entire stack of the calling thread would +need to be duplicated, since in many architectures there is no way to +determine the size of the calling frame. +.IP " *" 4 +Efficiency is reduced since at least some part of the stack has to be +copied, even though in most cases the thread never needs the copied +context, since it merely calls the desired start routine. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_create\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfork\fR\^(\|)", +.IR "\fIpthread_exit\fR\^(\|)", +.IR "\fIpthread_join\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_detach.3p b/man-pages-posix-2013-a/man3p/pthread_detach.3p new file mode 100644 index 0000000..6d37157 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_detach.3p @@ -0,0 +1,119 @@ +'\" et +.TH PTHREAD_DETACH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_detach +\(em detach a thread +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_detach(pthread_t \fIthread\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_detach\fR() +function shall indicate to the implementation that storage for the +thread +.IR thread +can be reclaimed when that thread terminates. If +.IR thread +has not terminated, +\fIpthread_detach\fR() +shall not cause it to terminate. +.P +The behavior is undefined if the value specified by the +.IR thread +argument to +\fIpthread_detach\fR() +does not refer to a joinable thread. +.SH "RETURN VALUE" +If the call succeeds, +\fIpthread_detach\fR() +shall return 0; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_detach\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_join\fR() +or +\fIpthread_detach\fR() +functions should eventually be called for every thread that is created +so that storage associated with the thread may be reclaimed. +.P +It has been suggested that a ``detach'' function is not necessary; the +.IR detachstate +thread creation attribute is sufficient, since a thread need never be +dynamically detached. However, need arises in at least two cases: +.IP " 1." 4 +In a cancellation handler for a +\fIpthread_join\fR() +it is nearly essential to have a +\fIpthread_detach\fR() +function in order to detach the thread on which +\fIpthread_join\fR() +was waiting. Without it, it would be necessary to have the handler do +another +\fIpthread_join\fR() +to attempt to detach the thread, which would both delay the cancellation +processing for an unbounded period and introduce a new call to +\fIpthread_join\fR(), +which might itself need a cancellation handler. A dynamic detach is +nearly essential in this case. +.IP " 2." 4 +In order to detach the ``initial thread'' (as may be desirable in +processes that set up server threads). +.P +If an implementation detects that the value specified by the +.IR thread +argument to +\fIpthread_detach\fR() +does not refer to a joinable thread, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_join\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_equal.3p b/man-pages-posix-2013-a/man3p/pthread_equal.3p new file mode 100644 index 0000000..a3ff5f1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_equal.3p @@ -0,0 +1,86 @@ +'\" et +.TH PTHREAD_EQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_equal +\(em compare thread IDs +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_equal(pthread_t \fIt1\fP, pthread_t \fIt2\fP); +.fi +.SH DESCRIPTION +This function shall compare the thread IDs +.IR t1 +and +.IR t2 . +.SH "RETURN VALUE" +The +\fIpthread_equal\fR() +function shall return a non-zero value if +.IR t1 +and +.IR t2 +are equal; otherwise, zero shall be returned. +.P +If either +.IR t1 +or +.IR t2 +are not valid thread IDs, the behavior is undefined. +.SH ERRORS +No errors are defined. +.P +The +\fIpthread_equal\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Implementations may choose to define a +thread ID as a structure. This allows additional flexibility and +robustness over using an +.BR int . +For example, a thread ID could include a sequence number that allows +detection of ``dangling IDs'' (copies of a thread ID that has been +detached). Since the C language does not support comparison on +structure types, the +\fIpthread_equal\fR() +function is provided to compare thread IDs. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_self\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_exit.3p b/man-pages-posix-2013-a/man3p/pthread_exit.3p new file mode 100644 index 0000000..afad1a6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_exit.3p @@ -0,0 +1,127 @@ +'\" et +.TH PTHREAD_EXIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_exit +\(em thread termination +.SH SYNOPSIS +.LP +.nf +#include +.P +void pthread_exit(void *\fIvalue_ptr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_exit\fR() +function shall terminate the calling thread and make the value +.IR value_ptr +available to any successful join with the terminating thread. Any +cancellation cleanup handlers that have been pushed and not yet popped +shall be popped in the reverse order that they were pushed and then +executed. After all cancellation cleanup handlers have been executed, +if the thread has any thread-specific data, appropriate destructor +functions shall be called in an unspecified order. Thread termination +does not release any application visible process resources, including, +but not limited to, mutexes and file descriptors, nor does it perform +any process-level cleanup actions, including, but not limited to, +calling any +\fIatexit\fR() +routines that may exist. +.P +An implicit call to +\fIpthread_exit\fR() +is made when a thread other than the thread in which +\fImain\fR() +was first invoked returns from the start routine that was used to +create it. The function's return value shall serve as the thread's +exit status. +.P +The behavior of +\fIpthread_exit\fR() +is undefined if called from a cancellation cleanup handler or +destructor function that was invoked as a result of either an implicit +or explicit call to +\fIpthread_exit\fR(). +.P +After a thread has terminated, the result of access to local (auto) +variables of the thread is undefined. Thus, references to local +variables of the exiting thread should not be used for the +\fIpthread_exit\fR() +.IR value_ptr +parameter value. +.P +The process shall exit with an exit status of 0 after the last thread +has been terminated. The behavior shall be as if the implementation +called +\fIexit\fR() +with a zero argument at thread termination time. +.SH "RETURN VALUE" +The +\fIpthread_exit\fR() +function cannot return to its caller. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The normal mechanism by which a thread terminates is to return from the +routine that was specified in the +\fIpthread_create\fR() +call that started it. The +\fIpthread_exit\fR() +function provides the capability for a thread to terminate without +requiring a return from the start routine of that thread, thereby +providing a function analogous to +\fIexit\fR(). +.P +Regardless of the method of thread termination, any +cancellation cleanup handlers that have been pushed and not yet popped +are executed, and the destructors for any existing thread-specific data +are executed. This volume of POSIX.1\(hy2008 requires that cancellation cleanup handlers be +popped and called in order. After all cancellation cleanup handlers have +been executed, thread-specific data destructors are called, in an +unspecified order, for each item of thread-specific data that exists in +the thread. This ordering is necessary because cancellation cleanup +handlers may rely on thread-specific data. +.P +As the meaning of the status is determined by the application (except +when the thread has been canceled, in which case it is +PTHREAD_CANCELED), +the implementation has no idea what an illegal status value is, which +is why no address error checking is done. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexit\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_join\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_getconcurrency.3p b/man-pages-posix-2013-a/man3p/pthread_getconcurrency.3p new file mode 100644 index 0000000..4a1c9bd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_getconcurrency.3p @@ -0,0 +1,140 @@ +'\" et +.TH PTHREAD_GETCONCURRENCY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_getconcurrency, +pthread_setconcurrency +\(em get and set the level of concurrency +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_getconcurrency(void); +int pthread_setconcurrency(int \fInew_level\fP); +.fi +.SH DESCRIPTION +Unbound threads in a process may or may not be required to be +simultaneously active. By default, the threads implementation ensures +that a sufficient number of threads are active so that the process can +continue to make progress. While this conserves system resources, it +may not produce the most effective level of concurrency. +.P +The +\fIpthread_setconcurrency\fR() +function allows an application to inform the threads implementation of +its desired concurrency level, +.IR new_level . +The actual level of concurrency provided by the implementation as a +result of this function call is unspecified. +.P +If +.IR new_level +is zero, it causes the implementation to maintain the concurrency level +at its discretion as if +\fIpthread_setconcurrency\fR() +had never been called. +.P +The +\fIpthread_getconcurrency\fR() +function shall return the value set by a previous call to the +\fIpthread_setconcurrency\fR() +function. If the +\fIpthread_setconcurrency\fR() +function was not previously called, this function shall return zero to +indicate that the implementation is maintaining the concurrency level. +.P +A call to +\fIpthread_setconcurrency\fR() +shall inform the implementation of its desired concurrency level. +The implementation shall use this as a hint, not a requirement. +.P +If an implementation does not support multiplexing of user threads on +top of several kernel-scheduled entities, the +\fIpthread_setconcurrency\fR() +and +\fIpthread_getconcurrency\fR() +functions are provided for source code compatibility but they shall +have no effect when called. To maintain the function semantics, the +.IR new_level +parameter is saved when +\fIpthread_setconcurrency\fR() +is called so that a subsequent call to +\fIpthread_getconcurrency\fR() +shall return the same value. +.SH "RETURN VALUE" +If successful, the +\fIpthread_setconcurrency\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.P +The +\fIpthread_getconcurrency\fR() +function shall always return the concurrency level set by a previous +call to +\fIpthread_setconcurrency\fR(). +If the +\fIpthread_setconcurrency\fR() +function has never been called, +\fIpthread_getconcurrency\fR() +shall return zero. +.SH ERRORS +The +\fIpthread_setconcurrency\fR() +function shall fail if: +.TP +.BR EINVAL +The value specified by +.IR new_level +is negative. +.TP +.BR EAGAIN +The value specified by +.IR new_level +would cause a system resource to be exceeded. +.P +The +\fIpthread_setconcurrency\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Application developers should note that an implementation can always +ignore any calls to +\fIpthread_setconcurrency\fR() +and return a constant for +\fIpthread_getconcurrency\fR(). +For this reason, it is not recommended that portable applications +use this function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_getcpuclockid.3p b/man-pages-posix-2013-a/man3p/pthread_getcpuclockid.3p new file mode 100644 index 0000000..37bd8d7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_getcpuclockid.3p @@ -0,0 +1,78 @@ +'\" et +.TH PTHREAD_GETCPUCLOCKID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_getcpuclockid +\(em access a thread CPU-time clock +(\fBADVANCED REALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int pthread_getcpuclockid(pthread_t \fIthread_id\fP, clockid_t *\fIclock_id\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_getcpuclockid\fR() +function shall return in +.IR clock_id +the clock ID of the CPU-time clock of the thread specified by +.IR thread_id , +if the thread specified by +.IR thread_id +exists. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_getcpuclockid\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_getcpuclockid\fR() +function is part of the Thread CPU-Time Clocks option and need not be +provided on all implementations. +.SH RATIONALE +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getcpuclockid\fR\^(\|)", +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_getschedparam.3p b/man-pages-posix-2013-a/man3p/pthread_getschedparam.3p new file mode 100644 index 0000000..1d36dd7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_getschedparam.3p @@ -0,0 +1,193 @@ +'\" et +.TH PTHREAD_GETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_getschedparam, +pthread_setschedparam +\(em dynamic thread scheduling parameters access +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_getschedparam(pthread_t \fIthread\fP, int *restrict \fIpolicy\fP, + struct sched_param *restrict \fIparam\fP); +int pthread_setschedparam(pthread_t \fIthread\fP, int \fIpolicy\fP, + const struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_getschedparam\fR() +and +\fIpthread_setschedparam\fR() +functions shall, respectively, get and set the scheduling policy and +parameters of individual threads within a multi-threaded process to be +retrieved and set. For SCHED_FIFO and SCHED_RR, +the only required member of the +.BR sched_param +structure is the priority +.IR sched_priority . +For SCHED_OTHER, +the affected scheduling parameters are implementation-defined. +.P +The +\fIpthread_getschedparam\fR() +function shall retrieve the scheduling policy and scheduling parameters +for the thread whose thread ID is given by +.IR thread +and shall store those values in +.IR policy +and +.IR param , +respectively. The priority value returned from +\fIpthread_getschedparam\fR() +shall be the value specified by the most recent +\fIpthread_setschedparam\fR(), +\fIpthread_setschedprio\fR(), +or +\fIpthread_create\fR() +call affecting the target thread. It shall not reflect any temporary +adjustments to its priority as a result of any priority inheritance or +ceiling functions. The +\fIpthread_setschedparam\fR() +function shall set the scheduling policy and associated scheduling +parameters for the thread whose thread ID is given by +.IR thread +to the policy and associated parameters provided in +.IR policy +and +.IR param , +respectively. +.P +The +.IR policy +parameter may have the value SCHED_OTHER, SCHED_FIFO, or SCHED_RR. The +scheduling parameters for the SCHED_OTHER policy are +implementation-defined. The SCHED_FIFO and SCHED_RR policies shall +have a single scheduling parameter, +.IR priority . +.P +If _POSIX_THREAD_SPORADIC_SERVER is defined, then the +.IR policy +argument may have the value SCHED_SPORADIC, with the exception for the +\fIpthread_setschedparam\fR() +function that if the scheduling policy was not SCHED_SPORADIC at the +time of the call, it is implementation-defined whether the function +is supported; in other words, the implementation need not allow the +application to dynamically change the scheduling policy to +SCHED_SPORADIC. The sporadic server scheduling policy has the +associated parameters +.IR sched_ss_low_priority , +.IR sched_ss_repl_period , +.IR sched_ss_init_budget , +.IR sched_priority , +and +.IR sched_ss_max_repl . +The specified +.IR sched_ss_repl_period +shall be greater than or equal to the specified +.IR sched_ss_init_budget +for the function to succeed; if it is not, then the function shall +fail. The value of +.IR sched_ss_max_repl +shall be within the inclusive range [1,\c +{SS_REPL_MAX}] +for the function to succeed; if not, the function shall fail. +It is unspecified whether the +.IR sched_ss_repl_period +and +.IR sched_ss_init_budget +values are stored as provided by this function or are rounded to +align with the resolution of the clock being used. +.P +If the +\fIpthread_setschedparam\fR() +function fails, the scheduling parameters shall not be changed +for the target thread. +.SH "RETURN VALUE" +If successful, the +\fIpthread_getschedparam\fR() +and +\fIpthread_setschedparam\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_setschedparam\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the policy or scheduling parameters to an +unsupported value. +.TP +.BR ENOTSUP +An attempt was made to dynamically change the scheduling policy to +SCHED_SPORADIC, and the implementation does not support this change. +.P +The +\fIpthread_setschedparam\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by +.IR policy +or one of the scheduling parameters associated with the scheduling +policy +.IR policy +is invalid. +.TP +.BR EPERM +The caller does not have appropriate privileges to set either the +scheduling parameters or the scheduling policy of the specified +thread. +.TP +.BR EPERM +The implementation does not allow the application to modify +one of the parameters to the value specified. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_setschedprio\fR\^(\|)", +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_getspecific.3p b/man-pages-posix-2013-a/man3p/pthread_getspecific.3p new file mode 100644 index 0000000..e8d6b4c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_getspecific.3p @@ -0,0 +1,151 @@ +'\" et +.TH PTHREAD_GETSPECIFIC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_getspecific, +pthread_setspecific +\(em thread-specific data management +.SH SYNOPSIS +.LP +.nf +#include +.P +void *pthread_getspecific(pthread_key_t \fIkey\fP); +int pthread_setspecific(pthread_key_t \fIkey\fP, const void *\fIvalue\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_getspecific\fR() +function shall return the value currently bound to the specified +.IR key +on behalf of the calling thread. +.P +The +\fIpthread_setspecific\fR() +function shall associate a thread-specific +.IR value +with a +.IR key +obtained via a previous call to +\fIpthread_key_create\fR(). +Different threads may bind different values to the same key. These +values are typically pointers to blocks of dynamically allocated memory +that have been reserved for use by the calling thread. +.P +The effect of calling +\fIpthread_getspecific\fR() +or +\fIpthread_setspecific\fR() +with a +.IR key +value not obtained from +\fIpthread_key_create\fR() +or after +.IR key +has been deleted with +\fIpthread_key_delete\fR() +is undefined. +.P +Both +\fIpthread_getspecific\fR() +and +\fIpthread_setspecific\fR() +may be called from a thread-specific data destructor function. A call +to +\fIpthread_getspecific\fR() +for the thread-specific data key being destroyed shall return the value +NULL, unless the value is changed (after the destructor starts) by a +call to +\fIpthread_setspecific\fR(). +Calling +\fIpthread_setspecific\fR() +from a thread-specific data destructor routine may result either in lost +storage (after at least PTHREAD_DESTRUCTOR_ITERATIONS attempts at +destruction) or in an infinite loop. +.P +Both functions may be implemented as macros. +.SH "RETURN VALUE" +The +\fIpthread_getspecific\fR() +function shall return the thread-specific data value associated +with the given +.IR key . +If no thread-specific data value is associated with +.IR key , +then the value NULL shall be returned. +.P +If successful, the +\fIpthread_setspecific\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +No errors are returned from +\fIpthread_getspecific\fR(). +.P +The +\fIpthread_setspecific\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to associate the non-NULL value with the key. +.P +The +\fIpthread_setspecific\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Performance and ease-of-use of +\fIpthread_getspecific\fR() +are critical for functions that rely on maintaining state in +thread-specific data. Since no errors are required to be detected by +it, and since the only error that could be detected is the use of an +invalid key, the function to +\fIpthread_getspecific\fR() +has been designed to favor speed and simplicity over error reporting. +.P +If an implementation detects that the value specified by the +.IR key +argument to +\fIpthread_setspecific\fR() +does not refer to a a key value obtained from +\fIpthread_key_create\fR() +or refers to a key that has been deleted with +\fIpthread_key_delete\fR(), +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_key_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_join.3p b/man-pages-posix-2013-a/man3p/pthread_join.3p new file mode 100644 index 0000000..5ba8bf3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_join.3p @@ -0,0 +1,230 @@ +'\" et +.TH PTHREAD_JOIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_join +\(em wait for thread termination +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_join(pthread_t \fIthread\fP, void **\fIvalue_ptr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_join\fR() +function shall suspend execution of the calling thread until the target +.IR thread +terminates, unless the target +.IR thread +has already terminated. On return from a successful +\fIpthread_join\fR() +call with a non-NULL +.IR value_ptr +argument, the value passed to +\fIpthread_exit\fR() +by the terminating thread shall be made available in the location +referenced by +.IR value_ptr . +When a +\fIpthread_join\fR() +returns successfully, the target thread has been terminated. The +results of multiple simultaneous calls to +\fIpthread_join\fR() +specifying the same target thread are undefined. If the thread calling +\fIpthread_join\fR() +is canceled, then the target thread shall not be detached. +.P +It is unspecified whether a thread that has exited but remains unjoined +counts against +{PTHREAD_THREADS_MAX}. +.P +The behavior is undefined if the value specified by the +.IR thread +argument to +\fIpthread_join\fR() +does not refer to a joinable thread. +.P +The behavior is undefined if the value specified by the +.IR thread +argument to +\fIpthread_join\fR() +refers to the calling thread. +.SH "RETURN VALUE" +If successful, the +\fIpthread_join\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_join\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock was detected. +.P +The +\fIpthread_join\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +An example of thread creation and deletion follows: +.sp +.RS 4 +.nf +\fB +typedef struct { + int *ar; + long n; +} subarray; +.P +void * +incer(void *arg) +{ + long i; +.P + for (i = 0; i < ((subarray *)arg)->n; i++) + ((subarray *)arg)->ar[i]++; +} +.P +int main(void) +{ + int ar[1000000]; + pthread_t th1, th2; + subarray sb1, sb2; +.P + sb1.ar = &ar[0]; + sb1.n = 500000; + (void) pthread_create(&th1, NULL, incer, &sb1); +.P + sb2.ar = &ar[500000]; + sb2.n = 500000; + (void) pthread_create(&th2, NULL, incer, &sb2); +.P + (void) pthread_join(th1, NULL); + (void) pthread_join(th2, NULL); + return 0; +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_join\fR() +function is a convenience that has proven useful in multi-threaded +applications. It is true that a programmer could simulate this +function if it were not provided by passing extra state as part of the +argument to the +\fIstart_routine\fR(). +The terminating thread would set a flag to indicate termination and +broadcast a condition that is part of that state; a joining thread +would wait on that condition variable. While such a technique would +allow a thread to wait on more complex conditions (for example, waiting +for multiple threads to terminate), waiting on individual thread +termination is considered widely useful. Also, including the +\fIpthread_join\fR() +function in no way precludes a programmer from coding such complex +waits. Thus, while not a primitive, including +\fIpthread_join\fR() +in this volume of POSIX.1\(hy2008 was considered valuable. +.P +The +\fIpthread_join\fR() +function provides a simple mechanism allowing an application to wait +for a thread to terminate. After the thread terminates, the +application may then choose to clean up resources that were used by the +thread. For instance, after +\fIpthread_join\fR() +returns, any application-provided stack storage could be reclaimed. +.P +The +\fIpthread_join\fR() +or +\fIpthread_detach\fR() +function should eventually be called for every thread that is created +with the +.IR detachstate +attribute set to PTHREAD_CREATE_JOINABLE +so that storage associated with the thread may be reclaimed. +.P +The interaction between +\fIpthread_join\fR() +and cancellation is well-defined for the following reasons: +.IP " *" 4 +The +\fIpthread_join\fR() +function, like all other non-async-cancel-safe functions, can only be +called with +deferred cancelability type. +.IP " *" 4 +Cancellation cannot occur in the disabled cancelability state. +.P +Thus, only the default cancelability state need be considered. As +specified, either the +\fIpthread_join\fR() +call is canceled, or it succeeds, but not both. The difference is +obvious to the application, since either a cancellation handler is run +or +\fIpthread_join\fR() +returns. There are no race conditions since +\fIpthread_join\fR() +was called in the deferred cancelability state. +.P +If an implementation detects that the value specified by the +.IR thread +argument to +\fIpthread_join\fR() +does not refer to a joinable thread, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR thread +argument to +\fIpthread_join\fR() +refers to the calling thread, it is recommended that the function +should fail and report an +.BR [EDEADLK] +error. +.P +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_key_create.3p b/man-pages-posix-2013-a/man3p/pthread_key_create.3p new file mode 100644 index 0000000..9fd2bc8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_key_create.3p @@ -0,0 +1,261 @@ +'\" et +.TH PTHREAD_KEY_CREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_key_create +\(em thread-specific data key creation +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_key_create(pthread_key_t *\fIkey\fP, void (*\fIdestructor\fP)(void*)); +.fi +.SH DESCRIPTION +The +\fIpthread_key_create\fR() +function shall create a thread-specific data key visible to all threads +in the process. Key values provided by +\fIpthread_key_create\fR() +are opaque objects used to locate thread-specific data. Although the +same key value may be used by different threads, the values bound to +the key by +\fIpthread_setspecific\fR() +are maintained on a per-thread basis and persist for the life of the +calling thread. +.P +Upon key creation, the value NULL shall be associated with the new key +in all active threads. Upon thread creation, the value NULL shall be +associated with all defined keys in the new thread. +.P +An optional destructor function may be associated with each key value. +At thread exit, if a key value has a non-NULL destructor pointer, and +the thread has a non-NULL value associated with that key, the value of +the key is set to NULL, and then the function pointed to is called with +the previously associated value as its sole argument. The order of +destructor calls is unspecified if more than one destructor exists for +a thread when it exits. +.P +If, after all the destructors have been called for all non-NULL values +with associated destructors, there are still some non-NULL values with +associated destructors, then the process is repeated. If, after at +least +{PTHREAD_DESTRUCTOR_ITERATIONS} +iterations of destructor calls for outstanding non-NULL values, there +are still some non-NULL values with associated destructors, +implementations may stop calling destructors, or they may continue +calling destructors until no non-NULL values with associated +destructors exist, even though this might result in an infinite loop. +.SH "RETURN VALUE" +If successful, the +\fIpthread_key_create\fR() +function shall store the newly created key value at *\fIkey\fP and +shall return zero. Otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_key_create\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources to create another +thread-specific data key, or the system-imposed limit on the total +number of keys per process +{PTHREAD_KEYS_MAX} +has been exceeded. +.TP +.BR ENOMEM +Insufficient memory exists to create the key. +.P +The +\fIpthread_key_create\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example demonstrates a function that initializes a +thread-specific data key when it is first called, and associates a +thread-specific object with each calling thread, initializing this +object when necessary. +.sp +.RS 4 +.nf +\fB +static pthread_key_t key; +static pthread_once_t key_once = PTHREAD_ONCE_INIT; +.P +static void +make_key() +{ + (void) pthread_key_create(&key, NULL); +} +.P +func() +{ + void *ptr; +.P + (void) pthread_once(&key_once, make_key); + if ((ptr = pthread_getspecific(key)) == NULL) { + ptr = malloc(OBJECT_SIZE); + ... + (void) pthread_setspecific(key, ptr); + } + ... +} +.fi \fR +.P +.RE +.P +Note that the key has to be initialized before +\fIpthread_getspecific\fR() +or +\fIpthread_setspecific\fR() +can be used. The +\fIpthread_key_create\fR() +call could either be explicitly made in a module initialization +routine, or it can be done implicitly by the first call to a module as +in this example. Any attempt to use the key before it is initialized +is a programming error, making the code below incorrect. +.sp +.RS 4 +.nf +\fB +static pthread_key_t key; +.P +func() +{ + void *ptr; +.P + /* KEY NOT INITIALIZED!!! THIS WON'T WORK!!! */ + if ((ptr = pthread_getspecific(key)) == NULL && + pthread_setspecific(key, NULL) != 0) { + pthread_key_create(&key, NULL); + ... + } +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.br +.SH RATIONALE +.SS "Destructor Functions" +.P +Normally, the value bound to a key on behalf of a particular thread is +a pointer to storage allocated dynamically on behalf of the calling +thread. The destructor functions specified with +\fIpthread_key_create\fR() +are intended to be used to free this storage when the thread exits. +Thread +cancellation cleanup handlers cannot be used for this purpose because +thread-specific data may persist outside the lexical scope in which the +cancellation cleanup handlers operate. +.P +If the value associated with a key needs to be updated during the +lifetime of the thread, it may be necessary to release the storage +associated with the old value before the new value is bound. Although +the +\fIpthread_setspecific\fR() +function could do this automatically, this feature is not needed often +enough to justify the added complexity. Instead, the programmer is +responsible for freeing the stale storage: +.sp +.RS 4 +.nf +\fB +pthread_getspecific(key, &old); +new = allocate(); +destructor(old); +pthread_setspecific(key, new); +.fi \fR +.P +.RE +.TP 10 +.BR Note: +The above example could leak storage if run with asynchronous +cancellation enabled. No such problems occur in the default cancellation +state if no cancellation points occur between the get and set. +.P +.P +There is no notion of a destructor-safe function. If an application +does not call +\fIpthread_exit\fR() +from a signal handler, or if it blocks any signal whose handler may +call +\fIpthread_exit\fR() +while calling async-unsafe functions, all functions may be safely +called from destructors. +.SS "Non-Idempotent Data Key Creation" +.P +There were requests to make +\fIpthread_key_create\fR() +idempotent with respect to a given +.IR key +address parameter. This would allow applications to call +\fIpthread_key_create\fR() +multiple times for a given +.IR key +address and be guaranteed that only one key would be created. Doing so +would require the key value to be previously initialized (possibly at +compile time) to a known null value and would require that implicit +mutual-exclusion be performed based on the address and contents of the +.IR key +parameter in order to guarantee that exactly one key would be created. +.P +Unfortunately, the implicit mutual-exclusion would not be limited to +only +\fIpthread_key_create\fR(). +On many implementations, implicit mutual-exclusion would also have to +be performed by +\fIpthread_getspecific\fR() +and +\fIpthread_setspecific\fR() +in order to guard against using incompletely stored or not-yet-visible +key values. This could significantly increase the cost of important +operations, particularly +\fIpthread_getspecific\fR(). +.P +Thus, this proposal was rejected. The +\fIpthread_key_create\fR() +function performs no implicit synchronization. It is the +responsibility of the programmer to ensure that it is called exactly +once per key before use of the key. Several straightforward mechanisms +can already be used to accomplish this, including calling explicit +module initialization functions, using mutexes, and using +\fIpthread_once\fR(). +This places no significant burden on the programmer, introduces no +possibly confusing \fIad hoc\fP implicit synchronization mechanism, and +potentially allows commonly used thread-specific data operations to be +more efficient. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_getspecific\fR\^(\|)", +.IR "\fIpthread_key_delete\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_key_delete.3p b/man-pages-posix-2013-a/man3p/pthread_key_delete.3p new file mode 100644 index 0000000..4eca083 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_key_delete.3p @@ -0,0 +1,139 @@ +'\" et +.TH PTHREAD_KEY_DELETE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_key_delete +\(em thread-specific data key deletion +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_key_delete(pthread_key_t \fIkey\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_key_delete\fR() +function shall delete a thread-specific data key previously returned by +\fIpthread_key_create\fR(). +The thread-specific data values associated with +.IR key +need not be NULL at the time +\fIpthread_key_delete\fR() +is called. It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific data in any +threads; this cleanup can be done either before or after +\fIpthread_key_delete\fR() +is called. Any attempt to use +.IR key +following the call to +\fIpthread_key_delete\fR() +results in undefined behavior. +.P +The +\fIpthread_key_delete\fR() +function shall be callable from within destructor functions. No +destructor functions shall be invoked by +\fIpthread_key_delete\fR(). +Any destructor function that may have been associated with +.IR key +shall no longer be called upon thread exit. +.SH "RETURN VALUE" +If successful, the +\fIpthread_key_delete\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_key_delete\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +A thread-specific data key deletion function has been included in order +to allow the resources associated with an unused thread-specific data +key to be freed. Unused thread-specific data keys can arise, among +other scenarios, when a dynamically loaded module that allocated a key +is unloaded. +.P +Conforming applications are responsible for performing any cleanup +actions needed for data structures associated with the key to be +deleted, including data referenced by thread-specific data values. No +such cleanup is done by +\fIpthread_key_delete\fR(). +In particular, destructor functions are not called. There are several +reasons for this division of responsibility: +.IP " 1." 4 +The associated destructor functions used to free thread-specific data +at thread exit time are only guaranteed to work correctly when called +in the thread that allocated the thread-specific data. (Destructors +themselves may utilize thread-specific data.) Thus, they cannot be used +to free thread-specific data in other threads at key deletion time. +Attempting to have them called by other threads at key deletion time +would require other threads to be asynchronously interrupted. But +since interrupted threads could be in an arbitrary state, including +holding locks necessary for the destructor to run, this approach would +fail. In general, there is no safe mechanism whereby an implementation +could free thread-specific data at key deletion time. +.IP " 2." 4 +Even if there were a means of safely freeing thread-specific data +associated with keys to be deleted, doing so would require that +implementations be able to enumerate the threads with non-NULL data and +potentially keep them from creating more thread-specific data while the +key deletion is occurring. This special case could cause extra +synchronization in the normal case, which would otherwise be +unnecessary. +.P +For an application to know that it is safe to delete a key, it has to +know that all the threads that might potentially ever use the key do +not attempt to use it again. For example, it could know this if all +the client threads have called a cleanup procedure declaring that they +are through with the module that is being shut down, perhaps by setting +a reference count to zero. +.P +If an implementation detects that the value specified by the +.IR key +argument to +\fIpthread_key_delete\fR() +does not refer to a a key value obtained from +\fIpthread_key_create\fR() +or refers to a key that has been deleted with +\fIpthread_key_delete\fR(), +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_key_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_kill.3p b/man-pages-posix-2013-a/man3p/pthread_kill.3p new file mode 100644 index 0000000..fa06e14 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_kill.3p @@ -0,0 +1,97 @@ +'\" et +.TH PTHREAD_KILL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_kill +\(em send a signal to a thread +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_kill(pthread_t \fIthread\fP, int \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_kill\fR() +function shall request that a signal be delivered to the specified +thread. +.P +As in +\fIkill\fR(), +if +.IR sig +is zero, error checking shall be performed but no signal shall +actually be sent. +.SH "RETURN VALUE" +Upon successful completion, the function shall return a value of zero. +Otherwise, the function shall return an error number. If the +\fIpthread_kill\fR() +function fails, no signal shall be sent. +.SH ERRORS +The +\fIpthread_kill\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR sig +argument is an invalid or unsupported signal number. +.P +The +\fIpthread_kill\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_kill\fR() +function provides a mechanism for asynchronously directing a signal at +a thread in the calling process. This could be used, for example, by +one thread to affect broadcast delivery of a signal to a set of +threads. +.P +Note that +\fIpthread_kill\fR() +only causes the signal to be handled in the context of the given +thread; the signal action (termination or stopping) affects the +process as a whole. +.SH RATIONALE +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIkill\fR\^(\|)", +.IR "\fIpthread_self\fR\^(\|)", +.IR "\fIraise\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutex_consistent.3p b/man-pages-posix-2013-a/man3p/pthread_mutex_consistent.3p new file mode 100644 index 0000000..177bbd9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutex_consistent.3p @@ -0,0 +1,120 @@ +'\" et +.TH PTHREAD_MUTEX_CONSISTENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutex_consistent \(em +mark state protected by robust mutex as consistent +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_consistent(pthread_mutex_t *\fImutex\fP); +.fi +.SH DESCRIPTION +If +.IR mutex +is a robust mutex in an inconsistent state, the +\fIpthread_mutex_consistent\fR() +function can be used to mark the state protected by the mutex +referenced by +.IR mutex +as consistent again. +.P +If an owner of a robust mutex terminates while holding the mutex, the +mutex becomes inconsistent and the next thread that acquires the mutex +lock shall be notified of the state by the return value +.BR [EOWNERDEAD] . +In this case, the mutex does not become normally usable again until the +state is marked consistent. +.P +If the thread which acquired the mutex lock with the return value +.BR [EOWNERDEAD] +terminates before calling either +\fIpthread_mutex_consistent\fR() +or +\fIpthread_mutex_unlock\fR(), +the next thread that acquires the mutex lock shall be notified about +the state of the mutex by the return value +.BR [EOWNERDEAD] . +.P +The behavior is undefined if the value specified by the +.IR mutex +argument to +\fIpthread_mutex_consistent\fR() +does not refer to an initialized mutex. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutex_consistent\fR() +function shall return zero. Otherwise, an error value shall be returned +to indicate the error. +.SH ERRORS +The +\fIpthread_mutex_consistent\fR() +function shall fail if: +.TP +.BR EINVAL +The mutex object referenced by +.IR mutex +is not robust or does not protect an inconsistent state. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_mutex_consistent\fR() +function is only responsible for notifying the implementation that the +state protected by the mutex has been recovered and that normal +operations with the mutex can be resumed. It is the responsibility of +the application to recover the state so it can be reused. If the +application is not able to perform the recovery, it can notify the +implementation that the situation is unrecoverable by a call to +\fIpthread_mutex_unlock\fR() +without a prior call to +\fIpthread_mutex_consistent\fR(), +in which case subsequent threads that attempt to lock the mutex will +fail to acquire the lock and be returned +.BR [ENOTRECOVERABLE] . +.SH RATIONALE +If an implementation detects that the value specified by the +.IR mutex +argument to +\fIpthread_mutex_consistent\fR() +does not refer to an initialized mutex, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutex_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_mutex_destroy.3p new file mode 100644 index 0000000..c8b22d6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutex_destroy.3p @@ -0,0 +1,455 @@ +'\" et +.TH PTHREAD_MUTEX_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutex_destroy, +pthread_mutex_init +\(em destroy and initialize a mutex +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_destroy(pthread_mutex_t *\fImutex\fP); +int pthread_mutex_init(pthread_mutex_t *restrict \fImutex\fP, + const pthread_mutexattr_t *restrict \fIattr\fP); +pthread_mutex_t \fImutex\fP = PTHREAD_MUTEX_INITIALIZER; +.fi +.SH DESCRIPTION +The +\fIpthread_mutex_destroy\fR() +function shall destroy the mutex object referenced by +.IR mutex ; +the mutex object becomes, in effect, uninitialized. An implementation +may cause +\fIpthread_mutex_destroy\fR() +to set the object referenced by +.IR mutex +to an invalid value. +.P +A destroyed mutex object can be reinitialized using +\fIpthread_mutex_init\fR(); +the results of otherwise referencing the object after it has been +destroyed are undefined. +.P +It shall be safe to destroy an initialized mutex that is unlocked. +Attempting to destroy a locked mutex or a mutex that is referenced +(for example, while being used in a +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR()) +by another thread results in undefined behavior. +.P +The +\fIpthread_mutex_init\fR() +function shall initialize the mutex referenced by +.IR mutex +with attributes specified by +.IR attr . +If +.IR attr +is NULL, the default mutex attributes are used; the effect shall be the +same as passing the address of a default mutex attributes object. Upon +successful initialization, the state of the mutex becomes initialized +and unlocked. +.P +Only +.IR mutex +itself may be used for performing synchronization. The result of +referring to copies of +.IR mutex +in calls to +\fIpthread_mutex_lock\fR(), +\fIpthread_mutex_trylock\fR(), +\fIpthread_mutex_unlock\fR(), +and +\fIpthread_mutex_destroy\fR() +is undefined. +.P +Attempting to initialize an already initialized mutex results in +undefined behavior. +.P +In cases where default mutex attributes are appropriate, the macro +PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes. The +effect shall be equivalent to dynamic initialization by a call to +\fIpthread_mutex_init\fR() +with parameter +.IR attr +specified as NULL, except that no error checks are performed. +.P +The behavior is undefined if the value specified by the +.IR mutex +argument to +\fIpthread_mutex_destroy\fR() +does not refer to an initialized mutex. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutex_init\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_mutex_destroy\fR() +and +\fIpthread_mutex_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutex_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources (other than memory) to +initialize another mutex. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the mutex. +.TP +.BR EPERM +The caller does not have the privilege to perform the operation. +.br +.P +The +\fIpthread_mutex_init\fR() +function may fail if: +.TP +.BR EINVAL +The attributes object referenced by +.IR attr +has the robust mutex attribute set without the process-shared attribute +being set. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR mutex +argument to +\fIpthread_mutex_destroy\fR() +does not refer to an initialized mutex, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR mutex +argument to +\fIpthread_mutex_destroy\fR() +or +\fIpthread_mutex_init\fR() +refers to a locked mutex or a mutex that is referenced (for example, +while being used in a +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR()) +by another thread, or detects that the value specified by the +.IR mutex +argument to +\fIpthread_mutex_init\fR() +refers to an already initialized mutex, it is recommended that the +function should fail and report an +.BR [EBUSY] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutex_init\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SS "Alternate Implementations Possible" +.P +This volume of POSIX.1\(hy2008 supports several alternative implementations of mutexes. +An implementation may store the lock directly in the object of type +.BR pthread_mutex_t . +Alternatively, an implementation may store the lock in the heap and +merely store a pointer, handle, or unique ID in the mutex object. +Either implementation has advantages or may be required on certain +hardware configurations. So that portable code can be written that is +invariant to this choice, this volume of POSIX.1\(hy2008 does not define assignment or +equality for this type, and it uses the term ``initialize'' to +reinforce the (more restrictive) notion that the lock may actually +reside in the mutex object itself. +.P +Note that this precludes an over-specification of the type of the mutex +or condition variable and motivates the opaqueness of the type. +.P +An implementation is permitted, but not required, to have +\fIpthread_mutex_destroy\fR() +store an illegal value into the mutex. This may help detect erroneous +programs that try to lock (or otherwise reference) a mutex that has +already been destroyed. +.SS "Tradeoff Between Error Checks and Performance Supported" +.P +Many error conditions that can occur are not required to be detected by +the implementation in order to let implementations trade off performance +\fIversus\fR degree of error checking according to the needs of their +specific applications and execution environment. As a general rule, +conditions caused by the system (such as insufficient memory) are required +to be detected, but conditions caused by an erroneously coded application +(such as failing to provide adequate synchronization to prevent a mutex +from being deleted while in use) are specified to result in undefined +behavior. +.P +A wide range of implementations is thus made possible. For example, an +implementation intended for application debugging may implement all of +the error checks, but an implementation running a single, provably +correct application under very tight performance constraints in an +embedded computer might implement minimal checks. An implementation +might even be provided in two versions, similar to the options that +compilers provide: a full-checking, but slower version; and a +limited-checking, but faster version. To forbid this optionality would +be a disservice to users. +.P +By carefully limiting the use of ``undefined behavior'' only to things +that an erroneous (badly coded) application might do, and by defining +that resource-not-available errors are mandatory, this volume of POSIX.1\(hy2008 ensures that +a fully-conforming application is portable across the full range of +implementations, while not forcing all implementations to add overhead +to check for numerous things that a correct program never does. When the +behavior is undefined, no error number is specified to be returned on +implementations that do detect the condition. This is because undefined +behavior means \fIanything\fR can happen, which includes returning +with any value (which might happen to be a valid, but different, error +number). However, since the error number might be useful to application +developers when diagnosing problems during application development, a +recommendation is made in rationale that implementors should return a +particular error number if their implementation does detect the condition. +.SS "Why No Limits are Defined" +.P +Defining symbols for the maximum number of mutexes and condition +variables was considered but rejected because the number of these +objects may change dynamically. Furthermore, many implementations +place these objects into application memory; thus, there is no explicit +maximum. +.SS "Static Initializers for Mutexes and Condition Variables" +.P +Providing for static initialization of statically allocated +synchronization objects allows modules with private static +synchronization variables to avoid runtime initialization tests and +overhead. Furthermore, it simplifies the coding of self-initializing +modules. Such modules are common in C libraries, where for various +reasons the design calls for self-initialization instead of requiring +an explicit module initialization function to be called. An example +use of static initialization follows. +.P +Without static initialization, a self-initializing routine +\fIfoo\fR() +might look as follows: +.sp +.RS 4 +.nf +\fB +static pthread_once_t foo_once = PTHREAD_ONCE_INIT; +static pthread_mutex_t foo_mutex; +.P +void foo_init() +{ + pthread_mutex_init(&foo_mutex, NULL); +} +.P +void foo() +{ + pthread_once(&foo_once, foo_init); + pthread_mutex_lock(&foo_mutex); + /* Do work. */ + pthread_mutex_unlock(&foo_mutex); +} +.fi \fR +.P +.RE +.P +With static initialization, the same routine could be coded as +follows: +.sp +.RS 4 +.nf +\fB +static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER; +.P +void foo() +{ + pthread_mutex_lock(&foo_mutex); + /* Do work. */ + pthread_mutex_unlock(&foo_mutex); +} +.fi \fR +.P +.RE +.P +Note that the static initialization both eliminates the need for the +initialization test inside +\fIpthread_once\fR() +and the fetch of &\fIfoo_mutex\fP to learn the address to be passed to +\fIpthread_mutex_lock\fR() +or +\fIpthread_mutex_unlock\fR(). +.P +Thus, the C code written to initialize static objects is simpler on all +systems and is also faster on a large class of systems; those where the +(entire) synchronization object can be stored in application memory. +.P +Yet the locking performance question is likely to be raised for +machines that require mutexes to be allocated out of special memory. +Such machines actually have to have mutexes and possibly condition +variables contain pointers to the actual hardware locks. For static +initialization to work on such machines, +\fIpthread_mutex_lock\fR() +also has to test whether or not the pointer to the actual lock has been +allocated. If it has not, +\fIpthread_mutex_lock\fR() +has to initialize it before use. The reservation of such resources can +be made when the program is loaded, and hence return codes have not +been added to mutex locking and condition variable waiting to indicate +failure to complete initialization. +.P +This runtime test in +\fIpthread_mutex_lock\fR() +would at first seem to be extra work; an extra test is required to see +whether the pointer has been initialized. On most machines this would +actually be implemented as a fetch of the pointer, testing the pointer +against zero, and then using the pointer if it has already been +initialized. While the test might seem to add extra work, the extra +effort of testing a register is usually negligible since no extra +memory references are actually done. As more and more machines provide +caches, the real expenses are memory references, not instructions +executed. +.P +Alternatively, depending on the machine architecture, there are often +ways to eliminate +.IR all +overhead in the most important case: on the lock operations that occur +.IR after +the lock has been initialized. This can be done by shifting more +overhead to the less frequent operation: initialization. Since +out-of-line mutex allocation also means that an address has to be +dereferenced to find the actual lock, one technique that is widely +applicable is to have static initialization store a bogus value for +that address; in particular, an address that causes a machine fault to +occur. When such a fault occurs upon the first attempt to lock such a +mutex, validity checks can be done, and then the correct address for +the actual lock can be filled in. Subsequent lock operations incur no +extra overhead since they do not ``fault''. This is merely one +technique that can be used to support static initialization, while not +adversely affecting the performance of lock acquisition. No doubt +there are other techniques that are highly machine-dependent. +.P +The locking overhead for machines doing out-of-line mutex allocation is +thus similar for modules being implicitly initialized, where it is +improved for those doing mutex allocation entirely inline. The inline +case is thus made much faster, and the out-of-line case is not +significantly worse. +.P +Besides the issue of locking performance for such machines, a concern +is raised that it is possible that threads would serialize contending +for initialization locks when attempting to finish initializing +statically allocated mutexes. (Such finishing would typically involve +taking an internal lock, allocating a structure, storing a pointer to +the structure in the mutex, and releasing the internal lock.) First, +many implementations would reduce such serialization by hashing on the +mutex address. Second, such serialization can only occur a bounded +number of times. In particular, it can happen at most as many times as +there are statically allocated synchronization objects. Dynamically +allocated objects would still be initialized via +\fIpthread_mutex_init\fR() +or +\fIpthread_cond_init\fR(). +.P +Finally, if none of the above optimization techniques for out-of-line +allocation yields sufficient performance for an application on some +implementation, the application can avoid static initialization +altogether by explicitly initializing all synchronization objects with +the corresponding +.IR pthread_*_init (\|) +functions, which are supported by all implementations. An +implementation can also document the tradeoffs and advise which +initialization technique is more efficient for that particular +implementation. +.SS "Destroying Mutexes" +.P +A mutex can be destroyed immediately after it is unlocked. For +example, consider the following code: +.sp +.RS 4 +.nf +\fB +struct obj { +pthread_mutex_t om; + int refcnt; + ... +}; +.P +obj_done(struct obj *op) +{ + pthread_mutex_lock(&op->om); + if (-\|-op->refcnt == 0) { + pthread_mutex_unlock(&op->om); +(A) pthread_mutex_destroy(&op->om); +(B) free(op); + } else +(C) pthread_mutex_unlock(&op->om); +} +.fi \fR +.P +.RE +.P +In this case +.IR obj +is reference counted and +\fIobj_done\fR() +is called whenever a reference to the object is dropped. +Implementations are required to allow an object to be destroyed and +freed and potentially unmapped (for example, lines A and B) immediately +after the object is unlocked (line C). +.SS "Robust Mutexes" +.P +Implementations are required to provide robust mutexes +for mutexes with the process-shared attribute set to +PTHREAD_PROCESS_SHARED. Implementations are allowed, but not required, +to provide robust mutexes when the process-shared attribute is set to +PTHREAD_PROCESS_PRIVATE. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_mutex_getprioceiling\fR\^(\|)", +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIpthread_mutexattr_getpshared\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutex_getprioceiling.3p b/man-pages-posix-2013-a/man3p/pthread_mutex_getprioceiling.3p new file mode 100644 index 0000000..03093eb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutex_getprioceiling.3p @@ -0,0 +1,151 @@ +'\" et +.TH PTHREAD_MUTEX_GETPRIOCEILING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutex_getprioceiling, +pthread_mutex_setprioceiling +\(em get and set the priority ceiling of a mutex +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict \fImutex\fP, + int *restrict \fIprioceiling\fP); +int pthread_mutex_setprioceiling(pthread_mutex_t *restrict \fImutex\fP, + int \fIprioceiling\fP, int *restrict \fIold_ceiling\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutex_getprioceiling\fR() +function shall return the current priority ceiling of the mutex. +.P +The +\fIpthread_mutex_setprioceiling\fR() +function shall attempt to lock the mutex as if by a call to +\fIpthread_mutex_lock\fR(), +except that the process of locking the mutex need not adhere to the +priority protect protocol. On acquiring the mutex it shall change the +mutex's priority ceiling and then release the mutex as if by a call to +\fIpthread_mutex_unlock\fR(). +When the change is successful, the previous value of the priority ceiling +shall be returned in +.IR old_ceiling . +.P +If the +\fIpthread_mutex_setprioceiling\fR() +function fails, the mutex priority ceiling shall not be changed. +.SH "RETURN VALUE" +If successful, the +\fIpthread_mutex_getprioceiling\fR() +and +\fIpthread_mutex_setprioceiling\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The protocol attribute of +.IR mutex +is PTHREAD_PRIO_NONE. +.TP +.BR EPERM +The implementation requires appropriate privileges to perform the +operation and the caller does not have appropriate privileges. +.P +The +\fIpthread_mutex_setprioceiling\fR() +function shall fail if: +.TP +.BR EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for +.IR mutex +has been exceeded. +.TP +.BR EDEADLK +The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current +thread already owns the mutex. +.TP +.BR EINVAL +The mutex was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than +the mutex's current priority ceiling, and the implementation adheres to +the priority protect protocol in the process of locking the mutex. +.TP +.BR ENOTRECOVERABLE +.br +The mutex is a robust mutex and the state protected by the mutex is +not recoverable. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the process containing the previous +owning thread terminated while holding the mutex lock. The mutex lock +shall be acquired by the calling thread and it is up to the new owner +to make the state consistent (see +.IR "\fIpthread_mutex_lock\fR\^(\|)"). +.P +The +\fIpthread_mutex_setprioceiling\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.TP +.BR EINVAL +The priority requested by +.IR prioceiling +is out of range. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the previous owning thread terminated +while holding the mutex lock. The mutex lock shall be acquired by the +calling thread and it is up to the new owner to make the state +consistent (see +.IR "\fIpthread_mutex_lock\fR\^(\|)"). +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutex_init.3p b/man-pages-posix-2013-a/man3p/pthread_mutex_init.3p new file mode 100644 index 0000000..d898454 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutex_init.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEX_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutex_init +\(em destroy and initialize a mutex +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_init(pthread_mutex_t *restrict \fImutex\fP, + const pthread_mutexattr_t *restrict \fIattr\fP); +pthread_mutex_t \fImutex\fP = PTHREAD_MUTEX_INITIALIZER; +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutex_destroy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutex_lock.3p b/man-pages-posix-2013-a/man3p/pthread_mutex_lock.3p new file mode 100644 index 0000000..a453a0b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutex_lock.3p @@ -0,0 +1,309 @@ +'\" et +.TH PTHREAD_MUTEX_LOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutex_lock, +pthread_mutex_trylock, +pthread_mutex_unlock +\(em lock and unlock a mutex +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_lock(pthread_mutex_t *\fImutex\fP); +int pthread_mutex_trylock(pthread_mutex_t *\fImutex\fP); +int pthread_mutex_unlock(pthread_mutex_t *\fImutex\fP); +.fi +.SH DESCRIPTION +The mutex object referenced by +.IR mutex +shall be locked by a call to +\fIpthread_mutex_lock\fR() +that returns zero or +.BR [EOWNERDEAD] . +If the mutex is already locked by another thread, the calling thread +shall block until the mutex becomes available. This operation shall +return with the mutex object referenced by +.IR mutex +in the locked state with the calling thread as its owner. If a thread +attempts to relock a mutex that it has already locked, +\fIpthread_mutex_lock\fR() +shall behave as described in the +.BR Relock +column of the following table. If a thread attempts to unlock a mutex +that it has not locked or a mutex which is unlocked, +\fIpthread_mutex_unlock\fR() +shall behave as described in the +.BR "Unlock When Not Owner" +column of the following table. +.TS +center box tab(!); +cB | cB | cB | cB +l | l | l | l. +Mutex Type!Robustness!Relock!Unlock When Not Owner +_ +NORMAL!non-robust!deadlock!undefined behavior +_ +NORMAL!robust!deadlock!error returned +_ +ERRORCHECK!either!error returned!error returned +_ +RECURSIVE!either!recursive!error returned +!!(see below) +_ +DEFAULT!non-robust!undefined!undefined behavior\s-2\(dg\s+2 +!!behavior\s-2\(dg\s+2 +_ +DEFAULT!robust!undefined!error returned +!!behavior\s-2\(dg\s+2 +.TE +.IP "\(dg" 6 +If the mutex type is PTHREAD_MUTEX_DEFAULT, the behavior of +\fIpthread_mutex_lock\fR() +may correspond to one of the three other standard mutex types as described +in the table above. If it does not correspond to one of those three, +the behavior is undefined for the cases marked \(dg. +.P +Where the table indicates recursive behavior, the mutex shall maintain +the concept of a lock count. When a thread successfully acquires a +mutex for the first time, the lock count shall be set to one. Every +time a thread relocks this mutex, the lock count shall be incremented +by one. Each time the thread unlocks the mutex, the lock count shall be +decremented by one. When the lock count reaches zero, the mutex shall +become available for other threads to acquire. +.P +The +\fIpthread_mutex_trylock\fR() +function shall be equivalent to +\fIpthread_mutex_lock\fR(), +except that if the mutex object referenced by +.IR mutex +is currently locked (by any thread, including the current thread), the +call shall return immediately. If the mutex type is +PTHREAD_MUTEX_RECURSIVE and the mutex is currently owned by the +calling thread, the mutex lock count shall be incremented by one and +the +\fIpthread_mutex_trylock\fR() +function shall immediately return success. +.P +The +\fIpthread_mutex_unlock\fR() +function shall release the mutex object referenced by +.IR mutex . +The manner in which a mutex is released is dependent upon the mutex's type +attribute. If there are threads blocked on the mutex object referenced by +.IR mutex +when +\fIpthread_mutex_unlock\fR() +is called, resulting in the mutex becoming available, the scheduling +policy shall determine which thread shall acquire the mutex. +.P +(In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become +available when the count reaches zero and the calling thread no longer +has any locks on this mutex.) +.P +If a signal is delivered to a thread waiting for a mutex, upon return +from the signal handler the thread shall resume waiting for the mutex +as if it was not interrupted. +.P +If +.IR mutex +is a robust mutex and the process containing the owning thread +terminated while holding the mutex lock, a call to +\fIpthread_mutex_lock\fR() +shall return the error value +.BR [EOWNERDEAD] . +If +.IR mutex +is a robust mutex and the owning thread terminated while holding the +mutex lock, a call to +\fIpthread_mutex_lock\fR() +may return the error value +.BR [EOWNERDEAD] +even if the process in which the owning thread resides has not +terminated. In these cases, the mutex is locked by the thread but the +state it protects is marked as inconsistent. The application should +ensure that the state is made consistent for reuse and when that is +complete call +\fIpthread_mutex_consistent\fR(). +If the application is unable to recover the state, it should unlock the +mutex without a prior call to +\fIpthread_mutex_consistent\fR(), +after which the mutex is marked permanently unusable. +.P +If +.IR mutex +does not refer to an initialized mutex object, the behavior of +\fIpthread_mutex_lock\fR(), +\fIpthread_mutex_trylock\fR(), +and +\fIpthread_mutex_unlock\fR() +is undefined. +.SH "RETURN VALUE" +If successful, the +\fIpthread_mutex_lock\fR(), +\fIpthread_mutex_trylock\fR(), +and +\fIpthread_mutex_unlock\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutex_lock\fR() +and +\fIpthread_mutex_trylock\fR() +functions shall fail if: +.TP +.BR EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for +.IR mutex +has been exceeded. +.TP +.BR EINVAL +The +.IR mutex +was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT +and the calling thread's priority is higher than the mutex's current +priority ceiling. +.TP +.BR ENOTRECOVERABLE +.br +The state protected by the mutex is not recoverable. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the process containing the previous +owning thread terminated while holding the mutex lock. The mutex lock +shall be acquired by the calling thread and it is up to the new owner +to make the state consistent. +.P +The +\fIpthread_mutex_lock\fR() +function shall fail if: +.TP +.BR EDEADLK +The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current +thread already owns the mutex. +.P +The +\fIpthread_mutex_trylock\fR() +function shall fail if: +.TP +.BR EBUSY +The +.IR mutex +could not be acquired because it was already locked. +.P +The +\fIpthread_mutex_unlock\fR() +function shall fail if: +.TP +.BR EPERM +The mutex type is PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE, +or the mutex is a robust mutex, and the current thread does not own +the mutex. +.P +The +\fIpthread_mutex_lock\fR() +and +\fIpthread_mutex_trylock\fR() +functions may fail if: +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the previous owning thread terminated +while holding the mutex lock. The mutex lock shall be acquired by the +calling thread and it is up to the new owner to make the state consistent. +.P +The +\fIpthread_mutex_lock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications that have assumed that non-zero return values are errors +will need updating for use with robust mutexes, since a valid return +for a thread acquiring a mutex which is protecting a currently +inconsistent state is +.BR [EOWNERDEAD] . +Applications that do not check the error returns, due to ruling out the +possibility of such errors arising, should not use robust mutexes. If +an application is supposed to work with normal and robust mutexes it +should check all return values for error conditions and if necessary +take appropriate action. +.SH RATIONALE +Mutex objects are intended to serve as a low-level primitive from which +other thread synchronization functions can be built. As such, the +implementation of mutexes should be as efficient as possible, and this +has ramifications on the features available at the interface. +.P +The mutex functions and the particular default settings of the mutex +attributes have been motivated by the desire to not preclude fast, +inlined implementations of mutex locking and unlocking. +.P +Since most attributes only need to be checked when a thread is going to +be blocked, the use of attributes does not slow the (common) +mutex-locking case. +.P +Likewise, while being able to extract the thread ID of the owner of a +mutex might be desirable, it would require storing the current thread +ID when each mutex is locked, and this could incur unacceptable levels +of overhead. Similar arguments apply to a +.IR mutex_tryunlock +operation. +.P +For further rationale on the extended mutex types, see the Rationale (Informative) volume of POSIX.1\(hy2008, +.IR "Threads Extensions". +.P +If an implementation detects that the value specified by the +.IR mutex +argument does not refer to an initialized mutex object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_mutex_consistent\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutex_setprioceiling.3p b/man-pages-posix-2013-a/man3p/pthread_mutex_setprioceiling.3p new file mode 100644 index 0000000..53ae3ef --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutex_setprioceiling.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEX_SETPRIOCEILING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutex_setprioceiling +\(em change the priority ceiling of a mutex +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_setprioceiling(pthread_mutex_t *restrict \fImutex\fP, + int \fIprioceiling\fP, int *restrict \fIold_ceiling\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutex_getprioceiling\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutex_timedlock.3p b/man-pages-posix-2013-a/man3p/pthread_mutex_timedlock.3p new file mode 100644 index 0000000..4c1b9cf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutex_timedlock.3p @@ -0,0 +1,195 @@ +'\" et +.TH PTHREAD_MUTEX_TIMEDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutex_timedlock +\(em lock a mutex +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int pthread_mutex_timedlock(pthread_mutex_t *restrict \fImutex\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutex_timedlock\fR() +function shall lock the mutex object referenced by +.IR mutex . +If the mutex is already locked, the calling thread shall block +until the mutex becomes available as in the +\fIpthread_mutex_lock\fR() +function. If the mutex cannot be locked without waiting for another +thread to unlock the mutex, this wait shall be terminated when the +specified timeout expires. +.P +The timeout shall expire when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock on +which it is based. The +.BR timespec +data type is defined in the +.IR +header. +.P +Under no circumstance shall the function fail with a timeout if the +mutex can be locked immediately. The validity of the +.IR abstime +parameter need not be checked if the mutex can be locked immediately. +.P +As a consequence of the priority inheritance rules (for mutexes +initialized with the PRIO_INHERIT protocol), if a timed mutex wait is +terminated +because its timeout expires, the priority of the owner of the mutex +shall be adjusted as necessary to reflect the fact that this thread is +no longer among the threads waiting for the mutex. +.P +If +.IR mutex +is a robust mutex and the process containing the owning thread +terminated while holding the mutex lock, a call to +\fIpthread_mutex_timedlock\fR() +shall return the error value +.BR [EOWNERDEAD] . +If +.IR mutex +is a robust mutex and the owning thread terminated while holding the +mutex lock, a call to +\fIpthread_mutex_timedlock\fR() +may return the error value +.BR [EOWNERDEAD] +even if the process in which the owning thread resides has not +terminated. In these cases, the mutex is locked by the thread but the +state it protects is marked as inconsistent. The application should +ensure that the state is made consistent for reuse and when that is +complete call +\fIpthread_mutex_consistent\fR(). +If the application is unable to recover the state, it should unlock the +mutex without a prior call to +\fIpthread_mutex_consistent\fR(), +after which the mutex is marked permanently unusable. +.P +If +.IR mutex +does not refer to an initialized mutex object, the behavior is undefined. +.SH "RETURN VALUE" +If successful, the +\fIpthread_mutex_timedlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutex_timedlock\fR() +function shall fail if: +.TP +.BR EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for +.IR mutex +has been exceeded. +.TP +.BR EDEADLK +The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current +thread already owns the mutex. +.TP +.BR EINVAL +The mutex was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than +the mutex' current priority ceiling. +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR ENOTRECOVERABLE +.br +The state protected by the mutex is not recoverable. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the process containing the previous +owning thread terminated while holding the mutex lock. The mutex lock +shall be acquired by the calling thread and it is up to the new owner +to make the state consistent. +.TP +.BR ETIMEDOUT +The mutex could not be locked before the specified timeout expired. +.P +The +\fIpthread_mutex_timedlock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the previous owning thread terminated +while holding the mutex lock. The mutex lock shall be acquired by the +calling thread and it is up to the new owner to make the state consistent. +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications that have assumed that non-zero return values are errors +will need updating for use with robust mutexes, since a valid return +for a thread acquiring a mutex which is protecting a currently +inconsistent state is +.BR [EOWNERDEAD] . +Applications that do not check the error returns, due to ruling out the +possibility of such errors arising, should not use robust mutexes. If +an application is supposed to work with normal and robust mutexes, it +should check all return values for error conditions and if necessary +take appropriate action. +.SH RATIONALE +Refer to +.IR "\fIpthread_mutex_lock\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutex_trylock.3p b/man-pages-posix-2013-a/man3p/pthread_mutex_trylock.3p new file mode 100644 index 0000000..fcdf1c9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutex_trylock.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEX_TRYLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutex_trylock, +pthread_mutex_unlock +\(em lock and unlock a mutex +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_trylock(pthread_mutex_t *\fImutex\fP); +int pthread_mutex_unlock(pthread_mutex_t *\fImutex\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutex_lock\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_destroy.3p new file mode 100644 index 0000000..1c6bdc9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_destroy.3p @@ -0,0 +1,364 @@ +'\" et +.TH PTHREAD_MUTEXATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_destroy, +pthread_mutexattr_init +\(em destroy and initialize the mutex attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_destroy(pthread_mutexattr_t *\fIattr\fP); +int pthread_mutexattr_init(pthread_mutexattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_destroy\fR() +function shall destroy a mutex attributes object; the object becomes, +in effect, uninitialized. An implementation may cause +\fIpthread_mutexattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_mutexattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIpthread_mutexattr_init\fR() +function shall initialize a mutex attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +Results are undefined if +\fIpthread_mutexattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +After a mutex attributes object has been used to initialize one or more +mutexes, any function affecting the attributes object (including +destruction) shall not affect any previously initialized mutexes. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_destroy\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_mutexattr_destroy\fR() +and +\fIpthread_mutexattr_init\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the mutex attributes object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_destroy\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +See +.IR "\fIpthread_attr_destroy\fR\^(\|)" +for a general explanation of attributes. Attributes objects allow +implementations to experiment with useful extensions and permit +extension of this volume of POSIX.1\(hy2008 without changing the existing functions. Thus, they +provide for future extensibility of this volume of POSIX.1\(hy2008 and reduce the temptation to +standardize prematurely on semantics that are not yet widely +implemented or understood. +.P +Examples of possible additional mutex attributes that have been +discussed are +.IR spin_only , +.IR limited_spin , +.IR no_spin , +.IR recursive , +and +.IR metered . +(To explain what the latter attributes might mean: recursive mutexes +would allow for multiple re-locking by the current owner; metered +mutexes would transparently keep records of queue length, wait time, +and so on.) Since there is not yet wide agreement on the usefulness of +these resulting from shared implementation and usage experience, they +are not yet specified in this volume of POSIX.1\(hy2008. Mutex attributes objects, +however, make it possible to test out these concepts for possible +standardization at a later time. +.SS "Mutex Attributes and Performance" +.P +Care has been taken to ensure that the default values of the mutex +attributes have been defined such that mutexes initialized with the +defaults have simple enough semantics so that the locking and unlocking +can be done with the equivalent of a test-and-set instruction (plus +possibly a few other basic instructions). +.P +There is at least one implementation method that can be used to reduce +the cost of testing at lock-time if a mutex has non-default +attributes. One such method that an implementation can employ (and +this can be made fully transparent to fully conforming POSIX +applications) is to secretly pre-lock any mutexes that are initialized +to non-default attributes. Any later attempt to lock such a mutex +causes the implementation to branch to the ``slow path'' as if the +mutex were unavailable; then, on the slow path, the implementation can +do the ``real work'' to lock a non-default mutex. The underlying +unlock operation is more complicated since the implementation never +really wants to release the pre-lock on this kind of mutex. This +illustrates that, depending on the hardware, there may be certain +optimizations that can be used so that whatever mutex attributes are +considered ``most frequently used'' can be processed most efficiently. +.SS "Process Shared Memory and Synchronization" +.P +The existence of memory mapping functions in this volume of POSIX.1\(hy2008 leads to the +possibility that an application may allocate the synchronization +objects from this section in memory that is accessed by multiple +processes (and therefore, by threads of multiple processes). +.P +In order to permit such usage, while at the same time keeping the usual +case (that is, usage within a single process) efficient, a +.IR process-shared +option has been defined. +.P +If an implementation supports the _POSIX_THREAD_PROCESS_SHARED +option, then the +.IR process-shared +attribute can be used to indicate that mutexes or condition variables +may be accessed by threads of multiple processes. +.P +The default setting of PTHREAD_PROCESS_PRIVATE +has been chosen for the +.IR process-shared +attribute so that the most efficient forms of these synchronization +objects are created by default. +.P +Synchronization variables that are initialized with the +PTHREAD_PROCESS_PRIVATE +.IR process-shared +attribute may only be operated on by threads in the process that +initialized them. Synchronization variables that are initialized with +the PTHREAD_PROCESS_SHARED +.IR process-shared +attribute may be operated on by any thread in any process that has +access to it. In particular, these processes may exist beyond the +lifetime of the initializing process. For example, the following code +implements a simple counting semaphore in a mapped file that may be +used by many processes. +.sp +.RS 4 +.nf +\fB +/* sem.h */ +struct semaphore { + pthread_mutex_t lock; + pthread_cond_t nonzero; + unsigned count; +}; +typedef struct semaphore semaphore_t; +.P +semaphore_t *semaphore_create(char *semaphore_name); +semaphore_t *semaphore_open(char *semaphore_name); +void semaphore_post(semaphore_t *semap); +void semaphore_wait(semaphore_t *semap); +void semaphore_close(semaphore_t *semap); +.P +/* sem.c */ +#include +#include +#include +#include +#include +#include "sem.h" +.P +semaphore_t * +semaphore_create(char *semaphore_name) +{ +int fd; + semaphore_t *semap; + pthread_mutexattr_t psharedm; + pthread_condattr_t psharedc; +.P + fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666); + if (fd < 0) + return (NULL); + (void) ftruncate(fd, sizeof(semaphore_t)); + (void) pthread_mutexattr_init(&psharedm); + (void) pthread_mutexattr_setpshared(&psharedm, + PTHREAD_PROCESS_SHARED); + (void) pthread_condattr_init(&psharedc); + (void) pthread_condattr_setpshared(&psharedc, + PTHREAD_PROCESS_SHARED); + semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, 0); + close (fd); + (void) pthread_mutex_init(&semap->lock, &psharedm); + (void) pthread_cond_init(&semap->nonzero, &psharedc); + semap->count = 0; + return (semap); +} +.P +semaphore_t * +semaphore_open(char *semaphore_name) +{ + int fd; + semaphore_t *semap; +.P + fd = open(semaphore_name, O_RDWR, 0666); + if (fd < 0) + return (NULL); + semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, 0); + close (fd); + return (semap); +} +.P +void +semaphore_post(semaphore_t *semap) +{ + pthread_mutex_lock(&semap->lock); + if (semap->count == 0) + pthread_cond_signal(&semapx->nonzero); + semap->count++; + pthread_mutex_unlock(&semap->lock); +} +.P +void +semaphore_wait(semaphore_t *semap) +{ + pthread_mutex_lock(&semap->lock); + while (semap->count == 0) + pthread_cond_wait(&semap->nonzero, &semap->lock); + semap->count-\|-; + pthread_mutex_unlock(&semap->lock); +} +.P +void +semaphore_close(semaphore_t *semap) +{ + munmap((void *) semap, sizeof(semaphore_t)); +} +.fi \fR +.P +.RE +.P +The following code is for three separate processes that create, post, +and wait on a semaphore in the file +.BR /tmp/semaphore . +Once the file is created, the post and wait programs increment and +decrement the counting semaphore (waiting and waking as required) even +though they did not initialize the semaphore. +.sp +.RS 4 +.nf +\fB +/* create.c */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_create("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_close(semap); + return (0); +} +.P +/* post */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_open("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_post(semap); + semaphore_close(semap); + return (0); +} +.P +/* wait */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_open("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_wait(semap); + semaphore_close(semap); + return (0); +} +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_getprioceiling.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_getprioceiling.3p new file mode 100644 index 0000000..12b41f4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_getprioceiling.3p @@ -0,0 +1,123 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPRIOCEILING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_getprioceiling, +pthread_mutexattr_setprioceiling +\(em get and set the prioceiling attribute of the mutex attributes object +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t + *restrict \fIattr\fP, int *restrict \fIprioceiling\fP); +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *\fIattr\fP, + int \fIprioceiling\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_getprioceiling\fR() +and +\fIpthread_mutexattr_setprioceiling\fR() +functions, respectively, shall get and set the priority ceiling +attribute of a mutex attributes object pointed to by +.IR attr +which was previously created by the function +\fIpthread_mutexattr_init\fR(). +.P +The +.IR prioceiling +attribute contains the priority ceiling of initialized mutexes. The +values of +.IR prioceiling +are within the maximum range of priorities defined by SCHED_FIFO. +.P +The +.IR prioceiling +attribute defines the priority ceiling of initialized mutexes, which is +the minimum priority level at which the critical section guarded by the +mutex is executed. In order to avoid priority inversion, the priority +ceiling of the mutex shall be set to a priority higher than or equal to +the highest priority of all the threads that may lock that mutex. The +values of +.IR prioceiling +are within the maximum range of priorities defined under the SCHED_FIFO +scheduling policy. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getprioceiling\fR() +or +\fIpthread_mutexattr_setprioceiling\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutexattr_getprioceiling\fR() +and +\fIpthread_mutexattr_setprioceiling\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR prioceiling +is invalid. +.TP +.BR EPERM +The caller does not have the privilege to perform the operation. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getprioceiling\fR() +or +\fIpthread_mutexattr_setprioceiling\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_getprotocol.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_getprotocol.3p new file mode 100644 index 0000000..d3ab83c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_getprotocol.3p @@ -0,0 +1,197 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPROTOCOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_getprotocol, +pthread_mutexattr_setprotocol +\(em get and set the protocol attribute of the mutex attributes object +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_getprotocol(const pthread_mutexattr_t + *restrict \fIattr\fP, int *restrict \fIprotocol\fP); +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *\fIattr\fP, + int \fIprotocol\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_getprotocol\fR() +and +\fIpthread_mutexattr_setprotocol\fR() +functions, respectively, shall get and set the protocol attribute of +a mutex attributes object pointed to by +.IR attr +which was previously created by the function +\fIpthread_mutexattr_init\fR(). +.P +The +.IR protocol +attribute defines the protocol to be followed in utilizing mutexes. +The value of +.IR protocol +may be one of: +.P +.nf +PTHREAD_PRIO_INHERIT +PTHREAD_PRIO_NONE +PTHREAD_PRIO_PROTECT +.fi +.P +which are defined in the +.IR +header. The default value of the attribute shall be PTHREAD_PRIO_NONE. +.P +When a thread owns a mutex with the PTHREAD_PRIO_NONE +.IR protocol +attribute, its priority and scheduling shall not be affected by +its mutex ownership. +.P +When a thread is blocking higher priority threads because of owning one +or more robust mutexes with the PTHREAD_PRIO_INHERIT +.IR protocol +attribute, it shall execute at the higher of its priority or the priority +of the highest priority thread waiting on any of the robust mutexes +owned by this thread and initialized with this protocol. +.P +When a thread is blocking higher priority threads because of owning one +or more non-robust mutexes with the PTHREAD_PRIO_INHERIT +.IR protocol +attribute, it shall execute at the higher of its priority or the priority +of the highest priority thread waiting on any of the non-robust mutexes +owned by this thread and initialized with this protocol. +.P +When a thread owns one or more robust mutexes initialized with the +PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of its +priority or the highest of the priority ceilings of all the robust mutexes +owned by this thread and initialized with this attribute, regardless of +whether other threads are blocked on any of these robust mutexes or not. +.P +When a thread owns one or more non-robust mutexes initialized with the +PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of its +priority or the highest of the priority ceilings of all the non-robust +mutexes owned by this thread and initialized with this attribute, +regardless of whether other threads are blocked on any of these non-robust +mutexes or not. +.P +While a thread is holding a mutex which has been initialized with the +PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it +shall not be subject to being moved to the tail of the scheduling queue +at its priority in the event that its original priority is changed, +such as by a call to +\fIsched_setparam\fR(). +Likewise, when a thread unlocks a mutex that has been initialized with +the PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, +it shall not be subject to being moved to the tail of the scheduling +queue at its priority in the event that its original priority is +changed. +.P +If a thread simultaneously owns several mutexes initialized with +different protocols, it shall execute at the highest of the priorities +that it would have obtained by each of these protocols. +.P +When a thread makes a call to +\fIpthread_mutex_lock\fR(), +the mutex was initialized with the protocol attribute having the value +PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the +mutex is owned by another thread, that owner thread shall inherit the +priority level of the calling thread as long as it continues to own the +mutex. The implementation shall update its execution priority to the +maximum of its assigned priority and all its inherited priorities. +Furthermore, if this owner thread itself becomes blocked on another +mutex with the +.IR protocol +attribute having the value PTHREAD_PRIO_INHERIT, the same priority +inheritance effect shall be propagated to this other owner thread, +in a recursive manner. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getprotocol\fR() +or +\fIpthread_mutexattr_setprotocol\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutexattr_getprotocol\fR() +and +\fIpthread_mutexattr_setprotocol\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_setprotocol\fR() +function shall fail if: +.TP +.BR ENOTSUP +The value specified by +.IR protocol +is an unsupported value. +.P +The +\fIpthread_mutexattr_getprotocol\fR() +and +\fIpthread_mutexattr_setprotocol\fR() +functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR protocol +is invalid. +.TP +.BR EPERM +The caller does not have the privilege to perform the operation. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getprotocol\fR() +or +\fIpthread_mutexattr_setprotocol\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_getpshared.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_getpshared.3p new file mode 100644 index 0000000..1c2d107 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_getpshared.3p @@ -0,0 +1,130 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_getpshared, +pthread_mutexattr_setpshared +\(em get and set the process-shared attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_getpshared(const pthread_mutexattr_t + *restrict \fIattr\fP, int *restrict \fIpshared\fP); +int pthread_mutexattr_setpshared(pthread_mutexattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_getpshared\fR() +function shall obtain the value of the +.IR process-shared +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIpthread_mutexattr_setpshared\fR() +function shall set the +.IR process-shared +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR process-shared +attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex +to be operated upon by any thread that has access to the memory where +the mutex is allocated, even if the mutex is allocated in memory that +is shared by multiple processes. If the +.IR process-shared +attribute is PTHREAD_PROCESS_PRIVATE, the mutex shall only be operated +upon by threads created within the same process as the thread that +initialized the mutex; if threads of differing processes attempt to +operate on such a mutex, the behavior is undefined. The default value +of the attribute shall be PTHREAD_PROCESS_PRIVATE. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getpshared\fR() +or +\fIpthread_mutexattr_setpshared\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_mutexattr_setpshared\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.P +Upon successful completion, +\fIpthread_mutexattr_getpshared\fR() +shall return zero and store the value of the +.IR process-shared +attribute of +.IR attr +into the object referenced by the +.IR pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +The +\fIpthread_mutexattr_setpshared\fR() +function may fail if: +.TP +.BR EINVAL +The new value specified for the attribute is outside the range of legal +values for that attribute. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getpshared\fR() +or +\fIpthread_mutexattr_setpshared\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutexattr_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_getrobust.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_getrobust.3p new file mode 100644 index 0000000..5196d9c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_getrobust.3p @@ -0,0 +1,160 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETROBUST "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_getrobust, +pthread_mutexattr_setrobust +\(em get and set the mutex robust attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_getrobust(const pthread_mutexattr_t *restrict + \fIattr\fP, int *restrict \fIrobust\fP); +int pthread_mutexattr_setrobust(pthread_mutexattr_t *\fIattr\fP, + int \fIrobust\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_getrobust\fR() +and +\fIpthread_mutexattr_setrobust\fR() +functions, respectively, shall get and set the mutex +.IR robust +attribute. This attribute is set in the +.IR robust +parameter. Valid values for +.IR robust +include: +.IP PTHREAD_MUTEX_STALLED 6 +.br +No special actions are taken if the owner of the mutex is terminated +while holding the mutex lock. This can lead to deadlocks if no other +thread can unlock the mutex. +.br +This is the default value. +.IP PTHREAD_MUTEX_ROBUST 6 +.br +If the process containing the owning thread of a robust mutex +terminates while holding the mutex lock, the next thread that acquires +the mutex shall be notified about the termination by the return value +.BR [EOWNERDEAD] +from the locking function. If the owning thread of a robust mutex +terminates while holding the mutex lock, the next thread that acquires +the mutex may be notified about the termination by the return value +.BR [EOWNERDEAD] . +The notified thread can then attempt to mark the state protected by the +mutex as consistent again by a call to +\fIpthread_mutex_consistent\fR(). +After a subsequent successful call to +\fIpthread_mutex_unlock\fR(), +the mutex lock shall be released and can be used normally by other +threads. If the mutex is unlocked without a call to +\fIpthread_mutex_consistent\fR(), +it shall be in a permanently unusable state and all attempts to lock +the mutex shall fail with the error +.BR [ENOTRECOVERABLE] . +The only permissible operation on such a mutex is +\fIpthread_mutex_destroy\fR(). +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getrobust\fR() +or +\fIpthread_mutexattr_setrobust\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutexattr_getrobust\fR() +function shall return zero and store the value of the +.IR robust +attribute of +.IR attr +into the object referenced by the +.IR robust +parameter. Otherwise, an error value shall be returned to indicate the +error. If successful, the +\fIpthread_mutexattr_setrobust\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_setrobust\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR robust +is invalid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The actions required to make the state protected by the mutex +consistent again are solely dependent on the application. If it is not +possible to make the state of a mutex consistent, robust mutexes can be +used to notify this situation by calling +\fIpthread_mutex_unlock\fR() +without a prior call to +\fIpthread_mutex_consistent\fR(). +.P +If the state is declared inconsistent by calling +\fIpthread_mutex_unlock\fR() +without a prior call to +\fIpthread_mutex_consistent\fR(), +a possible approach could be to destroy the mutex and then reinitialize +it. However, it should be noted that this is possible only in certain +situations where the state protected by the mutex has to be +reinitialized and coordination achieved with other threads blocked on +the mutex, because otherwise a call to a locking function with a +reference to a mutex object invalidated by a call to +\fIpthread_mutex_destroy\fR() +results in undefined behavior. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getrobust\fR() +or +\fIpthread_mutexattr_setrobust\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_mutex_consistent\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_gettype.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_gettype.3p new file mode 100644 index 0000000..778792d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_gettype.3p @@ -0,0 +1,135 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETTYPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_gettype, +pthread_mutexattr_settype +\(em get and set the mutex type attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict \fIattr\fP, + int *restrict \fItype\fP); +int pthread_mutexattr_settype(pthread_mutexattr_t *\fIattr\fP, int \fItype\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_gettype\fR() +and +\fIpthread_mutexattr_settype\fR() +functions, respectively, shall get and set the mutex +.IR type +attribute. This attribute is set in the +.IR type +parameter to these functions. The default value of the +.IR type +attribute is PTHREAD_MUTEX_DEFAULT. +.P +The type of mutex is contained in the +.IR type +attribute of the mutex attributes. Valid mutex types include: +.sp +.RS +PTHREAD_MUTEX_NORMAL +PTHREAD_MUTEX_ERRORCHECK +PTHREAD_MUTEX_RECURSIVE +PTHREAD_MUTEX_DEFAULT +.RE +.P +The mutex type affects the behavior of calls which lock and unlock the +mutex. See +.IR "\fIpthread_mutex_lock\fR\^(\|)" +for details. An implementation may map PTHREAD_MUTEX_DEFAULT to one of +the other mutex types. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_gettype\fR() +or +\fIpthread_mutexattr_settype\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutexattr_gettype\fR() +function shall return zero and store the value of the +.IR type +attribute of +.IR attr +into the object referenced by the +.IR type +parameter. Otherwise, an error shall be returned to indicate the error. +.P +If successful, the +\fIpthread_mutexattr_settype\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_settype\fR() +function shall fail if: +.TP +.BR EINVAL +The value +.IR type +is invalid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +It is advised that an application should not use a +PTHREAD_MUTEX_RECURSIVE mutex with condition variables +because the implicit unlock performed for a +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +may not actually release the mutex (if it had been locked multiple +times). If this happens, no other thread can satisfy the condition of +the predicate. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_gettype\fR() +or +\fIpthread_mutexattr_settype\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_init.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_init.3p new file mode 100644 index 0000000..8af996b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_MUTEXATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_init +\(em initialize the mutex attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_init(pthread_mutexattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_destroy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_setprioceiling.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_setprioceiling.3p new file mode 100644 index 0000000..e70d436 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_setprioceiling.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPRIOCEILING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_setprioceiling +\(em set the prioceiling attribute of the mutex attributes object +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *\fIattr\fP, + int \fIprioceiling\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_getprioceiling\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_setprotocol.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_setprotocol.3p new file mode 100644 index 0000000..dccf9a3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_setprotocol.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPROTOCOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_setprotocol +\(em set the protocol attribute of the mutex attributes object +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *\fIattr\fP, + int \fIprotocol\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_getprotocol\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_setpshared.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_setpshared.3p new file mode 100644 index 0000000..d89560e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_setpshared.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_setpshared +\(em set the process-shared attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_setpshared(pthread_mutexattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_getpshared\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_setrobust.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_setrobust.3p new file mode 100644 index 0000000..f889f91 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_setrobust.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETROBUST "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_setrobust +\(em get and set the mutex robust attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_setrobust(pthread_mutexattr_t *\fIattr\fP, + int \fIrobust\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_mutexattr_settype.3p b/man-pages-posix-2013-a/man3p/pthread_mutexattr_settype.3p new file mode 100644 index 0000000..332df5c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_mutexattr_settype.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETTYPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_mutexattr_settype +\(em set the mutex type attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_settype(pthread_mutexattr_t *\fIattr\fP, int \fItype\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_gettype\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_once.3p b/man-pages-posix-2013-a/man3p/pthread_once.3p new file mode 100644 index 0000000..316b1e9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_once.3p @@ -0,0 +1,175 @@ +'\" et +.TH PTHREAD_ONCE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_once +\(em dynamic package initialization +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_once(pthread_once_t *\fIonce_control\fP, + void (*\fIinit_routine\fP)(void)); +pthread_once_t \fIonce_control\fP = PTHREAD_ONCE_INIT; +.fi +.SH DESCRIPTION +The first call to +\fIpthread_once\fR() +by any thread in a process, with a given +.IR once_control , +shall call the +.IR init_routine +with no arguments. Subsequent calls of +\fIpthread_once\fR() +with the same +.IR once_control +shall not call the +.IR init_routine . +On return from +\fIpthread_once\fR(), +.IR init_routine +shall have completed. The +.IR once_control +parameter shall determine whether the associated initialization +routine has been called. +.P +The +\fIpthread_once\fR() +function is not a cancellation point. However, if +.IR init_routine +is a cancellation point and is canceled, the effect on +.IR once_control +shall be as if +\fIpthread_once\fR() +was never called. +.P +The constant PTHREAD_ONCE_INIT is defined in the +.IR +header. +.P +The behavior of +\fIpthread_once\fR() +is undefined if +.IR once_control +has automatic storage duration or is not initialized by +PTHREAD_ONCE_INIT. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_once\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_once\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Some C libraries are designed for dynamic initialization. That is, the +global initialization for the library is performed when the first +procedure in the library is called. In a single-threaded program, this +is normally implemented using a static variable whose value is checked +on entry to a routine, as follows: +.sp +.RS 4 +.nf +\fB +static int random_is_initialized = 0; +extern int initialize_random(); +.P +int random_function() +{ + if (random_is_initialized == 0) { + initialize_random(); + random_is_initialized = 1; + } + ... /* Operations performed after initialization. */ +} +.fi \fR +.P +.RE +.P +To keep the same structure in a multi-threaded program, a new primitive +is needed. Otherwise, library initialization has to be accomplished by +an explicit call to a library-exported initialization function prior to +any use of the library. +.P +For dynamic library initialization in a multi-threaded process, a +simple initialization flag is not sufficient; the flag needs to be +protected against modification by multiple threads simultaneously +calling into the library. Protecting the flag requires the use of a +mutex; however, mutexes have to be initialized before they are used. +Ensuring that the mutex is only initialized once requires a recursive +solution to this problem. +.P +The use of +\fIpthread_once\fR() +not only supplies an implementation-guaranteed means of dynamic +initialization, it provides an aid to the reliable construction of +multi-threaded and realtime systems. The preceding example then +becomes: +.sp +.RS 4 +.nf +\fB +#include +static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT; +extern int initialize_random(); +.P +int random_function() +{ + (void) pthread_once(&random_is_initialized, initialize_random); + ... /* Operations performed after initialization. */ +} +.fi \fR +.P +.RE +.P +Note that a +.BR pthread_once_t +cannot be an array because some compilers do not accept the construct +\fB&\fP. +.P +If an implementation detects that the value specified by the +.IR once_control +argument to +\fIpthread_once\fR() +does not refer to a +.BR pthread_once_t +object initialized by PTHREAD_ONCE_INIT, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlock_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_rwlock_destroy.3p new file mode 100644 index 0000000..acc1dd4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlock_destroy.3p @@ -0,0 +1,195 @@ +'\" et +.TH PTHREAD_RWLOCK_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlock_destroy, +pthread_rwlock_init +\(em destroy and initialize a read-write lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_destroy(pthread_rwlock_t *\fIrwlock\fP); +int pthread_rwlock_init(pthread_rwlock_t *restrict \fIrwlock\fP, + const pthread_rwlockattr_t *restrict \fIattr\fP); +pthread_rwlock_t \fIrwlock\fR = PTHREAD_RWLOCK_INITIALIZER; +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_destroy\fR() +function shall destroy the read-write lock object referenced by +.IR rwlock +and release any resources used by the lock. The effect of subsequent +use of the lock is undefined until the lock is reinitialized by +another call to +\fIpthread_rwlock_init\fR(). +An implementation may cause +\fIpthread_rwlock_destroy\fR() +to set the object referenced by +.IR rwlock +to an invalid value. Results are undefined if +\fIpthread_rwlock_destroy\fR() +is called when any thread holds +.IR rwlock . +Attempting to destroy an uninitialized read-write lock results in +undefined behavior. +.P +The +\fIpthread_rwlock_init\fR() +function shall allocate any resources required to use the read-write +lock referenced by +.IR rwlock +and initializes the lock to an unlocked state with attributes +referenced by +.IR attr . +If +.IR attr +is NULL, the default read-write lock attributes shall be used; the +effect is the same as passing the address of a default read-write lock +attributes object. Once initialized, the lock can be used any number of +times without being reinitialized. Results are undefined if +\fIpthread_rwlock_init\fR() +is called specifying an already initialized read-write lock. Results +are undefined if a read-write lock is used without first being +initialized. +.P +If the +\fIpthread_rwlock_init\fR() +function fails, +.IR rwlock +shall not be initialized and the contents of +.IR rwlock +are undefined. +.P +Only the object referenced by +.IR rwlock +may be used for performing synchronization. The result of referring to +copies of that object in calls to +\fIpthread_rwlock_destroy\fR(), +\fIpthread_rwlock_rdlock\fR(), +\fIpthread_rwlock_timedrdlock\fR(), +\fIpthread_rwlock_timedwrlock\fR(), +\fIpthread_rwlock_tryrdlock\fR(), +\fIpthread_rwlock_trywrlock\fR(), +\fIpthread_rwlock_unlock\fR(), +or +\fIpthread_rwlock_wrlock\fR() +is undefined. +.P +In cases where default read-write lock attributes are appropriate, the +macro PTHREAD_RWLOCK_INITIALIZER can be used to initialize read-write +locks. The effect shall be equivalent to dynamic initialization by a +call to +\fIpthread_rwlock_init\fR() +with the +.IR attr +parameter specified as NULL, except that no error checks are performed. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_rwlock_init\fR() +does not refer to an initialized read-write lock attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_rwlock_destroy\fR() +and +\fIpthread_rwlock_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlock_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources (other than memory) to +initialize another read-write lock. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the read-write lock. +.TP +.BR EPERM +The caller does not have the privilege to perform the operation. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these and related read-write lock functions may be +subject to priority inversion, as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_destroy\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_rwlockr_init\fR() +does not refer to an initialized read-write lock attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_destroy\fR() +or +\fIpthread_rwlock_init\fR() +refers to a locked read-write lock object, or detects that the value +specified by the +.IR rwlock +argument to +\fIpthread_rwlock_init\fR() +refers to an already initialized read-write lock object, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlock_rdlock.3p b/man-pages-posix-2013-a/man3p/pthread_rwlock_rdlock.3p new file mode 100644 index 0000000..6aa04e7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlock_rdlock.3p @@ -0,0 +1,182 @@ +'\" et +.TH PTHREAD_RWLOCK_RDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlock_rdlock, +pthread_rwlock_tryrdlock +\(em lock a read-write lock object for reading +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_rdlock(pthread_rwlock_t *\fIrwlock\fP); +int pthread_rwlock_tryrdlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_rdlock\fR() +function shall apply a read lock to the read-write lock referenced by +.IR rwlock . +The calling thread acquires the read lock if a writer does not hold the +lock and there are no writers blocked on the lock. +.P +If the Thread Execution Scheduling option is supported, and the threads +involved in the lock are executing with the scheduling policies +SCHED_FIFO or SCHED_RR, the calling thread shall +not acquire the lock if a writer holds the lock or if writers of higher +or equal priority are blocked on the lock; otherwise, the calling +thread shall acquire the lock. +.P +If the Thread Execution Scheduling option is supported, and the +threads involved in the lock are executing with the SCHED_SPORADIC +scheduling policy, the calling thread shall not acquire the lock if a +writer holds the lock or if writers of higher or equal priority are +blocked on the lock; otherwise, the calling thread shall acquire the +lock. +.P +If the Thread Execution Scheduling option is not supported, it is +implementation-defined whether the calling thread acquires the lock +when a writer does not hold the lock and there are writers blocked on +the lock. If a writer holds the lock, the calling thread shall not +acquire the read lock. If the read lock is not acquired, the calling +thread shall block until it can acquire the lock. The calling thread +may deadlock if at the time the call is made it holds a write lock. +.P +A thread may hold multiple concurrent read locks on +.IR rwlock +(that is, successfully call the +\fIpthread_rwlock_rdlock\fR() +function +.IR n +times). If so, the application shall ensure that the thread performs +matching unlocks (that is, it calls the +\fIpthread_rwlock_unlock\fR() +function +.IR n +times). +.P +The maximum number of simultaneous read locks that an implementation +guarantees can be applied to a read-write lock shall be +implementation-defined. The +\fIpthread_rwlock_rdlock\fR() +function may fail if this maximum would be exceeded. +.P +The +\fIpthread_rwlock_tryrdlock\fR() +function shall apply a read lock as in the +\fIpthread_rwlock_rdlock\fR() +function, with the exception that the function shall fail if the +equivalent +\fIpthread_rwlock_rdlock\fR() +call would have blocked the calling thread. In no case shall the +\fIpthread_rwlock_tryrdlock\fR() +function ever block; it always either acquires the lock or fails and +returns immediately. +.P +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.P +If a signal is delivered to a thread waiting for a read-write lock for +reading, upon return from the signal handler the thread resumes waiting +for the read-write lock for reading as if it was not interrupted. +.SH "RETURN VALUE" +If successful, the +\fIpthread_rwlock_rdlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.P +The +\fIpthread_rwlock_tryrdlock\fR() +function shall return zero if the lock for reading on the read-write +lock object referenced by +.IR rwlock +is acquired. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +The +\fIpthread_rwlock_tryrdlock\fR() +function shall fail if: +.TP +.BR EBUSY +The read-write lock could not be acquired for reading because a writer +holds the lock or a writer with the appropriate priority was blocked on it. +.P +The +\fIpthread_rwlock_rdlock\fR() +and +\fIpthread_rwlock_tryrdlock\fR() +functions may fail if: +.TP +.BR EAGAIN +The read lock could not be acquired because the maximum number of read +locks for +.IR rwlock +has been exceeded. +.P +The +\fIpthread_rwlock_rdlock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected or the current thread already owns +the read-write lock for writing. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_rdlock\fR() +or +\fIpthread_rwlock_tryrdlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlock_timedrdlock.3p b/man-pages-posix-2013-a/man3p/pthread_rwlock_timedrdlock.3p new file mode 100644 index 0000000..5ad394f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlock_timedrdlock.3p @@ -0,0 +1,148 @@ +'\" et +.TH PTHREAD_RWLOCK_TIMEDRDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlock_timedrdlock +\(em lock a read-write lock for reading +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict \fIrwlock\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_timedrdlock\fR() +function shall apply a read lock to the read-write lock referenced by +.IR rwlock +as in the +\fIpthread_rwlock_rdlock\fR() +function. However, if the lock cannot be acquired without waiting for +other threads to unlock the lock, this wait shall be terminated when +the specified timeout expires. The timeout shall expire when the +absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the +CLOCK_REALTIME clock. The +.BR timespec +data type is defined in the +.IR +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +.IR abstime +parameter need not be checked if the lock can be immediately acquired. +.P +If a signal that causes a signal handler to be executed is delivered to +a thread blocked on a read-write lock via a call to +\fIpthread_rwlock_timedrdlock\fR(), +upon return from the signal handler the thread shall resume waiting for +the lock as if it was not interrupted. +.P +The calling thread may deadlock if at the time the call is made it +holds a write lock on +.IR rwlock . +The results are undefined if this function is called with an +uninitialized read-write lock. +.SH "RETURN VALUE" +The +\fIpthread_rwlock_timedrdlock\fR() +function shall return zero if the lock for reading on the read-write +lock object referenced by +.IR rwlock +is acquired. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +The +\fIpthread_rwlock_timedrdlock\fR() +function shall fail if: +.TP +.BR ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.P +The +\fIpthread_rwlock_timedrdlock\fR() +function may fail if: +.TP +.BR EAGAIN +The read lock could not be acquired because the maximum number of read +locks for lock would be exceeded. +.TP +.BR EDEADLK +A deadlock condition was detected or the calling thread already holds a +write lock on +.IR rwlock . +.TP +.BR EINVAL +The +.IR abstime +nanosecond value is less than zero or greater than or equal to 1\|000 +million. +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_timedrdlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlock_timedwrlock.3p b/man-pages-posix-2013-a/man3p/pthread_rwlock_timedwrlock.3p new file mode 100644 index 0000000..3cc9dbe --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlock_timedwrlock.3p @@ -0,0 +1,141 @@ +'\" et +.TH PTHREAD_RWLOCK_TIMEDWRLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlock_timedwrlock +\(em lock a read-write lock for writing +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict \fIrwlock\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_timedwrlock\fR() +function shall apply a write lock to the read-write lock referenced by +.IR rwlock +as in the +\fIpthread_rwlock_wrlock\fR() +function. However, if the lock cannot be acquired without waiting for +other threads to unlock the lock, this wait shall be terminated when +the specified timeout expires. The timeout shall expire when the +absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the +CLOCK_REALTIME clock. The +.BR timespec +data type is defined in the +.IR +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +.IR abstime +parameter need not be checked if the lock can be immediately acquired. +.P +If a signal that causes a signal handler to be executed is delivered to +a thread blocked on a read-write lock via a call to +\fIpthread_rwlock_timedwrlock\fR(), +upon return from the signal handler the thread shall resume waiting for +the lock as if it was not interrupted. +.P +The calling thread may deadlock if at the time the call is made it +holds the read-write lock. The results are undefined if this function +is called with an uninitialized read-write lock. +.SH "RETURN VALUE" +The +\fIpthread_rwlock_timedwrlock\fR() +function shall return zero if the lock for writing on the read-write +lock object referenced by +.IR rwlock +is acquired. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +The +\fIpthread_rwlock_timedwrlock\fR() +function shall fail if: +.TP +.BR ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.P +The +\fIpthread_rwlock_timedwrlock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected or the calling thread already holds the +.IR rwlock . +.TP +.BR EINVAL +The +.IR abstime +nanosecond value is less than zero or greater than or equal to 1\|000 +million. +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_timedwrlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlock_tryrdlock.3p b/man-pages-posix-2013-a/man3p/pthread_rwlock_tryrdlock.3p new file mode 100644 index 0000000..ef9a3b7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlock_tryrdlock.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_RWLOCK_TRYRDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlock_tryrdlock +\(em lock a read-write lock object for reading +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_tryrdlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlock_trywrlock.3p b/man-pages-posix-2013-a/man3p/pthread_rwlock_trywrlock.3p new file mode 100644 index 0000000..30313d2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlock_trywrlock.3p @@ -0,0 +1,133 @@ +'\" et +.TH PTHREAD_RWLOCK_TRYWRLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlock_trywrlock, +pthread_rwlock_wrlock +\(em lock a read-write lock object for writing +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_trywrlock(pthread_rwlock_t *\fIrwlock\fP); +int pthread_rwlock_wrlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_trywrlock\fR() +function shall apply a write lock like the +\fIpthread_rwlock_wrlock\fR() +function, with the exception that the function shall fail if any thread +currently holds +.IR rwlock +(for reading or writing). +.P +The +\fIpthread_rwlock_wrlock\fR() +function shall apply a write lock to the read-write lock referenced by +.IR rwlock . +The calling thread acquires the write lock if no other thread (reader +or writer) holds the read-write lock +.IR rwlock . +Otherwise, the thread shall block until it can acquire the lock. The +calling thread may deadlock if at the time the call is made it holds +the read-write lock (whether a read or write lock). +.P +Implementations may favor writers over readers to avoid +writer starvation. +.P +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.P +If a signal is delivered to a thread waiting for a read-write lock for +writing, upon return from the signal handler the thread resumes waiting +for the read-write lock for writing as if it was not interrupted. +.SH "RETURN VALUE" +The +\fIpthread_rwlock_trywrlock\fR() +function shall return zero if the lock for writing on the read-write +lock object referenced by +.IR rwlock +is acquired. Otherwise, an error number shall be returned to indicate +the error. +.P +If successful, the +\fIpthread_rwlock_wrlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlock_trywrlock\fR() +function shall fail if: +.TP +.BR EBUSY +The read-write lock could not be acquired for writing because it was +already locked for reading or writing. +.P +The +\fIpthread_rwlock_wrlock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected or the current thread already owns +the read-write lock for writing or reading. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_trywrlock\fR() +or +\fIpthread_rwlock_wrlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlock_unlock.3p b/man-pages-posix-2013-a/man3p/pthread_rwlock_unlock.3p new file mode 100644 index 0000000..5583dc5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlock_unlock.3p @@ -0,0 +1,119 @@ +'\" et +.TH PTHREAD_RWLOCK_UNLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlock_unlock +\(em unlock a read-write lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_unlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_unlock\fR() +function shall release a lock held on the read-write lock object +referenced by +.IR rwlock . +Results are undefined if the read-write lock +.IR rwlock +is not held by the calling thread. +.P +If this function is called to release a read lock from the read-write +lock object and there are other read locks currently held on this +read-write lock object, the read-write lock object remains in the read +locked state. If this function releases the last read lock for this +read-write lock object, the read-write lock object shall be put in the +unlocked state with no owners. +.P +If this function is called to release a write lock for this read-write +lock object, the read-write lock object shall be put in the unlocked +state. +.P +If there are threads blocked on the lock when it becomes available, the +scheduling policy shall determine which thread(s) shall acquire the +lock. +If the Thread Execution Scheduling option is supported, when threads +executing with the scheduling policies SCHED_FIFO, SCHED_RR, or +SCHED_SPORADIC are waiting on the lock, they shall acquire the lock in +priority order when the lock becomes available. For equal priority +threads, write locks shall take precedence over read locks. +If the Thread Execution Scheduling option is not supported, it is +implementation-defined whether write locks take precedence over read +locks. +.P +Results are undefined if this function is called with an uninitialized +read-write lock. +.SH "RETURN VALUE" +If successful, the +\fIpthread_rwlock_unlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlock_unlock\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_unlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_unlock\fR() +refers to a read-write lock object for which the current thread does +not hold a lock, it is recommended that the function should fail +and report an +.BR [EPERM] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlock_wrlock.3p b/man-pages-posix-2013-a/man3p/pthread_rwlock_wrlock.3p new file mode 100644 index 0000000..c6a2940 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlock_wrlock.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_RWLOCK_WRLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlock_wrlock +\(em lock a read-write lock object for writing +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_wrlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlockattr_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_rwlockattr_destroy.3p new file mode 100644 index 0000000..330812b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlockattr_destroy.3p @@ -0,0 +1,115 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlockattr_destroy, +pthread_rwlockattr_init +\(em destroy and initialize the read-write lock attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlockattr_destroy(pthread_rwlockattr_t *\fIattr\fP); +int pthread_rwlockattr_init(pthread_rwlockattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlockattr_destroy\fR() +function shall destroy a read-write lock attributes object. A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_rwlockattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. An implementation may cause +\fIpthread_rwlockattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +The +\fIpthread_rwlockattr_init\fR() +function shall initialize a read-write lock attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +Results are undefined if +\fIpthread_rwlockattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +After a read-write lock attributes object has been used to initialize +one or more read-write locks, any function affecting the attributes +object (including destruction) shall not affect any previously +initialized read-write locks. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_rwlockattr_destroy\fR() +does not refer to an initialized read-write lock attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_rwlockattr_destroy\fR() +and +\fIpthread_rwlockattr_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlockattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the read-write lock attributes +object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_rwlockattr_destroy\fR() +does not refer to an initialized read-write lock attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlockattr_getpshared\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlockattr_getpshared.3p b/man-pages-posix-2013-a/man3p/pthread_rwlockattr_getpshared.3p new file mode 100644 index 0000000..aae565c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlockattr_getpshared.3p @@ -0,0 +1,124 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_GETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlockattr_getpshared, +pthread_rwlockattr_setpshared +\(em get and set the process-shared attribute of the read-write lock +attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t + *restrict \fIattr\fP, int *restrict \fIpshared\fP); +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlockattr_getpshared\fR() +function shall obtain the value of the +.IR process-shared +attribute from the initialized attributes object referenced by +.IR attr . +The +\fIpthread_rwlockattr_setpshared\fR() +function shall set the +.IR process-shared +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR process-shared +attribute shall be set to PTHREAD_PROCESS_SHARED to +permit a read-write lock to be operated upon by any thread that has +access to the memory where the read-write lock is allocated, even if +the read-write lock is allocated in memory that is shared by multiple +processes. If the +.IR process-shared +attribute is PTHREAD_PROCESS_PRIVATE, the +read-write lock shall only be operated upon by threads created within +the same process as the thread that initialized the read-write lock; if +threads of differing processes attempt to operate on such a read-write +lock, the behavior is undefined. The default value of the +.IR process-shared +attribute shall be PTHREAD_PROCESS_PRIVATE. +.P +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_rwlockattr_getpshared\fR() +or +\fIpthread_rwlockattr_setpshared\fR() +does not refer to an initialized read-write lock attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_rwlockattr_getpshared\fR() +function shall return zero and store the value of the +.IR process-shared +attribute of +.IR attr +into the object referenced by the +.IR pshared +parameter. Otherwise, an error number shall be returned to indicate the +error. +.P +If successful, the +\fIpthread_rwlockattr_setpshared\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlockattr_setpshared\fR() +function may fail if: +.TP +.BR EINVAL +The new value specified for the attribute is outside the range of legal +values for that attribute. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlockattr_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlockattr_init.3p b/man-pages-posix-2013-a/man3p/pthread_rwlockattr_init.3p new file mode 100644 index 0000000..31736b5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlockattr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlockattr_init +\(em initialize the read-write lock attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlockattr_init(pthread_rwlockattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_rwlockattr_destroy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_rwlockattr_setpshared.3p b/man-pages-posix-2013-a/man3p/pthread_rwlockattr_setpshared.3p new file mode 100644 index 0000000..929fbac --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_rwlockattr_setpshared.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_SETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_rwlockattr_setpshared +\(em set the process-shared attribute of the read-write lock +attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_rwlockattr_getpshared\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_self.3p b/man-pages-posix-2013-a/man3p/pthread_self.3p new file mode 100644 index 0000000..d63a03b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_self.3p @@ -0,0 +1,67 @@ +'\" et +.TH PTHREAD_SELF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_self +\(em get the calling thread ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pthread_t pthread_self(void); +.fi +.SH DESCRIPTION +The +\fIpthread_self\fR() +function shall return the thread ID of the calling thread. +.SH "RETURN VALUE" +The +\fIpthread_self\fR() +function shall always be successful and no return value is +reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_self\fR() +function provides a capability similar to the +\fIgetpid\fR() +function for processes and the rationale is the same: the creation +call does not provide the thread ID to the created thread. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_equal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_setcancelstate.3p b/man-pages-posix-2013-a/man3p/pthread_setcancelstate.3p new file mode 100644 index 0000000..c7663d6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_setcancelstate.3p @@ -0,0 +1,153 @@ +'\" et +.TH PTHREAD_SETCANCELSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_setcancelstate, +pthread_setcanceltype, +pthread_testcancel +\(em set cancelability state +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setcancelstate(int \fIstate\fP, int *\fIoldstate\fP); +int pthread_setcanceltype(int \fItype\fP, int *\fIoldtype\fP); +void pthread_testcancel(void); +.fi +.SH DESCRIPTION +The +\fIpthread_setcancelstate\fR() +function shall atomically both set the calling thread's cancelability +state to the indicated +.IR state +and return the previous cancelability state at the location referenced +by +.IR oldstate . +Legal values for +.IR state +are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. +.P +The +\fIpthread_setcanceltype\fR() +function shall atomically both set the calling thread's cancelability +type to the indicated +.IR type +and return the previous cancelability type at the location referenced +by +.IR oldtype . +Legal values for +.IR type +are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. +.P +The cancelability state and type of any newly created threads, +including the thread in which +\fImain\fR() +was first invoked, shall be PTHREAD_CANCEL_ENABLE and +PTHREAD_CANCEL_DEFERRED respectively. +.P +The +\fIpthread_testcancel\fR() +function shall create a cancellation point in the calling thread. The +\fIpthread_testcancel\fR() +function shall have no effect if cancelability is disabled. +.SH "RETURN VALUE" +If successful, the +\fIpthread_setcancelstate\fR() +and +\fIpthread_setcanceltype\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_setcancelstate\fR() +function may fail if: +.TP +.BR EINVAL +The specified state is not PTHREAD_CANCEL_ENABLE or +PTHREAD_CANCEL_DISABLE. +.P +The +\fIpthread_setcanceltype\fR() +function may fail if: +.TP +.BR EINVAL +The specified type is not PTHREAD_CANCEL_DEFERRED or +PTHREAD_CANCEL_ASYNCHRONOUS. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_setcancelstate\fR() +and +\fIpthread_setcanceltype\fR() +functions control the points at which a thread may be +asynchronously canceled. For cancellation control to be usable in +modular fashion, some rules need to be followed. +.P +An object can be considered to be a generalization of a procedure. It +is a set of procedures and global variables written as a unit and +called by clients not known by the object. Objects may depend on other +objects. +.P +First, cancelability should only be disabled on entry to an object, +never explicitly enabled. On exit from an object, the +cancelability state should always be restored to its value on entry to +the object. +.P +This follows from a modularity argument: if the client of an object +(or the client of an object that uses that object) has disabled +cancelability, it is because the client does not want to be concerned +about cleaning up if the thread is canceled while executing some +sequence of actions. If an object is called in such a state and it +enables cancelability and a cancellation request is pending for that +thread, then the thread is canceled, contrary to the wish of the client +that disabled. +.P +Second, the +cancelability type may be explicitly set to either +.IR deferred +or +.IR asynchronous +upon entry to an object. But as with the cancelability state, on exit +from an object the cancelability type should always be restored to its +value on entry to the object. +.P +Finally, only functions that are cancel-safe +may be called from a thread that is asynchronously cancelable. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cancel\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_setconcurrency.3p b/man-pages-posix-2013-a/man3p/pthread_setconcurrency.3p new file mode 100644 index 0000000..8b517b0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_setconcurrency.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_SETCONCURRENCY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_setconcurrency +\(em set the level of concurrency +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setconcurrency(int \fInew_level\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_getconcurrency\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_setschedparam.3p b/man-pages-posix-2013-a/man3p/pthread_setschedparam.3p new file mode 100644 index 0000000..d59b83b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_setschedparam.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_SETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_setschedparam +\(em dynamic thread scheduling parameters access +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setschedparam(pthread_t \fIthread\fP, int \fIpolicy\fP, + const struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_getschedparam\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_setschedprio.3p b/man-pages-posix-2013-a/man3p/pthread_setschedprio.3p new file mode 100644 index 0000000..5b936ac --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_setschedprio.3p @@ -0,0 +1,115 @@ +'\" et +.TH PTHREAD_SETSCHEDPRIO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_setschedprio +\(em dynamic thread scheduling parameters access +(\fBREALTIME THREADS\fR) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setschedprio(pthread_t \fIthread\fP, int \fIprio\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_setschedprio\fR() +function shall set the scheduling priority for the thread whose thread +ID is given by +.IR thread +to the value given by +.IR prio . +See +.IR "Scheduling Policies" +for a description on how this function call affects the ordering of the +thread in the thread list for its new priority. +.P +If the +\fIpthread_setschedprio\fR() +function fails, the scheduling priority of the target thread shall not +be changed. +.SH "RETURN VALUE" +If successful, the +\fIpthread_setschedprio\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_setschedprio\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR prio +is invalid for the scheduling policy of the specified thread. +.TP +.BR EPERM +The caller does not have appropriate privileges to set the scheduling +priority of the specified thread. +.P +The +\fIpthread_setschedprio\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_setschedprio\fR() +function provides a way for an application to temporarily raise its +priority and then lower it again, without having the undesired +side-effect of yielding to other threads of the same priority. This is +necessary if the application is to implement its own strategies for +bounding priority inversion, such as priority inheritance or priority +ceilings. This capability is especially important if the implementation +does not support the Thread Priority Protection or Thread Priority +Inheritance options, but even if those options are supported it is +needed if the application is to bound priority inheritance for other +resources, such as semaphores. +.P +The standard developers considered that while it might be preferable +conceptually to solve this problem by modifying the specification of +\fIpthread_setschedparam\fR(), +it was too late to make such a change, as there may be implementations +that would need to be changed. Therefore, this new function was +introduced. +.P +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Scheduling Policies", +.IR "\fIpthread_getschedparam\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_setspecific.3p b/man-pages-posix-2013-a/man3p/pthread_setspecific.3p new file mode 100644 index 0000000..3ea1e51 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_setspecific.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_SETSPECIFIC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_setspecific +\(em thread-specific data management +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setspecific(pthread_key_t \fIkey\fP, const void *\fIvalue\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_getspecific\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_sigmask.3p b/man-pages-posix-2013-a/man3p/pthread_sigmask.3p new file mode 100644 index 0000000..7c70fb4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_sigmask.3p @@ -0,0 +1,248 @@ +'\" et +.TH PTHREAD_SIGMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_sigmask, +sigprocmask +\(em examine and change blocked signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_sigmask(int \fIhow\fP, const sigset_t *restrict \fIset\fP, + sigset_t *restrict \fIoset\fP); +int sigprocmask(int \fIhow\fP, const sigset_t *restrict \fIset\fP, + sigset_t *restrict \fIoset\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_sigmask\fR() +function shall examine or change (or both) the calling thread's +signal mask, regardless of the number of threads in the process. The +function shall be equivalent to +\fIsigprocmask\fR(), +without the restriction that the call be made in a single-threaded +process. +.P +In a single-threaded process, the +\fIsigprocmask\fR() +function shall examine or change (or both) the signal mask of the +calling thread. +.P +If the argument +.IR set +is not a null pointer, it points to a set of signals to be used to +change the currently blocked set. +.P +The argument +.IR how +indicates the way in which the set is changed, and the application +shall ensure it consists of one of the following values: +.IP SIG_BLOCK 12 +The resulting set shall be the union of the current set and the signal +set pointed to by +.IR set . +.IP SIG_SETMASK 12 +The resulting set shall be the signal set pointed to by +.IR set . +.IP SIG_UNBLOCK 12 +The resulting set shall be the intersection of the current set and the +complement of the signal set pointed to by +.IR set . +.P +If the argument +.IR oset +is not a null pointer, the previous mask shall be stored in the location +pointed to by +.IR oset . +If +.IR set +is a null pointer, the value of the argument +.IR how +is not significant and the thread's signal mask shall be unchanged; +thus the call can be used to enquire about currently blocked signals. +.P +If there are any pending unblocked signals after the call to +\fIsigprocmask\fR(), +at least one of those signals shall be delivered before the call to +\fIsigprocmask\fR() +returns. +.P +It is not possible to block those signals which cannot be ignored. +This shall be enforced by the system without causing an error to be +indicated. +.P +If any of the SIGFPE, SIGILL, SIGSEGV, or SIGBUS +signals are generated while they are blocked, the result is undefined, +unless the signal was generated by the action of another process, or by +one of the functions +\fIkill\fR(), +\fIpthread_kill\fR(), +\fIraise\fR(), +or +\fIsigqueue\fR(). +.P +If +\fIsigprocmask\fR() +fails, the thread's signal mask shall not be changed. +.P +The use of the +\fIsigprocmask\fR() +function is unspecified in a multi-threaded process. +.SH "RETURN VALUE" +Upon successful completion +\fIpthread_sigmask\fR() +shall return 0; otherwise, it shall return the corresponding error +number. +.P +Upon successful completion, +\fIsigprocmask\fR() +shall return 0; otherwise, \(mi1 shall be returned, +.IR errno +shall be set to indicate the error, and the signal mask of the process +shall be unchanged. +.SH ERRORS +The +\fIpthread_sigmask\fR() +and +\fIsigprocmask\fR() +functions shall fail if: +.TP +.BR EINVAL +The value of the +.IR how +argument is not equal to one of the defined values. +.P +The +\fIpthread_sigmask\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Signaling in a Multi-Threaded Process" +.P +This example shows the use of +\fIpthread_sigmask\fR() +in order to deal with signals in a multi-threaded process. It provides +a fairly general framework that could be easily adapted/extended. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +\&... +.P +static sigset_t signal_mask; /* signals to block */ +.P +int main (int argc, char *argv[]) +{ + pthread_t sig_thr_id; /* signal handler thread ID */ + int rc; /* return code */ +.P + sigemptyset (&signal_mask); + sigaddset (&signal_mask, SIGINT); + sigaddset (&signal_mask, SIGTERM); + rc = pthread_sigmask (SIG_BLOCK, &signal_mask, NULL); + if (rc != 0) { + /* handle error */ + ... + } + /* any newly created threads inherit the signal mask */ +.P + rc = pthread_create (&sig_thr_id, NULL, signal_thread, NULL); + if (rc != 0) { + /* handle error */ + ... + } +.P + /* APPLICATION CODE */ + ... +} +.P +void *signal_thread (void *arg) +{ + int sig_caught; /* signal caught */ + int rc; /* returned code */ +.P + rc = sigwait (&signal_mask, &sig_caught); + if (rc != 0) { + /* handle error */ + } + switch (sig_caught) + { + case SIGINT: /* process SIGINT */ + ... + break; + case SIGTERM: /* process SIGTERM */ + ... + break; + default: /* should normally not happen */ + fprintf (stderr, "\enUnexpected signal %d\en", sig_caught); + break; + } +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +When a thread's signal mask is changed in a signal-catching function +that is installed by +\fIsigaction\fR(), +the restoration of the signal mask on return from the signal-catching +function overrides that change (see +\fIsigaction\fR()). +If the signal-catching function was installed with +\fIsignal\fR(), +it is unspecified whether this occurs. +.P +See +\fIkill\fR() +for a discussion of the requirement on delivery of signals. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIkill\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigqueue\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_spin_destroy.3p b/man-pages-posix-2013-a/man3p/pthread_spin_destroy.3p new file mode 100644 index 0000000..6b74c45 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_spin_destroy.3p @@ -0,0 +1,155 @@ +'\" et +.TH PTHREAD_SPIN_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_spin_destroy, +pthread_spin_init +\(em destroy or initialize a spin lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_spin_destroy(pthread_spinlock_t *\fIlock\fP); +int pthread_spin_init(pthread_spinlock_t *\fIlock\fP, int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_spin_destroy\fR() +function shall destroy the spin lock referenced by +.IR lock +and release any resources used by the lock. The effect of subsequent +use of the lock is undefined until the lock is reinitialized by another +call to +\fIpthread_spin_init\fR(). +The results are undefined if +\fIpthread_spin_destroy\fR() +is called when a thread holds the lock, or if this function is called +with an uninitialized thread spin lock. +.P +The +\fIpthread_spin_init\fR() +function shall allocate any resources required to use the spin lock +referenced by +.IR lock +and initialize the lock to an unlocked state. +.P +If the Thread Process-Shared Synchronization option is supported and +the value of +.IR pshared +is PTHREAD_PROCESS_SHARED, the implementation +shall permit the spin lock to be operated upon by any thread that has +access to the memory where the spin lock is allocated, even if it is +allocated in memory that is shared by multiple processes. +.P +If the Thread Process-Shared Synchronization option is supported and +the value of +.IR pshared +is PTHREAD_PROCESS_PRIVATE, +or if the option is not supported, the spin lock shall only be operated +upon by threads created within the same process as the thread that +initialized the spin lock. If threads of differing processes attempt to +operate on such a spin lock, the behavior is undefined. +.P +The results are undefined if +\fIpthread_spin_init\fR() +is called specifying an already initialized spin lock. The results are +undefined if a spin lock is used without first being initialized. +.P +If the +\fIpthread_spin_init\fR() +function fails, the lock is not initialized and the contents of +.IR lock +are undefined. +.P +Only the object referenced by +.IR lock +may be used for performing synchronization. +.P +The result of referring to copies of that object in calls to +\fIpthread_spin_destroy\fR(), +\fIpthread_spin_lock\fR(), +\fIpthread_spin_trylock\fR(), +or +\fIpthread_spin_unlock\fR() +is undefined. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIpthread_spin_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacks the necessary resources to initialize another spin +lock. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the lock. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_destroy\fR() +does not refer to an initialized spin lock object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_destroy\fR() +or +\fIpthread_spin_init\fR() +refers to a locked spin lock object, or detects that the value specified +by the +.IR lock +argument to +\fIpthread_spin_init\fR() +refers to an already initialized spin lock object, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_spin_lock\fR\^(\|)", +.IR "\fIpthread_spin_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_spin_lock.3p b/man-pages-posix-2013-a/man3p/pthread_spin_lock.3p new file mode 100644 index 0000000..8daf932 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_spin_lock.3p @@ -0,0 +1,114 @@ +'\" et +.TH PTHREAD_SPIN_LOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_spin_lock, +pthread_spin_trylock +\(em lock a spin lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_spin_lock(pthread_spinlock_t *\fIlock\fP); +int pthread_spin_trylock(pthread_spinlock_t *\fIlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_spin_lock\fR() +function shall lock the spin lock referenced by +.IR lock . +The calling thread shall acquire the lock if it is not held by another +thread. Otherwise, the thread shall spin (that is, shall not return +from the +\fIpthread_spin_lock\fR() +call) until the lock becomes available. The results are undefined if +the calling thread holds the lock at the time the call is made. The +\fIpthread_spin_trylock\fR() +function shall lock the spin lock referenced by +.IR lock +if it is not held by any thread. Otherwise, the function shall fail. +.P +The results are undefined if any of these functions is called with an +uninitialized spin lock. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIpthread_spin_lock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.P +The +\fIpthread_spin_trylock\fR() +function shall fail if: +.TP +.BR EBUSY +A thread currently holds the lock. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_lock\fR() +or +\fIpthread_spin_trylock\fR() +does not refer to an initialized spin lock object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_lock\fR() +refers to a spin lock object for which the calling thread already +holds the lock, it is recommended that the function should fail +and report an +.BR [EDEADLK] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_spin_destroy\fR\^(\|)", +.IR "\fIpthread_spin_unlock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_spin_unlock.3p b/man-pages-posix-2013-a/man3p/pthread_spin_unlock.3p new file mode 100644 index 0000000..d0c4c9e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_spin_unlock.3p @@ -0,0 +1,98 @@ +'\" et +.TH PTHREAD_SPIN_UNLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_spin_unlock +\(em unlock a spin lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_spin_unlock(pthread_spinlock_t *\fIlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_spin_unlock\fR() +function shall release the spin lock referenced by +.IR lock +which was locked via the +\fIpthread_spin_lock\fR() +or +\fIpthread_spin_trylock\fR() +functions. +.P +The results are undefined if the lock is not held by the +calling thread. +.P +If there are threads spinning on the lock when +\fIpthread_spin_unlock\fR() +is called, the lock becomes available and an unspecified spinning +thread shall acquire the lock. +.P +The results are undefined if this function is called with an +uninitialized thread spin lock. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_spin_unlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_unlock\fR() +does not refer to an initialized spin lock object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_unlock\fR() +refers to a spin lock object for which the current thread does not +hold the lock, it is recommended that the function should fail +and report an +.BR [EPERM] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_spin_destroy\fR\^(\|)", +.IR "\fIpthread_spin_lock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pthread_testcancel.3p b/man-pages-posix-2013-a/man3p/pthread_testcancel.3p new file mode 100644 index 0000000..14e255c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pthread_testcancel.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_TESTCANCEL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pthread_testcancel +\(em set cancelability state +.SH SYNOPSIS +.LP +.nf +#include +.P +void pthread_testcancel(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_setcancelstate\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ptsname.3p b/man-pages-posix-2013-a/man3p/ptsname.3p new file mode 100644 index 0000000..e3032bf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ptsname.3p @@ -0,0 +1,86 @@ +'\" et +.TH PTSNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ptsname +\(em get name of the slave pseudo-terminal device +.SH SYNOPSIS +.LP +.nf +#include +.P +char *ptsname(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIptsname\fR() +function shall return the name of the slave pseudo-terminal device +associated with a master pseudo-terminal device. The +.IR fildes +argument is a file descriptor that refers to the master device. The +\fIptsname\fR() +function shall return a pointer to a string containing the pathname +of the corresponding slave device. +.P +The +\fIptsname\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIptsname\fR() +shall return a pointer to a string which is the name of the +pseudo-terminal slave device. Upon failure, +\fIptsname\fR() +shall return a null pointer. This could occur if +.IR fildes +is an invalid file descriptor or if the slave device name does not +exist in the file system. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIptsname\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIposix_openpt\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_openpt\fR\^(\|)", +.IR "\fIttyname\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/putc.3p b/man-pages-posix-2013-a/man3p/putc.3p new file mode 100644 index 0000000..de09fc5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/putc.3p @@ -0,0 +1,78 @@ +'\" et +.TH PUTC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +putc +\(em put a byte on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int putc(int \fIc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIputc\fR() +function shall be equivalent to +\fIfputc\fR(), +except that if it is implemented as a macro it may evaluate +.IR stream +more than once, so the argument should never be an expression with +side-effects. +.SH "RETURN VALUE" +Refer to +.IR "\fIfputc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since it may be implemented as a macro, +\fIputc\fR() +may treat a +.IR stream +argument with side-effects incorrectly. In particular, +\fIputc\fP(\fIc\fP,*\fIf\fP++) does not necessarily work correctly. +Therefore, use of this function is not recommended in such situations; +\fIfputc\fR() +should be used instead. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfputc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/putc_unlocked.3p b/man-pages-posix-2013-a/man3p/putc_unlocked.3p new file mode 100644 index 0000000..f4db2ca --- /dev/null +++ b/man-pages-posix-2013-a/man3p/putc_unlocked.3p @@ -0,0 +1,38 @@ +'\" et +.TH PUTC_UNLOCKED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +putc_unlocked +\(em stdio with explicit client locking +.SH SYNOPSIS +.LP +.nf +#include +.P +int putc_unlocked(int \fIc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetc_unlocked\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/putchar.3p b/man-pages-posix-2013-a/man3p/putchar.3p new file mode 100644 index 0000000..7a59c4c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/putchar.3p @@ -0,0 +1,65 @@ +'\" et +.TH PUTCHAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +putchar +\(em put a byte on a stdout stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int putchar(int \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The function call +.IR putchar ( c ) +shall be equivalent to \fIputc\fP(\fIc\fP,\fIstdout\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIfputc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIputc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/putchar_unlocked.3p b/man-pages-posix-2013-a/man3p/putchar_unlocked.3p new file mode 100644 index 0000000..97e28b8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/putchar_unlocked.3p @@ -0,0 +1,38 @@ +'\" et +.TH PUTCHAR_UNLOCKED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +putchar_unlocked +\(em stdio with explicit client locking +.SH SYNOPSIS +.LP +.nf +#include +.P +int putchar_unlocked(int \fIc\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetc_unlocked\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/putenv.3p b/man-pages-posix-2013-a/man3p/putenv.3p new file mode 100644 index 0000000..6b2b177 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/putenv.3p @@ -0,0 +1,159 @@ +'\" et +.TH PUTENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +putenv +\(em change or add a value to an environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int putenv(char *\fIstring\fP); +.fi +.SH DESCRIPTION +The +\fIputenv\fR() +function shall use the +.IR string +argument to set environment variable values. The +.IR string +argument should point to a string of the form "\c +.IR name =\c +.IR value \c +\&". +The +\fIputenv\fR() +function shall make the value of the environment variable +.IR name +equal to +.IR value +by altering an existing variable or creating a new one. In either +case, the string pointed to by +.IR string +shall become part of the environment, so altering the string shall +change the environment. +.P +The +\fIputenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIputenv\fR() +shall return 0; otherwise, it shall return a non-zero value and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIputenv\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient memory was available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Value of an Environment Variable" +.P +The following example changes the value of the +.IR HOME +environment variable to the value +.BR /usr/home . +.sp +.RS 4 +.nf +\fB +#include +\&... +static char *var = "HOME=/usr/home"; +int ret; +.P +ret = putenv(var); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIputenv\fR() +function manipulates the environment pointed to by +.IR environ , +and can be used in conjunction with +\fIgetenv\fR(). +.P +See +\fIexec\fR() +for restrictions on changing the environment in multi-threaded +applications. +.P +This routine may use +\fImalloc\fR() +to enlarge the environment. +.P +A potential error is to call +\fIputenv\fR() +with an automatic variable as the argument, then return from the +calling function while +.IR string +is still part of the environment. +.P +Although the space used by +.IR string +is no longer used once a new string which defines +.IR name +is passed to +\fIputenv\fR(), +if any thread in the application has used +\fIgetenv\fR() +to retrieve a pointer to this variable, it should not be freed by calling +\fIfree\fR(). +If the changed environment variable is one known by the system (such as +the locale environment variables) the application should never free the +buffer used by earlier calls to +\fIputenv\fR() +for the same variable. +.P +The +\fIsetenv\fR() +function is preferred over this function. One reason is that +\fIputenv\fR() +is optional and therefore less portable. Another is that using +\fIputenv\fR() +can slow down environment searches, as explained in the RATIONALE +section for +.IR "\fIgetenv\fR\^(\|)". +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetenv\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfree\fR\^(\|)", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/putmsg.3p b/man-pages-posix-2013-a/man3p/putmsg.3p new file mode 100644 index 0000000..ff4ec56 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/putmsg.3p @@ -0,0 +1,361 @@ +'\" et +.TH PUTMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +putmsg, +putpmsg +\(em send a message on a STREAM (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int putmsg(int \fIfildes\fP, const struct strbuf *\fIctlptr\fP, + const struct strbuf *\fIdataptr\fP, int \fIflags\fP); +int putpmsg(int \fIfildes\fP, const struct strbuf *\fIctlptr\fP, + const struct strbuf *\fIdataptr\fP, int \fIband\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIputmsg\fR() +function shall create a message from a process buffer(s) and send the +message to a STREAMS file. The message may contain either a data part, +a control part, or both. The data and control parts are distinguished +by placement in separate buffers, as described below. The semantics of +each part are defined by the STREAMS module that receives the message. +.P +The +\fIputpmsg\fR() +function is equivalent to +\fIputmsg\fR(), +except that the process can send messages in different priority bands. +Except where noted, all requirements on +\fIputmsg\fR() +also pertain to +\fIputpmsg\fR(). +.P +The +.IR fildes +argument specifies a file descriptor referencing an open STREAM. The +.IR ctlptr +and +.IR dataptr +arguments each point to a +.BR strbuf +structure. +.P +The +.IR ctlptr +argument points to the structure describing the control part, if any, +to be included in the message. The +.IR buf +member in the +.BR strbuf +structure points to the buffer where the control information resides, +and the +.IR len +member indicates the number of bytes to be sent. The +.IR maxlen +member is not used by +\fIputmsg\fR(). +In a similar manner, the argument +.IR dataptr +specifies the data, if any, to be included in the message. The +.IR flags +argument indicates what type of message should be sent and is described +further below. +.P +To send the data part of a message, the application shall ensure that +.IR dataptr +is not a null pointer and the +.IR len +member of +.IR dataptr +is 0 or greater. To send the control part of a message, the application +shall ensure that the corresponding values are set for +.IR ctlptr . +No data (control) part shall be sent if either +.IR dataptr (\c +.IR ctlptr ) +is a null pointer or the +.IR len +member of +.IR dataptr (\c +.IR ctlptr ) +is set to \(mi1. +.P +For +\fIputmsg\fR(), +if a control part is specified and +.IR flags +is set to RS_HIPRI, a high +priority message shall be sent. If no control part is specified, and +.IR flags +is set to RS_HIPRI, +\fIputmsg\fR() +shall fail and set +.IR errno +to +.BR [EINVAL] . +If +.IR flags +is set to 0, a normal message (priority band equal to 0) shall be sent. +If a control part and data part are not specified and +.IR flags +is set to 0, no message shall be sent and 0 shall be returned. +.P +For +\fIputpmsg\fR(), +the flags are different. The +.IR flags +argument is a bitmask with the following mutually-exclusive flags +defined: MSG_HIPRI and MSG_BAND. If +.IR flags +is set to 0, +\fIputpmsg\fR() +shall fail and set +.IR errno +to +.BR [EINVAL] . +If a control part is specified and +.IR flags +is set to MSG_HIPRI and +.IR band +is set to 0, a high-priority message shall be sent. If +.IR flags +is set to MSG_HIPRI and either no control part is specified or +.IR band +is set to a non-zero value, +\fIputpmsg\fR() +shall fail and set +.IR errno +to +.BR [EINVAL] . +If +.IR flags +is set to MSG_BAND, then a message shall be sent in the priority band +specified by +.IR band . +If a control part and data part are not specified and +.IR flags +is set to MSG_BAND, no message shall be sent and 0 shall be returned. +.br +.P +The +\fIputmsg\fR() +function shall block if the STREAM write queue is full due to internal +flow control conditions, with the following exceptions: +.IP " *" 4 +For high-priority messages, +\fIputmsg\fR() +shall not block on this condition and continues processing the message. +.IP " *" 4 +For other messages, +\fIputmsg\fR() +shall not block but shall fail when the write queue is full and +O_NONBLOCK is set. +.P +The +\fIputmsg\fR() +function shall also block, unless prevented by lack of internal +resources, while waiting for the availability of message blocks in the +STREAM, regardless of priority or whether O_NONBLOCK has been +specified. No partial message shall be sent. +.SH "RETURN VALUE" +Upon successful completion, +\fIputmsg\fR() +and +\fIputpmsg\fR() +shall return 0; otherwise, they shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIputmsg\fR() +and +\fIputpmsg\fR() +functions shall fail if: +.TP +.BR EAGAIN +A non-priority message was specified, the O_NONBLOCK flag is set, and +the STREAM write queue is full due to internal flow control conditions; +or buffers could not be allocated for the message that was to be +created. +.TP +.BR EBADF +.IR fildes +is not a valid file descriptor open for writing. +.TP +.BR EINTR +A signal was caught during +\fIputmsg\fR(). +.TP +.BR EINVAL +An undefined value is specified in +.IR flags , +or +.IR flags +is set to RS_HIPRI or MSG_HIPRI and no control part is supplied, or the +STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer, or +.IR flags +is set to MSG_HIPRI and +.IR band +is non-zero (for +\fIputpmsg\fR() +only). +.TP +.BR ENOSR +Buffers could not be allocated for the message that was to be created +due to insufficient STREAMS memory resources. +.TP +.BR ENOSTR +A STREAM is not associated with +.IR fildes . +.TP +.BR ENXIO +A hangup condition was generated downstream for the specified STREAM. +.TP +.BR EPIPE " or " EIO +The +.IR fildes +argument refers to a STREAMS-based pipe and the other end of the pipe +is closed. A SIGPIPE signal is generated for the calling thread. +.TP +.BR ERANGE +The size of the data part of the message does not fall within the range +specified by the maximum and minimum packet sizes of the topmost STREAM +module. This value is also returned if the control part of the message +is larger than the maximum configured size of the control part of a +message, or if the data part of a message is larger than the maximum +configured size of the data part of a message. +.P +In addition, +\fIputmsg\fR() +and +\fIputpmsg\fR() +shall fail if the STREAM head had processed an asynchronous error +before the call. In this case, the value of +.IR errno +does not reflect the result of +\fIputmsg\fR() +or +\fIputpmsg\fR(), +but reflects the prior error. +.br +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Sending a High-Priority Message" +.P +The value of +.IR fd +is assumed to refer to an open STREAMS file. This call to +\fIputmsg\fR() +does the following: +.IP " 1." 4 +Creates a high-priority message with a control part and a data part, +using the buffers pointed to by +.IR ctrlbuf +and +.IR databuf , +respectively. +.IP " 2." 4 +Sends the message to the STREAMS file identified by +.IR fd . +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +int fd; +char *ctrlbuf = "This is the control part"; +char *databuf = "This is the data part"; +struct strbuf ctrl; +struct strbuf data; +int ret; +.P +ctrl.buf = ctrlbuf; +ctrl.len = strlen(ctrlbuf); +.P +data.buf = databuf; +data.len = strlen(databuf); +.P +ret = putmsg(fd, &ctrl, &data, MSG_HIPRI); +.fi \fR +.P +.RE +.SS "Using putpmsg(\|)" +.P +This example has the same effect as the previous example. In this +example, however, the +\fIputpmsg\fR() +function creates and sends the message to the STREAMS file. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +int fd; +char *ctrlbuf = "This is the control part"; +char *databuf = "This is the data part"; +struct strbuf ctrl; +struct strbuf data; +int ret; +.P +ctrl.buf = ctrlbuf; +ctrl.len = strlen(ctrlbuf); +.P +data.buf = databuf; +data.len = strlen(databuf); +.P +ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIputmsg\fR() +and +\fIputpmsg\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/puts.3p b/man-pages-posix-2013-a/man3p/puts.3p new file mode 100644 index 0000000..df4434a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/puts.3p @@ -0,0 +1,145 @@ +'\" et +.TH PUTS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +puts +\(em put a string on standard output +.SH SYNOPSIS +.LP +.nf +#include +.P +int puts(const char *\fIs\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIputs\fR() +function shall write the string pointed to by +.IR s , +followed by a +, +to the standard output stream +.IR stdout . +The terminating null byte shall not be written. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIputs\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIputs\fR() +shall return a non-negative number. Otherwise, it shall return EOF, +shall set an error indicator for the stream, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Printing to Standard Output" +.P +The following example gets the current time, converts it to a string +using +\fIlocaltime\fR() +and +\fIasctime\fR(), +and prints it to standard output using +\fIputs\fR(). +It then prints the number of minutes to an event for which it is +waiting. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +puts(asctime(localtime(&now))); +printf("There are %d minutes to the event.\en", + minutes_to_event); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIputs\fR() +function appends a +, +while +\fIfputs\fR() +does not. +.P +This volume of POSIX.1\(hy2008 requires that successful completion simply return a non-negative +integer. There are at least three known different implementation +conventions for this requirement: +.IP " *" 4 +Return a constant value. +.IP " *" 4 +Return the last character written. +.IP " *" 4 +Return the number of bytes written. Note that this implementation +convention cannot be adhered to for strings longer than +{INT_MAX} +bytes as the value would not be representable in the return type of the +function. For backwards compatibility, implementations can return the +number of bytes for strings of up to +{INT_MAX} +bytes, and return +{INT_MAX} +for all longer strings. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfputs\fR\^(\|)", +.IR "\fIputc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pututxline.3p b/man-pages-posix-2013-a/man3p/pututxline.3p new file mode 100644 index 0000000..ac93ce1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pututxline.3p @@ -0,0 +1,38 @@ +'\" et +.TH PUTUTXLINE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pututxline +\(em put an entry into the user accounting database +.SH SYNOPSIS +.LP +.nf +#include +.P +struct utmpx *pututxline(const struct utmpx *\fIutmpx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendutxent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/putwc.3p b/man-pages-posix-2013-a/man3p/putwc.3p new file mode 100644 index 0000000..5b52e09 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/putwc.3p @@ -0,0 +1,80 @@ +'\" et +.TH PUTWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +putwc +\(em put a wide character on a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t putwc(wchar_t \fIwc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIputwc\fR() +function shall be equivalent to +\fIfputwc\fR(), +except that if it is implemented as a macro it may evaluate +.IR stream +more than once, so the argument should never be an expression with +side-effects. +.SH "RETURN VALUE" +Refer to +.IR "\fIfputwc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfputwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since it may be implemented as a macro, +\fIputwc\fR() +may treat a +.IR stream +argument with side-effects incorrectly. In particular, +\fIputwc\fP(\fIwc\fP,*\fIf\fP++) need not work correctly. Therefore, +use of this function is not recommended; +\fIfputwc\fR() +should be used instead. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfputwc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/putwchar.3p b/man-pages-posix-2013-a/man3p/putwchar.3p new file mode 100644 index 0000000..4ad1398 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/putwchar.3p @@ -0,0 +1,66 @@ +'\" et +.TH PUTWCHAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +putwchar +\(em put a wide character on a stdout stream +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t putwchar(wchar_t \fIwc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The function call +.IR putwchar ( wc ) +shall be equivalent to \fIputwc\fP(\fIwc\fP,\fIstdout\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIfputwc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfputwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfputwc\fR\^(\|)", +.IR "\fIputwc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/pwrite.3p b/man-pages-posix-2013-a/man3p/pwrite.3p new file mode 100644 index 0000000..0713f73 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/pwrite.3p @@ -0,0 +1,39 @@ +'\" et +.TH PWRITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pwrite +\(em write on a file +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t pwrite(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP, + off_t \fIoffset\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwrite\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/qsort.3p b/man-pages-posix-2013-a/man3p/qsort.3p new file mode 100644 index 0000000..eeeaf94 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/qsort.3p @@ -0,0 +1,113 @@ +'\" et +.TH QSORT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qsort +\(em sort a table of data +.SH SYNOPSIS +.LP +.nf +#include +.P +void qsort(void *\fIbase\fP, size_t \fInel\fP, size_t \fIwidth\fP, + int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIqsort\fR() +function shall sort an array of +.IR nel +objects, the initial element of which is pointed to by +.IR base . +The size of each object, in bytes, is specified by the +.IR width +argument. If the +.IR nel +argument has the value zero, the comparison function pointed to by +.IR compar +shall not be called and no rearrangement shall take place. +.P +The application shall ensure that the comparison function pointed to by +.IR compar +does not alter the contents of the array. The implementation may +reorder elements of the array between calls to the comparison function, +but shall not alter the contents of any individual element. +.P +When the same objects (consisting of width bytes, irrespective of their +current positions in the array) are passed more than once to the +comparison function, the results shall be consistent with one another. +That is, they shall define a total ordering on the array. +.P +The contents of the array shall be sorted in ascending order according +to a comparison function. The +.IR compar +argument is a pointer to the comparison function, which is called with +two arguments that point to the elements being compared. The +application shall ensure that the function returns an integer less +than, equal to, or greater than 0, if the first argument is considered +respectively less than, equal to, or greater than the second. If two +members compare as equal, their order in the sorted array is +unspecified. +.SH "RETURN VALUE" +The +\fIqsort\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The comparison function need not compare every byte, so arbitrary data +may be contained in the elements in addition to the values being +compared. +.SH RATIONALE +The requirement that each argument (hereafter referred to as +.IR p) +to the comparison function is a pointer to elements of the array +implies that for every call, for each argument separately, all of the +following expressions are non-zero: +.sp +.RS 4 +.nf +\fB +((char *)p \(mi (char *)base) % width == 0 +(char *)p >= (char *)base +(char *)p < (char *)base + nel * width +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalphasort\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/raise.3p b/man-pages-posix-2013-a/man3p/raise.3p new file mode 100644 index 0000000..03a87e3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/raise.3p @@ -0,0 +1,93 @@ +'\" et +.TH RAISE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +raise +\(em send a signal to the executing process +.SH SYNOPSIS +.LP +.nf +#include +.P +int raise(int \fIsig\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIraise\fR() +function shall send the signal +.IR sig +to the executing +thread or process. +If a signal handler is called, the +\fIraise\fR() +function shall not return until after the signal handler does. +.P +The effect of the +\fIraise\fR() +function shall be equivalent to calling: +.sp +.RS 4 +.nf +\fB +pthread_kill(pthread_self(), sig); +.fi \fR +.P +.RE +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, a +non-zero value shall be returned +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIraise\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR sig +argument is an invalid signal number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The term ``thread'' is an extension to the ISO\ C standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIkill\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/rand.3p b/man-pages-posix-2013-a/man3p/rand.3p new file mode 100644 index 0000000..ca9234b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/rand.3p @@ -0,0 +1,225 @@ +'\" et +.TH RAND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rand, +rand_r, +srand +\(em pseudo-random number generator +.SH SYNOPSIS +.LP +.nf +#include +.P +int rand(void); +int rand_r(unsigned *\fIseed\fP); +void srand(unsigned \fIseed\fP); +.fi +.SH DESCRIPTION +For +\fIrand\fR() +and +\fIsrand\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIrand\fR() +function shall compute a sequence of pseudo-random integers in the +range [0,\c +{RAND_MAX}] +with a period of at least 2\u\s-332\s0\d. +.P +The +\fIrand\fR() +function need not be thread-safe. +.P +The +\fIrand_r\fR() +function shall compute a sequence of pseudo-random integers in +the range [0,\c +{RAND_MAX}]. +(The value of the +{RAND_MAX} +macro shall be at least 32\|767.) +.P +If +\fIrand_r\fR() +is called with the same initial value for the object pointed to by +.IR seed +and that object is not modified between successive returns and calls to +\fIrand_r\fR(), +the same sequence shall be generated. +.P +The +\fIsrand\fR() +function uses the argument as a seed for a new sequence of +pseudo-random numbers to be returned by subsequent calls to +\fIrand\fR(). +If +\fIsrand\fR() +is then called with the same seed value, the sequence of pseudo-random +numbers shall be repeated. If +\fIrand\fR() +is called before any calls to +\fIsrand\fR() +are made, the same sequence shall be generated as when +\fIsrand\fR() +is first called with a seed value of 1. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 +calls +\fIrand\fR() +or +\fIsrand\fR(). +.SH "RETURN VALUE" +The +\fIrand\fR() +function shall return the next pseudo-random number in the sequence. +.P +The +\fIrand_r\fR() +function shall return a pseudo-random integer. +.P +The +\fIsrand\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating a Pseudo-Random Number Sequence" +.P +The following example demonstrates how to generate a sequence of +pseudo-random numbers. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... + long count, i; + char *keystr; + int elementlen, len; + char c; +\&... +/* Initial random number generator. */ + srand(1); +.P + /* Create keys using only lowercase characters */ + len = 0; + for (i=0; i\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/random.3p b/man-pages-posix-2013-a/man3p/random.3p new file mode 100644 index 0000000..3dfd9ca --- /dev/null +++ b/man-pages-posix-2013-a/man3p/random.3p @@ -0,0 +1,38 @@ +'\" et +.TH RANDOM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +random +\(em generate pseudo-random number +.SH SYNOPSIS +.LP +.nf +#include +.P +long random(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIinitstate\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/read.3p b/man-pages-posix-2013-a/man3p/read.3p new file mode 100644 index 0000000..d411ce5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/read.3p @@ -0,0 +1,626 @@ +'\" et +.TH READ "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pread, +read +\(em read from a file +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t pread(int \fIfildes\fP, void *\fIbuf\fP, size_t \fInbyte\fP, off_t \fIoffset\fR); +ssize_t read(int \fIfildes\fP, void *\fIbuf\fP, size_t \fInbyte\fP); +.fi +.SH DESCRIPTION +The +\fIread\fR() +function shall attempt to read +.IR nbyte +bytes from the file associated with the open file descriptor, +.IR fildes , +into the buffer pointed to by +.IR buf . +The behavior of multiple concurrent reads on the same pipe, FIFO, or +terminal device is unspecified. +.P +Before any action described below is taken, and if +.IR nbyte +is zero, the +\fIread\fR() +function may detect and return errors as described below. In the +absence of errors, or if error detection is not performed, the +\fIread\fR() +function shall return zero and have no other results. +.P +On files that support seeking (for example, a regular file), the +\fIread\fR() +shall start at a position in the file given by the file offset +associated with +.IR fildes . +The file offset shall be incremented by the number of bytes +actually read. +.P +Files that do not support seeking\(emfor example, terminals\(emalways +read from the current position. The value of a file offset associated +with such a file is undefined. +.P +No data transfer shall occur past the current end-of-file. If the +starting position is at or after the end-of-file, 0 shall be returned. +If the file refers to a device special file, the result of subsequent +\fIread\fR() +requests is implementation-defined. +.P +If the value of +.IR nbyte +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +When attempting to read from an empty pipe or FIFO: +.IP " *" 4 +If no process has the pipe open for writing, +\fIread\fR() +shall return 0 to indicate end-of-file. +.IP " *" 4 +If some process has the pipe open for writing and O_NONBLOCK is set, +\fIread\fR() +shall return \(mi1 and set +.IR errno +to +.BR [EAGAIN] . +.IP " *" 4 +If some process has the pipe open for writing and O_NONBLOCK is clear, +\fIread\fR() +shall block the calling thread until some data is written or the pipe +is closed by all processes that had the pipe open for writing. +.P +When attempting to read a file (other than a pipe or FIFO) that +supports non-blocking reads and has no data currently available: +.IP " *" 4 +If O_NONBLOCK is set, +\fIread\fR() +shall return \(mi1 and set +.IR errno +to +.BR [EAGAIN] . +.IP " *" 4 +If O_NONBLOCK is clear, +\fIread\fR() +shall block the calling thread until some data becomes available. +.IP " *" 4 +The use of the O_NONBLOCK flag has no effect if there is some data +available. +.P +The +\fIread\fR() +function reads data previously written to a file. If any portion of a +regular file prior to the end-of-file has not been written, +\fIread\fR() +shall return bytes with value 0. For example, +\fIlseek\fR() +allows the file offset to be set beyond the end of existing data in the +file. If data is later written at this point, subsequent reads in the +gap between the previous end of data and the newly written data shall +return bytes with value 0 until data is written into the gap. +.P +Upon successful completion, where +.IR nbyte +is greater than 0, +\fIread\fR() +shall mark for update the last data access timestamp +of the file, and shall return the number of bytes read. +This number shall never be greater than +.IR nbyte . +The value returned may be less than +.IR nbyte +if the number of bytes left in the file is less than +.IR nbyte , +if the +\fIread\fR() +request was interrupted by a signal, or if the file is a pipe or FIFO +or special file and has fewer than +.IR nbyte +bytes immediately available for reading. For example, a +\fIread\fR() +from a file associated with a terminal may return one typed line of +data. +.P +If a +\fIread\fR() +is interrupted by a signal before it reads any data, it shall return +\(mi1 with +.IR errno +set to +.BR [EINTR] . +.P +If a +\fIread\fR() +is interrupted by a signal after it has successfully read some data, it +shall return the number of bytes read. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +.IR fildes . +.P +If +.IR fildes +refers to a socket, +\fIread\fR() +shall be equivalent to +\fIrecv\fR() +with no flags set. +.P +If the O_DSYNC and O_RSYNC bits have been set, +read I/O operations on the file descriptor shall complete as defined by +synchronized I/O data integrity completion. If the O_SYNC and O_RSYNC +bits have been set, read I/O operations on the file descriptor shall +complete as defined by synchronized I/O file integrity completion. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIread\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIread\fR() +function is unspecified. +.P +A +\fIread\fR() +from a STREAMS file can read data in three different modes: +\fIbyte-stream\fP mode, \fImessage-nondiscard\fP mode, and +\fImessage-discard\fP mode. The default shall be byte-stream mode. +This can be changed using the I_SRDOPT +\fIioctl\fR() +request, and can be tested with I_GRDOPT +\fIioctl\fR(). +In byte-stream mode, +\fIread\fR() +shall retrieve data from the STREAM until as many bytes as were +requested are +transferred, or until there is no more data to be retrieved. +Byte-stream mode ignores message boundaries. +.P +In STREAMS message-nondiscard mode, +\fIread\fR() +shall retrieve data until as many bytes as were requested are +transferred, or until a message boundary is reached. If +\fIread\fR() +does not retrieve all the data in a message, the remaining data shall +be left on the STREAM, and can be retrieved by the next +\fIread\fR() +call. Message-discard mode also retrieves data until as many bytes as +were requested are transferred, or a message boundary is reached. +However, unread data remaining in a message after the +\fIread\fR() +returns shall be discarded, and shall not be available for a subsequent +\fIread\fR(), +\fIgetmsg\fR(), +or +\fIgetpmsg\fR() +call. +.P +How +\fIread\fR() +handles zero-byte STREAMS messages is determined by the current read +mode setting. In byte-stream mode, +\fIread\fR() +shall accept data until it has read +.IR nbyte +bytes, or until there is no more data to read, or until a zero-byte +message block is encountered. The +\fIread\fR() +function shall then return the number of bytes read, and place the +zero-byte message back on the STREAM to be retrieved by the next +\fIread\fR(), +\fIgetmsg\fR(), +or +\fIgetpmsg\fR(). +In message-nondiscard mode or message-discard mode, a zero-byte message +shall return 0 and the message shall be removed from the STREAM. When a +zero-byte message is read as the first message on a STREAM, the message +shall be removed from the STREAM and 0 shall be returned, regardless of +the read mode. +.P +A +\fIread\fR() +from a STREAMS file shall return the data in the message at the front +of the STREAM head read queue, regardless of the priority band of the +message. +.P +By default, STREAMs are in control-normal mode, in which a +\fIread\fR() +from a STREAMS file can only process messages that contain a data part +but do not contain a control part. The +\fIread\fR() +shall fail if a message containing a control part is encountered at the +STREAM head. This default action can be changed by placing the STREAM +in either control-data mode or control-discard mode with the I_SRDOPT +\fIioctl\fR() +command. In control-data mode, +\fIread\fR() +shall convert any control part to data and pass it to the application +before passing any data part originally present in the same message. +In control-discard mode, +\fIread\fR() +shall discard message control parts but return to the process any data +part in the message. +.P +In addition, +\fIread\fR() +shall fail if the STREAM head had processed an asynchronous error +before the call. In this case, the value of +.IR errno +shall not reflect the result of +\fIread\fR(), +but reflect the prior error. If a hangup occurs on the STREAM being +read, +\fIread\fR() +shall continue to operate normally until the STREAM head read queue is +empty. Thereafter, it shall return 0. +.P +The +\fIpread\fR() +function shall be equivalent to +\fIread\fR(), +except that it shall read from a given position in the file without +changing the file pointer. The first three arguments to +\fIpread\fR() +are the same as +\fIread\fR() +with the addition of a fourth argument +.IR offset +for the desired position inside the file. An attempt to perform a +\fIpread\fR() +on a file that is incapable of seeking shall result in an error. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a non-negative +integer indicating the number of bytes actually read. Otherwise, the +functions shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EAGAIN +The file is neither a pipe, nor a FIFO, nor a socket, the O_NONBLOCK +flag is set for the file descriptor, and the thread would be delayed +in the read operation. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor open for reading. +.TP +.BR EBADMSG +The file is a STREAM file that is set to control-normal mode and the +message waiting to be read includes a control part. +.TP +.BR EINTR +The read operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EINVAL +The STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.TP +.BR EIO +The process is a member of a background process group attempting to read +from its controlling terminal, and either the calling thread is blocking +SIGTTIN or the process is ignoring SIGTTIN or the process group of the +process is orphaned. This error may also be generated for +implementation-defined reasons. +.TP +.BR EISDIR +The +.IR fildes +argument refers to a directory and the implementation +does not allow the directory to be read using +\fIread\fR() +or +\fIpread\fR(). +The +\fIreaddir\fR() +function should be used instead. +.TP +.BR EOVERFLOW +The file is a regular file, +.IR nbyte +is greater than 0, the starting position is before the end-of-file, and +the starting position is greater than or equal to the offset maximum +established in the open file description associated with +.IR fildes . +.P +The +\fIpread\fR() +function shall fail if: +.TP +.BR EINVAL +The file is a regular file or block special file, and the +.IR offset +argument is negative. The file pointer shall remain unchanged. +.TP +.BR ESPIPE +The file is a pipe, FIFO, or socket. +.br +.P +The +\fIread\fR() +function shall fail if: +.TP +.BR EAGAIN +The file is a pipe or FIFO, the O_NONBLOCK flag is set for the file +descriptor, and the thread would be delayed in the read operation. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The file is a socket, the O_NONBLOCK flag is set for the file +descriptor, and the thread would be delayed in the read operation. +.TP +.BR ECONNRESET +A read was attempted on a socket and the connection was forcibly closed +by its peer. +.TP +.BR ENOTCONN +A read was attempted on a socket that is not connected. +.TP +.BR ETIMEDOUT +A read was attempted on a socket and a transmission timeout occurred. +.P +These functions may fail if: +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading Data into a Buffer" +.P +The following example reads data from the file associated with the file +descriptor +.IR fd +into the buffer pointed to by +.IR buf . +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +char buf[20]; +size_t nbytes; +ssize_t bytes_read; +int fd; +\&... +nbytes = sizeof(buf); +bytes_read = read(fd, buf, nbytes); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +This volume of POSIX.1\(hy2008 does not specify the value of the file offset after an +error is returned; there are too many cases. For programming errors, +such as +.BR [EBADF] , +the concept is meaningless since no file is involved. For errors that +are detected immediately, such as +.BR [EAGAIN] , +clearly the pointer should not change. After an interrupt or hardware +error, however, an updated value would be very useful and is the +behavior of many implementations. +.P +Note that a +\fIread\fR() +of zero bytes does not modify the last data access timestamp. A +\fIread\fR() +that requests more than zero bytes, but returns zero, is required +to modify the last data access timestamp. +.P +Implementations are allowed, but not required, to perform error +checking for +\fIread\fR() +requests of zero bytes. +.SS "Input and Output" +.P +The use of I/O with large byte counts has always presented problems. +Ideas such as +\fIlread\fR() +and +\fIlwrite\fR() +(using and returning +.BR long s) +were considered at one time. The current solution is to use abstract +types on the ISO\ C standard function to +\fIread\fR() +and +\fIwrite\fR(). +The abstract types can be declared so that existing functions work, but +can also be declared so that larger types can be represented in future +implementations. It is presumed that whatever constraints limit the +maximum range of +.BR size_t +also limit portable I/O requests to the same range. This volume of POSIX.1\(hy2008 also limits +the range further by requiring that the byte count be limited so that a +signed return value remains meaningful. Since the return type is also a +(signed) abstract type, the byte count can be defined by the +implementation to be larger than an +.BR int +can hold. +.P +The standard developers considered adding atomicity requirements to a +pipe or FIFO, but recognized that due to the nature of pipes and FIFOs +there could be no guarantee of atomicity of reads of +{PIPE_BUF} +or any other size that would be an aid to applications portability. +.P +This volume of POSIX.1\(hy2008 requires that no action be taken for +\fIread\fR() +or +\fIwrite\fR() +when +.IR nbyte +is zero. This is not intended to take precedence over detection of +errors (such as invalid buffer pointers or file descriptors). This is +consistent with the rest of this volume of POSIX.1\(hy2008, but the phrasing here could be +misread to require detection of the zero case before any other errors. +A value of zero is to be considered a correct value, for which the +semantics are a no-op. +.P +I/O is intended to be atomic to ordinary files and pipes and FIFOs. +Atomic means that all the bytes from a single operation that +started out together end up together, without interleaving from other +I/O operations. It is a known attribute of terminals that this is not +honored, and terminals are explicitly (and implicitly permanently) +excepted, making the behavior unspecified. The behavior for other +device types is also left unspecified, but the wording is intended to +imply that future standards might choose to specify atomicity (or not). +.P +There were recommendations to add format parameters to +\fIread\fR() +and +\fIwrite\fR() +in order to handle networked transfers among heterogeneous file system +and base hardware types. Such a facility may be required for support by +the OSI presentation of layer services. However, it was determined that +this should correspond with similar C-language facilities, and that is +beyond the scope of this volume of POSIX.1\(hy2008. The concept was suggested to the developers +of the ISO\ C standard for their consideration as a possible area for future +work. +.P +In 4.3 BSD, a +\fIread\fR() +or +\fIwrite\fR() +that is interrupted by a signal before transferring any data does not +by default return an +.BR [EINTR] +error, but is restarted. In 4.2 BSD, +4.3 BSD, +and the Eighth Edition, there is an additional function, +\fIselect\fR(), +whose purpose is to pause until specified activity (data to read, space +to write, and so on) is detected on specified file descriptors. It is +common in applications written for those systems for +\fIselect\fR() +to be used before +\fIread\fR() +in situations (such as keyboard input) where interruption of I/O due to +a signal is desired. +.P +The issue of which files or file types are interruptible is considered +an implementation design issue. This is often affected primarily by +hardware and reliability issues. +.P +There are no references to actions taken following an ``unrecoverable +error''. It is considered beyond the scope of this volume of POSIX.1\(hy2008 to describe what +happens in the case of hardware errors. +.P +Earlier versions of this standard allowed two very different behaviors +with regard to the handling of interrupts. In order to minimize the +resulting confusion, it was decided that POSIX.1\(hy2008 should support only one +of these behaviors. Historical practice on AT&T-derived systems was to +have +\fIread\fR() +and +\fIwrite\fR() +return \(mi1 and set +.IR errno +to +.BR [EINTR] +when interrupted after some, but not all, of the data requested had +been transferred. However, the US Department of Commerce FIPS 151\(hy1 and +FIPS 151\(hy2 require the historical BSD behavior, in which +\fIread\fR() +and +\fIwrite\fR() +return the number of bytes actually transferred before the interrupt. +If \(mi1 is returned when any data is transferred, it is difficult to +recover from the error on a seekable device and impossible on a +non-seekable device. Most new implementations support this behavior. +The behavior required by POSIX.1\(hy2008 is to return the number of bytes +transferred. +.P +POSIX.1\(hy2008 does not specify when an implementation that buffers +\fIread\fR()s +actually moves the data into the user-supplied buffer, so an +implementation may choose to do this at the latest possible moment. +Therefore, an interrupt arriving earlier may not cause +\fIread\fR() +to return a partial byte count, but rather to return \(mi1 and set +.IR errno +to +.BR [EINTR] . +.P +Consideration was also given to combining the two previous options, and +setting +.IR errno +to +.BR [EINTR] +while returning a short count. However, not only is there no existing +practice that implements this, it is also contradictory to the idea +that when +.IR errno +is set, the function responsible shall return \(mi1. +.P +This volume of POSIX.1\(hy2008 intentionally does not specify any +\fIpread\fR() +errors related to pipes, FIFOs, and sockets other than +.BR [ESPIPE] . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIreadv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/readdir.3p b/man-pages-posix-2013-a/man3p/readdir.3p new file mode 100644 index 0000000..4456a2a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/readdir.3p @@ -0,0 +1,373 @@ +'\" et +.TH READDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +readdir, +readdir_r +\(em read a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +struct dirent *readdir(DIR *\fIdirp\fP); +int readdir_r(DIR *restrict \fIdirp\fP, struct dirent *restrict \fIentry\fP, + struct dirent **restrict \fIresult\fP); +.fi +.SH DESCRIPTION +The type +.BR DIR , +which is defined in the +.IR +header, represents a +.IR "directory stream" , +which is an ordered sequence of all the directory entries in a +particular directory. Directory entries represent files; files may be +removed from a directory or added to a directory asynchronously to the +operation of +\fIreaddir\fR(). +.P +The +\fIreaddir\fR() +function shall return a pointer to a structure representing the +directory entry at the current position in the directory stream +specified by the argument +.IR dirp , +and position the directory stream at the next entry. It shall return a +null pointer upon reaching the end of the directory stream. The +structure +.BR dirent +defined in the +.IR +header describes a directory entry. The value of the structure's +.IR d_ino +member shall be set to the file serial number of the file named by the +.IR d_name +member. If the +.IR d_name +member names a symbolic link, the value of the +.IR d_ino +member shall be set to the file serial number of the symbolic link itself. +.P +The +\fIreaddir\fR() +function shall not return directory entries containing empty names. If +entries for dot or dot-dot exist, one entry shall be returned for dot +and one entry shall be returned for dot-dot; otherwise, they shall not +be returned. +.P +The application shall not modify the structure to which the return +value of +\fIreaddir\fR() +points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIreaddir\fR() +on the same directory stream. They shall not be affected by a call to +\fIreaddir\fR() +on a different directory stream. +.P +If a file is removed from or added to the directory after the most +recent call to +\fIopendir\fR() +or +\fIrewinddir\fR(), +whether a subsequent call to +\fIreaddir\fR() +returns an entry for that file is unspecified. +.P +The +\fIreaddir\fR() +function may buffer several directory entries per actual read +operation; +\fIreaddir\fR() +shall mark for update the last data access timestamp +of the directory each time the directory is actually read. +.P +After a call to +\fIfork\fR(), +either the parent or child (but not both) may continue processing the +directory stream using +\fIreaddir\fR(), +\fIrewinddir\fR(), +or +\fIseekdir\fR(). +If both the parent and child processes use these functions, the result +is undefined. +.P +The +\fIreaddir\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIreaddir\fR(). +If +.IR errno +is set to non-zero on return, an error occurred. +.P +The +\fIreaddir_r\fR() +function shall initialize the +.BR dirent +structure referenced by +.IR entry +to represent the directory entry at the current position in the +directory stream referred to by +.IR dirp , +store a pointer to this structure at the location referenced by +.IR result , +and position the directory stream at the next entry. +.P +The storage pointed to by +.IR entry +shall be large enough for a +.BR dirent +with an array of +.BR char +.IR d_name +members containing at least +{NAME_MAX}+1 +elements. +.P +Upon successful return, the pointer returned at *\fIresult\fP shall have +the same value as the argument +.IR entry . +Upon reaching the end of the directory stream, this pointer shall +have the value NULL. +.P +The +\fIreaddir_r\fR() +function shall not return directory entries containing empty names. +.P +If a file is removed from or added to the directory after the most +recent call to +\fIopendir\fR() +or +\fIrewinddir\fR(), +whether a subsequent call to +\fIreaddir_r\fR() +returns an entry for that file is unspecified. +.P +The +\fIreaddir_r\fR() +function may buffer several directory entries per actual read +operation; +\fIreaddir_r\fR() +shall mark for update the last data access timestamp of the directory +each time the directory is actually read. +.SH "RETURN VALUE" +Upon successful completion, +\fIreaddir\fR() +shall return a pointer to an object of type +.BR "struct dirent" . +When an error is encountered, a null pointer shall be returned and +.IR errno +shall be set to indicate the error. When the end of the directory is +encountered, a null pointer shall be returned and +.IR errno +is not changed. +.P +If successful, the +\fIreaddir_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EOVERFLOW +One of the values in the structure to be returned cannot be represented +correctly. +.P +These functions may fail if: +.TP +.BR EBADF +The +.IR dirp +argument does not refer to an open directory stream. +.TP +.BR ENOENT +The current position of the directory stream is invalid. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following sample program searches the current directory for +each of the arguments supplied on the command line. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +.P +static void lookup(const char *arg) +{ + DIR *dirp; + struct dirent *dp; +.P + if ((dirp = opendir(".")) == NULL) { + perror("couldn't open '.'"); + return; + } +.P + do { + errno = 0; + if ((dp = readdir(dirp)) != NULL) { + if (strcmp(dp->d_name, arg) != 0) + continue; +.P + (void) printf("found %s\en", arg); + (void) closedir(dirp); + return; +.P + } + } while (dp != NULL); +.P + if (errno != 0) + perror("error reading directory"); + else + (void) printf("failed to find %s\en", arg); + (void) closedir(dirp); + return; +} +.P +int main(int argc, char *argv[]) +{ + int i; + for (i = 1; i < argc; i++) + lookup(argv[i]); + return (0); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIreaddir\fR() +function should be used in conjunction with +\fIopendir\fR(), +\fIclosedir\fR(), +and +\fIrewinddir\fR() +to examine the contents of the directory. +.P +The +\fIreaddir_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.SH RATIONALE +The returned value of +\fIreaddir\fR() +merely \fIrepresents\fP a directory entry. No equivalence should be +inferred. +.P +Historical implementations of +\fIreaddir\fR() +obtain multiple directory entries on a single read operation, which +permits subsequent +\fIreaddir\fR() +operations to operate from the buffered information. Any wording that +required each successful +\fIreaddir\fR() +operation to mark the directory last data access timestamp +for update would disallow such historical performance-oriented +implementations. +.P +When returning a directory entry for the root of a mounted file system, +some historical implementations of +\fIreaddir\fR() +returned the file serial number of the underlying mount point, rather +than of the root of the mounted file system. This behavior is considered +to be a bug, since the underlying file serial number has no significance +to applications. +.P +Since +\fIreaddir\fR() +returns NULL +when it detects an error and when the end of the directory is +encountered, an application that needs to tell the difference must set +.IR errno +to zero before the call and check it if NULL is returned. +Since the function must not change +.IR errno +in the second case and must set it to a non-zero value in the first +case, a zero +.IR errno +after a call returning NULL indicates end-of-directory; otherwise, an +error. +.P +Routines to deal with this problem more directly were proposed: +.sp +.RS 4 +.nf +\fB +int derror (\fIdirp\fP) +DIR *\fIdirp\fP; +.P +void clearderr (\fIdirp\fP) +DIR *\fIdirp\fP; +.fi \fR +.P +.RE +.P +The first would indicate whether an error had occurred, and the second +would clear the error indication. The simpler method involving +.IR errno +was adopted instead by requiring that +\fIreaddir\fR() +not change +.IR errno +when end-of-directory is encountered. +.P +An error or signal indicating that a directory has changed while open +was considered but rejected. +.P +The thread-safe version of the directory reading function returns +values in a user-supplied buffer instead of possibly using a static +data area that may be overwritten by each call. Either the +{NAME_MAX} +compile-time constant or the corresponding +\fIpathconf\fR() +option can be used to determine the maximum sizes of returned +pathnames. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIrewinddir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/readlink.3p b/man-pages-posix-2013-a/man3p/readlink.3p new file mode 100644 index 0000000..6bdf98f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/readlink.3p @@ -0,0 +1,255 @@ +'\" et +.TH READLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +readlink, readlinkat +\(em read the contents of a symbolic link +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t readlink(const char *restrict \fIpath\fP, char *restrict \fIbuf\fP, + size_t \fIbufsize\fP); +ssize_t readlinkat(int \fIfd\fP, const char *restrict \fIpath\fP, + char *restrict \fIbuf\fP, size_t \fIbufsize\fP); +.fi +.SH DESCRIPTION +The +\fIreadlink\fR() +function shall place the contents of the symbolic link referred to by +.IR path +in the buffer +.IR buf +which has size +.IR bufsize . +If the number of bytes in the symbolic link is less than +.IR bufsize , +the contents of the remainder of +.IR buf +are unspecified. If the +.IR buf +argument is not large enough to contain the link content, the first +.IR bufsize +bytes shall be placed in +.IR buf . +.P +If the value of +.IR bufsize +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +Upon successful completion, +\fIreadlink\fR() +shall mark for update the last data access timestamp of the symbolic +link. +.P +The +\fIreadlinkat\fR() +function shall be equivalent to the +\fIreadlink\fR() +function except in the case where +.IR path +specifies a relative path. In this case the symbolic link whose content +is read is relative to the directory associated with the file +descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +If +\fIreadlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIreadlink\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the count of +bytes placed in the buffer. Otherwise, these functions shall return a +value of \(mi1, leave the buffer unchanged, and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix of +.IR path . +.TP +.BR EINVAL +The +.IR path +argument names a file that is not a symbolic link. +.TP +.BR EIO +An I/O error occurred while reading from the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIreadlinkat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading the Name of a Symbolic Link" +.P +The following example shows how to read the name of a symbolic link +named +.BR /modules/pass1 . +.sp +.RS 4 +.nf +\fB +#include +.P +char buf[1024]; +ssize_t len; +\&... +if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1) + buf[len] = '\e0'; +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Conforming applications should not assume that the returned contents of +the symbolic link are null-terminated. +.SH RATIONALE +The type associated with +.IR bufsiz +is a +.BR size_t +in order to be consistent with both the ISO\ C standard and the definition of +\fIread\fR(). +The behavior specified for +\fIreadlink\fR() +when +.IR bufsiz +is zero represents historical practice. For this case, the standard +developers considered a change whereby +\fIreadlink\fR() +would return the number of non-null bytes contained in the symbolic +link with the buffer +.IR buf +remaining unchanged; however, since the +.BR stat +structure member +.IR st_size +value can be used to determine the size of buffer necessary to contain +the contents of the symbolic link as returned by +\fIreadlink\fR(), +this proposal was rejected, and the historical practice retained. +.P +The purpose of the +\fIreadlinkat\fR() +function is to read the content of symbolic links in directories other +than the current working directory without exposure to race conditions. +Any part of the path of a file could be changed in parallel to a call +to +\fIreadlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIreadlinkat\fR() +function it can be guaranteed that the symbolic link read is located +relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/readv.3p b/man-pages-posix-2013-a/man3p/readv.3p new file mode 100644 index 0000000..a700b02 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/readv.3p @@ -0,0 +1,150 @@ +'\" et +.TH READV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +readv +\(em read a vector +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t readv(int \fIfildes\fP, const struct iovec *\fIiov\fP, int \fIiovcnt\fP); +.fi +.SH DESCRIPTION +The +\fIreadv\fR() +function shall be equivalent to +\fIread\fR(), +except as described below. The +\fIreadv\fR() +function shall place the input data into the +.IR iovcnt +buffers specified by the members of the +.IR iov +array: +.IR iov [0], +.IR iov [1], +\&.\|.\|., +.IR iov [\c +.IR iovcnt \(mi1]. +The +.IR iovcnt +argument is valid if greater than 0 and less than or equal to +{IOV_MAX}. +.P +Each +.IR iovec +entry specifies the base address and length of an area +in memory where data should be placed. The +\fIreadv\fR() +function shall always fill an area completely before proceeding +to the next. +.P +Upon successful completion, +\fIreadv\fR() +shall mark for update the last data access timestamp of the file. +.SH "RETURN VALUE" +Refer to +.IR "\fIread\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIread\fR\^(\|)". +.P +In addition, the +\fIreadv\fR() +function shall fail if: +.TP +.BR EINVAL +The sum of the +.IR iov_len +values in the +.IR iov +array overflowed an +.BR ssize_t . +.P +The +\fIreadv\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR iovcnt +argument was less than or equal to 0, or greater than +{IOV_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading Data into an Array" +.P +The following example reads data from the file associated with the file +descriptor +.IR fd +into the buffers specified by members of the +.IR iov +array. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +ssize_t bytes_read; +int fd; +char buf0[20]; +char buf1[30]; +char buf2[40]; +int iovcnt; +struct iovec iov[3]; +.P +iov[0].iov_base = buf0; +iov[0].iov_len = sizeof(buf0); +iov[1].iov_base = buf1; +iov[1].iov_len = sizeof(buf1); +iov[2].iov_base = buf2; +iov[2].iov_len = sizeof(buf2); +\&... +iovcnt = sizeof(iov) / sizeof(struct iovec); +.P +bytes_read = readv(fd, iov, iovcnt); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIread\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIread\fR\^(\|)", +.IR "\fIwritev\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/realloc.3p b/man-pages-posix-2013-a/man3p/realloc.3p new file mode 100644 index 0000000..2eedf89 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/realloc.3p @@ -0,0 +1,176 @@ +'\" et +.TH REALLOC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +realloc +\(em memory reallocator +.SH SYNOPSIS +.LP +.nf +#include +.P +void *realloc(void *\fIptr\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIrealloc\fR() +function shall deallocate the old object pointed to by +.IR ptr +and return a pointer to a new object that has the size specified by +.IR size . +The contents of the new object shall be the same as that of the old +object prior to deallocation, up to the lesser of the new and old +sizes. Any bytes in the new object beyond the size of the old object +have indeterminate values. If the size of the space requested is zero, +the behavior shall be implementation-defined: either a null pointer is +returned, or the behavior shall be as if the size were some non-zero +value, except that the returned pointer shall not be used to access +an object. If the space cannot be allocated, the object shall remain +unchanged. +.P +If +.IR ptr +is a null pointer, +\fIrealloc\fR() +shall be equivalent to +\fImalloc\fR() +for the specified size. +.P +If +.IR ptr +does not match a pointer returned earlier by +\fIcalloc\fR(), +\fImalloc\fR(), +or +\fIrealloc\fR() +or if the space has previously been deallocated by a call to +\fIfree\fR() +or +\fIrealloc\fR(), +the behavior is undefined. +.P +The order and contiguity of storage allocated by successive calls to +\fIrealloc\fR() +is unspecified. The pointer returned if the allocation succeeds shall +be suitably aligned so that it may be assigned to a pointer to any type +of object and then used to access such an object in the space allocated +(until the space is explicitly freed or reallocated). Each such +allocation shall yield a pointer to an object disjoint from any other +object. The pointer returned shall point to the start (lowest byte +address) of the allocated space. If the space cannot be allocated, a +null pointer shall be returned. +.SH "RETURN VALUE" +Upon successful completion, +\fIrealloc\fR() +shall return a pointer to the (possibly moved) allocated space. If +.IR size +is 0, either: +.IP " *" 4 +A null pointer shall be returned +and +.IR errno +set to an implementation-defined value. +.IP " *" 4 +A unique pointer that can be successfully passed to +\fIfree\fR() +shall be returned, and the memory object pointed to by +.IR ptr +shall be freed. The application shall ensure that the pointer is not +used to access an object. +.P +If there is not enough available memory, +\fIrealloc\fR() +shall return a null pointer +and set +.IR errno +to +.BR [ENOMEM] . +If +\fIrealloc\fR() +returns a null pointer +and +.IR errno +has been set to +.BR [ENOMEM] , +the memory referenced by +.IR ptr +shall not be changed. +.SH ERRORS +The +\fIrealloc\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The description of +\fIrealloc\fR() +has been modified from previous versions of this standard to align +with the ISO/IEC\ 9899:\|1999 standard. Previous versions explicitly permitted a call to +.IR realloc \c +(\fIp\fI, 0) to free the space pointed to by +.IR p +and return a null pointer. While this behavior could be interpreted as +permitted by this version of the standard, the C language committee have +indicated that this interpretation is incorrect. Applications should +assume that if +\fIrealloc\fR() +returns a null pointer, the space pointed to by +.IR p +has not been freed. Since this could lead to double-frees, implementations +should also set +.IR errno +if a null pointer actually indicates a failure, and applications should +only free the space if +.IR errno +was changed. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +This standard defers to the ISO\ C standard. While that standard currently has +language that might permit +.IR realloc \c +(\fIp\fI, 0), where +.IR p +is not a null pointer, to free +.IR p +while still returning a null pointer, the committee responsible for that +standard is considering clarifying the language to explicitly prohibit +that alternative. +.SH "SEE ALSO" +.IR "\fIcalloc\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/realpath.3p b/man-pages-posix-2013-a/man3p/realpath.3p new file mode 100644 index 0000000..6a0c902 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/realpath.3p @@ -0,0 +1,254 @@ +'\" et +.TH REALPATH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +realpath +\(em resolve a pathname +.SH SYNOPSIS +.LP +.nf +#include +.P +char *realpath(const char *restrict \fIfile_name\fP, + char *restrict \fIresolved_name\fP); +.fi +.SH DESCRIPTION +The +\fIrealpath\fR() +function shall derive, from the pathname pointed to by +.IR file_name , +an absolute pathname that resolves to the same directory entry, whose +resolution does not involve +.BR '.' , +.BR '..' , +or symbolic links. If +.IR resolved_name +is a null pointer, the generated pathname shall be stored as a +null-terminated string in a buffer allocated as if by a call to +\fImalloc\fR(). +Otherwise, if +{PATH_MAX} +is defined as a constant in the +.IR +header, then the generated pathname shall be stored as a null-terminated +string, up to a maximum of +{PATH_MAX} +bytes, in the buffer pointed to by +.IR resolved_name . +.P +If +.IR resolved_name +is not a null pointer and +{PATH_MAX} +is not defined as a constant in the +.IR +header, the behavior is undefined. +.SH "RETURN VALUE" +Upon successful completion, +\fIrealpath\fR() +shall return a pointer to the buffer containing the resolved name. +Otherwise, +\fIrealpath\fR() +shall return a null pointer and set +.IR errno +to indicate the error. +.P +If the +.IR resolved_name +argument is a null pointer, the pointer returned by +\fIrealpath\fR() +can be passed to +\fIfree\fR(). +.P +If the +.IR resolved_name +argument is not a null pointer and the +\fIrealpath\fR() +function fails, the contents of the buffer pointed to by +.IR resolved_name +are undefined. +.SH ERRORS +The +\fIrealpath\fR() +function shall fail if: +.TP +.BR EACCES +Search permission was denied for a component of the path prefix of +.IR file_name . +.TP +.BR EINVAL +The +.IR file_name +argument is a null pointer. +.TP +.BR EIO +An error occurred while reading from the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR file_name +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR file_name +does not name an existing file or +.IR file_name +points to an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR file_name +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIrealpath\fR() +function may fail if: +.TP +.BR EACCES +The +.IR file_name +argument does not begin with a + +and none of the symbolic links (if any) processed during pathname +resolution of +.IR file_name +had contents that began with a +, +and either search permission was denied for the current directory or +read or search permission was denied for a directory above the current +directory in the file hierarchy. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR file_name +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating an Absolute Pathname" +.P +The following example generates an absolute pathname for the file +identified by the +.IR symlinkpath +argument. The generated pathname is stored in the buffer pointed to by +.IR actualpath . +.sp +.RS 4 +.nf +\fB +#include +\&... +char *symlinkpath = "/tmp/symlink/file"; +char *actualpath; +.P +actualpath = realpath(symlinkpath, NULL); +if (actualpath != NULL) +{ + ... use actualpath ... +.P + free(actualpath); +} +else +{ + ... handle error ... +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIrealpath\fR(), +this is the return value. +.SH RATIONALE +Since +\fIrealpath\fR() +has no +.IR length +argument, if +{PATH_MAX} +is not defined as a constant in +.IR , +applications have no way of determining how large a buffer they need +to allocate for it to be safe to pass to +\fIrealpath\fR(). +A +{PATH_MAX} +value obtained from a prior +\fIpathconf\fR() +call is out-of-date by the time +\fIrealpath\fR() +is called. Hence the only reliable way to use +\fIrealpath\fR() +when +{PATH_MAX} +is not defined in +.IR +is to pass a null pointer for +.IR resolved_name +so that +\fIrealpath\fR() +will allocate a buffer of the necessary size. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fIgetcwd\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/recv.3p b/man-pages-posix-2013-a/man3p/recv.3p new file mode 100644 index 0000000..9ec4726 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/recv.3p @@ -0,0 +1,220 @@ +'\" et +.TH RECV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +recv +\(em receive a message from a connected socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t recv(int \fIsocket\fP, void *\fIbuffer\fP, size_t \fIlength\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIrecv\fR() +function shall receive a message from a connection-mode or +connectionless-mode socket. It is normally used with connected sockets +because it does not permit the application to retrieve the source +address of received data. +.P +The +\fIrecv\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 10 +Specifies the socket file descriptor. +.IP "\fIbuffer\fR" 10 +Points to a buffer where the message should be stored. +.IP "\fIlength\fR" 10 +Specifies the length in bytes of the buffer pointed to by the +.IR buffer +argument. +.IP "\fIflags\fR" 10 +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following values: +.RS 10 +.IP MSG_PEEK 12 +Peeks at an incoming message. The data is treated as unread and the +next +\fIrecv\fR() +or similar function shall still return this data. +.IP MSG_OOB 12 +Requests out-of-band data. The significance and semantics of +out-of-band data are protocol-specific. +.IP MSG_WAITALL 12 +On SOCK_STREAM sockets this requests that the function block until the +full amount of data can be returned. The function may return the +smaller amount of data if the socket is a message-based socket, if a +signal is caught, if the connection is terminated, if MSG_PEEK was +specified, or if an error is pending for the socket. +.RE +.P +The +\fIrecv\fR() +function shall return the length of the message written to the buffer +pointed to by the +.IR buffer +argument. For message-based sockets, such as SOCK_DGRAM and +SOCK_SEQPACKET, the entire message shall be read in a single operation. +If a message is too long to fit in the supplied buffer, and MSG_PEEK is +not set in the +.IR flags +argument, the excess bytes shall be discarded. For stream-based +sockets, such as SOCK_STREAM, message boundaries shall be ignored. In +this case, data shall be returned to the user as soon as it becomes +available, and no data shall be discarded. +.P +If the MSG_WAITALL flag is not set, data shall be returned only up to +the end of the first message. +.P +If no messages are available at the socket and O_NONBLOCK is not set on +the socket's file descriptor, +\fIrecv\fR() +shall block until a message arrives. If no messages are available at +the socket and O_NONBLOCK is set on the socket's file descriptor, +\fIrecv\fR() +shall fail and set +.IR errno +to +.BR [EAGAIN] +or +.BR [EWOULDBLOCK] . +.SH "RETURN VALUE" +Upon successful completion, +\fIrecv\fR() +shall return the length of the message in bytes. If no messages are +available to be received and the peer has performed an orderly +shutdown, +\fIrecv\fR() +shall return 0. Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIrecv\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and no data is +waiting to be received; or MSG_OOB is set and no out-of-band data is +available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await out-of-band data. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +The +\fIrecv\fR() +function was interrupted by a signal that was caught, before any data +was available. +.TP +.BR EINVAL +The MSG_OOB flag is set and no out-of-band data is available. +.TP +.BR ENOTCONN +A receive is attempted on a connection-mode socket that is not +connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The specified flags are not supported for this socket type or +protocol. +.TP +.BR ETIMEDOUT +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.P +The +\fIrecv\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIrecv\fR() +function is equivalent to +\fIrecvfrom\fR() +with null pointer +.IR address +and +.IR address_len +arguments, and to +\fIread\fR() +if the +.IR socket +argument refers to a socket and the +.IR flags +argument is 0. +.P +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when data is available to be +received. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/recvfrom.3p b/man-pages-posix-2013-a/man3p/recvfrom.3p new file mode 100644 index 0000000..1323ba8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/recvfrom.3p @@ -0,0 +1,243 @@ +'\" et +.TH RECVFROM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +recvfrom +\(em receive a message from a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t recvfrom(int \fIsocket\fP, void *restrict \fIbuffer\fP, size_t \fIlength\fP, + int \fIflags\fP, struct sockaddr *restrict \fIaddress\fP, + socklen_t *restrict \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIrecvfrom\fR() +function shall receive a message from a connection-mode or +connectionless-mode socket. It is normally used with +connectionless-mode sockets because it permits the application to +retrieve the source address of received data. +.P +The +\fIrecvfrom\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fIbuffer\fR" 12 +Points to the buffer where the message should be stored. +.IP "\fIlength\fR" 12 +Specifies the length in bytes of the buffer pointed to by the +.IR buffer +argument. +.IP "\fIflags\fR" 12 +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following values: +.RS 12 +.IP MSG_PEEK 12 +Peeks at an incoming message. The data is treated as unread and the +next +\fIrecvfrom\fR() +or similar function shall still return this data. +.IP MSG_OOB 12 +Requests out-of-band data. The significance and semantics of +out-of-band data are protocol-specific. +.IP MSG_WAITALL 12 +On SOCK_STREAM sockets this requests that the function block until the +full amount of data can be returned. The function may return the +smaller amount of data if the socket is a message-based socket, if a +signal is caught, if the connection is terminated, if MSG_PEEK was +specified, or if an error is pending for the socket. +.RE +.IP "\fIaddress\fR" 12 +A null pointer, or points to a +.BR sockaddr +structure in which the sending address is to be stored. The length and +format of the address depend on the address family of the socket. +.IP "\fIaddress_len\fR" 12 +Either a null pointer, if +.IR address +is a null pointer, or a pointer to a +.BR socklen_t +object which on input specifies the length of the supplied +.BR sockaddr +structure, and on output specifies the length of the stored address. +.P +The +\fIrecvfrom\fR() +function shall return the length of the message written to the buffer +pointed to by the +.IR buffer +argument. For message-based sockets, such as +SOCK_RAW, +SOCK_DGRAM, and SOCK_SEQPACKET, the entire message shall be read in a +single operation. If a message is too long to fit in the supplied +buffer, and MSG_PEEK is not set in the +.IR flags +argument, the excess bytes shall be discarded. For stream-based +sockets, such as SOCK_STREAM, message boundaries shall be ignored. In +this case, data shall be returned to the user as soon as it becomes +available, and no data shall be discarded. +.P +If the MSG_WAITALL flag is not set, data shall be returned only up to +the end of the first message. +.P +Not all protocols provide the source address for messages. If the +.IR address +argument is not a null pointer and the protocol provides the source +address of messages, the source address of the received message shall +be stored in the +.BR sockaddr +structure pointed to by the +.IR address +argument, and the length of this address shall be stored in the object +pointed to by the +.IR address_len +argument. +.P +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. +.P +If the +.IR address +argument is not a null pointer and the protocol does not provide the +source address of messages, the value stored in the object pointed to +by +.IR address +is unspecified. +.P +If no messages are available at the socket and O_NONBLOCK is not set on +the socket's file descriptor, +\fIrecvfrom\fR() +shall block until a message arrives. If no messages are available at +the socket and O_NONBLOCK is set on the socket's file descriptor, +\fIrecvfrom\fR() +shall fail and set +.IR errno +to +.BR [EAGAIN] +or +.BR [EWOULDBLOCK] . +.SH "RETURN VALUE" +Upon successful completion, +\fIrecvfrom\fR() +shall return the length of the message in bytes. If no messages are +available to be received and the peer has performed an orderly +shutdown, +\fIrecvfrom\fR() +shall return 0. Otherwise, the function shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIrecvfrom\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and no data is +waiting to be received; or MSG_OOB is set and no out-of-band data is +available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await out-of-band data. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +A signal interrupted +\fIrecvfrom\fR() +before any data was available. +.TP +.BR EINVAL +The MSG_OOB flag is set and no out-of-band data is available. +.TP +.BR ENOTCONN +A receive is attempted on a connection-mode socket that is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The specified flags are not supported for this socket type. +.TP +.BR ETIMEDOUT +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.P +The +\fIrecvfrom\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when data is available to be +received. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/recvmsg.3p b/man-pages-posix-2013-a/man3p/recvmsg.3p new file mode 100644 index 0000000..855481b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/recvmsg.3p @@ -0,0 +1,278 @@ +'\" et +.TH RECVMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +recvmsg +\(em receive a message from a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t recvmsg(int \fIsocket\fP, struct msghdr *\fImessage\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIrecvmsg\fR() +function shall receive a message from a connection-mode or +connectionless-mode socket. It is normally used with +connectionless-mode sockets because it permits the application to +retrieve the source address of received data. +.P +The +\fIrecvmsg\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fImessage\fR" 12 +Points to a +.BR msghdr +structure, containing both the buffer to store the source address and +the buffers for the incoming message. The length and format of the +address depend on the address family of the socket. The +.IR msg_flags +member is ignored on input, but may contain meaningful values on +output. +.IP "\fIflags\fR" 12 +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following values: +.RS 12 +.IP MSG_OOB 12 +Requests out-of-band data. The significance and semantics of +out-of-band data are protocol-specific. +.IP MSG_PEEK 12 +Peeks at the incoming message. +.IP MSG_WAITALL 12 +On SOCK_STREAM sockets this requests that the function block until the +full amount of data can be returned. The function may return the +smaller amount of data if the socket is a message-based socket, if a +signal is caught, if the connection is terminated, if MSG_PEEK was +specified, or if an error is pending for the socket. +.RE +.P +The +\fIrecvmsg\fR() +function shall receive messages from unconnected or connected +sockets and shall return the length of the message. +.P +The +\fIrecvmsg\fR() +function shall return the total length of the message. For +message-based sockets, such as SOCK_DGRAM and SOCK_SEQPACKET, the +entire message shall be read in a single operation. If a message is too +long to fit in the supplied buffers, and MSG_PEEK is not set in the +.IR flags +argument, the excess bytes shall be discarded, and MSG_TRUNC shall be +set in the +.IR msg_flags +member of the +.BR msghdr +structure. For stream-based sockets, such as SOCK_STREAM, message +boundaries shall be ignored. In this case, data shall be returned to +the user as soon as it becomes available, and no data shall be +discarded. +.P +If the MSG_WAITALL flag is not set, data shall be returned only up to +the end of the first message. +.P +If no messages are available at the socket and O_NONBLOCK is not set on +the socket's file descriptor, +\fIrecvmsg\fR() +shall block until a message arrives. If no messages are available at +the socket and O_NONBLOCK is set on the socket's file descriptor, the +\fIrecvmsg\fR() +function shall fail and set +.IR errno +to +.BR [EAGAIN] +or +.BR [EWOULDBLOCK] . +.P +In the +.BR msghdr +structure, the +.IR msg_name +member may be a null pointer if the source address is not required. +Otherwise, if the socket is unconnected, the +.IR msg_name +member points to a +.BR sockaddr +structure in which the source address is to be stored, and the +.IR msg_namelen +member on input specifies the length of the supplied +.BR sockaddr +structure and on output specifies the length of the stored address. +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. If the socket is +connected, the +.IR msg_name +and +.IR msg_namelen +members shall be ignored. The +.IR msg_iov +and +.IR msg_iovlen +fields are used to specify where the received data shall be stored. +The +.IR msg_iov +member points to an array of +.BR iovec +structures; the +.IR msg_iovlen +member shall be set to the dimension of this array. In each +.BR iovec +structure, the +.IR iov_base +field specifies a storage area and the +.IR iov_len +field gives its size in bytes. Each storage area indicated by +.IR msg_iov +is filled with received data in turn until all of the received data is +stored or all of the areas have been filled. +.P +Upon successful completion, the +.IR msg_flags +member of the message header shall be the bitwise-inclusive OR of all +of the following flags that indicate conditions detected for the +received message: +.IP MSG_EOR 12 +End-of-record was received (if supported by the protocol). +.IP MSG_OOB 12 +Out-of-band data was received. +.IP MSG_TRUNC 12 +Normal data was truncated. +.IP MSG_CTRUNC 12 +Control data was truncated. +.SH "RETURN VALUE" +Upon successful completion, +\fIrecvmsg\fR() +shall return the length of the message in bytes. If no messages are +available to be received and the peer has performed an orderly +shutdown, +\fIrecvmsg\fR() +shall return 0. Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIrecvmsg\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and no data is +waiting to be received; or MSG_OOB is set and no out-of-band data is +available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await out-of-band data. +.TP +.BR EBADF +The +.IR socket +argument is not a valid open file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +This function was interrupted by a signal before any data was +available. +.TP +.BR EINVAL +The sum of the +.IR iov_len +values overflows a +.BR ssize_t , +or the MSG_OOB flag is set and no out-of-band data is available. +.TP +.BR EMSGSIZE +The +.IR msg_iovlen +member of the +.BR msghdr +structure pointed to by +.IR message +is less than or equal to 0, or is greater than +{IOV_MAX}. +.TP +.BR ENOTCONN +A receive is attempted on a connection-mode socket that is not +connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The specified flags are not supported for this socket type. +.TP +.BR ETIMEDOUT +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.P +The +\fIrecvmsg\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when data is available to be +received. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/regcomp.3p b/man-pages-posix-2013-a/man3p/regcomp.3p new file mode 100644 index 0000000..06466af --- /dev/null +++ b/man-pages-posix-2013-a/man3p/regcomp.3p @@ -0,0 +1,873 @@ +'\" et +.TH REGCOMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +regcomp, +regerror, +regexec, +regfree +\(em regular expression matching +.SH SYNOPSIS +.LP +.nf +#include +.P +int regcomp(regex_t *restrict \fIpreg\fP, const char *restrict \fIpattern\fP, + int \fIcflags\fP); +size_t regerror(int \fIerrcode\fP, const regex_t *restrict \fIpreg\fP, + char *restrict \fIerrbuf\fP, size_t \fIerrbuf_size\fP); +int regexec(const regex_t *restrict \fIpreg\fP, const char *restrict \fIstring\fP, + size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[restrict], int \fIeflags\fP); +void regfree(regex_t *\fIpreg\fP); +.fi +.SH DESCRIPTION +These functions interpret +.IR basic +and +.IR extended +regular expressions as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 9" ", " "Regular Expressions". +.P +The +.BR regex_t +structure is defined in +.IR +and contains at least the following member: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +size_t!re_nsub!T{ +Number of parenthesized subexpressions. +T} +.TE +.P +The +.BR regmatch_t +structure is defined in +.IR +and contains at least the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +regoff_t!rm_so!T{ +Byte offset from start of \fIstring\fP to start of substring. +T} +regoff_t!rm_eo!T{ +Byte offset from start of +.IR string +of the first character after the end of substring. +T} +.TE +.P +The +\fIregcomp\fR() +function shall compile the regular expression contained in the string +pointed to by the +.IR pattern +argument and place the results in the structure pointed to by +.IR preg . +The +.IR cflags +argument is the bitwise-inclusive OR of zero or more of the following +flags, which are defined in the +.IR +header: +.IP REG_EXTENDED 14 +Use Extended Regular Expressions. +.IP REG_ICASE 14 +Ignore case in match (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 9" ", " "Regular Expressions"). +.IP REG_NOSUB 14 +Report only success/fail in +\fIregexec\fR(). +.IP REG_NEWLINE 14 +Change the handling of + +characters, as described in the text. +.P +The default regular expression type for +.IR pattern +is a Basic Regular Expression. The application can specify Extended +Regular Expressions using the REG_EXTENDED +.IR cflags +flag. +.P +If the REG_NOSUB flag was not set in +.IR cflags , +then +\fIregcomp\fR() +shall set +.IR re_nsub +to the number of parenthesized subexpressions (delimited by +.BR \(dq\e(\e)\(dq +in basic regular expressions or +.BR \(dq(\|)\(dq +in extended regular expressions) found in +.IR pattern . +.P +The +\fIregexec\fR() +function compares the null-terminated string specified by +.IR string +with the compiled regular expression +.IR preg +initialized by a previous call to +\fIregcomp\fR(). +If it finds a match, +\fIregexec\fR() +shall return 0; otherwise, it shall return non-zero indicating either +no match or an error. The +.IR eflags +argument is the bitwise-inclusive OR of zero or more of the following +flags, which are defined in the +.IR +header: +.IP REG_NOTBOL 14 +The first character of the string pointed to by +.IR string +is not the beginning of the line. Therefore, the + +character +(\c +.BR '^' ), +when taken as a special character, shall not match the beginning of +.IR string . +.IP REG_NOTEOL 14 +The last character of the string pointed to by +.IR string +is not the end of the line. Therefore, the + +(\c +.BR '$' ), +when taken as a special character, shall not match the end of +.IR string . +.P +If +.IR nmatch +is 0 or REG_NOSUB was set in the +.IR cflags +argument to +\fIregcomp\fR(), +then +\fIregexec\fR() +shall ignore the +.IR pmatch +argument. Otherwise, the application shall ensure that the +.IR pmatch +argument points to an array with at least +.IR nmatch +elements, and +\fIregexec\fR() +shall fill in the elements of that array with offsets of the substrings +of +.IR string +that correspond to the parenthesized subexpressions of +.IR pattern : +.IR pmatch [\c +.IR i ].\c +.IR rm_so +shall be the byte offset of the beginning and +.IR pmatch [\c +.IR i ].\c +.IR rm_eo +shall be one greater than the byte offset of the end of substring +.IR i . +(Subexpression +.IR i +begins at the +.IR i th +matched open parenthesis, counting from 1.) Offsets in +.IR pmatch [0] +identify the substring that corresponds to the entire regular +expression. Unused elements of +.IR pmatch +up to +.IR pmatch [\c +.IR nmatch \(mi1] +shall be filled with \(mi1. If there are more than +.IR nmatch +subexpressions in +.IR pattern +(\c +.IR pattern +itself counts as a subexpression), then +\fIregexec\fR() +shall still do the match, but shall record only the first +.IR nmatch +substrings. +.P +When matching a basic or extended regular expression, any given +parenthesized subexpression of +.IR pattern +might participate in the match of several different substrings of +.IR string , +or it might not match any substring even though the pattern as a whole +did match. The following rules shall be used to determine which +substrings to report in +.IR pmatch +when matching regular expressions: +.IP " 1." 4 +If subexpression +.IR i +in a regular expression is not contained within another subexpression, +and it participated in the match several times, then the byte offsets +in +.IR pmatch [\c +.IR i ] +shall delimit the last such match. +.IP " 2." 4 +If subexpression +.IR i +is not contained within another subexpression, and it did not +participate in an otherwise successful match, the byte offsets in +.IR pmatch [\c +.IR i ] +shall be \(mi1. A subexpression does not participate in the match when: +.sp +.RS +.BR '*' +or +.BR \(dq\e{\e}\(dq +appears immediately after the subexpression in a basic regular +expression, or +.BR '*' , +.BR '?' , +or +.BR \(dq{\|}\(dq +appears immediately after the subexpression in an extended regular +expression, and the subexpression did not match (matched 0 times) +.RE +.RS 4 +.P +or: +.sp +.RS +.BR '|' +is used in an extended regular expression to select this subexpression +or another, and the other subexpression matched. +.RE +.RE +.IP " 3." 4 +If subexpression +.IR i +is contained within another subexpression +.IR j , +and +.IR i +is not contained within any other subexpression that is contained +within +.IR j , +and a match of subexpression +.IR j +is reported in +.IR pmatch [\c +.IR j ], +then the match or non-match of subexpression +.IR i +reported in +.IR pmatch [\c +.IR i ] +shall be as described in 1. and 2. above, but within the substring +reported in +.IR pmatch [\c +.IR j ] +rather than the whole string. The offsets in +.IR pmatch [\c +.IR i ] +are still relative to the start of +.IR string . +.IP " 4." 4 +If subexpression +.IR i +is contained in subexpression +.IR j , +and the byte offsets in +.IR pmatch [\c +.IR j ] +are \(mi1, then the pointers in +.IR pmatch [\c +.IR i ] +shall also be \(mi1. +.IP " 5." 4 +If subexpression +.IR i +matched a zero-length string, then both byte offsets in +.IR pmatch [\c +.IR i ] +shall be the byte offset of the character or null terminator +immediately following the zero-length string. +.P +If, when +\fIregexec\fR() +is called, the locale is different from when the regular expression was +compiled, the result is undefined. +.P +If REG_NEWLINE is not set in +.IR cflags , +then a + +in +.IR pattern +or +.IR string +shall be treated as an ordinary character. If REG_NEWLINE is set, then + +shall be treated as an ordinary character except as follows: +.IP " 1." 4 +A + +in +.IR string +shall not be matched by a + +outside a bracket expression or by any form of a non-matching list +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 9" ", " "Regular Expressions"). +.IP " 2." 4 +A + +(\c +.BR '^' ) +in +.IR pattern , +when used to specify expression anchoring (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3.8" ", " "BRE Expression Anchoring"), +shall match the zero-length string immediately after a + +in +.IR string , +regardless of the setting of REG_NOTBOL. +.IP " 3." 4 +A + +(\c +.BR '$' ) +in +.IR pattern , +when used to specify expression anchoring, shall match the zero-length +string immediately before a + +in +.IR string , +regardless of the setting of REG_NOTEOL. +.P +The +\fIregfree\fR() +function frees any memory allocated by +\fIregcomp\fR() +associated with +.IR preg . +.P +The following constants are defined as the minimum set of error return +values, although other errors listed as implementation extensions in +.IR +are possible: +.IP REG_BADBR 14 +Content of +.BR \(dq\e{\e}\(dq +invalid: not a number, number too large, more than two numbers, first +larger than second. +.IP REG_BADPAT 14 +Invalid regular expression. +.IP REG_BADRPT 14 +.BR '?' , +.BR '*' , +or +.BR '+' +not preceded by valid regular expression. +.IP REG_EBRACE 14 +.BR \(dq\e{\e}\(dq +imbalance. +.IP REG_EBRACK 14 +.BR \(dq[]\(dq +imbalance. +.IP REG_ECOLLATE 14 +Invalid collating element referenced. +.IP REG_ECTYPE 14 +Invalid character class type referenced. +.IP REG_EESCAPE 14 +Trailing + +character in pattern. +.IP REG_EPAREN 14 +.BR \(dq\e(\e)\(dq +or +.BR \(dq()\(dq +imbalance. +.IP REG_ERANGE 14 +Invalid endpoint in range expression. +.IP REG_ESPACE 14 +Out of memory. +.IP REG_ESUBREG 14 +Number in +.BR \(dq\edigit\(dq +invalid or in error. +.IP REG_NOMATCH 14 +\fIregexec\fR() +failed to match. +.P +If more than one error occurs in processing a function call, any one +of the possible constants may be returned, as the order of detection is +unspecified. +.P +The +\fIregerror\fR() +function provides a mapping from error codes returned by +\fIregcomp\fR() +and +\fIregexec\fR() +to unspecified printable strings. It generates a string corresponding +to the value of the +.IR errcode +argument, which the application shall ensure is the last non-zero value +returned by +\fIregcomp\fR() +or +\fIregexec\fR() +with the given value of +.IR preg . +If +.IR errcode +is not such a value, the content of the generated string is unspecified. +.P +If +.IR preg +is a null pointer, but +.IR errcode +is a value returned by a previous call to +\fIregexec\fR() +or +\fIregcomp\fR(), +the +\fIregerror\fR() +still generates an error string corresponding to the value of +.IR errcode , +but it might not be as detailed under some implementations. +.P +If the +.IR errbuf_size +argument is not 0, +\fIregerror\fR() +shall place the generated string into the buffer of size +.IR errbuf_size +bytes pointed to by +.IR errbuf . +If the string (including the terminating null) cannot fit in the +buffer, +\fIregerror\fR() +shall truncate the string and null-terminate the result. +.P +If +.IR errbuf_size +is 0, +\fIregerror\fR() +shall ignore the +.IR errbuf +argument, and return the size of the buffer needed to hold the +generated string. +.P +If the +.IR preg +argument to +\fIregexec\fR() +or +\fIregfree\fR() +is not a compiled regular expression returned by +\fIregcomp\fR(), +the result is undefined. A +.IR preg +is no longer treated as a compiled regular expression after it is given +to +\fIregfree\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fIregcomp\fR() +function shall return 0. Otherwise, it shall return an integer value +indicating an error as described in +.IR , +and the content of +.IR preg +is undefined. If a code is returned, the interpretation shall be as +given in +.IR . +.P +If +\fIregcomp\fR() +detects an invalid RE, it may return REG_BADPAT, or it may return one +of the error codes that more precisely describes the error. +.P +Upon successful completion, the +\fIregexec\fR() +function shall return 0. Otherwise, it shall return REG_NOMATCH to +indicate no match. +.P +Upon successful completion, the +\fIregerror\fR() +function shall return the number of bytes needed to hold the entire +generated string, including the null termination. If the return value +is greater than +.IR errbuf_size , +the string returned in the buffer pointed to by +.IR errbuf +has been truncated. +.P +The +\fIregfree\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +.sp +.RS 4 +.nf +\fB +#include +.P +/* + * Match string against the extended regular expression in + * pattern, treating errors as no match. + * + * Return 1 for match, 0 for no match. + */ +.P +int +match(const char *string, char *pattern) +{ + int status; + regex_t re; +.P + if (regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB) != 0) { + return(0); /* Report error. */ + } + status = regexec(&re, string, (size_t) 0, NULL, 0); + regfree(&re); + if (status != 0) { + return(0); /* Report error. */ + } + return(1); +} +.fi \fR +.P +.RE +.P +The following demonstrates how the REG_NOTBOL flag could be used with +\fIregexec\fR() +to find all substrings in a line that match a pattern supplied by a user. +(For simplicity of the example, very little error checking is done.) +.sp +.RS 4 +.nf +\fB +(void) regcomp (&re, pattern, 0); +/* This call to regexec() finds the first match on the line. */ +error = regexec (&re, &buffer[0], 1, &pm, 0); +while (error == 0) { /* While matches found. */ + /* Substring found between pm.rm_so and pm.rm_eo. */ + /* This call to regexec() finds the next match. */ + error = regexec (&re, buffer + pm.rm_eo, 1, &pm, REG_NOTBOL); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +An application could use: +.sp +.RS 4 +.nf +\fB +regerror(code,preg,(char *)NULL,(size_t)0) +.fi \fR +.P +.RE +.P +to find out how big a buffer is needed for the generated string, +\fImalloc\fR() +a buffer to hold the string, and then call +\fIregerror\fR() +again to get the string. Alternatively, it could allocate a fixed, +static buffer that is big enough to hold most strings, and then use +\fImalloc\fR() +to allocate a larger buffer if it finds that this is too small. +.P +To match a pattern as described in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.13" ", " "Pattern Matching Notation", +use the +\fIfnmatch\fR() +function. +.SH RATIONALE +The +\fIregexec\fR() +function must fill in all +.IR nmatch +elements of +.IR pmatch , +where +.IR nmatch +and +.IR pmatch +are supplied by the application, even if some elements of +.IR pmatch +do not correspond to subexpressions in +.IR pattern . +The application developer should note that there is probably no reason +for using a value of +.IR nmatch +that is larger than +.IR preg \(mi>\c +.IR re_nsub +1. +.P +The REG_NEWLINE flag supports a use of RE matching that is needed in +some applications like text editors. In such applications, the user +supplies an RE asking the application to find a line that matches the +given expression. An anchor in such an RE anchors at the beginning or +end of any line. Such an application can pass a sequence of +-separated +lines to +\fIregexec\fR() +as a single long string and specify REG_NEWLINE to +\fIregcomp\fR() +to get the desired behavior. The application must ensure that there are +no explicit + +characters in +.IR pattern +if it wants to ensure that any match occurs entirely within a single +line. +.P +The REG_NEWLINE flag affects the behavior of +\fIregexec\fR(), +but it is in the +.IR cflags +parameter to +\fIregcomp\fR() +to allow flexibility of implementation. Some implementations will want +to generate the same compiled RE in +\fIregcomp\fR() +regardless of the setting of REG_NEWLINE and have +\fIregexec\fR() +handle anchors differently based on the setting of the flag. Other +implementations will generate different compiled REs based on the +REG_NEWLINE. +.P +The REG_ICASE flag supports the operations taken by the +.IR grep +.BR \(mii +option and the historical implementations of +.IR ex +and +.IR vi . +Including this flag will make it easier for application code to be +written that does the same thing as these utilities. +.P +The substrings reported in +.IR pmatch [\|] +are defined using offsets from the start of the string rather than +pointers. This allows type-safe access to both constant and non-constant +strings. +.P +The type +.BR regoff_t +is used for the elements of +.IR pmatch [\|] +to ensure that the application can represent large arrays in memory +(important for an application conforming to the Shell and Utilities volume of POSIX.1\(hy2008). +.P +The 1992 edition of this standard required +.BR regoff_t +to be at least as wide as +.BR off_t , +to facilitate future extensions in which the string to be searched is +taken from a file. However, these future extensions have not appeared. +The requirement rules out popular implementations with 32-bit +.BR regoff_t +and 64-bit +.BR off_t , +so it has been removed. +.P +The standard developers rejected the inclusion of a +\fIregsub\fR() +function that would be used to do substitutions for a matched RE. While +such a routine would be useful to some applications, its utility would +be much more limited than the matching function described here. Both RE +parsing and substitution are possible to implement without support +other than that required by the ISO\ C standard, but matching is much more +complex than substituting. The only difficult part of substitution, +given the information supplied by +\fIregexec\fR(), +is finding the next character in a string when there can be multi-byte +characters. That is a much larger issue, and one that needs a more +general solution. +.P +The +.IR errno +variable has not been used for error returns to avoid filling the +.IR errno +name space for this feature. +.P +The interface is defined so that the matched substrings +.IR rm_sp +and +.IR rm_ep +are in a separate +.BR regmatch_t +structure instead of in +.BR regex_t . +This allows a single compiled RE to be used simultaneously in several +contexts; in +\fImain\fR() +and a signal handler, perhaps, or in multiple threads of lightweight +processes. (The +.IR preg +argument to +\fIregexec\fR() +is declared with type +.BR const , +so the implementation is not permitted to use the structure to store +intermediate results.) It also allows an application to request an +arbitrary number of substrings from an RE. The number of +subexpressions in the RE is reported in +.IR re_nsub +in +.IR preg . +With this change to +\fIregexec\fR(), +consideration was given to dropping the REG_NOSUB flag since the user +can now specify this with a zero +.IR nmatch +argument to +\fIregexec\fR(). +However, keeping REG_NOSUB allows an implementation to use a different +(perhaps more efficient) algorithm if it knows in +\fIregcomp\fR() +that no subexpressions need be reported. The implementation is only +required to fill in +.IR pmatch +if +.IR nmatch +is not zero and if REG_NOSUB is not specified. Note that the +.BR size_t +type, as defined in the ISO\ C standard, is unsigned, so the description of +\fIregexec\fR() +does not need to address negative values of +.IR nmatch . +.P +REG_NOTBOL was added to allow an application to do repeated searches +for the same pattern in a line. If the pattern contains a + +character that should match the beginning of a line, then the pattern +should only match when matched against the beginning of the line. +Without the REG_NOTBOL flag, the application could rewrite the +expression for subsequent matches, but in the general case this would +require parsing the expression. The need for REG_NOTEOL is not as +clear; it was added for symmetry. +.P +The addition of the +\fIregerror\fR() +function addresses the historical need for conforming application +programs to have access to error information more than ``Function +failed to compile/match your RE for unknown reasons''. +.P +This interface provides for two different methods of dealing with error +conditions. The specific error codes (REG_EBRACE, for example), defined +in +.IR , +allow an application to recover from an error if it is so able. Many +applications, especially those that use patterns supplied by a user, +will not try to deal with specific error cases, but will just use +\fIregerror\fR() +to obtain a human-readable error message to present to the user. +.P +The +\fIregerror\fR() +function uses a scheme similar to +\fIconfstr\fR() +to deal with the problem of allocating memory to hold the generated +string. The scheme used by +\fIstrerror\fR() +in the ISO\ C standard was considered unacceptable since it creates difficulties +for multi-threaded applications. +.P +The +.IR preg +argument is provided to +\fIregerror\fR() +to allow an implementation to generate a more descriptive message than +would be possible with +.IR errcode +alone. An implementation might, for example, save the character offset +of the offending character of the pattern in a field of +.IR preg , +and then include that in the generated message string. The +implementation may also ignore +.IR preg . +.P +A REG_FILENAME flag was considered, but omitted. This flag caused +\fIregexec\fR() +to match patterns as described in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.13" ", " "Pattern Matching Notation" +instead of REs. This service is now provided by the +\fIfnmatch\fR() +function. +.P +Notice that there is a difference in philosophy between the ISO\ POSIX\(hy2:\|1993 standard and +POSIX.1\(hy2008 in how to handle a ``bad'' regular expression. The ISO\ POSIX\(hy2:\|1993 standard says +that many bad constructs ``produce undefined results'', or that +``the interpretation is undefined''. POSIX.1\(hy2008, however, says that the +interpretation of such REs is unspecified. The term ``undefined'' means +that the action by the application is an error, of similar severity +to passing a bad pointer to a function. +.P +The +\fIregcomp\fR() +and +\fIregexec\fR() +functions are required to accept any null-terminated string as the +.IR pattern +argument. If the meaning of the string is ``undefined'', the behavior +of the function is ``unspecified''. POSIX.1\(hy2008 does not specify how the +functions will interpret the pattern; they might return error codes, or +they might do pattern matching in some completely unexpected way, but +they should not do something like abort the process. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfnmatch\fR\^(\|)", +.IR "\fIglob\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 9" ", " "Regular Expressions", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.13" ", " "Pattern Matching Notation" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/remainder.3p b/man-pages-posix-2013-a/man3p/remainder.3p new file mode 100644 index 0000000..70a121e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/remainder.3p @@ -0,0 +1,145 @@ +'\" et +.TH REMAINDER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +remainder, +remainderf, +remainderl +\(em remainder function +.SH SYNOPSIS +.LP +.nf +#include +.P +double remainder(double \fIx\fP, double \fIy\fP); +float remainderf(float \fIx\fP, float \fIy\fP); +long double remainderl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall return the floating-point remainder +.IR r =\c +.IR x \(mi\c +.IR ny +when +.IR y +is non-zero. The value +.IR n +is the integral value nearest the exact value +.IR x /\c +.IR y . +When |\|\fIn\fR\(mi\fIx\fR/\fIy\fR\||=\(12, the value +.IR n +is chosen to be even. +.P +The behavior of +\fIremainder\fR() +shall be independent of the rounding mode. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the +floating-point remainder +.IR r =\c +.IR x \(mi\c +.IR ny +when +.IR y +is non-zero. +.P +On systems that do not support the IEC 60559 Floating-Point option, if +.IR y +is zero, it is implementation-defined whether a domain error occurs or +zero is returned. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If +.IR x +is infinite or +.IR y +is 0 and the other is non-NaN, a domain error shall occur, and a NaN +shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is \(+-Inf, or the +.IR y +argument is \(+-0 and the other argument is non-NaN. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The +.IR y +argument is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIabs\fR\^(\|)", +.IR "\fIdiv\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIldiv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/remove.3p b/man-pages-posix-2013-a/man3p/remove.3p new file mode 100644 index 0000000..a06a78e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/remove.3p @@ -0,0 +1,97 @@ +'\" et +.TH REMOVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +remove +\(em remove a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int remove(const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIremove\fR() +function shall cause the file named by the pathname pointed to by +.IR path +to be no longer accessible by that name. A subsequent attempt to open +that file using that name shall fail, unless it is created anew. +.P +If +.IR path +does not name a directory, \fIremove\fP(\fIpath\fP) shall be equivalent +to \fIunlink\fP(\fIpath\fP). +.P +If +.IR path +names a directory, \fIremove\fP(\fIpath\fP) shall be equivalent to +\fIrmdir\fP(\fIpath\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIrmdir\fR\^(\|)" +or +.IR "\fIunlink\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIrmdir\fR\^(\|)" +or +.IR "\fIunlink\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Removing Access to a File" +.P +The following example shows how to remove access to a file named +.BR /home/cnd/old_mods . +.sp +.RS 4 +.nf +\fB +#include +.P +int status; +\&... +status = remove("/home/cnd/old_mods"); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/remque.3p b/man-pages-posix-2013-a/man3p/remque.3p new file mode 100644 index 0000000..3cc5221 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/remque.3p @@ -0,0 +1,38 @@ +'\" et +.TH REMQUE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +remque +\(em remove an element from a queue +.SH SYNOPSIS +.LP +.nf +#include +.P +void remque(void *\fIelement\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIinsque\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/remquo.3p b/man-pages-posix-2013-a/man3p/remquo.3p new file mode 100644 index 0000000..54b48fb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/remquo.3p @@ -0,0 +1,161 @@ +'\" et +.TH REMQUO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +remquo, +remquof, +remquol +\(em remainder functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double remquo(double \fIx\fP, double \fIy\fP, int *\fIquo\fP); +float remquof(float \fIx\fP, float \fIy\fP, int *\fIquo\fP); +long double remquol(long double \fIx\fP, long double \fIy\fP, int *\fIquo\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIremquo\fR(), +\fIremquof\fR(), +and +\fIremquol\fR() +functions shall compute the same remainder as the +\fIremainder\fR(), +\fIremainderf\fR(), +and +\fIremainderl\fR() +functions, respectively. In the object pointed to by +.IR quo , +they store a value whose sign is the sign of +.IR x /\c +.IR y +and whose magnitude is congruent modulo 2\fI\s-3\un\d\s+3\fR to the +magnitude of the integral quotient of +.IR x /\c +.IR y , +where +.IR n +is an implementation-defined integer greater than or equal to 3. If +.IR y +is zero, the value stored in the object pointed to by +.IR quo +is unspecified. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +These functions shall return +.IR x +REM +.IR y . +.P +On systems that do not support the IEC 60559 Floating-Point option, if +.IR y +is zero, it is implementation-defined whether a domain error occurs or +zero is returned. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-Inf or +.IR y +is zero and the other argument is non-NaN, a domain error shall occur, +and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is \(+-Inf, or the +.IR y +argument is \(+-0 and the other argument is non-NaN. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The +.IR y +argument is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions are intended for implementing argument reductions which +can exploit a few low-order bits of the quotient. Note that +.IR x +may be so large in magnitude relative to +.IR y +that an exact representation of the quotient is not practical. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIremainder\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/rename.3p b/man-pages-posix-2013-a/man3p/rename.3p new file mode 100644 index 0000000..c189d77 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/rename.3p @@ -0,0 +1,549 @@ +'\" et +.TH RENAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rename, renameat +\(em rename file relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int rename(const char *\fIold\fP, const char *\fInew\fP); +int renameat(int \fIoldfd\fP, const char *\fIold\fP, int \fInewfd\fP, + const char *\fInew\fP); +.fi +.SH DESCRIPTION +For +\fIrename\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIrename\fR() +function shall change the name of a file. The +.IR old +argument points to the pathname of the file to be renamed. The +.IR new +argument points to the new pathname of the file. +If the +.IR new +argument does not resolve to an existing directory entry for a file of +type directory and the +.IR new +argument contains at least one non-\c + +character and ends with one or more trailing + +characters after all symbolic links have been processed, +\fIrename\fR() +shall fail. +.P +If either the +.IR old +or +.IR new +argument names a symbolic link, +\fIrename\fR() +shall operate on the symbolic link itself, and shall not resolve the +last component of the argument. If the +.IR old +argument and the +.IR new +argument resolve to either the same existing directory entry or different +directory entries for the same existing file, +\fIrename\fR() +shall return successfully and perform no other action. +.P +If the +.IR old +argument points to the pathname of a file that is not a directory, the +.IR new +argument shall not point to the pathname of a directory. If the link +named by the +.IR new +argument exists, it shall be removed and +.IR old +renamed to +.IR new . +In this case, a link named +.IR new +shall remain visible to other processes throughout the renaming operation +and refer either to the file referred to by +.IR new +or +.IR old +before the operation began. Write access permission is required for +both the directory containing +.IR old +and the directory containing +.IR new . +.P +If the +.IR old +argument points to the pathname of a directory, the +.IR new +argument shall not point to the pathname of a file that is not a +directory. If the directory named by the +.IR new +argument exists, it shall be removed and +.IR old +renamed to +.IR new . +In this case, a link named +.IR new +shall exist throughout the renaming operation and shall refer either to +the directory referred to by +.IR new +or +.IR old +before the operation began. If +.IR new +names an existing directory, it shall be required to be an empty +directory. +.P +If either +.IR pathname +argument refers to a path whose final component is either dot or +dot-dot, +\fIrename\fR() +shall fail. +.P +If the +.IR old +argument points to a pathname of a symbolic link, the symbolic link +shall be renamed. If the +.IR new +argument points to a pathname of a symbolic link, the symbolic link +shall be removed. +.P +The +.IR old +pathname shall not name an ancestor directory of the +.IR new +pathname. Write access permission is required for the directory containing +.IR old +and the directory containing +.IR new . +If the +.IR old +argument points to the pathname of a directory, write access permission +may be required for the directory named by +.IR old , +and, if it exists, the directory named by +.IR new . +.P +If the link named by the +.IR new +argument exists and the file's link count becomes 0 when it is removed +and no process has the file open, the space occupied by the file shall +be freed and the file shall no longer be accessible. If one or more +processes have the file open when the last link is removed, the link +shall be removed before +\fIrename\fR() +returns, but the removal of the file contents shall be postponed until +all references to the file are closed. +.P +Upon successful completion, +\fIrename\fR() +shall mark for update the last data modification and last file status +change timestamps of the parent directory of each file. +.P +If the +\fIrename\fR() +function fails for any reason other than +.BR [EIO] , +any file named by +.IR new +shall be unaffected. +.P +The +\fIrenameat\fR() +function shall be equivalent to the +\fIrename\fR() +function except in the case where either +.IR old +or +.IR new +specifies a relative path. If +.IR old +is a relative path, the file to be renamed is located relative to the +directory associated with the file descriptor +.IR oldfd +instead of the current working directory. If +.IR new +is a relative path, the same happens only relative to the directory +associated with +.IR newfd . +If the file descriptor was opened without O_SEARCH, the function +shall check whether directory searches are permitted using the current +permissions of the directory underlying the file descriptor. If the +file descriptor was opened with O_SEARCH, the function shall not perform +the check. +.P +If +\fIrenameat\fR() +is passed the special value AT_FDCWD in the +.IR oldfd +or +.IR newfd +parameter, the current working directory shall be used in the +determination of the file for the respective +.IR path +parameter. +.SH "RETURN VALUE" +Upon successful completion, the +\fIrename\fR() +function shall return 0. Otherwise, it shall return \(mi1, +.IR errno +shall be set to indicate the error, +and neither the file named by +.IR old +nor the file named by +.IR new +shall be changed or created. +.P +Upon successful completion, the +\fIrenameat\fR() +function shall return 0. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIrename\fR() +and +\fIrenameat\fR() +functions shall fail if: +.TP +.BR EACCES +A component of either path prefix denies search permission; or one of +the directories containing +.IR old +or +.IR new +denies write permissions; or, write permission is required and is +denied for a directory pointed to by the +.IR old +or +.IR new +arguments. +.TP +.BR EBUSY +The directory named by +.IR old +or +.IR new +is currently in use by the system or another process, and the +implementation considers this an error. +.IP "[EEXIST]\ or\ [ENOTEMPTY]" 12 +.br +The link named by +.IR new +is a directory that is not an empty directory. +.TP +.BR EINVAL +The +.IR old +pathname names an ancestor directory of the +.IR new +pathname, or either pathname argument contains a final component that +is dot or dot-dot. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR EISDIR +The +.IR new +argument points to a directory and the +.IR old +argument points to a file that is not a directory. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMLINK +The file named by +.IR old +is a directory, and the link count of the parent directory of +.IR new +would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +The link named by +.IR old +does not name an existing file, a component of the path prefix of +.IR new +does not exist, or either +.IR old +or +.IR new +points to an empty string. +.TP +.BR ENOSPC +The directory that would contain +.IR new +cannot be extended. +.TP +.BR ENOTDIR +A component of either path prefix names an existing file that is +neither a directory nor a symbolic link to a directory; or the +.IR old +argument names a directory and the +.IR new +argument names a non-directory file; or the +.IR old +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory; or the +.IR old +argument names an existing non-directory file and the +.IR new +argument names a nonexistent file, contains at least one non-\c + +character, and ends with one or more trailing + +characters; or the +.IR new +argument names an existing non-directory file, contains at least one non-\c + +character, and ends with one or more trailing + +characters. +.TP +.BR EPERM " or " EACCES +.br +The S_ISVTX flag is set on the directory containing the file referred +to by +.IR old +and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.2" ", " "Directory Protection" +with respect to +.IR old ; +or +.IR new +refers to an existing file, the S_ISVTX flag is set on the directory +containing this file, and the process does not satisfy the criteria +specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.2" ", " "Directory Protection" +with respect to this file. +.TP +.BR EROFS +The requested operation requires writing in a directory on a read-only +file system. +.TP +.BR EXDEV +The links named by +.IR new +and +.IR old +are on different file systems and the implementation does not support +links between file systems. +.P +In addition, the +\fIrenameat\fR() +function shall fail if: +.TP +.BR EACCES +.IR oldfd +or +.IR newfd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR oldfd +or +.IR newfd +respectively do not permit directory searches. +.TP +.BR EBADF +The +.IR old +argument does not specify an absolute path and the +.IR oldfd +argument is neither AT_FDCWD nor a valid file descriptor open for +reading or searching, or the +.IR new +argument does not specify an absolute path and the +.IR newfd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR old +or +.IR new +argument is not an absolute path and +.IR oldfd +or +.IR newfd , +respectively, is a file descriptor associated with a non-directory file. +.P +The +\fIrename\fR() +and +\fIrenameat\fR() +functions may fail if: +.TP +.BR EBUSY +The file named by the +.IR old +or +.IR new +arguments is a named STREAM. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +The file named by +.IR new +exists and is the last directory entry to a pure procedure (shared text) +file that is being executed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Renaming a File" +.P +The following example shows how to rename a file named +.BR /home/cnd/mod1 +to +.BR /home/cnd/mod2 . +.sp +.RS 4 +.nf +\fB +#include +.P +int status; +\&... +status = rename("/home/cnd/mod1", "/home/cnd/mod2"); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Some implementations mark for update the last file status change timestamp +of renamed files and some do not. Applications which make use of the +last file status change timestamp may behave differently with respect +to renamed files unless they are designed to allow for either behavior. +.SH RATIONALE +This +\fIrename\fR() +function is equivalent for regular files to that defined by the ISO\ C standard. +Its inclusion here expands that definition to include actions on +directories and specifies behavior when the +.IR new +parameter names a file that already exists. That specification +requires that the action of the function be atomic. +.P +One of the reasons for introducing this function was to have a means of +renaming directories while permitting implementations to prohibit the +use of +\fIlink\fR() +and +\fIunlink\fR() +with directories, thus constraining links to directories to those made by +\fImkdir\fR(). +.P +The specification that if +.IR old +and +.IR new +refer to the same file is intended to guarantee that: +.sp +.RS 4 +.nf +\fB +rename("x", "x"); +.fi \fR +.P +.RE +.P +does not remove the file. +.P +Renaming dot or dot-dot is prohibited in order to prevent cyclical file +system paths. +.P +See also the descriptions of +.BR [ENOTEMPTY] +and +.BR [ENAMETOOLONG] +in +\fIrmdir\fR() +and +.BR [EBUSY] +in +\fIunlink\fR(). +For a discussion of +.BR [EXDEV] , +see +\fIlink\fR(). +.P +The purpose of the +\fIrenameat\fR() +function is to rename files in directories other than the current +working directory without exposure to race conditions. Any part of the +path of a file could be changed in parallel to a call to +\fIrename\fR(), +resulting in unspecified behavior. By opening file descriptors for the +source and target directories and using the +\fIrenameat\fR() +function it can be guaranteed that that renamed file is located correctly +and the resulting file is in the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlink\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.2" ", " "Directory Protection", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/rewind.3p b/man-pages-posix-2013-a/man3p/rewind.3p new file mode 100644 index 0000000..8ab54b5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/rewind.3p @@ -0,0 +1,100 @@ +'\" et +.TH REWIND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rewind +\(em reset the file position indicator in a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +void rewind(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The call: +.sp +.RS 4 +.nf +\fB +rewind(stream) +.fi \fR +.P +.RE +.P +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +(void) fseek(stream, 0L, SEEK_SET) +.fi \fR +.P +.RE +.P +except that +\fIrewind\fR() +shall also clear the error indicator. +.P +Since +\fIrewind\fR() +does not return a value, an application wishing to detect errors should +clear +.IR errno , +then call +\fIrewind\fR(), +and if +.IR errno +is non-zero, assume an error has occurred. +.SH "RETURN VALUE" +The +\fIrewind\fR() +function shall not return a value. +.SH ERRORS +Refer to +.IR "\fIfseek\fR\^(\|)" +with the exception of +.BR [EINVAL] +which does not apply. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfseek\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/rewinddir.3p b/man-pages-posix-2013-a/man3p/rewinddir.3p new file mode 100644 index 0000000..ca2f2dd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/rewinddir.3p @@ -0,0 +1,91 @@ +'\" et +.TH REWINDDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rewinddir +\(em reset the position of a directory stream to the beginning +of a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +void rewinddir(DIR *\fIdirp\fP); +.fi +.SH DESCRIPTION +The +\fIrewinddir\fR() +function shall reset the position of the directory stream to which +.IR dirp +refers to the beginning of the directory. It shall also cause the +directory stream to refer to the current state of the corresponding +directory, as a call to +\fIopendir\fR() +would have done. If +.IR dirp +does not refer to a directory stream, the effect is undefined. +.P +After a call to the +\fIfork\fR() +function, either the parent or child (but not both) may continue +processing the directory stream using +\fIreaddir\fR(), +\fIrewinddir\fR(), +or +\fIseekdir\fR(). +If both the parent and child processes use these functions, the result +is undefined. +.SH "RETURN VALUE" +The +\fIrewinddir\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIrewinddir\fR() +function should be used in conjunction with +\fIopendir\fR(), +\fIreaddir\fR(), +and +\fIclosedir\fR() +to examine the contents of the directory. This method is recommended +for portability. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/rint.3p b/man-pages-posix-2013-a/man3p/rint.3p new file mode 100644 index 0000000..4a97551 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/rint.3p @@ -0,0 +1,130 @@ +'\" et +.TH RINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rint, +rintf, +rintl +\(em round-to-nearest integral value +.SH SYNOPSIS +.LP +.nf +#include +.P +double rint(double \fIx\fP); +float rintf(float \fIx\fP); +long double rintl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall return the integral value (represented as a +.BR double ) +nearest +.IR x +in the direction of the current rounding mode. The current rounding +mode is implementation-defined. +.P +If the current rounding mode rounds toward negative infinity, then +\fIrint\fR() +shall be equivalent to +.IR "\fIfloor\fR\^(\|)". +If the current rounding mode rounds toward positive infinity, then +\fIrint\fR() +shall be equivalent to +.IR "\fIceil\fR\^(\|)". +If the current rounding mode rounds towards zero, then +\fIrint\fR() +shall be equivalent to +.IR "\fItrunc\fR\^(\|)". +If the current rounding mode rounds towards nearest, then +\fIrint\fR() +differs from +.IR "\fIround\fR\^(\|)" +in that halfway cases are rounded to even rather than away from zero. +.P +These functions differ from the +\fInearbyint\fR(), +\fInearbyintf\fR(), +and +\fInearbyintl\fR() +functions only in that they may raise the inexact floating-point +exception if the result differs in value from the argument. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the integer +(represented as a double precision number) nearest +.IR x +in the direction of the current rounding mode. +The result shall have the same sign as +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer type +to avoid the undefined results of an integer overflow. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIabs\fR\^(\|)", +.IR "\fIceil\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfloor\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fInearbyint\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/rmdir.3p b/man-pages-posix-2013-a/man3p/rmdir.3p new file mode 100644 index 0000000..614afa0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/rmdir.3p @@ -0,0 +1,267 @@ +'\" et +.TH RMDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rmdir +\(em remove a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int rmdir(const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIrmdir\fR() +function shall remove a directory whose name is given by +.IR path . +The directory shall be removed only if it is an empty directory. +.P +If the directory is the root directory or the current working directory +of any process, it is unspecified whether the function succeeds, or +whether it shall fail and set +.IR errno +to +.BR [EBUSY] . +.P +If +.IR path +names a symbolic link, then +\fIrmdir\fR() +shall fail and set +.IR errno +to +.BR [ENOTDIR] . +.P +If the +.IR path +argument refers to a path whose final component is either dot or +dot-dot, +\fIrmdir\fR() +shall fail. +.P +If the directory's link count becomes 0 and no process has the +directory open, the space occupied by the directory shall be freed and +the directory shall no longer be accessible. If one or more processes +have the directory open when the last link is removed, the dot and +dot-dot entries, if present, shall be removed before +\fIrmdir\fR() +returns and no new entries may be created in the directory, but the +directory shall not be removed until all references to the directory +are closed. +.P +If the directory is not an empty directory, +\fIrmdir\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] +or +.BR [ENOTEMPTY] . +.P +Upon successful completion, +\fIrmdir\fR() +shall mark for update the last data modification and last file status +change timestamps of the parent directory. +.SH "RETURN VALUE" +Upon successful completion, the function +\fIrmdir\fR() +shall return 0. Otherwise, \(mi1 shall be returned, and +.IR errno +set to indicate the error. If \(mi1 is returned, the named +directory shall not be changed. +.SH ERRORS +The +\fIrmdir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or write +permission is denied on the parent directory of the directory to be +removed. +.TP +.BR EBUSY +The directory to be removed is currently in use by the system or +some process and the implementation considers this to be an error. +.IP "[EEXIST]\ or\ [ENOTEMPTY]" 12 +.br +The +.IR path +argument names a directory that is not an empty directory, or there are +hard links to the directory other than dot or a single entry in +dot-dot. +.TP +.BR EINVAL +The +.IR path +argument contains a last component that is dot. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file, or the +.IR path +argument names a nonexistent directory or points to an empty string. +.TP +.BR ENOTDIR +A component of +.IR path +names an existing file that is neither a directory nor a symbolic link +to a directory. +.IP "[EPERM]\ or\ [EACCES]" 12 +.br +The S_ISVTX flag is set on the directory containing the file referred +to by the +.IR path +argument and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.2" ", " "Directory Protection". +.TP +.BR EROFS +The directory entry to be removed resides on a read-only file system. +.P +The +\fIrmdir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Removing a Directory" +.P +The following example shows how to remove a directory named +.BR /home/cnd/mod1 . +.sp +.RS 4 +.nf +\fB +#include +.P +int status; +\&... +status = rmdir("/home/cnd/mod1"); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIrmdir\fR() +and +\fIrename\fR() +functions originated in 4.2 BSD, and they used +.BR [ENOTEMPTY] +for the condition when the directory to be removed does not exist or +.IR new +already exists. When the 1984 /usr/group standard was published, it contained +.BR [EEXIST] +instead. When these functions were adopted into System V, the +1984 /usr/group standard was used as a reference. Therefore, several existing applications +and implementations support/use both forms, and no agreement could be +reached on either value. All implementations are required to supply +both +.BR [EEXIST] +and +.BR [ENOTEMPTY] +in +.IR +with distinct values, so that applications can use both values in +C-language +.BR case +statements. +.P +The meaning of deleting +.IR pathname \c +.BR /dot +is unclear, because the name of the file (directory) in the parent +directory to be removed is not clear, particularly in the presence of +multiple links to a directory. +.P +The POSIX.1\(hy1990 standard was silent with regard to the behavior of +\fIrmdir\fR() +when there are multiple hard links to the directory being removed. The +requirement to set +.IR errno +to +.BR [EEXIST] +or +.BR [ENOTEMPTY] +clarifies the behavior in this case. +.P +If the current working directory of the process is being removed, that +should be an allowed error. +.P +Virtually all existing implementations detect +.BR [ENOTEMPTY] +or the case of dot-dot. The text in +.IR "Section 2.3" ", " "Error Numbers" +about returning any one of the possible errors permits that behavior to +continue. The +.BR [ELOOP] +error may be returned if more than +{SYMLOOP_MAX} +symbolic links are encountered during resolution of the +.IR path +argument. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.3" ", " "Error Numbers", +.IR "\fImkdir\fR\^(\|)", +.IR "\fIremove\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.2" ", " "Directory Protection", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/round.3p b/man-pages-posix-2013-a/man3p/round.3p new file mode 100644 index 0000000..70cbb2f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/round.3p @@ -0,0 +1,88 @@ +'\" et +.TH ROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +round, +roundf, +roundl +\(em round to the nearest integer value in a floating-point format +.SH SYNOPSIS +.LP +.nf +#include +.P +double round(double \fIx\fP); +float roundf(float \fIx\fP); +long double roundl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer value +in floating-point format, rounding halfway cases away from zero, +regardless of the current rounding direction. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +The result shall have the same sign as +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer +type to avoid the undefined results of an integer overflow. +.P +These functions may raise the inexact floating-point exception if the +result differs in value from the argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/scalbln.3p b/man-pages-posix-2013-a/man3p/scalbln.3p new file mode 100644 index 0000000..bb6684c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/scalbln.3p @@ -0,0 +1,172 @@ +'\" et +.TH SCALBLN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +scalbln, +scalblnf, +scalblnl, +scalbn, +scalbnf, +scalbnl +\(em compute exponent using FLT_RADIX +.SH SYNOPSIS +.LP +.nf +#include +.P +double scalbln(double \fIx\fP, long \fIn\fP); +float scalblnf(float \fIx\fP, long \fIn\fP); +long double scalblnl(long double \fIx\fP, long \fIn\fP); +double scalbn(double \fIx\fP, int \fIn\fP); +float scalbnf(float \fIx\fP, int \fIn\fP); +long double scalbnl(long double \fIx\fP, int \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute \fIx\fR\ *\ FLT_RADIX\fI\s-3\un\d\s+3\fR +efficiently, not normally by computing FLT_RADIX\fI\s-3\un\d\s+3\fR +explicitly. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +\fIx\fR\ *\ FLT_RADIX\fI\s-3\un\d\s+3\fR. +.P +If the result would cause overflow, a range error shall occur and these +functions shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL +(according to the sign of +.IR x ) +as appropriate for the return type of the function. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIscalbln\fR(), +\fIscalblnf\fR(), +\fIscalblnl\fR(), +\fIscalbn\fR(), +\fIscalbnf\fR(), +and +\fIscalbnl\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, LDBL_MIN, DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.P +If +.IR n +is 0, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.br +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions are named so as to avoid conflicting with the +historical definition of the +.IR scalb (\|) +function from the Single UNIX Specification. The difference is that the +.IR scalb (\|) +function has a second argument of +.BR double +instead of +.BR int . +The +.IR scalb (\|) +function is not part of the ISO\ C standard. The three functions whose second +type is +.BR long +are provided because the factor required to scale from the smallest +positive floating-point value to the largest finite one, on many +implementations, is too large to represent in the minimum-width +.BR int +format. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/scandir.3p b/man-pages-posix-2013-a/man3p/scandir.3p new file mode 100644 index 0000000..9b74e5d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/scandir.3p @@ -0,0 +1,40 @@ +'\" et +.TH SCANDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +scandir +\(em scan a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int scandir(const char *\fIdir\fP, struct dirent ***\fInamelist\fP, + int (*\fIsel\fP)(const struct dirent *), + int (*\fIcompar\fP)(const struct dirent **, const struct dirent **)); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIalphasort\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/scanf.3p b/man-pages-posix-2013-a/man3p/scanf.3p new file mode 100644 index 0000000..489ae6b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/scanf.3p @@ -0,0 +1,38 @@ +'\" et +.TH SCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +scanf +\(em convert formatted input +.SH SYNOPSIS +.LP +.nf +#include +.P +int scanf(const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfscanf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sched_get_priority_max.3p b/man-pages-posix-2013-a/man3p/sched_get_priority_max.3p new file mode 100644 index 0000000..a13261a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sched_get_priority_max.3p @@ -0,0 +1,93 @@ +'\" et +.TH SCHED_GET_PRIORITY_MAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sched_get_priority_max, +sched_get_priority_min +\(em get priority limits +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_get_priority_max(int \fIpolicy\fP); +int sched_get_priority_min(int \fIpolicy\fP); +.fi +.SH DESCRIPTION +The +\fIsched_get_priority_max\fR() +and +\fIsched_get_priority_min\fR() +functions shall return the appropriate maximum or minimum, +respectively, for the scheduling policy specified by +.IR policy . +.P +The value of +.IR policy +shall be one of the scheduling policy values defined in +.IR . +.SH "RETURN VALUE" +If successful, the +\fIsched_get_priority_max\fR() +and +\fIsched_get_priority_min\fR() +functions shall return the appropriate maximum or minimum values, +respectively. If unsuccessful, they shall return a value of \(mi1 and +set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_get_priority_max\fR() +and +\fIsched_get_priority_min\fR() +functions shall fail if: +.TP +.BR EINVAL +The value of the +.IR policy +parameter does not represent a defined scheduling policy. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_rr_get_interval\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sched_getparam.3p b/man-pages-posix-2013-a/man3p/sched_getparam.3p new file mode 100644 index 0000000..50c354f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sched_getparam.3p @@ -0,0 +1,98 @@ +'\" et +.TH SCHED_GETPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sched_getparam +\(em get scheduling parameters +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_getparam(pid_t \fIpid\fP, struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIsched_getparam\fR() +function shall return the scheduling parameters of a process specified by +.IR pid +in the +.BR sched_param +structure pointed to by +.IR param . +.P +If a process specified by +.IR pid +exists, and if the calling process has permission, the scheduling +parameters for the process whose process ID is equal to +.IR pid +shall be returned. +.P +If +.IR pid +is zero, the scheduling parameters for the calling process shall be +returned. The behavior of the +\fIsched_getparam\fR() +function is unspecified if the value of +.IR pid +is negative. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsched_getparam\fR() +function shall return zero. If the call to +\fIsched_getparam\fR() +is unsuccessful, the function shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_getparam\fR() +function shall fail if: +.TP +.BR EPERM +The requesting process does not have permission to obtain the +scheduling parameters of the specified process. +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sched_getscheduler.3p b/man-pages-posix-2013-a/man3p/sched_getscheduler.3p new file mode 100644 index 0000000..ff248f3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sched_getscheduler.3p @@ -0,0 +1,98 @@ +'\" et +.TH SCHED_GETSCHEDULER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sched_getscheduler +\(em get scheduling policy +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_getscheduler(pid_t \fIpid\fP); +.fi +.SH DESCRIPTION +The +\fIsched_getscheduler\fR() +function shall return the scheduling policy of the process specified by +.IR pid . +If the value of +.IR pid +is negative, the behavior of the +\fIsched_getscheduler\fR() +function is unspecified. +.P +The values that can be returned by +\fIsched_getscheduler\fR() +are defined in the +.IR +header. +.P +If a process specified by +.IR pid +exists, and if the calling process has permission, the scheduling +policy shall be returned for the process whose process ID is equal to +.IR pid . +.P +If +.IR pid +is zero, the scheduling policy shall be returned for the calling process. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsched_getscheduler\fR() +function shall return the scheduling policy of the specified process. +If unsuccessful, the function shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_getscheduler\fR() +function shall fail if: +.TP +.BR EPERM +The requesting process does not have permission to determine the +scheduling policy of the specified process. +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sched_rr_get_interval.3p b/man-pages-posix-2013-a/man3p/sched_rr_get_interval.3p new file mode 100644 index 0000000..494a867 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sched_rr_get_interval.3p @@ -0,0 +1,86 @@ +'\" et +.TH SCHED_RR_GET_INTERVAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sched_rr_get_interval +\(em get execution time limits +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_rr_get_interval(pid_t \fIpid\fP, struct timespec *\fIinterval\fP); +.fi +.SH DESCRIPTION +The +\fIsched_rr_get_interval\fR() +function shall update the +.BR timespec +structure referenced by the +.IR interval +argument to contain the current execution time limit (that is, time +quantum) for the process specified by +.IR pid . +If +.IR pid +is zero, the current execution time limit for the calling process +shall be returned. +.SH "RETURN VALUE" +If successful, the +\fIsched_rr_get_interval\fR() +function shall return zero. Otherwise, it shall return a value of +\(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_rr_get_interval\fR() +function shall fail if: +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_get_priority_max\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sched_setparam.3p b/man-pages-posix-2013-a/man3p/sched_setparam.3p new file mode 100644 index 0000000..f3056d0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sched_setparam.3p @@ -0,0 +1,157 @@ +'\" et +.TH SCHED_SETPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sched_setparam +\(em set scheduling parameters +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_setparam(pid_t \fIpid\fP, const struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIsched_setparam\fR() +function shall set the scheduling parameters of the process specified by +.IR pid +to the values specified by the +.BR sched_param +structure pointed to by +.IR param . +The value of the +.IR sched_priority +member in the +.BR sched_param +structure shall be any integer within the inclusive priority range for +the current scheduling policy of the process specified by +.IR pid . +Higher numerical values for the priority represent higher priorities. +If the value of +.IR pid +is negative, the behavior of the +\fIsched_setparam\fR() +function is unspecified. +.P +If a process specified by +.IR pid +exists, and if the calling process has permission, the scheduling +parameters shall be set for the process whose process ID is equal to +.IR pid . +.P +If +.IR pid +is zero, the scheduling parameters shall be set for the calling process. +.P +The conditions under which one process has permission to change the +scheduling parameters of another process are implementation-defined. +.P +Implementations may require the requesting process to have appropriate +privileges to set its own scheduling parameters or those of another +process. +.P +See +.IR "Scheduling Policies" +for a description on how this function affects the scheduling of +the threads within the target process. +.P +If the current scheduling policy for the target process is not +SCHED_FIFO, SCHED_RR, +or SCHED_SPORADIC, +the result is implementation-defined; this case includes the +SCHED_OTHER policy. +.P +The specified +.IR sched_ss_repl_period +shall be greater than or equal to the specified +.IR sched_ss_init_budget +for the function to succeed; if it is not, then the function shall +fail. +.P +The value of +.IR sched_ss_max_repl +shall be within the inclusive range [1,{SS_REPL_MAX}] for the function +to succeed; if not, the function shall fail. It is unspecified whether the +.IR sched_ss_repl_period +and +.IR sched_ss_init_budget +values are stored as provided by this function or are rounded to +align with the resolution of the clock being used. +.P +This function is not atomic with respect to other threads in the +process. Threads may continue to execute while this function call is in +the process of changing the scheduling policy for the underlying +kernel-scheduled entities used by the process contention scope +threads. +.SH "RETURN VALUE" +If successful, the +\fIsched_setparam\fR() +function shall return zero. +.P +If the call to +\fIsched_setparam\fR() +is unsuccessful, the priority shall remain unchanged, and the function +shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_setparam\fR() +function shall fail if: +.TP +.BR EINVAL +One or more of the requested scheduling parameters is outside the range +defined for the scheduling policy of the specified +.IR pid . +.TP +.BR EPERM +The requesting process does not have permission to set the scheduling +parameters for the specified process, or does not have appropriate +privileges to invoke +\fIsched_setparam\fR(). +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Scheduling Policies", +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sched_setscheduler.3p b/man-pages-posix-2013-a/man3p/sched_setscheduler.3p new file mode 100644 index 0000000..2d6bf0a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sched_setscheduler.3p @@ -0,0 +1,182 @@ +'\" et +.TH SCHED_SETSCHEDULER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sched_setscheduler +\(em set scheduling policy and parameters +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_setscheduler(pid_t \fIpid\fP, int \fIpolicy\fP, + const struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIsched_setscheduler\fR() +function shall set the scheduling policy and scheduling parameters +of the process specified by +.IR pid +to +.IR policy +and the parameters specified in the +.BR sched_param +structure pointed to by +.IR param , +respectively. The value of the +.IR sched_priority +member in the +.BR sched_param +structure shall be any integer within the inclusive priority range +for the scheduling policy specified by +.IR policy . +If the value of +.IR pid +is negative, the behavior of the +\fIsched_setscheduler\fR() +function is unspecified. +.P +The possible values for the +.IR policy +parameter are defined in the +.IR +header. +.P +If a process specified by +.IR pid +exists, and if the calling process has permission, the scheduling +policy and scheduling parameters shall be set for the process whose +process ID is equal to +.IR pid . +.P +If +.IR pid +is zero, the scheduling policy and scheduling parameters shall be +set for the calling process. +.P +The conditions under which one process has appropriate privileges to +change the scheduling parameters of another process are +implementation-defined. +.P +Implementations may require that the requesting process have permission +to set its own scheduling parameters or those of another process. +Additionally, implementation-defined restrictions may apply as to the +appropriate privileges required to set the scheduling +policy of the process, or the scheduling policy of another process, +to a particular value. +.P +The +\fIsched_setscheduler\fR() +function shall be considered successful if it succeeds in setting the +scheduling policy and scheduling parameters of the process specified by +.IR pid +to the values specified by +.IR policy +and the structure pointed to by +.IR param , +respectively. +.P +See +.IR "Scheduling Policies" +for a description on how this function affects the scheduling of the +threads within the target process. +.P +If the current scheduling policy for the target process is not +SCHED_FIFO, SCHED_RR, +or SCHED_SPORADIC, +the result is implementation-defined; this case includes the +SCHED_OTHER policy. +.P +The specified +.IR sched_ss_repl_period +shall be greater than or equal to the specified +.IR sched_ss_init_budget +for the function to succeed; if it is not, then the function shall +fail. +.P +The value of +.IR sched_ss_max_repl +shall be within the inclusive range [1,{SS_REPL_MAX}] for the function +to succeed; if not, the function shall fail. It is unspecified whether the +.IR sched_ss_repl_period +and +.IR sched_ss_init_budget +values are stored as provided by this function or are rounded to +align with the resolution of the clock being used. +.P +This function is not atomic with respect to other threads in the +process. Threads may continue to execute while this function call is in +the process of changing the scheduling policy and associated scheduling +parameters for the underlying kernel-scheduled entities used by the +process contention scope threads. +.SH "RETURN VALUE" +Upon successful completion, the function shall return the former +scheduling policy of the specified process. If the +\fIsched_setscheduler\fR() +function fails to complete successfully, the policy and scheduling +parameters shall remain unchanged, and the function shall return a +value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_setscheduler\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR policy +parameter is invalid, or one or more of the parameters contained in +.IR param +is outside the valid range for the specified scheduling policy. +.TP +.BR EPERM +The requesting process does not have permission to set either or both +of the scheduling parameters or the scheduling policy of the specified +process. +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Scheduling Policies", +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sched_yield.3p b/man-pages-posix-2013-a/man3p/sched_yield.3p new file mode 100644 index 0000000..affc53c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sched_yield.3p @@ -0,0 +1,67 @@ +'\" et +.TH SCHED_YIELD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sched_yield +\(em yield the processor +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_yield(void); +.fi +.SH DESCRIPTION +The +\fIsched_yield\fR() +function shall force the running thread to relinquish the processor +until it again becomes the head of its thread list. It takes no arguments. +.SH "RETURN VALUE" +The +\fIsched_yield\fR() +function shall return 0 if it completes successfully; otherwise, it +shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The conceptual model for scheduling semantics in POSIX.1\(hy2008 defines +a set of thread lists. This set of thread lists is always present +regardless of the scheduling options supported by the system. On a +system where the Process Scheduling option is not supported, portable +applications should not make any assumptions regarding whether threads +from other processes will be on the same thread list. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/seed48.3p b/man-pages-posix-2013-a/man3p/seed48.3p new file mode 100644 index 0000000..876b529 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/seed48.3p @@ -0,0 +1,39 @@ +'\" et +.TH SEED48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +seed48 +\(em seed a uniformly distributed pseudo-random non-negative +long integer generator +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned short *seed48(unsigned short \fIseed16v\fP[3]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/seekdir.3p b/man-pages-posix-2013-a/man3p/seekdir.3p new file mode 100644 index 0000000..5428a14 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/seekdir.3p @@ -0,0 +1,117 @@ +'\" et +.TH SEEKDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +seekdir +\(em set the position of a directory stream +.SH SYNOPSIS +.LP +.nf +#include +.P +void seekdir(DIR *\fIdirp\fP, long \fIloc\fP); +.fi +.SH DESCRIPTION +The +\fIseekdir\fR() +function shall set the position of the next +\fIreaddir\fR() +operation on the directory stream specified by +.IR dirp +to the position specified by +.IR loc . +The value of +.IR loc +should have been returned from an earlier call to +\fItelldir\fR() +using the same directory stream. The new position reverts to the one +associated with the directory stream when +\fItelldir\fR() +was performed. +.P +If the value of +.IR loc +was not obtained from an earlier call to +\fItelldir\fR(), +or if a call to +\fIrewinddir\fR() +occurred between the call to +\fItelldir\fR() +and the call to +\fIseekdir\fR(), +the results of subsequent calls to +\fIreaddir\fR() +are unspecified. +.SH "RETURN VALUE" +The +\fIseekdir\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The original standard developers perceived that there were restrictions +on the use of the +\fIseekdir\fR() +and +\fItelldir\fR() +functions related to implementation details, and for that reason these +functions need not be supported on all POSIX-conforming systems. They +are required on implementations supporting the XSI option. +.P +One of the perceived problems of implementation is that returning to a +given point in a directory is quite difficult to describe formally, in +spite of its intuitive appeal, when systems that use B-trees, hashing +functions, or other similar mechanisms to order their directories are +considered. The definition of +\fIseekdir\fR() +and +\fItelldir\fR() +does not specify whether, when using these interfaces, a given +directory entry will be seen at all, or more than once. +.P +On systems not supporting these functions, their capability can +sometimes be accomplished by saving a filename found by +\fIreaddir\fR() +and later using +\fIrewinddir\fR() +and a loop on +\fIreaddir\fR() +to relocate the position from which the filename was saved. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fItelldir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/select.3p b/man-pages-posix-2013-a/man3p/select.3p new file mode 100644 index 0000000..f63c3ad --- /dev/null +++ b/man-pages-posix-2013-a/man3p/select.3p @@ -0,0 +1,40 @@ +'\" et +.TH SELECT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +select +\(em synchronous I/O multiplexing +.SH SYNOPSIS +.LP +.nf +#include +.P +int select(int \fInfds\fP, fd_set *restrict \fIreadfds\fP, + fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP, + struct timeval *restrict \fItimeout\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpselect\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_close.3p b/man-pages-posix-2013-a/man3p/sem_close.3p new file mode 100644 index 0000000..e7c0e31 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_close.3p @@ -0,0 +1,102 @@ +'\" et +.TH SEM_CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_close +\(em close a named semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_close(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +The +\fIsem_close\fR() +function shall indicate that the calling process is finished using +the named semaphore indicated by +.IR sem . +The effects of calling +\fIsem_close\fR() +for an unnamed semaphore (one created by +\fIsem_init\fR()) +are undefined. The +\fIsem_close\fR() +function shall deallocate (that is, make available for reuse by a +subsequent +\fIsem_open\fR() +by this process) any system resources allocated by the system for use +by this process for this semaphore. The effect of subsequent use of the +semaphore indicated by +.IR sem +by this process is undefined. If the semaphore has not been removed +with a successful call to +\fIsem_unlink\fR(), +then +\fIsem_close\fR() +has no effect on the state of the semaphore. If the +\fIsem_unlink\fR() +function has been successfully invoked for +.IR name +after the most recent call to +\fIsem_open\fR() +with O_CREAT for this semaphore, +then when all processes that have opened the semaphore close it, the +semaphore is no longer accessible. +.SH "RETURN VALUE" +Upon successful completion, a value of zero shall be returned. +Otherwise, a value of \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsem_close\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR sem +argument is not a valid semaphore descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_destroy.3p b/man-pages-posix-2013-a/man3p/sem_destroy.3p new file mode 100644 index 0000000..0f54616 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_destroy.3p @@ -0,0 +1,93 @@ +'\" et +.TH SEM_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_destroy +\(em destroy an unnamed semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_destroy(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +The +\fIsem_destroy\fR() +function shall destroy the unnamed semaphore indicated by +.IR sem . +Only a semaphore that was created using +\fIsem_init\fR() +may be destroyed using +\fIsem_destroy\fR(); +the effect of calling +\fIsem_destroy\fR() +with a named semaphore is undefined. The effect of subsequent use of +the semaphore +.IR sem +is undefined until +.IR sem +is reinitialized by another call to +\fIsem_init\fR(). +.P +It is safe to destroy an initialized semaphore upon which no threads +are currently blocked. The effect of destroying a semaphore upon which +other threads are currently blocked is undefined. +.SH "RETURN VALUE" +Upon successful completion, a value of zero shall be returned. Otherwise, +a value of \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsem_destroy\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR sem +argument is not a valid semaphore. +.TP +.BR EBUSY +There are currently processes blocked on the semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_getvalue.3p b/man-pages-posix-2013-a/man3p/sem_getvalue.3p new file mode 100644 index 0000000..bd5f1b3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_getvalue.3p @@ -0,0 +1,90 @@ +'\" et +.TH SEM_GETVALUE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_getvalue +\(em get the value of a semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_getvalue(sem_t *restrict \fIsem\fP, int *restrict \fIsval\fP); +.fi +.SH DESCRIPTION +The +\fIsem_getvalue\fR() +function shall update the location referenced by the +.IR sval +argument to have the value of the semaphore referenced by +.IR sem +without affecting the state of the semaphore. The updated value +represents an actual semaphore value that occurred at some unspecified +time during the call, but it need not be the actual value of the +semaphore when it is returned to the calling process. +.P +If +.IR sem +is locked, then the object to which +.IR sval +points shall either be set to zero or to a negative number whose +absolute value represents the number of processes waiting for the +semaphore at some unspecified time during the call. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsem_getvalue\fR() +function shall return a value of zero. Otherwise, it shall return +a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_getvalue\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR sem +argument does not refer to a valid semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_init.3p b/man-pages-posix-2013-a/man3p/sem_init.3p new file mode 100644 index 0000000..cc2445c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_init.3p @@ -0,0 +1,146 @@ +'\" et +.TH SEM_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_init +\(em initialize an unnamed semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_init(sem_t *\fIsem\fP, int \fIpshared\fP, unsigned \fIvalue\fP); +.fi +.SH DESCRIPTION +The +\fIsem_init\fR() +function shall initialize the unnamed semaphore referred to by +.IR sem . +The value of the initialized semaphore shall be +.IR value . +Following a successful call to +\fIsem_init\fR(), +the semaphore may be used in subsequent calls to +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_destroy\fR(). +This semaphore shall remain usable until the semaphore is destroyed. +.P +If the +.IR pshared +argument has a non-zero value, then the semaphore is shared between +processes; in this case, any process that can access the semaphore +.IR sem +can use +.IR sem +for performing +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_destroy\fR() +operations. +.P +Only +.IR sem +itself may be used for performing synchronization. The result of +referring to copies of +.IR sem +in calls to +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_destroy\fR() +is undefined. +.P +If the +.IR pshared +argument is zero, then the semaphore is shared between threads of the +process; any thread in this process can use +.IR sem +for performing +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_destroy\fR() +operations. The use of the semaphore by threads other than those +created in the same process is undefined. +.P +Attempting to initialize an already initialized semaphore results in +undefined behavior. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsem_init\fR() +function shall initialize the semaphore in +.IR sem +and return 0. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_init\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR value +argument exceeds +{SEM_VALUE_MAX}. +.TP +.BR ENOSPC +A resource required to initialize the semaphore has been exhausted, or +the limit on semaphores (\c +{SEM_NSEMS_MAX}) +has been reached. +.TP +.BR EPERM +The process lacks appropriate privileges to initialize the +semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_open.3p b/man-pages-posix-2013-a/man3p/sem_open.3p new file mode 100644 index 0000000..ece10ec --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_open.3p @@ -0,0 +1,296 @@ +'\" et +.TH SEM_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_open +\(em initialize and open a named semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +sem_t *sem_open(const char *\fIname\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +The +\fIsem_open\fR() +function shall establish a connection between a named semaphore +and a process. Following a call to +\fIsem_open\fR() +with semaphore name +.IR name , +the process may reference the semaphore associated with +.IR name +using the address returned from the call. This semaphore may be used +in subsequent calls to +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_close\fR(). +The semaphore remains usable by this process until the semaphore is +closed by a successful call to +\fIsem_close\fR(), +\fI_exit\fR(), +or one of the +.IR exec +functions. +.P +The +.IR oflag +argument controls whether the semaphore is created or merely accessed +by the call to +\fIsem_open\fR(). +The following flag bits may be set in +.IR oflag : +.IP O_CREAT 10 +This flag is used to create a semaphore if it does not already exist. +If O_CREAT is set and the semaphore already exists, then O_CREAT has no +effect, except as noted under O_EXCL. Otherwise, +\fIsem_open\fR() +creates a named semaphore. The O_CREAT flag requires a third and a +fourth argument: +.IR mode , +which is of type +.BR mode_t , +and +.IR value , +which is of type +.BR unsigned . +The semaphore is created with an initial value of +.IR value . +Valid initial values for semaphores are less than or equal to +{SEM_VALUE_MAX}. +.RS 10 +.P +The user ID of the semaphore shall be set to the effective user ID of +the process. The group ID of the semaphore shall be set to the effective +group ID of the process; however, if the +.IR name +argument is visible in the file system, the group ID may be set to +the group ID of the containing directory. The permission bits of the +semaphore are set to the value of the +.IR mode +argument except those set in the file mode creation mask of the +process. When bits in +.IR mode +other than the file permission bits are specified, the effect is +unspecified. +.P +After the semaphore named +.IR name +has been created by +\fIsem_open\fR() +with the O_CREAT flag, other processes can connect to the semaphore by +calling +\fIsem_open\fR() +with the same value of +.IR name . +.RE +.IP O_EXCL 10 +If O_EXCL and O_CREAT are set, +\fIsem_open\fR() +fails if the semaphore +.IR name +exists. The check for the existence of the semaphore and the creation +of the semaphore if it does not exist are atomic with respect to other +processes executing +\fIsem_open\fR() +with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, +the effect is undefined. +.RS 10 +.P +If flags other than O_CREAT and O_EXCL are specified in the +.IR oflag +parameter, the effect is unspecified. +.RE +.P +The +.IR name +argument points to a string naming a semaphore object. It is +unspecified whether the name appears in the file system and is visible +to functions that take pathnames as arguments. The +.IR name +argument conforms to the construction rules for a pathname, except +that the interpretation of + +characters other than the leading + +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as +the pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the + +character, then processes calling +\fIsem_open\fR() +with the same value of +.IR name +shall refer to the same semaphore object, as long as that name has not +been removed. If +.IR name +does not begin with the + +character, the effect is implementation-defined. +.P +If a process makes multiple successful calls to +\fIsem_open\fR() +with the same value for +.IR name , +the same semaphore address shall be returned for each such successful +call, provided that there have been no calls to +\fIsem_unlink\fR() +for this semaphore, and at least one previous successful +\fIsem_open\fR() +call for this semaphore has not been matched with a +\fIsem_close\fR() +call. +.P +References to copies of the semaphore produce undefined results. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsem_open\fR() +function shall return the address of the semaphore. Otherwise, it +shall return a value of SEM_FAILED and set +.IR errno +to indicate the error. The symbol SEM_FAILED is defined in the +.IR +header. No successful return from +\fIsem_open\fR() +shall return the value SEM_FAILED. +.SH ERRORS +If any of the following conditions occur, the +\fIsem_open\fR() +function shall return SEM_FAILED and set +.IR errno +to the corresponding value: +.TP +.BR EACCES +The named semaphore exists and the permissions specified by +.IR oflag +are denied, or the named semaphore does not exist and permission to +create the named semaphore is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set and the named semaphore already exists. +.TP +.BR EINTR +The +\fIsem_open\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +The +\fIsem_open\fR() +operation is not supported for the given name, or O_CREAT was specified +in +.IR oflag +and +.IR value +was greater than +{SEM_VALUE_MAX}. +.TP +.BR EMFILE +Too many semaphore descriptors or file descriptors are currently in use +by this process. +.TP +.BR ENFILE +Too many semaphores are currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and the named semaphore does not exist. +.TP +.BR ENOMEM +There is insufficient memory for the creation of the new named +semaphore. +.TP +.BR ENOSPC +There is insufficient space on a storage device for the creation of the +new named semaphore. +.P +If any of the following conditions occur, the +\fIsem_open\fR() +function may return SEM_FAILED and set +.IR errno +to the corresponding value: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Early drafts required an error return value of \(mi1 with the type +.BR "sem_t *" +for the +\fIsem_open\fR() +function, which is not guaranteed to be portable across +implementations. The revised text provides the symbolic error code +SEM_FAILED to eliminate the type conflict. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fIsem_open\fR() +and +\fIsem_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.ad l +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_post.3p b/man-pages-posix-2013-a/man3p/sem_post.3p new file mode 100644 index 0000000..f731e7d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_post.3p @@ -0,0 +1,104 @@ +'\" et +.TH SEM_POST "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_post +\(em unlock a semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_post(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +The +\fIsem_post\fR() +function shall unlock the semaphore referenced by +.IR sem +by performing a semaphore unlock operation on that semaphore. +.P +If the semaphore value resulting from this operation is positive, then +no threads were blocked waiting for the semaphore to become unlocked; +the semaphore value is simply incremented. +.P +If the value of the semaphore resulting from this operation is zero, +then one of the threads blocked waiting for the semaphore shall be +allowed to return successfully from its call to +\fIsem_wait\fR(). +If the Process Scheduling option is supported, the thread to be +unblocked shall be chosen in a manner appropriate to the scheduling +policies and parameters in effect for the blocked threads. In the case +of the schedulers SCHED_FIFO and SCHED_RR, +the highest priority waiting thread shall be unblocked, and if there is +more than one highest priority thread blocked waiting for the +semaphore, then the highest priority thread that has been waiting the +longest shall be unblocked. If the Process Scheduling option is not +defined, the choice of a thread to unblock is unspecified. +.P +If the Process Sporadic Server option is supported, and the scheduling +policy is SCHED_SPORADIC, the semantics are as per SCHED_FIFO above. +.P +The +\fIsem_post\fR() +function shall be async-signal-safe and may be invoked from a +signal-catching function. +.SH "RETURN VALUE" +If successful, the +\fIsem_post\fR() +function shall return zero; otherwise, the function shall return \(mi1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_post\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR sem +argument does not refer to a valid semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +See +.IR "\fIsem_timedwait\fR\^(\|)". +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_timedwait.3p b/man-pages-posix-2013-a/man3p/sem_timedwait.3p new file mode 100644 index 0000000..ee894bf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_timedwait.3p @@ -0,0 +1,231 @@ +'\" et +.TH SEM_TIMEDWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_timedwait +\(em lock a semaphore +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int sem_timedwait(sem_t *restrict \fIsem\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fIsem_timedwait\fR() +function shall lock the semaphore referenced by +.IR sem +as in the +\fIsem_wait\fR() +function. However, if the semaphore cannot be locked without waiting +for another process or thread to unlock the semaphore by performing a +\fIsem_post\fR() +function, this wait shall be terminated when the specified timeout +expires. +.P +The timeout shall expire when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the +clock on which it is based. The +.BR timespec +data type is defined as a structure in the +.IR +header. +.P +Under no circumstance shall the function fail with a timeout if the +semaphore can be locked immediately. The validity of the +.IR abstime +need not be checked if the semaphore can be locked immediately. +.SH "RETURN VALUE" +The +\fIsem_timedwait\fR() +function shall return zero if the calling process successfully +performed the semaphore lock operation on the semaphore designated by +.IR sem . +If the call was unsuccessful, the state of the semaphore shall be +unchanged, and the function shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_timedwait\fR() +function shall fail if: +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR ETIMEDOUT +The semaphore could not be locked before the specified timeout expired. +.P +The +\fIsem_timedwait\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.TP +.BR EINTR +A signal interrupted this function. +.TP +.BR EINVAL +The +.IR sem +argument does not refer to a valid semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The program shown below operates on an unnamed semaphore. The program +expects two command-line arguments. The first argument specifies a +seconds value that is used to set an alarm timer to generate a SIGALRM +signal. This handler performs a +.IR sem_post (3) +to increment the semaphore that is being waited on in +\fImain\fR() +using +\fIsem_timedwait\fR(). +The second command-line argument specifies the length of the timeout, +in seconds, for +\fIsem_timedwait\fR(). +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +#include +#include +.P +sem_t sem; +.P +static void +handler(int sig) +{ + int sav_errno = errno; + static const char info_msg[] = "sem_post() from handler\en"; + write(STDOUT_FILENO, info_msg, sizeof info_msg - 1); + if (sem_post(&sem) == -1) { + static const char err_msg[] = "sem_post() failed\en"; + write(STDERR_FILENO, err_msg, sizeof err_msg - 1); + _exit(EXIT_FAILURE); + } + errno = sav_errno; +} +.P +int +main(int argc, char *argv[]) +{ + struct sigaction sa; + struct timespec ts; + int s; +.P + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", + argv[0]); + exit(EXIT_FAILURE); + } +.P + if (sem_init(&sem, 0, 0) == -1) { + perror("sem_init"); + exit(EXIT_FAILURE); + } +.P + /* Establish SIGALRM handler; set alarm timer using argv[1] */ +.P + sa.sa_handler = handler; + sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + if (sigaction(SIGALRM, &sa, NULL) == -1) { + perror("sigaction"); + exit(EXIT_FAILURE); + } +.P + alarm(atoi(argv[1])); +.P + /* Calculate relative interval as current time plus + number of seconds given argv[2] */ +.P + if (clock_gettime(CLOCK_REALTIME, &ts) == -1) { + perror("clock_gettime"); + exit(EXIT_FAILURE); + } + ts.tv_sec += atoi(argv[2]); +.P + printf("main() about to call sem_timedwait()\en"); + while ((s = sem_timedwait(&sem, &ts)) == -1 && errno == EINTR) + continue; /* Restart if interrupted by handler */ +.P + /* Check what happened */ +.P + if (s == -1) { + if (errno == ETIMEDOUT) + printf("sem_timedwait() timed out\en"); + else + perror("sem_timedwait"); + } else + printf("sem_timedwait() succeeded\en"); +.P + exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority +inversion, as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_trywait.3p b/man-pages-posix-2013-a/man3p/sem_trywait.3p new file mode 100644 index 0000000..5dfbf15 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_trywait.3p @@ -0,0 +1,127 @@ +'\" et +.TH SEM_TRYWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_trywait, +sem_wait +\(em lock a semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_trywait(sem_t *\fIsem\fP); +int sem_wait(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +The +\fIsem_trywait\fR() +function shall lock the semaphore referenced by +.IR sem +only if the semaphore is currently not locked; that is, if the +semaphore value is currently positive. Otherwise, it shall not lock +the semaphore. +.P +The +\fIsem_wait\fR() +function shall lock the semaphore referenced by +.IR sem +by performing a semaphore lock operation on that semaphore. If the +semaphore value is currently zero, then the calling thread shall not +return from the call to +\fIsem_wait\fR() +until it either locks the semaphore or the call is interrupted by a +signal. +.P +Upon successful return, the state of the semaphore shall be locked and +shall remain locked until the +\fIsem_post\fR() +function is executed and returns successfully. +.P +The +\fIsem_wait\fR() +function is interruptible by the delivery of a signal. +.SH "RETURN VALUE" +The +\fIsem_trywait\fR() +and +\fIsem_wait\fR() +functions shall return zero if the calling process successfully +performed the semaphore lock operation on the semaphore designated by +.IR sem . +If the call was unsuccessful, the state of the semaphore shall be +unchanged, and the function shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_trywait\fR() +function shall fail if: +.TP +.BR EAGAIN +The semaphore was already locked, so it cannot be immediately locked by +the +\fIsem_trywait\fR() +operation. +.P +The +\fIsem_trywait\fR() +and +\fIsem_wait\fR() +functions may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.TP +.BR EINTR +A signal interrupted this function. +.TP +.BR EINVAL +The +.IR sem +argument does not refer to a valid semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_unlink.3p b/man-pages-posix-2013-a/man3p/sem_unlink.3p new file mode 100644 index 0000000..4e14310 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_unlink.3p @@ -0,0 +1,133 @@ +'\" et +.TH SEM_UNLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_unlink +\(em remove a named semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_unlink(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fIsem_unlink\fR() +function shall remove the semaphore named by the string +.IR name . +If the semaphore named by +.IR name +is currently referenced by other processes, then +\fIsem_unlink\fR() +shall have no effect on the state of the semaphore. If one or more +processes have the semaphore open when +\fIsem_unlink\fR() +is called, destruction of the semaphore is postponed until all +references to the semaphore have been destroyed by calls to +\fIsem_close\fR(), +\fI_exit\fR(), +or +.IR exec . +Calls to +\fIsem_open\fR() +to recreate or reconnect to the semaphore refer to a new semaphore +after +\fIsem_unlink\fR() +is called. The +\fIsem_unlink\fR() +call shall not block until all references have been destroyed; it +shall return immediately. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsem_unlink\fR() +function shall return a value of 0. Otherwise, the semaphore shall not +be changed and the function shall return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_unlink\fR() +function shall fail if: +.TP +.BR EACCES +Permission is denied to unlink the named semaphore. +.TP +.BR ENOENT +The named semaphore does not exist. +.P +The +\fIsem_unlink\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +A call to +\fIsem_unlink\fR() +with a +.IR name +argument that contains the same semaphore name as was previously used +in a successful +\fIsem_open\fR() +call shall not give an +.BR [ENAMETOOLONG] +error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fIsem_open\fR() +and +\fIsem_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sem_wait.3p b/man-pages-posix-2013-a/man3p/sem_wait.3p new file mode 100644 index 0000000..0346657 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sem_wait.3p @@ -0,0 +1,38 @@ +'\" et +.TH SEM_WAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sem_wait +\(em lock a semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_wait(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsem_trywait\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/semctl.3p b/man-pages-posix-2013-a/man3p/semctl.3p new file mode 100644 index 0000000..c71c238 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/semctl.3p @@ -0,0 +1,336 @@ +'\" et +.TH SEMCTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +semctl +\(em XSI semaphore control operations +.SH SYNOPSIS +.LP +.nf +#include\ +.P +int semctl(int \fIsemid\fP, int \fIsemnum\fP, int \fIcmd\fP, ...); +.fi +.SH DESCRIPTION +The +\fIsemctl\fR() +function operates on XSI semaphores (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.16" ", " "Semaphore"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIsemctl\fR() +function provides a variety of semaphore control operations as +specified by +.IR cmd . +The fourth argument is optional and depends upon the operation +requested. If required, it is of type +.BR "union semun" , +which the application shall explicitly declare: +.sp +.RS 4 +.nf +\fB +union semun { + int val; + struct semid_ds *buf; + unsigned short *array; +} arg; +.fi \fR +.P +.RE +.P +The following semaphore control operations as specified by +.IR cmd +are executed with respect to the semaphore specified by +.IR semid +and +.IR semnum . +The level of permission required for each operation is shown with each +command; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +The symbolic names for the values of +.IR cmd +are defined in the +.IR +header: +.IP GETVAL 12 +Return the value of +.IR semval ; +see +.IR . +Requires read permission. +.IP SETVAL 12 +Set the value of +.IR semval +to +.IR arg.val , +where +.IR arg +is the value of the fourth argument to +\fIsemctl\fR(). +When this command is successfully executed, the +.IR semadj +value corresponding to the specified semaphore in all processes is +cleared. Also, the +.IR sem_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +Requires alter permission; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.IP GETPID 12 +Return the value of +.IR sempid . +Requires read permission. +.IP GETNCNT 12 +Return the value of +.IR semncnt . +Requires read permission. +.IP GETZCNT 12 +Return the value of +.IR semzcnt . +Requires read permission. +.P +The following values of +.IR cmd +operate on each +.IR semval +in the set of semaphores: +.IP GETALL 12 +Return the value of +.IR semval +for each semaphore in the semaphore set and place into the array +pointed to by +.IR arg.array , +where +.IR arg +is the fourth argument to +\fIsemctl\fR(). +Requires read permission. +.IP SETALL 12 +Set the value of +.IR semval +for each semaphore in the semaphore set according to the array pointed +to by +.IR arg.array , +where +.IR arg +is the fourth argument to +\fIsemctl\fR(). +When this command is successfully executed, the +.IR semadj +values corresponding to each specified semaphore in all processes are +cleared. Also, the +.IR sem_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +Requires alter permission. +.br +.P +The following values of +.IR cmd +are also available: +.IP IPC_STAT 12 +Place the current value of each member of the +.BR semid_ds +data structure associated with +.IR semid +into the structure pointed to by +.IR arg.buf , +where +.IR arg +is the fourth argument to +\fIsemctl\fR(). +The contents of this structure are defined in +.IR . +Requires read permission. +.IP IPC_SET 12 +Set the value of the following members of the +.BR semid_ds +data structure associated with +.IR semid +to the corresponding value found in the structure pointed to by +.IR arg.buf , +where +.IR arg +is the fourth argument to +\fIsemctl\fR(): +.RS 12 +.sp +.RS 4 +.nf +\fB +sem_perm.uid +sem_perm.gid +sem_perm.mode +.fi \fR +.P +.RE +.P +The mode bits specified in +.IR "Section 2.7.1" ", " "IPC General Description" +are copied into the corresponding bits of the +.IR sem_perm.mode +associated with +.IR semid . +The stored values of any other bits are unspecified. The +.IR sem_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +This command can only be executed by a process that has an effective +user ID equal to either that of a process with appropriate privileges +or to the value of +.IR sem_perm.cuid +or +.IR sem_perm.uid +in the +.BR semid_ds +data structure associated with +.IR semid . +.RE +.IP IPC_RMID 12 +Remove the semaphore identifier specified by +.IR semid +from the system and destroy the set of semaphores and +.BR semid_ds +data structure associated with it. This command can only be executed +by a process that has an effective user ID equal to either that of a +process with appropriate privileges or to the value of +.IR sem_perm.cuid +or +.IR sem_perm.uid +in the +.BR semid_ds +data structure associated with +.IR semid . +.SH "RETURN VALUE" +If successful, the value returned by +\fIsemctl\fR() +depends on +.IR cmd +as follows: +.IP GETVAL 12 +The value of +.IR semval . +.IP GETPID 12 +The value of +.IR sempid . +.IP GETNCNT 12 +The value of +.IR semncnt . +.IP GETZCNT 12 +The value of +.IR semzcnt . +.IP "All others" 12 +0. +.P +Otherwise, +\fIsemctl\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsemctl\fR() +function shall fail if: +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EINVAL +The value of +.IR semid +is not a valid semaphore identifier, or the value of +.IR semnum +is less than 0 or greater than or equal to +.IR sem_nsems , +or the value of +.IR cmd +is not a valid command. +.TP +.BR EPERM +The argument +.IR cmd +is equal to IPC_RMID or IPC_SET +and the effective user ID of the calling process is not equal to that +of a process with appropriate privileges and it is not equal to the +value of +.IR sem_perm.cuid +or +.IR sem_perm.uid +in the data structure associated with +.IR semid . +.TP +.BR ERANGE +The argument +.IR cmd +is equal to SETVAL or SETALL and the value to which +.IR semval +is to be set is greater than the system-imposed maximum. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Refer to +.IR "\fIsemop\fR\^(\|)". +.SH "APPLICATION USAGE" +The fourth parameter in the SYNOPSIS section is now specified as +.BR \(dq...\(dq +in order to avoid a clash with the ISO\ C standard when referring to the union +.IR semun +(as defined in Issue 3) and for backwards-compatibility. +.P +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_getvalue\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.16" ", " "Semaphore", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/semget.3p b/man-pages-posix-2013-a/man3p/semget.3p new file mode 100644 index 0000000..7c15c14 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/semget.3p @@ -0,0 +1,196 @@ +'\" et +.TH SEMGET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +semget +\(em get set of XSI semaphores +.SH SYNOPSIS +.LP +.nf +#include +.P +int semget(key_t \fIkey\fP, int \fInsems\fP, int \fIsemflg\fP); +.fi +.SH DESCRIPTION +The +\fIsemget\fR() +function operates on XSI semaphores (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.16" ", " "Semaphore"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIsemget\fR() +function shall return the semaphore identifier associated with +.IR key . +.P +A semaphore identifier with its associated +.BR semid_ds +data structure and its associated set of +.IR nsems +semaphores (see +.IR ) +is created for +.IR key +if one of the following is true: +.IP " *" 4 +The argument +.IR key +is equal to IPC_PRIVATE. +.IP " *" 4 +The argument +.IR key +does not already have a semaphore identifier associated with it and +(\fIsemflg\fP &IPC_CREAT) is non-zero. +.P +Upon creation, the +.BR semid_ds +data structure associated with the new semaphore identifier is +initialized as follows: +.IP " *" 4 +In the operation permissions structure +.IR sem_perm.cuid , +.IR sem_perm.uid , +.IR sem_perm.cgid , +and +.IR sem_perm.gid +shall be set to the effective user ID and effective group ID, +respectively, of the calling process. +.IP " *" 4 +The low-order 9 bits of +.IR sem_perm.mode +shall be set to the low-order 9 bits of +.IR semflg . +.IP " *" 4 +The variable +.IR sem_nsems +shall be set to the value of +.IR nsems . +.IP " *" 4 +The variable +.IR sem_otime +shall be set to 0 and +.IR sem_ctime +shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.IP " *" 4 +The data structure associated with each semaphore in the set need not +be initialized. The +\fIsemctl\fR() +function with the command SETVAL or SETALL +can be used to initialize each semaphore. +.SH "RETURN VALUE" +Upon successful completion, +\fIsemget\fR() +shall return a non-negative integer, namely a semaphore identifier; +otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsemget\fR() +function shall fail if: +.TP +.BR EACCES +A semaphore identifier exists for +.IR key , +but operation permission as specified by the low-order 9 bits of +.IR semflg +would not be granted; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EEXIST +A semaphore identifier exists for the argument +.IR key +but ((\fIsemflg\fP &IPC_CREAT) &&(\fIsemflg\fP &IPC_EXCL)) +is non-zero. +.TP +.BR EINVAL +The value of +.IR nsems +is either less than or equal to 0 or greater than the system-imposed +limit, or a semaphore identifier exists for the argument +.IR key , +but the number of semaphores in the set associated with it is less than +.IR nsems +and +.IR nsems +is not equal to 0. +.TP +.BR ENOENT +A semaphore identifier does not exist for the argument +.IR key +and (\fIsemflg\fP &IPC_CREAT) is equal to 0. +.TP +.BR ENOSPC +A semaphore identifier is to be created but the system-imposed limit on +the maximum number of allowed semaphores system-wide would be +exceeded. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Refer to +.IR "\fIsemop\fR\^(\|)". +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version may require that the value of the +.IR semval , +.IR sempid , +.IR semncnt , +and +.IR semzcnt +members of all semaphores in a semaphore set be initialized to zero when +a call to +\fIsemget\fR() +creates a semaphore set. Many semaphore implementations already do this +and it greatly simplifies what an application must do to initialize a +semaphore set. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIftok\fR\^(\|)", +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_getvalue\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.16" ", " "Semaphore", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/semop.3p b/man-pages-posix-2013-a/man3p/semop.3p new file mode 100644 index 0000000..e07ba49 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/semop.3p @@ -0,0 +1,480 @@ +'\" et +.TH SEMOP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +semop +\(em XSI semaphore operations +.SH SYNOPSIS +.LP +.nf +#include +.P +int semop(int \fIsemid\fP, struct sembuf *\fIsops\fP, size_t \fInsops\fP); +.fi +.SH DESCRIPTION +The +\fIsemop\fR() +function operates on XSI semaphores (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.16" ", " "Semaphore"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIsemop\fR() +function shall perform atomically a user-defined array of semaphore +operations in array order on the set of semaphores associated with the +semaphore identifier specified by the argument +.IR semid . +.P +The argument +.IR sops +is a pointer to a user-defined array of semaphore operation +structures. The implementation shall not modify elements of this array +unless the application uses implementation-defined extensions. +.P +The argument +.IR nsops +is the number of such structures in the array. +.P +Each structure, +.BR sembuf , +includes the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +unsigned short!sem_num!Semaphore number. +short!sem_op!Semaphore operation. +short!sem_flg!Operation flags. +.TE +.P +Each semaphore operation specified by +.IR sem_op +is performed on the corresponding semaphore specified by +.IR semid +and +.IR sem_num . +.P +The variable +.IR sem_op +specifies one of three semaphore operations: +.IP " 1." 4 +If +.IR sem_op +is a negative integer and the calling process has alter permission, one +of the following shall occur: +.RS 4 +.IP " *" 4 +If +.IR semval (see +.IR ) +is greater than or equal to the absolute value of +.IR sem_op , +the absolute value of +.IR sem_op +is subtracted from +.IR semval . +Also, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the absolute value of +.IR sem_op +shall be added to the +.IR semadj +value of the calling process for the specified semaphore. +.IP " *" 4 +If +.IR semval +is less than the absolute value of +.IR sem_op +and (\fIsem_flg\fP &IPC_NOWAIT) is non-zero, +\fIsemop\fR() +shall return immediately. +.IP " *" 4 +If +.IR semval +is less than the absolute value of +.IR sem_op +and (\fIsem_flg\fP &IPC_NOWAIT) is 0, +\fIsemop\fR() +shall increment the +.IR semncnt +associated with the specified semaphore and suspend execution of the +calling thread until one of the following conditions occurs: +.RS 4 +.IP -- 4 +The value of +.IR semval +becomes greater than or equal to the absolute value of +.IR sem_op . +When this occurs, the value of +.IR semncnt +associated with the specified semaphore shall be decremented, the +absolute value of +.IR sem_op +shall be subtracted from +.IR semval +and, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the absolute value of +.IR sem_op +shall be added to the +.IR semadj +value of the calling process for the specified semaphore. +.IP -- 4 +The +.IR semid +for which the calling thread is awaiting action is removed from the +system. When this occurs, +.IR errno +shall be set to +.BR [EIDRM] +and \(mi1 shall be returned. +.IP -- 4 +The calling thread receives a signal that is to be caught. When this +occurs, the value of +.IR semncnt +associated with the specified semaphore shall be decremented, and the +calling thread shall resume execution in the manner prescribed in +.IR "\fIsigaction\fR\^(\|)". +.RE +.RE +.IP " 2." 4 +If +.IR sem_op +is a positive integer and the calling process has alter permission, the +value of +.IR sem_op +shall be added to +.IR semval +and, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the value of +.IR sem_op +shall be subtracted from the +.IR semadj +value of the calling process for the specified semaphore. +.IP " 3." 4 +If +.IR sem_op +is 0 and the calling process has read permission, one of the following +shall occur: +.RS 4 +.IP " *" 4 +If +.IR semval +is 0, +\fIsemop\fR() +shall return immediately. +.IP " *" 4 +If +.IR semval +is non-zero and (\fIsem_flg\fP &IPC_NOWAIT) is non-zero, +\fIsemop\fR() +shall return immediately. +.IP " *" 4 +If +.IR semval +is non-zero and (\fIsem_flg\fP &IPC_NOWAIT) is 0, +\fIsemop\fR() +shall increment the +.IR semzcnt +associated with the specified semaphore and suspend execution of the +calling thread until one of the following occurs: +.RS 4 +.IP -- 4 +The value of +.IR semval +becomes 0, at which time the value of +.IR semzcnt +associated with the specified semaphore shall be decremented. +.IP -- 4 +The +.IR semid +for which the calling thread is awaiting action is removed from the +system. When this occurs, +.IR errno +shall be set to +.BR [EIDRM] +and \(mi1 shall be returned. +.IP -- 4 +The calling thread receives a signal that is to be caught. When this +occurs, the value of +.IR semzcnt +associated with the specified semaphore shall be decremented, and the +calling thread shall resume execution in the manner prescribed in +.IR "\fIsigaction\fR\^(\|)". +.RE +.RE +.P +Upon successful completion, the value of +.IR sempid +for each semaphore specified in the array pointed to by +.IR sops +shall be set to the process ID of the calling process. Also, the +.IR sem_otime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.SH "RETURN VALUE" +Upon successful completion, +\fIsemop\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsemop\fR() +function shall fail if: +.TP +.BR E2BIG +The value of +.IR nsops +is greater than the system-imposed maximum. +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EAGAIN +The operation would result in suspension of the calling process but +(\fIsem_flg\fP &IPC_NOWAIT) is non-zero. +.TP +.BR EFBIG +The value of +.IR sem_num +is greater than or equal to the number of semaphores in the set +associated with +.IR semid . +.TP +.BR EIDRM +The semaphore identifier +.IR semid +is removed from the system. +.TP +.BR EINTR +The +\fIsemop\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The value of +.IR semid +is not a valid semaphore identifier, or the number of individual +semaphores for which the calling process requests a SEM_UNDO would +exceed the system-imposed limit. +.TP +.BR ENOSPC +The limit on the number of individual processes requesting a SEM_UNDO +would be exceeded. +.TP +.BR ERANGE +An operation would cause a +.IR semval +to overflow the system-imposed limit, or an operation would cause a +.IR semadj +value to overflow the system-imposed limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Setting Values in Semaphores" +.P +The following example sets the values of the two semaphores associated +with the +.IR semid +identifier to the values contained in the +.IR sb +array. +.sp +.RS 4 +.nf +\fB +#include +\&... +int semid; +struct sembuf sb[2]; +int nsops = 2; +int result; +.P +/* Code to initialize semid. */ +\&... +.P +/* Adjust value of semaphore in the semaphore array semid. */ +sb[0].sem_num = 0; +sb[0].sem_op = -1; +sb[0].sem_flg = SEM_UNDO | IPC_NOWAIT; +sb[1].sem_num = 1; +sb[1].sem_op = 1; +sb[1].sem_flg = 0; +.P +result = semop(semid, sb, nsops); +.fi \fR +.P +.RE +.SS "Creating a Semaphore Identifier" +.P +The following example gets a unique semaphore key using the +\fIftok\fR() +function, then gets a semaphore ID associated with that key using the +\fIsemget\fR() +function (the first call also tests to make sure the semaphore exists). +If the semaphore does not exist, the program creates it, as shown by +the second call to +\fIsemget\fR(). +In creating the semaphore for the queuing process, the program +attempts to create one semaphore with read/write permission for all. It +also uses the IPC_EXCL flag, which forces +\fIsemget\fR() +to fail if the semaphore already exists. +.P +After creating the semaphore, the program uses calls to +\fIsemctl\fR() +and +\fIsemop\fR() +to initialize it to the values in the +.IR sbuf +array. The number of processes that can execute concurrently without +queuing is initially set to 2. The final call to +\fIsemget\fR() +creates a semaphore identifier that can be used later in the program. +.P +Processes that obtain +.IR semid +without creating it check that +.IR sem_otime +is non-zero, to ensure that the creating process has completed the +\fIsemop\fR() +initialization. +.P +The final call to +\fIsemop\fR() +acquires the semaphore and waits until it is free; the SEM_UNDO option +releases the semaphore when the process exits, waiting until there are +less than two processes running concurrently. +.br +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +\&... +key_t semkey; +int semid; +struct sembuf sbuf; +union semun { + int val; + struct semid_ds *buf; + unsigned short *array; +} arg; +struct semid_ds ds; +\&... +/* Get unique key for semaphore. */ +if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { + perror("IPC error: ftok"); exit(1); +} +.P +/* Get semaphore ID associated with this key. */ +if ((semid = semget(semkey, 0, 0)) == -1) { +.P + /* Semaphore does not exist - Create. */ + if ((semid = semget(semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR | + S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1) + { + /* Initialize the semaphore. */ + arg.val = 0; + sbuf.sem_num = 0; + sbuf.sem_op = 2; /* This is the number of runs without queuing. */ + sbuf.sem_flg = 0; + if (semctl(semid, 0, SETVAL, arg) == -1 + || semop(semid, &sbuf, 1) == -1) { + perror("IPC error: semop"); exit(1); + } + } + else if (errno == EEXIST) { + if ((semid = semget(semkey, 0, 0)) == -1) { + perror("IPC error 1: semget"); exit(1); + } + goto check_init; + } + else { + perror("IPC error 2: semget"); exit(1); + } +} +else +{ + /* Check that semid has completed initialization. */ + /* An application can use a retry loop at this point rather than + exiting. */ + check_init: + arg.buf = &ds; + if (semctl(semid, 0, IPC_STAT, arg) < 0) { + perror("IPC error 3: semctl"); exit(1); + } + if (ds.sem_otime == 0) { + perror("IPC error 4: semctl"); exit(1); + } +} +\&... +sbuf.sem_num = 0; +sbuf.sem_op = -1; +sbuf.sem_flg = SEM_UNDO; +if (semop(semid, &sbuf, 1) == -1) { + perror("IPC Error: semop"); exit(1); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_getvalue\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.16" ", " "Semaphore", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/send.3p b/man-pages-posix-2013-a/man3p/send.3p new file mode 100644 index 0000000..a38fae1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/send.3p @@ -0,0 +1,224 @@ +'\" et +.TH SEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +send +\(em send a message on a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t send(int \fIsocket\fP, const void *\fIbuffer\fP, size_t \fIlength\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIsend\fR() +function shall initiate transmission of a message from the specified +socket to its peer. The +\fIsend\fR() +function shall send a message only when the socket is connected. If +the socket is a connectionless-mode socket, the message shall be sent +to the pre-specified peer address. +.P +The +\fIsend\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fIbuffer\fR" 12 +Points to the buffer containing the message to send. +.IP "\fIlength\fR" 12 +Specifies the length of the message in bytes. +.IP "\fIflags\fR" 12 +Specifies the type of message transmission. Values of this argument are +formed by logically OR'ing zero or more of the following flags: +.RS 12 +.IP MSG_EOR 14 +Terminates a record (if supported by the protocol). +.IP MSG_OOB 14 +Sends out-of-band data on sockets that support out-of-band +communications. The significance and semantics of out-of-band data are +protocol-specific. +.IP MSG_NOSIGNAL 14 +Requests not to send the SIGPIPE signal if an attempt to send is made +on a stream-oriented socket that is no longer connected. The +.BR [EPIPE] +error shall still be returned. +.RE +.P +The length of the message to be sent is specified by the +.IR length +argument. If the message is too long to pass through the underlying +protocol, +\fIsend\fR() +shall fail and no data shall be transmitted. +.P +Successful completion of a call to +\fIsend\fR() +does not guarantee delivery of the message. A return value of \(mi1 +indicates only locally-detected errors. +.P +If space is not available at the sending socket to hold the message to +be transmitted, and the socket file descriptor does not have O_NONBLOCK +set, +\fIsend\fR() +shall block until space is available. If space is not available at the +sending socket to hold the message to be transmitted, and the socket +file descriptor does have O_NONBLOCK set, +\fIsend\fR() +shall fail. The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when it is possible to send more +data. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIsend\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, +\fIsend\fR() +shall return the number of bytes sent. Otherwise, \(mi1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsend\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EDESTADDRREQ +.br +The socket is not connection-mode and no peer address is set. +.TP +.BR EINTR +A signal interrupted +\fIsend\fR() +before any data was transmitted. +.TP +.BR EMSGSIZE +The message is too large to be sent all at once, as the socket requires. +.TP +.BR ENOTCONN +The socket is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The +.IR socket +argument is associated with a socket that does not support one or more +of the values set in +.IR flags . +.TP +.BR EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if the socket is of +type SOCK_STREAM or SOCK_SEQPACKET and the MSG_NOSIGNAL flag is not set, +the SIGPIPE signal is generated to the calling thread. +.P +The +\fIsend\fR() +function may fail if: +.TP +.BR EACCES +The calling process does not have appropriate privileges. +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.TP +.BR ENETDOWN +The local network interface used to reach the destination is down. +.TP +.BR ENETUNREACH +.br +No route to the network is present. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +If the +.IR socket +argument refers to a connection-mode socket, the +\fIsend\fR() +function is equivalent to +\fIsendto\fR() +(with any value for the +.IR dest_addr +and +.IR dest_len +arguments, as they are ignored in this case). If the +.IR socket +argument refers to a socket and the +.IR flags +argument is 0, the +\fIsend\fR() +function is equivalent to +\fIwrite\fR(). +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sendmsg.3p b/man-pages-posix-2013-a/man3p/sendmsg.3p new file mode 100644 index 0000000..c826fe0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sendmsg.3p @@ -0,0 +1,323 @@ +'\" et +.TH SENDMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sendmsg +\(em send a message on a socket using a message structure +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t sendmsg(int \fIsocket\fP, const struct msghdr *\fImessage\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIsendmsg\fR() +function shall send a message through a connection-mode or +connectionless-mode socket. If the socket is a connectionless-mode +socket, the message shall be sent to the address specified by +.BR msghdr +if no pre-specified peer address has been set. If a peer address has +been pre-specified, either the message shall be sent to the address +specified in +.BR msghdr +(overriding the pre-specified peer address), or the function shall +return \(mi1 and set +.IR errno +to +.BR [EISCONN] . +If the socket is connection-mode, the destination address in +.BR msghdr +shall be ignored. +.P +The +\fIsendmsg\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fImessage\fR" 12 +Points to a +.BR msghdr +structure, containing both the destination address and the buffers for +the outgoing message. The length and format of the address depend on +the address family of the socket. The +.IR msg_flags +member is ignored. +.IP "\fIflags\fR" 12 +Specifies the type of message transmission. The application may +specify 0 or the following flag: +.RS 12 +.IP MSG_EOR 14 +Terminates a record (if supported by the protocol). +.IP MSG_OOB 14 +Sends out-of-band data on sockets that support out-of-bound data. The +significance and semantics of out-of-band data are protocol-specific. +.IP MSG_NOSIGNAL 14 +Requests not to send the SIGPIPE signal if an attempt to send is made +on a stream-oriented socket that is no longer connected. The +.BR [EPIPE] +error shall still be returned. +.RE +.P +The +.IR msg_iov +and +.IR msg_iovlen +fields of +.IR message +specify zero or more buffers containing the data to be sent. +.IR msg_iov +points to an array of +.BR iovec +structures; +.IR msg_iovlen +shall be set to the dimension of this array. In each +.BR iovec +structure, the +.IR iov_base +field specifies a storage area and the +.IR iov_len +field gives its size in bytes. Some of these sizes can be zero. The +data from each storage area indicated by +.IR msg_iov +is sent in turn. +.P +Successful completion of a call to +\fIsendmsg\fR() +does not guarantee delivery of the message. A return value of \(mi1 +indicates only locally-detected errors. +.P +If space is not available at the sending socket to hold the message to +be transmitted and the socket file descriptor does not have O_NONBLOCK +set, the +\fIsendmsg\fR() +function shall block until space is available. If space is not +available at the sending socket to hold the message to be transmitted +and the socket file descriptor does have O_NONBLOCK set, the +\fIsendmsg\fR() +function shall fail. +.P +If the socket protocol supports broadcast and the specified address is +a broadcast address for the socket protocol, +\fIsendmsg\fR() +shall fail if the SO_BROADCAST option is not set for the socket. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIsendmsg\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, +\fIsendmsg\fR() +shall return the number of bytes sent. Otherwise, \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsendmsg\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP +.BR EAFNOSUPPORT +.br +Addresses in the specified address family cannot be used with this +socket. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +A signal interrupted +\fIsendmsg\fR() +before any data was transmitted. +.TP +.BR EINVAL +The sum of the +.IR iov_len +values overflows an +.BR ssize_t . +.TP +.BR EMSGSIZE +The message is too large to be sent all at once (as the socket +requires), or the +.IR msg_iovlen +member of the +.BR msghdr +structure pointed to by +.IR message +is less than or equal to 0 or is greater than +{IOV_MAX}. +.TP +.BR ENOTCONN +The socket is connection-mode but is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The +.IR socket +argument is associated with a socket that does not support one or more +of the values set in +.IR flags . +.TP +.BR EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if the socket is of +type SOCK_STREAM or SOCK_SEQPACKET and the MSG_NOSIGNAL flag is not set, +the SIGPIPE signal is generated to the calling thread. +.P +If the address family of the socket is AF_UNIX, then +\fIsendmsg\fR() +shall fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in the socket address. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the pathname does not name an existing file or the path +name is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix of the pathname in the socket address +names an existing file that is neither a directory nor a symbolic link +to a directory, or the pathname in the socket address contains at least +one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIsendmsg\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP +.BR EDESTADDRREQ +.br +The socket is not connection-mode and does not have its peer address +set, and no destination address was specified. +.TP +.BR EHOSTUNREACH +.br +The destination host cannot be reached (probably because the host is +down or a remote router cannot reach it). +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.TP +.BR EISCONN +A destination address was specified and the socket is already +connected. +.TP +.BR ENETDOWN +The local network interface used to reach the destination is down. +.TP +.BR ENETUNREACH +.br +No route to the network is present. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.P +If the address family of the socket is AF_UNIX, then +\fIsendmsg\fR() +may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the pathname in +the socket address. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +Done. +.SH "APPLICATION USAGE" +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when it is possible to send more +data. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sendto.3p b/man-pages-posix-2013-a/man3p/sendto.3p new file mode 100644 index 0000000..1ce82ef --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sendto.3p @@ -0,0 +1,314 @@ +'\" et +.TH SENDTO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sendto +\(em send a message on a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t sendto(int \fIsocket\fP, const void *\fImessage\fP, size_t \fIlength\fP, + int \fIflags\fP, const struct sockaddr *\fIdest_addr\fP, + socklen_t \fIdest_len\fP); +.fi +.SH DESCRIPTION +The +\fIsendto\fR() +function shall send a message through a connection-mode or +connectionless-mode socket. +.P +If the socket is a connectionless-mode socket, the message shall be sent +to the address specified by +.IR dest_addr +if no pre-specified peer address has been set. If a peer address has +been pre-specified, either the message shall be sent to the address +specified by +.IR dest_addr +(overriding the pre-specified peer address), or the function shall +return \(mi1 and set +.IR errno +to +.BR [EISCONN] . +.P +If the socket is connection-mode, +.IR dest_addr +shall be ignored. +.P +The +\fIsendto\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fImessage\fR" 12 +Points to a buffer containing the message to be sent. +.IP "\fIlength\fR" 12 +Specifies the size of the message in bytes. +.IP "\fIflags\fR" 12 +Specifies the type of message transmission. Values of this argument +are formed by logically OR'ing zero or more of the following flags: +.RS 12 +.IP MSG_EOR 14 +Terminates a record (if supported by the protocol). +.IP MSG_OOB 14 +Sends out-of-band data on sockets that support out-of-band data. The +significance and semantics of out-of-band data are protocol-specific. +.IP MSG_NOSIGNAL 14 +Requests not to send the SIGPIPE signal if an attempt to send is made +on a stream-oriented socket that is no longer connected. The +.BR [EPIPE] +error shall still be returned. +.RE +.IP "\fIdest_addr\fR" 12 +Points to a +.BR sockaddr +structure containing the destination address. The length and format of +the address depend on the address family of the socket. +.IP "\fIdest_len\fR" 12 +Specifies the length of the +.BR sockaddr +structure pointed to by the +.IR dest_addr +argument. +.P +If the socket protocol supports broadcast and the specified address is +a broadcast address for the socket protocol, +\fIsendto\fR() +shall fail if the SO_BROADCAST option is not set for the socket. +.P +The +.IR dest_addr +argument specifies the address of the target. +.P +The +.IR length +argument specifies the length of the message. +.P +Successful completion of a call to +\fIsendto\fR() +does not guarantee delivery of the message. A return value of \(mi1 +indicates only locally-detected errors. +.P +If space is not available at the sending socket to hold the message to +be transmitted and the socket file descriptor does not have O_NONBLOCK +set, +\fIsendto\fR() +shall block until space is available. If space is not available at the +sending socket to hold the message to be transmitted and the socket +file descriptor does have O_NONBLOCK set, +\fIsendto\fR() +shall fail. +.br +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIsendto\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, +\fIsendto\fR() +shall return the number of bytes sent. Otherwise, \(mi1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsendto\fR() +function shall fail if: +.TP +.BR EAFNOSUPPORT +.br +Addresses in the specified address family cannot be used with this +socket. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +A signal interrupted +\fIsendto\fR() +before any data was transmitted. +.TP +.BR EMSGSIZE +The message is too large to be sent all at once, as the socket +requires. +.TP +.BR ENOTCONN +The socket is connection-mode but is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The +.IR socket +argument is associated with a socket that does not support one or more +of the values set in +.IR flags . +.TP +.BR EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if the socket is of +type SOCK_STREAM or SOCK_SEQPACKET and the MSG_NOSIGNAL flag is not set, +the SIGPIPE signal is generated to the calling thread. +.P +If the address family of the socket is AF_UNIX, then +\fIsendto\fR() +shall fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in the socket address. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the pathname does not name an existing file or the +pathname is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix of the pathname in the socket address +names an existing file that is neither a directory nor a symbolic link +to a directory, or the pathname in the socket address contains at +least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIsendto\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP +.BR EDESTADDRREQ +.br +The socket is not connection-mode and does not have its peer address +set, and no destination address was specified. +.TP +.BR EHOSTUNREACH +.br +The destination host cannot be reached (probably because the host is +down or a remote router cannot reach it). +.TP +.BR EINVAL +The +.IR dest_len +argument is not a valid length for the address family. +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR EISCONN +A destination address was specified and the socket is already +connected. +.TP +.BR ENETDOWN +The local network interface used to reach the destination is down. +.TP +.BR ENETUNREACH +.br +No route to the network is present. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.P +If the address family of the socket is AF_UNIX, then +\fIsendto\fR() +may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the pathname in +the socket address. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when it is possible to send more +data. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setbuf.3p b/man-pages-posix-2013-a/man3p/setbuf.3p new file mode 100644 index 0000000..32fb1a0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setbuf.3p @@ -0,0 +1,121 @@ +'\" et +.TH SETBUF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setbuf +\(em assign buffering to a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +void setbuf(FILE *restrict \fIstream\fP, char *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +Except that it returns no value, the function call: +.sp +.RS 4 +.nf +\fB +setbuf(stream, buf) +.fi \fR +.P +.RE +.P +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +setvbuf(stream, buf, _IOFBF, BUFSIZ) +.fi \fR +.P +.RE +.P +if +.IR buf +is not a null pointer, or to: +.sp +.RS 4 +.nf +\fB +setvbuf(stream, buf, _IONBF, BUFSIZ) +.fi \fR +.P +.RE +.P +if +.IR buf +is a null pointer. +.SH "RETURN VALUE" +The +\fIsetbuf\fR() +function shall not return a value. +.SH ERRORS +Although the +\fIsetvbuf\fR() +interface may set +.IR errno +in defined ways, the value of +.IR errno +after a call to +\fIsetbuf\fR() +is unspecified. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +A common source of error is allocating buffer space as an ``automatic'' +variable in a code block, and then failing to close the stream in the +same block. +.P +With +\fIsetbuf\fR(), +allocating a buffer of BUFSIZ bytes does not necessarily imply that all +of BUFSIZ bytes are used for the buffer area. +.P +Since +.IR errno +is not required to be unchanged on success, in order to correctly detect +and possibly recover from errors, applications should use +\fIsetvbuf\fR() +instead of +\fIsetbuf\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIsetvbuf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setegid.3p b/man-pages-posix-2013-a/man3p/setegid.3p new file mode 100644 index 0000000..6a388ca --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setegid.3p @@ -0,0 +1,94 @@ +'\" et +.TH SETEGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setegid +\(em set the effective group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int setegid(gid_t \fIgid\fP); +.fi +.SH DESCRIPTION +If +.IR gid +is equal to the real group ID or the saved set-group-ID, or if the +process has appropriate privileges, +\fIsetegid\fR() +shall set the effective group ID of the calling process to +.IR gid ; +the real group ID, saved set-group-ID, and any supplementary group IDs +shall remain unchanged. +.P +The +\fIsetegid\fR() +function shall not affect the supplementary group list in any way. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetegid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR gid +argument is invalid and is not supported by the implementation. +.TP +.BR EPERM +The process does not have appropriate privileges and +.IR gid +does not match the real group ID or the saved set-group-ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetuid\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setenv.3p b/man-pages-posix-2013-a/man3p/setenv.3p new file mode 100644 index 0000000..180025e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setenv.3p @@ -0,0 +1,167 @@ +'\" et +.TH SETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setenv +\(em add or change environment variable +.SH SYNOPSIS +.LP +.nf +#include +.P +int setenv(const char *\fIenvname\fP, const char *\fIenvval\fP, int \fIoverwrite\fP); +.fi +.SH DESCRIPTION +The +\fIsetenv\fR() +function shall update or add a variable in the environment of the +calling process. The +.IR envname +argument points to a string containing the name of an environment +variable to be added or altered. The environment variable shall be set +to the value to which +.IR envval +points. The function shall fail if +.IR envname +points to a string which contains an +.BR '=' +character. If the environment variable named by +.IR envname +already exists and the value of +.IR overwrite +is non-zero, the function shall return success and the environment +shall be updated. If the environment variable named by +.IR envname +already exists and the value of +.IR overwrite +is zero, the function shall return success and the environment shall +remain unchanged. +.P +The +\fIsetenv\fR() +function shall update the list of pointers to which +.IR environ +points. +.P +The strings described by +.IR envname +and +.IR envval +are copied by this function. +.P +The +\fIsetenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, zero shall be returned. Otherwise, \(mi1 +shall be returned, +.IR errno +set to indicate the error, and the environment shall be unchanged. +.SH ERRORS +The +\fIsetenv\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR envname +argument points to an empty string or points to a string containing an +.BR '=' +character. +.TP +.BR ENOMEM +Insufficient memory was available to add a variable or its value to the +environment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +See +\fIexec\fR() +for restrictions on changing the environment in multi-threaded +applications. +.SH RATIONALE +Unanticipated results may occur if +\fIsetenv\fR() +changes the external variable +.IR environ . +In particular, if the optional +.IR envp +argument to +\fImain\fR() +is present, it is not changed, and thus may point to an obsolete copy +of the environment (as may any other copy of +.IR environ ). +However, other than the aforementioned restriction, the standard +developers intended that the traditional method of walking through +the environment by way of the +.IR environ +pointer must be supported. +.P +It was decided that +\fIsetenv\fR() +should be required by this version because it addresses a piece of +missing functionality, and does not impose a significant burden on the +implementor. +.P +There was considerable debate as to whether the System V +\fIputenv\fR() +function or the BSD +\fIsetenv\fR() +function should be required as a mandatory function. The +\fIsetenv\fR() +function was chosen because it permitted the implementation of the +\fIunsetenv\fR() +function to delete environmental variables, without specifying an +additional interface. The +\fIputenv\fR() +function is available as part of the XSI option. +.P +The standard developers considered requiring that +\fIsetenv\fR() +indicate an error when a call to it would result in exceeding +{ARG_MAX}. +The requirement was rejected since the condition might be temporary, +with the application eventually reducing the environment size. The +ultimate success or failure depends on the size at the time of a call +to +.IR exec , +which returns an indication of this error condition. +.P +See also the RATIONALE section in +.IR "\fIgetenv\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIunsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/seteuid.3p b/man-pages-posix-2013-a/man3p/seteuid.3p new file mode 100644 index 0000000..af9f09e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/seteuid.3p @@ -0,0 +1,93 @@ +'\" et +.TH SETEUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +seteuid +\(em set effective user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int seteuid(uid_t \fIuid\fP); +.fi +.SH DESCRIPTION +If +.IR uid +is equal to the real user ID or the saved set-user-ID, or if the +process has appropriate privileges, +\fIseteuid\fR() +shall set the effective user ID of the calling process to +.IR uid ; +the real user ID and saved set-user-ID shall remain unchanged. +.P +The +\fIseteuid\fR() +function shall not affect the supplementary group list in any way. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIseteuid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR uid +argument is invalid and is not supported by the implementation. +.TP +.BR EPERM +The process does not have appropriate privileges and +.IR uid +does not match the real user ID or the saved set-user-ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetuid\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setgid.3p b/man-pages-posix-2013-a/man3p/setgid.3p new file mode 100644 index 0000000..9223c8d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setgid.3p @@ -0,0 +1,101 @@ +'\" et +.TH SETGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setgid +\(em set-group-ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int setgid(gid_t \fIgid\fP); +.fi +.SH DESCRIPTION +If the process has appropriate privileges, +\fIsetgid\fR() +shall set the real group ID, effective group ID, and the saved +set-group-ID of the calling process to +.IR gid . +.P +If the process does not have appropriate privileges, but +.IR gid +is equal to the real group ID or the saved set-group-ID, +\fIsetgid\fR() +shall set the effective group ID to +.IR gid ; +the real group ID and saved set-group-ID shall remain unchanged. +.P +The +\fIsetgid\fR() +function shall not affect the supplementary group list in any way. +.P +Any supplementary group IDs of the calling process shall remain +unchanged. +.SH "RETURN VALUE" +Upon successful completion, 0 is returned. Otherwise, \(mi1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetgid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR gid +argument is invalid and is not supported by the implementation. +.TP +.BR EPERM +The process does not have appropriate privileges and +.IR gid +does not match the real group ID or the saved set-group-ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetuid\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setgrent.3p b/man-pages-posix-2013-a/man3p/setgrent.3p new file mode 100644 index 0000000..f993735 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setgrent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETGRENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setgrent +\(em reset the group database to the first entry +.SH SYNOPSIS +.LP +.nf +#include +.P +void setgrent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendgrent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sethostent.3p b/man-pages-posix-2013-a/man3p/sethostent.3p new file mode 100644 index 0000000..9e35f60 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sethostent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETHOSTENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sethostent +\(em network host database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void sethostent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendhostent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setitimer.3p b/man-pages-posix-2013-a/man3p/setitimer.3p new file mode 100644 index 0000000..59d19b3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setitimer.3p @@ -0,0 +1,39 @@ +'\" et +.TH SETITIMER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setitimer +\(em set the value of an interval timer +.SH SYNOPSIS +.LP +.nf +#include +.P +int setitimer(int \fIwhich\fP, const struct itimerval *restrict \fIvalue\fP, + struct itimerval *restrict \fIovalue\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetitimer\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setjmp.3p b/man-pages-posix-2013-a/man3p/setjmp.3p new file mode 100644 index 0000000..ca5b6f8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setjmp.3p @@ -0,0 +1,104 @@ +'\" et +.TH SETJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setjmp +\(em set jump point for a non-local goto +.SH SYNOPSIS +.LP +.nf +#include +.P +int setjmp(jmp_buf \fIenv\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +A call to +\fIsetjmp\fR() +shall save the calling environment in its +.IR env +argument for later use by +\fIlongjmp\fR(). +.P +It is unspecified whether +\fIsetjmp\fR() +is a macro or a function. If a macro definition is suppressed in order +to access an actual function, or a program defines an external +identifier with the name +.IR setjmp , +the behavior is undefined. +.P +An application shall ensure that an invocation of +\fIsetjmp\fR() +appears in one of the following contexts only: +.IP " *" 4 +The entire controlling expression of a selection or iteration +statement +.IP " *" 4 +One operand of a relational or equality operator with the other operand +an integral constant expression, with the resulting expression being +the entire controlling expression of a selection or iteration statement +.IP " *" 4 +The operand of a unary +.BR '!' +operator with the resulting expression being the entire controlling +expression of a selection or iteration +.IP " *" 4 +The entire expression of an expression statement (possibly cast to +.BR void ) +.P +If the invocation appears in any other context, the behavior is +undefined. +.SH "RETURN VALUE" +If the return is from a direct invocation, +\fIsetjmp\fR() +shall return 0. If the return is from a call to +\fIlongjmp\fR(), +\fIsetjmp\fR() +shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +In general, +\fIsigsetjmp\fR() +is more useful in dealing with errors and interrupts encountered in a +low-level subroutine of a program. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setkey.3p b/man-pages-posix-2013-a/man3p/setkey.3p new file mode 100644 index 0000000..3aa615c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setkey.3p @@ -0,0 +1,98 @@ +'\" et +.TH SETKEY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setkey +\(em set encoding key +(\fBCRYPT\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +void setkey(const char *\fIkey\fP); +.fi +.SH DESCRIPTION +The +\fIsetkey\fR() +function provides access to an implementation-defined encoding +algorithm. The argument of +\fIsetkey\fR() +is an array of length 64 bytes containing only the bytes with numerical +value of 0 and 1. If this string is divided into groups of 8, the +low-order bit in each group is ignored; this gives a 56-bit key which +is used by the algorithm. This is the key that shall be used with the +algorithm to encode a string +.IR block +passed to +\fIencrypt\fR(). +.P +The +\fIsetkey\fR() +function shall not change the setting of +.IR errno +if successful. An application wishing to check for error situations +should set +.IR errno +to 0 before calling +\fIsetkey\fR(). +If +.IR errno +is non-zero on return, an error has occurred. +.P +The +\fIsetkey\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +No values are returned. +.SH ERRORS +The +\fIsetkey\fR() +function shall fail if: +.TP +.BR ENOSYS +The functionality is not supported on this implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Decoding need not be implemented in all environments. This is related +to government restrictions in some countries on encryption and +decryption routines. Historical practice has been to ship a different +version of the encryption library without the decryption feature in the +routines supplied. Thus the exported version of +\fIencrypt\fR() +does encoding but not decoding. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcrypt\fR\^(\|)", +.IR "\fIencrypt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setlocale.3p b/man-pages-posix-2013-a/man3p/setlocale.3p new file mode 100644 index 0000000..bb4f94d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setlocale.3p @@ -0,0 +1,441 @@ +'\" et +.TH SETLOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setlocale +\(em set program locale +.SH SYNOPSIS +.LP +.nf +#include +.P +char *setlocale(int \fIcategory\fP, const char *\fIlocale\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIsetlocale\fR() +function selects the appropriate piece of the global locale, as specified +by the +.IR category +and +.IR locale +arguments, and can be used to change or query the entire global locale +or portions thereof. The value LC_ALL for +.IR category +names the entire global locale; other values for +.IR category +name only a part of the global locale: +.IP LC_COLLATE 12 +Affects the behavior of regular expressions and the collation +functions. +.IP LC_CTYPE 12 +Affects the behavior of regular expressions, character classification, +character conversion functions, and wide-character functions. +.IP LC_MESSAGES 12 +Affects the affirmative and negative response expressions returned by +\fInl_langinfo\fR() +and the way message catalogs are located. It may also affect the +behavior of functions that return or write message strings. +.IP LC_MONETARY 12 +Affects the behavior of functions that handle monetary values. +.IP LC_NUMERIC 12 +Affects the behavior of functions that handle numeric values. +.IP LC_TIME 12 +Affects the behavior of the time conversion functions. +.P +The +.IR locale +argument is a pointer to a character string containing the required +setting of +.IR category . +The contents of this string are implementation-defined. In addition, +the following preset values of +.IR locale +are defined for all settings of +.IR category : +.IP "\&\(dqPOSIX\(dq" 12 +Specifies the minimal environment for C-language translation called the +POSIX locale. The POSIX locale is the default global locale at entry to +\fImain\fR(). +.IP "\&\(dqC\(dq" 12 +Equivalent to +.BR \(dqPOSIX\(dq . +.IP "\&\(dq\|\(dq" 12 +Specifies an implementation-defined native environment. +The determination of the name of the new locale for the specified +category depends on the value of the associated environment +variables, +.IR LC_* +and +.IR LANG ; +see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale" +and +.IR "Chapter 8" ", " "Environment Variables". +.IP "A\ null\ pointer" 12 +Directs +\fIsetlocale\fR() +to query the current global locale setting and return the name +of the locale if +.IR category +is not LC_ALL, or a string which encodes the locale name(s) for all of +the individual categories if +.IR category +is LC_ALL. +.P +Setting all of the categories of the global locale is similar to +successively setting each individual category of the global locale, except +that all error checking is done before any actions are performed. To +set all the categories of the global locale, +\fIsetlocale\fR() +can be invoked as: +.sp +.RS 4 +.nf +\fB +setlocale(LC_ALL, ""); +.fi \fR +.P +.RE +.P +In this case, +\fIsetlocale\fR() +shall first verify that the values of all the environment variables it +needs according to the precedence rules (described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables") +indicate supported locales. If the value of any of these environment +variable searches yields a locale that is not supported (and non-null), +\fIsetlocale\fR() +shall return a null pointer and the global locale shall not be changed. If +all environment variables name supported locales, +\fIsetlocale\fR() +shall proceed as if it had been called for each category, using the +appropriate value from the associated environment variable or from the +implementation-defined default if there is no such value. +.P +The global locale established using +\fIsetlocale\fR() +shall only be used in threads for which no current locale has been +set using +\fIuselocale\fR() +or whose current locale has been set to the global locale using +.IR uselocale (LC_GLOBAL_LOCALE) . +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 calls +\fIsetlocale\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIsetlocale\fR() +shall return the string associated with the specified category for the +new locale. Otherwise, +\fIsetlocale\fR() +shall return a null pointer and the global locale shall not be changed. +.P +A null pointer for +.IR locale +shall cause +\fIsetlocale\fR() +to return a pointer to the string associated with the specified +.IR category +for the current global locale. The global locale shall not be changed. +.P +The string returned by +\fIsetlocale\fR() +is such that a subsequent call with that string and its associated +.IR category +shall restore that part of the global locale. The application shall +not modify the string returned. +The returned string pointer might be invalidated or +the string content might be overwritten by a subsequent call to +\fIsetlocale\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The following code illustrates how a program can initialize the +international environment for one language, while selectively modifying +the global locale such that regular expressions and string operations +can be applied to text recorded in a different language: +.sp +.RS 4 +.nf +\fB +setlocale(LC_ALL, "De"); +setlocale(LC_COLLATE, "Fr@dict"); +.fi \fR +.P +.RE +.P +Internationalized programs can initiate language operation according +to environment variable settings (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables") +by calling +\fIsetlocale\fR() +as follows: +.sp +.RS 4 +.nf +\fB +setlocale(LC_ALL, ""); +.fi \fR +.P +.RE +.P +Changing the setting of +.IR LC_MESSAGES +has no effect on catalogs that have already been opened by calls to +\fIcatopen\fR(). +.P +In order to make use of different locale settings while multiple +threads are running, applications should use +\fIuselocale\fR() +in preference to +\fIsetlocale\fR(). +.SH RATIONALE +References to the international environment or locale in the following +text relate to the global locale for the process. This can be overridden +for individual threads using +\fIuselocale\fR(). +.P +The ISO\ C standard +defines a collection of functions to support internationalization. +One of the most significant aspects of these functions is a facility +to set and query the \fIinternational environment\fP. +The international environment is a repository of information that +affects the behavior of certain functionality, namely: +.IP " 1." 4 +Character handling +.IP " 2." 4 +Collating +.IP " 3." 4 +Date/time formatting +.IP " 4." 4 +Numeric editing +.IP " 5." 4 +Monetary formatting +.IP " 6." 4 +Messaging +.P +The +\fIsetlocale\fR() +function provides the application developer with the ability to set all +or portions, called \fIcategories\fP, of the international environment. +These categories correspond to the areas of functionality mentioned +above. The syntax for +\fIsetlocale\fR() +is as follows: +.sp +.RS 4 +.nf +\fB +char *setlocale(int \fIcategory\fP, const char *\fIlocale\fP); +.fi \fR +.P +.RE +.P +where +.IR category +is the name of one of following categories, namely: +.sp +.RS +LC_COLLATE +LC_CTYPE +LC_MESSAGES +LC_MONETARY +LC_NUMERIC +LC_TIME +.RE +.P +In addition, a special value called LC_ALL +directs +\fIsetlocale\fR() +to set all categories. +.P +There are two primary uses of +\fIsetlocale\fR(): +.IP " 1." 4 +Querying the international environment to find out what it is set to +.IP " 2." 4 +Setting the international environment, or +.IR locale , +to a specific value +.P +The behavior of +\fIsetlocale\fR() +in these two areas is described below. Since it is difficult to +describe the behavior in words, examples are used to illustrate the +behavior of specific uses. +.P +To query the international environment, +\fIsetlocale\fR() +is invoked with a specific category and the null pointer as the +locale. The null pointer is a special directive to +\fIsetlocale\fR() +that tells it to query rather than set the international environment. +The following syntax is used to query the name of the international +environment: +.sp +.RS 4 +.nf +\fB +setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \e + LC_NUMERIC, LC_TIME},(char *) NULL); +.fi \fR +.P +.RE +.P +The +\fIsetlocale\fR() +function shall return the string corresponding to the current +international environment. This value may be used by a subsequent call to +\fIsetlocale\fR() +to reset the international environment to this value. However, it +should be noted that the return value from +\fIsetlocale\fR() +may be a pointer to a static area within the function and is not +guaranteed to remain unchanged (that is, it may be modified by a +subsequent call to +\fIsetlocale\fR()). +Therefore, if the purpose of calling +\fIsetlocale\fR() +is to save the value of the current international environment so it can +be changed and reset later, the return value should be copied to an +array of +.BR char +in the calling program. +.P +There are three ways to set the international environment with +\fIsetlocale\fR(): +.IP "\fIsetlocale\fP(\fIcategory\fP,\ \fIstring\fP)" 6 +.br +This usage sets a specific +.IR category +in the international environment to a specific value corresponding to +the value of the +.IR string . +A specific example is provided below: +.RS 6 +.sp +.RS 4 +.nf +\fB +setlocale(LC_ALL, "fr_FR.ISO-8859-1"); +.fi \fR +.P +.RE +.P +In this example, all categories of the international environment are +set to the locale corresponding to the string +.BR \(dqfr_FR.ISO-8859-1\(dq , +or to the French language as spoken in France using the ISO/IEC\ 8859\(hy1:\|1998 standard codeset. +.P +If the string does not correspond to a valid locale, +\fIsetlocale\fR() +shall return a null pointer and the international environment is not +changed. Otherwise, +\fIsetlocale\fR() +shall return the name of the locale just set. +.RE +.IP "\&\fIsetlocale\fP(\fIcategory\fP,\ \(dqC\(dq)" 6 +.br +The ISO\ C standard states that one locale must exist on all conforming +implementations. The name of the locale is C and corresponds to a +minimal international environment needed to support the C programming +language. +.IP "\&\fIsetlocale\fP(\fIcategory\fP,\ \(dq\^\(dq)" 6 +.br +This sets a specific category to an implementation-defined default. +This corresponds to the value of the environment variables. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIcatopen\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswblank\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fImblen\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fInl_langinfo\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)", +.IR "\fIstrerror\fR\^(\|)", +.IR "\fIstrfmon\fR\^(\|)", +.IR "\fIstrsignal\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIstrxfrm\fR\^(\|)", +.IR "\fItolower\fR\^(\|)", +.IR "\fItoupper\fR\^(\|)", +.IR "\fItowlower\fR\^(\|)", +.IR "\fItowupper\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)", +.IR "\fIwcscoll\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)", +.IR "\fIwcsxfrm\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setlogmask.3p b/man-pages-posix-2013-a/man3p/setlogmask.3p new file mode 100644 index 0000000..8968918 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setlogmask.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETLOGMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setlogmask +\(em set the log priority mask +.SH SYNOPSIS +.LP +.nf +#include +.P +int setlogmask(int \fImaskpri\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcloselog\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setnetent.3p b/man-pages-posix-2013-a/man3p/setnetent.3p new file mode 100644 index 0000000..a85c2a7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setnetent.3p @@ -0,0 +1,37 @@ +'\" et +.TH SETNETENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setnetent \(em network database function +.SH SYNOPSIS +.LP +.nf +#include +.P +void setnetent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendnetent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setpgid.3p b/man-pages-posix-2013-a/man3p/setpgid.3p new file mode 100644 index 0000000..c50508c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setpgid.3p @@ -0,0 +1,201 @@ +'\" et +.TH SETPGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setpgid +\(em set process group ID for job control +.SH SYNOPSIS +.LP +.nf +#include +.P +int setpgid(pid_t \fIpid\fP, pid_t \fIpgid\fP); +.fi +.SH DESCRIPTION +The +\fIsetpgid\fR() +function shall either join an existing process group or create a +new process group within the session of the calling process. +.P +The process group ID of a session leader shall not change. +.P +Upon successful completion, the process group ID of the process with +a process ID that matches +.IR pid +shall be set to +.IR pgid . +.P +As a special case, if +.IR pid +is 0, the process ID of the calling process shall be used. Also, if +.IR pgid +is 0, the process ID of the indicated process shall be used. +.SH "RETURN VALUE" +Upon successful completion, +\fIsetpgid\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIsetpgid\fR() +function shall fail if: +.TP +.BR EACCES +The value of the +.IR pid +argument matches the process ID of a child process of the calling +process and the child process has successfully executed one of the +.IR exec +functions. +.TP +.BR EINVAL +The value of the +.IR pgid +argument is less than 0, or is not a value supported by the +implementation. +.TP +.BR EPERM +The process indicated by the +.IR pid +argument is a session leader. +.TP +.BR EPERM +The value of the +.IR pid +argument matches the process ID of a child process of the calling +process and the child process is not in the same session as the calling +process. +.TP +.BR EPERM +The value of the +.IR pgid +argument is valid but does not match the process ID of the process +indicated by the +.IR pid +argument and there is no process with a process group ID that matches +the value of the +.IR pgid +argument in the same session as the calling process. +.TP +.BR ESRCH +The value of the +.IR pid +argument does not match the process ID of the calling process or of a +child process of the calling process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIsetpgid\fR() +function shall group processes together for the purpose of +signaling, placement in foreground or background, +and other job control actions. +.P +The +\fIsetpgid\fR() +function is similar to the +\fIsetpgrp\fR() +function of 4.2 BSD, except that 4.2 BSD allowed the specified new process +group to assume any value. This presents certain security problems and +is more +flexible than necessary to support job control. +.P +To provide tighter security, +\fIsetpgid\fR() +only allows the calling process to join a process group already in use +inside its session or create a new process group +whose process group ID was equal to its process ID. +.P +When a job control shell spawns a new job, the processes in the +job must be placed into a new process group via +\fIsetpgid\fR(). +There are two timing constraints involved in this action: +.IP " 1." 4 +The new process must be placed in the new process group before the +appropriate program is launched via one of the +.IR exec +functions. +.IP " 2." 4 +The new process must be placed in the new process group before the +shell can correctly send signals to the new process group. +.P +To address these constraints, the following actions are performed. The +new processes call +\fIsetpgid\fR() +to alter their own process groups after +\fIfork\fR() +but before +.IR exec . +This satisfies the first constraint. Under 4.3 BSD, the second +constraint is satisfied by the synchronization property of +.IR vfork (\|); +that is, the shell is suspended until the child has completed the +.IR exec , +thus ensuring that the child has completed the +\fIsetpgid\fR(). +A new version of +\fIfork\fR() +with this same synchronization property was considered, but it was +decided instead to merely allow the parent shell process to adjust the +process group of its child processes via +\fIsetpgid\fR(). +Both timing constraints are now satisfied by having both the parent +shell and the child attempt to adjust the process group of the child +process; it does not matter which succeeds first. +.P +Since it would be confusing to an application to have its process +group change after it began executing (that is, after +.IR exec ), +and because the child process would already have adjusted its process +group before this, the +.BR [EACCES] +error was added to disallow this. +.P +One non-obvious use of +\fIsetpgid\fR() +is to allow a job control shell to return itself to its original +process group (the one in effect when the job control shell was +executed). A job control shell does this before returning control back +to its parent when it is terminating or suspending itself as a way of +restoring its job control ``state'' back to what its parent would +expect. (Note that the original process group of the job control shell +typically matches the process group of its parent, but this is not +necessarily always the case.) +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)", +.IR "\fItcsetpgrp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setpgrp.3p b/man-pages-posix-2013-a/man3p/setpgrp.3p new file mode 100644 index 0000000..29367c1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setpgrp.3p @@ -0,0 +1,85 @@ +'\" et +.TH SETPGRP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setpgrp +\(em set the process group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t setpgrp(void); +.fi +.SH DESCRIPTION +If the calling process is not already a session leader, +\fIsetpgrp\fR() +sets the process group ID of the calling process to the process ID of +the calling process. If +\fIsetpgrp\fR() +creates a new session, then the new session has no controlling +terminal. +.P +The +\fIsetpgrp\fR() +function has no effect when the calling process is a session leader. +.SH "RETURN VALUE" +Upon completion, +\fIsetpgrp\fR() +shall return the process group ID. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +It is unspecified whether this function behaves as +.IR setpgid (0,0) +or +\fIsetsid\fR() +unless the process is already a session leader. Therefore, applications +are encouraged to use +\fIsetpgid\fR() +or +\fIsetsid\fR() +as appropriate. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIsetpgrp\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetsid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setpriority.3p b/man-pages-posix-2013-a/man3p/setpriority.3p new file mode 100644 index 0000000..d7e1b59 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setpriority.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETPRIORITY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setpriority +\(em set the nice value +.SH SYNOPSIS +.LP +.nf +#include +.P +int setpriority(int \fIwhich\fP, id_t \fIwho\fP, int \fInice\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetpriority\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setprotoent.3p b/man-pages-posix-2013-a/man3p/setprotoent.3p new file mode 100644 index 0000000..53c5e7a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setprotoent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETPROTOENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setprotoent +\(em network protocol database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void setprotoent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendprotoent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setpwent.3p b/man-pages-posix-2013-a/man3p/setpwent.3p new file mode 100644 index 0000000..958cbe1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setpwent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETPWENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setpwent +\(em user database function +.SH SYNOPSIS +.LP +.nf +#include +.P +void setpwent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendpwent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setregid.3p b/man-pages-posix-2013-a/man3p/setregid.3p new file mode 100644 index 0000000..29fe9e7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setregid.3p @@ -0,0 +1,135 @@ +'\" et +.TH SETREGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setregid +\(em set real and effective group IDs +.SH SYNOPSIS +.LP +.nf +#include +.P +int setregid(gid_t \fIrgid\fP, gid_t \fIegid\fP); +.fi +.SH DESCRIPTION +The +\fIsetregid\fR() +function shall set the real and effective group IDs of the calling +process. +.P +If +.IR rgid +is \(mi1, the real group ID shall not be changed; if +.IR egid +is \(mi1, the effective group ID shall not be changed. +.P +The real and effective group IDs may be set to different values in the +same call. +.P +Only a process with appropriate privileges can set the real group ID +and the effective group ID to any valid value. +.P +A non-privileged process can set either the real group ID to the saved +set-group-ID from one of the +.IR exec +family of functions, or the effective group ID to the saved +set-group-ID or the real group ID. +.P +If the real group ID is being set (\c +.IR rgid +is not \(mi1), or the effective group ID is being set to a value not +equal to the real group ID, then the saved set-group-ID of the current +process shall be set equal to the new effective group ID. +.P +Any supplementary group IDs of the calling process remain unchanged. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error, and neither of the group IDs are changed. +.SH ERRORS +The +\fIsetregid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR rgid +or +.IR egid +argument is invalid or out-of-range. +.TP +.BR EPERM +The process does not have appropriate privileges and a change other +than changing the real group ID to the saved set-group-ID, or changing +the effective group ID to the real group ID or the saved set-group-ID, +was requested. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If a non-privileged set-group-ID process sets its effective group ID to +its real group ID, it can only set its effective group ID back to the +previous value if +.IR rgid +was \(mi1 in the +\fIsetregid\fR() +call, since the saved-group-ID is not changed in that case. If +.IR rgid +was equal to the real group ID in the +\fIsetregid\fR() +call, then the saved set-group-ID will also have been changed to the +real user ID. +.SH RATIONALE +Earlier versions of this standard did not specify whether the saved +set-group-ID was affected by +\fIsetregid\fR() +calls. This version specifies common existing practice that constitutes an +important security feature. The ability to set both the effective group +ID and saved set-group-ID to be the same as the real group ID means that +any security weakness in code that is executed after that point cannot +result in malicious code being executed with the previous effective +group ID. Privileged applications could already do this using just +\fIsetgid\fR(), +but for non-privileged applications the only standard method available +is to use this feature of +\fIsetregid\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setreuid.3p b/man-pages-posix-2013-a/man3p/setreuid.3p new file mode 100644 index 0000000..6d7982f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setreuid.3p @@ -0,0 +1,141 @@ +'\" et +.TH SETREUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setreuid +\(em set real and effective user IDs +.SH SYNOPSIS +.LP +.nf +#include +.P +int setreuid(uid_t \fIruid\fP, uid_t \fIeuid\fP); +.fi +.SH DESCRIPTION +The +\fIsetreuid\fR() +function shall set the real and effective user IDs of the current +process to the values specified by the +.IR ruid +and +.IR euid +arguments. If +.IR ruid +or +.IR euid +is \(mi1, the corresponding effective or real user ID of the current +process shall be left unchanged. +.P +A process with appropriate privileges can set either ID to any value. +An unprivileged process can only set the effective user ID if the +.IR euid +argument is equal to either the real, effective, or saved user ID of +the process. +.P +If the real user ID is being set (\c +.IR ruid +is not \(mi1), or the effective user ID is being set to a value not +equal to the real user ID, then the saved set-user-ID of the current +process shall be set equal to the new effective user ID. +.P +It is unspecified whether a process without appropriate privileges is +permitted to change the real user ID to match the current effective user +ID or saved set-user-ID of the process. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetreuid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR ruid +or +.IR euid +argument is invalid or out-of-range. +.TP +.BR EPERM +The current process does not have appropriate privileges, and either an +attempt was made to change the effective user ID to a value other than +the real user ID or the saved set-user-ID or an attempt was made to +change the real user ID to a value not permitted by the +implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Setting the Effective User ID to the Real User ID" +.P +The following example sets the effective user ID of the calling process +to the real user ID, so that files created later will be owned by the +current user. It also sets the saved set-user-ID to the real user ID, +so any future attempt to set the effective user ID back to its previous +value will fail. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +setreuid(getuid(), getuid()); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Earlier versions of this standard did not specify whether the saved +set-user-ID was affected by +\fIsetreuid\fR() +calls. This version specifies common existing practice that constitutes +an important security feature. The ability to set both the effective user +ID and saved set-user-ID to be the same as the real user ID means that +any security weakness in code that is executed after that point cannot +result in malicious code being executed with the previous effective user +ID. Privileged applications could already do this using just +\fIsetuid\fR(), +but for non-privileged applications the only standard method available +is to use this feature of +\fIsetreuid\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setrlimit.3p b/man-pages-posix-2013-a/man3p/setrlimit.3p new file mode 100644 index 0000000..00c2a17 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setrlimit.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETRLIMIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setrlimit +\(em control maximum resource consumption +.SH SYNOPSIS +.LP +.nf +#include +.P +int setrlimit(int \fIresource\fP, const struct rlimit *\fIrlp\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetrlimit\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setservent.3p b/man-pages-posix-2013-a/man3p/setservent.3p new file mode 100644 index 0000000..df868c9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setservent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETSERVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setservent +\(em network services database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void setservent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendservent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setsid.3p b/man-pages-posix-2013-a/man3p/setsid.3p new file mode 100644 index 0000000..4eb4e0e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setsid.3p @@ -0,0 +1,111 @@ +'\" et +.TH SETSID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setsid +\(em create session and set process group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t setsid(void); +.fi +.SH DESCRIPTION +The +\fIsetsid\fR() +function shall create a new session, if the calling process is not a +process group leader. Upon return the calling process shall be the +session leader of this new session, shall be the process group leader +of a new process group, and shall have no controlling terminal. The +process group ID of the calling process shall be set equal to the +process ID of the calling process. The calling process shall be the +only process in the new process group and the only process in the new +session. +.SH "RETURN VALUE" +Upon successful completion, +\fIsetsid\fR() +shall return the value of the new process group ID of the calling +process. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsetsid\fR() +function shall fail if: +.TP +.BR EPERM +The calling process is already a process group leader, or the process +group ID of a process other than the calling process matches the +process ID of the calling process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIsetsid\fR() +function is similar to the +\fIsetpgrp\fR() +function of System V. +System V, without job control, groups processes into +process groups and creates new process groups via +\fIsetpgrp\fR(); +only one process group may be part of a login session. +.P +Job control allows multiple process groups within a login session. In +order to limit job control actions so that they can only affect +processes in the same login session, this volume of POSIX.1\(hy2008 adds the concept of a +session that is created via +\fIsetsid\fR(). +The +\fIsetsid\fR() +function also creates the initial process group contained in the +session. Additional process groups can be created via the +\fIsetpgid\fR() +function. A System V process group would correspond to a POSIX System +Interfaces session containing a single POSIX process group. Note that +this function requires that the calling process not be a process group +leader. The usual way to ensure this is true is to create a new process +with +\fIfork\fR() +and have it call +\fIsetsid\fR(). +The +\fIfork\fR() +function guarantees that the process ID of the new process does not +match any existing process group ID. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetpgrp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setsockopt.3p b/man-pages-posix-2013-a/man3p/setsockopt.3p new file mode 100644 index 0000000..cff6e9f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setsockopt.3p @@ -0,0 +1,165 @@ +'\" et +.TH SETSOCKOPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setsockopt +\(em set the socket options +.SH SYNOPSIS +.LP +.nf +#include +.P +int setsockopt(int \fIsocket\fP, int \fIlevel\fP, int \fIoption_name\fP, + const void *\fIoption_value\fP, socklen_t \fIoption_len\fP); +.fi +.SH DESCRIPTION +The +\fIsetsockopt\fR() +function shall set the option specified by the +.IR option_name +argument, at the protocol level specified by the +.IR level +argument, to the value pointed to by the +.IR option_value +argument for the socket associated with the file descriptor specified +by the +.IR socket +argument. +.P +The +.IR level +argument specifies the protocol level at which the option resides. To +set options at the socket level, specify the +.IR level +argument as SOL_SOCKET. To set options at other levels, supply the +appropriate +.IR level +identifier for the protocol controlling the option. For example, to +indicate that an option is interpreted by the TCP (Transport Control +Protocol), set +.IR level +to IPPROTO_TCP as defined in the +.IR +header. +.P +The +.IR option_name +argument specifies a single option to set. It can be one of the +socket-level options defined in +.IR "\fB\fP" +and described in +.IR "Section 2.10.16" ", " "Use of Options". +If +.IR option_name +is equal to SO_RCVTIMEO or SO_SNDTIMEO and the implementation supports +setting the option, it is unspecified whether the +.BR "struct timeval" +pointed to by +.IR option_value +is stored as provided by this function or is rounded up to align with +the resolution of the clock being used. If +\fIsetsockopt\fR() +is called with +.IR option_name +equal to SO_ACCEPTCONN, SO_ERROR, or SO_TYPE, the behavior is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIsetsockopt\fR() +shall return 0. Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetsockopt\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EDOM +The send and receive timeout values are too big to fit into the timeout +fields in the socket structure. +.TP +.BR EINVAL +The specified option is invalid at the specified socket level or the +socket has been shut down. +.TP +.BR EISCONN +The socket is already connected, and a specified option cannot be set +while the socket is connected. +.TP +.BR ENOPROTOOPT +.br +The option is not supported by the protocol. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.P +The +\fIsetsockopt\fR() +function may fail if: +.TP +.BR ENOMEM +There was insufficient memory available for the operation to complete. +.TP +.BR ENOBUFS +Insufficient resources are available in the system to complete the +call. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIsetsockopt\fR() +function provides an application program with the means to control +socket behavior. An application program can use +\fIsetsockopt\fR() +to allocate buffer space, control timeouts, or permit socket data +broadcasts. The +.IR +header defines the socket-level options available to +\fIsetsockopt\fR(). +.P +Options may exist at multiple protocol levels. The SO_ options are +always present at the uppermost socket level. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.10" ", " "Sockets", +.IR "\fIbind\fR\^(\|)", +.IR "\fIendprotoent\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setstate.3p b/man-pages-posix-2013-a/man3p/setstate.3p new file mode 100644 index 0000000..c3e0fae --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setstate.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setstate +\(em switch pseudo-random number generator state arrays +.SH SYNOPSIS +.LP +.nf +#include +.P +char *setstate(char *\fIstate\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIinitstate\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setuid.3p b/man-pages-posix-2013-a/man3p/setuid.3p new file mode 100644 index 0000000..4bdd011 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setuid.3p @@ -0,0 +1,255 @@ +'\" et +.TH SETUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setuid +\(em set user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int setuid(uid_t \fIuid\fP); +.fi +.SH DESCRIPTION +If the process has appropriate privileges, +\fIsetuid\fR() +shall set the real user ID, effective user ID, and the saved +set-user-ID of the calling process to +.IR uid . +.P +If the process does not have appropriate privileges, but +.IR uid +is equal to the real user ID or the saved set-user-ID, +\fIsetuid\fR() +shall set the effective user ID to +.IR uid ; +the real user ID and saved set-user-ID shall remain unchanged. +.P +The +\fIsetuid\fR() +function shall not affect the supplementary group list in any way. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetuid\fR() +function shall fail, return \(mi1, and set +.IR errno +to the corresponding value if one or more of the following are true: +.TP +.BR EINVAL +The value of the +.IR uid +argument is invalid and not supported by the implementation. +.TP +.BR EPERM +The process does not have appropriate privileges and +.IR uid +does not match the real user ID or the saved set-user-ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The various behaviors of the +\fIsetuid\fR() +and +\fIsetgid\fR() +functions when called by non-privileged processes reflect the behavior +of different historical implementations. For portability, it is +recommended that new non-privileged applications use the +\fIseteuid\fR() +and +\fIsetegid\fR() +functions instead. +.P +The saved set-user-ID capability allows a program to regain the +effective user ID established at the last +.IR exec +call. Similarly, the saved set-group-ID capability allows a program to +regain the effective group ID established at the last +.IR exec +call. These capabilities are derived from System V. Without them, a +program might have to run as superuser in order to perform the same +functions, because superuser can write on the user's files. This is a +problem because such a program can write on any user's files, and so +must be carefully written to emulate the permissions of the calling +process properly. In System V, these capabilities have traditionally +been implemented only via the +\fIsetuid\fR() +and +\fIsetgid\fR() +functions for non-privileged processes. The fact that the behavior of +those functions was different for privileged processes made them +difficult to use. The POSIX.1\(hy1990 standard defined the +\fIsetuid\fR() +function to behave differently for privileged and unprivileged users. +When the caller had appropriate privileges, the function set the real +user ID, effective user ID, and saved set-user ID of the calling process +on implementations that supported it. When the caller did not have +appropriate privileges, the function set only the effective user ID, +subject to permission checks. The former use is generally needed for +utilities like +.IR login +and +.IR su , +which are not conforming applications and thus outside the scope of +POSIX.1\(hy2008. These utilities wish to change the user ID irrevocably to a new +value, generally that of an unprivileged user. The latter use is needed +for conforming applications that are installed with the set-user-ID bit +and need to perform operations using the real user ID. +.P +POSIX.1\(hy2008 augments the latter functionality with a mandatory feature named +_POSIX_SAVED_IDS. This feature permits a set-user-ID application to +switch its effective user ID back and forth between the values of its +.IR exec -time +real user ID and effective user ID. Unfortunately, the POSIX.1\(hy1990 standard did not +permit a conforming application using this feature to work properly when +it happened to be executed with (implementation-defined) +appropriate privileges. Furthermore, the application did not even have a +means to tell whether it had this privilege. Since the saved +set-user-ID feature is quite desirable for applications, as evidenced +by the fact that NIST required it in FIPS 151\(hy2, it has been mandated by +POSIX.1\(hy2008. However, there are implementors who have been reluctant to +support it given the limitation described above. +.P +The 4.3BSD system handles the problem by supporting separate +functions: +\fIsetuid\fR() +(which always sets both the real and effective user IDs, like +\fIsetuid\fR() +in POSIX.1\(hy2008 for privileged users), and +\fIseteuid\fR() +(which always sets just the effective user ID, like +\fIsetuid\fR() +in POSIX.1\(hy2008 for non-privileged users). This separation of functionality +into distinct functions seems desirable. 4.3BSD does not support the +saved set-user-ID feature. It supports similar functionality of +switching the effective user ID back and forth via +\fIsetreuid\fR(), +which permits reversing the real and effective user IDs. This model +seems less desirable than the saved set-user-ID because the real user +ID changes as a side-effect. The current 4.4BSD includes saved +effective IDs and uses them for +\fIseteuid\fR() +and +\fIsetegid\fR() +as described above. The +\fIsetreuid\fR() +and +\fIsetregid\fR() +functions will be deprecated or removed. +.P +The solution here is: +.IP " *" 4 +Require that all implementations support the functionality of the saved +set-user-ID, which is set by the +.IR exec +functions and by privileged calls to +\fIsetuid\fR(). +.IP " *" 4 +Add the +\fIseteuid\fR() +and +\fIsetegid\fR() +functions as portable alternatives to +\fIsetuid\fR() +and +\fIsetgid\fR() +for non-privileged and privileged processes. +.P +Historical systems have provided two mechanisms for a set-user-ID +process to change its effective user ID to be the same as its real user +ID in such a way that it could return to the original effective user +ID: the use of the +\fIsetuid\fR() +function in the presence of a saved set-user-ID, or the use of the BSD +\fIsetreuid\fR() +function, which was able to swap the real and effective user IDs. The +changes included in POSIX.1\(hy2008 provide a new mechanism using +\fIseteuid\fR() +in conjunction with a saved set-user-ID. Thus, all implementations with +the new +\fIseteuid\fR() +mechanism will have a saved set-user-ID for each process, and most of +the behavior controlled by _POSIX_SAVED_IDS has been changed +to agree with the case where the option was defined. The +\fIkill\fR() +function is an exception. Implementors of the new +\fIseteuid\fR() +mechanism will generally be required to maintain compatibility with the +older mechanisms previously supported by their systems. However, +compatibility with this use of +\fIsetreuid\fR() +and with the _POSIX_SAVED_IDS behavior of +\fIkill\fR() +is unfortunately complicated. If an implementation with a saved +set-user-ID allows a process to use +\fIsetreuid\fR() +to swap its real and effective user IDs, but were to leave the saved +set-user-ID unmodified, the process would then have an effective user +ID equal to the original real user ID, and both real and saved +set-user-ID would be equal to the original effective user ID. In that +state, the real user would be unable to kill the process, even though +the effective user ID of the process matches that of the real user, if +the +\fIkill\fR() +behavior of _POSIX_SAVED_IDS was used. This is obviously not +acceptable. The alternative choice, which is used in at least one +implementation, is to change the saved set-user-ID to the effective +user ID during most calls to +\fIsetreuid\fR(). +The standard developers considered that alternative to be less correct +than the retention of the old behavior of +\fIkill\fR() +in such systems. Current conforming applications shall accommodate +either behavior from +\fIkill\fR(), +and there appears to be no strong reason for +\fIkill\fR() +to check the saved set-user-ID rather than the effective user ID. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setutxent.3p b/man-pages-posix-2013-a/man3p/setutxent.3p new file mode 100644 index 0000000..d0cc57e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setutxent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETUTXENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setutxent +\(em reset the user accounting database to the first entry +.SH SYNOPSIS +.LP +.nf +#include +.P +void setutxent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendutxent\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/setvbuf.3p b/man-pages-posix-2013-a/man3p/setvbuf.3p new file mode 100644 index 0000000..ab401c6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/setvbuf.3p @@ -0,0 +1,124 @@ +'\" et +.TH SETVBUF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +setvbuf +\(em assign buffering to a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int setvbuf(FILE *restrict \fIstream\fP, char *restrict \fIbuf\fP, int \fItype\fP, + size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIsetvbuf\fR() +function may be used after the stream pointed to by +.IR stream +is associated with an open file but before any other operation +(other than an unsuccessful call to +\fIsetvbuf\fR()) +is performed on the stream. The argument +.IR type +determines how +.IR stream +shall be buffered, as follows: +.IP " *" 4 +{_IOFBF} shall cause input/output to be fully buffered. +.IP " *" 4 +{_IOLBF} shall cause input/output to be line buffered. +.IP " *" 4 +{_IONBF} shall cause input/output to be unbuffered. +.P +If +.IR buf +is not a null pointer, the array it points to may be used instead of a +buffer allocated by +\fIsetvbuf\fR() +and the argument +.IR size +specifies the size of the array; otherwise, +.IR size +may determine the size of a buffer allocated by the +\fIsetvbuf\fR() +function. The contents of the array at any time are unspecified. +.P +For information about streams, see +.IR "Section 2.5" ", " "Standard I/O Streams". +.SH "RETURN VALUE" +Upon successful completion, +\fIsetvbuf\fR() +shall return 0. Otherwise, it shall return a non-zero value if an +invalid value is given for +.IR type +or if the request cannot be honored, +and may set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsetvbuf\fR() +function may fail if: +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +A common source of error is allocating buffer space as an ``automatic'' +variable in a code block, and then failing to close the stream in the +same block. +.P +With +\fIsetvbuf\fR(), +allocating a buffer of +.IR size +bytes does not necessarily imply that all of +.IR size +bytes are used for the buffer area. +.P +Applications should note that many implementations only provide line +buffering on input from terminal devices. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/shm_open.3p b/man-pages-posix-2013-a/man3p/shm_open.3p new file mode 100644 index 0000000..7857174 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/shm_open.3p @@ -0,0 +1,400 @@ +'\" et +.TH SHM_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shm_open +\(em open a shared memory object +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int shm_open(const char *\fIname\fP, int \fIoflag\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIshm_open\fR() +function shall establish a connection between a shared memory object +and a file descriptor. It shall create an open file description that +refers to the shared memory object and a file descriptor that refers to +that open file description. The file descriptor is used by other +functions to refer to that shared memory object. The +.IR name +argument points to a string naming a shared memory object. It is +unspecified whether the name appears in the file system and is visible +to other functions that take pathnames as arguments. The +.IR name +argument conforms to the construction rules for a pathname, except that +the interpretation of + +characters other than the leading + +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as the +pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the + +character, then processes calling +\fIshm_open\fR() +with the same value of +.IR name +refer to the same shared memory object, as long as that name has not +been removed. If +.IR name +does not begin with the + +character, the effect is implementation-defined. +.P +If successful, +\fIshm_open\fR() +shall return a file descriptor for the shared memory object that is the +lowest numbered file descriptor not currently open for that process. +The open file description is new, and therefore the file descriptor +does not share it with any other processes. It is unspecified whether +the file offset is set. The FD_CLOEXEC +file descriptor flag associated with the new file descriptor is set. +.P +The file status flags and file access modes of the open file +description are according to the value of +.IR oflag . +The +.IR oflag +argument is the bitwise-inclusive OR of the following flags defined in +the +.IR +header. Applications specify exactly one of the first two values +(access modes) below in the value of +.IR oflag : +.IP O_RDONLY 12 +Open for read access only. +.IP O_RDWR 12 +Open for read or write access. +.P +Any combination of the remaining flags may be specified in the value of +.IR oflag : +.IP O_CREAT 12 +If the shared memory object exists, this flag has no effect, except +as noted under O_EXCL below. Otherwise, the shared memory object is +created. The user ID of the shared memory object shall be set to the +effective user ID of the process. The group ID of the shared memory object +shall be set to the effective group ID of the process; however, if the +.IR name +argument is visible in the file system, the group ID may be set to the +group ID of the containing directory. The permission bits of the shared +memory object shall be set to the value of the +.IR mode +argument except those set in the file mode creation mask of the +process. When bits in +.IR mode +other than the file permission bits are set, the effect is +unspecified. The +.IR mode +argument does not affect whether the shared memory object is opened for +reading, for writing, or for both. The shared memory object has a size +of zero. +.IP O_EXCL 12 +If O_EXCL and O_CREAT are set, +\fIshm_open\fR() +fails if the shared memory object exists. The check for the existence +of the shared memory object and the creation of the object if it does +not exist is atomic with respect to other processes executing +\fIshm_open\fR() +naming the same shared memory object with O_EXCL and O_CREAT set. If +O_EXCL is set and O_CREAT is not set, the result is undefined. +.IP O_TRUNC 12 +If the shared memory object exists, and it is successfully opened +O_RDWR, the object shall be truncated to zero length and the mode and +owner shall be unchanged by this function call. The result of using +O_TRUNC with O_RDONLY is undefined. +.P +When a shared memory object is created, the state of the shared memory +object, including all data associated with the shared memory object, +persists until the shared memory object is unlinked and all other +references are gone. It is unspecified whether the name and shared +memory object state remain valid after a system reboot. +.SH "RETURN VALUE" +Upon successful completion, the +\fIshm_open\fR() +function shall return a non-negative integer representing the lowest +numbered unused file descriptor. Otherwise, it shall return \(mi1 and +set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIshm_open\fR() +function shall fail if: +.TP +.BR EACCES +The shared memory object exists and the permissions specified by +.IR oflag +are denied, or the shared memory object does not exist and permission +to create the shared memory object is denied, or O_TRUNC is specified +and write permission is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set and +the named shared memory object already exists. +.TP +.BR EINTR +The +\fIshm_open\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +The +\fIshm_open\fR() +operation is not supported for the given name. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +Too many shared memory objects are currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and the named shared memory object does not exist. +.TP +.BR ENOSPC +There is insufficient space for the creation of the new shared memory +object. +.P +The +\fIshm_open\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating and Mapping a Shared Memory Object" +.P +The following code segment demonstrates the use of +\fIshm_open\fR() +to create a shared memory object which is then sized using +\fIftruncate\fR() +before being mapped into the process address space using +\fImmap\fR(): +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +.P +#define MAX_LEN 10000 +struct region { /* Defines "structure" of shared memory */ + int len; + char buf[MAX_LEN]; +}; +struct region *rptr; +int fd; +.P +/* Create shared memory object and set its size */ +.P +fd = shm_open("/myregion", O_CREAT | O_RDWR, S_IRUSR | S_IWUSR); +if (fd == \(mi1) + /* Handle error */; +.P +if (ftruncate(fd, sizeof(struct region)) == \(mi1) + /* Handle error */; +.P +/* Map shared memory object */ +.P +rptr = mmap(NULL, sizeof(struct region), + PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); +if (rptr == MAP_FAILED) + /* Handle error */; +.P +/* Now we can refer to mapped region using fields of rptr; + for example, rptr->len */ +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +When the Memory Mapped Files option is supported, the normal +\fIopen\fR() +call is used to obtain a descriptor to a file to be mapped according to +existing practice with +\fImmap\fR(). +When the Shared Memory Objects option is supported, the +\fIshm_open\fR() +function shall obtain a descriptor to the shared memory object +to be mapped. +.P +There is ample precedent for having a file descriptor represent several +types of objects. In the POSIX.1\(hy1990 standard, a file descriptor can represent a +file, a pipe, a FIFO, a tty, or a directory. Many implementations +simply have an operations vector, which is indexed by the file +descriptor type and does very different operations. Note that in some +cases the file descriptor passed to generic operations on file +descriptors is returned by +\fIopen\fR() +or +\fIcreat\fR() +and in some cases returned by alternate functions, such as +\fIpipe\fR(). +The latter technique is used by +\fIshm_open\fR(). +.P +Note that such shared memory objects can actually be implemented as +mapped files. In both cases, the size can be set after the open using +\fIftruncate\fR(). +The +\fIshm_open\fR() +function itself does not create a shared object of a specified size +because this would duplicate an extant function that set the size of +an object referenced by a file descriptor. +.P +On implementations where memory objects are implemented using the +existing file system, the +\fIshm_open\fR() +function may be implemented using a macro that invokes +\fIopen\fR(), +and the +\fIshm_unlink\fR() +function may be implemented using a macro that invokes +\fIunlink\fR(). +.P +For implementations without a permanent file system, the definition of +the name of the memory objects is allowed not to survive a system +reboot. Note that this allows systems with a permanent file system to +implement memory objects as data structures internal to the +implementation as well. +.P +On implementations that choose to implement memory objects using memory +directly, a +\fIshm_open\fR() +followed by an +\fIftruncate\fR() +and +\fIclose\fR() +can be used to preallocate a shared memory area and to set the size of +that preallocation. This may be necessary for systems without virtual +memory hardware support in order to ensure that the memory is +contiguous. +.P +The set of valid open flags to +\fIshm_open\fR() +was restricted to O_RDONLY, O_RDWR, O_CREAT, and O_TRUNC +because these could be easily implemented on most memory mapping +systems. This volume of POSIX.1\(hy2008 is silent on the results if the implementation +cannot supply the requested file access because of +implementation-defined reasons, including hardware ones. +.P +The error conditions +.BR [EACCES] +and +.BR [ENOTSUP] +are provided to inform the application that the implementation cannot +complete a request. +.P +.BR [EACCES] +indicates for implementation-defined reasons, probably +hardware-related, that the implementation cannot comply with a +requested mode because it conflicts with another requested mode. An +example might be that an application desires to open a memory object +two times, mapping different areas with different access modes. If the +implementation cannot map a single area into a process space in two +places, which would be required if different access modes were required +for the two areas, then the implementation may inform the application +at the time of the second open. +.P +.BR [ENOTSUP] +indicates for implementation-defined reasons, probably +hardware-related, that the implementation cannot comply with a +requested mode at all. An example would be that the hardware of the +implementation cannot support write-only shared memory areas. +.P +On all implementations, it may be desirable to restrict the location of +the memory objects to specific file systems for performance (such as a +RAM disk) or implementation-defined reasons (shared memory supported +directly only on certain file systems). The +\fIshm_open\fR() +function may be used to enforce these restrictions. There are a number +of methods available to the application to determine an appropriate +name of the file or the location of an appropriate directory. One way +is from the environment via +\fIgetenv\fR(). +Another would be from a configuration file. +.P +This volume of POSIX.1\(hy2008 specifies that memory objects have initial contents of +zero when created. This is consistent with current behavior for both +files and newly allocated memory. For those implementations that use +physical memory, it would be possible that such implementations could +simply use available memory and give it to the process uninitialized. +This, however, is not consistent with standard behavior for the +uninitialized data area, the stack, and of course, files. Finally, it +is highly desirable to set the allocated memory to zero for security +reasons. Thus, initializing memory objects to zero is required. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fIshm_open\fR() +and +\fIshm_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fIclose\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/shm_unlink.3p b/man-pages-posix-2013-a/man3p/shm_unlink.3p new file mode 100644 index 0000000..6d19b3b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/shm_unlink.3p @@ -0,0 +1,139 @@ +'\" et +.TH SHM_UNLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shm_unlink +\(em remove a shared memory object +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int shm_unlink(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fIshm_unlink\fR() +function shall remove the name of the shared memory object named +by the string pointed to by +.IR name . +.P +If one or more references to the shared memory object exist when the +object is unlinked, the name shall be removed before +\fIshm_unlink\fR() +returns, but the removal of the memory object contents shall be postponed +until all open and map references to the shared memory object have been +removed. +.P +Even if the object continues to exist after the last +\fIshm_unlink\fR(), +reuse of the name shall subsequently cause +\fIshm_open\fR() +to behave as if no shared memory object of this name exists (that is, +\fIshm_open\fR() +will fail if O_CREAT is not set, or will create a new shared memory +object if O_CREAT is set). +.SH "RETURN VALUE" +Upon successful completion, a value of zero shall be returned. +Otherwise, a value of \(mi1 shall be returned and +.IR errno +set to indicate the error. If \(mi1 is returned, the named shared +memory object shall not be changed by this function call. +.SH ERRORS +The +\fIshm_unlink\fR() +function shall fail if: +.TP +.BR EACCES +Permission is denied to unlink the named shared memory object. +.TP +.BR ENOENT +The named shared memory object does not exist. +.P +The +\fIshm_unlink\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +A call to +\fIshm_unlink\fR() +with a +.IR name +argument that contains the same shared memory object name as was +previously used in a successful +\fIshm_open\fR() +call shall not give an +.BR [ENAMETOOLONG] +error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Names of memory objects that were allocated with +\fIopen\fR() +are deleted with +\fIunlink\fR() +in the usual fashion. Names of memory objects that were allocated with +\fIshm_open\fR() +are deleted with +\fIshm_unlink\fR(). +Note that the actual memory object is not destroyed until the +last close and unmap on it have occurred if it was already in use. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fIshm_open\fR() +and +\fIshm_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fIclose\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/shmat.3p b/man-pages-posix-2013-a/man3p/shmat.3p new file mode 100644 index 0000000..99855ef --- /dev/null +++ b/man-pages-posix-2013-a/man3p/shmat.3p @@ -0,0 +1,152 @@ +'\" et +.TH SHMAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shmat +\(em XSI shared memory attach operation +.SH SYNOPSIS +.LP +.nf +#include +.P +void *shmat(int \fIshmid\fP, const void *\fIshmaddr\fP, int \fIshmflg\fP); +.fi +.SH DESCRIPTION +The +\fIshmat\fR() +function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIshmat\fR() +function attaches the shared memory segment associated with the shared +memory identifier specified by +.IR shmid +to the address space of the calling process. The segment is attached +at the address specified by one of the following criteria: +.IP " *" 4 +If +.IR shmaddr +is a null pointer, the segment is attached at the first available +address as selected by the system. +.IP " *" 4 +If +.IR shmaddr +is not a null pointer and (\fIshmflg\fP &SHM_RND) +is non-zero, the segment is attached at the address given by +(\fIshmaddr\fP \(mi((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)). The +character +.BR '%' +is the C-language remainder operator. +.IP " *" 4 +If +.IR shmaddr +is not a null pointer and (\fIshmflg\fP &SHM_RND) is 0, the segment is +attached at the address given by +.IR shmaddr . +.IP " *" 4 +The segment is attached for reading if (\fIshmflg\fP &SHM_RDONLY) +is non-zero and the calling process has read permission; otherwise, if +it is 0 and the calling process has read and write permission, the +segment is attached for reading and writing. +.SH "RETURN VALUE" +Upon successful completion, +\fIshmat\fR() +shall increment the value of +.IR shm_nattch +in the data structure associated with the shared memory ID of the +attached shared memory segment and return the segment's start address. +Also, the +.IR shm_atime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +Otherwise, the shared memory segment shall not be attached, +\fIshmat\fR() +shall return \(mi1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIshmat\fR() +function shall fail if: +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EINVAL +The value of +.IR shmid +is not a valid shared memory identifier, the +.IR shmaddr +is not a null pointer, and the value of +(\fIshmaddr\fP \(mi((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)) +is an illegal address for attaching shared memory; or the +.IR shmaddr +is not a null pointer, (\fIshmflg\fP &SHM_RND) is 0, and the value of +.IR shmaddr +is an illegal address for attaching shared memory. +.TP +.BR EMFILE +The number of shared memory segments attached to the calling process +would exceed the system-imposed limit. +.TP +.BR ENOMEM +The available data space is not large enough to accommodate the shared +memory segment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/shmctl.3p b/man-pages-posix-2013-a/man3p/shmctl.3p new file mode 100644 index 0000000..18de0ba --- /dev/null +++ b/man-pages-posix-2013-a/man3p/shmctl.3p @@ -0,0 +1,190 @@ +'\" et +.TH SHMCTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shmctl +\(em XSI shared memory control operations +.SH SYNOPSIS +.LP +.nf +#include +.P +int shmctl(int \fIshmid\fP, int \fIcmd\fP, struct shmid_ds *\fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fIshmctl\fR() +function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIshmctl\fR() +function provides a variety of shared memory control operations as +specified by +.IR cmd . +The following values for +.IR cmd +are available: +.IP IPC_STAT 12 +Place the current value of each member of the +.BR shmid_ds +data structure associated with +.IR shmid +into the structure pointed to by +.IR buf . +The contents of the structure are defined in +.IR . +.IP IPC_SET 12 +Set the value of the following members of the +.BR shmid_ds +data structure associated with +.IR shmid +to the corresponding value found in the structure pointed to by +.IR buf : +.RS 12 +.sp +.RS 4 +.nf +\fB +shm_perm.uid +shm_perm.gid +shm_perm.mode \fRLow-order nine bits.\fP +.fi \fR +.P +.RE +.P +Also, the +.IR shm_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +IPC_SET can only be executed by a process that has an effective user ID +equal to either that of a process with appropriate privileges or to the +value of +.IR shm_perm.cuid +or +.IR shm_perm.uid +in the +.BR shmid_ds +data structure associated with +.IR shmid . +.RE +.IP IPC_RMID 12 +Remove the shared memory identifier specified by +.IR shmid +from the system and destroy the shared memory segment and +.BR shmid_ds +data structure associated with it. IPC_RMID can only be executed by a +process that has an effective user ID equal to either that of a process +with appropriate privileges or to the value of +.IR shm_perm.cuid +or +.IR shm_perm.uid +in the +.BR shmid_ds +data structure associated with +.IR shmid . +.SH "RETURN VALUE" +Upon successful completion, +\fIshmctl\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIshmctl\fR() +function shall fail if: +.TP +.BR EACCES +The argument +.IR cmd +is equal to IPC_STAT and the calling process does not have read +permission; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EINVAL +The value of +.IR shmid +is not a valid shared memory identifier, or the value of +.IR cmd +is not a valid command. +.TP +.BR EPERM +The argument +.IR cmd +is equal to IPC_RMID or IPC_SET and the effective user ID of the +calling process is not equal to that of a process with appropriate +privileges and it is not equal to the value of +.IR shm_perm.cuid +or +.IR shm_perm.uid +in the data structure associated with +.IR shmid . +.br +.P +The +\fIshmctl\fR() +function may fail if: +.TP +.BR EOVERFLOW +The +.IR cmd +argument is IPC_STAT and the +.IR gid +or +.IR uid +value is too large to be stored in the structure pointed to by the +.IR buf +argument. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/shmdt.3p b/man-pages-posix-2013-a/man3p/shmdt.3p new file mode 100644 index 0000000..0ad0c16 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/shmdt.3p @@ -0,0 +1,105 @@ +'\" et +.TH SHMDT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shmdt +\(em XSI shared memory detach operation +.SH SYNOPSIS +.LP +.nf +#include +.P +int shmdt(const void *\fIshmaddr\fP); +.fi +.SH DESCRIPTION +The +\fIshmdt\fR() +function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIshmdt\fR() +function detaches the shared memory segment located at the address +specified by +.IR shmaddr +from the address space of the calling process. +.SH "RETURN VALUE" +Upon successful completion, +\fIshmdt\fR() +shall decrement the value of +.IR shm_nattch +in the data structure associated with the shared memory ID of the +attached shared memory segment and return 0. Also, the +.IR shm_dtime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +Otherwise, the shared memory segment shall not be detached, +\fIshmdt\fR() +shall return \(mi1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIshmdt\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR shmaddr +is not the data segment start address of a shared memory segment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/shmget.3p b/man-pages-posix-2013-a/man3p/shmget.3p new file mode 100644 index 0000000..ca1281e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/shmget.3p @@ -0,0 +1,183 @@ +'\" et +.TH SHMGET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shmget +\(em get an XSI shared memory segment +.SH SYNOPSIS +.LP +.nf +#include +.P +int shmget(key_t \fIkey\fP, size_t \fIsize\fP, int \fIshmflg\fP); +.fi +.SH DESCRIPTION +The +\fIshmget\fR() +function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIshmget\fR() +function shall return the shared memory identifier associated with +.IR key . +.P +A shared memory identifier, associated data structure, and shared +memory segment of at least +.IR size +bytes (see +.IR ) +are created for +.IR key +if one of the following is true: +.IP " *" 4 +The argument +.IR key +is equal to IPC_PRIVATE. +.IP " *" 4 +The argument +.IR key +does not already have a shared memory identifier associated with it and +(\fIshmflg\fP &IPC_CREAT) is non-zero. +.P +Upon creation, the data structure associated with the new shared memory +identifier shall be initialized as follows: +.IP " *" 4 +The values of +.IR shm_perm.cuid , +.IR shm_perm.uid , +.IR shm_perm.cgid , +and +.IR shm_perm.gid +are set to the effective user ID and effective group ID, +respectively, of the calling process. +.IP " *" 4 +The low-order nine bits of +.IR shm_perm.mode +are set to the low-order nine bits of +.IR shmflg . +.IP " *" 4 +The value of +.IR shm_segsz +is set to the value of +.IR size . +.IP " *" 4 +The values of +.IR shm_lpid , +.IR shm_nattch , +.IR shm_atime , +and +.IR shm_dtime +are set to 0. +.IP " *" 4 +The value of +.IR shm_ctime +is set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +When the shared memory segment is created, it shall be initialized +with all zero values. +.SH "RETURN VALUE" +Upon successful completion, +\fIshmget\fR() +shall return a non-negative integer, namely a shared memory identifier; +otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIshmget\fR() +function shall fail if: +.TP +.BR EACCES +A shared memory identifier exists for +.IR key +but operation permission as specified by the low-order nine bits of +.IR shmflg +would not be granted; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EEXIST +A shared memory identifier exists for the argument +.IR key +but (\fIshmflg\fR &IPC_CREAT) &&(\fIshmflg\fR &IPC_EXCL) is non-zero. +.TP +.BR EINVAL +A shared memory segment is to be created and the value of size is +less than the system-imposed minimum or greater than the +system-imposed maximum. +.TP +.BR EINVAL +No shared memory segment is to be created and a shared memory +segment exists for +.IR key +but the size of the segment associated with it is less than +.IR size . +.TP +.BR ENOENT +A shared memory identifier does not exist for the argument +.IR key +and (\fIshmflg\fP &IPC_CREAT) is 0. +.TP +.BR ENOMEM +A shared memory identifier and associated shared memory segment shall +be created, but the amount of available physical memory is not +sufficient to fill the request. +.TP +.BR ENOSPC +A shared memory identifier is to be created, but the system-imposed +limit on the maximum number of allowed shared memory identifiers +system-wide would be exceeded. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIftok\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/shutdown.3p b/man-pages-posix-2013-a/man3p/shutdown.3p new file mode 100644 index 0000000..2fe1a0f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/shutdown.3p @@ -0,0 +1,126 @@ +'\" et +.TH SHUTDOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shutdown +\(em shut down socket send and receive operations +.SH SYNOPSIS +.LP +.nf +#include +.P +int shutdown(int \fIsocket\fP, int \fIhow\fP); +.fi +.SH DESCRIPTION +The +\fIshutdown\fR() +function shall cause all or part of a full-duplex connection on the +socket associated with the file descriptor +.IR socket +to be shut down. +.P +The +\fIshutdown\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the file descriptor of the socket. +.IP "\fIhow\fR" 12 +Specifies the type of shutdown. The values are as follows: +.RS 12 +.IP SHUT_RD 12 +Disables further receive operations. +.IP SHUT_WR 12 +Disables further send operations. +.IP SHUT_RDWR 12 +Disables further send and receive operations. +.RE +.P +The +\fIshutdown\fR() +function disables subsequent send and/or receive operations on a +socket, depending on the value of the +.IR how +argument. +.SH "RETURN VALUE" +Upon successful completion, +\fIshutdown\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIshutdown\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EINVAL +The +.IR how +argument is invalid. +.TP +.BR ENOTCONN +The socket is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.P +The +\fIshutdown\fR() +function may fail if: +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigaction.3p b/man-pages-posix-2013-a/man3p/sigaction.3p new file mode 100644 index 0000000..5d68eb2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigaction.3p @@ -0,0 +1,676 @@ +'\" et +.TH SIGACTION "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigaction +\(em examine and change a signal action +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigaction(int \fIsig\fP, const struct sigaction *restrict \fIact\fP, + struct sigaction *restrict \fIoact\fP); +.fi +.SH DESCRIPTION +The +\fIsigaction\fR() +function allows the calling process to examine and/or specify the +action to be associated with a specific signal. The argument +.IR sig +specifies the signal; acceptable values are defined in +.IR . +.P +The structure +.BR sigaction , +used to describe an action to be taken, is defined in the +.IR +header to include at least the following members: +.ad l +.TS +center box tab(!); +cB | cB | cB +lw(1.5i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +void(*) (int)!sa_handler!T{ +Pointer to a signal-catching function or one of the macros +SIG_IGN or SIG_DFL. +T} +sigset_t!sa_mask!T{ +Additional set of signals to be blocked during execution of +signal-catching function. +T} +int!sa_flags!T{ +Special flags to affect behavior of signal. +T} +T{ +void(*) (int, +.br +\0\0siginfo_t *, void *) +T}!sa_sigaction!Pointer to a signal-catching function. +.TE +.ad b +.P +The storage occupied by +.IR sa_handler +and +.IR sa_sigaction +may overlap, and a conforming application shall not use both +simultaneously. +.P +If the argument +.IR act +is not a null pointer, it points to a structure specifying the action +to be associated with the specified signal. If the argument +.IR oact +is not a null pointer, the action previously associated with the signal +is stored in the location pointed to by the argument +.IR oact . +If the argument +.IR act +is a null pointer, signal handling is unchanged; thus, the call can be +used to enquire about the current handling of a given signal. The +SIGKILL and SIGSTOP signals shall not be added to the signal +mask using this mechanism; this restriction shall be enforced by the +system without causing an error to be indicated. +.P +If the SA_SIGINFO flag (see below) is cleared in the +.IR sa_flags +field of the +.BR sigaction +structure, the +.IR sa_handler +field identifies the action to be associated with the specified signal. +If the SA_SIGINFO flag is set in the +.IR sa_flags +field, the +.IR sa_sigaction +field specifies a signal-catching function. +.P +The +.IR sa_flags +field can be used to modify the behavior of the specified signal. +.P +The following flags, defined in the +.IR +header, can be set in +.IR sa_flags : +.IP SA_NOCLDSTOP 14 +Do not generate SIGCHLD when children stop +or stopped children continue. +.RS 14 +.P +If +.IR sig +is SIGCHLD and the SA_NOCLDSTOP flag is not set in +.IR sa_flags , +and the implementation supports the SIGCHLD signal, then a SIGCHLD +signal shall be generated for the calling process whenever any of its +child processes stop +and a SIGCHLD signal may be generated for the calling +process whenever any of its stopped child processes are continued. +If +.IR sig +is SIGCHLD and the SA_NOCLDSTOP flag is set in +.IR sa_flags , +then the implementation shall not generate a SIGCHLD signal in this +way. +.RE +.IP SA_ONSTACK 14 +If set and an alternate signal stack has been declared with +\fIsigaltstack\fR(), +the signal shall be delivered to the calling process on that stack. +Otherwise, the signal shall be delivered on the current stack. +.IP SA_RESETHAND 14 +If set, the disposition of the signal shall be reset to SIG_DFL and the +SA_SIGINFO flag shall be cleared on entry to the signal handler. +.RS 14 +.TP 10 +.BR Note: +SIGILL and SIGTRAP cannot be automatically reset when delivered; the +system silently enforces this restriction. +.P +Otherwise, the disposition of the signal shall not be modified on entry +to the signal handler. +.P +In addition, if this flag is set, +\fIsigaction\fR() +may behave as if the SA_NODEFER flag were also set. +.RE +.IP SA_RESTART 14 +This flag affects the behavior of interruptible functions; that is, +those specified to fail with +.IR errno +set to +.BR [EINTR] . +If set, and a function specified as interruptible is interrupted by +this signal, the function shall restart and shall not fail with +.BR [EINTR] +unless otherwise specified. If an interruptible function which uses a +timeout is restarted, the duration of the timeout following the restart +is set to an unspecified value that does not exceed the original +timeout value. If the flag is not set, interruptible functions +interrupted by this signal shall fail with +.IR errno +set to +.BR [EINTR] . +.IP SA_SIGINFO 14 +If cleared and the signal is caught, the signal-catching function +shall be entered as: +.RS 14 +.sp +.RS 4 +.nf +\fB +void func(int \fIsigno\fP); +.fi \fR +.P +.RE +.P +where +.IR signo +is the only argument to the signal-catching function. In this case, the +application shall use the +.IR sa_handler +member to describe the signal-catching function and the application +shall not modify the +.IR sa_sigaction +member. +.P +If SA_SIGINFO is set and the signal is caught, the signal-catching +function shall be entered as: +.sp +.RS 4 +.nf +\fB +void func(int \fIsigno\fP, siginfo_t *\fIinfo\fP, void *\fIcontext\fP); +.fi \fR +.P +.RE +.P +where two additional arguments are passed to the signal-catching +function. The second argument shall point to an object of type +.BR siginfo_t +explaining the reason why the signal was generated; the third argument +can be cast to a pointer to an object of type +.BR ucontext_t +to refer to the receiving thread's context that was interrupted when +the signal was delivered. In this case, the application shall use the +.IR sa_sigaction +member to describe the signal-catching function and the application +shall not modify the +.IR sa_handler +member. +.P +The +.IR si_signo +member contains the system-generated signal number. +.P +The +.IR si_errno +member may contain implementation-defined additional error +information; if non-zero, it contains an error number identifying the +condition that caused the signal to be generated. +.P +The +.IR si_code +member contains a code identifying the cause of the signal, as +described in +.IR "Section 2.4.3" ", " "Signal Actions". +.RE +.IP SA_NOCLDWAIT 14 +If set, and +.IR sig +equals SIGCHLD, child processes of the calling processes shall not +be transformed into zombie processes when they terminate. If the calling +process subsequently waits for its children, and the process has no +unwaited-for children that were transformed into zombie processes, it +shall block until all of its children terminate, and +\fIwait\fR(), +\fIwaitid\fR(), +and +\fIwaitpid\fR() +shall fail and set +.IR errno +to +.BR [ECHILD] . +Otherwise, terminating child processes shall be transformed into zombie +processes, unless SIGCHLD is set to SIG_IGN. +.IP SA_NODEFER 14 +If set and +.IR sig +is caught, +.IR sig +shall not be added to the thread's signal mask on entry to the signal +handler unless it is included in +.IR sa_mask . +Otherwise, +.IR sig +shall always be added to the thread's signal mask on entry to the +signal handler. +.P +When a signal is caught by a signal-catching function installed by +\fIsigaction\fR(), +a new signal mask is calculated and installed for the duration of the +signal-catching function (or until a call to either +\fIsigprocmask\fR() +or +\fIsigsuspend\fR() +is made). This mask is formed by taking the union of the current +signal mask and the value of the +.IR sa_mask +for the signal being delivered, and unless SA_NODEFER or +SA_RESETHAND is set, +then including the signal being delivered. If and when the user's +signal handler returns normally, the original signal mask is restored. +.P +Once an action is installed for a specific signal, it shall remain +installed until another action is explicitly requested (by another +call to +\fIsigaction\fR()), +until the SA_RESETHAND flag causes resetting of the handler, +or until one of the +.IR exec +functions is called. +.P +If the previous action for +.IR sig +had been established by +\fIsignal\fR(), +the values of the fields returned in the structure pointed to by +.IR oact +are unspecified, and in particular +.IR oact ->\c +.IR sa_handler +is not necessarily the same value passed to +\fIsignal\fR(). +However, if a pointer to the same structure or a copy thereof is passed +to a subsequent call to +\fIsigaction\fR() +via the +.IR act +argument, handling of the signal shall be as if the original call to +\fIsignal\fR() +were repeated. +.P +If +\fIsigaction\fR() +fails, no new signal handler is installed. +.P +It is unspecified whether an attempt to set the action for a signal +that cannot be caught or ignored to SIG_DFL is ignored or causes an +error to be returned with +.IR errno +set to +.BR [EINVAL] . +.P +If SA_SIGINFO is not set in +.IR sa_flags , +then the disposition of subsequent occurrences of +.IR sig +when it is already pending is implementation-defined; the +signal-catching function shall be invoked with a single argument. +If SA_SIGINFO is set in +.IR sa_flags , +then subsequent occurrences of +.IR sig +generated by +\fIsigqueue\fR() +or as a result of any signal-generating function that supports the +specification of an application-defined value (when +.IR sig +is already pending) shall be queued in FIFO order until delivered or +accepted; the signal-catching function shall be invoked with three +arguments. The application specified value is passed to the +signal-catching function as the +.IR si_value +member of the +.BR siginfo_t +structure. +.P +The result of the use of +\fIsigaction\fR() +and a +\fIsigwait\fR() +function concurrently within a process on the same signal is +unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigaction\fR() +shall return 0; otherwise, \(mi1 shall be returned, +.IR errno +shall be set to indicate the error, and no new signal-catching function +shall be installed. +.br +.SH ERRORS +The +\fIsigaction\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR sig +argument is not a valid signal number or an attempt is made to catch a +signal that cannot be caught or ignore a signal that cannot be ignored. +.TP +.BR ENOTSUP +The SA_SIGINFO bit flag is set in the +.IR sa_flags +field of the +.BR sigaction +structure. +.P +The +\fIsigaction\fR() +function may fail if: +.TP +.BR EINVAL +An attempt was made to set the action to SIG_DFL for a signal that +cannot be caught or ignored (or both). +.P +In addition, the +\fIsigaction\fR() +function may fail if the SA_SIGINFO flag is set in the +.IR sa_flags +field of the +.BR sigaction +structure for a signal not in the range SIGRTMIN to SIGRTMAX. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Establishing a Signal Handler" +.P +The following example demonstrates the use of +\fIsigaction\fR() +to establish a handler for the SIGINT signal. +.sp +.RS 4 +.nf +\fB +#include +.P +static void handler(int signum) +{ + /* Take appropriate actions for signal delivery */ +} +.P +int main() +{ + struct sigaction sa; +.P + sa.sa_handler = handler; + sigemptyset(&sa.sa_mask); + sa.sa_flags = SA_RESTART; /* Restart functions if + interrupted by handler */ + if (sigaction(SIGINT, &sa, NULL) == \(mi1) + /* Handle error */; +.P + /* Further code */ +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIsigaction\fR() +function supersedes the +\fIsignal\fR() +function, and should be used in preference. In particular, +\fIsigaction\fR() +and +\fIsignal\fR() +should not be used in the same process to control the same signal. +The behavior of async-signal-safe functions, as defined in their +respective DESCRIPTION sections, is as specified by this volume of POSIX.1\(hy2008, regardless +of invocation from a signal-catching function. This is the only intended +meaning of the statement that async-signal-safe functions may be used in +signal-catching functions without restrictions. Applications must still +consider all effects of such functions on such things as data structures, +files, and process state. In particular, application developers need +to consider the restrictions on interactions when interrupting +\fIsleep\fR() +and interactions among multiple handles for a file description. The +fact that any specific function is listed as async-signal-safe does not +necessarily mean that invocation of that function from a +signal-catching function is recommended. +.P +In order to prevent errors arising from interrupting non-async-signal-safe +function calls, applications should protect calls to these functions +either by blocking the appropriate signals or through the use of some +programmatic semaphore (see +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +and so on). Note in particular that even the ``safe'' functions may +modify +.IR errno ; +the signal-catching function, if not executing as an independent +thread, should save and restore its value in order to avoid the +possibility that delivery of a signal in between an error return +from a function that sets +.IR errno +and the subsequent examination of +.IR errno +could result in the signal-catching function changing the value of +.IR errno . +Naturally, the same principles apply to the async-signal-safety of +application routines and asynchronous data access. Note that +\fIlongjmp\fR() +and +\fIsiglongjmp\fR() +are not in the list of async-signal-safe functions. This is because +the code executing after +\fIlongjmp\fR() +and +\fIsiglongjmp\fR() +can call any unsafe functions with the same danger as calling those +unsafe functions directly from the signal handler. Applications that +use +\fIlongjmp\fR() +and +\fIsiglongjmp\fR() +from within signal handlers require rigorous protection in order to be +portable. Many of the other functions that are excluded from the list +are traditionally implemented using either +\fImalloc\fR() +or +\fIfree\fR() +functions or the standard I/O library, both of which traditionally +use data structures in a non-async-signal-safe manner. Since any +combination of different functions using a common data structure can +cause async-signal-safety problems, this volume of POSIX.1\(hy2008 does not define the behavior +when any unsafe function is called in a signal handler that interrupts +an unsafe function. +.P +Usually, the signal is executed on the stack that was in effect before +the signal was delivered. An alternate stack may be specified to +receive a subset of the signals being caught. +.P +When the signal handler returns, the receiving thread resumes +execution at the point it was interrupted unless the signal handler +makes other arrangements. If +\fIlongjmp\fR() +or +\fI_longjmp\fR() +is used to leave the signal handler, then the signal mask must be +explicitly restored. +.P +This volume of POSIX.1\(hy2008 defines the third argument of a signal handling function when +SA_SIGINFO is set as a +.BR "void *" +instead of a +.BR "ucontext_t *" , +but without requiring type checking. New applications should +explicitly cast the third argument of the signal handling function to +.BR "ucontext_t *" . +.P +The BSD optional four argument signal handling function is not +supported by this volume of POSIX.1\(hy2008. The BSD declaration would be: +.sp +.RS 4 +.nf +\fB +void handler(int \fIsig\fP, int \fIcode\fP, struct sigcontext *\fIscp\fP, + char *\fIaddr\fP); +.fi \fR +.P +.RE +.P +where +.IR sig +is the signal number, +.IR code +is additional information on certain signals, +.IR scp +is a pointer to the +.BR sigcontext +structure, and +.IR addr +is additional address information. Much the same information is +available in the objects pointed to by the second argument of the +signal handler specified when SA_SIGINFO is set. +.P +Since the +\fIsigaction\fR() +function is allowed but not required to set SA_NODEFER when the +application sets the SA_RESETHAND flag, applications which depend on the +SA_RESETHAND functionality for the newly installed signal handler must +always explicitly set SA_NODEFER when they set SA_RESETHAND in order to +be portable. +.P +See also the rationale for Realtime Signal Generation and Delivery in +the Rationale (Informative) volume of POSIX.1\(hy2008, +.IR "Section B.2.4.2" ", " "Signal Generation and Delivery". +.SH RATIONALE +Although this volume of POSIX.1\(hy2008 requires that signals that cannot be ignored +shall not be added to the signal mask when a signal-catching function +is entered, there is no explicit requirement that subsequent calls to +\fIsigaction\fR() +reflect this in the information returned in the +.IR oact +argument. In other words, if SIGKILL +is included in the +.IR sa_mask +field of +.IR act , +it is unspecified whether or not a subsequent call to +\fIsigaction\fR() +returns with SIGKILL included in the +.IR sa_mask +field of +.IR oact . +.P +The SA_NOCLDSTOP +flag, when supplied in the +.IR act ->\c +.IR sa_flags +parameter, allows overloading SIGCHLD with the System V +semantics that each SIGCLD +signal indicates a single terminated child. Most conforming applications +that catch SIGCHLD are expected to install signal-catching functions +that repeatedly call the +\fIwaitpid\fR() +function with the WNOHANG +flag set, acting on each child for which status is returned, until +\fIwaitpid\fR() +returns zero. If stopped children are not of interest, the use of the +SA_NOCLDSTOP +flag can prevent the overhead from invoking the signal-catching routine +when they stop. +.P +Some historical implementations also define other mechanisms for +stopping processes, such as the +\fIptrace\fR() +function. These implementations usually do not generate a SIGCHLD +signal when processes stop due to this mechanism; however, that is +beyond the scope of this volume of POSIX.1\(hy2008. +.P +This volume of POSIX.1\(hy2008 requires that calls to +\fIsigaction\fR() +that supply a NULL +.IR act +argument succeed, even in the case of signals that cannot be caught or +ignored (that is, SIGKILL +or SIGSTOP). +The System V +\fIsignal\fR() +and BSD +\fIsigvec\fR() +functions return +.BR [EINVAL] +in these cases and, in this respect, their behavior varies from +\fIsigaction\fR(). +.P +This volume of POSIX.1\(hy2008 requires that +\fIsigaction\fR() +properly save and restore a signal action set up by the ISO\ C standard +\fIsignal\fR() +function. However, there is no guarantee that the reverse is true, nor +could there be given the greater amount of information conveyed by the +.BR sigaction +structure. Because of this, applications should avoid using both +functions for the same signal in the same process. Since this cannot +always be avoided in case of general-purpose library routines, they +should always be implemented with +\fIsigaction\fR(). +.P +It was intended that the +\fIsignal\fR() +function should be implementable as a library routine using +\fIsigaction\fR(). +.P +The POSIX Realtime Extension extends the +\fIsigaction\fR() +function as specified by the POSIX.1\(hy1990 standard to allow the application to request +on a per-signal basis via an additional signal action flag that the +extra parameters, including the application-defined signal value, if +any, be passed to the signal-catching function. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIexec\fR\^", +.IR "\fIkill\fR\^(\|)", +.IR "\fI_longjmp\fR\^(\|)", +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigaddset.3p b/man-pages-posix-2013-a/man3p/sigaddset.3p new file mode 100644 index 0000000..367b4c7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigaddset.3p @@ -0,0 +1,103 @@ +'\" et +.TH SIGADDSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigaddset +\(em add a signal to a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigaddset(sigset_t *\fIset\fP, int \fIsigno\fP); +.fi +.SH DESCRIPTION +The +\fIsigaddset\fR() +function adds the individual signal specified by the +.IR signo +to the signal set pointed to by +.IR set . +.P +Applications shall call either +\fIsigemptyset\fR() +or +\fIsigfillset\fR() +at least once for each object of type +.BR sigset_t +prior to any other use of that object. If such an object is not +initialized in this way, but is nonetheless supplied as an argument to +any of +\fIpthread_sigmask\fR(), +\fIsigaction\fR(), +\fIsigaddset\fR(), +\fIsigdelset\fR(), +\fIsigismember\fR(), +\fIsigpending\fR(), +\fIsigprocmask\fR(), +\fIsigsuspend\fR(), +\fIsigtimedwait\fR(), +\fIsigwait\fR(), +or +\fIsigwaitinfo\fR(), +the results are undefined. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigaddset\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigaddset\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR signo +argument is an invalid or unsupported signal number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigaltstack.3p b/man-pages-posix-2013-a/man3p/sigaltstack.3p new file mode 100644 index 0000000..5e7574f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigaltstack.3p @@ -0,0 +1,181 @@ +'\" et +.TH SIGALTSTACK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigaltstack +\(em set and get signal alternate stack context +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigaltstack(const stack_t *restrict \fIss\fP, stack_t *restrict \fIoss\fP); +.fi +.SH DESCRIPTION +The +\fIsigaltstack\fR() +function allows a process to define and examine the state of an +alternate stack for signal handlers for the current thread. Signals +that have been explicitly declared to execute on the alternate stack +shall be delivered on the alternate stack. +.P +If +.IR ss +is not a null pointer, it points to a +.BR stack_t +structure that specifies the alternate signal stack that shall take +effect upon return from +\fIsigaltstack\fR(). +The +.IR ss_flags +member specifies the new stack state. If it is set to SS_DISABLE, the +stack is disabled and +.IR ss_sp +and +.IR ss_size +are ignored. Otherwise, the stack shall be enabled, and the +.IR ss_sp +and +.IR ss_size +members specify the new address and size of the stack. +.P +The range of addresses starting at +.IR ss_sp +up to but not including +.IR ss_sp +\c +.IR ss_size +is available to the implementation for use as the stack. This function +makes no assumptions regarding which end is the stack base and in which +direction the stack grows as items are pushed. +.P +If +.IR oss +is not a null pointer, upon successful completion it shall point to a +.BR stack_t +structure that specifies the alternate signal stack that was in effect +prior to the call to +\fIsigaltstack\fR(). +The +.IR ss_sp +and +.IR ss_size +members specify the address and size of that stack. The +.IR ss_flags +member specifies the stack's state, and may contain one of the +following values: +.IP SS_ONSTACK 12 +The process is currently executing on the alternate signal stack. +Attempts to modify the alternate signal stack while the process is +executing on it fail. This flag shall not be modified by processes. +.IP SS_DISABLE 12 +The alternate signal stack is currently disabled. +.P +The value SIGSTKSZ is a system default specifying the number of bytes +that would be used to cover the usual case when manually allocating an +alternate stack area. The value MINSIGSTKSZ is defined to be the +minimum stack size for +a signal handler. In computing an alternate stack size, a program +should add that amount to its stack requirements to allow for the +system implementation overhead. The constants SS_ONSTACK, SS_DISABLE, +SIGSTKSZ, and MINSIGSTKSZ are +defined in +.IR . +.P +After a successful call to one of the +.IR exec +functions, there are no alternate signal stacks in the new process +image. +.P +In some implementations, a signal (whether or not indicated to execute +on the alternate stack) shall always execute on the alternate stack if +it is delivered while another signal is being caught using the +alternate stack. +.P +Use of this function by library threads that are not bound to +kernel-scheduled entities results in undefined behavior. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigaltstack\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigaltstack\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR ss +argument is not a null pointer, and the +.IR ss_flags +member pointed to by +.IR ss +contains flags other than SS_DISABLE. +.TP +.BR ENOMEM +The size of the alternate stack area is less than MINSIGSTKSZ. +.TP +.BR EPERM +An attempt was made to modify an active stack. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Allocating Memory for an Alternate Stack" +.P +The following example illustrates a method for allocating memory for an +alternate stack. +.sp +.RS 4 +.nf +\fB +#include +\&... +if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) + /* Error return. */ +sigstk.ss_size = SIGSTKSZ; +sigstk.ss_flags = 0; +if (sigaltstack(&sigstk,(stack_t *)0) < 0) + perror("sigaltstack"); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +On some implementations, stack space is automatically extended as +needed. On those implementations, automatic extension is typically not +available for an alternate stack. If the stack overflows, the +behavior is undefined. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIexec\fR\^", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigdelset.3p b/man-pages-posix-2013-a/man3p/sigdelset.3p new file mode 100644 index 0000000..14817a0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigdelset.3p @@ -0,0 +1,104 @@ +'\" et +.TH SIGDELSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigdelset +\(em delete a signal from a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigdelset(sigset_t *\fIset\fP, int \fIsigno\fP); +.fi +.SH DESCRIPTION +The +\fIsigdelset\fR() +function deletes the individual signal specified by +.IR signo +from the signal set pointed to by +.IR set . +.P +Applications should call either +\fIsigemptyset\fR() +or +\fIsigfillset\fR() +at least once for each object of type +.BR sigset_t +prior to any other use of that object. If such an object is not +initialized in this way, but is nonetheless supplied as an argument to +any of +\fIpthread_sigmask\fR(), +\fIsigaction\fR(), +\fIsigaddset\fR(), +\fIsigdelset\fR(), +\fIsigismember\fR(), +\fIsigpending\fR(), +\fIsigprocmask\fR(), +\fIsigsuspend\fR(), +\fIsigtimedwait\fR(), +\fIsigwait\fR(), +or +\fIsigwaitinfo\fR(), +the results are undefined. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigdelset\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigdelset\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR signo +argument is not a valid signal number, or is an unsupported signal +number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigemptyset.3p b/man-pages-posix-2013-a/man3p/sigemptyset.3p new file mode 100644 index 0000000..6e0cd07 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigemptyset.3p @@ -0,0 +1,118 @@ +'\" et +.TH SIGEMPTYSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigemptyset +\(em initialize and empty a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigemptyset(sigset_t *\fIset\fP); +.fi +.SH DESCRIPTION +The +\fIsigemptyset\fR() +function initializes the signal set pointed to by +.IR set , +such that all signals defined in POSIX.1\(hy2008 are excluded. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigemptyset\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The implementation of the +\fIsigemptyset\fR() +(or +\fIsigfillset\fR()) +function could quite trivially clear (or set) all the bits in the +signal set. Alternatively, it would be reasonable to initialize part +of the structure, such as a version field, to permit +binary-compatibility between releases where the size of the set +varies. For such reasons, either +\fIsigemptyset\fR() +or +\fIsigfillset\fR() +must be called prior to any other use of the signal set, even if such +use is read-only (for example, as an argument to +\fIsigpending\fR()). +This function is not intended for dynamic allocation. +.P +The +\fIsigfillset\fR() +and +\fIsigemptyset\fR() +functions require that the resulting signal set include (or exclude) +all the signals defined in this volume of POSIX.1\(hy2008. Although it is outside the scope of +\&this volume of POSIX.1\(hy2008 to place this requirement on signals that are implemented as +extensions, it is recommended that implementation-defined signals +also be affected by these functions. However, there may be a good +reason for a particular signal not to be affected. For example, +blocking or ignoring an implementation-defined signal may have +undesirable side-effects, whereas the default action for that signal is +harmless. In such a case, it would be preferable for such a signal to +be excluded from the signal set returned by +\fIsigfillset\fR(). +.P +In early proposals there was no distinction between invalid and +unsupported signals (the names of optional signals that were not +supported by an implementation were not defined by that +implementation). The +.BR [EINVAL] +error was thus specified as a required error for invalid signals. With +that distinction, it is not necessary to require implementations of +these functions to determine whether an optional signal is actually +supported, as that could have a significant performance impact for +little value. The error could have been required for invalid signals +and optional for unsupported signals, but this seemed unnecessarily +complex. Thus, the error is optional in both cases. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigfillset.3p b/man-pages-posix-2013-a/man3p/sigfillset.3p new file mode 100644 index 0000000..72016b6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigfillset.3p @@ -0,0 +1,73 @@ +'\" et +.TH SIGFILLSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigfillset +\(em initialize and fill a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigfillset(sigset_t *\fIset\fP); +.fi +.SH DESCRIPTION +The +\fIsigfillset\fR() +function shall initialize the signal set pointed to by +.IR set , +such that all signals defined in this volume of POSIX.1\(hy2008 are included. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigfillset\fR() +shall return 0; otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIsigemptyset\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sighold.3p b/man-pages-posix-2013-a/man3p/sighold.3p new file mode 100644 index 0000000..2812e82 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sighold.3p @@ -0,0 +1,255 @@ +'\" et +.TH SIGHOLD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sighold, +sigignore, +sigpause, +sigrelse, +sigset +\(em signal management +.SH SYNOPSIS +.LP +.nf +#include +.P +int sighold(int \fIsig\fP); +int sigignore(int \fIsig\fP); +int sigpause(int \fIsig\fP); +int sigrelse(int \fIsig\fP); +void (*sigset(int \fIsig\fP, void (*\fIdisp\fP)(int)))(int); +.fi +.SH DESCRIPTION +Use of any of these functions is unspecified in a multi-threaded +process. +.P +The +\fIsighold\fR(), +\fIsigignore\fR(), +\fIsigpause\fR(), +\fIsigrelse\fR(), +and +\fIsigset\fR() +functions provide simplified signal management. +.P +The +\fIsigset\fR() +function shall modify signal dispositions. The +.IR sig +argument specifies the signal, which may be any signal except SIGKILL +and SIGSTOP. The +.IR disp +argument specifies the signal's disposition, which may be SIG_DFL, +SIG_IGN, or the address of a signal handler. If +\fIsigset\fR() +is used, and +.IR disp +is the address of a signal handler, the system shall add +.IR sig +to the signal mask of the calling process before executing the signal +handler; when the signal handler returns, the system shall restore the +signal mask of the calling process to its state prior to the delivery +of the signal. In addition, if +\fIsigset\fR() +is used, and +.IR disp +is equal to SIG_HOLD, +.IR sig +shall be added to the +signal mask of the calling process and +.IR sig 's +disposition shall remain unchanged. If +\fIsigset\fR() +is used, and +.IR disp +is not equal to SIG_HOLD, +.IR sig +shall be removed from the signal mask of the calling process. +.P +The +\fIsighold\fR() +function shall add +.IR sig +to the signal mask of the calling process. +.P +The +\fIsigrelse\fR() +function shall remove +.IR sig +from the signal mask of the calling process. +.P +The +\fIsigignore\fR() +function shall set the disposition of +.IR sig +to SIG_IGN. +.P +The +\fIsigpause\fR() +function shall remove +.IR sig +from the signal mask of the calling process and suspend the calling process +until a signal is received. The +\fIsigpause\fR() +function shall restore the signal mask of the process to its original +state before returning. +.P +If the action for the SIGCHLD signal is set to SIG_IGN, child processes +of the +calling processes shall not be transformed into zombie processes when +they terminate. If the calling process subsequently waits for its +children, and the process has no unwaited-for children that were +transformed into zombie processes, it shall block until all of its +children terminate, and +\fIwait\fR(), +\fIwaitid\fR(), +and +\fIwaitpid\fR() +shall fail and set +.IR errno +to +.BR [ECHILD] . +.SH "RETURN VALUE" +Upon successful completion, +\fIsigset\fR() +shall return SIG_HOLD if the signal had been blocked and the signal's +previous disposition if it had not been blocked. Otherwise, SIG_ERR +shall be returned and +.IR errno +set to indicate the error. +.P +The +\fIsigpause\fR() +function shall suspend execution of the thread until a signal is +received, whereupon it shall return \(mi1 and set +.IR errno +to +.BR [EINTR] . +.P +For all other functions, upon successful completion, 0 shall be returned. +Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The +.IR sig +argument is an illegal signal number. +.P +The +\fIsigset\fR() +and +\fIsigignore\fR() +functions shall fail if: +.TP +.BR EINVAL +An attempt is made to catch a signal that cannot be caught, or to +ignore a signal that cannot be ignored. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsigaction\fR() +function provides a more comprehensive and reliable mechanism for +controlling signals; new applications should use the +\fIsigaction\fR() +function instead of the obsolescent +\fIsigset\fR() +function. +.P +The +\fIsighold\fR() +function, in conjunction with +\fIsigrelse\fR() +or +\fIsigpause\fR(), +may be used to establish critical regions of code that require the +delivery of a signal to be temporarily deferred. For broader +portability, the +\fIpthread_sigmask\fR() +or +\fIsigprocmask\fR() +functions should be used instead of the obsolescent +\fIsighold\fR() +and +\fIsigrelse\fR() +functions. +.P +For broader portability, the +\fIsigsuspend\fR() +function should be used instead of the obsolescent +\fIsigpause\fR() +function. +.SH RATIONALE +Each of these historic functions has a direct analog in the other +functions which are required to be per-thread and thread-safe (aside +from +\fIsigprocmask\fR(), +which is replaced by +\fIpthread_sigmask\fR()). +The +\fIsigset\fR() +function can be implemented as a simple wrapper for +\fIsigaction\fR(). +The +\fIsighold\fR() +function is equivalent to +\fIsigprocmask\fR() +or +\fIpthread_sigmask\fR() +with SIG_BLOCK set. The +\fIsigignore\fR() +function is equivalent to +\fIsigaction\fR() +with SIG_IGN set. The +\fIsigpause\fR() +function is equivalent to +\fIsigsuspend\fR(). +The +\fIsigrelse\fR() +function is equivalent to +\fIsigprocmask\fR() +or +\fIpthread_sigmask\fR() +with SIG_UNBLOCK set. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIexec\fR\^", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/siginterrupt.3p b/man-pages-posix-2013-a/man3p/siginterrupt.3p new file mode 100644 index 0000000..78b25c3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/siginterrupt.3p @@ -0,0 +1,99 @@ +'\" et +.TH SIGINTERRUPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +siginterrupt +\(em allow signals to interrupt functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int siginterrupt(int \fIsig\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIsiginterrupt\fR() +function shall change the restart behavior when a function is +interrupted by the specified signal. The function +\fIsiginterrupt\fP(\fIsig\fP, \fIflag\fP) has an effect as if +implemented as: +.sp +.RS 4 +.nf +\fB +int siginterrupt(int sig, int flag) { + int ret; + struct sigaction act; +.P + (void) sigaction(sig, NULL, &act); + if (flag) + act.sa_flags &= ~SA_RESTART; + else + act.sa_flags |= SA_RESTART; + ret = sigaction(sig, &act, NULL); + return ret; +} +.fi \fR +.P +.RE +.SH "RETURN VALUE" +Upon successful completion, +\fIsiginterrupt\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsiginterrupt\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR sig +argument is not a valid signal number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsiginterrupt\fR() +function supports programs written to historical system interfaces. +Applications should use the +\fIsigaction\fR() +with the SA_RESTART flag instead of the obsolescent +\fIsiginterrupt\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigismember.3p b/man-pages-posix-2013-a/man3p/sigismember.3p new file mode 100644 index 0000000..55faf9f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigismember.3p @@ -0,0 +1,105 @@ +'\" et +.TH SIGISMEMBER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigismember +\(em test for a signal in a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigismember(const sigset_t *\fIset\fP, int \fIsigno\fP); +.fi +.SH DESCRIPTION +The +\fIsigismember\fR() +function shall test whether the signal specified by +.IR signo +is a member of the set pointed to by +.IR set . +.P +Applications should call either +\fIsigemptyset\fR() +or +\fIsigfillset\fR() +at least once for each object of type +.BR sigset_t +prior to any other use of that object. If such an object is not +initialized in this way, but is nonetheless supplied as an argument to +any of +\fIpthread_sigmask\fR(), +\fIsigaction\fR(), +\fIsigaddset\fR(), +\fIsigdelset\fR(), +\fIsigismember\fR(), +\fIsigpending\fR(), +\fIsigprocmask\fR(), +\fIsigsuspend\fR(), +\fIsigtimedwait\fR(), +\fIsigwait\fR(), +or +\fIsigwaitinfo\fR(), +the results are undefined. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigismember\fR() +shall return 1 if the specified signal is a member of the specified set, +or 0 if it is not. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigismember\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR signo +argument is not a valid signal number, or is an unsupported signal +number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/siglongjmp.3p b/man-pages-posix-2013-a/man3p/siglongjmp.3p new file mode 100644 index 0000000..a69f582 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/siglongjmp.3p @@ -0,0 +1,106 @@ +'\" et +.TH SIGLONGJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +siglongjmp +\(em non-local goto with signal handling +.SH SYNOPSIS +.LP +.nf +#include +.P +void siglongjmp(sigjmp_buf \fIenv\fP, int \fIval\fP); +.fi +.SH DESCRIPTION +The +\fIsiglongjmp\fR() +function shall be equivalent to the +\fIlongjmp\fR() +function, except as follows: +.IP " *" 4 +References to +\fIsetjmp\fR() +shall be equivalent to +\fIsigsetjmp\fR(). +.IP " *" 4 +The +\fIsiglongjmp\fR() +function shall restore the saved signal mask if and only if the +.IR env +argument was initialized by a call to +\fIsigsetjmp\fR() +with a non-zero +.IR savemask +argument. +.SH "RETURN VALUE" +After +\fIsiglongjmp\fR() +is completed, program execution shall continue as if the corresponding +invocation of +\fIsigsetjmp\fR() +had just returned the value specified by +.IR val . +The +\fIsiglongjmp\fR() +function shall not cause +\fIsigsetjmp\fR() +to return 0; if +.IR val +is 0, +\fIsigsetjmp\fR() +shall return the value 1. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The distinction between +\fIsetjmp\fR() +or +\fIlongjmp\fR() +and +\fIsigsetjmp\fR() +or +\fIsiglongjmp\fR() +is only significant for programs which use +\fIsigaction\fR(), +\fIsigprocmask\fR(), +or +\fIsigsuspend\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsetjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/signal.3p b/man-pages-posix-2013-a/man3p/signal.3p new file mode 100644 index 0000000..8a25dff --- /dev/null +++ b/man-pages-posix-2013-a/man3p/signal.3p @@ -0,0 +1,218 @@ +'\" et +.TH SIGNAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +signal +\(em signal management +.SH SYNOPSIS +.LP +.nf +#include +.P +void (*signal(int \fIsig\fP, void (*\fIfunc\fP)(int)))(int); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +Use of this function is unspecified in a multi-threaded process. +.P +The +\fIsignal\fR() +function chooses one of three ways in which receipt of the signal +number +.IR sig +is to be subsequently handled. If the value of +.IR func +is SIG_DFL, default handling for that signal shall occur. +If the value of +.IR func +is SIG_IGN, the signal shall be ignored. +Otherwise, the application shall ensure that +.IR func +points to a function to be called when that signal occurs. An +invocation of such a function because of a signal, or (recursively) of +any further functions called by that invocation (other than functions +in the standard library), is called a ``signal handler''. +.P +When a signal occurs, and +.IR func +points to a function, it is implementation-defined whether the +equivalent of a: +.sp +.RS 4 +.nf +\fB +signal(\fIsig\fP, SIG_DFL); +.fi \fR +.P +.RE +.P +is executed or the implementation prevents some implementation-defined +set of signals (at least including +.IR sig ) +from occurring until the current signal handling has completed. (If the +value of +.IR sig +is SIGILL, the implementation may alternatively define that no action +is taken.) Next the equivalent of: +.sp +.RS 4 +.nf +\fB +(*func)(sig); +.fi \fR +.P +.RE +.P +is executed. If and when the function returns, if the value of +.IR sig +was SIGFPE, SIGILL, or SIGSEGV or any other implementation-defined +value corresponding to +a computational exception, the behavior is undefined. Otherwise, the +program shall resume execution at the point it was interrupted. The +ISO\ C standard places a restriction on applications relating to the use of +\fIraise\fR() +from signal handlers. +This restriction does not apply to POSIX applications, as POSIX.1\(hy2008 requires +\fIraise\fR() +to be async-signal-safe (see +.IR "Section 2.4.3" ", " "Signal Actions"). +.P +If the process is multi-threaded, +or if the process is single-threaded and a signal handler is +executed other than as the result of: +.IP " *" 4 +The process calling +\fIabort\fR(), +\fIraise\fR(), +\fIkill\fR(), +\fIpthread_kill\fR(), +or +\fIsigqueue\fR() +to generate a signal that is not blocked +.IP " *" 4 +A pending signal being unblocked and being delivered before the call +that unblocked it returns +.P +the behavior is undefined if the signal handler refers to any object +other than +.IR errno +with static storage duration other than by assigning a value to an +object declared as +.BR "volatile sig_atomic_t" , +or if the signal handler calls any function defined in this standard +other than +one of the functions listed in +.IR "Section 2.4" ", " "Signal Concepts". +.P +At program start-up, the equivalent of: +.sp +.RS 4 +.nf +\fB +signal(\fIsig\fP, SIG_IGN); +.fi \fR +.P +.RE +.P +is executed for some signals, and the equivalent of: +.sp +.RS 4 +.nf +\fB +signal(\fIsig\fP, SIG_DFL); +.fi \fR +.P +.RE +.P +is executed for all other signals +(see +.IR exec ). +.P +The +\fIsignal\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +If the request can be honored, +\fIsignal\fR() +shall return the value of +.IR func +for the most recent call to +\fIsignal\fR() +for the specified signal +.IR sig . +Otherwise, SIG_ERR shall be returned and a positive value shall +be stored in +.IR errno . +.SH ERRORS +The +\fIsignal\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR sig +argument is not a valid signal number or an attempt is made to catch a +signal that cannot be caught or ignore a signal that cannot be +ignored. +.P +The +\fIsignal\fR() +function may fail if: +.TP +.BR EINVAL +An attempt was made to set the action to SIG_DFL for a signal that +cannot be caught or ignored (or both). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsigaction\fR() +function provides a more comprehensive and reliable mechanism for +controlling signals; new applications should use +\fIsigaction\fR() +rather than +\fIsignal\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIexec\fR\^", +.IR "\fIpause\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/signbit.3p b/man-pages-posix-2013-a/man3p/signbit.3p new file mode 100644 index 0000000..889a631 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/signbit.3p @@ -0,0 +1,70 @@ +'\" et +.TH SIGNBIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +signbit +\(em test sign +.SH SYNOPSIS +.LP +.nf +#include +.P +int signbit(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIsignbit\fR() +macro shall determine whether the sign of its argument value is +negative. NaNs, zeros, and infinities have a sign bit. +.SH "RETURN VALUE" +The +\fIsignbit\fR() +macro shall return a non-zero value if and only if the sign of its +argument value is negative. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/signgam.3p b/man-pages-posix-2013-a/man3p/signgam.3p new file mode 100644 index 0000000..3ac9cb5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/signgam.3p @@ -0,0 +1,38 @@ +'\" et +.TH SIGNGAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +signgam +\(em log gamma function +.SH SYNOPSIS +.LP +.nf +#include +.P +extern int signgam; +.fi +.SH DESCRIPTION +Refer to +.IR "\fIlgamma\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigpause.3p b/man-pages-posix-2013-a/man3p/sigpause.3p new file mode 100644 index 0000000..727f324 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigpause.3p @@ -0,0 +1,38 @@ +'\" et +.TH SIGPAUSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigpause +\(em remove a signal from the signal mask and suspend the thread +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigpause(int \fIsig\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsighold\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigpending.3p b/man-pages-posix-2013-a/man3p/sigpending.3p new file mode 100644 index 0000000..9a1d63a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigpending.3p @@ -0,0 +1,72 @@ +'\" et +.TH SIGPENDING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigpending +\(em examine pending signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigpending(sigset_t *\fIset\fP); +.fi +.SH DESCRIPTION +The +\fIsigpending\fR() +function shall store, in the location referenced by the +.IR set +argument, the set of signals that are blocked from delivery to the +calling thread and that are pending on the process or the calling +thread. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigpending\fR() +shall return 0; otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigprocmask.3p b/man-pages-posix-2013-a/man3p/sigprocmask.3p new file mode 100644 index 0000000..5b5e70d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigprocmask.3p @@ -0,0 +1,39 @@ +'\" et +.TH SIGPROCMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigprocmask +\(em examine and change blocked signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigprocmask(int \fIhow\fP, const sigset_t *restrict \fIset\fP, + sigset_t *restrict \fIoset\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_sigmask\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigqueue.3p b/man-pages-posix-2013-a/man3p/sigqueue.3p new file mode 100644 index 0000000..b3dd2b4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigqueue.3p @@ -0,0 +1,188 @@ +'\" et +.TH SIGQUEUE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigqueue +\(em queue a signal to a process +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigqueue(pid_t \fIpid\fP, int \fIsigno\fP, const union sigval \fIvalue\fP); +.fi +.SH DESCRIPTION +The +\fIsigqueue\fR() +function shall cause the signal specified by +.IR signo +to be sent with the value specified by +.IR value +to the process specified by +.IR pid . +If +.IR signo +is zero (the null signal), error checking is performed but no signal is +actually sent. The null signal can be used to check the validity of +.IR pid . +.P +The conditions required for a process to have permission to queue a +signal to another process are the same as for the +\fIkill\fR() +function. +.P +The +\fIsigqueue\fR() +function shall return immediately. If SA_SIGINFO is set for +.IR signo +and if the resources were available to queue the signal, the signal +shall be queued and sent to the receiving process. If SA_SIGINFO is not +set for +.IR signo , +then +.IR signo +shall be sent at least once to the receiving process; it is unspecified +whether +.IR value +shall be sent to the receiving process as a result of this call. +.P +If the value of +.IR pid +causes +.IR signo +to be generated for the sending process, and if +.IR signo +is not blocked for the calling thread and if no other thread has +.IR signo +unblocked or is waiting in a +\fIsigwait\fR() +function for +.IR signo , +either +.IR signo +or at least the pending, unblocked signal shall be delivered to the +calling thread before the +\fIsigqueue\fR() +function returns. Should any multiple pending signals in the range +SIGRTMIN to +SIGRTMAX be selected for delivery, it shall be the lowest numbered one. +The selection order between realtime and non-realtime signals, or +between multiple pending non-realtime signals, is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the specified signal shall have been +queued, and the +\fIsigqueue\fR() +function shall return a value of zero. Otherwise, the function shall +return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigqueue\fR() +function shall fail if: +.TP +.BR EAGAIN +No resources are available to queue the signal. The process has already +queued +{SIGQUEUE_MAX} +signals that are still pending at the receiver(s), or a system-wide +resource limit has been exceeded. +.TP +.BR EINVAL +The value of the +.IR signo +argument is an invalid or unsupported signal number. +.TP +.BR EPERM +The process does not have appropriate privileges to send the signal +to the receiving process. +.TP +.BR ESRCH +The process +.IR pid +does not exist. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIsigqueue\fR() +function allows an application to queue a realtime signal to itself or +to another process, specifying the application-defined value. This is +common practice in realtime applications on existing realtime systems. +It was felt that specifying another function in the +.IR sig .\|.\|. +name space already carved out for signals was preferable to extending +the interface to +\fIkill\fR(). +.P +Such a function became necessary when the put/get event function of +the message queues was removed. It should be noted that the +\fIsigqueue\fR() +function implies reduced performance in a security-conscious +implementation as the access permissions between the sender and +receiver have to be checked on each send when the +.IR pid +is resolved into a target process. Such access checks were necessary +only at message queue open in the previous interface. +.P +The standard developers required that +\fIsigqueue\fR() +have the same semantics with respect to the null signal as +\fIkill\fR(), +and that the same permission checking be used. But because of the +difficulty of implementing the ``broadcast'' semantic of +\fIkill\fR() +(for example, to process groups) and the interaction with resource +allocation, this semantic was not adopted. The +\fIsigqueue\fR() +function queues a signal to a single process specified by the +.IR pid +argument. +.P +The +\fIsigqueue\fR() +function can fail if the system has insufficient resources to queue the +signal. An explicit limit on the number of queued signals that a +process could send was introduced. While the limit is ``per-sender'', +\&this volume of POSIX.1\(hy2008 does not specify that the resources be part of the state +of the sender. This would require either that the sender be maintained +after exit until all signals that it had sent to other processes were +handled or that all such signals that had not yet been acted upon be +removed from the queue(s) of the receivers. This volume of POSIX.1\(hy2008 does not +preclude this behavior, but an implementation that allocated queuing +resources from a system-wide pool (with per-sender limits) and that +leaves queued signals pending after the sender exits is also +permitted. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.8.1" ", " "Realtime Signals" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigrelse.3p b/man-pages-posix-2013-a/man3p/sigrelse.3p new file mode 100644 index 0000000..49d3192 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigrelse.3p @@ -0,0 +1,40 @@ +'\" et +.TH SIGRELSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigrelse, +sigset +\(em signal management +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigrelse(int \fIsig\fP); +void (*sigset(int \fIsig\fP, void (*\fIdisp\fP)(int)))(int); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsighold\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigsetjmp.3p b/man-pages-posix-2013-a/man3p/sigsetjmp.3p new file mode 100644 index 0000000..a1882fc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigsetjmp.3p @@ -0,0 +1,155 @@ +'\" et +.TH SIGSETJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigsetjmp +\(em set jump point for a non-local goto +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigsetjmp(sigjmp_buf \fIenv\fP, int \fIsavemask\fP); +.fi +.SH DESCRIPTION +The +\fIsigsetjmp\fR() +function shall be equivalent to the +\fIsetjmp\fR() +function, except as follows: +.IP " *" 4 +References to +\fIsetjmp\fR() +are equivalent to +\fIsigsetjmp\fR(). +.IP " *" 4 +References to +\fIlongjmp\fR() +are equivalent to +\fIsiglongjmp\fR(). +.IP " *" 4 +If the value of the +.IR savemask +argument is not 0, +\fIsigsetjmp\fR() +shall also save the current signal mask of the calling thread as part +of the calling environment. +.SH "RETURN VALUE" +If the return is from a successful direct invocation, +\fIsigsetjmp\fR() +shall return 0. If the return is from a call to +\fIsiglongjmp\fR(), +\fIsigsetjmp\fR() +shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The distinction between +\fIsetjmp\fR()/\c +\fIlongjmp\fR() +and +\fIsigsetjmp\fR()/\c +\fIsiglongjmp\fR() +is only significant for programs which use +\fIsigaction\fR(), +\fIsigprocmask\fR(), +or +\fIsigsuspend\fR(). +.P +Note that since this function is defined in terms of +\fIsetjmp\fR(), +if +.IR savemask +is zero, it is unspecified whether the signal mask is saved. +.SH RATIONALE +The ISO\ C standard specifies various restrictions on the usage of the +\fIsetjmp\fR() +macro in order to permit implementors to recognize the name in the +compiler and not implement an actual function. These same restrictions +apply to the +\fIsigsetjmp\fR() +macro. +.P +There are processors that cannot easily support these calls, but this +was not considered a sufficient reason to exclude them. +.P +4.2 BSD, 4.3 BSD, and XSI-conformant systems provide functions named +\fI_setjmp\fR() +and +\fI_longjmp\fR() +that, together with +\fIsetjmp\fR() +and +\fIlongjmp\fR(), +provide the same functionality as +\fIsigsetjmp\fR() +and +\fIsiglongjmp\fR(). +On those systems, +\fIsetjmp\fR() +and +\fIlongjmp\fR() +save and restore signal masks, while +\fI_setjmp\fR() +and +\fI_longjmp\fR() +do not. On System V Release 3 +and in corresponding issues of the SVID, +\fIsetjmp\fR() +and +\fIlongjmp\fR() +are explicitly defined not to save and restore signal masks. In order +to permit existing practice in both cases, the relation of +\fIsetjmp\fR() +and +\fIlongjmp\fR() +to signal masks is not specified, and a new set of functions is defined +instead. +.P +The +\fIlongjmp\fR() +and +\fIsiglongjmp\fR() +functions operate as in the previous issue provided the matching +\fIsetjmp\fR() +or +\fIsigsetjmp\fR() +has been performed in the same thread. Non-local jumps into contexts +saved by other threads would be at best a questionable practice and +were not considered worthy of standardization. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigsuspend.3p b/man-pages-posix-2013-a/man3p/sigsuspend.3p new file mode 100644 index 0000000..22efe90 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigsuspend.3p @@ -0,0 +1,128 @@ +'\" et +.TH SIGSUSPEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigsuspend +\(em wait for a signal +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigsuspend(const sigset_t *\fIsigmask\fP); +.fi +.SH DESCRIPTION +The +\fIsigsuspend\fR() +function shall replace the current signal mask of the calling thread +with the set of signals pointed to by +.IR sigmask +and then suspend the thread until delivery of a signal whose action is +either to execute a signal-catching function or to terminate the +process. This shall not cause any other signals that may have been +pending on the process to become pending on the thread. +.P +If the action is to terminate the process then +\fIsigsuspend\fR() +shall never return. If the action is to execute a signal-catching +function, then +\fIsigsuspend\fR() +shall return after the signal-catching function returns, with the +signal mask restored to the set that existed prior to the +\fIsigsuspend\fR() +call. +.P +It is not possible to block signals that cannot be ignored. This is +enforced by the system without causing an error to be indicated. +.SH "RETURN VALUE" +Since +\fIsigsuspend\fR() +suspends thread execution indefinitely, there is no successful +completion return value. If a return occurs, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsigsuspend\fR() +function shall fail if: +.TP +.BR EINTR +A signal is caught by the calling process and control is returned from +the signal-catching function. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Normally, at the beginning of a critical code section, a specified set +of signals is blocked using the +\fIsigprocmask\fR() +function. When the thread has completed the critical section and +needs to wait for the previously blocked signal(s), it pauses by +calling +\fIsigsuspend\fR() +with the mask that was returned by the +\fIsigprocmask\fR() +call. +.SH RATIONALE +Code which wants to avoid the ambiguity of the signal mask for thread +cancellation handlers can install an additional cancellation handler +which resets the signal mask to the expected value. +.sp +.RS 4 +.nf +\fB +void cleanup(void *arg) +{ + sigset_t *ss = (sigset_t *) arg; + pthread_sigmask(SIG_SETMASK, ss, NULL); +} +.P +int call_sigsuspend(const sigset_t *mask) +{ + sigset_t oldmask; + int result; + pthread_sigmask(SIG_SETMASK, NULL, &oldmask); + pthread_cleanup_push(cleanup, &oldmask); + result = sigsuspend(sigmask); + pthread_cleanup_pop(0); + return result; +} +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpause\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigtimedwait.3p b/man-pages-posix-2013-a/man3p/sigtimedwait.3p new file mode 100644 index 0000000..f0ecfd1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigtimedwait.3p @@ -0,0 +1,366 @@ +'\" et +.TH SIGTIMEDWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigtimedwait, +sigwaitinfo +\(em wait for queued signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigtimedwait(const sigset_t *restrict \fIset\fP, + siginfo_t *restrict \fIinfo\fP, + const struct timespec *restrict \fItimeout\fP); +int sigwaitinfo(const sigset_t *restrict \fIset\fP, + siginfo_t *restrict \fIinfo\fP); +.fi +.SH DESCRIPTION +The +\fIsigtimedwait\fR() +function shall be equivalent to +\fIsigwaitinfo\fR() +except that if none of the signals specified by +.IR set +are pending, +\fIsigtimedwait\fR() +shall wait for the time interval specified in the +.BR timespec +structure referenced by +.IR timeout . +If the +.BR timespec +structure pointed to by +.IR timeout +is zero-valued and if none of the signals specified by +.IR set +are pending, then +\fIsigtimedwait\fR() +shall return immediately with an error. If +.IR timeout +is the null pointer, the behavior is unspecified. +If the Monotonic Clock option is supported, the CLOCK_MONOTONIC clock +shall be used to measure the time interval specified by the +.IR timeout +argument. +.P +The +\fIsigwaitinfo\fR() +function selects the pending signal from the set specified by +.IR set . +Should any of multiple pending signals in the range SIGRTMIN to +SIGRTMAX be selected, +it shall be the lowest numbered one. The selection order between +realtime and non-realtime signals, or between multiple pending +non-realtime signals, is unspecified. If no signal in +.IR set +is pending at the time of the call, the calling thread shall be +suspended until one or more signals in +.IR set +become pending or until it is interrupted by an unblocked, caught +signal. +.P +The +\fIsigwaitinfo\fR() +function shall be equivalent to the +\fIsigwait\fR() +function if the +.IR info +argument is NULL. If the +.IR info +argument is non-NULL, the +\fIsigwaitinfo\fR() +function shall be equivalent to +\fIsigwait\fR(), +except that the selected signal number shall be stored in the +.IR si_signo +member, and the cause of the signal shall be stored in the +.IR si_code +member. If any value is queued to the selected signal, the first such +queued value shall be dequeued and, if the +.IR info +argument is non-NULL, the value shall be stored in the +.IR si_value +member of +.IR info . +The system resource used to queue the signal shall be released and +returned to the system for other use. If no value is queued, the +content of the +.IR si_value +member is undefined. If no further signals are queued for the selected +signal, the pending indication for that signal shall be reset. +.SH "RETURN VALUE" +Upon successful completion (that is, one of the signals specified by +.IR set +is pending or is generated) +\fIsigwaitinfo\fR() +and +\fIsigtimedwait\fR() +shall return the selected signal number. Otherwise, the function shall +return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigtimedwait\fR() +function shall fail if: +.TP +.BR EAGAIN +No signal specified by +.IR set +was generated within the specified timeout period. +.P +The +\fIsigtimedwait\fR() +and +\fIsigwaitinfo\fR() +functions may fail if: +.TP +.BR EINTR +The wait was interrupted by an unblocked, caught signal. It shall be +documented in system documentation whether this error causes these +functions to fail. +.br +.P +The +\fIsigtimedwait\fR() +function may also fail if: +.TP +.BR EINVAL +The +.IR timeout +argument specified a +.IR tv_nsec +value less than zero or greater than or equal to 1\|000 million. +.P +An implementation should only check for this error if no signal is +pending in +.IR set +and it is necessary to wait. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsigtimedwait\fR() +function times out and returns an +.BR [EAGAIN] +error. Application developers should note that this is inconsistent +with other functions such as +\fIpthread_cond_timedwait\fR() +that return +.BR [ETIMEDOUT] . +.P +Note that in order to ensure that generated signals are queued and signal +values passed to +\fIsigqueue\fR() +are available in +.IR si_value , +applications which use +\fIsigwaitinfo\fR() +or +\fIsigtimedwait\fR() +need to set the SA_SIGINFO flag for each signal in the set (see +.IR "Section 2.4" ", " "Signal Concepts"). +This means setting each signal to be handled by a three-argument +signal-catching function, even if the handler will never be called. +It is not possible (portably) to set a signal handler to SIG_DFL while +setting the SA_SIGINFO flag, because assigning to the +.IR sa_handler +member of +.BR "struct sigaction" +instead of the +.IR sa_sigaction +member would result in undefined behavior, and SIG_DFL need not be +assignment-compatible with +.IR sa_sigaction . +Even if an assignment of SIG_DFL to +.IR sa_sigaction +is accepted by the compiler, the implementation need not treat this value +as special\(emit could just be taken as the address of a signal-catching +function. +.SH RATIONALE +Existing programming practice on realtime systems uses the ability to +pause waiting for a selected set of events and handle the first event +that occurs in-line instead of in a signal-handling function. This +allows applications to be written in an event-directed style similar to +a state machine. This style of programming is useful for largescale +transaction processing in which the overall throughput of an +application and the ability to clearly track states are more important +than the ability to minimize the response time of individual event +handling. +.P +It is possible to construct a signal-waiting macro function out of the +realtime signal function mechanism defined in this volume of POSIX.1\(hy2008. However, such a +macro has to include the definition of a generalized handler for all +signals to be waited on. A significant portion of the overhead of +handler processing can be avoided if the signal-waiting function is +provided by the kernel. This volume of POSIX.1\(hy2008 therefore provides two signal-waiting +functions\(emone that waits indefinitely and one with a timeout\(emas +part of the overall realtime signal function specification. +.P +The specification of a function with a timeout allows an application +to be written that can be broken out of a wait after a set period of +time if no event has occurred. It was argued that setting a timer +event before the wait and recognizing the timer event in the wait would +also implement the same functionality, but at a lower performance +level. Because of the performance degradation associated with the +user-level specification of a timer event and the subsequent +cancellation of that timer event after the wait completes for a valid +event, and the complexity associated with handling potential race +conditions associated with the user-level method, the separate +function has been included. +.P +Note that the semantics of the +\fIsigwaitinfo\fR() +function are nearly identical to that of the +\fIsigwait\fR() +function defined by this volume of POSIX.1\(hy2008. The only difference is that +\fIsigwaitinfo\fR() +returns the queued signal value in the +.IR value +argument. The return of the queued value is required so that +applications can differentiate between multiple events queued to the +same signal number. +.P +The two distinct functions are being maintained because some +implementations may choose to implement the POSIX Threads Extension functions and not +implement the queued signals extensions. Note, though, that +\fIsigwaitinfo\fR() +does not return the queued value if the +.IR value +argument is NULL, so the POSIX Threads Extension +\fIsigwait\fR() +function can be implemented as a macro on +\fIsigwaitinfo\fR(). +.P +The +\fIsigtimedwait\fR() +function was separated from the +\fIsigwaitinfo\fR() +function to address concerns regarding the overloading of the +.IR timeout +pointer to indicate indefinite wait (no timeout), timed wait, and +immediate return, and concerns regarding consistency with other +functions where the conditional and timed waits were separate +functions from the pure blocking function. The semantics of +\fIsigtimedwait\fR() +are specified such that +\fIsigwaitinfo\fR() +could be implemented as a macro with a null pointer for +.IR timeout . +.P +The +.IR sigwait +functions provide a synchronous mechanism for threads to wait for +asynchronously-generated signals. One important question was how many +threads that are suspended in a call to a +\fIsigwait\fR() +function for a signal should return from the call when the signal is +sent. Four choices were considered: +.IP " 1." 4 +Return an error for multiple simultaneous calls to +.IR sigwait +functions for the same signal. +.IP " 2." 4 +One or more threads return. +.IP " 3." 4 +All waiting threads return. +.IP " 4." 4 +Exactly one thread returns. +.P +Prohibiting multiple calls to +\fIsigwait\fR() +for the same signal was felt to be overly restrictive. The ``one or +more'' behavior made implementation of conforming packages easy at the +expense of forcing POSIX threads clients to protect against multiple +simultaneous calls to +\fIsigwait\fR() +in application code in order to achieve predictable behavior. There +was concern that the ``all waiting threads'' behavior would result in +``signal broadcast storms'', consuming excessive CPU resources by +replicating the signals in the general case. Furthermore, no +convincing examples could be presented that delivery to all was either +simpler or more powerful than delivery to one. +.P +Thus, the consensus was that exactly one thread that was suspended in a +call to a +.IR sigwait +function for a signal should return when that signal occurs. This is +not an onerous restriction as: +.IP " *" 4 +A multi-way signal wait can be built from the single-way wait. +.IP " *" 4 +Signals should only be handled by application-level code, as library +routines cannot guess what the application wants to do with signals +generated for the entire process. +.IP " *" 4 +Applications can thus arrange for a single thread to wait for any given +signal and call any needed routines upon its arrival. +.P +In an application that is using signals for interprocess communication, +signal processing is typically done in one place. Alternatively, if +the signal is being caught so that process cleanup can be done, the +signal handler thread can call separate process cleanup routines for +each portion of the application. Since the application main line +started each portion of the application, it is at the right abstraction +level to tell each portion of the application to clean up. +.P +Certainly, there exist programming styles where it is logical to +consider waiting for a single signal in multiple threads. A simple +\fIsigwait_multiple\fR() +routine can be constructed to achieve this goal. A possible +implementation would be to have each +\fIsigwait_multiple\fR() +caller registered as having expressed interest in a set of signals. +The caller then waits on a thread-specific condition variable. A +single server thread calls a +\fIsigwait\fR() +function on the union of all registered signals. When the +\fIsigwait\fR() +function returns, the appropriate state is set and condition variables +are broadcast. New +\fIsigwait_multiple\fR() +callers may cause the pending +\fIsigwait\fR() +call to be canceled and reissued in order to update the set of signals +being waited for. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "Section 2.8.1" ", " "Realtime Signals", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIsigwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigwait.3p b/man-pages-posix-2013-a/man3p/sigwait.3p new file mode 100644 index 0000000..1fe7ad5 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigwait.3p @@ -0,0 +1,145 @@ +'\" et +.TH SIGWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigwait +\(em wait for queued signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigwait(const sigset_t *restrict \fIset\fP, int *restrict \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIsigwait\fR() +function shall select a pending signal from +.IR set , +atomically clear it from the system's set of pending signals, and +return that signal number in the location referenced by +.IR sig . +If prior to the call to +\fIsigwait\fR() +there are multiple pending instances of a single signal number, it is +implementation-defined whether upon successful return there are any +remaining pending signals for that signal number. +If the implementation supports queued signals and there are multiple +signals queued for the signal number selected, the first such queued +signal shall cause a return from +\fIsigwait\fR() +and the remainder shall remain queued. If no signal in +.IR set +is pending at the time of the call, the thread shall be suspended +until one or more becomes pending. The signals defined by +.IR set +shall have been blocked at the time of the call to +\fIsigwait\fR(); +otherwise, the behavior is undefined. The effect of +\fIsigwait\fR() +on the signal actions for the signals in +.IR set +is unspecified. +.P +If more than one thread is using +\fIsigwait\fR() +to wait for the same signal, no more than one of these threads shall +return from +\fIsigwait\fR() +with the signal number. If more than a single thread is blocked in +\fIsigwait\fR() +for a signal when that signal is generated for the process, it is +unspecified which of the waiting threads returns from +\fIsigwait\fR(). +If the signal is generated for a specific thread, as by +\fIpthread_kill\fR(), +only that thread shall return. +.P +Should any of the multiple pending signals in the range SIGRTMIN to +SIGRTMAX be selected, it shall be the lowest numbered one. The +selection order between realtime and non-realtime signals, or between +multiple pending non-realtime signals, is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigwait\fR() +shall store the signal number of the received signal at the location +referenced by +.IR sig +and return zero. Otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIsigwait\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR set +argument contains an invalid or unsupported signal number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +To provide a convenient way for a thread to wait for a signal, this volume of POSIX.1\(hy2008 +provides the +\fIsigwait\fR() +function. For most cases where a thread has to wait for a signal, the +\fIsigwait\fR() +function should be quite convenient, efficient, and adequate. +.P +However, requests were made for a lower-level primitive than +\fIsigwait\fR() +and for semaphores that could be used by threads. After some +consideration, threads were allowed to use semaphores and +\fIsem_post\fR() +was defined to be async-signal-safe. +.P +In summary, when it is necessary for code run in response to an +asynchronous signal to notify a thread, +\fIsigwait\fR() +should be used to handle the signal. Alternatively, if the +implementation provides semaphores, they also can be used, either +following +\fIsigwait\fR() +or from within a signal handling routine previously registered with +\fIsigaction\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "Section 2.8.1" ", " "Realtime Signals", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIsigtimedwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sigwaitinfo.3p b/man-pages-posix-2013-a/man3p/sigwaitinfo.3p new file mode 100644 index 0000000..cb4cd78 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sigwaitinfo.3p @@ -0,0 +1,38 @@ +'\" et +.TH SIGWAITINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sigwaitinfo +\(em wait for queued signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigwaitinfo(const sigset_t *restrict \fIset\fP, siginfo_t *restrict \fIinfo\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsigtimedwait\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sin.3p b/man-pages-posix-2013-a/man3p/sin.3p new file mode 100644 index 0000000..53a0a97 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sin.3p @@ -0,0 +1,160 @@ +'\" et +.TH SIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sin, +sinf, +sinl +\(em sine function +.SH SYNOPSIS +.LP +.nf +#include +.P +double sin(double \fIx\fP); +float sinf(float \fIx\fP); +long double sinl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the sine of their argument +.IR x , +measured in radians. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the sine of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIsin\fR(), +\fIsinf\fR(), +and +\fIsinl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Taking the Sine of a 45-Degree Angle" +.sp +.RS 4 +.nf +\fB +#include +\&... +double radians = 45.0 * M_PI / 180; +double result; +\&... +result = sin(radians); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +These functions may lose accuracy when their argument is near a +multiple of \(*p or is far from 0.0. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasin\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sinh.3p b/man-pages-posix-2013-a/man3p/sinh.3p new file mode 100644 index 0000000..4137556 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sinh.3p @@ -0,0 +1,145 @@ +'\" et +.TH SINH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sinh, +sinhf, +sinhl +\(em hyperbolic sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double sinh(double \fIx\fP); +float sinhf(float \fIx\fP); +long double sinhl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the hyperbolic sine of their argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the hyperbolic +sine of +.IR x . +.P +If the result would cause an overflow, a range error shall occur and +\(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (with the same sign as +.IR x ) +shall be returned as appropriate for the type of the function. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIsinh\fR(), +\fIsinhf\fR(), +and +\fIsinhl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result would cause an overflow. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasinh\fR\^(\|)", +.IR "\fIcosh\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fItanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sinl.3p b/man-pages-posix-2013-a/man3p/sinl.3p new file mode 100644 index 0000000..1872e03 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sinl.3p @@ -0,0 +1,38 @@ +'\" et +.TH SINL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sinl +\(em sine function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double sinl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsin\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sleep.3p b/man-pages-posix-2013-a/man3p/sleep.3p new file mode 100644 index 0000000..467d9d9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sleep.3p @@ -0,0 +1,224 @@ +'\" et +.TH SLEEP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sleep +\(em suspend execution for an interval of time +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned sleep(unsigned \fIseconds\fP); +.fi +.SH DESCRIPTION +The +\fIsleep\fR() +function shall cause the calling thread to be suspended from execution +until either the number of realtime seconds specified by the argument +.IR seconds +has elapsed or a signal is delivered to the calling thread and its +action is to invoke a signal-catching function or to terminate the +process. The suspension time may be longer than requested due to the +scheduling of other activity by the system. +.P +If a SIGALRM signal is generated for the calling process during +execution of +\fIsleep\fR() +and if the SIGALRM signal is being ignored or blocked from delivery, it +is unspecified whether +\fIsleep\fR() +returns when the SIGALRM signal is scheduled. If the signal is being +blocked, it is also unspecified whether it remains pending after +\fIsleep\fR() +returns or it is discarded. +.P +If a SIGALRM signal is generated for the calling process during +execution of +\fIsleep\fR(), +except as a result of a prior call to +\fIalarm\fR(), +and if the SIGALRM signal is not being ignored or blocked from +delivery, it is unspecified whether that signal has any effect other +than causing +\fIsleep\fR() +to return. +.P +If a signal-catching function interrupts +\fIsleep\fR() +and examines or changes either the time a SIGALRM is scheduled to be +generated, the action associated with the SIGALRM signal, or whether +the SIGALRM signal is blocked from delivery, the results are +unspecified. +.P +If a signal-catching function interrupts +\fIsleep\fR() +and calls +\fIsiglongjmp\fR() +or +\fIlongjmp\fR() +to restore an environment saved prior to the +\fIsleep\fR() +call, the action associated with the SIGALRM signal and the time at +which a SIGALRM signal is scheduled to be generated are unspecified. +It is also unspecified whether the SIGALRM signal is blocked, unless +the signal mask of the process is restored as part of the environment. +.P +Interactions between +\fIsleep\fR() +and +\fIsetitimer\fR() +are unspecified. +.SH "RETURN VALUE" +If +\fIsleep\fR() +returns because the requested time has elapsed, the value returned +shall be 0. If +\fIsleep\fR() +returns due to delivery of a signal, the return value shall be +the ``unslept'' amount (the requested time minus the time actually +slept) in seconds. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +There are two general approaches to the implementation of the +\fIsleep\fR() +function. One is to use the +\fIalarm\fR() +function to schedule a SIGALRM +signal and then suspend the calling thread waiting for that signal. The +other is to implement an independent facility. This volume of POSIX.1\(hy2008 permits either +approach. +.P +In order to comply with the requirement that no primitive shall change +a process attribute unless explicitly described by this volume of POSIX.1\(hy2008, an +implementation using SIGALRM must carefully take into account any +SIGALRM signal scheduled by previous +\fIalarm\fR() +calls, the action previously established for SIGALRM, and whether +SIGALRM was blocked. If a SIGALRM has been scheduled before the +\fIsleep\fR() +would ordinarily complete, the +\fIsleep\fR() +must be shortened to that time and a SIGALRM generated (possibly +simulated by direct invocation of the signal-catching function) before +\fIsleep\fR() +returns. If a SIGALRM has been scheduled after the +\fIsleep\fR() +would ordinarily complete, it must be rescheduled for the same time +before +\fIsleep\fR() +returns. The action and blocking for SIGALRM must be saved and +restored. +.P +Historical implementations often implement the SIGALRM-based version +using +\fIalarm\fR() +and +\fIpause\fR(). +One such implementation is prone to infinite hangups, as described in +.IR "\fIpause\fR\^(\|)". +Another such implementation uses the C-language +\fIsetjmp\fR() +and +\fIlongjmp\fR() +functions to avoid that window. That implementation introduces a +different problem: when the SIGALRM signal interrupts a signal-catching +function installed by the user to catch a different signal, the +\fIlongjmp\fR() +aborts that signal-catching function. An implementation based on +\fIsigprocmask\fR(), +\fIalarm\fR(), +and +\fIsigsuspend\fR() +can avoid these problems. +.P +Despite all reasonable care, there are several very subtle, but +detectable and unavoidable, differences between the two types of +implementations. These are the cases mentioned in this volume of POSIX.1\(hy2008 where +some other activity relating to SIGALRM takes place, and the results +are stated to be unspecified. All of these cases are sufficiently +unusual as not to be of concern to most applications. +.P +See also the discussion of the term +.IR realtime +in +.IR "\fIalarm\fR\^(\|)". +.P +Since +\fIsleep\fR() +can be implemented using +\fIalarm\fR(), +the discussion about alarms occurring early under +\fIalarm\fR() +applies to +\fIsleep\fR() +as well. +.P +Application developers should note that the type of the argument +.IR seconds +and the return value of +\fIsleep\fR() +is +.BR unsigned . +That means that a Strictly Conforming POSIX System Interfaces +Application +cannot pass a value greater than the minimum guaranteed value for +{UINT_MAX}, +which the ISO\ C standard sets as 65\|535, and any application passing a larger +value is restricting its portability. A different type was considered, +but historical implementations, including those with a 16-bit +.BR int +type, consistently use either +.BR unsigned +or +.BR int . +.P +Scheduling delays may cause the process to return from the +\fIsleep\fR() +function significantly after the requested time. In such cases, the +return value should be set to zero, since the formula (requested time +minus the time actually spent) yields a negative number and +\fIsleep\fR() +returns an +.BR unsigned . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpause\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/snprintf.3p b/man-pages-posix-2013-a/man3p/snprintf.3p new file mode 100644 index 0000000..58d1182 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/snprintf.3p @@ -0,0 +1,39 @@ +'\" et +.TH SNPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +snprintf +\(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int snprintf(char *restrict \fIs\fP, size_t \fIn\fP, + const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sockatmark.3p b/man-pages-posix-2013-a/man3p/sockatmark.3p new file mode 100644 index 0000000..26b231d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sockatmark.3p @@ -0,0 +1,149 @@ +'\" et +.TH SOCKATMARK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sockatmark +\(em determine whether a socket is at the out-of-band mark +.SH SYNOPSIS +.LP +.nf +#include +.P +int sockatmark(int \fIs\fR); +.fi +.SH DESCRIPTION +The +\fIsockatmark\fR() +function shall determine whether the socket specified by the descriptor +.IR s +is at the out-of-band data mark (see +.IR "Section 2.10.12" ", " "Socket Out-of-Band Data State"). +If the protocol for the socket supports out-of-band data by marking the +stream with an out-of-band data mark, the +\fIsockatmark\fR() +function shall return 1 when all data preceding the mark has been read +and the out-of-band data mark is the first element in the receive +queue. The +\fIsockatmark\fR() +function shall not remove the mark from the stream. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsockatmark\fR() +function shall return a value indicating whether the socket is at an +out-of-band data mark. If the protocol has marked the data stream and +all data preceding the mark has been read, the return value shall be 1; +if there is no mark, or if data precedes the mark in the receive queue, +the +\fIsockatmark\fR() +function shall return 0. Otherwise, it shall return a value of \(mi1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsockatmark\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR s +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR s +argument is not a socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The use of this function between receive operations allows an +application to determine which received data precedes the out-of-band +data and which follows the out-of-band data. +.P +There is an inherent race condition in the use of this function. On an +empty receive queue, the current read of the location might well be at +the ``mark'', but the system has no way of knowing that the next data +segment that will arrive from the network will carry the mark, and +\fIsockatmark\fR() +will return false, and the next read operation will silently consume +the mark. +.P +Hence, this function can only be used reliably when the application +already knows that the out-of-band data has been seen by the system or +that it is known that there is data waiting to be read at the socket +(via SIGURG or +\fIselect\fR()). +See +.IR "Section 2.10.11" ", " "Socket Receive Queue", +.IR "Section 2.10.12" ", " "Socket Out-of-Band Data State", +.IR "Section 2.10.14" ", " "Signals", +and +\fIpselect\fR() +for details. +.SH RATIONALE +The +\fIsockatmark\fR() +function replaces the historical SIOCATMARK command to +\fIioctl\fR() +which implemented the same functionality on many implementations. Using +a wrapper function follows the adopted conventions to avoid specifying +commands to the +\fIioctl\fR() +function, other than those now included to support XSI STREAMS. The +\fIsockatmark\fR() +function could be implemented as follows: +.sp +.RS 4 +.nf +\fB +#include +.P +int sockatmark(int s) +{ + int val; + if (ioctl(s,SIOCATMARK,&val)==\(mi1) + return(\(mi1); + return(val); +} +.fi \fR +.P +.RE +.P +The use of +.BR [ENOTTY] +to indicate an incorrect descriptor type matches the historical +behavior of SIOCATMARK. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.10.12" ", " "Socket Out-of-Band Data State", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/socket.3p b/man-pages-posix-2013-a/man3p/socket.3p new file mode 100644 index 0000000..da1fc88 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/socket.3p @@ -0,0 +1,182 @@ +'\" et +.TH SOCKET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +socket +\(em create an endpoint for communication +.SH SYNOPSIS +.LP +.nf +#include +.P +int socket(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP); +.fi +.SH DESCRIPTION +The +\fIsocket\fR() +function shall create an unbound socket in a communications domain, and +return a file descriptor that can be used in later function calls that +operate on sockets. +.P +The +\fIsocket\fR() +function takes the following arguments: +.IP "\fIdomain\fR" 12 +Specifies the communications domain in which a socket is to be +created. +.IP "\fItype\fR" 12 +Specifies the type of socket to be created. +.IP "\fIprotocol\fR" 12 +Specifies a particular protocol to be used with the socket. Specifying +a +.IR protocol +of 0 causes +\fIsocket\fR() +to use an unspecified default protocol appropriate for the requested +socket type. +.P +The +.IR domain +argument specifies the address family used in the communications +domain. The address families supported by the system are +implementation-defined. +.P +Symbolic constants that can be used for the domain argument are defined +in the +.IR +header. +.P +The +.IR type +argument specifies the socket type, which determines the semantics of +communication over the socket. The following socket types are defined; +implementations may specify additional socket types: +.IP SOCK_STREAM 12 +Provides sequenced, reliable, bidirectional, connection-mode byte +streams, and may provide a transmission mechanism for out-of-band +data. +.IP SOCK_DGRAM 12 +Provides datagrams, which are connectionless-mode, unreliable messages +of fixed maximum length. +.IP SOCK_SEQPACKET 12 +.br +Provides sequenced, reliable, bidirectional, connection-mode +transmission paths for records. A record can be sent using one or more +output operations and received using one or more input operations, but +a single operation never transfers part of more than one record. Record +boundaries are visible to the receiver via the MSG_EOR flag. +.P +If the +.IR protocol +argument is non-zero, it shall specify a protocol that is supported by +the address family. If the +.IR protocol +argument is zero, the default protocol for this address family and type +shall be used. The protocols supported by the system are +implementation-defined. +.P +The process may need to have appropriate privileges to use the +\fIsocket\fR() +function or to create some sockets. +.SH "RETURN VALUE" +Upon successful completion, +\fIsocket\fR() +shall return a non-negative integer, the socket file descriptor. +Otherwise, a value of \(mi1 shall be returned and +.IR errno +set to indicate the error. +.br +.SH ERRORS +The +\fIsocket\fR() +function shall fail if: +.TP +.BR EAFNOSUPPORT +.br +The implementation does not support the specified address family. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +No more file descriptors are available for the system. +.TP +.BR EPROTONOSUPPORT +.br +The protocol is not supported by the address family, or the protocol is +not supported by the implementation. +.TP +.BR EPROTOTYPE +The socket type is not supported by the protocol. +.P +The +\fIsocket\fR() +function may fail if: +.TP +.BR EACCES +The process does not have appropriate privileges. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The documentation for specific address families specifies which +protocols each address family supports. The documentation for specific +protocols specifies which socket types each protocol supports. +.P +The application can determine whether an address family is supported by +trying to create a socket with +.IR domain +set to the protocol in question. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIlisten\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocketpair\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/socketpair.3p b/man-pages-posix-2013-a/man3p/socketpair.3p new file mode 100644 index 0000000..8b3ddef --- /dev/null +++ b/man-pages-posix-2013-a/man3p/socketpair.3p @@ -0,0 +1,170 @@ +'\" et +.TH SOCKETPAIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +socketpair +\(em create a pair of connected sockets +.SH SYNOPSIS +.LP +.nf +#include +.P +int socketpair(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP, + int \fIsocket_vector\fP[2]); +.fi +.SH DESCRIPTION +The +\fIsocketpair\fR() +function shall create an unbound pair of connected sockets in a +specified +.IR domain , +of a specified +.IR type , +under the protocol optionally specified by the +.IR protocol +argument. The two sockets shall be identical. The file descriptors +used in referencing the created sockets shall be returned in +.IR socket_vector [0] +and +.IR socket_vector [1]. +.P +The +\fIsocketpair\fR() +function takes the following arguments: +.IP "\fIdomain\fR" 12 +Specifies the communications domain in which the sockets are to be +created. +.IP "\fItype\fR" 12 +Specifies the type of sockets to be created. +.IP "\fIprotocol\fR" 12 +Specifies a particular protocol to be used with the sockets. +Specifying a +.IR protocol +of 0 causes +\fIsocketpair\fR() +to use an unspecified default protocol appropriate for the requested +socket type. +.IP "\fIsocket_vector\fR" 12 +Specifies a 2-integer array to hold the file descriptors of the created +socket pair. +.P +The +.IR type +argument specifies the socket type, which determines the semantics of +communications over the socket. The following socket types are defined; +implementations may specify additional socket types: +.IP SOCK_STREAM 14 +Provides sequenced, reliable, bidirectional, connection-mode byte +streams, and may provide a transmission mechanism for out-of-band +data. +.IP SOCK_DGRAM 14 +Provides datagrams, which are connectionless-mode, unreliable messages +of fixed maximum length. +.IP SOCK_SEQPACKET 14 +Provides sequenced, reliable, bidirectional, connection-mode +transmission paths for records. A record can be sent using one or more +output operations and received using one or more input operations, but +a single operation never transfers part of more than one record. Record +boundaries are visible to the receiver via the MSG_EOR flag. +.P +If the +.IR protocol +argument is non-zero, it shall specify a protocol that is supported by +the address family. If the +.IR protocol +argument is zero, the default protocol for this address family and type +shall be used. The protocols supported by the system are +implementation-defined. +.P +The process may need to have appropriate privileges to use the +\fIsocketpair\fR() +function or to create some sockets. +.SH "RETURN VALUE" +Upon successful completion, this function shall return 0; otherwise, +\(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsocketpair\fR() +function shall fail if: +.TP +.BR EAFNOSUPPORT +.br +The implementation does not support the specified address family. +.TP +.BR EMFILE +All, or all but one, of the file descriptors available to the +process are currently open. +.TP +.BR ENFILE +No more file descriptors are available for the system. +.TP +.BR EOPNOTSUPP +The specified protocol does not permit creation of socket pairs. +.TP +.BR EPROTONOSUPPORT +.br +The protocol is not supported by the address family, or the protocol is +not supported by the implementation. +.TP +.BR EPROTOTYPE +The socket type is not supported by the protocol. +.P +The +\fIsocketpair\fR() +function may fail if: +.TP +.BR EACCES +The process does not have appropriate privileges. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The documentation for specific address families specifies which +protocols each address family supports. The documentation for specific +protocols specifies which socket types each protocol supports. +.P +The +\fIsocketpair\fR() +function is used primarily with UNIX domain sockets and need not be +supported for other domains. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sprintf.3p b/man-pages-posix-2013-a/man3p/sprintf.3p new file mode 100644 index 0000000..72c9e14 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sprintf.3p @@ -0,0 +1,38 @@ +'\" et +.TH SPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sprintf +\(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int sprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sqrt.3p b/man-pages-posix-2013-a/man3p/sqrt.3p new file mode 100644 index 0000000..f1a8c3a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sqrt.3p @@ -0,0 +1,136 @@ +'\" et +.TH SQRT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.EQ +delim $$ +.EN +.SH NAME +sqrt, +sqrtf, +sqrtl +\(em square root function +.SH SYNOPSIS +.LP +.nf +#include +.P +double sqrt(double \fIx\fP); +float sqrtf(float \fIx\fP); +long double sqrtl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the square root of their argument +.IR x , +$sqrt {x}$. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the square +root of +.IR x . +.P +For finite values of +.IR x +< \(mi0, a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or +Inf, +.IR x +shall be returned. +.P +If +.IR x +is \(miInf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is < \(mi0, +or +.IR x +is \(miInf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Taking the Square Root of 9.0" +.sp +.RS 4 +.nf +\fB +#include +\&... +double x = 9.0; +double result; +\&... +result = sqrt(x); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/srand.3p b/man-pages-posix-2013-a/man3p/srand.3p new file mode 100644 index 0000000..1d03553 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/srand.3p @@ -0,0 +1,38 @@ +'\" et +.TH SRAND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +srand +\(em pseudo-random number generator +.SH SYNOPSIS +.LP +.nf +#include +.P +void srand(unsigned \fIseed\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIrand\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/srand48.3p b/man-pages-posix-2013-a/man3p/srand48.3p new file mode 100644 index 0000000..e645ce7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/srand48.3p @@ -0,0 +1,39 @@ +'\" et +.TH SRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +srand48 +\(em seed the uniformly distributed double-precision pseudo-random +number generator +.SH SYNOPSIS +.LP +.nf +#include +.P +void srand48(long \fIseedval\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/srandom.3p b/man-pages-posix-2013-a/man3p/srandom.3p new file mode 100644 index 0000000..26a0b0b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/srandom.3p @@ -0,0 +1,38 @@ +'\" et +.TH SRANDOM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +srandom +\(em seed pseudo-random number generator +.SH SYNOPSIS +.LP +.nf +#include +.P +void srandom(unsigned \fIseed\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIinitstate\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sscanf.3p b/man-pages-posix-2013-a/man3p/sscanf.3p new file mode 100644 index 0000000..117c217 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sscanf.3p @@ -0,0 +1,38 @@ +'\" et +.TH SSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sscanf +\(em convert formatted input +.SH SYNOPSIS +.LP +.nf +#include +.P +int sscanf(const char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfscanf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/stat.3p b/man-pages-posix-2013-a/man3p/stat.3p new file mode 100644 index 0000000..5f7a2b4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/stat.3p @@ -0,0 +1,38 @@ +'\" et +.TH STAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stat +\(em get file status +.SH SYNOPSIS +.LP +.nf +#include +.P +int stat(const char *restrict \fIpath\fP, struct stat *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfstatat\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/statvfs.3p b/man-pages-posix-2013-a/man3p/statvfs.3p new file mode 100644 index 0000000..429e2d0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/statvfs.3p @@ -0,0 +1,38 @@ +'\" et +.TH STATVFS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +statvfs +\(em get file system information +.SH SYNOPSIS +.LP +.nf +#include +.P +int statvfs(const char *restrict \fIpath\fP, struct statvfs *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfstatvfs\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/stdin.3p b/man-pages-posix-2013-a/man3p/stdin.3p new file mode 100644 index 0000000..f89bc60 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/stdin.3p @@ -0,0 +1,129 @@ +'\" et +.TH STDIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stderr, +stdin, +stdout +\(em standard I/O streams +.SH SYNOPSIS +.LP +.nf +#include +.P +extern FILE *stderr, *stdin, *stdout; +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +A file with associated buffering is called a +.IR stream +and is declared to be a pointer to a defined type +.BR FILE . +The +\fIfopen\fR() +function shall create certain descriptive data for a stream and return +a pointer to designate the stream in all further transactions. Normally, +there are three open streams with constant pointers declared in the +.IR +header and associated with the standard open files. +.P +At program start-up, three streams shall be predefined and need not +be opened explicitly: +.IR "standard input" +(for reading conventional input), +.IR "standard output" +(for writing conventional output), and +.IR "standard error" +(for writing diagnostic output). When opened, the standard error +stream is not fully buffered; the standard input and standard output +streams are fully buffered if and only if the stream can be determined +not to refer to an interactive device. +.P +The following symbolic values in +.IR +define the file descriptors that shall be associated with the C-language +.IR stdin , +.IR stdout , +and +.IR stderr +when the application is started: +.IP STDIN_FILENO 14 +Standard input value, +.IR stdin . +Its value is 0. +.IP STDOUT_FILENO 14 +Standard output value, +.IR stdout . +Its value is 1. +.IP STDERR_FILENO 14 +Standard error value, +.IR stderr . +Its value is 2. +.P +The +.IR stderr +stream is expected to be open for reading and writing. +.SH "RETURN VALUE" +None. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfileno\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputs\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)", +.IR "\fIsetvbuf\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)", +.IR "\fIvfprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/stpcpy.3p b/man-pages-posix-2013-a/man3p/stpcpy.3p new file mode 100644 index 0000000..08ae046 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/stpcpy.3p @@ -0,0 +1,38 @@ +'\" et +.TH STPCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stpcpy +\(em copy a string and return a pointer to the end of the result +.SH SYNOPSIS +.LP +.nf +#include +.P +char *stpcpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrcpy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/stpncpy.3p b/man-pages-posix-2013-a/man3p/stpncpy.3p new file mode 100644 index 0000000..13c37a9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/stpncpy.3p @@ -0,0 +1,38 @@ +'\" et +.TH STPNCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stpncpy +\(em copy fixed length string, returning a pointer to the array end +.SH SYNOPSIS +.LP +.nf +#include +.P +char *stpncpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrncpy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strcasecmp.3p b/man-pages-posix-2013-a/man3p/strcasecmp.3p new file mode 100644 index 0000000..1f23c8c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strcasecmp.3p @@ -0,0 +1,135 @@ +'\" et +.TH STRCASECMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strcasecmp, +strcasecmp_l, +strncasecmp, +strncasecmp_l +\(em case-insensitive string comparisons +.SH SYNOPSIS +.LP +.nf +#include +.P +int strcasecmp(const char *\fIs1\fP, const char *\fIs2\fP); +int strcasecmp_l(const char *\fIs1\fP, const char *\fIs2\fP, + locale_t \fIlocale\fP); +int strncasecmp(const char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP); +int strncasecmp_l(const char *\fIs1\fP, const char *\fIs2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +The +\fIstrcasecmp\fR() +and +\fIstrcasecmp_l\fR() +functions shall compare, while ignoring differences in case, the +string pointed to by +.IR s1 +to the string pointed to by +.IR s2 . +The +\fIstrncasecmp\fR() +and +\fIstrncasecmp_l\fR() +functions shall compare, while ignoring differences in case, not more +than +.IR n +bytes from the string pointed to by +.IR s1 +to the string pointed to by +.IR s2 . +.P +The +\fIstrcasecmp\fR() +and +\fIstrncasecmp\fR() +functions use the current locale to determine the case of the characters. +.P +The +\fIstrcasecmp_l\fR() +and +\fIstrncasecmp_l\fR() +functions use the locale represented by +.IR locale +to determine the case of the characters. +.P +When the +.IR LC_CTYPE +category of the locale being used is from the POSIX locale, these +functions shall behave as if the strings had been converted to lowercase +and then a byte comparison performed. Otherwise, the results are +unspecified. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrcasecmp_l\fR() +or +\fIstrncasecmp_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon completion, +\fIstrcasecmp\fR() +and +\fIstrcasecmp_l\fR() +shall return an integer greater than, equal to, or less than 0, if the +string pointed to by +.IR s1 +is, ignoring case, greater than, equal to, or less than the string +pointed to by +.IR s2 , +respectively. +.P +Upon successful completion, +\fIstrncasecmp\fR() +and +\fIstrncasecmp_l\fR() +shall return an integer greater than, equal to, or less than 0, if the +possibly null-terminated array pointed to by +.IR s1 +is, ignoring case, greater than, equal to, or less than the possibly +null-terminated array pointed to by +.IR s2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscasecmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strcat.3p b/man-pages-posix-2013-a/man3p/strcat.3p new file mode 100644 index 0000000..8f0a8d8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strcat.3p @@ -0,0 +1,78 @@ +'\" et +.TH STRCAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strcat +\(em concatenate two strings +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strcat(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrcat\fR() +function shall append a copy of the string pointed to by +.IR s2 +(including the terminating NUL character) to the end of the string pointed +to by +.IR s1 . +The initial byte of +.IR s2 +overwrites the NUL character at the end of +.IR s1 . +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fIstrcat\fR() +function shall return +.IR s1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +This version is aligned with the ISO\ C standard; this does not affect +compatibility with XPG3 applications. Reliable error detection by this +function was never guaranteed. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrncat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strchr.3p b/man-pages-posix-2013-a/man3p/strchr.3p new file mode 100644 index 0000000..3add32f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strchr.3p @@ -0,0 +1,71 @@ +'\" et +.TH STRCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strchr +\(em string scanning operation +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strchr(const char *\fIs\fP, int \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrchr\fR() +function shall locate the first occurrence of +.IR c +(converted to a +.BR char ) +in the string pointed to by +.IR s . +The terminating NUL character is considered to be part of the string. +.SH "RETURN VALUE" +Upon completion, +\fIstrchr\fR() +shall return a pointer to the byte, or a null pointer if the byte +was not found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strcmp.3p b/man-pages-posix-2013-a/man3p/strcmp.3p new file mode 100644 index 0000000..8f67c8e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strcmp.3p @@ -0,0 +1,125 @@ +'\" et +.TH STRCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strcmp +\(em compare two strings +.SH SYNOPSIS +.LP +.nf +#include +.P +int strcmp(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrcmp\fR() +function shall compare the string pointed to by +.IR s1 +to the string pointed to by +.IR s2 . +.P +The sign of a non-zero return value shall be determined by the sign of +the difference between the values of the first pair of bytes (both +interpreted as type +.BR "unsigned char" ) +that differ in the strings being compared. +.SH "RETURN VALUE" +Upon completion, +\fIstrcmp\fR() +shall return an integer greater than, equal to, or less than 0, if the +string pointed to by +.IR s1 +is greater than, equal to, or less than the string pointed to by +.IR s2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Checking a Password Entry" +.P +The following example compares the information read from standard input +to the value of the name of the user entry. If the +\fIstrcmp\fR() +function returns 0 (indicating a match), a further check will be made +to see if the user entered the proper old password. The +\fIcrypt\fR() +function shall encrypt the old password entered by the user, using +the value of the encrypted password in the +.BR passwd +structure as the salt. If this value matches the value of the encrypted +.BR passwd +in the structure, the entered password +.IR oldpasswd +is the correct user's password. Finally, the program encrypts the new +password so that it can store the information in the +.BR passwd +structure. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +int valid_change; +struct passwd *p; +char user[100]; +char oldpasswd[100]; +char newpasswd[100]; +char savepasswd[100]; +\&... +if (strcmp(p->pw_name, user) == 0) { + if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { + strcpy(savepasswd, crypt(newpasswd, user)); + p->pw_passwd = savepasswd; + valid_change = 1; + } + else { + fprintf(stderr, "Old password is not valid\en"); + } +} +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrncmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strcoll.3p b/man-pages-posix-2013-a/man3p/strcoll.3p new file mode 100644 index 0000000..7c7b896 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strcoll.3p @@ -0,0 +1,170 @@ +'\" et +.TH STRCOLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strcoll, +strcoll_l +\(em string comparison using collating information +.SH SYNOPSIS +.LP +.nf +#include +.P +int strcoll(const char *\fIs1\fP, const char *\fIs2\fP); +int strcoll_l(const char *\fIs1\fP, const char *\fIs2\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIstrcoll\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrcoll\fR() +and +\fIstrcoll_l\fR() +functions shall compare the string pointed to by +.IR s1 +to the string pointed to by +.IR s2 , +both interpreted as appropriate to the +.IR LC_COLLATE +category of the current locale, +or of the locale represented by +.IR locale , +respectively. +.P +The +\fIstrcoll\fR() +and +\fIstrcoll_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrcoll\fR(), +or +\fIstrcoll_l\fR() +then check +.IR errno . +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrcoll_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrcoll\fR() +shall return an integer greater than, equal to, or less than +0, according to whether the string pointed to by +.IR s1 +is greater than, equal to, or less than the string pointed to by +.IR s2 +when both are interpreted as appropriate to the current locale. +On error, +\fIstrcoll\fR() +may set +.IR errno , +but no return value is reserved to indicate an error. +.P +Upon successful completion, +\fIstrcoll_l\fR() +shall return an integer greater than, equal to, or less than 0, +according to whether the string pointed to by +.IR s1 +is greater than, equal to, or less than the string pointed to by +.IR s2 +when both are interpreted as appropriate to the locale represented by +.IR locale . +On error, +\fIstrcoll_l\fR() +may set +.IR errno , +but no return value is reserved to indicate an error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The +.IR s1 +or +.IR s2 +arguments contain characters outside the domain of the collating +sequence. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Comparing Nodes" +.P +The following example uses an application-defined function, +\fInode_compare\fR(), +to compare two nodes based on an alphabetical ordering of the +.IR string +field. +.sp +.RS 4 +.nf +\fB +#include +\&... +struct node { /* These are stored in the table. */ + char *string; + int length; +}; +\&... +int node_compare(const void *node1, const void *node2) +{ + return strcoll(((const struct node *)node1)->string, + ((const struct node *)node2)->string); +} +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIstrxfrm\fR() +and +\fIstrcmp\fR() +functions should be used for sorting large lists. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalphasort\fR\^(\|)", +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fIstrxfrm\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strcpy.3p b/man-pages-posix-2013-a/man3p/strcpy.3p new file mode 100644 index 0000000..6e0c352 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strcpy.3p @@ -0,0 +1,178 @@ +'\" et +.TH STRCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stpcpy, strcpy +\(em copy a string and return a pointer to the end of the result +.SH SYNOPSIS +.LP +.nf +#include +.P +char *stpcpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +char *strcpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +.fi +.SH DESCRIPTION +For +\fIstrcpy\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstpcpy\fR() +and +\fIstrcpy\fR() +functions shall copy the string pointed to by +.IR s2 +(including the terminating NUL character) into the array pointed to by +.IR s1 . +.P +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fIstpcpy\fR() +function shall return a pointer to the terminating NUL character copied +into the +.IR s1 +buffer. +.P +The +\fIstrcpy\fR() +function shall return +.IR s1 . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Construction of a Multi-Part Message in a Single Buffer" +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int +main (void) +{ + char buffer [10]; + char *name = buffer; +.P + name = stpcpy (stpcpy (stpcpy (name, "ice"),"-"), "cream"); + puts (buffer); + return 0; +} +.fi \fR +.P +.RE +.SS "Initializing a String" +.P +The following example copies the string +.BR \(dq----------\(dq +into the +.IR permstring +variable. +.sp +.RS 4 +.nf +\fB +#include +\&... +static char permstring[11]; +\&... +strcpy(permstring, "----------"); +\&... +.fi \fR +.P +.RE +.SS "Storing a Key and Data" +.P +The following example allocates space for a key using +\fImalloc\fR() +then uses +\fIstrcpy\fR() +to place the key there. Then it allocates space for data using +\fImalloc\fR(), +and uses +\fIstrcpy\fR() +to place data there. (The user-defined function +\fIdbfree\fR() +frees memory previously allocated to an array of type +.BR "struct element *" .) +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +/* Structure used to read data and store it. */ +struct element { + char *key; + char *data; +}; +.P +struct element *tbl, *curtbl; +char *key, *data; +int count; +\&... +void dbfree(struct element *, int); +\&... +if ((curtbl->key = malloc(strlen(key) + 1)) == NULL) { + perror("malloc"); dbfree(tbl, count); return NULL; +} +strcpy(curtbl->key, key); +.P +if ((curtbl->data = malloc(strlen(data) + 1)) == NULL) { + perror("malloc"); free(curtbl->key); dbfree(tbl, count); return NULL; +} +strcpy(curtbl->data, data); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Character movement is performed differently in different +implementations. Thus, overlapping moves may yield surprises. +.P +This version is aligned with the ISO\ C standard; this does not affect +compatibility with XPG3 applications. Reliable error detection by this +function was never guaranteed. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrncpy\fR\^(\|)", +.IR "\fIwcscpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strcspn.3p b/man-pages-posix-2013-a/man3p/strcspn.3p new file mode 100644 index 0000000..cf87337 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strcspn.3p @@ -0,0 +1,73 @@ +'\" et +.TH STRCSPN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strcspn +\(em get the length of a complementary substring +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strcspn(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrcspn\fR() +function shall compute the length (in bytes) of the maximum initial +segment of the string pointed to by +.IR s1 +which consists entirely of bytes +.IR not +from the string pointed to by +.IR s2 . +.SH "RETURN VALUE" +The +\fIstrcspn\fR() +function shall return the length of the computed segment of the string +pointed to by +.IR s1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrspn\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strdup.3p b/man-pages-posix-2013-a/man3p/strdup.3p new file mode 100644 index 0000000..f2009c0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strdup.3p @@ -0,0 +1,119 @@ +'\" et +.TH STRDUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strdup, strndup +\(em duplicate a specific number of bytes from a string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strdup(const char *\fIs\fP); +char *strndup(const char *\fIs\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIstrdup\fR() +function shall return a pointer to a new string, which is a duplicate +of the string pointed to by +.IR s . +The returned pointer can be passed to +\fIfree\fR(). +A null pointer is returned if the new string cannot be created. +.P +The +\fIstrndup\fR() +function shall be equivalent to the +\fIstrdup\fR() +function, duplicating the provided +.IR s +in a new block of memory allocated as if by using +\fImalloc\fR(), +with the exception being that +\fIstrndup\fR() +copies at most +.IR size +plus one bytes into the newly allocated memory, terminating the new +string with a NUL character. If the length of +.IR s +is larger than +.IR size , +only +.IR size +bytes shall be duplicated. If +.IR size +is larger than the length of +.IR s , +all bytes in +.IR s +shall be copied into the new memory buffer, including the terminating +NUL character. The newly created string shall always be properly +terminated. +.SH "RETURN VALUE" +The +\fIstrdup\fR() +function shall return a pointer to a new string on success. Otherwise, +it shall return a null pointer and set +.IR errno +to indicate the error. +.P +Upon successful completion, the +\fIstrndup\fR() +function shall return a pointer to the newly allocated memory +containing the duplicated string. Otherwise, it shall return a null +pointer and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR ENOMEM +Storage space available is insufficient. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIstrdup\fR() +and +\fIstrndup\fR(), +this is the return value. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fIwcsdup\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strerror.3p b/man-pages-posix-2013-a/man3p/strerror.3p new file mode 100644 index 0000000..815b318 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strerror.3p @@ -0,0 +1,307 @@ +'\" et +.TH STRERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strerror, +strerror_l, +strerror_r +\(em get error message string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strerror(int \fIerrnum\fR); +char *strerror_l(int \fIerrnum\fR, locale_t \fIlocale\fR); +int strerror_r(int \fIerrnum\fR, char *\fIstrerrbuf\fR, size_t \fIbuflen\fR); +.fi +.SH DESCRIPTION +For +\fIstrerror\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrerror\fR() +function shall map the error number in +.IR errnum +to a locale-dependent error message string and shall return a pointer +to it. Typically, the values for +.IR errnum +come from +.IR errno , +but +\fIstrerror\fR() +shall map any value of type +.BR int +to a message. +.P +The application shall not modify the string returned. +The returned string pointer might be invalidated or +the string content might be overwritten by a subsequent call to +\fIstrerror\fR(), +or by a subsequent call to +\fIstrerror_l\fR() +in the same thread. +.P +The string may be overwritten by a subsequent call to +\fIstrerror_l\fR() +in the same thread. +.P +The contents of the error message strings returned by +\fIstrerror\fR() +should be determined by the setting of the +.IR LC_MESSAGES +category in the current locale. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 +calls +\fIstrerror\fR(). +.P +The +\fIstrerror\fR() +and +\fIstrerror_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error of +\fIstrerror\fR(), +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrerror\fR(), +then check +.IR errno . +Similarly, since +\fIstrerror_l\fR() +is required to return a string for some errors, an application wishing +to check for all error situations should set +.IR errno +to 0, then call +\fIstrerror_l\fR(), +then check +.IR errno . +.P +The +\fIstrerror\fR() +function need not be thread-safe. +.P +The +\fIstrerror_l\fR() +function shall map the error number in +.IR errnum +to a locale-dependent error message string in the locale represented by +.IR locale +and shall return a pointer to it. +.P +The +\fIstrerror_r\fR() +function shall map the error number in +.IR errnum +to a locale-dependent error message string and shall return the string +in the buffer pointed to by +.IR strerrbuf , +with length +.IR buflen . +.P +If the value of +.IR errnum +is a valid error number, the message string shall indicate what error +occurred; if the value of +.IR errnum +is zero, the message string shall either be an empty string or +indicate that no error occurred; otherwise, if these functions complete +successfully, the message string shall indicate that an unknown error +occurred. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrerror_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon completion, whether successful or not, +\fIstrerror\fR() +shall return a pointer to the generated message string. +On error +.IR errno +may be set, but no return value is reserved to indicate an error. +.P +Upon successful completion, +\fIstrerror_l\fR() +shall return a pointer to the generated message string. If +.IR errnum +is not a valid error number, +.IR errno +may be set to +.BR [EINVAL] , +but a pointer to a message string shall still be returned. If any other +error occurs, +.IR errno +shall be set to indicate the error and a null pointer shall be +returned. +.P +Upon successful completion, +\fIstrerror_r\fR() +shall return 0. Otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value of +.IR errnum +is neither a valid error number nor zero. +.P +The +\fIstrerror_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR strerrbuf +and +.IR buflen +to contain the generated message string. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Historically in some implementations, calls to +\fIperror\fR() +would overwrite the string that the pointer returned by +\fIstrerror\fR() +points to. Such implementations did not conform to the ISO\ C standard; however, +application developers should be aware of this behavior if they wish +their applications to be portable to such implementations. +.SH RATIONALE +The +\fIstrerror_l\fR() +function is required to be thread-safe, thereby eliminating the +need for an equivalent to the +\fIstrerror_r\fR() +function. +.P +Earlier versions of this standard did not explicitly require that the +error message strings returned by +\fIstrerror\fR() +and +\fIstrerror_r\fR() +provide any information about the error. This version of the standard +requires a meaningful message for any successful completion. +.P +Since no return value is reserved to indicate a +\fIstrerror\fR() +error, but all calls (whether successful or not) must return a pointer +to a message string, on error +\fIstrerror\fR() +can return a pointer to an empty string or a pointer to a meaningful +string that can be printed. +.P +Note that the +.BR [EINVAL] +error condition is a may fail error. If an invalid error number is +supplied as the value of +.IR errnum , +applications should be prepared to handle any of the following: +.IP " 1." 4 +Error (with no meaningful message): +.IR errno +is set to +.BR [EINVAL] , +the return value is a pointer to an empty string. +.IP " 2." 4 +Successful completion: +.IR errno +is unchanged and the return value points to a string like +.BR \(dqunknown error\(dq +or +.BR \(dqerror number xxx\(dq +(where +.IR xxx +is the value of +.IR errnum ). +.IP " 3." 4 +Combination of #1 and #2: +.IR errno +is set to +.BR [EINVAL] +and the return value points to a string like +.BR \(dqunknown error\(dq +or +.BR \(dqerror number xxx\(dq +(where +.IR xxx +is the value of +.IR errnum ). +Since applications frequently use the return value of +\fIstrerror\fR() +as an argument to functions like +\fIfprintf\fR() +(without checking the return value) and since applications have no way +to parse an error message string to determine whether +.IR errnum +represents a valid error number, implementations are encouraged to +implement #3. Similarly, implementations are encouraged to have +\fIstrerror_r\fR() +return +.BR [EINVAL] +and put a string like +.BR \(dqunknown error\(dq +or +.BR \(dqerror number xxx\(dq +in the buffer pointed to by +.IR strerrbuf +when the value of +.IR errnum +is not a valid error number. +.P +Some applications rely on being able to set +.IR errno +to 0 before calling a function with no reserved value to indicate an +error, then call +.IR strerror ( errno ) +afterwards to detect whether an error occurred (because +.IR errno +changed) or to indicate success (because +.IR errno +remained zero). This usage pattern requires that +.IR strerror (0) +succeed with useful results. Previous versions of the standard did not +specify the behavior when +.IR errnum +is zero. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIperror\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strfmon.3p b/man-pages-posix-2013-a/man3p/strfmon.3p new file mode 100644 index 0000000..cbd1796 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strfmon.3p @@ -0,0 +1,326 @@ +'\" et +.TH STRFMON "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strfmon, +strfmon_l +\(em convert monetary value to a string +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t strfmon(char *restrict \fIs\fP, size_t \fImaxsize\fP, + const char *restrict \fIformat\fP, ...); +ssize_t strfmon_l(char *restrict \fIs\fP, size_t \fImaxsize\fP, + locale_t \fIlocale\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +The +\fIstrfmon\fR() +function shall place characters into the array pointed to by +.IR s +as controlled by the string pointed to by +.IR format . +No more than +.IR maxsize +bytes are placed into the array. +.P +The format is a character string, beginning and ending in its +initial state, if any, that contains two types of objects: +\fIplain characters\fP, +which are simply copied to the output stream, and \fIconversion +specifications\fP, +each of which shall result in the fetching of zero or more arguments +which are converted and formatted. The results are undefined if there +are insufficient arguments for the format. If the format is exhausted +while arguments remain, the excess arguments are simply ignored. +.P +The application shall ensure that a conversion specification consists +of the following sequence: +.IP " *" 4 +A +.BR '%' +character +.IP " *" 4 +Optional flags +.IP " *" 4 +Optional field width +.IP " *" 4 +Optional left precision +.IP " *" 4 +Optional right precision +.IP " *" 4 +A required conversion specifier character that determines the +conversion to be performed +.P +The +\fIstrfmon_l\fR() +function shall be equivalent to the +\fIstrfmon\fR() +function, except that the locale data used is from the +locale represented by +.IR locale . +.SS Flags +.P +One or more of the following optional flags can be specified to control +the conversion: +.IP "\fR=\fIf\fR" 8 +An +.BR '=' +followed by a single character +.IR f +which is used as the numeric fill character. In order to work with +precision or width counts, the fill character shall be a single byte +character; if not, the behavior is undefined. The default numeric fill +character is the +. +This flag does not affect field width filling which always uses the +. +This flag is ignored unless a left precision (see below) is specified. +.IP "\fR^\fR" 8 +Do not format the currency amount with grouping characters. The +default is to insert the grouping characters if defined for the current +locale. +.IP "\fR+\fR\ or\ \fR(\fR" 8 +Specify the style of representing positive and negative currency +amounts. Only one of +.BR '+' +or +.BR '(' +may be specified. If +.BR '+' +is specified, the locale's equivalent of +.BR '+' +and +.BR '\(mi' +are used (for example, in many locales, the empty string if positive and +.BR '\(mi' +if negative). If +.BR '(' +is specified, negative amounts are enclosed within parentheses. If +neither flag is specified, the +.BR '+' +style is used. +.IP "\fR!\fR" 8 +Suppress the currency symbol from the output conversion. +.IP "\fR\(mi\fR" 8 +Specify the alignment. If this flag is present the result of the +conversion is left-justified (padded to the right) rather than +right-justified. This flag shall be ignored unless a field width (see +below) is specified. +.SS "Field Width" +.IP "\fIw\fP" 8 +A decimal digit string +.IR w +specifying a minimum field width in bytes in which the result of the +conversion is right-justified (or left-justified if the flag +.BR '\(mi' +is specified). The default is 0. +.SS "Left Precision" +.IP "\fR#\fIn\fR" 8 +A +.BR '#' +followed by a decimal digit string +.IR n +specifying a maximum number of digits expected to be formatted to the +left of the radix character. This option can be used to keep the +formatted output from multiple calls to the +\fIstrfmon\fR() +function aligned in the same columns. It can also be used to fill +unused positions with a special character as in +.BR \(dq$***123.45\(dq . +This option causes an amount to be formatted as if it has the number of +digits specified by +.IR n . +If more than +.IR n +digit positions are required, this conversion specification is ignored. +Digit positions in excess of those actually required are filled with +the numeric fill character (see the \fR=\fIf\fR flag above). +.RS 8 +.P +If grouping has not been suppressed with the +.BR '^' +flag, and it is defined for the current locale, grouping separators are +inserted before the fill characters (if any) are added. Grouping +separators are not applied to fill characters even if the fill +character is a digit. +.P +To ensure alignment, any characters appearing before or after the +number in the formatted output such as currency or sign symbols are +padded as necessary with + +characters to make their positive and negative formats an equal length. +.RE +.SS "Right Precision" +.IP "\fR.\fIp\fR" 8 +A + +followed by a decimal digit string +.IR p +specifying the number of digits after the radix character. If the +value of the right precision +.IR p +is 0, no radix character appears. If a right precision is not +included, a default specified by the current locale is used. The +amount being formatted is rounded to the specified number of digits +prior to formatting. +.SS "Conversion Specifier Characters" +.P +The conversion specifier characters and their meanings are: +.IP "\fRi\fP" 8 +The +.BR double +argument is formatted according to the locale's international currency +format (for example, in the US: USD 1,234.56). If the argument is +\(+-Inf or NaN, the result of the conversion is unspecified. +.IP "\fRn\fP" 8 +The +.BR double +argument is formatted according to the locale's national currency +format (for example, in the US: $1,234.56). If the argument is +\(+-Inf or NaN, the result of the conversion is unspecified. +.IP "\fR%\fP" 8 +Convert to a +.BR '%' ; +no argument is converted. The entire conversion specification shall be +.BR %% . +.SS "Locale Information" +.P +The +.IR LC_MONETARY +category of the current locale affects the behavior of this function +including the monetary radix character (which may be different from the +numeric radix character affected by the +.IR LC_NUMERIC +category), the grouping separator, the currency symbols, and formats. +The international currency symbol should be conformant with the ISO\ 4217:\|2001 standard. +.P +If the value of +.IR maxsize +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrfmon_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +If the total number of resulting bytes including the terminating null +byte is not more than +.IR maxsize , +these functions shall return the number of bytes placed into the array +pointed to by +.IR s , +not including the terminating NUL character. Otherwise, \(mi1 shall be +returned, the contents of the array are unspecified, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR E2BIG +Conversion stopped due to lack of space in the buffer. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +Given a locale for the US and the values 123.45, \(mi123.45, and +3456.781, the following output might be produced. Square brackets (\c +.BR \(dq[\|]\(dq ) +are used in this example to delimit the output. +.sp +.RS 4 +.nf +\fB +%n [$123.45] \fRDefault formatting\fP + [-$123.45] + [$3,456.78] +.P +%11n [ $123.45] \fRRight align within an 11-character field\fP + [ -$123.45] + [ $3,456.78] +.P +%#5n [ $ 123.45] \fRAligned columns for values up to 99\|999\fP + [-$ 123.45] + [ $ 3,456.78] +.P +%=*#5n [ $***123.45] \fRSpecify a fill character\fP + [-$***123.45] + [ $*3,456.78] +.P +%=0#5n [ $000123.45] \fRFill characters do not use grouping\fP + [-$000123.45] \fReven if the fill character is a digit\fP + [ $03,456.78] +.P +%^#5n [ $ 123.45] \fRDisable the grouping separator\fP + [-$ 123.45] + [ $ 3456.78] +.P +%^#5.0n [ $ 123] \fRRound off to whole units\fP + [-$ 123] + [ $ 3457] +.P +%^#5.4n [ $ 123.4500] \fRIncrease the precision\fP + [-$ 123.4500] + [ $ 3456.7810] +.P +%(#5n [ $ 123.45 ] \fRUse an alternative pos/neg style\fP + [($ 123.45)] + [ $ 3,456.78 ] +.P +%!(#5n [ 123.45 ] \fRDisable the currency symbol\fP + [( 123.45)] + [ 3,456.78 ] +.P +%-14#5.4n [ $ 123.4500 ] \fRLeft-justify the output\fP + [-$ 123.4500 ] + [ $ 3,456.7810 ] +.P +%14#5.4n [ $ 123.4500] \fRCorresponding right-justified output\fP + [ -$ 123.4500] + [ $ 3,456.7810] +.fi \fR +.P +.RE +.P +See also the EXAMPLES section in +\fIfprintf\fR(). +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +Lowercase conversion characters are reserved for future standards use +and uppercase for implementation-defined use. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strftime.3p b/man-pages-posix-2013-a/man3p/strftime.3p new file mode 100644 index 0000000..c74625c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strftime.3p @@ -0,0 +1,996 @@ +'\" et +.TH STRFTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strftime, +strftime_l +\(em convert date and time to a string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strftime(char *restrict \fIs\fP, size_t \fImaxsize\fP, + const char *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP); +size_t strftime_l(char *restrict \fIs\fP, size_t \fImaxsize\fP, + const char *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIstrftime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrftime\fR() +function shall place bytes into the array pointed to by +.IR s +as controlled by the string pointed to by +.IR format . +The format is a character string, beginning and ending in its initial +shift state, if any. The format string consists of zero or more conversion +specifications and ordinary characters. +.P +Each conversion specification is introduced by the +.BR '%' +character after which the following appear in sequence: +.IP " *" 4 +An optional flag: +.RS 4 +.IP "\fR0\fR" 6 +The zero character (\c +.BR '0' ), +which specifies that the character used as the padding character is +.BR '0' , +.IP "\fR+\fR" 6 +The + +character (\c +.BR '+' ), +which specifies that the character used as the padding character is +.BR '0' , +and that if and only if the field being produced consumes more than four +bytes to represent a year (for +.BR %F , +.BR %G , +or +.BR %Y ) +or more than two bytes to represent the year divided by 100 (for +.BR %C ) +then a leading + +character shall be included if the year being processed is greater than +or equal to zero or a leading minus-sign character (\c +.BR '\(mi' ) +shall be included if the year is less than zero. +.P +The default padding character is unspecified. +.RE +.IP " *" 4 +An optional minimum field width. If the converted value, including +any leading +.BR '+' +or +.BR '\(mi' +sign, has fewer bytes than the minimum field width and the padding +character is not the NUL character, the output shall be padded on the left +(after any leading +.BR '+' +or +.BR '\(mi' +sign) with the padding character. +.IP " *" 4 +An optional +.BR E +or +.BR O +modifier. +.IP " *" 4 +A terminating conversion specifier character that indicates the type of +conversion to be applied. +.P +The results are unspecified if more than one flag character is specified, +a flag character is specified without a minimum field width; a minimum +field width is specified without a flag character; a modifier is specified +with a flag or with a minimum field width; or if a minimum field width +is specified for any conversion specifier other than +.BR C , +.BR F , +.BR G , +or +.BR Y . +.P +All ordinary characters (including the terminating NUL character) +are copied unchanged into the array. If copying takes place between +objects that overlap, the behavior is undefined. No more than maxsize +bytes are placed into the array. Each conversion specifier is replaced by +appropriate characters as described in the following list. The appropriate +characters are determined using the +.IR LC_TIME +category of the current locale and by the values of zero or more members +of the broken-down time structure pointed to by +.IR timeptr , +as specified in brackets in the description. If any of the specified +values are outside the normal range, the characters stored are +unspecified. +.P +The +\fIstrftime_l\fR() +function shall be equivalent to the +\fIstrftime\fR() +function, except that the locale data used is from the +locale represented by +.IR locale . +.P +Local timezone information is used as though +\fIstrftime\fR() +called +\fItzset\fR(). +.P +The following conversion specifiers shall be supported: +.IP "\fRa\fR" 8 +Replaced by the locale's abbreviated weekday name. [\c +.IR tm_wday ] +.IP "\fRA\fR" 8 +Replaced by the locale's full weekday name. [\c +.IR tm_wday ] +.IP "\fRb\fR" 8 +Replaced by the locale's abbreviated month name. [\c +.IR tm_mon ] +.IP "\fRB\fR" 8 +Replaced by the locale's full month name. [\c +.IR tm_mon ] +.IP "\fRc\fR" 8 +Replaced by the locale's appropriate date and time representation. +(See the Base Definitions volume of POSIX.1\(hy2008, +.IR .) +.IP "\fRC\fR" 8 +Replaced by the year divided by 100 and truncated to an integer, +as a decimal number. [\c +.IR tm_year ] +.RS 8 +.P +If a minimum field width is not specified, the number of characters +placed into the array pointed to by +.IR s +will be the number of digits in the year divided by 100 or two, whichever +is greater. +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits in the year divided by 100 or the minimum +field width, whichever is greater. +.RE +.IP "\fRd\fR" 8 +Replaced by the day of the month as a decimal number [01,31]. [\c +.IR tm_mday ] +.IP "\fRD\fR" 8 +Equivalent to +.BR %m /\c +.BR %d /\c +.BR %y . +[\c +.IR tm_mon , +.IR tm_mday , +.IR tm_year ] +.IP "\fRe\fR" 8 +Replaced by the day of the month as a decimal number [1,31]; +a single digit is preceded by a space. [\c +.IR tm_mday ] +.IP "\fRF\fR" 8 +Equivalent to %\*!+4\*?Y-%m-%d if no flag and no minimum field width +are specified. [\c +.IR tm_year , +.IR tm_mon , +.IR tm_mday ] +.RS 8 +.P +If a minimum field width of +.IR x +is specified, the year shall be output as if by the +.BR Y +specifier (described below) with whatever flag was given and a minimum +field width of +.IR x \(mi6. +If +.IR x +is less than 6, the behavior shall be as if +.IR x +equalled 6. +.P +If the minimum field width is specified to be 10, and the year is +four digits long, then the output string produced will match the +ISO\ 8601:\|2004 standard subclause 4.1.2.2 complete representation, extended format date +representation of a specific day. If a + flag is specified, a minimum +field width of +.IR x +is specified, and +.IR x \(mi7 +bytes are sufficient to hold the digits of the year (not including any +needed sign character), then the output will match the ISO\ 8601:\|2004 standard subclause +4.1.2.4 complete representation, expanded format date representation of +a specific day. +.RE +.IP "\fRg\fR" 8 +Replaced by the last 2 digits of the week-based year (see below) +as a decimal number [00,99]. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRG\fR" 8 +Replaced by the week-based year (see below) as a decimal number +(for example, 1977). [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.RS 8 +.P +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits and leading sign characters (if any) in +the year, or the minimum field width, whichever is greater. +.RE +.IP "\fRh\fR" 8 +Equivalent to +.BR %b . +[\c +.IR tm_mon ] +.IP "\fRH\fR" 8 +Replaced by the hour (24-hour clock) as a decimal number [00,23]. [\c +.IR tm_hour ] +.IP "\fRI\fR" 8 +Replaced by the hour (12-hour clock) as a decimal number [01,12]. [\c +.IR tm_hour ] +.IP "\fRj\fR" 8 +Replaced by the day of the year as a decimal number [001,366]. [\c +.IR tm_yday ] +.IP "\fRm\fR" 8 +Replaced by the month as a decimal number [01,12]. [\c +.IR tm_mon ] +.IP "\fRM\fR" 8 +Replaced by the minute as a decimal number [00,59]. [\c +.IR tm_min ] +.IP "\fRn\fR" 8 +Replaced by a +. +.IP "\fRp\fR" 8 +Replaced by the locale's equivalent of either a.m. or p.m. [\c +.IR tm_hour ] +.IP "\fRr\fR" 8 +Replaced by the time in a.m. and p.m. notation; +in the POSIX locale this shall be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +[\c +.IR tm_hour , +.IR tm_min , +.IR tm_sec ] +.IP "\fRR\fR" 8 +Replaced by the time in 24-hour notation (\c +.BR %H :\c +.BR %M ). +[\c +.IR tm_hour , +.IR tm_min ] +.IP "\fRS\fR" 8 +Replaced by the second as a decimal number [00,60]. [\c +.IR tm_sec ] +.IP "\fRt\fR" 8 +Replaced by a +. +.IP "\fRT\fR" 8 +Replaced by the time (\c +.BR %H :\c +.BR %M :\c +.BR %S ). +[\c +.IR tm_hour , +.IR tm_min , +.IR tm_sec ] +.IP "\fRu\fR" 8 +Replaced by the weekday as a decimal number [1,7], with 1 representing +Monday. [\c +.IR tm_wday ] +.IP "\fRU\fR" 8 +Replaced by the week number of the year as a decimal number [00,53]. +The first Sunday of January is the first day of week 1; days in the +new year before this are in week 0. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRV\fR" 8 +Replaced by the week number of the year (Monday as the first day of the +week) as a decimal number [01,53]. If the week containing 1 January +has four or more days in the new year, then it is considered week 1. +Otherwise, it is the last week of the previous year, and the next week +is week 1. Both January 4th and the first Thursday of January are +always in week 1. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRw\fR" 8 +Replaced by the weekday as a decimal number [0,6], with 0 representing +Sunday. [\c +.IR tm_wday ] +.IP "\fRW\fR" 8 +Replaced by the week number of the year as a decimal number [00,53]. +The first Monday of January is the first day of week 1; days in the new +year before this are in week 0. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRx\fR" 8 +Replaced by the locale's appropriate date representation. (See +the Base Definitions volume of POSIX.1\(hy2008, +.IR .) +.IP "\fRX\fR" 8 +Replaced by the locale's appropriate time representation. (See +the Base Definitions volume of POSIX.1\(hy2008, +.IR .) +.IP "\fRy\fR" 8 +Replaced by the last two digits of the year as a decimal number +[00,99]. [\c +.IR tm_year ] +.IP "\fRY\fR" 8 +Replaced by the year as a decimal number (for example, 1997). [\c +.IR tm_year ] +.RS 8 +.P +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits and leading sign characters (if any) in +the year, or the minimum field width, whichever is greater. +.RE +.IP "\fRz\fR" 8 +Replaced by the offset from UTC in the ISO\ 8601:\|2004 standard format (\c +.BR +hhmm +or +.BR \(mihhmm ), +or by no characters if no timezone is determinable. For example, +.BR \(dq\(mi0430\(dq +means 4 hours 30 minutes behind UTC (west of Greenwich). +If +.IR tm_isdst +is zero, the standard time offset is used. If +.IR tm_isdst +is greater than zero, the daylight savings time offset is used. If +.IR tm_isdst +is negative, no characters are returned. +[\c +.IR tm_isdst ] +.IP "\fRZ\fR" 8 +Replaced by the timezone name or abbreviation, or by no bytes if no +timezone information exists. [\c +.IR tm_isdst ] +.IP "\fR%\fR" 8 +Replaced by +.BR % . +.P +If a conversion specification does not correspond to any of the above, +the behavior is undefined. +.P +If a +.BR "struct tm" +broken-down time structure is created by +\fIlocaltime\fR() +or +\fIlocaltime_r\fR(), +or modified by +\fImktime\fR(), +and the value of +.IR TZ +is subsequently modified, the results of the +.BR %Z +and +.BR %z +\fIstrftime\fR() +conversion specifiers are undefined, when +\fIstrftime\fR() +is called with such a broken-down time structure. +.P +If a +.BR "struct tm" +broken-down time structure is created or modified by +\fIgmtime\fR() +or +\fIgmtime_r\fR(), +it is unspecified whether the result of the +.BR %Z +and +.BR %z +conversion specifiers shall refer to UTC or the current local timezone, +when +\fIstrftime\fR() +is called with such a broken-down time structure. +.SS "Modified Conversion Specifiers" +.P +Some conversion specifiers can be modified by the +.BR E +or +.BR O +modifier characters to indicate that an alternative format or +specification should be used rather than the one normally used by the +unmodified conversion specifier. If the alternative format or +specification does not exist for the current locale (see ERA in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME"), +the behavior shall be as if the unmodified conversion +specification were used. +.IP "\fR%Ec\fR" 8 +Replaced by the locale's alternative appropriate date and time +representation. +.IP "\fR%EC\fR" 8 +Replaced by the name of the base year (period) in the locale's +alternative representation. +.IP "\fR%Ex\fR" 8 +Replaced by the locale's alternative date representation. +.IP "\fR%EX\fR" 8 +Replaced by the locale's alternative time representation. +.IP "\fR%Ey\fR" 8 +Replaced by the offset from +.BR %EC +(year only) in the locale's alternative representation. +.IP "\fR%EY\fR" 8 +Replaced by the full alternative year representation. +.IP "\fR%Od\fR" 8 +Replaced by the day of the month, using the locale's alternative +numeric symbols, filled as needed with leading zeros if there is any +alternative symbol for zero; otherwise, with leading + +characters. +.IP "\fR%Oe\fR" 8 +Replaced by the day of the month, using the locale's alternative +numeric symbols, filled as needed with leading + +characters. +.IP "\fR%OH\fR" 8 +Replaced by the hour (24-hour clock) using the locale's alternative +numeric symbols. +.IP "\fR%OI\fR" 8 +Replaced by the hour (12-hour clock) using the locale's alternative +numeric symbols. +.IP "\fR%Om\fR" 8 +Replaced by the month using the locale's alternative numeric symbols. +.IP "\fR%OM\fR" 8 +Replaced by the minutes using the locale's alternative numeric symbols. +.IP "\fR%OS\fR" 8 +Replaced by the seconds using the locale's alternative numeric symbols. +.IP "\fR%Ou\fR" 8 +Replaced by the weekday as a number in the locale's alternative +representation (Monday=1). +.IP "\fR%OU\fR" 8 +Replaced by the week number of the year (Sunday as the first day of the +week, rules corresponding to +.BR %U ) +using the locale's alternative numeric symbols. +.IP "\fR%OV\fR" 8 +Replaced by the week number of the year (Monday as the first day of the +week, rules corresponding to +.BR %V ) +using the locale's alternative numeric symbols. +.IP "\fR%Ow\fR" 8 +Replaced by the number of the weekday (Sunday=0) using the locale's +alternative numeric symbols. +.IP "\fR%OW\fR" 8 +Replaced by the week number of the year (Monday as the first day of the +week) using the locale's alternative numeric symbols. +.IP "\fR%Oy\fR" 8 +Replaced by the year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.P +.BR %g , +.BR %G , +and +.BR %V +give values according to the ISO\ 8601:\|2004 standard week-based year. In this system, +weeks begin on a Monday and week 1 of the year is the week that +includes January 4th, which is also the week that includes the first +Thursday of the year, and is also the first week that contains at least +four days in the year. If the first Monday of January is the 2nd, 3rd, +or 4th, the preceding days are part of the last week of the preceding +year; thus, for Saturday 2nd January 1999, +.BR %G +is replaced by 1998 and +.BR %V +is replaced by 53. If December 29th, 30th, or 31st is a Monday, it and +any following days are part of week 1 of the following year. Thus, for +Tuesday 30th December 1997, +.BR %G +is replaced by 1998 and +.BR %V +is replaced by 01. +.P +If a conversion specifier is not one of the above, the behavior is +undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrftime_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +If the total number of resulting bytes including the terminating null +byte is not more than +.IR maxsize , +these functions shall return the number of bytes placed into the array +pointed to by +.IR s , +not including the terminating NUL character. Otherwise, 0 shall be returned +and the contents of the array are unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting a Localized Date String" +.P +The following example first sets the locale to the user's default. The +locale information will be used in the +\fInl_langinfo\fR() +and +\fIstrftime\fR() +functions. The +\fInl_langinfo\fR() +function returns the localized date string which specifies how the date +is laid out. The +\fIstrftime\fR() +function takes this information and, using the +.BR tm +structure for values, places the date and time information into +.IR datestring . +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +struct tm *tm; +char datestring[256]; +\&... +setlocale (LC_ALL, ""); +\&... +strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The range of values for +.BR %S +is [00,60] rather than [00,59] to allow for the occasional leap +second. +.P +Some of the conversion specifications are duplicates of others. They +are included for compatibility with +\fInl_cxtime\fR() +and +\fInl_ascxtime\fR(), +which were published in Issue 2. +.P +The +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y +format specifiers in +\fIstrftime\fR() +always print full values, but the +\fIstrptime\fR() +.BR %C , +.BR %F , +and +.BR %Y +format specifiers only scan two digits (assumed to be the first two +digits of a four-digit year) for +.BR %C +and four digits (assumed to be the entire (four-digit) year) for +.BR %F +and +.BR %Y . +This mimics the behavior of +\fIprintf\fR() +and +\fIscanf\fR(); +that is: +.sp +.RS 4 +.nf +\fB +printf("%2d", x = 1000); +.fi \fR +.P +.RE +.P +prints +.BR \(dq1000\(dq , +but: +.sp +.RS 4 +.nf +\fB +scanf(%2d", &x); +.fi \fR +.P +.RE +.P +when given +.BR \(dq1000\(dq +as input will only store 10 in +.IR x ). +Applications using extended ranges of years must be sure that the number +of digits specified for scanning years with +\fIstrptime\fR() +matches the number of digits that will actually be present in the input +stream. Historic implementations of the +.BR %Y +conversion specification (with no flags and no minimum field width) +produced different output formats. Some always produced at least four +digits (with 0 fill for years from 0 through 999) while others only +produced the number of digits present in the year (with no fill and no +padding). These two forms can be produced with the +.BR '0' +flag and a minimum field width options using the conversions +specifications +.BR %04Y +and +.BR %01Y , +respectively. +.P +In the past, the C and POSIX standards specified that +.BR %F +produced an ISO\ 8601:\|2004 standard date format, but didn't specify which one. For +years in the range [0001,9999], POSIX.1\(hy2008 requires that the output +produced match the ISO\ 8601:\|2004 standard complete representation extended format +(YYYY-MM-DD) and for years outside of this range produce output +that matches the ISO\ 8601:\|2004 standard expanded representation extended format +(<+/->YYYYY-MM-DD). To fully meet ISO\ 8601:\|2004 standard +requirements, the producer and consumer must agree on a date format that +has a specific number of bytes reserved to hold the characters used to +represent the years that is sufficiently large to hold all values that +will be shared. For example, the +.BR %+13F +conversion specification will produce output matching the format +.BR \(dq<+/->YYYYYY-MM-DD\(dq +(a leading +.BR '+' +or +.BR '\(mi' +sign; a six-digit, 0-filled year; a +.BR '\(mi' ; +a two-digit, leading 0-filled month; another +.BR '\(mi' ; +and the two-digit, leading 0-filled day within the month). +.P +Note that if the year being printed is greater than 9999, the resulting +string from the unadorned +.BR %F +conversion specifications will not conform to the ISO\ 8601:\|2004 standard extended format, +complete representation for a date and will instead be an extended format, +expanded representation (presumably without the required agreement +between the date's producer and consumer). +.P +In the C locale, the +.BR E +and +.BR O +modifiers are ignored and the replacement strings for the following +specifiers are: +.IP "\fR%a\fR" 8 +The first three characters of +.BR %A . +.IP "\fR%A\fR" 8 +One of Sunday, Monday, .\|.\|., Saturday. +.IP "\fR%b\fR" 8 +The first three characters of +.BR %B . +.IP "\fR%B\fR" 8 +One of January, February, .\|.\|., December. +.IP "\fR%c\fR" 8 +Equivalent to +.BR %a +.BR %b +.BR %e +.BR %T +.BR %Y . +.IP "\fR%p\fR" 8 +One of AM or PM. +.IP "\fR%r\fR" 8 +Equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fR%x\fR" 8 +Equivalent to +.BR %m /\c +.BR %d /\c +.BR %y . +.IP "\fR%X\fR" 8 +Equivalent to +.BR %T . +.IP "\fR%Z\fR" 8 +Implementation-defined. +.SH RATIONALE +The +.BR %Y +conversion specification to +\fIstrftime\fR() +was frequently assumed to be a four-digit year, but the ISO\ C standard does not +specify that +.BR %Y +is restricted to any subset of allowed values from the +.IR tm_year +field. Similarly, the +.BR %C +conversion specification was assumed to be a two-digit field and the +first part of the output from the +.BR %F +conversion specification was assumed to be a four-digit field. With +.IR tm_year +being a signed 32 or more-bit +.BR int +and with many current implementations supporting 64-bit +.BR time_t +types in one or more programming environments, these assumptions are +clearly wrong. +.P +POSIX.1\(hy2008 now allows the format specifications +.BR %0xC , +.BR %0xF , +.BR %0xG , +and +.BR %0xY +(where +.BR 'x' +is a string of decimal digits used to specify printing and scanning of a +string of +.IR x +decimal digits) with leading zero fill characters. Allowing applications +to set the field width enables them to agree on the number of digits +to be printed and scanned in the ISO\ 8601:\|2004 standard expanded representation of a +year (for +.BR %F , +.BR %G , +and +.BR %Y ) +or all but the last two digits of the year (for +.BR %C ). +This is based on a feature in some versions of GNU +.BR libc 's +\fIstrftime\fR(). +The GNU version allows specifying space, zero, or no-fill characters in +\fIstrftime\fR() +format strings, but does not allow any flags to be specified in +\fIstrptime\fR() +format strings. These implementations also allow these flags to be +specified for any numeric field. POSIX.1\(hy2008 only requires the zero fill flag +(\c +.BR '0' ) +and only requires that it be recognized when processing +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y +specifications when a minimum field width is also specified. The +.BR '0' +flag is the only flag needed to produce and scan the ISO\ 8601:\|2004 standard +year fields using the extended format forms. POSIX.1\(hy2008 also allows +applications to specify the same flag and field width specifiers to be +used in both +\fIstrftime\fR() +and +\fIstrptime\fR() +format strings for symmetry. Systems may provide other flag characters +and may accept flags in conjunction with conversion specifiers other than +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y ; +but portable applications cannot depend on such extensions. +.P +POSIX.1\(hy2008 now also allows the format specifications +.BR %+xC , +.BR %+xF , +.BR %+xG , +and +.BR %+xY +(where +.BR 'x' +is a string of decimal digits used to specify printing and scanning of +a string of +.BR 'x' +decimal digits) with leading zero fill characters and a leading +.BR '+' +sign character if the year being converted is more than four digits +or a minimum field width is specified that allows room for more than +four digits for the year. This allows date providers and consumers to +agree on a specific number of digits to represent a year as required by +the ISO\ 8601:\|2004 standard expanded representation formats. The expanded representation +formats all require the year to begin with a leading +.BR '+' +or +.BR '\(mi' +sign. +(All of these specifiers can also provide a leading +.BR '\(mi' +sign for negative years. Since negative years and the year 0 don't fit +well with the Gregorian or Julian calendars, the normal ranges of dates +start with year 1. The ISO\ C standard allows +.IR tm_year +to assume values corresponding to years before year 1, but the use of +such years provided unspecified results.) +.P +Some earlier version of this standard specified that applications wanting +to use +\fIstrptime\fR() +to scan dates and times printed by +\fIstrftime\fR() +should provide non-digit characters between fields to separate years +from months and days. It also supported +.BR %F +to print and scan the ISO\ 8601:\|2004 standard extended format, complete representation date +for years 1 through 9999 (i.e., YYYY-MM-DD). However, many applications +were written to print (using +\fIstrftime\fR()) +and scan (using +\fIstrptime\fR()) +dates written using the basic format complete representation +(four-digit years) and truncated representation (two-digit years) +specified by the ISO\ 8601:\|2004 standard representation of dates and times which do not +have any separation characters between fields. The ISO\ 8601:\|2004 standard also specifies +basic format expanded representation where the creator and consumer of +these fields agree beforehand to represent years as leading zero-filled +strings of an agreed length of more than four digits to represent a year +(again with no separation characters when year, month, and day are all +displayed). Applications producing and consuming expanded representations +are encouraged to use the +.BR '+' +flag and an appropriate maximum field width to scan the year including +the leading sign. Note that even without the +.BR '+' +flag, years less than zero may be represented with a leading +minus-sign for +.BR %F , +.BR %G , and +.BR %Y +conversion specifications. Using negative years results in unspecified +behavior. +.P +If a format specification +.BR %+xF +with the field width +.IR x +greater than 11 is specified and the width is large enough to display +the full year, the output string produced will match the ISO\ 8601:\|2004 standard +subclause 4.1.2.4 expanded representation, extended format date +representation for a specific day. (For years in the range [1,99\|999], +.BR %+12F +is sufficient for an agreed five-digit year with a leading sign using +the ISO\ 8601:\|2004 standard expanded representation, extended format for a specific day +.BR \(dq<+/->YYYYY-MM-DD\(dq .) +Note also that years less than 0 may produce a leading minus-sign (\c +.BR '\(mi' ) +when using +.BR %Y +or +.BR %C +whether or not the +.BR '0' +or +.BR '+' +flags are used. +.P +The difference between the +.BR '0' +flag and the +.BR '+' +flag is whether the leading +.BR '+' +character will be provided for years >9999 as required for the ISO\ 8601:\|2004 standard +extended representation format containing a year. For example: +.TS +box center tab(!); +cB | cB | cB | cB +cB | cB | cB | cB +l | lf5 | l | l. +!!\fIstrftime\fP(\^)!\fIstrptime\fP(\^) +Year!Conversion Specification!Output!Scan Back +_ +1970!%Y!1970!1970 +_ +1970!%+4Y!1970!1970 +_ +27!%Y!27 or 0027!27 +_ +270!%Y!270 or 0270!270 +_ +270!%+4Y!0270!270 +_ +17!%C%y!0017!17 +_ +270!%C%y!0270!270 +_ +12345!%Y!12345!1234* +_ +12345!%+4Y!+12345!123* +_ +12345!%05Y!12345!12345 +_ +270!%+5Y \fRor\fP %+3C%y!+0270!270 +_ +12345!%+5Y \fRor\fP %+3C%y!+12345!1234* +_ +12345!%06Y \fRor\fP %04C%y!012345!12345 +_ +12345!%+6Y \fRor\fP %+4C%y!+12345!12345 +_ +123456!%08Y \fRor\fP %06C%y!00123456!123456 +_ +123456!%+8Y \fRor\fP %+6C%y!+0123456!123456 +.TE +.P +In the cases above marked with a * in the +\fIstrptime\fR() +scan back field, the implied or specified number of characters scanned by +\fIstrptime\fR() +was less than the number of characters output by +\fIstrftime\fR() +using the same format; so the remaining digits of the year were dropped +when the output date produced by +\fIstrftime\fR() +was scanned back in by +\fIstrptime\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgetdate\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strlen.3p b/man-pages-posix-2013-a/man3p/strlen.3p new file mode 100644 index 0000000..ca0ce28 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strlen.3p @@ -0,0 +1,125 @@ +'\" et +.TH STRLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strlen, strnlen +\(em get length of fixed size string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strlen(const char *\fIs\fP); +size_t strnlen(const char *\fIs\fP, size_t \fImaxlen\fP); +.fi +.SH DESCRIPTION +For +\fIstrlen\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrlen\fR() +function shall compute the number of bytes in the string to which +.IR s +points, not including the terminating NUL character. +.P +The +\fIstrnlen\fR() +function shall compute the smaller of the number of bytes in the array +to which +.IR s +points, not including the terminating NUL character, or the value of the +.IR maxlen +argument. The +\fIstrnlen\fR() +function shall never examine more than +.IR maxlen +bytes of the array pointed to by +.IR s . +.SH "RETURN VALUE" +The +\fIstrlen\fR() +function shall return the length of +.IR s ; +no return value shall be reserved to indicate an error. +.P +The +\fIstrnlen\fR() +function shall return an integer containing the smaller of either the +length of the string pointed to by +.IR s +or +.IR maxlen . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting String Lengths" +.P +The following example sets the maximum length of +.IR key +and +.IR data +by using +\fIstrlen\fR() +to get the lengths of those strings. +.sp +.RS 4 +.nf +\fB +#include +\&... +struct element { + char *key; + char *data; +}; +\&... +char *key, *data; +int len; +.P +*keylength = *datalength = 0; +\&... +if ((len = strlen(key)) > *keylength) + *keylength = len; +if ((len = strlen(data)) > *datalength) + *datalength = len; +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcslen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strncasecmp.3p b/man-pages-posix-2013-a/man3p/strncasecmp.3p new file mode 100644 index 0000000..f21e972 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strncasecmp.3p @@ -0,0 +1,41 @@ +'\" et +.TH STRNCASECMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strncasecmp, +strncasecmp_l +\(em case-insensitive string comparisons +.SH SYNOPSIS +.LP +.nf +#include +.P +int strncasecmp(const char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP); +int strncasecmp_l(const char *\fIs1\fP, const char *\fIs2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrcasecmp\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strncat.3p b/man-pages-posix-2013-a/man3p/strncat.3p new file mode 100644 index 0000000..59b6b93 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strncat.3p @@ -0,0 +1,78 @@ +'\" et +.TH STRNCAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strncat +\(em concatenate a string with part of another +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strncat(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrncat\fR() +function shall append not more than +.IR n +bytes (a NUL character and bytes that follow it are not appended) +from the array pointed to by +.IR s2 +to the end of the string pointed to by +.IR s1 . +The initial byte of +.IR s2 +overwrites the NUL character at the end of +.IR s1 . +A terminating NUL character is always appended to the result. If copying +takes place between objects that overlap, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIstrncat\fR() +function shall return +.IR s1 ; +no return value shall be reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strncmp.3p b/man-pages-posix-2013-a/man3p/strncmp.3p new file mode 100644 index 0000000..a354df2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strncmp.3p @@ -0,0 +1,82 @@ +'\" et +.TH STRNCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strncmp +\(em compare part of two strings +.SH SYNOPSIS +.LP +.nf +#include +.P +int strncmp(const char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrncmp\fR() +function shall compare not more than +.IR n +bytes (bytes that follow a NUL character are not compared) from the array +pointed to by +.IR s1 +to the array pointed to by +.IR s2 . +.P +The sign of a non-zero return value is determined by the sign of the +difference between the values of the first pair of bytes (both +interpreted as type +.BR "unsigned char" ) +that differ in the strings being compared. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrncmp\fR() +shall return an integer greater than, equal to, or less than 0, if the +possibly null-terminated array pointed to by +.IR s1 +is greater than, equal to, or less than the possibly null-terminated +array pointed to by +.IR s2 +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strncpy.3p b/man-pages-posix-2013-a/man3p/strncpy.3p new file mode 100644 index 0000000..014b76e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strncpy.3p @@ -0,0 +1,116 @@ +'\" et +.TH STRNCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stpncpy, strncpy +\(em copy fixed length string, returning a pointer to the array end +.SH SYNOPSIS +.LP +.nf +#include +.P +char *stpncpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIn\fP); +char *strncpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +For +\fIstrncpy\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstpncpy\fR() +and +\fIstrncpy\fR() +functions shall copy not more than +.IR n +bytes (bytes that follow a NUL character are not copied) from the array +pointed to by +.IR s2 +to the array pointed to by +.IR s1 . +.P +If the array pointed to by +.IR s2 +is a string that is shorter than +.IR n +bytes, NUL characters shall be appended to the copy in the array +pointed to by +.IR s1 , +until +.IR n +bytes in all are written. +.P +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +If a NUL character is written to the destination, the +\fIstpncpy\fR() +function shall return the address of the first such NUL character. +Otherwise, it shall return +.IR &s1 [ n ]. +.P +The +\fIstrncpy\fR() +function shall return +.IR s1 . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications must provide the space in +.IR s1 +for the +.IR n +bytes to be transferred, as well as ensure that the +.IR s2 +and +.IR s1 +arrays do not overlap. +.P +Character movement is performed differently in different +implementations. Thus, overlapping moves may yield surprises. +.P +If there is no NUL character byte in the first +.IR n +bytes of the array pointed to by +.IR s2 , +the result is not null-terminated. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcpy\fR\^(\|)", +.IR "\fIwcsncpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strndup.3p b/man-pages-posix-2013-a/man3p/strndup.3p new file mode 100644 index 0000000..395a927 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strndup.3p @@ -0,0 +1,38 @@ +'\" et +.TH STRNDUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strndup +\(em duplicate a specific number of bytes from a string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strndup(const char *\fIs\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrdup\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strnlen.3p b/man-pages-posix-2013-a/man3p/strnlen.3p new file mode 100644 index 0000000..1d3f09a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strnlen.3p @@ -0,0 +1,38 @@ +'\" et +.TH STRNLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strnlen +\(em get length of fixed size string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strnlen(const char *\fIs\fP, size_t \fImaxlen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrlen\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strpbrk.3p b/man-pages-posix-2013-a/man3p/strpbrk.3p new file mode 100644 index 0000000..8b6775a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strpbrk.3p @@ -0,0 +1,71 @@ +'\" et +.TH STRPBRK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strpbrk +\(em scan a string for a byte +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strpbrk(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrpbrk\fR() +function shall locate the first occurrence in the string pointed to by +.IR s1 +of any byte from the string pointed to by +.IR s2 . +.SH "RETURN VALUE" +Upon successful completion, +\fIstrpbrk\fR() +shall return a pointer to the byte or a null pointer if no byte from +.IR s2 +occurs in +.IR s1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrchr\fR\^(\|)", +.IR "\fIstrrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strptime.3p b/man-pages-posix-2013-a/man3p/strptime.3p new file mode 100644 index 0000000..cfcf6cb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strptime.3p @@ -0,0 +1,442 @@ +'\" et +.TH STRPTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strptime +\(em date and time conversion +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strptime(const char *restrict \fIbuf\fP, const char *restrict \fIformat\fP, + struct tm *restrict \fItm\fP); +.fi +.SH DESCRIPTION +The +\fIstrptime\fR() +function shall convert the character string pointed to by +.IR buf +to values which are stored in the +.BR tm +structure pointed to by +.IR tm , +using the format specified by +.IR format . +.P +The format is composed of zero or more directives. Each directive is +composed of one of the following: one or more white-space characters +(as specified by +\fIisspace\fR()); +an ordinary character (neither +.BR '%' +nor a white-space character); or a conversion specification. +.P +Each conversion specification is introduced by the +.BR '%' +character after which the following appear in sequence: +.IP " *" 4 +An optional flag, the zero character (\c +.BR '0' ) +or the + +character (\c +.BR '+' ), +which is ignored. +.IP " *" 4 +An optional field width. If a field width is specified, it shall be +interpreted as a string of decimal digits that will determine the maximum +number of bytes converted for the conversion rather than the number of +bytes specified below in the description of the conversion specifiers. +.IP " *" 4 +An optional +.BR E +or +.BR O +modifier. +.IP " *" 4 +A terminating conversion specifier character that indicates the type of +conversion to be applied. +.P +The conversions are determined using the +.IR LC_TIME +category of the current locale. The application shall ensure that +there is white-space or other non-alphanumeric characters between any +two conversion specifications unless all of the adjacent conversion +specifications convert a known, fixed number of characters. In the +following list, the maximum number of characters scanned (excluding the +one matching the next directive) is as follows: +.IP " *" 4 +If a maximum field width is specified, then that number +.IP " *" 4 +Otherwise, the pattern +.BR \(dq{x}\(dq +indicates that the maximum is +.IR x +.IP " *" 4 +Otherwise, the pattern +.BR \(dq[x,y]\(dq +indicates that the value shall fall within the range given (both bounds +being inclusive), and the maximum number of characters scanned shall be +the maximum required to represent any value in the range without leading +zeros and without a leading + +.P +The following conversion specifiers are supported. +.P +The results are unspecified if a modifier is specified with a flag or +with a minimum field width, or if a field width is specified for any +conversion specifier other than +.BR C , +.BR F , +or +.BR Y . +.IP "\fRa\fR" 8 +The day of the week, using the locale's weekday names; either the +abbreviated or full name may be specified. +.IP "\fRA\fR" 8 +Equivalent to +.BR %a . +.IP "\fRb\fR" 8 +The month, using the locale's month names; either the abbreviated or +full name may be specified. +.IP "\fRB\fR" 8 +Equivalent to +.BR %b . +.IP "\fRc\fR" 8 +Replaced by the locale's appropriate date and time representation. +.IP "\fRC\fR" 8 +All but the last two digits of the year {2}; leading zeros shall be +permitted but shall not be required. A leading +.BR '+' +or +.BR '\(mi' +character shall be permitted before any leading zeros but shall not +be required. +.IP "\fRd\fR" 8 +The day of the month [01,31]; leading zeros shall be permitted but shall +not be required. +.IP "\fRD\fR" 8 +The date as +.BR %m /\c +.BR %d /\c +.BR %y . +.IP "\fRe\fR" 8 +Equivalent to +.BR %d . +.IP "\fRh\fR" 8 +Equivalent to +.BR %b . +.IP "\fRH\fR" 8 +The hour (24-hour clock) [00,23]; leading zeros shall be permitted but +shall not be required. +.IP "\fRI\fR" 8 +The hour (12-hour clock) [01,12]; leading zeros shall be permitted but +shall not be required. +.IP "\fRj\fR" 8 +The day number of the year [001,366]; leading zeros shall be permitted +but shall not be required. +.IP "\fRm\fR" 8 +The month number [01,12]; leading zeros shall be permitted but shall +not be required. +.IP "\fRM\fR" 8 +The minute [00,59]; leading zeros shall be permitted but shall not +be required. +.IP "\fRn\fR" 8 +Any white space. +.IP "\fRp\fR" 8 +The locale's equivalent of a.m. or p.m. +.IP "\fRr\fR" 8 +12-hour clock time using the AM/PM notation if +.BR t_fmt_ampm +is not an empty string in the +.IR LC_TIME +portion of the current locale; in the POSIX locale, this shall +be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fRR\fR" 8 +The time as +.BR %H :\c +.BR %M . +.IP "\fRS\fR" 8 +The seconds [00,60]; leading zeros shall be permitted but shall +not be required. +.IP "\fRt\fR" 8 +Any white space. +.IP "\fRT\fR" 8 +The time as +.BR %H :\c +.BR %M :\c +.BR %S . +.IP "\fRU\fR" 8 +The week number of the year (Sunday as the first day of the week) as a +decimal number [00,53]; leading zeros shall be permitted but shall +not be required. +.IP "\fRw\fR" 8 +The weekday as a decimal number [0,6], with 0 representing Sunday. +.IP "\fRW\fR" 8 +The week number of the year (Monday as the first day of the week) as a +decimal number [00,53]; leading zeros shall be permitted but shall +not be required. +.IP "\fRx\fR" 8 +The date, using the locale's date format. +.IP "\fRX\fR" 8 +The time, using the locale's time format. +.IP "\fRy\fR" 8 +The last two digits of the year. When +.IR format +contains neither a +.BR C +conversion specifier nor a +.BR Y +conversion specifier, values in the range [69,99] shall refer to years +1969 to 1999 inclusive and values in the range [00,68] shall refer to +years 2000 to 2068 inclusive; leading zeros shall be permitted but shall +not be required. A leading +.BR '+' +or +.BR '\(mi' +character shall be permitted before any leading zeros but shall not +be required. +.RS 8 +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.RE +.IP "\fRY\fR" 8 +The full year {4}; leading zeros shall be permitted but shall +not be required. A leading +.BR '+' +or +.BR '\(mi' +character shall be permitted before any leading zeros but shall not +be required. +.IP "\fR%\fP" 8 +Replaced by +.BR % . +.SS "Modified Conversion Specifiers" +.P +Some conversion specifiers can be modified by the +.BR E +and +.BR O +modifier characters to indicate that an alternative format or +specification should be used rather than the one normally used by the +unmodified conversion specifier. If the alternative format or +specification does not exist in the current locale, the behavior shall +be as if the unmodified conversion specification were used. +.IP "\fR%Ec\fR" 8 +The locale's alternative appropriate date and time representation. +.IP "\fR%EC\fR" 8 +The name of the base year (period) in the locale's alternative +representation. +.IP "\fR%Ex\fR" 8 +The locale's alternative date representation. +.IP "\fR%EX\fR" 8 +The locale's alternative time representation. +.IP "\fR%Ey\fR" 8 +The offset from +.BR %EC +(year only) in the locale's alternative representation. +.IP "\fR%EY\fR" 8 +The full alternative year representation. +.IP "\fR%Od\fR" 8 +The day of the month using the locale's alternative numeric symbols; +leading zeros shall be permitted but shall not be required. +.IP "\fR%Oe\fR" 8 +Equivalent to +.BR %Od . +.IP "\fR%OH\fR" 8 +The hour (24-hour clock) using the locale's alternative numeric +symbols. +.IP "\fR%OI\fR" 8 +The hour (12-hour clock) using the locale's alternative numeric +symbols. +.IP "\fR%Om\fR" 8 +The month using the locale's alternative numeric symbols. +.IP "\fR%OM\fR" 8 +The minutes using the locale's alternative numeric symbols. +.IP "\fR%OS\fR" 8 +The seconds using the locale's alternative numeric symbols. +.IP "\fR%OU\fR" 8 +The week number of the year (Sunday as the first day of the week) using +the locale's alternative numeric symbols. +.IP "\fR%Ow\fR" 8 +The number of the weekday (Sunday=0) using the locale's alternative +numeric symbols. +.IP "\fR%OW\fR" 8 +The week number of the year (Monday as the first day of the week) using +the locale's alternative numeric symbols. +.IP "\fR%Oy\fR" 8 +The year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.P +A conversion specification composed of white-space characters is +executed by scanning input up to the first character that is not +white-space (which remains unscanned), or until no more characters can +be scanned. +.P +A conversion specification that is an ordinary character is executed by +scanning the next character from the buffer. If the character scanned +from the buffer differs from the one comprising the directive, the +directive fails, and the differing and subsequent characters remain +unscanned. +.P +A series of conversion specifications composed of +.BR %n , +.BR %t , +white-space characters, or any combination is executed by scanning up +to the first character that is not white space (which remains +unscanned), or until no more characters can be scanned. +.P +Any other conversion specification is executed by scanning characters +until a character matching the next directive is scanned, or until no +more characters can be scanned. These characters, except the one +matching the next directive, are then compared to the locale values +associated with the conversion specifier. If a match is found, values +for the appropriate +.BR tm +structure members are set to values corresponding to the locale +information. Case is ignored when matching items in +.IR buf +such as month or weekday names. If no match is found, +\fIstrptime\fR() +fails and no more characters are scanned. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrptime\fR() +shall return a pointer to the character following the last character +parsed. Otherwise, a null pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Convert a Data-Plus-Time String to Broken-Down Time and Then into Seconds" +.P +The following example demonstrates the use of +\fIstrptime\fR() +to convert a string into broken-down time. The broken-down time is then +converted into seconds since the Epoch using +\fImktime\fR(). +.sp +.RS 4 +.nf +\fB +#include +\&... +.P +struct tm tm; +time_t t; +.P +if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL) + /* Handle error */; +.P +printf("year: %d; month: %d; day: %d;\en", + tm.tm_year, tm.tm_mon, tm.tm_mday); +printf("hour: %d; minute: %d; second: %d\en", + tm.tm_hour, tm.tm_min, tm.tm_sec); +printf("week day: %d; year day: %d\en", tm.tm_wday, tm.tm_yday); +.P +tm.tm_isdst = \(mi1; /* Not set by strptime(); tells mktime() + to determine whether daylight saving time + is in effect */ +t = mktime(&tm); +if (t == \(mi1) + /* Handle error */; +printf("seconds since the Epoch: %ld\en", (long) t);" +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Several ``equivalent to'' formats and the special processing of +white-space characters are provided in order to ease the use of +identical +.IR format +strings for +\fIstrftime\fR() +and +\fIstrptime\fR(). +.P +It should be noted that dates constructed by the +\fIstrftime\fR() +function with the +.BR %Y +or +.BR %C%y +conversion specifiers may have values larger than 9\|999. If the +\fIstrptime\fR() +function is used to read such values using +.BR %C%y +or +.BR %Y , +the year values will be truncated to four digits. Applications should use +.BR %+ \c +.IR w \c +.BR %y +or +.BR %+ \c +.IR x \c +.BR Y +with +.IR w +and +.IR x +set large enough to contain the full value of any years that will be +printed or scanned. +.P +See also the APPLICATION USAGE section in +.IR "\fIstrftime\fR\^(\|)". +.P +It is unspecified whether multiple calls to +\fIstrptime\fR() +using the same +.BR tm +structure will update the current contents of the structure or +overwrite all contents of the structure. Conforming applications +should make a single call to +\fIstrptime\fR() +with a format and all data needed to completely specify the date and +time being converted. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIstrftime\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strrchr.3p b/man-pages-posix-2013-a/man3p/strrchr.3p new file mode 100644 index 0000000..4f46b23 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strrchr.3p @@ -0,0 +1,97 @@ +'\" et +.TH STRRCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strrchr +\(em string scanning operation +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strrchr(const char *\fIs\fP, int \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrrchr\fR() +function shall locate the last occurrence of +.IR c +(converted to a +.BR char ) +in the string pointed to by +.IR s . +The terminating NUL character is considered to be part of the string. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrrchr\fR() +shall return a pointer to the byte or a null pointer if +.IR c +does not occur in the string. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Finding the Base Name of a File" +.P +The following example uses +\fIstrrchr\fR() +to get a pointer to the base name of a file. The +\fIstrrchr\fR() +function searches backwards through the name of the file to find the +last +.BR '/' +character in +.IR name . +This pointer (plus one) will point to the base name of the file. +.sp +.RS 4 +.nf +\fB +#include +\&... +const char *name; +char *basename; +\&... +basename = strrchr(name, '/') + 1; +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strsignal.3p b/man-pages-posix-2013-a/man3p/strsignal.3p new file mode 100644 index 0000000..4896279 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strsignal.3p @@ -0,0 +1,104 @@ +'\" et +.TH STRSIGNAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strsignal +\(em get name of signal +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strsignal(int \fIsignum\fP); +.fi +.SH DESCRIPTION +The +\fIstrsignal\fR() +function shall map the signal number in +.IR signum +to an implementation-defined string and shall return a pointer to it. +It shall use the same set of messages as the +\fIpsignal\fR() +function. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIstrsignal\fR() +or +\fIsetlocale\fR(). +.P +The contents of the message strings returned by +\fIstrsignal\fR() +should be determined by the setting of the +.IR LC_MESSAGES +category in the current locale. +.P +The implementation shall behave as if no function defined in this +standard calls +\fIstrsignal\fR(). +.P +Since no return value is reserved to indicate an error, an application +wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrsignal\fR(), +then check +.IR errno . +.P +The +\fIstrsignal\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrsignal\fR() +shall return a pointer to a string. Otherwise, if +.IR signum +is not a valid signal number, the return value is unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If +.IR signum +is not a valid signal number, some implementations return NULL, while +for others the +\fIstrsignal\fR() +function returns a pointer to a string containing an unspecified +message denoting an unknown signal. POSIX.1\(hy2008 leaves this return +value unspecified. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strspn.3p b/man-pages-posix-2013-a/man3p/strspn.3p new file mode 100644 index 0000000..02f2561 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strspn.3p @@ -0,0 +1,69 @@ +'\" et +.TH STRSPN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strspn +\(em get length of a substring +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strspn(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrspn\fR() +function shall compute the length (in bytes) of the maximum initial +segment of the string pointed to by +.IR s1 +which consists entirely of bytes from the string pointed to by +.IR s2 . +.SH "RETURN VALUE" +The +\fIstrspn\fR() +function shall return the computed length; no return value is reserved +to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcspn\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strstr.3p b/man-pages-posix-2013-a/man3p/strstr.3p new file mode 100644 index 0000000..df547ea --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strstr.3p @@ -0,0 +1,74 @@ +'\" et +.TH STRSTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strstr +\(em find a substring +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strstr(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrstr\fR() +function shall locate the first occurrence in the string pointed to by +.IR s1 +of the sequence of bytes (excluding the terminating NUL character) in the +string pointed to by +.IR s2 . +.SH "RETURN VALUE" +Upon successful completion, +\fIstrstr\fR() +shall return a pointer to the located string or a null pointer if the +string is not found. +.P +If +.IR s2 +points to a string with zero length, the function shall return +.IR s1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strtod.3p b/man-pages-posix-2013-a/man3p/strtod.3p new file mode 100644 index 0000000..421c17c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strtod.3p @@ -0,0 +1,341 @@ +'\" et +.TH STRTOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strtod, +strtof, +strtold +\(em convert a string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +double strtod(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP); +float strtof(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP); +long double strtold(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the string pointed +to by +.IR nptr +to +.BR double , +.BR float , +and +.BR "long double" +representation, respectively. First, they decompose the input string +into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by +\fIisspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as a floating-point constant or +representing infinity or NaN +.IP " 3." 4 +A final string of one or more unrecognized characters, including the +terminating NUL character of the input string +.P +Then they shall attempt to convert the subject sequence to a +floating-point number, and return the result. +.P +The expected form of the subject sequence is an optional +.BR '+' +or +.BR '\(mi' +sign, then one of the following: +.IP " *" 4 +A non-empty sequence of decimal digits optionally containing a radix +character; then an optional exponent part consisting of the character +.BR 'e' +or the character +.BR 'E' , +optionally followed by a +.BR '+' +or +.BR '\(mi' +character, and then followed by one or more decimal digits +.IP " *" 4 +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character; then an optional binary exponent part +consisting of the character +.BR 'p' +or the character +.BR 'P' , +optionally followed by a +.BR '+' +or +.BR '\(mi' +character, and then followed by one or more decimal digits +.IP " *" 4 +One of INF or INFINITY, ignoring case +.IP " *" 4 +One of NAN or NAN(\fIn-char-sequence\s-3\dopt\u\s+3\fR), ignoring case in +the NAN part, where: +.RS 4 +.sp +.RS 4 +.nf +\fB +n-char-sequence: + digit + nondigit + n-char-sequence digit + n-char-sequence nondigit +.fi \fR +.P +.RE +.RE +.P +The subject sequence is defined as the longest initial subsequence of +the input string, starting with the first non-white-space character, +that is of the expected form. The subject sequence contains no +characters if the input string is not of the expected form. +.P +If the subject sequence has the expected form for a floating-point +number, the sequence of characters starting with the first digit or the +decimal-point character (whichever occurs first) shall be interpreted +as a floating constant of the C language, except that the radix +character shall be used in place of a period, and that if neither an +exponent part nor a radix character appears in a decimal floating-point +number, or if a binary exponent part does not appear in a hexadecimal +floating-point number, an exponent part of the appropriate type with +value zero is assumed to follow the last digit in the string. If the +subject sequence begins with a minus-sign, the sequence shall be +interpreted as negated. A character sequence INF or INFINITY shall be +interpreted as an infinity, if representable in the return type, else +as if it were a floating constant that is too large for the range of +the return type. A character sequence NAN or +NAN(\fIn-char-sequence\s-3\dopt\u\s+3\fR) shall be interpreted as a +quiet NaN, if supported in the return type, else as if it were a +subject sequence part that does not have the expected form; the meaning +of the \fIn\fR-char sequences is implementation-defined. A pointer to +the final string is stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +If the subject sequence has the hexadecimal form and FLT_RADIX is a +power of 2, the value resulting from the conversion is correctly +rounded. +.P +The radix character is defined in the current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +In other than the C +or POSIX +locales, other implementation-defined subject sequences may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +is stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0 is returned on error and is also a valid return on success, +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrtod\fR(), +\fIstrtof\fR(), +or +\fIstrtold\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value. If no conversion could be performed, 0 shall be returned, and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +\(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL shall be returned +(according to the sign of the value), and +.IR errno +shall be set to +.BR [ERANGE] . +.P +If the correct value would cause an underflow, a value whose magnitude +is no greater than the smallest normalized positive number in the +return type shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR ERANGE +The value to be returned would cause overflow +or underflow. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the subject sequence has the hexadecimal form and FLT_RADIX is not a +power of 2, and the result is not exactly representable, the result +should be one of the two numbers in the appropriate internal format +that are adjacent to the hexadecimal floating source value, with the +extra stipulation that the error should have a correct sign for the +current rounding direction. +.P +If the subject sequence has the decimal form and at most DECIMAL_DIG +(defined in +.IR ) +significant digits, the result should be correctly rounded. If the +subject sequence +.IR D +has the decimal form and more than DECIMAL_DIG significant digits, +consider the two bounding, adjacent decimal strings +.IR L +and +.IR U , +both having DECIMAL_DIG significant digits, such that the values of +.IR L , +.IR D , +and +.IR U +satisfy +.IR L +<= +.IR D +<= +.IR U . +The result should be one of the (equal or adjacent) values that would +be obtained by correctly rounding +.IR L +and +.IR U +according to the current rounding direction, with the extra stipulation +that the error with respect to +.IR D +should have a correct sign for the current rounding direction. +.P +The changes to +\fIstrtod\fR() +introduced by the ISO/IEC\ 9899:\|1999 standard can alter the behavior of well-formed +applications complying with the ISO/IEC\ 9899:\|1990 standard and thus earlier versions of +this standard. One such example would be: +.sp +.RS 4 +.nf +\fB +int +what_kind_of_number (char *s) +{ + char *endp; + double d; + long l; +.P + d = strtod(s, &endp); + if (s != endp && *endp == `\e0') + printf("It's a float with value %g\en", d); + else + { + l = strtol(s, &endp, 0); + if (s != endp && *endp == `\e0') + printf("It's an integer with value %ld\en", 1); + else + return 1; + } + return 0; +} +.fi \fR +.P +.RE +.P +If the function is called with: +.sp +.RS 4 +.nf +\fB +what_kind_of_number ("0x10") +.fi \fR +.P +.RE +.P +an ISO/IEC\ 9899:\|1990 standard-compliant library will result in the function printing: +.sp +.RS 4 +.nf +\fB +It's an integer with value 16 +.fi \fR +.P +.RE +.P +With the ISO/IEC\ 9899:\|1999 standard, the result is: +.sp +.RS 4 +.nf +\fB +It's a float with value 16 +.fi \fR +.P +.RE +.P +The change in behavior is due to the inclusion of floating-point +numbers in hexadecimal notation without requiring that either a decimal +point or the binary exponent be present. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrtol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strtoimax.3p b/man-pages-posix-2013-a/man3p/strtoimax.3p new file mode 100644 index 0000000..c26cad2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strtoimax.3p @@ -0,0 +1,123 @@ +'\" et +.TH STRTOIMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strtoimax, +strtoumax +\(em convert string to integer type +.SH SYNOPSIS +.LP +.nf +#include +.P +intmax_t strtoimax(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP); +uintmax_t strtoumax(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall be equivalent to the +\fIstrtol\fR(), +\fIstrtoll\fR(), +\fIstrtoul\fR(), +and +\fIstrtoull\fR() +functions, except that the initial portion of the string shall be +converted to +.BR intmax_t +and +.BR uintmax_t +representation, respectively. +.SH "RETURN VALUE" +These functions shall return the converted value, if any. +.P +If no conversion could be performed, zero shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the value of +.IR base +is not supported, 0 shall be returned and +.IR errno +shall be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +{INTMAX_MAX}, +{INTMAX_MIN}, +or +{UINTMAX_MAX} +shall be returned (according to the return type and sign of the value, +if any), and +.IR errno +shall be set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the value of +.IR *endptr +is unspecified if the value of +.IR base +is not supported, applications should either ensure that +.IR base +has a supported value (0 or between 2 and 36) before the call, or check +for an +.BR [EINVAL] +error before examining +.IR *endptr . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtol\fR\^(\|)", +.IR "\fIstrtoul\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strtok.3p b/man-pages-posix-2013-a/man3p/strtok.3p new file mode 100644 index 0000000..531e309 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strtok.3p @@ -0,0 +1,241 @@ +'\" et +.TH STRTOK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strtok, +strtok_r +\(em split string into tokens +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strtok(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +char *strtok_r(char *restrict \fIs\fP, const char *restrict \fIsep\fP, + char **restrict \fIlasts\fP); +.fi +.SH DESCRIPTION +For +\fIstrtok\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +A sequence of calls to +\fIstrtok\fR() +breaks the string pointed to by +.IR s1 +into a sequence of tokens, each of which is delimited by a byte from +the string pointed to by +.IR s2 . +The first call in the sequence has +.IR s1 +as its first argument, and is followed by calls with a null pointer as +their first argument. The separator string pointed to by +.IR s2 +may be different from call to call. +.P +The first call in the sequence searches the string pointed to by +.IR s1 +for the first byte that is +.IR not +contained in the current separator string pointed to by +.IR s2 . +If no such byte is found, then there are no tokens in the string +pointed to by +.IR s1 +and +\fIstrtok\fR() +shall return a null pointer. If such a byte is found, it is the +start of the first token. +.P +The +\fIstrtok\fR() +function then searches from there for a byte that +.IR is +contained in the current separator string. If no such byte is found, +the current token extends to the end of the string pointed to by +.IR s1 , +and subsequent searches for a token shall return a null pointer. If +such a byte is found, it is overwritten by a NUL character, which +terminates the current token. The +\fIstrtok\fR() +function saves a pointer to the following byte, from which the next +search for a token shall start. +.P +Each subsequent call, with a null pointer as the value of the first +argument, starts searching from the saved pointer and behaves as +described above. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 +calls +\fIstrtok\fR(). +.P +The +\fIstrtok\fR() +function need not be thread-safe. +.P +The +\fIstrtok_r\fR() +function considers the null-terminated string +.IR s +as a sequence of zero or more text tokens separated by spans of one or +more characters from the separator string +.IR sep . +The argument +.IR lasts +points to a user-provided pointer which points to stored information +necessary for +\fIstrtok_r\fR() +to continue scanning the same string. +.P +In the first call to +\fIstrtok_r\fR(), +.IR s +points to a null-terminated string, +.IR sep +to a null-terminated string of separator characters, and the value +pointed to by +.IR lasts +is ignored. The +\fIstrtok_r\fR() +function shall return a pointer to the first character of the first +token, write a null character into +.IR s +immediately following the returned token, and update the pointer to +which +.IR lasts +points. +.P +In subsequent calls, +.IR s +is a null pointer and +.IR lasts +shall be unchanged from the previous call so that subsequent calls +shall move through the string +.IR s , +returning successive tokens until no tokens remain. The separator +string +.IR sep +may be different from call to call. When no token remains in +.IR s , +a null pointer shall be returned. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrtok\fR() +shall return a pointer to the first byte of a token. Otherwise, +if there is no token, +\fIstrtok\fR() +shall return a null pointer. +.P +The +\fIstrtok_r\fR() +function shall return a pointer to the token found, or a null pointer +when no token is found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Searching for Word Separators" +.P +The following example searches for tokens separated by + +characters. +.sp +.RS 4 +.nf +\fB +#include +\&... +char *token; +char line[] = "LINE TO BE SEPARATED"; +char *search = " "; +.P +/* Token will point to "LINE". */ +token = strtok(line, search); +.P +/* Token will point to "TO". */ +token = strtok(NULL, search); +.fi \fR +.P +.RE +.SS "Find First two Fields in a Buffer" +.P +The following example uses +\fIstrtok\fR() +to find two character strings (a key and data associated with that key) +separated by any combination of +, +, +or + +characters at the start of the array of characters pointed to by +.IR buffer . +.sp +.RS 4 +.nf +\fB +#include +\&... +char *buffer; +\&... +struct element { + char *key; + char *data; +} e; +\&... +// Load the buffer... +\&... +// Get the key and its data... +e.key = strtok(buffer, " \et\en"); +e.data = strtok(NULL, " \et\en"); +// Process the rest of the contents of the buffer... +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIstrtok_r\fR() +function is thread-safe and stores its state in a user-supplied buffer +instead of possibly using a static data area that may be overwritten +by an unrelated call from another thread. +.SH RATIONALE +The +\fIstrtok\fR() +function searches for a separator string within a larger string. It +returns a pointer to the last substring between separator strings. +This function uses static storage to keep track of the current string +position between calls. The new function, +\fIstrtok_r\fR(), +takes an additional argument, +.IR lasts , +to keep track of the current position in the string. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strtol.3p b/man-pages-posix-2013-a/man3p/strtol.3p new file mode 100644 index 0000000..ad1dc2e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strtol.3p @@ -0,0 +1,244 @@ +'\" et +.TH STRTOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strtol, +strtoll +\(em convert a string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long strtol(const char *restrict \fIstr\fP, char **restrict \fIendptr\fP, int \fIbase\fP); +long long strtoll(const char *restrict \fIstr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP) +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the string pointed +to by +.IR str +to a type +.BR "long" +and +.BR "long long" +representation, respectively. First, they decompose the input string +into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by +\fIisspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of +.IR base +.IP " 3." 4 +A final string of one or more unrecognized characters, including +the terminating NUL character of the input string. +.P +Then they shall attempt to convert the subject sequence to an +integer, and return the result. +.P +If the value of +.IR base +is 0, the expected form of the subject sequence is that of a decimal +constant, octal constant, or hexadecimal constant, any of which may be +preceded by a +.BR '+' +or +.BR '\(mi' +sign. A decimal constant begins with a non-zero digit, and consists of +a sequence of decimal digits. An octal constant consists of the prefix +.BR '0' +optionally followed by a sequence of the digits +.BR '0' +to +.BR '7' +only. A hexadecimal constant consists of the prefix 0x or 0X followed +by a sequence of the decimal digits and letters +.BR 'a' +(or +.BR 'A' ) +to +.BR 'f' +(or +.BR 'F' ) +with values 10 to 15 respectively. +.P +If the value of +.IR base +is between 2 and 36, the expected form of the subject sequence is a +sequence of letters and digits representing an integer with the radix +specified by +.IR base , +optionally preceded by a +.BR '+' +or +.BR '\(mi' +sign. The letters from +.BR 'a' +(or +.BR 'A' ) +to +.BR 'z' +(or +.BR 'Z' ) +inclusive are ascribed the values 10 to 35; only letters whose ascribed +values are less than that of +.IR base +are permitted. If the value of +.IR base +is 16, the characters 0x or 0X may optionally precede the sequence of +letters and digits, following the sign if present. +.P +The subject sequence is defined as the longest initial subsequence of +the input string, starting with the first non-white-space character +that is of the expected form. The subject sequence shall contain no +characters if the input string is empty or consists entirely of +white-space characters, or if the first non-white-space character is +other than a sign or a permissible letter or digit. +.P +If the subject sequence has the expected form and the value of +.IR base +is 0, the sequence of characters starting with the first digit shall be +interpreted as an integer constant. If the subject sequence has the +expected form and the value of +.IR base +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a minus-sign, the value resulting from the +conversion shall be negated. A pointer to the final string shall be +stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +In other than the C +or POSIX +locales, other implementation-defined subject sequences may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion is performed; the value of +.IR str +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0, +{LONG_MIN} +or +{LLONG_MIN}, +and +{LONG_MAX} +or +{LLONG_MAX} +are returned on error and are also valid returns on success, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrtol\fR() +or +\fIstrtoll\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the value of +.IR base +is not supported, 0 shall be returned and +.IR errno +shall be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +{LONG_MIN}, +{LONG_MAX}, +{LLONG_MIN}, +or +{LLONG_MAX} +shall be returned (according to the sign of the value), and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the value of +.IR *endptr +is unspecified if the value of +.IR base +is not supported, applications should either ensure that +.IR base +has a supported value (0 or between 2 and 36) before the call, or check +for an +.BR [EINVAL] +error before examining +.IR *endptr . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strtold.3p b/man-pages-posix-2013-a/man3p/strtold.3p new file mode 100644 index 0000000..6e53bf1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strtold.3p @@ -0,0 +1,38 @@ +'\" et +.TH STRTOLD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strtold +\(em convert a string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +long double strtold(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrtod\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strtoll.3p b/man-pages-posix-2013-a/man3p/strtoll.3p new file mode 100644 index 0000000..fa41797 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strtoll.3p @@ -0,0 +1,39 @@ +'\" et +.TH STRTOLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strtoll +\(em convert a string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long long strtoll(const char *restrict \fIstr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrtol\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strtoul.3p b/man-pages-posix-2013-a/man3p/strtoul.3p new file mode 100644 index 0000000..cf88249 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strtoul.3p @@ -0,0 +1,240 @@ +'\" et +.TH STRTOUL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strtoul, +strtoull +\(em convert a string to an unsigned long +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned long strtoul(const char *restrict \fIstr\fP, + char **restrict \fIendptr\fP, int \fIbase\fP); +unsigned long long strtoull(const char *restrict \fIstr\fP, + char **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the string pointed +to by +.IR str +to a type +.BR "unsigned long" +and +.BR "unsigned long long" +representation, respectively. First, they decompose the input string +into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by +\fIisspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of +.IR base +.IP " 3." 4 +A final string of one or more unrecognized characters, including +the terminating NUL character of the input string +.P +Then they shall attempt to convert the subject sequence to an +unsigned integer, and return the result. +.P +If the value of +.IR base +is 0, the expected form of the subject sequence is that of a decimal +constant, octal constant, or hexadecimal constant, any of which may be +preceded by a +.BR '+' +or +.BR '\(mi' +sign. A decimal constant begins with a non-zero digit, and consists of +a sequence of decimal digits. An octal constant consists of the prefix +.BR '0' +optionally followed by a sequence of the digits +.BR '0' +to +.BR '7' +only. A hexadecimal constant consists of the prefix 0x or 0X followed +by a sequence of the decimal digits and letters +.BR 'a' +(or +.BR 'A' ) +to +.BR 'f' +(or +.BR 'F' ) +with values 10 to 15 respectively. +.P +If the value of +.IR base +is between 2 and 36, the expected form of the subject sequence is a +sequence of letters and digits representing an integer with the radix +specified by +.IR base , +optionally preceded by a +.BR '+' +or +.BR '\(mi' +sign. The letters from +.BR 'a' +(or +.BR 'A' ) +to +.BR 'z' +(or +.BR 'Z' ) +inclusive are ascribed the values 10 to 35; only letters whose ascribed +values are less than that of +.IR base +are permitted. If the value of +.IR base +is 16, the characters 0x or 0X may optionally precede the sequence of +letters and digits, following the sign if present. +.P +The subject sequence is defined as the longest initial subsequence of +the input string, starting with the first non-white-space character +that is of the expected form. The subject sequence shall contain no +characters if the input string is empty or consists entirely of +white-space characters, or if the first non-white-space character is +other than a sign or a permissible letter or digit. +.P +If the subject sequence has the expected form and the value of +.IR base +is 0, the sequence of characters starting with the first digit shall be +interpreted as an integer constant. If the subject sequence has the +expected form and the value of +.IR base +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a minus-sign, the value resulting from the +conversion shall be negated. A pointer to the final string shall be +stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +In other than the C +or POSIX +locales, other implementation-defined subject sequences may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR str +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0, +{ULONG_MAX}, +and +{ULLONG_MAX} +are returned on error and are also valid returns on success, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrtoul\fR() +or +\fIstrtoull\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the value of +.IR base +is not supported, 0 shall be returned and +.IR errno +shall be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +{ULONG_MAX} +or +{ULLONG_MAX} +shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the value of +.IR *endptr +is unspecified if the value of +.IR base +is not supported, applications should either ensure that +.IR base +has a supported value (0 or between 2 and 36) before the call, or check +for an +.BR [EINVAL] +error before examining +.IR *endptr . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIstrtol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strtoumax.3p b/man-pages-posix-2013-a/man3p/strtoumax.3p new file mode 100644 index 0000000..7942019 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strtoumax.3p @@ -0,0 +1,39 @@ +'\" et +.TH STRTOUMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strtoumax +\(em convert a string to an integer type +.SH SYNOPSIS +.LP +.nf +#include +.P +uintmax_t strtoumax(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrtoimax\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/strxfrm.3p b/man-pages-posix-2013-a/man3p/strxfrm.3p new file mode 100644 index 0000000..687197b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/strxfrm.3p @@ -0,0 +1,154 @@ +'\" et +.TH STRXFRM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strxfrm, +strxfrm_l +\(em string transformation +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strxfrm(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIn\fP); +size_t strxfrm_l(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIstrxfrm\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIstrxfrm\fR() +and +\fIstrxfrm_l\fR() +functions shall transform the string pointed to by +.IR s2 +and place the resulting string into the array pointed to by +.IR s1 . +The transformation is such that if +\fIstrcmp\fR() +is applied to two transformed strings, it shall return a value greater +than, equal to, or less than 0, corresponding to the result of +\fIstrcoll\fR() +or +\fIstrcoll_l\fR(), +respectively, applied to the same two original strings +with the same locale. +No more than +.IR n +bytes are placed into the resulting array pointed to by +.IR s1 , +including the terminating NUL character. If +.IR n +is 0, +.IR s1 +is permitted to be a null pointer. If copying takes place between +objects that overlap, the behavior is undefined. +.P +The +\fIstrxfrm\fR() +and +\fIstrxfrm_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrxfrm\fR() +or +\fIstrxfrm_l\fR(), +then check +.IR errno . +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrxfrm_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrxfrm\fR() +and +\fIstrxfrm_l\fR() +shall return the length of the transformed string (not including the +terminating NUL character). If the value returned is +.IR n +or more, the contents of the array pointed to by +.IR s1 +are unspecified. +.P +On error, +\fIstrxfrm\fR() +and +\fIstrxfrm_l\fR() +may set +.IR errno +but no return value is reserved to indicate an error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The string pointed to by the +.IR s2 +argument contains characters outside the domain of the collating +sequence. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The transformation function is such that two transformed strings can be +ordered by +\fIstrcmp\fR() +as appropriate to collating sequence information in the +current locale (category +.IR LC_COLLATE ). +.P +The fact that when +.IR n +is 0 +.IR s1 +is permitted to be a null pointer is useful to determine the size of +the +.IR s1 +array prior to making the transformation. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/swab.3p b/man-pages-posix-2013-a/man3p/swab.3p new file mode 100644 index 0000000..14ce430 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/swab.3p @@ -0,0 +1,77 @@ +'\" et +.TH SWAB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +swab +\(em swap bytes +.SH SYNOPSIS +.LP +.nf +#include +.P +void swab(const void *restrict \fIsrc\fP, void *restrict \fIdest\fP, + ssize_t \fInbytes\fP); +.fi +.SH DESCRIPTION +The +\fIswab\fR() +function shall copy +.IR nbytes +bytes, which are pointed to by +.IR src , +to the object pointed to by +.IR dest , +exchanging adjacent bytes. The +.IR nbytes +argument should be even. If +.IR nbytes +is odd, +\fIswab\fR() +copies and exchanges +.IR nbytes \(mi1 +bytes and the disposition of the last byte is unspecified. If copying +takes place between objects that overlap, the behavior is undefined. +If +.IR nbytes +is negative, +\fIswab\fR() +does nothing. +.SH "RETURN VALUE" +None. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/swprintf.3p b/man-pages-posix-2013-a/man3p/swprintf.3p new file mode 100644 index 0000000..ee0fd20 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/swprintf.3p @@ -0,0 +1,40 @@ +'\" et +.TH SWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +swprintf +\(em print formatted wide-character output +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int swprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP, + const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfwprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/swscanf.3p b/man-pages-posix-2013-a/man3p/swscanf.3p new file mode 100644 index 0000000..91d0333 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/swscanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH SWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +swscanf +\(em convert formatted wide-character input +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int swscanf(const wchar_t *restrict \fIws\fP, + const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfwscanf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/symlink.3p b/man-pages-posix-2013-a/man3p/symlink.3p new file mode 100644 index 0000000..c5979e8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/symlink.3p @@ -0,0 +1,264 @@ +'\" et +.TH SYMLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +symlink, symlinkat +\(em make a symbolic link relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int symlink(const char *\fIpath1\fP, const char *\fIpath2\fP); +int symlinkat(const char *\fIpath1\fP, int \fIfd\fP, const char *\fIpath2\fP); +.fi +.SH DESCRIPTION +The +\fIsymlink\fR() +function shall create a symbolic link called +.IR path2 +that contains the string pointed to by +.IR path1 +(\c +.IR path2 +is the name of the symbolic link created, +.IR path1 +is the string contained in the symbolic link). +.P +The string pointed to by +.IR path1 +shall be treated only as a character string and shall not be validated +as a pathname. +.P +If the +\fIsymlink\fR() +function fails for any reason other than +.BR [EIO] , +any file named by +.IR path2 +shall be unaffected. +.P +If +.IR path2 +names a symbolic link, +\fIsymlink\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +The symbolic link's user ID shall be set to the process' effective +user ID. The symbolic link's group ID shall be set to the group +ID of the parent directory or to the effective group ID of the +process. Implementations shall provide a way to initialize the symbolic +link's group ID to the group ID of the parent directory. Implementations +may, but need not, provide an implementation-defined way to initialize the +symbolic link's group ID to the effective group ID of the calling process. +.P +The values of the file mode bits for the created symbolic link are +unspecified. All interfaces specified by POSIX.1\(hy2008 shall behave as if the +contents of symbolic links can always be read, except that the value of +the file mode bits returned in the +.IR st_mode +field of the +.BR stat +structure is unspecified. +.P +Upon successful completion, +\fIsymlink\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the symbolic link. Also, +the last data modification and last file status change timestamps of +the directory that contains the new entry shall be marked for update. +.P +The +\fIsymlinkat\fR() +function shall be equivalent to the +\fIsymlink\fR() +function except in the case where +.IR path2 +specifies a relative path. In this case the symbolic link is created +relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +If +\fIsymlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIsymlink\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Write permission is denied in the directory where the symbolic link is +being created, or search permission is denied for a component of the +path prefix of +.IR path2 . +.TP +.BR EEXIST +The +.IR path2 +argument names an existing file. +.TP +.BR EIO +An I/O error occurs while reading from or writing to the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path2 +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of the pathname specified by the +.IR path2 +argument is longer than +{NAME_MAX} +or the length of the +.IR path1 +argument is longer than +{SYMLINK_MAX}. +.TP +.BR ENOENT +A component of the path prefix of +.IR path2 +does not name an existing file or +.IR path2 +is an empty string. +.TP +.BR ENOSPC +The directory in which the entry for the new symbolic link is being +placed cannot be extended because no space is left on the file system +containing the directory, or the new symbolic link cannot be created +because no space is left on the file system which shall contain the +link, or the file system is out of file-allocation resources. +.TP +.BR ENOTDIR +A component of the path prefix of +.IR path2 +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EROFS +The new symbolic link would reside on a read-only file system. +.P +The +\fIsymlinkat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path2 +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path2 +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path2 +argument. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR path2 +argument exceeds +{PATH_MAX} +or pathname resolution of a symbolic link in the +.IR path2 +argument produced an intermediate result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Like a hard link, a symbolic link allows a file to have multiple +logical names. The presence of a hard link guarantees the existence of +a file, even after the original name has been removed. A symbolic link +provides no such assurance; in fact, the file named by the +.IR path1 +argument need not exist when the link is created. A symbolic link can +cross file system boundaries. +.P +Normal permission checks are made on each component of the symbolic +link pathname during its resolution. +.SH RATIONALE +The purpose of the +\fIsymlinkat\fR() +function is to create symbolic links in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIsymlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIsymlinkat\fR() +function it can be guaranteed that the created symbolic link is located +relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIlchown\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIreadlink\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sync.3p b/man-pages-posix-2013-a/man3p/sync.3p new file mode 100644 index 0000000..6cae26f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sync.3p @@ -0,0 +1,65 @@ +'\" et +.TH SYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sync +\(em schedule file system updates +.SH SYNOPSIS +.LP +.nf +#include +.P +void sync(void); +.fi +.SH DESCRIPTION +The +\fIsync\fR() +function shall cause all information in memory that updates file +systems to be scheduled for writing out to all file systems. +.P +The writing, although scheduled, is not necessarily complete upon +return from +\fIsync\fR(). +.SH "RETURN VALUE" +The +\fIsync\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfsync\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/sysconf.3p b/man-pages-posix-2013-a/man3p/sysconf.3p new file mode 100644 index 0000000..8e693bf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/sysconf.3p @@ -0,0 +1,358 @@ +'\" et +.TH SYSCONF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sysconf +\(em get configurable system variables +.SH SYNOPSIS +.LP +.nf +#include +.P +long sysconf(int \fIname\fP); +.fi +.SH DESCRIPTION +The +\fIsysconf\fR() +function provides a method for the application to determine the current +value of a configurable system limit or option (\c +.IR variable ). +The implementation shall support all of the variables listed in the +following table and may support others. +.P +The +.IR name +argument represents the system variable to be queried. The following +table lists the minimal set of system variables from +.IR +or +.IR +that can be returned by +\fIsysconf\fR(), +and the symbolic constants defined in +.IR +that are the corresponding values used for +.IR name . +.ad l +.TS +box center tab(@); +cB | cB +lw(2.7i)1e | le. +Variable@Value of Name +_ +{AIO_LISTIO_MAX}@_SC_AIO_LISTIO_MAX +{AIO_MAX}@_SC_AIO_MAX +{AIO_PRIO_DELTA_MAX}@_SC_AIO_PRIO_DELTA_MAX +{ARG_MAX}@_SC_ARG_MAX +{ATEXIT_MAX}@_SC_ATEXIT_MAX +{BC_BASE_MAX}@_SC_BC_BASE_MAX +{BC_DIM_MAX}@_SC_BC_DIM_MAX +{BC_SCALE_MAX}@_SC_BC_SCALE_MAX +{BC_STRING_MAX}@_SC_BC_STRING_MAX +{CHILD_MAX}@_SC_CHILD_MAX +Clock ticks/second@_SC_CLK_TCK +{COLL_WEIGHTS_MAX}@_SC_COLL_WEIGHTS_MAX +{DELAYTIMER_MAX}@_SC_DELAYTIMER_MAX +{EXPR_NEST_MAX}@_SC_EXPR_NEST_MAX +{HOST_NAME_MAX}@_SC_HOST_NAME_MAX +{IOV_MAX}@_SC_IOV_MAX +{LINE_MAX}@_SC_LINE_MAX +{LOGIN_NAME_MAX}@_SC_LOGIN_NAME_MAX +{NGROUPS_MAX}@_SC_NGROUPS_MAX +Initial size of \fIgetgrgid_r\fP\^(\|) and@_SC_GETGR_R_SIZE_MAX +\fIgetgrnam_r\fP\^(\|) data buffers +Initial size of \fIgetpwuid_r\fP\^(\|) and@_SC_GETPW_R_SIZE_MAX +\fIgetpwnam_r\fP\^(\|) data buffers +{MQ_OPEN_MAX}@_SC_MQ_OPEN_MAX +{MQ_PRIO_MAX}@_SC_MQ_PRIO_MAX +{OPEN_MAX}@_SC_OPEN_MAX +_POSIX_ADVISORY_INFO@_SC_ADVISORY_INFO +_POSIX_BARRIERS@_SC_BARRIERS +_POSIX_ASYNCHRONOUS_IO@_SC_ASYNCHRONOUS_IO +_POSIX_CLOCK_SELECTION@_SC_CLOCK_SELECTION +_POSIX_CPUTIME@_SC_CPUTIME +_POSIX_FSYNC@_SC_FSYNC +_POSIX_IPV6@_SC_IPV6 +_POSIX_JOB_CONTROL@_SC_JOB_CONTROL +_POSIX_MAPPED_FILES@_SC_MAPPED_FILES +_POSIX_MEMLOCK@_SC_MEMLOCK +_POSIX_MEMLOCK_RANGE@_SC_MEMLOCK_RANGE +_POSIX_MEMORY_PROTECTION@_SC_MEMORY_PROTECTION +_POSIX_MESSAGE_PASSING@_SC_MESSAGE_PASSING +_POSIX_MONOTONIC_CLOCK@_SC_MONOTONIC_CLOCK +_POSIX_PRIORITIZED_IO@_SC_PRIORITIZED_IO +_POSIX_PRIORITY_SCHEDULING@_SC_PRIORITY_SCHEDULING +_POSIX_RAW_SOCKETS@_SC_RAW_SOCKETS +_POSIX_READER_WRITER_LOCKS@_SC_READER_WRITER_LOCKS +_POSIX_REALTIME_SIGNALS@_SC_REALTIME_SIGNALS +_POSIX_REGEXP@_SC_REGEXP +_POSIX_SAVED_IDS@_SC_SAVED_IDS +_POSIX_SEMAPHORES@_SC_SEMAPHORES +_POSIX_SHARED_MEMORY_OBJECTS@_SC_SHARED_MEMORY_OBJECTS +_POSIX_SHELL@_SC_SHELL +_POSIX_SPAWN@_SC_SPAWN +_POSIX_SPIN_LOCKS@_SC_SPIN_LOCKS +_POSIX_SPORADIC_SERVER@_SC_SPORADIC_SERVER +_POSIX_SS_REPL_MAX@_SC_SS_REPL_MAX +_POSIX_SYNCHRONIZED_IO@_SC_SYNCHRONIZED_IO +_POSIX_THREAD_ATTR_STACKADDR@_SC_THREAD_ATTR_STACKADDR +_POSIX_THREAD_ATTR_STACKSIZE@_SC_THREAD_ATTR_STACKSIZE +_POSIX_THREAD_CPUTIME@_SC_THREAD_CPUTIME +_POSIX_THREAD_PRIO_INHERIT@_SC_THREAD_PRIO_INHERIT +_POSIX_THREAD_PRIO_PROTECT@_SC_THREAD_PRIO_PROTECT +_POSIX_THREAD_PRIORITY_SCHEDULING@_SC_THREAD_PRIORITY_SCHEDULING +_POSIX_THREAD_PROCESS_SHARED@_SC_THREAD_PROCESS_SHARED +_POSIX_THREAD_ROBUST_PRIO_INHERIT@_SC_THREAD_ROBUST_PRIO_INHERIT +_POSIX_THREAD_ROBUST_PRIO_PROTECT@_SC_THREAD_ROBUST_PRIO_PROTECT +_POSIX_THREAD_SAFE_FUNCTIONS@_SC_THREAD_SAFE_FUNCTIONS +_POSIX_THREAD_SPORADIC_SERVER@_SC_THREAD_SPORADIC_SERVER +_POSIX_THREADS@_SC_THREADS +_POSIX_TIMEOUTS@_SC_TIMEOUTS +_POSIX_TIMERS@_SC_TIMERS +_POSIX_TRACE@_SC_TRACE +_POSIX_TRACE_EVENT_FILTER@_SC_TRACE_EVENT_FILTER +_POSIX_TRACE_EVENT_NAME_MAX@_SC_TRACE_EVENT_NAME_MAX +_POSIX_TRACE_INHERIT@_SC_TRACE_INHERIT +_POSIX_TRACE_LOG@_SC_TRACE_LOG +_POSIX_TRACE_NAME_MAX@_SC_TRACE_NAME_MAX +_POSIX_TRACE_SYS_MAX@_SC_TRACE_SYS_MAX +_POSIX_TRACE_USER_EVENT_MAX@_SC_TRACE_USER_EVENT_MAX +_POSIX_TYPED_MEMORY_OBJECTS@_SC_TYPED_MEMORY_OBJECTS +_POSIX_VERSION@_SC_VERSION +_POSIX_V7_ILP32_OFF32@_SC_V7_ILP32_OFF32 +_POSIX_V7_ILP32_OFFBIG@_SC_V7_ILP32_OFFBIG +_POSIX_V7_LP64_OFF64@_SC_V7_LP64_OFF64 +_POSIX_V7_LPBIG_OFFBIG@_SC_V7_LPBIG_OFFBIG +.TE +.ad l +.TS +box center tab(@); +cB | cB +lw(2.6i)1e | le. +Variable@Value of Name +_ +_POSIX_V6_ILP32_OFF32@_SC_V6_ILP32_OFF32 +_POSIX_V6_ILP32_OFFBIG@_SC_V6_ILP32_OFFBIG +_POSIX_V6_LP64_OFF64@_SC_V6_LP64_OFF64 +_POSIX_V6_LPBIG_OFFBIG@_SC_V6_LPBIG_OFFBIG +_POSIX2_C_BIND@_SC_2_C_BIND +_POSIX2_C_DEV@_SC_2_C_DEV +_POSIX2_CHAR_TERM@_SC_2_CHAR_TERM +_POSIX2_FORT_DEV@_SC_2_FORT_DEV +_POSIX2_FORT_RUN@_SC_2_FORT_RUN +_POSIX2_LOCALEDEF@_SC_2_LOCALEDEF +_POSIX2_PBS@_SC_2_PBS +_POSIX2_PBS_ACCOUNTING@_SC_2_PBS_ACCOUNTING +_POSIX2_PBS_CHECKPOINT@_SC_2_PBS_CHECKPOINT +_POSIX2_PBS_LOCATE@_SC_2_PBS_LOCATE +_POSIX2_PBS_MESSAGE@_SC_2_PBS_MESSAGE +_POSIX2_PBS_TRACK@_SC_2_PBS_TRACK +_POSIX2_SW_DEV@_SC_2_SW_DEV +_POSIX2_UPE@_SC_2_UPE +_POSIX2_VERSION@_SC_2_VERSION +{PAGE_SIZE}@_SC_PAGE_SIZE +{PAGESIZE}@_SC_PAGESIZE +{PTHREAD_DESTRUCTOR_ITERATIONS}@_SC_THREAD_DESTRUCTOR_ITERATIONS +{PTHREAD_KEYS_MAX}@_SC_THREAD_KEYS_MAX +{PTHREAD_STACK_MIN}@_SC_THREAD_STACK_MIN +{PTHREAD_THREADS_MAX}@_SC_THREAD_THREADS_MAX +{RE_DUP_MAX}@_SC_RE_DUP_MAX +{RTSIG_MAX}@_SC_RTSIG_MAX +{SEM_NSEMS_MAX}@_SC_SEM_NSEMS_MAX +{SEM_VALUE_MAX}@_SC_SEM_VALUE_MAX +{SIGQUEUE_MAX}@_SC_SIGQUEUE_MAX +{STREAM_MAX}@_SC_STREAM_MAX +{SYMLOOP_MAX}@_SC_SYMLOOP_MAX +{TIMER_MAX}@_SC_TIMER_MAX +{TTY_NAME_MAX}@_SC_TTY_NAME_MAX +{TZNAME_MAX}@_SC_TZNAME_MAX +_XOPEN_CRYPT@_SC_XOPEN_CRYPT +_XOPEN_ENH_I18N@_SC_XOPEN_ENH_I18N +_XOPEN_REALTIME@_SC_XOPEN_REALTIME +_XOPEN_REALTIME_THREADS@_SC_XOPEN_REALTIME_THREADS +_XOPEN_SHM@_SC_XOPEN_SHM +_XOPEN_STREAMS@_SC_XOPEN_STREAMS +_XOPEN_UNIX@_SC_XOPEN_UNIX +_XOPEN_UUCP@_SC_XOPEN_UUCP +_XOPEN_VERSION@_SC_XOPEN_VERSION +.TE +.ad b +.SH "RETURN VALUE" +If +.IR name +is an invalid value, +\fIsysconf\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. If the variable corresponding to +.IR name +is described in +.IR +as a maximum or minimum value and the variable has no limit, +\fIsysconf\fR() +shall return \(mi1 without changing the value of +.IR errno . +Note that indefinite limits do not imply infinite limits; see +.IR . +.P +Otherwise, +\fIsysconf\fR() +shall return the current variable value on the system. The value +returned shall not be more restrictive than the corresponding value +described to the application when it was compiled with the +implementation's +.IR +or +.IR . +The value shall not change during the lifetime of the calling process, +except that \fIsysconf\fP(_SC_OPEN_MAX) may return different values +before and after a call to +\fIsetrlimit\fR() +which changes the RLIMIT_NOFILE soft limit. +.P +If the variable corresponding to +.IR name +is dependent on an unsupported option, the results are unspecified. +.SH ERRORS +The +\fIsysconf\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR name +argument is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +As \(mi1 is a permissible return value in a successful situation, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIsysconf\fR(), +and, if it returns \(mi1, check to see if +.IR errno +is non-zero. +.P +Application developers should check whether an option, such as +_POSIX_TRACE, is supported prior to obtaining and using values for +related variables, such as _POSIX_TRACE_NAME_MAX. +.SH RATIONALE +This functionality was added in response to requirements of application +developers and of system vendors who deal with many international +system configurations. It is closely related to +\fIpathconf\fR() +and +\fIfpathconf\fR(). +.P +Although a conforming application can run on all systems by never +demanding more resources than the minimum values published in this volume of POSIX.1\(hy2008, it +is useful for that application to be able to use the actual value for +the quantity of a resource available on any given system. To do this, +the application makes use of the value of a symbolic constant in +.IR +or +.IR . +.P +However, once compiled, the application must still be able to cope if +the amount of resource available is increased. To that end, an +application may need a means of determining the quantity of a resource, +or the presence of an option, at execution time. +.P +Two examples are offered: +.IP " 1." 4 +Applications may wish to act differently on systems with or without job +control. +Applications vendors who wish to distribute only a single binary +package to all instances of a computer architecture would be forced to +assume job control is never available if it were to rely solely on the +.IR +value published in this volume of POSIX.1\(hy2008. +.IP " 2." 4 +International applications vendors occasionally require knowledge of +the number of clock ticks per second. +Without these facilities, they would be required to either distribute +their applications partially in source form or to have 50 Hz and 60 Hz +versions for the various countries in which they operate. +.P +It is the knowledge that many applications are actually distributed +widely in executable form that leads to this facility. If limited to +the most restrictive values in the headers, such applications would +have to be prepared to accept the most limited environments offered by +the smallest microcomputers. Although this is entirely portable, there +was a consensus that they should be able to take advantage of the +facilities offered by large systems, without the restrictions +associated with source and object distributions. +.P +During the discussions of this feature, it was pointed out that it is +almost always possible for an application to discern what a value might +be at runtime by suitably testing the various functions themselves. +And, in any event, it could always be written to adequately deal with +error returns from the various functions. In the end, it was felt that +this imposed an unreasonable level of complication and sophistication +on the application developer. +.P +This runtime facility is not meant to provide ever-changing values +that applications have to check multiple times. The values are seen as +changing no more frequently than once per system initialization, such +as by a system administrator or operator with an automatic +configuration program. This volume of POSIX.1\(hy2008 specifies that they shall not change +within the lifetime of the process. +.P +Some values apply to the system overall and others vary at the file +system or directory level. The latter are described in +.IR "\fIfpathconf\fR\^(\|)". +.P +Note that all values returned must be expressible as integers. String +values were considered, but the additional flexibility of this approach +was rejected due to its added complexity of implementation and use. +.P +Some values, such as +{PATH_MAX}, +are sometimes so large that they must not be used to, say, allocate +arrays. The +\fIsysconf\fR() +function returns a negative value to show that this symbolic constant +is not even defined in this case. +.P +Similar to +\fIpathconf\fR(), +this permits the implementation not to have a limit. When one resource +is infinite, returning an error indicating that some other resource +limit has been reached is conforming behavior. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/syslog.3p b/man-pages-posix-2013-a/man3p/syslog.3p new file mode 100644 index 0000000..c51b55c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/syslog.3p @@ -0,0 +1,38 @@ +'\" et +.TH SYSLOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +syslog +\(em log a message +.SH SYNOPSIS +.LP +.nf +#include +.P +void syslog(int \fIpriority\fP, const char *\fImessage\fP, ... /* \fIargument\fP */); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcloselog\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/system.3p b/man-pages-posix-2013-a/man3p/system.3p new file mode 100644 index 0000000..9275c56 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/system.3p @@ -0,0 +1,459 @@ +'\" et +.TH SYSTEM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +system +\(em issue a command +.SH SYNOPSIS +.LP +.nf +#include +.P +int system(const char *\fIcommand\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If +.IR command +is a null pointer, the +\fIsystem\fR() +function shall determine whether the host environment has a command +processor. If +.IR command +is not a null pointer, the +\fIsystem\fR() +function shall pass the string pointed to by +.IR command +to that command processor to be executed in an implementation-defined +manner; this might then cause the program calling +\fIsystem\fR() +to behave in a non-conforming manner or to terminate. +.P +The +\fIsystem\fR() +function shall behave as if a child process were created using +\fIfork\fR(), +and the child process invoked the +.IR sh +utility using +\fIexecl\fR() +as follows: +.sp +.RS 4 +.nf +\fB +execl(<\fIshell path\fP>, "sh", "-c", \fIcommand\fP, (char *)0); +.fi \fR +.P +.RE +.P +where <\fIshell path\fP> is an unspecified pathname for the +.IR sh +utility. It is unspecified whether the handlers registered with +\fIpthread_atfork\fR() +are called as part of the creation of the child process. +.P +The +\fIsystem\fR() +function shall ignore the SIGINT and SIGQUIT signals, and shall +block the SIGCHLD +signal, while waiting for the command to terminate. If this might +cause the application to miss a signal that would have killed it, then +the application should examine the return value from +\fIsystem\fR() +and take whatever action is appropriate to the application if the +command terminated due to receipt of a signal. +.P +The +\fIsystem\fR() +function shall not affect the termination status of any child of the +calling processes other than the process or processes it itself +creates. +.P +The +\fIsystem\fR() +function shall not return until the child process has terminated. +.P +The +\fIsystem\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If +.IR command +is a null pointer, +\fIsystem\fR() +shall return non-zero to indicate that a command processor is +available, or zero if none is available. +The +\fIsystem\fR() +function shall always return non-zero when +.IR command +is NULL. +.P +If +.IR command +is not a null pointer, +\fIsystem\fR() +shall return the termination status of the command language interpreter +in the format specified by +\fIwaitpid\fR(). +The termination status shall be as defined for the +.IR sh +utility; otherwise, the termination status is unspecified. If some +error prevents the command language interpreter from executing after +the child process is created, the return value from +\fIsystem\fR() +shall be as if the command language interpreter had terminated using +.IR exit (127) +or +.IR _exit (127). +If a child process cannot be created, or if the termination status for +the command language interpreter cannot be obtained, +\fIsystem\fR() +shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsystem\fR() +function may set +.IR errno +values as described by +.IR "\fIfork\fR\^(\|)". +.br +.P +In addition, +\fIsystem\fR() +may fail if: +.TP +.BR ECHILD +The status of the child process created by +\fIsystem\fR() +is no longer available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the return value of +\fIsystem\fR() +is not \(mi1, its value can be decoded through the use of the macros +described in +.IR . +For convenience, these macros are also provided in +.IR . +.P +Note that, while +\fIsystem\fR() +must ignore SIGINT and SIGQUIT and block SIGCHLD while waiting for the +child to terminate, the handling of signals in the executed command is +as specified by +\fIfork\fR() +and +.IR exec . +For example, if SIGINT is being caught or is set to SIG_DFL when +\fIsystem\fR() +is called, then the child is started with SIGINT handling set to +SIG_DFL. +.P +Ignoring SIGINT and SIGQUIT in the parent process prevents coordination +problems (two processes reading from the same terminal, for example) +when the executed command ignores or catches one of the signals. It is +also usually the correct action when the user has given a command to +the application to be executed synchronously (as in the +.BR '!' +command in many interactive applications). In either case, the signal +should be delivered only to the child process, not to the application +itself. There is one situation where ignoring the signals might have +less than the desired effect. This is when the application uses +\fIsystem\fR() +to perform some task invisible to the user. If the user typed the +interrupt character (\c +.BR \(dq^C\(dq , +for example) while +\fIsystem\fR() +is being used in this way, one would expect the application to be +killed, but only the executed command is killed. Applications that use +\fIsystem\fR() +in this way should carefully check the return status from +\fIsystem\fR() +to see if the executed command was successful, and should take +appropriate action when the command fails. +.P +Blocking SIGCHLD while waiting for the child to terminate prevents the +application from catching the signal and obtaining status from +\fIsystem\fR()'s +child process before +\fIsystem\fR() +can get the status itself. +.P +The context in which the utility is ultimately executed may differ from +that in which +\fIsystem\fR() +was called. For example, file descriptors that have the FD_CLOEXEC +flag set are closed, and the process ID and parent process ID are +different. Also, if the executed utility changes its environment +variables or its current working directory, that change is not +reflected in the caller's context. +.P +There is no defined way for an application to find the specific path +for the shell. However, +\fIconfstr\fR() +can provide a value for +.IR PATH +that is guaranteed to find the +.IR sh +utility. +.P +Using the +\fIsystem\fR() +function in more than one thread in a process or when the SIGCHLD +signal is being manipulated by more than one thread in a process may +produce unexpected results. +.SH RATIONALE +The +\fIsystem\fR() +function should not be used by programs that have set user (or group) +ID privileges. The +\fIfork\fR() +and +.IR exec +family of functions (except +\fIexeclp\fR() +and +\fIexecvp\fR()), +should be used instead. This prevents any unforeseen manipulation of +the environment of the user that could cause execution of commands not +anticipated by the calling program. +.P +There are three levels of specification for the +\fIsystem\fR() +function. The ISO\ C standard gives the most basic. It requires that the function +exists, and defines a way for an application to query whether a command +language interpreter exists. It says nothing about the command language +or the environment in which the command is interpreted. +.P +POSIX.1\(hy2008 places additional restrictions on +\fIsystem\fR(). +It requires that if there is a command language interpreter, the +environment must be as specified by +\fIfork\fR() +and +.IR exec . +This ensures, for example, that close-on-\c +.IR exec +works, that file locks are not inherited, and that the process ID is +different. It also specifies the return value from +\fIsystem\fR() +when the command line can be run, thus giving the application some +information about the command's completion status. +.P +Finally, POSIX.1\(hy2008 requires the command to be interpreted as in the shell +command language defined in the Shell and Utilities volume of POSIX.1\(hy2008. +.P +Note that, +.IR system (NULL) +is required to return non-zero, indicating that there is a command +language interpreter. At first glance, this would seem to conflict with +the ISO\ C standard which allows +.IR system (NULL) +to return zero. There is no conflict, however. A system must have a +command language interpreter, and is non-conforming if none is present. +It is therefore permissible for the +\fIsystem\fR() +function on such a system to implement the behavior specified by the +ISO\ C standard as long as it is understood that the implementation does not +conform to POSIX.1\(hy2008 if +.IR system (NULL) +returns zero. +.P +It was explicitly decided that when +.IR command +is NULL, +\fIsystem\fR() +should not be required to check to make sure that the command language +interpreter actually exists with the correct mode, that there are +enough processes to execute it, and so on. The call +.IR system (NULL) +could, theoretically, check for such problems as too many existing +child processes, and return zero. However, it would be inappropriate to +return zero due to such a (presumably) transient condition. If some +condition exists that is not under the control of this application and +that would cause any +\fIsystem\fR() +call to fail, that system has been rendered non-conforming. +.P +Early drafts required, or allowed, +\fIsystem\fR() +to return with +.IR errno +set to +.BR [EINTR] +if it was interrupted with a signal. This error return was removed, and +a requirement that +\fIsystem\fR() +not return until the child has terminated was added. This means that if +a +\fIwaitpid\fR() +call in +\fIsystem\fR() +exits with +.IR errno +set to +.BR [EINTR] , +\fIsystem\fR() +must reissue the +\fIwaitpid\fR(). +This change was made for two reasons: +.IP " 1." 4 +There is no way for an application to clean up if +\fIsystem\fR() +returns +.BR [EINTR] , +short of calling +\fIwait\fR(), +and that could have the undesirable effect of returning the status of +children other than the one started by +\fIsystem\fR(). +.IP " 2." 4 +While it might require a change in some historical implementations, +those implementations already have to be changed because they use +\fIwait\fR() +instead of +\fIwaitpid\fR(). +.P +Note that if the application is catching SIGCHLD signals, it will +receive such a signal before a successful +\fIsystem\fR() +call returns. +.P +To conform to POSIX.1\(hy2008, +\fIsystem\fR() +must use +\fIwaitpid\fR(), +or some similar function, instead of +\fIwait\fR(). +.P +The following code sample illustrates how +\fIsystem\fR() +might be implemented on an implementation conforming to POSIX.1\(hy2008. +.sp +.RS 4 +.nf +\fB +#include +int system(const char *cmd) +{ + int stat; + pid_t pid; + struct sigaction sa, savintr, savequit; + sigset_t saveblock; + if (cmd == NULL) + return(1); + sa.sa_handler = SIG_IGN; + sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + sigemptyset(&savintr.sa_mask); + sigemptyset(&savequit.sa_mask); + sigaction(SIGINT, &sa, &savintr); + sigaction(SIGQUIT, &sa, &savequit); + sigaddset(&sa.sa_mask, SIGCHLD); + sigprocmask(SIG_BLOCK, &sa.sa_mask, &saveblock); + if ((pid = fork()) == 0) { + sigaction(SIGINT, &savintr, (struct sigaction *)0); + sigaction(SIGQUIT, &savequit, (struct sigaction *)0); + sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0); + execl("/bin/sh", "sh", "-c", cmd, (char *)0); + _exit(127); + } + if (pid == -1) { + stat = -1; /* errno comes from fork() */ + } else { + while (waitpid(pid, &stat, 0) == -1) { + if (errno != EINTR){ + stat = -1; + break; + } + } + } + sigaction(SIGINT, &savintr, (struct sigaction *)0); + sigaction(SIGQUIT, &savequit, (struct sigaction *)0); + sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0); + return(stat); +} +.fi \fR +.P +.RE +.P +Note that, while a particular implementation of +\fIsystem\fR() +(such as the one above) can assume a particular path for the shell, +such a path is not necessarily valid on another system. The above +example is not portable, and is not intended to be. +.P +One reviewer suggested that an implementation of +\fIsystem\fR() +might want to use an environment variable such as +.IR SHELL +to determine which command interpreter to use. The supposed +implementation would use the default command interpreter if the one +specified by the environment variable was not available. This would +allow a user, when using an application that prompts for command lines +to be processed using +\fIsystem\fR(), +to specify a different command interpreter. Such an implementation is +discouraged. If the alternate command interpreter did not follow the +command line syntax specified in the Shell and Utilities volume of POSIX.1\(hy2008, then changing +.IR SHELL +would render +\fIsystem\fR() +non-conforming. This would affect applications that expected the +specified behavior from +\fIsystem\fR(), +and since the Shell and Utilities volume of POSIX.1\(hy2008 does not mention that +.IR SHELL +affects +\fIsystem\fR(), +the application would not know that it needed to unset +.IR SHELL . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIsh\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tan.3p b/man-pages-posix-2013-a/man3p/tan.3p new file mode 100644 index 0000000..29c43ae --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tan.3p @@ -0,0 +1,206 @@ +'\" et +.TH TAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tan, +tanf, +tanl +\(em tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +double tan(double \fIx\fP); +float tanf(float \fIx\fP); +long double tanl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the tangent of their argument +.IR x , +measured in radians. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the tangent of +.IR x . +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fItan\fR(), +\fItanf\fR(), +and +\fItanl\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, and LDBL_MIN, +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fItan\fR(), +\fItanf\fR(), +and +\fItanl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and either a NaN (if +supported), or an implementation-defined value shall be returned. +.P +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be returned. +.P +If the correct value would cause overflow, a range error shall occur +and +\fItan\fR(), +\fItanf\fR(), +and +\fItanl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, +respectively, with the same sign as the correct value of the function. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The result overflows +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.br +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows, +or the value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Taking the Tangent of a 45-Degree Angle" +.sp +.RS 4 +.nf +\fB +#include +\&... +double radians = 45.0 * M_PI / 180; +double result; +\&... +result = tan (radians); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +There are no known floating-point representations such that for a +normal argument, +.IR tan (\c +.IR x ) +is either overflow or underflow. +.P +These functions may lose accuracy when their argument is near a +multiple of \(*p/2 or is far from 0.0. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatan\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tanh.3p b/man-pages-posix-2013-a/man3p/tanh.3p new file mode 100644 index 0000000..53cd05e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tanh.3p @@ -0,0 +1,129 @@ +'\" et +.TH TANH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tanh, +tanhf, +tanhl +\(em hyperbolic tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double tanh(double \fIx\fP); +float tanhf(float \fIx\fP); +long double tanhl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the hyperbolic tangent of their argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the hyperbolic +tangent of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is \(+-Inf, \(+-1 shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fItanh\fR(), +\fItanhf\fR(), +and +\fItanhl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatanh\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fItan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tanl.3p b/man-pages-posix-2013-a/man3p/tanl.3p new file mode 100644 index 0000000..5adf18c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tanl.3p @@ -0,0 +1,38 @@ +'\" et +.TH TANL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tanl +\(em tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double tanl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItan\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcdrain.3p b/man-pages-posix-2013-a/man3p/tcdrain.3p new file mode 100644 index 0000000..67cfe28 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcdrain.3p @@ -0,0 +1,97 @@ +'\" et +.TH TCDRAIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcdrain +\(em wait for transmission of output +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcdrain(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fItcdrain\fR() +function shall block until all output written to the object referred +to by +.IR fildes +is transmitted. The +.IR fildes +argument is an open file descriptor associated with a terminal. +.P +Any attempts to use +\fItcdrain\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal, shall cause the process group +to be sent a SIGTTOU signal. +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the process shall be allowed to perform the +operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcdrain\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINTR +A signal interrupted +\fItcdrain\fR(). +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcflush\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcflow.3p b/man-pages-posix-2013-a/man3p/tcflow.3p new file mode 100644 index 0000000..f3737a9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcflow.3p @@ -0,0 +1,133 @@ +'\" et +.TH TCFLOW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcflow +\(em suspend or restart the transmission or reception of data +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcflow(int \fIfildes\fP, int \fIaction\fP); +.fi +.SH DESCRIPTION +The +\fItcflow\fR() +function shall suspend or restart transmission or reception of data on +the object referred to by +.IR fildes , +depending on the value of +.IR action . +The +.IR fildes +argument is an open file descriptor associated with a terminal. +.IP " *" 4 +If +.IR action +is TCOOFF, output shall be suspended. +.IP " *" 4 +If +.IR action +is TCOON, suspended output shall be restarted. +.IP " *" 4 +If +.IR action +is TCIOFF and +.IR fildes +refers to a terminal device, the system shall transmit a STOP character, +which is intended to cause the terminal device to stop transmitting data +to the system. If +.IR fildes +is associated with a pseudo-terminal, the STOP character need not be +transmitted. +.IP " *" 4 +If +.IR action +is TCION and +.IR fildes +refers to a terminal device, the system shall transmit a START character, +which is intended to cause the terminal device to start transmitting +data to the system. If +.IR fildes +is associated with a pseudo-terminal, the START character need not be +transmitted. +.P +The default on the opening of a terminal file is that neither its input +nor its output are suspended. +.P +Attempts to use +\fItcflow\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal, shall cause the process group +to be sent a SIGTTOU signal. +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the process shall be allowed to perform the +operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcflow\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The +.IR action +argument is not a supported value. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcsendbreak\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcflush.3p b/man-pages-posix-2013-a/man3p/tcflush.3p new file mode 100644 index 0000000..641344c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcflush.3p @@ -0,0 +1,110 @@ +'\" et +.TH TCFLUSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcflush +\(em flush non-transmitted output data, non-read input data, or both +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcflush(int \fIfildes\fP, int \fIqueue_selector\fP); +.fi +.SH DESCRIPTION +Upon successful completion, +\fItcflush\fR() +shall discard data written to the object referred to by +.IR fildes +(an open file descriptor associated with a terminal) but not +transmitted, or data received but not read, depending on the value of +.IR queue_selector : +.IP " *" 4 +If +.IR queue_selector +is TCIFLUSH, it shall flush data received but not read. +.IP " *" 4 +If +.IR queue_selector +is TCOFLUSH, it shall flush data written but not transmitted. +.IP " *" 4 +If +.IR queue_selector +is TCIOFLUSH, it shall flush both data received but not read and data +written but not transmitted. +.P +Attempts to use +\fItcflush\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal shall cause the process group +to be sent a SIGTTOU signal. +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the process shall be allowed to perform the +operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcflush\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The +.IR queue_selector +argument is not a supported value. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcdrain\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcgetattr.3p b/man-pages-posix-2013-a/man3p/tcgetattr.3p new file mode 100644 index 0000000..6510980 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcgetattr.3p @@ -0,0 +1,146 @@ +'\" et +.TH TCGETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcgetattr +\(em get the parameters associated with the terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcgetattr(int \fIfildes\fP, struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fItcgetattr\fR() +function shall get the parameters associated with the terminal referred +to by +.IR fildes +and store them in the +.BR termios +structure referenced by +.IR termios_p . +The +.IR fildes +argument is an open file descriptor associated with a terminal. +.P +The +.IR termios_p +argument is a pointer to a +.BR termios +structure. +.P +The +\fItcgetattr\fR() +operation is allowed from any process. +.P +If the terminal device supports different input and output baud rates, +the baud rates stored in the +.BR termios +structure returned by +\fItcgetattr\fR() +shall reflect the actual baud rates, even if they are equal. If +differing baud rates are not supported, the rate returned as the output +baud rate shall be the actual baud rate. If the terminal device does +not support split baud rates, the input baud rate stored in the +.BR termios +structure shall be the output rate (as one of the symbolic values). +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcgetattr\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Care must be taken when changing the terminal attributes. Applications +should always do a +\fItcgetattr\fR(), +save the +.BR termios +structure values returned, and then do a +\fItcsetattr\fR(), +changing only the necessary fields. The application should use the +values saved from the +\fItcgetattr\fR() +to reset the terminal state whenever it is done with the terminal. +This is necessary because terminal attributes apply to the underlying +port and not to each individual open instance; that is, all processes +that have used the terminal see the latest attribute changes. +.P +A program that uses these functions should be written to catch all +signals and take other appropriate actions to ensure that when the +program terminates, whether planned or not, the terminal device's state +is restored to its original state. +.P +Existing practice dealing with error returns when only part of a +request can be honored is based on calls to the +\fIioctl\fR() +function. In historical BSD and System V implementations, +the corresponding +\fIioctl\fR() +returns zero if the requested actions were semantically correct, even +if some of the requested changes could not be made. Many existing +applications assume this behavior and would no longer work correctly if +the return value were changed from zero to \(mi1 in this case. +.P +Note that either specification has a problem. When zero is returned, +it implies everything succeeded even if some of the changes were not +made. When \(mi1 is returned, it implies everything failed even though +some of the changes were made. +.P +Applications that need all of the requested changes made to work +properly should follow +\fItcsetattr\fR() +with a call to +\fItcgetattr\fR() +and compare the appropriate field values. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcsetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcgetpgrp.3p b/man-pages-posix-2013-a/man3p/tcgetpgrp.3p new file mode 100644 index 0000000..c6ee6ae --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcgetpgrp.3p @@ -0,0 +1,90 @@ +'\" et +.TH TCGETPGRP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcgetpgrp +\(em get the foreground process group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t tcgetpgrp(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fItcgetpgrp\fR() +function shall return the value of the process group ID of the +foreground process group associated with the terminal. +.P +If there is no foreground process group, +\fItcgetpgrp\fR() +shall return a value greater than 1 that does not match the process +group ID of any existing process group. +.P +The +\fItcgetpgrp\fR() +function is allowed from a process that is a member of a background +process group; however, the information may be subsequently changed by +a process that is a member of a foreground process group. +.SH "RETURN VALUE" +Upon successful completion, +\fItcgetpgrp\fR() +shall return the value of the process group ID of the foreground +process associated with the terminal. Otherwise, \(mi1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcgetpgrp\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetsid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fItcsetpgrp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcgetsid.3p b/man-pages-posix-2013-a/man3p/tcgetsid.3p new file mode 100644 index 0000000..f770558 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcgetsid.3p @@ -0,0 +1,76 @@ +'\" et +.TH TCGETSID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcgetsid +\(em get the process group ID for the session leader for the +controlling terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t tcgetsid(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fItcgetsid\fR() +function shall obtain the process group ID of the session for which the +terminal specified by +.IR fildes +is the controlling terminal. +.SH "RETURN VALUE" +Upon successful completion, +\fItcgetsid\fR() +shall return the process group ID of the session associated with the +terminal. Otherwise, a value of \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcgetsid\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcsendbreak.3p b/man-pages-posix-2013-a/man3p/tcsendbreak.3p new file mode 100644 index 0000000..48a2da8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcsendbreak.3p @@ -0,0 +1,103 @@ +'\" et +.TH TCSENDBREAK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcsendbreak +\(em send a break for a specific duration +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcsendbreak(int \fIfildes\fP, int \fIduration\fP); +.fi +.SH DESCRIPTION +If the terminal is using asynchronous serial data transmission, +\fItcsendbreak\fR() +shall cause transmission of a continuous stream of zero-valued bits for +a specific duration. If +.IR duration +is 0, it shall cause transmission of zero-valued bits for at least 0.25 +seconds, and not more than 0.5 seconds. If +.IR duration +is not 0, it shall send zero-valued bits for an +implementation-defined period of time. +.P +The +.IR fildes +argument is an open file descriptor associated with a terminal. +.P +If the terminal is not using asynchronous serial data transmission, it +is implementation-defined whether +\fItcsendbreak\fR() +sends data to generate a break condition or returns without taking any +action. +.P +Attempts to use +\fItcsendbreak\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal shall cause the process group +to be sent a SIGTTOU signal. +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the process shall be allowed to perform the +operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcsendbreak\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcsetattr.3p b/man-pages-posix-2013-a/man3p/tcsetattr.3p new file mode 100644 index 0000000..014383b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcsetattr.3p @@ -0,0 +1,240 @@ +'\" et +.TH TCSETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcsetattr +\(em set the parameters associated with the terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcsetattr(int \fIfildes\fP, int \fIoptional_actions\fP, + const struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fItcsetattr\fR() +function shall set the parameters associated with the terminal referred +to by the open file descriptor +.IR fildes +(an open file descriptor associated with a terminal) from the +.BR termios +structure referenced by +.IR termios_p +as follows: +.IP " *" 4 +If +.IR optional_actions +is TCSANOW, the change shall occur immediately. +.IP " *" 4 +If +.IR optional_actions +is TCSADRAIN, the change shall occur after all output written to +.IR fildes +is transmitted. This function should be used when changing parameters +that affect output. +.IP " *" 4 +If +.IR optional_actions +is TCSAFLUSH, the change shall occur after all output written to +.IR fildes +is transmitted, and all input so far received but not read shall be +discarded before the change is made. +.P +If the output baud rate stored in the +.BR termios +structure pointed to by +.IR termios_p +is the zero baud rate, B0, the modem control lines shall no longer +be asserted. Normally, this shall disconnect the line. +.P +If the input baud rate stored in the +.BR termios +structure pointed to by +.IR termios_p +is 0, the input baud rate given to the hardware is the same as the +output baud rate stored in the +.BR termios +structure. +.P +The +\fItcsetattr\fR() +function shall return successfully if it was able to perform any of the +requested actions, even if some of the requested actions could not be +performed. It shall set all the attributes that the implementation +supports as requested and leave all the attributes not supported by +the implementation unchanged. If no part of the request can be honored, +it shall return \(mi1 and set +.IR errno +to +.BR [EINVAL] . +If the input and output baud rates differ and are a combination that is +not supported, neither baud rate shall be changed. A subsequent call to +\fItcgetattr\fR() +shall return the actual state of the terminal device (reflecting both +the changes made and not made in the previous +\fItcsetattr\fR() +call). The +\fItcsetattr\fR() +function shall not change the values found in the +.BR termios +structure under any circumstances. +.P +The effect of +\fItcsetattr\fR() +is undefined if the value of the +.BR termios +structure pointed to by +.IR termios_p +was not derived from the result of a call to +\fItcgetattr\fR() +on +.IR fildes ; +an application should modify only fields and flags defined by this volume of POSIX.1\(hy2008 +between the call to +\fItcgetattr\fR() +and +\fItcsetattr\fR(), +leaving all other fields and flags unmodified. +.P +No actions defined by this volume of POSIX.1\(hy2008, other than a call to +\fItcsetattr\fR(), +a close of the last file descriptor in the system associated with this +terminal device, or an open of the first file descriptor in the system +associated with this terminal device (using the O_TTY_INIT flag if it +is non-zero and the device is not a pseudo-terminal), shall cause any +of the terminal attributes defined by this volume of POSIX.1\(hy2008 to change. +.P +If +\fItcsetattr\fR() +is called from a process which is a member of a background process +group on a +.IR fildes +associated with its controlling terminal: +.IP " *" 4 +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the operation completes normally and no signal +is sent. +.IP " *" 4 +Otherwise, a SIGTTOU signal shall be sent to the process group. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, +\(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcsetattr\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINTR +A signal interrupted +\fItcsetattr\fR(). +.TP +.BR EINVAL +The +.IR optional_actions +argument is not a supported value, or an attempt was made to change an +attribute represented in the +.BR termios +structure to an unsupported value. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If trying to change baud rates, applications should call +\fItcsetattr\fR() +then call +\fItcgetattr\fR() +in order to determine what baud rates were actually selected. +.P +In general, there are two reasons for an application to change the +parameters associated with a terminal device: +.IP " 1." 4 +The device already has working parameter settings but the application +needs a different behavior, such as non-canonical mode instead of +canonical mode. The application sets (or clears) only a few flags or +.IR c_cc [\^] +values. Typically, the terminal device in this case is either the +controlling terminal for the process or a pseudo-terminal. +.IP " 2." 4 +The device is a modem or similar piece of equipment connected by a serial +line, and it was not open before the application opened it. In this case, +the application needs to initialize all of the parameter settings ``from +scratch''. However, since the +.BR termios +structure may include both standard and non-standard parameters, the +application cannot just initialize the whole structure in an arbitrary +way (e.g., using +\fImemset\fR()) +as this may cause some of the non-standard parameters to be set +incorrectly, resulting in non-conforming behavior of the terminal +device. Conversely, the application cannot just set the standard +parameters, assuming that the non-standard parameters will already have +suitable values, as the device might previously have been used with +non-conforming parameter settings (and some implementations retain the +settings from one use to the next). The solution is to open the terminal +device using the O_TTY_INIT flag to initialize the terminal device to +have conforming parameter settings, obtain those settings using +\fItcgetattr\fR(), +and then set all of the standard parameters to the desired settings. +.SH RATIONALE +The +\fItcsetattr\fR() +function can be interrupted in the following situations: +.IP " *" 4 +It is interrupted while waiting for output to drain. +.IP " *" 4 +It is called from a process in a background process group and SIGTTOU +is caught. +.P +See also the RATIONALE section in +.IR "\fItcgetattr\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +Using an input baud rate of 0 to set the input rate equal to the output +rate may not necessarily be supported in a future version of this volume of POSIX.1\(hy2008. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tcsetpgrp.3p b/man-pages-posix-2013-a/man3p/tcsetpgrp.3p new file mode 100644 index 0000000..e20cc00 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tcsetpgrp.3p @@ -0,0 +1,109 @@ +'\" et +.TH TCSETPGRP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcsetpgrp +\(em set the foreground process group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcsetpgrp(int \fIfildes\fP, pid_t \fIpgid_id\fP); +.fi +.SH DESCRIPTION +If the process has a controlling terminal, +\fItcsetpgrp\fR() +shall set the foreground process group ID associated with the terminal +to +.IR pgid_id . +The application shall ensure that the file associated with +.IR fildes +is the controlling terminal of the calling process and the controlling +terminal is currently associated with the session of the calling +process. The application shall ensure that the value of +.IR pgid_id +matches a process group ID of a process in the same session as the +calling process. +.P +Attempts to use +\fItcsetpgrp\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal shall cause the process group +to be sent a SIGTTOU signal. If the calling thread is blocking SIGTTOU +signals or the process is ignoring SIGTTOU signals, the process shall +be allowed to perform the operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcsetpgrp\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +This implementation does not support the value in the +.IR pgid_id +argument. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal, or the controlling terminal is no +longer associated with the session of the calling process. +.TP +.BR EPERM +The value of +.IR pgid_id +is a value supported by the implementation, but does not match the +process group ID of a process in the same session as the calling +process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcgetpgrp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tdelete.3p b/man-pages-posix-2013-a/man3p/tdelete.3p new file mode 100644 index 0000000..507a3ba --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tdelete.3p @@ -0,0 +1,319 @@ +'\" et +.TH TDELETE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tdelete, +tfind, +tsearch, +twalk +\(em manage a binary search tree +.SH SYNOPSIS +.LP +.nf +#include +.P +void *tdelete(const void *restrict \fIkey\fP, void **restrict \fIrootp\fP, + int(*\fIcompar\fP)(const void *, const void *)); +void *tfind(const void *\fIkey\fP, void *const *\fIrootp\fP, + int(*\fIcompar\fP)(const void *, const void *)); +void *tsearch(const void *\fIkey\fP, void **\fIrootp\fP, + int (*\fIcompar\fP)(const void *, const void *)); +void twalk(const void *\fIroot\fP, + void (*\fIaction\fP)(const void *, VISIT, int)); +.fi +.SH DESCRIPTION +The +\fItdelete\fR(), +\fItfind\fR(), +\fItsearch\fR(), +and +\fItwalk\fR() +functions manipulate binary search trees. Comparisons are made with a +user-supplied routine, the address of which is passed as the +.IR compar +argument. This routine is called with two arguments, which are the +pointers to the elements being compared. The application shall ensure +that the user-supplied routine returns an integer less than, equal to, +or greater than 0, according to whether the first argument is to be +considered less than, equal to, or greater than the second argument. +The comparison function need not compare every byte, so arbitrary data +may be contained in the elements in addition to the values being +compared. +.P +The +\fItsearch\fR() +function shall build and access the tree. The +.IR key +argument is a pointer to an element to be accessed or stored. If there +is a node in the tree whose element is equal to the value pointed to by +.IR key , +a pointer to this found node shall be returned. Otherwise, the value +pointed to by +.IR key +shall be inserted (that is, a new node is created and the value of +.IR key +is copied to this node), and a pointer to this node returned. Only +pointers are copied, so the application shall ensure that the calling +routine stores the data. The +.IR rootp +argument points to a variable that points to the root node of the +tree. A null pointer value for the variable pointed to by +.IR rootp +denotes an empty tree; in this case, the variable shall be set to point +to the node which shall be at the root of the new tree. +.P +Like +\fItsearch\fR(), +\fItfind\fR() +shall search for a node in the tree, returning a pointer to it if found. +However, if it is not found, +\fItfind\fR() +shall return a null pointer. The arguments for +\fItfind\fR() +are the same as for +\fItsearch\fR(). +.P +The +\fItdelete\fR() +function shall delete a node from a binary search tree. The arguments +are the same as for +\fItsearch\fR(). +The variable pointed to by +.IR rootp +shall be changed if the deleted node was the root of the tree. The +\fItdelete\fR() +function shall return a pointer to the parent of the deleted node, or +an unspecified non-null pointer if the deleted node was the root node, +or a null pointer if the node is not found. +.P +If +\fItsearch\fR() +adds an element to a tree, or +\fItdelete\fR() +successfully deletes an element from a tree, the concurrent use of +that tree in another thread, or use of pointers produced by a previous +call to +\fItfind\fR() +or +\fItsearch\fR(), +produces undefined results. +.P +The +\fItwalk\fR() +function shall traverse a binary search tree. The +.IR root +argument is a pointer to the root node of the tree to be traversed. +(Any node in a tree may be used as the root for a walk below that +node.) The argument +.IR action +is the name of a routine to be invoked at each node. This routine is, +in turn, called with three arguments. The first argument shall be the +address of the node being visited. The structure pointed to by this +argument is unspecified and shall not be modified by the application, +but it shall be possible to cast a pointer-to-node into a +pointer-to-pointer-to-element to access the element stored in the node. +The second argument shall be a value from an enumeration data type: +.sp +.RS 4 +.nf +\fB +typedef enum { preorder, postorder, endorder, leaf } VISIT; +.fi \fR +.P +.RE +.P +(defined in +.IR ), +depending on whether this is the first, second, or third time that the +node is visited (during a depth-first, left-to-right traversal of the +tree), or whether the node is a leaf. The third argument shall be +the level of the node in the tree, with the root being level 0. +.P +If the calling function alters the pointer to the root, the result is +undefined. +.P +If the functions pointed to by +.IR action +or +.IR compar +(for any of these binary search functions) change the tree, the results +are undefined. +.P +These functions are thread-safe only as long as multiple threads +do not access the same tree. +.SH "RETURN VALUE" +If the node is found, both +\fItsearch\fR() +and +\fItfind\fR() +shall return a pointer to it. If not, +\fItfind\fR() +shall return a null pointer, and +\fItsearch\fR() +shall return a pointer to the inserted item. +.P +A null pointer shall be returned by +\fItsearch\fR() +if there is not enough space available to create a new node. +.P +A null pointer shall be returned by +\fItdelete\fR(), +\fItfind\fR(), +and +\fItsearch\fR() +if +.IR rootp +is a null pointer on entry. +.P +The +\fItdelete\fR() +function shall return a pointer to the parent of the deleted node, or +an unspecified non-null pointer if the deleted node was the root node, +or a null pointer if the node is not found. +.P +The +\fItwalk\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following code reads in strings and stores structures containing a +pointer to each string and a count of its length. It then walks the +tree, printing out the stored strings and their lengths in alphabetical +order. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +.P +#define STRSZ 10000 +#define NODSZ 500 +.P +struct node { /* Pointers to these are stored in the tree. */ + char *string; + int length; +}; +.P +char string_space[STRSZ]; /* Space to store strings. */ +struct node nodes[NODSZ]; /* Nodes to store. */ +void *root = NULL; /* This points to the root. */ +.P +int main(int argc, char *argv[]) +{ + char *strptr = string_space; + struct node *nodeptr = nodes; + void print_node(const void *, VISIT, int); + int i = 0, node_compare(const void *, const void *); +.P + while (gets(strptr) != NULL && i++ < NODSZ) { + /* Set node. */ + nodeptr\(mi>string = strptr; + nodeptr\(mi>length = strlen(strptr); + /* Put node into the tree. */ + (void) tsearch((void *)nodeptr, (void **)&root, + node_compare); + /* Adjust pointers, so we do not overwrite tree. */ + strptr += nodeptr\(mi>length + 1; + nodeptr++; + } + twalk(root, print_node); + return 0; +} +.P +/* + * This routine compares two nodes, based on an + * alphabetical ordering of the string field. + */ +int +node_compare(const void *node1, const void *node2) +{ + return strcmp(((const struct node *) node1)\(mi>string, + ((const struct node *) node2)\(mi>string); +} +.P +/* + * This routine prints out a node, the second time + * twalk encounters it or if it is a leaf. + */ +void +print_node(const void *ptr, VISIT order, int level) +{ + const struct node *p = *(const struct node **) ptr; +.P + if (order == postorder \(or\(or order == leaf) { + (void) printf("string = %s, length = %d\en", + p->string, p->length); + } +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +.IR root +argument to +\fItwalk\fR() +is one level of indirection less than the +.IR rootp +arguments to +\fItdelete\fR() +and +\fItsearch\fR(). +.P +There are two nomenclatures used to refer to the order in which tree +nodes are visited. The +\fItsearch\fR() +function uses \fBpreorder\fP, \fBpostorder\fP, and \fBendorder\fP to +refer respectively to visiting a node before any of its children, after +its left child and before its right, and after both its children. The +alternative nomenclature uses \fBpreorder\fP, \fBinorder\fP, and +\fBpostorder\fP to refer to the same visits, which could result in some +confusion over the meaning of \fBpostorder\fP. +.P +Since the return value of +\fItdelete\fR() +is an unspecified non-null pointer in the case that the root of the tree +has been deleted, applications should only use the return value of +\fItdelete\fR() +as indication of success or failure and should not assume it can be +dereferenced. Some implementations in this case will return a pointer to +the new root of the tree (or to an empty tree if the deleted root node +was the only node in the tree); other implementations return arbitrary +non-null pointers. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIhcreate\fR\^(\|)", +.IR "\fIlsearch\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/telldir.3p b/man-pages-posix-2013-a/man3p/telldir.3p new file mode 100644 index 0000000..9e7e3b7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/telldir.3p @@ -0,0 +1,73 @@ +'\" et +.TH TELLDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +telldir +\(em current location of a named directory stream +.SH SYNOPSIS +.LP +.nf +#include +.P +long telldir(DIR *\fIdirp\fP); +.fi +.SH DESCRIPTION +The +\fItelldir\fR() +function shall obtain the current location associated with the +directory stream specified by +.IR dirp . +.P +If the most recent operation on the directory stream was a +\fIseekdir\fR(), +the directory position returned from the +\fItelldir\fR() +shall be the same as that supplied as a +.IR loc +argument for +\fIseekdir\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fItelldir\fR() +shall return the current location of the specified directory stream. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIseekdir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tempnam.3p b/man-pages-posix-2013-a/man3p/tempnam.3p new file mode 100644 index 0000000..1b9c18e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tempnam.3p @@ -0,0 +1,148 @@ +'\" et +.TH TEMPNAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tempnam +\(em create a name for a temporary file +.SH SYNOPSIS +.LP +.nf +#include +.P +char *tempnam(const char *\fIdir\fP, const char *\fIpfx\fP); +.fi +.SH DESCRIPTION +The +\fItempnam\fR() +function shall generate a pathname that may be used for a temporary +file. +.P +The +\fItempnam\fR() +function allows the user to control the choice of a directory. The +.IR dir +argument points to the name of the directory in which the file is to be +created. If +.IR dir +is a null pointer or points to a string which is not a name for an +appropriate directory, the path prefix defined as P_tmpdir in the +.IR +header shall be used. If that directory is not accessible, an +implementation-defined directory may be used. +.P +Many applications prefer their temporary files to have certain initial +letter sequences in their names. The +.IR pfx +argument should be used for this. This argument may be a null pointer +or point to a string of up to five bytes to be used as the beginning of +the filename. +.P +Some implementations of +\fItempnam\fR() +may use +\fItmpnam\fR() +internally. On such implementations, if called more than +{TMP_MAX} +times in a single process, the behavior is implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, +\fItempnam\fR() +shall allocate space for a string, put the generated pathname in that +space, and return a pointer to it. The pointer shall be suitable for +use in a subsequent call to +\fIfree\fR(). +Otherwise, it shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fItempnam\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating a Pathname" +.P +The following example generates a pathname for a temporary file in +directory +.BR /tmp , +with the prefix +.IR file . +After the pathname has been created, the call to +\fIfree\fR() +deallocates the space used to store the pathname. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +const char *directory = "/tmp"; +const char *fileprefix = "file"; +char *file; +.P +file = tempnam(directory, fileprefix); +free(file); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +This function only creates pathnames. It is the application's +responsibility to create and remove the files. Between the time a +pathname is created and the file is opened, it is possible for some +other process to create a file with the same name. Applications may +find +\fItmpfile\fR() +more useful. +.P +Applications should use the +\fItmpfile\fR(), +\fImkdtemp\fR(), +or +\fImkstemp\fR() +functions instead of the obsolescent +\fItempnam\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fItempnam\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fItmpnam\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tfind.3p b/man-pages-posix-2013-a/man3p/tfind.3p new file mode 100644 index 0000000..21761dc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tfind.3p @@ -0,0 +1,39 @@ +'\" et +.TH TFIND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tfind +\(em search binary search tree +.SH SYNOPSIS +.LP +.nf +#include +.P +void *tfind(const void *\fIkey\fP, void *const *\fIrootp\fP, + int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItdelete\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tgamma.3p b/man-pages-posix-2013-a/man3p/tgamma.3p new file mode 100644 index 0000000..d49a6bc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tgamma.3p @@ -0,0 +1,244 @@ +'\" et +.TH TGAMMA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tgamma, +tgammaf, +tgammal +\(em compute gamma(\|) function +.SH SYNOPSIS +.LP +.nf +#include +.P +double tgamma(double \fIx\fP); +float tgammaf(float \fIx\fP); +long double tgammal(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the +.IR gamma +function of +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +.IR Gamma (\c +.IR x ). +.P +If +.IR x +is a negative integer, a +domain +error may occur and either a NaN (if supported) or an +implementation-defined value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur and a NaN shall be returned. +.P +If +.IR x +is \(+-0, +\fItgamma\fR(), +\fItgammaf\fR(), +and +\fItgammal\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, +respectively. +On systems that support the IEC 60559 Floating-Point option, a pole +error shall occur; +otherwise, a +pole +error may occur. +.P +If the correct value would cause overflow, a range error shall occur +and +\fItgamma\fR(), +\fItgammaf\fR(), +and +\fItgammal\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL, +respectively, with the same sign as the correct value of the function. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fItgamma\fR(), +\fItgammaf\fR(), +and +\fItgammal\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, and LDBL_MIN, +respectively. +.P +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If +.IR x +is \(miInf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is a negative integer, or +.IR x +is \(miInf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.br +.RE +.IP "Range\ Error" 12 +The value overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is a negative integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) +is non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For IEEE\ Std\ 754\(hy1985 +.BR double , +overflow happens when 0 < \fIx\fP < 1/DBL_MAX, and 171.7 < \fIx\fP. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +This function is named +\fItgamma\fR() +in order to avoid conflicts with the historical +.IR gamma (\|) +and +\fIlgamma\fR() +functions. +.SH "FUTURE DIRECTIONS" +It is possible that the error response for a negative integer argument +may be changed to a pole error and a return value of \(+-Inf. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlgamma\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/time.3p b/man-pages-posix-2013-a/man3p/time.3p new file mode 100644 index 0000000..cf2569d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/time.3p @@ -0,0 +1,207 @@ +'\" et +.TH TIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +time +\(em get time +.SH SYNOPSIS +.LP +.nf +#include +.P +time_t time(time_t *\fItloc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fItime\fR() +function shall return the value of time +in seconds since the Epoch. +.P +The +.IR tloc +argument points to an area where the return value is also stored. If +.IR tloc +is a null pointer, no value is stored. +.SH "RETURN VALUE" +Upon successful completion, +\fItime\fR() +shall return the value of time. Otherwise, (\fBtime_t\fP)\(mi1 shall be +returned. +.SH ERRORS +The +\fItime\fR() +function may fail if: +.TP +.BR EOVERFLOW +The number of seconds since the Epoch will not fit in an object of type +.BR time_t . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the Current Time" +.P +The following example uses the +\fItime\fR() +function to calculate the time elapsed, in seconds, since the Epoch, +\fIlocaltime\fR() +to convert that value to a broken-down time, and +\fIasctime\fR() +to convert the broken-down time values into a printable string. +.sp +.RS 4 +.nf +\fB +#include +#include +.P +int main(void) +{ +time_t result; +.P + result = time(NULL); + printf("%s%ju secs since the Epoch\en", + asctime(localtime(&result)), + (uintmax_t)result); + return(0); +} +.fi \fR +.P +.RE +.P +This example writes the current time to +.IR stdout +in a form like this: +.sp +.RS 4 +.nf +\fB +Wed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +.fi \fR +.P +.RE +.SS "Timing an Event" +.P +The following example gets the current time, prints it out in the +user's format, and prints the number of minutes to an event being +timed. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +minutes_to_event = ...; +printf("The time is "); +puts(asctime(localtime(&now))); +printf("There are %d minutes to the event.\en", + minutes_to_event); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fItime\fR() +function returns a value in seconds while +\fIclock_gettime\fR() +and +\fIgettimeofday\fR() +return a +.BR "struct timespec" +(seconds and nanoseconds) and +.BR "struct timeval" +(seconds and microseconds), respectively, and are therefore capable of +returning more precise times. The +\fItimes\fR() +function is also capable of more precision than +\fItime\fR() +as it returns a value in clock ticks, although it returns the elapsed time +since an arbitrary point such as system boot time, not since the epoch. +.P +Implementations in which +.BR time_t +is a 32-bit signed integer (many historical implementations) fail in +the year 2038. POSIX.1\(hy2008 does not address this problem. However, the use +of the +.BR time_t +type is mandated in order to ease the eventual fix. +.P +On some systems the +\fItime\fR() +function is implemented using a system call that does not return an +error condition in addition to the return value. On these systems it is +impossible to differentiate between valid and invalid return values and +hence overflow conditions cannot be reliably detected. +.P +The use of the +.IR +header instead of +.IR +allows compatibility with the ISO\ C standard. +.P +Many historical implementations (including Version 7) and the 1984 /usr/group standard use +.BR long +instead of +.BR time_t . +This volume of POSIX.1\(hy2008 uses the latter type in order to agree with the ISO\ C standard. +.SH "FUTURE DIRECTIONS" +In a future version of this volume of POSIX.1\(hy2008, +.BR time_t +is likely to be required to be capable of representing times far in the +future. Whether this will be mandated as a 64-bit type or a requirement +that a specific date in the future be representable (for example, 10000 +AD) is not yet determined. Systems purchased after the approval of this volume of POSIX.1\(hy2008 +should be evaluated to determine whether their lifetime will extend +past 2038. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)", +.IR "\fIgettimeofday\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/timer_create.3p b/man-pages-posix-2013-a/man3p/timer_create.3p new file mode 100644 index 0000000..b0e7cb6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/timer_create.3p @@ -0,0 +1,263 @@ +'\" et +.TH TIMER_CREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +timer_create +\(em create a per-process timer +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int timer_create(clockid_t \fIclockid\fP, struct sigevent *restrict \fIevp\fP, + timer_t *restrict \fItimerid\fP); +.fi +.SH DESCRIPTION +The +\fItimer_create\fR() +function shall create a per-process timer using the specified clock, +.IR clock_id , +as the timing base. The +\fItimer_create\fR() +function shall return, in the location referenced by +.IR timerid , +a timer ID of type +.BR timer_t +used to identify the timer in timer requests. This timer ID shall be +unique within the calling process until the timer is deleted. The +particular clock, +.IR clock_id , +is defined in +.IR . +The timer whose ID is returned shall be in a disarmed state upon return +from +\fItimer_create\fR(). +.P +The +.IR evp +argument, if non-NULL, points to a +.BR sigevent +structure. This structure, allocated by the application, defines the +asynchronous notification to occur as specified in +.IR "Section 2.4.1" ", " "Signal Generation and Delivery" +when the timer expires. If the +.IR evp +argument is NULL, the effect is as if the +.IR evp +argument pointed to a +.BR sigevent +structure with the +.IR sigev_notify +member having the value SIGEV_SIGNAL, the +.IR sigev_signo +having a default signal number, and the +.IR sigev_value +member having the value of the timer ID. +.P +Each implementation shall define a set of clocks that can be used as +timing bases for per-process timers. All implementations shall support a +.IR clock_id +of CLOCK_REALTIME. +If the Monotonic Clock option is supported, implementations shall +support a +.IR clock_id +of CLOCK_MONOTONIC. +.P +Per-process timers shall not be inherited by a child process across a +\fIfork\fR() +and shall be disarmed and deleted by an +.IR exec . +.P +If _POSIX_CPUTIME is defined, implementations shall support +.IR clock_id +values representing the CPU-time clock of the calling process. +.P +If _POSIX_THREAD_CPUTIME is defined, implementations shall support +.IR clock_id +values representing the CPU-time clock of the calling thread. +.P +It is implementation-defined whether a +\fItimer_create\fR() +function will succeed if the value defined by +.IR clock_id +corresponds to the CPU-time clock of a process or thread different from +the process or thread invoking the function. +.P +If \fIevp\fR\->\fIsigev_sigev_notify\fR is SIGEV_THREAD and +\fIsev\fR\->\fIsigev_notify_attributes\fR is not NULL, if the attribute +pointed to by \fIsev\fR\->\fIsigev_notify_attributes\fR has a thread +stack address specified by a call to +\fIpthread_attr_setstack\fR(), +the results are unspecified if the signal is generated more than once. +.SH "RETURN VALUE" +If the call succeeds, +\fItimer_create\fR() +shall return zero and update the location referenced by +.IR timerid +to a +.BR timer_t , +which can be passed to the per-process timer calls. If an error +occurs, the function shall return a value of \(mi1 and set +.IR errno +to indicate the error. The value of +.IR timerid +is undefined if an error occurs. +.SH ERRORS +The +\fItimer_create\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacks sufficient signal queuing resources to honor the +request. +.TP +.BR EAGAIN +The calling process has already created all of the timers it is allowed +by this implementation. +.TP +.BR EINVAL +The specified clock ID is not defined. +.TP +.BR ENOTSUP +The implementation does not support the creation of a timer attached to +the CPU-time clock that is specified by +.IR clock_id +and associated with a process or thread different from the process or +thread invoking +\fItimer_create\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If a timer is created which has \fIevp\fR\->\fIsigev_sigev_notify\fR +set to SIGEV_THREAD and the attribute pointed to by +\fIevp\fR\->\fIsigev_notify_attributes\fR has a thread stack address +specified by a call to +\fIpthread_attr_setstack\fR(), +the memory dedicated as a thread stack cannot be recovered. The reason +for this is that the threads created in response to a timer expiration +are created detached, or in an unspecified way if the thread +attribute's +.IR detachstate +is PTHREAD_CREATE_JOINABLE. In neither case is it valid to call +\fIpthread_join\fR(), +which makes it impossible to determine the lifetime of the created +thread which thus means the stack memory cannot be reused. +.br +.SH RATIONALE +.SS "Periodic Timer Overrun and Resource Allocation" +.P +The specified timer facilities may deliver realtime signals (that is, +queued signals) on implementations that support this option. Since +realtime applications cannot afford to lose notifications of +asynchronous events, like timer expirations or asynchronous I/O +completions, it must be possible to ensure that sufficient resources +exist to deliver the signal when the event occurs. In general, this is +not a difficulty because there is a one-to-one correspondence between a +request and a subsequent signal generation. If the request cannot +allocate the signal delivery resources, it can fail the call with an +.BR [EAGAIN] +error. +.P +Periodic timers are a special case. A single request can generate an +unspecified number of signals. This is not a problem if the +requesting process can service the signals as fast as they are +generated, thus making the signal delivery resources available for +delivery of subsequent periodic timer expiration signals. But, in +general, this cannot be assured\(emprocessing of periodic timer signals +may ``overrun''; that is, subsequent periodic timer expirations may +occur before the currently pending signal has been delivered. +.P +Also, for signals, according to the POSIX.1\(hy1990 standard, if subsequent occurrences of +a pending signal are generated, it is implementation-defined whether +a signal is delivered for each occurrence. This is not adequate for +some realtime applications. So a mechanism is required to allow +applications to detect how many timer expirations were delayed without +requiring an indefinite amount of system resources to store the delayed +expirations. +.P +The specified facilities provide for an overrun count. The overrun +count is defined as the number of extra timer expirations that occurred +between the time a timer expiration signal is generated and the time +the signal is delivered. The signal-catching function, if it is +concerned with overruns, can retrieve this count on entry. With this +method, a periodic timer only needs one ``signal queuing resource'' +that can be allocated at the time of the +\fItimer_create\fR() +function call. +.P +A function is defined to retrieve the overrun count so that an +application need not allocate static storage to contain the count, and +an implementation need not update this storage asynchronously on timer +expirations. But, for some high-frequency periodic applications, the +overhead of an additional system call on each timer expiration may be +prohibitive. The functions, as defined, permit an implementation to +maintain the overrun count in user space, associated with the +.IR timerid . +The +\fItimer_getoverrun\fR() +function can then be implemented as a macro that uses the +.IR timerid +argument (which may just be a pointer to a user space structure +containing the counter) to locate the overrun count with no system call +overhead. Other implementations, less concerned with this class of +applications, can avoid the asynchronous update of user space by +maintaining the count in a system structure at the cost of the extra +system call to obtain it. +.SS "Timer Expiration Signal Parameters" +.P +The Realtime Signals Extension option supports an application-specific +datum that is delivered to the extended signal handler. This value is +explicitly specified by the application, along with the signal number +to be delivered, in a +.BR sigevent +structure. The type of the application-defined value can be either an +integer constant or a pointer. This explicit specification of the +value, as opposed to always sending the +timer ID, was selected based on existing practice. +.P +It is common practice for realtime applications (on non-POSIX systems +or realtime extended POSIX systems) to use the parameters of event +handlers as the case label of a switch statement or as a pointer to an +application-defined data structure. Since +.IR timer_id s +are dynamically allocated by the +\fItimer_create\fR() +function, they can be used for neither of these functions without +additional application overhead in the signal handler; for example, to +search an array of saved timer IDs to associate the ID with a constant +or application data structure. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_delete\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/timer_delete.3p b/man-pages-posix-2013-a/man3p/timer_delete.3p new file mode 100644 index 0000000..125c23f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/timer_delete.3p @@ -0,0 +1,78 @@ +'\" et +.TH TIMER_DELETE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +timer_delete +\(em delete a per-process timer +.SH SYNOPSIS +.LP +.nf +#include +.P +int timer_delete(timer_t \fItimerid\fP); +.fi +.SH DESCRIPTION +The +\fItimer_delete\fR() +function deletes the specified timer, +.IR timerid , +previously created by the +\fItimer_create\fR() +function. If the timer is armed when +\fItimer_delete\fR() +is called, the behavior shall be as if the timer is automatically +disarmed before removal. The disposition of pending signals for the +deleted timer is unspecified. +.SH "RETURN VALUE" +If successful, the +\fItimer_delete\fR() +function shall return a value of zero. Otherwise, the function shall +return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fItimer_delete\fR() +function may fail if: +.TP +.BR EINVAL +The timer ID specified by +.IR timerid +is not a valid timer ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/timer_getoverrun.3p b/man-pages-posix-2013-a/man3p/timer_getoverrun.3p new file mode 100644 index 0000000..d2835f6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/timer_getoverrun.3p @@ -0,0 +1,256 @@ +'\" et +.TH TIMER_GETOVERRUN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +timer_getoverrun, +timer_gettime, +timer_settime +\(em per-process timers +.SH SYNOPSIS +.LP +.nf +#include +.P +int timer_getoverrun(timer_t \fItimerid\fP); +int timer_gettime(timer_t \fItimerid\fP, struct itimerspec *\fIvalue\fP); +int timer_settime(timer_t \fItimerid\fP, int \fIflags\fP, + const struct itimerspec *restrict \fIvalue\fP, + struct itimerspec *restrict \fIovalue\fP); +.fi +.SH DESCRIPTION +The +\fItimer_gettime\fR() +function shall store the amount of time until the specified timer, +.IR timerid , +expires and the reload value of the timer into the space pointed to by +the +.IR value +argument. The +.IR it_value +member of this structure shall contain the amount of time before the timer +expires, or zero if the timer is disarmed. This value is returned as +the interval until timer expiration, even if the timer was armed with +absolute time. The +.IR it_interval +member of +.IR value +shall contain the reload value last set by +\fItimer_settime\fR(). +.P +The +\fItimer_settime\fR() +function shall set the time until the next expiration of the timer +specified by +.IR timerid +from the +.IR it_value +member of the +.IR value +argument and arm the timer if the +.IR it_value +member of +.IR value +is non-zero. If the specified timer was already armed when +\fItimer_settime\fR() +is called, this call shall reset the time until next expiration to the +.IR value +specified. If the +.IR it_value +member of +.IR value +is zero, the timer shall be disarmed. The effect of disarming or +resetting a timer with pending expiration notifications is unspecified. +.P +If the flag TIMER_ABSTIME is not set in the argument +.IR flags , +\fItimer_settime\fR() +shall behave as if the time until next expiration is set to be equal +to the interval specified by the +.IR it_value +member of +.IR value . +That is, the timer shall expire in +.IR it_value +nanoseconds from when the call is made. If the flag TIMER_ABSTIME is +set in the argument +.IR flags , +\fItimer_settime\fR() +shall behave as if the time until next expiration is set to be equal +to the difference between the absolute time specified by the +.IR it_value +member of +.IR value +and the current value of the clock associated with +.IR timerid . +That is, the timer shall expire when the clock reaches the value +specified by the +.IR it_value +member of +.IR value . +If the specified time has already passed, the function shall succeed +and the expiration notification shall be made. +.P +The reload value of the timer shall be set to the value specified by the +.IR it_interval +member of +.IR value . +When a timer is armed with a non-zero +.IR it_interval , +a periodic (or repetitive) timer is specified. +.P +Time values that are between two consecutive non-negative integer +multiples of the resolution of the specified timer shall be rounded up +to the larger multiple of the resolution. Quantization error shall not +cause the timer to expire earlier than the rounded time value. +.P +If the argument +.IR ovalue +is not NULL, the +\fItimer_settime\fR() +function shall store, in the location referenced by +.IR ovalue , +a value representing the previous amount of time before the timer would +have expired, or zero if the timer was disarmed, together with the +previous timer reload value. Timers shall not expire before their +scheduled time. +.P +Only a single signal shall be queued to the process for a given timer +at any point in time. When a timer for which a signal is still pending +expires, no signal shall be queued, and a timer overrun shall occur. +When a timer expiration signal is delivered to or accepted by a +process, the +\fItimer_getoverrun\fR() +function shall return the timer expiration overrun count for the +specified timer. The overrun count returned contains the number of +extra timer expirations that occurred between the time the signal was +generated (queued) and when it was delivered or accepted, up to but not +including an implementation-defined maximum of +{DELAYTIMER_MAX}. +If the number of such extra expirations is greater than or equal to +{DELAYTIMER_MAX}, +then the overrun count shall be set to +{DELAYTIMER_MAX}. +The value returned by +\fItimer_getoverrun\fR() +shall apply to the most recent expiration signal delivery or acceptance +for the timer. If no expiration signal has been delivered for the timer, +the return value of +\fItimer_getoverrun\fR() +is unspecified. +.SH "RETURN VALUE" +If the +\fItimer_getoverrun\fR() +function succeeds, it shall return the timer expiration overrun count +as explained above. +.P +If the +\fItimer_gettime\fR() +or +\fItimer_settime\fR() +functions succeed, a value of 0 shall be returned. +.P +If an error occurs for any of these functions, the value \(mi1 shall be +returned, and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItimer_settime\fR() +function shall fail if: +.TP +.BR EINVAL +A +.IR value +structure specified a nanosecond value less than zero or greater than +or equal to 1\|000 million, and the +.IR it_value +member of that structure did not specify zero seconds and nanoseconds. +.P +These functions may fail if: +.TP +.BR EINVAL +The +.IR timerid +argument does not correspond to an ID returned by +\fItimer_create\fR() +but not yet deleted by +\fItimer_delete\fR(). +.P +The +\fItimer_settime\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR it_interval +member of +.IR value +is not zero and the timer was created with notification by creation of +a new thread (\c +.IR sigev_sigev_notify +was SIGEV_THREAD) and a fixed stack address has been set in the thread +attribute pointed to by +.IR sigev_notify_attributes . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Using fixed stack addresses is problematic when timer expiration is +signaled by the creation of a new thread. Since it cannot be assumed +that the thread created for one expiration is finished before the next +expiration of the timer, it could happen that two threads use the same +memory as a stack at the same time. This is invalid and produces +undefined results. +.SH RATIONALE +Practical clocks tick at a finite rate, with rates of 100 hertz and +1\|000 hertz being common. The inverse of this tick rate is the clock +resolution, also called the clock granularity, which in either case is +expressed as a time duration, being 10 milliseconds and 1 millisecond +respectively for these common rates. The granularity of practical +clocks implies that if one reads a given clock twice in rapid +succession, one may get the same time value twice; and that timers must +wait for the next clock tick after the theoretical expiration time, to +ensure that a timer never returns too soon. Note also that the +granularity of the clock may be significantly coarser than the +resolution of the data format used to set and get time and interval +values. Also note that some implementations may choose to adjust time +and/or interval values to exactly match the ticks of the underlying +clock. +.P +This volume of POSIX.1\(hy2008 defines functions that allow an application to determine +the implementation-supported resolution for the clocks and requires an +implementation to document the resolution supported for timers and +\fInanosleep\fR() +if they differ from the supported clock resolution. This is more of a +procurement issue than a runtime application issue. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/times.3p b/man-pages-posix-2013-a/man3p/times.3p new file mode 100644 index 0000000..9d5754b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/times.3p @@ -0,0 +1,206 @@ +'\" et +.TH TIMES "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +times +\(em get process and waited-for child process times +.SH SYNOPSIS +.LP +.nf +#include +.P +clock_t times(struct tms *\fIbuffer\fP); +.fi +.SH DESCRIPTION +The +\fItimes\fR() +function shall fill the +.BR tms +structure pointed to by +.IR buffer +with time-accounting information. The +.BR tms +structure is defined in +.IR . +.P +All times are measured in terms of the number of clock ticks used. +.P +The times of a terminated child process shall be included in the +.IR tms_cutime +and +.IR tms_cstime +elements of the parent when +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +returns the process ID of this terminated child. If a child process +has not waited for its children, their times shall not be included in +its times. +.IP " *" 4 +The +.IR tms_utime +structure member is the CPU time charged for the execution of user +instructions of the calling process. +.IP " *" 4 +The +.IR tms_stime +structure member is the CPU time charged for execution by the system on +behalf of the calling process. +.IP " *" 4 +The +.IR tms_cutime +structure member is the sum of the +.IR tms_utime +and +.IR tms_cutime +times of the child processes. +.IP " *" 4 +The +.IR tms_cstime +structure member is the sum of the +.IR tms_stime +and +.IR tms_cstime +times of the child processes. +.SH "RETURN VALUE" +Upon successful completion, +\fItimes\fR() +shall return the elapsed real time, in clock ticks, since an arbitrary +point in the past (for example, system start-up time). This point does +not change from one invocation of +\fItimes\fR() +within the process to another. The return value may overflow the +possible range of type +.BR clock_t . +If +\fItimes\fR() +fails, (\fBclock_t\fR)\(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Timing a Database Lookup" +.P +The following example defines two functions, +\fIstart_clock\fR() +and +\fIend_clock\fR(), +that are used to time a lookup. It also defines variables of type +.BR clock_t +and +.BR tms +to measure the duration of transactions. The +\fIstart_clock\fR() +function saves the beginning times given by the +\fItimes\fR() +function. The +\fIend_clock\fR() +function gets the ending times and prints the difference between the +two times. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +void start_clock(void); +void end_clock(char *msg); +\&... +static clock_t st_time; +static clock_t en_time; +static struct tms st_cpu; +static struct tms en_cpu; +\&... +void +start_clock() +{ + st_time = times(&st_cpu); +} +.P +/* This example assumes that the result of each subtraction + is within the range of values that can be represented in + an integer type. */ +void +end_clock(char *msg) +{ + en_time = times(&en_cpu); +.P + fputs(msg,stdout); + printf("Real Time: %jd, User Time %jd, System Time %jd\en", + (intmax_t)(en_time - st_time), + (intmax_t)(en_cpu.tms_utime - st_cpu.tms_utime), + (intmax_t)(en_cpu.tms_stime - st_cpu.tms_stime)); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Applications should use \fIsysconf\fP(_SC_CLK_TCK) +to determine the number of clock ticks per second as it may vary from +system to system. +.SH RATIONALE +The accuracy of the times reported is intentionally left unspecified to +allow implementations flexibility in design, from uniprocessor to +multi-processor networks. +.P +The inclusion of times of child processes is recursive, so that a +parent process may collect the total times of all of its descendants. +But the times of a child are only added to those of its parent when its +parent successfully waits on the child. Thus, it is not guaranteed +that a parent process can always see the total times of all its +descendants; see also the discussion of the term ``realtime'' in +.IR "\fIalarm\fR\^(\|)". +.P +If the type +.BR clock_t +is defined to be a signed 32-bit integer, it overflows in somewhat more +than a year if there are 60 clock ticks per second, +or less than a year if there are 100. There are individual systems +that run continuously for longer than that. This volume of POSIX.1\(hy2008 permits an +implementation to make the reference point for the returned value be +the start-up time of the process, rather than system start-up time. +.P +The term ``charge'' in this context has nothing to do with billing +for services. The operating system accounts for time used in this +way. That information must be correct, regardless of how that +information is used. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/timezone.3p b/man-pages-posix-2013-a/man3p/timezone.3p new file mode 100644 index 0000000..75869fc --- /dev/null +++ b/man-pages-posix-2013-a/man3p/timezone.3p @@ -0,0 +1,38 @@ +'\" et +.TH TIMEZONE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +timezone +\(em difference from UTC and local standard time +.SH SYNOPSIS +.LP +.nf +#include +.P +extern long timezone; +.fi +.SH DESCRIPTION +Refer to +.IR "\fItzset\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tmpfile.3p b/man-pages-posix-2013-a/man3p/tmpfile.3p new file mode 100644 index 0000000..df140db --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tmpfile.3p @@ -0,0 +1,150 @@ +'\" et +.TH TMPFILE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tmpfile +\(em create a temporary file +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *tmpfile(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fItmpfile\fR() +function shall create a temporary file and open a corresponding +stream. The file shall be automatically deleted when all references +to the file are closed. The file is opened as in +\fIfopen\fR() +for update (\fIw\fP+), except that implementations may restrict the +permissions, either by clearing the file mode bits or setting them +to the value S_IRUSR | S_IWUSR. +.P +In some implementations, a permanent file may be left behind if +the process calling +\fItmpfile\fR() +is killed while it is processing a call to +\fItmpfile\fR(). +.P +An error message may be written to standard error if the stream cannot +be opened. +.SH "RETURN VALUE" +Upon successful completion, +\fItmpfile\fR() +shall return a pointer to the stream of the file that is created. +Otherwise, it shall return a null pointer +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fItmpfile\fR() +function shall fail if: +.TP +.BR EINTR +A signal was caught during +\fItmpfile\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOSPC +The directory or file system which would contain the new file cannot be +expanded. +.TP +.BR EOVERFLOW +The file is a regular file and the size of the file cannot be +represented correctly in an object of type +.BR off_t . +.P +The +\fItmpfile\fR() +function may fail if: +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a Temporary File" +.P +The following example creates a temporary file for update, and returns +a pointer to a stream for the created file in the +.IR fp +variable. +.sp +.RS 4 +.nf +\fB +#include +\&... +FILE *fp; +.P +fp = tmpfile (); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +It should be possible to open at least +{TMP_MAX} +temporary files during the lifetime of the program (this limit may be +shared with +\fItmpnam\fR()) +and there should be no limit on the number simultaneously open other +than this limit and any limit on the number of open file descriptors +or streams (\c +{OPEN_MAX}, +{FOPEN_MAX}, +{STREAM_MAX}). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fItmpnam\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tmpnam.3p b/man-pages-posix-2013-a/man3p/tmpnam.3p new file mode 100644 index 0000000..3978390 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tmpnam.3p @@ -0,0 +1,146 @@ +'\" et +.TH TMPNAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tmpnam +\(em create a name for a temporary file +.SH SYNOPSIS +.LP +.nf +#include +.P +char *tmpnam(char *\fIs\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fItmpnam\fR() +function shall generate a string that is a valid pathname that does not +name an existing file. The function is potentially capable of generating +{TMP_MAX} +different strings, but any or all of them may already be in use by +existing files and thus not be suitable return values. +.P +The +\fItmpnam\fR() +function generates a different string each time it is called from the +same process, up to +{TMP_MAX} +times. If it is called more than +{TMP_MAX} +times, the behavior is implementation-defined. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008, +except +\fItempnam\fR(), +calls +\fItmpnam\fR(). +.P +The +\fItmpnam\fR() +function need not be thread-safe if called with a NULL parameter. +.SH "RETURN VALUE" +Upon successful completion, +\fItmpnam\fR() +shall return a pointer to a string. If no suitable string can be +generated, the +\fItmpnam\fR() +function shall return a null pointer. +.P +If the argument +.IR s +is a null pointer, +\fItmpnam\fR() +shall leave its result in an internal static object and return a +pointer to that object. Subsequent calls to +\fItmpnam\fR() +may modify the same object. If the argument +.IR s +is not a null pointer, it is presumed to point to an array of at least +L_tmpnam +.BR char s; +\fItmpnam\fR() +shall write its result in that array and shall return the argument +as its value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating a Pathname" +.P +The following example generates a unique pathname and stores it in the +array pointed to by +.IR ptr . +.sp +.RS 4 +.nf +\fB +#include +\&... +char pathname[L_tmpnam+1]; +char *ptr; +.P +ptr = tmpnam(pathname); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +This function only creates pathnames. It is the application's +responsibility to create and remove the files. +.P +Between the time a pathname is created and the file is opened, it is +possible for some other process to create a file with the same name. +Applications may find +\fItmpfile\fR() +more useful. +.P +Applications should use the +\fItmpfile\fR(), +\fImkstemp\fR(), +or +\fImkdtemp\fR() +functions instead of the obsolescent +\fItmpnam\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fItmpnam\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfopen\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fItempnam\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/toascii.3p b/man-pages-posix-2013-a/man3p/toascii.3p new file mode 100644 index 0000000..968abd8 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/toascii.3p @@ -0,0 +1,64 @@ +'\" et +.TH TOASCII "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +toascii +\(em translate an integer to a 7-bit ASCII character +.SH SYNOPSIS +.LP +.nf +#include +.P +int toascii(int \fIc\fP); +.fi +.SH DESCRIPTION +The +\fItoascii\fR() +function shall convert its argument into a 7-bit ASCII character. +.SH "RETURN VALUE" +The +\fItoascii\fR() +function shall return the value (\fIc\fP &0x7f). +.SH ERRORS +No errors are returned. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fItoascii\fR() +function cannot be used portably in a localized application. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fItoascii\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIisascii\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tolower.3p b/man-pages-posix-2013-a/man3p/tolower.3p new file mode 100644 index 0000000..2a60c6e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tolower.3p @@ -0,0 +1,100 @@ +'\" et +.TH TOLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tolower, +tolower_l +\(em transliterate uppercase characters to lowercase +.SH SYNOPSIS +.LP +.nf +#include +.P +int tolower(int \fIc\fP); +int tolower_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItolower\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fItolower\fR() +and +\fItolower_l\fR() +functions have as a domain a type +.BR int , +the value of which is representable as an +.BR "unsigned char" +or the value of EOF. If the argument has any other value, the behavior +is undefined. If the argument of +\fItolower\fR() +or +\fItolower_l\fR() +represents an uppercase letter, and there exists a corresponding +lowercase letter as defined by character type information in the current +locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ), +the result shall be the corresponding lowercase letter. All other +arguments in the domain are returned unchanged. +.P +The behavior is undefined if the +.IR locale +argument to +\fItolower_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, the +\fItolower\fR() +and +\fItolower_l\fR() +functions shall return the lowercase letter corresponding to the +argument passed; otherwise, they shall return the argument unchanged. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/toupper.3p b/man-pages-posix-2013-a/man3p/toupper.3p new file mode 100644 index 0000000..fbe3281 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/toupper.3p @@ -0,0 +1,103 @@ +'\" et +.TH TOUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +toupper, +toupper_l +\(em transliterate lowercase characters to uppercase +.SH SYNOPSIS +.LP +.nf +#include +.P +int toupper(int \fIc\fP); +int toupper_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItoupper\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fItoupper\fR() +and +\fItoupper_l\fR() +functions have as a domain a type +.BR int , +the value of which is representable as an +.BR "unsigned char" +or the value of EOF. If the argument has any other value, the behavior +is undefined. +.P +If the argument of +\fItoupper\fR() +or +\fItoupper_l\fR() +represents a lowercase letter, and there exists a corresponding +uppercase letter as defined by character type information in the current +locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ), +the result shall be the corresponding uppercase letter. +.P +All other arguments in the domain are returned unchanged. +.P +The behavior is undefined if the +.IR locale +argument to +\fItoupper_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, +\fItoupper\fR() +and +\fItoupper_l\fR() +shall return the uppercase letter corresponding to the argument +passed; otherwise, they shall return the argument unchanged. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/towctrans.3p b/man-pages-posix-2013-a/man3p/towctrans.3p new file mode 100644 index 0000000..8fbd912 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/towctrans.3p @@ -0,0 +1,155 @@ +'\" et +.TH TOWCTRANS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +towctrans, +towctrans_l +\(em wide-character transliteration +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t towctrans(wint_t \fIwc\fP, wctrans_t \fIdesc\fP); +wint_t towctrans_l(wint_t \fIwc\fP, wctrans_t \fIdesc\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItowctrans\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fItowctrans\fR() +and +\fItowctrans_l\fR() +functions shall transliterate the wide-character code +.IR wc +using the mapping described by +.IR desc . +.P +The current setting of the +.IR LC_CTYPE +category in the current locale +or in the locale represented by +.IR locale , +respectively, should be the same as during the call to +\fIwctrans\fR() +or +\fIwctrans_l\fR() +that returned the value +.IR desc . +.P +If the value of +.IR desc +is invalid (that is, not obtained by a call to +\fIwctrans\fR() +or +.IR desc +is invalidated by a subsequent call to +\fIsetlocale\fR() +that has affected category +.IR LC_CTYPE ), +the result is unspecified. +.P +If the value of +.IR desc +is invalid (that is, not obtained by a call to +\fIwctrans_l\fR() +with the same locale object +.IR locale ) +the result is unspecified. +.P +An application wishing to check for error situations should set +.IR errno +to 0 before calling +\fItowctrans\fR() +or +\fItowctrans_l\fR(). +.P +If +.IR errno +is non-zero on return, an error has occurred. +.P +The behavior is undefined if the +.IR locale +argument to +\fItowctrans_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +If successful, the +\fItowctrans\fR() +and +\fItowctrans_l\fR() +functions shall return the mapped value of +.IR wc +using the mapping described by +.IR desc . +Otherwise, they shall return +.IR wc +unchanged. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +.IR desc +contains an invalid transliteration descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The strings +.BR \(dqtolower\(dq +and +.BR \(dqtoupper\(dq +are reserved for the standard mapping names. In the table below, the +functions in the left column are equivalent to the functions in the +right column. +.sp +.RS 4 +.nf +\fB +towlower(\fIwc\fP) towctrans(\fIwc\fP, wctrans("tolower")) +towlower_l(\fIwc\fP, \fIlocale\fP) towctrans_l(\fIwc\fP, wctrans("tolower"), \fIlocale\fP) +towupper(\fIwc\fP) towctrans(\fIwc\fP, wctrans("toupper")) +towupper_l(\fIwc\fP, \fIlocale\fP) towctrans_l(\fIwc\fP, wctrans("toupper"), \fIlocale\fP) +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItowlower\fR\^(\|)", +.IR "\fItowupper\fR\^(\|)", +.IR "\fIwctrans\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/towlower.3p b/man-pages-posix-2013-a/man3p/towlower.3p new file mode 100644 index 0000000..8dff90b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/towlower.3p @@ -0,0 +1,103 @@ +'\" et +.TH TOWLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +towlower, +towlower_l +\(em transliterate uppercase wide-character code to lowercase +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t towlower(wint_t \fIwc\fP); +wint_t towlower_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItowlower\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fItowlower\fR() +and +\fItowlower_l\fR() +functions have as a domain a type +.BR wint_t , +the value of which the application shall ensure is a character +representable as a +.BR wchar_t , +and a wide-character code corresponding to a valid character in the +current locale or the value of WEOF. +If the argument has any other value, the behavior is undefined. +If the argument of +\fItowlower\fR() +or +\fItowlower_l\fR() +represents an uppercase wide-character code, and there exists a +corresponding lowercase wide-character code as defined by character +type information in the current locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ), +the result shall be the corresponding lowercase wide-character code. +All other arguments in the domain are returned unchanged. +.P +The behavior is undefined if the +.IR locale +argument to +\fItowlower_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, the +\fItowlower\fR() +and +\fItowlower_l\fR() +functions shall return the lowercase letter corresponding to the +argument passed; otherwise, they shall return the argument unchanged. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/towupper.3p b/man-pages-posix-2013-a/man3p/towupper.3p new file mode 100644 index 0000000..93fd334 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/towupper.3p @@ -0,0 +1,103 @@ +'\" et +.TH TOWUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +towupper, +towupper_l +\(em transliterate lowercase wide-character code to uppercase +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t towupper(wint_t \fIwc\fP); +wint_t towupper_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItowupper\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fItowupper\fR() +and +\fItowupper_l\fR() +functions have as a domain a type +.BR wint_t , +the value of which the application shall ensure is a character +representable as a +.BR wchar_t , +and a wide-character code corresponding to a valid character in the +current locale or the value of WEOF. +If the argument has any other value, the behavior is undefined. +If the argument of +\fItowupper\fR() +or +\fItowupper_l\fR() +represents a lowercase wide-character code, and there exists a +corresponding uppercase wide-character code as defined by character +type information in the current locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ), +the result shall be the corresponding uppercase wide-character code. +All other arguments in the domain are returned unchanged. +.P +The behavior is undefined if the +.IR locale +argument to +\fItowupper_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, the +\fItowupper\fR() +and +\fItowupper_l\fR() +functions shall return the uppercase letter corresponding to the +argument passed. Otherwise, they shall return the argument unchanged. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/trunc.3p b/man-pages-posix-2013-a/man3p/trunc.3p new file mode 100644 index 0000000..3a7d42a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/trunc.3p @@ -0,0 +1,85 @@ +'\" et +.TH TRUNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +trunc, +truncf, +truncl +\(em round to truncated integer value +.SH SYNOPSIS +.LP +.nf +#include +.P +double trunc(double \fIx\fP); +float truncf(float \fIx\fP); +long double truncl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall round their argument to the integer value, in +floating format, nearest to but no larger in magnitude than the +argument. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the truncated +integer value. +.br \" without this, margin code is on the line above +The result shall have the same sign as +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer type +to avoid the undefined results of an integer overflow. +.P +These functions may raise the inexact floating-point exception if the +result differs in value from the argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/truncate.3p b/man-pages-posix-2013-a/man3p/truncate.3p new file mode 100644 index 0000000..fe2b406 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/truncate.3p @@ -0,0 +1,167 @@ +'\" et +.TH TRUNCATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +truncate +\(em truncate a file to a specified length +.SH SYNOPSIS +.LP +.nf +#include +.P +int truncate(const char *\fIpath\fP, off_t \fIlength\fP); +.fi +.SH DESCRIPTION +The +\fItruncate\fR() +function shall cause the regular file named by +.IR path +to have a size which shall be equal to +.IR length +bytes. +.P +If the file previously was larger than +.IR length , +the extra data is discarded. If the file was previously shorter than +.IR length , +its size is increased, and the extended area appears as if it were +zero-filled. +.P +The application shall ensure that the process has write permission for +the file. +.P +If the request would cause the file size to exceed the soft file size +limit for the process, the request shall fail and the implementation +shall generate the SIGXFSZ signal for the process. +.P +The +\fItruncate\fR() +function shall not modify the file offset for any open file descriptions +associated with the file. Upon successful completion, if the file size +is changed, +\fItruncate\fR() +shall mark for update the last data modification and last file status +change timestamps of the file, and the S_ISUID and S_ISGID bits of the +file mode may be cleared. +.SH "RETURN VALUE" +Upon successful completion, +\fItruncate\fR() +shall return 0. Otherwise, \(mi1 shall be returned, and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItruncate\fR() +function shall fail if: +.TP +.BR EINTR +A signal was caught during execution. +.TP +.BR EINVAL +The +.IR length +argument was less than 0. +.TP +.BR EFBIG " or " EINVAL +.br +The +.IR length +argument was greater than the maximum file size. +.TP +.BR EIO +An I/O error occurred while reading from or writing to a file system. +.TP +.BR EACCES +A component of the path prefix denies search permission, or write +permission is denied on the file. +.TP +.BR EISDIR +The named file is a directory. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The named file resides on a read-only file system. +.br +.P +The +\fItruncate\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/truncf.3p b/man-pages-posix-2013-a/man3p/truncf.3p new file mode 100644 index 0000000..7c9eb84 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/truncf.3p @@ -0,0 +1,40 @@ +'\" et +.TH TRUNCF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +truncf, +truncl +\(em round to truncated integer value +.SH SYNOPSIS +.LP +.nf +#include +.P +float truncf(float \fIx\fP); +long double truncl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItrunc\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tsearch.3p b/man-pages-posix-2013-a/man3p/tsearch.3p new file mode 100644 index 0000000..13a9a5d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tsearch.3p @@ -0,0 +1,39 @@ +'\" et +.TH TSEARCH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tsearch +\(em search a binary search tree +.SH SYNOPSIS +.LP +.nf +#include +.P +void *tsearch(const void *\fIkey\fP, void **\fIrootp\fP, + int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItdelete\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ttyname.3p b/man-pages-posix-2013-a/man3p/ttyname.3p new file mode 100644 index 0000000..2c52d8c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ttyname.3p @@ -0,0 +1,130 @@ +'\" et +.TH TTYNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ttyname, +ttyname_r +\(em find the pathname of a terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +char *ttyname(int \fIfildes\fP); +int ttyname_r(int \fIfildes\fP, char *\fIname\fP, size_t \fInamesize\fP); +.fi +.SH DESCRIPTION +The +\fIttyname\fR() +function shall return a pointer to a string containing a null-terminated +pathname of the terminal associated with file descriptor +.IR fildes . +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIttyname\fR(). +.P +The +\fIttyname\fR() +function need not be thread-safe. +.P +The +\fIttyname_r\fR() +function shall store the null-terminated pathname of the terminal +associated with the file descriptor +.IR fildes +in the character array referenced by +.IR name . +The array is +.IR namesize +characters long and should have space for the name and the terminating +null character. The maximum length of the terminal name shall be +{TTY_NAME_MAX}. +.SH "RETURN VALUE" +Upon successful completion, +\fIttyname\fR() +shall return a pointer to a string. Otherwise, a null pointer shall +be returned and +.IR errno +set to indicate the error. +.P +If successful, the +\fIttyname_r\fR() +function shall return zero. Otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIttyname\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a terminal. +.P +The +\fIttyname_r\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a terminal. +.TP +.BR ERANGE +The value of +.IR namesize +is smaller than the length of the string to be returned including the +terminating null character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The term ``terminal'' is used instead of the historical term +``terminal device'' in order to avoid a reference to an undefined +term. +.P +The thread-safe version places the terminal name in a user-supplied +buffer and returns a non-zero value if it fails. The non-thread-safe +version may return the name in a static data area that may be +overwritten by each call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/twalk.3p b/man-pages-posix-2013-a/man3p/twalk.3p new file mode 100644 index 0000000..cabe490 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/twalk.3p @@ -0,0 +1,39 @@ +'\" et +.TH TWALK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +twalk +\(em traverse a binary search tree +.SH SYNOPSIS +.LP +.nf +#include +.P +void twalk(const void *\fIroot\fP, + void (*\fIaction\fP)(const void *, VISIT, int )); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItdelete\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/tzset.3p b/man-pages-posix-2013-a/man3p/tzset.3p new file mode 100644 index 0000000..104167b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/tzset.3p @@ -0,0 +1,128 @@ +'\" et +.TH TZSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +daylight, +timezone, +tzname, +tzset +\(em set timezone conversion information +.SH SYNOPSIS +.LP +.nf +#include +.P +extern int daylight; +extern long timezone; +extern char *tzname[2]; +void tzset(void); +.fi +.SH DESCRIPTION +The +\fItzset\fR() +function shall use the value of the environment variable +.IR TZ +to set time conversion information used by +.IR "\fIctime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +and +.IR "\fIstrftime\fR\^(\|)". +If +.IR TZ +is absent from the environment, implementation-defined default +timezone information shall be used. +.P +The +\fItzset\fR() +function shall set the external variable +.IR tzname +as follows: +.sp +.RS 4 +.nf +\fB +tzname[0] = "\fIstd\fP"; +tzname[1] = "\fIdst\fP"; +.fi \fR +.P +.RE +.P +where +.IR std +and +.IR dst +are as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +The +\fItzset\fR() +function also shall set the external variable +.IR daylight +to 0 if Daylight Savings Time conversions should never be applied for +the timezone in use; otherwise, non-zero. The external variable +.IR timezone +shall be set to the difference, in seconds, between Coordinated +Universal Time (UTC) and local standard time. +.SH "RETURN VALUE" +The +\fItzset\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Example +.IR TZ +variables and their timezone differences are given in the table below: +.TS +center box tab(!); +cI | cI +lw(1i) | lw(1i). +TZ!timezone +_ +EST5EDT!5*60*60 +GMT0!0*60*60 +JST-9!\(mi9*60*60 +MET-1MEST!\(mi1*60*60 +MST7MDT!7*60*60 +PST8PDT!8*60*60 +.TE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIctime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ulimit.3p b/man-pages-posix-2013-a/man3p/ulimit.3p new file mode 100644 index 0000000..37e1eb2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ulimit.3p @@ -0,0 +1,132 @@ +'\" et +.TH ULIMIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ulimit +\(em get and set process limits +.SH SYNOPSIS +.LP +.nf +#include +.P +long ulimit(int \fIcmd\fP, ...); +.fi +.SH DESCRIPTION +The +\fIulimit\fR() +function shall control process limits. The process limits that can be +controlled by this function include the maximum size of a single file +that can be written (this is equivalent to using +\fIsetrlimit\fR() +with RLIMIT_FSIZE). The +.IR cmd +values, defined in +.IR , +include: +.IP UL_GETFSIZE 12 +Return the file size limit (RLIMIT_FSIZE) of the process. The limit +shall be in units of 512-byte blocks and shall be inherited by child +processes. Files of any size can be read. The return value shall be the +integer part of the soft file size limit divided by 512. If the result +cannot be represented as a +.BR long , +the result is unspecified. +.IP UL_SETFSIZE 12 +Set the file size limit for output operations of the process to the +value of the second argument, taken as a +.BR long , +multiplied by 512. If the result would overflow an +.BR rlim_t , +the actual value set is unspecified. Any process may decrease its own +limit, but only a process with appropriate privileges may increase the +limit. The return value shall be the integer part of the new file size +limit divided by 512. +.P +The +\fIulimit\fR() +function shall not change the setting of +.IR errno +if successful. +.P +As all return values are permissible in a successful situation, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIulimit\fR(), +and, if it returns \(mi1, check to see if +.IR errno +is non-zero. +.SH "RETURN VALUE" +Upon successful completion, +\fIulimit\fR() +shall return the value of the requested limit. Otherwise, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIulimit\fR() +function shall fail and the limit shall be unchanged if: +.TP +.BR EINVAL +The +.IR cmd +argument is not valid. +.TP +.BR EPERM +A process not having appropriate privileges attempts to increase its +file size limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the +\fIulimit\fR() +function uses type +.BR long +rather than +.BR rlim_t , +this function is not sufficient for file sizes on many current systems. +Applications should use the +\fIgetrlimit\fR() +or +\fIsetrlimit\fR() +functions instead of the obsolescent +\fIulimit\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIulimit\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/umask.3p b/man-pages-posix-2013-a/man3p/umask.3p new file mode 100644 index 0000000..6505edf --- /dev/null +++ b/man-pages-posix-2013-a/man3p/umask.3p @@ -0,0 +1,116 @@ +'\" et +.TH UMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +umask +\(em set and get the file mode creation mask +.SH SYNOPSIS +.LP +.nf +#include +.P +mode_t umask(mode_t \fIcmask\fP); +.fi +.SH DESCRIPTION +The +\fIumask\fR() +function shall set the file mode creation mask of the process to +.IR cmask +and return the previous value of the mask. Only the file permission +bits of +.IR cmask +(see +.IR ) +are used; the meaning of the other bits is implementation-defined. +.P +The file mode creation mask of the process is used to turn off +permission bits in the +.IR mode +argument supplied during calls to the following functions: +.IP " *" 4 +\fIopen\fR(), +\fIopenat\fR(), +\fIcreat\fR(), +\fImkdir\fR(), +\fImkdirat\fR(), +\fImkfifo\fR(), +and +\fImkfifoat\fR() +.IP " *" 4 +\fImknod\fR(), +\fImknodat\fR() +.IP " *" 4 +\fImq_open\fR() +.IP " *" 4 +\fIsem_open\fR() +.P +Bit positions that are set in +.IR cmask +are cleared in the mode of the created file. +.SH "RETURN VALUE" +The file permission bits in the value returned by +\fIumask\fR() +shall be the previous value of the file mode creation mask. The state +of any other bits in that value is unspecified, except that a +subsequent call to +\fIumask\fR() +with the returned value as +.IR cmask +shall leave the state of the mask the same as its state before the +first call, including any unspecified use of those bits. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Unsigned argument and return types for +\fIumask\fR() +were proposed. The return type and the argument were both changed to +.BR mode_t . +.P +Historical implementations have made use of additional bits in +.IR cmask +for their implementation-defined purposes. The addition of the text +that the meaning of other bits of the field is implementation-defined +permits these implementations to conform to this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcreat\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/uname.3p b/man-pages-posix-2013-a/man3p/uname.3p new file mode 100644 index 0000000..f55c537 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/uname.3p @@ -0,0 +1,122 @@ +'\" et +.TH UNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uname +\(em get the name of the current system +.SH SYNOPSIS +.LP +.nf +#include +.P +int uname(struct utsname *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fIuname\fR() +function shall store information identifying the current system in the +structure pointed to by +.IR name . +.P +The +\fIuname\fR() +function uses the +.BR utsname +structure defined in +.IR . +.P +The +\fIuname\fR() +function shall return a string naming the current system in the +character array +.IR sysname . +Similarly, +.IR nodename +shall contain the name of this node within an implementation-defined +communications network. The arrays +.IR release +and +.IR version +shall further identify the operating system. The array +.IR machine +shall contain a name that identifies the hardware that the system +is running on. +.P +The format of each member is implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, a non-negative value shall be returned. +Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The inclusion of the +.IR nodename +member in this structure does not imply that it is sufficient +information for interfacing to communications networks. +.SH RATIONALE +The values of the structure members are not constrained to have any +relation to the version of this volume of POSIX.1\(hy2008 implemented in the operating +system. An application should instead depend on _POSIX_VERSION +and related constants defined in +.IR . +.P +This volume of POSIX.1\(hy2008 does not define the sizes of the members of the structure +and permits them to be of different sizes, although most +implementations define them all to be the same size: eight bytes plus +one byte for the string terminator. That size for +.IR nodename +is not enough for use with many networks. +.P +The +\fIuname\fR() +function originated in System III, System V, and related +implementations, +and it does not exist in Version 7 or +4.3 BSD. The values it returns are set at system compile time in those +historical implementations. +.P +4.3 BSD has +\fIgethostname\fR() +and +\fIgethostid\fR(), +which return a symbolic name and a numeric value, respectively. There +are related +\fIsethostname\fR() +and +\fIsethostid\fR() +functions that are used to set the values the other two functions +return. The former functions are included in this specification, the +latter are not. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ungetc.3p b/man-pages-posix-2013-a/man3p/ungetc.3p new file mode 100644 index 0000000..2cbd874 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ungetc.3p @@ -0,0 +1,118 @@ +'\" et +.TH UNGETC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ungetc +\(em push byte back into input stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int ungetc(int \fIc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIungetc\fR() +function shall push the byte specified by +.IR c +(converted to an +.BR "unsigned char" ) +back onto the input stream pointed to by +.IR stream . +The pushed-back bytes shall be returned by subsequent reads on that +stream in the reverse order of their pushing. A successful intervening +call (with the stream pointed to by +.IR stream ) +to a file-positioning function (\c +\fIfseek\fR(), +\c +\fIfseeko\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR()) +or +\fIfflush\fR() +shall discard any pushed-back bytes for the stream. The external +storage corresponding to the stream shall be unchanged. +.P +One byte of push-back shall be provided. If +\fIungetc\fR() +is called too many times on the same stream without an intervening read +or file-positioning operation on that stream, the operation may fail. +.P +If the value of +.IR c +equals that of the macro EOF, the operation shall fail and the input +stream shall be left unchanged. +.P +A successful call to +\fIungetc\fR() +shall clear the end-of-file indicator for the stream. The value of the +file-position indicator for the stream after all pushed-back bytes have +been read, or discarded by calling +\fIfseek\fR(), +\fIfseeko\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR() +(but not +\fIfflush\fR()), +shall be the same as it was before the bytes were pushed back. The +file-position indicator is decremented by each successful call to +\fIungetc\fR(); +if its value was 0 before a call, its value is unspecified after the call. +.SH "RETURN VALUE" +Upon successful completion, +\fIungetc\fR() +shall return the byte pushed back after conversion. Otherwise, it +shall return EOF. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIfsetpos\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/ungetwc.3p b/man-pages-posix-2013-a/man3p/ungetwc.3p new file mode 100644 index 0000000..a1c1d57 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/ungetwc.3p @@ -0,0 +1,126 @@ +'\" et +.TH UNGETWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ungetwc +\(em push wide-character code back into the input stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t ungetwc(wint_t \fIwc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIungetwc\fR() +function shall push the character corresponding to the wide-character +code specified by +.IR wc +back onto the input stream pointed to by +.IR stream . +The pushed-back characters shall be returned by subsequent reads on that +stream in the reverse order of their pushing. A successful intervening +call (with the stream pointed to by +.IR stream ) +to a file-positioning function (\c +\fIfseek\fR(), +\c +\fIfseeko\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR()) +or +\fIfflush\fR() +shall discard any pushed-back characters for the stream. The external +storage corresponding to the stream is unchanged. +.P +At least one character of push-back shall be provided. If +\fIungetwc\fR() +is called too many times on the same stream without an intervening read +or file-positioning operation on that stream, the operation may fail. +.P +If the value of +.IR wc +equals that of the macro WEOF, the operation shall fail and the input +stream shall be left unchanged. +.P +A successful call to +\fIungetwc\fR() +shall clear the end-of-file indicator for the stream. The value of the +file-position indicator for the stream after all pushed-back characters +have been read, or discarded by calling +\fIfseek\fR(), +\c +\fIfseeko\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR() +(but not +\fIfflush\fR()), +shall be the same as it was before the characters were pushed back. The +file-position indicator is decremented (by one or more) by each successful +call to +\fIungetwc\fR(); +if its value was 0 before a call, its value is unspecified after the call. +.SH "RETURN VALUE" +Upon successful completion, +\fIungetwc\fR() +shall return the wide-character code corresponding to the pushed-back +character. Otherwise, it shall return WEOF. +.SH ERRORS +The +\fIungetwc\fR() +function may fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected, or a wide-character code +does not correspond to a valid character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIfsetpos\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/unlink.3p b/man-pages-posix-2013-a/man3p/unlink.3p new file mode 100644 index 0000000..0154c29 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/unlink.3p @@ -0,0 +1,449 @@ +'\" et +.TH UNLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unlink, unlinkat +\(em remove a directory entry relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int unlink(const char *\fIpath\fP); +int unlinkat(int \fIfd\fP, const char *\fIpath\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIunlink\fR() +function shall remove a link to a file. If +.IR path +names a symbolic link, +\fIunlink\fR() +shall remove the symbolic link named by +.IR path +and shall not affect any file or directory named by the contents of the +symbolic link. Otherwise, +\fIunlink\fR() +shall remove the link named by the pathname pointed to by +.IR path +and shall decrement the link count of the file referenced by the link. +.P +When the file's link count becomes 0 and no process has the file open, +the space occupied by the file shall be freed and the file shall no +longer be accessible. If one or more processes have the file open when +the last link is removed, the link shall be removed before +\fIunlink\fR() +returns, but the removal of the file contents shall be postponed until +all references to the file are closed. +.P +The +.IR path +argument shall not name a directory unless the process has appropriate +privileges and the implementation supports using +\fIunlink\fR() +on directories. +.P +Upon successful completion, +\fIunlink\fR() +shall mark for update the last data modification and last file status +change timestamps of the parent directory. Also, if the file's link +count is not 0, the last file status change timestamp of the file shall +be marked for update. +.P +The +\fIunlinkat\fR() +function shall be equivalent to the +\fIunlink\fR() +or +\fIrmdir\fR() +function except in the case where +.IR path +specifies a relative path. In this case the directory entry to be +removed is determined relative to the directory associated with the +file descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_REMOVEDIR 6 +.br +Remove the directory entry specified by +.IR fd +and +.IR path +as a directory, not a normal file. +.P +If +\fIunlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIunlink\fR() +or +\fIrmdir\fR() +respectively, depending on whether or not the AT_REMOVEDIR bit is set in +.IR flag . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. Otherwise, +these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, the named file shall not +be changed. +.SH ERRORS +These functions shall fail and shall not unlink the file if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix, or +write permission is denied on the directory containing the directory +entry to be removed. +.TP +.BR EBUSY +The file named by the +.IR path +argument cannot be unlinked because it is being used by the system or +another process and the implementation considers this an error. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The file named by +.IR path +is a directory, and either the calling process does not have +appropriate privileges, or the implementation prohibits using +\fIunlink\fR() +on directories. +.TP +.BR EPERM " or " EACCES +.br +The S_ISVTX flag is set on the directory containing the file referred +to by the +.IR path +argument and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.2" ", " "Directory Protection". +.TP +.BR EROFS +The directory entry to be unlinked is part of a read-only file system. +.P +The +\fIunlinkat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.TP +.BR EEXIST " or " ENOTEMPTY +.br +The +.IR flag +parameter has the AT_REMOVEDIR bit set and the +.IR path +argument names a directory that is not an empty directory, or there are +hard links to the directory other than dot or a single entry in dot-dot. +.TP +.BR ENOTDIR +The +.IR flag +parameter has the AT_REMOVEDIR bit set and +.IR path +does not name a directory. +.P +These functions may fail and not unlink the file if: +.TP +.BR EBUSY +The file named by +.IR path +is a named STREAM. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +The entry to be unlinked is the last directory entry to a pure +procedure (shared text) file that is being executed. +.br +.P +The +\fIunlinkat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Removing a Link to a File" +.P +The following example shows how to remove a link to a file named +.BR /home/cnd/mod1 +by removing the entry named +.BR /modules/pass1 . +.sp +.RS 4 +.nf +\fB +#include +.P +char *path = "/modules/pass1"; +int status; +\&... +status = unlink(path); +.fi \fR +.P +.RE +.SS "Checking for an Error" +.P +The following example fragment creates a temporary password lock file +named +.BR LOCKFILE , +which is defined as +.BR /etc/ptmp , +and gets a file descriptor for it. If the file cannot be opened for +writing, +\fIunlink\fR() +is used to remove the link between the file descriptor and +.BR LOCKFILE . +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +.P +int pfd; /* Integer for file descriptor returned by open call. */ +FILE *fpfd; /* File pointer for use in putpwent(). */ +\&... +/* Open password Lock file. If it exists, this is an error. */ +if ((pfd = open(LOCKFILE, O_WRONLY| O_CREAT | O_EXCL, S_IRUSR + | S_IWUSR | S_IRGRP | S_IROTH)) == -1) { + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en"); + exit(1); +} +.P +/* Lock file created; proceed with fdopen of lock file so that + putpwent() can be used. + */ +if ((fpfd = fdopen(pfd, "w")) == NULL) { + close(pfd); + unlink(LOCKFILE); + exit(1); +} +.fi \fR +.P +.RE +.SS "Replacing Files" +.P +The following example fragment uses +\fIunlink\fR() +to discard links to files, so that they can be replaced with new +versions of the files. The first call removes the link to +.BR LOCKFILE +if an error occurs. Successive calls remove the links to +.BR SAVEFILE +and +.BR PASSWDFILE +so that new links can be created, then removes the link to +.BR LOCKFILE +when it is no longer needed. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +#define SAVEFILE "/etc/opasswd" +\&... +/* If no change was made, assume error and leave passwd unchanged. */ +if (!valid_change) { + fprintf(stderr, "Could not change password for user %s\en", user); + unlink(LOCKFILE); + exit(1); +} +.P +/* Change permissions on new password file. */ +chmod(LOCKFILE, S_IRUSR | S_IRGRP | S_IROTH); +.P +/* Remove saved password file. */ +unlink(SAVEFILE); +.P +/* Save current password file. */ +link(PASSWDFILE, SAVEFILE); +.P +/* Remove current password file. */ +unlink(PASSWDFILE); +.P +/* Save new password file as current password file. */ +link(LOCKFILE,PASSWDFILE); +.P +/* Remove lock file. */ +unlink(LOCKFILE); +.P +exit(0); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Applications should use +\fIrmdir\fR() +to remove a directory. +.SH RATIONALE +Unlinking a directory is restricted to the superuser +in many historical implementations for reasons given in +\fIlink\fR() +(see also +\fIrename\fR()). +.P +The meaning of +.BR [EBUSY] +in historical implementations is ``mount point busy''. Since this volume of POSIX.1\(hy2008 does +not cover the system administration concepts of mounting and unmounting, +the description of the error was changed to ``resource busy''. (This +meaning is used by some device drivers when a second process tries to +open an exclusive use device.) The wording is also intended to allow +implementations to refuse to remove a directory if it is the root or +current working directory of any process. +.P +The standard developers reviewed TR 24715\(hy2006 and noted that +LSB-conforming implementations may return +.BR [EISDIR] +instead of +.BR [EPERM] +when unlinking a directory. A change to permit this behavior by +changing the requirement for +.BR [EPERM] +to +.BR [EPERM] +or +.BR [EISDIR] +was considered, but decided against since it would break existing +strictly conforming and conforming applications. Applications written +for portability to both POSIX.1\(hy2008 and the LSB should be prepared to +handle either error code. +.P +The purpose of the +\fIunlinkat\fR() +function is to remove directory entries in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIunlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIunlinkat\fR() +function it can be guaranteed that the removed directory entry is +located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclose\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIremove\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.2" ", " "Directory Protection", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/unlockpt.3p b/man-pages-posix-2013-a/man3p/unlockpt.3p new file mode 100644 index 0000000..89347e2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/unlockpt.3p @@ -0,0 +1,85 @@ +'\" et +.TH UNLOCKPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unlockpt +\(em unlock a pseudo-terminal master/slave pair +.SH SYNOPSIS +.LP +.nf +#include +.P +int unlockpt(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIunlockpt\fR() +function shall unlock the slave pseudo-terminal device associated with +the master to which +.IR fildes +refers. +.P +Conforming applications shall ensure that they call +\fIunlockpt\fR() +before opening the slave side of a pseudo-terminal device. +.SH "RETURN VALUE" +Upon successful completion, +\fIunlockpt\fR() +shall return 0. Otherwise, it shall return \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIunlockpt\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a file descriptor open for writing. +.TP +.BR EINVAL +The +.IR fildes +argument is not associated with a master pseudo-terminal device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIposix_openpt\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_openpt\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/unsetenv.3p b/man-pages-posix-2013-a/man3p/unsetenv.3p new file mode 100644 index 0000000..423674d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/unsetenv.3p @@ -0,0 +1,92 @@ +'\" et +.TH UNSETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unsetenv +\(em remove an environment variable +.SH SYNOPSIS +.LP +.nf +#include +.P +int unsetenv(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fIunsetenv\fR() +function shall remove an environment variable from the environment +of the calling process. The +.IR name +argument points to a string, which is the name of the variable to be +removed. The named argument shall not contain an +.BR '=' +character. If the named variable does not exist in the current +environment, the environment shall be unchanged and the function is +considered to have completed successfully. +.P +The +\fIunsetenv\fR() +function shall update the list of pointers to which +.IR environ +points. +.P +The +\fIunsetenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, zero shall be returned. Otherwise, \(mi1 +shall be returned, +.IR errno +set to indicate the error, and the environment shall be unchanged. +.SH ERRORS +The +\fIunsetenv\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR name +argument points to an empty string, or points to a +string containing an +.BR '=' +character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetenv\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/uselocale.3p b/man-pages-posix-2013-a/man3p/uselocale.3p new file mode 100644 index 0000000..c4f1832 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/uselocale.3p @@ -0,0 +1,126 @@ +'\" et +.TH USELOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uselocale +\(em use locale in current thread +.SH SYNOPSIS +.LP +.nf +#include +.P +locale_t uselocale(locale_t \fInewloc\fP); +.fi +.SH DESCRIPTION +The +\fIuselocale\fR() +function shall set the current locale for the current thread to the +locale represented by +.IR newloc . +.P +The value for the +.IR newloc +argument shall be one of the following: +.IP " 1." 4 +A value returned by the +\fInewlocale\fR() +or +\fIduplocale\fR() +functions +.IP " 2." 4 +The special locale object descriptor LC_GLOBAL_LOCALE +.IP " 3." 4 +(\c +.BR locale_t )0 +.P +Once the +\fIuselocale\fR() +function has been called to install a thread-local locale, the behavior +of every interface using data from the current locale shall be affected +for the calling thread. The current locale for other threads shall +remain unchanged. +.P +If the +.IR newloc +argument is (\c +.BR locale_t )0, +the object returned is the current locale or LC_GLOBAL_LOCALE if there +has been no previous call to +\fIuselocale\fR() +for the current thread. +.P +If the +.IR newloc +argument is LC_GLOBAL_LOCALE, the thread shall use the global locale +determined by the +\fIsetlocale\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, the +\fIuselocale\fR() +function shall return the locale handle from the previous call for the +current thread, or LC_GLOBAL_LOCALE if there was no such previous call. +Otherwise, +\fIuselocale\fR() +shall return (\c +.BR locale_t )0 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIuselocale\fR() +function may fail if: +.TP +.BR EINVAL +.IR locale +is not a valid locale object. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Unlike the +\fIsetlocale\fR() +function, the +\fIuselocale\fR() +function does not allow replacing some locale categories +only. Applications that need to install a locale which differs only in +a few categories must use +\fInewlocale\fR() +to change a locale object equivalent to the currently used locale and +install it. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIduplocale\fR\^(\|)", +.IR "\fIfreelocale\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/utime.3p b/man-pages-posix-2013-a/man3p/utime.3p new file mode 100644 index 0000000..560bfa6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/utime.3p @@ -0,0 +1,202 @@ +'\" et +.TH UTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +utime +\(em set file access and modification times +.SH SYNOPSIS +.LP +.nf +#include +.P +int utime(const char *\fIpath\fP, const struct utimbuf *\fItimes\fP); +.fi +.SH DESCRIPTION +The +\fIutime\fR() +function shall set the access and modification times of the file named +by the +.IR path +argument. +.P +If +.IR times +is a null pointer, the access and modification times of the file shall +be set to the current time. The effective user ID of the process shall +match the owner of the file, or the process has write permission to the +file or has appropriate privileges, to use +\fIutime\fR() +in this manner. +.P +If +.IR times +is not a null pointer, +.IR times +shall be interpreted as a pointer to a +.BR utimbuf +structure and the access and modification times shall be set to the +values contained in the designated structure. Only a process with +the effective user ID equal to the user ID of the file or a process with +appropriate privileges may use +\fIutime\fR() +this way. +.P +The +.BR utimbuf +structure is defined in the +.IR +header. The times in the structure +.BR utimbuf +are measured in seconds since the Epoch. +.P +Upon successful completion, the +\fIutime\fR() +function shall mark the last file status change timestamp +for update; see +.IR . +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 +shall be returned and +.IR errno +shall be set to indicate the error, and the file times shall not be +affected. +.SH ERRORS +The +\fIutime\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied by a component of the path prefix; or the +.IR times +argument is a null pointer and the effective user ID of the process +does not match the owner of the file, the process does not have write +permission for the file, and the process does not have appropriate +privileges. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The +.IR times +argument is not a null pointer and the effective user ID of the calling +process does not match the owner of the file and the calling process +does not have appropriate privileges. +.TP +.BR EROFS +The file system containing the file is read-only. +.br +.P +The +\fIutime\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the +.BR utimbuf +structure only contains +.BR time_t +variables and is not accurate to fractions of a second, +applications should use the +\fIutimensat\fR() +function instead of the obsolescent +\fIutime\fR() +function. +.SH RATIONALE +The +.IR actime +structure member must be present so that an application may set it, +even though an implementation may ignore it and not change the last data +access timestamp on the file. If an application intends to leave one of +the times of a file unchanged while changing the other, it should use +\fIstat\fR() +or +\fIfstat\fR() +to retrieve the file's +.IR st_atim +and +.IR st_mtim +parameters, set +.IR actime +and +.IR modtime +in the buffer, and change one of them before making the +\fIutime\fR() +call. +.SH "FUTURE DIRECTIONS" +The +\fIutime\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfstat\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/utimensat.3p b/man-pages-posix-2013-a/man3p/utimensat.3p new file mode 100644 index 0000000..5835dda --- /dev/null +++ b/man-pages-posix-2013-a/man3p/utimensat.3p @@ -0,0 +1,44 @@ +'\" et +.TH UTIMENSAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +utimensat, utimes +\(em set file access and modification times relative to directory +file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int utimensat(int \fIfd\fP, const char *\fIpath\fP, const struct timespec \fItimes\fP[2], + int \fIflag\fP); +.P +#include +.P +int utimes(const char *\fIpath\fP, const struct timeval \fItimes\fP[2]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfutimens\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/va_arg.3p b/man-pages-posix-2013-a/man3p/va_arg.3p new file mode 100644 index 0000000..6344919 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/va_arg.3p @@ -0,0 +1,44 @@ +'\" et +.TH VA_ARG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +va_arg, +va_copy, +va_end, +va_start +\(em handle variable argument list +.SH SYNOPSIS +.LP +.nf +#include +.P +\fItype\fP va_arg(va_list \fIap\fP, \fItype\fP); +void va_copy(va_list \fIdest\fP, va_list \fIsrc\fP); +void va_end(va_list \fIap\fP); +void va_start(va_list \fIap\fP, \fIargN\fP); +.fi +.SH DESCRIPTION +Refer to the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vfprintf.3p b/man-pages-posix-2013-a/man3p/vfprintf.3p new file mode 100644 index 0000000..ef797dd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vfprintf.3p @@ -0,0 +1,101 @@ +'\" et +.TH VFPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vdprintf, +vfprintf, +vprintf, +vsnprintf, +vsprintf +\(em format output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vdprintf(int \fIfildes\fR, const char *restrict \fIformat\fR, va_list \fIap\fR); +int vfprintf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, + va_list \fIap\fP); +int vprintf(const char *restrict \fIformat\fP, va_list \fIap\fP); +int vsnprintf(char *restrict \fIs\fP, size_t \fIn\fP, const char *restrict \fIformat\fP, + va_list \fIap\fP); +int vsprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, va_list \fIap\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIvdprintf\fR(), +\fIvfprintf\fR(), +\fIvprintf\fR(), +\fIvsnprintf\fR(), +and +\fIvsprintf\fR() +functions shall be equivalent to the \& +\fIdprintf\fR(), +\fIfprintf\fR(), +\fIprintf\fR(), +\fIsnprintf\fR(), +and +\fIsprintf\fR() +functions respectively, except that instead of being called with a +variable number of arguments, they are called with an argument list as +defined by +.IR . +.P +These functions shall not invoke the +.IR va_end +macro. As these functions invoke the +.IR va_arg +macro, the value of +.IR ap +after the return is unspecified. +.SH "RETURN VALUE" +Refer to +.IR "\fIfprintf\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfprintf\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions should call \fIva_end\fP(\fIap\fP) +afterwards to clean up. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vfscanf.3p b/man-pages-posix-2013-a/man3p/vfscanf.3p new file mode 100644 index 0000000..07b125a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vfscanf.3p @@ -0,0 +1,94 @@ +'\" et +.TH VFSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vfscanf, +vscanf, +vsscanf +\(em format input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vfscanf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, + va_list \fIarg\fP); +int vscanf(const char *restrict \fIformat\fP, va_list \fIarg\fP); +int vsscanf(const char *restrict \fIs\fP, const char *restrict \fIformat\fP, + va_list \fIarg\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIvscanf\fR(), +\fIvfscanf\fR(), +and +\fIvsscanf\fR() +functions shall be equivalent to the +\fIscanf\fR(), +\fIfscanf\fR(), +and +\fIsscanf\fR() +functions, respectively, except that instead of being called with a +variable number of arguments, they are called with an argument list as +defined in the +.IR +header. These functions shall not invoke the +.IR va_end +macro. As these functions invoke the +.IR va_arg +macro, the value of +.IR ap +after the return is unspecified. +.SH "RETURN VALUE" +Refer to +.IR "\fIfscanf\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfscanf\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions should call +.IR va_end (\c +.IR ap ) +afterwards to clean up. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfscanf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vfwprintf.3p b/man-pages-posix-2013-a/man3p/vfwprintf.3p new file mode 100644 index 0000000..54f8890 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vfwprintf.3p @@ -0,0 +1,95 @@ +'\" et +.TH VFWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vfwprintf, +vswprintf, +vwprintf +\(em wide-character formatted output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vfwprintf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, + va_list \fIarg\fP); +int vswprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP, + const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +int vwprintf(const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIvfwprintf\fR(), +\fIvswprintf\fR(), +and +\fIvwprintf\fR() +functions shall be equivalent to +\fIfwprintf\fR(), +\fIswprintf\fR(), +and +\fIwprintf\fR() +respectively, except that instead of being called with a variable +number of arguments, they are called with an argument list as defined +by +.IR . +.P +These functions shall not invoke the +.IR va_end +macro. However, as these functions do invoke the +.IR va_arg +macro, the value of +.IR ap +after the return is unspecified. +.SH "RETURN VALUE" +Refer to +.IR "\fIfwprintf\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfwprintf\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions should call \fIva_end\fP(\fIap\fP) +afterwards to clean up. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfwprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vfwscanf.3p b/man-pages-posix-2013-a/man3p/vfwscanf.3p new file mode 100644 index 0000000..c6ffb59 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vfwscanf.3p @@ -0,0 +1,96 @@ +'\" et +.TH VFWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vfwscanf, +vswscanf, +vwscanf +\(em wide-character formatted input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vfwscanf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, + va_list \fIarg\fP); +int vswscanf(const wchar_t *restrict \fIws\fP, const wchar_t *restrict \fIformat\fP, + va_list \fIarg\fP); +int vwscanf(const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIvfwscanf\fR(), +\fIvswscanf\fR(), +and +\fIvwscanf\fR() +functions shall be equivalent to the +\fIfwscanf\fR(), +\fIswscanf\fR(), +and +\fIwscanf\fR() +functions, respectively, except that instead of being called with a +variable number of arguments, they are called with an argument list as +defined in the +.IR +header. These functions shall not invoke the +.IR va_end +macro. As these functions invoke the +.IR va_arg +macro, the value of +.IR ap +after the return is unspecified. +.SH "RETURN VALUE" +Refer to +.IR "\fIfwscanf\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfwscanf\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions should call +.IR va_end (\c +.IR ap ) +afterwards to clean up. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfwscanf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vprintf.3p b/man-pages-posix-2013-a/man3p/vprintf.3p new file mode 100644 index 0000000..a5825ff --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vprintf.3p @@ -0,0 +1,39 @@ +'\" et +.TH VPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vprintf +\(em format the output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vprintf(const char *restrict \fIformat\fP, va_list \fIap\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vscanf.3p b/man-pages-posix-2013-a/man3p/vscanf.3p new file mode 100644 index 0000000..7f5d18d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vscanf.3p @@ -0,0 +1,39 @@ +'\" et +.TH VSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vscanf +\(em format input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vscanf(const char *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfscanf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vsnprintf.3p b/man-pages-posix-2013-a/man3p/vsnprintf.3p new file mode 100644 index 0000000..fef936d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vsnprintf.3p @@ -0,0 +1,43 @@ +'\" et +.TH VSNPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vsnprintf, +vsprintf +\(em format output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vsnprintf(char *restrict \fIs\fP, size_t \fIn\fP, + const char *restrict \fIformat\fP, va_list \fIap\fP); +int vsprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, + va_list \fIap\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vsscanf.3p b/man-pages-posix-2013-a/man3p/vsscanf.3p new file mode 100644 index 0000000..1218042 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vsscanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH VSSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vsscanf +\(em format input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vsscanf(const char *restrict \fIs\fP, const char *restrict \fIformat\fP, + va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfscanf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vswprintf.3p b/man-pages-posix-2013-a/man3p/vswprintf.3p new file mode 100644 index 0000000..9c28214 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vswprintf.3p @@ -0,0 +1,41 @@ +'\" et +.TH VSWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vswprintf +\(em wide-character formatted output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vswprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP, + const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfwprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vswscanf.3p b/man-pages-posix-2013-a/man3p/vswscanf.3p new file mode 100644 index 0000000..72045d7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vswscanf.3p @@ -0,0 +1,41 @@ +'\" et +.TH VSWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vswscanf +\(em wide-character formatted input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vswscanf(const wchar_t *restrict \fIws\fP, const wchar_t *restrict \fIformat\fP, + va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfwscanf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vwprintf.3p b/man-pages-posix-2013-a/man3p/vwprintf.3p new file mode 100644 index 0000000..d525110 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vwprintf.3p @@ -0,0 +1,40 @@ +'\" et +.TH VWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vwprintf +\(em wide-character formatted output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vwprintf(const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfwprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/vwscanf.3p b/man-pages-posix-2013-a/man3p/vwscanf.3p new file mode 100644 index 0000000..939a3f1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/vwscanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH VWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +vwscanf +\(em wide-character formatted input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vwscanf(const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfwscanf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wait.3p b/man-pages-posix-2013-a/man3p/wait.3p new file mode 100644 index 0000000..d14b60c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wait.3p @@ -0,0 +1,892 @@ +'\" et +.TH WAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wait, +waitpid +\(em wait for a child process to stop or terminate +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t wait(int *\fIstat_loc\fP); +pid_t waitpid(pid_t \fIpid\fP, int *\fIstat_loc\fP, int \fIoptions\fP); +.fi +.SH DESCRIPTION +The +\fIwait\fR() +and +\fIwaitpid\fR() +functions shall obtain status information pertaining to one of the +caller's child processes. Various options permit status information to +be obtained for child processes that have terminated or stopped. If +status information is available for two or more child processes, the +order in which their status is reported is unspecified. +.P +The +\fIwait\fR() +function shall suspend execution of the calling thread until status +information for one of the terminated child processes of the calling +process is available, or until delivery of a signal whose action is +either to execute a signal-catching function or to terminate the +process. If more than one thread is suspended in +\fIwait\fR() +or +\fIwaitpid\fR() +awaiting termination of the same process, exactly one thread shall +return the process status at the time of the target process +termination. If status information is available prior to the call to +\fIwait\fR(), +return shall be immediate. +.P +The +\fIwaitpid\fR() +function shall be equivalent to +\fIwait\fR() +if the +.IR pid +argument is (\fBpid_t\fP)\(mi1 and the +.IR options +argument is 0. Otherwise, its behavior shall be modified by the values +of the +.IR pid +and +.IR options +arguments. +.P +The +.IR pid +argument specifies a set of child processes for which +.IR status +is requested. The +\fIwaitpid\fR() +function shall only return the status of a child process from this set: +.IP " *" 4 +If +.IR pid +is equal to (\fBpid_t\fP)\(mi1, +.IR status +is requested for any child process. In this respect, +\fIwaitpid\fR() +is then equivalent to +\fIwait\fR(). +.IP " *" 4 +If +.IR pid +is greater than 0, it specifies the process ID of a single child +process for which +.IR status +is requested. +.IP " *" 4 +If +.IR pid +is 0, +.IR status +is requested for any child process whose process group ID is equal to +that of the calling process. +.IP " *" 4 +If +.IR pid +is less than (\fBpid_t\fP)\(mi1, +.IR status +is requested for any child process whose process group ID is equal to +the absolute value of +.IR pid . +.P +The +.IR options +argument is constructed from the bitwise-inclusive OR of zero or more +of the following flags, defined in the +.IR +header: +.IP WCONTINUED 12 +The +\fIwaitpid\fR() +function shall report the status of any continued child process +specified by +.IR pid +whose status has not been reported since it continued from a job +control stop. +.IP WNOHANG 12 +The +\fIwaitpid\fR() +function shall not suspend execution of the calling thread if +.IR status +is not immediately available for one of the child processes specified +by +.IR pid . +.IP WUNTRACED 12 +The status of any child processes specified by +.IR pid +that are stopped, and whose status has not yet been reported since they +stopped, shall also be reported to the requesting process. +.P +If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to +SIG_IGN, +and the process has no unwaited-for children that were transformed into +zombie processes, the calling thread shall block until all of the +children of the process containing the calling thread terminate, and +\fIwait\fR() +and +\fIwaitpid\fR() +shall fail and set +.IR errno +to +.BR [ECHILD] . +.P +If +\fIwait\fR() +or +\fIwaitpid\fR() +return because the status of a child process is available, these +functions shall return a value equal to the process ID of the child +process. In this case, if the value of the argument +.IR stat_loc +is not a null pointer, information shall be stored in the location +pointed to by +.IR stat_loc . +The value stored at the location pointed to by +.IR stat_loc +shall be 0 if and only if the status returned is from a terminated +child process that terminated by one of the following means: +.IP " 1." 4 +The process returned 0 from +\fImain\fR(). +.IP " 2." 4 +The process called +\fI_exit\fR() +or +\fIexit\fR() +with a +.IR status +argument of 0. +.IP " 3." 4 +The process was terminated because the last thread in the process +terminated. +.P +Regardless of its value, this information may be +interpreted using the following macros, which are defined in +.IR +and evaluate to integral expressions; the +.IR stat_val +argument is the integer value pointed to by +.IR stat_loc . +.IP "WIFEXITED(\fIstat_val\fP)" 6 +.br +Evaluates to a non-zero value if +.IR status +was returned for a child process that terminated normally. +.IP "WEXITSTATUS(\fIstat_val\fP)" 6 +.br +If the value of WIFEXITED(\fIstat_val\fP) is non-zero, this macro +evaluates to the low-order 8 bits of the +.IR status +argument that the child process passed to +\fI_exit\fR() +or +\fIexit\fR(), +or the value the child process returned from +\fImain\fR(). +.IP "WIFSIGNALED(\fIstat_val\fP)" 6 +.br +Evaluates to a non-zero value if +.IR status +was returned for a child process that terminated due to the receipt of +a signal that was not caught (see +.IR ). +.IP "WTERMSIG(\fIstat_val\fP)" 6 +.br +If the value of WIFSIGNALED(\fIstat_val\fP) is non-zero, this macro +evaluates to the number of the signal that caused the termination of +the child process. +.IP "WIFSTOPPED(\fIstat_val\fP)" 6 +.br +Evaluates to a non-zero value if +.IR status +was returned for a child process that is currently stopped. +.IP "WSTOPSIG(\fIstat_val\fP)" 6 +.br +If the value of WIFSTOPPED(\fIstat_val\fP) is non-zero, this macro +evaluates to the number of the signal that caused the child process to +stop. +.IP "WIFCONTINUED(\fIstat_val\fP)" 6 +.br +Evaluates to a non-zero value if +.IR status +was returned for a child process that has continued from a job control +stop. +.P +It is unspecified whether the +.IR status +value returned by calls to +\fIwait\fR() +or +\fIwaitpid\fR() +for processes created by +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +can indicate a WIFSTOPPED(\fIstat_val\fP) before subsequent calls to +\fIwait\fR() +or +\fIwaitpid\fR() +indicate WIFEXITED(\fIstat_val\fP) as the result of an error detected +before the new process image starts executing. +.P +It is unspecified whether the +.IR status +value returned by calls to +\fIwait\fR() +or +\fIwaitpid\fR() +for processes created by +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +can indicate a WIFSIGNALED(\fIstat_val\fP) if a signal is sent to the +parent's process group after +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +is called. +.P +If the information pointed to by +.IR stat_loc +was stored by a call to +\fIwaitpid\fR() +that specified the WUNTRACED flag +and did not specify the WCONTINUED flag, +exactly one of the macros WIFEXITED(*\fIstat_loc\fR), +WIFSIGNALED(*\fIstat_loc\fR), and WIFSTOPPED(*\fIstat_loc\fR) +shall evaluate to a non-zero value. +.P +If the information pointed to by +.IR stat_loc +was stored by a call to +\fIwaitpid\fR() +that specified the WUNTRACED +and WCONTINUED +flags, exactly one of the macros WIFEXITED(*\fIstat_loc\fR), +WIFSIGNALED(*\fIstat_loc\fR), WIFSTOPPED(*\fIstat_loc\fR), +and WIFCONTINUED(*\fIstat_loc\fR) +shall evaluate to a non-zero value. +.P +If the information pointed to by +.IR stat_loc +was stored by a call to +\fIwaitpid\fR() +that did not specify the WUNTRACED +or WCONTINUED +flags, or by a call to the +\fIwait\fR() +function, exactly one of the macros WIFEXITED(*\fIstat_loc\fR) and +WIFSIGNALED(*\fIstat_loc\fR) shall evaluate to a non-zero value. +.P +If the information pointed to by +.IR stat_loc +was stored by a call to +\fIwaitpid\fR() +that did not specify the WUNTRACED flag +and specified the WCONTINUED flag, +or by a call to the +\fIwait\fR() +function, exactly one of the macros WIFEXITED(*\fIstat_loc\fR), +WIFSIGNALED(*\fIstat_loc\fR), +and WIFCONTINUED(*\fIstat_loc\fR) +shall evaluate to a non-zero value. +.P +If _POSIX_REALTIME_SIGNALS is defined, and the implementation queues +the SIGCHLD signal, then if +\fIwait\fR() +or +\fIwaitpid\fR() +returns because the status of a child process is available, any pending +SIGCHLD signal associated with the process ID of the child process +shall be discarded. Any other pending SIGCHLD signals shall remain +pending. +.P +Otherwise, if SIGCHLD is blocked, if +\fIwait\fR() +or +\fIwaitpid\fR() +return because the status of a child process is available, any pending +SIGCHLD signal shall be cleared unless the status of another child +process is available. +.P +For all other conditions, it is unspecified whether child +.IR status +will be available when a SIGCHLD signal is delivered. +.P +There may be additional implementation-defined circumstances under +which +\fIwait\fR() +or +\fIwaitpid\fR() +report +.IR status . +This shall not occur unless the calling process or one of its child +processes explicitly makes use of a non-standard extension. In these +cases the interpretation of the reported +.IR status +is implementation-defined. +.P +If a parent process terminates without waiting for all of its child +processes to terminate, the remaining child processes shall be assigned +a new parent process ID corresponding to an implementation-defined +system process. +.SH "RETURN VALUE" +If +\fIwait\fR() +or +\fIwaitpid\fR() +returns because the status of a child process is available, these +functions shall return a value equal to the process ID of the child +process for which +.IR status +is reported. If +\fIwait\fR() +or +\fIwaitpid\fR() +returns due to the delivery of a signal to the calling process, \(mi1 +shall be returned and +.IR errno +set to +.BR [EINTR] . +If +\fIwaitpid\fR() +was invoked with WNOHANG set in +.IR options , +it has at least one child process specified by +.IR pid +for which +.IR status +is not available, and +.IR status +is not available for any process specified by +.IR pid , +0 is returned. Otherwise, \(mi1 shall be returned, and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIwait\fR() +function shall fail if: +.TP +.BR ECHILD +The calling process has no existing unwaited-for child processes. +.TP +.BR EINTR +The function was interrupted by a signal. The value of the location +pointed to by +.IR stat_loc +is undefined. +.P +The +\fIwaitpid\fR() +function shall fail if: +.TP +.BR ECHILD +The process specified by +.IR pid +does not exist or is not a child of the calling process, or the process +group specified by +.IR pid +does not exist or does not have any member process that is a child of +the calling process. +.TP +.BR EINTR +The function was interrupted by a signal. The value of the location +pointed to by +.IR stat_loc +is undefined. +.TP +.BR EINVAL +The +.IR options +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Waiting for a Child Process and then Checking its Status" +.P +The following example demonstrates the use of +\fIwaitpid\fR(), +\fIfork\fR(), +and the macros used to interpret the status value returned by +\fIwaitpid\fR() +(and +\fIwait\fR()). +The code segment creates a child process which does some unspecified +work. Meanwhile the parent loops performing calls to +\fIwaitpid\fR() +to monitor the status of the child. The loop terminates when child +termination is detected. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +\&... +.P +pid_t child_pid, wpid; +int status; +.P +child_pid = fork(); +if (child_pid == \(mi1) { /* fork() failed */ + perror("fork"); + exit(EXIT_FAILURE); +} +.P +if (child_pid == 0) { /* This is the child */ + /* Child does some work and then terminates */ + ... +.P +} else { /* This is the parent */ + do { + wpid = waitpid(child_pid, &status, WUNTRACED +#ifdef WCONTINUED /* Not all implementations support this */ + | WCONTINUED +#endif + ); + if (wpid == \(mi1) { + perror("waitpid"); + exit(EXIT_FAILURE); + } +.P + if (WIFEXITED(status)) { + printf("child exited, status=%d\en", WEXITSTATUS(status)); +.P + } else if (WIFSIGNALED(status)) { + printf("child killed (signal %d)\en", WTERMSIG(status)); +.P + } else if (WIFSTOPPED(status)) { + printf("child stopped (signal %d)\en", WSTOPSIG(status)); +.P +#ifdef WIFCONTINUED /* Not all implementations support this */ + } else if (WIFCONTINUED(status)) { + printf("child continued\en"); +#endif + } else { /* Non-standard case -- may never happen */ + printf("Unexpected status (0x%x)\en", status); + } + } while (!WIFEXITED(status) && !WIFSIGNALED(status)); +} +.fi \fR +.P +.RE +.SS "Waiting for a Child Process in a Signal Handler for SIGCHLD" +.P +The following example demonstrates how to use +\fIwaitpid\fR() +in a signal handler for SIGCHLD without passing \(mi1 as the +.IR pid +argument. (See the APPLICATION USAGE section below for the reasons +why passing a +.IR pid +of \(mi1 is not recommended.) The method used here relies on the +standard behavior of +\fIwaitpid\fR() +when SIGCHLD is blocked. On historical non-conforming systems, the +status of some child processes might not be reported. +.sp +.RS 4 +.nf +\fB +#include +#include +#include +#include +#include +#include +.P +#define CHILDREN 10 +.P +static void +handle_sigchld(int signum, siginfo_t *sinfo, void *unused) +{ + int sav_errno = errno; + int status; +.P + /* + * Obtain status information for the child which + * caused the SIGCHLD signal and write its exit code + * to stdout. + */ + if (sinfo->si_code != CLD_EXITED) + { + static char msg[] = "wrong si_code\en"; + write(2, msg, sizeof msg \(mi 1); + } + else if (waitpid(sinfo->si_pid, &status, 0) =\|= \(mi1) + { + static char msg[] = "waitpid() failed\en"; + write(2, msg, sizeof msg \(mi 1); + } + else if (!WIFEXITED(status)) + { + static char msg[] = "WIFEXITED was false\en"; + write(2, msg, sizeof msg \(mi 1); + } + else + { + int code = WEXITSTATUS(status); + char buf[2]; + buf[0] = '0' + code; + buf[1] = '\en'; + write(1, buf, 2); + } + errno = sav_errno; +} +.P +int +main(void) +{ + int i; + pid_t pid; + struct sigaction sa; +.P + sa.sa_flags = SA_SIGINFO; + sa.sa_sigaction = handle_sigchld; + sigemptyset(&sa.sa_mask); + if (sigaction(SIGCHLD, &sa, NULL) =\|= \(mi1) + { + perror("sigaction"); + exit(EXIT_FAILURE); + } +.P + for (i = 0; i < CHILDREN; i++) + { + switch (pid = fork()) + { + case \(mi1: + perror("fork"); + exit(EXIT_FAILURE); + case 0: + sleep(2); + _exit(i); + } + } +.P + /* Wait for all the SIGCHLD signals, then terminate on SIGALRM */ + alarm(3); + for (;;) + pause(); +.P + return 0; /* NOTREACHED */ +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Calls to +\fIwait\fR() +will collect information about any child process. This may result in +interactions with other interfaces that may be waiting for their own +children (such as by use of +\fIsystem\fR()). +For this and other reasons it is recommended that portable applications +not use +\fIwait\fR(), +but instead use +\fIwaitpid\fR(). +For these same reasons, the use of +\fIwaitpid\fR() +with a +.IR pid +argument of \(mi1, and the use of +\fIwaitid\fR() +with the +.IR idtype +argument set to P_ALL, are also not recommended for portable applications. +.SH RATIONALE +A call to the +\fIwait\fR() +or +\fIwaitpid\fR() +function only returns +.IR status +on an immediate child process of the calling process; that is, a child +that was produced by a single +\fIfork\fR() +call (perhaps followed by an +.IR exec +or other function calls) from the parent. If a child produces +grandchildren by further use of +\fIfork\fR(), +none of those grandchildren nor any of their descendants affect the +behavior of a +\fIwait\fR() +from the original parent process. Nothing in this volume of POSIX.1\(hy2008 prevents an +implementation from providing extensions that permit a process to get +.IR status +from a grandchild or any other process, but a process that does not use +such extensions must be guaranteed to see +.IR status +from only its direct children. +.P +The +\fIwaitpid\fR() +function is provided for three reasons: +.IP " 1." 4 +To support job control +.IP " 2." 4 +To permit a non-blocking version of the +\fIwait\fR() +function +.IP " 3." 4 +To permit a library routine, such as +\fIsystem\fR() +or +\fIpclose\fR(), +to wait for its children without interfering with other terminated +children for which the process has not waited +.P +The first two of these facilities are based on the +.IR wait3 (\|) +function provided by 4.3 BSD. The function uses the +.IR options +argument, which is equivalent to an argument to +.IR wait3 (\|). +The WUNTRACED +flag is used only in conjunction with job control on systems supporting +job control. Its name comes from 4.3 BSD +and refers to the fact that there are two types of stopped processes in +that implementation: processes being traced via the +\fIptrace\fR() +debugging facility and (untraced) processes stopped by job control +signals. Since +\fIptrace\fR() +is not part of this volume of POSIX.1\(hy2008, only the second type is relevant. The name +WUNTRACED was retained because its usage is the same, even though the +name is not intuitively meaningful in this context. +.P +The third reason for the +\fIwaitpid\fR() +function is to permit independent sections of a process to spawn and +wait for children without interfering with each other. For example, +the following problem occurs in developing a portable shell, or command +interpreter: +.sp +.RS 4 +.nf +\fB +stream = popen("/bin/true"); +(void) system("sleep 100"); +(void) pclose(stream); +.fi \fR +.P +.RE +.P +On all historical implementations, the final +\fIpclose\fR() +fails to reap the +\fIwait\fR() +.IR status +of the +\fIpopen\fR(). +.P +The status values are retrieved by macros, rather than given as +specific bit encodings as they are in most historical implementations +(and thus expected by existing programs). This was necessary to +eliminate a limitation on the number of signals an implementation can +support that was inherent in the traditional encodings. This volume of POSIX.1\(hy2008 +does require that a +.IR status +value of zero corresponds to a process calling +.IR _exit (0), +as this is the most common encoding expected by existing programs. +Some of the macro names were adopted from 4.3 BSD. +.P +These macros syntactically operate on an arbitrary integer value. The +behavior is undefined unless that value is one stored by a successful +call to +\fIwait\fR() +or +\fIwaitpid\fR() +in the location pointed to by the +.IR stat_loc +argument. An early proposal attempted to make this clearer by specifying +each argument as *\fIstat_loc\fP rather than +.IR stat_val . +However, that did not follow the conventions of other specifications in +\&this volume of POSIX.1\(hy2008 or traditional usage. It also could have implied that the +argument to the macro must literally be *\fIstat_loc\fP; in fact, that +value can be stored or passed as an argument to other functions before +being interpreted by these macros. +.P +The extension that affects +\fIwait\fR() +and +\fIwaitpid\fR() +and is common in historical implementations is the +\fIptrace\fR() +function. It is called by a child process and causes that child to +stop and return a +.IR status +that appears identical to the +.IR status +indicated by WIFSTOPPED. +The +.IR status +of +\fIptrace\fR() +children is traditionally returned regardless of the WUNTRACED +flag (or by the +\fIwait\fR() +function). Most applications do not need to concern themselves with +such extensions because they have control over what extensions they or +their children use. However, applications, such as command +interpreters, that invoke arbitrary processes may see this behavior +when those arbitrary processes misuse such extensions. +.P +Implementations that support +.BR core +file creation or other implementation-defined actions on termination +of some processes traditionally provide a bit in the +.IR status +returned by +\fIwait\fR() +to indicate that such actions have occurred. +.P +Allowing the +\fIwait\fR() +family of functions to discard a pending SIGCHLD signal that is +associated with a successfully waited-for child process puts them into +the +\fIsigwait\fR() +and +\fIsigwaitinfo\fR() +category with respect to SIGCHLD. +.P +This definition allows implementations to treat a pending SIGCHLD +signal as accepted by the process in +\fIwait\fR(), +with the same meaning of ``accepted'' as when that word is applied to +the +\fIsigwait\fR() +family of functions. +.P +Allowing the +\fIwait\fR() +family of functions to behave this way permits an implementation to be +able to deal precisely with SIGCHLD signals. +.P +In particular, an implementation that does accept (discard) the SIGCHLD +signal can make the following guarantees regardless of the queuing +depth of signals in general (the list of waitable children can hold the +SIGCHLD queue): +.IP " 1." 4 +If a SIGCHLD signal handler is established via +\fIsigaction\fR() +without the SA_RESETHAND flag, SIGCHLD signals can be accurately +counted; that is, exactly one SIGCHLD signal will be delivered to or +accepted by the process for every child process that terminates. +.IP " 2." 4 +A single +\fIwait\fR() +issued from a SIGCHLD signal handler can be guaranteed to return +immediately with status information for a child process. +.IP " 3." 4 +When SA_SIGINFO is requested, the SIGCHLD signal handler can be +guaranteed to receive a non-null pointer to a +.BR siginfo_t +structure that describes a child process for which a wait via +\fIwaitpid\fR() +or +\fIwaitid\fR() +will not block or fail. +.IP " 4." 4 +The +\fIsystem\fR() +function will not cause the SIGCHLD handler of a process to be +called as a result of the +\fIfork\fR()/\c +.IR exec +executed within +\fIsystem\fR() +because +\fIsystem\fR() +will accept the SIGCHLD signal when it performs a +\fIwaitpid\fR() +for its child process. This is a desirable behavior of +\fIsystem\fR() +so that it can be used in a library without causing side-effects to the +application linked with the library. +.P +An implementation that does not permit the +\fIwait\fR() +family of functions to accept (discard) a pending SIGCHLD signal +associated with a successfully waited-for child, cannot make the +guarantees described above for the following reasons: +.IP "Guarantee #1" 6 +.br +Although it might be assumed that reliable queuing of all SIGCHLD +signals generated by the system can make this guarantee, the +counter-example is the case of a process that blocks SIGCHLD and +performs an indefinite loop of +\fIfork\fR()/\c +\fIwait\fR() +operations. If the implementation supports queued signals, then +eventually the system will run out of memory for the queue. The +guarantee cannot be made because there must be some limit to the depth +of queuing. +.IP "Guarantees #2 and #3" 6 +.br +These cannot be guaranteed unless the +\fIwait\fR() +family of functions accepts the SIGCHLD signal. Otherwise, a +\fIfork\fR()/\c +\fIwait\fR() +executed while SIGCHLD is blocked (as in the +\fIsystem\fR() +function) will result in an invocation of the handler when SIGCHLD is +unblocked, after the process has disappeared. +.IP "Guarantee #4" 6 +.br +Although possible to make this guarantee, +\fIsystem\fR() +would have to set the SIGCHLD handler to SIG_DFL so that the SIGCHLD +signal generated by its +\fIfork\fR() +would be discarded (the SIGCHLD default action is to be ignored), then +restore it to its previous setting. This would have the undesirable +side-effect of discarding all SIGCHLD signals pending to the process. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/waitid.3p b/man-pages-posix-2013-a/man3p/waitid.3p new file mode 100644 index 0000000..555fbf6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/waitid.3p @@ -0,0 +1,212 @@ +'\" et +.TH WAITID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +waitid +\(em wait for a child process to change state +.SH SYNOPSIS +.LP +.nf +#include +.P +int waitid(idtype_t \fIidtype\fP, id_t \fIid\fP, siginfo_t *\fIinfop\fP, int \fIoptions\fP); +.fi +.SH DESCRIPTION +The +\fIwaitid\fR() +function shall suspend the calling thread until one child of the +process containing the calling thread changes state. It records the +current state of a child in the structure pointed to by +.IR infop . +The fields of the structure pointed to by +.IR infop +are filled in as described for the SIGCHLD signal in +.IR . +If a child process changed state prior to the call to +\fIwaitid\fR(), +\fIwaitid\fR() +shall return immediately. If more than one thread is suspended in +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +waiting for termination of the same process, exactly one thread shall +return the process status at the time of the target process termination. +.P +The +.IR idtype +and +.IR id +arguments are used to specify which children +\fIwaitid\fR() +waits for. +.P +If +.IR idtype +is P_PID, +\fIwaitid\fR() +shall wait for the child with a process ID equal to +(\fBpid_t\fP)\fIid\fR. +.P +If +.IR idtype +is P_PGID, +\fIwaitid\fR() +shall wait for any child with a process group ID equal to +(\fBpid_t\fP)\fIid\fR. +.P +If +.IR idtype +is P_ALL, +\fIwaitid\fR() +shall wait for any children and +.IR id +is ignored. +.P +The +.IR options +argument is used to specify which state changes +\fIwaitid\fR() +shall wait for. It is formed by OR'ing together the following flags: +.IP WCONTINUED 12 +Status shall be returned for any continued child process whose status +either has not been reported since it continued from a job control stop +or has been reported only by calls to +\fIwaitid\fR() +with the WNOWAIT flag set. +.IP WEXITED 12 +Wait for processes that have exited. +.IP WNOHANG 12 +Do not hang if no status is available; return immediately. +.IP WNOWAIT 12 +Keep the process whose status is returned in +.IR infop +in a waitable state. This shall not affect the state of the process; the +process may be waited for again after this call completes. +.IP WSTOPPED 12 +Status shall be returned for any child that has stopped upon receipt of +a signal, and whose status either has not been reported since it stopped +or has been reported only by calls to +\fIwaitid\fR() +with the WNOWAIT flag set. +.P +Applications shall specify at least one of the flags WEXITED, WSTOPPED, +or WCONTINUED to be OR'ed in with the +.IR options +argument. +.P +The application shall ensure that the +.IR infop +argument points to a +.BR siginfo_t +structure. If +\fIwaitid\fR() +returns because a child process was found that satisfied the conditions +indicated by the arguments +.IR idtype +and +.IR options , +then the structure pointed to by +.IR infop +shall be filled in by the system with the status of the process; the +.IR si_signo +member shall be set equal to SIGCHLD. +If +\fIwaitid\fR() +returns because WNOHANG was specified and status is not available for +any process specified by +.IR idtype +and +.IR id , +then the +.IR si_signo +and +.IR si_pid +members of the structure pointed to by +.IR infop +shall be set to zero and the values of other members of the structure +are unspecified. +.SH "RETURN VALUE" +If WNOHANG was specified and status is not available for any process +specified by +.IR idtype +and +.IR id , +0 shall be returned. If +\fIwaitid\fR() +returns due to the change of state of one of its children, 0 shall be +returned. Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIwaitid\fR() +function shall fail if: +.TP +.BR ECHILD +The calling process has no existing unwaited-for child processes. +.TP +.BR EINTR +The +\fIwaitid\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +An invalid value was specified for +.IR options , +or +.IR idtype +and +.IR id +specify an invalid set of processes. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Calls to +\fIwaitid\fR() +with +.IR idtype +equal to P_ALL will collect information about any child process. This +may result in interactions with other interfaces that may be waiting +for their own children (such as by use of +\fIsystem\fR()). +For this reason it is recommended that portable applications not use +\fIwaitid\fR() +with idtype of P_ALL. See also APPLICATION USAGE for +\fIwait\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/waitpid.3p b/man-pages-posix-2013-a/man3p/waitpid.3p new file mode 100644 index 0000000..3849009 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/waitpid.3p @@ -0,0 +1,38 @@ +'\" et +.TH WAITPID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +waitpid +\(em wait for a child process to stop or terminate +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t waitpid(pid_t \fIpid\fP, int *\fIstat_loc\fP, int \fIoptions\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwait\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcpcpy.3p b/man-pages-posix-2013-a/man3p/wcpcpy.3p new file mode 100644 index 0000000..fecc385 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcpcpy.3p @@ -0,0 +1,38 @@ +'\" et +.TH WCPCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcpcpy +\(em copy a wide-character string, returning a pointer to its end +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcpcpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcscpy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcpncpy.3p b/man-pages-posix-2013-a/man3p/wcpncpy.3p new file mode 100644 index 0000000..f497d1e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcpncpy.3p @@ -0,0 +1,40 @@ +'\" et +.TH WCPNCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcpncpy +\(em copy a fixed-size wide-character string, returning a pointer +to its end +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcpncpy(wchar_t restrict *\fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcsncpy\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcrtomb.3p b/man-pages-posix-2013-a/man3p/wcrtomb.3p new file mode 100644 index 0000000..6af7974 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcrtomb.3p @@ -0,0 +1,151 @@ +'\" et +.TH WCRTOMB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcrtomb +\(em convert a wide-character code to a character (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcrtomb(char *restrict \fIs\fP, wchar_t \fIwc\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +If +.IR s +is a null pointer, the +\fIwcrtomb\fR() +function shall be equivalent to the call: +.sp +.RS 4 +.nf +\fB +wcrtomb(\fIbuf\fP, L'\e0', \fIps\fP) +.fi \fR +.P +.RE +.P +where +.IR buf +is an internal buffer. +.P +If +.IR s +is not a null pointer, the +\fIwcrtomb\fR() +function shall determine the number of bytes needed to represent the +character that corresponds to the wide character given by +.IR wc +(including any shift sequences), and store the resulting bytes in the +array whose first element is pointed to by +.IR s . +At most +{MB_CUR_MAX} +bytes are stored. If +.IR wc +is a null wide character, a null byte shall be stored, preceded by any +shift sequence needed to restore the initial shift state. The resulting +state described shall be the initial conversion state. +.P +If +.IR ps +is a null pointer, the +\fIwcrtomb\fR() +function shall use its own internal +.BR mbstate_t +object, which is initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. The implementation shall behave as +if no function defined in this volume of POSIX.1\(hy2008 calls +\fIwcrtomb\fR(). +.P +The +\fIwcrtomb\fR() +function need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +The +\fIwcrtomb\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +The +\fIwcrtomb\fR() +function shall return the number of bytes stored in the array object +(including any shift sequences). When +.IR wc +is not a valid wide character, an encoding error shall occur. In this +case, the function shall store the value of the macro +.BR [EILSEQ] +in +.IR errno +and shall return (\fBsize_t\fP)\(mi1; the conversion state shall be +undefined. +.SH ERRORS +The +\fIwcrtomb\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid wide-character code is detected. +.P +The +\fIwcrtomb\fR() +function may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbsinit\fR\^(\|)", +.IR "\fIwcsrtombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcscasecmp.3p b/man-pages-posix-2013-a/man3p/wcscasecmp.3p new file mode 100644 index 0000000..4362bf2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcscasecmp.3p @@ -0,0 +1,158 @@ +'\" et +.TH WCSCASECMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcscasecmp, +wcscasecmp_l, +wcsncasecmp, +wcsncasecmp_l +\(em case-insensitive wide-character string comparison +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcscasecmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +int wcscasecmp_l(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, + locale_t \fIlocale\fP); +int wcsncasecmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +int wcsncasecmp_l(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +The +\fIwcscasecmp\fR() +and +\fIwcsncasecmp\fR() +functions are the wide-character equivalent of the +\fIstrcasecmp\fR() +and +\fIstrncasecmp\fR() +functions, respectively. +.P +The +\fIwcscasecmp\fR() +and +\fIwcscasecmp_l\fR() +functions shall compare, while ignoring differences in case, the +wide-character string pointed to by +.IR ws1 +to the wide-character string pointed to by +.IR ws2 . +.P +The +\fIwcsncasecmp\fR() +and +\fIwcsncasecmp_l\fR() +functions shall compare, while ignoring differences in case, not more +than +.IR n +wide-characters from the wide-character string pointed to by +.IR ws1 +to the wide-character string pointed to by +.IR ws2 . +.P +The +\fIwcscasecmp\fR() +and +\fIwcsncasecmp\fR() +functions use the current locale to determine the case of the wide +characters. +.P +The +\fIwcscasecmp_l\fR() +and +\fIwcsncasecmp_l\fR() +functions use the locale represented by +.IR locale +to determine the case of the wide characters. +.P +When the +.IR LC_CTIME +category of the locale being used is from the POSIX locale, these +functions shall behave as if the wide-character strings had been converted +to lowercase and then a comparison of wide-character codes performed. +Otherwise, the results are unspecified. +.P +The information for +\fIwcscasecmp_l\fR() +and +\fIwcsncasecmp_l\fR() +about the case of the characters comes from the locale represented by +.IR locale . +.P +The behavior is undefined if the +.IR locale +argument to +\fIwcscasecmp_l\fR() +or +\fIwcsncasecmp_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon completion, the +\fIwcscasecmp\fR() +and +\fIwcscasecmp_l\fR() +functions shall return an integer greater than, equal to, or less than 0 +if the wide-character string pointed to by +.IR ws1 +is, ignoring case, greater than, equal to, or less than the +wide-character string pointed to by +.IR ws2 , +respectively. +.P +Upon completion, the +\fIwcsncasecmp\fR() +and +\fIwcsncasecmp_l\fR() +functions shall return an integer greater than, equal to, or less than 0 +if the possibly null wide-character terminated string pointed to by +.IR ws1 +is, ignoring case, greater than, equal to, or less than the possibly +null wide-character terminated string pointed to by +.IR ws2 , +respectively. +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcasecmp\fR\^(\|)", +.IR "\fIwcscmp\fR\^(\|)", +.IR "\fIwcsncmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcscat.3p b/man-pages-posix-2013-a/man3p/wcscat.3p new file mode 100644 index 0000000..3474716 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcscat.3p @@ -0,0 +1,76 @@ +'\" et +.TH WCSCAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcscat +\(em concatenate two wide-character strings +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcscat(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcscat\fR() +function shall append a copy of the wide-character string pointed to by +.IR ws2 +(including the terminating null wide-character code) to the end of the +wide-character string pointed to by +.IR ws1 . +The initial wide-character code of +.IR ws2 +shall overwrite the null wide-character code at the end of +.IR ws1 . +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fIwcscat\fR() +function shall return +.IR ws1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcsncat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcschr.3p b/man-pages-posix-2013-a/man3p/wcschr.3p new file mode 100644 index 0000000..30c60ad --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcschr.3p @@ -0,0 +1,75 @@ +'\" et +.TH WCSCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcschr +\(em wide-character string scanning operation +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcschr(const wchar_t *\fIws\fP, wchar_t \fIwc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcschr\fR() +function shall locate the first occurrence of +.IR wc +in the wide-character string pointed to by +.IR ws . +The application shall ensure that the value of +.IR wc +is a character representable as a type +.BR wchar_t +and a wide-character code corresponding to a valid character in the +current locale. The terminating null wide-character code is considered +to be part of the wide-character string. +.SH "RETURN VALUE" +Upon completion, +\fIwcschr\fR() +shall return a pointer to the wide-character code, or a null pointer if +the wide-character code is not found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcsrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcscmp.3p b/man-pages-posix-2013-a/man3p/wcscmp.3p new file mode 100644 index 0000000..53cdbee --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcscmp.3p @@ -0,0 +1,78 @@ +'\" et +.TH WCSCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcscmp +\(em compare two wide-character strings +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcscmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcscmp\fR() +function shall compare the wide-character string pointed to by +.IR ws1 +to the wide-character string pointed to by +.IR ws2 . +.P +The sign of a non-zero return value shall be determined by the sign of +the difference between the values of the first pair of wide-character +codes that differ in the objects being compared. +.SH "RETURN VALUE" +Upon completion, +\fIwcscmp\fR() +shall return an integer greater than, equal to, or less than 0, if the +wide-character string pointed to by +.IR ws1 +is greater than, equal to, or less than the wide-character string +pointed to by +.IR ws2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscasecmp\fR\^(\|)", +.IR "\fIwcsncmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcscoll.3p b/man-pages-posix-2013-a/man3p/wcscoll.3p new file mode 100644 index 0000000..43614a7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcscoll.3p @@ -0,0 +1,135 @@ +'\" et +.TH WCSCOLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcscoll, +wcscoll_l +\(em wide-character string comparison using collating information +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcscoll(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +int wcscoll_l(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIwcscoll\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +functions shall compare the wide-character string pointed to by +.IR ws1 +to the wide-character string pointed to by +.IR ws2 , +both interpreted as appropriate to the +.IR LC_COLLATE +category of the current locale, +or the locale represented by +.IR locale , +respectively. +.P +The +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +An application wishing to check for error situations should set +.IR errno +to 0 before calling +\fIwcscoll\fR() +or +\fIwcscoll_l\fR(). +If +.IR errno +is non-zero on return, an error has occurred. +.P +The behavior is undefined if the +.IR locale +argument to +\fIwcscoll_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +shall return an integer greater than, equal to, or less than 0, +according to whether the wide-character string pointed to by +.IR ws1 +is greater than, equal to, or less than the wide-character string +pointed to by +.IR ws2 , +when both are interpreted as appropriate to the current locale, +or to the locale represented by +.IR locale , +respectively. On error, +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +shall set +.IR errno , +but no return value is reserved to indicate an error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The +.IR ws1 +or +.IR ws2 +arguments contain wide-character codes outside the domain of the +collating sequence. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIwcsxfrm\fR() +and +\fIwcscmp\fR() +functions should be used for sorting large lists. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscmp\fR\^(\|)", +.IR "\fIwcsxfrm\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcscpy.3p b/man-pages-posix-2013-a/man3p/wcscpy.3p new file mode 100644 index 0000000..0b021b2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcscpy.3p @@ -0,0 +1,99 @@ +'\" et +.TH WCSCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcpcpy, wcscpy +\(em copy a wide-character string, returning a pointer to its end +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcpcpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP); +wchar_t *wcscpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP); +.fi +.SH DESCRIPTION +For +\fIwcscpy\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcpcpy\fR() +and +\fIwcscpy\fR() +functions shall copy the wide-character string pointed to by +.IR ws2 +(including the terminating null wide-character code) into the array +pointed to by +.IR ws1 . +.P +The application shall ensure that there is room for at least +.IR wcslen (\c +.IR ws2 )\(pl1 +wide characters in the +.IR ws1 +array, and that the +.IR ws2 +and +.IR ws1 +arrays do not overlap. +.P +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fIwcpcpy\fR() +function shall return a pointer to the terminating null wide-character +code copied into the +.IR ws1 +buffer. +.P +The +\fIwcscpy\fR() +function shall return +.IR ws1 . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcpy\fR\^(\|)", +.IR "\fIwcsdup\fR\^(\|)", +.IR "\fIwcsncpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcscspn.3p b/man-pages-posix-2013-a/man3p/wcscspn.3p new file mode 100644 index 0000000..2c39fd1 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcscspn.3p @@ -0,0 +1,72 @@ +'\" et +.TH WCSCSPN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcscspn +\(em get the length of a complementary wide substring +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcscspn(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcscspn\fR() +function shall compute the length (in wide characters) of the maximum +initial segment of the wide-character string pointed to by +.IR ws1 +which consists entirely of wide-character codes +.IR not +from the wide-character string pointed to by +.IR ws2 . +.SH "RETURN VALUE" +The +\fIwcscspn\fR() +function shall return the length of the initial substring of +.IR ws1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcsspn\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsdup.3p b/man-pages-posix-2013-a/man3p/wcsdup.3p new file mode 100644 index 0000000..efd9ce2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsdup.3p @@ -0,0 +1,91 @@ +'\" et +.TH WCSDUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsdup +\(em duplicate a wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcsdup(const wchar_t *\fIstring\fP); +.fi +.SH DESCRIPTION +The +\fIwcsdup\fR() +function is the wide-character equivalent of the +\fIstrdup\fR() +function. +.P +The +\fIwcsdup\fR() +function shall return a pointer to a new wide-character string, +allocated as if by a call to +\fImalloc\fR(), +which is the duplicate of the wide-character string +.IR string . +The returned pointer can be passed to +\fIfree\fR(). +A null pointer is returned if the new wide-character string cannot be +created. +.SH "RETURN VALUE" +Upon successful completion, the +\fIwcsdup\fR() +function shall return a pointer to the newly allocated wide-character +string. Otherwise, it shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIwcsdup\fR() +function shall fail if: +.TP +.BR ENOMEM +Memory large enough for the duplicate string could not be allocated. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIwcsdup\fR(), +this is the return value. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fIstrdup\fR\^(\|)", +.IR "\fIwcscpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsftime.3p b/man-pages-posix-2013-a/man3p/wcsftime.3p new file mode 100644 index 0000000..d4d557b --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsftime.3p @@ -0,0 +1,94 @@ +'\" et +.TH WCSFTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsftime +\(em convert date and time to a wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsftime(wchar_t *restrict \fIwcs\fP, size_t \fImaxsize\fP, + const wchar_t *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcsftime\fR() +function shall be equivalent to the +\fIstrftime\fR() +function, except that: +.IP " *" 4 +The argument +.IR wcs +points to the initial element of an array of wide characters into which +the generated output is to be placed. +.IP " *" 4 +The argument +.IR maxsize +indicates the maximum number of wide characters to be placed in the +output array. +.IP " *" 4 +The argument +.IR format +is a wide-character string and the conversion specifications are +replaced by corresponding sequences of wide characters. +.IP " *" 4 +The return value indicates the number of wide characters placed in the +output array. +.P +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +If the total number of resulting wide-character codes including the +terminating null wide-character code is no more than +.IR maxsize , +\fIwcsftime\fR() +shall return the number of wide-character codes placed into the array +pointed to by +.IR wcs , +not including the terminating null wide-character code. Otherwise, +zero is returned and the contents of the array are unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrftime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcslen.3p b/man-pages-posix-2013-a/man3p/wcslen.3p new file mode 100644 index 0000000..f15b173 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcslen.3p @@ -0,0 +1,96 @@ +'\" et +.TH WCSLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcslen, wcsnlen +\(em get length of a fixed-sized wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcslen(const wchar_t *\fIws\fP); +size_t wcsnlen(const wchar_t *\fIws\fP, size_t \fImaxlen\fP); +.fi +.SH DESCRIPTION +For +\fIwcslen\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcslen\fR() +function shall compute the number of wide-character codes in the +wide-character string to which +.IR ws +points, not including the terminating null wide-character code. +.P +The +\fIwcsnlen\fR() +function shall compute the smaller of the number of wide characters in +the string to which +.IR ws +points, not including the terminating null wide-character code, and the +value of +.IR maxlen . +The +\fIwcsnlen\fR() +function shall never examine more than the first +.IR maxlen +characters of the wide-character string pointed to by +.IR ws . +.SH "RETURN VALUE" +The +\fIwcslen\fR() +function shall return the length of +.IR ws . +.P +The +\fIwcsnlen\fR() +function shall return an integer containing the smaller of either the +length of the wide-character string pointed to by +.IR ws +or +.IR maxlen . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrlen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsncasecmp.3p b/man-pages-posix-2013-a/man3p/wcsncasecmp.3p new file mode 100644 index 0000000..e77728f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsncasecmp.3p @@ -0,0 +1,41 @@ +'\" et +.TH WCSNCASECMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsncasecmp, +wcsncasecmp_l +\(em case-insensitive wide-character string comparison +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcsncasecmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +int wcsncasecmp_l(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcscasecmp\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsncat.3p b/man-pages-posix-2013-a/man3p/wcsncat.3p new file mode 100644 index 0000000..ef2324f --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsncat.3p @@ -0,0 +1,80 @@ +'\" et +.TH WCSNCAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsncat +\(em concatenate a wide-character string with part of another +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcsncat(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcsncat\fR() +function shall append not more than +.IR n +wide-character codes (a null wide-character code and wide-character +codes that follow it are not appended) from the array pointed to by +.IR ws2 +to the end of the wide-character string pointed to by +.IR ws1 . +The initial wide-character code of +.IR ws2 +shall overwrite the null wide-character code at the end of +.IR ws1 . +A terminating null wide-character code shall always be appended to the +result. If copying takes place between objects that overlap, the +behavior is undefined. +.SH "RETURN VALUE" +The +\fIwcsncat\fR() +function shall return +.IR ws1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsncmp.3p b/man-pages-posix-2013-a/man3p/wcsncmp.3p new file mode 100644 index 0000000..0517cab --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsncmp.3p @@ -0,0 +1,81 @@ +'\" et +.TH WCSNCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsncmp +\(em compare part of two wide-character strings +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcsncmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcsncmp\fR() +function shall compare not more than +.IR n +wide-character codes (wide-character codes that follow a null +wide-character code are not compared) from the array pointed to by +.IR ws1 +to the array pointed to by +.IR ws2 . +.P +The sign of a non-zero return value shall be determined by the sign of +the difference between the values of the first pair of wide-character +codes that differ in the objects being compared. +.SH "RETURN VALUE" +Upon successful completion, +\fIwcsncmp\fR() +shall return an integer greater than, equal to, or less than 0, if the +possibly null-terminated array pointed to by +.IR ws1 +is greater than, equal to, or less than the possibly null-terminated +array pointed to by +.IR ws2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscasecmp\fR\^(\|)", +.IR "\fIwcscmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsncpy.3p b/man-pages-posix-2013-a/man3p/wcsncpy.3p new file mode 100644 index 0000000..d5b6383 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsncpy.3p @@ -0,0 +1,106 @@ +'\" et +.TH WCSNCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcpncpy, wcsncpy +\(em copy a fixed-size wide-character string, returning a pointer +to its end +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcpncpy(wchar_t restrict *\fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +wchar_t *wcsncpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +For +\fIwcsncpy\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcpncpy\fR() +and +\fIwcsncpy\fR() +functions shall copy not more than +.IR n +wide-character codes (wide-character codes that follow a null +wide-character code are not copied) from the array pointed to by +.IR ws2 +to the array pointed to by +.IR ws1 . +If copying takes place between objects that overlap, the behavior is +undefined. +.P +If the array pointed to by +.IR ws2 +is a wide-character string that is shorter than +.IR n +wide-character codes, null wide-character codes shall be appended to +the copy in the array pointed to by +.IR ws1 , +until +.IR n +wide-character codes in all are written. +.SH "RETURN VALUE" +If any null wide-character codes were written into the +destination, the +\fIwcpncpy\fR() +function shall return the address of the first such null wide-character +code. Otherwise, it shall return +.IR &ws1 [ n ]. +.P +The +\fIwcsncpy\fR() +function shall return +.IR ws1 . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If there is no null wide-character code in the first +.IR n +wide-character codes of the array pointed to by +.IR ws2 , +the result is not null-terminated. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrncpy\fR\^(\|)", +.IR "\fIwcscpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsnlen.3p b/man-pages-posix-2013-a/man3p/wcsnlen.3p new file mode 100644 index 0000000..fdd919d --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsnlen.3p @@ -0,0 +1,38 @@ +'\" et +.TH WCSNLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsnlen +\(em get length of a fixed-sized wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsnlen(const wchar_t *\fIws\fP, size_t \fImaxlen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcslen\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsnrtombs.3p b/man-pages-posix-2013-a/man3p/wcsnrtombs.3p new file mode 100644 index 0000000..51895d3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsnrtombs.3p @@ -0,0 +1,39 @@ +'\" et +.TH WCSNRTOMBS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsnrtombs +\(em convert wide-character string to multi-byte string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsnrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP, + size_t \fInwc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcsrtombs\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcspbrk.3p b/man-pages-posix-2013-a/man3p/wcspbrk.3p new file mode 100644 index 0000000..e2f8723 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcspbrk.3p @@ -0,0 +1,73 @@ +'\" et +.TH WCSPBRK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcspbrk +\(em scan a wide-character string for a wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcspbrk(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcspbrk\fR() +function shall locate the first occurrence in the wide-character string +pointed to by +.IR ws1 +of any wide-character code from the wide-character string pointed to by +.IR ws2 . +.SH "RETURN VALUE" +Upon successful completion, +\fIwcspbrk\fR() +shall return a pointer to the wide-character code or a null pointer if +no wide-character code from +.IR ws2 +occurs in +.IR ws1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcschr\fR\^(\|)", +.IR "\fIwcsrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsrchr.3p b/man-pages-posix-2013-a/man3p/wcsrchr.3p new file mode 100644 index 0000000..5b7ed7a --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsrchr.3p @@ -0,0 +1,76 @@ +'\" et +.TH WCSRCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsrchr +\(em wide-character string scanning operation +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcsrchr(const wchar_t *\fIws\fP, wchar_t \fIwc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcsrchr\fR() +function shall locate the last occurrence of +.IR wc +in the wide-character string pointed to by +.IR ws . +The application shall ensure that the value of +.IR wc +is a character representable as a type +.BR wchar_t +and a wide-character code corresponding to a valid character in the +current locale. The terminating null wide-character code shall be +considered to be part of the wide-character string. +.SH "RETURN VALUE" +Upon successful completion, +\fIwcsrchr\fR() +shall return a pointer to the wide-character code or a null pointer if +.IR wc +does not occur in the wide-character string. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcschr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsrtombs.3p b/man-pages-posix-2013-a/man3p/wcsrtombs.3p new file mode 100644 index 0000000..99fd761 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsrtombs.3p @@ -0,0 +1,165 @@ +'\" et +.TH WCSRTOMBS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsnrtombs, wcsrtombs +\(em convert a wide-character string to a character string (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsnrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP, + size_t \fInwc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +size_t wcsrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP, + size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +For +\fIwcsrtombs\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcsrtombs\fR() +function shall convert a sequence of wide characters from the array +indirectly pointed to by +.IR src +into a sequence of corresponding characters, beginning in the +conversion state described by the object pointed to by +.IR ps . +If +.IR dst +is not a null pointer, the converted characters shall then be +stored into the array pointed to by +.IR dst . +Conversion continues up to and including a terminating null wide +character, which shall also be stored. Conversion shall stop +earlier in the following cases: +.IP " *" 4 +When a code is reached that does not correspond to a valid character +.IP " *" 4 +When the next character would exceed the limit of +.IR len +total bytes to be stored in the array pointed to by +.IR dst +(and +.IR dst +is not a null pointer) +.P +Each conversion shall take place as if by a call to the +\fIwcrtomb\fR() +function. +.P +If +.IR dst +is not a null pointer, the pointer object pointed to by +.IR src +shall be assigned either a null pointer (if conversion stopped due to +reaching a terminating null wide character) or the address just past +the last wide character converted (if any). If conversion stopped due +to reaching a terminating null wide character, the resulting state +described shall be the initial conversion state. +.P +If +.IR ps +is a null pointer, the +\fIwcsrtombs\fR() +function shall use its own internal +.BR mbstate_t +object, which is initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. +.P +The +\fIwcsnrtombs\fR() +and +\fIwcsrtombs\fR() +functions need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The +\fIwcsnrtombs\fR() +function shall be equivalent to the +\fIwcsrtombs\fR() +function, except that the conversion is limited to the first +.IR nwc +wide characters. +.P +The +\fIwcsrtombs\fR() +function shall not change the setting of +.IR errno +if successful. +.P +The behavior of these functions shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +The implementation shall behave as if no function defined in System Interfaces volume of POSIX.1\(hy2008 +calls these functions. +.SH "RETURN VALUE" +If conversion stops because a code is reached that does not correspond +to a valid character, an encoding error occurs. In this case, these +functions shall store the value of the macro +.BR [EILSEQ] +in +.IR errno +and return (\fBsize_t\fP)\(mi1; the conversion state is undefined. +Otherwise, these functions shall return the number of bytes in the +resulting character sequence, not including the terminating null (if any). +.SH ERRORS +These functions shall fail if: +.TP +.BR EILSEQ +A wide-character code does not correspond to a valid character. +.P +These functions may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbsinit\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsspn.3p b/man-pages-posix-2013-a/man3p/wcsspn.3p new file mode 100644 index 0000000..034dad3 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsspn.3p @@ -0,0 +1,71 @@ +'\" et +.TH WCSSPN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsspn +\(em get the length of a wide substring +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsspn(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcsspn\fR() +function shall compute the length (in wide characters) of the +maximum initial segment of the wide-character string pointed to by +.IR ws1 +which consists entirely of wide-character codes from the wide-character +string pointed to by +.IR ws2 . +.SH "RETURN VALUE" +The +\fIwcsspn\fR() +function shall return the length of the initial substring of +.IR ws1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscspn\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsstr.3p b/man-pages-posix-2013-a/man3p/wcsstr.3p new file mode 100644 index 0000000..8bd8b60 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsstr.3p @@ -0,0 +1,77 @@ +'\" et +.TH WCSSTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsstr +\(em find a wide-character substring +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcsstr(const wchar_t *restrict \fIws1\fP, + const wchar_t *restrict \fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcsstr\fR() +function shall locate the first occurrence in the wide-character string +pointed to by +.IR ws1 +of the sequence of wide characters (excluding the terminating null wide +character) in the wide-character string pointed to by +.IR ws2 . +.SH "RETURN VALUE" +Upon successful completion, +\fIwcsstr\fR() +shall return a pointer to the located wide-character string, or a null +pointer if the wide-character string is not found. +.P +If +.IR ws2 +points to a wide-character string with zero length, the function +shall return +.IR ws1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcschr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstod.3p b/man-pages-posix-2013-a/man3p/wcstod.3p new file mode 100644 index 0000000..a52ac29 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstod.3p @@ -0,0 +1,267 @@ +'\" et +.TH WCSTOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstod, +wcstof, +wcstold +\(em convert a wide-character string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +double wcstod(const wchar_t *restrict \fInptr\fP, wchar_t **restrict \fIendptr\fP); +float wcstof(const wchar_t *restrict \fInptr\fP, wchar_t **restrict \fIendptr\fP); +long double wcstold(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the wide-character +string pointed to by +.IR nptr +to +.BR double , +.BR float , +and +.BR "long double" +representation, respectively. First, they shall decompose the input +wide-character string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by +\fIiswspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as a floating-point constant or +representing infinity or NaN +.IP " 3." 4 +A final wide-character string of one or more unrecognized wide-character +codes, including the terminating null wide-character code of the input +wide-character string +.P +Then they shall attempt to convert the subject sequence to a +floating-point number, and return the result. +.P +The expected form of the subject sequence is an optional +.BR '+' +or +.BR '\(mi' +sign, then one of the following: +.IP " *" 4 +A non-empty sequence of decimal digits optionally containing a radix +character; then an optional exponent part consisting of the wide +character +.BR 'e' +or the wide character +.BR 'E' , +optionally followed by a +.BR '+' +or +.BR '\(mi' +wide character, and then followed by one or more decimal digits +.IP " *" 4 +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character; then an optional binary exponent part +consisting of the wide character +.BR 'p' +or the wide character +.BR 'P' , +optionally followed by a +.BR '+' +or +.BR '\(mi' +wide character, and then followed by one or more decimal digits +.IP " *" 4 +One of INF or INFINITY, or any other wide string equivalent except for +case +.IP " *" 4 +One of NAN or NAN(\fIn-wchar-sequence\s-3\dopt\u\s+3\fR), or any other +wide string ignoring case in the NAN part, where: +.RS 4 +.sp +.RS 4 +.nf +\fB +n-wchar-sequence: + digit + nondigit + n-wchar-sequence digit + n-wchar-sequence nondigit +.fi \fR +.P +.RE +.RE +.P +The subject sequence is defined as the longest initial subsequence of +the input wide string, starting with the first non-white-space wide +character, that is of the expected form. The subject sequence contains +no wide characters if the input wide string is not of the expected +form. +.P +If the subject sequence has the expected form for a floating-point +number, the sequence of wide characters starting with the first digit +or the radix character (whichever occurs first) shall be interpreted as +a floating constant according to the rules of the C language, except +that the radix character shall be used in place of a period, and that +if neither an exponent part nor a radix character appears in a decimal +floating-point number, or if a binary exponent part does not appear in +a hexadecimal floating-point number, an exponent part of the +appropriate type with value zero shall be assumed to follow the last +digit in the string. If the subject sequence begins with a minus-sign, +the sequence shall be interpreted as negated. A wide-character sequence +INF or INFINITY shall be interpreted as an infinity, if representable +in the return type, else as if it were a floating constant that is too +large for the range of the return type. A wide-character sequence NAN +or NAN(\fIn-wchar-sequence\s-3\dopt\u\s+3\fR) shall be interpreted as a +quiet NaN, if supported in the return type, else as if it were a +subject sequence part that does not have the expected form; the meaning +of the \fIn\fP-wchar sequences is implementation-defined. A pointer to +the final wide string shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +If the subject sequence has the hexadecimal form and FLT_RADIX is a +power of 2, the conversion shall be rounded in an +implementation-defined manner. +.P +The radix character shall be as defined in the current locale +(category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +In other than the C +or POSIX +locales, other implementation-defined subject sequences may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0 is returned on error and is also a valid return on success, +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcstod\fR(), +\fIwcstof\fR(), +or +\fIwcstold\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +\(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL shall be returned +(according to the sign of the value), and +.IR errno +shall be set to +.BR [ERANGE] . +.P +If the correct value would cause underflow, a value whose magnitude is +no greater than the smallest normalized positive number in the return +type shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +The +\fIwcstod\fR() +function shall fail if: +.TP +.BR ERANGE +The value to be returned would cause overflow or underflow. +.P +The +\fIwcstod\fR() +function may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the subject sequence has the hexadecimal form and FLT_RADIX is not a +power of 2, and the result is not exactly representable, the result +should be one of the two numbers in the appropriate internal format +that are adjacent to the hexadecimal floating source value, with the +extra stipulation that the error should have a correct sign for the +current rounding direction. +.P +If the subject sequence has the decimal form and at most DECIMAL_DIG +(defined in +.IR ) +significant digits, the result should be correctly rounded. If the +subject sequence \fID\fP has the decimal form and more than DECIMAL_DIG +significant digits, consider the two bounding, adjacent decimal strings +\fIL\fP and \fIU\fP, both having DECIMAL_DIG significant digits, such +that the values of \fIL\fP, \fID\fP, and \fIU\fP satisfy +.BR \(dqL <= D <= U\(dq . +The result should be one of the (equal or adjacent) values that would +be obtained by correctly rounding \fIL\fP and \fIU\fP according to the +current rounding direction, with the extra stipulation that the error +with respect to \fID\fP should have a correct sign for the current +rounding direction. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstoimax.3p b/man-pages-posix-2013-a/man3p/wcstoimax.3p new file mode 100644 index 0000000..8800679 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstoimax.3p @@ -0,0 +1,103 @@ +'\" et +.TH WCSTOIMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstoimax, +wcstoumax +\(em convert a wide-character string to an integer type +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +intmax_t wcstoimax(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +uintmax_t wcstoumax(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall be equivalent to the +\fIwcstol\fR(), +\fIwcstoll\fR(), +\fIwcstoul\fR(), +and +\fIwcstoull\fR() +functions, respectively, except that the initial portion of the wide +string shall be converted to +.BR intmax_t +and +.BR uintmax_t +representation, respectively. +.SH "RETURN VALUE" +These functions shall return the converted value, if any. +.P +If no conversion could be performed, zero shall be returned. If the +correct value is outside the range of representable values, +{INTMAX_MAX}, +{INTMAX_MIN}, +or +{UINTMAX_MAX} +shall be returned (according to the return type and sign of the value, +if any), and +.IR errno +shall be set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcstol\fR\^(\|)", +.IR "\fIwcstoul\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstok.3p b/man-pages-posix-2013-a/man3p/wcstok.3p new file mode 100644 index 0000000..f3d34d0 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstok.3p @@ -0,0 +1,122 @@ +'\" et +.TH WCSTOK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstok +\(em split a wide-character string into tokens +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcstok(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + wchar_t **restrict \fIptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +A sequence of calls to +\fIwcstok\fR() +shall break the wide-character string pointed to by +.IR ws1 +into a sequence of tokens, each of which shall be delimited by a +wide-character code from the wide-character string pointed to by +.IR ws2 . +The +.IR ptr +argument points to a caller-provided +.BR wchar_t +pointer into which the +\fIwcstok\fR() +function shall store information necessary for it to continue +scanning the same wide-character string. +.P +The first call in the sequence has +.IR ws1 +as its first argument, and is followed by calls with a null pointer as +their first argument. The separator string pointed to by +.IR ws2 +may be different from call to call. +.P +The first call in the sequence shall search the wide-character string +pointed to by +.IR ws1 +for the first wide-character code that is +.IR not +contained in the current separator string pointed to by +.IR ws2 . +If no such wide-character code is found, then there are no tokens in +the wide-character string pointed to by +.IR ws1 +and +\fIwcstok\fR() +shall return a null pointer. If such a wide-character code is found, +it shall be the start of the first token. +.P +The +\fIwcstok\fR() +function shall then search from there for a wide-character code that +.IR is +contained in the current separator string. If no such wide-character +code is found, the current token extends to the end of the +wide-character string pointed to by +.IR ws1 , +and subsequent searches for a token shall return a null pointer. If +such a wide-character code is found, it shall be overwritten by a null +wide character, which terminates the current token. The +\fIwcstok\fR() +function shall save a pointer to the following wide-character code, +from which the next search for a token shall start. +.P +Each subsequent call, with a null pointer as the value of the first +argument, shall start searching from the saved pointer and behave as +described above. +.P +The implementation shall behave as if no function calls +\fIwcstok\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fIwcstok\fR() +function shall return a pointer to the first wide-character code of a +token. Otherwise, if there is no token, +\fIwcstok\fR() +shall return a null pointer. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstol.3p b/man-pages-posix-2013-a/man3p/wcstol.3p new file mode 100644 index 0000000..3b9befb --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstol.3p @@ -0,0 +1,229 @@ +'\" et +.TH WCSTOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstol, +wcstoll +\(em convert a wide-character string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long wcstol(const wchar_t *restrict \fInptr\fP, wchar_t **restrict \fIendptr\fP, + int \fIbase\fP); +long long wcstoll(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the wide-character +string pointed to by +.IR nptr +to +.BR long +and +.BR "long long" , +respectively. First, they shall decompose the input string into three +parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by +\fIiswspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of +.IR base +.IP " 3." 4 +A final wide-character string of one or more unrecognized +wide-character codes, including the terminating null wide-character +code of the input wide-character string +.P +Then they shall attempt to convert the subject sequence to an +integer, and return the result. +.P +If +.IR base +is 0, the expected form of the subject sequence is that of a decimal +constant, octal constant, or hexadecimal constant, any of which may be +preceded by a +.BR '+' +or +.BR '\(mi' +sign. A decimal constant begins with a non-zero digit, and consists of +a sequence of decimal digits. An octal constant consists of the prefix +.BR '0' +optionally followed by a sequence of the digits +.BR '0' +to +.BR '7' +only. A hexadecimal constant consists of the prefix 0x or 0X followed +by a sequence of the decimal digits and letters +.BR 'a' +(or +.BR 'A' ) +to +.BR 'f' +(or +.BR 'F' ) +with values 10 to 15 respectively. +.P +If the value of +.IR base +is between 2 and 36, the expected form of the subject sequence is a +sequence of letters and digits representing an integer with the radix +specified by +.IR base , +optionally preceded by a +.BR '+' +or +.BR '\(mi' +sign, but not including an integer suffix. The letters from +.BR 'a' +(or +.BR 'A' ) +to +.BR 'z' +(or +.BR 'Z' ) +inclusive are ascribed the values 10 to 35; only letters whose ascribed +values are less than that of +.IR base +shall be permitted. If the value of +.IR base +is 16, the wide-character code representations of 0x or 0X may +optionally precede the sequence of letters and digits, following the +sign if present. +.P +The subject sequence is defined as the longest initial subsequence of +the input wide-character string, starting with the first +non-white-space wide-character code that is of the expected form. The +subject sequence contains no wide-character codes if the input +wide-character string is empty or consists entirely of white-space +wide-character code, or if the first non-white-space wide-character +code is other than a sign or a permissible letter or digit. +.P +If the subject sequence has the expected form and +.IR base +is 0, the sequence of wide-character codes starting with the first +digit shall be interpreted as an integer constant. If the subject +sequence has the expected form and the value of +.IR base +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a minus-sign, the value resulting from the +conversion shall be negated. A pointer to the final wide-character +string shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +In other than the C +or POSIX +locales, other implementation-defined subject sequences may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0, +{LONG_MIN} +or +{LLONG_MIN} +and +{LONG_MAX} +or +{LLONG_MAX} +are returned on error and are also valid returns on success, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcstol\fR() +or +\fIwcstoll\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to indicate the error. +If the correct value is outside the range of representable values, +{LONG_MIN}, +{LONG_MAX}, +{LLONG_MIN}, +or +{LLONG_MAX} +shall be returned (according to the sign of the value), and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstold.3p b/man-pages-posix-2013-a/man3p/wcstold.3p new file mode 100644 index 0000000..19047ba --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstold.3p @@ -0,0 +1,39 @@ +'\" et +.TH WCSTOLD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstold +\(em convert a wide-character string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +long double wcstold(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcstod\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstoll.3p b/man-pages-posix-2013-a/man3p/wcstoll.3p new file mode 100644 index 0000000..1c49609 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstoll.3p @@ -0,0 +1,39 @@ +'\" et +.TH WCSTOLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstoll +\(em convert a wide-character string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long long wcstoll(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcstol\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstombs.3p b/man-pages-posix-2013-a/man3p/wcstombs.3p new file mode 100644 index 0000000..f893097 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstombs.3p @@ -0,0 +1,111 @@ +'\" et +.TH WCSTOMBS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstombs +\(em convert a wide-character string to a character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcstombs(char *restrict \fIs\fP, const wchar_t *restrict \fIpwcs\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcstombs\fR() +function shall convert the sequence of wide-character codes that are +in the array pointed to by +.IR pwcs +into a sequence of characters that begins in the initial shift state +and store these characters into the array pointed to by +.IR s , +stopping if a character would exceed the limit of +.IR n +total bytes or if a null byte is stored. Each wide-character code +shall be converted as if by a call to +\fIwctomb\fR(), +except that the shift state of +\fIwctomb\fR() +shall not be affected. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +No more than +.IR n +bytes shall be modified in the array pointed to by +.IR s . +If copying takes place between objects that overlap, the behavior is +undefined. +If +.IR s +is a null pointer, +\fIwcstombs\fR() +shall return the length required to convert the entire array +regardless of the value of +.IR n , +but no values are stored. +.SH "RETURN VALUE" +If a wide-character code is encountered that does not correspond to a +valid character (of one or more bytes each), +\fIwcstombs\fR() +shall return (\fBsize_t\fP)\(mi1. Otherwise, +\fIwcstombs\fR() +shall return the number of bytes stored in the character array, not +including any terminating null byte. The array shall not be +null-terminated if the value returned is +.IR n . +.SH ERRORS +The +\fIwcstombs\fR() +function shall fail if: +.TP +.BR EILSEQ +A wide-character code does not correspond to a valid character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImblen\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstoul.3p b/man-pages-posix-2013-a/man3p/wcstoul.3p new file mode 100644 index 0000000..ee0d510 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstoul.3p @@ -0,0 +1,231 @@ +'\" et +.TH WCSTOUL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstoul, +wcstoull +\(em convert a wide-character string to an unsigned long +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned long wcstoul(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +unsigned long long wcstoull(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcstoul\fR() +and +\fIwcstoull\fR() +functions shall convert the initial portion of the wide-character +string pointed to by +.IR nptr +to +.BR "unsigned long" +and +.BR "unsigned long long" +representation, respectively. First, they shall decompose the input +wide-character string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by +\fIiswspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of +.IR base +.IP " 3." 4 +A final wide-character string of one or more unrecognized +wide-character codes, including the terminating null wide-character +code of the input wide-character string +.P +Then they shall attempt to convert the subject sequence to an +unsigned integer, and return the result. +.P +If +.IR base +is 0, the expected form of the subject sequence is that of a decimal +constant, octal constant, or hexadecimal constant, any of which may be +preceded by a +.BR '+' +or +.BR '\(mi' +sign. A decimal constant begins with a non-zero digit, and consists of +a sequence of decimal digits. An octal constant consists of the prefix +.BR '0' +optionally followed by a sequence of the digits +.BR '0' +to +.BR '7' +only. A hexadecimal constant consists of the prefix 0x or 0X followed +by a sequence of the decimal digits and letters +.BR 'a' +(or +.BR 'A' ) +to +.BR 'f' +(or +.BR 'F' ) +with values 10 to 15 respectively. +.P +If the value of +.IR base +is between 2 and 36, the expected form of the subject sequence is a +sequence of letters and digits representing an integer with the radix +specified by +.IR base , +optionally preceded by a +.BR '+' +or +.BR '\(mi' +sign, but not including an integer suffix. The letters from +.BR 'a' +(or +.BR 'A' ) +to +.BR 'z' +(or +.BR 'Z' ) +inclusive are ascribed the values 10 to 35; only letters whose ascribed +values are less than that of +.IR base +shall be permitted. If the value of +.IR base +is 16, the wide-character codes 0x or 0X may optionally precede the +sequence of letters and digits, following the sign if present. +.P +The subject sequence is defined as the longest initial subsequence of +the input wide-character string, starting with the first wide-character +code that is not white space and is of the expected form. The subject +sequence contains no wide-character codes if the input wide-character +string is empty or consists entirely of white-space wide-character +codes, or if the first wide-character code that is not white space is +other than a sign or a permissible letter or digit. +.P +If the subject sequence has the expected form and +.IR base +is 0, the sequence of wide-character codes starting with the first +digit shall be interpreted as an integer constant. If the subject +sequence has the expected form and the value of +.IR base +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a minus-sign, the value resulting from the +conversion shall be negated. A pointer to the final wide-character +string shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +In other than the C +or POSIX +locales, other implementation-defined subject sequences may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0, +{ULONG_MAX}, +and +{ULLONG_MAX} +are returned on error and 0 is also a valid return on success, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcstoul\fR() +or +\fIwcstoull\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, the +\fIwcstoul\fR() +and +\fIwcstoull\fR() +functions shall return the converted value, if any. If no conversion +could be performed, 0 shall be returned +and +.IR errno +may be set to indicate the error. +If the correct value is outside the range of representable values, +{ULONG_MAX} +or +{ULLONG_MAX} +respectively shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcstoumax.3p b/man-pages-posix-2013-a/man3p/wcstoumax.3p new file mode 100644 index 0000000..6e999b7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcstoumax.3p @@ -0,0 +1,40 @@ +'\" et +.TH WCSTOUMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcstoumax +\(em convert a wide-character string to an integer type +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +uintmax_t wcstoumax(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcstoimax\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcswidth.3p b/man-pages-posix-2013-a/man3p/wcswidth.3p new file mode 100644 index 0000000..1195140 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcswidth.3p @@ -0,0 +1,79 @@ +'\" et +.TH WCSWIDTH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcswidth +\(em number of column positions of a wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcswidth(const wchar_t *\fIpwcs\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The +\fIwcswidth\fR() +function shall determine the number of column positions required for +.IR n +wide-character codes (or fewer than +.IR n +wide-character codes if a null wide-character code is encountered +before +.IR n +wide-character codes are exhausted) in the string pointed to by +.IR pwcs . +.SH "RETURN VALUE" +The +\fIwcswidth\fR() +function either shall return 0 (if +.IR pwcs +points to a null wide-character code), or return the number of column +positions to be occupied by the wide-character string pointed to by +.IR pwcs , +or return \(mi1 (if any of the first +.IR n +wide-character codes in the wide-character string pointed to by +.IR pwcs +is not a printable wide-character code). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +This function was removed from the final ISO/IEC\ 9899:\|1990/Amendment 1:\|1995 (E), and the return value +for a non-printable wide character is not specified. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcwidth\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.103" ", " "Column Position", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcsxfrm.3p b/man-pages-posix-2013-a/man3p/wcsxfrm.3p new file mode 100644 index 0000000..eee5259 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcsxfrm.3p @@ -0,0 +1,161 @@ +'\" et +.TH WCSXFRM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcsxfrm, +wcsxfrm_l +\(em wide-character string transformation +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsxfrm(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +size_t wcsxfrm_l(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIwcsxfrm\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwcsxfrm\fR() +and +\fIwcsxfrm_l\fR() +functions shall transform the wide-character string pointed to by +.IR ws2 +and place the resulting wide-character string into the array pointed to +by +.IR ws1 . +The transformation shall be such that if +\fIwcscmp\fR() +is applied to two transformed wide strings, it shall return a value +greater than, equal to, or less than 0, corresponding to the result of +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +applied to the same two original wide-character strings, and the same +.IR LC_COLLATE +category of the current locale +or the locale object +.IR locale , +respectively. No more than +.IR n +wide-character codes shall be placed into the resulting array pointed +to by +.IR ws1 , +including the terminating null wide-character code. If +.IR n +is 0, +.IR ws1 +is permitted to be a null pointer. If copying takes place between +objects that overlap, the behavior is undefined. +.P +The +\fIwcsxfrm\fR() +and +\fIwcsxfrm_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcsxfrm\fR() +or +\fIwcsxfrm_l\fR(), +then check +.IR errno . +.P +The behavior is undefined if the +.IR locale +argument to +\fIwcsxfrm_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIwcsxfrm\fR() +and +\fIwcsxfrm_l\fR() +functions shall return the length of the transformed wide-character +string (not including the terminating null wide-character code). If the +value returned is +.IR n +or more, the contents of the array pointed to by +.IR ws1 +are unspecified. +.P +On error, the +\fIwcsxfrm\fR() +and +\fIwcsxfrm_l\fR() +functions may set +.IR errno , +but no return value is reserved to indicate an error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The wide-character string pointed to by +.IR ws2 +contains wide-character codes outside the domain of the collating +sequence. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The transformation function is such that two transformed wide-character +strings can be ordered by +\fIwcscmp\fR() +as appropriate to collating sequence information in the current locale +(category +.IR LC_COLLATE ). +.P +The fact that when +.IR n +is 0 +.IR ws1 +is permitted to be a null pointer is useful to determine the size of +the +.IR ws1 +array prior to making the transformation. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscmp\fR\^(\|)", +.IR "\fIwcscoll\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wctob.3p b/man-pages-posix-2013-a/man3p/wctob.3p new file mode 100644 index 0000000..9943bc7 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wctob.3p @@ -0,0 +1,80 @@ +'\" et +.TH WCTOB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wctob +\(em wide-character to single-byte conversion +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int wctob(wint_t \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwctob\fR() +function shall determine whether +.IR c +corresponds to a member of the extended character set whose character +representation is a single byte when in the initial shift state. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +.SH "RETURN VALUE" +The +\fIwctob\fR() +function shall return EOF if +.IR c +does not correspond to a character with length one in the initial shift +state. Otherwise, it shall return the single-byte representation of +that character as an +.BR "unsigned char" +converted to +.BR int . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbtowc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wctomb.3p b/man-pages-posix-2013-a/man3p/wctomb.3p new file mode 100644 index 0000000..d24da98 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wctomb.3p @@ -0,0 +1,127 @@ +'\" et +.TH WCTOMB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wctomb +\(em convert a wide-character code to a character +.SH SYNOPSIS +.LP +.nf +#include +.P +int wctomb(char *\fIs\fP, wchar_t \fIwchar\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwctomb\fR() +function shall determine the number of bytes needed to represent the +character corresponding to the wide-character code whose value is +.IR wchar +(including any change in the shift state). It shall store the character +representation (possibly multiple bytes and any special bytes to change +shift state) in the array object pointed to by +.IR s +(if +.IR s +is not a null pointer). At most +{MB_CUR_MAX} +bytes shall be stored. If +.IR wchar +is 0, a null byte shall be stored, preceded by any shift sequence +needed to restore the initial shift state, and +\fIwctomb\fR() +shall be left in the initial shift state. +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. For a state-dependent encoding, this +function shall be placed into its initial state by a call for which its +character pointer argument, +.IR s , +is a null pointer. Subsequent calls with +.IR s +as other than a null pointer shall cause the internal state of the +function to be altered as necessary. A call with +.IR s +as a null pointer shall cause this function to return a non-zero value +if encodings have state dependency, and 0 otherwise. Changing the +.IR LC_CTYPE +category causes the shift state of this function to be unspecified. +.P +The +\fIwctomb\fR() +function need not be thread-safe. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 +calls +\fIwctomb\fR(). +.SH "RETURN VALUE" +If +.IR s +is a null pointer, +\fIwctomb\fR() +shall return a non-zero or 0 value, if character encodings, +respectively, do or do not have state-dependent encodings. If +.IR s +is not a null pointer, +\fIwctomb\fR() +shall return \(mi1 if the value of +.IR wchar +does not correspond to a valid character, or return the number of +bytes that constitute the character corresponding to the value of +.IR wchar . +.P +In no case shall the value returned be greater than the value of the +{MB_CUR_MAX} +macro. +.SH ERRORS +The +\fIwctomb\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid wide-character code is detected. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImblen\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wctrans.3p b/man-pages-posix-2013-a/man3p/wctrans.3p new file mode 100644 index 0000000..1a5313c --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wctrans.3p @@ -0,0 +1,139 @@ +'\" et +.TH WCTRANS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wctrans, +wctrans_l +\(em define character mapping +.SH SYNOPSIS +.LP +.nf +#include +.P +wctrans_t wctrans(const char *\fIcharclass\fP); +wctrans_t wctrans_l(const char *\fIcharclass\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIwctrans\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwctrans\fR() +and +\fIwctrans_l\fR() +functions are defined for valid character mapping names identified +in the current locale. The +.IR charclass +is a string identifying a generic character mapping name for which +codeset-specific information is required. The following character +mapping names are defined in all locales: +.BR tolower +and +.BR toupper . +.P +These functions shall return a value of type +.BR wctrans_t , +which can be used as the second argument to subsequent calls of +\fItowctrans\fR() +and +\fItowctrans_l\fR(). +.P +The +\fIwctrans\fR() +and +\fIwctrans_l\fR() +functions shall determine values of +.BR wctrans_t +according to the rules of the coded character set defined by character +mapping information in the current locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ). +.P +The values returned by +\fIwctrans\fR() +shall be valid until a call to +\fIsetlocale\fR() +that modifies the category +.IR LC_CTYPE . +.P +The values returned by +\fIwctrans_l\fR() +shall be valid only in calls to +\fItowctrans_l\fR() +with a locale represented by +.IR locale +with the same +.IR LC_CTYPE +category value. +.P +The behavior is undefined if the +.IR locale +argument to +\fIwctrans_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIwctrans\fR() +and +\fIwctrans_l\fR() +functions shall return 0 and may set +.IR errno +to indicate the error if the given character mapping name is not valid +for the current locale (category +.IR LC_CTYPE ); +otherwise, they shall return a non-zero object of type +.BR wctrans_t +that can be used in calls to +\fItowctrans\fR() +and +\fItowctrans_l\fR(). +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The character mapping name pointed to by +.IR charclass +is not valid in the current locale. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItowctrans\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wctype.3p b/man-pages-posix-2013-a/man3p/wctype.3p new file mode 100644 index 0000000..7aed3fd --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wctype.3p @@ -0,0 +1,166 @@ +'\" et +.TH WCTYPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wctype, +wctype_l +\(em define character class +.SH SYNOPSIS +.LP +.nf +#include +.P +wctype_t wctype(const char *\fIproperty\fP); +wctype_t wctype_l(const char *\fIproperty\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIwctype\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwctype\fR() +and +\fIwctype_l\fR() +functions are defined for valid character class names as defined +in the current locale +or in the locale represented by +.IR locale , +respectively. +.P +The +.IR property +argument is a string identifying a generic character class for which +codeset-specific type information is required. The following character +class names shall be defined in all locales: +.sp +.RS +.TS +tab(!); +lB lB lB. +T{ +.nf +alnum +alpha +blank +cntrl +T}!T{ +.nf +digit +graph +lower +print +T}!T{ +.nf +punct +space +upper +xdigit +.fi +T} +.TE +.RE +.P +Additional character class names defined in the locale definition file +(category +.IR LC_CTYPE ) +can also be specified. +.P +These functions shall return a value of type +.BR wctype_t , +which can be used as the second argument to subsequent calls of +\fIiswctype\fR() +and +\fIiswctype_l\fR(). +.P +The +\fIwctype\fR() +and +\fIwctype_l\fR() +functions shall determine values of +.BR wctype_t +according to the rules of the coded character set defined by character +type information in the current locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ). +.P +The values returned by +\fIwctype\fR() +shall be valid until a call to +\fIsetlocale\fR() +that modifies the category +.IR LC_CTYPE . +.P +The values returned by +\fIwctype_l\fR() +shall be valid only in calls to +\fIiswctype_l\fR() +with a locale represented by +.IR locale +with the same +.IR LC_CTYPE +category value. +.P +The behavior is undefined if the +.IR locale +argument to +\fIwctype_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIwctype\fR() +and +\fIwctype_l\fR() +functions shall return 0 if the given character class name is not +valid for the current locale (category +.IR LC_CTYPE ); +otherwise, they shall return an object of type +.BR wctype_t +that can be used in calls to +\fIiswctype\fR() +and +\fIiswctype_l\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswctype\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wcwidth.3p b/man-pages-posix-2013-a/man3p/wcwidth.3p new file mode 100644 index 0000000..7424201 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wcwidth.3p @@ -0,0 +1,76 @@ +'\" et +.TH WCWIDTH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wcwidth +\(em number of column positions of a wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcwidth(wchar_t \fIwc\fP); +.fi +.SH DESCRIPTION +The +\fIwcwidth\fR() +function shall determine the number of column positions required for +the wide character +.IR wc . +The application shall ensure that the value of +.IR wc +is a character representable as a +.BR wchar_t , +and is a wide-character code corresponding to a valid character in +the current locale. +.SH "RETURN VALUE" +The +\fIwcwidth\fR() +function shall either return 0 (if +.IR wc +is a null wide-character code), or return the number of column +positions to be occupied by the wide-character code +.IR wc , +or return \(mi1 (if +.IR wc +does not correspond to a printable wide-character code). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +This function was removed from the final ISO/IEC\ 9899:\|1990/Amendment 1:\|1995 (E), and the return value +for a non-printable wide character is not specified. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcswidth\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wmemchr.3p b/man-pages-posix-2013-a/man3p/wmemchr.3p new file mode 100644 index 0000000..ab27e57 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wmemchr.3p @@ -0,0 +1,88 @@ +'\" et +.TH WMEMCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wmemchr +\(em find a wide character in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wmemchr(const wchar_t *\fIws\fP, wchar_t \fIwc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwmemchr\fR() +function shall locate the first occurrence of +.IR wc +in the initial +.IR n +wide characters of the object pointed to by +.IR ws . +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws +is a valid pointer and the function behaves as if no valid +occurrence of +.IR wc +is found. +.SH "RETURN VALUE" +The +\fIwmemchr\fR() +function shall return a pointer to the located wide character, or a null +pointer if the wide character does not occur in the object. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wmemcmp.3p b/man-pages-posix-2013-a/man3p/wmemcmp.3p new file mode 100644 index 0000000..6b86191 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wmemcmp.3p @@ -0,0 +1,93 @@ +'\" et +.TH WMEMCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wmemcmp +\(em compare wide characters in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +int wmemcmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwmemcmp\fR() +function shall compare the first +.IR n +wide characters of the object pointed to by +.IR ws1 +to the first +.IR n +wide characters of the object pointed to by +.IR ws2 . +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws1 +and +.IR ws2 +are valid pointers, and the function shall behave as if the two +objects compare equal. +.SH "RETURN VALUE" +The +\fIwmemcmp\fR() +function shall return an integer greater than, equal to, or less than +zero, respectively, as the object pointed to by +.IR ws1 +is greater than, equal to, or less than the object pointed to by +.IR ws2 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wmemcpy.3p b/man-pages-posix-2013-a/man3p/wmemcpy.3p new file mode 100644 index 0000000..3648a74 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wmemcpy.3p @@ -0,0 +1,88 @@ +'\" et +.TH WMEMCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wmemcpy +\(em copy wide characters in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wmemcpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwmemcpy\fR() +function shall copy +.IR n +wide characters from the object pointed to by +.IR ws2 +to the object pointed to by +.IR ws1 . +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws1 +and +.IR ws2 +are valid pointers, and the function shall copy zero wide characters. +.SH "RETURN VALUE" +The +\fIwmemcpy\fR() +function shall return the value of +.IR ws1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wmemmove.3p b/man-pages-posix-2013-a/man3p/wmemmove.3p new file mode 100644 index 0000000..66d26e9 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wmemmove.3p @@ -0,0 +1,103 @@ +'\" et +.TH WMEMMOVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wmemmove +\(em copy wide characters in memory with overlapping areas +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wmemmove(wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwmemmove\fR() +function shall copy +.IR n +wide characters from the object pointed to by +.IR ws2 +to the object pointed to by +.IR ws1 . +Copying shall take place as if the +.IR n +wide characters from the object pointed to by +.IR ws2 +are first copied into a temporary array of +.IR n +wide characters that does not overlap the objects pointed to by +.IR ws1 +or +.IR ws2 , +and then the +.IR n +wide characters from the temporary array are copied into the object +pointed to by +.IR ws1 . +.P +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws1 +and +.IR ws2 +are valid pointers, and the function shall copy zero wide characters. +.SH "RETURN VALUE" +The +\fIwmemmove\fR() +function shall return the value of +.IR ws1 . +.SH ERRORS +No errors are defined +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wmemset.3p b/man-pages-posix-2013-a/man3p/wmemset.3p new file mode 100644 index 0000000..c359e82 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wmemset.3p @@ -0,0 +1,85 @@ +'\" et +.TH WMEMSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wmemset +\(em set wide characters in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wmemset(wchar_t *\fIws\fP, wchar_t \fIwc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The +\fIwmemset\fR() +function shall copy the value of +.IR wc +into each of the first +.IR n +wide characters of the object pointed to by +.IR ws . +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws +is a valid pointer, and the function shall copy zero wide characters. +.SH "RETURN VALUE" +The +\fIwmemset\fR() +functions shall return the value of +.IR ws . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wordexp.3p b/man-pages-posix-2013-a/man3p/wordexp.3p new file mode 100644 index 0000000..96090a2 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wordexp.3p @@ -0,0 +1,489 @@ +'\" et +.TH WORDEXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wordexp, +wordfree +\(em perform word expansions +.SH SYNOPSIS +.LP +.nf +#include +.P +int wordexp(const char *restrict \fIwords\fP, wordexp_t *restrict \fIpwordexp\fP, + int \fIflags\fP); +void wordfree(wordexp_t *\fIpwordexp\fP); +.fi +.SH DESCRIPTION +The +\fIwordexp\fR() +function shall perform word expansions as described in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.6" ", " "Word Expansions", +subject to quoting as described in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "Quoting", +and place the list of expanded words into the structure pointed to by +.IR pwordexp . +.P +The +.IR words +argument is a pointer to a string containing one or more words to be +expanded. The expansions shall be the same as would be performed by the +command line interpreter if +.IR words +were the part of a command line representing the arguments to a +utility. Therefore, the application shall ensure that +.IR words +does not contain an unquoted + +character or any of the unquoted shell special characters +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' +except in the context of command substitution as specified in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.6.3" ", " "Command Substitution". +It also shall not contain unquoted parentheses or braces, except +in the context of command or variable substitution. The application +shall ensure that every member of +.IR words +which it expects to have expanded by +\fIwordexp\fR() +does not contain an unquoted initial comment character. The application +shall also ensure that any words which it intends to be ignored +(because they begin or continue a comment) are deleted from +.IR words . +If the argument +.IR words +contains an unquoted comment character (\c +) +that is the beginning of a token, +\fIwordexp\fR() +shall either treat the comment character as a regular character, or +interpret it as a comment indicator and ignore the remainder of +.IR words . +.P +The structure type +.BR wordexp_t +is defined in the +.IR +header and includes at least the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +size_t!we_wordc!Count of words matched by \fIwords\fP. +char **!we_wordv!Pointer to list of expanded words. +size_t!we_offs!T{ +Slots to reserve at the beginning of \fIpwordexp\fP\->\fIwe_wordv\fR. +T} +.TE +.P +The +\fIwordexp\fR() +function shall store the number of generated words into +\fIpwordexp\fP\->\fIwe_wordc\fP and a pointer to a list of pointers to +words in \fIpwordexp\fP\->\fIwe_wordv\fP. Each individual field created +during field splitting (see the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.6.5" ", " "Field Splitting") +or pathname expansion (see the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.6.6" ", " "Pathname Expansion") +shall be a separate word in the \fIpwordexp\fP\->\fIwe_wordv\fP +list. The words shall be in order as described in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.6" ", " "Word Expansions". +The first pointer after the last word pointer shall be a null pointer. +The expansion of special parameters described in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.5.2" ", " "Special Parameters" +is unspecified. +.P +It is the caller's responsibility to allocate the storage pointed to by +.IR pwordexp . +The +\fIwordexp\fR() +function shall allocate other space as needed, including memory +pointed to by \fIpwordexp\fP\->\fIwe_wordv\fP. The +\fIwordfree\fR() +function frees any memory associated with +.IR pwordexp +from a previous call to +\fIwordexp\fR(). +.P +The +.IR flags +argument is used to control the behavior of +\fIwordexp\fR(). +The value of +.IR flags +is the bitwise-inclusive OR of zero or more of the following constants, +which are defined in +.IR : +.IP WRDE_APPEND 14 +Append words generated to the ones from a previous call to +\fIwordexp\fR(). +.IP WRDE_DOOFFS 14 +Make use of \fIpwordexp\fP\->\fIwe_offs\fP. If this flag is set, +\fIpwordexp\fP\->\fIwe_offs\fP is used to specify how many null +pointers to add to the beginning of \fIpwordexp\fP\->\fIwe_wordv\fP. +In other words, \fIpwordexp\fP\->\fIwe_wordv\fP shall point to +\fIpwordexp\fP\->\fIwe_offs\fP null pointers, followed by +\fIpwordexp\fP\->\fIwe_wordc\fP word pointers, followed by a null +pointer. +.IP WRDE_NOCMD 14 +If the implementation supports the utilities defined in the Shell and Utilities volume of POSIX.1\(hy2008, +fail if command substitution, as specified in the Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Section 2.6.3" ", " "Command Substitution", +is requested. +.IP WRDE_REUSE 14 +The +.IR pwordexp +argument was passed to a previous successful call to +\fIwordexp\fR(), +and has not been passed to +\fIwordfree\fR(). +The result shall be the same as if the application had called +\fIwordfree\fR() +and then called +\fIwordexp\fR() +without WRDE_REUSE. +.IP WRDE_SHOWERR 14 +Do not redirect +.IR stderr +to +.BR /dev/null . +.IP WRDE_UNDEF 14 +Report error on an attempt to expand an undefined shell variable. +.P +The WRDE_APPEND flag can be used to append a new set of words to those +generated by a previous call to +\fIwordexp\fR(). +The following rules apply to applications when two or more calls to +\fIwordexp\fR() +are made with the same value of +.IR pwordexp +and without intervening calls to +\fIwordfree\fR(): +.IP " 1." 4 +The first such call shall not set WRDE_APPEND. All subsequent calls +shall set it. +.IP " 2." 4 +All of the calls shall set WRDE_DOOFFS, or all shall not set it. +.IP " 3." 4 +After the second and each subsequent call, +\fIpwordexp\fP\->\fIwe_wordv\fP shall point to a list containing the +following: +.RS 4 +.IP " a." 4 +Zero or more null pointers, as specified by WRDE_DOOFFS and +\fIpwordexp\fP\->\fIwe_offs\fP +.IP " b." 4 +Pointers to the words that were in the \fIpwordexp\fP\->\fIwe_wordv\fP +list before the call, in the same order as before +.IP " c." 4 +Pointers to the new words generated by the latest call, in the +specified order +.RE +.IP " 4." 4 +The count returned in \fIpwordexp\fP\->\fIwe_wordc\fP shall be the +total number of words from all of the calls. +.IP " 5." 4 +The application can change any of the fields after a call to +\fIwordexp\fR(), +but if it does it shall reset them to the original value before a +subsequent call, using the same +.IR pwordexp +value, to +\fIwordfree\fR() +or +\fIwordexp\fR() +with the WRDE_APPEND or WRDE_REUSE flag. +.P +If the implementation supports the utilities defined in the Shell and Utilities volume of POSIX.1\(hy2008, +and +.IR words +contains an unquoted character\(em\c +, +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' , +.BR '(' , +.BR ')' , +.BR '{' , +.BR '}' \(em\c +in an inappropriate context, +\fIwordexp\fR() +shall fail, and the number of expanded words shall be 0. +.P +Unless WRDE_SHOWERR is set in +.IR flags , +\fIwordexp\fR() +shall redirect +.IR stderr +to +.BR /dev/null +for any utilities executed as a result of command substitution while +expanding +.IR words . +If WRDE_SHOWERR is set, +\fIwordexp\fR() +may write messages to +.IR stderr +if syntax errors are detected while expanding +.IR words ; +however, it is unspecified whether any write errors encountered while +outputting such messages will affect the +.IR stderr +error indicator or the value of +.IR errno . +.P +The application shall ensure that if WRDE_DOOFFS is set, then +\fIpwordexp\fP\->\fIwe_offs\fP has the same value for each +\fIwordexp\fR() +call and +\fIwordfree\fR() +call using a given +.IR pwordexp . +.br +.P +The following constants are defined as error return values: +.IP WRDE_BADCHAR 14 +One of the unquoted characters\(em\c +, +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' , +.BR '(' , +.BR ')' , +.BR '{' , +.BR '}' \(em\c +appears in +.IR words +in an inappropriate context. +.IP WRDE_BADVAL 14 +Reference to undefined shell variable when WRDE_UNDEF is set in +.IR flags . +.IP WRDE_CMDSUB 14 +Command substitution requested when WRDE_NOCMD was set in +.IR flags . +.IP WRDE_NOSPACE 14 +Attempt to allocate memory failed. +.IP WRDE_SYNTAX 14 +Shell syntax error, such as unbalanced parentheses or unterminated +string. +.SH "RETURN VALUE" +Upon successful completion, +\fIwordexp\fR() +shall return 0. Otherwise, a non-zero value, as described in +.IR , +shall be returned to indicate an error. If +\fIwordexp\fR() +returns the value WRDE_NOSPACE, then \fIpwordexp\fP\->\fIwe_wordc\fP +and \fIpwordexp\fP\->\fIwe_wordv\fP shall be updated to reflect any +words that were successfully expanded. In other cases, they shall not +be modified. +.P +The +\fIwordfree\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIwordexp\fR() +function is intended to be used by an application that wants to do all +of the shell's expansions on a word or words obtained from a user. For +example, if the application prompts for a pathname (or list of +pathnames) and then uses +\fIwordexp\fR() +to process the input, the user could respond with anything that would +be valid as input to the shell. +.P +The WRDE_NOCMD flag is provided for applications that, for security or +other reasons, want to prevent a user from executing shell commands. +Disallowing unquoted shell special characters also prevents unwanted +side-effects, such as executing a command or writing a file. +.P +POSIX.1\(hy2008 does not require the +\fIwordexp\fR() +function to be thread-safe if passed an expression referencing an +environment variable while any other thread is concurrently modifying +any environment variable; see +.IR "\fIexec\fR\^". +.P +Even though the WRDE_SHOWERR flag allows the implementation to write +messages to +.IR stderr +during command substitution or syntax errors, this standard does not +provide any way to detect write failures during the output of such +messages. +.SH RATIONALE +This function was included as an alternative to +\fIglob\fR(). +There had been continuing controversy over exactly what features should +be included in +\fIglob\fR(). +It is hoped that by providing +\fIwordexp\fR() +(which provides all of the shell word expansions, but which may be slow +to execute) and +\fIglob\fR() +(which is faster, but which only performs pathname expansion, without +tilde or parameter expansion) this will satisfy the majority of +applications. +.P +While +\fIwordexp\fR() +could be implemented entirely as a library routine, it is expected that +most implementations run a shell in a subprocess to do the expansion. +.P +Two different approaches have been proposed for how the required +information might be presented to the shell and the results returned. +They are presented here as examples. +.P +One proposal is to extend the +.IR echo +utility by adding a +.BR \(miq +option. This option would cause +.IR echo +to add a + +before each + +and + +that occurs within an argument. The +\fIwordexp\fR() +function could then invoke the shell as follows: +.sp +.RS 4 +.nf +\fB +(void) strcpy(buffer, "echo -q"); +(void) strcat(buffer, \fIwords\fP); +if ((flags & WRDE_SHOWERR) == 0) + (void) strcat(buffer, "2>/dev/null"); +f = popen(buffer, "r"); +.fi \fR +.P +.RE +.P +The +\fIwordexp\fR() +function would read the resulting output, remove unquoted + +characters, and break into words at unquoted + +characters. If the WRDE_NOCMD flag was set, +\fIwordexp\fR() +would have to scan +.IR words +before starting the subshell to make sure that there would be no +command substitution. In any case, it would have to scan +.IR words +for unquoted special characters. +.P +Another proposal is to add the following options to +.IR sh : +.IP "\fB\(miw\fP\ \fIwordlist\fR" 6 +.br +This option provides a wordlist expansion service to applications. The +words in +.IR wordlist +shall be expanded and the following written to standard output: +.RS 6 +.IP " 1." 4 +The count of the number of words after expansion, in decimal, followed +by a null byte +.IP " 2." 4 +The number of bytes needed to represent the expanded words (not +including null separators), in decimal, followed by a null byte +.IP " 3." 4 +The expanded words, each terminated by a null byte +.P +If an error is encountered during word expansion, +.IR sh +exits with a non-zero status after writing the former to report any +words successfully expanded +.RE +.IP "\fB\(miP\fP" 6 +Run in ``protected'' mode. If specified with the +.BR \(miw +option, no command substitution shall be performed. +.P +With these options, +\fIwordexp\fR() +could be implemented fairly simply by creating a subprocess using +\fIfork\fR() +and executing +.IR sh +using the line: +.sp +.RS 4 +.nf +\fB +execl(<\fIshell path\fP>, "sh", "-P", "-w", \fIwords\fP, (char *)0); +.fi \fR +.P +.RE +.P +after directing standard error to +.BR /dev/null . +.P +It seemed objectionable for a library routine to write messages to +standard error, unless explicitly requested, so +\fIwordexp\fR() +is required to redirect standard error to +.BR /dev/null +to ensure that no messages are generated, even for commands executed +for command substitution. The WRDE_SHOWERR flag can be specified to +request that error messages be written. +.P +The WRDE_REUSE flag allows the implementation to avoid the expense of +freeing and reallocating memory, if that is possible. A minimal +implementation can call +\fIwordfree\fR() +when WRDE_REUSE is set. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfnmatch\fR\^(\|)", +.IR "\fIglob\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Chapter 2" ", " "Shell Command Language" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wprintf.3p b/man-pages-posix-2013-a/man3p/wprintf.3p new file mode 100644 index 0000000..85a89a6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wprintf.3p @@ -0,0 +1,39 @@ +'\" et +.TH WPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wprintf +\(em print formatted wide-character output +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int wprintf(const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfwprintf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/write.3p b/man-pages-posix-2013-a/man3p/write.3p new file mode 100644 index 0000000..5a07dd4 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/write.3p @@ -0,0 +1,735 @@ +'\" et +.TH WRITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pwrite, +write +\(em write on a file +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t pwrite(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP, + off_t \fIoffset\fP); +ssize_t write(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP); +.fi +.SH DESCRIPTION +The +\fIwrite\fR() +function shall attempt to write +.IR nbyte +bytes from the buffer pointed to by +.IR buf +to the file associated with the open file descriptor, +.IR fildes . +.P +Before any action described below is taken, and if +.IR nbyte +is zero and the file is a regular file, the +\fIwrite\fR() +function may detect and return errors as described below. In the +absence of errors, or if error detection is not performed, the +\fIwrite\fR() +function shall return zero and have no other results. If +.IR nbyte +is zero and the file is not a regular file, the results are +unspecified. +.P +On a regular file or other file capable of seeking, the actual writing +of data shall proceed from the position in the file indicated by the +file offset associated with +.IR fildes . +Before successful return from +\fIwrite\fR(), +the file offset shall be incremented by the number of bytes actually +written. On a regular file, if the position of the last byte written +is greater than or equal to the length of the file, +the length of the file shall be set to this position plus one. +.P +On a file not capable of seeking, writing shall always take place +starting at the current position. The value of a file offset associated +with such a device is undefined. +.P +If the O_APPEND flag of the file status flags is set, +the file offset shall be set to the end of the file prior to each write +and no intervening file modification operation shall occur between +changing the file offset and the write operation. +.P +If a +\fIwrite\fR() +requests that more bytes be written than there is room for (for +example, +the file size limit of the process or +the physical end of a medium), only as many bytes as there is room for +shall be written. For example, suppose there is space for 20 bytes more +in a file before reaching a limit. A write of 512 bytes will return +20. The next write of a non-zero number of bytes would give a failure +return (except as noted below). +.P +If the request would cause the file size to exceed the soft file size +limit for the process and there is no room for any bytes to be written, +the request shall fail and the implementation shall generate the +SIGXFSZ signal for the thread. +.P +If +\fIwrite\fR() +is interrupted by a signal before it writes any data, it shall +return \(mi1 with +.IR errno +set to +.BR [EINTR] . +.P +If +\fIwrite\fR() +is interrupted by a signal after it successfully writes some data, it +shall return the number of bytes written. +.P +If the value of +.IR nbyte +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +After a +\fIwrite\fR() +to a regular file has successfully returned: +.IP " *" 4 +Any successful +\fIread\fR() +from each byte position in the file that was modified by that write +shall return the data specified by the +\fIwrite\fR() +for that position until such byte positions are again modified. +.IP " *" 4 +Any subsequent successful +\fIwrite\fR() +to the same byte position in the file shall overwrite that file data. +.br +.P +Write requests to a pipe or FIFO shall be handled in the same way +as a regular file with the following exceptions: +.IP " *" 4 +There is no file offset associated with a pipe, hence each write +request shall append to the end of the pipe. +.IP " *" 4 +Write requests of +{PIPE_BUF} +bytes or less shall not be interleaved with data from other processes +doing writes on the same pipe. Writes of greater than +{PIPE_BUF} +bytes may have data interleaved, on arbitrary boundaries, with writes +by other processes, whether or not the O_NONBLOCK flag of the file +status flags is set. +.IP " *" 4 +If the O_NONBLOCK flag is clear, a write request may cause the thread +to block, but on normal completion it shall return +.IR nbyte . +.IP " *" 4 +If the O_NONBLOCK flag is set, +\fIwrite\fR() +requests shall be handled differently, in the following ways: +.RS 4 +.IP -- 4 +The +\fIwrite\fR() +function shall not block the thread. +.IP -- 4 +A write request for +{PIPE_BUF} +or fewer bytes shall have the following effect: if there is sufficient +space available in the pipe, +\fIwrite\fR() +shall transfer all the data and return the number of bytes requested. +Otherwise, +\fIwrite\fR() +shall transfer no data and return \(mi1 with +.IR errno +set to +.BR [EAGAIN] . +.IP -- 4 +A write request for more than +{PIPE_BUF} +bytes shall cause one of the following: +.RS 4 +.IP -- 4 +When at least one byte can be written, transfer what it can and return +the number of bytes written. When all data previously written to the +pipe is read, it shall transfer at least +{PIPE_BUF} +bytes. +.IP -- 4 +When no data can be written, transfer no data, and return \(mi1 with +.IR errno +set to +.BR [EAGAIN] . +.RE +.RE +.P +When attempting to write to a file descriptor (other than a pipe or +FIFO) that supports non-blocking writes and cannot accept the data +immediately: +.IP " *" 4 +If the O_NONBLOCK flag is clear, +\fIwrite\fR() +shall block the calling thread until the data can be accepted. +.IP " *" 4 +If the O_NONBLOCK flag is set, +\fIwrite\fR() +shall not block the thread. If some data can be written without +blocking the thread, +\fIwrite\fR() +shall write what it can and return the number of bytes written. +Otherwise, it shall return \(mi1 and set +.IR errno +to +.BR [EAGAIN] . +.P +Upon successful completion, where +.IR nbyte +is greater than 0, +\fIwrite\fR() +shall mark for update the last data modification and last file +status change timestamps of the file, and if the file is a regular file, +the S_ISUID and S_ISGID bits of the file mode may be cleared. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +.IR fildes . +.P +If +.IR fildes +refers to a socket, +\fIwrite\fR() +shall be equivalent to +\fIsend\fR() +with no flags set. +.P +If the O_DSYNC bit has been set, +write I/O operations on the file descriptor shall complete as defined +by synchronized I/O data integrity completion. +.P +If the O_SYNC bit has been set, write I/O operations on the file +descriptor shall complete as defined by synchronized I/O file +integrity completion. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIwrite\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIwrite\fR() +function is unspecified. +.P +If +.IR fildes +refers to a STREAM, the operation of +\fIwrite\fR() +shall be determined by the values of the minimum and maximum +.IR nbyte +range (packet size) accepted by the STREAM. These values are determined +by the topmost STREAM module. If +.IR nbyte +falls within the packet size range, +.IR nbyte +bytes shall be written. If +.IR nbyte +does not fall within the range and the minimum packet size value is 0, +\fIwrite\fR() +shall break the buffer into maximum packet size segments prior to +sending the data downstream (the last segment may contain less than the +maximum packet size). If +.IR nbyte +does not fall within the range and the minimum value is non-zero, +\fIwrite\fR() +shall fail with +.IR errno +set to +.BR [ERANGE] . +Writing a zero-length buffer (\c +.IR nbyte +is 0) to a STREAMS device sends 0 bytes with 0 returned. However, +writing a zero-length buffer to a STREAMS-based pipe or FIFO sends no +message and 0 is returned. The process may issue I_SWROPT +\fIioctl\fR() +to enable zero-length messages to be sent across the pipe or FIFO. +.P +When writing to a STREAM, data messages are created with a priority +band of 0. When writing to a STREAM that is not a pipe or FIFO: +.IP " *" 4 +If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM +write queue is full due to internal flow control conditions), +\fIwrite\fR() +shall block until data can be accepted. +.IP " *" 4 +If O_NONBLOCK is set and the STREAM cannot accept data, +\fIwrite\fR() +shall return \(mi1 and set +.IR errno +to +.BR [EAGAIN] . +.IP " *" 4 +If O_NONBLOCK is set and part of the buffer has been written while a +condition in which the STREAM cannot accept additional data occurs, +\fIwrite\fR() +shall terminate and return the number of bytes written. +.P +In addition, +\fIwrite\fR() +shall fail if the STREAM head has processed an asynchronous error +before the call. In this case, the value of +.IR errno +does not reflect the result of +\fIwrite\fR(), +but reflects the prior error. +.P +The +\fIpwrite\fR() +function shall be equivalent to +\fIwrite\fR(), +except that it writes into a given position and does not change the +file offset (regardless of whether O_APPEND is set). The first three +arguments to +\fIpwrite\fR() +are the same as +\fIwrite\fR() +with the addition of a fourth argument +.IR offset +for the desired position inside the file. An attempt to perform a +\fIpwrite\fR() +on a file that is incapable of seeking shall result in an error. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the number of +bytes actually written to the file associated with +.IR fildes . +This number shall never be greater than +.IR nbyte . +Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EAGAIN +The file is neither a pipe, nor a FIFO, nor a socket, the O_NONBLOCK flag +is set for the file descriptor, and the thread would be delayed in the +\fIwrite\fR() +operation. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor open for writing. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the +implementation-defined maximum file size +or the file size limit of the process, +and there was no room for any bytes to be written. +.TP +.BR EFBIG +The file is a regular file, +.IR nbyte +is greater than 0, and the starting position is greater than or equal +to the offset maximum established in the open file description +associated with +.IR fildes . +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the calling thread +is not blocking SIGTTOU, the process is not ignoring SIGTTOU, +and the process group of the process is orphaned. This error may also +be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR ERANGE +The transfer request size was outside the range supported by the +STREAMS file associated with +.IR fildes . +.P +The +\fIpwrite\fR() +function shall fail if: +.TP +.BR EINVAL +The file is a regular file or block special file, and the +.IR offset +argument is negative. The file pointer shall remain unchanged. +.TP +.BR ESPIPE +The file is a pipe, FIFO, or socket. +.P +The +\fIwrite\fR() +function shall fail if: +.TP +.BR EAGAIN +The file is a pipe or FIFO, the O_NONBLOCK flag is set for the file +descriptor, and the thread would be delayed in the write operation. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The file is a socket, the O_NONBLOCK flag is set for the file +descriptor, and the thread would be delayed in the write operation. +.TP +.BR ECONNRESET +A write was attempted on a socket that is not connected. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process, or that only has one end open. A SIGPIPE signal +shall also be sent to the thread. +.TP +.BR EPIPE +A write was attempted on a socket that is shut down for writing, or is +no longer connected. In the latter case, if the socket is of type +SOCK_STREAM, a SIGPIPE signal shall also be sent to the thread. +.P +These functions may fail if: +.TP +.BR EINVAL +The STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.TP +.BR ENXIO +A hangup occurred on the STREAM being written to. +.P +A write to a STREAMS file may fail if an error message has been +received at the STREAM head. In this case, +.IR errno +is set to the value included in the error message. +.br +.P +The +\fIwrite\fR() +function may fail if: +.TP +.BR EACCES +A write was attempted on a socket and the calling +process does not have appropriate privileges. +.TP +.BR ENETDOWN +A write was attempted on a socket and the local network interface used +to reach the destination is down. +.TP +.BR ENETUNREACH +.br +A write was attempted on a socket and no route to the network is +present. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Writing from a Buffer" +.P +The following example writes data from the buffer pointed to by +.IR buf +to the file associated with the file descriptor +.IR fd . +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +char buf[20]; +size_t nbytes; +ssize_t bytes_written; +int fd; +\&... +strcpy(buf, "This is a test\en"); +nbytes = strlen(buf); +.P +bytes_written = write(fd, buf, nbytes); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See also the RATIONALE section in +\fIread\fR(). +.P +An attempt to write to a pipe or FIFO has several major +characteristics: +.IP " *" 4 +\fIAtomic/non-atomic\fP: A write is atomic if the whole amount written +in one operation is not interleaved with data from any other process. +This is useful when there are multiple writers sending data to a single +reader. Applications need to know how large a write request can be +expected to be performed atomically. This maximum is called +{PIPE_BUF}. +This volume of POSIX.1\(hy2008 does not say whether write requests for more than +{PIPE_BUF} +bytes are atomic, but requires that writes of +{PIPE_BUF} +or fewer bytes shall be atomic. +.IP " *" 4 +\fIBlocking/immediate\fP: Blocking is only possible with O_NONBLOCK +clear. If there is enough space for all the data requested to be +written immediately, the implementation should do so. Otherwise, the +calling thread may block; that is, pause until enough space is +available for writing. The effective size of a pipe or FIFO (the +maximum amount that can be written in one operation without blocking) +may vary dynamically, depending on the implementation, so it is not +possible to specify a fixed value for it. +.IP " *" 4 +\fIComplete/partial/deferred\fP: A write request: +.RS 4 +.sp +.RS 4 +.nf +\fB +int fildes; +size_t nbyte; +ssize_t ret; +char *buf; +.P +ret = write(fildes, buf, nbyte); +.fi \fR +.P +.RE +.P +may return: +.IP Complete 10 +\fIret\fP=\fInbyte\fP +.IP Partial 10 +\fIret\fP<\fInbyte\fP +.RS 10 +.P +This shall never happen if +.IR nbyte \(<=\c +{PIPE_BUF}. +If it does happen (with +.IR nbyte >\c +{PIPE_BUF}), +\&this volume of POSIX.1\(hy2008 does not guarantee atomicity, even if +.IR ret \(<=\c +{PIPE_BUF}, +because atomicity is guaranteed according to the amount +.IR requested , +not the amount +.IR written . +.RE +.IP Deferred: 10 +\fIret\fP=\(mi1, \fIerrno\fP=[EAGAIN] +.RS 10 +.P +This error indicates that a later request may succeed. It does not +indicate that it +.IR shall +succeed, even if +.IR nbyte \(<=\c +{PIPE_BUF}, +because if no process reads from the pipe or FIFO, the write never +succeeds. An application could usefully count the number of times +.BR [EAGAIN] +is caused by a particular value of +.IR nbyte >\c +{PIPE_BUF} +and perhaps do later writes with a smaller value, on the assumption +that the effective size of the pipe may have decreased. +.RE +.P +Partial and deferred writes are only possible with O_NONBLOCK set. +.RE +.P +The relations of these properties are shown in the following tables: +.TS +center box tab(!); +cB s s s +cB | cB cB c +l1 | lw(1.25i)1 lw(1.25i)1 lw(1.25i). +Write to a Pipe or FIFO with O_NONBLOCK \fIclear\fP +_ +Immediately Writable:!None!Some!\fInbyte\fP +_ +\fInbyte\fP\(<={PIPE_BUF}!Atomic blocking!Atomic blocking!Atomic immediate +!\fInbyte\fP!\fInbyte\fP!\fInbyte\fP +_ +\fInbyte\fP>{PIPE_BUF}!Blocking \fInbyte\fP!Blocking \fInbyte\fP!Blocking \fInbyte\fP +.TE +.P +If the O_NONBLOCK flag is clear, a write request shall block if the +amount writable immediately is less than that requested. If the flag is +set (by +\fIfcntl\fR()), +a write request shall never block. +.TS +center box tab(!); +cB s s s +cB | cB cB c +l1 | lw(1.25i)1 lw(1.25i)1 lw(1.25i). +Write to a Pipe or FIFO with O_NONBLOCK \fIset\fP +_ +Immediately Writable:!None!Some!\fInbyte\fP +_ +\fInbyte\fP\(<={PIPE_BUF}!\(mi1, [EAGAIN]!\(mi1, [EAGAIN]!Atomic \fInbyte\fP +_ +\fInbyte\fP>{PIPE_BUF}!\(mi1, [EAGAIN]!<\fInbyte\fP or \(mi1,!\(<=\fInbyte\fP or \(mi1, +!![EAGAIN]![EAGAIN] +.TE +.P +There is no exception regarding partial writes when O_NONBLOCK is set. +With the exception of writing to an empty pipe, this volume of POSIX.1\(hy2008 does not specify +exactly when a partial write is performed since that would require +specifying internal details of the implementation. Every application +should be prepared to handle partial writes when O_NONBLOCK is set and +the requested amount is greater than +{PIPE_BUF}, +just as every application should be prepared to handle partial writes +on other kinds of file descriptors. +.P +The intent of forcing writing at least one byte if any can be written +is to assure that each write makes progress if there is any room in the +pipe. If the pipe is empty, +{PIPE_BUF} +bytes must be written; if not, at least some progress must have been +made. +.P +Where this volume of POSIX.1\(hy2008 requires \(mi1 to be returned and +.IR errno +set to +.BR [EAGAIN] , +most historical implementations return zero (with the O_NDELAY +flag set, which is the historical predecessor of O_NONBLOCK, but is not +itself in this volume of POSIX.1\(hy2008). The error indications in this volume of POSIX.1\(hy2008 were chosen so that an +application can distinguish these cases from end-of-file. While +\fIwrite\fR() +cannot receive an indication of end-of-file, +\fIread\fR() +can, and the two functions have similar return values. Also, some +existing systems (for example, Eighth Edition) permit a write of zero +bytes to +mean that the reader should get an end-of-file indication; for those +systems, a return value of zero from +\fIwrite\fR() +indicates a successful write of an end-of-file indication. +.P +Implementations are allowed, but not required, to perform error +checking for +\fIwrite\fR() +requests of zero bytes. +.P +The concept of a +{PIPE_MAX} +limit (indicating the maximum number of bytes that can be written to a +pipe in a single operation) was considered, but rejected, because this +concept would unnecessarily limit application writing. +.P +See also the discussion of O_NONBLOCK in +\fIread\fR(). +.P +Writes can be serialized with respect to other reads and writes. If a +\fIread\fR() +of file data can be proven (by any means) to occur after a +\fIwrite\fR() +of the data, it must reflect that +\fIwrite\fR(), +even if the calls are made by different processes. A similar +requirement applies to multiple write operations to the same file +position. This is needed to guarantee the propagation of data from +\fIwrite\fR() +calls to subsequent +\fIread\fR() +calls. This requirement is particularly significant for networked file +systems, where some caching schemes violate these semantics. +.P +Note that this is specified in terms of +\fIread\fR() +and +\fIwrite\fR(). +The XSI extensions +\fIreadv\fR() +and +\fIwritev\fR() +also obey these semantics. A new ``high-performance'' write +analog that did not follow these serialization requirements would also +be permitted by this wording. This volume of POSIX.1\(hy2008 is also silent about any effects of +application-level caching (such as that done by +.IR stdio ). +.P +This volume of POSIX.1\(hy2008 does not specify the value of the file offset after an error is +returned; there are too many cases. For programming errors, such as +.BR [EBADF] , +the concept is meaningless since no file is involved. For errors that +are detected immediately, such as +.BR [EAGAIN] , +clearly the pointer should not change. After an interrupt or hardware +error, however, an updated value would be very useful and is the +behavior of many implementations. +.P +This volume of POSIX.1\(hy2008 does not specify behavior of concurrent writes to a file from +multiple processes. Applications should use some form of concurrency +control. +.P +This volume of POSIX.1\(hy2008 intentionally does not specify any +\fIpwrite\fR() +errors related to pipes, FIFOs, and sockets other than +.BR [ESPIPE] . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIwritev\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/writev.3p b/man-pages-posix-2013-a/man3p/writev.3p new file mode 100644 index 0000000..e16e7f6 --- /dev/null +++ b/man-pages-posix-2013-a/man3p/writev.3p @@ -0,0 +1,169 @@ +'\" et +.TH WRITEV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +writev +\(em write a vector +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t writev(int \fIfildes\fP, const struct iovec *\fIiov\fP, int \fIiovcnt\fP); +.fi +.SH DESCRIPTION +The +\fIwritev\fR() +function shall be equivalent to +\fIwrite\fR(), +except as described below. The +\fIwritev\fR() +function shall gather output data from the +.IR iovcnt +buffers specified by the members of the +.IR iov +array: +.IR iov [0], +.IR iov [1], +\&.\|.\|., \fIiov\fR[\fIiovcnt\fR\(mi1]. +The +.IR iovcnt +argument is valid if greater than 0 and less than or equal to +{IOV_MAX}, +as defined in +.IR . +.P +Each +.IR iovec +entry specifies the base address and length of an area in memory from +which data should be written. The +\fIwritev\fR() +function shall always write a complete area before proceeding to the +next. +.P +If +.IR fildes +refers to a regular file and all of the +.IR iov_len +members in the array pointed to by +.IR iov +are 0, +\fIwritev\fR() +shall return 0 and have no other effect. For other file types, the +behavior is unspecified. +.P +If the sum of the +.IR iov_len +values is greater than +{SSIZE_MAX}, +the operation shall fail and no data shall be transferred. +.SH "RETURN VALUE" +Upon successful completion, +\fIwritev\fR() +shall return the number of bytes actually written. Otherwise, it shall +return a value of \(mi1, the file-pointer shall remain unchanged, and +.IR errno +shall be set to indicate an error. +.SH ERRORS +Refer to +.IR "\fIwrite\fR\^(\|)". +.P +In addition, the +\fIwritev\fR() +function shall fail if: +.TP +.BR EINVAL +The sum of the +.IR iov_len +values in the +.IR iov +array would overflow an +.BR ssize_t . +.P +The +\fIwritev\fR() +function may fail and set +.IR errno +to: +.TP +.BR EINVAL +The +.IR iovcnt +argument was less than or equal to 0, or greater than +{IOV_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Writing Data from an Array" +.P +The following example writes data from the buffers specified by members +of the +.IR iov +array to the file associated with the file descriptor +.IR fd . +.sp +.RS 4 +.nf +\fB +#include +#include +#include +\&... +ssize_t bytes_written; +int fd; +char *buf0 = "short string\en"; +char *buf1 = "This is a longer string\en"; +char *buf2 = "This is the longest string in this example\en"; +int iovcnt; +struct iovec iov[3]; +.P +iov[0].iov_base = buf0; +iov[0].iov_len = strlen(buf0); +iov[1].iov_base = buf1; +iov[1].iov_len = strlen(buf1); +iov[2].iov_base = buf2; +iov[2].iov_len = strlen(buf2); +\&... +iovcnt = sizeof(iov) / sizeof(struct iovec); +.P +bytes_written = writev(fd, iov, iovcnt); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIwrite\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIreadv\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/wscanf.3p b/man-pages-posix-2013-a/man3p/wscanf.3p new file mode 100644 index 0000000..1cc0b3e --- /dev/null +++ b/man-pages-posix-2013-a/man3p/wscanf.3p @@ -0,0 +1,39 @@ +'\" et +.TH WSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wscanf +\(em convert formatted wide-character input +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int wscanf(const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfwscanf\fR\^(\|)". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013-a/man3p/y0.3p b/man-pages-posix-2013-a/man3p/y0.3p new file mode 100644 index 0000000..470a1ab --- /dev/null +++ b/man-pages-posix-2013-a/man3p/y0.3p @@ -0,0 +1,162 @@ +'\" et +.TH Y0 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +y0, +y1, +yn +\(em Bessel functions of the second kind +.SH SYNOPSIS +.LP +.nf +#include +.P +double y0(double \fIx\fP); +double y1(double \fIx\fP); +double yn(int \fIn\fP, double \fIx\fP); +.fi +.SH DESCRIPTION +The +\fIy0\fR(), +\fIy1\fR(), +and +\fIyn\fR() +functions shall compute Bessel functions of +.IR x +of the second kind of orders 0, 1, and +.IR n , +respectively. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the relevant +Bessel value of +.IR x +of the second kind. +.P +If +.IR x +is NaN, NaN shall be returned. +.P +If the +.IR x +argument to these functions is negative, \(miHUGE_VAL or NaN shall be +returned, and a domain error may occur. +.P +If +.IR x +is 0.0, \(miHUGE_VAL shall be returned and a pole error may occur. +.P +If the correct result would cause underflow, 0.0 shall be returned and +a range error may occur. +.P +If the correct result would cause overflow, \(miHUGE_VAL or 0.0 shall +be returned and a range error may occur. +.SH ERRORS +These functions may fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is negative. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The correct result would cause overflow. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The value of +.IR x +is too large in magnitude, or the correct result would cause +underflow. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIj0\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man1/getent.1 b/man1/getent.1 new file mode 100644 index 0000000..8d5cd14 --- /dev/null +++ b/man1/getent.1 @@ -0,0 +1,408 @@ +.\" Copyright (c) 2011, Mark R. Bannister +.\" Copyright (c) 2015, Robin H. Johnson +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH GETENT 1 2015-04-19 "Linux" "User Commands" +.SH NAME +getent \- get entries from Name Service Switch libraries +.SH SYNOPSIS +.BR getent\ [\fIoption\fP]...\ \fIdatabase\fP\ \fIkey\fP... +.SH DESCRIPTION +The +.B getent +command displays entries from databases supported by the +Name Service Switch libraries, +which are configured in +.IR /etc/nsswitch.conf . +If one or more +.I key +arguments are provided, +then only the entries that match the supplied keys will be displayed. +Otherwise, if no +.I key +is provided, all entries will be displayed (unless the database does not +support enumeration). +.PP +The +.I database +may be any of those supported by the GNU C Library, listed below: +.RS 3 +.TP 10 +.B ahosts +When no +.I key +is provided, use +.BR sethostent (3), +.BR gethostent (3), +and +.BR endhostent (3) +to enumerate the hosts database. +This is identical to using +.BR hosts . +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getaddrinfo (3) +with the address family +.BR AF_UNSPEC , +enumerating each socket address structure returned. +.TP +.B ahostsv4 +Same as +.BR ahosts , +but use the address family +.BR AF_INET . +.TP +.B ahostsv6 +Same as +.BR ahosts , +but use the address family +.BR AF_INET6 . +The call to +.BR getaddrinfo (3) +in this case includes the +.B AI_V4MAPPED +flag. +.TP +.B aliases +When no +.I key +is provided, use +.BR setaliasent (3), +.BR getaliasent (3), +and +.BR endaliasent (3) +to enumerate the aliases database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getaliasbyname (3) +and display the result. +.TP +.B ethers +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR ether_aton (3) +and +.BR ether_hostton (3) +until a result is obtained, and display the result. +Enumeration is not supported on +.BR ethers , +so a +.I key +must be provided. +.TP +.B group +When no +.I key +is provided, use +.BR setgrent (3), +.BR getgrent (3), +and +.BR endgrent (3) +to enumerate the group database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getgrgid (3) +and each nonnumeric +.I key +to +.BR getgrnam (3) +and display the result. +.TP +.B gshadow +When no +.I key +is provided, use +.BR setsgent (3), +.BR getsgent (3), +and +.BR endsgent (3) +to enumerate the gshadow database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getsgnam (3) +and display the result. +.TP +.B hosts +When no +.I key +is provided, use +.BR sethostent (3), +.BR gethostent (3), +and +.BR endhostent (3) +to enumerate the hosts database. +When one or more +.I key +arguments are provided, pass each +.I key +to +.BR gethostbyaddr (3) +or +.BR gethostbyname2 (3), +depending on whether a call to +.BR inet_pton (3) +indicates that the +.I key +is an IPv6 or IPv4 address or not, and display the result. +.TP +.B initgroups +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getgrouplist (3) +and display the result. +Enumeration is not supported on +.BR initgroups , +so a +.I key +must be provided. +.TP +.B netgroup +When one +.I key +is provided, pass the +.I key +to +.BR setnetgrent (3) +and, using +.BR getnetgrent (3) +display the resulting string triple +.RI ( hostname ", " username ", " domainname ). +Alternatively, three +.I keys +may be provided, which are interpreted as the +.IR hostname , +.I username +and +.I domainname +to match to a netgroup name via +.BR innetgr (3). +Enumeration is not supported on +.BR netgroup , +so either one or three +.I keys +must be provided. +.TP +.B networks +When no +.I key +is provided, use +.BR setnetent (3), +.BR getnetent (3), +and +.BR endnetent (3) +to enumerate the networks database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getnetbyaddr (3) +and each nonnumeric +.I key +to +.BR getnetbyname (3) +and display the result. +.TP +.B passwd +When no +.I key +is provided, use +.BR setpwent (3), +.BR getpwent (3), +and +.BR endpwent (3) +to enumerate the passwd database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getpwuid (3) +and each nonnumeric +.I key +to +.BR getpwnam (3) +and display the result. +.TP +.B protocols +When no +.I key +is provided, use +.BR setprotoent (3), +.BR getprotoent (3), +and +.BR endprotoent (3) +to enumerate the protocols database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getprotobynumber (3) +and each nonnumeric +.I key +to +.BR getprotobyname (3) +and display the result. +.TP +.B rpc +When no +.I key +is provided, use +.BR setrpcent (3), +.BR getrpcent (3), +and +.BR endrpcent (3) +to enumerate the rpc database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getrpcbynumber (3) +and each nonnumeric +.I key +to +.BR getrpcbyname (3) +and display the result. +.TP +.B services +When no +.I key +is provided, use +.BR setservent (3), +.BR getservent (3), +and +.BR endservent (3) +to enumerate the services database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getservbynumber (3) +and each nonnumeric +.I key +to +.BR getservbyname (3) +and display the result. +.TP +.B shadow +When no +.I key +is provided, use +.BR setspent (3), +.BR getspent (3), +and +.BR endspent (3) +to enumerate the shadow database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getspnam (3) +and display the result. +.RE +.SH OPTIONS +.TP +.BR \-s\ \fIservice\fP ", " \-\-service\ \fIservice\fP +.\" commit 9d0881aa76b399e6a025c5cf44bebe2ae0efa8af (glibc) +Override all databases with the specified service. +(Since glibc 2.2.5.) +.TP +.BR \-s\ \fIdatabase\fP:\fIservice\fP ", "\ +\-\-service\ \fIdatabase\fP:\fIservice\fP +.\" commit b4f6f4be85d32b9c03361c38376e36f08100e3e8 (glibc) +Override only specified databases with the specified service. +The option may be used multiple times, +but only the last service for each database will be used. +(Since glibc 2.4.) +.TP +.BR \-i ", " \-\-no\-idn +.\" commit a160f8d808cf8020b13bd0ef4a9eaf3c11f964ad (glibc) +Disables IDN encoding in lookups for +.BR ahosts / getaddrinfo (3) +(Since glibc-2.13.) +.TP +.BR \-? ", " \-\-help +Print a usage summary and exit. +.TP +.B "\-\-usage" +Print a short usage summary and exit. +.TP +.BR \-V ", " \-\-version +Print the version number, license, and disclaimer of warranty for +.BR getent . +.SH EXIT STATUS +One of the following exit values can be returned by +.BR getent : +.RS 3 +.TP 10 +.B 0 +Command completed successfully. +.TP +.B 1 +Missing arguments, or +.I database +unknown. +.TP +.B 2 +One or more supplied +.I key +could not be found in the +.IR database . +.TP +.B 3 +Enumeration not supported on this +.IR database . +.RE +.SH SEE ALSO +.BR nsswitch.conf (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/iconv.1 b/man1/iconv.1 new file mode 100644 index 0000000..466aa02 --- /dev/null +++ b/man1/iconv.1 @@ -0,0 +1,213 @@ +'\" t -*- coding: UTF-8 -*- +.\" +.\" Copyright (C) 2014 Marko Myllynen +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ICONV 1 2018-02-02 "GNU" "Linux User Manual" +.SH NAME +iconv \- convert text from one character encoding to another +.SH SYNOPSIS +.B iconv +.RI [ options ] +.RI "[\-f " from-encoding "]" +.RI "[\-t " to-encoding "]" +.RI [ inputfile ]... +.SH DESCRIPTION +The +.B iconv +program reads in text in one encoding and outputs the text in another +encoding. +If no input files are given, or if it is given as a dash (\-), +.B iconv +reads from standard input. +If no output file is given, +.B iconv +writes to standard output. +.PP +If no +.I from-encoding +is given, the default is derived +from the current locale's character encoding. +If no +.I to-encoding +is given, the default is derived +from the current locale's character +encoding. +.SH OPTIONS +.TP +.BI \-f " from-encoding" "\fR, \fP\-\-from\-code=" from-encoding +Use +.I from-encoding +for input characters. +.TP +.BI \-t " to-encoding" "\fR, \fP\-\-to\-code=" to-encoding +Use +.I to-encoding +for output characters. +.IP +If the string +.BR //IGNORE +is appended to +.IR to-encoding , +characters that cannot be converted are discarded and an error is +printed after conversion. +.IP +If the string +.BR //TRANSLIT +is appended to +.IR to-encoding , +characters being converted are transliterated when needed and possible. +This means that when a character cannot be represented in the target +character set, it can be approximated through one or several similar +looking characters. +Characters that are outside of the target character set and cannot be +transliterated are replaced with a question mark (?) in the output. +.TP +.BR \-l ", " \-\-list +List all known character set encodings. +.TP +.B "\-c" +Silently discard characters that cannot be converted instead of +terminating when encountering such characters. +.TP +.BI \-o " outputfile" "\fR, \fP\-\-output=" outputfile +Use +.I outputfile +for output. +.TP +.BR \-s ", " \-\-silent +This option is ignored; it is provided only for compatibility. +.TP +.B "\-\-verbose" +Print progress information on standard error when processing +multiple files. +.TP +.BR \-? ", " \-\-help +Print a usage summary and exit. +.TP +.B "\-\-usage" +Print a short usage summary and exit. +.TP +.BR \-V ", " \-\-version +Print the version number, license, and disclaimer of warranty for +.BR iconv . +.SH EXIT STATUS +Zero on success, nonzero on errors. +.SH ENVIRONMENT +Internally, the +.B iconv +program uses the +.BR iconv (3) +function which in turn uses +.I gconv +modules (dynamically loaded shared libraries) +to convert to and from a character set. +Before calling +.BR iconv (3), +the +.B iconv +program must first allocate a conversion descriptor using +.BR iconv_open (3). +The operation of the latter function is influenced by the setting of the +.B GCONV_PATH +environment variable: +.IP * 3 +If +.B GCONV_PATH +is not set, +.BR iconv_open (3) +loads the system gconv module configuration cache file created by +.BR iconvconfig (8) +and then, based on the configuration, +loads the gconv modules needed to perform the conversion. +If the system gconv module configuration cache file is not available +then the system gconv module configuration file is used. +.IP * +If +.B GCONV_PATH +is defined (as a colon-separated list of pathnames), +the system gconv module configuration cache is not used. +Instead, +.BR iconv_open (3) +first tries to load the configuration files by searching the directories in +.BR GCONV_PATH +in order, +followed by the system default gconv module configuration file. +If a directory does not contain a gconv module configuration file, +any gconv modules that it may contain are ignored. +If a directory contains a gconv module configuration file +and it is determined that a module needed for this conversion is +available in the directory, +then the needed module is loaded from that directory, +the order being such that the first suitable module found in +.B GCONV_PATH +is used. +This allows users to use custom modules and even replace system-provided +modules by providing such modules in +.B GCONV_PATH +directories. +.SH FILES +.TP +.I /usr/lib/gconv +Usual default gconv module path. +.TP +.I /usr/lib/gconv/gconv\-modules +Usual system default gconv module configuration file. +.TP +.I /usr/lib/gconv/gconv\-modules.cache +Usual system gconv module configuration cache. +.SH CONFORMING TO +POSIX.1-2001. +.SH EXAMPLE +Convert text from the ISO 8859-15 character encoding to UTF-8: +.PP +.in +4n +.EX +$ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP +.EE +.in +.PP +The next example converts from UTF-8 to ASCII, transliterating when +possible: +.PP +.in +4n +.EX +$ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP +abc ss ? EUR abc +.EE +.in +.SH SEE ALSO +.BR locale (1), +.BR iconv (3), +.BR nl_langinfo (3), +.BR charsets (7), +.BR iconvconfig (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/intro.1 b/man1/intro.1 new file mode 100644 index 0000000..84eeae3 --- /dev/null +++ b/man1/intro.1 @@ -0,0 +1,334 @@ +.\" Copyright (c) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH INTRO 1 2015-07-23 "Linux" "Linux User's Manual" +.SH NAME +intro \- introduction to user commands +.SH DESCRIPTION +Section 1 of the manual describes user commands and tools, +for example, file manipulation tools, shells, compilers, +web browsers, file and image viewers and editors, and so on. +.SH NOTES +Linux is a flavor of UNIX, and as a first approximation +all user commands under UNIX work precisely the same under +Linux (and FreeBSD and lots of other UNIX-like systems). +.PP +Under Linux, there are GUIs (graphical user interfaces), where you +can point and click and drag, and hopefully get work done without +first reading lots of documentation. +The traditional UNIX environment +is a CLI (command line interface), where you type commands to +tell the computer what to do. +That is faster and more powerful, +but requires finding out what the commands are. +Below a bare minimum, to get started. +.SS Login +In order to start working, you probably first have to open a session by +giving your username and password. +The program +.BR login (1) +now starts a +.I shell +(command interpreter) for you. +In case of a graphical login, you get a screen with menus or icons +and a mouse click will start a shell in a window. +See also +.BR xterm (1). +.SS The shell +One types commands to the +.IR shell , +the command interpreter. +It is not built-in, but is just a program +and you can change your shell. +Everybody has her own favorite one. +The standard one is called +.IR sh . +See also +.BR ash (1), +.BR bash (1), +.BR chsh (1), +.BR csh (1), +.BR dash (1), +.BR ksh (1), +.BR zsh (1). +.PP +A session might go like: +.PP +.in +4n +.EX +.RB "knuth login: " aeb +.RB "Password: " ******** +.RB "$ " date +Tue Aug 6 23:50:44 CEST 2002 +.RB "$ " cal + August 2002 +Su Mo Tu We Th Fr Sa + 1 2 3 + 4 5 6 7 8 9 10 +11 12 13 14 15 16 17 +18 19 20 21 22 23 24 +25 26 27 28 29 30 31 + +.RB "$ " ls +bin tel +.RB "$ " "ls \-l" +total 2 +drwxrwxr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-rw\-r\-\- 1 aeb 37 Aug 6 23:52 tel +.RB "$ " "cat tel" +maja 0501\-1136285 +peter 0136\-7399214 +.RB "$ " "cp tel tel2" +.RB "$ " "ls \-l" +total 3 +drwxr\-xr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:52 tel +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:53 tel2 +.RB "$ " "mv tel tel1" +.RB "$ " "ls \-l" +total 3 +drwxr\-xr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:52 tel1 +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:53 tel2 +.RB "$ " "diff tel1 tel2" +.RB "$ " "rm tel1" +.RB "$ " "grep maja tel2" +maja 0501\-1136285 +$ +.EE +.in +.PP +Here typing Control-D ended the session. +.PP +The +.B $ +here was the command prompt\(emit is the shell's way of indicating +that it is ready for the next command. +The prompt can be customized +in lots of ways, and one might include stuff like username, +machine name, current directory, time, and so on. +An assignment PS1="What next, master? " +would change the prompt as indicated. +.PP +We see that there are commands +.I date +(that gives date and time), and +.I cal +(that gives a calendar). +.PP +The command +.I ls +lists the contents of the current directory\(emit tells you what +files you have. +With a +.I \-l +option it gives a long listing, +that includes the owner and size and date of the file, and the +permissions people have for reading and/or changing the file. +For example, the file "tel" here is 37 bytes long, owned by aeb +and the owner can read and write it, others can only read it. +Owner and permissions can be changed by the commands +.I chown +and +.IR chmod . +.PP +The command +.I cat +will show the contents of a file. +(The name is from "concatenate and print": all files given as +parameters are concatenated and sent to "standard output" +(see +.BR stdout (3)), +here +the terminal screen.) +.PP +The command +.I cp +(from "copy") will copy a file. +.PP +The command +.I mv +(from "move"), on the other hand, only renames it. +.PP +The command +.I diff +lists the differences between two files. +Here there was no output because there were no differences. +.PP +The command +.I rm +(from "remove") deletes the file, and be careful! it is gone. +No wastepaper basket or anything. +Deleted means lost. +.PP +The command +.I grep +(from "g/re/p") finds occurrences of a string in one or more files. +Here it finds Maja's telephone number. +.SS Pathnames and the current directory +Files live in a large tree, the file hierarchy. +Each has a +.I "pathname" +describing the path from the root of the tree (which is called +.IR / ) +to the file. +For example, such a full pathname might be +.IR /home/aeb/tel . +Always using full pathnames would be inconvenient, and the name +of a file in the current directory may be abbreviated by giving +only the last component. +That is why +.I /home/aeb/tel +can be abbreviated +to +.I tel +when the current directory is +.IR /home/aeb . +.PP +The command +.I pwd +prints the current directory. +.PP +The command +.I cd +changes the current directory. +.PP +Try alternatively +.I cd +and +.I pwd +commands and explore +.I cd +usage: "cd", "cd .", "cd ..", "cd /" and "cd ~". +.SS Directories +The command +.I mkdir +makes a new directory. +.PP +The command +.I rmdir +removes a directory if it is empty, and complains otherwise. +.PP +The command +.I find +(with a rather baroque syntax) will find files with given name +or other properties. +For example, "find . \-name tel" would find +the file +.I tel +starting in the present directory (which is called +.IR . ). +And "find / \-name tel" would do the same, but starting at the root +of the tree. +Large searches on a multi-GB disk will be time-consuming, +and it may be better to use +.BR locate (1). +.SS Disks and filesystems +The command +.I mount +will attach the filesystem found on some disk (or floppy, or CDROM or so) +to the big filesystem hierarchy. +And +.I umount +detaches it again. +The command +.I df +will tell you how much of your disk is still free. +.SS Processes +On a UNIX system many user and system processes run simultaneously. +The one you are talking to runs in the +.IR foreground , +the others in the +.IR background . +The command +.I ps +will show you which processes are active and what numbers these +processes have. +The command +.I kill +allows you to get rid of them. +Without option this is a friendly +request: please go away. +And "kill \-9" followed by the number +of the process is an immediate kill. +Foreground processes can often be killed by typing Control-C. +.SS Getting information +There are thousands of commands, each with many options. +Traditionally commands are documented on +.IR "man pages" , +(like this one), so that the command "man kill" will document +the use of the command "kill" (and "man man" document the command "man"). +The program +.I man +sends the text through some +.IR pager , +usually +.IR less . +Hit the space bar to get the next page, hit q to quit. +.PP +In documentation it is customary to refer to man pages +by giving the name and section number, as in +.BR man (1). +Man pages are terse, and allow you to find quickly some forgotten +detail. +For newcomers an introductory text with more examples +and explanations is useful. +.PP +A lot of GNU/FSF software is provided with info files. +Type "info info" +for an introduction on the use of the program +.IR info . +.PP +Special topics are often treated in HOWTOs. +Look in +.I /usr/share/doc/howto/en +and use a browser if you find HTML files there. +.\" +.\" Actual examples? Separate section for each of cat, cp, ...? +.\" gzip, bzip2, tar, rpm +.SH SEE ALSO +.BR ash (1), +.BR bash (1), +.BR chsh (1), +.BR csh (1), +.BR dash (1), +.BR ksh (1), +.BR locate (1), +.BR login (1), +.BR man (1), +.BR xterm (1), +.BR zsh (1), +.BR wait (2), +.BR stdout (3), +.BR man-pages (7), +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/ldd.1 b/man1/ldd.1 new file mode 100644 index 0000000..e468f4b --- /dev/null +++ b/man1/ldd.1 @@ -0,0 +1,181 @@ +.\" Copyright 1995-2000 David Engel (david@ods.com) +.\" Copyright 1995 Rickard E. Faith (faith@cs.unc.edu) +.\" Copyright 2000 Ben Collins (bcollins@debian.org) +.\" Redone for GLibc 2.2 +.\" Copyright 2000 Jakub Jelinek (jakub@redhat.com) +.\" Corrected. +.\" and Copyright (C) 2012, 2016, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Do not restrict distribution. +.\" May be distributed under the GNU General Public License +.\" %%%LICENSE_END +.\" +.TH LDD 1 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ldd \- print shared object dependencies +.SH SYNOPSIS +.BR ldd " [\fIoption\fP]... \fIfile\fP..." +.SH DESCRIPTION +.B ldd +prints the shared objects (shared libraries) required by each program or +shared object specified on the command line. +An example of its use and output is the following: +.PP +.in +2n +.EX +$ \fBldd /bin/ls\fP + linux-vdso.so.1 (0x00007ffcc3563000) + libselinux.so.1 => /lib64/libselinux.so.1 (0x00007f87e5459000) + libcap.so.2 => /lib64/libcap.so.2 (0x00007f87e5254000) + libc.so.6 => /lib64/libc.so.6 (0x00007f87e4e92000) + libpcre.so.1 => /lib64/libpcre.so.1 (0x00007f87e4c22000) + libdl.so.2 => /lib64/libdl.so.2 (0x00007f87e4a1e000) + /lib64/ld-linux-x86-64.so.2 (0x00005574bf12e000) + libattr.so.1 => /lib64/libattr.so.1 (0x00007f87e4817000) + libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f87e45fa000) +.EE +.in +.PP +In the usual case, +.B ldd +invokes the standard dynamic linker (see +.BR ld.so (8)) +with the +.B LD_TRACE_LOADED_OBJECTS +environment variable set to 1. +This causes the dynamic linker to inspect the program's dynamic dependencies, +and find (according to the rules described in +.BR ld.so (8)) +and load the objects that satisfy those dependencies. +For each dependency, +.BR ldd +displays the location of the matching object +and the (hexadecimal) address at which it is loaded. +(The +.I linux-vdso +and +.I ld-linux +shared dependencies are special; see +.BR vdso (7) +and +.BR ld.so (8).) +.\" +.SS Security +Be aware that in some circumstances +(e.g., where the program specifies an ELF interpreter other than +.IR ld-linux.so ), +.\" The circumstances are where the program has an interpreter +.\" other than ld-linux.so. In this case, ldd tries to execute the +.\" program directly with LD_TRACE_LOADED_OBJECTS=1, with the +.\" result that the program interpreter gets control, and can do +.\" what it likes, or pass control to the program itself. +.\" Much more detail at +.\" http://www.catonmat.net/blog/ldd-arbitrary-code-execution/ +some versions of +.BR ldd +may attempt to obtain the dependency information +by attempting to directly execute the program, +which may lead to the execution of whatever code is defined +in the program's ELF interpreter, +and perhaps to execution of the program itself. +.\" Mainline glibc's ldd allows this possibility (the line +.\" try_trace "$file" +.\" in glibc 2.15, for example), but many distro versions of +.\" ldd seem to remove that code path from the script. +(In glibc versions before 2.27, +.\" glibc commit eedca9772e99c72ab4c3c34e43cc764250aa3e3c +the upstream +.B ldd +implementation did this for example, +although most distributions provided a modified version that did not.) +.PP +Thus, you should +.I never +employ +.B ldd +on an untrusted executable, +since this may result in the execution of arbitrary code. +A safer alternative when dealing with untrusted executables is: +.PP +.in +4n +.EX +$ \fBobjdump \-p /path/to/program | grep NEEDED\fP +.EE +.in +.PP +Note, however, that this alternative shows only the direct dependencies +of the executable, while +.B ldd +shows the entire dependency tree of the executable. +.SH OPTIONS +.TP +.B \-\-version +Print the version number of +.BR ldd . +.TP +.BR \-v ", " \-\-verbose +Print all information, including, for example, +symbol versioning information. +.TP +.BR \-u ", " \-\-unused +Print unused direct dependencies. +(Since glibc 2.3.4.) +.TP +.BR \-d ", " \-\-data\-relocs +Perform relocations and report any missing objects (ELF only). +.TP +.BR \-r ", " \-\-function\-relocs +Perform relocations for both data objects and functions, and +report any missing objects or functions (ELF only). +.TP +.B \-\-help +Usage information. +.\" .SH NOTES +.\" The standard version of +.\" .B ldd +.\" comes with glibc2. +.\" Libc5 came with an older version, still present +.\" on some systems. +.\" The long options are not supported by the libc5 version. +.\" On the other hand, the glibc2 version does not support +.\" .B \-V +.\" and only has the equivalent +.\" .BR \-\-version . +.\" .LP +.\" The libc5 version of this program will use the name of a library given +.\" on the command line as-is when it contains a \(aq/\(aq; otherwise it +.\" searches for the library in the standard locations. +.\" To run it +.\" on a shared library in the current directory, prefix the name with "./". +.SH BUGS +.B ldd +does not work on a.out shared libraries. +.PP +.B ldd +does not work with some extremely old a.out programs which were +built before +.B ldd +support was added to the compiler releases. +If you use +.B ldd +on one of these programs, the program will attempt to run with +.I argc += 0 and the results will be unpredictable. +.\" .SH AUTHOR +.\" David Engel. +.\" Roland McGrath and Ulrich Drepper. +.SH SEE ALSO +.BR pldd (1), +.BR sprof (1), +.BR ld.so (8), +.BR ldconfig (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/locale.1 b/man1/locale.1 new file mode 100644 index 0000000..f539e9e --- /dev/null +++ b/man1/locale.1 @@ -0,0 +1,217 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH LOCALE 1 2017-09-15 "Linux" "Linux User Manual" +.SH NAME +locale \- get locale-specific information +.SH SYNOPSIS +.nf +.BR locale " [\fIoption\fP]" +.BR locale " [\fIoption\fP] " \-a +.BR locale " [\fIoption\fP] " \-m +.BR locale " [\fIoption\fP] \fIname\fP..." +.fi +.SH DESCRIPTION +The +.B locale +command displays information about the current locale, or all locales, +on standard output. +.PP +When invoked without arguments, +.B locale +displays the current locale settings for each locale category (see +.BR locale (5)), +based on the settings of the environment variables that control the locale +(see +.BR locale (7)). +Values for variables set in the environment are printed without double +quotes, implied values are printed with double quotes. +.PP +If either the +.B \-a +or the +.B \-m +option (or one of their long-format equivalents) is specified, +the behavior is as follows: +.TP +.BR \-a ", " \-\-all\-locales +Display a list of all available locales. +The +.B -v +option causes the +.B LC_IDENTIFICATION +metadata about each locale to be included in the output. +.TP +.BR \-m ", " \-\-charmaps +Display the available charmaps (character set description files). +To display the current character set for the locale, use +\fBlocale -c charmap\fR. +.PP +The +.B locale +command can also be provided with one or more arguments, +which are the names of locale keywords (for example, +.IR date_fmt , +.IR ctype-class-names , +.IR yesexpr , +or +.IR decimal_point ) +or locale categories (for example, +.BR LC_CTYPE +or +.BR LC_TIME ). +For each argument, the following is displayed: +.IP * 3 +For a locale keyword, the value of that keyword to be displayed. +.IP * +For a locale category, +the values of all keywords in that category are displayed. +.PP +When arguments are supplied, the following options are meaningful: +.TP +.BR \-c ", " \-\-category\-name +For a category name argument, +write the name of the locale category +on a separate line preceding the list of keyword values for that category. +.IP +For a keyword name argument, +write the name of the locale category for this keyword +on a separate line preceding the keyword value. +.IP +This option improves readability when multiple name arguments are specified. +It can be combined with the +.B \-k +option. +.TP +.BR \-k ", " \-\-keyword\-name +For each keyword whose value is being displayed, +include also the name of that keyword, +so that the output has the format: +.IP + \fIkeyword\fP="\fIvalue\fP" +.PP +The +.B locale +command also knows about the following options: +.TP +.BR \-v ", " \-\-verbose +Display additional information for some command-line option and argument +combinations. +.TP +.BR \-? ", " \-\-help +Display a summary of command-line options and arguments and exit. +.TP +.BR \-\-usage +Display a short usage message and exit. +.TP +.BR \-V ", " \-\-version +Display the program version and exit. +.SH FILES +.TP +.I /usr/lib/locale/locale-archive +Usual default locale archive location. +.TP +.I /usr/share/i18n/locales +Usual default path for locale definition files. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +.EX +$ \fBlocale\fP +LANG=en_US.UTF\-8 +LC_CTYPE="en_US.UTF\-8" +LC_NUMERIC="en_US.UTF\-8" +LC_TIME="en_US.UTF\-8" +LC_COLLATE="en_US.UTF\-8" +LC_MONETARY="en_US.UTF\-8" +LC_MESSAGES="en_US.UTF\-8" +LC_PAPER="en_US.UTF\-8" +LC_NAME="en_US.UTF\-8" +LC_ADDRESS="en_US.UTF\-8" +LC_TELEPHONE="en_US.UTF\-8" +LC_MEASUREMENT="en_US.UTF\-8" +LC_IDENTIFICATION="en_US.UTF\-8" +LC_ALL= + +$ \fBlocale date_fmt\fP +%a %b %e %H:%M:%S %Z %Y + +$ \fBlocale \-k date_fmt\fP +date_fmt="%a %b %e %H:%M:%S %Z %Y" + +$ \fBlocale \-ck date_fmt\fP +LC_TIME +date_fmt="%a %b %e %H:%M:%S %Z %Y" + +$ \fBlocale LC_TELEPHONE\fP ++%c (%a) %l +(%a) %l +11 +1 +UTF\-8 + +$ \fBlocale \-k LC_TELEPHONE\fP +tel_int_fmt="+%c (%a) %l" +tel_dom_fmt="(%a) %l" +int_select="11" +int_prefix="1" +telephone\-codeset="UTF\-8" +.EE +.PP +The following example compiles a custom locale from the +.I ./wrk +directory with the +.BR localedef (1) +utility under the +.I $HOME/.locale +directory, then tests the result with the +.BR date (1) +command, and then sets the environment variables +.B LOCPATH +and +.B LANG +in the shell profile file so that the custom locale will be used in the +subsequent user sessions: +.PP +.EX +$ \fBmkdir -p $HOME/.locale\fP +$ \fBI18NPATH=./wrk/ localedef -f UTF-8 -i fi_SE $HOME/.locale/fi_SE.UTF-8\fP +$ \fBLOCPATH=$HOME/.locale LC_ALL=fi_SE.UTF-8 date\fP +$ \fBecho "export LOCPATH=\\$HOME/.locale" >> $HOME/.bashrc\fP +$ \fBecho "export LANG=fi_SE.UTF-8" >> $HOME/.bashrc\fP +.EE +.SH SEE ALSO +.BR localedef (1), +.BR charmap (5), +.BR locale (5), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/localedef.1 b/man1/localedef.1 new file mode 100644 index 0000000..03e7d24 --- /dev/null +++ b/man1/localedef.1 @@ -0,0 +1,383 @@ +.\" Copyright (C) 2001 Richard Braakman +.\" Copyright (C) 2004 Alastair McKinstry +.\" Copyright (C) 2005 Lars Wirzenius +.\" Copyright (C) 2014 Marko Myllynen +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" This manual page was initially written by Richard Braakman +.\" on behalf of the Debian GNU/Linux Project and anyone else +.\" who wants it. It was amended by Alastair McKinstry to +.\" explain new ISO 14652 elements, and amended further by +.\" Lars Wirzenius to document new functionality (as of GNU +.\" C library 2.3.5). +.\" +.TH LOCALEDEF 1 2017-09-15 "Linux" "Linux User Manual" +.SH NAME +localedef \- compile locale definition files +.SH SYNOPSIS +.ad l +.nh +.B localedef +.RI [ options ] +.I outputpath +.br +.B "localedef \-\-list\-archive" +.RI [ options ] +.br +.B "localedef \-\-delete\-from\-archive" +.RI [ options ] +.IR localename " ..." +.br +.B "localedef \-\-add\-to\-archive" +.RI [ options ] +.IR compiledpath +.br +.B "localedef \-\-version" +.br +.B "localedef \-\-help" +.br +.B "localedef \-\-usage" +.ad b +.hy +.SH DESCRIPTION +The +.B localedef +program reads the indicated +.I charmap +and +.I input +files, compiles them to a binary form quickly usable by the +locale functions in the C library +.RB ( setlocale (3), +.BR localeconv (3), +etc.), and places the output in +.IR outputpath . +.PP +The +.I outputpath +argument is interpreted as follows: +.IP * 3 +If +.I outputpath +contains a slash character ('/'), it is interpreted as the name of the +directory where the output definitions are to be stored. +In this case, there is a separate output file for each locale category +.RI ( LC_TIME , +.IR LC_NUMERIC , +and so on). +.IP * +If the +.B \-\-no\-archive +option is used, +.I outputpath +is the name of a subdirectory in +.I /usr/lib/locale +where per-category compiled files are placed. +.IP * +Otherwise, +.I outputpath +is the name of a locale and the compiled locale data is added to the +archive file +.IR /usr/lib/locale/locale-archive . +A locale archive is a memory-mapped file which contains all the +system-provided locales; +it is used by all localized programs when the environment variable +.B LOCPATH +is not set. +.PP +In any case, +.B localedef +aborts if the directory in which it tries to write locale files has +not already been created. +.PP +If no +.I charmapfile +is given, the value +.I ANSI_X3.4-1968 +(for ASCII) is used by default. +If no +.I inputfile +is given, or if it is given as a dash +(\-), +.B localedef +reads from standard input. +.SH OPTIONS +.SS Operation-selection options +A few options direct +.B localedef +to do something other than compile locale definitions. +Only one of these options should be used at a time. +.TP +.B \-\-delete\-from\-archive +Delete the named locales from the locale archive file. +.TP +.B \-\-list\-archive +List the locales contained in the locale archive file. +.TP +.B \-\-add\-to\-archive +Add the +.I compiledpath +directories to the locale archive file. +The directories should have been created by previous runs of +.BR localedef , +using +.BR \-\-no\-archive . +.SS Other options +Some of the following options are sensible only for certain operations; +generally, it should be self-evident which ones. +.TP +.BI \-f " charmapfile" "\fR, \fP\-\-charmap=" charmapfile +Specify the file that defines the character set +that is used by the input file. +If +.I charmapfile +contains a slash character ('/'), +it is interpreted as the name of the character map. +Otherwise, the file is sought in the current directory +and the default directory for character maps. +If the environment variable +.B I18NPATH +is set, +.I $I18NPATH/charmaps/ +and +.I $I18NPATH/ +are also searched after the current directory. +The default directory for character maps is printed by +.BR "localedef \-\-help" . +.TP +.BI \-i " inputfile" "\fR, \fP\-\-inputfile=" inputfile +Specify the locale definition file to compile. +The file is sought in the current directory +and the default directory for locale definition files. +If the environment variable +.B I18NPATH +is set, +.I $I18NPATH/locales/ +and +.I $I18NPATH +are also searched after the current directory. +The default directory for locale definition files is printed by +.BR "localedef \-\-help" . +.TP +.BI \-u " repertoirefile" "\fR, \fP\-\-repertoire-map=" repertoirefile +Read mappings from symbolic names to Unicode code points from +.IR repertoirefile . +If +.I repertoirefile +contains a slash character ('/'), +it is interpreted as the pathname of the repertoire map. +Otherwise, the file is sought in the current directory +and the default directory for repertoire maps. +If the environment variable +.B I18NPATH +is set, +.I $I18NPATH/repertoiremaps/ +and +.I $I18NPATH +are also searched after the current directory. +The default directory for repertoire maps is printed by +.BR "localedef \-\-help" . +.TP +.BI \-A " aliasfile" "\fR, \fP\-\-alias\-file=" aliasfile +Use +.I aliasfile +to look up aliases for locale names. +There is no default aliases file. +.TP +.BI \-\-prefix= pathname +Set the prefix to be prepended to the full archive pathname. +By default, the prefix is empty. +Setting the prefix to +.IR foo , +the archive would be placed in +.IR foo/usr/lib/locale/locale-archive . +.TP +.BR \-c ", " \-\-force +Write the output files even if warnings were generated about the input +file. +.TP +.BR \-v ", " \-\-verbose +Generate extra warnings about errors that are normally ignored. +.TP +.B \-\-quiet +Suppress all notifications and warnings, and report only fatal errors. +.TP +.B \-\-posix +Conform strictly to POSIX. Implies +.BR \-\-verbose . +This option currently has no other effect. +POSIX conformance is assumed if the environment variable +.B POSIXLY_CORRECT +is set. +.TP +.B \-\-replace +Replace a locale in the locale archive file. +Without this option, if the locale is in the archive file already, +an error occurs. +.TP +.B \-\-no\-archive +Do not use the locale archive file, instead create +.I outputpath +as a subdirectory in the same directory as the locale archive file, +and create separate output files for locale categories in it. +This is helpful to prevent system locale archive updates from overwriting +custom locales created with +.BR localedef . +.TP +.BR \-? ", " \-\-help +Print a usage summary and exit. +Also prints the default paths used by +.BR localedef . +.TP +.B "\-\-usage" +Print a short usage summary and exit. +.TP +.BR \-V ", " \-\-version +Print the version number, license, and disclaimer of warranty for +.BR localedef . +.SH EXIT STATUS +One of the following exit values can be returned by +.BR localedef : +.RS 3 +.TP 10 +.B 0 +Command completed successfully. +.TP +.B 1 +Warnings or errors occurred, output files were written. +.TP +.B 4 +Errors encountered, no output created. +.RE +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +The +.B \-\-posix +flag is assumed if this environment variable is set. +.TP +.B I18NPATH +A colon-separated list of search directories for files. +.SH FILES +.TP +.I /usr/share/i18n/charmaps +Usual default character map path. +.TP +.I /usr/share/i18n/locales +Usual default path for locale definition files. +.TP +.I /usr/share/i18n/repertoiremaps +Usual default repertoire map path. +.TP +.I /usr/lib/locale/locale-archive +Usual default locale archive location. +.TP +.I /usr/lib/locale +Usual default path for compiled individual locale data files. +.TP +.I outputpath/LC_ADDRESS +An output file that contains information about formatting of +addresses and geography-related items. +.TP +.I outputpath/LC_COLLATE +An output file that contains information about the rules for comparing +strings. +.TP +.I outputpath/LC_CTYPE +An output file that contains information about character classes. +.TP +.I outputpath/LC_IDENTIFICATION +An output file that contains metadata about the locale. +.TP +.I outputpath/LC_MEASUREMENT +An output file that contains information about locale measurements +(metric versus US customary). +.TP +.I outputpath/LC_MESSAGES/SYS_LC_MESSAGES +An output file that contains information about the language messages +should be printed in, and what an affirmative or negative answer looks +like. +.TP +.I outputpath/LC_MONETARY +An output file that contains information about formatting of monetary +values. +.TP +.I outputpath/LC_NAME +An output file that contains information about salutations for persons. +.TP +.I outputpath/LC_NUMERIC +An output file that contains information about formatting of nonmonetary +numeric values. +.TP +.I outputpath/LC_PAPER +An output file that contains information about settings related to +standard paper size. +.TP +.I outputpath/LC_TELEPHONE +An output file that contains information about formats to be used with +telephone services. +.TP +.I outputpath/LC_TIME +An output file that contains information about formatting of data and +time values. +.SH CONFORMING TO +POSIX.1-2008. +.SH EXAMPLE +Compile the locale files for Finnish in the UTF\-8 character set +and add it to the default locale archive with the name +.BR fi_FI.UTF\-8 : +.PP +.in +4n +.EX +localedef \-f UTF\-8 \-i fi_FI fi_FI.UTF\-8 +.EE +.in +.PP +The next example does the same thing, but generates files into the +.I fi_FI.UTF\-8 +directory which can then be used by programs when the environment +variable +.B LOCPATH +is set to the current directory (note that the last argument must +contain a slash): +.PP +.in +4n +.EX +localedef \-f UTF\-8 \-i fi_FI ./fi_FI.UTF\-8 +.EE +.in +.SH SEE ALSO +.BR locale (1), +.BR charmap (5), +.BR locale (5), +.BR repertoiremap (5), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/memusage.1 b/man1/memusage.1 new file mode 100644 index 0000000..f5494ff --- /dev/null +++ b/man1/memusage.1 @@ -0,0 +1,282 @@ +.\" Copyright (c) 2013, Peter Schiffer +.\" and Copyright (C) 2014, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH MEMUSAGE 1 2017-09-15 "GNU" "Linux user manual" +.SH NAME +memusage \- profile memory usage of a program +.SH SYNOPSIS +.BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..." +.SH DESCRIPTION +.B memusage +is a bash script which profiles memory usage of the program, +.IR program . +It preloads the +.B libmemusage.so +library into the caller's environment (via the +.B LD_PRELOAD +environment variable; see +.BR ld.so (8)). +The +.B libmemusage.so +library traces memory allocation by intercepting calls to +.BR malloc (3), +.BR calloc (3), +.BR free (3), +and +.BR realloc (3); +optionally, calls to +.BR mmap (2), +.BR mremap (2), +and +.BR munmap (2) +can also be intercepted. +.PP +.B memusage +can output the collected data in textual form, or it can use +.BR memusagestat (1) +(see the +.B -p +option, below) +to create a PNG file containing graphical representation +of the collected data. +.SS Memory usage summary +The "Memory usage summary" line output by +.BR memusage +contains three fields: +.RS 4 +.TP +\fBheap total\fR +Sum of \fIsize\fR arguments of all +.BR malloc (3) +calls, +products of arguments (\fInmemb\fR*\fIsize\fR) of all +.BR calloc (3) +calls, +and sum of \fIlength\fR arguments of all +.BR mmap (2) +calls. +In the case of +.BR realloc (3) +and +.BR mremap (2), +if the new size of an allocation is larger than the previous size, +the sum of all such differences (new size minus old size) is added. +.TP +.B "heap peak" +Maximum of all \fIsize\fR arguments of +.BR malloc (3), +all products of \fInmemb\fR*\fIsize\fR of +.BR calloc (3), +all \fIsize\fR arguments of +.BR realloc (3), +.I length +arguments of +.BR mmap (2), +and +\fInew_size\fR arguments of +.BR mremap (2). +.TP +.B "stack peak" +Before the first call to any monitored function, +the stack pointer address (base stack pointer) is saved. +After each function call, the actual stack pointer address is read and +the difference from the base stack pointer computed. +The maximum of these differences is then the stack peak. +.RE +.PP +Immediately following this summary line, a table shows the number calls, +total memory allocated or deallocated, +and number of failed calls for each intercepted function. +For +.BR realloc (3) +and +.BR mremap (2), +the additional field "nomove" shows reallocations that +changed the address of a block, +and the additional "dec" field shows reallocations that +decreased the size of the block. +For +.BR realloc (3), +the additional field "free" shows reallocations that +caused a block to be freed (i.e., the reallocated size was 0). +.PP +The "realloc/total memory" of the table output by +.B memusage +does not reflect cases where +.BR realloc (3) +is used to reallocate a block of memory +to have a smaller size than previously. +This can cause sum of all "total memory" cells (excluding "free") +to be larger than the "free/total memory" cell. +.SS Histogram for block sizes +The "Histogram for block sizes" provides a breakdown of memory +allocations into various bucket sizes. +.SH OPTIONS +.TP +.BI \-n\ name \fR,\ \fB\-\-progname= name +Name of the program file to profile. +.TP +.BI \-p\ file \fR,\ \fB\-\-png= file +Generate PNG graphic and store it in +.IR file . +.TP +.BI \-d\ file \fR,\ \fB\-\-data= file +Generate binary data file and store it in +.IR file . +.TP +.BI \-u\fR,\ \fB\-\-unbuffered +Do not buffer output. +.TP +.BI \-b\ size \fR,\ \fB\-\-buffer= size +Collect +.I size +entries before writing them out. +.TP +.BI \fB\-\-no-timer +Disable timer-based +.RB ( SIGPROF ) +sampling of stack pointer value. +.TP +.BI \-m\fR,\ \fB\-\-mmap +Also trace +.BR mmap (2), +.BR mremap (2), +and +.BR munmap (2). +.TP +.BI \-?\fR,\ \fB\-\-help +Print help and exit. +.TP +.BI \fB\-\-usage +Print a short usage message and exit. +.TP +.BI \-V\fR,\ \fB\-\-version +Print version information and exit. +.TP +The following options apply only when generating graphical output: +.TP +.BI \-t\fR,\ \fB\-\-time\-based +Use time (rather than number of function calls) as the scale for the X axis. +.TP +.BI \-T\fR,\ \fB\-\-total +Also draw a graph of total memory use. +.TP +.BI \fB\-\-title= name +Use +.I name +as the title of the graph. +.TP +.BI \-x\ size \fR,\ \fB\-\-x\-size= size +Make the graph +.I size +pixels wide. +.TP +.BI \-y\ size \fR,\ \fB\-\-y\-size= size +Make the graph +.I size +pixels high. +.SH EXIT STATUS +Exit status is equal to the exit status of profiled program. +.SH BUGS +To report bugs, see +.UR http://www.gnu.org/software/libc/bugs.html +.UE +.SH EXAMPLE +Below is a simple program that reallocates a block of +memory in cycles that rise to a peak before then cyclically +reallocating the memory in smaller blocks that return to zero. +After compiling the program and running the following commands, +a graph of the memory usage of the program can be found in the file +.IR memusage.png : +.PP +.in +4n +.EX +$ \fBmemusage \-\-data=memusage.dat ./a.out\fP +\&... +Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224 + total calls total memory failed calls + malloc| 1 400 0 +realloc| 40 44800 0 (nomove:40, dec:19, free:0) + calloc| 0 0 0 + free| 1 440 +Histogram for block sizes: + 192\-207 1 2% ================ +\&... + 2192\-2207 1 2% ================ + 2240\-2255 2 4% ================================= + 2832\-2847 2 4% ================================= + 3440\-3455 2 4% ================================= + 4032\-4047 2 4% ================================= + 4640\-4655 2 4% ================================= + 5232\-5247 2 4% ================================= + 5840\-5855 2 4% ================================= + 6432\-6447 1 2% ================ +$ \fBmemusagestat memusage.dat memusage.png\fP +.EE +.in +.SS Program source +.EX +#include +#include + +#define CYCLES 20 + +int +main(int argc, char *argv[]) +{ + int i, j; + int *p; + + printf("malloc: %zd\\n", sizeof(int) * 100); + p = malloc(sizeof(int) * 100); + + for (i = 0; i < CYCLES; i++) { + if (i < CYCLES / 2) + j = i; + else + j--; + + printf("realloc: %zd\\n", sizeof(int) * (j * 50 + 110)); + p = realloc(p, sizeof(int) * (j * 50 + 100)); + + printf("realloc: %zd\\n", sizeof(int) * ((j+1) * 150 + 110)); + p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110)); + } + + free(p); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR memusagestat (1), +.BR mtrace (1) +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/memusagestat.1 b/man1/memusagestat.1 new file mode 100644 index 0000000..8793b7b --- /dev/null +++ b/man1/memusagestat.1 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2013, Peter Schiffer +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH MEMUSAGESTAT 1 2017-09-15 "GNU" "Linux programmer's manual" +.SH NAME +memusagestat \- generate graphic from memory profiling data +.SH SYNOPSIS +.BR memusagestat " [\fIoption\fR]... \fIdatafile\fR [\fIoutfile\fR]" +.SH DESCRIPTION +.B memusagestat +creates a PNG file containing a graphical representation of the +memory profiling data in the file +.IR datafile ; +that file is generated via the +.I -d +(or +.IR --data ) +option of +.BR memusage (1). +.PP +The red line in the graph shows the heap usage (allocated memory) +and the green line shows the stack usage. +The x-scale is either the number of memory-handling function calls or +(if the +.I -t +option is specified) +time. +.SH OPTIONS +.TP +.BI \-o\ file \fR,\ \fB\-\-output= file +Name of the output file. +.TP +.BI \-s\ string \fR,\ \fB\-\-string= string +Use +.I string +as the title inside the output graph. +.TP +.BI \-t\fR,\ \fB\-\-time +Use time (rather than number of function calls) as the scale for the X axis. +.TP +.BI \-T\fR,\ \fB\-\-total +Also draw a graph of total memory consumption. +.TP +.BI \-x\ size \fR,\ \fB\-\-x-size= size +Make the output graph +.I size +pixels wide. +.TP +.BI \-y\ size \fR,\ \fB\-\-y\-size= size +Make the output graph +.I size +pixels high. +.TP +.BI \-?\fR,\ \fB\-\-help +Print a help message and exit. +.TP +.BI \fB\-\-usage +Print a short usage message and exit. +.TP +.BI \-V\fR,\ \fB\-\-version +Print version information and exit. +.SH BUGS +To report bugs, see +.UR http://www.gnu.org/software/libc/bugs.html +.UE +.SH EXAMPLE +See +.BR memusage (1). +.SH SEE ALSO +.BR memusage (1), +.BR mtrace (1) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/mtrace.1 b/man1/mtrace.1 new file mode 100644 index 0000000..5a400d6 --- /dev/null +++ b/man1/mtrace.1 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2013, Peter Schiffer (pschiffe@redhat.com) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH MTRACE 1 2017-09-15 "GNU" "Linux user manual" +.SH NAME +mtrace \- interpret the malloc trace log +.SH SYNOPSIS +.BR mtrace " [\fIoption\fR]... [\fIbinary\fR] \fImtracedata\fR" +.SH DESCRIPTION +.B mtrace +is a Perl script used to interpret and provide human readable output +of the trace log contained in the file +.IR mtracedata , +whose contents were produced by +.BR mtrace (3). +If +.I binary +is provided, the output of +.B mtrace +also contains the source file name with line number information +for problem locations +(assuming that +.I binary +was compiled with debugging information). +.PP +For more information about the +.BR mtrace (3) +function and +.B mtrace +script usage, see +.BR mtrace (3). +.SH OPTIONS +.TP +.BI \fB\-\-help +Print help and exit. +.TP +.BI \fB\-\-version +Print version information and exit. +.SH BUGS +For bug reporting instructions, please see: +.UR http://www.gnu.org/software/libc/bugs.html +.UE . +.SH SEE ALSO +.BR memusage (1), +.BR mtrace (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/pldd.1 b/man1/pldd.1 new file mode 100644 index 0000000..0c744f0 --- /dev/null +++ b/man1/pldd.1 @@ -0,0 +1,131 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PLDD 1 2017-09-15 "GNU" "Linux User Manual" +.SH NAME +pldd \- display dynamic shared objects linked into a process +.SH SYNOPSIS +.nf +.BI "pldd " "pid" +.BI pldd " option" +.fi +.SH DESCRIPTION +The +.B pldd +command displays a list of the dynamic shared objects that are +linked into the process with the specified process ID. +The list includes the libraries that have been dynamically loaded using +.BR dlopen (3). +.SH OPTIONS +.TP +.BR \-? ", " \-\-help +Display program help message. +.TP +.BR \-\-usage +Display a short usage message. +.TP +.BR \-V ", " \-\-version +Display the program version. +.SH EXIT STATUS +On success, +.B pldd +exits with the status 0. +If the specified process does not exist, +the user does not have permission to access +its dynamic shared object list, +or no command-line arguments are supplied, +.B pldd +exists with a status of 1. +If given an invalid option, it exits with the status 64. +.SH VERSIONS +.B pldd +is available since glibc 2.15. +.SH CONFORMING TO +The +.B pldd +command is not specified by POSIX.1. +Some other systems +.\" There are man pages on Solaris and HP-UX. +have a similar command. +.SH NOTES +The command +.PP +.in +4n +.EX +lsof \-p PID +.EE +.in +.PP +also shows output that includes the dynamic shared objects +that are linked into a process. +.PP +The +.BR gdb (1) +.I "info shared" +command also shows the shared libraries being used by a process, +so that one can obtain similar output to +.BR pldd +using a command such as the following +(to monitor the process with the specified +.IR pid ): +.PP +.in +4n +.EX +$ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \\\fP + \fB-ex "quit" \-p $pid | grep '^0x.*0x'\fP +.EE +.in +.SH BUGS +Since glibc 2.19, +.B pldd +is broken: it just hangs when executed. +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=18035 +It is unclear if it will ever be fixed. +.SH EXAMPLE +.EX +$ \fBecho $$\fP # Display PID of shell +1143 +$ \fBpldd $$\fP # Display DSOs linked into the shell +1143: /usr/bin/bash +linux\-vdso.so.1 +/lib64/libtinfo.so.5 +/lib64/libdl.so.2 +/lib64/libc.so.6 +/lib64/ld\-linux\-x86\-64.so.2 +/lib64/libnss_files.so.2 +.EE +.SH SEE ALSO +.BR ldd (1), +.BR lsof (1), +.BR dlopen (3), +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/sprof.1 b/man1/sprof.1 new file mode 100644 index 0000000..f7639db --- /dev/null +++ b/man1/sprof.1 @@ -0,0 +1,311 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SPROF 1 2017-09-15 "Linux" "Linux User Manual" +.SH NAME +sprof \- read and display shared object profiling data +.SH SYNOPSIS +.nf +.BR sprof " [\fIoption\fP]... \fIshared-object-path\fP \ +[\fIprofile-data-path\fP]" +.fi +.SH DESCRIPTION +The +.B sprof +command displays a profiling summary for the +shared object (shared library) specified as its first command-line argument. +The profiling summary is created using previously generated +profiling data in the (optional) second command-line argument. +If the profiling data pathname is omitted, then +.B sprof +will attempt to deduce it using the soname of the shared object, +looking for a file with the name +.IR .profile +in the current directory. +.SH OPTIONS +The following command-line options specify the profile output +to be produced: +.TP +.BR \-c ", " \-\-call\-pairs +Print a list of pairs of call paths for the interfaces exported +by the shared object, +along with the number of times each path is used. +.TP +.BR \-p ", " \-\-flat\-profile +Generate a flat profile of all of the functions in the monitored object, +with counts and ticks. +.TP +.BR \-q ", " \-\-graph +Generate a call graph. +.PP +If none of the above options is specified, +then the default behavior is to display a flat profile and a call graph. +.PP +The following additional command-line options are available: +.TP +.BR \-? ", " \-\-help +Display a summary of command-line options and arguments and exit. +.TP +.BR \-\-usage +Display a short usage message and exit. +.TP +.BR \-V ", " \-\-version +Display the program version and exit. +.SH CONFORMING TO +The +.B sprof +command is a GNU extension, not present in POSIX.1. +.SH EXAMPLE +The following example demonstrates the use of +.BR sprof . +The example consists of a main program that calls two functions +in a shared object. +First, the code of the main program: +.PP +.in +4n +.EX +$ \fBcat prog.c\fP +#include + +void x1(void); +void x2(void); + +int +main(int argc, char *argv[]) +{ + x1(); + x2(); + exit(EXIT_SUCCESS); +} +.EE +.in +.PP +The functions +.IR x1() +and +.IR x2() +are defined in the following source file that is used to +construct the shared object: +.PP +.in +4n +.EX +$ \fBcat libdemo.c\fP +#include + +void +consumeCpu1(int lim) +{ + int j; + + for (j = 0; j < lim; j++) + getppid(); +} + +void +x1(void) { + int j; + + for (j = 0; j < 100; j++) + consumeCpu1(200000); +} + +void +consumeCpu2(int lim) +{ + int j; + + for (j = 0; j < lim; j++) + getppid(); +} + +void +x2(void) +{ + int j; + + for (j = 0; j < 1000; j++) + consumeCpu2(10000); +} +.EE +.in +.PP +Now we construct the shared object with the real name +.IR libdemo.so.1.0.1 , +and the soname +.IR libdemo.so.1 : +.PP +.in +4n +.EX +$ \fBcc \-g \-fPIC \-shared \-Wl,\-soname,libdemo.so.1 \e\fP + \fB\-o libdemo.so.1.0.1 libdemo.c\fP +.EE +.in +.PP +Then we construct symbolic links for the library soname and +the library linker name: +.PP +.in +4n +.EX +$ \fBln \-sf libdemo.so.1.0.1 libdemo.so.1\fP +$ \fBln \-sf libdemo.so.1 libdemo.so\fP +.EE +.in +.PP +Next, we compile the main program, linking it against the shared object, +and then list the dynamic dependencies of the program: +.PP +.in +4n +.EX +$ \fBcc \-g \-o prog prog.c \-L. \-ldemo\fP +$ \fBldd prog\fP + linux\-vdso.so.1 => (0x00007fff86d66000) + libdemo.so.1 => not found + libc.so.6 => /lib64/libc.so.6 (0x00007fd4dc138000) + /lib64/ld\-linux\-x86\-64.so.2 (0x00007fd4dc51f000) +.EE +.in +.PP +In order to get profiling information for the shared object, +we define the environment variable +.BR LD_PROFILE +with the soname of the library: +.PP +.in +4n +.EX +$ \fBexport LD_PROFILE=libdemo.so.1\fP +.EE +.in +.PP +We then define the environment variable +.BR LD_PROFILE_OUTPUT +with the pathname of the directory where profile output should be written, +and create that directory if it does not exist already: +.PP +.in +4n +.EX +$ \fBexport LD_PROFILE_OUTPUT=$(pwd)/prof_data\fP +$ \fBmkdir \-p $LD_PROFILE_OUTPUT\fP +.EE +.in +.PP +.B LD_PROFILE +causes profiling output to be +.I appended +to the output file if it already exists, +so we ensure that there is no preexisting profiling data: +.PP +.in +4n +.EX +$ \fBrm \-f $LD_PROFILE_OUTPUT/$LD_PROFILE.profile\fP +.EE +.in +.PP +We then run the program to produce the profiling output, +which is written to a file in the directory specified in +.BR LD_PROFILE_OUTPUT : +.PP +.in +4n +.EX +$ \fBLD_LIBRARY_PATH=. ./prog\fP +$ \fBls prof_data\fP +libdemo.so.1.profile +.EE +.in +.PP +We then use the +.BR "sprof \-p" +option to generate a flat profile with counts and ticks: +.PP +.in +4n +.EX +$ \fBsprof \-p libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP +Flat profile: + +Each sample counts as 0.01 seconds. + % cumulative self self total + time seconds seconds calls us/call us/call name + 60.00 0.06 0.06 100 600.00 consumeCpu1 + 40.00 0.10 0.04 1000 40.00 consumeCpu2 + 0.00 0.10 0.00 1 0.00 x1 + 0.00 0.10 0.00 1 0.00 x2 +.EE +.in +.PP +The +.BR "sprof \-q" +option generates a call graph: +.PP +.in +4n +.EX +$ \fBsprof \-q libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP + +index % time self children called name + + 0.00 0.00 100/100 x1 [1] +[0] 100.0 0.00 0.00 100 consumeCpu1 [0] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0.00 0.00 1/1 +[1] 0.0 0.00 0.00 1 x1 [1] + 0.00 0.00 100/100 consumeCpu1 [0] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0.00 0.00 1000/1000 x2 [3] +[2] 0.0 0.00 0.00 1000 consumeCpu2 [2] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0.00 0.00 1/1 +[3] 0.0 0.00 0.00 1 x2 [3] + 0.00 0.00 1000/1000 consumeCpu2 [2] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.EE +.in +.PP +Above and below, the "" strings represent identifiers that +are outside of the profiled object (in this example, these are instances of +.IR main() ). +.PP +The +.BR "sprof \-c" +option generates a list of call pairs and the number of their occurrences: +.PP +.in +4n +.EX +$ \fBsprof \-c libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP + x1 1 +x1 consumeCpu1 100 + x2 1 +x2 consumeCpu2 1000 +.EE +.in +.SH SEE ALSO +.BR gprof (1), +.BR ldd (1), +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man1/time.1 b/man1/time.1 new file mode 100644 index 0000000..07a2236 --- /dev/null +++ b/man1/time.1 @@ -0,0 +1,334 @@ +.\" Copyright Andries Brouwer, 2000 +.\" Some fragments of text came from the time-1.7 info file. +.\" Inspired by kromJx@crosswinds.net. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH TIME 1 2017-09-15 "" "Linux User's Manual" +.SH NAME +time \- time a simple command or give resource usage +.SH SYNOPSIS +.BI "time [" options "] " command " [" arguments... "] " +.SH DESCRIPTION +The +.B time +command runs the specified program +.I command +with the given arguments. +When +.I command +finishes, +.B time +writes a message to standard error giving timing statistics +about this program run. +These statistics consist of (i) the elapsed real time +between invocation and termination, (ii) the user CPU time +(the sum of the +.I tms_utime +and +.I tms_cutime +values in a +.I "struct tms" +as returned by +.BR times (2)), +and (iii) the system CPU time (the sum of the +.I tms_stime +and +.I tms_cstime +values in a +.I "struct tms" +as returned by +.BR times (2)). +.PP +Note: some shells (e.g., +.BR bash (1)) +have a built-in +.B time +command that provides similar information on the usage of time and +possibly other resources. +To access the real command, you may need to specify its pathname +(something like +.IR /usr/bin/time ). +.SH OPTIONS +.TP +.B \-p +When in the POSIX locale, use the precise traditional format +.IP +.in +4n +.EX +"real %f\enuser %f\ensys %f\en" +.EE +.in +.IP +(with numbers in seconds) +where the number of decimals in the output for %f is unspecified +but is sufficient to express the clock tick accuracy, and at least one. +.SH EXIT STATUS +If +.I command +was invoked, the exit status is that of +.IR command . +Otherwise, it is 127 if +.I command +could not be found, 126 if it could be found but could not be invoked, +and some other nonzero value (1\(en125) if something else went wrong. +.SH ENVIRONMENT +The variables +.BR LANG , +.BR LC_ALL , +.BR LC_CTYPE , +.BR LC_MESSAGES , +.BR LC_NUMERIC , +and +.BR NLSPATH +are used for the text and formatting of the output. +.B PATH +is used to search for +.IR command . +The remaining ones for the text and formatting of the output. +.SH GNU VERSION +Below a description of the GNU 1.7 version of +.BR time . +Disregarding the name of the utility, GNU makes it output lots of +useful information, not only about time used, but also on other +resources like memory, I/O and IPC calls (where available). +The output is formatted using a format string that can be specified +using the +.I \-f +option or the +.B TIME +environment variable. +.PP +The default format string is: +.PP +.in +4n +.EX +%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k +%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps +.EE +.in +.PP +When the +.I \-p +option is given, the (portable) output format is used: +.PP +.in +4n +.EX +real %e +user %U +sys %S +.EE +.in +.\" +.SS The format string +The format is interpreted in the usual printf-like way. +Ordinary characters are directly copied, tab, newline +and backslash are escaped using \et, \en and \e\e, +a percent sign is represented by %%, and otherwise % +indicates a conversion. +The program +.B time +will always add a trailing newline itself. +The conversions follow. +All of those used by +.BR tcsh (1) +are supported. +.PP +.B "Time" +.TP +.B %E +Elapsed real time (in [hours:]minutes:seconds). +.TP +.B %e +(Not in +.BR tcsh (1).) +Elapsed real time (in seconds). +.TP +.B %S +Total number of CPU-seconds that the process spent in kernel mode. +.TP +.B %U +Total number of CPU-seconds that the process spent in user mode. +.TP +.B %P +Percentage of the CPU that this job got, computed as (%U + %S) / %E. +.PP +.B "Memory" +.TP +.B %M +Maximum resident set size of the process during its lifetime, in Kbytes. +.TP +.B %t +(Not in +.BR tcsh (1).) +Average resident set size of the process, in Kbytes. +.TP +.B %K +Average total (data+stack+text) memory use of the process, +in Kbytes. +.TP +.B %D +Average size of the process's unshared data area, in Kbytes. +.TP +.B %p +(Not in +.BR tcsh (1).) +Average size of the process's unshared stack space, in Kbytes. +.TP +.B %X +Average size of the process's shared text space, in Kbytes. +.TP +.B %Z +(Not in +.BR tcsh (1).) +System's page size, in bytes. +This is a per-system constant, but varies between systems. +.TP +.B %F +Number of major page faults that occurred while the process was running. +These are faults where the page has to be read in from disk. +.TP +.B %R +Number of minor, or recoverable, page faults. +These are faults for pages that are not valid but which have +not yet been claimed by other virtual pages. +Thus the data +in the page is still valid but the system tables must be updated. +.TP +.B %W +Number of times the process was swapped out of main memory. +.TP +.B %c +Number of times the process was context-switched involuntarily +(because the time slice expired). +.TP +.B %w +Number of waits: times that the program was context-switched voluntarily, +for instance while waiting for an I/O operation to complete. +.PP +.B "I/O" +.TP +.B %I +Number of filesystem inputs by the process. +.TP +.B %O +Number of filesystem outputs by the process. +.TP +.B %r +Number of socket messages received by the process. +.TP +.B %s +Number of socket messages sent by the process. +.TP +.B %k +Number of signals delivered to the process. +.TP +.B %C +(Not in +.BR tcsh (1).) +Name and command-line arguments of the command being timed. +.TP +.B %x +(Not in +.BR tcsh (1).) +Exit status of the command. +.SS GNU options +.TP +.BI "\-f " format ", \-\-format=" format +Specify output format, possibly overriding the format specified +in the environment variable TIME. +.TP +.B "\-p, \-\-portability" +Use the portable output format. +.TP +.BI "\-o " file ", \-\-output=" file +Do not send the results to +.IR stderr , +but overwrite the specified file. +.TP +.B "\-a, \-\-append" +(Used together with \-o.) Do not overwrite but append. +.TP +.B "\-v, \-\-verbose" +Give very verbose output about all the program knows about. +.SS GNU standard options +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-V, \-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH BUGS +Not all resources are measured by all versions of UNIX, +so some of the values might be reported as zero. +The present selection was mostly inspired by the data +provided by 4.2 or 4.3BSD. +.PP +GNU time version 1.7 is not yet localized. +Thus, it does not implement the POSIX requirements. +.PP +The environment variable +.B TIME +was badly chosen. +It is not unusual for systems like +.BR autoconf (1) +or +.BR make (1) +to use environment variables with the name of a utility to override +the utility to be used. +Uses like MORE or TIME for options to programs +(instead of program pathnames) tend to lead to difficulties. +.PP +It seems unfortunate that +.I \-o +overwrites instead of appends. +(That is, the +.I \-a +option should be the default.) +.PP +Mail suggestions and bug reports for GNU +.B time +to +.IR bug\-utils@prep.ai.mit.edu . +Please include the version of +.BR time , +which you can get by running +.PP +.in +4n +.EX +time \-\-version +.EE +.in +.PP +and the operating system +and C compiler you used. +.\" .SH AUTHORS +.\" .TP +.\" .IP "David Keppel" +.\" Original version +.\" .IP "David MacKenzie" +.\" POSIXization, autoconfiscation, GNU getoptization, +.\" documentation, other bug fixes and improvements. +.\" .IP "Arne Henrik Juul" +.\" Helped with portability +.\" .IP "Francois Pinard" +.\" Helped with portability +.SH SEE ALSO +.BR bash (1), +.BR tcsh (1), +.BR times (2), +.BR wait3 (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/_Exit.2 b/man2/_Exit.2 new file mode 100644 index 0000000..9f9d2e7 --- /dev/null +++ b/man2/_Exit.2 @@ -0,0 +1 @@ +.so man2/_exit.2 diff --git a/man2/__clone2.2 b/man2/__clone2.2 new file mode 100644 index 0000000..68f41a5 --- /dev/null +++ b/man2/__clone2.2 @@ -0,0 +1 @@ +.so man2/clone.2 diff --git a/man2/_exit.2 b/man2/_exit.2 new file mode 100644 index 0000000..25187cc --- /dev/null +++ b/man2/_exit.2 @@ -0,0 +1,142 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 21 23:02:38 1993 by Rik Faith +.\" Modified 2001-11-17, aeb +.\" +.TH _EXIT 2 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +_exit, _Exit \- terminate the calling process +.SH SYNOPSIS +.B #include +.PP +.BI "void _exit(int " status ); + +.B #include +.PP +.BI "void _Exit(int " status ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR _Exit (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +The function +.BR _exit () +terminates the calling process "immediately". +Any open file descriptors belonging to the process are closed. +Any children of the process are inherited by +.BR init (1) +(or by the nearest "subreaper" process as defined through the use of the +.BR prctl (2) +.B PR_SET_CHILD_SUBREAPER +operation). +The process's parent is sent a +.B SIGCHLD +signal. +.PP +The value +.I "status & 0377" +is returned to the parent process as the process's exit status, and +can be collected using one of the +.BR wait (2) +family of calls. +.PP +The function +.BR _Exit () +is equivalent to +.BR _exit (). +.SH RETURN VALUE +These functions do not return. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +The function +.BR _Exit () +was introduced by C99. +.SH NOTES +For a discussion on the effects of an exit, the transmission of +exit status, zombie processes, signals sent, and so on, see +.BR exit (3). +.PP +The function +.BR _exit () +is like +.BR exit (3), +but does not call any +functions registered with +.BR atexit (3) +or +.BR on_exit (3). +Open +.BR stdio (3) +streams are not flushed. +On the other hand, +.BR _exit () +does close open file descriptors, and this may cause an unknown delay, +waiting for pending output to finish. +If the delay is undesired, +it may be useful to call functions like +.BR tcflush (3) +before calling +.BR _exit (). +Whether any pending I/O is canceled, and which pending I/O may be +canceled upon +.BR _exit (), +is implementation-dependent. +.SS C library/kernel differences +In glibc up to version 2.3, the +.BR _exit () +wrapper function invoked the kernel system call of the same name. +Since glibc 2.3, the wrapper function invokes +.BR exit_group (2), +in order to terminate all of the threads in a process. +.SH SEE ALSO +.BR execve (2), +.BR exit_group (2), +.BR fork (2), +.BR kill (2), +.BR wait (2), +.BR wait4 (2), +.BR waitpid (2), +.BR atexit (3), +.BR exit (3), +.BR on_exit (3), +.BR termios (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/_llseek.2 b/man2/_llseek.2 new file mode 100644 index 0000000..d15dbee --- /dev/null +++ b/man2/_llseek.2 @@ -0,0 +1 @@ +.so man2/llseek.2 diff --git a/man2/_newselect.2 b/man2/_newselect.2 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man2/_newselect.2 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man2/_syscall.2 b/man2/_syscall.2 new file mode 100644 index 0000000..81ee074 --- /dev/null +++ b/man2/_syscall.2 @@ -0,0 +1,195 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Tue Jul 6 12:42:46 MDT 1993 +.\" Added "Calling Directly" and supporting paragraphs +.\" +.\" Modified Sat Jul 24 15:19:12 1993 by Rik Faith +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Added explanation of arg stacking when 6 or more args. +.\" +.\" Modified 10 June 1995 by Andries Brouwer +.\" +.\" 2007-10-23 mtk: created as a new page, by taking the content +.\" specific to the _syscall() macros from intro(2). +.\" +.TH _SYSCALL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +_syscall \- invoking a system call without library support (OBSOLETE) +.SH SYNOPSIS +.B #include +.PP +A _syscall macro +.PP +desired system call +.SH DESCRIPTION +The important thing to know about a system call is its prototype. +You need to know how many arguments, their types, +and the function return type. +There are seven macros that make the actual call into the system easier. +They have the form: +.PP +.in +4n +.EX +.RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...) +.EE +.in +.PP +where +.IP +.I X +is 0\(en6, which are the number of arguments taken by the +system call +.IP +.I type +is the return type of the system call +.IP +.I name +is the name of the system call +.IP +.I typeN +is the Nth argument's type +.IP +.I argN +is the name of the Nth argument +.PP +These macros create a function called +.I name +with the arguments you +specify. +Once you include the _syscall() in your source file, +you call the system call by +.IR name . +.SH FILES +.I /usr/include/linux/unistd.h +.SH CONFORMING TO +The use of these macros is Linux-specific, and deprecated. +.SH NOTES +Starting around kernel 2.6.18, the _syscall macros were removed +from header files supplied to user space. +Use +.BR syscall (2) +instead. +(Some architectures, notably ia64, never provided the _syscall macros; +on those architectures, +.BR syscall (2) +was always required.) +.PP +The _syscall() macros +.I "do not" +produce a prototype. +You may have to +create one, especially for C++ users. +.PP +System calls are not required to return only positive or negative error +codes. +You need to read the source to be sure how it will return errors. +Usually, it is the negative of a standard error code, +for example, +.RI \- EPERM . +The _syscall() macros will return the result +.I r +of the system call +when +.I r +is nonnegative, but will return \-1 and set the variable +.I errno +to +.RI \- r +when +.I r +is negative. +For the error codes, see +.BR errno (3). +.PP +When defining a system call, the argument types +.I must +be +passed by-value or by-pointer (for aggregates like structs). +.\" The preferred way to invoke system calls that glibc does not know +.\" about yet is via +.\" .BR syscall (2). +.\" However, this mechanism can be used only if using a libc +.\" (such as glibc) that supports +.\" .BR syscall (2), +.\" and if the +.\" .I +.\" header file contains the required SYS_foo definition. +.\" Otherwise, the use of a _syscall macro is required. +.\" +.SH EXAMPLE +.EX +#include +#include +#include +#include /* for _syscallX macros/related stuff */ +#include /* for struct sysinfo */ + +_syscall1(int, sysinfo, struct sysinfo *, info); + +int +main(void) +{ + struct sysinfo s_info; + int error; + + error = sysinfo(&s_info); + printf("code error = %d\\n", error); + printf("Uptime = %lds\\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\\n" + "RAM: total %lu / free %lu / shared %lu\\n" + "Memory in buffers = %lu\\nSwap: total %lu / free %lu\\n" + "Number of processes = %d\\n", + s_info.uptime, s_info.loads[0], + s_info.loads[1], s_info.loads[2], + s_info.totalram, s_info.freeram, + s_info.sharedram, s_info.bufferram, + s_info.totalswap, s_info.freeswap, + s_info.procs); + exit(EXIT_SUCCESS); +} +.EE +.SS Sample output +.EX +code error = 0 +uptime = 502034s +Load: 1 min 13376 / 5 min 5504 / 15 min 1152 +RAM: total 15343616 / free 827392 / shared 8237056 +Memory in buffers = 5066752 +Swap: total 27881472 / free 24698880 +Number of processes = 40 +.EE +.SH SEE ALSO +.BR intro (2), +.BR syscall (2), +.BR errno (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/_sysctl.2 b/man2/_sysctl.2 new file mode 100644 index 0000000..9e14d4b --- /dev/null +++ b/man2/_sysctl.2 @@ -0,0 +1 @@ +.so man2/sysctl.2 diff --git a/man2/accept.2 b/man2/accept.2 new file mode 100644 index 0000000..7938795 --- /dev/null +++ b/man2/accept.2 @@ -0,0 +1,384 @@ +.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-21 by Eric S. Raymond +.\" Modified 1998-2000 by Andi Kleen to match Linux 2.2 reality +.\" Modified 2002-04-23 by Roger Luethi +.\" Modified 2004-06-17 by Michael Kerrisk +.\" 2008-12-04, mtk, Add documentation of accept4() +.\" +.TH ACCEPT 2 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +accept, accept4 \- accept a connection on a socket +.SH SYNOPSIS +.nf +.BR "#include " " /* See NOTES */" +.B #include +.PP +.BI "int accept(int " sockfd ", struct sockaddr *" addr ", socklen_t *" addrlen ); + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int accept4(int " sockfd ", struct sockaddr *" addr , +.BI " socklen_t *" addrlen ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR accept () +system call is used with connection-based socket types +.RB ( SOCK_STREAM , +.BR SOCK_SEQPACKET ). +It extracts the first connection request on the queue of pending +connections for the listening socket, +.IR sockfd , +creates a new connected socket, and returns a new file +descriptor referring to that socket. +The newly created socket is not in the listening state. +The original socket +.I sockfd +is unaffected by this call. +.PP +The argument +.I sockfd +is a socket that has been created with +.BR socket (2), +bound to a local address with +.BR bind (2), +and is listening for connections after a +.BR listen (2). +.PP +The argument +.I addr +is a pointer to a +.I sockaddr +structure. +This structure is filled in with the address of the peer socket, +as known to the communications layer. +The exact format of the address returned +.I addr +is determined by the socket's address family (see +.BR socket (2) +and the respective protocol man pages). +When +.I addr +is NULL, nothing is filled in; in this case, +.I addrlen +is not used, and should also be NULL. +.PP +The +.I addrlen +argument is a value-result argument: +the caller must initialize it to contain the +size (in bytes) of the structure pointed to by +.IR addr ; +on return it will contain the actual size of the peer address. +.PP +The returned address is truncated if the buffer provided is too small; +in this case, +.I addrlen +will return a value greater than was supplied to the call. +.PP +If no pending +connections are present on the queue, and the socket is not marked as +nonblocking, +.BR accept () +blocks the caller until a connection is present. +If the socket is marked +nonblocking and no pending connections are present on the queue, +.BR accept () +fails with the error +.BR EAGAIN +or +.BR EWOULDBLOCK . +.PP +In order to be notified of incoming connections on a socket, you can use +.BR select (2), +.BR poll (2), +or +.BR epoll (7). +A readable event will be delivered when a new connection is attempted and you +may then call +.BR accept () +to get a socket for that connection. +Alternatively, you can set the socket to deliver +.B SIGIO +when activity occurs on a socket; see +.BR socket (7) +for details. +.PP +If +.IR flags +is 0, then +.BR accept4 () +is the same as +.BR accept (). +The following values can be bitwise ORed in +.IR flags +to obtain different behavior: +.TP 16 +.B SOCK_NONBLOCK +Set the +.BR O_NONBLOCK +file status flag on the new open file description. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B SOCK_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.SH RETURN VALUE +On success, +these system calls return a nonnegative integer that is a file descriptor +for the accepted socket. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SS Error handling +Linux +.BR accept () +(and +.BR accept4 ()) +passes already-pending network errors on the new socket +as an error code from +.BR accept (). +This behavior differs from other BSD socket +implementations. +For reliable operation the application should detect +the network errors defined for the protocol after +.BR accept () +and treat +them like +.B EAGAIN +by retrying. +In the case of TCP/IP, these are +.BR ENETDOWN , +.BR EPROTO , +.BR ENOPROTOOPT , +.BR EHOSTDOWN , +.BR ENONET , +.BR EHOSTUNREACH , +.BR EOPNOTSUPP , +and +.BR ENETUNREACH . +.SH ERRORS +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The socket is marked nonblocking and no connections are +present to be accepted. +POSIX.1-2001 and POSIX.1-2008 +allow either error to be returned for this case, +and do not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EBADF +.I sockfd +is not an open file descriptor. +.TP +.B ECONNABORTED +A connection has been aborted. +.TP +.B EFAULT +The +.I addr +argument is not in a writable part of the user address space. +.TP +.B EINTR +The system call was interrupted by a signal that was caught +before a valid connection arrived; see +.BR signal (7). +.TP +.B EINVAL +Socket is not listening for connections, or +.I addrlen +is invalid (e.g., is negative). +.TP +.B EINVAL +.RB ( accept4 ()) +invalid value in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.BR ENOBUFS ", " ENOMEM +Not enough free memory. +This often means that the memory allocation is limited by the socket buffer +limits, not by the system memory. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.TP +.B EOPNOTSUPP +The referenced socket is not of type +.BR SOCK_STREAM . +.TP +.B EPROTO +Protocol error. +.PP +In addition, Linux +.BR accept () +may fail if: +.TP +.B EPERM +Firewall rules forbid connection. +.PP +In addition, network errors for the new socket and as defined +for the protocol may be returned. +Various Linux kernels can +return other errors such as +.BR ENOSR , +.BR ESOCKTNOSUPPORT , +.BR EPROTONOSUPPORT , +.BR ETIMEDOUT . +The value +.B ERESTARTSYS +may be seen during a trace. +.SH VERSIONS +The +.BR accept4 () +system call is available starting with Linux 2.6.28; +support in glibc is available starting with version 2.10. +.SH CONFORMING TO +.BR accept (): +POSIX.1-2001, POSIX.1-2008, +SVr4, 4.4BSD +.RB ( accept () +first appeared in 4.2BSD). +.\" The BSD man page documents five possible error returns +.\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). +.\" POSIX.1-2001 documents errors +.\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, +.\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. +.\" In addition, SUSv2 documents EFAULT and ENOSR. +.PP +.BR accept4 () +is a nonstandard Linux extension. +.PP +On Linux, the new socket returned by +.BR accept () +does \fInot\fP inherit file status flags such as +.B O_NONBLOCK +and +.B O_ASYNC +from the listening socket. +This behavior differs from the canonical BSD sockets implementation. +.\" Some testing seems to show that Tru64 5.1 and HP-UX 11 also +.\" do not inherit file status flags -- MTK Jun 05 +Portable programs should not rely on inheritance or noninheritance +of file status flags and always explicitly set all required flags on +the socket returned from +.BR accept (). +.SH NOTES +POSIX.1-2001 does not require the inclusion of +.IR , +and this header file is not required on Linux. +However, some historical (BSD) implementations required this header +file, and portable applications are probably wise to include it. +.PP +There may not always be a connection waiting after a +.B SIGIO +is delivered or +.BR select (2), +.BR poll (2), +or +.BR epoll (7) +return a readability event because the connection might have been +removed by an asynchronous network error or another thread before +.BR accept () +is called. +If this happens, then the call will block waiting for the next +connection to arrive. +To ensure that +.BR accept () +never blocks, the passed socket +.I sockfd +needs to have the +.B O_NONBLOCK +flag set (see +.BR socket (7)). +.PP +For certain protocols which require an explicit confirmation, +such as DECnet, +.BR accept () +can be thought of as merely dequeuing the next connection request and not +implying confirmation. +Confirmation can be implied by +a normal read or write on the new file descriptor, and rejection can be +implied by closing the new socket. +Currently, only DECnet has these semantics on Linux. +.\" +.SS The socklen_t type +In the original BSD sockets implementation (and on other older systems) +.\" such as Linux libc4 and libc5, SunOS 4, SGI +the third argument of +.BR accept () +was declared as an \fIint\ *\fP. +A POSIX.1g draft +standard wanted to change it into a \fIsize_t\ *\fPC; +.\" SunOS 5 has 'size_t *' +later POSIX standards and glibc 2.x have +.IR "socklen_t\ * ". +.SH EXAMPLE +See +.BR bind (2). +.SH SEE ALSO +.BR bind (2), +.BR connect (2), +.BR listen (2), +.BR select (2), +.BR socket (2), +.BR socket (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/accept4.2 b/man2/accept4.2 new file mode 100644 index 0000000..963dfb5 --- /dev/null +++ b/man2/accept4.2 @@ -0,0 +1 @@ +.so man2/accept.2 diff --git a/man2/access.2 b/man2/access.2 new file mode 100644 index 0000000..2d194b5 --- /dev/null +++ b/man2/access.2 @@ -0,0 +1,423 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2004, 2006, 2007, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): +.\" Removed note about old kernel (pre-1.1.44) using wrong id on path. +.\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de): +.\" Stated more clearly how it behaves with symbolic links. +.\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426 +.\" Modified 1996-09-07 by Michael Haardt: +.\" Restrictions for NFS +.\" Modified 1997-09-09 by Joseph S. Myers +.\" Modified 1998-01-13 by Michael Haardt: +.\" Using access is often insecure +.\" Modified 2001-10-16 by aeb +.\" Modified 2002-04-23 by Roger Luethi +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2007-06-10, mtk, various parts rewritten, and added BUGS section. +.\" +.TH ACCESS 2 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +access, faccessat \- check user's permissions for a file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int access(const char *" pathname ", int " mode ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int faccessat(int " dirfd ", const char *" pathname ", int " \ +mode ", int " flags ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR faccessat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +.BR access () +checks whether the calling process can access the file +.IR pathname . +If +.I pathname +is a symbolic link, it is dereferenced. +.PP +The +.I mode +specifies the accessibility check(s) to be performed, +and is either the value +.BR F_OK , +.\" F_OK is defined as 0 on every system that I know of. +or a mask consisting of the bitwise OR of one or more of +.BR R_OK ", " W_OK ", and " X_OK . +.B F_OK +tests for the existence of the file. +.BR R_OK ", " W_OK ", and " X_OK +test whether the file exists and grants read, write, and +execute permissions, respectively. +.PP +The check is done using the calling process's +.I real +UID and GID, rather than the effective IDs as is done when +actually attempting an operation (e.g., +.BR open (2)) +on the file. +Similarly, for the root user, the check uses the set of +permitted capabilities rather than the set of effective +capabilities; and for non-root users, the check uses an empty set +of capabilities. +.PP +This allows set-user-ID programs and capability-endowed programs +to easily determine the invoking user's authority. +In other words, +.BR access () +does not answer the "can I read/write/execute this file?" question. +It answers a slightly different question: +"(assuming I'm a setuid binary) can +.I the user who invoked me +read/write/execute this file?", +which gives set-user-ID programs the possibility to +prevent malicious users from causing them to read files +which users shouldn't be able to read. +.PP +If the calling process is privileged (i.e., its real UID is zero), +then an +.B X_OK +check is successful for a regular file if execute permission +is enabled for any of the file owner, group, or other. +.SS faccessat() +The +.BR faccessat () +system call operates in exactly the same way as +.BR access (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR access () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR access ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +.I flags +is constructed by ORing together zero or more of the following values: +.TP +.B AT_EACCESS +Perform access checks using the effective user and group IDs. +By default, +.BR faccessat () +uses the real IDs (like +.BR access ()). +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead return information about the link itself. +.PP +See +.BR openat (2) +for an explanation of the need for +.BR faccessat (). +.SH RETURN VALUE +On success (all requested permissions granted, or +.I mode +is +.B F_OK +and the file exists), zero is returned. +On error (at least one bit in +.I mode +asked for a permission that is denied, or +.I mode +is +.B F_OK +and the file does not exist, or some other error occurred), +\-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.BR access () +and +.BR faccessat () +shall fail if: +.TP +.B EACCES +The requested access would be denied to the file, or search permission +is denied for one of the directories in the path prefix of +.IR pathname . +(See also +.BR path_resolution (7).) +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A component of +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EROFS +Write permission was requested for a file on a read-only filesystem. +.PP +.BR access () +and +.BR faccessat () +may fail if: +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EINVAL +.I mode +was incorrectly specified. +.TP +.B EIO +An I/O error occurred. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ETXTBSY +Write access was requested to an executable which is being +executed. +.PP +The following additional errors can occur for +.BR faccessat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR faccessat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR access (): +SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. +.PP +.BR faccessat (): +POSIX.1-2008. +.SH NOTES +.PP +.BR Warning : +Using these calls to check if a user is authorized to, for example, +open a file before actually doing so using +.BR open (2) +creates a security hole, because the user might exploit the short time +interval between checking and opening the file to manipulate it. +.BR "For this reason, the use of this system call should be avoided" . +(In the example just described, +a safer alternative would be to temporarily switch the process's +effective user ID to the real ID and then call +.BR open (2).) +.PP +.BR access () +always dereferences symbolic links. +If you need to check the permissions on a symbolic link, use +.BR faccessat () +with the flag +.BR AT_SYMLINK_NOFOLLOW . +.PP +These calls return an error if any of the access types in +.I mode +is denied, even if some of the other access types in +.I mode +are permitted. +.PP +If the calling process has appropriate privileges (i.e., is superuser), +POSIX.1-2001 permits an implementation to indicate success for an +.B X_OK +check even if none of the execute file permission bits are set. +.\" HPU-UX 11 and Tru64 5.1 do this. +Linux does not do this. +.PP +A file is accessible only if the permissions on each of the +directories in the path prefix of +.I pathname +grant search (i.e., execute) access. +If any directory is inaccessible, then the +.BR access () +call fails, regardless of the permissions on the file itself. +.PP +Only access bits are checked, not the file type or contents. +Therefore, if a directory is found to be writable, +it probably means that files can be created in the directory, +and not that the directory can be written as a file. +Similarly, a DOS file may be found to be "executable," but the +.BR execve (2) +call will still fail. +.PP +These calls +may not work correctly on NFSv2 filesystems with UID mapping enabled, +because UID mapping is done on the server and hidden from the client, +which checks permissions. (NFS versions 3 and higher perform the check on +the server.) +Similar problems can occur to FUSE mounts. +.\" +.\" +.SS C library/kernel differences +The raw +.BR faccessat () +system call takes only the first three arguments. +The +.B AT_EACCESS +and +.B AT_SYMLINK_NOFOLLOW +flags are actually implemented within the glibc wrapper function for +.BR faccessat (). +If either of these flags is specified, then the wrapper function employs +.BR fstatat (2) +to determine access permissions. +.SS Glibc notes +On older kernels where +.BR faccessat () +is unavailable (and when the +.B AT_EACCESS +and +.B AT_SYMLINK_NOFOLLOW +flags are not specified), +the glibc wrapper function falls back to the use of +.BR access (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.IR /proc/self/fd +that corresponds to the +.IR dirfd +argument. +.SH BUGS +In kernel 2.4 (and earlier) there is some strangeness in the handling of +.B X_OK +tests for superuser. +If all categories of execute permission are disabled +for a nondirectory file, then the only +.BR access () +test that returns \-1 is when +.I mode +is specified as just +.BR X_OK ; +if +.B R_OK +or +.B W_OK +is also specified in +.IR mode , +then +.BR access () +returns 0 for such files. +.\" This behavior appears to have been an implementation accident. +Early 2.6 kernels (up to and including 2.6.3) +also behaved in the same way as kernel 2.4. +.PP +In kernels before 2.6.20, +these calls ignored the effect of the +.B MS_NOEXEC +flag if it was used to +.BR mount (2) +the underlying filesystem. +Since kernel 2.6.20, the +.B MS_NOEXEC +flag is honored. +.SH SEE ALSO +.BR chmod (2), +.BR chown (2), +.BR open (2), +.BR setgid (2), +.BR setuid (2), +.BR stat (2), +.BR euidaccess (3), +.BR credentials (7), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/acct.2 b/man2/acct.2 new file mode 100644 index 0000000..26b62ab --- /dev/null +++ b/man2/acct.2 @@ -0,0 +1,161 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-22 by Rik Faith +.\" Modified 1993-08-10 by Alan Cox +.\" Modified 1998-11-04 by Tigran Aivazian +.\" Modified 2004-05-27, 2004-06-17, 2004-06-23 by Michael Kerrisk +.\" +.TH ACCT 2 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +acct \- switch process accounting on or off +.SH SYNOPSIS +.ad l +.nf +.B #include +.PP +.BI "int acct(const char *" filename ); +.fi +.ad b +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR acct (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.fi +.SH DESCRIPTION +The +.BR acct () +system call enables or disables process accounting. +If called with the name of an existing file as its argument, +accounting is turned on, +and records for each terminating process are appended to +.I filename +as it terminates. +An argument of NULL causes accounting to be turned off. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write permission is denied for the specified file, +or search permission is denied for one of the directories +in the path prefix of +.I filename +(see also +.BR path_resolution (7)), +or +.I filename +is not a regular file. +.TP +.B EFAULT +.I filename +points outside your accessible address space. +.TP +.B EIO +Error writing to the file +.IR filename . +.TP +.B EISDIR +.I filename +is a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR filename . +.TP +.B ENAMETOOLONG +.I filename +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The specified file does not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOSYS +BSD process accounting has not been enabled when the operating system +kernel was compiled. +The kernel configuration parameter controlling this feature is +.BR CONFIG_BSD_PROCESS_ACCT . +.TP +.B ENOTDIR +A component used as a directory in +.I filename +is not in fact a directory. +.TP +.B EPERM +The calling process has insufficient privilege to enable process accounting. +On Linux, the +.B CAP_SYS_PACCT +capability is required. +.TP +.B EROFS +.I filename +refers to a file on a read-only filesystem. +.TP +.B EUSERS +There are no more free file structures or we ran out of memory. +.SH CONFORMING TO +SVr4, 4.3BSD (but not POSIX). +.\" SVr4 documents an EBUSY error condition, but no EISDIR or ENOSYS. +.\" Also AIX and HP-UX document EBUSY (attempt is made +.\" to enable accounting when it is already enabled), as does Solaris +.\" (attempt is made to enable accounting using the same file that is +.\" currently being used). +.SH NOTES +No accounting is produced for programs running when a system crash occurs. +In particular, nonterminating processes are never accounted for. +.PP +The structure of the records written to the accounting file is described in +.BR acct (5). +.SH SEE ALSO +.BR acct (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/add_key.2 b/man2/add_key.2 new file mode 100644 index 0000000..89b5af7 --- /dev/null +++ b/man2/add_key.2 @@ -0,0 +1,304 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH ADD_KEY 2 2017-09-15 Linux "Linux Key Management Calls" +.SH NAME +add_key \- add a key to the kernel's key management facility +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "key_serial_t add_key(const char *" type ", const char *" description , +.BI " const void *" payload ", size_t " plen , +.BI " key_serial_t " keyring ");" +.fi +.PP +No glibc wrapper is provided for this system call; see NOTES. +.SH DESCRIPTION +.BR add_key () +creates or updates a key of the given +.I type +and +.IR description , +instantiates it with the +.I payload +of length +.IR plen , +attaches it to the nominated +.IR keyring , +and returns the key's serial number. +.PP +The key may be rejected if the provided data is in the wrong format or +it is invalid in some other way. +.PP +If the destination +.I keyring +already contains a key that matches the specified +.IR type +and +.IR description , +then, if the key type supports it, +.\" FIXME The aforementioned phrases begs the question: +.\" which key types support this? +that key will be updated rather than a new key being created; +if not, a new key (with a different ID) will be created +and it will displace the link to the extant key from the keyring. +.\" FIXME Perhaps elaborate the implications here? Namely, the new +.\" key will have a new ID, and if the old key was a keyring that +.\" is consequently unlinked, then keys that it was anchoring +.\" will have their reference count decreased by one (and may +.\" consequently be garbage collected). Is this all correct? +.PP +The destination +.I keyring +serial number may be that of a valid keyring for which the caller has +.I write +permission. +Alternatively, it may be one of the following special keyring IDs: +.\" FIXME . Perhaps have a separate page describing special keyring IDs? +.TP +.B KEY_SPEC_THREAD_KEYRING +This specifies the caller's thread-specific keyring +.RB ( thread-keyring (7)). +.TP +.B KEY_SPEC_PROCESS_KEYRING +This specifies the caller's process-specific keyring +.RB ( process-keyring (7)). +.TP +.B KEY_SPEC_SESSION_KEYRING +This specifies the caller's session-specific keyring +.RB ( session-keyring (7)). +.TP +.B KEY_SPEC_USER_KEYRING +This specifies the caller's UID-specific keyring +.RB ( user-keyring (7)). +.TP +.B KEY_SPEC_USER_SESSION_KEYRING +This specifies the caller's UID-session keyring +.RB ( user-session-keyring (7)). +.SS Key types +The key +.I type +is a string that specifies the key's type. +Internally, the kernel defines a number of key types that are +available in the core key management code. +Among the types that are available for user-space use +and can be specified as the +.I type +argument to +.BR add_key () +are the following: +.TP +.I """keyring""" +Keyrings are special key types that may contain links to sequences of other +keys of any type. +If this interface is used to create a keyring, then +.I payload +should be NULL and +.I plen +should be zero. +.TP +.IR """user""" +This is a general purpose key type whose payload may be read and updated +by user-space applications. +The key is kept entirely within kernel memory. +The payload for keys of this type is a blob of arbitrary data +of up to 32,767 bytes. +.TP +.IR """logon""" " (since Linux 3.3)" +.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b +This key type is essentially the same as +.IR """user""" , +but it does not permit the key to read. +This is suitable for storing payloads +that you do not want to be readable from user space. +.PP +This key type vets the +.I description +to ensure that it is qualified by a "service" prefix, +by checking to ensure that the +.I description +contains a ':' that is preceded by other characters. +.TP +.IR """big_key""" " (since Linux 3.13)" +.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 +This key type is similar to +.IR """user""" , +but may hold a payload of up to 1\ MiB. +If the key payload is large enough, +then it may be stored encrypted in tmpfs +(which can be swapped out) rather than kernel memory. +.PP +For further details on these key types, see +.BR keyrings (7). +.SH RETURN VALUE +On success, +.BR add_key () +returns the serial number of the key it created or updated. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.TP +.B EACCES +The keyring wasn't available for modification by the user. +.TP +.B EDQUOT +The key quota for this user would be exceeded by creating this key or linking +it to the keyring. +.TP +.B EFAULT +One or more of +.IR type , +.IR description , +and +.I payload +points outside process's accessible address space. +.TP +.B EINVAL +The size of the string (including the terminating null byte) specified in +.I type +or +.I description +exceeded the limit (32 bytes and 4096 bytes respectively). +.TP +.B EINVAL +The payload data was invalid. +.TP +.B EINVAL +.IR type +was +.IR """logon""" +and the +.I description +was not qualified with a prefix string of the form +.IR """service:""" . +.TP +.B EKEYEXPIRED +The keyring has expired. +.TP +.B EKEYREVOKED +The keyring has been revoked. +.TP +.B ENOKEY +The keyring doesn't exist. +.TP +.B ENOMEM +Insufficient memory to create a key. +.TP +.B EPERM +The +.I type +started with a period (\(aq.\(aq). +Key types that begin with a period are reserved to the implementation. +.TP +.B EPERM +.I type +was +.I """keyring""" +and the +.I description +started with a period (\(aq.\(aq). +Keyrings with descriptions (names) +that begin with a period are reserved to the implementation. +.SH VERSIONS +This system call first appeared in Linux 2.6.10. +.SH CONFORMING TO +This system call is a nonstandard Linux extension. +.SH NOTES +No wrapper for this system call is provided in glibc. +A wrapper is provided in the +.IR libkeyutils +package. +When employing the wrapper in that library, link with +.IR \-lkeyutils . +.SH EXAMPLE +The program below creates a key with the type, description, and payload +specified in its command-line arguments, +and links that key into the session keyring. +The following shell session demonstrates the use of the program: +.PP +.in +4n +.EX +$ \fB./a.out user mykey "Some payload"\fP +Key ID is 64a4dca +$ \fBgrep \(aq64a4dca\(aq /proc/keys\fP +064a4dca I--Q--- 1 perm 3f010000 1000 1000 user mykey: 12 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + key_serial_t key; + + if (argc != 4) { + fprintf(stderr, "Usage: %s type description payload\\n", + argv[0]); + exit(EXIT_FAILURE); + } + + key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]), + KEY_SPEC_SESSION_KEYRING); + if (key == \-1) { + perror("add_key"); + exit(EXIT_FAILURE); + } + + printf("Key ID is %lx\\n", (long) key); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7) +.PP +The kernel source files +.IR Documentation/security/keys/core.rst +and +.IR Documentation/keys/request\-key.rst +(or, before Linux 4.13, in the files +.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 +.IR Documentation/security/keys.txt +and +.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b +.IR Documentation/security/keys\-request\-key.txt ). +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 new file mode 100644 index 0000000..61e1da2 --- /dev/null +++ b/man2/adjtimex.2 @@ -0,0 +1,556 @@ +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" and Copyright (C) 2014, 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1997-07-30 by Paul Slootman +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH ADJTIMEX 2 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +adjtimex, ntp_adjtime \- tune kernel clock +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int adjtimex(struct timex *" "buf" ); +.PP +.BI "int ntp_adjtime(struct timex *" buf ); +.fi +.SH DESCRIPTION +Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 5905). +The system call +.BR adjtimex () +reads and optionally sets adjustment parameters for this algorithm. +It takes a pointer to a +.I timex +structure, updates kernel parameters from (selected) field values, +and returns the same structure updated with the current kernel values. +This structure is declared as follows: +.PP +.in +4n +.EX +struct timex { + int modes; /* Mode selector */ + long offset; /* Time offset; nanoseconds, if STA_NANO + status flag is set, otherwise + microseconds */ + long freq; /* Frequency offset; see NOTES for units */ + long maxerror; /* Maximum error (microseconds) */ + long esterror; /* Estimated error (microseconds) */ + int status; /* Clock command/status */ + long constant; /* PLL (phase-locked loop) time constant */ + long precision; /* Clock precision + (microseconds, read-only) */ + long tolerance; /* Clock frequency tolerance (read-only); + see NOTES for units */ + struct timeval time; + /* Current time (read-only, except for + ADJ_SETOFFSET); upon return, time.tv_usec + contains nanoseconds, if STA_NANO status + flag is set, otherwise microseconds */ + long tick; /* Microseconds between clock ticks */ + long ppsfreq; /* PPS (pulse per second) frequency + (read-only); see NOTES for units */ + long jitter; /* PPS jitter (read-only); nanoseconds, if + STA_NANO status flag is set, otherwise + microseconds */ + int shift; /* PPS interval duration + (seconds, read-only) */ + long stabil; /* PPS stability (read-only); + see NOTES for units */ + long jitcnt; /* PPS count of jitter limit exceeded + events (read-only) */ + long calcnt; /* PPS count of calibration intervals + (read-only) */ + long errcnt; /* PPS count of calibration errors + (read-only) */ + long stbcnt; /* PPS count of stability limit exceeded + events (read-only) */ + int tai; /* TAI offset, as set by previous ADJ_TAI + operation (seconds, read-only, + since Linux 2.6.26) */ + /* Further padding bytes to allow for future expansion */ +}; +.EE +.in +.PP +The +.I modes +field determines which parameters, if any, to set. +(As described later in this page, +the constants used for +.BR ntp_adjtime () +are equivalent but differently named.) +It is a bit mask containing a +.RI bitwise- or +combination of zero or more of the following bits: +.TP +.BR ADJ_OFFSET +Set time offset from +.IR buf.offset . +Since Linux 2.6.26, +.\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 +the supplied value is clamped to the range (\-0.5s, +0.5s). +In older kernels, an +.B EINVAL +error occurs if the supplied value is out of range. +.TP +.BR ADJ_FREQUENCY +Set frequency offset from +.IR buf.freq . +Since Linux 2.6.26, +.\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 +the supplied value is clamped to the range (\-32768000, +32768000). +In older kernels, an +.B EINVAL +error occurs if the supplied value is out of range. +.TP +.BR ADJ_MAXERROR +Set maximum time error from +.IR buf.maxerror . +.TP +.BR ADJ_ESTERROR +Set estimated time error from +.IR buf.esterror . +.TP +.BR ADJ_STATUS +Set clock status bits from +.IR buf.status . +A description of these bits is provided below. +.TP +.BR ADJ_TIMECONST +Set PLL time constant from +.IR buf.constant . +If the +.B STA_NANO +status flag (see below) is clear, the kernel adds 4 to this value. +.TP +.BR ADJ_SETOFFSET " (since Linux 2.6.39)" +.\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762 +.\" Author: Richard Cochran +Add +.I buf.time +to the current time. +If +.I buf.status +includes the +.B ADJ_NANO +flag, then +.I buf.time.tv_usec +is interpreted as a nanosecond value; +otherwise it is interpreted as microseconds. +.TP +.BR ADJ_MICRO " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Select microsecond resolution. +.TP +.BR ADJ_NANO " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Select nanosecond resolution. +Only one of +.BR ADJ_MICRO +and +.BR ADJ_NANO +should be specified. +.TP +.BR ADJ_TAI " (since Linux 2.6.26)" +.\" commit 153b5d054ac2d98ea0d86504884326b6777f683d +Set TAI (Atomic International Time) offset from +.IR buf.constant . +.IP +.BR ADJ_TAI +should not be used in conjunction with +.BR ADJ_TIMECONST , +since the latter mode also employs the +.IR buf.constant +field. +.IP +For a complete explanation of TAI +and the difference between TAI and UTC, see +.UR http://www.bipm.org/en/bipm/tai/tai.html +.I BIPM +.UE +.TP +.BR ADJ_TICK +Set tick value from +.IR buf.tick . +.PP +Alternatively, +.I modes +can be specified as either of the following (multibit mask) values, +in which case other bits should not be specified in +.IR modes : +.\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001 +.\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!! +.TP +.BR ADJ_OFFSET_SINGLESHOT +.\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001 +.\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000) +Old-fashioned +.BR adjtime (): +(gradually) adjust time by value specified in +.IR buf.offset , +which specifies an adjustment in microseconds. +.TP +.BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)" +.\" In user space, ADJ_OFFSET_SS_READ is 0xa001 +.\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with +.\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001) +Return (in +.IR buf.offset ) +the remaining amount of time to be adjusted after an earlier +.BR ADJ_OFFSET_SINGLESHOT +operation. +This feature was added in Linux 2.6.24, +.\" commit 52bfb36050c8529d9031d2c2513b281a360922ec +but did not work correctly +.\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1 +until Linux 2.6.28. +.PP +Ordinary users are restricted to a value of either 0 or +.B ADJ_OFFSET_SS_READ +for +.IR modes . +Only the superuser may set any parameters. +.PP +The +.I buf.status +field is a bit mask that is used to set and/or retrieve status +bits associated with the NTP implementation. +Some bits in the mask are both readable and settable, +while others are read-only. +.TP +.BR STA_PLL " (read-write)" +Enable phase-locked loop (PLL) updates via +.BR ADJ_OFFSET . +.TP +.BR STA_PPSFREQ " (read-write)" +Enable PPS (pulse-per-second) frequency discipline. +.TP +.BR STA_PPSTIME " (read-write)" +Enable PPS time discipline. +.TP +.BR STA_FLL " (read-write)" +Select frequency-locked loop (FLL) mode. +.TP +.BR STA_INS " (read-write)" +Insert a leap second after the last second of the UTC day, +thus extending the last minute of the day by one second. +Leap-second insertion will occur each day, so long as this flag remains set. +.\" John Stultz; +.\" Usually this is written as extending the day by one second, +.\" which is represented as: +.\" 23:59:59 +.\" 23:59:60 +.\" 00:00:00 +.\" +.\" But since posix cannot represent 23:59:60, we repeat the last second: +.\" 23:59:59 + TIME_INS +.\" 23:59:59 + TIME_OOP +.\" 00:00:00 + TIME_WAIT +.\" +.TP +.BR STA_DEL " (read-write)" +Delete a leap second at the last second of the UTC day. +.\" John Stultz: +.\" Similarly the progression here is: +.\" 23:59:57 + TIME_DEL +.\" 23:59:58 + TIME_DEL +.\" 00:00:00 + TIME_WAIT +Leap second deletion will occur each day, so long as this flag +remains set. +.\" FIXME Does there need to be a statement that it is nonsensical to set +.\" to set both STA_INS and STA_DEL? +.TP +.BR STA_UNSYNC " (read-write)" +Clock unsynchronized. +.TP +.BR STA_FREQHOLD " (read-write)" +Hold frequency. +.\" Following text from John Stultz: +Normally adjustments made via +.B ADJ_OFFSET +result in dampened frequency adjustments also being made. +So a single call corrects the current offset, +but as offsets in the same direction are made repeatedly, +the small frequency adjustments will accumulate to fix the long-term skew. +.IP +This flag prevents the small frequency adjustment from being made +when correcting for an +.B ADJ_OFFSET +value. +.\" According to the Kernel Application Program Interface document, +.\" STA_FREQHOLD is not used by the NTP version 4 daemon +.TP +.BR STA_PPSSIGNAL " (read-only)" +A valid PPS (pulse-per-second) signal is present. +.TP +.BR STA_PPSJITTER " (read-only)" +PPS signal jitter exceeded. +.TP +.BR STA_PPSWANDER " (read-only)" +PPS signal wander exceeded. +.TP +.BR STA_PPSERROR " (read-only)" +PPS signal calibration error. +.TP +.BR STA_CLOCKERR " (read-only)" +Clock hardware fault. +.\" Not set in current kernel (4.5), but checked in a few places +.TP +.BR STA_NANO " (read-only; since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Resolution (0 = microsecond, 1 = nanoseconds). +Set via +.BR ADJ_NANO , +cleared via +.BR ADJ_MICRO . +.TP +.BR STA_MODE " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop). +.TP +.BR STA_CLK " (read-only; since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Clock source (0 = A, 1 = B); currently unused. +.PP +Attempts to set read-only +.I status +bits are silently ignored. +.\" +.SS ntp_adjtime () +The +.BR ntp_adjtime () +library function +(described in the NTP "Kernel Application Program API", KAPI) +is a more portable interface for performing the same task as +.BR adjtimex (). +Other than the following points, it is identical to +.BR adjtime (): +.IP * 3 +The constants used in +.I modes +are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus, +.BR MOD_OFFSET , +.BR MOD_FREQUENCY , +and so on), other than the exceptions noted in the following points. +.IP * +.BR MOD_CLKA +is the synonym for +.BR ADJ_OFFSET_SINGLESHOT . +.IP * +.BR MOD_CLKB +is the synonym for +.BR ADJ_TICK . +.IP * +The is no synonym for +.BR ADJ_OFFSET_SS_READ , +which is not described in the KAPI. +.SH RETURN VALUE +On success, +.BR adjtimex () +and +.BR ntp_adjtime () +return the clock state; that is, one of the following values: +.TP 12 +.BR TIME_OK +Clock synchronized, no leap second adjustment pending. +.TP +.BR TIME_INS +Indicates that a leap second will be added at the end of the UTC day. +.TP +.BR TIME_DEL +Indicates that a leap second will be deleted at the end of the UTC day. +.TP +.BR TIME_OOP +Insertion of a leap second is in progress. +.TP +.BR TIME_WAIT +A leap-second insertion or deletion has been completed. +This value will be returned until the next +.BR ADJ_STATUS +operation clears the +.B STA_INS +and +.B STA_DEL +flags. +.TP +.BR TIME_ERROR +The system clock is not synchronized to a reliable server. +This value is returned when any of the following holds true: +.RS +.IP * 3 +Either +.B STA_UNSYNC +or +.B STA_CLOCKERR +is set. +.IP * +.B STA_PPSSIGNAL +is clear and either +.B STA_PPSFREQ +or +.B STA_PPSTIME +is set. +.IP * +.B STA_PPSTIME +and +.B STA_PPSJITTER +are both set. +.IP * +.B STA_PPSFREQ +is set and either +.B STA_PPSWANDER +or +.B STA_PPSJITTER +is set. +.RE +.IP +The symbolic name +.B TIME_BAD +is a synonym for +.BR TIME_ERROR , +provided for backward compatibility. +.PP +Note that starting with Linux 3.4, +.\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous +.\" operation, so we can no longer rely on the return code. +the call operates asynchronously and the return value usually will +not reflect a state change caused by the call itself. +.PP +On failure, these calls return \-1 and set +.IR errno . +.SH ERRORS +.TP +.B EFAULT +.I buf +does not point to writable memory. +.TP +.BR EINVAL " (kernels before Linux 2.6.26)" +An attempt was made to set +.I buf.freq +to a value outside the range (\-33554432, +33554432). +.\" From a quick glance, it appears there was no clamping or range check +.\" for buf.freq in kernels before 2.0 +.TP +.BR EINVAL " (kernels before Linux 2.6.26)" +An attempt was made to set +.I buf.offset +to a value outside the permitted range. +In kernels before Linux 2.0, the permitted range was (\-131072, +131072). +From Linux 2.0 onwards, the permitted range was (\-512000, +512000). +.TP +.B EINVAL +An attempt was made to set +.I buf.status +to a value other than those listed above. +.TP +.B EINVAL +An attempt was made to set +.I buf.tick +to a value outside the range +.RB 900000/ HZ +to +.RB 1100000/ HZ , +where +.B HZ +is the system timer interrupt frequency. +.TP +.B EPERM +.I buf.modes +is neither 0 nor +.BR ADJ_OFFSET_SS_READ , +and the caller does not have sufficient privilege. +Under Linux, the +.B CAP_SYS_TIME +capability is required. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ntp_adjtime () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +Neither of these interfaces is described in POSIX.1 +.PP +.BR adjtimex () +is Linux-specific and should not be used in programs +intended to be portable. +.PP +The preferred API for the NTP daemon is +.BR ntp_adjtime (). +.SH NOTES +In struct +.IR timex , +.IR freq , +.IR ppsfreq , +and +.I stabil +are ppm (parts per million) with a 16-bit fractional part, +which means that a value of 1 in one of those fields +actually means 2^-16 ppm, and 2^16=65536 is 1 ppm. +This is the case for both input values (in the case of +.IR freq ) +and output values. +.PP +The leap-second processing triggered by +.B STA_INS +and +.B STA_DEL +is done by the kernel in timer context +Thus, it will take one tick into the second +for the leap second to be inserted or deleted. +.SH SEE ALSO +.BR settimeofday (2), +.BR adjtime (3), +.BR ntp_gettime (3), +.BR capabilities (7), +.BR time (7), +.BR adjtimex (8), +.BR hwclock (8) +.PP +.ad l +.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm +NTP "Kernel Application Program Interface" +.UE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/afs_syscall.2 b/man2/afs_syscall.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/afs_syscall.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/alarm.2 b/man2/alarm.2 new file mode 100644 index 0000000..43d7664 --- /dev/null +++ b/man2/alarm.2 @@ -0,0 +1,105 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 21 19:42:57 1993 by Rik Faith +.\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer +.\" Modified Wed Nov 6 03:46:05 1996 by Eric S. Raymond +.\" +.TH ALARM 2 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +alarm \- set an alarm clock for delivery of a signal +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "unsigned int alarm(unsigned int " seconds ); +.fi +.SH DESCRIPTION +.BR alarm () +arranges for a +.B SIGALRM +signal to be delivered to the calling process in +.I seconds +seconds. +.PP +If +.I seconds +is zero, any pending alarm is canceled. +.PP +In any event any previously set +.BR alarm () +is canceled. +.SH RETURN VALUE +.BR alarm () +returns the number of seconds remaining until any previously scheduled +alarm was due to be delivered, or zero if there was no previously +scheduled alarm. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +.BR alarm () +and +.BR setitimer (2) +share the same timer; calls to one will interfere with use of the +other. +.PP +Alarms created by +.BR alarm () +are preserved across +.BR execve (2) +and are not inherited by children created via +.BR fork (2). +.PP +.BR sleep (3) +may be implemented using +.BR SIGALRM ; +mixing calls to +.BR alarm () +and +.BR sleep (3) +is a bad idea. +.PP +Scheduling delays can, as ever, cause the execution of the process to +be delayed by an arbitrary amount of time. +.SH SEE ALSO +.BR gettimeofday (2), +.BR pause (2), +.BR select (2), +.BR setitimer (2), +.BR sigaction (2), +.BR signal (2), +.BR timer_create (2), +.BR timerfd_create (2), +.BR sleep (3), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 new file mode 100644 index 0000000..d8c727b --- /dev/null +++ b/man2/alloc_hugepages.2 @@ -0,0 +1,159 @@ +.\" Copyright 2003 Andries E. Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ALLOC_HUGEPAGES 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +alloc_hugepages, free_hugepages \- allocate or free huge pages +.SH SYNOPSIS +.nf +.BI "void *alloc_hugepages(int " key ", void *" addr ", size_t " len , +.BI " int " prot ", int " flag ); +.\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr, +.\" unsigned long len, int prot, int flag); +.PP +.BI "int free_hugepages(void *" addr ); +.\" asmlinkage int sys_free_hugepages(unsigned long addr); +.fi +.SH DESCRIPTION +The system calls +.BR alloc_hugepages () +and +.BR free_hugepages () +were introduced in Linux 2.5.36 and removed again in 2.5.54. +They existed only on i386 and ia64 (when built with +.BR CONFIG_HUGETLB_PAGE ). +In Linux 2.4.20, the syscall numbers exist, +but the calls fail with the error +.BR ENOSYS . +.PP +On i386 the memory management hardware knows about ordinary pages (4\ KiB) +and huge pages (2 or 4\ MiB). +Similarly ia64 knows about huge pages of +several sizes. +These system calls serve to map huge pages into the +process's memory or to free them again. +Huge pages are locked into memory, and are not swapped. +.PP +The +.I key +argument is an identifier. +When zero the pages are private, and +not inherited by children. +When positive the pages are shared with other applications using the same +.IR key , +and inherited by child processes. +.PP +The +.I addr +argument of +.BR free_hugepages () +tells which page is being freed: it was the return value of a +call to +.BR alloc_hugepages (). +(The memory is first actually freed when all users have released it.) +The +.I addr +argument of +.BR alloc_hugepages () +is a hint, that the kernel may or may not follow. +Addresses must be properly aligned. +.PP +The +.I len +argument is the length of the required segment. +It must be a multiple of the huge page size. +.PP +The +.I prot +argument specifies the memory protection of the segment. +It is one of +.BR PROT_READ , +.BR PROT_WRITE , +.BR PROT_EXEC . +.PP +The +.I flag +argument is ignored, unless +.I key +is positive. +In that case, if +.I flag +is +.BR IPC_CREAT , +then a new huge page segment is created when none +with the given key existed. +If this flag is not set, then +.B ENOENT +is returned when no segment with the given key exists. +.SH RETURN VALUE +On success, +.BR alloc_hugepages () +returns the allocated virtual address, and +.BR free_hugepages () +returns zero. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B ENOSYS +The system call is not supported on this kernel. +.SH FILES +.TP +.I /proc/sys/vm/nr_hugepages +Number of configured hugetlb pages. +This can be read and written. +.TP +.I /proc/meminfo +Gives info on the number of configured hugetlb pages and on their size +in the three variables HugePages_Total, HugePages_Free, Hugepagesize. +.SH CONFORMING TO +These calls are specific to Linux on Intel processors, and should not be +used in programs intended to be portable. +.SH NOTES +These system calls are gone; +they existed only in Linux 2.5.36 through to 2.5.54. +Now the hugetlbfs filesystem can be used instead. +Memory backed by huge pages (if the CPU supports them) is obtained by +using +.BR mmap (2) +to map files in this virtual filesystem. +.PP +The maximal number of huge pages can be specified using the +.B hugepages= +boot parameter. +.PP +.\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features") +.\" and CONFIG_HUGETLBFS (under "Filesystems"). +.\" mount -t hugetlbfs hugetlbfs /huge +.\" SHM_HUGETLB +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2 new file mode 100644 index 0000000..f37b182 --- /dev/null +++ b/man2/arch_prctl.2 @@ -0,0 +1,158 @@ +.\" Copyright (C) 2003 Andi Kleen +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ARCH_PRCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +arch_prctl \- set architecture-specific thread state +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int arch_prctl(int " code ", unsigned long " addr ); +.BI "int arch_prctl(int " code ", unsigned long *" addr ); +.fi +.SH DESCRIPTION +.BR arch_prctl () +sets architecture-specific process or thread state. +.I code +selects a subfunction +and passes argument +.I addr +to it; +.I addr +is interpreted as either an +.I "unsigned long" +for the "set" operations, or as an +.IR "unsigned long\ *" , +for the "get" operations. +.PP +Subfunctions for x86-64 are: +.TP +.B ARCH_SET_FS +Set the 64-bit base for the +.I FS +register to +.IR addr . +.TP +.B ARCH_GET_FS +Return the 64-bit base value for the +.I FS +register of the current thread in the +.I unsigned long +pointed to by +.IR addr . +.TP +.B ARCH_SET_GS +Set the 64-bit base for the +.I GS +register to +.IR addr . +.TP +.B ARCH_GET_GS +Return the 64-bit base value for the +.I GS +register of the current thread in the +.I unsigned long +pointed to by +.IR addr . +.SH RETURN VALUE +On success, +.BR arch_prctl () +returns 0; on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I addr +points to an unmapped address or is outside the process address space. +.TP +.B EINVAL +.I code +is not a valid subcommand. +.TP +.B EPERM +.I addr +is outside the process address space. +.\" .SH AUTHOR +.\" Man page written by Andi Kleen. +.SH CONFORMING TO +.BR arch_prctl () +is a Linux/x86-64 extension and should not be used in programs intended +to be portable. +.SH NOTES +.BR arch_prctl () +is supported only on Linux/x86-64 for 64-bit programs currently. +.PP +The 64-bit base changes when a new 32-bit segment selector is loaded. +.PP +.B ARCH_SET_GS +is disabled in some kernels. +.PP +Context switches for 64-bit segment bases are rather expensive. +As an optimization, if a 32-bit TLS base address is used, +.BR arch_prctl () +may use a real TLS entry as if +.BR set_thread_area (2) +had been called, instead of manipulating the segment base register directly. +Memory in the first 2\ GB of address space can be allocated by using +.BR mmap (2) +with the +.B MAP_32BIT +flag. +.PP +Because of the aforementioned optimization, using +.BR arch_prctl () +and +.BR set_thread_area (2) +in the same thread is dangerous, as they may overwrite each other's +TLS entries. +.PP +As of version 2.7, glibc provides no prototype for +.BR arch_prctl (). +You have to declare it yourself for now. +This may be fixed in future glibc versions. +.PP +.I FS +may be already used by the threading library. +Programs that use +.B ARCH_SET_FS +directly are very likely to crash. +.SH SEE ALSO +.BR mmap (2), +.BR modify_ldt (2), +.BR prctl (2), +.BR set_thread_area (2) +.PP +AMD X86-64 Programmer's manual +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/arm_fadvise.2 b/man2/arm_fadvise.2 new file mode 100644 index 0000000..53f54a1 --- /dev/null +++ b/man2/arm_fadvise.2 @@ -0,0 +1 @@ +.so man2/posix_fadvise.2 diff --git a/man2/arm_fadvise64_64.2 b/man2/arm_fadvise64_64.2 new file mode 100644 index 0000000..53f54a1 --- /dev/null +++ b/man2/arm_fadvise64_64.2 @@ -0,0 +1 @@ +.so man2/posix_fadvise.2 diff --git a/man2/arm_sync_file_range.2 b/man2/arm_sync_file_range.2 new file mode 100644 index 0000000..ad7a1e6 --- /dev/null +++ b/man2/arm_sync_file_range.2 @@ -0,0 +1 @@ +.so man2/sync_file_range.2 diff --git a/man2/bdflush.2 b/man2/bdflush.2 new file mode 100644 index 0000000..ac0df3e --- /dev/null +++ b/man2/bdflush.2 @@ -0,0 +1,133 @@ +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH BDFLUSH 2 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +bdflush \- start, flush, or tune buffer-dirty-flush daemon +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int bdflush(int " func ", long *" address ); +.BI "int bdflush(int " func ", long " data ); +.fi +.SH DESCRIPTION +.IR Note : +Since Linux 2.6, +.\" As noted in a changes in the 2.5.12 source +this system call is deprecated and does nothing. +It is likely to disappear altogether in a future kernel release. +Nowadays, the task performed by +.BR bdflush () +is handled by the kernel +.I pdflush +thread. +.PP +.BR bdflush () +starts, flushes, or tunes the buffer-dirty-flush daemon. +Only a privileged process (one with the +.B CAP_SYS_ADMIN +capability) may call +.BR bdflush (). +.PP +If +.I func +is negative or 0, and no daemon has been started, then +.BR bdflush () +enters the daemon code and never returns. +.PP +If +.I func +is 1, +some dirty buffers are written to disk. +.PP +If +.I func +is 2 or more and is even (low bit is 0), then +.I address +is the address of a long word, +and the tuning parameter numbered +.RI "(" "func" "\-2)/2" +is returned to the caller in that address. +.PP +If +.I func +is 3 or more and is odd (low bit is 1), then +.I data +is a long word, +and the kernel sets tuning parameter numbered +.RI "(" "func" "\-3)/2" +to that value. +.PP +The set of parameters, their values, and their valid ranges +are defined in the Linux kernel source file +.IR fs/buffer.c . +.SH RETURN VALUE +If +.I func +is negative or 0 and the daemon successfully starts, +.BR bdflush () +never returns. +Otherwise, the return value is 0 on success and \-1 on failure, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBUSY +An attempt was made to enter the daemon code after +another process has already entered. +.TP +.B EFAULT +.I address +points outside your accessible address space. +.TP +.B EINVAL +An attempt was made to read or write an invalid parameter number, +or to write an invalid value to a parameter. +.TP +.B EPERM +Caller does not have the +.B CAP_SYS_ADMIN +capability. +.SH VERSIONS +Since version 2.23, glibc no longer supports this obsolete system call. +.SH CONFORMING TO +.BR bdflush () +is Linux-specific and should not be used in programs +intended to be portable. +.SH SEE ALSO +.BR sync (1), +.BR fsync (2), +.BR sync (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/bind.2 b/man2/bind.2 new file mode 100644 index 0000000..d426e2c --- /dev/null +++ b/man2/bind.2 @@ -0,0 +1,344 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/sys/socket.h, which does not have +.\" any authorship information in it. It is probably available under the GPL. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: +.\" +.\" Copyright (c) 1983 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" $Id: bind.2,v 1.3 1999/04/23 19:56:07 freitag Exp $ +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH BIND 2 2016-12-12 "Linux" "Linux Programmer's Manual" +.SH NAME +bind \- bind a name to a socket +.SH SYNOPSIS +.nf +.BR "#include " " /* See NOTES */" +.B #include +.PP +.BI "int bind(int " sockfd ", const struct sockaddr *" addr , +.BI " socklen_t " addrlen ); +.fi +.SH DESCRIPTION +When a socket is created with +.BR socket (2), +it exists in a name space (address family) but has no address assigned to it. +.BR bind () +assigns the address specified by +.I addr +to the socket referred to by the file descriptor +.IR sockfd . +.I addrlen +specifies the size, in bytes, of the address structure pointed to by +.IR addr . +Traditionally, this operation is called \(lqassigning a name to a socket\(rq. +.PP +It is normally necessary to assign a local address using +.BR bind () +before a +.B SOCK_STREAM +socket may receive connections (see +.BR accept (2)). +.PP +The rules used in name binding vary between address families. +Consult the manual entries in Section 7 for detailed information. +For +.BR AF_INET , +see +.BR ip (7); +for +.BR AF_INET6 , +see +.BR ipv6 (7); +for +.BR AF_UNIX , +see +.BR unix (7); +for +.BR AF_APPLETALK , +see +.BR ddp (7); +for +.BR AF_PACKET , +see +.BR packet (7); +for +.BR AF_X25 , +see +.BR x25 (7); +and for +.BR AF_NETLINK , +see +.BR netlink (7). +.PP +The actual structure passed for the +.I addr +argument will depend on the address family. +The +.I sockaddr +structure is defined as something like: +.PP +.in +4n +.EX +struct sockaddr { + sa_family_t sa_family; + char sa_data[14]; +} +.EE +.in +.PP +The only purpose of this structure is to cast the structure +pointer passed in +.I addr +in order to avoid compiler warnings. +See EXAMPLE below. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +.\" e.g., privileged port in AF_INET domain +The address is protected, and the user is not the superuser. +.TP +.B EADDRINUSE +The given address is already in use. +.TP +.B EADDRINUSE +(Internet domain sockets) +The port number was specified as zero in the socket address structure, +but, upon attempting to bind to an ephemeral port, +it was determined that all port numbers in the ephemeral port range +are currently in use. +See the discussion of +.I /proc/sys/net/ipv4/ip_local_port_range +.BR ip (7). +.TP +.B EBADF +.I sockfd +is not a valid file descriptor. +.TP +.B EINVAL +The socket is already bound to an address. +.\" This may change in the future: see +.\" .I linux/unix/sock.c for details. +.TP +.B EINVAL +.I addrlen +is wrong, or +.I addr +is not a valid address for this socket's domain. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.PP +The following errors are specific to UNIX domain +.RB ( AF_UNIX ) +sockets: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EADDRNOTAVAIL +A nonexistent interface was requested or the requested +address was not local. +.TP +.B EFAULT +.I addr +points outside the user's accessible address space. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR addr . +.TP +.B ENAMETOOLONG +.I addr +is too long. +.TP +.B ENOENT +A component in the directory prefix of the socket pathname does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EROFS +The socket inode would reside on a read-only filesystem. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD +.RB ( bind () +first appeared in 4.2BSD). +.\" SVr4 documents an additional +.\" .B ENOSR +.\" general error condition, and +.\" additional +.\" .B EIO +.\" and +.\" .B EISDIR +.\" UNIX-domain error conditions. +.SH NOTES +POSIX.1 does not require the inclusion of +.IR , +and this header file is not required on Linux. +However, some historical (BSD) implementations required this header +file, and portable applications are probably wise to include it. +.PP +For background on the +.I socklen_t +type, see +.BR accept (2). +.SH BUGS +The transparent proxy options are not described. +.\" FIXME Document transparent proxy options +.SH EXAMPLE +An example of the use of +.BR bind () +with Internet domain sockets can be found in +.BR getaddrinfo (3). +.PP +The following example shows how to bind a stream socket in the UNIX +.RB ( AF_UNIX ) +domain, and accept connections: +.\" listen.7 refers to this example. +.\" accept.7 refers to this example. +.\" unix.7 refers to this example. +.PP +.EX +#include +#include +#include +#include +#include + +#define MY_SOCK_PATH "/somepath" +#define LISTEN_BACKLOG 50 + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +int +main(int argc, char *argv[]) +{ + int sfd, cfd; + struct sockaddr_un my_addr, peer_addr; + socklen_t peer_addr_size; + + sfd = socket(AF_UNIX, SOCK_STREAM, 0); + if (sfd == \-1) + handle_error("socket"); + + memset(&my_addr, 0, sizeof(struct sockaddr_un)); + /* Clear structure */ + my_addr.sun_family = AF_UNIX; + strncpy(my_addr.sun_path, MY_SOCK_PATH, + sizeof(my_addr.sun_path) \- 1); + + if (bind(sfd, (struct sockaddr *) &my_addr, + sizeof(struct sockaddr_un)) == \-1) + handle_error("bind"); + + if (listen(sfd, LISTEN_BACKLOG) == \-1) + handle_error("listen"); + + /* Now we can accept incoming connections one + at a time using accept(2) */ + + peer_addr_size = sizeof(struct sockaddr_un); + cfd = accept(sfd, (struct sockaddr *) &peer_addr, + &peer_addr_size); + if (cfd == \-1) + handle_error("accept"); + + /* Code to deal with incoming connection(s)... */ + + /* When no longer required, the socket pathname, MY_SOCK_PATH + should be deleted using unlink(2) or remove(3) */ +} +.EE +.SH SEE ALSO +.BR accept (2), +.BR connect (2), +.BR getsockname (2), +.BR listen (2), +.BR socket (2), +.BR getaddrinfo (3), +.BR getifaddrs (3), +.BR ip (7), +.BR ipv6 (7), +.BR path_resolution (7), +.BR socket (7), +.BR unix (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/bpf.2 b/man2/bpf.2 new file mode 100644 index 0000000..2119ed1 --- /dev/null +++ b/man2/bpf.2 @@ -0,0 +1,1188 @@ +.\" Copyright (C) 2015 Alexei Starovoitov +.\" and Copyright (C) 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH BPF 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +bpf \- perform a command on an extended BPF map or program +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int bpf(int " cmd ", union bpf_attr *" attr ", unsigned int " size "); +.SH DESCRIPTION +The +.BR bpf () +system call performs a range of operations related to extended +Berkeley Packet Filters. +Extended BPF (or eBPF) is similar to +the original ("classic") BPF (cBPF) used to filter network packets. +For both cBPF and eBPF programs, +the kernel statically analyzes the programs before loading them, +in order to ensure that they cannot harm the running system. +.PP +eBPF extends cBPF in multiple ways, including the ability to call +a fixed set of in-kernel helper functions +.\" See 'enum bpf_func_id' in include/uapi/linux/bpf.h +(via the +.B BPF_CALL +opcode extension provided by eBPF) +and access shared data structures such as eBPF maps. +.\" +.SS Extended BPF Design/Architecture +eBPF maps are a generic data structure for storage of different data types. +Data types are generally treated as binary blobs, so a user just specifies +the size of the key and the size of the value at map-creation time. +In other words, a key/value for a given map can have an arbitrary structure. +.PP +A user process can create multiple maps (with key/value-pairs being +opaque bytes of data) and access them via file descriptors. +Different eBPF programs can access the same maps in parallel. +It's up to the user process and eBPF program to decide what they store +inside maps. +.PP +There's one special map type, called a program array. +This type of map stores file descriptors referring to other eBPF programs. +When a lookup in the map is performed, the program flow is +redirected in-place to the beginning of another eBPF program and does not +return back to the calling program. +The level of nesting has a fixed limit of 32, +.\" Defined by the kernel constant MAX_TAIL_CALL_CNT in include/linux/bpf.h +so that infinite loops cannot be crafted. +At runtime, the program file descriptors stored in the map can be modified, +so program functionality can be altered based on specific requirements. +All programs referred to in a program-array map must +have been previously loaded into the kernel via +.BR bpf (). +If a map lookup fails, the current program continues its execution. +See +.B BPF_MAP_TYPE_PROG_ARRAY +below for further details. +.PP +Generally, eBPF programs are loaded by the user process and automatically +unloaded when the process exits. +In some cases, for example, +.BR tc-bpf (8), +the program will continue to stay alive inside the kernel even after the +process that loaded the program exits. +In that case, +the tc subsystem holds a reference to the eBPF program after the +file descriptor has been closed by the user-space program. +Thus, whether a specific program continues to live inside the kernel +depends on how it is further attached to a given kernel subsystem +after it was loaded via +.BR bpf (). +.PP +Each eBPF program is a set of instructions that is safe to run until +its completion. +An in-kernel verifier statically determines that the eBPF program +terminates and is safe to execute. +During verification, the kernel increments reference counts for each of +the maps that the eBPF program uses, +so that the attached maps can't be removed until the program is unloaded. +.PP +eBPF programs can be attached to different events. +These events can be the arrival of network packets, tracing +events, classification events by network queueing disciplines +(for eBPF programs attached to a +.BR tc (8) +classifier), and other types that may be added in the future. +A new event triggers execution of the eBPF program, which +may store information about the event in eBPF maps. +Beyond storing data, eBPF programs may call a fixed set of +in-kernel helper functions. +.PP +The same eBPF program can be attached to multiple events and different +eBPF programs can access the same map: +.PP +.in +4n +.EX +tracing tracing tracing packet packet packet +event A event B event C on eth0 on eth1 on eth2 + | | | | | ^ + | | | | v | + --> tracing <-- tracing socket tc ingress tc egress + prog_1 prog_2 prog_3 classifier action + | | | | prog_4 prog_5 + |--- -----| |------| map_3 | | + map_1 map_2 --| map_4 |-- +.EE +.in +.\" +.SS Arguments +The operation to be performed by the +.BR bpf () +system call is determined by the +.IR cmd +argument. +Each operation takes an accompanying argument, +provided via +.IR attr , +which is a pointer to a union of type +.IR bpf_attr +(see below). +The +.I size +argument is the size of the union pointed to by +.IR attr . +.PP +The value provided in +.IR cmd +is one of the following: +.TP +.B BPF_MAP_CREATE +Create a map and return a file descriptor that refers to the map. +The close-on-exec file descriptor flag (see +.BR fcntl (2)) +is automatically enabled for the new file descriptor. +.TP +.B BPF_MAP_LOOKUP_ELEM +Look up an element by key in a specified map and return its value. +.TP +.B BPF_MAP_UPDATE_ELEM +Create or update an element (key/value pair) in a specified map. +.TP +.B BPF_MAP_DELETE_ELEM +Look up and delete an element by key in a specified map. +.TP +.B BPF_MAP_GET_NEXT_KEY +Look up an element by key in a specified map and return the key +of the next element. +.TP +.B BPF_PROG_LOAD +Verify and load an eBPF program, +returning a new file descriptor associated with the program. +The close-on-exec file descriptor flag (see +.BR fcntl (2)) +is automatically enabled for the new file descriptor. +.IP +The +.I bpf_attr +union consists of various anonymous structures that are used by different +.BR bpf () +commands: +.PP +.in +4n +.EX +union bpf_attr { + struct { /* Used by BPF_MAP_CREATE */ + __u32 map_type; + __u32 key_size; /* size of key in bytes */ + __u32 value_size; /* size of value in bytes */ + __u32 max_entries; /* maximum number of entries + in a map */ + }; + + struct { /* Used by BPF_MAP_*_ELEM and BPF_MAP_GET_NEXT_KEY + commands */ + __u32 map_fd; + __aligned_u64 key; + union { + __aligned_u64 value; + __aligned_u64 next_key; + }; + __u64 flags; + }; + + struct { /* Used by BPF_PROG_LOAD */ + __u32 prog_type; + __u32 insn_cnt; + __aligned_u64 insns; /* 'const struct bpf_insn *' */ + __aligned_u64 license; /* 'const char *' */ + __u32 log_level; /* verbosity level of verifier */ + __u32 log_size; /* size of user buffer */ + __aligned_u64 log_buf; /* user supplied 'char *' + buffer */ + __u32 kern_version; + /* checked when prog_type=kprobe + (since Linux 4.1) */ +.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 + }; +} __attribute__((aligned(8))); +.EE +.in +.\" +.SS eBPF maps +Maps are a generic data structure for storage of different types of data. +They allow sharing of data between eBPF kernel programs, +and also between kernel and user-space applications. +.PP +Each map type has the following attributes: +.IP * 3 +type +.IP * +maximum number of elements +.IP * +key size in bytes +.IP * +value size in bytes +.PP +The following wrapper functions demonstrate how various +.BR bpf () +commands can be used to access the maps. +The functions use the +.IR cmd +argument to invoke different operations. +.TP +.B BPF_MAP_CREATE +The +.B BPF_MAP_CREATE +command creates a new map, +returning a new file descriptor that refers to the map. +.IP +.in +4n +.EX +int +bpf_create_map(enum bpf_map_type map_type, + unsigned int key_size, + unsigned int value_size, + unsigned int max_entries) +{ + union bpf_attr attr = { + .map_type = map_type, + .key_size = key_size, + .value_size = value_size, + .max_entries = max_entries + }; + + return bpf(BPF_MAP_CREATE, &attr, sizeof(attr)); +} +.EE +.in +.IP +The new map has the type specified by +.IR map_type , +and attributes as specified in +.IR key_size , +.IR value_size , +and +.IR max_entries . +On success, this operation returns a file descriptor. +On error, \-1 is returned and +.I errno +is set to +.BR EINVAL , +.BR EPERM , +or +.BR ENOMEM . +.IP +The +.I key_size +and +.I value_size +attributes will be used by the verifier during program loading +to check that the program is calling +.BR bpf_map_*_elem () +helper functions with a correctly initialized +.I key +and to check that the program doesn't access the map element +.I value +beyond the specified +.IR value_size . +For example, when a map is created with a +.IR key_size +of 8 and the eBPF program calls +.IP +.in +4n +.EX +bpf_map_lookup_elem(map_fd, fp - 4) +.EE +.in +.IP +the program will be rejected, +since the in-kernel helper function +.IP +.EX + bpf_map_lookup_elem(map_fd, void *key) +.EE +.IP +expects to read 8 bytes from the location pointed to by +.IR key , +but the +.IR "fp\ -\ 4" +(where +.I fp +is the top of the stack) +starting address will cause out-of-bounds stack access. +.IP +Similarly, when a map is created with a +.I value_size +of 1 and the eBPF program contains +.IP +.in +4n +.EX +value = bpf_map_lookup_elem(...); +*(u32 *) value = 1; +.EE +.in +.IP +the program will be rejected, since it accesses the +.I value +pointer beyond the specified 1 byte +.I value_size +limit. +.IP +Currently, the following values are supported for +.IR map_type : +.IP +.in +4n +.EX +enum bpf_map_type { + BPF_MAP_TYPE_UNSPEC, /* Reserve 0 as invalid map type */ + BPF_MAP_TYPE_HASH, + BPF_MAP_TYPE_ARRAY, + BPF_MAP_TYPE_PROG_ARRAY, + BPF_MAP_TYPE_PERF_EVENT_ARRAY, + BPF_MAP_TYPE_PERCPU_HASH, + BPF_MAP_TYPE_PERCPU_ARRAY, + BPF_MAP_TYPE_STACK_TRACE, + BPF_MAP_TYPE_CGROUP_ARRAY, + BPF_MAP_TYPE_LRU_HASH, + BPF_MAP_TYPE_LRU_PERCPU_HASH, + BPF_MAP_TYPE_LPM_TRIE, + BPF_MAP_TYPE_ARRAY_OF_MAPS, + BPF_MAP_TYPE_HASH_OF_MAPS, + BPF_MAP_TYPE_DEVMAP, + BPF_MAP_TYPE_SOCKMAP, + BPF_MAP_TYPE_CPUMAP, +}; +.EE +.in +.IP +.I map_type +selects one of the available map implementations in the kernel. +.\" FIXME We need an explanation of why one might choose each of +.\" these map implementations +For all map types, +eBPF programs access maps with the same +.BR bpf_map_lookup_elem () +and +.BR bpf_map_update_elem () +helper functions. +Further details of the various map types are given below. +.TP +.B BPF_MAP_LOOKUP_ELEM +The +.B BPF_MAP_LOOKUP_ELEM +command looks up an element with a given +.I key +in the map referred to by the file descriptor +.IR fd . +.IP +.in +4n +.EX +int +bpf_lookup_elem(int fd, const void *key, void *value) +{ + union bpf_attr attr = { + .map_fd = fd, + .key = ptr_to_u64(key), + .value = ptr_to_u64(value), + }; + + return bpf(BPF_MAP_LOOKUP_ELEM, &attr, sizeof(attr)); +} +.EE +.in +.IP +If an element is found, +the operation returns zero and stores the element's value into +.IR value , +which must point to a buffer of +.I value_size +bytes. +.IP +If no element is found, the operation returns \-1 and sets +.I errno +to +.BR ENOENT . +.TP +.B BPF_MAP_UPDATE_ELEM +The +.B BPF_MAP_UPDATE_ELEM +command +creates or updates an element with a given +.I key/value +in the map referred to by the file descriptor +.IR fd . +.IP +.in +4n +.EX +int +bpf_update_elem(int fd, const void *key, const void *value, + uint64_t flags) +{ + union bpf_attr attr = { + .map_fd = fd, + .key = ptr_to_u64(key), + .value = ptr_to_u64(value), + .flags = flags, + }; + + return bpf(BPF_MAP_UPDATE_ELEM, &attr, sizeof(attr)); +} +.EE +.in +.IP +The +.I flags +argument should be specified as one of the following: +.RS +.TP +.B BPF_ANY +Create a new element or update an existing element. +.TP +.B BPF_NOEXIST +Create a new element only if it did not exist. +.TP +.B BPF_EXIST +Update an existing element. +.RE +.IP +On success, the operation returns zero. +On error, \-1 is returned and +.I errno +is set to +.BR EINVAL , +.BR EPERM , +.BR ENOMEM , +or +.BR E2BIG . +.B E2BIG +indicates that the number of elements in the map reached the +.I max_entries +limit specified at map creation time. +.B EEXIST +will be returned if +.I flags +specifies +.B BPF_NOEXIST +and the element with +.I key +already exists in the map. +.B ENOENT +will be returned if +.I flags +specifies +.B BPF_EXIST +and the element with +.I key +doesn't exist in the map. +.TP +.B BPF_MAP_DELETE_ELEM +The +.B BPF_MAP_DELETE_ELEM +command +deleted the element whose key is +.I key +from the map referred to by the file descriptor +.IR fd . +.IP +.in +4n +.EX +int +bpf_delete_elem(int fd, const void *key) +{ + union bpf_attr attr = { + .map_fd = fd, + .key = ptr_to_u64(key), + }; + + return bpf(BPF_MAP_DELETE_ELEM, &attr, sizeof(attr)); +} +.EE +.in +.IP +On success, zero is returned. +If the element is not found, \-1 is returned and +.I errno +is set to +.BR ENOENT . +.TP +.B BPF_MAP_GET_NEXT_KEY +The +.B BPF_MAP_GET_NEXT_KEY +command looks up an element by +.I key +in the map referred to by the file descriptor +.IR fd +and sets the +.I next_key +pointer to the key of the next element. +.IP +.in +4n +.EX +int +bpf_get_next_key(int fd, const void *key, void *next_key) +{ + union bpf_attr attr = { + .map_fd = fd, + .key = ptr_to_u64(key), + .next_key = ptr_to_u64(next_key), + }; + + return bpf(BPF_MAP_GET_NEXT_KEY, &attr, sizeof(attr)); +} +.EE +.in +.IP +If +.I key +is found, the operation returns zero and sets the +.I next_key +pointer to the key of the next element. +If +.I key +is not found, the operation returns zero and sets the +.I next_key +pointer to the key of the first element. +If +.I key +is the last element, \-1 is returned and +.I errno +is set to +.BR ENOENT . +Other possible +.I errno +values are +.BR ENOMEM , +.BR EFAULT , +.BR EPERM , +and +.BR EINVAL . +This method can be used to iterate over all elements in the map. +.TP +.B close(map_fd) +Delete the map referred to by the file descriptor +.IR map_fd . +When the user-space program that created a map exits, all maps will +be deleted automatically (but see NOTES). +.\" +.SS eBPF map types +The following map types are supported: +.TP +.B BPF_MAP_TYPE_HASH +.\" commit 0f8e4bd8a1fc8c4185f1630061d0a1f2d197a475 +Hash-table maps have the following characteristics: +.RS +.IP * 3 +Maps are created and destroyed by user-space programs. +Both user-space and eBPF programs +can perform lookup, update, and delete operations. +.IP * +The kernel takes care of allocating and freeing key/value pairs. +.IP * +The +.BR map_update_elem () +helper will fail to insert new element when the +.I max_entries +limit is reached. +(This ensures that eBPF programs cannot exhaust memory.) +.IP * +.BR map_update_elem () +replaces existing elements atomically. +.RE +.IP +Hash-table maps are +optimized for speed of lookup. +.TP +.B BPF_MAP_TYPE_ARRAY +.\" commit 28fbcfa08d8ed7c5a50d41a0433aad222835e8e3 +Array maps have the following characteristics: +.RS +.IP * 3 +Optimized for fastest possible lookup. +In the future the verifier/JIT compiler +may recognize lookup() operations that employ a constant key +and optimize it into constant pointer. +It is possible to optimize a non-constant +key into direct pointer arithmetic as well, since pointers and +.I value_size +are constant for the life of the eBPF program. +In other words, +.BR array_map_lookup_elem () +may be 'inlined' by the verifier/JIT compiler +while preserving concurrent access to this map from user space. +.IP * +All array elements pre-allocated and zero initialized at init time +.IP * +The key is an array index, and must be exactly four bytes. +.IP * +.BR map_delete_elem () +fails with the error +.BR EINVAL , +since elements cannot be deleted. +.IP * +.BR map_update_elem () +replaces elements in a +.B nonatomic +fashion; +for atomic updates, a hash-table map should be used instead. +There is however one special case that can also be used with arrays: +the atomic built-in +.BR __sync_fetch_and_add() +can be used on 32 and 64 bit atomic counters. +For example, it can be +applied on the whole value itself if it represents a single counter, +or in case of a structure containing multiple counters, it could be +used on individual counters. +This is quite often useful for aggregation and accounting of events. +.RE +.IP +Among the uses for array maps are the following: +.RS +.IP * 3 +As "global" eBPF variables: an array of 1 element whose key is (index) 0 +and where the value is a collection of 'global' variables which +eBPF programs can use to keep state between events. +.IP * +Aggregation of tracing events into a fixed set of buckets. +.IP * +Accounting of networking events, for example, number of packets and packet +sizes. +.RE +.TP +.BR BPF_MAP_TYPE_PROG_ARRAY " (since Linux 4.2)" +A program array map is a special kind of array map whose map values +contain only file descriptors referring to other eBPF programs. +Thus, both the +.I key_size +and +.I value_size +must be exactly four bytes. +This map is used in conjunction with the +.BR bpf_tail_call () +helper. +.IP +This means that an eBPF program with a program array map attached to it +can call from kernel side into +.IP +.in +4n +.EX +void bpf_tail_call(void *context, void *prog_map, + unsigned int index); +.EE +.in +.IP +and therefore replace its own program flow with the one from the program +at the given program array slot, if present. +This can be regarded as kind of a jump table to a different eBPF program. +The invoked program will then reuse the same stack. +When a jump into the new program has been performed, +it won't return to the old program anymore. +.IP +If no eBPF program is found at the given index of the program array +(because the map slot doesn't contain a valid program file descriptor, +the specified lookup index/key is out of bounds, +or the limit of 32 +.\" MAX_TAIL_CALL_CNT +nested calls has been exceed), +execution continues with the current eBPF program. +This can be used as a fall-through for default cases. +.IP +A program array map is useful, for example, in tracing or networking, to +handle individual system calls or protocols in their own subprograms and +use their identifiers as an individual map index. +This approach may result in performance benefits, +and also makes it possible to overcome the maximum +instruction limit of a single eBPF program. +In dynamic environments, +a user-space daemon might atomically replace individual subprograms +at run-time with newer versions to alter overall program behavior, +for instance, if global policies change. +.\" +.SS eBPF programs +The +.B BPF_PROG_LOAD +command is used to load an eBPF program into the kernel. +The return value for this command is a new file descriptor associated +with this eBPF program. +.PP +.in +4n +.EX +char bpf_log_buf[LOG_BUF_SIZE]; + +int +bpf_prog_load(enum bpf_prog_type type, + const struct bpf_insn *insns, int insn_cnt, + const char *license) +{ + union bpf_attr attr = { + .prog_type = type, + .insns = ptr_to_u64(insns), + .insn_cnt = insn_cnt, + .license = ptr_to_u64(license), + .log_buf = ptr_to_u64(bpf_log_buf), + .log_size = LOG_BUF_SIZE, + .log_level = 1, + }; + + return bpf(BPF_PROG_LOAD, &attr, sizeof(attr)); +} +.EE +.in +.PP +.I prog_type +is one of the available program types: +.IP +.in +4n +.EX +enum bpf_prog_type { + BPF_PROG_TYPE_UNSPEC, /* Reserve 0 as invalid + program type */ + BPF_PROG_TYPE_SOCKET_FILTER, + BPF_PROG_TYPE_KPROBE, + BPF_PROG_TYPE_SCHED_CLS, + BPF_PROG_TYPE_SCHED_ACT, +}; +.EE +.in +.PP +For further details of eBPF program types, see below. +.PP +The remaining fields of +.I bpf_attr +are set as follows: +.IP * 3 +.I insns +is an array of +.I "struct bpf_insn" +instructions. +.IP * +.I insn_cnt +is the number of instructions in the program referred to by +.IR insns . +.IP * +.I license +is a license string, which must be GPL compatible to call helper functions +marked +.IR gpl_only . +(The licensing rules are the same as for kernel modules, +so that also dual licenses, such as "Dual BSD/GPL", may be used.) +.IP * +.I log_buf +is a pointer to a caller-allocated buffer in which the in-kernel +verifier can store the verification log. +This log is a multi-line string that can be checked by +the program author in order to understand how the verifier came to +the conclusion that the eBPF program is unsafe. +The format of the output can change at any time as the verifier evolves. +.IP * +.I log_size +size of the buffer pointed to by +.IR log_buf . +If the size of the buffer is not large enough to store all +verifier messages, \-1 is returned and +.I errno +is set to +.BR ENOSPC . +.IP * +.I log_level +verbosity level of the verifier. +A value of zero means that the verifier will not provide a log; +in this case, +.I log_buf +must be a NULL pointer, and +.I log_size +must be zero. +.PP +Applying +.BR close (2) +to the file descriptor returned by +.B BPF_PROG_LOAD +will unload the eBPF program (but see NOTES). +.PP +Maps are accessible from eBPF programs and are used to exchange data between +eBPF programs and between eBPF programs and user-space programs. +For example, +eBPF programs can process various events (like kprobe, packets) and +store their data into a map, +and user-space programs can then fetch data from the map. +Conversely, user-space programs can use a map as a configuration mechanism, +populating the map with values checked by the eBPF program, +which then modifies its behavior on the fly according to those values. +.\" +.\" +.SS eBPF program types +The eBPF program type +.RI ( prog_type ) +determines the subset of kernel helper functions that the program +may call. +The program type also determines the program input (context)\(emthe +format of +.I "struct bpf_context" +(which is the data blob passed into the eBPF program as the first argument). +.\" +.\" FIXME +.\" Somewhere in this page we need a general introduction to the +.\" bpf_context. For example, how does a BPF program access the +.\" context? +.PP +For example, a tracing program does not have the exact same +subset of helper functions as a socket filter program +(though they may have some helpers in common). +Similarly, +the input (context) for a tracing program is a set of register values, +while for a socket filter it is a network packet. +.PP +The set of functions available to eBPF programs of a given type may increase +in the future. +.PP +The following program types are supported: +.TP +.BR BPF_PROG_TYPE_SOCKET_FILTER " (since Linux 3.19)" +Currently, the set of functions for +.B BPF_PROG_TYPE_SOCKET_FILTER +is: +.IP +.in +4n +.EX +bpf_map_lookup_elem(map_fd, void *key) + /* look up key in a map_fd */ +bpf_map_update_elem(map_fd, void *key, void *value) + /* update key/value */ +bpf_map_delete_elem(map_fd, void *key) + /* delete key in a map_fd */ +.EE +.in +.IP +The +.I bpf_context +argument is a pointer to a +.IR "struct __sk_buff" . +.\" FIXME: We need some text here to explain how the program +.\" accesses __sk_buff. +.\" See 'struct __sk_buff' and commit 9bac3d6d548e5 +.\" +.\" Alexei commented: +.\" Actually now in case of SOCKET_FILTER, SCHED_CLS, SCHED_ACT +.\" the program can now access skb fields. +.\" +.TP +.BR BPF_PROG_TYPE_KPROBE " (since Linux 4.1) +.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 +[To be documented] +.\" FIXME Document this program type +.\" Describe allowed helper functions for this program type +.\" Describe bpf_context for this program type +.\" +.\" FIXME We need text here to describe 'kern_version' +.TP +.BR BPF_PROG_TYPE_SCHED_CLS " (since Linux 4.1) +.\" commit 96be4325f443dbbfeb37d2a157675ac0736531a1 +.\" commit e2e9b6541dd4b31848079da80fe2253daaafb549 +[To be documented] +.\" FIXME Document this program type +.\" Describe allowed helper functions for this program type +.\" Describe bpf_context for this program type +.TP +.BR BPF_PROG_TYPE_SCHED_ACT " (since Linux 4.1) +.\" commit 94caee8c312d96522bcdae88791aaa9ebcd5f22c +.\" commit a8cb5f556b567974d75ea29c15181c445c541b1f +[To be documented] +.\" FIXME Document this program type +.\" Describe allowed helper functions for this program type +.\" Describe bpf_context for this program type +.SS Events +Once a program is loaded, it can be attached to an event. +Various kernel subsystems have different ways to do so. +.PP +Since Linux 3.19, +.\" commit 89aa075832b0da4402acebd698d0411dcc82d03e +the following call will attach the program +.I prog_fd +to the socket +.IR sockfd , +which was created by an earlier call to +.BR socket (2): +.PP +.in +4n +.EX +setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF, + &prog_fd, sizeof(prog_fd)); +.EE +.in +.PP +Since Linux 4.1, +.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 +the following call may be used to attach +the eBPF program referred to by the file descriptor +.I prog_fd +to a perf event file descriptor, +.IR event_fd , +that was created by a previous call to +.BR perf_event_open (2): +.PP +.in +4n +.EX +ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd); +.EE +.in +.\" +.\" +.SH EXAMPLES +.EX +/* bpf+sockets example: + * 1. create array map of 256 elements + * 2. load program that counts number of packets received + * r0 = skb->data[ETH_HLEN + offsetof(struct iphdr, protocol)] + * map[r0]++ + * 3. attach prog_fd to raw socket via setsockopt() + * 4. print number of received TCP/UDP packets every second + */ +int +main(int argc, char **argv) +{ + int sock, map_fd, prog_fd, key; + long long value = 0, tcp_cnt, udp_cnt; + + map_fd = bpf_create_map(BPF_MAP_TYPE_ARRAY, sizeof(key), + sizeof(value), 256); + if (map_fd < 0) { + printf("failed to create map '%s'\\n", strerror(errno)); + /* likely not run as root */ + return 1; + } + + struct bpf_insn prog[] = { + BPF_MOV64_REG(BPF_REG_6, BPF_REG_1), /* r6 = r1 */ + BPF_LD_ABS(BPF_B, ETH_HLEN + offsetof(struct iphdr, protocol)), + /* r0 = ip->proto */ + BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_0, -4), + /* *(u32 *)(fp - 4) = r0 */ + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), /* r2 = fp */ + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -4), /* r2 = r2 - 4 */ + BPF_LD_MAP_FD(BPF_REG_1, map_fd), /* r1 = map_fd */ + BPF_CALL_FUNC(BPF_FUNC_map_lookup_elem), + /* r0 = map_lookup(r1, r2) */ + BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 2), + /* if (r0 == 0) goto pc+2 */ + BPF_MOV64_IMM(BPF_REG_1, 1), /* r1 = 1 */ + BPF_XADD(BPF_DW, BPF_REG_0, BPF_REG_1, 0, 0), + /* lock *(u64 *) r0 += r1 */ +.\" == atomic64_add + BPF_MOV64_IMM(BPF_REG_0, 0), /* r0 = 0 */ + BPF_EXIT_INSN(), /* return r0 */ + }; + + prog_fd = bpf_prog_load(BPF_PROG_TYPE_SOCKET_FILTER, prog, + sizeof(prog), "GPL"); + + sock = open_raw_sock("lo"); + + assert(setsockopt(sock, SOL_SOCKET, SO_ATTACH_BPF, &prog_fd, + sizeof(prog_fd)) == 0); + + for (;;) { + key = IPPROTO_TCP; + assert(bpf_lookup_elem(map_fd, &key, &tcp_cnt) == 0); + key = IPPROTO_UDP; + assert(bpf_lookup_elem(map_fd, &key, &udp_cnt) == 0); + printf("TCP %lld UDP %lld packets\\n", tcp_cnt, udp_cnt); + sleep(1); + } + + return 0; +} +.EE +.PP +Some complete working code can be found in the +.IR samples/bpf +directory in the kernel source tree. +.SH RETURN VALUE +For a successful call, the return value depends on the operation: +.TP +.B BPF_MAP_CREATE +The new file descriptor associated with the eBPF map. +.TP +.B BPF_PROG_LOAD +The new file descriptor associated with the eBPF program. +.TP +All other commands +Zero. +.PP +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.BR E2BIG +The eBPF program is too large or a map reached the +.I max_entries +limit (maximum number of elements). +.TP +.BR EACCES +For +.BR BPF_PROG_LOAD, +even though all program instructions are valid, the program has been +rejected because it was deemed unsafe. +This may be because it may have +accessed a disallowed memory region or an uninitialized stack/register or +because the function constraints don't match the actual types or because +there was a misaligned memory access. +In this case, it is recommended to call +.BR bpf () +again with +.I log_level = 1 +and examine +.I log_buf +for the specific reason provided by the verifier. +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EFAULT +One of the pointers +.RI ( key +or +.I value +or +.I log_buf +or +.IR insns ) +is outside the accessible address space. +.TP +.B EINVAL +The value specified in +.I cmd +is not recognized by this kernel. +.TP +.B EINVAL +For +.BR BPF_MAP_CREATE , +either +.I map_type +or attributes are invalid. +.TP +.B EINVAL +For +.BR BPF_MAP_*_ELEM +commands, +some of the fields of +.I "union bpf_attr" +that are not used by this command +are not set to zero. +.TP +.B EINVAL +For +.BR BPF_PROG_LOAD, +indicates an attempt to load an invalid program. +eBPF programs can be deemed +invalid due to unrecognized instructions, the use of reserved fields, jumps +out of range, infinite loops or calls of unknown functions. +.TP +.BR ENOENT +For +.B BPF_MAP_LOOKUP_ELEM +or +.BR BPF_MAP_DELETE_ELEM , +indicates that the element with the given +.I key +was not found. +.TP +.B ENOMEM +Cannot allocate sufficient memory. +.TP +.B EPERM +The call was made without sufficient privilege +(without the +.B CAP_SYS_ADMIN +capability). +.SH VERSIONS +The +.BR bpf () +system call first appeared in Linux 3.18. +.SH CONFORMING TO +The +.BR bpf () +system call is Linux-specific. +.SH NOTES +In the current implementation, all +.BR bpf () +commands require the caller to have the +.B CAP_SYS_ADMIN +capability. +.PP +eBPF objects (maps and programs) can be shared between processes. +For example, after +.BR fork (2), +the child inherits file descriptors referring to the same eBPF objects. +In addition, file descriptors referring to eBPF objects can be +transferred over UNIX domain sockets. +File descriptors referring to eBPF objects can be duplicated +in the usual way, using +.BR dup (2) +and similar calls. +An eBPF object is deallocated only after all file descriptors +referring to the object have been closed. +.PP +eBPF programs can be written in a restricted C that is compiled (using the +.B clang +compiler) into eBPF bytecode. +Various features are omitted from this restricted C, such as loops, +global variables, variadic functions, floating-point numbers, +and passing structures as function arguments. +Some examples can be found in the +.I samples/bpf/*_kern.c +files in the kernel source tree. +.\" There are also examples for the tc classifier, in the iproute2 +.\" project, in examples/bpf +.PP +The kernel contains a just-in-time (JIT) compiler that translates +eBPF bytecode into native machine code for better performance. +The JIT compiler is disabled by default, +but its operation can be controlled by writing one of the +following integer strings to the file +.IR /proc/sys/net/core/bpf_jit_enable : +.IP 0 3 +Disable JIT compilation (default). +.IP 1 +Normal compilation. +.IP 2 +Debugging mode. +The generated opcodes are dumped in hexadecimal into the kernel log. +These opcodes can then be disassembled using the program +.IR tools/net/bpf_jit_disasm.c +provided in the kernel source tree. +.PP +JIT compiler for eBPF is currently available for the x86-64, arm64, +and s390 architectures. +.SH SEE ALSO +.BR seccomp (2), +.BR socket (7), +.BR tc (8), +.BR tc-bpf (8) +.PP +Both classic and extended BPF are explained in the kernel source file +.IR Documentation/networking/filter.txt . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/break.2 b/man2/break.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/break.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/brk.2 b/man2/brk.2 new file mode 100644 index 0000000..6fb9c55 --- /dev/null +++ b/man2/brk.2 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 21 19:52:58 1993 by Rik Faith +.\" Modified Sun Aug 21 17:40:38 1994 by Rik Faith +.\" +.TH BRK 2 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +brk, sbrk \- change data segment size +.SH SYNOPSIS +.B #include +.PP +.BI "int brk(void *" addr ); +.PP +.BI "void *sbrk(intptr_t " increment ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR brk (), +.BR sbrk (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.19: +.nf +_DEFAULT_SOURCE || + (_XOPEN_SOURCE\ >=\ 500) && +.\" (_XOPEN_SOURCE\ >=\ 500 || +.\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) && + ! (_POSIX_C_SOURCE\ >=\ 200112L) +.fi +.TP 4 +From glibc 2.12 to 2.19: +.nf +_BSD_SOURCE || _SVID_SOURCE || + (_XOPEN_SOURCE\ >=\ 500) && +.\" (_XOPEN_SOURCE\ >=\ 500 || +.\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) && + ! (_POSIX_C_SOURCE\ >=\ 200112L) +.fi +.TP 4 +Before glibc 2.12: +_BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH DESCRIPTION +.BR brk () +and +.BR sbrk () +change the location of the +.IR "program break" , +which defines the end of the process's data segment +(i.e., the program break is the first location after the end of the +uninitialized data segment). +Increasing the program break has the effect of +allocating memory to the process; +decreasing the break deallocates memory. +.PP +.BR brk () +sets the end of the data segment to the value specified by +.IR addr , +when that value is reasonable, the system has enough memory, +and the process does not exceed its maximum data size (see +.BR setrlimit (2)). +.PP +.BR sbrk () +increments the program's data space by +.I increment +bytes. +Calling +.BR sbrk () +with an +.I increment +of 0 can be used to find the current location of the program break. +.SH RETURN VALUE +On success, +.BR brk () +returns zero. +On error, \-1 is returned, and +.I errno +is set to +.BR ENOMEM . +.PP +On success, +.BR sbrk () +returns the previous program break. +(If the break was increased, +then this value is a pointer to the start of the newly allocated memory). +On error, +.I "(void\ *)\ \-1" +is returned, and +.I errno +is set to +.BR ENOMEM . +.SH CONFORMING TO +4.3BSD; SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001. +.\" +.\" .BR brk () +.\" and +.\" .BR sbrk () +.\" are not defined in the C Standard and are deliberately excluded from the +.\" POSIX.1-1990 standard (see paragraphs B.1.1.1.3 and B.8.3.3). +.SH NOTES +Avoid using +.BR brk () +and +.BR sbrk (): +the +.BR malloc (3) +memory allocation package is the +portable and comfortable way of allocating memory. +.PP +Various systems use various types for the argument of +.BR sbrk (). +Common are \fIint\fP, \fIssize_t\fP, \fIptrdiff_t\fP, \fIintptr_t\fP. +.\" One sees +.\" \fIint\fP (e.g., XPGv4, DU 4.0, HP-UX 11, FreeBSD 4.0, OpenBSD 3.2), +.\" \fIssize_t\fP (OSF1 2.0, Irix 5.3, 6.5), +.\" \fIptrdiff_t\fP (libc4, libc5, ulibc, glibc 2.0, 2.1), +.\" \fIintptr_t\fP (e.g., XPGv5, AIX, SunOS 5.8, 5.9, FreeBSD 4.7, NetBSD 1.6, +.\" Tru64 5.1, glibc2.2). +.SS C library/kernel differences +The return value described above for +.BR brk () +is the behavior provided by the glibc wrapper function for the Linux +.BR brk () +system call. +(On most other implementations, the return value from +.BR brk () +is the same; this return value was also specified in SUSv2.) +However, +the actual Linux system call returns the new program break on success. +On failure, the system call returns the current break. +The glibc wrapper function does some work +(i.e., checks whether the new break is less than +.IR addr ) +to provide the 0 and \-1 return values described above. +.PP +On Linux, +.BR sbrk () +is implemented as a library function that uses the +.BR brk () +system call, and does some internal bookkeeping so that it can +return the old break value. +.SH SEE ALSO +.BR execve (2), +.BR getrlimit (2), +.BR end (3), +.BR malloc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/cacheflush.2 b/man2/cacheflush.2 new file mode 100644 index 0000000..4f960b7 --- /dev/null +++ b/man2/cacheflush.2 @@ -0,0 +1,112 @@ +.\" Written by Ralf Baechle (ralf@waldorf-gmbh.de), +.\" Copyright (c) 1994, 1995 Waldorf GMBH +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH CACHEFLUSH 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +cacheflush \- flush contents of instruction and/or data cache +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int cacheflush(char *" addr ", int "nbytes ", int "cache ); +.fi +.SH DESCRIPTION +.BR cacheflush () +flushes the contents of the indicated cache(s) for the +user addresses in the range +.I addr +to +.IR (addr+nbytes-1) . +.I cache +may be one of: +.TP +.B ICACHE +Flush the instruction cache. +.TP +.B DCACHE +Write back to memory and invalidate the affected valid cache lines. +.TP +.B BCACHE +Same as +.BR (ICACHE|DCACHE) . +.SH RETURN VALUE +.BR cacheflush () +returns 0 on success or \-1 on error. +If errors are detected, +.I errno +will indicate the error. +.SH ERRORS +.TP +.B EFAULT +Some or all of the address range +.I addr +to +.I (addr+nbytes-1) +is not accessible. +.TP +.B EINVAL +.I cache +is not one of +.BR ICACHE , +.BR DCACHE , +or +.BR BCACHE +(but see BUGS). +.SH CONFORMING TO +Historically, this system call was available on all MIPS UNIX variants +including RISC/os, IRIX, Ultrix, NetBSD, OpenBSD, and FreeBSD +(and also on some non-UNIX MIPS operating systems), so that +the existence of this call in MIPS operating systems is a de-facto +standard. +.SS Caveat +.BR cacheflush () +should not be used in programs intended to be portable. +On Linux, this call first appeared on the MIPS architecture, +but nowadays, Linux provides a +.BR cacheflush () +system call on some other architectures, but with different arguments. +.SH BUGS +Linux kernels older than version 2.6.11 ignore the +.I addr +and +.I nbytes +arguments, making this function fairly expensive. +Therefore, the whole cache is always flushed. +.PP +This function always behaves as if +.BR BCACHE +has been passed for the +.I cache +argument and does not do any error checking on the +.I cache +argument. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/capget.2 b/man2/capget.2 new file mode 100644 index 0000000..41a25e6 --- /dev/null +++ b/man2/capget.2 @@ -0,0 +1,258 @@ +.\" written by Andrew Morgan +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" may be distributed as per GPL +.\" %%%LICENSE_END +.\" +.\" Modified by David A. Wheeler +.\" Modified 2004-05-27, mtk +.\" Modified 2004-06-21, aeb +.\" Modified 2008-04-28, morgan of kernel.org +.\" Update in line with addition of file capabilities and +.\" 64-bit capability sets in kernel 2.6.2[45]. +.\" Modified 2009-01-26, andi kleen +.\" +.TH CAPGET 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +capget, capset \- set/get capabilities of thread(s) +.SH SYNOPSIS +.B #include +.PP +.BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap ); +.PP +.BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap ); +.SH DESCRIPTION +Since Linux 2.2, +the power of the superuser (root) has been partitioned into +a set of discrete capabilities. +Each thread has a set of effective capabilities identifying +which capabilities (if any) it may currently exercise. +Each thread also has a set of inheritable capabilities that may be +passed through an +.BR execve (2) +call, and a set of permitted capabilities +that it can make effective or inheritable. +.PP +These two system calls are the raw kernel interface for getting and +setting thread capabilities. +Not only are these system calls specific to Linux, +but the kernel API is likely to change and use of +these system calls (in particular the format of the +.I cap_user_*_t +types) is subject to extension with each kernel revision, +but old programs will keep working. +.PP +The portable interfaces are +.BR cap_set_proc (3) +and +.BR cap_get_proc (3); +if possible, you should use those interfaces in applications. +If you wish to use the Linux extensions in applications, you should +use the easier-to-use interfaces +.BR capsetp (3) +and +.BR capgetp (3). +.SS Current details +Now that you have been warned, some current kernel details. +The structures are defined as follows. +.PP +.in +4n +.EX +#define _LINUX_CAPABILITY_VERSION_1 0x19980330 +#define _LINUX_CAPABILITY_U32S_1 1 + + /* V2 added in Linux 2.6.25; deprecated */ +#define _LINUX_CAPABILITY_VERSION_2 0x20071026 +.\" commit e338d263a76af78fe8f38a72131188b58fceb591 +.\" Added 64 bit capability support +#define _LINUX_CAPABILITY_U32S_2 2 + + /* V3 added in Linux 2.6.26 */ +#define _LINUX_CAPABILITY_VERSION_3 0x20080522 +.\" commit ca05a99a54db1db5bca72eccb5866d2a86f8517f +#define _LINUX_CAPABILITY_U32S_3 2 + +typedef struct __user_cap_header_struct { + __u32 version; + int pid; +} *cap_user_header_t; + +typedef struct __user_cap_data_struct { + __u32 effective; + __u32 permitted; + __u32 inheritable; +} *cap_user_data_t; +.EE +.in +.PP +The +.IR effective , +.IR permitted , +and +.I inheritable +fields are bit masks of the capabilities defined in +.BR capabilities (7). +Note that the +.B CAP_* +values are bit indexes and need to be bit-shifted before ORing into +the bit fields. +To define the structures for passing to the system call, you have to use the +.I struct __user_cap_header_struct +and +.I struct __user_cap_data_struct +names because the typedefs are only pointers. +.PP +Kernels prior to 2.6.25 prefer +32-bit capabilities with version +.BR _LINUX_CAPABILITY_VERSION_1 . +Linux 2.6.25 added 64-bit capability sets, with version +.BR _LINUX_CAPABILITY_VERSION_2 . +There was, however, an API glitch, and Linux 2.6.26 added +.BR _LINUX_CAPABILITY_VERSION_3 +to fix the problem. +.PP +Note that 64-bit capabilities use +.IR datap [0] +and +.IR datap [1], +whereas 32-bit capabilities use only +.IR datap [0]. +.PP +On kernels that support file capabilities (VFS capabilities support), +these system calls behave slightly differently. +This support was added as an option in Linux 2.6.24, +and became fixed (nonoptional) in Linux 2.6.33. +.PP +For +.BR capget () +calls, one can probe the capabilities of any process by specifying its +process ID with the +.I hdrp->pid +field value. +.SS With VFS capabilities support +VFS capabilities employ a file extended attribute (see +.BR xattr (7)) +to allow capabilities to be attached to executables. +This privilege model obsoletes kernel support for one process +asynchronously setting the capabilities of another. +That is, on kernels that have VFS capabilities support, when calling +.BR capset (), +the only permitted values for +.I hdrp->pid +are 0 or, equivalently, the value returned by +.BR gettid (2). +.\" +.SS Without VFS capabilities support +On older kernels that do not provide VFS capabilities support +.BR capset () +can, if the caller has the +.BR CAP_SETPCAP +capability, be used to change not only the caller's own capabilities, +but also the capabilities of other threads. +The call operates on the capabilities of the thread specified by the +.I pid +field of +.I hdrp +when that is nonzero, or on the capabilities of the calling thread if +.I pid +is 0. +If +.I pid +refers to a single-threaded process, then +.I pid +can be specified as a traditional process ID; +operating on a thread of a multithreaded process requires a thread ID +of the type returned by +.BR gettid (2). +For +.BR capset (), +.I pid +can also be: \-1, meaning perform the change on all threads except the +caller and +.BR init (1); +or a value less than \-1, in which case the change is applied +to all members of the process group whose ID is \-\fIpid\fP. +.PP +For details on the data, see +.BR capabilities (7). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +The calls fail with the error +.BR EINVAL , +and set the +.I version +field of +.I hdrp +to the kernel preferred value of +.B _LINUX_CAPABILITY_VERSION_? +when an unsupported +.I version +value is specified. +In this way, one can probe what the current +preferred capability revision is. +.SH ERRORS +.TP +.B EFAULT +Bad memory address. +.I hdrp +must not be NULL. +.I datap +may be NULL only when the user is trying to determine the preferred +capability version format supported by the kernel. +.TP +.B EINVAL +One of the arguments was invalid. +.TP +.B EPERM +An attempt was made to add a capability to the Permitted set, or to set +a capability in the Effective or Inheritable sets that is not in the +Permitted set. +.TP +.B EPERM +The caller attempted to use +.BR capset () +to modify the capabilities of a thread other than itself, +but lacked sufficient privilege. +For kernels supporting VFS +capabilities, this is never permitted. +For kernels lacking VFS +support, the +.B CAP_SETPCAP +capability is required. +(A bug in kernels before 2.6.11 meant that this error could also +occur if a thread without this capability tried to change its +own capabilities by specifying the +.I pid +field as a nonzero value (i.e., the value returned by +.BR getpid (2)) +instead of 0.) +.TP +.B ESRCH +No such thread. +.SH CONFORMING TO +These system calls are Linux-specific. +.SH NOTES +The portable interface to the capability querying and setting +functions is provided by the +.I libcap +library and is available here: +.br +.UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git +.UE +.SH SEE ALSO +.BR clone (2), +.BR gettid (2), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/capset.2 b/man2/capset.2 new file mode 100644 index 0000000..9e829cb --- /dev/null +++ b/man2/capset.2 @@ -0,0 +1 @@ +.so man2/capget.2 diff --git a/man2/chdir.2 b/man2/chdir.2 new file mode 100644 index 0000000..d9711ed --- /dev/null +++ b/man2/chdir.2 @@ -0,0 +1,150 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1995-04-15 by Michael Chastain : +.\" Added 'fchdir'. Fixed bugs in error section. +.\" Modified 1996-10-21 by Eric S. Raymond +.\" Modified 1997-08-21 by Joseph S. Myers +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CHDIR 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +chdir, fchdir \- change working directory +.SH SYNOPSIS +.B #include +.PP +.BI "int chdir(const char *" path ); +.br +.BI "int fchdir(int " fd ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fchdir (): +.PD 0 +.ad l +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc up to and including 2.19: */ _BSD_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +.BR chdir () +changes the current working directory of the calling process to the +directory specified in +.IR path . +.PP +.BR fchdir () +is identical to +.BR chdir (); +the only difference is that the directory is given as an +open file descriptor. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Depending on the filesystem, other errors can be returned. +The more +general errors for +.BR chdir () +are listed below: +.TP +.B EACCES +Search permission is denied for one of the components of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The directory specified in +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of +.I path +is not a directory. +.PP +The general errors for +.BR fchdir () +are listed below: +.TP +.B EACCES +Search permission was denied on the directory open on +.IR fd . +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD. +.SH NOTES +The current working directory is the starting point for interpreting +relative pathnames (those not starting with \(aq/\(aq). +.PP +A child process created via +.BR fork (2) +inherits its parent's current working directory. +The current working directory is left unchanged by +.BR execve (2). +.SH SEE ALSO +.BR chroot (2), +.BR getcwd (3), +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/chmod.2 b/man2/chmod.2 new file mode 100644 index 0000000..5c55553 --- /dev/null +++ b/man2/chmod.2 @@ -0,0 +1,397 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1997-01-12 by Michael Haardt +.\" : NFS details +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CHMOD 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +chmod, fchmod, fchmodat \- change permissions of a file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int chmod(const char *" pathname ", mode_t " mode ); +.br +.BI "int fchmod(int " fd ", mode_t " mode ); + +.BR "#include " " /* Definition of AT_* constants */" +.B #include +.PP +.BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \ +mode ", int " flags ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.PD 0 +.BR fchmod (): +.RS 4 +Since glibc 2.24: + _POSIX_C_SOURCE\ >=\ 199309L +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.PP +Glibc 2.19 to 2.23 + _POSIX_C_SOURCE +.PP +Glibc 2.16 to 2.19: + _BSD_SOURCE || _POSIX_C_SOURCE +.PP +Glibc 2.12 to 2.16: + _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || + _POSIX_C_SOURCE >= 200809L +.PP +Glibc 2.11 and earlier: + _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.RE +.PD +.PP +.BR fchmodat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD +.ad +.SH DESCRIPTION +The +.BR chmod () +and +.BR fchmod () +system calls change a files mode bits. +(The file mode consists of the file permission bits plus the set-user-ID, +set-group-ID, and sticky bits.) +These system calls differ only in how the file is specified: +.IP * 2 +.BR chmod () +changes the mode of the file specified whose pathname is given in +.IR pathname , +which is dereferenced if it is a symbolic link. +.IP * +.BR fchmod () +changes the mode of the file referred to by the open file descriptor +.IR fd . +.PP +The new file mode is specified in +.IR mode , +which is a bit mask created by ORing together zero or +more of the following: +.TP 18 +.BR S_ISUID " (04000)" +set-user-ID (set process effective user ID on +.BR execve (2)) +.TP +.BR S_ISGID " (02000)" +set-group-ID (set process effective group ID on +.BR execve (2); +mandatory locking, as described in +.BR fcntl (2); +take a new file's group from parent directory, as described in +.BR chown (2) +and +.BR mkdir (2)) +.TP +.BR S_ISVTX " (01000)" +sticky bit (restricted deletion flag, as described in +.BR unlink (2)) +.TP +.BR S_IRUSR " (00400)" +read by owner +.TP +.BR S_IWUSR " (00200)" +write by owner +.TP +.BR S_IXUSR " (00100)" +execute/search by owner ("search" applies for directories, +and means that entries within the directory can be accessed) +.TP +.BR S_IRGRP " (00040)" +read by group +.TP +.BR S_IWGRP " (00020)" +write by group +.TP +.BR S_IXGRP " (00010)" +execute/search by group +.TP +.BR S_IROTH " (00004)" +read by others +.TP +.BR S_IWOTH " (00002)" +write by others +.TP +.BR S_IXOTH " (00001)" +execute/search by others +.PP +The effective UID of the calling process must match the owner of the file, +or the process must be privileged (Linux: it must have the +.B CAP_FOWNER +capability). +.PP +If the calling process is not privileged (Linux: does not have the +.B CAP_FSETID +capability), and the group of the file does not match +the effective group ID of the process or one of its +supplementary group IDs, the +.B S_ISGID +bit will be turned off, +but this will not cause an error to be returned. +.PP +As a security measure, depending on the filesystem, +the set-user-ID and set-group-ID execution bits +may be turned off if a file is written. +(On Linux, this occurs if the writing process does not have the +.B CAP_FSETID +capability.) +On some filesystems, only the superuser can set the sticky bit, +which may have a special meaning. +For the sticky bit, and for set-user-ID and set-group-ID bits on +directories, see +.BR inode (7). +.PP +On NFS filesystems, restricting the permissions will immediately influence +already open files, because the access control is done on the server, but +open files are maintained by the client. +Widening the permissions may be +delayed for other clients if attribute caching is enabled on them. +.\" +.\" +.SS fchmodat() +The +.BR fchmodat () +system call operates in exactly the same way as +.BR chmod (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR chmod () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR chmod ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +.I flags +can either be 0, or include the following flag: +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead operate on the link itself. +This flag is not currently implemented. +.PP +See +.BR openat (2) +for an explanation of the need for +.BR fchmodat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Depending on the filesystem, +errors other than those listed below can be returned. +.PP +The more general errors for +.BR chmod () +are listed below: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EPERM +The effective UID does not match the owner of the file, +and the process is not privileged (Linux: it does not have the +.B CAP_FOWNER +capability). +.TP +.B EPERM +The file is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +The named file resides on a read-only filesystem. +.PP +The general errors for +.BR fchmod () +are listed below: +.TP +.B EBADF +The file descriptor +.I fd +is not valid. +.TP +.B EIO +See above. +.TP +.B EPERM +See above. +.TP +.B EROFS +See above. +.PP +The same errors that occur for +.BR chmod () +can also occur for +.BR fchmodat (). +The following additional errors can occur for +.BR fchmodat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B ENOTSUP +.I flags +specified +.BR AT_SYMLINK_NOFOLLOW , +which is not supported. +.SH VERSIONS +.BR fchmodat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR chmod (), +.BR fchmod (): +4.4BSD, SVr4, POSIX.1-2001i, POSIX.1-2008. +.PP +.BR fchmodat (): +POSIX.1-2008. +.SH NOTES +.SS C library/kernel differences +The GNU C library +.BR fchmodat () +wrapper function implements the POSIX-specified +interface described in this page. +This interface differs from the underlying Linux system call, which does +.I not +have a +.I flags +argument. +.SS Glibc notes +On older kernels where +.BR fchmodat () +is unavailable, the glibc wrapper function falls back to the use of +.BR chmod (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.IR /proc/self/fd +that corresponds to the +.IR dirfd +argument. +.SH SEE ALSO +.BR chmod (1), +.BR chown (2), +.BR execve (2), +.BR open (2), +.BR stat (2), +.BR inode (7), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/chown.2 b/man2/chown.2 new file mode 100644 index 0000000..ef358e0 --- /dev/null +++ b/man2/chown.2 @@ -0,0 +1,512 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (c) 2006, 2007, 2008, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1996-07-09 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-05-18 by Michael Haardt +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2007-07-08, mtk, added an example program; updated SYNOPSIS +.\" 2008-05-08, mtk, Describe rules governing ownership of new files +.\" (bsdgroups versus sysvgroups, and the effect of the parent +.\" directory's set-group-ID mode bit). +.\" +.TH CHOWN 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +chown, fchown, lchown, fchownat \- change ownership of a file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group ); +.BI "int fchown(int " fd ", uid_t " owner ", gid_t " group ); +.BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int fchownat(int " dirfd ", const char *" pathname , +.BI " uid_t " owner ", gid_t " group ", int " flags ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fchown (), +.BR lchown (): +.PD 0 +.ad l +.RS 4 +/* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.PP +.BR fchownat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +These system calls change the owner and group of a file. +The +.BR chown (), +.BR fchown (), +and +.BR lchown () +system calls differ only in how the file is specified: +.IP * 2 +.BR chown () +changes the ownership of the file specified by +.IR pathname , +which is dereferenced if it is a symbolic link. +.IP * +.BR fchown () +changes the ownership of the file referred to by the open file descriptor +.IR fd . +.IP * +.BR lchown () +is like +.BR chown (), +but does not dereference symbolic links. +.PP +Only a privileged process (Linux: one with the +.B CAP_CHOWN +capability) may change the owner of a file. +The owner of a file may change the group of the file +to any group of which that owner is a member. +A privileged process (Linux: with +.BR CAP_CHOWN ) +may change the group arbitrarily. +.PP +If the +.I owner +or +.I group +is specified as \-1, then that ID is not changed. +.PP +When the owner or group of an executable file is +changed by an unprivileged user, the +.B S_ISUID +and +.B S_ISGID +mode bits are cleared. +POSIX does not specify whether +this also should happen when root does the +.BR chown (); +the Linux behavior depends on the kernel version, +and since Linux 2.2.13, root is treated like other users. +.\" In Linux 2.0 kernels, superuser was like everyone else +.\" In 2.2, up to 2.2.12, these bits were not cleared for superuser. +.\" Since 2.2.13, superuser is once more like everyone else. +In case of a non-group-executable file (i.e., one for which the +.B S_IXGRP +bit is not set) the +.B S_ISGID +bit indicates mandatory locking, and is not cleared by a +.BR chown (). +.PP +When the owner or group of an executable file is changed (by any user), +all capability sets for the file are cleared. +.\" +.SS fchownat() +The +.BR fchownat () +system call operates in exactly the same way as +.BR chown (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR chown () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR chown ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +The +.I flags +argument is a bit mask created by ORing together +0 or more of the following values; +.TP +.BR AT_EMPTY_PATH " (since Linux 2.6.39)" +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I pathname +is an empty string, operate on the file referred to by +.IR dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead operate on the link itself, like +.BR lchown (). +(By default, +.BR fchownat () +dereferences symbolic links, like +.BR chown ().) +.PP +See +.BR openat (2) +for an explanation of the need for +.BR fchownat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Depending on the filesystem, +errors other than those listed below can be returned. +.PP +The more general errors for +.BR chown () +are listed below. +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EPERM +The calling process did not have the required permissions +(see above) to change owner and/or group. +.TP +.B EPERM +The file is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +The named file resides on a read-only filesystem. +.PP +The general errors for +.BR fchown () +are listed below: +.TP +.B EBADF +.I fd +is not a valid open file descriptor. +.TP +.B EIO +A low-level I/O error occurred while modifying the inode. +.TP +.B ENOENT +See above. +.TP +.B EPERM +See above. +.TP +.B EROFS +See above. +.PP +The same errors that occur for +.BR chown () +can also occur for +.BR fchownat (). +The following additional errors can occur for +.BR fchownat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR fchownat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR chown (), +.BR fchown (), +.BR lchown (): +4.4BSD, SVr4, POSIX.1-2001, POSIX.1-2008. +.PP +The 4.4BSD version can be +used only by the superuser (that is, ordinary users cannot give away files). +.\" chown(): +.\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no +.\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions. +.\" fchown(): +.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK +.\" error conditions. +.PP +.BR fchownat (): +POSIX.1-2008. +.SH NOTES +.SS Ownership of new files +When a new file is created (by, for example, +.BR open (2) +or +.BR mkdir (2)), +its owner is made the same as the filesystem user ID of the +creating process. +The group of the file depends on a range of factors, +including the type of filesystem, +the options used to mount the filesystem, +and whether or not the set-group-ID mode bit is enabled +on the parent directory. +If the filesystem supports the +.B "\-o\ grpid" +(or, synonymously +.BR "\-o\ bsdgroups" ) +and +.B "\-o\ nogrpid" +(or, synonymously +.BR "\-o\ sysvgroups" ) +.BR mount (8) +options, then the rules are as follows: +.IP * 2 +If the filesystem is mounted with +.BR "\-o\ grpid" , +then the group of a new file is made +the same as that of the parent directory. +.IP * +If the filesystem is mounted with +.BR "\-o\ nogrpid" +and the set-group-ID bit is disabled on the parent directory, +then the group of a new file is made the same as the +process's filesystem GID. +.IP * +If the filesystem is mounted with +.BR "\-o\ nogrpid" +and the set-group-ID bit is enabled on the parent directory, +then the group of a new file is made +the same as that of the parent directory. +.PP +As at Linux 4.12, +the +.BR "\-o\ grpid" +and +.BR "\-o\ nogrpid" +mount options are supported by ext2, ext3, ext4, and XFS. +Filesystems that don't support these mount options follow the +.BR "\-o\ nogrpid" +rules. +.SS Glibc notes +On older kernels where +.BR fchownat () +is unavailable, the glibc wrapper function falls back to the use of +.BR chown () +and +.BR lchown (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.IR /proc/self/fd +that corresponds to the +.IR dirfd +argument. +.SS NFS +The +.BR chown () +semantics are deliberately violated on NFS filesystems +which have UID mapping enabled. +Additionally, the semantics of all system +calls which access the file contents are violated, because +.BR chown () +may cause immediate access revocation on already open files. +Client side +caching may lead to a delay between the time where ownership have +been changed to allow access for a user and the time where the file can +actually be accessed by the user on other clients. +.SS Historical details +The original Linux +.BR chown (), +.BR fchown (), +and +.BR lchown () +system calls supported only 16-bit user and group IDs. +Subsequently, Linux 2.4 added +.BR chown32 (), +.BR fchown32 (), +and +.BR lchown32 (), +supporting 32-bit IDs. +The glibc +.BR chown (), +.BR fchown (), +and +.BR lchown () +wrapper functions transparently deal with the variations across kernel versions. +.PP +In versions of Linux prior to 2.1.81 (and distinct from 2.1.46), +.BR chown () +did not follow symbolic links. +Since Linux 2.1.81, +.BR chown () +does follow symbolic links, and there is a new system call +.BR lchown () +that does not follow symbolic links. +Since Linux 2.1.86, this new call (that has the same semantics +as the old +.BR chown ()) +has got the same syscall number, and +.BR chown () +got the newly introduced number. +.SH EXAMPLE +.PP +The following program changes the ownership of the file named in +its second command-line argument to the value specified in its +first command-line argument. +The new owner can be specified either as a numeric user ID, +or as a username (which is converted to a user ID by using +.BR getpwnam (3) +to perform a lookup in the system password file). +.SS Program source +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + uid_t uid; + struct passwd *pwd; + char *endptr; + + if (argc != 3 || argv[1][0] == \(aq\\0\(aq) { + fprintf(stderr, "%s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */ + + if (*endptr != \(aq\\0\(aq) { /* Was not pure numeric string */ + pwd = getpwnam(argv[1]); /* Try getting UID for username */ + if (pwd == NULL) { + perror("getpwnam"); + exit(EXIT_FAILURE); + } + + uid = pwd\->pw_uid; + } + + if (chown(argv[2], uid, \-1) == \-1) { + perror("chown"); + exit(EXIT_FAILURE); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR chgrp (1), +.BR chown (1), +.BR chmod (2), +.BR flock (2), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/chown32.2 b/man2/chown32.2 new file mode 100644 index 0000000..f0a5635 --- /dev/null +++ b/man2/chown32.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man2/chroot.2 b/man2/chroot.2 new file mode 100644 index 0000000..a0d421d --- /dev/null +++ b/man2/chroot.2 @@ -0,0 +1,189 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Chastain +.\" Modified 1996-06-13 by aeb +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-08-21 by Joseph S. Myers +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CHROOT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +chroot \- change root directory +.SH SYNOPSIS +.B #include +.PP +.BI "int chroot(const char *" path ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR chroot (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.2.2: +.nf +_XOPEN_SOURCE && ! (_POSIX_C_SOURCE\ >=\ 200112L) + || /* Since glibc 2.20: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.TP 4 +.fi +Before glibc 2.2.2: none +.PD +.RE +.ad b +.SH DESCRIPTION +.BR chroot () +changes the root directory of the calling process to that specified in +.IR path . +This directory will be used for pathnames beginning with \fI/\fP. +The root directory is inherited by all children of the calling process. +.PP +Only a privileged process (Linux: one with the +.B CAP_SYS_CHROOT +capability in its user namespace) may call +.BR chroot (). +.PP +This call changes an ingredient in the pathname resolution process +and does nothing else. +In particular, it is not intended to be used +for any kind of security purpose, neither to fully sandbox a process nor +to restrict filesystem system calls. +In the past, +.BR chroot () +has been used by daemons to restrict themselves prior to passing paths +supplied by untrusted users to system calls such as +.BR open (2). +However, if a folder is moved out of the chroot directory, an attacker +can exploit that to get out of the chroot directory as well. +The easiest way to do that is to +.BR chdir (2) +to the to-be-moved directory, wait for it to be moved out, then open a +path like ../../../etc/passwd. +.PP +.\" This is how the "slightly trickier variation" works: +.\" https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt#L142 +A slightly +trickier variation also works under some circumstances if +.BR chdir (2) +is not permitted. +If a daemon allows a "chroot directory" to be specified, +that usually means that if you want to prevent remote users from accessing +files outside the chroot directory, you must ensure that folders are never +moved out of it. +.PP +This call does not change the current working directory, +so that after the call \(aq\fI.\fP\(aq can +be outside the tree rooted at \(aq\fI/\fP\(aq. +In particular, the superuser can escape from a "chroot jail" +by doing: +.PP +.in +4n +.EX +mkdir foo; chroot foo; cd .. +.EE +.in +.PP +This call does not close open file descriptors, and such file +descriptors may allow access to files outside the chroot tree. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Depending on the filesystem, other errors can be returned. +The more general errors are listed below: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.\" Also search permission is required on the final component, +.\" maybe just to guarantee that it is a directory? +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of +.I path +is not a directory. +.TP +.B EPERM +The caller has insufficient privilege. +.SH CONFORMING TO +SVr4, 4.4BSD, SUSv2 (marked LEGACY). +This function is not part of POSIX.1-2001. +.\" SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions. +.\" X/OPEN does not document EIO, ENOMEM or EFAULT error conditions. +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's root directory. +The root directory is left unchanged by +.BR execve (2). +.PP +FreeBSD has a stronger +.BR jail () +system call. +.SH SEE ALSO +.BR chroot (1), +.BR chdir (2), +.BR pivot_root (2), +.BR path_resolution (7), +.BR switch_root (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 new file mode 100644 index 0000000..fbaa04f --- /dev/null +++ b/man2/clock_getres.2 @@ -0,0 +1,340 @@ +.\" Copyright (c) 2003 Nick Clifford (zaf@nrc.co.nz), Jan 25, 2003 +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl), Aug 24, 2003 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2003-08-23 Martin Schulze improvements +.\" 2003-08-24 aeb, large parts rewritten +.\" 2004-08-06 Christoph Lameter , SMP note +.\" +.TH CLOCK_GETRES 2 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +clock_getres, clock_gettime, clock_settime \- clock and time functions +.SH SYNOPSIS +.B #include +.PP +.BI "int clock_getres(clockid_t " clk_id ", struct timespec *" res ); +.PP +.BI "int clock_gettime(clockid_t " clk_id ", struct timespec *" tp ); +.PP +.BI "int clock_settime(clockid_t " clk_id ", const struct timespec *" tp ); +.PP +Link with \fI\-lrt\fP (only for glibc versions before 2.17). +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR clock_getres (), +.BR clock_gettime (), +.BR clock_settime (): +.RS +_POSIX_C_SOURCE\ >=\ 199309L +.RE +.ad b +.SH DESCRIPTION +The function +.BR clock_getres () +finds the resolution (precision) of the specified clock +.IR clk_id , +and, if +.I res +is non-NULL, stores it in the \fIstruct timespec\fP pointed to by +.IR res . +The resolution of clocks depends on the implementation and cannot be +configured by a particular process. +If the time value pointed to by the argument +.I tp +of +.BR clock_settime () +is not a multiple of +.IR res , +then it is truncated to a multiple of +.IR res . +.PP +The functions +.BR clock_gettime () +and +.BR clock_settime () +retrieve and set the time of the specified clock +.IR clk_id . +.PP +The +.I res +and +.I tp +arguments are +.I timespec +structures, as specified in +.IR : +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.PP +The +.I clk_id +argument is the identifier of the particular clock on which to act. +A clock may be system-wide and hence visible for all processes, or +per-process if it measures time only within a single process. +.PP +All implementations support the system-wide real-time clock, +which is identified by +.BR CLOCK_REALTIME . +Its time represents seconds and nanoseconds since the Epoch. +When its time is changed, timers for a relative interval are +unaffected, but timers for an absolute point in time are affected. +.PP +More clocks may be implemented. +The interpretation of the +corresponding time values and the effect on timers is unspecified. +.PP +Sufficiently recent versions of glibc and the Linux kernel +support the following clocks: +.TP +.B CLOCK_REALTIME +System-wide clock that measures real (i.e., wall-clock) time. +Setting this clock requires appropriate privileges. +This clock is affected by discontinuous jumps in the system time +(e.g., if the system administrator manually changes the clock), +and by the incremental adjustments performed by +.BR adjtime (3) +and NTP. +.TP +.BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)" +.\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3 +A faster but less precise version of +.BR CLOCK_REALTIME . +Use when you need very fast, but not fine-grained timestamps. +Requires per-architecture support, +and probably also architecture support for this flag in the +.BR vdso (7). +.TP +.B CLOCK_MONOTONIC +Clock that cannot be set and represents monotonic time since +some unspecified starting point. +This clock is not affected by discontinuous jumps in the system time +(e.g., if the system administrator manually changes the clock), +but is affected by the incremental adjustments performed by +.BR adjtime (3) +and NTP. +.TP +.BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)" +.\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3 +A faster but less precise version of +.BR CLOCK_MONOTONIC . +Use when you need very fast, but not fine-grained timestamps. +Requires per-architecture support, +and probably also architecture support for this flag in the +.BR vdso (7). +.TP +.BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)" +.\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz +Similar to +.BR CLOCK_MONOTONIC , +but provides access to a raw hardware-based time +that is not subject to NTP adjustments or +the incremental adjustments performed by +.BR adjtime (3). +.TP +.BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)" +.\" commit 7fdd7f89006dd5a4c702fa0ce0c272345fa44ae0 +.\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0 +Identical to +.BR CLOCK_MONOTONIC , +except it also includes any time that the system is suspended. +This allows applications to get a suspend-aware monotonic clock +without having to deal with the complications of +.BR CLOCK_REALTIME , +which may have discontinuities if the time is changed using +.BR settimeofday (2) +or similar. +.TP +.BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)" +Per-process CPU-time clock +(measures CPU time consumed by all threads in the process). +.TP +.BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" +Thread-specific CPU-time clock. +.SH RETURN VALUE +.BR clock_gettime (), +.BR clock_settime (), +and +.BR clock_getres () +return 0 for success, or \-1 for failure (in which case +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EFAULT +.I tp +points outside the accessible address space. +.TP +.B EINVAL +The +.I clk_id +specified is not supported on this system. +.\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID +.\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be +.\" EPERM. +.TP +.B EPERM +.BR clock_settime () +does not have permission to set the clock indicated. +.SH VERSIONS +These system calls first appeared in Linux 2.6. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw32 lb lb +l l l. +Interface Attribute Value +T{ +.BR clock_getres (), +.BR clock_gettime (), +.BR clock_settime () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SUSv2. +.SH AVAILABILITY +On POSIX systems on which these functions are available, the symbol +.B _POSIX_TIMERS +is defined in \fI\fP to a value greater than 0. +The symbols +.BR _POSIX_MONOTONIC_CLOCK , +.BR _POSIX_CPUTIME , +.B _POSIX_THREAD_CPUTIME +indicate that +.BR CLOCK_MONOTONIC , +.BR CLOCK_PROCESS_CPUTIME_ID , +.B CLOCK_THREAD_CPUTIME_ID +are available. +(See also +.BR sysconf (3).) +.SH NOTES +POSIX.1 specifies the following: +.RS +.PP +Setting the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime () +shall have no effect on threads that are blocked waiting for a relative time +service based upon this clock, including the +.BR nanosleep () +function; nor on the expiration of relative timers based upon this clock. +Consequently, these time services shall expire when the requested relative +interval elapses, independently of the new or old value of the clock. +.RE +.\" +.SS C library/kernel differences +On some architectures, an implementation of +.BR clock_gettime () +is provided in the +.BR vdso (7). +.\" +.SS Historical note for SMP systems +Before Linux added kernel support for +.B CLOCK_PROCESS_CPUTIME_ID +and +.BR CLOCK_THREAD_CPUTIME_ID , +glibc implemented these clocks on many platforms using timer +registers from the CPUs +(TSC on i386, AR.ITC on Itanium). +These registers may differ between CPUs and as a consequence +these clocks may return +.B bogus results +if a process is migrated to another CPU. +.PP +If the CPUs in an SMP system have different clock sources, then +there is no way to maintain a correlation between the timer registers since +each CPU will run at a slightly different frequency. +If that is the case, then +.I clock_getcpuclockid(0) +will return +.B ENOENT +to signify this condition. +The two clocks will then be useful only if it +can be ensured that a process stays on a certain CPU. +.PP +The processors in an SMP system do not start all at exactly the same +time and therefore the timer registers are typically running at an offset. +Some architectures include code that attempts to limit these offsets on bootup. +However, the code cannot guarantee to accurately tune the offsets. +Glibc contains no provisions to deal with these offsets (unlike the Linux +Kernel). +Typically these offsets are small and therefore the effects may be +negligible in most cases. +.PP +Since glibc 2.4, +the wrapper functions for the system calls described in this page avoid +the abovementioned problems by employing the kernel implementation of +.B CLOCK_PROCESS_CPUTIME_ID +and +.BR CLOCK_THREAD_CPUTIME_ID , +on systems that provide such an implementation +(i.e., Linux 2.6.12 and later). +.SH BUGS +According to POSIX.1-2001, a process with "appropriate privileges" may set the +.B CLOCK_PROCESS_CPUTIME_ID +and +.B CLOCK_THREAD_CPUTIME_ID +clocks using +.BR clock_settime (). +On Linux, these clocks are not settable +(i.e., no process has "appropriate privileges"). +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=11972 +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR settimeofday (2), +.BR time (2), +.BR adjtime (3), +.BR clock_getcpuclockid (3), +.BR ctime (3), +.BR ftime (3), +.BR pthread_getcpuclockid (3), +.BR sysconf (3), +.BR time (7), +.BR vdso (7), +.BR hwclock (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/clock_gettime.2 b/man2/clock_gettime.2 new file mode 100644 index 0000000..5a599b4 --- /dev/null +++ b/man2/clock_gettime.2 @@ -0,0 +1 @@ +.so man2/clock_getres.2 diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2 new file mode 100644 index 0000000..d0d7b56 --- /dev/null +++ b/man2/clock_nanosleep.2 @@ -0,0 +1,270 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH CLOCK_NANOSLEEP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +clock_nanosleep \- high-resolution sleep with specifiable clock +.SH SYNOPSIS +.B #include +.nf +.PP +.BI "int clock_nanosleep(clockid_t " clock_id ", int " flags , +.BI " const struct timespec *" request , +.BI " struct timespec *" remain ); +.fi +.PP +Link with \fI\-lrt\fP (only for glibc versions before 2.17). +.PP +.ad l +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR clock_nanosleep (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +Like +.BR nanosleep (2), +.BR clock_nanosleep () +allows the calling thread to sleep for an interval specified +with nanosecond precision. +It differs in allowing the caller to select the clock against +which the sleep interval is to be measured, +and in allowing the sleep interval to be specified as +either an absolute or a relative value. +.PP +The time values passed to and returned by this call are specified using +.I timespec +structures, defined as follows: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds [0 .. 999999999] */ +}; +.EE +.in +.PP +The +.I clock_id +argument specifies the clock against which the sleep interval +is to be measured. +This argument can have one of the following values: +.TP 17 +.BR CLOCK_REALTIME +A settable system-wide real-time clock. +.TP +.BR CLOCK_MONOTONIC +A nonsettable, monotonically increasing clock that measures time +since some unspecified point in the past that does not change after +system startup. +.\" On Linux this clock measures time since boot. +.TP +.BR CLOCK_PROCESS_CPUTIME_ID +A settable per-process clock that measures CPU time consumed +by all threads in the process. +.\" There is some trickery between glibc and the kernel +.\" to deal with the CLOCK_PROCESS_CPUTIME_ID case. +.PP +See +.BR clock_getres (2) +for further details on these clocks. +In addition, the CPU clock IDs returned by +.BR clock_getcpuclockid (3) +and +.BR pthread_getcpuclockid (3) +can also be passed in +.IR clock_id . +.PP +If +.I flags +is 0, then the value specified in +.I request +is interpreted as an interval relative to the current +value of the clock specified by +.IR clock_id . +.PP +If +.I flags +is +.BR TIMER_ABSTIME , +then +.I request +is interpreted as an absolute time as measured by the clock, +.IR clock_id . +If +.I request +is less than or equal to the current value of the clock, +then +.BR clock_nanosleep () +returns immediately without suspending the calling thread. +.PP +.BR clock_nanosleep () +suspends the execution of the calling thread +until either at least the time specified by +.IR request +has elapsed, +or a signal is delivered that causes a signal handler to be called or +that terminates the process. +.PP +If the call is interrupted by a signal handler, +.BR clock_nanosleep () +fails with the error +.BR EINTR . +In addition, if +.I remain +is not NULL, and +.I flags +was not +.BR TIMER_ABSTIME , +it returns the remaining unslept time in +.IR remain . +This value can then be used to call +.BR clock_nanosleep () +again and complete a (relative) sleep. +.SH RETURN VALUE +On successfully sleeping for the requested interval, +.BR clock_nanosleep () +returns 0. +If the call is interrupted by a signal handler or encounters an error, +then it returns one of the positive error number listed in ERRORS. +.SH ERRORS +.TP +.B EFAULT +.I request +or +.I remain +specified an invalid address. +.TP +.B EINTR +The sleep was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The value in the +.I tv_nsec +field was not in the range 0 to 999999999 or +.I tv_sec +was negative. +.TP +.B EINVAL +.I clock_id +was invalid. +.RB ( CLOCK_THREAD_CPUTIME_ID +is not a permitted value for +.IR clock_id .) +.SH VERSIONS +The +.BR clock_nanosleep () +system call first appeared in Linux 2.6. +Support is available in glibc since version 2.1. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +If the interval specified in +.I request +is not an exact multiple of the granularity underlying clock (see +.BR time (7)), +then the interval will be rounded up to the next multiple. +Furthermore, after the sleep completes, there may still be a delay before +the CPU becomes free to once again execute the calling thread. +.PP +Using an absolute timer is useful for preventing +timer drift problems of the type described in +.BR nanosleep (2). +(Such problems are exacerbated in programs that try to restart +a relative sleep that is repeatedly interrupted by signals.) +To perform a relative sleep that avoids these problems, call +.BR clock_gettime (2) +for the desired clock, +add the desired interval to the returned time value, +and then call +.BR clock_nanosleep () +with the +.B TIMER_ABSTIME +flag. +.PP +.BR clock_nanosleep () +is never restarted after being interrupted by a signal handler, +regardless of the use of the +.BR sigaction (2) +.B SA_RESTART +flag. +.PP +The +.I remain +argument is unused, and unnecessary, when +.I flags +is +.BR TIMER_ABSTIME . +(An absolute sleep can be restarted using the same +.I request +argument.) +.PP +POSIX.1 specifies that +.BR clock_nanosleep () +has no effect on signals dispositions or the signal mask. +.PP +POSIX.1 specifies that after changing the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2), +the new clock value shall be used to determine the time +at which a thread blocked on an absolute +.BR clock_nanosleep () +will wake up; +if the new clock value falls past the end of the sleep interval, then the +.BR clock_nanosleep () +call will return immediately. +.PP +POSIX.1 specifies that +changing the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2) +shall have no effect on a thread that is blocked on a relative +.BR clock_nanosleep (). +.SH SEE ALSO +.BR clock_getres (2), +.BR nanosleep (2), +.BR restart_syscall (2), +.BR timer_create (2), +.BR sleep (3), +.BR usleep (3), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/clock_settime.2 b/man2/clock_settime.2 new file mode 100644 index 0000000..5a599b4 --- /dev/null +++ b/man2/clock_settime.2 @@ -0,0 +1 @@ +.so man2/clock_getres.2 diff --git a/man2/clone.2 b/man2/clone.2 new file mode 100644 index 0000000..20ead6d --- /dev/null +++ b/man2/clone.2 @@ -0,0 +1,1377 @@ +.\" Copyright (c) 1992 Drew Eckhardt , March 28, 1992 +.\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005, 2013 +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" May be distributed under the GNU General Public License. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 24 Jul 1993 by Rik Faith +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" New man page (copied from 'fork.2'). +.\" Modified 10 June 1995 by Andries Brouwer +.\" Modified 25 April 1998 by Xavier Leroy +.\" Modified 26 Jun 2001 by Michael Kerrisk +.\" Mostly upgraded to 2.4.x +.\" Added prototype for sys_clone() plus description +.\" Added CLONE_THREAD with a brief description of thread groups +.\" Added CLONE_PARENT and revised entire page remove ambiguity +.\" between "calling process" and "parent process" +.\" Added CLONE_PTRACE and CLONE_VFORK +.\" Added EPERM and EINVAL error codes +.\" Renamed "__clone" to "clone" (which is the prototype in ) +.\" various other minor tidy ups and clarifications. +.\" Modified 26 Jun 2001 by Michael Kerrisk +.\" Updated notes for 2.4.7+ behavior of CLONE_THREAD +.\" Modified 15 Oct 2002 by Michael Kerrisk +.\" Added description for CLONE_NEWNS, which was added in 2.4.19 +.\" Slightly rephrased, aeb. +.\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb. +.\" Modified 1 Jan 2004 - various updates, aeb +.\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb. +.\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid() +.\" wrapper under BUGS. +.\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED. +.\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD. +.\" 2008-11-18, mtk, order CLONE_* flags alphabetically +.\" 2008-11-18, mtk, document CLONE_NEWPID +.\" 2008-11-19, mtk, document CLONE_NEWUTS +.\" 2008-11-19, mtk, document CLONE_NEWIPC +.\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO +.\" +.TH CLONE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +clone, __clone2 \- create a child process +.SH SYNOPSIS +.nf +/* Prototype for the glibc wrapper function */ +.PP +.B #define _GNU_SOURCE +.B #include +.PP +.BI "int clone(int (*" "fn" ")(void *), void *" child_stack , +.BI " int " flags ", void *" "arg" ", ... " +.BI " /* pid_t *" ptid ", void *" newtls \ +", pid_t *" ctid " */ );" +.PP +/* For the prototype of the raw system call, see NOTES */ +.fi +.SH DESCRIPTION +.BR clone () +creates a new process, in a manner similar to +.BR fork (2). +.PP +This page describes both the glibc +.BR clone () +wrapper function and the underlying system call on which it is based. +The main text describes the wrapper function; +the differences for the raw system call +are described toward the end of this page. +.PP +Unlike +.BR fork (2), +.BR clone () +allows the child process to share parts of its execution context with +the calling process, such as the virtual address space, the table of file +descriptors, and the table of signal handlers. +(Note that on this manual +page, "calling process" normally corresponds to "parent process". +But see the description of +.B CLONE_PARENT +below.) +.PP +One use of +.BR clone () +is to implement threads: multiple flows of control in a program that +run concurrently in a shared address space. +.PP +When the child process is created with +.BR clone (), +it commences execution by calling the function pointed to by the argument +.IR fn . +(This differs from +.BR fork (2), +where execution continues in the child from the point +of the +.BR fork (2) +call.) +The +.I arg +argument is passed as the argument of the function +.IR fn . +.PP +When the +.IR fn ( arg ) +function returns, the child process terminates. +The integer returned by +.I fn +is the exit status for the child process. +The child process may also terminate explicitly by calling +.BR exit (2) +or after receiving a fatal signal. +.PP +The +.I child_stack +argument specifies the location of the stack used by the child process. +Since the child and calling process may share memory, +it is not possible for the child process to execute in the +same stack as the calling process. +The calling process must therefore +set up memory space for the child stack and pass a pointer to this +space to +.BR clone (). +Stacks grow downward on all processors that run Linux +(except the HP PA processors), so +.I child_stack +usually points to the topmost address of the memory space set up for +the child stack. +.PP +The low byte of +.I flags +contains the number of the +.I "termination signal" +sent to the parent when the child dies. +If this signal is specified as anything other than +.BR SIGCHLD , +then the parent process must specify the +.B __WALL +or +.B __WCLONE +options when waiting for the child with +.BR wait (2). +If no signal is specified, then the parent process is not signaled +when the child terminates. +.PP +.I flags +may also be bitwise-ORed with zero or more of the following constants, +in order to specify what is shared between the calling process +and the child process: +.TP +.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" +Clear (zero) the child thread ID at the location +.I ctid +in child memory when the child exits, and do a wakeup on the futex +at that address. +The address involved may be changed by the +.BR set_tid_address (2) +system call. +This is used by threading libraries. +.TP +.BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" +Store the child thread ID at the location +.I ctid +in the child's memory. +The store operation completes before +.BR clone () +returns control to user space. +.TP +.BR CLONE_FILES " (since Linux 2.0)" +If +.B CLONE_FILES +is set, the calling process and the child process share the same file +descriptor table. +Any file descriptor created by the calling process or by the child +process is also valid in the other process. +Similarly, if one of the processes closes a file descriptor, +or changes its associated flags (using the +.BR fcntl (2) +.B F_SETFD +operation), the other process is also affected. +If a process sharing a file descriptor table calls +.BR execve (2), +its file descriptor table is duplicated (unshared). +.IP +If +.B CLONE_FILES +is not set, the child process inherits a copy of all file descriptors +opened in the calling process at the time of +.BR clone (). +Subsequent operations that open or close file descriptors, +or change file descriptor flags, +performed by either the calling +process or the child process do not affect the other process. +Note, however, +that the duplicated file descriptors in the child refer to the same open file +descriptions as the corresponding file descriptors in the calling process, +and thus share file offsets and file status flags (see +.BR open (2)). +.TP +.BR CLONE_FS " (since Linux 2.0)" +If +.B CLONE_FS +is set, the caller and the child process share the same filesystem +information. +This includes the root of the filesystem, the current +working directory, and the umask. +Any call to +.BR chroot (2), +.BR chdir (2), +or +.BR umask (2) +performed by the calling process or the child process also affects the +other process. +.IP +If +.B CLONE_FS +is not set, the child process works on a copy of the filesystem +information of the calling process at the time of the +.BR clone () +call. +Calls to +.BR chroot (2), +.BR chdir (2), +or +.BR umask (2) +performed later by one of the processes do not affect the other process. +.TP +.BR CLONE_IO " (since Linux 2.6.25)" +If +.B CLONE_IO +is set, then the new process shares an I/O context with +the calling process. +If this flag is not set, then (as with +.BR fork (2)) +the new process has its own I/O context. +.IP +.\" The following based on text from Jens Axboe +The I/O context is the I/O scope of the disk scheduler (i.e., +what the I/O scheduler uses to model scheduling of a process's I/O). +If processes share the same I/O context, +they are treated as one by the I/O scheduler. +As a consequence, they get to share disk time. +For some I/O schedulers, +.\" the anticipatory and CFQ scheduler +if two processes share an I/O context, +they will be allowed to interleave their disk access. +If several threads are doing I/O on behalf of the same process +.RB ( aio_read (3), +for instance), they should employ +.BR CLONE_IO +to get better I/O performance. +.\" with CFQ and AS. +.IP +If the kernel is not configured with the +.B CONFIG_BLOCK +option, this flag is a no-op. +.TP +.BR CLONE_NEWCGROUP " (since Linux 4.6)" +Create the process in a new cgroup namespace. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same cgroup namespaces as the calling process. +This flag is intended for the implementation of containers. +.IP +For further information on cgroup namespaces, see +.BR cgroup_namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWCGROUP . +.\" +.TP +.BR CLONE_NEWIPC " (since Linux 2.6.19)" +If +.B CLONE_NEWIPC +is set, then create the process in a new IPC namespace. +If this flag is not set, then (as with +.BR fork (2)), +the process is created in the same IPC namespace as +the calling process. +This flag is intended for the implementation of containers. +.IP +An IPC namespace provides an isolated view of System\ V IPC objects (see +.BR svipc (7)) +and (since Linux 2.6.30) +.\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f +.\" https://lwn.net/Articles/312232/ +POSIX message queues +(see +.BR mq_overview (7)). +The common characteristic of these IPC mechanisms is that IPC +objects are identified by mechanisms other than filesystem +pathnames. +.IP +Objects created in an IPC namespace are visible to all other processes +that are members of that namespace, +but are not visible to processes in other IPC namespaces. +.IP +When an IPC namespace is destroyed +(i.e., when the last process that is a member of the namespace terminates), +all IPC objects in the namespace are automatically destroyed. +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWIPC . +This flag can't be specified in conjunction with +.BR CLONE_SYSVSEM . +.IP +For further information on IPC namespaces, see +.BR namespaces (7). +.TP +.BR CLONE_NEWNET " (since Linux 2.6.24)" +(The implementation of this flag was completed only +by about kernel version 2.6.29.) +.IP +If +.B CLONE_NEWNET +is set, then create the process in a new network namespace. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same network namespace as +the calling process. +This flag is intended for the implementation of containers. +.IP +A network namespace provides an isolated view of the networking stack +(network device interfaces, IPv4 and IPv6 protocol stacks, +IP routing tables, firewall rules, the +.I /proc/net +and +.I /sys/class/net +directory trees, sockets, etc.). +A physical network device can live in exactly one +network namespace. +A virtual network +.RB ( veth (4)) +device pair provides a pipe-like abstraction +that can be used to create tunnels between network namespaces, +and can be used to create a bridge to a physical network device +in another namespace. +.IP +When a network namespace is freed +(i.e., when the last process in the namespace terminates), +its physical network devices are moved back to the +initial network namespace (not to the parent of the process). +For further information on network namespaces, see +.BR namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWNET . +.TP +.BR CLONE_NEWNS " (since Linux 2.4.19)" +If +.B CLONE_NEWNS +is set, the cloned child is started in a new mount namespace, +initialized with a copy of the namespace of the parent. +If +.B CLONE_NEWNS +is not set, the child lives in the same mount +namespace as the parent. +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWNS . +It is not permitted to specify both +.B CLONE_NEWNS +and +.B CLONE_FS +.\" See https://lwn.net/Articles/543273/ +in the same +.BR clone () +call. +.IP +For further information on mount namespaces, see +.BR namespaces (7) +and +.BR mount_namespaces (7). +.TP +.BR CLONE_NEWPID " (since Linux 2.6.24)" +.\" This explanation draws a lot of details from +.\" http://lwn.net/Articles/259217/ +.\" Authors: Pavel Emelyanov +.\" and Kir Kolyshkin +.\" +.\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264 +.\" Author: Pavel Emelyanov +If +.B CLONE_NEWPID +is set, then create the process in a new PID namespace. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same PID namespace as +the calling process. +This flag is intended for the implementation of containers. +.IP +For further information on PID namespaces, see +.BR namespaces (7) +and +.BR pid_namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWPID . +This flag can't be specified in conjunction with +.BR CLONE_THREAD +or +.BR CLONE_PARENT . +.TP +.BR CLONE_NEWUSER +(This flag first became meaningful for +.BR clone () +in Linux 2.6.23, +the current +.BR clone () +semantics were merged in Linux 3.5, +and the final pieces to make the user namespaces completely usable were +merged in Linux 3.8.) +.IP +If +.B CLONE_NEWUSER +is set, then create the process in a new user namespace. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same user namespace as the calling process. +.IP +Before Linux 3.8, use of +.BR CLONE_NEWUSER +required that the caller have three capabilities: +.BR CAP_SYS_ADMIN , +.BR CAP_SETUID , +and +.BR CAP_SETGID . +.\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed +Starting with Linux 3.8, +no privileges are needed to create a user namespace. +.IP +This flag can't be specified in conjunction with +.BR CLONE_THREAD +or +.BR CLONE_PARENT . +For security reasons, +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +.\" https://lwn.net/Articles/543273/ +.\" The fix actually went into 3.9 and into 3.8.3. However, user namespaces +.\" were, for practical purposes, unusable in earlier 3.8.x because of the +.\" various filesystems that didn't support userns. +.BR CLONE_NEWUSER +cannot be specified in conjunction with +.BR CLONE_FS . +.IP +For further information on user namespaces, see +.BR namespaces (7) +and +.BR user_namespaces (7). +.TP +.BR CLONE_NEWUTS " (since Linux 2.6.19)" +If +.B CLONE_NEWUTS +is set, then create the process in a new UTS namespace, +whose identifiers are initialized by duplicating the identifiers +from the UTS namespace of the calling process. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same UTS namespace as +the calling process. +This flag is intended for the implementation of containers. +.IP +A UTS namespace is the set of identifiers returned by +.BR uname (2); +among these, the domain name and the hostname can be modified by +.BR setdomainname (2) +and +.BR sethostname (2), +respectively. +Changes made to the identifiers in a UTS namespace +are visible to all other processes in the same namespace, +but are not visible to processes in other UTS namespaces. +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWUTS . +.IP +For further information on UTS namespaces, see +.BR namespaces (7). +.TP +.BR CLONE_PARENT " (since Linux 2.3.12)" +If +.B CLONE_PARENT +is set, then the parent of the new child (as returned by +.BR getppid (2)) +will be the same as that of the calling process. +.IP +If +.B CLONE_PARENT +is not set, then (as with +.BR fork (2)) +the child's parent is the calling process. +.IP +Note that it is the parent process, as returned by +.BR getppid (2), +which is signaled when the child terminates, so that +if +.B CLONE_PARENT +is set, then the parent of the calling process, rather than the +calling process itself, will be signaled. +.TP +.BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" +Store the child thread ID at the location +.I ptid +in the parent's memory. +(In Linux 2.5.32-2.5.48 there was a flag +.B CLONE_SETTID +that did this.) +The store operation completes before +.BR clone () +returns control to user space. +.TP +.BR CLONE_PID " (Linux 2.0 to 2.5.15)" +If +.B CLONE_PID +is set, the child process is created with the same process ID as +the calling process. +This is good for hacking the system, but otherwise +of not much use. +From Linux 2.3.21 onward, this flag could be +specified only by the system boot process (PID 0). +The flag disappeared completely from the kernel sources in Linux 2.5.16. +Since then, the kernel silently ignores this bit if it is specified in +.IR flags . +.TP +.BR CLONE_PTRACE " (since Linux 2.2)" +If +.B CLONE_PTRACE +is specified, and the calling process is being traced, +then trace the child also (see +.BR ptrace (2)). +.TP +.BR CLONE_SETTLS " (since Linux 2.5.32)" +The TLS (Thread Local Storage) descriptor is set to +.IR newtls . +.IP +The interpretation of +.I newtls +and the resulting effect is architecture dependent. +On x86, +.I newtls +is interpreted as a +.IR "struct user_desc\ *" +(see +.BR set_thread_area (2)). +On x86-64 it is the new value to be set for the %fs base register +(see the +.B ARCH_SET_FS +argument to +.BR arch_prctl (2)). +On architectures with a dedicated TLS register, it is the new value +of that register. +.TP +.BR CLONE_SIGHAND " (since Linux 2.0)" +If +.B CLONE_SIGHAND +is set, the calling process and the child process share the same table of +signal handlers. +If the calling process or child process calls +.BR sigaction (2) +to change the behavior associated with a signal, the behavior is +changed in the other process as well. +However, the calling process and child +processes still have distinct signal masks and sets of pending +signals. +So, one of them may block or unblock signals using +.BR sigprocmask (2) +without affecting the other process. +.IP +If +.B CLONE_SIGHAND +is not set, the child process inherits a copy of the signal handlers +of the calling process at the time +.BR clone () +is called. +Calls to +.BR sigaction (2) +performed later by one of the processes have no effect on the other +process. +.IP +Since Linux 2.6.0-test6, +.I flags +must also include +.B CLONE_VM +if +.B CLONE_SIGHAND +is specified +.TP +.BR CLONE_STOPPED " (since Linux 2.6.0-test2)" +If +.B CLONE_STOPPED +is set, then the child is initially stopped (as though it was sent a +.B SIGSTOP +signal), and must be resumed by sending it a +.B SIGCONT +signal. +.IP +This flag was +.I deprecated +from Linux 2.6.25 onward, +and was +.I removed +altogether in Linux 2.6.38. +Since then, the kernel silently ignores it without error. +.\" glibc 2.8 removed this defn from bits/sched.h +Starting with Linux 4.6, the same bit was reused for the +.BR CLONE_NEWCGROUP +flag. +.TP +.BR CLONE_SYSVSEM " (since Linux 2.5.10)" +If +.B CLONE_SYSVSEM +is set, then the child and the calling process share +a single list of System V semaphore adjustment +.RI ( semadj ) +values (see +.BR semop (2)). +In this case, the shared list accumulates +.I semadj +values across all processes sharing the list, +and semaphore adjustments are performed only when the last process +that is sharing the list terminates (or ceases sharing the list using +.BR unshare (2)). +If this flag is not set, then the child has a separate +.I semadj +list that is initially empty. +.TP +.BR CLONE_THREAD " (since Linux 2.4.0-test8)" +If +.B CLONE_THREAD +is set, the child is placed in the same thread group as the calling process. +To make the remainder of the discussion of +.B CLONE_THREAD +more readable, the term "thread" is used to refer to the +processes within a thread group. +.IP +Thread groups were a feature added in Linux 2.4 to support the +POSIX threads notion of a set of threads that share a single PID. +Internally, this shared PID is the so-called +thread group identifier (TGID) for the thread group. +Since Linux 2.4, calls to +.BR getpid (2) +return the TGID of the caller. +.IP +The threads within a group can be distinguished by their (system-wide) +unique thread IDs (TID). +A new thread's TID is available as the function result +returned to the caller of +.BR clone (), +and a thread can obtain +its own TID using +.BR gettid (2). +.IP +When a call is made to +.BR clone () +without specifying +.BR CLONE_THREAD , +then the resulting thread is placed in a new thread group +whose TGID is the same as the thread's TID. +This thread is the +.I leader +of the new thread group. +.IP +A new thread created with +.B CLONE_THREAD +has the same parent process as the caller of +.BR clone () +(i.e., like +.BR CLONE_PARENT ), +so that calls to +.BR getppid (2) +return the same value for all of the threads in a thread group. +When a +.B CLONE_THREAD +thread terminates, the thread that created it using +.BR clone () +is not sent a +.B SIGCHLD +(or other termination) signal; +nor can the status of such a thread be obtained +using +.BR wait (2). +(The thread is said to be +.IR detached .) +.IP +After all of the threads in a thread group terminate +the parent process of the thread group is sent a +.B SIGCHLD +(or other termination) signal. +.IP +If any of the threads in a thread group performs an +.BR execve (2), +then all threads other than the thread group leader are terminated, +and the new program is executed in the thread group leader. +.IP +If one of the threads in a thread group creates a child using +.BR fork (2), +then any thread in the group can +.BR wait (2) +for that child. +.IP +Since Linux 2.5.35, +.I flags +must also include +.B CLONE_SIGHAND +if +.B CLONE_THREAD +is specified +(and note that, since Linux 2.6.0-test6, +.BR CLONE_SIGHAND +also requires +.BR CLONE_VM +to be included). +.IP +Signals may be sent to a thread group as a whole (i.e., a TGID) using +.BR kill (2), +or to a specific thread (i.e., TID) using +.BR tgkill (2). +.IP +Signal dispositions and actions are process-wide: +if an unhandled signal is delivered to a thread, then +it will affect (terminate, stop, continue, be ignored in) +all members of the thread group. +.IP +Each thread has its own signal mask, as set by +.BR sigprocmask (2), +but signals can be pending either: for the whole process +(i.e., deliverable to any member of the thread group), +when sent with +.BR kill (2); +or for an individual thread, when sent with +.BR tgkill (2). +A call to +.BR sigpending (2) +returns a signal set that is the union of the signals pending for the +whole process and the signals that are pending for the calling thread. +.IP +If +.BR kill (2) +is used to send a signal to a thread group, +and the thread group has installed a handler for the signal, then +the handler will be invoked in exactly one, arbitrarily selected +member of the thread group that has not blocked the signal. +If multiple threads in a group are waiting to accept the same signal using +.BR sigwaitinfo (2), +the kernel will arbitrarily select one of these threads +to receive a signal sent using +.BR kill (2). +.TP +.BR CLONE_UNTRACED " (since Linux 2.5.46)" +If +.B CLONE_UNTRACED +is specified, then a tracing process cannot force +.B CLONE_PTRACE +on this child process. +.TP +.BR CLONE_VFORK " (since Linux 2.2)" +If +.B CLONE_VFORK +is set, the execution of the calling process is suspended +until the child releases its virtual memory +resources via a call to +.BR execve (2) +or +.BR _exit (2) +(as with +.BR vfork (2)). +.IP +If +.B CLONE_VFORK +is not set, then both the calling process and the child are schedulable +after the call, and an application should not rely on execution occurring +in any particular order. +.TP +.BR CLONE_VM " (since Linux 2.0)" +If +.B CLONE_VM +is set, the calling process and the child process run in the same memory +space. +In particular, memory writes performed by the calling process +or by the child process are also visible in the other process. +Moreover, any memory mapping or unmapping performed with +.BR mmap (2) +or +.BR munmap (2) +by the child or calling process also affects the other process. +.IP +If +.B CLONE_VM +is not set, the child process runs in a separate copy of the memory +space of the calling process at the time of +.BR clone (). +Memory writes or file mappings/unmappings performed by one of the +processes do not affect the other, as with +.BR fork (2). +.SH NOTES +Note that the glibc +.BR clone () +wrapper function makes some changes +in the memory pointed to by +.I child_stack +(changes required to set the stack up correctly for the child) +.I before +invoking the +.BR clone () +system call. +So, in cases where +.BR clone () +is used to recursively create children, +do not use the buffer employed for the parent's stack +as the stack of the child. +.\" +.SS C library/kernel differences +The raw +.BR clone () +system call corresponds more closely to +.BR fork (2) +in that execution in the child continues from the point of the +call. +As such, the +.I fn +and +.I arg +arguments of the +.BR clone () +wrapper function are omitted. +.PP +Another difference for the raw +.BR clone () +system call is that the +.I child_stack +argument may be zero, +in which case the child uses a duplicate of the parent's stack. +(Copy-on-write semantics ensure that the child gets separate copies +of stack pages when either process modifies the stack.) +In this case, for correct operation, the +.B CLONE_VM +option should not be specified. +(If the child +.I shares +the parent's memory because of the use of the +.BR CLONE_VM +flag, +then no copy-on-write duplication occurs and chaos is likely to result.) +.PP +The order of the arguments also differs in the raw system call, +and there are variations in the arguments across architectures, +as detailed in the following paragraphs. +.PP +The raw system call interface on x86-64 and some other architectures +(including sh, tile, and alpha) is roughly: +.PP +.in +4 +.EX +.BI "long clone(unsigned long " flags ", void *" child_stack , +.BI " int *" ptid ", int *" ctid , +.BI " unsigned long " newtls ); +.EE +.in +.PP +On x86-32, and several other common architectures +(including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, +and MIPS), +.\" CONFIG_CLONE_BACKWARDS +the order of the last two arguments is reversed: +.PP +.in +4 +.EX +.BI "long clone(unsigned long " flags ", void *" child_stack , +.BI " int *" ptid ", unsigned long " newtls , +.BI " int *" ctid ); +.EE +.in +.PP +On the cris and s390 architectures, +.\" CONFIG_CLONE_BACKWARDS2 +the order of the first two arguments is reversed: +.PP +.in +4 +.EX +.BI "long clone(void *" child_stack ", unsigned long " flags , +.BI " int *" ptid ", int *" ctid , +.BI " unsigned long " newtls ); +.EE +.in +.PP +On the microblaze architecture, +.\" CONFIG_CLONE_BACKWARDS3 +an additional argument is supplied: +.PP +.in +4 +.EX +.BI "long clone(unsigned long " flags ", void *" child_stack , +.BI " int " stack_size , "\fR /* Size of stack */" +.BI " int *" ptid ", int *" ctid , +.BI " unsigned long " newtls ); +.EE +.in +.\" +.SS blackfin, m68k, and sparc +.\" Mike Frysinger noted in a 2013 mail: +.\" these arches don't define __ARCH_WANT_SYS_CLONE: +.\" blackfin ia64 m68k sparc +The argument-passing conventions on +blackfin, m68k, and sparc are different from the descriptions above. +For details, see the kernel (and glibc) source. +.SS ia64 +On ia64, a different interface is used: +.PP +.nf +.BI "int __clone2(int (*" "fn" ")(void *), " +.BI " void *" child_stack_base ", size_t " stack_size , +.BI " int " flags ", void *" "arg" ", ... " +.BI " /* pid_t *" ptid ", struct user_desc *" tls \ +", pid_t *" ctid " */ );" +.fi +.PP +The prototype shown above is for the glibc wrapper function; +the raw system call interface has no +.I fn +or +.I arg +argument, and changes the order of the arguments so that +.I flags +is the first argument, and +.I tls +is the last argument. +.PP +.BR __clone2 () +operates in the same way as +.BR clone (), +except that +.I child_stack_base +points to the lowest address of the child's stack area, +and +.I stack_size +specifies the size of the stack pointed to by +.IR child_stack_base . +.SS Linux 2.4 and earlier +In Linux 2.4 and earlier, +.BR clone () +does not take arguments +.IR ptid , +.IR tls , +and +.IR ctid . +.SH RETURN VALUE +.\" gettid(2) returns current->pid; +.\" getpid(2) returns current->tgid; +On success, the thread ID of the child process is returned +in the caller's thread of execution. +On failure, \-1 is returned +in the caller's context, no child process will be created, and +.I errno +will be set appropriately. +.SH ERRORS +.TP +.B EAGAIN +Too many processes are already running; see +.BR fork (2). +.TP +.B EINVAL +.B CLONE_SIGHAND +was specified, but +.B CLONE_VM +was not. +(Since Linux 2.6.0-test6.) +.TP +.B EINVAL +.B CLONE_THREAD +was specified, but +.B CLONE_SIGHAND +was not. +(Since Linux 2.5.35.) +.\" .TP +.\" .B EINVAL +.\" Precisely one of +.\" .B CLONE_DETACHED +.\" and +.\" .B CLONE_THREAD +.\" was specified. +.\" (Since Linux 2.6.0-test6.) +.TP +.B EINVAL +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +Both +.B CLONE_FS +and +.B CLONE_NEWNS +were specified in +.IR flags . +.TP +.BR EINVAL " (since Linux 3.9)" +Both +.B CLONE_NEWUSER +and +.B CLONE_FS +were specified in +.IR flags . +.TP +.B EINVAL +Both +.B CLONE_NEWIPC +and +.B CLONE_SYSVSEM +were specified in +.IR flags . +.TP +.B EINVAL +One (or both) of +.BR CLONE_NEWPID +or +.BR CLONE_NEWUSER +and one (or both) of +.BR CLONE_THREAD +or +.BR CLONE_PARENT +were specified in +.IR flags . +.TP +.B EINVAL +Returned by the glibc +.BR clone () +wrapper function when +.IR fn +or +.IR child_stack +is specified as NULL. +.TP +.B EINVAL +.BR CLONE_NEWIPC +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_SYSVIPC +and +.BR CONFIG_IPC_NS +options. +.TP +.B EINVAL +.BR CLONE_NEWNET +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_NET_NS +option. +.TP +.B EINVAL +.BR CLONE_NEWPID +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_PID_NS +option. +.TP +.B EINVAL +.BR CLONE_NEWUTS +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_UTS +option. +.TP +.B EINVAL +.I child_stack +is not aligned to a suitable boundary for this architecture. +For example, on aarch64, +.I child_stack +must be a multiple of 16. +.TP +.B ENOMEM +Cannot allocate sufficient memory to allocate a task structure for the +child, or to copy those parts of the caller's context that need to be +copied. +.TP +.BR ENOSPC " (since Linux 3.7)" +.\" commit f2302505775fd13ba93f034206f1e2a587017929 +.B CLONE_NEWPID +was specified in flags, +but the limit on the nesting depth of PID namespaces +would have been exceeded; see +.BR pid_namespaces (7). +.TP +.BR ENOSPC " (since Linux 4.9; beforehand " EUSERS ) +.B CLONE_NEWUSER +was specified in +.IR flags , +and the call would cause the limit on the number of +nested user namespaces to be exceeded. +See +.BR user_namespaces (7). +.IP +From Linux 3.11 to Linux 4.8, the error diagnosed in this case was +.BR EUSERS . +.TP +.BR ENOSPC " (since Linux 4.9)" +One of the values in +.I flags +specified the creation of a new user namespace, +but doing so would have caused the limit defined by the corresponding file in +.IR /proc/sys/user +to be exceeded. +For further details, see +.BR namespaces (7). +.TP +.B EPERM +.BR CLONE_NEWCGROUP , +.BR CLONE_NEWIPC , +.BR CLONE_NEWNET , +.BR CLONE_NEWNS , +.BR CLONE_NEWPID , +or +.BR CLONE_NEWUTS +was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP). +.TP +.B EPERM +.B CLONE_PID +was specified by a process other than process 0. +(This error occurs only on Linux 2.5.15 and earlier.) +.TP +.B EPERM +.BR CLONE_NEWUSER +was specified in +.IR flags , +but either the effective user ID or the effective group ID of the caller +does not have a mapping in the parent namespace (see +.BR user_namespaces (7)). +.TP +.BR EPERM " (since Linux 3.9)" +.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d +.B CLONE_NEWUSER +was specified in +.I flags +and the caller is in a chroot environment +.\" FIXME What is the rationale for this restriction? +(i.e., the caller's root directory does not match the root directory +of the mount namespace in which it resides). +.TP +.BR ERESTARTNOINTR " (since Linux 2.6.17)" +.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 +System call was interrupted by a signal and will be restarted. +(This can be seen only during a trace.) +.TP +.BR EUSERS " (Linux 3.11 to Linux 4.8)" +.B CLONE_NEWUSER +was specified in +.IR flags , +and the limit on the number of nested user namespaces would be exceeded. +See the discussion of the +.BR ENOSPC +error above. +.\" .SH VERSIONS +.\" There is no entry for +.\" .BR clone () +.\" in libc5. +.\" glibc2 provides +.\" .BR clone () +.\" as described in this manual page. +.SH CONFORMING TO +.BR clone () +is Linux-specific and should not be used in programs +intended to be portable. +.SH NOTES +The +.BR kcmp (2) +system call can be used to test whether two processes share various +resources such as a file descriptor table, +System V semaphore undo operations, or a virtual address space. +.PP +.PP +Handlers registered using +.BR pthread_atfork (3) +are not executed during a call to +.BR clone (). +.PP +In the Linux 2.4.x series, +.B CLONE_THREAD +generally does not make the parent of the new thread the same +as the parent of the calling process. +However, for kernel versions 2.4.7 to 2.4.18 the +.B CLONE_THREAD +flag implied the +.B CLONE_PARENT +flag (as in Linux 2.6.0 and later). +.PP +For a while there was +.B CLONE_DETACHED +(introduced in 2.5.32): +parent wants no child-exit signal. +In Linux 2.6.2, the need to give this flag together with +.B CLONE_THREAD +disappeared. +This flag is still defined, but has no effect. +.PP +On i386, +.BR clone () +should not be called through vsyscall, but directly through +.IR "int $0x80" . +.SH BUGS +GNU C library versions 2.3.4 up to and including 2.24 +contained a wrapper function for +.BR getpid (2) +that performed caching of PIDs. +This caching relied on support in the glibc wrapper for +.BR clone (), +but limitations in the implementation +meant that the cache was not up to date in some circumstances. +In particular, +if a signal was delivered to the child immediately after the +.BR clone () +call, then a call to +.BR getpid (2) +in a handler for the signal could return the PID +of the calling process ("the parent"), +if the clone wrapper had not yet had a chance to update the PID +cache in the child. +(This discussion ignores the case where the child was created using +.BR CLONE_THREAD , +when +.BR getpid (2) +.I should +return the same value in the child and in the process that called +.BR clone (), +since the caller and the child are in the same thread group. +The stale-cache problem also does not occur if the +.I flags +argument includes +.BR CLONE_VM .) +To get the truth, it was sometimes necessary to use code such as the following: +.PP +.in +4n +.EX +#include + +pid_t mypid; + +mypid = syscall(SYS_getpid); +.EE +.in +.\" See also the following bug reports +.\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 +.PP +Because of the stale-cache problem, as well as other problems noted in +.BR getpid (2), +the PID caching feature was removed in glibc 2.25. +.SH EXAMPLE +The following program demonstrates the use of +.BR clone () +to create a child process that executes in a separate UTS namespace. +The child changes the hostname in its UTS namespace. +Both parent and child then display the system hostname, +making it possible to see that the hostname +differs in the UTS namespaces of the parent and child. +For an example of the use of this program, see +.BR setns (2). +.SS Program source +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +static int /* Start function for cloned child */ +childFunc(void *arg) +{ + struct utsname uts; + + /* Change hostname in UTS namespace of child */ + + if (sethostname(arg, strlen(arg)) == \-1) + errExit("sethostname"); + + /* Retrieve and display hostname */ + + if (uname(&uts) == \-1) + errExit("uname"); + printf("uts.nodename in child: %s\\n", uts.nodename); + + /* Keep the namespace open for a while, by sleeping. + This allows some experimentation\-\-for example, another + process might join the namespace. */ + + sleep(200); + + return 0; /* Child terminates now */ +} + +#define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */ + +int +main(int argc, char *argv[]) +{ + char *stack; /* Start of stack buffer */ + char *stackTop; /* End of stack buffer */ + pid_t pid; + struct utsname uts; + + if (argc < 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_SUCCESS); + } + + /* Allocate stack for child */ + + stack = malloc(STACK_SIZE); + if (stack == NULL) + errExit("malloc"); + stackTop = stack + STACK_SIZE; /* Assume stack grows downward */ + + /* Create child that has its own UTS namespace; + child commences execution in childFunc() */ + + pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]); + if (pid == \-1) + errExit("clone"); + printf("clone() returned %ld\\n", (long) pid); + + /* Parent falls through to here */ + + sleep(1); /* Give child time to change its hostname */ + + /* Display hostname in parent\(aqs UTS namespace. This will be + different from hostname in child\(aqs UTS namespace. */ + + if (uname(&uts) == \-1) + errExit("uname"); + printf("uts.nodename in parent: %s\\n", uts.nodename); + + if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */ + errExit("waitpid"); + printf("child has terminated\\n"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fork (2), +.BR futex (2), +.BR getpid (2), +.BR gettid (2), +.BR kcmp (2), +.BR set_thread_area (2), +.BR set_tid_address (2), +.BR setns (2), +.BR tkill (2), +.BR unshare (2), +.BR wait (2), +.BR capabilities (7), +.BR namespaces (7), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/clone2.2 b/man2/clone2.2 new file mode 100644 index 0000000..68f41a5 --- /dev/null +++ b/man2/clone2.2 @@ -0,0 +1 @@ +.so man2/clone.2 diff --git a/man2/close.2 b/man2/close.2 new file mode 100644 index 0000000..bff2755 --- /dev/null +++ b/man2/close.2 @@ -0,0 +1,257 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 21 22:40:25 1993 by Rik Faith +.\" Modified Sat Feb 18 15:27:48 1995 by Michael Haardt +.\" Modified Sun Apr 14 11:40:50 1996 by Andries Brouwer : +.\" corrected description of effect on locks (thanks to +.\" Tigran Aivazian ). +.\" Modified Fri Jan 31 16:21:46 1997 by Eric S. Raymond +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" added note about close(2) not guaranteeing that data is safe on close. +.\" +.TH CLOSE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +close \- close a file descriptor +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int close(int " fd ); +.fi +.SH DESCRIPTION +.BR close () +closes a file descriptor, so that it no longer refers to any file and +may be reused. +Any record locks (see +.BR fcntl (2)) +held on the file it was associated with, +and owned by the process, are removed (regardless of the file +descriptor that was used to obtain the lock). +.PP +If +.I fd +is the last file descriptor referring to the underlying +open file description (see +.BR open (2)), +the resources associated with the open file description are freed; +if the file descriptor was the last reference to a file which has been +removed using +.BR unlink (2), +the file is deleted. +.SH RETURN VALUE +.BR close () +returns zero on success. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +isn't a valid open file descriptor. +.TP +.B EINTR +The +.BR close () +call was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An I/O error occurred. +.TP +.BR ENOSPC ", " EDQUOT +On NFS, these errors are not normally reported against the first write +which exceeds the available storage space, but instead against a +subsequent +.BR write (2), +.BR fsync (2), +or +.BR close (2). +.PP +See NOTES for a discussion of why +.BR close () +should not be retried after an error. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.\" SVr4 documents an additional ENOLINK error condition. +.SH NOTES +A successful close does not guarantee that the data has been successfully +saved to disk, as the kernel uses the buffer cache to defer writes. +Typically, filesystems do not flush buffers when a file is closed. +If you need to be sure that +the data is physically stored on the underlying disk, use +.BR fsync (2). +(It will depend on the disk hardware at this point.) +.PP +The close-on-exec file descriptor flag can be used to ensure +that a file descriptor is automatically closed upon a successful +.BR execve (2); +see +.BR fcntl (2) +for details. +.PP +It is probably unwise to close file descriptors while +they may be in use by system calls in +other threads in the same process. +Since a file descriptor may be reused, +there are some obscure race conditions +that may cause unintended side effects. +.\" Date: Tue, 4 Sep 2007 13:57:35 +0200 +.\" From: Fredrik Noring +.\" One such race involves signals and ERESTARTSYS. If a file descriptor +.\" in use by a system call is closed and then reused by e.g. an +.\" independent open() in some unrelated thread, before the original system +.\" call has restarted after ERESTARTSYS, the original system call will +.\" later restart with the reused file descriptor. This is most likely a +.\" serious programming error. +.\" +.SS Dealing with error returns from close() +A careful programmer will check the return value of +.BR close (), +since it is quite possible that errors on a previous +.BR write (2) +operation are reported only on the final +.BR close () +that releases the open file description. +Failing to check the return value when closing a file may lead to +.I silent +loss of data. +This can especially be observed with NFS and with disk quota. +.PP +Note, however, that a failure return should be used only for +diagnostic purposes (i.e., a warning to the application that there +may still be I/O pending or there may have been failed I/O) +or remedial purposes +(e.g., writing the file once more or creating a backup). +.PP +Retrying the +.BR close () +after a failure return is the wrong thing to do, +.\" The file descriptor is released early in close(); +.\" close() ==> __close_fd(): +.\" __put_unused_fd() ==> __clear_open_fd() +.\" return filp_close(file, files); +.\" +.\" The errors are returned by filp_close() after the FD has been +.\" cleared for re-use. +since this may cause a reused file descriptor +from another thread to be closed. +This can occur because the Linux kernel +.I always +releases the file descriptor early in the close +operation, freeing it for reuse; +the steps that may return an error, +.\" filp_close() +such as flushing data to the filesystem or device, +occur only later in the close operation. +.PP +Many other implementations similarly always close the file descriptor +.\" FreeBSD documents this explicitly. From the look of the source code +.\" SVR4, ancient SunOS, later Solaris, and AIX all do this. +(except in the case of +.BR EBADF , +meaning that the file descriptor was invalid) +even if they subsequently report an error on return from +.BR close (). +POSIX.1 is currently silent on this point, +but there are plans to mandate this behavior in the next major release +.\" Issue 8 +of the standard +.PP +A careful programmer who wants to know about I/O errors may precede +.BR close () +with a call to +.BR fsync (2). +.PP +The +.B EINTR +error is a somewhat special case. +Regarding the +.B EINTR +error, POSIX.1-2013 says: +.PP +.RS +If +.BR close () +is interrupted by a signal that is to be caught, it shall return \-1 with +.I errno +set to +.B EINTR +and the state of +.I fildes +is unspecified. +.RE +.PP +This permits the behavior that occurs on Linux and +many other implementations, where, +as with other errors that may be reported by +.BR close (), +the file descriptor is guaranteed to be closed. +However, it also permits another possibility: +that the implementation returns an +.B EINTR +error and keeps the file descriptor open. +(According to its documentation, HP-UX's +.BR close () +does this.) +The caller must then once more use +.BR close () +to close the file descriptor, to avoid file descriptor leaks. +This divergence in implementation behaviors provides +a difficult hurdle for portable applications, since on many implementations, +.BR close () +must not be called again after an +.B EINTR +error, and on at least one, +.BR close () +must be called again. +There are plans to address this conundrum for +the next major release of the POSIX.1 standard. +.\" FIXME . for later review when Issue 8 is one day released... +.\" POSIX proposes further changes for EINTR +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=529 +.\" +.\" FIXME . +.\" Review the following glibc bug later +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14627 +.SH SEE ALSO +.BR fcntl (2), +.BR fsync (2), +.BR open (2), +.BR shutdown (2), +.BR unlink (2), +.BR fclose (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/connect.2 b/man2/connect.2 new file mode 100644 index 0000000..22d7fbe --- /dev/null +++ b/man2/connect.2 @@ -0,0 +1,295 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/sys/socket.h, which does not have +.\" any authorship information in it. It is probably available under the GPL. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: +.\" +.\" Copyright (c) 1983 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1998, 1999 by Andi Kleen +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH CONNECT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +connect \- initiate a connection on a socket +.SH SYNOPSIS +.nf +.BR "#include " " /* See NOTES */" +.br +.B #include +.PP +.BI "int connect(int " sockfd ", const struct sockaddr *" addr , +.BI " socklen_t " addrlen ); +.fi +.SH DESCRIPTION +The +.BR connect () +system call connects the socket referred to by the file descriptor +.I sockfd +to the address specified by +.IR addr . +The +.I addrlen +argument specifies the size of +.IR addr . +The format of the address in +.I addr +is determined by the address space of the socket +.IR sockfd ; +see +.BR socket (2) +for further details. +.PP +If the socket +.I sockfd +is of type +.BR SOCK_DGRAM , +then +.I addr +is the address to which datagrams are sent by default, and the only +address from which datagrams are received. +If the socket is of type +.B SOCK_STREAM +or +.BR SOCK_SEQPACKET , +this call attempts to make a connection to the socket that is bound +to the address specified by +.IR addr . +.PP +Generally, connection-based protocol sockets may successfully +.BR connect () +only once; connectionless protocol sockets may use +.BR connect () +multiple times to change their association. +Connectionless sockets may +dissolve the association by connecting to an address with the +.I sa_family +member of +.I sockaddr +set to +.BR AF_UNSPEC +(supported on Linux since kernel 2.2). +.SH RETURN VALUE +If the connection or binding succeeds, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +The following are general socket errors only. +There may be other domain-specific error codes. +.TP +.B EACCES +For UNIX domain sockets, which are identified by pathname: +Write permission is denied on the socket file, +or search permission is denied for one of the directories +in the path prefix. +(See also +.BR path_resolution (7).) +.TP +.BR EACCES ", " EPERM +The user tried to connect to a broadcast address without having the socket +broadcast flag enabled or the connection request failed because of a local +firewall rule. +.TP +.B EADDRINUSE +Local address is already in use. +.TP +.B EADDRNOTAVAIL +(Internet domain sockets) +The socket referred to by +.I sockfd +had not previously been bound to an address and, +upon attempting to bind it to an ephemeral port, +it was determined that all port numbers in the ephemeral port range +are currently in use. +See the discussion of +.I /proc/sys/net/ipv4/ip_local_port_range +in +.BR ip (7). +.TP +.B EAFNOSUPPORT +The passed address didn't have the correct address family in its +.I sa_family +field. +.TP +.B EAGAIN +Insufficient entries in the routing cache. +.TP +.B EALREADY +The socket is nonblocking and a previous connection attempt has not yet +been completed. +.TP +.B EBADF +.I sockfd +is not a valid open file descriptor. +.TP +.B ECONNREFUSED +A +.BR connect () +on a stream socket found no one listening on the remote address. +.TP +.B EFAULT +The socket structure address is outside the user's address space. +.TP +.B EINPROGRESS +The socket is nonblocking and the connection cannot be completed +immediately. +It is possible to +.BR select (2) +or +.BR poll (2) +for completion by selecting the socket for writing. +After +.BR select (2) +indicates writability, use +.BR getsockopt (2) +to read the +.B SO_ERROR +option at level +.B SOL_SOCKET +to determine whether +.BR connect () +completed successfully +.RB ( SO_ERROR +is zero) or unsuccessfully +.RB ( SO_ERROR +is one of the usual error codes listed here, +explaining the reason for the failure). +.TP +.B EINTR +The system call was interrupted by a signal that was caught; see +.BR signal (7). +.\" For TCP, the connection will complete asynchronously. +.\" See http://lkml.org/lkml/2005/7/12/254 +.TP +.B EISCONN +The socket is already connected. +.TP +.B ENETUNREACH +Network is unreachable. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.TP +.B EPROTOTYPE +The socket type does not support the requested communications protocol. +This error can occur, for example, +on an attempt to connect a UNIX domain datagram socket to a stream socket. +.TP +.B ETIMEDOUT +Timeout while attempting connection. +The server may be too +busy to accept new connections. +Note that for IP sockets the timeout may +be very long when syncookies are enabled on the server. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD, +.RB (connect () +first appeared in 4.2BSD). +.\" SVr4 documents the additional +.\" general error codes +.\" .BR EADDRNOTAVAIL , +.\" .BR EINVAL , +.\" .BR EAFNOSUPPORT , +.\" .BR EALREADY , +.\" .BR EINTR , +.\" .BR EPROTOTYPE , +.\" and +.\" .BR ENOSR . +.\" It also +.\" documents many additional error conditions not described here. +.SH NOTES +POSIX.1 does not require the inclusion of +.IR , +and this header file is not required on Linux. +However, some historical (BSD) implementations required this header +file, and portable applications are probably wise to include it. +.PP +For background on the +.I socklen_t +type, see +.BR accept (2). +.PP +If +.BR connect () +fails, consider the state of the socket as unspecified. +Portable applications should close the socket and create a new one for +reconnecting. +.SH EXAMPLE +An example of the use of +.BR connect () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR getsockname (2), +.BR listen (2), +.BR socket (2), +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2 new file mode 100644 index 0000000..35c0967 --- /dev/null +++ b/man2/copy_file_range.2 @@ -0,0 +1,244 @@ +.\"This manpage is Copyright (C) 2015 Anna Schumaker +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume +.\" no responsibility for errors or omissions, or for damages resulting +.\" from the use of the information contained herein. The author(s) may +.\" not have taken the same level of care in the production of this +.\" manual, which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH COPY_FILE_RANGE 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +copy_file_range \- Copy a range of data from one file to another +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.PP +.BI "ssize_t copy_file_range(int " fd_in ", loff_t *" off_in , +.BI " int " fd_out ", loff_t *" off_out , +.BI " size_t " len ", unsigned int " flags ); +.fi +.SH DESCRIPTION +The +.BR copy_file_range () +system call performs an in-kernel copy between two file descriptors +without the additional cost of transferring data from the kernel to user space +and then back into the kernel. +It copies up to +.I len +bytes of data from file descriptor +.I fd_in +to file descriptor +.IR fd_out , +overwriting any data that exists within the requested range of the target file. +.PP +The following semantics apply for +.IR off_in , +and similar statements apply to +.IR off_out : +.IP * 3 +If +.I off_in +is NULL, then bytes are read from +.I fd_in +starting from the file offset, and the file offset is +adjusted by the number of bytes copied. +.IP * +If +.I off_in +is not NULL, then +.I off_in +must point to a buffer that specifies the starting +offset where bytes from +.I fd_in +will be read. +The file offset of +.I fd_in +is not changed, but +.I off_in +is adjusted appropriately. +.PP +.PP +The +.I flags +argument is provided to allow for future extensions +and currently must be to 0. +.SH RETURN VALUE +Upon successful completion, +.BR copy_file_range () +will return the number of bytes copied between files. +This could be less than the length originally requested. +.PP +On error, +.BR copy_file_range () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +One or more file descriptors are not valid; or +.I fd_in +is not open for reading; or +.I fd_out +is not open for writing; or +the +.B O_APPEND +flag is set for the open file description referred to by +.IR fd_out . +.TP +.B EFBIG +An attempt was made to write a file that exceeds the implementation-defined +maximum file size or the process's file size limit, +or to write at a position past the maximum allowed offset. +.TP +.B EINVAL +Requested range extends beyond the end of the source file; or the +.I flags +argument is not 0. +.TP +.B EIO +A low-level I/O error occurred while copying. +.TP +.B EISDIR +.I fd_in +or +.I fd_out +refers to a directory. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOSPC +There is not enough space on the target filesystem to complete the copy. +.TP +.B EXDEV +The files referred to by +.IR file_in " and " file_out +are not on the same mounted filesystem. +.SH VERSIONS +The +.BR copy_file_range () +system call first appeared in Linux 4.5, but glibc 2.27 provides a user-space +emulation when it is not available. +.\" https://sourceware.org/git/?p=glibc.git;a=commit;f=posix/unistd.h;h=bad7a0c81f501fbbcc79af9eaa4b8254441c4a1f +.SH CONFORMING TO +The +.BR copy_file_range () +system call is a nonstandard Linux and GNU extension. +.SH NOTES +If +.I file_in +is a sparse file, then +.BR copy_file_range () +may expand any holes existing in the requested range. +Users may benefit from calling +.BR copy_file_range () +in a loop, and using the +.BR lseek (2) +.BR SEEK_DATA +and +.BR SEEK_HOLE +operations to find the locations of data segments. +.PP +.BR copy_file_range () +gives filesystems an opportunity to implement "copy acceleration" techniques, +such as the use of reflinks (i.e., two or more i-nodes that share +pointers to the same copy-on-write disk blocks) +or server-side-copy (in the case of NFS). +.SH EXAMPLE +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +/* On versions of glibc before 2.27, we must invoke copy_file_range() + using syscall(2) */ + +static loff_t +copy_file_range(int fd_in, loff_t *off_in, int fd_out, + loff_t *off_out, size_t len, unsigned int flags) +{ + return syscall(__NR_copy_file_range, fd_in, off_in, fd_out, + off_out, len, flags); +} + +int +main(int argc, char **argv) +{ + int fd_in, fd_out; + struct stat stat; + loff_t len, ret; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + fd_in = open(argv[1], O_RDONLY); + if (fd_in == \-1) { + perror("open (argv[1])"); + exit(EXIT_FAILURE); + } + + if (fstat(fd_in, &stat) == \-1) { + perror("fstat"); + exit(EXIT_FAILURE); + } + + len = stat.st_size; + + fd_out = open(argv[2], O_CREAT | O_WRONLY | O_TRUNC, 0644); + if (fd_out == \-1) { + perror("open (argv[2])"); + exit(EXIT_FAILURE); + } + + do { + ret = copy_file_range(fd_in, NULL, fd_out, NULL, len, 0); + if (ret == \-1) { + perror("copy_file_range"); + exit(EXIT_FAILURE); + } + + len \-= ret; + } while (len > 0); + + close(fd_in); + close(fd_out); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR lseek (2), +.BR sendfile (2), +.BR splice (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/creat.2 b/man2/creat.2 new file mode 100644 index 0000000..604e121 --- /dev/null +++ b/man2/creat.2 @@ -0,0 +1 @@ +.so man2/open.2 diff --git a/man2/create_module.2 b/man2/create_module.2 new file mode 100644 index 0000000..958cfb0 --- /dev/null +++ b/man2/create_module.2 @@ -0,0 +1,88 @@ +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" reformatting and rewordings by mtk +.\" +.TH CREATE_MODULE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +create_module \- create a loadable module entry +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "caddr_t create_module(const char *" name ", size_t " size ); +.fi +.PP +.IR Note : +No declaration of this system call is provided in glibc headers; see NOTES. +.SH DESCRIPTION +.IR Note : +This system call is present only in kernels before Linux 2.6. +.PP +.BR create_module () +attempts to create a loadable module entry and reserve the kernel memory +that will be needed to hold the module. +This system call requires privilege. +.SH RETURN VALUE +On success, returns the kernel address at which the module will reside. +On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EEXIST +A module by that name already exists. +.TP +.B EFAULT +.I name +is outside the program's accessible address space. +.TP +.B EINVAL +The requested size is too small even for the module header information. +.TP +.B ENOMEM +The kernel could not allocate a contiguous block of memory large +enough for the module. +.TP +.B ENOSYS +.BR create_module () +is not supported in this version of the kernel +(e.g., the kernel is version 2.6 or later). +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability). +.SH VERSIONS +This system call is present on Linux only up until kernel 2.4; +it was removed in Linux 2.6. +.\" Removed in Linux 2.5.48 +.SH CONFORMING TO +.BR create_module () +is Linux-specific. +.SH NOTES +This obsolete system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it was sufficient to manually declare the interface in your code; +alternatively, you could invoke the system call using +.BR syscall (2). +.SH SEE ALSO +.BR delete_module (2), +.BR init_module (2), +.BR query_module (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/delete_module.2 b/man2/delete_module.2 new file mode 100644 index 0000000..911624b --- /dev/null +++ b/man2/delete_module.2 @@ -0,0 +1,225 @@ +.\" Copyright (C) 2012 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH DELETE_MODULE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +delete_module \- unload a kernel module +.SH SYNOPSIS +.nf +.BI "int delete_module(const char *" name ", int " flags ); +.fi +.PP +.IR Note : +No declaration of this system call is provided in glibc headers; see NOTES. +.SH DESCRIPTION +The +.BR delete_module () +system call attempts to remove the unused loadable module entry +identified by +.IR name . +If the module has an +.I exit +function, then that function is executed before unloading the module. +The +.IR flags +argument is used to modify the behavior of the system call, +as described below. +This system call requires privilege. +.PP +Module removal is attempted according to the following rules: +.IP 1. 4 +If there are other loaded modules that depend on +(i.e., refer to symbols defined in) this module, +then the call fails. +.IP 2. +Otherwise, if the reference count for the module +(i.e., the number of processes currently using the module) +is zero, then the module is immediately unloaded. +.IP 3. +If a module has a nonzero reference count, +then the behavior depends on the bits set in +.IR flags . +In normal usage (see NOTES), the +.BR O_NONBLOCK +flag is always specified, and the +.BR O_TRUNC +flag may additionally be specified. +.\" O_TRUNC == KMOD_REMOVE_FORCE in kmod library +.\" O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library +.IP +The various combinations for +.I flags +have the following effect: +.RS 4 +.TP +.B flags == O_NONBLOCK +The call returns immediately, with an error. +.TP +.B flags == (O_NONBLOCK | O_TRUNC) +The module is unloaded immediately, +regardless of whether it has a nonzero reference count. +.TP +.B (flags & O_NONBLOCK) == 0 +If +.I flags +does not specify +.BR O_NONBLOCK , +the following steps occur: +.RS +.IP * 3 +The module is marked so that no new references are permitted. +.IP * +If the module's reference count is nonzero, +the caller is placed in an uninterruptible sleep state +.RB ( TASK_UNINTERRUPTIBLE ) +until the reference count is zero, at which point the call unblocks. +.IP * +The module is unloaded in the usual way. +.RE +.RE +.PP +The +.B O_TRUNC +flag has one further effect on the rules described above. +By default, if a module has an +.I init +function but no +.I exit +function, then an attempt to remove the module fails. +However, if +.BR O_TRUNC +was specified, this requirement is bypassed. +.PP +Using the +.B O_TRUNC +flag is dangerous! +If the kernel was not built with +.BR CONFIG_MODULE_FORCE_UNLOAD , +this flag is silently ignored. +(Normally, +.BR CONFIG_MODULE_FORCE_UNLOAD +is enabled.) +Using this flag taints the kernel (TAINT_FORCED_RMMOD). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBUSY +The module is not "live" +(i.e., it is still being initialized or is already marked for removal); +or, the module has +an +.I init +function but has no +.I exit +function, and +.B O_TRUNC +was not specified in +.IR flags . +.TP +.B EFAULT +.I name +refers to a location outside the process's accessible address space. +.TP +.B ENOENT +No module by that name exists. +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability), +or module unloading is disabled +(see +.IR /proc/sys/kernel/modules_disabled +in +.BR proc (5)). +.TP +.B EWOULDBLOCK +Other modules depend on this module; +or, +.BR O_NONBLOCK +was specified in +.IR flags , +but the reference count of this module is nonzero and +.B O_TRUNC +was not specified in +.IR flags . +.SH CONFORMING TO +.BR delete_module () +is Linux-specific. +.SH NOTES +The +.BR delete_module () +system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it is (before glibc 2.23) sufficient to +manually declare the interface in your code; +alternatively, you can invoke the system call using +.BR syscall (2). +.PP +The uninterruptible sleep that may occur if +.BR O_NONBLOCK +is omitted from +.IR flags +is considered undesirable, because the sleeping process is left +in an unkillable state. +As at Linux 3.7, specifying +.BR O_NONBLOCK +is optional, but in future kernels it is likely to become mandatory. +.SS Linux 2.4 and earlier +In Linux 2.4 and earlier, the system call took only one argument: +.PP +.BI " int delete_module(const char *" name ); +.PP +If +.I name +is NULL, all unused modules marked auto-clean are removed. +.PP +Some further details of differences in the behavior of +.BR delete_module () +in Linux 2.4 and earlier are +.I not +currently explained in this manual page. +.SH SEE ALSO +.BR create_module (2), +.BR init_module (2), +.BR query_module (2), +.BR lsmod (8), +.BR modprobe (8), +.BR rmmod (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/dup.2 b/man2/dup.2 new file mode 100644 index 0000000..1829b5e --- /dev/null +++ b/man2/dup.2 @@ -0,0 +1,287 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2005, 2008 Michael Kerrisk +.\" and Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-21, Rik Faith +.\" Modified 1994-08-21, Michael Chastain : +.\" Fixed typos. +.\" Modified 1997-01-31, Eric S. Raymond +.\" Modified 2002-09-28, aeb +.\" 2009-01-12, mtk, reordered text in DESCRIPTION and added some +.\" details for dup2(). +.\" 2008-10-09, mtk: add description of dup3() +.\" +.TH DUP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +dup, dup2, dup3 \- duplicate a file descriptor +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int dup(int " oldfd ); +.BI "int dup2(int " oldfd ", int " newfd ); + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.BR "#include " " /* Obtain O_* constant definitions */ +.B #include +.PP +.BI "int dup3(int " oldfd ", int " newfd ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR dup () +system call creates a copy of the file descriptor +.IR oldfd , +using the lowest-numbered unused file descriptor for the new descriptor. +.PP +After a successful return, +the old and new file descriptors may be used interchangeably. +They refer to the same open file description (see +.BR open (2)) +and thus share file offset and file status flags; +for example, if the file offset is modified by using +.BR lseek (2) +on one of the file descriptors, the offset is also changed for the other. +.PP +The two file descriptors do not share file descriptor flags +(the close-on-exec flag). +The close-on-exec flag +.RB ( FD_CLOEXEC ; +see +.BR fcntl (2)) +for the duplicate descriptor is off. +.\" +.SS dup2() +The +.BR dup2 () +system call performs the same task as +.BR dup (), +but instead of using the lowest-numbered unused file descriptor, +it uses the file descriptor number specified in +.IR newfd . +If the file descriptor +.IR newfd +was previously open, it is silently closed before being reused. +.PP +The steps of closing and reusing the file descriptor +.IR newfd +are performed +.IR atomically . +This is important, because trying to implement equivalent functionality using +.BR close (2) +and +.BR dup () +would be +subject to race conditions, whereby +.I newfd +might be reused between the two steps. +Such reuse could happen because the main program is interrupted +by a signal handler that allocates a file descriptor, +or because a parallel thread allocates a file descriptor. +.PP +Note the following points: +.IP * 3 +If +.I oldfd +is not a valid file descriptor, then the call fails, and +.I newfd +is not closed. +.IP * +If +.I oldfd +is a valid file descriptor, and +.I newfd +has the same value as +.IR oldfd , +then +.BR dup2 () +does nothing, and returns +.IR newfd . +.\" +.SS dup3() +.BR dup3 () +is the same as +.BR dup2 (), +except that: +.IP * 3 +The caller can force the close-on-exec flag to be set +for the new file descriptor by specifying +.BR O_CLOEXEC +in +.IR flags . +See the description of the same flag in +.BR open (2) +for reasons why this may be useful. +.IP * +.\" Ulrich Drepper, LKML, 2008-10-09: +.\" We deliberately decided on this change. Otherwise, what is the +.\" result of dup3(fd, fd, O_CLOEXEC)? +If +.IR oldfd +equals +.IR newfd , +then +.BR dup3 () +fails with the error +.BR EINVAL . +.SH RETURN VALUE +On success, these system calls +return the new file descriptor. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I oldfd +isn't an open file descriptor. +.TP +.B EBADF +.I newfd +is out of the allowed range for file descriptors (see the discussion of +.BR RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B EBUSY +(Linux only) This may be returned by +.BR dup2 () +or +.BR dup3 () +during a race condition with +.BR open (2) +and +.BR dup (). +.TP +.B EINTR +The +.BR dup2 () +or +.BR dup3 () +call was interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +.RB ( dup3 ()) +.I flags +contain an invalid value. +.TP +.B EINVAL +.RB ( dup3 ()) +.I oldfd +was equal to +.IR newfd . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached +(see the discussion of +.BR RLIMIT_NOFILE +in +.BR getrlimit (2)). +.SH VERSIONS +.BR dup3 () +was added to Linux in version 2.6.27; +glibc support is available starting with +version 2.9. +.SH CONFORMING TO +.BR dup (), +.BR dup2 (): +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.PP +.BR dup3 () +is Linux-specific. +.\" SVr4 documents additional +.\" EINTR and ENOLINK error conditions. POSIX.1 adds EINTR. +.\" The EBUSY return is Linux-specific. +.SH NOTES +The error returned by +.BR dup2 () +is different from that returned by +.BR fcntl( "..., " F_DUPFD ", ..." ) +when +.I newfd +is out of range. +On some systems, +.BR dup2 () +also sometimes returns +.B EINVAL +like +.BR F_DUPFD . +.PP +If +.I newfd +was open, any errors that would have been reported at +.BR close (2) +time are lost. +If this is of concern, +then\(emunless the program is single-threaded and does not allocate +file descriptors in signal handlers\(emthe correct approach is +.I not +to close +.I newfd +before calling +.BR dup2 (), +because of the race condition described above. +Instead, code something like the following could be used: +.PP +.EX + /* Obtain a duplicate of 'newfd' that can subsequently + be used to check for close() errors; an EBADF error + means that 'newfd' was not open. */ + + tmpfd = dup(newfd); + if (tmpfd == \-1 && errno != EBADF) { + /* Handle unexpected dup() error */ + } + + /* Atomically duplicate 'oldfd' on 'newfd' */ + + if (dup2(oldfd, newfd) == \-1) { + /* Handle dup2() error */ + } + + /* Now check for close() errors on the file originally + referred to by 'newfd' */ + + if (tmpfd != \-1) { + if (close(tmpfd) == \-1) { + /* Handle errors from close */ + } + } +.EE +.SH SEE ALSO +.BR close (2), +.BR fcntl (2), +.BR open (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/dup2.2 b/man2/dup2.2 new file mode 100644 index 0000000..49a65c6 --- /dev/null +++ b/man2/dup2.2 @@ -0,0 +1 @@ +.so man2/dup.2 diff --git a/man2/dup3.2 b/man2/dup3.2 new file mode 100644 index 0000000..49a65c6 --- /dev/null +++ b/man2/dup3.2 @@ -0,0 +1 @@ +.so man2/dup.2 diff --git a/man2/epoll_create.2 b/man2/epoll_create.2 new file mode 100644 index 0000000..2bc253d --- /dev/null +++ b/man2/epoll_create.2 @@ -0,0 +1,160 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" Davide Libenzi +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2005-04-04 by Marko Kohtala +.\" 2008-10-10, mtk: add description of epoll_create1() +.\" +.TH EPOLL_CREATE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +epoll_create, epoll_create1 \- open an epoll file descriptor +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int epoll_create(int " size ); +.BI "int epoll_create1(int " flags ); +.fi +.SH DESCRIPTION +.BR epoll_create () +creates a new +.BR epoll (7) +instance. +Since Linux 2.6.8, the +.I size +argument is ignored, but must be greater than zero; see NOTES below. +.PP +.BR epoll_create () +returns a file descriptor referring to the new epoll instance. +This file descriptor is used for all the subsequent calls to the +.B epoll +interface. +When no longer required, the file descriptor returned by +.BR epoll_create () +should be closed by using +.BR close (2). +When all file descriptors referring to an epoll instance have been closed, +the kernel destroys the instance +and releases the associated resources for reuse. +.SS epoll_create1() +If +.I flags +is 0, then, other than the fact that the obsolete +.I size +argument is dropped, +.BR epoll_create1 () +is the same as +.BR epoll_create (). +The following value can be included in +.IR flags +to obtain different behavior: +.TP +.B EPOLL_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.SH RETURN VALUE +On success, +these system calls +return a nonnegative file descriptor. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I size +is not positive. +.TP +.B EINVAL +.RB ( epoll_create1 ()) +Invalid value specified in +.IR flags . +.TP +.B EMFILE +The per-user limit on the number of epoll instances imposed by +.I /proc/sys/fs/epoll/max_user_instances +was encountered. +See +.BR epoll (7) +for further details. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +There was insufficient memory to create the kernel object. +.SH VERSIONS +.BR epoll_create () +was added to the kernel in version 2.6. +Library support is provided in glibc starting with version 2.3.2. +.PP +.\" To be precise: kernel 2.5.44. +.\" The interface should be finalized by Linux kernel 2.5.66. +.BR epoll_create1 () +was added to the kernel in version 2.6.27. +Library support is provided in glibc starting with version 2.9. +.SH CONFORMING TO +.BR epoll_create () +is Linux-specific. +.SH NOTES +In the initial +.BR epoll_create () +implementation, the +.I size +argument informed the kernel of the number of file descriptors +that the caller expected to add to the +.B epoll +instance. +The kernel used this information as a hint for the amount of +space to initially allocate in internal data structures describing events. +(If necessary, the kernel would allocate more space +if the caller's usage exceeded the hint given in +.IR size .) +Nowadays, +this hint is no longer required +(the kernel dynamically sizes the required data structures +without needing the hint), but +.I size +must still be greater than zero, +in order to ensure backward compatibility when new +.B epoll +applications are run on older kernels. +.SH SEE ALSO +.BR close (2), +.BR epoll_ctl (2), +.BR epoll_wait (2), +.BR epoll (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/epoll_create1.2 b/man2/epoll_create1.2 new file mode 100644 index 0000000..69605b6 --- /dev/null +++ b/man2/epoll_create1.2 @@ -0,0 +1 @@ +.so man2/epoll_create.2 diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 new file mode 100644 index 0000000..bfd3813 --- /dev/null +++ b/man2/epoll_ctl.2 @@ -0,0 +1,441 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" Davide Libenzi +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH EPOLL_CTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +epoll_ctl \- control interface for an epoll file descriptor +.SH SYNOPSIS +.B #include +.PP +.BI "int epoll_ctl(int " epfd ", int " op ", int " fd \ +", struct epoll_event *" event ); +.SH DESCRIPTION +This system call performs control operations on the +.BR epoll (7) +instance +referred to by the file descriptor +.IR epfd . +It requests that the operation +.I op +be performed for the target file descriptor, +.IR fd . +.PP +Valid values for the +.I op +argument are: +.TP +.B EPOLL_CTL_ADD +Register the target file descriptor +.I fd +on the +.B epoll +instance referred to by the file descriptor +.I epfd +and associate the event +.I event +with the internal file linked to +.IR fd . +.TP +.B EPOLL_CTL_MOD +Change the event +.I event +associated with the target file descriptor +.IR fd . +.TP +.B EPOLL_CTL_DEL +Remove (deregister) the target file descriptor +.I fd +from the +.B epoll +instance referred to by +.IR epfd . +The +.I event +is ignored and can be NULL (but see BUGS below). +.PP +The +.I event +argument describes the object linked to the file descriptor +.IR fd . +The +.I struct epoll_event +is defined as: +.PP +.in +4n +.EX +typedef union epoll_data { + void *ptr; + int fd; + uint32_t u32; + uint64_t u64; +} epoll_data_t; + +struct epoll_event { + uint32_t events; /* Epoll events */ + epoll_data_t data; /* User data variable */ +}; +.EE +.in +.PP +The +.I events +member is a bit mask composed by ORing together zero or more of +the following available event types: +.TP +.B EPOLLIN +The associated file is available for +.BR read (2) +operations. +.TP +.B EPOLLOUT +The associated file is available for +.BR write (2) +operations. +.TP +.BR EPOLLRDHUP " (since Linux 2.6.17)" +Stream socket peer closed connection, +or shut down writing half of connection. +(This flag is especially useful for writing simple code to detect +peer shutdown when using Edge Triggered monitoring.) +.TP +.B EPOLLPRI +There is an exceptional condition on the file descriptor. +See the discussion of +.B POLLPRI +in +.BR poll (2). +.TP +.B EPOLLERR +Error condition happened on the associated file descriptor. +This event is also reported for the write end of a pipe when the read end +has been closed. +.BR epoll_wait (2) +will always report for this event; it is not necessary to set it in +.IR events . +.TP +.B EPOLLHUP +Hang up happened on the associated file descriptor. +.BR epoll_wait (2) +will always wait for this event; it is not necessary to set it in +.IR events . +.IP +Note that when reading from a channel such as a pipe or a stream socket, +this event merely indicates that the peer closed its end of the channel. +Subsequent reads from the channel will return 0 (end of file) +only after all outstanding data in the channel has been consumed. +.TP +.B EPOLLET +Sets the Edge Triggered behavior for the associated file descriptor. +The default behavior for +.B epoll +is Level Triggered. +See +.BR epoll (7) +for more detailed information about Edge and Level Triggered event +distribution architectures. +.TP +.BR EPOLLONESHOT " (since Linux 2.6.2)" +Sets the one-shot behavior for the associated file descriptor. +This means that after an event is pulled out with +.BR epoll_wait (2) +the associated file descriptor is internally disabled and no other events +will be reported by the +.B epoll +interface. +The user must call +.BR epoll_ctl () +with +.B EPOLL_CTL_MOD +to rearm the file descriptor with a new event mask. +.TP +.BR EPOLLWAKEUP " (since Linux 3.5)" +.\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238 +If +.B EPOLLONESHOT +and +.B EPOLLET +are clear and the process has the +.B CAP_BLOCK_SUSPEND +capability, +ensure that the system does not enter "suspend" or +"hibernate" while this event is pending or being processed. +The event is considered as being "processed" from the time +when it is returned by a call to +.BR epoll_wait (2) +until the next call to +.BR epoll_wait (2) +on the same +.BR epoll (7) +file descriptor, +the closure of that file descriptor, +the removal of the event file descriptor with +.BR EPOLL_CTL_DEL , +or the clearing of +.B EPOLLWAKEUP +for the event file descriptor with +.BR EPOLL_CTL_MOD . +See also BUGS. +.TP +.BR EPOLLEXCLUSIVE " (since Linux 4.5)" +Sets an exclusive wakeup mode for the epoll file descriptor that is being +attached to the target file descriptor, +.IR fd . +When a wakeup event occurs and multiple epoll file descriptors +are attached to the same target file using +.BR EPOLLEXCLUSIVE , +one or more of the epoll file descriptors will receive an event with +.BR epoll_wait (2). +The default in this scenario (when +.BR EPOLLEXCLUSIVE +is not set) is for all epoll file descriptors to receive an event. +.BR EPOLLEXCLUSIVE +is thus useful for avoiding thundering herd problems in certain scenarios. +.IP +If the same file descriptor is in multiple epoll instances, +some with the +.BR EPOLLEXCLUSIVE +flag, and others without, then events will be provided to all epoll +instances that did not specify +.BR EPOLLEXCLUSIVE , +and at least one of the epoll instances that did specify +.BR EPOLLEXCLUSIVE . +.IP +The following values may be specified in conjunction with +.BR EPOLLEXCLUSIVE : +.BR EPOLLIN , +.BR EPOLLOUT , +.BR EPOLLWAKEUP, +and +.BR EPOLLET . +.BR EPOLLHUP +and +.BR EPOLLERR +can also be specified, but this is not required: +as usual, these events are always reported if they occur, +regardless of whether they are specified in +.IR events . +Attempts to specify other values in +.I events +yield an error. +.B EPOLLEXCLUSIVE +may be used only in an +.B EPOLL_CTL_ADD +operation; attempts to employ it with +.B EPOLL_CTL_MOD +yield an error. +If +.B EPOLLEXCLUSIVE +has been set using +.BR epoll_ctl (), +then a subsequent +.B EPOLL_CTL_MOD +on the same +.IR epfd ",\ " fd +pair yields an error. +A call to +.BR epoll_ctl () +that specifies +.B EPOLLEXCLUSIVE +in +.I events +and specifies the target file descriptor +.I fd +as an epoll instance will likewise fail. +The error in all of these cases is +.BR EINVAL . +.SH RETURN VALUE +When successful, +.BR epoll_ctl () +returns zero. +When an error occurs, +.BR epoll_ctl () +returns \-1 and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I epfd +or +.I fd +is not a valid file descriptor. +.TP +.B EEXIST +.I op +was +.BR EPOLL_CTL_ADD , +and the supplied file descriptor +.I fd +is already registered with this epoll instance. +.TP +.B EINVAL +.I epfd +is not an +.B epoll +file descriptor, +or +.I fd +is the same as +.IR epfd , +or the requested operation +.I op +is not supported by this interface. +.TP +.B EINVAL +An invalid event type was specified along with +.B EPOLLEXCLUSIVE +in +.IR events . +.TP +.B EINVAL +.I op +was +.B EPOLL_CTL_MOD +and +.IR events +included +.BR EPOLLEXCLUSIVE . +.TP +.B EINVAL +.I op +was +.B EPOLL_CTL_MOD +and the +.BR EPOLLEXCLUSIVE +flag has previously been applied to this +.IR epfd ",\ " fd +pair. +.TP +.B EINVAL +.BR EPOLLEXCLUSIVE +was specified in +.IR event +and +.I fd +refers to an epoll instance. +.TP +.B ELOOP +.I fd +refers to an epoll instance and this +.B EPOLL_CTL_ADD +operation would result in a circular loop of epoll instances +monitoring one another. +.TP +.B ENOENT +.I op +was +.B EPOLL_CTL_MOD +or +.BR EPOLL_CTL_DEL , +and +.I fd +is not registered with this epoll instance. +.TP +.B ENOMEM +There was insufficient memory to handle the requested +.I op +control operation. +.TP +.B ENOSPC +The limit imposed by +.I /proc/sys/fs/epoll/max_user_watches +was encountered while trying to register +.RB ( EPOLL_CTL_ADD ) +a new file descriptor on an epoll instance. +See +.BR epoll (7) +for further details. +.TP +.B EPERM +The target file +.I fd +does not support +.BR epoll . +This error can occur if +.I fd +refers to, for example, a regular file or a directory. +.SH VERSIONS +.BR epoll_ctl () +was added to the kernel in version 2.6. +.\" To be precise: kernel 2.5.44. +.\" The interface should be finalized by Linux kernel 2.5.66. +.SH CONFORMING TO +.BR epoll_ctl () +is Linux-specific. +Library support is provided in glibc starting with version 2.3.2. +.SH NOTES +The +.B epoll +interface supports all file descriptors that support +.BR poll (2). +.SH BUGS +In kernel versions before 2.6.9, the +.B EPOLL_CTL_DEL +operation required a non-null pointer in +.IR event , +even though this argument is ignored. +Since Linux 2.6.9, +.I event +can be specified as NULL +when using +.BR EPOLL_CTL_DEL . +Applications that need to be portable to kernels before 2.6.9 +should specify a non-null pointer in +.IR event . +.PP +If +.B EPOLLWAKEUP +is specified in +.IR flags , +but the caller does not have the +.BR CAP_BLOCK_SUSPEND +capability, then the +.B EPOLLWAKEUP +flag is +.IR "silently ignored" . +This unfortunate behavior is necessary because no validity +checks were performed on the +.IR flags +argument in the original implementation, and the addition of the +.B EPOLLWAKEUP +with a check that caused the call to fail if the caller did not have the +.B CAP_BLOCK_SUSPEND +capability caused a breakage in at least one existing user-space +application that happened to randomly (and uselessly) specify this bit. +.\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change) +.\" https://lwn.net/Articles/520198/ +A robust application should therefore double check that it has the +.B CAP_BLOCK_SUSPEND +capability if attempting to use the +.B EPOLLWAKEUP +flag. +.SH SEE ALSO +.BR epoll_create (2), +.BR epoll_wait (2), +.BR poll (2), +.BR epoll (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/epoll_pwait.2 b/man2/epoll_pwait.2 new file mode 100644 index 0000000..9282a70 --- /dev/null +++ b/man2/epoll_pwait.2 @@ -0,0 +1 @@ +.so man2/epoll_wait.2 diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2 new file mode 100644 index 0000000..5edf20e --- /dev/null +++ b/man2/epoll_wait.2 @@ -0,0 +1,263 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" Davide Libenzi +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2007-04-30: mtk, Added description of epoll_pwait() +.\" +.TH EPOLL_WAIT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int epoll_wait(int " epfd ", struct epoll_event *" events , +.BI " int " maxevents ", int " timeout ); +.BI "int epoll_pwait(int " epfd ", struct epoll_event *" events , +.BI " int " maxevents ", int " timeout , +.BI " const sigset_t *" sigmask ); +.fi +.SH DESCRIPTION +The +.BR epoll_wait () +system call waits for events on the +.BR epoll (7) +instance referred to by the file descriptor +.IR epfd . +The memory area pointed to by +.I events +will contain the events that will be available for the caller. +Up to +.I maxevents +are returned by +.BR epoll_wait (). +The +.I maxevents +argument must be greater than zero. +.PP +The +.I timeout +argument specifies the number of milliseconds that +.BR epoll_wait () +will block. +Time is measured against the +.B CLOCK_MONOTONIC +clock. +The call will block until either: +.IP * 3 +a file descriptor delivers an event; +.IP * +the call is interrupted by a signal handler; or +.IP * +the timeout expires. +.PP +Note that the +.I timeout +interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the blocking interval +may overrun by a small amount. +Specifying a +.I timeout +of \-1 causes +.BR epoll_wait () +to block indefinitely, while specifying a +.I timeout +equal to zero cause +.BR epoll_wait () +to return immediately, even if no events are available. +.PP +The +.I struct epoll_event +is defined as: +.PP +.in +4n +.EX +typedef union epoll_data { + void *ptr; + int fd; + uint32_t u32; + uint64_t u64; +} epoll_data_t; + +struct epoll_event { + uint32_t events; /* Epoll events */ + epoll_data_t data; /* User data variable */ +}; +.EE +.in +.PP +The +.I data +field of each returned structure contains the same data as was specified +in the most recent call to +.BR epoll_ctl (2) +.RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD ) +for the corresponding open file description. +The +.I events +field contains the returned event bit field. +.SS epoll_pwait() +The relationship between +.BR epoll_wait () +and +.BR epoll_pwait () +is analogous to the relationship between +.BR select (2) +and +.BR pselect (2): +like +.BR pselect (2), +.BR epoll_pwait () +allows an application to safely wait until either a file descriptor +becomes ready or until a signal is caught. +.PP +The following +.BR epoll_pwait () +call: +.PP +.in +4n +.EX +ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask); +.EE +.in +.PP +is equivalent to +.I atomically +executing the following calls: +.PP +.in +4n +.EX +sigset_t origmask; + +pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); +ready = epoll_wait(epfd, &events, maxevents, timeout); +pthread_sigmask(SIG_SETMASK, &origmask, NULL); +.EE +.in +.PP +The +.I sigmask +argument may be specified as NULL, in which case +.BR epoll_pwait () +is equivalent to +.BR epoll_wait (). +.SH RETURN VALUE +When successful, +.BR epoll_wait () +returns the number of file descriptors ready for the requested I/O, or zero +if no file descriptor became ready during the requested +.I timeout +milliseconds. +When an error occurs, +.BR epoll_wait () +returns \-1 and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I epfd +is not a valid file descriptor. +.TP +.B EFAULT +The memory area pointed to by +.I events +is not accessible with write permissions. +.TP +.B EINTR +The call was interrupted by a signal handler before either (1) any of the +requested events occurred or (2) the +.I timeout +expired; see +.BR signal (7). +.TP +.B EINVAL +.I epfd +is not an +.B epoll +file descriptor, or +.I maxevents +is less than or equal to zero. +.SH VERSIONS +.BR epoll_wait () +was added to the kernel in version 2.6. +.\" To be precise: kernel 2.5.44. +.\" The interface should be finalized by Linux kernel 2.5.66. +Library support is provided in glibc starting with version 2.3.2. +.PP +.BR epoll_pwait () +was added to Linux in kernel 2.6.19. +Library support is provided in glibc starting with version 2.6. +.SH CONFORMING TO +.BR epoll_wait () +is Linux-specific. +.SH NOTES +While one thread is blocked in a call to +.BR epoll_pwait (), +it is possible for another thread to add a file descriptor to the waited-upon +.B epoll +instance. +If the new file descriptor becomes ready, +it will cause the +.BR epoll_wait () +call to unblock. +.PP +For a discussion of what may happen if a file descriptor in an +.B epoll +instance being monitored by +.BR epoll_wait () +is closed in another thread, see +.BR select (2). +.SH BUGS +In kernels before 2.6.37, a +.I timeout +value larger than approximately +.I LONG_MAX / HZ +milliseconds is treated as \-1 (i.e., infinity). +Thus, for example, on a system where +.I sizeof(long) +is 4 and the kernel +.I HZ +value is 1000, +this means that timeouts greater than 35.79 minutes are treated as infinity. +.SS C library/kernel differences +The raw +.BR epoll_pwait () +system call has a sixth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the +.IR sigmask +argument. +The glibc +.BR epoll_pwait () +wrapper function specifies this argument as a fixed value +(equal to +.IR sizeof(sigset_t) ). +.SH SEE ALSO +.BR epoll_create (2), +.BR epoll_ctl (2), +.BR epoll (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/eventfd.2 b/man2/eventfd.2 new file mode 100644 index 0000000..de2461f --- /dev/null +++ b/man2/eventfd.2 @@ -0,0 +1,458 @@ +.\" Copyright (C) 2008 Michael Kerrisk +.\" starting from a version by Davide Libenzi +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC +.\" +.TH EVENTFD 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +eventfd \- create a file descriptor for event notification +.SH SYNOPSIS +.B #include +.PP +.BI "int eventfd(unsigned int " initval ", int " flags ); +.SH DESCRIPTION +.BR eventfd () +creates an "eventfd object" that can be used as +an event wait/notify mechanism by user-space applications, +and by the kernel to notify user-space applications of events. +The object contains an unsigned 64-bit integer +.RI ( uint64_t ) +counter that is maintained by the kernel. +This counter is initialized with the value specified in the argument +.IR initval . +.PP +The following values may be bitwise ORed in +.IR flags +to change the behavior of +.BR eventfd (): +.TP +.BR EFD_CLOEXEC " (since Linux 2.6.27)" +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.TP +.BR EFD_NONBLOCK " (since Linux 2.6.27)" +Set the +.BR O_NONBLOCK +file status flag on the new open file description. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.BR EFD_SEMAPHORE " (since Linux 2.6.30)" +Provide semaphore-like semantics for reads from the new file descriptor. +See below. +.PP +In Linux up to version 2.6.26, the +.I flags +argument is unused, and must be specified as zero. +.PP +As its return value, +.BR eventfd () +returns a new file descriptor that can be used to refer to the +eventfd object. +The following operations can be performed on the file descriptor: +.TP +.BR read (2) +Each successful +.BR read (2) +returns an 8-byte integer. +A +.BR read (2) +fails with the error +.B EINVAL +if the size of the supplied buffer is less than 8 bytes. +.IP +The value returned by +.BR read (2) +is in host byte order\(emthat is, +the native byte order for integers on the host machine. +.IP +The semantics of +.BR read (2) +depend on whether the eventfd counter currently has a nonzero value +and whether the +.BR EFD_SEMAPHORE +flag was specified when creating the eventfd file descriptor: +.RS +.IP * 3 +If +.BR EFD_SEMAPHORE +was not specified and the eventfd counter has a nonzero value, then a +.BR read (2) +returns 8 bytes containing that value, +and the counter's value is reset to zero. +.IP * +If +.BR EFD_SEMAPHORE +was specified and the eventfd counter has a nonzero value, then a +.BR read (2) +returns 8 bytes containing the value 1, +and the counter's value is decremented by 1. +.IP * +If the eventfd counter is zero at the time of the call to +.BR read (2), +then the call either blocks until the counter becomes nonzero +(at which time, the +.BR read (2) +proceeds as described above) +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking. +.RE +.TP +.BR write (2) +A +.BR write (2) +call adds the 8-byte integer value supplied in its +buffer to the counter. +The maximum value that may be stored in the counter is the largest +unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe). +If the addition would cause the counter's value to exceed +the maximum, then the +.BR write (2) +either blocks until a +.BR read (2) +is performed on the file descriptor, +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking. +.IP +A +.BR write (2) +fails with the error +.B EINVAL +if the size of the supplied buffer is less than 8 bytes, +or if an attempt is made to write the value 0xffffffffffffffff. +.TP +.BR poll "(2), " select "(2) (and similar)" +The returned file descriptor supports +.BR poll (2) +(and analogously +.BR epoll (7)) +and +.BR select (2), +as follows: +.RS +.IP * 3 +The file descriptor is readable +(the +.BR select (2) +.I readfds +argument; the +.BR poll (2) +.B POLLIN +flag) +if the counter has a value greater than 0. +.IP * +The file descriptor is writable +(the +.BR select (2) +.I writefds +argument; the +.BR poll (2) +.B POLLOUT +flag) +if it is possible to write a value of at least "1" without blocking. +.IP * +If an overflow of the counter value was detected, +then +.BR select (2) +indicates the file descriptor as being both readable and writable, and +.BR poll (2) +returns a +.B POLLERR +event. +As noted above, +.BR write (2) +can never overflow the counter. +However an overflow can occur if 2^64 +eventfd "signal posts" were performed by the KAIO +subsystem (theoretically possible, but practically unlikely). +If an overflow has occurred, then +.BR read (2) +will return that maximum +.I uint64_t +value (i.e., 0xffffffffffffffff). +.RE +.IP +The eventfd file descriptor also supports the other file-descriptor +multiplexing APIs: +.BR pselect (2) +and +.BR ppoll (2). +.TP +.BR close (2) +When the file descriptor is no longer required it should be closed. +When all file descriptors associated with the same eventfd object +have been closed, the resources for object are freed by the kernel. +.PP +A copy of the file descriptor created by +.BR eventfd () +is inherited by the child produced by +.BR fork (2). +The duplicate file descriptor is associated with the same +eventfd object. +File descriptors created by +.BR eventfd () +are preserved across +.BR execve (2), +unless the close-on-exec flag has been set. +.SH RETURN VALUE +On success, +.BR eventfd () +returns a new eventfd file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An unsupported value was specified in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENODEV +.\" Note from Davide: +.\" The ENODEV error is basically never going to happen if +.\" the kernel boots correctly. That error happen only if during +.\" the kernel initialization, some error occur in the anonymous +.\" inode source initialization. +Could not mount (internal) anonymous inode device. +.TP +.B ENOMEM +There was insufficient memory to create a new +eventfd file descriptor. +.SH VERSIONS +.BR eventfd () +is available on Linux since kernel 2.6.22. +Working support is provided in glibc since version 2.8. +.\" eventfd() is in glibc 2.7, but reportedly does not build +The +.BR eventfd2 () +system call (see NOTES) is available on Linux since kernel 2.6.27. +Since version 2.9, the glibc +.BR eventfd () +wrapper will employ the +.BR eventfd2 () +system call, if it is supported by the kernel. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR eventfd () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +.BR eventfd () +and +.BR eventfd2 () +are Linux-specific. +.SH NOTES +Applications can use an eventfd file descriptor instead of a pipe (see +.BR pipe (2)) +in all cases where a pipe is used simply to signal events. +The kernel overhead of an eventfd file descriptor +is much lower than that of a pipe, +and only one file descriptor is +required (versus the two required for a pipe). +.PP +When used in the kernel, an eventfd +file descriptor can provide a bridge from kernel to user space, allowing, +for example, functionalities like KAIO (kernel AIO) +.\" or eventually syslets/threadlets +to signal to a file descriptor that some operation is complete. +.PP +A key point about an eventfd file descriptor is that it can be +monitored just like any other file descriptor using +.BR select (2), +.BR poll (2), +or +.BR epoll (7). +This means that an application can simultaneously monitor the +readiness of "traditional" files and the readiness of other +kernel mechanisms that support the eventfd interface. +(Without the +.BR eventfd () +interface, these mechanisms could not be multiplexed via +.BR select (2), +.BR poll (2), +or +.BR epoll (7).) +.PP +The current value of an eventfd counter can be viewed +via the entry for the corresponding file descriptor in the process's +.IR /proc/[pid]/fdinfo +directory. +See +.BR proc (5) +for further details. +.\" +.SS C library/kernel differences +There are two underlying Linux system calls: +.BR eventfd () +and the more recent +.BR eventfd2 (). +The former system call does not implement a +.I flags +argument. +The latter system call implements the +.I flags +values described above. +The glibc wrapper function will use +.BR eventfd2 () +where it is available. +.SS Additional glibc features +The GNU C library defines an additional type, +and two functions that attempt to abstract some of the details of +reading and writing on an eventfd file descriptor: +.PP +.in +4n +.EX +typedef uint64_t eventfd_t; + +int eventfd_read(int fd, eventfd_t *value); +int eventfd_write(int fd, eventfd_t value); +.EE +.in +.PP +The functions perform the read and write operations on an +eventfd file descriptor, +returning 0 if the correct number of bytes was transferred, +or \-1 otherwise. +.SH EXAMPLE +.PP +The following program creates an eventfd file descriptor +and then forks to create a child process. +While the parent briefly sleeps, +the child writes each of the integers supplied in the program's +command-line arguments to the eventfd file descriptor. +When the parent has finished sleeping, +it reads from the eventfd file descriptor. +.PP +The following shell session shows a sample run of the program: +.PP +.in +4n +.EX +.RB "$" " ./a.out 1 2 4 7 14" +Child writing 1 to efd +Child writing 2 to efd +Child writing 4 to efd +Child writing 7 to efd +Child writing 14 to efd +Child completed write loop +Parent about to read +Parent read 28 (0x1c) from efd +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include /* Definition of uint64_t */ + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +int +main(int argc, char *argv[]) +{ + int efd, j; + uint64_t u; + ssize_t s; + + if (argc < 2) { + fprintf(stderr, "Usage: %s ...\\n", argv[0]); + exit(EXIT_FAILURE); + } + + efd = eventfd(0, 0); + if (efd == \-1) + handle_error("eventfd"); + + switch (fork()) { + case 0: + for (j = 1; j < argc; j++) { + printf("Child writing %s to efd\\n", argv[j]); + u = strtoull(argv[j], NULL, 0); + /* strtoull() allows various bases */ + s = write(efd, &u, sizeof(uint64_t)); + if (s != sizeof(uint64_t)) + handle_error("write"); + } + printf("Child completed write loop\\n"); + + exit(EXIT_SUCCESS); + + default: + sleep(2); + + printf("Parent about to read\\n"); + s = read(efd, &u, sizeof(uint64_t)); + if (s != sizeof(uint64_t)) + handle_error("read"); + printf("Parent read %llu (0x%llx) from efd\\n", + (unsigned long long) u, (unsigned long long) u); + exit(EXIT_SUCCESS); + + case \-1: + handle_error("fork"); + } +} +.EE +.SH SEE ALSO +.BR futex (2), +.BR pipe (2), +.BR poll (2), +.BR read (2), +.BR select (2), +.BR signalfd (2), +.BR timerfd_create (2), +.BR write (2), +.BR epoll (7), +.BR sem_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/eventfd2.2 b/man2/eventfd2.2 new file mode 100644 index 0000000..eddfaa8 --- /dev/null +++ b/man2/eventfd2.2 @@ -0,0 +1 @@ +.so man2/eventfd.2 diff --git a/man2/execve.2 b/man2/execve.2 new file mode 100644 index 0000000..7aaa64b --- /dev/null +++ b/man2/execve.2 @@ -0,0 +1,836 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (c) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Chastain : +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1999-11-12 by Urs Thuermann +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2006-09-04 Michael Kerrisk +.\" Added list of process attributes that are not preserved on exec(). +.\" 2007-09-14 Ollie Wild , mtk +.\" Add text describing limits on command-line arguments + environment +.\" +.TH EXECVE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +execve \- execute program +.SH SYNOPSIS +.B #include +.PP +.BI "int execve(const char *" filename ", char *const " argv "[], " +.br +.BI " char *const " envp []); +.SH DESCRIPTION +.BR execve () +executes the program pointed to by \fIfilename\fP. +\fIfilename\fP must be either a binary executable, or a script +starting with a line of the form: +.PP +.in +4n +.EX +\fB#!\fP \fIinterpreter \fP[optional-arg] +.EE +.in +.PP +For details of the latter case, see "Interpreter scripts" below. +.PP +\fIargv\fP is an array of argument strings passed to the new program. +By convention, the first of these strings (i.e., +.IR argv[0] ) +should contain the filename associated with the file being executed. +\fIenvp\fP is an array of strings, conventionally of the form +\fBkey=value\fP, which are passed as environment to the new program. +The \fIargv\fP and \fIenvp\fP arrays must each include a null pointer +at the end of the array. +.PP +The argument vector and environment can be accessed by the +called program's main function, when it is defined as: +.PP +.in +4n +.EX +int main(int argc, char *argv[], char *envp[]) +.EE +.in +.PP +Note, however, that the use of a third argument to the main function +is not specified in POSIX.1; +according to POSIX.1, +the environment should be accessed via the external variable +.BR environ (7). +.PP +.BR execve () +does not return on success, and the text, initialized data, +uninitialized data (bss), and stack of the calling process are overwritten +according to the contents of the newly loaded program. +.PP +If the current program is being ptraced, a \fBSIGTRAP\fP signal is sent to it +after a successful +.BR execve (). +.PP +If the set-user-ID bit is set on the program file pointed to by +\fIfilename\fP, +then the effective user ID of the calling process is changed +to that of the owner of the program file. +Similarly, when the set-group-ID +bit of the program file is set the effective group ID of the calling +process is set to the group of the program file. +.PP +The aforementioned transformations of the effective IDs are +.I not +performed (i.e., the set-user-ID and set-group-ID bits are ignored) +if any of the following is true: +.IP * 3 +the +.I no_new_privs +attribute is set for the calling thread (see +.BR prctl (2)); +.IP * +the underlying filesystem is mounted +.I nosuid +(the +.B MS_NOSUID +flag for +.BR mount (2)); +or +.IP * +the calling process is being ptraced. +.PP +The capabilities of the program file (see +.BR capabilities (7)) +are also ignored if any of the above are true. +.PP +The effective user ID of the process is copied to the saved set-user-ID; +similarly, the effective group ID is copied to the saved set-group-ID. +This copying takes place after any effective ID changes that occur +because of the set-user-ID and set-group-ID mode bits. +.PP +The process's real UID and real GID, as well its supplementary group IDs, +are unchanged by a call to +.BR execve (). +.PP +If the executable is an a.out dynamically linked +binary executable containing +shared-library stubs, the Linux dynamic linker +.BR ld.so (8) +is called at the start of execution to bring +needed shared objects into memory +and link the executable with them. +.PP +If the executable is a dynamically linked ELF executable, the +interpreter named in the PT_INTERP segment is used to load the needed +shared objects. +This interpreter is typically +.I /lib/ld-linux.so.2 +for binaries linked with glibc (see +.BR ld-linux.so (8)). +.PP +All process attributes are preserved during an +.BR execve (), +except the following: +.IP * 3 +The dispositions of any signals that are being caught are +reset to the default +.RB ( signal (7)). +.IP * +Any alternate signal stack is not preserved +.RB ( sigaltstack (2)). +.IP * +Memory mappings are not preserved +.RB ( mmap (2)). +.IP * +Attached System\ V shared memory segments are detached +.RB ( shmat (2)). +.IP * +POSIX shared memory regions are unmapped +.RB ( shm_open (3)). +.IP * +Open POSIX message queue descriptors are closed +.RB ( mq_overview (7)). +.IP * +Any open POSIX named semaphores are closed +.RB ( sem_overview (7)). +.IP * +POSIX timers are not preserved +.RB ( timer_create (2)). +.IP * +Any open directory streams are closed +.RB ( opendir (3)). +.IP * +Memory locks are not preserved +.RB ( mlock (2), +.BR mlockall (2)). +.IP * +Exit handlers are not preserved +.RB ( atexit (3), +.BR on_exit (3)). +.IP * +The floating-point environment is reset to the default (see +.BR fenv (3)). +.PP +The process attributes in the preceding list are all specified +in POSIX.1. +The following Linux-specific process attributes are also +not preserved during an +.BR execve (): +.IP * 3 +The +.BR prctl (2) +.B PR_SET_DUMPABLE +flag is set, +unless a set-user-ID or set-group ID program is being executed, +in which case it is cleared. +.IP * +The +.BR prctl (2) +.B PR_SET_KEEPCAPS +flag is cleared. +.IP * +(Since Linux 2.4.36 / 2.6.23) +If a set-user-ID or set-group-ID program is being executed, +then the parent death signal set by +.BR prctl (2) +.B PR_SET_PDEATHSIG +flag is cleared. +.IP * +The process name, as set by +.BR prctl (2) +.B PR_SET_NAME +(and displayed by +.IR "ps\ \-o comm" ), +is reset to the name of the new executable file. +.IP * +The +.B SECBIT_KEEP_CAPS +.I securebits +flag is cleared. +See +.BR capabilities (7). +.IP * +The termination signal is reset to +.B SIGCHLD +(see +.BR clone (2)). +.IP * +The file descriptor table is unshared, undoing the effect of the +.B CLONE_FILES +flag of +.BR clone (2). +.PP +Note the following further points: +.IP * 3 +All threads other than the calling thread are destroyed during an +.BR execve (). +Mutexes, condition variables, and other pthreads objects are not preserved. +.IP * +The equivalent of \fIsetlocale(LC_ALL, "C")\fP +is executed at program start-up. +.IP * +POSIX.1 specifies that the dispositions of any signals that +are ignored or set to the default are left unchanged. +POSIX.1 specifies one exception: if +.B SIGCHLD +is being ignored, +then an implementation may leave the disposition unchanged or +reset it to the default; Linux does the former. +.IP * +Any outstanding asynchronous I/O operations are canceled +.RB ( aio_read (3), +.BR aio_write (3)). +.IP * +For the handling of capabilities during +.BR execve (), +see +.BR capabilities (7). +.IP * +By default, file descriptors remain open across an +.BR execve (). +File descriptors that are marked close-on-exec are closed; +see the description of +.B FD_CLOEXEC +in +.BR fcntl (2). +(If a file descriptor is closed, this will cause the release +of all record locks obtained on the underlying file by this process. +See +.BR fcntl (2) +for details.) +POSIX.1 says that if file descriptors 0, 1, and 2 would +otherwise be closed after a successful +.BR execve (), +and the process would gain privilege because the set-user-ID or +set-group_ID mode bit was set on the executed file, +then the system may open an unspecified file for each of these +file descriptors. +As a general principle, no portable program, whether privileged or not, +can assume that these three file descriptors will remain +closed across an +.BR execve (). +.\" On Linux it appears that these file descriptors are +.\" always open after an execve(), and it looks like +.\" Solaris 8 and FreeBSD 6.1 are the same. -- mtk, 30 Apr 2007 +.SS Interpreter scripts +An interpreter script is a text file that has execute +permission enabled and whose first line is of the form: +.PP +.in +4n +.EX +\fB#!\fP \fIinterpreter \fP[optional-arg] +.EE +.in +.PP +The +.I interpreter +must be a valid pathname for an executable file. +If the +.I filename +argument of +.BR execve () +specifies an interpreter script, then +.I interpreter +will be invoked with the following arguments: +.PP +.in +4n +.EX +\fIinterpreter\fP [optional-arg] \fIfilename\fP arg... +.EE +.in +.PP +where +.I arg... +is the series of words pointed to by the +.I argv +argument of +.BR execve (), +starting at +.IR argv [1]. +.PP +For portable use, +.I optional-arg +should either be absent, or be specified as a single word (i.e., it +should not contain white space); see NOTES below. +.PP +Since Linux 2.6.28, +.\" commit bf2a9a39639b8b51377905397a5005f444e9a892 +the kernel permits the interpreter of a script to itself be a script. +This permission is recursive, up to a limit of four recursions, +so that the interpreter may be a script which is interpreted by a script, +and so on. +.SS Limits on size of arguments and environment +Most UNIX implementations impose some limit on the total size +of the command-line argument +.RI ( argv ) +and environment +.RI ( envp ) +strings that may be passed to a new program. +POSIX.1 allows an implementation to advertise this limit using the +.B ARG_MAX +constant (either defined in +.I +or available at run time using the call +.IR "sysconf(_SC_ARG_MAX)" ). +.PP +On Linux prior to kernel 2.6.23, the memory used to store the +environment and argument strings was limited to 32 pages +(defined by the kernel constant +.BR MAX_ARG_PAGES ). +On architectures with a 4-kB page size, +this yields a maximum size of 128\ kB. +.PP +On kernel 2.6.23 and later, most architectures support a size limit +derived from the soft +.B RLIMIT_STACK +resource limit (see +.BR getrlimit (2)) +that is in force at the time of the +.BR execve () +call. +(Architectures with no memory management unit are excepted: +they maintain the limit that was in effect before kernel 2.6.23.) +This change allows programs to have a much larger +argument and/or environment list. +.\" For some background on the changes to ARG_MAX in kernels 2.6.23 and +.\" 2.6.25, see: +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=5786 +.\" http://bugzilla.kernel.org/show_bug.cgi?id=10095 +.\" http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101, +.\" checked into 2.6.25 as commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2. +For these architectures, the total size is limited to 1/4 of the allowed +stack size. +(Imposing the 1/4-limit +ensures that the new program always has some stack space.) +.\" Ollie: That doesn't include the lists of pointers, though, +.\" so the actual usage is a bit higher (1 pointer per argument). +Since Linux 2.6.25, +the kernel places a floor of 32 pages on this size limit, +so that, even when +.BR RLIMIT_STACK +is set very low, +applications are guaranteed to have at least as much argument and +environment space as was provided by Linux 2.6.23 and earlier. +(This guarantee was not provided in Linux 2.6.23 and 2.6.24.) +Additionally, the limit per string is 32 pages (the kernel constant +.BR MAX_ARG_STRLEN ), +and the maximum number of strings is 0x7FFFFFFF. +.SH RETURN VALUE +On success, +.BR execve () +does not return, on error \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B E2BIG +The total number of bytes in the environment +.RI ( envp ) +and argument list +.RI ( argv ) +is too large. +.TP +.B EACCES +Search permission is denied on a component of the path prefix of +.I filename +or the name of a script interpreter. +(See also +.BR path_resolution (7).) +.TP +.B EACCES +The file or a script interpreter is not a regular file. +.TP +.B EACCES +Execute permission is denied for the file or a script or ELF interpreter. +.TP +.B EACCES +The filesystem is mounted +.IR noexec . +.TP +.BR EAGAIN " (since Linux 3.1)" +.\" commit 72fa59970f8698023045ab0713d66f3f4f96945c +Having changed its real UID using one of the +.BR set*uid () +calls, the caller was\(emand is now still\(emabove its +.BR RLIMIT_NPROC +resource limit (see +.BR setrlimit (2)). +For a more detailed explanation of this error, see NOTES. +.TP +.B EFAULT +.I filename +or one of the pointers in the vectors +.I argv +or +.I envp +points outside your accessible address space. +.TP +.B EINVAL +An ELF executable had more than one PT_INTERP segment (i.e., tried to +name more than one interpreter). +.TP +.B EIO +An I/O error occurred. +.TP +.B EISDIR +An ELF interpreter was a directory. +.TP +.B ELIBBAD +An ELF interpreter was not in a recognized format. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.I filename +or the name of a script or ELF interpreter. +.TP +.B ELOOP +The maximum recursion limit was reached during recursive script +interpretation (see "Interpreter scripts", above). +Before Linux 3.8, +.\" commit d740269867021faf4ce38a449353d2b986c34a67 +the error produced for this case was +.BR ENOEXEC . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +.I filename +is too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The file +.I filename +or a script or ELF interpreter does not exist, or a shared library +.\" FIXME but see http://sourceware.org/bugzilla/show_bug.cgi?id=12241 +needed for the file or interpreter cannot be found. +.TP +.B ENOEXEC +An executable is not in a recognized format, is for the wrong +architecture, or has some other format error that means it cannot be +executed. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix of +.I filename +or a script or ELF interpreter is not a directory. +.TP +.B EPERM +The filesystem is mounted +.IR nosuid , +the user is not the superuser, +and the file has the set-user-ID or set-group-ID bit set. +.TP +.B EPERM +The process is being traced, the user is not the superuser and the +file has the set-user-ID or set-group-ID bit set. +.TP +.B EPERM +A "capability-dumb" applications would not obtain the full set of +permitted capabilities granted by the executable file. +See +.BR capabilities (7). +.TP +.B ETXTBSY +The specified executable was open for writing by one or more processes. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX does not document the #! behavior, but it exists +(with some variations) on other UNIX systems. +.\" SVr4 documents additional error +.\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not +.\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, +.\" EISDIR or ELIBBAD error conditions. +.SH NOTES +Set-user-ID and set-group-ID processes can not be +.BR ptrace (2)d. +.PP +The result of mounting a filesystem +.I nosuid +varies across Linux kernel versions: +some will refuse execution of set-user-ID and set-group-ID +executables when this would +give the user powers she did not have already (and return +.BR EPERM ), +some will just ignore the set-user-ID and set-group-ID bits and +.BR exec () +successfully. +.PP +On Linux, +.I argv +and +.I envp +can be specified as NULL. +In both cases, this has the same effect as specifying the argument +as a pointer to a list containing a single null pointer. +.B "Do not take advantage of this nonstandard and nonportable misfeature!" +On many other UNIX systems, specifying +.I argv +as NULL will result in an error +.RB ( EFAULT ). +.I Some +other UNIX systems treat the +.I envp==NULL +case the same as Linux. +.\" e.g., EFAULT on Solaris 8 and FreeBSD 6.1; but +.\" HP-UX 11 is like Linux -- mtk, Apr 2007 +.\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408 +.\" Bug rejected (because fix would constitute an ABI change). +.\" +.PP +POSIX.1 says that values returned by +.BR sysconf (3) +should be invariant over the lifetime of a process. +However, since Linux 2.6.23, if the +.BR RLIMIT_STACK +resource limit changes, then the value reported by +.B _SC_ARG_MAX +will also change, +to reflect the fact that the limit on space for holding +command-line arguments and environment variables has changed. +.PP +In most cases where +.BR execve () +fails, control returns to the original executable image, +and the caller of +.BR execve () +can then handle the error. +However, in (rare) cases (typically caused by resource exhaustion), +failure may occur past the point of no return: +the original executable image has been torn down, +but the new image could not be completely built. +In such cases, the kernel kills the process with a +.BR SIGKILL +signal. +.\" +.SS Interpreter scripts +A maximum line length of 127 characters is allowed for the first line in +an interpreter script. +.PP +The semantics of the +.I optional-arg +argument of an interpreter script vary across implementations. +On Linux, the entire string following the +.I interpreter +name is passed as a single argument to the interpreter, +and this string can include white space. +However, behavior differs on some other systems. +Some systems +.\" e.g., Solaris 8 +use the first white space to terminate +.IR optional-arg . +On some systems, +.\" e.g., FreeBSD before 6.0, but not FreeBSD 6.0 onward +an interpreter script can have multiple arguments, +and white spaces in +.I optional-arg +are used to delimit the arguments. +.PP +Linux ignores the set-user-ID and set-group-ID bits on scripts. +.\" +.\" .SH BUGS +.\" Some Linux versions have failed to check permissions on ELF +.\" interpreters. This is a security hole, because it allows users to +.\" open any file, such as a rewinding tape device, for reading. Some +.\" Linux versions have also had other security holes in +.\" .BR execve () +.\" that could be exploited for denial of service by a suitably crafted +.\" ELF binary. There are no known problems with 2.0.34 or 2.2.15. +.SS execve() and EAGAIN +A more detailed explanation of the +.BR EAGAIN +error that can occur (since Linux 3.1) when calling +.BR execve () +is as follows. +.PP +The +.BR EAGAIN +error can occur when a +.I preceding +call to +.BR setuid (2), +.BR setreuid (2), +or +.BR setresuid (2) +caused the real user ID of the process to change, +and that change caused the process to exceed its +.BR RLIMIT_NPROC +resource limit (i.e., the number of processes belonging +to the new real UID exceeds the resource limit). +From Linux 2.6.0 to 3.0, this caused the +.BR set*uid () +call to fail. +(Prior to 2.6, +.\" commit 909cc4ae86f3380152a18e2a3c44523893ee11c4 +the resource limit was not imposed on processes that +changed their user IDs.) +.PP +Since Linux 3.1, the scenario just described no longer causes the +.BR set*uid () +call to fail, +because it too often led to security holes where buggy applications +didn't check the return status and assumed +that\(emif the caller had root privileges\(emthe call would always succeed. +Instead, the +.BR set*uid () +calls now successfully change the real UID, +but the kernel sets an internal flag, named +.BR PF_NPROC_EXCEEDED , +to note that the +.BR RLIMIT_NPROC +resource limit has been exceeded. +If the +.BR PF_NPROC_EXCEEDED +flag is set and the resource limit is still +exceeded at the time of a subsequent +.BR execve () +call, that call fails with the error +.BR EAGAIN . +This kernel logic ensures that the +.BR RLIMIT_NPROC +resource limit is still enforced for the +common privileged daemon workflow\(emnamely, +.BR fork (2) ++ +.BR set*uid () ++ +.BR execve (). +.PP +If the resource limit was not still exceeded at the time of the +.BR execve () +call +(because other processes belonging to this real UID terminated between the +.BR set*uid () +call and the +.BR execve () +call), then the +.BR execve () +call succeeds and the kernel clears the +.BR PF_NPROC_EXCEEDED +process flag. +The flag is also cleared if a subsequent call to +.BR fork (2) +by this process succeeds. +.SS Historical +With UNIX\ V6, the argument list of an +.BR exec () +call was ended by 0, +while the argument list of +.I main +was ended by \-1. +Thus, this argument list was not directly usable in a further +.BR exec () +call. +Since UNIX\ V7, both are NULL. +.\" +.\" .SH BUGS +.\" Some Linux versions have failed to check permissions on ELF +.\" interpreters. This is a security hole, because it allows users to +.\" open any file, such as a rewinding tape device, for reading. Some +.\" Linux versions have also had other security holes in +.\" .BR execve () +.\" that could be exploited for denial of service by a suitably crafted +.\" ELF binary. There are no known problems with 2.0.34 or 2.2.15. +.SH EXAMPLE +The following program is designed to be execed by the second program below. +It just echoes its command-line arguments, one per line. +.PP +.in +4n +.EX +/* myecho.c */ + +#include +#include + +int +main(int argc, char *argv[]) +{ + int j; + + for (j = 0; j < argc; j++) + printf("argv[%d]: %s\\n", j, argv[j]); + + exit(EXIT_SUCCESS); +} +.EE +.in +.PP +This program can be used to exec the program named in its command-line +argument: +.PP +.in +4n +.EX +/* execve.c */ + +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + char *newargv[] = { NULL, "hello", "world", NULL }; + char *newenviron[] = { NULL }; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + newargv[0] = argv[1]; + + execve(argv[1], newargv, newenviron); + perror("execve"); /* execve() returns only on error */ + exit(EXIT_FAILURE); +} +.EE +.in +.PP +We can use the second program to exec the first as follows: +.PP +.in +4n +.EX +.RB "$" " cc myecho.c \-o myecho" +.RB "$" " cc execve.c \-o execve" +.RB "$" " ./execve ./myecho" +argv[0]: ./myecho +argv[1]: hello +argv[2]: world +.EE +.in +.PP +We can also use these programs to demonstrate the use of a script +interpreter. +To do this we create a script whose "interpreter" is our +.I myecho +program: +.PP +.in +4n +.EX +.RB "$" " cat > script" +.B #!./myecho script-arg +.B ^D +.RB "$" " chmod +x script" +.EE +.in +.PP +We can then use our program to exec the script: +.PP +.in +4n +.EX +.RB "$" " ./execve ./script" +argv[0]: ./myecho +argv[1]: script-arg +argv[2]: ./script +argv[3]: hello +argv[4]: world +.EE +.in +.SH SEE ALSO +.BR chmod (2), +.BR execveat (2), +.BR fork (2), +.BR get_robust_list (2), +.BR ptrace (2), +.BR execl (3), +.BR fexecve (3), +.BR getopt (3), +.BR system (3), +.BR credentials (7), +.BR environ (7), +.BR path_resolution (7), +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/execveat.2 b/man2/execveat.2 new file mode 100644 index 0000000..3fe297b --- /dev/null +++ b/man2/execveat.2 @@ -0,0 +1,241 @@ +.\" Copyright (c) 2014 Google, Inc., written by David Drysdale +.\" and Copyright (c) 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH EXECVEAT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +execveat \- execute program relative to a directory file descriptor +.SH SYNOPSIS +.B #include +.PP +.BI "int execveat(int " dirfd ", const char *" pathname "," +.br +.BI " char *const " argv "[], char *const " envp "[]," +.br +.BI " int " flags ); +.SH DESCRIPTION +.\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874 +The +.BR execveat () +system call executes the program referred to by the combination of +.I dirfd +and +.IR pathname . +It operates in exactly the same way as +.BR execve (2), +except for the differences described in this manual page. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR execve (2) +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR execve (2)). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +If +.I pathname +is an empty string and the +.BR AT_EMPTY_PATH +flag is specified, then the file descriptor +.I dirfd +specifies the file to be executed (i.e., +.IR dirfd +refers to an executable file, rather than a directory). +.PP +The +.I flags +argument is a bit mask that can include zero or more of the following flags: +.TP +.BR AT_EMPTY_PATH +If +.I pathname +is an empty string, operate on the file referred to by +.IR dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +.TP +.B AT_SYMLINK_NOFOLLOW +If the file identified by +.I dirfd +and a non-NULL +.I pathname +is a symbolic link, then the call fails with the error +.BR ELOOP . +.SH RETURN VALUE +On success, +.BR execveat () +does not return. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +The same errors that occur for +.BR execve (2) +can also occur for +.BR execveat (). +The following additional errors can occur for +.BR execveat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B ELOOP +.I flags +includes +.BR AT_SYMLINK_NOFOLLOW +and the file identified by +.I dirfd +and a non-NULL +.I pathname +is a symbolic link. +.TP +.B ENOENT +The program identified by +.I dirfd +and +.I pathname +requires the use of an interpreter program +(such as a script starting with "#!"), but the file descriptor +.I dirfd +was opened with the +.B O_CLOEXEC +flag, with the result that +the program file is inaccessible to the launched interpreter. +See BUGS. +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR execveat () +was added to Linux in kernel 3.19. +GNU C library support is pending. +.\" FIXME . check for glibc support in a future release +.SH CONFORMING TO +The +.BR execveat () +system call is Linux-specific. +.SH NOTES +In addition to the reasons explained in +.BR openat (2), +the +.BR execveat () +system call is also needed to allow +.BR fexecve (3) +to be implemented on systems that do not have the +.I /proc +filesystem mounted. +.PP +When asked to execute a script file, the +.IR argv[0] +that is passed to the script interpreter is a string of the form +.IR /dev/fd/N +or +.IR /dev/fd/N/P , +where +.I N +is the number of the file descriptor passed via the +.IR dirfd +argument. +A string of the first form occurs when +.BR AT_EMPTY_PATH +is employed. +A string of the second form occurs when the script is specified via both +.IR dirfd +and +.IR pathname ; +in this case, +.IR P +is the value given in +.IR pathname . +.PP +For the same reasons described in +.BR fexecve (3), +the natural idiom when using +.BR execveat () +is to set the close-on-exec flag on +.IR dirfd . +(But see BUGS.) +.SH BUGS +The +.B ENOENT +error described above means that it is not possible to set the +close-on-exec flag on the file descriptor given to a call of the form: +.PP + execveat(fd, "", argv, envp, AT_EMPTY_PATH); +.PP +However, the inability to set the close-on-exec flag means that a file +descriptor referring to the script leaks through to the script itself. +As well as wasting a file descriptor, +this leakage can lead to file-descriptor exhaustion in scenarios +where scripts recursively employ +.BR execveat (). +.\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML +.\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229): +.\" +.\" Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\" for execveat(2 +.\" Date: Mon, 24 Nov 2014 11:53:59 +0000 +.SH SEE ALSO +.BR execve (2), +.BR openat (2), +.BR fexecve (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/exit.2 b/man2/exit.2 new file mode 100644 index 0000000..9f9d2e7 --- /dev/null +++ b/man2/exit.2 @@ -0,0 +1 @@ +.so man2/_exit.2 diff --git a/man2/exit_group.2 b/man2/exit_group.2 new file mode 100644 index 0000000..1567f04 --- /dev/null +++ b/man2/exit_group.2 @@ -0,0 +1,59 @@ +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH EXIT_GROUP 2 2008-11-27 "Linux" "Linux Programmer's Manual" +.SH NAME +exit_group \- exit all threads in a process +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void exit_group(int " status ); +.fi +.SH DESCRIPTION +This system call is equivalent to +.BR _exit (2) +except that it terminates not only the calling thread, but all threads +in the calling process's thread group. +.SH RETURN VALUE +This system call does not return. +.SH VERSIONS +This call is present since Linux 2.5.35. +.SH CONFORMING TO +This call is Linux-specific. +.SH NOTES +Since glibc 2.3, this is the system call invoked when the +.BR _exit (2) +wrapper function is called. +.SH SEE ALSO +.BR exit (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/faccessat.2 b/man2/faccessat.2 new file mode 100644 index 0000000..9d4f76e --- /dev/null +++ b/man2/faccessat.2 @@ -0,0 +1 @@ +.so man2/access.2 diff --git a/man2/fadvise64.2 b/man2/fadvise64.2 new file mode 100644 index 0000000..53f54a1 --- /dev/null +++ b/man2/fadvise64.2 @@ -0,0 +1 @@ +.so man2/posix_fadvise.2 diff --git a/man2/fadvise64_64.2 b/man2/fadvise64_64.2 new file mode 100644 index 0000000..53f54a1 --- /dev/null +++ b/man2/fadvise64_64.2 @@ -0,0 +1 @@ +.so man2/posix_fadvise.2 diff --git a/man2/fallocate.2 b/man2/fallocate.2 new file mode 100644 index 0000000..de9401b --- /dev/null +++ b/man2/fallocate.2 @@ -0,0 +1,483 @@ +.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved +.\" Written by Dave Chinner +.\" +.\" %%%LICENSE_START(GPLv2_ONELINE) +.\" May be distributed as per GNU General Public License version 2. +.\" %%%LICENSE_END +.\" +.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE +.\" 2011-09-19: Substantial restructuring of the page +.\" +.TH FALLOCATE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +fallocate \- manipulate file space +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int fallocate(int " fd ", int " mode ", off_t " offset \ +", off_t " len "); +.fi +.SH DESCRIPTION +This is a nonportable, Linux-specific system call. +For the portable, POSIX.1-specified method of ensuring that space +is allocated for a file, see +.BR posix_fallocate (3). +.PP +.BR fallocate () +allows the caller to directly manipulate the allocated disk space +for the file referred to by +.I fd +for the byte range starting at +.I offset +and continuing for +.I len +bytes. +.PP +The +.I mode +argument determines the operation to be performed on the given range. +Details of the supported operations are given in the subsections below. +.SS Allocating disk space +The default operation (i.e., +.I mode +is zero) of +.BR fallocate () +allocates the disk space within the range specified by +.I offset +and +.IR len . +The file size (as reported by +.BR stat (2)) +will be changed if +.IR offset + len +is greater than the file size. +Any subregion within the range specified by +.I offset +and +.IR len +that did not contain data before the call will be initialized to zero. +This default behavior closely resembles the behavior of the +.BR posix_fallocate (3) +library function, +and is intended as a method of optimally implementing that function. +.PP +After a successful call, subsequent writes into the range specified by +.IR offset +and +.IR len +are guaranteed not to fail because of lack of disk space. +.PP +If the +.B FALLOC_FL_KEEP_SIZE +flag is specified in +.IR mode , +the behavior of the call is similar, +but the file size will not be changed even if +.IR offset + len +is greater than the file size. +Preallocating zeroed blocks beyond the end of the file in this manner +is useful for optimizing append workloads. +.PP +If the +.B FALLOC_FL_UNSHARE +flag is specified in +.IR mode , +shared file data extents will be made private to the file to guarantee +that a subsequent write will not fail due to lack of space. +Typically, this will be done by performing a copy-on-write operation on +all shared data in the file. +This flag may not be supported by all filesystems. +.PP +Because allocation is done in block size chunks, +.BR fallocate () +may allocate a larger range of disk space than was specified. +.SS Deallocating file space +Specifying the +.BR FALLOC_FL_PUNCH_HOLE +flag (available since Linux 2.6.38) in +.I mode +deallocates space (i.e., creates a hole) +in the byte range starting at +.I offset +and continuing for +.I len +bytes. +Within the specified range, partial filesystem blocks are zeroed, +and whole filesystem blocks are removed from the file. +After a successful call, +subsequent reads from this range will return zeroes. +.PP +The +.BR FALLOC_FL_PUNCH_HOLE +flag must be ORed with +.BR FALLOC_FL_KEEP_SIZE +in +.IR mode ; +in other words, even when punching off the end of the file, the file size +(as reported by +.BR stat (2)) +does not change. +.PP +Not all filesystems support +.BR FALLOC_FL_PUNCH_HOLE ; +if a filesystem doesn't support the operation, an error is returned. +The operation is supported on at least the following filesystems: +.IP * 3 +XFS (since Linux 2.6.38) +.IP * +ext4 (since Linux 3.0) +.\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622 +.IP * +Btrfs (since Linux 3.7) +.IP * +.BR tmpfs "(5) (since Linux 3.5)" +.\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe +.SS Collapsing file space +.\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841 +Specifying the +.BR FALLOC_FL_COLLAPSE_RANGE +flag (available since Linux 3.15) in +.I mode +removes a byte range from a file, without leaving a hole. +The byte range to be collapsed starts at +.I offset +and continues for +.I len +bytes. +At the completion of the operation, +the contents of the file starting at the location +.I offset+len +will be appended at the location +.IR offset , +and the file will be +.I len +bytes smaller. +.PP +A filesystem may place limitations on the granularity of the operation, +in order to ensure efficient implementation. +Typically, +.I offset +and +.I len +must be a multiple of the filesystem logical block size, +which varies according to the filesystem type and configuration. +If a filesystem has such a requirement, +.BR fallocate () +fails with the error +.BR EINVAL +if this requirement is violated. +.PP +If the region specified by +.I offset +plus +.I len +reaches or passes the end of file, an error is returned; +instead, use +.BR ftruncate (2) +to truncate a file. +.PP +No other flags may be specified in +.IR mode +in conjunction with +.BR FALLOC_FL_COLLAPSE_RANGE . +.PP +As at Linux 3.15, +.B FALLOC_FL_COLLAPSE_RANGE +is supported by +ext4 (only for extent-based files) +.\" commit 9eb79482a97152930b113b51dff530aba9e28c8e +and XFS. +.\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d +.SS Zeroing file space +Specifying the +.BR FALLOC_FL_ZERO_RANGE +flag (available since Linux 3.15) +.\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642 +in +.I mode +zeroes space in the byte range starting at +.I offset +and continuing for +.I len +bytes. +Within the specified range, blocks are preallocated for the regions +that span the holes in the file. +After a successful call, subsequent +reads from this range will return zeroes. +.PP +Zeroing is done within the filesystem preferably by converting the range into +unwritten extents. +This approach means that the specified range will not be physically zeroed +out on the device (except for partial blocks at the either end of the range), +and I/O is (otherwise) required only to update metadata. +.PP +If the +.B FALLOC_FL_KEEP_SIZE +flag is additionally specified in +.IR mode , +the behavior of the call is similar, +but the file size will not be changed even if +.IR offset + len +is greater than the file size. +This behavior is the same as when preallocating space with +.B FALLOC_FL_KEEP_SIZE +specified. +.PP +Not all filesystems support +.BR FALLOC_FL_ZERO_RANGE ; +if a filesystem doesn't support the operation, an error is returned. +The operation is supported on at least the following filesystems: +.IP * 3 +XFS (since Linux 3.15) +.\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa +.IP * +ext4, for extent-based files (since Linux 3.15) +.\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0 +.IP * +SMB3 (since Linux 3.17) +.\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556 +.SS Increasing file space +Specifying the +.BR FALLOC_FL_INSERT_RANGE +flag +(available since Linux 4.1) +.\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d +in +.I mode +increases the file space by inserting a hole within the file size without +overwriting any existing data. +The hole will start at +.I offset +and continue for +.I len +bytes. +When inserting the hole inside file, the contents of the file starting at +.I offset +will be shifted upward (i.e., to a higher file offset) by +.I len +bytes. +Inserting a hole inside a file increases the file size by +.I len +bytes. +.PP +This mode has the same limitations as +.BR FALLOC_FL_COLLAPSE_RANGE +regarding the granularity of the operation. +If the granularity requirements are not met, +.BR fallocate () +fails with the error +.BR EINVAL. +If the +.I offset +is equal to or greater than the end of file, an error is returned. +For such operations (i.e., inserting a hole at the end of file), +.BR ftruncate (2) +should be used. +.PP +No other flags may be specified in +.IR mode +in conjunction with +.BR FALLOC_FL_INSERT_RANGE . +.PP +.B FALLOC_FL_INSERT_RANGE +requires filesystem support. +Filesystems that support this operation include +XFS (since Linux 4.1) +.\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b +and ext4 (since Linux 4.2). +.\" commit 331573febb6a224bc50322e3670da326cb7f4cfc +.\" f2fs also has support since Linux 4.2 +.\" commit f62185d0e283e9d311e3ac1020f159d95f0aab39 +.SH RETURN VALUE +On success, +.BR fallocate () +returns zero. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor, or is not opened for writing. +.TP +.B EFBIG +.IR offset + len +exceeds the maximum file size. +.TP +.B EFBIG +.I mode +is +.BR FALLOC_FL_INSERT_RANGE , +and the current file size+\fIlen\fP exceeds the maximum file size. +.TP +.B EINTR +A signal was caught during execution; see +.BR signal (7). +.TP +.B EINVAL +.I offset +was less than 0, or +.I len +.\" FIXME . (raise a kernel bug) Probably the len==0 case should be +.\" a no-op, rather than an error. That would be consistent with +.\" similar APIs for the len==0 case. +.\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition" +.\" 21 Sep 2012 +.\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526 +was less than or equal to 0. +.TP +.B EINVAL +.I mode +is +.BR FALLOC_FL_COLLAPSE_RANGE +and the range specified by +.I offset +plus +.I len +reaches or passes the end of the file. +.TP +.B EINVAL +.I mode +is +.BR FALLOC_FL_INSERT_RANGE +and the range specified by +.I offset +reaches or passes the end of the file. +.TP +.B EINVAL +.I mode +is +.BR FALLOC_FL_COLLAPSE_RANGE +or +.BR FALLOC_FL_INSERT_RANGE , +but either +.I offset +or +.I len +is not a multiple of the filesystem block size. +.TP +.B EINVAL +.I mode +contains one of +.B FALLOC_FL_COLLAPSE_RANGE +or +.B FALLOC_FL_INSERT_RANGE +and also other flags; +no other flags are permitted with +.BR FALLOC_FL_COLLAPSE_RANGE +or +.BR FALLOC_FL_INSERT_RANGE . +.TP +.B EINVAL +.I mode +is +.BR FALLOC_FL_COLLAPSE_RANGE +or +.BR FALLOC_FL_ZERO_RANGE +or +.BR FALLOC_FL_INSERT_RANGE , +but the file referred to by +.I fd +is not a regular file. +.\" There was an inconsistency in 3.15-rc1, that should be resolved so that all +.\" filesystems use this error for this case. (Tytso says ex4 will change.) +.\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521 +.\" From: Michael Kerrisk (man-pages +.\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate +.\" Newsgroups: gmane.linux.man, gmane.linux.file-systems +.\" Date: 2014-04-17 13:40:05 GMT +.TP +.B EIO +An I/O error occurred while reading from or writing to a filesystem. +.TP +.B ENODEV +.I fd +does not refer to a regular file or a directory. +(If +.I fd +is a pipe or FIFO, a different error results.) +.TP +.B ENOSPC +There is not enough space left on the device containing the file +referred to by +.IR fd . +.TP +.B ENOSYS +This kernel does not implement +.BR fallocate (). +.TP +.B EOPNOTSUPP +The filesystem containing the file referred to by +.I fd +does not support this operation; +or the +.I mode +is not supported by the filesystem containing the file referred to by +.IR fd . +.TP +.B EPERM +The file referred to by +.I fd +is marked immutable (see +.BR chattr (1)). +.TP +.B EPERM +.I mode +specifies +.BR FALLOC_FL_PUNCH_HOLE +or +.BR FALLOC_FL_COLLAPSE_RANGE +or +.BR FALLOC_FL_INSERT_RANGE +and +the file referred to by +.I fd +is marked append-only +(see +.BR chattr (1)). +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B ESPIPE +.I fd +refers to a pipe or FIFO. +.TP +.B ETXTBSY +.I mode +specifies +.BR FALLOC_FL_COLLAPSE_RANGE +or +.BR FALLOC_FL_INSERT_RANGE , +but the file referred to by +.IR fd +is currently being executed. +.SH VERSIONS +.BR fallocate () +is available on Linux since kernel 2.6.23. +Support is provided by glibc since version 2.10. +The +.BR FALLOC_FL_* +flags are defined in glibc headers only since version 2.18. +.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964 +.SH CONFORMING TO +.BR fallocate () +is Linux-specific. +.SH SEE ALSO +.BR fallocate (1), +.BR ftruncate (2), +.BR posix_fadvise (3), +.BR posix_fallocate (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 new file mode 100644 index 0000000..606d000 --- /dev/null +++ b/man2/fanotify_init.2 @@ -0,0 +1,274 @@ +.\" Copyright (C) 2013, Heinrich Schuchardt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.TH FANOTIFY_INIT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +fanotify_init \- create and initialize fanotify group +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ); +.SH DESCRIPTION +For an overview of the fanotify API, see +.BR fanotify (7). +.PP +.BR fanotify_init () +initializes a new fanotify group and returns a file descriptor for the event +queue associated with the group. +.PP +The file descriptor is used in calls to +.BR fanotify_mark (2) +to specify the files, directories, and mounts for which fanotify events +shall be created. +These events are received by reading from the file descriptor. +Some events are only informative, indicating that a file has been accessed. +Other events can be used to determine whether +another application is permitted to access a file or directory. +Permission to access filesystem objects is granted by writing to the file +descriptor. +.PP +Multiple programs may be using the fanotify interface at the same time to +monitor the same files. +.PP +In the current implementation, the number of fanotify groups per user is +limited to 128. +This limit cannot be overridden. +.PP +Calling +.BR fanotify_init () +requires the +.B CAP_SYS_ADMIN +capability. +This constraint might be relaxed in future versions of the API. +Therefore, certain additional capability checks have been implemented as +indicated below. +.PP +The +.I flags +argument contains a multi-bit field defining the notification class of the +listening application and further single bit fields specifying the behavior +of the file descriptor. +.PP +If multiple listeners for permission events exist, +the notification class is used to establish the sequence +in which the listeners receive the events. +.PP +Only one of the following notification classes may be specified in +.IR flags : +.TP +.B FAN_CLASS_PRE_CONTENT +This value allows the receipt of events notifying that a file has been +accessed and events for permission decisions if a file may be accessed. +It is intended for event listeners that need to access files before they +contain their final data. +This notification class might be used by hierarchical storage managers, +for example. +.TP +.B FAN_CLASS_CONTENT +This value allows the receipt of events notifying that a file has been +accessed and events for permission decisions if a file may be accessed. +It is intended for event listeners that need to access files when they +already contain their final content. +This notification class might be used by malware detection programs, for +example. +.TP +.B FAN_CLASS_NOTIF +This is the default value. +It does not need to be specified. +This value only allows the receipt of events notifying that a file has been +accessed. +Permission decisions before the file is accessed are not possible. +.PP +Listeners with different notification classes will receive events in the +order +.BR FAN_CLASS_PRE_CONTENT , +.BR FAN_CLASS_CONTENT , +.BR FAN_CLASS_NOTIF . +The order of notification for listeners in the same notification class +is undefined. +.PP +The following bits can additionally be set in +.IR flags : +.TP +.B FAN_CLOEXEC +Set the close-on-exec flag +.RB ( FD_CLOEXEC ) +on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2). +.TP +.B FAN_NONBLOCK +Enable the nonblocking flag +.RB ( O_NONBLOCK ) +for the file descriptor. +Reading from the file descriptor will not block. +Instead, if no data is available, +.BR read (2) +fails with the error +.BR EAGAIN . +.TP +.B FAN_UNLIMITED_QUEUE +Remove the limit of 16384 events for the event queue. +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.TP +.B FAN_UNLIMITED_MARKS +Remove the limit of 8192 marks. +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.PP +The +.I event_f_flags +argument +defines the file status flags that will be set on the open file descriptions +that are created for fanotify events. +For details of these flags, see the description of the +.I flags +values in +.BR open (2). +.I event_f_flags +includes a multi-bit field for the access mode. +This field can take the following values: +.TP +.B O_RDONLY +This value allows only read access. +.TP +.B O_WRONLY +This value allows only write access. +.TP +.B O_RDWR +This value allows read and write access. +.PP +Additional bits can be set in +.IR event_f_flags . +The most useful values are: +.TP +.B O_LARGEFILE +Enable support for files exceeding 2\ GB. +Failing to set this flag will result in an +.B EOVERFLOW +error when trying to open a large file which is monitored by +an fanotify group on a 32-bit system. +.TP +.BR O_CLOEXEC " (since Linux 3.18)" +.\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 +Enable the close-on-exec flag for the file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.PP +The following are also allowable: +.BR O_APPEND , +.BR O_DSYNC , +.BR O_NOATIME , +.BR O_NONBLOCK , +and +.BR O_SYNC . +Specifying any other flag in +.I event_f_flags +yields the error +.B EINVAL +(but see BUGS). +.SH RETURN VALUE +On success, +.BR fanotify_init () +returns a new file descriptor. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An invalid value was passed in +.I flags +or +.IR event_f_flags . +.B FAN_ALL_INIT_FLAGS +defines all allowable bits for +.IR flags . +.TP +.B EMFILE +The number of fanotify groups for this user exceeds 128. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENOMEM +The allocation of memory for the notification group failed. +.TP +.B ENOSYS +This kernel does not implement +.BR fanotify_init (). +The fanotify API is available only if the kernel was configured with +.BR CONFIG_FANOTIFY . +.TP +.B EPERM +The operation is not permitted because the caller lacks the +.B CAP_SYS_ADMIN +capability. +.SH VERSIONS +.BR fanotify_init () +was introduced in version 2.6.36 of the Linux kernel and enabled in version +2.6.37. +.SH CONFORMING TO +This system call is Linux-specific. +.SH BUGS +The following bug was present in Linux kernels before version 3.18: +.IP * 3 +.\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 +The +.B O_CLOEXEC +is ignored when passed in +.IR event_f_flags . +.PP +The following bug was present in Linux kernels before version 3.14: +.IP * 3 +.\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 +The +.I event_f_flags +argument is not checked for invalid flags. +Flags that are intended only for internal use, +such as +.BR FMODE_EXEC , +can be set, and will consequently be set for the file descriptors +returned when reading from the fanotify file descriptor. +.SH SEE ALSO +.BR fanotify_mark (2), +.BR fanotify (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 new file mode 100644 index 0000000..681b3a6 --- /dev/null +++ b/man2/fanotify_mark.2 @@ -0,0 +1,349 @@ +.\" Copyright (C) 2013, Heinrich Schuchardt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.TH FANOTIFY_MARK 2 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem +object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags , +.BI " uint64_t " mask ", int " dirfd \ +", const char *" pathname ); +.fi +.SH DESCRIPTION +For an overview of the fanotify API, see +.BR fanotify (7). +.PP +.BR fanotify_mark () +adds, removes, or modifies an fanotify mark on a filesystem object. +The caller must have read permission on the filesystem object that +is to be marked. +.PP +The +.I fanotify_fd +argument is a file descriptor returned by +.BR fanotify_init (2). +.PP +.I flags +is a bit mask describing the modification to perform. +It must include exactly one of the following values: +.TP +.B FAN_MARK_ADD +The events in +.I mask +will be added to the mark mask (or to the ignore mask). +.I mask +must be nonempty or the error +.B EINVAL +will occur. +.TP +.B FAN_MARK_REMOVE +The events in argument +.I mask +will be removed from the mark mask (or from the ignore mask). +.I mask +must be nonempty or the error +.B EINVAL +will occur. +.TP +.B FAN_MARK_FLUSH +Remove either all mount or all non-mount marks from the fanotify group. +If +.I flags +contains +.BR FAN_MARK_MOUNT , +all marks for mounts are removed from the group. +Otherwise, all marks for directories and files are removed. +No flag other than +.B FAN_MARK_MOUNT +can be used in conjunction with +.BR FAN_MARK_FLUSH . +.I mask +is ignored. +.PP +If none of the values above is specified, or more than one is specified, +the call fails with the error +.BR EINVAL . +.PP +In addition, +zero or more of the following values may be ORed into +.IR flags : +.TP +.B FAN_MARK_DONT_FOLLOW +If +.I pathname +is a symbolic link, mark the link itself, rather than the file to which it +refers. +(By default, +.BR fanotify_mark () +dereferences +.I pathname +if it is a symbolic link.) +.TP +.B FAN_MARK_ONLYDIR +If the filesystem object to be marked is not a directory, the error +.B ENOTDIR +shall be raised. +.TP +.B FAN_MARK_MOUNT +Mark the mount point specified by +.IR pathname . +If +.I pathname +is not itself a mount point, the mount point containing +.I pathname +will be marked. +All directories, subdirectories, and the contained files of the mount point +will be monitored. +.TP +.B FAN_MARK_IGNORED_MASK +The events in +.I mask +shall be added to or removed from the ignore mask. +.TP +.B FAN_MARK_IGNORED_SURV_MODIFY +The ignore mask shall survive modify events. +If this flag is not set, +the ignore mask is cleared when a modify event occurs +for the ignored file or directory. +.PP +.I mask +defines which events shall be listened for (or which shall be ignored). +It is a bit mask composed of the following values: +.TP +.B FAN_ACCESS +Create an event when a file or directory (but see BUGS) is accessed (read). +.TP +.B FAN_MODIFY +Create an event when a file is modified (write). +.TP +.B FAN_CLOSE_WRITE +Create an event when a writable file is closed. +.TP +.B FAN_CLOSE_NOWRITE +Create an event when a read-only file or directory is closed. +.TP +.B FAN_OPEN +Create an event when a file or directory is opened. +.TP +.B FAN_Q_OVERFLOW +Create an event when an overflow of the event queue occurs. +The size of the event queue is limited to 16384 entries if +.B FAN_UNLIMITED_QUEUE +is not set in +.BR fanotify_init (2). +.TP +.B FAN_OPEN_PERM +Create an event when a permission to open a file or directory is requested. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +or +.B FAN_CLASS_CONTENT +is required. +.TP +.B FAN_ACCESS_PERM +Create an event when a permission to read a file or directory is requested. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +or +.B FAN_CLASS_CONTENT +is required. +.TP +.B FAN_ONDIR +Create events for directories\(emfor example, when +.BR opendir (3), +.BR readdir (3) +(but see BUGS), and +.BR closedir (3) +are called. +Without this flag, only events for files are created. +.TP +.B FAN_EVENT_ON_CHILD +Events for the immediate children of marked directories shall be created. +The flag has no effect when marking mounts. +Note that events are not generated for children of the subdirectories +of marked directories. +To monitor complete directory trees it is necessary to mark the relevant +mount. +.PP +The following composed value is defined: +.TP +.B FAN_CLOSE +A file is closed +.RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ). +.PP +The filesystem object to be marked is determined by the file descriptor +.I dirfd +and the pathname specified in +.IR pathname : +.IP * 3 +If +.I pathname +is NULL, +.I dirfd +defines the filesystem object to be marked. +.IP * +If +.I pathname +is NULL, and +.I dirfd +takes the special value +.BR AT_FDCWD , +the current working directory is to be marked. +.IP * +If +.I pathname +is absolute, it defines the filesystem object to be marked, and +.I dirfd +is ignored. +.IP * +If +.I pathname +is relative, and +.I dirfd +does not have the value +.BR AT_FDCWD , +then the filesystem object to be marked is determined by interpreting +.I pathname +relative the directory referred to by +.IR dirfd . +.IP * +If +.I pathname +is relative, and +.I dirfd +has the value +.BR AT_FDCWD , +then the filesystem object to be marked is determined by interpreting +.I pathname +relative the current working directory. +.SH RETURN VALUE +On success, +.BR fanotify_mark () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +An invalid file descriptor was passed in +.IR fanotify_fd . +.TP +.B EINVAL +An invalid value was passed in +.IR flags +or +.IR mask , +or +.I fanotify_fd +was not an fanotify file descriptor. +.TP +.B EINVAL +The fanotify file descriptor was opened with +.B FAN_CLASS_NOTIF +and mask contains a flag for permission events +.RB ( FAN_OPEN_PERM +or +.BR FAN_ACCESS_PERM ). +.TP +.B ENOENT +The filesystem object indicated by +.IR dirfd +and +.IR pathname +does not exist. +This error also occurs when trying to remove a mark from an object +which is not marked. +.TP +.B ENOMEM +The necessary memory could not be allocated. +.TP +.B ENOSPC +The number of marks exceeds the limit of 8192 and the +.B FAN_UNLIMITED_MARKS +flag was not specified when the fanotify file descriptor was created with +.BR fanotify_init (2). +.TP +.B ENOSYS +This kernel does not implement +.BR fanotify_mark (). +The fanotify API is available only if the kernel was configured with +.BR CONFIG_FANOTIFY . +.TP +.B ENOTDIR +.I flags +contains +.BR FAN_MARK_ONLYDIR , +and +.I dirfd +and +.I pathname +do not specify a directory. +.SH VERSIONS +.BR fanotify_mark () +was introduced in version 2.6.36 of the Linux kernel and enabled in version +2.6.37. +.SH CONFORMING TO +This system call is Linux-specific. +.SH BUGS +The following bugs were present in Linux kernels before version 3.16: +.IP * 3 +.\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563 +If +.I flags +contains +.BR FAN_MARK_FLUSH , +.I dirfd +and +.I pathname +must specify a valid filesystem object, even though this object is not used. +.IP * +.\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b +.BR readdir (2) +does not generate a +.B FAN_ACCESS +event. +.IP * +.\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406 +If +.BR fanotify_mark () +is called with +.BR FAN_MARK_FLUSH , +.I flags +is not checked for invalid values. +.SH SEE ALSO +.BR fanotify_init (2), +.BR fanotify (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/fattach.2 b/man2/fattach.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/fattach.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/fchdir.2 b/man2/fchdir.2 new file mode 100644 index 0000000..60b9685 --- /dev/null +++ b/man2/fchdir.2 @@ -0,0 +1 @@ +.so man2/chdir.2 diff --git a/man2/fchmod.2 b/man2/fchmod.2 new file mode 100644 index 0000000..92647d2 --- /dev/null +++ b/man2/fchmod.2 @@ -0,0 +1 @@ +.so man2/chmod.2 diff --git a/man2/fchmodat.2 b/man2/fchmodat.2 new file mode 100644 index 0000000..92647d2 --- /dev/null +++ b/man2/fchmodat.2 @@ -0,0 +1 @@ +.so man2/chmod.2 diff --git a/man2/fchown.2 b/man2/fchown.2 new file mode 100644 index 0000000..f0a5635 --- /dev/null +++ b/man2/fchown.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man2/fchown32.2 b/man2/fchown32.2 new file mode 100644 index 0000000..b8b9452 --- /dev/null +++ b/man2/fchown32.2 @@ -0,0 +1 @@ +.so man2/fchown.2 diff --git a/man2/fchownat.2 b/man2/fchownat.2 new file mode 100644 index 0000000..f0a5635 --- /dev/null +++ b/man2/fchownat.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man2/fcntl.2 b/man2/fcntl.2 new file mode 100644 index 0000000..9829805 --- /dev/null +++ b/man2/fcntl.2 @@ -0,0 +1,2111 @@ +'\" t +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson; +.\" and Copyright (C) 1998 Jamie Lokier; +.\" and Copyright (C) 2002-2010, 2014 Michael Kerrisk; +.\" and Copyright (C) 2014 Jeff Layton +.\" and Copyright (C) 2014 David Herrmann +.\" and Copyright (C) 2017 Jens Axboe +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-09-26 by Andries Brouwer +.\" and again on 960413 and 980804 and 981223. +.\" Modified 1998-12-11 by Jamie Lokier +.\" Applied correction by Christian Ehrhardt - aeb, 990712 +.\" Modified 2002-04-23 by Michael Kerrisk +.\" Added note on F_SETFL and O_DIRECT +.\" Complete rewrite + expansion of material on file locking +.\" Incorporated description of F_NOTIFY, drawing on +.\" Stephen Rothwell's notes in Documentation/dnotify.txt. +.\" Added description of F_SETLEASE and F_GETLEASE +.\" Corrected and polished, aeb, 020527. +.\" Modified 2004-03-03 by Michael Kerrisk +.\" Modified description of file leases: fixed some errors of detail +.\" Replaced the term "lease contestant" by "lease breaker" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool +.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb. +.\" 2005-04-08 Jamie Lokier , mtk +.\" Described behavior of F_SETOWN/F_SETSIG in +.\" multithreaded processes, and generally cleaned +.\" up the discussion of F_SETOWN. +.\" 2005-05-20, Johannes Nicolai , +.\" mtk: Noted F_SETOWN bug for socket file descriptor in Linux 2.4 +.\" and earlier. Added text on permissions required to send signal. +.\" 2009-09-30, Michael Kerrisk +.\" Note obsolete F_SETOWN behavior with threads. +.\" Document F_SETOWN_EX and F_GETOWN_EX +.\" 2010-06-17, Michael Kerrisk +.\" Document F_SETPIPE_SZ and F_GETPIPE_SZ. +.\" 2014-07-08, David Herrmann +.\" Document F_ADD_SEALS and F_GET_SEALS +.\" 2017-06-26, Jens Axboe +.\" Document F_{GET,SET}_RW_HINT and F_{GET,SET}_FILE_RW_HINT +.\" +.TH FCNTL 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +fcntl \- manipulate file descriptor +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );" +.fi +.SH DESCRIPTION +.BR fcntl () +performs one of the operations described below on the open file descriptor +.IR fd . +The operation is determined by +.IR cmd . +.PP +.BR fcntl () +can take an optional third argument. +Whether or not this argument is required is determined by +.IR cmd . +The required argument type is indicated in parentheses after each +.I cmd +name (in most cases, the required type is +.IR int , +and we identify the argument using the name +.IR arg ), +or +.I void +is specified if the argument is not required. +.PP +Certain of the operations below are supported only since a particular +Linux kernel version. +The preferred method of checking whether the host kernel supports +a particular operation is to invoke +.BR fcntl () +with the desired +.IR cmd +value and then test whether the call failed with +.BR EINVAL , +indicating that the kernel does not recognize this value. +.SS Duplicating a file descriptor +.TP +.BR F_DUPFD " (\fIint\fP)" +Duplicate the file descriptor +.IR fd +using the lowest-numbered available file descriptor greater than or equal to +.IR arg . +This is different from +.BR dup2 (2), +which uses exactly the file descriptor specified. +.IP +On success, the new file descriptor is returned. +.IP +See +.BR dup (2) +for further details. +.TP +.BR F_DUPFD_CLOEXEC " (\fIint\fP; since Linux 2.6.24)" +As for +.BR F_DUPFD , +but additionally set the +close-on-exec flag for the duplicate file descriptor. +Specifying this flag permits a program to avoid an additional +.BR fcntl () +.B F_SETFD +operation to set the +.B FD_CLOEXEC +flag. +For an explanation of why this flag is useful, +see the description of +.B O_CLOEXEC +in +.BR open (2). +.SS File descriptor flags +The following commands manipulate the flags associated with +a file descriptor. +Currently, only one such flag is defined: +.BR FD_CLOEXEC , +the close-on-exec flag. +If the +.B FD_CLOEXEC +bit is set, +the file descriptor will automatically be closed during a successful +.BR execve (2). +(If the +.BR execve (2) +fails, the file descriptor is left open.) +If the +.B FD_CLOEXEC +bit is not set, the file descriptor will remain open across an +.BR execve (2). +.TP +.BR F_GETFD " (\fIvoid\fP)" +Return (as the function result) the file descriptor flags; +.I arg +is ignored. +.TP +.BR F_SETFD " (\fIint\fP)" +Set the file descriptor flags to the value specified by +.IR arg . +.PP +In multithreaded programs, using +.BR fcntl () +.B F_SETFD +to set the close-on-exec flag at the same time as another thread performs a +.BR fork (2) +plus +.BR execve (2) +is vulnerable to a race condition that may unintentionally leak +the file descriptor to the program executed in the child process. +See the discussion of the +.BR O_CLOEXEC +flag in +.BR open (2) +for details and a remedy to the problem. +.SS File status flags +Each open file description has certain associated status flags, +initialized by +.BR open (2) +.\" or +.\" .BR creat (2), +and possibly modified by +.BR fcntl (). +Duplicated file descriptors +(made with +.BR dup (2), +.BR fcntl (F_DUPFD), +.BR fork (2), +etc.) refer to the same open file description, and thus +share the same file status flags. +.PP +The file status flags and their semantics are described in +.BR open (2). +.TP +.BR F_GETFL " (\fIvoid\fP)" +Return (as the function result) +the file access mode and the file status flags; +.I arg +is ignored. +.TP +.BR F_SETFL " (\fIint\fP)" +Set the file status flags to the value specified by +.IR arg . +File access mode +.RB ( O_RDONLY ", " O_WRONLY ", " O_RDWR ) +and file creation flags +(i.e., +.BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", " O_TRUNC ) +in +.I arg +are ignored. +On Linux, this command can change only the +.BR O_APPEND , +.BR O_ASYNC , +.BR O_DIRECT , +.BR O_NOATIME , +and +.B O_NONBLOCK +flags. +It is not possible to change the +.BR O_DSYNC +and +.BR O_SYNC +flags; see BUGS, below. +.SS Advisory record locking +Linux implements traditional ("process-associated") UNIX record locks, +as standardized by POSIX. +For a Linux-specific alternative with better semantics, +see the discussion of open file description locks below. +.PP +.BR F_SETLK , +.BR F_SETLKW , +and +.BR F_GETLK +are used to acquire, release, and test for the existence of record +locks (also known as byte-range, file-segment, or file-region locks). +The third argument, +.IR lock , +is a pointer to a structure that has at least the following fields +(in unspecified order). +.PP +.in +4n +.EX +struct flock { + ... + short l_type; /* Type of lock: F_RDLCK, + F_WRLCK, F_UNLCK */ + short l_whence; /* How to interpret l_start: + SEEK_SET, SEEK_CUR, SEEK_END */ + off_t l_start; /* Starting offset for lock */ + off_t l_len; /* Number of bytes to lock */ + pid_t l_pid; /* PID of process blocking our lock + (set by F_GETLK and F_OFD_GETLK) */ + ... +}; +.EE +.in +.PP +The +.IR l_whence ", " l_start ", and " l_len +fields of this structure specify the range of bytes we wish to lock. +Bytes past the end of the file may be locked, +but not bytes before the start of the file. +.PP +.I l_start +is the starting offset for the lock, and is interpreted +relative to either: +the start of the file (if +.I l_whence +is +.BR SEEK_SET ); +the current file offset (if +.I l_whence +is +.BR SEEK_CUR ); +or the end of the file (if +.I l_whence +is +.BR SEEK_END ). +In the final two cases, +.I l_start +can be a negative number provided the +offset does not lie before the start of the file. +.PP +.I l_len +specifies the number of bytes to be locked. +If +.I l_len +is positive, then the range to be locked covers bytes +.I l_start +up to and including +.IR l_start + l_len \-1. +Specifying 0 for +.I l_len +has the special meaning: lock all bytes starting at the +location specified by +.IR l_whence " and " l_start +through to the end of file, no matter how large the file grows. +.PP +POSIX.1-2001 allows (but does not require) +an implementation to support a negative +.I l_len +value; if +.I l_len +is negative, the interval described by +.I lock +covers bytes +.IR l_start + l_len +up to and including +.IR l_start \-1. +This is supported by Linux since kernel versions 2.4.21 and 2.5.49. +.PP +The +.I l_type +field can be used to place a read +.RB ( F_RDLCK ) +or a write +.RB ( F_WRLCK ) +lock on a file. +Any number of processes may hold a read lock (shared lock) +on a file region, but only one process may hold a write lock +(exclusive lock). +An exclusive lock excludes all other locks, +both shared and exclusive. +A single process can hold only one type of lock on a file region; +if a new lock is applied to an already-locked region, +then the existing lock is converted to the new lock type. +(Such conversions may involve splitting, shrinking, or coalescing with +an existing lock if the byte range specified by the new lock does not +precisely coincide with the range of the existing lock.) +.TP +.BR F_SETLK " (\fIstruct flock *\fP)" +Acquire a lock (when +.I l_type +is +.B F_RDLCK +or +.BR F_WRLCK ) +or release a lock (when +.I l_type +is +.BR F_UNLCK ) +on the bytes specified by the +.IR l_whence ", " l_start ", and " l_len +fields of +.IR lock . +If a conflicting lock is held by another process, +this call returns \-1 and sets +.I errno +to +.B EACCES +or +.BR EAGAIN . +(The error returned in this case differs across implementations, +so POSIX requires a portable application to check for both errors.) +.TP +.BR F_SETLKW " (\fIstruct flock *\fP)" +As for +.BR F_SETLK , +but if a conflicting lock is held on the file, then wait for that +lock to be released. +If a signal is caught while waiting, then the call is interrupted +and (after the signal handler has returned) +returns immediately (with return value \-1 and +.I errno +set to +.BR EINTR ; +see +.BR signal (7)). +.TP +.BR F_GETLK " (\fIstruct flock *\fP)" +On input to this call, +.I lock +describes a lock we would like to place on the file. +If the lock could be placed, +.BR fcntl () +does not actually place it, but returns +.B F_UNLCK +in the +.I l_type +field of +.I lock +and leaves the other fields of the structure unchanged. +.IP +If one or more incompatible locks would prevent +this lock being placed, then +.BR fcntl () +returns details about one of those locks in the +.IR l_type ", " l_whence ", " l_start ", and " l_len +fields of +.IR lock . +If the conflicting lock is a traditional (process-associated) record lock, +then the +.I l_pid +field is set to the PID of the process holding that lock. +If the conflicting lock is an open file description lock, then +.I l_pid +is set to \-1. +Note that the returned information +may already be out of date by the time the caller inspects it. +.PP +In order to place a read lock, +.I fd +must be open for reading. +In order to place a write lock, +.I fd +must be open for writing. +To place both types of lock, open a file read-write. +.PP +When placing locks with +.BR F_SETLKW , +the kernel detects +.IR deadlocks , +whereby two or more processes have their +lock requests mutually blocked by locks held by the other processes. +For example, suppose process A holds a write lock on byte 100 of a file, +and process B holds a write lock on byte 200. +If each process then attempts to lock the byte already +locked by the other process using +.BR F_SETLKW , +then, without deadlock detection, +both processes would remain blocked indefinitely. +When the kernel detects such deadlocks, +it causes one of the blocking lock requests to immediately fail with the error +.BR EDEADLK ; +an application that encounters such an error should release +some of its locks to allow other applications to proceed before +attempting regain the locks that it requires. +Circular deadlocks involving more than two processes are also detected. +Note, however, that there are limitations to the kernel's +deadlock-detection algorithm; see BUGS. +.PP +As well as being removed by an explicit +.BR F_UNLCK , +record locks are automatically released when the process terminates. +.PP +Record locks are not inherited by a child created via +.BR fork (2), +but are preserved across an +.BR execve (2). +.PP +Because of the buffering performed by the +.BR stdio (3) +library, the use of record locking with routines in that package +should be avoided; use +.BR read (2) +and +.BR write (2) +instead. +.PP +The record locks described above are associated with the process +(unlike the open file description locks described below). +This has some unfortunate consequences: +.IP * 3 +If a process closes +.I any +file descriptor referring to a file, +then all of the process's locks on that file are released, +regardless of the file descriptor(s) on which the locks were obtained. +.\" (Additional file descriptors referring to the same file +.\" may have been obtained by calls to +.\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl ().) +This is bad: it means that a process can lose its locks on +a file such as +.I /etc/passwd +or +.I /etc/mtab +when for some reason a library function decides to open, read, +and close the same file. +.IP * +The threads in a process share locks. +In other words, +a multithreaded program can't use record locking to ensure +that threads don't simultaneously access the same region of a file. +.PP +Open file description locks solve both of these problems. +.SS Open file description locks (non-POSIX) +Open file description locks are advisory byte-range locks whose operation is +in most respects identical to the traditional record locks described above. +This lock type is Linux-specific, +and available since Linux 3.15. +(There is a proposal with the Austin Group +.\" FIXME . Review progress into POSIX +.\" http://austingroupbugs.net/view.php?id=768 +to include this lock type in the next revision of POSIX.1.) +For an explanation of open file descriptions, see +.BR open (2). +.PP +The principal difference between the two lock types +is that whereas traditional record locks +are associated with a process, +open file description locks are associated with the +open file description on which they are acquired, +much like locks acquired with +.BR flock (2). +Consequently (and unlike traditional advisory record locks), +open file description locks are inherited across +.BR fork (2) +(and +.BR clone (2) +with +.BR CLONE_FILES ), +and are only automatically released on the last close +of the open file description, +instead of being released on any close of the file. +.PP +Conflicting lock combinations +(i.e., a read lock and a write lock or two write locks) +where one lock is an open file description lock and the other +is a traditional record lock conflict +even when they are acquired by the same process on the same file descriptor. +.PP +Open file description locks placed via the same open file description +(i.e., via the same file descriptor, +or via a duplicate of the file descriptor created by +.BR fork (2), +.BR dup (2), +.BR fcntl () +.BR F_DUPFD , +and so on) are always compatible: +if a new lock is placed on an already locked region, +then the existing lock is converted to the new lock type. +(Such conversions may result in splitting, shrinking, or coalescing with +an existing lock as discussed above.) +.PP +On the other hand, open file description locks may conflict with +each other when they are acquired via different open file descriptions. +Thus, the threads in a multithreaded program can use +open file description locks to synchronize access to a file region +by having each thread perform its own +.BR open (2) +on the file and applying locks via the resulting file descriptor. +.PP +As with traditional advisory locks, the third argument to +.BR fcntl (), +.IR lock , +is a pointer to an +.IR flock +structure. +By contrast with traditional record locks, the +.I l_pid +field of that structure must be set to zero +when using the commands described below. +.PP +The commands for working with open file description locks are analogous +to those used with traditional locks: +.TP +.BR F_OFD_SETLK " (\fIstruct flock *\fP)" +Acquire an open file description lock (when +.I l_type +is +.B F_RDLCK +or +.BR F_WRLCK ) +or release an open file description lock (when +.I l_type +is +.BR F_UNLCK ) +on the bytes specified by the +.IR l_whence ", " l_start ", and " l_len +fields of +.IR lock . +If a conflicting lock is held by another process, +this call returns \-1 and sets +.I errno +to +.BR EAGAIN . +.TP +.BR F_OFD_SETLKW " (\fIstruct flock *\fP)" +As for +.BR F_OFD_SETLK , +but if a conflicting lock is held on the file, then wait for that lock to be +released. +If a signal is caught while waiting, then the call is interrupted +and (after the signal handler has returned) returns immediately +(with return value \-1 and +.I errno +set to +.BR EINTR ; +see +.BR signal (7)). +.TP +.BR F_OFD_GETLK " (\fIstruct flock *\fP)" +On input to this call, +.I lock +describes an open file description lock we would like to place on the file. +If the lock could be placed, +.BR fcntl () +does not actually place it, but returns +.B F_UNLCK +in the +.I l_type +field of +.I lock +and leaves the other fields of the structure unchanged. +If one or more incompatible locks would prevent this lock being placed, +then details about one of these locks are returned via +.IR lock , +as described above for +.BR F_GETLK . +.PP +In the current implementation, +.\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7 +no deadlock detection is performed for open file description locks. +(This contrasts with process-associated record locks, +for which the kernel does perform deadlock detection.) +.\" +.SS Mandatory locking +.IR Warning : +the Linux implementation of mandatory locking is unreliable. +See BUGS below. +Because of these bugs, +and the fact that the feature is believed to be little used, +since Linux 4.5, mandatory locking has been made an optional feature, +governed by a configuration option +.RB ( CONFIG_MANDATORY_FILE_LOCKING ). +This is an initial step toward removing this feature completely. +.PP +By default, both traditional (process-associated) and open file description +record locks are advisory. +Advisory locks are not enforced and are useful only between +cooperating processes. +.PP +Both lock types can also be mandatory. +Mandatory locks are enforced for all processes. +If a process tries to perform an incompatible access (e.g., +.BR read (2) +or +.BR write (2)) +on a file region that has an incompatible mandatory lock, +then the result depends upon whether the +.B O_NONBLOCK +flag is enabled for its open file description. +If the +.B O_NONBLOCK +flag is not enabled, then +the system call is blocked until the lock is removed +or converted to a mode that is compatible with the access. +If the +.B O_NONBLOCK +flag is enabled, then the system call fails with the error +.BR EAGAIN . +.PP +To make use of mandatory locks, mandatory locking must be enabled +both on the filesystem that contains the file to be locked, +and on the file itself. +Mandatory locking is enabled on a filesystem +using the "\-o mand" option to +.BR mount (8), +or the +.B MS_MANDLOCK +flag for +.BR mount (2). +Mandatory locking is enabled on a file by disabling +group execute permission on the file and enabling the set-group-ID +permission bit (see +.BR chmod (1) +and +.BR chmod (2)). +.PP +Mandatory locking is not specified by POSIX. +Some other systems also support mandatory locking, +although the details of how to enable it vary across systems. +.\" +.SS Lost locks +When an advisory lock is obtained on a networked filesystem such as +NFS it is possible that the lock might get lost. +This may happen due to administrative action on the server, or due to a +network partition (i.e., loss of network connectivity with the server) +which lasts long enough for the server to assume +that the client is no longer functioning. +.PP +When the filesystem determines that a lock has been lost, future +.BR read (2) +or +.BR write (2) +requests may fail with the error +.BR EIO . +This error will persist until the lock is removed or the file +descriptor is closed. +Since Linux 3.12, +.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d +this happens at least for NFSv4 (including all minor versions). +.PP +Some versions of UNIX send a signal +.RB ( SIGLOST ) +in this circumstance. +Linux does not define this signal, and does not provide any +asynchronous notification of lost locks. +.\" +.SS Managing signals +.BR F_GETOWN , +.BR F_SETOWN , +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_GETSIG +and +.B F_SETSIG +are used to manage I/O availability signals: +.TP +.BR F_GETOWN " (\fIvoid\fP)" +Return (as the function result) +the process ID or process group currently receiving +.B SIGIO +and +.B SIGURG +signals for events on file descriptor +.IR fd . +Process IDs are returned as positive values; +process group IDs are returned as negative values (but see BUGS below). +.I arg +is ignored. +.TP +.BR F_SETOWN " (\fIint\fP)" +Set the process ID or process group ID that will receive +.B SIGIO +and +.B SIGURG +signals for events on the file descriptor +.IR fd . +The target process or process group ID is specified in +.IR arg . +A process ID is specified as a positive value; +a process group ID is specified as a negative value. +Most commonly, the calling process specifies itself as the owner +(that is, +.I arg +is specified as +.BR getpid (2)). +.IP +As well as setting the file descriptor owner, +one must also enable generation of signals on the file descriptor. +This is done by using the +.BR fcntl () +.B F_SETFL +command to set the +.B O_ASYNC +file status flag on the file descriptor. +Subsequently, a +.B SIGIO +signal is sent whenever input or output becomes possible +on the file descriptor. +The +.BR fcntl () +.B F_SETSIG +command can be used to obtain delivery of a signal other than +.BR SIGIO . +.IP +Sending a signal to the owner process (group) specified by +.B F_SETOWN +is subject to the same permissions checks as are described for +.BR kill (2), +where the sending process is the one that employs +.B F_SETOWN +(but see BUGS below). +If this permission check fails, then the signal is +silently discarded. +.IR Note : +The +.BR F_SETOWN +operation records the caller's credentials at the time of the +.BR fcntl () +call, +and it is these saved credentials that are used for the permission checks. +.IP +If the file descriptor +.I fd +refers to a socket, +.B F_SETOWN +also selects +the recipient of +.B SIGURG +signals that are delivered when out-of-band +data arrives on that socket. +.RB ( SIGURG +is sent in any situation where +.BR select (2) +would report the socket as having an "exceptional condition".) +.\" The following appears to be rubbish. It doesn't seem to +.\" be true according to the kernel source, and I can write +.\" a program that gets a terminal-generated SIGIO even though +.\" it is not the foreground process group of the terminal. +.\" -- MTK, 8 Apr 05 +.\" +.\" If the file descriptor +.\" .I fd +.\" refers to a terminal device, then SIGIO +.\" signals are sent to the foreground process group of the terminal. +.IP +The following was true in 2.6.x kernels up to and including +kernel 2.6.11: +.RS +.IP +If a nonzero value is given to +.B F_SETSIG +in a multithreaded process running with a threading library +that supports thread groups (e.g., NPTL), +then a positive value given to +.B F_SETOWN +has a different meaning: +.\" The relevant place in the (2.6) kernel source is the +.\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005 +instead of being a process ID identifying a whole process, +it is a thread ID identifying a specific thread within a process. +Consequently, it may be necessary to pass +.B F_SETOWN +the result of +.BR gettid (2) +instead of +.BR getpid (2) +to get sensible results when +.B F_SETSIG +is used. +(In current Linux threading implementations, +a main thread's thread ID is the same as its process ID. +This means that a single-threaded program can equally use +.BR gettid (2) +or +.BR getpid (2) +in this scenario.) +Note, however, that the statements in this paragraph do not apply +to the +.B SIGURG +signal generated for out-of-band data on a socket: +this signal is always sent to either a process or a process group, +depending on the value given to +.BR F_SETOWN . +.\" send_sigurg()/send_sigurg_to_task() bypasses +.\" kill_fasync()/send_sigio()/send_sigio_to_task() +.\" to directly call send_group_sig_info() +.\" -- MTK, Apr 2005 (kernel 2.6.11) +.RE +.IP +The above behavior was accidentally dropped in Linux 2.6.12, +and won't be restored. +From Linux 2.6.32 onward, use +.BR F_SETOWN_EX +to target +.B SIGIO +and +.B SIGURG +signals at a particular thread. +.TP +.BR F_GETOWN_EX " (\fIstruct f_owner_ex *\fP) (since Linux 2.6.32)" +Return the current file descriptor owner settings +as defined by a previous +.BR F_SETOWN_EX +operation. +The information is returned in the structure pointed to by +.IR arg , +which has the following form: +.IP +.in +4n +.EX +struct f_owner_ex { + int type; + pid_t pid; +}; +.EE +.in +.IP +The +.I type +field will have one of the values +.BR F_OWNER_TID , +.BR F_OWNER_PID , +or +.BR F_OWNER_PGRP . +The +.I pid +field is a positive integer representing a thread ID, process ID, +or process group ID. +See +.B F_SETOWN_EX +for more details. +.TP +.BR F_SETOWN_EX " (\fIstruct f_owner_ex *\fP) (since Linux 2.6.32)" +This operation performs a similar task to +.BR F_SETOWN . +It allows the caller to direct I/O availability signals +to a specific thread, process, or process group. +The caller specifies the target of signals via +.IR arg , +which is a pointer to a +.IR f_owner_ex +structure. +The +.I type +field has one of the following values, which define how +.I pid +is interpreted: +.RS +.TP +.BR F_OWNER_TID +Send the signal to the thread whose thread ID +(the value returned by a call to +.BR clone (2) +or +.BR gettid (2)) +is specified in +.IR pid . +.TP +.BR F_OWNER_PID +Send the signal to the process whose ID +is specified in +.IR pid . +.TP +.BR F_OWNER_PGRP +Send the signal to the process group whose ID +is specified in +.IR pid . +(Note that, unlike with +.BR F_SETOWN , +a process group ID is specified as a positive value here.) +.RE +.TP +.BR F_GETSIG " (\fIvoid\fP)" +Return (as the function result) +the signal sent when input or output becomes possible. +A value of zero means +.B SIGIO +is sent. +Any other value (including +.BR SIGIO ) +is the +signal sent instead, and in this case additional info is available to +the signal handler if installed with +.BR SA_SIGINFO . +.I arg +is ignored. +.TP +.BR F_SETSIG " (\fIint\fP)" +Set the signal sent when input or output becomes possible +to the value given in +.IR arg . +A value of zero means to send the default +.B SIGIO +signal. +Any other value (including +.BR SIGIO ) +is the signal to send instead, and in this case additional info +is available to the signal handler if installed with +.BR SA_SIGINFO . +.\" +.\" The following was true only up until 2.6.11: +.\" +.\" Additionally, passing a nonzero value to +.\" .B F_SETSIG +.\" changes the signal recipient from a whole process to a specific thread +.\" within a process. +.\" See the description of +.\" .B F_SETOWN +.\" for more details. +.IP +By using +.B F_SETSIG +with a nonzero value, and setting +.B SA_SIGINFO +for the +signal handler (see +.BR sigaction (2)), +extra information about I/O events is passed to +the handler in a +.I siginfo_t +structure. +If the +.I si_code +field indicates the source is +.BR SI_SIGIO , +the +.I si_fd +field gives the file descriptor associated with the event. +Otherwise, +there is no indication which file descriptors are pending, and you +should use the usual mechanisms +.RB ( select (2), +.BR poll (2), +.BR read (2) +with +.B O_NONBLOCK +set etc.) to determine which file descriptors are available for I/O. +.IP +Note that the file descriptor provided in +.I si_fd +is the one that was specified during the +.BR F_SETSIG +operation. +This can lead to an unusual corner case. +If the file descriptor is duplicated +.RB ( dup (2) +or similar), and the original file descriptor is closed, +then I/O events will continue to be generated, but the +.I si_fd +field will contain the number of the now closed file descriptor. +.IP +By selecting a real time signal (value >= +.BR SIGRTMIN ), +multiple I/O events may be queued using the same signal numbers. +(Queuing is dependent on available memory.) +Extra information is available +if +.B SA_SIGINFO +is set for the signal handler, as above. +.IP +Note that Linux imposes a limit on the +number of real-time signals that may be queued to a +process (see +.BR getrlimit (2) +and +.BR signal (7)) +and if this limit is reached, then the kernel reverts to +delivering +.BR SIGIO , +and this signal is delivered to the entire +process rather than to a specific thread. +.\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 +.PP +Using these mechanisms, a program can implement fully asynchronous I/O +without using +.BR select (2) +or +.BR poll (2) +most of the time. +.PP +The use of +.BR O_ASYNC +is specific to BSD and Linux. +The only use of +.BR F_GETOWN +and +.B F_SETOWN +specified in POSIX.1 is in conjunction with the use of the +.B SIGURG +signal on sockets. +(POSIX does not specify the +.BR SIGIO +signal.) +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_GETSIG , +and +.B F_SETSIG +are Linux-specific. +POSIX has asynchronous I/O and the +.I aio_sigevent +structure to achieve similar things; these are also available +in Linux as part of the GNU C Library (Glibc). +.SS Leases +.B F_SETLEASE +and +.B F_GETLEASE +(Linux 2.4 onward) are used (respectively) to establish a new lease, +and retrieve the current lease, on the open file description +referred to by the file descriptor +.IR fd . +A file lease provides a mechanism whereby the process holding +the lease (the "lease holder") is notified (via delivery of a signal) +when a process (the "lease breaker") tries to +.BR open (2) +or +.BR truncate (2) +the file referred to by that file descriptor. +.TP +.BR F_SETLEASE " (\fIint\fP)" +Set or remove a file lease according to which of the following +values is specified in the integer +.IR arg : +.RS +.TP +.B F_RDLCK +Take out a read lease. +This will cause the calling process to be notified when +the file is opened for writing or is truncated. +.\" The following became true in kernel 2.6.10: +.\" See the man-pages-2.09 Changelog for further info. +A read lease can be placed only on a file descriptor that +is opened read-only. +.TP +.B F_WRLCK +Take out a write lease. +This will cause the caller to be notified when +the file is opened for reading or writing or is truncated. +A write lease may be placed on a file only if there are no +other open file descriptors for the file. +.TP +.B F_UNLCK +Remove our lease from the file. +.RE +.PP +Leases are associated with an open file description (see +.BR open (2)). +This means that duplicate file descriptors (created by, for example, +.BR fork (2) +or +.BR dup (2)) +refer to the same lease, and this lease may be modified +or released using any of these descriptors. +Furthermore, the lease is released by either an explicit +.B F_UNLCK +operation on any of these duplicate file descriptors, or when all +such file descriptors have been closed. +.PP +Leases may be taken out only on regular files. +An unprivileged process may take out a lease only on a file whose +UID (owner) matches the filesystem UID of the process. +A process with the +.B CAP_LEASE +capability may take out leases on arbitrary files. +.TP +.BR F_GETLEASE " (\fIvoid\fP)" +Indicates what type of lease is associated with the file descriptor +.I fd +by returning either +.BR F_RDLCK ", " F_WRLCK ", or " F_UNLCK , +indicating, respectively, a read lease , a write lease, or no lease. +.I arg +is ignored. +.PP +When a process (the "lease breaker") performs an +.BR open (2) +or +.BR truncate (2) +that conflicts with a lease established via +.BR F_SETLEASE , +the system call is blocked by the kernel and +the kernel notifies the lease holder by sending it a signal +.RB ( SIGIO +by default). +The lease holder should respond to receipt of this signal by doing +whatever cleanup is required in preparation for the file to be +accessed by another process (e.g., flushing cached buffers) and +then either remove or downgrade its lease. +A lease is removed by performing an +.B F_SETLEASE +command specifying +.I arg +as +.BR F_UNLCK . +If the lease holder currently holds a write lease on the file, +and the lease breaker is opening the file for reading, +then it is sufficient for the lease holder to downgrade +the lease to a read lease. +This is done by performing an +.B F_SETLEASE +command specifying +.I arg +as +.BR F_RDLCK . +.PP +If the lease holder fails to downgrade or remove the lease within +the number of seconds specified in +.IR /proc/sys/fs/lease-break-time , +then the kernel forcibly removes or downgrades the lease holder's lease. +.PP +Once a lease break has been initiated, +.B F_GETLEASE +returns the target lease type (either +.B F_RDLCK +or +.BR F_UNLCK , +depending on what would be compatible with the lease breaker) +until the lease holder voluntarily downgrades or removes the lease or +the kernel forcibly does so after the lease break timer expires. +.PP +Once the lease has been voluntarily or forcibly removed or downgraded, +and assuming the lease breaker has not unblocked its system call, +the kernel permits the lease breaker's system call to proceed. +.PP +If the lease breaker's blocked +.BR open (2) +or +.BR truncate (2) +is interrupted by a signal handler, +then the system call fails with the error +.BR EINTR , +but the other steps still occur as described above. +If the lease breaker is killed by a signal while blocked in +.BR open (2) +or +.BR truncate (2), +then the other steps still occur as described above. +If the lease breaker specifies the +.B O_NONBLOCK +flag when calling +.BR open (2), +then the call immediately fails with the error +.BR EWOULDBLOCK , +but the other steps still occur as described above. +.PP +The default signal used to notify the lease holder is +.BR SIGIO , +but this can be changed using the +.B F_SETSIG +command to +.BR fcntl (). +If a +.B F_SETSIG +command is performed (even one specifying +.BR SIGIO ), +and the signal +handler is established using +.BR SA_SIGINFO , +then the handler will receive a +.I siginfo_t +structure as its second argument, and the +.I si_fd +field of this argument will hold the file descriptor of the leased file +that has been accessed by another process. +(This is useful if the caller holds leases against multiple files.) +.SS File and directory change notification (dnotify) +.TP +.BR F_NOTIFY " (\fIint\fP)" +(Linux 2.4 onward) +Provide notification when the directory referred to by +.I fd +or any of the files that it contains is changed. +The events to be notified are specified in +.IR arg , +which is a bit mask specified by ORing together zero or more of +the following bits: +.PP +.RS +.PD 0 +.TP 12 +.B DN_ACCESS +A file was accessed +.RB ( read (2), +.BR pread (2), +.BR readv (2), +and similar) +.TP +.B DN_MODIFY +A file was modified +.RB ( write (2), +.BR pwrite (2), +.BR writev (2), +.BR truncate (2), +.BR ftruncate (2), +and similar). +.TP +.B DN_CREATE +A file was created +.RB ( open (2), +.BR creat (2), +.BR mknod (2), +.BR mkdir (2), +.BR link (2), +.BR symlink (2), +.BR rename (2) +into this directory). +.TP +.B DN_DELETE +A file was unlinked +.RB ( unlink (2), +.BR rename (2) +to another directory, +.BR rmdir (2)). +.TP +.B DN_RENAME +A file was renamed within this directory +.RB ( rename (2)). +.TP +.B DN_ATTRIB +The attributes of a file were changed +.RB ( chown (2), +.BR chmod (2), +.BR utime (2), +.BR utimensat (2), +and similar). +.PD +.RE +.IP +(In order to obtain these definitions, the +.B _GNU_SOURCE +feature test macro must be defined before including +.I any +header files.) +.IP +Directory notifications are normally "one-shot", and the application +must reregister to receive further notifications. +Alternatively, if +.B DN_MULTISHOT +is included in +.IR arg , +then notification will remain in effect until explicitly removed. +.IP +.\" The following does seem a poor API-design choice... +A series of +.B F_NOTIFY +requests is cumulative, with the events in +.I arg +being added to the set already monitored. +To disable notification of all events, make an +.B F_NOTIFY +call specifying +.I arg +as 0. +.IP +Notification occurs via delivery of a signal. +The default signal is +.BR SIGIO , +but this can be changed using the +.B F_SETSIG +command to +.BR fcntl (). +(Note that +.B SIGIO +is one of the nonqueuing standard signals; +switching to the use of a real-time signal means that +multiple notifications can be queued to the process.) +In the latter case, the signal handler receives a +.I siginfo_t +structure as its second argument (if the handler was +established using +.BR SA_SIGINFO ) +and the +.I si_fd +field of this structure contains the file descriptor which +generated the notification (useful when establishing notification +on multiple directories). +.IP +Especially when using +.BR DN_MULTISHOT , +a real time signal should be used for notification, +so that multiple notifications can be queued. +.IP +.B NOTE: +New applications should use the +.I inotify +interface (available since kernel 2.6.13), +which provides a much superior interface for obtaining notifications of +filesystem events. +See +.BR inotify (7). +.SS Changing the capacity of a pipe +.TP +.BR F_SETPIPE_SZ " (\fIint\fP; since Linux 2.6.35)" +Change the capacity of the pipe referred to by +.I fd +to be at least +.I arg +bytes. +An unprivileged process can adjust the pipe capacity to any value +between the system page size and the limit defined in +.IR /proc/sys/fs/pipe-max-size +(see +.BR proc (5)). +Attempts to set the pipe capacity below the page size are silently +rounded up to the page size. +Attempts by an unprivileged process to set the pipe capacity above the limit in +.IR /proc/sys/fs/pipe-max-size +yield the error +.BR EPERM ; +a privileged process +.RB ( CAP_SYS_RESOURCE ) +can override the limit. +.IP +When allocating the buffer for the pipe, +the kernel may use a capacity larger than +.IR arg , +if that is convenient for the implementation. +(In the current implementation, +the allocation is the next higher power-of-two page-size multiple +of the requested size.) +The actual capacity (in bytes) that is set is returned as the function result. +.IP +Attempting to set the pipe capacity smaller than the amount +of buffer space currently used to store data produces the error +.BR EBUSY . +.TP +.BR F_GETPIPE_SZ " (\fIvoid\fP; since Linux 2.6.35)" +Return (as the function result) the capacity of the pipe referred to by +.IR fd . +.\" +.SS File Sealing +File seals limit the set of allowed operations on a given file. +For each seal that is set on a file, +a specific set of operations will fail with +.B EPERM +on this file from now on. +The file is said to be sealed. +The default set of seals depends on the type of the underlying +file and filesystem. +For an overview of file sealing, a discussion of its purpose, +and some code examples, see +.BR memfd_create (2). +.PP +Currently, +file seals can be applied only to a file descriptor returned by +.BR memfd_create (2) +(if the +.B MFD_ALLOW_SEALING +was employed). +On other filesystems, all +.BR fcntl () +operations that operate on seals will return +.BR EINVAL . +.PP +Seals are a property of an inode. +Thus, all open file descriptors referring to the same inode share +the same set of seals. +Furthermore, seals can never be removed, only added. +.TP +.BR F_ADD_SEALS " (\fIint\fP; since Linux 3.17)" +Add the seals given in the bit-mask argument +.I arg +to the set of seals of the inode referred to by the file descriptor +.IR fd . +Seals cannot be removed again. +Once this call succeeds, the seals are enforced by the kernel immediately. +If the current set of seals includes +.BR F_SEAL_SEAL +(see below), then this call will be rejected with +.BR EPERM . +Adding a seal that is already set is a no-op, in case +.B F_SEAL_SEAL +is not set already. +In order to place a seal, the file descriptor +.I fd +must be writable. +.TP +.BR F_GET_SEALS " (\fIvoid\fP; since Linux 3.17)" +Return (as the function result) the current set of seals +of the inode referred to by +.IR fd . +If no seals are set, 0 is returned. +If the file does not support sealing, \-1 is returned and +.I errno +is set to +.BR EINVAL . +.PP +The following seals are available: +.TP +.BR F_SEAL_SEAL +If this seal is set, any further call to +.BR fcntl () +with +.B F_ADD_SEALS +fails with the error +.BR EPERM . +Therefore, this seal prevents any modifications to the set of seals itself. +If the initial set of seals of a file includes +.BR F_SEAL_SEAL , +then this effectively causes the set of seals to be constant and locked. +.TP +.BR F_SEAL_SHRINK +If this seal is set, the file in question cannot be reduced in size. +This affects +.BR open (2) +with the +.B O_TRUNC +flag as well as +.BR truncate (2) +and +.BR ftruncate (2). +Those calls fail with +.B EPERM +if you try to shrink the file in question. +Increasing the file size is still possible. +.TP +.BR F_SEAL_GROW +If this seal is set, the size of the file in question cannot be increased. +This affects +.BR write (2) +beyond the end of the file, +.BR truncate (2), +.BR ftruncate (2), +and +.BR fallocate (2). +These calls fail with +.B EPERM +if you use them to increase the file size. +If you keep the size or shrink it, those calls still work as expected. +.TP +.BR F_SEAL_WRITE +If this seal is set, you cannot modify the contents of the file. +Note that shrinking or growing the size of the file is +still possible and allowed. +.\" One or more other seals are typically used with F_SEAL_WRITE +.\" because, given a file with the F_SEAL_WRITE seal set, then, +.\" while it would no longer be possible to (say) write zeros into +.\" the last 100 bytes of a file, it would still be possible +.\" to (say) shrink the file by 100 bytes using ftruncate(), and +.\" then increase the file size by 100 bytes, which would have +.\" the effect of replacing the last hundred bytes by zeros. +.\" +Thus, this seal is normally used in combination with one of the other seals. +This seal affects +.BR write (2) +and +.BR fallocate (2) +(only in combination with the +.B FALLOC_FL_PUNCH_HOLE +flag). +Those calls fail with +.B EPERM +if this seal is set. +Furthermore, trying to create new shared, writable memory-mappings via +.BR mmap (2) +will also fail with +.BR EPERM . +.IP +Using the +.B F_ADD_SEALS +operation to set the +.B F_SEAL_WRITE +seal fails with +.B EBUSY +if any writable, shared mapping exists. +Such mappings must be unmapped before you can add this seal. +Furthermore, if there are any asynchronous I/O operations +.RB ( io_submit (2)) +pending on the file, +all outstanding writes will be discarded. +.\" +.SS File read/write hints +Write lifetime hints can be used to inform the kernel about the relative +expected lifetime of writes on a given inode or +via a particular open file description. +(See +.BR open (2) +for an explanation of open file descriptions.) +In this context, the term "write lifetime" means +the expected time the data will live on media, before +being overwritten or erased. +.PP +An application may use the different hint values specified below to +separate writes into different write classes, +so that multiple users or applications running on a single storage back-end +can aggregate their I/O patterns in a consistent manner. +However, there are no functional semantics implied by these flags, +and different I/O classes can use the write lifetime hints +in arbitrary ways, so long as the hints are used consistently. +.PP +The following operations can be applied to the file descriptor, +.IR fd : +.TP +.BR F_GET_RW_HINT " (\fIuint64_t *\fP; since Linux 4.13)" +Returns the value of the read/write hint associated with the underlying inode +referred to by +.IR fd . +.TP +.BR F_SET_RW_HINT " (\fIuint64_t *\fP; since Linux 4.13)" +Sets the read/write hint value associated with the +underlying inode referred to by +.IR fd . +This hint persists until either it is explicitly modified or +the underlying filesystem is unmounted. +.TP +.BR F_GET_FILE_RW_HINT " (\fIuint64_t *\fP; since Linux 4.13)" +Returns the value of the read/write hint associated with +the open file description referred to by +.IR fd . +.TP +.BR F_SET_FILE_RW_HINT " (\fIuint64_t *\fP; since Linux 4.13)" +Sets the read/write hint value associated with the open file description +referred to by +.IR fd . +.PP +If an open file description has not been assigned a read/write hint, +then it shall use the value assigned to the inode, if any. +.PP +The following read/write +hints are valid since Linux 4.13: +.TP +.BR RWH_WRITE_LIFE_NOT_SET +No specific hint has been set. +This is the default value. +.TP +.BR RWH_WRITE_LIFE_NONE +No specific write lifetime is associated with this file or inode. +.TP +.BR RWH_WRITE_LIFE_SHORT +Data written to this inode or via this open file description +is expected to have a short lifetime. +.TP +.BR RWH_WRITE_LIFE_MEDIUM +Data written to this inode or via this open file description +is expected to have a lifetime longer than +data written with +.BR RWH_WRITE_LIFE_SHORT . +.TP +.BR RWH_WRITE_LIFE_LONG +Data written to this inode or via this open file description +is expected to have a lifetime longer than +data written with +.BR RWH_WRITE_LIFE_MEDIUM . +.TP +.BR RWH_WRITE_LIFE_EXTREME +Data written to this inode or via this open file description +is expected to have a lifetime longer than +data written with +.BR RWH_WRITE_LIFE_LONG . +.PP +All the write-specific hints are relative to each other, +and no individual absolute meaning should be attributed to them. +.SH RETURN VALUE +For a successful call, the return value depends on the operation: +.TP 0.9i +.B F_DUPFD +The new file descriptor. +.TP +.B F_GETFD +Value of file descriptor flags. +.TP +.B F_GETFL +Value of file status flags. +.TP +.B F_GETLEASE +Type of lease held on file descriptor. +.TP +.B F_GETOWN +Value of file descriptor owner. +.TP +.B F_GETSIG +Value of signal sent when read or write becomes possible, or zero +for traditional +.B SIGIO +behavior. +.TP +.BR F_GETPIPE_SZ ", " F_SETPIPE_SZ +The pipe capacity. +.TP +.BR F_GET_SEALS +A bit mask identifying the seals that have been set +for the inode referred to by +.IR fd . +.TP +All other commands +Zero. +.PP +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.BR EACCES " or " EAGAIN +Operation is prohibited by locks held by other processes. +.TP +.B EAGAIN +The operation is prohibited because the file has been memory-mapped by +another process. +.TP +.B EBADF +.I fd +is not an open file descriptor +.TP +.B EBADF +.I cmd +is +.B F_SETLK +or +.B F_SETLKW +and the file descriptor open mode doesn't match with the +type of lock requested. +.TP +.BR EBUSY +.I cmd +is +.BR F_SETPIPE_SZ +and the new pipe capacity specified in +.I arg +is smaller than the amount of buffer space currently +used to store data in the pipe. +.TP +.B EBUSY +.I cmd +is +.BR F_ADD_SEALS , +.IR arg +includes +.BR F_SEAL_WRITE , +and there exists a writable, shared mapping on the file referred to by +.IR fd . +.TP +.B EDEADLK +It was detected that the specified +.B F_SETLKW +command would cause a deadlock. +.TP +.B EFAULT +.I lock +is outside your accessible address space. +.TP +.B EINTR +.I cmd +is +.BR F_SETLKW +or +.BR F_OFD_SETLKW +and the operation was interrupted by a signal; see +.BR signal (7). +.TP +.B EINTR +.I cmd +is +.BR F_GETLK , +.BR F_SETLK , +.BR F_OFD_GETLK , +or +.BR F_OFD_SETLK , +and the operation was interrupted by a signal before the lock was checked or +acquired. +Most likely when locking a remote file (e.g., locking over +NFS), but can sometimes happen locally. +.TP +.B EINVAL +The value specified in +.I cmd +is not recognized by this kernel. +.TP +.B EINVAL +.I cmd +is +.BR F_ADD_SEALS +and +.I arg +includes an unrecognized sealing bit. +.TP +.BR EINVAL +.I cmd +is +.BR F_ADD_SEALS +or +.BR F_GET_SEALS +and the filesystem containing the inode referred to by +.I fd +does not support sealing. +.TP +.B EINVAL +.I cmd +is +.BR F_DUPFD +and +.I arg +is negative or is greater than the maximum allowable value +(see the discussion of +.BR RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B EINVAL +.I cmd +is +.BR F_SETSIG +and +.I arg +is not an allowable signal number. +.TP +.B EINVAL +.I cmd +is +.BR F_OFD_SETLK , +.BR F_OFD_SETLKW , +or +.BR F_OFD_GETLK , +and +.I l_pid +was not specified as zero. +.TP +.B EMFILE +.I cmd +is +.BR F_DUPFD +and the per-process limit on the number of open file descriptors +has been reached. +.TP +.B ENOLCK +Too many segment locks open, lock table is full, or a remote locking +protocol failed (e.g., locking over NFS). +.TP +.B ENOTDIR +.B F_NOTIFY +was specified in +.IR cmd , +but +.IR fd +does not refer to a directory. +.TP +.BR EPERM +.I cmd +is +.BR F_SETPIPE_SZ +and the soft or hard user pipe limit has been reached; see +.BR pipe (7). +.TP +.B EPERM +Attempted to clear the +.B O_APPEND +flag on a file that has the append-only attribute set. +.TP +.B EPERM +.I cmd +was +.BR F_ADD_SEALS , +but +.I fd +was not open for writing +or the current set of seals on the file already includes +.BR F_SEAL_SEAL . +.SH CONFORMING TO +SVr4, 4.3BSD, POSIX.1-2001. +Only the operations +.BR F_DUPFD , +.BR F_GETFD , +.BR F_SETFD , +.BR F_GETFL , +.BR F_SETFL , +.BR F_GETLK , +.BR F_SETLK , +and +.BR F_SETLKW +are specified in POSIX.1-2001. +.PP +.BR F_GETOWN +and +.B F_SETOWN +are specified in POSIX.1-2001. +(To get their definitions, define either +.\" .BR _BSD_SOURCE , +.\" or +.BR _XOPEN_SOURCE +with the value 500 or greater, or +.BR _POSIX_C_SOURCE +with the value 200809L or greater.) +.PP +.B F_DUPFD_CLOEXEC +is specified in POSIX.1-2008. +(To get this definition, define +.B _POSIX_C_SOURCE +with the value 200809L or greater, or +.B _XOPEN_SOURCE +with the value 700 or greater.) +.PP +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_SETPIPE_SZ , +.BR F_GETPIPE_SZ , +.BR F_GETSIG , +.BR F_SETSIG , +.BR F_NOTIFY , +.BR F_GETLEASE , +and +.B F_SETLEASE +are Linux-specific. +(Define the +.B _GNU_SOURCE +macro to obtain these definitions.) +.\" .PP +.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. +.PP +.BR F_OFD_SETLK , +.BR F_OFD_SETLKW , +and +.BR F_OFD_GETLK +are Linux-specific (and one must define +.BR _GNU_SOURCE +to obtain their definitions), +but work is being done to have them included in the next version of POSIX.1. +.PP +.BR F_ADD_SEALS +and +.BR F_GET_SEALS +are Linux-specific. +.\" FIXME . Once glibc adds support, add a note about FTM requirements +.SH NOTES +The errors returned by +.BR dup2 (2) +are different from those returned by +.BR F_DUPFD . +.\" +.SS File locking +The original Linux +.BR fcntl () +system call was not designed to handle large file offsets +(in the +.I flock +structure). +Consequently, an +.BR fcntl64 () +system call was added in Linux 2.4. +The newer system call employs a different structure for file locking, +.IR flock64 , +and corresponding commands, +.BR F_GETLK64 , +.BR F_SETLK64 , +and +.BR F_SETLKW64 . +However, these details can be ignored by applications using glibc, whose +.BR fcntl () +wrapper function transparently employs the more recent system call +where it is available. +.\" +.SS Record locks +Since kernel 2.0, there is no interaction between the types of lock +placed by +.BR flock (2) +and +.BR fcntl (). +.PP +Several systems have more fields in +.I "struct flock" +such as, for example, +.IR l_sysid . +.\" e.g., Solaris 8 documents this field in fcntl(2), and Irix 6.5 +.\" documents it in fcntl(5). mtk, May 2007 +.\" Also, FreeBSD documents it (Apr 2014). +Clearly, +.I l_pid +alone is not going to be very useful if the process holding the lock +may live on a different machine. +.PP +The original Linux +.BR fcntl () +system call was not designed to handle large file offsets +(in the +.I flock +structure). +Consequently, an +.BR fcntl64 () +system call was added in Linux 2.4. +The newer system call employs a different structure for file locking, +.IR flock64 , +and corresponding commands, +.BR F_GETLK64 , +.BR F_SETLK64 , +and +.BR F_SETLKW64 . +However, these details can be ignored by applications using glibc, whose +.BR fcntl () +wrapper function transparently employs the more recent system call +where it is available. +.SS Record locking and NFS +Before Linux 3.12, if an NFSv4 client +loses contact with the server for a period of time +(defined as more than 90 seconds with no communication), +.\" +.\" Neil Brown: With NFSv3 the failure mode is the reverse. If +.\" the server loses contact with a client then any lock stays in place +.\" indefinitely ("why can't I read my mail"... I remember it well). +.\" +it might lose and regain a lock without ever being aware of the fact. +(The period of time after which contact is assumed lost is known as +the NFSv4 leasetime. +On a Linux NFS server, this can be determined by looking at +.IR /proc/fs/nfsd/nfsv4leasetime , +which expresses the period in seconds. +The default value for this file is 90.) +.\" +.\" Jeff Layton: +.\" Note that this is not a firm timeout. The server runs a job +.\" periodically to clean out expired stateful objects, and it's likely +.\" that there is some time (maybe even up to another whole lease period) +.\" between when the timeout expires and the job actually runs. If the +.\" client gets a RENEW in there within that window, its lease will be +.\" renewed and its state preserved. +.\" +This scenario potentially risks data corruption, +since another process might acquire a lock in the intervening period +and perform file I/O. +.PP +Since Linux 3.12, +.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d +if an NFSv4 client loses contact with the server, +any I/O to the file by a process which "thinks" it holds +a lock will fail until that process closes and reopens the file. +A kernel parameter, +.IR nfs.recover_lost_locks , +can be set to 1 to obtain the pre-3.12 behavior, +whereby the client will attempt to recover lost locks +when contact is reestablished with the server. +Because of the attendant risk of data corruption, +.\" commit f6de7a39c181dfb8a2c534661a53c73afb3081cd +this parameter defaults to 0 (disabled). +.SH BUGS +.SS F_SETFL +It is not possible to use +.BR F_SETFL +to change the state of the +.BR O_DSYNC +and +.BR O_SYNC +flags. +.\" FIXME . According to POSIX.1-2001, O_SYNC should also be modifiable +.\" via fcntl(2), but currently Linux does not permit this +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5994 +Attempts to change the state of these flags are silently ignored. +.SS F_GETOWN +A limitation of the Linux system call conventions on some +architectures (notably i386) means that if a (negative) +process group ID to be returned by +.B F_GETOWN +falls in the range \-1 to \-4095, then the return value is wrongly +interpreted by glibc as an error in the system call; +.\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h +that is, the return value of +.BR fcntl () +will be \-1, and +.I errno +will contain the (positive) process group ID. +The Linux-specific +.BR F_GETOWN_EX +operation avoids this problem. +.\" mtk, Dec 04: some limited testing on alpha and ia64 seems to +.\" indicate that ANY negative PGID value will cause F_GETOWN +.\" to misinterpret the return as an error. Some other architectures +.\" seem to have the same range check as i386. +Since glibc version 2.11, glibc makes the kernel +.B F_GETOWN +problem invisible by implementing +.B F_GETOWN +using +.BR F_GETOWN_EX . +.SS F_SETOWN +In Linux 2.4 and earlier, there is bug that can occur +when an unprivileged process uses +.B F_SETOWN +to specify the owner +of a socket file descriptor +as a process (group) other than the caller. +In this case, +.BR fcntl () +can return \-1 with +.I errno +set to +.BR EPERM , +even when the owner process (group) is one that the caller +has permission to send signals to. +Despite this error return, the file descriptor owner is set, +and signals will be sent to the owner. +.\" +.SS Deadlock detection +The deadlock-detection algorithm employed by the kernel when dealing with +.BR F_SETLKW +requests can yield both +false negatives (failures to detect deadlocks, +leaving a set of deadlocked processes blocked indefinitely) +and false positives +.RB ( EDEADLK +errors when there is no deadlock). +For example, +the kernel limits the lock depth of its dependency search to 10 steps, +meaning that circular deadlock chains that exceed +that size will not be detected. +In addition, the kernel may falsely indicate a deadlock +when two or more processes created using the +.BR clone (2) +.B CLONE_FILES +flag place locks that appear (to the kernel) to conflict. +.\" +.SS Mandatory locking +The Linux implementation of mandatory locking +is subject to race conditions which render it unreliable: +.\" http://marc.info/?l=linux-kernel&m=119013491707153&w=2 +.\" +.\" Reconfirmed by Jeff Layton +.\" From: Jeff Layton redhat.com> +.\" Subject: Re: Status of fcntl() mandatory locking +.\" Newsgroups: gmane.linux.file-systems +.\" Date: 2014-04-28 10:07:57 GMT +.\" http://thread.gmane.org/gmane.linux.file-systems/84481/focus=84518 +a +.BR write (2) +call that overlaps with a lock may modify data after the mandatory lock is +acquired; +a +.BR read (2) +call that overlaps with a lock may detect changes to data that were made +only after a write lock was acquired. +Similar races exist between mandatory locks and +.BR mmap (2). +It is therefore inadvisable to rely on mandatory locking. +.SH SEE ALSO +.BR dup2 (2), +.BR flock (2), +.BR open (2), +.BR socket (2), +.BR lockf (3), +.BR capabilities (7), +.BR feature_test_macros (7), +.BR lslocks (8) +.PP +.IR locks.txt , +.IR mandatory-locking.txt , +and +.I dnotify.txt +in the Linux kernel source directory +.IR Documentation/filesystems/ +(on older kernels, these files are directly under the +.I Documentation/ +directory, and +.I mandatory-locking.txt +is called +.IR mandatory.txt ) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/fcntl64.2 b/man2/fcntl64.2 new file mode 100644 index 0000000..fc8ddc1 --- /dev/null +++ b/man2/fcntl64.2 @@ -0,0 +1 @@ +.so man2/fcntl.2 diff --git a/man2/fdatasync.2 b/man2/fdatasync.2 new file mode 100644 index 0000000..3c7494f --- /dev/null +++ b/man2/fdatasync.2 @@ -0,0 +1 @@ +.so man2/fsync.2 diff --git a/man2/fdetach.2 b/man2/fdetach.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/fdetach.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/fgetxattr.2 b/man2/fgetxattr.2 new file mode 100644 index 0000000..d9e5d90 --- /dev/null +++ b/man2/fgetxattr.2 @@ -0,0 +1 @@ +.so man2/getxattr.2 diff --git a/man2/finit_module.2 b/man2/finit_module.2 new file mode 100644 index 0000000..20c5c51 --- /dev/null +++ b/man2/finit_module.2 @@ -0,0 +1 @@ +.so man2/init_module.2 diff --git a/man2/flistxattr.2 b/man2/flistxattr.2 new file mode 100644 index 0000000..117bd2b --- /dev/null +++ b/man2/flistxattr.2 @@ -0,0 +1 @@ +.so man2/listxattr.2 diff --git a/man2/flock.2 b/man2/flock.2 new file mode 100644 index 0000000..c4a2fcb --- /dev/null +++ b/man2/flock.2 @@ -0,0 +1,263 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and +.\" and Copyright 2002 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Fri Jan 31 16:26:07 1997 by Eric S. Raymond +.\" Modified Fri Dec 11 17:57:27 1998 by Jamie Lokier +.\" Modified 24 Apr 2002 by Michael Kerrisk +.\" Substantial rewrites and additions +.\" 2005-05-10 mtk, noted that lock conversions are not atomic. +.\" +.\" FIXME Maybe document LOCK_MAND, LOCK_RW, LOCK_READ, LOCK_WRITE +.\" which only have effect for SAMBA. +.\" +.TH FLOCK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +flock \- apply or remove an advisory lock on an open file +.SH SYNOPSIS +.B #include +.PP +.BI "int flock(int " fd ", int " operation ); +.SH DESCRIPTION +Apply or remove an advisory lock on the open file specified by +.IR fd . +The argument +.I operation +is one of the following: +.RS 4 +.TP 9 +.B LOCK_SH +Place a shared lock. +More than one process may hold a shared lock for a given file +at a given time. +.TP +.B LOCK_EX +Place an exclusive lock. +Only one process may hold an exclusive lock for a given +file at a given time. +.TP +.B LOCK_UN +Remove an existing lock held by this process. +.RE +.PP +A call to +.BR flock () +may block if an incompatible lock is held by another process. +To make a nonblocking request, include +.B LOCK_NB +(by ORing) +with any of the above operations. +.PP +A single file may not simultaneously have both shared and exclusive locks. +.PP +Locks created by +.BR flock () +are associated with an open file description (see +.BR open (2)). +This means that duplicate file descriptors (created by, for example, +.BR fork (2) +or +.BR dup (2)) +refer to the same lock, and this lock may be modified +or released using any of these file descriptors. +Furthermore, the lock is released either by an explicit +.B LOCK_UN +operation on any of these duplicate file descriptors, or when all +such file descriptors have been closed. +.PP +If a process uses +.BR open (2) +(or similar) to obtain more than one file descriptor for the same file, +these file descriptors are treated independently by +.BR flock (). +An attempt to lock the file using one of these file descriptors +may be denied by a lock that the calling process has +already placed via another file descriptor. +.PP +A process may hold only one type of lock (shared or exclusive) +on a file. +Subsequent +.BR flock () +calls on an already locked file will convert an existing lock to the new +lock mode. +.PP +Locks created by +.BR flock () +are preserved across an +.BR execve (2). +.PP +A shared or exclusive lock can be placed on a file regardless of the +mode in which the file was opened. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EINTR +While waiting to acquire a lock, the call was interrupted by +delivery of a signal caught by a handler; see +.BR signal (7). +.TP +.B EINVAL +.I operation +is invalid. +.TP +.B ENOLCK +The kernel ran out of memory for allocating lock records. +.TP +.B EWOULDBLOCK +The file is locked and the +.B LOCK_NB +flag was selected. +.SH CONFORMING TO +4.4BSD (the +.BR flock () +call first appeared in 4.2BSD). +A version of +.BR flock (), +possibly implemented in terms of +.BR fcntl (2), +appears on most UNIX systems. +.SH NOTES +Since kernel 2.0, +.BR flock () +is implemented as a system call in its own right rather +than being emulated in the GNU C library as a call to +.BR fcntl (2). +With this implementation, +there is no interaction between the types of lock +placed by +.BR flock () +and +.BR fcntl (2), +and +.BR flock () +does not detect deadlock. +(Note, however, that on some systems, such as the modern BSDs, +.\" E.g., according to the flock(2) man page, FreeBSD since at least 5.3 +.BR flock () +and +.BR fcntl (2) +locks +.I do +interact with one another.) +.PP +.BR flock () +places advisory locks only; given suitable permissions on a file, +a process is free to ignore the use of +.BR flock () +and perform I/O on the file. +.PP +.BR flock () +and +.BR fcntl (2) +locks have different semantics with respect to forked processes and +.BR dup (2). +On systems that implement +.BR flock () +using +.BR fcntl (2), +the semantics of +.BR flock () +will be different from those described in this manual page. +.PP +Converting a lock +(shared to exclusive, or vice versa) is not guaranteed to be atomic: +the existing lock is first removed, and then a new lock is established. +Between these two steps, +a pending lock request by another process may be granted, +with the result that the conversion either blocks, or fails if +.B LOCK_NB +was specified. +(This is the original BSD behavior, +and occurs on many other implementations.) +.\" Kernel 2.5.21 changed things a little: during lock conversion +.\" it is now the highest priority process that will get the lock -- mtk +.SS NFS details +In Linux kernels up to 2.6.11, +.BR flock () +does not lock files over NFS +(i.e., the scope of locks was limited to the local system). +Instead, one could use +.BR fcntl (2) +byte-range locking, which does work over NFS, +given a sufficiently recent version of +Linux and a server which supports locking. +.PP +Since Linux 2.6.12, NFS clients support +.BR flock () +locks by emulating them as +.BR fcntl (2) +byte-range locks on the entire file. +This means that +.BR fcntl (2) +and +.BR flock () +locks +.I do +interact with one another over NFS. +It also means that in order to place an exclusive lock, +the file must be opened for writing. +.PP +Since Linux 2.6.37, +.\" commit 5eebde23223aeb0ad2d9e3be6590ff8bbfab0fc2 +the kernel supports a compatibility mode that allows +.BR flock () +locks (and also +.BR fcntl (2) +byte region locks) to be treated as local; +see the discussion of the +.I "local_lock" +option in +.BR nfs (5). +.SH SEE ALSO +.BR flock (1), +.BR close (2), +.BR dup (2), +.BR execve (2), +.BR fcntl (2), +.BR fork (2), +.BR open (2), +.BR lockf (3), +.BR lslocks (8) +.PP +.I Documentation/filesystems/locks.txt +in the Linux kernel source tree +.RI ( Documentation/locks.txt +in older kernels) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/fork.2 b/man2/fork.2 new file mode 100644 index 0000000..c217a3a --- /dev/null +++ b/man2/fork.2 @@ -0,0 +1,337 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" A few fragments remain from an earlier (1992) page by +.\" Drew Eckhardt (drew@cs.colorado.edu), +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 13:22:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 21 Aug 1994 by Michael Chastain (mec@shell.portal.com): +.\" Referenced 'clone(2)'. +.\" Modified 1995-06-10, 1996-04-18, 1999-11-01, 2000-12-24 +.\" by Andries Brouwer (aeb@cwi.nl) +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" 2006-09-04, Michael Kerrisk +.\" Greatly expanded, to describe all attributes that differ +.\" parent and child. +.\" +.TH FORK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +fork \- create a child process +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B pid_t fork(void); +.SH DESCRIPTION +.BR fork () +creates a new process by duplicating the calling process. +The new process is referred to as the +.I child +process. +The calling process is referred to as the +.I parent +process. +.PP +The child process and the parent process run in separate memory spaces. +At the time of +.BR fork () +both memory spaces have the same content. +Memory writes, file mappings +.RB ( mmap (2)), +and unmappings +.RB ( munmap (2)) +performed by one of the processes do not affect the other. +.PP +The child process is an exact duplicate of the parent +process except for the following points: +.IP * 3 +The child has its own unique process ID, +and this PID does not match the ID of any existing process group +.RB ( setpgid (2)) +or session. +.IP * +The child's parent process ID is the same as the parent's process ID. +.IP * +The child does not inherit its parent's memory locks +.RB ( mlock (2), +.BR mlockall (2)). +.IP * +Process resource utilizations +.RB ( getrusage (2)) +and CPU time counters +.RB ( times (2)) +are reset to zero in the child. +.IP * +The child's set of pending signals is initially empty +.RB ( sigpending (2)). +.IP * +The child does not inherit semaphore adjustments from its parent +.RB ( semop (2)). +.IP * +The child does not inherit process-associated record locks from its parent +.RB ( fcntl (2)). +(On the other hand, it does inherit +.BR fcntl (2) +open file description locks and +.BR flock (2) +locks from its parent.) +.IP * +The child does not inherit timers from its parent +.RB ( setitimer (2), +.BR alarm (2), +.BR timer_create (2)). +.IP * +The child does not inherit outstanding asynchronous I/O operations +from its parent +.RB ( aio_read (3), +.BR aio_write (3)), +nor does it inherit any asynchronous I/O contexts from its parent (see +.BR io_setup (2)). +.PP +The process attributes in the preceding list are all specified +in POSIX.1. +The parent and child also differ with respect to the following +Linux-specific process attributes: +.IP * 3 +The child does not inherit directory change notifications (dnotify) +from its parent +(see the description of +.B F_NOTIFY +in +.BR fcntl (2)). +.IP * +The +.BR prctl (2) +.B PR_SET_PDEATHSIG +setting is reset so that the child does not receive a signal +when its parent terminates. +.IP * +The default timer slack value is set to the parent's +current timer slack value. +See the description of +.BR PR_SET_TIMERSLACK +in +.BR prctl (2). +.IP * +Memory mappings that have been marked with the +.BR madvise (2) +.B MADV_DONTFORK +flag are not inherited across a +.BR fork (). +.IP * +Memory in address ranges that have been marked with the +.BR madvise (2) +.B MADV_WIPEONFORK +flag is zeroed in the child after a +.BR fork (). +(The +.B MADV_WIPEONFORK +setting remains in place for those address ranges in the child.) +.IP * +The termination signal of the child is always +.B SIGCHLD +(see +.BR clone (2)). +.IP * +The port access permission bits set by +.BR ioperm (2) +are not inherited by the child; +the child must turn on any bits that it requires using +.BR ioperm (2). +.PP +Note the following further points: +.IP * 3 +The child process is created with a single thread\(emthe +one that called +.BR fork (). +The entire virtual address space of the parent is replicated in the child, +including the states of mutexes, condition variables, +and other pthreads objects; the use of +.BR pthread_atfork (3) +may be helpful for dealing with problems that this can cause. +.IP * +After a +.BR fork () +in a multithreaded program, +the child can safely call only async-signal-safe functions (see +.BR signal-safety (7)) +until such time as it calls +.BR execve (2). +.IP * +The child inherits copies of the parent's set of open file descriptors. +Each file descriptor in the child refers to the same +open file description (see +.BR open (2)) +as the corresponding file descriptor in the parent. +This means that the two file descriptors share open file status flags, +file offset, +and signal-driven I/O attributes (see the description of +.B F_SETOWN +and +.B F_SETSIG +in +.BR fcntl (2)). +.IP * +The child inherits copies of the parent's set of open message +queue descriptors (see +.BR mq_overview (7)). +Each file descriptor in the child refers to the same +open message queue description +as the corresponding file descriptor in the parent. +This means that the two file descriptors share the same flags +.RI ( mq_flags ). +.IP * +The child inherits copies of the parent's set of open directory streams (see +.BR opendir (3)). +POSIX.1 says that the corresponding directory streams +in the parent and child +.I may +share the directory stream positioning; +on Linux/glibc they do not. +.SH RETURN VALUE +On success, the PID of the child process is returned in the parent, +and 0 is returned in the child. +On failure, \-1 is returned in the parent, +no child process is created, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +.\" NOTE! The following should match the description in pthread_create(3) +A system-imposed limit on the number of threads was encountered. +There are a number of limits that may trigger this error: +.RS +.IP * 3 +the +.BR RLIMIT_NPROC +soft resource limit (set via +.BR setrlimit (2)), +which limits the number of processes and threads for a real user ID, +was reached; +.IP * +the kernel's system-wide limit on the number of processes and threads, +.IR /proc/sys/kernel/threads-max , +was reached (see +.BR proc (5)); +.IP * +the maximum number of PIDs, +.IR /proc/sys/kernel/pid_max , +was reached (see +.BR proc (5)); +or +.IP * +the PID limit +.RI ( pids.max ) +imposed by the cgroup "process number" (PIDs) controller was reached. +.RE +.TP +.B EAGAIN +The caller is operating under the +.BR SCHED_DEADLINE +scheduling policy and does not have the reset-on-fork flag set. +See +.BR sched (7). +.TP +.B ENOMEM +.BR fork () +failed to allocate the necessary kernel structures because memory is tight. +.TP +.B ENOMEM +An attempt was made to create a child process in a PID namespace +whose "init" process has terminated. +See +.BR pid_namespaces (7). +.TP +.B ENOSYS +.BR fork () +is not supported on this platform (for example, +.\" e.g., arm (optionally), blackfin, c6x, frv, h8300, microblaze, xtensa +hardware without a Memory-Management Unit). +.TP +.BR ERESTARTNOINTR " (since Linux 2.6.17)" +.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 +System call was interrupted by a signal and will be restarted. +(This can be seen only during a trace.) +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +.PP +Under Linux, +.BR fork () +is implemented using copy-on-write pages, so the only penalty that it incurs +is the time and memory required to duplicate the parent's page tables, +and to create a unique task structure for the child. +.SS C library/kernel differences +Since version 2.3.3, +.\" nptl/sysdeps/unix/sysv/linux/fork.c +rather than invoking the kernel's +.BR fork () +system call, +the glibc +.BR fork () +wrapper that is provided as part of the +NPTL threading implementation invokes +.BR clone (2) +with flags that provide the same effect as the traditional system call. +(A call to +.BR fork () +is equivalent to a call to +.BR clone (2) +specifying +.I flags +as just +.BR SIGCHLD .) +The glibc wrapper invokes any fork handlers that have been +established using +.BR pthread_atfork (3). +.\" and does some magic to ensure that getpid(2) returns the right value. +.SH EXAMPLE +See +.BR pipe (2) +and +.BR wait (2). +.SH SEE ALSO +.BR clone (2), +.BR execve (2), +.BR exit (2), +.BR setrlimit (2), +.BR unshare (2), +.BR vfork (2), +.BR wait (2), +.BR daemon (3), +.BR pthread_atfork (3), +.BR capabilities (7), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/free_hugepages.2 b/man2/free_hugepages.2 new file mode 100644 index 0000000..d4b906a --- /dev/null +++ b/man2/free_hugepages.2 @@ -0,0 +1 @@ +.so man2/alloc_hugepages.2 diff --git a/man2/fremovexattr.2 b/man2/fremovexattr.2 new file mode 100644 index 0000000..38d01cc --- /dev/null +++ b/man2/fremovexattr.2 @@ -0,0 +1 @@ +.so man2/removexattr.2 diff --git a/man2/fsetxattr.2 b/man2/fsetxattr.2 new file mode 100644 index 0000000..dc07807 --- /dev/null +++ b/man2/fsetxattr.2 @@ -0,0 +1 @@ +.so man2/setxattr.2 diff --git a/man2/fstat.2 b/man2/fstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man2/fstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/fstat64.2 b/man2/fstat64.2 new file mode 100644 index 0000000..2b9971d --- /dev/null +++ b/man2/fstat64.2 @@ -0,0 +1 @@ +.so man2/fstat.2 diff --git a/man2/fstatat.2 b/man2/fstatat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man2/fstatat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/fstatat64.2 b/man2/fstatat64.2 new file mode 100644 index 0000000..7791269 --- /dev/null +++ b/man2/fstatat64.2 @@ -0,0 +1 @@ +.so man2/fstatat.2 diff --git a/man2/fstatfs.2 b/man2/fstatfs.2 new file mode 100644 index 0000000..923d3c0 --- /dev/null +++ b/man2/fstatfs.2 @@ -0,0 +1 @@ +.so man2/statfs.2 diff --git a/man2/fstatfs64.2 b/man2/fstatfs64.2 new file mode 100644 index 0000000..fde2b22 --- /dev/null +++ b/man2/fstatfs64.2 @@ -0,0 +1 @@ +.so man2/fstatfs.2 diff --git a/man2/fstatvfs.2 b/man2/fstatvfs.2 new file mode 100644 index 0000000..adec9dd --- /dev/null +++ b/man2/fstatvfs.2 @@ -0,0 +1 @@ +.so man3/statvfs.3 diff --git a/man2/fsync.2 b/man2/fsync.2 new file mode 100644 index 0000000..27d269d --- /dev/null +++ b/man2/fsync.2 @@ -0,0 +1,209 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and +.\" and Copyright 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Removed note about old libc (pre-4.5.26) translating to 'sync'. +.\" Modified 15 Apr 1995 by Michael Chastain : +.\" Added `see also' section. +.\" Modified 13 Apr 1996 by Markus Kuhn +.\" Added remarks about fdatasync. +.\" Modified 31 Jan 1997 by Eric S. Raymond +.\" Modified 18 Apr 2001 by Andi Kleen +.\" Fix description to describe what it really does; add a few caveats. +.\" 2006-04-28, mtk, substantial rewrite of various parts. +.\" 2012-02-27 Various changes by Christoph Hellwig +.\" +.TH FSYNC 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +fsync, fdatasync \- synchronize a file's in-core state with storage device +.SH SYNOPSIS +.B #include +.PP +.BI "int fsync(int " fd ); +.PP +.BI "int fdatasync(int " fd ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fsync (): + Glibc 2.16 and later: + No feature test macros need be defined + Glibc up to and including 2.15: + _BSD_SOURCE || _XOPEN_SOURCE + || /* since glibc 2.8: */ _POSIX_C_SOURCE\ >=\ 200112L +.br +.BR fdatasync (): + _POSIX_C_SOURCE\ >=\ 199309L || _XOPEN_SOURCE\ >=\ 500 +.SH DESCRIPTION +.BR fsync () +transfers ("flushes") all modified in-core data of +(i.e., modified buffer cache pages for) the +file referred to by the file descriptor +.I fd +to the disk device (or other permanent storage device) so that all +changed information can be retrieved even if the system crashes or +is rebooted. +This includes writing through or flushing a disk cache if present. +The call blocks until the device reports that the transfer has completed. +.PP +As well as flushing the file data, +.BR fsync () +also flushes the metadata information associated with the file (see +.BR inode (7)). +.PP +Calling +.BR fsync () +does not necessarily ensure +that the entry in the directory containing the file has also reached disk. +For that an explicit +.BR fsync () +on a file descriptor for the directory is also needed. +.PP +.BR fdatasync () +is similar to +.BR fsync (), +but does not flush modified metadata unless that metadata +is needed in order to allow a subsequent data retrieval to be +correctly handled. +For example, changes to +.I st_atime +or +.I st_mtime +(respectively, time of last access and +time of last modification; see +.BR inode (7)) +do not require flushing because they are not necessary for +a subsequent data read to be handled correctly. +On the other hand, a change to the file size +.RI ( st_size , +as made by say +.BR ftruncate (2)), +would require a metadata flush. +.PP +The aim of +.BR fdatasync () +is to reduce disk activity for applications that do not +require all metadata to be synchronized with the disk. +.SH RETURN VALUE +On success, these system calls return zero. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid open file descriptor. +.TP +.B EIO +An error occurred during synchronization. +This error may relate to data written to some other file descriptor +on the same file. +Since Linux 4.13, +.\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750 +errors from write-back will be reported to +all file descriptors that might have written the data which triggered +the error. +Some filesystems (e.g., NFS) keep close track of which data +came through which file descriptor, and give more precise reporting. +Other filesystems (e.g., most local filesystems) will report errors to +all file descriptors that where open on the file when the error was recorded. +.TP +.B ENOSPC +Disk space was exhausted while synchronizing. +.TP +.BR EROFS ", " EINVAL +.I fd +is bound to a special file (e.g., a pipe, FIFO, or socket) +which does not support synchronization. +.TP +.BR ENOSPC ", " EDQUOT +.I fd +is bound to a file on NFS or another filesystem which does not allocate +space at the time of a +.BR write (2) +system call, and some previous write failed due to insufficient +storage space. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH AVAILABILITY +On POSIX systems on which +.BR fdatasync () +is available, +.B _POSIX_SYNCHRONIZED_IO +is defined in +.I +to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines them to 1. +.SH NOTES +On some UNIX systems (but not Linux), +.I fd +must be a +.I writable +file descriptor. +.PP +In Linux 2.2 and earlier, +.BR fdatasync () +is equivalent to +.BR fsync (), +and so has no performance advantage. +.PP +The +.BR fsync () +implementations in older kernels and lesser used filesystems +does not know how to flush disk caches. +In these cases disk caches need to be disabled using +.BR hdparm (8) +or +.BR sdparm (8) +to guarantee safe operation. +.SH SEE ALSO +.BR sync (1), +.BR bdflush (2), +.BR open (2), +.BR posix_fadvise (2), +.BR pwritev (2), +.BR sync (2), +.BR sync_file_range (2), +.BR fflush (3), +.BR fileno (3), +.BR hdparm (8), +.BR mount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ftruncate.2 b/man2/ftruncate.2 new file mode 100644 index 0000000..2ed34f1 --- /dev/null +++ b/man2/ftruncate.2 @@ -0,0 +1 @@ +.so man2/truncate.2 diff --git a/man2/ftruncate64.2 b/man2/ftruncate64.2 new file mode 100644 index 0000000..a8862d3 --- /dev/null +++ b/man2/ftruncate64.2 @@ -0,0 +1 @@ +.so man2/ftruncate.2 diff --git a/man2/futex.2 b/man2/futex.2 new file mode 100644 index 0000000..2730f5b --- /dev/null +++ b/man2/futex.2 @@ -0,0 +1,1947 @@ +.\" Page by b.hubert +.\" and Copyright (C) 2015, Thomas Gleixner +.\" and Copyright (C) 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" may be freely modified and distributed +.\" %%%LICENSE_END +.\" +.\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com) +.\" added ERRORS section. +.\" +.\" Modified 2004-06-17 mtk +.\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE +.\" +.\" FIXME Still to integrate are some points from Torvald Riegel's mail of +.\" 2015-01-23: +.\" http://thread.gmane.org/gmane.linux.kernel/1703405/focus=7977 +.\" +.\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail +.\" http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242 +.\" +.TH FUTEX 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +futex \- fast user-space locking +.SH SYNOPSIS +.nf +.PP +.B "#include " +.B "#include " +.PP +.BI "int futex(int *" uaddr ", int " futex_op ", int " val , +.BI " const struct timespec *" timeout , \ +" \fR /* or: \fBuint32_t \fIval2\fP */ +.BI " int *" uaddr2 ", int " val3 ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.PP +The +.BR futex () +system call provides a method for waiting until a certain condition becomes +true. +It is typically used as a blocking construct in the context of +shared-memory synchronization. +When using futexes, the majority of +the synchronization operations are performed in user space. +A user-space program employs the +.BR futex () +system call only when it is likely that the program has to block for +a longer time until the condition becomes true. +Other +.BR futex () +operations can be used to wake any processes or threads waiting +for a particular condition. +.PP +A futex is a 32-bit value\(emreferred to below as a +.IR "futex word" \(emwhose +address is supplied to the +.BR futex () +system call. +(Futexes are 32 bits in size on all platforms, including 64-bit systems.) +All futex operations are governed by this value. +In order to share a futex between processes, +the futex is placed in a region of shared memory, +created using (for example) +.BR mmap (2) +or +.BR shmat (2). +(Thus, the futex word may have different +virtual addresses in different processes, +but these addresses all refer to the same location in physical memory.) +In a multithreaded program, it is sufficient to place the futex word +in a global variable shared by all threads. +.PP +When executing a futex operation that requests to block a thread, +the kernel will block only if the futex word has the value that the +calling thread supplied (as one of the arguments of the +.BR futex () +call) as the expected value of the futex word. +The loading of the futex word's value, +the comparison of that value with the expected value, +and the actual blocking will happen atomically and will be totally ordered +with respect to concurrent operations performed by other threads +on the same futex word. +.\" Notes from Darren Hart (Dec 2015): +.\" Totally ordered with respect futex operations refers to semantics +.\" of the ACQUIRE/RELEASE operations and how they impact ordering of +.\" memory reads and writes. The kernel futex operations are protected +.\" by spinlocks, which ensure that all operations are serialized +.\" with respect to one another. +.\" +.\" This is a lot to attempt to define in this document. Perhaps a +.\" reference to linux/Documentation/memory-barriers.txt as a footnote +.\" would be sufficient? Or perhaps for this manual, "serialized" would +.\" be sufficient, with a footnote regarding "totally ordered" and a +.\" pointer to the memory-barrier documentation? +Thus, the futex word is used to connect the synchronization in user space +with the implementation of blocking by the kernel. +Analogously to an atomic +compare-and-exchange operation that potentially changes shared memory, +blocking via a futex is an atomic compare-and-block operation. +.\" FIXME(Torvald Riegel): +.\" Eventually we want to have some text in NOTES to satisfy +.\" the reference in the following sentence +.\" See NOTES for a detailed specification of +.\" the synchronization semantics. +.PP +One use of futexes is for implementing locks. +The state of the lock (i.e., acquired or not acquired) +can be represented as an atomically accessed flag in shared memory. +In the uncontended case, +a thread can access or modify the lock state with atomic instructions, +for example atomically changing it from not acquired to acquired +using an atomic compare-and-exchange instruction. +(Such instructions are performed entirely in user mode, +and the kernel maintains no information about the lock state.) +On the other hand, a thread may be unable to acquire a lock because +it is already acquired by another thread. +It then may pass the lock's flag as a futex word and the value +representing the acquired state as the expected value to a +.BR futex () +wait operation. +This +.BR futex () +operation will block if and only if the lock is still acquired +(i.e., the value in the futex word still matches the "acquired state"). +When releasing the lock, a thread has to first reset the +lock state to not acquired and then execute a futex +operation that wakes threads blocked on the lock flag used as a futex word +(this can be further optimized to avoid unnecessary wake-ups). +See +.BR futex (7) +for more detail on how to use futexes. +.PP +Besides the basic wait and wake-up futex functionality, there are further +futex operations aimed at supporting more complex use cases. +.PP +Note that +no explicit initialization or destruction is necessary to use futexes; +the kernel maintains a futex +(i.e., the kernel-internal implementation artifact) +only while operations such as +.BR FUTEX_WAIT , +described below, are being performed on a particular futex word. +.\" +.SS Arguments +The +.I uaddr +argument points to the futex word. +On all platforms, futexes are four-byte +integers that must be aligned on a four-byte boundary. +The operation to perform on the futex is specified in the +.I futex_op +argument; +.IR val +is a value whose meaning and purpose depends on +.IR futex_op . +.PP +The remaining arguments +.RI ( timeout , +.IR uaddr2 , +and +.IR val3 ) +are required only for certain of the futex operations described below. +Where one of these arguments is not required, it is ignored. +.PP +For several blocking operations, the +.I timeout +argument is a pointer to a +.IR timespec +structure that specifies a timeout for the operation. +However, notwithstanding the prototype shown above, for some operations, +the least significant four bytes of this argument are instead +used as an integer whose meaning is determined by the operation. +For these operations, the kernel casts the +.I timeout +value first to +.IR "unsigned long", +then to +.IR uint32_t , +and in the remainder of this page, this argument is referred to as +.I val2 +when interpreted in this fashion. +.PP +Where it is required, the +.IR uaddr2 +argument is a pointer to a second futex word that is employed +by the operation. +.PP +The interpretation of the final integer argument, +.IR val3 , +depends on the operation. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS Futex operations +The +.I futex_op +argument consists of two parts: +a command that specifies the operation to be performed, +bit-wise ORed with zero or more options that +modify the behaviour of the operation. +The options that may be included in +.I futex_op +are as follows: +.TP +.BR FUTEX_PRIVATE_FLAG " (since Linux 2.6.22)" +.\" commit 34f01cc1f512fa783302982776895c73714ebbc2 +This option bit can be employed with all futex operations. +It tells the kernel that the futex is process-private and not shared +with another process (i.e., it is being used for synchronization +only between threads of the same process). +This allows the kernel to make some additional performance optimizations. +.\" I.e., It allows the kernel choose the fast path for validating +.\" the user-space address and avoids expensive VMA lookups, +.\" taking reference counts on file backing store, and so on. +.IP +As a convenience, +.IR +defines a set of constants with the suffix +.BR _PRIVATE +that are equivalents of all of the operations listed below, +.\" except the obsolete FUTEX_FD, for which the "private" flag was +.\" meaningless +but with the +.BR FUTEX_PRIVATE_FLAG +ORed into the constant value. +Thus, there are +.BR FUTEX_WAIT_PRIVATE , +.BR FUTEX_WAKE_PRIVATE , +and so on. +.TP +.BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)" +.\" commit 1acdac104668a0834cfa267de9946fac7764d486 +This option bit can be employed only with the +.BR FUTEX_WAIT_BITSET , +.BR FUTEX_WAIT_REQUEUE_PI , +and +(since Linux 4.5) +.\" commit 337f13046ff03717a9e99675284a817527440a49 +.BR FUTEX_WAIT +operations. +.IP +If this option is set, the kernel measures the +.I timeout +against the +.BR CLOCK_REALTIME +clock. +.IP +If this option is not set, the kernel measures the +.I timeout +against the +.BR CLOCK_MONOTONIC +clock. +.PP +The operation specified in +.I futex_op +is one of the following: +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAIT " (since Linux 2.6.0)" +.\" Strictly speaking, since some time in 2.5.x +This operation tests that the value at the +futex word pointed to by the address +.I uaddr +still contains the expected value +.IR val , +and if so, then sleeps waiting for a +.B FUTEX_WAKE +operation on the futex word. +The load of the value of the futex word is an atomic memory +access (i.e., using atomic machine instructions of the respective +architecture). +This load, the comparison with the expected value, and +starting to sleep are performed atomically +.\" FIXME: Torvald, I think we may need to add some explanation of +.\" "totally ordered" here. +and totally ordered +with respect to other futex operations on the same futex word. +If the thread starts to sleep, +it is considered a waiter on this futex word. +If the futex value does not match +.IR val , +then the call fails immediately with the error +.BR EAGAIN . +.IP +The purpose of the comparison with the expected value is to prevent lost +wake-ups. +If another thread changed the value of the futex word after the +calling thread decided to block based on the prior value, +and if the other thread executed a +.BR FUTEX_WAKE +operation (or similar wake-up) after the value change and before this +.BR FUTEX_WAIT +operation, then the calling thread will observe the +value change and will not start to sleep. +.IP +If the +.I timeout +is not NULL, the structure it points to specifies a +timeout for the wait. +(This interval will be rounded up to the system clock granularity, +and is guaranteed not to expire early.) +The timeout is by default measured according to the +.BR CLOCK_MONOTONIC +clock, but, since Linux 4.5, the +.BR CLOCK_REALTIME +clock can be selected by specifying +.BR FUTEX_CLOCK_REALTIME +in +.IR futex_op . +If +.I timeout +is NULL, the call blocks indefinitely. +.IP +.IR Note : +for +.BR FUTEX_WAIT , +.IR timeout +is interpreted as a +.IR relative +value. +This differs from other futex operations, where +.I timeout +is interpreted as an absolute value. +To obtain the equivalent of +.BR FUTEX_WAIT +with an absolute timeout, employ +.BR FUTEX_WAIT_BITSET +with +.IR val3 +specified as +.BR FUTEX_BITSET_MATCH_ANY . +.IP +The arguments +.I uaddr2 +and +.I val3 +are ignored. +.\" FIXME . (Torvald) I think we should remove this. Or maybe adapt to a +.\" different example. +.\" +.\" For +.\" .BR futex (7), +.\" this call is executed if decrementing the count gave a negative value +.\" (indicating contention), +.\" and will sleep until another process or thread releases +.\" the futex and executes the +.\" .B FUTEX_WAKE +.\" operation. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAKE " (since Linux 2.6.0)" +.\" Strictly speaking, since Linux 2.5.x +This operation wakes at most +.I val +of the waiters that are waiting (e.g., inside +.BR FUTEX_WAIT ) +on the futex word at the address +.IR uaddr . +Most commonly, +.I val +is specified as either 1 (wake up a single waiter) or +.BR INT_MAX +(wake up all waiters). +No guarantee is provided about which waiters are awoken +(e.g., a waiter with a higher scheduling priority is not guaranteed +to be awoken in preference to a waiter with a lower priority). +.IP +The arguments +.IR timeout , +.IR uaddr2 , +and +.I val3 +are ignored. +.\" FIXME . (Torvald) I think we should remove this. Or maybe adapt to +.\" a different example. +.\" +.\" For +.\" .BR futex (7), +.\" this is executed if incrementing the count showed that +.\" there were waiters, +.\" once the futex value has been set to 1 +.\" (indicating that it is available). +.\" +.\" How does "incrementing the count show that there were waiters"? +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_FD " (from Linux 2.6.0 up to and including Linux 2.6.25)" +.\" Strictly speaking, from Linux 2.5.x to 2.6.25 +This operation creates a file descriptor that is associated with +the futex at +.IR uaddr . +The caller must close the returned file descriptor after use. +When another process or thread performs a +.BR FUTEX_WAKE +on the futex word, the file descriptor indicates as being readable with +.BR select (2), +.BR poll (2), +and +.BR epoll (7) +.IP +The file descriptor can be used to obtain asynchronous notifications: if +.I val +is nonzero, then, when another process or thread executes a +.BR FUTEX_WAKE , +the caller will receive the signal number that was passed in +.IR val . +.IP +The arguments +.IR timeout , +.I uaddr2 +and +.I val3 +are ignored. +.IP +Because it was inherently racy, +.B FUTEX_FD +has been removed +.\" commit 82af7aca56c67061420d618cc5a30f0fd4106b80 +from Linux 2.6.26 onward. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_REQUEUE " (since Linux 2.6.0)" +This operation performs the same task as +.BR FUTEX_CMP_REQUEUE +(see below), except that no check is made using the value in +.IR val3 . +(The argument +.I val3 +is ignored.) +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" +This operation first checks whether the location +.I uaddr +still contains the value +.IR val3 . +If not, the operation fails with the error +.BR EAGAIN . +Otherwise, the operation wakes up a maximum of +.I val +waiters that are waiting on the futex at +.IR uaddr . +If there are more than +.I val +waiters, then the remaining waiters are removed +from the wait queue of the source futex at +.I uaddr +and added to the wait queue of the target futex at +.IR uaddr2 . +The +.I val2 +argument specifies an upper limit on the number of waiters +that are requeued to the futex at +.IR uaddr2 . +.IP +.\" FIXME(Torvald) Is the following correct? Or is just the decision +.\" which threads to wake or requeue part of the atomic operation? +The load from +.I uaddr +is an atomic memory access (i.e., using atomic machine instructions of +the respective architecture). +This load, the comparison with +.IR val3 , +and the requeueing of any waiters are performed atomically and totally +ordered with respect to other operations on the same futex word. +.\" Notes from a f2f conversation with Thomas Gleixner (Aug 2015): ### +.\" The operation is serialized with respect to operations on both +.\" source and target futex. No other waiter can enqueue itself +.\" for waiting and no other waiter can dequeue itself because of +.\" a timeout or signal. +.IP +Typical values to specify for +.I val +are 0 or 1. +(Specifying +.BR INT_MAX +is not useful, because it would make the +.BR FUTEX_CMP_REQUEUE +operation equivalent to +.BR FUTEX_WAKE .) +The limit value specified via +.I val2 +is typically either 1 or +.BR INT_MAX . +(Specifying the argument as 0 is not useful, because it would make the +.BR FUTEX_CMP_REQUEUE +operation equivalent to +.BR FUTEX_WAIT .) +.IP +The +.B FUTEX_CMP_REQUEUE +operation was added as a replacement for the earlier +.BR FUTEX_REQUEUE . +The difference is that the check of the value at +.I uaddr +can be used to ensure that requeueing happens only under certain +conditions, which allows race conditions to be avoided in certain use cases. +.\" But, as Rich Felker points out, there remain valid use cases for +.\" FUTEX_REQUEUE, for example, when the calling thread is requeuing +.\" the target(s) to a lock that the calling thread owns +.\" From: Rich Felker +.\" Date: Wed, 29 Oct 2014 22:43:17 -0400 +.\" To: Darren Hart +.\" CC: libc-alpha@sourceware.org, ... +.\" Subject: Re: Add futex wrapper to glibc? +.IP +Both +.BR FUTEX_REQUEUE +and +.BR FUTEX_CMP_REQUEUE +can be used to avoid "thundering herd" wake-ups that could occur when using +.B FUTEX_WAKE +in cases where all of the waiters that are woken need to acquire +another futex. +Consider the following scenario, +where multiple waiter threads are waiting on B, +a wait queue implemented using a futex: +.IP +.in +4n +.EX +lock(A) +while (!check_value(V)) { + unlock(A); + block_on(B); + lock(A); +}; +unlock(A); +.EE +.in +.IP +If a waker thread used +.BR FUTEX_WAKE , +then all waiters waiting on B would be woken up, +and they would all try to acquire lock A. +However, waking all of the threads in this manner would be pointless because +all except one of the threads would immediately block on lock A again. +By contrast, a requeue operation wakes just one waiter and moves +the other waiters to lock A, +and when the woken waiter unlocks A then the next waiter can proceed. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAKE_OP " (since Linux 2.6.14)" +.\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721 +.\" Author: Jakub Jelinek +.\" Date: Tue Sep 6 15:16:25 2005 -0700 +.\" FIXME. (Torvald) The glibc condvar implementation is currently being +.\" revised (e.g., to not use an internal lock anymore). +.\" It is probably more future-proof to remove this paragraph. +.\" [Torvald, do you have an update here?] +This operation was added to support some user-space use cases +where more than one futex must be handled at the same time. +The most notable example is the implementation of +.BR pthread_cond_signal (3), +which requires operations on two futexes, +the one used to implement the mutex and the one used in the implementation +of the wait queue associated with the condition variable. +.BR FUTEX_WAKE_OP +allows such cases to be implemented without leading to +high rates of contention and context switching. +.IP +The +.BR FUTEX_WAKE_OP +operation is equivalent to executing the following code atomically +and totally ordered with respect to other futex operations on +any of the two supplied futex words: +.IP +.in +4n +.EX +int oldval = *(int *) uaddr2; +*(int *) uaddr2 = oldval \fIop\fP \fIoparg\fP; +futex(uaddr, FUTEX_WAKE, val, 0, 0, 0); +if (oldval \fIcmp\fP \fIcmparg\fP) + futex(uaddr2, FUTEX_WAKE, val2, 0, 0, 0); +.EE +.in +.IP +In other words, +.BR FUTEX_WAKE_OP +does the following: +.RS +.IP * 3 +saves the original value of the futex word at +.IR uaddr2 +and performs an operation to modify the value of the futex at +.IR uaddr2 ; +this is an atomic read-modify-write memory access (i.e., using atomic +machine instructions of the respective architecture) +.IP * +wakes up a maximum of +.I val +waiters on the futex for the futex word at +.IR uaddr ; +and +.IP * +dependent on the results of a test of the original value of the +futex word at +.IR uaddr2 , +wakes up a maximum of +.I val2 +waiters on the futex for the futex word at +.IR uaddr2 . +.RE +.IP +The operation and comparison that are to be performed are encoded +in the bits of the argument +.IR val3 . +Pictorially, the encoding is: +.IP +.in +8n +.EX ++---+---+-----------+-----------+ +|op |cmp| oparg | cmparg | ++---+---+-----------+-----------+ + 4 4 12 12 <== # of bits +.EE +.in +.IP +Expressed in code, the encoding is: +.IP +.in +4n +.EX +#define FUTEX_OP(op, oparg, cmp, cmparg) \\ + (((op & 0xf) << 28) | \\ + ((cmp & 0xf) << 24) | \\ + ((oparg & 0xfff) << 12) | \\ + (cmparg & 0xfff)) +.EE +.in +.IP +In the above, +.I op +and +.I cmp +are each one of the codes listed below. +The +.I oparg +and +.I cmparg +components are literal numeric values, except as noted below. +.IP +The +.I op +component has one of the following values: +.IP +.in +4n +.EX +FUTEX_OP_SET 0 /* uaddr2 = oparg; */ +FUTEX_OP_ADD 1 /* uaddr2 += oparg; */ +FUTEX_OP_OR 2 /* uaddr2 |= oparg; */ +FUTEX_OP_ANDN 3 /* uaddr2 &= ~oparg; */ +FUTEX_OP_XOR 4 /* uaddr2 ^= oparg; */ +.EE +.in +.IP +In addition, bit-wise ORing the following value into +.I op +causes +.IR "(1\ <<\ oparg)" +to be used as the operand: +.IP +.in +4n +.EX +FUTEX_OP_ARG_SHIFT 8 /* Use (1 << oparg) as operand */ +.EE +.in +.IP +The +.I cmp +field is one of the following: +.IP +.in +4n +.EX +FUTEX_OP_CMP_EQ 0 /* if (oldval == cmparg) wake */ +FUTEX_OP_CMP_NE 1 /* if (oldval != cmparg) wake */ +FUTEX_OP_CMP_LT 2 /* if (oldval < cmparg) wake */ +FUTEX_OP_CMP_LE 3 /* if (oldval <= cmparg) wake */ +FUTEX_OP_CMP_GT 4 /* if (oldval > cmparg) wake */ +FUTEX_OP_CMP_GE 5 /* if (oldval >= cmparg) wake */ +.EE +.in +.IP +The return value of +.BR FUTEX_WAKE_OP +is the sum of the number of waiters woken on the futex +.IR uaddr +plus the number of waiters woken on the futex +.IR uaddr2 . +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)" +.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d +This operation is like +.BR FUTEX_WAIT +except that +.I val3 +is used to provide a 32-bit bit mask to the kernel. +This bit mask, in which at least one bit must be set, +is stored in the kernel-internal state of the waiter. +See the description of +.BR FUTEX_WAKE_BITSET +for further details. +.IP +If +.I timeout +is not NULL, the structure it points to specifies +an absolute timeout for the wait operation. +If +.I timeout +is NULL, the operation can block indefinitely. +.IP +.IP +The +.I uaddr2 +argument is ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)" +.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d +This operation is the same as +.BR FUTEX_WAKE +except that the +.I val3 +argument is used to provide a 32-bit bit mask to the kernel. +This bit mask, in which at least one bit must be set, +is used to select which waiters should be woken up. +The selection is done by a bit-wise AND of the "wake" bit mask +(i.e., the value in +.IR val3 ) +and the bit mask which is stored in the kernel-internal +state of the waiter (the "wait" bit mask that is set using +.BR FUTEX_WAIT_BITSET ). +All of the waiters for which the result of the AND is nonzero are woken up; +the remaining waiters are left sleeping. +.IP +The effect of +.BR FUTEX_WAIT_BITSET +and +.BR FUTEX_WAKE_BITSET +is to allow selective wake-ups among multiple waiters that are blocked +on the same futex. +However, note that, depending on the use case, +employing this bit-mask multiplexing feature on a +futex can be less efficient than simply using multiple futexes, +because employing bit-mask multiplexing requires the kernel +to check all waiters on a futex, +including those that are not interested in being woken up +(i.e., they do not have the relevant bit set in their "wait" bit mask). +.\" According to http://locklessinc.com/articles/futex_cheat_sheet/: +.\" +.\" "The original reason for the addition of these extensions +.\" was to improve the performance of pthread read-write locks +.\" in glibc. However, the pthreads library no longer uses the +.\" same locking algorithm, and these extensions are not used +.\" without the bitset parameter being all ones. +.\" +.\" The page goes on to note that the FUTEX_WAIT_BITSET operation +.\" is nevertheless used (with a bit mask of all ones) in order to +.\" obtain the absolute timeout functionality that is useful +.\" for efficiently implementing Pthreads APIs (which use absolute +.\" timeouts); FUTEX_WAIT provides only relative timeouts. +.IP +The constant +.BR FUTEX_BITSET_MATCH_ANY , +which corresponds to all 32 bits set in the bit mask, can be used as the +.I val3 +argument for +.BR FUTEX_WAIT_BITSET +and +.BR FUTEX_WAKE_BITSET . +Other than differences in the handling of the +.I timeout +argument, the +.BR FUTEX_WAIT +operation is equivalent to +.BR FUTEX_WAIT_BITSET +with +.IR val3 +specified as +.BR FUTEX_BITSET_MATCH_ANY ; +that is, allow a wake-up by any waker. +The +.BR FUTEX_WAKE +operation is equivalent to +.BR FUTEX_WAKE_BITSET +with +.IR val3 +specified as +.BR FUTEX_BITSET_MATCH_ANY ; +that is, wake up any waiter(s). +.IP +The +.I uaddr2 +and +.I timeout +arguments are ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS Priority-inheritance futexes +Linux supports priority-inheritance (PI) futexes in order to handle +priority-inversion problems that can be encountered with +normal futex locks. +Priority inversion is the problem that occurs when a high-priority +task is blocked waiting to acquire a lock held by a low-priority task, +while tasks at an intermediate priority continuously preempt +the low-priority task from the CPU. +Consequently, the low-priority task makes no progress toward +releasing the lock, and the high-priority task remains blocked. +.PP +Priority inheritance is a mechanism for dealing with +the priority-inversion problem. +With this mechanism, when a high-priority task becomes blocked +by a lock held by a low-priority task, +the priority of the low-priority task is temporarily raised +to that of the high-priority task, +so that it is not preempted by any intermediate level tasks, +and can thus make progress toward releasing the lock. +To be effective, priority inheritance must be transitive, +meaning that if a high-priority task blocks on a lock +held by a lower-priority task that is itself blocked by a lock +held by another intermediate-priority task +(and so on, for chains of arbitrary length), +then both of those tasks +(or more generally, all of the tasks in a lock chain) +have their priorities raised to be the same as the high-priority task. +.PP +From a user-space perspective, +what makes a futex PI-aware is a policy agreement (described below) +between user space and the kernel about the value of the futex word, +coupled with the use of the PI-futex operations described below. +(Unlike the other futex operations described above, +the PI-futex operations are designed +for the implementation of very specific IPC mechanisms.) +.\" +.\" Quoting Darren Hart: +.\" These opcodes paired with the PI futex value policy (described below) +.\" defines a "futex" as PI aware. These were created very specifically +.\" in support of PI pthread_mutexes, so it makes a lot more sense to +.\" talk about a PI aware pthread_mutex, than a PI aware futex, since +.\" there is a lot of policy and scaffolding that has to be built up +.\" around it to use it properly (this is what a PI pthread_mutex is). +.PP +.\" mtk: The following text is drawn from the Hart/Guniguntala paper +.\" (listed in SEE ALSO), but I have reworded some pieces +.\" significantly. +.\" +The PI-futex operations described below differ from the other +futex operations in that they impose policy on the use of the value of the +futex word: +.IP * 3 +If the lock is not acquired, the futex word's value shall be 0. +.IP * +If the lock is acquired, the futex word's value shall +be the thread ID (TID; +see +.BR gettid (2)) +of the owning thread. +.IP * +If the lock is owned and there are threads contending for the lock, +then the +.B FUTEX_WAITERS +bit shall be set in the futex word's value; in other words, this value is: +.IP + FUTEX_WAITERS | TID +.IP +(Note that is invalid for a PI futex word to have no owner and +.BR FUTEX_WAITERS +set.) +.PP +With this policy in place, +a user-space application can acquire an unacquired +lock or release a lock using atomic instructions executed in user mode +(e.g., a compare-and-swap operation such as +.I cmpxchg +on the x86 architecture). +Acquiring a lock simply consists of using compare-and-swap to atomically +set the futex word's value to the caller's TID if its previous value was 0. +Releasing a lock requires using compare-and-swap to set the futex word's +value to 0 if the previous value was the expected TID. +.PP +If a futex is already acquired (i.e., has a nonzero value), +waiters must employ the +.B FUTEX_LOCK_PI +operation to acquire the lock. +If other threads are waiting for the lock, then the +.B FUTEX_WAITERS +bit is set in the futex value; +in this case, the lock owner must employ the +.B FUTEX_UNLOCK_PI +operation to release the lock. +.PP +In the cases where callers are forced into the kernel +(i.e., required to perform a +.BR futex () +call), +they then deal directly with a so-called RT-mutex, +a kernel locking mechanism which implements the required +priority-inheritance semantics. +After the RT-mutex is acquired, the futex value is updated accordingly, +before the calling thread returns to user space. +.PP +It is important to note +.\" tglx (July 2015): +.\" If there are multiple waiters on a pi futex then a wake pi operation +.\" will wake the first waiter and hand over the lock to this waiter. This +.\" includes handing over the rtmutex which represents the futex in the +.\" kernel. The strict requirement is that the futex owner and the rtmutex +.\" owner must be the same, except for the update period which is +.\" serialized by the futex internal locking. That means the kernel must +.\" update the user-space value prior to returning to user space +that the kernel will update the futex word's value prior +to returning to user space. +(This prevents the possibility of the futex word's value ending +up in an invalid state, such as having an owner but the value being 0, +or having waiters but not having the +.B FUTEX_WAITERS +bit set.) +.PP +If a futex has an associated RT-mutex in the kernel +(i.e., there are blocked waiters) +and the owner of the futex/RT-mutex dies unexpectedly, +then the kernel cleans up the RT-mutex and hands it over to the next waiter. +This in turn requires that the user-space value is updated accordingly. +To indicate that this is required, the kernel sets the +.B FUTEX_OWNER_DIED +bit in the futex word along with the thread ID of the new owner. +User space can detect this situation via the presence of the +.B FUTEX_OWNER_DIED +bit and is then responsible for cleaning up the stale state left over by +the dead owner. +.\" tglx (July 2015): +.\" The FUTEX_OWNER_DIED bit can also be set on uncontended futexes, where +.\" the kernel has no state associated. This happens via the robust futex +.\" mechanism. In that case the futex value will be set to +.\" FUTEX_OWNER_DIED. The robust futex mechanism is also available for non +.\" PI futexes. +.PP +PI futexes are operated on by specifying one of the values listed below in +.IR futex_op . +Note that the PI futex operations must be used as paired operations +and are subject to some additional requirements: +.IP * 3 +.B FUTEX_LOCK_PI +and +.B FUTEX_TRYLOCK_PI +pair with +.BR FUTEX_UNLOCK_PI. +.B FUTEX_UNLOCK_PI +must be called only on a futex owned by the calling thread, +as defined by the value policy, otherwise the error +.B EPERM +results. +.IP * +.B FUTEX_WAIT_REQUEUE_PI +pairs with +.BR FUTEX_CMP_REQUEUE_PI . +This must be performed from a non-PI futex to a distinct PI futex +(or the error +.B EINVAL +results). +Additionally, +.I val +(the number of waiters to be woken) must be 1 +(or the error +.B EINVAL +results). +.PP +The PI futex operations are as follows: +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_LOCK_PI " (since Linux 2.6.18)" +.\" commit c87e2837be82df479a6bae9f155c43516d2feebc +This operation is used after an attempt to acquire +the lock via an atomic user-mode instruction failed +because the futex word has a nonzero value\(emspecifically, +because it contained the (PID-namespace-specific) TID of the lock owner. +.IP +The operation checks the value of the futex word at the address +.IR uaddr . +If the value is 0, then the kernel tries to atomically set +the futex value to the caller's TID. +If the futex word's value is nonzero, +the kernel atomically sets the +.B FUTEX_WAITERS +bit, which signals the futex owner that it cannot unlock the futex in +user space atomically by setting the futex value to 0. +.\" tglx (July 2015): +.\" The operation here is similar to the FUTEX_WAIT logic. When the user +.\" space atomic acquire does not succeed because the futex value was non +.\" zero, then the waiter goes into the kernel, takes the kernel internal +.\" lock and retries the acquisition under the lock. If the acquisition +.\" does not succeed either, then it sets the FUTEX_WAITERS bit, to signal +.\" the lock owner that it needs to go into the kernel. Here is the pseudo +.\" code: +.\" +.\" lock(kernel_lock); +.\" retry: +.\" +.\" /* +.\" * Owner might have unlocked in userspace before we +.\" * were able to set the waiter bit. +.\" */ +.\" if (atomic_acquire(futex) == SUCCESS) { +.\" unlock(kernel_lock()); +.\" return 0; +.\" } +.\" +.\" /* +.\" * Owner might have unlocked after the above atomic_acquire() +.\" * attempt. +.\" */ +.\" if (atomic_set_waiters_bit(futex) != SUCCESS) +.\" goto retry; +.\" +.\" queue_waiter(); +.\" unlock(kernel_lock); +.\" block(); +.\" +After that, the kernel: +.RS +.IP 1. 3 +Tries to find the thread which is associated with the owner TID. +.IP 2. +Creates or reuses kernel state on behalf of the owner. +(If this is the first waiter, there is no kernel state for this +futex, so kernel state is created by locking the RT-mutex +and the futex owner is made the owner of the RT-mutex. +If there are existing waiters, then the existing state is reused.) +.IP 3. +Attaches the waiter to the futex +(i.e., the waiter is enqueued on the RT-mutex waiter list). +.RE +.IP +If more than one waiter exists, +the enqueueing of the waiter is in descending priority order. +(For information on priority ordering, see the discussion of the +.BR SCHED_DEADLINE , +.BR SCHED_FIFO , +and +.BR SCHED_RR +scheduling policies in +.BR sched (7).) +The owner inherits either the waiter's CPU bandwidth +(if the waiter is scheduled under the +.BR SCHED_DEADLINE +policy) or the waiter's priority (if the waiter is scheduled under the +.BR SCHED_RR +or +.BR SCHED_FIFO +policy). +.\" August 2015: +.\" mtk: If the realm is restricted purely to SCHED_OTHER (SCHED_NORMAL) +.\" processes, does the nice value come into play also? +.\" +.\" tglx: No. SCHED_OTHER/NORMAL tasks are handled in FIFO order +This inheritance follows the lock chain in the case of nested locking +.\" (i.e., task 1 blocks on lock A, held by task 2, +.\" while task 2 blocks on lock B, held by task 3) +and performs deadlock detection. +.IP +The +.I timeout +argument provides a timeout for the lock attempt. +If +.I timeout +is not NULL, the structure it points to specifies +an absolute timeout, measured against the +.BR CLOCK_REALTIME +clock. +.\" 2016-07-07 response from Thomas Gleixner on LKML: +.\" From: Thomas Gleixner +.\" Date: 6 July 2016 at 20:57 +.\" Subject: Re: futex: Allow FUTEX_CLOCK_REALTIME with FUTEX_WAIT op +.\" +.\" On Thu, 23 Jun 2016, Michael Kerrisk (man-pages) wrote: +.\" > On 06/23/2016 08:28 PM, Darren Hart wrote: +.\" > > And as a follow-on, what is the reason for FUTEX_LOCK_PI only using +.\" > > CLOCK_REALTIME? It seems reasonable to me that a user may want to wait a +.\" > > specific amount of time, regardless of wall time. +.\" > +.\" > Yes, that's another weird inconsistency. +.\" +.\" The reason is that phtread_mutex_timedlock() uses absolute timeouts based on +.\" CLOCK_REALTIME. glibc folks asked to make that the default behaviour back +.\" then when we added LOCK_PI. +If +.I timeout +is NULL, the operation will block indefinitely. +.IP +The +.IR uaddr2 , +.IR val , +and +.IR val3 +arguments are ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)" +.\" commit c87e2837be82df479a6bae9f155c43516d2feebc +This operation tries to acquire the lock at +.IR uaddr . +It is invoked when a user-space atomic acquire did not +succeed because the futex word was not 0. +.IP +Because the kernel has access to more state information than user space, +acquisition of the lock might succeed if performed by the +kernel in cases where the futex word +(i.e., the state information accessible to use-space) contains stale state +.RB ( FUTEX_WAITERS +and/or +.BR FUTEX_OWNER_DIED ). +This can happen when the owner of the futex died. +User space cannot handle this condition in a race-free manner, +but the kernel can fix this up and acquire the futex. +.\" Paraphrasing a f2f conversation with Thomas Gleixner about the +.\" above point (Aug 2015): ### +.\" There is a rare possibility of a race condition involving an +.\" uncontended futex with no owner, but with waiters. The +.\" kernel-user-space contract is that if a futex is nonzero, you must +.\" go into kernel. The futex was owned by a task, and that task dies +.\" but there are no waiters, so the futex value is non zero. +.\" Therefore, the next locker has to go into the kernel, +.\" so that the kernel has a chance to clean up. (CMXCH on zero +.\" in user space would fail, so kernel has to clean up.) +.\" Darren Hart (Oct 2015): +.\" The trylock in the kernel has more state, so it can independently +.\" verify the flags that userspace must trust implicitly. +.IP +The +.IR uaddr2 , +.IR val , +.IR timeout , +and +.IR val3 +arguments are ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_UNLOCK_PI " (since Linux 2.6.18)" +.\" commit c87e2837be82df479a6bae9f155c43516d2feebc +This operation wakes the top priority waiter that is waiting in +.B FUTEX_LOCK_PI +on the futex address provided by the +.I uaddr +argument. +.IP +This is called when the user-space value at +.I uaddr +cannot be changed atomically from a TID (of the owner) to 0. +.IP +The +.IR uaddr2 , +.IR val , +.IR timeout , +and +.IR val3 +arguments are ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_CMP_REQUEUE_PI " (since Linux 2.6.31)" +.\" commit 52400ba946759af28442dee6265c5c0180ac7122 +This operation is a PI-aware variant of +.BR FUTEX_CMP_REQUEUE . +It requeues waiters that are blocked via +.B FUTEX_WAIT_REQUEUE_PI +on +.I uaddr +from a non-PI source futex +.RI ( uaddr ) +to a PI target futex +.RI ( uaddr2 ). +.IP +As with +.BR FUTEX_CMP_REQUEUE , +this operation wakes up a maximum of +.I val +waiters that are waiting on the futex at +.IR uaddr . +However, for +.BR FUTEX_CMP_REQUEUE_PI , +.I val +is required to be 1 +(since the main point is to avoid a thundering herd). +The remaining waiters are removed from the wait queue of the source futex at +.I uaddr +and added to the wait queue of the target futex at +.IR uaddr2 . +.IP +The +.I val2 +.\" val2 is the cap on the number of requeued waiters. +.\" In the glibc pthread_cond_broadcast() implementation, this argument +.\" is specified as INT_MAX, and for pthread_cond_signal() it is 0. +and +.I val3 +arguments serve the same purposes as for +.BR FUTEX_CMP_REQUEUE . +.\" +.\" The page at http://locklessinc.com/articles/futex_cheat_sheet/ +.\" notes that "priority-inheritance Futex to priority-inheritance +.\" Futex requeues are currently unsupported". However, probably +.\" the page does not need to say nothing about this, since +.\" Thomas Gleixner commented (July 2015): "they never will be +.\" supported because they make no sense at all" +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAIT_REQUEUE_PI " (since Linux 2.6.31)" +.\" commit 52400ba946759af28442dee6265c5c0180ac7122 +.\" +Wait on a non-PI futex at +.I uaddr +and potentially be requeued (via a +.BR FUTEX_CMP_REQUEUE_PI +operation in another task) onto a PI futex at +.IR uaddr2 . +The wait operation on +.I uaddr +is the same as for +.BR FUTEX_WAIT . +.IP +The waiter can be removed from the wait on +.I uaddr +without requeueing on +.IR uaddr2 +via a +.BR FUTEX_WAKE +operation in another task. +In this case, the +.BR FUTEX_WAIT_REQUEUE_PI +operation fails with the error +.BR EAGAIN . +.IP +If +.I timeout +is not NULL, the structure it points to specifies +an absolute timeout for the wait operation. +If +.I timeout +is NULL, the operation can block indefinitely. +.IP +The +.I val3 +argument is ignored. +.IP +The +.BR FUTEX_WAIT_REQUEUE_PI +and +.BR FUTEX_CMP_REQUEUE_PI +were added to support a fairly specific use case: +support for priority-inheritance-aware POSIX threads condition variables. +The idea is that these operations should always be paired, +in order to ensure that user space and the kernel remain in sync. +Thus, in the +.BR FUTEX_WAIT_REQUEUE_PI +operation, the user-space application pre-specifies the target +of the requeue that takes place in the +.BR FUTEX_CMP_REQUEUE_PI +operation. +.\" +.\" Darren Hart notes that a patch to allow glibc to fully support +.\" PI-aware pthreads condition variables has not yet been accepted into +.\" glibc. The story is complex, and can be found at +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=11588 +.\" Darren notes that in the meantime, the patch is shipped with various +.\" PREEMPT_RT-enabled Linux systems. +.\" +.\" Related to the preceding, Darren proposed that somewhere, man-pages +.\" should document the following point: +.\" +.\" While the Linux kernel, since 2.6.31, supports requeueing of +.\" priority-inheritance (PI) aware mutexes via the +.\" FUTEX_WAIT_REQUEUE_PI and FUTEX_CMP_REQUEUE_PI futex operations, +.\" the glibc implementation does not yet take full advantage of this. +.\" Specifically, the condvar internal data lock remains a non-PI aware +.\" mutex, regardless of the type of the pthread_mutex associated with +.\" the condvar. This can lead to an unbounded priority inversion on +.\" the internal data lock even when associating a PI aware +.\" pthread_mutex with a condvar during a pthread_cond*_wait +.\" operation. For this reason, it is not recommended to rely on +.\" priority inheritance when using pthread condition variables. +.\" +.\" The problem is that the obvious location for this text is +.\" the pthread_cond*wait(3) man page. However, such a man page +.\" does not currently exist. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SH RETURN VALUE +.PP +In the event of an error (and assuming that +.BR futex () +was invoked via +.BR syscall (2)), +all operations return \-1 and set +.I errno +to indicate the cause of the error. +.PP +The return value on success depends on the operation, +as described in the following list: +.TP +.B FUTEX_WAIT +Returns 0 if the caller was woken up. +Note that a wake-up can also be caused by common futex usage patterns +in unrelated code that happened to have previously used the futex word's +memory location (e.g., typical futex-based implementations of +Pthreads mutexes can cause this under some conditions). +Therefore, callers should always conservatively assume that a return +value of 0 can mean a spurious wake-up, and use the futex word's value +(i.e., the user-space synchronization scheme) +to decide whether to continue to block or not. +.TP +.B FUTEX_WAKE +Returns the number of waiters that were woken up. +.TP +.B FUTEX_FD +Returns the new file descriptor associated with the futex. +.TP +.B FUTEX_REQUEUE +Returns the number of waiters that were woken up. +.TP +.B FUTEX_CMP_REQUEUE +Returns the total number of waiters that were woken up or +requeued to the futex for the futex word at +.IR uaddr2 . +If this value is greater than +.IR val , +then the difference is the number of waiters requeued to the futex for the +futex word at +.IR uaddr2 . +.TP +.B FUTEX_WAKE_OP +Returns the total number of waiters that were woken up. +This is the sum of the woken waiters on the two futexes for +the futex words at +.I uaddr +and +.IR uaddr2 . +.TP +.B FUTEX_WAIT_BITSET +Returns 0 if the caller was woken up. +See +.B FUTEX_WAIT +for how to interpret this correctly in practice. +.TP +.B FUTEX_WAKE_BITSET +Returns the number of waiters that were woken up. +.TP +.B FUTEX_LOCK_PI +Returns 0 if the futex was successfully locked. +.TP +.B FUTEX_TRYLOCK_PI +Returns 0 if the futex was successfully locked. +.TP +.B FUTEX_UNLOCK_PI +Returns 0 if the futex was successfully unlocked. +.TP +.B FUTEX_CMP_REQUEUE_PI +Returns the total number of waiters that were woken up or +requeued to the futex for the futex word at +.IR uaddr2 . +If this value is greater than +.IR val , +then difference is the number of waiters requeued to the futex for +the futex word at +.IR uaddr2 . +.TP +.B FUTEX_WAIT_REQUEUE_PI +Returns 0 if the caller was successfully requeued to the futex for +the futex word at +.IR uaddr2 . +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SH ERRORS +.TP +.B EACCES +No read access to the memory of a futex word. +.TP +.B EAGAIN +.RB ( FUTEX_WAIT , +.BR FUTEX_WAIT_BITSET , +.BR FUTEX_WAIT_REQUEUE_PI ) +The value pointed to by +.I uaddr +was not equal to the expected value +.I val +at the time of the call. +.IP +.BR Note : +on Linux, the symbolic names +.B EAGAIN +and +.B EWOULDBLOCK +(both of which appear in different parts of the kernel futex code) +have the same value. +.TP +.B EAGAIN +.RB ( FUTEX_CMP_REQUEUE , +.BR FUTEX_CMP_REQUEUE_PI ) +The value pointed to by +.I uaddr +is not equal to the expected value +.IR val3 . +.TP +.BR EAGAIN +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The futex owner thread ID of +.I uaddr +(for +.BR FUTEX_CMP_REQUEUE_PI : +.IR uaddr2 ) +is about to exit, +but has not yet handled the internal state cleanup. +Try again. +.TP +.BR EDEADLK +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The futex word at +.I uaddr +is already locked by the caller. +.TP +.BR EDEADLK +.\" FIXME . I see that kernel/locking/rtmutex.c uses EDEADLK in some +.\" places, and EDEADLOCK in others. On almost all architectures +.\" these constants are synonymous. Is there a reason that both +.\" names are used? +.\" +.\" tglx (July 2015): "No. We should probably fix that." +.\" +.RB ( FUTEX_CMP_REQUEUE_PI ) +While requeueing a waiter to the PI futex for the futex word at +.IR uaddr2 , +the kernel detected a deadlock. +.TP +.B EFAULT +A required pointer argument (i.e., +.IR uaddr , +.IR uaddr2 , +or +.IR timeout ) +did not point to a valid user-space address. +.TP +.B EINTR +A +.B FUTEX_WAIT +or +.B FUTEX_WAIT_BITSET +operation was interrupted by a signal (see +.BR signal (7)). +In kernels before Linux 2.6.22, this error could also be returned for +a spurious wakeup; since Linux 2.6.22, this no longer happens. +.TP +.B EINVAL +The operation in +.IR futex_op +is one of those that employs a timeout, but the supplied +.I timeout +argument was invalid +.RI ( tv_sec +was less than zero, or +.IR tv_nsec +was not less than 1,000,000,000). +.TP +.B EINVAL +The operation specified in +.IR futex_op +employs one or both of the pointers +.I uaddr +and +.IR uaddr2 , +but one of these does not point to a valid object\(emthat is, +the address is not four-byte-aligned. +.TP +.B EINVAL +.RB ( FUTEX_WAIT_BITSET , +.BR FUTEX_WAKE_BITSET ) +The bit mask supplied in +.IR val3 +is zero. +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +.I uaddr +equals +.IR uaddr2 +(i.e., an attempt was made to requeue to the same futex). +.TP +.BR EINVAL +.RB ( FUTEX_FD ) +The signal number supplied in +.I val +is invalid. +.TP +.B EINVAL +.RB ( FUTEX_WAKE , +.BR FUTEX_WAKE_OP , +.BR FUTEX_WAKE_BITSET , +.BR FUTEX_REQUEUE , +.BR FUTEX_CMP_REQUEUE ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state\(emthat is, it detected a waiter which waits in +.BR FUTEX_LOCK_PI +on +.IR uaddr . +.TP +.B EINVAL +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_UNLOCK_PI ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state. +This indicates either state corruption +or that the kernel found a waiter on +.I uaddr +which is waiting via +.BR FUTEX_WAIT +or +.BR FUTEX_WAIT_BITSET . +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +The kernel detected an inconsistency between the user-space state at +.I uaddr2 +and the kernel state; +.\" From a conversation with Thomas Gleixner (Aug 2015): ### +.\" The kernel sees: I have non PI state for a futex you tried to +.\" tell me was PI +that is, the kernel detected a waiter which waits via +.BR FUTEX_WAIT +or +.BR FUTEX_WAIT_BITSET +on +.IR uaddr2 . +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state; +that is, the kernel detected a waiter which waits via +.BR FUTEX_WAIT +or +.BR FUTEX_WAIT_BITESET +on +.IR uaddr . +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state; +that is, the kernel detected a waiter which waits on +.I uaddr +via +.BR FUTEX_LOCK_PI +(instead of +.BR FUTEX_WAIT_REQUEUE_PI ). +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +.\" This deals with the case: +.\" wait_requeue_pi(A, B); +.\" requeue_pi(A, C); +An attempt was made to requeue a waiter to a futex other than that +specified by the matching +.B FUTEX_WAIT_REQUEUE_PI +call for that waiter. +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +The +.I val +argument is not 1. +.TP +.B EINVAL +Invalid argument. +.TP +.B ENFILE +.RB ( FUTEX_FD ) +The system-wide limit on the total number of open files has been reached. +.TP +.BR ENOMEM +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The kernel could not allocate memory to hold state information. +.TP +.B ENOSYS +Invalid operation specified in +.IR futex_op . +.TP +.B ENOSYS +The +.BR FUTEX_CLOCK_REALTIME +option was specified in +.IR futex_op , +but the accompanying operation was neither +.BR FUTEX_WAIT , +.BR FUTEX_WAIT_BITSET , +nor +.BR FUTEX_WAIT_REQUEUE_PI . +.TP +.BR ENOSYS +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_UNLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI , +.BR FUTEX_WAIT_REQUEUE_PI ) +A run-time check determined that the operation is not available. +The PI-futex operations are not implemented on all architectures and +are not supported on some CPU variants. +.TP +.BR EPERM +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The caller is not allowed to attach itself to the futex at +.I uaddr +(for +.BR FUTEX_CMP_REQUEUE_PI : +the futex at +.IR uaddr2 ). +(This may be caused by a state corruption in user space.) +.TP +.BR EPERM +.RB ( FUTEX_UNLOCK_PI ) +The caller does not own the lock represented by the futex word. +.TP +.BR ESRCH +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The thread ID in the futex word at +.I uaddr +does not exist. +.TP +.BR ESRCH +.RB ( FUTEX_CMP_REQUEUE_PI ) +The thread ID in the futex word at +.I uaddr2 +does not exist. +.TP +.B ETIMEDOUT +The operation in +.IR futex_op +employed the timeout specified in +.IR timeout , +and the timeout expired before the operation completed. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SH VERSIONS +.PP +Futexes were first made available in a stable kernel release +with Linux 2.6.0. +.PP +Initial futex support was merged in Linux 2.5.7 but with different +semantics from what was described above. +A four-argument system call with the semantics +described in this page was introduced in Linux 2.5.40. +A fifth argument was added in Linux 2.5.70, +and a sixth argument was added in Linux 2.6.7. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.PP +Several higher-level programming abstractions are implemented via futexes, +including POSIX semaphores and +various POSIX threads synchronization mechanisms +(mutexes, condition variables, read-write locks, and barriers). +.\" TODO FIXME(Torvald) Above, we cite this section and claim it contains +.\" details on the synchronization semantics; add the C11 equivalents +.\" here (or whatever we find consensus for). +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SH EXAMPLE +The program below demonstrates use of futexes in a program where a parent +process and a child process use a pair of futexes located inside a +shared anonymous mapping to synchronize access to a shared resource: +the terminal. +The two processes each write +.IR nloops +(a command-line argument that defaults to 5 if omitted) +messages to the terminal and employ a synchronization protocol +that ensures that they alternate in writing messages. +Upon running this program we see output such as the following: +.PP +.in +4n +.EX +$ \fB./futex_demo\fP +Parent (18534) 0 +Child (18535) 0 +Parent (18534) 1 +Child (18535) 1 +Parent (18534) 2 +Child (18535) 2 +Parent (18534) 3 +Child (18535) 3 +Parent (18534) 4 +Child (18535) 4 +.EE +.in +.SS Program source +\& +.EX +/* futex_demo.c + + Usage: futex_demo [nloops] + (Default: 5) + + Demonstrate the use of futexes in a program where parent and child + use a pair of futexes located inside a shared anonymous mapping to + synchronize access to a shared resource: the terminal. The two + processes each write \(aqnum\-loops\(aq messages to the terminal and employ + a synchronization protocol that ensures that they alternate in + writing messages. +*/ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +static int *futex1, *futex2, *iaddr; + +static int +futex(int *uaddr, int futex_op, int val, + const struct timespec *timeout, int *uaddr2, int val3) +{ + return syscall(SYS_futex, uaddr, futex_op, val, + timeout, uaddr, val3); +} + +/* Acquire the futex pointed to by \(aqfutexp\(aq: wait for its value to + become 1, and then set the value to 0. */ + +static void +fwait(int *futexp) +{ + int s; + + /* __sync_bool_compare_and_swap(ptr, oldval, newval) is a gcc + built\-in function. It atomically performs the equivalent of: + + if (*ptr == oldval) + *ptr = newval; + + It returns true if the test yielded true and *ptr was updated. + The alternative here would be to employ the equivalent atomic + machine\-language instructions. For further information, see + the GCC Manual. */ + + while (1) { + + /* Is the futex available? */ + + if (__sync_bool_compare_and_swap(futexp, 1, 0)) + break; /* Yes */ + + /* Futex is not available; wait */ + + s = futex(futexp, FUTEX_WAIT, 0, NULL, NULL, 0); + if (s == \-1 && errno != EAGAIN) + errExit("futex\-FUTEX_WAIT"); + } +} + +/* Release the futex pointed to by \(aqfutexp\(aq: if the futex currently + has the value 0, set its value to 1 and the wake any futex waiters, + so that if the peer is blocked in fpost(), it can proceed. */ + +static void +fpost(int *futexp) +{ + int s; + + /* __sync_bool_compare_and_swap() was described in comments above */ + + if (__sync_bool_compare_and_swap(futexp, 0, 1)) { + + s = futex(futexp, FUTEX_WAKE, 1, NULL, NULL, 0); + if (s == \-1) + errExit("futex\-FUTEX_WAKE"); + } +} + +int +main(int argc, char *argv[]) +{ + pid_t childPid; + int j, nloops; + + setbuf(stdout, NULL); + + nloops = (argc > 1) ? atoi(argv[1]) : 5; + + /* Create a shared anonymous mapping that will hold the futexes. + Since the futexes are being shared between processes, we + subsequently use the "shared" futex operations (i.e., not the + ones suffixed "_PRIVATE") */ + + iaddr = mmap(NULL, sizeof(int) * 2, PROT_READ | PROT_WRITE, + MAP_ANONYMOUS | MAP_SHARED, \-1, 0); + if (iaddr == MAP_FAILED) + errExit("mmap"); + + futex1 = &iaddr[0]; + futex2 = &iaddr[1]; + + *futex1 = 0; /* State: unavailable */ + *futex2 = 1; /* State: available */ + + /* Create a child process that inherits the shared anonymous + mapping */ + + childPid = fork(); + if (childPid == \-1) + errExit("fork"); + + if (childPid == 0) { /* Child */ + for (j = 0; j < nloops; j++) { + fwait(futex1); + printf("Child (%ld) %d\\n", (long) getpid(), j); + fpost(futex2); + } + + exit(EXIT_SUCCESS); + } + + /* Parent falls through to here */ + + for (j = 0; j < nloops; j++) { + fwait(futex2); + printf("Parent (%ld) %d\\n", (long) getpid(), j); + fpost(futex1); + } + + wait(NULL); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.BR get_robust_list (2), +.BR restart_syscall (2), +.BR pthread_mutexattr_getprotocol (3), +.BR futex (7), +.BR sched (7) +.PP +The following kernel source files: +.IP * 2 +.I Documentation/pi-futex.txt +.IP * +.I Documentation/futex-requeue-pi.txt +.IP * +.I Documentation/locking/rt-mutex.txt +.IP * +.I Documentation/locking/rt-mutex-design.txt +.IP * +.I Documentation/robust-futex-ABI.txt +.PP +Franke, H., Russell, R., and Kirwood, M., 2002. +\fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP +(from proceedings of the Ottawa Linux Symposium 2002), +.br +.UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf +.UE +.PP +Hart, D., 2009. \fIA futex overview and update\fP, +.UR http://lwn.net/Articles/360699/ +.UE +.PP +Hart, D. and Guniguntala, D., 2009. +\fIRequeue-PI: Making Glibc Condvars PI-Aware\fP +(from proceedings of the 2009 Real-Time Linux Workshop), +.UR http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf +.UE +.PP +Drepper, U., 2011. \fIFutexes Are Tricky\fP, +.UR http://www.akkadia.org/drepper/futex.pdf +.UE +.PP +Futex example library, futex-*.tar.bz2 at +.br +.UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ +.UE +.\" +.\" FIXME(Torvald) We should probably refer to the glibc code here, in +.\" particular the glibc-internal futex wrapper functions that are +.\" WIP, and the generic pthread_mutex_t and perhaps condvar +.\" implementations. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/futimesat.2 b/man2/futimesat.2 new file mode 100644 index 0000000..8991c98 --- /dev/null +++ b/man2/futimesat.2 @@ -0,0 +1,142 @@ +.\" This manpage is Copyright (C) 2006, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FUTIMESAT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +futimesat \- change timestamps of a file relative to a \ +directory file descriptor +.SH SYNOPSIS +.nf +.B #include /* Definition of AT_* constants */ +.B #include +.PP +.BI "int futimesat(int " dirfd ", const char *" pathname , +.BI " const struct timeval " times [2]); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR futimesat (): +_GNU_SOURCE +.SH DESCRIPTION +This system call is obsolete. +Use +.BR utimensat (2) +instead. +.PP +The +.BR futimesat () +system call operates in exactly the same way as +.BR utimes (2), +except for the differences described in this manual page. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR utimes (2) +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR utimes (2)). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.SH RETURN VALUE +On success, +.BR futimesat () +returns a 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +The same errors that occur for +.BR utimes (2) +can also occur for +.BR futimesat (). +The following additional errors can occur for +.BR futimesat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR futimesat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +This system call is nonstandard. +It was implemented from a specification that was proposed for POSIX.1, +but that specification was replaced by the one for +.BR utimensat (2). +.PP +A similar system call exists on Solaris. +.SH NOTES +.SS Glibc notes +If +.I pathname +is NULL, then the glibc +.BR futimesat () +wrapper function updates the times for the file referred to by +.IR dirfd . +.\" The Solaris futimesat() also has this strangeness. +.SH SEE ALSO +.BR stat (2), +.BR utimensat (2), +.BR utimes (2), +.BR futimes (3), +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/get_kernel_syms.2 b/man2/get_kernel_syms.2 new file mode 100644 index 0000000..c4233ac --- /dev/null +++ b/man2/get_kernel_syms.2 @@ -0,0 +1,104 @@ +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" reformatting and rewordings by mtk +.\" +.TH GET_KERNEL_SYMS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +get_kernel_syms \- retrieve exported kernel and module symbols +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int get_kernel_syms(struct kernel_sym *" table ); +.fi +.PP +.IR Note : +No declaration of this system call is provided in glibc headers; see NOTES. +.SH DESCRIPTION +.BR Note : +This system call is present only in kernels before Linux 2.6. +.PP +If +.I table +is NULL, +.BR get_kernel_syms () +returns the number of symbols available for query. +Otherwise, it fills in a table of structures: +.PP +.in +4n +.EX +struct kernel_sym { + unsigned long value; + char name[60]; +}; +.EE +.in +.PP +The symbols are interspersed with magic symbols of the form +.BI # module-name +with the kernel having an empty name. +The value associated with a symbol of this form is the address at +which the module is loaded. +.PP +The symbols exported from each module follow their magic module tag +and the modules are returned in the reverse of the +order in which they were loaded. +.SH RETURN VALUE +On success, returns the number of symbols copied to +.IR table . +On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +There is only one possible error return: +.TP +.B ENOSYS +.BR get_kernel_syms () +is not supported in this version of the kernel. +.SH VERSIONS +This system call is present on Linux only up until kernel 2.4; +it was removed in Linux 2.6. +.\" Removed in Linux 2.5.48 +.SH CONFORMING TO +.BR get_kernel_syms () +is Linux-specific. +.SH NOTES +This obsolete system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it was sufficient to manually declare the interface in your code; +alternatively, you could invoke the system call using +.BR syscall (2). +.SH BUGS +There is no way to indicate the size of the buffer allocated for +.IR table . +If symbols have been added to the kernel since the +program queried for the symbol table size, memory will be corrupted. +.PP +The length of exported symbol names is limited to 59 characters. +.PP +Because of these limitations, this system call is deprecated in +favor of +.BR query_module (2) +(which is itself nowadays deprecated +in favor of other interfaces described on its manual page). +.SH SEE ALSO +.BR create_module (2), +.BR delete_module (2), +.BR init_module (2), +.BR query_module (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2 new file mode 100644 index 0000000..774e036 --- /dev/null +++ b/man2/get_mempolicy.2 @@ -0,0 +1,260 @@ +.\" Copyright 2003,2004 Andi Kleen, SuSE Labs. +.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard +.\" +.\" %%%LICENSE_START(VERBATIM_PROF) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2006-02-03, mtk, substantial wording changes and other improvements +.\" 2007-08-27, Lee Schermerhorn +.\" more precise specification of behavior. +.\" +.TH GET_MEMPOLICY 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +get_mempolicy \- retrieve NUMA memory policy for a thread +.SH SYNOPSIS +.B "#include " +.nf +.PP +.BI "long get_mempolicy(int *" mode ", unsigned long *" nodemask , +.BI " unsigned long " maxnode ", void *" addr , +.BI " unsigned long " flags ); +.PP +Link with \fI\-lnuma\fP. +.fi +.SH DESCRIPTION +.BR get_mempolicy () +retrieves the NUMA policy of the calling thread or of a memory address, +depending on the setting of +.IR flags . +.PP +A NUMA machine has different +memory controllers with different distances to specific CPUs. +The memory policy defines from which node memory is allocated for +the thread. +.PP +If +.I flags +is specified as 0, +then information about the calling thread's default policy +(as set by +.BR set_mempolicy (2)) +is returned, in the buffers pointed to by +.I mode +and +.IR nodemask . +The value returned in these arguments +may be used to restore the thread's policy to its state at +the time of the call to +.BR get_mempolicy () +using +.BR set_mempolicy (2). +When +.I flags +is 0, +.I addr +must be specified as NULL. +.PP +If +.I flags +specifies +.BR MPOL_F_MEMS_ALLOWED +(available since Linux 2.6.24), the +.I mode +argument is ignored and the set of nodes (memories) that the +thread is allowed to specify in subsequent calls to +.BR mbind (2) +or +.BR set_mempolicy (2) +(in the absence of any +.IR "mode flags" ) +is returned in +.IR nodemask . +It is not permitted to combine +.B MPOL_F_MEMS_ALLOWED +with either +.B MPOL_F_ADDR +or +.BR MPOL_F_NODE . +.PP +If +.I flags +specifies +.BR MPOL_F_ADDR , +then information is returned about the policy governing the memory +address given in +.IR addr . +This policy may be different from the thread's default policy if +.BR mbind (2) +or one of the helper functions described in +.BR numa (3) +has been used to establish a policy for the memory range containing +.IR addr . +.PP +If the +.I mode +argument is not NULL, then +.BR get_mempolicy () +will store the policy mode and any optional +.I "mode flags" +of the requested NUMA policy in the location pointed to by this argument. +If +.I nodemask +is not NULL, then the nodemask associated with the policy will be stored +in the location pointed to by this argument. +.I maxnode +specifies the number of node IDs +that can be stored into +.IR nodemask \(emthat +is, the maximum node ID plus one. +The value specified by +.I maxnode +is always rounded to a multiple of +.IR "sizeof(unsigned\ long)*8" . +.PP +If +.I flags +specifies both +.B MPOL_F_NODE +and +.BR MPOL_F_ADDR , +.BR get_mempolicy () +will return the node ID of the node on which the address +.I addr +is allocated into the location pointed to by +.IR mode . +If no page has yet been allocated for the specified address, +.BR get_mempolicy () +will allocate a page as if the thread had performed a read +(load) access to that address, and return the ID of the node +where that page was allocated. +.PP +If +.I flags +specifies +.BR MPOL_F_NODE , +but not +.BR MPOL_F_ADDR , +and the thread's current policy is +.BR MPOL_INTERLEAVE , +then +.BR get_mempolicy () +will return in the location pointed to by a non-NULL +.I mode +argument, +the node ID of the next node that will be used for +interleaving of internal kernel pages allocated on behalf of the thread. +.\" Note: code returns next interleave node via 'mode' argument -Lee Schermerhorn +These allocations include pages for memory-mapped files in +process memory ranges mapped using the +.BR mmap (2) +call with the +.B MAP_PRIVATE +flag for read accesses, and in memory ranges mapped with the +.B MAP_SHARED +flag for all accesses. +.PP +Other flag values are reserved. +.PP +For an overview of the possible policies see +.BR set_mempolicy (2). +.SH RETURN VALUE +On success, +.BR get_mempolicy () +returns 0; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Part of all of the memory range specified by +.I nodemask +and +.I maxnode +points outside your accessible address space. +.TP +.B EINVAL +The value specified by +.I maxnode +is less than the number of node IDs supported by the system. +Or +.I flags +specified values other than +.B MPOL_F_NODE +or +.BR MPOL_F_ADDR ; +or +.I flags +specified +.B MPOL_F_ADDR +and +.I addr +is NULL, +or +.I flags +did not specify +.B MPOL_F_ADDR +and +.I addr +is not NULL. +Or, +.I flags +specified +.B MPOL_F_NODE +but not +.B MPOL_F_ADDR +and the current thread policy is not +.BR MPOL_INTERLEAVE . +Or, +.I flags +specified +.B MPOL_F_MEMS_ALLOWED +with either +.B MPOL_F_ADDR +or +.BR MPOL_F_NODE . +(And there are other +.B EINVAL +cases.) +.SH VERSIONS +The +.BR get_mempolicy () +system call was added to the Linux kernel in version 2.6.7. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +For information on library support, see +.BR numa (7). +.SH SEE ALSO +.BR getcpu (2), +.BR mbind (2), +.BR mmap (2), +.BR set_mempolicy (2), +.BR numa (3), +.BR numa (7), +.BR numactl (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2 new file mode 100644 index 0000000..94209e5 --- /dev/null +++ b/man2/get_robust_list.2 @@ -0,0 +1,181 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Written by Ivana Varekova +.\" and Copyright (c) 2017, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" FIXME Something could be added to this page (or exit(2)) +.\" about exit_robust_list processing +.\" +.TH GET_ROBUST_LIST 2 2017-09-15 Linux "Linux System Calls" +.SH NAME +get_robust_list, set_robust_list \- get/set list of robust futexes +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "long get_robust_list(int " pid ", struct robust_list_head **" head_ptr , +.BI " size_t *" len_ptr ); +.BI "long set_robust_list(struct robust_list_head *" head ", size_t " len ); +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +These system calls deal with per-thread robust futex lists. +These lists are managed in user space: +the kernel knows only about the location of the head of the list. +A thread can inform the kernel of the location of its robust futex list using +.BR set_robust_list (). +The address of a thread's robust futex list can be obtained using +.BR get_robust_list (). +.PP +The purpose of the robust futex list is to ensure that if a thread +accidentally fails to unlock a futex before terminating or calling +.BR execve (2), +another thread that is waiting on that futex is notified that +the former owner of the futex has died. +This notification consists of two pieces: the +.BR FUTEX_OWNER_DIED +bit is set in the futex word, and the kernel performs a +.BR futex (2) +.BR FUTEX_WAKE +operation on one of the threads waiting on the futex. +.PP +The +.BR get_robust_list () +system call returns the head of the robust futex list of the thread +whose thread ID is specified in +.IR pid . +If +.I pid +is 0, +the head of the list for the calling thread is returned. +The list head is stored in the location pointed to by +.IR head_ptr . +The size of the object pointed to by +.I **head_ptr +is stored in +.IR len_ptr . +.PP +Permission to employ +.BR get_robust_list () +is governed by a ptrace access mode +.B PTRACE_MODE_READ_REALCREDS +check; see +.BR ptrace (2). +.PP +The +.BR set_robust_list () +system call requests the kernel to record the head of the list of +robust futexes owned by the calling thread. +The +.I head +argument is the list head to record. +The +.I len +argument should be +.IR sizeof(*head) . +.SH RETURN VALUE +The +.BR set_robust_list () +and +.BR get_robust_list () +system calls return zero when the operation is successful, +an error code otherwise. +.SH ERRORS +The +.BR set_robust_list () +system call can fail with the following error: +.TP +.B EINVAL +.I len +does not equal +.IR "sizeof(struct\ robust_list_head)" . +.PP +The +.BR get_robust_list () +system call can fail with the following errors: +.TP +.B EPERM +The calling process does not have permission to see the robust futex list of +the thread with the thread ID +.IR pid , +and does not have the +.BR CAP_SYS_PTRACE +capability. +.TP +.B ESRCH +No thread with the thread ID +.I pid +could be found. +.TP +.B EFAULT +The head of the robust futex list can't be stored at the location +.IR head . +.SH VERSIONS +These system calls were added in Linux 2.6.17. +.SH NOTES +These system calls are not needed by normal applications. +No support for them is provided in glibc. +In the unlikely event that you want to call them directly, use +.BR syscall (2). +.PP +A thread can have only one robust futex list; +therefore applications that wish +to use this functionality should use the robust mutexes provided by glibc. +.PP +In the initial implementation, +a thread waiting on a futex was notified that the owner had died +only if the owner terminated. +Starting with Linux 2.6.28, +.\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7 +notification was extended to include the case where the owner performs an +.BR execve (2). +.PP +The thread IDs mentioned in the main text are +.I kernel +thread IDs of the kind returned by +.BR clone (2) +and +.BR gettid (2). +.SH SEE ALSO +.BR futex (2), +.BR pthread_mutexattr_setrobust (3) +.PP +.IR Documentation/robust-futexes.txt +and +.IR Documentation/robust-futex-ABI.txt +in the Linux kernel source tree +.\" http://lwn.net/Articles/172149/ +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/get_thread_area.2 b/man2/get_thread_area.2 new file mode 100644 index 0000000..a03fe54 --- /dev/null +++ b/man2/get_thread_area.2 @@ -0,0 +1 @@ +.so man2/set_thread_area.2 diff --git a/man2/getcontext.2 b/man2/getcontext.2 new file mode 100644 index 0000000..b01818d --- /dev/null +++ b/man2/getcontext.2 @@ -0,0 +1 @@ +.so man3/getcontext.3 diff --git a/man2/getcpu.2 b/man2/getcpu.2 new file mode 100644 index 0000000..ece7062 --- /dev/null +++ b/man2/getcpu.2 @@ -0,0 +1,156 @@ +.\" This man page is Copyright (C) 2006 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" 2008, mtk, various edits +.\" +.TH GETCPU 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getcpu \- determine CPU and NUMA node on which the calling thread is running +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getcpu(unsigned *" cpu ", unsigned *" node \ +", struct getcpu_cache *" tcache ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The +.BR getcpu () +system call identifies the processor and node on which the calling +thread or process is currently running and writes them into the +integers pointed to by the +.I cpu +and +.I node +arguments. +The processor is a unique small integer identifying a CPU. +The node is a unique small identifier identifying a NUMA node. +When either +.I cpu +or +.I node +is NULL nothing is written to the respective pointer. +.PP +The third argument to this system call is nowadays unused, +and should be specified as NULL +unless portability to Linux 2.6.23 or earlier is required (see NOTES). +.PP +The information placed in +.I cpu +is guaranteed to be current only at the time of the call: +unless the CPU affinity has been fixed using +.BR sched_setaffinity (2), +the kernel might change the CPU at any time. +(Normally this does not happen +because the scheduler tries to minimize movements between CPUs to +keep caches hot, but it is possible.) +The caller must allow for the possibility that the information returned in +.I cpu +and +.I node +is no longer current by the time the call returns. +.SH RETURN VALUE +On success, 0 is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Arguments point outside the calling process's address space. +.SH VERSIONS +.BR getcpu () +was added in kernel 2.6.19 for x86-64 and i386. +.SH CONFORMING TO +.BR getcpu () +is Linux-specific. +.SH NOTES +Linux makes a best effort to make this call as fast as possible. +(On some architectures, this is done via an implementation in the +.BR vdso (7).) +The intention of +.BR getcpu () +is to allow programs to make optimizations with per-CPU data +or for NUMA optimization. +.PP +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2); +or use +.BR sched_getcpu (3) +instead. +.PP +The +.I tcache +argument is unused since Linux 2.6.24. +.\" commit 4307d1e5ada595c87f9a4d16db16ba5edb70dcb1 +.\" Author: Ingo Molnar +.\" Date: Wed Nov 7 18:37:48 2007 +0100 +.\" x86: ignore the sys_getcpu() tcache parameter +In earlier kernels, +if this argument was non-NULL, +then it specified a pointer to a caller-allocated buffer in thread-local +storage that was used to provide a caching mechanism for +.BR getcpu (). +Use of the cache could speed +.BR getcpu () +calls, at the cost that there was a very small chance that +the returned information would be out of date. +The caching mechanism was considered to cause problems when +migrating threads between CPUs, and so the argument is now ignored. +.\" +.\" ===== Before kernel 2.6.24: ===== +.\" .I tcache +.\" is a pointer to a +.\" .IR "struct getcpu_cache" +.\" that is used as a cache by +.\" .BR getcpu (). +.\" The caller should put the cache into a thread-local variable +.\" if the process is multithreaded, +.\" because the cache cannot be shared between different threads. +.\" .I tcache +.\" can be NULL. +.\" If it is not NULL +.\" .BR getcpu () +.\" will use it to speed up operation. +.\" The information inside the cache is private to the system call +.\" and should not be accessed by the user program. +.\" The information placed in the cache can change between kernel releases. +.\" +.\" When no cache is specified +.\" .BR getcpu () +.\" will be slower, +.\" but always retrieve the current CPU and node information. +.\" With a cache +.\" .BR getcpu () +.\" is faster. +.\" However, the cached information is updated only once per jiffy (see +.\" .BR time (7)). +.\" This means that the information could theoretically be out of date, +.\" although in practice the scheduler's attempt to maintain +.\" soft CPU affinity means that the information is unlikely to change +.\" over the course of the caching interval. +.SH SEE ALSO +.BR mbind (2), +.BR sched_setaffinity (2), +.BR set_mempolicy (2), +.BR sched_getcpu (3), +.BR cpuset (7), +.BR vdso (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getcwd.2 b/man2/getcwd.2 new file mode 100644 index 0000000..f73c157 --- /dev/null +++ b/man2/getcwd.2 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man2/getdents.2 b/man2/getdents.2 new file mode 100644 index 0000000..73d57cc --- /dev/null +++ b/man2/getdents.2 @@ -0,0 +1,320 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright 2008, 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" Modified 22 July 1995 by Michael Chastain : +.\" Derived from 'readdir.2'. +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" +.TH GETDENTS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getdents, getdents64 \- get directory entries +.SH SYNOPSIS +.nf +.BI "int getdents(unsigned int " fd ", struct linux_dirent *" dirp , +.BI " unsigned int " count ); +.BI "int getdents64(unsigned int " fd ", struct linux_dirent64 *" dirp , +.BI " unsigned int " count ); +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +These are not the interfaces you are interested in. +Look at +.BR readdir (3) +for the POSIX-conforming C library interface. +This page documents the bare kernel system call interfaces. +.SS getdents() +The system call +.BR getdents () +reads several +.I linux_dirent +structures from the directory +referred to by the open file descriptor +.I fd +into the buffer pointed to by +.IR dirp . +The argument +.I count +specifies the size of that buffer. +.PP +The +.I linux_dirent +structure is declared as follows: +.PP +.in +4n +.EX +struct linux_dirent { + unsigned long d_ino; /* Inode number */ + unsigned long d_off; /* Offset to next \fIlinux_dirent\fP */ + unsigned short d_reclen; /* Length of this \fIlinux_dirent\fP */ + char d_name[]; /* Filename (null-terminated) */ + /* length is actually (d_reclen \- 2 \- + offsetof(struct linux_dirent, d_name)) */ + /* + char pad; // Zero padding byte + char d_type; // File type (only since Linux + // 2.6.4); offset is (d_reclen \- 1) + */ +} +.EE +.in +.PP +.I d_ino +is an inode number. +.I d_off +is the distance from the start of the directory to the start of the next +.IR linux_dirent . +.I d_reclen +is the size of this entire +.IR linux_dirent . +.I d_name +is a null-terminated filename. +.PP +.I d_type +is a byte at the end of the structure that indicates the file type. +It contains one of the following values (defined in +.IR ): +.TP 12 +.B DT_BLK +This is a block device. +.TP +.B DT_CHR +This is a character device. +.TP +.B DT_DIR +This is a directory. +.TP +.B DT_FIFO +This is a named pipe (FIFO). +.TP +.B DT_LNK +This is a symbolic link. +.TP +.B DT_REG +This is a regular file. +.TP +.B DT_SOCK +This is a UNIX domain socket. +.TP +.B DT_UNKNOWN +The file type is unknown. +.PP +The +.I d_type +field is implemented since Linux 2.6.4. +It occupies a space that was previously a zero-filled padding byte in the +.IR linux_dirent +structure. +Thus, on kernels up to and including 2.6.3, +attempting to access this field always provides the value 0 +.RB ( DT_UNKNOWN ). +.PP +Currently, +.\" kernel 2.6.27 +.\" The same sentence is in readdir.2 +only some filesystems (among them: Btrfs, ext2, ext3, and ext4) +have full support for returning the file type in +.IR d_type . +All applications must properly handle a return of +.BR DT_UNKNOWN . +.SS getdents64() +The original Linux +.BR getdents () +system call did not handle large filesystems and large file offsets. +Consequently, Linux 2.4 added +.BR getdents64 (), +with wider types for the +.I d_ino +and +.I d_off +fields. +In addition, +.BR getdents64 () +supports an explicit +.I d_type +field. +.PP +The +.BR getdents64 () +system call is like +.BR getdents (), +except that its second argument is a pointer to a buffer containing +structures of the following type: +.PP +.EX +.in +4n +struct linux_dirent64 { + ino64_t d_ino; /* 64-bit inode number */ + off64_t d_off; /* 64-bit offset to next structure */ + unsigned short d_reclen; /* Size of this dirent */ + unsigned char d_type; /* File type */ + char d_name[]; /* Filename (null-terminated) */ +}; +.EE +.in +.SH RETURN VALUE +On success, the number of bytes read is returned. +On end of directory, 0 is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +Invalid file descriptor +.IR fd . +.TP +.B EFAULT +Argument points outside the calling process's address space. +.TP +.B EINVAL +Result buffer is too small. +.TP +.B ENOENT +No such directory. +.TP +.B ENOTDIR +File descriptor does not refer to a directory. +.SH CONFORMING TO +SVr4. +.\" SVr4 documents additional ENOLINK, EIO error conditions. +.SH NOTES +Glibc does not provide a wrapper for these system calls; call them using +.BR syscall (2). +You will need to define the +.I linux_dirent +or +.I linux_dirent64 +structure yourself. +However, you probably want to use +.BR readdir (3) +instead. +.PP +These calls supersede +.BR readdir (2). +.SH EXAMPLE +.\" FIXME The example program needs to be revised, since it uses the older +.\" getdents() system call and the structure with smaller field widths. +The program below demonstrates the use of +.BR getdents (). +The following output shows an example of what we see when running this +program on an ext2 directory: +.PP +.in +4n +.EX +.RB "$" " ./a.out /testfs/" +--------------- nread=120 --------------- +inode# file type d_reclen d_off d_name + 2 directory 16 12 . + 2 directory 16 24 .. + 11 directory 24 44 lost+found + 12 regular 16 56 a + 228929 directory 16 68 sub + 16353 directory 16 80 sub2 + 130817 directory 16 4096 sub3 +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include /* Defines DT_* constants */ +#include +#include +#include +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +struct linux_dirent { + long d_ino; + off_t d_off; + unsigned short d_reclen; + char d_name[]; +}; + +#define BUF_SIZE 1024 + +int +main(int argc, char *argv[]) +{ + int fd, nread; + char buf[BUF_SIZE]; + struct linux_dirent *d; + int bpos; + char d_type; + + fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY); + if (fd == \-1) + handle_error("open"); + + for ( ; ; ) { + nread = syscall(SYS_getdents, fd, buf, BUF_SIZE); + if (nread == \-1) + handle_error("getdents"); + + if (nread == 0) + break; + + printf("\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=%d \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\\n", nread); + printf("inode# file type d_reclen d_off d_name\\n"); + for (bpos = 0; bpos < nread;) { + d = (struct linux_dirent *) (buf + bpos); + printf("%8ld ", d\->d_ino); + d_type = *(buf + bpos + d\->d_reclen \- 1); + printf("%\-10s ", (d_type == DT_REG) ? "regular" : + (d_type == DT_DIR) ? "directory" : + (d_type == DT_FIFO) ? "FIFO" : + (d_type == DT_SOCK) ? "socket" : + (d_type == DT_LNK) ? "symlink" : + (d_type == DT_BLK) ? "block dev" : + (d_type == DT_CHR) ? "char dev" : "???"); + printf("%4d %10lld %s\\n", d\->d_reclen, + (long long) d\->d_off, d\->d_name); + bpos += d\->d_reclen; + } + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR readdir (2), +.BR readdir (3), +.BR inode (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getdents64.2 b/man2/getdents64.2 new file mode 100644 index 0000000..f3674ba --- /dev/null +++ b/man2/getdents64.2 @@ -0,0 +1 @@ +.so man2/getdents.2 diff --git a/man2/getdomainname.2 b/man2/getdomainname.2 new file mode 100644 index 0000000..45627ef --- /dev/null +++ b/man2/getdomainname.2 @@ -0,0 +1,146 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1997-08-25 by Nicolás Lichtmaier +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2008-11-27 by mtk +.\" +.TH GETDOMAINNAME 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getdomainname, setdomainname \- get/set NIS domain name +.SH SYNOPSIS +.B #include +.PP +.BI "int getdomainname(char *" name ", size_t " len ); +.br +.BI "int setdomainname(const char *" name ", size_t " len ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR getdomainname (), +.BR setdomainname (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.fi +.ad +.SH DESCRIPTION +These functions are used to access or to change the NIS domain name of the +host system. +.PP +.BR setdomainname () +sets the domain name to the value given in the character array +.IR name . +The +.I len +argument specifies the number of bytes in +.IR name . +(Thus, +.I name +does not require a terminating null byte.) +.PP +.BR getdomainname () +returns the null-terminated domain name in the character array +.IR name , +which has a length of +.I len +bytes. +If the null-terminated domain name requires more than \fIlen\fP bytes, +.BR getdomainname () +returns the first \fIlen\fP bytes (glibc) or gives an error (libc). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.BR setdomainname () +can fail with the following errors: +.TP +.B EFAULT +.I name +pointed outside of user address space. +.TP +.B EINVAL +.I len +was negative or too large. +.TP +.B EPERM +The caller did not have the +.B CAP_SYS_ADMIN +capability in the user namespace associated with its UTS namespace (see +.BR namespaces (7)). +.PP +.BR getdomainname () +can fail with the following errors: +.TP +.B EINVAL +For +.BR getdomainname () +under libc: +.I name +is NULL or +.I name +is longer than +.I len +bytes. +.SH CONFORMING TO +POSIX does not specify these calls. +.\" But they appear on most systems... +.SH NOTES +Since Linux 1.0, the limit on the length of a domain name, +including the terminating null byte, is 64 bytes. +In older kernels, it was 8 bytes. +.PP +On most Linux architectures (including x86), +there is no +.BR getdomainname () +system call; instead, glibc implements +.BR getdomainname () +as a library function that returns a copy of the +.I domainname +field returned from a call to +.BR uname (2). +.SH SEE ALSO +.BR gethostname (2), +.BR sethostname (2), +.BR uname (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getdtablesize.2 b/man2/getdtablesize.2 new file mode 100644 index 0000000..68c2fd8 --- /dev/null +++ b/man2/getdtablesize.2 @@ -0,0 +1,2 @@ +.so man3/getdtablesize.3 +.\" Created 2013-02-05; will eventually be removed diff --git a/man2/getegid.2 b/man2/getegid.2 new file mode 100644 index 0000000..d9b10e7 --- /dev/null +++ b/man2/getegid.2 @@ -0,0 +1 @@ +.so man2/getgid.2 diff --git a/man2/getegid32.2 b/man2/getegid32.2 new file mode 100644 index 0000000..d7da708 --- /dev/null +++ b/man2/getegid32.2 @@ -0,0 +1 @@ +.so man2/getegid.2 diff --git a/man2/geteuid.2 b/man2/geteuid.2 new file mode 100644 index 0000000..165cfe1 --- /dev/null +++ b/man2/geteuid.2 @@ -0,0 +1 @@ +.so man2/getuid.2 diff --git a/man2/geteuid32.2 b/man2/geteuid32.2 new file mode 100644 index 0000000..8e60b77 --- /dev/null +++ b/man2/geteuid32.2 @@ -0,0 +1 @@ +.so man2/geteuid.2 diff --git a/man2/getgid.2 b/man2/getgid.2 new file mode 100644 index 0000000..c31a20b --- /dev/null +++ b/man2/getgid.2 @@ -0,0 +1,75 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETGID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getgid, getegid \- get group identity +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B gid_t getgid(void); +.br +.B gid_t getegid(void); +.SH DESCRIPTION +.BR getgid () +returns the real group ID of the calling process. +.PP +.BR getegid () +returns the effective group ID of the calling process. +.SH ERRORS +These functions are always successful. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH NOTES +The original Linux +.BR getgid () +and +.BR getegid () +system calls supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR getgid32 () +and +.BR getegid32 (), +supporting 32-bit IDs. +The glibc +.BR getgid () +and +.BR getegid () +wrapper functions transparently deal with the variations across kernel versions. +.SH SEE ALSO +.BR getresgid (2), +.BR setgid (2), +.BR setregid (2), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getgid32.2 b/man2/getgid32.2 new file mode 100644 index 0000000..d9b10e7 --- /dev/null +++ b/man2/getgid32.2 @@ -0,0 +1 @@ +.so man2/getgid.2 diff --git a/man2/getgroups.2 b/man2/getgroups.2 new file mode 100644 index 0000000..9455a7f --- /dev/null +++ b/man2/getgroups.2 @@ -0,0 +1,228 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" and Copyright (C) 2008, 2010, 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" 2008-05-03, mtk, expanded and rewrote parts of DESCRIPTION and RETURN +.\" VALUE, made style of page more consistent with man-pages style. +.\" +.TH GETGROUPS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getgroups, setgroups \- get/set list of supplementary group IDs +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int getgroups(int " size ", gid_t " list []); + +.B #include +.PP +.BI "int setgroups(size_t " size ", const gid_t *" list ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR setgroups (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +.PP +.BR getgroups () +returns the supplementary group IDs of the calling process in +.IR list . +The argument +.I size +should be set to the maximum number of items that can be stored in the +buffer pointed to by +.IR list . +If the calling process is a member of more than +.I size +supplementary groups, then an error results. +It is unspecified whether the effective group ID of the calling process +is included in the returned list. +(Thus, an application should also call +.BR getegid (2) +and add or remove the resulting value.) +.PP +If +.I size +is zero, +.I list +is not modified, but the total number of supplementary group IDs for the +process is returned. +This allows the caller to determine the size of a dynamically allocated +.I list +to be used in a further call to +.BR getgroups (). +.PP +.BR setgroups () +sets the supplementary group IDs for the calling process. +Appropriate privileges are required (see the description of the +.BR EPERM +error, below). +The +.I size +argument specifies the number of supplementary group IDs +in the buffer pointed to by +.IR list . +.SH RETURN VALUE +On success, +.BR getgroups () +returns the number of supplementary group IDs. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +On success, +.BR setgroups () +returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I list +has an invalid address. +.PP +.BR getgroups () +can additionally fail with the following error: +.TP +.B EINVAL +.I size +is less than the number of supplementary group IDs, but is not zero. +.PP +.BR setgroups () +can additionally fail with the following errors: +.TP +.B EINVAL +.I size +is greater than +.B NGROUPS_MAX +(32 before Linux 2.6.4; 65536 since Linux 2.6.4). +.TP +.B ENOMEM +Out of memory. +.TP +.B EPERM +The calling process has insufficient privilege +(the caller does not have the +.BR CAP_SETGID +capability in the user namespace in which it resides). +.TP +.BR EPERM " (since Linux 3.19)" +The use of +.BR setgroups () +is denied in this user namespace. +See the description of +.IR /proc/[pid]/setgroups +in +.BR user_namespaces (7). +.SH CONFORMING TO +.BR getgroups (): +SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. +.PP +.BR setgroups (): +SVr4, 4.3BSD. +Since +.BR setgroups () +requires privilege, it is not covered by POSIX.1. +.SH NOTES +A process can have up to +.B NGROUPS_MAX +supplementary group IDs +in addition to the effective group ID. +The constant +.B NGROUPS_MAX +is defined in +.IR . +The set of supplementary group IDs +is inherited from the parent process, and preserved across an +.BR execve (2). +.PP +The maximum number of supplementary group IDs can be found at run time using +.BR sysconf (3): +.PP +.in +4n +.EX +long ngroups_max; +ngroups_max = sysconf(_SC_NGROUPS_MAX); +.EE +.in +.PP +The maximum return value of +.BR getgroups () +cannot be larger than one more than this value. +Since Linux 2.6.4, the maximum number of supplementary group IDs is also +exposed via the Linux-specific read-only file, +.IR /proc/sys/kernel/ngroups_max . +.PP +The original Linux +.BR getgroups () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR getgroups32 (), +supporting 32-bit IDs. +The glibc +.BR getgroups () +wrapper function transparently deals with the variation across kernel versions. +.\" +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including the one for +.BR setgroups ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH SEE ALSO +.BR getgid (2), +.BR setgid (2), +.BR getgrouplist (3), +.BR group_member (3), +.BR initgroups (3), +.BR capabilities (7), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getgroups32.2 b/man2/getgroups32.2 new file mode 100644 index 0000000..0ae4cc0 --- /dev/null +++ b/man2/getgroups32.2 @@ -0,0 +1 @@ +.so man2/getgroups.2 diff --git a/man2/gethostid.2 b/man2/gethostid.2 new file mode 100644 index 0000000..3210db0 --- /dev/null +++ b/man2/gethostid.2 @@ -0,0 +1 @@ +.so man3/gethostid.3 diff --git a/man2/gethostname.2 b/man2/gethostname.2 new file mode 100644 index 0000000..5febc8a --- /dev/null +++ b/man2/gethostname.2 @@ -0,0 +1,196 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1995-07-22 by Michael Chastain : +.\" 'gethostname' is real system call on Linux/Alpha. +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2000-06-04, 2001-12-15 by aeb +.\" Modified 2004-06-17 by mtk +.\" Modified 2008-11-27 by mtk +.\" +.TH GETHOSTNAME 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +gethostname, sethostname \- get/set hostname +.SH SYNOPSIS +.B #include +.PP +.BI "int gethostname(char *" name ", size_t " len ); +.br +.BI "int sethostname(const char *" name ", size_t " len ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.PD 0 +.BR gethostname (): +.RS 4 +Since glibc 2.12: +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.br +|| /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200112L +.RE +.br +.BR sethostname (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.fi +.PD +.ad +.SH DESCRIPTION +These system calls are used to access or to change the hostname of the +current processor. +.PP +.BR sethostname () +sets the hostname to the value given in the character array +.IR name . +The +.I len +argument specifies the number of bytes in +.IR name . +(Thus, +.I name +does not require a terminating null byte.) +.PP +.BR gethostname () +returns the null-terminated hostname in the character array +.IR name , +which has a length of +.I len +bytes. +If the null-terminated hostname is too large to fit, +then the name is truncated, and no error is returned (but see NOTES below). +POSIX.1 says that if such truncation occurs, +then it is unspecified whether the returned buffer +includes a terminating null byte. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I name +is an invalid address. +.TP +.B EINVAL +.I len +is negative +.\" Can't occur for gethostbyname() wrapper, since 'len' has an +.\" unsigned type; can occur for the underlying system call. +or, for +.BR sethostname (), +.I len +is larger than the maximum allowed size. +.TP +.B ENAMETOOLONG +.RB "(glibc " gethostname ()) +.I len +is smaller than the actual size. +(Before version 2.1, glibc uses +.BR EINVAL +for this case.) +.TP +.B EPERM +For +.BR sethostname (), +the caller did not have the +.B CAP_SYS_ADMIN +capability in the user namespace associated with its UTS namespace (see +.BR namespaces (7)). +.SH CONFORMING TO +SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). +POSIX.1-2001 and POSIX.1-2008 specify +.BR gethostname () +but not +.BR sethostname (). +.SH NOTES +SUSv2 guarantees that "Host names are limited to 255 bytes". +POSIX.1 guarantees that "Host names (not including +the terminating null byte) are limited to +.B HOST_NAME_MAX +bytes". +On Linux, +.B HOST_NAME_MAX +is defined with the value 64, which has been the limit since Linux 1.0 +(earlier kernels imposed a limit of 8 bytes). +.SS C library/kernel differences +The GNU C library does not employ the +.BR gethostname () +system call; instead, it implements +.BR gethostname () +as a library function that calls +.BR uname (2) +and copies up to +.I len +bytes from the returned +.I nodename +field into +.IR name . +Having performed the copy, the function then checks if the length of the +.I nodename +was greater than or equal to +.IR len , +and if it is, then the function returns \-1 with +.I errno +set to +.BR ENAMETOOLONG ; +in this case, a terminating null byte is not included in the returned +.IR name . +.PP +Versions of glibc before 2.2 +.\" At least glibc 2.0 and 2.1, older versions not checked +handle the case where the length of the +.I nodename +was greater than or equal to +.I len +differently: nothing is copied into +.I name +and the function returns \-1 with +.I errno +set to +.BR ENAMETOOLONG . +.SH SEE ALSO +.BR hostname (1), +.BR getdomainname (2), +.BR setdomainname (2), +.BR uname (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getitimer.2 b/man2/getitimer.2 new file mode 100644 index 0000000..d7aa9ad --- /dev/null +++ b/man2/getitimer.2 @@ -0,0 +1,274 @@ +.\" Copyright 7/93 by Darren Senn +.\" and Copyright (C) 2016, Michael Kerrisk +.\" Based on a similar page Copyright 1992 by Rick Faith +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" May be freely distributed and modified +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.\" 2005-04-06 mtk, Matthias Lang +.\" Noted MAX_SEC_IN_JIFFIES ceiling +.\" +.TH GETITIMER 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getitimer, setitimer \- get or set value of an interval timer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getitimer(int " which ", struct itimerval *" curr_value ); +.BI "int setitimer(int " which ", const struct itimerval *" new_value , +.BI " struct itimerval *" old_value ); +.fi +.SH DESCRIPTION +These system calls provide access to interval timers, that is, +timers that initially expire at some point in the future, +and (optionally) at regular intervals after that. +When a timer expires, a signal is generated for the calling process, +and the timer is reset to the specified interval +(if the interval is nonzero). +.PP +Three types of timers\(emspecified via the +.IR which +argument\(emare provided, +each of which counts against a different clock and +generates a different signal on timer expiration: +.TP 1.5i +.B ITIMER_REAL +This timer counts down in real (i.e., wall clock) time. +At each expiration, a +.B SIGALRM +signal is generated. +.TP +.B ITIMER_VIRTUAL +This timer counts down against the user-mode CPU time consumed by the process. +(The measurement includes CPU time consumed by all threads in the process.) +At each expiration, a +.B SIGVTALRM +signal is generated. +.TP +.B ITIMER_PROF +This timer counts down against the total (i.e., both user and system) +CPU time consumed by the process. +(The measurement includes CPU time consumed by all threads in the process.) +At each expiration, a +.B SIGPROF +signal is generated. +.IP +In conjunction with +.BR ITIMER_VIRTUAL , +this timer can be used to profile user and system CPU time +consumed by the process. +.PP +A process has only one of each of the three types of timers. +.PP +Timer values are defined by the following structures: +.PP +.in +4n +.EX +struct itimerval { + struct timeval it_interval; /* Interval for periodic timer */ + struct timeval it_value; /* Time until next expiration */ +}; + +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.\" +.SS getitimer() +The function +.BR getitimer () +places the current value of the timer specified by +.IR which +in the buffer pointed to by +.IR curr_value . +.PP +The +.IR it_value +substructure is populated with the amount of time remaining until +the next expiration of the specified timer. +This value changes as the timer counts down, and will be reset to +.IR it_interval +when the timer expires. +If both fields of +.IR it_value +are zero, then this timer is currently disarmed (inactive). +.PP +The +.IR it_interval +substructure is populated with the timer interval. +If both fields of +.IR it_interval +are zero, then this is a single-shot timer (i.e., it expires just once). +.SS setitimer() +The function +.BR setitimer () +arms or disarms the timer specified by +.IR which , +by setting the timer to the value specified by +.IR new_value . +If +.I old_value +is non-NULL, +the buffer it points to is used to return the previous value of the timer +(i.e., the same information that is returned by +.BR getitimer ()). +.PP +If either field in +.IR new_value.it_value +is nonzero, +then the timer is armed to initially expire at the specified time. +If both fields in +.IR new_value.it_value +are zero, then the timer is disarmed. +.PP +The +.IR new_value.it_interval +field specifies the new interval for the timer; +if both of its subfields are zero, the timer is single-shot. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.IR new_value , +.IR old_value , +or +.I curr_value +is not valid a pointer. +.TP +.B EINVAL +.I which +is not one of +.BR ITIMER_REAL , +.BR ITIMER_VIRTUAL , +or +.BR ITIMER_PROF ; +or (since Linux 2.6.22) one of the +.I tv_usec +fields in the structure pointed to by +.I new_value +contains a value outside the range 0 to 999999. +.SH CONFORMING TO +POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD). +POSIX.1-2008 marks +.BR getitimer () +and +.BR setitimer () +obsolete, recommending the use of the POSIX timers API +.RB ( timer_gettime (2), +.BR timer_settime (2), +etc.) instead. +.SH NOTES +Timers will never expire before the requested time, +but may expire some (short) time afterward, which depends +on the system timer resolution and on the system load; see +.BR time (7). +(But see BUGS below.) +If the timer expires while the process is active (always true for +.BR ITIMER_VIRTUAL ), +the signal will be delivered immediately when generated. +.PP +A child created via +.BR fork (2) +does not inherit its parent's interval timers. +Interval timers are preserved across an +.BR execve (2). +.PP +POSIX.1 leaves the +interaction between +.BR setitimer () +and the three interfaces +.BR alarm (2), +.BR sleep (3), +and +.BR usleep (3) +unspecified. +.PP +The standards are silent on the meaning of the call: +.PP + setitimer(which, NULL, &old_value); +.PP +Many systems (Solaris, the BSDs, and perhaps others) +treat this as equivalent to: +.PP + getitimer(which, &old_value); +.PP +In Linux, this is treated as being equivalent to a call in which the +.I new_value +fields are zero; that is, the timer is disabled. +.IR "Don't use this Linux misfeature" : +it is nonportable and unnecessary. +.SH BUGS +The generation and delivery of a signal are distinct, and +only one instance of each of the signals listed above may be pending +for a process. +Under very heavy loading, an +.B ITIMER_REAL +timer may expire before the signal from a previous expiration +has been delivered. +The second signal in such an event will be lost. +.PP +On Linux kernels before 2.6.16, timer values are represented in jiffies. +If a request is made set a timer with a value whose jiffies +representation exceeds +.B MAX_SEC_IN_JIFFIES +(defined in +.IR include/linux/jiffies.h ), +then the timer is silently truncated to this ceiling value. +On Linux/i386 (where, since Linux 2.6.13, +the default jiffy is 0.004 seconds), +this means that the ceiling value for a timer is +approximately 99.42 days. +Since Linux 2.6.16, +the kernel uses a different internal representation for times, +and this ceiling is removed. +.PP +On certain systems (including i386), +Linux kernels before version 2.6.12 have a bug which will produce +premature timer expirations of up to one jiffy under some circumstances. +This bug is fixed in kernel 2.6.12. +.\" 4 Jul 2005: It looks like this bug may remain in 2.4.x. +.\" http://lkml.org/lkml/2005/7/1/165 +.PP +POSIX.1-2001 says that +.BR setitimer () +should fail if a +.I tv_usec +value is specified that is outside of the range 0 to 999999. +However, in kernels up to and including 2.6.21, +Linux does not give an error, but instead silently +adjusts the corresponding seconds value for the timer. +From kernel 2.6.22 onward, +this nonconformance has been repaired: +an improper +.I tv_usec +value results in an +.B EINVAL +error. +.\" Bugzilla report 25 Apr 2006: +.\" http://bugzilla.kernel.org/show_bug.cgi?id=6443 +.\" "setitimer() should reject noncanonical arguments" +.SH SEE ALSO +.BR gettimeofday (2), +.BR sigaction (2), +.BR signal (2), +.BR timer_create (2), +.BR timerfd_create (2), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getmsg.2 b/man2/getmsg.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/getmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/getpagesize.2 b/man2/getpagesize.2 new file mode 100644 index 0000000..584b77a --- /dev/null +++ b/man2/getpagesize.2 @@ -0,0 +1,123 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETPAGESIZE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getpagesize \- get memory page size +.SH SYNOPSIS +.B #include +.PP +.B int getpagesize(void); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getpagesize (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.19: +.nf +_DEFAULT_SOURCE || ! (_POSIX_C_SOURCE\ >=\ 200112L) +.TP 4 +.fi +From glibc 2.12 to 2.19: +.nf +_BSD_SOURCE || ! (_POSIX_C_SOURCE\ >=\ 200112L) +.TP 4 +.fi +Before glibc 2.12: +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH DESCRIPTION +The function +.BR getpagesize () +returns the number of bytes in a memory page, +where "page" is a fixed-length block, +the unit for memory allocation and file mapping performed by +.BR mmap (2). +.\" .SH HISTORY +.\" This call first appeared in 4.2BSD. +.SH CONFORMING TO +SVr4, 4.4BSD, SUSv2. +In SUSv2 the +.BR getpagesize () +call is labeled LEGACY, and in POSIX.1-2001 +it has been dropped; +HP-UX does not have this call. +.SH NOTES +Portable applications should employ +.I sysconf(_SC_PAGESIZE) +instead of +.BR getpagesize (): +.PP +.in +4n +.EX +#include +long sz = sysconf(_SC_PAGESIZE); +.EE +.in +.PP +(Most systems allow the synonym +.B _SC_PAGE_SIZE +for +.BR _SC_PAGESIZE .) +.PP +Whether +.BR getpagesize () +is present as a Linux system call depends on the architecture. +If it is, it returns the kernel symbol +.BR PAGE_SIZE , +whose value depends on the architecture and machine model. +Generally, one uses binaries that are dependent on the architecture but not +on the machine model, in order to have a single binary +distribution per architecture. +This means that a user program +should not find +.B PAGE_SIZE +at compile time from a header file, +but use an actual system call, at least for those architectures +(like sun4) where this dependency exists. +Here glibc 2.0 fails because its +.BR getpagesize () +returns a statically derived value, and does not use a system call. +Things are OK in glibc 2.1. +.SH SEE ALSO +.BR mmap (2), +.BR sysconf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getpeername.2 b/man2/getpeername.2 new file mode 100644 index 0000000..7f1c71c --- /dev/null +++ b/man2/getpeername.2 @@ -0,0 +1,152 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)getpeername.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 16:37:50 1993 by Rik Faith +.\" Modified Thu Jul 30 14:37:50 1993 by Martin Schulze +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer +.\" Modified 17 Jul 2002, Michael Kerrisk +.\" Added 'socket' to NAME, so that "man -k socket" will show this page. +.\" +.TH GETPEERNAME 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getpeername \- get name of connected peer socket +.SH SYNOPSIS +.B #include +.PP +.BI "int getpeername(int " sockfd ", struct sockaddr *" addr \ +", socklen_t *" addrlen ); +.SH DESCRIPTION +.BR getpeername () +returns the address of the peer connected to the socket +.IR sockfd , +in the buffer pointed to by +.IR addr . +The +.I addrlen +argument should be initialized to indicate the amount of space pointed to +by +.IR addr . +On return it contains the actual size of the name returned (in bytes). +The name is truncated if the buffer provided is too small. +.PP +The returned address is truncated if the buffer provided is too small; +in this case, +.I addrlen +will return a value greater than was supplied to the call. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +The argument +.I sockfd +is not a valid file descriptor. +.TP +.B EFAULT +The +.I addr +argument points to memory not in a valid part of the +process address space. +.TP +.B EINVAL +.I addrlen +is invalid (e.g., is negative). +.TP +.B ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.TP +.B ENOTCONN +The socket is not connected. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD +.RB ( getpeername () +first appeared in 4.2BSD). +.SH NOTES +For background on the +.I socklen_t +type, see +.BR accept (2). +.PP +For stream sockets, once a +.BR connect (2) +has been performed, either socket can call +.BR getpeername () +to obtain the address of the peer socket. +On the other hand, datagram sockets are connectionless. +Calling +.BR connect (2) +on a datagram socket merely sets the peer address for outgoing +datagrams sent with +.BR write (2) +or +.BR recv (2). +The caller of +.BR connect (2) +can use +.BR getpeername () +to obtain the peer address that it earlier set for the socket. +However, the peer socket is unaware of this information, and calling +.BR getpeername () +on the peer socket will return no useful information (unless a +.BR connect (2) +call was also executed on the peer). +Note also that the receiver of a datagram can obtain +the address of the sender when using +.BR recvfrom (2). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR getsockname (2), +.BR ip (7), +.BR socket (7), +.BR unix (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getpgid.2 b/man2/getpgid.2 new file mode 100644 index 0000000..d6b107a --- /dev/null +++ b/man2/getpgid.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man2/getpgrp.2 b/man2/getpgrp.2 new file mode 100644 index 0000000..d6b107a --- /dev/null +++ b/man2/getpgrp.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man2/getpid.2 b/man2/getpid.2 new file mode 100644 index 0000000..11b3293 --- /dev/null +++ b/man2/getpid.2 @@ -0,0 +1,159 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETPID 2 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +getpid, getppid \- get process identification +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B pid_t getpid(void); +.br +.B pid_t getppid(void); +.SH DESCRIPTION +.BR getpid () +returns the process ID (PID) of the calling process. +(This is often used by +routines that generate unique temporary filenames.) +.PP +.BR getppid () +returns the process ID of the parent of the calling process. +This will be either the ID of the process that created this process using +.BR fork (), +or, if that process has already terminated, +the ID of the process to which this process has been reparented (either +.BR init (1) +or a "subreaper" process defined via the +.BR prctl (2) +.BR PR_SET_CHILD_SUBREAPER +operation). +.SH ERRORS +These functions are always successful. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD, SVr4. +.SH NOTES +If the caller's parent is in a different PID namespace (see +.BR pid_namespaces (7)), +.BR getppid () +returns 0. +.PP +From a kernel perspective, +the PID (which is shared by all of the threads in a multithreaded process) +is sometimes also known as the thread group ID (TGID). +This contrasts with the kernel thread ID (TID), +which is unique for each thread. +For further details, see +.BR gettid (2) +and the discussion of the +.BR CLONE_THREAD +flag in +.BR clone (2). +.\" +.SS C library/kernel differences +From glibc version 2.3.4 up to and including version 2.24, +the glibc wrapper function for +.BR getpid () +cached PIDs, +with the goal of avoiding additional system calls when a process calls +.BR getpid () +repeatedly. +Normally this caching was invisible, +but its correct operation relied on support in the wrapper functions for +.BR fork (2), +.BR vfork (2), +and +.BR clone (2): +if an application bypassed the glibc wrappers for these system calls by using +.BR syscall (2), +then a call to +.BR getpid () +in the child would return the wrong value +(to be precise: it would return the PID of the parent process). +.\" The following program demonstrates this "feature": +.\" +.\" #define _GNU_SOURCE +.\" #include +.\" #include +.\" #include +.\" #include +.\" #include +.\" +.\" int +.\" main(int argc, char *argv[]) +.\" { +.\" /* The following statement fills the getpid() cache */ +.\" +.\" printf("parent PID = %ld\n", (long) getpid()); +.\" +.\" if (syscall(SYS_fork) == 0) { +.\" if (getpid() != syscall(SYS_getpid)) +.\" printf("child getpid() mismatch: getpid()=%ld; " +.\" "syscall(SYS_getpid)=%ld\n", +.\" (long) getpid(), (long) syscall(SYS_getpid)); +.\" exit(EXIT_SUCCESS); +.\" } +.\" wait(NULL); +.\"} +In addition, there were cases where +.BR getpid () +could return the wrong value even when invoking +.BR clone (2) +via the glibc wrapper function. +(For a discussion of one such case, see BUGS in +.BR clone (2).) +Furthermore, the complexity of the caching code had been +the source of a few bugs within glibc over the years. +.PP +Because of the aforementioned problems, +since glibc version 2.25, the PID cache is removed: +.\" commit c579f48edba88380635ab98cb612030e3ed8691e +.\" https://sourceware.org/glibc/wiki/Release/2.25#pid_cache_removal +calls to +.BR getpid () +always invoke the actual system call, rather than returning a cached value. +.\" FIXME . +.\" Review progress of https://bugzilla.redhat.com/show_bug.cgi?id=1469757 +.SH SEE ALSO +.BR clone (2), +.BR fork (2), +.BR gettid (2), +.BR kill (2), +.BR exec (3), +.BR mkstemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3), +.BR credentials (7), +.BR pid_namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getpmsg.2 b/man2/getpmsg.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/getpmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/getppid.2 b/man2/getppid.2 new file mode 100644 index 0000000..fca885e --- /dev/null +++ b/man2/getppid.2 @@ -0,0 +1 @@ +.so man2/getpid.2 diff --git a/man2/getpriority.2 b/man2/getpriority.2 new file mode 100644 index 0000000..fb76172 --- /dev/null +++ b/man2/getpriority.2 @@ -0,0 +1,261 @@ +.\" Copyright (c) 1980, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)getpriority.2 6.9 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-07-01 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 2001-10-21 by Michael Kerrisk +.\" Corrected statement under EPERM to clarify privileges required +.\" Modified 2002-06-21 by Michael Kerrisk +.\" Clarified meaning of 0 value for 'who' argument +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH GETPRIORITY 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getpriority, setpriority \- get/set program scheduling priority +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int getpriority(int " which ", id_t " who ); +.br +.BI "int setpriority(int " which ", id_t " who ", int " prio ); +.SH DESCRIPTION +The scheduling priority of the process, process group, or user, as +indicated by +.I which +and +.I who +is obtained with the +.BR getpriority () +call and set with the +.BR setpriority () +call. +The process attribute dealt with by these system calls is +the same attribute (also known as the "nice" value) that is dealt with by +.BR nice (2). +.PP +The value +.I which +is one of +.BR PRIO_PROCESS , +.BR PRIO_PGRP , +or +.BR PRIO_USER , +and +.I who +is interpreted relative to +.I which +(a process identifier for +.BR PRIO_PROCESS , +process group +identifier for +.BR PRIO_PGRP , +and a user ID for +.BR PRIO_USER ). +A zero value for +.I who +denotes (respectively) the calling process, the process group of the +calling process, or the real user ID of the calling process. +.PP +The +.I prio +argument is a value in the range \-20 to 19 (but see NOTES below). +with \-20 being the highest priority and 19 being the lowest priority. +Attempts to set a priority outside this range +are silently clamped to the range. +The default priority is 0; +lower values give a process a higher scheduling priority. +.PP +The +.BR getpriority () +call returns the highest priority (lowest numerical value) +enjoyed by any of the specified processes. +The +.BR setpriority () +call sets the priorities of all of the specified processes +to the specified value. +.PP +Traditionally, only a privileged process could lower the nice value +(i.e., set a higher priority). +However, since Linux 2.6.12, an unprivileged process can decrease +the nice value of a target process that has a suitable +.BR RLIMIT_NICE +soft limit; see +.BR getrlimit (2) +for details. +.SH RETURN VALUE +On success, +.BR getpriority () +returns the calling thread's nice value, which may be a negative number. +On error, it returns \-1 and sets +.I errno +to indicate the cause of the error. +Since a successful call to +.BR getpriority () +can legitimately return the value \-1, it is necessary +to clear the external variable +.I errno +prior to the +call, then check it afterward to determine +if \-1 is an error or a legitimate value. +.PP +.BR setpriority () +returns 0 on success. +On error, it returns \-1 and sets +.I errno +to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +.I which +was not one of +.BR PRIO_PROCESS , +.BR PRIO_PGRP , +or +.BR PRIO_USER . +.TP +.B ESRCH +No process was located using the +.I which +and +.I who +values specified. +.PP +In addition to the errors indicated above, +.BR setpriority () +may fail if: +.TP +.B EACCES +The caller attempted to set a lower nice value +(i.e., a higher process priority), but did not +have the required privilege (on Linux: did not have the +.B CAP_SYS_NICE +capability). +.TP +.B EPERM +A process was located, but its effective user ID did not match +either the effective or the real user ID of the caller, +and was not privileged (on Linux: did not have the +.B CAP_SYS_NICE +capability). +But see NOTES below. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, +SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). +.SH NOTES +For further details on the nice value, see +.BR sched (7). +.PP +.IR Note : +the addition of the "autogroup" feature in Linux 2.6.38 means that +the nice value no longer has its traditional effect in many circumstances. +For details, see +.BR sched (7). +.PP +A child created by +.BR fork (2) +inherits its parent's nice value. +The nice value is preserved across +.BR execve (2). +.PP +The details on the condition for +.B EPERM +depend on the system. +The above description is what POSIX.1-2001 says, and seems to be followed on +all System\ V-like systems. +Linux kernels before 2.6.12 required the real or +effective user ID of the caller to match +the real user of the process \fIwho\fP (instead of its effective user ID). +Linux 2.6.12 and later require +the effective user ID of the caller to match +the real or effective user ID of the process \fIwho\fP. +All BSD-like systems (SunOS 4.1.3, Ultrix 4.2, +4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same +manner as Linux 2.6.12 and later. +.PP +Including +.I +is not required these days, but increases portability. +(Indeed, +.I +defines the +.I rusage +structure with fields of type +.I struct timeval +defined in +.IR .) +.\" +.SS C library/kernel differences +Within the kernel, nice values are actually represented +using the range 40..1 +(since negative numbers are error codes) and these are the values +employed by the +.BR setpriority () +and +.BR getpriority () +system calls. +The glibc wrapper functions for these system calls handle the +translations between the user-land and kernel representations +of the nice value according to the formula +.IR "unice\ =\ 20\ \-\ knice" . +(Thus, the kernel's 40..1 range corresponds to the +range \-20..19 as seen by user space.) +.SH BUGS +According to POSIX, the nice value is a per-process setting. +However, under the current Linux/NPTL implementation of POSIX threads, +the nice value is a per-thread attribute: +different threads in the same process can have different nice values. +Portable applications should avoid relying on the Linux behavior, +which may be made standards conformant in the future. +.SH SEE ALSO +.BR nice (1), +.BR renice (1), +.BR fork (2), +.BR capabilities (7), +.BR sched (7) +.PP +.I Documentation/scheduler/sched-nice-design.txt +in the Linux kernel source tree (since Linux 2.6.23) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getrandom.2 b/man2/getrandom.2 new file mode 100644 index 0000000..aba4d77 --- /dev/null +++ b/man2/getrandom.2 @@ -0,0 +1,319 @@ +.\" Copyright (C) 2014, Theodore Ts'o +.\" Copyright (C) 2014,2015 Heinrich Schuchardt +.\" Copyright (C) 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETRANDOM 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getrandom \- obtain a series of random bytes +.SH SYNOPSIS +.B #include +.PP +.BI "ssize_t getrandom(void *"buf ", size_t " buflen ", unsigned int " flags ); +.SH DESCRIPTION +The +.BR getrandom () +system call fills the buffer pointed to by +.I buf +with up to +.I buflen +random bytes. +These bytes can be used to seed user-space random number generators +or for cryptographic purposes. +.PP +By default, +.BR getrandom () +draws entropy from the +.I urandom +source (i.e., the same source as the +.IR /dev/urandom +device). +This behavior can be changed via the +.I flags +argument. +.PP +If the +.I urandom +source has been initialized, +reads of up to 256 bytes will always return as many bytes as +requested and will not be interrupted by signals. +No such guarantees apply for larger buffer sizes. +For example, if the call is interrupted by a signal handler, +it may return a partially filled buffer, or fail with the error +.BR EINTR . +.PP +If the +.I urandom +source has not yet been initialized, then +.BR getrandom () +will block, unless +.B GRND_NONBLOCK +is specified in +.IR flags . +.PP +The +.I flags +argument is a bit mask that can contain zero or more of the following values +ORed together: +.TP +.B GRND_RANDOM +If this bit is set, then random bytes are drawn from the +.I random +source +(i.e., the same source as the +.IR /dev/random +device) +instead of the +.I urandom +source. +The +.I random +source is limited based on the entropy that can be obtained from environmental +noise. +If the number of available bytes in the +.I random +source is less than requested in +.IR buflen , +the call returns just the available random bytes. +If no random bytes are available, the behavior depends on the presence of +.B GRND_NONBLOCK +in the +.I flags +argument. +.TP +.B GRND_NONBLOCK +By default, when reading from the +.IR random +source, +.BR getrandom () +blocks if no random bytes are available, +and when reading from the +.IR urandom +source, it blocks if the entropy pool has not yet been initialized. +If the +.B GRND_NONBLOCK +flag is set, then +.BR getrandom () +does not block in these cases, but instead immediately returns \-1 with +.I errno +set to +.BR EAGAIN . +.SH RETURN VALUE +On success, +.BR getrandom () +returns the number of bytes that were copied to the buffer +.IR buf . +This may be less than the number of bytes requested via +.I buflen +if either +.BR GRND_RANDOM +was specified in +.IR flags +and insufficient entropy was present in the +.IR random +source or the system call was interrupted by a signal. +.PP +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +The requested entropy was not available, and +.BR getrandom () +would have blocked if the +.B GRND_NONBLOCK +flag was not set. +.TP +.B EFAULT +The address referred to by +.I buf +is outside the accessible address space. +.TP +.B EINTR +The call was interrupted by a signal +handler; see the description of how interrupted +.BR read (2) +calls on "slow" devices are handled with and without the +.B SA_RESTART +flag in the +.BR signal (7) +man page. +.TP +.B EINVAL +An invalid flag was specified in +.IR flags . +.TP +.B ENOSYS +The glibc wrapper function for +.BR getrandom () +determined that the underlying kernel does not implement this system call. +.SH VERSIONS +.BR getrandom () +was introduced in version 3.17 of the Linux kernel. +Support was added to glibc in version 2.25. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +For an overview and comparison of the various interfaces that +can be used to obtain randomness, see +.BR random (7). +.PP +Unlike +.IR /dev/random +and +.IR /dev/urandom , +.BR getrandom () +does not involve the use of pathnames or file descriptors. +Thus, +.BR getrandom () +can be useful in cases where +.BR chroot (2) +makes +.I /dev +pathnames invisible, +and where an application (e.g., a daemon during start-up) +closes a file descriptor for one of these files +that was opened by a library. +.\" +.SS Maximum number of bytes returned +As of Linux 3.19 the following limits apply: +.IP * 3 +When reading from the +.IR urandom +source, a maximum of 33554431 bytes is returned by a single call to +.BR getrandom () +on systems where +.I int +has a size of 32 bits. +.IP * +When reading from the +.IR random +source, a maximum of 512 bytes is returned. +.SS Interruption by a signal handler +When reading from the +.I urandom +source +.RB ( GRND_RANDOM +is not set), +.BR getrandom () +will block until the entropy pool has been initialized +(unless the +.BR GRND_NONBLOCK +flag was specified). +If a request is made to read a large number of bytes (more than 256), +.BR getrandom () +will block until those bytes have been generated and transferred +from kernel memory to +.IR buf . +When reading from the +.I random +source +.RB ( GRND_RANDOM +is set), +.BR getrandom () +will block until some random bytes become available +(unless the +.BR GRND_NONBLOCK +flag was specified). +.PP +The behavior when a call to +.BR getrandom () +that is blocked while reading from the +.I urandom +source is interrupted by a signal handler +depends on the initialization state of the entropy buffer +and on the request size, +.IR buflen . +If the entropy is not yet initialized, then the call fails with the +.B EINTR +error. +If the entropy pool has been initialized +and the request size is large +.RI ( buflen "\ >\ 256)," +the call either succeeds, returning a partially filled buffer, +or fails with the error +.BR EINTR. +If the entropy pool has been initialized and the request size is small +.RI ( buflen "\ <=\ 256)," +then +.BR getrandom () +will not fail with +.BR EINTR . +Instead, it will return all of the bytes that have been requested. +.PP +When reading from the +.IR random +source, blocking requests of any size can be interrupted by a signal handler +(the call fails with the error +.BR EINTR ). +.PP +Using +.BR getrandom () +to read small buffers (<=\ 256 bytes) from the +.I urandom +source is the preferred mode of usage. +.PP +The special treatment of small values of +.I buflen +was designed for compatibility with +OpenBSD's +.BR getentropy (3), +which is nowadays supported by glibc. +.PP +The user of +.BR getrandom () +.I must +always check the return value, +to determine whether either an error occurred +or fewer bytes than requested were returned. +In the case where +.B GRND_RANDOM +is not specified and +.I buflen +is less than or equal to 256, +a return of fewer bytes than requested should never happen, +but the careful programmer will check for this anyway! +.SH BUGS +As of Linux 3.19, the following bug exists: +.\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16 +.IP * 3 +Depending on CPU load, +.BR getrandom () +does not react to interrupts before reading all bytes requested. +.SH SEE ALSO +.BR getentropy (3), +.BR random (4), +.BR urandom (4), +.BR random (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getresgid.2 b/man2/getresgid.2 new file mode 100644 index 0000000..ac4fb7c --- /dev/null +++ b/man2/getresgid.2 @@ -0,0 +1 @@ +.so man2/getresuid.2 diff --git a/man2/getresgid32.2 b/man2/getresgid32.2 new file mode 100644 index 0000000..2b3240f --- /dev/null +++ b/man2/getresgid32.2 @@ -0,0 +1 @@ +.so man2/getresgid.2 diff --git a/man2/getresuid.2 b/man2/getresuid.2 new file mode 100644 index 0000000..dd9e8b1 --- /dev/null +++ b/man2/getresuid.2 @@ -0,0 +1,100 @@ +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (c) 2007, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified, 2003-05-26, Michael Kerrisk, +.\" +.TH GETRESUID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getresuid, getresgid \- get real, effective and saved user/group IDs +.SH SYNOPSIS +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.PP +.BI "int getresuid(uid_t *" ruid ", uid_t *" euid ", uid_t *" suid ); +.br +.BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid ); +.SH DESCRIPTION +.BR getresuid () +returns the real UID, the effective UID, and the saved set-user-ID +of the calling process, in the arguments +.IR ruid , +.IR euid , +and +.IR suid , +respectively. +.BR getresgid () +performs the analogous task for the process's group IDs. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +One of the arguments specified an address outside the calling program's +address space. +.SH VERSIONS +These system calls appeared on Linux starting with kernel 2.1.44. +.PP +The prototypes are given by glibc since version 2.3.2, +provided +.B _GNU_SOURCE +is defined. +.SH CONFORMING TO +These calls are nonstandard; +they also appear on HP-UX and some of the BSDs. +.SH NOTES +The original Linux +.BR getresuid () +and +.BR getresgid () +system calls supported only 16-bit user and group IDs. +Subsequently, Linux 2.4 added +.BR getresuid32 () +and +.BR getresgid32 (), +supporting 32-bit IDs. +The glibc +.BR getresuid () +and +.BR getresgid () +wrapper functions transparently deal with the variations across kernel versions. +.SH SEE ALSO +.BR getuid (2), +.BR setresuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getresuid32.2 b/man2/getresuid32.2 new file mode 100644 index 0000000..ac4fb7c --- /dev/null +++ b/man2/getresuid32.2 @@ -0,0 +1 @@ +.so man2/getresuid.2 diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 new file mode 100644 index 0000000..30490c2 --- /dev/null +++ b/man2/getrlimit.2 @@ -0,0 +1,859 @@ +.\" Copyright (c) 1992 Drew Eckhardt, March 28, 1992 +.\" and Copyright (c) 2002, 2004, 2005, 2008, 2010 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-01-13 by Arnt Gulbrandsen +.\" Modified 1996-01-22 by aeb, following a remark by +.\" Tigran Aivazian +.\" Modified 1996-04-14 by aeb, following a remark by +.\" Robert Bihlmeyer +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2001-05-04 by aeb, following a remark by +.\" Håvard Lygre +.\" Modified 2001-04-17 by Michael Kerrisk +.\" Modified 2002-06-13 by Michael Kerrisk +.\" Added note on nonstandard behavior when SIGCHLD is ignored. +.\" Modified 2002-07-09 by Michael Kerrisk +.\" Enhanced descriptions of 'resource' values +.\" Modified 2003-11-28 by aeb, added RLIMIT_CORE +.\" Modified 2004-03-26 by aeb, added RLIMIT_AS +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added notes on CAP_SYS_RESOURCE +.\" +.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formally included +.\" coverage of getrusage(2), has been split, so that the latter +.\" is now covered in its own getrusage.2. +.\" +.\" Modified 2004-11-16, mtk: A few other minor changes +.\" Modified 2004-11-23, mtk +.\" Added notes on RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS +.\" to "CONFORMING TO" +.\" Modified 2004-11-25, mtk +.\" Rewrote discussion on RLIMIT_MEMLOCK to incorporate kernel +.\" 2.6.9 changes. +.\" Added note on RLIMIT_CPU error in older kernels +.\" 2004-11-03, mtk, Added RLIMIT_SIGPENDING +.\" 2005-07-13, mtk, documented RLIMIT_MSGQUEUE limit. +.\" 2005-07-28, mtk, Added descriptions of RLIMIT_NICE and RLIMIT_RTPRIO +.\" 2008-05-07, mtk / Peter Zijlstra, Added description of RLIMIT_RTTIME +.\" 2010-11-06, mtk: Added documentation of prlimit() +.\" +.TH GETRLIMIT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getrlimit, setrlimit, prlimit \- get/set resource limits +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int getrlimit(int " resource ", struct rlimit *" rlim ); +.br +.BI "int setrlimit(int " resource ", const struct rlimit *" rlim ); +.PP +.BI "int prlimit(pid_t " pid ", int " resource \ +", const struct rlimit *" new_limit , +.br +.BI " struct rlimit *" old_limit ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR prlimit (): +_GNU_SOURCE +.SH DESCRIPTION +The +.BR getrlimit () +and +.BR setrlimit () +system calls get and set resource limits respectively. +Each resource has an associated soft and hard limit, as defined by the +.I rlimit +structure: +.PP +.in +4n +.EX +struct rlimit { + rlim_t rlim_cur; /* Soft limit */ + rlim_t rlim_max; /* Hard limit (ceiling for rlim_cur) */ +}; +.EE +.in +.PP +The soft limit is the value that the kernel enforces for the +corresponding resource. +The hard limit acts as a ceiling for the soft limit: +an unprivileged process may set only its soft limit to a value in the +range from 0 up to the hard limit, and (irreversibly) lower its hard limit. +A privileged process (under Linux: one with the +.B CAP_SYS_RESOURCE +capability) may make arbitrary changes to either limit value. +.PP +The value +.B RLIM_INFINITY +denotes no limit on a resource (both in the structure returned by +.BR getrlimit () +and in the structure passed to +.BR setrlimit ()). +.PP +The +.I resource +argument must be one of: +.TP +.B RLIMIT_AS +This is the maximum size of the process's virtual memory +(address space). +The limit is specified in bytes, and is rounded down to the system page size. +.\" since 2.0.27 / 2.1.12 +This limit affects calls to +.BR brk (2), +.BR mmap (2), +and +.BR mremap (2), +which fail with the error +.B ENOMEM +upon exceeding this limit. +In addition, automatic stack expansion fails +(and generates a +.B SIGSEGV +that kills the process if no alternate stack +has been made available via +.BR sigaltstack (2)). +Since the value is a \fIlong\fP, on machines with a 32-bit \fIlong\fP +either this limit is at most 2\ GiB, or this resource is unlimited. +.TP +.B RLIMIT_CORE +This is the maximum size of a +.I core +file (see +.BR core (5)) +in bytes that the process may dump. +When 0 no core dump files are created. +When nonzero, larger dumps are truncated to this size. +.TP +.B RLIMIT_CPU +This is a limit, in seconds, +on the amount of CPU time that the process can consume. +When the process reaches the soft limit, it is sent a +.B SIGXCPU +signal. +The default action for this signal is to terminate the process. +However, the signal can be caught, and the handler can return control to +the main program. +If the process continues to consume CPU time, it will be sent +.B SIGXCPU +once per second until the hard limit is reached, at which time +it is sent +.BR SIGKILL . +(This latter point describes Linux behavior. +Implementations vary in how they treat processes which continue to +consume CPU time after reaching the soft limit. +Portable applications that need to catch this signal should +perform an orderly termination upon first receipt of +.BR SIGXCPU .) +.TP +.B RLIMIT_DATA +This is the maximum size +of the process's data segment (initialized data, +uninitialized data, and heap). +The limit is specified in bytes, and is rounded down to the system page size. +This limit affects calls to +.BR brk (2), +.BR sbrk (2), +and (since Linux 4.7) +.BR mmap (2), +.\" commits 84638335900f1995495838fe1bd4870c43ec1f67 +.\" ("mm: rework virtual memory accounting"), +.\" f4fcd55841fc9e46daac553b39361572453c2b88 +.\" (mm: enable RLIMIT_DATA by default with workaround for valgrind). +which fail with the error +.B ENOMEM +upon encountering the soft limit of this resource. +.TP +.B RLIMIT_FSIZE +This is the maximum size in bytes of files that the process may create. +Attempts to extend a file beyond this limit result in delivery of a +.B SIGXFSZ +signal. +By default, this signal terminates a process, but a process can +catch this signal instead, in which case the relevant system call (e.g., +.BR write (2), +.BR truncate (2)) +fails with the error +.BR EFBIG . +.TP +.BR RLIMIT_LOCKS " (early Linux 2.4 only)" +.\" to be precise: Linux 2.4.0-test9; no longer in 2.4.25 / 2.5.65 +This is a limit on the combined number of +.BR flock (2) +locks and +.BR fcntl (2) +leases that this process may establish. +.TP +.B RLIMIT_MEMLOCK +This is the maximum number of bytes of memory that may be locked +into RAM. +This limit is in effect rounded down to the nearest multiple +of the system page size. +This limit affects +.BR mlock (2), +.BR mlockall (2), +and the +.BR mmap (2) +.B MAP_LOCKED +operation. +Since Linux 2.6.9, it also affects the +.BR shmctl (2) +.B SHM_LOCK +operation, where it sets a maximum on the total bytes in +shared memory segments (see +.BR shmget (2)) +that may be locked by the real user ID of the calling process. +The +.BR shmctl (2) +.B SHM_LOCK +locks are accounted for separately from the per-process memory +locks established by +.BR mlock (2), +.BR mlockall (2), +and +.BR mmap (2) +.BR MAP_LOCKED ; +a process can lock bytes up to this limit in each of these +two categories. +.IP +In Linux kernels before 2.6.9, this limit controlled the amount of +memory that could be locked by a privileged process. +Since Linux 2.6.9, no limits are placed on the amount of memory +that a privileged process may lock, and this limit instead governs +the amount of memory that an unprivileged process may lock. +.TP +.BR RLIMIT_MSGQUEUE " (since Linux 2.6.8)" +This is a limit on the number of bytes that can be allocated +for POSIX message queues for the real user ID of the calling process. +This limit is enforced for +.BR mq_open (3). +Each message queue that the user creates counts (until it is removed) +against this limit according to the formula: +.IP + Since Linux 3.5: +.IP +.EX + bytes = attr.mq_maxmsg * sizeof(struct msg_msg) + + min(attr.mq_maxmsg, MQ_PRIO_MAX) * + sizeof(struct posix_msg_tree_node)+ + /* For overhead */ + attr.mq_maxmsg * attr.mq_msgsize; + /* For message data */ +.EE +.IP + Linux 3.4 and earlier: +.IP +.EX + bytes = attr.mq_maxmsg * sizeof(struct msg_msg *) + + /* For overhead */ + attr.mq_maxmsg * attr.mq_msgsize; + /* For message data */ +.EE +.IP +where +.I attr +is the +.I mq_attr +structure specified as the fourth argument to +.BR mq_open (3), +and the +.I msg_msg +and +.I posix_msg_tree_node +structures are kernel-internal structures. +.IP +The "overhead" addend in the formula accounts for overhead +bytes required by the implementation +and ensures that the user cannot +create an unlimited number of zero-length messages (such messages +nevertheless each consume some system memory for bookkeeping overhead). +.TP +.BR RLIMIT_NICE " (since Linux 2.6.12, but see BUGS below)" +This specifies a ceiling to which the process's nice value can be raised using +.BR setpriority (2) +or +.BR nice (2). +The actual ceiling for the nice value is calculated as +.IR "20\ \-\ rlim_cur" . +The useful range for this limit is thus from 1 +(corresponding to a nice value of 19) to 40 +(corresponding to a nice value of -20). +This unusual choice of range was necessary +because negative numbers cannot be specified +as resource limit values, since they typically have special meanings. +For example, +.B RLIM_INFINITY +typically is the same as \-1. +For more detail on the nice value, see +.BR sched (7). +.TP +.B RLIMIT_NOFILE +This specifies a value one greater than the maximum file descriptor number +that can be opened by this process. +Attempts +.RB ( open (2), +.BR pipe (2), +.BR dup (2), +etc.) +to exceed this limit yield the error +.BR EMFILE . +(Historically, this limit was named +.B RLIMIT_OFILE +on BSD.) +.IP +Since Linux 4.5, +this limit also defines the maximum number of file descriptors that +an unprivileged process (one without the +.BR CAP_SYS_RESOURCE +capability) may have "in flight" to other processes, +by being passed across UNIX domain sockets. +This limit applies to the +.BR sendmsg (2) +system call. +For further details, see +.BR unix (7). +.TP +.B RLIMIT_NPROC +This is a limit on the number of extant process +(or, more precisely on Linux, threads) +for the real user ID of the calling process. +So long as the current number of processes belonging to this +process's real user ID is greater than or equal to this limit, +.BR fork (2) +fails with the error +.BR EAGAIN . +.IP +The +.B RLIMIT_NPROC +limit is not enforced for processes that have either the +.B CAP_SYS_ADMIN +or the +.B CAP_SYS_RESOURCE +capability. +.TP +.B RLIMIT_RSS +This is a limit (in bytes) on the process's resident set +(the number of virtual pages resident in RAM). +This limit has effect only in Linux 2.4.x, x < 30, and there +affects only calls to +.BR madvise (2) +specifying +.BR MADV_WILLNEED . +.\" As at kernel 2.6.12, this limit still does nothing in 2.6 though +.\" talk of making it do something has surfaced from time to time in LKML +.\" -- MTK, Jul 05 +.TP +.BR RLIMIT_RTPRIO " (since Linux 2.6.12, but see BUGS)" +This specifies a ceiling on the real-time priority that may be set for +this process using +.BR sched_setscheduler (2) +and +.BR sched_setparam (2). +.IP +For further details on real-time scheduling policies, see +.BR sched (7) +.TP +.BR RLIMIT_RTTIME " (since Linux 2.6.25)" +This is a limit (in microseconds) +on the amount of CPU time that a process scheduled +under a real-time scheduling policy may consume without making a blocking +system call. +For the purpose of this limit, +each time a process makes a blocking system call, +the count of its consumed CPU time is reset to zero. +The CPU time count is not reset if the process continues trying to +use the CPU but is preempted, its time slice expires, or it calls +.BR sched_yield (2). +.IP +Upon reaching the soft limit, the process is sent a +.B SIGXCPU +signal. +If the process catches or ignores this signal and +continues consuming CPU time, then +.B SIGXCPU +will be generated once each second until the hard limit is reached, +at which point the process is sent a +.B SIGKILL +signal. +.IP +The intended use of this limit is to stop a runaway +real-time process from locking up the system. +.IP +For further details on real-time scheduling policies, see +.BR sched (7) +.TP +.BR RLIMIT_SIGPENDING " (since Linux 2.6.8)" +This is a limit on the number of signals +that may be queued for the real user ID of the calling process. +Both standard and real-time signals are counted for the purpose of +checking this limit. +However, the limit is enforced only for +.BR sigqueue (3); +it is always possible to use +.BR kill (2) +to queue one instance of any of the signals that are not already +queued to the process. +.\" This replaces the /proc/sys/kernel/rtsig-max system-wide limit +.\" that was present in kernels <= 2.6.7. MTK Dec 04 +.TP +.B RLIMIT_STACK +This is the maximum size of the process stack, in bytes. +Upon reaching this limit, a +.B SIGSEGV +signal is generated. +To handle this signal, a process must employ an alternate signal stack +.RB ( sigaltstack (2)). +.IP +Since Linux 2.6.23, +this limit also determines the amount of space used for the process's +command-line arguments and environment variables; for details, see +.BR execve (2). +.SS prlimit() +.\" commit c022a0acad534fd5f5d5f17280f6d4d135e74e81 +.\" Author: Jiri Slaby +.\" Date: Tue May 4 18:03:50 2010 +0200 +.\" +.\" rlimits: implement prlimit64 syscall +.\" +.\" commit 6a1d5e2c85d06da35cdfd93f1a27675bfdc3ad8c +.\" Author: Jiri Slaby +.\" Date: Wed Mar 24 17:06:58 2010 +0100 +.\" +.\" rlimits: add rlimit64 structure +.\" +The Linux-specific +.BR prlimit () +system call combines and extends the functionality of +.BR setrlimit () +and +.BR getrlimit (). +It can be used to both set and get the resource limits of an arbitrary process. +.PP +The +.I resource +argument has the same meaning as for +.BR setrlimit () +and +.BR getrlimit (). +.PP +If the +.IR new_limit +argument is a not NULL, then the +.I rlimit +structure to which it points is used to set new values for +the soft and hard limits for +.IR resource . +If the +.IR old_limit +argument is a not NULL, then a successful call to +.BR prlimit () +places the previous soft and hard limits for +.I resource +in the +.I rlimit +structure pointed to by +.IR old_limit . +.PP +The +.I pid +argument specifies the ID of the process on which the call is to operate. +If +.I pid +is 0, then the call applies to the calling process. +To set or get the resources of a process other than itself, +the caller must have the +.B CAP_SYS_RESOURCE +capability in the user namespace of the process +whose resource limits are being changed, or the +real, effective, and saved set user IDs of the target process +must match the real user ID of the caller +.I and +the real, effective, and saved set group IDs of the target process +must match the real group ID of the caller. +.\" FIXME . this permission check is strange +.\" Asked about this on LKML, 7 Nov 2010 +.\" "Inconsistent credential checking in prlimit() syscall" +.SH RETURN VALUE +On success, these system calls return 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +A pointer argument points to a location +outside the accessible address space. +.TP +.B EINVAL +The value specified in +.I resource +is not valid; +or, for +.BR setrlimit () +or +.BR prlimit (): +.I rlim\->rlim_cur +was greater than +.IR rlim\->rlim_max . +.TP +.B EPERM +An unprivileged process tried to raise the hard limit; the +.B CAP_SYS_RESOURCE +capability is required to do this. +.TP +.B EPERM +The caller tried to increase the hard +.B RLIMIT_NOFILE +limit above the maximum defined by +.IR /proc/sys/fs/nr_open +(see +.BR proc (5)) +.TP +.B EPERM +.RB ( prlimit ()) +The calling process did not have permission to set limits +for the process specified by +.IR pid . +.TP +.B ESRCH +Could not find a process with the ID specified in +.IR pid . +.SH VERSIONS +The +.BR prlimit () +system call is available since Linux 2.6.36. +Library support is available since glibc 2.13. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw35 lb lb +l l l. +Interface Attribute Value +T{ +.BR getrlimit (), +.BR setrlimit (), +.BR prlimit () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +.BR getrlimit (), +.BR setrlimit (): +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.PP +.BR prlimit (): +Linux-specific. +.PP +.B RLIMIT_MEMLOCK +and +.B RLIMIT_NPROC +derive from BSD and are not specified in POSIX.1; +they are present on the BSDs and Linux, but on few other implementations. +.B RLIMIT_RSS +derives from BSD and is not specified in POSIX.1; +it is nevertheless present on most implementations. +.BR RLIMIT_MSGQUEUE , +.BR RLIMIT_NICE , +.BR RLIMIT_RTPRIO , +.BR RLIMIT_RTTIME , +and +.B RLIMIT_SIGPENDING +are Linux-specific. +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's resource limits. +Resource limits are preserved across +.BR execve (2). +.PP +Lowering the soft limit for a resource below the process's +current consumption of that resource will succeed +(but will prevent the process from further increasing +its consumption of the resource). +.PP +One can set the resource limits of the shell using the built-in +.IR ulimit +command +.RI ( limit +in +.BR csh (1)). +The shell's resource limits are inherited by the processes that +it creates to execute commands. +.PP +Since Linux 2.6.24, the resource limits of any process can be inspected via +.IR /proc/[pid]/limits ; +see +.BR proc (5). +.PP +Ancient systems provided a +.BR vlimit () +function with a similar purpose to +.BR setrlimit (). +For backward compatibility, glibc also provides +.BR vlimit (). +All new applications should be written using +.BR setrlimit (). +.SS C library/kernel ABI differences +Since version 2.13, the glibc +.BR getrlimit () +and +.BR setrlimit () +wrapper functions no longer invoke the corresponding system calls, +but instead employ +.BR prlimit (), +for the reasons described in BUGS. +.PP +The name of the glibc wrapper function is +.BR prlimit (); +the underlying system call is +.BR prlimit64 (). +.SH BUGS +In older Linux kernels, the +.B SIGXCPU +and +.B SIGKILL +signals delivered when a process encountered the soft and hard +.B RLIMIT_CPU +limits were delivered one (CPU) second later than they should have been. +This was fixed in kernel 2.6.8. +.PP +In 2.6.x kernels before 2.6.17, a +.B RLIMIT_CPU +limit of 0 is wrongly treated as "no limit" (like +.BR RLIM_INFINITY ). +Since Linux 2.6.17, setting a limit of 0 does have an effect, +but is actually treated as a limit of 1 second. +.\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=114008066530167&w=2 +.PP +A kernel bug means that +.\" See https://lwn.net/Articles/145008/ +.B RLIMIT_RTPRIO +does not work in kernel 2.6.12; the problem is fixed in kernel 2.6.13. +.PP +In kernel 2.6.12, there was an off-by-one mismatch +between the priority ranges returned by +.BR getpriority (2) +and +.BR RLIMIT_NICE . +This had the effect that the actual ceiling for the nice value +was calculated as +.IR "19\ \-\ rlim_cur" . +This was fixed in kernel 2.6.13. +.\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2 +.PP +Since Linux 2.6.12, +.\" The relevant patch, sent to LKML, seems to be +.\" http://thread.gmane.org/gmane.linux.kernel/273462 +.\" From: Roland McGrath redhat.com> +.\" Subject: [PATCH 7/7] make RLIMIT_CPU/SIGXCPU per-process +.\" Date: 2005-01-23 23:27:46 GMT +if a process reaches its soft +.BR RLIMIT_CPU +limit and has a handler installed for +.BR SIGXCPU , +then, in addition to invoking the signal handler, +the kernel increases the soft limit by one second. +This behavior repeats if the process continues to consume CPU time, +until the hard limit is reached, +at which point the process is killed. +Other implementations +.\" Tested Solaris 10, FreeBSD 9, OpenBSD 5.0 +do not change the +.BR RLIMIT_CPU +soft limit in this manner, +and the Linux behavior is probably not standards conformant; +portable applications should avoid relying on this Linux-specific behavior. +.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=50951 +The Linux-specific +.BR RLIMIT_RTTIME +limit exhibits the same behavior when the soft limit is encountered. +.PP +Kernels before 2.4.22 did not diagnose the error +.B EINVAL +for +.BR setrlimit () +when +.I rlim\->rlim_cur +was greater than +.IR rlim\->rlim_max . +.\" +.SS Representation of """large""" resource limit values on 32-bit platforms +The glibc +.BR getrlimit () +and +.BR setrlimit () +wrapper functions use a 64-bit +.IR rlim_t +data type, even on 32-bit platforms. +However, the +.I rlim_t +data type used in the +.BR getrlimit () +and +.BR setrlimit () +system calls is a (32-bit) +.IR "unsigned long" . +Furthermore, in Linux versions before 2.6.36, +the kernel represents resource limits on 32-bit platforms as +.IR "unsigned long" . +However, a 32-bit data type is not wide enough. +.\" https://bugzilla.kernel.org/show_bug.cgi?id=5042 +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=12201 +The most pertinent limit here is +.BR RLIMIT_FSIZE , +which specifies the maximum size to which a file can grow: +to be useful, this limit must be represented using a type +that is as wide as the type used to +represent file offsets\(emthat is, as wide as a 64-bit +.BR off_t +(assuming a program compiled with +.IR _FILE_OFFSET_BITS=64 ). +.PP +To work around this kernel limitation, +if a program tried to set a resource limit to a value larger than +can be represented in a 32-bit +.IR "unsigned long" , +then the glibc +.BR setrlimit () +wrapper function silently converted the limit value to +.BR RLIM_INFINITY . +In other words, the requested resource limit setting was silently ignored. +.PP +This problem was addressed in Linux 2.6.36 with two principal changes: +.IP * 3 +the addition of a new kernel representation of resource limits that +uses 64 bits, even on 32-bit platforms; +.IP * +the addition of the +.BR prlimit () +system call, which employs 64-bit values for its resource limit arguments. +.PP +Since version 2.13, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201 +glibc works around the limitations of the +.BR getrlimit () +and +.BR setrlimit () +system calls by implementing +.BR setrlimit () +and +.BR getrlimit () +as wrapper functions that call +.BR prlimit (). +.SH EXAMPLE +The program below demonstrates the use of +.BR prlimit (). +.PP +.EX +#define _GNU_SOURCE +#define _FILE_OFFSET_BITS 64 +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + struct rlimit old, new; + struct rlimit *newp; + pid_t pid; + + if (!(argc == 2 || argc == 4)) { + fprintf(stderr, "Usage: %s [ " + "]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + pid = atoi(argv[1]); /* PID of target process */ + + newp = NULL; + if (argc == 4) { + new.rlim_cur = atoi(argv[2]); + new.rlim_max = atoi(argv[3]); + newp = &new; + } + + /* Set CPU time limit of target process; retrieve and display + previous limit */ + + if (prlimit(pid, RLIMIT_CPU, newp, &old) == \-1) + errExit("prlimit\-1"); + printf("Previous limits: soft=%lld; hard=%lld\\n", + (long long) old.rlim_cur, (long long) old.rlim_max); + + /* Retrieve and display new CPU time limit */ + + if (prlimit(pid, RLIMIT_CPU, NULL, &old) == \-1) + errExit("prlimit\-2"); + printf("New limits: soft=%lld; hard=%lld\\n", + (long long) old.rlim_cur, (long long) old.rlim_max); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR prlimit (1), +.BR dup (2), +.BR fcntl (2), +.BR fork (2), +.BR getrusage (2), +.BR mlock (2), +.BR mmap (2), +.BR open (2), +.BR quotactl (2), +.BR sbrk (2), +.BR shmctl (2), +.BR malloc (3), +.BR sigqueue (3), +.BR ulimit (3), +.BR core (5), +.BR capabilities (7), +.BR cgroups (7), +.BR credentials (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getrusage.2 b/man2/getrusage.2 new file mode 100644 index 0000000..fdd7f0b --- /dev/null +++ b/man2/getrusage.2 @@ -0,0 +1,281 @@ +.\" Copyright (c) 1992 Drew Eckhardt, March 28, 1992 +.\" and Copyright (c) 2002 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formerly included +.\" coverage of getrusage(2), has been split, so that the latter is +.\" now covered in its own getrusage.2. For older details of change +.\" history, etc., see getrlimit.2 +.\" +.\" Modified 2004-11-16, mtk, Noted that the nonconformance +.\" when SIGCHLD is being ignored is fixed in 2.6.9. +.\" 2008-02-22, Sripathi Kodi : Document RUSAGE_THREAD +.\" 2008-05-25, mtk, clarify RUSAGE_CHILDREN + other clean-ups. +.\" 2010-05-24, Mark Hills : Description of fields, +.\" document ru_maxrss +.\" 2010-05-24, mtk, enhanced description of various fields +.\" +.TH GETRUSAGE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getrusage \- get resource usage +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int getrusage(int " who ", struct rusage *" usage ); +.SH DESCRIPTION +.PP +.BR getrusage () +returns resource usage measures for +.IR who , +which can be one of the following: +.TP +.B RUSAGE_SELF +Return resource usage statistics for the calling process, +which is the sum of resources used by all threads in the process. +.TP +.B RUSAGE_CHILDREN +Return resource usage statistics for all children of the +calling process that have terminated and been waited for. +These statistics will include the resources used by grandchildren, +and further removed descendants, +if all of the intervening descendants waited on their terminated children. +.TP +.BR RUSAGE_THREAD " (since Linux 2.6.26)" +Return resource usage statistics for the calling thread. +The +.B _GNU_SOURCE +feature test macro must be defined (before including +.I any +header file) +in order to obtain the definition of this constant from +.IR . +.PP +The resource usages are returned in the structure pointed to by +.IR usage , +which has the following form: +.PP +.in +4n +.EX +struct rusage { + struct timeval ru_utime; /* user CPU time used */ + struct timeval ru_stime; /* system CPU time used */ + long ru_maxrss; /* maximum resident set size */ + long ru_ixrss; /* integral shared memory size */ + long ru_idrss; /* integral unshared data size */ + long ru_isrss; /* integral unshared stack size */ + long ru_minflt; /* page reclaims (soft page faults) */ + long ru_majflt; /* page faults (hard page faults) */ + long ru_nswap; /* swaps */ + long ru_inblock; /* block input operations */ + long ru_oublock; /* block output operations */ + long ru_msgsnd; /* IPC messages sent */ + long ru_msgrcv; /* IPC messages received */ + long ru_nsignals; /* signals received */ + long ru_nvcsw; /* voluntary context switches */ + long ru_nivcsw; /* involuntary context switches */ +}; +.EE +.in +.PP +Not all fields are completed; +unmaintained fields are set to zero by the kernel. +(The unmaintained fields are provided for compatibility with other systems, +and because they may one day be supported on Linux.) +The fields are interpreted as follows: +.TP +.I ru_utime +This is the total amount of time spent executing in user mode, +expressed in a +.I timeval +structure (seconds plus microseconds). +.TP +.I ru_stime +This is the total amount of time spent executing in kernel mode, +expressed in a +.I timeval +structure (seconds plus microseconds). +.TP +.IR ru_maxrss " (since Linux 2.6.32)" +This is the maximum resident set size used (in kilobytes). +For +.BR RUSAGE_CHILDREN , +this is the resident set size of the largest child, not the maximum +resident set size of the process tree. +.TP +.IR ru_ixrss " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, +.\" this is the integral of the text segment memory consumption, +.\" expressed in kilobyte-seconds. +.TP +.IR ru_idrss " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, this is the integral of the data segment memory consumption, +.\" expressed in kilobyte-seconds. +.TP +.IR ru_isrss " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, this is the integral of the stack memory consumption, +.\" expressed in kilobyte-seconds. +.TP +.I ru_minflt +The number of page faults serviced without any I/O activity; here +I/O activity is avoided by \*(lqreclaiming\*(rq a page frame from +the list of pages awaiting reallocation. +.TP +.I ru_majflt +The number of page faults serviced that required I/O activity. +.TP +.IR ru_nswap " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, this is the number of swaps out of physical memory. +.TP +.IR ru_inblock " (since Linux 2.6.22)" +The number of times the filesystem had to perform input. +.TP +.IR ru_oublock " (since Linux 2.6.22)" +The number of times the filesystem had to perform output. +.TP +.IR ru_msgsnd " (unmaintained)" +This field is currently unused on Linux. +.\" On FreeBSD 6.2, this appears to measure messages sent over sockets +.\" On some systems, +.\" this field records the number of messages sent over sockets. +.TP +.IR ru_msgrcv " (unmaintained)" +This field is currently unused on Linux. +.\" On FreeBSD 6.2, this appears to measure messages received over sockets +.\" On some systems, +.\" this field records the number of messages received over sockets. +.TP +.IR ru_nsignals " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, this field records the number of signals received. +.TP +.IR ru_nvcsw " (since Linux 2.6)" +The number of times a context switch resulted due to a process +voluntarily giving up the processor before its time slice was +completed (usually to await availability of a resource). +.TP +.IR ru_nivcsw " (since Linux 2.6)" +The number of times a context switch resulted due to a higher +priority process becoming runnable or because the current process +exceeded its time slice. +.PP +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I usage +points outside the accessible address space. +.TP +.B EINVAL +.I who +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getrusage () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +POSIX.1 specifies +.BR getrusage (), +but specifies only the fields +.I ru_utime +and +.IR ru_stime . +.PP +.B RUSAGE_THREAD +is Linux-specific. +.SH NOTES +Resource usage metrics are preserved across an +.BR execve (2). +.PP +Including +.I +is not required these days, but increases portability. +(Indeed, +.I struct timeval +is defined in +.IR .) +.PP +In Linux kernel versions before 2.6.9, if the disposition of +.B SIGCHLD +is set to +.B SIG_IGN +then the resource usages of child processes +are automatically included in the value returned by +.BR RUSAGE_CHILDREN , +although POSIX.1-2001 explicitly prohibits this. +This nonconformance is rectified in Linux 2.6.9 and later. +.\" See the description of getrusage() in XSH. +.\" A similar statement was also in SUSv2. +.PP +The structure definition shown at the start of this page +was taken from 4.3BSD Reno. +.PP +Ancient systems provided a +.BR vtimes () +function with a similar purpose to +.BR getrusage (). +For backward compatibility, glibc also provides +.BR vtimes (). +All new applications should be written using +.BR getrusage (). +.PP +See also the description of +.IR /proc/[pid]/stat +in +.BR proc (5). +.SH SEE ALSO +.BR clock_gettime (2), +.BR getrlimit (2), +.BR times (2), +.BR wait (2), +.BR wait4 (2), +.BR clock (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getsid.2 b/man2/getsid.2 new file mode 100644 index 0000000..7779438 --- /dev/null +++ b/man2/getsid.2 @@ -0,0 +1,106 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Thu Oct 31 14:18:40 1996 by Eric S. Raymond +.\" Modified 2001-12-17, aeb +.TH GETSID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getsid \- get session ID +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "pid_t getsid(pid_t" " pid" ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.PD 0 +.BR getsid (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.br + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L +.RE +.PD +.ad +.SH DESCRIPTION +.I getsid(0) +returns the session ID of the calling process. +.BR getsid () +returns the session ID of the process with process ID +.IR pid . +If +.I pid +is 0, +.BR getsid () +returns the session ID of the calling process. +.SH RETURN VALUE +On success, a session ID is returned. +On error, \fI(pid_t)\ \-1\fP will be returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +A process with process ID +.I pid +exists, but it is not in the same session as the calling process, +and the implementation considers this an error. +.TP +.B ESRCH +No process with process ID +.I pid +was found. +.SH VERSIONS +This system call is available on Linux since version 2.0. +.\" Linux has this system call since Linux 1.3.44. +.\" There is libc support since libc 5.2.19. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.SH NOTES +Linux does not return +.BR EPERM . +.PP +See +.BR credentials (7) +for a description of sessions and session IDs. +.SH SEE ALSO +.BR getpgid (2), +.BR setsid (2), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getsockname.2 b/man2/getsockname.2 new file mode 100644 index 0000000..633acc8 --- /dev/null +++ b/man2/getsockname.2 @@ -0,0 +1,123 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)getsockname.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 16:30:29 1993 by Rik Faith +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer +.\" +.TH GETSOCKNAME 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getsockname \- get socket name +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getsockname(int " sockfd ", struct sockaddr *" addr \ +", socklen_t *" addrlen ); +.fi +.SH DESCRIPTION +.BR getsockname () +returns the current address to which the socket +.I sockfd +is bound, in the buffer pointed to by +.IR addr . +The +.I addrlen +argument should be initialized to indicate +the amount of space (in bytes) pointed to by +.IR addr . +On return it contains the actual size of the socket address. +.PP +The returned address is truncated if the buffer provided is too small; +in this case, +.I addrlen +will return a value greater than was supplied to the call. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +The argument +.I sockfd +is not a valid file descriptor. +.TP +.B EFAULT +The +.I addr +argument points to memory not in a valid part of the +process address space. +.TP +.B EINVAL +.I addrlen +is invalid (e.g., is negative). +.TP +.B ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD +.RB ( getsockname () +first appeared in 4.2BSD). +.\" SVr4 documents additional ENOMEM +.\" and ENOSR error codes. +.SH NOTES +For background on the +.I socklen_t +type, see +.BR accept (2). +.SH SEE ALSO +.BR bind (2), +.BR socket (2), +.BR getifaddrs (3), +.BR ip (7), +.BR socket (7), +.BR unix (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getsockopt.2 b/man2/getsockopt.2 new file mode 100644 index 0000000..dfbd3be --- /dev/null +++ b/man2/getsockopt.2 @@ -0,0 +1,214 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" $Id: getsockopt.2,v 1.1 1999/05/24 14:57:04 freitag Exp $ +.\" +.\" Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de) +.\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 1999 by Andi Kleen . +.\" Removed most stuff because it is in socket.7 now. +.\" +.TH GETSOCKOPT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getsockopt, setsockopt \- get and set options on sockets +.SH SYNOPSIS +.nf +.BR "#include " " /* See NOTES */" +.B #include +.PP +.BI "int getsockopt(int " sockfd ", int " level ", int " optname , +.BI " void *" optval ", socklen_t *" optlen ); +.BI "int setsockopt(int " sockfd ", int " level ", int " optname , +.BI " const void *" optval ", socklen_t " optlen ); +.fi +.SH DESCRIPTION +.BR getsockopt () +and +.BR setsockopt () +manipulate options for the socket referred to by the file descriptor +.IR sockfd . +Options may exist at multiple +protocol levels; they are always present at the uppermost +socket level. +.PP +When manipulating socket options, the level at which the +option resides and the name of the option must be specified. +To manipulate options at the sockets API level, +.I level +is specified as +.BR SOL_SOCKET . +To manipulate options at any +other level the protocol number of the appropriate protocol +controlling the option is supplied. +For example, +to indicate that an option is to be interpreted by the +.B TCP +protocol, +.I level +should be set to the protocol number of +.BR TCP ; +see +.BR getprotoent (3). +.PP +The arguments +.I optval +and +.I optlen +are used to access option values for +.BR setsockopt (). +For +.BR getsockopt () +they identify a buffer in which the value for the +requested option(s) are to be returned. +For +.BR getsockopt (), +.I optlen +is a value-result argument, initially containing the +size of the buffer pointed to by +.IR optval , +and modified on return to indicate the actual size of +the value returned. +If no option value is to be supplied or returned, +.I optval +may be NULL. +.PP +.I Optname +and any specified options are passed uninterpreted to the appropriate +protocol module for interpretation. +The include file +.I +contains definitions for socket level options, described below. +Options at +other protocol levels vary in format and name; consult the appropriate +entries in section 4 of the manual. +.PP +Most socket-level options utilize an +.I int +argument for +.IR optval . +For +.BR setsockopt (), +the argument should be nonzero to enable a boolean option, or zero if the +option is to be disabled. +.PP +For a description of the available socket options see +.BR socket (7) +and the appropriate protocol man pages. +.SH RETURN VALUE +On success, zero is returned for the standard options. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +Netfilter allows the programmer +to define custom socket options with associated handlers; for such +options, the return value on success is the value returned by the handler. +.SH ERRORS +.TP 10 +.B EBADF +The argument +.I sockfd +is not a valid file descriptor. +.TP +.B EFAULT +The address pointed to by +.I optval +is not in a valid part of the process address space. +For +.BR getsockopt (), +this error may also be returned if +.I optlen +is not in a valid part of the process address space. +.TP +.B EINVAL +.I optlen +invalid in +.BR setsockopt (). +In some cases this error can also occur for an invalid value in +.IR optval +(e.g., for the +.B IP_ADD_MEMBERSHIP +option described in +.BR ip (7)). +.TP +.B ENOPROTOOPT +The option is unknown at the level indicated. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, +SVr4, 4.4BSD (these system calls first appeared in 4.2BSD). +.\" SVr4 documents additional ENOMEM and ENOSR error codes, but does +.\" not document the +.\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO +.\" options +.SH NOTES +POSIX.1 does not require the inclusion of +.IR , +and this header file is not required on Linux. +However, some historical (BSD) implementations required this header +file, and portable applications are probably wise to include it. +.PP +For background on the +.I socklen_t +type, see +.BR accept (2). +.SH BUGS +Several of the socket options should be handled at lower levels of the +system. +.SH SEE ALSO +.BR ioctl (2), +.BR socket (2), +.BR getprotoent (3), +.BR protocols (5), +.BR ip (7), +.BR packet (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/gettid.2 b/man2/gettid.2 new file mode 100644 index 0000000..7434b66 --- /dev/null +++ b/man2/gettid.2 @@ -0,0 +1,110 @@ +.\" Copyright 2003 Abhijit Menon-Sen +.\" and Copyright (C) 2008 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETTID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +gettid \- get thread identification +.SH SYNOPSIS +.nf +.B #include +.PP +.B pid_t gettid(void); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.BR gettid () +returns the caller's thread ID (TID). +In a single-threaded process, the thread ID +is equal to the process ID (PID, as returned by +.BR getpid (2)). +In a multithreaded process, all threads +have the same PID, but each one has a unique TID. +For further details, see the discussion of +.BR CLONE_THREAD +in +.BR clone (2). +.SH RETURN VALUE +On success, returns the thread ID of the calling process. +.SH ERRORS +This call is always successful. +.SH VERSIONS +The +.BR gettid () +system call first appeared on Linux in kernel 2.4.11. +.SH CONFORMING TO +.BR gettid () +is Linux-specific and should not be used in programs that +are intended to be portable. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.\" FIXME . See http://sourceware.org/bugzilla/show_bug.cgi?id=6399 +.\" "gettid() should have a wrapper" +.PP +The thread ID returned by this call is not the same thing as a +POSIX thread ID (i.e., the opaque value returned by +.BR pthread_self (3)). +.PP +In a new thread group created by a +.BR clone (2) +call that does not specify the +.BR CLONE_THREAD +flag (or, equivalently, a new process created by +.BR fork (2)), +the new process is a thread group leader, +and its thread group ID (the value returned by +.BR getpid (2)) +is the same as its thread ID (the value returned by +.BR gettid ()). +.SH SEE ALSO +.BR capget (2), +.BR clone (2), +.BR fcntl (2), +.BR fork (2), +.BR getpid (2), +.BR get_robust_list (2), +.\" .BR kcmp (2), +.BR ioprio_set (2), +.\" .BR move_pages (2), +.\" .BR migrate_pages (2), +.BR perf_event_open (2), +.\" .BR process_vm_readv (2), +.\" .BR ptrace (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR tgkill (2), +.BR timer_create (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2 new file mode 100644 index 0000000..de5759d --- /dev/null +++ b/man2/gettimeofday.2 @@ -0,0 +1,281 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified 1993-07-23 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): +.\" Fixed necessary '#include' lines. +.\" Modified 1995-04-15 by Michael Chastain (mec@shell.portal.com): +.\" Added reference to adjtimex. +.\" Removed some nonsense lines pointed out by Urs Thuermann, +.\" (urs@isnogud.escape.de), aeb, 950722. +.\" Modified 1997-01-14 by Austin Donnelly (and1000@debian.org): +.\" Added return values section, and bit on EFAULT +.\" Added clarification on timezone, aeb, 971210. +.\" Removed "#include ", aeb, 010316. +.\" Modified, 2004-05-27 by Michael Kerrisk +.\" Added notes on capability requirement. +.\" +.TH GETTIMEOFDAY 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +gettimeofday, settimeofday \- get / set time +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int gettimeofday(struct timeval *" tv ", struct timezone *" tz ); +.PP +.BI "int settimeofday(const struct timeval *" tv \ +", const struct timezone *" tz ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR settimeofday (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The functions +.BR gettimeofday () +and +.BR settimeofday () +can get and set the time as well as a timezone. +The +.I tv +argument is a +.I struct timeval +(as specified in +.IR ): +.PP +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.PP +and gives the number of seconds and microseconds since the Epoch (see +.BR time (2)). +The +.I tz +argument is a +.IR "struct timezone" : +.PP +.in +4n +.EX +struct timezone { + int tz_minuteswest; /* minutes west of Greenwich */ + int tz_dsttime; /* type of DST correction */ +}; +.EE +.in +.PP +If either +.I tv +or +.I tz +is NULL, the corresponding structure is not set or returned. +.\" FIXME . The compilation warning looks to be going away in 2.17 +.\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8 +(However, compilation warnings will result if +.I tv +is NULL.) +.\" The following is covered under EPERM below: +.\" .PP +.\" Only the superuser may use +.\" .BR settimeofday (). +.PP +The use of the +.I timezone +structure is obsolete; the +.I tz +argument should normally be specified as NULL. +(See NOTES below.) +.PP +Under Linux, there are some peculiar "warp clock" semantics associated +with the +.BR settimeofday () +system call if on the very first call (after booting) +that has a non-NULL +.I tz +argument, the +.I tv +argument is NULL and the +.I tz_minuteswest +field is nonzero. +(The +.I tz_dsttime +field should be zero for this case.) +In such a case it is assumed that the CMOS clock +is on local time, and that it has to be incremented by this amount +to get UTC system time. +No doubt it is a bad idea to use this feature. +.SH RETURN VALUE +.BR gettimeofday () +and +.BR settimeofday () +return 0 for success, or \-1 for failure (in which case +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EFAULT +One of +.I tv +or +.I tz +pointed outside the accessible address space. +.TP +.B EINVAL +Timezone (or something else) is invalid. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR settimeofday (); +under Linux the +.B CAP_SYS_TIME +capability is required. +.SH CONFORMING TO +SVr4, 4.3BSD. +POSIX.1-2001 describes +.BR gettimeofday () +but not +.BR settimeofday (). +POSIX.1-2008 marks +.BR gettimeofday () +as obsolete, recommending the use of +.BR clock_gettime (2) +instead. +.SH NOTES +The time returned by +.BR gettimeofday () +.I is +affected by discontinuous jumps in the system time +(e.g., if the system administrator manually changes the system time). +If you need a monotonically increasing clock, see +.BR clock_gettime (2). +.PP +Macros for operating on +.I timeval +structures are described in +.BR timeradd (3). +.PP +Traditionally, the fields of +.I struct timeval +were of type +.IR long . +.\" +.SS C library/kernel differences +On some architectures, an implementation of +.BR gettimeofday () +is provided in the +.BR vdso (7). +.\" +.SS The tz_dsttime field +On a non-Linux kernel, with glibc, the +.I tz_dsttime +field of +.I struct timezone +will be set to a nonzero value by +.BR gettimeofday () +if the current timezone has ever had or will have a daylight saving +rule applied. +In this sense it exactly mirrors the meaning of +.BR daylight (3) +for the current zone. +On Linux, with glibc, the setting of the +.I tz_dsttime +field of +.I struct timezone +has never been used by +.BR settimeofday () +or +.BR gettimeofday (). +.\" it has not +.\" been and will not be supported by libc or glibc. +.\" Each and every occurrence of this field in the kernel source +.\" (other than the declaration) is a bug. +Thus, the following is purely of historical interest. +.PP +On old systems, the field +.I tz_dsttime +contains a symbolic constant (values are given below) +that indicates in which part of the year Daylight Saving Time +is in force. +(Note: this value is constant throughout the year: +it does not indicate that DST is in force, it just selects an +algorithm.) +The daylight saving time algorithms defined are as follows: +.PP +.in +4n +.EX +\fBDST_NONE\fP /* not on DST */ +\fBDST_USA\fP /* USA style DST */ +\fBDST_AUST\fP /* Australian style DST */ +\fBDST_WET\fP /* Western European DST */ +\fBDST_MET\fP /* Middle European DST */ +\fBDST_EET\fP /* Eastern European DST */ +\fBDST_CAN\fP /* Canada */ +\fBDST_GB\fP /* Great Britain and Eire */ +\fBDST_RUM\fP /* Romania */ +\fBDST_TUR\fP /* Turkey */ +\fBDST_AUSTALT\fP /* Australian style with shift in 1986 */ +.EE +.in +.PP +Of course it turned out that the period in which +Daylight Saving Time is in force cannot be given +by a simple algorithm, one per country; indeed, +this period is determined by unpredictable political +decisions. +So this method of representing timezones +has been abandoned. +.SH SEE ALSO +.BR date (1), +.BR adjtimex (2), +.BR clock_gettime (2), +.BR time (2), +.BR ctime (3), +.BR ftime (3), +.BR timeradd (3), +.BR capabilities (7), +.BR time (7), +.BR vdso (7), +.BR hwclock (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getuid.2 b/man2/getuid.2 new file mode 100644 index 0000000..af18abf --- /dev/null +++ b/man2/getuid.2 @@ -0,0 +1,86 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Historical remark, aeb, 2004-06-05 +.TH GETUID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getuid, geteuid \- get user identity +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B uid_t getuid(void); +.br +.B uid_t geteuid(void); +.SH DESCRIPTION +.BR getuid () +returns the real user ID of the calling process. +.PP +.BR geteuid () +returns the effective user ID of the calling process. +.SH ERRORS +These functions are always successful. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH NOTES +.SS History +In UNIX\ V6 the +.BR getuid () +call returned +.IR "(euid << 8) + uid" . +UNIX\ V7 introduced separate calls +.BR getuid () +and +.BR geteuid (). +.PP +The original Linux +.BR getuid () +and +.BR geteuid () +system calls supported only 16-bit user IDs. +Subsequently, Linux 2.4 added +.BR getuid32 () +and +.BR geteuid32 (), +supporting 32-bit IDs. +The glibc +.BR getuid () +and +.BR geteuid () +wrapper functions transparently deal with the variations across kernel versions. +.SH SEE ALSO +.BR getresuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getuid32.2 b/man2/getuid32.2 new file mode 100644 index 0000000..165cfe1 --- /dev/null +++ b/man2/getuid32.2 @@ -0,0 +1 @@ +.so man2/getuid.2 diff --git a/man2/getunwind.2 b/man2/getunwind.2 new file mode 100644 index 0000000..3173178 --- /dev/null +++ b/man2/getunwind.2 @@ -0,0 +1,119 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Written by Marcela Maslanova +.\" and Copyright 2013, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETUNWIND 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +getunwind \- copy the unwind data to caller's buffer +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "long getunwind(void " *buf ", size_t " buf_size ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.I Note: this function is obsolete. +.PP +The +IA-64-specific +.BR getunwind () +system call copies the kernel's call frame +unwind data into the buffer pointed to by +.I buf +and returns the size of the unwind data; +this data describes the gate page (kernel code that +is mapped into user space). +.PP +The size of the buffer +.I buf +is specified in +.IR buf_size . +The data is copied only if +.I buf_size +is greater than or equal to the size of the unwind data and +.I buf +is not NULL; +otherwise, no data is copied, and the call succeeds, +returning the size that would be needed to store the unwind data. +.PP +The first part of the unwind data contains an unwind table. +The rest contains the associated unwind information, in no particular order. +The unwind table contains entries of the following form: +.PP +.in +4n +.EX +u64 start; (64-bit address of start of function) +u64 end; (64-bit address of end of function) +u64 info; (BUF-relative offset to unwind info) +.EE +.in +.PP +An entry whose +.I start +value is zero indicates the end of the table. +For more information about the format, see the +.I IA-64 Software Conventions and Runtime Architecture +manual. +.SH RETURN VALUE +On success, +.BR getunwind () +returns the size of the unwind data. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR getunwind () +fails with the error +.B EFAULT +if the unwind info can't be stored in the space specified by +.IR buf . +.SH VERSIONS +This system call is available since Linux 2.4. +.SH CONFORMING TO +This system call is Linux-specific, +and is available only on the IA-64 architecture. +.SH NOTES +This system call has been deprecated. +The modern way to obtain the kernel's unwind data is via the +.BR vdso (7). +.PP +Glibc does not provide a wrapper for this system call; +in the unlikely event that you want to call it, use +.BR syscall (2). +.SH SEE ALSO +.BR getauxval (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/getxattr.2 b/man2/getxattr.2 new file mode 100644 index 0000000..eaf5555 --- /dev/null +++ b/man2/getxattr.2 @@ -0,0 +1,172 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH GETXATTR 2 2017-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +getxattr, lgetxattr, fgetxattr \- retrieve an extended attribute value +.SH SYNOPSIS +.fam C +.nf +.B #include +.B #include +.PP +.BI "ssize_t getxattr(const char\ *" path ", const char\ *" name , +.BI " void\ *" value ", size_t " size ); +.BI "ssize_t lgetxattr(const char\ *" path ", const char\ *" name , +.BI " void\ *" value ", size_t " size ); +.BI "ssize_t fgetxattr(int " fd ", const char\ *" name , +.BI " void\ *" value ", size_t " size ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +.I value +pairs associated with inodes (files, directories, symbolic links, etc.). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e., the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR xattr (7). +.PP +.BR getxattr () +retrieves the value of the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +The attribute value is placed in the buffer pointed to by +.IR value ; +.I size +specifies the size of that buffer. +The return value of the call is the number of bytes placed in +.IR value . +.PP +.BR lgetxattr () +is identical to +.BR getxattr (), +except in the case of a symbolic link, where the link itself is +interrogated, not the file that it refers to. +.PP +.BR fgetxattr () +is identical to +.BR getxattr (), +only the open file referred to by +.I fd +(as returned by +.BR open (2)) +is interrogated in place of +.IR path . +.PP +An extended attribute +.I name +is a null-terminated string. +The name includes a namespace prefix; there may be several, disjoint +namespaces associated with an individual inode. +The value of an extended attribute is a chunk of arbitrary textual or +binary data that was assigned using +.BR setxattr (2). +.PP +If +.I size +is specified as zero, these calls return the current size of the +named extended attribute (and leave +.I value +unchanged). +This can be used to determine the size of the buffer that +should be supplied in a subsequent call. +(But, bear in mind that there is a possibility that the +attribute value may change between the two calls, +so that it is still necessary to check the return status +from the second call.) +.SH RETURN VALUE +On success, these calls return a nonnegative value which is +the size (in bytes) of the extended attribute value. +On failure, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B E2BIG +The size of the attribute value is larger than the maximum size allowed; the +attribute cannot be retrieved. +This can happen on filesystems that support +very large attribute values such as NFSv4, for example. +.TP +.B ENOATTR +The named attribute does not exist, or the process has no access to +this attribute. +.RB ( ENOATTR +is defined to be a synonym for +.BR ENODATA +in +.IR .) +.TP +.B ENOTSUP +Extended attributes are not supported by the filesystem, or are disabled. +.TP +.B ERANGE +The +.I size +of the +.I value +buffer is too small to hold the result. +.PP +In addition, the errors documented in +.BR stat (2) +can also occur. +.SH VERSIONS +These system calls have been available on Linux since kernel 2.4; +glibc support is provided since version 2.3. +.SH CONFORMING TO +These system calls are Linux-specific. +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +.SH EXAMPLE +See +.BR listxattr (2). +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR listxattr (2), +.BR open (2), +.BR removexattr (2), +.BR setxattr (2), +.BR stat (2), +.BR symlink (7), +.BR xattr (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/gtty.2 b/man2/gtty.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/gtty.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/idle.2 b/man2/idle.2 new file mode 100644 index 0000000..5c2b2a2 --- /dev/null +++ b/man2/idle.2 @@ -0,0 +1,72 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from linux/mm/swap.c: +.\" Copyright (C) 1991, 1992 Linus Torvalds +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Added text about calling restriction (new in kernel 1.1.20 I believe). +.\" N.B. calling "idle" from user process used to hang process! +.\" Modified Thu Oct 31 14:41:15 1996 by Eric S. Raymond +.\" " +.TH IDLE 2 2012-12-31 "Linux" "Linux Programmer's Manual" +.SH NAME +idle \- make process 0 idle +.SH SYNOPSIS +.B #include +.PP +.B int idle(void); +.SH DESCRIPTION +.BR idle () +is an internal system call used during bootstrap. +It marks the process's pages as swappable, lowers its priority, +and enters the main scheduling loop. +.BR idle () +never returns. +.PP +Only process 0 may call +.BR idle (). +Any user process, even a process with superuser permission, +will receive +.BR EPERM . +.SH RETURN VALUE +.BR idle () +never returns for process 0, and always returns \-1 for a user process. +.SH ERRORS +.TP +.B EPERM +Always, for a user process. +.SH VERSIONS +Since Linux 2.3.13, this system call does not exist anymore. +.SH CONFORMING TO +This function is Linux-specific, and should not be used in programs +intended to be portable. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/inb.2 b/man2/inb.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/inb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/inb_p.2 b/man2/inb_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/inb_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/init_module.2 b/man2/init_module.2 new file mode 100644 index 0000000..4a5d531 --- /dev/null +++ b/man2/init_module.2 @@ -0,0 +1,368 @@ +.\" Copyright (C) 2012 Michael Kerrisk +.\" A few fragments remain from a version +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH INIT_MODULE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +init_module, finit_module \- load a kernel module +.SH SYNOPSIS +.nf +.BI "int init_module(void *" module_image ", unsigned long " len , +.BI " const char *" param_values ); +.PP +.BI "int finit_module(int " fd ", const char *" param_values , +.BI " int " flags ); +.fi +.PP +.IR Note : +glibc provides no header file declaration of +.BR init_module () +and no wrapper function for +.BR finit_module (); +see NOTES. +.SH DESCRIPTION +.BR init_module () +loads an ELF image into kernel space, +performs any necessary symbol relocations, +initializes module parameters to values provided by the caller, +and then runs the module's +.I init +function. +This system call requires privilege. +.PP +The +.I module_image +argument points to a buffer containing the binary image +to be loaded; +.I len +specifies the size of that buffer. +The module image should be a valid ELF image, built for the running kernel. +.PP +The +.I param_values +argument is a string containing space-delimited specifications of the +values for module parameters (defined inside the module using +.BR module_param () +and +.BR module_param_array ()). +The kernel parses this string and initializes the specified +parameters. +Each of the parameter specifications has the form: +.PP +.RI " " name [\c +.BI = value\c +.RB [ ,\c +.IR value ...]] +.PP +The parameter +.I name +is one of those defined within the module using +.IR module_param () +(see the Linux kernel source file +.IR include/linux/moduleparam.h ). +The parameter +.I value +is optional in the case of +.I bool +and +.I invbool +parameters. +Values for array parameters are specified as a comma-separated list. +.SS finit_module() +The +.BR finit_module () +.\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2 +.\" https://lwn.net/Articles/519010/ +system call is like +.BR init_module (), +but reads the module to be loaded from the file descriptor +.IR fd . +It is useful when the authenticity of a kernel module +can be determined from its location in the filesystem; +in cases where that is possible, +the overhead of using cryptographically signed modules to +determine the authenticity of a module can be avoided. +The +.I param_values +argument is as for +.BR init_module (). +.PP +The +.I flags +argument modifies the operation of +.BR finit_module (). +It is a bit mask value created by ORing +together zero or more of the following flags: +.\" commit 2f3238aebedb243804f58d62d57244edec4149b2 +.TP +.B MODULE_INIT_IGNORE_MODVERSIONS +Ignore symbol version hashes. +.TP +.B MODULE_INIT_IGNORE_VERMAGIC +Ignore kernel version magic. +.PP +There are some safety checks built into a module to ensure that +it matches the kernel against which it is loaded. +.\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html +.\" is dated, but informative +These checks are recorded when the module is built and +verified when the module is loaded. +First, the module records a "vermagic" string containing +the kernel version number and prominent features (such as the CPU type). +Second, if the module was built with the +.B CONFIG_MODVERSIONS +configuration option enabled, +a version hash is recorded for each symbol the module uses. +This hash is based on the types of the arguments and return value +for the function named by the symbol. +In this case, the kernel version number within the +"vermagic" string is ignored, +as the symbol version hashes are assumed to be sufficiently reliable. +.PP +Using the +.B MODULE_INIT_IGNORE_VERMAGIC +flag indicates that the "vermagic" string is to be ignored, and the +.B MODULE_INIT_IGNORE_MODVERSIONS +flag indicates that the symbol version hashes are to be ignored. +If the kernel is built to permit forced loading (i.e., configured with +.BR CONFIG_MODULE_FORCE_LOAD ), +then loading continues, otherwise it fails with the error +.B ENOEXEC +as expected for malformed modules. +.SH RETURN VALUE +On success, these system calls return 0. +On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.BR EBADMSG " (since Linux 3.7)" +Module signature is misformatted. +.TP +.B EBUSY +Timeout while trying to resolve a symbol reference by this module. +.TP +.B EFAULT +An address argument referred to a location that +is outside the process's accessible address space. +.TP +.BR ENOKEY " (since Linux 3.7)" +.\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1 +.\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa +.\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7 +Module signature is invalid or +the kernel does not have a key for this module. +This error is returned only if the kernel was configured with +.BR CONFIG_MODULE_SIG_FORCE ; +if the kernel was not configured with this option, +then an invalid or unsigned module simply taints the kernel. +.TP +.B ENOMEM +Out of memory. +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability), +or module loading is disabled +(see +.IR /proc/sys/kernel/modules_disabled +in +.BR proc (5)). +.PP +The following errors may additionally occur for +.BR init_module (): +.TP +.B EEXIST +A module with this name is already loaded. +.TP +.B EINVAL +.I param_values +is invalid, or some part of the ELF image in +.IR module_image +contains inconsistencies. +.\" .TP +.\" .BR EINVAL " (Linux 2.4 and earlier)" +.\" Some +.\" .I image +.\" slot is filled in incorrectly, +.\" .I image\->name +.\" does not correspond to the original module name, some +.\" .I image\->deps +.\" entry does not correspond to a loaded module, +.\" or some other similar inconsistency. +.TP +.B ENOEXEC +The binary image supplied in +.I module_image +is not an ELF image, +or is an ELF image that is invalid or for a different architecture. +.PP +The following errors may additionally occur for +.BR finit_module (): +.TP +.B EBADF +The file referred to by +.I fd +is not opened for reading. +.TP +.B EFBIG +The file referred to by +.I fd +is too large. +.TP +.B EINVAL +.I flags +is invalid. +.TP +.B ENOEXEC +.I fd +does not refer to an open file. +.PP +In addition to the above errors, if the module's +.I init +function is executed and returns an error, then +.BR init_module () +or +.BR finit_module () +fails and +.I errno +is set to the value returned by the +.I init +function. +.SH VERSIONS +.BR finit_module () +is available since Linux 3.8. +.SH CONFORMING TO +.BR init_module () +and +.BR finit_module () +are Linux-specific. +.SH NOTES +The +.BR init_module () +system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it is (before glibc 2.23) sufficient to +manually declare the interface in your code; +alternatively, you can invoke the system call using +.BR syscall (2). +.PP +Glibc does not provide a wrapper for +.BR finit_module (); +call it using +.BR syscall (2). +.PP +Information about currently loaded modules can be found in +.IR /proc/modules +and in the file trees under the per-module subdirectories under +.IR /sys/module . +.PP +See the Linux kernel source file +.I include/linux/module.h +for some useful background information. +.SS Linux 2.4 and earlier +.PP +In Linux 2.4 and earlier, the +.BR init_module () +system call was rather different: +.PP +.B " #include " +.PP +.BI " int init_module(const char *" name ", struct module *" image ); +.PP +(User-space applications can detect which version of +.BR init_module () +is available by calling +.BR query_module (); +the latter call fails with the error +.BR ENOSYS +on Linux 2.6 and later.) +.PP +The older version of the system call +loads the relocated module image pointed to by +.I image +into kernel space and runs the module's +.I init +function. +The caller is responsible for providing the relocated image (since +Linux 2.6, the +.BR init_module () +system call does the relocation). +.PP +The module image begins with a module structure and is followed by +code and data as appropriate. +Since Linux 2.2, the module structure is defined as follows: +.PP +.in +4n +.EX +struct module { + unsigned long size_of_struct; + struct module *next; + const char *name; + unsigned long size; + long usecount; + unsigned long flags; + unsigned int nsyms; + unsigned int ndeps; + struct module_symbol *syms; + struct module_ref *deps; + struct module_ref *refs; + int (*init)(void); + void (*cleanup)(void); + const struct exception_table_entry *ex_table_start; + const struct exception_table_entry *ex_table_end; +#ifdef __alpha__ + unsigned long gp; +#endif +}; +.EE +.in +.PP +All of the pointer fields, with the exception of +.I next +and +.IR refs , +are expected to point within the module body and be +initialized as appropriate for kernel space, that is, relocated with +the rest of the module. +.SH SEE ALSO +.BR create_module (2), +.BR delete_module (2), +.BR query_module (2), +.BR lsmod (8), +.BR modprobe (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/inl.2 b/man2/inl.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/inl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/inl_p.2 b/man2/inl_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/inl_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/inotify_add_watch.2 b/man2/inotify_add_watch.2 new file mode 100644 index 0000000..2bb77ef --- /dev/null +++ b/man2/inotify_add_watch.2 @@ -0,0 +1,132 @@ +.\" Copyright (C) 2005 Robert Love +.\" and Copyright, 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2005-07-19 Robert Love - initial version +.\" 2006-02-07 mtk, various changes +.\" +.TH INOTIFY_ADD_WATCH 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +inotify_add_watch \- add a watch to an initialized inotify instance +.SH SYNOPSIS +.B #include +.PP +.BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask ); +.SH DESCRIPTION +.BR inotify_add_watch () +adds a new watch, or modifies an existing watch, +for the file whose location is specified in +.IR pathname ; +the caller must have read permission for this file. +The +.I fd +argument is a file descriptor referring to the +inotify instance whose watch list is to be modified. +The events to be monitored for +.I pathname +are specified in the +.I mask +bit-mask argument. +See +.BR inotify (7) +for a description of the bits that can be set in +.IR mask . +.PP +A successful call to +.BR inotify_add_watch () +returns a unique watch descriptor for this inotify instance, +for the filesystem object (inode) that corresponds to +.IR pathname . +If the filesystem object +was not previously being watched by this inotify instance, +then the watch descriptor is newly allocated. +If the filesystem object was already being watched +(perhaps via a different link to the same object), then the descriptor +for the existing watch is returned. +.PP +The watch descriptor is returned by later +.BR read (2)s +from the inotify file descriptor. +These reads fetch +.I inotify_event +structures (see +.BR inotify (7)) +indicating filesystem events; +the watch descriptor inside this structure identifies +the object for which the event occurred. +.SH RETURN VALUE +On success, +.BR inotify_add_watch () +returns a nonnegative watch descriptor. +On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Read access to the given file is not permitted. +.TP +.B EBADF +The given file descriptor is not valid. +.TP +.B EFAULT +.I pathname +points outside of the process's accessible address space. +.TP +.B EINVAL +The given event mask contains no valid events; or +.I fd +is not an inotify file descriptor. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The user limit on the total number of inotify watches was reached or the +kernel failed to allocate a needed resource. +.SH VERSIONS +Inotify was merged into the 2.6.13 Linux kernel. +.SH CONFORMING TO +This system call is Linux-specific. +.SH SEE ALSO +.BR inotify_init (2), +.BR inotify_rm_watch (2), +.BR inotify (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/inotify_init.2 b/man2/inotify_init.2 new file mode 100644 index 0000000..cf95d03 --- /dev/null +++ b/man2/inotify_init.2 @@ -0,0 +1,118 @@ +.\" Copyright (C) 2005 Robert Love +.\" and Copyright (C) 2008, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2005-07-19 Robert Love - initial version +.\" 2006-02-07 mtk, minor changes +.\" 2008-10-10 mtk: add description of inotify_init1() +.\" +.TH INOTIFY_INIT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +inotify_init, inotify_init1 \- initialize an inotify instance +.SH SYNOPSIS +.nf +.B #include +.PP +.B "int inotify_init(void);" +.BI "int inotify_init1(int " flags ); +.fi +.SH DESCRIPTION +For an overview of the inotify API, see +.BR inotify (7). +.PP +.BR inotify_init () +initializes a new inotify instance and returns a file descriptor associated +with a new inotify event queue. +.PP +If +.I flags +is 0, then +.BR inotify_init1 () +is the same as +.BR inotify_init (). +The following values can be bitwise ORed in +.IR flags +to obtain different behavior: +.TP 12 +.B IN_NONBLOCK +Set the +.BR O_NONBLOCK +file status flag on the new open file description. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B IN_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.SH RETURN VALUE +On success, these system calls return a new file descriptor. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.RB ( inotify_init1 ()) +An invalid value was specified in +.IR flags . +.TP +.B EMFILE +The user limit on the total number of inotify instances has been reached. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +Insufficient kernel memory is available. +.SH VERSIONS +.BR inotify_init () +first appeared in Linux 2.6.13; +library support was added to glibc in version 2.4. +.BR inotify_init1 () +was added in Linux 2.6.27; +library support was added to glibc in version 2.9. +.SH CONFORMING TO +These system calls are Linux-specific. +.SH SEE ALSO +.BR inotify_add_watch (2), +.BR inotify_rm_watch (2), +.BR inotify (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/inotify_init1.2 b/man2/inotify_init1.2 new file mode 100644 index 0000000..62c5b44 --- /dev/null +++ b/man2/inotify_init1.2 @@ -0,0 +1 @@ +.so man2/inotify_init.2 diff --git a/man2/inotify_rm_watch.2 b/man2/inotify_rm_watch.2 new file mode 100644 index 0000000..b407668 --- /dev/null +++ b/man2/inotify_rm_watch.2 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2005 Robert Love +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2005-07-19 Robert Love - initial version +.\" 2006-02-07 mtk, minor changes +.\" +.TH INOTIFY_RM_WATCH 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +inotify_rm_watch \- remove an existing watch from an inotify instance +.SH SYNOPSIS +.B #include +.PP +.BI "int inotify_rm_watch(int " fd ", int " wd ); +.\" Before glibc 2.10, the second argument was types as uint32_t. +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040 +.SH DESCRIPTION +.BR inotify_rm_watch () +removes the watch associated with the watch descriptor +.I wd +from the inotify instance associated with the file descriptor +.IR fd . +.PP +Removing a watch causes an +.B IN_IGNORED +event to be generated for this watch descriptor. +(See +.BR inotify (7).) +.SH RETURN VALUE +On success, +.BR inotify_rm_watch () +returns zero. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +The watch descriptor +.I wd +is not valid; or +.I fd +is not an inotify file descriptor. +.SH VERSIONS +Inotify was merged into the 2.6.13 Linux kernel. +.SH CONFORMING TO +This system call is Linux-specific. +.SH SEE ALSO +.BR inotify_add_watch (2), +.BR inotify_init (2), +.BR inotify (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/insb.2 b/man2/insb.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/insb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/insl.2 b/man2/insl.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/insl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/insw.2 b/man2/insw.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/insw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/intro.2 b/man2/intro.2 new file mode 100644 index 0000000..6e8be87 --- /dev/null +++ b/man2/intro.2 @@ -0,0 +1,143 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-10-23 mtk: moved the _syscallN specific material to the +.\" new _syscall(2) page, and substantially enhanced and rewrote +.\" the remaining material on this page. +.\" +.TH INTRO 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- introduction to system calls +.SH DESCRIPTION +Section 2 of the manual describes the Linux system calls. +A system call is an entry point into the Linux kernel. +Usually, system calls are not invoked directly: +instead, most system calls have corresponding C library +wrapper functions which perform the steps required +(e.g., trapping to kernel mode) in order to invoke +the system call. +Thus, making a system call looks the same as invoking a normal +library function. +.PP +In many cases, the C library wrapper function does nothing more than: +.IP * 3 +copying arguments and the unique system call number to the +registers where the kernel expects them; +.IP * +trapping to kernel mode, +at which point the kernel does the real work of the system call; +.IP * +setting +.I errno +if the system call returns an error number when the kernel returns the +CPU to user mode. +.PP +However, in a few cases, a wrapper function may do rather more than this, +for example, performing some preprocessing +of the arguments before trapping to kernel mode, +or postprocessing of values returned by the system call. +Where this is the case, the manual pages in Section 2 generally +try to note the details of both the (usually GNU) C library API +interface and the raw system call. +Most commonly, the main DESCRIPTION will focus on the C library interface, +and differences for the system call are covered in the NOTES section. +.PP +For a list of the Linux system calls, see +.BR syscalls (2). +.SH RETURN VALUE +On error, most system calls return a negative error number +(i.e., the negated value of one of the constants described in +.BR errno (3)). +The C library wrapper hides this detail from the caller: when a +system call returns a negative value, the wrapper copies the +absolute value into the +.I errno +variable, and returns \-1 as the return value of the wrapper. +.PP +The value returned by a successful system call depends on the call. +Many system calls return 0 on success, but some can return nonzero +values from a successful call. +The details are described in the individual manual pages. +.PP +In some cases, +the programmer must define a feature test macro in order to obtain +the declaration of a system call from the header file specified +in the man page SYNOPSIS section. +(Where required, these feature test macros must be defined before including +.I any +header files.) +In such cases, the required macro is described in the man page. +For further information on feature test macros, see +.BR feature_test_macros (7). +.SH CONFORMING TO +Certain terms and abbreviations are used to indicate UNIX variants +and standards to which calls in this section conform. +See +.BR standards (7). +.SH NOTES +.SS Calling directly +In most cases, it is unnecessary to invoke a system call directly, +but there are times when the Standard C library does not implement +a nice wrapper function for you. +In this case, the programmer must manually invoke the system call using +.BR syscall (2). +Historically, this was also possible using one of the _syscall macros +described in +.BR _syscall (2). +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.ad l +.nh +.BR _syscall (2), +.BR syscall (2), +.BR syscalls (2), +.BR errno (3), +.BR intro (3), +.BR capabilities (7), +.BR credentials (7), +.BR feature_test_macros (7), +.BR mq_overview (7), +.BR path_resolution (7), +.BR pipe (7), +.BR pty (7), +.BR sem_overview (7), +.BR shm_overview (7), +.BR signal (7), +.BR socket (7), +.BR standards (7), +.BR svipc (7), +.BR symlink (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/inw.2 b/man2/inw.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/inw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/inw_p.2 b/man2/inw_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/inw_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/io_cancel.2 b/man2/io_cancel.2 new file mode 100644 index 0000000..464104c --- /dev/null +++ b/man2/io_cancel.2 @@ -0,0 +1,110 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.TH IO_CANCEL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +io_cancel \- cancel an outstanding asynchronous I/O operation +.SH SYNOPSIS +.nf +.BR "#include " " /* Defines needed types */" +.PP +.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb , +.BI " struct io_event *" result ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.PP +The +.BR io_cancel () +system call +attempts to cancel an asynchronous I/O operation previously submitted with +.BR io_submit (2). +The +.I iocb +argument describes the operation to be canceled and the +.I ctx_id +argument is the AIO context to which the operation was submitted. +If the operation is successfully canceled, the event will be copied into +the memory pointed to by +.I result +without being placed into the +completion queue. +.SH RETURN VALUE +On success, +.BR io_cancel () +returns 0. +For the failure return, see NOTES. +.SH ERRORS +.TP +.B EAGAIN +The \fIiocb\fP specified was not canceled. +.TP +.B EFAULT +One of the data structures points to invalid data. +.TP +.B EINVAL +The AIO context specified by \fIctx_id\fP is invalid. +.TP +.B ENOSYS +.BR io_cancel () +is not implemented on this architecture. +.SH VERSIONS +.PP +The asynchronous I/O system calls first appeared in Linux 2.5. +.SH CONFORMING TO +.PP +.BR io_cancel () +is Linux-specific and should not be used +in programs that are intended to be portable. +.SH NOTES +Glibc does not provide a wrapper function for this system call. +You could invoke it using +.BR syscall (2). +But instead, you probably want to use the +.BR io_cancel () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.PP +Note that the +.I libaio +wrapper function uses a different type +.RI ( io_context_t ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_id +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH SEE ALSO +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR io_submit (2), +.BR aio (7) +.\" .SH AUTHOR +.\" Kent Yoder. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/io_destroy.2 b/man2/io_destroy.2 new file mode 100644 index 0000000..4c77809 --- /dev/null +++ b/man2/io_destroy.2 @@ -0,0 +1,99 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.TH IO_DESTROY 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +io_destroy \- destroy an asynchronous I/O context +.SH SYNOPSIS +.nf +.BR "#include " " /* Defines needed types */" +.PP +.BI "int io_destroy(aio_context_t " ctx_id ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.PP +The +.BR io_destroy () +system call +will attempt to cancel all outstanding asynchronous I/O operations against +.IR ctx_id , +will block on the completion of all operations +that could not be canceled, and will destroy the +.IR ctx_id . +.SH RETURN VALUE +On success, +.BR io_destroy () +returns 0. +For the failure return, see NOTES. +.SH ERRORS +.TP +.B EFAULT +The context pointed to is invalid. +.TP +.B EINVAL +The AIO context specified by \fIctx_id\fP is invalid. +.TP +.B ENOSYS +.BR io_destroy () +is not implemented on this architecture. +.SH VERSIONS +.PP +The asynchronous I/O system calls first appeared in Linux 2.5. +.SH CONFORMING TO +.PP +.BR io_destroy () +is Linux-specific and should not be used in programs +that are intended to be portable. +.SH NOTES +Glibc does not provide a wrapper function for this system call. +You could invoke it using +.BR syscall (2). +But instead, you probably want to use the +.BR io_destroy () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.PP +Note that the +.I libaio +wrapper function uses a different type +.RI ( io_context_t ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_id +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH SEE ALSO +.BR io_cancel (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR io_submit (2), +.BR aio (7) +.\" .SH AUTHOR +.\" Kent Yoder. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/io_getevents.2 b/man2/io_getevents.2 new file mode 100644 index 0000000..cd69255 --- /dev/null +++ b/man2/io_getevents.2 @@ -0,0 +1,143 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.TH IO_GETEVENTS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +io_getevents \- read asynchronous I/O events from the completion queue +.SH SYNOPSIS +.nf +.BR "#include " " /* Defines needed types */" +.BR "#include " " /* Defines 'struct timespec' */" +.PP +.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr , +.BI " struct io_event *" events \ +", struct timespec *" timeout ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.PP +The +.BR io_getevents () +system call +attempts to read at least \fImin_nr\fP events and +up to \fInr\fP events from the completion queue of the AIO context +specified by \fIctx_id\fP. +.PP +The \fItimeout\fP argument specifies the amount of time to wait for events, +and is specified as a relative timeout in a structure of the following form: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds [0 .. 999999999] */ +}; +.EE +.in +.PP +The specified time will be rounded up to the system clock granularity +and is guaranteed not to expire early. +.PP +Specifying +.I timeout +as NULL means block indefinitely until at least +.I min_nr +events have been obtained. +.SH RETURN VALUE +On success, +.BR io_getevents () +returns the number of events read. +This may be 0, or a value less than +.IR min_nr , +if the +.I timeout +expired. +It may also be a nonzero value less than +.IR min_nr , +if the call was interrupted by a signal handler. +.PP +For the failure return, see NOTES. +.SH ERRORS +.TP +.B EFAULT +Either \fIevents\fP or \fItimeout\fP is an invalid pointer. +.TP +.B EINTR +Interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +\fIctx_id\fP is invalid. +\fImin_nr\fP is out of range or \fInr\fP is +out of range. +.TP +.B ENOSYS +.BR io_getevents () +is not implemented on this architecture. +.SH VERSIONS +.PP +The asynchronous I/O system calls first appeared in Linux 2.5. +.SH CONFORMING TO +.PP +.BR io_getevents () +is Linux-specific and should not be used in +programs that are intended to be portable. +.SH NOTES +Glibc does not provide a wrapper function for this system call. +You could invoke it using +.BR syscall (2). +But instead, you probably want to use the +.BR io_getevents () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.PP +Note that the +.I libaio +wrapper function uses a different type +.RI ( io_context_t ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_id +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH BUGS +An invalid +.IR ctx_id +may cause a segmentation fault instead of generating the error +.BR EINVAL . +.SH SEE ALSO +.PP +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_setup (2), +.BR io_submit (2), +.BR aio (7), +.BR time (7) +.\" .SH AUTHOR +.\" Kent Yoder. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/io_setup.2 b/man2/io_setup.2 new file mode 100644 index 0000000..62c8d01 --- /dev/null +++ b/man2/io_setup.2 @@ -0,0 +1,112 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.TH IO_SETUP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +io_setup \- create an asynchronous I/O context +.SH SYNOPSIS +.nf +.BR "#include " " /* Defines needed types */" +.PP +.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.PP +The +.BR io_setup () +system call +creates an asynchronous I/O context suitable for concurrently processing +\fInr_events\fP operations. +The +.I ctx_idp +argument must not point to an AIO context that already exists, and must +be initialized to 0 prior to the call. +On successful creation of the AIO context, \fI*ctx_idp\fP is filled in +with the resulting handle. +.SH RETURN VALUE +On success, +.BR io_setup () +returns 0. +For the failure return, see NOTES. +.SH ERRORS +.TP +.B EAGAIN +The specified \fInr_events\fP exceeds the user's limit of available events, +as defined in +.IR /proc/sys/fs/aio-max-nr . +.TP +.B EFAULT +An invalid pointer is passed for \fIctx_idp\fP. +.TP +.B EINVAL +\fIctx_idp\fP is not initialized, or the specified \fInr_events\fP +exceeds internal limits. +\fInr_events\fP should be greater than 0. +.TP +.B ENOMEM +Insufficient kernel resources are available. +.TP +.B ENOSYS +.BR io_setup () +is not implemented on this architecture. +.SH VERSIONS +.PP +The asynchronous I/O system calls first appeared in Linux 2.5. +.SH CONFORMING TO +.PP +.BR io_setup () +is Linux-specific and should not be used in programs +that are intended to be portable. +.SH NOTES +Glibc does not provide a wrapper function for this system call. +You could invoke it using +.BR syscall (2). +But instead, you probably want to use the +.BR io_setup () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.PP +Note that the +.I libaio +wrapper function uses a different type +.RI ( "io_context_t\ *" ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_idp +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH SEE ALSO +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_submit (2), +.BR aio (7) +.\" .SH AUTHOR +.\" Kent Yoder. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/io_submit.2 b/man2/io_submit.2 new file mode 100644 index 0000000..b0dd517 --- /dev/null +++ b/man2/io_submit.2 @@ -0,0 +1,246 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" and Copyright (C) 2017 Goldwyn Rodrigues +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.TH IO_SUBMIT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +io_submit \- submit asynchronous I/O blocks for processing +.SH SYNOPSIS +.nf +.BR "#include " " /* Defines needed types */" +.PP +.BI "int io_submit(aio_context_t " ctx_id ", long " nr \ +", struct iocb **" iocbpp ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.PP +The +.BR io_submit () +system call +queues \fInr\fP I/O request blocks for processing in +the AIO context \fIctx_id\fP. +The +.I iocbpp +argument should be an array of \fInr\fP AIO control blocks, +which will be submitted to context \fIctx_id\fP. +.PP +The +.I iocb +(I/O control block) structure defined in +.IR linux/aio_abi.h +defines the parameters that control the I/O operation. +.PP +.in +4n +.EX +#include + +struct iocb { + __u64 aio_data; + __u32 PADDED(aio_key, aio_rw_flags); + __u16 aio_lio_opcode; + __s16 aio_reqprio; + __u32 aio_fildes; + __u64 aio_buf; + __u64 aio_nbytes; + __s64 aio_offset; + __u64 aio_reserved2; + __u32 aio_flags; + __u32 aio_resfd; +}; +.EE +.in +.PP +The fields of this structure are as follows: +.TP +.I aio_data +This is an internal field used by the kernel. +Do not modify this field after an +.BR io_submit (2) +call. +.TP +.I aio_key +This is an internal field used by the kernel. +Do not modify this field after an +.BR io_submit (2) +call. +.TP +.I aio_rw_flags +This defines the R/W flags passed with structure. +The valid values are: +.RS +.TP +.B RWF_HIPRI +High priority request, poll if possible +.TP +.B RWF_DSYNC +Write operation complete according to requirement of +synchronized I/O data integrity. +See the description of the flag of the same name in +.BR pwritev2 (2) +as well the description of +.B O_DSYNC +in +.BR open (2). +.TP +.B RWF_SYNC +Write operation complete according to requirement of +synchronized I/O file integrity. +See the description of the flag of the same name in +.BR pwritev2 (2) +as well the description of +.B O_SYNC +in +.BR open (2). +.TP +.B RWF_NOWAIT +Don't wait if the I/O will block for operations such as +file block allocations, dirty page flush, mutex locks, +or a congested block device inside the kernel. +If any of these conditions are met, the control block is returned +immediately with a return value of +.B \-EAGAIN +in the +.I res +field of the +.I io_event +structure (see +.BR io_getevents (2)). +.RE +.TP +.I aio_lio_opcode +This defines the type of I/O to be performed by the iocb structure. +The +valid values are defined by the enum defined in +.IR linux/aio_abi.h : +.IP +.in +4 +.EX +enum { + IOCB_CMD_PREAD = 0, + IOCB_CMD_PWRITE = 1, + IOCB_CMD_FSYNC = 2, + IOCB_CMD_FDSYNC = 3, + IOCB_CMD_NOOP = 6, + IOCB_CMD_PREADV = 7, + IOCB_CMD_PWRITEV = 8, +}; +.EE +.in +.TP +.I aio_reqprio +This defines the requests priority. +.TP +.I aio_filedes +The file descriptor on which the I/O operation is to be performed. +.TP +.I aio_buf +This is the buffer used to transfer data for a read or write operation. +.TP +.I aio_nbytes +This is the size of the buffer pointed to by +.IR aio_buf . +.TP +.I aio_offset +This is the file offset at which the I/O operation is to be performed. +.TP +.I aio_flags +This is the flag to be passed iocb structure. +The only valid value is +.BR IOCB_FLAG_RESFD , +which indicates that the asynchronous I/O control must signal the file +descriptor mentioned in +.I aio_resfd +upon completion. +.TP +.I aio_resfd +The file descriptor to signal in the event of asynchronous I/O completion. +.SH RETURN VALUE +On success, +.BR io_submit () +returns the number of \fIiocb\fPs submitted (which may be +less than \fInr\fP, or 0 if \fInr\fP is zero). +For the failure return, see NOTES. +.SH ERRORS +.TP +.B EAGAIN +Insufficient resources are available to queue any \fIiocb\fPs. +.TP +.B EBADF +The file descriptor specified in the first \fIiocb\fP is invalid. +.TP +.B EFAULT +One of the data structures points to invalid data. +.TP +.B EINVAL +The AIO context specified by \fIctx_id\fP is invalid. +\fInr\fP is less than 0. +The \fIiocb\fP at +.I *iocbpp[0] +is not properly initialized, +or the operation specified is invalid for the file descriptor +in the \fIiocb\fP. +.TP +.B ENOSYS +.BR io_submit () +is not implemented on this architecture. +.SH VERSIONS +.PP +The asynchronous I/O system calls first appeared in Linux 2.5. +.SH CONFORMING TO +.PP +.BR io_submit () +is Linux-specific and should not be used in +programs that are intended to be portable. +.SH NOTES +Glibc does not provide a wrapper function for this system call. +You could invoke it using +.BR syscall (2). +But instead, you probably want to use the +.BR io_submit () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.PP +Note that the +.I libaio +wrapper function uses a different type +.RI ( io_context_t ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_id +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH SEE ALSO +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR aio (7) +.\" .SH AUTHOR +.\" Kent Yoder. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl.2 b/man2/ioctl.2 new file mode 100644 index 0000000..16610ac --- /dev/null +++ b/man2/ioctl.2 @@ -0,0 +1,167 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)ioctl.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1999-06-25 by Rachael Munns +.\" Modified 2000-09-21 by Andries Brouwer +.\" +.TH IOCTL 2 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl \- control device +.SH SYNOPSIS +.B #include +.PP +.BI "int ioctl(int " fd ", unsigned long " request ", ...);" +.\" POSIX says 'request' is int, but glibc has the above +.\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705 +.SH DESCRIPTION +The +.BR ioctl () +system call manipulates the underlying device parameters of special files. +In particular, many operating characteristics of character special files +(e.g., terminals) may be controlled with +.BR ioctl () +requests. +The argument +.I fd +must be an open file descriptor. +.PP +The second argument is a device-dependent request code. +The third argument is an untyped pointer to memory. +It's traditionally +.BI "char *" argp +(from the days before +.B "void *" +was valid C), and will be so named for this discussion. +.PP +An +.BR ioctl () +.I request +has encoded in it whether the argument is an +.I in +parameter or +.I out +parameter, and the size of the argument +.I argp +in bytes. +Macros and defines used in specifying an +.BR ioctl () +.I request +are located in the file +.IR . +.SH RETURN VALUE +Usually, on success zero is returned. +A few +.BR ioctl () +requests use the return value as an output parameter +and return a nonnegative value on success. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP 0.7i +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EFAULT +.I argp +references an inaccessible memory area. +.TP +.B EINVAL +.I request +or +.I argp +is not valid. +.TP +.B ENOTTY +.I fd +is not associated with a character special device. +.TP +.B ENOTTY +The specified request does not apply to the kind of object that the +file descriptor +.I fd +references. +.SH CONFORMING TO +No single standard. +Arguments, returns, and semantics of +.BR ioctl () +vary according to the device driver in question (the call is used as a +catch-all for operations that don't cleanly fit the UNIX stream I/O +model). +See +.BR ioctl_list (2) +for a list of many of the known +.BR ioctl () +calls. +The +.BR ioctl () +system call appeared in Version 7 AT&T UNIX. +.SH NOTES +In order to use this call, one needs an open file descriptor. +Often the +.BR open (2) +call has unwanted side effects, that can be avoided under Linux +by giving it the +.B O_NONBLOCK +flag. +.SH SEE ALSO +.BR execve (2), +.BR fcntl (2), +.BR ioctl_console (2), +.BR ioctl_fat (2), +.BR ioctl_ficlonerange (2), +.BR ioctl_fideduperange (2), +.BR ioctl_getfsmap (2), +.BR ioctl_iflags (2), +.BR ioctl_list (2), +.BR ioctl_ns (2), +.BR ioctl_tty (2), +.BR ioctl_userfaultfd (2), +.BR open (2), +.\" .BR mt (4), +.BR sd (4), +.BR tty (4) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2 new file mode 100644 index 0000000..a9db2c4 --- /dev/null +++ b/man2/ioctl_console.2 @@ -0,0 +1,882 @@ +.\" Copyright (c) 1995 Jim Van Zandt and aeb +.\" Sun Feb 26 11:46:23 MET 1995 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified, Sun Feb 26 15:04:20 1995, faith@cs.unc.edu +.\" Modified, Thu Apr 20 22:08:17 1995, jrv@vanzandt.mv.com +.\" Modified, Mon Sep 18 22:32:47 1995, hpa@storm.net (H. Peter Anvin) +.\" FIXME The following are not documented: +.\" KDFONTOP (since 2.1.111) +.\" KDGKBDIACRUC (since 2.6.24) +.\" KDSKBDIACR +.\" KDSKBDIACRUC (since 2.6.24) +.\" KDKBDREP (since 2.1.113) +.\" KDMAPDISP (not implemented as at 2.6.27) +.\" KDUNMAPDISP (not implemented as at 2.6.27) +.\" VT_LOCKSWITCH (since 1.3.47, needs CAP_SYS_TTY_CONFIG) +.\" VT_UNLOCKSWITCH (since 1.3.47, needs CAP_SYS_TTY_CONFIG) +.\" VT_GETHIFONTMASK (since 2.6.18) +.\" +.TH IOCTL_CONSOLE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_console \- ioctls for console terminal and virtual consoles +.SH DESCRIPTION +The following Linux-specific +.BR ioctl (2) +requests are supported for console terminals and virtual consoles. +Each requires a third argument, assumed here to be +.IR argp . +.TP +.B KDGETLED +Get state of LEDs. +.I argp +points to a +.IR char . +The lower three bits +of +.I *argp +are set to the state of the LEDs, as follows: +.TS +l l l. +LED_CAP 0x04 caps lock led +LED_NUM 0x02 num lock led +LED_SCR 0x01 scroll lock led +.TE +.TP +.B KDSETLED +Set the LEDs. +The LEDs are set to correspond to the lower three bits of the +unsigned long integer in +.IR argp . +However, if a higher order bit is set, +the LEDs revert to normal: displaying the state of the +keyboard functions of caps lock, num lock, and scroll lock. +.PP +Before Linux 1.1.54, the LEDs just reflected the state of the corresponding +keyboard flags, and KDGETLED/KDSETLED would also change the keyboard +flags. +Since Linux 1.1.54 the LEDs can be made to display arbitrary +information, but by default they display the keyboard flags. +The following two ioctls are used to access the keyboard flags. +.TP +.B KDGKBLED +Get keyboard flags CapsLock, NumLock, ScrollLock (not lights). +.I argp +points to a char which is set to the flag state. +The low order three bits (mask 0x7) get the current flag state, +and the low order bits of the next nibble (mask 0x70) get +the default flag state. +(Since Linux 1.1.54.) +.TP +.B KDSKBLED +Set keyboard flags CapsLock, NumLock, ScrollLock (not lights). +.I argp +is an unsigned long integer that has the desired flag state. +The low order three bits (mask 0x7) have the flag state, +and the low order bits of the next nibble (mask 0x70) have +the default flag state. +(Since Linux 1.1.54.) +.TP +.B KDGKBTYPE +Get keyboard type. +This returns the value KB_101, defined as 0x02. +.TP +.B KDADDIO +Add I/O port as valid. +Equivalent to +.IR ioperm(arg,1,1) . +.TP +.B KDDELIO +Delete I/O port as valid. +Equivalent to +.IR ioperm(arg,1,0) . +.TP +.B KDENABIO +Enable I/O to video board. +Equivalent to +.IR "ioperm(0x3b4, 0x3df\-0x3b4+1, 1)" . +.TP +.B KDDISABIO +Disable I/O to video board. +Equivalent to +.IR "ioperm(0x3b4, 0x3df\-0x3b4+1, 0)" . +.TP +.B KDSETMODE +Set text/graphics mode. +.I argp +is an unsigned integer containing one of: +.TS +l l. +KD_TEXT 0x00 +KD_GRAPHICS 0x01 +.TE +.TP +.B KDGETMODE +Get text/graphics mode. +.I argp +points to an +.I int +which is set to one +of the values shown above for +.BR KDSETMODE . +.TP +.B KDMKTONE +Generate tone of specified length. +The lower 16 bits of the unsigned long integer in +.I argp +specify the period in clock cycles, +and the upper 16 bits give the duration in msec. +If the duration is zero, the sound is turned off. +Control returns immediately. +For example, +.I argp += (125<<16) + 0x637 would specify +the beep normally associated with a ctrl-G. +(Thus since Linux 0.99pl1; broken in Linux 2.1.49-50.) +.TP +.B KIOCSOUND +Start or stop sound generation. +The lower 16 bits of +.I argp +specify the period in clock cycles +(that is, +.I argp += 1193180/frequency). +.I argp += 0 turns sound off. +In either case, control returns immediately. +.TP +.B GIO_CMAP +Get the current default color map from kernel. +.I argp +points to +a 48-byte array. +(Since Linux 1.3.3.) +.TP +.B PIO_CMAP +Change the default text-mode color map. +.I argp +points to a +48-byte array which contains, in order, the Red, Green, and Blue +values for the 16 available screen colors: 0 is off, and 255 is full +intensity. +The default colors are, in order: black, dark red, dark +green, brown, dark blue, dark purple, dark cyan, light grey, dark +grey, bright red, bright green, yellow, bright blue, bright purple, +bright cyan and white. +(Since Linux 1.3.3.) +.TP +.B GIO_FONT +Gets 256-character screen font in expanded form. +.I argp +points to an 8192-byte array. +Fails with error code +.B EINVAL +if the +currently loaded font is a 512-character font, or if the console is +not in text mode. +.TP +.B GIO_FONTX +Gets screen font and associated information. +.I argp +points to a +.I "struct consolefontdesc" +(see +.BR PIO_FONTX ). +On call, the +.I charcount +field should be set to the maximum number of +characters that would fit in the buffer pointed to by +.IR chardata . +On return, the +.I charcount +and +.I charheight +are filled with +the respective data for the currently loaded font, and the +.I chardata +array contains the font data if the initial value of +.I charcount +indicated enough space was available; otherwise the +buffer is untouched and +.I errno +is set to +.BR ENOMEM . +(Since Linux 1.3.1.) +.TP +.B PIO_FONT +Sets 256-character screen font. +Load font into the EGA/VGA character +generator. +.I argp +points to an 8192-byte map, with 32 bytes per +character. +Only the first +.I N +of them are used for an 8x\fIN\fP font +(0 < +.I N +<= 32). +This call also invalidates the Unicode mapping. +.TP +.B PIO_FONTX +Sets screen font and associated rendering information. +.I argp +points to a +.IP +.in +4n +.EX +struct consolefontdesc { + unsigned short charcount; /* characters in font + (256 or 512) */ + unsigned short charheight; /* scan lines per + character (1\-32) */ + char *chardata; /* font data in + expanded form */ +}; +.EE +.in +.IP +If necessary, the screen will be appropriately resized, and +.B SIGWINCH +sent to the appropriate processes. +This call also invalidates the Unicode mapping. +(Since Linux 1.3.1.) +.TP +.B PIO_FONTRESET +Resets the screen font, size and Unicode mapping to the bootup +defaults. +.I argp +is unused, but should be set to NULL to +ensure compatibility with future versions of Linux. +(Since Linux 1.3.28.) +.TP +.B GIO_SCRNMAP +Get screen mapping from kernel. +.I argp +points to an area of size +E_TABSZ, which is loaded with the font positions used to display each +character. +This call is likely to return useless information if the +currently loaded font is more than 256 characters. +.TP +.B GIO_UNISCRNMAP +Get full Unicode screen mapping from kernel. +.I argp +points to an +area of size +.IR "E_TABSZ*sizeof(unsigned short)" , +which is loaded with the +Unicodes each character represent. +A special set of Unicodes, +starting at U+F000, are used to represent "direct to font" mappings. +(Since Linux 1.3.1.) +.TP +.B PIO_SCRNMAP +Loads the "user definable" (fourth) table in the kernel which maps +bytes into console screen symbols. +.I argp +points to an area of +size E_TABSZ. +.TP +.B PIO_UNISCRNMAP +Loads the "user definable" (fourth) table in the kernel which maps +bytes into Unicodes, which are then translated into screen symbols +according to the currently loaded Unicode-to-font map. +Special Unicodes starting at U+F000 can be used to map directly to the font +symbols. +(Since Linux 1.3.1.) +.TP +.B GIO_UNIMAP +Get Unicode-to-font mapping from kernel. +.I argp +points to a +.IP +.in +4n +.EX +struct unimapdesc { + unsigned short entry_ct; + struct unipair *entries; +}; +.EE +.in +.IP +where +.I entries +points to an array of +,IP +.in +4n +.EX +struct unipair { + unsigned short unicode; + unsigned short fontpos; +}; +.EE +.in +.IP +(Since Linux 1.1.92.) +.TP +.B PIO_UNIMAP +Put unicode-to-font mapping in kernel. +.I argp +points to a +.IR "struct unimapdesc" . +(Since Linux 1.1.92) +.TP +.B PIO_UNIMAPCLR +Clear table, possibly advise hash algorithm. +.I argp +points to a +.IP +.in +4n +.EX +struct unimapinit { + unsigned short advised_hashsize; /* 0 if no opinion */ + unsigned short advised_hashstep; /* 0 if no opinion */ + unsigned short advised_hashlevel; /* 0 if no opinion */ +}; +.EE +.in +.IP +(Since Linux 1.1.92.) +.TP +.B KDGKBMODE +Gets current keyboard mode. +.I argp +points to a +.I long +which is set to one +of these: +.TS +l l. +K_RAW 0x00 /* Raw (scancode) mode */ +K_XLATE 0x01 /* Translate keycodes using keymap */ +K_MEDIUMRAW 0x02 /* Medium raw (scancode) mode */ +K_UNICODE 0x03 /* Unicode mode */ +K_OFF 0x04 /* Disabled mode; since Linux 2.6.39 */ +.\" K_OFF: commit 9fc3de9c83565fcaa23df74c2fc414bb6e7efb0a +.TE +.TP +.B KDSKBMODE +Sets current keyboard mode. +.I argp +is a +.I long +equal to one of the values shown for +.BR KDGKBMODE . +.TP +.B KDGKBMETA +Gets meta key handling mode. +.I argp +points to a +.I long +which is +set to one of these: +.TS +l l l. +K_METABIT 0x03 set high order bit +K_ESCPREFIX 0x04 escape prefix +.TE +.TP +.B KDSKBMETA +Sets meta key handling mode. +.I argp +is a +.I long +equal to one of the values shown above for +.BR KDGKBMETA . +.TP +.B KDGKBENT +Gets one entry in key translation table (keycode to action code). +.I argp +points to a +.IP +.in +4n +.EX +struct kbentry { + unsigned char kb_table; + unsigned char kb_index; + unsigned short kb_value; +}; +.EE +.in +.IP +with the first two members filled in: +.I kb_table +selects the key table (0 <= +.I kb_table +< MAX_NR_KEYMAPS), +and +.IR kb_index +is the keycode (0 <= +.I kb_index +< NR_KEYS). +.I kb_value +is set to the corresponding action code, +or K_HOLE if there is no such key, +or K_NOSUCHMAP if +.I kb_table +is invalid. +.TP +.B KDSKBENT +Sets one entry in translation table. +.I argp +points to a +.IR "struct kbentry" . +.TP +.B KDGKBSENT +Gets one function key string. +.I argp +points to a +.IP +.in +4n +.EX +struct kbsentry { + unsigned char kb_func; + unsigned char kb_string[512]; +}; +.EE +.in +.IP +.I kb_string +is set to the (null-terminated) string corresponding to +the +.IR kb_func th +function key action code. +.TP +.B KDSKBSENT +Sets one function key string entry. +.I argp +points to a +.IR "struct kbsentry" . +.TP +.B KDGKBDIACR +Read kernel accent table. +.I argp +points to a +.IP +.in +4n +.EX +struct kbdiacrs { + unsigned int kb_cnt; + struct kbdiacr kbdiacr[256]; +}; +.EE +.in +.IP +where +.I kb_cnt +is the number of entries in the array, each of which +is a +.IP +.in +4n +.EX +struct kbdiacr { + unsigned char diacr; + unsigned char base; + unsigned char result; +}; +.EE +.in +.TP +.B KDGETKEYCODE +Read kernel keycode table entry (scan code to keycode). +.I argp +points to a +.IP +.in +4n +.EX +struct kbkeycode { + unsigned int scancode; + unsigned int keycode; +}; +.EE +.in +.IP +.I keycode +is set to correspond to the given +.IR scancode . +(89 <= +.I scancode +<= 255 only. +For 1 <= +.I scancode +<= 88, +.IR keycode == scancode .) +(Since Linux 1.1.63.) +.TP +.B KDSETKEYCODE +Write kernel keycode table entry. +.I argp +points to a +.IR "struct kbkeycode" . +(Since Linux 1.1.63.) +.TP +.B KDSIGACCEPT +The calling process indicates its willingness to accept the signal +.I argp +when it is generated by pressing an appropriate key combination. +(1 <= +.I argp +<= NSIG). +(See +.IR spawn_console () +in +.IR linux/drivers/char/keyboard.c .) +.TP +.B VT_OPENQRY +Returns the first available (non-opened) console. +.I argp +points to an +.I int +which is set to the +number of the vt (1 <= +.I *argp +<= MAX_NR_CONSOLES). +.TP +.B VT_GETMODE +Get mode of active vt. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_mode { + char mode; /* vt mode */ + char waitv; /* if set, hang on writes if not active */ + short relsig; /* signal to raise on release req */ + short acqsig; /* signal to raise on acquisition */ + short frsig; /* unused (set to 0) */ +}; +.EE +.in +.IP +which is set to the mode of the active vt. +.I mode +is set to one of these values: +.TS +l l. +VT_AUTO auto vt switching +VT_PROCESS process controls switching +VT_ACKACQ acknowledge switch +.TE +.TP +.B VT_SETMODE +Set mode of active vt. +.I argp +points to a +.IR "struct vt_mode" . +.TP +.B VT_GETSTATE +Get global vt state info. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_stat { + unsigned short v_active; /* active vt */ + unsigned short v_signal; /* signal to send */ + unsigned short v_state; /* vt bit mask */ +}; +.EE +.in +.IP +For each vt in use, the corresponding bit in the +.I v_state +member is set. +(Kernels 1.0 through 1.1.92.) +.TP +.B VT_RELDISP +Release a display. +.TP +.B VT_ACTIVATE +Switch to vt +.IR argp +(1 <= +.I argp +<= MAX_NR_CONSOLES). +.TP +.B VT_WAITACTIVE +Wait until vt +.I argp +has been activated. +.TP +.B VT_DISALLOCATE +Deallocate the memory associated with vt +.IR argp . +(Since Linux 1.1.54.) +.TP +.B VT_RESIZE +Set the kernel's idea of screensize. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_sizes { + unsigned short v_rows; /* # rows */ + unsigned short v_cols; /* # columns */ + unsigned short v_scrollsize; /* no longer used */ +}; +.EE +.in +.IP +Note that this does not change the videomode. +See +.BR resizecons (8). +(Since Linux 1.1.54.) +.TP +.B VT_RESIZEX +Set the kernel's idea of various screen parameters. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_consize { + unsigned short v_rows; /* number of rows */ + unsigned short v_cols; /* number of columns */ + unsigned short v_vlin; /* number of pixel rows + on screen */ + unsigned short v_clin; /* number of pixel rows + per character */ + unsigned short v_vcol; /* number of pixel columns + on screen */ + unsigned short v_ccol; /* number of pixel columns + per character */ +}; +.EE +.in +.IP +Any parameter may be set to zero, indicating "no change", but if +multiple parameters are set, they must be self-consistent. +Note that this does not change the videomode. +See +.BR resizecons (8). +(Since Linux 1.3.3.) +.PP +The action of the following ioctls depends on the first byte in the struct +pointed to by +.IR argp , +referred to here as the +.IR subcode . +These are legal only for the superuser or the owner of the current terminal. +.TP +.B "TIOCLINUX, subcode=0" +Dump the screen. +Disappeared in Linux 1.1.92. (With kernel 1.1.92 or later, read from +.I /dev/vcsN +or +.I /dev/vcsaN +instead.) +.TP +.B "TIOCLINUX, subcode=1" +Get task information. +Disappeared in Linux 1.1.92. +.TP +.B "TIOCLINUX, subcode=2" +Set selection. +.I argp +points to a +.IP +.in +4n +.EX +struct { + char subcode; + short xs, ys, xe, ye; + short sel_mode; +}; +.EE +.in +.IP +.I xs +and +.I ys +are the starting column and row. +.I xe +and +.I ye +are the ending +column and row. +(Upper left corner is row=column=1.) +.I sel_mode +is 0 for character-by-character selection, +1 for word-by-word selection, +or 2 for line-by-line selection. +The indicated screen characters are highlighted and saved +in the static array sel_buffer in +.IR devices/char/console.c . +.TP +.B "TIOCLINUX, subcode=3" +Paste selection. +The characters in the selection buffer are +written to +.IR fd . +.TP +.B "TIOCLINUX, subcode=4" +Unblank the screen. +.TP +.B "TIOCLINUX, subcode=5" +Sets contents of a 256-bit look up table defining characters in a "word", +for word-by-word selection. +(Since Linux 1.1.32.) +.TP +.B "TIOCLINUX, subcode=6" +.I argp +points to a char which is set to the value of the kernel +variable +.IR shift_state . +(Since Linux 1.1.32.) +.TP +.B "TIOCLINUX, subcode=7" +.I argp +points to a char which is set to the value of the kernel +variable +.IR report_mouse . +(Since Linux 1.1.33.) +.TP +.B "TIOCLINUX, subcode=8" +Dump screen width and height, cursor position, and all the +character-attribute pairs. +(Kernels 1.1.67 through 1.1.91 only. +With kernel 1.1.92 or later, read from +.I /dev/vcsa* +instead.) +.TP +.B "TIOCLINUX, subcode=9" +Restore screen width and height, cursor position, and all the +character-attribute pairs. +(Kernels 1.1.67 through 1.1.91 only. +With kernel 1.1.92 or later, write to +.I /dev/vcsa* +instead.) +.TP +.B "TIOCLINUX, subcode=10" +Handles the Power Saving +feature of the new generation of monitors. +VESA screen blanking mode is set to +.IR argp[1] , +which governs what +screen blanking does: +.RS +.IP 0: 3 +Screen blanking is disabled. +.IP 1: +The current video adapter +register settings are saved, then the controller is programmed to turn off +the vertical synchronization pulses. +This puts the monitor into "standby" mode. +If your monitor has an Off_Mode timer, then +it will eventually power down by itself. +.IP 2: +The current settings are saved, then both the vertical and horizontal +synchronization pulses are turned off. +This puts the monitor into "off" mode. +If your monitor has no Off_Mode timer, +or if you want your monitor to power down immediately when the +blank_timer times out, then you choose this option. +.RI ( Caution: +Powering down frequently will damage the monitor.) +(Since Linux 1.1.76.) +.RE +.SH RETURN VALUE +On success, 0 is returned. +On error, \-1 is returned, and +.I errno +is set. +.SH ERRORS +.I errno +may take on these values: +.TP +.B EBADF +The file descriptor is invalid. +.TP +.B EINVAL +The file descriptor or +.I argp +is invalid. +.TP +.B ENOTTY +The file descriptor is not associated with a character special device, +or the specified request does not apply to it. +.TP +.B EPERM +Insufficient permission. +.SH NOTES +.BR Warning : +Do not regard this man page as documentation of the Linux console ioctls. +This is provided for the curious only, as an alternative to reading the +source. +Ioctl's are undocumented Linux internals, liable to be changed +without warning. +(And indeed, this page more or less describes the +situation as of kernel version 1.1.94; +there are many minor and not-so-minor +differences with earlier versions.) +.PP +Very often, ioctls are introduced for communication between the +kernel and one particular well-known program (fdisk, hdparm, setserial, +tunelp, loadkeys, selection, setfont, etc.), and their behavior will be +changed when required by this particular program. +.PP +Programs using these ioctls will not be portable to other versions +of UNIX, will not work on older versions of Linux, and will not work +on future versions of Linux. +.PP +Use POSIX functions. +.SH SEE ALSO +.BR dumpkeys (1), +.BR kbd_mode (1), +.BR loadkeys (1), +.BR mknod (1), +.BR setleds (1), +.BR setmetamode (1), +.BR execve (2), +.BR fcntl (2), +.BR ioctl_tty (2), +.BR ioperm (2), +.BR termios (3), +.BR console_codes (4), +.BR mt (4), +.BR sd (4), +.BR tty (4), +.BR ttyS (4), +.BR vcs (4), +.BR vcsa (4), +.BR charsets (7), +.BR mapscrn (8), +.BR resizecons (8), +.BR setfont (8) +.PP +.IR /usr/include/linux/kd.h , +.I /usr/include/linux/vt.h +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2 new file mode 100644 index 0000000..beb093a --- /dev/null +++ b/man2/ioctl_fat.2 @@ -0,0 +1,511 @@ +.\" Copyright (C) 2014, Heinrich Schuchardt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume +.\" no responsibility for errors or omissions, or for damages resulting +.\" from the use of the information contained herein. The author(s) may +.\" not have taken the same level of care in the production of this +.\" manual, which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.TH IOCTL-FAT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_fat \- manipulating the FAT filesystem +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t *" attr ); +.BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr ); +.BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id ); +.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH, +.BI " struct __fat_dirent[2] " entry ); +.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT, +.BI " struct __fat_dirent[2] " entry ); +.fi +.SH DESCRIPTION +The +.BR ioctl (2) +system call can be used to read and write metadata of FAT filesystems that +are not accessible using other system calls. +.SS Reading and setting file attributes +Files and directories in the FAT filesystem possess an attribute bit mask that +can be read with +.B FAT_IOCTL_GET_ATTRIBUTES +and written with +.BR FAT_IOCTL_SET_ATTRIBUTES . +.PP +The +.I fd +argument contains a file descriptor for a file or directory. +It is sufficient to create the file descriptor by calling +.BR open (2) +with the +.B O_RDONLY +flag. +.PP +The +.I attr +argument contains a pointer to a bit mask. +The bits of the bit mask are: +.TP +.B ATTR_RO +This bit specifies that the file or directory is read-only. +.TP +.B ATTR_HIDDEN +This bit specifies that the file or directory is hidden. +.TP +.B ATTR_SYS +This bit specifies that the file is a system file. +.TP +.B ATTR_VOLUME +This bit specifies that the file is a volume label. +This attribute is read-only. +.TP +.B ATTR_DIR +This bit specifies that this is a directory. +This attribute is read-only. +.TP +.B ATTR_ARCH +This bit indicates that this file or directory should be archived. +It is set when a file is created or modified. +It is reset by an archiving system. +.PP +The zero value +.B ATTR_NONE +can be used to indicate that no attribute bit is set. +.SS Reading the volume ID +FAT filesystems are identified by a volume ID. +The volume ID can be read with +.BR FAT_IOCTL_GET_VOLUME_ID . +.PP +The +.I fd +argument can be a file descriptor for any file or directory of the +filesystem. +It is sufficient to create the file descriptor by calling +.BR open (2) +with the +.B O_RDONLY +flag. +.PP +The +.I id +argument is a pointer to the field that will be filled with the volume ID. +Typically the volume ID is displayed to the user as a group of two +16-bit fields: +.PP +.in +4n +.EX +printf("Volume ID %04x-%04x\\n", id >> 16, id & 0xFFFF); +.EE +.in +.SS Reading short file names of a directory +A file or directory on a FAT filesystem always has a short filename +consisting of up to 8 capital letters, optionally followed by a period +and up to 3 capital letters for the file extension. +If the actual filename does not fit into this scheme, it is stored +as a long filename of up to 255 UTF-16 characters. +.PP +The short filenames in a directory can be read with +.BR VFAT_IOCTL_READDIR_SHORT . +.B VFAT_IOCTL_READDIR_BOTH +reads both the short and the long filenames. +.PP +The +.I fd +argument must be a file descriptor for a directory. +It is sufficient to create the file descriptor by calling +.BR open (2) +with the +.B O_RDONLY +flag. +The file descriptor can be used only once to iterate over the directory +entries by calling +.BR ioctl (2) +repeatedly. +.PP +The +.I entry +argument is a two-element array of the following structures: +.PP +.in +4n +.EX +struct __fat_dirent { + long d_ino; + __kernel_off_t d_off; + uint32_t short d_reclen; + char d_name[256]; +}; +.EE +.in +.PP +The first entry in the array is for the short filename. +The second entry is for the long filename. +.PP +The +.I d_ino +and +.I d_off +fields are filled only for long filenames. +The +.I d_ino +field holds the inode number of the directory. +The +.I d_off +field holds the offset of the file entry in the directory. +As these values are not available for short filenames, the user code should +simply ignore them. +.PP +The field +.I d_reclen +contains the length of the filename in the field +.IR d_name . +To keep backward compatibility, a length of 0 for the short filename signals +that the end of the directory has been reached. +However, the preferred method for detecting the end of the directory +is to test the +.BR ioctl (2) +return value. +If no long filename exists, field +.I d_reclen +is set to 0 and +.I d_name +is a character string of length 0 for the long filename. +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.PP +For +.B VFAT_IOCTL_READDIR_BOTH +and +.B VFAT_IOCTL_READDIR_SHORT +a return value of 1 signals that a new directory entry has been read and +a return value of 0 signals that the end of the directory has been reached. +.SH ERRORS +.TP +.B ENOENT +This error is returned by +.B VFAT_IOCTL_READDIR_BOTH +and +.B VFAT_IOCTL_READDIR_SHORT +if the file descriptor +.I fd +refers to a removed, but still open directory. +.TP +.B ENOTDIR +This error is returned by +.B VFAT_IOCTL_READDIR_BOTH +and +.B VFAT_IOCTL_READDIR_SHORT +if the file descriptor +.I fd +does not refer to a directory. +.TP +.B ENOTTY +The file descriptor +.I fd +does not refer to an object in a FAT filesystem. +.PP +For further error values, see +.BR ioctl (2). +.SH VERSIONS +.BR VFAT_IOCTL_READDIR_BOTH +and +.B VFAT_IOCTL_READDIR_SHORT +first appeared in Linux 2.0. +.PP +.BR FAT_IOCTL_GET_ATTRIBUTES +and +.BR FAT_IOCTL_SET_ATTRIBUTES +first appeared +.\" just before we got Git history +in Linux 2.6.12. +.PP +.B FAT_IOCTL_GET_VOLUME_ID +was introduced in version 3.11 +.\" commit 6e5b93ee55d401f1619092fb675b57c28c9ed7ec +of the Linux kernel. +.SH CONFORMING TO +This API is Linux-specific. +.SH EXAMPLE +.SS Toggling the archive flag +The following program demonstrates the usage of +.BR ioctl (2) +to manipulate file attributes. +The program reads and displays the archive attribute of a file. +After inverting the value of the attribute, +the program reads and displays the attribute again. +.PP +The following was recorded when applying the program for the file +.IR /mnt/user/foo : +.PP +.in +4n +.EX +# ./toggle_fat_archive_flag /mnt/user/foo +Archive flag is set +Toggling archive flag +Archive flag is not set +.EE +.in +.SS Program source (toggle_fat_archive_flag.c) +\& +.EX +#include +#include +#include +#include +#include +#include +#include + +/* + * Read file attributes of a file on a FAT filesystem. + * Output the state of the archive flag. + */ +static uint32_t +readattr(int fd) +{ + uint32_t attr; + int ret; + + ret = ioctl(fd, FAT_IOCTL_GET_ATTRIBUTES, &attr); + if (ret == \-1) { + perror("ioctl"); + exit(EXIT_FAILURE); + } + + if (attr & ATTR_ARCH) + printf("Archive flag is set\\n"); + else + printf("Archive flag is not set\\n"); + + return attr; +} + +int +main(int argc, char *argv[]) +{ + uint32_t attr; + int fd; + int ret; + + if (argc != 2) { + printf("Usage: %s FILENAME\\n", argv[0]); + exit(EXIT_FAILURE); + } + + fd = open(argv[1], O_RDONLY); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } + + /* + * Read and display the FAT file attributes. + */ + attr = readattr(fd); + + /* + * Invert archive attribute. + */ + printf("Toggling archive flag\\n"); + attr ^= ATTR_ARCH; + + /* + * Write the changed FAT file attributes. + */ + ret = ioctl(fd, FAT_IOCTL_SET_ATTRIBUTES, &attr); + if (ret == \-1) { + perror("ioctl"); + exit(EXIT_FAILURE); + } + + /* + * Read and display the FAT file attributes. + */ + readattr(fd); + + close(fd); + + exit(EXIT_SUCCESS); +} +.EE +.\" +.SS Reading the volume ID +The following program demonstrates the use of +.BR ioctl (2) +to display the volume ID of a FAT filesystem. +.PP +The following output was recorded when applying the program for +directory +.IR /mnt/user : +.PP +.in +4n +.EX +$ ./display_fat_volume_id /mnt/user +Volume ID 6443-6241 +.EE +.in +.SS Program source (display_fat_volume_id.c) +\& +.EX +#include +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + uint32_t id; + int fd; + int ret; + + if (argc != 2) { + printf("Usage: %s FILENAME\\n", argv[0]); + exit(EXIT_FAILURE); + } + + fd = open(argv[1], O_RDONLY); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } + + /* + * Read volume ID. + */ + ret = ioctl(fd, FAT_IOCTL_GET_VOLUME_ID, &id); + if (ret == \-1) { + perror("ioctl"); + exit(EXIT_FAILURE); + } + + /* + * Format the output as two groups of 16 bits each. + */ + printf("Volume ID %04x\-%04x\\n", id >> 16, id & 0xFFFF); + + close(fd); + + exit(EXIT_SUCCESS); +} +.EE +.\" +.SS Listing a directory +The following program demonstrates the use of +.BR ioctl (2) +to list a directory. +.PP +The following was recorded when applying the program to the directory +.IR /mnt/user : +.PP +.in +4n +.EX +$ \fB./fat_dir /mnt/user\fP +\[char46] -> '' +\[char46]. -> '' +ALONGF~1.TXT -> 'a long filename.txt' +UPPER.TXT -> '' +LOWER.TXT -> 'lower.txt' +.EE +.in +.\" +.SS Program source +.in +4n +.EX +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct __fat_dirent entry[2]; + int fd; + int ret; + + if (argc != 2) { + printf("Usage: %s DIRECTORY\\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* + * Open file descriptor for the directory. + */ + fd = open(argv[1], O_RDONLY | O_DIRECTORY); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } + + for (;;) { + + /* + * Read next directory entry. + */ + ret = ioctl( fd, VFAT_IOCTL_READDIR_BOTH, entry); + + /* + * If an error occurs, the return value is \-1. + * If the end of the directory list has been reached, + * the return value is 0. + * For backward compatibility the end of the directory + * list is also signaled by d_reclen == 0. + */ + if (ret < 1) + break; + + /* + * Write both the short name and the long name. + */ + printf("%s \-> '%s'\\n", entry[0].d_name, entry[1].d_name); + } + + if (ret == \-1) { + perror("VFAT_IOCTL_READDIR_BOTH"); + exit(EXIT_FAILURE); + } + + /* + * Close the file descriptor. + */ + close(fd); + + exit(EXIT_SUCCESS); +} +.EE +.in +.SH SEE ALSO +.BR ioctl (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_ficlone.2 b/man2/ioctl_ficlone.2 new file mode 100644 index 0000000..19bb348 --- /dev/null +++ b/man2/ioctl_ficlone.2 @@ -0,0 +1 @@ +.so man2/ioctl_ficlonerange.2 diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2 new file mode 100644 index 0000000..ddce937 --- /dev/null +++ b/man2/ioctl_ficlonerange.2 @@ -0,0 +1,154 @@ +.\" Copyright (c) 2016, Oracle. All rights reserved. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH IOCTL-FICLONERANGE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file +.SH SYNOPSIS +.br +.B #include +.br +.B #include +.PP +.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg ); +.br +.BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd ); +.SH DESCRIPTION +If a filesystem supports files sharing physical storage between multiple +files ("reflink"), this +.BR ioctl (2) +operation can be used to make some of the data in the +.I src_fd +file appear in the +.I dest_fd +file by sharing the underlying storage, which is faster than making a separate +physical copy of the data. +Both files must reside within the same filesystem. +If a file write should occur to a shared region, +the filesystem must ensure that the changes remain private to the file being +written. +This behavior is commonly referred to as "copy on write". +.PP +This ioctl reflinks up to +.IR src_length +bytes from file descriptor +.IR src_fd +at offset +.IR src_offset +into the file +.IR dest_fd +at offset +.IR dest_offset ", +provided that both are files. +If +.IR src_length +is zero, the ioctl reflinks to the end of the source file. +This information is conveyed in a structure of +the following form: +.PP +.in +4n +.EX +struct file_clone_range { + __s64 src_fd; + __u64 src_offset; + __u64 src_length; + __u64 dest_offset; +}; +.EE +.in +.PP +Clones are atomic with regards to concurrent writes, so no locks need to be +taken to obtain a consistent cloned copy. +.PP +The +.B FICLONE +ioctl clones entire files. +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.PP +.SH ERRORS +Error codes can be one of, but are not limited to, the following: +.TP +.B EBADF +.IR src_fd +is not open for reading; +.IR dest_fd +is not open for writing or is open for append-only writes; +or the filesystem which +.IR src_fd +resides on does not support reflink. +.TP +.B EINVAL +The filesystem does not support reflinking the ranges of the given files. +This error can also appear if either file descriptor represents +a device, FIFO, or socket. +Disk filesystems generally require the offset and length arguments +to be aligned to the fundamental block size. +XFS and Btrfs do not support +overlapping reflink ranges in the same file. +.TP +.B EISDIR +One of the files is a directory and the filesystem does not support shared +regions in directories. +.TP +.B EOPNOTSUPP +This can appear if the filesystem does not support reflinking either file +descriptor, or if either file descriptor refers to special inodes. +.TP +.B EPERM +.IR dest_fd +is immutable. +.TP +.B ETXTBSY +One of the files is a swap file. +Swap files cannot share storage. +.TP +.B EXDEV +.IR dest_fd " and " src_fd +are not on the same mounted filesystem. +.SH VERSIONS +These ioctl operations first appeared in Linux 4.5. +They were previously known as +.B BTRFS_IOC_CLONE +and +.BR BTRFS_IOC_CLONE_RANGE , +and were private to Btrfs. +.SH CONFORMING TO +This API is Linux-specific. +.SH NOTES +Because a copy-on-write operation requires the allocation of new storage, the +.BR fallocate (2) +operation may unshare shared blocks to guarantee that subsequent writes will +not fail because of lack of disk space. +.SH SEE ALSO +.BR ioctl (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2 new file mode 100644 index 0000000..9130bde --- /dev/null +++ b/man2/ioctl_fideduperange.2 @@ -0,0 +1,223 @@ +.\" Copyright (c) 2016, Oracle. All rights reserved. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH IOCTL-FIDEDUPERANGE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_fideduperange \- share some the data of one file with another file +.SH SYNOPSIS +.br +.B #include +.br +.B #include +.PP +.BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg ); +.SH DESCRIPTION +If a filesystem supports files sharing physical storage between multiple +files, this +.BR ioctl (2) +operation can be used to make some of the data in the +.B src_fd +file appear in the +.B dest_fd +file by sharing the underlying storage if the file data is identical +("deduplication"). +Both files must reside within the same filesystem. +This reduces storage consumption by allowing the filesystem +to store one shared copy of the data. +If a file write should occur to a shared +region, the filesystem must ensure that the changes remain private to the file +being written. +This behavior is commonly referred to as "copy on write". +.PP +This ioctl performs the "compare and share if identical" operation on up to +.IR src_length +bytes from file descriptor +.IR src_fd +at offset +.IR src_offset ". +This information is conveyed in a structure of the following form: +.PP +.in +4n +.EX +struct file_dedupe_range { + __u64 src_offset; + __u64 src_length; + __u16 dest_count; + __u16 reserved1; + __u32 reserved2; + struct file_dedupe_range_info info[0]; +}; +.EE +.in +.PP +Deduplication is atomic with regards to concurrent writes, so no locks need to +be taken to obtain a consistent deduplicated copy. +.PP +The fields +.IR reserved1 " and " reserved2 +must be zero. +.PP +Destinations for the deduplication operation are conveyed in the array at the +end of the structure. +The number of destinations is given in +.IR dest_count ", +and the destination information is conveyed in the following form: +.PP +.in +4n +.EX +struct file_dedupe_range_info { + __s64 dest_fd; + __u64 dest_offset; + __u64 bytes_deduped; + __s32 status; + __u32 reserved; +}; +.EE +.in +.PP +Each deduplication operation targets +.IR src_length +bytes in file descriptor +.IR dest_fd +at offset +.IR dest_offset ". +The field +.IR reserved +must be zero. +During the call, +.IR src_fd +must be open for reading and +.IR dest_fd +must be open for writing. +The combined size of the struct +.IR file_dedupe_range +and the struct +.IR file_dedupe_range_info +array must not exceed the system page size. +The maximum size of +.IR src_length +is filesystem dependent and is typically 16\ MiB. +This limit will be enforced silently by the filesystem. +By convention, the storage used by +.IR src_fd +is mapped into +.IR dest_fd +and the previous contents in +.IR dest_fd +are freed. +.PP +Upon successful completion of this ioctl, the number of bytes successfully +deduplicated is returned in +.IR bytes_deduped +and a status code for the deduplication operation is returned in +.IR status ". +If even a single byte in the range does not match, the deduplication +request will be ignored and +.IR status +set to +.BR FILE_DEDUPE_RANGE_DIFFERS . +The +.IR status +code is set to +.B FILE_DEDUPE_RANGE_SAME +for success, a negative error code in case of error, or +.B FILE_DEDUPE_RANGE_DIFFERS +if the data did not match. +.PP +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.PP +.SH ERRORS +Error codes can be one of, but are not limited to, the following: +.TP +.B ENOMEM +The kernel was unable to allocate sufficient memory to perform the +operation or +.IR dest_count +is so large that the input argument description spans more than a single +page of memory. +.TP +.B EBADF +.IR src_fd +is not open for reading; +.IR dest_fd +is not open for writing or is open for append-only writes; or the filesystem +which +.IR src_fd +resides on does not support deduplication. +.TP +.B EINVAL +The filesystem does not support deduplicating the ranges of the given files. +This error can also appear if either file descriptor represents +a device, FIFO, or socket. +Disk filesystems generally require the offset and length arguments +to be aligned to the fundamental block size. +Neither Btrfs nor XFS support +overlapping deduplication ranges in the same file. +.TP +.B EISDIR +One of the files is a directory and the filesystem does not support shared +regions in directories. +.TP +.B EOPNOTSUPP +This can appear if the filesystem does not support deduplicating either file +descriptor, or if either file descriptor refers to special inodes. +.TP +.B EPERM +.IR dest_fd +is immutable. +.TP +.B ETXTBSY +One of the files is a swap file. +Swap files cannot share storage. +.TP +.B EXDEV +.IR dest_fd " and " src_fd +are not on the same mounted filesystem. +.SH VERSIONS +This ioctl operation first appeared in Linux 4.5. +It was previously known as +.B BTRFS_IOC_FILE_EXTENT_SAME +and was private to Btrfs. +.SH CONFORMING TO +This API is Linux-specific. +.SH NOTES +Because a copy-on-write operation requires the allocation of new storage, the +.BR fallocate (2) +operation may unshare shared blocks to guarantee that subsequent writes will +not fail because of lack of disk space. +.PP +Some filesystems may limit the amount of data that can be deduplicated in a +single call. +.SH SEE ALSO +.BR ioctl (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2 new file mode 100644 index 0000000..8021761 --- /dev/null +++ b/man2/ioctl_getfsmap.2 @@ -0,0 +1,382 @@ +.\" Copyright (c) 2017, Oracle. All rights reserved. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH IOCTL_GETFSMAP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_getfsmap \- retrieve the physical layout of the filesystem +.SH SYNOPSIS +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg ); +.SH DESCRIPTION +This +.BR ioctl (2) +operation retrieves physical extent mappings for a filesystem. +This information can be used to discover which files are mapped to a physical +block, examine free space, or find known bad blocks, among other things. +.PP +The sole argument to this operation should be a pointer to a single +.IR "struct fsmap_head" ":" +.PP +.in +4n +.EX +struct fsmap { + __u32 fmr_device; /* Device ID */ + __u32 fmr_flags; /* Mapping flags */ + __u64 fmr_physical; /* Device offset of segment */ + __u64 fmr_owner; /* Owner ID */ + __u64 fmr_offset; /* File offset of segment */ + __u64 fmr_length; /* Length of segment */ + __u64 fmr_reserved[3]; /* Must be zero */ +}; + +struct fsmap_head { + __u32 fmh_iflags; /* Control flags */ + __u32 fmh_oflags; /* Output flags */ + __u32 fmh_count; /* # of entries in array incl. input */ + __u32 fmh_entries; /* # of entries filled in (output) */ + __u64 fmh_reserved[6]; /* Must be zero */ + + struct fsmap fmh_keys[2]; /* Low and high keys for + the mapping search */ + struct fsmap fmh_recs[]; /* Returned records */ +}; +.EE +.in +.PP +The two +.I fmh_keys +array elements specify the lowest and highest reverse-mapping +key for which the application would like physical mapping +information. +A reverse mapping key consists of the tuple (device, block, owner, offset). +The owner and offset fields are part of the key because some filesystems +support sharing physical blocks between multiple files and +therefore may return multiple mappings for a given physical block. +.PP +Filesystem mappings are copied into the +.I fmh_recs +array, which immediately follows the header data. +.\" +.SS Fields of struct fsmap_head +.PP +The +.I fmh_iflags +field is a bit mask passed to the kernel to alter the output. +No flags are currently defined, so the caller must set this value to zero. +.PP +The +.I fmh_oflags +field is a bit mask of flags set by the kernel concerning the returned mappings. +If +.B FMH_OF_DEV_T +is set, then the +.I fmr_device +field represents a +.I dev_t +structure containing the major and minor numbers of the block device. +.PP +The +.I fmh_count +field contains the number of elements in the array being passed to the +kernel. +If this value is 0, +.I fmh_entries +will be set to the number of records that would have been returned had +the array been large enough; +no mapping information will be returned. +.PP +The +.I fmh_entries +field contains the number of elements in the +.I fmh_recs +array that contain useful information. +.PP +The +.I fmh_reserved +fields must be set to zero. +.\" +.SS Keys +.PP +The two key records in +.I fsmap_head.fmh_keys +specify the lowest and highest extent records in the keyspace that the caller +wants returned. +A filesystem that can share blocks between files likely requires the tuple +.RI "(" "device" ", " "physical" ", " "owner" ", " "offset" ", " "flags" ")" +to uniquely index any filesystem mapping record. +Classic non-sharing filesystems might be able to identify any record with only +.RI "(" "device" ", " "physical" ", " "flags" ")." +For example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem will +only return records for extents starting at or above 36\ KiB on disk. +If the high key is set to (8:0, 1048576, 0, 0, 0), only records below 1\ MiB will +be returned. +The format of +.I fmr_device +in the keys must match the format of the same field in the output records, +as defined below. +By convention, the field +.I fsmap_head.fmh_keys[0] +must contain the low key and +.I fsmap_head.fmh_keys[1] +must contain the high key for the request. +.PP +For convenience, if +.I fmr_length +is set in the low key, it will be added to +.IR fmr_block " or " fmr_offset +as appropriate. +The caller can take advantage of this subtlety to set up subsequent calls +by copying +.I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1] +into the low key. +The function +.I fsmap_advance +(defined in +.IR linux/fsmap.h ) +provides this functionality. +.\" +.SS Fields of struct fsmap +.PP +The +.I fmr_device +field uniquely identifies the underlying storage device. +If the +.B FMH_OF_DEV_T +flag is set in the header's +.I fmh_oflags +field, this field contains a +.I dev_t +from which major and minor numbers can be extracted. +If the flag is not set, this field contains a value that must be unique +for each unique storage device. +.PP +The +.I fmr_physical +field contains the disk address of the extent in bytes. +.PP +The +.I fmr_owner +field contains the owner of the extent. +This is an inode number unless +.B FMR_OF_SPECIAL_OWNER +is set in the +.I fmr_flags +field, in which case the value is determined by the filesystem. +See the section below about owner values for more details. +.PP +The +.I fmr_offset +field contains the logical address in the mapping record in bytes. +This field has no meaning if the +.BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP +flags are set in +.IR fmr_flags "." +.PP +The +.I fmr_length +field contains the length of the extent in bytes. +.PP +The +.I fmr_flags +field is a bit mask of extent state flags. +The bits are: +.RS 0.4i +.TP +.B FMR_OF_PREALLOC +The extent is allocated but not yet written. +.TP +.B FMR_OF_ATTR_FORK +This extent contains extended attribute data. +.TP +.B FMR_OF_EXTENT_MAP +This extent contains extent map information for the owner. +.TP +.B FMR_OF_SHARED +Parts of this extent may be shared. +.TP +.B FMR_OF_SPECIAL_OWNER +The +.I fmr_owner +field contains a special value instead of an inode number. +.TP +.B FMR_OF_LAST +This is the last record in the data set. +.RE +.PP +The +.I fmr_reserved +field will be set to zero. +.\" +.SS Owner values +Generally, the value of the +.I fmr_owner +field for non-metadata extents should be an inode number. +However, filesystems are under no obligation to report inode numbers; +they may instead report +.B FMR_OWN_UNKNOWN +if the inode number cannot easily be retrieved, if the caller lacks +sufficient privilege, if the filesystem does not support stable +inode numbers, or for any other reason. +If a filesystem wishes to condition the reporting of inode numbers based +on process capabilities, it is strongly urged that the +.B CAP_SYS_ADMIN +capability be used for this purpose. +.TP +The following special owner values are generic to all filesystems: +.RS 0.4i +.TP +.B FMR_OWN_FREE +Free space. +.TP +.B FMR_OWN_UNKNOWN +This extent is in use but its owner is not known or not easily retrieved. +.TP +.B FMR_OWN_METADATA +This extent is filesystem metadata. +.RE +.PP +XFS can return the following special owner values: +.RS 0.4i +.TP +.B XFS_FMR_OWN_FREE +Free space. +.TP +.B XFS_FMR_OWN_UNKNOWN +This extent is in use but its owner is not known or not easily retrieved. +.TP +.B XFS_FMR_OWN_FS +Static filesystem metadata which exists at a fixed address. +These are the AG superblock, the AGF, the AGFL, and the AGI headers. +.TP +.B XFS_FMR_OWN_LOG +The filesystem journal. +.TP +.B XFS_FMR_OWN_AG +Allocation group metadata, such as the free space btrees and the +reverse mapping btrees. +.TP +.B XFS_FMR_OWN_INOBT +The inode and free inode btrees. +.TP +.B XFS_FMR_OWN_INODES +Inode records. +.TP +.B XFS_FMR_OWN_REFC +Reference count information. +.TP +.B XFS_FMR_OWN_COW +This extent is being used to stage a copy-on-write. +.TP +.B XFS_FMR_OWN_DEFECTIVE: +This extent has been marked defective either by the filesystem or the +underlying device. +.RE +.PP +ext4 can return the following special owner values: +.RS 0.4i +.TP +.B EXT4_FMR_OWN_FREE +Free space. +.TP +.B EXT4_FMR_OWN_UNKNOWN +This extent is in use but its owner is not known or not easily retrieved. +.TP +.B EXT4_FMR_OWN_FS +Static filesystem metadata which exists at a fixed address. +This is the superblock and the group descriptors. +.TP +.B EXT4_FMR_OWN_LOG +The filesystem journal. +.TP +.B EXT4_FMR_OWN_INODES +Inode records. +.TP +.B EXT4_FMR_OWN_BLKBM +Block bit map. +.TP +.B EXT4_FMR_OWN_INOBM +Inode bit map. +.RE +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.PP +.SH ERRORS +The error placed in +.I errno +can be one of, but is not limited to, the following: +.TP +.B EBADF +.IR fd +is not open for reading. +.TP +.B EBADMSG +The filesystem has detected a checksum error in the metadata. +.TP +.B EFAULT +The pointer passed in was not mapped to a valid memory address. +.TP +.B EINVAL +The array is not long enough, the keys do not point to a valid part of +the filesystem, the low key points to a higher point in the filesystem's +physical storage address space than the high key, or a nonzero value +was passed in one of the fields that must be zero. +.TP +.B ENOMEM +Insufficient memory to process the request. +.TP +.B EOPNOTSUPP +The filesystem does not support this command. +.TP +.B EUCLEAN +The filesystem metadata is corrupt and needs repair. +.SH VERSIONS +The +.B FS_IOC_GETFSMAP +operation first appeared in Linux 4.12. +.SH CONFORMING TO +This API is Linux-specific. +Not all filesystems support it. +.SH EXAMPLE +See +.I io/fsmap.c +in the +.I xfsprogs +distribution for a sample program. +.SH SEE ALSO +.BR ioctl (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_iflags.2 b/man2/ioctl_iflags.2 new file mode 100644 index 0000000..1c31e44 --- /dev/null +++ b/man2/ioctl_iflags.2 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH IOCTL_IFLAGS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_iflags \- ioctl() operations for inode flags +.SH DESCRIPTION +Various Linux filesystems support the notion of +.IR "inode flags" \(emattributes +that modify the semantics of files and directories. +These flags can be retrieved and modified using two +.BR ioctl (2) +operations: +.PP +.in +4n +.EX +int attr; +fd = open("pathname", ...); + +ioctl(fd, FS_IOC_GETFLAGS, &attr); /* Place current flags + in \(aqattr\(aq */ +attr |= FS_NOATIME_FL; /* Tweak returned bit mask */ +ioctl(fd, FS_IOC_SETFLAGS, &attr); /* Update flags for inode + referred to by \(aqfd\(aq */ +.EE +.in +.PP +The +.BR lsattr (1) +and +.BR chattr (1) +shell commands provide interfaces to these two operations, +allowing a user to view and modify the inode flags associated with a file. +.PP +The following flags are supported +(shown along with the corresponding letter used to indicate the flag by +.BR lsattr (1) +and +.BR chattr (1)): +.TP +.BR FS_APPEND_FL " \(aqa\(aq" +The file can be opened only with the +.B O_APPEND +flag. +(This restriction applies even to the superuser.) +Only a privileged process +.RB ( CAP_LINUX_IMMUTABLE ) +can set or clear this attribute. +.TP +.BR FS_COMPR_FL " \(aqc\(aq" +Store the file in a compressed format on disk. +This flag is +.I not +supported by most of the mainstream filesystem implementations; +one exception is +.BR btrfs (5). +.TP +.BR FS_DIRSYNC_FL " \(aqD\(aq (since Linux 2.6.0)" +Write directory changes synchronously to disk. +This flag provides semantics equivalent to the +.BR mount (2) +.B MS_DIRSYNC +option, but on a per-directory basis. +This flag can be applied only to directories. +.\" .TP +.\" .BR FS_EXTENT_FL " \(aqe\(aq" +.\" FIXME Some support on ext4? (EXT4_EXTENTS_FL) +.TP +.BR FS_IMMUTABLE_FL " \(aqi\(aq" +The file is immutable: +no changes are permitted to the file contents or metadata +(permissions, timestamps, ownership, link count and so on). +(This restriction applies even to the superuser.) +Only a privileged process +.RB ( CAP_LINUX_IMMUTABLE ) +can set or clear this attribute. +.TP +.BR FS_JOURNAL_DATA_FL " \(aqj\(aq" +Enable journaling of file data on +.BR ext3 (5) +and +.BR ext4 (5) +filesystems. +On a filesystem that is journaling in +.I ordered +or +.I writeback +mode, a privileged +.RB ( CAP_SYS_RESOURCE ) +process can set this flag to enable journaling of data updates on +a per-file basis. +.TP +.BR FS_NOATIME_FL " \(aqA\(aq" +Don't update the file last access time when the file is accessed. +This can provide I/O performance benefits for applications that do not care +about the accuracy of this timestamp. +This flag provides functionality similar to the +.BR mount (2) +.BR MS_NOATIME +flag, but on a per-file basis. +.\" .TP +.\" .BR FS_NOCOMP_FL " \(aq\(aq" +.\" FIXME Support for FS_NOCOMP_FL on Btrfs? +.TP +.BR FS_NOCOW_FL " \(aqC\(aq (since Linux 2.6.39)" +The file will not be subject to copy-on-write updates. +This flag has an effect only on filesystems that support copy-on-write +semantics, such as Btrfs. +See +.BR chattr (1) +and +.BR btrfs (5). +.TP +.BR FS_NODUMP_FL " \(aqd\(aq" +Don't include this file in backups made using +.BR dump (8). +.TP +.BR FS_NOTAIL_FL " \(aqt\(aq" +This flag is supported only on Reiserfs. +It disables the Reiserfs tail-packing feature, +which tries to pack small files (and the final fragment of larger files) +into the same disk block as the file metadata. +.TP +.BR FS_PROJINHERIT_FL " \(aqP\(aq (since Linux 4.5)" +.\" commit 040cb3786d9b25293b8b0b05b90da0f871e1eb9b +.\" Flag name was added in Linux 4.4 +.\" FIXME Not currently supported because not in FS_FL_USER_MODIFIABLE? +Inherit the quota project ID. +Files and subdirectories will inherit the project ID of the directory. +This flag can be applied only to directories. +.TP +.BR FS_SECRM_FL " \(aqs\(aq" +Mark the file for secure deletion. +This feature is not implemented by any filesystem, +since the task of securely erasing a file from a recording medium +is surprisingly difficult. +.TP +.BR FS_SYNC_FL " \(aqS\(aq" +Make file updates synchronous. +For files, this makes all writes synchronous +(as though all opens of the file were with the +.BR O_SYNC +flag). +For directories, this has the same effect as the +.BR FS_DIRSYNC_FL +flag. +.TP +.BR FS_TOPDIR_FL " \(aqT\(aq" +Mark a directory for special treatment under the Orlov block-allocation +strategy. +See +.BR chattr (1) +for details. +This flag can be applied only to directories and +has an effect only for ext2, ext3, and ext4. +.TP +.BR FS_UNRM_FL " \(aqu\(aq" +Allow the file to be undeleted if it is deleted. +This feature is not implemented by any filesystem, +since it is possible to implement file-recovery mechanisms outside the kernel. +.PP +In most cases, +when any of the above flags is set on a directory, +the flag is inherited by files and subdirectories +created inside that directory. +Exceptions include +.BR FS_TOPDIR_FL , +which is not inheritable, and +.BR FS_DIRSYNC_FL , +which is inherited only by subdirectories. +.SH CONFORMING TO +Inode flags are a nonstandard Linux extension. +.SH NOTES +In order to change the inode flags of a file using the +.BR FS_IOC_SETFLAGS +operation, +the effective user ID of the caller must match the owner of the file, +or the caller must have the +.BR CAP_FOWNER +capability. +.SH SEE ALSO +.BR chattr (1), +.BR lsattr (1), +.BR mount (2), +.BR btrfs (5), +.BR ext4 (5), +.BR xfs (5), +.BR xattr (7), +.BR mount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_list.2 b/man2/ioctl_list.2 new file mode 100644 index 0000000..f95f0b5 --- /dev/null +++ b/man2/ioctl_list.2 @@ -0,0 +1,1052 @@ +.\" Ioctl List 1.3.27 is copyright 1995 by Michael Elizabeth Chastain. +.\" Michael Elizabeth Chastain +.\" +.\" +.\" %%%LICENSE_START(GPLv2_MISC) +.\" It is licensed under the GNU General Public License, Version 2. +.\" %%%LICENSE_END +.\" +.\" Ioctl List 1.3.27 +.\" Sun 17 Sep 1995 +.\" +.\" // Copyright +.\" +.\" +.\" +.\" // Change Log +.\" +.\" 1.3.27 421 ioctls. +.\" Type information for non-pointer args. +.\" SIOCDEVPRIVATE, SIOCPROTOPRIVATE ioctls. +.\" Descriptions of extended arguments. +.\" +.\" 1.2.9 365 ioctls. +.\" First public version. +.\" +.\" +.\" 2007-12-29 Alain Portal and Michael Kerrisk +.\" : +.\" Various formatting improvements +.\" +.TH IOCTL_LIST 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_list \- list of ioctl calls in Linux/i386 kernel +.SH DESCRIPTION +This is Ioctl List 1.3.27, a list of ioctl calls in Linux/i386 kernel +1.3.27. +It contains 421 ioctls from +.IR . +For each ioctl, its numerical value, its name, and its argument +type are given. +.PP +An argument type of +.I "const struct foo\ *" +means the argument is input to the kernel. +.I "struct foo\ *" +means the kernel outputs the argument. +If the kernel uses the argument for both input and output, this is +marked with \fI//\ I-O\fP. +.PP +Some ioctls take more arguments or return more values than a single +structure. +These are marked \fI//\ MORE\fP and documented further in a +separate section. +.PP +This list is very incomplete. +.SS ioctl structure +.\" added two sections - aeb +Ioctl command values are 32-bit constants. +In principle these constants are completely arbitrary, but people have +tried to build some structure into them. +.PP +The old Linux situation was that of mostly 16-bit constants, where the +last byte is a serial number, and the preceding byte(s) give a type +indicating the driver. +Sometimes the major number was used: 0x03 +for the +.B HDIO_* +ioctls, 0x06 for the +.B LP* +ioctls. +And sometimes +one or more ASCII letters were used. +For example, +.B TCGETS +has value +0x00005401, with 0x54 = \(aqT\(aq indicating the terminal driver, and +.B CYGETTIMEOUT +has value 0x00435906, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq +indicating the cyclades driver. +.PP +Later (0.98p5) some more information was built into the number. +One has 2 direction bits +(00: none, 01: write, 10: read, 11: read/write) +followed by 14 size bits (giving the size of the argument), +followed by an 8-bit type (collecting the ioctls in groups +for a common purpose or a common driver), and an 8-bit +serial number. +.PP +The macros describing this structure live in +.I +and are +.B _IO(type,nr) +and +.BR "{_IOR,_IOW,_IOWR}(type,nr,size)" . +They use +.I sizeof(size) +so that size is a +misnomer here: this third argument is a data type. +.PP +Note that the size bits are very unreliable: in lots of cases +they are wrong, either because of buggy macros using +.IR sizeof(sizeof(struct)) , +or because of legacy values. +.PP +Thus, it seems that the new structure only gave disadvantages: +it does not help in checking, but it causes varying values +for the various architectures. +.SH RETURN VALUE +Decent ioctls return 0 on success and \-1 on error, while +any output value is stored via the argument. +However, +quite a few ioctls in fact return an output value. +This is not yet indicated below. +.PP +// Main table. +.PP +// +.TS +l l l. +0x00008901 FIOSETOWN const int * +0x00008902 SIOCSPGRP const int * +0x00008903 FIOGETOWN int * +0x00008904 SIOCGPGRP int * +0x00008905 SIOCATMAR int * +0x00008906 SIOCGSTAMP timeval * +.TE +.sp 1 +// +.TS +l l l l. +0x00005401 TCGETS struct termios * +0x00005402 TCSETS const struct termios * +0x00005403 TCSETSW const struct termios * +0x00005404 TCSETSF const struct termios * +0x00005405 TCGETA struct termio * +0x00005406 TCSETA const struct termio * +0x00005407 TCSETAW const struct termio * +0x00005408 TCSETAF const struct termio * +0x00005409 TCSBRK int +0x0000540A TCXONC int +0x0000540B TCFLSH int +0x0000540C TIOCEXCL void +0x0000540D TIOCNXCL void +0x0000540E TIOCSCTTY int +0x0000540F TIOCGPGRP pid_t * +0x00005410 TIOCSPGRP const pid_t * +0x00005411 TIOCOUTQ int * +0x00005412 TIOCSTI const char * +0x00005413 TIOCGWINSZ struct winsize * +0x00005414 TIOCSWINSZ const struct winsize * +0x00005415 TIOCMGET int * +0x00005416 TIOCMBIS const int * +0x00005417 TIOCMBIC const int * +0x00005418 TIOCMSET const int * +0x00005419 TIOCGSOFTCAR int * +0x0000541A TIOCSSOFTCAR const int * +0x0000541B FIONREAD int * +0x0000541B TIOCINQ int * +0x0000541C TIOCLINUX const char * // MORE +0x0000541D TIOCCONS void +0x0000541E TIOCGSERIAL struct serial_struct * +0x0000541F TIOCSSERIAL const struct serial_struct * +0x00005420 TIOCPKT const int * +0x00005421 FIONBIO const int * +0x00005422 TIOCNOTTY void +0x00005423 TIOCSETD const int * +0x00005424 TIOCGETD int * +0x00005425 TCSBRKP int +0x00005426 TIOCTTYGSTRUCT struct tty_struct * +0x00005450 FIONCLEX void +0x00005451 FIOCLEX void +0x00005452 FIOASYNC const int * +0x00005453 TIOCSERCONFIG void +0x00005454 TIOCSERGWILD int * +0x00005455 TIOCSERSWILD const int * +0x00005456 TIOCGLCKTRMIOS struct termios * +0x00005457 TIOCSLCKTRMIOS const struct termios * +0x00005458 TIOCSERGSTRUCT struct async_struct * +0x00005459 TIOCSERGETLSR int * +.TE +.\" Some tables are split into two or more to avoid the warning: +.\" "table wider than line width". Some lines are to long to fit +.\" on one line on an 80 columns console +.TS +l l l. +0x0000545A TIOCSERGETMULTI struct serial_multiport_struct * +0x0000545B TIOCSERSETMULTI const struct serial_multiport_struct * +.TE +.sp 1 +// +.TS +l l l l. +0x000089E0 SIOCAX25GETUID const struct sockaddr_ax25 * +0x000089E1 SIOCAX25ADDUID const struct sockaddr_ax25 * +0x000089E2 SIOCAX25DELUID const struct sockaddr_ax25 * +0x000089E3 SIOCAX25NOUID const int * +0x000089E4 SIOCAX25DIGCTL const int * +0x000089E5 SIOCAX25GETPARMS struct ax25_parms_struct * // I-O +.TE +.TS +l l l. +0x000089E6 SIOCAX25SETPARMS const struct ax25_parms_struct * +.TE +.sp 1 +// +.TS +l l l. +0x00007314 STL_BINTR void +0x00007315 STL_BSTART void +0x00007316 STL_BSTOP void +0x00007317 STL_BRESET void +.TE +.sp 1 +// +.TS +l l l. +0x00005301 CDROMPAUSE void +0x00005302 CDROMRESUME void +0x00005303 CDROMPLAYMSF const struct cdrom_msf * +0x00005304 CDROMPLAYTRKIND const struct cdrom_ti * +0x00005305 CDROMREADTOCHDR struct cdrom_tochdr * +.TE +.TS +l l l l. +0x00005306 CDROMREADTOCENTRY struct cdrom_tocentry * // I-O +.TE +.TS +l l l l. +0x00005307 CDROMSTOP void +0x00005308 CDROMSTART void +0x00005309 CDROMEJECT void +0x0000530A CDROMVOLCTRL const struct cdrom_volctrl * +0x0000530B CDROMSUBCHNL struct cdrom_subchnl * // I-O +0x0000530C CDROMREADMODE2 const struct cdrom_msf * // MORE +0x0000530D CDROMREADMODE1 const struct cdrom_msf * // MORE +0x0000530E CDROMREADAUDIO const struct cdrom_read_audio * // MORE +0x0000530F CDROMEJECT_SW int +.TE +.TS +l l l l. +0x00005310 CDROMMULTISESSION struct cdrom_multisession * // I-O +.TE +.TS +l l l l. +0x00005311 CDROM_GET_UPC struct { char [8]; } * +0x00005312 CDROMRESET void +0x00005313 CDROMVOLREAD struct cdrom_volctrl * +0x00005314 CDROMREADRAW const struct cdrom_msf * // MORE +0x00005315 CDROMREADCOOKED const struct cdrom_msf * // MORE +0x00005316 CDROMSEEK const struct cdrom_msf * +.TE +.sp 1 +// +.TS +l l l. +0x00002000 CM206CTL_GET_STAT int +0x00002001 CM206CTL_GET_LAST_STAT int +.TE +.sp 1 +// +.TS +l l l. +0x00435901 CYGETMON struct cyclades_monitor * +0x00435902 CYGETTHRESH int * +0x00435903 CYSETTHRESH int +0x00435904 CYGETDEFTHRESH int * +0x00435905 CYSETDEFTHRESH int +0x00435906 CYGETTIMEOUT int * +0x00435907 CYSETTIMEOUT int +0x00435908 CYGETDEFTIMEOUT int * +0x00435909 CYSETDEFTIMEOUT int +.TE +.sp 1 +// +.TS +l l l. +0x00000000 FDCLRPRM void +0x00000001 FDSETPRM const struct floppy_struct * +0x00000002 FDDEFPRM const struct floppy_struct * +0x00000003 FDGETPRM struct floppy_struct * +0x00000004 FDMSGON void +0x00000005 FDMSGOFF void +0x00000006 FDFMTBEG void +0x00000007 FDFMTTRK const struct format_descr * +0x00000008 FDFMTEND void +0x0000000A FDSETEMSGTRESH int +0x0000000B FDFLUSH void +0x0000000C FDSETMAXERRS const struct floppy_max_errors * +0x0000000E FDGETMAXERRS struct floppy_max_errors * +0x00000010 FDGETDRVTYP struct { char [16]; } * +0x00000014 FDSETDRVPRM const struct floppy_drive_params * +0x00000015 FDGETDRVPRM struct floppy_drive_params * +0x00000016 FDGETDRVSTAT struct floppy_drive_struct * +0x00000017 FDPOLLDRVSTAT struct floppy_drive_struct * +0x00000018 FDRESET int +0x00000019 FDGETFDCSTAT struct floppy_fdc_state * +0x0000001B FDWERRORCLR void +0x0000001C FDWERRORGET struct floppy_write_errors * +.TE +.TS +l l l l. +0x0000001E FDRAWCMD struct floppy_raw_cmd * // MORE // I-O +0x00000028 FDTWADDLE void +.TE +.sp 1 +// +.TS +l l l l. +0x0000125D BLKROSET const int * +0x0000125E BLKROGET int * +0x0000125F BLKRRPART void +0x00001260 BLKGETSIZE unsigned long * +0x00001261 BLKFLSBUF void +0x00001262 BLKRASET unsigned long +0x00001263 BLKRAGET unsigned long * +0x00000001 FIBMAP int * // I-O +0x00000002 FIGETBSZ int * +0x80086601 FS_IOC_GETFLAGS int * +0x40086602 FS_IOC_SETFLAGS int * +0x80087601 FS_IOC_GETVERSION int * +0x40087602 FS_IOC_SETVERSION int * +0xC020660B FS_IOC_FIEMAP struct fiemap * +0x40086602 FS_IOC32_SETFLAGS int * +0x40086602 FS_IOC32_SETFLAGS int * +0x80047601 FS_IOC32_GETVERSION int * +0x40047602 FS_IOC32_SETVERSION int * +.TE +.sp 1 +// +.TS +l l l l. +0x00000301 HDIO_GETGEO struct hd_geometry * +0x00000302 HDIO_GET_UNMASKINTR int * +0x00000304 HDIO_GET_MULTCOUNT int * +0x00000307 HDIO_GET_IDENTITY struct hd_driveid * +0x00000308 HDIO_GET_KEEPSETTINGS int * +0x00000309 HDIO_GET_CHIPSET int * +0x0000030A HDIO_GET_NOWERR int * +0x0000030B HDIO_GET_DMA int * +0x0000031F HDIO_DRIVE_CMD int * // I-O +0x00000321 HDIO_SET_MULTCOUNT int +0x00000322 HDIO_SET_UNMASKINTR int +0x00000323 HDIO_SET_KEEPSETTINGS int +0x00000324 HDIO_SET_CHIPSET int +0x00000325 HDIO_SET_NOWERR int +0x00000326 HDIO_SET_DMA int +.TE +.sp 1 +// +.TS +l l l l. +0x000089F0 EQL_ENSLAVE struct ifreq * // MORE // I-O +0x000089F1 EQL_EMANCIPATE struct ifreq * // MORE // I-O +0x000089F2 EQL_GETSLAVECFG struct ifreq * // MORE // I-O +0x000089F3 EQL_SETSLAVECFG struct ifreq * // MORE // I-O +0x000089F4 EQL_GETMASTRCFG struct ifreq * // MORE // I-O +0x000089F5 EQL_SETMASTRCFG struct ifreq * // MORE // I-O +.TE +.sp 1 +// +.TS +l l l l. +0x000089F0 SIOCDEVPLIP struct ifreq * // I-O +.TE +.sp 1 +// +.TS +l l l. +0x00005490 PPPIOCGFLAGS int * +0x00005491 PPPIOCSFLAGS const int * +0x00005492 PPPIOCGASYNCMAP int * +0x00005493 PPPIOCSASYNCMAP const int * +0x00005494 PPPIOCGUNIT int * +0x00005495 PPPIOCSINPSIG const int * +0x00005497 PPPIOCSDEBUG const int * +0x00005498 PPPIOCGDEBUG int * +0x00005499 PPPIOCGSTAT struct ppp_stats * +0x0000549A PPPIOCGTIME struct ppp_ddinfo * +0x0000549B PPPIOCGXASYNCMAP struct { int [8]; } * +0x0000549C PPPIOCSXASYNCMAP const struct { int [8]; } * +0x0000549D PPPIOCSMRU const int * +0x0000549E PPPIOCRASYNCMAP const int * +0x0000549F PPPIOCSMAXCID const int * +.TE +.sp 1 +// +.TS +l l l. +0x000089E0 SIOCAIPXITFCRT const char * +0x000089E1 SIOCAIPXPRISLT const char * +0x000089E2 SIOCIPXCFGDATA struct ipx_config_data * +.TE +.sp 1 +// +.TS +l l l. +0x00004B60 GIO_FONT struct { char [8192]; } * +0x00004B61 PIO_FONT const struct { char [8192]; } * +.TE +.TS +l2 l2 l2 l. +0x00004B6B GIO_FONTX struct console_font_desc * // MORE // I-O +0x00004B6C PIO_FONTX const struct console_font_desc * //MORE +.TE +.TS +l l l. +0x00004B70 GIO_CMAP struct { char [48]; } * +0x00004B71 PIO_CMAP const struct { char [48]; } +.TE +.TS +l l l l. +0x00004B2F KIOCSOUND int +0x00004B30 KDMKTONE int +0x00004B31 KDGETLED char * +0x00004B32 KDSETLED int +0x00004B33 KDGKBTYPE char * +0x00004B34 KDADDIO int // MORE +0x00004B35 KDDELIO int // MORE +0x00004B36 KDENABIO void // MORE +0x00004B37 KDDISABIO void // MORE +0x00004B3A KDSETMODE int +0x00004B3B KDGETMODE int * +0x00004B3C KDMAPDISP void // MORE +0x00004B3D KDUNMAPDISP void // MORE +0x00004B40 GIO_SCRNMAP struct { char [E_TABSZ]; } * +.TE +.TS +l l l. +0x00004B41 PIO_SCRNMAP const struct { char [E_TABSZ]; } * +0x00004B69 GIO_UNISCRNMAP struct { short [E_TABSZ]; } * +0x00004B6A PIO_UNISCRNMAP const struct { short [E_TABSZ]; } * +.TE +.TS +l l l l. +0x00004B66 GIO_UNIMAP struct unimapdesc * // MORE // I-O +0x00004B67 PIO_UNIMAP const struct unimapdesc * // MORE +0x00004B68 PIO_UNIMAPCLR const struct unimapinit * +0x00004B44 KDGKBMODE int * +0x00004B45 KDSKBMODE int +0x00004B62 KDGKBMETA int * +0x00004B63 KDSKBMETA int +0x00004B64 KDGKBLED int * +0x00004B65 KDSKBLED int +0x00004B46 KDGKBENT struct kbentry * // I-O +0x00004B47 KDSKBENT const struct kbentry * +0x00004B48 KDGKBSENT struct kbsentry * // I-O +0x00004B49 KDSKBSENT const struct kbsentry * +0x00004B4A KDGKBDIACR struct kbdiacrs * +0x00004B4B KDSKBDIACR const struct kbdiacrs * +0x00004B4C KDGETKEYCODE struct kbkeycode * // I-O +0x00004B4D KDSETKEYCODE const struct kbkeycode * +0x00004B4E KDSIGACCEPT int +.TE +.sp 1 +// +.TS +l l l. +0x00000601 LPCHAR int +0x00000602 LPTIME int +0x00000604 LPABORT int +0x00000605 LPSETIRQ int +0x00000606 LPGETIRQ int * +0x00000608 LPWAIT int +0x00000609 LPCAREFUL int +0x0000060A LPABORTOPEN int +0x0000060B LPGETSTATUS int * +0x0000060C LPRESET void +0x0000060D LPGETSTATS struct lp_stats * +.TE +.sp 1 +// +.TS +l l l l. +0x000089E0 SIOCGETVIFCNT struct sioc_vif_req * // I-O +0x000089E1 SIOCGETSGCNT struct sioc_sg_req * // I-O +.TE +.sp 1 +// see +.BR ioctl_fat (2) +.TS +l l l l. +0x82307201 VFAT_IOCTL_READDIR_BOTH struct dirent [2] +0x82307202 VFAT_IOCTL_READDIR_SHORT struct dirent [2] +0x80047210 FAT_IOCTL_GET_ATTRIBUTES __u32 * +0x40047211 FAT_IOCTL_SET_ATTRIBUTES const __u32 * +0x80047213 FAT_IOCTL_GET_VOLUME_ID __u32 * +.TE +.sp 1 +// +.TS +l l l. +0x40086D01 MTIOCTOP const struct mtop * +0x801C6D02 MTIOCGET struct mtget * +0x80046D03 MTIOCPOS struct mtpos * +0x80206D04 MTIOCGETCONFIG struct mtconfiginfo * +0x40206D05 MTIOCSETCONFIG const struct mtconfiginfo * +.TE +.sp 1 +// +.TS +l l l l. +0x000089E0 SIOCNRGETPARMS struct nr_parms_struct * // I-O +0x000089E1 SIOCNRSETPARMS const struct nr_parms_struct * +0x000089E2 SIOCNRDECOBS void +0x000089E3 SIOCNRRTCTL const int * +.TE +.sp 1 +// +.br +// This API is deprecated. +.br +// It is being replaced by nl80211 and cfg80211. +See +.br +// +.I https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 +.TS +l l l. +x00008b00 SIOCSIWCOMMIT struct iwreq * +x00008b01 SIOCGIWNAME struct iwreq * +x00008b02 SIOCSIWNWID struct iwreq * +x00008b03 SIOCGIWNWID struct iwreq * +x00008b04 SIOCSIWFREQ struct iwreq * +x00008b05 SIOCGIWFREQ struct iwreq * +x00008b06 SIOCSIWMODE struct iwreq * +x00008b07 SIOCGIWMODE struct iwreq * +x00008b08 SIOCSIWSENS struct iwreq * +x00008b09 SIOCGIWSENS struct iwreq * +x00008b0a SIOCSIWRANGE struct iwreq * +x00008b0b SIOCGIWRANGE struct iwreq * +x00008b0c SIOCSIWPRIV struct iwreq * +x00008b0d SIOCGIWPRIV struct iwreq * +x00008b0e SIOCSIWSTATS struct iwreq * +x00008b0f SIOCGIWSTATS struct iwreq * +x00008b10 SIOCSIWSPY struct iwreq * +x00008b11 SIOCGIWSPY struct iwreq * +x00008b12 SIOCSIWTHRSPY struct iwreq * +x00008b13 SIOCGIWTHRSPY struct iwreq * +x00008b14 SIOCSIWAP struct iwreq * +x00008b15 SIOCGIWAP struct iwreq * +x00008b17 SIOCGIWAPLIST struct iwreq * +x00008b18 SIOCSIWSCAN struct iwreq * +x00008b19 SIOCGIWSCAN struct iwreq * +x00008b1a SIOCSIWESSID struct iwreq * +x00008b1b SIOCGIWESSID struct iwreq * +x00008b1c SIOCSIWNICKN struct iwreq * +x00008b1d SIOCGIWNICKN struct iwreq * +x00008b20 SIOCSIWRATE struct iwreq * +x00008b21 SIOCGIWRATE struct iwreq * +x00008b22 SIOCSIWRTS struct iwreq * +x00008b23 SIOCGIWRTS struct iwreq * +x00008b24 SIOCSIWFRAG struct iwreq * +x00008b25 SIOCGIWFRAG struct iwreq * +x00008b26 SIOCSIWTXPOW struct iwreq * +x00008b27 SIOCGIWTXPOW struct iwreq * +x00008b28 SIOCSIWRETRY struct iwreq * +x00008b29 SIOCGIWRETRY struct iwreq * +x00008b2a SIOCSIWENCODE struct iwreq * +x00008b2b SIOCGIWENCODE struct iwreq * +x00008b2c SIOCSIWPOWER struct iwreq * +x00008b2d SIOCGIWPOWER struct iwreq * +x00008b30 SIOCSIWGENIE struct iwreq * +x00008b31 SIOCGIWGENIE struct iwreq * +x00008b16 SIOCSIWMLME struct iwreq * +x00008b32 SIOCSIWAUTH struct iwreq * +x00008b33 SIOCGIWAUTH struct iwreq * +x00008b34 SIOCSIWENCODEEXT struct iwreq * +x00008b35 SIOCGIWENCODEEXT struct iwreq * +x00008b36 SIOCSIWPMKSA struct iwreq * +.TE +.sp 1 +// +.TS +l l l. +0x00009000 DDIOCSDBG const int * +0x00005382 CDROMAUDIOBUFSIZ int +.TE +.sp 1 +// +.TS +l l l l. +0x00005470 TIOCSCCINI void +0x00005471 TIOCCHANINI const struct scc_modem * +0x00005472 TIOCGKISS struct ioctl_command * // I-O +0x00005473 TIOCSKISS const struct ioctl_command * +0x00005474 TIOCSCCSTAT struct scc_stat * +.TE +.sp 1 +// +.TS +l l l. +0x00005382 SCSI_IOCTL_GET_IDLUN struct { int [2]; } * +0x00005383 SCSI_IOCTL_TAGGED_ENABLE void +0x00005384 SCSI_IOCTL_TAGGED_DISABLE void +.TE +.TS +l l l l. +0x00005385 SCSI_IOCTL_PROBE_HOST const int * // MORE +.TE +.sp 1 +// +.TS +l l l. +0x80027501 SMB_IOC_GETMOUNTUID uid_t * +.TE +.sp 1 +// see +.BR netdevice (7) +.PP +.TS +l l l l. +0x0000890B SIOCADDRT const struct rtentry * // MORE +0x0000890C SIOCDELRT const struct rtentry * // MORE +0x00008910 SIOCGIFNAME char [] +0x00008911 SIOCSIFLINK void +0x00008912 SIOCGIFCONF struct ifconf * // MORE // I-O +0x00008913 SIOCGIFFLAGS struct ifreq * // I-O +0x00008914 SIOCSIFFLAGS const struct ifreq * +0x00008915 SIOCGIFADDR struct ifreq * // I-O +0x00008916 SIOCSIFADDR const struct ifreq * +0x00008917 SIOCGIFDSTADDR struct ifreq * // I-O +0x00008918 SIOCSIFDSTADDR const struct ifreq * +0x00008919 SIOCGIFBRDADDR struct ifreq * // I-O +0x0000891A SIOCSIFBRDADDR const struct ifreq * +0x0000891B SIOCGIFNETMASK struct ifreq * // I-O +0x0000891C SIOCSIFNETMASK const struct ifreq * +0x0000891D SIOCGIFMETRIC struct ifreq * // I-O +0x0000891E SIOCSIFMETRIC const struct ifreq * +0x0000891F SIOCGIFMEM struct ifreq * // I-O +0x00008920 SIOCSIFMEM const struct ifreq * +0x00008921 SIOCGIFMTU struct ifreq * // I-O +0x00008922 SIOCSIFMTU const struct ifreq * +.TE +.TS +l l l l. +0x00008923 OLD_SIOCGIFHWADDR struct ifreq * // I-O +0x00008924 SIOCSIFHWADDR const struct ifreq * // MORE +0x00008925 SIOCGIFENCAP int * +0x00008926 SIOCSIFENCAP const int * +0x00008927 SIOCGIFHWADDR struct ifreq * // I-O +0x00008929 SIOCGIFSLAVE void +0x00008930 SIOCSIFSLAVE void +0x00008931 SIOCADDMULTI const struct ifreq * +0x00008932 SIOCDELMULTI const struct ifreq * +0x00008940 SIOCADDRTOLD void +0x00008941 SIOCDELRTOLD void +0x00008950 SIOCDARP const struct arpreq * +0x00008951 SIOCGARP struct arpreq * // I-O +0x00008952 SIOCSARP const struct arpreq * +0x00008960 SIOCDRARP const struct arpreq * +0x00008961 SIOCGRARP struct arpreq * // I-O +0x00008962 SIOCSRARP const struct arpreq * +0x00008970 SIOCGIFMAP struct ifreq * // I-O +0x00008971 SIOCSIFMAP const struct ifreq * +.TE +.sp 1 +// +.TS +l l l. +0x00005100 SNDCTL_SEQ_RESET void +0x00005101 SNDCTL_SEQ_SYNC void +.TE +.TS +l l l l. +0xC08C5102 SNDCTL_SYNTH_INFO struct synth_info * // I-O +0xC0045103 SNDCTL_SEQ_CTRLRATE int * // I-O +0x80045104 SNDCTL_SEQ_GETOUTCOUNT int * +0x80045105 SNDCTL_SEQ_GETINCOUNT int * +0x40045106 SNDCTL_SEQ_PERCMODE void +.TE +.TS +l l l. +0x40285107 SNDCTL_FM_LOAD_INSTR const struct sbi_instrument * +.TE +.TS +l l l l. +0x40045108 SNDCTL_SEQ_TESTMIDI const int * +0x40045109 SNDCTL_SEQ_RESETSAMPLES const int * +0x8004510A SNDCTL_SEQ_NRSYNTHS int * +0x8004510B SNDCTL_SEQ_NRMIDIS int * +0xC074510C SNDCTL_MIDI_INFO struct midi_info * // I-O +0x4004510D SNDCTL_SEQ_THRESHOLD const int * +0xC004510E SNDCTL_SYNTH_MEMAVL int * // I-O +0x4004510F SNDCTL_FM_4OP_ENABLE const int * +0xCFB85110 SNDCTL_PMGR_ACCESS struct patmgr_info * // I-O +0x00005111 SNDCTL_SEQ_PANIC void +.TE +.TS +l l l. +0x40085112 SNDCTL_SEQ_OUTOFBAND const struct seq_event_rec * +.TE +.TS +l l l l. +0xC0045401 SNDCTL_TMR_TIMEBASE int * // I-O +0x00005402 SNDCTL_TMR_START void +0x00005403 SNDCTL_TMR_STOP void +0x00005404 SNDCTL_TMR_CONTINUE void +0xC0045405 SNDCTL_TMR_TEMPO int * // I-O +0xC0045406 SNDCTL_TMR_SOURCE int * // I-O +0x40045407 SNDCTL_TMR_METRONOME const int * +0x40045408 SNDCTL_TMR_SELECT int * // I-O +0xCFB85001 SNDCTL_PMGR_IFACE struct patmgr_info * // I-O +0xC0046D00 SNDCTL_MIDI_PRETIME int * // I-O +0xC0046D01 SNDCTL_MIDI_MPUMODE const int * +.TE +.TS +l l l l. +0xC0216D02 SNDCTL_MIDI_MPUCMD struct mpu_command_rec * // I-O +.TE +.TS +l l l l. +0x00005000 SNDCTL_DSP_RESET void +0x00005001 SNDCTL_DSP_SYNC void +0xC0045002 SNDCTL_DSP_SPEED int * // I-O +0xC0045003 SNDCTL_DSP_STEREO int * // I-O +0xC0045004 SNDCTL_DSP_GETBLKSIZE int * // I-O +0xC0045006 SOUND_PCM_WRITE_CHANNELS int * // I-O +0xC0045007 SOUND_PCM_WRITE_FILTER int * // I-O +0x00005008 SNDCTL_DSP_POST void +0xC0045009 SNDCTL_DSP_SUBDIVIDE int * // I-O +0xC004500A SNDCTL_DSP_SETFRAGMENT int * // I-O +0x8004500B SNDCTL_DSP_GETFMTS int * +0xC0045005 SNDCTL_DSP_SETFMT int * // I-O +.TE +.TS +l l l. +0x800C500C SNDCTL_DSP_GETOSPACE struct audio_buf_info * +0x800C500D SNDCTL_DSP_GETISPACE struct audio_buf_info * +0x0000500E SNDCTL_DSP_NONBLOCK void +0x80045002 SOUND_PCM_READ_RATE int * +0x80045006 SOUND_PCM_READ_CHANNELS int * +0x80045005 SOUND_PCM_READ_BITS int * +0x80045007 SOUND_PCM_READ_FILTER int * +0x00004300 SNDCTL_COPR_RESET void +0xCFB04301 SNDCTL_COPR_LOAD const struct copr_buffer * +.TE +.TS +l l l l. +0xC0144302 SNDCTL_COPR_RDATA struct copr_debug_buf * // I-O +0xC0144303 SNDCTL_COPR_RCODE struct copr_debug_buf * // I-O +.TE +.TS +l l l. +0x40144304 SNDCTL_COPR_WDATA const struct copr_debug_buf * +0x40144305 SNDCTL_COPR_WCODE const struct copr_debug_buf * +.TE +.TS +l l l l. +0xC0144306 SNDCTL_COPR_RUN struct copr_debug_buf * // I-O +0xC0144307 SNDCTL_COPR_HALT struct copr_debug_buf * // I-O +.TE +.TS +l l l. +0x4FA44308 SNDCTL_COPR_SENDMSG const struct copr_msg * +0x8FA44309 SNDCTL_COPR_RCVMSG struct copr_msg * +0x80044D00 SOUND_MIXER_READ_VOLUME int * +0x80044D01 SOUND_MIXER_READ_BASS int * +0x80044D02 SOUND_MIXER_READ_TREBLE int * +0x80044D03 SOUND_MIXER_READ_SYNTH int * +0x80044D04 SOUND_MIXER_READ_PCM int * +0x80044D05 SOUND_MIXER_READ_SPEAKER int * +0x80044D06 SOUND_MIXER_READ_LINE int * +0x80044D07 SOUND_MIXER_READ_MIC int * +0x80044D08 SOUND_MIXER_READ_CD int * +0x80044D09 SOUND_MIXER_READ_IMIX int * +0x80044D0A SOUND_MIXER_READ_ALTPCM int * +0x80044D0B SOUND_MIXER_READ_RECLEV int * +0x80044D0C SOUND_MIXER_READ_IGAIN int * +0x80044D0D SOUND_MIXER_READ_OGAIN int * +0x80044D0E SOUND_MIXER_READ_LINE1 int * +0x80044D0F SOUND_MIXER_READ_LINE2 int * +0x80044D10 SOUND_MIXER_READ_LINE3 int * +0x80044D1C SOUND_MIXER_READ_MUTE int * +0x80044D1D SOUND_MIXER_READ_ENHANCE int * +0x80044D1E SOUND_MIXER_READ_LOUD int * +0x80044DFF SOUND_MIXER_READ_RECSRC int * +0x80044DFE SOUND_MIXER_READ_DEVMASK int * +0x80044DFD SOUND_MIXER_READ_RECMASK int * +0x80044DFB SOUND_MIXER_READ_STEREODEVS int * +0x80044DFC SOUND_MIXER_READ_CAPS int * +.TE +.TS +l l l l. +0xC0044D00 SOUND_MIXER_WRITE_VOLUME int * // I-O +0xC0044D01 SOUND_MIXER_WRITE_BASS int * // I-O +0xC0044D02 SOUND_MIXER_WRITE_TREBLE int * // I-O +0xC0044D03 SOUND_MIXER_WRITE_SYNTH int * // I-O +0xC0044D04 SOUND_MIXER_WRITE_PCM int * // I-O +0xC0044D05 SOUND_MIXER_WRITE_SPEAKER int * // I-O +0xC0044D06 SOUND_MIXER_WRITE_LINE int * // I-O +0xC0044D07 SOUND_MIXER_WRITE_MIC int * // I-O +0xC0044D08 SOUND_MIXER_WRITE_CD int * // I-O +0xC0044D09 SOUND_MIXER_WRITE_IMIX int * // I-O +0xC0044D0A SOUND_MIXER_WRITE_ALTPCM int * // I-O +0xC0044D0B SOUND_MIXER_WRITE_RECLEV int * // I-O +0xC0044D0C SOUND_MIXER_WRITE_IGAIN int * // I-O +0xC0044D0D SOUND_MIXER_WRITE_OGAIN int * // I-O +0xC0044D0E SOUND_MIXER_WRITE_LINE1 int * // I-O +0xC0044D0F SOUND_MIXER_WRITE_LINE2 int * // I-O +0xC0044D10 SOUND_MIXER_WRITE_LINE3 int * // I-O +0xC0044D1C SOUND_MIXER_WRITE_MUTE int * // I-O +0xC0044D1D SOUND_MIXER_WRITE_ENHANCE int * // I-O +0xC0044D1E SOUND_MIXER_WRITE_LOUD int * // I-O +0xC0044DFF SOUND_MIXER_WRITE_RECSRC int * // I-O +.TE +.sp 1 +// see +.BR timerfd_create (2) +.TS +l l l l. +0x40085400 TFD_IOC_SET_TICKS uint64_t * +.TE +.sp 1 +// +.TS +l l l l. +0x000004D2 UMSDOS_READDIR_DOS struct umsdos_ioctl * // I-O +0x000004D3 UMSDOS_UNLINK_DOS const struct umsdos_ioctl * +0x000004D4 UMSDOS_RMDIR_DOS const struct umsdos_ioctl * +0x000004D5 UMSDOS_STAT_DOS struct umsdos_ioctl * // I-O +0x000004D6 UMSDOS_CREAT_EMD const struct umsdos_ioctl * +0x000004D7 UMSDOS_UNLINK_EMD const struct umsdos_ioctl * +0x000004D8 UMSDOS_READDIR_EMD struct umsdos_ioctl * // I-O +0x000004D9 UMSDOS_GETVERSION struct umsdos_ioctl * +0x000004DA UMSDOS_INIT_EMD void +0x000004DB UMSDOS_DOS_SETUP const struct umsdos_ioctl * +0x000004DC UMSDOS_RENAME_DOS const struct umsdos_ioctl * +.TE +.sp 1 +// +.TS +l l l. +0x00005600 VT_OPENQRY int * +0x00005601 VT_GETMODE struct vt_mode * +0x00005602 VT_SETMODE const struct vt_mode * +0x00005603 VT_GETSTATE struct vt_stat * +0x00005604 VT_SENDSIG void +0x00005605 VT_RELDISP int +0x00005606 VT_ACTIVATE int +0x00005607 VT_WAITACTIVE int +0x00005608 VT_DISALLOCATE int +0x00005609 VT_RESIZE const struct vt_sizes * +0x0000560A VT_RESIZEX const struct vt_consize * +.TE +.sp 1 +// More arguments. +Some ioctl's take a pointer to a structure which contains additional +pointers. +These are documented here in alphabetical order. +.PP +.B CDROMREADAUDIO +takes an input pointer +.IR "const struct cdrom_read_audio\ *" . +The +.I buf +field points to an output buffer of length +.IR "nframes\ * CD_FRAMESIZE_RAW" . +.PP +.BR CDROMREADCOOKED , +.BR CDROMREADMODE1 , +.BR CDROMREADMODE2 , +and +.B CDROMREADRAW +take an input pointer +.IR "const struct cdrom_msf\ *" . +They use the same pointer as an output pointer to +.IR "char []" . +The length varies by request. +For +.BR CDROMREADMODE1 , +most drivers use CD_FRAMESIZE, but the Optics Storage +driver uses OPT_BLOCKSIZE instead (both have the numerical value +2048). +.PP +.nf + CDROMREADCOOKED char [CD_FRAMESIZE] + CDROMREADMODE1 char [CD_FRAMESIZE or OPT_BLOCKSIZE] + CDROMREADMODE2 char [CD_FRAMESIZE_RAW0] + CDROMREADRAW char [CD_FRAMESIZE_RAW] +.fi +.PP +.BR EQL_ENSLAVE , +.BR EQL_EMANCIPATE , +.BR EQL_GETSLAVECFG , +.BR EQL_SETSLAVECFG , +.BR EQL_GETMASTERCFG , +and +.B EQL_SETMASTERCFG +take a +.IR "struct ifreq\ *" . +The +.I ifr_data +field is a pointer to another structure as follows: +.PP +.nf + EQL_ENSLAVE const struct slaving_request * + EQL_EMANCIPATE const struct slaving_request * + EQL_GETSLAVECFG struct slave_config * // I-O + EQL_SETSLAVECFG const struct slave_config * + EQL_GETMASTERCFG struct master_config * + EQL_SETMASTERCFG const struct master_config * +.fi +.PP +.B FDRAWCMD +takes a +.IR "struct floppy raw_cmd\ *" . +If +.I flags & FD_RAW_WRITE +is nonzero, then +.I data +points to an input buffer of length +.IR length . +If +.I flags & FD_RAW_READ +is nonzero, then +.I data +points to an output buffer of length +.IR length . +.PP +.B GIO_FONTX +and +.B PIO_FONTX +take a +.I struct console_font_desc\ * +or a +.IR "const struct console_font_desc\ *" , +respectively. +.I chardata +points to a buffer of +.IR "char [charcount]" . +This is an output buffer for +.B GIO_FONTX +and an input buffer for +.BR PIO_FONTX . +.PP +.B GIO_UNIMAP +and +.B PIO_UNIMAP +take a +.I "struct unimapdesc\ *" +or a +.IR "const struct unimapdesc\ *" , +respectively. +.I entries +points to a buffer of +.IR "struct unipair [entry_ct]" . +This is an output buffer for +.B GIO_UNIMAP +and an input buffer for +.BR PIO_UNIMAP . +.PP +KDADDIO, KDDELIO, KDDISABIO, and KDENABIO enable or disable access to +I/O ports. +They are essentially alternate interfaces to 'ioperm'. +.PP +.B KDMAPDISP +and +.B KDUNMAPDISP +enable or disable memory mappings or I/O port access. +They are not implemented in the kernel. +.PP +.B SCSI_IOCTL_PROBE_HOST +takes an input pointer +.IR "const int\ *" , +which is a length. +It uses the same pointer as an output pointer to a +.I char [] +buffer of this length. +.PP +.B SIOCADDRT +and +.B SIOCDELRT +take an input pointer whose type depends on +the protocol: +.PP +.nf + Most protocols const struct rtentry * + AX.25 const struct ax25_route * + NET/ROM const struct nr_route_struct * + INET6 const struct in6_rtmsg * +.fi +.PP +.B SIOCGIFCONF +takes a +.IR "struct ifconf\ *" . +The +.I ifc_buf +field points to a buffer of length +.I ifc_len +bytes, into which the kernel writes a list of type +.IR "struct ifreq []" . +.PP +.B SIOCSIFHWADDR +takes an input pointer whose type depends on the protocol: +.PP +.nf + Most protocols const struct ifreq * + AX.25 const char [AX25_ADDR_LEN] +.fi +.PP +.B TIOCLINUX +takes a +.IR "const char\ *" . +It uses this to distinguish several +independent subcases. +In the table below, +.I N + foo +means +.I foo +after an N-byte pad. +.I struct selection +is implicitly defined in +.IR drivers/char/selection.c +.PP +.nf + TIOCLINUX-2 1 + const struct selection * + TIOCLINUX-3 void + TIOCLINUX-4 void + TIOCLINUX-5 4 + const struct { long [8]; } * + TIOCLINUX-6 char * + TIOCLINUX-7 char * + TIOCLINUX-10 1 + const char * +.fi +.PP +// Duplicate ioctls +.PP +This list does not include ioctls in the range +.B SIOCDEVPRIVATE +and +.BR SIOCPROTOPRIVATE . +.TS +l l l. +0x00000001 FDSETPRM FIBMAP +0x00000002 FDDEFPRM FIGETBSZ +0x00005382 CDROMAUDIOBUFSIZ SCSI_IOCTL_GET_IDLUN +0x00005402 SNDCTL_TMR_START TCSETS +0x00005403 SNDCTL_TMR_STOP TCSETSW +0x00005404 SNDCTL_TMR_CONTINUE TCSETSF +.TE +.SH SEE ALSO +.BR ioctl (2), +.BR ioctl_fat (2), +.BR netdevice (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_ns.2 b/man2/ioctl_ns.2 new file mode 100644 index 0000000..7c50d4a --- /dev/null +++ b/man2/ioctl_ns.2 @@ -0,0 +1,371 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH IOCTL_NS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_ns \- ioctl() operations for Linux namespaces +.SH DESCRIPTION +.\" ============================================================ +.\" +.SS Discovering namespace relationships +The following +.BR ioctl (2) +operations are provided to allow discovery of namespace relationships (see +.BR user_namespaces (7) +and +.BR pid_namespaces (7)). +The form of the calls is: +.PP +.in +4n +.EX +new_fd = ioctl(fd, request); +.EE +.in +.PP +In each case, +.I fd +refers to a +.IR /proc/[pid]/ns/* +file. +Both operations return a new file descriptor on success. +.TP +.BR NS_GET_USERNS " (since Linux 4.9)" +.\" commit bcac25a58bfc6bd79191ac5d7afb49bea96da8c9 +.\" commit 6786741dbf99e44fb0c0ed85a37582b8a26f1c3b +Returns a file descriptor that refers to the owning user namespace +for the namespace referred to by +.IR fd . +.TP +.BR NS_GET_PARENT " (since Linux 4.9)" +.\" commit a7306ed8d94af729ecef8b6e37506a1c6fc14788 +Returns a file descriptor that refers to the parent namespace of +the namespace referred to by +.IR fd . +This operation is valid only for hierarchical namespaces +(i.e., PID and user namespaces). +For user namespaces, +.BR NS_GET_PARENT +is synonymous with +.BR NS_GET_USERNS . +.PP +The new file descriptor returned by these operations is opened with the +.BR O_RDONLY +and +.BR O_CLOEXEC +(close-on-exec; see +.BR fcntl (2)) +flags. +.PP +By applying +.BR fstat (2) +to the returned file descriptor, one obtains a +.I stat +structure whose +.I st_dev +(resident device) and +.I st_ino +(inode number) fields together identify the owning/parent namespace. +This inode number can be matched with the inode number of another +.IR /proc/[pid]/ns/{pid,user} +file to determine whether that is the owning/parent namespace. +.PP +Either of these +.BR ioctl (2) +operations can fail with the following errors: +.TP +.B EPERM +The requested namespace is outside of the caller's namespace scope. +This error can occur if, for example, the owning user namespace is an +ancestor of the caller's current user namespace. +It can also occur on attempts to obtain the parent of the initial +user or PID namespace. +.TP +.B ENOTTY +The operation is not supported by this kernel version. +.PP +Additionally, the +.B NS_GET_PARENT +operation can fail with the following error: +.TP +.B EINVAL +.I fd +refers to a nonhierarchical namespace. +.PP +See the EXAMPLE section for an example of the use of these operations. +.\" ============================================================ +.\" +.SS Discovering the namespace type +The +.B NS_GET_NSTYPE +.\" commit e5ff5ce6e20ee22511398bb31fb912466cf82a36 +operation (available since Linux 4.11) can be used to discover +the type of namespace referred to by the file descriptor +.IR fd : +.PP +.in +4n +.EX +nstype = ioctl(fd, NS_GET_NSTYPE); +.EE +.in +.PP +.I fd +refers to a +.IR /proc/[pid]/ns/* +file. +.PP +The return value is one of the +.BR CLONE_NEW* +values that can be specified to +.BR clone (2) +or +.BR unshare (2) +in order to create a namespace. +.\" ============================================================ +.\" +.SS Discovering the owner of a user namespace +The +.B NS_GET_OWNER_UID +.\" commit 015bb305b8ebe8d601a238ab70ebdc394c7a19ba +operation (available since Linux 4.11) can be used to discover +the owner user ID of a user namespace (i.e., the effective user ID +of the process that created the user namespace). +The form of the call is: +.PP +.in +4n +.EX +uid_t uid; +ioctl(fd, NS_GET_OWNER_UID, &uid); +.EE +.in +.PP +.I fd +refers to a +.IR /proc/[pid]/ns/user +file. +.PP +The owner user ID is returned in the +.I uid_t +pointed to by the third argument. +.PP +This operation can fail with the following error: +.TP +.B EINVAL +.I fd +does not refer to a user namespace. +.SH ERRORS +Any of the above +.BR ioctl () +operations can return the following errors: +.TP +.B ENOTTY +.I fd +does not refer to a +.I /proc/[pid]/ns/* +file. +.SH CONFORMING TO +Namespaces and the operations described on this page are a Linux-specific. +.SH EXAMPLE +The example shown below uses the +.BR ioctl (2) +operations described above to perform simple +discovery of namespace relationships. +The following shell sessions show various examples of the use +of this program. +.PP +Trying to get the parent of the initial user namespace fails, +since it has no parent: +.PP +.in +4n +.EX +$ \fB./ns_show /proc/self/ns/user p\fP +The parent namespace is outside your namespace scope +.EE +.in +.PP +Create a process running +.BR sleep (1) +that resides in new user and UTS namespaces, +and show that the new UTS namespace is associated with the new user namespace: +.PP +.in +4n +.EX +$ \fBunshare \-Uu sleep 1000 &\fP +[1] 23235 +$ \fB./ns_show /proc/23235/ns/uts u\fP +Device/Inode of owning user namespace is: [0,3] / 4026532448 +$ \fBreadlink /proc/23235/ns/user \fP +user:[4026532448] +.EE +.in +.PP +Then show that the parent of the new user namespace in the preceding +example is the initial user namespace: +.PP +.in +4n +.EX +$ \fBreadlink /proc/self/ns/user\fP +user:[4026531837] +$ \fB./ns_show /proc/23235/ns/user p\fP +Device/Inode of parent namespace is: [0,3] / 4026531837 +.EE +.in +.PP +Start a shell in a new user namespace, and show that from within +this shell, the parent user namespace can't be discovered. +Similarly, the UTS namespace +(which is associated with the initial user namespace) +can't be discovered. +.PP +.in +4n +.EX +$ \fBPS1="sh2$ " unshare \-U bash\fP +sh2$ \fB./ns_show /proc/self/ns/user p\fP +The parent namespace is outside your namespace scope +sh2$ \fB./ns_show /proc/self/ns/uts u\fP +The owning user namespace is outside your namespace scope +.EE +.in +.SS Program source +\& +.EX +/* ns_show.c + + Licensed under the GNU General Public License v2 or later. +*/ +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#ifndef NS_GET_USERNS +#define NSIO 0xb7 +#define NS_GET_USERNS _IO(NSIO, 0x1) +#define NS_GET_PARENT _IO(NSIO, 0x2) +#endif + +int +main(int argc, char *argv[]) +{ + int fd, userns_fd, parent_fd; + struct stat sb; + + if (argc < 2) { + fprintf(stderr, "Usage: %s /proc/[pid]/ns/[file] [p|u]\\n", + argv[0]); + fprintf(stderr, "\\nDisplay the result of one or both " + "of NS_GET_USERNS (u) or NS_GET_PARENT (p)\\n" + "for the specified /proc/[pid]/ns/[file]. If neither " + "\(aqp\(aq nor \(aqu\(aq is specified,\\n" + "NS_GET_USERNS is the default.\\n"); + exit(EXIT_FAILURE); + } + + /* Obtain a file descriptor for the \(aqns\(aq file specified + in argv[1] */ + + fd = open(argv[1], O_RDONLY); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } + + /* Obtain a file descriptor for the owning user namespace and + then obtain and display the inode number of that namespace */ + + if (argc < 3 || strchr(argv[2], \(aqu\(aq)) { + userns_fd = ioctl(fd, NS_GET_USERNS); + + if (userns_fd == \-1) { + if (errno == EPERM) + printf("The owning user namespace is outside " + "your namespace scope\\n"); + else + perror("ioctl\-NS_GET_USERNS"); + exit(EXIT_FAILURE); + } + + if (fstat(userns_fd, &sb) == \-1) { + perror("fstat\-userns"); + exit(EXIT_FAILURE); + } + printf("Device/Inode of owning user namespace is: " + "[%lx,%lx] / %ld\\n", + (long) major(sb.st_dev), (long) minor(sb.st_dev), + (long) sb.st_ino); + + close(userns_fd); + } + + /* Obtain a file descriptor for the parent namespace and + then obtain and display the inode number of that namespace */ + + if (argc > 2 && strchr(argv[2], \(aqp\(aq)) { + parent_fd = ioctl(fd, NS_GET_PARENT); + + if (parent_fd == \-1) { + if (errno == EINVAL) + printf("Can\(aq get parent namespace of a " + "nonhierarchical namespace\\n"); + else if (errno == EPERM) + printf("The parent namespace is outside " + "your namespace scope\\n"); + else + perror("ioctl\-NS_GET_PARENT"); + exit(EXIT_FAILURE); + } + + if (fstat(parent_fd, &sb) == \-1) { + perror("fstat\-parentns"); + exit(EXIT_FAILURE); + } + printf("Device/Inode of parent namespace is: [%lx,%lx] / %ld\\n", + (long) major(sb.st_dev), (long) minor(sb.st_dev), + (long) sb.st_ino); + + close(parent_fd); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fstat (2), +.BR ioctl (2), +.BR proc (5), +.BR namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 new file mode 100644 index 0000000..1980da1 --- /dev/null +++ b/man2/ioctl_tty.2 @@ -0,0 +1,602 @@ +.\" Copyright 2002 Walter Harms +.\" and Andries Brouwer . +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH IOCTL_TTY 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_tty \- ioctls for terminals and serial lines +.SH SYNOPSIS +.B "#include " +.PP +.BI "int ioctl(int " fd ", int " cmd ", ...);" +.SH DESCRIPTION +The +.BR ioctl (2) +call for terminals and serial ports accepts many possible command arguments. +Most require a third argument, of varying type, here called +.I argp +or +.IR arg . +.PP +Use of +.I ioctl +makes for nonportable programs. +Use the POSIX interface described in +.BR termios (3) +whenever possible. +.SS Get and set terminal attributes +.TP +.BI "TCGETS struct termios *" argp +Equivalent to +.IR "tcgetattr(fd, argp)" . +.br +Get the current serial port settings. +.TP +.BI "TCSETS const struct termios *" argp +Equivalent to +.IR "tcsetattr(fd, TCSANOW, argp)" . +.br +Set the current serial port settings. +.TP +.BI "TCSETSW const struct termios *" argp +Equivalent to +.IR "tcsetattr(fd, TCSADRAIN, argp)" . +.br +Allow the output buffer to drain, and +set the current serial port settings. +.TP +.BI "TCSETSF const struct termios *" argp +Equivalent to +.IR "tcsetattr(fd, TCSAFLUSH, argp)" . +.br +Allow the output buffer to drain, discard pending input, and +set the current serial port settings. +.PP +The following four ioctls are just like +.BR TCGETS , +.BR TCSETS , +.BR TCSETSW , +.BR TCSETSF , +except that they take a +.I "struct termio\ *" +instead of a +.IR "struct termios\ *" . +.IP +.BI "TCGETA struct termio *" argp +.IP +.BI "TCSETA const struct termio *" argp +.IP +.BI "TCSETAW const struct termio *" argp +.IP +.BI "TCSETAF const struct termio *" argp +.SS Locking the termios structure +The +.I termios +structure of a terminal can be locked. +The lock is itself a +.I termios +structure, with nonzero bits or fields indicating a +locked value. +.TP +.BI "TIOCGLCKTRMIOS struct termios *" argp +Gets the locking status of the +.I termios +structure of the terminal. +.TP +.BI "TIOCSLCKTRMIOS const struct termios *" argp +Sets the locking status of the +.I termios +structure of the terminal. +Only a process with the +.BR CAP_SYS_ADMIN +capability can do this. +.SS Get and set window size +Window sizes are kept in the kernel, but not used by the kernel +(except in the case of virtual consoles, where the kernel will +update the window size when the size of the virtual console changes, +for example, by loading a new font). +.PP +The following constants and structure are defined in +.IR . +.TP +.BI "TIOCGWINSZ struct winsize *" argp +Get window size. +.TP +.BI "TIOCSWINSZ const struct winsize *" argp +Set window size. +.PP +The struct used by these ioctls is defined as +.PP +.in +4n +.EX +struct winsize { + unsigned short ws_row; + unsigned short ws_col; + unsigned short ws_xpixel; /* unused */ + unsigned short ws_ypixel; /* unused */ +}; +.EE +.in +.PP +When the window size changes, a +.B SIGWINCH +signal is sent to the +foreground process group. +.SS Sending a break +.TP +.BI "TCSBRK int " arg +Equivalent to +.IR "tcsendbreak(fd, arg)" . +.br +If the terminal is using asynchronous serial data transmission, and +.I arg +is zero, then send a break (a stream of zero bits) for between +0.25 and 0.5 seconds. +If the terminal is not using asynchronous +serial data transmission, then either a break is sent, or the function +returns without doing anything. +When +.I arg +is nonzero, nobody knows what will happen. +.IP +(SVr4, UnixWare, Solaris, Linux treat +.I "tcsendbreak(fd,arg)" +with nonzero +.I arg +like +.IR "tcdrain(fd)" . +SunOS treats +.I arg +as a multiplier, and sends a stream of bits +.I arg +times as long as done for zero +.IR arg . +DG/UX and AIX treat +.I arg +(when nonzero) as a time interval measured in milliseconds. +HP-UX ignores +.IR arg .) +.TP +.BI "TCSBRKP int " arg +So-called "POSIX version" of +.BR TCSBRK . +It treats nonzero +.I arg +as a timeinterval measured in deciseconds, and does nothing +when the driver does not support breaks. +.TP +.B "TIOCSBRK void" +Turn break on, that is, start sending zero bits. +.TP +.B "TIOCCBRK void" +Turn break off, that is, stop sending zero bits. +.SS Software flow control +.TP +.BI "TCXONC int " arg +Equivalent to +.IR "tcflow(fd, arg)" . +.br +See +.BR tcflow (3) +for the argument values +.BR TCOOFF , +.BR TCOON , +.BR TCIOFF , +.BR TCION . +.SS Buffer count and flushing +.TP +.BI "FIONREAD int *" argp +Get the number of bytes in the input buffer. +.TP +.BI "TIOCINQ int *" argp +Same as +.BR FIONREAD . +.TP +.BI "TIOCOUTQ int *" argp +Get the number of bytes in the output buffer. +.TP +.BI "TCFLSH int " arg +Equivalent to +.IR "tcflush(fd, arg)" . +.br +See +.BR tcflush (3) +for the argument values +.BR TCIFLUSH , +.BR TCOFLUSH , +.BR TCIOFLUSH . +.SS Faking input +.TP +.BI "TIOCSTI const char *" argp +Insert the given byte in the input queue. +.SS Redirecting console output +.TP +.B "TIOCCONS void" +Redirect output that would have gone to +.I /dev/console +or +.I /dev/tty0 +to the given terminal. +If that was a pseudoterminal master, send it to the slave. +In Linux before version 2.6.10, +anybody can do this as long as the output was not redirected yet; +since version 2.6.10, only a process with the +.BR CAP_SYS_ADMIN +capability may do this. +If output was redirected already +.B EBUSY +is returned, +but redirection can be stopped by using this ioctl with +.I fd +pointing at +.I /dev/console +or +.IR /dev/tty0 . +.SS Controlling terminal +.TP +.BI "TIOCSCTTY int " arg +Make the given terminal the controlling terminal of the calling process. +The calling process must be a session leader and not have a +controlling terminal already. +For this case, +.I arg +should be specified as zero. +.IP +If this terminal is already the controlling terminal +of a different session group, then the ioctl fails with +.BR EPERM , +unless the caller has the +.BR CAP_SYS_ADMIN +capability and +.I arg +equals 1, in which case the terminal is stolen, and all processes that had +it as controlling terminal lose it. +.TP +.B "TIOCNOTTY void" +If the given terminal was the controlling terminal of the calling process, +give up this controlling terminal. +If the process was session leader, +then send +.B SIGHUP +and +.B SIGCONT +to the foreground process group +and all processes in the current session lose their controlling terminal. +.SS Process group and session ID +.TP +.BI "TIOCGPGRP pid_t *" argp +When successful, equivalent to +.IR "*argp = tcgetpgrp(fd)" . +.br +Get the process group ID of the foreground process group on this terminal. +.TP +.BI "TIOCSPGRP const pid_t *" argp +Equivalent to +.IR "tcsetpgrp(fd, *argp)" . +.br +Set the foreground process group ID of this terminal. +.TP +.BI "TIOCGSID pid_t *" argp +Get the session ID of the given terminal. +This fails with the error +.B ENOTTY +if the terminal is not a master pseudoterminal +and not our controlling terminal. +Strange. +.SS Exclusive mode +.TP +.B "TIOCEXCL void" +Put the terminal into exclusive mode. +No further +.BR open (2) +operations on the terminal are permitted. +(They fail with +.BR EBUSY , +except for a process with the +.BR CAP_SYS_ADMIN +capability.) +.TP +.BI "TIOCGEXCL int *" argp +(since Linux 3.8) +If the terminal is currently in exclusive mode, +place a nonzero value in the location pointed to by +.IR argp ; +otherwise, place zero in +.IR *argp . +.TP +.B "TIOCNXCL void" +Disable exclusive mode. +.SS Line discipline +.TP +.BI "TIOCGETD int *" argp +Get the line discipline of the terminal. +.TP +.BI "TIOCSETD const int *" argp +Set the line discipline of the terminal. +.SS Pseudoterminal ioctls +.TP +.BI "TIOCPKT const int *" argp +Enable (when +.RI * argp +is nonzero) or disable packet mode. +Can be applied to the master side of a pseudoterminal only (and will return +.B ENOTTY +otherwise). +In packet mode, each subsequent +.BR read (2) +will return a packet that either contains a single nonzero control byte, +or has a single byte containing zero (\(aq\0\(aq) followed by data +written on the slave side of the pseudoterminal. +If the first byte is not +.B TIOCPKT_DATA +(0), it is an OR of one +or more of the following bits: +.IP +.nf +TIOCPKT_FLUSHREAD The read queue for the terminal is flushed. +TIOCPKT_FLUSHWRITE The write queue for the terminal is flushed. +TIOCPKT_STOP Output to the terminal is stopped. +TIOCPKT_START Output to the terminal is restarted. +TIOCPKT_DOSTOP The start and stop characters are \fB^S\fP/\fB^Q\fP. +TIOCPKT_NOSTOP The start and stop characters are not \fB^S\fP/\fB^Q\fP. +.fi +.IP +While this mode is in use, the presence +of control status information to be read +from the master side may be detected by a +.BR select (2) +for exceptional conditions or a +.BR poll (2) +for the +.I POLLPRI +event. +.IP +This mode is used by +.BR rlogin (1) +and +.BR rlogind (8) +to implement a remote-echoed, +locally \fB^S\fP/\fB^Q\fP flow-controlled remote login. +.TP +.BI "TIOCGPKT const int *" argp +(since Linux 3.8) +Return the current packet mode setting in the integer pointed to by +.IR argp . +.TP +.BI "TIOCSPTLCK int *" argp +Set (if +.IR *argp +is nonzero) or remove (if +.IR *argp +is zero) the pseudoterminal slave device. +(See also +.BR unlockpt (3).) +.TP +.BI "TIOCGPTLCK int *" argp +(since Linux 3.8) +Place the current lock state of the pseudoterminal slave device +in the location pointed to by +.IR argp . +.TP +.BI "TIOCGPTPEER int " flags +.\" commit 54ebbfb1603415d9953c150535850d30609ef077 +(since Linux 4.13) +Given a file descriptor in +.I fd +that refers to a pseudoterminal master, +open (with the given +.BR open (2)-style +.IR flags ) +and return a new file descriptor that refers to the peer +pseudoterminal slave device. +This operation can be performed +regardless of whether the pathname of the slave device +is accessible through the calling process's mount namespace. +.IP +Security-conscious programs interacting with namespaces may wish to use this +operation rather than +.BR open (2) +with the pathname returned by +.BR ptsname (3), +and similar library functions that have insecure APIs. +(For example, confusion can occur in some cases using +.BR ptsname (3) +with a pathname where a devpts filesystem +has been mounted in a different mount namespace.) +.PP +The BSD ioctls +.BR TIOCSTOP , +.BR TIOCSTART , +.BR TIOCUCNTL , +.B TIOCREMOTE +have not been implemented under Linux. +.SS Modem control +.TP +.BI "TIOCMGET int *" argp +Get the status of modem bits. +.TP +.BI "TIOCMSET const int *" argp +Set the status of modem bits. +.TP +.BI "TIOCMBIC const int *" argp +Clear the indicated modem bits. +.TP +.BI "TIOCMBIS const int *" argp +Set the indicated modem bits. +.PP +The following bits are used by the above ioctls: +.PP +.nf +TIOCM_LE DSR (data set ready/line enable) +TIOCM_DTR DTR (data terminal ready) +TIOCM_RTS RTS (request to send) +TIOCM_ST Secondary TXD (transmit) +TIOCM_SR Secondary RXD (receive) +TIOCM_CTS CTS (clear to send) +TIOCM_CAR DCD (data carrier detect) +TIOCM_CD see TIOCM_CAR +TIOCM_RNG RNG (ring) +TIOCM_RI see TIOCM_RNG +TIOCM_DSR DSR (data set ready) +.fi +.TP +.BI "TIOCMIWAIT int " arg +Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change. +The bits of interest are specified as a bit mask in +.IR arg , +by ORing together any of the bit values, +.BR TIOCM_RNG , +.BR TIOCM_DSR , +.BR TIOCM_CD , +and +.BR TIOCM_CTS . +The caller should use +.B TIOCGICOUNT +to see which bit has changed. +.TP +.BI "TIOCGICOUNT struct serial_icounter_struct *" argp +Get counts of input serial line interrupts (DCD, RI, DSR, CTS). +The counts are written to the +.I serial_icounter_struct +structure pointed to by +.IR argp . +.IP +Note: both 1->0 and 0->1 transitions are counted, except for +RI, where only 0->1 transitions are counted. +.SS Marking a line as local +.TP +.BI "TIOCGSOFTCAR int *" argp +("Get software carrier flag") +Get the status of the CLOCAL flag in the c_cflag field of the +.I termios +structure. +.TP +.BI "TIOCSSOFTCAR const int *" argp +("Set software carrier flag") +Set the CLOCAL flag in the +.I termios +structure when +.RI * argp +is nonzero, and clear it otherwise. +.PP +If the +.B CLOCAL +flag for a line is off, the hardware carrier detect (DCD) +signal is significant, and an +.BR open (2) +of the corresponding terminal will block until DCD is asserted, +unless the +.B O_NONBLOCK +flag is given. +If +.B CLOCAL +is set, the line behaves as if DCD is always asserted. +The software carrier flag is usually turned on for local devices, +and is off for lines with modems. +.SS Linux-specific +For the +.B TIOCLINUX +ioctl, see +.BR ioctl_console (2). +.SS Kernel debugging +.B "#include " +.TP +.BI "TIOCTTYGSTRUCT struct tty_struct *" argp +Get the +.I tty_struct +corresponding to +.IR fd . +This command was removed in Linux 2.5.67. +.\" commit b3506a09d15dc5aee6d4bb88d759b157016e1864 +.\" Author: Andries E. Brouwer +.\" Date: Tue Apr 1 04:42:46 2003 -0800 +.\" +.\" [PATCH] kill TIOCTTYGSTRUCT +.\" +.\" Only used for (dubious) debugging purposes, and exposes +.\" internal kernel state. +.\" +.\" .SS Serial info +.\" .BR "#include " +.\" .PP +.\" .TP +.\" .BI "TIOCGSERIAL struct serial_struct *" argp +.\" Get serial info. +.\" .TP +.\" .BI "TIOCSSERIAL const struct serial_struct *" argp +.\" Set serial info. +.SH RETURN VALUE +The +.BR ioctl (2) +system call returns 0 on success. +On error, it returns \-1 and sets +.I errno +appropriately. +.SH ERRORS +.TP +.B EINVAL +Invalid command parameter. +.TP +.B ENOIOCTLCMD +Unknown command. +.TP +.B ENOTTY +Inappropriate +.IR fd . +.TP +.B EPERM +Insufficient permission. +.SH EXAMPLE +Check the condition of DTR on the serial port. +.PP +.EX +#include +#include +#include + +int +main(void) +{ + int fd, serial; + + fd = open("/dev/ttyS0", O_RDONLY); + ioctl(fd, TIOCMGET, &serial); + if (serial & TIOCM_DTR) + puts("TIOCM_DTR is set"); + else + puts("TIOCM_DTR is not set"); + close(fd); +} +.EE +.SH SEE ALSO +.BR ldattach (1), +.BR ioctl (2), +.BR ioctl_console (2), +.BR termios (3), +.BR pty (7) +.\" +.\" FIONBIO const int * +.\" FIONCLEX void +.\" FIOCLEX void +.\" FIOASYNC const int * +.\" from serial.c: +.\" TIOCSERCONFIG void +.\" TIOCSERGWILD int * +.\" TIOCSERSWILD const int * +.\" TIOCSERGSTRUCT struct async_struct * +.\" TIOCSERGETLSR int * +.\" TIOCSERGETMULTI struct serial_multiport_struct * +.\" TIOCSERSETMULTI const struct serial_multiport_struct * +.\" TIOCGSERIAL, TIOCSSERIAL (see above) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 new file mode 100644 index 0000000..a7b32d4 --- /dev/null +++ b/man2/ioctl_userfaultfd.2 @@ -0,0 +1,700 @@ +.\" Copyright (c) 2016, IBM Corporation. +.\" Written by Mike Rapoport +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH IOCTL_USERFAULTFD 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_userfaultfd \- create a file descriptor for handling page faults in user +space +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int ioctl(int " fd ", int " cmd ", ...);" +.fi +.SH DESCRIPTION +Various +.BR ioctl (2) +operations can be performed on a userfaultfd object (created by a call to +.BR userfaultfd (2)) +using calls of the form: +.PP +.in +4n +.EX +ioctl(fd, cmd, argp); +.EE +.in +In the above, +.I fd +is a file descriptor referring to a userfaultfd object, +.I cmd +is one of the commands listed below, and +.I argp +is a pointer to a data structure that is specific to +.IR cmd . +.PP +The various +.BR ioctl (2) +operations are described below. +The +.BR UFFDIO_API, +.BR UFFDIO_REGISTER , +and +.BR UFFDIO_UNREGISTER +operations are used to +.I configure +userfaultfd behavior. +These operations allow the caller to choose what features will be enabled and +what kinds of events will be delivered to the application. +The remaining operations are +.IR range +operations. +These operations enable the calling application to resolve page-fault +events. +.\" +.SS UFFDIO_API +(Since Linux 4.3.) +Enable operation of the userfaultfd and perform API handshake. +.PP +The +.I argp +argument is a pointer to a +.IR uffdio_api +structure, defined as: +.PP +.in +4n +.EX +struct uffdio_api { + __u64 api; /* Requested API version (input) */ + __u64 features; /* Requested features (input/output) */ + __u64 ioctls; /* Available ioctl() operations (output) */ +}; +.EE +.in +.PP +The +.I api +field denotes the API version requested by the application. +.PP +The kernel verifies that it can support the requested API version, +and sets the +.I features +and +.I ioctls +fields to bit masks representing all the available features and the generic +.BR ioctl (2) +operations available. +.PP +For Linux kernel versions before 4.11, the +.I features +field must be initialized to zero before the call to +.IR UFFDIO_API , +and zero (i.e., no feature bits) is placed in the +.I features +field by the kernel upon return from +.BR ioctl (2). +.PP +Starting from Linux 4.11, the +.I features +field can be used to ask whether particular features are supported +and explicitly enable userfaultfd features that are disabled by default. +The kernel always reports all the available features in the +.I features +field. +.PP +To enable userfaultfd features the application should set +a bit corresponding to each feature it wants to enable in the +.I features +field. +If the kernel supports all the requested features it will enable them. +Otherwise it will zero out the returned +.I uffdio_api +structure and return +.BR EINVAL . +.\" FIXME add more details about feature negotiation and enablement +.PP +The following feature bits may be set: +.TP +.BR UFFD_FEATURE_EVENT_FORK " (since Linux 4.11)" +When this feature is enabled, +the userfaultfd objects associated with a parent process are duplicated +into the child process during +.BR fork (2) +and a +.B UFFD_EVENT_FORK +event is delivered to the userfaultfd monitor +.TP +.BR UFFD_FEATURE_EVENT_REMAP " (since Linux 4.11)" +If this feature is enabled, +when the faulting process invokes +.BR mremap (2), +the userfaultfd monitor will receive an event of type +.BR UFFD_EVENT_REMAP . +.TP +.BR UFFD_FEATURE_EVENT_REMOVE " (since Linux 4.11)" +If this feature is enabled, +when the faulting process calls +.BR madvise (2) +with the +.B MADV_DONTNEED +or +.B MADV_REMOVE +advice value to free a virtual memory area +the userfaultfd monitor will receive an event of type +.BR UFFD_EVENT_REMOVE . +.TP +.BR UFFD_FEATURE_EVENT_UNMAP " (since Linux 4.11)" +If this feature is enabled, +when the faulting process unmaps virtual memory either explicitly with +.BR munmap (2), +or implicitly during either +.BR mmap (2) +or +.BR mremap (2). +the userfaultfd monitor will receive an event of type +.BR UFFD_EVENT_UNMAP . +.TP +.BR UFFD_FEATURE_MISSING_HUGETLBFS " (since Linux 4.11)" +If this feature bit is set, +the kernel supports registering userfaultfd ranges on hugetlbfs +virtual memory areas +.TP +.BR UFFD_FEATURE_MISSING_SHMEM " (since Linux 4.11)" +If this feature bit is set, +the kernel supports registering userfaultfd ranges on shared memory areas. +This includes all kernel shared memory APIs: +System V shared memory, +.BR tmpfs (5), +shared mappings of +.IR /dev/zero , +.BR mmap (2) +with the +.B MAP_SHARED +flag set, +.BR memfd_create (2), +and so on. +.TP +.BR UFFD_FEATURE_SIGBUS " (since Linux 4.14)" +.\" commit 2d6d6f5a09a96cc1fec7ed992b825e05f64cb50e +If this feature bit is set, no page-fault events +.RB ( UFFD_EVENT_PAGEFAULT ) +will be delivered. +Instead, a +.B SIGBUS +signal will be sent to the faulting process. +Applications using this +feature will not require the use of a userfaultfd monitor for processing +memory accesses to the regions registered with userfaultfd. +.PP +The returned +.I ioctls +field can contain the following bits: +.\" FIXME This user-space API seems not fully polished. Why are there +.\" not constants defined for each of the bit-mask values listed below? +.TP +.B 1 << _UFFDIO_API +The +.B UFFDIO_API +operation is supported. +.TP +.B 1 << _UFFDIO_REGISTER +The +.B UFFDIO_REGISTER +operation is supported. +.TP +.B 1 << _UFFDIO_UNREGISTER +The +.B UFFDIO_UNREGISTER +operation is supported. +.PP +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +Possible errors include: +.TP +.B EFAULT +.I argp +refers to an address that is outside the calling process's +accessible address space. +.TP +.B EINVAL +The userfaultfd has already been enabled by a previous +.BR UFFDIO_API +operation. +.TP +.B EINVAL +The API version requested in the +.I api +field is not supported by this kernel, or the +.I features +field passed to the kernel includes feature bits that are not supported +by the current kernel version. +.\" FIXME In the above error case, the returned 'uffdio_api' structure is +.\" zeroed out. Why is this done? This should be explained in the manual page. +.\" +.\" Mike Rapoport: +.\" In my understanding the uffdio_api +.\" structure is zeroed to allow the caller +.\" to distinguish the reasons for -EINVAL. +.\" +.SS UFFDIO_REGISTER +(Since Linux 4.3.) +Register a memory address range with the userfaultfd object. +The pages in the range must be "compatible". +.PP +Up to Linux kernel 4.11, +only private anonymous ranges are compatible for registering with +.BR UFFDIO_REGISTER . +.PP +Since Linux 4.11, +hugetlbfs and shared memory ranges are also compatible with +.BR UFFDIO_REGISTER . +.PP +The +.I argp +argument is a pointer to a +.I uffdio_register +structure, defined as: +.PP +.in +4n +.EX +struct uffdio_range { + __u64 start; /* Start of range */ + __u64 len; /* Length of range (bytes) */ +}; + +struct uffdio_register { + struct uffdio_range range; + __u64 mode; /* Desired mode of operation (input) */ + __u64 ioctls; /* Available ioctl() operations (output) */ +}; +.EE +.in +.PP +The +.I range +field defines a memory range starting at +.I start +and continuing for +.I len +bytes that should be handled by the userfaultfd. +.PP +The +.I mode +field defines the mode of operation desired for this memory region. +The following values may be bitwise ORed to set the userfaultfd mode for +the specified range: +.TP +.B UFFDIO_REGISTER_MODE_MISSING +Track page faults on missing pages. +.TP +.B UFFDIO_REGISTER_MODE_WP +Track page faults on write-protected pages. +.PP +Currently, the only supported mode is +.BR UFFDIO_REGISTER_MODE_MISSING . +.PP +If the operation is successful, the kernel modifies the +.I ioctls +bit-mask field to indicate which +.BR ioctl (2) +operations are available for the specified range. +This returned bit mask is as for +.BR UFFDIO_API . +.PP +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +Possible errors include: +.\" FIXME Is the following error list correct? +.\" +.TP +.B EBUSY +A mapping in the specified range is registered with another +userfaultfd object. +.TP +.B EFAULT +.I argp +refers to an address that is outside the calling process's +accessible address space. +.TP +.B EINVAL +An invalid or unsupported bit was specified in the +.I mode +field; or the +.I mode +field was zero. +.TP +.B EINVAL +There is no mapping in the specified address range. +.TP +.B EINVAL +.I range.start +or +.I range.len +is not a multiple of the system page size; or, +.I range.len +is zero; or these fields are otherwise invalid. +.TP +.B EINVAL +There as an incompatible mapping in the specified address range. +.\" Mike Rapoport: +.\" ENOMEM if the process is exiting and the +.\" mm_struct has gone by the time userfault grabs it. +.SS UFFDIO_UNREGISTER +(Since Linux 4.3.) +Unregister a memory address range from userfaultfd. +The pages in the range must be "compatible" (see the description of +.BR UFFDIO_REGISTER .) +.PP +The address range to unregister is specified in the +.IR uffdio_range +structure pointed to by +.IR argp . +.PP +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +Possible errors include: +.TP +.B EINVAL +Either the +.I start +or the +.I len +field of the +.I ufdio_range +structure was not a multiple of the system page size; or the +.I len +field was zero; or these fields were otherwise invalid. +.TP +.B EINVAL +There as an incompatible mapping in the specified address range. +.TP +.B EINVAL +There was no mapping in the specified address range. +.\" +.SS UFFDIO_COPY +(Since Linux 4.3.) +Atomically copy a continuous memory chunk into the userfault registered +range and optionally wake up the blocked thread. +The source and destination addresses and the number of bytes to copy are +specified by the +.IR src ", " dst ", and " len +fields of the +.I uffdio_copy +structure pointed to by +.IR argp : +.PP +.in +4n +.EX +struct uffdio_copy { + __u64 dst; /* Source of copy */ + __u64 src; /* Destination of copy */ + __u64 len; /* Number of bytes to copy */ + __u64 mode; /* Flags controlling behavior of copy */ + __s64 copy; /* Number of bytes copied, or negated error */ +}; +.EE +.in +.PP +The following value may be bitwise ORed in +.IR mode +to change the behavior of the +.B UFFDIO_COPY +operation: +.TP +.B UFFDIO_COPY_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution +.PP +The +.I copy +field is used by the kernel to return the number of bytes +that was actually copied, or an error (a negated +.IR errno -style +value). +.\" FIXME Above: Why is the 'copy' field used to return error values? +.\" This should be explained in the manual page. +If the value returned in +.I copy +doesn't match the value that was specified in +.IR len , +the operation fails with the error +.BR EAGAIN . +The +.I copy +field is output-only; +it is not read by the +.B UFFDIO_COPY +operation. +.PP +This +.BR ioctl (2) +operation returns 0 on success. +In this case, the entire area was copied. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes copied (i.e., the value returned in the +.I copy +field) +does not equal the value that was specified in the +.I len +field. +.TP +.B EINVAL +Either +.I dst +or +.I len +was not a multiple of the system page size, or the range specified by +.IR src +and +.IR len +or +.IR dst +and +.IR len +was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.IR mode +field. +.TP +.BR ENOENT " (since Linux 4.11)" +The faulting process has changed +its virtual memory layout simultaneously with an outstanding +.I UFFDIO_COPY +operation. +.TP +.BR ENOSPC " (from Linux 4.11 until Linux 4.13)" +The faulting process has exited at the time of a +.I UFFDIO_COPY +operation. +.TP +.BR ESRCH " (since Linux 4.13)" +The faulting process has exited at the time of a +.I UFFDIO_COPY +operation. +.\" +.SS UFFDIO_ZEROPAGE +(Since Linux 4.3.) +Zero out a memory range registered with userfaultfd. +.PP +The requested range is specified by the +.I range +field of the +.I uffdio_zeropage +structure pointed to by +.IR argp : +.PP +.in +4n +.EX +struct uffdio_zeropage { + struct uffdio_range range; + __u64 mode; /* Flags controlling behavior of copy */ + __s64 zeropage; /* Number of bytes zeroed, or negated error */ +}; +.EE +.in +.PP +The following value may be bitwise ORed in +.IR mode +to change the behavior of the +.B UFFDIO_ZERO +operation: +.TP +.B UFFDIO_ZEROPAGE_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution. +.PP +The +.I zeropage +field is used by the kernel to return the number of bytes +that was actually zeroed, +or an error in the same manner as +.BR UFFDIO_COPY . +.\" FIXME Why is the 'zeropage' field used to return error values? +.\" This should be explained in the manual page. +If the value returned in the +.I zeropage +field doesn't match the value that was specified in +.IR range.len , +the operation fails with the error +.BR EAGAIN . +The +.I zeropage +field is output-only; +it is not read by the +.B UFFDIO_ZERO +operation. +.PP +This +.BR ioctl (2) +operation returns 0 on success. +In this case, the entire area was zeroed. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes zeroed (i.e., the value returned in the +.I zeropage +field) +does not equal the value that was specified in the +.I range.len +field. +.TP +.B EINVAL +Either +.I range.start +or +.I range.len +was not a multiple of the system page size; or +.I range.len +was zero; or the range specified was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.IR mode +field. +.TP +.BR ESRCH " (since Linux 4.13)" +The faulting process has exited at the time of a +.I UFFDIO_ZEROPAGE +operation. +.\" +.SS UFFDIO_WAKE +(Since Linux 4.3.) +Wake up the thread waiting for page-fault resolution on +a specified memory address range. +.PP +The +.B UFFDIO_WAKE +operation is used in conjunction with +.BR UFFDIO_COPY +and +.BR UFFDIO_ZEROPAGE +operations that have the +.BR UFFDIO_COPY_MODE_DONTWAKE +or +.BR UFFDIO_ZEROPAGE_MODE_DONTWAKE +bit set in the +.I mode +field. +The userfault monitor can perform several +.BR UFFDIO_COPY +and +.BR UFFDIO_ZEROPAGE +operations in a batch and then explicitly wake up the faulting thread using +.BR UFFDIO_WAKE . +.PP +The +.I argp +argument is a pointer to a +.I uffdio_range +structure (shown above) that specifies the address range. +.PP +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +Possible errors include: +.TP +.B EINVAL +The +.I start +or the +.I len +field of the +.I ufdio_range +structure was not a multiple of the system page size; or +.I len +was zero; or the specified range was otherwise invalid. +.SH RETURN VALUE +See descriptions of the individual operations, above. +.SH ERRORS +See descriptions of the individual operations, above. +In addition, the following general errors can occur for all of the +operations described above: +.TP +.B EFAULT +.I argp +does not point to a valid memory address. +.TP +.B EINVAL +(For all operations except +.BR UFFDIO_API .) +The userfaultfd object has not yet been enabled (via the +.BR UFFDIO_API +operation). +.SH CONFORMING TO +These +.BR ioctl (2) +operations are Linux-specific. +.SH BUGS +In order to detect available userfault features and +enable some subset of those features +the userfaultfd file descriptor must be closed after the first +.BR UFFDIO_API +operation that queries features availability and reopened before +the second +.BR UFFDIO_API +operation that actually enables the desired features. +.SH EXAMPLE +See +.BR userfaultfd (2). +.SH SEE ALSO +.BR ioctl (2), +.BR mmap (2), +.BR userfaultfd (2) +.PP +.IR Documentation/vm/userfaultfd.txt +in the Linux kernel source tree +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioperm.2 b/man2/ioperm.2 new file mode 100644 index 0000000..760ab2b --- /dev/null +++ b/man2/ioperm.2 @@ -0,0 +1,131 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 15:12:05 1993 by Rik Faith +.\" Modified Tue Aug 1 16:27 1995 by Jochen Karrer +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Mon Feb 15 17:28:41 CET 1999 by Andries E. Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH IOPERM 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioperm \- set port input/output permissions +.SH SYNOPSIS +.B #include +/* for glibc */ +.PP +.BI "int ioperm(unsigned long " from ", unsigned long " num ", int " turn_on ); +.SH DESCRIPTION +.BR ioperm () +sets the port access permission bits for the calling thread for +.I num +bits starting from port address +.IR from . +If +.I turn_on +is nonzero, then permission for the specified bits is enabled; +otherwise it is disabled. +If +.I turn_on +is nonzero, the calling thread must be privileged +.RB ( CAP_SYS_RAWIO ). +.PP +Before Linux 2.6.8, +only the first 0x3ff I/O ports could be specified in this manner. +For more ports, the +.BR iopl (2) +system call had to be used (with a +.I level +argument of 3). +Since Linux 2.6.8, 65,536 I/O ports can be specified. +.PP +Permissions are inherited by the child created by +.BR fork (2) +(but see NOTES). +Permissions are preserved across +.BR execve (2); +this is useful for giving port access permissions to unprivileged +programs. +.PP +This call is mostly for the i386 architecture. +On many other architectures it does not exist or will always +return an error. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +Invalid values for +.I from +or +.IR num . +.TP +.B EIO +(on PowerPC) This call is not supported. +.TP +.B ENOMEM +.\" Could not allocate I/O bitmap. +Out of memory. +.TP +.B EPERM +The calling thread has insufficient privilege. +.SH CONFORMING TO +.BR ioperm () +is Linux-specific and should not be used in programs +intended to be portable. +.SH NOTES +The +.I /proc/ioports +file shows the I/O ports that are currently allocated on the system. +.PP +Before Linux 2.4, +permissions were not inherited by a child created by +.BR fork (2). +.PP +Glibc has an +.BR ioperm () +prototype both in +.I +and in +.IR . +Avoid the latter, it is available on i386 only. +.SH SEE ALSO +.BR iopl (2), +.BR outb (2), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/iopl.2 b/man2/iopl.2 new file mode 100644 index 0000000..d169921 --- /dev/null +++ b/man2/iopl.2 @@ -0,0 +1,123 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from linux/kernel/ioport.c (no copyright notice). +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Tue Aug 1 16:47 1995 by Jochen Karrer +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Fri Nov 27 14:50:36 CET 1998 by Andries Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH IOPL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +iopl \- change I/O privilege level +.SH SYNOPSIS +.B #include +.PP +.BI "int iopl(int " level ); +.SH DESCRIPTION +.BR iopl () +changes the I/O privilege level of the calling process, +as specified by the two least significant bits in +.IR level . +.PP +This call is necessary to allow 8514-compatible X servers to run under +Linux. +Since these X servers require access to all 65536 I/O ports, the +.BR ioperm (2) +call is not sufficient. +.PP +In addition to granting unrestricted I/O port access, running at a higher +I/O privilege level also allows the process to disable interrupts. +This will probably crash the system, and is not recommended. +.PP +Permissions are not inherited by the child process created by +.BR fork (2) +and are not preserved across +.BR execve (2) +(but see NOTES). +.PP +The I/O privilege level for a normal process is 0. +.PP +This call is mostly for the i386 architecture. +On many other architectures it does not exist or will always +return an error. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +.I level +is greater than 3. +.TP +.B ENOSYS +This call is unimplemented. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR iopl (); +the +.B CAP_SYS_RAWIO +capability is required to raise the I/O privilege level +above its current value. +.SH CONFORMING TO +.BR iopl () +is Linux-specific and should not be used in programs that are +intended to be portable. +.SH NOTES +.\" Libc5 treats it as a system call and has a prototype in +.\" .IR . +.\" Glibc1 does not have a prototype. +Glibc2 has a prototype both in +.I +and in +.IR . +Avoid the latter, it is available on i386 only. +.PP +Prior to Linux 3.7, +on some architectures (such as i386), permissions +.I were +inherited by the child produced by +.BR fork (2) +and were preserved across +.BR execve (2). +This behavior was inadvertently changed in Linux 3.7, +and won't be reinstated. +.SH SEE ALSO +.BR ioperm (2), +.BR outb (2), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ioprio_get.2 b/man2/ioprio_get.2 new file mode 100644 index 0000000..d6d5b3b --- /dev/null +++ b/man2/ioprio_get.2 @@ -0,0 +1 @@ +.so man2/ioprio_set.2 diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 new file mode 100644 index 0000000..5510d8a --- /dev/null +++ b/man2/ioprio_set.2 @@ -0,0 +1,380 @@ +.\" Copyright (c) International Business Machines orp., 2006 +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See +.\" the GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" HISTORY: +.\" 2006-04-27, created by Eduardo M. Fleury +.\" with various additions by Michael Kerrisk +.\" +.\" +.TH IOPRIO_SET 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioprio_get, ioprio_set \- get/set I/O scheduling class and priority +.SH SYNOPSIS +.nf +.BI "int ioprio_get(int " which ", int " who ); +.BI "int ioprio_set(int " which ", int " who ", int " ioprio ); +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +The +.BR ioprio_get () +and +.BR ioprio_set () +system calls respectively get and set the I/O scheduling class and +priority of one or more threads. +.PP +The +.I which +and +.I who +arguments identify the thread(s) on which the system +calls operate. +The +.I which +argument determines how +.I who +is interpreted, and has one of the following values: +.TP +.B IOPRIO_WHO_PROCESS +.I who +is a process ID or thread ID identifying a single process or thread. +If +.I who +is 0, then operate on the calling thread. +.TP +.B IOPRIO_WHO_PGRP +.I who +is a process group ID identifying all the members of a process group. +If +.I who +is 0, then operate on the process group of which the caller is a member. +.TP +.B IOPRIO_WHO_USER +.I who +is a user ID identifying all of the processes that +have a matching real UID. +.\" FIXME . Need to document the behavior when 'who" is specified as 0 +.\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443 +.PP +If +.I which +is specified as +.B IOPRIO_WHO_PGRP +or +.B IOPRIO_WHO_USER +when calling +.BR ioprio_get (), +and more than one process matches +.IR who , +then the returned priority will be the highest one found among +all of the matching processes. +One priority is said to be +higher than another one if it belongs to a higher priority +class +.RB ( IOPRIO_CLASS_RT +is the highest priority class; +.B IOPRIO_CLASS_IDLE +is the lowest) +or if it belongs to the same priority class as the other process but +has a higher priority level (a lower priority number means a +higher priority level). +.PP +The +.I ioprio +argument given to +.BR ioprio_set () +is a bit mask that specifies both the scheduling class and the +priority to be assigned to the target process(es). +The following macros are used for assembling and dissecting +.I ioprio +values: +.TP +.BI IOPRIO_PRIO_VALUE( class ", " data ) +Given a scheduling +.I class +and priority +.RI ( data ), +this macro combines the two values to produce an +.I ioprio +value, which is returned as the result of the macro. +.TP +.BI IOPRIO_PRIO_CLASS( mask ) +Given +.I mask +(an +.I ioprio +value), this macro returns its I/O class component, that is, +one of the values +.BR IOPRIO_CLASS_RT , +.BR IOPRIO_CLASS_BE , +or +.BR IOPRIO_CLASS_IDLE . +.TP +.BI IOPRIO_PRIO_DATA( mask ) +Given +.I mask +(an +.I ioprio +value), this macro returns its priority +.RI ( data ) +component. +.PP +See the NOTES section for more +information on scheduling classes and priorities, +as well as the meaning of specifying +.I ioprio +as 0. +.PP +I/O priorities are supported for reads and for synchronous +.RB ( O_DIRECT , +.BR O_SYNC ) +writes. +I/O priorities are not supported for asynchronous +writes because they are issued outside the context of the program +dirtying the memory, and thus program-specific priorities do not apply. +.SH RETURN VALUE +On success, +.BR ioprio_get () +returns the +.I ioprio +value of the process with highest I/O priority of any of the processes +that match the criteria specified in +.I which +and +.IR who . +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.PP +On success, +.BR ioprio_set () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid value for +.I which +or +.IR ioprio . +Refer to the NOTES section for available scheduler +classes and priority levels for +.IR ioprio . +.TP +.B EPERM +The calling process does not have the privilege needed to assign this +.I ioprio +to the specified process(es). +See the NOTES section for more information on required +privileges for +.BR ioprio_set (). +.TP +.B ESRCH +No process(es) could be found that matched the specification in +.I which +and +.IR who . +.SH VERSIONS +These system calls have been available on Linux since +kernel 2.6.13. +.SH CONFORMING TO +These system calls are Linux-specific. +.SH NOTES +Glibc does not provide a wrapper for these system calls; call them using +.BR syscall (2). +.PP +Two or more processes or threads can share an I/O context. +This will be the case when +.BR clone (2) +was called with the +.B CLONE_IO +flag. +However, by default, the distinct threads of a process will +.B not +share the same I/O context. +This means that if you want to change the I/O +priority of all threads in a process, you may need to call +.BR ioprio_set () +on each of the threads. +The thread ID that you would need for this operation +is the one that is returned by +.BR gettid (2) +or +.BR clone (2). +.PP +These system calls have an effect only when used +in conjunction with an I/O scheduler that supports I/O priorities. +As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing +(CFQ) I/O scheduler. +.PP +If no I/O scheduler has been set for a thread, +then by default the I/O priority will follow the CPU nice value +.RB ( setpriority (2)). +In Linux kernels before version 2.6.24, +once an I/O priority had been set using +.BR ioprio_set (), +there was no way to reset the I/O scheduling behavior to the default. +Since Linux 2.6.24, +.\" commit 8ec680e4c3ec818efd1652f15199ed1c216ab550 +specifying +.I ioprio +as 0 can be used to reset to the default I/O scheduling behavior. +.SS Selecting an I/O scheduler +I/O schedulers are selected on a per-device basis via the special +file +.IR /sys/block//queue/scheduler . +.PP +One can view the current I/O scheduler via the +.I /sys +filesystem. +For example, the following command +displays a list of all schedulers currently loaded in the kernel: +.PP +.in +4n +.EX +.RB "$" " cat /sys/block/sda/queue/scheduler" +noop anticipatory deadline [cfq] +.EE +.in +.PP +The scheduler surrounded by brackets is the one actually +in use for the device +.RI ( sda +in the example). +Setting another scheduler is done by writing the name of the +new scheduler to this file. +For example, the following command will set the +scheduler for the +.I sda +device to +.IR cfq : +.PP +.in +4n +.EX +.RB "$" " su" +Password: +.RB "#" " echo cfq > /sys/block/sda/queue/scheduler" +.EE +.in +.\" +.SS The Completely Fair Queuing (CFQ) I/O scheduler +Since version 3 (also known as CFQ Time Sliced), CFQ implements +I/O nice levels similar to those +of CPU scheduling. +These nice levels are grouped into three scheduling classes, +each one containing one or more priority levels: +.TP +.BR IOPRIO_CLASS_RT " (1)" +This is the real-time I/O class. +This scheduling class is given +higher priority than any other class: +processes from this class are +given first access to the disk every time. +Thus, this I/O class needs to be used with some +care: one I/O real-time process can starve the entire system. +Within the real-time class, +there are 8 levels of class data (priority) that determine exactly +how much time this process needs the disk for on each service. +The highest real-time priority level is 0; the lowest is 7. +In the future, this might change to be more directly mappable to +performance, by passing in a desired data rate instead. +.TP +.BR IOPRIO_CLASS_BE " (2)" +This is the best-effort scheduling class, +which is the default for any process +that hasn't set a specific I/O priority. +The class data (priority) determines how much +I/O bandwidth the process will get. +Best-effort priority levels are analogous to CPU nice values +(see +.BR getpriority (2)). +The priority level determines a priority relative +to other processes in the best-effort scheduling class. +Priority levels range from 0 (highest) to 7 (lowest). +.TP +.BR IOPRIO_CLASS_IDLE " (3)" +This is the idle scheduling class. +Processes running at this level get I/O +time only when no one else needs the disk. +The idle class has no class data. +Attention is required when assigning this priority class to a process, +since it may become starved if higher priority processes are +constantly accessing the disk. +.PP +Refer to the kernel source file +.I Documentation/block/ioprio.txt +for more information on the CFQ I/O Scheduler and an example program. +.SS Required permissions to set I/O priorities +Permission to change a process's priority is granted or denied based +on two criteria: +.TP +.B "Process ownership" +An unprivileged process may set the I/O priority only for a process +whose real UID +matches the real or effective UID of the calling process. +A process which has the +.B CAP_SYS_NICE +capability can change the priority of any process. +.TP +.B "What is the desired priority" +Attempts to set very high priorities +.RB ( IOPRIO_CLASS_RT ) +require the +.B CAP_SYS_ADMIN +capability. +Kernel versions up to 2.6.24 also required +.B CAP_SYS_ADMIN +to set a very low priority +.RB ( IOPRIO_CLASS_IDLE ), +but since Linux 2.6.25, this is no longer required. +.PP +A call to +.BR ioprio_set () +must follow both rules, or the call will fail with the error +.BR EPERM . +.SH BUGS +.\" 6 May 07: Bug report raised: +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464 +.\" Ulrich Drepper replied that he wasn't going to add these +.\" to glibc. +Glibc does not yet provide a suitable header file defining +the function prototypes and macros described on this page. +Suitable definitions can be found in +.IR linux/ioprio.h . +.SH SEE ALSO +.BR ionice (1), +.BR getpriority (2), +.BR open (2), +.BR capabilities (7), +.BR cgroups (7) +.PP +.I Documentation/block/ioprio.txt +in the Linux kernel source tree +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ipc.2 b/man2/ipc.2 new file mode 100644 index 0000000..34f04d3 --- /dev/null +++ b/man2/ipc.2 @@ -0,0 +1,79 @@ +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.TH IPC 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ipc \- System V IPC system calls +.SH SYNOPSIS +.nf +.BI "int ipc(unsigned int " call ", int " first ", int " second \ +", int " third , +.BI " void *" ptr ", long " fifth ); +.fi +.SH DESCRIPTION +.BR ipc () +is a common kernel entry point for the System\ V IPC calls +for messages, semaphores, and shared memory. +.I call +determines which IPC function to invoke; +the other arguments are passed through to the appropriate call. +.PP +User-space programs should call the appropriate functions by their usual names. +Only standard library implementors and kernel hackers need to know about +.BR ipc (). +.SH CONFORMING TO +.BR ipc () +is Linux-specific, and should not be used in programs +intended to be portable. +.SH NOTES +On some architectures\(emfor example x86-64 and ARM\(emthere is no +.BR ipc () +system call; instead, +.BR msgctl (2), +.BR semctl (2), +.BR shmctl (2), +and so on really are implemented as separate system calls. +.SH SEE ALSO +.BR msgctl (2), +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR semctl (2), +.BR semget (2), +.BR semop (2), +.BR semtimedop (2), +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR shmget (2), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/isastream.2 b/man2/isastream.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/isastream.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/kcmp.2 b/man2/kcmp.2 new file mode 100644 index 0000000..a735bc1 --- /dev/null +++ b/man2/kcmp.2 @@ -0,0 +1,439 @@ +.\" Copyright (C) 2012, Cyrill Gorcunov +.\" and Copyright (C) 2012, 2016, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume +.\" no responsibility for errors or omissions, or for damages resulting +.\" from the use of the information contained herein. The author(s) may +.\" not have taken the same level of care in the production of this +.\" manual, which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Kernel commit d97b46a64674a267bc41c9e16132ee2a98c3347d +.\" +.TH KCMP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +kcmp \- compare two processes to determine if they share a kernel resource +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int kcmp(pid_t " pid1 ", pid_t " pid2 ", int " type , +.BI " unsigned long " idx1 ", unsigned long " idx2 ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The +.BR kcmp () +system call can be used to check whether the two processes identified by +.I pid1 +and +.I pid2 +share a kernel resource such as virtual memory, file descriptors, +and so on. +.PP +Permission to employ +.BR kcmp () +is governed by ptrace access mode +.B PTRACE_MODE_READ_REALCREDS +checks against both +.I pid1 +and +.IR pid2 ; +see +.BR ptrace (2). +.PP +The +.I type +argument specifies which resource is to be compared in the two processes. +It has one of the following values: +.TP +.BR KCMP_FILE +Check whether a file descriptor +.I idx1 +in the process +.I pid1 +refers to the same open file description (see +.BR open (2)) +as file descriptor +.I idx2 +in the process +.IR pid2 . +The existence of two file descriptors that refer to the same +open file description can occur as a result of +.BR dup (2) +(and similar) +.BR fork (2), +or passing file descriptors via a domain socket (see +.BR unix (7)). +.TP +.BR KCMP_FILES +Check whether the processes share the same set of open file descriptors. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.BR CLONE_FILES +flag in +.BR clone (2). +.TP +.BR KCMP_FS +Check whether the processes share the same filesystem information +(i.e., file mode creation mask, working directory, and filesystem root). +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.BR CLONE_FS +flag in +.BR clone (2). +.TP +.BR KCMP_IO +Check whether the processes share I/O context. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.BR CLONE_IO +flag in +.BR clone (2). +.TP +.BR KCMP_SIGHAND +Check whether the processes share the same table of signal dispositions. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.BR CLONE_SIGHAND +flag in +.BR clone (2). +.TP +.BR KCMP_SYSVSEM +Check whether the processes share the same +list of System\ V semaphore undo operations. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.BR CLONE_SYSVSEM +flag in +.BR clone (2). +.TP +.BR KCMP_VM +Check whether the processes share the same address space. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.BR CLONE_VM +flag in +.BR clone (2). +.TP +.BR KCMP_EPOLL_TFD " (since Linux 4.13)" +.\" commit 0791e3644e5ef21646fe565b9061788d05ec71d4 +Check whether the file descriptor +.I idx1 +of the process +.I pid1 +is present in the +.BR epoll (7) +instance described by +.I idx2 +of the process +.IR pid2 . +The argument +.I idx2 +is a pointer to a structure where the target file is described. +This structure has the form: +.PP +.in +4n +.EX +struct kcmp_epoll_slot { + __u32 efd; + __u32 tfd; + __u64 toff; +}; +.EE +.in +.PP +Within this structure, +.I efd +is an epoll file descriptor returned from +.BR epoll_create (2), +.I tfd +is a target file descriptor number, and +.I toff +is a target file offset counted from zero. +Several different targets may be registered with +the same file descriptor number and setting a specific +offset helps to investigate each of them. +.PP +Note the +.BR kcmp () +is not protected against false positives which may occur if +the processes are currently running. +One should stop the processes by sending +.BR SIGSTOP +(see +.BR signal (7)) +prior to inspection with this system call to obtain meaningful results. +.SH RETURN VALUE +The return value of a successful call to +.BR kcmp () +is simply the result of arithmetic comparison +of kernel pointers (when the kernel compares resources, it uses their +memory addresses). +.PP +The easiest way to explain is to consider an example. +Suppose that +.I v1 +and +.I v2 +are the addresses of appropriate resources, then the return value +is one of the following: +.RS 4 +.IP 0 4 +.I v1 +is equal to +.IR v2 ; +in other words, the two processes share the resource. +.IP 1 +.I v1 +is less than +.IR v2 . +.IP 2 +.I v1 +is greater than +.IR v2 . +.IP 3 +.I v1 +is not equal to +.IR v2 , +but ordering information is unavailable. +.RE +.PP +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +.BR kcmp () +was designed to return values suitable for sorting. +This is particularly handy if one needs to compare +a large number of file descriptors. +.SH ERRORS +.TP +.B EBADF +.I type +is +.B KCMP_FILE +and +.I fd1 +or +.I fd2 +is not an open file descriptor. +.TP +.B EINVAL +.I type +is invalid. +.TP +.B EPERM +Insufficient permission to inspect process resources. +The +.B CAP_SYS_PTRACE +capability is required to inspect processes that you do not own. +Other ptrace limitations may also apply, such as +.BR CONFIG_SECURITY_YAMA , +which, when +.I /proc/sys/kernel/yama/ptrace_scope +is 2, limits +.BR kcmp () +to child processes; +see +.BR ptrace (2). +.TP +.B ESRCH +Process +.I pid1 +or +.I pid2 +does not exist. +.TP +.B EFAULT +The epoll slot addressed by +.I idx2 +is outside of the user's address space. +.TP +.B ENOENT +The target file is not present in +.BR epoll (7) +instance. +.SH VERSIONS +The +.BR kcmp () +system call first appeared in Linux 3.5. +.SH CONFORMING TO +.BR kcmp () +is Linux-specific and should not be used in programs intended to be portable. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.PP +This system call is available only if the kernel was configured with +.BR CONFIG_CHECKPOINT_RESTORE . +The main use of the system call is for the +checkpoint/restore in user space (CRIU) feature. +The alternative to this system call would have been to expose suitable +process information via the +.BR proc (5) +filesystem; this was deemed to be unsuitable for security reasons. +.PP +See +.BR clone (2) +for some background information on the shared resources +referred to on this page. +.SH EXAMPLE +The program below uses +.BR kcmp () +to test whether pairs of file descriptors refer to +the same open file description. +The program tests different cases for the file descriptor pairs, +as described in the program output. +An example run of the program is as follows: +.PP +.in +4n +.EX +$ \fB./a.out\fP +Parent PID is 1144 +Parent opened file on FD 3 + +PID of child of fork() is 1145 + Compare duplicate FDs from different processes: + kcmp(1145, 1144, KCMP_FILE, 3, 3) ==> same +Child opened file on FD 4 + Compare FDs from distinct open()s in same process: + kcmp(1145, 1145, KCMP_FILE, 3, 4) ==> different +Child duplicated FD 3 to create FD 5 + Compare duplicated FDs in same process: + kcmp(1145, 1145, KCMP_FILE, 3, 5) ==> same +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +static int +kcmp(pid_t pid1, pid_t pid2, int type, + unsigned long idx1, unsigned long idx2) +{ + return syscall(SYS_kcmp, pid1, pid2, type, idx1, idx2); +} + +static void +test_kcmp(char *msg, id_t pid1, pid_t pid2, int fd_a, int fd_b) +{ + printf("\\t%s\\n", msg); + printf("\\t\\tkcmp(%ld, %ld, KCMP_FILE, %d, %d) ==> %s\\n", + (long) pid1, (long) pid2, fd_a, fd_b, + (kcmp(pid1, pid2, KCMP_FILE, fd_a, fd_b) == 0) ? + "same" : "different"); +} + +int +main(int argc, char *argv[]) +{ + int fd1, fd2, fd3; + char pathname[] = "/tmp/kcmp.test"; + + fd1 = open(pathname, O_CREAT | O_RDWR, S_IRUSR | S_IWUSR); + if (fd1 == \-1) + errExit("open"); + + printf("Parent PID is %ld\\n", (long) getpid()); + printf("Parent opened file on FD %d\\n\\n", fd1); + + switch (fork()) { + case \-1: + errExit("fork"); + + case 0: + printf("PID of child of fork() is %ld\\n", (long) getpid()); + + test_kcmp("Compare duplicate FDs from different processes:", + getpid(), getppid(), fd1, fd1); + + fd2 = open(pathname, O_CREAT | O_RDWR, S_IRUSR | S_IWUSR); + if (fd2 == \-1) + errExit("open"); + printf("Child opened file on FD %d\\n", fd2); + + test_kcmp("Compare FDs from distinct open()s in same process:", + getpid(), getpid(), fd1, fd2); + + fd3 = dup(fd1); + if (fd3 == \-1) + errExit("dup"); + printf("Child duplicated FD %d to create FD %d\\n", fd1, fd3); + + test_kcmp("Compare duplicated FDs in same process:", + getpid(), getpid(), fd1, fd3); + break; + + default: + wait(NULL); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR clone (2), +.BR unshare (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/kexec_file_load.2 b/man2/kexec_file_load.2 new file mode 100644 index 0000000..6c20331 --- /dev/null +++ b/man2/kexec_file_load.2 @@ -0,0 +1 @@ +.so man2/kexec_load.2 diff --git a/man2/kexec_load.2 b/man2/kexec_load.2 new file mode 100644 index 0000000..cfe26fc --- /dev/null +++ b/man2/kexec_load.2 @@ -0,0 +1,358 @@ +.\" Copyright (C) 2010 Intel Corporation, Author: Andi Kleen +.\" and Copyright 2014, Vivek Goyal +.\" and Copyright (c) 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH KEXEC_LOAD 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +kexec_load, kexec_file_load \- load a new kernel for later execution +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long kexec_load(unsigned long " entry ", unsigned long " nr_segments "," +.BI " struct kexec_segment *" segments \ +", unsigned long " flags ");" +.PP +.BI "long kexec_file_load(int " kernel_fd ", int " initrd_fd "," +.BI " unsigned long " cmdline_len \ +", const char *" cmdline "," +.BI " unsigned long " flags ");" +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +The +.BR kexec_load () +system call loads a new kernel that can be executed later by +.BR reboot (2). +.PP +The +.I flags +argument is a bit mask that controls the operation of the call. +The following values can be specified in +.IR flags : +.TP +.BR KEXEC_ON_CRASH " (since Linux 2.6.13)" +Execute the new kernel automatically on a system crash. +This "crash kernel" is loaded into an area of reserved memory that +is determined at boot time using the +.I crashkernel +kernel command-line parameter. +The location of this reserved memory is exported to user space via the +.I /proc/iomem +file, in an entry labeled "Crash kernel". +A user-space application can parse this file and prepare a list of +segments (see below) that specify this reserved memory as destination. +If this flag is specified, the kernel checks that the +target segments specified in +.I segments +fall within the reserved region. +.TP +.BR KEXEC_PRESERVE_CONTEXT " (since Linux 2.6.27)" +Preserve the system hardware and +software states before executing the new kernel. +This could be used for system suspend. +This flag is available only if the kernel was configured with +.BR CONFIG_KEXEC_JUMP , +and is effective only if +.I nr_segments +is greater than 0. +.PP +The high-order bits (corresponding to the mask 0xffff0000) of +.I flags +contain the architecture of the to-be-executed kernel. +Specify (OR) the constant +.B KEXEC_ARCH_DEFAULT +to use the current architecture, +or one of the following architecture constants +.BR KEXEC_ARCH_386 , +.BR KEXEC_ARCH_68K , +.BR KEXEC_ARCH_X86_64 , +.BR KEXEC_ARCH_PPC , +.BR KEXEC_ARCH_PPC64 , +.BR KEXEC_ARCH_IA_64 , +.BR KEXEC_ARCH_ARM , +.BR KEXEC_ARCH_S390 , +.BR KEXEC_ARCH_SH , +.BR KEXEC_ARCH_MIPS , +and +.BR KEXEC_ARCH_MIPS_LE . +The architecture must be executable on the CPU of the system. +.PP +The +.I entry +argument is the physical entry address in the kernel image. +The +.I nr_segments +argument is the number of segments pointed to by the +.I segments +pointer; +the kernel imposes an (arbitrary) limit of 16 on the number of segments. +The +.I segments +argument is an array of +.I kexec_segment +structures which define the kernel layout: +.PP +.in +4n +.EX +struct kexec_segment { + void *buf; /* Buffer in user space */ + size_t bufsz; /* Buffer length in user space */ + void *mem; /* Physical address of kernel */ + size_t memsz; /* Physical address length */ +}; +.EE +.in +.PP +The kernel image defined by +.I segments +is copied from the calling process into +the kernel either in regular +memory or in reserved memory (if +.BR KEXEC_ON_CRASH +is set). +The kernel first performs various sanity checks on the +information passed in +.IR segments . +If these checks pass, the kernel copies the segment data to kernel memory. +Each segment specified in +.I segments +is copied as follows: +.IP * 3 +.I buf +and +.I bufsz +identify a memory region in the caller's virtual address space +that is the source of the copy. +The value in +.I bufsz +may not exceed the value in the +.I memsz +field. +.IP * +.I mem +and +.I memsz +specify a physical address range that is the target of the copy. +The values specified in both fields must be multiples of +the system page size. +.IP * +.I bufsz +bytes are copied from the source buffer to the target kernel buffer. +If +.I bufsz +is less than +.IR memsz , +then the excess bytes in the kernel buffer are zeroed out. +.PP +In case of a normal kexec (i.e., the +.BR KEXEC_ON_CRASH +flag is not set), the segment data is loaded in any available memory +and is moved to the final destination at kexec reboot time (e.g., when the +.BR kexec (8) +command is executed with the +.I \-e +option). +.PP +In case of kexec on panic (i.e., the +.BR KEXEC_ON_CRASH +flag is set), the segment data is +loaded to reserved memory at the time of the call, and, after a crash, +the kexec mechanism simply passes control to that kernel. +.PP +The +.BR kexec_load () +system call is available only if the kernel was configured with +.BR CONFIG_KEXEC . +.SS kexec_file_load() +The +.BR kexec_file_load () +system call is similar to +.BR kexec_load (), +but it takes a different set of arguments. +It reads the kernel to be loaded from the file referred to by +the file descriptor +.IR kernel_fd , +and the initrd (initial RAM disk) +to be loaded from file referred to by the file descriptor +.IR initrd_fd . +The +.IR cmdline +argument is a pointer to a buffer containing the command line +for the new kernel. +The +.IR cmdline_len +argument specifies size of the buffer. +The last byte in the buffer must be a null byte (\(aq\\0\(aq). +.PP +The +.IR flags +argument is a bit mask which modifies the behavior of the call. +The following values can be specified in +.IR flags : +.TP +.BR KEXEC_FILE_UNLOAD +Unload the currently loaded kernel. +.TP +.BR KEXEC_FILE_ON_CRASH +Load the new kernel in the memory region reserved for the crash kernel +(as for +.BR KEXEC_ON_CRASH). +This kernel is booted if the currently running kernel crashes. +.TP +.BR KEXEC_FILE_NO_INITRAMFS +Loading initrd/initramfs is optional. +Specify this flag if no initramfs is being loaded. +If this flag is set, the value passed in +.IR initrd_fd +is ignored. +.PP +The +.BR kexec_file_load () +.\" See also http://lwn.net/Articles/603116/ +system call was added to provide support for systems +where "kexec" loading should be restricted to +only kernels that are signed. +This system call is available only if the kernel was configured with +.BR CONFIG_KEXEC_FILE . +.SH RETURN VALUE +On success, these system calls returns 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EADDRNOTAVAIL +.\" See kernel/kexec.::sanity_check_segment_list in the 3.19 kernel source +The +.B KEXEC_ON_CRASH +flags was specified, but the region specified by the +.I mem +and +.I memsz +fields of one of the +.I segments +entries lies outside the range of memory reserved for the crash kernel. +.TP +.B EADDRNOTAVAIL +The value in a +.I mem +or +.I memsz +field in one of the +.I segments +entries is not a multiple of the system page size. +.TP +.B EBADF +.I kernel_fd +or +.I initrd_fd +is not a valid file descriptor. +.TP +.B EBUSY +Another crash kernel is already being loaded +or a crash kernel is already in use. +.TP +.B EINVAL +.I flags +is invalid. +.TP +.B EINVAL +The value of a +.I bufsz +field in one of the +.I segments +entries exceeds the value in the corresponding +.I memsz +field. +.TP +.B EINVAL +.IR nr_segments +exceeds +.BR KEXEC_SEGMENT_MAX +(16). +.TP +.B EINVAL +Two or more of the kernel target buffers overlap. +.TP +.B EINVAL +The value in +.I cmdline[cmdline_len-1] +is not \(aq\\0\(aq. +.TP +.B EINVAL +The file referred to by +.I kernel_fd +or +.I initrd_fd +is empty (length zero). +.TP +.B ENOEXEC +.I kernel_fd +does not refer to an open file, or the kernel can't load this file. +Currently, the file must be a bzImage and contain an x86 kernel that +is loadable above 4\ GiB in memory (see the kernel source file +.IR Documentation/x86/boot.txt ). +.TP +.B ENOMEM +Could not allocate memory. +.TP +.B EPERM +The caller does not have the +.BR CAP_SYS_BOOT +capability. +.SH VERSIONS +The +.BR kexec_load () +system call first appeared in Linux 2.6.13. +The +.BR kexec_file_load () +system call first appeared in Linux 3.17. +.SH CONFORMING TO +These system calls are Linux-specific. +.SH NOTES +Currently, there is no glibc support for these system calls. +Call them using +.BR syscall (2). +.SH SEE ALSO +.BR reboot (2), +.BR syscall (2), +.BR kexec (8) +.PP +The kernel source files +.IR Documentation/kdump/kdump.txt +and +.IR Documentation/admin-guide/kernel-parameters.txt +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/keyctl.2 b/man2/keyctl.2 new file mode 100644 index 0000000..1b55c87 --- /dev/null +++ b/man2/keyctl.2 @@ -0,0 +1,2290 @@ +.\" Copyright (C) 2016 Michael Kerrisk +.\" and Copyright (C) 2016 Eugene Syromyatnikov +.\" A very few fragments remain from an earlier version of this page +.\" written by David Howells (dhowells@redhat.com) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH KEYCTL 2 2017-09-15 Linux "Linux Key Management Calls" +.SH NAME +keyctl \- manipulate the kernel's key management facility +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "long keyctl(int " operation ", ...)" + +.B "/* For direct call via syscall(2): */" +.B #include +.B #include +.B #include +.PP +.BI "long syscall(__NR_keyctl, int " operation ", __kernel_ulong_t " arg2 , +.BI " __kernel_ulong_t " arg3 ", __kernel_ulong_t " arg4 , +.BI " __kernel_ulong_t " arg5 ); +.fi +.PP +No glibc wrapper is provided for this system call; see NOTES. +.SH DESCRIPTION +.BR keyctl () +allows user-space programs to perform key manipulation. +.PP +The operation performed by +.BR keyctl () +is determined by the value of the +.I operation +argument. +Each of these operations is wrapped by the +.I libkeyutils +library (provided by the +.I keyutils +package) into individual functions (noted below) +to permit the compiler to check types. +.PP +The permitted values for +.I operation +are: +.TP +.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)" +Map a special key ID to a real key ID for this process. +.IP +This operation looks up the special key whose ID is provided in +.I arg2 +(cast to +.IR key_serial_t ). +If the special key is found, +the ID of the corresponding real key is returned as the function result. +The following values may be specified in +.IR arg2 : +.RS +.TP +.B KEY_SPEC_THREAD_KEYRING +This specifies the calling thread's thread-specific keyring. +See +.BR thread-keyring (7). +.TP +.B KEY_SPEC_PROCESS_KEYRING +This specifies the caller's process-specific keyring. +See +.BR process-keyring (7). +.TP +.B KEY_SPEC_SESSION_KEYRING +This specifies the caller's session-specific keyring. +See +.BR session-keyring (7). +.TP +.B KEY_SPEC_USER_KEYRING +This specifies the caller's UID-specific keyring. +See +.BR user-keyring (7). +.TP +.B KEY_SPEC_USER_SESSION_KEYRING +This specifies the caller's UID-session keyring. +See +.BR user-session-keyring (7). +.TP +.BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)" +.\" commit b5f545c880a2a47947ba2118b2509644ab7a2969 +This specifies the authorization key created by +.BR request_key (2) +and passed to the process it spawns to generate a key. +This key is available only in a +.BR request-key (8)-style +program that was passed an authorization key by the kernel and +ceases to be available once the requested key has been instantiated; see +.BR request_key (2). +.TP +.BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)" +.\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 +This specifies the key ID for the +.BR request_key (2) +destination keyring. +This keyring is available only in a +.BR request-key (8)-style +program that was passed an authorization key by the kernel and +ceases to be available once the requested key has been instantiated; see +.BR request_key (2). +.RE +.IP +The behavior if the key specified in +.I arg2 +does not exist depends on the value of +.I arg3 +(cast to +.IR int ). +If +.I arg3 +contains a nonzero value, then\(emif it is appropriate to do so +(e.g., when looking up the user, user-session, or session key)\(ema new key +is created and its real key ID returned as the function result. +.\" The keyctl_get_keyring_ID.3 page says that a new key +.\" "will be created *if it is appropriate to do so**. What is the +.\" determiner for appropriate? +.\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY +.\" wouldn't get created but user/user-session/session keyring would +.\" be created. +Otherwise, the operation fails with the error +.BR ENOKEY . +.IP +If a valid key ID is specified in +.IR arg2 , +and the key exists, then this operation simply returns the key ID. +If the key does not exist, the call fails with error +.BR ENOKEY . +.IP +The caller must have +.I search +permission on a keyring in order for it to be found. +.IP +The arguments +.IR arg4 +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_get_keyring_ID (3). +.TP +.BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)" +Replace the session keyring this process subscribes to with +a new session keyring. +.\" This may be useful in conjunction with some sort of +.\" session management framework that is employed by the application. +.IP +If +.I arg2 +is NULL, +an anonymous keyring with the description "_ses" is created +and the process is subscribed to that keyring as its session keyring, +displacing the previous session keyring. +.IP +Otherwise, +.I arg2 +(cast to +.IR "char\ *" ) +is treated as the description (name) of a keyring, +and the behavior is as follows: +.RS +.IP * 3 +If a keyring with a matching description exists, +the process will attempt to subscribe to that keyring +as its session keyring if possible; +if that is not possible, an error is returned. +In order to subscribe to the keyring, +the caller must have +.I search +permission on the keyring. +.IP * +If a keyring with a matching description does not exist, +then a new keyring with the specified description is created, +and the process is subscribed to that keyring as its session keyring. +.RE +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_join_session_keyring (3). +.TP +.BR KEYCTL_UPDATE " (since Linux 2.6.10)" +Update a key's data payload. +.IP +The +.I arg2 +argument (cast to +.IR key_serial_t ) +specifies the ID of the key to be updated. +The +.I arg3 +argument (cast to +.IR "void\ *" ) +points to the new payload and +.I arg4 +(cast to +.IR size_t ) +contains the new payload size in bytes. +.IP +The caller must have +.I write +permission on the key specified and the key type must support updating. +.IP +A negatively instantiated key (see the description of +.BR KEYCTL_REJECT ) +can be positively instantiated with this operation. +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_update (3). +.TP +.BR KEYCTL_REVOKE " (since Linux 2.6.10)" +Revoke the key with the ID provided in +.I arg2 +(cast to +.IR key_serial_t ). +The key is scheduled for garbage collection; +it will no longer be findable, +and will be unavailable for further operations. +Further attempts to use the key will fail with the error +.BR EKEYREVOKED . +.IP +The caller must have +.IR write +or +.IR setattr +permission on the key. +.\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM +.\" error for KEYCTL_REVOKE. Does this need to be documented? +.\" David Howells: No significance for user space. +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_revoke (3). +.TP +.BR KEYCTL_CHOWN " (since Linux 2.6.10)" +Change the ownership (user and group ID) of a key. +.IP +The +.I arg2 +argument (cast to +.IR key_serial_t ) +contains the key ID. +The +.I arg3 +argument (cast to +.IR uid_t ) +contains the new user ID (or \-1 in case the user ID shouldn't be changed). +The +.I arg4 +argument (cast to +.IR gid_t ) +contains the new group ID (or \-1 in case the group ID shouldn't be changed). +.IP +The key must grant the caller +.I setattr +permission. +.IP +For the UID to be changed, or for the GID to be changed to a group +the caller is not a member of, the caller must have the +.B CAP_SYS_ADMIN +capability (see +.BR capabilities (7)). +.IP +If the UID is to be changed, the new user must have sufficient +quota to accept the key. +The quota deduction will be removed from the old user +to the new user should the UID be changed. +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_chown (3). +.TP +.BR KEYCTL_SETPERM " (since Linux 2.6.10)" +Change the permissions of the key with the ID provided in the +.I arg2 +argument (cast to +.IR key_serial_t ) +to the permissions provided in the +.I arg3 +argument (cast to +.IR key_perm_t ). +.IP +If the caller doesn't have the +.B CAP_SYS_ADMIN +capability, it can change permissions only for the keys it owns. +(More precisely: the caller's filesystem UID must match the UID of the key.) +.IP +The key must grant +.I setattr +permission to the caller +.IR regardless +of the caller's capabilities. +.\" FIXME Above, is it really intended that a privileged process can't +.\" override the lack of the 'setattr' permission? +.IP +The permissions in +.IR arg3 +specify masks of available operations +for each of the following user categories: +.RS +.TP +.IR possessor " (since Linux 2.6.14)" +.\" commit 664cceb0093b755739e56572b836a99104ee8a75 +This is the permission granted to a process that possesses the key +(has it attached searchably to one of the process's keyrings); +see +.BR keyrings (7). +.TP +.IR user +This is the permission granted to a process +whose filesystem UID matches the UID of the key. +.TP +.IR group +This is the permission granted to a process +whose filesystem GID or any of its supplementary GIDs +matches the GID of the key. +.TP +.IR other +This is the permission granted to other processes +that do not match the +.IR user +and +.IR group +categories. +.RE +.IP +The +.IR user , +.IR group , +and +.IR other +categories are exclusive: if a process matches the +.IR user +category, it will not receive permissions granted in the +.IR group +category; if a process matches the +.I user +or +.IR group +category, then it will not receive permissions granted in the +.IR other +category. +.IP +The +.I possessor +category grants permissions that are cumulative with the grants from the +.IR user , +.IR group , +or +.IR other +category. +.IP +Each permission mask is eight bits in size, +with only six bits currently used. +The available permissions are: +.RS +.TP +.IR view +This permission allows reading attributes of a key. +.IP +This permission is required for the +.BR KEYCTL_DESCRIBE +operation. +.IP +The permission bits for each category are +.BR KEY_POS_VIEW , +.BR KEY_USR_VIEW , +.BR KEY_GRP_VIEW , +and +.BR KEY_OTH_VIEW . +.TP +.IR read +This permission allows reading a key's payload. +.IP +This permission is required for the +.BR KEYCTL_READ +operation. +.IP +The permission bits for each category are +.BR KEY_POS_READ , +.BR KEY_USR_READ , +.BR KEY_GRP_READ , +and +.BR KEY_OTH_READ . +.TP +.IR write +This permission allows update or instantiation of a key's payload. +For a keyring, it allows keys to be linked and unlinked from the keyring, +.IP +This permission is required for the +.BR KEYCTL_UPDATE , +.BR KEYCTL_REVOKE , +.BR KEYCTL_CLEAR , +.BR KEYCTL_LINK , +and +.BR KEYCTL_UNLINK +operations. +.IP +The permission bits for each category are +.BR KEY_POS_WRITE , +.BR KEY_USR_WRITE , +.BR KEY_GRP_WRITE , +and +.BR KEY_OTH_WRITE . +.TP +.IR search +This permission allows keyrings to be searched and keys to be found. +Searches can recurse only into nested keyrings that have +.I search +permission set. +.IP +This permission is required for the +.BR KEYCTL_GET_KEYRING_ID , +.BR KEYCTL_JOIN_SESSION_KEYRING , +.BR KEYCTL_SEARCH , +and +.BR KEYCTL_INVALIDATE +operations. +.IP +The permission bits for each category are +.BR KEY_POS_SEARCH , +.BR KEY_USR_SEARCH , +.BR KEY_GRP_SEARCH , +and +.BR KEY_OTH_SEARCH . +.TP +.IR link +This permission allows a key or keyring to be linked to. +.IP +This permission is required for the +.BR KEYCTL_LINK +and +.BR KEYCTL_SESSION_TO_PARENT +operations. +.IP +The permission bits for each category are +.BR KEY_POS_LINK , +.BR KEY_USR_LINK , +.BR KEY_GRP_LINK , +and +.BR KEY_OTH_LINK . +.TP +.IR setattr " (since Linux 2.6.15)." +This permission allows a key's UID, GID, and permissions mask to be changed. +.IP +This permission is required for the +.BR KEYCTL_REVOKE , +.BR KEYCTL_CHOWN , +and +.BR KEYCTL_SETPERM +operations. +.IP +The permission bits for each category are +.BR KEY_POS_SETATTR , +.BR KEY_USR_SETATTR , +.BR KEY_GRP_SETATTR , +and +.BR KEY_OTH_SETATTR . +.RE +.IP +As a convenience, the following macros are defined as masks for +all of the permission bits in each of the user categories: +.BR KEY_POS_ALL , +.BR KEY_USR_ALL, +.BR KEY_GRP_ALL , +and +.BR KEY_OTH_ALL . +.IP +The +.IR arg4 " and " arg5 +arguments are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_setperm (3). +.TP +.BR KEYCTL_DESCRIBE " (since Linux 2.6.10)" +Obtain a string describing the attributes of a specified key. +.IP +The ID of the key to be described is specified in +.I arg2 +(cast to +.IR key_serial_t ). +The descriptive string is returned in the buffer pointed to by +.I arg3 +(cast to +.IR "char\ *" ); +.I arg4 +(cast to +.IR size_t ) +specifies the size of that buffer in bytes. +.IP +The key must grant the caller +.I view +permission. +.IP +The returned string is null-terminated and +contains the following information about the key: +.IP +.in +4n +.IR type ; uid ; gid ; perm ; description +.in +.IP +In the above, +.IR type +and +.IR description +are strings, +.IR uid +and +.IR gid +are decimal strings, and +.I perm +is a hexadecimal permissions mask. +The descriptive string is written with the following format: +.IP + %s;%d;%d;%08x;%s +.IP +.BR "Note: the intention is that the descriptive string should" +.BR "be extensible in future kernel versions". +In particular, the +.IR description +field will not contain semicolons; +.\" FIXME But, the kernel does not enforce the requirement +.\" that the key description contains no semicolons! +.\" So, user space has no guarantee here?? +.\" Either something more needs to be said here, +.\" or a kernel fix is required. +it should be parsed by working backwards from the end of the string +to find the last semicolon. +This allows future semicolon-delimited fields to be inserted +in the descriptive string in the future. +.IP +Writing to the buffer is attempted only when +.IR arg3 +is non-NULL and the specified buffer size +is large enough to accept the descriptive string +(including the terminating null byte). +'\" Function commentary says it copies up to buflen bytes, but see the +'\" (buffer && buflen >= ret) condition in keyctl_describe_key() in +'\" security/keyctl.c +In order to determine whether the buffer size was too small, +check to see if the return value of the operation is greater than +.IR arg4 . +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_describe (3). +.TP +.B KEYCTL_CLEAR +Clear the contents of (i.e., unlink all keys from) a keyring. +.IP +The ID of the key +(which must be of keyring type) +.\" or the error ENOTDIR results +is provided in +.I arg2 +(cast to +.IR key_serial_t ). +.\" According to Documentation/security/keys.txt: +.\" This function can also be used to clear special kernel keyrings if they +.\" are appropriately marked if the user has CAP_SYS_ADMIN capability. The +.\" DNS resolver cache keyring is an example of this. +.IP +The caller must have +.I write +permission on the keyring. +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_clear (3). +.TP +.BR KEYCTL_LINK " (since Linux 2.6.10)" +Create a link from a keyring to a key. +.IP +The key to be linked is specified in +.IR arg2 +(cast to +.IR key_serial_t ); +the keyring is specified in +.IR arg3 +(cast to +.IR key_serial_t ). +.IP +If a key with the same type and description is already linked in the keyring, +then that key is displaced from the keyring. +.IP +Before creating the link, +the kernel checks the nesting of the keyrings and returns appropriate errors +if the link would produce a cycle +or if the nesting of keyrings would be too deep +(The limit on the nesting of keyrings is determined by the kernel constant +.BR KEYRING_SEARCH_MAX_DEPTH , +defined with the value 6, and is necessary to prevent overflows +on the kernel stack when recursively searching keyrings). +.IP +The caller must have +.I link +permission on the key being added and +.I write +permission on the keyring. +.IP +The arguments +.IR arg4 +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_link (3). +.TP +.BR KEYCTL_UNLINK " (since Linux 2.6.10)" +Unlink a key from a keyring. +.IP +The ID of the key to be unlinked is specified in +.I arg2 +(cast to +.IR key_serial_t ); +the ID of the keyring from which it is to be unlinked is specified in +.I arg3 +(cast to +.IR key_serial_t ). +.IP +If the key is not currently linked into the keyring, an error results. +.IP +The caller must have +.I write +permission on the keyring from which the key is being removed. +.IP +If the last link to a key is removed, +then that key will be scheduled for destruction. +.IP +The arguments +.IR arg4 +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_unlink (3). +.TP +.BR KEYCTL_SEARCH " (since Linux 2.6.10)" +Search for a key in a keyring tree, +returning its ID and optionally linking it to a specified keyring. +.IP +The tree to be searched is specified by passing +the ID of the head keyring in +.IR arg2 +(cast to +.IR key_serial_t ). +The search is performed breadth-first and recursively. +.IP +The +.I arg3 +and +.I arg4 +arguments specify the key to be searched for: +.I arg3 +(cast as +.IR "char\ *" ) +contains the key type +(a null-terminated character string up to 32 bytes in size, +including the terminating null byte), and +.I arg4 +(cast as +.IR "char\ *" ) +contains the description of the key +(a null-terminated character string up to 4096 bytes in size, +including the terminating null byte). +.IP +The source keyring must grant +.I search +permission to the caller. +When performing the recursive search, only keyrings that grant the caller +.I search +permission will be searched. +Only keys with for which the caller has +.I search +permission can be found. +.IP +If the key is found, its ID is returned as the function result. +.IP +If the key is found and +.I arg5 +(cast to +.IR key_serial_t ) +is nonzero, then, subject to the same constraints and rules as +.BR KEYCTL_LINK , +the key is linked into the keyring whose ID is specified in +.IR arg5 . +If the destination keyring specified in +.I arg5 +already contains a link to a key that has the same type and description, +then that link will be displaced by a link to +the key found by this operation. +.IP +Instead of valid existing keyring IDs, the source +.RI ( arg2 ) +and destination +.RI ( arg5 ) +keyrings can be one of the special keyring IDs listed under +.BR KEYCTL_GET_KEYRING_ID . +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_search (3). +.TP +.BR KEYCTL_READ " (since Linux 2.6.10)" +Read the payload data of a key. +.IP +The ID of the key whose payload is to be read is specified in +.I arg2 +(cast to +.IR key_serial_t ). +This can be the ID of an existing key, +or any of the special key IDs listed for +.BR KEYCTL_GET_KEYRING_ID . +.\" including KEY_SPEC_REQKEY_AUTH_KEY +.IP +The payload is placed in the buffer pointed by +.I arg3 +(cast to +.IR "char\ *" ); +the size of that buffer must be specified in +.I arg4 +(cast to +.IR size_t ). +.IP +The returned data will be processed for presentation +according to the key type. +For example, a keyring will return an array of +.I key_serial_t +entries representing the IDs of all the keys that are linked to it. +The +.IR "user" +key type will return its data as is. +If a key type does not implement this function, +the operation fails with the error +.BR EOPNOTSUPP . +.IP +If +.I arg3 +is not NULL, +as much of the payload data as will fit is copied into the buffer. +On a successful return, +the return value is always the total size of the payload data. +To determine whether the buffer was of sufficient size, +check to see that the return value is less than or equal to +the value supplied in +.IR arg4 . +.IP +The key must either grant the caller +.I read +permission, or grant the caller +.I search +permission when searched for from the process keyrings +(i.e., the key is possessed). +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_read (3). +.TP +.BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)" +(Positively) instantiate an uninstantiated key with a specified payload. +.IP +The ID of the key to be instantiated is provided in +.I arg2 +(cast to +.IR key_serial_t ). +.IP +The key payload is specified in the buffer pointed to by +.I arg3 +(cast to +.IR "void\ *"); +the size of that buffer is specified in +.I arg4 +(cast to +.IR size_t ). +.IP +The payload may be a NULL pointer and the buffer size may be 0 +if this is supported by the key type (e.g., it is a keyring). +.IP +The operation may be fail if the payload data is in the wrong format +or is otherwise invalid. +.IP +If +.I arg5 +(cast to +.IR key_serial_t ) +is nonzero, then, subject to the same constraints and rules as +.BR KEYCTL_LINK , +the instantiated key is linked into the keyring whose ID specified in +.IR arg5 . +.IP +The caller must have the appropriate authorization key, +and once the uninstantiated key has been instantiated, +the authorization key is revoked. +In other words, this operation is available only from a +.BR request-key (8)-style +program. +See +.BR request_key (2) +for an explanation of uninstantiated keys and key instantiation. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_instantiate (3). +.TP +.BR KEYCTL_NEGATE " (since Linux 2.6.10)" +Negatively instantiate an uninstantiated key. +.IP +This operation is equivalent to the call: +.IP + keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4); +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_negate (3). +.TP +.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)" +Set the default keyring to which implicitly requested keys +will be linked for this thread, and return the previous setting. +Implicit key requests are those made by internal kernel components, +.\" I.e., calls to the kernel's internal request_key() interface, +.\" which is distinct from the request_key(2) system call (which +.\" ultimately employs the kernel-internal interface). +such as can occur when, for example, opening files +on an AFS or NFS filesystem. +Setting the default keyring also has an effect when requesting +a key from user space; see +.BR request_key (2) +for details. +.IP +The +.I arg2 +argument (cast to +.IR int ) +should contain one of the following values, +to specify the new default keyring: +.RS +.TP +.BR KEY_REQKEY_DEFL_NO_CHANGE +Don't change the default keyring. +This can be used to discover the current default keyring +(without changing it). +.TP +.BR KEY_REQKEY_DEFL_DEFAULT +This selects the default behaviour, +which is to use the thread-specific keyring if there is one, +otherwise the process-specific keyring if there is one, +otherwise the session keyring if there is one, +otherwise the UID-specific session keyring, +otherwise the user-specific keyring. +.TP +.BR KEY_REQKEY_DEFL_THREAD_KEYRING +Use the thread-specific keyring +.RB ( thread-keyring (7)) +as the new default keyring. +.TP +.BR KEY_REQKEY_DEFL_PROCESS_KEYRING +Use the process-specific keyring +.RB ( process-keyring (7)) +as the new default keyring. +.TP +.BR KEY_REQKEY_DEFL_SESSION_KEYRING +Use the session-specific keyring +.RB ( session-keyring (7)) +as the new default keyring. +.TP +.BR KEY_REQKEY_DEFL_USER_KEYRING +Use the UID-specific keyring +.RB ( user-keyring (7)) +as the new default keyring. +.TP +.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING +Use the UID-specific session keyring +.RB ( user-session-keyring (7)) +as the new default keyring. +.TP +.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)" +'\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 +Use the requestor keyring. +.\" FIXME The preceding explanation needs to be expanded. +.\" Is the following correct: +.\" +.\" The requestor keyring is the dest_keyring that +.\" was supplied to a call to request_key(2)? +.\" +.\" David Howells said: to be checked +.RE +.IP +All other values are invalid. +.\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING) +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.IP +The setting controlled by this operation is inherited by the child of +.BR fork (2) +and preserved across +.BR execve (2). +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_set_reqkey_keyring (3). +.TP +.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)" +Set a timeout on a key. +.IP +The ID of the key is specified in +.I arg2 +(cast to +.IR key_serial_t ). +The timeout value, in seconds from the current time, +is specified in +.I arg3 +(cast to +.IR "unsigned int" ). +The timeout is measured against the realtime clock. +.IP +Specifying the timeout value as 0 clears any existing timeout on the key. +.IP +The +.I /proc/keys +file displays the remaining time until each key will expire. +(This is the only method of discovering the timeout on a key.) +.IP +The caller must either have the +.I setattr +permission on the key +or hold an instantiation authorization token for the key (see +.BR request_key (2)). +.IP +The key and any links to the key will be +automatically garbage collected after the timeout expires. +Subsequent attempts to access the key will then fail with the error +.BR EKEYEXPIRED . +.IP +This operation cannot be used to set timeouts on revoked, expired, +or negatively instantiated keys. +.IP +The arguments +.IR arg4 +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_set_timeout (3). +.TP +.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" +Assume (or divest) the authority for the calling thread +to instantiate a key. +.IP +The +.I arg2 +argument (cast to +.IR key_serial_t ) +specifies either a nonzero key ID to assume authority, +or the value 0 to divest authority. +.IP +If +.I arg2 +is nonzero, then it specifies the ID of an uninstantiated key for which +authority is to be assumed. +That key can then be instantiated using one of +.BR KEYCTL_INSTANTIATE , +.BR KEYCTL_INSTANTIATE_IOV , +.BR KEYCTL_REJECT , +or +.BR KEYCTL_NEGATE . +Once the key has been instantiated, +the thread is automatically divested of authority to instantiate the key. +.IP +Authority over a key can be assumed only if the calling thread has present +in its keyrings the authorization key that is +associated with the specified key. +(In other words, the +.BR KEYCTL_ASSUME_AUTHORITY +operation is available only from a +.BR request-key (8)-style +program; see +.BR request_key (2) +for an explanation of how this operation is used.) +The caller must have +.I search +permission on the authorization key. +.IP +If the specified key has a matching authorization key, +then the ID of that key is returned. +The authorization key can be read +.RB ( KEYCTL_READ ) +to obtain the callout information passed to +.BR request_key (2). +.IP +If the ID given in +.I arg2 +is 0, then the currently assumed authority is cleared (divested), +and the value 0 is returned. +.IP +The +.BR KEYCTL_ASSUME_AUTHORITY +mechanism allows a program such as +.BR request-key (8) +to assume the necessary authority to instantiate a new uninstantiated key +that was created as a consequence of a call to +.BR request_key (2). +For further information, see +.BR request_key (2) +and the kernel source file +.IR Documentation/security/keys-request-key.txt . +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_assume_authority (3). +.TP +.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)" +.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d +Get the LSM (Linux Security Module) security label of the specified key. +.IP +The ID of the key whose security label is to be fetched is specified in +.I arg2 +(cast to +.IR key_serial_t ). +The security label (terminated by a null byte) +will be placed in the buffer pointed to by +.I arg3 +argument (cast to +.IR "char\ *" ); +the size of the buffer must be provided in +.I arg4 +(cast to +.IR size_t ). +.IP +If +.I arg3 +is specified as NULL or the buffer size specified in +.IR arg4 +is too small, the full size of the security label string +(including the terminating null byte) +is returned as the function result, +and nothing is copied to the buffer. +.IP +The caller must have +.I view +permission on the specified key. +.IP +The returned security label string will be rendered in a form appropriate +to the LSM in force. +For example, with SELinux, it may look like: +.IP + unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 +.IP +If no LSM is currently in force, +then an empty string is placed in the buffer. +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the functions +.BR keyctl_get_security (3) +and +.BR keyctl_get_security_alloc (3). +.TP +.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)" +.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f +Replace the session keyring to which the +.I parent +of the calling process +subscribes with the session keyring of the calling process. +.\" What is the use case for KEYCTL_SESSION_TO_PARENT? +.\" David Howells: the Process Authentication Groups people requested this, +.\" but then didn't use it; maybe there are no users. +.IP +The keyring will be replaced in the parent process at the point +where the parent next transitions from kernel space to user space. +.IP +The keyring must exist and must grant the caller +.I link +permission. +The parent process must be single-threaded and have +the same effective ownership as this process +and must not be set-user-ID or set-group-ID. +The UID of the parent process's existing session keyring (f it has one), +as well as the UID of the caller's session keyring +much match the caller's effective UID. +.IP +The fact that it is the parent process that is affected by this operation +allows a program such as the shell to start a child process that +uses this operation to change the shell's session keyring. +(This is what the +.BR keyctl (1) +.B new_session +command does.) +.IP +The arguments +.IR arg2 , +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_session_to_parent (3). +.TP +.BR KEYCTL_REJECT " (since Linux 2.6.39)" +.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c +Mark a key as negatively instantiated and set an expiration timer +on the key. +This operation provides a superset of the functionality of the earlier +.BR KEYCTL_NEGATE +operation. +.IP +The ID of the key that is to be negatively instantiated is specified in +.I arg2 +(cast to +.IR key_serial_t ). +The +.I arg3 +(cast to +.IR "unsigned int" ) +argument specifies the lifetime of the key, in seconds. +The +.I arg4 +argument (cast to +.IR "unsigned int" ) +specifies the error to be returned when a search hits this key; +typically, this is one of +.BR EKEYREJECTED , +.BR EKEYREVOKED , +or +.BR EKEYEXPIRED . +.IP +If +.I arg5 +(cast to +.IR key_serial_t ) +is nonzero, then, subject to the same constraints and rules as +.BR KEYCTL_LINK , +the negatively instantiated key is linked into the keyring +whose ID is specified in +.IR arg5 . +.IP +The caller must have the appropriate authorization key. +In other words, this operation is available only from a +.BR request-key (8)-style +program. +See +.BR request_key (2). +.IP +The caller must have the appropriate authorization key, +and once the uninstantiated key has been instantiated, +the authorization key is revoked. +In other words, this operation is available only from a +.BR request-key (8)-style +program. +See +.BR request_key (2) +for an explanation of uninstantiated keys and key instantiation. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_reject (3). +.TP +.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)" +.\" commit ee009e4a0d4555ed522a631bae9896399674f063 +Instantiate an uninstantiated key with a payload specified +via a vector of buffers. +.IP +This operation is the same as +.BR KEYCTL_INSTANTIATE , +but the payload data is specified as an array of +.IR iovec +structures: +.IP +.in +4n +.EX +struct iovec { + void *iov_base; /* Starting address of buffer */ + size_t iov_len; /* Size of buffer (in bytes) */ +}; +.EE +.in +.IP +The pointer to the payload vector is specified in +.IR arg3 +(cast as +.IR "const struct iovec\ *" ). +The number of items in the vector is specified in +.IR arg4 +(cast as +.IR "unsigned int" ). +.IP +The +.I arg2 +(key ID) +and +.I arg5 +(keyring ID) +are interpreted as for +.BR KEYCTL_INSTANTIATE . +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_instantiate_iov (3). +.TP +.BR KEYCTL_INVALIDATE " (since Linux 3.5)" +.\" commit fd75815f727f157a05f4c96b5294a4617c0557da +Mark a key as invalid. +.IP +The ID of the key to be invalidated is specified in +.I arg2 +(cast to +.IR key_serial_t ). +.IP +To invalidate a key, +the caller must have +.I search +permission on the key. +.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys +.IP +This operation marks the key as invalid +and schedules immediate garbage collection. +The garbage collector removes the invalidated key from all keyrings and +deletes the key when its reference count reaches zero. +After this operation, +the key will be ignored by all searches, +even if it is not yet deleted. +.IP +Keys that are marked invalid become invisible to normal key operations +immediately, though they are still visible in +.I /proc/keys +(marked with an 'i' flag) +until they are actually removed. +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_invalidate (3). +.TP +.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)" +.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e +Get the persistent keyring +.RB ( persistent-keyring (7)) +for a specified user and link it to a specified keyring. +.IP +The user ID is specified in +.I arg2 +(cast to +.IR uid_t ). +If the value \-1 is specified, the caller's real user ID is used. +The ID of the destination keyring is specified in +.I arg3 +(cast to +.IR key_serial_t ). +.IP +The caller must have the +.BR CAP_SETUID +capability in its user namespace in order to fetch the persistent keyring +for a user ID that does not match either the real or effective user ID +of the caller. +.IP +If the call is successful, +a link to the persistent keyring is added to the keyring +whose ID was specified in +.IR arg3 . +.IP +The caller must have +.I write +permission on the keyring. +.IP +The persistent keyring will be created by the kernel +if it does not yet exist. +.IP +Each time the +.B KEYCTL_GET_PERSISTENT +operation is performed, the persistent keyring will +have its expiration timeout reset to the value in: +.IP +.in +4n +.EX +/proc/sys/kernel/keys/persistent_keyring_expiry +.EE +.in +.IP +Should the timeout be reached, +the persistent keyring will be removed and +everything it pins can then be garbage collected. +.IP +Persistent keyrings were added to Linux in kernel version 3.13. +.IP +The arguments +.IR arg4 +and +.IR arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_get_persistent (3). +.TP +.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)" +.\" commit ddbb41148724367394d0880c516bfaeed127b52e +Compute a Diffie-Hellman shared secret or public key, +optionally applying key derivation function (KDF) to the result. +.IP +The +.I arg2 +argument is a pointer to a set of parameters containing +serial numbers for three +.IR """user""" +keys used in the Diffie-Hellman calculation, +packaged in a structure of the following form: +.IP +.in +4n +.EX +struct keyctl_dh_params { + int32_t private; /* The local private key */ + int32_t prime; /* The prime, known to both parties */ + int32_t base; /* The base integer: either a shared + generator or the remote public key */ +}; +.EE +.in +.IP +Each of the three keys specified in this structure must grant the caller +.I read +permission. +The payloads of these keys are used to calculate the Diffie-Hellman +result as: +.IP + base ^ private mod prime +.IP +If the base is the shared generator, the result is the local public key. +If the base is the remote public key, the result is the shared secret. +.IP +The +.I arg3 +argument (cast to +.IR "char\ *" ) +points to a buffer where the result of the calculation is placed. +The size of that buffer is specified in +.I arg4 +(cast to +.IR size_t ). +.IP +The buffer must be large enough to accommodate the output data, +otherwise an error is returned. +If +.I arg4 +is specified zero, +in which case the buffer is not used and +the operation returns the minimum required buffer size +(i.e., the length of the prime). +.IP +Diffie-Hellman computations can be performed in user space, +but require a multiple-precision integer (MPI) library. +Moving the implementation into the kernel gives access to +the kernel MPI implementation, +and allows access to secure or acceleration hardware. +.IP +Adding support for DH computation to the +.BR keyctl() +system call was considered a good fit due to the DH algorithm's use +for deriving shared keys; +it also allows the type of the key to determine +which DH implementation (software or hardware) is appropriate. +.\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8 +.IP +If the +.I arg5 +argument is +.BR NULL , +then the DH result itself is returned. +Otherwise (since Linux 4.12), it is a pointer to a structure which specifies +parameters of the KDF operation to be applied: +.IP +.in +4n +.EX +struct keyctl_kdf_params { + char *hashname; /* Hash algorithm name */ + char *otherinfo; /* SP800-56A OtherInfo */ + __u32 otherinfolen; /* Length of otherinfo data */ + __u32 __spare[8]; /* Reserved */ +}; +.EE +.in +.IP +The +.I hashname +field is a null-terminated string which specifies a hash name +(available in the kernel's crypto API; the list of the hashes available +is rather tricky to observe; please refer to the +.UR https://www.kernel.org\:/doc\:/html\:/latest\:/crypto\:/architecture.html +"Kernel Crypto API Architecture" +.UE +documentation for the information regarding how hash names are constructed and +your kernel's source and configuration regarding what ciphers +and templates with type +.B CRYPTO_ALG_TYPE_SHASH +are available) +to be applied to DH result in KDF operation. +.IP +The +.I otherinfo +field is an +.I OtherInfo +data as described in SP800-56A section 5.8.1.2 and is algorithm-specific. +This data is concatenated with the result of DH operation and is provided as +an input to the KDF operation. +Its size is provided in the +.I otherinfolen +field and is limited by +.B KEYCTL_KDF_MAX_OI_LEN +constant that defined in +.I security/keys/internal.h +to a value of 64. +.IP +The +.B __spare +field is currently unused. +.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 +It was ignored until Linux 4.13 (but still should be +user-addressable since it is copied to the kernel), +and should contain zeroes since Linux 4.13. +.IP +The KDF implementation complies with SP800-56A as well +as with SP800-108 (the counter KDF). +.IP +.\" keyutils commit 742c9d7b94051d3b21f9f61a73ed6b5f3544cb82 +.\" keyutils commit d68a981e5db41d059ac782071c35d1e8f3aaf61c +This operation is exposed by +.I libkeyutils +(from version 1.5.10 onwards) via the functions +.BR keyctl_dh_compute (3) +and +.BR keyctl_dh_compute_alloc (3). +.TP +.BR KEYCTL_RESTRICT_KEYRING " (since Linux 4.12)" +.\" commit 6563c91fd645556c7801748f15bc727c77fcd311 +.\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9 +Apply a key-linking restriction to the keyring with the ID provided in +.IR arg2 +(cast to +.IR key_serial_t ). +The caller must have +.IR setattr +permission on the key. +If +.I arg3 +is NULL, any attempt to add a key to the keyring is blocked; +otherwise it contains a pointer to a string with a key type name and +.I arg4 +contains a pointer to string that describes the type-specific restriction. +As of Linux 4.12, only the type "asymmetric" has restrictions defined: +.RS +.TP +.B builtin_trusted +Allows only keys that are signed by a key linked to the builtin keyring +(".builtin_trusted_keys"). +.TP +.B builtin_and_secondary_trusted +Allows only keys that are signed by a key linked to the secondary keyring +(".secondary_trusted_keys") or, by extension, a key in a builtin keyring, +as the latter is linked to the former. +.TP +.BI key_or_keyring: key +.TQ +.BI key_or_keyring: key :chain +If +.I key +specifies the ID of a key of type "asymmetric", +then only keys that are signed by this key are allowed. +.IP +If +.I key +specifies the ID of a keyring, +then only keys that are signed by a key linked +to this keyring are allowed. +.IP +If ":chain" is specified, keys that are signed by a keys linked to the +destination keyring (that is, the keyring with the ID specified in the +.I arg2 +argument) are also allowed. +.RE +.IP +Note that a restriction can be configured only once for the specified keyring; +once a restriction is set, it can't be overridden. +.IP +The argument +.I arg5 +is ignored. +.SH RETURN VALUE +For a successful call, the return value depends on the operation: +.TP +.B KEYCTL_GET_KEYRING_ID +The ID of the requested keyring. +.TP +.B KEYCTL_JOIN_SESSION_KEYRING +The ID of the joined session keyring. +.TP +.B KEYCTL_DESCRIBE +The size of the description (including the terminating null byte), +irrespective of the provided buffer size. +.TP +.B KEYCTL_SEARCH +The ID of the key that was found. +.TP +.B KEYCTL_READ +The amount of data that is available in the key, +irrespective of the provided buffer size. +.TP +.B KEYCTL_SET_REQKEY_KEYRING +The ID of the previous default keyring +to which implicitly requested keys were linked +(one of +.BR KEY_REQKEY_DEFL_USER_* ). +.TP +.B KEYCTL_ASSUME_AUTHORITY +Either 0, if the ID given was 0, +or the ID of the authorization key matching the specified key, +if a nonzero key ID was provided. +.TP +.B KEYCTL_GET_SECURITY +The size of the LSM security label string +(including the terminating null byte), +irrespective of the provided buffer size. +.TP +.B KEYCTL_GET_PERSISTENT +The ID of the persistent keyring. +.TP +.B KEYCTL_DH_COMPUTE +The number of bytes copied to the buffer, or, if +.I arg4 +is 0, the required buffer size. +.TP +All other operations +Zero. +.PP +On error, \-1 is returned, and +.I errno +is set appropriately to indicate the error. +.SH ERRORS +.TP +.B EACCES +The requested operation wasn't permitted. +.TP +.B EAGAIN +.I operation +was +.B KEYCTL_DH_COMPUTE +and there was an error during crypto module initialisation. +.TP +.B EDEADLK +.I operation +was +.BR KEYCTL_LINK +and the requested link would result in a cycle. +.TP +.B EDEADLK +.I operation +was +.BR KEYCTL_RESTRICT_KEYRING +and the requested keyring restriction would result in a cycle. +.TP +.B EDQUOT +The key quota for the caller's user would be exceeded by creating a key or +linking it to the keyring. +.TP +.B EEXIST +.I operation +was +.BR KEYCTL_RESTRICT_KEYRING +and keyring provided in +.I arg2 +argument already has a restriction set. +.TP +.B EFAULT +.I operation +was +.B KEYCTL_DH_COMPUTE +and one of the following has failed: +.RS +.IP \(bu 3 +copying of the +.IR "struct keyctl_dh_params" , +provided in the +.I arg2 +argument, from user space; +.IP \(bu +copying of the +.IR "struct keyctl_kdf_params" , +provided in the non-NULL +.I arg5 +argument, from user space +(in case kernel supports performing KDF operation on DH operation result); +.IP \(bu +copying of data pointed by the +.I hashname +field of the +.I "struct keyctl_kdf_params" +from user space; +.IP \(bu +copying of data pointed by the +.I otherinfo +field of the +.I struct keyctl_kdf_params +from user space if the +.I otherinfolen +field was nonzero; +.IP \(bu +copying of the result to user space. +.RE +.TP +.B EINVAL +.I operation +was +.B KEYCTL_SETPERM +and an invalid permission bit was specified in +.IR arg3 . +.TP +.B EINVAL +.I operation +was +.BR KEYCTL_SEARCH +and the size of the description in +.IR arg4 +(including the terminating null byte) exceeded 4096 bytes. +size of the string (including the terminating null byte) specified in +.I arg3 +(the key type) +or +.I arg4 +(the key description) +exceeded the limit (32 bytes and 4096 bytes respectively). +.TP +.BR EINVAL " (Linux kernels before 4.12)" +.I operation +was +.BR KEYCTL_DH_COMPUTE , +argument +.I arg5 +was non-NULL. +.TP +.B EINVAL +.I operation +was +.B KEYCTL_DH_COMPUTE +And the digest size of the hashing algorithm supplied is zero. +.TP +.B EINVAL +.I operation +was +.B KEYCTL_DH_COMPUTE +and the buffer size provided is not enough to hold the result. +Provide 0 as a buffer size in order to obtain the minimum buffer size. +.TP +.B EINVAL +.I operation +was +.B KEYCTL_DH_COMPUTE +and the hash name provided in the +.I hashname +field of the +.I struct keyctl_kdf_params +pointed by +.I arg5 +argument is too big (the limit is implementation-specific and varies between +kernel versions, but it is deemed big enough for all valid algorithm names). +.TP +.B EINVAL +.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 +.I operation +was +.B KEYCTL_DH_COMPUTE +and the +.I __spare +field of the +.I struct keyctl_kdf_params +provided in the +.I arg5 +argument contains nonzero values. +.TP +.B EKEYEXPIRED +An expired key was found or specified. +.TP +.B EKEYREJECTED +A rejected key was found or specified. +.TP +.B EKEYREVOKED +A revoked key was found or specified. +.TP +.B ELOOP +.I operation +was +.BR KEYCTL_LINK +and the requested link would cause the maximum nesting depth +for keyrings to be exceeded. +.TP +.B EMSGSIZE +.I operation +was +.B KEYCTL_DH_COMPUTE +and the buffer length exceeds +.B KEYCTL_KDF_MAX_OUTPUT_LEN +(which is 1024 currently) +or the +.I otherinfolen +field of the +.I struct keyctl_kdf_parms +passed in +.I arg5 +exceeds +.B KEYCTL_KDF_MAX_OI_LEN +(which is 64 currently). +.TP +.BR ENFILE " (Linux kernels before 3.13)" +.IR operation +was +.BR KEYCTL_LINK +and the keyring is full. +(Before Linux 3.13, +.\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69 +the available space for storing keyring links was limited to +a single page of memory; since Linux 3.13, there is no fixed limit.) +.TP +.B ENOENT +.I operation +was +.B KEYCTL_UNLINK +and the key to be unlinked isn't linked to the keyring. +.TP +.B ENOENT +.I operation +was +.B KEYCTL_DH_COMPUTE +and the hashing algorithm specified in the +.I hashname +field of the +.I struct keyctl_kdf_params +pointed by +.I arg5 +argument hasn't been found. +.TP +.B ENOENT +.I operation +was +.B KEYCTL_RESTRICT_KEYRING +and the type provided in +.I arg3 +argument doesn't support setting key linking restrictions. +.TP +.B ENOKEY +No matching key was found or an invalid key was specified. +.TP +.B ENOKEY +The value +.B KEYCTL_GET_KEYRING_ID +was specified in +.IR operation , +the key specified in +.I arg2 +did not exist, and +.I arg3 +was zero (meaning don't create the key if it didn't exist). +.TP +.B ENOMEM +One of kernel memory allocation routines failed during the execution of the +syscall. +.TP +.B ENOTDIR +A key of keyring type was expected but the ID of a key with +a different type was provided. +.TP +.B EOPNOTSUPP +.I operation +was +.B KEYCTL_READ +and the key type does not support reading +(e.g., the type is +.IR """login""" ). +.TP +.B EOPNOTSUPP +.I operation +was +.B KEYCTL_UPDATE +and the key type does not support updating. +.TP +.B EOPNOTSUPP +.I operation +was +.BR KEYCTL_RESTRICT_KEYRING , +the type provided in +.I arg3 +argument was "asymmetric", and the key specified in the restriction specification +provided in +.I arg4 +has type other than "asymmetric" or "keyring". +.TP +.B EPERM +.I operation +was +.BR KEYCTL_GET_PERSISTENT , +.I arg2 +specified a UID other than the calling thread's real or effective UID, +and the caller did not have the +.B CAP_SETUID +capability. +.TP +.B EPERM +.I operation +was +.BR KEYCTL_SESSION_TO_PARENT +and either: +all of the UIDs (GIDs) of the parent process do not match +the effective UID (GID) of the calling process; +the UID of the parent's existing session keyring or +the UID of the caller's session keyring did not match +the effective UID of the caller; +the parent process is not single-thread; +or the parent process is +.BR init (1) +or a kernel thread. +.TP +.B ETIMEDOUT +.I operation +was +.B KEYCTL_DH_COMPUTE +and the initialisation of crypto modules has timed out. +.SH VERSIONS +This system call first appeared in Linux 2.6.10. +.SH CONFORMING TO +This system call is a nonstandard Linux extension. +.SH NOTES +No wrapper for this system call is provided in glibc. +A wrapper is provided in the +.IR libkeyutils +library. +When employing the wrapper in that library, link with +.IR \-lkeyutils . +However, rather than using this system call directly, +you probably want to use the various library functions +mentioned in the descriptions of individual operations above. +.SH EXAMPLE +The program below provide subset of the functionality of the +.BR request-key (8) +program provided by the +.I keyutils +package. +For informational purposes, +the program records various information in a log file. +.PP +As described in +.BR request_key (2), +the +.BR request-key (8) +program is invoked with command-line arguments that +describe a key that is to be instantiated. +The example program fetches and logs these arguments. +The program assumes authority to instantiate the requested key, +and then instantiates that key. +.PP +The following shell session demonstrates the use of this program. +In the session, +we compile the program and then use it to temporarily replace the standard +.BR request-key (8) +program. +(Note that temporarily disabling the standard +.BR request-key (8) +program may not be safe on some systems.) +While our example program is installed, +we use the example program shown in +.BR request_key (2) +to request a key. +.PP +.in +4n +.EX +$ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP +$ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP +$ \fBsudo cp key_instantiate /sbin/request\-key\fP +$ \fB./t_request_key user mykey somepayloaddata\fP +Key ID is 20d035bf +$ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP +.EE +.in +.PP +Looking at the log file created by this program, +we can see the command-line arguments supplied to our example program: +.PP +.in +4n +.EX +$ \fBcat /tmp/key_instantiate.log \fP +Time: Mon Nov 7 13:06:47 2016 + +Command line arguments: + argv[0]: /sbin/request-key + operation: create + key_to_instantiate: 20d035bf + UID: 1000 + GID: 1000 + thread_keyring: 0 + process_keyring: 0 + session_keyring: 256e6a6 + +Key description: user;1000;1000;3f010000;mykey +Auth key payload: somepayloaddata +Destination keyring: 256e6a6 +Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf +.EE +.in +.PP +The last few lines of the above output show that the example program +was able to fetch: +.IP * 3 +the description of the key to be instantiated, +which included the name of the key +.RI ( mykey ); +.IP * +the payload of the authorization key, which consisted of the data +.RI ( somepayloaddata ) +passed to +.BR request_key (2); +.IP * +the destination keyring that was specified in the call to +.BR request_key (2); +and +.IP * +the description of the authorization key, +where we can see that the name of the authorization key matches +the ID of the key that is to be instantiated +.RI ( 20d035bf ). +.PP +The example program in +.BR request_key (2) +specified the destination keyring as +.BR KEY_SPEC_SESSION_KEYRING . +By examining the contents of +.IR /proc/keys , +we can see that this was translated to the ID of the destination keyring +.RI ( 0256e6a6 ) +shown in the log output above; +we can also see the newly created key with the name +.IR mykey +and ID +.IR 20d035bf . +.PP +.in +4n +.EX +$ \fBcat /proc/keys | egrep \(aqmykey|256e6a6\(aq\fP +0256e6a6 I\-\-Q\-\-\- 194 perm 3f030000 1000 1000 keyring _ses: 3 +20d035bf I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 16 +.EE +.in +.SS Program source +\& +.EX +/* key_instantiate.c */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#ifndef KEY_SPEC_REQUESTOR_KEYRING +#define KEY_SPEC_REQUESTOR_KEYRING \-8 +#endif + +int +main(int argc, char *argv[]) +{ + FILE *fp; + time_t t; + char *operation; + key_serial_t key_to_instantiate, dest_keyring; + key_serial_t thread_keyring, process_keyring, session_keyring; + uid_t uid; + gid_t gid; + char dbuf[256]; + char auth_key_payload[256]; + int akp_size; /* Size of auth_key_payload */ + + fp = fopen("/tmp/key_instantiate.log", "w"); + if (fp == NULL) + exit(EXIT_FAILURE); + + setbuf(fp, NULL); + + t = time(NULL); + fprintf(fp, "Time: %s\\n", ctime(&t)); + + /* + * The kernel passes a fixed set of arguments to the program + * that it execs; fetch them. + */ + operation = argv[1]; + key_to_instantiate = atoi(argv[2]); + uid = atoi(argv[3]); + gid = atoi(argv[4]); + thread_keyring = atoi(argv[5]); + process_keyring = atoi(argv[6]); + session_keyring = atoi(argv[7]); + + fprintf(fp, "Command line arguments:\\n"); + fprintf(fp, " argv[0]: %s\\n", argv[0]); + fprintf(fp, " operation: %s\\n", operation); + fprintf(fp, " key_to_instantiate: %lx\\n", + (long) key_to_instantiate); + fprintf(fp, " UID: %ld\\n", (long) uid); + fprintf(fp, " GID: %ld\\n", (long) gid); + fprintf(fp, " thread_keyring: %lx\\n", (long) thread_keyring); + fprintf(fp, " process_keyring: %lx\\n", (long) process_keyring); + fprintf(fp, " session_keyring: %lx\\n", (long) session_keyring); + fprintf(fp, "\\n"); + + /* + * Assume the authority to instantiate the key named in argv[2] + */ + if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) { + fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\\n", + strerror(errno)); + exit(EXIT_FAILURE); + } + + /* + * Fetch the description of the key that is to be instantiated + */ + if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate, + dbuf, sizeof(dbuf)) == \-1) { + fprintf(fp, "KEYCTL_DESCRIBE failed: %s\\n", strerror(errno)); + exit(EXIT_FAILURE); + } + + fprintf(fp, "Key description: %s\\n", dbuf); + + /* + * Fetch the payload of the authorization key, which is + * actually the callout data given to request_key() + */ + akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY, + auth_key_payload, sizeof(auth_key_payload)); + if (akp_size == \-1) { + fprintf(fp, "KEYCTL_READ failed: %s\\n", strerror(errno)); + exit(EXIT_FAILURE); + } + + auth_key_payload[akp_size] = \(aq\\0\(aq; + fprintf(fp, "Auth key payload: %s\\n", auth_key_payload); + + /* + * For interest, get the ID of the authorization key and + * display it. + */ + auth_key = keyctl(KEYCTL_GET_KEYRING_ID, + KEY_SPEC_REQKEY_AUTH_KEY); + if (auth_key == \-1) { + fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\\n", + strerror(errno)); + exit(EXIT_FAILURE); + } + + fprintf(fp, "Auth key ID: %lx\\n", (long) auth_key); + + /* + * Fetch key ID for the request_key(2) destination keyring. + */ + dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID, + KEY_SPEC_REQUESTOR_KEYRING); + if (dest_keyring == \-1) { + fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\\n", + strerror(errno)); + exit(EXIT_FAILURE); + } + + fprintf(fp, "Destination keyring: %lx\\n", (long) dest_keyring); + + /* + * Fetch the description of the authorization key. This + * allows us to see the key type, UID, GID, permissions, + * and description (name) of the key. Among other things, + * we will see that the name of the key is a hexadecimal + * string representing the ID of the key to be instantiated. + */ + if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY, + dbuf, sizeof(dbuf)) == \-1) { + fprintf(fp, "KEYCTL_DESCRIBE failed: %s\\n", strerror(errno)); + exit(EXIT_FAILURE); + } + + fprintf(fp, "Auth key description: %s\\n", dbuf); + + /* + * Instantiate the key using the callout data that was supplied + * in the payload of the authorization key. + */ + if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate, + auth_key_payload, akp_size + 1, dest_keyring) == \-1) { + fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\\n", + strerror(errno)); + exit(EXIT_FAILURE); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR request_key (2), +.\" .BR find_key_by_type_and_name (3) +.\" There is a man page, but this function seems not to exist +.BR keyctl (3), +.BR keyctl_assume_authority (3), +.BR keyctl_chown (3), +.BR keyctl_clear (3), +.BR keyctl_describe (3), +.BR keyctl_describe_alloc (3), +.BR keyctl_dh_compute (3), +.BR keyctl_dh_compute_alloc (3), +.BR keyctl_get_keyring_ID (3), +.BR keyctl_get_persistent (3), +.BR keyctl_get_security (3), +.BR keyctl_get_security_alloc (3), +.BR keyctl_instantiate (3), +.BR keyctl_instantiate_iov (3), +.BR keyctl_invalidate (3), +.BR keyctl_join_session_keyring (3), +.BR keyctl_link (3), +.BR keyctl_negate (3), +.BR keyctl_read (3), +.BR keyctl_read_alloc (3), +.BR keyctl_reject (3), +.BR keyctl_revoke (3), +.BR keyctl_search (3), +.BR keyctl_session_to_parent (3), +.BR keyctl_set_reqkey_keyring (3), +.BR keyctl_set_timeout (3), +.BR keyctl_setperm (3), +.BR keyctl_unlink (3), +.BR keyctl_update (3), +.BR recursive_key_scan (3), +.BR recursive_session_key_scan (3), +.BR capabilities (7), +.BR credentials (7), +.BR keyrings (7), +.BR keyutils (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user_namespaces (7), +.BR user\-session\-keyring (7), +.BR request\-key (8) +.PP +The kernel source files under +.IR Documentation/security/keys/ +(or, before Linux 4.13, in the file +.IR Documentation/security/keys.txt ). +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/kill.2 b/man2/kill.2 new file mode 100644 index 0000000..428e1d9 --- /dev/null +++ b/man2/kill.2 @@ -0,0 +1,189 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified by Thomas Koenig +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1993-07-25 by Rik Faith +.\" Modified 1995-11-01 by Michael Haardt +.\" +.\" Modified 1996-04-14 by Andries Brouwer +.\" [added some polishing contributed by Mike Battersby ] +.\" Modified 1996-07-21 by Andries Brouwer +.\" Modified 1997-01-17 by Andries Brouwer +.\" Modified 2001-12-18 by Andries Brouwer +.\" Modified 2002-07-24 by Michael Kerrisk +.\" Added note on historical rules enforced when an unprivileged process +.\" sends a signal. +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added note on CAP_KILL +.\" Modified 2004-06-24 by aeb +.\" Modified, 2004-11-30, after idea from emmanuel.colbus@ensimag.imag.fr +.\" +.TH KILL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +kill \- send signal to a process +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int kill(pid_t " pid ", int " sig ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR kill (): +_POSIX_C_SOURCE +.ad b +.SH DESCRIPTION +The +.BR kill () +system call +can be used to send any signal to any process group or process. +.PP +If \fIpid\fP is positive, then signal \fIsig\fP is sent to the +process with the ID specified by \fIpid\fP. +.PP +If \fIpid\fP equals 0, then \fIsig\fP is sent to every process in the +process group of the calling process. +.PP +If \fIpid\fP equals \-1, then \fIsig\fP is sent to every process +for which the calling process has permission to send signals, +except for process 1 (\fIinit\fP), but see below. +.PP +If \fIpid\fP is less than \-1, then \fIsig\fP is sent to every process +in the process group whose ID is \fI\-pid\fP. +.PP +If \fIsig\fP is 0, then no signal is sent, +but existence and permission checks are still performed; +this can be used to check for the existence of a process ID or +process group ID that the caller is permitted to signal. +.PP +For a process to have permission to send a signal, +it must either be privileged (under Linux: have the +.B CAP_KILL +capability in the user namespace of the target process), +or the real or effective user ID of the sending process must equal +the real or saved set-user-ID of the target process. +In the case of +.BR SIGCONT , +it suffices when the sending and receiving +processes belong to the same session. +(Historically, the rules were different; see NOTES.) +.SH RETURN VALUE +On success (at least one signal was sent), zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +An invalid signal was specified. +.TP +.B EPERM +The process does not have permission to send the signal +to any of the target processes. +.TP +.B ESRCH +The process or process group does not exist. +Note that an existing process might be a zombie, +a process that has terminated execution, but +has not yet been +.BR wait (2)ed +for. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +The only signals that can be sent to process ID 1, the +.I init +process, are those for which +.I init +has explicitly installed signal handlers. +This is done to assure the +system is not brought down accidentally. +.PP +POSIX.1 requires that \fIkill(\-1,sig)\fP send \fIsig\fP +to all processes that the calling process may send signals to, +except possibly for some implementation-defined system processes. +Linux allows a process to signal itself, but on Linux the call +\fIkill(\-1,sig)\fP does not signal the calling process. +.PP +POSIX.1 requires that if a process sends a signal to itself, +and the sending thread does not have the signal blocked, +and no other thread +has it unblocked or is waiting for it in +.BR sigwait (3), +at least one +unblocked signal must be delivered to the sending thread before the +.BR kill () +returns. +.SS Linux notes +Across different kernel versions, Linux has enforced different rules +for the permissions required for an unprivileged process +to send a signal to another process. +.\" In the 0.* kernels things chopped and changed quite +.\" a bit - MTK, 24 Jul 02 +In kernels 1.0 to 1.2.2, a signal could be sent if the +effective user ID of the sender matched effective user ID of the target, +or the real user ID of the sender matched the real user ID of the target. +From kernel 1.2.3 until 1.3.77, a signal could be sent if the +effective user ID of the sender matched either the real or effective +user ID of the target. +The current rules, which conform to POSIX.1, were adopted +in kernel 1.3.78. +.SH BUGS +In 2.6 kernels up to and including 2.6.7, +there was a bug that meant that when sending signals to a process group, +.BR kill () +failed with the error +.B EPERM +if the caller did not have permission to send the signal to \fIany\fP (rather +than \fIall\fP) of the members of the process group. +Notwithstanding this error return, the signal was still delivered +to all of the processes for which the caller had permission to signal. +.SH SEE ALSO +.BR kill (1), +.BR _exit (2), +.BR signal (2), +.BR tkill (2), +.BR exit (3), +.BR killpg (3), +.BR sigqueue (3), +.BR capabilities (7), +.BR credentials (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/killpg.2 b/man2/killpg.2 new file mode 100644 index 0000000..0ced862 --- /dev/null +++ b/man2/killpg.2 @@ -0,0 +1,2 @@ +.so man3/killpg.3 +.\" Eventually, this link will be removed. Added in Nov 2016 diff --git a/man2/lchown.2 b/man2/lchown.2 new file mode 100644 index 0000000..f0a5635 --- /dev/null +++ b/man2/lchown.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man2/lchown32.2 b/man2/lchown32.2 new file mode 100644 index 0000000..8ed3964 --- /dev/null +++ b/man2/lchown32.2 @@ -0,0 +1 @@ +.so man2/lchown.2 diff --git a/man2/lgetxattr.2 b/man2/lgetxattr.2 new file mode 100644 index 0000000..d9e5d90 --- /dev/null +++ b/man2/lgetxattr.2 @@ -0,0 +1 @@ +.so man2/getxattr.2 diff --git a/man2/link.2 b/man2/link.2 new file mode 100644 index 0000000..0742aed --- /dev/null +++ b/man2/link.2 @@ -0,0 +1,441 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1994-08-21 by Michael Haardt +.\" Modified 2004-06-23 by Michael Kerrisk +.\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2 +.\" +.TH LINK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +link, linkat \- make a new name for a file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int link(const char *" oldpath ", const char *" newpath ); +.PP +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int linkat(int " olddirfd ", const char *" oldpath , +.BI " int " newdirfd ", const char *" newpath ", int " flags ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR linkat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +.BR link () +creates a new link (also known as a hard link) to an existing file. +.PP +If +.I newpath +exists, it will +.I not +be overwritten. +.PP +This new name may be used exactly as the old one for any operation; +both names refer to the same file (and so have the same permissions +and ownership) and it is impossible to tell which name was the +"original". +.SS linkat() +The +.BR linkat () +system call operates in exactly the same way as +.BR link (), +except for the differences described here. +.PP +If the pathname given in +.I oldpath +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I olddirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR link () +for a relative pathname). +.PP +If +.I oldpath +is relative and +.I olddirfd +is the special value +.BR AT_FDCWD , +then +.I oldpath +is interpreted relative to the current working +directory of the calling process (like +.BR link ()). +.PP +If +.I oldpath +is absolute, then +.I olddirfd +is ignored. +.PP +The interpretation of +.I newpath +is as for +.IR oldpath , +except that a relative pathname is interpreted relative +to the directory referred to by the file descriptor +.IR newdirfd . +.PP +The following values can be bitwise ORed in +.IR flags : +.TP +.BR AT_EMPTY_PATH " (since Linux 2.6.39)" +.\" commit 11a7b371b64ef39fc5fb1b6f2218eef7c4d035e3 +If +.I oldpath +is an empty string, create a link to the file referenced by +.IR olddirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I olddirfd +can refer to any type of file except a directory. +This will generally not work if the file has a link count of zero (files +created with +.BR O_TMPFILE +and without +.BR O_EXCL +are an exception). +The caller must have the +.BR CAP_DAC_READ_SEARCH +capability in order to use this flag. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)" +By default, +.BR linkat (), +does not dereference +.I oldpath +if it is a symbolic link (like +.BR link ()). +The flag +.B AT_SYMLINK_FOLLOW +can be specified in +.I flags +to cause +.I oldpath +to be dereferenced if it is a symbolic link. +If procfs is mounted, +this can be used as an alternative to +.BR AT_EMPTY_PATH , +like this: +.IP +.in +4n +.EX +linkat(AT_FDCWD, "/proc/self/fd/", newdirfd, + newname, AT_SYMLINK_FOLLOW); +.EE +.in +.PP +Before kernel 2.6.18, the +.I flags +argument was unused, and had to be specified as 0. +.PP +See +.BR openat (2) +for an explanation of the need for +.BR linkat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I newpath +is denied, or search permission is denied for one of the directories +in the path prefix of +.I oldpath +or +.IR newpath . +(See also +.BR path_resolution (7).) +.TP +.B EDQUOT +The user's quota of disk blocks on the filesystem has been exhausted. +.TP +.B EEXIST +.I newpath +already exists. +.TP +.B EFAULT +.IR oldpath " or " newpath " points outside your accessible address space." +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR oldpath " or " newpath . +.TP +.B EMLINK +The file referred to by +.I oldpath +already has the maximum number of links to it. +For example, on an +.BR ext4 (5) +filesystem that does not employ the +.I dir_index +feature, the limit on the number of hard links to a file is 65,000; on +.BR btrfs (5), +the limit is 65,535 links. +.TP +.B ENAMETOOLONG +.IR oldpath " or " newpath " was too long." +.TP +.B ENOENT +A directory component in +.IR oldpath " or " newpath +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.IR oldpath " or " newpath +is not, in fact, a directory. +.TP +.B EPERM +.I oldpath +is a directory. +.TP +.B EPERM +The filesystem containing +.IR oldpath " and " newpath +does not support the creation of hard links. +.TP +.BR EPERM " (since Linux 3.6)" +The caller does not have permission to create a hard link to this file +(see the description of +.IR /proc/sys/fs/protected_hardlinks +in +.BR proc (5)). +.TP +.B EPERM +.I oldpath +is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +The file is on a read-only filesystem. +.TP +.B EXDEV +.IR oldpath " and " newpath +are not on the same mounted filesystem. +(Linux permits a filesystem to be mounted at multiple points, but +.BR link () +does not work across different mount points, +even if the same filesystem is mounted on both.) +.PP +The following additional errors can occur for +.BR linkat (): +.TP +.B EBADF +.I olddirfd +or +.I newdirfd +is not a valid file descriptor. +.TP +.B EINVAL +An invalid flag value was specified in +.IR flags . +.TP +.B ENOENT +.B AT_EMPTY_PATH +was specified in +.IR flags , +but the caller did not have the +.B CAP_DAC_READ_SEARCH +capability. +.TP +.B ENOENT +An attempt was made to link to the +.I /proc/self/fd/NN +file corresponding to a file descriptor created with +.IP + open(path, O_TMPFILE | O_EXCL, mode); +.IP +See +.BR open (2). +.TP +.B ENOENT +.I oldpath +is a relative pathname and +.I olddirfd +refers to a directory that has been deleted, +or +.I newpath +is a relative pathname and +.I newdirfd +refers to a directory that has been deleted. +.TP +.B ENOTDIR +.I oldpath +is relative and +.I olddirfd +is a file descriptor referring to a file other than a directory; +or similar for +.I newpath +and +.I newdirfd +.TP +.B EPERM +.BR AT_EMPTY_PATH +was specified in +.IR flags , +.I oldpath +is an empty string, and +.IR olddirfd +refers to a directory. +.SH VERSIONS +.BR linkat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR link (): +SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008. +.\" SVr4 documents additional ENOLINK and +.\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP. +.\" X/OPEN does not document EFAULT, ENOMEM or EIO. +.PP +.BR linkat (): +POSIX.1-2008. +.SH NOTES +Hard links, as created by +.BR link (), +cannot span filesystems. +Use +.BR symlink (2) +if this is required. +.PP +POSIX.1-2001 says that +.BR link () +should dereference +.I oldpath +if it is a symbolic link. +However, since kernel 2.0, +.\" more precisely: since kernel 1.3.56 +Linux does not do so: if +.I oldpath +is a symbolic link, then +.I newpath +is created as a (hard) link to the same symbolic link file +(i.e., +.I newpath +becomes a symbolic link to the same file that +.I oldpath +refers to). +Some other implementations behave in the same manner as Linux. +.\" For example, the default Solaris compilation environment +.\" behaves like Linux, and contributors to a March 2005 +.\" thread in the Austin mailing list reported that some +.\" other (System V) implementations did/do the same -- MTK, Apr 05 +POSIX.1-2008 changes the specification of +.BR link (), +making it implementation-dependent whether or not +.I oldpath +is dereferenced if it is a symbolic link. +For precise control over the treatment of symbolic links when +creating a link, use +.BR linkat (). +.SS Glibc notes +On older kernels where +.BR linkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR link (), +unless the +.B AT_SYMLINK_FOLLOW +is specified. +When +.I oldpath +and +.I newpath +are relative pathnames, +glibc constructs pathnames based on the symbolic links in +.IR /proc/self/fd +that correspond to the +.I olddirfd +and +.IR newdirfd +arguments. +.SH BUGS +On NFS filesystems, the return code may be wrong in case the NFS server +performs the link creation and dies before it can say so. +Use +.BR stat (2) +to find out if the link got created. +.SH SEE ALSO +.BR ln (1), +.BR open (2), +.BR rename (2), +.BR stat (2), +.BR symlink (2), +.BR unlink (2), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/linkat.2 b/man2/linkat.2 new file mode 100644 index 0000000..a7d6da5 --- /dev/null +++ b/man2/linkat.2 @@ -0,0 +1 @@ +.so man2/link.2 diff --git a/man2/listen.2 b/man2/listen.2 new file mode 100644 index 0000000..c38d82d --- /dev/null +++ b/man2/listen.2 @@ -0,0 +1,194 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" and Copyright (C) 2007, Michael Kerrisk +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" $Id: listen.2,v 1.6 1999/05/18 14:10:32 freitag Exp $ +.\" +.\" Modified Fri Jul 23 22:07:54 1993 by Rik Faith +.\" Modified 950727 by aeb, following a suggestion by Urs Thuermann +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" Modified 11 May 2001 by Sam Varshavchik +.\" +.\" +.TH LISTEN 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +listen \- listen for connections on a socket +.SH SYNOPSIS +.nf +.BR "#include " " /* See NOTES */" +.B #include +.PP +.BI "int listen(int " sockfd ", int " backlog ); +.fi +.SH DESCRIPTION +.BR listen () +marks the socket referred to by +.I sockfd +as a passive socket, that is, as a socket that will +be used to accept incoming connection requests using +.BR accept (2). +.PP +The +.I sockfd +argument is a file descriptor that refers to a socket of type +.B SOCK_STREAM +or +.BR SOCK_SEQPACKET . +.PP +The +.I backlog +argument defines the maximum length +to which the queue of pending connections for +.I sockfd +may grow. +If a connection request arrives when the queue is full, the client +may receive an error with an indication of +.B ECONNREFUSED +or, if the underlying protocol supports retransmission, the request may be +ignored so that a later reattempt at connection succeeds. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EADDRINUSE +Another socket is already listening on the same port. +.TP +.B EADDRINUSE +(Internet domain sockets) +The socket referred to by +.I sockfd +had not previously been bound to an address and, +upon attempting to bind it to an ephemeral port, +it was determined that all port numbers in the ephemeral port range +are currently in use. +See the discussion of +.I /proc/sys/net/ipv4/ip_local_port_range +in +.BR ip (7). +.TP +.B EBADF +The argument +.I sockfd +is not a valid file descriptor. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.TP +.B EOPNOTSUPP +The socket is not of a type that supports the +.BR listen () +operation. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.4BSD +.RB ( listen () +first appeared in 4.2BSD). +.SH NOTES +To accept connections, the following steps are performed: +.RS 4 +.IP 1. 4 +A socket is created with +.BR socket (2). +.IP 2. +The socket is bound to a local address using +.BR bind (2), +so that other sockets may be +.BR connect (2)ed +to it. +.IP 3. +A willingness to accept incoming connections and a queue limit for incoming +connections are specified with +.BR listen (). +.IP 4. +Connections are accepted with +.BR accept (2). +.RE +.PP +POSIX.1 does not require the inclusion of +.IR , +and this header file is not required on Linux. +However, some historical (BSD) implementations required this header +file, and portable applications are probably wise to include it. +.PP +The behavior of the +.I backlog +argument on TCP sockets changed with Linux 2.2. +Now it specifies the queue length for +.I completely +established sockets waiting to be accepted, +instead of the number of incomplete connection requests. +The maximum length of the queue for incomplete sockets +can be set using +.IR /proc/sys/net/ipv4/tcp_max_syn_backlog . +When syncookies are enabled there is no logical maximum +length and this setting is ignored. +See +.BR tcp (7) +for more information. +.PP +If the +.I backlog +argument is greater than the value in +.IR /proc/sys/net/core/somaxconn , +then it is silently truncated to that value; +the default value in this file is 128. +In kernels before 2.4.25, this limit was a hard coded value, +.BR SOMAXCONN , +with the value 128. +.\" The following is now rather historic information (MTK, Jun 05) +.\" Don't rely on this value in portable applications since BSD +.\" (and some BSD-derived systems) limit the backlog to 5. +.SH EXAMPLE +See +.BR bind (2). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR socket (2), +.BR socket (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/listxattr.2 b/man2/listxattr.2 new file mode 100644 index 0000000..cb2fa4b --- /dev/null +++ b/man2/listxattr.2 @@ -0,0 +1,348 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" Copyright (C) 2015 Heinrich Schuchardt +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH LISTXATTR 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +listxattr, llistxattr, flistxattr \- list extended attribute names +.SH SYNOPSIS +.fam C +.nf +.B #include +.B #include +.PP +.BI "ssize_t listxattr(const char\ *" path ", char\ *" list \ +", size_t " size ); +.BI "ssize_t llistxattr(const char\ *" path ", char\ *" list \ +", size_t " size ); +.BI "ssize_t flistxattr(int " fd ", char\ *" list ", size_t " size ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name : value +pairs associated with inodes (files, directories, symbolic links, etc.). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e., the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR xattr (7). +.PP +.BR listxattr () +retrieves the list +of extended attribute names associated with the given +.I path +in the filesystem. +The retrieved list is placed in +.IR list , +a caller-allocated buffer whose size (in bytes) is specified in the argument +.IR size . +The list is the set of (null-terminated) names, one after the other. +Names of extended attributes to which the calling process does not +have access may be omitted from the list. +The length of the attribute name +.I list +is returned. +.PP +.BR llistxattr () +is identical to +.BR listxattr (), +except in the case of a symbolic link, where the list of names of +extended attributes associated with the link itself is retrieved, +not the file that it refers to. +.PP +.BR flistxattr () +is identical to +.BR listxattr (), +only the open file referred to by +.I fd +(as returned by +.BR open (2)) +is interrogated in place of +.IR path . +.PP +A single extended attribute +.I name +is a null-terminated string. +The name includes a namespace prefix; there may be several, disjoint +namespaces associated with an individual inode. +.PP +If +.I size +is specified as zero, these calls return the current size of the +list of extended attribute names (and leave +.I list +unchanged). +This can be used to determine the size of the buffer that +should be supplied in a subsequent call. +(But, bear in mind that there is a possibility that the +set of extended attributes may change between the two calls, +so that it is still necessary to check the return status +from the second call.) +.SS Example +The +.I list +of names is returned as an unordered array of null-terminated character +strings (attribute names are separated by null bytes (\(aq\\0\(aq)), like this: +.PP +.in +4n +.EX +user.name1\\0system.name1\\0user.name2\\0 +.EE +.in +.PP +Filesystems that implement POSIX ACLs using +extended attributes might return a +.I list +like this: +.PP +.in +4n +.EX +system.posix_acl_access\\0system.posix_acl_default\\0 +.EE +.in +.SH RETURN VALUE +On success, a nonnegative number is returned indicating the size of the +extended attribute name list. +On failure, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B E2BIG +The size of the list of extended attribute names is larger than the maximum +size allowed; the list cannot be retrieved. +This can happen on filesystems that support an unlimited number of +extended attributes per file such as XFS, for example. +See BUGS. +.TP +.B ENOTSUP +Extended attributes are not supported by the filesystem, or are disabled. +.TP +.B ERANGE +The +.I size +of the +.I list +buffer is too small to hold the result. +.PP +In addition, the errors documented in +.BR stat (2) +can also occur. +.SH VERSIONS +These system calls have been available on Linux since kernel 2.4; +glibc support is provided since version 2.3. +.SH CONFORMING TO +These system calls are Linux-specific. +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +.SH BUGS +.\" The xattr(7) page refers to this text: +As noted in +.BR xattr (7), +the VFS imposes a limit of 64\ kB on the size of the extended +attribute name list returned by +.BR listxattr (7). +If the total size of attribute names attached to a file exceeds this limit, +it is no longer possible to retrieve the list of attribute names. +.SH EXAMPLE +The following program demonstrates the usage of +.BR listxattr () +and +.BR getxattr (2). +For the file whose pathname is provided as a command-line argument, +it lists all extended file attributes and their values. +.PP +To keep the code simple, the program assumes that attribute keys and +values are constant during the execution of the program. +A production program should expect and handle changes during +execution of the program. +For example, +the number of bytes required for attribute keys +might increase between the two calls to +.BR listxattr (). +An application could handle this possibility using +a loop that retries the call +(perhaps up to a predetermined maximum number of attempts) +with a larger buffer each time it fails with the error +.BR ERANGE . +Calls to +.BR getxattr (2) +could be handled similarly. +.PP +The following output was recorded by first creating a file, setting +some extended file attributes, +and then listing the attributes with the example program. +.SS Example output +.in +4n +.EX +$ \fBtouch /tmp/foo\fP +$ \fBsetfattr -n user.fred -v chocolate /tmp/foo\fP +$ \fBsetfattr -n user.frieda -v bar /tmp/foo\fP +$ \fBsetfattr -n user.empty /tmp/foo\fP +$ \fB./listxattr /tmp/foo\fP +user.fred: chocolate +user.frieda: bar +user.empty: +.EE +.in +.SS Program source (listxattr.c) +.EX +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + ssize_t buflen, keylen, vallen; + char *buf, *key, *val; + + if (argc != 2) { + fprintf(stderr, "Usage: %s path\\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* + * Determine the length of the buffer needed. + */ + buflen = listxattr(argv[1], NULL, 0); + if (buflen == \-1) { + perror("listxattr"); + exit(EXIT_FAILURE); + } + if (buflen == 0) { + printf("%s has no attributes.\\n", argv[1]); + exit(EXIT_SUCCESS); + } + + /* + * Allocate the buffer. + */ + buf = malloc(buflen); + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + + /* + * Copy the list of attribute keys to the buffer. + */ + buflen = listxattr(argv[1], buf, buflen); + if (buflen == \-1) { + perror("listxattr"); + exit(EXIT_FAILURE); + } + + /* + * Loop over the list of zero terminated strings with the + * attribute keys. Use the remaining buffer length to determine + * the end of the list. + */ + key = buf; + while (buflen > 0) { + + /* + * Output attribute key. + */ + printf("%s: ", key); + + /* + * Determine length of the value. + */ + vallen = getxattr(argv[1], key, NULL, 0); + if (vallen == \-1) + perror("getxattr"); + + if (vallen > 0) { + + /* + * Allocate value buffer. + * One extra byte is needed to append 0x00. + */ + val = malloc(vallen + 1); + if (val == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + + /* + * Copy value to buffer. + */ + vallen = getxattr(argv[1], key, val, vallen); + if (vallen == \-1) + perror("getxattr"); + else { + /* + * Output attribute value. + */ + val[vallen] = 0; + printf("%s", val); + } + + free(val); + } else if (vallen == 0) + printf(""); + + printf("\\n"); + + /* + * Forward to next attribute key. + */ + keylen = strlen(key) + 1; + buflen \-= keylen; + key += keylen; + } + + free(buf); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR open (2), +.BR removexattr (2), +.BR setxattr (2), +.BR stat (2), +.BR symlink (7), +.BR xattr (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/llistxattr.2 b/man2/llistxattr.2 new file mode 100644 index 0000000..117bd2b --- /dev/null +++ b/man2/llistxattr.2 @@ -0,0 +1 @@ +.so man2/listxattr.2 diff --git a/man2/llseek.2 b/man2/llseek.2 new file mode 100644 index 0000000..c049a00 --- /dev/null +++ b/man2/llseek.2 @@ -0,0 +1,106 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" Written 10 June 1995 by Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Thu Oct 31 15:16:23 1996 by Eric S. Raymond +.\" +.TH LLSEEK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +_llseek \- reposition read/write file offset +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int _llseek(unsigned int " fd ", unsigned long " offset_high , +.BI " unsigned long " offset_low ", loff_t *" result , +.BI " unsigned int " whence ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The +.BR _llseek () +system call repositions the offset of the open file description associated +with the file descriptor +.I fd +to +.I (offset_high<<32) | offset_low +bytes relative to the beginning of the file, the current file offset, +or the end of the file, depending on whether +.I whence +is +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +respectively. +It returns the resulting file position in the argument +.IR result . +.PP +This system call exists on various 32-bit platforms to support +seeking to large file offsets. +.SH RETURN VALUE +Upon successful completion, +.BR _llseek () +returns 0. +Otherwise, a value of \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EFAULT +Problem with copying results to user space. +.TP +.B EINVAL +.I whence +is invalid. +.SH CONFORMING TO +This function is Linux-specific, and should not be used in programs +intended to be portable. +.SH NOTES +Glibc does not provide a wrapper for this system call. +To invoke it directly, use +.BR syscall (2). +However, you probably want to use the +.BR lseek (2) +wrapper function instead. +.SH SEE ALSO +.BR lseek (2), +.BR open (2), +.BR lseek64 (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/lock.2 b/man2/lock.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/lock.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/lookup_dcookie.2 b/man2/lookup_dcookie.2 new file mode 100644 index 0000000..90fe7e9 --- /dev/null +++ b/man2/lookup_dcookie.2 @@ -0,0 +1,100 @@ +.\" Copyright (C) 2003 John Levon +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 2004-06-17 Michael Kerrisk +.\" +.TH LOOKUP_DCOOKIE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +lookup_dcookie \- return a directory entry's path +.SH SYNOPSIS +.BI "int lookup_dcookie(u64 " cookie ", char *" buffer ", size_t " len ); +.SH DESCRIPTION +Look up the full path of the directory entry specified by the value +.IR cookie . +The cookie is an opaque identifier uniquely identifying a particular +directory entry. +The buffer given is filled in with the full path of the directory entry. +.PP +For +.BR lookup_dcookie () +to return successfully, +the kernel must still hold a cookie reference to the directory entry. +.SH RETURN VALUE +On success, +.BR lookup_dcookie () +returns the length of the path string copied into the buffer. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +The buffer was not valid. +.TP +.B EINVAL +The kernel has no registered cookie/directory entry mappings at the +time of lookup, or the cookie does not refer to a valid directory entry. +.TP +.B ENAMETOOLONG +The name could not fit in the buffer. +.TP +.B ENOMEM +The kernel could not allocate memory for the temporary buffer holding +the path. +.TP +.B EPERM +The process does not have the capability +.B CAP_SYS_ADMIN +required to look up cookie values. +.TP +.B ERANGE +The buffer was not large enough to hold the path of the directory entry. +.SH VERSIONS +Available since Linux 2.5.43. +The +.B ENAMETOOLONG +error return was added in 2.5.70. +.SH CONFORMING TO +.BR lookup_dcookie () +is Linux-specific. +.SH NOTES +.BR lookup_dcookie () +is a special-purpose system call, currently used only by the +.BR oprofile (1) +profiler. +It relies on a kernel driver to register cookies for directory entries. +.PP +The path returned may be suffixed by the string " (deleted)" if the directory +entry has been removed. +.SH SEE ALSO +.BR oprofile (1) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/lremovexattr.2 b/man2/lremovexattr.2 new file mode 100644 index 0000000..38d01cc --- /dev/null +++ b/man2/lremovexattr.2 @@ -0,0 +1 @@ +.so man2/removexattr.2 diff --git a/man2/lseek.2 b/man2/lseek.2 new file mode 100644 index 0000000..784797f --- /dev/null +++ b/man2/lseek.2 @@ -0,0 +1,277 @@ +'\" t +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" and Copyright (c) 2011, Michael Kerrisk +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)lseek.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1995-06-10 by Andries Brouwer +.\" Modified 1996-10-31 by Eric S. Raymond +.\" Modified 1998-01-17 by Michael Haardt +.\" +.\" Modified 2001-09-24 by Michael Haardt +.\" Modified 2003-08-21 by Andries Brouwer +.\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE +.\" +.TH LSEEK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +lseek \- reposition read/write file offset +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); +.SH DESCRIPTION +.BR lseek () +repositions the file offset of the open file description +associated with the file descriptor +.I fd +to the argument +.I offset +according to the directive +.I whence +as follows: +.TP +.B SEEK_SET +The file offset is set to +.I offset +bytes. +.TP +.B SEEK_CUR +The file offset is set to its current location plus +.I offset +bytes. +.TP +.B SEEK_END +The file offset is set to the size of the file plus +.I offset +bytes. +.PP +.BR lseek () +allows the file offset to be set beyond the end +of the file (but this does not change the size of the file). +If data is later written at this point, subsequent reads of the data +in the gap (a "hole") return null bytes (\(aq\\0\(aq) until +data is actually written into the gap. +.SS Seeking file data and holes +Since version 3.1, Linux supports the following additional values for +.IR whence : +.TP +.B SEEK_DATA +Adjust the file offset to the next location +in the file greater than or equal to +.I offset +containing data. +If +.I offset +points to data, +then the file offset is set to +.IR offset . +.TP +.B SEEK_HOLE +Adjust the file offset to the next hole in the file +greater than or equal to +.IR offset . +If +.I offset +points into the middle of a hole, +then the file offset is set to +.IR offset . +If there is no hole past +.IR offset , +then the file offset is adjusted to the end of the file +(i.e., there is an implicit hole at the end of any file). +.PP +In both of the above cases, +.BR lseek () +fails if +.I offset +points past the end of the file. +.PP +These operations allow applications to map holes in a sparsely +allocated file. +This can be useful for applications such as file backup tools, +which can save space when creating backups and preserve holes, +if they have a mechanism for discovering holes. +.PP +For the purposes of these operations, a hole is a sequence of zeros that +(normally) has not been allocated in the underlying file storage. +However, a filesystem is not obliged to report holes, +so these operations are not a guaranteed mechanism for +mapping the storage space actually allocated to a file. +(Furthermore, a sequence of zeros that actually has been written +to the underlying storage may not be reported as a hole.) +In the simplest implementation, +a filesystem can support the operations by making +.BR SEEK_HOLE +always return the offset of the end of the file, +and making +.BR SEEK_DATA +always return +.IR offset +(i.e., even if the location referred to by +.I offset +is a hole, +it can be considered to consist of data that is a sequence of zeros). +.\" https://lkml.org/lkml/2011/4/22/79 +.\" http://lwn.net/Articles/440255/ +.\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data +.PP +The +.BR _GNU_SOURCE +feature test macro must be defined in order to obtain the definitions of +.BR SEEK_DATA +and +.BR SEEK_HOLE +from +.IR . +.PP +The +.BR SEEK_HOLE +and +.BR SEEK_DATA +operations are supported for the following filesystems: +.IP * 3 +Btrfs (since Linux 3.1) +.IP * 3 +OCFS (since Linux 3.2) +.\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1 +.IP * +XFS (since Linux 3.5) +.IP * +ext4 (since Linux 3.8) +.IP * +.BR tmpfs "(5) (since Linux 3.8)" +.IP * +NFS (since Linux 3.18) +.\" commit 1c6dcbe5ceff81c2cf8d929646af675cd59fe7c0 +.\" commit 24bab491220faa446d945624086d838af41d616c +.IP * +FUSE (since Linux 4.5) +.\" commit 0b5da8db145bfd44266ac964a2636a0cf8d7c286 +.SH RETURN VALUE +Upon successful completion, +.BR lseek () +returns the resulting offset location as measured in bytes from the +beginning of the file. +On error, the value \fI(off_t)\ \-1\fP is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EINVAL +.I whence +is not valid. +Or: the resulting file offset would be negative, +or beyond the end of a seekable device. +.\" Some systems may allow negative offsets for character devices +.\" and/or for remote filesystems. +.TP +.B ENXIO +.I whence +is +.B SEEK_DATA +or +.BR SEEK_HOLE , +and the file offset is beyond the end of the file. +.TP +.B EOVERFLOW +.\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW) +The resulting file offset cannot be represented in an +.IR off_t . +.TP +.B ESPIPE +.I fd +is associated with a pipe, socket, or FIFO. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.PP +.BR SEEK_DATA +and +.BR SEEK_HOLE +are nonstandard extensions also present in Solaris, +FreeBSD, and DragonFly BSD; +they are proposed for inclusion in the next POSIX revision (Issue 8). +.\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future +.SH NOTES +See +.BR open (2) +for a discussion of the relationship between file descriptors, +open file descriptions, and files. +.PP +If the +.B O_APPEND +file status flag is set on the open file description, +then a +.BR write (2) +.I always +moves the file offset to the end of the file, regardless of the use of +.BR lseek (). +.PP +The +.I off_t +data type is a signed integer data type specified by POSIX.1. +.PP +Some devices are incapable of seeking and POSIX does not specify which +devices must support +.BR lseek (). +.PP +On Linux, using +.BR lseek () +on a terminal device fails with the error +\fBESPIPE\fP. +.\" Other systems return the number of written characters, +.\" using SEEK_SET to set the counter. (Of written characters.) +.SH SEE ALSO +.BR dup (2), +.BR fallocate (2), +.BR fork (2), +.BR open (2), +.BR fseek (3), +.BR lseek64 (3), +.BR posix_fallocate (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/lsetxattr.2 b/man2/lsetxattr.2 new file mode 100644 index 0000000..dc07807 --- /dev/null +++ b/man2/lsetxattr.2 @@ -0,0 +1 @@ +.so man2/setxattr.2 diff --git a/man2/lstat.2 b/man2/lstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man2/lstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/lstat64.2 b/man2/lstat64.2 new file mode 100644 index 0000000..89b1c84 --- /dev/null +++ b/man2/lstat64.2 @@ -0,0 +1 @@ +.so man2/lstat.2 diff --git a/man2/madvise.2 b/man2/madvise.2 new file mode 100644 index 0000000..0b40155 --- /dev/null +++ b/man2/madvise.2 @@ -0,0 +1,584 @@ +.\" Copyright (C) 2001 David Gómez +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Based on comments from mm/filemap.c. Last modified on 10-06-2001 +.\" Modified, 25 Feb 2002, Michael Kerrisk, +.\" Added notes on MADV_DONTNEED +.\" 2010-06-19, mtk, Added documentation of MADV_MERGEABLE and +.\" MADV_UNMERGEABLE +.\" 2010-06-15, Andi Kleen, Add documentation of MADV_HWPOISON. +.\" 2010-06-19, Andi Kleen, Add documentation of MADV_SOFT_OFFLINE. +.\" 2011-09-18, Doug Goldstein +.\" Document MADV_HUGEPAGE and MADV_NOHUGEPAGE +.\" +.TH MADVISE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +madvise \- give advice about use of memory +.SH SYNOPSIS +.B #include +.PP +.BI "int madvise(void *" addr ", size_t " length ", int " advice ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR madvise (): +.PD 0 +.RS 4 +.TP 4 +Since glibc 2.19: +_DEFAULT_SOURCE +.TP +Up to and including glibc 2.19: +_BSD_SOURCE +.RE +.PD +.SH DESCRIPTION +The +.BR madvise () +system call is used to give advice or directions to the kernel +about the address range beginning at address +.I addr +and with size +.I length +bytes +In most cases, +the goal of such advice is to improve system or application performance. +.PP +Initially, the system call supported a set of "conventional" +.I advice +values, which are also available on several other implementations. +(Note, though, that +.BR madvise () +is not specified in POSIX.) +Subsequently, a number of Linux-specific +.IR advice +values have been added. +.\" +.\" ====================================================================== +.\" +.SS Conventional advice values +The +.I advice +values listed below +allow an application to tell the kernel how it expects to use +some mapped or shared memory areas, so that the kernel can choose +appropriate read-ahead and caching techniques. +These +.I advice +values do not influence the semantics of the application +(except in the case of +.BR MADV_DONTNEED ), +but may influence its performance. +All of the +.I advice +values listed here have analogs in the POSIX-specified +.BR posix_madvise (3) +function, and the values have the same meanings, with the exception of +.BR MADV_DONTNEED . +.PP +The advice is indicated in the +.I advice +argument, which is one of the following: +.TP +.B MADV_NORMAL +No special treatment. +This is the default. +.TP +.B MADV_RANDOM +Expect page references in random order. +(Hence, read ahead may be less useful than normally.) +.TP +.B MADV_SEQUENTIAL +Expect page references in sequential order. +(Hence, pages in the given range can be aggressively read ahead, +and may be freed soon after they are accessed.) +.TP +.B MADV_WILLNEED +Expect access in the near future. +(Hence, it might be a good idea to read some pages ahead.) +.TP +.B MADV_DONTNEED +Do not expect access in the near future. +(For the time being, the application is finished with the given range, +so the kernel can free resources associated with it.) +.IP +After a successful +.B MADV_DONTNEED +operation, +the semantics of memory access in the specified region are changed: +subsequent accesses of pages in the range will succeed, but will result +in either repopulating the memory contents from the +up-to-date contents of the underlying mapped file +(for shared file mappings, shared anonymous mappings, +and shmem-based techniques such as System V shared memory segments) +or zero-fill-on-demand pages for anonymous private mappings. +.IP +Note that, when applied to shared mappings, +.BR MADV_DONTNEED +might not lead to immediate freeing of the pages in the range. +The kernel is free to delay freeing the pages until an appropriate moment. +The resident set size (RSS) of the calling process will be immediately +reduced however. +.IP +.B MADV_DONTNEED +cannot be applied to locked pages, Huge TLB pages, or +.BR VM_PFNMAP +pages. +(Pages marked with the kernel-internal +.B VM_PFNMAP +.\" http://lwn.net/Articles/162860/ +flag are special memory areas that are not managed +by the virtual memory subsystem. +Such pages are typically created by device drivers that +map the pages into user space.) +.\" +.\" ====================================================================== +.\" +.SS Linux-specific advice values +The following Linux-specific +.I advice +values have no counterparts in the POSIX-specified +.BR posix_madvise (3), +and may or may not have counterparts in the +.BR madvise () +interface available on other implementations. +Note that some of these operations change the semantics of memory accesses. +.TP +.BR MADV_REMOVE " (since Linux 2.6.16)" +.\" commit f6b3ec238d12c8cc6cc71490c6e3127988460349 +Free up a given range of pages +and its associated backing store. +This is equivalent to punching a hole in the corresponding byte +range of the backing store (see +.BR fallocate (2)). +Subsequent accesses in the specified address range will see +bytes containing zero. +.\" Databases want to use this feature to drop a section of their +.\" bufferpool (shared memory segments) - without writing back to +.\" disk/swap space. This feature is also useful for supporting +.\" hot-plug memory on UML. +.IP +The specified address range must be mapped shared and writable. +This flag cannot be applied to locked pages, Huge TLB pages, or +.BR VM_PFNMAP +pages. +.IP +In the initial implementation, only +.BR tmpfs (5) +was supported +.BR MADV_REMOVE ; +but since Linux 3.5, +.\" commit 3f31d07571eeea18a7d34db9af21d2285b807a17 +any filesystem which supports the +.BR fallocate (2) +.BR FALLOC_FL_PUNCH_HOLE +mode also supports +.BR MADV_REMOVE . +Hugetlbfs fails with the error +.BR EINVAL +and other filesystems fail with the error +.BR EOPNOTSUPP . +.TP +.BR MADV_DONTFORK " (since Linux 2.6.16)" +.\" commit f822566165dd46ff5de9bf895cfa6c51f53bb0c4 +.\" See http://lwn.net/Articles/171941/ +Do not make the pages in this range available to the child after a +.BR fork (2). +This is useful to prevent copy-on-write semantics from changing +the physical location of a page if the parent writes to it after a +.BR fork (2). +(Such page relocations cause problems for hardware that +DMAs into the page.) +.\" [PATCH] madvise MADV_DONTFORK/MADV_DOFORK +.\" Currently, copy-on-write may change the physical address of +.\" a page even if the user requested that the page is pinned in +.\" memory (either by mlock or by get_user_pages). This happens +.\" if the process forks meanwhile, and the parent writes to that +.\" page. As a result, the page is orphaned: in case of +.\" get_user_pages, the application will never see any data hardware +.\" DMA's into this page after the COW. In case of mlock'd memory, +.\" the parent is not getting the realtime/security benefits of mlock. +.\" +.\" In particular, this affects the Infiniband modules which do DMA from +.\" and into user pages all the time. +.\" +.\" This patch adds madvise options to control whether memory range is +.\" inherited across fork. Useful e.g. for when hardware is doing DMA +.\" from/into these pages. Could also be useful to an application +.\" wanting to speed up its forks by cutting large areas out of +.\" consideration. +.\" +.\" SEE ALSO: http://lwn.net/Articles/171941/ +.\" "Tweaks to madvise() and posix_fadvise()", 14 Feb 2006 +.TP +.BR MADV_DOFORK " (since Linux 2.6.16)" +Undo the effect of +.BR MADV_DONTFORK , +restoring the default behavior, whereby a mapping is inherited across +.BR fork (2). +.TP +.BR MADV_HWPOISON " (since Linux 2.6.32) +.\" commit 9893e49d64a4874ea67849ee2cfbf3f3d6817573 +Poison the pages in the range specified by +.I addr +and +.IR length +and handle subsequent references to those pages +like a hardware memory corruption. +This operation is available only for privileged +.RB ( CAP_SYS_ADMIN ) +processes. +This operation may result in the calling process receiving a +.B SIGBUS +and the page being unmapped. +.IP +This feature is intended for testing of memory error-handling code; +it is available only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.BR MADV_MERGEABLE " (since Linux 2.6.32)" +.\" commit f8af4da3b4c14e7267c4ffb952079af3912c51c5 +Enable Kernel Samepage Merging (KSM) for the pages in the range specified by +.I addr +and +.IR length . +The kernel regularly scans those areas of user memory that have +been marked as mergeable, +looking for pages with identical content. +These are replaced by a single write-protected page (which is automatically +copied if a process later wants to update the content of the page). +KSM merges only private anonymous pages (see +.BR mmap (2)). +.IP +The KSM feature is intended for applications that generate many +instances of the same data (e.g., virtualization systems such as KVM). +It can consume a lot of processing power; use with care. +See the Linux kernel source file +.I Documentation/vm/ksm.txt +for more details. +.IP +The +.BR MADV_MERGEABLE +and +.BR MADV_UNMERGEABLE +operations are available only if the kernel was configured with +.BR CONFIG_KSM . +.TP +.BR MADV_UNMERGEABLE " (since Linux 2.6.32)" +Undo the effect of an earlier +.BR MADV_MERGEABLE +operation on the specified address range; +KSM unmerges whatever pages it had merged in the address range specified by +.IR addr +and +.IR length . +.TP +.BR MADV_SOFT_OFFLINE " (since Linux 2.6.33) +.\" commit afcf938ee0aac4ef95b1a23bac704c6fbeb26de6 +Soft offline the pages in the range specified by +.I addr +and +.IR length . +The memory of each page in the specified range is preserved +(i.e., when next accessed, the same content will be visible, +but in a new physical page frame), +and the original page is offlined +(i.e., no longer used, and taken out of normal memory management). +The effect of the +.B MADV_SOFT_OFFLINE +operation is invisible to (i.e., does not change the semantics of) +the calling process. +.IP +This feature is intended for testing of memory error-handling code; +it is available only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.BR MADV_HUGEPAGE " (since Linux 2.6.38)" +.\" commit 0af4e98b6b095c74588af04872f83d333c958c32 +.\" http://lwn.net/Articles/358904/ +.\" https://lwn.net/Articles/423584/ +Enable Transparent Huge Pages (THP) for pages in the range specified by +.I addr +and +.IR length . +Currently, Transparent Huge Pages work only with private anonymous pages (see +.BR mmap (2)). +The kernel will regularly scan the areas marked as huge page candidates +to replace them with huge pages. +The kernel will also allocate huge pages directly when the region is +naturally aligned to the huge page size (see +.BR posix_memalign (2)). +.IP +This feature is primarily aimed at applications that use large mappings of +data and access large regions of that memory at a time (e.g., virtualization +systems such as QEMU). +It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses +1 byte will result in 2\ MB of wired memory instead of one 4\ KB page). +See the Linux kernel source file +.I Documentation/vm/transhuge.txt +for more details. +.IP +The +.BR MADV_HUGEPAGE +and +.BR MADV_NOHUGEPAGE +operations are available only if the kernel was configured with +.BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.BR MADV_NOHUGEPAGE " (since Linux 2.6.38)" +Ensures that memory in the address range specified by +.IR addr +and +.IR length +will not be collapsed into huge pages. +.TP +.BR MADV_DONTDUMP " (since Linux 3.4)" +.\" commit 909af768e88867016f427264ae39d27a57b6a8ed +.\" commit accb61fe7bb0f5c2a4102239e4981650f9048519 +Exclude from a core dump those pages in the range specified by +.I addr +and +.IR length . +This is useful in applications that have large areas of memory +that are known not to be useful in a core dump. +The effect of +.BR MADV_DONTDUMP +takes precedence over the bit mask that is set via the +.I /proc/[pid]/coredump_filter +file (see +.BR core (5)). +.TP +.BR MADV_DODUMP " (since Linux 3.4)" +Undo the effect of an earlier +.BR MADV_DONTDUMP . +.TP +.BR MADV_FREE " (since Linux 4.5)" +The application no longer requires the pages in the range specified by +.IR addr +and +.IR len . +The kernel can thus free these pages, +but the freeing could be delayed until memory pressure occurs. +For each of the pages that has been marked to be freed +but has not yet been freed, +the free operation will be canceled if the caller writes into the page. +After a successful +.B MADV_FREE +operation, any stale data (i.e., dirty, unwritten pages) will be lost +when the kernel frees the pages. +However, subsequent writes to pages in the range will succeed +and then kernel cannot free those dirtied pages, +so that the caller can always see just written data. +If there is no subsequent write, +the kernel can free the pages at any time. +Once pages in the range have been freed, the caller will +see zero-fill-on-demand pages upon subsequent page references. +.IP +The +.B MADV_FREE +operation +can be applied only to private anonymous pages (see +.BR mmap (2)). +On a swapless system, freeing pages in a given range happens instantly, +regardless of memory pressure. +.TP +.BR MADV_WIPEONFORK " (since Linux 4.14)" +.\" commit d2cd9ede6e193dd7d88b6d27399e96229a551b19 +Present the child process with zero-filled memory in this range after a +.BR fork (2). +This is useful in forking servers in order to ensure +that sensitive per-process data +(for example, PRNG seeds, cryptographic secrets, and so on) +is not handed to child processes. +.IP +The +.B MADV_WIPEONFORK +operation can be applied only to private anonymous pages (see +.BR mmap (2)). +.IP +Within the child created by +.BR fork (2), +the +.B MADV_WIPEONFORK +setting remains in place on the specified address range. +This setting is cleared during +.BR execve (2). +.TP +.BR MADV_KEEPONFORK " (since Linux 4.14)" +.\" commit d2cd9ede6e193dd7d88b6d27399e96229a551b19 +Undo the effect of an earlier +.BR MADV_WIPEONFORK . +.SH RETURN VALUE +On success, +.BR madvise () +returns zero. +On error, it returns \-1 and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +.I advice +is +.BR MADV_REMOVE , +but the specified address range is not a shared writable mapping. +.TP +.B EAGAIN +A kernel resource was temporarily unavailable. +.TP +.B EBADF +The map exists, but the area maps something that isn't a file. +.TP +.B EINVAL +.I addr +is not page-aligned or +.I length +is negative. +.\" .I length +.\" is zero, +.TP +.B EINVAL +.I advice +is not a valid. +.TP +.B EINVAL +.I advice +is +.B MADV_DONTNEED +or +.BR MADV_REMOVE +and the specified address range includes locked, Huge TLB pages, or +.B VM_PFNMAP +pages. +.TP +.B EINVAL +.I advice +is +.BR MADV_MERGEABLE +or +.BR MADV_UNMERGEABLE , +but the kernel was not configured with +.BR CONFIG_KSM . +.TP +.B EINVAL +.I advice +is +.BR MADV_FREE +or +.BR MADV_WIPEONFORK +but the specified address range includes file, Huge TLB, +.BR MAP_SHARED , +or +.BR VM_PFNMAP +ranges. +.TP +.B EIO +(for +.BR MADV_WILLNEED ) +Paging in this area would exceed the process's +maximum resident set size. +.TP +.B ENOMEM +(for +.BR MADV_WILLNEED ) +Not enough memory: paging in failed. +.TP +.B ENOMEM +Addresses in the specified range are not currently +mapped, or are outside the address space of the process. +.TP +.B EPERM +.I advice +is +.BR MADV_HWPOISON , +but the caller does not have the +.B CAP_SYS_ADMIN +capability. +.SH VERSIONS +Since Linux 3.18, +.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb +support for this system call is optional, +depending on the setting of the +.B CONFIG_ADVISE_SYSCALLS +configuration option. +.SH CONFORMING TO +.BR madvise () +is not specified by any standards. +Versions of this system call, implementing a wide variety of +.I advice +values, exist on many other implementations. +Other implementations typically implement at least the flags listed +above under +.IR "Conventional advice flags" , +albeit with some variation in semantics. +.PP +POSIX.1-2001 describes +.BR posix_madvise (3) +with constants +.BR POSIX_MADV_NORMAL , +.BR POSIX_MADV_RANDOM , +.BR POSIX_MADV_SEQUENTIAL , +.BR POSIX_MADV_WILLNEED , +and +.BR POSIX_MADV_DONTNEED , +and so on, with behavior close to the similarly named flags listed above. +.SH NOTES +.SS Linux notes +The Linux implementation requires that the address +.I addr +be page-aligned, and allows +.I length +to be zero. +If there are some parts of the specified address range +that are not mapped, the Linux version of +.BR madvise () +ignores them and applies the call to the rest (but returns +.B ENOMEM +from the system call, as it should). +.\" .SH HISTORY +.\" The +.\" .BR madvise () +.\" function first appeared in 4.4BSD. +.SH SEE ALSO +.BR getrlimit (2), +.BR mincore (2), +.BR mmap (2), +.BR mprotect (2), +.BR msync (2), +.BR munmap (2), +.BR prctl (2), +.BR posix_madvise (3), +.BR core (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/madvise1.2 b/man2/madvise1.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/madvise1.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/mbind.2 b/man2/mbind.2 new file mode 100644 index 0000000..929ac84 --- /dev/null +++ b/man2/mbind.2 @@ -0,0 +1,500 @@ +.\" Copyright 2003,2004 Andi Kleen, SuSE Labs. +.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard +.\" +.\" %%%LICENSE_START(VERBATIM_PROF) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2006-02-03, mtk, substantial wording changes and other improvements +.\" 2007-08-27, Lee Schermerhorn +.\" more precise specification of behavior. +.\" +.\" FIXME +.\" Linux 3.8 added MPOL_MF_LAZY, which needs to be documented. +.\" Does it also apply for move_pages()? +.\" +.\" commit b24f53a0bea38b266d219ee651b22dba727c44ae +.\" Author: Lee Schermerhorn +.\" Date: Thu Oct 25 14:16:32 2012 +0200 +.\" +.TH MBIND 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +mbind \- set memory policy for a memory range +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "long mbind(void *" addr ", unsigned long " len ", int " mode , +.BI " const unsigned long *" nodemask ", unsigned long " maxnode , +.BI " unsigned " flags ); +.PP +Link with \fI\-lnuma\fP. +.fi +.SH DESCRIPTION +.BR mbind () +sets the NUMA memory policy, +which consists of a policy mode and zero or more nodes, +for the memory range starting with +.I addr +and continuing for +.I len +bytes. +The memory policy defines from which node memory is allocated. +.PP +If the memory range specified by the +.IR addr " and " len +arguments includes an "anonymous" region of memory\(emthat is +a region of memory created using the +.BR mmap (2) +system call with the +.BR MAP_ANONYMOUS \(emor +a memory-mapped file, mapped using the +.BR mmap (2) +system call with the +.B MAP_PRIVATE +flag, pages will be allocated only according to the specified +policy when the application writes (stores) to the page. +For anonymous regions, an initial read access will use a shared +page in the kernel containing all zeros. +For a file mapped with +.BR MAP_PRIVATE , +an initial read access will allocate pages according to the +memory policy of the thread that causes the page to be allocated. +This may not be the thread that called +.BR mbind (). +.PP +The specified policy will be ignored for any +.B MAP_SHARED +mappings in the specified memory range. +Rather the pages will be allocated according to the memory policy +of the thread that caused the page to be allocated. +Again, this may not be the thread that called +.BR mbind (). +.PP +If the specified memory range includes a shared memory region +created using the +.BR shmget (2) +system call and attached using the +.BR shmat (2) +system call, +pages allocated for the anonymous or shared memory region will +be allocated according to the policy specified, regardless of which +process attached to the shared memory segment causes the allocation. +If, however, the shared memory region was created with the +.B SHM_HUGETLB +flag, +the huge pages will be allocated according to the policy specified +only if the page allocation is caused by the process that calls +.BR mbind () +for that region. +.PP +By default, +.BR mbind () +has an effect only for new allocations; if the pages inside +the range have been already touched before setting the policy, +then the policy has no effect. +This default behavior may be overridden by the +.B MPOL_MF_MOVE +and +.B MPOL_MF_MOVE_ALL +flags described below. +.PP +The +.I mode +argument must specify one of +.BR MPOL_DEFAULT , +.BR MPOL_BIND , +.BR MPOL_INTERLEAVE , +.BR MPOL_PREFERRED , +or +.BR MPOL_LOCAL +(which are described in detail below). +All policy modes except +.B MPOL_DEFAULT +require the caller to specify the node or nodes to which the mode applies, +via the +.I nodemask +argument. +.PP +The +.I mode +argument may also include an optional +.IR "mode flag" . +The supported +.I "mode flags" +are: +.TP +.BR MPOL_F_STATIC_NODES " (since Linux-2.6.26)" +A nonempty +.I nodemask +specifies physical node IDs. +Linux does not remap the +.I nodemask +when the thread moves to a different cpuset context, +nor when the set of nodes allowed by the thread's +current cpuset context changes. +.TP +.BR MPOL_F_RELATIVE_NODES " (since Linux-2.6.26)" +A nonempty +.I nodemask +specifies node IDs that are relative to the set of +node IDs allowed by the thread's current cpuset. +.PP +.I nodemask +points to a bit mask of nodes containing up to +.I maxnode +bits. +The bit mask size is rounded to the next multiple of +.IR "sizeof(unsigned long)" , +but the kernel will use bits only up to +.IR maxnode . +A NULL value of +.I nodemask +or a +.I maxnode +value of zero specifies the empty set of nodes. +If the value of +.I maxnode +is zero, +the +.I nodemask +argument is ignored. +Where a +.I nodemask +is required, it must contain at least one node that is on-line, +allowed by the thread's current cpuset context +(unless the +.B MPOL_F_STATIC_NODES +mode flag is specified), +and contains memory. +.PP +The +.I mode +argument must include one of the following values: +.TP +.B MPOL_DEFAULT +This mode requests that any nondefault policy be removed, +restoring default behavior. +When applied to a range of memory via +.BR mbind (), +this means to use the thread memory policy, +which may have been set with +.BR set_mempolicy (2). +If the mode of the thread memory policy is also +.BR MPOL_DEFAULT , +the system-wide default policy will be used. +The system-wide default policy allocates +pages on the node of the CPU that triggers the allocation. +For +.BR MPOL_DEFAULT , +the +.I nodemask +and +.I maxnode +arguments must be specify the empty set of nodes. +.TP +.B MPOL_BIND +This mode specifies a strict policy that restricts memory allocation to +the nodes specified in +.IR nodemask . +If +.I nodemask +specifies more than one node, page allocations will come from +the node with sufficient free memory that is closest to +the node where the allocation takes place. +Pages will not be allocated from any node not specified in the +IR nodemask . +(Before Linux 2.6.26, +.\" commit 19770b32609b6bf97a3dece2529089494cbfc549 +page allocations came from +the node with the lowest numeric node ID first, until that node +contained no free memory. +Allocations then came from the node with the next highest +node ID specified in +.I nodemask +and so forth, until none of the specified nodes contained free memory.) +.TP +.B MPOL_INTERLEAVE +This mode specifies that page allocations be interleaved across the +set of nodes specified in +.IR nodemask . +This optimizes for bandwidth instead of latency +by spreading out pages and memory accesses to those pages across +multiple nodes. +To be effective the memory area should be fairly large, +at least 1\ MB or bigger with a fairly uniform access pattern. +Accesses to a single page of the area will still be limited to +the memory bandwidth of a single node. +.TP +.B MPOL_PREFERRED +This mode sets the preferred node for allocation. +The kernel will try to allocate pages from this +node first and fall back to other nodes if the +preferred nodes is low on free memory. +If +.I nodemask +specifies more than one node ID, the first node in the +mask will be selected as the preferred node. +If the +.I nodemask +and +.I maxnode +arguments specify the empty set, then the memory is allocated on +the node of the CPU that triggered the allocation. +.TP +.BR MPOL_LOCAL " (since Linux 3.8)" +.\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8 +.\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f +This mode specifies "local allocation"; the memory is allocated on +the node of the CPU that triggered the allocation (the "local node"). +The +.I nodemask +and +.I maxnode +arguments must specify the empty set. +If the "local node" is low on free memory, +the kernel will try to allocate memory from other nodes. +The kernel will allocate memory from the "local node" +whenever memory for this node is available. +If the "local node" is not allowed by the thread's current cpuset context, +the kernel will try to allocate memory from other nodes. +The kernel will allocate memory from the "local node" whenever +it becomes allowed by the thread's current cpuset context. +By contrast, +.B MPOL_DEFAULT +reverts to the memory policy of the thread (which may be set via +.BR set_mempolicy (2)); +that policy may be something other than "local allocation". +.PP +If +.B MPOL_MF_STRICT +is passed in +.I flags +and +.I mode +is not +.BR MPOL_DEFAULT , +then the call fails with the error +.B EIO +if the existing pages in the memory range don't follow the policy. +.\" According to the kernel code, the following is not true +.\" --Lee Schermerhorn +.\" In 2.6.16 or later the kernel will also try to move pages +.\" to the requested node with this flag. +.PP +If +.B MPOL_MF_MOVE +is specified in +.IR flags , +then the kernel will attempt to move all the existing pages +in the memory range so that they follow the policy. +Pages that are shared with other processes will not be moved. +If +.B MPOL_MF_STRICT +is also specified, then the call fails with the error +.B EIO +if some pages could not be moved. +.PP +If +.B MPOL_MF_MOVE_ALL +is passed in +.IR flags , +then the kernel will attempt to move all existing pages in the memory range +regardless of whether other processes use the pages. +The calling thread must be privileged +.RB ( CAP_SYS_NICE ) +to use this flag. +If +.B MPOL_MF_STRICT +is also specified, then the call fails with the error +.B EIO +if some pages could not be moved. +.\" --------------------------------------------------------------- +.SH RETURN VALUE +On success, +.BR mbind () +returns 0; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.\" --------------------------------------------------------------- +.SH ERRORS +.\" I think I got all of the error returns. --Lee Schermerhorn +.TP +.B EFAULT +Part or all of the memory range specified by +.I nodemask +and +.I maxnode +points outside your accessible address space. +Or, there was an unmapped hole in the specified memory range specified by +.IR addr +and +.IR len . +.TP +.B EINVAL +An invalid value was specified for +.I flags +or +.IR mode ; +or +.I addr + len +was less than +.IR addr ; +or +.I addr +is not a multiple of the system page size. +Or, +.I mode +is +.B MPOL_DEFAULT +and +.I nodemask +specified a nonempty set; +or +.I mode +is +.B MPOL_BIND +or +.B MPOL_INTERLEAVE +and +.I nodemask +is empty. +Or, +.I maxnode +exceeds a kernel-imposed limit. +.\" As at 2.6.23, this limit is "a page worth of bits", e.g., +.\" 8 * 4096 bits, assuming a 4kB page size. +Or, +.I nodemask +specifies one or more node IDs that are +greater than the maximum supported node ID. +Or, none of the node IDs specified by +.I nodemask +are on-line and allowed by the thread's current cpuset context, +or none of the specified nodes contain memory. +Or, the +.I mode +argument specified both +.B MPOL_F_STATIC_NODES +and +.BR MPOL_F_RELATIVE_NODES . +.TP +.B EIO +.B MPOL_MF_STRICT +was specified and an existing page was already on a node +that does not follow the policy; +or +.B MPOL_MF_MOVE +or +.B MPOL_MF_MOVE_ALL +was specified and the kernel was unable to move all existing +pages in the range. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B EPERM +The +.I flags +argument included the +.B MPOL_MF_MOVE_ALL +flag and the caller does not have the +.B CAP_SYS_NICE +privilege. +.\" --------------------------------------------------------------- +.SH VERSIONS +The +.BR mbind () +system call was added to the Linux kernel in version 2.6.7. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +For information on library support, see +.BR numa (7). +.PP +NUMA policy is not supported on a memory-mapped file range +that was mapped with the +.B MAP_SHARED +flag. +.PP +The +.B MPOL_DEFAULT +mode can have different effects for +.BR mbind () +and +.BR set_mempolicy (2). +When +.B MPOL_DEFAULT +is specified for +.BR set_mempolicy (2), +the thread's memory policy reverts to the system default policy +or local allocation. +When +.B MPOL_DEFAULT +is specified for a range of memory using +.BR mbind (), +any pages subsequently allocated for that range will use +the thread's memory policy, as set by +.BR set_mempolicy (2). +This effectively removes the explicit policy from the +specified range, "falling back" to a possibly nondefault +policy. +To select explicit "local allocation" for a memory range, +specify a +.I mode +of +.B MPOL_LOCAL +or +.B MPOL_PREFERRED +with an empty set of nodes. +This method will work for +.BR set_mempolicy (2), +as well. +.PP +Support for huge page policy was added with 2.6.16. +For interleave policy to be effective on huge page mappings the +policied memory needs to be tens of megabytes or larger. +.PP +.B MPOL_MF_STRICT +is ignored on huge page mappings. +.PP +.B MPOL_MF_MOVE +and +.B MPOL_MF_MOVE_ALL +are available only on Linux 2.6.16 and later. +.SH SEE ALSO +.BR get_mempolicy (2), +.BR getcpu (2), +.BR mmap (2), +.BR set_mempolicy (2), +.BR shmat (2), +.BR shmget (2), +.BR numa (3), +.BR cpuset (7), +.BR numa (7), +.BR numactl (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/membarrier.2 b/man2/membarrier.2 new file mode 100644 index 0000000..5cd4eb3 --- /dev/null +++ b/man2/membarrier.2 @@ -0,0 +1,359 @@ +.\" Copyright 2015-2017 Mathieu Desnoyers +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MEMBARRIER 2 2017-11-15 "Linux" "Linux Programmer's Manual" +.SH NAME +membarrier \- issue memory barriers on a set of threads +.SH SYNOPSIS +.B #include +.PP +.BI "int membarrier(int " cmd ", int " flags "); +.SH DESCRIPTION +The +.BR membarrier () +system call helps reducing the overhead of the memory barrier +instructions required to order memory accesses on multi-core systems. +However, this system call is heavier than a memory barrier, so using it +effectively is +.I not +as simple as replacing memory barriers with this +system call, but requires understanding of the details below. +.PP +Use of memory barriers needs to be done taking into account that a +memory barrier always needs to be either matched with its memory barrier +counterparts, or that the architecture's memory model doesn't require the +matching barriers. +.PP +There are cases where one side of the matching barriers (which we will +refer to as "fast side") is executed much more often than the other +(which we will refer to as "slow side"). +This is a prime target for the use of +.BR membarrier (). +The key idea is to replace, for these matching +barriers, the fast-side memory barriers by simple compiler barriers, +for example: +.PP + asm volatile ("" : : : "memory") +.PP +and replace the slow-side memory barriers by calls to +.BR membarrier (). +.PP +This will add overhead to the slow side, and remove overhead from the +fast side, thus resulting in an overall performance increase as long as +the slow side is infrequent enough that the overhead of the +.BR membarrier () +calls does not outweigh the performance gain on the fast side. +.PP +The +.I cmd +argument is one of the following: +.TP +.B MEMBARRIER_CMD_QUERY +Query the set of supported commands. +The return value of the call is a bit mask of supported +commands. +.BR MEMBARRIER_CMD_QUERY , +which has the value 0, +is not itself included in this bit mask. +This command is always supported (on kernels where +.BR membarrier () +is provided). +.TP +.B MEMBARRIER_CMD_SHARED +Ensure that all threads from all processes on the system pass through a +state where all memory accesses to user-space addresses match program +order between entry to and return from the +.BR membarrier () +system call. +All threads on the system are targeted by this command. +.TP +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED " (since Linux 4.14)" +Execute a memory barrier on each running thread belonging to the same +process as the current thread. +Upon return from system call, the calling +thread is assured that all its running threads siblings have passed +through a state where all memory accesses to user-space addresses match +program order between entry to and return from the system call +(non-running threads are de facto in such a state). +This covers only threads from the same process as the calling thread. +.IP +The "expedited" commands complete faster than the non-expedited ones; +they never block, but have the downside of causing extra overhead. +A process needs to register its intent to use the private +expedited command prior to using it. +.TP +.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED " (since Linux 4.14)" +Register the process's intent to use +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED . +.PP +The +.I flags +argument is currently unused and must be specified as 0. +.PP +All memory accesses performed in program order from each targeted thread +are guaranteed to be ordered with respect to +.BR membarrier (). +.PP +If we use the semantic +.I barrier() +to represent a compiler barrier forcing memory +accesses to be performed in program order across the barrier, and +.I smp_mb() +to represent explicit memory barriers forcing full memory +ordering across the barrier, we have the following ordering table for +each pairing of +.IR barrier() , +.BR membarrier () +and +.IR smp_mb() . +The pair ordering is detailed as (O: ordered, X: not ordered): +.PP + barrier() smp_mb() membarrier() + barrier() X X O + smp_mb() X O O + membarrier() O O O +.SH RETURN VALUE +On success, the +.B MEMBARRIER_CMD_QUERY +operation returns a bit mask of supported commands, and the +.B MEMBARRIER_CMD_SHARED , +.B MEMBARRIER_CMD_PRIVATE_EXPEDITED , +and +.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED , +operations return zero. +On error, \-1 is returned, +and +.I errno +is set appropriately. +.PP +For a given command, with +.I flags +set to 0, this system call is +guaranteed to always return the same value until reboot. +Further calls with the same arguments will lead to the same result. +Therefore, with +.I flags +set to 0, error handling is required only for the first call to +.BR membarrier (). +.SH ERRORS +.TP +.B EINVAL +.I cmd +is invalid, or +.I flags +is nonzero, or the +.BR MEMBARRIER_CMD_SHARED +command is disabled because the +.I nohz_full +CPU parameter has been set. +.TP +.B ENOSYS +The +.BR membarrier () +system call is not implemented by this kernel. +.TP +.B EPERM +The current process was not registered prior to using private expedited +commands. +.SH VERSIONS +The +.BR membarrier () +system call was added in Linux 4.3. +.\" +.SH CONFORMING TO +.BR membarrier () +is Linux-specific. +.\" .SH SEE ALSO +.\" FIXME See if the following syscalls make it into Linux 4.15 or later +.\" .BR cpu_opv (2), +.\" .BR rseq (2) +.SH NOTES +A memory barrier instruction is part of the instruction set of +architectures with weakly-ordered memory models. +It orders memory +accesses prior to the barrier and after the barrier with respect to +matching barriers on other cores. +For instance, a load fence can order +loads prior to and following that fence with respect to stores ordered +by store fences. +.PP +Program order is the order in which instructions are ordered in the +program assembly code. +.PP +Examples where +.BR membarrier () +can be useful include implementations +of Read-Copy-Update libraries and garbage collectors. +.SH EXAMPLE +Assuming a multithreaded application where "fast_path()" is executed +very frequently, and where "slow_path()" is executed infrequently, the +following code (x86) can be transformed using +.BR membarrier (): +.PP +.in +4n +.EX +#include + +static volatile int a, b; + +static void +fast_path(int *read_b) +{ + a = 1; + asm volatile ("mfence" : : : "memory"); + *read_b = b; +} + +static void +slow_path(int *read_a) +{ + b = 1; + asm volatile ("mfence" : : : "memory"); + *read_a = a; +} + +int +main(int argc, char **argv) +{ + int read_a, read_b; + + /* + * Real applications would call fast_path() and slow_path() + * from different threads. Call those from main() to keep + * this example short. + */ + + slow_path(&read_a); + fast_path(&read_b); + + /* + * read_b == 0 implies read_a == 1 and + * read_a == 0 implies read_b == 1. + */ + + if (read_b == 0 && read_a == 0) + abort(); + + exit(EXIT_SUCCESS); +} +.EE +.in +.PP +The code above transformed to use +.BR membarrier () +becomes: +.PP +.in +4n +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include + +static volatile int a, b; + +static int +membarrier(int cmd, int flags) +{ + return syscall(__NR_membarrier, cmd, flags); +} + +static int +init_membarrier(void) +{ + int ret; + + /* Check that membarrier() is supported. */ + + ret = membarrier(MEMBARRIER_CMD_QUERY, 0); + if (ret < 0) { + perror("membarrier"); + return \-1; + } + + if (!(ret & MEMBARRIER_CMD_SHARED)) { + fprintf(stderr, + "membarrier does not support MEMBARRIER_CMD_SHARED\\n"); + return \-1; + } + + return 0; +} + +static void +fast_path(int *read_b) +{ + a = 1; + asm volatile ("" : : : "memory"); + *read_b = b; +} + +static void +slow_path(int *read_a) +{ + b = 1; + membarrier(MEMBARRIER_CMD_SHARED, 0); + *read_a = a; +} + +int +main(int argc, char **argv) +{ + int read_a, read_b; + + if (init_membarrier()) + exit(EXIT_FAILURE); + + /* + * Real applications would call fast_path() and slow_path() + * from different threads. Call those from main() to keep + * this example short. + */ + + slow_path(&read_a); + fast_path(&read_b); + + /* + * read_b == 0 implies read_a == 1 and + * read_a == 0 implies read_b == 1. + */ + + if (read_b == 0 && read_a == 0) + abort(); + + exit(EXIT_SUCCESS); +} +.EE +.in +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/memfd_create.2 b/man2/memfd_create.2 new file mode 100644 index 0000000..ac956ea --- /dev/null +++ b/man2/memfd_create.2 @@ -0,0 +1,541 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 David Herrmann +.\" +.\" %%%LICENSE_START(GPLv2+) +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH MEMFD_CREATE 2 2018-02-02 Linux "Linux Programmer's Manual" +.SH NAME +memfd_create \- create an anonymous file +.SH SYNOPSIS +.B #include +.PP +.BI "int memfd_create(const char *" name ", unsigned int " flags ");" +.SH DESCRIPTION +.BR memfd_create () +creates an anonymous file and returns a file descriptor that refers to it. +The file behaves like a regular file, and so can be modified, +truncated, memory-mapped, and so on. +However, unlike a regular file, +it lives in RAM and has a volatile backing storage. +Once all references to the file are dropped, it is automatically released. +Anonymous memory is used for all backing pages of the file. +Therefore, files created by +.BR memfd_create () +have the same semantics as other anonymous +.\" David Herrmann: +.\" memfd uses VM_NORESERVE so each page is accounted on first access. +.\" This means, the overcommit-limits (see __vm_enough_memory()) and the +.\" memory-cgroup limits (mem_cgroup_try_charge()) are applied. Note that +.\" those are accounted on "current" and "current->mm", that is, the +.\" process doing the first page access. +memory allocations such as those allocated using +.BR mmap (2) +with the +.BR MAP_ANONYMOUS +flag. +.PP +The initial size of the file is set to 0. +Following the call, the file size should be set using +.BR ftruncate (2). +(Alternatively, the file may be populated by calls to +.BR write (2) +or similar.) +.PP +The name supplied in +.I name +is used as a filename and will be displayed +as the target of the corresponding symbolic link in the directory +.IR /proc/self/fd/ . +The displayed name is always prefixed with +.IR memfd: +and serves only for debugging purposes. +Names do not affect the behavior of the file descriptor, +and as such multiple files can have the same name without any side effects. +.PP +The following values may be bitwise ORed in +.IR flags +to change the behavior of +.BR memfd_create (): +.TP +.BR MFD_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.TP +.BR MFD_ALLOW_SEALING +Allow sealing operations on this file. +See the discussion of the +.B F_ADD_SEALS +and +.BR F_GET_SEALS +operations in +.BR fcntl (2), +and also NOTES, below. +The initial set of seals is empty. +If this flag is not set, the initial set of seals will be +.BR F_SEAL_SEAL , +meaning that no other seals can be set on the file. +.\" FIXME Why is the MFD_ALLOW_SEALING behavior not simply the default? +.\" Is it worth adding some text explaining this? +.TP +.BR MFD_HUGETLB " (since Linux 4.14)" +.\" commit 749df87bd7bee5a79cef073f5d032ddb2b211de8 +The anonymous file will be created in the hugetlbfs filesystem using +huge pages. +See the Linux kernel source file +.I Documentation/vm/hugetlbpage.txt +for more information about hugetlbfs. +The hugetlbfs filesystem does not support file-sealing operations. +Therefore, specifying both +.B MFD_HUGETLB +and +.B MFD_ALLOW_SEALING +in +.I flags +is disallowed. +.TP +.BR MFD_HUGE_2MB ", " MFD_HUGE_1GB ", " "..." +Used in conjunction with +.B MFD_HUGETLB +to select alternative hugetlb page sizes (respectively, 2\ MB, 1\ GB, ...) +on systems that support multiple hugetlb page sizes. +Definitions for known +huge page sizes are included in the header file +.I . +.IP +For details on encoding huge page sizes not included in the header file, +see the discussion of the similarly named constants in +.BR mmap (2). +.PP +Unused bits in +.I flags +must be 0. +.PP +As its return value, +.BR memfd_create () +returns a new file descriptor that can be used to refer to the file. +This file descriptor is opened for both reading and writing +.RB ( O_RDWR ) +and +.B O_LARGEFILE +is set for the file descriptor. +.PP +With respect to +.BR fork (2) +and +.BR execve (2), +the usual semantics apply for the file descriptor created by +.BR memfd_create (). +A copy of the file descriptor is inherited by the child produced by +.BR fork (2) +and refers to the same file. +The file descriptor is preserved across +.BR execve (2), +unless the close-on-exec flag has been set. +.SH RETURN VALUE +On success, +.BR memfd_create () +returns a new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The address in +.IR name +points to invalid memory. +.TP +.B EINVAL +.I flags +included unknown bits. +.TP +.B EINVAL +.I name +was too long. +(The limit is +.\" NAME_MAX - strlen("memfd:") +249 bytes, excluding the terminating null byte.) +.TP +.B EINVAL +Both +.B MFD_HUGETLB +and +.B MFD_ALLOW_SEALING +were specified in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +There was insufficient memory to create a new anonymous file. +.SH VERSIONS +The +.BR memfd_create () +system call first appeared in Linux 3.17; +glibc support was added in version 2.27. +.SH CONFORMING TO +The +.BR memfd_create () +system call is Linux-specific. +.SH NOTES +.PP +.\" See also http://lwn.net/Articles/593918/ +.\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/ +The +.BR memfd_create () +system call provides a simple alternative to manually mounting a +.BR tmpfs (5) +filesystem and creating and opening a file in that filesystem. +The primary purpose of +.BR memfd_create () +is to create files and associated file descriptors that are +used with the file-sealing APIs provided by +.BR fcntl (2). +.PP +The +.BR memfd_create () +system call also has uses without file sealing +(which is why file-sealing is disabled, unless explicitly requested with the +.BR MFD_ALLOW_SEALING +flag). +In particular, it can be used as an alternative to creating files in +.IR tmp +or as an alternative to using the +.BR open (2) +.B O_TMPFILE +in cases where there is no intention to actually link the +resulting file into the filesystem. +.SS File sealing +In the absence of file sealing, +processes that communicate via shared memory must either trust each other, +or take measures to deal with the possibility that an untrusted peer +may manipulate the shared memory region in problematic ways. +For example, an untrusted peer might modify the contents of the +shared memory at any time, or shrink the shared memory region. +The former possibility leaves the local process vulnerable to +time-of-check-to-time-of-use race conditions +(typically dealt with by copying data from +the shared memory region before checking and using it). +The latter possibility leaves the local process vulnerable to +.BR SIGBUS +signals when an attempt is made to access a now-nonexistent +location in the shared memory region. +(Dealing with this possibility necessitates the use of a handler for the +.BR SIGBUS +signal.) +.PP +Dealing with untrusted peers imposes extra complexity on +code that employs shared memory. +Memory sealing enables that extra complexity to be eliminated, +by allowing a process to operate secure in the knowledge that +its peer can't modify the shared memory in an undesired fashion. +.PP +An example of the usage of the sealing mechanism is as follows: +.IP 1. 3 +The first process creates a +.BR tmpfs (5) +file using +.BR memfd_create (). +The call yields a file descriptor used in subsequent steps. +.IP 2. +The first process +sizes the file created in the previous step using +.BR ftruncate (2), +maps it using +.BR mmap (2), +and populates the shared memory with the desired data. +.IP 3. +The first process uses the +.BR fcntl (2) +.B F_ADD_SEALS +operation to place one or more seals on the file, +in order to restrict further modifications on the file. +(If placing the seal +.BR F_SEAL_WRITE , +then it will be necessary to first unmap the shared writable mapping +created in the previous step.) +.IP 4. +A second process obtains a file descriptor for the +.BR tmpfs (5) +file and maps it. +Among the possible ways in which this could happen are the following: +.RS +.IP * 3 +The process that called +.BR memfd_create () +could transfer the resulting file descriptor to the second process +via a UNIX domain socket (see +.BR unix (7) +and +.BR cmsg (3)). +The second process then maps the file using +.BR mmap (2). +.IP * +The second process is created via +.BR fork (2) +and thus automatically inherits the file descriptor and mapping. +(Note that in this case and the next, +there is a natural trust relationship between the two processes, +since they are running under the same user ID. +Therefore, file sealing would not normally be necessary.) +.IP * +The second process opens the file +.IR /proc//fd/ , +where +.I +is the PID of the first process (the one that called +.BR memfd_create ()), +and +.I +is the number of the file descriptor returned by the call to +.BR memfd_create () +in that process. +The second process then maps the file using +.BR mmap (2). +.RE +.IP 5. +The second process uses the +.BR fcntl (2) +.B F_GET_SEALS +operation to retrieve the bit mask of seals +that has been applied to the file. +This bit mask can be inspected in order to determine +what kinds of restrictions have been placed on file modifications. +If desired, the second process can apply further seals +to impose additional restrictions (so long as the +.BR F_SEAL_SEAL +seal has not yet been applied). +.SH EXAMPLE +Below are shown two example programs that demonstrate the use of +.BR memfd_create () +and the file sealing API. +.PP +The first program, +.IR t_memfd_create.c , +creates a +.BR tmpfs (5) +file using +.BR memfd_create (), +sets a size for the file, maps it into memory, +and optionally places some seals on the file. +The program accepts up to three command-line arguments, +of which the first two are required. +The first argument is the name to associate with the file, +the second argument is the size to be set for the file, +and the optional third argument is a string of characters that specify +seals to be set on file. +.PP +The second program, +.IR t_get_seals.c , +can be used to open an existing file that was created via +.BR memfd_create () +and inspect the set of seals that have been applied to that file. +.PP +The following shell session demonstrates the use of these programs. +First we create a +.BR tmpfs (5) +file and set some seals on it: +.PP +.in +4n +.EX +$ \fB./t_memfd_create my_memfd_file 4096 sw &\fP +[1] 11775 +PID: 11775; fd: 3; /proc/11775/fd/3 +.EE +.in +.PP +At this point, the +.I t_memfd_create +program continues to run in the background. +From another program, we can obtain a file descriptor for the +file created by +.BR memfd_create () +by opening the +.IR /proc/[pid]/fd +file that corresponds to the file descriptor opened by +.BR memfd_create (). +Using that pathname, we inspect the content of the +.IR /proc/[pid]/fd +symbolic link, and use our +.I t_get_seals +program to view the seals that have been placed on the file: +.PP +.in +4n +.EX +$ \fBreadlink /proc/11775/fd/3\fP +/memfd:my_memfd_file (deleted) +$ \fB./t_get_seals /proc/11775/fd/3\fP +Existing seals: WRITE SHRINK +.EE +.in +.SS Program source: t_memfd_create.c +\& +.EX +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + int fd; + unsigned int seals; + char *addr; + char *name, *seals_arg; + ssize_t len; + + if (argc < 3) { + fprintf(stderr, "%s name size [seals]\\n", argv[0]); + fprintf(stderr, "\\t\(aqseals\(aq can contain any of the " + "following characters:\\n"); + fprintf(stderr, "\\t\\tg \- F_SEAL_GROW\\n"); + fprintf(stderr, "\\t\\ts \- F_SEAL_SHRINK\\n"); + fprintf(stderr, "\\t\\tw \- F_SEAL_WRITE\\n"); + fprintf(stderr, "\\t\\tS \- F_SEAL_SEAL\\n"); + exit(EXIT_FAILURE); + } + + name = argv[1]; + len = atoi(argv[2]); + seals_arg = argv[3]; + + /* Create an anonymous file in tmpfs; allow seals to be + placed on the file */ + + fd = memfd_create(name, MFD_ALLOW_SEALING); + if (fd == \-1) + errExit("memfd_create"); + + /* Size the file as specified on the command line */ + + if (ftruncate(fd, len) == \-1) + errExit("truncate"); + + printf("PID: %ld; fd: %d; /proc/%ld/fd/%d\\n", + (long) getpid(), fd, (long) getpid(), fd); + + /* Code to map the file and populate the mapping with data + omitted */ + + /* If a \(aqseals\(aq command\-line argument was supplied, set some + seals on the file */ + + if (seals_arg != NULL) { + seals = 0; + + if (strchr(seals_arg, \(aqg\(aq) != NULL) + seals |= F_SEAL_GROW; + if (strchr(seals_arg, \(aqs\(aq) != NULL) + seals |= F_SEAL_SHRINK; + if (strchr(seals_arg, \(aqw\(aq) != NULL) + seals |= F_SEAL_WRITE; + if (strchr(seals_arg, \(aqS\(aq) != NULL) + seals |= F_SEAL_SEAL; + + if (fcntl(fd, F_ADD_SEALS, seals) == \-1) + errExit("fcntl"); + } + + /* Keep running, so that the file created by memfd_create() + continues to exist */ + + pause(); + + exit(EXIT_SUCCESS); +} +.EE +.SS Program source: t_get_seals.c +\& +.EX +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + int fd; + unsigned int seals; + + if (argc != 2) { + fprintf(stderr, "%s /proc/PID/fd/FD\\n", argv[0]); + exit(EXIT_FAILURE); + } + + fd = open(argv[1], O_RDWR); + if (fd == \-1) + errExit("open"); + + seals = fcntl(fd, F_GET_SEALS); + if (seals == \-1) + errExit("fcntl"); + + printf("Existing seals:"); + if (seals & F_SEAL_SEAL) + printf(" SEAL"); + if (seals & F_SEAL_GROW) + printf(" GROW"); + if (seals & F_SEAL_WRITE) + printf(" WRITE"); + if (seals & F_SEAL_SHRINK) + printf(" SHRINK"); + printf("\\n"); + + /* Code to map the file and access the contents of the + resulting mapping omitted */ + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fcntl (2), +.BR ftruncate (2), +.BR mmap (2), +.BR shmget (2), +.BR shm_open (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/migrate_pages.2 b/man2/migrate_pages.2 new file mode 100644 index 0000000..77109fb --- /dev/null +++ b/man2/migrate_pages.2 @@ -0,0 +1,193 @@ +.\" Copyright 2009 Intel Corporation +.\" Author: Andi Kleen +.\" Based on the move_pages manpage which was +.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc. +.\" Christoph Lameter +.\" +.\" %%%LICENSE_START(VERBATIM_TWO_PARA) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" %%%LICENSE_END +.\" +.TH MIGRATE_PAGES 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +migrate_pages \- move all pages in a process to another set of nodes +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long migrate_pages(int " pid ", unsigned long " maxnode, +.BI " const unsigned long *" old_nodes, +.BI " const unsigned long *" new_nodes ); +.fi +.PP +Link with \fI\-lnuma\fP. +.SH DESCRIPTION +.BR migrate_pages () +attempts to move all pages of the process +.I pid +that are in memory nodes +.I old_nodes +to the memory nodes in +.IR new_nodes . +Pages not located in any node in +.I old_nodes +will not be migrated. +As far as possible, +the kernel maintains the relative topology relationship inside +.I old_nodes +during the migration to +.IR new_nodes . +.PP +The +.I old_nodes +and +.I new_nodes +arguments are pointers to bit masks of node numbers, with up to +.I maxnode +bits in each mask. +These masks are maintained as arrays of unsigned +.I long +integers (in the last +.I long +integer, the bits beyond those specified by +.I maxnode +are ignored). +The +.I maxnode +argument is the maximum node number in the bit mask plus one (this is the same +as in +.BR mbind (2), +but different from +.BR select (2)). +.PP +The +.I pid +argument is the ID of the process whose pages are to be moved. +To move pages in another process, +the caller must be privileged +.RB ( CAP_SYS_NICE ) +or the real or effective user ID of the calling process must match the +real or saved-set user ID of the target process. +If +.I pid +is 0, then +.BR migrate_pages () +moves pages of the calling process. +.PP +Pages shared with another process will be moved only if the initiating +process has the +.B CAP_SYS_NICE +privilege. +.SH RETURN VALUE +On success +.BR migrate_pages () +returns the number of pages that could not be moved +(i.e., a return of zero means that all pages were successfully moved). +On error, it returns \-1, and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Part or all of the memory range specified by +.IR old_nodes / new_nodes +and +.I maxnode +points outside your accessible address space. +.TP +.B EINVAL +The value specified by +.I maxnode +exceeds a kernel-imposed limit. +.\" As at 3.5, this limit is "a page worth of bits", e.g., +.\" 8 * 4096 bits, assuming a 4kB page size. +Or, +.I old_nodes +or +.I new_nodes +specifies one or more node IDs that are +greater than the maximum supported node ID. +Or, none of the node IDs specified by +.I new_nodes +are on-line and allowed by the process's current cpuset context, +or none of the specified nodes contain memory. +.TP +.B EPERM +Insufficient privilege +.RB ( CAP_SYS_NICE ) +to move pages of the process specified by +.IR pid , +or insufficient privilege +.RB ( CAP_SYS_NICE ) +to access the specified target nodes. +.TP +.B ESRCH +No process matching +.I pid +could be found. +.\" FIXME Document the other errors that can occur for migrate_pages() +.SH VERSIONS +The +.BR migrate_pages () +system call first appeared on Linux in version 2.6.16. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +For information on library support, see +.BR numa (7). +.PP +Use +.BR get_mempolicy (2) +with the +.B MPOL_F_MEMS_ALLOWED +flag to obtain the set of nodes that are allowed by +the calling process's cpuset. +Note that this information is subject to change at any +time by manual or automatic reconfiguration of the cpuset. +.PP +Use of +.BR migrate_pages () +may result in pages whose location +(node) violates the memory policy established for the +specified addresses (see +.BR mbind (2)) +and/or the specified process (see +.BR set_mempolicy (2)). +That is, memory policy does not constrain the destination +nodes used by +.BR migrate_pages (). +.PP +The +.I +header is not included with glibc, but requires installing +.I libnuma-devel +or a similar package. +.SH SEE ALSO +.BR get_mempolicy (2), +.BR mbind (2), +.BR set_mempolicy (2), +.BR numa (3), +.BR numa_maps (5), +.BR cpuset (7), +.BR numa (7), +.BR migratepages (8), +.BR numastat (8) +.PP +.IR Documentation/vm/page_migration +in the Linux kernel source tree +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mincore.2 b/man2/mincore.2 new file mode 100644 index 0000000..eac6ff7 --- /dev/null +++ b/man2/mincore.2 @@ -0,0 +1,184 @@ +.\" Copyright (C) 2001 Bert Hubert +.\" and Copyright (C) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created Sun Jun 3 17:23:32 2001 by bert hubert +.\" Slightly adapted, following comments by Hugh Dickins, aeb, 2001-06-04. +.\" Modified, 20 May 2003, Michael Kerrisk +.\" Modified, 30 Apr 2004, Michael Kerrisk +.\" 2005-04-05 mtk, Fixed error descriptions +.\" after message from +.\" 2007-01-08 mtk, rewrote various parts +.\" +.TH MINCORE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mincore \- determine whether pages are resident in memory +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int mincore(void *" addr ", size_t " length ", unsigned char *" vec ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mincore (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +.BR mincore () +returns a vector that indicates whether pages +of the calling process's virtual memory are resident in core (RAM), +and so will not cause a disk access (page fault) if referenced. +The kernel returns residency information about the pages +starting at the address +.IR addr , +and continuing for +.I length +bytes. +.PP +The +.I addr +argument must be a multiple of the system page size. +The +.I length +argument need not be a multiple of the page size, +but since residency information is returned for whole pages, +.I length +is effectively rounded up to the next multiple of the page size. +One may obtain the page size +.RB ( PAGE_SIZE ) +using +.IR sysconf(_SC_PAGESIZE) . +.PP +The +.I vec +argument must point to an array containing at least +.I "(length+PAGE_SIZE\-1) / PAGE_SIZE" +bytes. +On return, +the least significant bit of each byte will be set if +the corresponding page is currently resident in memory, +and be clear otherwise. +(The settings of the other bits in each byte are undefined; +these bits are reserved for possible later use.) +Of course the information returned in +.I vec +is only a snapshot: pages that are not +locked in memory can come and go at any moment, and the contents of +.I vec +may already be stale by the time this call returns. +.SH RETURN VALUE +On success, +.BR mincore () +returns zero. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.B EAGAIN +kernel is temporarily out of resources. +.TP +.B EFAULT +.I vec +points to an invalid address. +.TP +.B EINVAL +.I addr +is not a multiple of the page size. +.TP +.B ENOMEM +.I length +is greater than +.RI ( TASK_SIZE " \- " addr ). +(This could occur if a negative value is specified for +.IR length , +since that value will be interpreted as a large +unsigned integer.) +In Linux 2.6.11 and earlier, the error +.B EINVAL +was returned for this condition. +.TP +.B ENOMEM +.I addr +to +.I addr ++ +.I length +contained unmapped memory. +.SH VERSIONS +Available since Linux 2.3.99pre1 and glibc 2.2. +.SH CONFORMING TO +.BR mincore () +is not specified in POSIX.1, +and it is not available on all UNIX implementations. +.\" It is on at least NetBSD, FreeBSD, OpenBSD, Solaris 8, +.\" AIX 5.1, SunOS 4.1 +.\" .SH HISTORY +.\" The +.\" .BR mincore () +.\" function first appeared in 4.4BSD. +.SH BUGS +Before kernel 2.6.21, +.BR mincore () +did not return correct information for +.B MAP_PRIVATE +mappings, or for nonlinear mappings (established using +.BR remap_file_pages (2)). +.\" Linux (up to now, 2.6.5), +.\" .B mincore +.\" does not return correct information for MAP_PRIVATE mappings: +.\" for a MAP_PRIVATE file mapping, +.\" .B mincore +.\" returns the residency of the file pages, rather than any +.\" modified process-private pages that have been copied on write; +.\" for a MAP_PRIVATE mapping of +.\" .IR /dev/zero , +.\" .B mincore +.\" always reports pages as nonresident; +.\" and for a MAP_PRIVATE, MAP_ANONYMOUS mapping, +.\" .B mincore +.\" always fails with the error +.\" .BR ENOMEM . +.SH SEE ALSO +.BR fincore (1), +.BR madvise (2), +.BR mlock (2), +.BR mmap (2), +.BR posix_fadvise (2), +.BR posix_madvise (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mkdir.2 b/man2/mkdir.2 new file mode 100644 index 0000000..28839bd --- /dev/null +++ b/man2/mkdir.2 @@ -0,0 +1,262 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt +.\" and Copyright (C) 1993,1994 Ian Jackson +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" You may distribute it under the terms of the GNU General +.\" Public License. It comes with NO WARRANTY. +.\" %%%LICENSE_END +.\" +.TH MKDIR 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mkdir, mkdirat \- create a directory +.SH SYNOPSIS +.nf +.B #include +.B #include +.\" .B #include +.PP +.BI "int mkdir(const char *" pathname ", mode_t " mode ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int mkdirat(int " dirfd ", const char *" pathname ", mode_t " mode ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mkdirat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +.BR mkdir () +attempts to create a directory named +.IR pathname . +.PP +The argument +.I mode +specifies the mode for the new directory (see +.BR inode (7)). +It is modified by the process's +.I umask +in the usual way: in the absence of a default ACL, the mode of the +created directory is +.RI ( mode " & ~" umask " & 0777)." +Whether other +.I mode +bits are honored for the created directory depends on the operating system. +For Linux, see NOTES below. +.PP +The newly created directory will be owned by the effective user ID of the +process. +If the directory containing the file has the set-group-ID +bit set, or if the filesystem is mounted with BSD group semantics +.RI ( "mount -o bsdgroups" +or, synonymously +.IR "mount -o grpid" ), +the new directory will inherit the group ownership from its parent; +otherwise it will be owned by the effective group ID of the process. +.PP +If the parent directory has the set-group-ID bit set, then so will the +newly created directory. +.\" +.\" +.SS mkdirat() +The +.BR mkdirat () +system call operates in exactly the same way as +.BR mkdir (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR mkdir () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR mkdir ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +See +.BR openat (2) +for an explanation of the need for +.BR mkdirat (). +.SH RETURN VALUE +.BR mkdir () +and +.BR mkdirat () +return zero on success, or \-1 if an error occurred (in which case, +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EACCES +The parent directory does not allow write permission to the process, +or one of the directories in +.I pathname +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.B EDQUOT +The user's quota of disk blocks or inodes on the filesystem has been +exhausted. +.TP +.B EEXIST +.I pathname +already exists (not necessarily as a directory). +This includes the case where +.I pathname +is a symbolic link, dangling or not. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EINVAL +The final component ("basename") of the new directory's +.I pathname +is invalid +(e.g., it contains characters not permitted by the underlying filesystem). +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B EMLINK +The number of links to the parent directory would exceed +.BR LINK_MAX . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing +.I pathname +has no room for the new directory. +.TP +.B ENOSPC +The new directory cannot be created because the user's disk quota is +exhausted. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EPERM +The filesystem containing +.I pathname +does not support the creation of directories. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.PP +The following additional errors can occur for +.BR mkdirat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR mkdirat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR mkdir (): +SVr4, BSD, POSIX.1-2001, POSIX.1-2008. +.\" SVr4 documents additional EIO, EMULTIHOP +.PP +.BR mkdirat (): +POSIX.1-2008. +.SH NOTES +Under Linux, apart from the permission bits, the +.B S_ISVTX +.I mode +bit is also honored. +.PP +There are many infelicities in the protocol underlying NFS. +Some of these affect +.BR mkdir (). +.SS Glibc notes +On older kernels where +.BR mkdirat () +is unavailable, the glibc wrapper function falls back to the use of +.BR mkdir (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.IR /proc/self/fd +that corresponds to the +.IR dirfd +argument. +.SH SEE ALSO +.BR mkdir (1), +.BR chmod (2), +.BR chown (2), +.BR mknod (2), +.BR mount (2), +.BR rmdir (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR acl (5) +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mkdirat.2 b/man2/mkdirat.2 new file mode 100644 index 0000000..467b98a --- /dev/null +++ b/man2/mkdirat.2 @@ -0,0 +1 @@ +.so man2/mkdir.2 diff --git a/man2/mknod.2 b/man2/mknod.2 new file mode 100644 index 0000000..82134da --- /dev/null +++ b/man2/mknod.2 @@ -0,0 +1,311 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt +.\" and Copyright (C) 1993,1994 Ian Jackson +.\" and Copyright (C) 2006, 2014, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" You may distribute it under the terms of the GNU General +.\" Public License. It comes with NO WARRANTY. +.\" %%%LICENSE_END +.\" +.\" Modified 1996-08-18 by urs +.\" Modified 2003-04-23 by Michael Kerrisk +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH MKNOD 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mknod, mknodat \- create a special or ordinary file +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.PP +.BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int mknodat(int " dirfd ", const char *" pathname ", mode_t " mode \ +", dev_t " dev ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mknod (): +.ad l +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +The system call +.BR mknod () +creates a filesystem node (file, device special file, or +named pipe) named +.IR pathname , +with attributes specified by +.I mode +and +.IR dev . +.PP +The +.I mode +argument specifies both the file mode to use and the type of node +to be created. +It should be a combination (using bitwise OR) of one of the file types +listed below and zero or more of the file mode bits listed in +.BR inode (7). +.PP +The file mode is modified by the process's +.I umask +in the usual way: in the absence of a default ACL, the permissions of the +created node are +.RI ( mode " & ~" umask ). +.PP +The file type must be one of +.BR S_IFREG , +.BR S_IFCHR , +.BR S_IFBLK , +.BR S_IFIFO , +or +.B S_IFSOCK +.\" (S_IFSOCK since Linux 1.2.4) +to specify a regular file (which will be created empty), character +special file, block special file, FIFO (named pipe), or UNIX domain socket, +respectively. +(Zero file type is equivalent to type +.BR S_IFREG .) +.PP +If the file type is +.B S_IFCHR +or +.BR S_IFBLK , +then +.I dev +specifies the major and minor numbers of the newly created device +special file +.RB ( makedev (3) +may be useful to build the value for +.IR dev ); +otherwise it is ignored. +.PP +If +.I pathname +already exists, or is a symbolic link, this call fails with an +.B EEXIST +error. +.PP +The newly created node will be owned by the effective user ID of the +process. +If the directory containing the node has the set-group-ID +bit set, or if the filesystem is mounted with BSD group semantics, the +new node will inherit the group ownership from its parent directory; +otherwise it will be owned by the effective group ID of the process. +.\" +.\" +.SS mknodat() +The +.BR mknodat () +system call operates in exactly the same way as +.BR mknod (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR mknod () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR mknod ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +See +.BR openat (2) +for an explanation of the need for +.BR mknodat (). +.SH RETURN VALUE +.BR mknod () +and +.BR mknodat () +return zero on success, or \-1 if an error occurred (in which case, +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EACCES +The parent directory does not allow write permission to the process, +or one of the directories in the path prefix of +.I pathname +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.B EDQUOT +The user's quota of disk blocks or inodes on the filesystem has been +exhausted. +.TP +.B EEXIST +.I pathname +already exists. +This includes the case where +.I pathname +is a symbolic link, dangling or not. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EINVAL +.I mode +requested creation of something other than a regular file, device +special file, FIFO or socket. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing +.I pathname +has no room for the new node. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EPERM +.I mode +requested creation of something other than a regular file, +FIFO (named pipe), or UNIX domain socket, and the caller +is not privileged (Linux: does not have the +.B CAP_MKNOD +capability); +.\" For UNIX domain sockets and regular files, EPERM is returned only in +.\" Linux 2.2 and earlier; in Linux 2.4 and later, unprivileged can +.\" use mknod() to make these files. +also returned if the filesystem containing +.I pathname +does not support the type of node requested. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.PP +The following additional errors can occur for +.BR mknodat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR mknodat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR mknod (): +SVr4, 4.4BSD, POSIX.1-2001 (but see below), POSIX.1-2008. +.\" The Linux version differs from the SVr4 version in that it +.\" does not require root permission to create pipes, also in that no +.\" EMULTIHOP, ENOLINK, or EINTR error is documented. +.PP +.BR mknodat (): +POSIX.1-2008. +.SH NOTES +POSIX.1-2001 says: "The only portable use of +.BR mknod () +is to create a FIFO-special file. +If +.I mode +is not +.B S_IFIFO +or +.I dev +is not 0, the behavior of +.BR mknod () +is unspecified." +However, nowadays one should never use +.BR mknod () +for this purpose; one should use +.BR mkfifo (3), +a function especially defined for this purpose. +.PP +Under Linux, +.BR mknod () +cannot be used to create directories. +One should make directories with +.BR mkdir (2). +.\" and one should make UNIX domain sockets with socket(2) and bind(2). +.PP +There are many infelicities in the protocol underlying NFS. +Some of these affect +.BR mknod () +and +.BR mknodat (). +.SH SEE ALSO +.BR mknod (1), +.BR chmod (2), +.BR chown (2), +.BR fcntl (2), +.BR mkdir (2), +.BR mount (2), +.BR socket (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR makedev (3), +.BR mkfifo (3), +.BR acl (5) +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mknodat.2 b/man2/mknodat.2 new file mode 100644 index 0000000..3db2282 --- /dev/null +++ b/man2/mknodat.2 @@ -0,0 +1 @@ +.so man2/mknod.2 diff --git a/man2/mlock.2 b/man2/mlock.2 new file mode 100644 index 0000000..a9ea342 --- /dev/null +++ b/man2/mlock.2 @@ -0,0 +1,508 @@ +.\" Copyright (C) Michael Kerrisk, 2004 +.\" using some material drawn from earlier man pages +.\" written by Thomas Kuhn, Copyright 1996 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH MLOCK 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mlock(const void *" addr ", size_t " len ); +.BI "int mlock2(const void *" addr ", size_t " len ", int " flags ); +.BI "int munlock(const void *" addr ", size_t " len ); +.PP +.BI "int mlockall(int " flags ); +.B int munlockall(void); +.fi +.SH DESCRIPTION +.BR mlock (), +.BR mlock2 (), +and +.BR mlockall () +lock part or all of the calling process's virtual address +space into RAM, preventing that memory from being paged to the +swap area. +.PP +.BR munlock () +and +.BR munlockall () +perform the converse operation, +unlocking part or all of the calling process's virtual +address space, so that pages in the specified virtual address range may +once more to be swapped out if required by the kernel memory manager. +.PP +Memory locking and unlocking are performed in units of whole pages. +.SS mlock(), mlock2(), and munlock() +.BR mlock () +locks pages in the address range starting at +.I addr +and continuing for +.I len +bytes. +All pages that contain a part of the specified address range are +guaranteed to be resident in RAM when the call returns successfully; +the pages are guaranteed to stay in RAM until later unlocked. +.PP +.BR mlock2 () +.\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e +.\" commit de60f5f10c58d4f34b68622442c0e04180367f3f +.\" commit b0f205c2a3082dd9081f9a94e50658c5fa906ff1 +also locks pages in the specified range starting at +.I addr +and continuing for +.I len +bytes. +However, the state of the pages contained in that range after the call +returns successfully will depend on the value in the +.I flags +argument. +.PP +The +.I flags +argument can be either 0 or the following constant: +.TP +.B MLOCK_ONFAULT +Lock pages that are currently resident and mark the entire range so +that the remaining nonresident pages locked when they are populated +by a page fault. +.PP +.PP +If +.I flags +is 0, +.BR mlock2 () +behaves exactly the same as +.BR mlock (). +.PP +.BR munlock () +unlocks pages in the address range starting at +.I addr +and continuing for +.I len +bytes. +After this call, all pages that contain a part of the specified +memory range can be moved to external swap space again by the kernel. +.SS mlockall() and munlockall() +.BR mlockall () +locks all pages mapped into the address space of the +calling process. +This includes the pages of the code, data and stack +segment, as well as shared libraries, user space kernel data, shared +memory, and memory-mapped files. +All mapped pages are guaranteed +to be resident in RAM when the call returns successfully; +the pages are guaranteed to stay in RAM until later unlocked. +.PP +The +.I flags +argument is constructed as the bitwise OR of one or more of the +following constants: +.TP 1.2i +.B MCL_CURRENT +Lock all pages which are currently mapped into the address space of +the process. +.TP +.B MCL_FUTURE +Lock all pages which will become mapped into the address space of the +process in the future. +These could be, for instance, new pages required +by a growing heap and stack as well as new memory-mapped files or +shared memory regions. +.TP +.BR MCL_ONFAULT " (since Linux 4.4)" +Used together with +.BR MCL_CURRENT , +.BR MCL_FUTURE , +or both. +Mark all current (with +.BR MCL_CURRENT ) +or future (with +.BR MCL_FUTURE ) +mappings to lock pages when they are faulted in. +When used with +.BR MCL_CURRENT , +all present pages are locked, but +.BR mlockall () +will not fault in non-present pages. +When used with +.BR MCL_FUTURE , +all future mappings will be marked to lock pages when they are faulted +in, but they will not be populated by the lock when the mapping is +created. +.B MCL_ONFAULT +must be used with either +.B MCL_CURRENT +or +.B MCL_FUTURE +or both. +.PP +If +.B MCL_FUTURE +has been specified, then a later system call (e.g., +.BR mmap (2), +.BR sbrk (2), +.BR malloc (3)), +may fail if it would cause the number of locked bytes to exceed +the permitted maximum (see below). +In the same circumstances, stack growth may likewise fail: +the kernel will deny stack expansion and deliver a +.B SIGSEGV +signal to the process. +.PP +.BR munlockall () +unlocks all pages mapped into the address space of the +calling process. +.SH RETURN VALUE +On success, these system calls return 0. +On error, \-1 is returned, +.I errno +is set appropriately, and no changes are made to any locks in the +address space of the process. +.SH ERRORS +.TP +.B ENOMEM +(Linux 2.6.9 and later) the caller had a nonzero +.B RLIMIT_MEMLOCK +soft resource limit, but tried to lock more memory than the limit +permitted. +This limit is not enforced if the process is privileged +.RB ( CAP_IPC_LOCK ). +.TP +.B ENOMEM +(Linux 2.4 and earlier) the calling process tried to lock more than +half of RAM. +.\" In the case of mlock(), this check is somewhat buggy: it doesn't +.\" take into account whether the to-be-locked range overlaps with +.\" already locked pages. Thus, suppose we allocate +.\" (num_physpages / 4 + 1) of memory, and lock those pages once using +.\" mlock(), and then lock the *same* page range a second time. +.\" In the case, the second mlock() call will fail, since the check +.\" calculates that the process is trying to lock (num_physpages / 2 + 2) +.\" pages, which of course is not true. (MTK, Nov 04, kernel 2.4.28) +.TP +.B EPERM +The caller is not privileged, but needs privilege +.RB ( CAP_IPC_LOCK ) +to perform the requested operation. +.\"SVr4 documents an additional EAGAIN error code. +.PP +For +.BR mlock (), +.BR mlock2 (), +and +.BR munlock (): +.TP +.B EAGAIN +Some or all of the specified address range could not be locked. +.TP +.B EINVAL +The result of the addition +.IR addr + len +was less than +.IR addr +(e.g., the addition may have resulted in an overflow). +.TP +.B EINVAL +(Not on Linux) +.I addr +was not a multiple of the page size. +.TP +.B ENOMEM +Some of the specified address range does not correspond to mapped +pages in the address space of the process. +.TP +.B ENOMEM +Locking or unlocking a region would result in the total number of +mappings with distinct attributes (e.g., locked versus unlocked) +exceeding the allowed maximum. +.\" I.e., the number of VMAs would exceed the 64kB maximum +(For example, unlocking a range in the middle of a currently locked +mapping would result in three mappings: +two locked mappings at each end and an unlocked mapping in the middle.) +.PP +For +.BR mlock2 (): +.TP +.B EINVAL +Unknown \fIflags\fP were specified. +.PP +For +.BR mlockall (): +.TP +.B EINVAL +Unknown \fIflags\fP were specified or +.B MCL_ONFAULT +was specified without either +.B MCL_FUTURE +or +.BR MCL_CURRENT . +.PP +For +.BR munlockall (): +.TP +.B EPERM +(Linux 2.6.8 and earlier) The caller was not privileged +.RB ( CAP_IPC_LOCK ). +.SH VERSIONS +.BR mlock2 () +is available since Linux 4.4; +glibc support was added in version 2.27. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.PP +mlock2 () +is Linux specific. +.SH AVAILABILITY +On POSIX systems on which +.BR mlock () +and +.BR munlock () +are available, +.B _POSIX_MEMLOCK_RANGE +is defined in \fI\fP and the number of bytes in a page +can be determined from the constant +.B PAGESIZE +(if defined) in \fI\fP or by calling +.IR sysconf(_SC_PAGESIZE) . +.PP +On POSIX systems on which +.BR mlockall () +and +.BR munlockall () +are available, +.B _POSIX_MEMLOCK +is defined in \fI\fP to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines it to 1. +.SH NOTES +Memory locking has two main applications: real-time algorithms and +high-security data processing. +Real-time applications require +deterministic timing, and, like scheduling, paging is one major cause +of unexpected program execution delays. +Real-time applications will +usually also switch to a real-time scheduler with +.BR sched_setscheduler (2). +Cryptographic security software often handles critical bytes like +passwords or secret keys as data structures. +As a result of paging, +these secrets could be transferred onto a persistent swap store medium, +where they might be accessible to the enemy long after the security +software has erased the secrets in RAM and terminated. +(But be aware that the suspend mode on laptops and some desktop +computers will save a copy of the system's RAM to disk, regardless +of memory locks.) +.PP +Real-time processes that are using +.BR mlockall () +to prevent delays on page faults should reserve enough +locked stack pages before entering the time-critical section, +so that no page fault can be caused by function calls. +This can be achieved by calling a function that allocates a +sufficiently large automatic variable (an array) and writes to the +memory occupied by this array in order to touch these stack pages. +This way, enough pages will be mapped for the stack and can be +locked into RAM. +The dummy writes ensure that not even copy-on-write +page faults can occur in the critical section. +.PP +Memory locks are not inherited by a child created via +.BR fork (2) +and are automatically removed (unlocked) during an +.BR execve (2) +or when the process terminates. +The +.BR mlockall () +.B MCL_FUTURE +and +.B MCL_FUTURE | MCL_ONFAULT +settings are not inherited by a child created via +.BR fork (2) +and are cleared during an +.BR execve (2). +.PP +Note that +.BR fork (2) +will prepare the address space for a copy-on-write operation. +The consequence is that any write access that follows will cause +a page fault that in turn may cause high latencies for a real-time process. +Therefore, it is crucial not to invoke +.BR fork (2) +after an +.BR mlockall () +or +.BR mlock () +operation\(emnot even from a thread which runs at a low priority within +a process which also has a thread running at elevated priority. +.PP +The memory lock on an address range is automatically removed +if the address range is unmapped via +.BR munmap (2). +.PP +Memory locks do not stack, that is, pages which have been locked several times +by calls to +.BR mlock (), +.BR mlock2 (), +or +.BR mlockall () +will be unlocked by a single call to +.BR munlock () +for the corresponding range or by +.BR munlockall (). +Pages which are mapped to several locations or by several processes stay +locked into RAM as long as they are locked at least at one location or by +at least one process. +.PP +If a call to +.BR mlockall () +which uses the +.B MCL_FUTURE +flag is followed by another call that does not specify this flag, the +changes made by the +.B MCL_FUTURE +call will be lost. +.PP +The +.BR mlock2 () +.B MLOCK_ONFAULT +flag and the +.BR mlockall () +.B MCL_ONFAULT +flag allow efficient memory locking for applications that deal with +large mappings where only a (small) portion of pages in the mapping are touched. +In such cases, locking all of the pages in a mapping would incur +a significant penalty for memory locking. +.SS Linux notes +Under Linux, +.BR mlock (), +.BR mlock2 (), +and +.BR munlock () +automatically round +.I addr +down to the nearest page boundary. +However, the POSIX.1 specification of +.BR mlock () +and +.BR munlock () +allows an implementation to require that +.I addr +is page aligned, so portable applications should ensure this. +.PP +The +.I VmLck +field of the Linux-specific +.I /proc/[pid]/status +file shows how many kilobytes of memory the process with ID +.I PID +has locked using +.BR mlock (), +.BR mlock2 (), +.BR mlockall (), +and +.BR mmap (2) +.BR MAP_LOCKED . +.SS Limits and permissions +In Linux 2.6.8 and earlier, +a process must be privileged +.RB ( CAP_IPC_LOCK ) +in order to lock memory and the +.B RLIMIT_MEMLOCK +soft resource limit defines a limit on how much memory the process may lock. +.PP +Since Linux 2.6.9, no limits are placed on the amount of memory +that a privileged process can lock and the +.B RLIMIT_MEMLOCK +soft resource limit instead defines a limit on how much memory an +unprivileged process may lock. +.SH BUGS +In Linux 4.8 and earlier, +a bug in the kernel's accounting of locked memory for unprivileged processes +(i.e., without +.BR CAP_IPC_LOCK ) +meant that if the region specified by +.I addr +and +.I len +overlapped an existing lock, +then the already locked bytes in the overlapping region were counted twice +when checking against the limit. +Such double accounting could incorrectly calculate a "total locked memory" +value for the process that exceeded the +.BR RLIMIT_MEMLOCK +limit, with the result that +.BR mlock () +and +.BR mlock2() +would fail on requests that should have succeeded. +This bug was fixed +.\" commit 0cf2f6f6dc605e587d2c1120f295934c77e810e8 +in Linux 4.9 +.PP +In the 2.4 series Linux kernels up to and including 2.4.17, +a bug caused the +.BR mlockall () +.B MCL_FUTURE +flag to be inherited across a +.BR fork (2). +This was rectified in kernel 2.4.18. +.PP +Since kernel 2.6.9, if a privileged process calls +.I mlockall(MCL_FUTURE) +and later drops privileges (loses the +.B CAP_IPC_LOCK +capability by, for example, +setting its effective UID to a nonzero value), +then subsequent memory allocations (e.g., +.BR mmap (2), +.BR brk (2)) +will fail if the +.B RLIMIT_MEMLOCK +resource limit is encountered. +.\" See the following LKML thread: +.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2 +.\" "Rationale for RLIMIT_MEMLOCK" +.\" 23 Jan 2006 +.SH SEE ALSO +.BR mincore (2), +.BR mmap (2), +.BR setrlimit (2), +.BR shmctl (2), +.BR sysconf (3), +.BR proc (5), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mlock2.2 b/man2/mlock2.2 new file mode 100644 index 0000000..5e5b3c7 --- /dev/null +++ b/man2/mlock2.2 @@ -0,0 +1 @@ +.so man2/mlock.2 diff --git a/man2/mlockall.2 b/man2/mlockall.2 new file mode 100644 index 0000000..5e5b3c7 --- /dev/null +++ b/man2/mlockall.2 @@ -0,0 +1 @@ +.so man2/mlock.2 diff --git a/man2/mmap.2 b/man2/mmap.2 new file mode 100644 index 0000000..48c799c --- /dev/null +++ b/man2/mmap.2 @@ -0,0 +1,906 @@ +.\" Copyright (C) 1996 Andries Brouwer +.\" and Copyright (C) 2006, 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2000-03-25 by Jim Van Zandt +.\" Modified 2001-10-04 by John Levon +.\" Modified 2003-02-02 by Andi Kleen +.\" Modified 2003-05-21 by Michael Kerrisk +.\" MAP_LOCKED works from 2.5.37 +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2004-09-11 by aeb +.\" Modified 2004-12-08, from Eric Estievenart +.\" Modified 2004-12-08, mtk, formatting tidy-ups +.\" Modified 2006-12-04, mtk, various parts rewritten +.\" 2007-07-10, mtk, Added an example program. +.\" 2008-11-18, mtk, document MAP_STACK +.\" +.TH MMAP 2 2017-12-18 "Linux" "Linux Programmer's Manual" +.SH NAME +mmap, munmap \- map or unmap files or devices into memory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *mmap(void *" addr ", size_t " length \ +", int " prot ", int " flags , +.BI " int " fd ", off_t " offset ); +.BI "int munmap(void *" addr ", size_t " length ); +.fi +.PP +See NOTES for information on feature test macro requirements. +.SH DESCRIPTION +.BR mmap () +creates a new mapping in the virtual address space of +the calling process. +The starting address for the new mapping is specified in +.IR addr . +The +.I length +argument specifies the length of the mapping (which must be greater than 0). +.PP +If +.I addr +is NULL, +then the kernel chooses the address at which to create the mapping; +this is the most portable method of creating a new mapping. +If +.I addr +is not NULL, +then the kernel takes it as a hint about where to place the mapping; +on Linux, the mapping will be created at a nearby page boundary. +.\" Before Linux 2.6.24, the address was rounded up to the next page +.\" boundary; since 2.6.24, it is rounded down! +The address of the new mapping is returned as the result of the call. +.PP +The contents of a file mapping (as opposed to an anonymous mapping; see +.B MAP_ANONYMOUS +below), are initialized using +.I length +bytes starting at offset +.I offset +in the file (or other object) referred to by the file descriptor +.IR fd . +.I offset +must be a multiple of the page size as returned by +.IR sysconf(_SC_PAGE_SIZE) . +.PP +The +.I prot +argument describes the desired memory protection of the mapping +(and must not conflict with the open mode of the file). +It is either +.B PROT_NONE +or the bitwise OR of one or more of the following flags: +.TP 1.1i +.B PROT_EXEC +Pages may be executed. +.TP +.B PROT_READ +Pages may be read. +.TP +.B PROT_WRITE +Pages may be written. +.TP +.B PROT_NONE +Pages may not be accessed. +.PP +The +.I flags +argument determines whether updates to the mapping +are visible to other processes mapping the same region, +and whether updates are carried through to the underlying file. +This behavior is determined by including exactly one +of the following values in +.IR flags : +.TP +.B MAP_SHARED +Share this mapping. +Updates to the mapping are visible to other processes mapping the same region, +and (in the case of file-backed mappings) +are carried through to the underlying file. +(To precisely control when updates are carried through +to the underlying file requires the use of +.BR msync (2).) +.TP +.B MAP_PRIVATE +Create a private copy-on-write mapping. +Updates to the mapping are not visible to other processes +mapping the same file, and are not carried through to +the underlying file. +It is unspecified whether changes made to the file after the +.BR mmap () +call are visible in the mapped region. +.PP +Both of these flags are described in POSIX.1-2001 and POSIX.1-2008. +.PP +In addition, zero or more of the following values can be ORed in +.IR flags : +.TP +.BR MAP_32BIT " (since Linux 2.4.20, 2.6)" +Put the mapping into the first 2 Gigabytes of the process address space. +This flag is supported only on x86-64, for 64-bit programs. +It was added to allow thread stacks to be allocated somewhere +in the first 2\ GB of memory, +so as to improve context-switch performance on some early +64-bit processors. +.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 +Modern x86-64 processors no longer have this performance problem, +so use of this flag is not required on those systems. +The +.B MAP_32BIT +flag is ignored when +.B MAP_FIXED +is set. +.TP +.B MAP_ANON +Synonym for +.BR MAP_ANONYMOUS . +Deprecated. +.TP +.B MAP_ANONYMOUS +The mapping is not backed by any file; +its contents are initialized to zero. +The +.I fd +argument is ignored; +however, some implementations require +.I fd +to be \-1 if +.B MAP_ANONYMOUS +(or +.BR MAP_ANON ) +is specified, +and portable applications should ensure this. +The +.I offset +argument should be zero. +.\" See the pgoff overflow check in do_mmap(). +.\" See the offset check in sys_mmap in arch/x86/kernel/sys_x86_64.c. +The use of +.B MAP_ANONYMOUS +in conjunction with +.B MAP_SHARED +is supported on Linux only since kernel 2.4. +.TP +.B MAP_DENYWRITE +This flag is ignored. +.\" Introduced in 1.1.36, removed in 1.3.24. +(Long ago, it signaled that attempts to write to the underlying file +should fail with +.BR ETXTBUSY . +But this was a source of denial-of-service attacks.) +.TP +.B MAP_EXECUTABLE +This flag is ignored. +.\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link. +.\" (Long ago, it signaled that the underlying file is an executable. +.\" However, that information was not really used anywhere.) +.\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of +.\" MAP_DENYWRITE? +.TP +.B MAP_FILE +Compatibility flag. +Ignored. +.\" On some systems, this was required as the opposite of +.\" MAP_ANONYMOUS -- mtk, 1 May 2007 +.TP +.B MAP_FIXED +Don't interpret +.I addr +as a hint: place the mapping at exactly that address. +.I addr +must be suitably aligned: for most architectures a multiple of the page +size is sufficient; however, some architectures may impose additional +restrictions. +If the memory region specified by +.I addr +and +.I len +overlaps pages of any existing mapping(s), then the overlapped +part of the existing mapping(s) will be discarded. +If the specified address cannot be used, +.BR mmap () +will fail. +Software that aspires to be portable should use this option with care, +keeping in mind that the exact layout of a process's memory mappings +is allowed to change significantly between kernel versions, +C library versions, and operating system releases. +.IP +Furthermore, this option is extremely hazardous (when used on its own), +because it forcibly removes preexisting mappings, +making it easy for a multithreaded process to corrupt its own address space. +.IP +For example, thread A looks through +.I /proc//maps +and locates an available address range, +while thread B simultaneously acquires part or all of that same +address range. +Thread A then calls +.BR mmap(MAP_FIXED) , +effectively overwriting the mapping that thread B created. +.IP +Thread B need not create a mapping directly; simply making a library call +that, internally, uses +.BR dlopen (3) +to load some other shared library, will +suffice. +The +.BR dlopen (3) +call will map the library into the process's address space. +Furthermore, almost any library call may be implemented in a way that +adds memory mappings to the address space, either with this technique, +or by simply allocating memory. +Examples include +.BR brk (2), +.BR malloc (3), +.BR pthread_create (3), +and the PAM libraries +.UR http://www.linux-pam.org +.UE . +.TP +.B MAP_GROWSDOWN +This flag is used for stacks. +It indicates to the kernel virtual memory system that the mapping +should extend downward in memory. +The return address is one page lower than the memory area that is +actually created in the process's virtual address space. +Touching an address in the "guard" page below the mapping will cause +the mapping to grow by a page. +This growth can be repeated until the mapping grows to within a +page of the high end of the next lower mapping, +at which point touching the "guard" page will result in a +.B SIGSEGV +signal. +.TP +.BR MAP_HUGETLB " (since Linux 2.6.32)" +Allocate the mapping using "huge pages." +See the Linux kernel source file +.I Documentation/vm/hugetlbpage.txt +for further information, as well as NOTES, below. +.TP +.BR MAP_HUGE_2MB ", " MAP_HUGE_1GB " (since Linux 3.8)" +.\" See https://lwn.net/Articles/533499/ +Used in conjunction with +.B MAP_HUGETLB +to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) +on systems that support multiple hugetlb page sizes. +.IP +More generally, the desired huge page size can be configured by encoding +the base-2 logarithm of the desired page size in the six bits at the offset +.BR MAP_HUGE_SHIFT . +(A value of zero in this bit field provides the default huge page size; +the default huge page size can be discovered vie the +.I Hugepagesize +field exposed by +.IR /proc/meminfo .) +Thus, the above two constants are defined as: +.IP +.in +4n +.EX +#define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT) +#define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT) +.EE +.in +.IP +The range of huge page sizes that are supported by the system +can be discovered by listing the subdirectories in +.IR /sys/kernel/mm/hugepages . +.TP +.BR MAP_LOCKED " (since Linux 2.5.37)" +Mark the mapped region to be locked in the same way as +.BR mlock (2). +This implementation will try to populate (prefault) the whole range but the +.BR mmap () +call doesn't fail with +.B ENOMEM +if this fails. +Therefore major faults might happen later on. +So the semantic is not as strong as +.BR mlock (2). +One should use +.BR mmap () +plus +.BR mlock (2) +when major faults are not acceptable after the initialization of the mapping. +The +.BR MAP_LOCKED +flag is ignored in older kernels. +.\" If set, the mapped pages will not be swapped out. +.TP +.BR MAP_NONBLOCK " (since Linux 2.5.46)" +This flag is meaningful only in conjunction with +.BR MAP_POPULATE . +Don't perform read-ahead: +create page tables entries only for pages +that are already present in RAM. +Since Linux 2.6.23, this flag causes +.BR MAP_POPULATE +to do nothing. +One day, the combination of +.BR MAP_POPULATE +and +.BR MAP_NONBLOCK +may be reimplemented. +.TP +.B MAP_NORESERVE +Do not reserve swap space for this mapping. +When swap space is reserved, one has the guarantee +that it is possible to modify the mapping. +When swap space is not reserved one might get +.B SIGSEGV +upon a write +if no physical memory is available. +See also the discussion of the file +.I /proc/sys/vm/overcommit_memory +in +.BR proc (5). +In kernels before 2.6, this flag had effect only for +private writable mappings. +.TP +.BR MAP_POPULATE " (since Linux 2.5.46)" +Populate (prefault) page tables for a mapping. +For a file mapping, this causes read-ahead on the file. +This will help to reduce blocking on page faults later. +.BR MAP_POPULATE +is supported for private mappings only since Linux 2.6.23. +.TP +.BR MAP_STACK " (since Linux 2.6.27)" +Allocate the mapping at an address suitable for a process +or thread stack. +This flag is currently a no-op, +but is used in the glibc threading implementation so that +if some architectures require special treatment for stack allocations, +support can later be transparently implemented for glibc. +.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 +.\" commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7 +.\" http://thread.gmane.org/gmane.linux.kernel/720412 +.\" "pthread_create() slow for many threads; also time to revisit 64b +.\" context switch optimization?" +.TP +.BR MAP_UNINITIALIZED " (since Linux 2.6.33)" +Don't clear anonymous pages. +This flag is intended to improve performance on embedded devices. +This flag is honored only if the kernel was configured with the +.B CONFIG_MMAP_ALLOW_UNINITIALIZED +option. +Because of the security implications, +that option is normally enabled only on embedded devices +(i.e., devices where one has complete control of the contents of user memory). +.PP +Of the above flags, only +.B MAP_FIXED +is specified in POSIX.1-2001 and POSIX.1-2008. +However, most systems also support +.B MAP_ANONYMOUS +(or its synonym +.BR MAP_ANON ). +.\" FIXME . for later review when Issue 8 is one day released... +.\" POSIX may add MAP_ANON in the future +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=850 +.PP +Memory mapped by +.BR mmap () +is preserved across +.BR fork (2), +with the same attributes. +.PP +A file is mapped in multiples of the page size. +For a file that is not +a multiple of the page size, the remaining memory is zeroed when mapped, +and writes to that region are not written out to the file. +The effect of +changing the size of the underlying file of a mapping on the pages that +correspond to added or removed regions of the file is unspecified. +.SS munmap() +The +.BR munmap () +system call deletes the mappings for the specified address range, and +causes further references to addresses within the range to generate +invalid memory references. +The region is also automatically unmapped +when the process is terminated. +On the other hand, closing the file +descriptor does not unmap the region. +.PP +The address +.I addr +must be a multiple of the page size (but +.I length +need not be). +All pages containing a part +of the indicated range are unmapped, and subsequent references +to these pages will generate +.BR SIGSEGV . +It is not an error if the +indicated range does not contain any mapped pages. +.SH RETURN VALUE +On success, +.BR mmap () +returns a pointer to the mapped area. +On error, the value +.B MAP_FAILED +(that is, +.IR "(void\ *)\ \-1" ) +is returned, and +.I errno +is set to indicate the cause of the error. +.PP +On success, +.BR munmap () +returns 0. +On failure, it returns \-1, and +.I errno +is set to indicate the cause of the error (probably to +.BR EINVAL ). +.SH ERRORS +.TP +.B EACCES +A file descriptor refers to a non-regular file. +Or a file mapping was requested, but +.I fd +is not open for reading. +Or +.B MAP_SHARED +was requested and +.B PROT_WRITE +is set, but +.I fd +is not open in read/write +.RB ( O_RDWR ) +mode. +Or +.B PROT_WRITE +is set, but the file is append-only. +.TP +.B EAGAIN +The file has been locked, or too much memory has been locked (see +.BR setrlimit (2)). +.TP +.B EBADF +.I fd +is not a valid file descriptor (and +.B MAP_ANONYMOUS +was not set). +.TP +.B EINVAL +We don't like +.IR addr , +.IR length , +or +.I offset +(e.g., they are too large, or not aligned on a page boundary). +.TP +.B EINVAL +(since Linux 2.6.12) +.I length +was 0. +.TP +.B EINVAL +.I flags +contained neither +.B MAP_PRIVATE +or +.BR MAP_SHARED , +or contained both of these values. +.TP +.B ENFILE +.\" This is for shared anonymous segments +.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() +The system-wide limit on the total number of open files has been reached. +.\" .TP +.\" .B ENOEXEC +.\" A file could not be mapped for reading. +.TP +.B ENODEV +The underlying filesystem of the specified file does not support +memory mapping. +.TP +.B ENOMEM +No memory is available. +.TP +.B ENOMEM +The process's maximum number of mappings would have been exceeded. +This error can also occur for +.BR munmap (), +when unmapping a region in the middle of an existing mapping, +since this results in two smaller mappings on either side of +the region being unmapped. +.TP +.B ENOMEM +(since Linux 4.7) +The process's +.B RLIMIT_DATA +limit, described in +.BR getrlimit (2), +would have been exceeded. +.TP +.B EOVERFLOW +On 32-bit architecture together with the large file extension +(i.e., using 64-bit +.IR off_t ): +the number of pages used for +.I length +plus number of pages used for +.I offset +would overflow +.I "unsigned long" +(32 bits). +.TP +.B EPERM +The +.I prot +argument asks for +.B PROT_EXEC +but the mapped area belongs to a file on a filesystem that +was mounted no-exec. +.\" (Since 2.4.25 / 2.6.0.) +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B ETXTBSY +.B MAP_DENYWRITE +was set but the object specified by +.I fd +is open for writing. +.PP +Use of a mapped region can result in these signals: +.TP +.B SIGSEGV +Attempted write into a region mapped as read-only. +.TP +.B SIGBUS +Attempted access to a portion of the buffer that does not correspond +to the file (for example, beyond the end of the file, including the +case where another process has truncated the file). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw18 lb lb +l l l. +Interface Attribute Value +T{ +.BR mmap (), +.BR munmap () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD. +.\" SVr4 documents additional error codes ENXIO and ENODEV. +.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. +.SH AVAILABILITY +On POSIX systems on which +.BR mmap (), +.BR msync (2), +and +.BR munmap () +are available, +.B _POSIX_MAPPED_FILES +is defined in \fI\fP to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines it to 1. +.SH NOTES +On some hardware architectures (e.g., i386), +.B PROT_WRITE +implies +.BR PROT_READ . +It is architecture dependent whether +.B PROT_READ +implies +.B PROT_EXEC +or not. +Portable programs should always set +.B PROT_EXEC +if they intend to execute code in the new mapping. +.PP +The portable way to create a mapping is to specify +.I addr +as 0 (NULL), and omit +.B MAP_FIXED +from +.IR flags . +In this case, the system chooses the address for the mapping; +the address is chosen so as not to conflict with any existing mapping, +and will not be 0. +If the +.B MAP_FIXED +flag is specified, and +.I addr +is 0 (NULL), then the mapped address will be 0 (NULL). +.PP +Certain +.I flags +constants are defined only if suitable feature test macros are defined +(possibly by default): +.BR _DEFAULT_SOURCE +with glibc 2.19 or later; +or +.BR _BSD_SOURCE +or +.BR _SVID_SOURCE +in glibc 2.19 and earlier. +(Employing +.BR _GNU_SOURCE +also suffices, +and requiring that macro specifically would have been more logical, +since these flags are all Linux-specific.) +The relevant flags are: +.BR MAP_32BIT , +.BR MAP_ANONYMOUS +(and the synonym +.BR MAP_ANON ), +.BR MAP_DENYWRITE , +.BR MAP_EXECUTABLE , +.BR MAP_FILE , +.BR MAP_GROWSDOWN , +.BR MAP_HUGETLB , +.BR MAP_LOCKED , +.BR MAP_NONBLOCK , +.BR MAP_NORESERVE , +.BR MAP_POPULATE , +and +.BR MAP_STACK . +.PP +An application can determine which pages of a mapping are +currently resident in the buffer/page cache using +.BR mincore (2). +.\" +.SS Timestamps changes for file-backed mappings +For file-backed mappings, the +.I st_atime +field for the mapped file may be updated at any time between the +.BR mmap () +and the corresponding unmapping; the first reference to a mapped +page will update the field if it has not been already. +.PP +The +.I st_ctime +and +.I st_mtime +field for a file mapped with +.B PROT_WRITE +and +.B MAP_SHARED +will be updated after +a write to the mapped region, and before a subsequent +.BR msync (2) +with the +.B MS_SYNC +or +.B MS_ASYNC +flag, if one occurs. +.\" +.SS Huge page (Huge TLB) mappings +For mappings that employ huge pages, the requirements for the arguments of +.BR mmap () +and +.BR munmap () +differ somewhat from the requirements for mappings +that use the native system page size. +.PP +For +.BR mmap (), +.I offset +must be a multiple of the underlying huge page size. +The system automatically aligns +.I length +to be a multiple of the underlying huge page size. +.PP +For +.BR munmap (), +.I addr +and +.I length +must both be a multiple of the underlying huge page size. +.\" +.SS C library/kernel differences +This page describes the interface provided by the glibc +.BR mmap () +wrapper function. +Originally, this function invoked a system call of the same name. +Since kernel 2.4, that system call has been superseded by +.BR mmap2 (2), +and nowadays +.\" Since around glibc 2.1/2.2, depending on the platform. +the glibc +.BR mmap () +wrapper function invokes +.BR mmap2 (2) +with a suitably adjusted value for +.IR offset . +.SH BUGS +On Linux, there are no guarantees like those suggested above under +.BR MAP_NORESERVE . +By default, any process can be killed +at any moment when the system runs out of memory. +.PP +In kernels before 2.6.7, the +.B MAP_POPULATE +flag has effect only if +.I prot +is specified as +.BR PROT_NONE . +.PP +SUSv3 specifies that +.BR mmap () +should fail if +.I length +is 0. +However, in kernels before 2.6.12, +.BR mmap () +succeeded in this case: no mapping was created and the call returned +.IR addr . +Since kernel 2.6.12, +.BR mmap () +fails with the error +.B EINVAL +for this case. +.PP +POSIX specifies that the system shall always +zero fill any partial page at the end +of the object and that system will never write any modification of the +object beyond its end. +On Linux, when you write data to such partial page after the end +of the object, the data stays in the page cache even after the file +is closed and unmapped +and even though the data is never written to the file itself, +subsequent mappings may see the modified content. +In some cases, this could be fixed by calling +.BR msync (2) +before the unmap takes place; +however, this doesn't work on +.BR tmpfs (5) +(for example, when using the POSIX shared memory interface documented in +.BR shm_overview (7)). +.SH EXAMPLE +.\" FIXME . Add an example here that uses an anonymous shared region for +.\" IPC between parent and child. +.PP +The following program prints part of the file specified in +its first command-line argument to standard output. +The range of bytes to be printed is specified via offset and length +values in the second and third command-line arguments. +The program creates a memory mapping of the required +pages of the file and then uses +.BR write (2) +to output the desired bytes. +.SS Program source +.EX +#include +#include +#include +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +int +main(int argc, char *argv[]) +{ + char *addr; + int fd; + struct stat sb; + off_t offset, pa_offset; + size_t length; + ssize_t s; + + if (argc < 3 || argc > 4) { + fprintf(stderr, "%s file offset [length]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + fd = open(argv[1], O_RDONLY); + if (fd == \-1) + handle_error("open"); + + if (fstat(fd, &sb) == \-1) /* To obtain file size */ + handle_error("fstat"); + + offset = atoi(argv[2]); + pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) \- 1); + /* offset for mmap() must be page aligned */ + + if (offset >= sb.st_size) { + fprintf(stderr, "offset is past end of file\\n"); + exit(EXIT_FAILURE); + } + + if (argc == 4) { + length = atoi(argv[3]); + if (offset + length > sb.st_size) + length = sb.st_size \- offset; + /* Can\(aqt display bytes past end of file */ + + } else { /* No length arg ==> display to end of file */ + length = sb.st_size \- offset; + } + + addr = mmap(NULL, length + offset \- pa_offset, PROT_READ, + MAP_PRIVATE, fd, pa_offset); + if (addr == MAP_FAILED) + handle_error("mmap"); + + s = write(STDOUT_FILENO, addr + offset \- pa_offset, length); + if (s != length) { + if (s == \-1) + handle_error("write"); + + fprintf(stderr, "partial write"); + exit(EXIT_FAILURE); + } + + munmap(addr, length + offset \- pa_offset); + close(fd); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ftruncate (2), +.BR getpagesize (2), +.BR memfd_create (2), +.BR mincore (2), +.BR mlock (2), +.BR mmap2 (2), +.BR mprotect (2), +.BR mremap (2), +.BR msync (2), +.BR remap_file_pages (2), +.BR setrlimit (2), +.BR shmat (2), +.BR userfaultfd (2), +.BR shm_open (3), +.BR shm_overview (7) +.PP +The descriptions of the following files in +.BR proc (5): +.IR /proc/[pid]/maps , +.IR /proc/[pid]/map_files , +and +.IR /proc/[pid]/smaps . +.PP +B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391. +.\" +.\" Repeat after me: private read-only mappings are 100% equivalent to +.\" shared read-only mappings. No ifs, buts, or maybes. -- Linus +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mmap2.2 b/man2/mmap2.2 new file mode 100644 index 0000000..fa45c71 --- /dev/null +++ b/man2/mmap2.2 @@ -0,0 +1,109 @@ +.\" Copyright (C) 2002, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 31 Jan 2002, Michael Kerrisk +.\" Added description of mmap2 +.\" Modified, 2004-11-25, mtk -- removed stray #endif in prototype +.\" +.TH MMAP2 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mmap2 \- map files or devices into memory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *mmap2(void *" addr ", size_t " length ", int " prot , +.BI " int " flags ", int " fd ", off_t " pgoffset ); +.fi +.SH DESCRIPTION +This is probably not the system call that you are interested in; instead, see +.BR mmap (2), +which describes the glibc wrapper function that invokes this system call. +.PP +The +.BR mmap2 () +system call provides the same interface as +.BR mmap (2), +except that the final argument specifies the offset into the +file in 4096-byte units (instead of bytes, as is done by +.BR mmap (2)). +This enables applications that use a 32-bit +.I off_t +to map large files (up to 2^44 bytes). +.SH RETURN VALUE +On success, +.BR mmap2 () +returns a pointer to the mapped area. +On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Problem with getting the data from user space. +.TP +.B EINVAL +(Various platforms where the page size is not 4096 bytes.) +.I "offset\ *\ 4096" +is not a multiple of the system page size. +.PP +.BR mmap2 () +can also return any of the errors described in +.BR mmap (2). +.SH VERSIONS +.BR mmap2 () +is available since Linux 2.3.31. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +On architectures where this system call is present, +the glibc +.BR mmap () +wrapper function invokes this system call rather than the +.BR mmap (2) +system call. +.PP +This system call does not exist on x86-64. +.PP +On ia64, the unit for +.I offset +is actually the system page size, rather than 4096 bytes. +.\" ia64 can have page sizes ranging from 4 kB to 64 kB. +.\" On cris, it looks like the unit might also be the page size, +.\" which is 8192 bytes. -- mtk, June 2007 +.SH SEE ALSO +.BR getpagesize (2), +.BR mmap (2), +.BR mremap (2), +.BR msync (2), +.BR shm_open (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/modify_ldt.2 b/man2/modify_ldt.2 new file mode 100644 index 0000000..9b2f8f1 --- /dev/null +++ b/man2/modify_ldt.2 @@ -0,0 +1,219 @@ +.\" Copyright (c) 1995 Michael Chastain (mec@duracef.shout.net), 22 July 1995. +.\" Copyright (c) 2015 Andrew Lutomirski +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH MODIFY_LDT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +modify_ldt \- get or set a per-process LDT entry +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int modify_ldt(int " func ", void *" ptr ", unsigned long " bytecount ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.BR modify_ldt () +reads or writes the local descriptor table (LDT) for a process. +The LDT +is an array of segment descriptors that can be referenced by user code. +Linux allows processes to configure a per-process (actually per-mm) LDT. +For more information about the LDT, see the Intel Software Developer's +Manual or the AMD Architecture Programming Manual. +.PP +When +.I func +is 0, +.BR modify_ldt () +reads the LDT into the memory pointed to by +.IR ptr . +The number of bytes read is the smaller of +.I bytecount +and the actual size of the LDT, although the kernel may act as though +the LDT is padded with additional trailing zero bytes. +On success, +.BR modify_ldt () +will return the number of bytes read. +.PP +When +.I func +is 1 or 0x11, +.BR modify_ldt () +modifies the LDT entry indicated by +.IR ptr\->entry_number . +.I ptr +points to a +.I user_desc +structure +and +.I bytecount +must equal the size of this structure. +.PP +The +.I user_desc +structure is defined in \fI\fP as: +.PP +.in +4n +.EX +struct user_desc { + unsigned int entry_number; + unsigned long base_addr; + unsigned int limit; + unsigned int seg_32bit:1; + unsigned int contents:2; + unsigned int read_exec_only:1; + unsigned int limit_in_pages:1; + unsigned int seg_not_present:1; + unsigned int useable:1; +}; +.EE +.in +.PP +In Linux 2.4 and earlier, this structure was named +.IR modify_ldt_ldt_s . +.PP +The +.I contents +field is the segment type (data, expand-down data, non-conforming code, or +conforming code). +The other fields match their descriptions in the CPU manual, although +.BR modify_ldt () +cannot set the hardware-defined "accessed" bit described in the CPU manual. +.PP +A +.I user_desc +is considered "empty" if +.I read_exec_only +and +.I seg_not_present +are set to 1 and all of the other fields are 0. +An LDT entry can be cleared by setting it to an "empty" +.I user_desc +or, if +.I func +is 1, by setting both +.I base +and +.I limit +to 0. +.PP +A conforming code segment (i.e., one with +.IR contents==3 ) +will be rejected if +.I +func +is 1 or if +.I seg_not_present +is 0. +.PP +When +.I func +is 2, +.BR modify_ldt () +will read zeros. +This appears to be a leftover from Linux 2.4. +.SH RETURN VALUE +On success, +.BR modify_ldt () +returns either the actual number of bytes read (for reading) +or 0 (for writing). +On failure, +.BR modify_ldt () +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I ptr +points outside the address space. +.TP +.B EINVAL +.I ptr +is 0, +or +.I func +is 1 and +.I bytecount +is not equal to the size of the structure +.IR user_desc , +or +.I func +is 1 or 0x11 and the new LDT entry has invalid values. +.TP +.B ENOSYS +.I func +is neither 0, 1, 2, nor 0x11. +.SH CONFORMING TO +This call is Linux-specific and should not be used in programs intended +to be portable. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.PP +.BR modify_ldt () +should not be used for thread-local storage, as it slows down context +switches and only supports a limited number of threads. +Threading libraries should use +.BR set_thread_area (2) +or +.BR arch_prctl (2) +instead, except on extremely old kernels that do not support those system +calls. +.PP +The normal use for +.BR modify_ldt () +is to run legacy 16-bit or segmented 32-bit code. +Not all kernels allow 16-bit segments to be installed, however. +.PP +Even on 64-bit kernels, +.BR modify_ldt () +cannot be used to create a long mode (i.e., 64-bit) code segment. +The undocumented field "lm" in +.IR user_desc +is not useful, and, despite its name, +does not result in a long mode segment. +.SH BUGS +On 64-bit kernels before Linux 3.19, +.\" commit e30ab185c490e9a9381385529e0fd32f0a399495 +setting the "lm" bit in +.IR user_desc +prevents the descriptor from being considered empty. +Keep in mind that the +"lm" bit does not exist in the 32-bit headers, but these buggy kernels +will still notice the bit even when set in a 32-bit process. +.SH SEE ALSO +.BR arch_prctl (2), +.BR set_thread_area (2), +.BR vm86 (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mount.2 b/man2/mount.2 new file mode 100644 index 0000000..27105db --- /dev/null +++ b/man2/mount.2 @@ -0,0 +1,822 @@ +.\" Copyright (C) 1993 Rickard E. Faith +.\" and Copyright (C) 1994 Andries E. Brouwer +.\" and Copyright (C) 2002, 2005, 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1996-11-04 by Eric S. Raymond +.\" Modified 2001-10-13 by Michael Kerrisk +.\" Added note on historical behavior of MS_NOSUID +.\" Modified 2002-05-16 by Michael Kerrisk +.\" Extensive changes and additions +.\" Modified 2002-05-27 by aeb +.\" Modified 2002-06-11 by Michael Kerrisk +.\" Enhanced descriptions of MS_MOVE, MS_BIND, and MS_REMOUNT +.\" Modified 2004-06-17 by Michael Kerrisk +.\" 2005-05-18, mtk, Added MNT_EXPIRE, plus a few other tidy-ups. +.\" 2008-10-06, mtk: move umount*() material into separate umount.2 page. +.\" 2008-10-06, mtk: Add discussion of namespaces. +.\" +.TH MOUNT 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +mount \- mount filesystem +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "int mount(const char *" source ", const char *" target , +.BI " const char *" filesystemtype ", unsigned long " mountflags , +.BI " const void *" data ); +.fi +.SH DESCRIPTION +.BR mount () +attaches the filesystem specified by +.I source +(which is often a pathname referring to a device, +but can also be the pathname of a directory or file, +or a dummy string) to the location (a directory or file) +specified by the pathname in +.IR target . +.PP +Appropriate privilege (Linux: the +.B CAP_SYS_ADMIN +capability) is required to mount filesystems. +.PP +Values for the +.I filesystemtype +argument supported by the kernel are listed in +.I /proc/filesystems +(e.g., "btrfs", "ext4", "jfs", "xfs", "vfat", "fuse", +"tmpfs", "cgroup", "proc", "mqueue", "nfs", "cifs", "iso9660"). +Further types may become available when the appropriate modules +are loaded. +.PP +The +.I data +argument is interpreted by the different filesystems. +Typically it is a string of comma-separated options +understood by this filesystem. +See +.BR mount (8) +for details of the options available for each filesystem type. +.PP +A call to +.BR mount () +performs one of a number of general types of operation, +depending on the bits specified in +.IR mountflags . +The choice of which operation to perform is determined by +testing the bits set in +.IR mountflags , +with the tests being conducted in the order listed here: +.IP * 3 +Remount an existing mount: +.IR mountflags +includes +.BR MS_REMOUNT . +.IP * +Create a bind mount: +.IR mountflags +includes +.BR MS_BIND . +.IP * +Change the propagation type of an existing mount: +.IR mountflags +includes one of +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.BR MS_UNBINDABLE . +.IP * +Move an existing mount to a new location: +.IR mountflags +includes +.BR MS_MOVE . +.IP * +Create a new mount: +.IR mountflags +includes none of the above flags. +.PP +Each of these operations is detailed later in this page. +Further flags may be specified in +.IR mountflags +to modify the behavior of +.BR mount (), +as described below. +.\" +.SS Additional mount flags +The list below describes the additional flags that can be specified in +.IR mountflags . +Note that some operation types ignore some or all of these flags, +as described later in this page. +.\" +.\" FIXME 2.6.25 Added MS_I_VERSION, which needs to be documented. +.\" +.TP +.BR MS_DIRSYNC " (since Linux 2.5.19)" +Make directory changes on this filesystem synchronous. +(This property can be obtained for individual directories +or subtrees using +.BR chattr (1).) +.TP +.BR MS_LAZYTIME " (since Linux 4.0)" +.\" commit 0ae45f63d4ef8d8eeec49c7d8b44a1775fff13e8 +.\" commit fe032c422c5ba562ba9c2d316f55e258e03259c6 +.\" commit a26f49926da938f47561f386be56a83dd37a496d +Reduce on-disk updates of inode timestamps (atime, mtime, ctime) +by maintaining these changes only in memory. +The on-disk timestamps are updated only when: +.RS +.IP (a) 5 +the inode needs to be updated for some change unrelated to file timestamps; +.IP (b) +the application employs +.BR fsync (2), +.BR syncfs (2), +or +.BR sync (2); +.IP (c) +an undeleted inode is evicted from memory; or +.IP (d) +more than 24 hours have passed since the inode was written to disk. +.RE +.IP +This mount option significantly reduces writes +needed to update the inode's timestamps, especially mtime and atime. +However, in the event of a system crash, the atime and mtime fields +on disk might be out of date by up to 24 hours. +.PP +Examples of workloads where this option could be of significant benefit +include frequent random writes to preallocated files, +as well as cases where the +.B MS_STRICTATIME +mount option is also enabled. +(The advantage of combining +.BR MS_STRICTATIME +and +.BR MS_LAZYTIME +is that +.BR stat (2) +will return the correctly updated atime, but the atime updates +will be flushed to disk only in the cases listed above.) +.TP +.B MS_MANDLOCK +Permit mandatory locking on files in this filesystem. +(Mandatory locking must still be enabled on a per-file basis, +as described in +.BR fcntl (2).) +Since Linux 4.5, +.\" commit 95ace75414f312f9a7b93d873f386987b92a5301 +this mount option requires the +.B CAP_SYS_ADMIN +capability. +.TP +.B MS_NOATIME +Do not update access times for (all types of) files on this filesystem. +.TP +.B MS_NODEV +Do not allow access to devices (special files) on this filesystem. +.TP +.B MS_NODIRATIME +Do not update access times for directories on this filesystem. +This flag provides a subset of the functionality provided by +.BR MS_NOATIME ; +that is, +.BR MS_NOATIME +implies +.BR MS_NODIRATIME . +.TP +.B MS_NOEXEC +Do not allow programs to be executed from this filesystem. +.\" (Possibly useful for a filesystem that contains non-Linux executables. +.\" Often used as a security feature, e.g., to make sure that restricted +.\" users cannot execute files uploaded using ftp or so.) +.TP +.B MS_NOSUID +Do not honor set-user-ID and set-group-ID bits or file capabilities +when executing programs from this filesystem. +.\" (This is a security feature to prevent users executing set-user-ID and +.\" set-group-ID programs from removable disk devices.) +.TP +.B MS_RDONLY +Mount filesystem read-only. +.TP +.BR MS_REC " (since Linux 2.4.11)" +Used in conjunction with +.BR MS_BIND +to create a recursive bind mount, +and in conjunction with the propagation type flags to recursively change +the propagation type of all of the mounts in a subtree. +See below for further details. +.TP +.BR MS_RELATIME " (since Linux 2.6.20)" +When a file on this filesystem is accessed, +update the file's last access time (atime) only if the current value +of atime is less than or equal to the file's last modification time (mtime) +or last status change time (ctime). +This option is useful for programs, such as +.BR mutt (1), +that need to know when a file has been read since it was last modified. +Since Linux 2.6.30, the kernel defaults to the behavior provided +by this flag (unless +.BR MS_NOATIME +was specified), and the +.B MS_STRICTATIME +flag is required to obtain traditional semantics. +In addition, since Linux 2.6.30, +the file's last access time is always updated if it +is more than 1 day old. +.\" Matthew Garrett notes in the patch that added this behavior +.\" that this lets utilities such as tmpreaper (which deletes +.\" files based on last access time) work correctly. +.TP +.BR MS_SILENT " (since Linux 2.6.17)" +Suppress the display of certain +.RI ( printk ()) +warning messages in the kernel log. +This flag supersedes the misnamed and obsolete +.BR MS_VERBOSE +flag (available since Linux 2.4.12), which has the same meaning. +.TP +.BR MS_STRICTATIME " (since Linux 2.6.30)" +Always update the last access time (atime) when files on this +filesystem are accessed. +(This was the default behavior before Linux 2.6.30.) +Specifying this flag overrides the effect of setting the +.BR MS_NOATIME +and +.BR MS_RELATIME +flags. +.TP +.B MS_SYNCHRONOUS +Make writes on this filesystem synchronous (as though +the +.B O_SYNC +flag to +.BR open (2) +was specified for all file opens to this filesystem). +.PP +From Linux 2.4 onward, the +.BR MS_NODEV ", " MS_NOEXEC ", and " MS_NOSUID +flags are settable on a per-mount-point basis. +From kernel 2.6.16 onward, +.B MS_NOATIME +and +.B MS_NODIRATIME +are also settable on a per-mount-point basis. +The +.B MS_RELATIME +flag is also settable on a per-mount-point basis. +Since Linux 2.6.16, +.B MS_RDONLY +can be set or cleared on a per-mount-point basis as well as on +the underlying filesystem. +The mounted filesystem will be writable only if neither the filesystem +nor the mountpoint are flagged as read-only. +.\" +.SS Remounting an existing mount +An existing mount may be remounted by specifying +.B MS_REMOUNT +in +.IR mountflags . +This allows you to change the +.I mountflags +and +.I data +of an existing mount without having to unmount and remount the filesystem. +.I target +should be the same value specified in the initial +.BR mount () +call. +.PP +The +.I source +and +.I filesystemtype +arguments are ignored. +.PP +The +.I mountflags +and +.I data +arguments should match the values used in the original +.BR mount () +call, except for those parameters that are being deliberately changed. +Another exception is that +.B MS_BIND +has a different meaning for remount, and it should be included only if +explicitly desired. +.PP +The following +.I mountflags +can be changed: +.BR MS_LAZYTIME , +.BR MS_MANDLOCK , +.BR MS_NOATIME , +.BR MS_NODEV , +.BR MS_NODIRATIME , +.BR MS_NOEXEC , +.BR MS_NOSUID , +.BR MS_RELATIME , +.BR MS_RDONLY , +and +.BR MS_SYNCHRONOUS . +Attempts to change the setting of the +.\" See the definition of MS_RMT_MASK in include/uapi/linux/fs.h +.BR MS_DIRSYNC +flag during a remount are silently ignored. +.PP +Since Linux 3.17, +.\" commit ffbc6f0ead47fa5a1dc9642b0331cb75c20a640e +if none of +.BR MS_NOATIME , +.BR MS_NODIRATIME , +.BR MS_RELATIME , +or +.BR MS_STRICTATIME +is specified in +.IR mountflags , +then the remount operation preserves the existing values of these flags +(rather than defaulting to +.BR MS_RELATIME ). +.PP +Since Linux 2.6.26, this flag can be used with +.B MS_BIND +to modify only the per-mount-point flags. +.\" See https://lwn.net/Articles/281157/ +This is particularly useful for setting or clearing the "read-only" +flag on a mount point without changing the underlying filesystem. +Specifying +.IR mountflags +as: +.PP + MS_REMOUNT | MS_BIND | MS_RDONLY +.PP +will make access through this mountpoint read-only, without affecting +other mount points. +.\" +.SS Creating a bind mount +If +.I mountflags +includes +.BR MS_BIND +(available since Linux 2.4), +.\" since 2.4.0-test9 +then perform a bind mount. +A bind mount makes a file or a directory subtree visible at +another point within the single directory hierarchy. +Bind mounts may cross filesystem boundaries and span +.BR chroot (2) +jails. +.PP +The +.IR filesystemtype +and +.IR data +arguments are ignored. +.PP +The remaining bits in the +.I mountflags +argument are also ignored, with the exception of +.BR MS_REC . +(The bind mount has the same mount options as +the underlying mount point.) +However, see the discussion of remounting above, +for a method of making an existing bind mount read-only. +.PP +By default, when a directory is bind mounted, +only that directory is mounted; +if there are any submounts under the directory tree, +they are not bind mounted. +If the +.BR MS_REC +flag is also specified, then a recursive bind mount operation is performed: +all submounts under the +.I source +subtree (other than unbindable mounts) +are also bind mounted at the corresponding location in the +.I target +subtree. +.\" +.SS Changing the propagation type of an existing mount +If +.IR mountflags +includes one of +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.BR MS_UNBINDABLE +(all available since Linux 2.6.15), +then the propagation type of an existing mount is changed. +If more than one of these flags is specified, an error results. +.PP +The only flags that can be used with changing the propagation type are +.BR MS_REC +and +.BR MS_SILENT . +.PP +The +.IR source , +.IR filesystemtype , +and +.IR data +arguments are ignored. +.PP +The meanings of the propagation type flags are as follows: +.TP +.BR MS_SHARED +Make this mount point shared. +Mount and unmount events immediately under this mount point will propagate +to the other mount points that are members of this mount's peer group. +Propagation here means that the same mount or unmount will automatically +occur under all of the other mount points in the peer group. +Conversely, mount and unmount events that take place under +peer mount points will propagate to this mount point. +.TP +.BR MS_PRIVATE +Make this mount point private. +Mount and unmount events do not propagate into or out of this mount point. +.TP +.BR MS_SLAVE +If this is a shared mount point that is a member of a peer group +that contains other members, convert it to a slave mount. +If this is a shared mount point that is a member of a peer group +that contains no other members, convert it to a private mount. +Otherwise, the propagation type of the mount point is left unchanged. +.PP +When a mount point is a slave, +mount and unmount events propagate into this mount point from +the (master) shared peer group of which it was formerly a member. +Mount and unmount events under this mount point do not propagate to any peer. +.PP +A mount point can be the slave of another peer group +while at the same time sharing mount and unmount events +with a peer group of which it is a member. +.TP +.BR MS_UNBINDABLE +Make this mount unbindable. +This is like a private mount, +and in addition this mount can't be bind mounted. +When a recursive bind mount +.RB ( mount () +with the +.BR MS_BIND +and +.BR MS_REC +flags) is performed on a directory subtree, +any bind mounts within the subtree are automatically pruned +(i.e., not replicated) +when replicating that subtree to produce the target subtree. +.PP +By default, changing the propagation type affects only the +.I target +mount point. +If the +.B MS_REC +flag is also specified in +.IR mountflags , +then the propagation type of all mount points under +.IR target +is also changed. +.PP +For further details regarding mount propagation types +(including the default propagation type assigned to new mounts), see +.BR mount_namespaces (7). +.\" +.SS Moving a mount +If +.I mountflags +contains the flag +.BR MS_MOVE +(available since Linux 2.4.18), +then move a subtree: +.I source +specifies an existing mount point and +.I target +specifies the new location to which that mount point is to be relocated. +The move is atomic: at no point is the subtree unmounted. +.PP +The remaining bits in the +.IR mountflags +argument are ignored, as are the +.IR filesystemtype +and +.IR data +arguments. +.\" +.SS Creating a new mount point +If none of +.BR MS_REMOUNT , +.BR MS_BIND , +.BR MS_MOVE , +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.BR MS_UNBINDABLE +is specified in +.IR mountflags , +then +.BR mount () +performs its default action: creating a new mount point. +.IR source +specifies the source for the new mount point, and +.IR target +specifies the directory at which to create the mount point. +.PP +The +.I filesystemtype +and +.I data +arguments are employed, and further bits may be specified in +.IR mountflags +to modify the behavior of the call. +.\" +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +The error values given below result from filesystem type independent +errors. +Each filesystem type may have its own special errors and its +own special behavior. +See the Linux kernel source code for details. +.TP +.B EACCES +A component of a path was not searchable. +(See also +.BR path_resolution (7).) +.TP +.B EACCES +Mounting a read-only filesystem was attempted without giving the +.B MS_RDONLY +flag. +.TP +.B EACCES +The block device +.I source +is located on a filesystem mounted with the +.B MS_NODEV +option. +.\" mtk: Probably: write permission is required for MS_BIND, with +.\" the error EPERM if not present; CAP_DAC_OVERRIDE is required. +.TP +.B EBUSY +.I source +is already mounted. +.TP +.B EBUSY +.I source +cannot be remounted read-only, +because it still holds files open for writing. +.TP +.B EBUSY +.I source +cannot be mounted on +.I target +because +.I target +is still busy (it is the working directory of some thread, +the mount point of another device, has open files, etc.). +.TP +.B EFAULT +One of the pointer arguments points outside the user address space. +.TP +.B EINVAL +.I source +had an invalid superblock. +.TP +.B EINVAL +A remount operation +.RB ( MS_REMOUNT ) +was attempted, but +.I source +was not already mounted on +.IR target . +.TP +.B EINVAL +A move operation +.RB ( MS_MOVE ) +was attempted, but +.I source +was not a mount point, or was \(aq/\(aq. +.TP +.B EINVAL +.I mountflags +includes more than one of +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.BR MS_UNBINDABLE . +.TP +.B EINVAL +.I mountflags +includes +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.BR MS_UNBINDABLE +and also includes a flag other than +.BR MS_REC +or +.BR MS_SILENT . +.TP +.BR EINVAL +An attempt was made to bind mount an unbindable mount. +.TP +.BR EINVAL +In an unprivileged mount namespace +(i.e., a mount namespace owned by a user namespace +that was created by an unprivileged user), +a bind mount operation +.RB ( MS_BIND ) +was attempted without specifying +.RB ( MS_REC ), +which would have revealed the filesystem tree underneath one of +the submounts of the directory being bound. +.TP +.B ELOOP +Too many links encountered during pathname resolution. +.TP +.B ELOOP +A move operation was attempted, and +.I target +is a descendant of +.IR source . +.TP +.B EMFILE +(In case no block device is required:) +Table of dummy devices is full. +.TP +.B ENAMETOOLONG +A pathname was longer than +.BR MAXPATHLEN . +.TP +.B ENODEV +.I filesystemtype +not configured in the kernel. +.TP +.B ENOENT +A pathname was empty or had a nonexistent component. +.TP +.B ENOMEM +The kernel could not allocate a free page to copy filenames or data into. +.TP +.B ENOTBLK +.I source +is not a block device (and a device was required). +.TP +.B ENOTDIR +.IR target , +or a prefix of +.IR source , +is not a directory. +.TP +.B ENXIO +The major number of the block device +.I source +is out of range. +.TP +.B EPERM +The caller does not have the required privileges. +.SH VERSIONS +The definitions of +.BR MS_DIRSYNC , +.BR MS_MOVE , +.BR MS_PRIVATE , +.BR MS_REC , +.BR MS_RELATIME , +.BR MS_SHARED , +.BR MS_SLAVE , +.BR MS_STRICTATIME +and +.BR MS_UNBINDABLE +were added to glibc headers in version 2.12. +.\" +.SH CONFORMING TO +This function is Linux-specific and should not be used in +programs intended to be portable. +.SH NOTES +Since Linux 2.4 a single filesystem can be mounted at +multiple mount points, and multiple mounts can be stacked +on the same mount point. +.\" Multiple mounts on same mount point: since 2.3.99pre7. +.PP +The +.I mountflags +argument may have the magic number 0xC0ED (\fBMS_MGC_VAL\fP) +in the top 16 bits. +(All of the other flags discussed in DESCRIPTION +occupy the low order 16 bits of +.IR mountflags .) +Specifying +.BR MS_MGC_VAL +was required in kernel versions prior to 2.4, +but since Linux 2.4 is no longer required and is ignored if specified. +.PP +The original +.B MS_SYNC +flag was renamed +.B MS_SYNCHRONOUS +in 1.1.69 +when a different +.B MS_SYNC +was added to \fI\fP. +.PP +Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID program +on a filesystem mounted with +.B MS_NOSUID +would fail with +.BR EPERM . +Since Linux 2.4 the set-user-ID and set-group-ID bits are +just silently ignored in this case. +.\" The change is in patch-2.4.0-prerelease. +.\" +.SS Per-process namespaces +Starting with kernel 2.4.19, Linux provides +per-process mount namespaces. +A mount namespace is the set of filesystem mounts that +are visible to a process. +Mount-point namespaces can be (and usually are) +shared between multiple processes, +and changes to the namespace (i.e., mounts and unmounts) by one process +are visible to all other processes sharing the same namespace. +(The pre-2.4.19 Linux situation can be considered as one in which +a single namespace was shared by every process on the system.) +.PP +A child process created by +.BR fork (2) +shares its parent's mount namespace; +the mount namespace is preserved across an +.BR execve (2). +.PP +A process can obtain a private mount namespace if: +it was created using the +.BR clone (2) +.BR CLONE_NEWNS +flag, +in which case its new namespace is initialized to be a +.I copy +of the namespace of the process that called +.BR clone (2); +or it calls +.BR unshare (2) +with the +.BR CLONE_NEWNS +flag, +which causes the caller's mount namespace to obtain a private copy +of the namespace that it was previously sharing with other processes, +so that future mounts and unmounts by the caller are invisible +to other processes (except child processes that the caller +subsequently creates) and vice versa. +.PP +The Linux-specific +.I /proc/[pid]/mounts +file exposes the list of mount points in the mount +namespace of the process with the specified ID; see +.BR proc (5) +for details. +.SH SEE ALSO +.BR mountpoint (1), +.BR umount (2), +.BR mount_namespaces (7), +.BR path_resolution (7), +.BR findmnt (8), +.BR lsblk (8), +.BR mount (8), +.BR umount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/move_pages.2 b/man2/move_pages.2 new file mode 100644 index 0000000..655a5d3 --- /dev/null +++ b/man2/move_pages.2 @@ -0,0 +1,261 @@ +.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc. +.\" Christoph Lameter +.\" +.\" %%%LICENSE_START(VERBATIM_TWO_PARA) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" %%%LICENSE_END +.\" +.\" FIXME Should programs normally be using move_pages() directly, or should +.\" they rather be using interfaces in the numactl package? +.\" (e.g., compare with recommendation in mbind(2)). +.\" Does this page need to give advice on this topic? +.\" +.TH MOVE_PAGES 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +move_pages \- move individual pages of a process to another node +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long move_pages(int " pid ", unsigned long count, void **" pages , +.BI " const int *" nodes ", int *" status ", int " flags ); +.fi +.PP +Link with \fI\-lnuma\fP. +.SH DESCRIPTION +.BR move_pages () +moves the specified +.I pages +of the process +.I pid +to the memory nodes specified by +.IR nodes . +The result of the move is reflected in +.IR status . +The +.I flags +indicate constraints on the pages to be moved. +.PP +.I pid +is the ID of the process in which pages are to be moved. +If +.I pid +is 0, then +.BR move_pages () +moves pages of the calling process. +.PP +To move pages in another process requires the following privileges: +.IP * 3 +In kernels up to and including Linux 4.12: +the caller must be privileged +.RB ( CAP_SYS_NICE ) +or the real or effective user ID of the calling process must match the +real or saved-set user ID of the target process. +.IP * +The older rules allowed the caller to discover various +virtual address choices made by the kernel that could lead +to the defeat of address-space-layout randomization +for a process owned by the same UID as the caller, +the rules were changed starting with Linux 4.13. +Since Linux 4.13, +.\" commit 197e7e521384a23b9e585178f3f11c9fa08274b9 +permission is governed by a ptrace access mode +.B PTRACE_MODE_READ_REALCREDS +check with respect to the target process; see +.BR ptrace (2). +.PP +.I count +is the number of pages to move. +It defines the size of the three arrays +.IR pages , +.IR nodes , +and +.IR status . +.PP +.I pages +is an array of pointers to the pages that should be moved. +These are pointers that should be aligned to page boundaries. +.\" FIXME Describe the result if pointers in the 'pages' array are +.\" not aligned to page boundaries +Addresses are specified as seen by the process specified by +.IR pid . +.PP +.I nodes +is an array of integers that specify the desired location for each page. +Each element in the array is a node number. +.I nodes +can also be NULL, in which case +.BR move_pages () +does not move any pages but instead will return the node +where each page currently resides, in the +.I status +array. +Obtaining the status of each page may be necessary to determine +pages that need to be moved. +.PP +.I status +is an array of integers that return the status of each page. +The array contains valid values only if +.BR move_pages () +did not return an error. +.PP +.I flags +specify what types of pages to move. +.B MPOL_MF_MOVE +means that only pages that are in exclusive use by the process +are to be moved. +.B MPOL_MF_MOVE_ALL +means that pages shared between multiple processes can also be moved. +The process must be privileged +.RB ( CAP_SYS_NICE ) +to use +.BR MPOL_MF_MOVE_ALL . +.SS Page states in the status array +The following values can be returned in each element of the +.I status +array. +.TP +.B 0..MAX_NUMNODES +Identifies the node on which the page resides. +.TP +.B -EACCES +The page is mapped by multiple processes and can be moved only if +.B MPOL_MF_MOVE_ALL +is specified. +.TP +.B -EBUSY +The page is currently busy and cannot be moved. +Try again later. +This occurs if a page is undergoing I/O or another kernel subsystem +is holding a reference to the page. +.TP +.B -EFAULT +This is a zero page or the memory area is not mapped by the process. +.TP +.B -EIO +Unable to write back a page. +The page has to be written back +in order to move it since the page is dirty and the filesystem +does not provide a migration function that would allow the move +of dirty pages. +.TP +.B -EINVAL +A dirty page cannot be moved. +The filesystem does not +provide a migration function and has no ability to write back pages. +.TP +.B -ENOENT +The page is not present. +.TP +.B -ENOMEM +Unable to allocate memory on target node. +.SH RETURN VALUE +On success +.BR move_pages () +returns zero. +.\" FIXME . Is the following quite true: does the wrapper in numactl +.\" do the right thing? +On error, it returns \-1, and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B E2BIG +Too many pages to move. +.TP +.B EACCES +.\" FIXME Clarify "current cpuset" in the description of the EACCESS error. +.\" Is that the cpuset of the caller or the target? +One of the target nodes is not allowed by the current cpuset. +.TP +.B EFAULT +Parameter array could not be accessed. +.TP +.B EINVAL +Flags other than +.B MPOL_MF_MOVE +and +.B MPOL_MF_MOVE_ALL +was specified or an attempt was made to migrate pages of a kernel thread. +.TP +.B ENODEV +One of the target nodes is not online. +.TP +.B ENOENT +No pages were found that require moving. +All pages are either already +on the target node, not present, had an invalid address or could not be +moved because they were mapped by multiple processes. +.TP +.B EPERM +The caller specified +.B MPOL_MF_MOVE_ALL +without sufficient privileges +.RB ( CAP_SYS_NICE ). +Or, the caller attempted to move pages of a process belonging +to another user but did not have privilege to do so +.RB ( CAP_SYS_NICE ). +.TP +.B ESRCH +Process does not exist. +.SH VERSIONS +.BR move_pages () +first appeared on Linux in version 2.6.18. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +For information on library support, see +.BR numa (7). +.PP +Use +.BR get_mempolicy (2) +with the +.B MPOL_F_MEMS_ALLOWED +flag to obtain the set of nodes that are allowed by +.\" FIXME Clarify "current cpuset". Is that the cpuset of the caller +.\" or the target? +the current cpuset. +Note that this information is subject to change at any +time by manual or automatic reconfiguration of the cpuset. +.PP +Use of this function may result in pages whose location +(node) violates the memory policy established for the +specified addresses (See +.BR mbind (2)) +and/or the specified process (See +.BR set_mempolicy (2)). +That is, memory policy does not constrain the destination +nodes used by +.BR move_pages (). +.PP +The +.I +header is not included with glibc, but requires installing +.I libnuma-devel +or a similar package. +.SH SEE ALSO +.BR get_mempolicy (2), +.BR mbind (2), +.BR set_mempolicy (2), +.BR numa (3), +.BR numa_maps (5), +.BR cpuset (7), +.BR numa (7), +.BR migratepages (8), +.BR numastat (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mprotect.2 b/man2/mprotect.2 new file mode 100644 index 0000000..9c581b7 --- /dev/null +++ b/man2/mprotect.2 @@ -0,0 +1,380 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" and Copyright (C) 1995 Michael Shields . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and author of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1997-05-31 by Andries Brouwer +.\" Modified 2003-08-24 by Andries Brouwer +.\" Modified 2004-08-16 by Andi Kleen +.\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and +.\" a much improved example program. +.\" +.TH MPROTECT 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +mprotect, pkey_mprotect \- set protection on a region of memory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mprotect(void *" addr ", size_t " len ", int " prot ); +.BI "int pkey_mprotect(void *" addr ", size_t " len ", int " prot ", int " pkey "); +.fi +.SH DESCRIPTION +.BR mprotect () +changes the access protections for the calling process's memory pages +containing any part of the address range in the +interval [\fIaddr\fP,\ \fIaddr\fP+\fIlen\fP\-1]. +.I addr +must be aligned to a page boundary. +.PP +If the calling process tries to access memory in a manner +that violates the protections, then the kernel generates a +.B SIGSEGV +signal for the process. +.PP +.I prot +is a combination of the following access flags: +.B PROT_NONE +or a bitwise-or of the other values in the following list: +.TP 1.1i +.B PROT_NONE +The memory cannot be accessed at all. +.TP +.B PROT_READ +The memory can be read. +.TP +.B PROT_WRITE +The memory can be modified. +.TP +.B PROT_EXEC +The memory can be executed. +.TP +.BR PROT_SEM " (since Linux 2.5.7)" +The memory can be used for atomic operations. +This flag was introduced as part of the +.BR futex (2) +implementation (in order to guarantee the ability to perform atomic +operations required by commands such as +.BR FUTEX_WAIT ), +but is not currently used in on any architecture. +.TP +.BR PROT_SAO " (since Linux 2.6.26)" +.\" commit aba46c5027cb59d98052231b36efcbbde9c77a1d +.\" commit ef3d3246a0d06be622867d21af25f997aeeb105f +The memory should have strong access ordering. +This feature is specific to +the PowerPC architecture +(version 2.06 of the architecture specification adds the SAO CPU feature, +and it is available on POWER 7 or PowerPC A2, for example). +.PP +Additionally (since Linux 2.6.0), +.I prot +can have one of the following flags set: +.TP 1.1i +.\" mm/mmap.c: +.\" vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) | +.\" mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC; +.\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED. +.B PROT_GROWSUP +Apply the protection mode up to the end of a mapping +that grows upwards. +(Such mappings are created for the stack area on +architectures\(emfor example, HP-PARISC\(emthat +have an upwardly growing stack.) +.\" The VMA is one that was marked with VM_GROWSUP by the kernel +.\" when the stack was created. Note that (unlike VM_GROWSDOWN), +.\" there is no mmap() flag (analogous to MAP_GROWSDOWN) for +.\" creating a VMA that is marked VM_GROWSUP. +.TP +.B PROT_GROWSDOWN +Apply the protection mode down to the beginning of a mapping +that grows downward +(which should be a stack segment or a segment mapped with the +.B MAP_GROWSDOWN +flag set). +.PP +Like +.BR mprotect (), +.BR pkey_mprotect () +changes the protection on the pages specified by +.IR addr +and +.IR len . +The +.I pkey +argument specifies the protection key (see +.BR pkeys (7)) +to assign to the memory. +The protection key must be allocated with +.BR pkey_alloc (2) +before it is passed to +.BR pkey_mprotect (). +For an example of the use of this system call, see +.BR pkeys (7). +.SH RETURN VALUE +On success, +.BR mprotect () +and +.BR pkey_mprotect () +return zero. +On error, these system calls return \-1, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +The memory cannot be given the specified access. +This can happen, for example, if you +.BR mmap (2) +a file to which you have read-only access, then ask +.BR mprotect () +to mark it +.BR PROT_WRITE . +.TP +.B EINVAL +\fIaddr\fP is not a valid pointer, +or not a multiple of the system page size. +.TP +.BR EINVAL +.RB ( pkey_mprotect ()) +\fIpkey\fP has not been allocated with +.BR pkey_alloc (2) +.TP +.BR EINVAL +Both +.BR PROT_GROWSUP +and +.BR PROT_GROWSDOWN +were specified in +.IR prot . +.TP +.BR EINVAL +Invalid flags specified in +.IR prot . +.TP +.BR EINVAL +(PowerPC architecture) +.B PROT_SAO +was specified in +.IR prot , +but SAO hardware feature is not available. +.TP +.B ENOMEM +Internal kernel structures could not be allocated. +.TP +.B ENOMEM +Addresses in the range +.RI [ addr , +.IR addr + len \-1] +are invalid for the address space of the process, +or specify one or more pages that are not mapped. +(Before kernel 2.4.19, the error +.BR EFAULT +was incorrectly produced for these cases.) +.TP +.B ENOMEM +Changing the protection of a memory region would result in the total number of +mappings with distinct attributes (e.g., read versus read/write protection) +exceeding the allowed maximum. +.\" I.e., the number of VMAs would exceed the 64 kB maximum +(For example, making the protection of a range +.BR PROT_READ +in the middle of a region currently protected as +.BR PROT_READ|PROT_WRITE +would result in three mappings: +two read/write mappings at each end and a read-only mapping in the middle.) +.SH VERSIONS +.BR pkey_mprotect () +first appeared in Linux 4.9; +library support was added in glibc 2.27. +.SH CONFORMING TO +.BR mprotect (): +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVr4 defines an additional error +.\" code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's. +POSIX says that the behavior of +.BR mprotect () +is unspecified if it is applied to a region of memory that +was not obtained via +.BR mmap (2). +.PP +.BR pkey_mprotect () +is a nonportable Linux extension. +.SH NOTES +On Linux, it is always permissible to call +.BR mprotect () +on any address in a process's address space (except for the +kernel vsyscall area). +In particular, it can be used +to change existing code mappings to be writable. +.PP +Whether +.B PROT_EXEC +has any effect different from +.B PROT_READ +depends on processor architecture, kernel version, and process state. +If +.B READ_IMPLIES_EXEC +is set in the process's personality flags (see +.BR personality (2)), +specifying +.B PROT_READ +will implicitly add +.BR PROT_EXEC. +.PP +On some hardware architectures (e.g., i386), +.B PROT_WRITE +implies +.BR PROT_READ . +.PP +POSIX.1 says that an implementation may permit access +other than that specified in +.IR prot , +but at a minimum can allow write access only if +.B PROT_WRITE +has been set, and must not allow any access if +.B PROT_NONE +has been set. +.PP +Applications should be careful when mixing use of +.BR mprotect () +and +.BR pkey_mprotect (). +On x86, when +.BR mprotect () +is used with +.IR prot +set to +.B PROT_EXEC +a pkey is may be allocated and set on the memory implicitly +by the kernel, but only when the pkey was 0 previously. +.PP +On systems that do not support protection keys in hardware, +.BR pkey_mprotect () +may still be used, but +.IR pkey +must be set to 0. +When called this way, the operation of +.BR pkey_mprotect () +is equivalent to +.BR mprotect (). +.SH EXAMPLE +.\" sigaction.2 refers to this example +.PP +The program below demonstrates the use of +.BR mprotect (). +The program allocates four pages of memory, makes the third +of these pages read-only, and then executes a loop that walks upward +through the allocated region modifying bytes. +.PP +An example of what we might see when running the program is the +following: +.PP +.in +4n +.EX +.RB "$" " ./a.out" +Start of region: 0x804c000 +Got SIGSEGV at address: 0x804e000 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +static char *buffer; + +static void +handler(int sig, siginfo_t *si, void *unused) +{ + /* Note: calling printf() from a signal handler is not safe + (and should not be done in production programs), since + printf() is not async\-signal\-safe; see signal-safety(7). + Nevertheless, we use printf() here as a simple way of + showing that the handler was called. */ + + printf("Got SIGSEGV at address: 0x%lx\\n", + (long) si\->si_addr); + exit(EXIT_FAILURE); +} + +int +main(int argc, char *argv[]) +{ + char *p; + int pagesize; + struct sigaction sa; + + sa.sa_flags = SA_SIGINFO; + sigemptyset(&sa.sa_mask); + sa.sa_sigaction = handler; + if (sigaction(SIGSEGV, &sa, NULL) == \-1) + handle_error("sigaction"); + + pagesize = sysconf(_SC_PAGE_SIZE); + if (pagesize == \-1) + handle_error("sysconf"); + + /* Allocate a buffer aligned on a page boundary; + initial protection is PROT_READ | PROT_WRITE */ + + buffer = memalign(pagesize, 4 * pagesize); + if (buffer == NULL) + handle_error("memalign"); + + printf("Start of region: 0x%lx\\n", (long) buffer); + + if (mprotect(buffer + pagesize * 2, pagesize, + PROT_READ) == \-1) + handle_error("mprotect"); + + for (p = buffer ; ; ) + *(p++) = \(aqa\(aq; + + printf("Loop completed\\n"); /* Should never happen */ + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR mmap (2), +.BR sysconf (3), +.BR pkeys (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mpx.2 b/man2/mpx.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/mpx.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/mq_getsetattr.2 b/man2/mq_getsetattr.2 new file mode 100644 index 0000000..cadf285 --- /dev/null +++ b/man2/mq_getsetattr.2 @@ -0,0 +1,67 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_GETSETATTR 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_getsetattr \- get/set message queue attributes +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int mq_getsetattr(mqd_t " mqdes ", struct mq_attr *" newattr "," +.BI " struct mq_attr *" oldattr ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +Do not use this system call. +.PP +This is the low-level system call used to implement +.BR mq_getattr (3) +and +.BR mq_setattr (3). +For an explanation of how this system call operates, +see the description of +.BR mq_setattr (3). +.SH CONFORMING TO +This interface is nonstandard; avoid its use. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +(Actually, never call it unless you are writing a C library!) +.SH SEE ALSO +.BR mq_getattr (3), +.BR mq_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/mq_notify.2 b/man2/mq_notify.2 new file mode 100644 index 0000000..fda80ff --- /dev/null +++ b/man2/mq_notify.2 @@ -0,0 +1 @@ +.so man3/mq_notify.3 diff --git a/man2/mq_open.2 b/man2/mq_open.2 new file mode 100644 index 0000000..54b4766 --- /dev/null +++ b/man2/mq_open.2 @@ -0,0 +1 @@ +.so man3/mq_open.3 diff --git a/man2/mq_timedreceive.2 b/man2/mq_timedreceive.2 new file mode 100644 index 0000000..9fed5f2 --- /dev/null +++ b/man2/mq_timedreceive.2 @@ -0,0 +1 @@ +.so man3/mq_receive.3 diff --git a/man2/mq_timedsend.2 b/man2/mq_timedsend.2 new file mode 100644 index 0000000..28b1eff --- /dev/null +++ b/man2/mq_timedsend.2 @@ -0,0 +1 @@ +.so man3/mq_send.3 diff --git a/man2/mq_unlink.2 b/man2/mq_unlink.2 new file mode 100644 index 0000000..4e72f11 --- /dev/null +++ b/man2/mq_unlink.2 @@ -0,0 +1 @@ +.so man3/mq_unlink.3 diff --git a/man2/mremap.2 b/man2/mremap.2 new file mode 100644 index 0000000..daf221e --- /dev/null +++ b/man2/mremap.2 @@ -0,0 +1,285 @@ +.\" Copyright (c) 1996 Tom Bjorkholm +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1996-04-11 Tom Bjorkholm +.\" First version written (1.3.86) +.\" 1996-04-12 Tom Bjorkholm +.\" Update for Linux 1.3.87 and later +.\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text. +.\" +.TH MREMAP 2 2017-09-25 "Linux" "Linux Programmer's Manual" +.SH NAME +mremap \- remap a virtual memory address +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void *mremap(void *" old_address ", size_t " old_size , +.BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);" +.fi +.SH DESCRIPTION +.BR mremap () +expands (or shrinks) an existing memory mapping, potentially +moving it at the same time (controlled by the \fIflags\fP argument and +the available virtual address space). +.PP +\fIold_address\fP is the old address of the virtual memory block that you +want to expand (or shrink). +Note that \fIold_address\fP has to be page +aligned. +\fIold_size\fP is the old size of the +virtual memory block. +\fInew_size\fP is the requested size of the +virtual memory block after the resize. +An optional fifth argument, +.IR new_address , +may be provided; see the description of +.B MREMAP_FIXED +below. +.PP +If the value of \fIold_size\fP is zero, and \fIold_address\fP refers to +a shareable mapping (see +.BR mmap (2) +.BR MAP_SHARED ), +then +.BR mremap () +will create a new mapping of the same pages. +\fInew_size\fP +will be the size of the new mapping and the location of the new mapping +may be specified with \fInew_address\fP; see the description of +.B MREMAP_FIXED +below. +If a new mapping is requested via this method, then the +.B MREMAP_MAYMOVE +flag must also be specified. +.PP +In Linux the memory is divided into pages. +A user process has (one or) +several linear virtual memory segments. +Each virtual memory segment has one +or more mappings to real memory pages (in the page table). +Each virtual memory segment has its own +protection (access rights), which may cause +a segmentation violation if the memory is accessed incorrectly (e.g., +writing to a read-only segment). +Accessing virtual memory outside of the +segments will also cause a segmentation violation. +.PP +.BR mremap () +uses the Linux page table scheme. +.BR mremap () +changes the +mapping between virtual addresses and memory pages. +This can be used to implement a very efficient +.BR realloc (3). +.PP +The \fIflags\fP bit-mask argument may be 0, or include the following flag: +.TP +.B MREMAP_MAYMOVE +By default, if there is not sufficient space to expand a mapping +at its current location, then +.BR mremap () +fails. +If this flag is specified, then the kernel is permitted to +relocate the mapping to a new virtual address, if necessary. +If the mapping is relocated, +then absolute pointers into the old mapping location +become invalid (offsets relative to the starting address of +the mapping should be employed). +.TP +.BR MREMAP_FIXED " (since Linux 2.3.31)" +This flag serves a similar purpose to the +.B MAP_FIXED +flag of +.BR mmap (2). +If this flag is specified, then +.BR mremap () +accepts a fifth argument, +.IR "void\ *new_address" , +which specifies a page-aligned address to which the mapping must +be moved. +Any previous mapping at the address range specified by +.I new_address +and +.I new_size +is unmapped. +If +.B MREMAP_FIXED +is specified, then +.B MREMAP_MAYMOVE +must also be specified. +.PP +If the memory segment specified by +.I old_address +and +.I old_size +is locked (using +.BR mlock (2) +or similar), then this lock is maintained when the segment is +resized and/or relocated. +As a consequence, the amount of memory locked by the process may change. +.SH RETURN VALUE +On success +.BR mremap () +returns a pointer to the new virtual memory area. +On error, the value +.B MAP_FAILED +(that is, \fI(void\ *)\ \-1\fP) is returned, +and \fIerrno\fP is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +The caller tried to expand a memory segment that is locked, +but this was not possible without exceeding the +.B RLIMIT_MEMLOCK +resource limit. +.TP +.B EFAULT +"Segmentation fault." Some address in the range +\fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid +virtual memory address for this process. +You can also get +.B EFAULT +even if there exist mappings that cover the +whole address space requested, but those mappings are of different types. +.TP +.B EINVAL +An invalid argument was given. +Possible causes are: +.RS +.IP * 3 +\fIold_address\fP was not +page aligned; +.IP * +a value other than +.B MREMAP_MAYMOVE +or +.B MREMAP_FIXED +was specified in +.IR flags ; +.IP * +.I new_size +was zero; +.IP * +.I new_size +or +.I new_address +was invalid; +.IP * +the new address range specified by +.I new_address +and +.I new_size +overlapped the old address range specified by +.I old_address +and +.IR old_size ; +.IP * +.B MREMAP_FIXED +was specified without also specifying +.BR MREMAP_MAYMOVE ; +.IP * +\fIold_size\fP was zero and \fIold_address\fP does not refer to a +shareable mapping (but see BUGS); +.IP * +\fIold_size\fP was zero and the +.BR MREMAP_MAYMOVE +flag was not specified. +.RE +.TP +.B ENOMEM +The memory area cannot be expanded at the current virtual address, and the +.B MREMAP_MAYMOVE +flag is not set in \fIflags\fP. +Or, there is not enough (virtual) memory available. +.SH CONFORMING TO +This call is Linux-specific, and should not be used in programs +intended to be portable. +.\" 4.2BSD had a (never actually implemented) +.\" .BR mremap (2) +.\" call with completely different semantics. +.SH NOTES +Prior to version 2.4, glibc did not expose the definition of +.BR MREMAP_FIXED , +and the prototype for +.BR mremap () +did not allow for the +.I new_address +argument. +.PP +If +.BR mremap () +is used to move or expand an area locked with +.BR mlock (2) +or equivalent, the +.BR mremap () +call will make a best effort to populate the new area but will not fail +with +.B ENOMEM +if the area cannot be populated. +.SH BUGS +Before Linux 4.14, +if +.I old_size +was zero and the mapping referred to by +.I old_address +was a private mapping +.RB ( mmap "(2) " MAP_PRIVATE ), +.BR mremap () +created a new private mapping unrelated to the original mapping. +This behavior was unintended +and probably unexpected in user-space applications +(since the intention of +.BR mremap () +is to create a new mapping based on the original mapping). +Since Linux 4.14, +.\" commit dba58d3b8c5045ad89c1c95d33d01451e3964db7 +.BR mremap () +fails with the error +.B EINVAL +in this scenario. +.SH SEE ALSO +.BR brk (2), +.BR getpagesize (2), +.BR getrlimit (2), +.BR mlock (2), +.BR mmap (2), +.BR sbrk (2), +.BR malloc (3), +.BR realloc (3) +.PP +Your favorite text book on operating systems +for more information on paged memory +(e.g., \fIModern Operating Systems\fP by Andrew S. Tanenbaum, +\fIInside Linux\fP by Randolf Bentson, +\fIThe Design of the UNIX Operating System\fP by Maurice J. Bach) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/msgctl.2 b/man2/msgctl.2 new file mode 100644 index 0000000..461aae9 --- /dev/null +++ b/man2/msgctl.2 @@ -0,0 +1,382 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright 2004, 2005 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified, 17 Jun 2004, Michael Kerrisk +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added msqid_ds and ipc_perm structure definitions +.\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions +.\" +.TH MSGCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +msgctl \- System V message control operations +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf ); +.fi +.SH DESCRIPTION +.BR msgctl () +performs the control operation specified by +.I cmd +on the System\ V message queue with identifier +.IR msqid . +.PP +The +.I msqid_ds +data structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct msqid_ds { + struct ipc_perm msg_perm; /* Ownership and permissions */ + time_t msg_stime; /* Time of last msgsnd(2) */ + time_t msg_rtime; /* Time of last msgrcv(2) */ + time_t msg_ctime; /* Time of last change */ + unsigned long __msg_cbytes; /* Current number of bytes in + queue (nonstandard) */ + msgqnum_t msg_qnum; /* Current number of messages + in queue */ + msglen_t msg_qbytes; /* Maximum number of bytes + allowed in queue */ + pid_t msg_lspid; /* PID of last msgsnd(2) */ + pid_t msg_lrpid; /* PID of last msgrcv(2) */ +}; +.EE +.in +.PP +The +.I ipc_perm +structure is defined as follows +(the highlighted fields are settable using +.BR IPC_SET ): +.PP +.in +4n +.EX +struct ipc_perm { + key_t __key; /* Key supplied to msgget(2) */ + uid_t \fBuid\fP; /* Effective UID of owner */ + gid_t \fBgid\fP; /* Effective GID of owner */ + uid_t cuid; /* Effective UID of creator */ + gid_t cgid; /* Effective GID of creator */ + unsigned short \fBmode\fP; /* Permissions */ + unsigned short __seq; /* Sequence number */ +}; +.EE +.in +.PP +Valid values for +.I cmd +are: +.TP +.B IPC_STAT +Copy information from the kernel data structure associated with +.I msqid +into the +.I msqid_ds +structure pointed to by +.IR buf . +The caller must have read permission on the message queue. +.TP +.B IPC_SET +Write the values of some members of the +.I msqid_ds +structure pointed to by +.I buf +to the kernel data structure associated with this message queue, +updating also its +.I msg_ctime +member. +The following members of the structure are updated: +.IR msg_qbytes , +.IR msg_perm.uid , +.IR msg_perm.gid , +and (the least significant 9 bits of) +.IR msg_perm.mode . +The effective UID of the calling process must match the owner +.RI ( msg_perm.uid ) +or creator +.RI ( msg_perm.cuid ) +of the message queue, or the caller must be privileged. +Appropriate privilege (Linux: the +.B CAP_SYS_RESOURCE +capability) is required to raise the +.I msg_qbytes +value beyond the system parameter +.BR MSGMNB . +.TP +.B IPC_RMID +Immediately remove the message queue, +awakening all waiting reader and writer processes (with an error +return and +.I errno +set to +.BR EIDRM ). +The calling process must have appropriate privileges +or its effective user ID must be either that of the creator or owner +of the message queue. +The third argument to +.BR msgctl () +is ignored in this case. +.TP +.BR IPC_INFO " (Linux-specific)" +Return information about system-wide message queue limits and +parameters in the structure pointed to by +.IR buf . +This structure is of type +.I msginfo +(thus, a cast is required), +defined in +.I +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct msginfo { + int msgpool; /* Size in kibibytes of buffer pool + used to hold message data; + unused within kernel */ + int msgmap; /* Maximum number of entries in message + map; unused within kernel */ + int msgmax; /* Maximum number of bytes that can be + written in a single message */ + int msgmnb; /* Maximum number of bytes that can be + written to queue; used to initialize + msg_qbytes during queue creation + (msgget(2)) */ + int msgmni; /* Maximum number of message queues */ + int msgssz; /* Message segment size; + unused within kernel */ + int msgtql; /* Maximum number of messages on all queues + in system; unused within kernel */ + unsigned short int msgseg; + /* Maximum number of segments; + unused within kernel */ +}; +.EE +.in +.IP +The +.IR msgmni , +.IR msgmax , +and +.I msgmnb +settings can be changed via +.I /proc +files of the same name; see +.BR proc (5) +for details. +.TP +.BR MSG_INFO " (Linux-specific)" +Return a +.I msginfo +structure containing the same information as for +.BR IPC_INFO , +except that the following fields are returned with information +about system resources consumed by message queues: the +.I msgpool +field returns the number of message queues that currently exist +on the system; the +.I msgmap +field returns the total number of messages in all queues +on the system; and the +.I msgtql +field returns the total number of bytes in all messages +in all queues on the system. +.TP +.BR MSG_STAT " (Linux-specific)" +Return a +.I msqid_ds +structure as for +.BR IPC_STAT . +However, the +.I msqid +argument is not a queue identifier, but instead an index into +the kernel's internal array that maintains information about +all message queues on the system. +.SH RETURN VALUE +On success, +.BR IPC_STAT , +.BR IPC_SET , +and +.B IPC_RMID +return 0. +A successful +.B IPC_INFO +or +.B MSG_INFO +operation returns the index of the highest used entry in the +kernel's internal array recording information about all +message queues. +(This information can be used with repeated +.B MSG_STAT +operations to obtain information about all queues on the system.) +A successful +.B MSG_STAT +operation returns the identifier of the queue whose index was given in +.IR msqid . +.PP +On error, \-1 is returned with +.I errno +indicating the error. +.SH ERRORS +On failure, +.I errno +is set to one of the following: +.TP +.B EACCES +The argument +.I cmd +is equal to +.B IPC_STAT +or +.BR MSG_STAT , +but the calling process does not have read permission on the message queue +.IR msqid , +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The argument +.I cmd +has the value +.B IPC_SET +or +.BR IPC_STAT , +but the address pointed to by +.I buf +isn't accessible. +.TP +.B EIDRM +The message queue was removed. +.TP +.B EINVAL +Invalid value for +.I cmd +or +.IR msqid . +Or: for a +.B MSG_STAT +operation, the index value specified in +.I msqid +referred to an array slot that is currently unused. +.TP +.B EPERM +The argument +.I cmd +has the value +.B IPC_SET +or +.BR IPC_RMID , +but the effective user ID of the calling process is not the creator +(as found in +.IR msg_perm.cuid ) +or the owner +(as found in +.IR msg_perm.uid ) +of the message queue, +and the caller is not privileged (Linux: does not have the +.B CAP_SYS_ADMIN +capability). +.TP +.B EPERM +An attempt +.RB ( IPC_SET ) +was made to increase +.I msg_qbytes +beyond the system parameter +.BR MSGMNB , +but the caller is not privileged (Linux: does not have the +.B CAP_SYS_RESOURCE +capability). +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVID does not document the EIDRM error condition. +.SH NOTES +The inclusion of +.I +and +.I +isn't required on Linux or by any version of POSIX. +However, +some old implementations required the inclusion of these header files, +and the SVID also documented their inclusion. +Applications intended to be portable to such old systems may need +to include these header files. +.\" Like Linux, the FreeBSD man pages still document +.\" the inclusion of these header files. +.PP +The +.BR IPC_INFO , +.B MSG_STAT +and +.B MSG_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future these may modified or moved to a +.I /proc +filesystem interface. +.PP +Various fields in the \fIstruct msqid_ds\fP were +typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR cmd .) +.SH SEE ALSO +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR capabilities (7), +.BR mq_overview (7), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/msgget.2 b/man2/msgget.2 new file mode 100644 index 0000000..73e1ce9 --- /dev/null +++ b/man2/msgget.2 @@ -0,0 +1,249 @@ +.\" Copyright 1993 Giorgio Ciucci +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Added correction due to Nick Duffek , aeb, 960426 +.\" Modified Wed Nov 6 04:00:31 1996 by Eric S. Raymond +.\" Modified, 8 Jan 2003, Michael Kerrisk, +.\" Removed EIDRM from errors - that can't happen... +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" +.TH MSGGET 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +msgget \- get a System V message queue identifier +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int msgget(key_t " key ", int " msgflg ); +.fi +.SH DESCRIPTION +The +.BR msgget () +system call returns the System\ V message queue identifier associated +with the value of the +.I key +argument. +A new message queue is created if +.I key +has the value +.B IPC_PRIVATE +or +.I key +isn't +.BR IPC_PRIVATE , +no message queue with the given key +.I key +exists, and +.B IPC_CREAT +is specified in +.IR msgflg . +.PP +If +.I msgflg +specifies both +.B IPC_CREAT +and +.B IPC_EXCL +and a message queue already exists for +.IR key , +then +.BR msgget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) +.PP +Upon creation, the least significant bits of the argument +.I msgflg +define the permissions of the message queue. +These permission bits have the same format and semantics +as the permissions specified for the +.I mode +argument of +.BR open (2). +(The execute permissions are not used.) +.PP +If a new message queue is created, +then its associated data structure +.I msqid_ds +(see +.BR msgctl (2)) +is initialized as follows: +.IP +.I msg_perm.cuid +and +.I msg_perm.uid +are set to the effective user ID of the calling process. +.IP +.I msg_perm.cgid +and +.I msg_perm.gid +are set to the effective group ID of the calling process. +.IP +The least significant 9 bits of +.I msg_perm.mode +are set to the least significant 9 bits of +.IR msgflg . +.IP +.IR msg_qnum , +.IR msg_lspid , +.IR msg_lrpid , +.IR msg_stime , +and +.I msg_rtime +are set to 0. +.IP +.I msg_ctime +is set to the current time. +.IP +.I msg_qbytes +is set to the system limit +.BR MSGMNB . +.PP +If the message queue already exists the permissions are +verified, and a check is made to see if it is marked for +destruction. +.SH RETURN VALUE +If successful, the return value will be the message queue identifier (a +nonnegative integer), otherwise \-1 +with +.I errno +indicating the error. +.SH ERRORS +On failure, +.I errno +is set to one of the following values: +.TP +.B EACCES +A message queue exists for +.IR key , +but the calling process does not have permission to access the queue, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EEXIST +.B IPC_CREAT +and +.BR IPC_EXCL +were specified in +.IR msgflg , +but a message queue already exists for +.IR key . +.TP +.B ENOENT +No message queue exists for +.I key +and +.I msgflg +did not specify +.BR IPC_CREAT . +.TP +.B ENOMEM +A message queue has to be created but the system does not have enough +memory for the new data structure. +.TP +.B ENOSPC +A message queue has to be created but the system limit for the maximum +number of message queues +.RB ( MSGMNI ) +would be exceeded. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.SH NOTES +The inclusion of +.I +and +.I +isn't required on Linux or by any version of POSIX. +However, +some old implementations required the inclusion of these header files, +and the SVID also documented their inclusion. +Applications intended to be portable to such old systems may need +to include these header files. +.\" Like Linux, the FreeBSD man pages still document +.\" the inclusion of these header files. +.PP +.B IPC_PRIVATE +isn't a flag field but a +.I key_t +type. +If this special value is used for +.IR key , +the system call ignores everything but the least significant 9 bits of +.I msgflg +and creates a new message queue (on success). +.PP +The following is a system limit on message queue resources affecting a +.BR msgget () +call: +.TP +.B MSGMNI +System-wide limit on the number of message queues. +Before Linux 3.19, +.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 +the default value for this limit was calculated using a formula +based on available system memory. +Since Linux 3.19, the default value is 32,000. +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/msgmni . +.SS Linux notes +Until version 2.3.20, Linux would return +.B EIDRM +for a +.BR msgget () +on a message queue scheduled for deletion. +.SH BUGS +The name choice +.B IPC_PRIVATE +was perhaps unfortunate, +.B IPC_NEW +would more clearly show its function. +.SH SEE ALSO +.BR msgctl (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR ftok (3), +.BR capabilities (7), +.BR mq_overview (7), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/msgop.2 b/man2/msgop.2 new file mode 100644 index 0000000..822d5d7 --- /dev/null +++ b/man2/msgop.2 @@ -0,0 +1,724 @@ +.\" Copyright 1993 Giorgio Ciucci +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond +.\" Modified Mon Jul 10 21:09:59 2000 by aeb +.\" Modified 1 Jun 2002, Michael Kerrisk +.\" Language clean-ups. +.\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX +.\" Added note on restart behavior of msgsnd() and msgrcv() +.\" Formatting clean-ups (argument and field names marked as .I +.\" instead of .B) +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" +.TH MSGOP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +msgrcv, msgsnd \- System V message queue operations +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int msgsnd(int " msqid ", const void *" msgp ", size_t " msgsz \ +", int " msgflg ); +.PP +.BI "ssize_t msgrcv(int " msqid ", void *" msgp ", size_t " msgsz \ +", long " msgtyp , +.BI " int " msgflg ); +.fi +.SH DESCRIPTION +The +.BR msgsnd () +and +.BR msgrcv () +system calls are used, respectively, to send messages to, +and receive messages from, a System\ V message queue. +The calling process must have write permission on the message queue +in order to send a message, and read permission to receive a message. +.PP +The +.I msgp +argument is a pointer to a caller-defined structure +of the following general form: +.PP +.in +4n +.EX +struct msgbuf { + long mtype; /* message type, must be > 0 */ + char mtext[1]; /* message data */ +}; +.EE +.in +.PP +The +.I mtext +field is an array (or other structure) whose size is specified by +.IR msgsz , +a nonnegative integer value. +Messages of zero length (i.e., no +.I mtext +field) are permitted. +The +.I mtype +field must have a strictly positive integer value. +This value can be +used by the receiving process for message selection +(see the description of +.BR msgrcv () +below). +.SS msgsnd() +The +.BR msgsnd () +system call appends a copy of the message pointed to by +.I msgp +to the message queue whose identifier is specified +by +.IR msqid . +.PP +If sufficient space is available in the queue, +.BR msgsnd () +succeeds immediately. +The queue capacity is governed by the +.I msg_qbytes +field in the associated data structure for the message queue. +During queue creation this field is initialized to +.B MSGMNB +bytes, but this limit can be modified using +.BR msgctl (2). +A message queue is considered to be full if either of the following +conditions is true: +.IP * 2 +Adding a new message to the queue would cause the total number of bytes +in the queue to exceed the queue's maximum size (the +.I msg_qbytes +field). +.IP * +Adding another message to the queue would cause the total number of messages +in the queue to exceed the queue's maximum size (the +.I msg_qbytes +field). +This check is necessary to prevent an unlimited number of zero-length +messages being placed on the queue. +Although such messages contain no data, +they nevertheless consume (locked) kernel memory. +.PP +If insufficient space is available in the queue, then the default +behavior of +.BR msgsnd () +is to block until space becomes available. +If +.B IPC_NOWAIT +is specified in +.IR msgflg , +then the call instead fails with the error +.BR EAGAIN . +.PP +A blocked +.BR msgsnd () +call may also fail if: +.IP * 2 +the queue is removed, +in which case the system call fails with +.I errno +set to +.BR EIDRM ; +or +.IP * +a signal is caught, in which case the system call fails +with +.I errno +set to +.BR EINTR ; see +.BR signal (7). +.RB ( msgsnd () +is never automatically restarted after being interrupted by a +signal handler, regardless of the setting of the +.B SA_RESTART +flag when establishing a signal handler.) +.PP +Upon successful completion the message queue data structure is updated +as follows: +.IP +.I msg_lspid +is set to the process ID of the calling process. +.IP +.I msg_qnum +is incremented by 1. +.IP +.I msg_stime +is set to the current time. +.SS msgrcv() +The +.BR msgrcv () +system call removes a message from the queue specified by +.I msqid +and places it in the buffer +pointed to by +.IR msgp . +.PP +The argument +.I msgsz +specifies the maximum size in bytes for the member +.I mtext +of the structure pointed to by the +.I msgp +argument. +If the message text has length greater than +.IR msgsz , +then the behavior depends on whether +.B MSG_NOERROR +is specified in +.IR msgflg . +If +.B MSG_NOERROR +is specified, then +the message text will be truncated (and the truncated part will be +lost); if +.B MSG_NOERROR +is not specified, then +the message isn't removed from the queue and +the system call fails returning \-1 with +.I errno +set to +.BR E2BIG . +.PP +Unless +.B MSG_COPY +is specified in +.IR msgflg +(see below), +the +.I msgtyp +argument specifies the type of message requested, as follows: +.IP * 2 +If +.I msgtyp +is 0, +then the first message in the queue is read. +.IP * +If +.I msgtyp +is greater than 0, +then the first message in the queue of type +.I msgtyp +is read, unless +.B MSG_EXCEPT +was specified in +.IR msgflg , +in which case +the first message in the queue of type not equal to +.I msgtyp +will be read. +.IP * +If +.I msgtyp +is less than 0, +then the first message in the queue with the lowest type less than or +equal to the absolute value of +.I msgtyp +will be read. +.PP +The +.I msgflg +argument is a bit mask constructed by ORing together zero or more +of the following flags: +.TP +.B IPC_NOWAIT +Return immediately if no message of the requested type is in the queue. +The system call fails with +.I errno +set to +.BR ENOMSG . +.TP +.BR MSG_COPY " (since Linux 3.8)" +.\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8 +Nondestructively fetch a copy of the message at the ordinal position +in the queue specified by +.I msgtyp +(messages are considered to be numbered starting at 0). +.IP +This flag must be specified in conjunction with +.BR IPC_NOWAIT , +with the result that, if there is no message available at the given position, +the call fails immediately with the error +.BR ENOMSG . +Because they alter the meaning of +.I msgtyp +in orthogonal ways, +.BR MSG_COPY +and +.BR MSG_EXCEPT +may not both be specified in +.IR msgflg . +.IP +The +.BR MSG_COPY +flag was added for the implementation of +the kernel checkpoint-restore facility and +is available only if the kernel was built with the +.B CONFIG_CHECKPOINT_RESTORE +option. +.TP +.B MSG_EXCEPT +Used with +.I msgtyp +greater than 0 +to read the first message in the queue with message type that differs +from +.IR msgtyp . +.TP +.B MSG_NOERROR +To truncate the message text if longer than +.I msgsz +bytes. +.PP +If no message of the requested type is available and +.B IPC_NOWAIT +isn't specified in +.IR msgflg , +the calling process is blocked until one of the following conditions occurs: +.IP * 2 +A message of the desired type is placed in the queue. +.IP * +The message queue is removed from the system. +In this case, the system call fails with +.I errno +set to +.BR EIDRM . +.IP * +The calling process catches a signal. +In this case, the system call fails with +.I errno +set to +.BR EINTR . +.RB ( msgrcv () +is never automatically restarted after being interrupted by a +signal handler, regardless of the setting of the +.B SA_RESTART +flag when establishing a signal handler.) +.PP +Upon successful completion the message queue data structure is updated +as follows: +.IP +.I msg_lrpid +is set to the process ID of the calling process. +.IP +.I msg_qnum +is decremented by 1. +.IP +.I msg_rtime +is set to the current time. +.SH RETURN VALUE +On failure both functions return \-1 +with +.I errno +indicating the error, +otherwise +.BR msgsnd () +returns 0 +and +.BR msgrcv () +returns the number of bytes actually copied into the +.I mtext +array. +.SH ERRORS +When +.BR msgsnd () +fails, +.I errno +will be set to one among the following values: +.TP +.B EACCES +The calling process does not have write permission on the message queue, +and does not have the +.B CAP_IPC_OWNER +capability. +.TP +.B EAGAIN +The message can't be sent due to the +.I msg_qbytes +limit for the queue and +.B IPC_NOWAIT +was specified in +.IR msgflg . +.TP +.B EFAULT +The address pointed to by +.I msgp +isn't accessible. +.TP +.B EIDRM +The message queue was removed. +.TP +.B EINTR +Sleeping on a full message queue condition, the process caught a signal. +.TP +.B EINVAL +Invalid +.I msqid +value, or nonpositive +.I mtype +value, or +invalid +.I msgsz +value (less than 0 or greater than the system value +.BR MSGMAX ). +.TP +.B ENOMEM +The system does not have enough memory to make a copy of the +message pointed to by +.IR msgp . +.PP +When +.BR msgrcv () +fails, +.I errno +will be set to one among the following values: +.TP +.B E2BIG +The message text length is greater than +.I msgsz +and +.B MSG_NOERROR +isn't specified in +.IR msgflg . +.TP +.B EACCES +The calling process does not have read permission on the message queue, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The address pointed to by +.I msgp +isn't accessible. +.TP +.B EIDRM +While the process was sleeping to receive a message, +the message queue was removed. +.TP +.B EINTR +While the process was sleeping to receive a message, +the process caught a signal; see +.BR signal (7). +.TP +.B EINVAL +.I msqid +was invalid, or +.I msgsz +was less than 0. +.TP +.BR EINVAL " (since Linux 3.14)" +.I msgflg +specified +.BR MSG_COPY , +but not +.BR IPC_NOWAIT . +.TP +.BR EINVAL " (since Linux 3.14)" +.I msgflg +specified both +.BR MSG_COPY +and +.BR MSG_EXCEPT . +.TP +.B ENOMSG +.B IPC_NOWAIT +was specified in +.I msgflg +and no message of the requested type existed on the message queue. +.TP +.B ENOMSG +.B IPC_NOWAIT +and +.B MSG_COPY +were specified in +.I msgflg +and the queue contains less than +.I msgtyp +messages. +.TP +.BR ENOSYS " (since Linux 3.8)" +.I MSG_COPY +was specified in +.IR msgflg , +and this kernel was configured without +.BR CONFIG_CHECKPOINT_RESTORE . +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.PP +The +.B MSG_EXCEPT +and +.B MSG_COPY +flags are Linux-specific; +their definitions can be obtained by defining the +.B _GNU_SOURCE +.\" MSG_COPY since glibc 2.18 +feature test macro. +.SH NOTES +The inclusion of +.I +and +.I +isn't required on Linux or by any version of POSIX. +However, +some old implementations required the inclusion of these header files, +and the SVID also documented their inclusion. +Applications intended to be portable to such old systems may need +to include these header files. +.\" Like Linux, the FreeBSD man pages still document +.\" the inclusion of these header files. +.PP +The +.I msgp +argument is declared as \fIstruct msgbuf\ *\fP in +glibc 2.0 and 2.1. +It is declared as \fIvoid\ *\fP +in glibc 2.2 and later, as required by SUSv2 and SUSv3. +.PP +The following limits on message queue resources affect the +.BR msgsnd () +call: +.TP +.B MSGMAX +Maximum size of a message text, in bytes (default value: 8192 bytes). +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/msgmax . +.TP +.B MSGMNB +Maximum number of bytes that can be held in a message queue +(default value: 16384 bytes). +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/msgmnb . +A privileged process +(Linux: a process with the +.B CAP_SYS_RESOURCE +capability) +can increase the size of a message queue beyond +.B MSGMNB +using the +.BR msgctl (2) +.B IPC_SET +operation. +.PP +The implementation has no intrinsic system-wide limits on the +number of message headers +.RB ( MSGTQL ) +and the number of bytes in the message pool +.RB ( MSGPOOL ). +.SH BUGS +In Linux 3.13 and earlier, +if +.BR msgrcv () +was called with the +.BR MSG_COPY +flag, but without +.BR IPC_NOWAIT , +and the message queue contained less than +.I msgtyp +messages, then the call would block until the next message is written +to the queue. +.\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2 +At that point, the call would return a copy of the message, +.I regardless +of whether that message was at the ordinal position +.IR msgtyp . +This bug is fixed +.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c +in Linux 3.14. +.PP +Specifying both +.B MSG_COPY +and +.B MSC_EXCEPT +in +.I msgflg +is a logical error (since these flags impose different interpretations on +.IR msgtyp ). +In Linux 3.13 and earlier, +.\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2 +this error was not diagnosed by +.BR msgrcv (). +This bug is fixed +.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c +in Linux 3.14. +.SH EXAMPLE +The program below demonstrates the use of +.BR msgsnd () +and +.BR msgrcv (). +.PP +The example program is first run with the \fB\-s\fP option to send a +message and then run again with the \fB\-r\fP option to receive a +message. +.PP +The following shell session shows a sample run of the program: +.PP +.in +4n +.EX +.RB "$" " ./a.out \-s" +sent: a message at Wed Mar 4 16:25:45 2015 + +.RB "$" " ./a.out \-r" +message received: a message at Wed Mar 4 16:25:45 2015 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +#include +#include +#include + +struct msgbuf { + long mtype; + char mtext[80]; +}; + +static void +usage(char *prog_name, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); + + fprintf(stderr, "Usage: %s [options]\\n", prog_name); + fprintf(stderr, "Options are:\\n"); + fprintf(stderr, "\-s send message using msgsnd()\\n"); + fprintf(stderr, "\-r read message using msgrcv()\\n"); + fprintf(stderr, "\-t message type (default is 1)\\n"); + fprintf(stderr, "\-k message queue key (default is 1234)\\n"); + exit(EXIT_FAILURE); +} + +static void +send_msg(int qid, int msgtype) +{ + struct msgbuf msg; + time_t t; + + msg.mtype = msgtype; + + time(&t); + snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s", + ctime(&t)); + + if (msgsnd(qid, (void *) &msg, sizeof(msg.mtext), + IPC_NOWAIT) == \-1) { + perror("msgsnd error"); + exit(EXIT_FAILURE); + } + printf("sent: %s\\n", msg.mtext); +} + +static void +get_msg(int qid, int msgtype) +{ + struct msgbuf msg; + + if (msgrcv(qid, (void *) &msg, sizeof(msg.mtext), msgtype, + MSG_NOERROR | IPC_NOWAIT) == \-1) { + if (errno != ENOMSG) { + perror("msgrcv"); + exit(EXIT_FAILURE); + } + printf("No message available for msgrcv()\\n"); + } else + printf("message received: %s\\n", msg.mtext); +} + +int +main(int argc, char *argv[]) +{ + int qid, opt; + int mode = 0; /* 1 = send, 2 = receive */ + int msgtype = 1; + int msgkey = 1234; + + while ((opt = getopt(argc, argv, "srt:k:")) != \-1) { + switch (opt) { + case \(aqs\(aq: + mode = 1; + break; + case \(aqr\(aq: + mode = 2; + break; + case \(aqt\(aq: + msgtype = atoi(optarg); + if (msgtype <= 0) + usage(argv[0], "\-t option must be greater than 0\\n"); + break; + case \(aqk\(aq: + msgkey = atoi(optarg); + break; + default: + usage(argv[0], "Unrecognized option\\n"); + } + } + + if (mode == 0) + usage(argv[0], "must use either \-s or \-r option\\n"); + + qid = msgget(msgkey, IPC_CREAT | 0666); + + if (qid == \-1) { + perror("msgget"); + exit(EXIT_FAILURE); + } + + if (mode == 2) + get_msg(qid, msgtype); + else + send_msg(qid, msgtype); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR msgctl (2), +.BR msgget (2), +.BR capabilities (7), +.BR mq_overview (7), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/msgrcv.2 b/man2/msgrcv.2 new file mode 100644 index 0000000..b34869e --- /dev/null +++ b/man2/msgrcv.2 @@ -0,0 +1 @@ +.so man2/msgop.2 diff --git a/man2/msgsnd.2 b/man2/msgsnd.2 new file mode 100644 index 0000000..b34869e --- /dev/null +++ b/man2/msgsnd.2 @@ -0,0 +1 @@ +.so man2/msgop.2 diff --git a/man2/msync.2 b/man2/msync.2 new file mode 100644 index 0000000..4ddef2c --- /dev/null +++ b/man2/msync.2 @@ -0,0 +1,162 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MSYNC 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +msync \- synchronize a file with a memory map +.SH SYNOPSIS +.B #include +.PP +.BI "int msync(void *" addr ", size_t " length ", int " flags ); +.SH DESCRIPTION +.BR msync () +flushes changes made to the in-core copy of a file that was mapped +into memory using +.BR mmap (2) +back to the filesystem. +Without use of this call, +there is no guarantee that changes are written back before +.BR munmap (2) +is called. +To be more precise, the part of the file that +corresponds to the memory area starting at +.I addr +and having length +.I length +is updated. +.PP +The +.I flags +argument should specify exactly one of +.BR MS_ASYNC +and +.BR MS_SYNC , +and may additionally include the +.B MS_INVALIDATE +bit. +These bits have the following meanings: +.TP +.B MS_ASYNC +Specifies that an update be scheduled, but the call returns immediately. +.TP +.B MS_SYNC +Requests an update and waits for it to complete. +.TP +.B MS_INVALIDATE +.\" Since Linux 2.4, this seems to be a no-op (other than the +.\" EBUSY check for VM_LOCKED). +Asks to invalidate other mappings of the same file +(so that they can be updated with the fresh values just written). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBUSY +.B MS_INVALIDATE +was specified in +.IR flags , +and a memory lock exists for the specified address range. +.TP +.B EINVAL +.I addr +is not a multiple of PAGESIZE; or any bit other than +.BR MS_ASYNC " | " MS_INVALIDATE " | " MS_SYNC +is set in +.IR flags ; +or both +.B MS_SYNC +and +.B MS_ASYNC +are set in +.IR flags . +.TP +.B ENOMEM +The indicated memory (or part of it) was not mapped. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.PP +This call was introduced in Linux 1.3.21, and then used +.B EFAULT +instead of +.BR ENOMEM . +In Linux 2.4.19, this was changed to the POSIX value +.BR ENOMEM . +.SH AVAILABILITY +On POSIX systems on which +.BR msync () +is available, both +.B _POSIX_MAPPED_FILES +and +.B _POSIX_SYNCHRONIZED_IO +are defined in +.I +to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines them to 1. +.SH NOTES +According to POSIX, either +.BR MS_SYNC +or +.BR MS_ASYNC +must be specified in +.IR flags , +and indeed failure to include one of these flags will cause +.BR msync () +to fail on some systems. +However, Linux permits a call to +.BR msync () +that specifies neither of these flags, +with semantics that are (currently) equivalent to specifying +.BR MS_ASYNC . +(Since Linux 2.6.19, +.\" commit 204ec841fbea3e5138168edbc3a76d46747cc987 +.BR MS_ASYNC +is in fact a no-op, since the kernel properly tracks dirty +pages and flushes them to storage as necessary.) +Notwithstanding the Linux behavior, +portable, future-proof applications should ensure that they specify either +.BR MS_SYNC +or +.BR MS_ASYNC +in +.IR flags . +.SH SEE ALSO +.BR mmap (2) +.PP +B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/munlock.2 b/man2/munlock.2 new file mode 100644 index 0000000..5e5b3c7 --- /dev/null +++ b/man2/munlock.2 @@ -0,0 +1 @@ +.so man2/mlock.2 diff --git a/man2/munlockall.2 b/man2/munlockall.2 new file mode 100644 index 0000000..5e5b3c7 --- /dev/null +++ b/man2/munlockall.2 @@ -0,0 +1 @@ +.so man2/mlock.2 diff --git a/man2/munmap.2 b/man2/munmap.2 new file mode 100644 index 0000000..8902d1b --- /dev/null +++ b/man2/munmap.2 @@ -0,0 +1 @@ +.so man2/mmap.2 diff --git a/man2/name_to_handle_at.2 b/man2/name_to_handle_at.2 new file mode 100644 index 0000000..090521c --- /dev/null +++ b/man2/name_to_handle_at.2 @@ -0,0 +1 @@ +.so man2/open_by_handle_at.2 diff --git a/man2/nanosleep.2 b/man2/nanosleep.2 new file mode 100644 index 0000000..86c9b41 --- /dev/null +++ b/man2/nanosleep.2 @@ -0,0 +1,246 @@ +.\" Copyright (C) Markus Kuhn, 1996 +.\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1996-04-10 Markus Kuhn +.\" First version written +.\" Modified, 2004-10-24, aeb +.\" 2008-06-24, mtk +.\" Minor rewrites of some parts. +.\" NOTES: describe case where clock_nanosleep() can be preferable. +.\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP +.\" Replace crufty discussion of HZ with a pointer to time(7). +.TH NANOSLEEP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +nanosleep \- high-resolution sleep +.SH SYNOPSIS +.B #include +.PP +.BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR nanosleep (): +_POSIX_C_SOURCE\ >=\ 199309L +.SH DESCRIPTION +.BR nanosleep () +suspends the execution of the calling thread +until either at least the time specified in +.IR *req +has elapsed, or the delivery of a signal +that triggers the invocation of a handler in the calling thread or +that terminates the process. +.PP +If the call is interrupted by a signal handler, +.BR nanosleep () +returns \-1, sets +.I errno +to +.BR EINTR , +and writes the remaining time into the structure pointed to by +.I rem +unless +.I rem +is NULL. +The value of +.I *rem +can then be used to call +.BR nanosleep () +again and complete the specified pause (but see NOTES). +.PP +The structure +.I timespec +is used to specify intervals of time with nanosecond precision. +It is defined as follows: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.PP +The value of the nanoseconds field must be in the range 0 to 999999999. +.PP +Compared to +.BR sleep (3) +and +.BR usleep (3), +.BR nanosleep () +has the following advantages: +it provides a higher resolution for specifying the sleep interval; +POSIX.1 explicitly specifies that it +does not interact with signals; +and it makes the task of resuming a sleep that has been +interrupted by a signal handler easier. +.SH RETURN VALUE +On successfully sleeping for the requested interval, +.BR nanosleep () +returns 0. +If the call is interrupted by a signal handler or encounters an error, +then it returns \-1, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Problem with copying information from user space. +.TP +.B EINTR +The pause has been interrupted by a signal that was +delivered to the thread (see +.BR signal (7)). +The remaining sleep time has been written +into +.I *rem +so that the thread can easily call +.BR nanosleep () +again and continue with the pause. +.TP +.B EINVAL +The value in the +.I tv_nsec +field was not in the range 0 to 999999999 or +.I tv_sec +was negative. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +If the interval specified in +.I req +is not an exact multiple of the granularity underlying clock (see +.BR time (7)), +then the interval will be rounded up to the next multiple. +Furthermore, after the sleep completes, there may still be a delay before +the CPU becomes free to once again execute the calling thread. +.PP +The fact that +.BR nanosleep () +sleeps for a relative interval can be problematic if the call +is repeatedly restarted after being interrupted by signals, +since the time between the interruptions and restarts of the call +will lead to drift in the time when the sleep finally completes. +This problem can be avoided by using +.BR clock_nanosleep (2) +with an absolute time value. +.PP +POSIX.1 specifies that +.BR nanosleep () +should measure time against the +.B CLOCK_REALTIME +clock. +However, Linux measures the time using the +.B CLOCK_MONOTONIC +clock. +.\" See also http://thread.gmane.org/gmane.linux.kernel/696854/ +.\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME? +.\" Date: 2008-06-22 07:35:41 GMT +This probably does not matter, since the POSIX.1 specification for +.BR clock_settime (2) +says that discontinuous changes in +.B CLOCK_REALTIME +should not affect +.BR nanosleep (): +.RS +.PP +Setting the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2) +shall +have no effect on threads that are blocked waiting for a relative time +service based upon this clock, including the +.BR nanosleep () +function; ... +Consequently, these time services shall expire when the requested relative +interval elapses, independently of the new or old value of the clock. +.RE +.SS Old behavior +In order to support applications requiring much more precise pauses +(e.g., in order to control some time-critical hardware), +.BR nanosleep () +would handle pauses of up to 2 milliseconds by busy waiting with microsecond +precision when called from a thread scheduled under a real-time policy +like +.B SCHED_FIFO +or +.BR SCHED_RR . +This special extension was removed in kernel 2.5.39, +and is thus not available in Linux 2.6.0 and later kernels. +.SH BUGS +If a program that catches signals and uses +.BR nanosleep () +receives signals at a very high rate, +then scheduling delays and rounding errors in the kernel's +calculation of the sleep interval and the returned +.IR remain +value mean that the +.IR remain +value may steadily +.IR increase +on successive restarts of the +.BR nanosleep () +call. +To avoid such problems, use +.BR clock_nanosleep (2) +with the +.BR TIMER_ABSTIME +flag to sleep to an absolute deadline. +.PP +In Linux 2.4, if +.BR nanosleep () +is stopped by a signal (e.g., +.BR SIGTSTP ), +then the call fails with the error +.B EINTR +after the thread is resumed by a +.B SIGCONT +signal. +If the system call is subsequently restarted, +then the time that the thread spent in the stopped state is +.I not +counted against the sleep interval. +This problem is fixed in Linux 2.6.0 and later kernels. +.SH SEE ALSO +.BR clock_nanosleep (2), +.BR restart_syscall (2), +.BR sched_setscheduler (2), +.BR timer_create (2), +.BR sleep (3), +.BR usleep (3), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/newfstatat.2 b/man2/newfstatat.2 new file mode 100644 index 0000000..7791269 --- /dev/null +++ b/man2/newfstatat.2 @@ -0,0 +1 @@ +.so man2/fstatat.2 diff --git a/man2/nfsservctl.2 b/man2/nfsservctl.2 new file mode 100644 index 0000000..25ce164 --- /dev/null +++ b/man2/nfsservctl.2 @@ -0,0 +1,71 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This text is in the public domain. +.\" %%%LICENSE_END +.\" +.TH NFSSERVCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +nfsservctl \- syscall interface to kernel nfs daemon +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long nfsservctl(int " cmd ", struct nfsctl_arg *" argp , +.BI " union nfsctl_res *" resp ); +.fi +.SH DESCRIPTION +.IR Note : +Since Linux 3.1, this system call no longer exists. +It has been replaced by a set of files in the +.I nfsd +filesystem; see +.BR nfsd (7). +.PP +.in +4n +.EX +/* + * These are the commands understood by nfsctl(). + */ +#define NFSCTL_SVC 0 /* This is a server process. */ +#define NFSCTL_ADDCLIENT 1 /* Add an NFS client. */ +#define NFSCTL_DELCLIENT 2 /* Remove an NFS client. */ +#define NFSCTL_EXPORT 3 /* Export a filesystem. */ +#define NFSCTL_UNEXPORT 4 /* Unexport a filesystem. */ +#define NFSCTL_UGIDUPDATE 5 /* Update a client's UID/GID map + (only in Linux 2.4.x and earlier). */ +#define NFSCTL_GETFH 6 /* Get a file handle (used by mountd) + (only in Linux 2.4.x and earlier). */ + +struct nfsctl_arg { + int ca_version; /* safeguard */ + union { + struct nfsctl_svc u_svc; + struct nfsctl_client u_client; + struct nfsctl_export u_export; + struct nfsctl_uidmap u_umap; + struct nfsctl_fhparm u_getfh; + unsigned int u_debug; + } u; +} + +union nfsctl_res { + struct knfs_fh cr_getfh; + unsigned int cr_debug; +}; +.EE +.in +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH CONFORMING TO +This call is Linux-specific. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/nice.2 b/man2/nice.2 new file mode 100644 index 0000000..41c066d --- /dev/null +++ b/man2/nice.2 @@ -0,0 +1,140 @@ +.\" Copyright (c) 1992 Drew Eckhardt , March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-11-04 by Eric S. Raymond +.\" Modified 2001-06-04 by aeb +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH NICE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +nice \- change process priority +.SH SYNOPSIS +.B #include +.PP +.BI "int nice(int " inc ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR nice (): +_XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +.BR nice () +adds +.I inc +to the nice value for the calling thread. +(A higher nice value means a low priority.) +.PP +The range of the nice value is +19 (low priority) to \-20 (high priority). +Attempts to set a nice value outside the range are clamped to the range. +.PP +Traditionally, only a privileged process could lower the nice value +(i.e., set a higher priority). +However, since Linux 2.6.12, an unprivileged process can decrease +the nice value of a target process that has a suitable +.BR RLIMIT_NICE +soft limit; see +.BR getrlimit (2) +for details. +.SH RETURN VALUE +On success, the new nice value is returned (but see NOTES below). +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +A successful call can legitimately return \-1. +To detect an error, set +.I errno +to 0 before the call, and check whether it is nonzero after +.BR nice () +returns \-1. +.SH ERRORS +.TP +.B EPERM +The calling process attempted to increase its priority by +supplying a negative +.I inc +but has insufficient privileges. +Under Linux, the +.B CAP_SYS_NICE +capability is required. +(But see the discussion of the +.B RLIMIT_NICE +resource limit in +.BR setrlimit (2).) +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +However, the raw system call and (g)libc +(earlier than glibc 2.2.4) return value is nonstandard, see below. +.\" SVr4 documents an additional +.\" .B EINVAL +.\" error code. +.SH NOTES +For further details on the nice value, see +.BR sched (7). +.PP +.IR Note : +the addition of the "autogroup" feature in Linux 2.6.38 means that +the nice value no longer has its traditional effect in many circumstances. +For details, see +.BR sched (7). +.\" +.SS C library/kernel differences +POSIX.1 specifies that +.BR nice () +should return the new nice value. +However, the raw Linux system call returns 0 on success. +Likewise, the +.BR nice () +wrapper function provided in glibc 2.2.3 and earlier returns 0 on success. +.PP +Since glibc 2.2.4, the +.BR nice () +wrapper function provided by glibc provides conformance to POSIX.1 by calling +.BR getpriority (2) +to obtain the new nice value, which is then returned to the caller. +.SH SEE ALSO +.BR nice (1), +.BR renice (1), +.BR fork (2), +.BR getpriority (2), +.BR getrlimit (2), +.BR setpriority (2), +.BR capabilities (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/oldfstat.2 b/man2/oldfstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man2/oldfstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/oldlstat.2 b/man2/oldlstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man2/oldlstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/oldolduname.2 b/man2/oldolduname.2 new file mode 100644 index 0000000..450f7b1 --- /dev/null +++ b/man2/oldolduname.2 @@ -0,0 +1 @@ +.so man2/uname.2 diff --git a/man2/oldstat.2 b/man2/oldstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man2/oldstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/olduname.2 b/man2/olduname.2 new file mode 100644 index 0000000..450f7b1 --- /dev/null +++ b/man2/olduname.2 @@ -0,0 +1 @@ +.so man2/uname.2 diff --git a/man2/open.2 b/man2/open.2 new file mode 100644 index 0000000..0f9a9e7 --- /dev/null +++ b/man2/open.2 @@ -0,0 +1,1765 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2008 Greg Banks +.\" and Copyright (C) 2006, 2008, 2013, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Haardt +.\" Modified 1996-04-13 by Andries Brouwer +.\" Modified 1996-05-13 by Thomas Koenig +.\" Modified 1996-12-20 by Michael Haardt +.\" Modified 1999-02-19 by Andries Brouwer +.\" Modified 1998-11-28 by Joseph S. Myers +.\" Modified 1999-06-03 by Michael Haardt +.\" Modified 2002-05-07 by Michael Kerrisk +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2004-12-08, mtk, reordered flags list alphabetically +.\" 2004-12-08, Martin Pool (& mtk), added O_NOATIME +.\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits +.\" 2008-01-03, mtk, with input from Trond Myklebust +.\" and Timo Sirainen +.\" Rewrite description of O_EXCL. +.\" 2008-01-11, Greg Banks : add more detail +.\" on O_DIRECT. +.\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode +.\" +.\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and +.\" O_TTYINIT. Eventually these may need to be documented. --mtk +.\" +.TH OPEN 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +open, openat, creat \- open and possibly create a file +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int open(const char *" pathname ", int " flags ); +.BI "int open(const char *" pathname ", int " flags ", mode_t " mode ); +.PP +.BI "int creat(const char *" pathname ", mode_t " mode ); +.PP +.BI "int openat(int " dirfd ", const char *" pathname ", int " flags ); +.BI "int openat(int " dirfd ", const char *" pathname ", int " flags \ +", mode_t " mode ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR openat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR open () +system call opens the file specified by +.IR pathname . +If the specified file does not exist, +it may optionally (if +.B O_CREAT +is specified in +.IR flags ) +be created by +.BR open (). +.PP +The return value of +.BR open () +is a file descriptor, a small, nonnegative integer that is used +in subsequent system calls +.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2), +etc.) to refer to the open file. +The file descriptor returned by a successful call will be +the lowest-numbered file descriptor not currently open for the process. +.PP +By default, the new file descriptor is set to remain open across an +.BR execve (2) +(i.e., the +.B FD_CLOEXEC +file descriptor flag described in +.BR fcntl (2) +is initially disabled); the +.B O_CLOEXEC +flag, described below, can be used to change this default. +The file offset is set to the beginning of the file (see +.BR lseek (2)). +.PP +A call to +.BR open () +creates a new +.IR "open file description" , +an entry in the system-wide table of open files. +The open file description records the file offset and the file status flags +(see below). +A file descriptor is a reference to an open file description; +this reference is unaffected if +.I pathname +is subsequently removed or modified to refer to a different file. +For further details on open file descriptions, see NOTES. +.PP +The argument +.I flags +must include one of the following +.IR "access modes" : +.BR O_RDONLY ", " O_WRONLY ", or " O_RDWR . +These request opening the file read-only, write-only, or read/write, +respectively. +.PP +In addition, zero or more file creation flags and file status flags +can be +.RI bitwise- or 'd +in +.IR flags . +The +.I file creation flags +are +.BR O_CLOEXEC , +.BR O_CREAT , +.BR O_DIRECTORY , +.BR O_EXCL , +.BR O_NOCTTY , +.BR O_NOFOLLOW , +.BR O_TMPFILE , +and +.BR O_TRUNC . +The +.I file status flags +are all of the remaining flags listed below. +.\" SUSv4 divides the flags into: +.\" * Access mode +.\" * File creation +.\" * File status +.\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW) +.\" though it's not clear what the difference between "other" and +.\" "File creation" flags is. I raised an Aardvark to see if this +.\" can be clarified in SUSv4; 10 Oct 2008. +.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67 +.\" TC1 (balloted in 2013), resolved this, so that those three constants +.\" are also categorized" as file status flags. +.\" +The distinction between these two groups of flags is that +the file creation flags affect the semantics of the open operation itself, +while the file status flags affect the semantics of subsequent I/O operations. +The file status flags can be retrieved and (in some cases) +modified; see +.BR fcntl (2) +for details. +.PP +The full list of file creation flags and file status flags is as follows: +.TP +.B O_APPEND +The file is opened in append mode. +Before each +.BR write (2), +the file offset is positioned at the end of the file, +as if with +.BR lseek (2). +The modification of the file offset and the write operation +are performed as a single atomic step. +.IP +.B O_APPEND +may lead to corrupted files on NFS filesystems if more than one process +appends data to a file at once. +.\" For more background, see +.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946 +.\" http://nfs.sourceforge.net/ +This is because NFS does not support +appending to a file, so the client kernel has to simulate it, which +can't be done without a race condition. +.TP +.B O_ASYNC +Enable signal-driven I/O: +generate a signal +.RB ( SIGIO +by default, but this can be changed via +.BR fcntl (2)) +when input or output becomes possible on this file descriptor. +This feature is available only for terminals, pseudoterminals, +sockets, and (since Linux 2.6) pipes and FIFOs. +See +.BR fcntl (2) +for further details. +See also BUGS, below. +.TP +.BR O_CLOEXEC " (since Linux 2.6.23)" +.\" NOTE! several other man pages refer to this text +Enable the close-on-exec flag for the new file descriptor. +.\" FIXME . for later review when Issue 8 is one day released... +.\" POSIX proposes to fix many APIs that provide hidden FDs +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=368 +Specifying this flag permits a program to avoid additional +.BR fcntl (2) +.B F_SETFD +operations to set the +.B FD_CLOEXEC +flag. +.IP +Note that the use of this flag is essential in some multithreaded programs, +because using a separate +.BR fcntl (2) +.B F_SETFD +operation to set the +.B FD_CLOEXEC +flag does not suffice to avoid race conditions +where one thread opens a file descriptor and +attempts to set its close-on-exec flag using +.BR fcntl (2) +at the same time as another thread does a +.BR fork (2) +plus +.BR execve (2). +Depending on the order of execution, +the race may lead to the file descriptor returned by +.BR open () +being unintentionally leaked to the program executed by the child process +created by +.BR fork (2). +(This kind of race is in principle possible for any system call +that creates a file descriptor whose close-on-exec flag should be set, +and various other Linux system calls provide an equivalent of the +.BR O_CLOEXEC +flag to deal with this problem.) +.\" This flag fixes only one form of the race condition; +.\" The race can also occur with, for example, file descriptors +.\" returned by accept(), pipe(), etc. +.TP +.B O_CREAT +If +.I pathname +does not exist, create it as a regular file. +.IP +The owner (user ID) of the new file is set to the effective user ID +of the process. +.IP +The group ownership (group ID) of the new file is set either to +the effective group ID of the process (System V semantics) +or to the group ID of the parent directory (BSD semantics). +On Linux, the behavior depends on whether the +set-group-ID mode bit is set on the parent directory: +if that bit is set, then BSD semantics apply; +otherwise, System V semantics apply. +For some filesystems, the behavior also depends on the +.I bsdgroups +and +.I sysvgroups +mount options described in +.BR mount (8)). +.\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and +.\" XFS (since 2.6.14). +.RS +.PP +The +.I mode +argument specifies the file mode bits be applied when a new file is created. +This argument must be supplied when +.B O_CREAT +or +.B O_TMPFILE +is specified in +.IR flags ; +if neither +.B O_CREAT +nor +.B O_TMPFILE +is specified, then +.I mode +is ignored. +The effective mode is modified by the process's +.I umask +in the usual way: in the absence of a default ACL, the mode of the +created file is +.IR "(mode\ &\ ~umask)" . +Note that this mode applies only to future accesses of the +newly created file; the +.BR open () +call that creates a read-only file may well return a read/write +file descriptor. +.PP +The following symbolic constants are provided for +.IR mode : +.TP 9 +.B S_IRWXU +00700 user (file owner) has read, write, and execute permission +.TP +.B S_IRUSR +00400 user has read permission +.TP +.B S_IWUSR +00200 user has write permission +.TP +.B S_IXUSR +00100 user has execute permission +.TP +.B S_IRWXG +00070 group has read, write, and execute permission +.TP +.B S_IRGRP +00040 group has read permission +.TP +.B S_IWGRP +00020 group has write permission +.TP +.B S_IXGRP +00010 group has execute permission +.TP +.B S_IRWXO +00007 others have read, write, and execute permission +.TP +.B S_IROTH +00004 others have read permission +.TP +.B S_IWOTH +00002 others have write permission +.TP +.B S_IXOTH +00001 others have execute permission +.RE +.IP +According to POSIX, the effect when other bits are set in +.I mode +is unspecified. +On Linux, the following bits are also honored in +.IR mode : +.RS +.TP 9 +.B S_ISUID +0004000 set-user-ID bit +.TP +.B S_ISGID +0002000 set-group-ID bit (see +.BR inode (7)). +.TP +.B S_ISVTX +0001000 sticky bit (see +.BR inode (7)). +.RE +.TP +.BR O_DIRECT " (since Linux 2.4.10)" +Try to minimize cache effects of the I/O to and from this file. +In general this will degrade performance, but it is useful in +special situations, such as when applications do their own caching. +File I/O is done directly to/from user-space buffers. +The +.B O_DIRECT +flag on its own makes an effort to transfer data synchronously, +but does not give the guarantees of the +.B O_SYNC +flag that data and necessary metadata are transferred. +To guarantee synchronous I/O, +.B O_SYNC +must be used in addition to +.BR O_DIRECT . +See NOTES below for further discussion. +.IP +A semantically similar (but deprecated) interface for block devices +is described in +.BR raw (8). +.TP +.B O_DIRECTORY +If \fIpathname\fP is not a directory, cause the open to fail. +.\" But see the following and its replies: +.\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2 +.\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail +.\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored. +This flag was added in kernel version 2.1.126, to +avoid denial-of-service problems if +.BR opendir (3) +is called on a +FIFO or tape device. +.TP +.B O_DSYNC +Write operations on the file will complete according to the requirements of +synchronized I/O +.I data +integrity completion. +.IP +By the time +.BR write (2) +(and similar) +return, the output data +has been transferred to the underlying hardware, +along with any file metadata that would be required to retrieve that data +(i.e., as though each +.BR write (2) +was followed by a call to +.BR fdatasync (2)). +.IR "See NOTES below" . +.TP +.B O_EXCL +Ensure that this call creates the file: +if this flag is specified in conjunction with +.BR O_CREAT , +and +.I pathname +already exists, then +.BR open () +fails with the error +.BR EEXIST . +.IP +When these two flags are specified, symbolic links are not followed: +.\" POSIX.1-2001 explicitly requires this behavior. +if +.I pathname +is a symbolic link, then +.BR open () +fails regardless of where the symbolic link points. +.IP +In general, the behavior of +.B O_EXCL +is undefined if it is used without +.BR O_CREAT . +There is one exception: on Linux 2.6 and later, +.B O_EXCL +can be used without +.B O_CREAT +if +.I pathname +refers to a block device. +If the block device is in use by the system (e.g., mounted), +.BR open () +fails with the error +.BR EBUSY . +.IP +On NFS, +.B O_EXCL +is supported only when using NFSv3 or later on kernel 2.6 or later. +In NFS environments where +.B O_EXCL +support is not provided, programs that rely on it +for performing locking tasks will contain a race condition. +Portable programs that want to perform atomic file locking using a lockfile, +and need to avoid reliance on NFS support for +.BR O_EXCL , +can create a unique file on +the same filesystem (e.g., incorporating hostname and PID), and use +.BR link (2) +to make a link to the lockfile. +If +.BR link (2) +returns 0, the lock is successful. +Otherwise, use +.BR stat (2) +on the unique file to check if its link count has increased to 2, +in which case the lock is also successful. +.TP +.B O_LARGEFILE +(LFS) +Allow files whose sizes cannot be represented in an +.I off_t +(but can be represented in an +.IR off64_t ) +to be opened. +The +.B _LARGEFILE64_SOURCE +macro must be defined +(before including +.I any +header files) +in order to obtain this definition. +Setting the +.B _FILE_OFFSET_BITS +feature test macro to 64 (rather than using +.BR O_LARGEFILE ) +is the preferred +method of accessing large files on 32-bit systems (see +.BR feature_test_macros (7)). +.TP +.BR O_NOATIME " (since Linux 2.6.8)" +Do not update the file last access time +.RI ( st_atime +in the inode) +when the file is +.BR read (2). +.IP +This flag can be employed only if one of the following conditions is true: +.RS +.IP * 3 +The effective UID of the process +.\" Strictly speaking: the filesystem UID +matches the owner UID of the file. +.IP * +The calling process has the +.BR CAP_FOWNER +capability in its user namespace and +the owner UID of the file has a mapping in the namespace. +.RE +.IP +This flag is intended for use by indexing or backup programs, +where its use can significantly reduce the amount of disk activity. +This flag may not be effective on all filesystems. +One example is NFS, where the server maintains the access time. +.\" The O_NOATIME flag also affects the treatment of st_atime +.\" by mmap() and readdir(2), MTK, Dec 04. +.TP +.B O_NOCTTY +If +.I pathname +refers to a terminal device\(emsee +.BR tty (4)\(emit +will not become the process's controlling terminal even if the +process does not have one. +.TP +.B O_NOFOLLOW +If \fIpathname\fP is a symbolic link, then the open fails, with the error +.BR ELOOP . +Symbolic links in earlier components of the pathname will still be +followed. +(Note that the +.B ELOOP +error that can occur in this case is indistinguishable from the case where +an open fails because there are too many symbolic links found +while resolving components in the prefix part of the pathname.) +.IP +This flag is a FreeBSD extension, which was added to Linux in version 2.1.126, +and has subsequently been standardized in POSIX.1-2008. +.IP +See also +.BR O_PATH +below. +.\" The headers from glibc 2.0.100 and later include a +.\" definition of this flag; \fIkernels before 2.1.126 will ignore it if +.\" used\fP. +.TP +.BR O_NONBLOCK " or " O_NDELAY +When possible, the file is opened in nonblocking mode. +Neither the +.BR open () +nor any subsequent operations on the file descriptor which is +returned will cause the calling process to wait. +.IP +Note that this flag has no effect for regular files and block devices; +that is, I/O operations will (briefly) block when device activity +is required, regardless of whether +.B O_NONBLOCK +is set. +Since +.B O_NONBLOCK +semantics might eventually be implemented, +applications should not depend upon blocking behavior +when specifying this flag for regular files and block devices. +.IP +For the handling of FIFOs (named pipes), see also +.BR fifo (7). +For a discussion of the effect of +.B O_NONBLOCK +in conjunction with mandatory file locks and with file leases, see +.BR fcntl (2). +.TP +.BR O_PATH " (since Linux 2.6.39)" +.\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd +.\" commit 326be7b484843988afe57566b627fb7a70beac56 +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +.\" +.\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496 +.\" Subject: Re: [PATCH] open(2): document O_PATH +.\" Newsgroups: gmane.linux.man, gmane.linux.kernel +.\" +Obtain a file descriptor that can be used for two purposes: +to indicate a location in the filesystem tree and +to perform operations that act purely at the file descriptor level. +The file itself is not opened, and other file operations (e.g., +.BR read (2), +.BR write (2), +.BR fchmod (2), +.BR fchown (2), +.BR fgetxattr (2), +.BR ioctl (2), +.BR mmap (2)) +fail with the error +.BR EBADF . +.IP +The following operations +.I can +be performed on the resulting file descriptor: +.RS +.IP * 3 +.BR close (2). +.IP * +.BR fchdir (2), +if the file descriptor refers to a directory +(since Linux 3.5). +.\" commit 332a2e1244bd08b9e3ecd378028513396a004a24 +.IP * +.BR fstat (2) +(since Linux 3.6). +.IP * +.\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2 +.BR fstatfs (2) +(since Linux 3.12). +.\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf +.IP * +Duplicating the file descriptor +.RB ( dup (2), +.BR fcntl (2) +.BR F_DUPFD , +etc.). +.IP * +Getting and setting file descriptor flags +.RB ( fcntl (2) +.BR F_GETFD +and +.BR F_SETFD ). +.IP * +Retrieving open file status flags using the +.BR fcntl (2) +.BR F_GETFL +operation: the returned flags will include the bit +.BR O_PATH . +.IP * +Passing the file descriptor as the +.IR dirfd +argument of +.BR openat () +and the other "*at()" system calls. +This includes +.BR linkat (2) +with +.BR AT_EMPTY_PATH +(or via procfs using +.BR AT_SYMLINK_FOLLOW ) +even if the file is not a directory. +.IP * +Passing the file descriptor to another process via a UNIX domain socket +(see +.BR SCM_RIGHTS +in +.BR unix (7)). +.RE +.IP +When +.B O_PATH +is specified in +.IR flags , +flag bits other than +.BR O_CLOEXEC , +.BR O_DIRECTORY , +and +.BR O_NOFOLLOW +are ignored. +.IP +Opening a file or directory with the +.B O_PATH +flag requires no permissions on the object itself +(but does require execute permission on the directories in the path prefix). +Depending on the subsequent operation, +a check for suitable file permissions may be performed (e.g., +.BR fchdir (2) +requires execute permission on the directory referred to +by its file descriptor argument). +By contrast, +obtaining a reference to a filesystem object by opening it with the +.B O_RDONLY +flag requires that the caller have read permission on the object, +even when the subsequent operation (e.g., +.BR fchdir (2), +.BR fstat (2)) +does not require read permission on the object. +.IP +If +.I pathname +is a symbolic link and the +.BR O_NOFOLLOW +flag is also specified, +then the call returns a file descriptor referring to the symbolic link. +This file descriptor can be used as the +.I dirfd +argument in calls to +.BR fchownat (2), +.BR fstatat (2), +.BR linkat (2), +and +.BR readlinkat (2) +with an empty pathname to have the calls operate on the symbolic link. +.IP +If +.I pathname +refers to an automount point that has not yet been triggered, so no +other filesystem is mounted on it, then the call returns a file +descriptor referring to the automount directory without triggering a mount. +.BR fstatfs (2) +can then be used to determine if it is, in fact, an untriggered +automount point +.RB ( ".f_type == AUTOFS_SUPER_MAGIC" ). +.IP +One use of +.B O_PATH +for regular files is to provide the equivalent of POSIX.1's +.B O_EXEC +functionality. +This permits us to open a file for which we have execute +permission but not read permission, and then execute that file, +with steps something like the following: +.IP +.in +4n +.EX +char buf[PATH_MAX]; +fd = open("some_prog", O_PATH); +snprintf(buf, "/proc/self/fd/%d", fd); +execl(buf, "some_prog", (char *) NULL); +.EE +.in +.IP +An +.B O_PATH +file descriptor can also be passed as the argument of +.BR fexecve (3). +.TP +.B O_SYNC +Write operations on the file will complete according to the requirements of +synchronized I/O +.I file +integrity completion +(by contrast with the +synchronized I/O +.I data +integrity completion +provided by +.BR O_DSYNC .) +.IP +By the time +.BR write (2) +(or similar) +returns, the output data and associated file metadata +have been transferred to the underlying hardware +(i.e., as though each +.BR write (2) +was followed by a call to +.BR fsync (2)). +.IR "See NOTES below" . +.TP +.BR O_TMPFILE " (since Linux 3.11)" +.\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e +.\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e +.\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd +Create an unnamed temporary regular file. +The +.I pathname +argument specifies a directory; +an unnamed inode will be created in that directory's filesystem. +Anything written to the resulting file will be lost when +the last file descriptor is closed, unless the file is given a name. +.IP +.B O_TMPFILE +must be specified with one of +.B O_RDWR +or +.B O_WRONLY +and, optionally, +.BR O_EXCL . +If +.B O_EXCL +is not specified, then +.BR linkat (2) +can be used to link the temporary file into the filesystem, making it +permanent, using code like the following: +.IP +.in +4n +.EX +char path[PATH_MAX]; +fd = open("/path/to/dir", O_TMPFILE | O_RDWR, + S_IRUSR | S_IWUSR); + +/* File I/O on 'fd'... */ + +snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd); +linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file", + AT_SYMLINK_FOLLOW); +.EE +.in +.IP +In this case, +the +.BR open () +.I mode +argument determines the file permission mode, as with +.BR O_CREAT . +.IP +Specifying +.B O_EXCL +in conjunction with +.B O_TMPFILE +prevents a temporary file from being linked into the filesystem +in the above manner. +(Note that the meaning of +.B O_EXCL +in this case is different from the meaning of +.B O_EXCL +otherwise.) +.IP +There are two main use cases for +.\" Inspired by http://lwn.net/Articles/559147/ +.BR O_TMPFILE : +.RS +.IP * 3 +Improved +.BR tmpfile (3) +functionality: race-free creation of temporary files that +(1) are automatically deleted when closed; +(2) can never be reached via any pathname; +(3) are not subject to symlink attacks; and +(4) do not require the caller to devise unique names. +.IP * +Creating a file that is initially invisible, which is then populated +with data and adjusted to have appropriate filesystem attributes +.RB ( fchown (2), +.BR fchmod (2), +.BR fsetxattr (2), +etc.) +before being atomically linked into the filesystem +in a fully formed state (using +.BR linkat (2) +as described above). +.RE +.IP +.B O_TMPFILE +requires support by the underlying filesystem; +only a subset of Linux filesystems provide that support. +In the initial implementation, support was provided in +the ext2, ext3, ext4, UDF, Minix, and shmem filesystems. +.\" To check for support, grep for "tmpfile" in kernel sources +Support for other filesystems has subsequently been added as follows: +XFS (Linux 3.15); +.\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788 +.\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe +Btrfs (Linux 3.16); +.\" commit ef3b9af50bfa6a1f02cd7b3f5124b712b1ba3e3c +F2FS (Linux 3.16); +.\" commit 50732df02eefb39ab414ef655979c2c9b64ad21c +and ubifs (Linux 4.9) +.TP +.B O_TRUNC +If the file already exists and is a regular file and the access mode allows +writing (i.e., is +.B O_RDWR +or +.BR O_WRONLY ) +it will be truncated to length 0. +If the file is a FIFO or terminal device file, the +.B O_TRUNC +flag is ignored. +Otherwise, the effect of +.B O_TRUNC +is unspecified. +.SS creat() +A call to +.BR creat () +is equivalent to calling +.BR open () +with +.I flags +equal to +.BR O_CREAT|O_WRONLY|O_TRUNC . +.SS openat() +The +.BR openat () +system call operates in exactly the same way as +.BR open (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR open () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR open ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.SH RETURN VALUE +.BR open (), +.BR openat (), +and +.BR creat () +return the new file descriptor, or \-1 if an error occurred +(in which case, +.I errno +is set appropriately). +.SH ERRORS +.BR open (), +.BR openat (), +and +.BR creat () +can fail with the following errors: +.TP +.B EACCES +The requested access to the file is not allowed, or search permission +is denied for one of the directories in the path prefix of +.IR pathname , +or the file did not exist yet and write access to the parent directory +is not allowed. +(See also +.BR path_resolution (7).) +.TP +.B EDQUOT +Where +.B O_CREAT +is specified, the file does not exist, and the user's quota of disk +blocks or inodes on the filesystem has been exhausted. +.TP +.B EEXIST +.I pathname +already exists and +.BR O_CREAT " and " O_EXCL +were used. +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EFBIG +See +.BR EOVERFLOW . +.TP +.B EINTR +While blocked waiting to complete an open of a slow device +(e.g., a FIFO; see +.BR fifo (7)), +the call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The filesystem does not support the +.BR O_DIRECT +flag. +See +.BR NOTES +for more information. +.TP +.B EINVAL +Invalid value in +.\" In particular, __O_TMPFILE instead of O_TMPFILE +.IR flags . +.TP +.B EINVAL +.B O_TMPFILE +was specified in +.IR flags , +but neither +.B O_WRONLY +nor +.B O_RDWR +was specified. +.TP +.B EINVAL +.B O_CREAT +was specified in +.I flags +and the final component ("basename") of the new file's +.I pathname +is invalid +(e.g., it contains characters not permitted by the underlying filesystem). +.TP +.B EISDIR +.I pathname +refers to a directory and the access requested involved writing +(that is, +.B O_WRONLY +or +.B O_RDWR +is set). +.TP +.B EISDIR +.I pathname +refers to an existing directory, +.B O_TMPFILE +and one of +.B O_WRONLY +or +.B O_RDWR +were specified in +.IR flags , +but this kernel version does not provide the +.B O_TMPFILE +functionality. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ELOOP +.I pathname +was a symbolic link, and +.I flags +specified +.BR O_NOFOLLOW +but not +.BR O_PATH . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached +(see the description of +.BR RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B ENAMETOOLONG +.I pathname +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENODEV +.I pathname +refers to a device special file and no corresponding device exists. +(This is a Linux kernel bug; in this situation +.B ENXIO +must be returned.) +.TP +.B ENOENT +.B O_CREAT +is not set and the named file does not exist. +Or, a directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOENT +.I pathname +refers to a nonexistent directory, +.B O_TMPFILE +and one of +.B O_WRONLY +or +.B O_RDWR +were specified in +.IR flags , +but this kernel version does not provide the +.B O_TMPFILE +functionality. +.TP +.B ENOMEM +The named file is a FIFO, +but memory for the FIFO buffer can't be allocated because +the per-user hard limit on memory allocation for pipes has been reached +and the caller is not privileged; see +.BR pipe (7). +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +.I pathname +was to be created but the device containing +.I pathname +has no room for the new file. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and +.I pathname +was not a directory. +.TP +.B ENXIO +.BR O_NONBLOCK " | " O_WRONLY +is set, the named file is a FIFO, and +no process has the FIFO open for reading. +.TP +.B ENXIO +The file is a device special file and no corresponding device exists. +.TP +.BR EOPNOTSUPP +The filesystem containing +.I pathname +does not support +.BR O_TMPFILE . +.TP +.B EOVERFLOW +.I pathname +refers to a regular file that is too large to be opened. +The usual scenario here is that an application compiled +on a 32-bit platform without +.I -D_FILE_OFFSET_BITS=64 +tried to open a file whose size exceeds +.I (1<<31)-1 +bytes; +see also +.B O_LARGEFILE +above. +This is the error specified by POSIX.1; +in kernels before 2.6.24, Linux gave the error +.B EFBIG +for this case. +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253 +.\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW" +.\" Reported 2006-10-03 +.TP +.B EPERM +The +.B O_NOATIME +flag was specified, but the effective user ID of the caller +.\" Strictly speaking, it's the filesystem UID... (MTK) +did not match the owner of the file and the caller was not privileged. +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem and write access was +requested. +.TP +.B ETXTBSY +.I pathname +refers to an executable image which is currently being executed and +write access was requested. +.TP +.B EWOULDBLOCK +The +.B O_NONBLOCK +flag was specified, and an incompatible lease was held on the file +(see +.BR fcntl (2)). +.PP +The following additional errors can occur for +.BR openat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I pathname +is a relative pathname and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR openat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR open (), +.BR creat () +SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. +.PP +.BR openat (): +POSIX.1-2008. +.PP +The +.BR O_DIRECT , +.BR O_NOATIME , +.BR O_PATH , +and +.BR O_TMPFILE +flags are Linux-specific. +One must define +.B _GNU_SOURCE +to obtain their definitions. +.PP +The +.BR O_CLOEXEC , +.BR O_DIRECTORY , +and +.BR O_NOFOLLOW +flags are not specified in POSIX.1-2001, +but are specified in POSIX.1-2008. +Since glibc 2.12, one can obtain their definitions by defining either +.B _POSIX_C_SOURCE +with a value greater than or equal to 200809L or +.BR _XOPEN_SOURCE +with a value greater than or equal to 700. +In glibc 2.11 and earlier, one obtains the definitions by defining +.BR _GNU_SOURCE . +.PP +As noted in +.BR feature_test_macros (7), +feature test macros such as +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +and +.B _GNU_SOURCE +must be defined before including +.I any +header files. +.SH NOTES +Under Linux, the +.B O_NONBLOCK +flag indicates that one wants to open +but does not necessarily have the intention to read or write. +This is typically used to open devices in order to get a file descriptor +for use with +.BR ioctl (2). +.PP +The (undefined) effect of +.B O_RDONLY | O_TRUNC +varies among implementations. +On many systems the file is actually truncated. +.\" Linux 2.0, 2.5: truncate +.\" Solaris 5.7, 5.8: truncate +.\" Irix 6.5: truncate +.\" Tru64 5.1B: truncate +.\" HP-UX 11.22: truncate +.\" FreeBSD 4.7: truncate +.PP +Note that +.BR open () +can open device special files, but +.BR creat () +cannot create them; use +.BR mknod (2) +instead. +.PP +If the file is newly created, its +.IR st_atime , +.IR st_ctime , +.I st_mtime +fields +(respectively, time of last access, time of last status change, and +time of last modification; see +.BR stat (2)) +are set +to the current time, and so are the +.I st_ctime +and +.I st_mtime +fields of the +parent directory. +Otherwise, if the file is modified because of the +.B O_TRUNC +flag, its +.I st_ctime +and +.I st_mtime +fields are set to the current time. +.PP +The files in the +.I /proc/[pid]/fd +directory show the open file descriptors of the process with the PID +.IR pid . +The files in the +.I /proc/[pid]/fdinfo +directory show even more information about these files descriptors. +See +.BR proc (5) +for further details of both of these directories. +.\" +.\" +.SS Open file descriptions +The term open file description is the one used by POSIX to refer to the +entries in the system-wide table of open files. +In other contexts, this object is +variously also called an "open file object", +a "file handle", an "open file table entry", +or\(emin kernel-developer parlance\(ema +.IR "struct file" . +.PP +When a file descriptor is duplicated (using +.BR dup (2) +or similar), +the duplicate refers to the same open file description +as the original file descriptor, +and the two file descriptors consequently share +the file offset and file status flags. +Such sharing can also occur between processes: +a child process created via +.BR fork (2) +inherits duplicates of its parent's file descriptors, +and those duplicates refer to the same open file descriptions. +.PP +Each +.BR open () +of a file creates a new open file description; +thus, there may be multiple open file descriptions +corresponding to a file inode. +.PP +On Linux, one can use the +.BR kcmp (2) +.B KCMP_FILE +operation to test whether two file descriptors +(in the same process or in two different processes) +refer to the same open file description. +.\" +.\" +.SS Synchronized I/O +The POSIX.1-2008 "synchronized I/O" option +specifies different variants of synchronized I/O, +and specifies the +.BR open () +flags +.BR O_SYNC , +.BR O_DSYNC , +and +.BR O_RSYNC +for controlling the behavior. +Regardless of whether an implementation supports this option, +it must at least support the use of +.BR O_SYNC +for regular files. +.PP +Linux implements +.BR O_SYNC +and +.BR O_DSYNC , +but not +.BR O_RSYNC . +(Somewhat incorrectly, glibc defines +.BR O_RSYNC +to have the same value as +.BR O_SYNC .) +.PP +.BR O_SYNC +provides synchronized I/O +.I file +integrity completion, +meaning write operations will flush data and all associated metadata +to the underlying hardware. +.BR O_DSYNC +provides synchronized I/O +.I data +integrity completion, +meaning write operations will flush data +to the underlying hardware, +but will only flush metadata updates that are required +to allow a subsequent read operation to complete successfully. +Data integrity completion can reduce the number of disk operations +that are required for applications that don't need the guarantees +of file integrity completion. +.PP +To understand the difference between the two types of completion, +consider two pieces of file metadata: +the file last modification timestamp +.RI ( st_mtime ) +and the file length. +All write operations will update the last file modification timestamp, +but only writes that add data to the end of the +file will change the file length. +The last modification timestamp is not needed to ensure that +a read completes successfully, but the file length is. +Thus, +.BR O_DSYNC +would only guarantee to flush updates to the file length metadata +(whereas +.BR O_SYNC +would also always flush the last modification timestamp metadata). +.PP +Before Linux 2.6.33, Linux implemented only the +.BR O_SYNC +flag for +.BR open (). +However, when that flag was specified, +most filesystems actually provided the equivalent of synchronized I/O +.I data +integrity completion (i.e., +.BR O_SYNC +was actually implemented as the equivalent of +.BR O_DSYNC ). +.PP +Since Linux 2.6.33, proper +.BR O_SYNC +support is provided. +However, to ensure backward binary compatibility, +.BR O_DSYNC +was defined with the same value as the historical +.BR O_SYNC , +and +.BR O_SYNC +was defined as a new (two-bit) flag value that includes the +.BR O_DSYNC +flag value. +This ensures that applications compiled against +new headers get at least +.BR O_DSYNC +semantics on pre-2.6.33 kernels. +.\" +.SS C library/kernel differences +Since version 2.26, +the glibc wrapper function for +.BR open () +employs the +.BR openat () +system call, rather than the kernel's +.BR open () +system call. +For certain architectures, this is also true in glibc versions before 2.26. +.\" +.SS NFS +There are many infelicities in the protocol underlying NFS, affecting +amongst others +.BR O_SYNC " and " O_NDELAY . +.PP +On NFS filesystems with UID mapping enabled, +.BR open () +may +return a file descriptor but, for example, +.BR read (2) +requests are denied +with \fBEACCES\fP. +This is because the client performs +.BR open () +by checking the +permissions, but UID mapping is performed by the server upon +read and write requests. +.\" +.\" +.SS FIFOs +Opening the read or write end of a FIFO blocks until the other +end is also opened (by another process or thread). +See +.BR fifo (7) +for further details. +.\" +.\" +.SS File access mode +Unlike the other values that can be specified in +.IR flags , +the +.I "access mode" +values +.BR O_RDONLY ", " O_WRONLY ", and " O_RDWR +do not specify individual bits. +Rather, they define the low order two bits of +.IR flags , +and are defined respectively as 0, 1, and 2. +In other words, the combination +.B "O_RDONLY | O_WRONLY" +is a logical error, and certainly does not have the same meaning as +.BR O_RDWR . +.PP +Linux reserves the special, nonstandard access mode 3 (binary 11) in +.I flags +to mean: +check for read and write permission on the file and return a file descriptor +that can't be used for reading or writing. +This nonstandard access mode is used by some Linux drivers to return a +file descriptor that is to be used only for device-specific +.BR ioctl (2) +operations. +.\" See for example util-linux's disk-utils/setfdprm.c +.\" For some background on access mode 3, see +.\" http://thread.gmane.org/gmane.linux.kernel/653123 +.\" "[RFC] correct flags to f_mode conversion in __dentry_open" +.\" LKML, 12 Mar 2008 +.\" +.\" +.SS Rationale for openat() and other "directory file descriptor" APIs +.BR openat () +and the other system calls and library functions that take +a directory file descriptor argument +(i.e., +.BR execveat (2), +.BR faccessat (2), +.BR fanotify_mark (2), +.BR fchmodat (2), +.BR fchownat (2), +.BR fstatat (2), +.BR futimesat (2), +.BR linkat (2), +.BR mkdirat (2), +.BR mknodat (2), +.BR name_to_handle_at (2), +.BR readlinkat (2), +.BR renameat (2), +.BR statx (2), +.BR symlinkat (2), +.BR unlinkat (2), +.BR utimensat (2), +.BR mkfifoat (3), +and +.BR scandirat (3)) +address two problems with the older interfaces that preceded them. +Here, the explanation is in terms of the +.BR openat () +call, but the rationale is analogous for the other interfaces. +.PP +First, +.BR openat () +allows an application to avoid race conditions that could +occur when using +.BR open () +to open files in directories other than the current working directory. +These race conditions result from the fact that some component +of the directory prefix given to +.BR open () +could be changed in parallel with the call to +.BR open (). +Suppose, for example, that we wish to create the file +.I dir1/dir2/xxx.dep +if the file +.I dir1/dir2/xxx +exists. +The problem is that between the existence check and the file-creation step, +.I dir1 +or +.I dir2 +(which might be symbolic links) +could be modified to point to a different location. +Such races can be avoided by +opening a file descriptor for the target directory, +and then specifying that file descriptor as the +.I dirfd +argument of (say) +.BR fstatat (2) +and +.BR openat (). +The use of the +.I dirfd +file descriptor also has other benefits: +.IP * 3 +the file descriptor is a stable reference to the directory, +even if the directory is renamed; and +.IP * +the open file descriptor prevents the underlying filesystem from +being dismounted, +just as when a process has a current working directory on a filesystem. +.PP +Second, +.BR openat () +allows the implementation of a per-thread "current working +directory", via file descriptor(s) maintained by the application. +(This functionality can also be obtained by tricks based +on the use of +.IR /proc/self/fd/ dirfd, +but less efficiently.) +.\" +.\" +.SS O_DIRECT +.PP +The +.B O_DIRECT +flag may impose alignment restrictions on the length and address +of user-space buffers and the file offset of I/Os. +In Linux alignment +restrictions vary by filesystem and kernel version and might be +absent entirely. +However there is currently no filesystem\-independent +interface for an application to discover these restrictions for a given +file or filesystem. +Some filesystems provide their own interfaces +for doing so, for example the +.B XFS_IOC_DIOINFO +operation in +.BR xfsctl (3). +.PP +Under Linux 2.4, transfer sizes, and the alignment of the user buffer +and the file offset must all be multiples of the logical block size +of the filesystem. +Since Linux 2.6.0, alignment to the logical block size of the +underlying storage (typically 512 bytes) suffices. +The logical block size can be determined using the +.BR ioctl (2) +.B BLKSSZGET +operation or from the shell using the command: +.PP +.EX + blockdev \-\-getss +.EE +.PP +.B O_DIRECT +I/Os should never be run concurrently with the +.BR fork (2) +system call, +if the memory buffer is a private mapping +(i.e., any mapping created with the +.BR mmap (2) +.BR MAP_PRIVATE +flag; +this includes memory allocated on the heap and statically allocated buffers). +Any such I/Os, whether submitted via an asynchronous I/O interface or from +another thread in the process, +should be completed before +.BR fork (2) +is called. +Failure to do so can result in data corruption and undefined behavior in +parent and child processes. +This restriction does not apply when the memory buffer for the +.B O_DIRECT +I/Os was created using +.BR shmat (2) +or +.BR mmap (2) +with the +.B MAP_SHARED +flag. +Nor does this restriction apply when the memory buffer has been advised as +.B MADV_DONTFORK +with +.BR madvise (2), +ensuring that it will not be available +to the child after +.BR fork (2). +.PP +The +.B O_DIRECT +flag was introduced in SGI IRIX, where it has alignment +restrictions similar to those of Linux 2.4. +IRIX has also a +.BR fcntl (2) +call to query appropriate alignments, and sizes. +FreeBSD 4.x introduced +a flag of the same name, but without alignment restrictions. +.PP +.B O_DIRECT +support was added under Linux in kernel version 2.4.10. +Older Linux kernels simply ignore this flag. +Some filesystems may not implement the flag, in which case +.BR open () +fails with the error +.B EINVAL +if it is used. +.PP +Applications should avoid mixing +.B O_DIRECT +and normal I/O to the same file, +and especially to overlapping byte regions in the same file. +Even when the filesystem correctly handles the coherency issues in +this situation, overall I/O throughput is likely to be slower than +using either mode alone. +Likewise, applications should avoid mixing +.BR mmap (2) +of files with direct I/O to the same files. +.PP +The behavior of +.B O_DIRECT +with NFS will differ from local filesystems. +Older kernels, or +kernels configured in certain ways, may not support this combination. +The NFS protocol does not support passing the flag to the server, so +.B O_DIRECT +I/O will bypass the page cache only on the client; the server may +still cache the I/O. +The client asks the server to make the I/O +synchronous to preserve the synchronous semantics of +.BR O_DIRECT . +Some servers will perform poorly under these circumstances, especially +if the I/O size is small. +Some servers may also be configured to +lie to clients about the I/O having reached stable storage; this +will avoid the performance penalty at some risk to data integrity +in the event of server power failure. +The Linux NFS client places no alignment restrictions on +.B O_DIRECT +I/O. +.PP +In summary, +.B O_DIRECT +is a potentially powerful tool that should be used with caution. +It is recommended that applications treat use of +.B O_DIRECT +as a performance option which is disabled by default. +.PP +.RS +"The thing that has always disturbed me about O_DIRECT is that the whole +interface is just stupid, and was probably designed by a deranged monkey +on some serious mind-controlling substances."\(emLinus +.RE +.SH BUGS +Currently, it is not possible to enable signal-driven +I/O by specifying +.B O_ASYNC +when calling +.BR open (); +use +.BR fcntl (2) +to enable this flag. +.\" FIXME . Check bugzilla report on open(O_ASYNC) +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 +.PP +One must check for two different error codes, +.B EISDIR +and +.BR ENOENT , +when trying to determine whether the kernel supports +.B O_TMPFILE +functionality. +.PP +When both +.B O_CREAT +and +.B O_DIRECTORY +are specified in +.IR flags +and the file specified by +.I pathname +does not exist, +.BR open () +will create a regular file (i.e., +.B O_DIRECTORY +is ignored). +.SH SEE ALSO +.BR chmod (2), +.BR chown (2), +.BR close (2), +.BR dup (2), +.BR fcntl (2), +.BR link (2), +.BR lseek (2), +.BR mknod (2), +.BR mmap (2), +.BR mount (2), +.BR open_by_handle_at (2), +.BR read (2), +.BR socket (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR write (2), +.BR fopen (3), +.BR acl (5), +.BR fifo (7), +.BR inode (7), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2 new file mode 100644 index 0000000..7f7243c --- /dev/null +++ b/man2/open_by_handle_at.2 @@ -0,0 +1,775 @@ +.\" Copyright (c) 2014 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH OPEN_BY_HANDLE_AT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +name_to_handle_at, open_by_handle_at \- obtain handle +for a pathname and open file via a handle +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.B #include +.B #include +.PP +.BI "int name_to_handle_at(int " dirfd ", const char *" pathname , +.BI " struct file_handle *" handle , +.BI " int *" mount_id ", int " flags ); +.PP +.BI "int open_by_handle_at(int " mount_fd ", struct file_handle *" handle , +.BI " int " flags ); +.fi +.SH DESCRIPTION +The +.BR name_to_handle_at () +and +.BR open_by_handle_at () +system calls split the functionality of +.BR openat (2) +into two parts: +.BR name_to_handle_at () +returns an opaque handle that corresponds to a specified file; +.BR open_by_handle_at () +opens the file corresponding to a handle returned by a previous call to +.BR name_to_handle_at () +and returns an open file descriptor. +.\" +.\" +.SS name_to_handle_at() +The +.BR name_to_handle_at () +system call returns a file handle and a mount ID corresponding to +the file specified by the +.IR dirfd +and +.IR pathname +arguments. +The file handle is returned via the argument +.IR handle , +which is a pointer to a structure of the following form: +.PP +.in +4n +.EX +struct file_handle { + unsigned int handle_bytes; /* Size of f_handle [in, out] */ + int handle_type; /* Handle type [out] */ + unsigned char f_handle[0]; /* File identifier (sized by + caller) [out] */ +}; +.EE +.in +.PP +It is the caller's responsibility to allocate the structure +with a size large enough to hold the handle returned in +.IR f_handle . +Before the call, the +.IR handle_bytes +field should be initialized to contain the allocated size for +.IR f_handle . +(The constant +.BR MAX_HANDLE_SZ , +defined in +.IR , +specifies the maximum expected size for a file handle. +It is not a +guaranteed upper limit as future filesystems may require more space.) +Upon successful return, the +.IR handle_bytes +field is updated to contain the number of bytes actually written to +.IR f_handle . +.PP +The caller can discover the required size for the +.I file_handle +structure by making a call in which +.IR handle->handle_bytes +is zero; +in this case, the call fails with the error +.BR EOVERFLOW +and +.IR handle->handle_bytes +is set to indicate the required size; +the caller can then use this information to allocate a structure +of the correct size (see EXAMPLE below). +Some care is needed here as +.BR EOVERFLOW +can also indicate that no file handle is available for this particular +name in a filesystem which does normally support file-handle lookup. +This case can be detected when the +.B EOVERFLOW +error is returned without +.I handle_bytes +being increased. +.PP +Other than the use of the +.IR handle_bytes +field, the caller should treat the +.IR file_handle +structure as an opaque data type: the +.IR handle_type +and +.IR f_handle +fields are needed only by a subsequent call to +.BR open_by_handle_at (). +.PP +The +.I flags +argument is a bit mask constructed by ORing together zero or more of +.BR AT_EMPTY_PATH +and +.BR AT_SYMLINK_FOLLOW , +described below. +.PP +Together, the +.I pathname +and +.I dirfd +arguments identify the file for which a handle is to be obtained. +There are four distinct cases: +.IP * 3 +If +.I pathname +is a nonempty string containing an absolute pathname, +then a handle is returned for the file referred to by that pathname. +In this case, +.IR dirfd +is ignored. +.IP * +If +.I pathname +is a nonempty string containing a relative pathname and +.IR dirfd +has the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working directory of the caller, +and a handle is returned for the file to which it refers. +.IP * +If +.I pathname +is a nonempty string containing a relative pathname and +.IR dirfd +is a file descriptor referring to a directory, then +.I pathname +is interpreted relative to the directory referred to by +.IR dirfd , +and a handle is returned for the file to which it refers. +(See +.BR openat (2) +for an explanation of why "directory file descriptors" are useful.) +.IP * +If +.I pathname +is an empty string and +.I flags +specifies the value +.BR AT_EMPTY_PATH , +then +.IR dirfd +can be an open file descriptor referring to any type of file, +or +.BR AT_FDCWD , +meaning the current working directory, +and a handle is returned for the file to which it refers. +.PP +The +.I mount_id +argument returns an identifier for the filesystem +mount that corresponds to +.IR pathname . +This corresponds to the first field in one of the records in +.IR /proc/self/mountinfo . +Opening the pathname in the fifth field of that record yields a file +descriptor for the mount point; +that file descriptor can be used in a subsequent call to +.BR open_by_handle_at (). +.I mount_id +is returned both for a successful call and for a call that results +in the error +.BR EOVERFLOW . +.PP +By default, +.BR name_to_handle_at () +does not dereference +.I pathname +if it is a symbolic link, and thus returns a handle for the link itself. +If +.B AT_SYMLINK_FOLLOW +is specified in +.IR flags , +.I pathname +is dereferenced if it is a symbolic link +(so that the call returns a handle for the file referred to by the link). +.PP +.BR name_to_handle_at () +does not trigger a mount when the final component of the path is an +automount point. +When a filesystem supports both file handles and +automount points, a +.BR name_to_handle_at () +call on an automount point will return with error +.BR EOVERFLOW +without having increased +.IR handle_bytes . +This can happen since Linux 4.13 +.\" commit 20fa19027286983ab2734b5910c4a687436e0c31 +with NFS when accessing a directory +which is on a separate filesystem on the server. +In this case, the automount can be triggered by adding a "/" to the end +of the path. +.SS open_by_handle_at() +The +.BR open_by_handle_at () +system call opens the file referred to by +.IR handle , +a file handle returned by a previous call to +.BR name_to_handle_at (). +.PP +The +.IR mount_fd +argument is a file descriptor for any object (file, directory, etc.) +in the mounted filesystem with respect to which +.IR handle +should be interpreted. +The special value +.B AT_FDCWD +can be specified, meaning the current working directory of the caller. +.PP +The +.I flags +argument +is as for +.BR open (2). +If +.I handle +refers to a symbolic link, the caller must specify the +.B O_PATH +flag, and the symbolic link is not dereferenced; the +.B O_NOFOLLOW +flag, if specified, is ignored. +.PP +The caller must have the +.B CAP_DAC_READ_SEARCH +capability to invoke +.BR open_by_handle_at (). +.SH RETURN VALUE +On success, +.BR name_to_handle_at () +returns 0, +and +.BR open_by_handle_at () +returns a nonnegative file descriptor. +.PP +In the event of an error, both system calls return \-1 and set +.I errno +to indicate the cause of the error. +.SH ERRORS +.BR name_to_handle_at () +and +.BR open_by_handle_at () +can fail for the same errors as +.BR openat (2). +In addition, they can fail with the errors noted below. +.PP +.BR name_to_handle_at () +can fail with the following errors: +.TP +.B EFAULT +.IR pathname , +.IR mount_id , +or +.IR handle +points outside your accessible address space. +.TP +.B EINVAL +.I flags +includes an invalid bit value. +.TP +.B EINVAL +.IR handle\->handle_bytes +is greater than +.BR MAX_HANDLE_SZ . +.TP +.B ENOENT +.I pathname +is an empty string, but +.BR AT_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOTDIR +The file descriptor supplied in +.I dirfd +does not refer to a directory, +and it is not the case that both +.I flags +includes +.BR AT_EMPTY_PATH +and +.I pathname +is an empty string. +.TP +.B EOPNOTSUPP +The filesystem does not support decoding of a pathname to a file handle. +.TP +.B EOVERFLOW +The +.I handle->handle_bytes +value passed into the call was too small. +When this error occurs, +.I handle->handle_bytes +is updated to indicate the required size for the handle. +.\" +.\" +.PP +.BR open_by_handle_at () +can fail with the following errors: +.TP +.B EBADF +.IR mount_fd +is not an open file descriptor. +.TP +.B EFAULT +.IR handle +points outside your accessible address space. +.TP +.B EINVAL +.I handle->handle_bytes +is greater than +.BR MAX_HANDLE_SZ +or is equal to zero. +.TP +.B ELOOP +.I handle +refers to a symbolic link, but +.B O_PATH +was not specified in +.IR flags . +.TP +.B EPERM +The caller does not have the +.BR CAP_DAC_READ_SEARCH +capability. +.TP +.B ESTALE +The specified +.I handle +is not valid. +This error will occur if, for example, the file has been deleted. +.SH VERSIONS +These system calls first appeared in Linux 2.6.39. +Library support is provided in glibc since version 2.14. +.SH CONFORMING TO +These system calls are nonstandard Linux extensions. +.PP +FreeBSD has a broadly similar pair of system calls in the form of +.BR getfh () +and +.BR openfh (). +.SH NOTES +A file handle can be generated in one process using +.BR name_to_handle_at () +and later used in a different process that calls +.BR open_by_handle_at (). +.PP +Some filesystem don't support the translation of pathnames to +file handles, for example, +.IR /proc , +.IR /sys , +and various network filesystems. +.PP +A file handle may become invalid ("stale") if a file is deleted, +or for other filesystem-specific reasons. +Invalid handles are notified by an +.B ESTALE +error from +.BR open_by_handle_at (). +.PP +These system calls are designed for use by user-space file servers. +For example, a user-space NFS server might generate a file handle +and pass it to an NFS client. +Later, when the client wants to open the file, +it could pass the handle back to the server. +.\" https://lwn.net/Articles/375888/ +.\" "Open by handle" - Jonathan Corbet, 2010-02-23 +This sort of functionality allows a user-space file server to operate in +a stateless fashion with respect to the files it serves. +.PP +If +.I pathname +refers to a symbolic link and +.IR flags +does not specify +.BR AT_SYMLINK_FOLLOW , +then +.BR name_to_handle_at () +returns a handle for the link (rather than the file to which it refers). +.\" commit bcda76524cd1fa32af748536f27f674a13e56700 +The process receiving the handle can later perform operations +on the symbolic link by converting the handle to a file descriptor using +.BR open_by_handle_at () +with the +.BR O_PATH +flag, and then passing the file descriptor as the +.IR dirfd +argument in system calls such as +.BR readlinkat (2) +and +.BR fchownat (2). +.SS Obtaining a persistent filesystem ID +The mount IDs in +.IR /proc/self/mountinfo +can be reused as filesystems are unmounted and mounted. +Therefore, the mount ID returned by +.BR name_to_handle_at () +(in +.IR *mount_id ) +should not be treated as a persistent identifier +for the corresponding mounted filesystem. +However, an application can use the information in the +.I mountinfo +record that corresponds to the mount ID +to derive a persistent identifier. +.PP +For example, one can use the device name in the fifth field of the +.I mountinfo +record to search for the corresponding device UUID via the symbolic links in +.IR /dev/disks/by-uuid . +(A more comfortable way of obtaining the UUID is to use the +.\" e.g., http://stackoverflow.com/questions/6748429/using-libblkid-to-find-uuid-of-a-partition +.BR libblkid (3) +library.) +That process can then be reversed, +using the UUID to look up the device name, +and then obtaining the corresponding mount point, +in order to produce the +.IR mount_fd +argument used by +.BR open_by_handle_at (). +.SH EXAMPLE +The two programs below demonstrate the use of +.BR name_to_handle_at () +and +.BR open_by_handle_at (). +The first program +.RI ( t_name_to_handle_at.c ) +uses +.BR name_to_handle_at () +to obtain the file handle and mount ID +for the file specified in its command-line argument; +the handle and mount ID are written to standard output. +.PP +The second program +.RI ( t_open_by_handle_at.c ) +reads a mount ID and file handle from standard input. +The program then employs +.BR open_by_handle_at () +to open the file using that handle. +If an optional command-line argument is supplied, then the +.IR mount_fd +argument for +.BR open_by_handle_at () +is obtained by opening the directory named in that argument. +Otherwise, +.IR mount_fd +is obtained by scanning +.IR /proc/self/mountinfo +to find a record whose mount ID matches the mount ID +read from standard input, +and the mount directory specified in that record is opened. +(These programs do not deal with the fact that mount IDs are not persistent.) +.PP +The following shell session demonstrates the use of these two programs: +.PP +.in +4n +.EX +$ \fBecho 'Can you please think about it?' > cecilia.txt\fP +$ \fB./t_name_to_handle_at cecilia.txt > fh\fP +$ \fB./t_open_by_handle_at < fh\fP +open_by_handle_at: Operation not permitted +$ \fBsudo ./t_open_by_handle_at < fh\fP # Need CAP_SYS_ADMIN +Read 31 bytes +$ \fBrm cecilia.txt\fP +.EE +.in +.PP +Now we delete and (quickly) re-create the file so that +it has the same content and (by chance) the same inode. +Nevertheless, +.BR open_by_handle_at () +.\" Christoph Hellwig: That's why the file handles contain a generation +.\" counter that gets incremented in this case. +recognizes that the original file referred to by the file handle +no longer exists. +.PP +.in +4n +.EX +$ \fBstat \-\-printf="%i\\n" cecilia.txt\fP # Display inode number +4072121 +$ \fBrm cecilia.txt\fP +$ \fBecho 'Can you please think about it?' > cecilia.txt\fP +$ \fBstat \-\-printf="%i\\n" cecilia.txt\fP # Check inode number +4072121 +$ \fBsudo ./t_open_by_handle_at < fh\fP +open_by_handle_at: Stale NFS file handle +.EE +.in +.SS Program source: t_name_to_handle_at.c +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + struct file_handle *fhp; + int mount_id, fhsize, flags, dirfd, j; + char *pathname; + + if (argc != 2) { + fprintf(stderr, "Usage: %s pathname\\n", argv[0]); + exit(EXIT_FAILURE); + } + + pathname = argv[1]; + + /* Allocate file_handle structure */ + + fhsize = sizeof(*fhp); + fhp = malloc(fhsize); + if (fhp == NULL) + errExit("malloc"); + + /* Make an initial call to name_to_handle_at() to discover + the size required for file handle */ + + dirfd = AT_FDCWD; /* For name_to_handle_at() calls */ + flags = 0; /* For name_to_handle_at() calls */ + fhp\->handle_bytes = 0; + if (name_to_handle_at(dirfd, pathname, fhp, + &mount_id, flags) != \-1 || errno != EOVERFLOW) { + fprintf(stderr, "Unexpected result from name_to_handle_at()\\n"); + exit(EXIT_FAILURE); + } + + /* Reallocate file_handle structure with correct size */ + + fhsize = sizeof(struct file_handle) + fhp\->handle_bytes; + fhp = realloc(fhp, fhsize); /* Copies fhp\->handle_bytes */ + if (fhp == NULL) + errExit("realloc"); + + /* Get file handle from pathname supplied on command line */ + + if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == \-1) + errExit("name_to_handle_at"); + + /* Write mount ID, file handle size, and file handle to stdout, + for later reuse by t_open_by_handle_at.c */ + + printf("%d\\n", mount_id); + printf("%d %d ", fhp\->handle_bytes, fhp\->handle_type); + for (j = 0; j < fhp\->handle_bytes; j++) + printf(" %02x", fhp\->f_handle[j]); + printf("\\n"); + + exit(EXIT_SUCCESS); +} +.EE +.SS Program source: t_open_by_handle_at.c +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +/* Scan /proc/self/mountinfo to find the line whose mount ID matches + \(aqmount_id\(aq. (An easier way to do this is to install and use the + \(aqlibmount\(aq library provided by the \(aqutil\-linux\(aq project.) + Open the corresponding mount path and return the resulting file + descriptor. */ + +static int +open_mount_path_by_id(int mount_id) +{ + char *linep; + size_t lsize; + char mount_path[PATH_MAX]; + int mi_mount_id, found; + ssize_t nread; + FILE *fp; + + fp = fopen("/proc/self/mountinfo", "r"); + if (fp == NULL) + errExit("fopen"); + + found = 0; + linep = NULL; + while (!found) { + nread = getline(&linep, &lsize, fp); + if (nread == \-1) + break; + + nread = sscanf(linep, "%d %*d %*s %*s %s", + &mi_mount_id, mount_path); + if (nread != 2) { + fprintf(stderr, "Bad sscanf()\\n"); + exit(EXIT_FAILURE); + } + + if (mi_mount_id == mount_id) + found = 1; + } + free(linep); + + fclose(fp); + + if (!found) { + fprintf(stderr, "Could not find mount point\\n"); + exit(EXIT_FAILURE); + } + + return open(mount_path, O_RDONLY); +} + +int +main(int argc, char *argv[]) +{ + struct file_handle *fhp; + int mount_id, fd, mount_fd, handle_bytes, j; + ssize_t nread; + char buf[1000]; +#define LINE_SIZE 100 + char line1[LINE_SIZE], line2[LINE_SIZE]; + char *nextp; + + if ((argc > 1 && strcmp(argv[1], "\-\-help") == 0) || argc > 2) { + fprintf(stderr, "Usage: %s [mount\-path]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* Standard input contains mount ID and file handle information: + + Line 1: + Line 2: + */ + + if ((fgets(line1, sizeof(line1), stdin) == NULL) || + (fgets(line2, sizeof(line2), stdin) == NULL)) { + fprintf(stderr, "Missing mount_id / file handle\\n"); + exit(EXIT_FAILURE); + } + + mount_id = atoi(line1); + + handle_bytes = strtoul(line2, &nextp, 0); + + /* Given handle_bytes, we can now allocate file_handle structure */ + + fhp = malloc(sizeof(struct file_handle) + handle_bytes); + if (fhp == NULL) + errExit("malloc"); + + fhp\->handle_bytes = handle_bytes; + + fhp\->handle_type = strtoul(nextp, &nextp, 0); + + for (j = 0; j < fhp\->handle_bytes; j++) + fhp\->f_handle[j] = strtoul(nextp, &nextp, 16); + + /* Obtain file descriptor for mount point, either by opening + the pathname specified on the command line, or by scanning + /proc/self/mounts to find a mount that matches the \(aqmount_id\(aq + that we received from stdin. */ + + if (argc > 1) + mount_fd = open(argv[1], O_RDONLY); + else + mount_fd = open_mount_path_by_id(mount_id); + + if (mount_fd == \-1) + errExit("opening mount fd"); + + /* Open file using handle and mount point */ + + fd = open_by_handle_at(mount_fd, fhp, O_RDONLY); + if (fd == \-1) + errExit("open_by_handle_at"); + + /* Try reading a few bytes from the file */ + + nread = read(fd, buf, sizeof(buf)); + if (nread == \-1) + errExit("read"); + + printf("Read %zd bytes\\n", nread); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR open (2), +.BR libblkid (3), +.BR blkid (8), +.BR findfs (8), +.BR mount (8) +.PP +The +.I libblkid +and +.I libmount +documentation in the latest +.I util-linux +release at +.UR https://www.kernel.org/pub/linux/utils/util\-linux/ +.UE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/openat.2 b/man2/openat.2 new file mode 100644 index 0000000..604e121 --- /dev/null +++ b/man2/openat.2 @@ -0,0 +1 @@ +.so man2/open.2 diff --git a/man2/outb.2 b/man2/outb.2 new file mode 100644 index 0000000..b20bac3 --- /dev/null +++ b/man2/outb.2 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1995 Paul Gortmaker +.\" (gpg109@rsphy1.anu.edu.au) +.\" Wed Nov 29 10:58:54 EST 1995 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH OUTB 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +outb, outw, outl, outsb, outsw, outsl, +inb, inw, inl, insb, insw, insl, +outb_p, outw_p, outl_p, inb_p, inw_p, inl_p \- port I/O +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "unsigned char inb(unsigned short int " port ); +.BI "unsigned char inb_p(unsigned short int " port ); +.BI "unsigned short int inw(unsigned short int " port ); +.BI "unsigned short int inw_p(unsigned short int " port ); +.BI "unsigned int inl(unsigned short int " port ); +.BI "unsigned int inl_p(unsigned short int " port ); +.PP +.BI "void outb(unsigned char " value ", unsigned short int " port ); +.BI "void outb_p(unsigned char " value ", unsigned short int " port ); +.BI "void outw(unsigned short int " value ", unsigned short int " port ); +.BI "void outw_p(unsigned short int " value ", unsigned short int " port ); +.BI "void outl(unsigned int " value ", unsigned short int " port ); +.BI "void outl_p(unsigned int " value ", unsigned short int " port ); +.PP +.BI "void insb(unsigned short int " port ", void *" addr , +.BI " unsigned long int " count ); +.BI "void insw(unsigned short int " port ", void *" addr , +.BI " unsigned long int " count ); +.BI "void insl(unsigned short int " port ", void *" addr , +.BI " unsigned long int " count ); +.BI "void outsb(unsigned short int " port ", const void *" addr , +.BI " unsigned long int " count ); +.BI "void outsw(unsigned short int " port ", const void *" addr , +.BI " unsigned long int " count ); +.BI "void outsl(unsigned short int " port ", const void *" addr , +.BI " unsigned long int " count ); +.fi +.SH DESCRIPTION +This family of functions is used to do low-level port input and output. +The out* functions do port output, the in* functions do port input; +the b-suffix functions are byte-width and the w-suffix functions +word-width; the _p-suffix functions pause until the I/O completes. +.PP +They are primarily designed for internal kernel use, +but can be used from user space. +.\" , given the following information +.\" in addition to that given in +.\" .BR outb (9). +.PP +You must compile with \fB\-O\fP or \fB\-O2\fP or similar. +The functions +are defined as inline macros, and will not be substituted in without +optimization enabled, causing unresolved references at link time. +.PP +You use +.BR ioperm (2) +or alternatively +.BR iopl (2) +to tell the kernel to allow the user space application to access the +I/O ports in question. +Failure to do this will cause the application +to receive a segmentation fault. +.SH CONFORMING TO +.BR outb () +and friends are hardware-specific. +The +.I value +argument is passed first and the +.I port +argument is passed second, +which is the opposite order from most DOS implementations. +.SH SEE ALSO +.BR ioperm (2), +.BR iopl (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/outb_p.2 b/man2/outb_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/outb_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outl.2 b/man2/outl.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/outl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outl_p.2 b/man2/outl_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/outl_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outsb.2 b/man2/outsb.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/outsb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outsl.2 b/man2/outsl.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/outsl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outsw.2 b/man2/outsw.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/outsw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outw.2 b/man2/outw.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/outw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/outw_p.2 b/man2/outw_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man2/outw_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man2/pause.2 b/man2/pause.2 new file mode 100644 index 0000000..1a3aa54 --- /dev/null +++ b/man2/pause.2 @@ -0,0 +1,72 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 14:48:00 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) +.\" Modified 2000 by aeb, following Michael Kerrisk +.\" +.TH PAUSE 2 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +pause \- wait for signal +.SH SYNOPSIS +.B #include +.PP +.B int pause(void); +.SH DESCRIPTION +.BR pause () +causes the calling process (or thread) to sleep +until a signal is delivered that either terminates the process or causes +the invocation of a signal-catching function. +.SH RETURN VALUE +.BR pause () +returns only when a signal was caught and the +signal-catching function returned. +In this case, +.BR pause () +returns \-1, and +.I errno +is set to +.\" .BR ERESTARTNOHAND . +.BR EINTR . +.SH ERRORS +.TP +.B EINTR +a signal was caught and the signal-catching function returned. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH SEE ALSO +.BR kill (2), +.BR select (2), +.BR signal (2), +.BR sigsuspend (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/pciconfig_iobase.2 b/man2/pciconfig_iobase.2 new file mode 100644 index 0000000..5ab2995 --- /dev/null +++ b/man2/pciconfig_iobase.2 @@ -0,0 +1 @@ +.so man2/pciconfig_read.2 diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2 new file mode 100644 index 0000000..176cf0e --- /dev/null +++ b/man2/pciconfig_read.2 @@ -0,0 +1,124 @@ +.\" Contributed by Niki A. Rahimi, LTC Security Development +.\" narahimi@us.ibm.com +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" May be freely distributed and modified. +.\" %%%LICENSE_END +.\" +.TH PCICONFIG_READ 2 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +pciconfig_read, pciconfig_write, pciconfig_iobase \- pci device information handling +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pciconfig_read(unsigned long " bus ", unsigned long " dfn , +.BI " unsigned long " off ", unsigned long " len ", void *" buf ); +.BI "int pciconfig_write(unsigned long " bus ", unsigned long " dfn , +.BI " unsigned long " off ", unsigned long " len ", void *" buf ); +.BI "int pciconfig_iobase(long " which ", unsigned long " bus , +.BI " unsigned long " devfn ); +.fi +.SH DESCRIPTION +.PP +Most of the interaction with PCI devices is already handled by the +kernel PCI layer, +and thus these calls should not normally need to be accessed from user space. +.TP +.BR pciconfig_read () +Reads to +.I buf +from device +.I dev +at offset +.I off +value. +.TP +.BR pciconfig_write () +Writes from +.I buf +to device +.I dev +at offset +.I off +value. +.TP +.BR pciconfig_iobase () +You pass it a bus/devfn pair and get a physical address for either the +memory offset (for things like prep, this is 0xc0000000), +the IO base for PIO cycles, or the ISA holes if any. +.SH RETURN VALUE +.TP +.BR pciconfig_read () +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set appropriately. +.TP +.BR pciconfig_write () +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set appropriately. +.TP +.BR pciconfig_iobase () +Returns information on locations of various I/O +regions in physical memory according to the +.I which +value. +Values for +.I which +are: +.BR IOBASE_BRIDGE_NUMBER , +.BR IOBASE_MEMORY , +.BR IOBASE_IO , +.BR IOBASE_ISA_IO , +.BR IOBASE_ISA_MEM . +.SH ERRORS +.TP +.B EINVAL +.I len +value is invalid. +This does not apply to +.BR pciconfig_iobase (). +.TP +.B EIO +I/O error. +.TP +.B ENODEV +For +.BR pciconfig_iobase (), +"hose" value is NULL. +For the other calls, could not find a slot. +.TP +.B ENOSYS +The system has not implemented these calls +.RB ( CONFIG_PCI +not defined). +.TP +.B EOPNOTSUPP +This return value is valid only for +.BR pciconfig_iobase (). +It is returned if the value for +.I which +is invalid. +.TP +.B EPERM +User does not have the +.B CAP_SYS_ADMIN +capability. +This does not apply to +.BR pciconfig_iobase (). +.SH CONFORMING TO +These calls are Linux-specific, available since Linux 2.0.26/2.1.11. +.SH SEE ALSO +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/pciconfig_write.2 b/man2/pciconfig_write.2 new file mode 100644 index 0000000..5ab2995 --- /dev/null +++ b/man2/pciconfig_write.2 @@ -0,0 +1 @@ +.so man2/pciconfig_read.2 diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 new file mode 100644 index 0000000..c583526 --- /dev/null +++ b/man2/perf_event_open.2 @@ -0,0 +1,3340 @@ +.\" Copyright (c) 2012, Vincent Weaver +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" This document is based on the perf_event.h header file, the +.\" tools/perf/design.txt file, and a lot of bitter experience. +.\" +.TH PERF_EVENT_OPEN 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +perf_event_open \- set up performance monitoring +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int perf_event_open(struct perf_event_attr *" attr , +.BI " pid_t " pid ", int " cpu ", int " group_fd , +.BI " unsigned long " flags ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +Given a list of parameters, +.BR perf_event_open () +returns a file descriptor, for use in subsequent system calls +.RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)." +.PP +A call to +.BR perf_event_open () +creates a file descriptor that allows measuring performance +information. +Each file descriptor corresponds to one +event that is measured; these can be grouped together +to measure multiple events simultaneously. +.PP +Events can be enabled and disabled in two ways: via +.BR ioctl (2) +and via +.BR prctl (2). +When an event is disabled it does not count or generate overflows but does +continue to exist and maintain its count value. +.PP +Events come in two flavors: counting and sampled. +A +.I counting +event is one that is used for counting the aggregate number of events +that occur. +In general, counting event results are gathered with a +.BR read (2) +call. +A +.I sampling +event periodically writes measurements to a buffer that can then +be accessed via +.BR mmap (2). +.SS Arguments +.PP +The +.I pid +and +.I cpu +arguments allow specifying which process and CPU to monitor: +.TP +.BR "pid == 0" " and " "cpu == \-1" +This measures the calling process/thread on any CPU. +.TP +.BR "pid == 0" " and " "cpu >= 0" +This measures the calling process/thread only +when running on the specified CPU. +.TP +.BR "pid > 0" " and " "cpu == \-1" +This measures the specified process/thread on any CPU. +.TP +.BR "pid > 0" " and " "cpu >= 0" +This measures the specified process/thread only +when running on the specified CPU. +.TP +.BR "pid == \-1" " and " "cpu >= 0" +This measures all processes/threads on the specified CPU. +This requires +.B CAP_SYS_ADMIN +capability or a +.I /proc/sys/kernel/perf_event_paranoid +value of less than 1. +.TP +.BR "pid == \-1" " and " "cpu == \-1" +This setting is invalid and will return an error. +.PP +When +.I pid +is greater than zero, permission to perform this system call +is governed by a ptrace access mode +.B PTRACE_MODE_READ_REALCREDS +check; see +.BR ptrace (2). +.PP +The +.I group_fd +argument allows event groups to be created. +An event group has one event which is the group leader. +The leader is created first, with +.IR group_fd " = \-1." +The rest of the group members are created with subsequent +.BR perf_event_open () +calls with +.IR group_fd +being set to the file descriptor of the group leader. +(A single event on its own is created with +.IR group_fd " = \-1" +and is considered to be a group with only 1 member.) +An event group is scheduled onto the CPU as a unit: it will +be put onto the CPU only if all of the events in the group can be put onto +the CPU. +This means that the values of the member events can be +meaningfully compared\(emadded, divided (to get ratios), and so on\(emwith each +other, since they have counted events for the same set of executed +instructions. +.PP +The +.I flags +argument is formed by ORing together zero or more of the following values: +.TP +.BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)" +.\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e +This flag enables the close-on-exec flag for the created +event file descriptor, +so that the file descriptor is automatically closed on +.BR execve (2). +Setting the close-on-exec flags at creation time, rather than later with +.BR fcntl (2), +avoids potential race conditions where the calling thread invokes +.BR perf_event_open () +and +.BR fcntl (2) +at the same time as another thread calls +.BR fork (2) +then +.BR execve (2). +.TP +.BR PERF_FLAG_FD_NO_GROUP +This flag tells the event to ignore the +.IR group_fd +parameter except for the purpose of setting up output redirection +using the +.B PERF_FLAG_FD_OUTPUT +flag. +.TP +.BR PERF_FLAG_FD_OUTPUT " (broken since Linux 2.6.35)" +.\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318 +This flag re-routes the event's sampled output to instead +be included in the mmap buffer of the event specified by +.IR group_fd . +.TP +.BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)" +.\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25 +This flag activates per-container system-wide monitoring. +A container +is an abstraction that isolates a set of resources for finer-grained +control (CPUs, memory, etc.). +In this mode, the event is measured +only if the thread running on the monitored CPU belongs to the designated +container (cgroup). +The cgroup is identified by passing a file descriptor +opened on its directory in the cgroupfs filesystem. +For instance, if the +cgroup to monitor is called +.IR test , +then a file descriptor opened on +.I /dev/cgroup/test +(assuming cgroupfs is mounted on +.IR /dev/cgroup ) +must be passed as the +.I pid +parameter. +cgroup monitoring is available only +for system-wide events and may therefore require extra permissions. +.PP +The +.I perf_event_attr +structure provides detailed configuration information +for the event being created. +.PP +.in +4n +.EX +struct perf_event_attr { + __u32 type; /* Type of event */ + __u32 size; /* Size of attribute structure */ + __u64 config; /* Type-specific configuration */ + + union { + __u64 sample_period; /* Period of sampling */ + __u64 sample_freq; /* Frequency of sampling */ + }; + + __u64 sample_type; /* Specifies values included in sample */ + __u64 read_format; /* Specifies values returned in read */ + + __u64 disabled : 1, /* off by default */ + inherit : 1, /* children inherit it */ + pinned : 1, /* must always be on PMU */ + exclusive : 1, /* only group on PMU */ + exclude_user : 1, /* don't count user */ + exclude_kernel : 1, /* don't count kernel */ + exclude_hv : 1, /* don't count hypervisor */ + exclude_idle : 1, /* don't count when idle */ + mmap : 1, /* include mmap data */ + comm : 1, /* include comm data */ + freq : 1, /* use freq, not period */ + inherit_stat : 1, /* per task counts */ + enable_on_exec : 1, /* next exec enables */ + task : 1, /* trace fork/exit */ + watermark : 1, /* wakeup_watermark */ + precise_ip : 2, /* skid constraint */ + mmap_data : 1, /* non-exec mmap data */ + sample_id_all : 1, /* sample_type all events */ + exclude_host : 1, /* don't count in host */ + exclude_guest : 1, /* don't count in guest */ + exclude_callchain_kernel : 1, + /* exclude kernel callchains */ + exclude_callchain_user : 1, + /* exclude user callchains */ + mmap2 : 1, /* include mmap with inode data */ + comm_exec : 1, /* flag comm events that are + due to exec */ + use_clockid : 1, /* use clockid for time fields */ + context_switch : 1, /* context switch data */ + + __reserved_1 : 37; + + union { + __u32 wakeup_events; /* wakeup every n events */ + __u32 wakeup_watermark; /* bytes before wakeup */ + }; + + __u32 bp_type; /* breakpoint type */ + + union { + __u64 bp_addr; /* breakpoint address */ + __u64 config1; /* extension of config */ + }; + + union { + __u64 bp_len; /* breakpoint length */ + __u64 config2; /* extension of config1 */ + }; + __u64 branch_sample_type; /* enum perf_branch_sample_type */ + __u64 sample_regs_user; /* user regs to dump on samples */ + __u32 sample_stack_user; /* size of stack to dump on + samples */ + __s32 clockid; /* clock to use for time fields */ + __u64 sample_regs_intr; /* regs to dump on samples */ + __u32 aux_watermark; /* aux bytes before wakeup */ + __u16 sample_max_stack; /* max frames in callchain */ + __u16 __reserved_2; /* align to u64 */ + +}; +.EE +.in +.PP +The fields of the +.I perf_event_attr +structure are described in more detail below: +.TP +.I type +This field specifies the overall event type. +It has one of the following values: +.RS +.TP +.B PERF_TYPE_HARDWARE +This indicates one of the "generalized" hardware events provided +by the kernel. +See the +.I config +field definition for more details. +.TP +.B PERF_TYPE_SOFTWARE +This indicates one of the software-defined events provided by the kernel +(even if no hardware support is available). +.TP +.B PERF_TYPE_TRACEPOINT +This indicates a tracepoint +provided by the kernel tracepoint infrastructure. +.TP +.B PERF_TYPE_HW_CACHE +This indicates a hardware cache event. +This has a special encoding, described in the +.I config +field definition. +.TP +.B PERF_TYPE_RAW +This indicates a "raw" implementation-specific event in the +.IR config " field." +.TP +.BR PERF_TYPE_BREAKPOINT " (since Linux 2.6.33)" +.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e +This indicates a hardware breakpoint as provided by the CPU. +Breakpoints can be read/write accesses to an address as well as +execution of an instruction address. +.TP +.RB "dynamic PMU" +Since Linux 2.6.38, +.\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19 +.BR perf_event_open () +can support multiple PMUs. +To enable this, a value exported by the kernel can be used in the +.I type +field to indicate which PMU to use. +The value to use can be found in the sysfs filesystem: +there is a subdirectory per PMU instance under +.IR /sys/bus/event_source/devices . +In each subdirectory there is a +.I type +file whose content is an integer that can be used in the +.I type +field. +For instance, +.I /sys/bus/event_source/devices/cpu/type +contains the value for the core CPU PMU, which is usually 4. +.RE +.TP +.I "size" +The size of the +.I perf_event_attr +structure for forward/backward compatibility. +Set this using +.I sizeof(struct perf_event_attr) +to allow the kernel to see +the struct size at the time of compilation. +.IP +The related define +.B PERF_ATTR_SIZE_VER0 +is set to 64; this was the size of the first published struct. +.B PERF_ATTR_SIZE_VER1 +is 72, corresponding to the addition of breakpoints in Linux 2.6.33. +.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2 +.\" this was added much later when PERF_ATTR_SIZE_VER2 happened +.\" but the actual attr_size had increased in 2.6.33 +.B PERF_ATTR_SIZE_VER2 +is 80 corresponding to the addition of branch sampling in Linux 3.4. +.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2 +.B PERF_ATTR_SIZE_VER3 +is 96 corresponding to the addition +of +.I sample_regs_user +and +.I sample_stack_user +in Linux 3.7. +.\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03 +.B PERF_ATTR_SIZE_VER4 +is 104 corresponding to the addition of +.I sample_regs_intr +in Linux 3.19. +.\" commit 60e2364e60e86e81bc6377f49779779e6120977f +.B PERF_ATTR_SIZE_VER5 +is 112 corresponding to the addition of +.I aux_watermark +in Linux 4.1. +.\" commit 1a5941312414c71dece6717da9a0fa1303127afa +.TP +.I "config" +This specifies which event you want, in conjunction with +the +.I type +field. +The +.IR config1 " and " config2 +fields are also taken into account in cases where 64 bits is not +enough to fully specify the event. +The encoding of these fields are event dependent. +.IP +There are various ways to set the +.I config +field that are dependent on the value of the previously +described +.I type +field. +What follows are various possible settings for +.I config +separated out by +.IR type . +.IP +If +.I type +is +.BR PERF_TYPE_HARDWARE , +we are measuring one of the generalized hardware CPU events. +Not all of these are available on all platforms. +Set +.I config +to one of the following: +.RS 12 +.TP +.B PERF_COUNT_HW_CPU_CYCLES +Total cycles. +Be wary of what happens during CPU frequency scaling. +.TP +.B PERF_COUNT_HW_INSTRUCTIONS +Retired instructions. +Be careful, these can be affected by various +issues, most notably hardware interrupt counts. +.TP +.B PERF_COUNT_HW_CACHE_REFERENCES +Cache accesses. +Usually this indicates Last Level Cache accesses but this may +vary depending on your CPU. +This may include prefetches and coherency messages; again this +depends on the design of your CPU. +.TP +.B PERF_COUNT_HW_CACHE_MISSES +Cache misses. +Usually this indicates Last Level Cache misses; this is intended to be +used in conjunction with the +.B PERF_COUNT_HW_CACHE_REFERENCES +event to calculate cache miss rates. +.TP +.B PERF_COUNT_HW_BRANCH_INSTRUCTIONS +Retired branch instructions. +Prior to Linux 2.6.35, this used +the wrong event on AMD processors. +.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2 +.TP +.B PERF_COUNT_HW_BRANCH_MISSES +Mispredicted branch instructions. +.TP +.B PERF_COUNT_HW_BUS_CYCLES +Bus cycles, which can be different from total cycles. +.TP +.BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (since Linux 3.0)" +.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a +Stalled cycles during issue. +.TP +.BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (since Linux 3.0)" +.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a +Stalled cycles during retirement. +.TP +.BR PERF_COUNT_HW_REF_CPU_CYCLES " (since Linux 3.3)" +.\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890 +Total cycles; not affected by CPU frequency scaling. +.RE +.IP +If +.I type +is +.BR PERF_TYPE_SOFTWARE , +we are measuring software events provided by the kernel. +Set +.I config +to one of the following: +.RS 12 +.TP +.B PERF_COUNT_SW_CPU_CLOCK +This reports the CPU clock, a high-resolution per-CPU timer. +.TP +.B PERF_COUNT_SW_TASK_CLOCK +This reports a clock count specific to the task that is running. +.TP +.B PERF_COUNT_SW_PAGE_FAULTS +This reports the number of page faults. +.TP +.B PERF_COUNT_SW_CONTEXT_SWITCHES +This counts context switches. +Until Linux 2.6.34, these were all reported as user-space +events, after that they are reported as happening in the kernel. +.\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21 +.TP +.B PERF_COUNT_SW_CPU_MIGRATIONS +This reports the number of times the process +has migrated to a new CPU. +.TP +.B PERF_COUNT_SW_PAGE_FAULTS_MIN +This counts the number of minor page faults. +These did not require disk I/O to handle. +.TP +.B PERF_COUNT_SW_PAGE_FAULTS_MAJ +This counts the number of major page faults. +These required disk I/O to handle. +.TP +.BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (since Linux 2.6.33)" +.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497 +This counts the number of alignment faults. +These happen when unaligned memory accesses happen; the kernel +can handle these but it reduces performance. +This happens only on some architectures (never on x86). +.TP +.BR PERF_COUNT_SW_EMULATION_FAULTS " (since Linux 2.6.33)" +.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497 +This counts the number of emulation faults. +The kernel sometimes traps on unimplemented instructions +and emulates them for user space. +This can negatively impact performance. +.TP +.BR PERF_COUNT_SW_DUMMY " (since Linux 3.12)" +.\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77 +This is a placeholder event that counts nothing. +Informational sample record types such as mmap or comm +must be associated with an active event. +This dummy event allows gathering such records without requiring +a counting event. +.RE +.PP +.RS +If +.I type +is +.BR PERF_TYPE_TRACEPOINT , +then we are measuring kernel tracepoints. +The value to use in +.I config +can be obtained from under debugfs +.I tracing/events/*/*/id +if ftrace is enabled in the kernel. +.RE +.PP +.RS +If +.I type +is +.BR PERF_TYPE_HW_CACHE , +then we are measuring a hardware CPU cache event. +To calculate the appropriate +.I config +value use the following equation: +.PP +.RS 4 +.nf + (perf_hw_cache_id) | (perf_hw_cache_op_id << 8) | + (perf_hw_cache_op_result_id << 16) +.fi +.PP +where +.I perf_hw_cache_id +is one of: +.RS 4 +.TP +.B PERF_COUNT_HW_CACHE_L1D +for measuring Level 1 Data Cache +.TP +.B PERF_COUNT_HW_CACHE_L1I +for measuring Level 1 Instruction Cache +.TP +.B PERF_COUNT_HW_CACHE_LL +for measuring Last-Level Cache +.TP +.B PERF_COUNT_HW_CACHE_DTLB +for measuring the Data TLB +.TP +.B PERF_COUNT_HW_CACHE_ITLB +for measuring the Instruction TLB +.TP +.B PERF_COUNT_HW_CACHE_BPU +for measuring the branch prediction unit +.TP +.BR PERF_COUNT_HW_CACHE_NODE " (since Linux 3.1)" +.\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477 +for measuring local memory accesses +.RE +.PP +and +.I perf_hw_cache_op_id +is one of: +.RS 4 +.TP +.B PERF_COUNT_HW_CACHE_OP_READ +for read accesses +.TP +.B PERF_COUNT_HW_CACHE_OP_WRITE +for write accesses +.TP +.B PERF_COUNT_HW_CACHE_OP_PREFETCH +for prefetch accesses +.RE +.PP +and +.I perf_hw_cache_op_result_id +is one of: +.RS 4 +.TP +.B PERF_COUNT_HW_CACHE_RESULT_ACCESS +to measure accesses +.TP +.B PERF_COUNT_HW_CACHE_RESULT_MISS +to measure misses +.RE +.RE +.PP +If +.I type +is +.BR PERF_TYPE_RAW , +then a custom "raw" +.I config +value is needed. +Most CPUs support events that are not covered by the "generalized" events. +These are implementation defined; see your CPU manual (for example +the Intel Volume 3B documentation or the AMD BIOS and Kernel Developer +Guide). +The libpfm4 library can be used to translate from the name in the +architectural manuals to the raw hex value +.BR perf_event_open () +expects in this field. +.PP +If +.I type +is +.BR PERF_TYPE_BREAKPOINT , +then leave +.I config +set to zero. +Its parameters are set in other places. +.RE +.TP +.IR sample_period ", " sample_freq +A "sampling" event is one that generates an overflow notification +every N events, where N is given by +.IR sample_period . +A sampling event has +.IR sample_period " > 0." +When an overflow occurs, requested data is recorded +in the mmap buffer. +The +.I sample_type +field controls what data is recorded on each overflow. +.IP +.I sample_freq +can be used if you wish to use frequency rather than period. +In this case, you set the +.I freq +flag. +The kernel will adjust the sampling period +to try and achieve the desired rate. +The rate of adjustment is a +timer tick. +.TP +.I "sample_type" +The various bits in this field specify which values to include +in the sample. +They will be recorded in a ring-buffer, +which is available to user space using +.BR mmap (2). +The order in which the values are saved in the +sample are documented in the MMAP Layout subsection below; +it is not the +.I "enum perf_event_sample_format" +order. +.RS +.TP +.B PERF_SAMPLE_IP +Records instruction pointer. +.TP +.B PERF_SAMPLE_TID +Records the process and thread IDs. +.TP +.B PERF_SAMPLE_TIME +Records a timestamp. +.TP +.B PERF_SAMPLE_ADDR +Records an address, if applicable. +.TP +.B PERF_SAMPLE_READ +Record counter values for all events in a group, not just the group leader. +.TP +.B PERF_SAMPLE_CALLCHAIN +Records the callchain (stack backtrace). +.TP +.B PERF_SAMPLE_ID +Records a unique ID for the opened event's group leader. +.TP +.B PERF_SAMPLE_CPU +Records CPU number. +.TP +.B PERF_SAMPLE_PERIOD +Records the current sampling period. +.TP +.B PERF_SAMPLE_STREAM_ID +Records a unique ID for the opened event. +Unlike +.B PERF_SAMPLE_ID +the actual ID is returned, not the group leader. +This ID is the same as the one returned by +.BR PERF_FORMAT_ID . +.TP +.B PERF_SAMPLE_RAW +Records additional data, if applicable. +Usually returned by tracepoint events. +.TP +.BR PERF_SAMPLE_BRANCH_STACK " (since Linux 3.4)" +.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e +This provides a record of recent branches, as provided +by CPU branch sampling hardware (such as Intel Last Branch Record). +Not all hardware supports this feature. +.IP +See the +.I branch_sample_type +field for how to filter which branches are reported. +.TP +.BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)" +.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56 +Records the current user-level CPU register state +(the values in the process before the kernel was called). +.TP +.BR PERF_SAMPLE_STACK_USER " (since Linux 3.7)" +.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7 +Records the user level stack, allowing stack unwinding. +.TP +.BR PERF_SAMPLE_WEIGHT " (since Linux 3.10)" +.\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c +Records a hardware provided weight value that expresses how +costly the sampled event was. +This allows the hardware to highlight expensive events in +a profile. +.TP +.BR PERF_SAMPLE_DATA_SRC " (since Linux 3.10)" +.\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1 +Records the data source: where in the memory hierarchy +the data associated with the sampled instruction came from. +This is available only if the underlying hardware +supports this feature. +.TP +.BR PERF_SAMPLE_IDENTIFIER " (since Linux 3.12)" +.\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955 +Places the +.B SAMPLE_ID +value in a fixed position in the record, +either at the beginning (for sample events) or at the end +(if a non-sample event). +.IP +This was necessary because a sample stream may have +records from various different event sources with different +.I sample_type +settings. +Parsing the event stream properly was not possible because the +format of the record was needed to find +.BR SAMPLE_ID , +but +the format could not be found without knowing what +event the sample belonged to (causing a circular +dependency). +.IP +The +.B PERF_SAMPLE_IDENTIFIER +setting makes the event stream always parsable +by putting +.B SAMPLE_ID +in a fixed location, even though +it means having duplicate +.B SAMPLE_ID +values in records. +.TP +.BR PERF_SAMPLE_TRANSACTION " (since Linux 3.13)" +.\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5 +Records reasons for transactional memory abort events +(for example, from Intel TSX transactional memory support). +.IP +The +.I precise_ip +setting must be greater than 0 and a transactional memory abort +event must be measured or no values will be recorded. +Also note that some perf_event measurements, such as sampled +cycle counting, may cause extraneous aborts (by causing an +interrupt during a transaction). +.TP +.BR PERF_SAMPLE_REGS_INTR " (since Linux 3.19)" +.\" commit 60e2364e60e86e81bc6377f49779779e6120977f +Records a subset of the current CPU register state +as specified by +.IR sample_regs_intr . +Unlike +.B PERF_SAMPLE_REGS_USER +the register values will return kernel register +state if the overflow happened while kernel +code is running. +If the CPU supports hardware sampling of +register state (i.e., PEBS on Intel x86) and +.I precise_ip +is set higher than zero then the register +values returned are those captured by +hardware at the time of the sampled +instruction's retirement. +.RE +.TP +.IR "read_format" +This field specifies the format of the data returned by +.BR read (2) +on a +.BR perf_event_open () +file descriptor. +.RS +.TP +.B PERF_FORMAT_TOTAL_TIME_ENABLED +Adds the 64-bit +.I time_enabled +field. +This can be used to calculate estimated totals if +the PMU is overcommitted and multiplexing is happening. +.TP +.B PERF_FORMAT_TOTAL_TIME_RUNNING +Adds the 64-bit +.I time_running +field. +This can be used to calculate estimated totals if +the PMU is overcommitted and multiplexing is happening. +.TP +.B PERF_FORMAT_ID +Adds a 64-bit unique value that corresponds to the event group. +.TP +.B PERF_FORMAT_GROUP +Allows all counter values in an event group to be read with one read. +.RE +.TP +.IR "disabled" +The +.I disabled +bit specifies whether the counter starts out disabled or enabled. +If disabled, the event can later be enabled by +.BR ioctl (2), +.BR prctl (2), +or +.IR enable_on_exec . +.IP +When creating an event group, typically the group leader is initialized +with +.I disabled +set to 1 and any child events are initialized with +.I disabled +set to 0. +Despite +.I disabled +being 0, the child events will not start until the group leader +is enabled. +.TP +.IR "inherit" +The +.I inherit +bit specifies that this counter should count events of child +tasks as well as the task specified. +This applies only to new children, not to any existing children at +the time the counter is created (nor to any new children of +existing children). +.IP +Inherit does not work for some combinations of +.IR read_format +values, such as +.BR PERF_FORMAT_GROUP . +.TP +.IR "pinned" +The +.I pinned +bit specifies that the counter should always be on the CPU if at all +possible. +It applies only to hardware counters and only to group leaders. +If a pinned counter cannot be put onto the CPU (e.g., because there are +not enough hardware counters or because of a conflict with some other +event), then the counter goes into an 'error' state, where reads +return end-of-file (i.e., +.BR read (2) +returns 0) until the counter is subsequently enabled or disabled. +.TP +.IR "exclusive" +The +.I exclusive +bit specifies that when this counter's group is on the CPU, +it should be the only group using the CPU's counters. +In the future this may allow monitoring programs to +support PMU features that need to run alone so that they do not +disrupt other hardware counters. +.IP +Note that many unexpected situations may prevent events with the +.I exclusive +bit set from ever running. +This includes any users running a system-wide +measurement as well as any kernel use of the performance counters +(including the commonly enabled NMI Watchdog Timer interface). +.TP +.IR "exclude_user" +If this bit is set, the count excludes events that happen in user space. +.TP +.IR "exclude_kernel" +If this bit is set, the count excludes events that happen in kernel space. +.TP +.IR "exclude_hv" +If this bit is set, the count excludes events that happen in the +hypervisor. +This is mainly for PMUs that have built-in support for handling this +(such as POWER). +Extra support is needed for handling hypervisor measurements on most +machines. +.TP +.IR "exclude_idle" +If set, don't count when the CPU is idle. +.TP +.IR "mmap" +The +.I mmap +bit enables generation of +.B PERF_RECORD_MMAP +samples for every +.BR mmap (2) +call that has +.B PROT_EXEC +set. +This allows tools to notice new executable code being mapped into +a program (dynamic shared libraries for example) +so that addresses can be mapped back to the original code. +.TP +.IR "comm" +The +.I comm +bit enables tracking of process command name as modified by the +.BR exec (2) +and +.BR prctl (PR_SET_NAME) +system calls as well as writing to +.IR /proc/self/comm . +If the +.I comm_exec +flag is also successfully set (possible since Linux 3.16), +.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871 +then the misc flag +.B PERF_RECORD_MISC_COMM_EXEC +can be used to differentiate the +.BR exec (2) +case from the others. +.TP +.IR "freq" +If this bit is set, then +.I sample_frequency +not +.I sample_period +is used when setting up the sampling interval. +.TP +.IR "inherit_stat" +This bit enables saving of event counts on context switch for +inherited tasks. +This is meaningful only if the +.I inherit +field is set. +.TP +.IR "enable_on_exec" +If this bit is set, a counter is automatically +enabled after a call to +.BR exec (2). +.TP +.IR "task" +If this bit is set, then +fork/exit notifications are included in the ring buffer. +.TP +.IR "watermark" +If set, have an overflow notification happen when we cross the +.I wakeup_watermark +boundary. +Otherwise, overflow notifications happen after +.I wakeup_events +samples. +.TP +.IR "precise_ip" " (since Linux 2.6.35)" +.\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076 +This controls the amount of skid. +Skid is how many instructions +execute between an event of interest happening and the kernel +being able to stop and record the event. +Smaller skid is +better and allows more accurate reporting of which events +correspond to which instructions, but hardware is often limited +with how small this can be. +.IP +The possible values of this field are the following: +.RS +.IP 0 3 +.B SAMPLE_IP +can have arbitrary skid. +.IP 1 +.B SAMPLE_IP +must have constant skid. +.IP 2 +.B SAMPLE_IP +requested to have 0 skid. +.IP 3 +.B SAMPLE_IP +must have 0 skid. +See also the description of +.BR PERF_RECORD_MISC_EXACT_IP . +.RE +.TP +.IR "mmap_data" " (since Linux 2.6.36)" +.\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e +This is the counterpart of the +.I mmap +field. +This enables generation of +.B PERF_RECORD_MMAP +samples for +.BR mmap (2) +calls that do not have +.B PROT_EXEC +set (for example data and SysV shared memory). +.TP +.IR "sample_id_all" " (since Linux 2.6.38)" +.\" commit c980d1091810df13f21aabbce545fd98f545bbf7 +If set, then TID, TIME, ID, STREAM_ID, and CPU can +additionally be included in +.RB non- PERF_RECORD_SAMPLE s +if the corresponding +.I sample_type +is selected. +.IP +If +.B PERF_SAMPLE_IDENTIFIER +is specified, then an additional ID value is included +as the last value to ease parsing the record stream. +This may lead to the +.I id +value appearing twice. +.IP +The layout is described by this pseudo-structure: +.IP +.in +4n +.EX +struct sample_id { + { u32 pid, tid; } /* if PERF_SAMPLE_TID set */ + { u64 time; } /* if PERF_SAMPLE_TIME set */ + { u64 id; } /* if PERF_SAMPLE_ID set */ + { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */ + { u32 cpu, res; } /* if PERF_SAMPLE_CPU set */ + { u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */ +}; +.EE +,in +.TP +.IR "exclude_host" " (since Linux 3.2)" +.\" commit a240f76165e6255384d4bdb8139895fac7988799 +When conducting measurements that include processes running +VM instances (i.e., have executed a +.B KVM_RUN +.BR ioctl (2)), +only measure events happening inside a guest instance. +This is only meaningful outside the guests; this setting does +not change counts gathered inside of a guest. +Currently, this functionality is x86 only. +.TP +.IR "exclude_guest" " (since Linux 3.2)" +.\" commit a240f76165e6255384d4bdb8139895fac7988799 +When conducting measurements that include processes running +VM instances (i.e., have executed a +.B KVM_RUN +.BR ioctl (2)), +do not measure events happening inside guest instances. +This is only meaningful outside the guests; this setting does +not change counts gathered inside of a guest. +Currently, this functionality is x86 only. +.TP +.IR "exclude_callchain_kernel" " (since Linux 3.7)" +.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91 +Do not include kernel callchains. +.TP +.IR "exclude_callchain_user" " (since Linux 3.7)" +.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91 +Do not include user callchains. +.TP +.IR "mmap2" " (since Linux 3.16)" +.\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741 +.\" This is tricky; was committed during 3.12 development +.\" but right before release was disabled. +.\" So while you could select mmap2 starting with 3.12 +.\" it did not work until 3.16 +.\" commit a5a5ba72843dd05f991184d6cb9a4471acce1005 +Generate an extended executable mmap record that contains enough +additional information to uniquely identify shared mappings. +The +.I mmap +flag must also be set for this to work. +.TP +.IR "comm_exec" " (since Linux 3.16)" +.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871 +This is purely a feature-detection flag, it does not change +kernel behavior. +If this flag can successfully be set, then, when +.I comm +is enabled, the +.B PERF_RECORD_MISC_COMM_EXEC +flag will be set in the +.I misc +field of a comm record header if the rename event being +reported was caused by a call to +.BR exec (2). +This allows tools to distinguish between the various +types of process renaming. +.TP +.IR "use_clockid" " (since Linux 4.1)" +.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b +This allows selecting which internal Linux clock to use +when generating timestamps via the +.I clockid +field. +This can make it easier to correlate perf sample times with +timestamps generated by other tools. +.TP +.IR "context_switch" " (since Linux 4.3)" +.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4 +This enables the generation of +.B PERF_RECORD_SWITCH +records when a context switch occurs. +It also enables the generation of +.B PERF_RECORD_SWITCH_CPU_WIDE +records when sampling in CPU-wide mode. +This functionality is in addition to existing tracepoint and +software events for measuring context switches. +The advantage of this method is that it will give full +information even with strict +.I perf_event_paranoid +settings. +.TP +.IR "wakeup_events" ", " "wakeup_watermark" +This union sets how many samples +.RI ( wakeup_events ) +or bytes +.RI ( wakeup_watermark ) +happen before an overflow notification happens. +Which one is used is selected by the +.I watermark +bit flag. +.IP +.I wakeup_events +counts only +.B PERF_RECORD_SAMPLE +record types. +To receive overflow notification for all +.B PERF_RECORD +types choose watermark and set +.I wakeup_watermark +to 1. +.IP +Prior to Linux 3.0, setting +.\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50 +.I wakeup_events +to 0 resulted in no overflow notifications; +more recent kernels treat 0 the same as 1. +.TP +.IR "bp_type" " (since Linux 2.6.33)" +.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e +This chooses the breakpoint type. +It is one of: +.RS +.TP +.BR HW_BREAKPOINT_EMPTY +No breakpoint. +.TP +.BR HW_BREAKPOINT_R +Count when we read the memory location. +.TP +.BR HW_BREAKPOINT_W +Count when we write the memory location. +.TP +.BR HW_BREAKPOINT_RW +Count when we read or write the memory location. +.TP +.BR HW_BREAKPOINT_X +Count when we execute code at the memory location. +.PP +The values can be combined via a bitwise or, but the +combination of +.B HW_BREAKPOINT_R +or +.B HW_BREAKPOINT_W +with +.B HW_BREAKPOINT_X +is not allowed. +.RE +.TP +.IR "bp_addr" " (since Linux 2.6.33)" +.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e +This is the address of the breakpoint. +For execution breakpoints, this is the memory address of the instruction +of interest; for read and write breakpoints, it is the memory address +of the memory location of interest. +.TP +.IR "config1" " (since Linux 2.6.39)" +.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6 +.I config1 +is used for setting events that need an extra register or otherwise +do not fit in the regular config field. +Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field +on Linux 3.3 and later kernels. +.TP +.IR "bp_len" " (since Linux 2.6.33)" +.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e +.I bp_len +is the length of the breakpoint being measured if +.I type +is +.BR PERF_TYPE_BREAKPOINT . +Options are +.BR HW_BREAKPOINT_LEN_1 , +.BR HW_BREAKPOINT_LEN_2 , +.BR HW_BREAKPOINT_LEN_4 , +and +.BR HW_BREAKPOINT_LEN_8 . +For an execution breakpoint, set this to +.IR sizeof(long) . +.TP +.IR "config2" " (since Linux 2.6.39)" +.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6 +.I config2 +is a further extension of the +.I config1 +field. +.TP +.IR "branch_sample_type" " (since Linux 3.4)" +.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e +If +.B PERF_SAMPLE_BRANCH_STACK +is enabled, then this specifies what branches to include +in the branch record. +.IP +The first part of the value is the privilege level, which +is a combination of one of the values listed below. +If the user does not set privilege level explicitly, the kernel +will use the event's privilege level. +Event and branch privilege levels do not have to match. +.RS +.TP +.B PERF_SAMPLE_BRANCH_USER +Branch target is in user space. +.TP +.B PERF_SAMPLE_BRANCH_KERNEL +Branch target is in kernel space. +.TP +.B PERF_SAMPLE_BRANCH_HV +Branch target is in hypervisor. +.TP +.B PERF_SAMPLE_BRANCH_PLM_ALL +A convenience value that is the three preceding values ORed together. +.PP +In addition to the privilege value, at least one or more of the +following bits must be set. +.TP +.B PERF_SAMPLE_BRANCH_ANY +Any branch type. +.TP +.B PERF_SAMPLE_BRANCH_ANY_CALL +Any call branch (includes direct calls, indirect calls, and far jumps). +.TP +.B PERF_SAMPLE_BRANCH_IND_CALL +Indirect calls. +.TP +.BR PERF_SAMPLE_BRANCH_CALL " (since Linux 4.4)" +.\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73 +Direct calls. +.TP +.B PERF_SAMPLE_BRANCH_ANY_RETURN +Any return branch. +.TP +.BR PERF_SAMPLE_BRANCH_IND_JUMP " (since Linux 4.2)" +.\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc +Indirect jumps. +.TP +.BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)" +.\" commit bac52139f0b7ab31330e98fd87fc5a2664951050 +Conditional branches. +.TP +.BR PERF_SAMPLE_BRANCH_ABORT_TX " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +Transactional memory aborts. +.TP +.BR PERF_SAMPLE_BRANCH_IN_TX " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +Branch in transactional memory transaction. +.TP +.BR PERF_SAMPLE_BRANCH_NO_TX " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +Branch not in transactional memory transaction. +.BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)" +.\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70 +Branch is part of a hardware-generated call stack. +This requires hardware support, currently only found +on Intel x86 Haswell or newer. +.RE +.TP +.IR "sample_regs_user" " (since Linux 3.7)" +.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56 +This bit mask defines the set of user CPU registers to dump on samples. +The layout of the register mask is architecture-specific and +is described in the kernel header file +.IR arch/ARCH/include/uapi/asm/perf_regs.h . +.TP +.IR "sample_stack_user" " (since Linux 3.7)" +.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7 +This defines the size of the user stack to dump if +.B PERF_SAMPLE_STACK_USER +is specified. +.TP +.IR "clockid" " (since Linux 4.1)" +.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b +If +.I use_clockid +is set, then this field selects which internal Linux timer to +use for timestamps. +The available timers are defined in +.IR linux/time.h , +with +.BR CLOCK_MONOTONIC , +.BR CLOCK_MONOTONIC_RAW , +.BR CLOCK_REALTIME , +.BR CLOCK_BOOTTIME , +and +.B CLOCK_TAI +currently supported. +.TP +.IR "aux_watermark" " (since Linux 4.1)" +.\" commit 1a5941312414c71dece6717da9a0fa1303127afa +This specifies how much data is required to trigger a +.B PERF_RECORD_AUX +sample. +.TP +.IR "sample_max_stack" " (since Linux 4.8)" +.\" commit 97c79a38cd454602645f0470ffb444b3b75ce574 +When +.I sample_type +includes +.BR PERF_SAMPLE_CALLCHAIN , +this field specifies how many stack frames to report when +generating the callchain. +.SS Reading results +Once a +.BR perf_event_open () +file descriptor has been opened, the values +of the events can be read from the file descriptor. +The values that are there are specified by the +.I read_format +field in the +.I attr +structure at open time. +.PP +If you attempt to read into a buffer that is not big enough to hold the +data, the error +.B ENOSPC +results. +.PP +Here is the layout of the data returned by a read: +.IP * 2 +If +.B PERF_FORMAT_GROUP +was specified to allow reading all events in a group at once: +.IP +.in +4n +.EX +struct read_format { + u64 nr; /* The number of events */ + u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */ + u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */ + struct { + u64 value; /* The value of the event */ + u64 id; /* if PERF_FORMAT_ID */ + } values[nr]; +}; +.EE +.in +.IP * +If +.B PERF_FORMAT_GROUP +was +.I not +specified: +.IP +.in +4n +.EX +struct read_format { + u64 value; /* The value of the event */ + u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */ + u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */ + u64 id; /* if PERF_FORMAT_ID */ +}; +.EE +.in +.PP +The values read are as follows: +.TP +.I nr +The number of events in this file descriptor. +Available only if +.B PERF_FORMAT_GROUP +was specified. +.TP +.IR time_enabled ", " time_running +Total time the event was enabled and running. +Normally these values are the same. +If more events are started, +then available counter slots on the PMU, then multiplexing +happens and events run only part of the time. +In that case, the +.I time_enabled +and +.I time running +values can be used to scale an estimated value for the count. +.TP +.I value +An unsigned 64-bit value containing the counter result. +.TP +.I id +A globally unique value for this particular event; only present if +.B PERF_FORMAT_ID +was specified in +.IR read_format . +.SS MMAP layout +When using +.BR perf_event_open () +in sampled mode, asynchronous events +(like counter overflow or +.B PROT_EXEC +mmap tracking) +are logged into a ring-buffer. +This ring-buffer is created and accessed through +.BR mmap (2). +.PP +The mmap size should be 1+2^n pages, where the first page is a +metadata page +.RI ( "struct perf_event_mmap_page" ) +that contains various +bits of information such as where the ring-buffer head is. +.PP +Before kernel 2.6.39, there is a bug that means you must allocate an mmap +ring buffer when sampling even if you do not plan to access it. +.PP +The structure of the first metadata mmap page is as follows: +.PP +.in +4n +.EX +struct perf_event_mmap_page { + __u32 version; /* version number of this structure */ + __u32 compat_version; /* lowest version this is compat with */ + __u32 lock; /* seqlock for synchronization */ + __u32 index; /* hardware counter identifier */ + __s64 offset; /* add to hardware counter value */ + __u64 time_enabled; /* time event active */ + __u64 time_running; /* time event on CPU */ + union { + __u64 capabilities; + struct { + __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1, + cap_bit0_is_deprecated : 1, + cap_user_rdpmc : 1, + cap_user_time : 1, + cap_user_time_zero : 1, + }; + }; + __u16 pmc_width; + __u16 time_shift; + __u32 time_mult; + __u64 time_offset; + __u64 __reserved[120]; /* Pad to 1 k */ + __u64 data_head; /* head in the data section */ + __u64 data_tail; /* user-space written tail */ + __u64 data_offset; /* where the buffer starts */ + __u64 data_size; /* data buffer size */ + __u64 aux_head; + __u64 aux_tail; + __u64 aux_offset; + __u64 aux_size; + +} +.EE +.in +.PP +The following list describes the fields in the +.I perf_event_mmap_page +structure in more detail: +.TP +.I version +Version number of this structure. +.TP +.I compat_version +The lowest version this is compatible with. +.TP +.I lock +A seqlock for synchronization. +.TP +.I index +A unique hardware counter identifier. +.TP +.I offset +When using rdpmc for reads this offset value +must be added to the one returned by rdpmc to get +the current total event count. +.TP +.I time_enabled +Time the event was active. +.TP +.I time_running +Time the event was running. +.TP +.IR cap_usr_time " / " cap_usr_rdpmc " / " cap_bit0 " (since Linux 3.4)" +.\" commit c7206205d00ab375839bd6c7ddb247d600693c09 +There was a bug in the definition of +.I cap_usr_time +and +.I cap_usr_rdpmc +from Linux 3.4 until Linux 3.11. +Both bits were defined to point to the same location, so it was +impossible to know if +.I cap_usr_time +or +.I cap_usr_rdpmc +were actually set. +.IP +Starting with Linux 3.12, these are renamed to +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +.I cap_bit0 +and you should use the +.I cap_user_time +and +.I cap_user_rdpmc +fields instead. +.TP +.IR cap_bit0_is_deprecated " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +If set, this bit indicates that the kernel supports +the properly separated +.I cap_user_time +and +.I cap_user_rdpmc +bits. +.IP +If not-set, it indicates an older kernel where +.I cap_usr_time +and +.I cap_usr_rdpmc +map to the same bit and thus both features should +be used with caution. +.TP +.IR cap_user_rdpmc " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +If the hardware supports user-space read of performance counters +without syscall (this is the "rdpmc" instruction on x86), then +the following code can be used to do a read: +.IP +.in +4n +.EX +u32 seq, time_mult, time_shift, idx, width; +u64 count, enabled, running; +u64 cyc, time_offset; + +do { + seq = pc\->lock; + barrier(); + enabled = pc\->time_enabled; + running = pc\->time_running; + + if (pc\->cap_usr_time && enabled != running) { + cyc = rdtsc(); + time_offset = pc\->time_offset; + time_mult = pc\->time_mult; + time_shift = pc\->time_shift; + } + + idx = pc\->index; + count = pc\->offset; + + if (pc\->cap_usr_rdpmc && idx) { + width = pc\->pmc_width; + count += rdpmc(idx \- 1); + } + + barrier(); +} while (pc\->lock != seq); +.EE +.in +.TP +.IR cap_user_time " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +This bit indicates the hardware has a constant, nonstop +timestamp counter (TSC on x86). +.TP +.IR cap_user_time_zero " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +Indicates the presence of +.I time_zero +which allows mapping timestamp values to +the hardware clock. +.TP +.I pmc_width +If +.IR cap_usr_rdpmc , +this field provides the bit-width of the value +read using the rdpmc or equivalent instruction. +This can be used to sign extend the result like: +.IP +.in +4n +.EX +pmc <<= 64 \- pmc_width; +pmc >>= 64 \- pmc_width; // signed shift right +count += pmc; +.EE +.in +.TP +.IR time_shift ", " time_mult ", " time_offset +.IP +If +.IR cap_usr_time , +these fields can be used to compute the time +delta since +.I time_enabled +(in nanoseconds) using rdtsc or similar. +.IP +.nf + u64 quot, rem; + u64 delta; + quot = (cyc >> time_shift); + rem = cyc & (((u64)1 << time_shift) \- 1); + delta = time_offset + quot * time_mult + + ((rem * time_mult) >> time_shift); +.fi +.IP +Where +.IR time_offset , +.IR time_mult , +.IR time_shift , +and +.IR cyc +are read in the +seqcount loop described above. +This delta can then be added to +enabled and possible running (if idx), improving the scaling: +.IP +.nf + enabled += delta; + if (idx) + running += delta; + quot = count / running; + rem = count % running; + count = quot * enabled + (rem * enabled) / running; +.fi +.TP +.IR time_zero " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +.IP +If +.I cap_usr_time_zero +is set, then the hardware clock (the TSC timestamp counter on x86) +can be calculated from the +.IR time_zero ", " time_mult ", and " time_shift " values:" +.IP +.nf + time = timestamp - time_zero; + quot = time / time_mult; + rem = time % time_mult; + cyc = (quot << time_shift) + (rem << time_shift) / time_mult; +.fi +.IP +And vice versa: +.IP +.nf + quot = cyc >> time_shift; + rem = cyc & (((u64)1 << time_shift) - 1); + timestamp = time_zero + quot * time_mult + + ((rem * time_mult) >> time_shift); +.fi +.TP +.I data_head +This points to the head of the data section. +The value continuously increases, it does not wrap. +The value needs to be manually wrapped by the size of the mmap buffer +before accessing the samples. +.IP +On SMP-capable platforms, after reading the +.I data_head +value, +user space should issue an rmb(). +.TP +.I data_tail +When the mapping is +.BR PROT_WRITE , +the +.I data_tail +value should be written by user space to reflect the last read data. +In this case, the kernel will not overwrite unread data. +.TP +.IR data_offset " (since Linux 4.1)" +.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f +Contains the offset of the location in the mmap buffer +where perf sample data begins. +.TP +.IR data_size " (since Linux 4.1)" +.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f +Contains the size of the perf sample region within +the mmap buffer. +.TP +.IR aux_head ", " aux_tail ", " aux_offset ", " aux_size " (since Linux 4.1) +.\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff +The AUX region allows mmaping a separate sample buffer for +high-bandwidth data streams (separate from the main perf sample buffer). +An example of a high-bandwidth stream is instruction tracing support, +as is found in newer Intel processors. +.IP +To set up an AUX area, first +.I aux_offset +needs to be set with an offset greater than +.IR data_offset + data_size +and +.I aux_size +needs to be set to the desired buffer size. +The desired offset and size must be page aligned, and the size +must be a power of two. +These values are then passed to mmap in order to map the AUX buffer. +Pages in the AUX buffer are included as part of the +.BR RLIMIT_MEMLOCK +resource limit (see +.BR setrlimit (2)), +and also as part of the +.I perf_event_mlock_kb +allowance. +.IP +By default, the AUX buffer will be truncated if it will not fit +in the available space in the ring buffer. +If the AUX buffer is mapped as a read only buffer, then it will +operate in ring buffer mode where old data will be overwritten +by new. +In overwrite mode, it might not be possible to infer where the +new data began, and it is the consumer's job to disable +measurement while reading to avoid possible data races. +.IP +The +.IR aux_head " and " aux_tail +ring buffer pointers have the same behavior and ordering +rules as the previous described +.IR data_head " and " data_tail . +.PP +The following 2^n ring-buffer pages have the layout described below. +.PP +If +.I perf_event_attr.sample_id_all +is set, then all event types will +have the sample_type selected fields related to where/when (identity) +an event took place (TID, TIME, ID, CPU, STREAM_ID) described in +.B PERF_RECORD_SAMPLE +below, it will be stashed just after the +.I perf_event_header +and the fields already present for the existing +fields, that is, at the end of the payload. +This allows a newer perf.data +file to be supported by older perf tools, with the new optional +fields being ignored. +.PP +The mmap values start with a header: +.PP +.in +4n +.EX +struct perf_event_header { + __u32 type; + __u16 misc; + __u16 size; +}; +.EE +.in +.PP +Below, we describe the +.I perf_event_header +fields in more detail. +For ease of reading, +the fields with shorter descriptions are presented first. +.TP +.I size +This indicates the size of the record. +.TP +.I misc +The +.I misc +field contains additional information about the sample. +.IP +The CPU mode can be determined from this value by masking with +.B PERF_RECORD_MISC_CPUMODE_MASK +and looking for one of the following (note these are not +bit masks, only one can be set at a time): +.RS +.TP +.B PERF_RECORD_MISC_CPUMODE_UNKNOWN +Unknown CPU mode. +.TP +.B PERF_RECORD_MISC_KERNEL +Sample happened in the kernel. +.TP +.B PERF_RECORD_MISC_USER +Sample happened in user code. +.TP +.B PERF_RECORD_MISC_HYPERVISOR +Sample happened in the hypervisor. +.TP +.BR PERF_RECORD_MISC_GUEST_KERNEL " (since Linux 2.6.35)" +.\" commit 39447b386c846bbf1c56f6403c5282837486200f +Sample happened in the guest kernel. +.TP +.B PERF_RECORD_MISC_GUEST_USER " (since Linux 2.6.35)" +.\" commit 39447b386c846bbf1c56f6403c5282837486200f +Sample happened in guest user code. +.RE +.PP +.RS +Since the following three statuses are generated by +different record types, they alias to the same bit: +.TP +.BR PERF_RECORD_MISC_MMAP_DATA " (since Linux 3.10)" +.\" commit 2fe85427e3bf65d791700d065132772fc26e4d75 +This is set when the mapping is not executable; +otherwise the mapping is executable. +.TP +.BR PERF_RECORD_MISC_COMM_EXEC " (since Linux 3.16)" +.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871 +This is set for a +.B PERF_RECORD_COMM +record on kernels more recent than Linux 3.16 +if a process name change was caused by an +.BR exec (2) +system call. +.TP +.BR PERF_RECORD_MISC_SWITCH_OUT " (since Linux 4.3)" +.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4 +When a +.BR PERF_RECORD_SWITCH +or +.BR PERF_RECORD_SWITCH_CPU_WIDE +record is generated, this bit indicates that the +context switch is away from the current process +(instead of into the current process). +.RE +.PP +.RS +In addition, the following bits can be set: +.TP +.B PERF_RECORD_MISC_EXACT_IP +This indicates that the content of +.B PERF_SAMPLE_IP +points +to the actual instruction that triggered the event. +See also +.IR perf_event_attr.precise_ip . +.TP +.BR PERF_RECORD_MISC_EXT_RESERVED " (since Linux 2.6.35)" +.\" commit 1676b8a077c352085d52578fb4f29350b58b6e74 +This indicates there is extended data available (currently not used). +.TP +.B PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT +.\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4 +This bit is not set by the kernel. +It is reserved for the user-space perf utility to indicate that +.I /proc/i[pid]/maps +parsing was taking too long and was stopped, and thus the mmap +records may be truncated. +.RE +.TP +.I type +The +.I type +value is one of the below. +The values in the corresponding record (that follows the header) +depend on the +.I type +selected as shown. +.RS +.TP 4 +.B PERF_RECORD_MMAP +The MMAP events record the +.B PROT_EXEC +mappings so that we can correlate +user-space IPs to code. +They have the following structure: +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid, tid; + u64 addr; + u64 len; + u64 pgoff; + char filename[]; +}; +.EE +.in +.RS +.TP +.I pid +is the process ID. +.TP +.I tid +is the thread ID. +.TP +.I addr +is the address of the allocated memory. +.I len +is the length of the allocated memory. +.I pgoff +is the page offset of the allocated memory. +.I filename +is a string describing the backing of the allocated memory. +.RE +.TP +.B PERF_RECORD_LOST +This record indicates when events are lost. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 id; + u64 lost; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I id +is the unique event ID for the samples that were lost. +.TP +.I lost +is the number of events that were lost. +.RE +.TP +.B PERF_RECORD_COMM +This record indicates a change in the process name. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid; + u32 tid; + char comm[]; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I pid +is the process ID. +.TP +.I tid +is the thread ID. +.TP +.I comm +is a string containing the new name of the process. +.RE +.TP +.B PERF_RECORD_EXIT +This record indicates a process exit event. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid, ppid; + u32 tid, ptid; + u64 time; + struct sample_id sample_id; +}; +.EE +.in +.TP +.BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE +This record indicates a throttle/unthrottle event. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 time; + u64 id; + u64 stream_id; + struct sample_id sample_id; +}; +.EE +.in +.TP +.B PERF_RECORD_FORK +This record indicates a fork event. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid, ppid; + u32 tid, ptid; + u64 time; + struct sample_id sample_id; +}; +.EE +.in +.TP +.B PERF_RECORD_READ +This record indicates a read event. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid, tid; + struct read_format values; + struct sample_id sample_id; +}; +.EE +.in +.TP +.B PERF_RECORD_SAMPLE +This record indicates a sample. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */ + u64 ip; /* if PERF_SAMPLE_IP */ + u32 pid, tid; /* if PERF_SAMPLE_TID */ + u64 time; /* if PERF_SAMPLE_TIME */ + u64 addr; /* if PERF_SAMPLE_ADDR */ + u64 id; /* if PERF_SAMPLE_ID */ + u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */ + u32 cpu, res; /* if PERF_SAMPLE_CPU */ + u64 period; /* if PERF_SAMPLE_PERIOD */ + struct read_format v; + /* if PERF_SAMPLE_READ */ + u64 nr; /* if PERF_SAMPLE_CALLCHAIN */ + u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */ + u32 size; /* if PERF_SAMPLE_RAW */ + char data[size]; /* if PERF_SAMPLE_RAW */ + u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */ + struct perf_branch_entry lbr[bnr]; + /* if PERF_SAMPLE_BRANCH_STACK */ + u64 abi; /* if PERF_SAMPLE_REGS_USER */ + u64 regs[weight(mask)]; + /* if PERF_SAMPLE_REGS_USER */ + u64 size; /* if PERF_SAMPLE_STACK_USER */ + char data[size]; /* if PERF_SAMPLE_STACK_USER */ + u64 dyn_size; /* if PERF_SAMPLE_STACK_USER && + size != 0 */ + u64 weight; /* if PERF_SAMPLE_WEIGHT */ + u64 data_src; /* if PERF_SAMPLE_DATA_SRC */ + u64 transaction; /* if PERF_SAMPLE_TRANSACTION */ + u64 abi; /* if PERF_SAMPLE_REGS_INTR */ + u64 regs[weight(mask)]; + /* if PERF_SAMPLE_REGS_INTR */ +}; +.EE +.RS 4 +.TP 4 +.I sample_id +If +.B PERF_SAMPLE_IDENTIFIER +is enabled, a 64-bit unique ID is included. +This is a duplication of the +.B PERF_SAMPLE_ID +.I id +value, but included at the beginning of the sample +so parsers can easily obtain the value. +.TP +.I ip +If +.B PERF_SAMPLE_IP +is enabled, then a 64-bit instruction +pointer value is included. +.TP +.IR pid ", " tid +If +.B PERF_SAMPLE_TID +is enabled, then a 32-bit process ID +and 32-bit thread ID are included. +.TP +.I time +If +.B PERF_SAMPLE_TIME +is enabled, then a 64-bit timestamp +is included. +This is obtained via local_clock() which is a hardware timestamp +if available and the jiffies value if not. +.TP +.I addr +If +.B PERF_SAMPLE_ADDR +is enabled, then a 64-bit address is included. +This is usually the address of a tracepoint, +breakpoint, or software event; otherwise the value is 0. +.TP +.I id +If +.B PERF_SAMPLE_ID +is enabled, a 64-bit unique ID is included. +If the event is a member of an event group, the group leader ID is returned. +This ID is the same as the one returned by +.BR PERF_FORMAT_ID . +.TP +.I stream_id +If +.B PERF_SAMPLE_STREAM_ID +is enabled, a 64-bit unique ID is included. +Unlike +.B PERF_SAMPLE_ID +the actual ID is returned, not the group leader. +This ID is the same as the one returned by +.BR PERF_FORMAT_ID . +.TP +.IR cpu ", " res +If +.B PERF_SAMPLE_CPU +is enabled, this is a 32-bit value indicating +which CPU was being used, in addition to a reserved (unused) +32-bit value. +.TP +.I period +If +.B PERF_SAMPLE_PERIOD +is enabled, a 64-bit value indicating +the current sampling period is written. +.TP +.I v +If +.B PERF_SAMPLE_READ +is enabled, a structure of type read_format +is included which has values for all events in the event group. +The values included depend on the +.I read_format +value used at +.BR perf_event_open () +time. +.TP +.IR nr ", " ips[nr] +If +.B PERF_SAMPLE_CALLCHAIN +is enabled, then a 64-bit number is included +which indicates how many following 64-bit instruction pointers will +follow. +This is the current callchain. +.TP +.IR size ", " data[size] +If +.B PERF_SAMPLE_RAW +is enabled, then a 32-bit value indicating size +is included followed by an array of 8-bit values of length size. +The values are padded with 0 to have 64-bit alignment. +.IP +This RAW record data is opaque with respect to the ABI. +The ABI doesn't make any promises with respect to the stability +of its content, it may vary depending +on event, hardware, and kernel version. +.TP +.IR bnr ", " lbr[bnr] +If +.B PERF_SAMPLE_BRANCH_STACK +is enabled, then a 64-bit value indicating +the number of records is included, followed by +.I bnr +.I perf_branch_entry +structures which each include the fields: +.RS +.TP +.I from +This indicates the source instruction (may not be a branch). +.TP +.I to +The branch target. +.TP +.I mispred +The branch target was mispredicted. +.TP +.I predicted +The branch target was predicted. +.TP +.IR in_tx " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +The branch was in a transactional memory transaction. +.TP +.IR abort " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +The branch was in an aborted transactional memory transaction. +.TP +.IR cycles " (since Linux 4.3)" +.\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f +This reports the number of cycles elapsed since the +previous branch stack update. +.PP +The entries are from most to least recent, so the first entry +has the most recent branch. +.PP +Support for +.IR mispred , +.IR predicted , +and +.IR cycles +is optional; if not supported, those +values will be 0. +.PP +The type of branches recorded is specified by the +.I branch_sample_type +field. +.RE +.TP +.IR abi ", " regs[weight(mask)] +If +.B PERF_SAMPLE_REGS_USER +is enabled, then the user CPU registers are recorded. +.IP +The +.I abi +field is one of +.BR PERF_SAMPLE_REGS_ABI_NONE ", " PERF_SAMPLE_REGS_ABI_32 " or " +.BR PERF_SAMPLE_REGS_ABI_64 . +.IP +The +.I regs +field is an array of the CPU registers that were specified by +the +.I sample_regs_user +attr field. +The number of values is the number of bits set in the +.I sample_regs_user +bit mask. +.TP +.IR size ", " data[size] ", " dyn_size +If +.B PERF_SAMPLE_STACK_USER +is enabled, then the user stack is recorded. +This can be used to generate stack backtraces. +.I size +is the size requested by the user in +.I sample_stack_user +or else the maximum record size. +.I data +is the stack data (a raw dump of the memory pointed to by the +stack pointer at the time of sampling). +.I dyn_size +is the amount of data actually dumped (can be less than +.IR size ). +Note that +.I dyn_size +is omitted if +.I size +is 0. +.TP +.I weight +If +.B PERF_SAMPLE_WEIGHT +is enabled, then a 64-bit value provided by the hardware +is recorded that indicates how costly the event was. +This allows expensive events to stand out more clearly +in profiles. +.TP +.I data_src +If +.B PERF_SAMPLE_DATA_SRC +is enabled, then a 64-bit value is recorded that is made up of +the following fields: +.RS +.TP 4 +.I mem_op +Type of opcode, a bitwise combination of: +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_OP_NA +Not available +.TP +.B PERF_MEM_OP_LOAD +Load instruction +.TP +.B PERF_MEM_OP_STORE +Store instruction +.TP +.B PERF_MEM_OP_PFETCH +Prefetch +.TP +.B PERF_MEM_OP_EXEC +Executable code +.RE +.PD +.TP +.I mem_lvl +Memory hierarchy level hit or miss, a bitwise combination of +the following, shifted left by +.BR PERF_MEM_LVL_SHIFT : +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_LVL_NA +Not available +.TP +.B PERF_MEM_LVL_HIT +Hit +.TP +.B PERF_MEM_LVL_MISS +Miss +.TP +.B PERF_MEM_LVL_L1 +Level 1 cache +.TP +.B PERF_MEM_LVL_LFB +Line fill buffer +.TP +.B PERF_MEM_LVL_L2 +Level 2 cache +.TP +.B PERF_MEM_LVL_L3 +Level 3 cache +.TP +.B PERF_MEM_LVL_LOC_RAM +Local DRAM +.TP +.B PERF_MEM_LVL_REM_RAM1 +Remote DRAM 1 hop +.TP +.B PERF_MEM_LVL_REM_RAM2 +Remote DRAM 2 hops +.TP +.B PERF_MEM_LVL_REM_CCE1 +Remote cache 1 hop +.TP +.B PERF_MEM_LVL_REM_CCE2 +Remote cache 2 hops +.TP +.B PERF_MEM_LVL_IO +I/O memory +.TP +.B PERF_MEM_LVL_UNC +Uncached memory +.RE +.PD +.TP +.I mem_snoop +Snoop mode, a bitwise combination of the following, shifted left by +.BR PERF_MEM_SNOOP_SHIFT : +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_SNOOP_NA +Not available +.TP +.B PERF_MEM_SNOOP_NONE +No snoop +.TP +.B PERF_MEM_SNOOP_HIT +Snoop hit +.TP +.B PERF_MEM_SNOOP_MISS +Snoop miss +.TP +.B PERF_MEM_SNOOP_HITM +Snoop hit modified +.RE +.PD +.TP +.I mem_lock +Lock instruction, a bitwise combination of the following, shifted left by +.BR PERF_MEM_LOCK_SHIFT : +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_LOCK_NA +Not available +.TP +.B PERF_MEM_LOCK_LOCKED +Locked transaction +.RE +.PD +.TP +.I mem_dtlb +TLB access hit or miss, a bitwise combination of the following, shifted +left by +.BR PERF_MEM_TLB_SHIFT : +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_TLB_NA +Not available +.TP +.B PERF_MEM_TLB_HIT +Hit +.TP +.B PERF_MEM_TLB_MISS +Miss +.TP +.B PERF_MEM_TLB_L1 +Level 1 TLB +.TP +.B PERF_MEM_TLB_L2 +Level 2 TLB +.TP +.B PERF_MEM_TLB_WK +Hardware walker +.TP +.B PERF_MEM_TLB_OS +OS fault handler +.RE +.PD +.RE +.TP +.I transaction +If the +.B PERF_SAMPLE_TRANSACTION +flag is set, then a 64-bit field is recorded describing +the sources of any transactional memory aborts. +.IP +The field is a bitwise combination of the following values: +.RS +.TP +.B PERF_TXN_ELISION +Abort from an elision type transaction (Intel-CPU-specific). +.TP +.B PERF_TXN_TRANSACTION +Abort from a generic transaction. +.TP +.B PERF_TXN_SYNC +Synchronous abort (related to the reported instruction). +.TP +.B PERF_TXN_ASYNC +Asynchronous abort (not related to the reported instruction). +.TP +.B PERF_TXN_RETRY +Retryable abort (retrying the transaction may have succeeded). +.TP +.B PERF_TXN_CONFLICT +Abort due to memory conflicts with other threads. +.TP +.B PERF_TXN_CAPACITY_WRITE +Abort due to write capacity overflow. +.TP +.B PERF_TXN_CAPACITY_READ +Abort due to read capacity overflow. +.RE +.IP +In addition, a user-specified abort code can be obtained from +the high 32 bits of the field by shifting right by +.B PERF_TXN_ABORT_SHIFT +and masking with the value +.BR PERF_TXN_ABORT_MASK . +.TP +.IR abi ", " regs[weight(mask)] +If +.B PERF_SAMPLE_REGS_INTR +is enabled, then the user CPU registers are recorded. +.IP +The +.I abi +field is one of +.BR PERF_SAMPLE_REGS_ABI_NONE , +.BR PERF_SAMPLE_REGS_ABI_32 , +or +.BR PERF_SAMPLE_REGS_ABI_64 . +.IP +The +.I regs +field is an array of the CPU registers that were specified by +the +.I sample_regs_intr +attr field. +The number of values is the number of bits set in the +.I sample_regs_intr +bit mask. +.RE +.TP +.B PERF_RECORD_MMAP2 +This record includes extended information on +.BR mmap (2) +calls returning executable mappings. +The format is similar to that of the +.B PERF_RECORD_MMAP +record, but includes extra values that allow uniquely identifying +shared mappings. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid; + u32 tid; + u64 addr; + u64 len; + u64 pgoff; + u32 maj; + u32 min; + u64 ino; + u64 ino_generation; + u32 prot; + u32 flags; + char filename[]; + struct sample_id sample_id; +}; +.EE +.RS +.TP +.I pid +is the process ID. +.TP +.I tid +is the thread ID. +.TP +.I addr +is the address of the allocated memory. +.TP +.I len +is the length of the allocated memory. +.TP +.I pgoff +is the page offset of the allocated memory. +.TP +.I maj +is the major ID of the underlying device. +.TP +.I min +is the minor ID of the underlying device. +.TP +.I ino +is the inode number. +.TP +.I ino_generation +is the inode generation. +.TP +.I prot +is the protection information. +.TP +.I flags +is the flags information. +.TP +.I filename +is a string describing the backing of the allocated memory. +.RE +.TP +.BR PERF_RECORD_AUX " (since Linux 4.1)" +\" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0 +This record reports that new data is available in the separate +AUX buffer region. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 aux_offset; + u64 aux_size; + u64 flags; + struct sample_id sample_id; +}; +.EE +.RS +.TP +.I aux_offset +offset in the AUX mmap region where the new data begins. +.TP +.I aux_size +size of the data made available. +.TP +.I flags +describes the AUX update. +.RS +.TP +.B PERF_AUX_FLAG_TRUNCATED +if set, then the data returned was truncated to fit the available +buffer size. +.TP +.B PERF_AUX_FLAG_OVERWRITE +.\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142 +if set, then the data returned has overwritten previous data. +.RE +.RE +.TP +.BR PERF_RECORD_ITRACE_START " (since Linux 4.1)" +\" ec0d7729bbaed4b9d2d3fada693278e13a3d1368 +This record indicates which process has initiated an instruction +trace event, allowing tools to properly correlate the instruction +addresses in the AUX buffer with the proper executable. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid; + u32 tid; +}; +.EE +.RS +.TP +.I pid +process ID of the thread starting an instruction trace. +.TP +.I tid +thread ID of the thread starting an instruction trace. +.RE +.TP +.BR PERF_RECORD_LOST_SAMPLES " (since Linux 4.2)" +\" f38b0dbb491a6987e198aa6b428db8692a6480f8 +When using hardware sampling (such as Intel PEBS) this record +indicates some number of samples that may have been lost. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 lost; + struct sample_id sample_id; +}; +.EE +.RS +.TP +.I lost +the number of potentially lost samples. +.RE +.TP +.BR PERF_RECORD_SWITCH " (since Linux 4.3)" +\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4 +This record indicates a context switch has happened. +The +.B PERF_RECORD_MISC_SWITCH_OUT +bit in the +.I misc +field indicates whether it was a context switch into +or away from the current process. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + struct sample_id sample_id; +}; +.EE +.TP +.BR PERF_RECORD_SWITCH_CPU_WIDE " (since Linux 4.3)" +\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4 +As with +.B PERF_RECORD_SWITCH +this record indicates a context switch has happened, +but it only occurs when sampling in CPU-wide mode +and provides additional information on the process +being switched to/from. +The +.B PERF_RECORD_MISC_SWITCH_OUT +bit in the +.I misc +field indicates whether it was a context switch into +or away from the current process. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 next_prev_pid; + u32 next_prev_tid; + struct sample_id sample_id; +}; +.EE +.RS +.TP +.I next_prev_pid +The process ID of the previous (if switching in) +or next (if switching out) process on the CPU. +.TP +.I next_prev_tid +The thread ID of the previous (if switching in) +or next (if switching out) thread on the CPU. +.RE +.RE +.SS Overflow handling +Events can be set to notify when a threshold is crossed, +indicating an overflow. +Overflow conditions can be captured by monitoring the +event file descriptor with +.BR poll (2), +.BR select (2), +or +.BR epoll (7). +Alternatively, the overflow events can be captured via sa signal handler, +by enabling I/O signaling on the file descriptor; see the discussion of the +.BR F_SETOWN +and +.BR F_SETSIG +operations in +.BR fcntl (2). +.PP +Overflows are generated only by sampling events +.RI ( sample_period +must have a nonzero value). +.PP +There are two ways to generate overflow notifications. +.PP +The first is to set a +.I wakeup_events +or +.I wakeup_watermark +value that will trigger if a certain number of samples +or bytes have been written to the mmap ring buffer. +In this case, +.B POLL_IN +is indicated. +.PP +The other way is by use of the +.B PERF_EVENT_IOC_REFRESH +ioctl. +This ioctl adds to a counter that decrements each time the event overflows. +When nonzero, +.B POLL_IN +is indicated, but +once the counter reaches 0 +.B POLL_HUP +is indicated and +the underlying event is disabled. +.PP +Refreshing an event group leader refreshes all siblings and +refreshing with a parameter of 0 currently enables infinite +refreshes; +these behaviors are unsupported and should not be relied on. +.\" See https://lkml.org/lkml/2011/5/24/337 +.PP +Starting with Linux 3.18, +.\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883 +.B POLL_HUP +is indicated if the event being monitored is attached to a different +process and that process exits. +.SS rdpmc instruction +Starting with Linux 3.4 on x86, you can use the +.\" commit c7206205d00ab375839bd6c7ddb247d600693c09 +.I rdpmc +instruction to get low-latency reads without having to enter the kernel. +Note that using +.I rdpmc +is not necessarily faster than other methods for reading event values. +.PP +Support for this can be detected with the +.I cap_usr_rdpmc +field in the mmap page; documentation on how +to calculate event values can be found in that section. +.PP +Originally, when rdpmc support was enabled, any process (not just ones +with an active perf event) could use the rdpmc instruction to access +the counters. +Starting with Linux 4.0, +.\" 7911d3f7af14a614617e38245fedf98a724e46a9 +rdpmc support is only allowed if an event is currently enabled +in a process's context. +To restore the old behavior, write the value 2 to +.IR /sys/devices/cpu/rdpmc . +.SS perf_event ioctl calls +.PP +Various ioctls act on +.BR perf_event_open () +file descriptors: +.TP +.B PERF_EVENT_IOC_ENABLE +This enables the individual event or event group specified by the +file descriptor argument. +.IP +If the +.B PERF_IOC_FLAG_GROUP +bit is set in the ioctl argument, then all events in a group are +enabled, even if the event specified is not the group leader +(but see BUGS). +.TP +.B PERF_EVENT_IOC_DISABLE +This disables the individual counter or event group specified by the +file descriptor argument. +.IP +Enabling or disabling the leader of a group enables or disables the +entire group; that is, while the group leader is disabled, none of the +counters in the group will count. +Enabling or disabling a member of a group other than the leader +affects only that counter; disabling a non-leader +stops that counter from counting but doesn't affect any other counter. +.IP +If the +.B PERF_IOC_FLAG_GROUP +bit is set in the ioctl argument, then all events in a group are +disabled, even if the event specified is not the group leader +(but see BUGS). +.TP +.B PERF_EVENT_IOC_REFRESH +Non-inherited overflow counters can use this +to enable a counter for a number of overflows specified by the argument, +after which it is disabled. +Subsequent calls of this ioctl add the argument value to the current +count. +An overflow notification with +.B POLL_IN +set will happen on each overflow until the +count reaches 0; when that happens a notification with +.B POLL_HUP +set is sent and the event is disabled. +Using an argument of 0 is considered undefined behavior. +.TP +.B PERF_EVENT_IOC_RESET +Reset the event count specified by the +file descriptor argument to zero. +This resets only the counts; there is no way to reset the +multiplexing +.I time_enabled +or +.I time_running +values. +.IP +If the +.B PERF_IOC_FLAG_GROUP +bit is set in the ioctl argument, then all events in a group are +reset, even if the event specified is not the group leader +(but see BUGS). +.TP +.B PERF_EVENT_IOC_PERIOD +This updates the overflow period for the event. +.IP +Since Linux 3.7 (on ARM) +.\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc +and Linux 3.14 (all other architectures), +.\" commit bad7192b842c83e580747ca57104dd51fe08c223 +the new period takes effect immediately. +On older kernels, the new period did not take effect until +after the next overflow. +.IP +The argument is a pointer to a 64-bit value containing the +desired new period. +.IP +Prior to Linux 2.6.36, +.\" commit ad0cf3478de8677f720ee06393b3147819568d6a +this ioctl always failed due to a bug +in the kernel. +.TP +.B PERF_EVENT_IOC_SET_OUTPUT +This tells the kernel to report event notifications to the specified +file descriptor rather than the default one. +The file descriptors must all be on the same CPU. +.IP +The argument specifies the desired file descriptor, or \-1 if +output should be ignored. +.TP +.BR PERF_EVENT_IOC_SET_FILTER " (since Linux 2.6.33)" +.\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830 +This adds an ftrace filter to this event. +.IP +The argument is a pointer to the desired ftrace filter. +.TP +.BR PERF_EVENT_IOC_ID " (since Linux 3.12)" +.\" commit cf4957f17f2a89984915ea808876d9c82225b862 +This returns the event ID value for the given event file descriptor. +.IP +The argument is a pointer to a 64-bit unsigned integer +to hold the result. +.TP +.BR PERF_EVENT_IOC_SET_BPF " (since Linux 4.1)" +.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 +This allows attaching a Berkeley Packet Filter (BPF) +program to an existing kprobe tracepoint event. +You need +.B CAP_SYS_ADMIN +privileges to use this ioctl. +.IP +The argument is a BPF program file descriptor that was created by +a previous +.BR bpf (2) +system call. +.SS Using prctl(2) +A process can enable or disable all the event groups that are +attached to it using the +.BR prctl (2) +.B PR_TASK_PERF_EVENTS_ENABLE +and +.B PR_TASK_PERF_EVENTS_DISABLE +operations. +This applies to all counters on the calling process, whether created by +this process or by another, and does not affect any counters that this +process has created on other processes. +It enables or disables only +the group leaders, not any other members in the groups. +.SS perf_event related configuration files +.PP +Files in +.I /proc/sys/kernel/ +.RS 4 +.TP +.I /proc/sys/kernel/perf_event_paranoid +The +.I perf_event_paranoid +file can be set to restrict access to the performance counters. +.IP +.PD 0 +.RS +.IP 2 4 +allow only user-space measurements (default since Linux 4.6). +.\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66 +.IP 1 +allow both kernel and user measurements (default before Linux 4.6). +.IP 0 +allow access to CPU-specific data but not raw tracepoint samples. +.IP \-1 +no restrictions. +.RE +.PD +.IP +The existence of the +.I perf_event_paranoid +file is the official method for determining if a kernel supports +.BR perf_event_open (). +.TP +.I /proc/sys/kernel/perf_event_max_sample_rate +This sets the maximum sample rate. +Setting this too high can allow +users to sample at a rate that impacts overall machine performance +and potentially lock up the machine. +The default value is +100000 (samples per second). +.TP +.I /proc/sys/kernel/perf_event_max_stack +.\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e +This file sets the maximum depth of stack frame entries reported +when generating a call trace. +.TP +.I /proc/sys/kernel/perf_event_mlock_kb +Maximum number of pages an unprivileged user can +.BR mlock (2). +The default is 516 (kB). +.RE +.PP +Files in +.I /sys/bus/event_source/devices/ +.PP +.RS 4 +Since Linux 2.6.34, the kernel supports having multiple PMUs +available for monitoring. +Information on how to program these PMUs can be found under +.IR /sys/bus/event_source/devices/ . +Each subdirectory corresponds to a different PMU. +.TP +.IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)" +.\" commit abe43400579d5de0078c2d3a760e6598e183f871 +This contains an integer that can be used in the +.I type +field of +.I perf_event_attr +to indicate that you wish to use this PMU. +.TP +.IR /sys/bus/event_source/devices/cpu/rdpmc " (since Linux 3.4)" +.\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f +If this file is 1, then direct user-space access to the +performance counter registers is allowed via the rdpmc instruction. +This can be disabled by echoing 0 to the file. +.IP +As of Linux 4.0 +.\" a66734297f78707ce39d756b656bfae861d53f62 +.\" 7911d3f7af14a614617e38245fedf98a724e46a9 +the behavior has changed, so that 1 now means only allow access +to processes with active perf events, with 2 indicating the old +allow-anyone-access behavior. +.TP +.IR /sys/bus/event_source/devices/*/format/ " (since Linux 3.4)" +.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33 +This subdirectory contains information on the architecture-specific +subfields available for programming the various +.I config +fields in the +.I perf_event_attr +struct. +.IP +The content of each file is the name of the config field, followed +by a colon, followed by a series of integer bit ranges separated by +commas. +For example, the file +.I event +may contain the value +.I config1:1,6\-10,44 +which indicates that event is an attribute that occupies bits 1,6\(en10, and 44 +of +.IR perf_event_attr::config1 . +.TP +.IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)" +.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33 +This subdirectory contains files with predefined events. +The contents are strings describing the event settings +expressed in terms of the fields found in the previously mentioned +.I ./format/ +directory. +These are not necessarily complete lists of all events supported by +a PMU, but usually a subset of events deemed useful or interesting. +.IP +The content of each file is a list of attribute names +separated by commas. +Each entry has an optional value (either hex or decimal). +If no value is specified, then it is assumed to be a single-bit +field with a value of 1. +An example entry may look like this: +.IR event=0x2,inv,ldlat=3 . +.TP +.I /sys/bus/event_source/devices/*/uevent +This file is the standard kernel device interface +for injecting hotplug events. +.TP +.IR /sys/bus/event_source/devices/*/cpumask " (since Linux 3.7)" +.\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac +The +.I cpumask +file contains a comma-separated list of integers that +indicate a representative CPU number for each socket (package) +on the motherboard. +This is needed when setting up uncore or northbridge events, as +those PMUs present socket-wide events. +.RE +.SH RETURN VALUE +.BR perf_event_open () +returns the new file descriptor, or \-1 if an error occurred +(in which case, +.I errno +is set appropriately). +.SH ERRORS +The errors returned by +.BR perf_event_open () +can be inconsistent, and may +vary across processor architectures and performance monitoring units. +.TP +.B E2BIG +Returned if the +.I perf_event_attr +.I size +value is too small +(smaller than +.BR PERF_ATTR_SIZE_VER0 ), +too big (larger than the page size), +or larger than the kernel supports and the extra bytes are not zero. +When +.B E2BIG +is returned, the +.I perf_event_attr +.I size +field is overwritten by the kernel to be the size of the structure +it was expecting. +.TP +.B EACCES +Returned when the requested event requires +.B CAP_SYS_ADMIN +permissions (or a more permissive perf_event paranoid setting). +Some common cases where an unprivileged process +may encounter this error: +attaching to a process owned by a different user; +monitoring all processes on a given CPU (i.e., specifying the +.I pid +argument as \-1); +and not setting +.I exclude_kernel +when the paranoid setting requires it. +.TP +.B EBADF +Returned if the +.I group_fd +file descriptor is not valid, or, if +.B PERF_FLAG_PID_CGROUP +is set, +the cgroup file descriptor in +.I pid +is not valid. +.TP +.BR EBUSY " (since Linux 4.1)" +.\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0 +Returned if another event already has exclusive +access to the PMU. +.TP +.B EFAULT +Returned if the +.I attr +pointer points at an invalid memory address. +.TP +.B EINVAL +Returned if the specified event is invalid. +There are many possible reasons for this. +A not-exhaustive list: +.I sample_freq +is higher than the maximum setting; +the +.I cpu +to monitor does not exist; +.I read_format +is out of range; +.I sample_type +is out of range; +the +.I flags +value is out of range; +.I exclusive +or +.I pinned +set and the event is not a group leader; +the event +.I config +values are out of range or set reserved bits; +the generic event selected is not supported; or +there is not enough room to add the selected event. +.TP +.B EMFILE +Each opened event uses one file descriptor. +If a large number of events are opened, +the per-process limit on the number of open file descriptors will be reached, +and no more events can be created. +.TP +.B ENODEV +Returned when the event involves a feature not supported +by the current CPU. +.TP +.B ENOENT +Returned if the +.I type +setting is not valid. +This error is also returned for +some unsupported generic events. +.TP +.B ENOSPC +Prior to Linux 3.3, if there was not enough room for the event, +.\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6 +.B ENOSPC +was returned. +In Linux 3.3, this was changed to +.BR EINVAL . +.B ENOSPC +is still returned if you try to add more breakpoint events +than supported by the hardware. +.TP +.B ENOSYS +Returned if +.B PERF_SAMPLE_STACK_USER +is set in +.I sample_type +and it is not supported by hardware. +.TP +.B EOPNOTSUPP +Returned if an event requiring a specific hardware feature is +requested but there is no hardware support. +This includes requesting low-skid events if not supported, +branch tracing if it is not available, sampling if no PMU +interrupt is available, and branch stacks for software events. +.TP +.BR EOVERFLOW " (since Linux 4.8)" +.\" 97c79a38cd454602645f0470ffb444b3b75ce574 +Returned if +.B PERF_SAMPLE_CALLCHAIN +is requested and +.I sample_max_stack +is larger than the maximum specified in +.IR /proc/sys/kernel/perf_event_max_stack . +.TP +.B EPERM +Returned on many (but not all) architectures when an unsupported +.IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel +setting is specified. +.IP +It can also happen, as with +.BR EACCES , +when the requested event requires +.B CAP_SYS_ADMIN +permissions (or a more permissive perf_event paranoid setting). +This includes setting a breakpoint on a kernel address, +and (since Linux 3.13) setting a kernel function-trace tracepoint. +.\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34 +.TP +.B ESRCH +Returned if attempting to attach to a process that does not exist. +.SH VERSION +.BR perf_event_open () +was introduced in Linux 2.6.31 but was called +.\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e +.BR perf_counter_open (). +It was renamed in Linux 2.6.32. +.\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6 +.SH CONFORMING TO +This +.BR perf_event_open () +system call Linux-specific +and should not be used in programs intended to be portable. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +See the example below. +.PP +The official way of knowing if +.BR perf_event_open () +support is enabled is checking +for the existence of the file +.IR /proc/sys/kernel/perf_event_paranoid . +.SH BUGS +The +.B F_SETOWN_EX +option to +.BR fcntl (2) +is needed to properly get overflow signals in threads. +This was introduced in Linux 2.6.32. +.\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5 +.PP +Prior to Linux 2.6.33 (at least for x86), +.\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1 +the kernel did not check +if events could be scheduled together until read time. +The same happens on all known kernels if the NMI watchdog is enabled. +This means to see if a given set of events works you have to +.BR perf_event_open (), +start, then read before you know for sure you +can get valid measurements. +.PP +Prior to Linux 2.6.34, +.\" FIXME . cannot find a kernel commit for this one +event constraints were not enforced by the kernel. +In that case, some events would silently return "0" if the kernel +scheduled them in an improper counter slot. +.PP +Prior to Linux 2.6.34, there was a bug when multiplexing where the +wrong results could be returned. +.\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8 +.PP +Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if +"inherit" is enabled and many threads are started. +.\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd +.PP +Prior to Linux 2.6.35, +.\" commit 050735b08ca8a016bbace4445fa025b88fee770b +.B PERF_FORMAT_GROUP +did not work with attached processes. +.PP +There is a bug in the kernel code between +Linux 2.6.36 and Linux 3.0 that ignores the +"watermark" field and acts as if a wakeup_event +was chosen if the union has a +nonzero value in it. +.\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02 +.PP +From Linux 2.6.31 to Linux 3.4, the +.B PERF_IOC_FLAG_GROUP +ioctl argument was broken and would repeatedly operate +on the event specified rather than iterating across +all sibling events in a group. +.\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e +.PP +From Linux 3.4 to Linux 3.11, the mmap +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +.I cap_usr_rdpmc +and +.I cap_usr_time +bits mapped to the same location. +Code should migrate to the new +.I cap_user_rdpmc +and +.I cap_user_time +fields instead. +.PP +Always double-check your results! +Various generalized events have had wrong values. +For example, retired branches measured +the wrong thing on AMD machines until Linux 2.6.35. +.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2 +.SH EXAMPLE +The following is a short example that measures the total +instruction count of a call to +.BR printf (3). +.PP +.EX +#include +#include +#include +#include +#include +#include +#include + +static long +perf_event_open(struct perf_event_attr *hw_event, pid_t pid, + int cpu, int group_fd, unsigned long flags) +{ + int ret; + + ret = syscall(__NR_perf_event_open, hw_event, pid, cpu, + group_fd, flags); + return ret; +} + +int +main(int argc, char **argv) +{ + struct perf_event_attr pe; + long long count; + int fd; + + memset(&pe, 0, sizeof(struct perf_event_attr)); + pe.type = PERF_TYPE_HARDWARE; + pe.size = sizeof(struct perf_event_attr); + pe.config = PERF_COUNT_HW_INSTRUCTIONS; + pe.disabled = 1; + pe.exclude_kernel = 1; + pe.exclude_hv = 1; + + fd = perf_event_open(&pe, 0, \-1, \-1, 0); + if (fd == \-1) { + fprintf(stderr, "Error opening leader %llx\\n", pe.config); + exit(EXIT_FAILURE); + } + + ioctl(fd, PERF_EVENT_IOC_RESET, 0); + ioctl(fd, PERF_EVENT_IOC_ENABLE, 0); + + printf("Measuring instruction count for this printf\\n"); + + ioctl(fd, PERF_EVENT_IOC_DISABLE, 0); + read(fd, &count, sizeof(long long)); + + printf("Used %lld instructions\\n", count); + + close(fd); +} +.EE +.SH SEE ALSO +.BR perf (1), +.BR fcntl (2), +.BR mmap (2), +.BR open (2), +.BR prctl (2), +.BR read (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/perfmonctl.2 b/man2/perfmonctl.2 new file mode 100644 index 0000000..8e598ea --- /dev/null +++ b/man2/perfmonctl.2 @@ -0,0 +1,217 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" and Copyright (C) 2013 Michael Kerrisk +.\" Written by Ivana Varekova +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PERFMONCTL 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +perfmonctl \- interface to IA-64 performance monitoring unit +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "long perfmonctl(int " fd ", int " cmd ", void *" arg ", int " narg "); +.fi +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The IA-64-specific +.BR perfmonctl () +system call provides an interface to the +PMU (performance monitoring unit). +The PMU consists of PMD (performance monitoring data) registers and +PMC (performance monitoring control) registers, +which gather hardware statistics. +.PP +.BR perfmonctl () +applies the operation +.I cmd +to the input arguments specified by +.IR arg . +The number of arguments is defined by \fInarg\fR. +The +.I fd +argument specifies the perfmon context to operate on. +.PP +Supported values for +.I cmd +are: +.TP +.B PFM_CREATE_CONTEXT +.nf +.BI "perfmonctl(int " fd ", PFM_CREATE_CONTEXT, pfarg_context_t *" ctxt ", 1); +.fi +Set up a context. +.IP +The +.I fd +parameter is ignored. +A new perfmon context is created as specified in +.I ctxt +and its file descriptor is returned in \fIctxt->ctx_fd\fR. +.IP +The file descriptor can be used in subsequent calls to +.BR perfmonctl () +and can be used to read event notifications (type +.IR pfm_msg_t ) +using +.BR read (2). +The file descriptor is pollable using +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +.IP +The context can be destroyed by calling +.BR close (2) +on the file descriptor. +.TP +.B PFM_WRITE_PMCS +.\" pfm_write_pmcs() +.nf +.BI "perfmonctl(int " fd ", PFM_WRITE_PMCS, pfarg_reg_t *" pmcs ", n); +.fi +Set PMC registers. +.TP +.B PFM_WRITE_PMDS +.nf +.BI "perfmonctl(int " fd ", PFM_WRITE_PMDS, pfarg_reg_t *" pmds ", n); +.fi +.\" pfm_write_pmds() +Set PMD registers. +.TP +.B PFM_READ_PMDS +.\" pfm_read_pmds() +.nf +.BI "perfmonctl(int " fd ", PFM_READ_PMDS, pfarg_reg_t *" pmds ", n); +.fi +Read PMD registers. +.TP +.B PFM_START +.\" pfm_start() +.nf +.\" .BI "perfmonctl(int " fd ", PFM_START, arg, 1); +.BI "perfmonctl(int " fd ", PFM_START, NULL, 0); +.fi +Start monitoring. +.TP +.B PFM_STOP +.\" pfm_stop() +.nf +.BI "perfmonctl(int " fd ", PFM_STOP, NULL, 0); +.fi +Stop monitoring. +.TP +.B PFM_LOAD_CONTEXT +.\" pfm_context_load() +.nf +.BI "perfmonctl(int " fd ", PFM_LOAD_CONTEXT, pfarg_load_t *" largs ", 1); +.fi +Attach the context to a thread. +.TP +.B PFM_UNLOAD_CONTEXT +.\" pfm_context_unload() +.nf +.BI "perfmonctl(int " fd ", PFM_UNLOAD_CONTEXT, NULL, 0); +.fi +Detach the context from a thread. +.TP +.B PFM_RESTART +.\" pfm_restart() +.nf +.BI "perfmonctl(int " fd ", PFM_RESTART, NULL, 0); +.fi +Restart monitoring after receiving an overflow notification. +.TP +.B PFM_GET_FEATURES +.\" pfm_get_features() +.nf +.BI "perfmonctl(int " fd ", PFM_GET_FEATURES, pfarg_features_t *" arg ", 1); +.fi +.TP +.B PFM_DEBUG +.\" pfm_debug() +.nf +.BI "perfmonctl(int " fd ", PFM_DEBUG, " val ", 0); +.fi +If +.I val +is nonzero, enable debugging mode, otherwise disable. +.TP +.B PFM_GET_PMC_RESET_VAL +.\" pfm_get_pmc_reset() +.nf +.BI "perfmonctl(int " fd ", PFM_GET_PMC_RESET_VAL, pfarg_reg_t *" req ", n); +.fi +Reset PMC registers to default values. +.\" +.\" +.\" .TP +.\" .B PFM_CREATE_EVTSETS +.\" +.\" create or modify event sets +.\" .nf +.\" .BI "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n); +.\" .fi +.\" .TP +.\" .B PFM_DELETE_EVTSETS +.\" delete event sets +.\" .nf +.\" .BI "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n); +.\" .fi +.\" .TP +.\" .B PFM_GETINFO_EVTSETS +.\" get information about event sets +.\" .nf +.\" .BI "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n); +.\" .fi +.SH RETURN VALUE +.BR perfmonctl () +returns zero when the operation is successful. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +.SH VERSIONS +.BR perfmonctl () +is available since Linux 2.4. +.SH CONFORMING TO +.BR perfmonctl () +is Linux-specific and is available only on the IA-64 architecture. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.SH SEE ALSO +.BR gprof (1) +.PP +The perfmon2 interface specification +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/personality.2 b/man2/personality.2 new file mode 100644 index 0000000..085462c --- /dev/null +++ b/man2/personality.2 @@ -0,0 +1,280 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" and Copyright (C) 2016, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created Sat Aug 21 1995 Thomas K. Dyas +.\" +.\" typo corrected, aeb, 950825 +.\" added layout change from joey, 960722 +.\" changed prototype, documented 0xffffffff, aeb, 030101 +.\" Modified 2004-11-03 patch from Martin Schulze +.\" +.TH PERSONALITY 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +personality \- set the process execution domain +.SH SYNOPSIS +.B #include +.PP +.BI "int personality(unsigned long " persona ); +.SH DESCRIPTION +Linux supports different execution domains, or personalities, for each +process. +Among other things, execution domains tell Linux how to map +signal numbers into signal actions. +The execution domain system allows +Linux to provide limited support for binaries compiled under other +UNIX-like operating systems. +.PP +If +.I persona +is not +0xffffffff, then +.BR personality () +sets the caller's execution domain to the value specified by +.IR persona . +Specifying +.IR persona +as 0xffffffff provides a way of retrieving +the current persona without changing it. +.PP +A list of the available execution domains can be found in +.IR . +The execution domain is a 32-bit value in which the top three +bytes are set aside for flags that cause the kernel to modify the +behavior of certain system calls so as to emulate historical or +architectural quirks. +The least significant byte is value defining the personality +the kernel should assume. +The flag values are as follows: +.TP +.BR ADDR_COMPAT_LAYOUT " (since Linux 2.6.9)" +With this flag set, provide legacy virtual address space layout. +.TP +.BR ADDR_NO_RANDOMIZE " (since Linux 2.6.12)" +With this flag set, disable address-space-layout randomization. +.TP +.BR ADDR_LIMIT_32BIT " (since Linux 2.2)" +Limit the address space to 32 bits. +.TP +.BR ADDR_LIMIT_3GB " (since Linux 2.4.0)" +With this flag set, use 0xc0000000 as the offset at which to search +a virtual memory chunk on +.BR mmap (2); +otherwise use 0xffffe000. +.TP +.BR FDPIC_FUNCPTRS " (since Linux 2.6.11)" +User-space function pointers to signal handlers point +(on certain architectures) to descriptors. +.TP +.BR MMAP_PAGE_ZERO " (since Linux 2.4.0)" +Map page 0 as read-only +(to support binaries that depend on this SVr4 behavior). +.TP +.BR READ_IMPLIES_EXEC " (since Linux 2.6.8)" +With this flag set, +.BR PROT_READ +implies +.BR PROT_EXEC +for +.BR mmap (2). +.TP +.BR SHORT_INODE " (since Linux 2.4.0)" +No effects(?). +.TP +.BR STICKY_TIMEOUTS " (since Linux 1.2.0)" +With this flag set, +.BR select (2), +.BR pselect (2), +and +.BR ppoll (2) +do not modify the returned timeout argument when +interrupted by a signal handler. +.TP +.BR UNAME26 " (since Linux 3.1)" +Have +.BR uname (2) +report a 2.6.40+ version number rather than a 3.x version number. +Added as a stopgap measure to support broken applications that +could not handle the kernel version-numbering switch from 2.6.x to 3.x. +.TP +.BR WHOLE_SECONDS " (since Linux 1.2.0)" +No effects(?). +.PP +The available execution domains are: +.TP +.BR PER_BSD " (since Linux 1.2.0)" +BSD. (No effects.) +.TP +.BR PER_HPUX " (since Linux 2.4)" +Support for 32-bit HP/UX. +This support was never complete, and was dropped so that since Linux 4.0, +this value has no effect. +.TP +.BR PER_IRIX32 " (since Linux 2.2)" +IRIX 5 32-bit. +Never fully functional; support dropped in Linux 2.6.27. +Implies +.BR STICKY_TIMEOUTS . +.TP +.BR PER_IRIX64 " (since Linux 2.2)" +IRIX 6 64-bit. +Implies +.BR STICKY_TIMEOUTS ; +otherwise no effects. +.TP +.BR PER_IRIXN32 " (since Linux 2.2)" +IRIX 6 new 32-bit. +Implies +.BR STICKY_TIMEOUTS ; +otherwise no effects. +.TP +.BR PER_ISCR4 " (since Linux 1.2.0)" +Implies +.BR STICKY_TIMEOUTS ; +otherwise no effects. +.TP +.BR PER_LINUX " (since Linux 1.2.0)" +Linux. +.TP +.BR PER_LINUX32 " (since Linux 2.2)" +[To be documented.] +.TP +.BR PER_LINUX32_3GB " (since Linux 2.4)" +Implies +.BR ADDR_LIMIT_3GB . +.TP +.BR PER_LINUX_32BIT " (since Linux 2.0)" +Implies +.BR ADDR_LIMIT_32BIT . +.TP +.BR PER_LINUX_FDPIC " (since Linux 2.6.11)" +Implies +.BR FDPIC_FUNCPTRS . +.TP +.BR PER_OSF4 " (since Linux 2.4)" +OSF/1 v4. +On alpha, +.\" Following is from a comment in arch/alpha/kernel/osf_sys.c +clear top 32 bits of iov_len in the user's buffer for +compatibility with old versions of OSF/1 where iov_len +was defined as. +.IR int . +.TP +.BR PER_OSR5 " (since Linux 2.4)" +Implies +.BR STICKY_TIMEOUTS +and +.BR WHOLE_SECONDS ; +otherwise no effects. +.TP +.BR PER_RISCOS " (since Linux 2.2)" +[To be documented.] +.TP +.BR PER_SCOSVR3 " (since Linux 1.2.0)" +Implies +.BR STICKY_TIMEOUTS , +.BR WHOLE_SECONDS , +and +.BR SHORT_INODE ; +otherwise no effects. +.TP +.BR PER_SOLARIS " (since Linux 2.4)" +Implies +.BR STICKY_TIMEOUTS ; +otherwise no effects. +.TP +.BR PER_SUNOS " (since Linux 2.4.0)" +Implies +.BR STICKY_TIMEOUTS . +Divert library and dynamic linker searches to +.IR /usr/gnemul . +Buggy, largely unmaintained, and almost entirely unused; +support was removed in Linux 2.6.26. +.TP +.BR PER_SVR3 " (since Linux 1.2.0)" +Implies +.BR STICKY_TIMEOUTS +and +.BR SHORT_INODE ; +otherwise no effects. +.TP +.BR PER_SVR4 " (since Linux 1.2.0)" +Implies +.BR STICKY_TIMEOUTS +and +.BR MMAP_PAGE_ZERO ; +otherwise no effects. +.TP +.BR PER_UW7 " (since Linux 2.4)" +Implies +.BR STICKY_TIMEOUTS +and +.BR MMAP_PAGE_ZERO ; +otherwise no effects. +.TP +.BR PER_WYSEV386 " (since Linux 1.2.0)" +Implies +.BR STICKY_TIMEOUTS +and +.BR SHORT_INODE ; +otherwise no effects. +.TP +.BR PER_XENIX " (since Linux 1.2.0)" +Implies +.BR STICKY_TIMEOUTS +and +.BR SHORT_INODE ; +otherwise no effects. +.SH RETURN VALUE +On success, the previous +.I persona +is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The kernel was unable to change the personality. +.SH VERSIONS +This system call first appeared in Linux 1.1.20 +(and thus first in a stable kernel release with Linux 1.2.0); +library support was added in glibc 2.3. +.\" personality wrapper first appeared in glibc 1.90, +.\" was added later in 2.2.91. +.SH CONFORMING TO +.BR personality () +is Linux-specific and should not be used in programs intended to +be portable. +.SH SEE ALSO +.BR setarch (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/phys.2 b/man2/phys.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/phys.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/pipe.2 b/man2/pipe.2 new file mode 100644 index 0000000..1f2e565 --- /dev/null +++ b/man2/pipe.2 @@ -0,0 +1,277 @@ +.\" Copyright (C) 2005, 2008, Michael Kerrisk +.\" (A few fragments remain from an earlier (1992) version by +.\" Drew Eckhardt .) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2005, mtk: added an example program +.\" Modified 2008-01-09, mtk: rewrote DESCRIPTION; minor additions +.\" to EXAMPLE text. +.\" 2008-10-10, mtk: add description of pipe2() +.\" +.TH PIPE 2 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +pipe, pipe2 \- create pipe +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pipe(int " pipefd "[2]);" + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.BR "#include " " /* Obtain O_* constant definitions */ +.B #include +.PP +.BI "int pipe2(int " pipefd "[2], int " flags ); +.fi +.SH DESCRIPTION +.BR pipe () +creates a pipe, a unidirectional data channel that +can be used for interprocess communication. +The array +.IR pipefd +is used to return two file descriptors referring to the ends of the pipe. +.IR pipefd[0] +refers to the read end of the pipe. +.IR pipefd[1] +refers to the write end of the pipe. +Data written to the write end of the pipe is buffered by the kernel +until it is read from the read end of the pipe. +For further details, see +.BR pipe (7). +.PP +If +.IR flags +is 0, then +.BR pipe2 () +is the same as +.BR pipe (). +The following values can be bitwise ORed in +.IR flags +to obtain different behavior: +.TP +.B O_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the two new file descriptors. +See the description of the same flag in +.BR open (2) +for reasons why this may be useful. +.TP +.BR O_DIRECT " (since Linux 3.4)" +.\" commit 9883035ae7edef3ec62ad215611cb8e17d6a1a5d +Create a pipe that performs I/O in "packet" mode. +Each +.BR write (2) +to the pipe is dealt with as a separate packet, and +.BR read (2)s +from the pipe will read one packet at a time. +Note the following points: +.RS +.IP * 3 +Writes of greater than +.BR PIPE_BUF +bytes (see +.BR pipe (7)) +will be split into multiple packets. +The constant +.BR PIPE_BUF +is defined in +.IR . +.IP * +If a +.BR read (2) +specifies a buffer size that is smaller than the next packet, +then the requested number of bytes are read, +and the excess bytes in the packet are discarded. +Specifying a buffer size of +.BR PIPE_BUF +will be sufficient to read the largest possible packets +(see the previous point). +.IP * +Zero-length packets are not supported. +(A +.BR read (2) +that specifies a buffer size of zero is a no-op, and returns 0.) +.RE +.IP +Older kernels that do not support this flag will indicate this via an +.B EINVAL +error. +.IP +Since Linux 4.5, +.\" commit 0dbf5f20652108106cb822ad7662c786baaa03ff +.\" FIXME . But, it is not possible to specify O_DIRECT when opening a FIFO +it is possible to change the +.B O_DIRECT +setting of a pipe file descriptor using +.BR fcntl (2). +.TP +.B O_NONBLOCK +Set the +.BR O_NONBLOCK +file status flag on the two new open file descriptions. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +On Linux (and other systems), +.BR pipe () +does not modify +.I pipefd +on failure. +A requirement standardizing this behavior was added in POSIX.1-2016. +.\" http://austingroupbugs.net/view.php?id=467 +The Linux-specific +.BR pipe2 () +system call +likewise does not modify +.I pipefd +on failure. +.SH ERRORS +.TP +.B EFAULT +.I pipefd +is not valid. +.TP +.B EINVAL +.RB ( pipe2 ()) +Invalid value in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENFILE +The user hard limit on memory that can be allocated for pipes +has been reached and the caller is not privileged; see +.BR pipe (7). +.SH VERSIONS +.BR pipe2 () +was added to Linux in version 2.6.27; +glibc support is available starting with +version 2.9. +.SH CONFORMING TO +.BR pipe (): +POSIX.1-2001, POSIX.1-2008. +.PP +.BR pipe2 () +is Linux-specific. +.SH EXAMPLE +.\" fork.2 refers to this example program. +The following program creates a pipe, and then +.BR fork (2)s +to create a child process; +the child inherits a duplicate set of file +descriptors that refer to the same pipe. +After the +.BR fork (2), +each process closes the file descriptors that it doesn't need for the pipe +(see +.BR pipe (7)). +The parent then writes the string contained in the program's +command-line argument to the pipe, +and the child reads this string a byte at a time from the pipe +and echoes it on standard output. +.SS Program source +.EX +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + int pipefd[2]; + pid_t cpid; + char buf; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + if (pipe(pipefd) == \-1) { + perror("pipe"); + exit(EXIT_FAILURE); + } + + cpid = fork(); + if (cpid == \-1) { + perror("fork"); + exit(EXIT_FAILURE); + } + + if (cpid == 0) { /* Child reads from pipe */ + close(pipefd[1]); /* Close unused write end */ + + while (read(pipefd[0], &buf, 1) > 0) + write(STDOUT_FILENO, &buf, 1); + + write(STDOUT_FILENO, "\\n", 1); + close(pipefd[0]); + _exit(EXIT_SUCCESS); + + } else { /* Parent writes argv[1] to pipe */ + close(pipefd[0]); /* Close unused read end */ + write(pipefd[1], argv[1], strlen(argv[1])); + close(pipefd[1]); /* Reader will see EOF */ + wait(NULL); /* Wait for child */ + exit(EXIT_SUCCESS); + } +} +.EE +.SH SEE ALSO +.BR fork (2), +.BR read (2), +.BR socketpair (2), +.BR splice (2), +.BR tee (2), +.BR vmsplice (2), +.BR write (2), +.BR popen (3), +.BR pipe (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/pipe2.2 b/man2/pipe2.2 new file mode 100644 index 0000000..980e240 --- /dev/null +++ b/man2/pipe2.2 @@ -0,0 +1 @@ +.so man2/pipe.2 diff --git a/man2/pivot_root.2 b/man2/pivot_root.2 new file mode 100644 index 0000000..9536d76 --- /dev/null +++ b/man2/pivot_root.2 @@ -0,0 +1,155 @@ +.\" Copyright (C) 2000 by Werner Almesberger +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" May be distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Written 2000-02-23 by Werner Almesberger +.\" Modified 2004-06-17 Michael Kerrisk +.\" +.TH PIVOT_ROOT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pivot_root \- change the root filesystem +.SH SYNOPSIS +.BI "int pivot_root(const char *" new_root ", const char *" put_old ); +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.BR pivot_root () +moves the root filesystem of the calling process to the +directory \fIput_old\fP and makes \fInew_root\fP the new root filesystem +of the calling process. +.\" +.\" The +.\" .B CAP_SYS_ADMIN +.\" capability is required. +.PP +The typical use of +.BR pivot_root () +is during system startup, when the +system mounts a temporary root filesystem (e.g., an \fBinitrd\fP), then +mounts the real root filesystem, and eventually turns the latter into +the current root of all relevant processes or threads. +.PP +.BR pivot_root () +may or may not change the current root and the current +working directory of any processes or threads which use the old +root directory. +The caller of +.BR pivot_root () +must ensure that processes with root or current working directory +at the old root operate correctly in either case. +An easy way to ensure this is to change their +root and current working directory to \fInew_root\fP before invoking +.BR pivot_root (). +.PP +The paragraph above is intentionally vague because the implementation of +.BR pivot_root () +may change in the future. +At the time of writing, +.BR pivot_root () +changes root and current working directory of each process or +thread to \fInew_root\fP if they point to the old root directory. +This is necessary in order to prevent kernel threads from keeping the old +root directory busy with their root and current working directory, +even if they never access +the filesystem in any way. +In the future, there may be a mechanism for +kernel threads to explicitly relinquish any access to the filesystem, +such that this fairly intrusive mechanism can be removed from +.BR pivot_root (). +.PP +Note that this also applies to the calling process: +.BR pivot_root () +may or may not affect its current working directory. +It is therefore recommended to call +\fBchdir("/")\fP immediately after +.BR pivot_root (). +.PP +The following restrictions apply to \fInew_root\fP and \fIput_old\fP: +.IP \- 3 +They must be directories. +.IP \- 3 +\fInew_root\fP and \fIput_old\fP must not be on the same filesystem as +the current root. +.IP \- 3 +\fIput_old\fP must be underneath \fInew_root\fP, that is, adding a nonzero +number of \fI/..\fP to the string pointed to by \fIput_old\fP must yield +the same directory as \fInew_root\fP. +.IP \- 3 +No other filesystem may be mounted on \fIput_old\fP. +.PP +See also +.BR pivot_root (8) +for additional usage examples. +.PP +If the current root is not a mount point (e.g., after +.BR chroot (2) +or +.BR pivot_root (), +see also below), not the old root directory, but the +mount point of that filesystem is mounted on \fIput_old\fP. +.PP +\fInew_root\fP does not have to be a mount point. +In this case, +\fI/proc/mounts\fP will show the mount point of the filesystem containing +\fInew_root\fP as root (\fI/\fP). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +\fIerrno\fP is set appropriately. +.SH ERRORS +.BR pivot_root () +may return (in \fIerrno\fP) any of the errors returned by +.BR stat (2). +Additionally, it may return: +.TP +.B EBUSY +\fInew_root\fP or \fIput_old\fP are on the current root filesystem, +or a filesystem is already mounted on \fIput_old\fP. +.TP +.B EINVAL +\fIput_old\fP is not underneath \fInew_root\fP. +.TP +.B ENOTDIR +\fInew_root\fP or \fIput_old\fP is not a directory. +.TP +.B EPERM +The calling process does not have the +.B CAP_SYS_ADMIN +capability. +.SH VERSIONS +.BR pivot_root () +was introduced in Linux 2.3.41. +.SH CONFORMING TO +.BR pivot_root () +is Linux-specific and hence is not portable. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.SH BUGS +.BR pivot_root () +should not have to change root and current working directory of all other +processes in the system. +.PP +Some of the more obscure uses of +.BR pivot_root () +may quickly lead to +insanity. +.SH SEE ALSO +.BR chdir (2), +.BR chroot (2), +.BR stat (2), +.BR initrd (4), +.BR pivot_root (8), +.BR switch_root (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/pkey_alloc.2 b/man2/pkey_alloc.2 new file mode 100644 index 0000000..6658d19 --- /dev/null +++ b/man2/pkey_alloc.2 @@ -0,0 +1,148 @@ +.\" Copyright (C) 2016 Intel Corporation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and author of this work. +.\" %%%LICENSE_END +.\" +.TH PKEY_ALLOC 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +pkey_alloc, pkey_free \- allocate or free a protection key +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pkey_alloc(unsigned long " flags ", unsigned long " access_rights ");" +.BI "int pkey_free(int " pkey ");" +.fi +.SH DESCRIPTION +.BR pkey_alloc () +allocates a protection key (pkey) and allows it to be passed to +.BR pkey_mprotect (2). +.PP +The +.BR pkey_alloc () +.I flags +is reserved for future use and currently must always be specified as 0. +.PP +The +.BR pkey_alloc () +.I access_rights +.BR +argument may contain zero or more disable operations: +.TP +.B PKEY_DISABLE_ACCESS +Disable all data access to memory covered by the returned protection key. +.TP +.B PKEY_DISABLE_WRITE +Disable write access to memory covered by the returned protection key. +.PP +.BR pkey_free () +frees a protection key and makes it available for later +allocations. +After a protection key has been freed, it may no longer be used +in any protection-key-related operations. +.PP +An application should not call +.BR pkey_free () +on any protection key which has been assigned to an address +range by +.BR pkey_mprotect (2) +and which is still in use. +The behavior in this case is undefined and may result in an error. +.SH RETURN VALUE +On success, +.BR pkey_alloc () +returns a positive protection key value. +On success, +.BR pkey_free () +returns zero. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +.IR pkey , +.IR flags , +or +.I access_rights +is invalid. +.TP +.B ENOSPC +.RB ( pkey_alloc ()) +All protection keys available for the current process have +been allocated. +The number of keys available is architecture-specific and +implementation-specific and may be reduced by kernel-internal use +of certain keys. +There are currently 15 keys available to user programs on x86. +.IP +This error will also be returned if the processor or operating system +does not support protection keys. +Applications should always be prepared to handle this error, since +factors outside of the application's control can reduce the number +of available pkeys. +.SH VERSIONS +.BR pkey_alloc () +and +.BR pkey_free () +were added to Linux in kernel 4.9; +library support was added in glibc 2.27. +.SH CONFORMING TO +The +.BR pkey_alloc () +and +.BR pkey_free () +system calls are Linux-specific. +.SH NOTES +.BR pkey_alloc () +is always safe to call regardless of whether or not the operating system +supports protection keys. +It can be used in lieu of any other mechanism for detecting pkey support +and will simply fail with the error +.B ENOSPC +if the operating system has no pkey support. +.PP +The kernel guarantees that the contents of the hardware rights +register (PKRU) will be preserved only for allocated protection +keys. +Any time a key is unallocated (either before the first call +returning that key from +.BR pkey_alloc () +or after it is freed via +.BR pkey_free ()), +the kernel may make arbitrary changes to the parts of the +rights register affecting access to that key. +.SH EXAMPLE +See +.BR pkeys (7). +.SH SEE ALSO +.BR pkey_mprotect (2), +.BR pkeys (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/pkey_free.2 b/man2/pkey_free.2 new file mode 100644 index 0000000..5b524cb --- /dev/null +++ b/man2/pkey_free.2 @@ -0,0 +1 @@ +.so man2/pkey_alloc.2 diff --git a/man2/pkey_mprotect.2 b/man2/pkey_mprotect.2 new file mode 100644 index 0000000..b4f9309 --- /dev/null +++ b/man2/pkey_mprotect.2 @@ -0,0 +1 @@ +.so man2/mprotect.2 diff --git a/man2/poll.2 b/man2/poll.2 new file mode 100644 index 0000000..ea4fed9 --- /dev/null +++ b/man2/poll.2 @@ -0,0 +1,458 @@ +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2006, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Additions from Richard Gooch and aeb, 971207 +.\" 2006-03-13, mtk, Added ppoll() + various other rewordings +.\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and +.\" formatting changes. +.\" +.TH POLL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +poll, ppoll \- wait for some event on a file descriptor +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout ); + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.B #include +.PP +.BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", " +.BI " const struct timespec *" tmo_p ", const sigset_t *" sigmask ); +.fi +.SH DESCRIPTION +.BR poll () +performs a similar task to +.BR select (2): +it waits for one of a set of file descriptors to become ready +to perform I/O. +.PP +The set of file descriptors to be monitored is specified in the +.I fds +argument, which is an array of structures of the following form: +.PP +.in +4n +.EX +struct pollfd { + int fd; /* file descriptor */ + short events; /* requested events */ + short revents; /* returned events */ +}; +.EE +.in +.PP +The caller should specify the number of items in the +.I fds +array in +.IR nfds . +.PP +The field +.I fd +contains a file descriptor for an open file. +If this field is negative, then the corresponding +.I events +field is ignored and the +.I revents +field returns zero. +(This provides an easy way of ignoring a +file descriptor for a single +.BR poll () +call: simply negate the +.I fd +field. +Note, however, that this technique can't be used to ignore file descriptor 0.) +.PP +The field +.I events +is an input parameter, a bit mask specifying the events the application +is interested in for the file descriptor +.IR fd . +This field may be specified as zero, +in which case the only events that can be returned in +.I revents +are +.BR POLLHUP , +.BR POLLERR , +and +.B POLLNVAL +(see below). +.PP +The field +.I revents +is an output parameter, filled by the kernel with the events that +actually occurred. +The bits returned in +.I revents +can include any of those specified in +.IR events , +or one of the values +.BR POLLERR , +.BR POLLHUP , +or +.BR POLLNVAL . +(These three bits are meaningless in the +.I events +field, and will be set in the +.I revents +field whenever the corresponding condition is true.) +.PP +If none of the events requested (and no error) has occurred for any +of the file descriptors, then +.BR poll () +blocks until one of the events occurs. +.PP +The +.I timeout +argument specifies the number of milliseconds that +.BR poll () +should block waiting for a file descriptor to become ready. +The call will block until either: +.IP * 3 +a file descriptor becomes ready; +.IP * +the call is interrupted by a signal handler; or +.IP * +the timeout expires. +.PP +Note that the +.I timeout +interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the blocking interval +may overrun by a small amount. +Specifying a negative value in +.I timeout +means an infinite timeout. +Specifying a +.I timeout +of zero causes +.BR poll () +to return immediately, even if no file descriptors are ready. +.PP +The bits that may be set/returned in +.I events +and +.I revents +are defined in \fI\fP: +.TP +.B POLLIN +There is data to read. +.TP +.B POLLPRI +There is some exceptional condition on the file descriptor. +Possibilities include: +.RS +.IP * 3 +There is out-of-band data on a TCP socket (see +.BR tcp (7)). +.IP * +A pseudoterminal master in packet mode has seen a state change on the slave +(see +.BR ioctl_tty (2)). +.IP * +A +.I cgroup.events +file has been modified (see +.BR cgroups (7)). +.RE +.TP +.B POLLOUT +Writing is now possible, though a write larger that the available space +in a socket or pipe will still block (unless +.B O_NONBLOCK +is set). +.TP +.BR POLLRDHUP " (since Linux 2.6.17)" +Stream socket peer closed connection, +or shut down writing half of connection. +The +.B _GNU_SOURCE +feature test macro must be defined +(before including +.I any +header files) +in order to obtain this definition. +.TP +.B POLLERR +Error condition (only returned in +.IR revents ; +ignored in +.IR events ). +This bit is also set for a file descriptor referring +to the write end of a pipe when the read end has been closed. +.TP +.B POLLHUP +Hang up (only returned in +.IR revents ; +ignored in +.IR events ). +Note that when reading from a channel such as a pipe or a stream socket, +this event merely indicates that the peer closed its end of the channel. +Subsequent reads from the channel will return 0 (end of file) +only after all outstanding data in the channel has been consumed. +.TP +.B POLLNVAL +Invalid request: +.I fd +not open (only returned in +.IR revents ; +ignored in +.IR events ). +.PP +When compiling with +.B _XOPEN_SOURCE +defined, one also has the following, +which convey no further information beyond the bits listed above: +.TP +.B POLLRDNORM +Equivalent to +.BR POLLIN . +.TP +.B POLLRDBAND +Priority band data can be read (generally unused on Linux). +.\" POLLRDBAND is used in the DECnet protocol. +.TP +.B POLLWRNORM +Equivalent to +.BR POLLOUT . +.TP +.B POLLWRBAND +Priority data may be written. +.PP +Linux also knows about, but does not use +.BR POLLMSG . +.SS ppoll() +The relationship between +.BR poll () +and +.BR ppoll () +is analogous to the relationship between +.BR select (2) +and +.BR pselect (2): +like +.BR pselect (2), +.BR ppoll () +allows an application to safely wait until either a file descriptor +becomes ready or until a signal is caught. +.PP +Other than the difference in the precision of the +.I timeout +argument, the following +.BR ppoll () +call: +.PP +.in +4n +.EX +ready = ppoll(&fds, nfds, tmo_p, &sigmask); +.EE +.in +.PP +is equivalent to +.I atomically +executing the following calls: +.PP +.in +4n +.EX +sigset_t origmask; +int timeout; + +timeout = (tmo_p == NULL) ? \-1 : + (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000); +pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); +ready = poll(&fds, nfds, timeout); +pthread_sigmask(SIG_SETMASK, &origmask, NULL); +.EE +.in +.PP +See the description of +.BR pselect (2) +for an explanation of why +.BR ppoll () +is necessary. +.PP +If the +.I sigmask +argument is specified as NULL, then +no signal mask manipulation is performed +(and thus +.BR ppoll () +differs from +.BR poll () +only in the precision of the +.I timeout +argument). +.PP +The +.I tmo_p +argument specifies an upper limit on the amount of time that +.BR ppoll () +will block. +This argument is a pointer to a structure of the following form: +.PP +.in +4n +.EX +struct timespec { + long tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.PP +If +.I tmo_p +is specified as NULL, then +.BR ppoll () +can block indefinitely. +.SH RETURN VALUE +On success, a positive number is returned; this is +the number of structures which have nonzero +.I revents +fields (in other words, those descriptors with events or errors reported). +A value of 0 indicates that the call timed out and no file +descriptors were ready. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +The array given as argument was not contained in the calling program's +address space. +.TP +.B EINTR +A signal occurred before any requested event; see +.BR signal (7). +.TP +.B EINVAL +The +.I nfds +value exceeds the +.B RLIMIT_NOFILE +value. +.TP +.B ENOMEM +There was no space to allocate file descriptor tables. +.SH VERSIONS +The +.BR poll () +system call was introduced in Linux 2.1.23. +On older kernels that lack this system call, +.\" library call was introduced in libc 5.4.28 +the glibc (and the old Linux libc) +.BR poll () +wrapper function provides emulation using +.BR select (2). +.PP +The +.BR ppoll () +system call was added to Linux in kernel 2.6.16. +The +.BR ppoll () +library call was added in glibc 2.4. +.SH CONFORMING TO +.BR poll () +conforms to POSIX.1-2001 and POSIX.1-2008. +.BR ppoll () +is Linux-specific. +.\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). +.SH NOTES +On some other UNIX systems, +.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett +.BR poll () +can fail with the error +.B EAGAIN +if the system fails to allocate kernel-internal resources, rather than +.B ENOMEM +as Linux does. +POSIX permits this behavior. +Portable programs may wish to check for +.B EAGAIN +and loop, just as with +.BR EINTR . +.PP +Some implementations define the nonstandard constant +.B INFTIM +with the value \-1 for use as a +.IR timeout +for +.BR poll (). +This constant is not provided in glibc. +.PP +For a discussion of what may happen if a file descriptor being monitored by +.BR poll () +is closed in another thread, see +.BR select (2). +.SS C library/kernel differences +The Linux +.BR ppoll () +system call modifies its +.I tmo_p +argument. +However, the glibc wrapper function hides this behavior +by using a local variable for the timeout argument that +is passed to the system call. +Thus, the glibc +.BR ppoll () +function does not modify its +.I tmo_p +argument. +.PP +The raw +.BR ppoll () +system call has a fifth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the +.IR sigmask +argument. +The glibc +.BR ppoll () +wrapper function specifies this argument as a fixed value +(equal to +.IR sizeof(kernel_sigset_t) ). +See +.BR sigprocmask (2) +for a discussion on the differences between the kernel and the libc +notion of the sigset. +.SH BUGS +See the discussion of spurious readiness notifications under the +BUGS section of +.BR select (2). +.SH SEE ALSO +.BR restart_syscall (2), +.BR select (2), +.BR select_tut (2), +.BR epoll (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 new file mode 100644 index 0000000..8f4fedf --- /dev/null +++ b/man2/posix_fadvise.2 @@ -0,0 +1,248 @@ +.\" Copyright 2003 Abhijit Menon-Sen +.\" and Copyright (C) 2010, 2015, 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2005-04-08 mtk, noted kernel version and added BUGS +.\" 2010-10-09, mtk, document arm_fadvise64_64() +.\" +.TH POSIX_FADVISE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +posix_fadvise \- predeclare an access pattern for file data +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \ +", int " advice ");" +.fi +.PP +.ad l +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR posix_fadvise (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +Programs can use +.BR posix_fadvise () +to announce an intention to access +file data in a specific pattern in the future, thus allowing the kernel +to perform appropriate optimizations. +.PP +The \fIadvice\fP applies to a (not necessarily existent) region starting +at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of +the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. +The \fIadvice\fP is not binding; +it merely constitutes an expectation on behalf of +the application. +.PP +Permissible values for \fIadvice\fP include: +.TP +.B POSIX_FADV_NORMAL +Indicates that the application has no advice to give about its access +pattern for the specified data. +If no advice is given for an open file, +this is the default assumption. +.TP +.B POSIX_FADV_SEQUENTIAL +The application expects to access the specified data sequentially (with +lower offsets read before higher ones). +.TP +.B POSIX_FADV_RANDOM +The specified data will be accessed in random order. +.TP +.B POSIX_FADV_NOREUSE +The specified data will be accessed only once. +.IP +In kernels before 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the +same semantics as \fBPOSIX_FADV_WILLNEED\fP. +This was probably a bug; since kernel 2.6.18, this flag is a no-op. +.TP +.B POSIX_FADV_WILLNEED +The specified data will be accessed in the near future. +.IP +\fBPOSIX_FADV_WILLNEED\fP initiates a +nonblocking read of the specified region into the page cache. +The amount of data read may be decreased by the kernel depending +on virtual memory load. +(A few megabytes will usually be fully satisfied, +and more is rarely useful.) +.TP +.B POSIX_FADV_DONTNEED +The specified data will not be accessed in the near future. +.IP +\fBPOSIX_FADV_DONTNEED\fP attempts to free cached pages associated with +the specified region. +This is useful, for example, while streaming large +files. +A program may periodically request the kernel to free cached data +that has already been used, so that more useful cached pages are not +discarded instead. +.IP +Requests to discard partial pages are ignored. +It is preferable to preserve needed data than discard unneeded data. +If the application requires that data be considered for discarding, then +.I offset +and +.I len +must be page-aligned. +.IP +The implementation +.I may +attempt to write back dirty pages in the specified region, +but this is not guaranteed. +Any unwritten dirty pages will not be freed. +If the application wishes to ensure that dirty pages will be released, +it should call +.BR fsync (2) +or +.BR fdatasync (2) +first. +.SH RETURN VALUE +On success, zero is returned. +On error, an error number is returned. +.SH ERRORS +.TP +.B EBADF +The \fIfd\fP argument was not a valid file descriptor. +.TP +.B EINVAL +An invalid value was specified for \fIadvice\fP. +.TP +.B ESPIPE +The specified file descriptor refers to a pipe or FIFO. +.RB ( ESPIPE +is the error specified by POSIX, +but before kernel version 2.6.16, +.\" commit 87ba81dba431232548ce29d5d224115d0c2355ac +Linux returned +.B EINVAL +in this case.) +.SH VERSIONS +Kernel support first appeared in Linux 2.5.60; +the underlying system call is called +.BR fadvise64 (). +.\" of fadvise64_64() +Library support has been provided since glibc version 2.2, +via the wrapper function +.BR posix_fadvise (). +.PP +Since Linux 3.18, +.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb +support for the underlying system call is optional, +depending on the setting of the +.B CONFIG_ADVISE_SYSCALLS +configuration option. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +Note that the type of the +.I len +argument was changed from +.I size_t +to +.I off_t +in POSIX.1-2003 TC1. +.SH NOTES +Under Linux, \fBPOSIX_FADV_NORMAL\fP sets the readahead window to the +default size for the backing device; \fBPOSIX_FADV_SEQUENTIAL\fP doubles +this size, and \fBPOSIX_FADV_RANDOM\fP disables file readahead entirely. +These changes affect the entire file, not just the specified region +(but other open file handles to the same file are unaffected). +.PP +The contents of the kernel buffer cache can be cleared via the +.IR /proc/sys/vm/drop_caches +interface described in +.BR proc (5). +.PP +One can obtain a snapshot of which pages of a file are resident +in the buffer cache by opening a file, mapping it with +.BR mmap (2), +and then applying +.BR mincore (2) +to the mapping. +.SS C library/kernel differences +The name of the wrapper function in the C library is +.BR posix_fadvise (). +The underlying system call is called +.BR fadvise64 () +(or, on some architectures, +.BR fadvise64_64 ()). +.SS Architecture-specific variants +Some architectures require +64-bit arguments to be aligned in a suitable pair of registers (see +.BR syscall (2) +for further detail). +On such architectures, the call signature of +.BR posix_fadvise () +shown in the SYNOPSIS would force +a register to be wasted as padding between the +.I fd +and +.I offset +arguments. +Therefore, these architectures define a version of the +system call that orders the arguments suitably, +but is otherwise exactly the same as +.BR posix_fadvise (). +.PP +For example, since Linux 2.6.14, ARM has the following system call: +.PP +.in +4n +.EX +.BI "long arm_fadvise64_64(int " fd ", int " advice , +.BI " loff_t " offset ", loff_t " len ); +.EE +.in +.PP +These architecture-specific details are generally +hidden from applications by the glibc +.BR posix_fadvise () +wrapper function, +which invokes the appropriate architecture-specific system call. +.SH BUGS +In kernels before 2.6.6, if +.I len +was specified as 0, then this was interpreted literally as "zero bytes", +rather than as meaning "all bytes through to the end of the file". +.SH SEE ALSO +.BR fincore (1), +.BR mincore (2), +.BR readahead (2), +.BR sync_file_range (2), +.BR posix_fallocate (3), +.BR posix_madvise (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ppoll.2 b/man2/ppoll.2 new file mode 100644 index 0000000..227cd0e --- /dev/null +++ b/man2/ppoll.2 @@ -0,0 +1 @@ +.so man2/poll.2 diff --git a/man2/prctl.2 b/man2/prctl.2 new file mode 100644 index 0000000..b99596f --- /dev/null +++ b/man2/prctl.2 @@ -0,0 +1,1607 @@ +.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2002, 2006, 2008, 2012, 2013 Michael Kerrisk +.\" and Copyright Guillem Jover +.\" and Copyright (C) 2014 Dave Hansen / Intel +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG +.\" Modified 27 Jun 02, Michael Kerrisk +.\" Added PR_SET_DUMPABLE, PR_GET_DUMPABLE, +.\" PR_SET_KEEPCAPS, PR_GET_KEEPCAPS +.\" Modified 2006-08-30 Guillem Jover +.\" Updated Linux versions where the options where introduced. +.\" Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME, +.\" PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU, +.\" PR_SET_FPEXC, PR_GET_FPEXC +.\" 2008-04-29 Serge Hallyn, Document PR_CAPBSET_READ and PR_CAPBSET_DROP +.\" 2008-06-13 Erik Bosman, +.\" Document PR_GET_TSC and PR_SET_TSC. +.\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP +.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL +.\" 2012-04 Cyrill Gorcunov, Document PR_SET_MM +.\" 2012-04-25 Michael Kerrisk, Document PR_TASK_PERF_EVENTS_DISABLE and +.\" PR_TASK_PERF_EVENTS_ENABLE +.\" 2012-09-20 Kees Cook, update PR_SET_SECCOMP for mode 2 +.\" 2012-09-20 Kees Cook, document PR_SET_NO_NEW_PRIVS, PR_GET_NO_NEW_PRIVS +.\" 2012-10-25 Michael Kerrisk, Document PR_SET_TIMERSLACK and +.\" PR_GET_TIMERSLACK +.\" 2013-01-10 Kees Cook, document PR_SET_PTRACER +.\" 2012-02-04 Michael Kerrisk, document PR_{SET,GET}_CHILD_SUBREAPER +.\" 2014-11-10 Dave Hansen, document PR_MPX_{EN,DIS}ABLE_MANAGEMENT +.\" +.\" +.TH PRCTL 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +prctl \- operations on a process +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 , +.BI " unsigned long " arg4 ", unsigned long " arg5 ); +.fi +.SH DESCRIPTION +.BR prctl () +is called with a first argument describing what to do +(with values defined in \fI\fP), and further +arguments with a significance depending on the first one. +The first argument can be: +.\" +.TP +.BR PR_CAP_AMBIENT " (since Linux 4.3)" +.\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08 +Reads or changes the ambient capability set of the calling thread, +according to the value of +.IR arg2 , +which must be one of the following: +.RS +.\" +.TP +.B PR_CAP_AMBIENT_RAISE +The capability specified in +.I arg3 +is added to the ambient set. +The specified capability must already be present in +both the permitted and the inheritable sets of the process. +This operation is not permitted if the +.B SECBIT_NO_CAP_AMBIENT_RAISE +securebit is set. +.TP +.B PR_CAP_AMBIENT_LOWER +The capability specified in +.I arg3 +is removed from the ambient set. +.TP +.B PR_CAP_AMBIENT_IS_SET +The +.BR prctl () +call returns 1 if the capability in +.I arg3 +is in the ambient set and 0 if it is not. +.TP +.BR PR_CAP_AMBIENT_CLEAR_ALL +All capabilities will be removed from the ambient set. +This operation requires setting +.I arg3 +to zero. +.RE +.IP +In all of the above operations, +.I arg4 +and +.I arg5 +must be specified as 0. +.TP +.BR PR_CAPBSET_READ " (since Linux 2.6.25)" +Return (as the function result) 1 if the capability specified in +.I arg2 +is in the calling thread's capability bounding set, +or 0 if it is not. +(The capability constants are defined in +.IR .) +The capability bounding set dictates +whether the process can receive the capability through a +file's permitted capability set on a subsequent call to +.BR execve (2). +.IP +If the capability specified in +.I arg2 +is not valid, then the call fails with the error +.BR EINVAL . +.TP +.BR PR_CAPBSET_DROP " (since Linux 2.6.25)" +If the calling thread has the +.B CAP_SETPCAP +capability within its user namespace, then drop the capability specified by +.I arg2 +from the calling thread's capability bounding set. +Any children of the calling thread will inherit the newly +reduced bounding set. +.IP +The call fails with the error: +.B EPERM +if the calling thread does not have the +.BR CAP_SETPCAP ; +.BR EINVAL +if +.I arg2 +does not represent a valid capability; or +.BR EINVAL +if file capabilities are not enabled in the kernel, +in which case bounding sets are not supported. +.TP +.BR PR_SET_CHILD_SUBREAPER " (since Linux 3.4)" +.\" commit ebec18a6d3aa1e7d84aab16225e87fd25170ec2b +If +.I arg2 +is nonzero, +set the "child subreaper" attribute of the calling process; +if +.I arg2 +is zero, unset the attribute. +.IP +A subreaper fulfills the role of +.BR init (1) +for its descendant processes. +When a process becomes orphaned +(i.e., its immediate parent terminates) +then that process will be reparented to +the nearest still living ancestor subreaper. +Subsequently, calls to +.BR getppid () +in the orphaned process will now return the PID of the subreaper process, +and when the orphan terminates, it is the subreaper process that +will receive a +.BR SIGCHLD +signal and will be able to +.BR wait (2) +on the process to discover its termination status. +.IP +The setting of this bit is not inherited by children created by +.BR fork (2) +and +.BR clone (2). +The setting is preserved across +.BR execve (2). +.IP +Establishing a subreaper process is useful in session management frameworks +where a hierarchical group of processes is managed by a subreaper process +that needs to be informed when one of the processes\(emfor example, +a double-forked daemon\(emterminates +(perhaps so that it can restart that process). +Some +.BR init (1) +frameworks (e.g., +.BR systemd (1)) +employ a subreaper process for similar reasons. +.TP +.BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)" +Return the "child subreaper" setting of the caller, +in the location pointed to by +.IR "(int\ *) arg2" . +.TP +.BR PR_SET_DUMPABLE " (since Linux 2.3.20)" +Set the state of the "dumpable" flag, +which determines whether core dumps are produced for the calling process +upon delivery of a signal whose default behavior is to produce a core dump. +.IP +In kernels up to and including 2.6.12, +.I arg2 +must be either 0 +.RB ( SUID_DUMP_DISABLE , +process is not dumpable) or 1 +.RB ( SUID_DUMP_USER , +process is dumpable). +Between kernels 2.6.13 and 2.6.17, +.\" commit abf75a5033d4da7b8a7e92321d74021d1fcfb502 +the value 2 was also permitted, +which caused any binary which normally would not be dumped +to be dumped readable by root only; +for security reasons, this feature has been removed. +.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2 +.\" Subject: Fix prctl privilege escalation (CVE-2006-2451) +.\" From: Marcel Holtmann +.\" Date: 2006-07-12 11:12:00 +(See also the description of +.I /proc/sys/fs/\:suid_dumpable +in +.BR proc (5).) +.IP +Normally, this flag is set to 1. +However, it is reset to the current value contained in the file +.IR /proc/sys/fs/\:suid_dumpable +(which by default has the value 0), +in the following circumstances: +.\" See kernel/cred.c::commit_creds() (Linux 3.18 sources) +.RS +.IP * 3 +The process's effective user or group ID is changed. +.IP * +The process's filesystem user or group ID is changed (see +.BR credentials (7)). +.IP * +The process executes +.RB ( execve (2)) +a set-user-ID or set-group-ID program, resulting in a change +of either the effective user ID or the effective group ID. +.IP * +The process executes +.RB ( execve (2)) +a program that has file capabilities (see +.BR capabilities (7)), +.\" See kernel/cred.c::commit_creds() +but only if the permitted capabilities +gained exceed those already permitted for the process. +.\" Also certain namespace operations; +.RE +.IP +Processes that are not dumpable can not be attached via +.BR ptrace (2) +.BR PTRACE_ATTACH ; +see +.BR ptrace (2) +for further details. +.IP +If a process is not dumpable, +the ownership of files in the process's +.IR /proc/[pid] +directory is affected as described in +.BR proc (5). +.TP +.BR PR_GET_DUMPABLE " (since Linux 2.3.20)" +Return (as the function result) the current state of the calling +process's dumpable flag. +.\" Since Linux 2.6.13, the dumpable flag can have the value 2, +.\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable +.\" flags has a nonzero value. This was fixed in 2.6.14. +.TP +.BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)" +Set the endian-ness of the calling process to the value given +in \fIarg2\fP, which should be one of the following: +.\" Respectively 0, 1, 2 +.BR PR_ENDIAN_BIG , +.BR PR_ENDIAN_LITTLE , +or +.B PR_ENDIAN_PPC_LITTLE +(PowerPC pseudo little endian). +.TP +.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)" +Return the endian-ness of the calling process, +in the location pointed to by +.IR "(int\ *) arg2" . +.TP +.BR PR_SET_FP_MODE " (since Linux 4.0, only on MIPS)" +.\" commit 9791554b45a2acc28247f66a5fd5bbc212a6b8c8 +On the MIPS architecture, +user-space code can be built using an ABI which permits linking +with code that has more restrictive floating-point (FP) requirements. +For example, user-space code may be built to target the O32 FPXX ABI +and linked with code built for either one of the more restrictive +FP32 or FP64 ABIs. +When more restrictive code is linked in, +the overall requirement for the process is to use the more +restrictive floating-point mode. +.IP +Because the kernel has no means of knowing in advance +which mode the process should be executed in, +and because these restrictions can +change over the lifetime of the process, the +.B PR_SET_FP_MODE +operation is provided to allow control of the floating-point mode +from user space. +.IP +.\" https://dmz-portal.mips.com/wiki/MIPS_O32_ABI_-_FR0_and_FR1_Interlinking +The +.I (unsigned int) arg2 +argument is a bit mask describing the floating-point mode used: +.RS +.TP +.BR PR_FP_MODE_FR +When this bit is +.I unset +(so called +.BR FR=0 " or " FR0 +mode), the 32 floating-point registers are 32 bits wide, +and 64-bit registers are represented as a pair of registers +(even- and odd- numbered, +with the even-numbered register containing the lower 32 bits, +and the odd-numbered register containing the higher 32 bits). +.IP +When this bit is +.I set +(on supported hardware), +the 32 floating-point registers are 64 bits wide (so called +.BR FR=1 " or " FR1 +mode). +Note that modern MIPS implementations (MIPS R6 and newer) support +.B FR=1 +mode only. +.IP +.IP +Applications that use the O32 FP32 ABI can operate only when this bit is +.I unset +.RB ( FR=0 ; +or they can be used with FRE enabled, see below). +Applications that use the O32 FP64 ABI +(and the O32 FP64A ABI, which exists to +provide the ability to operate with existing FP32 code; see below) +can operate only when this bit is +.I set +.RB ( FR=1 ). +Applications that use the O32 FPXX ABI can operate with either +.BR FR=0 +or +.BR FR=1 . +.TP +.BR PR_FP_MODE_FRE +Enable emulation of 32-bit floating-point mode. +When this mode is enabled, +it emulates 32-bit floating-point operations +by raising a reserved-instruction exception +on every instruction that uses 32-bit formats and +the kernel then handles the instruction in software. +(The problem lies in the discrepancy of handling odd-numbered registers +which are the high 32 bits of 64-bit registers with even numbers in +.B FR=0 +mode and the lower 32-bit parts of odd-numbered 64-bit registers in +.B FR=1 +mode.) +Enabling this bit is necessary when code with the O32 FP32 ABI should operate +with code with compatible the O32 FPXX or O32 FP64A ABIs (which require +.B FR=1 +FPU mode) or when it is executed on newer hardware (MIPS R6 onwards) +which lacks +.B FR=0 +mode support when a binary with the FP32 ABI is used. +.IP +Note that this mode makes sense only when the FPU is in 64-bit mode +.RB ( FR=1 ). +.IP +Note that the use of emulation inherently has a significant performance hit +and should be avoided if possible. +.RE +.IP +In the N32/N64 ABI, 64-bit floating-point mode is always used, +so FPU emulation is not required and the FPU always operates in +.B FR=1 +mode. +.IP +This option is mainly intended for use by the dynamic linker +.RB ( ld.so (8)). +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.TP +.BR PR_GET_FP_MODE " (since Linux 4.0, only on MIPS)" +Get the current floating-point mode (see the description of +.B PR_SET_FP_MODE +for details). +.IP +On success, +the call returns a bit mask which represents the current floating-point mode. +.IP +The arguments +.IR arg2 , +.IR arg3 , +.IR arg4 , +and +.IR arg5 +are ignored. +.TP +.BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)" +Set floating-point emulation control bits to \fIarg2\fP. +Pass +.B PR_FPEMU_NOPRINT +to silently emulate floating-point operation accesses, or +.B PR_FPEMU_SIGFPE +to not emulate floating-point operations and send +.B SIGFPE +instead. +.TP +.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)" +Return floating-point emulation control bits, +in the location pointed to by +.IR "(int\ *) arg2" . +.TP +.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)" +Set floating-point exception mode to \fIarg2\fP. +Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables, +\fBPR_FP_EXC_DIV\fP for floating-point divide by zero, +\fBPR_FP_EXC_OVF\fP for floating-point overflow, +\fBPR_FP_EXC_UND\fP for floating-point underflow, +\fBPR_FP_EXC_RES\fP for floating-point inexact result, +\fBPR_FP_EXC_INV\fP for floating-point invalid operation, +\fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled, +\fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode, +\fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode, +\fBPR_FP_EXC_PRECISE\fP for precise exception mode. +.TP +.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)" +Return floating-point exception mode, +in the location pointed to by +.IR "(int\ *) arg2" . +.TP +.BR PR_SET_KEEPCAPS " (since Linux 2.2.18)" +Set the state of the calling thread's "keep capabilities" flag. +The effect if this flag is described in +.BR capabilities (7). +.I arg2 +must be either 0 (clear the flag) +or 1 (set the flag). +The "keep capabilities" value will be reset to 0 on subsequent calls to +.BR execve (2). +.TP +.BR PR_GET_KEEPCAPS " (since Linux 2.2.18)" +Return (as the function result) the current state of the calling thread's +"keep capabilities" flag. +See +.BR capabilities (7) +for a description of this flag. +.TP +.BR PR_MCE_KILL " (since Linux 2.6.32)" +Set the machine check memory corruption kill policy for the calling thread. +If +.I arg2 +is +.BR PR_MCE_KILL_CLEAR , +clear the thread memory corruption kill policy and use the system-wide default. +(The system-wide default is defined by +.IR /proc/sys/vm/memory_failure_early_kill ; +see +.BR proc (5).) +If +.I arg2 +is +.BR PR_MCE_KILL_SET , +use a thread-specific memory corruption kill policy. +In this case, +.I arg3 +defines whether the policy is +.I early kill +.RB ( PR_MCE_KILL_EARLY ), +.I late kill +.RB ( PR_MCE_KILL_LATE ), +or the system-wide default +.RB ( PR_MCE_KILL_DEFAULT ). +Early kill means that the thread receives a +.B SIGBUS +signal as soon as hardware memory corruption is detected inside +its address space. +In late kill mode, the process is killed only when it accesses a corrupted page. +See +.BR sigaction (2) +for more information on the +.BR SIGBUS +signal. +The policy is inherited by children. +The remaining unused +.BR prctl () +arguments must be zero for future compatibility. +.TP +.BR PR_MCE_KILL_GET " (since Linux 2.6.32)" +Return the current per-process machine check kill policy. +All unused +.BR prctl () +arguments must be zero. +.TP +.BR PR_SET_MM " (since Linux 3.3)" +.\" commit 028ee4be34a09a6d48bdf30ab991ae933a7bc036 +Modify certain kernel memory map descriptor fields +of the calling process. +Usually these fields are set by the kernel and dynamic loader (see +.BR ld.so (8) +for more information) and a regular application should not use this feature. +However, there are cases, such as self-modifying programs, +where a program might find it useful to change its own memory map. +.IP +The calling process must have the +.BR CAP_SYS_RESOURCE +capability. +The value in +.I arg2 +is one of the options below, while +.I arg3 +provides a new value for the option. +The +.I arg4 +and +.I arg5 +arguments must be zero if unused. +.IP +.\" commit 52b3694157e3aa6df871e283115652ec6f2d31e0 +Since Linux 3.10, +this feature is available all the time. +Before Linux 3.10, +this feature is available only if the kernel is built with the +.BR CONFIG_CHECKPOINT_RESTORE +option enabled. +.RS +.TP +.BR PR_SET_MM_START_CODE +Set the address above which the program text can run. +The corresponding memory area must be readable and executable, +but not writable or shareable (see +.BR mprotect (2) +and +.BR mmap (2) +for more information). +.TP +.BR PR_SET_MM_END_CODE +Set the address below which the program text can run. +The corresponding memory area must be readable and executable, +but not writable or shareable. +.TP +.BR PR_SET_MM_START_DATA +Set the address above which initialized and +uninitialized (bss) data are placed. +The corresponding memory area must be readable and writable, +but not executable or shareable. +.TP +.B PR_SET_MM_END_DATA +Set the address below which initialized and +uninitialized (bss) data are placed. +The corresponding memory area must be readable and writable, +but not executable or shareable. +.TP +.BR PR_SET_MM_START_STACK +Set the start address of the stack. +The corresponding memory area must be readable and writable. +.TP +.BR PR_SET_MM_START_BRK +Set the address above which the program heap can be expanded with +.BR brk (2) +call. +The address must be greater than the ending address of +the current program data segment. +In addition, the combined size of the resulting heap and +the size of the data segment can't exceed the +.BR RLIMIT_DATA +resource limit (see +.BR setrlimit (2)). +.TP +.BR PR_SET_MM_BRK +Set the current +.BR brk (2) +value. +The requirements for the address are the same as for the +.BR PR_SET_MM_START_BRK +option. +.PP +The following options are available since Linux 3.5. +.\" commit fe8c7f5cbf91124987106faa3bdf0c8b955c4cf7 +.TP +.BR PR_SET_MM_ARG_START +Set the address above which the program command line is placed. +.TP +.BR PR_SET_MM_ARG_END +Set the address below which the program command line is placed. +.TP +.BR PR_SET_MM_ENV_START +Set the address above which the program environment is placed. +.TP +.BR PR_SET_MM_ENV_END +Set the address below which the program environment is placed. +.IP +The address passed with +.BR PR_SET_MM_ARG_START , +.BR PR_SET_MM_ARG_END , +.BR PR_SET_MM_ENV_START , +and +.BR PR_SET_MM_ENV_END +should belong to a process stack area. +Thus, the corresponding memory area must be readable, writable, and +(depending on the kernel configuration) have the +.BR MAP_GROWSDOWN +attribute set (see +.BR mmap (2)). +.TP +.BR PR_SET_MM_AUXV +Set a new auxiliary vector. +The +.I arg3 +argument should provide the address of the vector. +The +.I arg4 +is the size of the vector. +.TP +.BR PR_SET_MM_EXE_FILE +.\" commit b32dfe377102ce668775f8b6b1461f7ad428f8b6 +Supersede the +.IR /proc/pid/exe +symbolic link with a new one pointing to a new executable file +identified by the file descriptor provided in +.I arg3 +argument. +The file descriptor should be obtained with a regular +.BR open (2) +call. +.IP +To change the symbolic link, one needs to unmap all existing +executable memory areas, including those created by the kernel itself +(for example the kernel usually creates at least one executable +memory area for the ELF +.IR \.text +section). +.IP +The second limitation is that such transitions can be done only once +in a process life time. +Any further attempts will be rejected. +This should help system administrators monitor unusual +symbolic-link transitions over all processes running on a system. +.PP +The following options are available since Linux 3.18. +.\" commit f606b77f1a9e362451aca8f81d8f36a3a112139e +.TP +.BR PR_SET_MM_MAP +Provides one-shot access to all the addresses by passing in a +.I struct prctl_mm_map +(as defined in \fI\fP). +The +.I arg4 +argument should provide the size of the struct. +.IP +This feature is available only if the kernel is built with the +.BR CONFIG_CHECKPOINT_RESTORE +option enabled. +.TP +.BR PR_SET_MM_MAP_SIZE +Returns the size of the +.I struct prctl_mm_map +the kernel expects. +This allows user space to find a compatible struct. +The +.I arg4 +argument should be a pointer to an unsigned int. +.IP +This feature is available only if the kernel is built with the +.BR CONFIG_CHECKPOINT_RESTORE +option enabled. +.RE +.TP +.BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19) " +.\" commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c +.\" See also http://lwn.net/Articles/582712/ +.\" See also https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler +Enable or disable kernel management of Memory Protection eXtensions (MPX) +bounds tables. +The +.IR arg2 , +.IR arg3 , +.IR arg4 , +and +.IR arg5 +.\" commit e9d1b4f3c60997fe197bf0243cb4a41a44387a88 +arguments must be zero. +.IP +MPX is a hardware-assisted mechanism for performing bounds checking on +pointers. +It consists of a set of registers storing bounds information +and a set of special instruction prefixes that tell the CPU on which +instructions it should do bounds enforcement. +There is a limited number of these registers and +when there are more pointers than registers, +their contents must be "spilled" into a set of tables. +These tables are called "bounds tables" and the MPX +.BR prctl () +operations control +whether the kernel manages their allocation and freeing. +.IP +When management is enabled, the kernel will take over allocation +and freeing of the bounds tables. +It does this by trapping the #BR exceptions that result +at first use of missing bounds tables and +instead of delivering the exception to user space, +it allocates the table and populates the bounds directory +with the location of the new table. +For freeing, the kernel checks to see if bounds tables are +present for memory which is not allocated, and frees them if so. +.IP +Before enabling MPX management using +.BR PR_MPX_ENABLE_MANAGEMENT , +the application must first have allocated a user-space buffer for +the bounds directory and placed the location of that directory in the +.I bndcfgu +register. +.IP +These calls fail if the CPU or kernel does not support MPX. +Kernel support for MPX is enabled via the +.BR CONFIG_X86_INTEL_MPX +configuration option. +You can check whether the CPU supports MPX by looking for the 'mpx' +CPUID bit, like with the following command: +.IP + cat /proc/cpuinfo | grep ' mpx ' +.IP +A thread may not switch in or out of long (64-bit) mode while MPX is +enabled. +.IP +All threads in a process are affected by these calls. +.IP +The child of a +.BR fork (2) +inherits the state of MPX management. +During +.BR execve (2), +MPX management is reset to a state as if +.BR PR_MPX_DISABLE_MANAGEMENT +had been called. +.IP +For further information on Intel MPX, see the kernel source file +.IR Documentation/x86/intel_mpx.txt . +.TP +.BR PR_SET_NAME " (since Linux 2.6.9)" +Set the name of the calling thread, +using the value in the location pointed to by +.IR "(char\ *) arg2" . +The name can be up to 16 bytes long, +.\" TASK_COMM_LEN in include/linux/sched.h +including the terminating null byte. +(If the length of the string, including the terminating null byte, +exceeds 16 bytes, the string is silently truncated.) +This is the same attribute that can be set via +.BR pthread_setname_np (3) +and retrieved using +.BR pthread_getname_np (3). +The attribute is likewise accessible via +.IR /proc/self/task/[tid]/comm , +where +.I tid +is the name of the calling thread. +.TP +.BR PR_GET_NAME " (since Linux 2.6.11)" +Return the name of the calling thread, +in the buffer pointed to by +.IR "(char\ *) arg2" . +The buffer should allow space for up to 16 bytes; +the returned string will be null-terminated. +.TP +.BR PR_SET_NO_NEW_PRIVS " (since Linux 3.5)" +Set the calling thread's +.I no_new_privs +bit to the value in +.IR arg2 . +With +.I no_new_privs +set to 1, +.BR execve (2) +promises not to grant privileges to do anything +that could not have been done without the +.BR execve (2) +call (for example, +rendering the set-user-ID and set-group-ID mode bits, +and file capabilities non-functional). +Once set, this bit cannot be unset. +The setting of this bit is inherited by children created by +.BR fork (2) +and +.BR clone (2), +and preserved across +.BR execve (2). +.IP +Since Linux 4.10, +the value of a thread's +.I no_new_privs +bit can be viewed via the +.I NoNewPrivs +field in the +.IR /proc/[pid]/status +file. +.IP +For more information, see the kernel source file +.IR Documentation/userspace\-api/no_new_privs.rst +.\" commit 40fde647ccb0ae8c11d256d271e24d385eed595b +(or +.IR Documentation/prctl/no_new_privs.txt +before Linux 4.13). +See also +.BR seccomp (2). +.TP +.BR PR_GET_NO_NEW_PRIVS " (since Linux 3.5)" +Return (as the function result) the value of the +.I no_new_privs +bit for the calling thread. +A value of 0 indicates the regular +.BR execve (2) +behavior. +A value of 1 indicates +.BR execve (2) +will operate in the privilege-restricting mode described above. +.TP +.BR PR_SET_PDEATHSIG " (since Linux 2.1.57)" +Set the parent death signal +of the calling process to \fIarg2\fP (either a signal value +in the range 1..maxsig, or 0 to clear). +This is the signal that the calling process will get when its +parent dies. +This value is cleared for the child of a +.BR fork (2) +and (since Linux 2.4.36 / 2.6.23) +when executing a set-user-ID or set-group-ID binary, +or a binary that has associated capabilities (see +.BR capabilities (7)). +This value is preserved across +.BR execve (2). +.IP +.IR Warning : +.\" https://bugzilla.kernel.org/show_bug.cgi?id=43300 +the "parent" in this case is considered to be the +.I thread +that created this process. +In other words, the signal will be sent when that thread terminates +(via, for example, +.BR pthread_exit (3)), +rather than after all of the threads in the parent process terminate. +.TP +.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)" +Return the current value of the parent process death signal, +in the location pointed to by +.IR "(int\ *) arg2" . +.TP +.BR PR_SET_PTRACER " (since Linux 3.4)" +.\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb +.\" commit bf06189e4d14641c0148bea16e9dd24943862215 +This is meaningful only when the Yama LSM is enabled and in mode 1 +("restricted ptrace", visible via +.IR /proc/sys/kernel/yama/ptrace_scope ). +When a "ptracer process ID" is passed in \fIarg2\fP, +the caller is declaring that the ptracer process can +.BR ptrace (2) +the calling process as if it were a direct process ancestor. +Each +.B PR_SET_PTRACER +operation replaces the previous "ptracer process ID". +Employing +.B PR_SET_PTRACER +with +.I arg2 +set to 0 clears the caller's "ptracer process ID". +If +.I arg2 +is +.BR PR_SET_PTRACER_ANY , +the ptrace restrictions introduced by Yama are effectively disabled for the +calling process. +.IP +For further information, see the kernel source file +.IR Documentation/admin\-guide/LSM/Yama.rst +.\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22 +(or +.IR Documentation/security/Yama.txt +before Linux 4.13). +.TP +.BR PR_SET_SECCOMP " (since Linux 2.6.23)" +.\" See http://thread.gmane.org/gmane.linux.kernel/542632 +.\" [PATCH 0 of 2] seccomp updates +.\" andrea@cpushare.com +Set the secure computing (seccomp) mode for the calling thread, to limit +the available system calls. +The more recent +.BR seccomp (2) +system call provides a superset of the functionality of +.BR PR_SET_SECCOMP . +.IP +The seccomp mode is selected via +.IR arg2 . +(The seccomp constants are defined in +.IR .) +.IP +With +.IR arg2 +set to +.BR SECCOMP_MODE_STRICT , +the only system calls that the thread is permitted to make are +.BR read (2), +.BR write (2), +.BR _exit (2) +(but not +.BR exit_group (2)), +and +.BR sigreturn (2). +Other system calls result in the delivery of a +.BR SIGKILL +signal. +Strict secure computing mode is useful for number-crunching applications +that may need to execute untrusted byte code, +perhaps obtained by reading from a pipe or socket. +This operation is available only +if the kernel is configured with +.B CONFIG_SECCOMP +enabled. +.IP +With +.IR arg2 +set to +.BR SECCOMP_MODE_FILTER " (since Linux 3.5)," +the system calls allowed are defined by a pointer +to a Berkeley Packet Filter passed in +.IR arg3 . +This argument is a pointer to +.IR "struct sock_fprog" ; +it can be designed to filter +arbitrary system calls and system call arguments. +This mode is available only if the kernel is configured with +.B CONFIG_SECCOMP_FILTER +enabled. +.IP +If +.BR SECCOMP_MODE_FILTER +filters permit +.BR fork (2), +then the seccomp mode is inherited by children created by +.BR fork (2); +if +.BR execve (2) +is permitted, then the seccomp mode is preserved across +.BR execve (2). +If the filters permit +.BR prctl () +calls, then additional filters can be added; +they are run in order until the first non-allow result is seen. +.IP +For further information, see the kernel source file +.IR Documentation/userspace\-api/seccomp_filter.rst +.\" commit c061f33f35be0ccc80f4b8e0aea5dfd2ed7e01a3 +(or +.IR Documentation/prctl/seccomp_filter.txt +before Linux 4.13). +.TP +.BR PR_GET_SECCOMP " (since Linux 2.6.23)" +Return (as the function result) +the secure computing mode of the calling thread. +If the caller is not in secure computing mode, this operation returns 0; +if the caller is in strict secure computing mode, then the +.BR prctl () +call will cause a +.B SIGKILL +signal to be sent to the process. +If the caller is in filter mode, and this system call is allowed by the +seccomp filters, it returns 2; otherwise, the process is killed with a +.BR SIGKILL +signal. +This operation is available only +if the kernel is configured with +.B CONFIG_SECCOMP +enabled. +.IP +Since Linux 3.8, the +.IR Seccomp +field of the +.IR /proc/[pid]/status +file provides a method of obtaining the same information, +without the risk that the process is killed; see +.BR proc (5). +.TP +.BR PR_SET_SECUREBITS " (since Linux 2.6.26)" +Set the "securebits" flags of the calling thread to the value supplied in +.IR arg2 . +See +.BR capabilities (7). +.TP +.BR PR_GET_SECUREBITS " (since Linux 2.6.26)" +Return (as the function result) +the "securebits" flags of the calling thread. +See +.BR capabilities (7). +.TP +.BR PR_SET_THP_DISABLE " (since Linux 3.15)" +.\" commit a0715cc22601e8830ace98366c0c2bd8da52af52 +Set the state of the "THP disable" flag for the calling thread. +If +.I arg2 +has a nonzero value, the flag is set, otherwise it is cleared. +Setting this flag provides a method +for disabling transparent huge pages +for jobs where the code cannot be modified, and using a malloc hook with +.BR madvise (2) +is not an option (i.e., statically allocated data). +The setting of the "THP disable" flag is inherited by a child created via +.BR fork (2) +and is preserved across +.BR execve (2). +.\" +.TP +.BR PR_TASK_PERF_EVENTS_DISABLE " (since Linux 2.6.31)" +Disable all performance counters attached to the calling process, +regardless of whether the counters were created by +this process or another process. +Performance counters created by the calling process for other +processes are unaffected. +For more information on performance counters, see the Linux kernel source file +.IR tools/perf/design.txt . +.IP +Originally called +.BR PR_TASK_PERF_COUNTERS_DISABLE ; +.\" commit 1d1c7ddbfab358445a542715551301b7fc363e28 +renamed (retaining the same numerical value) +in Linux 2.6.32. +.\" +.TP +.BR PR_TASK_PERF_EVENTS_ENABLE " (since Linux 2.6.31)" +The converse of +.BR PR_TASK_PERF_EVENTS_DISABLE ; +enable performance counters attached to the calling process. +.IP +Originally called +.BR PR_TASK_PERF_COUNTERS_ENABLE ; +.\" commit 1d1c7ddbfab358445a542715551301b7fc363e28 +renamed +.\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6 +in Linux 2.6.32. +.\" +.TP +.BR PR_GET_THP_DISABLE " (since Linux 3.15)" +Return (via the function result) the current setting of the "THP disable" +flag for the calling thread: +either 1, if the flag is set, or 0, if it is not. +.TP +.BR PR_GET_TID_ADDRESS " (since Linux 3.5)" +.\" commit 300f786b2683f8bb1ec0afb6e1851183a479c86d +Retrieve the +.I clear_child_tid +address set by +.BR set_tid_address (2) +and the +.BR clone (2) +.B CLONE_CHILD_CLEARTID +flag, in the location pointed to by +.IR "(int\ **)\ arg2" . +This feature is available only if the kernel is built with the +.BR CONFIG_CHECKPOINT_RESTORE +option enabled. +Note that since the +.BR prctl () +system call does not have a compat implementation for +the AMD64 x32 and MIPS n32 ABIs, +and the kernel writes out a pointer using the kernel's pointer size, +this operation expects a user-space buffer of 8 (not 4) bytes on these ABIs. +.TP +.BR PR_SET_TIMERSLACK " (since Linux 2.6.28)" +.\" See https://lwn.net/Articles/369549/ +.\" commit 6976675d94042fbd446231d1bd8b7de71a980ada +Each thread has two associated timer slack values: +a "default" value, and a "current" value. +This operation sets the "current" timer slack value for the calling thread. +If the nanosecond value supplied in +.IR arg2 +is greater than zero, then the "current" value is set to this value. +If +.I arg2 +is less than or equal to zero, +.\" It seems that it's not possible to set the timer slack to zero; +.\" The minimum value is 1? Seems a little strange. +the "current" timer slack is reset to the +thread's "default" timer slack value. +.IP +The "current" timer slack is used by the kernel to group timer expirations +for the calling thread that are close to one another; +as a consequence, timer expirations for the thread may be +up to the specified number of nanoseconds late (but will never expire early). +Grouping timer expirations can help reduce system power consumption +by minimizing CPU wake-ups. +.IP +The timer expirations affected by timer slack are those set by +.BR select (2), +.BR pselect (2), +.BR poll (2), +.BR ppoll (2), +.BR epoll_wait (2), +.BR epoll_pwait (2), +.BR clock_nanosleep (2), +.BR nanosleep (2), +and +.BR futex (2) +(and thus the library functions implemented via futexes, including +.\" List obtained by grepping for futex usage in glibc source +.BR pthread_cond_timedwait (3), +.BR pthread_mutex_timedlock (3), +.BR pthread_rwlock_timedrdlock (3), +.BR pthread_rwlock_timedwrlock (3), +and +.BR sem_timedwait (3)). +.IP +Timer slack is not applied to threads that are scheduled under +a real-time scheduling policy (see +.BR sched_setscheduler (2)). +.IP +When a new thread is created, +the two timer slack values are made the same as the "current" value +of the creating thread. +Thereafter, a thread can adjust its "current" timer slack value via +.BR PR_SET_TIMERSLACK . +The "default" value can't be changed. +The timer slack values of +.IR init +(PID 1), the ancestor of all processes, +are 50,000 nanoseconds (50 microseconds). +The timer slack values are preserved across +.BR execve (2). +.IP +Since Linux 4.6, the "current" timer slack value of any process +can be examined and changed via the file +.IR /proc/[pid]/timerslack_ns . +See +.BR proc (5). +.TP +.BR PR_GET_TIMERSLACK " (since Linux 2.6.28)" +Return (as the function result) +the "current" timer slack value of the calling thread. +.TP +.BR PR_SET_TIMING " (since Linux 2.6.0-test4)" +Set whether to use (normal, traditional) statistical process timing or +accurate timestamp-based process timing, by passing +.B PR_TIMING_STATISTICAL +.\" 0 +or +.B PR_TIMING_TIMESTAMP +.\" 1 +to \fIarg2\fP. +.B PR_TIMING_TIMESTAMP +is not currently implemented +(attempting to set this mode will yield the error +.BR EINVAL ). +.\" PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8, +.\" and looking at the patch history, it appears +.\" that it never did anything. +.TP +.BR PR_GET_TIMING " (since Linux 2.6.0-test4)" +Return (as the function result) which process timing method is currently +in use. +.TP +.BR PR_SET_TSC " (since Linux 2.6.26, x86 only)" +Set the state of the flag determining whether the timestamp counter +can be read by the process. +Pass +.B PR_TSC_ENABLE +to +.I arg2 +to allow it to be read, or +.B PR_TSC_SIGSEGV +to generate a +.B SIGSEGV +when the process tries to read the timestamp counter. +.TP +.BR PR_GET_TSC " (since Linux 2.6.26, x86 only)" +Return the state of the flag determining whether the timestamp counter +can be read, +in the location pointed to by +.IR "(int\ *) arg2" . +.TP +.B PR_SET_UNALIGN +(Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15; +PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22; +.\" sh: 94ea5e449ae834af058ef005d16a8ad44fcf13d6 +.\" tile: 2f9ac29eec71a696cb0dcc5fb82c0f8d4dac28c9 +sh, since Linux 2.6.34; tile, since Linux 3.12) +Set unaligned access control bits to \fIarg2\fP. +Pass +\fBPR_UNALIGN_NOPRINT\fP to silently fix up unaligned user accesses, +or \fBPR_UNALIGN_SIGBUS\fP to generate +.B SIGBUS +on unaligned user access. +Alpha also supports an additional flag with the value +of 4 and no corresponding named constant, +which instructs kernel to not fix up +unaligned accesses (it is analogous to providing the +.BR UAC_NOFIX +flag in +.BR SSI_NVPAIRS +operation of the +.BR setsysinfo () +system call on Tru64). +.TP +.B PR_GET_UNALIGN +(see +.B PR_SET_UNALIGN +for information on versions and architectures) +Return unaligned access control bits, in the location pointed to by +.IR "(unsigned int\ *) arg2" . +.SH RETURN VALUE +On success, +.BR PR_GET_DUMPABLE , +.BR PR_GET_KEEPCAPS , +.BR PR_GET_NO_NEW_PRIVS , +.BR PR_GET_THP_DISABLE , +.BR PR_CAPBSET_READ , +.BR PR_GET_TIMING , +.BR PR_GET_TIMERSLACK , +.BR PR_GET_SECUREBITS , +.BR PR_MCE_KILL_GET , +.BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET , +and (if it returns) +.BR PR_GET_SECCOMP +return the nonnegative values described above. +All other +.I option +values return 0 on success. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +.I option +is +.BR PR_SET_SECCOMP +and +.I arg2 +is +.BR SECCOMP_MODE_FILTER , +but the process does not have the +.BR CAP_SYS_ADMIN +capability or has not set the +.IR no_new_privs +attribute (see the discussion of +.BR PR_SET_NO_NEW_PRIVS +above). +.TP +.B EACCES +.I option +is +.BR PR_SET_MM , +and +.I arg3 +is +.BR PR_SET_MM_EXE_FILE , +the file is not executable. +.TP +.B EBADF +.I option +is +.BR PR_SET_MM , +.I arg3 +is +.BR PR_SET_MM_EXE_FILE , +and the file descriptor passed in +.I arg4 +is not valid. +.TP +.B EBUSY +.I option +is +.BR PR_SET_MM , +.I arg3 +is +.BR PR_SET_MM_EXE_FILE , +and this the second attempt to change the +.I /proc/pid/exe +symbolic link, which is prohibited. +.TP +.B EFAULT +.I arg2 +is an invalid address. +.TP +.B EFAULT +.I option +is +.BR PR_SET_SECCOMP , +.I arg2 +is +.BR SECCOMP_MODE_FILTER , +the system was built with +.BR CONFIG_SECCOMP_FILTER , +and +.I arg3 +is an invalid address. +.TP +.B EINVAL +The value of +.I option +is not recognized. +.TP +.B EINVAL +.I option +is +.BR PR_MCE_KILL +or +.BR PR_MCE_KILL_GET +or +.BR PR_SET_MM , +and unused +.BR prctl () +arguments were not specified as zero. +.TP +.B EINVAL +.I arg2 +is not valid value for this +.IR option . +.TP +.B EINVAL +.I option +is +.BR PR_SET_SECCOMP +or +.BR PR_GET_SECCOMP , +and the kernel was not configured with +.BR CONFIG_SECCOMP . +.TP +.B EINVAL +.I option +is +.BR PR_SET_SECCOMP , +.I arg2 +is +.BR SECCOMP_MODE_FILTER , +and the kernel was not configured with +.BR CONFIG_SECCOMP_FILTER . +.TP +.B EINVAL +.I option +is +.BR PR_SET_MM , +and one of the following is true +.RS +.IP * 3 +.I arg4 +or +.I arg5 +is nonzero; +.IP * +.I arg3 +is greater than +.B TASK_SIZE +(the limit on the size of the user address space for this architecture); +.IP * +.I arg2 +is +.BR PR_SET_MM_START_CODE , +.BR PR_SET_MM_END_CODE , +.BR PR_SET_MM_START_DATA , +.BR PR_SET_MM_END_DATA , +or +.BR PR_SET_MM_START_STACK , +and the permissions of the corresponding memory area are not as required; +.IP * +.I arg2 +is +.BR PR_SET_MM_START_BRK +or +.BR PR_SET_MM_BRK , +and +.I arg3 +is less than or equal to the end of the data segment +or specifies a value that would cause the +.B RLIMIT_DATA +resource limit to be exceeded. +.RE +.TP +.B EINVAL +.I option +is +.BR PR_SET_PTRACER +and +.I arg2 +is not 0, +.BR PR_SET_PTRACER_ANY , +or the PID of an existing process. +.TP +.B EINVAL +.I option +is +.B PR_SET_PDEATHSIG +and +.I arg2 +is not a valid signal number. +.TP +.B EINVAL +.I option +is +.BR PR_SET_DUMPABLE +and +.I arg2 +is neither +.B SUID_DUMP_DISABLE +nor +.BR SUID_DUMP_USER . +.TP +.B EINVAL +.I option +is +.BR PR_SET_TIMING +and +.I arg2 +is not +.BR PR_TIMING_STATISTICAL . +.TP +.B EINVAL +.I option +is +.BR PR_SET_NO_NEW_PRIVS +and +.I arg2 +is not equal to 1 +or +.IR arg3 , +.IR arg4 , +or +.IR arg5 +is nonzero. +.TP +.B EINVAL +.I option +is +.BR PR_GET_NO_NEW_PRIVS +and +.IR arg2 , +.IR arg3 , +.IR arg4 , +or +.IR arg5 +is nonzero. +.TP +.B EINVAL +.I option +is +.BR PR_SET_THP_DISABLE +and +.IR arg3 , +.IR arg4 , +or +.IR arg5 +is nonzero. +.TP +.B EINVAL +.I option +is +.BR PR_GET_THP_DISABLE +and +.IR arg2 , +.IR arg3 , +.IR arg4 , +or +.IR arg5 +is nonzero. +.TP +.B EINVAL +.I option +is +.B PR_CAP_AMBIENT +and an unused argument +.RI ( arg4 , +.IR arg5 , +or, +in the case of +.BR PR_CAP_AMBIENT_CLEAR_ALL , +.IR arg3 ) +is nonzero; or +.IR arg2 +has an invalid value; +or +.IR arg2 +is +.BR PR_CAP_AMBIENT_LOWER , +.BR PR_CAP_AMBIENT_RAISE , +or +.BR PR_CAP_AMBIENT_IS_SET +and +.IR arg3 +does not specify a valid capability. +.TP +.B ENXIO +.I option +was +.BR PR_MPX_ENABLE_MANAGEMENT +or +.BR PR_MPX_DISABLE_MANAGEMENT +and the kernel or the CPU does not support MPX management. +Check that the kernel and processor have MPX support. +.TP +.B EOPNOTSUPP +.I option +is +.B PR_SET_FP_MODE +and +.I arg2 +has an invalid or unsupported value. +.TP +.B EPERM +.I option +is +.BR PR_SET_SECUREBITS , +and the caller does not have the +.B CAP_SETPCAP +capability, +or tried to unset a "locked" flag, +or tried to set a flag whose corresponding locked flag was set +(see +.BR capabilities (7)). +.TP +.B EPERM +.I option +is +.BR PR_SET_KEEPCAPS , +and the caller's +.B SECBIT_KEEP_CAPS_LOCKED +flag is set +(see +.BR capabilities (7)). +.TP +.B EPERM +.I option +is +.BR PR_CAPBSET_DROP , +and the caller does not have the +.B CAP_SETPCAP +capability. +.TP +.B EPERM +.I option +is +.BR PR_SET_MM , +and the caller does not have the +.B CAP_SYS_RESOURCE +capability. +.TP +.B EPERM +.IR option +is +.BR PR_CAP_AMBIENT +and +.IR arg2 +is +.BR PR_CAP_AMBIENT_RAISE , +but either the capability specified in +.IR arg3 +is not present in the process's permitted and inheritable capability sets, +or the +.B PR_CAP_AMBIENT_LOWER +securebit has been set. +.SH VERSIONS +The +.BR prctl () +system call was introduced in Linux 2.1.57. +.\" The library interface was added in glibc 2.0.6 +.SH CONFORMING TO +This call is Linux-specific. +IRIX has a +.BR prctl () +system call (also introduced in Linux 2.1.44 +as irix_prctl on the MIPS architecture), +with prototype +.PP +.in +4n +.EX +.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 ); +.EE +.in +.PP +and options to get the maximum number of processes per user, +get the maximum number of processors the calling process can use, +find out whether a specified process is currently blocked, +get or set the maximum stack size, and so on. +.SH SEE ALSO +.BR signal (2), +.BR core (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/pread.2 b/man2/pread.2 new file mode 100644 index 0000000..3682c93 --- /dev/null +++ b/man2/pread.2 @@ -0,0 +1,180 @@ +.\" Copyright (C) 1999 Joseph Samuel Myers. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PREAD 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pread, pwrite \- read from or write to a file descriptor at a given offset +.SH SYNOPSIS +.B #include +.PP +.BI "ssize_t pread(int " fd ", void *" buf ", size_t " count \ +", off_t " offset ); +.PP +.BI "ssize_t pwrite(int " fd ", const void *" buf ", size_t " count \ +", off_t " offset ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.PD 0 +.ad l +.BR pread (), +.BR pwrite (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.br +|| /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L +.RE +.ad +.PD +.SH DESCRIPTION +.BR pread () +reads up to +.I count +bytes from file descriptor +.I fd +at offset +.I offset +(from the start of the file) into the buffer starting at +.IR buf . +The file offset is not changed. +.PP +.BR pwrite () +writes up to +.I count +bytes from the buffer starting at +.I buf +to the file descriptor +.I fd +at offset +.IR offset . +The file offset is not changed. +.PP +The file referenced by +.I fd +must be capable of seeking. +.SH RETURN VALUE +On success, +.BR pread () +returns the number of bytes read +(a return of zero indicates end of file) +and +.BR pwrite () +returns the number of bytes written. +.PP +Note that is not an error for a successful call to transfer fewer bytes +than requested (see +.BR read (2) +and +.BR write (2)). +.PP +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.BR pread () +can fail and set +.I errno +to any error specified for +.BR read (2) +or +.BR lseek (2). +.BR pwrite () +can fail and set +.I errno +to any error specified for +.BR write (2) +or +.BR lseek (2). +.SH VERSIONS +The +.BR pread () +and +.BR pwrite () +system calls were added to Linux in +version 2.1.60; the entries in the i386 system call table were added +in 2.1.69. +C library support (including emulation using +.BR lseek (2) +on older kernels without the system calls) was added in glibc 2.1. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The +.BR pread () +and +.BR pwrite () +system calls are especially useful in multithreaded applications. +They allow multiple threads to perform I/O on the same file descriptor +without being affected by changes to the file offset by other threads. +.\" +.SS C library/kernel differences +On Linux, the underlying system calls were renamed +in kernel 2.6: +.BR pread () +became +.BR pread64 (), +and +.BR pwrite () +became +.BR pwrite64 (). +The system call numbers remained the same. +The glibc +.BR pread () +and +.BR pwrite () +wrapper functions transparently deal with the change. +.PP +On some 32-bit architectures, +the calling signature for these system calls differ, +for the reasons described in +.BR syscall (2). +.SH BUGS +POSIX requires that opening a file with the +.BR O_APPEND +flag should have no effect on the location at which +.BR pwrite () +writes data. +However, on Linux, if a file is opened with +.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=43178 +.BR O_APPEND , +.BR pwrite () +appends data to the end of the file, regardless of the value of +.IR offset . +.SH SEE ALSO +.BR lseek (2), +.BR read (2), +.BR readv (2), +.BR write (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/pread64.2 b/man2/pread64.2 new file mode 100644 index 0000000..87eacb2 --- /dev/null +++ b/man2/pread64.2 @@ -0,0 +1 @@ +.so man2/pread.2 diff --git a/man2/preadv.2 b/man2/preadv.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man2/preadv.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man2/preadv2.2 b/man2/preadv2.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man2/preadv2.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man2/prlimit.2 b/man2/prlimit.2 new file mode 100644 index 0000000..df6d736 --- /dev/null +++ b/man2/prlimit.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man2/prlimit64.2 b/man2/prlimit64.2 new file mode 100644 index 0000000..df6d736 --- /dev/null +++ b/man2/prlimit64.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man2/process_vm_readv.2 b/man2/process_vm_readv.2 new file mode 100644 index 0000000..6e3404b --- /dev/null +++ b/man2/process_vm_readv.2 @@ -0,0 +1,349 @@ +.\" Copyright (C) 2011 Christopher Yeoh +.\" and Copyright (C) 2012 Mike Frysinger +.\" and Copyright (C) 2012 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Commit fcf634098c00dd9cd247447368495f0b79be12d1 +.\" +.TH PROCESS_VM_READV 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +process_vm_readv, process_vm_writev \- transfer data between process address spaces +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "ssize_t process_vm_readv(pid_t " pid , +.BI " const struct iovec *" local_iov , +.BI " unsigned long " liovcnt , +.BI " const struct iovec *" remote_iov , +.BI " unsigned long " riovcnt , +.BI " unsigned long " flags ");" +.PP +.BI "ssize_t process_vm_writev(pid_t " pid , +.BI " const struct iovec *" local_iov , +.BI " unsigned long " liovcnt , +.BI " const struct iovec *" remote_iov , +.BI " unsigned long " riovcnt , +.BI " unsigned long " flags ");" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR process_vm_readv (), +.BR process_vm_writev (): +.PD 0 +.ad l +.RS 4 +.BR _GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +These system calls transfer data between the address space +of the calling process ("the local process") and the process identified by +.IR pid +("the remote process"). +The data moves directly between the address spaces of the two processes, +without passing through kernel space. +.PP +The +.BR process_vm_readv () +system call transfers data from the remote process to the local process. +The data to be transferred is identified by +.IR remote_iov +and +.IR riovcnt : +.IR remote_iov +is a pointer to an array describing address ranges in the process +.IR pid , +and +.IR riovcnt +specifies the number of elements in +.IR remote_iov . +The data is transferred to the locations specified by +.IR local_iov +and +.IR liovcnt : +.IR local_iov +is a pointer to an array describing address ranges in the calling process, +and +.IR liovcnt +specifies the number of elements in +.IR local_iov . +.PP +The +.BR process_vm_writev () +system call is the converse of +.BR process_vm_readv ()\(emit +transfers data from the local process to the remote process. +Other than the direction of the transfer, the arguments +.IR liovcnt , +.IR local_iov , +.IR riovcnt , +and +.IR remote_iov +have the same meaning as for +.BR process_vm_readv (). +.PP +The +.I local_iov +and +.I remote_iov +arguments point to an array of +.I iovec +structures, defined in +.IR +as: +.PP +.in +4n +.EX +struct iovec { + void *iov_base; /* Starting address */ + size_t iov_len; /* Number of bytes to transfer */ +}; +.EE +.in +.PP +Buffers are processed in array order. +This means that +.BR process_vm_readv () +completely fills +.I local_iov[0] +before proceeding to +.IR local_iov[1] , +and so on. +Likewise, +.I remote_iov[0] +is completely read before proceeding to +.IR remote_iov[1] , +and so on. +.PP +Similarly, +.BR process_vm_writev () +writes out the entire contents of +.I local_iov[0] +before proceeding to +.IR local_iov[1] , +and it completely fills +.I remote_iov[0] +before proceeding to +.IR remote_iov[1] . +.PP +The lengths of +.I remote_iov[i].iov_len +and +.I local_iov[i].iov_len +do not have to be the same. +Thus, it is possible to split a single local buffer +into multiple remote buffers, or vice versa. +.PP +The +.I flags +argument is currently unused and must be set to 0. +.PP +The values specified in the +.I liovcnt +and +.I riovcnt +arguments must be less than or equal to +.BR IOV_MAX +(defined in +.I +or accessible via the call +.IR sysconf(_SC_IOV_MAX) ). +.\" In time, glibc might provide a wrapper that works around this limit, +.\" as is done for readv()/writev() +.PP +The count arguments and +.IR local_iov +are checked before doing any transfers. +If the counts are too big, or +.I local_iov +is invalid, +or the addresses refer to regions that are inaccessible to the local process, +none of the vectors will be processed +and an error will be returned immediately. +.PP +Note, however, that these system calls do not check the memory regions +in the remote process until just before doing the read/write. +Consequently, a partial read/write (see RETURN VALUE) +may result if one of the +.I remote_iov +elements points to an invalid memory region in the remote process. +No further reads/writes will be attempted beyond that point. +Keep this in mind when attempting to read data of unknown length +(such as C strings that are null-terminated) from a remote process, +by avoiding spanning memory pages (typically 4\ KiB) in a single remote +.I iovec +element. +(Instead, split the remote read into two +.I remote_iov +elements and have them merge back into a single write +.I local_iov +entry. +The first read entry goes up to the page boundary, +while the second starts on the next page boundary.) +.PP +Permission to read from or write to another process +is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_REALCREDS +check; see +.BR ptrace (2). +.SH RETURN VALUE +On success, +.BR process_vm_readv () +returns the number of bytes read and +.BR process_vm_writev () +returns the number of bytes written. +This return value may be less than the total number of requested bytes, +if a partial read/write occurred. +(Partial transfers apply at the granularity of +.I iovec +elements. +These system calls won't perform a partial transfer that splits a single +.I iovec +element.) +The caller should check the return value to determine whether +a partial read/write occurred. +.PP +On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +The memory described by +.I local_iov +is outside the caller's accessible address space. +.TP +.B EFAULT +The memory described by +.I remote_iov +is outside the accessible address space of the process +.IR pid . +.TP +.B EINVAL +The sum of the +.I iov_len +values of either +.I local_iov +or +.I remote_iov +overflows a +.I ssize_t +value. +.TP +.B EINVAL +.I flags +is not 0. +.TP +.B EINVAL +.I liovcnt +or +.I riovcnt +is too large. +.TP +.B ENOMEM +Could not allocate memory for internal copies of the +.I iovec +structures. +.TP +.B EPERM +The caller does not have permission to access the address space of the process +.IR pid . +.TP +.B ESRCH +No process with ID +.I pid +exists. +.SH VERSIONS +These system calls were added in Linux 3.2. +Support is provided in glibc since version 2.15. +.SH CONFORMING TO +These system calls are nonstandard Linux extensions. +.SH NOTES +The data transfers performed by +.BR process_vm_readv () +and +.BR process_vm_writev () +are not guaranteed to be atomic in any way. +.PP +These system calls were designed to permit fast message passing +by allowing messages to be exchanged with a single copy operation +(rather than the double copy that would be required +when using, for example, shared memory or pipes). +.\" Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/ +.\" See also some benchmarks at http://lwn.net/Articles/405284/ +.\" and http://marc.info/?l=linux-mm&m=130105930902915&w=2 +.SH EXAMPLE +The following code sample demonstrates the use of +.BR process_vm_readv (). +It reads 20 bytes at the address 0x10000 from the process with PID 10 +and writes the first 10 bytes into +.I buf1 +and the second 10 bytes into +.IR buf2 . +.PP +.EX +#include + +int +main(void) +{ + struct iovec local[2]; + struct iovec remote[1]; + char buf1[10]; + char buf2[10]; + ssize_t nread; + pid_t pid = 10; /* PID of remote process */ + + local[0].iov_base = buf1; + local[0].iov_len = 10; + local[1].iov_base = buf2; + local[1].iov_len = 10; + remote[0].iov_base = (void *) 0x10000; + remote[0].iov_len = 20; + + nread = process_vm_readv(pid, local, 2, remote, 1, 0); + if (nread != 20) + return 1; + else + return 0; +} +.EE +.SH SEE ALSO +.BR readv (2), +.BR writev (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/process_vm_writev.2 b/man2/process_vm_writev.2 new file mode 100644 index 0000000..7b198a9 --- /dev/null +++ b/man2/process_vm_writev.2 @@ -0,0 +1 @@ +.so man2/process_vm_readv.2 diff --git a/man2/prof.2 b/man2/prof.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/prof.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/pselect.2 b/man2/pselect.2 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man2/pselect.2 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man2/pselect6.2 b/man2/pselect6.2 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man2/pselect6.2 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man2/ptrace.2 b/man2/ptrace.2 new file mode 100644 index 0000000..406e46e --- /dev/null +++ b/man2/ptrace.2 @@ -0,0 +1,2802 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" and changes Copyright (C) 1999 Mike Coleman (mkc@acm.org) +.\" -- major revision to fully document ptrace semantics per recent Linux +.\" kernel (2.2.10) and glibc (2.1.2) +.\" Sun Nov 7 03:18:35 CST 1999 +.\" +.\" and Copyright (c) 2011, Denys Vlasenko +.\" and Copyright (c) 2015, 2016, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith +.\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond +.\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com> +.\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO, +.\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP +.\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.) +.\" 2011-09, major update by Denys Vlasenko +.\" 2015-01, Kees Cook +.\" Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP +.\" +.\" FIXME The following are undocumented: +.\" +.\" PTRACE_GETWMMXREGS +.\" PTRACE_SETWMMXREGS +.\" ARM +.\" Linux 2.6.12 +.\" +.\" PTRACE_SET_SYSCALL +.\" ARM and ARM64 +.\" Linux 2.6.16 +.\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f +.\" Author: Nicolas Pitre +.\" Date: Sat Jan 14 19:30:04 2006 +0000 +.\" +.\" PTRACE_GETCRUNCHREGS +.\" PTRACE_SETCRUNCHREGS +.\" ARM +.\" Linux 2.6.18 +.\" commit 3bec6ded282b331552587267d67a06ed7fd95ddd +.\" Author: Lennert Buytenhek +.\" Date: Tue Jun 27 22:56:18 2006 +0100 +.\" +.\" PTRACE_GETVFPREGS +.\" PTRACE_SETVFPREGS +.\" ARM and ARM64 +.\" Linux 2.6.30 +.\" commit 3d1228ead618b88e8606015cbabc49019981805d +.\" Author: Catalin Marinas +.\" Date: Wed Feb 11 13:12:56 2009 +0100 +.\" +.\" PTRACE_GETHBPREGS +.\" PTRACE_SETHBPREGS +.\" ARM and ARM64 +.\" Linux 2.6.37 +.\" commit 864232fa1a2f8dfe003438ef0851a56722740f3e +.\" Author: Will Deacon +.\" Date: Fri Sep 3 10:42:55 2010 +0100 +.\" +.\" PTRACE_SINGLEBLOCK +.\" Since at least Linux 2.4.0 on various architectures +.\" Since Linux 2.6.25 on x86 (and others?) +.\" commit 5b88abbf770a0e1975c668743100f42934f385e8 +.\" Author: Roland McGrath +.\" Date: Wed Jan 30 13:30:53 2008 +0100 +.\" ptrace: generic PTRACE_SINGLEBLOCK +.\" +.\" PTRACE_GETFPXREGS +.\" PTRACE_SETFPXREGS +.\" Since at least Linux 2.4.0 on various architectures +.\" +.\" PTRACE_GETFDPIC +.\" PTRACE_GETFDPIC_EXEC +.\" PTRACE_GETFDPIC_INTERP +.\" blackfin, c6x, frv, sh +.\" First appearance in Linux 2.6.11 on frv +.\" +.\" and others that can be found in the arch/*/include/uapi/asm/ptrace files +.\" +.TH PTRACE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ptrace \- process trace +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", " +.BI " void *" addr ", void *" data ); +.fi +.SH DESCRIPTION +The +.BR ptrace () +system call provides a means by which one process (the "tracer") +may observe and control the execution of another process (the "tracee"), +and examine and change the tracee's memory and registers. +It is primarily used to implement breakpoint debugging and system +call tracing. +.PP +A tracee first needs to be attached to the tracer. +Attachment and subsequent commands are per thread: +in a multithreaded process, +every thread can be individually attached to a +(potentially different) tracer, +or left not attached and thus not debugged. +Therefore, "tracee" always means "(one) thread", +never "a (possibly multithreaded) process". +Ptrace commands are always sent to +a specific tracee using a call of the form +.PP + ptrace(PTRACE_foo, pid, ...) +.PP +where +.I pid +is the thread ID of the corresponding Linux thread. +.PP +(Note that in this page, a "multithreaded process" +means a thread group consisting of threads created using the +.BR clone (2) +.B CLONE_THREAD +flag.) +.PP +A process can initiate a trace by calling +.BR fork (2) +and having the resulting child do a +.BR PTRACE_TRACEME , +followed (typically) by an +.BR execve (2). +Alternatively, one process may commence tracing another process using +.B PTRACE_ATTACH +or +.BR PTRACE_SEIZE . +.PP +While being traced, the tracee will stop each time a signal is delivered, +even if the signal is being ignored. +(An exception is +.BR SIGKILL , +which has its usual effect.) +The tracer will be notified at its next call to +.BR waitpid (2) +(or one of the related "wait" system calls); that call will return a +.I status +value containing information that indicates +the cause of the stop in the tracee. +While the tracee is stopped, +the tracer can use various ptrace requests to inspect and modify the tracee. +The tracer then causes the tracee to continue, +optionally ignoring the delivered signal +(or even delivering a different signal instead). +.PP +If the +.B PTRACE_O_TRACEEXEC +option is not in effect, all successful calls to +.BR execve (2) +by the traced process will cause it to be sent a +.B SIGTRAP +signal, +giving the parent a chance to gain control before the new program +begins execution. +.PP +When the tracer is finished tracing, it can cause the tracee to continue +executing in a normal, untraced mode via +.BR PTRACE_DETACH . +.PP +The value of +.I request +determines the action to be performed: +.TP +.B PTRACE_TRACEME +Indicate that this process is to be traced by its parent. +A process probably shouldn't make this request if its parent +isn't expecting to trace it. +.RI ( pid , +.IR addr , +and +.IR data +are ignored.) +.IP +The +.B PTRACE_TRACEME +request is used only by the tracee; +the remaining requests are used only by the tracer. +In the following requests, +.I pid +specifies the thread ID of the tracee to be acted on. +For requests other than +.BR PTRACE_ATTACH , +.BR PTRACE_SEIZE , +.BR PTRACE_INTERRUPT , +and +.BR PTRACE_KILL , +the tracee must be stopped. +.TP +.BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA +Read a word at the address +.I addr +in the tracee's memory, returning the word as the result of the +.BR ptrace () +call. +Linux does not have separate text and data address spaces, +so these two requests are currently equivalent. +.RI ( data +is ignored; but see NOTES.) +.TP +.B PTRACE_PEEKUSER +.\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER, +.\" and that is the name that seems common on other systems. +Read a word at offset +.I addr +in the tracee's USER area, +which holds the registers and other information about the process +(see +.IR ). +The word is returned as the result of the +.BR ptrace () +call. +Typically, the offset must be word-aligned, though this might vary by +architecture. +See NOTES. +.RI ( data +is ignored; but see NOTES.) +.TP +.BR PTRACE_POKETEXT ", " PTRACE_POKEDATA +Copy the word +.I data +to the address +.I addr +in the tracee's memory. +As for +.BR PTRACE_PEEKTEXT +and +.BR PTRACE_PEEKDATA , +these two requests are currently equivalent. +.TP +.B PTRACE_POKEUSER +.\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER, +.\" and that is the name that seems common on other systems. +Copy the word +.I data +to offset +.I addr +in the tracee's USER area. +As for +.BR PTRACE_PEEKUSER , +the offset must typically be word-aligned. +In order to maintain the integrity of the kernel, +some modifications to the USER area are disallowed. +.\" FIXME In the preceding sentence, which modifications are disallowed, +.\" and when they are disallowed, how does user space discover that fact? +.TP +.BR PTRACE_GETREGS ", " PTRACE_GETFPREGS +Copy the tracee's general-purpose or floating-point registers, +respectively, to the address +.I data +in the tracer. +See +.I +for information on the format of this data. +.RI ( addr +is ignored.) +Note that SPARC systems have the meaning of +.I data +and +.I addr +reversed; that is, +.I data +is ignored and the registers are copied to the address +.IR addr . +.B PTRACE_GETREGS +and +.B PTRACE_GETFPREGS +are not present on all architectures. +.TP +.BR PTRACE_GETREGSET " (since Linux 2.6.34)" +Read the tracee's registers. +.I addr +specifies, in an architecture-dependent way, the type of registers to be read. +.B NT_PRSTATUS +(with numerical value 1) +usually results in reading of general-purpose registers. +If the CPU has, for example, +floating-point and/or vector registers, they can be retrieved by setting +.I addr +to the corresponding +.B NT_foo +constant. +.I data +points to a +.BR "struct iovec" , +which describes the destination buffer's location and length. +On return, the kernel modifies +.B iov.len +to indicate the actual number of bytes returned. +.TP +.BR PTRACE_SETREGS ", " PTRACE_SETFPREGS +Modify the tracee's general-purpose or floating-point registers, +respectively, from the address +.I data +in the tracer. +As for +.BR PTRACE_POKEUSER , +some general-purpose register modifications may be disallowed. +.\" FIXME . In the preceding sentence, which modifications are disallowed, +.\" and when they are disallowed, how does user space discover that fact? +.RI ( addr +is ignored.) +Note that SPARC systems have the meaning of +.I data +and +.I addr +reversed; that is, +.I data +is ignored and the registers are copied from the address +.IR addr . +.B PTRACE_SETREGS +and +.B PTRACE_SETFPREGS +are not present on all architectures. +.TP +.BR PTRACE_SETREGSET " (since Linux 2.6.34)" +Modify the tracee's registers. +The meaning of +.I addr +and +.I data +is analogous to +.BR PTRACE_GETREGSET . +.TP +.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)" +Retrieve information about the signal that caused the stop. +Copy a +.I siginfo_t +structure (see +.BR sigaction (2)) +from the tracee to the address +.I data +in the tracer. +.RI ( addr +is ignored.) +.TP +.BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)" +Set signal information: +copy a +.I siginfo_t +structure from the address +.I data +in the tracer to the tracee. +This will affect only signals that would normally be delivered to +the tracee and were caught by the tracer. +It may be difficult to tell +these normal signals from synthetic signals generated by +.BR ptrace () +itself. +.RI ( addr +is ignored.) +.TP +.BR PTRACE_PEEKSIGINFO " (since Linux 3.10)" +.\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4 +Retrieve +.I siginfo_t +structures without removing signals from a queue. +.I addr +points to a +.I ptrace_peeksiginfo_args +structure that specifies the ordinal position from which +copying of signals should start, +and the number of signals to copy. +.I siginfo_t +structures are copied into the buffer pointed to by +.IR data . +The return value contains the number of copied signals (zero indicates +that there is no signal corresponding to the specified ordinal position). +Within the returned +.I siginfo +structures, +the +.IR si_code +field includes information +.RB ( __SI_CHLD , +.BR __SI_FAULT , +etc.) that are not otherwise exposed to user space. +.PP +.in +4n +.EX +struct ptrace_peeksiginfo_args { + u64 off; /* Ordinal position in queue at which + to start copying signals */ + u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */ + s32 nr; /* Number of signals to copy */ +}; +.EE +.in +.IP +Currently, there is only one flag, +.BR PTRACE_PEEKSIGINFO_SHARED , +for dumping signals from the process-wide signal queue. +If this flag is not set, +signals are read from the per-thread queue of the specified thread. +.in +.PP +.TP +.BR PTRACE_GETSIGMASK " (since Linux 3.11)" +.\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1 +Place a copy of the mask of blocked signals (see +.BR sigprocmask (2)) +in the buffer pointed to by +.IR data , +which should be a pointer to a buffer of type +.IR sigset_t . +The +.I addr +argument contains the size of the buffer pointed to by +.IR data +(i.e., +.IR sizeof(sigset_t) ). +.TP +.BR PTRACE_SETSIGMASK " (since Linux 3.11)" +Change the mask of blocked signals (see +.BR sigprocmask (2)) +to the value specified in the buffer pointed to by +.IR data , +which should be a pointer to a buffer of type +.IR sigset_t . +The +.I addr +argument contains the size of the buffer pointed to by +.IR data +(i.e., +.IR sizeof(sigset_t) ). +.TP +.BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)" +Set ptrace options from +.IR data . +.RI ( addr +is ignored.) +.IR data +is interpreted as a bit mask of options, +which are specified by the following flags: +.RS +.TP +.BR PTRACE_O_EXITKILL " (since Linux 3.8)" +.\" commit 992fb6e170639b0849bace8e49bf31bd37c4123 +Send a +.B SIGKILL +signal to the tracee if the tracer exits. +This option is useful for ptrace jailers that +want to ensure that tracees can never escape the tracer's control. +.TP +.BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)" +Stop the tracee at the next +.BR clone (2) +and automatically start tracing the newly cloned process, +which will start with a +.BR SIGSTOP , +or +.B PTRACE_EVENT_STOP +if +.B PTRACE_SEIZE +was used. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8)) +.fi +.IP +The PID of the new process can be retrieved with +.BR PTRACE_GETEVENTMSG . +.IP +This option may not catch +.BR clone (2) +calls in all cases. +If the tracee calls +.BR clone (2) +with the +.B CLONE_VFORK +flag, +.B PTRACE_EVENT_VFORK +will be delivered instead +if +.B PTRACE_O_TRACEVFORK +is set; otherwise if the tracee calls +.BR clone (2) +with the exit signal set to +.BR SIGCHLD , +.B PTRACE_EVENT_FORK +will be delivered if +.B PTRACE_O_TRACEFORK +is set. +.TP +.BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)" +Stop the tracee at the next +.BR execve (2). +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8)) +.fi +.IP +If the execing thread is not a thread group leader, +the thread ID is reset to thread group leader's ID before this stop. +Since Linux 3.0, the former thread ID can be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)" +Stop the tracee at exit. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8)) +.fi +.IP +The tracee's exit status can be retrieved with +.BR PTRACE_GETEVENTMSG . +.IP +The tracee is stopped early during process exit, +when registers are still available, +allowing the tracer to see where the exit occurred, +whereas the normal exit notification is done after the process +is finished exiting. +Even though context is available, +the tracer cannot prevent the exit from happening at this point. +.TP +.BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)" +Stop the tracee at the next +.BR fork (2) +and automatically start tracing the newly forked process, +which will start with a +.BR SIGSTOP , +or +.B PTRACE_EVENT_STOP +if +.B PTRACE_SEIZE +was used. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8)) +.fi +.IP +The PID of the new process can be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)" +When delivering system call traps, set bit 7 in the signal number +(i.e., deliver +.IR "SIGTRAP|0x80" ). +This makes it easy for the tracer to distinguish +normal traps from those caused by a system call. +.RB ( PTRACE_O_TRACESYSGOOD +may not work on all architectures.) +.TP +.BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)" +Stop the tracee at the next +.BR vfork (2) +and automatically start tracing the newly vforked process, +which will start with a +.BR SIGSTOP , +or +.B PTRACE_EVENT_STOP +if +.B PTRACE_SEIZE +was used. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8)) +.fi +.IP +The PID of the new process can be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)" +Stop the tracee at the completion of the next +.BR vfork (2). +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8)) +.fi +.IP +The PID of the new process can (since Linux 2.6.18) be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)" +Stop the tracee when a +.BR seccomp (2) +.BR SECCOMP_RET_TRACE +rule is triggered. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8)) +.fi +.IP +While this triggers a +.BR PTRACE_EVENT +stop, it is similar to a syscall-enter-stop. +For details, see the note on +.B PTRACE_EVENT_SECCOMP +below. +The seccomp event message data (from the +.BR SECCOMP_RET_DATA +portion of the seccomp filter rule) can be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.3)" +.\" commit 13c4a90119d28cfcb6b5bdd820c233b86c2b0237 +Suspend the tracee's seccomp protections. +This applies regardless of mode, and +can be used when the tracee has not yet installed seccomp filters. +That is, a valid use case is to suspend a tracee's seccomp protections +before they are installed by the tracee, +let the tracee install the filters, +and then clear this flag when the filters should be resumed. +Setting this option requires that the tracer have the +.BR CAP_SYS_ADMIN +capability, +not have any seccomp protections installed, and not have +.BR PTRACE_O_SUSPEND_SECCOMP +set on itself. +.RE +.TP +.BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)" +Retrieve a message (as an +.IR "unsigned long" ) +about the ptrace event +that just happened, placing it at the address +.I data +in the tracer. +For +.BR PTRACE_EVENT_EXIT , +this is the tracee's exit status. +For +.BR PTRACE_EVENT_FORK , +.BR PTRACE_EVENT_VFORK , +.BR PTRACE_EVENT_VFORK_DONE , +and +.BR PTRACE_EVENT_CLONE , +this is the PID of the new process. +For +.BR PTRACE_EVENT_SECCOMP , +this is the +.BR seccomp (2) +filter's +.BR SECCOMP_RET_DATA +associated with the triggered rule. +.RI ( addr +is ignored.) +.TP +.B PTRACE_CONT +Restart the stopped tracee process. +If +.I data +is nonzero, +it is interpreted as the number of a signal to be delivered to the tracee; +otherwise, no signal is delivered. +Thus, for example, the tracer can control +whether a signal sent to the tracee is delivered or not. +.RI ( addr +is ignored.) +.TP +.BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP +Restart the stopped tracee as for +.BR PTRACE_CONT , +but arrange for the tracee to be stopped at +the next entry to or exit from a system call, +or after execution of a single instruction, respectively. +(The tracee will also, as usual, be stopped upon receipt of a signal.) +From the tracer's perspective, the tracee will appear to have been +stopped by receipt of a +.BR SIGTRAP . +So, for +.BR PTRACE_SYSCALL , +for example, the idea is to inspect +the arguments to the system call at the first stop, +then do another +.B PTRACE_SYSCALL +and inspect the return value of the system call at the second stop. +The +.I data +argument is treated as for +.BR PTRACE_CONT . +.RI ( addr +is ignored.) +.TP +.BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" +For +.BR PTRACE_SYSEMU , +continue and stop on entry to the next system call, +which will not be executed. +See the documentation on syscall-stops below. +For +.BR PTRACE_SYSEMU_SINGLESTEP , +do the same but also singlestep if not a system call. +This call is used by programs like +User Mode Linux that want to emulate all the tracee's system calls. +The +.I data +argument is treated as for +.BR PTRACE_CONT . +The +.I addr +argument is ignored. +These requests are currently +.\" As at 3.7 +supported only on x86. +.TP +.BR PTRACE_LISTEN " (since Linux 3.4)" +Restart the stopped tracee, but prevent it from executing. +The resulting state of the tracee is similar to a process which +has been stopped by a +.B SIGSTOP +(or other stopping signal). +See the "group-stop" subsection for additional information. +.B PTRACE_LISTEN +works only on tracees attached by +.BR PTRACE_SEIZE . +.TP +.B PTRACE_KILL +Send the tracee a +.B SIGKILL +to terminate it. +.RI ( addr +and +.I data +are ignored.) +.IP +.I This operation is deprecated; do not use it! +Instead, send a +.BR SIGKILL +directly using +.BR kill (2) +or +.BR tgkill (2). +The problem with +.B PTRACE_KILL +is that it requires the tracee to be in signal-delivery-stop, +otherwise it may not work +(i.e., may complete successfully but won't kill the tracee). +By contrast, sending a +.B SIGKILL +directly has no such limitation. +.\" [Note from Denys Vlasenko: +.\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it +.\" instead of describing (and needing to support) PTRACE_KILL's quirks.] +.TP +.BR PTRACE_INTERRUPT " (since Linux 3.4)" +Stop a tracee. +If the tracee is running or sleeping in kernel space and +.B PTRACE_SYSCALL +is in effect, +the system call is interrupted and syscall-exit-stop is reported. +(The interrupted system call is restarted when the tracee is restarted.) +If the tracee was already stopped by a signal and +.B PTRACE_LISTEN +was sent to it, +the tracee stops with +.B PTRACE_EVENT_STOP +and +.I WSTOPSIG(status) +returns the stop signal. +If any other ptrace-stop is generated at the same time (for example, +if a signal is sent to the tracee), this ptrace-stop happens. +If none of the above applies (for example, if the tracee is running in user +space), it stops with +.B PTRACE_EVENT_STOP +with +.I WSTOPSIG(status) +== +.BR SIGTRAP . +.B PTRACE_INTERRUPT +only works on tracees attached by +.BR PTRACE_SEIZE . +.TP +.B PTRACE_ATTACH +Attach to the process specified in +.IR pid , +making it a tracee of the calling process. +.\" No longer true (removed by Denys Vlasenko, 2011, who remarks: +.\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x. +.\" Basically, it's not true for any Linux in practical use. +.\" ; the behavior of the tracee is as if it had done a +.\" .BR PTRACE_TRACEME . +.\" The calling process actually becomes the parent of the tracee +.\" process for most purposes (e.g., it will receive +.\" notification of tracee events and appears in +.\" .BR ps (1) +.\" output as the tracee's parent), but a +.\" .BR getppid (2) +.\" by the tracee will still return the PID of the original parent. +The tracee is sent a +.BR SIGSTOP , +but will not necessarily have stopped +by the completion of this call; use +.BR waitpid (2) +to wait for the tracee to stop. +See the "Attaching and detaching" subsection for additional information. +.RI ( addr +and +.I data +are ignored.) +.IP +Permission to perform a +.BR PTRACE_ATTACH +is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_REALCREDS +check; see below. +.TP +.BR PTRACE_SEIZE " (since Linux 3.4)" +.\" +.\" Noted by Dmitry Levin: +.\" +.\" PTRACE_SEIZE was introduced by commit v3.1-rc1~308^2~28, but +.\" it had to be used along with a temporary flag PTRACE_SEIZE_DEVEL, +.\" which was removed later by commit v3.4-rc1~109^2~20. +.\" +.\" That is, [before] v3.4 we had a test mode of PTRACE_SEIZE API, +.\" which was not compatible with the current PTRACE_SEIZE API introduced +.\" in Linux 3.4. +.\" +Attach to the process specified in +.IR pid , +making it a tracee of the calling process. +Unlike +.BR PTRACE_ATTACH , +.B PTRACE_SEIZE +does not stop the process. +Group-stops are reported as +.B PTRACE_EVENT_STOP +and +.I WSTOPSIG(status) +returns the stop signal. +Automatically attached children stop with +.B PTRACE_EVENT_STOP +and +.I WSTOPSIG(status) +returns +.B SIGTRAP +instead of having +.B SIGSTOP +signal delivered to them. +.BR execve (2) +does not deliver an extra +.BR SIGTRAP . +Only a +.BR PTRACE_SEIZE d +process can accept +.B PTRACE_INTERRUPT +and +.B PTRACE_LISTEN +commands. +The "seized" behavior just described is inherited by +children that are automatically attached using +.BR PTRACE_O_TRACEFORK , +.BR PTRACE_O_TRACEVFORK , +and +.BR PTRACE_O_TRACECLONE . +.I addr +must be zero. +.I data +contains a bit mask of ptrace options to activate immediately. +.IP +Permission to perform a +.BR PTRACE_SEIZE +is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_REALCREDS +check; see below. +.\" +.TP +.BR PTRACE_SECCOMP_GET_FILTER " (since Linux 4.4)" +.\" commit f8e529ed941ba2bbcbf310b575d968159ce7e895 +This operation allows the tracer to dump the tracee's +classic BPF filters. +.IP +.I addr +is an integer specifying the index of the filter to be dumped. +The most recently installed filter has the index 0. +If +.I addr +is greater than the number of installed filters, +the operation fails with the error +.BR ENOENT . +.IP +.I data +is either a pointer to a +.IR "struct sock_filter" +array that is large enough to store the BPF program, +or NULL if the program is not to be stored. +.IP +Upon success, +the return value is the number of instructions in the BPF program. +If +.I data +was NULL, then this return value can be used to correctly size the +.IR "struct sock_filter" +array passed in a subsequent call. +.IP +This operation fails with the error +.B EACCESS +if the caller does not have the +.B CAP_SYS_ADMIN +capability or if the caller is in strict or filter seccomp mode. +If the filter referred to by +.I addr +is not a classic BPF filter, the operation fails with the error +.BR EMEDIUMTYPE . +.IP +This operation is available if the kernel was configured with both the +.B CONFIG_SECCOMP_FILTER +and the +.B CONFIG_CHECKPOINT_RESTORE +options. +.TP +.B PTRACE_DETACH +Restart the stopped tracee as for +.BR PTRACE_CONT , +but first detach from it. +Under Linux, a tracee can be detached in this way regardless +of which method was used to initiate tracing. +.RI ( addr +is ignored.) +.\" +.TP +.BR PTRACE_GET_THREAD_AREA " (since Linux 2.6.0)" +This operation performs a similar task to +.BR get_thread_area (2). +It reads the TLS entry in the GDT whose index is given in +.IR addr , +placing a copy of the entry into the +.IR "struct user_desc" +pointed to by +.IR data . +(By contrast with +.BR get_thread_area (2), +the +.I entry_number +of the +.IR "struct user_desc" +is ignored.) +.TP +.BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)" +This operation performs a similar task to +.BR set_thread_area (2). +It sets the TLS entry in the GDT whose index is given in +.IR addr , +assigning it the data supplied in the +.IR "struct user_desc" +pointed to by +.IR data . +(By contrast with +.BR set_thread_area (2), +the +.I entry_number +of the +.IR "struct user_desc" +is ignored; in other words, +this ptrace operation can't be used to allocate a free TLS entry.) +.\" +.SS Death under ptrace +When a (possibly multithreaded) process receives a killing signal +(one whose disposition is set to +.B SIG_DFL +and whose default action is to kill the process), +all threads exit. +Tracees report their death to their tracer(s). +Notification of this event is delivered via +.BR waitpid (2). +.PP +Note that the killing signal will first cause signal-delivery-stop +(on one tracee only), +and only after it is injected by the tracer +(or after it was dispatched to a thread which isn't traced), +will death from the signal happen on +.I all +tracees within a multithreaded process. +(The term "signal-delivery-stop" is explained below.) +.PP +.B SIGKILL +does not generate signal-delivery-stop and +therefore the tracer can't suppress it. +.B SIGKILL +kills even within system calls +(syscall-exit-stop is not generated prior to death by +.BR SIGKILL ). +The net effect is that +.B SIGKILL +always kills the process (all its threads), +even if some threads of the process are ptraced. +.PP +When the tracee calls +.BR _exit (2), +it reports its death to its tracer. +Other threads are not affected. +.PP +When any thread executes +.BR exit_group (2), +every tracee in its thread group reports its death to its tracer. +.PP +If the +.B PTRACE_O_TRACEEXIT +option is on, +.B PTRACE_EVENT_EXIT +will happen before actual death. +This applies to exits via +.BR exit (2), +.BR exit_group (2), +and signal deaths (except +.BR SIGKILL , +depending on the kernel version; see BUGS below), +and when threads are torn down on +.BR execve (2) +in a multithreaded process. +.PP +The tracer cannot assume that the ptrace-stopped tracee exists. +There are many scenarios when the tracee may die while stopped (such as +.BR SIGKILL ). +Therefore, the tracer must be prepared to handle an +.B ESRCH +error on any ptrace operation. +Unfortunately, the same error is returned if the tracee +exists but is not ptrace-stopped +(for commands which require a stopped tracee), +or if it is not traced by the process which issued the ptrace call. +The tracer needs to keep track of the stopped/running state of the tracee, +and interpret +.B ESRCH +as "tracee died unexpectedly" only if it knows that the tracee has +been observed to enter ptrace-stop. +Note that there is no guarantee that +.I waitpid(WNOHANG) +will reliably report the tracee's death status if a +ptrace operation returned +.BR ESRCH . +.I waitpid(WNOHANG) +may return 0 instead. +In other words, the tracee may be "not yet fully dead", +but already refusing ptrace requests. +.PP +The tracer can't assume that the tracee +.I always +ends its life by reporting +.I WIFEXITED(status) +or +.IR WIFSIGNALED(status) ; +there are cases where this does not occur. +For example, if a thread other than thread group leader does an +.BR execve (2), +it disappears; +its PID will never be seen again, +and any subsequent ptrace stops will be reported under +the thread group leader's PID. +.SS Stopped states +A tracee can be in two states: running or stopped. +For the purposes of ptrace, a tracee which is blocked in a system call +(such as +.BR read (2), +.BR pause (2), +etc.) +is nevertheless considered to be running, even if the tracee is blocked +for a long time. +The state of the tracee after +.BR PTRACE_LISTEN +is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands +won't work on it, and it will deliver +.BR waitpid (2) +notifications), +but it also may be considered "stopped" because +it is not executing instructions (is not scheduled), and if it was +in group-stop before +.BR PTRACE_LISTEN , +it will not respond to signals until +.B SIGCONT +is received. +.PP +There are many kinds of states when the tracee is stopped, and in ptrace +discussions they are often conflated. +Therefore, it is important to use precise terms. +.PP +In this manual page, any stopped state in which the tracee is ready +to accept ptrace commands from the tracer is called +.IR ptrace-stop . +Ptrace-stops can +be further subdivided into +.IR signal-delivery-stop , +.IR group-stop , +.IR syscall-stop , +.IR PTRACE_EVENT stops, +and so on. +These stopped states are described in detail below. +.PP +When the running tracee enters ptrace-stop, it notifies its tracer using +.BR waitpid (2) +(or one of the other "wait" system calls). +Most of this manual page assumes that the tracer waits with: +.PP + pid = waitpid(pid_or_minus_1, &status, __WALL); +.PP +Ptrace-stopped tracees are reported as returns with +.I pid +greater than 0 and +.I WIFSTOPPED(status) +true. +.\" Denys Vlasenko: +.\" Do we require __WALL usage, or will just using 0 be ok? (With 0, +.\" I am not 100% sure there aren't ugly corner cases.) Are the +.\" rules different if user wants to use waitid? Will waitid require +.\" WEXITED? +.\" +.PP +The +.B __WALL +flag does not include the +.B WSTOPPED +and +.B WEXITED +flags, but implies their functionality. +.PP +Setting the +.B WCONTINUED +flag when calling +.BR waitpid (2) +is not recommended: the "continued" state is per-process and +consuming it can confuse the real parent of the tracee. +.PP +Use of the +.B WNOHANG +flag may cause +.BR waitpid (2) +to return 0 ("no wait results available yet") +even if the tracer knows there should be a notification. +Example: +.PP +.in +4n +.EX +errno = 0; +ptrace(PTRACE_CONT, pid, 0L, 0L); +if (errno == ESRCH) { + /* tracee is dead */ + r = waitpid(tracee, &status, __WALL | WNOHANG); + /* r can still be 0 here! */ +} +.EE +.in +.\" FIXME . +.\" waitid usage? WNOWAIT? +.\" describe how wait notifications queue (or not queue) +.PP +The following kinds of ptrace-stops exist: signal-delivery-stops, +group-stops, +.B PTRACE_EVENT +stops, syscall-stops. +They all are reported by +.BR waitpid (2) +with +.I WIFSTOPPED(status) +true. +They may be differentiated by examining the value +.IR status>>8 , +and if there is ambiguity in that value, by querying +.BR PTRACE_GETSIGINFO . +(Note: the +.I WSTOPSIG(status) +macro can't be used to perform this examination, +because it returns the value +.IR "(status>>8)\ &\ 0xff" .) +.SS Signal-delivery-stop +When a (possibly multithreaded) process receives any signal except +.BR SIGKILL , +the kernel selects an arbitrary thread which handles the signal. +(If the signal is generated with +.BR tgkill (2), +the target thread can be explicitly selected by the caller.) +If the selected thread is traced, it enters signal-delivery-stop. +At this point, the signal is not yet delivered to the process, +and can be suppressed by the tracer. +If the tracer doesn't suppress the signal, +it passes the signal to the tracee in the next ptrace restart request. +This second step of signal delivery is called +.I "signal injection" +in this manual page. +Note that if the signal is blocked, +signal-delivery-stop doesn't happen until the signal is unblocked, +with the usual exception that +.B SIGSTOP +can't be blocked. +.PP +Signal-delivery-stop is observed by the tracer as +.BR waitpid (2) +returning with +.I WIFSTOPPED(status) +true, with the signal returned by +.IR WSTOPSIG(status) . +If the signal is +.BR SIGTRAP , +this may be a different kind of ptrace-stop; +see the "Syscall-stops" and "execve" sections below for details. +If +.I WSTOPSIG(status) +returns a stopping signal, this may be a group-stop; see below. +.SS Signal injection and suppression +After signal-delivery-stop is observed by the tracer, +the tracer should restart the tracee with the call +.PP + ptrace(PTRACE_restart, pid, 0, sig) +.PP +where +.B PTRACE_restart +is one of the restarting ptrace requests. +If +.I sig +is 0, then a signal is not delivered. +Otherwise, the signal +.I sig +is delivered. +This operation is called +.I "signal injection" +in this manual page, to distinguish it from signal-delivery-stop. +.PP +The +.I sig +value may be different from the +.I WSTOPSIG(status) +value: the tracer can cause a different signal to be injected. +.PP +Note that a suppressed signal still causes system calls to return +prematurely. +In this case, system calls will be restarted: the tracer will +observe the tracee to reexecute the interrupted system call (or +.BR restart_syscall (2) +system call for a few system calls which use a different mechanism +for restarting) if the tracer uses +.BR PTRACE_SYSCALL . +Even system calls (such as +.BR poll (2)) +which are not restartable after signal are restarted after +signal is suppressed; +however, kernel bugs exist which cause some system calls to fail with +.B EINTR +even though no observable signal is injected to the tracee. +.PP +Restarting ptrace commands issued in ptrace-stops other than +signal-delivery-stop are not guaranteed to inject a signal, even if +.I sig +is nonzero. +No error is reported; a nonzero +.I sig +may simply be ignored. +Ptrace users should not try to "create a new signal" this way: use +.BR tgkill (2) +instead. +.PP +The fact that signal injection requests may be ignored +when restarting the tracee after +ptrace stops that are not signal-delivery-stops +is a cause of confusion among ptrace users. +One typical scenario is that the tracer observes group-stop, +mistakes it for signal-delivery-stop, restarts the tracee with +.PP + ptrace(PTRACE_restart, pid, 0, stopsig) +.PP +with the intention of injecting +.IR stopsig , +but +.I stopsig +gets ignored and the tracee continues to run. +.PP +The +.B SIGCONT +signal has a side effect of waking up (all threads of) +a group-stopped process. +This side effect happens before signal-delivery-stop. +The tracer can't suppress this side effect (it can +only suppress signal injection, which only causes the +.BR SIGCONT +handler to not be executed in the tracee, if such a handler is installed). +In fact, waking up from group-stop may be followed by +signal-delivery-stop for signal(s) +.I other than +.BR SIGCONT , +if they were pending when +.B SIGCONT +was delivered. +In other words, +.B SIGCONT +may be not the first signal observed by the tracee after it was sent. +.PP +Stopping signals cause (all threads of) a process to enter group-stop. +This side effect happens after signal injection, and therefore can be +suppressed by the tracer. +.PP +In Linux 2.4 and earlier, the +.B SIGSTOP +signal can't be injected. +.\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(), +.\" there is: +.\" +.\" /* The debugger continued. Ignore SIGSTOP. */ +.\" if (signr == SIGSTOP) +.\" continue; +.PP +.B PTRACE_GETSIGINFO +can be used to retrieve a +.I siginfo_t +structure which corresponds to the delivered signal. +.B PTRACE_SETSIGINFO +may be used to modify it. +If +.B PTRACE_SETSIGINFO +has been used to alter +.IR siginfo_t , +the +.I si_signo +field and the +.I sig +parameter in the restarting command must match, +otherwise the result is undefined. +.SS Group-stop +When a (possibly multithreaded) process receives a stopping signal, +all threads stop. +If some threads are traced, they enter a group-stop. +Note that the stopping signal will first cause signal-delivery-stop +(on one tracee only), and only after it is injected by the tracer +(or after it was dispatched to a thread which isn't traced), +will group-stop be initiated on +.I all +tracees within the multithreaded process. +As usual, every tracee reports its group-stop separately +to the corresponding tracer. +.PP +Group-stop is observed by the tracer as +.BR waitpid (2) +returning with +.I WIFSTOPPED(status) +true, with the stopping signal available via +.IR WSTOPSIG(status) . +The same result is returned by some other classes of ptrace-stops, +therefore the recommended practice is to perform the call +.PP + ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo) +.PP +The call can be avoided if the signal is not +.BR SIGSTOP , +.BR SIGTSTP , +.BR SIGTTIN , +or +.BR SIGTTOU ; +only these four signals are stopping signals. +If the tracer sees something else, it can't be a group-stop. +Otherwise, the tracer needs to call +.BR PTRACE_GETSIGINFO . +If +.B PTRACE_GETSIGINFO +fails with +.BR EINVAL , +then it is definitely a group-stop. +(Other failure codes are possible, such as +.B ESRCH +("no such process") if a +.B SIGKILL +killed the tracee.) +.PP +If tracee was attached using +.BR PTRACE_SEIZE , +group-stop is indicated by +.BR PTRACE_EVENT_STOP : +.IR "status>>16 == PTRACE_EVENT_STOP" . +This allows detection of group-stops +without requiring an extra +.B PTRACE_GETSIGINFO +call. +.PP +As of Linux 2.6.38, +after the tracer sees the tracee ptrace-stop and until it +restarts or kills it, the tracee will not run, +and will not send notifications (except +.B SIGKILL +death) to the tracer, even if the tracer enters into another +.BR waitpid (2) +call. +.PP +The kernel behavior described in the previous paragraph +causes a problem with transparent handling of stopping signals. +If the tracer restarts the tracee after group-stop, +the stopping signal +is effectively ignored\(emthe tracee doesn't remain stopped, it runs. +If the tracer doesn't restart the tracee before entering into the next +.BR waitpid (2), +future +.B SIGCONT +signals will not be reported to the tracer; +this would cause the +.B SIGCONT +signals to have no effect on the tracee. +.PP +Since Linux 3.4, there is a method to overcome this problem: instead of +.BR PTRACE_CONT , +a +.B PTRACE_LISTEN +command can be used to restart a tracee in a way where it does not execute, +but waits for a new event which it can report via +.BR waitpid (2) +(such as when +it is restarted by a +.BR SIGCONT ). +.SS PTRACE_EVENT stops +If the tracer sets +.B PTRACE_O_TRACE_* +options, the tracee will enter ptrace-stops called +.B PTRACE_EVENT +stops. +.PP +.B PTRACE_EVENT +stops are observed by the tracer as +.BR waitpid (2) +returning with +.IR WIFSTOPPED(status) , +and +.I WSTOPSIG(status) +returns +.BR SIGTRAP . +An additional bit is set in the higher byte of the status word: +the value +.I status>>8 +will be +.PP + (SIGTRAP | PTRACE_EVENT_foo << 8). +.PP +The following events exist: +.TP +.B PTRACE_EVENT_VFORK +Stop before return from +.BR vfork (2) +or +.BR clone (2) +with the +.B CLONE_VFORK +flag. +When the tracee is continued after this stop, it will wait for child to +exit/exec before continuing its execution +(in other words, the usual behavior on +.BR vfork (2)). +.TP +.B PTRACE_EVENT_FORK +Stop before return from +.BR fork (2) +or +.BR clone (2) +with the exit signal set to +.BR SIGCHLD . +.TP +.B PTRACE_EVENT_CLONE +Stop before return from +.BR clone (2). +.TP +.B PTRACE_EVENT_VFORK_DONE +Stop before return from +.BR vfork (2) +or +.BR clone (2) +with the +.B CLONE_VFORK +flag, +but after the child unblocked this tracee by exiting or execing. +.PP +For all four stops described above, +the stop occurs in the parent (i.e., the tracee), +not in the newly created thread. +.BR PTRACE_GETEVENTMSG +can be used to retrieve the new thread's ID. +.TP +.B PTRACE_EVENT_EXEC +Stop before return from +.BR execve (2). +Since Linux 3.0, +.BR PTRACE_GETEVENTMSG +returns the former thread ID. +.TP +.B PTRACE_EVENT_EXIT +Stop before exit (including death from +.BR exit_group (2)), +signal death, or exit caused by +.BR execve (2) +in a multithreaded process. +.B PTRACE_GETEVENTMSG +returns the exit status. +Registers can be examined +(unlike when "real" exit happens). +The tracee is still alive; it needs to be +.BR PTRACE_CONT ed +or +.BR PTRACE_DETACH ed +to finish exiting. +.TP +.B PTRACE_EVENT_STOP +Stop induced by +.B PTRACE_INTERRUPT +command, or group-stop, or initial ptrace-stop when a new child is attached +(only if attached using +.BR PTRACE_SEIZE ). +.TP +.B PTRACE_EVENT_SECCOMP +Stop triggered by a +.BR seccomp (2) +rule on tracee syscall entry when +.BR PTRACE_O_TRACESECCOMP +has been set by the tracer. +The seccomp event message data (from the +.BR SECCOMP_RET_DATA +portion of the seccomp filter rule) can be retrieved with +.BR PTRACE_GETEVENTMSG . +The semantics of this stop are described in +detail in a separate section below. +.PP +.B PTRACE_GETSIGINFO +on +.B PTRACE_EVENT +stops returns +.B SIGTRAP +in +.IR si_signo , +with +.I si_code +set to +.IR "(event<<8)\ |\ SIGTRAP" . +.SS Syscall-stops +If the tracee was restarted by +.BR PTRACE_SYSCALL +or +.BR PTRACE_SYSEMU , +the tracee enters +syscall-enter-stop just prior to entering any system call (which +will not be executed if the restart was using +.BR PTRACE_SYSEMU , +regardless of any change made to registers at this point or how the +tracee is restarted after this stop). +No matter which method caused the syscall-entry-stop, +if the tracer restarts the tracee with +.BR PTRACE_SYSCALL , +the tracee enters syscall-exit-stop when the system call is finished, +or if it is interrupted by a signal. +(That is, signal-delivery-stop never happens between syscall-enter-stop +and syscall-exit-stop; it happens +.I after +syscall-exit-stop.). +If the tracee is continued using any other method (including +.BR PTRACE_SYSEMU ), +no syscall-exit-stop occurs. +Note that all mentions +.BR PTRACE_SYSEMU +apply equally to +.BR PTRACE_SYSEMU_SINGLESTEP. +.PP +However, even if the tracee was continued using +.BR PTRACE_SYSCALL +, it is not guaranteed that the next stop will be a syscall-exit-stop. +Other possibilities are that the tracee may stop in a +.B PTRACE_EVENT +stop (including seccomp stops), exit (if it entered +.BR _exit (2) +or +.BR exit_group (2)), +be killed by +.BR SIGKILL , +or die silently (if it is a thread group leader, the +.BR execve (2) +happened in another thread, +and that thread is not traced by the same tracer; +this situation is discussed later). +.PP +Syscall-enter-stop and syscall-exit-stop are observed by the tracer as +.BR waitpid (2) +returning with +.I WIFSTOPPED(status) +true, and +.I WSTOPSIG(status) +giving +.BR SIGTRAP . +If the +.B PTRACE_O_TRACESYSGOOD +option was set by the tracer, then +.I WSTOPSIG(status) +will give the value +.IR "(SIGTRAP\ |\ 0x80)" . +.PP +Syscall-stops can be distinguished from signal-delivery-stop with +.B SIGTRAP +by querying +.BR PTRACE_GETSIGINFO +for the following cases: +.TP +.IR si_code " <= 0" +.B SIGTRAP +was delivered as a result of a user-space action, +for example, a system call +.RB ( tgkill (2), +.BR kill (2), +.BR sigqueue (3), +etc.), +expiration of a POSIX timer, +change of state on a POSIX message queue, +or completion of an asynchronous I/O request. +.TP +.IR si_code " == SI_KERNEL (0x80)" +.B SIGTRAP +was sent by the kernel. +.TP +.IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)" +This is a syscall-stop. +.PP +However, syscall-stops happen very often (twice per system call), +and performing +.B PTRACE_GETSIGINFO +for every syscall-stop may be somewhat expensive. +.PP +Some architectures allow the cases to be distinguished +by examining registers. +For example, on x86, +.I rax +== +.RB - ENOSYS +in syscall-enter-stop. +Since +.B SIGTRAP +(like any other signal) always happens +.I after +syscall-exit-stop, +and at this point +.I rax +almost never contains +.RB - ENOSYS , +the +.B SIGTRAP +looks like "syscall-stop which is not syscall-enter-stop"; +in other words, it looks like a +"stray syscall-exit-stop" and can be detected this way. +But such detection is fragile and is best avoided. +.PP +Using the +.B PTRACE_O_TRACESYSGOOD +option is the recommended method to distinguish syscall-stops +from other kinds of ptrace-stops, +since it is reliable and does not incur a performance penalty. +.PP +Syscall-enter-stop and syscall-exit-stop are +indistinguishable from each other by the tracer. +The tracer needs to keep track of the sequence of +ptrace-stops in order to not misinterpret syscall-enter-stop as +syscall-exit-stop or vice versa. +In general, a syscall-enter-stop is +always followed by syscall-exit-stop, +.B PTRACE_EVENT +stop, or the tracee's death; +no other kinds of ptrace-stop can occur in between. +However, note that seccomp stops (see below) can cause syscall-exit-stops, +without preceding syscall-entry-stops. +If seccomp is in use, care needs +to be taken not to misinterpret such stops as syscall-entry-stops. +.PP +If after syscall-enter-stop, +the tracer uses a restarting command other than +.BR PTRACE_SYSCALL , +syscall-exit-stop is not generated. +.PP +.B PTRACE_GETSIGINFO +on syscall-stops returns +.B SIGTRAP +in +.IR si_signo , +with +.I si_code +set to +.B SIGTRAP +or +.IR (SIGTRAP|0x80) . +.\" +.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7) +The behavior of +.BR PTRACE_EVENT_SECCOMP +stops and their interaction with other kinds +of ptrace stops has changed between kernel versions. +This documents the behavior +from their introduction until Linux 4.7 (inclusive). +The behavior in later kernel versions is documented in the next section. +.PP +A +.BR PTRACE_EVENT_SECCOMP +stop occurs whenever a +.BR SECCOMP_RET_TRACE +rule is triggered. +This is independent of which methods was used to restart the system call. +Notably, seccomp still runs even if the tracee was restarted using +.BR PTRACE_SYSEMU +and this system call is unconditionally skipped. +.PP +Restarts from this stop will behave as if the stop had occurred right +before the system call in question. +In particular, both +.BR PTRACE_SYSCALL +and +.BR PTRACE_SYSEMU +will normally cause a subsequent syscall-entry-stop. +However, if after the +.BR PTRACE_EVENT_SECCOMP +the system call number is negative, +both the syscall-entry-stop and the system call itself will be skipped. +This means that if the system call number is negative after a +.BR PTRACE_EVENT_SECCOMP +and the tracee is restarted using +.BR PTRACE_SYSCALL, +the next observed stop will be a syscall-exit-stop, +rather than the syscall-entry-stop that might have been expected. +.\" +.SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8) +Starting with Linux 4.8, +.\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea +the +.BR PTRACE_EVENT_SECCOMP +stop was reordered to occur between syscall-entry-stop and +syscall-exit-stop. +Note that seccomp no longer runs (and no +.B PTRACE_EVENT_SECCOMP +will be reported) if the system call is skipped due to +.BR PTRACE_SYSEMU . +.PP +Functionally, a +.B PTRACE_EVENT_SECCOMP +stop functions comparably +to a syscall-entry-stop (i.e., continuations using +.BR PTRACE_SYSCALL +will cause syscall-exit-stops, +the system call number may be changed and any other modified registers +are visible to the to-be-executed system call as well). +Note that there may be, +but need not have been a preceding syscall-entry-stop. +.PP +After a +.BR PTRACE_EVENT_SECCOMP +stop, seccomp will be rerun, with a +.BR SECCOMP_RET_TRACE +rule now functioning the same as a +.BR SECCOMP_RET_ALLOW . +Specifically, this means that if registers are not modified during the +.BR PTRACE_EVENT_SECCOMP +stop, the system call will then be allowed. +.\" +.SS PTRACE_SINGLESTEP stops +[Details of these kinds of stops are yet to be documented.] +.\" +.\" FIXME . +.\" document stops occurring with PTRACE_SINGLESTEP +.\" +.SS Informational and restarting ptrace commands +Most ptrace commands (all except +.BR PTRACE_ATTACH , +.BR PTRACE_SEIZE , +.BR PTRACE_TRACEME , +.BR PTRACE_INTERRUPT , +and +.BR PTRACE_KILL ) +require the tracee to be in a ptrace-stop, otherwise they fail with +.BR ESRCH . +.PP +When the tracee is in ptrace-stop, +the tracer can read and write data to +the tracee using informational commands. +These commands leave the tracee in ptrace-stopped state: +.PP +.in +4n +.EX +ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0); +ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val); +ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct); +ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct); +ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov); +ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov); +ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo); +ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo); +ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var); +ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); +.EE +.in +.PP +Note that some errors are not reported. +For example, setting signal information +.RI ( siginfo ) +may have no effect in some ptrace-stops, yet the call may succeed +(return 0 and not set +.IR errno ); +querying +.B PTRACE_GETEVENTMSG +may succeed and return some random value if current ptrace-stop +is not documented as returning a meaningful event message. +.PP +The call +.PP + ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); +.PP +affects one tracee. +The tracee's current flags are replaced. +Flags are inherited by new tracees created and "auto-attached" via active +.BR PTRACE_O_TRACEFORK , +.BR PTRACE_O_TRACEVFORK , +or +.BR PTRACE_O_TRACECLONE +options. +.PP +Another group of commands makes the ptrace-stopped tracee run. +They have the form: +.PP + ptrace(cmd, pid, 0, sig); +.PP +where +.I cmd +is +.BR PTRACE_CONT , +.BR PTRACE_LISTEN , +.BR PTRACE_DETACH , +.BR PTRACE_SYSCALL , +.BR PTRACE_SINGLESTEP , +.BR PTRACE_SYSEMU , +or +.BR PTRACE_SYSEMU_SINGLESTEP . +If the tracee is in signal-delivery-stop, +.I sig +is the signal to be injected (if it is nonzero). +Otherwise, +.I sig +may be ignored. +(When restarting a tracee from a ptrace-stop other than signal-delivery-stop, +recommended practice is to always pass 0 in +.IR sig .) +.SS Attaching and detaching +A thread can be attached to the tracer using the call +.PP + ptrace(PTRACE_ATTACH, pid, 0, 0); +.PP +or +.PP + ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags); +.PP +.B PTRACE_ATTACH +sends +.B SIGSTOP +to this thread. +If the tracer wants this +.B SIGSTOP +to have no effect, it needs to suppress it. +Note that if other signals are concurrently sent to +this thread during attach, +the tracer may see the tracee enter signal-delivery-stop +with other signal(s) first! +The usual practice is to reinject these signals until +.B SIGSTOP +is seen, then suppress +.B SIGSTOP +injection. +The design bug here is that a ptrace attach and a concurrently delivered +.B SIGSTOP +may race and the concurrent +.B SIGSTOP +may be lost. +.\" +.\" FIXME Describe how to attach to a thread which is already group-stopped. +.PP +Since attaching sends +.B SIGSTOP +and the tracer usually suppresses it, this may cause a stray +.B EINTR +return from the currently executing system call in the tracee, +as described in the "Signal injection and suppression" section. +.PP +Since Linux 3.4, +.B PTRACE_SEIZE +can be used instead of +.BR PTRACE_ATTACH . +.B PTRACE_SEIZE +does not stop the attached process. +If you need to stop +it after attach (or at any other time) without sending it any signals, +use +.B PTRACE_INTERRUPT +command. +.PP +The request +.PP + ptrace(PTRACE_TRACEME, 0, 0, 0); +.PP +turns the calling thread into a tracee. +The thread continues to run (doesn't enter ptrace-stop). +A common practice is to follow the +.B PTRACE_TRACEME +with +.PP + raise(SIGSTOP); +.PP +and allow the parent (which is our tracer now) to observe our +signal-delivery-stop. +.PP +If the +.BR PTRACE_O_TRACEFORK , +.BR PTRACE_O_TRACEVFORK , +or +.BR PTRACE_O_TRACECLONE +options are in effect, then children created by, respectively, +.BR vfork (2) +or +.BR clone (2) +with the +.B CLONE_VFORK +flag, +.BR fork (2) +or +.BR clone (2) +with the exit signal set to +.BR SIGCHLD , +and other kinds of +.BR clone (2), +are automatically attached to the same tracer which traced their parent. +.B SIGSTOP +is delivered to the children, causing them to enter +signal-delivery-stop after they exit the system call which created them. +.PP +Detaching of the tracee is performed by: +.PP + ptrace(PTRACE_DETACH, pid, 0, sig); +.PP +.B PTRACE_DETACH +is a restarting operation; +therefore it requires the tracee to be in ptrace-stop. +If the tracee is in signal-delivery-stop, a signal can be injected. +Otherwise, the +.I sig +parameter may be silently ignored. +.PP +If the tracee is running when the tracer wants to detach it, +the usual solution is to send +.B SIGSTOP +(using +.BR tgkill (2), +to make sure it goes to the correct thread), +wait for the tracee to stop in signal-delivery-stop for +.B SIGSTOP +and then detach it (suppressing +.B SIGSTOP +injection). +A design bug is that this can race with concurrent +.BR SIGSTOP s. +Another complication is that the tracee may enter other ptrace-stops +and needs to be restarted and waited for again, until +.B SIGSTOP +is seen. +Yet another complication is to be sure that +the tracee is not already ptrace-stopped, +because no signal delivery happens while it is\(emnot even +.BR SIGSTOP . +.\" FIXME Describe how to detach from a group-stopped tracee so that it +.\" doesn't run, but continues to wait for SIGCONT. +.PP +If the tracer dies, all tracees are automatically detached and restarted, +unless they were in group-stop. +Handling of restart from group-stop is currently buggy, +but the "as planned" behavior is to leave tracee stopped and waiting for +.BR SIGCONT . +If the tracee is restarted from signal-delivery-stop, +the pending signal is injected. +.SS execve(2) under ptrace +.\" clone(2) CLONE_THREAD says: +.\" If any of the threads in a thread group performs an execve(2), +.\" then all threads other than the thread group leader are terminated, +.\" and the new program is executed in the thread group leader. +.\" +When one thread in a multithreaded process calls +.BR execve (2), +the kernel destroys all other threads in the process, +.\" In kernel 3.1 sources, see fs/exec.c::de_thread() +and resets the thread ID of the execing thread to the +thread group ID (process ID). +(Or, to put things another way, when a multithreaded process does an +.BR execve (2), +at completion of the call, it appears as though the +.BR execve (2) +occurred in the thread group leader, regardless of which thread did the +.BR execve (2).) +This resetting of the thread ID looks very confusing to tracers: +.IP * 3 +All other threads stop in +.B PTRACE_EVENT_EXIT +stop, if the +.BR PTRACE_O_TRACEEXIT +option was turned on. +Then all other threads except the thread group leader report +death as if they exited via +.BR _exit (2) +with exit code 0. +.IP * +The execing tracee changes its thread ID while it is in the +.BR execve (2). +(Remember, under ptrace, the "pid" returned from +.BR waitpid (2), +or fed into ptrace calls, is the tracee's thread ID.) +That is, the tracee's thread ID is reset to be the same as its process ID, +which is the same as the thread group leader's thread ID. +.IP * +Then a +.B PTRACE_EVENT_EXEC +stop happens, if the +.BR PTRACE_O_TRACEEXEC +option was turned on. +.IP * +If the thread group leader has reported its +.B PTRACE_EVENT_EXIT +stop by this time, +it appears to the tracer that +the dead thread leader "reappears from nowhere". +(Note: the thread group leader does not report death via +.I WIFEXITED(status) +until there is at least one other live thread. +This eliminates the possibility that the tracer will see +it dying and then reappearing.) +If the thread group leader was still alive, +for the tracer this may look as if thread group leader +returns from a different system call than it entered, +or even "returned from a system call even though +it was not in any system call". +If the thread group leader was not traced +(or was traced by a different tracer), then during +.BR execve (2) +it will appear as if it has become a tracee of +the tracer of the execing tracee. +.PP +All of the above effects are the artifacts of +the thread ID change in the tracee. +.PP +The +.B PTRACE_O_TRACEEXEC +option is the recommended tool for dealing with this situation. +First, it enables +.BR PTRACE_EVENT_EXEC +stop, +which occurs before +.BR execve (2) +returns. +In this stop, the tracer can use +.B PTRACE_GETEVENTMSG +to retrieve the tracee's former thread ID. +(This feature was introduced in Linux 3.0.) +Second, the +.B PTRACE_O_TRACEEXEC +option disables legacy +.B SIGTRAP +generation on +.BR execve (2). +.PP +When the tracer receives +.B PTRACE_EVENT_EXEC +stop notification, +it is guaranteed that except this tracee and the thread group leader, +no other threads from the process are alive. +.PP +On receiving the +.B PTRACE_EVENT_EXEC +stop notification, +the tracer should clean up all its internal +data structures describing the threads of this process, +and retain only one data structure\(emone which +describes the single still running tracee, with +.PP + thread ID == thread group ID == process ID. +.PP +Example: two threads call +.BR execve (2) +at the same time: +.PP +.nf +*** we get syscall-enter-stop in thread 1: ** +PID1 execve("/bin/foo", "foo" +*** we issue PTRACE_SYSCALL for thread 1 ** +*** we get syscall-enter-stop in thread 2: ** +PID2 execve("/bin/bar", "bar" +*** we issue PTRACE_SYSCALL for thread 2 ** +*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL ** +*** we get syscall-exit-stop for PID0: ** +PID0 <... execve resumed> ) = 0 +.fi +.PP +If the +.B PTRACE_O_TRACEEXEC +option is +.I not +in effect for the execing tracee, +and if the tracee was +.BR PTRACE_ATTACH ed +rather that +.BR PTRACE_SEIZE d, +the kernel delivers an extra +.B SIGTRAP +to the tracee after +.BR execve (2) +returns. +This is an ordinary signal (similar to one which can be +generated by +.IR "kill -TRAP" ), +not a special kind of ptrace-stop. +Employing +.B PTRACE_GETSIGINFO +for this signal returns +.I si_code +set to 0 +.RI ( SI_USER ). +This signal may be blocked by signal mask, +and thus may be delivered (much) later. +.PP +Usually, the tracer (for example, +.BR strace (1)) +would not want to show this extra post-execve +.B SIGTRAP +signal to the user, and would suppress its delivery to the tracee (if +.B SIGTRAP +is set to +.BR SIG_DFL , +it is a killing signal). +However, determining +.I which +.B SIGTRAP +to suppress is not easy. +Setting the +.B PTRACE_O_TRACEEXEC +option or using +.B PTRACE_SEIZE +and thus suppressing this extra +.B SIGTRAP +is the recommended approach. +.SS Real parent +The ptrace API (ab)uses the standard UNIX parent/child signaling over +.BR waitpid (2). +This used to cause the real parent of the process to stop receiving +several kinds of +.BR waitpid (2) +notifications when the child process is traced by some other process. +.PP +Many of these bugs have been fixed, but as of Linux 2.6.38 several still +exist; see BUGS below. +.PP +As of Linux 2.6.38, the following is believed to work correctly: +.IP * 3 +exit/death by signal is reported first to the tracer, then, +when the tracer consumes the +.BR waitpid (2) +result, to the real parent (to the real parent only when the +whole multithreaded process exits). +If the tracer and the real parent are the same process, +the report is sent only once. +.SH RETURN VALUE +On success, the +.B PTRACE_PEEK* +requests return the requested data (but see NOTES), +while other requests return zero. +.PP +On error, all requests return \-1, and +.I errno +is set appropriately. +Since the value returned by a successful +.B PTRACE_PEEK* +request may be \-1, the caller must clear +.I errno +before the call, and then check it afterward +to determine whether or not an error occurred. +.SH ERRORS +.TP +.B EBUSY +(i386 only) There was an error with allocating or freeing a debug register. +.TP +.B EFAULT +There was an attempt to read from or write to an invalid area in +the tracer's or the tracee's memory, +probably because the area wasn't mapped or accessible. +Unfortunately, under Linux, different variations of this fault +will return +.B EIO +or +.B EFAULT +more or less arbitrarily. +.TP +.B EINVAL +An attempt was made to set an invalid option. +.TP +.B EIO +.I request +is invalid, or an attempt was made to read from or +write to an invalid area in the tracer's or the tracee's memory, +or there was a word-alignment violation, +or an invalid signal was specified during a restart request. +.TP +.B EPERM +The specified process cannot be traced. +This could be because the +tracer has insufficient privileges (the required capability is +.BR CAP_SYS_PTRACE ); +unprivileged processes cannot trace processes that they +cannot send signals to or those running +set-user-ID/set-group-ID programs, for obvious reasons. +Alternatively, the process may already be being traced, +or (on kernels before 2.6.26) be +.BR init (1) +(PID 1). +.TP +.B ESRCH +The specified process does not exist, or is not currently being traced +by the caller, or is not stopped +(for requests that require a stopped tracee). +.SH CONFORMING TO +SVr4, 4.3BSD. +.SH NOTES +Although arguments to +.BR ptrace () +are interpreted according to the prototype given, +glibc currently declares +.BR ptrace () +as a variadic function with only the +.I request +argument fixed. +It is recommended to always supply four arguments, +even if the requested operation does not use them, +setting unused/ignored arguments to +.I 0L +or +.IR "(void\ *)\ 0". +.PP +In Linux kernels before 2.6.26, +.\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb +.BR init (1), +the process with PID 1, may not be traced. +.PP +A tracees parent continues to be the tracer even if that tracer calls +.BR execve (2). +.PP +The layout of the contents of memory and the USER area are +quite operating-system- and architecture-specific. +The offset supplied, and the data returned, +might not entirely match with the definition of +.IR "struct user" . +.\" See http://lkml.org/lkml/2008/5/8/375 +.PP +The size of a "word" is determined by the operating-system variant +(e.g., for 32-bit Linux it is 32 bits). +.PP +This page documents the way the +.BR ptrace () +call works currently in Linux. +Its behavior differs significantly on other flavors of UNIX. +In any case, use of +.BR ptrace () +is highly specific to the operating system and architecture. +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS Ptrace access mode checking +Various parts of the kernel-user-space API (not just +.BR ptrace () +operations), require so-called "ptrace access mode" checks, +whose outcome determines whether an operation is permitted +(or, in a few cases, causes a "read" operation to return sanitized data). +These checks are performed in cases where one process can +inspect sensitive information about, +or in some cases modify the state of, another process. +The checks are based on factors such as the credentials and capabilities +of the two processes, +whether or not the "target" process is dumpable, +and the results of checks performed by any enabled Linux Security Module +(LSM)\(emfor example, SELinux, Yama, or Smack\(emand by the commoncap LSM +(which is always invoked). +.PP +Prior to Linux 2.6.27, all access checks were of a single type. +Since Linux 2.6.27, +.\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd +two access mode levels are distinguished: +.TP +.BR PTRACE_MODE_READ +For "read" operations or other operations that are less dangerous, +such as: +.BR get_robust_list (2); +.BR kcmp (2); +reading +.IR /proc/[pid]/auxv , +.IR /proc/[pid]/environ , +or +.IR /proc/[pid]/stat ; +or +.BR readlink (2) +of a +.IR /proc/[pid]/ns/* +file. +.TP +.BR PTRACE_MODE_ATTACH +For "write" operations, or other operations that are more dangerous, +such as: ptrace attaching +.RB ( PTRACE_ATTACH ) +to another process +or calling +.BR process_vm_writev (2). +.RB ( PTRACE_MODE_ATTACH +was effectively the default before Linux 2.6.27.) +.\" +.\" Regarding the above description of the distinction between +.\" PTRACE_MODE_READ and PTRACE_MODE_ATTACH, Stephen Smalley notes: +.\" +.\" That was the intent when the distinction was introduced, but it doesn't +.\" appear to have been properly maintained, e.g. there is now a common +.\" helper lock_trace() that is used for +.\" /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and +.\" PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show(). Likely +.\" should review and make them consistent. There was also some debate +.\" about proper handling of /proc/pid/fd. Arguably that one might belong +.\" back in the _ATTACH camp. +.\" +.PP +Since Linux 4.5, +.\" commit caaee6234d05a58c5b4d05e7bf766131b810a657 +the above access mode checks are combined (ORed) with +one of the following modifiers: +.TP +.B PTRACE_MODE_FSCREDS +Use the caller's filesystem UID and GID (see +.BR credentials (7)) +or effective capabilities for LSM checks. +.TP +.B PTRACE_MODE_REALCREDS +Use the caller's real UID and GID or permitted capabilities for LSM checks. +This was effectively the default before Linux 4.5. +.PP +Because combining one of the credential modifiers with one of +the aforementioned access modes is typical, +some macros are defined in the kernel sources for the combinations: +.TP +.B PTRACE_MODE_READ_FSCREDS +Defined as +.BR "PTRACE_MODE_READ | PTRACE_MODE_FSCREDS" . +.TP +.B PTRACE_MODE_READ_REALCREDS +Defined as +.BR "PTRACE_MODE_READ | PTRACE_MODE_REALCREDS" . +.TP +.B PTRACE_MODE_ATTACH_FSCREDS +Defined as +.BR "PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS" . +.TP +.B PTRACE_MODE_ATTACH_REALCREDS +Defined as +.BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" . +.PP +One further modifier can be ORed with the access mode: +.TP +.BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)" +.\" commit 69f594a38967f4540ce7a29b3fd214e68a8330bd +.\" Just for /proc/pid/stat +Don't audit this access mode check. +This modifier is employed for ptrace access mode checks +(such as checks when reading +.IR /proc/[pid]/stat ) +that merely cause the output to be filtered or sanitized, +rather than causing an error to be returned to the caller. +In these cases, accessing the file is not a security violation and +there is no reason to generate a security audit record. +This modifier suppresses the generation of +such an audit record for the particular access check. +.PP +Note that all of the +.BR PTRACE_MODE_* +constants described in this subsection are kernel-internal, +and not visible to user space. +The constant names are mentioned here in order to label the various kinds of +ptrace access mode checks that are performed for various system calls +and accesses to various pseudofiles (e.g., under +.IR /proc ). +These names are used in other manual pages to provide a simple +shorthand for labeling the different kernel checks. +.PP +The algorithm employed for ptrace access mode checking determines whether +the calling process is allowed to perform the corresponding action +on the target process. +(In the case of opening +.IR /proc/[pid] +files, the "calling process" is the one opening the file, +and the process with the corresponding PID is the "target process".) +The algorithm is as follows: +.IP 1. 3 +If the calling thread and the target thread are in the same +thread group, access is always allowed. +.IP 2. +If the access mode specifies +.BR PTRACE_MODE_FSCREDS , +then, for the check in the next step, +employ the caller's filesystem UID and GID. +(As noted in +.BR credentials (7), +the filesystem UID and GID almost always have the same values +as the corresponding effective IDs.) +.IP +Otherwise, the access mode specifies +.BR PTRACE_MODE_REALCREDS , +so use the caller's real UID and GID for the checks in the next step. +(Most APIs that check the caller's UID and GID use the effective IDs. +For historical reasons, the +.BR PTRACE_MODE_REALCREDS +check uses the real IDs instead.) +.IP 3. +Deny access if +.I neither +of the following is true: +.RS +.IP \(bu 2 +The real, effective, and saved-set user IDs of the target +match the caller's user ID, +.IR and +the real, effective, and saved-set group IDs of the target +match the caller's group ID. +.IP \(bu +The caller has the +.B CAP_SYS_PTRACE +capability in the user namespace of the target. +.RE +.IP 4. +Deny access if the target process "dumpable" attribute has a value other than 1 +.RB ( SUID_DUMP_USER ; +see the discussion of +.BR PR_SET_DUMPABLE +in +.BR prctl (2)), +and the caller does not have the +.BR CAP_SYS_PTRACE +capability in the user namespace of the target process. +.IP 5. +The kernel LSM +.IR security_ptrace_access_check () +interface is invoked to see if ptrace access is permitted. +The results depend on the LSM(s). +The implementation of this interface in the commoncap LSM performs +the following steps: +.\" (in cap_ptrace_access_check()): +.RS +.IP a) 3 +If the access mode includes +.BR PTRACE_MODE_FSCREDS , +then use the caller's +.I effective +capability set +in the following check; +otherwise (the access mode specifies +.BR PTRACE_MODE_REALCREDS , +so) use the caller's +.I permitted +capability set. +.IP b) +Deny access if +.I neither +of the following is true: +.RS +.IP \(bu 2 +The caller and the target process are in the same user namespace, +and the caller's capabilities are a proper superset of the target process's +.I permitted +capabilities. +.IP \(bu +The caller has the +.B CAP_SYS_PTRACE +capability in the target process's user namespace. +.RE +.IP +Note that the commoncap LSM does not distinguish between +.B PTRACE_MODE_READ +and +.BR PTRACE_MODE_ATTACH . +.RE +.IP 6. +If access has not been denied by any of the preceding steps, +then access is allowed. +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS /proc/sys/kernel/yama/ptrace_scope +On systems with the Yama Linux Security Module (LSM) installed +(i.e., the kernel was configured with +.BR CONFIG_SECURITY_YAMA ), +the +.I /proc/sys/kernel/yama/ptrace_scope +file (available since Linux 3.4) +.\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb +can be used to restrict the ability to trace a process with +.BR ptrace () +(and thus also the ability to use tools such as +.BR strace (1) +and +.BR gdb (1)). +The goal of such restrictions is to prevent attack escalation whereby +a compromised process can ptrace-attach to other sensitive processes +(e.g., a GPG agent or an SSH session) owned by the user in order +to gain additional credentials that may exist in memory +and thus expand the scope of the attack. +.PP +More precisely, the Yama LSM limits two types of operations: +.IP * 3 +Any operation that performs a ptrace access mode +.BR PTRACE_MODE_ATTACH +check\(emfor example, +.BR ptrace () +.BR PTRACE_ATTACH . +(See the "Ptrace access mode checking" discussion above.) +.IP +.IP * +.BR ptrace () +.BR PTRACE_TRACEME . +.PP +A process that has the +.B CAP_SYS_PTRACE +capability can update the +.IR /proc/sys/kernel/yama/ptrace_scope +file with one of the following values: +.TP +0 ("classic ptrace permissions") +No additional restrictions on operations that perform +.BR PTRACE_MODE_ATTACH +checks (beyond those imposed by the commoncap and other LSMs). +.IP +The use of +.BR PTRACE_TRACEME +is unchanged. +.TP +1 ("restricted ptrace") [default value] +When performing an operation that requires a +.BR PTRACE_MODE_ATTACH +check, the calling process must either have the +.B CAP_SYS_PTRACE +capability in the user namespace of the target process or +it must have a predefined relationship with the target process. +By default, +the predefined relationship is that the target process +must be a descendant of the caller. +.IP +A target process can employ the +.BR prctl (2) +.B PR_SET_PTRACER +operation to declare an additional PID that is allowed to perform +.BR PTRACE_MODE_ATTACH +operations on the target. +See the kernel source file +.IR Documentation/admin\-guide/LSM/Yama.rst +.\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22 +(or +.IR Documentation/security/Yama.txt +before Linux 4.13) +for further details. +.IP +The use of +.BR PTRACE_TRACEME +is unchanged. +.TP +2 ("admin-only attach") +Only processes with the +.B CAP_SYS_PTRACE +capability in the user namespace of the target process may perform +.BR PTRACE_MODE_ATTACH +operations or trace children that employ +.BR PTRACE_TRACEME . +.TP +3 ("no attach") +No process may perform +.BR PTRACE_MODE_ATTACH +operations or trace children that employ +.BR PTRACE_TRACEME . +.IP +Once this value has been written to the file, it cannot be changed. +.PP +With respect to values 1 and 2, +note that creating a new user namespace effectively removes the +protection offered by Yama. +This is because a process in the parent user namespace whose effective +UID matches the UID of the creator of a child namespace +has all capabilities (including +.BR CAP_SYS_PTRACE ) +when performing operations within the child user namespace +(and further-removed descendants of that namespace). +Consequently, when a process tries to use user namespaces to sandbox itself, +it inadvertently weakens the protections offered by the Yama LSM. +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS C library/kernel differences +At the system call level, the +.BR PTRACE_PEEKTEXT , +.BR PTRACE_PEEKDATA , +and +.BR PTRACE_PEEKUSER +requests have a different API: they store the result +at the address specified by the +.I data +parameter, and the return value is the error flag. +The glibc wrapper function provides the API given in DESCRIPTION above, +with the result being returned via the function return value. +.SH BUGS +On hosts with 2.6 kernel headers, +.B PTRACE_SETOPTIONS +is declared with a different value than the one for 2.4. +This leads to applications compiled with 2.6 kernel +headers failing when run on 2.4 kernels. +This can be worked around by redefining +.B PTRACE_SETOPTIONS +to +.BR PTRACE_OLDSETOPTIONS , +if that is defined. +.PP +Group-stop notifications are sent to the tracer, but not to real parent. +Last confirmed on 2.6.38.6. +.PP +If a thread group leader is traced and exits by calling +.BR _exit (2), +.\" Note from Denys Vlasenko: +.\" Here "exits" means any kind of death - _exit, exit_group, +.\" signal death. Signal death and exit_group cases are trivial, +.\" though: since signal death and exit_group kill all other threads +.\" too, "until all other threads exit" thing happens rather soon +.\" in these cases. Therefore, only _exit presents observably +.\" puzzling behavior to ptrace users: thread leader _exit's, +.\" but WIFEXITED isn't reported! We are trying to explain here +.\" why it is so. +a +.B PTRACE_EVENT_EXIT +stop will happen for it (if requested), but the subsequent +.B WIFEXITED +notification will not be delivered until all other threads exit. +As explained above, if one of other threads calls +.BR execve (2), +the death of the thread group leader will +.I never +be reported. +If the execed thread is not traced by this tracer, +the tracer will never know that +.BR execve (2) +happened. +One possible workaround is to +.B PTRACE_DETACH +the thread group leader instead of restarting it in this case. +Last confirmed on 2.6.38.6. +.\" FIXME . need to test/verify this scenario +.PP +A +.B SIGKILL +signal may still cause a +.B PTRACE_EVENT_EXIT +stop before actual signal death. +This may be changed in the future; +.B SIGKILL +is meant to always immediately kill tasks even under ptrace. +Last confirmed on Linux 3.13. +.PP +Some system calls return with +.B EINTR +if a signal was sent to a tracee, but delivery was suppressed by the tracer. +(This is very typical operation: it is usually +done by debuggers on every attach, in order to not introduce +a bogus +.BR SIGSTOP ). +As of Linux 3.2.9, the following system calls are affected +(this list is likely incomplete): +.BR epoll_wait (2), +and +.BR read (2) +from an +.BR inotify (7) +file descriptor. +The usual symptom of this bug is that when you attach to +a quiescent process with the command +.PP +.in +4n +.EX +strace \-p +.EE +.in +.PP +then, instead of the usual +and expected one-line output such as +.PP +.in +4n +.EX +restart_syscall(<... resuming interrupted call ...>_ +.EE +.in +.PP +or +.PP +.in +4n +.EX +select(6, [5], NULL, [5], NULL_ +.EE +.in +.PP +('_' denotes the cursor position), you observe more than one line. +For example: +.PP +.in +4n +.EX + clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0 + epoll_wait(4,_ +.EE +.in +.PP +What is not visible here is that the process was blocked in +.BR epoll_wait (2) +before +.BR strace (1) +has attached to it. +Attaching caused +.BR epoll_wait (2) +to return to user space with the error +.BR EINTR . +In this particular case, the program reacted to +.B EINTR +by checking the current time, and then executing +.BR epoll_wait (2) +again. +(Programs which do not expect such "stray" +.BR EINTR +errors may behave in an unintended way upon an +.BR strace (1) +attach.) +.SH SEE ALSO +.BR gdb (1), +.BR ltrace (1), +.BR strace (1), +.BR clone (2), +.BR execve (2), +.BR fork (2), +.BR gettid (2), +.BR prctl (2), +.BR seccomp (2), +.BR sigaction (2), +.BR tgkill (2), +.BR vfork (2), +.BR waitpid (2), +.BR exec (3), +.BR capabilities (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/putmsg.2 b/man2/putmsg.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/putmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/putpmsg.2 b/man2/putpmsg.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/putpmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/pwrite.2 b/man2/pwrite.2 new file mode 100644 index 0000000..87eacb2 --- /dev/null +++ b/man2/pwrite.2 @@ -0,0 +1 @@ +.so man2/pread.2 diff --git a/man2/pwrite64.2 b/man2/pwrite64.2 new file mode 100644 index 0000000..9290e0a --- /dev/null +++ b/man2/pwrite64.2 @@ -0,0 +1 @@ +.so man2/pwrite.2 diff --git a/man2/pwritev.2 b/man2/pwritev.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man2/pwritev.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man2/pwritev2.2 b/man2/pwritev2.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man2/pwritev2.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man2/query_module.2 b/man2/query_module.2 new file mode 100644 index 0000000..5a5993c --- /dev/null +++ b/man2/query_module.2 @@ -0,0 +1,208 @@ +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" reformatting and rewordings by mtk +.\" +.TH QUERY_MODULE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +query_module \- query the kernel for various bits pertaining to modules +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int query_module(const char *" name ", int " which ", void *" buf , +.BI " size_t " bufsize ", size_t *" ret ); +.fi +.PP +.IR Note : +No declaration of this system call is provided in glibc headers; see NOTES. +.SH DESCRIPTION +.IR Note : +This system call is present only in kernels before Linux 2.6. +.PP +.BR query_module () +requests information from the kernel about loadable modules. +The returned information is placed in the buffer pointed to by +.IR buf . +The caller must specify the size of +.I buf +in +.IR bufsize . +The precise nature and format of the returned information +depend on the operation specified by +.IR which . +Some operations require +.I name +to identify a currently loaded module, some allow +.I name +to be NULL, indicating the kernel proper. +.PP +The following values can be specified for +.IR which : +.TP +.B 0 +Returns success, if the kernel supports +.BR query_module (). +Used to probe for availability of the system call. +.TP +.B QM_MODULES +Returns the names of all loaded modules. +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of +modules. +.\" ret is set on ENOSPC +.TP +.B QM_DEPS +Returns the names of all modules used by the indicated module. +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of modules. +.\" ret is set on ENOSPC +.TP +.B QM_REFS +Returns the names of all modules using the indicated module. +This is the inverse of +.BR QM_DEPS . +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of modules. +.\" ret is set on ENOSPC +.TP +.B QM_SYMBOLS +Returns the symbols and values exported by the kernel or the indicated +module. +The returned buffer is an array of structures of the following form +.\" ret is set on ENOSPC +.IP +.in +4n +.EX +struct module_symbol { + unsigned long value; + unsigned long name; +}; +.EE +.in +.IP +followed by null-terminated strings. +The value of +.I name +is the character offset of the string relative to the start of +.IR buf ; +.I ret +is set to the number of symbols. +.TP +.B QM_INFO +Returns miscellaneous information about the indicated module. +The output buffer format is: +.IP +.in +4n +.EX +struct module_info { + unsigned long address; + unsigned long size; + unsigned long flags; +}; +.EE +.in +.IP +where +.I address +is the kernel address at which the module resides, +.I size +is the size of the module in bytes, and +.I flags +is a mask of +.BR MOD_RUNNING , +.BR MOD_AUTOCLEAN , +and so on, that indicates the current status of the module +(see the Linux kernel source file +.IR include/linux/module.h ). +.I ret +is set to the size of the +.I module_info +structure. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +At least one of +.IR name , +.IR buf , +or +.I ret +was outside the program's accessible address space. +.TP +.B EINVAL +Invalid +.IR which ; +or +.I name +is NULL (indicating "the kernel"), +but this is not permitted with the specified value of +.IR which . +.\" Not permitted with QM_DEPS, QM_REFS, or QM_INFO. +.TP +.B ENOENT +No module by that +.I name +exists. +.TP +.B ENOSPC +The buffer size provided was too small. +.I ret +is set to the minimum size needed. +.TP +.B ENOSYS +.BR query_module () +is not supported in this version of the kernel +(e.g., the kernel is version 2.6 or later). +.SH VERSIONS +This system call is present on Linux only up until kernel 2.4; +it was removed in Linux 2.6. +.\" Removed in Linux 2.5.48 +.SH CONFORMING TO +.BR query_module () +is Linux-specific. +.SH NOTES +Some of the information that was formerly available via +.BR query_module () +can be obtained from +.IR /proc/modules , +.IR /proc/kallsyms , +and the files under the directory +.IR /sys/module . +.PP +The +.BR query_module () +system call is not supported by glibc. +No declaration is provided in glibc headers, but, +through a quirk of history, glibc does export an ABI for this system call. +Therefore, in order to employ this system call, +it is sufficient to manually declare the interface in your code; +alternatively, you can invoke the system call using +.BR syscall (2). +.SH SEE ALSO +.BR create_module (2), +.BR delete_module (2), +.BR get_kernel_syms (2), +.BR init_module (2), +.BR lsmod (8), +.BR modinfo (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/quotactl.2 b/man2/quotactl.2 new file mode 100644 index 0000000..1fa8fee --- /dev/null +++ b/man2/quotactl.2 @@ -0,0 +1,807 @@ +.\" Copyright (c) 2010, Jan Kara +.\" A few pieces copyright (c) 1996 Andries Brouwer (aeb@cwi.nl) +.\" and copyright 2010 (c) Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume +.\" no responsibility for errors or omissions, or for damages resulting +.\" from the use of the information contained herein. The author(s) may +.\" not have taken the same level of care in the production of this +.\" manual, which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH QUOTACTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +quotactl \- manipulate disk quotas +.SH SYNOPSIS +.nf +.B #include +.B #include /* for XFS quotas */ +.PP +.BI "int quotactl(int " cmd ", const char *" special ", int " id \ +", caddr_t " addr ); +.fi +.SH DESCRIPTION +.PP +The quota system can be used to set per-user, per-group, and per-project limits +on the amount of disk space used on a filesystem. +For each user and/or group, +a soft limit and a hard limit can be set for each filesystem. +The hard limit can't be exceeded. +The soft limit can be exceeded, but warnings will ensue. +Moreover, the user can't exceed the soft limit for more than grace period +duration (one week by default) at a time; +after this, the soft limit counts as a hard limit. +.PP +The +.BR quotactl () +call manipulates disk quotas. +The +.I cmd +argument indicates a command to be applied to the user or +group ID specified in +.IR id . +To initialize the +.IR cmd +argument, use the +.IR "QCMD(subcmd, type)" +macro. +The +.I type +value is either +.BR USRQUOTA , +for user quotas, +.BR GRPQUOTA , +for group quotas, or (since Linux 4.1) +.\" 847aac644e92e5624f2c153bab409bf713d5ff9a +.BR PRJQUOTA , +for project quotas. +The +.I subcmd +value is described below. +.PP +The +.I special +argument is a pointer to a null-terminated string containing the pathname +of the (mounted) block special device for the filesystem being manipulated. +.PP +The +.I addr +argument is the address of an optional, command-specific, data structure +that is copied in or out of the system. +The interpretation of +.I addr +is given with each command below. +.PP +The +.I subcmd +value is one of the following: +.TP 8 +.B Q_QUOTAON +Turn on quotas for a filesystem. +The +.I id +argument is the identification number of the quota format to be used. +Currently, there are three supported quota formats: +.RS +.TP 13 +.BR QFMT_VFS_OLD +The original quota format. +.TP +.BR QFMT_VFS_V0 +The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs +and quota limits up to 2^42 bytes and 2^32 inodes. +.TP +.BR QFMT_VFS_V1 +A quota format that can handle 32-bit UIDs and GIDs +and quota limits of 2^64 bytes and 2^64 inodes. +.RE +.IP +The +.IR addr +argument points to the pathname of a file containing the quotas for +the filesystem. +The quota file must exist; it is normally created with the +.BR quotacheck (8) +program. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP 8 +.B Q_QUOTAOFF +Turn off quotas for a filesystem. +The +.I addr +and +.I id +arguments are ignored. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.B Q_GETQUOTA +Get disk quota limits and current usage for user or group +.IR id . +The +.I addr +argument is a pointer to a +.I dqblk +structure defined in +.IR +as follows: +.IP +.in +4n +.EX +/* uint64_t is an unsigned 64\-bit integer; + uint32_t is an unsigned 32\-bit integer */ + +struct dqblk { /* Definition since Linux 2.4.22 */ + uint64_t dqb_bhardlimit; /* Absolute limit on disk + quota blocks alloc */ + uint64_t dqb_bsoftlimit; /* Preferred limit on + disk quota blocks */ + uint64_t dqb_curspace; /* Current occupied space + (in bytes) */ + uint64_t dqb_ihardlimit; /* Maximum number of + allocated inodes */ + uint64_t dqb_isoftlimit; /* Preferred inode limit */ + uint64_t dqb_curinodes; /* Current number of + allocated inodes */ + uint64_t dqb_btime; /* Time limit for excessive + disk use */ + uint64_t dqb_itime; /* Time limit for excessive + files */ + uint32_t dqb_valid; /* Bit mask of QIF_* + constants */ +}; + +/* Flags in dqb_valid that indicate which fields in + dqblk structure are valid. */ + +#define QIF_BLIMITS 1 +#define QIF_SPACE 2 +#define QIF_ILIMITS 4 +#define QIF_INODES 8 +#define QIF_BTIME 16 +#define QIF_ITIME 32 +#define QIF_LIMITS (QIF_BLIMITS | QIF_ILIMITS) +#define QIF_USAGE (QIF_SPACE | QIF_INODES) +#define QIF_TIMES (QIF_BTIME | QIF_ITIME) +#define QIF_ALL (QIF_LIMITS | QIF_USAGE | QIF_TIMES) +.EE +.in +.IP +The +.I dqb_valid +field is a bit mask that is set to indicate the entries in the +.I dqblk +structure that are valid. +Currently, the kernel fills in all entries of the +.I dqblk +structure and marks them as valid in the +.I dqb_valid +field. +Unprivileged users may retrieve only their own quotas; +a privileged user +.RB ( CAP_SYS_ADMIN ) +can retrieve the quotas of any user. +.TP +.BR Q_GETNEXTQUOTA " (since Linux 4.6)" +.\" commit 926132c0257a5a8d149a6a395cc3405e55420566 +This operation is the same as +.BR Q_GETQUOTA , +but it returns quota information for the next ID greater than or equal to +.IR id +that has a quota set. +.IP +The +.I addr +argument is a pointer to a +.I nextdqblk +structure whose fields are as for the +.IR dqblk , +except for the addition of a +.I dqb_id +field that is used to return the ID for which +quota information is being returned: +.IP +.in +4n +.EX +struct nextdqblk { + uint64_t dqb_bhardlimit; + uint64_t dqb_bsoftlimit; + uint64_t dqb_curspace; + uint64_t dqb_ihardlimit; + uint64_t dqb_isoftlimit; + uint64_t dqb_curinodes; + uint64_t dqb_btime; + uint64_t dqb_itime; + uint32_t dqb_valid; + uint32_t dqb_id; +}; +.EE +.in +.TP +.B Q_SETQUOTA +Set quota information for user or group +.IR id , +using the information supplied in the +.I dqblk +structure pointed to by +.IR addr . +The +.I dqb_valid +field of the +.I dqblk +structure indicates which entries in the structure have been set by the caller. +This operation supersedes the +.B Q_SETQLIM +and +.B Q_SETUSE +operations in the previous quota interfaces. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.BR Q_GETINFO " (since Linux 2.4.22)" +Get information (like grace times) about quotafile. +The +.I addr +argument should be a pointer to a +.I dqinfo +structure. +This structure is defined in +.IR +as follows: +.IP +.in +4n +.EX +/* uint64_t is an unsigned 64\-bit integer; + uint32_t is an unsigned 32\-bit integer */ + +struct dqinfo { /* Defined since kernel 2.4.22 */ + uint64_t dqi_bgrace; /* Time before block soft limit + becomes hard limit */ + uint64_t dqi_igrace; /* Time before inode soft limit + becomes hard limit */ + uint32_t dqi_flags; /* Flags for quotafile + (DQF_*) */ + uint32_t dqi_valid; +}; + +/* Bits for dqi_flags */ + +/* Quota format QFMT_VFS_OLD */ + +#define DQF_ROOT_SQUASH (1 << 0) /* Root squash enabled */ + /* Before Linux v4.0, this had been defined + privately as V1_DQF_RSQUASH */ + +/* Quota format QFMT_VFS_V0 / QFMT_VFS_V1 */ + +#define DQF_SYS_FILE (1 << 16) /* Quota stored in + a system file */ + +/* Flags in dqi_valid that indicate which fields in + dqinfo structure are valid. */ + +#define IIF_BGRACE 1 +#define IIF_IGRACE 2 +#define IIF_FLAGS 4 +#define IIF_ALL (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS) +.EE +.in +.IP +The +.I dqi_valid +field in the +.I dqinfo +structure indicates the entries in the structure that are valid. +Currently, the kernel fills in all entries of the +.I dqinfo +structure and marks them all as valid in the +.I dqi_valid +field. +The +.I id +argument is ignored. +.TP +.BR Q_SETINFO " (since Linux 2.4.22)" +Set information about quotafile. +The +.I addr +argument should be a pointer to a +.I dqinfo +structure. +The +.I dqi_valid +field of the +.I dqinfo +structure indicates the entries in the structure +that have been set by the caller. +This operation supersedes the +.B Q_SETGRACE +and +.B Q_SETFLAGS +operations in the previous quota interfaces. +The +.I id +argument is ignored. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.BR Q_GETFMT " (since Linux 2.4.22)" +Get quota format used on the specified filesystem. +The +.I addr +argument should be a pointer to a 4-byte buffer +where the format number will be stored. +.TP +.B Q_SYNC +Update the on-disk copy of quota usages for a filesystem. +If +.I special +is NULL, then all filesystems with active quotas are sync'ed. +The +.I addr +and +.I id +arguments are ignored. +.TP +.BR Q_GETSTATS " (supported up to Linux 2.4.21)" +Get statistics and other generic information about the quota subsystem. +The +.I addr +argument should be a pointer to a +.I dqstats +structure in which data should be stored. +This structure is defined in +.IR . +The +.I special +and +.I id +arguments are ignored. +.IP +This operation is obsolete and was removed in Linux 2.4.22. +Files in +.I /proc/sys/fs/quota/ +carry the information instead. +.PP +For XFS filesystems making use of the XFS Quota Manager (XQM), +the above commands are bypassed and the following commands are used: +.TP 8 +.B Q_XQUOTAON +Turn on quotas for an XFS filesystem. +XFS provides the ability to turn on/off quota limit enforcement +with quota accounting. +Therefore, XFS expects +.I addr +to be a pointer to an +.I "unsigned int" +that contains a combination of the following flags (defined in +.IR ): +.IP +.in +4n +.EX +#define XFS_QUOTA_UDQ_ACCT (1<<0) /* User quota + accounting */ +#define XFS_QUOTA_UDQ_ENFD (1<<1) /* User quota limits + enforcement */ +#define XFS_QUOTA_GDQ_ACCT (1<<2) /* Group quota + accounting */ +#define XFS_QUOTA_GDQ_ENFD (1<<3) /* Group quota limits + enforcement */ +#define XFS_QUOTA_PDQ_ACCT (1<<4) /* Project quota + accounting */ +#define XFS_QUOTA_PDQ_ENFD (1<<5) /* Project quota limits + enforcement */ +.EE +.in +.IP +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +The +.I id +argument is ignored. +.TP +.B Q_XQUOTAOFF +Turn off quotas for an XFS filesystem. +As with +.BR Q_QUOTAON , +XFS filesystems expect a pointer to an +.I "unsigned int" +that specifies whether quota accounting and/or limit enforcement need +to be turned off (using the same flags as for +.B Q_XQUOTAON +subcommand). +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +The +.I id +argument is ignored. +.TP +.B Q_XGETQUOTA +Get disk quota limits and current usage for user +.IR id . +The +.I addr +argument is a pointer to an +.I fs_disk_quota +structure, which is defined in +.I +as follows: +.IP +.in +4n +.EX +/* All the blk units are in BBs (Basic Blocks) of + 512 bytes. */ + +#define FS_DQUOT_VERSION 1 /* fs_disk_quota.d_version */ + +#define XFS_USER_QUOTA (1<<0) /* User quota type */ +#define XFS_PROJ_QUOTA (1<<1) /* Project quota type */ +#define XFS_GROUP_QUOTA (1<<2) /* Group quota type */ + +struct fs_disk_quota { + int8_t d_version; /* Version of this structure */ + int8_t d_flags; /* XFS_{USER,PROJ,GROUP}_QUOTA */ + uint16_t d_fieldmask; /* Field specifier */ + uint32_t d_id; /* User, project, or group ID */ + uint64_t d_blk_hardlimit; /* Absolute limit on + disk blocks */ + uint64_t d_blk_softlimit; /* Preferred limit on + disk blocks */ + uint64_t d_ino_hardlimit; /* Maximum # allocated + inodes */ + uint64_t d_ino_softlimit; /* Preferred inode limit */ + uint64_t d_bcount; /* # disk blocks owned by + the user */ + uint64_t d_icount; /* # inodes owned by the user */ + int32_t d_itimer; /* Zero if within inode limits */ + /* If not, we refuse service */ + int32_t d_btimer; /* Similar to above; for + disk blocks */ + uint16_t d_iwarns; /* # warnings issued with + respect to # of inodes */ + uint16_t d_bwarns; /* # warnings issued with + respect to disk blocks */ + int32_t d_padding2; /* Padding - for future use */ + uint64_t d_rtb_hardlimit; /* Absolute limit on realtime + (RT) disk blocks */ + uint64_t d_rtb_softlimit; /* Preferred limit on RT + disk blocks */ + uint64_t d_rtbcount; /* # realtime blocks owned */ + int32_t d_rtbtimer; /* Similar to above; for RT + disk blocks */ + uint16_t d_rtbwarns; /* # warnings issued with + respect to RT disk blocks */ + int16_t d_padding3; /* Padding - for future use */ + char d_padding4[8]; /* Yet more padding */ +}; +.EE +.in +.IP +Unprivileged users may retrieve only their own quotas; +a privileged user +.RB ( CAP_SYS_ADMIN ) +may retrieve the quotas of any user. +.TP +.BR Q_XGETNEXTQUOTA " (since Linux 4.6)" +.\" commit 8b37524962b9c54423374717786198f5c0820a28 +This operation is the same as +.BR Q_XGETQUOTA , +but it returns (in the +.I fs_disk_quota +structure pointed by +.IR addr ) +quota information for the next ID greater than or equal to +.IR id +that has a quota set. +Note that since +.I fs_disk_quota +already has +.I q_id +field, no separate structure type is needed (in contrast with +.B Q_GETQUOTA +and +.B Q_GETNEXTQUOTA +commands) +.TP +.B Q_XSETQLIM +Set disk quota limits for user +.IR id . +The +.I addr +argument is a pointer to an +.I fs_disk_quota +structure. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.B Q_XGETQSTAT +Returns XFS filesystem-specific quota information in the +.I fs_quota_stat +structure pointed by +.IR addr . +This is useful for finding out how much space is used to store quota +information, and also to get the quota on/off status of a given local XFS +filesystem. +The +.I fs_quota_stat +structure itself is defined as follows: +.IP +.in +4n +.EX +#define FS_QSTAT_VERSION 1 /* fs_quota_stat.qs_version */ + +struct fs_qfilestat { + uint64_t qfs_ino; /* Inode number */ + uint64_t qfs_nblks; /* Number of BBs + 512-byte-blocks */ + uint32_t qfs_nextents; /* Number of extents */ +}; + +struct fs_quota_stat { + int8_t qs_version; /* Version number for + future changes */ + uint16_t qs_flags; /* XFS_QUOTA_{U,P,G}DQ_{ACCT,ENFD} */ + int8_t qs_pad; /* Unused */ + struct fs_qfilestat qs_uquota; /* User quota storage + information */ + struct fs_qfilestat qs_gquota; /* Group quota storage + information */ + uint32_t qs_incoredqs; /* Number of dquots in core */ + int32_t qs_btimelimit; /* Limit for blocks timer */ + int32_t qs_itimelimit; /* Limit for inodes timer */ + int32_t qs_rtbtimelimit;/* Limit for RT + blocks timer */ + uint16_t qs_bwarnlimit; /* Limit for # of warnings */ + uint16_t qs_iwarnlimit; /* Limit for # of warnings */ +}; +.EE +.in +.IP +The +.I id +argument is ignored. +.TP +.B Q_XGETQSTATV +Returns XFS filesystem-specific quota information in the +.I fs_quota_statv +pointed to by +.IR addr . +This version of the command uses a structure with proper versioning support, +along with appropriate layout (all fields are naturally aligned) and +padding to avoiding special compat handling; +it also provides the ability to get statistics regarding +the project quota file. +The +.I fs_quota_statv +structure itself is defined as follows: +.IP +.in +4n +.EX +#define FS_QSTATV_VERSION1 1 /* fs_quota_statv.qs_version */ + +struct fs_qfilestatv { + uint64_t qfs_ino; /* Inode number */ + uint64_t qfs_nblks; /* Number of BBs + 512-byte-blocks */ + uint32_t qfs_nextents; /* Number of extents */ + uint32_t qfs_pad; /* Pad for 8-byte alignment */ +}; + +struct fs_quota_statv { + int8_t qs_version; /* Version for future + changes */ + uint8_t qs_pad1; /* Pad for 16-bit alignment */ + uint16_t qs_flags; /* XFS_QUOTA_.* flags */ + uint32_t qs_incoredqs; /* Number of dquots incore */ + struct fs_qfilestatv qs_uquota; /* User quota + information */ + struct fs_qfilestatv qs_gquota; /* Group quota + information */ + struct fs_qfilestatv qs_pquota; /* Project quota + information */ + int32_t qs_btimelimit; /* Limit for blocks timer */ + int32_t qs_itimelimit; /* Limit for inodes timer */ + int32_t qs_rtbtimelimit; /* Limit for RT blocks + timer */ + uint16_t qs_bwarnlimit; /* Limit for # of warnings */ + uint16_t qs_iwarnlimit; /* Limit for # of warnings */ + uint64_t qs_pad2[8]; /* For future proofing */ +}; +.EE +.in +.IP +The +.I qs_version +field of the structure should be filled with the version of the structure +supported by the callee (for now, only +.I FS_QSTAT_VERSION1 +is supported). +The kernel will fill the structure in accordance with +version provided. +The +.I id +argument is ignored. +.TP +.B Q_XQUOTARM +Free the disk space taken by disk quotas. The +.I addr +argument should be a pointer to an +.I "unsigned int" +value containing flags (the same as in +.I d_flags +field of +.I fs_disk_quota +structure) which identify what types of quota should be removed +(note that the quota type passed in the +.I cmd +argument is ignored, but should remain valid in order to pass preliminary +quotactl syscall handler checks). +.IP +Quotas must have already been turned off. +The +.I id +argument is ignored. +.TP +.BR Q_XQUOTASYNC " (since Linux 2.6.15; no-op since Linux 3.4)" +.\" Added in commit ee34807a65aa0c5911dc27682863afca780a003e +This command was an XFS quota equivalent to +.IR Q_SYNC , +but it is no-op since Linux 3.4, +.\" 4b217ed9e30f94b6e8e5e262020ef0ceab6113af +as +.BR sync (1) +writes quota information to disk now +(in addition to the other filesystem metadata that it writes out). +The +.IR special ", " id " and " addr +arguments are ignored. +.SH RETURN VALUE +.PP +On success, +.BR quotactl () +returns 0; on error \-1 +is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.I cmd +is +.BR Q_QUOTAON , +and the quota file pointed to by +.I addr +exists, but is not a regular file or +is not on the filesystem pointed to by +.IR special . +.TP +.B EBUSY +.I cmd +is +.BR Q_QUOTAON , +but another +.B Q_QUOTAON +had already been performed. +.TP +.B EFAULT +.I addr +or +.I special +is invalid. +.TP +.B EINVAL +.I cmd +or +.I type +is invalid. +.TP +.B EINVAL +.I cmd +is +.BR Q_QUOTAON , +but the specified quota file is corrupted. +.TP +.B ENOENT +The file specified by +.I special +or +.I addr +does not exist. +.TP +.B ENOSYS +The kernel has not been compiled with the +.B CONFIG_QUOTA +option. +.TP +.B ENOTBLK +.I special +is not a block device. +.TP +.B EPERM +The caller lacked the required privilege +.RB ( CAP_SYS_ADMIN ) +for the specified operation. +.TP +.B ERANGE +.I cmd +is +.BR Q_SETQUOTA , +but the specified limits are out of the range allowed by the quota format. +.TP +.B ESRCH +No disk quota is found for the indicated user. +Quotas have not been turned on for this filesystem. +.TP +.B ESRCH +.I cmd +is +.BR Q_QUOTAON , +but the specified quota format was not found. +.TP +.B ESRCH +.I cmd +is +.B Q_GETNEXTQUOTA +or +.BR Q_XGETNEXTQUOTA , +but there is no ID greater than or equal to +.IR id +that has an active quota. +.SH NOTES +Instead of +.I +one can use +.IR , +taking into account that there are several naming discrepancies: +.IP \(bu 3 +Quota enabling flags (of format +.BR XFS_QUOTA_[UGP]DQ_{ACCT,ENFD} ) +are defined without a leading "X", as +.BR FS_QUOTA_[UGP]DQ_{ACCT,ENFD} . +.IP \(bu +The same is true for +.B XFS_{USER,GROUP,PROJ}_QUOTA +quota type flags, which are defined as +.BR FS_{USER,GROUP,PROJ}_QUOTA . +.IP \(bu +The +.I dqblk_xfs.h +header file defines its own +.BR XQM_USRQUOTA , +.BR XQM_GRPQUOTA , +and +.B XQM_PRJQUOTA +constants for the available quota types, but their values are the same as for +constants without the +.B XQM_ +prefix. +.SH SEE ALSO +.BR quota (1), +.BR getrlimit (2), +.BR quotacheck (8), +.BR quotaon (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/read.2 b/man2/read.2 new file mode 100644 index 0000000..92ee3fe --- /dev/null +++ b/man2/read.2 @@ -0,0 +1,275 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 00:06:00 1993 by Rik Faith +.\" Modified Wed Jan 17 16:02:32 1996 by Michael Haardt +.\" +.\" Modified Thu Apr 11 19:26:35 1996 by Andries Brouwer +.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer +.\" Modified Fri Jan 31 16:47:33 1997 by Eric S. Raymond +.\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt +.\" +.\" +.TH READ 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +read \- read from a file descriptor +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "ssize_t read(int " fd ", void *" buf ", size_t " count ); +.fi +.SH DESCRIPTION +.BR read () +attempts to read up to +.I count +bytes from file descriptor +.I fd +into the buffer starting at +.IR buf . +.PP +On files that support seeking, +the read operation commences at the file offset, +and the file offset is incremented by the number of bytes read. +If the file offset is at or past the end of file, +no bytes are read, and +.BR read () +returns zero. +.PP +If +.I count +is zero, +.BR read () +.I may +detect the errors described below. +In the absence of any errors, +or if +.BR read () +does not check for errors, a +.BR read () +with a +.I count +of 0 returns zero and has no other effects. +.PP +According to POSIX.1, if +.I count +is greater than +.BR SSIZE_MAX , +the result is implementation-defined; +see NOTES for the upper limit on Linux. +.SH RETURN VALUE +On success, the number of bytes read is returned (zero indicates end of +file), and the file position is advanced by this number. +It is not an error if this number is smaller than the number of bytes +requested; this may happen for example because fewer bytes are actually +available right now (maybe because we were close to end-of-file, or +because we are reading from a pipe, or from a terminal), or because +.BR read () +was interrupted by a signal. +See also NOTES. +.PP +On error, \-1 is returned, and +.I errno +is set appropriately. +In this case, it is left unspecified whether +the file position (if any) changes. +.SH ERRORS +.TP +.B EAGAIN +The file descriptor +.I fd +refers to a file other than a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +and the read would block. +See +.BR open (2) +for further details on the +.BR O_NONBLOCK +flag. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The file descriptor +.I fd +refers to a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +and the read would block. +POSIX.1-2001 allows either error to be returned for this case, +and does not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for reading. +.TP +.B EFAULT +.I buf +is outside your accessible address space. +.TP +.B EINTR +The call was interrupted by a signal before any data was read; see +.BR signal (7). +.TP +.B EINVAL +.I fd +is attached to an object which is unsuitable for reading; +or the file was opened with the +.B O_DIRECT +flag, and either the address specified in +.IR buf , +the value specified in +.IR count , +or the file offset is not suitably aligned. +.TP +.B EINVAL +.I fd +was created via a call to +.BR timerfd_create (2) +and the wrong size buffer was given to +.BR read (); +see +.BR timerfd_create (2) +for further information. +.TP +.B EIO +I/O error. +This will happen for example when the process is in a +background process group, tries to read from its controlling terminal, +and either it is ignoring or blocking +.B SIGTTIN +or its process group +is orphaned. +It may also occur when there is a low-level I/O error +while reading from a disk or tape. +A further possible cause of +.B EIO +on networked filesystems is when an advisory lock had been taken +out on the file descriptor and this lock has been lost. +See the +.I "Lost locks" +section of +.BR fcntl (2) +for further details. +.TP +.B EISDIR +.I fd +refers to a directory. +.PP +Other errors may occur, depending on the object connected to +.IR fd . +.SH CONFORMING TO +SVr4, 4.3BSD, POSIX.1-2001. +.SH NOTES +The types +.I size_t +and +.I ssize_t +are, respectively, +unsigned and signed integer data types specified by POSIX.1. +.PP +On Linux, +.BR read () +(and similar system calls) will transfer at most +0x7ffff000 (2,147,479,552) bytes, +returning the number of bytes actually transferred. +.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 +(This is true on both 32-bit and 64-bit systems.) +.PP +On NFS filesystems, reading small amounts of data will update the +timestamp only the first time, subsequent calls may not do so. +This is caused +by client side attribute caching, because most if not all NFS clients +leave +.I st_atime +(last file access time) +updates to the server, and client side reads satisfied from the +client's cache will not cause +.I st_atime +updates on the server as there are no +server-side reads. +UNIX semantics can be obtained by disabling client-side attribute caching, +but in most situations this will substantially +increase server load and decrease performance. +.SH BUGS +According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 +("Thread Interactions with Regular File Operations"): +.PP +.RS 4 +All of the following functions shall be atomic with respect to +each other in the effects specified in POSIX.1-2008 when they +operate on regular files or symbolic links: ... +.RE +.PP +Among the APIs subsequently listed are +.BR read () +and +.BR readv (2). +And among the effects that should be atomic across threads (and processes) +are updates of the file offset. +However, on Linux before version 3.14, +this was not the case: if two processes that share +an open file description (see +.BR open (2)) +perform a +.BR read () +(or +.BR readv (2)) +at the same time, then the I/O operations were not atomic +with respect updating the file offset, +with the result that the reads in the two processes +might (incorrectly) overlap in the blocks of data that they obtained. +This problem was fixed in Linux 3.14. +.\" http://thread.gmane.org/gmane.linux.kernel/1649458 +.\" From: Michael Kerrisk (man-pages gmail.com> +.\" Subject: Update of file offset on write() etc. is non-atomic with I/O +.\" Date: 2014-02-17 15:41:37 GMT +.\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems +.\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4 +.\" Author: Linus Torvalds +.\" Date: Mon Mar 3 09:36:58 2014 -0800 +.\" +.\" vfs: atomic f_pos accesses as per POSIX +.SH SEE ALSO +.BR close (2), +.BR fcntl (2), +.BR ioctl (2), +.BR lseek (2), +.BR open (2), +.BR pread (2), +.BR readdir (2), +.BR readlink (2), +.BR readv (2), +.BR select (2), +.BR write (2), +.BR fread (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/readahead.2 b/man2/readahead.2 new file mode 100644 index 0000000..e79cdcb --- /dev/null +++ b/man2/readahead.2 @@ -0,0 +1,121 @@ +.\" This manpage is Copyright (C) 2004, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2004-05-40 Created by Michael Kerrisk +.\" 2004-10-05 aeb, minor correction +.\" +.TH READAHEAD 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +readahead \- initiate file readahead into page cache +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "ssize_t readahead(int " fd ", off64_t " offset ", size_t " count ); +.fi +.SH DESCRIPTION +.BR readahead () +initiates readahead on a file so that subsequent reads from that file will +be satisfied from the cache, and not block on disk I/O +(assuming the readahead was initiated early enough and that other activity +on the system did not in the meantime flush pages from the cache). +.PP +The +.I fd +argument is a file descriptor identifying the file which is +to be read. +The +.I offset +argument specifies the starting point from which data is to be read +and +.I count +specifies the number of bytes to be read. +I/O is performed in whole pages, so that +.I offset +is effectively rounded down to a page boundary +and bytes are read up to the next page boundary greater than or +equal to +.IR "(offset+count)" . +.BR readahead () +does not read beyond the end of the file. +The file offset of the open file description referred to by +.I fd +is left unchanged. +.SH RETURN VALUE +On success, +.BR readahead () +returns 0; on failure, \-1 is returned, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for reading. +.TP +.B EINVAL +.I fd +does not refer to a file type to which +.BR readahead () +can be applied. +.SH VERSIONS +The +.BR readahead () +system call appeared in Linux 2.4.13; +glibc support has been provided since version 2.3. +.SH CONFORMING TO +The +.BR readahead () +system call is Linux-specific, and its use should be avoided +in portable applications. +.SH NOTES +On some 32-bit architectures, +the calling signature for this system call differs, +for the reasons described in +.BR syscall (2). +.SH BUGS +.BR readahead () +attempts to schedule the reads in the background and return immediately. +However, it may block while it reads the filesystem metadata needed +to locate the requested blocks. +This occurs frequently with ext[234] on large files +using indirect blocks instead of extents, +giving the appearance that the call blocks until the requested data has +been read. +.SH SEE ALSO +.BR lseek (2), +.BR madvise (2), +.BR mmap (2), +.BR posix_fadvise (2), +.BR read (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/readdir.2 b/man2/readdir.2 new file mode 100644 index 0000000..3a232a1 --- /dev/null +++ b/man2/readdir.2 @@ -0,0 +1,138 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" Modified 22 July 1995 by Michael Chastain : +.\" In 1.3.X, returns only one entry each time; return value is different. +.\" Modified 2004-12-01, mtk, fixed headers listed in SYNOPSIS +.\" +.TH READDIR 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +readdir \- read directory entry +.SH SYNOPSIS +.nf +.PP +.BI "int readdir(unsigned int " fd ", struct old_linux_dirent *" dirp "," +.BI " unsigned int " count ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +This is not the function you are interested in. +Look at +.BR readdir (3) +for the POSIX conforming C library interface. +This page documents the bare kernel system call interface, +which is superseded by +.BR getdents (2). +.PP +.BR readdir () +reads one +.I old_linux_dirent +structure from the directory +referred to by the file descriptor +.I fd +into the buffer pointed to by +.IR dirp . +The argument +.I count +is ignored; at most one +.I old_linux_dirent +structure is read. +.PP +The +.I old_linux_dirent +structure is declared as follows: +.PP +.in +4n +.EX +struct old_linux_dirent { + long d_ino; /* inode number */ + off_t d_off; /* offset to this \fIold_linux_dirent\fP */ + unsigned short d_reclen; /* length of this \fId_name\fP */ + char d_name[NAME_MAX+1]; /* filename (null-terminated) */ +} +.EE +.in +.PP +.I d_ino +is an inode number. +.I d_off +is the distance from the start of the directory to this +.IR old_linux_dirent . +.I d_reclen +is the size of +.IR d_name , +not counting the terminating null byte (\(aq\\0\(aq). +.I d_name +is a null-terminated filename. +.SH RETURN VALUE +On success, 1 is returned. +On end of directory, 0 is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +Invalid file descriptor +.IR fd . +.TP +.B EFAULT +Argument points outside the calling process's address space. +.TP +.B EINVAL +Result buffer is too small. +.TP +.B ENOENT +No such directory. +.TP +.B ENOTDIR +File descriptor does not refer to a directory. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +You will need to define the +.I old_linux_dirent +structure yourself. +However, probably you should use +.BR readdir (3) +instead. +.PP +This system call does not exist on x86-64. +.SH SEE ALSO +.BR getdents (2), +.BR readdir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/readlink.2 b/man2/readlink.2 new file mode 100644 index 0000000..8a72a37 --- /dev/null +++ b/man2/readlink.2 @@ -0,0 +1,366 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" And Copyright (C) 2011 Guillem Jover +.\" And Copyright (C) 2006, 2014 Michael Kerrisk +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)readlink.2 6.8 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Jul 9 23:55:17 1996 by aeb +.\" Modified Fri Jan 24 00:26:00 1997 by aeb +.\" 2011-09-20, Guillem Jover : +.\" Added text on dynamically allocating buffer + example program +.\" +.TH READLINK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +readlink, readlinkat \- read value of a symbolic link +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "ssize_t readlink(const char *" pathname ", char *" buf \ +", size_t " bufsiz ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "ssize_t readlinkat(int " dirfd ", const char *" pathname , +.BI " char *" buf ", size_t " bufsiz ); +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR readlink (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 || _POSIX_C_SOURCE\ >=\ 200112L +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.PP +.BR readlinkat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad b +.PD +.SH DESCRIPTION +.BR readlink () +places the contents of the symbolic link +.I pathname +in the buffer +.IR buf , +which has size +.IR bufsiz . +.BR readlink () +does not append a null byte to +.IR buf . +It will (silently) truncate the contents (to a length of +.I bufsiz +characters), in case the buffer is too small to hold all of the contents. +.SS readlinkat() +The +.BR readlinkat () +system call operates in exactly the same way as +.BR readlink (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR readlink () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR readlink ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +Since Linux 2.6.39, +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +.I pathname +can be an empty string, +in which case the call operates on the symbolic link referred to by +.IR dirfd +(which should have been obtained using +.BR open (2) +with the +.B O_PATH +and +.B O_NOFOLLOW +flags). +.PP +See +.BR openat (2) +for an explanation of the need for +.BR readlinkat (). +.SH RETURN VALUE +On success, these calls return the number of bytes placed in +.IR buf . +(If the returned value equals +.IR bufsiz , +then truncation may have occurred.) +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EFAULT +.I buf +extends outside the process's allocated address space. +.TP +.B EINVAL +.I bufsiz +is not positive. +.\" At the glibc level, bufsiz is unsigned, so this error can only occur +.\" if bufsiz==0. However, the in the kernel syscall, bufsiz is signed, +.\" and this error can also occur if bufsiz < 0. +.\" See: http://thread.gmane.org/gmane.linux.man/380 +.\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall? +.TP +.B EINVAL +The named file (i.e., the final filename component of +.IR pathname ) +is not a symbolic link. +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A pathname, or a component of a pathname, was too long. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.PP +The following additional errors can occur for +.BR readlinkat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR readlinkat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR readlink (): +4.4BSD +.RB ( readlink () +first appeared in 4.2BSD), +POSIX.1-2001, POSIX.1-2008. +.PP +.BR readlinkat (): +POSIX.1-2008. +.SH NOTES +In versions of glibc up to and including glibc 2.4, the return type of +.BR readlink () +was declared as +.IR int . +Nowadays, the return type is declared as +.IR ssize_t , +as (newly) required in POSIX.1-2001. +.PP +Using a statically sized buffer might not provide enough room for the +symbolic link contents. +The required size for the buffer can be obtained from the +.I stat.st_size +value returned by a call to +.BR lstat (2) +on the link. +However, the number of bytes written by +.BR readlink () +and +.BR readlinkat () +should be checked to make sure that the size of the +symbolic link did not increase between the calls. +Dynamically allocating the buffer for +.BR readlink () +and +.BR readlinkat () +also addresses a common portability problem when using +.I PATH_MAX +for the buffer size, +as this constant is not guaranteed to be defined per POSIX +if the system does not have such limit. +.SS Glibc notes +On older kernels where +.BR readlinkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR readlink (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.IR /proc/self/fd +that corresponds to the +.IR dirfd +argument. +.SH EXAMPLE +The following program allocates the buffer needed by +.BR readlink () +dynamically from the information provided by +.BR lstat (2), +falling back to a buffer of size +.BR PATH_MAX +in cases where +.BR lstat (2) +reports a size of zero. +.PP +.EX +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct stat sb; + char *buf; + ssize_t nbytes, bufsiz; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + if (lstat(argv[1], &sb) == \-1) { + perror("lstat"); + exit(EXIT_FAILURE); + } + + /* Add one to the link size, so that we can determine whether + the buffer returned by readlink() was truncated. */ + + bufsiz = sb.st_size + 1; + + /* Some magic symlinks under (for example) /proc and /sys + report \(aqst_size\(aq as zero. In that case, take PATH_MAX as + a "good enough" estimate. */ + + if (sb.st_size == 0) + bufsiz = PATH_MAX; + + buf = malloc(bufsiz); + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + + nbytes = readlink(argv[1], buf, bufsiz); + if (nbytes == \-1) { + perror("readlink"); + exit(EXIT_FAILURE); + } + + printf("\(aq%s\(aq points to \(aq%.*s\(aq\\n", argv[1], (int) nbytes, buf); + + /* If the return value was equal to the buffer size, then the + the link target was larger than expected (perhaps because the + target was changed between the call to lstat() and the call to + readlink()). Warn the user that the returned target may have + been truncated. */ + + if (nbytes == bufsiz) + printf("(Returned buffer may have been truncated)\\n"); + + free(buf); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR readlink (1), +.BR lstat (2), +.BR stat (2), +.BR symlink (2), +.BR realpath (3), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/readlinkat.2 b/man2/readlinkat.2 new file mode 100644 index 0000000..b29d1b5 --- /dev/null +++ b/man2/readlinkat.2 @@ -0,0 +1 @@ +.so man2/readlink.2 diff --git a/man2/readv.2 b/man2/readv.2 new file mode 100644 index 0000000..92d5085 --- /dev/null +++ b/man2/readv.2 @@ -0,0 +1,425 @@ +.\" Copyright (C) 2007, 2010 Michael Kerrisk +.\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Merged readv.[23], 2002-10-17, aeb +.\" 2007-04-30 mtk, A fairly major rewrite to fix errors and +.\" add more details. +.\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() +.\" +.TH READV 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into multiple buffers +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); +.PP +.BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); +.PP +.BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ); +.PP +.BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ); +.PP +.BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ", int " flags ); +.PP +.BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ", int " flags ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR preadv (), +.BR pwritev (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The +.BR readv () +system call reads +.I iovcnt +buffers from the file associated with the file descriptor +.I fd +into the buffers described by +.I iov +("scatter input"). +.PP +The +.BR writev () +system call writes +.I iovcnt +buffers of data described by +.I iov +to the file associated with the file descriptor +.I fd +("gather output"). +.PP +The pointer +.I iov +points to an array of +.I iovec +structures, +defined in +.I +as: +.PP +.in +4n +.EX +struct iovec { + void *iov_base; /* Starting address */ + size_t iov_len; /* Number of bytes to transfer */ +}; +.EE +.in +.PP +The +.BR readv () +system call works just like +.BR read (2) +except that multiple buffers are filled. +.PP +The +.BR writev () +system call works just like +.BR write (2) +except that multiple buffers are written out. +.PP +Buffers are processed in array order. +This means that +.BR readv () +completely fills +.IR iov [0] +before proceeding to +.IR iov [1], +and so on. +(If there is insufficient data, then not all buffers pointed to by +.I iov +may be filled.) +Similarly, +.BR writev () +writes out the entire contents of +.IR iov [0] +before proceeding to +.IR iov [1], +and so on. +.PP +The data transfers performed by +.BR readv () +and +.BR writev () +are atomic: the data written by +.\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596 +.BR writev () +is written as a single block that is not intermingled with output +from writes in other processes (but see +.BR pipe (7) +for an exception); +analogously, +.BR readv () +is guaranteed to read a contiguous block of data from the file, +regardless of read operations performed in other threads or processes +that have file descriptors referring to the same open file description +(see +.BR open (2)). +.SS preadv() and pwritev() +The +.BR preadv () +system call combines the functionality of +.BR readv () +and +.BR pread (2). +It performs the same task as +.BR readv (), +but adds a fourth argument, +.IR offset , +which specifies the file offset at which the input operation +is to be performed. +.PP +The +.BR pwritev () +system call combines the functionality of +.BR writev () +and +.BR pwrite (2). +It performs the same task as +.BR writev (), +but adds a fourth argument, +.IR offset , +which specifies the file offset at which the output operation +is to be performed. +.PP +The file offset is not changed by these system calls. +The file referred to by +.I fd +must be capable of seeking. +.SS preadv2() and pwritev2() +.PP +These system calls are similar to +.BR preadv () +and +.BR pwritev () +calls, but add a fifth argument, +.IR flags , +which modifies the behavior on a per-call basis. +.PP +Unlike +.BR preadv () +and +.BR pwritev (), +if the +.I offset +argument is \-1, then the current file offset is used and updated. +.PP +The +.I flags +argument contains a bitwise OR of zero or more of the following flags: +.TP +.BR RWF_DSYNC " (since Linux 4.7)" +.\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 +Provide a per-write equivalent of the +.B O_DSYNC +.BR open (2) +flag. +This flag is meaningful only for +.BR pwritev2 (), +and its effect applies only to the data range written by the system call. +.TP +.BR RWF_HIPRI " (since Linux 4.6)" +High priority read/write. +Allows block-based filesystems to use polling of the device, +which provides lower latency, but may use additional resources. +(Currently, this feature is usable only on a file descriptor opened using the +.BR O_DIRECT +flag.) +.TP +.BR RWF_SYNC " (since Linux 4.7)" +.\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 +Provide a per-write equivalent of the +.B O_SYNC +.BR open (2) +flag. +This flag is meaningful only for +.BR pwritev2 (), +and its effect applies only to the data range written by the system call. +.TP +.BR RWF_NOWAIT " (since Linux 4.14)" +.\" commit 3239d834847627b6634a4139cf1dc58f6f137a46 +.\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571 +Do not wait for data which is not immediately available. +If this flag is specified, the +.BR preadv2 () +system call will return instantly if it would have to read data from +the backing storage or wait for a lock. +If some data was successfully read, it will return the number of bytes read. +If no bytes were read, it will return -1 and set +.IR errno +to +.BR EAGAIN . +Currently, this flag is meaningful only for +.BR preadv2 (). +.SH RETURN VALUE +On success, +.BR readv (), +.BR preadv () +and +.BR preadv2 () +return the number of bytes read; +.BR writev (), +.BR pwritev () +and +.BR pwritev2 () +return the number of bytes written. +.PP +Note that it is not an error for a successful call to transfer fewer bytes +than requested (see +.BR read (2) +and +.BR write (2)). +.PP +On error, \-1 is returned, and \fIerrno\fP is set appropriately. +.SH ERRORS +The errors are as given for +.BR read (2) +and +.BR write (2). +Furthermore, +.BR preadv (), +.BR preadv2 (), +.BR pwritev (), +and +.BR pwritev2 () +can also fail for the same reasons as +.BR lseek (2). +Additionally, the following errors are defined: +.TP +.B EINVAL +The sum of the +.I iov_len +values overflows an +.I ssize_t +value. +.TP +.B EINVAL +The vector count, +.IR iovcnt , +is less than zero or greater than the permitted maximum. +.TP +.B EINVAL +An unknown flag is specified in \fIflags\fP. +.SH VERSIONS +.BR preadv () +and +.BR pwritev () +first appeared in Linux 2.6.30; library support was added in glibc 2.10. +.PP +.BR preadv2 () +and +.BR pwritev2 () +first appeared in Linux 4.6. +Library support was added in glibc 2.26. +.SH CONFORMING TO +.BR readv (), +.BR writev (): +POSIX.1-2001, POSIX.1-2008, +4.4BSD (these system calls first appeared in 4.2BSD). +.\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, +.\" and \fIint\fP as the return type. +.\" The readv/writev system calls were buggy before Linux 1.3.40. +.\" (Says release.libc.) +.PP +.BR preadv (), +.BR pwritev (): +nonstandard, but present also on the modern BSDs. +.PP +.BR preadv2 (), +.BR pwritev2 (): +nonstandard Linux extension. +.SH NOTES +POSIX.1 allows an implementation to place a limit on +the number of items that can be passed in +.IR iov . +An implementation can advertise its limit by defining +.B IOV_MAX +in +.I +or at run time via the return value from +.IR sysconf(_SC_IOV_MAX) . +On modern Linux systems, the limit is 1024. +Back in Linux 2.0 days, this limit was 16. +.\" +.\" +.SS C library/kernel differences +The raw +.BR preadv () +and +.BR pwritev () +system calls have call signatures that differ slightly from that of the +corresponding GNU C library wrapper functions shown in the SYNOPSIS. +The final argument, +.IR offset , +is unpacked by the wrapper functions into two arguments in the system calls: +.PP +.BI " unsigned long " pos_l ", unsigned long " pos +.PP +These arguments contain, respectively, the low order and high order 32 bits of +.IR offset . +.SS Historical C library/kernel differences +To deal with the fact that +.B IOV_MAX +was so low on early versions of Linux, +the glibc wrapper functions for +.BR readv () +and +.BR writev () +did some extra work if they detected that the underlying kernel +system call failed because this limit was exceeded. +In the case of +.BR readv (), +the wrapper function allocated a temporary buffer large enough +for all of the items specified by +.IR iov , +passed that buffer in a call to +.BR read (2), +copied data from the buffer to the locations specified by the +.I iov_base +fields of the elements of +.IR iov , +and then freed the buffer. +The wrapper function for +.BR writev () +performed the analogous task using a temporary buffer and a call to +.BR write (2). +.PP +The need for this extra effort in the glibc wrapper functions +went away with Linux 2.2 and later. +However, glibc continued to provide this behavior until version 2.10. +Starting with glibc version 2.9, +the wrapper functions provide this behavior only if the library detects +that the system is running a Linux kernel older than version 2.6.18 +(an arbitrarily selected kernel version). +And since glibc 2.20 +(which requires a minimum Linux kernel version of 2.6.32), +the glibc wrapper functions always just directly invoke the system calls. +.SH EXAMPLE +The following code sample demonstrates the use of +.BR writev (): +.PP +.in +4n +.EX +char *str0 = "hello "; +char *str1 = "world\\n"; +struct iovec iov[2]; +ssize_t nwritten; + +iov[0].iov_base = str0; +iov[0].iov_len = strlen(str0); +iov[1].iov_base = str1; +iov[1].iov_len = strlen(str1); + +nwritten = writev(STDOUT_FILENO, iov, 2); +.EE +.in +.SH SEE ALSO +.BR pread (2), +.BR read (2), +.BR write (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/reboot.2 b/man2/reboot.2 new file mode 100644 index 0000000..3fe2799 --- /dev/null +++ b/man2/reboot.2 @@ -0,0 +1,262 @@ +.\" Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl), 24 September 1998 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH REBOOT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +reboot \- reboot or enable/disable Ctrl-Alt-Del +.SH SYNOPSIS +/* Since kernel version 2.1.30 there are symbolic names LINUX_REBOOT_* + for the constants and a fourth argument to the call: */ +.PP +.B #include +.br +.B #include +.PP +.BI "int reboot(int " magic ", int " magic2 ", int " cmd ", void *" arg ); + +/* Under glibc and most alternative libc's (including uclibc, dietlibc, + musl and a few others), some of the constants involved have gotten + symbolic names RB_*, and the library call is a 1-argument + wrapper around the system call: */ +.PP +.B #include +.br +.B #include +.PP +.BI "int reboot(int " cmd ); +.SH DESCRIPTION +The +.BR reboot () +call reboots the system, or enables/disables the reboot keystroke +(abbreviated CAD, since the default is Ctrl-Alt-Delete; +it can be changed using +.BR loadkeys (1)). +.PP +This system call fail (with the error +.BR EINVAL ) +unless +.I magic +equals +.B LINUX_REBOOT_MAGIC1 +(that is, 0xfee1dead) and +.I magic2 +equals +.B LINUX_REBOOT_MAGIC2 +(that is, 672274793). +However, since 2.1.17 also +.B LINUX_REBOOT_MAGIC2A +(that is, 85072278) +and since 2.1.97 also +.B LINUX_REBOOT_MAGIC2B +(that is, 369367448) +and since 2.5.71 also +.B LINUX_REBOOT_MAGIC2C +(that is, 537993216) +are permitted as values for +.IR magic2 . +(The hexadecimal values of these constants are meaningful.) +.PP +The +.I cmd +argument can have the following values: +.TP +.B LINUX_REBOOT_CMD_CAD_OFF +.RB ( RB_DISABLE_CAD , +0). +CAD is disabled. +This means that the CAD keystroke will cause a +.B SIGINT +signal to be +sent to init (process 1), whereupon this process may decide upon a +proper action (maybe: kill all processes, sync, reboot). +.TP +.B LINUX_REBOOT_CMD_CAD_ON +.RB ( RB_ENABLE_CAD , +0x89abcdef). +CAD is enabled. +This means that the CAD keystroke will immediately cause +the action associated with +.BR LINUX_REBOOT_CMD_RESTART . +.TP +.B LINUX_REBOOT_CMD_HALT +.RB ( RB_HALT_SYSTEM , +0xcdef0123; since Linux 1.1.76). +The message "System halted." is printed, and the system is halted. +Control is given to the ROM monitor, if there is one. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.BR LINUX_REBOOT_CMD_KEXEC +.RB ( RB_KEXEC , +0x45584543, since Linux 2.6.13). +Execute a kernel that has been loaded earlier with +.BR kexec_load (2). +This option is available only if the kernel was configured with +.BR CONFIG_KEXEC . +.TP +.B LINUX_REBOOT_CMD_POWER_OFF +.RB ( RB_POWER_OFF , +0x4321fedc; since Linux 2.1.30). +The message "Power down." is printed, the system is stopped, +and all power is removed from the system, if possible. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_RESTART +.RB ( RB_AUTOBOOT , +0x1234567). +The message "Restarting system." is printed, and a default +restart is performed immediately. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_RESTART2 +(0xa1b2c3d4; since Linux 2.1.30). +The message "Restarting system with command \(aq%s\(aq" is printed, +and a restart (using the command string given in +.IR arg ) +is performed immediately. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.BR LINUX_REBOOT_CMD_SW_SUSPEND +.RB ( RB_SW_SUSPEND , +0xd000fce1; since Linux 2.5.18). +The system is suspended (hibernated) to disk. +This option is available only if the kernel was configured with +.BR CONFIG_HIBERNATION . +.PP +Only the superuser may call +.BR reboot (). +.PP +The precise effect of the above actions depends on the architecture. +For the i386 architecture, the additional argument does not do +anything at present (2.1.122), but the type of reboot can be +determined by kernel command-line arguments ("reboot=...") to be +either warm or cold, and either hard or through the BIOS. +.\" +.SS Behavior inside PID namespaces +.\" commit cf3f89214ef6a33fad60856bc5ffd7bb2fc4709b +.\" see also commit 923c7538236564c46ee80c253a416705321f13e3 +Since Linux 3.4, +if +.BR reboot () +is called +from a PID namespace other than the initial PID namespace +with one of the +.I cmd +values listed below, +it performs a "reboot" of that namespace: +the "init" process of the PID namespace is immediately terminated, +with the effects described in +.BR pid_namespaces (7). +.PP +The values that can be supplied in +.I cmd +when calling +.BR reboot () +in this case are as follows: +.TP +.BR LINUX_REBOOT_CMD_RESTART ", " LINUX_REBOOT_CMD_RESTART2 +The "init" process is terminated, +and +.BR wait (2) +in the parent process reports that the child was killed with a +.B SIGHUP +signal. +.TP +.BR LINUX_REBOOT_CMD_POWER_OFF ", " LINUX_REBOOT_CMD_HALT +The "init" process is terminated, +and +.BR wait (2) +in the parent process reports that the child was killed with a +.B SIGINT +signal. +.PP +For the other +.I cmd +values, +.BR reboot () +returns \-1 and +.I errno +is set to +.BR EINVAL . +.SH RETURN VALUE +For the values of +.I cmd +that stop or restart the system, +a successful call to +.BR reboot () +does not return. +For the other +.I cmd +values, zero is returned on success. +In all cases, \-1 is returned on failure, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Problem with getting user-space data under +.BR LINUX_REBOOT_CMD_RESTART2 . +.TP +.B EINVAL +Bad magic numbers or \fIcmd\fP. +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR reboot (); +the caller must have the +.B CAP_SYS_BOOT +inside its user namespace. +.SH CONFORMING TO +.BR reboot () +is Linux-specific, +and should not be used in programs intended to be portable. +.SH SEE ALSO +.BR systemctl (1), +.BR systemd (1), +.BR kexec_load (2), +.BR sync (2), +.BR bootparam (7), +.BR capabilities (7), +.BR ctrlaltdel (8), +.BR halt (8), +.BR shutdown (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/recv.2 b/man2/recv.2 new file mode 100644 index 0000000..c6d4c86 --- /dev/null +++ b/man2/recv.2 @@ -0,0 +1,577 @@ +.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $ +.\" +.\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith +.\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond +.\" Modified 1998,1999 by Andi Kleen +.\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin +.\" +.TH RECV 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +recv, recvfrom, recvmsg \- receive a message from a socket +.SH SYNOPSIS +.\" .B #include +.\" .br +.nf +.B #include +.br +.B #include +.PP +.BI "ssize_t recv(int " sockfd ", void *" buf ", size_t " len ", int " flags ); +.PP +.BI "ssize_t recvfrom(int " sockfd ", void *" buf ", size_t " len ", int " flags , +.BI " struct sockaddr *" src_addr ", socklen_t *" addrlen ); +.PP +.BI "ssize_t recvmsg(int " sockfd ", struct msghdr *" msg ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR recv (), +.BR recvfrom (), +and +.BR recvmsg () +calls are used to receive messages from a socket. +They may be used +to receive data on both connectionless and connection-oriented sockets. +This page first describes common features of all three system calls, +and then describes the differences between the calls. +.PP +The only difference between +.BR recv () +and +.BR read (2) +is the presence of +.IR flags . +With a zero +.I flags +argument, +.BR recv () +is generally equivalent to +.BR read (2) +(but see NOTES). +Also, the following call +.PP + recv(sockfd, buf, len, flags); +.PP +is equivalent to +.PP + recvfrom(sockfd, buf, len, flags, NULL, NULL); +.PP +All three calls return the length of the message on successful +completion. +If a message is too long to fit in the supplied buffer, excess +bytes may be discarded depending on the type of socket the message is +received from. +.PP +If no messages are available at the socket, the receive calls wait for a +message to arrive, unless the socket is nonblocking (see +.BR fcntl (2)), +in which case the value \-1 is returned and the external variable +.I errno +is set to +.BR EAGAIN " or " EWOULDBLOCK . +The receive calls normally return any data available, up to the requested +amount, rather than waiting for receipt of the full amount requested. +.PP +An application can use +.BR select (2), +.BR poll (2), +or +.BR epoll (7) +to determine when more data arrives on a socket. +.SS The flags argument +The +.I flags +argument is formed by ORing one or more of the following values: +.TP +.BR MSG_CMSG_CLOEXEC " (" recvmsg "() only; since Linux 2.6.23)" +Set the close-on-exec flag for the file descriptor received +via a UNIX domain file descriptor using the +.B SCM_RIGHTS +operation (described in +.BR unix (7)). +This flag is useful for the same reasons as the +.B O_CLOEXEC +flag of +.BR open (2). +.TP +.BR MSG_DONTWAIT " (since Linux 2.2)" +Enables nonblocking operation; if the operation would block, +the call fails with the error +.BR EAGAIN " or " EWOULDBLOCK . +This provides similar behavior to setting the +.B O_NONBLOCK +flag (via the +.BR fcntl (2) +.B F_SETFL +operation), but differs in that +.B MSG_DONTWAIT +is a per-call option, whereas +.B O_NONBLOCK +is a setting on the open file description (see +.BR open (2)), +which will affect all threads in the calling process +and as well as other processes that hold file descriptors +referring to the same open file description. +.TP +.BR MSG_ERRQUEUE " (since Linux 2.2)" +This flag +specifies that queued errors should be received from the socket error queue. +The error is passed in +an ancillary message with a type dependent on the protocol (for IPv4 +.BR IP_RECVERR ). +The user should supply a buffer of sufficient size. +See +.BR cmsg (3) +and +.BR ip (7) +for more information. +The payload of the original packet that caused the error +is passed as normal data via +.IR msg_iovec . +The original destination address of the datagram that caused the error +is supplied via +.IR msg_name . +.IP +The error is supplied in a +.I sock_extended_err +structure: +.IP +.in +4n +.EX +#define SO_EE_ORIGIN_NONE 0 +#define SO_EE_ORIGIN_LOCAL 1 +#define SO_EE_ORIGIN_ICMP 2 +#define SO_EE_ORIGIN_ICMP6 3 + +struct sock_extended_err +{ + uint32_t ee_errno; /* error number */ + uint8_t ee_origin; /* where the error originated */ + uint8_t ee_type; /* type */ + uint8_t ee_code; /* code */ + uint8_t ee_pad; /* padding */ + uint32_t ee_info; /* additional information */ + uint32_t ee_data; /* other data */ + /* More data may follow */ +}; + +struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); +.EE +.in +.IP +.I ee_errno +contains the +.I errno +number of the queued error. +.I ee_origin +is the origin code of where the error originated. +The other fields are protocol-specific. +The macro +.B SOCK_EE_OFFENDER +returns a pointer to the address of the network object +where the error originated from given a pointer to the ancillary message. +If this address is not known, the +.I sa_family +member of the +.I sockaddr +contains +.B AF_UNSPEC +and the other fields of the +.I sockaddr +are undefined. +The payload of the packet that caused the error is passed as normal data. +.IP +For local errors, no address is passed (this +can be checked with the +.I cmsg_len +member of the +.IR cmsghdr ). +For error receives, +the +.B MSG_ERRQUEUE +flag is set in the +.IR msghdr . +After an error has been passed, the pending socket error +is regenerated based on the next queued error and will be passed +on the next socket operation. +.TP +.B MSG_OOB +This flag requests receipt of out-of-band data that would not be received +in the normal data stream. +Some protocols place expedited data +at the head of the normal data queue, and thus this flag cannot +be used with such protocols. +.TP +.B MSG_PEEK +This flag causes the receive operation to +return data from the beginning of the +receive queue without removing that data from the queue. +Thus, a +subsequent receive call will return the same data. +.TP +.BR MSG_TRUNC " (since Linux 2.2)" +For raw +.RB ( AF_PACKET ), +Internet datagram (since Linux 2.4.27/2.6.8), +netlink (since Linux 2.6.22), and UNIX datagram +.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f +(since Linux 3.4) sockets: +return the real length of the packet or datagram, +even when it was longer than the passed buffer. +.IP +For use with Internet stream sockets, see +.BR tcp (7). +.TP +.BR MSG_WAITALL " (since Linux 2.2)" +This flag requests that the operation block until the full request is +satisfied. +However, the call may still return less data than requested if +a signal is caught, an error or disconnect occurs, or the next data to be +received is of a different type than that returned. +This flag has no effect for datagram sockets. +.\" +.SS recvfrom() +.BR recvfrom () +places the received message into the buffer +.IR buf . +The caller must specify the size of the buffer in +.IR len . +.PP +If +.I src_addr +is not NULL, +and the underlying protocol provides the source address of the message, +that source address is placed in the buffer pointed to by +.IR src_addr . +.\" (Note: for datagram sockets in both the UNIX and Internet domains, +.\" .I src_addr +.\" is filled in. +.\" .I src_addr +.\" is also filled in for stream sockets in the UNIX domain, but is not +.\" filled in for stream sockets in the Internet domain.) +.\" [The above notes on AF_UNIX and AF_INET sockets apply as at +.\" Kernel 2.4.18. (MTK, 22 Jul 02)] +In this case, +.I addrlen +is a value-result argument. +Before the call, +it should be initialized to the size of the buffer associated with +.IR src_addr . +Upon return, +.I addrlen +is updated to contain the actual size of the source address. +The returned address is truncated if the buffer provided is too small; +in this case, +.I addrlen +will return a value greater than was supplied to the call. +.PP +If the caller is not interested in the source address, +.I src_addr +and +.I addrlen +should be specified as NULL. +.\" +.SS recv() +The +.BR recv () +call is normally used only on a +.I connected +socket (see +.BR connect (2)). +It is equivalent to the call: +.PP + recvfrom(fd, buf, len, flags, NULL, 0); +.\" +.SS recvmsg() +The +.BR recvmsg () +call uses a +.I msghdr +structure to minimize the number of directly supplied arguments. +This structure is defined as follows in +.IR : +.PP +.in +4n +.EX +struct iovec { /* Scatter/gather array items */ + void *iov_base; /* Starting address */ + size_t iov_len; /* Number of bytes to transfer */ +}; + +struct msghdr { + void *msg_name; /* optional address */ + socklen_t msg_namelen; /* size of address */ + struct iovec *msg_iov; /* scatter/gather array */ + size_t msg_iovlen; /* # elements in msg_iov */ + void *msg_control; /* ancillary data, see below */ + size_t msg_controllen; /* ancillary data buffer len */ + int msg_flags; /* flags on received message */ +}; +.EE +.in +.PP +The +.I msg_name +field points to a caller-allocated buffer that is used to +return the source address if the socket is unconnected. +The caller should set +.I msg_namelen +to the size of this buffer before this call; +upon return from a successful call, +.I msg_namelen +will contain the length of the returned address. +If the application does not need to know the source address, +.I msg_name +can be specified as NULL. +.PP +The fields +.I msg_iov +and +.I msg_iovlen +describe scatter-gather locations, as discussed in +.BR readv (2). +.PP +The field +.IR msg_control , +which has length +.IR msg_controllen , +points to a buffer for other protocol control-related messages or +miscellaneous ancillary data. +When +.BR recvmsg () +is called, +.I msg_controllen +should contain the length of the available buffer in +.IR msg_control ; +upon return from a successful call it will contain the length +of the control message sequence. +.PP +The messages are of the form: +.PP +.in +4n +.EX +struct cmsghdr { + size_t cmsg_len; /* Data byte count, including header + (type is socklen_t in POSIX) */ + int cmsg_level; /* Originating protocol */ + int cmsg_type; /* Protocol-specific type */ +/* followed by + unsigned char cmsg_data[]; */ +}; +.EE +.in +.PP +Ancillary data should be accessed only by the macros defined in +.BR cmsg (3). +.PP +As an example, Linux uses this ancillary data mechanism to pass extended +errors, IP options, or file descriptors over UNIX domain sockets. +.PP +The +.I msg_flags +field in the +.I msghdr +is set on return of +.BR recvmsg (). +It can contain several flags: +.TP +.B MSG_EOR +indicates end-of-record; the data returned completed a record (generally +used with sockets of type +.BR SOCK_SEQPACKET ). +.TP +.B MSG_TRUNC +indicates that the trailing portion of a datagram was discarded because the +datagram was larger than the buffer supplied. +.TP +.B MSG_CTRUNC +indicates that some control data were discarded due to lack of space in the +buffer for ancillary data. +.TP +.B MSG_OOB +is returned to indicate that expedited or out-of-band data were received. +.TP +.B MSG_ERRQUEUE +indicates that no data was received but an extended error from the socket +error queue. +.SH RETURN VALUE +These calls return the number of bytes received, or \-1 +if an error occurred. +In the event of an error, +.I errno +is set to indicate the error. +.PP +When a stream socket peer has performed an orderly shutdown, +the return value will be 0 (the traditional "end-of-file" return). +.PP +Datagram sockets in various domains (e.g., the UNIX and Internet domains) +permit zero-length datagrams. +When such a datagram is received, the return value is 0. +.PP +The value 0 may also be returned if the requested number of bytes +to receive from a stream socket was 0. +.SH ERRORS +These are some standard errors generated by the socket layer. +Additional errors +may be generated and returned from the underlying protocol modules; +see their manual pages. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The socket is marked nonblocking and the receive operation +would block, or a receive timeout had been set and the timeout expired +before data was received. +POSIX.1 allows either error to be returned for this case, +and does not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EBADF +The argument +.I sockfd +is an invalid file descriptor. +.TP +.B ECONNREFUSED +A remote host refused to allow the network connection (typically +because it is not running the requested service). +.TP +.B EFAULT +The receive buffer pointer(s) point outside the process's +address space. +.TP +.B EINTR +The receive was interrupted by delivery of a signal before +any data were available; see +.BR signal (7). +.TP +.B EINVAL +Invalid argument passed. +.\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom() +.TP +.B ENOMEM +Could not allocate memory for +.BR recvmsg (). +.TP +.B ENOTCONN +The socket is associated with a connection-oriented protocol +and has not been connected (see +.BR connect (2) +and +.BR accept (2)). +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, +4.4BSD (these interfaces first appeared in 4.2BSD). +.PP +POSIX.1 describes only the +.BR MSG_OOB , +.BR MSG_PEEK , +and +.B MSG_WAITALL +flags. +.SH NOTES +If a zero-length datagram is pending, +.BR read (2) +and +.BR recv () +with a +.I flags +argument of zero provide different behavior. +In this circumstance, +.BR read (2) +has no effect (the datagram remains pending), while +.BR recv () +consumes the pending datagram. +.PP +The +.I socklen_t +type was invented by POSIX. +See also +.BR accept (2). +.PP +According to POSIX.1, +.\" POSIX.1-2001, POSIX.1-2008 +the +.I msg_controllen +field of the +.I msghdr +structure should be typed as +.IR socklen_t , +but glibc currently types it as +.IR size_t . +.\" glibc bug raised 12 Mar 2006 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 +.\" The problem is an underlying kernel issue: the size of the +.\" __kernel_size_t type used to type this field varies +.\" across architectures, but socklen_t is always 32 bits. +.PP +See +.BR recvmmsg (2) +for information about a Linux-specific system call +that can be used to receive multiple datagrams in a single call. +.SH EXAMPLE +An example of the use of +.BR recvfrom () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR fcntl (2), +.BR getsockopt (2), +.BR read (2), +.BR recvmmsg (2), +.BR select (2), +.BR shutdown (2), +.BR socket (2), +.BR cmsg (3), +.BR sockatmark (3), +.BR ip (7), +.BR ipv6 (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/recvfrom.2 b/man2/recvfrom.2 new file mode 100644 index 0000000..13228c3 --- /dev/null +++ b/man2/recvfrom.2 @@ -0,0 +1 @@ +.so man2/recv.2 diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2 new file mode 100644 index 0000000..8ce0d0b --- /dev/null +++ b/man2/recvmmsg.2 @@ -0,0 +1,302 @@ +.\" Copyright (C) 2011 by Andi Kleen +.\" and Copyright (c) 2011 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Syscall added in following commit +.\" commit a2e2725541fad72416326798c2d7fa4dafb7d337 +.\" Author: Arnaldo Carvalho de Melo +.\" Date: Mon Oct 12 23:40:10 2009 -0700 +.\" +.TH RECVMMSG 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +recvmmsg \- receive multiple messages on a socket +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.BI "#include " +.PP +.BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \ +", unsigned int " vlen "," +.BI " int " flags ", struct timespec *" timeout ");" +.fi +.SH DESCRIPTION +The +.BR recvmmsg () +system call is an extension of +.BR recvmsg (2) +that allows the caller to receive multiple messages from a socket +using a single system call. +(This has performance benefits for some applications.) +A further extension over +.BR recvmsg (2) +is support for a timeout on the receive operation. +.PP +The +.I sockfd +argument is the file descriptor of the socket to receive data from. +.PP +The +.I msgvec +argument is a pointer to an array of +.I mmsghdr +structures. +The size of this array is specified in +.IR vlen . +.PP +The +.I mmsghdr +structure is defined in +.I +as: +.PP +.in +4n +.EX +struct mmsghdr { + struct msghdr msg_hdr; /* Message header */ + unsigned int msg_len; /* Number of received bytes for header */ +}; +.EE +.in +.PP +The +.I msg_hdr +field is a +.I msghdr +structure, as described in +.BR recvmsg (2). +The +.I msg_len +field is the number of bytes returned for the message in the entry. +This field has the same value as the return value of a single +.BR recvmsg (2) +on the header. +.PP +The +.I flags +argument contains flags ORed together. +The flags are the same as documented for +.BR recvmsg (2), +with the following addition: +.TP +.BR MSG_WAITFORONE " (since Linux 2.6.34)" +Turns on +.B MSG_DONTWAIT +after the first message has been received. +.PP +The +.I timeout +argument points to a +.I struct timespec +(see +.BR clock_gettime (2)) +defining a timeout (seconds plus nanoseconds) for the receive operation +.RI ( "but see BUGS!" ). +(This interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the blocking interval +may overrun by a small amount.) +If +.I timeout +is NULL, then the operation blocks indefinitely. +.PP +A blocking +.BR recvmmsg () +call blocks until +.I vlen +messages have been received +or until the timeout expires. +A nonblocking call reads as many messages as are available +(up to the limit specified by +.IR vlen ) +and returns immediately. +.PP +On return from +.BR recvmmsg (), +successive elements of +.IR msgvec +are updated to contain information about each received message: +.I msg_len +contains the size of the received message; +the subfields of +.I msg_hdr +are updated as described in +.BR recvmsg (2). +The return value of the call indicates the number of elements of +.I msgvec +that have been updated. +.SH RETURN VALUE +On success, +.BR recvmmsg () +returns the number of messages received in +.IR msgvec ; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Errors are as for +.BR recvmsg (2). +In addition, the following error can occur: +.TP +.B EINVAL +.I timeout +is invalid. +.PP +See also BUGS. +.SH VERSIONS +The +.BR recvmmsg () +system call was added in Linux 2.6.33. +Support in glibc was added in version 2.12. +.SH CONFORMING TO +.BR recvmmsg () +is Linux-specific. +.SH BUGS +The +.I timeout +argument does not work as intended. +.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=75371 +.\" http://thread.gmane.org/gmane.linux.man/5677 +The timeout is checked only after the receipt of each datagram, +so that if up to +.I vlen\-1 +datagrams are received before the timeout expires, +but then no further datagrams are received, the call will block forever. +.PP +If an error occurs after at least one message has been received, +the call succeeds, and returns the number of messages received. +The error code is expected to be returned on a subsequent call to +.BR recvmmsq (). +In the current implementation, however, the error code can be overwritten +in the meantime by an unrelated network event on a socket, +for example an incoming ICMP packet. +.SH EXAMPLE +.PP +The following program uses +.BR recvmmsg () +to receive multiple messages on a socket and stores +them in multiple buffers. +The call returns if all buffers are filled or if the +timeout specified has expired. +.PP +The following snippet periodically generates UDP datagrams +containing a random number: +.PP +.in +4n +.EX +.RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234; " +.B " sleep 0.25; done" +.EE +.in +.PP +These datagrams are read by the example application, which +can give the following output: +.PP +.in +4n +.EX +.RB "$" " ./a.out" +5 messages received +1 11782 +2 11345 +3 304 +4 13514 +5 28421 +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include + +int +main(void) +{ +#define VLEN 10 +#define BUFSIZE 200 +#define TIMEOUT 1 + int sockfd, retval, i; + struct sockaddr_in addr; + struct mmsghdr msgs[VLEN]; + struct iovec iovecs[VLEN]; + char bufs[VLEN][BUFSIZE+1]; + struct timespec timeout; + + sockfd = socket(AF_INET, SOCK_DGRAM, 0); + if (sockfd == \-1) { + perror("socket()"); + exit(EXIT_FAILURE); + } + + addr.sin_family = AF_INET; + addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + addr.sin_port = htons(1234); + if (bind(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { + perror("bind()"); + exit(EXIT_FAILURE); + } + + memset(msgs, 0, sizeof(msgs)); + for (i = 0; i < VLEN; i++) { + iovecs[i].iov_base = bufs[i]; + iovecs[i].iov_len = BUFSIZE; + msgs[i].msg_hdr.msg_iov = &iovecs[i]; + msgs[i].msg_hdr.msg_iovlen = 1; + } + + timeout.tv_sec = TIMEOUT; + timeout.tv_nsec = 0; + + retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout); + if (retval == \-1) { + perror("recvmmsg()"); + exit(EXIT_FAILURE); + } + + printf("%d messages received\\n", retval); + for (i = 0; i < retval; i++) { + bufs[i][msgs[i].msg_len] = 0; + printf("%d %s", i+1, bufs[i]); + } + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR clock_gettime (2), +.BR recvmsg (2), +.BR sendmmsg (2), +.BR sendmsg (2), +.BR socket (2), +.BR socket (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/recvmsg.2 b/man2/recvmsg.2 new file mode 100644 index 0000000..13228c3 --- /dev/null +++ b/man2/recvmsg.2 @@ -0,0 +1 @@ +.so man2/recv.2 diff --git a/man2/remap_file_pages.2 b/man2/remap_file_pages.2 new file mode 100644 index 0000000..de352ff --- /dev/null +++ b/man2/remap_file_pages.2 @@ -0,0 +1,199 @@ +.\" Copyright (C) 2003, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2003-12-10 Initial creation, Michael Kerrisk +.\" 2004-10-28 aeb, corrected prototype, prot must be 0 +.\" +.TH REMAP_FILE_PAGES 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +remap_file_pages \- create a nonlinear file mapping +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int remap_file_pages(void *" addr ", size_t " size ", int " prot , +.BI " size_t " pgoff ", int " flags ); +.fi +.SH DESCRIPTION +.BR Note : +.\" commit 33041a0d76d3c3e0aff28ac95a2ffdedf1282dbc +.\" http://lwn.net/Articles/597632/ +this system call was marked as deprecated starting with Linux 3.16. +In Linux 4.0, the implementation was replaced +.\" commit c8d78c1823f46519473949d33f0d1d33fe21ea16 +by a slower in-kernel emulation. +Those few applications that use this system call should +consider migrating to alternatives. +This change was made because the kernel code for this system call was complex, +and it is believed to be little used or perhaps even completely unused. +While it had some use cases in database applications on 32-bit systems, +those use cases don't exist on 64-bit systems. +.PP +The +.BR remap_file_pages () +system call is used to create a nonlinear mapping, that is, a mapping +in which the pages of the file are mapped into a nonsequential order +in memory. +The advantage of using +.BR remap_file_pages () +over using repeated calls to +.BR mmap (2) +is that the former approach does not require the kernel to create +additional VMA (Virtual Memory Area) data structures. +.PP +To create a nonlinear mapping we perform the following steps: +.TP 3 +1. +Use +.BR mmap (2) +to create a mapping (which is initially linear). +This mapping must be created with the +.B MAP_SHARED +flag. +.TP +2. +Use one or more calls to +.BR remap_file_pages () +to rearrange the correspondence between the pages of the mapping +and the pages of the file. +It is possible to map the same page of a file +into multiple locations within the mapped region. +.PP +The +.I pgoff +and +.I size +arguments specify the region of the file that is to be relocated +within the mapping: +.I pgoff +is a file offset in units of the system page size; +.I size +is the length of the region in bytes. +.PP +The +.I addr +argument serves two purposes. +First, it identifies the mapping whose pages we want to rearrange. +Thus, +.I addr +must be an address that falls within +a region previously mapped by a call to +.BR mmap (2). +Second, +.I addr +specifies the address at which the file pages +identified by +.I pgoff +and +.I size +will be placed. +.PP +The values specified in +.I addr +and +.I size +should be multiples of the system page size. +If they are not, then the kernel rounds +.I both +values +.I down +to the nearest multiple of the page size. +.\" This rounding is weird, and not consistent with the treatment of +.\" the analogous arguments for munmap()/mprotect() and for mlock(). +.\" MTK, 14 Sep 2005 +.PP +The +.I prot +argument must be specified as 0. +.PP +The +.I flags +argument has the same meaning as for +.BR mmap (2), +but all flags other than +.B MAP_NONBLOCK +are ignored. +.SH RETURN VALUE +On success, +.BR remap_file_pages () +returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +.I addr +does not refer to a valid mapping +created with the +.B MAP_SHARED +flag. +.TP +.B EINVAL +.IR addr , +.IR size , +.IR prot , +or +.I pgoff +is invalid. +.\" And possibly others from vma->vm_ops->populate() +.SH VERSIONS +The +.BR remap_file_pages () +system call appeared in Linux 2.5.46; +glibc support was added in version 2.3.3. +.SH CONFORMING TO +The +.BR remap_file_pages () +system call is Linux-specific. +.SH NOTES +Since Linux 2.6.23, +.\" commit 3ee6dafc677a68e461a7ddafc94a580ebab80735 +.BR remap_file_pages () +creates non-linear mappings only +on in-memory filesystems such as +.BR tmpfs (5), +hugetlbfs or ramfs. +On filesystems with a backing store, +.BR remap_file_pages () +is not much more efficient than using +.BR mmap (2) +to adjust which parts of the file are mapped to which addresses. +.SH SEE ALSO +.BR getpagesize (2), +.BR mmap (2), +.BR mmap2 (2), +.BR mprotect (2), +.BR mremap (2), +.BR msync (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/removexattr.2 b/man2/removexattr.2 new file mode 100644 index 0000000..e1101ed --- /dev/null +++ b/man2/removexattr.2 @@ -0,0 +1,128 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH REMOVEXATTR 2 2015-05-07 "Linux" "Linux Programmer's Manual" +.SH NAME +removexattr, lremovexattr, fremovexattr \- remove an extended attribute +.SH SYNOPSIS +.fam C +.nf +.B #include +.B #include +.PP +.BI "int removexattr(const char\ *" path ", const char\ *" name ); +.BI "int lremovexattr(const char\ *" path ", const char\ *" name ); +.BI "int fremovexattr(int " fd ", const char\ *" name ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name : value +pairs associated with inodes (files, directories, symbolic links, etc.). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e., the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR xattr (7). +.PP +.BR removexattr () +removes the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +.PP +.BR lremovexattr () +is identical to +.BR removexattr (), +except in the case of a symbolic link, where the extended attribute is +removed from the link itself, not the file that it refers to. +.PP +.BR fremovexattr () +is identical to +.BR removexattr (), +only the extended attribute is removed from the open file referred to by +.I fd +(as returned by +.BR open (2)) +in place of +.IR path . +.PP +An extended attribute name is a null-terminated string. +The +.I name +includes a namespace prefix; there may be several, disjoint +namespaces associated with an individual inode. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B ENOATTR +The named attribute does not exist. +.RB ( ENOATTR +is defined to be a synonym for +.BR ENODATA +in +.IR .) +.TP +.B ENOTSUP +Extended attributes are not supported by the filesystem, or are disabled. +.PP +In addition, the errors documented in +.BR stat (2) +can also occur. +.SH VERSIONS +These system calls have been available on Linux since kernel 2.4; +glibc support is provided since version 2.3. +.SH CONFORMING TO +These system calls are Linux-specific. +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR listxattr (2), +.BR open (2), +.BR setxattr (2), +.BR stat (2), +.BR symlink (7), +.BR xattr (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/rename.2 b/man2/rename.2 new file mode 100644 index 0000000..f8b4991 --- /dev/null +++ b/man2/rename.2 @@ -0,0 +1,543 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt; +.\" and Copyright (C) 1993,1995 Ian Jackson +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith +.\" Modified Thu Jun 4 12:21:13 1998 by Andries Brouwer +.\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt +.\" 2007-03-25, mtk, added various text to DESCRIPTION. +.\" +.TH RENAME 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +rename, renameat, renameat2 \- change the name or location of a file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int rename(const char *" oldpath ", const char *" newpath ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int renameat(int " olddirfd ", const char *" oldpath , +.BI " int " newdirfd ", const char *" newpath ); +.PP +.BI "int renameat2(int " olddirfd ", const char *" oldpath , +.BI " int " newdirfd ", const char *" newpath \ +", unsigned int " flags ); +.fi +.PP +.IR Note : +There is no glibc wrapper for +.BR renameat2 (); +see NOTES. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR renameat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.\" FIXME . need to define FTMs for renameat2(), once it hits glibc +.RE +.ad +.PD +.SH DESCRIPTION +.BR rename () +renames a file, moving it between directories if required. +Any other hard links to the file (as created using +.BR link (2)) +are unaffected. +Open file descriptors for +.I oldpath +are also unaffected. +.PP +Various restrictions determine whether or not the rename operation succeeds: +see ERRORS below. +.PP +If +.I newpath +already exists, it will be atomically replaced, so that there is +no point at which another process attempting to access +.I newpath +will find it missing. +However, there will probably be a window in which both +.I oldpath +and +.I newpath +refer to the file being renamed. +.PP +If +.I oldpath +and +.I newpath +are existing hard links referring to the same file, then +.BR rename () +does nothing, and returns a success status. +.PP +If +.I newpath +exists but the operation fails for some reason, +.BR rename () +guarantees to leave an instance of +.I newpath +in place. +.PP +.I oldpath +can specify a directory. +In this case, +.I newpath +must either not exist, or it must specify an empty directory. +.PP +If +.I oldpath +refers to a symbolic link, the link is renamed; if +.I newpath +refers to a symbolic link, the link will be overwritten. +.SS renameat() +The +.BR renameat () +system call operates in exactly the same way as +.BR rename (), +except for the differences described here. +.PP +If the pathname given in +.I oldpath +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I olddirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR rename () +for a relative pathname). +.PP +If +.I oldpath +is relative and +.I olddirfd +is the special value +.BR AT_FDCWD , +then +.I oldpath +is interpreted relative to the current working +directory of the calling process (like +.BR rename ()). +.PP +If +.I oldpath +is absolute, then +.I olddirfd +is ignored. +.PP +The interpretation of +.I newpath +is as for +.IR oldpath , +except that a relative pathname is interpreted relative +to the directory referred to by the file descriptor +.IR newdirfd . +.PP +See +.BR openat (2) +for an explanation of the need for +.BR renameat (). +.SS renameat2() +.BR renameat2 () +has an additional +.I flags +argument. +A +.BR renameat2 () +call with a zero +.I flags +argument is equivalent to +.BR renameat (). +.PP +The +.I flags +argument is a bit mask consisting of zero or more of the following flags: +.TP +.B RENAME_EXCHANGE +Atomically exchange +.IR oldpath +and +.IR newpath . +Both pathnames must exist +but may be of different types (e.g., one could be a non-empty directory +and the other a symbolic link). +.TP +.B RENAME_NOREPLACE +Don't overwrite +.IR newpath +of the rename. +Return an error if +.IR newpath +already exists. +.IP +.B RENAME_NOREPLACE +can't be employed together with +.BR RENAME_EXCHANGE . +.TP +.BR RENAME_WHITEOUT " (since Linux 3.18)" +.\" commit 0d7a855526dd672e114aff2ac22b60fc6f155b08 +.\" commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41 +This operation makes sense only for overlay/union +filesystem implementations. +.IP +Specifying +.B RENAME_WHITEOUT +creates a "whiteout" object at the source of +the rename at the same time as performing the rename. +The whole operation is atomic, +so that if the rename succeeds then the whiteout will also have been created. +.IP +A "whiteout" is an object that has special meaning in union/overlay +filesystem constructs. +In these constructs, +multiple layers exist and only the top one is ever modified. +A whiteout on an upper layer will effectively hide a +matching file in the lower layer, +making it appear as if the file didn't exist. +.IP +When a file that exists on the lower layer is renamed, +the file is first copied up (if not already on the upper layer) +and then renamed on the upper, read-write layer. +At the same time, the source file needs to be "whiteouted" +(so that the version of the source file in the lower layer +is rendered invisible). +The whole operation needs to be done atomically. +.IP +When not part of a union/overlay, +the whiteout appears as a character device with a {0,0} device number. +.IP +.B RENAME_WHITEOUT +requires the same privileges as creating a device node (i.e., the +.BR CAP_MKNOD +capability). +.IP +.B RENAME_WHITEOUT +can't be employed together with +.BR RENAME_EXCHANGE . +.IP +.B RENAME_WHITEOUT +requires support from the underlying filesystem. +Among the filesystems that provide that support are +shmem (since Linux 3.18), +.\" shmem: commit 46fdb794e3f52ef18b859ebc92f0a9d7db21c5df +ext4 (since Linux 3.18), +.\" ext4: commit cd808deced431b66b5fa4e5c193cb7ec0059eaff +and XFS (since Linux 4.1). +.\" XFS: commit 7dcf5c3e4527cfa2807567b00387cf2ed5e07f00 +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write permission is denied for the directory containing +.I oldpath +or +.IR newpath , +or, search permission is denied for one of the directories +in the path prefix of +.I oldpath +or +.IR newpath , +or +.I oldpath +is a directory and does not allow write permission (needed to update +the +.I .. +entry). +(See also +.BR path_resolution (7).) +.TP +.B EBUSY +The rename fails because +.IR oldpath " or " newpath +is a directory that is in use by some process (perhaps as +current working directory, or as root directory, or because +it was open for reading) or is in use by the system +(for example as mount point), while the system considers +this an error. +(Note that there is no requirement to return +.B EBUSY +in such +cases\(emthere is nothing wrong with doing the rename anyway\(embut +it is allowed to return +.B EBUSY +if the system cannot otherwise +handle such situations.) +.TP +.B EDQUOT +The user's quota of disk blocks on the filesystem has been exhausted. +.TP +.B EFAULT +.IR oldpath " or " newpath " points outside your accessible address space." +.TP +.B EINVAL +The new pathname contained a path prefix of the old, or, more generally, +an attempt was made to make a directory a subdirectory of itself. +.TP +.B EISDIR +.I newpath +is an existing directory, but +.I oldpath +is not a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR oldpath " or " newpath . +.TP +.B EMLINK +.I oldpath +already has the maximum number of links to it, or +it was a directory and the directory containing +.I newpath +has the maximum number of links. +.TP +.B ENAMETOOLONG +.IR oldpath " or " newpath " was too long." +.TP +.B ENOENT +The link named by +.I oldpath +does not exist; +or, a directory component in +.I newpath +does not exist; +or, +.I oldpath +or +.I newpath +is an empty string. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.IR oldpath " or " newpath +is not, in fact, a directory. +Or, +.I oldpath +is a directory, and +.I newpath +exists but is not a directory. +.TP +.BR ENOTEMPTY " or " EEXIST +.I newpath +is a nonempty directory, that is, contains entries other than "." and "..". +.TP +.BR EPERM " or " EACCES +The directory containing +.I oldpath +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective user ID is neither +the user ID of the file to be deleted nor that of the directory +containing it, and the process is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability); +or +.I newpath +is an existing file and the directory containing it has the sticky bit set +and the process's effective user ID is neither the user ID of the file +to be replaced nor that of the directory containing it, +and the process is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability); +or the filesystem containing +.I pathname +does not support renaming of the type requested. +.TP +.B EROFS +The file is on a read-only filesystem. +.TP +.B EXDEV +.IR oldpath " and " newpath +are not on the same mounted filesystem. +(Linux permits a filesystem to be mounted at multiple points, but +.BR rename () +does not work across different mount points, +even if the same filesystem is mounted on both.) +.PP +The following additional errors can occur for +.BR renameat () +and +.BR renameat2 (): +.TP +.B EBADF +.I olddirfd +or +.I newdirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I oldpath +is relative and +.I olddirfd +is a file descriptor referring to a file other than a directory; +or similar for +.I newpath +and +.I newdirfd +.PP +The following additional errors can occur for +.BR renameat2 (): +.TP +.B EEXIST +.I flags +contains +.B RENAME_NOREPLACE +and +.I newpath +already exists. +.TP +.B EINVAL +An invalid flag was specified in +.IR flags . +.TP +.B EINVAL +Both +.B RENAME_NOREPLACE +and +.B RENAME_EXCHANGE +were specified in +.IR flags . +.TP +.B EINVAL +Both +.B RENAME_WHITEOUT +and +.B RENAME_EXCHANGE +were specified in +.IR flags . +.TP +.B EINVAL +The filesystem does not support one of the flags in +.IR flags . +.TP +.B ENOENT +.I flags +contains +.B RENAME_EXCHANGE +and +.IR newpath +does not exist. +.TP +.B EPERM +.B RENAME_WHITEOUT +was specified in +.IR flags , +but the caller does not have the +.B CAP_MKNOD +capability. +.SH VERSIONS +.BR renameat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.PP +.BR renameat2 () +was added to Linux in kernel 3.15. +.\" FIXME . glibc support is pending. +.SH CONFORMING TO +.BR rename (): +4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008. +.PP +.BR renameat (): +POSIX.1-2008. +.PP +.BR renameat2 () +is Linux-specific. +.SH NOTES +Glibc does not provide a wrapper for the +.BR renameat2 () +system call; call it using +.BR syscall (2). +.\" +.SS Glibc notes +On older kernels where +.BR renameat () +is unavailable, the glibc wrapper function falls back to the use of +.BR rename (). +When +.I oldpath +and +.I newpath +are relative pathnames, +glibc constructs pathnames based on the symbolic links in +.IR /proc/self/fd +that correspond to the +.I olddirfd +and +.IR newdirfd +arguments. +.SH BUGS +On NFS filesystems, you can not assume that if the operation +failed, the file was not renamed. +If the server does the rename operation +and then crashes, the retransmitted RPC which will be processed when the +server is up again causes a failure. +The application is expected to +deal with this. +See +.BR link (2) +for a similar problem. +.SH SEE ALSO +.BR mv (1), +.BR chmod (2), +.BR link (2), +.BR symlink (2), +.BR unlink (2), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/renameat.2 b/man2/renameat.2 new file mode 100644 index 0000000..9b74442 --- /dev/null +++ b/man2/renameat.2 @@ -0,0 +1 @@ +.so man2/rename.2 diff --git a/man2/renameat2.2 b/man2/renameat2.2 new file mode 100644 index 0000000..9b74442 --- /dev/null +++ b/man2/renameat2.2 @@ -0,0 +1 @@ +.so man2/rename.2 diff --git a/man2/request_key.2 b/man2/request_key.2 new file mode 100644 index 0000000..3520b5a --- /dev/null +++ b/man2/request_key.2 @@ -0,0 +1,581 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH REQUEST_KEY 2 2017-09-15 Linux "Linux Key Management Calls" +.SH NAME +request_key \- request a key from the kernel's key management facility +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "key_serial_t request_key(const char *" type ", const char *" description , +.BI " const char *" callout_info , +.BI " key_serial_t " dest_keyring ");" +.fi +.PP +No glibc wrapper is provided for this system call; see NOTES. +.SH DESCRIPTION +.BR request_key () +attempts to find a key of the given +.I type +with a description (name) that matches the specified +.IR description . +If such a key could not be found, then the key is optionally created. +If the key is found or created, +.BR request_key () +attaches it to the keyring whose ID is specified in +.I dest_keyring +and returns the key's serial number. +.PP +.BR request_key () +first recursively searches for a matching key in all of the keyrings +attached to the calling process. +The keyrings are searched in the order: thread-specific keyring, +process-specific keyring, and then session keyring. +.PP +If +.BR request_key () +is called from a program invoked by +.BR request_key () +on behalf of some other process to generate a key, then the keyrings of that +other process will be searched next, +using that other process's user ID, group ID, +supplementary group IDs, and security context to determine access. +.\" David Howells: we can then have an arbitrarily long sequence +.\" of "recursive" request-key upcalls. There is no limit, other +.\" than number of PIDs, etc. +.PP +The search of the keyring tree is breadth-first: +the keys in each keyring searched are checked for a match before any child +keyrings are recursed into. +Only keys for which the caller has +.I search +permission be found, and only keyrings for which the caller has +.I search +permission may be searched. +.PP +If the key is not found and +.I callout +is NULL, then the call fails with the error +.BR ENOKEY . +.PP +If the key is not found and +.I callout +is not NULL, then the kernel attempts to invoke a user-space +program to instantiate the key. +The details are given below. +.PP +The +.I dest_keyring +serial number may be that of a valid keyring for which the caller has +.I write +permission, or it may be one of the following special keyring IDs: +.TP +.B KEY_SPEC_THREAD_KEYRING +This specifies the caller's thread-specific keyring (see +.BR thread-keyring (7)). +.TP +.B KEY_SPEC_PROCESS_KEYRING +This specifies the caller's process-specific keyring (see +.BR process-keyring (7)). +.TP +.B KEY_SPEC_SESSION_KEYRING +This specifies the caller's session-specific keyring (see +.BR session-keyring (7)). +.TP +.B KEY_SPEC_USER_KEYRING +This specifies the caller's UID-specific keyring (see +.BR user-keyring (7)). +.TP +.B KEY_SPEC_USER_SESSION_KEYRING +This specifies the caller's UID-session keyring (see +.BR user-session-keyring (7)). +.PP +When the +.I dest_keyring +is specified as 0 +and no key construction has been performed, +then no additional linking is done. +.PP +Otherwise, if +.I dest_keyring +is 0 and a new key is constructed, the new key will be linked +to the "default" keyring. +More precisely, when the kernel tries to determine to which keyring the +newly constructed key should be linked, +it tries the following keyrings, +beginning with the keyring set via the +.BR keyctl (2) +.BR KEYCTL_SET_REQKEY_KEYRING +operation and continuing in the order shown below +until it finds the first keyring that exists: +.IP \(bu 3 +.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 +The requestor keyring +.RB ( KEY_REQKEY_DEFL_REQUESTOR_KEYRING , +since Linux 2.6.29). +.\" FIXME +.\" Actually, is the preceding point correct? +.\" If I understand correctly, we'll only get here if +.\" 'dest_keyring' is zero, in which case KEY_REQKEY_DEFL_REQUESTOR_KEYRING +.\" won't refer to a keyring. Have I misunderstood? +.IP \(bu +The thread-specific keyring +.RB ( KEY_REQKEY_DEFL_THREAD_KEYRING ; +see +.BR thread-keyring (7)). +.IP \(bu +The process-specific keyring +.RB ( KEY_REQKEY_DEFL_PROCESS_KEYRING ; +see +.BR process-keyring (7)). +.IP \(bu +The session-specific keyring +.RB ( KEY_REQKEY_DEFL_SESSION_KEYRING ; +see +.BR session-keyring (7)). +.IP \(bu +The session keyring for the process's user ID +.RB ( KEY_REQKEY_DEFL_USER_SESSION_KEYRING ; +see +.BR user-session-keyring (7)). +This keyring is expected to always exist. +.IP \(bu +The UID-specific keyring +.RB ( KEY_REQKEY_DEFL_USER_KEYRING ; +see +.BR user-keyring (7)). +This keyring is also expected to always exist. +.\" mtk: Are there circumstances where the user sessions and UID-specific +.\" keyrings do not exist? +.\" +.\" David Howells: +.\" The uid keyrings don't exist until someone tries to access them - +.\" at which point they're both created. When you log in, pam_keyinit +.\" creates a link to your user keyring in the session keyring it just +.\" created, thereby creating the user and user-session keyrings. +.\" +.\" and David elaborated that "access" means: +.\" +.\" It means lookup_user_key() was passed KEY_LOOKUP_CREATE. So: +.\" +.\" add_key() - destination keyring +.\" request_key() - destination keyring +.\" KEYCTL_GET_KEYRING_ID - if create arg is true +.\" KEYCTL_CLEAR +.\" KEYCTL_LINK - both args +.\" KEYCTL_SEARCH - destination keyring +.\" KEYCTL_CHOWN +.\" KEYCTL_SETPERM +.\" KEYCTL_SET_TIMEOUT +.\" KEYCTL_INSTANTIATE - destination keyring +.\" KEYCTL_INSTANTIATE_IOV - destination keyring +.\" KEYCTL_NEGATE - destination keyring +.\" KEYCTL_REJECT - destination keyring +.\" KEYCTL_GET_PERSISTENT - destination keyring +.\" +.\" will all create a keyring under some circumstances. Whereas the rest, +.\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't. +.PP +If the +.BR keyctl (2) +.BR KEYCTL_SET_REQKEY_KEYRING +operation specifies +.BR KEY_REQKEY_DEFL_DEFAULT +(or no +.BR KEYCTL_SET_REQKEY_KEYRING +operation is performed), +then the kernel looks for a keyring +starting from the beginning of the list. +.\" +.SS Requesting user-space instantiation of a key +If the kernel cannot find a key matching +.IR type +and +.IR description , +and +.I callout +is not NULL, then the kernel attempts to invoke a user-space +program to instantiate a key with the given +.IR type +and +.IR description . +In this case, the following steps are performed: +.IP a) 4 +The kernel creates an uninstantiated key, U, with the requested +.I type +and +.IR description . +.IP b) +The kernel creates an authorization key, V, +.\" struct request_key_auth, defined in security/keys/internal.h +that refers to the key U and records the facts that the caller of +.BR request_key () +is: +.RS +.IP (1) 4 +the context in which the key U should be instantiated and secured, and +.IP (2) +the context from which associated key requests may be satisfied. +.RE +.IP +The authorization key is constructed as follows: +.RS +.IP * 3 +The key type is +.IR """.request_key_auth""" . +.IP * +The key's UID and GID are the same as the corresponding filesystem IDs +of the requesting process. +.IP * +The key grants +.IR view , +.IR read , +and +.IR search +permissions to the key possessor as well as +.IR view +permission for the key user. +.IP * +The description (name) of the key is the hexadecimal +string representing the ID of the key that is to be instantiated +in the requesting program. +.IP * +The payload of the key is taken from the data specified in +.IR callout_info . +.IP * +Internally, the kernel also records the PID of the process that called +.BR request_key (). +.RE +.IP c) +The kernel creates a process that executes a user-space service such as +.BR request-key (8) +with a new session keyring that contains a link to the authorization key, V. +.\" The request-key(8) program can be invoked in circumstances *other* than +.\" when triggered by request_key(2). For example, upcalls from places such +.\" as the DNS resolver. +.IP +This program is supplied with the following command-line arguments: +.RS +.IP [0] 4 +The string +.IR """/sbin/request-key""" . +.IP [1] +The string +.I """create""" +(indicating that a key is to be created). +.IP [2] +The ID of the key that is to be instantiated. +.IP [3] +The filesystem UID of the caller of +.BR request_key (). +.IP [4] +The filesystem GID of the caller of +.BR request_key (). +.IP [5] +The ID of the thread keyring of the caller of +.BR request_key (). +This may be zero if that keyring hasn't been created. +.IP [6] +The ID of the process keyring of the caller of +.BR request_key (). +This may be zero if that keyring hasn't been created. +.IP [7] +The ID of the session keyring of the caller of +.BR request_key (). +.RE +.IP +.IR Note : +each of the command-line arguments that is a key ID is encoded in +.IR decimal +(unlike the key IDs shown in +.IR /proc/keys , +which are shown as hexadecimal values). +.IP d) +The program spawned in the previous step: +.RS +.IP * 3 +Assumes the authority to instantiate the key U using the +.BR keyctl (2) +.BR KEYCTL_ASSUME_AUTHORITY +operation (typically via the +.BR keyctl_assume_authority (3) +function). +.IP * +Obtains the callout data from the payload of the authorization key V +(using the +.BR keyctl (2) +.BR KEYCTL_READ +operation (or, more commonly, the +.BR keyctl_read (3) +function) with a key ID value of +.BR KEY_SPEC_REQKEY_AUTH_KEY ). +.IP * +Instantiates the key +(or execs another program that performs that task), +specifying the payload and destination keyring. +(The destination keyring that the requestor specified when calling +.BR request_key () +can be accessed using the special key ID +.BR KEY_SPEC_REQUESTOR_KEYRING .) +.\" Should an instantiating program be using KEY_SPEC_REQUESTOR_KEYRING? +.\" I couldn't find a use in the keyutils git repo. +.\" According to David Howells: +.\" * This feature is provided, but not used at the moment. +.\" * A key added to that ring is then owned by the requester +Instantiation is performed using the +.BR keyctl (2) +.BR KEYCTL_INSTANTIATE +operation (or, more commonly, the +.BR keyctl_instantiate (3) +function). +At this point, the +.BR request_key () +call completes, and the requesting program can continue execution. +.RE +.PP +If these steps are unsuccessful, then an +.BR ENOKEY +error will be returned to the caller of +.BR request_key () +and a temporary, negatively instantiated key will be installed +in the keyring specified by +.IR dest_keyring . +This will expire after a few seconds, but will cause subsequent calls to +.BR request_key () +to fail until it does. +The purpose of this negatively instantiated key is to prevent +(possibly different) processes making repeated requests +(that require expensive +.BR request-key (8) +upcalls) for a key that can't (at the moment) be positively instantiated. +.PP +Once the key has been instantiated, the authorization key +.RB ( KEY_SPEC_REQKEY_AUTH_KEY ) +is revoked, and the destination keyring +.RB ( KEY_SPEC_REQUESTOR_KEYRING ) +is no longer accessible from the +.BR request-key (8) +program. +.PP +If a key is created, then\(emregardless of whether it is a valid key or +a negatively instantiated key\(emit will displace any other key with +the same type and description from the keyring specified in +.IR dest_keyring . +.SH RETURN VALUE +On success, +.BR request_key () +returns the serial number of the key it found or caused to be created. +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.TP +.B EACCES +The keyring wasn't available for modification by the user. +.TP +.B EDQUOT +The key quota for this user would be exceeded by creating this key or linking +it to the keyring. +.TP +.B EFAULT +One of +.IR type , +.IR description , +or +.IR callout_info +points outside the process's accessible address space. +.TP +.B EINTR +The request was interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +The size of the string (including the terminating null byte) specified in +.I type +or +.I description +exceeded the limit (32 bytes and 4096 bytes respectively). +.TP +.B EINVAL +The size of the string (including the terminating null byte) specified in +.I callout_info +exceeded the system page size. +.TP +.B EKEYEXPIRED +An expired key was found, but no replacement could be obtained. +.TP +.B EKEYREJECTED +The attempt to generate a new key was rejected. +.TP +.B EKEYREVOKED +A revoked key was found, but no replacement could be obtained. +.TP +.B ENOKEY +No matching key was found. +.TP +.B ENOMEM +Insufficient memory to create a key. +.TP +.B EPERM +The +.I type +argument started with a period (\(aq.\(aq). +.SH VERSIONS +This system call first appeared in Linux 2.6.10. +The ability to instantiate keys upon request was added +.\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a +in Linux 2.6.13. +.SH CONFORMING TO +This system call is a nonstandard Linux extension. +.SH NOTES +No wrapper for this system call is provided in glibc. +A wrapper is provided in the +.IR libkeyutils +package. +When employing the wrapper in that library, link with +.IR \-lkeyutils . +.SH EXAMPLE +The program below demonstrates the use of +.BR request_key (). +The +.IR type , +.IR description , +and +.IR callout_info +arguments for the system call are taken from the values +supplied in the command-line arguments. +The call specifies the session keyring as the target keyring. +.PP +In order to demonstrate this program, +we first create a suitable entry in the file +.IR /etc/request-key.conf . +.PP +.in +4n +.EX +$ sudo sh +# \fBecho 'create user mtk:* * /bin/keyctl instantiate %k %c %S' \\\fP + \fB> /etc/request-key.conf\fP +# \fBexit\fP +.EE +.in +.PP +This entry specifies that when a new "user" key with the prefix +"mtk:" must be instantiated, that task should be performed via the +.BR keyctl (1) +command's +.B instantiate +operation. +The arguments supplied to the +.B instantiate +operation are: +the ID of the uninstantiated key +.RI ( %k ); +the callout data supplied to the +.BR request_key () +call +.RI ( %c ); +and the session keyring +.RI ( %S ) +of the requestor (i.e., the caller of +.BR request_key ()). +See +.BR request-key.conf (5) +for details of these +.I % +specifiers. +.PP +Then we run the program and check the contents of +.IR /proc/keys +to verify that the requested key has been instantiated: +.PP +.in +4n +.EX +$ \fB./t_request_key user mtk:key1 "Payload data"\fP +$ \fBgrep \(aq2dddaf50\(aq /proc/keys\fP +2dddaf50 I--Q--- 1 perm 3f010000 1000 1000 user mtk:key1: 12 +.EE +.in +.PP +For another example of the use of this program, see +.BR keyctl (2). +.SS Program source +\& +.EX +/* t_request_key.c */ + +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + key_serial_t key; + + if (argc != 4) { + fprintf(stderr, "Usage: %s type description callout\-data\\n", + argv[0]); + exit(EXIT_FAILURE); + } + + key = request_key(argv[1], argv[2], argv[3], + KEY_SPEC_SESSION_KEYRING); + if (key == \-1) { + perror("request_key"); + exit(EXIT_FAILURE); + } + + printf("Key ID is %lx\\n", (long) key); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR keyctl (3), +.BR capabilities (7), +.BR keyrings (7), +.BR keyutils (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7), +.BR request\-key (8) +.PP +The kernel source files +.IR Documentation/security/keys/core.rst +and +.IR Documentation/keys/request\-key.rst +(or, before Linux 4.13, in the files +.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 +.IR Documentation/security/keys.txt +and +.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b +.IR Documentation/security/keys\-request\-key.txt ). +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/restart_syscall.2 b/man2/restart_syscall.2 new file mode 100644 index 0000000..70c291b --- /dev/null +++ b/man2/restart_syscall.2 @@ -0,0 +1,152 @@ +.\" Copyright (c) 2013 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" http://thread.gmane.org/gmane.linux.kernel/76552/focus=76803 +.\" From: Linus Torvalds transmeta.com> +.\" Subject: Re: [PATCH] compatibility syscall layer (lets try again) +.\" Newsgroups: gmane.linux.kernel +.\" Date: 2002-12-05 02:51:12 GMT +.\" +.\" See also Section 11.3.3 of Understanding the Linux Kernel, 3rd edition +.\" +.TH RESTART_SYSCALL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +restart_syscall \- restart a system call after interruption by a stop signal +.SH SYNOPSIS +.B int restart_syscall(void); +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The +.BR restart_syscall () +system call is used to restart certain system calls +after a process that was stopped by a signal (e.g., +.BR SIGSTOP +or +.BR SIGTSTP ) +is later resumed after receiving a +.BR SIGCONT +signal. +This system call is designed only for internal use by the kernel. +.PP +.BR restart_syscall () +is used for restarting only those system calls that, +when restarted, should adjust their time-related parameters\(emnamely +.BR poll (2) +(since Linux 2.6.24), +.BR nanosleep (2) +(since Linux 2.6), +.BR clock_nanosleep (2) +(since Linux 2.6), +and +.BR futex (2), +when employed with the +.BR FUTEX_WAIT +(since Linux 2.6.22) +and +.BR FUTEX_WAIT_BITSET +(since Linux 2.6.31) +operations. +.\" These system calls correspond to the special internal errno value +.\" ERESTART_RESTARTBLOCK. Each of the system calls has a "restart" +.\" helper function that is invoked by restart_syscall(). +.\" Notable (as at Linux 3.17) is that poll() has such a "restart" +.\" function, but ppoll(), select(), and pselect() do not. +.\" This means that the latter system calls do not take account of the +.\" time spent in the stopped state when restarting. +.BR restart_syscall () +restarts the interrupted system call with a +time argument that is suitably adjusted to account for the +time that has already elapsed (including the time where the process +was stopped by a signal). +Without the +.BR restart_syscall () +mechanism, restarting these system calls would not correctly deduct the +already elapsed time when the process continued execution. +.SH RETURN VALUE +The return value of +.BR restart_syscall () +is the return value of whatever system call is being restarted. +.SH ERRORS +.I errno +is set as per the errors for whatever system call is being restarted by +.BR restart_syscall (). +.SH VERSIONS +The +.BR restart_syscall () +system call is present since Linux 2.6. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +There is no glibc wrapper for this system call, +because it is intended for use only by the kernel and +should never be called by applications. +.PP +The kernel uses +.BR restart_syscall () +to ensure that when a system call is restarted +after a process has been stopped by a signal and then resumed by +.BR SIGCONT , +then the time that the process spent in the stopped state is counted +against the timeout interval specified in the original system call. +In the case of system calls that take a timeout argument and +automatically restart after a stop signal plus +.BR SIGCONT , +but which do not have the +.BR restart_syscall () +mechanism built in, then, after the process resumes execution, +the time that the process spent in the stop state is +.I not +counted against the timeout value. +Notable examples of system calls that suffer this problem are +.BR ppoll (2), +.BR select (2), +and +.BR pselect (2). +.PP +From user space, the operation of +.BR restart_syscall () +is largely invisible: +to the process that made the system call that is restarted, +it appears as though that system call executed and +returned in the usual fashion. +.SH SEE ALSO +.BR sigaction (2), +.BR sigreturn (2), +.BR signal (7) +.\" FIXME . ppoll(2), select(2), and pselect(2) +.\" should probably get the restart_syscall() treatment: +.\" If a select() call is suspended by stop-sig+SIGCONT, the time +.\" spent suspended is *not* deducted when the select() is restarted. +.\" FIXME . check whether recvmmsg() handles stop-sig+SIGCONT properly. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/rmdir.2 b/man2/rmdir.2 new file mode 100644 index 0000000..1eff7cd --- /dev/null +++ b/man2/rmdir.2 @@ -0,0 +1,150 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH RMDIR 2 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +rmdir \- delete a directory +.SH SYNOPSIS +.B #include +.PP +.BI "int rmdir(const char *" pathname ); +.SH DESCRIPTION +.BR rmdir () +deletes a directory, which must be empty. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I pathname +was not allowed, or one of the directories in the path prefix of +.I pathname +did not allow search permission. +(See also +.BR path_resolution (7). +.TP +.B EBUSY +.I pathname +is currently in use by the system or some process that prevents its +removal. +On Linux, this means +.I pathname +is currently used as a mount point +or is the root directory of the calling process. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EINVAL +.I pathname +has +.I . +as last component. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +.IR pathname , +or a component used as a directory in +.IR pathname , +is not, in fact, a directory. +.TP +.B ENOTEMPTY +.I pathname +contains entries other than +.IR . " and " .. " ;" +or, +.I pathname +has +.I .. +as its final component. +POSIX.1 also allows +.\" POSIX.1-2001, POSIX.1-2008 +.B EEXIST +for this condition. +.TP +.B EPERM +The directory containing +.I pathname +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective user ID is neither the user ID +of the file to be deleted nor that of the directory containing it, +and the process is not privileged (Linux: does not have the +.B CAP_FOWNER +capability). +.TP +.B EPERM +The filesystem containing +.I pathname +does not support the removal of directories. +.TP +.B EROFS +.I pathname +refers to a directory on a read-only filesystem. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of directories which are still being used. +.SH SEE ALSO +.BR rm (1), +.BR rmdir (1), +.BR chdir (2), +.BR chmod (2), +.BR mkdir (2), +.BR rename (2), +.BR unlink (2), +.BR unlinkat (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/rt_sigaction.2 b/man2/rt_sigaction.2 new file mode 100644 index 0000000..d642d26 --- /dev/null +++ b/man2/rt_sigaction.2 @@ -0,0 +1 @@ +.so man2/sigaction.2 diff --git a/man2/rt_sigpending.2 b/man2/rt_sigpending.2 new file mode 100644 index 0000000..304adff --- /dev/null +++ b/man2/rt_sigpending.2 @@ -0,0 +1 @@ +.so man2/sigpending.2 diff --git a/man2/rt_sigprocmask.2 b/man2/rt_sigprocmask.2 new file mode 100644 index 0000000..5eab7ac --- /dev/null +++ b/man2/rt_sigprocmask.2 @@ -0,0 +1 @@ +.so man2/sigprocmask.2 diff --git a/man2/rt_sigqueueinfo.2 b/man2/rt_sigqueueinfo.2 new file mode 100644 index 0000000..8c74ef8 --- /dev/null +++ b/man2/rt_sigqueueinfo.2 @@ -0,0 +1,204 @@ +.\" Copyright (c) 2002, 2011 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH RT_SIGQUEUEINFO 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +rt_sigqueueinfo, rt_tgsigqueueinfo \- queue a signal and data +.SH SYNOPSIS +.nf +.BI "int rt_sigqueueinfo(pid_t " tgid ", int " sig ", siginfo_t *" uinfo ); +.PP +.BI "int rt_tgsigqueueinfo(pid_t " tgid ", pid_t " tid ", int " sig , +.BI " siginfo_t *" uinfo ); +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +The +.BR rt_sigqueueinfo () +and +.BR rt_tgsigqueueinfo () +system calls are the low-level interfaces used to send a signal plus data +to a process or thread. +The receiver of the signal can obtain the accompanying data +by establishing a signal handler with the +.BR sigaction (2) +.B SA_SIGINFO +flag. +.PP +These system calls are not intended for direct application use; +they are provided to allow the implementation of +.BR sigqueue (3) +and +.BR pthread_sigqueue (3). +.PP +The +.BR rt_sigqueueinfo () +system call sends the signal +.I sig +to the thread group with the ID +.IR tgid . +(The term "thread group" is synonymous with "process", and +.I tid +corresponds to the traditional UNIX process ID.) +The signal will be delivered to an arbitrary member of the thread group +(i.e., one of the threads that is not currently blocking the signal). +.PP +The +.I uinfo +argument specifies the data to accompany the signal. +This argument is a pointer to a structure of type +.IR siginfo_t , +described in +.BR sigaction (2) +(and defined by including +.IR ). +The caller should set the following fields in this structure: +.TP +.I si_code +This must be one of the +.B SI_* +codes in the Linux kernel source file +.IR include/asm-generic/siginfo.h , +with the restriction that the code must be negative +(i.e., cannot be +.BR SI_USER , +which is used by the kernel to indicate a signal sent by +.BR kill (2)) +and cannot (since Linux 2.6.39) be +.BR SI_TKILL +(which is used by the kernel to indicate a signal sent using +.\" tkill(2) or +.BR tgkill (2)). +.TP +.I si_pid +This should be set to a process ID, +typically the process ID of the sender. +.TP +.I si_uid +This should be set to a user ID, +typically the real user ID of the sender. +.TP +.I si_value +This field contains the user data to accompany the signal. +For more information, see the description of the last +.RI ( "union sigval" ) +argument of +.BR sigqueue (3). +.PP +Internally, the kernel sets the +.I si_signo +field to the value specified in +.IR sig , +so that the receiver of the signal can also obtain +the signal number via that field. +.PP +The +.BR rt_tgsigqueueinfo () +system call is like +.BR rt_sigqueueinfo (), +but sends the signal and data to the single thread +specified by the combination of +.IR tgid , +a thread group ID, +and +.IR tid , +a thread in that thread group. +.SH RETURN VALUE +On success, these system calls return 0. +On error, they return \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.IR sig , +.IR tgid , +or +.IR tid +was invalid. +.TP +.B EPERM +The caller does not have permission to send the signal to the target. +For the required permissions, see +.BR kill (2). +Or: +.I uinfo->si_code +is invalid. +.TP +.B ESRCH +.BR rt_sigqueueinfo (): +No thread group matching +.I tgid +was found. +.PP +.BR rt_tgsigqueinfo (): +No thread matching +.I tgid +and +.I tid +was found. +.SH VERSIONS +The +.BR rt_sigqueueinfo () +system call was added to Linux in version 2.2. +The +.BR rt_tgsigqueueinfo () +system call was added to Linux in version 2.6.31. +.SH CONFORMING TO +These system calls are Linux-specific. +.SH NOTES +Since these system calls are not intended for application use, +there are no glibc wrapper functions; use +.BR syscall (2) +in the unlikely case that you want to call them directly. +.PP +As with +.BR kill (2), +the null signal (0) can be used to check if the specified process +or thread exists. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR tgkill (2), +.BR pthread_sigqueue (3), +.BR sigqueue (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/rt_sigreturn.2 b/man2/rt_sigreturn.2 new file mode 100644 index 0000000..830b7b9 --- /dev/null +++ b/man2/rt_sigreturn.2 @@ -0,0 +1 @@ +.so man2/sigreturn.2 diff --git a/man2/rt_sigsuspend.2 b/man2/rt_sigsuspend.2 new file mode 100644 index 0000000..96d99c4 --- /dev/null +++ b/man2/rt_sigsuspend.2 @@ -0,0 +1 @@ +.so man2/sigsuspend.2 diff --git a/man2/rt_sigtimedwait.2 b/man2/rt_sigtimedwait.2 new file mode 100644 index 0000000..ca098e5 --- /dev/null +++ b/man2/rt_sigtimedwait.2 @@ -0,0 +1 @@ +.so man2/sigtimedwait.2 diff --git a/man2/rt_tgsigqueueinfo.2 b/man2/rt_tgsigqueueinfo.2 new file mode 100644 index 0000000..7b6cf68 --- /dev/null +++ b/man2/rt_tgsigqueueinfo.2 @@ -0,0 +1 @@ +.so man2/rt_sigqueueinfo.2 diff --git a/man2/s390_pci_mmio_read.2 b/man2/s390_pci_mmio_read.2 new file mode 100644 index 0000000..dedc390 --- /dev/null +++ b/man2/s390_pci_mmio_read.2 @@ -0,0 +1 @@ +.so man2/s390_pci_mmio_write.2 diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2 new file mode 100644 index 0000000..8fcdcd3 --- /dev/null +++ b/man2/s390_pci_mmio_write.2 @@ -0,0 +1,116 @@ +.\" Copyright (c) IBM Corp. 2015 +.\" Author: Alexey Ishchuk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH S390_PCI_MMIO_WRITE 2 2017-09-15 "Linux Programmer's Manual" +.SH NAME +s390_pci_mmio_write, s390_pci_mmio_read \- transfer data to/from PCI +MMIO memory page +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int s390_pci_mmio_write(unsigned long " mmio_addr ", +.BI " void *" user_buffer ", size_t " length "); +.BI "int s390_pci_mmio_read(unsigned long " mmio_addr ", +.BI " void *" user_buffer ", size_t " length "); +.fi +.SH DESCRIPTION +The +.BR s390_pci_mmio_write () +system call writes +.IR length +bytes of data from the user-space buffer +.IR user_buffer +to the PCI MMIO memory location specified by +.IR mmio_addr . +The +.BR s390_pci_mmio_read () +system call reads +.I length +bytes of +data from the PCI MMIO memory location specified by +.IR mmio_addr +to the user-space buffer +.IR user_buffer . +.PP +These system calls must be used instead of the simple assignment +or data-transfer operations that are used to access the PCI MMIO +memory areas mapped to user space on the Linux System z platform. +The address specified by +.IR mmio_addr +must belong to a PCI MMIO memory page mapping in the caller's address space, +and the data being written or read must not cross a page boundary. +The +.IR length +value cannot be greater than the system page size. +.SH RETURN VALUE +On success, +.BR s390_pci_mmio_write () +and +.BR s390_pci_mmio_read () +return 0. +On error, \-1 is returned and +.IR errno +is set to one of the error codes listed below. +.SH ERRORS +.TP +.B EFAULT +The address in +.I mmio_addr +is invalid. +.TP +.B EFAULT +.IR user_buffer +does not point to a valid location in the caller's address space. +.TP +.B EINVAL +Invalid +.I length +argument. +.TP +.B ENODEV +PCI support is not enabled. +.TP +.B ENOMEM +Insufficient memory. +.SH VERSIONS +These system calls are available since Linux 3.19. +.SH CONFORMING TO +This Linux-specific system call is available only on the s390 architecture. +The required PCI support is available beginning with System z EC12. +.SH NOTES +Glibc does not provide a wrapper for this system call, use +.BR syscall (2) +to call it. +.SH SEE ALSO +.BR syscall (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2 new file mode 100644 index 0000000..d7edaab --- /dev/null +++ b/man2/s390_runtime_instr.2 @@ -0,0 +1,99 @@ +.\" Copyright (c) IBM Corp. 2012 +.\" Author: Jan Glauber +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH S390_RUNTIME_INSTR 2 2017-09-15 "Linux Programmer's Manual" +.SH NAME +s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int s390_runtime_instr(int " command ", int " signum "); +.fi +.SH DESCRIPTION +The +.BR s390_runtime_instr () +system call starts or stops CPU run-time instrumentation for the +calling thread. +.PP +The +.IR command +argument controls whether run-time instrumentation is started +.RB ( S390_RUNTIME_INSTR_START , +1) or stopped +.RB ( S390_RUNTIME_INSTR_STOP , +2) for the calling thread. +.PP +The +.IR signum +argument specifies the number of a real-time signal. +The real-time signal is sent to the thread if the run-time instrumentation +buffer is full or if the run-time-instrumentation-halted interrupt +occurred. +.SH RETURN VALUE +On success, +.BR s390_runtime_instr () +returns 0 and enables the thread for +run-time instrumentation by assigning the thread a default run-time +instrumentation control block. +The caller can then read and modify the control block and start the run-time +instrumentation. +On error, \-1 is returned and +.IR errno +is set to one of the error codes listed below. +.SH ERRORS +.TP +.B EINVAL +The value specified in +.IR command +is not a valid command or the value specified in +.IR signum +is not a real-time signal number. +.TP +.B ENOMEM +Allocating memory for the run-time instrumentation control block failed. +.TP +.B EOPNOTSUPP +The run-time instrumentation facility is not available. +.SH VERSIONS +This system call is available since Linux 3.7. +.SH CONFORMING TO +This Linux-specific system call is available only on the s390 architecture. +The run-time instrumentation facility is available beginning with System z EC12. +.SH NOTES +Glibc does not provide a wrapper for this system call, use +.BR syscall (2) +to call it. +.SH SEE ALSO +.BR syscall (2), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2 new file mode 100644 index 0000000..bf935ee --- /dev/null +++ b/man2/s390_sthyi.2 @@ -0,0 +1,140 @@ +.\" Copyright IBM Corp. 2017 +.\" Author: QingFeng Hao +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH S390_STHYI 2 2018-02-02 "Linux Programmer's Manual" +.SH NAME +s390_sthyi \- emulate STHYI instruction +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ", +.BI " uint64_t *" return_code ", unsigned long " flags "); +.fi +.SH DESCRIPTION +The +.BR s390_sthyi () +system call emulates the STHYI (Store Hypervisor Information) instruction. +It provides hardware resource information for the machine and its +virtualization levels. +This includes CPU type and capacity, as well as the machine model and +other metrics. +.PP +The +.I function_code +argument indicates which function to perform. +The following code(s) are supported: +.TP +0 +Return CP (Central Processor) and IFL (Integrated Facility for Linux) +capacity information. +.PP +The +.I resp_buffer +argument specifies the address of a response buffer. +If the system call returns 0, +the response buffer will be filled with CPU capacity information. +Otherwise, the response buffer's content is unchanged. +.PP +The +.I return_code +argument stores the return code of the STHYI instruction, +using one of the following values: +.TP 8 +0 +Success. +.TP +4 +Unsupported function code. +.PP +For further details about +.IR return_code , +.IR function_code , +and +.IR resp_buffer , +see the reference given in NOTES. +.PP +The +.I flags +argument is provided to allow for future extensions and currently +must be set to 0. +.SH RETURN VALUE +On success (that is: emulation succeeded), the return value of +.BR s390_sthyi () +matches the condition code of the STHYI instructions, which is a value +in the range [0..3]. +A return value of 0 indicates that CPU capacity information is stored in +.IR *resp_buffer . +A return value of 3 indicates "unsupported function code" and the content of +.IR *resp_buffer +is unchanged. +The return values 1 and 2 are reserved. +.PP +On error, \-1 is returned, and +.IR errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +The value specified in +.I resp_buffer +or +.I return_code +is not a valid address. +.TP +.B EINVAL +The value specified in +.I flags +is nonzero. +.TP +.B ENOMEM +Allocating memory for handling the CPU capacity information failed. +.TP +.B EOPNOTSUPP +The value specified in +.I function_code +is not valid. +.SH VERSIONS +This system call is available since Linux 4.15. +.SH CONFORMING TO +This Linux-specific system call is available only on the s390 architecture. +.SH NOTES +Glibc does not provide a wrapper for this system call, use +.BR syscall (2) +to call it. +.PP +For details of the STHYI instruction, see +.UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm +.UE . +.SH SEE ALSO +.BR syscall (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sbrk.2 b/man2/sbrk.2 new file mode 100644 index 0000000..a3711a5 --- /dev/null +++ b/man2/sbrk.2 @@ -0,0 +1 @@ +.so man2/brk.2 diff --git a/man2/sched_get_priority_max.2 b/man2/sched_get_priority_max.2 new file mode 100644 index 0000000..aafa63d --- /dev/null +++ b/man2/sched_get_priority_max.2 @@ -0,0 +1,134 @@ +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH SCHED_GET_PRIORITY_MAX 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_get_priority_max, sched_get_priority_min \- get static priority range +.SH SYNOPSIS +.B #include +.PP +.BI "int sched_get_priority_max(int " policy ); +.PP +.BI "int sched_get_priority_min(int " policy ); +.SH DESCRIPTION +.BR sched_get_priority_max () +returns the maximum priority value that can be used with the +scheduling algorithm identified by +.IR policy . +.BR sched_get_priority_min () +returns the minimum priority value that can be used with the +scheduling algorithm identified by +.IR policy . +Supported +.I policy +values are +.BR SCHED_FIFO , +.BR SCHED_RR , +.BR SCHED_OTHER , +.BR SCHED_BATCH , +.BR SCHED_IDLE , +and +.BR SCHED_DEADLINE . +Further details about these policies can be found in +.BR sched (7). +.PP +Processes with numerically higher priority values are scheduled before +processes with numerically lower priority values. +Thus, the value +returned by +.BR sched_get_priority_max () +will be greater than the +value returned by +.BR sched_get_priority_min (). +.PP +Linux allows the static priority range 1 to 99 for the +.B SCHED_FIFO +and +.B SCHED_RR +policies, and the priority 0 for the remaining policies. +Scheduling priority ranges for the various policies +are not alterable. +.PP +The range of scheduling priorities may vary on other POSIX systems, +thus it is a good idea for portable applications to use a virtual +priority range and map it to the interval given by +.BR sched_get_priority_max () +and +.BR sched_get_priority_min +POSIX.1 requires +.\" POSIX.1-2001, POSIX.1-2008 (XBD 2.8.4) +a spread of at least 32 between the maximum and the minimum values for +.B SCHED_FIFO +and +.BR SCHED_RR . +.PP +POSIX systems on which +.BR sched_get_priority_max () +and +.BR sched_get_priority_min () +are available define +.B _POSIX_PRIORITY_SCHEDULING +in +.IR . +.SH RETURN VALUE +On success, +.BR sched_get_priority_max () +and +.BR sched_get_priority_min () +return the maximum/minimum priority value for the named scheduling +policy. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The argument +.I policy +does not identify a defined scheduling policy. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.ad l +.nh +.BR sched_getaffinity (2), +.BR sched_getparam (2), +.BR sched_getscheduler (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sched_get_priority_min.2 b/man2/sched_get_priority_min.2 new file mode 100644 index 0000000..17b99f0 --- /dev/null +++ b/man2/sched_get_priority_min.2 @@ -0,0 +1 @@ +.so man2/sched_get_priority_max.2 diff --git a/man2/sched_getaffinity.2 b/man2/sched_getaffinity.2 new file mode 100644 index 0000000..f376c11 --- /dev/null +++ b/man2/sched_getaffinity.2 @@ -0,0 +1 @@ +.so man2/sched_setaffinity.2 diff --git a/man2/sched_getattr.2 b/man2/sched_getattr.2 new file mode 100644 index 0000000..cb2c346 --- /dev/null +++ b/man2/sched_getattr.2 @@ -0,0 +1 @@ +.so man2/sched_setattr.2 diff --git a/man2/sched_getparam.2 b/man2/sched_getparam.2 new file mode 100644 index 0000000..d39facd --- /dev/null +++ b/man2/sched_getparam.2 @@ -0,0 +1 @@ +.so man2/sched_setparam.2 diff --git a/man2/sched_getscheduler.2 b/man2/sched_getscheduler.2 new file mode 100644 index 0000000..13aa827 --- /dev/null +++ b/man2/sched_getscheduler.2 @@ -0,0 +1 @@ +.so man2/sched_setscheduler.2 diff --git a/man2/sched_rr_get_interval.2 b/man2/sched_rr_get_interval.2 new file mode 100644 index 0000000..011d45d --- /dev/null +++ b/man2/sched_rr_get_interval.2 @@ -0,0 +1,142 @@ +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH SCHED_RR_GET_INTERVAL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_rr_get_interval \- get the SCHED_RR interval for the named process +.SH SYNOPSIS +.B #include +.PP +.BI "int sched_rr_get_interval(pid_t " pid ", struct timespec *" tp ); +.SH DESCRIPTION +.BR sched_rr_get_interval () +writes into the +.I timespec +structure pointed to by +.I tp +the round-robin time quantum for the process identified by +.IR pid . +The specified process should be running under the +.B SCHED_RR +scheduling policy. +.PP +The +.I timespec +structure has the following form: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.PP +If +.I pid +is zero, the time quantum for the calling process is written into +.IR *tp . +.\" FIXME . On Linux, sched_rr_get_interval() +.\" returns the timeslice for SCHED_OTHER processes -- this timeslice +.\" is influenced by the nice value. +.\" For SCHED_FIFO processes, this always returns 0. +.\" +.\" The round-robin time quantum value is not alterable under Linux +.\" 1.3.81. +.\" +.SH RETURN VALUE +On success, +.BR sched_rr_get_interval () +returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Problem with copying information to user space. +.TP +.B EINVAL +Invalid pid. +.TP +.B ENOSYS +The system call is not yet implemented (only on rather old kernels). +.TP +.B ESRCH +Could not find a process with the ID +.IR pid . +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +POSIX systems on which +.BR sched_rr_get_interval () +is available define +.B _POSIX_PRIORITY_SCHEDULING +in +.IR . +.SS Linux notes +POSIX does not specify any mechanism for controlling the size of the +round-robin time quantum. +Older Linux kernels provide a (nonportable) method of doing this. +The quantum can be controlled by adjusting the process's nice value (see +.BR setpriority (2)). +Assigning a negative (i.e., high) nice value results in a longer quantum; +assigning a positive (i.e., low) nice value results in a shorter quantum. +The default quantum is 0.1 seconds; +the degree to which changing the nice value affects the +quantum has varied somewhat across kernel versions. +This method of adjusting the quantum was removed +.\" commit a4ec24b48ddef1e93f7578be53270f0b95ad666c +starting with Linux 2.6.24. +.PP +Linux 3.9 added +.\" commit ce0dbbbb30aee6a835511d5be446462388ba9eee +a new mechanism for adjusting (and viewing) the +.BR SCHED_RR +quantum: the +.I /proc/sys/kernel/sched_rr_timeslice_ms +file exposes the quantum as a millisecond value, whose default is 100. +Writing 0 to this file resets the quantum to the default value. +.\" .SH BUGS +.\" As of Linux 1.3.81 +.\" .BR sched_rr_get_interval () +.\" returns with error +.\" ENOSYS, because SCHED_RR has not yet been fully implemented and tested +.\" properly. +.SH SEE ALSO +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2 new file mode 100644 index 0000000..bb8559e --- /dev/null +++ b/man2/sched_setaffinity.2 @@ -0,0 +1,439 @@ +.\" Copyright (C) 2002 Robert Love +.\" and Copyright (C) 2006, 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2002-11-19 Robert Love - initial version +.\" 2004-04-20 mtk - fixed description of return value +.\" 2004-04-22 aeb - added glibc prototype history +.\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread +.\" migration and that CPU affinity is a per-thread attribute. +.\" 2006-02-03 mtk -- Major rewrite +.\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a +.\" separate CPU_SET(3) page. +.\" +.TH SCHED_SETAFFINITY 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_setaffinity, sched_getaffinity \- \ +set and get a thread's CPU affinity mask +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize , +.BI " const cpu_set_t *" mask ); +.PP +.BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize , +.BI " cpu_set_t *" mask ); +.fi +.SH DESCRIPTION +A thread's CPU affinity mask determines the set of CPUs on which +it is eligible to run. +On a multiprocessor system, setting the CPU affinity mask +can be used to obtain performance benefits. +For example, +by dedicating one CPU to a particular thread +(i.e., setting the affinity mask of that thread to specify a single CPU, +and setting the affinity mask of all other threads to exclude that CPU), +it is possible to ensure maximum execution speed for that thread. +Restricting a thread to run on a single CPU also avoids +the performance cost caused by the cache invalidation that occurs +when a thread ceases to execute on one CPU and then +recommences execution on a different CPU. +.PP +A CPU affinity mask is represented by the +.I cpu_set_t +structure, a "CPU set", pointed to by +.IR mask . +A set of macros for manipulating CPU sets is described in +.BR CPU_SET (3). +.PP +.BR sched_setaffinity () +sets the CPU affinity mask of the thread whose ID is +.I pid +to the value specified by +.IR mask . +If +.I pid +is zero, then the calling thread is used. +The argument +.I cpusetsize +is the length (in bytes) of the data pointed to by +.IR mask . +Normally this argument would be specified as +.IR "sizeof(cpu_set_t)" . +.PP +If the thread specified by +.I pid +is not currently running on one of the CPUs specified in +.IR mask , +then that thread is migrated to one of the CPUs specified in +.IR mask . +.PP +.BR sched_getaffinity () +writes the affinity mask of the thread whose ID is +.I pid +into the +.I cpu_set_t +structure pointed to by +.IR mask . +The +.I cpusetsize +argument specifies the size (in bytes) of +.IR mask . +If +.I pid +is zero, then the mask of the calling thread is returned. +.SH RETURN VALUE +On success, +.BR sched_setaffinity () +and +.BR sched_getaffinity () +return 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +A supplied memory address was invalid. +.TP +.B EINVAL +The affinity bit mask +.I mask +contains no processors that are currently physically on the system +and permitted to the thread according to any restrictions that +may be imposed by +.I cpuset +cgroups or the "cpuset" mechanism described in +.BR cpuset (7). +.TP +.B EINVAL +.RB ( sched_getaffinity () +and, in kernels before 2.6.9, +.BR sched_setaffinity ()) +.I cpusetsize +is smaller than the size of the affinity mask used by the kernel. +.TP +.B EPERM +.RB ( sched_setaffinity ()) +The calling thread does not have appropriate privileges. +The caller needs an effective user ID equal to the real user ID +or effective user ID of the thread identified by +.IR pid , +or it must possess the +.B CAP_SYS_NICE +capability in the user namespace of the thread +.IR pid . +.TP +.B ESRCH +The thread whose ID is \fIpid\fP could not be found. +.SH VERSIONS +The CPU affinity system calls were introduced in Linux kernel 2.5.8. +The system call wrappers were introduced in glibc 2.3. +Initially, the glibc interfaces included a +.I cpusetsize +argument, typed as +.IR "unsigned int" . +In glibc 2.3.3, the +.I cpusetsize +argument was removed, but was then restored in glibc 2.3.4, with type +.IR size_t . +.SH CONFORMING TO +These system calls are Linux-specific. +.SH NOTES +After a call to +.BR sched_setaffinity (), +the set of CPUs on which the thread will actually run is +the intersection of the set specified in the +.I mask +argument and the set of CPUs actually present on the system. +The system may further restrict the set of CPUs on which the thread +runs if the "cpuset" mechanism described in +.BR cpuset (7) +is being used. +These restrictions on the actual set of CPUs on which the thread +will run are silently imposed by the kernel. +.PP +There are various ways of determining the number of CPUs +available on the system, including: inspecting the contents of +.IR /proc/cpuinfo ; +using +.BR sysconf (3) +to obtain the values of the +.BR _SC_NPROCESSORS_CONF +and +.BR _SC_NPROCESSORS_ONLN +parameters; and inspecting the list of CPU directories under +.IR /sys/devices/system/cpu/ . +.PP +.BR sched (7) +has a description of the Linux scheduling scheme. +.PP +The affinity mask is a per-thread attribute that can be +adjusted independently for each of the threads in a thread group. +The value returned from a call to +.BR gettid (2) +can be passed in the argument +.IR pid . +Specifying +.I pid +as 0 will set the attribute for the calling thread, +and passing the value returned from a call to +.BR getpid (2) +will set the attribute for the main thread of the thread group. +(If you are using the POSIX threads API, then use +.BR pthread_setaffinity_np (3) +instead of +.BR sched_setaffinity ().) +.PP +The +.I isolcpus +boot option can be used to isolate one or more CPUs at boot time, +so that no processes are scheduled onto those CPUs. +Following the use of this boot option, +the only way to schedule processes onto the isolated CPUs is via +.BR sched_setaffinity () +or the +.BR cpuset (7) +mechanism. +For further information, see the kernel source file +.IR Documentation/admin-guide/kernel-parameters.txt . +As noted in that file, +.I isolcpus +is the preferred mechanism of isolating CPUs +(versus the alternative of manually setting the CPU affinity +of all processes on the system). +.PP +A child created via +.BR fork (2) +inherits its parent's CPU affinity mask. +The affinity mask is preserved across an +.BR execve (2). +.SS C library/kernel differences +This manual page describes the glibc interface for the CPU affinity calls. +The actual system call interface is slightly different, with the +.I mask +being typed as +.IR "unsigned long\ *" , +reflecting the fact that the underlying implementation of CPU +sets is a simple bit mask. +On success, the raw +.BR sched_getaffinity () +system call returns the size (in bytes) of the +.I cpumask_t +data type that is used internally by the kernel to +represent the CPU set bit mask. +.SS Handling systems with large CPU affinity masks +The underlying system calls (which represent CPU masks as bit masks of type +.IR "unsigned long\ *" ) +impose no restriction on the size of the CPU mask. +However, the +.I cpu_set_t +data type used by glibc has a fixed size of 128 bytes, +meaning that the maximum CPU number that can be represented is 1023. +.\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630 +.\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html +If the kernel CPU affinity mask is larger than 1024, +then calls of the form: +.PP + sched_getaffinity(pid, sizeof(cpu_set_t), &mask); +.PP +fail with the error +.BR EINVAL , +the error produced by the underlying system call for the case where the +.I mask +size specified in +.I cpusetsize +is smaller than the size of the affinity mask used by the kernel. +(Depending on the system CPU topology, the kernel affinity mask can +be substantially larger than the number of active CPUs in the system.) +.PP +When working on systems with large kernel CPU affinity masks, +one must dynamically allocate the +.I mask +argument (see +.BR CPU_ALLOC (3)). +Currently, the only way to do this is by probing for the size +of the required mask using +.BR sched_getaffinity () +calls with increasing mask sizes (until the call does not fail with the error +.BR EINVAL ). +.PP +Be aware that +.BR CPU_ALLOC (3) +may allocate a slightly larger CPU set than requested +(because CPU sets are implemented as bit masks allocated in units of +.IR sizeof(long) ). +Consequently, +.BR sched_getaffinity () +can set bits beyond the requested allocation size, because the kernel +sees a few additional bits. +Therefore, the caller should iterate over the bits in the returned set, +counting those which are set, and stop upon reaching the value returned by +.BR CPU_COUNT (3) +(rather than iterating over the number of bits +requested to be allocated). +.SH EXAMPLE +The program below creates a child process. +The parent and child then each assign themselves to a specified CPU +and execute identical loops that consume some CPU time. +Before terminating, the parent waits for the child to complete. +The program takes three command-line arguments: +the CPU number for the parent, +the CPU number for the child, +and the number of loop iterations that both processes should perform. +.PP +As the sample runs below demonstrate, the amount of real and CPU time +consumed when running the program will depend on intra-core caching effects +and whether the processes are using the same CPU. +.PP +We first employ +.BR lscpu (1) +to determine that this (x86) +system has two cores, each with two CPUs: +.PP +.in +4n +.EX +$ \fBlscpu | grep -i 'core.*:|socket'\fP +Thread(s) per core: 2 +Core(s) per socket: 2 +Socket(s): 1 +.EE +.in +.PP +We then time the operation of the example program for three cases: +both processes running on the same CPU; +both processes running on different CPUs on the same core; +and both processes running on different CPUs on different cores. +.PP +.in +4n +.EX +$ \fBtime \-p ./a.out 0 0 100000000\fP +real 14.75 +user 3.02 +sys 11.73 +$ \fBtime \-p ./a.out 0 1 100000000\fP +real 11.52 +user 3.98 +sys 19.06 +$ \fBtime \-p ./a.out 0 3 100000000\fP +real 7.89 +user 3.29 +sys 12.07 +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + cpu_set_t set; + int parentCPU, childCPU; + int nloops, j; + + if (argc != 4) { + fprintf(stderr, "Usage: %s parent\-cpu child\-cpu num\-loops\\n", + argv[0]); + exit(EXIT_FAILURE); + } + + parentCPU = atoi(argv[1]); + childCPU = atoi(argv[2]); + nloops = atoi(argv[3]); + + CPU_ZERO(&set); + + switch (fork()) { + case \-1: /* Error */ + errExit("fork"); + + case 0: /* Child */ + CPU_SET(childCPU, &set); + + if (sched_setaffinity(getpid(), sizeof(set), &set) == \-1) + errExit("sched_setaffinity"); + + for (j = 0; j < nloops; j++) + getppid(); + + exit(EXIT_SUCCESS); + + default: /* Parent */ + CPU_SET(parentCPU, &set); + + if (sched_setaffinity(getpid(), sizeof(set), &set) == \-1) + errExit("sched_setaffinity"); + + for (j = 0; j < nloops; j++) + getppid(); + + wait(NULL); /* Wait for child to terminate */ + exit(EXIT_SUCCESS); + } +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR lscpu (1), +.BR nproc (1), +.BR taskset (1), +.BR clone (2), +.BR getcpu (2), +.BR getpriority (2), +.BR gettid (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getscheduler (2), +.BR sched_setscheduler (2), +.BR setpriority (2), +.BR CPU_SET (3), +.BR get_nprocs (3), +.BR pthread_setaffinity_np (3), +.BR sched_getcpu (3), +.BR capabilities (7), +.BR cpuset (7), +.BR sched (7), +.BR numactl (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sched_setattr.2 b/man2/sched_setattr.2 new file mode 100644 index 0000000..999809c --- /dev/null +++ b/man2/sched_setattr.2 @@ -0,0 +1,417 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 Peter Zijlstra +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SCHED_SETATTR 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_setattr, sched_getattr \- +set and get scheduling policy and attributes +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sched_setattr(pid_t " pid ", struct sched_attr *" attr , +.BI " unsigned int " flags ); +.PP +.BI "int sched_getattr(pid_t " pid ", struct sched_attr *" attr , +.BI " unsigned int " size ", unsigned int " flags ); +.fi +.\" FIXME . Add feature test macro requirements +.SH DESCRIPTION +.SS sched_setattr() +The +.BR sched_setattr () +system call sets the scheduling policy and +associated attributes for the thread whose ID is specified in +.IR pid . +If +.I pid +equals zero, +the scheduling policy and attributes of the calling thread will be set. +.PP +Currently, Linux supports the following "normal" +(i.e., non-real-time) scheduling policies as values that may be specified in +.IR policy : +.TP 14 +.BR SCHED_OTHER +the standard round-robin time-sharing policy; +.\" In the 2.6 kernel sources, SCHED_OTHER is actually called +.\" SCHED_NORMAL. +.TP +.BR SCHED_BATCH +for "batch" style execution of processes; and +.TP +.BR SCHED_IDLE +for running +.I very +low priority background jobs. +.PP +Various "real-time" policies are also supported, +for special time-critical applications that need precise control over +the way in which runnable threads are selected for execution. +For the rules governing when a process may use these policies, see +.BR sched (7). +The real-time policies that may be specified in +.IR policy +are: +.TP 14 +.BR SCHED_FIFO +a first-in, first-out policy; and +.TP +.BR SCHED_RR +a round-robin policy. +.PP +Linux also provides the following policy: +.TP 14 +.B SCHED_DEADLINE +a deadline scheduling policy; see +.BR sched (7) +for details. +.PP +The +.I attr +argument is a pointer to a structure that defines +the new scheduling policy and attributes for the specified thread. +This structure has the following form: +.PP +.in +4n +.EX +struct sched_attr { + u32 size; /* Size of this structure */ + u32 sched_policy; /* Policy (SCHED_*) */ + u64 sched_flags; /* Flags */ + s32 sched_nice; /* Nice value (SCHED_OTHER, + SCHED_BATCH) */ + u32 sched_priority; /* Static priority (SCHED_FIFO, + SCHED_RR) */ + /* Remaining fields are for SCHED_DEADLINE */ + u64 sched_runtime; + u64 sched_deadline; + u64 sched_period; +}; +.EE +.in +.PP +The fields of this structure are as follows: +.TP +.B size +This field should be set to the size of the structure in bytes, as in +.IR "sizeof(struct sched_attr)" . +If the provided structure is smaller than the kernel structure, +any additional fields are assumed to be '0'. +If the provided structure is larger than the kernel structure, +the kernel verifies that all additional fields are 0; +if they are not, +.BR sched_setattr () +fails with the error +.BR E2BIG +and updates +.I size +to contain the size of the kernel structure. +.IP +The above behavior when the size of the user-space +.I sched_attr +structure does not match the size of the kernel structure +allows for future extensibility of the interface. +Malformed applications that pass oversize structures +won't break in the future if the size of the kernel +.I sched_attr +structure is increased. +In the future, +it could also allow applications that know about a larger user-space +.I sched_attr +structure to determine whether they are running on an older kernel +that does not support the larger structure. +.TP +.I sched_policy +This field specifies the scheduling policy, as one of the +.BR SCHED_* +values listed above. +.TP +.I sched_flags +This field contains flags controlling scheduling behavior. +Only one such flag is currently defined: +.BR SCHED_FLAG_RESET_ON_FORK . +As a result of including this flag, children created by +.BR fork (2) +do not inherit privileged scheduling policies. +See +.BR sched (7) +for details. +.TP +.I sched_nice +This field specifies the nice value to be set when specifying +.IR sched_policy +as +.BR SCHED_OTHER +or +.BR SCHED_BATCH . +The nice value is a number in the range \-20 (high priority) +to +19 (low priority); see +.BR sched (7). +.TP +.I sched_priority +This field specifies the static priority to be set when specifying +.IR sched_policy +as +.BR SCHED_FIFO +or +.BR SCHED_RR . +The allowed range of priorities for these policies can be determined using +.BR sched_get_priority_min (2) +and +.BR sched_get_priority_max (2). +For other policies, this field must be specified as 0. +.TP +.I sched_runtime +This field specifies the "Runtime" parameter for deadline scheduling. +The value is expressed in nanoseconds. +This field, and the next two fields, +are used only for +.BR SCHED_DEADLINE +scheduling; for further details, see +.BR sched (7). +.TP +.I sched_deadline +This field specifies the "Deadline" parameter for deadline scheduling. +The value is expressed in nanoseconds. +.TP +.I sched_period +This field specifies the "Period" parameter for deadline scheduling. +The value is expressed in nanoseconds. +.PP +The +.I flags +argument is provided to allow for future extensions to the interface; +in the current implementation it must be specified as 0. +.\" +.\" +.SS sched_getattr() +The +.BR sched_getattr () +system call fetches the scheduling policy and the +associated attributes for the thread whose ID is specified in +.IR pid . +If +.I pid +equals zero, +the scheduling policy and attributes of the calling thread +will be retrieved. +.PP +The +.I size +argument should be set to the size of the +.I sched_attr +structure as known to user space. +The value must be at least as large as the size of the initially published +.I sched_attr +structure, or the call fails with the error +.BR EINVAL . +.PP +The retrieved scheduling attributes are placed in the fields of the +.I sched_attr +structure pointed to by +.IR attr . +The kernel sets +.I attr.size +to the size of its +.I sched_attr +structure. +.PP +If the caller-provided +.I attr +buffer is larger than the kernel's +.I sched_attr +structure, +the additional bytes in the user-space structure are not touched. +If the caller-provided structure is smaller than the kernel +.I sched_attr +structure and the kernel needs to return values outside the provided space, +.BR sched_getattr () +fails with the error +.BR E2BIG . +As with +.BR sched_setattr (), +these semantics allow for future extensibility of the interface. +.PP +The +.I flags +argument is provided to allow for future extensions to the interface; +in the current implementation it must be specified as 0. +.SH RETURN VALUE +On success, +.BR sched_setattr () +and +.BR sched_getattr () +return 0. +On error, \-1 is returned, and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.BR sched_getattr () +and +.BR sched_setattr () +can both fail for the following reasons: +.TP +.B EINVAL +.I attr +is NULL; or +.I pid +is negative; or +.I flags +is not zero. +.TP +.B ESRCH +The thread whose ID is +.I pid +could not be found. +.PP +In addition, +.BR sched_getattr () +can fail for the following reasons: +.TP +.B E2BIG +The buffer specified by +.I size +and +.I attr +is too small. +.TP +.B EINVAL +.I size +is invalid; that is, it is smaller than the initial version of the +.I sched_attr +structure (48 bytes) or larger than the system page size. +.PP +In addition, +.BR sched_setattr () +can fail for the following reasons: +.TP +.B E2BIG +The buffer specified by +.I size +and +.I attr +is larger than the kernel structure, +and one or more of the excess bytes is nonzero. +.TP +.B EBUSY +.B SCHED_DEADLINE +admission control failure, see +.BR sched (7). +.TP +.B EINVAL +.I attr.sched_policy +is not one of the recognized policies; +.I attr.sched_flags +contains a flag other than +.BR SCHED_FLAG_RESET_ON_FORK ; +or +.I attr.sched_priority +is invalid; or +.I attr.sched_policy +is +.BR SCHED_DEADLINE +and the deadline scheduling parameters in +.I attr +are invalid. +.TP +.B EPERM +The caller does not have appropriate privileges. +.TP +.B EPERM +The CPU affinity mask of the thread specified by +.I pid +does not include all CPUs in the system +(see +.BR sched_setaffinity (2)). +.SH VERSIONS +These system calls first appeared in Linux 3.14. +.\" FIXME . Add glibc version +.SH CONFORMING TO +These system calls are nonstandard Linux extensions. +.SH NOTES +.BR sched_setattr () +provides a superset of the functionality of +.BR sched_setscheduler (2), +.BR sched_setparam (2), +.BR nice (2), +and (other than the ability to set the priority of all processes +belonging to a specified user or all processes in a specified group) +.BR setpriority (2). +Analogously, +.BR sched_getattr () +provides a superset of the functionality of +.BR sched_getscheduler (2), +.BR sched_getparam (2), +and (partially) +.BR getpriority (2). +.SH BUGS +In Linux versions up to +.\" FIXME . patch sent to Peter Zijlstra +3.15, +.BR sched_settattr () +failed with the error +.BR EFAULT +instead of +.BR E2BIG +for the case described in ERRORS. +.\" In Linux versions up to up 3.15, +.\" FIXME . patch from Peter Zijlstra pending +.\" .BR sched_setattr () +.\" allowed a negative +.\" .I attr.sched_policy +.\" value. +.SH SEE ALSO +.ad l +.nh +.BR chrt (1), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getparam (2), +.BR sched_getscheduler (2), +.BR sched_rr_get_interval (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR sched_yield (2), +.BR setpriority (2), +.BR pthread_getschedparam (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR capabilities (7), +.BR cpuset (7), +.BR sched (7) +.ad +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sched_setparam.2 b/man2/sched_setparam.2 new file mode 100644 index 0000000..ca61478 --- /dev/null +++ b/man2/sched_setparam.2 @@ -0,0 +1,150 @@ +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH SCHED_SETPARAM 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_setparam, sched_getparam \- set and get scheduling parameters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sched_setparam(pid_t " pid ", const struct sched_param *" param ); +.PP +.BI "int sched_getparam(pid_t " pid ", struct sched_param *" param ); +.PP +\fBstruct sched_param { + ... + int \fIsched_priority\fB; + ... +}; +.fi +.SH DESCRIPTION +.BR sched_setparam () +sets the scheduling parameters associated with the scheduling policy +for the process identified by \fIpid\fP. +If \fIpid\fP is zero, then +the parameters of the calling process are set. +The interpretation of +the argument \fIparam\fP depends on the scheduling +policy of the process identified by +.IR pid . +See +.BR sched (7) +for a description of the scheduling policies supported under Linux. +.PP +.BR sched_getparam () +retrieves the scheduling parameters for the +process identified by \fIpid\fP. +If \fIpid\fP is zero, then the parameters +of the calling process are retrieved. +.PP +.BR sched_setparam () +checks the validity of \fIparam\fP for the scheduling policy of the +thread. +The value \fIparam\->sched_priority\fP must lie within the +range given by +.BR sched_get_priority_min (2) +and +.BR sched_get_priority_max (2). +.PP +For a discussion of the privileges and resource limits related to +scheduling priority and policy, see +.BR sched (7). +.PP +POSIX systems on which +.BR sched_setparam () +and +.BR sched_getparam () +are available define +.B _POSIX_PRIORITY_SCHEDULING +in \fI\fP. +.SH RETURN VALUE +On success, +.BR sched_setparam () +and +.BR sched_getparam () +return 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +Invalid arguments: +.I param +is NULL or +.I pid +is negative +.TP +.B EINVAL +.RB ( sched_setparam ()) +The argument \fIparam\fP does not make sense for the current +scheduling policy. +.TP +.B EPERM +.RB ( sched_setparam ()) +The calling process does not have appropriate privileges +(Linux: does not have the +.B CAP_SYS_NICE +capability). +.TP +.B ESRCH +The process whose ID is \fIpid\fP could not be found. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +.PP +Scheduling parameters are in fact per-thread +attributes on Linux; +see +.BR sched (7). +.SH SEE ALSO +.ad l +.nh +.BR getpriority (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getscheduler (2), +.BR sched_setaffinity (2), +.BR sched_setattr (2), +.BR sched_setscheduler (2), +.BR setpriority (2), +.BR capabilities (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2 new file mode 100644 index 0000000..dc76245 --- /dev/null +++ b/man2/sched_setscheduler.2 @@ -0,0 +1,253 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH SCHED_SETSCHEDULER 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_setscheduler, sched_getscheduler \- +set and get scheduling policy/parameters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sched_setscheduler(pid_t " pid ", int " policy , +.BI " const struct sched_param *" param ); +.PP +.BI "int sched_getscheduler(pid_t " pid ); +.fi +.SH DESCRIPTION +The +.BR sched_setscheduler () +system call +sets both the scheduling policy and parameters for the +thread whose ID is specified in \fIpid\fP. +If \fIpid\fP equals zero, the +scheduling policy and parameters of the calling thread will be set. +.PP +The scheduling parameters are specified in the +.I param +argument, which is a pointer to a structure of the following form: +.PP +.in +4n +.EX +struct sched_param { + ... + int sched_priority; + ... +}; +.EE +.in +.PP +In the current implementation, the structure contains only one field, +.IR sched_priority . +The interpretation of +.I param +depends on the selected policy. +.PP +Currently, Linux supports the following "normal" +(i.e., non-real-time) scheduling policies as values that may be specified in +.IR policy : +.TP 14 +.BR SCHED_OTHER +the standard round-robin time-sharing policy; +.\" In the 2.6 kernel sources, SCHED_OTHER is actually called +.\" SCHED_NORMAL. +.TP +.BR SCHED_BATCH +for "batch" style execution of processes; and +.TP +.BR SCHED_IDLE +for running +.I very +low priority background jobs. +.PP +For each of the above policies, +.IR param\->sched_priority +must be 0. +.PP +Various "real-time" policies are also supported, +for special time-critical applications that need precise control over +the way in which runnable threads are selected for execution. +For the rules governing when a process may use these policies, see +.BR sched (7). +The real-time policies that may be specified in +.IR policy +are: +.TP 14 +.BR SCHED_FIFO +a first-in, first-out policy; and +.TP +.BR SCHED_RR +a round-robin policy. +.PP +For each of the above policies, +.IR param\->sched_priority +specifies a scheduling priority for the thread. +This is a number in the range returned by calling +.BR sched_get_priority_min (2) +and +.BR sched_get_priority_max (2) +with the specified +.IR policy . +On Linux, these system calls return, respectively, 1 and 99. +.PP +Since Linux 2.6.32, the +.B SCHED_RESET_ON_FORK +flag can be ORed in +.I policy +when calling +.BR sched_setscheduler (). +As a result of including this flag, children created by +.BR fork (2) +do not inherit privileged scheduling policies. +See +.BR sched (7) +for details. +.PP +.BR sched_getscheduler () +returns the current scheduling policy of the thread +identified by \fIpid\fP. +If \fIpid\fP equals zero, the policy of the +calling thread will be retrieved. +.SH RETURN VALUE +On success, +.BR sched_setscheduler () +returns zero. +On success, +.BR sched_getscheduler () +returns the policy for the thread (a nonnegative integer). +On error, both calls return \-1, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +Invalid arguments: +.I pid +is negative or +.I param +is NULL. +.TP +.B EINVAL +.RB ( sched_setscheduler ()) +.I policy +is not one of the recognized policies. +.TP +.B EINVAL +.RB ( sched_setscheduler ()) +.I param +does not make sense for the specified +.IR policy . +.TP +.B EPERM +The calling thread does not have appropriate privileges. +.TP +.B ESRCH +The thread whose ID is \fIpid\fP could not be found. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008 (but see BUGS below). +The \fBSCHED_BATCH\fP and \fBSCHED_IDLE\fP policies are Linux-specific. +.SH NOTES +Further details of the semantics of all of the above "normal" +and "real-time" scheduling policies can be found in the +.BR sched (7) +manual page. +That page also describes an additional policy, +.BR SCHED_DEADLINE , +which is settable only via +.BR sched_setattr (2). +.PP +POSIX systems on which +.BR sched_setscheduler () +and +.BR sched_getscheduler () +are available define +.B _POSIX_PRIORITY_SCHEDULING +in \fI\fP. +.PP +POSIX.1 does not detail the permissions that an unprivileged +thread requires in order to call +.BR sched_setscheduler (), +and details vary across systems. +For example, the Solaris 7 manual page says that +the real or effective user ID of the caller must +match the real user ID or the save set-user-ID of the target. +.PP +The scheduling policy and parameters are in fact per-thread +attributes on Linux. +The value returned from a call to +.BR gettid (2) +can be passed in the argument +.IR pid . +Specifying +.I pid +as 0 will operate on the attributes of the calling thread, +and passing the value returned from a call to +.BR getpid (2) +will operate on the attributes of the main thread of the thread group. +(If you are using the POSIX threads API, then use +.BR pthread_setschedparam (3), +.BR pthread_getschedparam (3), +and +.BR pthread_setschedprio (3), +instead of the +.BR sched_* (2) +system calls.) +.SH BUGS +POSIX.1 says that on success, +.BR sched_setscheduler () +should return the previous scheduling policy. +Linux +.BR sched_setscheduler () +does not conform to this requirement, +since it always returns 0 on success. +.SH SEE ALSO +.ad l +.nh +.BR chrt (1), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getattr (2), +.BR sched_getparam (2), +.BR sched_rr_get_interval (2), +.BR sched_setaffinity (2), +.BR sched_setattr (2), +.BR sched_setparam (2), +.BR sched_yield (2), +.BR setpriority (2), +.BR capabilities (7), +.BR cpuset (7), +.BR sched (7) +.ad +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sched_yield.2 b/man2/sched_yield.2 new file mode 100644 index 0000000..1cb773c --- /dev/null +++ b/man2/sched_yield.2 @@ -0,0 +1,100 @@ +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH SCHED_YIELD 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_yield \- yield the processor +.SH SYNOPSIS +.B #include +.PP +.B int sched_yield(void); +.SH DESCRIPTION +.BR sched_yield () +causes the calling thread to relinquish the CPU. +The thread is moved to the end of the queue for its static +priority and a new thread gets to run. +.SH RETURN VALUE +On success, +.BR sched_yield () +returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +In the Linux implementation, +.BR sched_yield () +always succeeds. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +If the calling thread is the only thread in the highest +priority list at that time, +it will continue to run after a call to +.BR sched_yield (). +.PP +POSIX systems on which +.BR sched_yield () +is available define +.B _POSIX_PRIORITY_SCHEDULING +in +.IR . +.PP +Strategic calls to +.BR sched_yield () +can improve performance by giving other threads or processes +a chance to run when (heavily) contended resources (e.g., mutexes) +have been released by the caller. +Avoid calling +.BR sched_yield () +unnecessarily or inappropriately +(e.g., when resources needed by other +schedulable threads are still held by the caller), +since doing so will result in unnecessary context switches, +which will degrade system performance. +.PP +.BR sched_yield () +is intended for use with read-time scheduling policies (i.e., +.BR SCHED_FIFO +or +.BR SCHED_RR ). +Use of +.BR sched_yield () +with nondeterministic scheduling policies such as +.BR SCHED_OTHER +is unspecified and very likely means your application design is broken. +.SH SEE ALSO +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/seccomp.2 b/man2/seccomp.2 new file mode 100644 index 0000000..055634b --- /dev/null +++ b/man2/seccomp.2 @@ -0,0 +1,1109 @@ +.\" Copyright (C) 2014 Kees Cook +.\" and Copyright (C) 2012 Will Drewry +.\" and Copyright (C) 2008, 2014,2017 Michael Kerrisk +.\" and Copyright (C) 2017 Tyler Hicks +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SECCOMP 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +seccomp \- operate on Secure Computing state of the process +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.\" Kees Cook noted: Anything that uses SECCOMP_RET_TRACE returns will +.\" need +.PP +.BI "int seccomp(unsigned int " operation ", unsigned int " flags \ +", void *" args ); +.fi +.SH DESCRIPTION +The +.BR seccomp () +system call operates on the Secure Computing (seccomp) state of the +calling process. +.PP +Currently, Linux supports the following +.IR operation +values: +.TP +.BR SECCOMP_SET_MODE_STRICT +The only system calls that the calling thread is permitted to make are +.BR read (2), +.BR write (2), +.BR _exit (2) +(but not +.BR exit_group (2)), +and +.BR sigreturn (2). +Other system calls result in the delivery of a +.BR SIGKILL +signal. +Strict secure computing mode is useful for number-crunching +applications that may need to execute untrusted byte code, perhaps +obtained by reading from a pipe or socket. +.IP +Note that although the calling thread can no longer call +.BR sigprocmask (2), +it can use +.BR sigreturn (2) +to block all signals apart from +.BR SIGKILL +and +.BR SIGSTOP . +This means that +.BR alarm (2) +(for example) is not sufficient for restricting the process's execution time. +Instead, to reliably terminate the process, +.BR SIGKILL +must be used. +This can be done by using +.BR timer_create (2) +with +.BR SIGEV_SIGNAL +and +.IR sigev_signo +set to +.BR SIGKILL , +or by using +.BR setrlimit (2) +to set the hard limit for +.BR RLIMIT_CPU . +.IP +This operation is available only if the kernel is configured with +.BR CONFIG_SECCOMP +enabled. +.IP +The value of +.IR flags +must be 0, and +.IR args +must be NULL. +.IP +This operation is functionally identical to the call: +.IP + prctl(PR_SET_SECCOMP, SECCOMP_MODE_STRICT); +.TP +.BR SECCOMP_SET_MODE_FILTER +The system calls allowed are defined by a pointer to a Berkeley Packet +Filter (BPF) passed via +.IR args . +This argument is a pointer to a +.IR "struct\ sock_fprog" ; +it can be designed to filter arbitrary system calls and system call +arguments. +If the filter is invalid, +.BR seccomp () +fails, returning +.BR EINVAL +in +.IR errno . +.IP +If +.BR fork (2) +or +.BR clone (2) +is allowed by the filter, any child processes will be constrained to +the same system call filters as the parent. +If +.BR execve (2) +is allowed, +the existing filters will be preserved across a call to +.BR execve (2). +.IP +In order to use the +.BR SECCOMP_SET_MODE_FILTER +operation, either the caller must have the +.BR CAP_SYS_ADMIN +capability in its user namespace, or the thread must already have the +.I no_new_privs +bit set. +If that bit was not already set by an ancestor of this thread, +the thread must make the following call: +.IP + prctl(PR_SET_NO_NEW_PRIVS, 1); +.IP +Otherwise, the +.BR SECCOMP_SET_MODE_FILTER +operation fails and returns +.BR EACCES +in +.IR errno . +This requirement ensures that an unprivileged process cannot apply +a malicious filter and then invoke a set-user-ID or +other privileged program using +.BR execve (2), +thus potentially compromising that program. +(Such a malicious filter might, for example, cause an attempt to use +.BR setuid (2) +to set the caller's user IDs to nonzero values to instead +return 0 without actually making the system call. +Thus, the program might be tricked into retaining superuser privileges +in circumstances where it is possible to influence it to do +dangerous things because it did not actually drop privileges.) +.IP +If +.BR prctl (2) +or +.BR seccomp () +is allowed by the attached filter, further filters may be added. +This will increase evaluation time, but allows for further reduction of +the attack surface during execution of a thread. +.IP +The +.BR SECCOMP_SET_MODE_FILTER +operation is available only if the kernel is configured with +.BR CONFIG_SECCOMP_FILTER +enabled. +.IP +When +.IR flags +is 0, this operation is functionally identical to the call: +.IP + prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, args); +.IP +The recognized +.IR flags +are: +.RS +.TP +.BR SECCOMP_FILTER_FLAG_TSYNC +When adding a new filter, synchronize all other threads of the calling +process to the same seccomp filter tree. +A "filter tree" is the ordered list of filters attached to a thread. +(Attaching identical filters in separate +.BR seccomp () +calls results in different filters from this perspective.) +.IP +If any thread cannot synchronize to the same filter tree, +the call will not attach the new seccomp filter, +and will fail, returning the first thread ID found that cannot synchronize. +Synchronization will fail if another thread in the same process is in +.BR SECCOMP_MODE_STRICT +or if it has attached new seccomp filters to itself, +diverging from the calling thread's filter tree. +.TP +.BR SECCOMP_FILTER_FLAG_LOG " (since Linux 4.14)" +.\" commit e66a39977985b1e69e17c4042cb290768eca9b02 +All filter return actions except +.BR SECCOMP_RET_ALLOW +should be logged. +An administrator may override this filter flag by preventing specific +actions from being logged via the +.IR /proc/sys/kernel/seccomp/actions_logged +file. +.RE +.TP +.BR SECCOMP_GET_ACTION_AVAIL " (since Linux 4.14)" +.\" commit d612b1fd8010d0d67b5287fe146b8b55bcbb8655 +Test to see if an action is supported by the kernel. +This operation is helpful to confirm that the kernel knows +of a more recently added filter return action +since the kernel treats all unknown actions as +.BR SECCOMP_RET_KILL_PROCESS . +.IP +The value of +.IR flags +must be 0, and +.IR args +must be a pointer to an unsigned 32-bit filter return action. +.SS Filters +When adding filters via +.BR SECCOMP_SET_MODE_FILTER , +.IR args +points to a filter program: +.PP +.in +4n +.EX +struct sock_fprog { + unsigned short len; /* Number of BPF instructions */ + struct sock_filter *filter; /* Pointer to array of + BPF instructions */ +}; +.EE +.in +.PP +Each program must contain one or more BPF instructions: +.PP +.in +4n +.EX +struct sock_filter { /* Filter block */ + __u16 code; /* Actual filter code */ + __u8 jt; /* Jump true */ + __u8 jf; /* Jump false */ + __u32 k; /* Generic multiuse field */ +}; +.EE +.in +.PP +When executing the instructions, the BPF program operates on the +system call information made available (i.e., use the +.BR BPF_ABS +addressing mode) as a (read-only) +.\" Quoting Kees Cook: +.\" If BPF even allows changing the data, it's not copied back to +.\" the syscall when it runs. Anything wanting to do things like +.\" that would need to use ptrace to catch the call and directly +.\" modify the registers before continuing with the call. +buffer of the following form: +.PP +.in +4n +.EX +struct seccomp_data { + int nr; /* System call number */ + __u32 arch; /* AUDIT_ARCH_* value + (see ) */ + __u64 instruction_pointer; /* CPU instruction pointer */ + __u64 args[6]; /* Up to 6 system call arguments */ +}; +.EE +.in +.PP +Because numbering of system calls varies between architectures and +some architectures (e.g., x86-64) allow user-space code to use +the calling conventions of multiple architectures, it is usually +necessary to verify the value of the +.IR arch +field. +.PP +It is strongly recommended to use a whitelisting approach whenever +possible because such an approach is more robust and simple. +A blacklist will have to be updated whenever a potentially +dangerous system call is added (or a dangerous flag or option if those +are blacklisted), and it is often possible to alter the +representation of a value without altering its meaning, leading to +a blacklist bypass. +See also +.IR Caveats +below. +.PP +The +.IR arch +field is not unique for all calling conventions. +The x86-64 ABI and the x32 ABI both use +.BR AUDIT_ARCH_X86_64 +as +.IR arch , +and they run on the same processors. +Instead, the mask +.BR __X32_SYSCALL_BIT +is used on the system call number to tell the two ABIs apart. +.\" As noted by Dave Drysdale in a note at the end of +.\" https://lwn.net/Articles/604515/ +.\" One additional detail to point out for the x32 ABI case: +.\" the syscall number gets a high bit set (__X32_SYSCALL_BIT), +.\" to mark it as an x32 call. +.\" +.\" If x32 support is included in the kernel, then __SYSCALL_MASK +.\" will have a value that is not all-ones, and this will trigger +.\" an extra instruction in system_call to mask off the extra bit, +.\" so that the syscall table indexing still works. +.PP +This means that in order to create a seccomp-based +blacklist for system calls performed through the x86-64 ABI, +it is necessary to not only check that +.IR arch +equals +.BR AUDIT_ARCH_X86_64 , +but also to explicitly reject all system calls that contain +.BR __X32_SYSCALL_BIT +in +.IR nr . +.PP +The +.I instruction_pointer +field provides the address of the machine-language instruction that +performed the system call. +This might be useful in conjunction with the use of +.I /proc/[pid]/maps +to perform checks based on which region (mapping) of the program +made the system call. +(Probably, it is wise to lock down the +.BR mmap (2) +and +.BR mprotect (2) +system calls to prevent the program from subverting such checks.) +.PP +When checking values from +.IR args +against a blacklist, keep in mind that arguments are often +silently truncated before being processed, but after the seccomp check. +For example, this happens if the i386 ABI is used on an +x86-64 kernel: although the kernel will normally not look beyond +the 32 lowest bits of the arguments, the values of the full +64-bit registers will be present in the seccomp data. +A less surprising example is that if the x86-64 ABI is used to perform +a system call that takes an argument of type +.IR int , +the more-significant half of the argument register is ignored by +the system call, but visible in the seccomp data. +.PP +A seccomp filter returns a 32-bit value consisting of two parts: +the most significant 16 bits +(corresponding to the mask defined by the constant +.BR SECCOMP_RET_ACTION_FULL ) +contain one of the "action" values listed below; +the least significant 16-bits (defined by the constant +.BR SECCOMP_RET_DATA ) +are "data" to be associated with this return value. +.PP +If multiple filters exist, they are \fIall\fP executed, +in reverse order of their addition to the filter tree\(emthat is, +the most recently installed filter is executed first. +(Note that all filters will be called +even if one of the earlier filters returns +.BR SECCOMP_RET_KILL . +This is done to simplify the kernel code and to provide a +tiny speed-up in the execution of sets of filters by +avoiding a check for this uncommon case.) +.\" From an Aug 2015 conversation with Kees Cook where I asked why *all* +.\" filters are applied even if one of the early filters returns +.\" SECCOMP_RET_KILL: +.\" +.\" It's just because it would be an optimization that would only speed up +.\" the RET_KILL case, but it's the uncommon one and the one that doesn't +.\" benefit meaningfully from such a change (you need to kill the process +.\" really quickly?). We would speed up killing a program at the (albeit +.\" tiny) expense to all other filtered programs. Best to keep the filter +.\" execution logic clear, simple, and as fast as possible for all +.\" filters. +The return value for the evaluation of a given system call is the first-seen +action value of highest precedence (along with its accompanying data) +returned by execution of all of the filters. +.PP +In decreasing order of precedence, +the action values that may be returned by a seccomp filter are: +.TP +.BR SECCOMP_RET_KILL_PROCESS " (since Linux 4.14)" +.\" commit 4d3b0b05aae9ee9ce0970dc4cc0fb3fad5e85945 +.\" commit 0466bdb99e8744bc9befa8d62a317f0fd7fd7421 +This value results in immediate termination of the process, +with a core dump. +The system call is not executed. +By contrast with +.BR SECCOMP_RET_KILL_THREAD +below, all threads in the thread group are terminated. +(For a discussion of thread groups, see the description of the +.BR CLONE_THREAD +flag in +.BR clone (2).) +.IP +The process terminates +.I "as though" +killed by a +.B SIGSYS +signal. +Even if a signal handler has been registered for +.BR SIGSYS , +the handler will be ignored in this case and the process always terminates. +To a parent process that is waiting on this process (using +.BR waitpid (2) +or similar), the returned +.I wstatus +will indicate that its child was terminated as though by a +.BR SIGSYS +signal. +.TP +.BR SECCOMP_RET_KILL_THREAD " (or " SECCOMP_RET_KILL ) +This value results in immediate termination of the thread +that made the system call. +The system call is not executed. +Other threads in the same thread group will continue to execute. +.IP +The thread terminates +.I "as though" +killed by a +.B SIGSYS +signal. +See +.BR SECCOMP_RET_KILL_PROCESS +above. +.IP +.\" See these commits: +.\" seccomp: dump core when using SECCOMP_RET_KILL +.\" (b25e67161c295c98acda92123b2dd1e7d8642901) +.\" seccomp: Only dump core when single-threaded +.\" (d7276e321ff8a53106a59c85ca46d03e34288893) +Before Linux 4.11, +any process terminated in this way would not trigger a coredump +(even though +.B SIGSYS +is documented in +.BR signal (7) +as having a default action of termination with a core dump). +Since Linux 4.11, +a single-threaded process will dump core if terminated in this way. +.IP +With the addition of +.BR SECCOMP_RET_KILL_PROCESS +in Linux 4.14, +.BR SECCOMP_RET_KILL_THREAD +was added as a synonym for +.BR SECCOMP_RET_KILL , +in order to more clearly distinguish the two actions. +.TP +.BR SECCOMP_RET_TRAP +This value results in the kernel sending a thread-directed +.BR SIGSYS +signal to the triggering thread. +(The system call is not executed.) +Various fields will be set in the +.I siginfo_t +structure (see +.BR sigaction (2)) +associated with signal: +.RS +.IP * 3 +.I si_signo +will contain +.BR SIGSYS . +.IP * +.IR si_call_addr +will show the address of the system call instruction. +.IP * +.IR si_syscall +and +.IR si_arch +will indicate which system call was attempted. +.IP * +.I si_code +will contain +.BR SYS_SECCOMP . +.IP * +.I si_errno +will contain the +.BR SECCOMP_RET_DATA +portion of the filter return value. +.RE +.IP +The program counter will be as though the system call happened +(i.e., the program counter will not point to the system call instruction). +The return value register will contain an architecture\-dependent value; +if resuming execution, set it to something appropriate for the system call. +(The architecture dependency is because replacing it with +.BR ENOSYS +could overwrite some useful information.) +.TP +.BR SECCOMP_RET_ERRNO +This value results in the +.B SECCOMP_RET_DATA +portion of the filter's return value being passed to user space as the +.IR errno +value without executing the system call. +.TP +.BR SECCOMP_RET_TRACE +When returned, this value will cause the kernel to attempt to notify a +.BR ptrace (2)-based +tracer prior to executing the system call. +If there is no tracer present, +the system call is not executed and returns a failure status with +.I errno +set to +.BR ENOSYS . +.IP +A tracer will be notified if it requests +.BR PTRACE_O_TRACESECCOMP +using +.IR ptrace(PTRACE_SETOPTIONS) . +The tracer will be notified of a +.BR PTRACE_EVENT_SECCOMP +and the +.BR SECCOMP_RET_DATA +portion of the filter's return value will be available to the tracer via +.BR PTRACE_GETEVENTMSG . +.IP +The tracer can skip the system call by changing the system call number +to \-1. +Alternatively, the tracer can change the system call +requested by changing the system call to a valid system call number. +If the tracer asks to skip the system call, then the system call will +appear to return the value that the tracer puts in the return value register. +.IP +.\" This was changed in ce6526e8afa4. +.\" A related hole, using PTRACE_SYSCALL instead of SECCOMP_RET_TRACE, was +.\" changed in arch-specific commits, e.g. 93e35efb8de4 for X86 and +.\" 0f3912fd934c for ARM. +Before kernel 4.8, the seccomp check will not be run again after the tracer is +notified. +(This means that, on older kernels, seccomp-based sandboxes +.B "must not" +allow use of +.BR ptrace (2)\(emeven +of other +sandboxed processes\(emwithout extreme care; +ptracers can use this mechanism to escape from the seccomp sandbox.) +.TP +.BR SECCOMP_RET_LOG " (since Linux 4.14)" +.\" commit 59f5cf44a38284eb9e76270c786fb6cc62ef8ac4 +This value results in the system call being executed after +the filter return action is logged. +An administrator may override the logging of this action via +the +.IR /proc/sys/kernel/seccomp/actions_logged +file. +.TP +.BR SECCOMP_RET_ALLOW +This value results in the system call being executed. +.PP +If an action value other than one of the above is specified, +then the filter action is treated as either +.BR SECCOMP_RET_KILL_PROCESS +(since Linux 4.14) +.\" commit 4d3b0b05aae9ee9ce0970dc4cc0fb3fad5e85945 +or +.BR SECCOMP_RET_KILL_THREAD +(in Linux 4.13 and earlier). +.\" +.SS /proc interfaces +The files in the directory +.IR /proc/sys/kernel/seccomp +provide additional seccomp information and configuration: +.TP +.IR actions_avail " (since Linux 4.14)" +.\" commit 8e5f1ad116df6b0de65eac458d5e7c318d1c05af +A read-only ordered list of seccomp filter return actions in string form. +The ordering, from left-to-right, is in decreasing order of precedence. +The list represents the set of seccomp filter return actions +supported by the kernel. +.TP +.IR actions_logged " (since Linux 4.14)" +.\" commit 0ddec0fc8900201c0897b87b762b7c420436662f +A read-write ordered list of seccomp filter return actions that +are allowed to be logged. +Writes to the file do not need to be in ordered form but reads from +the file will be ordered in the same way as the +.IR actions_avail +file. +.IP +It is important to note that the value of +.IR actions_logged +does not prevent certain filter return actions from being logged when +the audit subsystem is configured to audit a task. +If the action is not found in the +.IR actions_logged +file, the final decision on whether to audit the action for that task is +ultimately left up to the audit subsystem to decide for all filter return +actions other than +.BR SECCOMP_RET_ALLOW . +.IP +The "allow" string is not accepted in the +.IR actions_logged +file as it is not possible to log +.BR SECCOMP_RET_ALLOW +actions. +Attempting to write "allow" to the file will fail with the error +.BR EINVAL . +.\" +.SS Audit logging of seccomp actions +.\" commit 59f5cf44a38284eb9e76270c786fb6cc62ef8ac4 +Since Linux 4.14, the kernel provides the facility to log the +actions returned by seccomp filters in the audit log. +The kernel makes the decision to log an action based on +the action type, whether or not the action is present in the +.I actions_logged +file, and whether kernel auditing is enabled +(e.g., via the kernel boot option +.IR audit=1 ). +.\" or auditing could be enabled via the netlink API (AUDIT_SET) +The rules are as follows: +.IP * 3 +If the action is +.BR SECCOMP_RET_ALLOW , +the action is not logged. +.IP * +Otherwise, if the action is either +.BR SECCOMP_RET_KILL_PROCESS +or +.BR SECCOMP_RET_KILL_THREAD , +and that action appears in the +.IR actions_logged +file, the action is logged. +.IP * +Otherwise, if the filter has requested logging (the +.BR SECCOMP_FILTER_FLAG_LOG +flag) +and the action appears in the +.IR actions_logged +file, the action is logged. +.IP * +Otherwise, if kernel auditing is enabled and the process is being audited +.RB ( autrace (8)), +the action is logged. +.IP * +Otherwise, the action is not logged. +.SH RETURN VALUE +On success, +.BR seccomp () +returns 0. +On error, if +.BR SECCOMP_FILTER_FLAG_TSYNC +was used, +the return value is the ID of the thread +that caused the synchronization failure. +(This ID is a kernel thread ID of the type returned by +.BR clone (2) +and +.BR gettid (2).) +On other errors, \-1 is returned, and +.IR errno +is set to indicate the cause of the error. +.SH ERRORS +.BR seccomp () +can fail for the following reasons: +.TP +.BR EACCESS +The caller did not have the +.BR CAP_SYS_ADMIN +capability in its user namespace, or had not set +.IR no_new_privs +before using +.BR SECCOMP_SET_MODE_FILTER . +.TP +.BR EFAULT +.IR args +was not a valid address. +.TP +.BR EINVAL +.IR operation +is unknown or is not supported by this kernel version or configuration. +.TP +.B EINVAL +The specified +.IR flags +are invalid for the given +.IR operation . +.TP +.BR EINVAL +.I operation +included +.BR BPF_ABS , +but the specified offset was not aligned to a 32-bit boundary or exceeded +.IR "sizeof(struct\ seccomp_data)" . +.TP +.BR EINVAL +.\" See kernel/seccomp.c::seccomp_may_assign_mode() in 3.18 sources +A secure computing mode has already been set, and +.I operation +differs from the existing setting. +.TP +.BR EINVAL +.I operation +specified +.BR SECCOMP_SET_MODE_FILTER , +but the filter program pointed to by +.I args +was not valid or the length of the filter program was zero or exceeded +.B BPF_MAXINSNS +(4096) instructions. +.TP +.BR ENOMEM +Out of memory. +.TP +.BR ENOMEM +.\" ENOMEM in kernel/seccomp.c::seccomp_attach_filter() in 3.18 sources +The total length of all filter programs attached +to the calling thread would exceed +.B MAX_INSNS_PER_PATH +(32768) instructions. +Note that for the purposes of calculating this limit, +each already existing filter program incurs an +overhead penalty of 4 instructions. +.TP +.BR EOPNOTSUPP +.I operation +specified +.BR SECCOMP_GET_ACTION_AVAIL , +but the kernel does not support the filter return action specified by +.IR args . +.TP +.BR ESRCH +Another thread caused a failure during thread sync, but its ID could not +be determined. +.SH VERSIONS +The +.BR seccomp () +system call first appeared in Linux 3.17. +.\" FIXME . Add glibc version +.SH CONFORMING TO +The +.BR seccomp () +system call is a nonstandard Linux extension. +.SH NOTES +Rather than hand-coding seccomp filters as shown in the example below, +you may prefer to employ the +.I libseccomp +library, which provides a front-end for generating seccomp filters. +.PP +The +.IR Seccomp +field of the +.IR /proc/[pid]/status +file provides a method of viewing the seccomp mode of a process; see +.BR proc (5). +.PP +.BR seccomp () +provides a superset of the functionality provided by the +.BR prctl (2) +.BR PR_SET_SECCOMP +operation (which does not support +.IR flags ). +.PP +Since Linux 4.4, the +.BR prctl (2) +.B PTRACE_SECCOMP_GET_FILTER +operation can be used to dump a process's seccomp filters. +.\" +.SS Caveats +There are various subtleties to consider when applying seccomp filters +to a program, including the following: +.IP * 3 +Some traditional system calls have user-space implementations in the +.BR vdso (7) +on many architectures. +Notable examples include +.BR clock_gettime (2), +.BR gettimeofday (2), +and +.BR time (2). +On such architectures, +seccomp filtering for these system calls will have no effect. +(However, there are cases where the +.BR vdso (7) +implementations may fall back to invoking the true system call, +in which case seccomp filters would see the system call.) +.IP * +Seccomp filtering is based on system call numbers. +However, applications typically do not directly invoke system calls, +but instead call wrapper functions in the C library which +in turn invoke the system calls. +Consequently, one must be aware of the following: +.RS +.IP \(bu 3 +The glibc wrappers for some traditional system calls may actually +employ system calls with different names in the kernel. +For example, the +.BR exit (2) +wrapper function actually employs the +.BR exit_group (2) +system call, and the +.BR fork (2) +wrapper function actually calls +.BR clone (2). +.IP \(bu +The behavior of wrapper functions may vary across architectures, +according to the range of system calls provided on those architectures. +In other words, the same wrapper function may invoke +different system calls on different architectures. +.IP \(bu +Finally, the behavior of wrapper functions can change across glibc versions. +For example, in older versions, the glibc wrapper function for +.BR open (2) +invoked the system call of the same name, +but starting in glibc 2.26, the implementation switched to calling +.BR openat (2) +on all architectures. +.RE +.PP +The consequence of the above points is that it may be necessary +to filter for a system call other than might be expected. +Various manual pages in Section 2 provide helpful details +about the differences between wrapper functions and +the underlying system calls in subsections entitled +.IR "C library/kernel differences" . +.PP +Furthermore, note that the application of seccomp filters +even risks causing bugs in an application, +when the filters cause unexpected failures for legitimate operations +that the application might need to perform. +Such bugs may not easily be discovered when testing the seccomp +filters if the bugs occur in rarely used application code paths. +.RS 3 +.\" +.SS Seccomp-specific BPF details +Note the following BPF details specific to seccomp filters: +.IP * 3 +The +.B BPF_H +and +.B BPF_B +size modifiers are not supported: all operations must load and store +(4-byte) words +.RB ( BPF_W ). +.IP * +To access the contents of the +.I seccomp_data +buffer, use the +.B BPF_ABS +addressing mode modifier. +.IP * +The +.B BPF_LEN +addressing mode modifier yields an immediate mode operand +whose value is the size of the +.IR seccomp_data +buffer. +.SH EXAMPLE +The program below accepts four or more arguments. +The first three arguments are a system call number, +a numeric architecture identifier, and an error number. +The program uses these values to construct a BPF filter +that is used at run time to perform the following checks: +.IP [1] 4 +If the program is not running on the specified architecture, +the BPF filter causes system calls to fail with the error +.BR ENOSYS . +.IP [2] +If the program attempts to execute the system call with the specified number, +the BPF filter causes the system call to fail, with +.I errno +being set to the specified error number. +.PP +The remaining command-line arguments specify +the pathname and additional arguments of a program +that the example program should attempt to execute using +.BR execv (3) +(a library function that employs the +.BR execve (2) +system call). +Some example runs of the program are shown below. +.PP +First, we display the architecture that we are running on (x86-64) +and then construct a shell function that looks up system call +numbers on this architecture: +.PP +.in +4n +.EX +$ \fBuname -m\fP +x86_64 +$ \fBsyscall_nr() { + cat /usr/src/linux/arch/x86/syscalls/syscall_64.tbl | \\ + awk '$2 != "x32" && $3 == "'$1'" { print $1 }' +}\fP +.EE +.in +.PP +When the BPF filter rejects a system call (case [2] above), +it causes the system call to fail with the error number +specified on the command line. +In the experiments shown here, we'll use error number 99: +.PP +.in +4n +.EX +$ \fBerrno 99\fP +EADDRNOTAVAIL 99 Cannot assign requested address +.EE +.in +.PP +In the following example, we attempt to run the command +.BR whoami (1), +but the BPF filter rejects the +.BR execve (2) +system call, so that the command is not even executed: +.PP +.in +4n +.EX +$ \fBsyscall_nr execve\fP +59 +$ \fB./a.out\fP +Usage: ./a.out [] +Hint for : AUDIT_ARCH_I386: 0x40000003 + AUDIT_ARCH_X86_64: 0xC000003E +$ \fB./a.out 59 0xC000003E 99 /bin/whoami\fP +execv: Cannot assign requested address +.EE +.in +.PP +In the next example, the BPF filter rejects the +.BR write (2) +system call, so that, although it is successfully started, the +.BR whoami (1) +command is not able to write output: +.PP +.in +4n +.EX +$ \fBsyscall_nr write\fP +1 +$ \fB./a.out 1 0xC000003E 99 /bin/whoami\fP +.EE +.in +.PP +In the final example, +the BPF filter rejects a system call that is not used by the +.BR whoami (1) +command, so it is able to successfully execute and produce output: +.PP +.in +4n +.EX +$ \fBsyscall_nr preadv\fP +295 +$ \fB./a.out 295 0xC000003E 99 /bin/whoami\fP +cecilia +.EE +.in +.SS Program source +.EX +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define X32_SYSCALL_BIT 0x40000000 + +static int +install_filter(int syscall_nr, int t_arch, int f_errno) +{ + unsigned int upper_nr_limit = 0xffffffff; + + /* Assume that AUDIT_ARCH_X86_64 means the normal x86-64 ABI */ + if (t_arch == AUDIT_ARCH_X86_64) + upper_nr_limit = X32_SYSCALL_BIT - 1; + + struct sock_filter filter[] = { + /* [0] Load architecture from 'seccomp_data' buffer into + accumulator */ + BPF_STMT(BPF_LD | BPF_W | BPF_ABS, + (offsetof(struct seccomp_data, arch))), + + /* [1] Jump forward 5 instructions if architecture does not + match 't_arch' */ + BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, t_arch, 0, 5), + + /* [2] Load system call number from 'seccomp_data' buffer into + accumulator */ + BPF_STMT(BPF_LD | BPF_W | BPF_ABS, + (offsetof(struct seccomp_data, nr))), + + /* [3] Check ABI - only needed for x86-64 in blacklist use + cases. Use BPF_JGT instead of checking against the bit + mask to avoid having to reload the syscall number. */ + BPF_JUMP(BPF_JMP | BPF_JGT | BPF_K, upper_nr_limit, 3, 0), + + /* [4] Jump forward 1 instruction if system call number + does not match 'syscall_nr' */ + BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, syscall_nr, 0, 1), + + /* [5] Matching architecture and system call: don't execute + the system call, and return 'f_errno' in 'errno' */ + BPF_STMT(BPF_RET | BPF_K, + SECCOMP_RET_ERRNO | (f_errno & SECCOMP_RET_DATA)), + + /* [6] Destination of system call number mismatch: allow other + system calls */ + BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW), + + /* [7] Destination of architecture mismatch: kill task */ + BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL), + }; + + struct sock_fprog prog = { + .len = (unsigned short) (sizeof(filter) / sizeof(filter[0])), + .filter = filter, + }; + + if (seccomp(SECCOMP_SET_MODE_FILTER, 0, &prog)) { + perror("seccomp"); + return 1; + } + + return 0; +} + +int +main(int argc, char **argv) +{ + if (argc < 5) { + fprintf(stderr, "Usage: " + "%s []\\n" + "Hint for : AUDIT_ARCH_I386: 0x%X\\n" + " AUDIT_ARCH_X86_64: 0x%X\\n" + "\\n", argv[0], AUDIT_ARCH_I386, AUDIT_ARCH_X86_64); + exit(EXIT_FAILURE); + } + + if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { + perror("prctl"); + exit(EXIT_FAILURE); + } + + if (install_filter(strtol(argv[1], NULL, 0), + strtol(argv[2], NULL, 0), + strtol(argv[3], NULL, 0))) + exit(EXIT_FAILURE); + + execv(argv[4], &argv[4]); + perror("execv"); + exit(EXIT_FAILURE); +} +.EE +.SH SEE ALSO +.BR strace (1), +.BR bpf (2), +.BR prctl (2), +.BR ptrace (2), +.BR sigaction (2), +.BR proc (5), +.BR signal (7), +.BR socket (7) +.PP +Various pages from the +.I libseccomp +library, including: +.BR scmp_sys_resolver (1), +.BR seccomp_init (3), +.BR seccomp_load (3), +.BR seccomp_rule_add (3), +and +.BR seccomp_export_bpf (3). +.PP +The kernel source files +.IR Documentation/networking/filter.txt +and +.IR Documentation/userspace\-api/seccomp_filter.rst +.\" commit c061f33f35be0ccc80f4b8e0aea5dfd2ed7e01a3 +(or +.IR Documentation/prctl/seccomp_filter.txt +before Linux 4.13). +.PP +McCanne, S. and Jacobson, V. (1992) +.IR "The BSD Packet Filter: A New Architecture for User-level Packet Capture" , +Proceedings of the USENIX Winter 1993 Conference +.UR http://www.tcpdump.org/papers/bpf\-usenix93.pdf +.UE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/security.2 b/man2/security.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/security.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/select.2 b/man2/select.2 new file mode 100644 index 0000000..c0a3a47 --- /dev/null +++ b/man2/select.2 @@ -0,0 +1,717 @@ +.\" This manpage is copyright (C) 1992 Drew Eckhardt, +.\" copyright (C) 1995 Michael Shields. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-05-18 by Jim Van Zandt +.\" Sun Feb 11 14:07:00 MET 1996 Martin Schulze +.\" * layout slightly modified +.\" +.\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond +.\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb +.\" Modified Thu Feb 9 22:32:09 CET 2001 by bert hubert , aeb +.\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard +.\" 2005-03-11, mtk, modified pselect() text (it is now a system +.\" call in 2.6.16. +.\" +.TH SELECT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- +synchronous I/O multiplexing +.SH SYNOPSIS +.nf +/* According to POSIX.1-2001, POSIX.1-2008 */ +.B #include +.PP +/* According to earlier standards */ +.B #include +.B #include +.B #include +.PP +.BI "int select(int " nfds ", fd_set *" readfds ", fd_set *" writefds , +.BI " fd_set *" exceptfds ", struct timeval *" timeout ); +.PP +.BI "void FD_CLR(int " fd ", fd_set *" set ); +.BI "int FD_ISSET(int " fd ", fd_set *" set ); +.BI "void FD_SET(int " fd ", fd_set *" set ); +.BI "void FD_ZERO(fd_set *" set ); + +.B #include +.PP +.BI "int pselect(int " nfds ", fd_set *" readfds ", fd_set *" writefds , +.BI " fd_set *" exceptfds ", const struct timespec *" timeout , +.BI " const sigset_t *" sigmask ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR pselect (): +_POSIX_C_SOURCE\ >=\ 200112L +.SH DESCRIPTION +.BR select () +and +.BR pselect () +allow a program to monitor multiple file descriptors, +waiting until one or more of the file descriptors become "ready" +for some class of I/O operation (e.g., input possible). +A file descriptor is considered ready if it is possible to +perform a corresponding I/O operation (e.g., +.BR read (2) +without blocking, or a sufficiently small +.BR write (2)). +.PP +.BR select () +can monitor only file descriptors numbers that are less than +.BR FD_SETSIZE ; +.BR poll (2) +does not have this limitation. +See BUGS. +.PP +The operation of +.BR select () +and +.BR pselect () +is identical, other than these three differences: +.TP +(i) +.BR select () +uses a timeout that is a +.I struct timeval +(with seconds and microseconds), while +.BR pselect () +uses a +.I struct timespec +(with seconds and nanoseconds). +.TP +(ii) +.BR select () +may update the +.I timeout +argument to indicate how much time was left. +.BR pselect () +does not change this argument. +.TP +(iii) +.BR select () +has no +.I sigmask +argument, and behaves as +.BR pselect () +called with NULL +.IR sigmask . +.PP +Three independent sets of file descriptors are watched. +The file descriptors listed in +.I readfds +will be watched to see if characters become +available for reading (more precisely, to see if a read will not +block; in particular, a file descriptor is also ready on end-of-file). +The file descriptors in +.I writefds +will be watched to see if space is available for write (though a large +write may still block). +The file descriptors in +.I exceptfds +will be watched for exceptional conditions. +(For examples of some exceptional conditions, see the discussion of +.B POLLPRI +in +.BR poll (2).) +.PP +On exit, each of the file descriptor sets is modified in place +to indicate which file descriptors actually changed status. +(Thus, if using +.BR select () +within a loop, the sets must be reinitialized before each call.) +.PP +Each of the three file descriptor sets may be specified as NULL +if no file descriptors are to be watched for the corresponding class +of events. +.PP +Four macros are provided to manipulate the sets. +.BR FD_ZERO () +clears a set. +.BR FD_SET () +and +.BR FD_CLR () +respectively add and remove a given file descriptor from a set. +.BR FD_ISSET () +tests to see if a file descriptor is part of the set; +this is useful after +.BR select () +returns. +.PP +.I nfds +should be set to the highest-numbered file descriptor in any +of the three sets, plus 1. +The indicated file descriptors in each set are checked, up to this limit +(but see BUGS). +.PP +The +.I timeout +argument specifies the interval that +.BR select () +should block waiting for a file descriptor to become ready. +The call will block until either: +.IP * 3 +a file descriptor becomes ready; +.IP * +the call is interrupted by a signal handler; or +.IP * +the timeout expires. +.PP +Note that the +.I timeout +interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the blocking interval +may overrun by a small amount. +If both fields of the +.I timeval +structure are zero, then +.BR select () +returns immediately. +(This is useful for polling.) +If +.I timeout +is NULL (no timeout), +.BR select () +can block indefinitely. +.PP +.I sigmask +is a pointer to a signal mask (see +.BR sigprocmask (2)); +if it is not NULL, then +.BR pselect () +first replaces the current signal mask by the one pointed to by +.IR sigmask , +then does the "select" function, and then restores the original +signal mask. +.PP +Other than the difference in the precision of the +.I timeout +argument, the following +.BR pselect () +call: +.PP +.in +4n +.EX +ready = pselect(nfds, &readfds, &writefds, &exceptfds, + timeout, &sigmask); +.EE +.in +.PP +is equivalent to +.I atomically +executing the following calls: +.PP +.in +4n +.EX +sigset_t origmask; + +pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); +ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); +pthread_sigmask(SIG_SETMASK, &origmask, NULL); +.EE +.in +.PP +.PP +The reason that +.BR pselect () +is needed is that if one wants to wait for either a signal +or for a file descriptor to become ready, then +an atomic test is needed to prevent race conditions. +(Suppose the signal handler sets a global flag and +returns. +Then a test of this global flag followed by a call of +.BR select () +could hang indefinitely if the signal arrived just after the test +but just before the call. +By contrast, +.BR pselect () +allows one to first block signals, handle the signals that have come in, +then call +.BR pselect () +with the desired +.IR sigmask , +avoiding the race.) +.SS The timeout +The time structures involved are defined in +.I +and look like +.PP +.in +4n +.EX +struct timeval { + long tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.EE +.in +.PP +and +.PP +.in +4n +.EX +struct timespec { + long tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.PP +(However, see below on the POSIX.1 versions.) +.PP +Some code calls +.BR select () +with all three sets empty, +.I nfds +zero, and a non-NULL +.I timeout +as a fairly portable way to sleep with subsecond precision. +.PP +On Linux, +.BR select () +modifies +.I timeout +to reflect the amount of time not slept; most other implementations +do not do this. +(POSIX.1 permits either behavior.) +This causes problems both when Linux code which reads +.I timeout +is ported to other operating systems, and when code is ported to Linux +that reuses a \fIstruct timeval\fP for multiple +.BR select ()s +in a loop without reinitializing it. +Consider +.I timeout +to be undefined after +.BR select () +returns. +.\" .PP - it is rumored that: +.\" On BSD, when a timeout occurs, the file descriptor bits are not changed. +.\" - it is certainly true that: +.\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. +.SH RETURN VALUE +On success, +.BR select () +and +.BR pselect () +return the number of file descriptors contained in the three returned +descriptor sets (that is, the total number of bits that are set in +.IR readfds , +.IR writefds , +.IR exceptfds ) +which may be zero if the timeout expires before anything interesting happens. +On error, \-1 is returned, and +.I errno +is set to indicate the error; +the file descriptor sets are unmodified, +and +.I timeout +becomes undefined. +.SH ERRORS +.TP +.B EBADF +An invalid file descriptor was given in one of the sets. +(Perhaps a file descriptor that was already closed, +or one on which an error has occurred.) +However, see BUGS. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EINVAL +.I nfds +is negative or exceeds the +.BR RLIMIT_NOFILE +resource limit (see +.BR getrlimit (2)). +.TP +.B EINVAL +The value contained within +.I timeout +is invalid. +.TP +.B ENOMEM +Unable to allocate memory for internal tables. +.SH VERSIONS +.BR pselect () +was added to Linux in kernel 2.6.16. +Prior to this, +.BR pselect () +was emulated in glibc (but see BUGS). +.SH CONFORMING TO +.BR select () +conforms to POSIX.1-2001, POSIX.1-2008, and +4.4BSD +.RB ( select () +first appeared in 4.2BSD). +Generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System\ V variants). +However, note that the System\ V variant typically +sets the timeout variable before exit, but the BSD variant does not. +.PP +.BR pselect () +is defined in POSIX.1g, and in +POSIX.1-2001 and POSIX.1-2008. +.SH NOTES +An +.I fd_set +is a fixed size buffer. +Executing +.BR FD_CLR () +or +.BR FD_SET () +with a value of +.I fd +that is negative or is equal to or larger than +.B FD_SETSIZE +will result +in undefined behavior. +Moreover, POSIX requires +.I fd +to be a valid file descriptor. +.PP +On some other UNIX systems, +.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett +.BR select () +can fail with the error +.B EAGAIN +if the system fails to allocate kernel-internal resources, rather than +.B ENOMEM +as Linux does. +POSIX specifies this error for +.BR poll (2), +but not for +.BR select (). +Portable programs may wish to check for +.B EAGAIN +and loop, just as with +.BR EINTR . +.PP +On systems that lack +.BR pselect (), +reliable (and more portable) signal trapping can be achieved +using the self-pipe trick. +In this technique, +a signal handler writes a byte to a pipe whose other end +is monitored by +.BR select () +in the main program. +(To avoid possibly blocking when writing to a pipe that may be full +or reading from a pipe that may be empty, +nonblocking I/O is used when reading from and writing to the pipe.) +.PP +Concerning the types involved, the classical situation is that +the two fields of a +.I timeval +structure are typed as +.I long +(as shown above), and the structure is defined in +.IR . +The POSIX.1 situation is +.PP +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.PP +where the structure is defined in +.I +and the data types +.I time_t +and +.I suseconds_t +are defined in +.IR . +.PP +Concerning prototypes, the classical situation is that one should +include +.I +for +.BR select (). +The POSIX.1 situation is that one should include +.I +for +.BR select () +and +.BR pselect (). +.PP +Under glibc 2.0, +.I +gives the wrong prototype for +.BR pselect (). +Under glibc 2.1 to 2.2.1, it gives +.BR pselect () +when +.B _GNU_SOURCE +is defined. +Since glibc 2.2.2, the requirements are as shown in the SYNOPSIS. +.\" +.SS Correspondence between select() and poll() notifications +Within the Linux kernel source, +.\" fs/select.c +we find the following definitions which show the correspondence +between the readable, writable, and exceptional condition notifications of +.BR select () +and the event notifications provided by +.BR poll (2) +(and +.BR epoll (7)): +.PP +.in +4n +.EX +#define POLLIN_SET (POLLRDNORM | POLLRDBAND | POLLIN | POLLHUP | + POLLERR) + /* Ready for reading */ +#define POLLOUT_SET (POLLWRBAND | POLLWRNORM | POLLOUT | POLLERR) + /* Ready for writing */ +#define POLLEX_SET (POLLPRI) + /* Exceptional condition */ +.EE +.in +.\" +.SS Multithreaded applications +If a file descriptor being monitored by +.BR select () +is closed in another thread, the result is unspecified. +On some UNIX systems, +.BR select () +unblocks and returns, with an indication that the file descriptor is ready +(a subsequent I/O operation will likely fail with an error, +unless another the file descriptor reopened between the time +.BR select () +returned and the I/O operations was performed). +On Linux (and some other systems), +closing the file descriptor in another thread has no effect on +.BR select (). +In summary, any application that relies on a particular behavior +in this scenario must be considered buggy. +.\" +.SS C library/kernel differences +The Linux kernel allows file descriptor sets of arbitrary size, +determining the length of the sets to be checked from the value of +.IR nfds . +However, in the glibc implementation, the +.IR fd_set +type is fixed in size. +See also BUGS. +.PP +The +.BR pselect () +interface described in this page is implemented by glibc. +The underlying Linux system call is named +.BR pselect6 (). +This system call has somewhat different behavior from the glibc +wrapper function. +.PP +The Linux +.BR pselect6 () +system call modifies its +.I timeout +argument. +However, the glibc wrapper function hides this behavior +by using a local variable for the timeout argument that +is passed to the system call. +Thus, the glibc +.BR pselect () +function does not modify its +.I timeout +argument; +this is the behavior required by POSIX.1-2001. +.PP +The final argument of the +.BR pselect6 () +system call is not a +.I "sigset_t\ *" +pointer, but is instead a structure of the form: +.PP +.in +4 +.EX +struct { + const kernel_sigset_t *ss; /* Pointer to signal set */ + size_t ss_len; /* Size (in bytes) of object + pointed to by 'ss' */ +}; +.EE +.in +.PP +This allows the system call to obtain both +a pointer to the signal set and its size, +while allowing for the fact that most architectures +support a maximum of 6 arguments to a system call. +See +.BR sigprocmask (2) +for a discussion of the difference between the kernel and libc +notion of the signal set. +.SH BUGS +POSIX allows an implementation to define an upper limit, +advertised via the constant +.BR FD_SETSIZE , +on the range of file descriptors that can be specified +in a file descriptor set. +The Linux kernel imposes no fixed limit, but the glibc implementation makes +.IR fd_set +a fixed-size type, with +.BR FD_SETSIZE +defined as 1024, and the +.BR FD_* () +macros operating according to that limit. +To monitor file descriptors greater than 1023, use +.BR poll (2) +instead. +.PP +According to POSIX, +.BR select () +should check all specified file descriptors in the three file descriptor sets, +up to the limit +.IR nfds\-1 . +However, the current implementation ignores any file descriptor in +these sets that is greater than the maximum file descriptor number +that the process currently has open. +According to POSIX, any such file descriptor that is specified in one +of the sets should result in the error +.BR EBADF . +.PP +Glibc 2.0 provided a version of +.BR pselect () +that did not take a +.I sigmask +argument. +.PP +Starting with version 2.1, glibc provided an emulation of +.BR pselect () +that was implemented using +.BR sigprocmask (2) +and +.BR select (). +This implementation remained vulnerable to the very race condition that +.BR pselect () +was designed to prevent. +Modern versions of glibc use the (race-free) +.BR pselect () +system call on kernels where it is provided. +.PP +Under Linux, +.BR select () +may report a socket file descriptor as "ready for reading", while +nevertheless a subsequent read blocks. +This could for example +happen when data has arrived but upon examination has wrong +checksum and is discarded. +There may be other circumstances +in which a file descriptor is spuriously reported as ready. +.\" Stevens discusses a case where accept can block after select +.\" returns successfully because of an intervening RST from the client. +Thus it may be safer to use +.B O_NONBLOCK +on sockets that should not block. +.\" Maybe the kernel should have returned EIO in such a situation? +.PP +On Linux, +.BR select () +also modifies +.I timeout +if the call is interrupted by a signal handler (i.e., the +.B EINTR +error return). +This is not permitted by POSIX.1. +The Linux +.BR pselect () +system call has the same behavior, +but the glibc wrapper hides this behavior by internally copying the +.I timeout +to a local variable and passing that variable to the system call. +.SH EXAMPLE +.EX +#include +#include +#include +#include +#include + +int +main(void) +{ + fd_set rfds; + struct timeval tv; + int retval; + + /* Watch stdin (fd 0) to see when it has input. */ + + FD_ZERO(&rfds); + FD_SET(0, &rfds); + + /* Wait up to five seconds. */ + + tv.tv_sec = 5; + tv.tv_usec = 0; + + retval = select(1, &rfds, NULL, NULL, &tv); + /* Don't rely on the value of tv now! */ + + if (retval == \-1) + perror("select()"); + else if (retval) + printf("Data is available now.\\n"); + /* FD_ISSET(0, &rfds) will be true. */ + else + printf("No data within five seconds.\\n"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR accept (2), +.BR connect (2), +.BR poll (2), +.BR read (2), +.BR recv (2), +.BR restart_syscall (2), +.BR send (2), +.BR sigprocmask (2), +.BR write (2), +.BR epoll (7), +.BR time (7) +.PP +For a tutorial with discussion and examples, see +.BR select_tut (2). +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/select_tut.2 b/man2/select_tut.2 new file mode 100644 index 0000000..cfb6438 --- /dev/null +++ b/man2/select_tut.2 @@ -0,0 +1,846 @@ +.\" This manpage is copyright (C) 2001 Paul Sheer. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" very minor changes, aeb +.\" +.\" Modified 5 June 2002, Michael Kerrisk +.\" 2006-05-13, mtk, removed much material that is redundant with select.2 +.\" various other changes +.\" 2008-01-26, mtk, substantial changes and rewrites +.\" +.TH SELECT_TUT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- +synchronous I/O multiplexing +.SH SYNOPSIS +.nf +/* According to POSIX.1-2001, POSIX.1-2008 */ +.B #include +.PP +/* According to earlier standards */ +.B #include +.B #include +.B #include +.PP +.BI "int select(int " nfds ", fd_set *" readfds ", fd_set *" writefds , +.BI " fd_set *" exceptfds ", struct timeval *" utimeout ); +.PP +.BI "void FD_CLR(int " fd ", fd_set *" set ); +.BI "int FD_ISSET(int " fd ", fd_set *" set ); +.BI "void FD_SET(int " fd ", fd_set *" set ); +.BI "void FD_ZERO(fd_set *" set ); + +.B #include +.PP +.BI "int pselect(int " nfds ", fd_set *" readfds ", fd_set *" writefds , +.BI " fd_set *" exceptfds ", const struct timespec *" ntimeout , +.BI " const sigset_t *" sigmask ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR pselect (): +_POSIX_C_SOURCE\ >=\ 200112L +.SH DESCRIPTION +.BR select () +(or +.BR pselect ()) +is used to efficiently monitor multiple file descriptors, +to see if any of them is, or becomes, "ready"; +that is, to see whether I/O becomes possible, +or an "exceptional condition" has occurred on any of the file descriptors. +.PP +Its principal arguments are three "sets" of file descriptors: +\fIreadfds\fP, \fIwritefds\fP, and \fIexceptfds\fP. +Each set is declared as type +.IR fd_set , +and its contents can be manipulated with the macros +.BR FD_CLR (), +.BR FD_ISSET (), +.BR FD_SET (), +and +.BR FD_ZERO (). +A newly declared set should first be cleared using +.BR FD_ZERO (). +.BR select () +modifies the contents of the sets according to the rules +described below; after calling +.BR select () +you can test if a file descriptor is still present in a set with the +.BR FD_ISSET () +macro. +.BR FD_ISSET () +returns nonzero if a specified file descriptor is present in a set +and zero if it is not. +.BR FD_CLR () +removes a file descriptor from a set. +.SS Arguments +.TP +\fIreadfds\fP +This set is watched to see if data is available for reading from any of +its file descriptors. +After +.BR select () +has returned, \fIreadfds\fP will be +cleared of all file descriptors except for those that +are immediately available for reading. +.TP +\fIwritefds\fP +This set is watched to see if there is space to write data to any of +its file descriptors. +After +.BR select () +has returned, \fIwritefds\fP will be +cleared of all file descriptors except for those that +are immediately available for writing. +.TP +\fIexceptfds\fP +This set is watched for "exceptional conditions". +In practice, only one such exceptional condition is common: +the availability of \fIout-of-band\fP (OOB) data for reading +from a TCP socket. +See +.BR recv (2), +.BR send (2), +and +.BR tcp (7) +for more details about OOB data. +(One other less common case where +.BR select (2) +indicates an exceptional condition occurs with pseudoterminals +in packet mode; see +.BR ioctl_tty (2).) +After +.BR select () +has returned, +\fIexceptfds\fP will be cleared of all file descriptors except for those +for which an exceptional condition has occurred. +.TP +\fInfds\fP +This is an integer one more than the maximum of any file descriptor in +any of the sets. +In other words, while adding file descriptors to each of the sets, +you must calculate the maximum integer value of all of them, +then increment this value by one, and then pass this as \fInfds\fP. +.TP +\fIutimeout\fP +This is the longest time +.BR select () +may wait before returning, even if nothing interesting happened. +If this value is passed as NULL, then +.BR select () +blocks indefinitely waiting for a file descriptor to become ready. +\fIutimeout\fP can be set to zero seconds, which causes +.BR select () +to return immediately, with information about the readiness +of file descriptors at the time of the call. +The structure \fIstruct timeval\fP is defined as: +.IP +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.EE +.in +.TP +\fIntimeout\fP +This argument for +.BR pselect () +has the same meaning as +.IR utimeout , +but +.I "struct timespec" +has nanosecond precision as follows: +.IP +.in +4n +.EX +struct timespec { + long tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.TP +\fIsigmask\fP +This argument holds a set of signals that the kernel should unblock +(i.e., remove from the signal mask of the calling thread), +while the caller is blocked inside the +.BR pselect () +call (see +.BR sigaddset (3) +and +.BR sigprocmask (2)). +It may be NULL, +in which case the call does not modify the signal mask on +entry and exit to the function. +In this case, +.BR pselect () +will then behave just like +.BR select (). +.SS Combining signal and data events +.BR pselect () +is useful if you are waiting for a signal as well as +for file descriptor(s) to become ready for I/O. +Programs that receive signals +normally use the signal handler only to raise a global flag. +The global flag will indicate that the event must be processed +in the main loop of the program. +A signal will cause the +.BR select () +(or +.BR pselect ()) +call to return with \fIerrno\fP set to \fBEINTR\fP. +This behavior is essential so that signals can be processed +in the main loop of the program, otherwise +.BR select () +would block indefinitely. +Now, somewhere +in the main loop will be a conditional to check the global flag. +So we must ask: +what if a signal arrives after the conditional, but before the +.BR select () +call? +The answer is that +.BR select () +would block indefinitely, even though an event is actually pending. +This race condition is solved by the +.BR pselect () +call. +This call can be used to set the signal mask to a set of signals +that are to be received only within the +.BR pselect () +call. +For instance, let us say that the event in question +was the exit of a child process. +Before the start of the main loop, we +would block \fBSIGCHLD\fP using +.BR sigprocmask (2). +Our +.BR pselect () +call would enable +.B SIGCHLD +by using an empty signal mask. +Our program would look like: +.PP +.EX +static volatile sig_atomic_t got_SIGCHLD = 0; + +static void +child_sig_handler(int sig) +{ + got_SIGCHLD = 1; +} + +int +main(int argc, char *argv[]) +{ + sigset_t sigmask, empty_mask; + struct sigaction sa; + fd_set readfds, writefds, exceptfds; + int r; + + sigemptyset(&sigmask); + sigaddset(&sigmask, SIGCHLD); + if (sigprocmask(SIG_BLOCK, &sigmask, NULL) == \-1) { + perror("sigprocmask"); + exit(EXIT_FAILURE); + } + + sa.sa_flags = 0; + sa.sa_handler = child_sig_handler; + sigemptyset(&sa.sa_mask); + if (sigaction(SIGCHLD, &sa, NULL) == \-1) { + perror("sigaction"); + exit(EXIT_FAILURE); + } + + sigemptyset(&empty_mask); + + for (;;) { /* main loop */ + /* Initialize readfds, writefds, and exceptfds + before the pselect() call. (Code omitted.) */ + + r = pselect(nfds, &readfds, &writefds, &exceptfds, + NULL, &empty_mask); + if (r == \-1 && errno != EINTR) { + /* Handle error */ + } + + if (got_SIGCHLD) { + got_SIGCHLD = 0; + + /* Handle signalled event here; e.g., wait() for all + terminated children. (Code omitted.) */ + } + + /* main body of program */ + } +} +.EE +.SS Practical +So what is the point of +.BR select ()? +Can't I just read and write to my file descriptors whenever I want? +The point of +.BR select () +is that it watches +multiple descriptors at the same time and properly puts the process to +sleep if there is no activity. +UNIX programmers often find +themselves in a position where they have to handle I/O from more than one +file descriptor where the data flow may be intermittent. +If you were to merely create a sequence of +.BR read (2) +and +.BR write (2) +calls, you would +find that one of your calls may block waiting for data from/to a file +descriptor, while another file descriptor is unused though ready for I/O. +.BR select () +efficiently copes with this situation. +.SS Select law +Many people who try to use +.BR select () +come across behavior that is +difficult to understand and produces nonportable or borderline results. +For instance, the above program is carefully written not to +block at any point, even though it does not set its file descriptors to +nonblocking mode. +It is easy to introduce +subtle errors that will remove the advantage of using +.BR select (), +so here is a list of essentials to watch for when using +.BR select (). +.TP 4 +1. +You should always try to use +.BR select () +without a timeout. +Your program +should have nothing to do if there is no data available. +Code that +depends on timeouts is not usually portable and is difficult to debug. +.TP +2. +The value \fInfds\fP must be properly calculated for efficiency as +explained above. +.TP +3. +No file descriptor must be added to any set if you do not intend +to check its result after the +.BR select () +call, and respond appropriately. +See next rule. +.TP +4. +After +.BR select () +returns, all file descriptors in all sets +should be checked to see if they are ready. +.TP +5. +The functions +.BR read (2), +.BR recv (2), +.BR write (2), +and +.BR send (2) +do \fInot\fP necessarily read/write the full amount of data +that you have requested. +If they do read/write the full amount, it's +because you have a low traffic load and a fast stream. +This is not always going to be the case. +You should cope with the case of your +functions managing to send or receive only a single byte. +.TP +6. +Never read/write only in single bytes at a time unless you are really +sure that you have a small amount of data to process. +It is extremely +inefficient not to read/write as much data as you can buffer each time. +The buffers in the example below are 1024 bytes although they could +easily be made larger. +.TP +7. +Calls to +.BR read (2), +.BR recv (2), +.BR write (2), +.BR send (2), +and +.BR select () +can fail with the error +\fBEINTR\fP, +and calls to +.BR read (2), +.BR recv (2) +.BR write (2), +and +.BR send (2) +can fail with +.I errno +set to \fBEAGAIN\fP (\fBEWOULDBLOCK\fP). +These results must be properly managed (not done properly above). +If your program is not going to receive any signals, then +it is unlikely you will get \fBEINTR\fP. +If your program does not set nonblocking I/O, +you will not get \fBEAGAIN\fP. +.\" Nonetheless, you should still cope with these errors for completeness. +.TP +8. +Never call +.BR read (2), +.BR recv (2), +.BR write (2), +or +.BR send (2) +with a buffer length of zero. +.TP +9. +If the functions +.BR read (2), +.BR recv (2), +.BR write (2), +and +.BR send (2) +fail with errors other than those listed in \fB7.\fP, +or one of the input functions returns 0, indicating end of file, +then you should \fInot\fP pass that file descriptor to +.BR select () +again. +In the example below, +I close the file descriptor immediately, and then set it to \-1 +to prevent it being included in a set. +.TP +10. +The timeout value must be initialized with each new call to +.BR select (), +since some operating systems modify the structure. +.BR pselect () +however does not modify its timeout structure. +.TP +11. +Since +.BR select () +modifies its file descriptor sets, +if the call is being used in a loop, +then the sets must be reinitialized before each call. +.\" "I have heard" does not fill me with confidence, and doesn't +.\" belong in a man page, so I've commented this point out. +.\" .TP +.\" 11. +.\" I have heard that the Windows socket layer does not cope with OOB data +.\" properly. +.\" It also does not cope with +.\" .BR select () +.\" calls when no file descriptors are set at all. +.\" Having no file descriptors set is a useful +.\" way to sleep the process with subsecond precision by using the timeout. +.\" (See further on.) +.SS Usleep emulation +On systems that do not have a +.BR usleep (3) +function, you can call +.BR select () +with a finite timeout and no file descriptors as +follows: +.PP +.in +4n +.EX +struct timeval tv; +tv.tv_sec = 0; +tv.tv_usec = 200000; /* 0.2 seconds */ +select(0, NULL, NULL, NULL, &tv); +.EE +.in +.PP +This is guaranteed to work only on UNIX systems, however. +.SH RETURN VALUE +On success, +.BR select () +returns the total number of file descriptors +still present in the file descriptor sets. +.PP +If +.BR select () +timed out, then the return value will be zero. +The file descriptors set should be all +empty (but may not be on some systems). +.PP +A return value of \-1 indicates an error, with \fIerrno\fP being +set appropriately. +In the case of an error, the contents of the returned sets and +the \fIstruct timeout\fP contents are undefined and should not be used. +.BR pselect () +however never modifies \fIntimeout\fP. +.SH NOTES +Generally speaking, +all operating systems that support sockets also support +.BR select (). +.BR select () +can be used to solve +many problems in a portable and efficient way that naive programmers try +to solve in a more complicated manner using +threads, forking, IPCs, signals, memory sharing, and so on. +.PP +The +.BR poll (2) +system call has the same functionality as +.BR select (), +and is somewhat more efficient when monitoring sparse +file descriptor sets. +It is nowadays widely available, but historically was less portable than +.BR select (). +.PP +The Linux-specific +.BR epoll (7) +API provides an interface that is more efficient than +.BR select (2) +and +.BR poll (2) +when monitoring large numbers of file descriptors. +.SH EXAMPLE +Here is an example that better demonstrates the true utility of +.BR select (). +The listing below is a TCP forwarding program that forwards +from one TCP port to another. +.PP +.EX +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +static int forward_port; + +#undef max +#define max(x,y) ((x) > (y) ? (x) : (y)) + +static int +listen_socket(int listen_port) +{ + struct sockaddr_in addr; + int lfd; + int yes; + + lfd = socket(AF_INET, SOCK_STREAM, 0); + if (lfd == \-1) { + perror("socket"); + return \-1; + } + + yes = 1; + if (setsockopt(lfd, SOL_SOCKET, SO_REUSEADDR, + &yes, sizeof(yes)) == \-1) { + perror("setsockopt"); + close(lfd); + return \-1; + } + + memset(&addr, 0, sizeof(addr)); + addr.sin_port = htons(listen_port); + addr.sin_family = AF_INET; + if (bind(lfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { + perror("bind"); + close(lfd); + return \-1; + } + + printf("accepting connections on port %d\\n", listen_port); + listen(lfd, 10); + return lfd; +} + +static int +connect_socket(int connect_port, char *address) +{ + struct sockaddr_in addr; + int cfd; + + cfd = socket(AF_INET, SOCK_STREAM, 0); + if (cfd == \-1) { + perror("socket"); + return \-1; + } + + memset(&addr, 0, sizeof(addr)); + addr.sin_port = htons(connect_port); + addr.sin_family = AF_INET; + + if (!inet_aton(address, (struct in_addr *) &addr.sin_addr.s_addr)) { + perror("bad IP address format"); + close(cfd); + return \-1; + } + + if (connect(cfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { + perror("connect()"); + shutdown(cfd, SHUT_RDWR); + close(cfd); + return \-1; + } + return cfd; +} + +#define SHUT_FD1 do { \\ + if (fd1 >= 0) { \\ + shutdown(fd1, SHUT_RDWR); \\ + close(fd1); \\ + fd1 = \-1; \\ + } \\ + } while (0) + +#define SHUT_FD2 do { \\ + if (fd2 >= 0) { \\ + shutdown(fd2, SHUT_RDWR); \\ + close(fd2); \\ + fd2 = \-1; \\ + } \\ + } while (0) + +#define BUF_SIZE 1024 + +int +main(int argc, char *argv[]) +{ + int h; + int fd1 = \-1, fd2 = \-1; + char buf1[BUF_SIZE], buf2[BUF_SIZE]; + int buf1_avail = 0, buf1_written = 0; + int buf2_avail = 0, buf2_written = 0; + + if (argc != 4) { + fprintf(stderr, "Usage\\n\\tfwd " + " \\n"); + exit(EXIT_FAILURE); + } + + signal(SIGPIPE, SIG_IGN); + + forward_port = atoi(argv[2]); + + h = listen_socket(atoi(argv[1])); + if (h == \-1) + exit(EXIT_FAILURE); + + for (;;) { + int ready, nfds = 0; + ssize_t nbytes; + fd_set readfds, writefds, exceptfds; + + FD_ZERO(&readfds); + FD_ZERO(&writefds); + FD_ZERO(&exceptfds); + FD_SET(h, &readfds); + nfds = max(nfds, h); + + if (fd1 > 0 && buf1_avail < BUF_SIZE) + FD_SET(fd1, &readfds); + /* Note: nfds is updated below, when fd1 is added to + exceptfds. */ + if (fd2 > 0 && buf2_avail < BUF_SIZE) + FD_SET(fd2, &readfds); + + if (fd1 > 0 && buf2_avail \- buf2_written > 0) + FD_SET(fd1, &writefds); + if (fd2 > 0 && buf1_avail \- buf1_written > 0) + FD_SET(fd2, &writefds); + + if (fd1 > 0) { + FD_SET(fd1, &exceptfds); + nfds = max(nfds, fd1); + } + if (fd2 > 0) { + FD_SET(fd2, &exceptfds); + nfds = max(nfds, fd2); + } + + ready = select(nfds + 1, &readfds, &writefds, &exceptfds, NULL); + + if (ready == \-1 && errno == EINTR) + continue; + + if (ready == \-1) { + perror("select()"); + exit(EXIT_FAILURE); + } + + if (FD_ISSET(h, &readfds)) { + socklen_t addrlen; + struct sockaddr_in client_addr; + int fd; + + addrlen = sizeof(client_addr); + memset(&client_addr, 0, addrlen); + fd = accept(h, (struct sockaddr *) &client_addr, &addrlen); + if (fd == \-1) { + perror("accept()"); + } else { + SHUT_FD1; + SHUT_FD2; + buf1_avail = buf1_written = 0; + buf2_avail = buf2_written = 0; + fd1 = fd; + fd2 = connect_socket(forward_port, argv[3]); + if (fd2 == \-1) + SHUT_FD1; + else + printf("connect from %s\\n", + inet_ntoa(client_addr.sin_addr)); + + /* Skip any events on the old, closed file descriptors. */ + continue; + } + } + + /* NB: read OOB data before normal reads */ + + if (fd1 > 0 && FD_ISSET(fd1, &exceptfds)) { + char c; + + nbytes = recv(fd1, &c, 1, MSG_OOB); + if (nbytes < 1) + SHUT_FD1; + else + send(fd2, &c, 1, MSG_OOB); + } + if (fd2 > 0 && FD_ISSET(fd2, &exceptfds)) { + char c; + + nbytes = recv(fd2, &c, 1, MSG_OOB); + if (nbytes < 1) + SHUT_FD2; + else + send(fd1, &c, 1, MSG_OOB); + } + if (fd1 > 0 && FD_ISSET(fd1, &readfds)) { + nbytes = read(fd1, buf1 + buf1_avail, + BUF_SIZE \- buf1_avail); + if (nbytes < 1) + SHUT_FD1; + else + buf1_avail += nbytes; + } + if (fd2 > 0 && FD_ISSET(fd2, &readfds)) { + nbytes = read(fd2, buf2 + buf2_avail, + BUF_SIZE \- buf2_avail); + if (nbytes < 1) + SHUT_FD2; + else + buf2_avail += nbytes; + } + if (fd1 > 0 && FD_ISSET(fd1, &writefds) && buf2_avail > 0) { + nbytes = write(fd1, buf2 + buf2_written, + buf2_avail \- buf2_written); + if (nbytes < 1) + SHUT_FD1; + else + buf2_written += nbytes; + } + if (fd2 > 0 && FD_ISSET(fd2, &writefds) && buf1_avail > 0) { + nbytes = write(fd2, buf1 + buf1_written, + buf1_avail \- buf1_written); + if (nbytes < 1) + SHUT_FD2; + else + buf1_written += nbytes; + } + + /* Check if write data has caught read data */ + + if (buf1_written == buf1_avail) + buf1_written = buf1_avail = 0; + if (buf2_written == buf2_avail) + buf2_written = buf2_avail = 0; + + /* One side has closed the connection, keep + writing to the other side until empty */ + + if (fd1 < 0 && buf1_avail \- buf1_written == 0) + SHUT_FD2; + if (fd2 < 0 && buf2_avail \- buf2_written == 0) + SHUT_FD1; + } + exit(EXIT_SUCCESS); +} +.EE +.PP +The above program properly forwards most kinds of TCP connections +including OOB signal data transmitted by \fBtelnet\fP servers. +It handles the tricky problem of having data flow in both directions +simultaneously. +You might think it more efficient to use a +.BR fork (2) +call and devote a thread to each stream. +This becomes more tricky than you might suspect. +Another idea is to set nonblocking I/O using +.BR fcntl (2). +This also has its problems because you end up using +inefficient timeouts. +.PP +The program does not handle more than one simultaneous connection at a +time, although it could easily be extended to do this with a linked list +of buffers\(emone for each connection. +At the moment, new +connections cause the current connection to be dropped. +.SH SEE ALSO +.BR accept (2), +.BR connect (2), +.BR ioctl (2), +.BR poll (2), +.BR read (2), +.BR recv (2), +.BR select (2), +.BR send (2), +.BR sigprocmask (2), +.BR write (2), +.BR sigaddset (3), +.BR sigdelset (3), +.BR sigemptyset (3), +.BR sigfillset (3), +.BR sigismember (3), +.BR epoll (7) +.\" .SH AUTHORS +.\" This man page was written by Paul Sheer. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/semctl.2 b/man2/semctl.2 new file mode 100644 index 0000000..a16a884 --- /dev/null +++ b/man2/semctl.2 @@ -0,0 +1,593 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright 2004, 2005 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond +.\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer +.\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer +.\" Modified 20 Dec 2001, Michael Kerrisk +.\" Modified 21 Dec 2001, aeb +.\" Modified 27 May 2004, Michael Kerrisk +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified 17 Jun 2004, Michael Kerrisk +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Rewrote semun text +.\" Added semid_ds and ipc_perm structure definitions +.\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. +.\" +.TH SEMCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +semctl \- System V semaphore control operations +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" +.fi +.SH DESCRIPTION +.BR semctl () +performs the control operation specified by +.I cmd +on the System\ V semaphore set identified by +.IR semid , +or on the +.IR semnum -th +semaphore of that set. +(The semaphores in a set are numbered starting at 0.) +.PP +This function has three or four arguments, depending on +.IR cmd . +When there are four, the fourth has the type +.IR "union semun" . +The \fIcalling program\fP must define this union as follows: +.PP +.in +4n +.EX +union semun { + int val; /* Value for SETVAL */ + struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ + unsigned short *array; /* Array for GETALL, SETALL */ + struct seminfo *__buf; /* Buffer for IPC_INFO + (Linux-specific) */ +}; +.EE +.in +.PP +The +.I semid_ds +data structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct semid_ds { + struct ipc_perm sem_perm; /* Ownership and permissions */ + time_t sem_otime; /* Last semop time */ + time_t sem_ctime; /* Last change time */ + unsigned long sem_nsems; /* No. of semaphores in set */ +}; +.EE +.in +.PP +The +.I ipc_perm +structure is defined as follows +(the highlighted fields are settable using +.BR IPC_SET ): +.PP +.in +4n +.EX +struct ipc_perm { + key_t __key; /* Key supplied to semget(2) */ + uid_t \fBuid\fP; /* Effective UID of owner */ + gid_t \fBgid\fP; /* Effective GID of owner */ + uid_t cuid; /* Effective UID of creator */ + gid_t cgid; /* Effective GID of creator */ + unsigned short \fBmode\fP; /* Permissions */ + unsigned short __seq; /* Sequence number */ +}; +.EE +.in +.PP +Valid values for +.I cmd +are: +.TP 10 +.B IPC_STAT +Copy information from the kernel data structure associated with +.I semid +into the +.I semid_ds +structure pointed to by +.IR arg.buf . +The argument +.I semnum +is ignored. +The calling process must have read permission on the semaphore set. +.TP +.B IPC_SET +Write the values of some members of the +.I semid_ds +structure pointed to by +.I arg.buf +to the kernel data structure associated with this semaphore set, +updating also its +.I sem_ctime +member. +The following members of the structure are updated: +.IR sem_perm.uid , +.IR sem_perm.gid , +and (the least significant 9 bits of) +.IR sem_perm.mode . +The effective UID of the calling process must match the owner +.RI ( sem_perm.uid ) +or creator +.RI ( sem_perm.cuid ) +of the semaphore set, or the caller must be privileged. +The argument +.I semnum +is ignored. +.TP +.B IPC_RMID +Immediately remove the semaphore set, +awakening all processes blocked in +.BR semop (2) +calls on the set (with an error return and +.I errno +set to +.BR EIDRM ). +The effective user ID of the calling process must +match the creator or owner of the semaphore set, +or the caller must be privileged. +The argument +.I semnum +is ignored. +.TP +.BR IPC_INFO " (Linux-specific)" +Return information about system-wide semaphore limits and +parameters in the structure pointed to by +.IR arg.__buf . +This structure is of type +.IR seminfo , +defined in +.I +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct seminfo { + int semmap; /* Number of entries in semaphore + map; unused within kernel */ + int semmni; /* Maximum number of semaphore sets */ + int semmns; /* Maximum number of semaphores in all + semaphore sets */ + int semmnu; /* System-wide maximum number of undo + structures; unused within kernel */ + int semmsl; /* Maximum number of semaphores in a + set */ + int semopm; /* Maximum number of operations for + semop(2) */ + int semume; /* Maximum number of undo entries per + process; unused within kernel */ + int semusz; /* Size of struct sem_undo */ + int semvmx; /* Maximum semaphore value */ + int semaem; /* Max. value that can be recorded for + semaphore adjustment (SEM_UNDO) */ +}; +.EE +.in +.IP +The +.IR semmsl , +.IR semmns , +.IR semopm , +and +.I semmni +settings can be changed via +.IR /proc/sys/kernel/sem ; +see +.BR proc (5) +for details. +.TP +.BR SEM_INFO " (Linux-specific)" +Return a +.I seminfo +structure containing the same information as for +.BR IPC_INFO , +except that the following fields are returned with information +about system resources consumed by semaphores: the +.I semusz +field returns the number of semaphore sets that currently exist +on the system; and the +.I semaem +field returns the total number of semaphores in all semaphore sets +on the system. +.TP +.BR SEM_STAT " (Linux-specific)" +Return a +.I semid_ds +structure as for +.BR IPC_STAT . +However, the +.I semid +argument is not a semaphore identifier, but instead an index into +the kernel's internal array that maintains information about +all semaphore sets on the system. +.TP +.B GETALL +Return +.B semval +(i.e., the current value) +for all semaphores of the set into +.IR arg.array . +The argument +.I semnum +is ignored. +The calling process must have read permission on the semaphore set. +.TP +.B GETNCNT +Return the value of +.B semncnt +for the +.IR semnum \-th +semaphore of the set +(i.e., the number of processes waiting for an increase of +.B semval +for the +.IR semnum \-th +semaphore of the set). +The calling process must have read permission on the semaphore set. +.TP +.B GETPID +Return the value of +.B sempid +for the +.IR semnum \-th +semaphore of the set. +This is the PID of the process that last performed an operation on +that semaphore (but see NOTES). +The calling process must have read permission on the semaphore set. +.TP +.B GETVAL +Return the value of +.B semval +for the +.IR semnum \-th +semaphore of the set. +The calling process must have read permission on the semaphore set. +.TP +.B GETZCNT +Return the value of +.B semzcnt +for the +.IR semnum \-th +semaphore of the set +(i.e., the number of processes waiting for +.B semval +of the +.IR semnum \-th +semaphore of the set to become 0). +The calling process must have read permission on the semaphore set. +.TP +.B SETALL +Set +.B semval +for all semaphores of the set using +.IR arg.array , +updating also the +.I sem_ctime +member of the +.I semid_ds +structure associated with the set. +Undo entries (see +.BR semop (2)) +are cleared for altered semaphores in all processes. +If the changes to semaphore values would permit blocked +.BR semop (2) +calls in other processes to proceed, then those processes are woken up. +The argument +.I semnum +is ignored. +The calling process must have alter (write) permission on +the semaphore set. +.TP +.B SETVAL +Set the value of +.B semval +to +.I arg.val +for the +.IR semnum \-th +semaphore of the set, updating also the +.I sem_ctime +member of the +.I semid_ds +structure associated with the set. +Undo entries are cleared for altered semaphores in all processes. +If the changes to semaphore values would permit blocked +.BR semop (2) +calls in other processes to proceed, then those processes are woken up. +The calling process must have alter permission on the semaphore set. +.SH RETURN VALUE +On failure, +.BR semctl () +returns \-1 +with +.I errno +indicating the error. +.PP +Otherwise, the system call returns a nonnegative value depending on +.I cmd +as follows: +.TP 10 +.B GETNCNT +the value of +.BR semncnt . +.TP +.B GETPID +the value of +.BR sempid . +.TP +.B GETVAL +the value of +.BR semval . +.TP +.B GETZCNT +the value of +.BR semzcnt . +.TP +.B IPC_INFO +the index of the highest used entry in the +kernel's internal array recording information about all +semaphore sets. +(This information can be used with repeated +.B SEM_STAT +operations to obtain information about all semaphore sets on the system.) +.TP +.B SEM_INFO +as for +.BR IPC_INFO . +.TP +.B SEM_STAT +the identifier of the semaphore set whose index was given in +.IR semid . +.PP +All other +.I cmd +values return 0 on success. +.SH ERRORS +On failure, +.I errno +will be set to one of the following: +.TP +.B EACCES +The argument +.I cmd +has one of the values +.BR GETALL , +.BR GETPID , +.BR GETVAL , +.BR GETNCNT , +.BR GETZCNT , +.BR IPC_STAT , +.BR SEM_STAT , +.BR SETALL , +or +.B SETVAL +and the calling process does not have the required +permissions on the semaphore set and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The address pointed to by +.I arg.buf +or +.I arg.array +isn't accessible. +.TP +.B EIDRM +The semaphore set was removed. +.TP +.B EINVAL +Invalid value for +.I cmd +or +.IR semid . +Or: for a +.B SEM_STAT +operation, the index value specified in +.I semid +referred to an array slot that is currently unused. +.TP +.B EPERM +The argument +.I cmd +has the value +.B IPC_SET +or +.B IPC_RMID +but the effective user ID of the calling process is not the creator +(as found in +.IR sem_perm.cuid ) +or the owner +(as found in +.IR sem_perm.uid ) +of the semaphore set, +and the process does not have the +.B CAP_SYS_ADMIN +capability. +.TP +.B ERANGE +The argument +.I cmd +has the value +.B SETALL +or +.B SETVAL +and the value to which +.B semval +is to be set (for some semaphore of the set) is less than 0 +or greater than the implementation limit +.BR SEMVMX . +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVr4 documents more error conditions EINVAL and EOVERFLOW. +.PP +POSIX.1 specifies the +.\" POSIX.1-2001, POSIX.1-2008 +.I sem_nsems +field of the +.I semid_ds +structure as having the type +.IR "unsigned\ short" , +and the field is so defined on most other systems. +It was also so defined on Linux 2.2 and earlier, +but, since Linux 2.4, the field has the type +.IR "unsigned\ long" . +.SH NOTES +The inclusion of +.I +and +.I +isn't required on Linux or by any version of POSIX. +However, +some old implementations required the inclusion of these header files, +and the SVID also documented their inclusion. +Applications intended to be portable to such old systems may need +to include these header files. +.\" Like Linux, the FreeBSD man pages still document +.\" the inclusion of these header files. +.PP +The +.BR IPC_INFO , +.B SEM_STAT +and +.B SEM_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future these may modified or moved to a +.I /proc +filesystem interface. +.PP +Various fields in a \fIstruct semid_ds\fP were typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR cmd .) +.PP +In some earlier versions of glibc, the +.I semun +union was defined in \fI\fP, but POSIX.1 requires +.\" POSIX.1-2001, POSIX.1-2008 +that the caller define this union. +On versions of glibc where this union is \fInot\fP defined, +the macro +.B _SEM_SEMUN_UNDEFINED +is defined in \fI\fP. +.PP +The following system limit on semaphore sets affects a +.BR semctl () +call: +.TP +.B SEMVMX +Maximum value for +.BR semval : +implementation dependent (32767). +.PP +For greater portability, it is best to always call +.BR semctl () +with four arguments. +.\" +.SS The sempid value +POSIX.1 defines +.I sempid +as the "process ID of [the] last operation" on a semaphore, +and explicitly notes that this value is set by a successful +.BR semop (2) +call, with the implication that no other interface affects the +.I sempid +value. +.PP +While some implementations conform to the behavior specified in POSIX.1, +others do not. +(The fault here probably lies with POSIX.1 inasmuch as it likely failed +to capture the full range of existing implementation behaviors.) +Various other implementations +.\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin +also update +.I sempid +for the other operations that update the value of a semaphore: the +.B SETVAL +and +.B SETALL +operations, as well as the semaphore adjustments performed +on process termination as a consequence of the use of the +.B SEM_UNDO +flag (see +.BR semop (2)). +.PP +Linux also updates +.I sempid +for +.BR SETVAL +operations and semaphore adjustments. +However, somewhat inconsistently, up to and including 4.5, +Linux did not update +.I sempid +for +.BR SETALL +operations. +This was rectified +.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f +in Linux 4.6. +.SH SEE ALSO +.BR ipc (2), +.BR semget (2), +.BR semop (2), +.BR capabilities (7), +.BR sem_overview (7), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/semget.2 b/man2/semget.2 new file mode 100644 index 0000000..8fdbb25 --- /dev/null +++ b/man2/semget.2 @@ -0,0 +1,321 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond +.\" Modified 1 Jan 2002, Martin Schulze +.\" Modified 4 Jan 2002, Michael Kerrisk +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" Rewrote BUGS note about semget()'s failure to initialize +.\" semaphore values +.\" +.TH SEMGET 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +semget \- get a System V semaphore set identifier +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.fi +.PP +.BI "int semget(key_t " key , +.BI "int " nsems , +.BI "int " semflg ); +.SH DESCRIPTION +The +.BR semget () +system call returns the System\ V semaphore set identifier +associated with the argument +.IR key . +A new set of +.I nsems +semaphores is created if +.I key +has the value +.B IPC_PRIVATE +or if no existing semaphore set is associated with +.I key +and +.B IPC_CREAT +is specified in +.IR semflg . +.PP +If +.I semflg +specifies both +.B IPC_CREAT +and +.B IPC_EXCL +and a semaphore set already exists for +.IR key , +then +.BR semget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) +.PP +Upon creation, the least significant 9 bits of the argument +.I semflg +define the permissions (for owner, group and others) +for the semaphore set. +These bits have the same format, and the same +meaning, as the +.I mode +argument of +.BR open (2) +(though the execute permissions are +not meaningful for semaphores, and write permissions mean permission +to alter semaphore values). +.PP +When creating a new semaphore set, +.BR semget () +initializes the set's associated data structure, +.I semid_ds +(see +.BR semctl (2)), +as follows: +.IP +.I sem_perm.cuid +and +.I sem_perm.uid +are set to the effective user ID of the calling process. +.IP +.I sem_perm.cgid +and +.I sem_perm.gid +are set to the effective group ID of the calling process. +.IP +The least significant 9 bits of +.I sem_perm.mode +are set to the least significant 9 bits of +.IR semflg . +.IP +.I sem_nsems +is set to the value of +.IR nsems . +.IP +.I sem_otime +is set to 0. +.IP +.I sem_ctime +is set to the current time. +.PP +The argument +.I nsems +can be 0 +(a don't care) +when a semaphore set is not being created. +Otherwise, +.I nsems +must be greater than 0 +and less than or equal to the maximum number of semaphores per semaphore set +.RB ( SEMMSL ). +.PP +If the semaphore set already exists, the permissions are +verified. +.\" and a check is made to see if it is marked for destruction. +.SH RETURN VALUE +If successful, the return value will be the semaphore set identifier +(a nonnegative integer), otherwise, \-1 +is returned, with +.I errno +indicating the error. +.SH ERRORS +On failure, +.I errno +will be set to one of the following: +.TP +.B EACCES +A semaphore set exists for +.IR key , +but the calling process does not have permission to access the set, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EEXIST +.B IPC_CREAT +and +.BR IPC_EXCL +were specified in +.IR semflg , +but a semaphore set already exists for +.IR key . +.\" .TP +.\" .B EIDRM +.\" The semaphore set is marked to be deleted. +.TP +.B EINVAL +.I nsems +is less than 0 or greater than the limit on the number +of semaphores per semaphore set +.RB ( SEMMSL ). +.TP +.B EINVAL +A semaphore set corresponding to +.I key +already exists, but +.I nsems +is larger than the number of semaphores in that set. +.TP +.B ENOENT +No semaphore set exists for +.I key +and +.I semflg +did not specify +.BR IPC_CREAT . +.TP +.B ENOMEM +A semaphore set has to be created but the system does not have +enough memory for the new data structure. +.TP +.B ENOSPC +A semaphore set has to be created but the system limit for the maximum +number of semaphore sets +.RB ( SEMMNI ), +or the system wide maximum number of semaphores +.RB ( SEMMNS ), +would be exceeded. +.SH CONFORMING TO +SVr4, POSIX.1-2001. +.\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN, +.\" ERANGE, EFAULT. +.SH NOTES +The inclusion of +.I +and +.I +isn't required on Linux or by any version of POSIX. +However, +some old implementations required the inclusion of these header files, +and the SVID also documented their inclusion. +Applications intended to be portable to such old systems may need +to include these header files. +.\" Like Linux, the FreeBSD man pages still document +.\" the inclusion of these header files. +.PP +.B IPC_PRIVATE +isn't a flag field but a +.I key_t +type. +If this special value is used for +.IR key , +the system call ignores all but the least significant 9 bits of +.I semflg +and creates a new semaphore set (on success). +.\" +.SS Semaphore initialization +The values of the semaphores in a newly created set are indeterminate. +(POSIX.1-2001 and POSIX.1-2008 are explicit on this point, +although POSIX.1-2008 notes that a future version of the standard +may require an implementation to initialize the semaphores to 0.) +Although Linux, like many other implementations, +initializes the semaphore values to 0, +a portable application cannot rely on this: +it should explicitly initialize the semaphores to the desired values. +.\" In truth, every one of the many implementations that I've tested sets +.\" the values to zero, but I suppose there is/was some obscure +.\" implementation out there that does not. +.PP +Initialization can be done using +.BR semctl (2) +.B SETVAL +or +.B SETALL +operation. +Where multiple peers do not know who will be the first to +initialize the set, checking for a nonzero +.I sem_otime +in the associated data structure retrieved by a +.BR semctl (2) +.B IPC_STAT +operation can be used to avoid races. +.\" +.SS Semaphore limits +The following limits on semaphore set resources affect the +.BR semget () +call: +.TP +.B SEMMNI +System-wide limit on the number of semaphore sets. +On Linux systems before version 3.19, +the default value for this limit was 128. +Since Linux 3.19, +.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 +the default value is 32,000. +On Linux, this limit can be read and modified via the fourth field of +.IR /proc/sys/kernel/sem . +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK +.TP +.B SEMMSL +Maximum number of semaphores per semaphore ID. +On Linux systems before version 3.19, +the default value for this limit was 250. +Since Linux 3.19, +.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 +the default value is 32,000. +On Linux, this limit can be read and modified via the first field of +.IR /proc/sys/kernel/sem . +.TP +.B SEMMNS +System-wide limit on the number of semaphores: policy dependent +(on Linux, this limit can be read and modified via the second field of +.IR /proc/sys/kernel/sem ). +Note that the number of semaphores system-wide +is also limited by the product of +.B SEMMSL +and +.BR SEMMNI . +.SH BUGS +The name choice +.B IPC_PRIVATE +was perhaps unfortunate, +.B IPC_NEW +would more clearly show its function. +.SH SEE ALSO +.BR semctl (2), +.BR semop (2), +.BR ftok (3), +.BR capabilities (7), +.BR sem_overview (7), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/semop.2 b/man2/semop.2 new file mode 100644 index 0000000..7d94669 --- /dev/null +++ b/man2/semop.2 @@ -0,0 +1,564 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1996-10-22, Eric S. Raymond +.\" Modified 2002-01-08, Michael Kerrisk +.\" Modified 2003-04-28, Ernie Petrides +.\" Modified 2004-05-27, Michael Kerrisk +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() +.\" 2007-07-09, mtk, Added an EXAMPLE code segment. +.\" +.TH SEMOP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +semop, semtimedop \- System V semaphore operations +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int semop(int " semid ", struct sembuf *" sops ", size_t " nsops ); +.PP +.BI "int semtimedop(int " semid ", struct sembuf *" sops ", size_t " nsops , +.BI " const struct timespec *" timeout ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR semtimedop (): +_GNU_SOURCE +.SH DESCRIPTION +Each semaphore in a System\ V semaphore set +has the following associated values: +.PP +.in +4n +.EX +unsigned short semval; /* semaphore value */ +unsigned short semzcnt; /* # waiting for zero */ +unsigned short semncnt; /* # waiting for increase */ +pid_t sempid; /* PID of process that last +.in +.EE +.PP +.BR semop () +performs operations on selected semaphores in the set indicated by +.IR semid . +Each of the +.I nsops +elements in the array pointed to by +.I sops +is a structure that +specifies an operation to be performed on a single semaphore. +The elements of this structure are of type +.IR "struct sembuf" , +containing the following members: +.PP +.in +4n +.EX +unsigned short sem_num; /* semaphore number */ +short sem_op; /* semaphore operation */ +short sem_flg; /* operation flags */ +.EE +.in +.PP +Flags recognized in +.I sem_flg +are +.B IPC_NOWAIT +and +.BR SEM_UNDO . +If an operation specifies +.BR SEM_UNDO , +it will be automatically undone when the process terminates. +.PP +The set of operations contained in +.I sops +is performed in +.IR "array order" , +and +.IR atomically , +that is, the operations are performed either as a complete unit, +or not at all. +The behavior of the system call if not all operations can be +performed immediately depends on the presence of the +.B IPC_NOWAIT +flag in the individual +.I sem_flg +fields, as noted below. +.PP +Each operation is performed on the +.IR sem_num \-th +semaphore of the semaphore set, where the first semaphore of the set +is numbered 0. +There are three types of operation, distinguished by the value of +.IR sem_op . +.PP +If +.I sem_op +is a positive integer, the operation adds this value to +the semaphore value +.RI ( semval ). +Furthermore, if +.B SEM_UNDO +is specified for this operation, the system subtracts the value +.I sem_op +from the semaphore adjustment +.RI ( semadj ) +value for this semaphore. +This operation can always proceed\(emit never forces a thread to wait. +The calling process must have alter permission on the semaphore set. +.PP +If +.I sem_op +is zero, the process must have read permission on the semaphore +set. +This is a "wait-for-zero" operation: if +.I semval +is zero, the operation can immediately proceed. +Otherwise, if +.B IPC_NOWAIT +is specified in +.IR sem_flg , +.BR semop () +fails with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +Otherwise, +.I semzcnt +(the count of threads waiting until this semaphore's value becomes zero) +is incremented by one and the thread sleeps until +one of the following occurs: +.IP \(bu 3 +.I semval +becomes 0, at which time the value of +.I semzcnt +is decremented. +.IP \(bu +The semaphore set +is removed: +.BR semop () +fails, with +.I errno +set to +.BR EIDRM . +.IP \(bu +The calling thread catches a signal: +the value of +.I semzcnt +is decremented and +.BR semop () +fails, with +.I errno +set to +.BR EINTR . +.PP +If +.I sem_op +is less than zero, the process must have alter permission on the +semaphore set. +If +.I semval +is greater than or equal to the absolute value of +.IR sem_op , +the operation can proceed immediately: +the absolute value of +.I sem_op +is subtracted from +.IR semval , +and, if +.B SEM_UNDO +is specified for this operation, the system adds the absolute value of +.I sem_op +to the semaphore adjustment +.RI ( semadj ) +value for this semaphore. +If the absolute value of +.I sem_op +is greater than +.IR semval , +and +.B IPC_NOWAIT +is specified in +.IR sem_flg , +.BR semop () +fails, with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +Otherwise, +.I semncnt +(the counter of threads waiting for this semaphore's value to increase) +is incremented by one and the thread sleeps until +one of the following occurs: +.IP \(bu 3 +.I semval +becomes greater than or equal to the absolute value of +.IR sem_op : +the operation now proceeds, as described above. +.IP \(bu +The semaphore set is removed from the system: +.BR semop () +fails, with +.I errno +set to +.BR EIDRM . +.IP \(bu +The calling thread catches a signal: +the value of +.I semncnt +is decremented and +.BR semop () +fails, with +.I errno +set to +.BR EINTR . +.PP +On successful completion, the +.I sempid +value for each semaphore specified in the array pointed to by +.I sops +is set to the caller's process ID. +In addition, the +.I sem_otime +.\" and +.\" .I sem_ctime +is set to the current time. +.SS semtimedop() +.BR semtimedop () +behaves identically to +.BR semop () +except that in those cases where the calling thread would sleep, +the duration of that sleep is limited by the amount of elapsed +time specified by the +.I timespec +structure whose address is passed in the +.I timeout +argument. +(This sleep interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the interval +may overrun by a small amount.) +If the specified time limit has been reached, +.BR semtimedop () +fails with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +If the +.I timeout +argument is NULL, +then +.BR semtimedop () +behaves exactly like +.BR semop (). +.PP +Note that if +.BR semtimedop () +is interrupted by a signal, causing the call to fail with the error +.BR EINTR , +the contents of +.IR timeout +are left unchanged. +.SH RETURN VALUE +If successful, +.BR semop () +and +.BR semtimedop () +return 0; +otherwise they return \-1 +with +.I errno +indicating the error. +.SH ERRORS +On failure, +.I errno +is set to one of the following: +.TP +.B E2BIG +The argument +.I nsops +is greater than +.BR SEMOPM , +the maximum number of operations allowed per system +call. +.TP +.B EACCES +The calling process does not have the permissions required +to perform the specified semaphore operations, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EAGAIN +An operation could not proceed immediately and either +.B IPC_NOWAIT +was specified in +.I sem_flg +or the time limit specified in +.I timeout +expired. +.TP +.B EFAULT +An address specified in either the +.I sops +or the +.I timeout +argument isn't accessible. +.TP +.B EFBIG +For some operation the value of +.I sem_num +is less than 0 or greater than or equal to the number +of semaphores in the set. +.TP +.B EIDRM +The semaphore set was removed. +.TP +.B EINTR +While blocked in this system call, the thread caught a signal; see +.BR signal (7). +.TP +.B EINVAL +The semaphore set doesn't exist, or +.I semid +is less than zero, or +.I nsops +has a nonpositive value. +.TP +.B ENOMEM +The +.I sem_flg +of some operation specified +.B SEM_UNDO +and the system does not have enough memory to allocate the undo +structure. +.TP +.B ERANGE +For some operation +.I sem_op+semval +is greater than +.BR SEMVMX , +the implementation dependent maximum value for +.IR semval . +.SH VERSIONS +.BR semtimedop () +first appeared in Linux 2.5.52, +and was subsequently backported into kernel 2.4.22. +Glibc support for +.BR semtimedop () +first appeared in version 2.3.3. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC. +.SH NOTES +The inclusion of +.I +and +.I +isn't required on Linux or by any version of POSIX. +However, +some old implementations required the inclusion of these header files, +and the SVID also documented their inclusion. +Applications intended to be portable to such old systems may need +to include these header files. +.\" Like Linux, the FreeBSD man pages still document +.\" the inclusion of these header files. +.PP +The +.I sem_undo +structures of a process aren't inherited by the child produced by +.BR fork (2), +but they are inherited across an +.BR execve (2) +system call. +.PP +.BR semop () +is never automatically restarted after being interrupted by a signal handler, +regardless of the setting of the +.B SA_RESTART +flag when establishing a signal handler. +.PP +A semaphore adjustment +.RI ( semadj ) +value is a per-process, per-semaphore integer that is the negated sum +of all operations performed on a semaphore specifying the +.B SEM_UNDO +flag. +Each process has a list of +.I semadj +values\(emone value for each semaphore on which it has operated using +.BR SEM_UNDO . +When a process terminates, each of its per-semaphore +.I semadj +values is added to the corresponding semaphore, +thus undoing the effect of that process's operations on the semaphore +(but see BUGS below). +When a semaphore's value is directly set using the +.B SETVAL +or +.B SETALL +request to +.BR semctl (2), +the corresponding +.I semadj +values in all processes are cleared. +The +.BR clone (2) +.B CLONE_SYSVSEM +flag allows more than one process to share a +.I semadj +list; see +.BR clone (2) +for details. +.PP +The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values +for a semaphore can all be retrieved using appropriate +.BR semctl (2) +calls. +.SS Semaphore limits +The following limits on semaphore set resources affect the +.BR semop () +call: +.TP +.B SEMOPM +Maximum number of operations allowed for one +.BR semop () +call. +Before Linux 3.19, +.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 +the default value for this limit was 32. +Since Linux 3.19, the default value is 500. +On Linux, this limit can be read and modified via the third field of +.IR /proc/sys/kernel/sem . +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK +.IR Note : +this limit should not be raised above 1000, +.\" See comment in Linux 3.19 source file include/uapi/linux/sem.h +because of the risk of that +.BR semop () +fails due to kernel memory fragmentation when allocating memory to copy the +.IR sops +array. +.TP +.B SEMVMX +Maximum allowable value for +.IR semval : +implementation dependent (32767). +.PP +The implementation has no intrinsic limits for +the adjust on exit maximum value +.RB ( SEMAEM ), +the system wide maximum number of undo structures +.RB ( SEMMNU ) +and the per-process maximum number of undo entries system parameters. +.SH BUGS +When a process terminates, its set of associated +.I semadj +structures is used to undo the effect of all of the +semaphore operations it performed with the +.B SEM_UNDO +flag. +This raises a difficulty: if one (or more) of these semaphore adjustments +would result in an attempt to decrease a semaphore's value below zero, +what should an implementation do? +One possible approach would be to block until all the semaphore +adjustments could be performed. +This is however undesirable since it could force process termination to +block for arbitrarily long periods. +Another possibility is that such semaphore adjustments could be ignored +altogether (somewhat analogously to failing when +.B IPC_NOWAIT +is specified for a semaphore operation). +Linux adopts a third approach: decreasing the semaphore value +as far as possible (i.e., to zero) and allowing process +termination to proceed immediately. +.PP +In kernels 2.6.x, x <= 10, there is a bug that in some circumstances +prevents a thread that is waiting for a semaphore value to become +zero from being woken up when the value does actually become zero. +This bug is fixed in kernel 2.6.11. +.\" The bug report: +.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2 +.\" the fix: +.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2 +.SH EXAMPLE +The following code segment uses +.BR semop () +to atomically wait for the value of semaphore 0 to become zero, +and then increment the semaphore value by one. +.PP +.in +4n +.EX +struct sembuf sops[2]; +int semid; + +/* Code to set \fIsemid\fP omitted */ + +sops[0].sem_num = 0; /* Operate on semaphore 0 */ +sops[0].sem_op = 0; /* Wait for value to equal 0 */ +sops[0].sem_flg = 0; + +sops[1].sem_num = 0; /* Operate on semaphore 0 */ +sops[1].sem_op = 1; /* Increment value by one */ +sops[1].sem_flg = 0; + +if (semop(semid, sops, 2) == \-1) { + perror("semop"); + exit(EXIT_FAILURE); +} +.EE +.in +.SH SEE ALSO +.BR clone (2), +.BR semctl (2), +.BR semget (2), +.BR sigaction (2), +.BR capabilities (7), +.BR sem_overview (7), +.BR svipc (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/semtimedop.2 b/man2/semtimedop.2 new file mode 100644 index 0000000..8a40618 --- /dev/null +++ b/man2/semtimedop.2 @@ -0,0 +1 @@ +.so man2/semop.2 diff --git a/man2/send.2 b/man2/send.2 new file mode 100644 index 0000000..e0bea6d --- /dev/null +++ b/man2/send.2 @@ -0,0 +1,491 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified Oct 1998 by Andi Kleen +.\" Modified Oct 2003 by aeb +.\" Modified 2004-07-01 by mtk +.\" +.TH SEND 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +send, sendto, sendmsg \- send a message on a socket +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "ssize_t send(int " sockfd ", const void *" buf ", size_t " len \ +", int " flags ); +.PP +.BI "ssize_t sendto(int " sockfd ", const void *" buf ", size_t " len \ +", int " flags , +.BI " const struct sockaddr *" dest_addr ", socklen_t " addrlen ); +.PP +.BI "ssize_t sendmsg(int " sockfd ", const struct msghdr *" msg \ +", int " flags ); +.fi +.SH DESCRIPTION +The system calls +.BR send (), +.BR sendto (), +and +.BR sendmsg () +are used to transmit a message to another socket. +.PP +The +.BR send () +call may be used only when the socket is in a +.I connected +state (so that the intended recipient is known). +The only difference between +.BR send () +and +.BR write (2) +is the presence of +.IR flags . +With a zero +.I flags +argument, +.BR send () +is equivalent to +.BR write (2). +Also, the following call +.PP + send(sockfd, buf, len, flags); +.PP +is equivalent to +.PP + sendto(sockfd, buf, len, flags, NULL, 0); +.PP +The argument +.I sockfd +is the file descriptor of the sending socket. +.PP +If +.BR sendto () +is used on a connection-mode +.RB ( SOCK_STREAM , +.BR SOCK_SEQPACKET ) +socket, the arguments +.I dest_addr +and +.I addrlen +are ignored (and the error +.B EISCONN +may be returned when they are +not NULL and 0), and the error +.B ENOTCONN +is returned when the socket was not actually connected. +Otherwise, the address of the target is given by +.I dest_addr +with +.I addrlen +specifying its size. +For +.BR sendmsg (), +the address of the target is given by +.IR msg.msg_name , +with +.I msg.msg_namelen +specifying its size. +.PP +For +.BR send () +and +.BR sendto (), +the message is found in +.I buf +and has length +.IR len . +For +.BR sendmsg (), +the message is pointed to by the elements of the array +.IR msg.msg_iov . +The +.BR sendmsg () +call also allows sending ancillary data (also known as control information). +.PP +If the message is too long to pass atomically through the +underlying protocol, the error +.B EMSGSIZE +is returned, and the message is not transmitted. +.PP +No indication of failure to deliver is implicit in a +.BR send (). +Locally detected errors are indicated by a return value of \-1. +.PP +When the message does not fit into the send buffer of the socket, +.BR send () +normally blocks, unless the socket has been placed in nonblocking I/O +mode. +In nonblocking mode it would fail with the error +.B EAGAIN +or +.B EWOULDBLOCK +in this case. +The +.BR select (2) +call may be used to determine when it is possible to send more data. +.SS The flags argument +The +.I flags +argument is the bitwise OR +of zero or more of the following flags. +.\" FIXME . ? document MSG_PROXY (which went away in 2.3.15) +.TP +.BR MSG_CONFIRM " (since Linux 2.3.15)" +Tell the link layer that forward progress happened: you got a successful +reply from the other side. +If the link layer doesn't get this +it will regularly reprobe the neighbor (e.g., via a unicast ARP). +Valid only on +.B SOCK_DGRAM +and +.B SOCK_RAW +sockets and currently implemented only for IPv4 and IPv6. +See +.BR arp (7) +for details. +.TP +.B MSG_DONTROUTE +Don't use a gateway to send out the packet, send to hosts only on +directly connected networks. +This is usually used only +by diagnostic or routing programs. +This is defined only for protocol +families that route; packet sockets don't. +.TP +.BR MSG_DONTWAIT " (since Linux 2.2)" +Enables nonblocking operation; if the operation would block, +.B EAGAIN +or +.B EWOULDBLOCK +is returned. +This provides similar behavior to setting the +.B O_NONBLOCK +flag (via the +.BR fcntl (2) +.B F_SETFL +operation), but differs in that +.B MSG_DONTWAIT +is a per-call option, whereas +.B O_NONBLOCK +is a setting on the open file description (see +.BR open (2)), +which will affect all threads in the calling process +and as well as other processes that hold file descriptors +referring to the same open file description. +.TP +.BR MSG_EOR " (since Linux 2.2)" +Terminates a record (when this notion is supported, as for sockets of type +.BR SOCK_SEQPACKET ). +.TP +.BR MSG_MORE " (since Linux 2.4.4)" +The caller has more data to send. +This flag is used with TCP sockets to obtain the same effect +as the +.B TCP_CORK +socket option (see +.BR tcp (7)), +with the difference that this flag can be set on a per-call basis. +.IP +Since Linux 2.6, this flag is also supported for UDP sockets, and informs +the kernel to package all of the data sent in calls with this flag set +into a single datagram which is transmitted only when a call is performed +that does not specify this flag. +(See also the +.B UDP_CORK +socket option described in +.BR udp (7).) +.TP +.BR MSG_NOSIGNAL " (since Linux 2.2)" +Don't generate a +.B SIGPIPE +signal if the peer on a stream-oriented socket has closed the connection. +The +.B EPIPE +error is still returned. +This provides similar behavior to using +.BR sigaction (2) +to ignore +.BR SIGPIPE , +but, whereas +.B MSG_NOSIGNAL +is a per-call feature, +ignoring +.B SIGPIPE +sets a process attribute that affects all threads in the process. +.TP +.B MSG_OOB +Sends +.I out-of-band +data on sockets that support this notion (e.g., of type +.BR SOCK_STREAM ); +the underlying protocol must also support +.I out-of-band +data. +.SS sendmsg() +The definition of the +.I msghdr +structure employed by +.BR sendmsg () +is as follows: +.PP +.in +4n +.EX +struct msghdr { + void *msg_name; /* optional address */ + socklen_t msg_namelen; /* size of address */ + struct iovec *msg_iov; /* scatter/gather array */ + size_t msg_iovlen; /* # elements in msg_iov */ + void *msg_control; /* ancillary data, see below */ + size_t msg_controllen; /* ancillary data buffer len */ + int msg_flags; /* flags (unused) */ +}; +.EE +.in +.PP +The +.I msg_name +field is used on an unconnected socket to specify the target +address for a datagram. +It points to a buffer containing the address; the +.I msg_namelen +field should be set to the size of the address. +For a connected socket, these fields should be specified as NULL and 0, +respectively. +.PP +The +.I msg_iov +and +.I msg_iovlen +fields specify scatter-gather locations, as for +.BR writev (2). +.PP +You may send control information using the +.I msg_control +and +.I msg_controllen +members. +The maximum control buffer length the kernel can process is limited +per socket by the value in +.IR /proc/sys/net/core/optmem_max ; +see +.BR socket (7). +.PP +The +.I msg_flags +field is ignored. +.\" Still to be documented: +.\" Send file descriptors and user credentials using the +.\" msg_control* fields. +.SH RETURN VALUE +On success, these calls return the number of bytes sent. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +These are some standard errors generated by the socket layer. +Additional errors +may be generated and returned from the underlying protocol modules; +see their respective manual pages. +.TP +.B EACCES +(For UNIX domain sockets, which are identified by pathname) +Write permission is denied on the destination socket file, +or search permission is denied for one of the directories +the path prefix. +(See +.BR path_resolution (7).) +.IP +(For UDP sockets) An attempt was made to send to a +network/broadcast address as though it was a unicast address. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The socket is marked nonblocking and the requested operation +would block. +POSIX.1-2001 allows either error to be returned for this case, +and does not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EAGAIN +(Internet domain datagram sockets) +The socket referred to by +.I sockfd +had not previously been bound to an address and, +upon attempting to bind it to an ephemeral port, +it was determined that all port numbers in the ephemeral port range +are currently in use. +See the discussion of +.I /proc/sys/net/ipv4/ip_local_port_range +in +.BR ip (7). +.TP +.B EALREADY +Another Fast Open is in progress. +.TP +.B EBADF +.I sockfd +is not a valid open file descriptor. +.TP +.B ECONNRESET +Connection reset by peer. +.TP +.B EDESTADDRREQ +The socket is not connection-mode, and no peer address is set. +.TP +.B EFAULT +An invalid user space address was specified for an argument. +.TP +.B EINTR +A signal occurred before any data was transmitted; see +.BR signal (7). +.TP +.B EINVAL +Invalid argument passed. +.TP +.B EISCONN +The connection-mode socket was connected already but a +recipient was specified. +(Now either this error is returned, or the recipient specification +is ignored.) +.TP +.B EMSGSIZE +The socket type +.\" (e.g., SOCK_DGRAM ) +requires that message be sent atomically, and the size +of the message to be sent made this impossible. +.TP +.B ENOBUFS +The output queue for a network interface was full. +This generally indicates that the interface has stopped sending, +but may be caused by transient congestion. +(Normally, this does not occur in Linux. +Packets are just silently dropped +when a device queue overflows.) +.TP +.B ENOMEM +No memory available. +.TP +.B ENOTCONN +The socket is not connected, and no target has been given. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.TP +.B EOPNOTSUPP +Some bit in the +.I flags +argument is inappropriate for the socket type. +.TP +.B EPIPE +The local end has been shut down on a connection oriented socket. +In this case, the process +will also receive a +.B SIGPIPE +unless +.B MSG_NOSIGNAL +is set. +.SH CONFORMING TO +4.4BSD, SVr4, POSIX.1-2001. +These interfaces first appeared in 4.2BSD. +.PP +POSIX.1-2001 describes only the +.B MSG_OOB +and +.B MSG_EOR +flags. +POSIX.1-2008 adds a specification of +.BR MSG_NOSIGNAL . +The +.B MSG_CONFIRM +flag is a Linux extension. +.SH NOTES +According to POSIX.1-2001, the +.I msg_controllen +field of the +.I msghdr +structure should be typed as +.IR socklen_t , +but glibc currently types it as +.IR size_t . +.\" glibc bug raised 12 Mar 2006 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 +.\" The problem is an underlying kernel issue: the size of the +.\" __kernel_size_t type used to type this field varies +.\" across architectures, but socklen_t is always 32 bits. +.PP +See +.BR sendmmsg (2) +for information about a Linux-specific system call +that can be used to transmit multiple datagrams in a single call. +.SH BUGS +Linux may return +.B EPIPE +instead of +.BR ENOTCONN . +.SH EXAMPLE +An example of the use of +.BR sendto () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR fcntl (2), +.BR getsockopt (2), +.BR recv (2), +.BR select (2), +.BR sendfile (2), +.BR sendmmsg (2), +.BR shutdown (2), +.BR socket (2), +.BR write (2), +.BR cmsg (3), +.BR ip (7), +.BR ipv6 (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sendfile.2 b/man2/sendfile.2 new file mode 100644 index 0000000..81b627c --- /dev/null +++ b/man2/sendfile.2 @@ -0,0 +1,253 @@ +.\" This man page is Copyright (C) 1998 Pawel Krawczyk. +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $ +.\" 2000-11-19 bert hubert : in_fd cannot be socket +.\" +.\" 2004-12-17, mtk +.\" updated description of in_fd and out_fd for 2.6 +.\" Various wording and formatting changes +.\" +.\" 2005-03-31 Martin Pool mmap() improvements +.\" +.TH SENDFILE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sendfile \- transfer data between file descriptors +.SH SYNOPSIS +.B #include +.PP +.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ + offset ", size_t" " count" ); +.\" The below is too ugly. Comments about glibc versions belong +.\" in the notes, not in the header. +.\" +.\" .B #include +.\" .br +.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2 +.\" .br +.\" .B #include +.\" .br +.\" #else +.\" .br +.\" .B #include +.\" .br +.\" .B /* No system prototype before glibc 2.1. */ +.\" .br +.\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ +.\" offset ", size_t" " count" ) +.\" .br +.\" .B #endif +.\" +.SH DESCRIPTION +.BR sendfile () +copies data between one file descriptor and another. +Because this copying is done within the kernel, +.BR sendfile () +is more efficient than the combination of +.BR read (2) +and +.BR write (2), +which would require transferring data to and from user space. +.PP +.I in_fd +should be a file descriptor opened for reading and +.I out_fd +should be a descriptor opened for writing. +.PP +If +.I offset +is not NULL, then it points +to a variable holding the file offset from which +.BR sendfile () +will start reading data from +.IR in_fd . +When +.BR sendfile () +returns, this variable +will be set to the offset of the byte following the last byte that was read. +If +.I offset +is not NULL, then +.BR sendfile () +does not modify the file offset of +.IR in_fd ; +otherwise the file offset is adjusted to reflect +the number of bytes read from +.IR in_fd . +.PP +If +.I offset +is NULL, then data will be read from +.IR in_fd +starting at the file offset, +and the file offset will be updated by the call. +.PP +.I count +is the number of bytes to copy between the file descriptors. +.PP +The +.IR in_fd +argument must correspond to a file which supports +.BR mmap (2)-like +operations +(i.e., it cannot be a socket). +.PP +In Linux kernels before 2.6.33, +.I out_fd +must refer to a socket. +Since Linux 2.6.33 it can be any file. +If it is a regular file, then +.BR sendfile () +changes the file offset appropriately. +.SH RETURN VALUE +If the transfer was successful, the number of bytes written to +.I out_fd +is returned. +Note that a successful call to +.BR sendfile () +may write fewer bytes than requested; +the caller should be prepared to retry the call if there were unsent bytes. +See also NOTES. +.PP +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +Nonblocking I/O has been selected using +.B O_NONBLOCK +and the write would block. +.TP +.B EBADF +The input file was not opened for reading or the output file +was not opened for writing. +.TP +.B EFAULT +Bad address. +.TP +.B EINVAL +Descriptor is not valid or locked, or an +.BR mmap (2)-like +operation is not available for +.IR in_fd , +or +.I count +is negative. +.TP +.B EINVAL +.I out_fd +has the +.B O_APPEND +flag set. +This is not currently supported by +.BR sendfile (). +.TP +.B EIO +Unspecified error while reading from +.IR in_fd . +.TP +.B ENOMEM +Insufficient memory to read from +.IR in_fd . +.TP +.B EOVERFLOW +.I count +is too large, the operation would result in exceeding the maximum size of either +the input file or the output file. +.TP +.B ESPIPE +.I offset +is not NULL but the input file is not +.BR seek (2)-able. +.SH VERSIONS +.BR sendfile () +first appeared in Linux 2.2. +The include file +.I +is present since glibc 2.1. +.SH CONFORMING TO +Not specified in POSIX.1-2001, nor in other standards. +.PP +Other UNIX systems implement +.BR sendfile () +with different semantics and prototypes. +It should not be used in portable programs. +.SH NOTES +.BR sendfile () +will transfer at most 0x7ffff000 (2,147,479,552) bytes, +returning the number of bytes actually transferred. +.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 +(This is true on both 32-bit and 64-bit systems.) +.PP +If you plan to use +.BR sendfile () +for sending files to a TCP socket, but need +to send some header data in front of the file contents, you will find +it useful to employ the +.B TCP_CORK +option, described in +.BR tcp (7), +to minimize the number of packets and to tune performance. +.PP +In Linux 2.4 and earlier, +.I out_fd +could also refer to a regular file; +this possibility went away in the Linux 2.6.x kernel series, +but was restored in Linux 2.6.33. +.PP +The original Linux +.BR sendfile () +system call was not designed to handle large file offsets. +Consequently, Linux 2.4 added +.BR sendfile64 (), +with a wider type for the +.I offset +argument. +The glibc +.BR sendfile () +wrapper function transparently deals with the kernel differences. +.PP +Applications may wish to fall back to +.BR read (2)/ write (2) +in the case where +.BR sendfile () +fails with +.B EINVAL +or +.BR ENOSYS . +.PP +If +.I out_fd +refers to a socket or pipe with zero-copy support, callers must ensure the +transferred portions of the file referred to by +.I in_fd +remain unmodified until the reader on the other end of +.I out_fd +has consumed the transferred data. +.PP +The Linux-specific +.BR splice (2) +call supports transferring data between arbitrary file descriptors +provided one (or both) of them is a pipe. +.SH SEE ALSO +.BR copy_file_range (2), +.BR mmap (2), +.BR open (2), +.BR socket (2), +.BR splice (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sendfile64.2 b/man2/sendfile64.2 new file mode 100644 index 0000000..888077b --- /dev/null +++ b/man2/sendfile64.2 @@ -0,0 +1 @@ +.so man2/sendfile.2 diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2 new file mode 100644 index 0000000..85419c3 --- /dev/null +++ b/man2/sendmmsg.2 @@ -0,0 +1,258 @@ +.\" Copyright (c) 2012 by Michael Kerrisk +.\" with some material from a draft by +.\" Stephan Mueller +.\" in turn based on Andi Kleen's recvmmsg.2 page. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SENDMMSG 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +sendmmsg \- send multiple messages on a socket +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.BI "#include " +.PP +.BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \ +", unsigned int " vlen "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +The +.BR sendmmsg () +system call is an extension of +.BR sendmsg (2) +that allows the caller to transmit multiple messages on a socket +using a single system call. +(This has performance benefits for some applications.) +.\" See commit 228e548e602061b08ee8e8966f567c12aa079682 +.PP +The +.I sockfd +argument is the file descriptor of the socket +on which data is to be transmitted. +.PP +The +.I msgvec +argument is a pointer to an array of +.I mmsghdr +structures. +The size of this array is specified in +.IR vlen . +.PP +The +.I mmsghdr +structure is defined in +.I +as: +.PP +.in +4n +.EX +struct mmsghdr { + struct msghdr msg_hdr; /* Message header */ + unsigned int msg_len; /* Number of bytes transmitted */ +}; +.EE +.in +.PP +The +.I msg_hdr +field is a +.I msghdr +structure, as described in +.BR sendmsg (2). +The +.I msg_len +field is used to return the number of bytes sent from the message in +.IR msg_hdr +(i.e., the same as the return value from a single +.BR sendmsg (2) +call). +.PP +The +.I flags +argument contains flags ORed together. +The flags are the same as for +.BR sendmsg (2). +.PP +A blocking +.BR sendmmsg () +call blocks until +.I vlen +messages have been sent. +A nonblocking call sends as many messages as possible +(up to the limit specified by +.IR vlen ) +and returns immediately. +.PP +On return from +.BR sendmmsg (), +the +.I msg_len +fields of successive elements of +.IR msgvec +are updated to contain the number of bytes transmitted from the corresponding +.IR msg_hdr . +The return value of the call indicates the number of elements of +.I msgvec +that have been updated. +.SH RETURN VALUE +On success, +.BR sendmmsg () +returns the number of messages sent from +.IR msgvec ; +if this is less than +.IR vlen , +the caller can retry with a further +.BR sendmmsg () +call to send the remaining messages. +.PP +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Errors are as for +.BR sendmsg (2). +An error is returned only if no datagrams could be sent. +See also BUGS. +.\" commit 728ffb86f10873aaf4abd26dde691ee40ae731fe +.\" ... only return an error if no datagrams could be sent. +.\" If less than the requested number of messages were sent, the application +.\" must retry starting at the first failed one and if the problem is +.\" persistent the error will be returned. +.\" +.\" This matches the behavior of other syscalls like read/write - it +.\" is not an error if less than the requested number of elements are sent. +.SH VERSIONS +The +.BR sendmmsg () +system call was added in Linux 3.0. +Support in glibc was added in version 2.14. +.SH CONFORMING TO +.BR sendmmsg () +is Linux-specific. +.SH NOTES +The value specified in +.I vlen +is capped to +.B UIO_MAXIOV +(1024). +.\" commit 98382f419f32d2c12d021943b87dea555677144b +.\" net: Cap number of elements for sendmmsg +.\" +.\" To limit the amount of time we can spend in sendmmsg, cap the +.\" number of elements to UIO_MAXIOV (currently 1024). +.\" +.\" For error handling an application using sendmmsg needs to retry at +.\" the first unsent message, so capping is simpler and requires less +.\" application logic than returning EINVAL. +.SH BUGS +If an error occurs after at least one message has been sent, +the call succeeds, and returns the number of messages sent. +The error code is lost. +The caller can retry the transmission, +starting at the first failed message, but there is no guarantee that, +if an error is returned, it will be the same as the one that was lost +on the previous call. +.SH EXAMPLE +The example below uses +.BR sendmmsg () +to send +.I onetwo +and +.I three +in two distinct UDP datagrams using one system call. +The contents of the first datagram originates from a pair of buffers. +.PP +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +int +main(void) +{ + int sockfd; + struct sockaddr_in addr; + struct mmsghdr msg[2]; + struct iovec msg1[2], msg2; + int retval; + + sockfd = socket(AF_INET, SOCK_DGRAM, 0); + if (sockfd == \-1) { + perror("socket()"); + exit(EXIT_FAILURE); + } + + addr.sin_family = AF_INET; + addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + addr.sin_port = htons(1234); + if (connect(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { + perror("connect()"); + exit(EXIT_FAILURE); + } + + memset(msg1, 0, sizeof(msg1)); + msg1[0].iov_base = "one"; + msg1[0].iov_len = 3; + msg1[1].iov_base = "two"; + msg1[1].iov_len = 3; + + memset(&msg2, 0, sizeof(msg2)); + msg2.iov_base = "three"; + msg2.iov_len = 5; + + memset(msg, 0, sizeof(msg)); + msg[0].msg_hdr.msg_iov = msg1; + msg[0].msg_hdr.msg_iovlen = 2; + + msg[1].msg_hdr.msg_iov = &msg2; + msg[1].msg_hdr.msg_iovlen = 1; + + retval = sendmmsg(sockfd, msg, 2, 0); + if (retval == \-1) + perror("sendmmsg()"); + else + printf("%d messages sent\\n", retval); + + exit(0); +} +.EE +.SH SEE ALSO +.BR recvmmsg (2), +.BR sendmsg (2), +.BR socket (2), +.BR socket (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sendmsg.2 b/man2/sendmsg.2 new file mode 100644 index 0000000..9a61b33 --- /dev/null +++ b/man2/sendmsg.2 @@ -0,0 +1 @@ +.so man2/send.2 diff --git a/man2/sendto.2 b/man2/sendto.2 new file mode 100644 index 0000000..9a61b33 --- /dev/null +++ b/man2/sendto.2 @@ -0,0 +1 @@ +.so man2/send.2 diff --git a/man2/set_mempolicy.2 b/man2/set_mempolicy.2 new file mode 100644 index 0000000..8ed929d --- /dev/null +++ b/man2/set_mempolicy.2 @@ -0,0 +1,331 @@ +.\" Copyright 2003,2004 Andi Kleen, SuSE Labs. +.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard +.\" +.\" %%%LICENSE_START(VERBATIM_PROF) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2006-02-03, mtk, substantial wording changes and other improvements +.\" 2007-08-27, Lee Schermerhorn +.\" more precise specification of behavior. +.\" +.TH SET_MEMPOLICY 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +set_mempolicy \- set default NUMA memory policy for a thread and its children +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "long set_mempolicy(int " mode ", const unsigned long *" nodemask , +.BI " unsigned long " maxnode ); +.PP +Link with \fI\-lnuma\fP. +.fi +.SH DESCRIPTION +.BR set_mempolicy () +sets the NUMA memory policy of the calling thread, +which consists of a policy mode and zero or more nodes, +to the values specified by the +.IR mode , +.I nodemask +and +.I maxnode +arguments. +.PP +A NUMA machine has different +memory controllers with different distances to specific CPUs. +The memory policy defines from which node memory is allocated for +the thread. +.PP +This system call defines the default policy for the thread. +The thread policy governs allocation of pages in the process's +address space outside of memory ranges +controlled by a more specific policy set by +.BR mbind (2). +The thread default policy also controls allocation of any pages for +memory-mapped files mapped using the +.BR mmap (2) +call with the +.B MAP_PRIVATE +flag and that are only read (loaded) from by the thread +and of memory-mapped files mapped using the +.BR mmap (2) +call with the +.B MAP_SHARED +flag, regardless of the access type. +The policy is applied only when a new page is allocated +for the thread. +For anonymous memory this is when the page is first +touched by the thread. +.PP +The +.I mode +argument must specify one of +.BR MPOL_DEFAULT , +.BR MPOL_BIND , +.BR MPOL_INTERLEAVE , +.BR MPOL_PREFERRED , +or +.BR MPOL_LOCAL +(which are described in detail below). +All modes except +.B MPOL_DEFAULT +require the caller to specify the node or nodes to which the mode applies, +via the +.I nodemask +argument. +.PP +The +.I mode +argument may also include an optional +.IR "mode flag" . +The supported +.I "mode flags" +are: +.TP +.BR MPOL_F_STATIC_NODES " (since Linux 2.6.26)" +A nonempty +.I nodemask +specifies physical node IDs. +Linux will not remap the +.I nodemask +when the process moves to a different cpuset context, +nor when the set of nodes allowed by the process's +current cpuset context changes. +.TP +.BR MPOL_F_RELATIVE_NODES " (since Linux 2.6.26)" +A nonempty +.I nodemask +specifies node IDs that are relative to the set of +node IDs allowed by the process's current cpuset. +.PP +.I nodemask +points to a bit mask of node IDs that contains up to +.I maxnode +bits. +The bit mask size is rounded to the next multiple of +.IR "sizeof(unsigned long)" , +but the kernel will use bits only up to +.IR maxnode . +A NULL value of +.I nodemask +or a +.I maxnode +value of zero specifies the empty set of nodes. +If the value of +.I maxnode +is zero, +the +.I nodemask +argument is ignored. +.PP +Where a +.I nodemask +is required, it must contain at least one node that is on-line, +allowed by the process's current cpuset context, +(unless the +.B MPOL_F_STATIC_NODES +mode flag is specified), +and contains memory. +If the +.B MPOL_F_STATIC_NODES +is set in +.I mode +and a required +.I nodemask +contains no nodes that are allowed by the process's current cpuset context, +the memory policy reverts to +.IR "local allocation" . +This effectively overrides the specified policy until the process's +cpuset context includes one or more of the nodes specified by +.IR nodemask . +.PP +The +.I mode +argument must include one of the following values: +.TP +.B MPOL_DEFAULT +This mode specifies that any nondefault thread memory policy be removed, +so that the memory policy "falls back" to the system default policy. +The system default policy is "local allocation"\(emthat is, +allocate memory on the node of the CPU that triggered the allocation. +.I nodemask +must be specified as NULL. +If the "local node" contains no free memory, the system will +attempt to allocate memory from a "near by" node. +.TP +.B MPOL_BIND +This mode defines a strict policy that restricts memory allocation to the +nodes specified in +.IR nodemask . +If +.I nodemask +specifies more than one node, page allocations will come from +the node with the lowest numeric node ID first, until that node +contains no free memory. +Allocations will then come from the node with the next highest +node ID specified in +.I nodemask +and so forth, until none of the specified nodes contain free memory. +Pages will not be allocated from any node not specified in the +.IR nodemask . +.IP +.TP +.B MPOL_INTERLEAVE +This mode interleaves page allocations across the nodes specified in +.I nodemask +in numeric node ID order. +This optimizes for bandwidth instead of latency +by spreading out pages and memory accesses to those pages across +multiple nodes. +However, accesses to a single page will still be limited to +the memory bandwidth of a single node. +.\" NOTE: the following sentence doesn't make sense in the context +.\" of set_mempolicy() -- no memory area specified. +.\" To be effective the memory area should be fairly large, +.\" at least 1 MB or bigger. +.TP +.B MPOL_PREFERRED +This mode sets the preferred node for allocation. +The kernel will try to allocate pages from this node first +and fall back to "near by" nodes if the preferred node is low on free +memory. +If +.I nodemask +specifies more than one node ID, the first node in the +mask will be selected as the preferred node. +If the +.I nodemask +and +.I maxnode +arguments specify the empty set, then the policy +specifies "local allocation" +(like the system default policy discussed above). +.TP +.BR MPOL_LOCAL " (since Linux 3.8)" +.\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8 +.\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f +This mode specifies "local allocation"; the memory is allocated on +the node of the CPU that triggered the allocation (the "local node"). +The +.I nodemask +and +.I maxnode +arguments must specify the empty set. +If the "local node" is low on free memory, +the kernel will try to allocate memory from other nodes. +The kernel will allocate memory from the "local node" +whenever memory for this node is available. +If the "local node" is not allowed by the process's current cpuset context, +the kernel will try to allocate memory from other nodes. +The kernel will allocate memory from the "local node" whenever +it becomes allowed by the process's current cpuset context. +.PP +The thread memory policy is preserved across an +.BR execve (2), +and is inherited by child threads created using +.BR fork (2) +or +.BR clone (2). +.SH RETURN VALUE +On success, +.BR set_mempolicy () +returns 0; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Part of all of the memory range specified by +.I nodemask +and +.I maxnode +points outside your accessible address space. +.TP +.B EINVAL +.I mode +is invalid. +Or, +.I mode +is +.B MPOL_DEFAULT +and +.I nodemask +is nonempty, +or +.I mode +is +.B MPOL_BIND +or +.B MPOL_INTERLEAVE +and +.I nodemask +is empty. +Or, +.I maxnode +specifies more than a page worth of bits. +Or, +.I nodemask +specifies one or more node IDs that are +greater than the maximum supported node ID. +Or, none of the node IDs specified by +.I nodemask +are on-line and allowed by the process's current cpuset context, +or none of the specified nodes contain memory. +Or, the +.I mode +argument specified both +.B MPOL_F_STATIC_NODES +and +.BR MPOL_F_RELATIVE_NODES . +.TP +.B ENOMEM +Insufficient kernel memory was available. +.SH VERSIONS +The +.BR set_mempolicy () +system call was added to the Linux kernel in version 2.6.7. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +Memory policy is not remembered if the page is swapped out. +When such a page is paged back in, it will use the policy of +the thread or memory range that is in effect at the time the +page is allocated. +.PP +For information on library support, see +.BR numa (7). +.SH SEE ALSO +.BR get_mempolicy (2), +.BR getcpu (2), +.BR mbind (2), +.BR mmap (2), +.BR numa (3), +.BR cpuset (7), +.BR numa (7), +.BR numactl (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/set_robust_list.2 b/man2/set_robust_list.2 new file mode 100644 index 0000000..a38aa23 --- /dev/null +++ b/man2/set_robust_list.2 @@ -0,0 +1 @@ +.so man2/get_robust_list.2 diff --git a/man2/set_thread_area.2 b/man2/set_thread_area.2 new file mode 100644 index 0000000..16cff1f --- /dev/null +++ b/man2/set_thread_area.2 @@ -0,0 +1,177 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" Copyright (C) 2015 Andrew Lutomirski +.\" Author: Kent Yoder +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file is distributed according to the GNU General Public License. +.\" %%%LICENSE_END +.\" +.TH SET_THREAD_AREA 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +get_thread_area, set_thread_area \- set a GDT entry for thread-local storage +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int get_thread_area(struct user_desc *" u_info ); +.BI "int set_thread_area(struct user_desc *" u_info ); +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +Linux dedicates three global descriptor table (GDT) entries for +thread-local storage. +For more information about the GDT, see the +Intel Software Developer's Manual or the AMD Architecture Programming Manual. +.PP +Both of these system calls take an argument that is a pointer +to a structure of the following type: +.PP +.in +4n +.EX +struct user_desc { + unsigned int entry_number; + unsigned long base_addr; + unsigned int limit; + unsigned int seg_32bit:1; + unsigned int contents:2; + unsigned int read_exec_only:1; + unsigned int limit_in_pages:1; + unsigned int seg_not_present:1; + unsigned int useable:1; +}; +.EE +.in +.PP +.BR get_thread_area () +reads the GDT entry indicated by +.I u_info\->entry_number +and fills in the rest of the fields in +.IR u_info . +.PP +.BR set_thread_area () +sets a TLS entry in the GDT. +.PP +The TLS array entry set by +.BR set_thread_area () +corresponds to the value of +.I u_info\->entry_number +passed in by the user. +If this value is in bounds, +.BR set_thread_area () +writes the TLS descriptor pointed to by +.I u_info +into the thread's TLS array. +.PP +When +.BR set_thread_area () +is passed an +.I entry_number +of \-1, it searches for a free TLS entry. +If +.BR set_thread_area () +finds a free TLS entry, the value of +.I u_info\->entry_number +is set upon return to show which entry was changed. +.PP +A +.I user_desc +is considered "empty" if +.I read_exec_only +and +.I seg_not_present +are set to 1 and all of the other fields are 0. +If an "empty" descriptor is passed to +.BR set_thread_area, +the corresponding TLS entry will be cleared. +See BUGS for additional details. +.PP +Since Linux 3.19, +.BR set_thread_area () +cannot be used to write non-present segments, 16-bit segments, or code +segments, although clearing a segment is still acceptable. +.SH RETURN VALUE +These system calls +return 0 on success, and \-1 on failure, with +.I errno +set appropriately. +.SH ERRORS +.TP +.B EFAULT +\fIu_info\fP is an invalid pointer. +.TP +.B EINVAL +\fIu_info\->entry_number\fP is out of bounds. +.TP +.B ENOSYS +.BR get_thread_area () +or +.BR set_thread_area () +was invoked as a 64-bit system call. +.TP +.B ESRCH +.RB ( set_thread_area ()) +A free TLS entry could not be located. +.SH VERSIONS +.BR set_thread_area () +first appeared in Linux 2.5.29. +.BR get_thread_area () +first appeared in Linux 2.5.32. +.SH CONFORMING TO +.BR set_thread_area () +is Linux-specific and should not be used in programs that are intended +to be portable. +.SH NOTES +Glibc does not provide wrappers for these system calls, +since they are generally intended for use only by threading libraries. +In the unlikely event that you want to call them directly, use +.BR syscall (2). +.PP +.BR arch_prctl (2) +can interfere with +.BR set_thread_area (). +See +.BR arch_prctl (2) +for more details. +This is not normally a problem, as +.BR arch_prctl (2) +is normally used only by 64-bit programs. +.SH BUGS +On 64-bit kernels before Linux 3.19, +.\" commit e30ab185c490e9a9381385529e0fd32f0a399495 +one of the padding bits in +.IR user_desc , +if set, would prevent the descriptor from being considered empty (see +.BR modify_ldt (2)). +As a result, the only reliable way to clear a TLS entry is to use +.BR memset (3) +to zero the entire +.I user_desc +structure, including padding bits, and then to set the +.I read_exec_only +and +.I seg_not_present +bits. +On Linux 3.19, a +.I user_desc +consisting entirely of zeros except for +.I entry_number +will also be interpreted as a request to clear a TLS entry, but this +behaved differently on older kernels. +.PP +Prior to Linux 3.19, the DS and ES segment registers must not reference +TLS entries. +.SH SEE ALSO +.BR arch_prctl (2), +.BR modify_ldt (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/set_tid_address.2 b/man2/set_tid_address.2 new file mode 100644 index 0000000..153026d --- /dev/null +++ b/man2/set_tid_address.2 @@ -0,0 +1,117 @@ +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SET_TID_ADDRESS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +set_tid_address \- set pointer to thread ID +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long set_tid_address(int *" tidptr ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +For each thread, the kernel maintains two attributes (addresses) called +.I set_child_tid +and +.IR clear_child_tid . +These two attributes contain the value NULL by default. +.TP +.I set_child_tid +If a thread is started using +.BR clone (2) +with the +.B CLONE_CHILD_SETTID +flag, +.I set_child_tid +is set to the value passed in the +.I ctid +argument of that system call. +.IP +When +.I set_child_tid +is set, the very first thing the new thread does +is to write its thread ID at this address. +.TP +.I clear_child_tid +If a thread is started using +.BR clone (2) +with the +.B CLONE_CHILD_CLEARTID +flag, +.I clear_child_tid +is set to the value passed in the +.I ctid +argument of that system call. +.PP +The system call +.BR set_tid_address () +sets the +.I clear_child_tid +value for the calling thread to +.IR tidptr . +.PP +When a thread whose +.I clear_child_tid +is not NULL terminates, then, +if the thread is sharing memory with other threads, +then 0 is written at the address specified in +.I clear_child_tid +and the kernel performs the following operation: +.PP + futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0); +.PP +The effect of this operation is to wake a single thread that +is performing a futex wait on the memory location. +Errors from the futex wake operation are ignored. +.SH RETURN VALUE +.BR set_tid_address () +always returns the caller's thread ID. +.SH ERRORS +.BR set_tid_address () +always succeeds. +.SH VERSIONS +This call is present since Linux 2.5.48. +Details as given here are valid since Linux 2.5.49. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.SH SEE ALSO +.BR clone (2), +.BR futex (2), +.BR gettid (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setcontext.2 b/man2/setcontext.2 new file mode 100644 index 0000000..b01818d --- /dev/null +++ b/man2/setcontext.2 @@ -0,0 +1 @@ +.so man3/getcontext.3 diff --git a/man2/setdomainname.2 b/man2/setdomainname.2 new file mode 100644 index 0000000..1c1594c --- /dev/null +++ b/man2/setdomainname.2 @@ -0,0 +1 @@ +.so man2/getdomainname.2 diff --git a/man2/setegid.2 b/man2/setegid.2 new file mode 100644 index 0000000..85032b5 --- /dev/null +++ b/man2/setegid.2 @@ -0,0 +1 @@ +.so man2/seteuid.2 diff --git a/man2/seteuid.2 b/man2/seteuid.2 new file mode 100644 index 0000000..585fda7 --- /dev/null +++ b/man2/seteuid.2 @@ -0,0 +1,161 @@ +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" [should really be seteuid.3] +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SETEUID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +seteuid, setegid \- set effective user or group ID +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int seteuid(uid_t " euid ); +.br +.BI "int setegid(gid_t " egid ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR seteuid (), +.BR setegid (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.ad +.SH DESCRIPTION +.BR seteuid () +sets the effective user ID of the calling process. +Unprivileged processes may only set the effective user ID to the +real user ID, the effective user ID or the saved set-user-ID. +.PP +Precisely the same holds for +.BR setegid () +with "group" instead of "user". +.\" When +.\" .I euid +.\" equals \-1, nothing is changed. +.\" (This is an artifact of the implementation in glibc of seteuid() +.\" using setresuid(2).) +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +.IR Note : +there are cases where +.BR seteuid () +can fail even when the caller is UID 0; +it is a grave security error to omit checking for a failure return from +.BR seteuid (). +.SH ERRORS +.TP +.B EINVAL +The target user or group ID is not valid in this user namespace. +.TP +.B EPERM +In the case of +.BR seteuid (): +the calling process is not privileged (does not have the +.BR CAP_SETUID +capability in its user namespace) and +.I euid +does not match the current real user ID, current effective user ID, +or current saved set-user-ID. +.IP +In the case of +.BR setegid (): +the calling process is not privileged (does not have the +.BR CAP_SETGID +capability in its user namespace) and +.I egid +does not match the current real group ID, current effective group ID, +or current saved set-group-ID. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH NOTES +Setting the effective user (group) ID to the +saved set-user-ID (saved set-group-ID) is +possible since Linux 1.1.37 (1.1.38). +On an arbitrary system one should check +.BR _POSIX_SAVED_IDS . +.PP +Under glibc 2.0 +.BI seteuid( euid ) +is equivalent to +.BI setreuid(\-1, " euid" ) +and hence may change the saved set-user-ID. +Under glibc 2.1 and later it is equivalent to +.BI setresuid(\-1, " euid" ", \-1)" +and hence does not change the saved set-user-ID. +Analogous remarks hold for +.BR setegid (), +with the difference that the change in implementation from +.BI setregid(\-1, " egid" ) +to +.BI setresgid(\-1, " egid" ", \-1)" +occurred in glibc 2.2 or 2.3 (depending on the hardware architecture). +.PP +According to POSIX.1, +.BR seteuid () +.RB ( setegid ()) +need not permit +.I euid +.RI ( egid ) +to be the same value as the current effective user (group) ID, +and some implementations do not permit this. +.SS C library/kernel differences +On Linux, +.BR seteuid () +and +.BR setegid () +are implemented as library functions that call, respectively, +.BR setreuid (2) +and +.BR setregid (2). +.SH SEE ALSO +.BR geteuid (2), +.BR setresuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setfsgid.2 b/man2/setfsgid.2 new file mode 100644 index 0000000..7d679ec --- /dev/null +++ b/man2/setfsgid.2 @@ -0,0 +1,139 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created 1995-08-06 Thomas K. Dyas +.\" Modified 2000-07-01 aeb +.\" Modified 2002-07-23 aeb +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SETFSGID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setfsgid \- set group identity used for filesystem checks +.SH SYNOPSIS +.B #include +.PP +.BI "int setfsgid(uid_t " fsgid ); +.SH DESCRIPTION +The system call +.BR setfsgid () +changes the value of the caller's filesystem group ID\(emthe +group ID that the Linux kernel uses to check for all accesses +to the filesystem. +Normally, the value of +the filesystem group ID +will shadow the value of the effective group ID. +In fact, whenever the +effective group ID is changed, +the filesystem group ID +will also be changed to the new value of the effective group ID. +.PP +Explicit calls to +.BR setfsuid (2) +and +.BR setfsgid () +are usually used only by programs such as the Linux NFS server that +need to change what user and group ID is used for file access without a +corresponding change in the real and effective user and group IDs. +A change in the normal user IDs for a program such as the NFS server +is a security hole that can expose it to unwanted signals. +(But see below.) +.PP +.BR setfsgid () +will succeed only if the caller is the superuser or if +.I fsgid +matches either the caller's real group ID, effective group ID, +saved set-group-ID, or current the filesystem user ID. +.SH RETURN VALUE +On both success and failure, +this call returns the previous filesystem group ID of the caller. +.SH VERSIONS +This system call is present in Linux since version 1.2. +.\" This system call is present since Linux 1.1.44 +.\" and in libc since libc 4.7.6. +.SH CONFORMING TO +.BR setfsgid () +is Linux-specific and should not be used in programs intended +to be portable. +.SH NOTES +Note that at the time this system call was introduced, a process +could send a signal to a process with the same effective user ID. +Today signal permission handling is slightly different. +See +.BR setfsuid (2) +for a discussion of why the use of both +.BR setfsuid (2) +and +.BR setfsgid () +is nowadays unneeded. +.PP +The original Linux +.BR setfsgid () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR setfsgid32 () +supporting 32-bit IDs. +The glibc +.BR setfsgid () +wrapper function transparently deals with the variation across kernel versions. +.SS C library/kernel differences +In glibc 2.15 and earlier, +when the wrapper for this system call determines that the argument can't be +passed to the kernel without integer truncation (because the kernel +is old and does not support 32-bit group IDs), +they will return \-1 and set \fIerrno\fP to +.B EINVAL +without attempting +the system call. +.SH BUGS +No error indications of any kind are returned to the caller, +and the fact that both successful and unsuccessful calls return +the same value makes it impossible to directly determine +whether the call succeeded or failed. +Instead, the caller must resort to looking at the return value +from a further call such as +.IR setfsgid(\-1) +(which will always fail), in order to determine if a preceding call to +.BR setfsgid () +changed the filesystem group ID. +At the very +least, +.B EPERM +should be returned when the call fails (because the caller lacks the +.B CAP_SETGID +capability). +.SH SEE ALSO +.BR kill (2), +.BR setfsuid (2), +.BR capabilities (7), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setfsgid32.2 b/man2/setfsgid32.2 new file mode 100644 index 0000000..fdb8bdc --- /dev/null +++ b/man2/setfsgid32.2 @@ -0,0 +1 @@ +.so man2/setfsgid.2 diff --git a/man2/setfsuid.2 b/man2/setfsuid.2 new file mode 100644 index 0000000..e0ae551 --- /dev/null +++ b/man2/setfsuid.2 @@ -0,0 +1,147 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created 1995-08-06 Thomas K. Dyas +.\" Modified 2000-07-01 aeb +.\" Modified 2002-07-23 aeb +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH SETFSUID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setfsuid \- set user identity used for filesystem checks +.SH SYNOPSIS +.B #include +.PP +.BI "int setfsuid(uid_t " fsuid ); +.SH DESCRIPTION +The system call +.BR setfsuid () +changes the value of the caller's filesystem user ID\(emthe +user ID that the Linux kernel uses to check for all accesses +to the filesystem. +Normally, the value of +the filesystem user ID +will shadow the value of the effective user ID. +In fact, whenever the +effective user ID is changed, +the filesystem user ID +will also be changed to the new value of the effective user ID. +.PP +Explicit calls to +.BR setfsuid () +and +.BR setfsgid (2) +are usually used only by programs such as the Linux NFS server that +need to change what user and group ID is used for file access without a +corresponding change in the real and effective user and group IDs. +A change in the normal user IDs for a program such as the NFS server +is a security hole that can expose it to unwanted signals. +(But see below.) +.PP +.BR setfsuid () +will succeed only if the caller is the superuser or if +.I fsuid +matches either the caller's real user ID, effective user ID, +saved set-user-ID, or current filesystem user ID. +.SH RETURN VALUE +On both success and failure, +this call returns the previous filesystem user ID of the caller. +.SH VERSIONS +This system call is present in Linux since version 1.2. +.\" This system call is present since Linux 1.1.44 +.\" and in libc since libc 4.7.6. +.SH CONFORMING TO +.BR setfsuid () +is Linux-specific and should not be used in programs intended +to be portable. +.SH NOTES +At the time when this system call was introduced, one process +could send a signal to another process with the same effective user ID. +This meant that if a privileged process changed its effective user ID +for the purpose of file permission checking, +then it could become vulnerable to receiving signals +sent by another (unprivileged) process with the same user ID. +The filesystem user ID attribute was thus added to allow a process to +change its user ID for the purposes of file permission checking without +at the same time becoming vulnerable to receiving unwanted signals. +Since Linux 2.0, signal permission handling is different (see +.BR kill (2)), +with the result that a process change can change its effective user ID +without being vulnerable to receiving signals from unwanted processes. +Thus, +.BR setfsuid () +is nowadays unneeded and should be avoided in new applications +(likewise for +.BR setfsgid (2)). +.PP +The original Linux +.BR setfsuid () +system call supported only 16-bit user IDs. +Subsequently, Linux 2.4 added +.BR setfsuid32 () +supporting 32-bit IDs. +The glibc +.BR setfsuid () +wrapper function transparently deals with the variation across kernel versions. +.SS C library/kernel differences +In glibc 2.15 and earlier, +when the wrapper for this system call determines that the argument can't be +passed to the kernel without integer truncation (because the kernel +is old and does not support 32-bit user IDs), +they will return \-1 and set \fIerrno\fP to +.B EINVAL +without attempting +the system call. +.SH BUGS +No error indications of any kind are returned to the caller, +and the fact that both successful and unsuccessful calls return +the same value makes it impossible to directly determine +whether the call succeeded or failed. +Instead, the caller must resort to looking at the return value +from a further call such as +.IR setfsuid(\-1) +(which will always fail), in order to determine if a preceding call to +.BR setfsuid () +changed the filesystem user ID. +At the very +least, +.B EPERM +should be returned when the call fails (because the caller lacks the +.B CAP_SETUID +capability). +.SH SEE ALSO +.BR kill (2), +.BR setfsgid (2), +.BR capabilities (7), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setfsuid32.2 b/man2/setfsuid32.2 new file mode 100644 index 0000000..1ea58fd --- /dev/null +++ b/man2/setfsuid32.2 @@ -0,0 +1 @@ +.so man2/setfsuid.2 diff --git a/man2/setgid.2 b/man2/setgid.2 new file mode 100644 index 0000000..84ff367 --- /dev/null +++ b/man2/setgid.2 @@ -0,0 +1,116 @@ +.\" Copyright (C), 1994, Graeme W. Wilford. (Wilf.) +.\" and Copyright (C) 2010, 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2002-03-09 by aeb +.\" +.TH SETGID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setgid \- set group identity +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int setgid(gid_t " gid ); +.SH DESCRIPTION +.BR setgid () +sets the effective group ID of the calling process. +If the calling process is privileged (has the +.B CAP_SETGID +capability in its user namespace), +the real GID and saved set-group-ID are also set. +.PP +Under Linux, +.BR setgid () +is implemented like the POSIX version with the +.B _POSIX_SAVED_IDS +feature. +This allows a set-group-ID program that is not set-user-ID-root +to drop all of its group +privileges, do some un-privileged work, and then reengage the original +effective group ID in a secure manner. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The group ID specified in +.I gid +is not valid in this user namespace. +.TP +.B EPERM +The calling process is not privileged (does not have the +\fBCAP_SETGID\fP capability), and +.I gid +does not match the real group ID or saved set-group-ID of +the calling process. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.SH NOTES +The original Linux +.BR setgid () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR setgid32 () +supporting 32-bit IDs. +The glibc +.BR setgid () +wrapper function transparently deals with the variation across kernel versions. +.\" +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including the one for +.BR setgid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH SEE ALSO +.BR getgid (2), +.BR setegid (2), +.BR setregid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setgid32.2 b/man2/setgid32.2 new file mode 100644 index 0000000..bc8ef19 --- /dev/null +++ b/man2/setgid32.2 @@ -0,0 +1 @@ +.so man2/setgid.2 diff --git a/man2/setgroups.2 b/man2/setgroups.2 new file mode 100644 index 0000000..0ae4cc0 --- /dev/null +++ b/man2/setgroups.2 @@ -0,0 +1 @@ +.so man2/getgroups.2 diff --git a/man2/setgroups32.2 b/man2/setgroups32.2 new file mode 100644 index 0000000..478fb63 --- /dev/null +++ b/man2/setgroups32.2 @@ -0,0 +1 @@ +.so man2/setgroups.2 diff --git a/man2/sethostid.2 b/man2/sethostid.2 new file mode 100644 index 0000000..3210db0 --- /dev/null +++ b/man2/sethostid.2 @@ -0,0 +1 @@ +.so man3/gethostid.3 diff --git a/man2/sethostname.2 b/man2/sethostname.2 new file mode 100644 index 0000000..e1fa2a6 --- /dev/null +++ b/man2/sethostname.2 @@ -0,0 +1 @@ +.so man2/gethostname.2 diff --git a/man2/setitimer.2 b/man2/setitimer.2 new file mode 100644 index 0000000..9518567 --- /dev/null +++ b/man2/setitimer.2 @@ -0,0 +1 @@ +.so man2/getitimer.2 diff --git a/man2/setns.2 b/man2/setns.2 new file mode 100644 index 0000000..87d755a --- /dev/null +++ b/man2/setns.2 @@ -0,0 +1,314 @@ +.\" Copyright (C) 2011, Eric Biederman +.\" and Copyright (C) 2011, 2012, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2_ONELINE) +.\" Licensed under the GPLv2 +.\" %%%LICENSE_END +.\" +.TH SETNS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setns \- reassociate thread with a namespace +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int setns(int " fd ", int " nstype ); +.fi +.SH DESCRIPTION +Given a file descriptor referring to a namespace, +reassociate the calling thread with that namespace. +.PP +The +.I fd +argument is a file descriptor referring to one of the namespace entries in a +.I /proc/[pid]/ns/ +directory; see +.BR namespaces (7) +for further information on +.IR /proc/[pid]/ns/ . +The calling thread will be reassociated with the corresponding namespace, +subject to any constraints imposed by the +.I nstype +argument. +.PP +The +.I nstype +argument specifies which type of namespace +the calling thread may be reassociated with. +This argument can have one of the following values: +.TP +.BR 0 +Allow any type of namespace to be joined. +.TP +.BR CLONE_NEWCGROUP " (since Linux 4.6)" +.I fd +must refer to a cgroup namespace. +.TP +.BR CLONE_NEWIPC " (since Linux 3.0)" +.I fd +must refer to an IPC namespace. +.TP +.BR CLONE_NEWNET " (since Linux 3.0)" +.I fd +must refer to a network namespace. +.TP +.BR CLONE_NEWNS " (since Linux 3.8)" +.I fd +must refer to a mount namespace. +.TP +.BR CLONE_NEWPID " (since Linux 3.8)" +.I fd +must refer to a descendant PID namespace. +.TP +.BR CLONE_NEWUSER " (since Linux 3.8)" +.I fd +must refer to a user namespace. +.TP +.BR CLONE_NEWUTS " (since Linux 3.0)" +.I fd +must refer to a UTS namespace. +.PP +Specifying +.I nstype +as 0 suffices if the caller knows (or does not care) +what type of namespace is referred to by +.IR fd . +Specifying a nonzero value for +.I nstype +is useful if the caller does not know what type of namespace is referred to by +.IR fd +and wants to ensure that the namespace is of a particular type. +(The caller might not know the type of the namespace referred to by +.IR fd +if the file descriptor was opened by another process and, for example, +passed to the caller via a UNIX domain socket.) +.PP +If +.I fd +refers to a PID namespaces, the semantics are somewhat different +from other namespace types: +reassociating the calling thread with a PID namespace changes only +the PID namespace that subsequently created child processes of +the caller will be placed in; +it does not change the PID namespace of the caller itself. +Reassociating with a PID namespace is allowed only if the +PID namespace specified by +.IR fd +is a descendant (child, grandchild, etc.) +of the PID namespace of the caller. +For further details on PID namespaces, see +.BR pid_namespaces (7). +.PP +A process reassociating itself with a user namespace must have the +.B CAP_SYS_ADMIN +.\" See kernel/user_namespace.c:userns_install() [3.8 source] +capability in the target user namespace. +Upon successfully joining a user namespace, +a process is granted all capabilities in that namespace, +regardless of its user and group IDs. +A multithreaded process may not change user namespace with +.BR setns (). +It is not permitted to use +.BR setns () +to reenter the caller's current user namespace. +This prevents a caller that has dropped capabilities from regaining +those capabilities via a call to +.BR setns (). +For security reasons, +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +.\" https://lwn.net/Articles/543273/ +a process can't join a new user namespace if it is sharing +filesystem-related attributes +(the attributes whose sharing is controlled by the +.BR clone (2) +.B CLONE_FS +flag) with another process. +For further details on user namespaces, see +.BR user_namespaces (7). +.PP +A process may not be reassociated with a new mount namespace if it is +multithreaded. +.\" Above check is in fs/namespace.c:mntns_install() [3.8 source] +Changing the mount namespace requires that the caller possess both +.B CAP_SYS_CHROOT +and +.BR CAP_SYS_ADMIN +capabilities in its own user namespace and +.BR CAP_SYS_ADMIN +in the target mount namespace. +See +.BR user_namespaces (7) +for details on the interaction of user namespaces and mount namespaces. +.PP +Using +.BR setns () +to change the caller's cgroup namespace does not change +the caller's cgroup memberships. +.SH RETURN VALUE +On success, +.BR setns () +returns 0. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I fd +refers to a namespace whose type does not match that specified in +.IR nstype . +.TP +.B EINVAL +There is problem with reassociating +the thread with the specified namespace. +.TP +.\" See kernel/pid_namespace.c::pidns_install() [kernel 3.18 sources] +.B EINVAL +The caller tried to join an ancestor (parent, grandparent, and so on) +PID namespace. +.TP +.B EINVAL +The caller attempted to join the user namespace +in which it is already a member. +.TP +.B EINVAL +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +The caller shares filesystem +.RB ( CLONE_FS ) +state (in particular, the root directory) +with other processes and tried to join a new user namespace. +.TP +.B EINVAL +.\" See kernel/user_namespace.c::userns_install() [kernel 3.15 sources] +The caller is multithreaded and tried to join a new user namespace. +.TP +.B ENOMEM +Cannot allocate sufficient memory to change the specified namespace. +.TP +.B EPERM +The calling thread did not have the required capability +for this operation. +.SH VERSIONS +The +.BR setns () +system call first appeared in Linux in kernel 3.0; +library support was added to glibc in version 2.14. +.SH CONFORMING TO +The +.BR setns () +system call is Linux-specific. +.SH NOTES +Not all of the attributes that can be shared when +a new thread is created using +.BR clone (2) +can be changed using +.BR setns (). +.SH EXAMPLE +The program below takes two or more arguments. +The first argument specifies the pathname of a namespace file in an existing +.I /proc/[pid]/ns/ +directory. +The remaining arguments specify a command and its arguments. +The program opens the namespace file, joins that namespace using +.BR setns (), +and executes the specified command inside that namespace. +.PP +The following shell session demonstrates the use of this program +(compiled as a binary named +.IR ns_exec ) +in conjunction with the +.BR CLONE_NEWUTS +example program in the +.BR clone (2) +man page (complied as a binary named +.IR newuts ). +.PP +We begin by executing the example program in +.BR clone (2) +in the background. +That program creates a child in a separate UTS namespace. +The child changes the hostname in its namespace, +and then both processes display the hostnames in their UTS namespaces, +so that we can see that they are different. +.PP +.in +4n +.EX +$ \fBsu\fP # Need privilege for namespace operations +Password: +# \fB./newuts bizarro &\fP +[1] 3549 +clone() returned 3550 +uts.nodename in child: bizarro +uts.nodename in parent: antero +# \fBuname \-n\fP # Verify hostname in the shell +antero +.EE +.in +.PP +We then run the program shown below, +using it to execute a shell. +Inside that shell, we verify that the hostname is the one +set by the child created by the first program: +.PP +.in +4n +.EX +# \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP +# \fBuname \-n\fP # Executed in shell started by ns_exec +bizarro +.EE +.in +.SS Program source +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + int fd; + + if (argc < 3) { + fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\\n", argv[0]); + exit(EXIT_FAILURE); + } + + fd = open(argv[1], O_RDONLY); /* Get file descriptor for namespace */ + if (fd == \-1) + errExit("open"); + + if (setns(fd, 0) == \-1) /* Join that namespace */ + errExit("setns"); + + execvp(argv[2], &argv[2]); /* Execute a command in namespace */ + errExit("execvp"); +} +.EE +.SH SEE ALSO +.BR nsenter (1), +.BR clone (2), +.BR fork (2), +.BR unshare (2), +.BR vfork (2), +.BR namespaces (7), +.BR unix (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setpgid.2 b/man2/setpgid.2 new file mode 100644 index 0000000..6f6b337 --- /dev/null +++ b/man2/setpgid.2 @@ -0,0 +1,348 @@ +.\" Copyright (c) 1983, 1991 Regents of the University of California. +.\" and Copyright (C) 2007, Michael Kerrisk +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)getpgrp.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-04-15 by Michael Chastain : +.\" Added 'getpgid'. +.\" Modified 1996-07-21 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1999-09-02 by Michael Haardt +.\" Modified 2002-01-18 by Michael Kerrisk +.\" Modified 2003-01-20 by Andries Brouwer +.\" 2007-07-25, mtk, fairly substantial rewrites and rearrangements +.\" of text. +.\" +.TH SETPGID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setpgid, getpgid, setpgrp, getpgrp \- set/get process group +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int setpgid(pid_t " pid ", pid_t " pgid ); +.br +.BI "pid_t getpgid(pid_t " pid ); +.PP +.BR "pid_t getpgrp(void);" " /* POSIX.1 version */" +.br +.BI "pid_t getpgrp(pid_t " pid ");\ \ \ \ \ \ \ \ \ \ \ " +/* BSD version */ +.PP +.BR "int setpgrp(void);" " /* System V version */" +.br +.BI "int setpgrp(pid_t " pid ", pid_t " pgid ");\ " +/* BSD version */ +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR getpgid (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.br + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L +.RE +.PP +.BR setpgrp "() (POSIX.1):" +.nf + _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.fi +.PP +.BR setpgrp "()\ (BSD)," +.BR getpgrp "()\ (BSD):" +.nf + [These are available only before glibc 2.19] + _BSD_SOURCE && + !\ (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE || + _GNU_SOURCE || _SVID_SOURCE) +.fi +.ad +.SH DESCRIPTION +All of these interfaces are available on Linux, +and are used for getting and setting the +process group ID (PGID) of a process. +The preferred, POSIX.1-specified ways of doing this are: +.BR getpgrp (void), +for retrieving the calling process's PGID; and +.BR setpgid (), +for setting a process's PGID. +.PP +.BR setpgid () +sets the PGID of the process specified by +.I pid +to +.IR pgid . +If +.I pid +is zero, then the process ID of the calling process is used. +If +.I pgid +is zero, then the PGID of the process specified by +.I pid +is made the same as its process ID. +If +.BR setpgid () +is used to move a process from one process +group to another (as is done by some shells when creating pipelines), +both process groups must be part of the same session (see +.BR setsid (2) +and +.BR credentials (7)). +In this case, +the \fIpgid\fP specifies an existing process group to be joined and the +session ID of that group must match the session ID of the joining process. +.PP +The POSIX.1 version of +.BR getpgrp (), +which takes no arguments, +returns the PGID of the calling process. +.PP +.BR getpgid () +returns the PGID of the process specified by +.IR pid . +If +.I pid +is zero, the process ID of the calling process is used. +(Retrieving the PGID of a process other than the caller is rarely +necessary, and the POSIX.1 +.BR getpgrp () +is preferred for that task.) +.PP +The System\ V-style +.BR setpgrp (), +which takes no arguments, is equivalent to +.IR "setpgid(0,\ 0)" . +.PP +The BSD-specific +.BR setpgrp () +call, which takes arguments +.I pid +and +.IR pgid , +is a wrapper function that calls +.PP + setpgid(pid, pgid) +.PP +.\" The true BSD setpgrp() system call differs in allowing the PGID +.\" to be set to arbitrary values, rather than being restricted to +.\" PGIDs in the same session. +Since glibc 2.19, the BSD-specific +.BR setpgrp () +function is no longer exposed by +.IR ; +calls should be replaced with the +.BR setpgid () +call shown above. +.PP +The BSD-specific +.BR getpgrp () +call, which takes a single +.I pid +argument, is a wrapper function that calls +.PP + getpgid(pid) +.PP +Since glibc 2.19, the BSD-specific +.BR getpgrp () +function is no longer exposed by +.IR ; +calls should be replaced with calls to the POSIX.1 +.BR getpgrp () +which takes no arguments (if the intent is to obtain the caller's PGID), +or with the +.BR getpgid () +call shown above. +.SH RETURN VALUE +On success, +.BR setpgid () +and +.BR setpgrp () +return zero. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +The POSIX.1 +.BR getpgrp () +always returns the PGID of the caller. +.PP +.BR getpgid (), +and the BSD-specific +.BR getpgrp () +return a process group on success. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +An attempt was made to change the process group ID +of one of the children of the calling process and the child had +already performed an +.BR execve (2) +.RB ( setpgid (), +.BR setpgrp ()). +.TP +.B EINVAL +.I pgid +is less than 0 +.RB ( setpgid (), +.BR setpgrp ()). +.TP +.B EPERM +An attempt was made to move a process into a process group in a +different session, or to change the process +group ID of one of the children of the calling process and the +child was in a different session, or to change the process group ID of +a session leader +.RB ( setpgid (), +.BR setpgrp ()). +.TP +.B ESRCH +For +.BR getpgid (): +.I pid +does not match any process. +For +.BR setpgid (): +.I pid +is not the calling process and not a child of the calling process. +.SH CONFORMING TO +.BR setpgid () +and the version of +.BR getpgrp () +with no arguments +conform to POSIX.1-2001. +.PP +POSIX.1-2001 also specifies +.BR getpgid () +and the version of +.BR setpgrp () +that takes no arguments. +(POSIX.1-2008 marks this +.BR setpgrp () +specification as obsolete.) +.PP +The version of +.BR getpgrp () +with one argument and the version of +.BR setpgrp () +that takes two arguments derive from 4.2BSD, +and are not specified by POSIX.1. +.SH NOTES +A child created via +.BR fork (2) +inherits its parent's process group ID. +The PGID is preserved across an +.BR execve (2). +.PP +Each process group is a member of a session and each process is a +member of the session of which its process group is a member. +(See +.BR credentials (7).) +.PP +A session can have a controlling terminal. +At any time, one (and only one) of the process groups +in the session can be the foreground process group +for the terminal; +the remaining process groups are in the background. +If a signal is generated from the terminal (e.g., typing the +interrupt key to generate +.BR SIGINT ), +that signal is sent to the foreground process group. +(See +.BR termios (3) +for a description of the characters that generate signals.) +Only the foreground process group may +.BR read (2) +from the terminal; +if a background process group tries to +.BR read (2) +from the terminal, then the group is sent a +.B SIGTTIN +signal, which suspends it. +The +.BR tcgetpgrp (3) +and +.BR tcsetpgrp (3) +functions are used to get/set the foreground +process group of the controlling terminal. +.PP +The +.BR setpgid () +and +.BR getpgrp () +calls are used by programs such as +.BR bash (1) +to create process groups in order to implement shell job control. +.PP +If the termination of a process causes a process group to become orphaned, +and if any member of the newly orphaned process group is stopped, then a +.B SIGHUP +signal followed by a +.B SIGCONT +signal will be sent to each process +in the newly orphaned process group. +.\" exit.3 refers to the following text: +An orphaned process group is one in which the parent of +every member of process group is either itself also a member +of the process group or is a member of a process group +in a different session (see also +.BR credentials (7)). +.SH SEE ALSO +.BR getuid (2), +.BR setsid (2), +.BR tcgetpgrp (3), +.BR tcsetpgrp (3), +.BR termios (3), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setpgrp.2 b/man2/setpgrp.2 new file mode 100644 index 0000000..d6b107a --- /dev/null +++ b/man2/setpgrp.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man2/setpriority.2 b/man2/setpriority.2 new file mode 100644 index 0000000..b1dcfd9 --- /dev/null +++ b/man2/setpriority.2 @@ -0,0 +1 @@ +.so man2/getpriority.2 diff --git a/man2/setregid.2 b/man2/setregid.2 new file mode 100644 index 0000000..ec3ff64 --- /dev/null +++ b/man2/setregid.2 @@ -0,0 +1 @@ +.so man2/setreuid.2 diff --git a/man2/setregid32.2 b/man2/setregid32.2 new file mode 100644 index 0000000..035df17 --- /dev/null +++ b/man2/setregid32.2 @@ -0,0 +1 @@ +.so man2/setregid.2 diff --git a/man2/setresgid.2 b/man2/setresgid.2 new file mode 100644 index 0000000..d6866a1 --- /dev/null +++ b/man2/setresgid.2 @@ -0,0 +1 @@ +.so man2/setresuid.2 diff --git a/man2/setresgid32.2 b/man2/setresgid32.2 new file mode 100644 index 0000000..dec1b95 --- /dev/null +++ b/man2/setresgid32.2 @@ -0,0 +1 @@ +.so man2/setresgid.2 diff --git a/man2/setresuid.2 b/man2/setresuid.2 new file mode 100644 index 0000000..ca8fb65 --- /dev/null +++ b/man2/setresuid.2 @@ -0,0 +1,176 @@ +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2005, 2010, 2014, 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified, 2003-05-26, Michael Kerrisk, +.TH SETRESUID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setresuid, setresgid \- set real, effective and saved user or group ID +.SH SYNOPSIS +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.PP +.BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid ); +.br +.BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid ); +.SH DESCRIPTION +.BR setresuid () +sets the real user ID, the effective user ID, and the +saved set-user-ID of the calling process. +.PP +An unprivileged process may change its real UID, +effective UID, and saved set-user-ID, each to one of: +the current real UID, the current effective UID or the +current saved set-user-ID. +.PP +A privileged process (on Linux, one having the \fBCAP_SETUID\fP capability) +may set its real UID, effective UID, and +saved set-user-ID to arbitrary values. +.PP +If one of the arguments equals \-1, the corresponding value is not changed. +.PP +Regardless of what changes are made to the real UID, effective UID, +and saved set-user-ID, the filesystem UID is always set to the same +value as the (possibly new) effective UID. +.PP +Completely analogously, +.BR setresgid () +sets the real GID, effective GID, and saved set-group-ID +of the calling process (and always modifies the filesystem GID +to be the same as the effective GID), +with the same restrictions for unprivileged processes. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +.IR Note : +there are cases where +.BR setresuid () +can fail even when the caller is UID 0; +it is a grave security error to omit checking for a failure return from +.BR setresuid (). +.SH ERRORS +.TP +.B EAGAIN +The call would change the caller's real UID (i.e., +.I ruid +does not match the caller's real UID), +but there was a temporary failure allocating the +necessary kernel data structures. +.TP +.B EAGAIN +.I ruid +does not match the caller's real UID and this call would +bring the number of processes belonging to the real user ID +.I ruid +over the caller's +.B RLIMIT_NPROC +resource limit. +Since Linux 3.1, this error case no longer occurs +(but robust applications should check for this error); +see the description of +.B EAGAIN +in +.BR execve (2). +.TP +.B EINVAL +One or more of the target user or group IDs +is not valid in this user namespace. +.TP +.B EPERM +The calling process is not privileged (did not have the necessary +capability in its user namespace) +and tried to change the IDs to values that are not permitted. +For +.BR setresuid (), +the necessary capability is +.BR CAP_SETUID ; +for +.BR setresgid (), +it is +.BR CAP_SETGID . +.SH VERSIONS +These calls are available under Linux since Linux 2.1.44. +.SH CONFORMING TO +These calls are nonstandard; +they also appear on HP-UX and some of the BSDs. +.SH NOTES +Under HP-UX and FreeBSD, the prototype is found in +.IR . +Under Linux, the prototype is provided by glibc since version 2.3.2. +.PP +The original Linux +.BR setresuid () +and +.BR setresgid () +system calls supported only 16-bit user and group IDs. +Subsequently, Linux 2.4 added +.BR setresuid32 () +and +.BR setresgid32 (), +supporting 32-bit IDs. +The glibc +.BR setresuid () +and +.BR setresgid () +wrapper functions transparently deal with the variations across kernel versions. +.\" +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including those for +.BR setresuid () +and +.BR setresgid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH SEE ALSO +.BR getresuid (2), +.BR getuid (2), +.BR setfsgid (2), +.BR setfsuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setresuid32.2 b/man2/setresuid32.2 new file mode 100644 index 0000000..d6866a1 --- /dev/null +++ b/man2/setresuid32.2 @@ -0,0 +1 @@ +.so man2/setresuid.2 diff --git a/man2/setreuid.2 b/man2/setreuid.2 new file mode 100644 index 0000000..e7bed15 --- /dev/null +++ b/man2/setreuid.2 @@ -0,0 +1,232 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" and Copyright (C) 2009, 2010, 2014, 2015, Michael Kerrisk +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)setregid.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 09:08:49 1993 by Rik Faith +.\" Portions extracted from linux/kernel/sys.c: +.\" Copyright (C) 1991, 1992 Linus Torvalds +.\" May be distributed under the GNU General Public License +.\" Changes: 1994-07-29 by Wilf +.\" 1994-08-02 by Wilf due to change in kernel. +.\" 2004-07-04 by aeb +.\" 2004-05-27 by Michael Kerrisk +.\" +.TH SETREUID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setreuid, setregid \- set real and/or effective user or group ID +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int setreuid(uid_t " ruid ", uid_t " euid ); +.br +.BI "int setregid(gid_t " rgid ", gid_t " egid ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR setreuid (), +.BR setregid (): +.RS 4 +.ad l +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.ad +.RE +.SH DESCRIPTION +.BR setreuid () +sets real and effective user IDs of the calling process. +.PP +Supplying a value of \-1 for either the real or effective user ID forces +the system to leave that ID unchanged. +.PP +Unprivileged processes may only set the effective user ID to the real user ID, +the effective user ID, or the saved set-user-ID. +.PP +Unprivileged users may only set the real user ID to +the real user ID or the effective user ID. +.PP +If the real user ID is set (i.e., +.I ruid +is not \-1) or the effective user ID is set to a value +not equal to the previous real user ID, +the saved set-user-ID will be set to the new effective user ID. +.PP +Completely analogously, +.BR setregid () +sets real and effective group ID's of the calling process, +and all of the above holds with "group" instead of "user". +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +.IR Note : +there are cases where +.BR setreuid () +can fail even when the caller is UID 0; +it is a grave security error to omit checking for a failure return from +.BR setreuid (). +.SH ERRORS +.TP +.B EAGAIN +The call would change the caller's real UID (i.e., +.I ruid +does not match the caller's real UID), +but there was a temporary failure allocating the +necessary kernel data structures. +.TP +.B EAGAIN +.I ruid +does not match the caller's real UID and this call would +bring the number of processes belonging to the real user ID +.I ruid +over the caller's +.B RLIMIT_NPROC +resource limit. +Since Linux 3.1, this error case no longer occurs +(but robust applications should check for this error); +see the description of +.B EAGAIN +in +.BR execve (2). +.TP +.B EINVAL +One or more of the target user or group IDs +is not valid in this user namespace. +.TP +.B EPERM +The calling process is not privileged +(on Linux, does not have the necessary capability in its user namespace: +.B CAP_SETUID +in the case of +.BR setreuid (), +or +.B CAP_SETGID +in the case of +.BR setregid ()) +and a change other than (i) +swapping the effective user (group) ID with the real user (group) ID, +or (ii) setting one to the value of the other or (iii) setting the +effective user (group) ID to the value of the +saved set-user-ID (saved set-group-ID) was specified. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD +.RB ( setreuid () +and +.BR setregid () +first appeared in 4.2BSD). +.SH NOTES +Setting the effective user (group) ID to the +saved set-user-ID (saved set-group-ID) is +possible since Linux 1.1.37 (1.1.38). +.PP +POSIX.1 does not specify all of the UID changes that Linux permits +for an unprivileged process. +For +.BR setreuid (), +the effective user ID can be made the same as the +real user ID or the saved set-user-ID, +and it is unspecified whether unprivileged processes may set the +real user ID to the real user ID, the effective user ID, or the +saved set-user-ID. +For +.BR setregid (), +the real group ID can be changed to the value of the saved set-group-ID, +and the effective group ID can be changed to the value of +the real group ID or the saved set-group-ID. +The precise details of what ID changes are permitted vary +across implementations. +.PP +POSIX.1 makes no specification about the effect of these calls +on the saved set-user-ID and saved set-group-ID. +.PP +The original Linux +.BR setreuid () +and +.BR setregid () +system calls supported only 16-bit user and group IDs. +Subsequently, Linux 2.4 added +.BR setreuid32 () +and +.BR setregid32 (), +supporting 32-bit IDs. +The glibc +.BR setreuid () +and +.BR setregid () +wrapper functions transparently deal with the variations across kernel versions. +.\" +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including those for +.BR setreuid () +and +.BR setregid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH SEE ALSO +.BR getgid (2), +.BR getuid (2), +.BR seteuid (2), +.BR setgid (2), +.BR setresuid (2), +.BR setuid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setreuid32.2 b/man2/setreuid32.2 new file mode 100644 index 0000000..ec3ff64 --- /dev/null +++ b/man2/setreuid32.2 @@ -0,0 +1 @@ +.so man2/setreuid.2 diff --git a/man2/setrlimit.2 b/man2/setrlimit.2 new file mode 100644 index 0000000..df6d736 --- /dev/null +++ b/man2/setrlimit.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man2/setsid.2 b/man2/setsid.2 new file mode 100644 index 0000000..145161f --- /dev/null +++ b/man2/setsid.2 @@ -0,0 +1,126 @@ +.\" Copyright Michael Haardt (michael@cantor.informatik.rwth-aachen.de) +.\" Sat Aug 27 20:43:50 MET DST 1994 +.\" and Copyright (C) 2014, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sun Sep 11 19:19:05 1994 +.\" Modified Mon Mar 25 10:19:00 1996 (merged a few +.\" tiny changes from a man page by Charles Livingston). +.\" Modified Sun Jul 21 14:45:46 1996 +.\" +.TH SETSID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setsid \- creates a session and sets the process group ID +.SH SYNOPSIS +.ad l +.B #include +.br +.B #include +.PP +.B pid_t setsid(void); +.br +.ad b +.SH DESCRIPTION +.BR setsid () +creates a new session if the calling process is not a +process group leader. +The calling process is the leader of the new session +(i.e., its session ID is made the same as its process ID). +The calling process also becomes +the process group leader of a new process group in the session +(i.e., its process group ID is made the same as its process ID). +.PP +The calling process will be the only process in +the new process group and in the new session. +.PP +Initially, the new session has no controlling terminal. +For details of how a session acquires a controlling terminal, see +.BR credentials (7). +.SH RETURN VALUE +On success, the (new) session ID of the calling process is returned. +On error, +.I "(pid_t)\ \-1" +is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EPERM +The process group ID of any process equals the PID of the calling process. +Thus, in particular, +.BR setsid () +fails if the calling process is already a process group leader. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.SH NOTES +A child created via +.BR fork (2) +inherits its parent's session ID. +The session ID is preserved across an +.BR execve (2). +.PP +A process group leader is a process whose process group ID equals its PID. +Disallowing a process group leader from calling +.BR setsid () +prevents the possibility that a process group leader places itself +in a new session while other processes in the process group remain +in the original session; +such a scenario would break the strict +two-level hierarchy of sessions and process groups. +In order to be sure that +.BR setsid () +will succeed, call +.BR fork (2) +and have the parent +.BR _exit (2), +while the child (which by definition can't be a process group leader) calls +.BR setsid (). +.PP +If a session has a controlling terminal, and the +.B CLOCAL +flag for that terminal is not set, +and a terminal hangup occurs, then the session leader is sent a +.BR SIGHUP +signal. +.PP +If a process that is a session leader terminates, then a +.B SIGHUP +signal is sent to each process in the foreground +process group of the controlling terminal. +.SH SEE ALSO +.BR setsid (1), +.BR getsid (2), +.BR setpgid (2), +.BR setpgrp (2), +.BR tcgetsid (3), +.BR credentials (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setsockopt.2 b/man2/setsockopt.2 new file mode 100644 index 0000000..d98c776 --- /dev/null +++ b/man2/setsockopt.2 @@ -0,0 +1 @@ +.so man2/getsockopt.2 diff --git a/man2/settimeofday.2 b/man2/settimeofday.2 new file mode 100644 index 0000000..2b6eff4 --- /dev/null +++ b/man2/settimeofday.2 @@ -0,0 +1 @@ +.so man2/gettimeofday.2 diff --git a/man2/setuid.2 b/man2/setuid.2 new file mode 100644 index 0000000..8419cf5 --- /dev/null +++ b/man2/setuid.2 @@ -0,0 +1,179 @@ +.\" Copyright (C), 1994, Graeme W. Wilford (Wilf). +.\" and Copyright (C) 2010, 2014, 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. +.\" Changes inspired by patch from Richard Kettlewell +.\" , aeb 970616. +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.TH SETUID 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setuid \- set user identity +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int setuid(uid_t " uid ); +.SH DESCRIPTION +.BR setuid () +sets the effective user ID of the calling process. +If the calling process is privileged +(more precisely: if the process has the +.BR CAP_SETUID +capability in its user namespace), +the real UID and saved set-user-ID are also set. +.PP +Under Linux, +.BR setuid () +is implemented like the POSIX version with the +.B _POSIX_SAVED_IDS +feature. +This allows a set-user-ID (other than root) program to drop all of its user +privileges, do some un-privileged work, and then reengage the original +effective user ID in a secure manner. +.PP +If the user is root or the program is set-user-ID-root, special care must be +taken: +.BR setuid () +checks the effective user ID of the caller and if it is +the superuser, all process-related user ID's are set to +.IR uid . +After this has occurred, it is impossible for the program to regain root +privileges. +.PP +Thus, a set-user-ID-root program wishing to temporarily drop root +privileges, assume the identity of an unprivileged user, and then regain +root privileges afterward cannot use +.BR setuid (). +You can accomplish this with +.BR seteuid (2). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +.IR Note : +there are cases where +.BR setuid () +can fail even when the caller is UID 0; +it is a grave security error to omit checking for a failure return from +.BR setuid (). +.SH ERRORS +.TP +.B EAGAIN +The call would change the caller's real UID (i.e., +.I uid +does not match the caller's real UID), +but there was a temporary failure allocating the +necessary kernel data structures. +.TP +.B EAGAIN +.I uid +does not match the real user ID of the caller and this call would +bring the number of processes belonging to the real user ID +.I uid +over the caller's +.B RLIMIT_NPROC +resource limit. +Since Linux 3.1, this error case no longer occurs +(but robust applications should check for this error); +see the description of +.B EAGAIN +in +.BR execve (2). +.TP +.B EINVAL +The user ID specified in +.I uid +is not valid in this user namespace. +.TP +.B EPERM +The user is not privileged (Linux: does not have the +.B CAP_SETUID +capability) and +.I uid +does not match the real UID or saved set-user-ID of the calling process. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +Not quite compatible with the 4.4BSD call, which +sets all of the real, saved, and effective user IDs. +.\" SVr4 documents an additional EINVAL error condition. +.SH NOTES +Linux has the concept of the filesystem user ID, normally equal to the +effective user ID. +The +.BR setuid () +call also sets the filesystem user ID of the calling process. +See +.BR setfsuid (2). +.PP +If +.I uid +is different from the old effective UID, the process will +be forbidden from leaving core dumps. +.PP +The original Linux +.BR setuid () +system call supported only 16-bit user IDs. +Subsequently, Linux 2.4 added +.BR setuid32 () +supporting 32-bit IDs. +The glibc +.BR setuid () +wrapper function transparently deals with the variation across kernel versions. +.\" +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including the one for +.BR setuid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH SEE ALSO +.BR getuid (2), +.BR seteuid (2), +.BR setfsuid (2), +.BR setreuid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setuid32.2 b/man2/setuid32.2 new file mode 100644 index 0000000..24656c2 --- /dev/null +++ b/man2/setuid32.2 @@ -0,0 +1 @@ +.so man2/setuid.2 diff --git a/man2/setup.2 b/man2/setup.2 new file mode 100644 index 0000000..02e3d3d --- /dev/null +++ b/man2/setup.2 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified Sun Jul 25 10:14:13 1993 by Rik Faith +.\" Modified 15 April 1995 by Michael Chastain +.\" Update calling parameters to Linux 1.2.4 values. +.\" Modified 10 June 1995 by Andries Brouwer +.\" Modified 3 May 1996 by Martin Schulze +.\" Modified Wed Nov 6 04:05:28 1996 by Eric S. Raymond +.\" Modified Sat Jan 29 01:08:23 2000 by aeb +.\" +.TH SETUP 2 2008-12-03 "Linux" "Linux Programmer's Manual" +.SH NAME +setup \- setup devices and filesystems, mount root filesystem +.SH SYNOPSIS +.B #include +.PP +.B int setup(void); +.SH DESCRIPTION +.BR setup () +is called once from within +.IR linux/init/main.c . +It calls initialization functions for devices and filesystems +configured into the kernel and then mounts the root filesystem. +.PP +No user process may call +.BR setup (). +Any user process, even a process with superuser permission, +will receive +.BR EPERM . +.SH RETURN VALUE +.BR setup () +always returns \-1 for a user process. +.SH ERRORS +.TP +.B EPERM +Always, for a user process. +.SH VERSIONS +Since Linux 2.1.121, no such function exists anymore. +.SH CONFORMING TO +This function is Linux-specific, and should not be used in programs +intended to be portable, or indeed in any programs at all. +.SH NOTES +The calling sequence varied: at some times +.BR setup () +has had a single argument +.I "void\ *BIOS" +and at other times a single argument +.IR "int magic" . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/setxattr.2 b/man2/setxattr.2 new file mode 100644 index 0000000..8c7ccd3 --- /dev/null +++ b/man2/setxattr.2 @@ -0,0 +1,181 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH SETXATTR 2 2017-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +setxattr, lsetxattr, fsetxattr \- set an extended attribute value +.SH SYNOPSIS +.fam C +.nf +.B #include +.B #include +.PP +.BI "int setxattr(const char\ *" path ", const char\ *" name , +.BI " const void\ *" value ", size_t " size ", int " flags ); +.BI "int lsetxattr(const char\ *" path ", const char\ *" name , +.BI " const void\ *" value ", size_t " size ", int " flags ); +.BI "int fsetxattr(int " fd ", const char\ *" name , +.BI " const void\ *" value ", size_t " size ", int " flags ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +.I value +pairs associated with inodes (files, directories, symbolic links, etc.). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e., the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR xattr (7). +.PP +.BR setxattr () +sets the +.I value +of the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +The +.I size +argument specifies the size (in bytes) of +.IR value ; +a zero-length value is permitted. +.PP +.BR lsetxattr () +is identical to +.BR setxattr (), +except in the case of a symbolic link, where the extended attribute is +set on the link itself, not the file that it refers to. +.PP +.BR fsetxattr () +is identical to +.BR setxattr (), +only the extended attribute is set on the open file referred to by +.I fd +(as returned by +.BR open (2)) +in place of +.IR path . +.PP +An extended attribute name is a null-terminated string. +The +.I name +includes a namespace prefix; there may be several, disjoint +namespaces associated with an individual inode. +The +.I value +of an extended attribute is a chunk of arbitrary textual or +binary data of specified length. +.PP +By default +(i.e., +.IR flags +is zero), +the extended attribute will be created if it does not exist, +or the value will be replaced if the attribute already exists. +To modify these semantics, one of the following values can be specified in +.IR flags : +.TP +.B XATTR_CREATE +Perform a pure create, which fails if the named attribute exists already. +.TP +.B XATTR_REPLACE +Perform a pure replace operation, +which fails if the named attribute does not already exist. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EDQUOT +Disk quota limits meant that +there is insufficient space remaining to store the extended attribute. +.TP +.B EEXIST +.B XATTR_CREATE +was specified, and the attribute exists already. +.TP +.B ENOATTR +.B XATTR_REPLACE +was specified, and the attribute does not exist. +.RB ( ENOATTR +is defined to be a synonym for +.BR ENODATA +in +.IR .) +.TP +.B ENOSPC +There is insufficient space remaining to store the extended attribute. +.TP +.B ENOTSUP +The namespace prefix of +.I name +is not valid. +.TP +.B ENOTSUP +Extended attributes are not supported by the filesystem, or are disabled, +.TP +.B EPERM +The file is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.PP +In addition, the errors documented in +.BR stat (2) +can also occur. +.SH VERSIONS +These system calls have been available on Linux since kernel 2.4; +glibc support is provided since version 2.3. +.SH CONFORMING TO +These system calls are Linux-specific. +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR listxattr (2), +.BR open (2), +.BR removexattr (2), +.BR stat (2), +.BR symlink (7), +.BR xattr (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sgetmask.2 b/man2/sgetmask.2 new file mode 100644 index 0000000..0d80b25 --- /dev/null +++ b/man2/sgetmask.2 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (c) 2007 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SGETMASK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sgetmask, ssetmask \- manipulation of signal mask (obsolete) +.SH SYNOPSIS +.B "long sgetmask(void);" +.PP +.BI "long ssetmask(long " newmask ); +.PP +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +These system calls are obsolete. +.IR "Do not use them" ; +use +.BR sigprocmask (2) +instead. +.PP +.BR sgetmask () +returns the signal mask of the calling process. +.PP +.BR ssetmask () +sets the signal mask of the calling process to the value given in +.IR newmask . +The previous signal mask is returned. +.PP +The signal masks dealt with by these two system calls +are plain bit masks (unlike the +.I sigset_t +used by +.BR sigprocmask (2)); +use +.BR sigmask (3) +to create and inspect these masks. +.SH RETURN VALUE +.BR sgetmask () +always successfully returns the signal mask. +.BR ssetmask () +always succeeds, and returns the previous signal mask. +.SH ERRORS +These system calls always succeed. +.SH VERSIONS +Since Linux 3.16, +.\" f6187769dae48234f3877df3c4d99294cc2254fa +support for these system calls is optional, +depending on whether the kernel was built with the +.B CONFIG_SGETMASK_SYSCALL +option. +.SH CONFORMING TO +These system calls are Linux-specific. +.SH NOTES +Glibc does not provide wrappers for these obsolete system calls; +in the unlikely event that you want to call them, use +.BR syscall (2). +.PP +These system calls are unaware of signal numbers greater than 31 +(i.e., real-time signals). +.PP +These system calls do not exist on x86-64. +.PP +It is not possible to block +.B SIGSTOP +or +.BR SIGKILL . +.SH SEE ALSO +.BR sigprocmask (2), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/shmat.2 b/man2/shmat.2 new file mode 100644 index 0000000..3f3e5a4 --- /dev/null +++ b/man2/shmat.2 @@ -0,0 +1 @@ +.so man2/shmop.2 diff --git a/man2/shmctl.2 b/man2/shmctl.2 new file mode 100644 index 0000000..404f28f --- /dev/null +++ b/man2/shmctl.2 @@ -0,0 +1,441 @@ +.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993 +.\" and Copyright 1993 Giorgio Ciucci +.\" and Copyright 2004, 2005 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-28, Rik Faith +.\" Modified 1993-11-28, Giorgio Ciucci +.\" Modified 1997-01-31, Eric S. Raymond +.\" Modified 2001-02-18, Andries Brouwer +.\" Modified 2002-01-05, 2004-05-27, 2004-06-17, +.\" Michael Kerrisk +.\" Modified 2004-10-11, aeb +.\" Modified, Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Updated shmid_ds structure definitions +.\" Added information on SHM_DEST and SHM_LOCKED flags +.\" Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK +.\" since kernel 2.6.9 +.\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes +.\" 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new +.\" attaches to a segment that has already been marked for deletion. +.\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions. +.\" +.TH SHMCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +shmctl \- System V shared memory control +.SH SYNOPSIS +.ad l +.B #include +.br +.B #include +.PP +.BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf ); +.ad b +.SH DESCRIPTION +.BR shmctl () +performs the control operation specified by +.I cmd +on the System\ V shared memory segment whose identifier is given in +.IR shmid . +.PP +The +.I buf +argument is a pointer to a \fIshmid_ds\fP structure, +defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct shmid_ds { + struct ipc_perm shm_perm; /* Ownership and permissions */ + size_t shm_segsz; /* Size of segment (bytes) */ + time_t shm_atime; /* Last attach time */ + time_t shm_dtime; /* Last detach time */ + time_t shm_ctime; /* Last change time */ + pid_t shm_cpid; /* PID of creator */ + pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */ + shmatt_t shm_nattch; /* No. of current attaches */ + ... +}; +.EE +.in +.PP +The +.I ipc_perm +structure is defined as follows +(the highlighted fields are settable using +.BR IPC_SET ): +.PP +.in +4n +.EX +struct ipc_perm { + key_t __key; /* Key supplied to shmget(2) */ + uid_t \fBuid\fP; /* Effective UID of owner */ + gid_t \fBgid\fP; /* Effective GID of owner */ + uid_t cuid; /* Effective UID of creator */ + gid_t cgid; /* Effective GID of creator */ + unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and + SHM_LOCKED flags */ + unsigned short __seq; /* Sequence number */ +}; +.EE +.in +.PP +Valid values for +.I cmd +are: +.TP 10 +.B IPC_STAT +Copy information from the kernel data structure associated with +.I shmid +into the +.I shmid_ds +structure pointed to by \fIbuf\fP. +The caller must have read permission on the +shared memory segment. +.TP +.B IPC_SET +Write the values of some members of the +.I shmid_ds +structure pointed to by +.I buf +to the kernel data structure associated with this shared memory segment, +updating also its +.I shm_ctime +member. +The following fields can be changed: +\fIshm_perm.uid\fP, \fIshm_perm.gid\fP, +and (the least significant 9 bits of) \fIshm_perm.mode\fP. +The effective UID of the calling process must match the owner +.RI ( shm_perm.uid ) +or creator +.RI ( shm_perm.cuid ) +of the shared memory segment, or the caller must be privileged. +.TP +.B IPC_RMID +Mark the segment to be destroyed. +The segment will actually be destroyed +only after the last process detaches it (i.e., when the +.I shm_nattch +member of the associated structure +.I shmid_ds +is zero). +The caller must be the owner or creator of the segment, or be privileged. +The +.I buf +argument is ignored. +.IP +If a segment has been marked for destruction, then the (nonstandard) +.B SHM_DEST +flag of the +.I shm_perm.mode +field in the associated data structure retrieved by +.B IPC_STAT +will be set. +.IP +The caller \fImust\fP ensure that a segment is eventually destroyed; +otherwise its pages that were faulted in will remain in memory or swap. +.IP +See also the description of +.I /proc/sys/kernel/shm_rmid_forced +in +.BR proc (5). +.TP 10 +.BR IPC_INFO " (Linux-specific)" +Return information about system-wide shared memory limits and +parameters in the structure pointed to by +.IR buf . +This structure is of type +.I shminfo +(thus, a cast is required), +defined in +.I +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct shminfo { + unsigned long shmmax; /* Maximum segment size */ + unsigned long shmmin; /* Minimum segment size; + always 1 */ + unsigned long shmmni; /* Maximum number of segments */ + unsigned long shmseg; /* Maximum number of segments + that a process can attach; + unused within kernel */ + unsigned long shmall; /* Maximum number of pages of + shared memory, system-wide */ +}; +.EE +.in +.IP +The +.IR shmmni , +.IR shmmax , +and +.I shmall +settings can be changed via +.I /proc +files of the same name; see +.BR proc (5) +for details. +.TP +.BR SHM_INFO " (Linux-specific)" +Return a +.I shm_info +structure whose fields contain information +about system resources consumed by shared memory. +This structure is defined in +.I +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct shm_info { + int used_ids; /* # of currently existing + segments */ + unsigned long shm_tot; /* Total number of shared + memory pages */ + unsigned long shm_rss; /* # of resident shared + memory pages */ + unsigned long shm_swp; /* # of swapped shared + memory pages */ + unsigned long swap_attempts; + /* Unused since Linux 2.4 */ + unsigned long swap_successes; + /* Unused since Linux 2.4 */ +}; +.EE +.in +.TP +.BR SHM_STAT " (Linux-specific)" +Return a +.I shmid_ds +structure as for +.BR IPC_STAT . +However, the +.I shmid +argument is not a segment identifier, but instead an index into +the kernel's internal array that maintains information about +all shared memory segments on the system. +.PP +The caller can prevent or allow swapping of a shared +memory segment with the following \fIcmd\fP values: +.TP 10 +.BR SHM_LOCK " (Linux-specific)" +Prevent swapping of the shared memory segment. +The caller must fault in +any pages that are required to be present after locking is enabled. +If a segment has been locked, then the (nonstandard) +.B SHM_LOCKED +flag of the +.I shm_perm.mode +field in the associated data structure retrieved by +.B IPC_STAT +will be set. +.TP +.BR SHM_UNLOCK " (Linux-specific)" +Unlock the segment, allowing it to be swapped out. +.PP +In kernels before 2.6.10, only a privileged process +could employ +.B SHM_LOCK +and +.BR SHM_UNLOCK . +Since kernel 2.6.10, an unprivileged process can employ these operations +if its effective UID matches the owner or creator UID of the segment, and +(for +.BR SHM_LOCK ) +the amount of memory to be locked falls within the +.B RLIMIT_MEMLOCK +resource limit (see +.BR setrlimit (2)). +.\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could +.\" be applied to a segment, regardless of ownership of the segment. +.\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed +.\" in 2.6.10. MTK, May 2005 +.SH RETURN VALUE +A successful +.B IPC_INFO +or +.B SHM_INFO +operation returns the index of the highest used entry in the +kernel's internal array recording information about all +shared memory segments. +(This information can be used with repeated +.B SHM_STAT +operations to obtain information about all shared memory segments +on the system.) +A successful +.B SHM_STAT +operation returns the identifier of the shared memory segment +whose index was given in +.IR shmid . +Other operations return 0 on success. +.PP +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +\fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and +\fIshm_perm.mode\fP does not allow read access for +.IR shmid , +and the calling process does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The argument +.I cmd +has value +.B IPC_SET +or +.B IPC_STAT +but the address pointed to by +.I buf +isn't accessible. +.TP +.B EIDRM +\fIshmid\fP points to a removed identifier. +.TP +.B EINVAL +\fIshmid\fP is not a valid identifier, or \fIcmd\fP +is not a valid command. +Or: for a +.B SHM_STAT +operation, the index value specified in +.I shmid +referred to an array slot that is currently unused. +.TP +.B ENOMEM +(In kernels since 2.6.9), +.B SHM_LOCK +was specified and the size of the to-be-locked segment would mean +that the total bytes in locked shared memory segments would exceed +the limit for the real user ID of the calling process. +This limit is defined by the +.B RLIMIT_MEMLOCK +soft resource limit (see +.BR setrlimit (2)). +.TP +.B EOVERFLOW +\fBIPC_STAT\fP is attempted, and the GID or UID value +is too large to be stored in the structure pointed to by +.IR buf . +.TP +.B EPERM +\fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the +effective user ID of the calling process is not that of the creator +(found in +.IR shm_perm.cuid ), +or the owner +(found in +.IR shm_perm.uid ), +and the process was not privileged (Linux: did not have the +.B CAP_SYS_ADMIN +capability). +.IP +Or (in kernels before 2.6.9), +.B SHM_LOCK +or +.B SHM_UNLOCK +was specified, but the process was not privileged +(Linux: did not have the +.B CAP_IPC_LOCK +capability). +(Since Linux 2.6.9, this error can also occur if the +.B RLIMIT_MEMLOCK +is 0 and the caller is not privileged.) +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVr4 documents additional error conditions EINVAL, +.\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents +.\" an EIDRM error condition. +.SH NOTES +The inclusion of +.I +and +.I +isn't required on Linux or by any version of POSIX. +However, +some old implementations required the inclusion of these header files, +and the SVID also documented their inclusion. +Applications intended to be portable to such old systems may need +to include these header files. +.\" Like Linux, the FreeBSD man pages still document +.\" the inclusion of these header files. +.PP +The +.BR IPC_INFO , +.B SHM_STAT +and +.B SHM_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future, these may modified or moved to a +.I /proc +filesystem interface. +.PP +Linux permits a process to attach +.RB ( shmat (2)) +a shared memory segment that has already been marked for deletion +using +.IR shmctl(IPC_RMID) . +This feature is not available on other UNIX implementations; +portable applications should avoid relying on it. +.PP +Various fields in a \fIstruct shmid_ds\fP were typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR cmd .) +.SH SEE ALSO +.BR mlock (2), +.BR setrlimit (2), +.BR shmget (2), +.BR shmop (2), +.BR capabilities (7), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/shmdt.2 b/man2/shmdt.2 new file mode 100644 index 0000000..3f3e5a4 --- /dev/null +++ b/man2/shmdt.2 @@ -0,0 +1 @@ +.so man2/shmop.2 diff --git a/man2/shmget.2 b/man2/shmget.2 new file mode 100644 index 0000000..c70b624 --- /dev/null +++ b/man2/shmget.2 @@ -0,0 +1,422 @@ +.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 28 10:57:35 1993, Rik Faith +.\" Modified Sun Nov 28 16:43:30 1993, Rik Faith +.\" with material from Giorgio Ciucci +.\" Portions Copyright 1993 Giorgio Ciucci +.\" Modified Tue Oct 22 22:03:17 1996 by Eric S. Raymond +.\" Modified, 8 Jan 2003, Michael Kerrisk, +.\" Removed EIDRM from errors - that can't happen... +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" +.TH SHMGET 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +shmget \- allocates a System V shared memory segment +.SH SYNOPSIS +.ad l +.B #include +.br +.B #include +.PP +.BI "int shmget(key_t " key ", size_t " size ", int " shmflg ); +.ad b +.SH DESCRIPTION +.BR shmget () +returns the identifier of the System\ V shared memory segment +associated with the value of the argument +.IR key . +A new shared memory segment, with size equal to the value of +.I size +rounded up to a multiple of +.BR PAGE_SIZE , +is created if +.I key +has the value +.B IPC_PRIVATE +or +.I key +isn't +.BR IPC_PRIVATE , +no shared memory segment corresponding to +.I key +exists, and +.B IPC_CREAT +is specified in +.IR shmflg . +.PP +If +.I shmflg +specifies both +.B IPC_CREAT +and +.B IPC_EXCL +and a shared memory segment already exists for +.IR key , +then +.BR shmget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) +.PP +The value +.I shmflg +is composed of: +.TP 12 +.B IPC_CREAT +Create a new segment. +If this flag is not used, then +.BR shmget () +will find the segment associated with \fIkey\fP and check to see if +the user has permission to access the segment. +.TP +.B IPC_EXCL +This flag is used with +.B IPC_CREAT +to ensure that this call creates the segment. +If the segment already exists, the call fails. +.TP +.BR SHM_HUGETLB " (since Linux 2.6)" +Allocate the segment using "huge pages." +See the Linux kernel source file +.I Documentation/vm/hugetlbpage.txt +for further information. +.TP +.BR SHM_HUGE_2MB ", " SHM_HUGE_1GB " (since Linux 3.8)" +.\" See https://lwn.net/Articles/533499/ +Used in conjunction with +.B SHM_HUGETLB +to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) +on systems that support multiple hugetlb page sizes. +.IP +More generally, the desired huge page size can be configured by encoding +the base-2 logarithm of the desired page size in the six bits at the offset +.BR SHM_HUGE_SHIFT . +Thus, the above two constants are defined as: +.IP +.in +4 +.EX +#define SHM_HUGE_2MB (21 << SHM_HUGE_SHIFT) +#define SHM_HUGE_1GB (30 << SHM_HUGE_SHIFT) +.EE +.in +.IP +For some additional details, +see the discussion of the similarly named constants in +.BR mmap (2). +.TP +.BR SHM_NORESERVE " (since Linux 2.6.15)" +This flag serves the same purpose as the +.BR mmap (2) +.B MAP_NORESERVE +flag. +Do not reserve swap space for this segment. +When swap space is reserved, one has the guarantee +that it is possible to modify the segment. +When swap space is not reserved one might get +.B SIGSEGV +upon a write +if no physical memory is available. +See also the discussion of the file +.I /proc/sys/vm/overcommit_memory +in +.BR proc (5). +.\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also +.\" specified. +.PP +In addition to the above flags, the least significant 9 bits of +.I shmflg +specify the permissions granted to the owner, group, and others. +These bits have the same format, and the same +meaning, as the +.I mode +argument of +.BR open (2). +Presently, execute permissions are not used by the system. +.PP +When a new shared memory segment is created, +its contents are initialized to zero values, and +its associated data structure, +.I shmid_ds +(see +.BR shmctl (2)), +is initialized as follows: +.IP +.I shm_perm.cuid +and +.I shm_perm.uid +are set to the effective user ID of the calling process. +.IP +.I shm_perm.cgid +and +.I shm_perm.gid +are set to the effective group ID of the calling process. +.IP +The least significant 9 bits of +.I shm_perm.mode +are set to the least significant 9 bit of +.IR shmflg . +.IP +.I shm_segsz +is set to the value of +.IR size . +.IP +.IR shm_lpid , +.IR shm_nattch , +.IR shm_atime , +and +.I shm_dtime +are set to 0. +.IP +.I shm_ctime +is set to the current time. +.PP +If the shared memory segment already exists, the permissions are +verified, and a check is made to see if it is marked for destruction. +.SH RETURN VALUE +On success, a valid shared memory identifier is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +On failure, +.I errno +is set to one of the following: +.TP +.B EACCES +The user does not have permission to access the +shared memory segment, and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EEXIST +.BR IPC_CREAT +and +.BR IPC_EXCL +were specified in +.IR shmflg , +but a shared memory segment already exists for +.IR key . +.TP +.B EINVAL +A new segment was to be created and +.I size +is less than +.B SHMMIN +or greater than +.BR SHMMAX . +.TP +.B EINVAL +A segment for the given +.I key +exists, but \fIsize\fP is greater than the size +of that segment. +.TP +.B ENFILE +.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +No segment exists for the given \fIkey\fP, and +.B IPC_CREAT +was not specified. +.TP +.B ENOMEM +No memory could be allocated for segment overhead. +.TP +.B ENOSPC +All possible shared memory IDs have been taken +.RB ( SHMMNI ), +or allocating a segment of the requested +.I size +would cause the system to exceed the system-wide limit on shared memory +.RB ( SHMALL ). +.TP +.B EPERM +The +.B SHM_HUGETLB +flag was specified, but the caller was not privileged (did not have the +.B CAP_IPC_LOCK +capability). +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVr4 documents an additional error condition EEXIST. +.PP +.B SHM_HUGETLB +and +.B SHM_NORESERVE +are Linux extensions. +.SH NOTES +The inclusion of +.I +and +.I +isn't required on Linux or by any version of POSIX. +However, +some old implementations required the inclusion of these header files, +and the SVID also documented their inclusion. +Applications intended to be portable to such old systems may need +to include these header files. +.\" Like Linux, the FreeBSD man pages still document +.\" the inclusion of these header files. +.PP +.B IPC_PRIVATE +isn't a flag field but a +.I key_t +type. +If this special value is used for +.IR key , +the system call ignores all but the least significant 9 bits of +.I shmflg +and creates a new shared memory segment. +.\" +.SS Shared memory limits +The following limits on shared memory segment resources affect the +.BR shmget () +call: +.TP +.B SHMALL +System-wide limit on the total amount of shared memory, +measured in units of the system page size. +.IP +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmall . +Since Linux 3.16, +.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31 +the default value for this limit is: +.IP + ULONG_MAX - 2^24 +.IP +The effect of this value +(which is suitable for both 32-bit and 64-bit systems) +is to impose no limitation on allocations. +This value, rather than +.BR ULONG_MAX , +was chosen as the default to prevent some cases where historical +applications simply raised the existing limit without first checking +its current value. +Such applications would cause the value to overflow if the limit was set at +.BR ULONG_MAX . +.IP +From Linux 2.4 up to Linux 3.15, +the default value for this limit was: +.IP + SHMMAX / PAGE_SIZE * (SHMMNI / 16) +.IP +If +.B SHMMAX +and +.B SHMMNI +were not modified, then multiplying the result of this formula +by the page size (to get a value in bytes) yielded a value of 8\ GB +as the limit on the total memory used by all shared memory segments. +.TP +.B SHMMAX +Maximum size in bytes for a shared memory segment. +.IP +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmmax . +Since Linux 3.16, +.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31 +the default value for this limit is: +.IP + ULONG_MAX - 2^24 +.IP +The effect of this value +(which is suitable for both 32-bit and 64-bit systems) +is to impose no limitation on allocations. +See the description of +.BR SHMALL +for a discussion of why this default value (rather than +.BR ULONG_MAX ) +is used. +.IP +From Linux 2.2 up to Linux 3.15, the default value of +this limit was 0x2000000 (32\ MB). +.IP +Because it is not possible to map just part of a shared memory segment, +the amount of virtual memory places another limit on the maximum size of a +usable segment: +for example, on i386 the largest segments that can be mapped have a +size of around 2.8\ GB, and on x86-64 the limit is around 127 TB. +.TP +.B SHMMIN +Minimum size in bytes for a shared memory segment: implementation +dependent (currently 1 byte, though +.B PAGE_SIZE +is the effective minimum size). +.TP +.B SHMMNI +System-wide limit on the number of shared memory segments. +In Linux 2.2, the default value for this limit was 128; +since Linux 2.4, the default value is 4096. +.IP +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmmni . +.\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant +.\" that we could create one more segment than SHMMNI -- MTK +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK +.PP +The implementation has no specific limits for the per-process maximum +number of shared memory segments +.RB ( SHMSEG ). +.SS Linux notes +Until version 2.3.30, Linux would return +.B EIDRM +for a +.BR shmget () +on a shared memory segment scheduled for deletion. +.SH BUGS +The name choice +.B IPC_PRIVATE +was perhaps unfortunate, +.B IPC_NEW +would more clearly show its function. +.SH SEE ALSO +.BR memfd_create (2), +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR ftok (3), +.BR capabilities (7), +.BR shm_overview (7), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/shmop.2 b/man2/shmop.2 new file mode 100644 index 0000000..798fa77 --- /dev/null +++ b/man2/shmop.2 @@ -0,0 +1,311 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu) +.\" with material from Luigi P. Bai (lpb@softint.com) +.\" Portions Copyright 1993 Luigi P. Bai +.\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond +.\" Modified, 5 Jan 2002, Michael Kerrisk +.\" Modified, 19 Sep 2002, Michael Kerrisk +.\" Added SHM_REMAP flag description +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Changed wording and placement of sentence regarding attachment +.\" of segments marked for destruction +.\" +.\" FIXME . Add an example program to this page. +.\" +.TH SHMOP 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +shmat, shmdt \- System V shared memory operations +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "void *shmat(int " shmid ", const void *" shmaddr ", int " shmflg ); +.PP +.BI "int shmdt(const void *" shmaddr ); +.fi +.SH DESCRIPTION +.SS shmat() +.BR shmat () +attaches the System\ V shared memory segment identified by +.I shmid +to the address space of the calling process. +The attaching address is specified by +.I shmaddr +with one of the following criteria: +.IP * 3 +If +.I shmaddr +is NULL, +the system chooses a suitable (unused) page-aligned address to attach +the segment. +.IP * +If +.I shmaddr +isn't NULL +and +.B SHM_RND +is specified in +.IR shmflg , +the attach occurs at the address equal to +.I shmaddr +rounded down to the nearest multiple of +.BR SHMLBA . +.IP * +Otherwise, +.I shmaddr +must be a page-aligned address at which the attach occurs. +.PP +In addition to +.BR SHM_RND , +the following flags may be specified in the +.I shmflg +bit-mask argument: +.TP +.BR SHM_EXEC " (Linux-specific; since Linux 2.6.9)" +Allow the contents of the segment to be executed. +The caller must have execute permission on the segment. +.TP +.BR SHM_RDONLY +Attach the segment for read-only access. +The process must have read permission for the segment. +If this flag is not specified, +the segment is attached for read and write access, +and the process must have read and write permission for the segment. +There is no notion of a write-only shared memory segment. +.TP +.BR SHM_REMAP " (Linux-specific)" +This flag specifies +that the mapping of the segment should replace +any existing mapping in the range starting at +.I shmaddr +and continuing for the size of the segment. +(Normally, an +.B EINVAL +error would result if a mapping already exists in this address range.) +In this case, +.I shmaddr +must not be NULL. +.PP +The +.BR brk (2) +value of the calling process is not altered by the attach. +The segment will automatically be detached at process exit. +The same segment may be attached as a read and as a read-write +one, and more than once, in the process's address space. +.PP +A successful +.BR shmat () +call updates the members of the +.I shmid_ds +structure (see +.BR shmctl (2)) +associated with the shared memory segment as follows: +.IP +.I shm_atime +is set to the current time. +.IP +.I shm_lpid +is set to the process-ID of the calling process. +.IP +.I shm_nattch +is incremented by one. +.\" +.SS shmdt() +.BR shmdt () +detaches the shared memory segment located at the address specified by +.I shmaddr +from the address space of the calling process. +The to-be-detached segment must be currently +attached with +.I shmaddr +equal to the value returned by the attaching +.BR shmat () +call. +.PP +On a successful +.BR shmdt () +call, the system updates the members of the +.I shmid_ds +structure associated with the shared memory segment as follows: +.IP +.I shm_dtime +is set to the current time. +.IP +.I shm_lpid +is set to the process-ID of the calling process. +.IP +.I shm_nattch +is decremented by one. +If it becomes 0 and the segment is marked for deletion, +the segment is deleted. +.SH RETURN VALUE +On success, +.BR shmat () +returns the address of the attached shared memory segment; on error, +.I (void\ *)\ \-1 +is returned, and +.I errno +is set to indicate the cause of the error. +.PP +On success, +.BR shmdt () +returns 0; on error \-1 is returned, and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +When +.BR shmat () +fails, +.I errno +is set to one of the following: +.TP +.B EACCES +The calling process does not have the required permissions for +the requested attach type, and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EIDRM +\fIshmid\fP points to a removed identifier. +.TP +.B EINVAL +Invalid +.I shmid +value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not +specified) or invalid +.I shmaddr +value, or can't attach segment at +.IR shmaddr , +or +.B SHM_REMAP +was specified and +.I shmaddr +was NULL. +.TP +.B ENOMEM +Could not allocate memory for the descriptor or for the page tables. +.PP +When +.BR shmdt () +fails, +.I errno +is set as follows: +.TP +.B EINVAL +There is no shared memory segment attached at +.IR shmaddr ; +or, +.\" The following since 2.6.17-rc1: +.I shmaddr +is not aligned on a page boundary. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVr4 documents an additional error condition EMFILE. +.PP +In SVID 3 (or perhaps earlier), +the type of the \fIshmaddr\fP argument was changed from +.I "char\ *" +into +.IR "const void\ *" , +and the returned type of +.BR shmat () +from +.I "char\ *" +into +.IR "void\ *" . +.SH NOTES +.PP +After a +.BR fork (2), +the child inherits the attached shared memory segments. +.PP +After an +.BR execve (2), +all attached shared memory segments are detached from the process. +.PP +Upon +.BR _exit (2), +all attached shared memory segments are detached from the process. +.PP +Using +.BR shmat () +with +.I shmaddr +equal to NULL +is the preferred, portable way of attaching a shared memory segment. +Be aware that the shared memory segment attached in this way +may be attached at different addresses in different processes. +Therefore, any pointers maintained within the shared memory must be +made relative (typically to the starting address of the segment), +rather than absolute. +.PP +On Linux, it is possible to attach a shared memory segment even if it +is already marked to be deleted. +However, POSIX.1 does not specify this behavior and +many other implementations do not support it. +.PP +The following system parameter affects +.BR shmat (): +.TP +.B SHMLBA +Segment low boundary address multiple. +When explicitly specifying an attach address in a call to +.BR shmat (), +the caller should ensure that the address is a multiple of this value. +This is necessary on some architectures, +in order either to ensure good CPU cache performance or to ensure that +different attaches of the same segment have consistent views +within the CPU cache. +.B SHMLBA +is normally some multiple of the system page size. +(On many Linux architectures, +.B SHMLBA +is the same as the system page size.) +.PP +The implementation places no intrinsic per-process limit on the +number of shared memory segments +.RB ( SHMSEG ). +.SH SEE ALSO +.BR brk (2), +.BR mmap (2), +.BR shmctl (2), +.BR shmget (2), +.BR capabilities (7), +.BR shm_overview (7), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/shutdown.2 b/man2/shutdown.2 new file mode 100644 index 0000000..0bc7a3e --- /dev/null +++ b/man2/shutdown.2 @@ -0,0 +1,128 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" $Id: shutdown.2,v 1.1.1.1 1999/03/21 22:52:23 freitag Exp $ +.\" +.\" Modified Sat Jul 24 09:57:55 1993 by Rik Faith +.\" Modified Tue Oct 22 22:04:51 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" +.TH SHUTDOWN 2 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +shutdown \- shut down part of a full-duplex connection +.SH SYNOPSIS +.B #include +.PP +.BI "int shutdown(int " sockfd ", int " how ); +.SH DESCRIPTION +The +.BR shutdown () +call causes all or part of a full-duplex connection on the socket +associated with +.I sockfd +to be shut down. +If +.I how +is +.BR SHUT_RD , +further receptions will be disallowed. +If +.I how +is +.BR SHUT_WR , +further transmissions will be disallowed. +If +.I how +is +.BR SHUT_RDWR , +further receptions and transmissions will be disallowed. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I sockfd +is not a valid file descriptor. +.TP +.B EINVAL +An invalid value was specified in +.IR how +(but see BUGS). +.TP +.B ENOTCONN +The specified socket is not connected. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.4BSD +.RB ( shutdown () +first appeared in 4.2BSD). +.SH NOTES +The constants +.BR SHUT_RD , +.BR SHUT_WR , +.B SHUT_RDWR +have the value 0, 1, 2, +respectively, and are defined in +.I +since glibc-2.1.91. +.SH BUGS +Checks for the validity of +.I how +are done in domain-specific code, +and before Linux 3.7 not all domains performed these checks. +.\" https://bugzilla.kernel.org/show_bug.cgi?id=47111 +Most notably, UNIX domain sockets simply ignored invalid values. +This problem was fixed for UNIX domain sockets +.\" commit fc61b928dc4d72176cf4bd4d30bf1d22e599aefc +.\" and for DECnet sockets in commit 46b66d7077b89fb4917ceef19b3f7dd86055c94a +in Linux 3.7. +.SH SEE ALSO +.BR connect (2), +.BR socket (2), +.BR socket (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sigaction.2 b/man2/sigaction.2 new file mode 100644 index 0000000..7c87c14 --- /dev/null +++ b/man2/sigaction.2 @@ -0,0 +1,1057 @@ +'\" t +.\" Copyright (c) 1994,1995 Mike Battersby +.\" and Copyright 2004, 2005 Michael Kerrisk +.\" based on work by faith@cs.unc.edu +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified, aeb, 960424 +.\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond +.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. +.\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox +.\" add POSIX.1b signals +.\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones +.\" SA_ONSTACK +.\" Modified 2004-11-11 by Michael Kerrisk +.\" Added mention of SIGCONT under SA_NOCLDSTOP +.\" Added SA_NOCLDWAIT +.\" Modified 2004-11-17 by Michael Kerrisk +.\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags. +.\" Formatting fixes +.\" 2004-12-09, mtk, added SI_TKILL + other minor changes +.\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend() +.\" out of this page into separate pages. +.\" 2010-06-11 Andi Kleen, add hwpoison signal extensions +.\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields. +.\" 2015-01-17, Kees Cook +.\" Added notes on ptrace SIGTRAP and SYS_SECCOMP. +.\" +.TH SIGACTION 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigaction, rt_sigaction \- examine and change a signal action +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sigaction(int " signum ", const struct sigaction *" act , +.BI " struct sigaction *" oldact ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sigaction (): +_POSIX_C_SOURCE +.PP +.IR siginfo_t : +_POSIX_C_SOURCE >= 199309L +.ad b +.SH DESCRIPTION +The +.BR sigaction () +system call is used to change the action taken by a process on +receipt of a specific signal. +(See +.BR signal (7) +for an overview of signals.) +.PP +.I signum +specifies the signal and can be any valid signal except +.B SIGKILL +and +.BR SIGSTOP . +.PP +If +.I act +is non-NULL, the new action for signal +.I signum +is installed from +.IR act . +If +.I oldact +is non-NULL, the previous action is saved in +.IR oldact . +.PP +The +.I sigaction +structure is defined as something like: +.PP +.in +4n +.EX +struct sigaction { + void (*sa_handler)(int); + void (*sa_sigaction)(int, siginfo_t *, void *); + sigset_t sa_mask; + int sa_flags; + void (*sa_restorer)(void); +}; +.EE +.in +.PP +On some architectures a union is involved: do not assign to both +.I sa_handler +and +.IR sa_sigaction . +.PP +The +.I sa_restorer +field is not intended for application use. +(POSIX does not specify a +.I sa_restorer +field.) +Some further details of the purpose of this field can be found in +.BR sigreturn (2). +.PP +.I sa_handler +specifies the action to be associated with +.I signum +and may be +.B SIG_DFL +for the default action, +.B SIG_IGN +to ignore this signal, or a pointer to a signal handling function. +This function receives the signal number as its only argument. +.PP +If +.B SA_SIGINFO +is specified in +.IR sa_flags , +then +.I sa_sigaction +(instead of +.IR sa_handler ) +specifies the signal-handling function for +.IR signum . +This function receives three arguments, as described below. +.PP +.I sa_mask +specifies a mask of signals which should be blocked +(i.e., added to the signal mask of the thread in which +the signal handler is invoked) +during execution of the signal handler. +In addition, the signal which triggered the handler +will be blocked, unless the +.B SA_NODEFER +flag is used. +.PP +.I sa_flags +specifies a set of flags which modify the behavior of the signal. +It is formed by the bitwise OR of zero or more of the following: +.RS 4 +.TP +.B SA_NOCLDSTOP +If +.I signum +is +.BR SIGCHLD , +do not receive notification when child processes stop (i.e., when they +receive one of +.BR SIGSTOP ", " SIGTSTP ", " SIGTTIN ", " +or +.BR SIGTTOU ) +or resume (i.e., they receive +.BR SIGCONT ) +(see +.BR wait (2)). +This flag is meaningful only when establishing a handler for +.BR SIGCHLD . +.TP +.BR SA_NOCLDWAIT " (since Linux 2.6)" +.\" To be precise: Linux 2.5.60 -- MTK +If +.I signum +is +.BR SIGCHLD , +do not transform children into zombies when they terminate. +See also +.BR waitpid (2). +This flag is meaningful only when establishing a handler for +.BR SIGCHLD , +or when setting that signal's disposition to +.BR SIG_DFL . +.IP +If the +.B SA_NOCLDWAIT +flag is set when establishing a handler for +.BR SIGCHLD , +POSIX.1 leaves it unspecified whether a +.B SIGCHLD +signal is generated when a child process terminates. +On Linux, a +.B SIGCHLD +signal is generated in this case; +on some other implementations, it is not. +.TP +.B SA_NODEFER +Do not prevent the signal from being received from within its own signal +handler. +This flag is meaningful only when establishing a signal handler. +.B SA_NOMASK +is an obsolete, nonstandard synonym for this flag. +.TP +.B SA_ONSTACK +Call the signal handler on an alternate signal stack provided by +.BR sigaltstack (2). +If an alternate stack is not available, the default stack will be used. +This flag is meaningful only when establishing a signal handler. +.TP +.BR SA_RESETHAND +Restore the signal action to the default upon entry to the signal handler. +This flag is meaningful only when establishing a signal handler. +.B SA_ONESHOT +is an obsolete, nonstandard synonym for this flag. +.TP +.B SA_RESTART +Provide behavior compatible with BSD signal semantics by making certain +system calls restartable across signals. +This flag is meaningful only when establishing a signal handler. +See +.BR signal (7) +for a discussion of system call restarting. +.TP +.BR SA_RESTORER +.IR "Not intended for application use" . +This flag is used by C libraries to indicate that the +.IR sa_restorer +field contains the address of a "signal trampoline". +See +.BR sigreturn (2) +for more details. +.TP +.BR SA_SIGINFO " (since Linux 2.2)" +The signal handler takes three arguments, not one. +In this case, +.I sa_sigaction +should be set instead of +.IR sa_handler . +This flag is meaningful only when establishing a signal handler. +.\" (The +.\" .I sa_sigaction +.\" field was added in Linux 2.1.86.) +.RE +.SS The siginfo_t argument to a SA_SIGINFO handler +When the +.B SA_SIGINFO +flag is specified in +.IR act.sa_flags , +the signal handler address is passed via the +.IR act.sa_sigaction +field. +This handler takes three arguments, as follows: +.PP +.in +4n +.EX +void +handler(int sig, siginfo_t *info, void *ucontext) +{ + ... +} +.EE +.in +.PP +These three arguments are as follows +.TP +.I sig +The number of the signal that caused invocation of the handler. +.TP +.I info +A pointer to a +.IR siginfo_t , +which is a structure containing further information about the signal, +as described below. +.TP +.I ucontext +This is a pointer to a +.I ucontext_t +structure, cast to \fIvoid\ *\fP. +The structure pointed to by this field contains +signal context information that was saved +on the user-space stack by the kernel; for details, see +.BR sigreturn (2). +Further information about the +.IR ucontext_t +structure can be found in +.BR getcontext (3). +Commonly, the handler function doesn't make any use of the third argument. +.PP +The +.I siginfo_t +data type is a structure with the following fields: +.PP +.in +4n +.EX +siginfo_t { + int si_signo; /* Signal number */ + int si_errno; /* An errno value */ + int si_code; /* Signal code */ + int si_trapno; /* Trap number that caused + hardware-generated signal + (unused on most architectures) */ +.\" FIXME +.\" The siginfo_t 'si_trapno' field seems to be used +.\" only on SPARC and Alpha; this page could use +.\" a little more detail on its purpose there. + pid_t si_pid; /* Sending process ID */ + uid_t si_uid; /* Real user ID of sending process */ + int si_status; /* Exit value or signal */ + clock_t si_utime; /* User time consumed */ + clock_t si_stime; /* System time consumed */ + sigval_t si_value; /* Signal value */ + int si_int; /* POSIX.1b signal */ + void *si_ptr; /* POSIX.1b signal */ + int si_overrun; /* Timer overrun count; + POSIX.1b timers */ + int si_timerid; /* Timer ID; POSIX.1b timers */ +.\" In the kernel: si_tid + void *si_addr; /* Memory location which caused fault */ + long si_band; /* Band event (was \fIint\fP in + glibc 2.3.2 and earlier) */ + int si_fd; /* File descriptor */ + short si_addr_lsb; /* Least significant bit of address + (since Linux 2.6.32) */ + void *si_lower; /* Lower bound when address violation + occurred (since Linux 3.19) */ + void *si_upper; /* Upper bound when address violation + occurred (since Linux 3.19) */ + int si_pkey; /* Protection key on PTE that caused + fault (since Linux 4.6) */ + void *si_call_addr; /* Address of system call instruction + (since Linux 3.5) */ + int si_syscall; /* Number of attempted system call + (since Linux 3.5) */ + unsigned int si_arch; /* Architecture of attempted system call + (since Linux 3.5) */ +} +.EE +.in +.PP +.IR si_signo ", " si_errno " and " si_code +are defined for all signals. +.RI ( si_errno +is generally unused on Linux.) +The rest of the struct may be a union, so that one should +read only the fields that are meaningful for the given signal: +.IP * 2 +Signals sent with +.BR kill (2) +and +.BR sigqueue (3) +fill in +.IR si_pid " and " si_uid . +In addition, signals sent with +.BR sigqueue (3) +fill in +.IR si_int " and " si_ptr +with the values specified by the sender of the signal; +see +.BR sigqueue (3) +for more details. +.IP * +Signals sent by POSIX.1b timers (since Linux 2.6) fill in +.I si_overrun +and +.IR si_timerid . +The +.I si_timerid +field is an internal ID used by the kernel to identify +the timer; it is not the same as the timer ID returned by +.BR timer_create (2). +The +.I si_overrun +field is the timer overrun count; +this is the same information as is obtained by a call to +.BR timer_getoverrun (2). +These fields are nonstandard Linux extensions. +.IP * +Signals sent for message queue notification (see the description of +.B SIGEV_SIGNAL +in +.BR mq_notify (3)) +fill in +.IR si_int / si_ptr , +with the +.I sigev_value +supplied to +.BR mq_notify (3); +.IR si_pid , +with the process ID of the message sender; and +.IR si_uid , +with the real user ID of the message sender. +.IP * +.B SIGCHLD +fills in +.IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime , +providing information about the child. +The +.I si_pid +field is the process ID of the child; +.I si_uid +is the child's real user ID. +The +.I si_status +field contains the exit status of the child (if +.I si_code +is +.BR CLD_EXITED ), +or the signal number that caused the process to change state. +The +.I si_utime +and +.I si_stime +contain the user and system CPU time used by the child process; +these fields do not include the times used by waited-for children (unlike +.BR getrusage (2) +and +.BR times (2)). +In kernels up to 2.6, and since 2.6.27, these fields report +CPU time in units of +.IR sysconf(_SC_CLK_TCK) . +In 2.6 kernels before 2.6.27, +a bug meant that these fields reported time in units +of the (configurable) system jiffy (see +.BR time (7)). +.\" FIXME . +.\" When si_utime and si_stime where originally implemented, the +.\" measurement unit was HZ, which was the same as clock ticks +.\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and +.\" was *still* used as the unit to return the info these fields, +.\" with the result that the field values depended on the +.\" configured HZ. Of course, the should have been measured in +.\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to +.\" convert to seconds. I have a queued patch to fix this: +.\" http://thread.gmane.org/gmane.linux.kernel/698061/ . +.\" This patch made it into 2.6.27. +.\" But note that these fields still don't return the times of +.\" waited-for children (as is done by getrusage() and times() +.\" and wait4()). Solaris 8 does include child times. +.IP * +.BR SIGILL , +.BR SIGFPE , +.BR SIGSEGV , +.BR SIGBUS , +and +.BR SIGTRAP +fill in +.I si_addr +with the address of the fault. +On some architectures, +these signals also fill in the +.I si_trapno +field. +.IP +Some suberrors of +.BR SIGBUS , +in particular +.B BUS_MCEERR_AO +and +.BR BUS_MCEERR_AR , +also fill in +.IR si_addr_lsb . +This field indicates the least significant bit of the reported address +and therefore the extent of the corruption. +For example, if a full page was corrupted, +.I si_addr_lsb +contains +.IR log2(sysconf(_SC_PAGESIZE)) . +When +.BR SIGTRAP +is delivered in response to a +.BR ptrace (2) +event (PTRACE_EVENT_foo), +.I si_addr +is not populated, but +.I si_pid +and +.I si_uid +are populated with the respective process ID and user ID responsible for +delivering the trap. +In the case of +.BR seccomp (2), +the tracee will be shown as delivering the event. +.B BUS_MCEERR_* +and +.I si_addr_lsb +are Linux-specific extensions. +.IP +The +.BR SEGV_BNDERR +suberror of +.B SIGSEGV +populates +.IR si_lower +and +.IR si_upper . +.IP +The +.BR SEGV_PKUERR +suberror of +.B SIGSEGV +populates +.IR si_pkey . +.IP * +.BR SIGIO / SIGPOLL +(the two names are synonyms on Linux) +fills in +.IR si_band " and " si_fd . +The +.I si_band +event is a bit mask containing the same values as are filled in the +.I revents +field by +.BR poll (2). +The +.I si_fd +field indicates the file descriptor for which the I/O event occurred; +for further details, see the description of +.BR F_SETSIG +in +.BR fcntl (2). +.IP * +.BR SIGSYS , +generated (since Linux 3.5) +.\" commit a0727e8ce513fe6890416da960181ceb10fbfae6 +when a seccomp filter returns +.BR SECCOMP_RET_TRAP , +fills in +.IR si_call_addr , +.IR si_syscall , +.IR si_arch , +.IR si_errno , +and other fields as described in +.BR seccomp (2). +.\" +.SS +The si_code field +The +.I si_code +field inside the +.I siginfo_t +argument that is passed to a +.B SA_SIGINFO +signal handler is a value (not a bit mask) +indicating why this signal was sent. +For a +.BR ptrace (2) +event, +.I si_code +will contain +.BR SIGTRAP +and have the ptrace event in the high byte: +.PP +.in +4n +.EX +(SIGTRAP | PTRACE_EVENT_foo << 8). +.EE +.in +.PP +For a +.RB non- ptrace (2) +event, the values that can appear in +.I si_code +are described in the remainder of this section. +Since glibc 2.20, +the definitions of most of these symbols are obtained from +.I +by defining feature test macros (before including +.I any +header file) as follows: +.IP * 3 +.B _XOPEN_SOURCE +with the value 500 or greater; +.IP * +.B _XOPEN_SOURCE +and +.BR _XOPEN_SOURCE_EXTENDED ; +or +.IP * +.B _POSIX_C_SOURCE +with the value 200809L or greater. +.PP +For the +.B TRAP_* +constants, the symbol definitions are provided only in the first two cases. +Before glibc 2.20, no feature test macros were required to obtain these symbols. +.PP +For a regular signal, the following list shows the values which can be +placed in +.I si_code +for any signal, along with the reason that the signal was generated. +.RS 4 +.TP +.B SI_USER +.BR kill (2). +.TP +.B SI_KERNEL +Sent by the kernel. +.TP +.B SI_QUEUE +.BR sigqueue (3). +.TP +.B SI_TIMER +POSIX timer expired. +.TP +.BR SI_MESGQ " (since Linux 2.6.6)" +POSIX message queue state changed; see +.BR mq_notify (3). +.TP +.B SI_ASYNCIO +AIO completed. +.TP +.B SI_SIGIO +Queued +.B SIGIO +(only in kernels up to Linux 2.2; from Linux 2.4 onward +.BR SIGIO / SIGPOLL +fills in +.I si_code +as described below). +.TP +.BR SI_TKILL " (since Linux 2.4.19)" +.BR tkill (2) +or +.BR tgkill (2). +.\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented +.\" It appears to have been an idea that was tried during 2.5.6 +.\" through to 2.5.24 and then was backed out. +.RE +.PP +The following values can be placed in +.I si_code +for a +.B SIGILL +signal: +.RS 4 +.TP +.B ILL_ILLOPC +Illegal opcode. +.TP +.B ILL_ILLOPN +Illegal operand. +.TP +.B ILL_ILLADR +Illegal addressing mode. +.TP +.B ILL_ILLTRP +Illegal trap. +.TP +.B ILL_PRVOPC +Privileged opcode. +.TP +.B ILL_PRVREG +Privileged register. +.TP +.B ILL_COPROC +Coprocessor error. +.TP +.B ILL_BADSTK +Internal stack error. +.RE +.PP +The following values can be placed in +.I si_code +for a +.B SIGFPE +signal: +.RS 4 +.TP +.B FPE_INTDIV +Integer divide by zero. +.TP +.B FPE_INTOVF +Integer overflow. +.TP +.B FPE_FLTDIV +Floating-point divide by zero. +.TP +.B FPE_FLTOVF +Floating-point overflow. +.TP +.B FPE_FLTUND +Floating-point underflow. +.TP +.B FPE_FLTRES +Floating-point inexact result. +.TP +.B FPE_FLTINV +Floating-point invalid operation. +.TP +.B FPE_FLTSUB +Subscript out of range. +.RE +.PP +The following values can be placed in +.I si_code +for a +.B SIGSEGV +signal: +.RS 4 +.TP +.B SEGV_MAPERR +Address not mapped to object. +.TP +.B SEGV_ACCERR +Invalid permissions for mapped object. +.TP +.BR SEGV_BNDERR " (since Linux 3.19)" +.\" commit ee1b58d36aa1b5a79eaba11f5c3633c88231da83 +Failed address bound checks. +.TP +.BR SEGV_PKUERR " (since Linux 4.6)" +.\" commit cd0ea35ff5511cde299a61c21a95889b4a71464e +Access was denied by memory protection keys. +See +.BR pkeys (7). +The protection key which applied to this access is available via +.IR si_pkey . +.RE +.PP +The following values can be placed in +.I si_code +for a +.B SIGBUS +signal: +.RS 4 +.TP +.B BUS_ADRALN +Invalid address alignment. +.TP +.B BUS_ADRERR +Nonexistent physical address. +.TP +.B BUS_OBJERR +Object-specific hardware error. +.TP +.BR BUS_MCEERR_AR " (since Linux 2.6.32)" +Hardware memory error consumed on a machine check; action required. +.TP +.BR BUS_MCEERR_AO " (since Linux 2.6.32)" +Hardware memory error detected in process but not consumed; action optional. +.RE +.PP +The following values can be placed in +.I si_code +for a +.B SIGTRAP +signal: +.RS 4 +.TP +.B TRAP_BRKPT +Process breakpoint. +.TP +.B TRAP_TRACE +Process trace trap. +.TP +.BR TRAP_BRANCH " (since Linux 2.4, IA64 only))" +Process taken branch trap. +.TP +.BR TRAP_HWBKPT " (since Linux 2.4, IA64 only))" +Hardware breakpoint/watchpoint. +.RE +.PP +The following values can be placed in +.I si_code +for a +.B SIGCHLD +signal: +.RS 4 +.TP +.B CLD_EXITED +Child has exited. +.TP +.B CLD_KILLED +Child was killed. +.TP +.B CLD_DUMPED +Child terminated abnormally. +.TP +.B CLD_TRAPPED +Traced child has trapped. +.TP +.B CLD_STOPPED +Child has stopped. +.TP +.BR CLD_CONTINUED " (since Linux 2.6.9)" +Stopped child has continued. +.RE +.PP +The following values can be placed in +.I si_code +for a +.BR SIGIO / SIGPOLL +signal: +.RS 4 +.TP +.B POLL_IN +Data input available. +.TP +.B POLL_OUT +Output buffers available. +.TP +.B POLL_MSG +Input message available. +.TP +.B POLL_ERR +I/O error. +.TP +.B POLL_PRI +High priority input available. +.TP +.B POLL_HUP +Device disconnected. +.RE +.PP +The following value can be placed in +.I si_code +for a +.BR SIGSYS +signal: +.RS 4 +.TP +.BR SYS_SECCOMP " (since Linux 3.5)" +Triggered by a +.BR seccomp (2) +filter rule. +.RE +.SH RETURN VALUE +.BR sigaction () +returns 0 on success; on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.IR act " or " oldact +points to memory which is not a valid part of the process address space. +.TP +.B EINVAL +An invalid signal was specified. +This will also be generated if an attempt +is made to change the action for +.BR SIGKILL " or " SIGSTOP ", " +which cannot be caught or ignored. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.\" SVr4 does not document the EINTR condition. +.SH NOTES +A child created via +.BR fork (2) +inherits a copy of its parent's signal dispositions. +During an +.BR execve (2), +the dispositions of handled signals are reset to the default; +the dispositions of ignored signals are left unchanged. +.PP +According to POSIX, the behavior of a process is undefined after it +ignores a +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +signal that was not generated by +.BR kill (2) +or +.BR raise (3). +Integer division by zero has undefined result. +On some architectures it will generate a +.B SIGFPE +signal. +(Also dividing the most negative integer by \-1 may generate +.BR SIGFPE .) +Ignoring this signal might lead to an endless loop. +.PP +POSIX.1-1990 disallowed setting the action for +.B SIGCHLD +to +.BR SIG_IGN . +POSIX.1-2001 and later allow this possibility, so that ignoring +.B SIGCHLD +can be used to prevent the creation of zombies (see +.BR wait (2)). +Nevertheless, the historical BSD and System\ V behaviors for ignoring +.B SIGCHLD +differ, so that the only completely portable method of ensuring that +terminated children do not become zombies is to catch the +.B SIGCHLD +signal and perform a +.BR wait (2) +or similar. +.PP +POSIX.1-1990 specified only +.BR SA_NOCLDSTOP . +POSIX.1-2001 added +.BR SA_NOCLDSTOP , +.BR SA_NOCLDWAIT , +.BR SA_NODEFER , +.BR SA_ONSTACK , +.BR SA_RESETHAND , +.BR SA_RESTART , +and +.BR SA_SIGINFO . +Use of these latter values in +.I sa_flags +may be less portable in applications intended for older +UNIX implementations. +.PP +The +.B SA_RESETHAND +flag is compatible with the SVr4 flag of the same name. +.PP +The +.B SA_NODEFER +flag is compatible with the SVr4 flag of the same name under kernels +1.3.9 and newer. +On older kernels the Linux implementation +allowed the receipt of any signal, not just the one we are installing +(effectively overriding any +.I sa_mask +settings). +.PP +.BR sigaction () +can be called with a NULL second argument to query the current signal +handler. +It can also be used to check whether a given signal is valid for +the current machine by calling it with NULL second and third arguments. +.PP +It is not possible to block +.BR SIGKILL " or " SIGSTOP +(by specifying them in +.IR sa_mask ). +Attempts to do so are silently ignored. +.PP +See +.BR sigsetops (3) +for details on manipulating signal sets. +.PP +See +.BR signal-safety (7) +for a list of the async-signal-safe functions that can be +safely called inside from inside a signal handler. +.\" +.SS C library/kernel differences +The glibc wrapper function for +.BR sigaction () +gives an error +.RB ( EINVAL ) +on attempts to change the disposition of the two real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.PP +On architectures where the signal trampoline resides in the C library, +the glibc wrapper function for +.BR sigaction () +places the address of the trampoline code in the +.I act.sa_restorer +field and sets the +.B SA_RESTORER +flag in the +.IR act.sa_flags +field. +See +.BR sigreturn (2). +.PP +The original Linux system call was named +.BR sigaction (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.IR sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigaction (), +was added to support an enlarged +.IR sigset_t +type. +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal sets in +.IR act.sa_mask +and +.IR oldact.sa_mask . +This argument is currently required to have the value +.IR sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigaction () +wrapper function hides these details from us, transparently calling +.BR rt_sigaction () +when the kernel provides it. +.\" +.SS Undocumented +Before the introduction of +.BR SA_SIGINFO , +it was also possible to get some additional information, +namely by using a +.I sa_handler +with a second argument of type +.IR "struct sigcontext". +See the relevant Linux kernel sources for details. +This use is obsolete now. +.SH BUGS +In kernels up to and including 2.6.13, specifying +.B SA_NODEFER +in +.I sa_flags +prevents not only the delivered signal from being masked during +execution of the handler, but also the signals specified in +.IR sa_mask . +This bug was fixed in kernel 2.6.14. +.SH EXAMPLE +See +.BR mprotect (2). +.SH SEE ALSO +.BR kill (1), +.BR kill (2), +.BR pause (2), +.BR restart_syscall (2), +.BR seccomp (2) +.BR sigaltstack (2), +.BR signal (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigreturn (2), +.BR sigsuspend (2), +.BR wait (2), +.BR killpg (3), +.BR raise (3), +.BR siginterrupt (3), +.BR sigqueue (3), +.BR sigsetops (3), +.BR sigvec (3), +.BR core (5), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 new file mode 100644 index 0000000..b332694 --- /dev/null +++ b/man2/sigaltstack.2 @@ -0,0 +1,378 @@ +'\" t +.\" Copyright (c) 2001, 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" aeb, various minor fixes +.TH SIGALTSTACK 2 2017-11-08 "Linux" "Linux Programmer's Manual" +.SH NAME +sigaltstack \- set and/or get signal stack context +.SH SYNOPSIS +.B #include +.PP +.BI "int sigaltstack(const stack_t *" ss ", stack_t *" old_ss ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR sigaltstack (): +.ad l +.RS 4 +.PD 0 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.PD +.RE +.ad +.SH DESCRIPTION +.BR sigaltstack () +allows a process to define a new alternate +signal stack and/or retrieve the state of an existing +alternate signal stack. +An alternate signal stack is used during the +execution of a signal handler if the establishment of that handler (see +.BR sigaction (2)) +requested it. +.PP +The normal sequence of events for using an alternate signal stack +is the following: +.TP 3 +1. +Allocate an area of memory to be used for the alternate +signal stack. +.TP +2. +Use +.BR sigaltstack () +to inform the system of the existence and +location of the alternate signal stack. +.TP +3. +When establishing a signal handler using +.BR sigaction (2), +inform the system that the signal handler should be executed +on the alternate signal stack by +specifying the \fBSA_ONSTACK\fP flag. +.PP +The \fIss\fP argument is used to specify a new +alternate signal stack, while the \fIold_ss\fP argument +is used to retrieve information about the currently +established signal stack. +If we are interested in performing just one +of these tasks, then the other argument can be specified as NULL. +.PP +The +.I stack_t +type used to type the arguments of this function is defined as follows: +.PP +.in +4n +.EX +typedef struct { + void *ss_sp; /* Base address of stack */ + int ss_flags; /* Flags */ + size_t ss_size; /* Number of bytes in stack */ +} stack_t; +.EE +.in +.PP +To establish a new alternate signal stack, +the fields of this structure are set as follows: +.TP +.I ss.ss_flags +This field contains either 0, or the following flag: +.RS +.TP +.BR SS_AUTODISARM " (since Linux 4.7)" +.\" commit 2a74213838104a41588d86fd5e8d344972891ace +.\" See tools/testing/selftests/sigaltstack/sas.c in kernel sources +Clear the alternate signal stack settings on entry to the signal handler. +When the signal handler returns, +the previous alternate signal stack settings are restored. +.IP +This flag was added in order make it safe +to switch away from the signal handler with +.BR swapcontext (3). +Without this flag, a subsequently handled signal will corrupt +the state of the switched-away signal handler. +On kernels where this flag is not supported, +.BR sigaltstack () +fails with the error +.BR EINVAL +when this flag is supplied. +.RE +.TP +.I ss.ss_sp +This field specifies the starting address of the stack. +When a signal handler is invoked on the alternate stack, +the kernel automatically aligns the address given in \fIss.ss_sp\fP +to a suitable address boundary for the underlying hardware architecture. +.TP +.I ss.ss_size +This field specifies the size of the stack. +The constant \fBSIGSTKSZ\fP is defined to be large enough +to cover the usual size requirements for an alternate signal stack, +and the constant \fBMINSIGSTKSZ\fP defines the minimum +size required to execute a signal handler. +.PP +To disable an existing stack, specify \fIss.ss_flags\fP +as \fBSS_DISABLE\fP. +In this case, the kernel ignores any other flags in +.IR ss.ss_flags +and the remaining fields +in \fIss\fP. +.PP +If \fIold_ss\fP is not NULL, then it is used to return information about +the alternate signal stack which was in effect prior to the +call to +.BR sigaltstack (). +The \fIold_ss.ss_sp\fP and \fIold_ss.ss_size\fP fields return the starting +address and size of that stack. +The \fIold_ss.ss_flags\fP may return either of the following values: +.TP +.B SS_ONSTACK +The process is currently executing on the alternate signal stack. +(Note that it is not possible +to change the alternate signal stack if the process is +currently executing on it.) +.TP +.B SS_DISABLE +The alternate signal stack is currently disabled. +.IP +Alternatively, this value is returned if the process is currently +executing on an alternate signal stack that was established using the +.B SS_AUTODISARM +flag. +In this case, it is safe to switch away from the signal handler with +.BR swapcontext (3). +It is also possible to set up a different alternative signal stack +using a further call to +.BR sigaltstack (). +.\" FIXME Was it intended that one can set up a different alternative +.\" signal stack in this scenario? (In passing, if one does this, the +.\" sigaltstack(NULL, &old_ss) now returns old_ss.ss_flags==SS_AUTODISARM +.\" rather than old_ss.ss_flags==SS_DISABLE. The API design here seems +.\" confusing... +.TP +.B SS_AUTODISARM +The alternate signal stack has been marked to be autodisarmed +as described above. +.PP +By specifying +.I ss +as NULL, and +.I old_ss +as a non-NULL value, one can obtain the current settings for +the alternate signal stack without changing them. +.SH RETURN VALUE +.BR sigaltstack () +returns 0 on success, or \-1 on failure with +\fIerrno\fP set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Either \fIss\fP or \fIold_ss\fP is not NULL and points to an area +outside of the process's address space. +.TP +.B EINVAL +\fIss\fP is not NULL and the \fIss_flags\fP field contains +an invalid flag. +.TP +.B ENOMEM +The specified size of the new alternate signal stack +.I ss.ss_size +was less than +.BR MINSTKSZ . +.TP +.B EPERM +An attempt was made to change the alternate signal stack while +it was active (i.e., the process was already executing +on the current alternate signal stack). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sigaltstack () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SUSv2, SVr4. +.PP +The +.B SS_AUTODISARM +flag is a Linux extension. +.SH NOTES +The most common usage of an alternate signal stack is to handle the +.B SIGSEGV +signal that is generated if the space available for the +normal process stack is exhausted: in this case, a signal handler for +.B SIGSEGV +cannot be invoked on the process stack; if we wish to handle it, +we must use an alternate signal stack. +.PP +Establishing an alternate signal stack is useful if a process +expects that it may exhaust its standard stack. +This may occur, for example, because the stack grows so large +that it encounters the upwardly growing heap, or it reaches a +limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP. +If the standard stack is exhausted, the kernel sends +the process a \fBSIGSEGV\fP signal. +In these circumstances the only way to catch this signal is +on an alternate signal stack. +.PP +On most hardware architectures supported by Linux, stacks grow +downward. +.BR sigaltstack () +automatically takes account +of the direction of stack growth. +.PP +Functions called from a signal handler executing on an alternate +signal stack will also use the alternate signal stack. +(This also applies to any handlers invoked for other signals while +the process is executing on the alternate signal stack.) +Unlike the standard stack, the system does not +automatically extend the alternate signal stack. +Exceeding the allocated size of the alternate signal stack will +lead to unpredictable results. +.PP +A successful call to +.BR execve (2) +removes any existing alternate +signal stack. +A child process created via +.BR fork (2) +inherits a copy of its parent's alternate signal stack settings. +.PP +.BR sigaltstack () +supersedes the older +.BR sigstack () +call. +For backward compatibility, glibc also provides +.BR sigstack (). +All new applications should be written using +.BR sigaltstack (). +.SS History +4.2BSD had a +.BR sigstack () +system call. +It used a slightly +different struct, and had the major disadvantage that the caller +had to know the direction of stack growth. +.SH EXAMPLE +The following code segment demonstrates the use of +.BR sigaltstack () +(and +.BR sigaction (2)) +to install an alternate signal stack that is employed by a handler +for the +.BR SIGSEGV +signal: +.PP +.in +4n +.EX +stack_t ss; + +ss.ss_sp = malloc(SIGSTKSZ); +if (ss.ss_sp == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); +} + +ss.ss_size = SIGSTKSZ; +ss.ss_flags = 0; +if (sigaltstack(&ss, NULL) == \-1) { + perror("sigaltstack"); + exit(EXIT_FAILURE); +} + +sa.sa_flags = SA_ONSTACK; +sa.sa_handler = handler(); /* Address of a signal handler */ +sigemptyset(&sa.sa_mask); +if (sigaction(SIGSEGV, &sa, NULL) == -1) { + perror("sigaction"); + exit(EXIT_FAILURE); +} +.EE +.in +.SH BUGS +In Linux 2.2 and earlier, the only flag that could be specified +in +.I ss.sa_flags +was +.BR SS_DISABLE . +In the lead up to the release of the Linux 2.4 kernel, +.\" Linux 2.3.40 +.\" After quite a bit of web and mail archive searching, +.\" I could not find the patch on any mailing list, and I +.\" could find no place where the rationale for this change +.\" explained -- mtk +a change was made to allow +.BR sigaltstack () +to allow +.I ss.ss_flags==SS_ONSTACK +with the same meaning as +.IR "ss.ss_flags==0" +(i.e., the inclusion of +.B SS_ONSTACK +in +.I ss.ss_flags +is a no-op). +On other implementations, and according to POSIX.1, +.B SS_ONSTACK +appears only as a reported flag in +.IR old_ss.ss_flags . +On Linux, there is no need ever to specify +.B SS_ONSTACK +in +.IR ss.ss_flags , +and indeed doing so should be avoided on portability grounds: +various other systems +.\" See the source code of Illumos and FreeBSD, for example. +give an error if +.B SS_ONSTACK +is specified in +.IR ss.ss_flags . +.SH SEE ALSO +.BR execve (2), +.BR setrlimit (2), +.BR sigaction (2), +.BR siglongjmp (3), +.BR sigsetjmp (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/signal.2 b/man2/signal.2 new file mode 100644 index 0000000..62f55c9 --- /dev/null +++ b/man2/signal.2 @@ -0,0 +1,297 @@ +.\" Copyright (c) 2000 Andries Brouwer +.\" and Copyright (c) 2007 Michael Kerrisk +.\" and Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" based on work by Rik Faith +.\" and Mike Battersby . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 2004-11-19, mtk: +.\" added pointer to sigaction.2 for details of ignoring SIGCHLD +.\" 2007-06-03, mtk: strengthened portability warning, and rewrote +.\" various sections. +.\" 2008-07-11, mtk: rewrote and expanded portability discussion. +.\" +.TH SIGNAL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +signal \- ANSI C signal handling +.SH SYNOPSIS +.B #include +.PP +.B typedef void (*sighandler_t)(int); +.PP +.BI "sighandler_t signal(int " signum ", sighandler_t " handler ); +.SH DESCRIPTION +The behavior of +.BR signal () +varies across UNIX versions, +and has also varied historically across different versions of Linux. +\fBAvoid its use\fP: use +.BR sigaction (2) +instead. +See \fIPortability\fP below. +.PP +.BR signal () +sets the disposition of the signal +.I signum +to +.IR handler , +which is either +.BR SIG_IGN , +.BR SIG_DFL , +or the address of a programmer-defined function (a "signal handler"). +.PP +If the signal +.I signum +is delivered to the process, then one of the following happens: +.TP 3 +* +If the disposition is set to +.BR SIG_IGN , +then the signal is ignored. +.TP +* +If the disposition is set to +.BR SIG_DFL , +then the default action associated with the signal (see +.BR signal (7)) +occurs. +.TP +* +If the disposition is set to a function, +then first either the disposition is reset to +.BR SIG_DFL , +or the signal is blocked (see \fIPortability\fP below), and then +.I handler +is called with argument +.IR signum . +If invocation of the handler caused the signal to be blocked, +then the signal is unblocked upon return from the handler. +.PP +The signals +.B SIGKILL +and +.B SIGSTOP +cannot be caught or ignored. +.SH RETURN VALUE +.BR signal () +returns the previous value of the signal handler, or +.B SIG_ERR +on error. +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +.TP +.B EINVAL +.I signum +is invalid. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.SH NOTES +The effects of +.BR signal () +in a multithreaded process are unspecified. +.PP +According to POSIX, the behavior of a process is undefined after it +ignores a +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +signal that was not generated by +.BR kill (2) +or +.BR raise (3). +Integer division by zero has undefined result. +On some architectures it will generate a +.B SIGFPE +signal. +(Also dividing the most negative integer by \-1 may generate +.BR SIGFPE .) +Ignoring this signal might lead to an endless loop. +.PP +See +.BR sigaction (2) +for details on what happens when the disposition +.B SIGCHLD +is set to +.BR SIG_IGN . +.PP +See +.BR signal-safety (7) +for a list of the async-signal-safe functions that can be +safely called from inside a signal handler. +.PP +The use of +.I sighandler_t +is a GNU extension, exposed if +.B _GNU_SOURCE +is defined; +.\" libc4 and libc5 define +.\" .IR SignalHandler ; +glibc also defines (the BSD-derived) +.I sig_t +if +.B _BSD_SOURCE +(glibc 2.19 and earlier) +or +.BR _DEFAULT_SOURCE +(glibc 2.19 and later) +is defined. +Without use of such a type, the declaration of +.BR signal () +is the somewhat harder to read: +.PP +.in +4n +.EX +.BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);" +.EE +.in +.SS Portability +The only portable use of +.BR signal () +is to set a signal's disposition to +.BR SIG_DFL +or +.BR SIG_IGN . +The semantics when using +.BR signal () +to establish a signal handler vary across systems +(and POSIX.1 explicitly permits this variation); +.B do not use it for this purpose. +.PP +POSIX.1 solved the portability mess by specifying +.BR sigaction (2), +which provides explicit control of the semantics when a +signal handler is invoked; use that interface instead of +.BR signal (). +.PP +In the original UNIX systems, when a handler that was established using +.BR signal () +was invoked by the delivery of a signal, +the disposition of the signal would be reset to +.BR SIG_DFL , +and the system did not block delivery of further instances of the signal. +This is equivalent to calling +.BR sigaction (2) +with the following flags: +.PP +.EX + sa.sa_flags = SA_RESETHAND | SA_NODEFER; +.EE +.PP +System\ V also provides these semantics for +.BR signal (). +This was bad because the signal might be delivered again +before the handler had a chance to reestablish itself. +Furthermore, rapid deliveries of the same signal could +result in recursive invocations of the handler. +.PP +BSD improved on this situation, but unfortunately also +changed the semantics of the existing +.BR signal () +interface while doing so. +On BSD, when a signal handler is invoked, +the signal disposition is not reset, +and further instances of the signal are blocked from +being delivered while the handler is executing. +Furthermore, certain blocking system calls are automatically +restarted if interrupted by a signal handler (see +.BR signal (7)). +The BSD semantics are equivalent to calling +.BR sigaction (2) +with the following flags: +.PP +.EX + sa.sa_flags = SA_RESTART; +.EE +.PP +The situation on Linux is as follows: +.IP * 2 +The kernel's +.BR signal () +system call provides System\ V semantics. +.IP * +By default, in glibc 2 and later, the +.BR signal () +wrapper function does not invoke the kernel system call. +Instead, it calls +.BR sigaction (2) +using flags that supply BSD semantics. +This default behavior is provided as long as a suitable +feature test macro is defined: +.B _BSD_SOURCE +on glibc 2.19 and earlier or +.BR _DEFAULT_SOURCE +in glibc 2.19 and later. +(By default, these macros are defined; see +.BR feature_test_macros (7) +for details.) +If such a feature test macro is not defined, then +.BR signal () +provides System\ V semantics. +.\" +.\" System V semantics are also provided if one uses the separate +.\" .BR sysv_signal (3) +.\" function. +.\" .IP * +.\" The +.\" .BR signal () +.\" function in Linux libc4 and libc5 provide System\ V semantics. +.\" If one on a libc5 system includes +.\" .I +.\" instead of +.\" .IR , +.\" then +.\" .BR signal () +.\" provides BSD semantics. +.SH SEE ALSO +.BR kill (1), +.BR alarm (2), +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR bsd_signal (3), +.BR killpg (3), +.BR raise (3), +.BR siginterrupt (3), +.BR sigqueue (3), +.BR sigsetops (3), +.BR sigvec (3), +.BR sysv_signal (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/signalfd.2 b/man2/signalfd.2 new file mode 100644 index 0000000..90e81ef --- /dev/null +++ b/man2/signalfd.2 @@ -0,0 +1,512 @@ +.\" Copyright (C) 2008 Michael Kerrisk +.\" starting from a version by Davide Libenzi +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH SIGNALFD 2 2017-05-03 Linux "Linux Programmer's Manual" +.SH NAME +signalfd \- create a file descriptor for accepting signals +.SH SYNOPSIS +.B #include +.PP +.BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags ); +.SH DESCRIPTION +.BR signalfd () +creates a file descriptor that can be used to accept signals +targeted at the caller. +This provides an alternative to the use of a signal handler or +.BR sigwaitinfo (2), +and has the advantage that the file descriptor may be monitored by +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +.PP +The +.I mask +argument specifies the set of signals that the caller +wishes to accept via the file descriptor. +This argument is a signal set whose contents can be initialized +using the macros described in +.BR sigsetops (3). +Normally, the set of signals to be received via the +file descriptor should be blocked using +.BR sigprocmask (2), +to prevent the signals being handled according to their default +dispositions. +It is not possible to receive +.B SIGKILL +or +.B SIGSTOP +signals via a signalfd file descriptor; +these signals are silently ignored if specified in +.IR mask . +.PP +If the +.I fd +argument is \-1, +then the call creates a new file descriptor and associates the +signal set specified in +.I mask +with that file descriptor. +If +.I fd +is not \-1, +then it must specify a valid existing signalfd file descriptor, and +.I mask +is used to replace the signal set associated with that file descriptor. +.PP +Starting with Linux 2.6.27, the following values may be bitwise ORed in +.IR flags +to change the behavior of +.BR signalfd (): +.TP 14 +.B SFD_NONBLOCK +Set the +.BR O_NONBLOCK +file status flag on the new open file description. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B SFD_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.PP +In Linux up to version 2.6.26, the +.I flags +argument is unused, and must be specified as zero. +.PP +.BR signalfd () +returns a file descriptor that supports the following operations: +.TP +.BR read (2) +If one or more of the signals specified in +.I mask +is pending for the process, then the buffer supplied to +.BR read (2) +is used to return one or more +.I signalfd_siginfo +structures (see below) that describe the signals. +The +.BR read (2) +returns information for as many signals as are pending and will +fit in the supplied buffer. +The buffer must be at least +.I "sizeof(struct signalfd_siginfo)" +bytes. +The return value of the +.BR read (2) +is the total number of bytes read. +.IP +As a consequence of the +.BR read (2), +the signals are consumed, +so that they are no longer pending for the process +(i.e., will not be caught by signal handlers, +and cannot be accepted using +.BR sigwaitinfo (2)). +.IP +If none of the signals in +.I mask +is pending for the process, then the +.BR read (2) +either blocks until one of the signals in +.I mask +is generated for the process, +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking. +.TP +.BR poll "(2), " select "(2) (and similar)" +The file descriptor is readable +(the +.BR select (2) +.I readfds +argument; the +.BR poll (2) +.B POLLIN +flag) +if one or more of the signals in +.I mask +is pending for the process. +.IP +The signalfd file descriptor also supports the other file-descriptor +multiplexing APIs: +.BR pselect (2), +.BR ppoll (2), +and +.BR epoll (7). +.TP +.BR close (2) +When the file descriptor is no longer required it should be closed. +When all file descriptors associated with the same signalfd object +have been closed, the resources for object are freed by the kernel. +.SS The signalfd_siginfo structure +The format of the +.I signalfd_siginfo +structure(s) returned by +.BR read (2)s +from a signalfd file descriptor is as follows: +.PP +.in +4n +.EX +struct signalfd_siginfo { + uint32_t ssi_signo; /* Signal number */ + int32_t ssi_errno; /* Error number (unused) */ + int32_t ssi_code; /* Signal code */ + uint32_t ssi_pid; /* PID of sender */ + uint32_t ssi_uid; /* Real UID of sender */ + int32_t ssi_fd; /* File descriptor (SIGIO) */ + uint32_t ssi_tid; /* Kernel timer ID (POSIX timers) + uint32_t ssi_band; /* Band event (SIGIO) */ + uint32_t ssi_overrun; /* POSIX timer overrun count */ + uint32_t ssi_trapno; /* Trap number that caused signal */ +.\" ssi_trapno is unused on most arches + int32_t ssi_status; /* Exit status or signal (SIGCHLD) */ + int32_t ssi_int; /* Integer sent by sigqueue(3) */ + uint64_t ssi_ptr; /* Pointer sent by sigqueue(3) */ + uint64_t ssi_utime; /* User CPU time consumed (SIGCHLD) */ + uint64_t ssi_stime; /* System CPU time consumed + (SIGCHLD) */ + uint64_t ssi_addr; /* Address that generated signal + (for hardware-generated signals) */ + uint16_t ssi_addr_lsb; /* Least significant bit of address + (SIGBUS; since Linux 2.6.37) +.\" ssi_addr_lsb: commit b8aeec34175fc8fe8b0d40efea4846dfc1ba663e + uint8_t pad[\fIX\fP]; /* Pad size to 128 bytes (allow for + additional fields in the future) */ +}; +.EE +.in +.PP +Each of the fields in this structure +is analogous to the similarly named field in the +.I siginfo_t +structure. +The +.I siginfo_t +structure is described in +.BR sigaction (2). +Not all fields in the returned +.I signalfd_siginfo +structure will be valid for a specific signal; +the set of valid fields can be determined from the value returned in the +.I ssi_code +field. +This field is the analog of the +.I siginfo_t +.I si_code +field; see +.BR sigaction (2) +for details. +.SS fork(2) semantics +After a +.BR fork (2), +the child inherits a copy of the signalfd file descriptor. +A +.BR read (2) +from the file descriptor in the child will return information +about signals queued to the child. +.SS Semantics of file descriptor passing +As with other file descriptors, +signalfd file descriptors can be passed to another process +via a UNIX domain socket (see +.BR unix (7)). +In the receiving process, a +.BR read (2) +from the received file descriptor will return information +about signals queued to that process. +.SS execve(2) semantics +Just like any other file descriptor, +a signalfd file descriptor remains open across an +.BR execve (2), +unless it has been marked for close-on-exec (see +.BR fcntl (2)). +Any signals that were available for reading before the +.BR execve (2) +remain available to the newly loaded program. +(This is analogous to traditional signal semantics, +where a blocked signal that is pending remains pending across an +.BR execve (2).) +.SS Thread semantics +The semantics of signalfd file descriptors in a multithreaded program +mirror the standard semantics for signals. +In other words, +when a thread reads from a signalfd file descriptor, +it will read the signals that are directed to the thread +itself and the signals that are directed to the process +(i.e., the entire thread group). +(A thread will not be able to read signals that are directed +to other threads in the process.) +.SH RETURN VALUE +On success, +.BR signalfd () +returns a signalfd file descriptor; +this is either a new file descriptor (if +.I fd +was \-1), or +.I fd +if +.I fd +was a valid signalfd file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The +.I fd +file descriptor is not a valid file descriptor. +.TP +.B EINVAL +.I fd +is not a valid signalfd file descriptor. +.\" or, the +.\" .I sizemask +.\" argument is not equal to +.\" .IR sizeof(sigset_t) ; +.TP +.B EINVAL +.I flags +is invalid; +or, in Linux 2.6.26 or earlier, +.I flags +is nonzero. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENODEV +Could not mount (internal) anonymous inode device. +.TP +.B ENOMEM +There was insufficient memory to create a new signalfd file descriptor. +.SH VERSIONS +.BR signalfd () +is available on Linux since kernel 2.6.22. +Working support is provided in glibc since version 2.8. +.\" signalfd() is in glibc 2.7, but reportedly does not build +The +.BR signalfd4 () +system call (see NOTES) is available on Linux since kernel 2.6.27. +.SH CONFORMING TO +.BR signalfd () +and +.BR signalfd4 () +are Linux-specific. +.SH NOTES +A process can create multiple signalfd file descriptors. +This makes it possible to accept different signals +on different file descriptors. +(This may be useful if monitoring the file descriptors using +.BR select (2), +.BR poll (2), +or +.BR epoll (7): +the arrival of different signals will make different file descriptors ready.) +If a signal appears in the +.I mask +of more than one of the file descriptors, then occurrences +of that signal can be read (once) from any one of the file descriptors. +.PP +Attempts to include +.B SIGKILL +and +.B SIGSTOP +in +.I mask +are silently ignored. +.PP +The signal mask employed by a signalfd file descriptor can be viewed +via the entry for the corresponding file descriptor in the process's +.IR /proc/[pid]/fdinfo +directory. +See +.BR proc (5) +for further details. +.\" +.SS Limitations +The signalfd mechanism can't be used to receive signals that +are synchronously generated, such as the +.BR SIGSEGV +signal that results from accessing an invalid memory address +or the +.BR SIGFPE +signal that results from an arithmetic error. +Such signals can be caught only via signal handler. +.PP +As described above, +in normal usage one blocks the signals that will be accepted via +.BR signalfd (). +If spawning a child process to execute a helper program +(that does not need the signalfd file descriptor), +then, after the call to +.BR fork (2), +you will normally want to unblock those signals before calling +.BR execve (2), +so that the helper program can see any signals that it expects to see. +Be aware, however, +that this won't be possible in the case of a helper program spawned +behind the scenes by any library function that the program may call. +In such cases, one must fall back to using a traditional signal +handler that writes to a file descriptor monitored by +.BR select (2), +.BR poll (2), +or +.BR epoll (7), +.\" +.SS C library/kernel differences +The underlying Linux system call requires an additional argument, +.IR "size_t sizemask" , +which specifies the size of the +.I mask +argument. +The glibc +.BR signalfd () +wrapper function does not include this argument, +since it provides the required value for the underlying system call. +.PP +There are two underlying Linux system calls: +.BR signalfd () +and the more recent +.BR signalfd4 (). +The former system call does not implement a +.I flags +argument. +The latter system call implements the +.I flags +values described above. +Starting with glibc 2.9, the +.BR signalfd () +wrapper function will use +.BR signalfd4 () +where it is available. +.SH BUGS +In kernels before 2.6.25, the +.I ssi_ptr +and +.I ssi_int +fields are not filled in with the data accompanying a signal sent by +.BR sigqueue (3). +.\" The fix also was put into 2.6.24.5 +.SH EXAMPLE +The program below accepts the signals +.B SIGINT +and +.B SIGQUIT +via a signalfd file descriptor. +The program terminates after accepting a +.B SIGQUIT +signal. +The following shell session demonstrates the use of the program: +.PP +.in +4n +.EX +.RB "$" " ./signalfd_demo" +.BR "^C" " # Control\-C generates SIGINT" +Got SIGINT +.B ^C +Got SIGINT +\fB^\\\fP # Control\-\\ generates SIGQUIT +Got SIGQUIT +$ +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +int +main(int argc, char *argv[]) +{ + sigset_t mask; + int sfd; + struct signalfd_siginfo fdsi; + ssize_t s; + + sigemptyset(&mask); + sigaddset(&mask, SIGINT); + sigaddset(&mask, SIGQUIT); + + /* Block signals so that they aren\(aqt handled + according to their default dispositions */ + + if (sigprocmask(SIG_BLOCK, &mask, NULL) == \-1) + handle_error("sigprocmask"); + + sfd = signalfd(\-1, &mask, 0); + if (sfd == \-1) + handle_error("signalfd"); + + for (;;) { + s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo)); + if (s != sizeof(struct signalfd_siginfo)) + handle_error("read"); + + if (fdsi.ssi_signo == SIGINT) { + printf("Got SIGINT\\n"); + } else if (fdsi.ssi_signo == SIGQUIT) { + printf("Got SIGQUIT\\n"); + exit(EXIT_SUCCESS); + } else { + printf("Read unexpected signal\\n"); + } + } +} +.EE +.SH SEE ALSO +.BR eventfd (2), +.BR poll (2), +.BR read (2), +.BR select (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR sigwaitinfo (2), +.BR timerfd_create (2), +.BR sigsetops (3), +.BR sigwait (3), +.BR epoll (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/signalfd4.2 b/man2/signalfd4.2 new file mode 100644 index 0000000..8dbea5c --- /dev/null +++ b/man2/signalfd4.2 @@ -0,0 +1 @@ +.so man2/signalfd.2 diff --git a/man2/sigpending.2 b/man2/sigpending.2 new file mode 100644 index 0000000..33d6842 --- /dev/null +++ b/man2/sigpending.2 @@ -0,0 +1,135 @@ +.\" Copyright (c) 2005 Michael Kerrisk +.\" based on earlier work by faith@cs.unc.edu and +.\" Mike Battersby +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 +.\" +.TH SIGPENDING 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigpending, rt_sigpending \- examine pending signals +.SH SYNOPSIS +.B #include +.PP +.BI "int sigpending(sigset_t *" set ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sigpending (): +_POSIX_C_SOURCE +.ad b +.SH DESCRIPTION +.PP +.BR sigpending () +returns the set of signals that are pending for delivery to the calling +thread (i.e., the signals which have been raised while blocked). +The mask of pending signals is returned in +.IR set . +.SH RETURN VALUE +.BR sigpending () +returns 0 on success and \-1 on error. +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +.TP +.B EFAULT +.I set +points to memory which is not a valid part of the process address space. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +See +.BR sigsetops (3) +for details on manipulating signal sets. +.PP +If a signal is both blocked and has a disposition of "ignored", it is +.I not +added to the mask of pending signals when generated. +.PP +The set of signals that is pending for a thread +is the union of the set of signals that is pending for that thread +and the set of signals that is pending for the process as a whole; see +.BR signal (7). +.PP +A child created via +.BR fork (2) +initially has an empty pending signal set; +the pending signal set is preserved across an +.BR execve (2). +.\" +.SS C library/kernel differences +The original Linux system call was named +.BR sigpending (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.IR sigset_t +argument supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigpending (), +was added to support an enlarged +.IR sigset_t +type. +The new system call takes a second argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal set in +.IR set . +.\" This argument is currently required to be less than or equal to +.\" .IR sizeof(sigset_t) +.\" (or the error +.\" .B EINVAL +.\" results). +The glibc +.BR sigpending () +wrapper function hides these details from us, transparently calling +.BR rt_sigpending () +when the kernel provides it. +.\" +.SH BUGS +In versions of glibc up to and including 2.2.1, +there is a bug in the wrapper function for +.BR sigpending () +which means that information about pending real-time signals +is not correctly returned. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigsetops (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2 new file mode 100644 index 0000000..3e57535 --- /dev/null +++ b/man2/sigprocmask.2 @@ -0,0 +1,241 @@ +.\" Copyright (c) 2005 Michael Kerrisk +.\" based on earlier work by faith@cs.unc.edu and +.\" Mike Battersby +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 +.\" +.TH SIGPROCMASK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigprocmask, rt_sigprocmask \- examine and change blocked signals +.SH SYNOPSIS +.B #include +.PP +.nf +/* Prototype for the glibc wrapper function */ +.BI "int sigprocmask(int " how ", const sigset_t *" set ", sigset_t *" oldset ); +.PP +/* Prototype for the underlying system call */ +.BI "int rt_sigprocmask(int " how ", const kernel_sigset_t *" set , +.BI " kernel_sigset_t *" oldset ", size_t " sigsetsize ); +.PP +/* Prototype for the legacy system call (deprecated) */ +.BI "int sigprocmask(int " how ", const old_kernel_sigset_t *" set , +.BI " old_kernel_sigset_t *" oldset ); " +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sigprocmask (): +_POSIX_C_SOURCE +.ad b +.SH DESCRIPTION +.BR sigprocmask () +is used to fetch and/or change the signal mask of the calling thread. +The signal mask is the set of signals whose delivery is currently +blocked for the caller +(see also +.BR signal (7) +for more details). +.PP +The behavior of the call is dependent on the value of +.IR how , +as follows. +.TP +.B SIG_BLOCK +The set of blocked signals is the union of the current set and the +.I set +argument. +.TP +.B SIG_UNBLOCK +The signals in +.I set +are removed from the current set of blocked signals. +It is permissible to attempt to unblock a signal which is not blocked. +.TP +.B SIG_SETMASK +The set of blocked signals is set to the argument +.IR set . +.PP +If +.I oldset +is non-NULL, the previous value of the signal mask is stored in +.IR oldset . +.PP +If +.I set +is NULL, then the signal mask is unchanged (i.e., +.I how +is ignored), +but the current value of the signal mask is nevertheless returned in +.I oldset +(if it is not NULL). +.PP +A set of functions for modifying and inspecting variables of type +.I sigset_t +("signal sets") is described in +.BR sigsetops (3). +.PP +The use of +.BR sigprocmask () +is unspecified in a multithreaded process; see +.BR pthread_sigmask (3). +.SH RETURN VALUE +.BR sigprocmask () +returns 0 on success and \-1 on error. +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +.TP +.B EFAULT +The +.I set +or +.I oldset +argument points outside the process's allocated address space. +.TP +.B EINVAL +Either the value specified in +.I how +was invalid or the kernel does not support the size passed in +.I sigsetsize. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +It is not possible to block +.BR SIGKILL " or " SIGSTOP . +Attempts to do so are silently ignored. +.PP +Each of the threads in a process has its own signal mask. +.PP +A child created via +.BR fork (2) +inherits a copy of its parent's signal mask; +the signal mask is preserved across +.BR execve (2). +.PP +If +.BR SIGBUS , +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +are generated +while they are blocked, the result is undefined, +unless the signal was generated by +.BR kill (2), +.BR sigqueue (3), +or +.BR raise (3). +.PP +See +.BR sigsetops (3) +for details on manipulating signal sets. +.PP +Note that it is permissible (although not very useful) to specify both +.I set +and +.I oldset +as NULL. +.\" +.SS C library/kernel differences +.PP +The kernel's definition of +.IR sigset_t +differs in size from that used +by the C library. +In this manual page, the former is referred to as +.I kernel_sigset_t +(it is nevertheless named +.I sigset_t +in the kernel sources). +.PP +The glibc wrapper function for +.BR sigprocmask () +silently ignores attempts to block the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.PP +The original Linux system call was named +.BR sigprocmask (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.IR sigset_t +(referred to as +.IR old_kernel_sigset_t +in this manual page) +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigprocmask (), +was added to support an enlarged +.IR sigset_t +type +(referred to as +.IR kernel_sigset_t +in this manual page). +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal sets in +.IR set +and +.IR oldset . +This argument is currently required to have a fixed architecture specific value +(equal to +.IR sizeof(kernel_sigset_t) ). +.\" sizeof(kernel_sigset_t) == _NSIG / 8, +.\" which equals to 8 on most architectures, but e.g. on MIPS it's 16. +.PP +The glibc +.BR sigprocmask () +wrapper function hides these details from us, transparently calling +.BR rt_sigprocmask () +when the kernel provides it. +.\" +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigpending (2), +.BR sigsuspend (2), +.BR pthread_sigmask (3), +.BR sigqueue (3), +.BR sigsetops (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sigqueue.2 b/man2/sigqueue.2 new file mode 100644 index 0000000..fee2bfb --- /dev/null +++ b/man2/sigqueue.2 @@ -0,0 +1,2 @@ +.so man3/sigqueue.3 +.\" FIXME . this link will eventually be removed (created Sep 2011) diff --git a/man2/sigreturn.2 b/man2/sigreturn.2 new file mode 100644 index 0000000..c22273e --- /dev/null +++ b/man2/sigreturn.2 @@ -0,0 +1,173 @@ +.\" Copyright (C) 2008, 2014, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created Sat Aug 21 1995 Thomas K. Dyas +.\" Modified Tue Oct 22 22:09:03 1996 by Eric S. Raymond +.\" 2008-06-26, mtk, added some more detail on the work done by sigreturn() +.\" 2014-12-05, mtk, rewrote all of the rest of the original page +.\" +.TH SIGRETURN 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame +.SH SYNOPSIS +.BI "int sigreturn(...);" +.SH DESCRIPTION +If the Linux kernel determines that an unblocked +signal is pending for a process, then, +at the next transition back to user mode in that process +(e.g., upon return from a system call or +when the process is rescheduled onto the CPU), +it creates a new frame on the user-space stack where it +saves various pieces of process context +(processor status word, registers, signal mask, and signal stack settings). +.\" See arch/x86/kernel/signal.c::__setup_frame() [in 3.17 source code] +.PP +The kernel also arranges that, during the transition back to user mode, +the signal handler is called, and that, upon return from the handler, +control passes to a piece of user-space code commonly called +the "signal trampoline". +The signal trampoline code in turn calls +.BR sigreturn (). +.PP +This +.BR sigreturn () +call undoes everything that was +done\(emchanging the process's signal mask, switching signal stacks (see +.BR sigaltstack "(2))\(emin " +order to invoke the signal handler. +Using the information that was earlier saved on the user-space stack +.BR sigreturn () +restores the process's signal mask, switches stacks, +and restores the process's context +(processor flags and registers, +including the stack pointer and instruction pointer), +so that the process resumes execution +at the point where it was interrupted by the signal. +.SH RETURN VALUE +.BR sigreturn () +never returns. +.SH CONFORMING TO +Many UNIX-type systems have a +.BR sigreturn () +system call or near equivalent. +However, this call is not specified in POSIX, +and details of its behavior vary across systems. +.SH NOTES +.BR sigreturn () +exists only to allow the implementation of signal handlers. +It should +.B never +be called directly. +(Indeed, a simple +.BR sigreturn () +.\" See sysdeps/unix/sysv/linux/sigreturn.c and +.\" signal/sigreturn.c in the glibc source +wrapper in the GNU C library simply returns -1, with +.I errno +set to +.BR ENOSYS .) +Details of the arguments (if any) passed to +.BR sigreturn () +vary depending on the architecture. +(On some architectures, such as x86-64, +.BR sigreturn () +takes no arguments, since all of the information that it requires +is available in the stack frame that was previously created by the +kernel on the user-space stack.) +.PP +Once upon a time, UNIX systems placed the signal trampoline code +onto the user stack. +Nowadays, pages of the user stack are protected so as to +disallow code execution. +Thus, on contemporary Linux systems, depending on the architecture, +the signal trampoline code lives either in the +.BR vdso (7) +or in the C library. +In the latter case, +.\" See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and +.\" sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source. +the C library's +.BR sigaction (2) +wrapper function informs the kernel of the location of the trampoline code +by placing its address in the +.I sa_restorer +field of the +.I sigaction +structure, +and sets the +.BR SA_RESTORER +flag in the +.IR sa_flags +field. +.PP +The saved process context information is placed in a +.I ucontext_t +structure (see +.IR ). +That structure is visible within the signal handler +as the third argument of a handler established via +.BR sigaction (2) +with the +.BR SA_SIGINFO +flag. +.PP +On some other UNIX systems, +the operation of the signal trampoline differs a little. +In particular, on some systems, upon transitioning back to user mode, +the kernel passes control to the trampoline (rather than the signal handler), +and the trampoline code calls the signal handler (and then calls +.BR sigreturn () +once the handler returns). +.\" +.SS C library/kernel differences +The original Linux system call was named +.BR sigreturn (). +However, with the addition of real-time signals in Linux 2.2, +a new system call, +.BR rt_sigreturn () +was added to support an enlarged +.IR sigset_t +type. +The GNU C library +hides these details from us, transparently employing +.BR rt_sigreturn () +when the kernel provides it. +.\" +.SH SEE ALSO +.BR kill (2), +.BR restart_syscall (2), +.BR sigaltstack (2), +.BR signal (2), +.BR getcontext (3), +.BR signal (7), +.BR vdso (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sigsuspend.2 b/man2/sigsuspend.2 new file mode 100644 index 0000000..07c0186 --- /dev/null +++ b/man2/sigsuspend.2 @@ -0,0 +1,155 @@ +.\" Copyright (c) 2005 Michael Kerrisk +.\" based on earlier work by faith@cs.unc.edu and +.\" Mike Battersby +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 +.\" +.TH SIGSUSPEND 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigsuspend, rt_sigsuspend \- wait for a signal +.SH SYNOPSIS +.B #include +.PP +.BI "int sigsuspend(const sigset_t *" mask ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sigsuspend (): +_POSIX_C_SOURCE +.ad b +.SH DESCRIPTION +.BR sigsuspend () +temporarily replaces the signal mask of the calling process with the +mask given by +.I mask +and then suspends the process until delivery of a signal whose +action is to invoke a signal handler or to terminate a process. +.PP +If the signal terminates the process, then +.BR sigsuspend () +does not return. +If the signal is caught, then +.BR sigsuspend () +returns after the signal handler returns, +and the signal mask is restored to the state before the call to +.BR sigsuspend (). +.PP +It is not possible to block +.B SIGKILL +or +.BR SIGSTOP ; +specifying these signals in +.IR mask , +has no effect on the process's signal mask. +.SH RETURN VALUE +.BR sigsuspend () +always returns \-1, with +.I errno +set to indicate the error (normally, +.BR EINTR ). +.SH ERRORS +.TP +.B EFAULT +.I mask +points to memory which is not a valid part of the process address space. +.TP +.B EINTR +The call was interrupted by a signal; +.BR signal (7). +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +.PP +Normally, +.BR sigsuspend () +is used in conjunction with +.BR sigprocmask (2) +in order to prevent delivery of a signal during the execution of a +critical code section. +The caller first blocks the signals with +.BR sigprocmask (2). +When the critical code has completed, the caller then waits for the +signals by calling +.BR sigsuspend () +with the signal mask that was returned by +.BR sigprocmask (2) +(in the +.I oldset +argument). +.PP +See +.BR sigsetops (3) +for details on manipulating signal sets. +.\" +.SS C library/kernel differences +The original Linux system call was named +.BR sigsuspend (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.IR sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigsuspend (), +was added to support an enlarged +.IR sigset_t +type. +The new system call takes a second argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal set in +.IR mask . +This argument is currently required to have the value +.IR sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigsuspend () +wrapper function hides these details from us, transparently calling +.BR rt_sigsuspend () +when the kernel provides it. +.\" +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR sigwaitinfo (2), +.BR sigsetops (3), +.BR sigwait (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sigtimedwait.2 b/man2/sigtimedwait.2 new file mode 100644 index 0000000..1b13df1 --- /dev/null +++ b/man2/sigtimedwait.2 @@ -0,0 +1 @@ +.so man2/sigwaitinfo.2 diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2 new file mode 100644 index 0000000..84a2198 --- /dev/null +++ b/man2/sigwaitinfo.2 @@ -0,0 +1,258 @@ +.\" Copyright (c) 2002 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SIGWAITINFO 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigwaitinfo, sigtimedwait, rt_sigtimedwait \- synchronously wait +for queued signals +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sigwaitinfo(const sigset_t *" set ", siginfo_t *" info ");" +.PP +.BI "int sigtimedwait(const sigset_t *" set ", siginfo_t *" info ", " +.BI " const struct timespec *" timeout ");" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR sigwaitinfo (), +.BR sigtimedwait (): +_POSIX_C_SOURCE\ >=\ 199309L +.SH DESCRIPTION +.BR sigwaitinfo () +suspends execution of the calling thread until one of the signals in +.I set +is pending +(If one of the signals in +.I set +is already pending for the calling thread, +.BR sigwaitinfo () +will return immediately.) +.PP +.BR sigwaitinfo () +removes the signal from the set of pending +signals and returns the signal number as its function result. +If the +.I info +argument is not NULL, +then the buffer that it points to is used to return a structure of type +.I siginfo_t +(see +.BR sigaction (2)) +containing information about the signal. +.PP +If multiple signals in +.I set +are pending for the caller, the signal that is retrieved by +.BR sigwaitinfo () +is determined according to the usual ordering rules; see +.BR signal (7) +for further details. +.PP +.BR sigtimedwait () +operates in exactly the same way as +.BR sigwaitinfo () +except that it has an additional argument, +.IR timeout , +which specifies the interval for which +the thread is suspended waiting for a signal. +(This interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the interval +may overrun by a small amount.) +This argument is of the following type: +.PP +.in +4n +.EX +struct timespec { + long tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +} +.EE +.in +.PP +If both fields of this structure are specified as 0, a poll is performed: +.BR sigtimedwait () +returns immediately, either with information about a signal that +was pending for the caller, or with an error +if none of the signals in +.I set +was pending. +.SH RETURN VALUE +On success, both +.BR sigwaitinfo () +and +.BR sigtimedwait () +return a signal number (i.e., a value greater than zero). +On failure both calls return \-1, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +No signal in +.I set +was became pending within the +.I timeout +period specified to +.BR sigtimedwait (). +.TP +.B EINTR +The wait was interrupted by a signal handler; see +.BR signal (7). +(This handler was for a signal other than one of those in +.IR set .) +.TP +.B EINVAL +.I timeout +was invalid. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +In normal usage, the calling program blocks the signals in +.I set +via a prior call to +.BR sigprocmask (2) +(so that the default disposition for these signals does not occur if they +become pending between successive calls to +.BR sigwaitinfo () +or +.BR sigtimedwait ()) +and does not establish handlers for these signals. +In a multithreaded program, +the signal should be blocked in all threads, in order to prevent +the signal being treated according to its default disposition in +a thread other than the one calling +.BR sigwaitinfo () +or +.BR sigtimedwait ()). +.PP +The set of signals that is pending for a given thread is the +union of the set of signals that is pending specifically for that thread +and the set of signals that is pending for the process as a whole (see +.BR signal (7)). +.PP +Attempts to wait for +.B SIGKILL +and +.B SIGSTOP +are silently ignored. +.PP +If multiple threads of a process are blocked +waiting for the same signal(s) in +.BR sigwaitinfo () +or +.BR sigtimedwait (), +then exactly one of the threads will actually receive the +signal if it becomes pending for the process as a whole; +which of the threads receives the signal is indeterminate. +.PP +.BR sigwaitinfo () +or +.BR sigtimedwait (), +can't be used to receive signals that +are synchronously generated, such as the +.BR SIGSEGV +signal that results from accessing an invalid memory address +or the +.BR SIGFPE +signal that results from an arithmetic error. +Such signals can be caught only via signal handler. +.PP +POSIX leaves the meaning of a NULL value for the +.I timeout +argument of +.BR sigtimedwait () +unspecified, permitting the possibility that this has the same meaning +as a call to +.BR sigwaitinfo (), +and indeed this is what is done on Linux. +.\" +.SS C library/kernel differences +On Linux, +.BR sigwaitinfo () +is a library function implemented on top of +.BR sigtimedwait (). +.PP +The glibc wrapper functions for +.BR sigwaitinfo () +and +.BR sigtimedwait () +silently ignore attempts to wait for the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.PP +The original Linux system call was named +.BR sigtimedwait (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigtimedwait (), +was added to support an enlarged +.IR sigset_t +type. +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal set in +.IR set . +This argument is currently required to have the value +.IR sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigtimedwait () +wrapper function hides these details from us, transparently calling +.BR rt_sigtimedwait () +when the kernel provides it. +.\" +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigqueue (3), +.BR sigsetops (3), +.BR sigwait (3), +.BR signal (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/socket.2 b/man2/socket.2 new file mode 100644 index 0000000..ca6267a --- /dev/null +++ b/man2/socket.2 @@ -0,0 +1,439 @@ +'\" t +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $ +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998, 1999 by Andi Kleen +.\" Modified 2002-07-17 by Michael Kerrisk +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH SOCKET 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +socket \- create an endpoint for communication +.SH SYNOPSIS +.BR "#include " " /* See NOTES */" +.br +.B #include +.PP +.BI "int socket(int " domain ", int " type ", int " protocol ); +.SH DESCRIPTION +.BR socket () +creates an endpoint for communication and returns a file descriptor +that refers to that endpoint. +The file descriptor returned by a successful call will be +the lowest-numbered file descriptor not currently open for the process. +.PP +The +.I domain +argument specifies a communication domain; this selects the protocol +family which will be used for communication. +These families are defined in +.IR . +The currently understood formats include: +.TS +tab(:); +l l l. +Name:Purpose:Man page +T{ +.BR AF_UNIX ", " AF_LOCAL +T}:T{ +Local communication +T}:T{ +.BR unix (7) +T} +T{ +.B AF_INET +T}:IPv4 Internet protocols:T{ +.BR ip (7) +T} +T{ +.B AF_INET6 +T}:IPv6 Internet protocols:T{ +.BR ipv6 (7) +T} +T{ +.B AF_IPX +T}:IPX \- Novell protocols: +T{ +.B AF_NETLINK +T}:T{ +Kernel user interface device +T}:T{ +.BR netlink (7) +T} +T{ +.B AF_X25 +T}:ITU-T X.25 / ISO-8208 protocol:T{ +.BR x25 (7) +T} +T{ +.B AF_AX25 +T}:T{ +Amateur radio AX.25 protocol +T}: +T{ +.B AF_ATMPVC +T}:Access to raw ATM PVCs: +T{ +.B AF_APPLETALK +T}:AppleTalk:T{ +.BR ddp (7) +T} +T{ +.B AF_PACKET +T}:T{ +Low level packet interface +T}:T{ +.BR packet (7) +T} +T{ +.B AF_ALG +T}:T{ +Interface to kernel crypto API +T} +.TE +.PP +The socket has the indicated +.IR type , +which specifies the communication semantics. +Currently defined types +are: +.TP 16 +.B SOCK_STREAM +Provides sequenced, reliable, two-way, connection-based byte streams. +An out-of-band data transmission mechanism may be supported. +.TP +.B SOCK_DGRAM +Supports datagrams (connectionless, unreliable messages of a fixed +maximum length). +.TP +.B SOCK_SEQPACKET +Provides a sequenced, reliable, two-way connection-based data +transmission path for datagrams of fixed maximum length; a consumer is +required to read an entire packet with each input system call. +.TP +.B SOCK_RAW +Provides raw network protocol access. +.TP +.B SOCK_RDM +Provides a reliable datagram layer that does not guarantee ordering. +.TP +.B SOCK_PACKET +Obsolete and should not be used in new programs; +see +.BR packet (7). +.PP +Some socket types may not be implemented by all protocol families. +.PP +Since Linux 2.6.27, the +.I type +argument serves a second purpose: +in addition to specifying a socket type, +it may include the bitwise OR of any of the following values, +to modify the behavior of +.BR socket (): +.TP 16 +.B SOCK_NONBLOCK +Set the +.BR O_NONBLOCK +file status flag on the new open file description. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B SOCK_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.PP +The +.I protocol +specifies a particular protocol to be used with the socket. +Normally only a single protocol exists to support a particular +socket type within a given protocol family, in which case +.I protocol +can be specified as 0. +However, it is possible that many protocols may exist, in +which case a particular protocol must be specified in this manner. +The protocol number to use is specific to the \*(lqcommunication domain\*(rq +in which communication is to take place; see +.BR protocols (5). +See +.BR getprotoent (3) +on how to map protocol name strings to protocol numbers. +.PP +Sockets of type +.B SOCK_STREAM +are full-duplex byte streams. +They do not preserve +record boundaries. +A stream socket must be in +a +.I connected +state before any data may be sent or received on it. +A connection to +another socket is created with a +.BR connect (2) +call. +Once connected, data may be transferred using +.BR read (2) +and +.BR write (2) +calls or some variant of the +.BR send (2) +and +.BR recv (2) +calls. +When a session has been completed a +.BR close (2) +may be performed. +Out-of-band data may also be transmitted as described in +.BR send (2) +and received as described in +.BR recv (2). +.PP +The communications protocols which implement a +.B SOCK_STREAM +ensure that data is not lost or duplicated. +If a piece of data for which +the peer protocol has buffer space cannot be successfully transmitted +within a reasonable length of time, then the connection is considered +to be dead. +When +.B SO_KEEPALIVE +is enabled on the socket the protocol checks in a protocol-specific +manner if the other end is still alive. +A +.B SIGPIPE +signal is raised if a process sends or receives +on a broken stream; this causes naive processes, +which do not handle the signal, to exit. +.B SOCK_SEQPACKET +sockets employ the same system calls as +.B SOCK_STREAM +sockets. +The only difference is that +.BR read (2) +calls will return only the amount of data requested, +and any data remaining in the arriving packet will be discarded. +Also all message boundaries in incoming datagrams are preserved. +.PP +.B SOCK_DGRAM +and +.B SOCK_RAW +sockets allow sending of datagrams to correspondents named in +.BR sendto (2) +calls. +Datagrams are generally received with +.BR recvfrom (2), +which returns the next datagram along with the address of its sender. +.PP +.B SOCK_PACKET +is an obsolete socket type to receive raw packets directly from the +device driver. +Use +.BR packet (7) +instead. +.PP +An +.BR fcntl (2) +.B F_SETOWN +operation can be used to specify a process or process group to receive a +.B SIGURG +signal when the out-of-band data arrives or +.B SIGPIPE +signal when a +.B SOCK_STREAM +connection breaks unexpectedly. +This operation may also be used to set the process or process group +that receives the I/O and asynchronous notification of I/O events via +.BR SIGIO . +Using +.B F_SETOWN +is equivalent to an +.BR ioctl (2) +call with the +.B FIOSETOWN +or +.B SIOCSPGRP +argument. +.PP +When the network signals an error condition to the protocol module (e.g., +using an ICMP message for IP) the pending error flag is set for the socket. +The next operation on this socket will return the error code of the pending +error. +For some protocols it is possible to enable a per-socket error queue +to retrieve detailed information about the error; see +.B IP_RECVERR +in +.BR ip (7). +.PP +The operation of sockets is controlled by socket level +.IR options . +These options are defined in +.IR . +The functions +.BR setsockopt (2) +and +.BR getsockopt (2) +are used to set and get options, respectively. +.SH RETURN VALUE +On success, a file descriptor for the new socket is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.TP +.B EAFNOSUPPORT +The implementation does not support the specified address family. +.TP +.B EINVAL +Unknown protocol, or protocol family not available. +.TP +.B EINVAL +.\" Since Linux 2.6.27 +Invalid flags in +.IR type . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.BR ENOBUFS " or " ENOMEM +Insufficient memory is available. +The socket cannot be +created until sufficient resources are freed. +.TP +.B EPROTONOSUPPORT +The protocol type or the specified protocol is not +supported within this domain. +.PP +Other errors may be generated by the underlying protocol modules. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.4BSD. +.PP +The +.B SOCK_NONBLOCK +and +.B SOCK_CLOEXEC +flags are Linux-specific. +.PP +.BR socket () +appeared in 4.2BSD. +It is generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System\ V variants). +.SH NOTES +POSIX.1 does not require the inclusion of +.IR , +and this header file is not required on Linux. +However, some historical (BSD) implementations required this header +file, and portable applications are probably wise to include it. +.PP +The manifest constants used under 4.x BSD for protocol families +are +.BR PF_UNIX , +.BR PF_INET , +and so on, while +.BR AF_UNIX , +.BR AF_INET , +and so on are used for address +families. +However, already the BSD man page promises: "The protocol +family generally is the same as the address family", and subsequent +standards use AF_* everywhere. +.PP +The +.B AF_ALG +protocol type was added in Linux 2.6.38. +More information on this interface is provided with the kernel HTML +documentation at +.IR https://www.kernel.org/doc/htmldocs/crypto\-API/User.html . +.SH EXAMPLE +An example of the use of +.BR socket () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR close (2), +.BR connect (2), +.BR fcntl (2), +.BR getpeername (2), +.BR getsockname (2), +.BR getsockopt (2), +.BR ioctl (2), +.BR listen (2), +.BR read (2), +.BR recv (2), +.BR select (2), +.BR send (2), +.BR shutdown (2), +.BR socketpair (2), +.BR write (2), +.BR getprotoent (3), +.BR ip (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) +.PP +\(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq +and +\(lqBSD Interprocess Communication Tutorial\(rq, +reprinted in +.I UNIX Programmer's Supplementary Documents Volume 1. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/socketcall.2 b/man2/socketcall.2 new file mode 100644 index 0000000..528577d --- /dev/null +++ b/man2/socketcall.2 @@ -0,0 +1,200 @@ +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 22:11:53 1996 by Eric S. Raymond +.TH SOCKETCALL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +socketcall \- socket system calls +.SH SYNOPSIS +.B #include +.PP +.BI "int socketcall(int " call ", unsigned long *" args ); +.SH DESCRIPTION +.BR socketcall () +is a common kernel entry point for the socket system calls. +.I call +determines which socket function to invoke. +.I args +points to a block containing the actual arguments, +which are passed through to the appropriate call. +.PP +User programs should call the appropriate functions by their usual names. +Only standard library implementors and kernel hackers need to know about +.BR socketcall (). +.PP +.TS +tab(:); +l l. +\fIcall\fR:Man page +T{ +.B SYS_SOCKET +T}:T{ +.BR socket (2) +T} +T{ +.B SYS_BIND +T}:T{ +.BR bind (2) +T} +T{ +.B SYS_CONNECT +T}:T{ +.BR connect (2) +T} +T{ +.B SYS_LISTEN +T}:T{ +.BR listen (2) +T} +T{ +.B SYS_ACCEPT +T}:T{ +.BR accept (2) +T} +T{ +.B SYS_GETSOCKNAME +T}:T{ +.BR getsockname (2) +T} +T{ +.B SYS_GETPEERNAME +T}:T{ +.BR getpeername (2) +T} +T{ +.B SYS_SOCKETPAIR +T}:T{ +.BR socketpair (2) +T} +T{ +.B SYS_SEND +T}:T{ +.BR send (2) +T} +T{ +.B SYS_RECV +T}:T{ +.BR recv (2) +T} +T{ +.B SYS_SENDTO +T}:T{ +.BR sendto (2) +T} +T{ +.B SYS_RECVFROM +T}:T{ +.BR recvfrom (2) +T} +T{ +.B SYS_SHUTDOWN +T}:T{ +.BR shutdown (2) +T} +T{ +.B SYS_SETSOCKOPT +T}:T{ +.BR setsockopt (2) +T} +T{ +.B SYS_GETSOCKOPT +T}:T{ +.BR getsockopt (2) +T} +T{ +.B SYS_SENDMSG +T}:T{ +.BR sendmsg (2) +T} +T{ +.B SYS_RECVMSG +T}:T{ +.BR recvmsg (2) +T} +T{ +.B SYS_ACCEPT4 +T}:T{ +.BR accept4 (2) +T} +T{ +.B SYS_RECVMMSG +T}:T{ +.BR recvmmsg (2) +T} +T{ +.B SYS_SENDMMSG +T}:T{ +.BR sendmmsg (2) +T} +.TE +.SH CONFORMING TO +This call is specific to Linux, and should not be used in programs +intended to be portable. +.SH NOTES +On a some architectures\(emfor example, x86-64 and ARM\(emthere is no +.BR socketcall () +system call; instead +.BR socket (2), +.BR accept (2), +.BR bind (2), +and so on really are implemented as separate system calls. +.PP +On x86-32, +.BR socketcall () +was historically the only entry point for the sockets API. +However, starting in Linux 4.3, +.\" commit 9dea5dc921b5f4045a18c63eb92e84dc274d17eb +direct system calls are provided on x86-32 for the sockets API. +This facilitates the creation of +.BR seccomp (2) +filters that filter sockets system calls +(for new user-space binaries that are compiled +to use the new entry points) +and also provides a (very) small performance improvement. +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR getpeername (2), +.BR getsockname (2), +.BR getsockopt (2), +.BR listen (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmsg (2), +.BR send (2), +.BR sendmsg (2), +.BR sendto (2), +.BR setsockopt (2), +.BR shutdown (2), +.BR socket (2), +.BR socketpair (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/socketpair.2 b/man2/socketpair.2 new file mode 100644 index 0000000..3224538 --- /dev/null +++ b/man2/socketpair.2 @@ -0,0 +1,148 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)socketpair.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2002-07-22 by Michael Kerrisk +.\" Modified 2004-06-17 by Michael Kerrisk +.\" 2008-10-11, mtk: Add description of SOCK_NONBLOCK and SOCK_CLOEXEC +.\" +.TH SOCKETPAIR 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +socketpair \- create a pair of connected sockets +.SH SYNOPSIS +.BR "#include " " /* See NOTES */" +.br +.B #include +.PP +.BI "int socketpair(int " domain ", int " type ", int " protocol \ +", int " sv [2]); +.SH DESCRIPTION +The +.BR socketpair () +call creates an unnamed pair of connected sockets in the specified +.IR domain , +of the specified +.IR type , +and using the optionally specified +.IR protocol . +For further details of these arguments, see +.BR socket (2). +.PP +The file descriptors used in referencing the new sockets are returned in +.IR sv [0] +and +.IR sv [1]. +The two sockets are indistinguishable. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.PP +On Linux (and other systems), +.BR socketpair () +does not modify +.I sv +on failure. +A requirement standardizing this behavior was added in POSIX.1-2016. +.\" http://austingroupbugs.net/view.php?id=483 +.SH ERRORS +.TP +.B EAFNOSUPPORT +The specified address family is not supported on this machine. +.TP +.B EFAULT +The address +.I sv +does not specify a valid part of the process address space. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B EOPNOTSUPP +The specified protocol does not support creation of socket pairs. +.TP +.B EPROTONOSUPPORT +The specified protocol is not supported on this machine. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.4BSD. +.BR socketpair () +first appeared in 4.2BSD. +It is generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System\ V variants). +.SH NOTES +On Linux, the only supported domain for this call is +.B AF_UNIX +(or synonymously, +.BR AF_LOCAL ). +(Most implementations have the same restriction.) +.PP +Since Linux 2.6.27, +.BR socketpair () +supports the +.BR SOCK_NONBLOCK +and +.BR SOCK_CLOEXEC +flags in the +.I type +argument, as described in +.BR socket (2). +.PP +POSIX.1 does not require the inclusion of +.IR , +and this header file is not required on Linux. +However, some historical (BSD) implementations required this header +file, and portable applications are probably wise to include it. +.SH SEE ALSO +.BR pipe (2), +.BR read (2), +.BR socket (2), +.BR write (2), +.BR socket (7), +.BR unix (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/splice.2 b/man2/splice.2 new file mode 100644 index 0000000..6efcb08 --- /dev/null +++ b/man2/splice.2 @@ -0,0 +1,279 @@ +.\" This manpage is Copyright (C) 2006 Jens Axboe +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SPLICE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +splice \- splice data to/from a pipe +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "ssize_t splice(int " fd_in ", loff_t *" off_in ", int " fd_out , +.BI " loff_t *" off_out ", size_t " len \ +", unsigned int " flags ); +.\" Return type was long before glibc 2.7 +.fi +.SH DESCRIPTION +.BR splice () +moves data between two file descriptors +without copying between kernel address space and user address space. +It transfers up to +.I len +bytes of data from the file descriptor +.I fd_in +to the file descriptor +.IR fd_out , +where one of the file descriptors must refer to a pipe. +.PP +The following semantics apply for +.I fd_in +and +.IR off_in : +.IP * 3 +If +.I fd_in +refers to a pipe, then +.I off_in +must be NULL. +.IP * +If +.I fd_in +does not refer to a pipe and +.I off_in +is NULL, then bytes are read from +.I fd_in +starting from the file offset, +and the file offset is adjusted appropriately. +.IP * +If +.I fd_in +does not refer to a pipe and +.I off_in +is not NULL, then +.I off_in +must point to a buffer which specifies the starting +offset from which bytes will be read from +.IR fd_in ; +in this case, the file offset of +.I fd_in +is not changed. +.PP +Analogous statements apply for +.I fd_out +and +.IR off_out . +.PP +The +.I flags +argument is a bit mask that is composed by ORing together +zero or more of the following values: +.TP +.B SPLICE_F_MOVE +Attempt to move pages instead of copying. +This is only a hint to the kernel: +pages may still be copied if the kernel cannot move the +pages from the pipe, or if +the pipe buffers don't refer to full pages. +The initial implementation of this flag was buggy: +therefore starting in Linux 2.6.21 it is a no-op +(but is still permitted in a +.BR splice () +call); +in the future, a correct implementation may be restored. +.TP +.B SPLICE_F_NONBLOCK +Do not block on I/O. +This makes the splice pipe operations nonblocking, but +.BR splice () +may nevertheless block because the file descriptors that +are spliced to/from may block (unless they have the +.B O_NONBLOCK +flag set). +.TP +.B SPLICE_F_MORE +More data will be coming in a subsequent splice. +This is a helpful hint when +the +.I fd_out +refers to a socket (see also the description of +.B MSG_MORE +in +.BR send (2), +and the description of +.B TCP_CORK +in +.BR tcp (7)). +.TP +.B SPLICE_F_GIFT +Unused for +.BR splice (); +see +.BR vmsplice (2). +.SH RETURN VALUE +Upon successful completion, +.BR splice () +returns the number of bytes +spliced to or from the pipe. +.PP +A return value of 0 means end of input. +If +.I fd_in +refers to a pipe, then this means that there was no data to transfer, +and it would not make sense to block because there are no writers +connected to the write end of the pipe. +.PP +On error, +.BR splice () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.B SPLICE_F_NONBLOCK +was specified in +.IR flags , +and the operation would block. +.TP +.B EBADF +One or both file descriptors are not valid, +or do not have proper read-write mode. +.TP +.B EINVAL +The target filesystem doesn't support splicing. +.TP +.B EINVAL +The target file is opened in append mode. +.\" The append-mode error is given since 2.6.27; in earlier kernels, +.\" splice() in append mode was broken +.TP +.B EINVAL +Neither of the file descriptors refers to a pipe. +.TP +.B EINVAL +An offset was given for nonseekable device (e.g., a pipe). +.TP +.B EINVAL +.I fd_in +and +.I fd_out +refer to the same pipe. +.TP +.B ENOMEM +Out of memory. +.TP +.B ESPIPE +Either +.I off_in +or +.I off_out +was not NULL, but the corresponding file descriptor refers to a pipe. +.SH VERSIONS +The +.BR splice () +system call first appeared in Linux 2.6.17; +library support was added to glibc in version 2.5. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +The three system calls +.BR splice (), +.BR vmsplice (2), +and +.BR tee (2), +provide user-space programs with full control over an arbitrary +kernel buffer, implemented within the kernel using the same type +of buffer that is used for a pipe. +In overview, these system calls perform the following tasks: +.TP 1.2i +.BR splice () +moves data from the buffer to an arbitrary file descriptor, or vice versa, +or from one buffer to another. +.TP +.BR tee (2) +"copies" the data from one buffer to another. +.TP +.BR vmsplice (2) +"copies" data from user space into the buffer. +.PP +Though we talk of copying, actual copies are generally avoided. +The kernel does this by implementing a pipe buffer as a set +of reference-counted pointers to pages of kernel memory. +The kernel creates "copies" of pages in a buffer by creating new +pointers (for the output buffer) referring to the pages, +and increasing the reference counts for the pages: +only pointers are copied, not the pages of the buffer. +.\" +.\" Linus: Now, imagine using the above in a media server, for example. +.\" Let's say that a year or two has passed, so that the video drivers +.\" have been updated to be able to do the splice thing, and what can +.\" you do? You can: +.\" +.\" - splice from the (mpeg or whatever - let's just assume that the video +.\" input is either digital or does the encoding on its own - like they +.\" pretty much all do) video input into a pipe (remember: no copies - the +.\" video input will just DMA directly into memory, and splice will just +.\" set up the pages in the pipe buffer) +.\" - tee that pipe to split it up +.\" - splice one end to a file (ie "save the compressed stream to disk") +.\" - splice the other end to a real-time video decoder window for your +.\" real-time viewing pleasure. +.\" +.\" Linus: Now, the advantage of splice()/tee() is that you can +.\" do zero-copy movement of data, and unlike sendfile() you can +.\" do it on _arbitrary_ data (and, as shown by "tee()", it's more +.\" than just sending the data to somebody else: you can duplicate +.\" the data and choose to forward it to two or more different +.\" users - for things like logging etc.). +.\" +.PP +In Linux 2.6.30 and earlier, +exactly one of +.I fd_in +and +.I fd_out +was required to be a pipe. +Since Linux 2.6.31, +.\" commit 7c77f0b3f9208c339a4b40737bb2cb0f0319bb8d +both arguments may refer to pipes. +.SH EXAMPLE +See +.BR tee (2). +.SH SEE ALSO +.BR copy_file_range (2), +.BR sendfile (2), +.BR tee (2), +.BR vmsplice (2), +.BR pipe (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/spu_create.2 b/man2/spu_create.2 new file mode 100644 index 0000000..875e8a6 --- /dev/null +++ b/man2/spu_create.2 @@ -0,0 +1,283 @@ +.\" Copyright (c) International Business Machines Corp., 2006 +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See +.\" the GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" HISTORY: +.\" 2005-09-28, created by Arnd Bergmann +.\" 2006-06-16, revised by Eduardo M. Fleury +.\" 2007-07-10, some polishing by mtk +.\" 2007-09-28, updates for newer kernels by Jeremy Kerr +.\" +.TH SPU_CREATE 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +spu_create \- create a new spu context +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode ");" +.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode "," +.BI " int " neighbor_fd ");" +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The +.BR spu_create () +system call is used on PowerPC machines that implement the +Cell Broadband Engine Architecture in order to access Synergistic +Processor Units (SPUs). +It creates a new logical context for an SPU in +.I pathname +and returns a file descriptor associated with it. +.I pathname +must refer to a nonexistent directory in the mount point of +the SPU filesystem +.RB ( spufs ). +If +.BR spu_create () +is successful, a directory is created at +.I pathname +and it is populated with the files described in +.BR spufs (7). +.PP +When a context is created, +the returned file descriptor can only be passed to +.BR spu_run (2), +used as the +.I dirfd +argument to the +.B *at +family of system calls (e.g., +.BR openat (2)), +or closed; +other operations are not defined. +A logical SPU +context is destroyed (along with all files created within the context's +.I pathname +directory) once the last reference to the context has gone; +this usually occurs when the file descriptor returned by +.BR spu_create () +is closed. +.PP +The +.I flags +argument can be zero or any bitwise OR-ed +combination of the following constants: +.TP +.B SPU_CREATE_EVENTS_ENABLED +Rather than using signals for reporting DMA errors, use the +.I event +argument to +.BR spu_run (2). +.TP +.B SPU_CREATE_GANG +Create an SPU gang instead of a context. +(A gang is a group of SPU contexts that are +functionally related to each other and which share common scheduling +parameters\(empriority and policy. +In the future, gang scheduling may be implemented causing +the group to be switched in and out as a single unit.) +.IP +A new directory will be created at the location specified by the +.I pathname +argument. +This gang may be used to hold other SPU contexts, by providing +a pathname that is within the gang directory to further calls to +.BR spu_create (). +.TP +.B SPU_CREATE_NOSCHED +Create a context that is not affected by the SPU scheduler. +Once the context is run, +it will not be scheduled out until it is destroyed by +the creating process. +.IP +Because the context cannot be removed from the SPU, some functionality +is disabled for +.BR SPU_CREATE_NOSCHED +contexts. +Only a subset of the files will be +available in this context directory in +.BR spufs . +Additionally, +.BR SPU_CREATE_NOSCHED +contexts cannot dump a core file when crashing. +.IP +Creating +.BR SPU_CREATE_NOSCHED +contexts requires the +.B CAP_SYS_NICE +capability. +.TP +.B SPU_CREATE_ISOLATE +Create an isolated SPU context. +Isolated contexts are protected from some +PPE (PowerPC Processing Element) +operations, +such as access to the SPU local store and the NPC register. +.IP +Creating +.B SPU_CREATE_ISOLATE +contexts also requires the +.B SPU_CREATE_NOSCHED +flag. +.TP +.B SPU_CREATE_AFFINITY_SPU +Create a context with affinity to another SPU context. +This affinity information is used within the SPU scheduling algorithm. +Using this flag requires that a file descriptor referring to +the other SPU context be passed in the +.I neighbor_fd +argument. +.TP +.B SPU_CREATE_AFFINITY_MEM +Create a context with affinity to system memory. +This affinity information +is used within the SPU scheduling algorithm. +.PP +The +.I mode +argument (minus any bits set in the process's +.BR umask (2)) +specifies the permissions used for creating the new directory in +.BR spufs . +See +.BR stat (2) +for a full list of the possible +.I mode +values. +.SH RETURN VALUE +On success, +.BR spu_create () +returns a new file descriptor. +On error, \-1 is returned, and +.I errno +is set to one of the error codes listed below. +.SH ERRORS +.TP +.B EACCES +The current user does not have write access to the +.BR spufs (7) +mount point. +.TP +.B EEXIST +An SPU context already exists at the given pathname. +.TP +.B EFAULT +.I pathname +is not a valid string pointer in the +calling process's address space. +.TP +.B EINVAL +.I pathname +is not a directory in the +.BR spufs (7) +mount point, or invalid flags have been provided. +.TP +.B ELOOP +Too many symbolic links were found while resolving +.IR pathname . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENODEV +An isolated context was requested, but the hardware does not support +SPU isolation. +.TP +.B ENOENT +Part of +.I pathname +could not be resolved. +.TP +.B ENOMEM +The kernel could not allocate all resources required. +.TP +.B ENOSPC +There are not enough SPU resources available to create +a new context or the user-specific limit for the number +of SPU contexts has been reached. +.TP +.B ENOSYS +The functionality is not provided by the current system, because +either the hardware does not provide SPUs or the spufs module is not +loaded. +.TP +.B ENOTDIR +A part of +.I pathname +is not a directory. +.TP +.B EPERM +The +.I SPU_CREATE_NOSCHED +flag has been given, but the user does not have the +.B CAP_SYS_NICE +capability. +.SH FILES +.I pathname +must point to a location beneath the mount point of +.BR spufs . +By convention, it gets mounted in +.IR /spu . +.SH VERSIONS +The +.BR spu_create () +system call was added to Linux in kernel 2.6.16. +.SH CONFORMING TO +This call is Linux-specific and implemented only on the PowerPC +architecture. +Programs using this system call are not portable. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +Note however, that +.BR spu_create () +is meant to be used from libraries that implement a more abstract +interface to SPUs, not to be used from regular applications. +See +.UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ +.UE +for the recommended libraries. +.SH EXAMPLE +See +.BR spu_run (2) +for an example of the use of +.BR spu_create () +.SH SEE ALSO +.BR close (2), +.BR spu_run (2), +.BR capabilities (7), +.BR spufs (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/spu_run.2 b/man2/spu_run.2 new file mode 100644 index 0000000..012f24e --- /dev/null +++ b/man2/spu_run.2 @@ -0,0 +1,277 @@ +.\" Copyright (c) International Business Machines Corp., 2006 +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See +.\" the GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" HISTORY: +.\" 2005-09-28, created by Arnd Bergmann +.\" 2006-06-16, revised by Eduardo M. Fleury +.\" 2007-07-10, some polishing by mtk +.\" 2007-09-28, updates for newer kernels, added example +.\" by Jeremy Kerr +.\" +.TH SPU_RUN 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +spu_run \- execute an SPU context +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int spu_run(int " fd ", unsigned int *" npc \ +", unsigned int *" event ");" +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The +.BR spu_run () +system call is used on PowerPC machines that implement the +Cell Broadband Engine Architecture in order to access Synergistic +Processor Units (SPUs). +The +.I fd +argument is a file descriptor returned by +.BR spu_create (2) +that refers to a specific SPU context. +When the context gets scheduled to a physical SPU, +it starts execution at the instruction pointer passed in +.IR npc . +.PP +Execution of SPU code happens synchronously, meaning that +.BR spu_run () +blocks while the SPU is still running. +If there is a need +to execute SPU code in parallel with other code on either the +main CPU or other SPUs, a new thread of execution must be created +first (e.g., using +.BR pthread_create (3)). +.PP +When +.BR spu_run () +returns, the current value of the SPU program counter is written to +.IR npc , +so successive calls to +.BR spu_run () +can use the same +.I npc +pointer. +.PP +The +.I event +argument provides a buffer for an extended status code. +If the SPU +context was created with the +.B SPU_CREATE_EVENTS_ENABLED +flag, then this buffer is populated by the Linux kernel before +.BR spu_run () +returns. +.PP +The status code may be one (or more) of the following constants: +.TP +.B SPE_EVENT_DMA_ALIGNMENT +A DMA alignment error occurred. +.TP +.B SPE_EVENT_INVALID_DMA +An invalid MFC DMA command was attempted. +.TP +.B SPE_EVENT_SPE_DATA_STORAGE +A DMA storage error occurred. +.TP +.B SPE_EVENT_SPE_ERROR +An illegal instruction was executed. +.PP +NULL +is a valid value for the +.I event +argument. +In this case, the events will not be reported to the calling process. +.SH RETURN VALUE +On success, +.BR spu_run () +returns the value of the +.I spu_status +register. +On error, it returns \-1 and sets +.I errno +to one of the error codes listed below. +.PP +The +.I spu_status +register value is a bit mask of status codes and +optionally a 14-bit code returned from the +.BR stop-and-signal +instruction on the SPU. +The bit masks for the status codes +are: +.TP +.B 0x02 +SPU was stopped by a +.BR stop-and-signal +instruction. +.TP +.B 0x04 +SPU was stopped by a +.BR halt +instruction. +.TP +.B 0x08 +SPU is waiting for a channel. +.TP +.B 0x10 +SPU is in single-step mode. +.TP +.B 0x20 +SPU has tried to execute an invalid instruction. +.TP +.B 0x40 +SPU has tried to access an invalid channel. +.TP +.B 0x3fff0000 +The bits masked with this value contain the code returned from a +.BR stop-and-signal +instruction. +These bits are valid only if the 0x02 bit is set. +.PP +If +.BR spu_run () +has not returned an error, one or more bits among the lower eight +ones are always set. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EFAULT +.I npc +is not a valid pointer, or +.I event +is non-NULL and an invalid pointer. +.TP +.B EINTR +A signal occurred while +.BR spu_run () +was in progress; see +.BR signal (7). +The +.I npc +value has been updated to the new program counter value if +necessary. +.TP +.B EINVAL +.I fd +is not a valid file descriptor returned from +.BR spu_create (2). +.TP +.B ENOMEM +There was not enough memory available to handle a page fault +resulting from a Memory Flow Controller (MFC) direct memory access. +.TP +.B ENOSYS +The functionality is not provided by the current system, because +either the hardware does not provide SPUs or the spufs module is not +loaded. +.SH VERSIONS +The +.BR spu_run () +system call was added to Linux in kernel 2.6.16. +.SH CONFORMING TO +This call is Linux-specific and implemented only by the PowerPC +architecture. +Programs using this system call are not portable. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +Note however, that +.BR spu_run () +is meant to be used from libraries that implement a more abstract +interface to SPUs, not to be used from regular applications. +See +.UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ +.UE +for the recommended libraries. +.SH EXAMPLE +The following is an example of running a simple, one-instruction SPU +program with the +.BR spu_run () +system call. +.PP +.EX +#include +#include +#include +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +int main(void) +{ + int context, fd, spu_status; + uint32_t instruction, npc; + + context = spu_create("/spu/example\-context", 0, 0755); + if (context == \-1) + handle_error("spu_create"); + + /* write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs + * local store memory + */ + instruction = 0x00001234; + + fd = open("/spu/example\-context/mem", O_RDWR); + if (fd == \-1) + handle_error("open"); + write(fd, &instruction, sizeof(instruction)); + + /* set npc to the starting instruction address of the + * SPU program. Since we wrote the instruction at the + * start of the mem file, the entry point will be 0x0 + */ + npc = 0; + + spu_status = spu_run(context, &npc, NULL); + if (spu_status == \-1) + handle_error("open"); + + /* we should see a status code of 0x1234002: + * 0x00000002 (spu was stopped due to stop\-and\-signal) + * | 0x12340000 (the stop\-and\-signal code) + */ + printf("SPU Status: 0x%08x\\n", spu_status); + + exit(EXIT_SUCCESS); +} +.EE +.\" .SH AUTHORS +.\" Arnd Bergmann , Jeremy Kerr +.SH SEE ALSO +.BR close (2), +.BR spu_create (2), +.BR capabilities (7), +.BR spufs (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ssetmask.2 b/man2/ssetmask.2 new file mode 100644 index 0000000..a7f99d2 --- /dev/null +++ b/man2/ssetmask.2 @@ -0,0 +1 @@ +.so man2/sgetmask.2 diff --git a/man2/stat.2 b/man2/stat.2 new file mode 100644 index 0000000..ba64ffa --- /dev/null +++ b/man2/stat.2 @@ -0,0 +1,723 @@ +'\" t +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 +.\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-05-18 by Todd Larason +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1995-01-09 by Richard Kettlewell +.\" Modified 1998-05-13 by Michael Haardt +.\" Modified 1999-07-06 by aeb & Albert Cahalan +.\" Modified 2000-01-07 by aeb +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2007-06-08 mtk: Added example program +.\" 2007-07-05 mtk: Added details on underlying system call interfaces +.\" +.TH STAT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +stat, fstat, lstat, fstatat \- get file status +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int stat(const char *" pathname ", struct stat *" statbuf ); +.BI "int fstat(int " fd ", struct stat *" statbuf ); +.BI "int lstat(const char *" pathname ", struct stat *" statbuf ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int fstatat(int " dirfd ", const char *" pathname ", struct stat *" \ +statbuf , +.BI " int " flags ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR lstat (): +.RS 4 +/* glibc 2.19 and earlier */ _BSD_SOURCE +.br + || /* Since glibc 2.20 */ _DEFAULT_SOURCE +.br + || _XOPEN_SOURCE\ >=\ 500 +.\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.br + || /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L +.RE +.PP +.BR fstatat (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.PD +.ad +.SH DESCRIPTION +.PP +These functions return information about a file, in the buffer pointed to by +.IR statbuf . +No permissions are required on the file itself, but\(emin the case of +.BR stat (), +.BR fstatat (), +and +.BR lstat ()\(emexecute +(search) permission is required on all of the directories in +.I pathname +that lead to the file. +.PP +.BR stat () +and +.BR fstatat () +retrieve information about the file pointed to by +.IR pathname ; +the differences for +.BR fstatat () +are described below. +.PP +.BR lstat () +is identical to +.BR stat (), +except that if +.I pathname +is a symbolic link, then it returns information about the link itself, +not the file that it refers to. +.PP +.BR fstat () +is identical to +.BR stat (), +except that the file about which information is to be retrieved +is specified by the file descriptor +.IR fd . +.\" +.SS The stat structure +All of these system calls return a +.I stat +structure, which contains the following fields: +.PP +.in +4n +.EX +struct stat { + dev_t st_dev; /* ID of device containing file */ + ino_t st_ino; /* Inode number */ + mode_t st_mode; /* File type and mode */ + nlink_t st_nlink; /* Number of hard links */ + uid_t st_uid; /* User ID of owner */ + gid_t st_gid; /* Group ID of owner */ + dev_t st_rdev; /* Device ID (if special file) */ + off_t st_size; /* Total size, in bytes */ + blksize_t st_blksize; /* Block size for filesystem I/O */ + blkcnt_t st_blocks; /* Number of 512B blocks allocated */ + + /* Since Linux 2.6, the kernel supports nanosecond + precision for the following timestamp fields. + For the details before Linux 2.6, see NOTES. */ + + struct timespec st_atim; /* Time of last access */ + struct timespec st_mtim; /* Time of last modification */ + struct timespec st_ctim; /* Time of last status change */ + +#define st_atime st_atim.tv_sec /* Backward compatibility */ +#define st_mtime st_mtim.tv_sec +#define st_ctime st_ctim.tv_sec +}; +.EE +.in +.PP +.IR Note : +the order of fields in the +.I stat +structure varies somewhat +across architectures. +In addition, +the definition above does not show the padding bytes +that may be present between some fields on various architectures. +Consult the glibc and kernel source code +if you need to know the details. +.PP +.\" Background: inode attributes are modified with i_mutex held, but +.\" read by stat() without taking the mutex. +.IR Note : +for performance and simplicity reasons, different fields in the +.I stat +structure may contain state information from different moments +during the execution of the system call. +For example, if +.IR st_mode +or +.IR st_uid +is changed by another process by calling +.BR chmod (2) +or +.BR chown (2), +.BR stat () +might return the old +.I st_mode +together with the new +.IR st_uid , +or the old +.I st_uid +together with the new +.IR st_mode . +.PP +The fields in the +.I stat +structure are as follows: +.TP +.I st_dev +This field describes the device on which this file resides. +(The +.BR major (3) +and +.BR minor (3) +macros may be useful to decompose the device ID in this field.) +.TP +.I st_ino +This field contains the file's inode number. +.TP +.I st_mode +This field contains the file type and mode. +See +.BR inode (7) +for further information. +.TP +.I st_nlink +This field contains the number of hard links to the file. +.TP +.I st_uid +This field contains the user ID of the owner of the file. +.TP +.I st_gid +This field contains the ID of the group owner of the file. +.TP +.I st_rdev +This field describes the device that this file (inode) represents. +.TP +.I st_size +This field gives the size of the file (if it is a regular +file or a symbolic link) in bytes. +The size of a symbolic link is the length of the pathname +it contains, without a terminating null byte. +.TP +.I st_blksize +This field gives the "preferred" block size for efficient filesystem I/O. +.TP +.I st_blocks +This field indicates the number of blocks allocated to the file, +in 512-byte units. +(This may be smaller than +.IR st_size /512 +when the file has holes.) +.TP +.I st_atime +This is the file's last access timestamp. +.TP +.I st_mtime +This is the file's last modification timestamp. +.TP +.I st_ctime +This is the file's last status change timestamp. +.PP +For further information on the above fields, see +.BR inode (7). +.\" +.SS fstatat() +The +.BR fstatat () +system call is a more general interface for accessing file information +which can still provide exactly the behavior of each of +.BR stat (), +.BR lstat (), +and +.BR fstat (). +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR stat () +and +.BR lstat () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR stat () +and +.BR lstat ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +.I flags +can either be 0, or include one or more of the following flags ORed: +.TP +.BR AT_EMPTY_PATH " (since Linux 2.6.39)" +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I pathname +is an empty string, operate on the file referred to by +.IR dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory, and +the behavior of +.BR fstatat () +is similar to that of +.BR fstat (). +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)" +Don't automount the terminal ("basename") component of +.I pathname +if it is a directory that is an automount point. +This allows the caller to gather attributes of an automount point +(rather than the location it would mount). +Since Linux 4.14, +.\" commit 42f46148217865a545e129612075f3d828a2c4e4 +also don't instantiate a nonexistent name in an +on-demand directory such as used for automounter indirect maps. +This flag can be used in tools that scan directories +to prevent mass-automounting of a directory of automount points. +The +.B AT_NO_AUTOMOUNT +flag has no effect if the mount point has already been mounted over. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +Both +.BR stat () +and +.BR lstat () +act as though +.B AT_NO_AUTOMOUNT +was set. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead return information about the link itself, like +.BR lstat (). +(By default, +.BR fstatat () +dereferences symbolic links, like +.BR stat ().) +.PP +See +.BR openat (2) +for an explanation of the need for +.BR fstatat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR pathname . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.I fd +is not a valid open file descriptor. +.TP +.B EFAULT +Bad address. +.TP +.B ELOOP +Too many symbolic links encountered while traversing the path. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A component of +.I pathname +does not exist, or +.I pathname +is an empty string and +.B AT_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOMEM +Out of memory (i.e., kernel memory). +.TP +.B ENOTDIR +A component of the path prefix of +.I pathname +is not a directory. +.TP +.B EOVERFLOW +.I pathname +or +.I fd +refers to a file whose size, inode number, +or number of blocks cannot be represented in, respectively, the types +.IR off_t , +.IR ino_t , +or +.IR blkcnt_t . +This error can occur when, for example, +an application compiled on a 32-bit platform without +.I -D_FILE_OFFSET_BITS=64 +calls +.BR stat () +on a file whose size exceeds +.I (1<<31)-1 +bytes. +.PP +The following additional errors can occur for +.BR fstatat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR fstatat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR stat (), +.BR fstat (), +.BR lstat (): +SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008. +.\" SVr4 documents additional +.\" .BR fstat () +.\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4 +.\" documents additional +.\" .BR stat () +.\" and +.\" .BR lstat () +.\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW. +.PP +.BR fstatat (): +POSIX.1-2008. +.PP +According to POSIX.1-2001, +.BR lstat () +on a symbolic link need return valid information only in the +.I st_size +field and the file type of the +.IR st_mode +field of the +.IR stat +structure. +POSIX.1-2008 tightens the specification, requiring +.BR lstat () +to return valid information in all fields except the mode bits in +.IR st_mode . +.PP +Use of the +.I st_blocks +and +.I st_blksize +fields may be less portable. +(They were introduced in BSD. +The interpretation differs between systems, +and possibly on a single system when NFS mounts are involved.) +.SH NOTES +.SS Timestamp fields +Older kernels and older standards did not support nanosecond timestamp +fields. +Instead, there were three timestamp +.RI fields\(em st_atime , +.IR st_mtime , +and +.IR st_ctime \(emtyped +as +.IR time_t +that recorded timestamps with one-second precision. +.PP +Since kernel 2.5.48, the +.I stat +structure supports nanosecond resolution for the three file timestamp fields. +The nanosecond components of each timestamp are available +via names of the form +.IR st_atim.tv_nsec , +if suitable feature test macros are defined. +Nanosecond timestamps were standardized in POSIX.1-2008, +and, starting with version 2.12, +glibc exposes the nanosecond component names if +.BR _POSIX_C_SOURCE +is defined with the value 200809L or greater, or +.BR _XOPEN_SOURCE +is defined with the value 700 or greater. +Up to and including glibc 2.19, +the definitions of the nanoseconds components are also defined if +.B _BSD_SOURCE +or +.B _SVID_SOURCE +is defined. +If none of the aforementioned macros are defined, +then the nanosecond values are exposed with names of the form +.IR st_atimensec . +.\" +.SS C library/kernel differences +Over time, increases in the size of the +.I stat +structure have led to three successive versions of +.BR stat (): +.IR sys_stat () +(slot +.IR __NR_oldstat ), +.IR sys_newstat () +(slot +.IR __NR_stat ), +and +.I sys_stat64() +(slot +.IR __NR_stat64 ) +on 32-bit platforms such as i386. +The first two versions were already present in Linux 1.0 +(albeit with different names); +.\" See include/asm-i386/stat.h in the Linux 2.4 source code for the +.\" various versions of the structure definitions +the last was added in Linux 2.4. +Similar remarks apply for +.BR fstat () +and +.BR lstat (). +.PP +The kernel-internal versions of the +.I stat +structure dealt with by the different versions are, respectively: +.TP +.IR __old_kernel_stat +The original structure, with rather narrow fields, and no padding. +.TP +.IR stat +Larger +.I st_ino +field and padding added to various parts of the structure to +allow for future expansion. +.TP +.IR stat64 +Even larger +.I st_ino +field, +larger +.I st_uid +and +.I st_gid +fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits, +and various other enlarged fields and further padding in the structure. +(Various padding bytes were eventually consumed in Linux 2.6, +with the advent of 32-bit device IDs and nanosecond components +for the timestamp fields.) +.PP +The glibc +.BR stat () +wrapper function hides these details from applications, +invoking the most recent version of the system call provided by the kernel, +and repacking the returned information if required for old binaries. +.\" +.\" A note from Andries Brouwer, July 2007 +.\" +.\" > Is the story not rather more complicated for some calls like +.\" > stat(2)? +.\" +.\" Yes and no, mostly no. See /usr/include/sys/stat.h . +.\" +.\" The idea is here not so much that syscalls change, but that +.\" the definitions of struct stat and of the types dev_t and mode_t change. +.\" This means that libc (even if it does not call the kernel +.\" but only calls some internal function) must know what the +.\" format of dev_t or of struct stat is. +.\" The communication between the application and libc goes via +.\" the include file that defines a _STAT_VER and +.\" _MKNOD_VER describing the layout of the data that user space +.\" uses. Each (almost each) occurrence of stat() is replaced by +.\" an occurrence of xstat() where the first parameter of xstat() +.\" is this version number _STAT_VER. +.\" +.\" Now, also the definitions used by the kernel change. +.\" But glibc copes with this in the standard way, and the +.\" struct stat as returned by the kernel is repacked into +.\" the struct stat as expected by the application. +.\" Thus, _STAT_VER and this setup cater for the application-libc +.\" interface, rather than the libc-kernel interface. +.\" +.\" (Note that the details depend on gcc being used as c compiler.) +.PP +On modern 64-bit systems, life is simpler: there is a single +.BR stat () +system call and the kernel deals with a +.I stat +structure that contains fields of a sufficient size. +.PP +The underlying system call employed by the glibc +.BR fstatat () +wrapper function is actually called +.BR fstatat64 () +or, on some architectures, +.\" strace(1) shows the name "newfstatat" on x86-64 +.BR newfstatat (). +.SH EXAMPLE +The following program calls +.BR lstat () +and displays selected fields in the returned +.I stat +structure. +.PP +.EX +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct stat sb; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + if (lstat(argv[1], &sb) == \-1) { + perror("lstat"); + exit(EXIT_FAILURE); + } + + printf("ID of containing device: [%lx,%lx]\\n", + (long) major(sb.st_dev), (long) minor(sb.st_dev)); + + printf("File type: "); + + switch (sb.st_mode & S_IFMT) { + case S_IFBLK: printf("block device\\n"); break; + case S_IFCHR: printf("character device\\n"); break; + case S_IFDIR: printf("directory\\n"); break; + case S_IFIFO: printf("FIFO/pipe\\n"); break; + case S_IFLNK: printf("symlink\\n"); break; + case S_IFREG: printf("regular file\\n"); break; + case S_IFSOCK: printf("socket\\n"); break; + default: printf("unknown?\\n"); break; + } + + printf("I\-node number: %ld\\n", (long) sb.st_ino); + + printf("Mode: %lo (octal)\\n", + (unsigned long) sb.st_mode); + + printf("Link count: %ld\\n", (long) sb.st_nlink); + printf("Ownership: UID=%ld GID=%ld\\n", + (long) sb.st_uid, (long) sb.st_gid); + + printf("Preferred I/O block size: %ld bytes\\n", + (long) sb.st_blksize); + printf("File size: %lld bytes\\n", + (long long) sb.st_size); + printf("Blocks allocated: %lld\\n", + (long long) sb.st_blocks); + + printf("Last status change: %s", ctime(&sb.st_ctime)); + printf("Last file access: %s", ctime(&sb.st_atime)); + printf("Last file modification: %s", ctime(&sb.st_mtime)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ls (1), +.BR stat (1), +.BR access (2), +.BR chmod (2), +.BR chown (2), +.BR readlink (2), +.BR utime (2), +.BR capabilities (7), +.BR inode (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/stat64.2 b/man2/stat64.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man2/stat64.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man2/statfs.2 b/man2/statfs.2 new file mode 100644 index 0000000..a8ebeb7 --- /dev/null +++ b/man2/statfs.2 @@ -0,0 +1,400 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 2003-08-17 by Walter Harms +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH STATFS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +statfs, fstatfs \- get filesystem statistics +.SH SYNOPSIS +.BR "#include " "/* or */" +.PP +.BI "int statfs(const char *" path ", struct statfs *" buf ); +.br +.BI "int fstatfs(int " fd ", struct statfs *" buf ); +.SH DESCRIPTION +The +.BR statfs () +system call returns information about a mounted filesystem. +.I path +is the pathname of any file within the mounted filesystem. +.I buf +is a pointer to a +.I statfs +structure defined approximately as follows: +.PP +.in +4n +.EX +struct statfs { + __fsword_t f_type; /* Type of filesystem (see below) */ + __fsword_t f_bsize; /* Optimal transfer block size */ + fsblkcnt_t f_blocks; /* Total data blocks in filesystem */ + fsblkcnt_t f_bfree; /* Free blocks in filesystem */ + fsblkcnt_t f_bavail; /* Free blocks available to + unprivileged user */ + fsfilcnt_t f_files; /* Total file nodes in filesystem */ + fsfilcnt_t f_ffree; /* Free file nodes in filesystem */ + fsid_t f_fsid; /* Filesystem ID */ + __fsword_t f_namelen; /* Maximum length of filenames */ + __fsword_t f_frsize; /* Fragment size (since Linux 2.6) */ + __fsword_t f_flags; /* Mount flags of filesystem + (since Linux 2.6.36) */ + __fsword_t f_spare[xxx]; + /* Padding bytes reserved for future use */ +}; +.EE +.in +.PP +The following filesystem types may appear in +.IR f_type : +.PP +.in +4n +.EX +ADFS_SUPER_MAGIC 0xadf5 +AFFS_SUPER_MAGIC 0xadff +AFS_SUPER_MAGIC 0x5346414f +ANON_INODE_FS_MAGIC 0x09041934 /* Anonymous inode FS (for + pseudofiles that have no name; + e.g., epoll, signalfd, bpf) */ +AUTOFS_SUPER_MAGIC 0x0187 +BDEVFS_MAGIC 0x62646576 +BEFS_SUPER_MAGIC 0x42465331 +BFS_MAGIC 0x1badface +BINFMTFS_MAGIC 0x42494e4d +BPF_FS_MAGIC 0xcafe4a11 +BTRFS_SUPER_MAGIC 0x9123683e +BTRFS_TEST_MAGIC 0x73727279 +CGROUP_SUPER_MAGIC 0x27e0eb /* Cgroup pseudo FS */ +CGROUP2_SUPER_MAGIC 0x63677270 /* Cgroup v2 pseudo FS */ +CIFS_MAGIC_NUMBER 0xff534d42 +CODA_SUPER_MAGIC 0x73757245 +COH_SUPER_MAGIC 0x012ff7b7 +CRAMFS_MAGIC 0x28cd3d45 +DEBUGFS_MAGIC 0x64626720 +DEVFS_SUPER_MAGIC 0x1373 /* Linux 2.6.17 and earlier */ +DEVPTS_SUPER_MAGIC 0x1cd1 +ECRYPTFS_SUPER_MAGIC 0xf15f +EFIVARFS_MAGIC 0xde5e81e4 +EFS_SUPER_MAGIC 0x00414a53 +EXT_SUPER_MAGIC 0x137d /* Linux 2.0 and earlier */ +EXT2_OLD_SUPER_MAGIC 0xef51 +EXT2_SUPER_MAGIC 0xef53 +EXT3_SUPER_MAGIC 0xef53 +EXT4_SUPER_MAGIC 0xef53 +F2FS_SUPER_MAGIC 0xf2f52010 +FUSE_SUPER_MAGIC 0x65735546 +FUTEXFS_SUPER_MAGIC 0xbad1dea /* Unused */ +HFS_SUPER_MAGIC 0x4244 +HOSTFS_SUPER_MAGIC 0x00c0ffee +HPFS_SUPER_MAGIC 0xf995e849 +HUGETLBFS_MAGIC 0x958458f6 +ISOFS_SUPER_MAGIC 0x9660 +JFFS2_SUPER_MAGIC 0x72b6 +JFS_SUPER_MAGIC 0x3153464a +MINIX_SUPER_MAGIC 0x137f /* original minix FS */ +MINIX_SUPER_MAGIC2 0x138f /* 30 char minix FS */ +MINIX2_SUPER_MAGIC 0x2468 /* minix V2 FS */ +MINIX2_SUPER_MAGIC2 0x2478 /* minix V2 FS, 30 char names */ +MINIX3_SUPER_MAGIC 0x4d5a /* minix V3 FS, 60 char names */ +MQUEUE_MAGIC 0x19800202 /* POSIX message queue FS */ +MSDOS_SUPER_MAGIC 0x4d44 +MTD_INODE_FS_MAGIC 0x11307854 +NCP_SUPER_MAGIC 0x564c +NFS_SUPER_MAGIC 0x6969 +NILFS_SUPER_MAGIC 0x3434 +NSFS_MAGIC 0x6e736673 +NTFS_SB_MAGIC 0x5346544e +OCFS2_SUPER_MAGIC 0x7461636f +OPENPROM_SUPER_MAGIC 0x9fa1 +OVERLAYFS_SUPER_MAGIC 0x794c7630 +PIPEFS_MAGIC 0x50495045 +PROC_SUPER_MAGIC 0x9fa0 /* /proc FS */ +PSTOREFS_MAGIC 0x6165676c +QNX4_SUPER_MAGIC 0x002f +QNX6_SUPER_MAGIC 0x68191122 +RAMFS_MAGIC 0x858458f6 +REISERFS_SUPER_MAGIC 0x52654973 +ROMFS_MAGIC 0x7275 +SECURITYFS_MAGIC 0x73636673 +SELINUX_MAGIC 0xf97cff8c +SMACK_MAGIC 0x43415d53 +SMB_SUPER_MAGIC 0x517b +SOCKFS_MAGIC 0x534f434b +SQUASHFS_MAGIC 0x73717368 +SYSFS_MAGIC 0x62656572 +SYSV2_SUPER_MAGIC 0x012ff7b6 +SYSV4_SUPER_MAGIC 0x012ff7b5 +TMPFS_MAGIC 0x01021994 +TRACEFS_MAGIC 0x74726163 +UDF_SUPER_MAGIC 0x15013346 +UFS_MAGIC 0x00011954 +USBDEVICE_SUPER_MAGIC 0x9fa2 +V9FS_MAGIC 0x01021997 +VXFS_SUPER_MAGIC 0xa501fcf5 +XENFS_SUPER_MAGIC 0xabba1974 +XENIX_SUPER_MAGIC 0x012ff7b4 +XFS_SUPER_MAGIC 0x58465342 +_XIAFS_SUPER_MAGIC 0x012fd16d /* Linux 2.0 and earlier */ +.EE +.in +.PP +Most of these MAGIC constants are defined in +.IR /usr/include/linux/magic.h , +and some are hardcoded in kernel sources. +.PP +The +.IR f_flags +field is a bit mask indicating mount options for the filesystem. +It contains zero or more of the following bits: +.\" XXX Keep this list in sync with statvfs(3) +.TP +.B ST_MANDLOCK +Mandatory locking is permitted on the filesystem (see +.BR fcntl (2)). +.TP +.B ST_NOATIME +Do not update access times; see +.BR mount (2). +.TP +.B ST_NODEV +Disallow access to device special files on this filesystem. +.TP +.B ST_NODIRATIME +Do not update directory access times; see +.BR mount (2). +.TP +.B ST_NOEXEC +Execution of programs is disallowed on this filesystem. +.TP +.B ST_NOSUID +The set-user-ID and set-group-ID bits are ignored by +.BR exec (3) +for executable files on this filesystem +.TP +.B ST_RDONLY +This filesystem is mounted read-only. +.TP +.B ST_RELATIME +Update atime relative to mtime/ctime; see +.BR mount (2). +.TP +.B ST_SYNCHRONOUS +Writes are synched to the filesystem immediately (see the description of +.B O_SYNC +in +.BR open (2)). +.PP +Nobody knows what +.I f_fsid +is supposed to contain (but see below). +.PP +Fields that are undefined for a particular filesystem are set to 0. +.PP +.BR fstatfs () +returns the same information about an open file referenced by descriptor +.IR fd . +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +.RB ( statfs ()) +Search permission is denied for a component of the path prefix of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( fstatfs ()) +.I fd +is not a valid open file descriptor. +.TP +.B EFAULT +.I buf +or +.I path +points to an invalid address. +.TP +.B EINTR +The call was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +.RB ( statfs ()) +Too many symbolic links were encountered in translating +.IR path . +.TP +.B ENAMETOOLONG +.RB ( statfs ()) +.I path +is too long. +.TP +.B ENOENT +.RB ( statfs ()) +The file referred to by +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSYS +The filesystem does not support this call. +.TP +.B ENOTDIR +.RB ( statfs ()) +A component of the path prefix of +.I path +is not a directory. +.TP +.B EOVERFLOW +Some values were too large to be represented in the returned struct. +.SH CONFORMING TO +Linux-specific. +The Linux +.BR statfs () +was inspired by the 4.4BSD one +(but they do not use the same structure). +.SH NOTES +The +.I __fsword_t +type used for various fields in the +.I statfs +structure definition is a glibc internal type, +not intended for public use. +This leaves the programmer in a bit of a conundrum when trying to copy +or compare these fields to local variables in a program. +Using +.I "unsigned\ int" +for such variables suffices on most systems. +.PP +The original Linux +.BR statfs () +and +.BR fstatfs () +system calls were not designed with extremely large file sizes in mind. +Subsequently, Linux 2.6 +added new +.BR statfs64 () +and +.BR fstatfs64 () +system calls that employ a new structure, +.IR statfs64 . +The new structure contains the same fields as the original +.I statfs +structure, but the sizes of various fields are increased, +to accommodate large file sizes. +The glibc +.BR statfs () +and +.BR fstatfs () +wrapper functions transparently deal with the kernel differences. +.PP +Some systems have only \fI\fP, other systems also have +\fI\fP, where the former includes the latter. +So it seems +including the former is the best choice. +.PP +LSB has deprecated the library calls +.BR statfs () +and +.BR fstatfs () +and tells us to use +.BR statvfs (2) +and +.BR fstatvfs (2) +instead. +.SS The f_fsid field +Solaris, Irix and POSIX have a system call +.BR statvfs (2) +that returns a +.I "struct statvfs" +(defined in +.IR ) +containing an +.I "unsigned long" +.IR f_fsid . +Linux, SunOS, HP-UX, 4.4BSD have a system call +.BR statfs () +that returns a +.I "struct statfs" +(defined in +.IR ) +containing a +.I fsid_t +.IR f_fsid , +where +.I fsid_t +is defined as +.IR "struct { int val[2]; }" . +The same holds for FreeBSD, except that it uses the include file +.IR . +.PP +The general idea is that +.I f_fsid +contains some random stuff such that the pair +.RI ( f_fsid , ino ) +uniquely determines a file. +Some operating systems use (a variation on) the device number, +or the device number combined with the filesystem type. +Several operating systems restrict giving out the +.I f_fsid +field to the superuser only (and zero it for unprivileged users), +because this field is used in the filehandle of the filesystem +when NFS-exported, and giving it out is a security concern. +.PP +Under some operating systems, the +.I fsid +can be used as the second argument to the +.BR sysfs (2) +system call. +.SH BUGS +From Linux 2.6.38 up to and including Linux 3.1, +.\" broken in commit ff0c7d15f9787b7e8c601533c015295cc68329f8 +.\" fixed in commit d70ef97baf048412c395bb5d65791d8fe133a52b +.BR fstatfs () +failed with the error +.B ENOSYS +for file descriptors created by +.BR pipe (2). +.SH SEE ALSO +.BR stat (2), +.BR statvfs (3), +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/statfs64.2 b/man2/statfs64.2 new file mode 100644 index 0000000..923d3c0 --- /dev/null +++ b/man2/statfs64.2 @@ -0,0 +1 @@ +.so man2/statfs.2 diff --git a/man2/statvfs.2 b/man2/statvfs.2 new file mode 100644 index 0000000..adec9dd --- /dev/null +++ b/man2/statvfs.2 @@ -0,0 +1 @@ +.so man3/statvfs.3 diff --git a/man2/statx.2 b/man2/statx.2 new file mode 100644 index 0000000..bb04455 --- /dev/null +++ b/man2/statx.2 @@ -0,0 +1,557 @@ +'\" t +.\" Copyright (c) 2017 David Howells +.\" +.\" Derived from the stat.2 manual page: +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 +.\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH STATX 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +statx \- get file status (extended) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.BR "#include " "/* Definition of AT_* constants */" +.PP +.BI "int statx(int " dirfd ", const char *" pathname ", int " flags "," +.BI " unsigned int " mask ", struct statx *" statxbuf ); +.fi +.PP +.IR Note : +There is no glibc wrapper for +.BR statx (); +see NOTES. +.SH DESCRIPTION +.PP +This function returns information about a file, storing it in the buffer +pointed to by +.IR statxbuf . +The returned buffer is a structure of the following type: +.PP +.in +4n +.EX +struct statx { + __u32 stx_mask; /* Mask of bits indicating + filled fields */ + __u32 stx_blksize; /* Block size for filesystem I/O */ + __u64 stx_attributes; /* Extra file attribute indicators */ + __u32 stx_nlink; /* Number of hard links */ + __u32 stx_uid; /* User ID of owner */ + __u32 stx_gid; /* Group ID of owner */ + __u16 stx_mode; /* File type and mode */ + __u64 stx_ino; /* Inode number */ + __u64 stx_size; /* Total size in bytes */ + __u64 stx_blocks; /* Number of 512B blocks allocated */ + __u64 stx_attributes_mask; + /* Mask to show what's supported + in stx_attributes */ + + /* The following fields are file timestamps */ + struct statx_timestamp stx_atime; /* Last access */ + struct statx_timestamp stx_btime; /* Creation */ + struct statx_timestamp stx_ctime; /* Last status change */ + struct statx_timestamp stx_mtime; /* Last modification */ + + /* If this file represents a device, then the next two + fields contain the ID of the device */ + __u32 stx_rdev_major; /* Major ID */ + __u32 stx_rdev_minor; /* Minor ID */ + + /* The next two fields contain the ID of the device + containing the filesystem where the file resides */ + __u32 stx_dev_major; /* Major ID */ + __u32 stx_dev_minor; /* Minor ID */ +}; +.EE +.in +.PP +The file timestamps are structures of the following type: +.PP +.in +4n +.EX +struct statx_timestamp { + __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */ + __u32 tv_nsec; /* Nanoseconds since tv_sec */ +}; +.EE +.in +.PP +(Note that reserved space and padding is omitted.) +.SS +Invoking \fBstatx\fR(): +.PP +To access a file's status, no permissions are required on the file itself, +but in the case of +.BR statx () +with a pathname, +execute (search) permission is required on all of the directories in +.I pathname +that lead to the file. +.PP +.BR statx () +uses +.IR pathname , +.IR dirfd , +and +.IR flags +to identify the target file in one of the following ways: +.TP +An absolute pathname +If +.I pathname +begins with a slash, +then it is an absolute pathname that identifies the target file. +In this case, +.I dirfd +is ignored. +.TP +A relative pathname +If +.I pathname +is a string that begins with a character other than a slash and +.IR dirfd +is +.BR AT_FDCWD , +then +.I pathname +is a relative pathname that is interpreted relative to the process's +current working directory. +.TP +A directory-relative pathname +If +.I pathname +is a string that begins with a character other than a slash and +.I dirfd +is a file descriptor that refers to a directory, then +.I pathname +is a relative pathname that is interpreted relative to the directory +referred to by +.IR dirfd . +.TP +By file descriptor +If +.IR pathname +is an empty string and the +.B AT_EMPTY_PATH +flag is specified in +.IR flags +(see below), +then the target file is the one referred to by the file descriptor +.IR dirfd . +.PP +.I flags +can be used to influence a pathname-based lookup. +A value for +.I flags +is constructed by ORing together zero or more of the following constants: +.TP +.BR AT_EMPTY_PATH +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I pathname +is an empty string, operate on the file referred to by +.IR dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +.IP +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +.IP +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.BR AT_NO_AUTOMOUNT +Don't automount the terminal ("basename") component of +.I pathname +if it is a directory that is an automount point. +This allows the caller to gather attributes of an automount point +(rather than the location it would mount). +This flag can be used in tools that scan directories +to prevent mass-automounting of a directory of automount points. +The +.B AT_NO_AUTOMOUNT +flag has no effect if the mount point has already been mounted over. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead return information about the link itself, like +.BR lstat (2). +.PP +.I flags +can also be used to control what sort of synchronization the kernel will do +when querying a file on a remote filesystem. +This is done by ORing in one of the following values: +.TP +.B AT_STATX_SYNC_AS_STAT +Do whatever +.BR stat (2) +does. +This is the default and is very much filesystem-specific. +.TP +.B AT_STATX_FORCE_SYNC +Force the attributes to be synchronized with the server. +This may require that +a network filesystem perform a data writeback to get the timestamps correct. +.TP +.B AT_STATX_DONT_SYNC +Don't synchronize anything, but rather just take whatever +the system has cached if possible. +This may mean that the information returned is approximate, but, +on a network filesystem, it may not involve a round trip to the server - even +if no lease is held. +.PP +The +.I mask +argument to +.BR statx () +is used to tell the kernel which fields the caller is interested in. +.I mask +is an ORed combination of the following constants: +.PP +.in +4n +.TS +lB l. +STATX_TYPE Want stx_mode & S_IFMT +STATX_MODE Want stx_mode & ~S_IFMT +STATX_NLINK Want stx_nlink +STATX_UID Want stx_uid +STATX_GID Want stx_gid +STATX_ATIME Want stx_atime +STATX_MTIME Want stx_mtime +STATX_CTIME Want stx_ctime +STATX_INO Want stx_ino +STATX_SIZE Want stx_size +STATX_BLOCKS Want stx_blocks +STATX_BASIC_STATS [All of the above] +STATX_BTIME Want stx_btime +STATX_ALL [All currently available fields] +.TE +.in +.PP +Note that the kernel does +.I not +reject values in +.I mask +other than the above. +Instead, it simply informs the caller which values are supported +by this kernel and filesystem via the +.I statx.stx_mask +field. +Therefore, +.I "do not" +simply set +.I mask +to +.B UINT_MAX +(all bits set), +as one or more bits may, in the future, be used to specify an +extension to the buffer. +.SS +The returned information +.PP +The status information for the target file is returned in the +.I statx +structure pointed to by +.IR statxbuf . +Included in this is +.I stx_mask +which indicates what other information has been returned. +.I stx_mask +has the same format as the +.I mask +argument and bits are set in it to indicate +which fields have been filled in. +.PP +It should be noted that the kernel may return fields that weren't +requested and may fail to return fields that were requested, +depending on what the backing filesystem supports. +(Fields that are given values despite being unrequested can just be ignored.) +In either case, +.I stx_mask +will not be equal +.IR mask . +.PP +If a filesystem does not support a field or if it has +an unrepresentable value (for instance, a file with an exotic type), +then the mask bit corresponding to that field will be cleared in +.I stx_mask +even if the user asked for it and a dummy value will be filled in for +compatibility purposes if one is available (e.g., a dummy UID and GID may be +specified to mount under some circumstances). +.PP +A filesystem may also fill in fields that the caller didn't ask for if it has +values for them available and the information is available at no extra cost. +If this happens, the corresponding bits will be set in +.IR stx_mask . +.PP +.\" Background: inode attributes are modified with i_mutex held, but +.\" read by stat() without taking the mutex. +.IR Note : +for performance and simplicity reasons, different fields in the +.I statx +structure may contain state information from different moments +during the execution of the system call. +For example, if +.IR stx_mode +or +.IR stx_uid +is changed by another process by calling +.BR chmod (2) +or +.BR chown (2), +.BR stat () +might return the old +.I stx_mode +together with the new +.IR stx_uid , +or the old +.I stx_uid +together with the new +.IR stx_mode . +.PP +Apart from +.I stx_mask +(which is described above), the fields in the +.I statx +structure are: +.TP +.I stx_blksize +The "preferred" block size for efficient filesystem I/O. +(Writing to a file in +smaller chunks may cause an inefficient read-modify-rewrite.) +.TP +.I stx_attributes +Further status information about the file (see below for more information). +.TP +.I stx_nlink +The number of hard links on a file. +.TP +.I stx_uid +This field contains the user ID of the owner of the file. +.TP +.I stx_gid +This field contains the ID of the group owner of the file. +.TP +.I stx_mode +The file type and mode. +See +.BR inode (7) +for details. +.TP +.I stx_ino +The inode number of the file. +.TP +.I stx_size +The size of the file (if it is a regular file or a symbolic link) in bytes. +The size of a symbolic link is the length of the pathname it contains, +without a terminating null byte. +.TP +.I stx_blocks +The number of blocks allocated to the file on the medium, in 512-byte units. +(This may be smaller than +.IR stx_size /512 +when the file has holes.) +.TP +.I stx_attributes_mask +A mask indicating which bits in +.IR stx_attributes +are supported by the VFS and the filesystem. +.TP +.I stx_atime +The file's last access timestamp. +.TP +.I stx_btime +The file's creation timestamp. +.TP +.I stx_ctime +The file's last status change timestamp. +.TP +.I stx_mtime +The file's last modification timestamp. +.TP +.IR stx_dev_major " and " stx_dev_minor +The device on which this file (inode) resides. +.TP +.IR stx_rdev_major " and " stx_rdev_minor +The device that this file (inode) represents if the file is of block or +character device type. +.PP +For further information on the above fields, see +.BR inode (7). +.\" +.SS File attributes +.PP +The +.I stx_attributes +field contains a set of ORed flags that indicate additional attributes +of the file. +Note that any attribute that is not indicated as supported by +.I stx_attributes_mask +has no usable value here. +The bits in +.I stx_attributes_mask +correspond bit-by-bit to +.IR stx_attributes . +.PP +The flags are as follows: +.TP +.B STATX_ATTR_COMPRESSED +The file is compressed by the filesystem and may take extra resources +to access. +.TP +.B STATX_ATTR_IMMUTABLE +The file cannot be modified: it cannot be deleted or renamed, +no hard links can be created to this file and no data can be written to it. +See +.BR chattr (1). +.TP +.B STATX_ATTR_APPEND +The file can only be opened in append mode for writing. +Random access writing +is not permitted. +See +.BR chattr (1). +.TP +.B STATX_ATTR_NODUMP +File is not a candidate for backup when a backup program such as +.BR dump (8) +is run. +See +.BR chattr (1). +.TP +.B STATX_ATTR_ENCRYPTED +A key is required for the file to be encrypted by the filesystem. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR pathname . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.I dirfd +is not a valid open file descriptor. +.TP +.B EFAULT +.I pathname +or +.I statxbuf +is NULL or points to a location outside the process's +accessible address space. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B EINVAL +Reserved flag specified in +.IR mask . +.TP +.B ELOOP +Too many symbolic links encountered while traversing the pathname. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A component of +.I pathname +does not exist, or +.I pathname +is an empty string and +.B AT_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOMEM +Out of memory (i.e., kernel memory). +.TP +.B ENOTDIR +A component of the path prefix of +.I pathname +is not a directory or +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR statx () +was added to Linux in kernel 4.11. +.SH CONFORMING TO +.BR statx () +is Linux-specific. +.SH NOTES +Glibc does not (yet) provide a wrapper for the +.BR statx () +system call; call it using +.BR syscall (2). +.SH SEE ALSO +.BR ls (1), +.BR stat (1), +.BR access (2), +.BR chmod (2), +.BR chown (2), +.BR readlink (2), +.BR stat (2), +.BR utime (2), +.BR capabilities (7), +.BR inode (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/stime.2 b/man2/stime.2 new file mode 100644 index 0000000..707cc88 --- /dev/null +++ b/man2/stime.2 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 2001-03-16 by Andries Brouwer +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH STIME 2 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +stime \- set time +.SH SYNOPSIS +.B #include +.PP +.BI "int stime(const time_t *" t ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR stime (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +.BR stime () +sets the system's idea of the time and date. +The time, pointed +to by \fIt\fP, is measured in seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.BR stime () +may be executed only by the superuser. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Error in getting information from user space. +.TP +.B EPERM +The calling process has insufficient privilege. +Under Linux, the +.B CAP_SYS_TIME +privilege is required. +.SH CONFORMING TO +SVr4. +.SH SEE ALSO +.BR date (1), +.BR settimeofday (2), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/stty.2 b/man2/stty.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/stty.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/subpage_prot.2 b/man2/subpage_prot.2 new file mode 100644 index 0000000..bd1bd38 --- /dev/null +++ b/man2/subpage_prot.2 @@ -0,0 +1,142 @@ +.\" Copyright (c) 2010 Michael Kerrisk +.\" based on a proposal from Stephan Mueller +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume +.\" no responsibility for errors or omissions, or for damages resulting +.\" from the use of the information contained herein. The author(s) may +.\" not have taken the same level of care in the production of this +.\" manual, which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Various pieces of text taken from the kernel source and the commentary +.\" in kernel commit fa28237cfcc5827553044cbd6ee52e33692b0faa +.\" both written by Paul Mackerras +.\" +.TH SUBPAGE_PROT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +subpage_prot \- define a subpage protection for an address range +.SH SYNOPSIS +.nf +.BI "long subpage_prot(unsigned long " addr ", unsigned long " len , +.BI " uint32_t *" map "); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The PowerPC-specific +.BR subpage_prot () +system call provides the facility to control the access +permissions on individual 4\ kB subpages on systems configured with +a page size of 64\ kB. +.PP +The protection map is applied to the memory pages in the region starting at +.I addr +and continuing for +.I len +bytes. +Both of these arguments must be aligned to a 64-kB boundary. +.PP +The protection map is specified in the buffer pointed to by +.IR map . +The map has 2 bits per 4\ kB subpage; +thus each 32-bit word specifies the protections of 16 4\ kB subpages +inside a 64\ kB page +(so, the number of 32-bit words pointed to by +.I map +should equate to the number of 64-kB pages specified by +.IR len ). +Each 2-bit field in the protection map is either 0 to allow any access, +1 to prevent writes, or 2 or 3 to prevent all accesses. +.SH RETURN VALUE +On success, +.BR subpage_prot () +returns 0. +Otherwise, one of the error codes specified below is returned. +.SH ERRORS +.TP +.B EFAULT +The buffer referred to by +.I map +is not accessible. +.TP +.B EINVAL +The +.I addr +or +.I len +arguments are incorrect. +Both of these arguments must be aligned to a multiple of the system page size, +and they must not refer to a region outside of the +address space of the process or to a region that consists of huge pages. +.TP +.B ENOMEM +Out of memory. +.SH VERSIONS +This system call is provided on the PowerPC architecture +since Linux 2.6.25. +The system call is provided only if the kernel is configured with +.BR CONFIG_PPC_64K_PAGES . +No library support is provided. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.PP +Normal page protections (at the 64-kB page level) also apply; +the subpage protection mechanism is an additional constraint, +so putting 0 in a 2-bit field won't allow writes to a page that is otherwise +write-protected. +.SS Rationale +This system call is provided to assist writing emulators that +operate using 64-kB pages on PowerPC systems. +When emulating systems such as x86, which uses a smaller page size, +the emulator can no longer use the memory-management unit (MMU) +and normal system calls for controlling page protections. +(The emulator could emulate the MMU by checking and possibly remapping +the address for each memory access in software, but that is slow.) +The idea is that the emulator supplies an array of protection masks +to apply to a specified range of virtual addresses. +These masks are applied at the level where hardware page-table entries (PTEs) +are inserted into the hardware page table based on the Linux PTEs, +so the Linux PTEs are not affected. +Implicit in this is that the regions of the address space that are +protected are switched to use 4-kB hardware pages rather than 64-kB +hardware pages (on machines with hardware 64-kB page support). +.\" In the initial implementation, it was the case that: +.\" In fact the whole process is switched to use 4 kB hardware pages when the +.\" subpage_prot system call is used, but this could be improved in future +.\" to switch only the affected segments. +.\" But Paul Mackerass says (Oct 2010): I'm pretty sure we now only switch +.\" the affected segment, not the whole process. +.SH SEE ALSO +.BR mprotect (2), +.BR syscall (2) +.PP +.IR Documentation/vm/hugetlbpage.txt +in the Linux kernel source tree +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/swapoff.2 b/man2/swapoff.2 new file mode 100644 index 0000000..2bd424c --- /dev/null +++ b/man2/swapoff.2 @@ -0,0 +1 @@ +.so man2/swapon.2 diff --git a/man2/swapon.2 b/man2/swapon.2 new file mode 100644 index 0000000..adb9823 --- /dev/null +++ b/man2/swapon.2 @@ -0,0 +1,217 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-07-22 by Michael Chastain +.\" Modified 1995-07-23 by aeb +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998-09-08 by aeb +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2004-10-10 by aeb +.\" 2004-12-14 mtk, Anand Kumria: added new errors +.\" 2007-06-22 Ivana Varekova , mtk +.\" Update text describing limit on number of swap files. +.\" +.\" FIXME Linux 3.11 added SWAP_FLAG_DISCARD_ONCE and SWAP_FLAG_DISCARD_PAGES +.\" commit dcf6b7ddd7df8965727746f89c59229b23180e5a +.\" Author: Rafael Aquini +.\" Date: Wed Jul 3 15:02:46 2013 -0700 +.\" +.TH SWAPON 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +swapon, swapoff \- start/stop swapping to file/device +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int swapon(const char *" path ", int " swapflags ); +.br +.BI "int swapoff(const char *" path ); +.SH DESCRIPTION +.BR swapon () +sets the swap area to the file or block device specified by +.IR path . +.BR swapoff () +stops swapping to the file or block device specified by +.IR path . +.PP +If the +.B SWAP_FLAG_PREFER +flag is specified in the +.BR swapon () +.I swapflags +argument, the new swap area will have a higher priority than default. +The priority is encoded within +.I swapflags +as: +.PP +.in +4n +.EX +.I "(prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK" +.EE +.in +.PP +If the +.B SWAP_FLAG_DISCARD +flag is specified in the +.BR swapon () +.I swapflags +argument, freed swap pages will be discarded before they are reused, +if the swap device supports the discard or trim operation. +(This may improve performance on some Solid State Devices, +but often it does not.) +See also NOTES. +.PP +These functions may be used only by a privileged process (one having the +.B CAP_SYS_ADMIN +capability). +.SS Priority +Each swap area has a priority, either high or low. +The default priority is low. +Within the low-priority areas, +newer areas are even lower priority than older areas. +.PP +All priorities set with +.I swapflags +are high-priority, higher than default. +They may have any nonnegative value chosen by the caller. +Higher numbers mean higher priority. +.PP +Swap pages are allocated from areas in priority order, +highest priority first. +For areas with different priorities, +a higher-priority area is exhausted before using a lower-priority area. +If two or more areas have the same priority, +and it is the highest priority available, +pages are allocated on a round-robin basis between them. +.PP +As of Linux 1.3.6, the kernel usually follows these rules, +but there are exceptions. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBUSY +(for +.BR swapon ()) +The specified +.I path +is already being used as a swap area. +.TP +.B EINVAL +The file +.I path +exists, but refers neither to a regular file nor to a block device; +.TP +.B EINVAL +.RB ( swapon ()) +The indicated path does not contain a valid swap signature or +resides on an in-memory filesystem such as +.BR tmpfs (5). +.TP +.BR EINVAL " (since Linux 3.4)" +.RB ( swapon ()) +An invalid flag value was specified in +.IR flags . +.TP +.B EINVAL +.RB ( swapoff ()) +.I path +is not currently a swap area. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The file +.I path +does not exist. +.TP +.B ENOMEM +The system has insufficient memory to start swapping. +.TP +.B EPERM +The caller does not have the +.B CAP_SYS_ADMIN +capability. +Alternatively, the maximum number of swap files are already in use; +see NOTES below. +.SH CONFORMING TO +These functions are Linux-specific and should not be used in programs +intended to be portable. +The second +.I swapflags +argument was introduced in Linux 1.3.2. +.SH NOTES +The partition or path must be prepared with +.BR mkswap (8). +.PP +There is an upper limit on the number of swap files that may be used, +defined by the kernel constant +.BR MAX_SWAPFILES . +Before kernel 2.4.10, +.B MAX_SWAPFILES +has the value 8; +since kernel 2.4.10, it has the value 32. +Since kernel 2.6.18, the limit is decreased by 2 (thus: 30) +if the kernel is built with the +.B CONFIG_MIGRATION +option +(which reserves two swap table entries for the page migration features of +.BR mbind (2) +and +.BR migrate_pages (2)). +Since kernel 2.6.32, the limit is further decreased by 1 +if the kernel is built with the +.B CONFIG_MEMORY_FAILURE +option. +.PP +Discard of swap pages was introduced in kernel 2.6.29, +then made conditional +on the +.B SWAP_FLAG_DISCARD +flag in kernel 2.6.36, +.\" To be precise: 2.6.35.5 +which still discards the +entire swap area when +.BR swapon () +is called, even if that flag bit is not set. +.SH SEE ALSO +.BR mkswap (8), +.BR swapoff (8), +.BR swapon (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/symlink.2 b/man2/symlink.2 new file mode 100644 index 0000000..ce0cbe7 --- /dev/null +++ b/man2/symlink.2 @@ -0,0 +1,283 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-04-26 by Nick Duffek +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH SYMLINK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +symlink, symlinkat \- make a new name for a file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int symlink(const char *" target ", const char *" linkpath ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int symlinkat(const char *" target ", int " newdirfd \ +", const char *" linkpath ); +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR symlink (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 || _POSIX_C_SOURCE\ >=\ 200112L +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.PP +.BR symlinkat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad b +.PD +.SH DESCRIPTION +.BR symlink () +creates a symbolic link named +.I linkpath +which contains the string +.IR target . +.PP +Symbolic links are interpreted at run time as if the contents of the +link had been substituted into the path being followed to find a file or +directory. +.PP +Symbolic links may contain +.I .. +path components, which (if used at the start of the link) refer to the +parent directories of that in which the link resides. +.PP +A symbolic link (also known as a soft link) may point to an existing +file or to a nonexistent one; the latter case is known as a dangling +link. +.PP +The permissions of a symbolic link are irrelevant; the ownership is +ignored when following the link, but is checked when removal or +renaming of the link is requested and the link is in a directory with +the sticky bit +.RB ( S_ISVTX ) +set. +.PP +If +.I linkpath +exists, it will +.I not +be overwritten. +.SS symlinkat() +The +.BR symlinkat () +system call operates in exactly the same way as +.BR symlink (), +except for the differences described here. +.PP +If the pathname given in +.I linkpath +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I newdirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR symlink () +for a relative pathname). +.PP +If +.I linkpath +is relative and +.I newdirfd +is the special value +.BR AT_FDCWD , +then +.I linkpath +is interpreted relative to the current working +directory of the calling process (like +.BR symlink ()). +.PP +If +.I linkpath +is absolute, then +.I newdirfd +is ignored. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I linkpath +is denied, or one of the directories in the path prefix of +.I linkpath +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.B EDQUOT +The user's quota of resources on the filesystem has been exhausted. +The resources could be inodes or disk blocks, depending on the filesystem +implementation. +.TP +.B EEXIST +.I linkpath +already exists. +.TP +.B EFAULT +.IR target " or " linkpath " points outside your accessible address space." +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR linkpath . +.TP +.B ENAMETOOLONG +.IR target " or " linkpath " was too long." +.TP +.B ENOENT +A directory component in +.I linkpath +does not exist or is a dangling symbolic link, or +.I target +or +.I linkpath +is an empty string. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.I linkpath +is not, in fact, a directory. +.TP +.B EPERM +The filesystem containing +.I linkpath +does not support the creation of symbolic links. +.TP +.B EROFS +.I linkpath +is on a read-only filesystem. +.PP +The following additional errors can occur for +.BR symlinkat (): +.TP +.B EBADF +.I newdirfd +is not a valid file descriptor. +.TP +.B ENOENT +.I linkpath +is a relative pathname and +.IR newdirfd +refers to a directory that has been deleted. +.TP +.B ENOTDIR +.I linkpath +is relative and +.I newdirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR symlinkat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR symlink (): +SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. +.\" SVr4 documents additional error codes EDQUOT and ENOSYS. +.\" See +.\" .BR open (2) +.\" re multiple files with the same name, and NFS. +.PP +.BR symlinkat (): +POSIX.1-2008. +.SH NOTES +No checking of +.I target +is done. +.PP +Deleting the name referred to by a symbolic link will actually delete the +file (unless it also has other hard links). +If this behavior is not desired, use +.BR link (2). +.SS Glibc notes +On older kernels where +.BR symlinkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR symlink (). +When +.I linkpath +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.IR /proc/self/fd +that corresponds to the +.IR newdirfd +argument. +.SH SEE ALSO +.BR ln (1), +.BR namei (1), +.BR lchown (2), +.BR link (2), +.BR lstat (2), +.BR open (2), +.BR readlink (2), +.BR rename (2), +.BR unlink (2), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/symlinkat.2 b/man2/symlinkat.2 new file mode 100644 index 0000000..78568cd --- /dev/null +++ b/man2/symlinkat.2 @@ -0,0 +1 @@ +.so man2/symlink.2 diff --git a/man2/sync.2 b/man2/sync.2 new file mode 100644 index 0000000..7375c0d --- /dev/null +++ b/man2/sync.2 @@ -0,0 +1,139 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (c) 2011 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 12:02:47 1993 by Rik Faith +.\" Modified 15 Apr 1995 by Michael Chastain : +.\" Added reference to `bdflush(2)'. +.\" Modified 960414 by Andries Brouwer : +.\" Added the fact that since 1.3.20 sync actually waits. +.\" Modified Tue Oct 22 22:27:07 1996 by Eric S. Raymond +.\" Modified 2001-10-10 by aeb, following Michael Kerrisk. +.\" 2011-09-07, mtk, Added syncfs() documentation, +.\" +.TH SYNC 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sync, syncfs \- commit filesystem caches to disk +.SH SYNOPSIS +.B #include +.PP +.B void sync(void); +.PP +.BI "int syncfs(int " fd ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR sync (): +.ad l +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.ad +.PP +.BR syncfs (): +.ad l +.RS 4 +_GNU_SOURCE +.RE +.ad +.SH DESCRIPTION +.BR sync () +causes all pending modifications to filesystem metadata and cached file +data to be written to the underlying filesystems. +.PP +.BR syncfs () +is like +.BR sync (), +but synchronizes just the filesystem containing file +referred to by the open file descriptor +.IR fd . +.SH RETURN VALUE +.BR syncfs () +returns 0 on success; +on error, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.BR sync () +is always successful. +.PP +.BR syncfs () +can fail for at least the following reason: +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.SH VERSIONS +.BR syncfs () +first appeared in Linux 2.6.39; +library support was added to glibc in version 2.14. +.SH CONFORMING TO +.BR sync (): +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.PP +.BR syncfs () +is Linux-specific. +.SH NOTES +Since glibc 2.2.2, the Linux prototype for +.BR sync () +is as listed above, +following the various standards. +In glibc 2.2.1 and earlier, +it was "int sync(void)", and +.BR sync () +always returned 0. +.PP +According to the standard specification (e.g., POSIX.1-2001), +.BR sync () +schedules the writes, but may return before the actual +writing is done. However Linux waits for I/O completions, +and thus +.BR sync () +or +.BR syncfs () +provide the same guarantees as fsync called on every file in +the system or filesystem respectively. +.SH BUGS +Before version 1.3.20 Linux did not wait for I/O to complete +before returning. +.SH SEE ALSO +.BR sync (1), +.BR fdatasync (2), +.BR fsync (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2 new file mode 100644 index 0000000..8c7d1db --- /dev/null +++ b/man2/sync_file_range.2 @@ -0,0 +1,232 @@ +.\" Copyright (c) 2006 Andrew Morton +.\" and Copyright 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2006-07-05 Initial creation, Michael Kerrisk based on +.\" Andrew Morton's comments in fs/sync.c +.\" 2010-10-09, mtk, Document sync_file_range2() +.\" +.TH SYNC_FILE_RANGE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sync_file_range \- sync a file segment with disk +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes , +.BI " unsigned int " flags ); +.fi +.SH DESCRIPTION +.BR sync_file_range () +permits fine control when synchronizing the open file referred to by the +file descriptor +.I fd +with disk. +.PP +.I offset +is the starting byte of the file range to be synchronized. +.I nbytes +specifies the length of the range to be synchronized, in bytes; if +.I nbytes +is zero, then all bytes from +.I offset +through to the end of file are synchronized. +Synchronization is in units of the system page size: +.I offset +is rounded down to a page boundary; +.I (offset+nbytes-1) +is rounded up to a page boundary. +.PP +The +.I flags +bit-mask argument can include any of the following values: +.TP +.B SYNC_FILE_RANGE_WAIT_BEFORE +Wait upon write-out of all pages in the specified range +that have already been submitted to the device driver for write-out +before performing any write. +.TP +.B SYNC_FILE_RANGE_WRITE +Initiate write-out of all dirty pages in the specified +range which are not presently submitted write-out. +Note that even this may block if you attempt to +write more than request queue size. +.TP +.B SYNC_FILE_RANGE_WAIT_AFTER +Wait upon write-out of all pages in the range +after performing any write. +.PP +Specifying +.I flags +as 0 is permitted, as a no-op. +.SS Warning +This system call is extremely dangerous and should not be used in portable +programs. +None of these operations writes out the file's metadata. +Therefore, unless the application is strictly performing overwrites of +already-instantiated disk blocks, there are no guarantees that the data will +be available after a crash. +There is no user interface to know if a write is purely an overwrite. +On filesystems using copy-on-write semantics (e.g., +.IR btrfs ) +an overwrite of existing allocated blocks is impossible. +When writing into preallocated space, +many filesystems also require calls into the block +allocator, which this system call does not sync out to disk. +This system call does not flush disk write caches and thus does not provide +any data integrity on systems with volatile disk write caches. +.SS Some details +.B SYNC_FILE_RANGE_WAIT_BEFORE +and +.B SYNC_FILE_RANGE_WAIT_AFTER +will detect any +I/O errors or +.B ENOSPC +conditions and will return these to the caller. +.PP +Useful combinations of the +.I flags +bits are: +.TP +.B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE +Ensures that all pages +in the specified range which were dirty when +.BR sync_file_range () +was called are placed +under write-out. +This is a start-write-for-data-integrity operation. +.TP +.B SYNC_FILE_RANGE_WRITE +Start write-out of all dirty pages in the specified range which +are not presently under write-out. +This is an asynchronous flush-to-disk +operation. +This is not suitable for data integrity operations. +.TP +.BR SYNC_FILE_RANGE_WAIT_BEFORE " (or " SYNC_FILE_RANGE_WAIT_AFTER ) +Wait for +completion of write-out of all pages in the specified range. +This can be used after an earlier +.B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE +operation to wait for completion of that operation, and obtain its result. +.TP +.B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | \ +SYNC_FILE_RANGE_WAIT_AFTER +This is a write-for-data-integrity operation +that will ensure that all pages in the specified range which were dirty when +.BR sync_file_range () +was called are committed to disk. +.SH RETURN VALUE +On success, +.BR sync_file_range () +returns 0; on failure \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I flags +specifies an invalid bit; or +.I offset +or +.I nbytes +is invalid. +.TP +.B EIO +I/O error. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOSPC +Out of disk space. +.TP +.B ESPIPE +.I fd +refers to something other than a regular file, a block device, or +a directory. +.SH VERSIONS +.BR sync_file_range () +appeared on Linux in kernel 2.6.17. +.SH CONFORMING TO +This system call is Linux-specific, and should be avoided +in portable programs. +.SH NOTES +.SS sync_file_range2() +Some architectures (e.g., PowerPC, ARM) +need 64-bit arguments to be aligned in a suitable pair of registers. +.\" See kernel commit edd5cd4a9424f22b0fa08bef5e299d41befd5622 +On such architectures, the call signature of +.BR sync_file_range () +shown in the SYNOPSIS would force +a register to be wasted as padding between the +.I fd +and +.I offset +arguments. +(See +.BR syscall (2) +for details.) +Therefore, these architectures define a different +system call that orders the arguments suitably: +.PP +.in +4n +.EX +.BI "int sync_file_range2(int " fd ", unsigned int " flags , +.BI " off64_t " offset ", off64_t " nbytes ); +.EE +.in +.PP +The behavior of this system call is otherwise exactly the same as +.BR sync_file_range (). +.PP +A system call with this signature first appeared on the ARM architecture +in Linux 2.6.20, with the name +.BR arm_sync_file_range (). +It was renamed in Linux 2.6.22, +when the analogous system call was added for PowerPC. +On architectures where glibc support is provided, +glibc transparently wraps +.BR sync_file_range2 () +under the name +.BR sync_file_range (). +.SH SEE ALSO +.BR fdatasync (2), +.BR fsync (2), +.BR msync (2), +.BR sync (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sync_file_range2.2 b/man2/sync_file_range2.2 new file mode 100644 index 0000000..ad7a1e6 --- /dev/null +++ b/man2/sync_file_range2.2 @@ -0,0 +1 @@ +.so man2/sync_file_range.2 diff --git a/man2/syncfs.2 b/man2/syncfs.2 new file mode 100644 index 0000000..5555798 --- /dev/null +++ b/man2/syncfs.2 @@ -0,0 +1 @@ +.so man2/sync.2 diff --git a/man2/syscall.2 b/man2/syscall.2 new file mode 100644 index 0000000..cdaab47 --- /dev/null +++ b/man2/syscall.2 @@ -0,0 +1,334 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)syscall.2 8.1 (Berkeley) 6/16/93 +.\" +.\" +.\" 2002-03-20 Christoph Hellwig +.\" - adopted for Linux +.\" 2015-01-17, Kees Cook +.\" Added mips and arm64. +.\" +.TH SYSCALL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +syscall \- indirect system call +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.BR "#include " "/* For SYS_xxx definitions */" +.PP +.BI "long syscall(long " number ", ...);" +.fi +.SH DESCRIPTION +.BR syscall () +is a small library function that invokes +the system call whose assembly language +interface has the specified +.I number +with the specified arguments. +Employing +.BR syscall () +is useful, for example, +when invoking a system call that has no wrapper function in the C library. +.PP +.BR syscall () +saves CPU registers before making the system call, +restores the registers upon return from the system call, +and stores any error code returned by the system call in +.BR errno (3) +if an error occurs. +.PP +Symbolic constants for system call numbers can be found in the header file +.IR . +.SH RETURN VALUE +The return value is defined by the system call being invoked. +In general, a 0 return value indicates success. +A \-1 return value indicates an error, +and an error code is stored in +.IR errno . +.SH NOTES +.BR syscall () +first appeared in +4BSD. +.SS Architecture-specific requirements +Each architecture ABI has its own requirements on how +system call arguments are passed to the kernel. +For system calls that have a glibc wrapper (e.g., most system calls), +glibc handles the details of copying arguments to the right registers +in a manner suitable for the architecture. +However, when using +.BR syscall () +to make a system call, +the caller might need to handle architecture-dependent details; +this requirement is most commonly encountered on certain 32-bit architectures. +.PP +For example, on the ARM architecture Embedded ABI (EABI), a +64-bit value (e.g., +.IR "long long" ) +must be aligned to an even register pair. +Thus, using +.BR syscall () +instead of the wrapper provided by glibc, +the +.BR readahead () +system call would be invoked as follows on the ARM architecture with the EABI +in little endian mode: +.PP +.in +4n +.EX +syscall(SYS_readahead, fd, 0, + (unsigned int) (offset & 0xFFFFFFFF), + (unsigned int) (offset >> 32), + count); +.EE +.in +.PP +Since the offset argument is 64 bits, and the first argument +.RI ( fd ) +is passed in +.IR r0 , +the caller must manually split and align the 64-bit value +so that it is passed in the +.IR r2 / r3 +register pair. +That means inserting a dummy value into +.I r1 +(the second argument of 0). +Care also must be taken so that the split follows endian conventions +(according to the C ABI for the platform). +.PP +Similar issues can occur on MIPS with the O32 ABI, +on PowerPC with the 32-bit ABI, and on Xtensa. +.\" Mike Frysinger: this issue ends up forcing MIPS +.\" O32 to take 7 arguments to syscall() +.PP +.\" See arch/parisc/kernel/sys_parisc.c. +Note that while the parisc C ABI also uses aligned register pairs, +it uses a shim layer to hide the issue from userspace. +.PP +The affected system calls are +.BR fadvise64_64 (2), +.BR ftruncate64 (2), +.BR posix_fadvise (2), +.BR pread64 (2), +.BR pwrite64 (2), +.BR readahead (2), +.BR sync_file_range (2), +and +.BR truncate64 (2). +.PP +.\" You need to look up the syscalls directly in the kernel source to see if +.\" they should be in this list. For example, look at fs/read_write.c and +.\" the function signatures that do: +.\" ..., unsigned long, pos_l, unsigned long, pos_h, ... +.\" If they use off_t, then they most likely do not belong in this list. +This does not affect syscalls that manually split and assemble 64-bit values +such as +.BR _llseek (2), +.BR preadv (2), +.BR preadv2 (2), +.BR pwritev (2). +and +.BR pwritev2 (2). +Welcome to the wonderful world of historical baggage. +.SS Architecture calling conventions +Every architecture has its own way of invoking and passing arguments to the +kernel. +The details for various architectures are listed in the two tables below. +.PP +The first table lists the instruction used to transition to kernel mode +(which might not be the fastest or best way to transition to the kernel, +so you might have to refer to +.BR vdso (7)), +the register used to indicate the system call number, +the register used to return the system call result, +and the register used to signal an error. +.if t \{\ +.ft CW +\} +.TS +l2 l2 l2 l2 l2 l. +arch/ABI instruction syscall # retval error Notes +_ +alpha callsys v0 a0 a3 [1] +arc trap0 r8 r0 - +arm/OABI swi NR - a1 - [2] +arm/EABI swi 0x0 r7 r0 - +arm64 svc #0 x8 x0 - +blackfin excpt 0x0 P0 R0 - +i386 int $0x80 eax eax - +ia64 break 0x100000 r15 r8 r10 [1] +m68k trap #0 d0 d0 - +microblaze brki r14,8 r12 r3 - +mips syscall v0 v0 a3 [1] +nios2 trap r2 r2 r7 +parisc ble 0x100(%sr2, %r0) r20 r28 - +powerpc sc r0 r3 r0 [1] +s390 svc 0 r1 r2 - [3] +s390x svc 0 r1 r2 - [3] +superh trap #0x17 r3 r0 - [4] +sparc/32 t 0x10 g1 o0 psr/csr [1] +sparc/64 t 0x6d g1 o0 psr/csr [1] +tile swint1 R10 R00 R01 [1] +x86-64 syscall rax rax - [5] +x32 syscall rax rax - [5] +xtensa syscall a2 a2 - +.TE +.PP +Notes: +.RS 4 +.IP [1] 4 +On a few architectures, +a register is used as a boolean +(0 indicating no error, and \-1 indicating an error) to signal that the +system call failed. +The actual error value is still contained in the return register. +On sparc, the carry bit +.RI ( csr ) +in the processor status register +.RI ( psr ) +is used instead of a full register. +.IP [2] +.I NR +is the system call number. +.IP [3] +For s390 and s390x, +.I NR +(the system call number) may be passed directly with +.I "svc\ NR" +if it is less than 256. +.IP [4] +On SuperH, the trap number controls the maximum number of arguments passed. +A +.IR "trap\ #0x10" +can be used with only 0-argument system calls, a +.IR "trap\ #0x11" +can be used with 0- or 1-argument system calls, +and so on up to +.IR "trap #0x17" +for 7-argument system calls. +.IP [5] +The x32 ABI uses the same instruction as the x86-64 ABI and is used on +the same processors. +To differentiate between them, the bit mask +.I __X32_SYSCALL_BIT +is bitwise-ORed into the system call number for system calls +under the x32 ABI. +Both system call tables are available though, +so setting the bit is not a hard requirement. +.RE +.if t \{\ +.in +.ft P +\} +.PP +The second table shows the registers used to pass the system call arguments. +.if t \{\ +.ft CW +\} +.TS +l l2 l2 l2 l2 l2 l2 l2 l. +arch/ABI arg1 arg2 arg3 arg4 arg5 arg6 arg7 Notes +_ +alpha a0 a1 a2 a3 a4 a5 - +arc r0 r1 r2 r3 r4 r5 - +arm/OABI a1 a2 a3 a4 v1 v2 v3 +arm/EABI r0 r1 r2 r3 r4 r5 r6 +arm64 x0 x1 x2 x3 x4 x5 - +blackfin R0 R1 R2 R3 R4 R5 - +i386 ebx ecx edx esi edi ebp - +ia64 out0 out1 out2 out3 out4 out5 - +m68k d1 d2 d3 d4 d5 a0 - +microblaze r5 r6 r7 r8 r9 r10 - +mips/o32 a0 a1 a2 a3 - - - [1] +mips/n32,64 a0 a1 a2 a3 a4 a5 - +nios2 r4 r5 r6 r7 r8 r9 - +parisc r26 r25 r24 r23 r22 r21 - +powerpc r3 r4 r5 r6 r7 r8 r9 +s390 r2 r3 r4 r5 r6 r7 - +s390x r2 r3 r4 r5 r6 r7 - +superh r4 r5 r6 r7 r0 r1 r2 +sparc/32 o0 o1 o2 o3 o4 o5 - +sparc/64 o0 o1 o2 o3 o4 o5 - +tile R00 R01 R02 R03 R04 R05 - +x86-64 rdi rsi rdx r10 r8 r9 - +x32 rdi rsi rdx r10 r8 r9 - +xtensa a6 a3 a4 a5 a8 a9 - +.TE +.PP +Notes: +.RS 4 +.IP [1] 4 +The mips/o32 system call convention passes +arguments 5 through 8 on the user stack. +.RE +.if t \{\ +.in +.ft P +\} +.PP +Note that these tables don't cover the entire calling convention\(emsome +architectures may indiscriminately clobber other registers not listed here. +.SH EXAMPLE +.EX +#define _GNU_SOURCE +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + pid_t tid; + + tid = syscall(SYS_gettid); + syscall(SYS_tgkill, getpid(), tid, SIGHUP); +} +.EE +.SH SEE ALSO +.BR _syscall (2), +.BR intro (2), +.BR syscalls (2), +.BR errno (3), +.BR vdso (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/syscalls.2 b/man2/syscalls.2 new file mode 100644 index 0000000..df96ea4 --- /dev/null +++ b/man2/syscalls.2 @@ -0,0 +1,873 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" with some input from Stepan Kasal +.\" +.\" Some content retained from an earlier version of this page: +.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl) +.\" Modifications for 2.2 and 2.4 Copyright (C) 2002 Ian Redfern +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SYSCALLS 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +syscalls \- Linux system calls +.SH SYNOPSIS +Linux system calls. +.SH DESCRIPTION +The system call is the fundamental interface between an application +and the Linux kernel. +.SS System calls and library wrapper functions +System calls are generally not invoked directly, +but rather via wrapper functions in glibc (or perhaps some other library). +For details of direct invocation of a system call, see +.BR intro (2). +Often, but not always, the name of the wrapper function is the same +as the name of the system call that it invokes. +For example, glibc contains a function +.BR truncate () +which invokes the underlying "truncate" system call. +.PP +Often the glibc wrapper function is quite thin, doing little work +other than copying arguments to the right registers +before invoking the system call, +and then setting +.I errno +appropriately after the system call has returned. +(These are the same steps that are performed by +.BR syscall (2), +which can be used to invoke system calls +for which no wrapper function is provided.) +Note: system calls indicate a failure by returning a negative error +number to the caller; +when this happens, +the wrapper function negates the returned error number +(to make it positive), copies it to +.IR errno , +and returns \-1 to the caller of the wrapper. +.PP +Sometimes, however, the wrapper function does some extra work +before invoking the system call. +For example, nowadays there are (for reasons described below) two +related system calls, +.BR truncate (2) +and +.BR truncate64 (2), +and the glibc +.BR truncate () +wrapper function checks which of those system calls +are provided by the kernel and determines which should be employed. +.SS System call list +Below is a list of the Linux system calls. +In the list, the +.I Kernel +column indicates the kernel version +for those system calls that were new in Linux 2.2, +or have appeared since that kernel version. +Note the following points: +.IP * 3 +Where no kernel version is indicated, +the system call appeared in kernel 1.0 or earlier. +.IP * +Where a system call is marked "1.2" +this means the system call probably appeared in a 1.1.x kernel version, +and first appeared in a stable kernel with 1.2. +(Development of the 1.2 kernel was initiated from a branch of kernel +1.0.6 via the 1.1.x unstable kernel series.) +.IP * +Where a system call is marked "2.0" +this means the system call probably appeared in a 1.3.x kernel version, +and first appeared in a stable kernel with 2.0. +(Development of the 2.0 kernel was initiated from a branch of kernel +1.2.x, somewhere around 1.2.10, +via the 1.3.x unstable kernel series.) +.\" Was kernel 2.0 started from a branch of 1.2.10? +.\" At least from the timestamps of the tarballs of +.\" of 1.2.10 and 1.3.0, that's how it looks, but in +.\" fact the diff doesn't seem very clear, the +.\" 1.3.0 .tar.bz is much bigger (2.0 MB) than the +.\" 1.2.10 .tar.bz2 (1.8 MB), and AEB points out the +.\" timestamps of some files in 1.3.0 seem to be older +.\" than those in 1.2.10. All of this suggests +.\" that there might not have been a clean branch point. +.IP * +Where a system call is marked "2.2" +this means the system call probably appeared in a 2.1.x kernel version, +and first appeared in a stable kernel with 2.2.0. +(Development of the 2.2 kernel was initiated from a branch of kernel +2.0.21 via the 2.1.x unstable kernel series.) +.IP * +Where a system call is marked "2.4" +this means the system call probably appeared in a 2.3.x kernel version, +and first appeared in a stable kernel with 2.4.0. +(Development of the 2.4 kernel was initiated from a branch of +kernel 2.2.8 via the 2.3.x unstable kernel series.) +.IP * +Where a system call is marked "2.6" +this means the system call probably appeared in a 2.5.x kernel version, +and first appeared in a stable kernel with 2.6.0. +(Development of kernel 2.6 was initiated from a branch +of kernel 2.4.15 via the 2.5.x unstable kernel series.) +.IP * +Starting with kernel 2.6.0, the development model changed, +and new system calls may appear in each 2.6.x release. +In this case, the exact version number where the system call appeared +is shown. +This convention continues with the 3.x kernel series, +which followed on from kernel 2.6.39, and the 4.x kernel series, +which followed on from kernel 3.19. +.IP * +In some cases, a system call was added to a stable kernel +series after it branched from the previous stable kernel +series, and then backported into the earlier stable kernel series. +For example some system calls that appeared in 2.6.x were also backported +into a 2.4.x release after 2.4.15. +When this is so, the version where the system call appeared +in both of the major kernel series is listed. +.PP +The list of system calls that are available as at kernel 4.11 +(or in a few cases only on older kernels) is as follows: +.\" +.\" Looking at scripts/checksyscalls.sh in the kernel source is +.\" instructive about x86 specifics. +.\" +.ad l +.TS +l2 le l +--- +l l l. +\fBSystem call\fP \fBKernel\fP \fBNotes\fP + +\fB_llseek\fP(2) 1.2 +\fB_newselect\fP(2) 2.0 +\fB_sysctl\fP(2) 2.0 +\fBaccept\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBaccept4\fP(2) 2.6.28 +\fBaccess\fP(2) 1.0 +\fBacct\fP(2) 1.0 +\fBadd_key\fP(2) 2.6.10 +\fBadjtimex\fP(2) 1.0 +\fBalarm\fP(2) 1.0 +\fBalloc_hugepages\fP(2) 2.5.36 Removed in 2.5.44 +\fBbdflush\fP(2) 1.2 T{ +Deprecated (does nothing) +.br +since 2.6 +T} +\fBbind\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBbpf\fP(2) 3.18 +\fBbrk\fP(2) 1.0 +\fBcacheflush\fP(2) 1.2 Not on x86 +\fBcapget\fP(2) 2.2 +\fBcapset\fP(2) 2.2 +\fBchdir\fP(2) 1.0 +\fBchmod\fP(2) 1.0 +\fBchown\fP(2) 2.2 T{ +See \fBchown\fP(2) for +.br +version details +T} +\fBchown32\fP(2) 2.4 +\fBchroot\fP(2) 1.0 +\fBclock_adjtime\fP(2) 2.6.39 +\fBclock_getres\fP(2) 2.6 +\fBclock_gettime\fP(2) 2.6 +\fBclock_nanosleep\fP(2) 2.6 +\fBclock_settime\fP(2) 2.6 +\fBclone\fP(2) 1.0 +\fBclose\fP(2) 1.0 +\fBconnect\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBcopy_file_range\fP(2) 4.5 +\fBcreat\fP(2) 1.0 +\fBcreate_module\fP(2) 1.0 Removed in 2.6 +\fBdelete_module\fP(2) 1.0 +\fBdup\fP(2) 1.0 +\fBdup2\fP(2) 1.0 +\fBdup3\fP(2) 2.6.27 +\fBepoll_create\fP(2) 2.6 +\fBepoll_create1\fP(2) 2.6.27 +\fBepoll_ctl\fP(2) 2.6 +\fBepoll_pwait\fP(2) 2.6.19 +\fBepoll_wait\fP(2) 2.6 +\fBeventfd\fP(2) 2.6.22 +\fBeventfd2\fP(2) 2.6.27 +\fBexecve\fP(2) 1.0 +\fBexecveat\fP(2) 3.19 +\fBexit\fP(2) 1.0 +\fBexit_group\fP(2) 2.6 +\fBfaccessat\fP(2) 2.6.16 +\fBfadvise64\fP(2) 2.6 +.\" Implements \fBposix_fadvise\fP(2) +\fBfadvise64_64\fP(2) 2.6 +\fBfallocate\fP(2) 2.6.23 +\fBfanotify_init\fP(2) 2.6.37 +\fBfanotify_mark\fP(2) 2.6.37 +.\" The fanotify calls were added in Linux 2.6.36, +.\" but disabled while the API was finalized. +\fBfchdir\fP(2) 1.0 +\fBfchmod\fP(2) 1.0 +\fBfchmodat\fP(2) 2.6.16 +\fBfchown\fP(2) 1.0 +\fBfchown32\fP(2) 2.4 +\fBfchownat\fP(2) 2.6.16 +\fBfcntl\fP(2) 1.0 +\fBfcntl64\fP(2) 2.4 +\fBfdatasync\fP(2) 2.0 +\fBfgetxattr\fP(2) 2.6; 2.4.18 +\fBfinit_module\fP(2) 3.8 +\fBflistxattr\fP(2) 2.6; 2.4.18 +\fBflock\fP(2) 2.0 +\fBfork\fP(2) 1.0 +\fBfree_hugepages\fP(2) 2.5.36 Removed in 2.5.44 +\fBfremovexattr\fP(2) 2.6; 2.4.18 +\fBfsetxattr\fP(2) 2.6; 2.4.18 +\fBfstat\fP(2) 1.0 +\fBfstat64\fP(2) 2.4 +\fBfstatat64\fP(2) 2.6.16 +\fBfstatfs\fP(2) 1.0 +\fBfstatfs64\fP(2) 2.6 +\fBfsync\fP(2) 1.0 +\fBftruncate\fP(2) 1.0 +\fBftruncate64\fP(2) 2.4 +\fBfutex\fP(2) 2.6 +\fBfutimesat\fP(2) 2.6.16 +\fBget_kernel_syms\fP(2) 1.0 Removed in 2.6 +\fBget_mempolicy\fP(2) 2.6.6 +\fBget_robust_list\fP(2) 2.6.17 +\fBget_thread_area\fP(2) 2.6 +\fBgetcpu\fP(2) 2.6.19 +\fBgetcwd\fP(2) 2.2 +\fBgetdents\fP(2) 2.0 +\fBgetdents64\fP(2) 2.4 +\fBgetegid\fP(2) 1.0 +\fBgetegid32\fP(2) 2.4 +\fBgeteuid\fP(2) 1.0 +\fBgeteuid32\fP(2) 2.4 +\fBgetgid\fP(2) 1.0 +\fBgetgid32\fP(2) 2.4 +\fBgetgroups\fP(2) 1.0 +\fBgetgroups32\fP(2) 2.4 +\fBgetitimer\fP(2) 1.0 +\fBgetpeername\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBgetpagesize\fP(2) 2.0 Not on x86 +\fBgetpgid\fP(2) 1.0 +\fBgetpgrp\fP(2) 1.0 +\fBgetpid\fP(2) 1.0 +\fBgetppid\fP(2) 1.0 +\fBgetpriority\fP(2) 1.0 +\fBgetrandom\fP(2) 3.17 +\fBgetresgid\fP(2) 2.2 +\fBgetresgid32\fP(2) 2.4 +\fBgetresuid\fP(2) 2.2 +\fBgetresuid32\fP(2) 2.4 +\fBgetrlimit\fP(2) 1.0 +\fBgetrusage\fP(2) 1.0 +\fBgetsid\fP(2) 2.0 +\fBgetsockname\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBgetsockopt\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBgettid\fP(2) 2.4.11 +\fBgettimeofday\fP(2) 1.0 +\fBgetuid\fP(2) 1.0 +\fBgetuid32\fP(2) 2.4 +\fBgetunwind\fP(2) 2.4.8 ia64; deprecated +\fBgetxattr\fP(2) 2.6; 2.4.18 +\fBinit_module\fP(2) 1.0 +\fBinotify_add_watch\fP(2) 2.6.13 +\fBinotify_init\fP(2) 2.6.13 +\fBinotify_init1\fP(2) 2.6.27 +\fBinotify_rm_watch\fP(2) 2.6.13 +\fBio_cancel\fP(2) 2.6 +\fBio_destroy\fP(2) 2.6 +\fBio_getevents\fP(2) 2.6 +\fBio_setup\fP(2) 2.6 +\fBio_submit\fP(2) 2.6 +\fBioctl\fP(2) 1.0 +\fBioperm\fP(2) 1.0 +\fBiopl\fP(2) 1.0 +\fBioprio_get\fP(2) 2.6.13 +\fBioprio_set\fP(2) 2.6.13 +\fBipc\fP(2) 1.0 +.\" Implements System V IPC calls +\fBkcmp\fP(2) 3.5 +\fBkern_features\fP(2) 3.7 Sparc64 +.\" FIXME . document kern_features(): +.\" commit 517ffce4e1a03aea979fe3a18a3dd1761a24fafb +\fBkexec_file_load\fP(2) 3.17 +\fBkexec_load\fP(2) 2.6.13 +.\" The entry in the syscall table was reserved starting in 2.6.7 +.\" Was named sys_kexec_load() from 2.6.7 to 2.6.16 +\fBkeyctl\fP(2) 2.6.10 +\fBkill\fP(2) 1.0 +\fBlchown\fP(2) 1.0 T{ +See \fBchown\fP(2) for +.br +version details +T} +\fBlchown32\fP(2) 2.4 +\fBlgetxattr\fP(2) 2.6; 2.4.18 +\fBlink\fP(2) 1.0 +\fBlinkat\fP(2) 2.6.16 +\fBlisten\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBlistxattr\fP(2) 2.6; 2.4.18 +\fBllistxattr\fP(2) 2.6; 2.4.18 +\fBlookup_dcookie\fP(2) 2.6 +\fBlremovexattr\fP(2) 2.6; 2.4.18 +\fBlseek\fP(2) 1.0 +\fBlsetxattr\fP(2) 2.6; 2.4.18 +\fBlstat\fP(2) 1.0 +\fBlstat64\fP(2) 2.4 +\fBmadvise\fP(2) 2.4 +\fBmbind\fP(2) 2.6.6 +.\" \fBmemory_ordering\fP(2) ??? Sparc64 +\fBmembarrier\fP(2) 3.17 +\fBmemfd_create\fP(2) 3.17 +\fBmigrate_pages\fP(2) 2.6.16 +\fBmincore\fP(2) 2.4 +\fBmkdir\fP(2) 1.0 +\fBmkdirat\fP(2) 2.6.16 +\fBmknod\fP(2) 1.0 +\fBmknodat\fP(2) 2.6.16 +\fBmlock\fP(2) 2.0 +\fBmlock2\fP(2) 4.4 +\fBmlockall\fP(2) 2.0 +\fBmmap\fP(2) 1.0 +\fBmmap2\fP(2) 2.4 +\fBmodify_ldt\fP(2) 1.0 +\fBmount\fP(2) 1.0 +\fBmove_pages\fP(2) 2.6.18 +\fBmprotect\fP(2) 1.0 +\fBmq_getsetattr\fP(2) 2.6.6 +.\" Implements \fBmq_getattr\fP(3) and \fBmq_setattr\fP(3) +\fBmq_notify\fP(2) 2.6.6 +\fBmq_open\fP(2) 2.6.6 +\fBmq_timedreceive\fP(2) 2.6.6 +\fBmq_timedsend\fP(2) 2.6.6 +\fBmq_unlink\fP(2) 2.6.6 +\fBmremap\fP(2) 2.0 +\fBmsgctl\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBmsgget\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBmsgrcv\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBmsgsnd\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBmsync\fP(2) 2.0 +.\" \fBmultiplexer\fP(2) ?? __NR_multiplexer reserved on +.\" PowerPC, but unimplemented? +\fBmunlock\fP(2) 2.0 +\fBmunlockall\fP(2) 2.0 +\fBmunmap\fP(2) 1.0 +\fBname_to_handle_at\fP(2) 2.6.39 +\fBnanosleep\fP(2) 2.0 +\fBnfsservctl\fP(2) 2.2 Removed in 3.1 +\fBnice\fP(2) 1.0 +\fBoldfstat\fP(2) 1.0 +\fBoldlstat\fP(2) 1.0 +\fBoldolduname\fP(2) 1.0 +\fBoldstat\fP(2) 1.0 +\fBolduname\fP(2) 1.0 +\fBopen\fP(2) 1.0 +\fBopen_by_handle_at\fP(2) 2.6.39 +\fBopenat\fP(2) 2.6.16 +\fBpause\fP(2) 1.0 +\fBpciconfig_iobase\fP(2) 2.2.15; 2.4 Not on x86 +.\" Alpha, PowerPC, ARM; not x86 +\fBpciconfig_read\fP(2) 2.0.26; 2.2 Not on x86 +.\" , PowerPC, ARM; not x86 +\fBpciconfig_write\fP(2) 2.0.26; 2.2 Not on x86 +.\" , PowerPC, ARM; not x86 +\fBperf_event_open\fP(2) 2.6.31 T{ +Was perf_counter_open() in +.br +2.6.31; renamed in 2.6.32 +T} +\fBpersonality\fP(2) 1.2 +\fBperfctr\fP(2) 2.2 Sparc; removed in 2.6.34 +.\" commit c7d5a0050773e98d1094eaa9f2a1a793fafac300 removed perfctr() +\fBperfmonctl\fP(2) 2.4 ia64 +\fBpipe\fP(2) 1.0 +\fBpipe2\fP(2) 2.6.27 +\fBpivot_root\fP(2) 2.4 +\fBpkey_alloc\fP(2) 4.8 +\fBpkey_free\fP(2) 4.8 +\fBpkey_mprotect\fP(2) 4.8 +\fBpoll\fP(2) 2.0.36; 2.2 +\fBppc_rtas\fP(2) 2.6.2 PowerPC only +\fBppc_swapcontext\fP(2) 2.6.3 PowerPC only +\fBppoll\fP(2) 2.6.16 +\fBprctl\fP(2) 2.2 +\fBpread64\fP(2) T{ +Added as "pread" in 2.2; +.br +renamed "pread64" in 2.6 +T} +\fBpreadv\fP(2) 2.6.30 +\fBpreadv2\fP(2) 4.6 +\fBprlimit64\fP(2) 2.6.36 +\fBprocess_vm_readv\fP(2) 3.2 +\fBprocess_vm_writev\fP(2) 3.2 +\fBpselect6\fP(2) 2.6.16 +.\" Implements \fBpselect\fP(2) +\fBptrace\fP(2) 1.0 +\fBpwrite64\fP(2) T{ +Added as "pwrite" in 2.2; +.br +renamed "pwrite64" in 2.6 +T} +\fBpwritev\fP(2) 2.6.30 +\fBpwritev2\fP(2) 4.6 +\fBquery_module\fP(2) 2.2 Removed in 2.6 +\fBquotactl\fP(2) 1.0 +\fBread\fP(2) 1.0 +\fBreadahead\fP(2) 2.4.13 +\fBreaddir\fP(2) 1.0 +.\" Supersedes \fBgetdents\fP(2) +\fBreadlink\fP(2) 1.0 +\fBreadlinkat\fP(2) 2.6.16 +\fBreadv\fP(2) 2.0 +\fBreboot\fP(2) 1.0 +\fBrecv\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBrecvfrom\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBrecvmsg\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBrecvmmsg\fP(2) 2.6.33 +\fBremap_file_pages\fP(2) 2.6 Deprecated since 3.16 +\fBremovexattr\fP(2) 2.6; 2.4.18 +\fBrename\fP(2) 1.0 +\fBrenameat\fP(2) 2.6.16 +\fBrenameat2\fP(2) 3.15 +\fBrequest_key\fP(2) 2.6.10 +\fBrestart_syscall\fP(2) 2.6 +\fBrmdir\fP(2) 1.0 +\fBrt_sigaction\fP(2) 2.2 +\fBrt_sigpending\fP(2) 2.2 +\fBrt_sigprocmask\fP(2) 2.2 +\fBrt_sigqueueinfo\fP(2) 2.2 +\fBrt_sigreturn\fP(2) 2.2 +\fBrt_sigsuspend\fP(2) 2.2 +\fBrt_sigtimedwait\fP(2) 2.2 +\fBrt_tgsigqueueinfo\fP(2) 2.6.31 +\fBs390_runtime_instr\fP(2) 3.7 s390 only +\fBs390_pci_mmio_read\fP(2) 3.19 s390 only +\fBs390_pci_mmio_write\fP(2) 3.19 s390 only +\fBs390_sthyi\fP(2) 4.15 s390 only +\fBsched_get_priority_max\fP(2) 2.0 +\fBsched_get_priority_min\fP(2) 2.0 +\fBsched_getaffinity\fP(2) 2.6 +\fBsched_getattr\fP(2) 3.14 +\fBsched_getparam\fP(2) 2.0 +\fBsched_getscheduler\fP(2) 2.0 +\fBsched_rr_get_interval\fP(2) 2.0 +\fBsched_setaffinity\fP(2) 2.6 +\fBsched_setattr\fP(2) 3.14 +\fBsched_setparam\fP(2) 2.0 +\fBsched_setscheduler\fP(2) 2.0 +\fBsched_yield\fP(2) 2.0 +\fBseccomp\fP(2) 3.17 +\fBselect\fP(2) 1.0 +\fBsemctl\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBsemget\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBsemop\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBsemtimedop\fP(2) 2.6; 2.4.22 +\fBsend\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBsendfile\fP(2) 2.2 +\fBsendfile64\fP(2) 2.6; 2.4.19 +\fBsendmmsg\fP(2) 3.0 +\fBsendmsg\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBsendto\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBset_mempolicy\fP(2) 2.6.6 +\fBset_robust_list\fP(2) 2.6.17 +\fBset_thread_area\fP(2) 2.6 +\fBset_tid_address\fP(2) 2.6 +.\" See http://lkml.org/lkml/2005/8/1/83 +.\" "[PATCH] remove sys_set_zone_reclaim()" +\fBsetdomainname\fP(2) 1.0 +\fBsetfsgid\fP(2) 1.2 +\fBsetfsgid32\fP(2) 2.4 +\fBsetfsuid\fP(2) 1.2 +\fBsetfsuid32\fP(2) 2.4 +\fBsetgid\fP(2) 1.0 +\fBsetgid32\fP(2) 2.4 +\fBsetgroups\fP(2) 1.0 +\fBsetgroups32\fP(2) 2.4 +\fBsethostname\fP(2) 1.0 +\fBsetitimer\fP(2) 1.0 +\fBsetns\fP(2) 3.0 +\fBsetpgid\fP(2) 1.0 +\fBsetpriority\fP(2) 1.0 +\fBsetregid\fP(2) 1.0 +\fBsetregid32\fP(2) 2.4 +\fBsetresgid\fP(2) 2.2 +\fBsetresgid32\fP(2) 2.4 +\fBsetresuid\fP(2) 2.2 +\fBsetresuid32\fP(2) 2.4 +\fBsetreuid\fP(2) 1.0 +\fBsetreuid32\fP(2) 2.4 +\fBsetrlimit\fP(2) 1.0 +\fBsetsid\fP(2) 1.0 +\fBsetsockopt\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBsettimeofday\fP(2) 1.0 +\fBsetuid\fP(2) 1.0 +\fBsetuid32\fP(2) 2.4 +\fBsetup\fP(2) 1.0 Removed in 2.2 +\fBsetxattr\fP(2) 2.6; 2.4.18 +\fBsgetmask\fP(2) 1.0 +\fBshmat\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBshmctl\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBshmdt\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBshmget\fP(2) 2.0 See notes on \fBipc\fP(2) +\fBshutdown\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBsigaction\fP(2) 1.0 +\fBsigaltstack\fP(2) 2.2 +\fBsignal\fP(2) 1.0 +\fBsignalfd\fP(2) 2.6.22 +\fBsignalfd4\fP(2) 2.6.27 +\fBsigpending\fP(2) 1.0 +\fBsigprocmask\fP(2) 1.0 +\fBsigreturn\fP(2) 1.0 +\fBsigsuspend\fP(2) 1.0 +\fBsocket\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBsocketcall\fP(2) 1.0 +.\" Implements BSD socket calls +\fBsocketpair\fP(2) 2.0 See notes on \fBsocketcall\fP(2) +\fBsplice\fP(2) 2.6.17 +\fBspu_create\fP(2) 2.6.16 PowerPC only +\fBspu_run\fP(2) 2.6.16 PowerPC only +\fBssetmask\fP(2) 1.0 +\fBstat\fP(2) 1.0 +\fBstat64\fP(2) 2.4 +\fBstatfs\fP(2) 1.0 +\fBstatfs64\fP(2) 2.6 +\fBstatx\fP(2) 4.11 +\fBstime\fP(2) 1.0 +\fBsubpage_prot\fP(2) 2.6.25 PowerPC only +\fBswapoff\fP(2) 1.0 +\fBswapon\fP(2) 1.0 +\fBsymlink\fP(2) 1.0 +\fBsymlinkat\fP(2) 2.6.16 +\fBsync\fP(2) 1.0 +\fBsync_file_range\fP(2) 2.6.17 +\fBsync_file_range2\fP(2) 2.6.22 +.\" PowerPC, ARM, tile +.\" First appeared on ARM, as arm_sync_file_range(), but later renamed +.\" \fBsys_debug_setcontext\fP(2) ??? PowerPC if CONFIG_PPC32 +\fBsyncfs\fP(2) 2.6.39 +\fBsysfs\fP(2) 1.2 +\fBsysinfo\fP(2) 1.0 +\fBsyslog\fP(2) 1.0 +.\" glibc interface is \fBklogctl\fP(3) +\fBtee\fP(2) 2.6.17 +\fBtgkill\fP(2) 2.6 +\fBtime\fP(2) 1.0 +\fBtimer_create\fP(2) 2.6 +\fBtimer_delete\fP(2) 2.6 +\fBtimer_getoverrun\fP(2) 2.6 +\fBtimer_gettime\fP(2) 2.6 +\fBtimer_settime\fP(2) 2.6 +\fBtimerfd_create\fP(2) 2.6.25 +\fBtimerfd_gettime\fP(2) 2.6.25 +\fBtimerfd_settime\fP(2) 2.6.25 +\fBtimes\fP(2) 1.0 +\fBtkill\fP(2) 2.6; 2.4.22 +\fBtruncate\fP(2) 1.0 +\fBtruncate64\fP(2) 2.4 +\fBugetrlimit\fP(2) 2.4 +\fBumask\fP(2) 1.0 +\fBumount\fP(2) 1.0 +.\" sys_oldumount() -- __NR_umount +\fBumount2\fP(2) 2.2 +.\" sys_umount() -- __NR_umount2 +\fBuname\fP(2) 1.0 +\fBunlink\fP(2) 1.0 +\fBunlinkat\fP(2) 2.6.16 +\fBunshare\fP(2) 2.6.16 +\fBuselib\fP(2) 1.0 +\fBustat\fP(2) 1.0 +\fBuserfaultfd\fP(2) 4.3 +\fButime\fP(2) 1.0 +\fButimensat\fP(2) 2.6.22 +\fButimes\fP(2) 2.2 +\fButrap_install\fP(2) 2.2 Sparc only +.\" FIXME . document utrap_install() +.\" There's a man page for Solaris 5.11 +\fBvfork\fP(2) 2.2 +\fBvhangup\fP(2) 1.0 +\fBvm86old\fP(2) 1.0 T{ +Was "vm86"; renamed in +2.0.28/2.2 +T} +\fBvm86\fP(2) 2.0.28; 2.2 +\fBvmsplice\fP(2) 2.6.17 +\fBwait4\fP(2) 1.0 +\fBwaitid\fP(2) 2.6.10 +\fBwaitpid\fP(2) 1.0 +\fBwrite\fP(2) 1.0 +\fBwritev\fP(2) 2.0 +.TE +.ad +.PP +On many platforms, including x86-32, socket calls are all multiplexed +(via glibc wrapper functions) through +.BR socketcall (2) +and similarly System\ V IPC calls are multiplexed through +.BR ipc (2). +.PP +Although slots are reserved for them in the system call table, +the following system calls are not implemented in the standard kernel: +.BR afs_syscall (2), \" __NR_afs_syscall is 53 on Linux 2.6.22/i386 +.BR break (2), \" __NR_break is 17 on Linux 2.6.22/i386 +.BR ftime (2), \" __NR_ftime is 35 on Linux 2.6.22/i386 +.BR getpmsg (2), \" __NR_getpmsg is 188 on Linux 2.6.22/i386 +.BR gtty (2), \" __NR_gtty is 32 on Linux 2.6.22/i386 +.BR idle (2), \" __NR_idle is 112 on Linux 2.6.22/i386 +.BR lock (2), \" __NR_lock is 53 on Linux 2.6.22/i386 +.BR madvise1 (2), \" __NR_madvise1 is 219 on Linux 2.6.22/i386 +.BR mpx (2), \" __NR_mpx is 66 on Linux 2.6.22/i386 +.BR phys (2), \" Slot has been reused +.BR prof (2), \" __NR_prof is 44 on Linux 2.6.22/i386 +.BR profil (2), \" __NR_profil is 98 on Linux 2.6.22/i386 +.BR putpmsg (2), \" __NR_putpmsg is 189 on Linux 2.6.22/i386 +.\" __NR_security is 223 on Linux 2.4/i386; absent on 2.6/i386, present +.\" on a couple of 2.6 architectures +.BR security (2), \" __NR_security is 223 on Linux 2.4/i386 +.\" The security call is for future use. +.BR stty (2), \" __NR_stty is 31 on Linux 2.6.22/i386 +.BR tuxcall (2), \" __NR_tuxcall is 184 on x86_64, also on PPC and alpha +.BR ulimit (2), \" __NR_ulimit is 58 on Linux 2.6.22/i386 +and +.BR vserver (2) \" __NR_vserver is 273 on Linux 2.6.22/i386 +(see also +.BR unimplemented (2)). +However, +.BR ftime (3), +.BR profil (3), +and +.BR ulimit (3) +exist as library routines. +The slot for +.BR phys (2) +is in use since kernel 2.1.116 for +.BR umount (2); +.BR phys (2) +will never be implemented. +The +.BR getpmsg (2) +and +.BR putpmsg (2) +calls are for kernels patched to support STREAMS, +and may never be in the standard kernel. +.PP +There was briefly +.BR set_zone_reclaim (2), +added in Linux 2.6.13, and removed in 2.6.16; +this system call was never available to user space. +.SH NOTES +.PP +Roughly speaking, the code belonging to the system call +with number __NR_xxx defined in +.I /usr/include/asm/unistd.h +can be found in the Linux kernel source in the routine +.IR sys_xxx (). +(The dispatch table for i386 can be found in +.IR /usr/src/linux/arch/i386/kernel/entry.S .) +There are many exceptions, however, mostly because +older system calls were superseded by newer ones, +and this has been treated somewhat unsystematically. +On platforms with +proprietary operating-system emulation, +such as parisc, sparc, sparc64, and alpha, +there are many additional system calls; mips64 also contains a full +set of 32-bit system calls. +.PP +Over time, changes to the interfaces of some system calls have been +necessary. +One reason for such changes was the need to increase the size of +structures or scalar values passed to the system call. +Because of these changes, certain architectures +(notably, longstanding 32-bit architectures such as i386) +now have various groups of related system calls (e.g., +.BR truncate (2) +and +.BR truncate64 (2)) +which perform similar tasks, but which vary in +details such as the size of their arguments. +(As noted earlier, applications are generally unaware of this: +the glibc wrapper functions do some work to ensure that the right +system call is invoked, and that ABI compatibility is +preserved for old binaries.) +Examples of systems calls that exist in multiple versions are +the following: +.IP * 3 +By now there are three different versions of +.BR stat (2): +.IR sys_stat () +(slot +.IR __NR_oldstat ), +.IR sys_newstat () +(slot +.IR __NR_stat ), +and +.IR sys_stat64 () +(slot +.IR __NR_stat64 ), +with the last being the most current. +.\" e.g., on 2.6.22/i386: __NR_oldstat 18, __NR_stat 106, __NR_stat64 195 +.\" The stat system calls deal with three different data structures, +.\" defined in include/asm-i386/stat.h: __old_kernel_stat, stat, stat64 +A similar story applies for +.BR lstat (2) +and +.BR fstat (2). +.IP * +Similarly, the defines +.IR __NR_oldolduname , +.IR __NR_olduname , +and +.I __NR_uname +refer to the routines +.IR sys_olduname (), +.IR sys_uname () +and +.IR sys_newuname (). +.IP * +In Linux 2.0, a new version of +.BR vm86 (2) +appeared, with the old and the new kernel routines being named +.IR sys_vm86old () +and +.IR sys_vm86 (). +.IP * +In Linux 2.4, a new version of +.BR getrlimit (2) +appeared, with the old and the new kernel routines being named +.IR sys_old_getrlimit () +(slot +.IR __NR_getrlimit ) +and +.IR sys_getrlimit () +(slot +.IR __NR_ugetrlimit ). +.IP * +Linux 2.4 increased the size of user and group IDs from 16 to 32 bits. +.\" 64-bit off_t changes: ftruncate64, *stat64, +.\" fcntl64 (because of the flock structure), getdents64, *statfs64 +To support this change, a range of system calls were added +(e.g., +.BR chown32 (2), +.BR getuid32 (2), +.BR getgroups32 (2), +.BR setresuid32 (2)), +superseding earlier calls of the same name without the +"32" suffix. +.IP * +Linux 2.4 added support for applications on 32-bit architectures +to access large files (i.e., files for which the sizes and +file offsets can't be represented in 32 bits.) +To support this change, replacements were required for system calls +that deal with file offsets and sizes. +Thus the following system calls were added: +.BR fcntl64 (2), +.BR getdents64 (2), +.BR stat64 (2), +.BR statfs64 (2), +.BR truncate64 (2), +and their analogs that work with file descriptors or +symbolic links. +These system calls supersede the older system calls +which, except in the case of the "stat" calls, +have the same name without the "64" suffix. +.IP +On newer platforms that only have 64-bit file access and 32-bit UIDs/GIDs +(e.g., alpha, ia64, s390x, x86-64), there is just a single version of +the UID/GID and file access system calls. +On platforms (typically, 32-bit platforms) where the *64 and *32 calls exist, +the other versions are obsolete. +.IP * +The +.I rt_sig* +calls were added in kernel 2.2 to support the addition +of real-time signals (see +.BR signal (7)). +These system calls supersede the older system calls of the same +name without the "rt_" prefix. +.IP * +The +.BR select (2) +and +.BR mmap (2) +system calls use five or more arguments, +which caused problems in the way +argument passing on the i386 used to be set up. +Thus, while other architectures have +.IR sys_select () +and +.IR sys_mmap () +corresponding to +.I __NR_select +and +.IR __NR_mmap , +on i386 one finds +.IR old_select () +and +.IR old_mmap () +(routines that use a pointer to an +argument block) instead. +These days passing five arguments +is not a problem any more, and there is a +.I __NR__newselect +.\" (used by libc 6) +that corresponds directly to +.IR sys_select () +and similarly +.IR __NR_mmap2 . +.\" .PP +.\" Two system call numbers, +.\" .IR __NR__llseek +.\" and +.\" .IR __NR__sysctl +.\" have an additional underscore absent in +.\" .IR sys_llseek () +.\" and +.\" .IR sys_sysctl (). +.\" +.\" In kernel 2.1.81, +.\" .BR lchown (2) +.\" and +.\" .BR chown (2) +.\" were swapped; that is, +.\" .BR lchown (2) +.\" was added with the semantics that were then current for +.\" .BR chown (2), +.\" and the semantics of the latter call were changed to what +.\" they are today. +.SH SEE ALSO +.BR intro (2), +.BR syscall (2), +.BR unimplemented (2), +.BR errno (3), +.BR libc (7), +.BR vdso (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sysctl.2 b/man2/sysctl.2 new file mode 100644 index 0000000..849f1b5 --- /dev/null +++ b/man2/sysctl.2 @@ -0,0 +1,190 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Written 11 April 1996 by Andries Brouwer +.\" 960412: Added comments from Stephen Tweedie +.\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond +.\" Modified Mon Jan 5 20:31:04 1998 by aeb. +.\" +.TH SYSCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sysctl \- read/write system parameters +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int _sysctl(struct __sysctl_args *" args ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.B Do not use this system call! +See NOTES. +.PP +The +.BR _sysctl () +call reads and/or writes kernel parameters. +For example, the hostname, +or the maximum number of open files. +The argument has the form +.PP +.in +4n +.EX +struct __sysctl_args { + int *name; /* integer vector describing variable */ + int nlen; /* length of this vector */ + void *oldval; /* 0 or address where to store old value */ + size_t *oldlenp; /* available room for old value, + overwritten by actual size of old value */ + void *newval; /* 0 or address of new value */ + size_t newlen; /* size of new value */ +}; +.EE +.in +.PP +This call does a search in a tree structure, possibly resembling +a directory tree under +.IR /proc/sys , +and if the requested item is found calls some appropriate routine +to read or modify the value. +.SH RETURN VALUE +Upon successful completion, +.BR _sysctl () +returns 0. +Otherwise, a value of \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.BR EACCES ", " EPERM +No search permission for one of the encountered "directories", +or no read permission where +.I oldval +was nonzero, or no write permission where +.I newval +was nonzero. +.TP +.B EFAULT +The invocation asked for the previous value by setting +.I oldval +non-NULL, but allowed zero room in +.IR oldlenp . +.TP +.B ENOTDIR +.I name +was not found. +.SH CONFORMING TO +This call is Linux-specific, and should not be used in programs +intended to be portable. +A +.BR sysctl () +call has been present in Linux since version 1.3.57. +It originated in +4.4BSD. +Only Linux has the +.I /proc/sys +mirror, and the object naming schemes differ between Linux and 4.4BSD, +but the declaration of the +.BR sysctl () +function is the same in both. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +Or rather... +.I don't +call it: +use of this system call has long been discouraged, +and it is so unloved that +\fBit is likely to disappear in a future kernel version\fP. +.\" See http://lwn.net/Articles/247243/ +Since Linux 2.6.24, +uses of this system call result in warnings in the kernel log. +.\" Though comments in suggest that it is needed by old glibc binaries, +.\" so maybe it's not going away. +Remove it from your programs now; use the +.I /proc/sys +interface instead. +.PP +This system call is available only if the kernel was configured with the +.B CONFIG_SYSCTL_SYSCALL +option. +.SH BUGS +The object names vary between kernel versions, +making this system call worthless for applications. +.PP +Not all available objects are properly documented. +.PP +It is not yet possible to change operating system by writing to +.IR /proc/sys/kernel/ostype . +.SH EXAMPLE +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +int _sysctl(struct __sysctl_args *args ); + +#define OSNAMESZ 100 + +int +main(void) +{ + struct __sysctl_args args; + char osname[OSNAMESZ]; + size_t osnamelth; + int name[] = { CTL_KERN, KERN_OSTYPE }; + + memset(&args, 0, sizeof(struct __sysctl_args)); + args.name = name; + args.nlen = sizeof(name)/sizeof(name[0]); + args.oldval = osname; + args.oldlenp = &osnamelth; + + osnamelth = sizeof(osname); + + if (syscall(SYS__sysctl, &args) == \-1) { + perror("_sysctl"); + exit(EXIT_FAILURE); + } + printf("This machine is running %*s\\n", osnamelth, osname); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR proc (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sysfs.2 b/man2/sysfs.2 new file mode 100644 index 0000000..f7f7832 --- /dev/null +++ b/man2/sysfs.2 @@ -0,0 +1,121 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created Wed Aug 9 1995 Thomas K. Dyas +.\" +.TH SYSFS 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sysfs \- get filesystem type information +.SH SYNOPSIS +.BI "int sysfs(int " option ", const char *" fsname ); +.PP +.BI "int sysfs(int " option ", unsigned int " fs_index ", char *" buf ); +.PP +.BI "int sysfs(int " option ); +.SH DESCRIPTION +.BR "Note" : +if you are looking for information about the +.B sysfs +filesystem that is normally mounted at +.IR /sys , +see +.BR sysfs (5). +.PP +The (obsolete) +.BR sysfs () +system call returns information about the filesystem types +currently present in the kernel. +The specific form of the +.BR sysfs () +call and the information returned depends on the +.I option +in effect: +.TP 3 +.B 1 +Translate the filesystem identifier string +.I fsname +into a filesystem type index. +.TP +.B 2 +Translate the filesystem type index +.I fs_index +into a null-terminated filesystem identifier string. +This string will +be written to the buffer pointed to by +.IR buf . +Make sure that +.I buf +has enough space to accept the string. +.TP +.B 3 +Return the total number of filesystem types currently present in the +kernel. +.PP +The numbering of the filesystem type indexes begins with zero. +.SH RETURN VALUE +On success, +.BR sysfs () +returns the filesystem index for option +.BR 1 , +zero for option +.BR 2 , +and the number of currently configured filesystems for option +.BR 3 . +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.RI "Either " fsname " or " buf +is outside your accessible address space. +.TP +.B EINVAL +.I fsname +is not a valid filesystem type identifier; +.I fs_index +is out-of-bounds; +.I option +is invalid. +.SH CONFORMING TO +SVr4. +.SH NOTES +This System-V derived system call is obsolete; don't use it. +On systems with +.IR /proc , +the same information can be obtained via +.IR /proc/filesystems ; +use that interface instead. +.SH BUGS +There is no libc or glibc support. +There is no way to guess how large \fIbuf\fP should be. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/sysinfo.2 b/man2/sysinfo.2 new file mode 100644 index 0000000..3260f9c --- /dev/null +++ b/man2/sysinfo.2 @@ -0,0 +1,132 @@ +.\" Copyright (C) 2016, Michael Kerrisk +.\" Based on an earlier version of the page where a few pieces were +.\" copyright (C) 1993 by Dan Miner (dminer@nyx.cs.du.edu) and subsequently +.\" others (see old changelog below). +.\" The structure definitions are taken more or less straight from the kernel +.\" source files. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.\" Modified Sat Jul 24 12:35:12 1993 by Rik Faith +.\" Modified Tue Oct 22 22:29:51 1996 by Eric S. Raymond +.\" Modified Mon Aug 25 16:06:11 1997 by Nicolás Lichtmaier +.\" +.TH SYSINFO 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sysinfo \- return system information +.SH SYNOPSIS +.B #include +.PP +.BI "int sysinfo(struct sysinfo *" info ); +.SH DESCRIPTION +.BR sysinfo () +returns certain statistics on memory and swap usage, +as well as the load average. +.PP +Until Linux 2.3.16, +.BR sysinfo () +returned information in the following structure: +.PP +.in +4n +.EX +struct sysinfo { + long uptime; /* Seconds since boot */ + unsigned long loads[3]; /* 1, 5, and 15 minute load averages */ + unsigned long totalram; /* Total usable main memory size */ + unsigned long freeram; /* Available memory size */ + unsigned long sharedram; /* Amount of shared memory */ + unsigned long bufferram; /* Memory used by buffers */ + unsigned long totalswap; /* Total swap space size */ + unsigned long freeswap; /* Swap space still available */ + unsigned short procs; /* Number of current processes */ + char _f[22]; /* Pads structure to 64 bytes */ +}; +.EE +.in +.PP +In the above structure, the sizes of the memory and swap fields +are given in bytes. +.PP +Since Linux 2.3.23 (i386) and Linux 2.3.48 +(all architectures) the structure is: +.PP +.in +4n +.EX +struct sysinfo { + long uptime; /* Seconds since boot */ + unsigned long loads[3]; /* 1, 5, and 15 minute load averages */ + unsigned long totalram; /* Total usable main memory size */ + unsigned long freeram; /* Available memory size */ + unsigned long sharedram; /* Amount of shared memory */ + unsigned long bufferram; /* Memory used by buffers */ + unsigned long totalswap; /* Total swap space size */ + unsigned long freeswap; /* Swap space still available */ + unsigned short procs; /* Number of current processes */ + unsigned long totalhigh; /* Total high memory size */ + unsigned long freehigh; /* Available high memory size */ + unsigned int mem_unit; /* Memory unit size in bytes */ + char _f[20\-2*sizeof(long)\-sizeof(int)]; + /* Padding to 64 bytes */ +}; +.EE +.in +.PP +In the above structure, +sizes of the memory and swap fields are given as multiples of +.I mem_unit +bytes. +.SH RETURN VALUE +On success, +.BR sysinfo () +returns zero. +On error, \-1 is returned, and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.TP +.B EFAULT +.IR info +is not a valid address. +.SH VERSIONS +.BR sysinfo () +first appeared in Linux 0.98.pl6. +.SH CONFORMING TO +This function is Linux-specific, and should not be used in programs +intended to be portable. +.SH NOTES +All of the information provided by this system call is also available via +.IR /proc/meminfo +and +.IR /proc/loadavg . +.SH SEE ALSO +.BR proc (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/syslog.2 b/man2/syslog.2 new file mode 100644 index 0000000..05f8f3b --- /dev/null +++ b/man2/syslog.2 @@ -0,0 +1,398 @@ +'\" t +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2012, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" 2008-02-15, Jeremy Kerr +.\" Add info on command type 10; add details on types 6, 7, 8, & 9. +.\" 2008-02-15, Michael Kerrisk +.\" Update LOG_BUF_LEN details; update RETURN VALUE section. +.\" +.TH SYSLOG 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +syslog, klogctl \- read and/or clear kernel message ring buffer; +set console_loglevel +.SH SYNOPSIS +.nf +.BI "int syslog(int " type ", char *" bufp ", int " len ); +.B " /* No wrapper provided in glibc */" +.PP +/* The glibc interface */ +.B "#include " +.PP +.BI "int klogctl(int " type ", char *" bufp ", int " len ); +.fi +.SH DESCRIPTION +.IR Note : +Probably, you are looking for the C library function +.BR syslog (), +which talks to +.BR syslogd (8); +see +.BR syslog (3) +for details. +.PP +This page describes the kernel +.BR syslog () +system call, which is used to control the kernel +.IR printk () +buffer; the glibc wrapper function for the system call is called +.BR klogctl (). +.SS The kernel log buffer +The kernel has a cyclic buffer of length +.B LOG_BUF_LEN +in which messages given as arguments to the kernel function +.BR printk () +are stored (regardless of their log level). +In early kernels, +.B LOG_BUF_LEN +had the value 4096; +from kernel 1.3.54, it was 8192; +from kernel 2.1.113, it was 16384; +since kernel 2.4.23/2.6, the value is a kernel configuration option +.RB ( CONFIG_LOG_BUF_SHIFT , +default value dependent on the architecture). +.\" Under "General setup" ==> "Kernel log buffer size" +.\" For 2.6, precisely the option seems to have appeared in 2.5.55. +Since Linux 2.6.6, the size can be queried with command type 10 (see below). +.SS Commands +The \fItype\fP argument determines the action taken by this function. +The list below specifies the values for +.IR type . +The symbolic names are defined in the kernel source, +but are not exported to user space; +you will either need to use the numbers, or define the names yourself. +.TP +.BR SYSLOG_ACTION_CLOSE " (0)" +Close the log. +Currently a NOP. +.TP +.BR SYSLOG_ACTION_OPEN " (1)" +Open the log. +Currently a NOP. +.TP +.BR SYSLOG_ACTION_READ " (2)" +Read from the log. +The call +waits until the kernel log buffer is nonempty, and then reads +at most \fIlen\fP bytes into the buffer pointed to by +.IR bufp . +The call returns the number of bytes read. +Bytes read from the log disappear from the log buffer: +the information can be read only once. +This is the function executed by the kernel when a user program reads +.IR /proc/kmsg . +.TP +.BR SYSLOG_ACTION_READ_ALL " (3)" +Read all messages remaining in the ring buffer, +placing them in the buffer pointed to by +.IR bufp . +The call reads the last \fIlen\fP +bytes from the log buffer (nondestructively), +but will not read more than was written into the buffer since the +last "clear ring buffer" command (see command 5 below)). +The call returns the number of bytes read. +.TP +.BR SYSLOG_ACTION_READ_CLEAR " (4)" +Read and clear all messages remaining in the ring buffer. +The call does precisely the same as for a +.I type +of 3, but also executes the "clear ring buffer" command. +.TP +.BR SYSLOG_ACTION_CLEAR " (5)" +The call executes just the "clear ring buffer" command. +The +.I bufp +and +.I len +arguments are ignored. +.IP +This command does not really clear the ring buffer. +Rather, it sets a kernel bookkeeping variable that +determines the results returned by commands 3 +.RB ( SYSLOG_ACTION_READ_ALL ) +and 4 +.RB ( SYSLOG_ACTION_READ_CLEAR ). +This command has no effect on commands 2 +.RB ( SYSLOG_ACTION_READ ) +and 9 +.RB ( SYSLOG_ACTION_SIZE_UNREAD ). +.TP +.BR SYSLOG_ACTION_CONSOLE_OFF " (6)" +The command saves the current value of +.I console_loglevel +and then sets +.I console_loglevel +to +.IR minimum_console_loglevel , +so that no messages are printed to the console. +Before Linux 2.6.32, +.\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245 +the command simply sets +.I console_loglevel +to +.IR minimum_console_loglevel . +See the discussion of +.IR /proc/sys/kernel/printk , +below. +.IP +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_CONSOLE_ON " (7)" +If a previous +.B SYSLOG_ACTION_CONSOLE_OFF +command has been performed, +this command restores +.I console_loglevel +to the value that was saved by that command. +Before Linux 2.6.32, +.\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245 +this command simply sets +.I console_loglevel +to +.IR default_console_loglevel . +See the discussion of +.IR /proc/sys/kernel/printk , +below. +.IP +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)" +The call sets +.I console_loglevel +to the value given in +.IR len , +which must be an integer between 1 and 8 (inclusive). +The kernel silently enforces a minimum value of +.IR minimum_console_loglevel +for +.IR len . +See the +.IR "log level" +section for details. +The +.I bufp +argument is ignored. +.TP +.BR SYSLOG_ACTION_SIZE_UNREAD " (9) (since Linux 2.4.10)" +The call +returns the number of bytes currently available to be read +from the kernel log buffer via command 2 +.RB ( SYSLOG_ACTION_READ ). +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_SIZE_BUFFER " (10) (since Linux 2.6.6)" +This command returns the total size of the kernel log buffer. +The +.I bufp +and +.I len +arguments are ignored. +.PP +All commands except 3 and 10 require privilege. +In Linux kernels before 2.6.37, +command types 3 and 10 are allowed to unprivileged processes; +since Linux 2.6.37, +these commands are allowed to unprivileged processes only if +.IR /proc/sys/kernel/dmesg_restrict +has the value 0. +Before Linux 2.6.37, "privileged" means that the caller has the +.BR CAP_SYS_ADMIN +capability. +Since Linux 2.6.37, +"privileged" means that the caller has either the +.BR CAP_SYS_ADMIN +capability (now deprecated for this purpose) or the (new) +.BR CAP_SYSLOG +capability. +.\" +.\" +.SS /proc/sys/kernel/printk +.I /proc/sys/kernel/printk +is a writable file containing four integer values that influence kernel +.I printk() +behavior when printing or logging error messages. +The four values are: +.TP +.I console_loglevel +Only messages with a log level lower than this value will +be printed to the console. +The default value for this field is +.B DEFAULT_CONSOLE_LOGLEVEL +(7), but it is set to +4 if the kernel command line contains the word "quiet", \" since Linux 2.4 +10 if the kernel command line contains the word "debug", +and to 15 in case +of a kernel fault (the 10 and 15 are just silly, and equivalent to 8). +The value of +.IR console_loglevel +can be set (to a value in the range 1\(en8) by a +.BR syslog () +call with a +.I type +of 8. +.TP +.I default_message_loglevel +This value will be used as the log level for +.IR printk() +messages that do not have an explicit level. +Up to and including Linux 2.6.38, +the hard-coded default value for this field was 4 +.RB ( KERN_WARNING ); +since Linux 2.6.39, +.\" commit 5af5bcb8d37f99ba415a1adc6da71051b84f93a5 +the default value is a defined by the kernel configuration option +.BR CONFIG_DEFAULT_MESSAGE_LOGLEVEL , +which defaults to 4. +.TP +.I minimum_console_loglevel +The value in this field is the minimum value to which +.I console_loglevel +can be set. +.TP +.I default_console_loglevel +This is the default value for +.IR console_loglevel . +.\" +.\" +.SS The log level +Every +.IR printk () +message has its own log level. +If the log level is not explicitly specified as part of the message, +it defaults to +.IR default_message_loglevel . +The conventional meaning of the log level is as follows: +.TS +lB lB lB +lB c l. +Kernel constant Level value Meaning +KERN_EMERG 0 System is unusable +KERN_ALERT 1 Action must be taken immediately +KERN_CRIT 2 Critical conditions +KERN_ERR 3 Error conditions +KERN_WARNING 4 Warning conditions +KERN_NOTICE 5 Normal but significant condition +KERN_INFO 6 Informational +KERN_DEBUG 7 Debug-level messages +.TE +.sp 1 +The kernel +.IR printk() +routine will print a message on the +console only if it has a log level less than the value of +.IR console_loglevel . +.SH RETURN VALUE +For \fItype\fP equal to 2, 3, or 4, a successful call to +.BR syslog () +returns the number +of bytes read. +For \fItype\fP 9, +.BR syslog () +returns the number of bytes currently +available to be read on the kernel log buffer. +For \fItype\fP 10, +.BR syslog () +returns the total size of the kernel log buffer. +For other values of \fItype\fP, 0 is returned on success. +.PP +In case of error, \-1 is returned, +and \fIerrno\fP is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Bad arguments (e.g., +bad +.IR type ; +or for +.I type +2, 3, or 4, +.I buf +is NULL, +or +.I len +is less than zero; or for +.I type +8, the +.I level +is outside the range 1 to 8). +.TP +.B ENOSYS +This +.BR syslog () +system call is not available, because the kernel was compiled with the +.BR CONFIG_PRINTK +kernel-configuration option disabled. +.TP +.B EPERM +An attempt was made to change +.I console_loglevel +or clear the kernel +message ring buffer by a process without sufficient privilege +(more precisely: without the +.B CAP_SYS_ADMIN +or +.BR CAP_SYSLOG +capability). +.TP +.B ERESTARTSYS +System call was interrupted by a signal; nothing was read. +(This can be seen only during a trace.) +.SH CONFORMING TO +This system call is Linux-specific and should not be used in programs +intended to be portable. +.SH NOTES +From the very start, people noted that it is unfortunate that +a system call and a library routine of the same name are entirely +different animals. +.\" In libc4 and libc5 the number of this call was defined by +.\" .BR SYS_klog . +.\" In glibc 2.0 the syscall is baptized +.\" .BR klogctl (). +.SH SEE ALSO +.BR dmesg (1), +.BR syslog (3), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/tee.2 b/man2/tee.2 new file mode 100644 index 0000000..7535bce --- /dev/null +++ b/man2/tee.2 @@ -0,0 +1,224 @@ +.\" This manpage is Copyright (C) 2006 Jens Axboe +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TEE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +tee \- duplicating pipe content +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "ssize_t tee(int " fd_in ", int " fd_out ", size_t " len \ +", unsigned int " flags ); +.fi +.\" Return type was long before glibc 2.7 +.SH DESCRIPTION +.\" Example programs http://brick.kernel.dk/snaps +.\" +.\" +.\" add a "tee(in, out1, out2)" system call that duplicates the pages +.\" (again, incrementing their reference count, not copying the data) from +.\" one pipe to two other pipes. +.BR tee () +duplicates up to +.I len +bytes of data from the pipe referred to by the file descriptor +.I fd_in +to the pipe referred to by the file descriptor +.IR fd_out . +It does not consume the data that is duplicated from +.IR fd_in ; +therefore, that data can be copied by a subsequent +.BR splice (2). +.PP +.I flags +is a bit mask that is composed by ORing together +zero or more of the following values: +.TP 1.9i +.B SPLICE_F_MOVE +Currently has no effect for +.BR tee (); +see +.BR splice (2). +.TP +.B SPLICE_F_NONBLOCK +Do not block on I/O; see +.BR splice (2) +for further details. +.TP +.B SPLICE_F_MORE +Currently has no effect for +.BR tee (), +but may be implemented in the future; see +.BR splice (2). +.TP +.B SPLICE_F_GIFT +Unused for +.BR tee (); +see +.BR vmsplice (2). +.SH RETURN VALUE +Upon successful completion, +.BR tee () +returns the number of bytes that were duplicated between the input +and output. +A return value of 0 means that there was no data to transfer, +and it would not make sense to block, because there are no +writers connected to the write end of the pipe referred to by +.IR fd_in . +.PP +On error, +.BR tee () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.B SPLICE_F_NONBLOCK +was specified in +.IR flags , +and the operation would block. +.TP +.B EINVAL +.I fd_in +or +.I fd_out +does not refer to a pipe; or +.I fd_in +and +.I fd_out +refer to the same pipe. +.TP +.B ENOMEM +Out of memory. +.SH VERSIONS +The +.BR tee () +system call first appeared in Linux 2.6.17; +library support was added to glibc in version 2.5. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +Conceptually, +.BR tee () +copies the data between the two pipes. +In reality no real data copying takes place though: +under the covers, +.BR tee () +assigns data to the output by merely grabbing +a reference to the input. +.SH EXAMPLE +The example below implements a basic +.BR tee (1) +program using the +.BR tee () +system call. +Here is an example of its use: +.PP +.in +4n +.EX +$ \fBdate |./a.out out.log | cat\fP +Tue Oct 28 10:06:00 CET 2014 +$ \fBcat out.log\fP +Tue Oct 28 10:06:00 CET 2014 +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + int fd; + int len, slen; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } + + do { + /* + * tee stdin to stdout. + */ + len = tee(STDIN_FILENO, STDOUT_FILENO, + INT_MAX, SPLICE_F_NONBLOCK); + + if (len < 0) { + if (errno == EAGAIN) + continue; + perror("tee"); + exit(EXIT_FAILURE); + } else + if (len == 0) + break; + + /* + * Consume stdin by splicing it to a file. + */ + while (len > 0) { + slen = splice(STDIN_FILENO, NULL, fd, NULL, + len, SPLICE_F_MOVE); + if (slen < 0) { + perror("splice"); + break; + } + len \-= slen; + } + } while (1); + + close(fd); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR splice (2), +.BR vmsplice (2), +.BR pipe (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/tgkill.2 b/man2/tgkill.2 new file mode 100644 index 0000000..82fc2d6 --- /dev/null +++ b/man2/tgkill.2 @@ -0,0 +1 @@ +.so man2/tkill.2 diff --git a/man2/time.2 b/man2/time.2 new file mode 100644 index 0000000..00a9b4d --- /dev/null +++ b/man2/time.2 @@ -0,0 +1,140 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 14:13:40 1993 by Rik Faith +.\" Additions by Joseph S. Myers , 970909 +.\" +.TH TIME 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +time \- get time in seconds +.SH SYNOPSIS +.B #include +.PP +.BI "time_t time(time_t *" tloc ); +.SH DESCRIPTION +.BR time () +returns the time as the number of seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.PP +If +.I tloc +is non-NULL, +the return value is also stored in the memory pointed to by +.IR tloc . +.SH RETURN VALUE +On success, the value of time in seconds since the Epoch is returned. +On error, \fI((time_t)\ \-1)\fP is returned, and \fIerrno\fP is set +appropriately. +.SH ERRORS +.TP +.B EFAULT +.I tloc +points outside your accessible address space (but see BUGS). +.IP +On systems where the C library +.BR time () +wrapper function invokes an implementation provided by the +.BR vdso (7) +(so that there is no trap into the kernel), +an invalid address may instead trigger a +.B SIGSEGV +signal. +.SH CONFORMING TO +SVr4, 4.3BSD, C89, C99, POSIX.1-2001. +.\" Under 4.3BSD, this call is obsoleted by +.\" .BR gettimeofday (2). +POSIX does not specify any error conditions. +.SH NOTES +POSIX.1 defines +.I seconds since the Epoch +using a formula that approximates the number of seconds between a +specified time and the Epoch. +This formula takes account of the facts that +all years that are evenly divisible by 4 are leap years, +but years that are evenly divisible by 100 are not leap years +unless they are also evenly divisible by 400, +in which case they are leap years. +This value is not the same as the actual number of seconds between the time +and the Epoch, because of leap seconds and because system clocks are not +required to be synchronized to a standard reference. +The intention is that the interpretation of seconds since the Epoch values be +consistent; see POSIX.1-2008 Rationale A.4.15 for further rationale. +.PP +On Linux, a call to +.BR time () +with +.I tloc +specified as NULL cannot fail with the error +.BR EOVERFLOW , +even on ABIs where +.I time_t +is a signed 32-bit integer and the clock ticks past the time 2**31 +(2038-01-19 03:14:08 UTC, ignoring leap seconds). +(POSIX.1 permits, but does not require, the +.B EOVERFLOW +error in the case where the seconds since the Epoch will not fit in +.IR time_t .) +Instead, the behavior on Linux is undefined when the system time is out of the +.I time_t +range. +Applications intended to run after 2038 should use ABIs with +.I time_t +wider than 32 bits. +.SH BUGS +Error returns from this system call are indistinguishable from +successful reports that the time is a few seconds +.I before +the Epoch, so the C library wrapper function never sets +.I errno +as a result of this call. +.PP +The +.I tloc +argument is obsolescent and should always be NULL in new code. +When +.I tloc +is NULL, the call cannot fail. +.\" +.SS C library/kernel differences +On some architectures, an implementation of +.BR time () +is provided in the +.BR vdso (7). +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR ctime (3), +.BR ftime (3), +.BR time (7), +.BR vdso (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/timer_create.2 b/man2/timer_create.2 new file mode 100644 index 0000000..9ecda6f --- /dev/null +++ b/man2/timer_create.2 @@ -0,0 +1,488 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TIMER_CREATE 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +timer_create \- create a POSIX per-process timer +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int timer_create(clockid_t " clockid ", struct sigevent *" sevp , +.BI " timer_t *" timerid ); +.fi +.PP +Link with \fI\-lrt\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR timer_create (): +_POSIX_C_SOURCE\ >=\ 199309L +.SH DESCRIPTION +.BR timer_create () +creates a new per-process interval timer. +The ID of the new timer is returned in the buffer pointed to by +.IR timerid , +which must be a non-null pointer. +This ID is unique within the process, until the timer is deleted. +The new timer is initially disarmed. +.PP +The +.I clockid +argument specifies the clock that the new timer uses to measure time. +It can be specified as one of the following values: +.TP +.B CLOCK_REALTIME +A settable system-wide real-time clock. +.TP +.B CLOCK_MONOTONIC +A nonsettable monotonically increasing clock that measures time +from some unspecified point in the past that does not change +after system startup. +.\" Note: the CLOCK_MONOTONIC_RAW clock added for clock_gettime() +.\" in 2.6.28 is not supported for POSIX timers -- mtk, Feb 2009 +.TP +.BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)" +A clock that measures (user and system) CPU time consumed by +(all of the threads in) the calling process. +.TP +.BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" +A clock that measures (user and system) CPU time consumed by +the calling thread. +.\" The CLOCK_MONOTONIC_RAW that was added in 2.6.28 can't be used +.\" to create a timer -- mtk, Feb 2009 +.TP +.BR CLOCK_BOOTTIME " (Since Linux 2.6.39)" +.\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0 +Like +.BR CLOCK_MONOTONIC , +this is a monotonically increasing clock. +However, whereas the +.BR CLOCK_MONOTONIC +clock does not measure the time while a system is suspended, the +.BR CLOCK_BOOTTIME +clock does include the time during which the system is suspended. +This is useful for applications that need to be suspend-aware. +.BR CLOCK_REALTIME +is not suitable for such applications, since that clock is affected +by discontinuous changes to the system clock. +.TP +.BR CLOCK_REALTIME_ALARM " (since Linux 3.0)" +.\" commit 9a7adcf5c6dea63d2e47e6f6d2f7a6c9f48b9337 +This clock is like +.BR CLOCK_REALTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.TP +.BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0)" +.\" commit 9a7adcf5c6dea63d2e47e6f6d2f7a6c9f48b9337 +This clock is like +.BR CLOCK_BOOTTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.PP +As well as the above values, +.I clockid +can be specified as the +.I clockid +returned by a call to +.BR clock_getcpuclockid (3) +or +.BR pthread_getcpuclockid (3). +.PP +The +.I sevp +argument points to a +.I sigevent +structure that specifies how the caller +should be notified when the timer expires. +For the definition and general details of this structure, see +.BR sigevent (7). +.PP +The +.I sevp.sigev_notify +field can have the following values: +.TP +.BR SIGEV_NONE +Don't asynchronously notify when the timer expires. +Progress of the timer can be monitored using +.BR timer_gettime (2). +.TP +.BR SIGEV_SIGNAL +Upon timer expiration, generate the signal +.I sigev_signo +for the process. +See +.BR sigevent (7) +for general details. +The +.I si_code +field of the +.I siginfo_t +structure will be set to +.BR SI_TIMER . +At any point in time, +at most one signal is queued to the process for a given timer; see +.BR timer_getoverrun (2) +for more details. +.TP +.BR SIGEV_THREAD +Upon timer expiration, invoke +.I sigev_notify_function +as if it were the start function of a new thread. +See +.BR sigevent (7) +for details. +.TP +.BR SIGEV_THREAD_ID " (Linux-specific)" +As for +.BR SIGEV_SIGNAL , +but the signal is targeted at the thread whose ID is given in +.IR sigev_notify_thread_id , +which must be a thread in the same process as the caller. +The +.IR sigev_notify_thread_id +field specifies a kernel thread ID, that is, the value returned by +.BR clone (2) +or +.BR gettid (2). +This flag is intended only for use by threading libraries. +.PP +Specifying +.I sevp +as NULL is equivalent to specifying a pointer to a +.I sigevent +structure in which +.I sigev_notify +is +.BR SIGEV_SIGNAL , +.I sigev_signo +is +.BR SIGALRM , +and +.I sigev_value.sival_int +is the timer ID. +.SH RETURN VALUE +On success, +.BR timer_create () +returns 0, and the ID of the new timer is placed in +.IR *timerid . +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +Temporary error during kernel allocation of timer structures. +.TP +.B EINVAL +Clock ID, +.IR sigev_notify , +.IR sigev_signo , +or +.IR sigev_notify_thread_id +is invalid. +.TP +.B ENOMEM +.\" glibc layer: malloc() +Could not allocate memory. +.SH VERSIONS +This system call is available since Linux 2.6. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +A program may create multiple interval timers using +.BR timer_create (). +.PP +Timers are not inherited by the child of a +.BR fork (2), +and are disarmed and deleted during an +.BR execve (2). +.PP +The kernel preallocates a "queued real-time signal" +for each timer created using +.BR timer_create (). +Consequently, the number of timers is limited by the +.BR RLIMIT_SIGPENDING +resource limit (see +.BR setrlimit (2)). +.PP +The timers created by +.BR timer_create () +are commonly known as "POSIX (interval) timers". +The POSIX timers API consists of the following interfaces: +.IP * 3 +.BR timer_create (): +Create a timer. +.IP * +.BR timer_settime (2): +Arm (start) or disarm (stop) a timer. +.IP * +.BR timer_gettime (2): +Fetch the time remaining until the next expiration of a timer, +along with the interval setting of the timer. +.IP * +.BR timer_getoverrun (2): +Return the overrun count for the last timer expiration. +.IP * +.BR timer_delete (2): +Disarm and delete a timer. +.PP +Since Linux 3.10, the +.IR /proc/[pid]/timers +file can be used to list the POSIX timers for the process with PID +.IR pid . +See +.BR proc (5) +for further information. +.PP +Since Linux 4.10, +.\" baa73d9e478ff32d62f3f9422822b59dd9a95a21 +support for POSIX timers is a configurable option that is enabled by default. +Kernel support can be disabled via the +.BR CONFIG_POSIX_TIMERS +option. +.\" +.SS C library/kernel differences +Part of the implementation of the POSIX timers API is provided by glibc. +.\" See nptl/sysdeps/unix/sysv/linux/timer_create.c +In particular: +.IP * 3 +Much of the functionality for +.BR SIGEV_THREAD +is implemented within glibc, rather than the kernel. +(This is necessarily so, +since the thread involved in handling the notification is one +that must be managed by the C library POSIX threads implementation.) +Although the notification delivered to the process is via a thread, +internally the NPTL implementation uses a +.I sigev_notify +value of +.BR SIGEV_THREAD_ID +along with a real-time signal that is reserved by the implementation (see +.BR nptl (7)). +.IP * +The implementation of the default case where +.I evp +is NULL is handled inside glibc, +which invokes the underlying system call with a suitably populated +.I sigevent +structure. +.IP * +The timer IDs presented at user level are maintained by glibc, +which maps these IDs to the timer IDs employed by the kernel. +.\" See the glibc source file kernel-posix-timers.h for the structure +.\" that glibc uses to map user-space timer IDs to kernel timer IDs +.\" The kernel-level timer ID is exposed via siginfo.si_tid. +.PP +The POSIX timers system calls first appeared in Linux 2.6. +Prior to this, +glibc provided an incomplete user-space implementation +.RB ( CLOCK_REALTIME +timers only) using POSIX threads, +and in glibc versions before 2.17, +.\" glibc commit 93a78ac437ba44f493333d7e2a4b0249839ce460 +the implementation falls back to this technique on systems +running pre-2.6 Linux kernels. +.SH EXAMPLE +The program below takes two arguments: a sleep period in seconds, +and a timer frequency in nanoseconds. +The program establishes a handler for the signal it uses for the timer, +blocks that signal, +creates and arms a timer that expires with the given frequency, +sleeps for the specified number of seconds, +and then unblocks the timer signal. +Assuming that the timer expired at least once while the program slept, +the signal handler will be invoked, +and the handler displays some information about the timer notification. +The program terminates after one invocation of the signal handler. +.PP +In the following example run, the program sleeps for 1 second, +after creating a timer that has a frequency of 100 nanoseconds. +By the time the signal is unblocked and delivered, +there have been around ten million overruns. +.PP +.in +4n +.EX +$ \fB./a.out 1 100\fP +Establishing handler for signal 34 +Blocking signal 34 +timer ID is 0x804c008 +Sleeping for 1 seconds +Unblocking signal 34 +Caught signal 34 + sival_ptr = 0xbfb174f4; *sival_ptr = 0x804c008 + overrun count = 10004886 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include + +#define CLOCKID CLOCK_REALTIME +#define SIG SIGRTMIN + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +static void +print_siginfo(siginfo_t *si) +{ + timer_t *tidp; + int or; + + tidp = si\->si_value.sival_ptr; + + printf(" sival_ptr = %p; ", si\->si_value.sival_ptr); + printf(" *sival_ptr = 0x%lx\\n", (long) *tidp); + + or = timer_getoverrun(*tidp); + if (or == \-1) + errExit("timer_getoverrun"); + else + printf(" overrun count = %d\\n", or); +} + +static void +handler(int sig, siginfo_t *si, void *uc) +{ + /* Note: calling printf() from a signal handler is not safe + (and should not be done in production programs), since + printf() is not async\-signal\-safe; see signal-safety(7). + Nevertheless, we use printf() here as a simple way of + showing that the handler was called. */ + + printf("Caught signal %d\\n", sig); + print_siginfo(si); + signal(sig, SIG_IGN); +} + +int +main(int argc, char *argv[]) +{ + timer_t timerid; + struct sigevent sev; + struct itimerspec its; + long long freq_nanosecs; + sigset_t mask; + struct sigaction sa; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", + argv[0]); + exit(EXIT_FAILURE); + } + + /* Establish handler for timer signal */ + + printf("Establishing handler for signal %d\\n", SIG); + sa.sa_flags = SA_SIGINFO; + sa.sa_sigaction = handler; + sigemptyset(&sa.sa_mask); + if (sigaction(SIG, &sa, NULL) == \-1) + errExit("sigaction"); + + /* Block timer signal temporarily */ + + printf("Blocking signal %d\\n", SIG); + sigemptyset(&mask); + sigaddset(&mask, SIG); + if (sigprocmask(SIG_SETMASK, &mask, NULL) == \-1) + errExit("sigprocmask"); + + /* Create the timer */ + + sev.sigev_notify = SIGEV_SIGNAL; + sev.sigev_signo = SIG; + sev.sigev_value.sival_ptr = &timerid; + if (timer_create(CLOCKID, &sev, &timerid) == \-1) + errExit("timer_create"); + + printf("timer ID is 0x%lx\\n", (long) timerid); + + /* Start the timer */ + + freq_nanosecs = atoll(argv[2]); + its.it_value.tv_sec = freq_nanosecs / 1000000000; + its.it_value.tv_nsec = freq_nanosecs % 1000000000; + its.it_interval.tv_sec = its.it_value.tv_sec; + its.it_interval.tv_nsec = its.it_value.tv_nsec; + + if (timer_settime(timerid, 0, &its, NULL) == \-1) + errExit("timer_settime"); + + /* Sleep for a while; meanwhile, the timer may expire + multiple times */ + + printf("Sleeping for %d seconds\\n", atoi(argv[1])); + sleep(atoi(argv[1])); + + /* Unlock the timer signal, so that timer notification + can be delivered */ + + printf("Unblocking signal %d\\n", SIG); + if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == \-1) + errExit("sigprocmask"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR clock_gettime (2), +.BR setitimer (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_settime (2), +.BR timerfd_create (2), +.BR clock_getcpuclockid (3), +.BR pthread_getcpuclockid (3), +.BR pthreads (7), +.BR sigevent (7), +.BR signal (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/timer_delete.2 b/man2/timer_delete.2 new file mode 100644 index 0000000..b1b9b99 --- /dev/null +++ b/man2/timer_delete.2 @@ -0,0 +1,83 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TIMER_DELETE 2 2015-08-08 Linux "Linux Programmer's Manual" +.SH NAME +timer_delete \- delete a POSIX per-process timer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int timer_delete(timer_t " timerid ); +.fi +.PP +Link with \fI\-lrt\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR timer_delete (): +_POSIX_C_SOURCE\ >=\ 199309L +.SH DESCRIPTION +.BR timer_delete () +deletes the timer whose ID is given in +.IR timerid . +If the timer was armed at the time of this call, +it is disarmed before being deleted. +The treatment of any pending signal generated by the deleted timer +is unspecified. +.SH RETURN VALUE +On success, +.BR timer_delete () +returns 0. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I timerid +is not a valid timer ID. +.SH VERSIONS +This system call is available since Linux 2.6. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR clock_gettime (2), +.BR timer_create (2), +.BR timer_getoverrun (2), +.BR timer_settime (2), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/timer_getoverrun.2 b/man2/timer_getoverrun.2 new file mode 100644 index 0000000..2ca6e4b --- /dev/null +++ b/man2/timer_getoverrun.2 @@ -0,0 +1,149 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TIMER_GETOVERRUN 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +timer_getoverrun \- get overrun count for a POSIX per-process timer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int timer_getoverrun(timer_t " timerid ); +.fi +.PP +Link with \fI\-lrt\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR timer_getoverrun (): +_POSIX_C_SOURCE\ >=\ 199309L +.SH DESCRIPTION +.BR timer_getoverrun () +returns the "overrun count" for the timer referred to by +.IR timerid . +An application can use the overrun count to accurately calculate the number +of timer expirations that would have occurred over a given time interval. +Timer overruns can occur both when receiving expiration notifications +via signals +.RB ( SIGEV_SIGNAL ), +and via threads +.RB ( SIGEV_THREAD ). +.PP +When expiration notifications are delivered via a signal, +overruns can occur as follows. +Regardless of whether or not a real-time signal is used for +timer notifications, +the system queues at most one signal per timer. +(This is the behavior specified by POSIX.1. +The alternative, queuing one signal for each timer expiration, +could easily result in overflowing the allowed limits for +queued signals on the system.) +Because of system scheduling delays, +or because the signal may be temporarily blocked, +there can be a delay between the time when the notification +signal is generated and the time when it +is delivered (e.g., caught by a signal handler) or accepted (e.g., using +.BR sigwaitinfo (2)). +In this interval, further timer expirations may occur. +The timer overrun count is the number of additional +timer expirations that occurred between the time when the signal +was generated and when it was delivered or accepted. +.PP +Timer overruns can also occur when expiration notifications +are delivered via invocation of a thread, +since there may be an arbitrary delay between an expiration of the timer +and the invocation of the notification thread, +and in that delay interval, additional timer expirations may occur. +.SH RETURN VALUE +On success, +.BR timer_getoverrun () +returns the overrun count of the specified timer; +this count may be 0 if no overruns have occurred. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I timerid +is not a valid timer ID. +.SH VERSIONS +This system call is available since Linux 2.6. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +When timer notifications are delivered via signals +.RB ( SIGEV_SIGNAL ), +on Linux it is also possible to obtain the overrun count via the +.I si_overrun +field of the +.I siginfo_t +structure (see +.BR sigaction (2)). +This allows an application to avoid the overhead of making +a system call to obtain the overrun count, +but is a nonportable extension to POSIX.1. +.PP +POSIX.1 discusses timer overruns only in the context of +timer notifications using signals. +.\" FIXME . Austin bug filed, 11 Feb 09 +.SH BUGS +POSIX.1 specifies that if the timer overrun count +is equal to or greater than an implementation-defined maximum, +.BR DELAYTIMER_MAX , +then +.BR timer_getoverrun () +should return +.BR DELAYTIMER_MAX . +However, Linux does not implement this feature: instead, +if the timer overrun value exceeds the maximum representable integer, +the counter cycles, starting once more from low values. +.\" Bug filed: http://bugzilla.kernel.org/show_bug.cgi?id=12665 +.\" http://thread.gmane.org/gmane.linux.kernel/113276/ +.SH EXAMPLE +See +.BR timer_create (2). +.SH SEE ALSO +.BR clock_gettime (2), +.BR sigaction (2), +.BR signalfd (2), +.BR sigwaitinfo (2), +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_settime (2), +.BR signal (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/timer_gettime.2 b/man2/timer_gettime.2 new file mode 100644 index 0000000..42015ca --- /dev/null +++ b/man2/timer_gettime.2 @@ -0,0 +1 @@ +.so man2/timer_settime.2 diff --git a/man2/timer_settime.2 b/man2/timer_settime.2 new file mode 100644 index 0000000..44af390 --- /dev/null +++ b/man2/timer_settime.2 @@ -0,0 +1,224 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TIMER_SETTIME 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +timer_settime, timer_gettime \- arm/disarm and fetch +state of POSIX per-process timer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int timer_settime(timer_t " timerid ", int " flags , +.BI " const struct itimerspec *" new_value , +.BI " struct itimerspec *" old_value ); +.BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value ); +.fi +.PP +Link with \fI\-lrt\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR timer_settime (), +.BR timer_gettime (): +_POSIX_C_SOURCE\ >=\ 199309L +.SH DESCRIPTION +.BR timer_settime () +arms or disarms the timer identified by +.IR timerid . +The +.I new_value +argument is pointer to an +.I itimerspec +structure that specifies the new initial value and +the new interval for the timer. +The +.I itimerspec +structure is defined as follows: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* Seconds */ + long tv_nsec; /* Nanoseconds */ +}; + +struct itimerspec { + struct timespec it_interval; /* Timer interval */ + struct timespec it_value; /* Initial expiration */ +}; +.EE +.in +.PP +Each of the substructures of the +.I itimerspec +structure is a +.I timespec +structure that allows a time value to be specified +in seconds and nanoseconds. +These time values are measured according to the clock +that was specified when the timer was created by +.BR timer_create (2). +.PP +If +.I new_value->it_value +specifies a nonzero value (i.e., either subfield is nonzero), then +.BR timer_settime () +arms (starts) the timer, +setting it to initially expire at the given time. +(If the timer was already armed, +then the previous settings are overwritten.) +If +.I new_value->it_value +specifies a zero value +(i.e., both subfields are zero), +then the timer is disarmed. +.PP +The +.I new_value->it_interval +field specifies the period of the timer, in seconds and nanoseconds. +If this field is nonzero, then each time that an armed timer expires, +the timer is reloaded from the value specified in +.IR new_value->it_interval . +If +.I new_value->it_interval +specifies a zero value, +then the timer expires just once, at the time specified by +.IR it_value . +.PP +By default, the initial expiration time specified in +.I new_value->it_value +is interpreted relative to the current time on the timer's +clock at the time of the call. +This can be modified by specifying +.B TIMER_ABSTIME +in +.IR flags , +in which case +.I new_value->it_value +is interpreted as an absolute value as measured on the timer's clock; +that is, the timer will expire when the clock value reaches the +value specified by +.IR new_value->it_value . +If the specified absolute time has already passed, +then the timer expires immediately, +and the overrun count (see +.BR timer_getoverrun (2)) +will be set correctly. +.\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME. +.PP +If the value of the +.B CLOCK_REALTIME +clock is adjusted while an absolute timer based on that clock is armed, +then the expiration of the timer will be appropriately adjusted. +Adjustments to the +.B CLOCK_REALTIME +clock have no effect on relative timers based on that clock. +.\" Similar remarks might apply with respect to process and thread CPU time +.\" clocks, but these clocks are not currently (2.6.28) settable on Linux. +.PP +If +.I old_value +is not NULL, then it points to a buffer +that is used to return the previous interval of the timer (in +.IR old_value->it_interval ) +and the amount of time until the timer +would previously have next expired (in +.IR old_value->it_value ). +.PP +.BR timer_gettime () +returns the time until next expiration, and the interval, +for the timer specified by +.IR timerid , +in the buffer pointed to by +.IR curr_value . +The time remaining until the next timer expiration is returned in +.IR curr_value->it_value ; +this is always a relative value, regardless of whether the +.BR TIMER_ABSTIME +flag was used when arming the timer. +If the value returned in +.IR curr_value->it_value +is zero, then the timer is currently disarmed. +The timer interval is returned in +.IR curr_value->it_interval . +If the value returned in +.IR curr_value->it_interval +is zero, then this is a "one-shot" timer. +.SH RETURN VALUE +On success, +.BR timer_settime () +and +.BR timer_gettime () +return 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +These functions may fail with the following errors: +.TP +.B EFAULT +.IR new_value , +.IR old_value , +or +.I curr_value +is not a valid pointer. +.TP +.B EINVAL +.I timerid +is invalid. +.\" FIXME . eventually: invalid value in flags +.PP +.BR timer_settime () +may fail with the following errors: +.TP +.B EINVAL +.I new_value.it_value +is negative; or +.I new_value.it_value.tv_nsec +is negative or greater than 999,999,999. +.SH VERSIONS +These system calls are available since Linux 2.6. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +See +.BR timer_create (2). +.SH SEE ALSO +.BR timer_create (2), +.BR timer_getoverrun (2), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2 new file mode 100644 index 0000000..de5fea5 --- /dev/null +++ b/man2/timerfd_create.2 @@ -0,0 +1,656 @@ +.\" Copyright (C) 2008 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" FIXME Linux 3.0: timerfd_settime() adds a TFD_TIMER_CANCEL_ON_SET flag; +.\" This flag needs to documented. +.\" +.TH TIMERFD_CREATE 2 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +timerfd_create, timerfd_settime, timerfd_gettime \- +timers that notify via file descriptors +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int timerfd_create(int " clockid ", int " flags ); +.PP +.BI "int timerfd_settime(int " fd ", int " flags , +.BI " const struct itimerspec *" new_value , +.BI " struct itimerspec *" old_value ); +.PP +.BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value ); +.fi +.SH DESCRIPTION +These system calls create and operate on a timer +that delivers timer expiration notifications via a file descriptor. +They provide an alternative to the use of +.BR setitimer (2) +or +.BR timer_create (2), +with the advantage that the file descriptor may be monitored by +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +.PP +The use of these three system calls is analogous to the use of +.BR timer_create (2), +.BR timer_settime (2), +and +.BR timer_gettime (2). +(There is no analog of +.BR timer_getoverrun (2), +since that functionality is provided by +.BR read (2), +as described below.) +.\" +.SS timerfd_create() +.BR timerfd_create () +creates a new timer object, +and returns a file descriptor that refers to that timer. +The +.I clockid +argument specifies the clock that is used to mark the progress +of the timer, and must one of the following: +.TP +.B CLOCK_REALTIME +A settable system-wide real-time clock. +.TP +.B CLOCK_MONOTONIC +A nonsettable monotonically increasing clock that measures time +from some unspecified point in the past that does not change +after system startup. +.TP +.BR CLOCK_BOOTTIME " (Since Linux 3.15)" +.\" commit 4a2378a943f09907fb1ae35c15de917f60289c14 +Like +.BR CLOCK_MONOTONIC , +this is a monotonically increasing clock. +However, whereas the +.BR CLOCK_MONOTONIC +clock does not measure the time while a system is suspended, the +.BR CLOCK_BOOTTIME +clock does include the time during which the system is suspended. +This is useful for applications that need to be suspend-aware. +.BR CLOCK_REALTIME +is not suitable for such applications, since that clock is affected +by discontinuous changes to the system clock. +.TP +.BR CLOCK_REALTIME_ALARM " (since Linux 3.11)" +.\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8 +This clock is like +.BR CLOCK_REALTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.TP +.BR CLOCK_BOOTTIME_ALARM " (since Linux 3.11)" +.\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8 +This clock is like +.BR CLOCK_BOOTTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.PP +The current value of each of these clocks can be retrieved using +.BR clock_gettime (2). +.PP +Starting with Linux 2.6.27, the following values may be bitwise ORed in +.IR flags +to change the behavior of +.BR timerfd_create (): +.TP 14 +.B TFD_NONBLOCK +Set the +.BR O_NONBLOCK +file status flag on the new open file description. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B TFD_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.PP +In Linux versions up to and including 2.6.26, +.I flags +must be specified as zero. +.SS timerfd_settime() +.BR timerfd_settime () +arms (starts) or disarms (stops) +the timer referred to by the file descriptor +.IR fd . +.PP +The +.I new_value +argument specifies the initial expiration and interval for the timer. +The +.I itimerspec +structure used for this argument contains two fields, +each of which is in turn a structure of type +.IR timespec : +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* Seconds */ + long tv_nsec; /* Nanoseconds */ +}; + +struct itimerspec { + struct timespec it_interval; /* Interval for periodic timer */ + struct timespec it_value; /* Initial expiration */ +}; +.EE +.in +.PP +.I new_value.it_value +specifies the initial expiration of the timer, +in seconds and nanoseconds. +Setting either field of +.I new_value.it_value +to a nonzero value arms the timer. +Setting both fields of +.I new_value.it_value +to zero disarms the timer. +.PP +Setting one or both fields of +.I new_value.it_interval +to nonzero values specifies the period, in seconds and nanoseconds, +for repeated timer expirations after the initial expiration. +If both fields of +.I new_value.it_interval +are zero, the timer expires just once, at the time specified by +.IR new_value.it_value . +.PP +By default, +the initial expiration time specified in +.I new_value +is interpreted relative to the current time +on the timer's clock at the time of the call (i.e., +.I new_value.it_value +specifies a time relative to the current value of the clock specified by +.IR clockid ). +An absolute timeout can be selected via the +.I flags +argument. +.PP +The +.I flags +argument is a bit mask that can include the following values: +.TP +.B TFD_TIMER_ABSTIME +Interpret +.I new_value.it_value +as an absolute value on the timer's clock. +The timer will expire when the value of the timer's +clock reaches the value specified in +.IR new_value.it_value . +.TP +.BR TFD_TIMER_CANCEL_ON_SET +If this flag is specified along with +.B TFD_TIMER_ABSTIME +and the clock for this timer is +.BR CLOCK_REALTIME +or +.BR CLOCK_REALTIME_ALARM , +then mark this timer as cancelable if the real-time clock +undergoes a discontinuous change +.RB ( settimeofday (2), +.BR clock_settime (2), +or similar). +When such changes occur, a current or future +.BR read (2) +from the file descriptor will fail with the error +.BR ECANCELED . +.PP +If the +.I old_value +argument is not NULL, then the +.I itimerspec +structure that it points to is used to return the setting of the timer +that was current at the time of the call; +see the description of +.BR timerfd_gettime () +following. +.\" +.SS timerfd_gettime() +.BR timerfd_gettime () +returns, in +.IR curr_value , +an +.IR itimerspec +structure that contains the current setting of the timer +referred to by the file descriptor +.IR fd . +.PP +The +.I it_value +field returns the amount of time +until the timer will next expire. +If both fields of this structure are zero, +then the timer is currently disarmed. +This field always contains a relative value, regardless of whether the +.BR TFD_TIMER_ABSTIME +flag was specified when setting the timer. +.PP +The +.I it_interval +field returns the interval of the timer. +If both fields of this structure are zero, +then the timer is set to expire just once, at the time specified by +.IR curr_value.it_value . +.SS Operating on a timer file descriptor +The file descriptor returned by +.BR timerfd_create () +supports the following operations: +.TP +.BR read (2) +If the timer has already expired one or more times since +its settings were last modified using +.BR timerfd_settime (), +or since the last successful +.BR read (2), +then the buffer given to +.BR read (2) +returns an unsigned 8-byte integer +.RI ( uint64_t ) +containing the number of expirations that have occurred. +(The returned value is in host byte order\(emthat is, +the native byte order for integers on the host machine.) +.IP +If no timer expirations have occurred at the time of the +.BR read (2), +then the call either blocks until the next timer expiration, +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking +(via the use of the +.BR fcntl (2) +.B F_SETFL +operation to set the +.B O_NONBLOCK +flag). +.IP +A +.BR read (2) +fails with the error +.B EINVAL +if the size of the supplied buffer is less than 8 bytes. +.IP +If the associated clock is either +.BR CLOCK_REALTIME +or +.BR CLOCK_REALTIME_ALARM , +the timer is absolute +.RB ( TFD_TIMER_ABSTIME ), +and the flag +.BR TFD_TIMER_CANCEL_ON_SET +was specified when calling +.BR timerfd_settime (), +then +.BR read (2) +fails with the error +.BR ECANCELED +if the real-time clock undergoes a discontinuous change. +(This allows the reading application to discover +such discontinuous changes to the clock.) +.TP +.BR poll "(2), " select "(2) (and similar)" +The file descriptor is readable +(the +.BR select (2) +.I readfds +argument; the +.BR poll (2) +.B POLLIN +flag) +if one or more timer expirations have occurred. +.IP +The file descriptor also supports the other file-descriptor +multiplexing APIs: +.BR pselect (2), +.BR ppoll (2), +and +.BR epoll (7). +.TP +.BR ioctl "(2)" +The following timerfd-specific command is supported: +.RS +.TP +.BR TFD_IOC_SET_TICKS " (since Linux 3.17)" +.\" commit 5442e9fbd7c23172a1c9bc736629cd123a9923f0 +Adjust the number of timer expirations that have occurred. +The argument is a pointer to a nonzero 8-byte integer +.RI ( uint64_t *) +containing the new number of expirations. +Once the number is set, any waiter on the timer is woken up. +The only purpose of this command is to restore the expirations +for the purpose of checkpoint/restore. +This operation is available only if the kernel was configured with the +.BR CONFIG_CHECKPOINT_RESTORE +option. +.RE +.TP +.BR close (2) +When the file descriptor is no longer required it should be closed. +When all file descriptors associated with the same timer object +have been closed, +the timer is disarmed and its resources are freed by the kernel. +.\" +.SS fork(2) semantics +After a +.BR fork (2), +the child inherits a copy of the file descriptor created by +.BR timerfd_create (). +The file descriptor refers to the same underlying +timer object as the corresponding file descriptor in the parent, +and +.BR read (2)s +in the child will return information about +expirations of the timer. +.\" +.SS execve(2) semantics +A file descriptor created by +.BR timerfd_create () +is preserved across +.BR execve (2), +and continues to generate timer expirations if the timer was armed. +.SH RETURN VALUE +On success, +.BR timerfd_create () +returns a new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.PP +.BR timerfd_settime () +and +.BR timerfd_gettime () +return 0 on success; +on error they return \-1, and set +.I errno +to indicate the error. +.SH ERRORS +.BR timerfd_create () +can fail with the following errors: +.TP +.B EINVAL +The +.I clockid +argument is neither +.B CLOCK_MONOTONIC +nor +.BR CLOCK_REALTIME ; +.TP +.B EINVAL +.I flags +is invalid; +or, in Linux 2.6.26 or earlier, +.I flags +is nonzero. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENODEV +Could not mount (internal) anonymous inode device. +.TP +.B ENOMEM +There was insufficient kernel memory to create the timer. +.PP +.BR timerfd_settime () +and +.BR timerfd_gettime () +can fail with the following errors: +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EFAULT +.IR new_value , +.IR old_value , +or +.I curr_value +is not valid a pointer. +.TP +.B EINVAL +.I fd +is not a valid timerfd file descriptor. +.PP +.BR timerfd_settime () +can also fail with the following errors: +.TP +.B EINVAL +.I new_value +is not properly initialized (one of the +.I tv_nsec +falls outside the range zero to 999,999,999). +.TP +.B EINVAL +.\" This case only checked since 2.6.29, and 2.2.2[78].some-stable-version. +.\" In older kernel versions, no check was made for invalid flags. +.I flags +is invalid. +.SH VERSIONS +These system calls are available on Linux since kernel 2.6.25. +Library support is provided by glibc since version 2.8. +.SH CONFORMING TO +These system calls are Linux-specific. +.SH BUGS +Currently, +.\" 2.6.29 +.BR timerfd_create () +supports fewer types of clock IDs than +.BR timer_create (2). +.SH EXAMPLE +The following program creates a timer and then monitors its progress. +The program accepts up to three command-line arguments. +The first argument specifies the number of seconds for +the initial expiration of the timer. +The second argument specifies the interval for the timer, in seconds. +The third argument specifies the number of times the program should +allow the timer to expire before terminating. +The second and third command-line arguments are optional. +.PP +The following shell session demonstrates the use of the program: +.PP +.in +4n +.EX +.RB "$" " a.out 3 1 100" +0.000: timer started +3.000: read: 1; total=1 +4.000: read: 1; total=2 +.BR "^Z " " # type control-Z to suspend the program" +[1]+ Stopped ./timerfd3_demo 3 1 100 +.RB "$ " "fg" " # Resume execution after a few seconds" +a.out 3 1 100 +9.660: read: 5; total=7 +10.000: read: 1; total=8 +11.000: read: 1; total=9 +.BR "^C " " # type control-C to suspend the program" +.EE +.in +.SS Program source +\& +.EX +.\" The commented out code here is what we currently need until +.\" the required stuff is in glibc +.\" +.\" +.\"/* Link with -lrt */ +.\"#define _GNU_SOURCE +.\"#include +.\"#include +.\"#include +.\"#if defined(__i386__) +.\"#define __NR_timerfd_create 322 +.\"#define __NR_timerfd_settime 325 +.\"#define __NR_timerfd_gettime 326 +.\"#endif +.\" +.\"static int +.\"timerfd_create(int clockid, int flags) +.\"{ +.\" return syscall(__NR_timerfd_create, clockid, flags); +.\"} +.\" +.\"static int +.\"timerfd_settime(int fd, int flags, struct itimerspec *new_value, +.\" struct itimerspec *curr_value) +.\"{ +.\" return syscall(__NR_timerfd_settime, fd, flags, new_value, +.\" curr_value); +.\"} +.\" +.\"static int +.\"timerfd_gettime(int fd, struct itimerspec *curr_value) +.\"{ +.\" return syscall(__NR_timerfd_gettime, fd, curr_value); +.\"} +.\" +.\"#define TFD_TIMER_ABSTIME (1 << 0) +.\" +.\"//////////////////////////////////////////////////////////// +#include +#include +#include +#include +#include +#include /* Definition of uint64_t */ + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +static void +print_elapsed_time(void) +{ + static struct timespec start; + struct timespec curr; + static int first_call = 1; + int secs, nsecs; + + if (first_call) { + first_call = 0; + if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1) + handle_error("clock_gettime"); + } + + if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1) + handle_error("clock_gettime"); + + secs = curr.tv_sec \- start.tv_sec; + nsecs = curr.tv_nsec \- start.tv_nsec; + if (nsecs < 0) { + secs\-\-; + nsecs += 1000000000; + } + printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000); +} + +int +main(int argc, char *argv[]) +{ + struct itimerspec new_value; + int max_exp, fd; + struct timespec now; + uint64_t exp, tot_exp; + ssize_t s; + + if ((argc != 2) && (argc != 4)) { + fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\\n", + argv[0]); + exit(EXIT_FAILURE); + } + + if (clock_gettime(CLOCK_REALTIME, &now) == \-1) + handle_error("clock_gettime"); + + /* Create a CLOCK_REALTIME absolute timer with initial + expiration and interval as specified in command line */ + + new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]); + new_value.it_value.tv_nsec = now.tv_nsec; + if (argc == 2) { + new_value.it_interval.tv_sec = 0; + max_exp = 1; + } else { + new_value.it_interval.tv_sec = atoi(argv[2]); + max_exp = atoi(argv[3]); + } + new_value.it_interval.tv_nsec = 0; + + fd = timerfd_create(CLOCK_REALTIME, 0); + if (fd == \-1) + handle_error("timerfd_create"); + + if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1) + handle_error("timerfd_settime"); + + print_elapsed_time(); + printf("timer started\\n"); + + for (tot_exp = 0; tot_exp < max_exp;) { + s = read(fd, &exp, sizeof(uint64_t)); + if (s != sizeof(uint64_t)) + handle_error("read"); + + tot_exp += exp; + print_elapsed_time(); + printf("read: %llu; total=%llu\\n", + (unsigned long long) exp, + (unsigned long long) tot_exp); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR eventfd (2), +.BR poll (2), +.BR read (2), +.BR select (2), +.BR setitimer (2), +.BR signalfd (2), +.BR timer_create (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR epoll (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/timerfd_gettime.2 b/man2/timerfd_gettime.2 new file mode 100644 index 0000000..6d12940 --- /dev/null +++ b/man2/timerfd_gettime.2 @@ -0,0 +1 @@ +.so man2/timerfd_create.2 diff --git a/man2/timerfd_settime.2 b/man2/timerfd_settime.2 new file mode 100644 index 0000000..6d12940 --- /dev/null +++ b/man2/timerfd_settime.2 @@ -0,0 +1 @@ +.so man2/timerfd_create.2 diff --git a/man2/times.2 b/man2/times.2 new file mode 100644 index 0000000..4295fd1 --- /dev/null +++ b/man2/times.2 @@ -0,0 +1,226 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 14:29:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 961203 and 001211 and 010326 by aeb@cwi.nl +.\" Modified 001213 by Michael Haardt (michael@moria.de) +.\" Modified 13 Jun 02, Michael Kerrisk +.\" Added note on nonstandard behavior when SIGCHLD is ignored. +.\" Modified 2004-11-16, mtk, Noted that the nonconformance when +.\" SIGCHLD is being ignored is fixed in 2.6.9; other minor changes +.\" Modified 2004-12-08, mtk, in 2.6 times() return value changed +.\" 2005-04-13, mtk +.\" Added notes on nonstandard behavior: Linux allows 'buf' to +.\" be NULL, but POSIX.1 doesn't specify this and it's nonportable. +.\" +.TH TIMES 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +times \- get process times +.SH SYNOPSIS +.B #include +.PP +.BI "clock_t times(struct tms *" buf ); +.SH DESCRIPTION +.BR times () +stores the current process times in the +.I "struct tms" +that +.I buf +points to. +The +.I struct tms +is as defined in +.IR : +.PP +.in +4n +.EX +struct tms { + clock_t tms_utime; /* user time */ + clock_t tms_stime; /* system time */ + clock_t tms_cutime; /* user time of children */ + clock_t tms_cstime; /* system time of children */ +}; +.EE +.in +.PP +The +.I tms_utime +field contains the CPU time spent executing instructions +of the calling process. +The +.I tms_stime +field contains the CPU time spent executing inside the kernel +while performing tasks on behalf of the calling process. +.PP +The +.I tms_cutime +field contains the sum of the +.I tms_utime +and +.I tms_cutime +values for all waited-for terminated children. +The +.I tms_cstime +field contains the sum of the +.I tms_stime +and +.I tms_cstime +values for all waited-for terminated children. +.PP +Times for terminated children (and their descendants) +are added in at the moment +.BR wait (2) +or +.BR waitpid (2) +returns their process ID. +In particular, times of grandchildren +that the children did not wait for are never seen. +.PP +All times reported are in clock ticks. +.SH RETURN VALUE +.BR times () +returns the number of clock ticks that have elapsed since +an arbitrary point in the past. +The return value may overflow the possible range of type +.IR clock_t . +On error, \fI(clock_t)\ \-1\fP is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I tms +points outside the process's address space. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +The number of clock ticks per second can be obtained using: +.PP +.in +4n +.EX +sysconf(_SC_CLK_TCK); +.EE +.in +.PP +In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in +.IR ) +is mentioned as obsolescent. +It is obsolete now. +.PP +In Linux kernel versions before 2.6.9, +if the disposition of +.B SIGCHLD +is set to +.BR SIG_IGN , +then the times of terminated children +are automatically included in the +.I tms_cstime +and +.I tms_cutime +fields, although POSIX.1-2001 says that this should happen +only if the calling process +.BR wait (2)s +on its children. +This nonconformance is rectified in Linux 2.6.9 and later. +.\" See the description of times() in XSH, which says: +.\" The times of a terminated child process are included... when wait() +.\" or waitpid() returns the process ID of this terminated child. +.PP +On Linux, the +.I buf +argument can be specified as NULL, with the result that +.BR times () +just returns a function result. +However, POSIX does not specify this behavior, and most +other UNIX implementations require a non-NULL value for +.IR buf . +.PP +Note that +.BR clock (3) +also returns a value of type +.IR clock_t , +but this value is measured in units of +.BR CLOCKS_PER_SEC , +not the clock ticks used by +.BR times (). +.PP +On Linux, the "arbitrary point in the past" from which the return value of +.BR times () +is measured has varied across kernel versions. +On Linux 2.4 and earlier, this point is the moment the system was booted. +Since Linux 2.6, this point is \fI(2^32/HZ) \- 300\fP +seconds before system boot time. +This variability across kernel versions (and across UNIX implementations), +combined with the fact that the returned value may overflow the range of +.IR clock_t , +means that a portable application would be wise to avoid using this value. +To measure changes in elapsed time, use +.BR clock_gettime (2) +instead. +.\" .PP +.\" On older systems the number of clock ticks per second is given +.\" by the variable HZ. +.SS Historical +SVr1-3 returns +.I long +and the struct members are of type +.I time_t +although they store clock ticks, not seconds since the Epoch. +V7 used +.I long +for the struct members, because it had no type +.I time_t +yet. +.SH BUGS +A limitation of the Linux system call conventions on some architectures +(notably i386) means that on Linux 2.6 there is a small time window +(41 seconds) soon after boot when +.BR times () +can return \-1, falsely indicating that an error occurred. +The same problem can occur when the return value wraps past +the maximum value that can be stored in +.BR clock_t . +.\" The problem is that a syscall return of -4095 to -1 +.\" is interpreted by glibc as an error, and the wrapper converts +.\" the return value to -1. +.\" http://marc.info/?l=linux-kernel&m=119447727031225&w=2 +.\" "compat_sys_times() bogus until jiffies >= 0" +.\" November 2007 +.SH SEE ALSO +.BR time (1), +.BR getrusage (2), +.BR wait (2), +.BR clock (3), +.BR sysconf (3), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/tkill.2 b/man2/tkill.2 new file mode 100644 index 0000000..ef9eedb --- /dev/null +++ b/man2/tkill.2 @@ -0,0 +1,151 @@ +.\" Copyright (C) 2008 Michael Kerrisk +.\" and Copyright 2003 Abhijit Menon-Sen +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2004-05-31, added tgkill, ahu, aeb +.\" 2008-01-15 mtk -- rewrote DESCRIPTION +.\" +.TH TKILL 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +tkill, tgkill \- send a signal to a thread +.SH SYNOPSIS +.nf +.BI "int tkill(int " tid ", int " sig ); +.PP +.BI "int tgkill(int " tgid ", int " tid ", int " sig ); +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +.BR tgkill () +sends the signal +.I sig +to the thread with the thread ID +.I tid +in the thread group +.IR tgid . +(By contrast, +.BR kill (2) +can be used to send a signal only to a process (i.e., thread group) +as a whole, and the signal will be delivered to an arbitrary +thread within that process.) +.PP +.BR tkill () +is an obsolete predecessor to +.BR tgkill (). +It allows only the target thread ID to be specified, +which may result in the wrong thread being signaled if a thread +terminates and its thread ID is recycled. +Avoid using this system call. +.\" FIXME Maybe say something about the following: +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12889 +.\" +.\" Quoting Rich Felker : +.\" +.\" There is a race condition in pthread_kill: it is possible that, +.\" between the time pthread_kill reads the pid/tid from the target +.\" thread descriptor and the time it makes the tgkill syscall, +.\" the target thread terminates and the same tid gets assigned +.\" to a new thread in the same process. +.\" +.\" (The tgkill syscall was designed to eliminate a similar race +.\" condition in tkill, but it only succeeded in eliminating races +.\" where the tid gets reused in a different process, and does not +.\" help if the same tid gets assigned to a new thread in the +.\" same process.) +.\" +.\" The only solution I can see is to introduce a mutex that ensures +.\" that a thread cannot exit while pthread_kill is being called on it. +.\" +.\" Note that in most real-world situations, like almost all race +.\" conditions, this one will be extremely rare. To make it +.\" measurable, one could exhaust all but 1-2 available pid values, +.\" possibly by lowering the max pid parameter in /proc, forcing +.\" the same tid to be reused rapidly. +.PP +These are the raw system call interfaces, meant for internal +thread library use. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and \fIerrno\fP +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +An invalid thread ID, thread group ID, or signal was specified. +.TP +.B EPERM +Permission denied. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process with the specified thread ID (and thread group ID) exists. +.TP +.B EAGAIN +The +.B RLIMIT_SIGPENDING +resource limit was reached and +.I sig +is a real-time signal. +.TP +.B EAGAIN +Insufficient kernel memory was available and +.I sig +is a real-time signal. +.SH VERSIONS +.BR tkill () +is supported since Linux 2.4.19 / 2.5.4. +.BR tgkill () +was added in Linux 2.5.75. +.SH CONFORMING TO +.BR tkill () +and +.BR tgkill () +are Linux-specific and should not be used +in programs that are intended to be portable. +.SH NOTES +See the description of +.B CLONE_THREAD +in +.BR clone (2) +for an explanation of thread groups. +.PP +Glibc does not provide wrappers for these system calls; call them using +.BR syscall (2). +.SH SEE ALSO +.BR clone (2), +.BR gettid (2), +.BR kill (2), +.BR rt_sigqueueinfo (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/truncate.2 b/man2/truncate.2 new file mode 100644 index 0000000..50f6231 --- /dev/null +++ b/man2/truncate.2 @@ -0,0 +1,287 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)truncate.2 6.9 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998-12-21 by Andries Brouwer +.\" Modified 2002-01-07 by Michael Kerrisk +.\" Modified 2002-04-06 by Andries Brouwer +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH TRUNCATE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +truncate, ftruncate \- truncate a file to a specified length +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int truncate(const char *" path ", off_t " length ); +.br +.BI "int ftruncate(int " fd ", off_t " length ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.PP +.BR truncate (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.br + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.PP +.BR ftruncate (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE\ >=\ 200112L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR truncate () +and +.BR ftruncate () +functions cause the regular file named by +.I path +or referenced by +.I fd +to be truncated to a size of precisely +.I length +bytes. +.PP +If the file previously was larger than this size, the extra data is lost. +If the file previously was shorter, it is extended, and +the extended part reads as null bytes (\(aq\\0\(aq). +.PP +The file offset is not changed. +.PP +If the size changed, then the st_ctime and st_mtime fields +(respectively, time of last status change and +time of last modification; see +.BR inode (7)) +for the file are updated, +and the set-user-ID and set-group-ID mode bits may be cleared. +.PP +With +.BR ftruncate (), +the file must be open for writing; with +.BR truncate (), +the file must be writable. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +For +.BR truncate (): +.TP +.B EACCES +Search permission is denied for a component of the path prefix, +or the named file is not writable by the user. +(See also +.BR path_resolution (7).) +.TP +.B EFAULT +The argument +.I path +points outside the process's allocated address space. +.TP +.B EFBIG +The argument +.I length +is larger than the maximum file size. (XSI) +.TP +.B EINTR +While blocked waiting to complete, +the call was interrupted by a signal handler; see +.BR fcntl (2) +and +.BR signal (7). +.TP +.B EINVAL +The argument +.I length +is negative or larger than the maximum file size. +.TP +.B EIO +An I/O error occurred updating the inode. +.TP +.B EISDIR +The named file is a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire pathname exceeded 1023 characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EPERM +.\" This happens for at least MSDOS and VFAT filesystems +.\" on kernel 2.6.13 +The underlying filesystem does not support extending +a file beyond its current size. +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B EROFS +The named file resides on a read-only filesystem. +.TP +.B ETXTBSY +The file is an executable file that is being executed. +.PP +For +.BR ftruncate () +the same errors apply, but instead of things that can be wrong with +.IR path , +we now have things that can be wrong with the file descriptor, +.IR fd : +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.BR EBADF " or " EINVAL +.I fd +is not open for writing. +.TP +.B EINVAL +.I fd +does not reference a regular file or a POSIX shared memory object. +.TP +.BR EINVAL " or " EBADF +The file descriptor +.I fd +is not open for writing. +POSIX permits, and portable applications should handle, +either error for this case. +(Linux produces +.BR EINVAL .) +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, +4.4BSD, SVr4 (these calls first appeared in 4.2BSD). +.\" POSIX.1-1996 has +.\" .BR ftruncate (). +.\" POSIX.1-2001 also has +.\" .BR truncate (), +.\" as an XSI extension. +.\" .LP +.\" SVr4 documents additional +.\" .BR truncate () +.\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for +.\" .BR ftruncate () +.\" an additional EAGAIN error condition. +.SH NOTES +.BR ftruncate () +can also be used to set the size of a POSIX shared memory object; see +.BR shm_open (7). +.PP +The details in DESCRIPTION are for XSI-compliant systems. +For non-XSI-compliant systems, the POSIX standard allows +two behaviors for +.BR ftruncate () +when +.I length +exceeds the file length +(note that +.BR truncate () +is not specified at all in such an environment): +either returning an error, or extending the file. +Like most UNIX implementations, Linux follows the XSI requirement +when dealing with native filesystems. +However, some nonnative filesystems do not permit +.BR truncate () +and +.BR ftruncate () +to be used to extend a file beyond its current length: +a notable example on Linux is VFAT. +.\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002 +.PP +The original Linux +.BR truncate () +and +.BR ftruncate () +system calls were not designed to handle large file offsets. +Consequently, Linux 2.4 added +.BR truncate64 () +and +.BR ftruncate64 () +system calls that handle large files. +However, these details can be ignored by applications using glibc, whose +wrapper functions transparently employ the more recent system calls +where they are available. +.PP +On some 32-bit architectures, +the calling signature for these system calls differ, +for the reasons described in +.BR syscall (2). +.SH BUGS +A header file bug in glibc 2.12 meant that the minimum value of +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037 +.BR _POSIX_C_SOURCE +required to expose the declaration of +.BR ftruncate () +was 200809L instead of 200112L. +This has been fixed in later glibc versions. +.SH SEE ALSO +.BR truncate (1), +.BR open (2), +.BR stat (2), +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/truncate64.2 b/man2/truncate64.2 new file mode 100644 index 0000000..2ed34f1 --- /dev/null +++ b/man2/truncate64.2 @@ -0,0 +1 @@ +.so man2/truncate.2 diff --git a/man2/tuxcall.2 b/man2/tuxcall.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/tuxcall.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/ugetrlimit.2 b/man2/ugetrlimit.2 new file mode 100644 index 0000000..df6d736 --- /dev/null +++ b/man2/ugetrlimit.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man2/umask.2 b/man2/umask.2 new file mode 100644 index 0000000..608528b --- /dev/null +++ b/man2/umask.2 @@ -0,0 +1,169 @@ +.\" Copyright (c) 2006, 2008, Michael Kerrisk +.\" (A few fragments remain from an earlier (1992) version written in +.\" 1992 by Drew Eckhardt .) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 12:51:53 1993 by Rik Faith +.\" Modified Tue Oct 22 22:39:04 1996 by Eric S. Raymond +.\" Modified Thu May 1 06:05:54 UTC 1997 by Nicolás Lichtmaier +.\" with Lars Wirzenius suggestion +.\" 2006-05-13, mtk, substantial rewrite of description of 'mask' +.\" 2008-01-09, mtk, a few rewrites and additions. +.TH UMASK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +umask \- set file mode creation mask +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "mode_t umask(mode_t " mask ); +.SH DESCRIPTION +.BR umask () +sets the calling process's file mode creation mask (umask) to +.I mask +& 0777 (i.e., only the file permission bits of +.I mask +are used), and returns the previous value of the mask. +.PP +The umask is used by +.BR open (2), +.BR mkdir (2), +and other system calls that create files +.\" e.g., mkfifo(), creat(), mknod(), sem_open(), mq_open(), shm_open() +.\" but NOT the System V IPC *get() calls +to modify the permissions placed on newly created files or directories. +Specifically, permissions in the umask are turned off from +the +.I mode +argument to +.BR open (2) +and +.BR mkdir (2). +.PP +Alternatively, if the parent directory has a default ACL (see +.BR acl (5)), +the umask is ignored, the default ACL is inherited, +the permission bits are set based on the inherited ACL, +and permission bits absent in the +.I mode +argument are turned off. +For example, the following default ACL is equivalent to a umask of 022: +.PP + u::rwx,g::r-x,o::r-x +.PP +Combining the effect of this default ACL with a +.I mode +argument of 0666 (rw-rw-rw-), the resulting file permissions would be 0644 +(rw-r--r--). +.PP +The constants that should be used to specify +.I mask +are described in +.BR inode (7). +.PP +The typical default value for the process umask is +.I S_IWGRP\ |\ S_IWOTH +(octal 022). +In the usual case where the +.I mode +argument to +.BR open (2) +is specified as: +.PP +.in +4n +.EX +S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH +.EE +.in +.PP +(octal 0666) when creating a new file, the permissions on the +resulting file will be: +.PP +.in +4n +.EX +S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH +.EE +.in +.PP +(because 0666 & ~022 = 0644; i.e., rw\-r\-\-r\-\-). +.SH RETURN VALUE +This system call always succeeds and the previous value of the mask +is returned. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's umask. +The umask is left unchanged by +.BR execve (2). +.PP +It is impossible to use +.BR umask () +to fetch a process's umask without at the same time changing it. +A second call to +.BR umask () +would then be needed to restore the umask. +The nonatomicity of these two steps provides the potential +for races in multithreaded programs. +.PP +Since Linux 4.7, the umask of any process can be viewed via the +.I Umask +field of +.IR /proc/[pid]/status . +Inspecting this field in +.IR /proc/self/status +allows a process to retrieve its umask without at the same time changing it. +.PP +The umask setting also affects the permissions assigned to POSIX IPC objects +.RB ( mq_open (3), +.BR sem_open (3), +.BR shm_open (3)), +FIFOs +.RB ( mkfifo (3)), +and UNIX domain sockets +.RB ( unix (7)) +created by the process. +The umask does not affect the permissions assigned +to System\ V IPC objects created by the process (using +.BR msgget (2), +.BR semget (2), +.BR shmget (2)). +.SH SEE ALSO +.BR chmod (2), +.BR mkdir (2), +.BR open (2), +.BR stat (2), +.BR acl (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/umount.2 b/man2/umount.2 new file mode 100644 index 0000000..292076c --- /dev/null +++ b/man2/umount.2 @@ -0,0 +1,237 @@ +.\" Copyright (C) 1993 Rickard E. Faith +.\" and Copyright (C) 1994 Andries E. Brouwer +.\" and Copyright (C) 2002, 2005 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2008-10-06, mtk: Created this as a new page by splitting +.\" umount/umount2 material out of mount.2 +.\" +.TH UMOUNT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +umount, umount2 \- unmount filesystem +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "int umount(const char *" target ); +.PP +.BI "int umount2(const char *" target ", int " flags ); +.fi +.SH DESCRIPTION +.BR umount () +and +.BR umount2 () +remove the attachment of the (topmost) filesystem mounted on +.IR target . +.\" Note: the kernel naming differs from the glibc naming +.\" umount2 is the glibc name for what the kernel now calls umount +.\" and umount is the glibc name for oldumount +.PP +Appropriate privilege (Linux: the +.B CAP_SYS_ADMIN +capability) is required to unmount filesystems. +.PP +Linux 2.1.116 added the +.BR umount2 () +system call, which, like +.BR umount (), +unmounts a target, but allows additional +.I flags +controlling the behavior of the operation: +.TP +.BR MNT_FORCE " (since Linux 2.1.116)" +Ask the filesystem to abort pending requests before attempting the +unmount. +This may allow the unmount to complete without waiting +for an inaccessible server, but could cause data loss. +If, after aborting requests, +some processes still have active references to the filesystem, +the unmount will still fail. +As at Linux 4.12, +.BR MNT_FORCE +is supported only on the following filesystems: +9p (since Linux 2.6.16), +ceph (since Linux 2.6.34), +cifs (since Linux 2.6.12), +fuse (since Linux 2.6.16), +lustre (since Linux 3.11), +and NFS (since Linux 2.1.116). +.TP +.BR MNT_DETACH " (since Linux 2.4.11)" +Perform a lazy unmount: make the mount point unavailable for new +accesses, immediately disconnect the filesystem and all filesystems +mounted below it from each other and from the mount table, and +actually perform the unmount when the mount point ceases to be busy. +.TP +.BR MNT_EXPIRE " (since Linux 2.6.8)" +Mark the mount point as expired. +If a mount point is not currently in use, then an initial call to +.BR umount2 () +with this flag fails with the error +.BR EAGAIN , +but marks the mount point as expired. +The mount point remains expired as long as it isn't accessed +by any process. +A second +.BR umount2 () +call specifying +.B MNT_EXPIRE +unmounts an expired mount point. +This flag cannot be specified with either +.B MNT_FORCE +or +.BR MNT_DETACH . +.TP +.BR UMOUNT_NOFOLLOW " (since Linux 2.6.34)" +.\" Later added to 2.6.33-stable +Don't dereference +.I target +if it is a symbolic link. +This flag allows security problems to be avoided in set-user-ID-\fIroot\fP +programs that allow unprivileged users to unmount filesystems. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +The error values given below result from filesystem type independent +errors. +Each filesystem type may have its own special errors and its +own special behavior. +See the Linux kernel source code for details. +.TP +.B EAGAIN +A call to +.BR umount2 () +specifying +.B MNT_EXPIRE +successfully marked an unbusy filesystem as expired. +.TP +.B EBUSY +.I target +could not be unmounted because it is busy. +.TP +.B EFAULT +.I target +points outside the user address space. +.TP +.B EINVAL +.I target +is not a mount point. +.TP +.B EINVAL +.BR umount2 () +was called with +.B MNT_EXPIRE +and either +.B MNT_DETACH +or +.BR MNT_FORCE . +.TP +.BR EINVAL " (since Linux 2.6.34)" +.BR umount2 () +was called with an invalid flag value in +.IR flags . +.TP +.B ENAMETOOLONG +A pathname was longer than +.BR MAXPATHLEN . +.TP +.B ENOENT +A pathname was empty or had a nonexistent component. +.TP +.B ENOMEM +The kernel could not allocate a free page to copy filenames or data into. +.TP +.B EPERM +The caller does not have the required privileges. +.SH VERSIONS +.BR MNT_DETACH +and +.BR MNT_EXPIRE +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=10092 +are available in glibc since version 2.11. +.SH CONFORMING TO +These functions are Linux-specific and should not be used in +programs intended to be portable. +.SH NOTES +.SS umount() and shared mount points +Shared mount points cause any mount activity on a mount point, including +.BR umount () +operations, to be forwarded to every shared mount point in the +peer group and every slave mount of that peer group. +This means that +.BR umount () +of any peer in a set of shared mounts will cause all of its +peers to be unmounted and all of their slaves to be unmounted as well. +.PP +This propagation of unmount activity can be particularly surprising +on systems where every mount point is shared by default. +On such systems, +recursively bind mounting the root directory of the filesystem +onto a subdirectory and then later unmounting that subdirectory with +.BR MNT_DETACH +will cause every mount in the mount namespace to be lazily unmounted. +.PP +To ensure +.BR umount () +does not propagate in this fashion, +the mount point may be remounted using a +.BR mount () +call with a +.I mount_flags +argument that includes both +.BR MS_REC +and +.BR MS_PRIVATE +prior to +.BR umount () +being called. +.SS Historical details +The original +.BR umount () +function was called as \fIumount(device)\fP and would return +.B ENOTBLK +when called with something other than a block device. +In Linux 0.98p4, a call \fIumount(dir)\fP was added, in order to +support anonymous devices. +In Linux 2.3.99-pre7, the call \fIumount(device)\fP was removed, +leaving only \fIumount(dir)\fP (since now devices can be mounted +in more than one place, so specifying the device does not suffice). +.SH SEE ALSO +.BR mount (2), +.BR mount_namespaces (7), +.BR path_resolution (7), +.BR mount (8), +.BR umount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/umount2.2 b/man2/umount2.2 new file mode 100644 index 0000000..84ea419 --- /dev/null +++ b/man2/umount2.2 @@ -0,0 +1 @@ +.so man2/umount.2 diff --git a/man2/uname.2 b/man2/uname.2 new file mode 100644 index 0000000..5274fd3 --- /dev/null +++ b/man2/uname.2 @@ -0,0 +1,180 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-07-05 mtk: Added details on underlying system call interfaces +.\" +.TH UNAME 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +uname \- get name and information about current kernel +.SH SYNOPSIS +.B #include +.PP +.BI "int uname(struct utsname *" buf ); +.SH DESCRIPTION +.BR uname () +returns system information in the structure pointed to by +.IR buf . +The +.I utsname +struct is defined in +.IR : +.PP +.in +4n +.EX +struct utsname { + char sysname[]; /* Operating system name (e.g., "Linux") */ + char nodename[]; /* Name within "some implementation-defined + network" */ + char release[]; /* Operating system release (e.g., "2.6.28") */ + char version[]; /* Operating system version */ + char machine[]; /* Hardware identifier */ +#ifdef _GNU_SOURCE + char domainname[]; /* NIS or YP domain name */ +#endif +}; +.EE +.in +.PP +The length of the arrays in a +.I struct utsname +is unspecified (see NOTES); +the fields are terminated by a null byte (\(aq\\0\(aq). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I buf +is not valid. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +There is no +.BR uname () +call in 4.3BSD. +.PP +The +.I domainname +member (the NIS or YP domain name) is a GNU extension. +.SH NOTES +This is a system call, and the operating system presumably knows +its name, release and version. +It also knows what hardware it runs on. +So, four of the fields of the struct are meaningful. +On the other hand, the field +.I nodename +is meaningless: +it gives the name of the present machine in some undefined +network, but typically machines are in more than one network +and have several names. +Moreover, the kernel has no way of knowing +about such things, so it has to be told what to answer here. +The same holds for the additional +.I domainname +field. +.PP +To this end, Linux uses the system calls +.BR sethostname (2) +and +.BR setdomainname (2). +Note that there is no standard that says that the hostname set by +.BR sethostname (2) +is the same string as the +.I nodename +field of the struct returned by +.BR uname () +(indeed, some systems allow a 256-byte hostname and an 8-byte nodename), +but this is true on Linux. +The same holds for +.BR setdomainname (2) +and the +.I domainname +field. +.PP +The length of the fields in the struct varies. +Some operating systems +or libraries use a hardcoded 9 or 33 or 65 or 257. +Other systems use +.B SYS_NMLN +or +.B _SYS_NMLN +or +.B UTSLEN +or +.BR _UTSNAME_LENGTH . +Clearly, it is a bad +idea to use any of these constants; just use sizeof(...). +Often 257 is chosen in order to have room for an internet hostname. +.PP +Part of the utsname information is also accessible via +.IR /proc/sys/kernel/ { ostype , +.IR hostname , +.IR osrelease , +.IR version , +.IR domainname }. +.SS C library/kernel differences +.PP +Over time, increases in the size of the +.I utsname +structure have led to three successive versions of +.BR uname (): +.IR sys_olduname () +(slot +.IR __NR_oldolduname ), +.IR sys_uname () +(slot +.IR __NR_olduname ), +and +.IR sys_newuname () +(slot +.IR __NR_uname) . +The first one +.\" That was back before Linux 1.0 +used length 9 for all fields; +the second +.\" That was also back before Linux 1.0 +used 65; +the third also uses 65 but adds the +.I domainname +field. +The glibc +.BR uname () +wrapper function hides these details from applications, +invoking the most recent version of the system call provided by the kernel. +.SH SEE ALSO +.BR uname (1), +.BR getdomainname (2), +.BR gethostname (2), +.BR namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/unimplemented.2 b/man2/unimplemented.2 new file mode 100644 index 0000000..65fa310 --- /dev/null +++ b/man2/unimplemented.2 @@ -0,0 +1,74 @@ +.\" Copyright 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Updated, aeb, 980612 +.\" +.TH UNIMPLEMENTED 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +afs_syscall, break, fattach, fdetach, ftime, getmsg, getpmsg, gtty, isastream, +lock, madvise1, mpx, prof, profil, putmsg, putpmsg, security, +stty, tuxcall, ulimit, vserver \- unimplemented system calls +.SH SYNOPSIS +Unimplemented system calls. +.SH DESCRIPTION +These system calls are not implemented in the Linux kernel. +.SH RETURN VALUE +These system calls always return \-1 and set +.I errno +to +.BR ENOSYS . +.SH NOTES +Note that +.BR ftime (3), +.BR profil (3), +and +.BR ulimit (3) +are implemented as library functions. +.PP +Some system calls, like +.BR alloc_hugepages (2), +.BR free_hugepages (2), +.BR ioperm (2), +.BR iopl (2), +and +.BR vm86 (2) +exist only on certain architectures. +.PP +Some system calls, like +.BR ipc (2), +.BR create_module (2), +.BR init_module (2), +and +.BR delete_module (2) +exist only when the Linux kernel was built with support for them. +.SH SEE ALSO +.BR syscalls (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/unlink.2 b/man2/unlink.2 new file mode 100644 index 0000000..b25b153 --- /dev/null +++ b/man2/unlink.2 @@ -0,0 +1,326 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Ian Jackson +.\" and Copyright (C) 2006, 2014 Michael Kerrisk. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-09-08 by Arnt Gulbrandsen +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2001-05-17 by aeb +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH UNLINK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +unlink, unlinkat \- delete a name and possibly the file it refers to +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int unlink(const char *" pathname ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR unlinkat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +.BR unlink () +deletes a name from the filesystem. +If that name was the +last link to a file and no processes have the file open, the file is +deleted and the space it was using is made available for reuse. +.PP +If the name was the last link to a file but any processes still have +the file open, the file will remain in existence until the last file +descriptor referring to it is closed. +.PP +If the name referred to a symbolic link, the link is removed. +.PP +If the name referred to a socket, FIFO, or device, the name for it is +removed but processes which have the object open may continue to use +it. +.SS unlinkat() +The +.BR unlinkat () +system call operates in exactly the same way as either +.BR unlink () +or +.BR rmdir (2) +(depending on whether or not +.I flags +includes the +.B AT_REMOVEDIR +flag) +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR unlink () +and +.BR rmdir (2) +for a relative pathname). +.PP +If the pathname given in +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR unlink () +and +.BR rmdir (2)). +.PP +If the pathname given in +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +.I flags +is a bit mask that can either be specified as 0, or by ORing +together flag values that control the operation of +.BR unlinkat (). +Currently, only one such flag is defined: +.TP +.B AT_REMOVEDIR +By default, +.BR unlinkat () +performs the equivalent of +.BR unlink () +on +.IR pathname . +If the +.B AT_REMOVEDIR +flag is specified, then +performs the equivalent of +.BR rmdir (2) +on +.IR pathname . +.PP +See +.BR openat (2) +for an explanation of the need for +.BR unlinkat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I pathname +is not allowed for the process's effective UID, or one of the +directories in +.I pathname +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.BR EBUSY +The file +.I pathname +cannot be unlinked because it is being used by the system +or another process; +for example, it is a mount point +or the NFS client software created it to represent an +active but otherwise nameless inode ("NFS silly renamed"). +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B EISDIR +.I pathname +refers to a directory. +(This is the non-POSIX value returned by Linux since 2.1.132.) +.TP +.B ELOOP +Too many symbolic links were encountered in translating +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A component in +.I pathname +does not exist or is a dangling symbolic link, or +.I pathname +is empty. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EPERM +The system does not allow unlinking of directories, +or unlinking of directories requires privileges that the +calling process doesn't have. +(This is the POSIX prescribed error return; +as noted above, Linux returns +.B EISDIR +for this case.) +.TP +.BR EPERM " (Linux only)" +The filesystem does not allow unlinking of files. +.TP +.BR EPERM " or " EACCES +The directory containing +.I pathname +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective UID is neither the UID of the file to +be deleted nor that of the directory containing it, and +the process is not privileged (Linux: does not have the +.B CAP_FOWNER +capability). +.TP +.B EPERM +The file to be unlinked is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.PP +The same errors that occur for +.BR unlink () +and +.BR rmdir (2) +can also occur for +.BR unlinkat (). +The following additional errors can occur for +.BR unlinkat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B EINVAL +An invalid flag value was specified in +.IR flags . +.TP +.B EISDIR +.I pathname +refers to a directory, and +.B AT_REMOVEDIR +was not specified in +.IR flags . +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR unlinkat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. +.SH CONFORMING TO +.BR unlink (): +SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. +.\" SVr4 documents additional error +.\" conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK. +.PP +.BR unlinkat (): +POSIX.1-2008. +.SH NOTES +.SS Glibc notes +On older kernels where +.BR unlinkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR unlink () +or +.BR rmdir (2). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.IR /proc/self/fd +that corresponds to the +.IR dirfd +argument. +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of files which are still being used. +.SH SEE ALSO +.BR rm (1), +.BR unlink (1), +.BR chmod (2), +.BR link (2), +.BR mknod (2), +.BR open (2), +.BR rename (2), +.BR rmdir (2), +.BR mkfifo (3), +.BR remove (3), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/unlinkat.2 b/man2/unlinkat.2 new file mode 100644 index 0000000..4921f73 --- /dev/null +++ b/man2/unlinkat.2 @@ -0,0 +1 @@ +.so man2/unlink.2 diff --git a/man2/unshare.2 b/man2/unshare.2 new file mode 100644 index 0000000..b91908c --- /dev/null +++ b/man2/unshare.2 @@ -0,0 +1,505 @@ +.\" Copyright (C) 2006, Janak Desai +.\" and Copyright (C) 2006, 2012 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Licensed under the GPL +.\" %%%LICENSE_END +.\" +.\" Patch Justification: +.\" unshare system call is needed to implement, using PAM, +.\" per-security_context and/or per-user namespace to provide +.\" polyinstantiated directories. Using unshare and bind mounts, a +.\" PAM module can create private namespace with appropriate +.\" directories(based on user's security context) bind mounted on +.\" public directories such as /tmp, thus providing an instance of +.\" /tmp that is based on user's security context. Without the +.\" unshare system call, namespace separation can only be achieved +.\" by clone, which would require porting and maintaining all commands +.\" such as login, and su, that establish a user session. +.\" +.TH UNSHARE 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +unshare \- disassociate parts of the process execution context +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.PP +.BI "int unshare(int " flags ); +.fi +.SH DESCRIPTION +.BR unshare () +allows a process (or thread) to disassociate parts of its execution +context that are currently being shared with other processes (or threads). +Part of the execution context, such as the mount namespace, is shared +implicitly when a new process is created using +.BR fork (2) +or +.BR vfork (2), +while other parts, such as virtual memory, may be +shared by explicit request when creating a process or thread using +.BR clone (2). +.PP +The main use of +.BR unshare () +is to allow a process to control its +shared execution context without creating a new process. +.PP +The +.I flags +argument is a bit mask that specifies which parts of +the execution context should be unshared. +This argument is specified by ORing together zero or more +of the following constants: +.TP +.B CLONE_FILES +Reverse the effect of the +.BR clone (2) +.B CLONE_FILES +flag. +Unshare the file descriptor table, so that the calling process +no longer shares its file descriptors with any other process. +.TP +.B CLONE_FS +Reverse the effect of the +.BR clone (2) +.B CLONE_FS +flag. +Unshare filesystem attributes, so that the calling process +no longer shares its root directory +.RB ( chroot (2)), +current directory +.RB ( chdir (2)), +or umask +.RB ( umask (2)) +attributes with any other process. +.TP +.BR CLONE_NEWCGROUP " (since Linux 4.6)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWCGROUP +flag. +Unshare the cgroup namespace. +Use of +.BR CLONE_NEWCGROUP +requires the +.BR CAP_SYS_ADMIN +capability. +.TP +.BR CLONE_NEWIPC " (since Linux 2.6.19)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWIPC +flag. +Unshare the IPC namespace, +so that the calling process has a private copy of the +IPC namespace which is not shared with any other process. +Specifying this flag automatically implies +.BR CLONE_SYSVSEM +as well. +Use of +.BR CLONE_NEWIPC +requires the +.BR CAP_SYS_ADMIN +capability. +.TP +.BR CLONE_NEWNET " (since Linux 2.6.24)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWNET +flag. +Unshare the network namespace, +so that the calling process is moved into a +new network namespace which is not shared +with any previously existing process. +Use of +.BR CLONE_NEWNET +requires the +.BR CAP_SYS_ADMIN +capability. +.TP +.B CLONE_NEWNS +.\" These flag name are inconsistent: +.\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM, +.\" CLONE_FS, and CLONE_FILES reverse the action of the clone() +.\" flags of the same name. +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWNS +flag. +Unshare the mount namespace, +so that the calling process has a private copy of +its namespace which is not shared with any other process. +Specifying this flag automatically implies +.B CLONE_FS +as well. +Use of +.BR CLONE_NEWNS +requires the +.BR CAP_SYS_ADMIN +capability. +For further information, see +.BR mount_namespaces (7). +.TP +.BR CLONE_NEWPID " (since Linux 3.8)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWPID +flag. +Unshare the PID namespace, +so that the calling process has a new PID namespace for its children +which is not shared with any previously existing process. +The calling process is +.I not +moved into the new namespace. +The first child created by the calling process will have +the process ID 1 and will assume the role of +.BR init (1) +in the new namespace. +.BR CLONE_NEWPID +automatically implies +.BR CLONE_THREAD +as well. +Use of +.BR CLONE_NEWPID +requires the +.BR CAP_SYS_ADMIN +capability. +For further information, see +.BR pid_namespaces (7). +.TP +.BR CLONE_NEWUSER " (since Linux 3.8)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWUSER +flag. +Unshare the user namespace, +so that the calling process is moved into a new user namespace +which is not shared with any previously existing process. +As with the child process created by +.BR clone (2) +with the +.B CLONE_NEWUSER +flag, the caller obtains a full set of capabilities in the new namespace. +.IP +.BR CLONE_NEWUSER +requires that the calling process is not threaded; specifying +.BR CLONE_NEWUSER +automatically implies +.BR CLONE_THREAD . +Since Linux 3.9, +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +.\" https://lwn.net/Articles/543273/ +.BR CLONE_NEWUSER +also automatically implies +.BR CLONE_FS . +.BR CLONE_NEWUSER +requires that the user ID and group ID +of the calling process are mapped to user IDs and group IDs in the +user namespace of the calling process at the time of the call. +.IP +For further information on user namespaces, see +.BR user_namespaces (7). +.TP +.BR CLONE_NEWUTS " (since Linux 2.6.19)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWUTS +flag. +Unshare the UTS IPC namespace, +so that the calling process has a private copy of the +UTS namespace which is not shared with any other process. +Use of +.BR CLONE_NEWUTS +requires the +.BR CAP_SYS_ADMIN +capability. +.TP +.BR CLONE_SYSVSEM " (since Linux 2.6.26) +.\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7 +This flag reverses the effect of the +.BR clone (2) +.B CLONE_SYSVSEM +flag. +Unshare System\ V semaphore adjustment +.RI ( semadj ) +values, +so that the calling process has a new empty +.I semadj +list that is not shared with any other process. +If this is the last process that has a reference to the process's current +.I semadj +list, then the adjustments in that list are applied +to the corresponding semaphores, as described in +.BR semop (2). +.\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared +.\" (i.e., current->signal->count > 1), force CLONE_THREAD. +.PP +In addition, +.BR CLONE_THREAD , +.BR CLONE_SIGHAND , +and +.BR CLONE_VM +can be specified in +.I flags +if the caller is single threaded (i.e., it is not sharing +its address space with another process or thread). +In this case, these flags have no effect. +(Note also that specifying +.BR CLONE_THREAD +automatically implies +.BR CLONE_VM , +and specifying +.BR CLONE_VM +automatically implies +.BR CLONE_SIGHAND .) +.\" As at 3.9, the following forced implications also apply, +.\" although the relevant flags are not yet implemented. +.\" If CLONE_THREAD is set force CLONE_VM. +.\" If CLONE_VM is set, force CLONE_SIGHAND. +.\" +If the process is multithreaded, then +the use of these flags results in an error. +.\" See kernel/fork.c::check_unshare_flags() +.PP +If +.I flags +is specified as zero, then +.BR unshare () +is a no-op; +no changes are made to the calling process's execution context. +.SH RETURN VALUE +On success, zero returned. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An invalid bit was specified in +.IR flags . +.TP +.B EINVAL +.BR CLONE_THREAD , +.BR CLONE_SIGHAND , +or +.BR CLONE_VM +was specified in +.IR flags , +and the caller is multithreaded. +.TP +.B ENOMEM +Cannot allocate sufficient memory to copy parts of caller's +context that need to be unshared. +.TP +.BR ENOSPC " (since Linux 3.7)" +.\" commit f2302505775fd13ba93f034206f1e2a587017929 +.B CLONE_NEWPID +was specified in flags, +but the limit on the nesting depth of PID namespaces +would have been exceeded; see +.BR pid_namespaces (7). +.TP +.BR ENOSPC " (since Linux 4.9; beforehand " EUSERS ) +.B CLONE_NEWUSER +was specified in +.IR flags , +and the call would cause the limit on the number of +nested user namespaces to be exceeded. +See +.BR user_namespaces (7). +.IP +From Linux 3.11 to Linux 4.8, the error diagnosed in this case was +.BR EUSERS . +.TP +.BR ENOSPC " (since Linux 4.9)" +One of the values in +.I flags +specified the creation of a new user namespace, +but doing so would have caused the limit defined by the corresponding file in +.IR /proc/sys/user +to be exceeded. +For further details, see +.BR namespaces (7). +.TP +.B EPERM +The calling process did not have the required privileges for this operation. +.TP +.B EPERM +.BR CLONE_NEWUSER +was specified in +.IR flags , +but either the effective user ID or the effective group ID of the caller +does not have a mapping in the parent namespace (see +.BR user_namespaces (7)). +.TP +.BR EPERM " (since Linux 3.9)" +.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d +.B CLONE_NEWUSER +was specified in +.I flags +and the caller is in a chroot environment +.\" FIXME What is the rationale for this restriction? +(i.e., the caller's root directory does not match the root directory +of the mount namespace in which it resides). +.TP +.BR EUSERS " (from Linux 3.11 to Linux 4.8)" +.B CLONE_NEWUSER +was specified in +.IR flags , +and the limit on the number of nested user namespaces would be exceeded. +See the discussion of the +.BR ENOSPC +error above. +.SH VERSIONS +The +.BR unshare () +system call was added to Linux in kernel 2.6.16. +.SH CONFORMING TO +The +.BR unshare () +system call is Linux-specific. +.SH NOTES +Not all of the process attributes that can be shared when +a new process is created using +.BR clone (2) +can be unshared using +.BR unshare (). +In particular, as at kernel 3.8, +.\" FIXME all of the following needs to be reviewed for the current kernel +.BR unshare () +does not implement flags that reverse the effects of +.BR CLONE_SIGHAND , +.\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND +.\" was not specified when doing clone(); i.e., unsharing +.\" signal handlers is permitted if we are not actually +.\" sharing signal handlers. mtk +.BR CLONE_THREAD , +or +.BR CLONE_VM . +.\" However, we can do unshare(CLONE_VM) if CLONE_VM +.\" was not specified when doing clone(); i.e., unsharing +.\" virtual memory is permitted if we are not actually +.\" sharing virtual memory. mtk +Such functionality may be added in the future, if required. +.\" +.\"9) Future Work +.\"-------------- +.\"The current implementation of unshare does not allow unsharing of +.\"signals and signal handlers. Signals are complex to begin with and +.\"to unshare signals and/or signal handlers of a currently running +.\"process is even more complex. If in the future there is a specific +.\"need to allow unsharing of signals and/or signal handlers, it can +.\"be incrementally added to unshare without affecting legacy +.\"applications using unshare. +.\" +.SH EXAMPLE +The program below provides a simple implementation of the +.BR unshare (1) +command, which unshares one or more namespaces and executes the +command supplied in its command-line arguments. +Here's an example of the use of this program, +running a shell in a new mount namespace, +and verifying that the original shell and the +new shell are in separate mount namespaces: +.PP +.in +4n +.EX +$ \fBreadlink /proc/$$/ns/mnt\fP +mnt:[4026531840] +$ \fBsudo ./unshare -m /bin/bash\fP +# \fBreadlink /proc/$$/ns/mnt\fP +mnt:[4026532325] +.EE +.in +.PP +The differing output of the two +.BR readlink (1) +commands shows that the two shells are in different mount namespaces. +.SS Program source +\& +.EX +/* unshare.c + + A simple implementation of the unshare(1) command: unshare + namespaces and execute a command. +*/ +#define _GNU_SOURCE +#include +#include +#include +#include + +/* A simple error\-handling function: print an error message based + on the value in \(aqerrno\(aq and terminate the calling process */ + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +static void +usage(char *pname) +{ + fprintf(stderr, "Usage: %s [options] program [arg...]\\n", pname); + fprintf(stderr, "Options can be:\\n"); + fprintf(stderr, " \-i unshare IPC namespace\\n"); + fprintf(stderr, " \-m unshare mount namespace\\n"); + fprintf(stderr, " \-n unshare network namespace\\n"); + fprintf(stderr, " \-p unshare PID namespace\\n"); + fprintf(stderr, " \-u unshare UTS namespace\\n"); + fprintf(stderr, " \-U unshare user namespace\\n"); + exit(EXIT_FAILURE); +} + +int +main(int argc, char *argv[]) +{ + int flags, opt; + + flags = 0; + + while ((opt = getopt(argc, argv, "imnpuU")) != \-1) { + switch (opt) { + case \(aqi\(aq: flags |= CLONE_NEWIPC; break; + case \(aqm\(aq: flags |= CLONE_NEWNS; break; + case \(aqn\(aq: flags |= CLONE_NEWNET; break; + case \(aqp\(aq: flags |= CLONE_NEWPID; break; + case \(aqu\(aq: flags |= CLONE_NEWUTS; break; + case \(aqU\(aq: flags |= CLONE_NEWUSER; break; + default: usage(argv[0]); + } + } + + if (optind >= argc) + usage(argv[0]); + + if (unshare(flags) == \-1) + errExit("unshare"); + + execvp(argv[optind], &argv[optind]); + errExit("execvp"); +} +.EE +.SH SEE ALSO +.BR unshare (1), +.BR clone (2), +.BR fork (2), +.BR kcmp (2), +.BR setns (2), +.BR vfork (2), +.BR namespaces (7) +.PP +.I Documentation/userspace-api/unshare.rst +in the Linux kernel source tree +.\" commit f504d47be5e8fa7ecf2bf660b18b42e6960c0eb2 +(or +.I Documentation/unshare.txt +before Linux 4.12) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/uselib.2 b/man2/uselib.2 new file mode 100644 index 0000000..df7bad5 --- /dev/null +++ b/man2/uselib.2 @@ -0,0 +1,138 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" Modified 2005-01-09 by aeb +.\" +.TH USELIB 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +uselib \- load shared library +.SH SYNOPSIS +.B #include +.PP +.BI "int uselib(const char *" library ); +.PP +.IR Note : +No declaration of this system call is provided in glibc headers; see NOTES. +.SH DESCRIPTION +The system call +.BR uselib () +serves to load +a shared library to be used by the calling process. +It is given a pathname. +The address where to load is found +in the library itself. +The library can have any recognized +binary format. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +In addition to all of the error codes returned by +.BR open (2) +and +.BR mmap (2), +the following may also be returned: +.TP +.B EACCES +The library specified by +.I library +does not have read or execute permission, or the caller does not have +search permission for one of the directories in the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOEXEC +The file specified by +.I library +is not an executable of a known type; +for example, it does not have the correct magic numbers. +.SH CONFORMING TO +.BR uselib () +is Linux-specific, and should not be used in programs +intended to be portable. +.SH NOTES +This obsolete system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it was sufficient to manually declare the interface in your code; +alternatively, you could invoke the system call using +.BR syscall (2). +.PP +In ancient libc versions, +.BR uselib () +was used to load +the shared libraries with names found in an array of names +in the binary. +.PP +.\" libc 4.3.1f - changelog 1993-03-02 +Since libc 4.3.2, startup code tries to prefix these names +with "/usr/lib", "/lib" and "" before giving up. +.\" libc 4.3.4 - changelog 1993-04-21 +In libc 4.3.4 and later these names are looked for in the directories +found in +.BR LD_LIBRARY_PATH , +and if not found there, +prefixes "/usr/lib", "/lib" and "/" are tried. +.PP +From libc 4.4.4 on only the library "/lib/ld.so" is loaded, +so that this dynamic library can load the remaining libraries needed +(again using this call). +This is also the state of affairs in libc5. +.PP +glibc2 does not use this call. +.PP +Since Linux 3.15, +.\" commit 69369a7003735d0d8ef22097e27a55a8bad9557a +this system call is available only when the kernel is configured with the +.B CONFIG_USELIB +option. +.SH SEE ALSO +.BR ar (1), +.BR gcc (1), +.BR ld (1), +.BR ldd (1), +.BR mmap (2), +.BR open (2), +.BR dlopen (3), +.BR capabilities (7), +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2 new file mode 100644 index 0000000..f35db20 --- /dev/null +++ b/man2/userfaultfd.2 @@ -0,0 +1,770 @@ +.\" Copyright (c) 2016, IBM Corporation. +.\" Written by Mike Rapoport +.\" and Copyright (C) 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH USERFAULTFD 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +userfaultfd \- create a file descriptor for handling page faults in user space +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int userfaultfd(int " flags ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.BR userfaultfd () +creates a new userfaultfd object that can be used for delegation of page-fault +handling to a user-space application, +and returns a file descriptor that refers to the new object. +The new userfaultfd object is configured using +.BR ioctl (2). +.PP +Once the userfaultfd object is configured, the application can use +.BR read (2) +to receive userfaultfd notifications. +The reads from userfaultfd may be blocking or non-blocking, +depending on the value of +.I flags +used for the creation of the userfaultfd or subsequent calls to +.BR fcntl (2). +.PP +The following values may be bitwise ORed in +.IR flags +to change the behavior of +.BR userfaultfd (): +.TP +.BR O_CLOEXEC +Enable the close-on-exec flag for the new userfaultfd file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2). +.TP +.BR O_NONBLOCK +Enables non-blocking operation for the userfaultfd object. +See the description of the +.BR O_NONBLOCK +flag in +.BR open (2). +.PP +When the last file descriptor referring to a userfaultfd object is closed, +all memory ranges that were registered with the object are unregistered +and unread events are flushed. +.\" +.SS Usage +The userfaultfd mechanism is designed to allow a thread in a multithreaded +program to perform user-space paging for the other threads in the process. +When a page fault occurs for one of the regions registered +to the userfaultfd object, +the faulting thread is put to sleep and +an event is generated that can be read via the userfaultfd file descriptor. +The fault-handling thread reads events from this file descriptor and services +them using the operations described in +.BR ioctl_userfaultfd (2). +When servicing the page fault events, +the fault-handling thread can trigger a wake-up for the sleeping thread. +.PP +It is possible for the faulting threads and the fault-handling threads +to run in the context of different processes. +In this case, these threads may belong to different programs, +and the program that executes the faulting threads +will not necessarily cooperate with the program that handles the page faults. +In such non-cooperative mode, +the process that monitors userfaultfd and handles page faults +needs to be aware of the changes in the virtual memory layout +of the faulting process to avoid memory corruption. +.PP +Starting from Linux 4.11, +userfaultfd can also notify the fault-handling threads about changes +in the virtual memory layout of the faulting process. +In addition, if the faulting process invokes +.BR fork (2), +the userfaultfd objects associated with the parent may be duplicated +into the child process and the userfaultfd monitor will be notified +(via the +.B UFFD_EVENT_FORK +described below) +about the file descriptor associated with the userfault objects +created for the child process, +which allows the userfaultfd monitor to perform user-space paging +for the child process. +Unlike page faults which have to be synchronous and require an +explicit or implicit wakeup, +all other events are delivered asynchronously and +the non-cooperative process resumes execution as +soon as the userfaultfd manager executes +.BR read (2). +The userfaultfd manager should carefully synchronize calls to +.B UFFDIO_COPY +with the processing of events. +.PP +The current asynchronous model of the event delivery is optimal for +single threaded non-cooperative userfaultfd manager implementations. +.\" Regarding the preceding sentence, Mike Rapoport says: +.\" The major point here is that current events delivery model could be +.\" problematic for multi-threaded monitor. I even suspect that it would be +.\" impossible to ensure synchronization between page faults and non-page +.\" fault events in multi-threaded monitor. +.PP +.\" FIXME elaborate about non-cooperating mode, describe its limitations +.\" for kernels before 4.11, features added in 4.11 +.\" and limitations remaining in 4.11 +.\" Maybe it's worth adding a dedicated sub-section... +.\" +.SS Userfaultfd operation +After the userfaultfd object is created with +.BR userfaultfd (), +the application must enable it using the +.B UFFDIO_API +.BR ioctl (2) +operation. +This operation allows a handshake between the kernel and user space +to determine the API version and supported features. +This operation must be performed before any of the other +.BR ioctl (2) +operations described below (or those operations fail with the +.BR EINVAL +error). +.PP +After a successful +.B UFFDIO_API +operation, +the application then registers memory address ranges using the +.B UFFDIO_REGISTER +.BR ioctl (2) +operation. +After successful completion of a +.B UFFDIO_REGISTER +operation, +a page fault occurring in the requested memory range, and satisfying +the mode defined at the registration time, will be forwarded by the kernel to +the user-space application. +The application can then use the +.B UFFDIO_COPY +or +.B UFFDIO_ZERO +.BR ioctl (2) +operations to resolve the page fault. +.PP +Starting from Linux 4.14, if the application sets the +.B UFFD_FEATURE_SIGBUS +feature bit using the +.B UFFDIO_API +.BR ioctl (2), +no page-fault notification will be forwarded to user space. +Instead a +.B SIGBUS +signal is delivered to the faulting process. +With this feature, +userfaultfd can be used for robustness purposes to simply catch +any access to areas within the registered address range that do not +have pages allocated, without having to listen to userfaultfd events. +No userfaultfd monitor will be required for dealing with such memory +accesses. +For example, this feature can be useful for applications that +want to prevent the kernel from automatically allocating pages and filling +holes in sparse files when the hole is accessed through a memory mapping. +.PP +The +.B UFFD_FEATURE_SIGBUS +feature is implicitly inherited through +.BR fork (2) +if used in combination with +.BR UFFD_FEATURE_FORK . +.PP +Details of the various +.BR ioctl (2) +operations can be found in +.BR ioctl_userfaultfd (2). +.PP +Since Linux 4.11, events other than page-fault may enabled during +.B UFFDIO_API +operation. +.PP +Up to Linux 4.11, +userfaultfd can be used only with anonymous private memory mappings. +Since Linux 4.11, +userfaultfd can be also used with hugetlbfs and shared memory mappings. +.PP +.\" +.SS Reading from the userfaultfd structure +Each +.BR read (2) +from the userfaultfd file descriptor returns one or more +.I uffd_msg +structures, each of which describes a page-fault event +or an event required for the non-cooperative userfaultfd usage: +.PP +.in +4n +.EX +struct uffd_msg { + __u8 event; /* Type of event */ + ... + union { + struct { + __u64 flags; /* Flags describing fault */ + __u64 address; /* Faulting address */ + } pagefault; + + struct { /* Since Linux 4.11 */ + __u32 ufd; /* Userfault file descriptor + of the child process */ + } fork; + + struct { /* Since Linux 4.11 */ + __u64 from; /* Old address of remapped area */ + __u64 to; /* New address of remapped area */ + __u64 len; /* Original mapping length */ + } remap; + + struct { /* Since Linux 4.11 */ + __u64 start; /* Start address of removed area */ + __u64 end; /* End address of removed area */ + } remove; + ... + } arg; + + /* Padding fields omitted */ +} __packed; +.EE +.in +.PP +If multiple events are available and the supplied buffer is large enough, +.BR read (2) +returns as many events as will fit in the supplied buffer. +If the buffer supplied to +.BR read (2) +is smaller than the size of the +.I uffd_msg +structure, the +.BR read (2) +fails with the error +.BR EINVAL . +.PP +The fields set in the +.I uffd_msg +structure are as follows: +.TP +.I event +The type of event. +Depending of the event type, +different fields of the +.I arg +union represent details required for the event processing. +The non-page-fault events are generated only when appropriate feature +is enabled during API handshake with +.B UFFDIO_API +.BR ioctl (2). +.IP +The following values can appear in the +.I event +field: +.RS +.TP +.BR UFFD_EVENT_PAGEFAULT " (since Linux 4.3)" +A page-fault event. +The page-fault details are available in the +.I pagefault +field. +.TP +.BR UFFD_EVENT_FORK " (since Linux 4.11)" +Generated when the faulting process invokes +.BR fork (2) +(or +.BR clone (2) +without the +.BR CLONE_VM +flag). +The event details are available in the +.I fork +field. +.\" FIXME describe duplication of userfault file descriptor during fork +.TP +.BR UFFD_EVENT_REMAP " (since Linux 4.11)" +Generated when the faulting process invokes +.BR mremap (2). +The event details are available in the +.I remap +field. +.TP +.BR UFFD_EVENT_REMOVE " (since Linux 4.11)" +Generated when the faulting process invokes +.BR madvise (2) +with +.BR MADV_DONTNEED +or +.BR MADV_REMOVE +advice. +The event details are available in the +.I remove +field. +.TP +.BR UFFD_EVENT_UNMAP " (since Linux 4.11)" +Generated when the faulting process unmaps a memory range, +either explicitly using +.BR munmap (2) +or implicitly during +.BR mmap (2) +or +.BR mremap (2). +The event details are available in the +.I remove +field. +.RE +.TP +.I pagefault.address +The address that triggered the page fault. +.TP +.I pagefault.flags +A bit mask of flags that describe the event. +For +.BR UFFD_EVENT_PAGEFAULT , +the following flag may appear: +.RS +.TP +.B UFFD_PAGEFAULT_FLAG_WRITE +If the address is in a range that was registered with the +.B UFFDIO_REGISTER_MODE_MISSING +flag (see +.BR ioctl_userfaultfd (2)) +and this flag is set, this a write fault; +otherwise it is a read fault. +.\" +.\" UFFD_PAGEFAULT_FLAG_WP is not yet supported. +.RE +.TP +.I fork.ufd +The file descriptor associated with the userfault object +created for the child created by +.BR fork (2). +.TP +.I remap.from +The original address of the memory range that was remapped using +.BR mremap (2). +.TP +.I remap.to +The new address of the memory range that was remapped using +.BR mremap (2). +.TP +.I remap.len +The original length of the memory range that was remapped using +.BR mremap (2). +.TP +.I remove.start +The start address of the memory range that was freed using +.BR madvise (2) +or unmapped +.TP +.I remove.end +The end address of the memory range that was freed using +.BR madvise (2) +or unmapped +.PP +A +.BR read (2) +on a userfaultfd file descriptor can fail with the following errors: +.TP +.B EINVAL +The userfaultfd object has not yet been enabled using the +.BR UFFDIO_API +.BR ioctl (2) +operation +.PP +If the +.B O_NONBLOCK +flag is enabled in the associated open file description, +the userfaultfd file descriptor can be monitored with +.BR poll (2), +.BR select (2), +and +.BR epoll (7). +When events are available, the file descriptor indicates as readable. +If the +.B O_NONBLOCK +flag is not enabled, then +.BR poll (2) +(always) indicates the file as having a +.BR POLLERR +condition, and +.BR select (2) +indicates the file descriptor as both readable and writable. +.\" FIXME What is the reason for this seemingly odd behavior with respect +.\" to the O_NONBLOCK flag? (see userfaultfd_poll() in fs/userfaultfd.c). +.\" Something needs to be said about this. +.SH RETURN VALUE +On success, +.BR userfaultfd () +returns a new file descriptor that refers to the userfaultfd object. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +An unsupported value was specified in +.IR flags . +.TP +.BR EMFILE +The per-process limit on the number of open file descriptors has been +reached +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.SH VERSIONS +The +.BR userfaultfd () +system call first appeared in Linux 4.3. +.PP +The support for hugetlbfs and shared memory areas and +non-page-fault events was added in Linux 4.11 +.SH CONFORMING TO +.BR userfaultfd () +is Linux-specific and should not be used in programs intended to be +portable. +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.PP +The userfaultfd mechanism can be used as an alternative to +traditional user-space paging techniques based on the use of the +.BR SIGSEGV +signal and +.BR mmap (2). +It can also be used to implement lazy restore +for checkpoint/restore mechanisms, +as well as post-copy migration to allow (nearly) uninterrupted execution +when transferring virtual machines and Linux containers +from one host to another. +.SH BUGS +If the +.B UFFD_FEATURE_EVENT_FORK +is enabled and a system call from the +.BR fork (2) +family is interrupted by a signal or failed, a stale userfaultfd descriptor +might be created. +In this case, a spurious +.B UFFD_EVENT_FORK +will be delivered to the userfaultfd monitor. +.SH EXAMPLE +The program below demonstrates the use of the userfaultfd mechanism. +The program creates two threads, one of which acts as the +page-fault handler for the process, for the pages in a demand-page zero +region created using +.BR mmap (2). +.PP +The program takes one command-line argument, +which is the number of pages that will be created in a mapping +whose page faults will be handled via userfaultfd. +After creating a userfaultfd object, +the program then creates an anonymous private mapping of the specified size +and registers the address range of that mapping using the +.B UFFDIO_REGISTER +.BR ioctl (2) +operation. +The program then creates a second thread that will perform the +task of handling page faults. +.PP +The main thread then walks through the pages of the mapping fetching +bytes from successive pages. +Because the pages have not yet been accessed, +the first access of a byte in each page will trigger a page-fault event +on the userfaultfd file descriptor. +.PP +Each of the page-fault events is handled by the second thread, +which sits in a loop processing input from the userfaultfd file descriptor. +In each loop iteration, the second thread first calls +.BR poll (2) +to check the state of the file descriptor, +and then reads an event from the file descriptor. +All such events should be +.B UFFD_EVENT_PAGEFAULT +events, +which the thread handles by copying a page of data into +the faulting region using the +.B UFFDIO_COPY +.BR ioctl (2) +operation. +.PP +The following is an example of what we see when running the program: +.PP +.in +4n +.EX +$ \fB./userfaultfd_demo 3\fP +Address returned by mmap() = 0x7fd30106c000 + +fault_handler_thread(): + poll() returns: nready = 1; POLLIN = 1; POLLERR = 0 + UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106c00f + (uffdio_copy.copy returned 4096) +Read address 0x7fd30106c00f in main(): A +Read address 0x7fd30106c40f in main(): A +Read address 0x7fd30106c80f in main(): A +Read address 0x7fd30106cc0f in main(): A + +fault_handler_thread(): + poll() returns: nready = 1; POLLIN = 1; POLLERR = 0 + UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106d00f + (uffdio_copy.copy returned 4096) +Read address 0x7fd30106d00f in main(): B +Read address 0x7fd30106d40f in main(): B +Read address 0x7fd30106d80f in main(): B +Read address 0x7fd30106dc0f in main(): B + +fault_handler_thread(): + poll() returns: nready = 1; POLLIN = 1; POLLERR = 0 + UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106e00f + (uffdio_copy.copy returned 4096) +Read address 0x7fd30106e00f in main(): C +Read address 0x7fd30106e40f in main(): C +Read address 0x7fd30106e80f in main(): C +Read address 0x7fd30106ec0f in main(): C +.EE +.in +.SS Program source +\& +.EX +/* userfaultfd_demo.c + + Licensed under the GNU General Public License version 2 or later. +*/ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +static int page_size; + +static void * +fault_handler_thread(void *arg) +{ + static struct uffd_msg msg; /* Data read from userfaultfd */ + static int fault_cnt = 0; /* Number of faults so far handled */ + long uffd; /* userfaultfd file descriptor */ + static char *page = NULL; + struct uffdio_copy uffdio_copy; + ssize_t nread; + + uffd = (long) arg; + + /* Create a page that will be copied into the faulting region */ + + if (page == NULL) { + page = mmap(NULL, page_size, PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_ANONYMOUS, \-1, 0); + if (page == MAP_FAILED) + errExit("mmap"); + } + + /* Loop, handling incoming events on the userfaultfd + file descriptor */ + + for (;;) { + + /* See what poll() tells us about the userfaultfd */ + + struct pollfd pollfd; + int nready; + pollfd.fd = uffd; + pollfd.events = POLLIN; + nready = poll(&pollfd, 1, \-1); + if (nready == \-1) + errExit("poll"); + + printf("\\nfault_handler_thread():\\n"); + printf(" poll() returns: nready = %d; " + "POLLIN = %d; POLLERR = %d\\n", nready, + (pollfd.revents & POLLIN) != 0, + (pollfd.revents & POLLERR) != 0); + + /* Read an event from the userfaultfd */ + + nread = read(uffd, &msg, sizeof(msg)); + if (nread == 0) { + printf("EOF on userfaultfd!\\n"); + exit(EXIT_FAILURE); + } + + if (nread == \-1) + errExit("read"); + + /* We expect only one kind of event; verify that assumption */ + + if (msg.event != UFFD_EVENT_PAGEFAULT) { + fprintf(stderr, "Unexpected event on userfaultfd\\n"); + exit(EXIT_FAILURE); + } + + /* Display info about the page\-fault event */ + + printf(" UFFD_EVENT_PAGEFAULT event: "); + printf("flags = %llx; ", msg.arg.pagefault.flags); + printf("address = %llx\\n", msg.arg.pagefault.address); + + /* Copy the page pointed to by \(aqpage\(aq into the faulting + region. Vary the contents that are copied in, so that it + is more obvious that each fault is handled separately. */ + + memset(page, \(aqA\(aq + fault_cnt % 20, page_size); + fault_cnt++; + + uffdio_copy.src = (unsigned long) page; + + /* We need to handle page faults in units of pages(!). + So, round faulting address down to page boundary */ + + uffdio_copy.dst = (unsigned long) msg.arg.pagefault.address & + ~(page_size \- 1); + uffdio_copy.len = page_size; + uffdio_copy.mode = 0; + uffdio_copy.copy = 0; + if (ioctl(uffd, UFFDIO_COPY, &uffdio_copy) == \-1) + errExit("ioctl\-UFFDIO_COPY"); + + printf(" (uffdio_copy.copy returned %lld)\\n", + uffdio_copy.copy); + } +} + +int +main(int argc, char *argv[]) +{ + long uffd; /* userfaultfd file descriptor */ + char *addr; /* Start of region handled by userfaultfd */ + unsigned long len; /* Length of region handled by userfaultfd */ + pthread_t thr; /* ID of thread that handles page faults */ + struct uffdio_api uffdio_api; + struct uffdio_register uffdio_register; + int s; + + if (argc != 2) { + fprintf(stderr, "Usage: %s num\-pages\\n", argv[0]); + exit(EXIT_FAILURE); + } + + page_size = sysconf(_SC_PAGE_SIZE); + len = strtoul(argv[1], NULL, 0) * page_size; + + /* Create and enable userfaultfd object */ + + uffd = syscall(__NR_userfaultfd, O_CLOEXEC | O_NONBLOCK); + if (uffd == \-1) + errExit("userfaultfd"); + + uffdio_api.api = UFFD_API; + uffdio_api.features = 0; + if (ioctl(uffd, UFFDIO_API, &uffdio_api) == \-1) + errExit("ioctl\-UFFDIO_API"); + + /* Create a private anonymous mapping. The memory will be + demand\-zero paged\-\-that is, not yet allocated. When we + actually touch the memory, it will be allocated via + the userfaultfd. */ + + addr = mmap(NULL, len, PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_ANONYMOUS, \-1, 0); + if (addr == MAP_FAILED) + errExit("mmap"); + + printf("Address returned by mmap() = %p\\n", addr); + + /* Register the memory range of the mapping we just created for + handling by the userfaultfd object. In mode, we request to track + missing pages (i.e., pages that have not yet been faulted in). */ + + uffdio_register.range.start = (unsigned long) addr; + uffdio_register.range.len = len; + uffdio_register.mode = UFFDIO_REGISTER_MODE_MISSING; + if (ioctl(uffd, UFFDIO_REGISTER, &uffdio_register) == \-1) + errExit("ioctl\-UFFDIO_REGISTER"); + + /* Create a thread that will process the userfaultfd events */ + + s = pthread_create(&thr, NULL, fault_handler_thread, (void *) uffd); + if (s != 0) { + errno = s; + errExit("pthread_create"); + } + + /* Main thread now touches memory in the mapping, touching + locations 1024 bytes apart. This will trigger userfaultfd + events for all pages in the region. */ + + int l; + l = 0xf; /* Ensure that faulting address is not on a page + boundary, in order to test that we correctly + handle that case in fault_handling_thread() */ + while (l < len) { + char c = addr[l]; + printf("Read address %p in main(): ", addr + l); + printf("%c\\n", c); + l += 1024; + usleep(100000); /* Slow things down a little */ + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fcntl (2), +.BR ioctl (2), +.BR ioctl_userfaultfd (2), +.BR madvise (2), +.BR mmap (2) +.PP +.IR Documentation/vm/userfaultfd.txt +in the Linux kernel source tree +.PP +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/ustat.2 b/man2/ustat.2 new file mode 100644 index 0000000..41e9a88 --- /dev/null +++ b/man2/ustat.2 @@ -0,0 +1,127 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created 1995-08-09 Thomas K. Dyas +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2001-03-22 by aeb +.\" Modified 2003-08-04 by aeb +.\" +.TH USTAT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ustat \- get filesystem statistics +.SH SYNOPSIS +.nf +.B #include +.BR "#include " " /* libc[45] */" +.BR "#include " " /* glibc2 */" +.PP +.BI "int ustat(dev_t " dev ", struct ustat *" ubuf ); +.fi +.SH DESCRIPTION +.BR ustat () +returns information about a mounted filesystem. +.I dev +is a device number identifying a device containing +a mounted filesystem. +.I ubuf +is a pointer to a +.I ustat +structure that contains the following +members: +.PP +.in +4n +.EX +daddr_t f_tfree; /* Total free blocks */ +ino_t f_tinode; /* Number of free inodes */ +char f_fname[6]; /* Filsys name */ +char f_fpack[6]; /* Filsys pack name */ +.EE +.in +.PP +The last two fields, +.I f_fname +and +.IR f_fpack , +are not implemented and will +always be filled with null bytes (\(aq\\0\(aq). +.SH RETURN VALUE +On success, zero is returned and the +.I ustat +structure pointed to by +.I ubuf +will be filled in. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I ubuf +points outside of your accessible address space. +.TP +.B EINVAL +.I dev +does not refer to a device containing a mounted filesystem. +.TP +.B ENOSYS +The mounted filesystem referenced by +.I dev +does not support this operation, or any version of Linux before +1.3.16. +.SH CONFORMING TO +SVr4. +.\" SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR +.\" but has no ENOSYS condition. +.SH NOTES +.BR ustat () +is deprecated and has been provided only for compatibility. +All new programs should use +.BR statfs (2) +instead. +.SS HP-UX notes +The HP-UX version of the +.I ustat +structure has an additional field, +.IR f_blksize , +that is unknown elsewhere. +HP-UX warns: +For some filesystems, the number of free inodes does not change. +Such filesystems will return \-1 in the field +.IR f_tinode . +.\" Some software tries to use this in order to test whether the +.\" underlying filesystem is NFS. +For some filesystems, inodes are dynamically allocated. +Such filesystems will return the current number of free inodes. +.SH SEE ALSO +.BR stat (2), +.BR statfs (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/utime.2 b/man2/utime.2 new file mode 100644 index 0000000..6c848e8 --- /dev/null +++ b/man2/utime.2 @@ -0,0 +1,201 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-06-10 by Andries Brouwer +.\" Modified 2004-06-23 by Michael Kerrisk +.\" Modified 2004-10-10 by Andries Brouwer +.\" +.TH UTIME 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +utime, utimes \- change file last access and modification times +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int utime(const char *" filename ", const struct utimbuf *" times ); +.PP +.B #include +.PP +.BI "int utimes(const char *" filename ", const struct timeval " times [2]); +.fi +.SH DESCRIPTION +.B Note: +modern applications may prefer to use the interfaces described in +.BR utimensat (2). +.PP +The +.BR utime () +system call +changes the access and modification times of the inode specified by +.I filename +to the +.IR actime " and " modtime +fields of +.I times +respectively. +.PP +If +.I times +is NULL, then the access and modification times of the file are set +to the current time. +.PP +Changing timestamps is permitted when: either +the process has appropriate privileges, +or the effective user ID equals the user ID +of the file, or +.I times +is NULL and the process has write permission for the file. +.PP +The +.I utimbuf +structure is: +.PP +.in +4n +.EX +struct utimbuf { + time_t actime; /* access time */ + time_t modtime; /* modification time */ +}; +.EE +.in +.PP +The +.BR utime () +system call +allows specification of timestamps with a resolution of 1 second. +.PP +The +.BR utimes () +system call +is similar, but the +.I times +argument refers to an array rather than a structure. +The elements of this array are +.I timeval +structures, which allow a precision of 1 microsecond for specifying timestamps. +The +.I timeval +structure is: +.PP +.in +4n +.EX +struct timeval { + long tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.EE +.in +.PP +.IR times [0] +specifies the new access time, and +.IR times [1] +specifies the new modification time. +If +.I times +is NULL, then analogously to +.BR utime (), +the access and modification times of the file are +set to the current time. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories in +the path prefix of +.I path +(see also +.BR path_resolution (7)). +.TP +.B EACCES +.I times +is NULL, +the caller's effective user ID does not match the owner of the file, +the caller does not have write access to the file, +and the caller is not privileged +(Linux: does not have either the +.B CAP_DAC_OVERRIDE +or the +.B CAP_FOWNER +capability). +.TP +.B ENOENT +.I filename +does not exist. +.TP +.B EPERM +.I times +is not NULL, +the caller's effective UID does not match the owner of the file, +and the caller is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability). +.TP +.B EROFS +.I path +resides on a read-only filesystem. +.SH CONFORMING TO +.BR utime (): +SVr4, POSIX.1-2001. +POSIX.1-2008 marks +.BR utime () +as obsolete. +.PP +.BR utimes (): +4.3BSD, POSIX.1-2001. +.SH NOTES +Linux does not allow changing the timestamps on an immutable file, +or setting the timestamps to something other than the current time +on an append-only file. +.\" +.\" In libc4 and libc5, +.\" .BR utimes () +.\" is just a wrapper for +.\" .BR utime () +.\" and hence does not allow a subsecond resolution. +.SH SEE ALSO +.BR chattr (1), +.BR touch (1), +.BR futimesat (2), +.BR stat (2), +.BR utimensat (2), +.BR futimens (3), +.BR futimes (3), +.BR inode (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/utimensat.2 b/man2/utimensat.2 new file mode 100644 index 0000000..5414b86 --- /dev/null +++ b/man2/utimensat.2 @@ -0,0 +1,655 @@ +.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH UTIMENSAT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +utimensat, futimens \- change file timestamps with nanosecond precision +.SH SYNOPSIS +.nf +.B #include /* Definition of AT_* constants */ +.B #include +.PP +.BI "int utimensat(int " dirfd ", const char *" pathname , +.BI " const struct timespec " times "[2], int " flags ); +.PP +.BI "int futimens(int " fd ", const struct timespec " times [2]); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.PD 0 +.BR utimensat (): +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.PP +.BR futimens (): +.RS 4 +.TP +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.ad +.SH DESCRIPTION +.BR utimensat () +and +.BR futimens () +update the timestamps of a file with nanosecond precision. +This contrasts with the historical +.BR utime (2) +and +.BR utimes (2), +which permit only second and microsecond precision, respectively, +when setting file timestamps. +.PP +With +.BR utimensat () +the file is specified via the pathname given in +.IR pathname . +With +.BR futimens () +the file whose timestamps are to be updated is specified via +an open file descriptor, +.IR fd . +.PP +For both calls, the new file timestamps are specified in the array +.IR times : +.IR times [0] +specifies the new "last access time" (\fIatime\fP); +.IR times [1] +specifies the new "last modification time" (\fImtime\fP). +Each of the elements of +.I times +specifies a time as the number of seconds and nanoseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +This information is conveyed in a structure of the following form: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.PP +Updated file timestamps are set to the greatest value +supported by the filesystem that is not greater than the specified time. +.PP +If the +.I tv_nsec +field of one of the +.I timespec +structures has the special value +.BR UTIME_NOW , +then the corresponding file timestamp is set to the current time. +If the +.I tv_nsec +field of one of the +.I timespec +structures has the special value +.BR UTIME_OMIT , +then the corresponding file timestamp is left unchanged. +In both of these cases, the value of the corresponding +.I tv_sec +.\" 2.6.22 was broken: it is not ignored +field is ignored. +.PP +If +.I times +is NULL, then both timestamps are set to the current time. +.\" +.SS Permissions requirements +To set both file timestamps to the current time (i.e., +.I times +is NULL, or both +.I tv_nsec +fields specify +.BR UTIME_NOW ), +either: +.IP 1. 3 +the caller must have write access to the file; +.\" 2.6.22 was broken here -- for futimens() the check is +.\" based on whether or not the file descriptor is writable, +.\" not on whether the caller's effective UID has write +.\" permission for the file referred to by the descriptor. +.IP 2. +the caller's effective user ID must match the owner of the file; or +.IP 3. +the caller must have appropriate privileges. +.PP +To make any change other than setting both timestamps to the +current time (i.e., +.I times +is not NULL, and neither +.I tv_nsec +field is +.B UTIME_NOW +.\" 2.6.22 was broken here: +.\" both must be something other than *either* UTIME_OMIT *or* UTIME_NOW. +and neither +.I tv_nsec +field is +.BR UTIME_OMIT ), +either condition 2 or 3 above must apply. +.PP +If both +.I tv_nsec +fields are specified as +.BR UTIME_OMIT , +then no file ownership or permission checks are performed, +and the file timestamps are not modified, +but other error conditions may still be detected. +.\" +.\" +.SS utimensat() specifics +If +.I pathname +is relative, then by default it is interpreted relative to the +directory referred to by the open file descriptor, +.IR dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR utimes (2) +for a relative pathname). +See +.BR openat (2) +for an explanation of why this can be useful. +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR utimes (2)). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.PP +The +.I flags +field is a bit mask that may be 0, or include the following constant, +defined in +.IR : +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +specifies a symbolic link, then update the timestamps of the link, +rather than the file to which it refers. +.SH RETURN VALUE +On success, +.BR utimensat () +and +.BR futimens () +return 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.I times +is NULL, +or both +.I tv_nsec +values are +.BR UTIME_NOW , +and either: +.RS +.IP * 3 +the effective user ID of the caller does not match +the owner of the file, +the caller does not have write access to the file, +and the caller is not privileged +(Linux: does not have either the +.B CAP_FOWNER +or the +.B CAP_DAC_OVERRIDE +capability); or, +.\" But Linux 2.6.22 was broken here. +.\" Traditionally, utime()/utimes() gives the error EACCES for the case +.\" where the timestamp pointer argument is NULL (i.e., set both timestamps +.\" to the current time), and the file is owned by a user other than the +.\" effective UID of the caller, and the file is not writable by the +.\" effective UID of the program. utimensat() also gives this error in the +.\" same case. However, in the same circumstances, when utimensat() is +.\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which +.\" provides equivalent functionality to specifying 'times' as NULL, the +.\" call succeeds. It should fail with the error EACCES in this case. +.\" +.\" POSIX.1-2008 has the following: +.\" .TP +.\" .B EACCES +.\" .RB ( utimensat ()) +.\" .I fd +.\" was not opened with +.\" .B O_SEARCH +.\" and the permissions of the directory to which +.\" .I fd +.\" refers do not allow searches. +.IP * +the file is marked immutable (see +.BR chattr (1)). +.\" EXT2_IMMUTABLE_FL and similar flags for other filesystems. +.RE +.TP +.B EBADF +.RB ( futimens ()) +.I fd +is not a valid file descriptor. +.TP +.B EBADF +.RB ( utimensat ()) +.I pathname +is a relative pathname, but +.I dirfd +is neither +.BR AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I times +pointed to an invalid address; or, +.I dirfd +was +.BR AT_FDCWD , +and +.I pathname +is NULL or an invalid address. +.TP +.B EINVAL +Invalid value in +.IR flags . +.TP +.B EINVAL +Invalid value in one of the +.I tv_nsec +fields (value outside range 0 to 999,999,999, and not +.B UTIME_NOW +or +.BR UTIME_OMIT ); +or an invalid value in one of the +.I tv_sec +fields. +.TP +.B EINVAL +.\" SUSv4 does not specify this error. +.I pathname +is NULL, +.I dirfd +is not +.BR AT_FDCWD , +and +.I flags +contains +.BR AT_SYMLINK_NOFOLLOW . +.TP +.B ELOOP +.RB ( utimensat ()) +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.RB ( utimensat ()) +.I pathname +is too long. +.TP +.B ENOENT +.RB ( utimensat ()) +A component of +.I pathname +does not refer to an existing directory or file, +or +.I pathname +is an empty string. +.TP +.B ENOTDIR +.RB ( utimensat ()) +.I pathname +is a relative pathname, but +.I dirfd +is neither +.B AT_FDCWD +nor a file descriptor referring to a directory; +or, one of the prefix components of +.I pathname +is not a directory. +.TP +.B EPERM +The caller attempted to change one or both timestamps to a value +other than the current time, +or to change one of the timestamps to the current time while +leaving the other timestamp unchanged, +(i.e., +.I times +is not NULL, neither +.I tv_nsec +field is +.BR UTIME_NOW , +and neither +.I tv_nsec +field is +.BR UTIME_OMIT ) +and either: +.RS +.IP * 3 +the caller's effective user ID does not match the owner of file, +and the caller is not privileged +(Linux: does not have the +.BR CAP_FOWNER +capability); or, +.IP * +.\" Linux 2.6.22 was broken here: +.\" it was not consistent with the old utimes() implementation, +.\" since the case when both tv_nsec fields are UTIME_NOW, was not +.\" treated like the (times == NULL) case. +the file is marked append-only or immutable (see +.BR chattr (1)). +.\" EXT2_IMMUTABLE_FL EXT_APPPEND_FL and similar flags for +.\" other filesystems. +.\" +.\" Why the inconsistency (which is described under NOTES) between +.\" EACCES and EPERM, where only EPERM tests for append-only. +.\" (This was also so for the older utimes() implementation.) +.RE +.TP +.B EROFS +The file is on a read-only filesystem. +.TP +.B ESRCH +.RB ( utimensat ()) +Search permission is denied for one of the prefix components of +.IR pathname . +.SH VERSIONS +.BR utimensat () +was added to Linux in kernel 2.6.22; +glibc support was added with version 2.6. +.PP +Support for +.BR futimens () +first appeared in glibc 2.6. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR utimensat (), +.BR futimens () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +.BR futimens () +and +.BR utimensat () +are specified in POSIX.1-2008. +.SH NOTES +.BR utimensat () +obsoletes +.BR futimesat (2). +.PP +On Linux, timestamps cannot be changed for a file marked immutable, +and the only change permitted for files marked append-only is to +set the timestamps to the current time. +(This is consistent with the historical behavior of +.BR utime (2) +and +.BR utimes (2) +on Linux.) +.PP +If both +.I tv_nsec +fields are specified as +.BR UTIME_OMIT , +then the Linux implementation of +.BR utimensat () +succeeds even if the file referred to by +.IR dirfd +and +.I pathname +does not exist. +.SS C library/kernel ABI differences +On Linux, +.BR futimens () +is a library function implemented on top of the +.BR utimensat () +system call. +To support this, the Linux +.BR utimensat () +system call implements a nonstandard feature: if +.I pathname +is NULL, then the call modifies the timestamps of +the file referred to by the file descriptor +.I dirfd +(which may refer to any type of file). +Using this feature, the call +.I "futimens(fd,\ times)" +is implemented as: +.PP +.in +4n +.EX +utimensat(fd, NULL, times, 0); +.EE +.in +.PP +Note, however, that the glibc wrapper for +.BR utimensat () +disallows passing NULL as the value for +.IR pathname : +the wrapper function returns the error +.IR EINVAL +in this case. +.SH BUGS +Several bugs afflict +.BR utimensat () +and +.BR futimens () +on kernels before 2.6.26. +These bugs are either nonconformances with the POSIX.1 draft specification +or inconsistencies with historical Linux behavior. +.IP * 3 +POSIX.1 specifies that if one of the +.I tv_nsec +fields has the value +.B UTIME_NOW +or +.BR UTIME_OMIT , +then the value of the corresponding +.I tv_sec +field should be ignored. +Instead, the value of the +.I tv_sec +field is required to be 0 (or the error +.B EINVAL +results). +.IP * +Various bugs mean that for the purposes of permission checking, +the case where both +.I tv_nsec +fields are set to +.BR UTIME_NOW +isn't always treated the same as specifying +.I times +as NULL, +and the case where one +.I tv_nsec +value is +.B UTIME_NOW +and the other is +.B UTIME_OMIT +isn't treated the same as specifying +.I times +as a pointer to an array of structures containing arbitrary time values. +As a result, in some cases: +a) file timestamps can be updated by a process that shouldn't have +permission to perform updates; +b) file timestamps can't be updated by a process that should have +permission to perform updates; and +c) the wrong +.I errno +value is returned in case of an error. +.\" Below, the long description of the errors from the previous bullet +.\" point (abridged because it's too much detail for a man page). +.\" .IP * +.\" If one of the +.\" .I tv_nsec +.\" fields is +.\" .BR UTIME_OMIT +.\" and the other is +.\" .BR UTIME_NOW , +.\" then the error +.\" .B EPERM +.\" should occur if the process's effective user ID does not match +.\" the file owner and the process is not privileged. +.\" Instead, the call successfully changes one of the timestamps. +.\" .IP * +.\" If file is not writable by the effective user ID of the process and +.\" the process's effective user ID does not match the file owner and +.\" the process is not privileged, +.\" and +.\" .I times +.\" is NULL, then the error +.\" .B EACCES +.\" results. +.\" This error should also occur if +.\" .I times +.\" points to an array of structures in which both +.\" .I tv_nsec +.\" fields are +.\" .BR UTIME_NOW . +.\" Instead the call succeeds. +.\" .IP * +.\" If a file is marked as append-only (see +.\" .BR chattr (1)), +.\" then Linux traditionally +.\" (i.e., +.\" .BR utime (2), +.\" .BR utimes (2)), +.\" permits a NULL +.\" .I times +.\" argument to be used in order to update both timestamps to the current time. +.\" For consistency, +.\" .BR utimensat () +.\" and +.\" .BR futimens () +.\" should also produce the same result when given a +.\" .I times +.\" argument that points to an array of structures in which both +.\" .I tv_nsec +.\" fields are +.\" .BR UTIME_NOW . +.\" Instead, the call fails with the error +.\" .BR EPERM . +.\" .IP * +.\" If a file is marked as immutable (see +.\" .BR chattr (1)), +.\" then Linux traditionally +.\" (i.e., +.\" .BR utime (2), +.\" .BR utimes (2)), +.\" gives an +.\" .B EACCES +.\" error if +.\" .I times +.\" is NULL. +.\" For consistency, +.\" .BR utimensat () +.\" and +.\" .BR futimens () +.\" should also produce the same result when given a +.\" .I times +.\" that points to an array of structures in which both +.\" .I tv_nsec +.\" fields are +.\" .BR UTIME_NOW . +.\" Instead, the call fails with the error +.\" .BR EPERM . +.IP * +POSIX.1 says that a process that has \fIwrite access to the file\fP +can make a call with +.I times +as NULL, or with +.I times +pointing to an array of structures in which both +.I tv_nsec +fields are +.BR UTIME_NOW , +in order to update both timestamps to the current time. +However, +.BR futimens () +instead checks whether the +.IR "access mode of the file descriptor allows writing" . +.\" This means that a process with a file descriptor that allows +.\" writing could change the timestamps of a file for which it +.\" does not have write permission; +.\" conversely, a process with a read-only file descriptor won't +.\" be able to update the timestamps of a file, +.\" even if it has write permission on the file. +.SH SEE ALSO +.BR chattr (1), +.BR touch (1), +.BR futimesat (2), +.BR openat (2), +.BR stat (2), +.BR utimes (2), +.BR futimes (3), +.BR inode (7), +.BR path_resolution (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/utimes.2 b/man2/utimes.2 new file mode 100644 index 0000000..04372d4 --- /dev/null +++ b/man2/utimes.2 @@ -0,0 +1 @@ +.so man2/utime.2 diff --git a/man2/vfork.2 b/man2/vfork.2 new file mode 100644 index 0000000..32d6042 --- /dev/null +++ b/man2/vfork.2 @@ -0,0 +1,346 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl), 1 Nov 1999 +.\" and Copyright 2006, 2012, 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 1999-11-10: Merged text taken from the page contributed by +.\" Reed H. Petty (rhp@draper.net) +.\" +.TH VFORK 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +vfork \- create a child process and block parent +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B pid_t vfork(void); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR vfork (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.12: +.nf +(_XOPEN_SOURCE\ >=\ 500) && ! (_POSIX_C_SOURCE\ >=\ 200809L) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.TP 4 +.fi +Before glibc 2.12: +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH DESCRIPTION +.SS Standard description +(From POSIX.1) +The +.BR vfork () +function has the same effect as +.BR fork (2), +except that the behavior is undefined if the process created by +.BR vfork () +either modifies any data other than a variable of type +.I pid_t +used to store the return value from +.BR vfork (), +or returns from the function in which +.BR vfork () +was called, or calls any other function before successfully calling +.BR _exit (2) +or one of the +.BR exec (3) +family of functions. +.SS Linux description +.BR vfork (), +just like +.BR fork (2), +creates a child process of the calling process. +For details and return value and errors, see +.BR fork (2). +.PP +.BR vfork () +is a special case of +.BR clone (2). +It is used to create new processes without copying the page tables of +the parent process. +It may be useful in performance-sensitive applications +where a child is created which then immediately issues an +.BR execve (2). +.PP +.BR vfork () +differs from +.BR fork (2) +in that the calling thread is suspended until the child terminates +(either normally, +by calling +.BR _exit (2), +or abnormally, after delivery of a fatal signal), +or it makes a call to +.BR execve (2). +Until that point, the child shares all memory with its parent, +including the stack. +The child must not return from the current function or call +.BR exit (3) +(which would have the effect of calling exit handlers +established by the parent process and flushing the parent's +.BR stdio (3) +buffers), but may call +.BR _exit (2). +.PP +As with +.BR fork (2), +the child process created by +.BR vfork () +inherits copies of various of the caller's process attributes +(e.g., file descriptors, signal dispositions, and current working directory); +the +.BR vfork () +call differs only in the treatment of the virtual address space, +as described above. +.PP +Signals sent to the parent +arrive after the child releases the parent's memory +(i.e., after the child terminates +or calls +.BR execve (2)). +.SS Historic description +Under Linux, +.BR fork (2) +is implemented using copy-on-write pages, so the only penalty incurred by +.BR fork (2) +is the time and memory required to duplicate the parent's page tables, +and to create a unique task structure for the child. +However, in the bad old days a +.BR fork (2) +would require making a complete copy of the caller's data space, +often needlessly, since usually immediately afterward an +.BR exec (3) +is done. +Thus, for greater efficiency, BSD introduced the +.BR vfork () +system call, which did not fully copy the address space of +the parent process, but borrowed the parent's memory and thread +of control until a call to +.BR execve (2) +or an exit occurred. +The parent process was suspended while the +child was using its resources. +The use of +.BR vfork () +was tricky: for example, not modifying data +in the parent process depended on knowing which variables were +held in a register. +.SH CONFORMING TO +4.3BSD; POSIX.1-2001 (but marked OBSOLETE). +POSIX.1-2008 removes the specification of +.BR vfork (). +.PP +The requirements put on +.BR vfork () +by the standards are weaker than those put on +.BR fork (2), +so an implementation where the two are synonymous is compliant. +In particular, the programmer cannot rely on the parent +remaining blocked until the child either terminates or calls +.BR execve (2), +and cannot rely on any specific behavior with respect to shared memory. +.\" In AIXv3.1 vfork is equivalent to fork. +.SH NOTES +.PP +Some consider the semantics of +.BR vfork () +to be an architectural blemish, and the 4.2BSD man page stated: +"This system call will be eliminated when proper system sharing mechanisms +are implemented. +Users should not depend on the memory sharing semantics of +.BR vfork () +as it will, in that case, be made synonymous to +.BR fork (2).\c +" +However, even though modern memory management hardware +has decreased the performance difference between +.BR fork (2) +and +.BR vfork (), +there are various reasons why Linux and other systems have retained +.BR vfork (): +.IP * 3 +Some performance-critical applications require the small performance +advantage conferred by +.BR vfork (). +.IP * +.BR vfork () +can be implemented on systems that lack a memory-management unit (MMU), but +.BR fork (2) +can't be implemented on such systems. +(POSIX.1-2008 removed +.BR vfork () +from the standard; the POSIX rationale for the +.BR posix_spawn (3) +function notes that that function, +which provides functionality equivalent to +.BR fork (2)+ exec (3), +is designed to be implementable on systems that lack an MMU.) +.\" http://stackoverflow.com/questions/4259629/what-is-the-difference-between-fork-and-vfork +.\" http://developers.sun.com/solaris/articles/subprocess/subprocess.html +.\" http://mailman.uclinux.org/pipermail/uclinux-dev/2009-April/000684.html +.\" +.IP * +On systems where memory is constrained, +.BR vfork () +avoids the need to temporarily commit memory (see the description of +.IR /proc/sys/vm/overcommit_memory +in +.BR proc (5)) +in order to execute a new program. +(This can be especially beneficial where a large parent process wishes +to execute a small helper program in a child process.) +By contrast, using +.BR fork (2) +in this scenario requires either committing an amount of memory equal +to the size of the parent process (if strict overcommitting is in force) +or overcommitting memory with the risk that a process is terminated +by the out-of-memory (OOM) killer. +.\" +.SS Caveats +The child process should take care not to modify the memory in unintended ways, +since such changes will be seen by the parent process once +the child terminates or executes another program. +In this regard, signal handlers can be especially problematic: +if a signal handler that is invoked in the child of +.BR vfork () +changes memory, those changes may result in an inconsistent process state +from the perspective of the parent process +(e.g., memory changes would be visible in the parent, +but changes to the state of open file descriptors would not be visible). +.PP +When +.BR vfork () +is called in a multithreaded process, +only the calling thread is suspended until the child terminates +or executes a new program. +This means that the child is sharing an address space with other running code. +This can be dangerous if another thread in the parent process +changes credentials (using +.BR setuid (2) +or similar), +since there are now two processes with different privilege levels +running in the same address space. +As an example of the dangers, +suppose that a multithreaded program running as root creates a child using +.BR vfork (). +After the +.BR vfork (), +a thread in the parent process drops the process to an unprivileged user +in order to run some untrusted code +(e.g., perhaps via plug-in opened with +.BR dlopen (3)). +In this case, attacks are possible where the parent process uses +.BR mmap (2) +to map in code that will be executed by the privileged child process. +.\" +.SS Linux notes +Fork handlers established using +.BR pthread_atfork (3) +are not called when a multithreaded program employing +the NPTL threading library calls +.BR vfork (). +Fork handlers are called in this case in a program using the +LinuxThreads threading library. +(See +.BR pthreads (7) +for a description of Linux threading libraries.) +.PP +A call to +.BR vfork () +is equivalent to calling +.BR clone (2) +with +.I flags +specified as: +.PP + CLONE_VM | CLONE_VFORK | SIGCHLD +.SS History +The +.BR vfork () +system call appeared in 3.0BSD. +.\" In the release notes for 4.2BSD Sam Leffler wrote: `vfork: Is still +.\" present, but definitely on its way out'. +In 4.4BSD it was made synonymous to +.BR fork (2) +but NetBSD introduced it again; +see +.UR http://www.netbsd.org\:/Documentation\:/kernel\:/vfork.html +.UE . +In Linux, it has been equivalent to +.BR fork (2) +until 2.2.0-pre6 or so. +Since 2.2.0-pre9 (on i386, somewhat later on +other architectures) it is an independent system call. +Support was added in glibc 2.0.112. +.SH BUGS +.PP +Details of the signal handling are obscure and differ between systems. +The BSD man page states: +"To avoid a possible deadlock situation, processes that are children +in the middle of a +.BR vfork () +are never sent +.B SIGTTOU +or +.B SIGTTIN +signals; rather, output or +.IR ioctl s +are allowed and input attempts result in an end-of-file indication." +.\" +.\" As far as I can tell, the following is not true in 2.6.19: +.\" Currently (Linux 2.3.25), +.\" .BR strace (1) +.\" cannot follow +.\" .BR vfork () +.\" and requires a kernel patch. +.SH SEE ALSO +.BR clone (2), +.BR execve (2), +.BR _exit (2), +.BR fork (2), +.BR unshare (2), +.BR wait (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/vhangup.2 b/man2/vhangup.2 new file mode 100644 index 0000000..a8117f0 --- /dev/null +++ b/man2/vhangup.2 @@ -0,0 +1,85 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH VHANGUP 2 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +vhangup \- virtually hangup the current terminal +.SH SYNOPSIS +.B #include +.PP +.B int vhangup(void); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR vhangup (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.fi +.ad b +.SH DESCRIPTION +.BR vhangup () +simulates a hangup on the current terminal. +This call arranges for other +users to have a \*(lqclean\*(rq terminal at login time. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR vhangup (); +the +.B CAP_SYS_TTY_CONFIG +capability is required. +.SH CONFORMING TO +This call is Linux-specific, and should not be used in programs +intended to be portable. +.SH SEE ALSO +.BR init (1), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/vm86.2 b/man2/vm86.2 new file mode 100644 index 0000000..2893e8c --- /dev/null +++ b/man2/vm86.2 @@ -0,0 +1,84 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Copyright 1997 Andries E. Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH VM86 2 2009-02-20 "Linux" "Linux Programmer's Manual" +.SH NAME +vm86old, vm86 \- enter virtual 8086 mode +.SH SYNOPSIS +.B #include +.PP +.BI "int vm86old(struct vm86_struct *" info ); +.PP +.BI "int vm86(unsigned long " fn ", struct vm86plus_struct *" v86 ); +.SH DESCRIPTION +The system call +.BR vm86 () +was introduced in Linux 0.97p2. +In Linux 2.1.15 and 2.0.28, it was renamed to +.BR vm86old (), +and a new +.BR vm86 () +was introduced. +The definition of +.IR "struct vm86_struct" +was changed +in 1.1.8 and 1.1.9. +.PP +These calls cause the process to enter VM86 mode (virtual-8086 in Intel +literature), and are used by +.BR dosemu . +.PP +VM86 mode is an emulation of real mode within a protected mode task. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +This return value is specific to i386 and indicates a problem with getting +user-space data. +.TP +.B ENOSYS +This return value indicates the call is not implemented on the present +architecture. +.TP +.B EPERM +Saved kernel stack exists. +(This is a kernel sanity check; the saved +stack should exist only within vm86 mode itself.) +.SH CONFORMING TO +This call is specific to Linux on 32-bit Intel processors, +and should not be used in programs intended to be portable. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/vm86old.2 b/man2/vm86old.2 new file mode 100644 index 0000000..bf2581d --- /dev/null +++ b/man2/vm86old.2 @@ -0,0 +1 @@ +.so man2/vm86.2 diff --git a/man2/vmsplice.2 b/man2/vmsplice.2 new file mode 100644 index 0000000..8d3aff4 --- /dev/null +++ b/man2/vmsplice.2 @@ -0,0 +1,178 @@ +.\" This manpage is Copyright (C) 2006 Jens Axboe +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH VMSPLICE 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +vmsplice \- splice user pages into a pipe +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.B #include +.PP +.BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov , +.BI " unsigned long " nr_segs ", unsigned int " flags ); +.fi +.\" Return type was long before glibc 2.7 +.SH DESCRIPTION +.\" Linus: vmsplice() system call to basically do a "write to +.\" the buffer", but using the reference counting and VM traversal +.\" to actually fill the buffer. This means that the user needs to +.\" be careful not to reuse the user-space buffer it spliced into +.\" the kernel-space one (contrast this to "write()", which copies +.\" the actual data, and you can thus reuse the buffer immediately +.\" after a successful write), but that is often easy to do. +The +.BR vmsplice () +system call maps +.I nr_segs +ranges of user memory described by +.I iov +into a pipe. +The file descriptor +.I fd +must refer to a pipe. +.PP +The pointer +.I iov +points to an array of +.I iovec +structures as defined in +.IR : +.PP +.in +4n +.EX +struct iovec { + void *iov_base; /* Starting address */ + size_t iov_len; /* Number of bytes */ +}; +.EE +.in +.PP +The +.I flags +argument is a bit mask that is composed by ORing together +zero or more of the following values: +.TP +.B SPLICE_F_MOVE +Unused for +.BR vmsplice (); +see +.BR splice (2). +.TP +.B SPLICE_F_NONBLOCK +.\" Not used for vmsplice +.\" May be in the future -- therefore EAGAIN +Do not block on I/O; see +.BR splice (2) +for further details. +.TP +.B SPLICE_F_MORE +Currently has no effect for +.BR vmsplice (), +but may be implemented in the future; see +.BR splice (2). +.TP +.B SPLICE_F_GIFT +The user pages are a gift to the kernel. +The application may not modify this memory ever, +.\" FIXME . Explain the following line in a little more detail: +otherwise the page cache and on-disk data may differ. +Gifting pages to the kernel means that a subsequent +.BR splice (2) +.B SPLICE_F_MOVE +can successfully move the pages; +if this flag is not specified, then a subsequent +.BR splice (2) +.B SPLICE_F_MOVE +must copy the pages. +Data must also be properly page aligned, both in memory and length. +.\" FIXME +.\" It looks like the page-alignment requirement went away with +.\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d +.\" +.\" .... if we expect to later SPLICE_F_MOVE to the cache. +.SH RETURN VALUE +Upon successful completion, +.BR vmsplice () +returns the number of bytes transferred to the pipe. +On error, +.BR vmsplice () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.B SPLICE_F_NONBLOCK +was specified in +.IR flags , +and the operation would block. +.TP +.B EBADF +.I fd +either not valid, or doesn't refer to a pipe. +.TP +.B EINVAL +.I nr_segs +is greater than +.BR IOV_MAX ; +or memory not aligned if +.B SPLICE_F_GIFT +set. +.TP +.B ENOMEM +Out of memory. +.SH VERSIONS +The +.BR vmsplice () +system call first appeared in Linux 2.6.17; +library support was added to glibc in version 2.5. +.SH CONFORMING TO +This system call is Linux-specific. +.SH NOTES +.BR vmsplice () +follows the other vectorized read/write type functions when it comes to +limitations on the number of segments being passed in. +This limit is +.B IOV_MAX +as defined in +.IR . +Currently, +.\" UIO_MAXIOV in kernel source +this limit is 1024. +.SH SEE ALSO +.BR splice (2), +.BR tee (2), +.BR pipe (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/vserver.2 b/man2/vserver.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man2/vserver.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man2/wait.2 b/man2/wait.2 new file mode 100644 index 0000000..b338944 --- /dev/null +++ b/man2/wait.2 @@ -0,0 +1,709 @@ +.\" Copyright (c) 1993 by Thomas Koenig +.\" and Copyright (c) 2004 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith +.\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith +.\" (Thanks to Koen Holtman ) +.\" Modified Wed May 17 15:54:12 1995 by Rik Faith +.\" To remove *'s from status in macros (Thanks to Michael Shields). +.\" Modified as suggested by Nick Duffek , aeb, 960426 +.\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR. +.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. +.\" Modified Mon Jul 24 21:37:38 2000 by David A. Wheeler +.\" - noted thread issues. +.\" Modified 26 Jun 01 by Michael Kerrisk +.\" Added __WCLONE, __WALL, and __WNOTHREAD descriptions +.\" Modified 2001-09-25, aeb +.\" Modified 26 Jun 01 by Michael Kerrisk, +.\" Updated notes on setting disposition of SIGCHLD to SIG_IGN +.\" 2004-11-11, mtk +.\" Added waitid(2); added WCONTINUED and WIFCONTINUED() +.\" Added text on SA_NOCLDSTOP +.\" Updated discussion of SA_NOCLDWAIT to reflect 2.6 behavior +.\" Much other text rewritten +.\" 2005-05-10, mtk, __W* flags can't be used with waitid() +.\" 2008-07-04, mtk, removed erroneous text about SA_NOCLDSTOP +.\" +.TH WAIT 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +wait, waitpid, waitid \- wait for process to change state +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "pid_t wait(int *" "wstatus" ); +.PP +.BI "pid_t waitpid(pid_t " pid ", int *" wstatus ", int " options ); +.PP +.BI "int waitid(idtype_t " idtype ", id_t " id \ +", siginfo_t *" infop ", int " options ); + /* This is the glibc and POSIX interface; see + NOTES for information on the raw system call. */ +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.PD 0 +.BR waitid (): +.RS 4 +Since glibc 2.26: +_XOPEN_SOURCE >= 500 || +.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + _POSIX_C_SOURCE\ >=\ 200809L +.br +Glibc 2.25 and earlier: + _XOPEN_SOURCE + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.PD +.ad +.SH DESCRIPTION +All of these system calls are used to wait for state changes +in a child of the calling process, and obtain information +about the child whose state has changed. +A state change is considered to be: the child terminated; +the child was stopped by a signal; or the child was resumed by a signal. +In the case of a terminated child, performing a wait allows +the system to release the resources associated with the child; +if a wait is not performed, then the terminated child remains in +a "zombie" state (see NOTES below). +.PP +If a child has already changed state, then these calls return immediately. +Otherwise, they block until either a child changes state or +a signal handler interrupts the call (assuming that system calls +are not automatically restarted using the +.B SA_RESTART +flag of +.BR sigaction (2)). +In the remainder of this page, a child whose state has changed +and which has not yet been waited upon by one of these system +calls is termed +.IR waitable . +.SS wait() and waitpid() +The +.BR wait () +system call suspends execution of the calling process until one of its +children terminates. +The call +.I wait(&wstatus) +is equivalent to: +.PP +.in +4n +.EX +waitpid(\-1, &wstatus, 0); +.EE +.in +.PP +The +.BR waitpid () +system call suspends execution of the calling process until a +child specified by +.I pid +argument has changed state. +By default, +.BR waitpid () +waits only for terminated children, but this behavior is modifiable +via the +.I options +argument, as described below. +.PP +The value of +.I pid +can be: +.IP "< \-1" +meaning wait for any child process whose process group ID is +equal to the absolute value of +.IR pid . +.IP \-1 +meaning wait for any child process. +.IP 0 +meaning wait for any child process whose process group ID is +equal to that of the calling process. +.IP "> 0" +meaning wait for the child whose process ID is equal to the +value of +.IR pid . +.PP +The value of +.I options +is an OR of zero or more of the following constants: +.TP 12 +.B WNOHANG +return immediately if no child has exited. +.TP +.B WUNTRACED +also return if a child has stopped +(but not traced via +.BR ptrace (2)). +Status for +.I traced +children which have stopped is provided +even if this option is not specified. +.TP +.BR WCONTINUED " (since Linux 2.6.10)" +also return if a stopped child has been resumed by delivery of +.BR SIGCONT . +.PP +(For Linux-only options, see below.) +.PP +If +.I wstatus +is not NULL, +.BR wait () +and +.BR waitpid () +store status information in the \fIint\fP to which it points. +This integer can be inspected with the following macros (which +take the integer itself as an argument, not a pointer to it, +as is done in +.BR wait () +and +.BR waitpid ()!): +.TP +.BI WIFEXITED( wstatus ) +returns true if the child terminated normally, that is, +by calling +.BR exit (3) +or +.BR _exit (2), +or by returning from main(). +.TP +.BI WEXITSTATUS( wstatus ) +returns the exit status of the child. +This consists of the least significant 8 bits of the +.I status +argument that the child specified in a call to +.BR exit (3) +or +.BR _exit (2) +or as the argument for a return statement in main(). +This macro should be employed only if +.B WIFEXITED +returned true. +.TP +.BI WIFSIGNALED( wstatus ) +returns true if the child process was terminated by a signal. +.TP +.BI WTERMSIG( wstatus ) +returns the number of the signal that caused the child process to +terminate. +This macro should be employed only if +.B WIFSIGNALED +returned true. +.TP +.BI WCOREDUMP( wstatus ) +returns true if the child produced a core dump. +This macro should be employed only if +.B WIFSIGNALED +returned true. +.IP +This macro is not specified in POSIX.1-2001 and is not available on +some UNIX implementations (e.g., AIX, SunOS). +Therefore, enclose its use inside +.IR "#ifdef WCOREDUMP ... #endif" . +.TP +.BI WIFSTOPPED( wstatus ) +returns true if the child process was stopped by delivery of a signal; +this is possible only if the call was done using +.B WUNTRACED +or when the child is being traced (see +.BR ptrace (2)). +.TP +.BI WSTOPSIG( wstatus ) +returns the number of the signal which caused the child to stop. +This macro should be employed only if +.B WIFSTOPPED +returned true. +.TP +.BI WIFCONTINUED( wstatus ) +(since Linux 2.6.10) +returns true if the child process was resumed by delivery of +.BR SIGCONT . +.SS waitid() +The +.BR waitid () +system call (available since Linux 2.6.9) provides more precise +control over which child state changes to wait for. +.PP +The +.I idtype +and +.I id +arguments select the child(ren) to wait for, as follows: +.IP "\fIidtype\fP == \fBP_PID\fP" +Wait for the child whose process ID matches +.IR id . +.IP "\fIidtype\fP == \fBP_PGID\fP" +Wait for any child whose process group ID matches +.IR id . +.IP "\fIidtype\fP == \fBP_ALL\fP" +Wait for any child; +.I id +is ignored. +.PP +The child state changes to wait for are specified by ORing +one or more of the following flags in +.IR options : +.TP 12 +.B WEXITED +Wait for children that have terminated. +.TP +.B WSTOPPED +Wait for children that have been stopped by delivery of a signal. +.TP +.B WCONTINUED +Wait for (previously stopped) children that have been +resumed by delivery of +.BR SIGCONT . +.PP +The following flags may additionally be ORed in +.IR options : +.TP 12 +.B WNOHANG +As for +.BR waitpid (). +.TP +.B WNOWAIT +Leave the child in a waitable state; a later wait call +can be used to again retrieve the child status information. +.PP +Upon successful return, +.BR waitid () +fills in the following fields of the +.I siginfo_t +structure pointed to by +.IR infop : +.TP 12 +\fIsi_pid\fP +The process ID of the child. +.TP +\fIsi_uid\fP +The real user ID of the child. +(This field is not set on most other implementations.) +.TP +\fIsi_signo\fP +Always set to +.BR SIGCHLD . +.TP +\fIsi_status\fP +Either the exit status of the child, as given to +.BR _exit (2) +(or +.BR exit (3)), +or the signal that caused the child to terminate, stop, or continue. +The +.I si_code +field can be used to determine how to interpret this field. +.TP +\fIsi_code\fP +Set to one of: +.B CLD_EXITED +(child called +.BR _exit (2)); +.B CLD_KILLED +(child killed by signal); +.B CLD_DUMPED +(child killed by signal, and dumped core); +.B CLD_STOPPED +(child stopped by signal); +.B CLD_TRAPPED +(traced child has trapped); or +.B CLD_CONTINUED +(child continued by +.BR SIGCONT ). +.PP +If +.B WNOHANG +was specified in +.I options +and there were no children in a waitable state, then +.BR waitid () +returns 0 immediately and +the state of the +.I siginfo_t +structure pointed to by +.I infop +depends on the implementation. +To (portably) distinguish this case from that where a child was in a +waitable state, zero out the +.I si_pid +field before the call and check for a nonzero value in this field +after the call returns. +.PP +POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when +.B WNOHANG +is specified in +.I options +and there were no children in a waitable state, then +.BR waitid () +should zero out the +.I si_pid +and +.I si_signo +fields of the structure. +On Linux and other implementations that adhere to this requirement, +it is not necessary to zero out the +.I si_pid +field before calling +.BR waitid (). +However, +not all implementations follow the POSIX.1 specification on this point. +.\" POSIX.1-2001 leaves this possibility unspecified; most +.\" implementations (including Linux) zero out the structure +.\" in this case, but at least one implementation (AIX 5.1) +.\" does not -- MTK Nov 04 +.SH RETURN VALUE +.BR wait (): +on success, returns the process ID of the terminated child; +on error, \-1 is returned. +.PP +.BR waitpid (): +on success, returns the process ID of the child whose state has changed; +if +.B WNOHANG +was specified and one or more child(ren) specified by +.I pid +exist, but have not yet changed state, then 0 is returned. +On error, \-1 is returned. +.PP +.BR waitid (): +returns 0 on success or +if +.B WNOHANG +was specified and no child(ren) specified by +.I id +has yet changed state; +on error, \-1 is returned. +.\" FIXME As reported by Vegard Nossum, if infop is NULL, then waitid() +.\" returns the PID of the child. Either this is a bug, or it is intended +.\" behavior that needs to be documented. See my Jan 2009 LKML mail +.\" "waitid() return value strangeness when infop is NULL". +.PP +Each of these calls sets +.I errno +to an appropriate value in the case of an error. +.SH ERRORS +.TP +.B ECHILD +(for +.BR wait ()) +The calling process does not have any unwaited-for children. +.TP +.B ECHILD +(for +.BR waitpid () +or +.BR waitid ()) +The process specified by +.I pid +.RB ( waitpid ()) +or +.I idtype +and +.I id +.RB ( waitid ()) +does not exist or is not a child of the calling process. +(This can happen for one's own child if the action for +.B SIGCHLD +is set to +.BR SIG_IGN . +See also the \fILinux Notes\fP section about threads.) +.TP +.B EINTR +.B WNOHANG +was not set and an unblocked signal or a +.B SIGCHLD +was caught; see +.BR signal (7). +.TP +.B EINVAL +The +.I options +argument was invalid. +.SH CONFORMING TO +SVr4, 4.3BSD, POSIX.1-2001. +.SH NOTES +A child that terminates, but has not been waited for becomes a "zombie". +The kernel maintains a minimal set of information about the zombie +process (PID, termination status, resource usage information) +in order to allow the parent to later perform a wait to obtain +information about the child. +As long as a zombie is not removed from the system via a wait, +it will consume a slot in the kernel process table, and if +this table fills, it will not be possible to create further processes. +If a parent process terminates, then its "zombie" children (if any) +are adopted by +.BR init (1), +(or by the nearest "subreaper" process as defined through the use of the +.BR prctl (2) +.B PR_SET_CHILD_SUBREAPER +operation); +.BR init (1) +automatically performs a wait to remove the zombies. +.PP +POSIX.1-2001 specifies that if the disposition of +.B SIGCHLD +is set to +.B SIG_IGN +or the +.B SA_NOCLDWAIT +flag is set for +.B SIGCHLD +(see +.BR sigaction (2)), +then children that terminate do not become zombies and a call to +.BR wait () +or +.BR waitpid () +will block until all children have terminated, and then fail with +.I errno +set to +.BR ECHILD . +(The original POSIX standard left the behavior of setting +.B SIGCHLD +to +.B SIG_IGN +unspecified. +Note that even though the default disposition of +.B SIGCHLD +is "ignore", explicitly setting the disposition to +.B SIG_IGN +results in different treatment of zombie process children.) +.PP +Linux 2.6 conforms to the POSIX requirements. +However, Linux 2.4 (and earlier) does not: +if a +.BR wait () +or +.BR waitpid () +call is made while +.B SIGCHLD +is being ignored, the call behaves just as though +.B SIGCHLD +were not being ignored, that is, the call blocks until the next child +terminates and then returns the process ID and status of that child. +.SS Linux notes +In the Linux kernel, a kernel-scheduled thread is not a distinct +construct from a process. +Instead, a thread is simply a process +that is created using the Linux-unique +.BR clone (2) +system call; other routines such as the portable +.BR pthread_create (3) +call are implemented using +.BR clone (2). +Before Linux 2.4, a thread was just a special case of a process, +and as a consequence one thread could not wait on the children +of another thread, even when the latter belongs to the same thread group. +However, POSIX prescribes such functionality, and since Linux 2.4 +a thread can, and by default will, wait on children of other threads +in the same thread group. +.PP +The following Linux-specific +.I options +are for use with children created using +.BR clone (2); +they can also, since Linux 4.7, +.\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba +be used with +.BR waitid (): +.TP +.B __WCLONE +.\" since 0.99pl10 +Wait for "clone" children only. +If omitted, then wait for "non-clone" children only. +(A "clone" child is one which delivers no signal, or a signal other than +.B SIGCHLD +to its parent upon termination.) +This option is ignored if +.B __WALL +is also specified. +.TP +.BR __WALL " (since Linux 2.4)" +.\" since patch-2.3.48 +Wait for all children, regardless of +type ("clone" or "non-clone"). +.TP +.BR __WNOTHREAD " (since Linux 2.4)" +.\" since patch-2.4.0-test8 +Do not wait for children of other threads in +the same thread group. +This was the default before Linux 2.4. +.PP +Since Linux 4.7, +.\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c +.\" prevents cases where an unreapable zombie is created if +.\" /sbin/init doesn't use __WALL. +the +.B __WALL +flag is automatically implied if the child is being ptraced. +.SS C library/kernel differences +.BR wait () +is actually a library function that (in glibc) is implemented as a call to +.BR wait4 (2). +.PP +On some architectures, there is no +.BR waitpid () +system call; +.\" e.g., i386 has the system call, but not x86-64 +instead, this interface is implemented via a C library +wrapper function that calls +.BR wait4 (2). +.PP +The raw +.BR waitid () +system call takes a fifth argument, of type +.IR "struct rusage\ *" . +If this argument is non-NULL, +then it is used to return resource usage information about the child, +in the same manner as +.BR wait4 (2). +See +.BR getrusage (2) +for details. +.SH BUGS +According to POSIX.1-2008, an application calling +.BR waitid () +must ensure that +.I infop +points to a +.I siginfo_t +structure (i.e., that it is a non-null pointer). +On Linux, if +.I infop +is NULL, +.BR waitid () +succeeds, and returns the process ID of the waited-for child. +Applications should avoid relying on this inconsistent, +nonstandard, and unnecessary feature. +.SH EXAMPLE +.\" fork.2 refers to this example program. +The following program demonstrates the use of +.BR fork (2) +and +.BR waitpid (). +The program creates a child process. +If no command-line argument is supplied to the program, +then the child suspends its execution using +.BR pause (2), +to allow the user to send signals to the child. +Otherwise, if a command-line argument is supplied, +then the child exits immediately, +using the integer supplied on the command line as the exit status. +The parent process executes a loop that monitors the child using +.BR waitpid (), +and uses the W*() macros described above to analyze the wait status value. +.PP +The following shell session demonstrates the use of the program: +.PP +.in +4n +.EX +.RB "$" " ./a.out &" +Child PID is 32360 +[1] 32359 +.RB "$" " kill \-STOP 32360" +stopped by signal 19 +.RB "$" " kill \-CONT 32360" +continued +.RB "$" " kill \-TERM 32360" +killed by signal 15 +[1]+ Done ./a.out +$ +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + pid_t cpid, w; + int wstatus; + + cpid = fork(); + if (cpid == \-1) { + perror("fork"); + exit(EXIT_FAILURE); + } + + if (cpid == 0) { /* Code executed by child */ + printf("Child PID is %ld\\n", (long) getpid()); + if (argc == 1) + pause(); /* Wait for signals */ + _exit(atoi(argv[1])); + + } else { /* Code executed by parent */ + do { + w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED); + if (w == \-1) { + perror("waitpid"); + exit(EXIT_FAILURE); + } + + if (WIFEXITED(wstatus)) { + printf("exited, status=%d\\n", WEXITSTATUS(wstatus)); + } else if (WIFSIGNALED(wstatus)) { + printf("killed by signal %d\\n", WTERMSIG(wstatus)); + } else if (WIFSTOPPED(wstatus)) { + printf("stopped by signal %d\\n", WSTOPSIG(wstatus)); + } else if (WIFCONTINUED(wstatus)) { + printf("continued\\n"); + } + } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus)); + exit(EXIT_SUCCESS); + } +} +.EE +.SH SEE ALSO +.BR _exit (2), +.BR clone (2), +.BR fork (2), +.BR kill (2), +.BR ptrace (2), +.BR sigaction (2), +.BR signal (2), +.BR wait4 (2), +.BR pthread_create (3), +.BR credentials (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/wait3.2 b/man2/wait3.2 new file mode 100644 index 0000000..097794b --- /dev/null +++ b/man2/wait3.2 @@ -0,0 +1 @@ +.so man2/wait4.2 diff --git a/man2/wait4.2 b/man2/wait4.2 new file mode 100644 index 0000000..be31213 --- /dev/null +++ b/man2/wait4.2 @@ -0,0 +1,190 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (c) 2004 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 13:32:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR. +.\" Modified Tue Jul 7 12:26:42 1998 by aeb - changed return value wait3 +.\" Modified 2004-11-11, Michael Kerrisk +.\" Rewrote much of this page, and removed much duplicated text, +.\" replacing with pointers to wait.2 +.\" +.TH WAIT4 2 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +wait3, wait4 \- wait for process to change state, BSD style +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.PP +.BI "pid_t wait3(int *" "wstatus" ", int " options , +.BI " struct rusage *" rusage ); +.PP +.BI "pid_t wait4(pid_t " pid ", int *" wstatus ", int " options , +.BI " struct rusage *" rusage ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR wait3 (): + Since glibc 2.19: + _DEFAULT_SOURCE || _XOPEN_SOURCE\ >=\ 500 + Glibc 2.19 and earlier: + _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.br +.BR wait4 (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.ad +.SH DESCRIPTION +These functions are obsolete; use +.BR waitpid (2) +or +.BR waitid (2) +in new programs. +.PP +The +.BR wait3 () +and +.BR wait4 () +system calls are similar to +.BR waitpid (2), +but additionally return resource usage information about the +child in the structure pointed to by +.IR rusage . +.PP +Other than the use of the +.I rusage +argument, the following +.BR wait3 () +call: +.PP +.in +4n +.EX +wait3(wstatus, options, rusage); +.EE +.in +.PP +is equivalent to: +.PP +.in +4n +.EX +waitpid(\-1, wstatus, options); +.EE +.in +.PP +Similarly, the following +.BR wait4 () +call: +.PP +.in +4n +.EX +wait4(pid, wstatus, options, rusage); +.EE +.in +.PP +is equivalent to: +.PP +.in +4n +.EX +waitpid(pid, wstatus, options); +.EE +.in +.PP +In other words, +.BR wait3 () +waits of any child, while +.BR wait4 () +can be used to select a specific child, or children, on which to wait. +See +.BR wait (2) +for further details. +.PP +If +.I rusage +is not NULL, the +.I struct rusage +to which it points will be filled with accounting information +about the child. +See +.BR getrusage (2) +for details. +.SH RETURN VALUE +As for +.BR waitpid (2). +.SH ERRORS +As for +.BR waitpid (2). +.SH CONFORMING TO +4.3BSD. +.PP +SUSv1 included a specification of +.BR wait3 (); +SUSv2 included +.BR wait3 (), +but marked it LEGACY; +SUSv3 removed it. +.SH NOTES +Including +.I +is not required these days, but increases portability. +(Indeed, +.I +defines the +.I rusage +structure with fields of type +.I struct timeval +defined in +.IR .) +.SS C library/kernel differences +On Linux, +.BR wait3 () +is a library function implemented on top of the +.BR wait4 () +system call. +.SH SEE ALSO +.BR fork (2), +.BR getrusage (2), +.BR sigaction (2), +.BR signal (2), +.BR wait (2), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/waitid.2 b/man2/waitid.2 new file mode 100644 index 0000000..0605b35 --- /dev/null +++ b/man2/waitid.2 @@ -0,0 +1 @@ +.so man2/wait.2 diff --git a/man2/waitpid.2 b/man2/waitpid.2 new file mode 100644 index 0000000..0605b35 --- /dev/null +++ b/man2/waitpid.2 @@ -0,0 +1 @@ +.so man2/wait.2 diff --git a/man2/write.2 b/man2/write.2 new file mode 100644 index 0000000..7b655d8 --- /dev/null +++ b/man2/write.2 @@ -0,0 +1,336 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 13:35:59 1993 by Rik Faith +.\" Modified Sun Nov 28 17:19:01 1993 by Rik Faith +.\" Modified Sat Jan 13 12:58:08 1996 by Michael Haardt +.\" +.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer +.\" 2001-12-13 added remark by Zack Weinberg +.\" 2007-06-18 mtk: +.\" Added details about seekable files and file offset. +.\" Noted that write() may write less than 'count' bytes, and +.\" gave some examples of why this might occur. +.\" Noted what happens if write() is interrupted by a signal. +.\" +.TH WRITE 2 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +write \- write to a file descriptor +.SH SYNOPSIS +.B #include +.PP +.BI "ssize_t write(int " fd ", const void *" buf ", size_t " count ); +.SH DESCRIPTION +.BR write () +writes up to +.I count +bytes from the buffer starting at +.I buf +to the file referred to by the file descriptor +.IR fd . +.PP +The number of bytes written may be less than +.I count +if, for example, +there is insufficient space on the underlying physical medium, or the +.B RLIMIT_FSIZE +resource limit is encountered (see +.BR setrlimit (2)), +or the call was interrupted by a signal +handler after having written less than +.I count +bytes. +(See also +.BR pipe (7).) +.PP +For a seekable file (i.e., one to which +.BR lseek (2) +may be applied, for example, a regular file) +writing takes place at the file offset, +and the file offset is incremented by +the number of bytes actually written. +If the file was +.BR open (2)ed +with +.BR O_APPEND , +the file offset is first set to the end of the file before writing. +The adjustment of the file offset and the write operation +are performed as an atomic step. +.PP +POSIX requires that a +.BR read (2) +that can be proved to occur after a +.BR write () +has returned will return the new data. +Note that not all filesystems are POSIX conforming. +.PP +According to POSIX.1, if +.I count +is greater than +.BR SSIZE_MAX , +the result is implementation-defined; +see NOTES for the upper limit on Linux. +.SH RETURN VALUE +On success, the number of bytes written is returned (zero indicates +nothing was written). +It is not an error if this number is smaller than the number of bytes +requested; this may happen for example because the disk device was filled. +See also NOTES. +.PP +On error, \-1 is returned, and \fIerrno\fP is set +appropriately. +.PP +If \fIcount\fP is zero and +.I fd +refers to a regular file, then +.BR write () +may return a failure status if one of the errors below is detected. +If no errors are detected, or error detection is not performed, +0 will be returned without causing any other effect. +If +\fIcount\fP is zero and +.I fd +refers to a file other than a regular file, +the results are not specified. +.SH ERRORS +.TP +.B EAGAIN +The file descriptor +.I fd +refers to a file other than a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +and the write would block. +See +.BR open (2) +for further details on the +.BR O_NONBLOCK +flag. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The file descriptor +.I fd +refers to a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +and the write would block. +POSIX.1-2001 allows either error to be returned for this case, +and does not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for writing. +.TP +.B EDESTADDRREQ +.I fd +refers to a datagram socket for which a peer address has not been set using +.BR connect (2). +.TP +.B EDQUOT +The user's quota of disk blocks on the filesystem containing the file +referred to by +.I fd +has been exhausted. +.TP +.B EFAULT +.I buf +is outside your accessible address space. +.TP +.B EFBIG +An attempt was made to write a file that exceeds the implementation-defined +maximum file size or the process's file size limit, +or to write at a position past the maximum allowed offset. +.TP +.B EINTR +The call was interrupted by a signal before any data was written; see +.BR signal (7). +.TP +.B EINVAL +.I fd +is attached to an object which is unsuitable for writing; +or the file was opened with the +.B O_DIRECT +flag, and either the address specified in +.IR buf , +the value specified in +.IR count , +or the file offset is not suitably aligned. +.TP +.B EIO +A low-level I/O error occurred while modifying the inode. +This error may relate to the write-back of data written by an earlier +.BR write (2), +which may have been issued to a different file descriptor on +the same file. +Since Linux 4.13, errors from write-back come +with a promise that they +.I may +be reported by subsequent. +.BR write (2) +requests, and +.I will +be reported by a subsequent +.BR fsync (2) +(whether or not they were also reported by +.BR write (2)). +.\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750 +An alternate cause of +.B EIO +on networked filesystems is when an advisory lock had been taken out +on the file descriptor and this lock has been lost. +See the +.I "Lost locks" +section of +.BR fcntl (2) +for further details. +.TP +.B ENOSPC +The device containing the file referred to by +.I fd +has no room for the data. +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B EPIPE +.I fd +is connected to a pipe or socket whose reading end is closed. +When this happens the writing process will also receive a +.B SIGPIPE +signal. +(Thus, the write return value is seen only if the program +catches, blocks or ignores this signal.) +.PP +Other errors may occur, depending on the object connected to +.IR fd . +.SH CONFORMING TO +SVr4, 4.3BSD, POSIX.1-2001. +.\" SVr4 documents additional error +.\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. +.PP +Under SVr4 a write may be interrupted and return +.B EINTR +at any point, +not just before any data is written. +.SH NOTES +The types +.I size_t +and +.I ssize_t +are, respectively, +unsigned and signed integer data types specified by POSIX.1. +.PP +A successful return from +.BR write () +does not make any guarantee that data has been committed to disk. +On some filesystems, including NFS, it does not even guarantee +that space has successfully been reserved for the data. +In this case, +some errors might be delayed until a future +.BR write (2), +.BR fsync (2), +or even +.BR close (2). +The only way to be sure is to call +.BR fsync (2) +after you are done writing all your data. +.PP +If a +.BR write () +is interrupted by a signal handler before any bytes are written, +then the call fails with the error +.BR EINTR ; +if it is interrupted after at least one byte has been written, +the call succeeds, and returns the number of bytes written. +.PP +On Linux, +.BR write () +(and similar system calls) will transfer at most +0x7ffff000 (2,147,479,552) bytes, +returning the number of bytes actually transferred. +.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 +(This is true on both 32-bit and 64-bit systems.) +.SH BUGS +According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 +("Thread Interactions with Regular File Operations"): +.PP +.RS 4 +All of the following functions shall be atomic with respect to +each other in the effects specified in POSIX.1-2008 when they +operate on regular files or symbolic links: ... +.RE +.PP +Among the APIs subsequently listed are +.BR write () +and +.BR writev (2). +And among the effects that should be atomic across threads (and processes) +are updates of the file offset. +However, on Linux before version 3.14, +this was not the case: if two processes that share +an open file description (see +.BR open (2)) +perform a +.BR write () +(or +.BR writev (2)) +at the same time, then the I/O operations were not atomic +with respect updating the file offset, +with the result that the blocks of data output by the two processes +might (incorrectly) overlap. +This problem was fixed in Linux 3.14. +.\" http://thread.gmane.org/gmane.linux.kernel/1649458 +.\" From: Michael Kerrisk (man-pages gmail.com> +.\" Subject: Update of file offset on write() etc. is non-atomic with I/O +.\" Date: 2014-02-17 15:41:37 GMT +.\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems +.\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4 +.\" Author: Linus Torvalds +.\" Date: Mon Mar 3 09:36:58 2014 -0800 +.\" +.\" vfs: atomic f_pos accesses as per POSIX +.SH SEE ALSO +.BR close (2), +.BR fcntl (2), +.BR fsync (2), +.BR ioctl (2), +.BR lseek (2), +.BR open (2), +.BR pwrite (2), +.BR read (2), +.BR select (2), +.BR writev (2), +.BR fwrite (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man2/writev.2 b/man2/writev.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man2/writev.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man3/CIRCLEQ_ENTRY.3 b/man3/CIRCLEQ_ENTRY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/CIRCLEQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/CIRCLEQ_HEAD.3 b/man3/CIRCLEQ_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/CIRCLEQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/CIRCLEQ_INIT.3 b/man3/CIRCLEQ_INIT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/CIRCLEQ_INIT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/CIRCLEQ_INSERT_AFTER.3 b/man3/CIRCLEQ_INSERT_AFTER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/CIRCLEQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/CIRCLEQ_INSERT_BEFORE.3 b/man3/CIRCLEQ_INSERT_BEFORE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/CIRCLEQ_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/CIRCLEQ_INSERT_HEAD.3 b/man3/CIRCLEQ_INSERT_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/CIRCLEQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/CIRCLEQ_INSERT_TAIL.3 b/man3/CIRCLEQ_INSERT_TAIL.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/CIRCLEQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/CIRCLEQ_REMOVE.3 b/man3/CIRCLEQ_REMOVE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/CIRCLEQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/CMSG_ALIGN.3 b/man3/CMSG_ALIGN.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man3/CMSG_ALIGN.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CMSG_DATA.3 b/man3/CMSG_DATA.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man3/CMSG_DATA.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CMSG_FIRSTHDR.3 b/man3/CMSG_FIRSTHDR.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man3/CMSG_FIRSTHDR.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CMSG_LEN.3 b/man3/CMSG_LEN.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man3/CMSG_LEN.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CMSG_NXTHDR.3 b/man3/CMSG_NXTHDR.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man3/CMSG_NXTHDR.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CMSG_SPACE.3 b/man3/CMSG_SPACE.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man3/CMSG_SPACE.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man3/CPU_ALLOC.3 b/man3/CPU_ALLOC.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_ALLOC.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_ALLOC_SIZE.3 b/man3/CPU_ALLOC_SIZE.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_ALLOC_SIZE.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_AND.3 b/man3/CPU_AND.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_AND.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_AND_S.3 b/man3/CPU_AND_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_AND_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_CLR.3 b/man3/CPU_CLR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_CLR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_CLR_S.3 b/man3/CPU_CLR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_CLR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_COUNT.3 b/man3/CPU_COUNT.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_COUNT.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_COUNT_S.3 b/man3/CPU_COUNT_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_COUNT_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_EQUAL.3 b/man3/CPU_EQUAL.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_EQUAL.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_EQUAL_S.3 b/man3/CPU_EQUAL_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_EQUAL_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_FREE.3 b/man3/CPU_FREE.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_FREE.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_ISSET.3 b/man3/CPU_ISSET.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_ISSET.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_ISSET_S.3 b/man3/CPU_ISSET_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_ISSET_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_OR.3 b/man3/CPU_OR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_OR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_OR_S.3 b/man3/CPU_OR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_OR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_SET.3 b/man3/CPU_SET.3 new file mode 100644 index 0000000..891a48a --- /dev/null +++ b/man3/CPU_SET.3 @@ -0,0 +1,372 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" and Copyright (C) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH CPU_SET 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, +CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL, +CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE, +CPU_SET_S, CPU_CLR_S, CPU_ISSET_S, CPU_ZERO_S, +CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S, CPU_EQUAL_S \- +macros for manipulating CPU sets +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void CPU_ZERO(cpu_set_t *" set ); +.PP +.BI "void CPU_SET(int " cpu ", cpu_set_t *" set ); +.BI "void CPU_CLR(int " cpu ", cpu_set_t *" set ); +.BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set ); +.PP +.BI "int CPU_COUNT(cpu_set_t *" set ); +.PP +.BI "void CPU_AND(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_OR(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_XOR(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.PP +.BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 ); +.PP +.BI "cpu_set_t *CPU_ALLOC(int " num_cpus ); +.BI "void CPU_FREE(cpu_set_t *" set ); +.BI "size_t CPU_ALLOC_SIZE(int " num_cpus ); +.PP +.BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set ); +.PP +.BI "void CPU_SET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.BI "void CPU_CLR_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.BI "int CPU_ISSET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.PP +.BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set ); +.PP +.BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.PP +.BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \ +", cpu_set_t *" set2 ); +.fi +.SH DESCRIPTION +The +.I cpu_set_t +data structure represents a set of CPUs. +CPU sets are used by +.BR sched_setaffinity (2) +and similar interfaces. +.PP +The +.I cpu_set_t +data type is implemented as a bit mask. +However, the data structure treated as considered opaque: +all manipulation of CPU sets should be done via the macros +described in this page. +.PP +The following macros are provided to operate on the CPU set +.IR set : +.TP 17 +.BR CPU_ZERO () +Clears +.IR set , +so that it contains no CPUs. +.TP +.BR CPU_SET () +Add CPU +.I cpu +to +.IR set . +.TP +.BR CPU_CLR () +Remove CPU +.I cpu +from +.IR set . +.TP +.BR CPU_ISSET () +Test to see if CPU +.I cpu +is a member of +.IR set . +.TP +.BR CPU_COUNT () +Return the number of CPUs in +.IR set . +.PP +Where a +.I cpu +argument is specified, it should not produce side effects, +since the above macros may evaluate the argument more than once. +.PP +The first CPU on the system corresponds to a +.I cpu +value of 0, the next CPU corresponds to a +.I cpu +value of 1, and so on. +No assumptions should be made about particular CPUs being +available, or the set of CPUs being contiguous, since CPUs can +be taken offline dynamically or be otherwise absent. +The constant +.B CPU_SETSIZE +(currently 1024) specifies a value one greater than the maximum CPU +number that can be stored in +.IR cpu_set_t . +.PP +The following macros perform logical operations on CPU sets: +.TP 17 +.BR CPU_AND () +Store the intersection of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +.TP +.BR CPU_OR () +Store the union of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +.TP +.BR CPU_XOR () +Store the XOR of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +The XOR means the set of CPUs that are in either +.I srcset1 +or +.IR srcset2 , +but not both. +.TP +.BR CPU_EQUAL () +Test whether two CPU set contain exactly the same CPUs. +.SS Dynamically sized CPU sets +Because some applications may require the ability to dynamically +size CPU sets (e.g., to allocate sets larger than that +defined by the standard +.I cpu_set_t +data type), glibc nowadays provides a set of macros to support this. +.PP +The following macros are used to allocate and deallocate CPU sets: +.TP 17 +.BR CPU_ALLOC () +Allocate a CPU set large enough to hold CPUs +in the range 0 to +.IR num_cpus-1 . +.TP +.BR CPU_ALLOC_SIZE () +Return the size in bytes of the CPU set that would be needed to +hold CPUs in the range 0 to +.IR num_cpus-1 . +This macro provides the value that can be used for the +.I setsize +argument in the +.BR CPU_*_S () +macros described below. +.TP +.BR CPU_FREE () +Free a CPU set previously allocated by +.BR CPU_ALLOC (). +.PP +The macros whose names end with "_S" are the analogs of +the similarly named macros without the suffix. +These macros perform the same tasks as their analogs, +but operate on the dynamically allocated CPU set(s) whose size is +.I setsize +bytes. +.SH RETURN VALUE +.BR CPU_ISSET () +and +.BR CPU_ISSET_S () +return nonzero if +.I cpu +is in +.IR set ; +otherwise, it returns 0. +.PP +.BR CPU_COUNT () +and +.BR CPU_COUNT_S () +return the number of CPUs in +.IR set . +.PP +.BR CPU_EQUAL () +and +.BR CPU_EQUAL_S () +return nonzero if the two CPU sets are equal; otherwise they return 0. +.PP +.BR CPU_ALLOC () +returns a pointer on success, or NULL on failure. +(Errors are as for +.BR malloc (3).) +.PP +.BR CPU_ALLOC_SIZE () +returns the number of bytes required to store a +CPU set of the specified cardinality. +.PP +The other functions do not return a value. +.SH VERSIONS +The +.BR CPU_ZERO (), +.BR CPU_SET (), +.BR CPU_CLR (), +and +.BR CPU_ISSET () +macros were added in glibc 2.3.3. +.PP +.BR CPU_COUNT () +first appeared in glibc 2.6. +.PP +.BR CPU_AND (), +.BR CPU_OR (), +.BR CPU_XOR (), +.BR CPU_EQUAL (), +.BR CPU_ALLOC (), +.BR CPU_ALLOC_SIZE (), +.BR CPU_FREE (), +.BR CPU_ZERO_S (), +.BR CPU_SET_S (), +.BR CPU_CLR_S (), +.BR CPU_ISSET_S (), +.BR CPU_AND_S (), +.BR CPU_OR_S (), +.BR CPU_XOR_S (), +and +.BR CPU_EQUAL_S () +first appeared in glibc 2.7. +.SH CONFORMING TO +These interfaces are Linux-specific. +.SH NOTES +To duplicate a CPU set, use +.BR memcpy (3). +.PP +Since CPU sets are bit masks allocated in units of long words, +the actual number of CPUs in a dynamically +allocated CPU set will be rounded up to the next multiple of +.IR "sizeof(unsigned long)" . +An application should consider the contents of these extra bits +to be undefined. +.PP +Notwithstanding the similarity in the names, +note that the constant +.B CPU_SETSIZE +indicates the number of CPUs in the +.I cpu_set_t +data type (thus, it is effectively a count of the bits in the bit mask), +while the +.I setsize +argument of the +.BR CPU_*_S () +macros is a size in bytes. +.PP +The data types for arguments and return values shown +in the SYNOPSIS are hints what about is expected in each case. +However, since these interfaces are implemented as macros, +the compiler won't necessarily catch all type errors +if you violate the suggestions. +.SH BUGS +On 32-bit platforms with glibc 2.8 and earlier, +.BR CPU_ALLOC () +allocates twice as much space as is required, and +.BR CPU_ALLOC_SIZE () +returns a value twice as large as it should. +This bug should not affect the semantics of a program, +but does result in wasted memory +and less efficient operation of the macros that +operate on dynamically allocated CPU sets. +These bugs are fixed in glibc 2.9. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029 +.SH EXAMPLE +The following program demonstrates the use of some of the macros +used for dynamically allocated CPU sets. +.PP +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + cpu_set_t *cpusetp; + size_t size; + int num_cpus, cpu; + + if (argc < 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + num_cpus = atoi(argv[1]); + + cpusetp = CPU_ALLOC(num_cpus); + if (cpusetp == NULL) { + perror("CPU_ALLOC"); + exit(EXIT_FAILURE); + } + + size = CPU_ALLOC_SIZE(num_cpus); + + CPU_ZERO_S(size, cpusetp); + for (cpu = 0; cpu < num_cpus; cpu += 2) + CPU_SET_S(cpu, size, cpusetp); + + printf("CPU_COUNT() of set: %d\\n", CPU_COUNT_S(size, cpusetp)); + + CPU_FREE(cpusetp); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_setaffinity_np (3), +.BR cpuset (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/CPU_SET_S.3 b/man3/CPU_SET_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_SET_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_XOR.3 b/man3/CPU_XOR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_XOR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_XOR_S.3 b/man3/CPU_XOR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_XOR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_ZERO.3 b/man3/CPU_ZERO.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_ZERO.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/CPU_ZERO_S.3 b/man3/CPU_ZERO_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man3/CPU_ZERO_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man3/DES_FAILED.3 b/man3/DES_FAILED.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man3/DES_FAILED.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man3/FD_CLR.3 b/man3/FD_CLR.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man3/FD_CLR.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man3/FD_ISSET.3 b/man3/FD_ISSET.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man3/FD_ISSET.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man3/FD_SET.3 b/man3/FD_SET.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man3/FD_SET.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man3/FD_ZERO.3 b/man3/FD_ZERO.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man3/FD_ZERO.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man3/HUGE_VAL.3 b/man3/HUGE_VAL.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man3/HUGE_VAL.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man3/HUGE_VALF.3 b/man3/HUGE_VALF.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man3/HUGE_VALF.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man3/HUGE_VALL.3 b/man3/HUGE_VALL.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man3/HUGE_VALL.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man3/INFINITY.3 b/man3/INFINITY.3 new file mode 100644 index 0000000..72787c0 --- /dev/null +++ b/man3/INFINITY.3 @@ -0,0 +1,109 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH INFINITY 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +INFINITY, NAN, HUGE_VAL, HUGE_VALF, HUGE_VALL \- floating-point constants +.SH SYNOPSIS +.nf +.BR "#define _ISOC99_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.B INFINITY +.PP +.B NAN +.PP +.B HUGE_VAL +.B HUGE_VALF +.B HUGE_VALL +.fi +.SH DESCRIPTION +The macro +.B INFINITY +expands to a +.I float +constant representing positive infinity. +.PP +The macro +.B NAN +expands to a +.I float +constant representing a quiet NaN +(when supported). +A +.I quiet +NaN is a NaN ("not-a-number") that does not raise exceptions +when it is used in arithmetic. +The opposite is a +.I signaling +NaN. +See IEC 60559:1989. +.PP +The macros +.BR HUGE_VAL , +.BR HUGE_VALF , +.B HUGE_VALL +expand to constants of types +.IR double , +.I float +and +.IR "long double" , +respectively, +that represent a large positive value, possibly positive infinity. +.SH CONFORMING TO +C99. +.SH AVAILABILITY +On a glibc system, the macro +.B HUGE_VAL +is always available. +Availability of the +.B NAN +macro can be tested using +.BR "#ifdef NAN" , +and similarly for +.BR INFINITY , +.BR HUGE_VALF , +.BR HUGE_VALL . +They will be defined by +.I +if +.B _ISOC99_SOURCE +or +.B _GNU_SOURCE +is defined, or +.B __STDC_VERSION__ +is defined +and has a value not less than 199901L. +.SH SEE ALSO +.BR fpclassify (3), +.BR math_error (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/LIST_EMPTY.3 b/man3/LIST_EMPTY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_EMPTY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_ENTRY.3 b/man3/LIST_ENTRY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_ENTRY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_FIRST.3 b/man3/LIST_FIRST.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_FIRST.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_FOREACH.3 b/man3/LIST_FOREACH.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_FOREACH.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_HEAD.3 b/man3/LIST_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_HEAD_INITIALIZER.3 b/man3/LIST_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_INIT.3 b/man3/LIST_INIT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_INIT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_INSERT_AFTER.3 b/man3/LIST_INSERT_AFTER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_INSERT_BEFORE.3 b/man3/LIST_INSERT_BEFORE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_INSERT_HEAD.3 b/man3/LIST_INSERT_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_NEXT.3 b/man3/LIST_NEXT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_NEXT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/LIST_REMOVE.3 b/man3/LIST_REMOVE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/LIST_REMOVE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/MB_CUR_MAX.3 b/man3/MB_CUR_MAX.3 new file mode 100644 index 0000000..69ebce2 --- /dev/null +++ b/man3/MB_CUR_MAX.3 @@ -0,0 +1,52 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Modified, aeb, 990824 +.\" +.TH MB_CUR_MAX 3 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +MB_CUR_MAX \- maximum length of a multibyte character in the current locale +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.B MB_CUR_MAX +macro defines an integer expression giving +the maximum number of bytes needed to represent a single +wide character in the current locale. +This value is locale dependent and therefore not a compile-time constant. +.SH RETURN VALUE +An integer in the range [1, +.BR MB_LEN_MAX ]. +The value 1 denotes traditional 8-bit encoded characters. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR MB_LEN_MAX (3), +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcstombs (3), +.BR wctomb (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/MB_LEN_MAX.3 b/man3/MB_LEN_MAX.3 new file mode 100644 index 0000000..dd0efd3 --- /dev/null +++ b/man3/MB_LEN_MAX.3 @@ -0,0 +1,60 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Modified, aeb, 990824 +.\" +.TH MB_LEN_MAX 3 2015-07-23 "Linux" "Linux Programmer's Manual" +.SH NAME +MB_LEN_MAX \- maximum multibyte length of a character across all locales +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.B MB_LEN_MAX +macro is the maximum number of bytes needed to represent a single +wide character, in any of the supported locales. +.SH RETURN VALUE +A constant integer greater than zero. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The entities +.B MB_LEN_MAX +and +.I sizeof(wchar_t) +are totally unrelated. +In glibc, +.B MB_LEN_MAX +is typically 16 +.\" For an explanation of why the limit was raised to 16, see +.\" http://lists.gnu.org/archive/html/bug-gnulib/2015-05/msg00001.html +.\" From: Bruno Haible +.\" Subject: Re: why is MB_LEN_MAX so large (16) on glibc +.\" Date: Thu, 14 May 2015 02:30:14 +0200 +(6 in glibc versions earlier than 2.2), while +.I sizeof(wchar_t) +is 4. +.SH SEE ALSO +.BR MB_CUR_MAX (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/NAN.3 b/man3/NAN.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man3/NAN.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man3/SLIST_EMPTY.3 b/man3/SLIST_EMPTY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_EMPTY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_ENTRY.3 b/man3/SLIST_ENTRY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_ENTRY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_FIRST.3 b/man3/SLIST_FIRST.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_FIRST.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_FOREACH.3 b/man3/SLIST_FOREACH.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_FOREACH.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_HEAD.3 b/man3/SLIST_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_HEAD_INITIALIZER.3 b/man3/SLIST_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_INIT.3 b/man3/SLIST_INIT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_INIT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_INSERT_AFTER.3 b/man3/SLIST_INSERT_AFTER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_INSERT_HEAD.3 b/man3/SLIST_INSERT_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_NEXT.3 b/man3/SLIST_NEXT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_NEXT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_REMOVE.3 b/man3/SLIST_REMOVE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_REMOVE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/SLIST_REMOVE_HEAD.3 b/man3/SLIST_REMOVE_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/SLIST_REMOVE_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_CONCAT.3 b/man3/STAILQ_CONCAT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_CONCAT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_EMPTY.3 b/man3/STAILQ_EMPTY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_ENTRY.3 b/man3/STAILQ_ENTRY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_FIRST.3 b/man3/STAILQ_FIRST.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_FOREACH.3 b/man3/STAILQ_FOREACH.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_HEAD.3 b/man3/STAILQ_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_HEAD_INITIALIZER.3 b/man3/STAILQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_INIT.3 b/man3/STAILQ_INIT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_INIT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_INSERT_AFTER.3 b/man3/STAILQ_INSERT_AFTER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_INSERT_HEAD.3 b/man3/STAILQ_INSERT_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_INSERT_TAIL.3 b/man3/STAILQ_INSERT_TAIL.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_NEXT.3 b/man3/STAILQ_NEXT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_REMOVE.3 b/man3/STAILQ_REMOVE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/STAILQ_REMOVE_HEAD.3 b/man3/STAILQ_REMOVE_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/STAILQ_REMOVE_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_CONCAT.3 b/man3/TAILQ_CONCAT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_CONCAT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_EMPTY.3 b/man3/TAILQ_EMPTY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_ENTRY.3 b/man3/TAILQ_ENTRY.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_FIRST.3 b/man3/TAILQ_FIRST.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_FOREACH.3 b/man3/TAILQ_FOREACH.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_FOREACH_REVERSE.3 b/man3/TAILQ_FOREACH_REVERSE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_FOREACH_REVERSE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_HEAD.3 b/man3/TAILQ_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_HEAD_INITIALIZER.3 b/man3/TAILQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_INIT.3 b/man3/TAILQ_INIT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_INIT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_INSERT_AFTER.3 b/man3/TAILQ_INSERT_AFTER.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_INSERT_BEFORE.3 b/man3/TAILQ_INSERT_BEFORE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_INSERT_HEAD.3 b/man3/TAILQ_INSERT_HEAD.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_INSERT_TAIL.3 b/man3/TAILQ_INSERT_TAIL.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_LAST.3 b/man3/TAILQ_LAST.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_LAST.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_NEXT.3 b/man3/TAILQ_NEXT.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_PREV.3 b/man3/TAILQ_PREV.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_PREV.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_REMOVE.3 b/man3/TAILQ_REMOVE.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/TAILQ_SWAP.3 b/man3/TAILQ_SWAP.3 new file mode 100644 index 0000000..c2956c9 --- /dev/null +++ b/man3/TAILQ_SWAP.3 @@ -0,0 +1 @@ +.so man3/queue.3 diff --git a/man3/__after_morecore_hook.3 b/man3/__after_morecore_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man3/__after_morecore_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man3/__fbufsize.3 b/man3/__fbufsize.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/__fbufsize.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__flbf.3 b/man3/__flbf.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/__flbf.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fpending.3 b/man3/__fpending.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/__fpending.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fpurge.3 b/man3/__fpurge.3 new file mode 100644 index 0000000..d7cfd49 --- /dev/null +++ b/man3/__fpurge.3 @@ -0,0 +1 @@ +.so man3/fpurge.3 diff --git a/man3/__freadable.3 b/man3/__freadable.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/__freadable.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__freading.3 b/man3/__freading.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/__freading.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__free_hook.3 b/man3/__free_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man3/__free_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man3/__fsetlocking.3 b/man3/__fsetlocking.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/__fsetlocking.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fwritable.3 b/man3/__fwritable.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/__fwritable.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__fwriting.3 b/man3/__fwriting.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/__fwriting.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/__malloc_hook.3 b/man3/__malloc_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man3/__malloc_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man3/__malloc_initialize_hook.3 b/man3/__malloc_initialize_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man3/__malloc_initialize_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man3/__memalign_hook.3 b/man3/__memalign_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man3/__memalign_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man3/__ppc_get_timebase.3 b/man3/__ppc_get_timebase.3 new file mode 100644 index 0000000..edf2a2e --- /dev/null +++ b/man3/__ppc_get_timebase.3 @@ -0,0 +1,121 @@ +.\" Copyright (c) 2012, IBM Corporation. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH __PPC_GET_TIMEBASE 3 2017-09-15 "GNU C Library" "Linux Programmer's\ +Manual" +.SH NAME +__ppc_get_timebase, __ppc_get_timebase_freq \- get the current value + of the Time Base Register on Power architecture and its frequency. +.SH SYNOPSIS +.B #include +.PP +.BI "uint64_t __ppc_get_timebase(void)" +.PP +.BI "uint64_t __ppc_get_timebase_freq(void);" +.SH DESCRIPTION +.BR __ppc_get_timebase () +reads the current value of the Time Base Register and returns its +value, while +.BR __ppc_get_timebase_freq () +returns the frequency in which the Time Base Register is updated. +.PP +The Time Base Register is a 64-bit register provided by Power Architecture +processors. +It stores a monotonically incremented value that is updated at a +system-dependent frequency that may be different from the processor +frequency. +.SH RETURN VALUE +.BR __ppc_get_timebase () +returns a 64-bit unsigned integer that represents the current value of the +Time Base Register. +.PP +.BR __ppc_get_timebase_freq () +returns a 64-bit unsigned integer that represents the frequency at +which the Time Base Register is updated. +.SH VERSIONS +GNU C Library support for +.\" commit d9dc34cd569bcfe714fe8c708e58c028106e8b2e +.BR __ppc_get_timebase () +has been provided since version 2.16 and +.\" commit 8ad11b9a9cf1de82bd7771306b42070b91417c11 +.BR __ppc_get_timebase_freq () +has been available since version 2.17. +.SH CONFORMING TO +Both functions are nonstandard GNU extensions. +.SH EXAMPLE +The following program will calculate the time, in microseconds, spent +between two calls to +.BR __ppc_get_timebase (). +.SS Program source +\& +.EX +#include +#include +#include +#include +#include + +/* Maximum value of the Time Base Register: 2^60 \- 1. + Source: POWER ISA. */ +#define MAX_TB 0xFFFFFFFFFFFFFFF + +int +main(void) +{ + uint64_t tb1, tb2, diff; + + uint64_t freq = __ppc_get_timebase_freq(); + printf("Time Base frequency = %"PRIu64" Hz\\n", freq); + + tb1 = __ppc_get_timebase(); + + // Do some stuff... + + tb2 = __ppc_get_timebase(); + + if (tb2 > tb1) { + diff = tb2 \- tb1; + } else { + /* Treat Time Base Register overflow. */ + diff = (MAX_TB \- tb2) + tb1; + } + + printf("Elapsed time = %1.2f usecs\\n", + (double) diff * 1000000 / freq ); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR time (2), +.BR usleep (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/__ppc_get_timebase_freq.3 b/man3/__ppc_get_timebase_freq.3 new file mode 100644 index 0000000..8599293 --- /dev/null +++ b/man3/__ppc_get_timebase_freq.3 @@ -0,0 +1 @@ +.so man3/__ppc_get_timebase.3 diff --git a/man3/__ppc_mdoio.3 b/man3/__ppc_mdoio.3 new file mode 100644 index 0000000..c9f047f --- /dev/null +++ b/man3/__ppc_mdoio.3 @@ -0,0 +1 @@ +.so man3/__ppc_yield.3 diff --git a/man3/__ppc_mdoom.3 b/man3/__ppc_mdoom.3 new file mode 100644 index 0000000..c9f047f --- /dev/null +++ b/man3/__ppc_mdoom.3 @@ -0,0 +1 @@ +.so man3/__ppc_yield.3 diff --git a/man3/__ppc_set_ppr_low.3 b/man3/__ppc_set_ppr_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man3/__ppc_set_ppr_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man3/__ppc_set_ppr_med.3 b/man3/__ppc_set_ppr_med.3 new file mode 100644 index 0000000..29f295b --- /dev/null +++ b/man3/__ppc_set_ppr_med.3 @@ -0,0 +1,142 @@ +.\" Copyright (c) 2015, 2016 IBM Corporation. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH __PPC_SET_PPR_MED 3 2017-09-15 "GNU C Library" "Linux\ +Programmer's Manual" +.SH NAME +__ppc_set_ppr_med, __ppc_set_ppr_very_low, __ppc_set_ppr_low, __ppc_set_ppr_med_low, __ppc_set_ppr_med_high \- +Set the Program Priority Register +.SH SYNOPSIS +.B #include +.PP +.B void __ppc_set_ppr_med(void); +.br +.B void __ppc_set_ppr_very_low(void); +.br +.B void __ppc_set_ppr_low(void); +.br +.B void __ppc_set_ppr_med_low(void); +.br +.B void __ppc_set_ppr_med_high(void); +.SH DESCRIPTION +These functions provide access to the +.I Program Priority Register +(PPR) on the Power architecture. +.PP +The PPR is a 64-bit register that controls the program's priority. +By adjusting the PPR value the programmer may improve system +throughput by causing system resources to be used more +efficiently, especially in contention situations. +The available unprivileged states are covered by the following functions: +.IP * 3 +.BR __ppc_set_ppr_med () +sets the Program Priority Register value to +.IR medium +(default). +.IP * +.BR __ppc_set_ppr_very_low () +sets the Program Priority Register value to +.IR "very low" . +.IP * +.BR __ppc_set_ppr_low () +sets the Program Priority Register value to +.IR low . +.IP * +.BR __ppc_set_ppr_med_low () +sets the Program Priority Register value to +.IR "medium low" . +.PP +The privileged state +.IR "medium high" +may also be set during certain time intervals by problem-state (unprivileged) +programs, with the following function: +.IP * 3 +.BR __ppc_set_ppr_med_high () +sets the Program Priority to +.IR "medium high" . +.PP +If the program priority is medium high when the time interval expires or if an +attempt is made to set the priority to medium high when it is not allowed, the +priority is set to medium. +.SH VERSIONS +The functions +.BR __ppc_set_ppr_med (), +.BR __ppc_set_ppr_low () +and +.BR __ppc_set_ppr_med_low () +are provided by glibc since version 2.18. +The functions +.BR __ppc_set_ppr_very_low () +and +.BR __ppc_set_ppr_med_high () +first appeared in glibc in version 2.23. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw26 lb lb +l l l. +Interface Attribute Value +T{ +.BR __ppc_set_ppr_med (), +.br +.BR __ppc_set_ppr_very_low (), +.br +.BR __ppc_set_ppr_low (), +.br +.BR __ppc_set_ppr_med_low (), +.br +.BR __ppc_set_ppr_med_high () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +These functions are nonstandard GNU extensions. +.SH NOTES +The functions +.BR __ppc_set_ppr_very_low () +and +.BR __ppc_set_ppr_med_high () +will be defined by +.I +if +.B _ARCH_PWR8 +is defined. +Availability of these functions can be tested using +.BR "#ifdef _ARCH_PWR8" . +.SH SEE ALSO +.BR __ppc_yield (3) +.PP +.IR "Power ISA, Book\ II - Section\ 3.1 (Program Priority Registers)" +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/__ppc_set_ppr_med_high.3 b/man3/__ppc_set_ppr_med_high.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man3/__ppc_set_ppr_med_high.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man3/__ppc_set_ppr_med_low.3 b/man3/__ppc_set_ppr_med_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man3/__ppc_set_ppr_med_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man3/__ppc_set_ppr_very_low.3 b/man3/__ppc_set_ppr_very_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man3/__ppc_set_ppr_very_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man3/__ppc_yield.3 b/man3/__ppc_yield.3 new file mode 100644 index 0000000..6341067 --- /dev/null +++ b/man3/__ppc_yield.3 @@ -0,0 +1,93 @@ +.\" Copyright (c) 2015, IBM Corporation. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH __PPC_YIELD 3 2017-09-15 "GNU C Library" "Linux Programmer's\ +Manual" +.SH NAME +__ppc_yield, __ppc_mdoio, __ppc_mdoom \- +Hint the processor to release shared resources +.SH SYNOPSIS +.B #include +.PP +.B void __ppc_yield(void); +.br +.B void __ppc_mdoio(void); +.br +.B void __ppc_mdoom(void); +.SH DESCRIPTION +These functions +provide hints about the usage of resources that are shared with other +processors on the Power architecture. +They can be used, for example, if a program waiting on a lock intends +to divert the shared resources to be used by other processors. +.PP +.BR __ppc_yield () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released for use by +other processors. +.PP +.BR __ppc_mdoio () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released until all +outstanding storage accesses to caching-inhibited storage have been +completed. +.PP +.BR __ppc_mdoom () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released until all +outstanding storage accesses to cacheable storage for which the data +is not in the cache have been completed. +.SH VERSIONS +These functions first appeared in glibc in version 2.18. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw29 lb lb +l l l. +Interface Attribute Value +T{ +.BR __ppc_yield (), +.BR __ppc_mdoio (), +.BR __ppc_mdoom () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +These functions are nonstandard GNU extensions. +.SH SEE ALSO +.BR __ppc_set_ppr_med (3) +.PP +.IR "Power ISA, Book\ II - Section\ 3.2 (""or"" architecture)" +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/__realloc_hook.3 b/man3/__realloc_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man3/__realloc_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man3/__setfpucw.3 b/man3/__setfpucw.3 new file mode 100644 index 0000000..ad5d371 --- /dev/null +++ b/man3/__setfpucw.3 @@ -0,0 +1,73 @@ +.\" Written Sat Mar 8 10:35:08 MEZ 1997 by +.\" J. "MUFTI" Scheurich (mufti@csv.ica.uni-stuttgart.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This page is licensed under the GNU General Public License +.\" %%%LICENSE_END +.\" +.TH __SETFPUCW 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +__setfpucw \- set FPU control word on i386 architecture (obsolete) +.SH SYNOPSIS +.B #include +.PP +.BI "void __setfpucw(unsigned short " control_word ); +.SH DESCRIPTION +.BR __setfpucw () +transfers +.I control_word +to the registers of the FPU (floating-point unit) on the i386 architecture. +This was used to control floating-point precision, +rounding and floating-point exceptions. +.SH CONFORMING TO +This function was a nonstandard GNU extension. +.SH NOTES +As of glibc 2.1 this function does not exist anymore. +There are new functions from C99, with prototypes in +.IR , +to control FPU rounding modes, like +.BR fegetround (3), +.BR fesetround (3), +and the floating-point environment, like +.BR fegetenv (3), +.BR feholdexcept (3), +.BR fesetenv (3), +.BR feupdateenv (3), +and FPU exception handling, like +.BR feclearexcept (3), +.BR fegetexceptflag (3), +.BR feraiseexcept (3), +.BR fesetexceptflag (3), +and +.BR fetestexcept (3). +.PP +If direct access to the FPU control word is still needed, the +.B _FPU_GETCW +and +.B _FPU_SETCW +macros from +.I +can be used. +.SH EXAMPLE +.B __setfpucw(0x1372) +.PP +Set FPU control word on the i386 architecture to +.br + \- extended precision +.br + \- rounding to nearest +.br + \- exceptions on overflow, zero divide and NaN +.SH SEE ALSO +.BR feclearexcept (3) +.PP +.I +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/_flushlbf.3 b/man3/_flushlbf.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man3/_flushlbf.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man3/a64l.3 b/man3/a64l.3 new file mode 100644 index 0000000..f0f3c36 --- /dev/null +++ b/man3/a64l.3 @@ -0,0 +1,114 @@ +\t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Corrected, aeb, 2002-05-30 +.\" +.TH A64L 3 2016-03-15 "" "Linux Programmer's Manual" +.SH NAME +a64l, l64a \- convert between long and base-64 +.SH SYNOPSIS +.B #include +.PP +.BI "long a64l(const char *" str64 ); +.PP +.BI "char *l64a(long " value ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR a64l (), +.BR l64a (): +.br +.RS 4 +.ad l +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions provide a conversion between 32-bit long integers +and little-endian base-64 ASCII strings (of length zero to six). +If the string used as argument for +.BR a64l () +has length greater than six, only the first six bytes are used. +If the type +.I long +has more than 32 bits, then +.BR l64a () +uses only the low order 32 bits of +.IR value , +and +.BR a64l () +sign-extends its 32-bit result. +.PP +The 64 digits in the base-64 system are: +.PP +.RS +.nf +\&\(aq.\(aq represents a 0 +\&\(aq/\(aq represents a 1 +0-9 represent 2-11 +A-Z represent 12-37 +a-z represent 38-63 +.fi +.RE +.PP +So 123 = 59*64^0 + 1*64^1 = "v/". +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR l64a () +T} Thread safety MT-Unsafe race:l64a +T{ +.BR a64l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The value returned by +.BR l64a () +may be a pointer to a static buffer, possibly overwritten +by later calls. +.PP +The behavior of +.BR l64a () +is undefined when +.I value +is negative. +If +.I value +is zero, it returns an empty string. +.PP +These functions are broken in glibc before 2.2.5 +(puts most significant digit first). +.PP +This is not the encoding used by +.BR uuencode (1). +.SH SEE ALSO +.BR uuencode (1), +.\" .BR itoa (3), +.BR strtoul (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/abort.3 b/man3/abort.3 new file mode 100644 index 0000000..09e04f4 --- /dev/null +++ b/man3/abort.3 @@ -0,0 +1,114 @@ +.\" Copyright 2007 (C) Michael Kerrisk +.\" some parts Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:46:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Aug 4 10:51:53 2000 - patch from Joseph S. Myers +.\" 2007-12-15, mtk, Mostly rewritten +.\" +.TH ABORT 3 2017-11-26 "GNU" "Linux Programmer's Manual" +.SH NAME +abort \- cause abnormal process termination +.SH SYNOPSIS +.nf +.B #include +.PP +.B void abort(void); +.fi +.SH DESCRIPTION +The +.BR abort () +first unblocks the +.B SIGABRT +signal, and then raises that signal for the calling process +(as though +.BR raise (3) +was called). +This results in the abnormal termination of the process unless the +.B SIGABRT +signal is caught and the signal handler does not return +(see +.BR longjmp (3)). +.PP +If the +.B SIGABRT +signal is ignored, or caught by a handler that returns, the +.BR abort () +function will still terminate the process. +It does this by restoring the default disposition for +.B SIGABRT +and then raising the signal for a second time. +.SH RETURN VALUE +The +.BR abort () +function never returns. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR abort () +T} Thread safety MT-Safe +.TE +.SH NOTES +Up until glibc 2.26, +if the +.BR abort () +function caused process termination, +all open streams were closed and flushed (as with +.BR fclose (3)). +However, in some cases this could result in deadlocks and data corruption. +Therefore, starting with glibc 2.27, +.\" glibc commit 91e7cf982d0104f0e71770f5ae8e3faf352dea9f +.BR abort () +terminates the process without flushing streams. +POSIX.1 permits either possible behavior, saying that +.BR abort () +"may include an attempt to effect fclose() on all open streams". +.SH CONFORMING TO +SVr4, POSIX.1-2001, POSIX.1-2008, 4.3BSD, C89, C99. +.SH SEE ALSO +.BR gdb (1), +.BR sigaction (2), +.BR assert (3), +.BR exit (3), +.BR longjmp (3), +.BR raise (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/abs.3 b/man3/abs.3 new file mode 100644 index 0000000..b7f731d --- /dev/null +++ b/man3/abs.3 @@ -0,0 +1,149 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:31:13 1993, David Metcalfe +.\" Modified Sun Jun 6 23:27:50 1993, David Metcalfe +.\" Modified Sat Jul 24 21:45:37 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Dec 16 15:02:59 2000, Joseph S. Myers +.\" +.TH ABS 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +abs, labs, llabs, imaxabs \- compute the absolute value of an integer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int abs(int " j ); +.BI "long int labs(long int " j ); +.BI "long long int llabs(long long int " j ); + +.B #include +.PP +.BI "intmax_t imaxabs(intmax_t " j ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR llabs (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +The +.BR abs () +function computes the absolute value of the integer +argument \fIj\fP. +The +.BR labs (), +.BR llabs () +and +.BR imaxabs () +functions compute the absolute value of the argument \fIj\fP of the +appropriate integer type for the function. +.SH RETURN VALUE +Returns the absolute value of the integer argument, of the appropriate +integer type for the function. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR abs (), +.BR labs (), +.BR llabs (), +.BR imaxabs () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99, SVr4, 4.3BSD. +.\" POSIX.1 (1996 edition) requires only the +.\" .BR abs () +.\" function. +C89 only +includes the +.BR abs () +and +.BR labs () +functions; the functions +.BR llabs () +and +.BR imaxabs () +were added in C99. +.SH NOTES +Trying to take the absolute value of the most negative integer +is not defined. +.PP +The +.BR llabs () +function is included in glibc since version 2.0. +The +.BR imaxabs () +function is included in +glibc since version 2.1.1. +.PP +For +.BR llabs () +to be declared, it may be necessary to define +\fB_ISOC99_SOURCE\fP or \fB_ISOC9X_SOURCE\fP (depending on the +version of glibc) before including any standard headers. +.PP +By default, +GCC handles +.BR abs (), +.BR labs (), +and (since GCC 3.0) +.BR llabs () +and +.BR imaxabs () +as built-in functions. +.SH SEE ALSO +.BR cabs (3), +.BR ceil (3), +.BR fabs (3), +.BR floor (3), +.BR rint (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/acos.3 b/man3/acos.3 new file mode 100644 index 0000000..e8151f9 --- /dev/null +++ b/man3/acos.3 @@ -0,0 +1,146 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ACOS 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +acos, acosf, acosl \- arc cosine function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double acos(double " x ); +.BI "float acosf(float " x ); +.BI "long double acosl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR acosf (), +.BR acosl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions calculate the arc cosine of +.IR x ; +that is +the value whose cosine is +.IR x . +.SH RETURN VALUE +On success, these functions return the arc cosine of +.IR x +in radians; the return value is in the range [0,\ pi]. +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +1, ++0 is returned. +.PP +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.PP +If +.I x +is outside the range [\-1,\ 1], +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is outside the range [\-1,\ 1] +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR acos (), +.BR acosf (), +.BR acosl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cacos (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/acosf.3 b/man3/acosf.3 new file mode 100644 index 0000000..66104f7 --- /dev/null +++ b/man3/acosf.3 @@ -0,0 +1 @@ +.so man3/acos.3 diff --git a/man3/acosh.3 b/man3/acosh.3 new file mode 100644 index 0000000..4dd9e5d --- /dev/null +++ b/man3/acosh.3 @@ -0,0 +1,149 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ACOSH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +acosh, acoshf, acoshl \- inverse hyperbolic cosine function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double acosh(double " x ); +.BI "float acoshf(float " x ); +.BI "long double acoshl(long double " x ); +.PP +.fi +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR acosh (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR acoshf (), +.BR acoshl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions calculate the inverse hyperbolic cosine of +.IR x ; +that is the value whose hyperbolic cosine is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic cosine of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +1, +0 is returned. +.PP +If +.I x +is positive infinity, positive infinity is returned. +.PP +If +.I x +is less than 1, +a domain error occurs, +and the functions return a NaN. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is less than 1 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR acosh (), +.BR acoshf (), +.BR acoshl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR asinh (3), +.BR atanh (3), +.BR cacosh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/acoshf.3 b/man3/acoshf.3 new file mode 100644 index 0000000..f0f5c7a --- /dev/null +++ b/man3/acoshf.3 @@ -0,0 +1 @@ +.so man3/acosh.3 diff --git a/man3/acoshl.3 b/man3/acoshl.3 new file mode 100644 index 0000000..f0f5c7a --- /dev/null +++ b/man3/acoshl.3 @@ -0,0 +1 @@ +.so man3/acosh.3 diff --git a/man3/acosl.3 b/man3/acosl.3 new file mode 100644 index 0000000..66104f7 --- /dev/null +++ b/man3/acosl.3 @@ -0,0 +1 @@ +.so man3/acos.3 diff --git a/man3/addmntent.3 b/man3/addmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man3/addmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/addseverity.3 b/man3/addseverity.3 new file mode 100644 index 0000000..666e0a7 --- /dev/null +++ b/man3/addseverity.3 @@ -0,0 +1,95 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" adapted glibc info page +.\" +.\" polished a little, aeb +.TH ADDSEVERITY 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +addseverity \- introduce new severity classes +.SH SYNOPSIS +.nf +.PP +.B #include +.PP +.BI "int addseverity(int " severity ", const char *" s ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR addseverity (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +This function allows the introduction of new severity classes +which can be addressed by the +.I severity +argument of the +.BR fmtmsg (3) +function. +By default, that function knows only how to +print messages for severity 0-4 (with strings (none), HALT, +ERROR, WARNING, INFO). +This call attaches the given string +.I s +to the given value +.IR severity . +If +.I s +is NULL, the severity class with the numeric value +.I severity +is removed. +It is not possible to overwrite or remove one of the default +severity classes. +The severity value must be nonnegative. +.SH RETURN VALUE +Upon success, the value +.B MM_OK +is returned. +Upon error, the return value is +.BR MM_NOTOK . +Possible errors include: out of memory, attempt to remove a +nonexistent or default severity class. +.SH VERSIONS +.BR addseverity () +is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR addseverity () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is not specified in the X/Open Portability Guide +although the +.BR fmtmsg (3) +function is. +It is available on System V +systems. +.SH NOTES +New severity classes can also be added by setting the environment variable +.BR SEV_LEVEL . +.SH SEE ALSO +.BR fmtmsg (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/adjtime.3 b/man3/adjtime.3 new file mode 100644 index 0000000..1dd0de1 --- /dev/null +++ b/man3/adjtime.3 @@ -0,0 +1,171 @@ +.\" Copyright (c) 2006 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ADJTIME 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +adjtime \- correct the time to synchronize the system clock +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int adjtime(const struct timeval *" delta ", struct timeval *" olddelta ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR adjtime (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The +.BR adjtime () +function gradually adjusts the system clock (as returned by +.BR gettimeofday (2)). +The amount of time by which the clock is to be adjusted is specified +in the structure pointed to by +.IR delta . +This structure has the following form: +.PP +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.PP +If the adjustment in +.I delta +is positive, then the system clock is speeded up by some +small percentage (i.e., by adding a small +amount of time to the clock value in each second) until the adjustment +has been completed. +If the adjustment in +.I delta +is negative, then the clock is slowed down in a similar fashion. +.PP +If a clock adjustment from an earlier +.BR adjtime () +call is already in progress +at the time of a later +.BR adjtime () +call, and +.I delta +is not NULL for the later call, then the earlier adjustment is stopped, +but any already completed part of that adjustment is not undone. +.PP +If +.I olddelta +is not NULL, then the buffer that it points to is used to return +the amount of time remaining from any previous adjustment that +has not yet been completed. +.SH RETURN VALUE +On success, +.BR adjtime () +returns 0. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The adjustment in +.I delta +is outside the permitted range. +.TP +.B EPERM +The caller does not have sufficient privilege to adjust the time. +Under Linux, the +.B CAP_SYS_TIME +capability is required. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR adjtime () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.3BSD, System V. +.SH NOTES +The adjustment that +.BR adjtime () +makes to the clock is carried out in such a manner that the clock +is always monotonically increasing. +Using +.BR adjtime () +to adjust the time prevents the problems that can be caused for certain +applications (e.g., +.BR make (1)) +by abrupt positive or negative jumps in the system time. +.PP +.BR adjtime () +is intended to be used to make small adjustments to the system time. +Most systems impose a limit on the adjustment that can be specified in +.IR delta . +In the glibc implementation, +.I delta +must be less than or equal to (INT_MAX / 1000000 \- 2) +and greater than or equal to (INT_MIN / 1000000 + 2) +(respectively 2145 and \-2145 seconds on i386). +.SH BUGS +A longstanding bug +.\" http://sourceware.org/bugzilla/show_bug?id=2449 +.\" http://bugzilla.kernel.org/show_bug.cgi?id=6761 +meant that if +.I delta +was specified as NULL, +no valid information about the outstanding clock adjustment was returned in +.IR olddelta . +(In this circumstance, +.BR adjtime () +should return the outstanding clock adjustment, without changing it.) +This bug is fixed +.\" Thanks to the new adjtimex() ADJ_OFFSET_SS_READ flag +on systems with glibc 2.8 or later and +Linux kernel 2.6.26 or later. +.SH SEE ALSO +.BR adjtimex (2), +.BR gettimeofday (2), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aio_cancel.3 b/man3/aio_cancel.3 new file mode 100644 index 0000000..0ae688d --- /dev/null +++ b/man3/aio_cancel.3 @@ -0,0 +1,148 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH AIO_CANCEL 3 2015-03-02 "" "Linux Programmer's Manual" +.SH NAME +aio_cancel \- cancel an outstanding asynchronous I/O request +.SH SYNOPSIS +.B "#include " +.PP +.BI "int aio_cancel(int " fd ", struct aiocb *" aiocbp ); +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +The +.BR aio_cancel () +function attempts to cancel outstanding asynchronous I/O requests +for the file descriptor +.IR fd . +If +.I aiocbp +is NULL, all such requests are canceled. +Otherwise, only the request +described by the control block pointed to by +.I aiocbp +is canceled. +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.PP +Normal asynchronous notification occurs for canceled requests (see +.BR aio (7) +and +.BR sigevent (7)). +The request return status +.RB ( aio_return (3)) +is set to \-1, and the request error status +.RB ( aio_error (3)) +is set to +.BR ECANCELED . +The control block of requests that cannot be canceled is not changed. +.PP +If the request could not be canceled, +then it will terminate in the usual way after performing the I/O operation. +(In this case, +.BR aio_error (3) +will return the status +.BR EINPROGRESSS .) +.PP +If +.I aiocbp +is not NULL, and +.I fd +differs from the file descriptor with which the asynchronous operation +was initiated, unspecified results occur. +.PP +Which operations are cancelable is implementation-defined. +.\" FreeBSD: not those on raw disk devices. +.SH RETURN VALUE +The +.BR aio_cancel () +function returns one of the following values: +.TP +.B AIO_CANCELED +All requests were successfully canceled. +.TP +.B AIO_NOTCANCELED +At least one of the +requests specified was not canceled because it was in progress. +In this case, one may check the status of individual requests using +.BR aio_error (3). +.TP +.B AIO_ALLDONE +All requests had already been completed before the call. +.TP +\-1 +An error occurred. +The cause of the error can be found by inspecting +.IR errno . +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOSYS +.BR aio_cancel () +is not implemented. +.SH VERSIONS +The +.BR aio_cancel () +function is available since glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR aio_cancel () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +See +.BR aio (7). +.SH SEE ALSO +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aio_error.3 b/man3/aio_error.3 new file mode 100644 index 0000000..a4c9fda --- /dev/null +++ b/man3/aio_error.3 @@ -0,0 +1,116 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH AIO_ERROR 3 2015-03-02 "" "Linux Programmer's Manual" +.SH NAME +aio_error \- get error status of asynchronous I/O operation +.SH SYNOPSIS +.B "#include " +.PP +.BI "int aio_error(const struct aiocb *" aiocbp ); +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +The +.BR aio_error () +function returns the error status for the asynchronous I/O request +with control block pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.SH RETURN VALUE +This function returns one of the following: +.IP * 3 +.BR EINPROGRESS , +if the request has not been +completed yet. +.IP * +.BR ECANCELED , +if the request was canceled. +.IP * +0, if the request completed successfully. +.IP * +A positive error number, if the asynchronous I/O operation failed. +This is the same value that would have been stored in the +.I errno +variable in the case of a synchronous +.BR read (2), +.BR write (2), +.BR fsync (2), +or +.BR fdatasync (2) +call. +.SH ERRORS +.TP +.B EINVAL +.I aiocbp +does not point at a control block for an asynchronous I/O request +of which the return status (see +.BR aio_return (3)) +has not been retrieved yet. +.TP +.B ENOSYS +.BR aio_error () +is not implemented. +.SH VERSIONS +The +.BR aio_error () +function is available since glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR aio_error () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aio_fsync.3 b/man3/aio_fsync.3 new file mode 100644 index 0000000..5b6c342 --- /dev/null +++ b/man3/aio_fsync.3 @@ -0,0 +1,135 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH AIO_FSYNC 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +aio_fsync \- asynchronous file synchronization +.SH SYNOPSIS +.B "#include " +.PP +.BI "int aio_fsync(int " op ", struct aiocb *" aiocbp ); +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +The +.BR aio_fsync () +function does a sync on all outstanding asynchronous I/O operations +associated with +.IR aiocbp\->aio_fildes . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.PP +More precisely, if +.I op +is +.BR O_SYNC , +then all currently queued I/O operations shall be +completed as if by a call of +.BR fsync (2), +and if +.I op +is +.BR O_DSYNC , +this call is the asynchronous analog of +.BR fdatasync (2). +.PP +Note that this is a request only; it does not wait for I/O completion. +.PP +Apart from +.IR aio_fildes , +the only field in the structure pointed to by +.I aiocbp +that is used by this call is the +.I aio_sigevent +field (a +.I sigevent +structure, described in +.BR sigevent (7)), +which indicates the desired type of asynchronous notification at completion. +All other fields are ignored. +.SH RETURN VALUE +On success (the sync request was successfully queued) +this function returns 0. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for writing. +.TP +.B EINVAL +Synchronized I/O is not supported for this file, or +.I op +is not +.B O_SYNC +or +.BR O_DSYNC . +.TP +.B ENOSYS +.BR aio_fsync () +is not implemented. +.SH VERSIONS +The +.BR aio_fsync () +function is available since glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR aio_fsync () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7), +.BR sigevent (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aio_init.3 b/man3/aio_init.3 new file mode 100644 index 0000000..6991635 --- /dev/null +++ b/man3/aio_init.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright (c) 2010 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH AIO_INIT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +aio_init \- asynchronous I/O initialization +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B "#include " +.PP +.BI "void aio_init(const struct aioinit *" init ); +.fi +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +The GNU-specific +.BR aio_init () +function allows the caller to provide tuning hints to the +glibc POSIX AIO implementation. +Use of this function is optional, but to be effective, +it must be called before employing any other functions in the POSIX AIO API. +.PP +The tuning information is provided in the buffer pointed to by the argument +.IR init . +This buffer is a structure of the following form: +.PP +.in +4n +.EX +struct aioinit { + int aio_threads; /* Maximum number of threads */ + int aio_num; /* Number of expected simultaneous + requests */ + int aio_locks; /* Not used */ + int aio_usedba; /* Not used */ + int aio_debug; /* Not used */ + int aio_numusers; /* Not used */ + int aio_idle_time; /* Number of seconds before idle thread + terminates (since glibc 2.2) */ + int aio_reserved; +}; +.EE +.in +.PP +The following fields are used in the +.I aioinit +structure: +.TP 15 +.I aio_threads +This field specifies the maximum number of worker threads that +may be used by the implementation. +If the number of outstanding I/O operations exceeds this limit, +then excess operations will be queued until a worker thread becomes free. +If this field is specified with a value less than 1, the value 1 is used. +The default value is 20. +.TP +.I aio_num +This field should specify the maximum number of simultaneous I/O requests +that the caller expects to enqueue. +If a value less than 32 is specified for this field, +it is rounded up to 32. +.\" FIXME . But, if aio_num > 32, the behavior looks strange. See +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12083 +The default value is 64. +.TP +.I aio_idle_time +This field specifies the amount of time in seconds that a +worker thread should wait for further requests before terminating, +after having completed a previous request. +The default value is 1. +.SH VERSIONS +The +.BR aio_init () +function is available since glibc 2.1. +.SH CONFORMING TO +This function is a GNU extension. +.SH SEE ALSO +.BR aio (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aio_read.3 b/man3/aio_read.3 new file mode 100644 index 0000000..13ad0a3 --- /dev/null +++ b/man3/aio_read.3 @@ -0,0 +1,178 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH AIO_READ 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +aio_read \- asynchronous read +.SH SYNOPSIS +.B "#include " +.PP +.BI "int aio_read(struct aiocb *" aiocbp ); +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +The +.BR aio_read () +function queues the I/O request described by the buffer pointed to by +.IR aiocbp . +This function is the asynchronous analog of +.BR read (2). +The arguments of the call +.PP + read(fd, buf, count) +.PP +correspond (in order) to the fields +.IR aio_fildes , +.IR aio_buf , +and +.IR aio_nbytes +of the structure pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.PP +The data is read starting at the absolute position +.IR aiocbp\->aio_offset , +regardless of the file offset. +After the call, +the value of the file offset is unspecified. +.PP +The "asynchronous" means that this call returns as soon as the +request has been enqueued; the read may or may not have completed +when the call returns. +One tests for completion using +.BR aio_error (3). +The return status of a completed I/O operation can be obtained by +.BR aio_return (3). +Asynchronous notification of I/O completion can be obtained by setting +.IR aiocbp\->aio_sigevent +appropriately; see +.BR sigevent (7) +for details. +.PP +If +.B _POSIX_PRIORITIZED_IO +is defined, and this file supports it, +then the asynchronous operation is submitted at a priority equal +to that of the calling process minus +.IR aiocbp\->aio_reqprio . +.PP +The field +.I aiocbp\->aio_lio_opcode +is ignored. +.PP +No data is read from a regular file beyond its maximum offset. +.SH RETURN VALUE +On success, 0 is returned. +On error, the request is not enqueued, \-1 +is returned, and +.I errno +is set appropriately. +If an error is detected only later, it will +be reported via +.BR aio_return (3) +(returns status \-1) and +.BR aio_error (3) +(error status\(emwhatever one would have gotten in +.IR errno , +such as +.BR EBADF ). +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for reading. +.TP +.B EINVAL +One or more of +.IR aio_offset , +.IR aio_reqprio , +or +.I aio_nbytes +are invalid. +.TP +.B ENOSYS +.BR aio_read () +is not implemented. +.TP +.B EOVERFLOW +The file is a regular file, we start reading before end-of-file +and want at least one byte, but the starting position is past +the maximum offset for this file. +.SH VERSIONS +The +.BR aio_read () +function is available since glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR aio_read () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +It is a good idea to zero out the control block before use. +The control block must not be changed while the read operation +is in progress. +The buffer area being read into +.\" or the control block of the operation +must not be accessed during the operation or undefined results may occur. +The memory areas involved must remain valid. +.PP +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH EXAMPLE +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aio_return.3 b/man3/aio_return.3 new file mode 100644 index 0000000..99ce15a --- /dev/null +++ b/man3/aio_return.3 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH AIO_RETURN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +aio_return \- get return status of asynchronous I/O operation +.SH SYNOPSIS +.B "#include " +.PP +.BI "ssize_t aio_return(struct aiocb *" aiocbp ); +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +The +.BR aio_return () +function returns the final return status for the asynchronous I/O request +with control block pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.PP +This function should be called only once for any given request, after +.BR aio_error (3) +returns something other than +.BR EINPROGRESS . +.SH RETURN VALUE +If the asynchronous I/O operation has completed, this function returns +the value that would have been returned in case of a synchronous +.BR read (2), +.BR write (2), +.BR fsync (2) +or +.BR fdatasync (2), +call. +On error, \-1 is returned, and \fIerrno\fP is set appropriately. +.PP +If the asynchronous I/O operation has not yet completed, +the return value and effect of +.BR aio_return () +are undefined. +.SH ERRORS +.TP +.B EINVAL +.I aiocbp +does not point at a control block for an asynchronous I/O request +of which the return status has not been retrieved yet. +.TP +.B ENOSYS +.BR aio_return () +is not implemented. +.SH VERSIONS +The +.BR aio_return () +function is available since glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR aio_return () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aio_suspend.3 b/man3/aio_suspend.3 new file mode 100644 index 0000000..b28691c --- /dev/null +++ b/man3/aio_suspend.3 @@ -0,0 +1,164 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2010 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH AIO_SUSPEND 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +aio_suspend \- wait for asynchronous I/O operation or timeout +.SH SYNOPSIS +.nf +.PP +.B "#include " +.PP +.BI "int aio_suspend(const struct aiocb * const " aiocb_list [], +.BI " int " nitems ", const struct timespec *" timeout ); +.PP +Link with \fI\-lrt\fP. +.fi +.SH DESCRIPTION +The +.BR aio_suspend () +function suspends the calling thread until one of the following occurs: +.IP * 3 +One or more of the asynchronous I/O requests in the list +.I aiocb_list +has completed. +.IP * +A signal is delivered. +.IP * +.I timeout +is not NULL and the specified time interval has passed. +(For details of the +.I timespec +structure, see +.BR nanosleep (2).) +.PP +The +.I nitems +argument specifies the number of items in +.IR aiocb_list . +Each item in the list pointed to by +.I aiocb_list +must be either NULL (and then is ignored), +or a pointer to a control block on which I/O was initiated using +.BR aio_read (3), +.BR aio_write (3), +or +.BR lio_listio (3). +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.PP +If +.B CLOCK_MONOTONIC +is supported, this clock is used to measure +the timeout interval (see +.BR clock_gettime (3)). +.SH RETURN VALUE +If this function returns after completion of one of the I/O +requests specified in +.IR aiocb_list , +0 is returned. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The call timed out before any of the indicated operations +had completed. +.TP +.B EINTR +The call was ended by signal +(possibly the completion signal of one of the operations we were +waiting for); see +.BR signal (7). +.TP +.B ENOSYS +.BR aio_suspend () +is not implemented. +.SH VERSIONS +The +.BR aio_suspend () +function is available since glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR aio_suspend () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +One can achieve polling by using a non-NULL +.I timeout +that specifies a zero time interval. +.PP +If one or more of the asynchronous I/O operations specified in +.IR aiocb_list +has already completed at the time of the call to +.BR aio_suspend (), +then the call returns immediately. +.PP +To determine which I/O operations have completed +after a successful return from +.BR aio_suspend (), +use +.BR aio_error (3) +to scan the list of +.I aiocb +structures pointed to by +.IR aiocb_list . +.SH BUGS +The glibc implementation of +.BR aio_suspend () +is not async-signal-safe, +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172 +in violation of the requirements of POSIX.1. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aio_write.3 b/man3/aio_write.3 new file mode 100644 index 0000000..e581282 --- /dev/null +++ b/man3/aio_write.3 @@ -0,0 +1,180 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH AIO_WRITE 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +aio_write \- asynchronous write +.SH SYNOPSIS +.B "#include " +.PP +.BI "int aio_write(struct aiocb *" aiocbp ); +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +The +.BR aio_write () +function queues the I/O request described by the buffer pointed to by +.IR aiocbp . +This function is the asynchronous analog of +.BR write (2). +The arguments of the call +.PP + write(fd, buf, count) +.PP +correspond (in order) to the fields +.IR aio_fildes , +.IR aio_buf , +and +.IR aio_nbytes +of the structure pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.PP +If +.B O_APPEND +is not set, the data is written starting at the +absolute position +.IR aiocbp\->aio_offset , +regardless of the file offset. +If +.B O_APPEND +is set, data is written at the end of the file in the same order as +.BR aio_write () +calls are made. +After the call, the value of the file offset is unspecified. +.PP +The "asynchronous" means that this call returns as soon as the +request has been enqueued; the write may or may not have completed +when the call returns. +One tests for completion using +.BR aio_error (3). +The return status of a completed I/O operation can be obtained +.BR aio_return (3). +Asynchronous notification of I/O completion can be obtained by setting +.IR aiocbp\->aio_sigevent +appropriately; see +.BR sigevent (7) +for details. +.PP +If +.B _POSIX_PRIORITIZED_IO +is defined, and this file supports it, +then the asynchronous operation is submitted at a priority equal +to that of the calling process minus +.IR aiocbp\->aio_reqprio . +.PP +The field +.I aiocbp\->aio_lio_opcode +is ignored. +.PP +No data is written to a regular file beyond its maximum offset. +.SH RETURN VALUE +On success, 0 is returned. +On error, the request is not enqueued, \-1 +is returned, and +.I errno +is set appropriately. +If an error is detected only later, it will +be reported via +.BR aio_return (3) +(returns status \-1) and +.BR aio_error (3) +(error status\(emwhatever one would have gotten in +.IR errno , +such as +.BR EBADF ). +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for writing. +.TP +.B EFBIG +The file is a regular file, we want to write at least one byte, +but the starting position is at or beyond the maximum offset for this file. +.TP +.B EINVAL +One or more of +.IR aio_offset , +.IR aio_reqprio , +.I aio_nbytes +are invalid. +.TP +.B ENOSYS +.BR aio_write () +is not implemented. +.SH VERSIONS +The +.BR aio_write () +function is available since glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR aio_write () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +It is a good idea to zero out the control block before use. +The control block must not be changed while the write operation +is in progress. +The buffer area being written out +.\" or the control block of the operation +must not be accessed during the operation or undefined results may occur. +The memory areas involved must remain valid. +.PP +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR lio_listio (3), +.BR aio (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/aligned_alloc.3 b/man3/aligned_alloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man3/aligned_alloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man3/alloca.3 b/man3/alloca.3 new file mode 100644 index 0000000..694a64d --- /dev/null +++ b/man3/alloca.3 @@ -0,0 +1,179 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)alloca.3 5.1 (Berkeley) 5/2/91 +.\" +.\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith +.\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond +.\" Modified 2002-07-17, aeb +.\" 2008-01-24, mtk: +.\" Various rewrites and additions (notes on longjmp() and SIGSEGV). +.\" Weaken warning against use of alloca() (as per Debian bug 461100). +.\" +.TH ALLOCA 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +alloca \- allocate memory that is automatically freed +.SH SYNOPSIS +.B #include +.PP +.BI "void *alloca(size_t " size ); +.SH DESCRIPTION +The +.BR alloca () +function allocates +.I size +bytes of space in the stack frame of the caller. +This temporary space is +automatically freed when the function that called +.BR alloca () +returns to its caller. +.SH RETURN VALUE +The +.BR alloca () +function returns a pointer to the beginning of the allocated space. +If the allocation causes stack overflow, program behavior is undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR alloca () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is not in POSIX.1. +.PP +There is evidence that the +.BR alloca () +function appeared in 32V, PWB, PWB.2, 3BSD, and 4BSD. +There is a man page for it in 4.3BSD. +Linux uses the GNU version. +.SH NOTES +The +.BR alloca () +function is machine- and compiler-dependent. +For certain applications, +its use can improve efficiency compared to the use of +.BR malloc (3) +plus +.BR free (3). +In certain cases, +it can also simplify memory deallocation in applications that use +.BR longjmp (3) +or +.BR siglongjmp (3). +Otherwise, its use is discouraged. +.PP +Because the space allocated by +.BR alloca () +is allocated within the stack frame, +that space is automatically freed if the function return +is jumped over by a call to +.BR longjmp (3) +or +.BR siglongjmp (3). +.PP +Do not attempt to +.BR free (3) +space allocated by +.BR alloca ()! +.SS Notes on the GNU version +Normally, +.BR gcc (1) +translates calls to +.BR alloca () +with inlined code. +This is not done when either the +.IR "\-ansi" , +.IR "\-std=c89" , +.IR "\-std=c99" , +or the +.IR "\-std=c11" +option is given +.BR and +the header +.I +is not included. +Otherwise, (without an \-ansi or \-std=c* option) the glibc version of +.I +includes +.I +and that contains the lines: +.PP +.in +4n +.EX +#ifdef __GNUC__ +#define alloca(size) __builtin_alloca (size) +#endif +.EE +.in +.PP +with messy consequences if one has a private version of this function. +.PP +The fact that the code is inlined means that it is impossible +to take the address of this function, or to change its behavior +by linking with a different library. +.PP +The inlined code often consists of a single instruction adjusting +the stack pointer, and does not check for stack overflow. +Thus, there is no NULL error return. +.SH BUGS +There is no error indication if the stack frame cannot be extended. +(However, after a failed allocation, the program is likely to receive a +.B SIGSEGV +signal if it attempts to access the unallocated space.) +.PP +On many systems +.BR alloca () +cannot be used inside the list of arguments of a function call, because +the stack space reserved by +.BR alloca () +would appear on the stack in the middle of the space for the +function arguments. +.SH SEE ALSO +.BR brk (2), +.BR longjmp (3), +.BR malloc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/alphasort.3 b/man3/alphasort.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man3/alphasort.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man3/argz.3 b/man3/argz.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_add.3 b/man3/argz_add.3 new file mode 100644 index 0000000..ad94bca --- /dev/null +++ b/man3/argz_add.3 @@ -0,0 +1,243 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH ARGZ_ADD 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +argz_add, argz_add_sep, argz_append, argz_count, argz_create, +argz_create_sep, argz_delete, argz_extract, argz_insert, +argz_next, argz_replace, argz_stringify \- functions to handle an argz list +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "error_t argz_add(char **" argz ", size_t *" argz_len \ +", const char *" str ); +.PP +.BI "error_t argz_add_sep(char **" argz ", size_t *" argz_len , +.BI " const char *" str ", int " delim ); +.PP +.BI "error_t argz_append(char **" argz ", size_t *" argz_len , +.BI " const char *" buf ", size_t " buf_len ); +.PP +.BI "size_t argz_count(const char *" argz ", size_t " argz_len ); +.PP +.BI "error_t argz_create(char * const " argv "[], char **" argz , +.BI " size_t *" argz_len ); +.PP +.BI "error_t argz_create_sep(const char *" str ", int " sep ", char **" argz , +.BI " size_t *" argz_len ); +.PP +.BI "void argz_delete(char **" argz ", size_t *" argz_len ", char *" entry ); +.PP +.BI "void argz_extract(const char *" argz ", size_t " argz_len ", char **" argv ); +.PP +.BI "error_t argz_insert(char **" argz ", size_t *" argz_len ", char *" before , +.BI " const char *" entry ); +.PP +.BI "char *argz_next(const char *" argz ", size_t " argz_len ", const char *" entry ); +.PP +.BI "error_t argz_replace(char **" argz ", size_t *" argz_len \ +", const char *" str , +.BI " const char *" with ", unsigned int *" replace_count ); +.PP +.BI "void argz_stringify(char *" argz ", size_t " len ", int " sep ); +.fi +.SH DESCRIPTION +These functions are glibc-specific. +.PP +An argz vector is a pointer to a character buffer together with a length. +The intended interpretation of the character buffer is an array +of strings, where the strings are separated by null bytes (\(aq\\0\(aq). +If the length is nonzero, the last byte of the buffer must be a null byte. +.PP +These functions are for handling argz vectors. +The pair (NULL,0) is an argz vector, and, conversely, +argz vectors of length 0 must have null pointer. +Allocation of nonempty argz vectors is done using +.BR malloc (3), +so that +.BR free (3) +can be used to dispose of them again. +.PP +.BR argz_add () +adds the string +.I str +at the end of the array +.IR *argz , +and updates +.I *argz +and +.IR *argz_len . +.PP +.BR argz_add_sep () +is similar, but splits the string +.I str +into substrings separated by the delimiter +.IR delim . +For example, one might use this on a UNIX search path with +delimiter \(aq:\(aq. +.PP +.BR argz_append () +appends the argz vector +.RI ( buf ,\ buf_len ) +after +.RI ( *argz ,\ *argz_len ) +and updates +.IR *argz +and +.IR *argz_len . +(Thus, +.I *argz_len +will be increased by +.IR buf_len .) +.PP +.BR argz_count () +counts the number of strings, that is, +the number of null bytes (\(aq\\0\(aq), in +.RI ( argz ,\ argz_len ). +.PP +.BR argz_create () +converts a UNIX-style argument vector +.IR argv , +terminated by +.IR "(char\ *)\ 0" , +into an argz vector +.RI ( *argz ,\ *argz_len ). +.PP +.BR argz_create_sep () +converts the null-terminated string +.I str +into an argz vector +.RI ( *argz ,\ *argz_len ) +by breaking it up at every occurrence of the separator +.IR sep . +.PP +.BR argz_delete () +removes the substring pointed to by +.I entry +from the argz vector +.RI ( *argz ,\ *argz_len ) +and updates +.I *argz +and +.IR *argz_len . +.PP +.BR argz_extract () +is the opposite of +.BR argz_create (). +It takes the argz vector +.RI ( argz ,\ argz_len ) +and fills the array starting at +.I argv +with pointers to the substrings, and a final NULL, +making a UNIX-style argv vector. +The array +.I argv +must have room for +.IR argz_count ( argz ", " argz_len ") + 1" +pointers. +.PP +.BR argz_insert () +is the opposite of +.BR argz_delete (). +It inserts the argument +.I entry +at position +.I before +into the argz vector +.RI ( *argz ,\ *argz_len ) +and updates +.I *argz +and +.IR *argz_len . +If +.I before +is NULL, then +.I entry +will inserted at the end. +.PP +.BR argz_next () +is a function to step trough the argz vector. +If +.I entry +is NULL, the first entry is returned. +Otherwise, the entry +following is returned. +It returns NULL if there is no following entry. +.PP +.BR argz_replace () +replaces each occurrence of +.I str +with +.IR with , +reallocating argz as necessary. +If +.I replace_count +is non-NULL, +.I *replace_count +will be incremented by the number of replacements. +.PP +.BR argz_stringify () +is the opposite of +.BR argz_create_sep (). +It transforms the argz vector into a normal string by replacing +all null bytes (\(aq\\0\(aq) except the last by +.IR sep . +.SH RETURN VALUE +All argz functions that do memory allocation have a return type of +.IR error_t , +and return 0 for success, and +.B ENOMEM +if an allocation error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw33 lb lb +l l l. +Interface Attribute Value +T{ +.BR argz_add (), +.BR argz_add_sep (), +.br +.BR argz_append (), +.BR argz_count (), +.br +.BR argz_create (), +.BR argz_create_sep (), +.br +.BR argz_delete (), +.BR argz_extract (), +.br +.BR argz_insert (), +.BR argz_next (), +.br +.BR argz_replace (), +.BR argz_stringify () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +These functions are a GNU extension. +Handle with care. +.SH BUGS +Argz vectors without a terminating null byte may lead to +Segmentation Faults. +.SH SEE ALSO +.BR envz_add (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/argz_add_sep.3 b/man3/argz_add_sep.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_add_sep.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_append.3 b/man3/argz_append.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_append.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_count.3 b/man3/argz_count.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_count.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_create.3 b/man3/argz_create.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_create.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_create_sep.3 b/man3/argz_create_sep.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_create_sep.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_delete.3 b/man3/argz_delete.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_delete.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_extract.3 b/man3/argz_extract.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_extract.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_insert.3 b/man3/argz_insert.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_insert.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_next.3 b/man3/argz_next.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_next.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_replace.3 b/man3/argz_replace.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_replace.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/argz_stringify.3 b/man3/argz_stringify.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man3/argz_stringify.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man3/asctime.3 b/man3/asctime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man3/asctime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/asctime_r.3 b/man3/asctime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man3/asctime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/asin.3 b/man3/asin.3 new file mode 100644 index 0000000..aa8864b --- /dev/null +++ b/man3/asin.3 @@ -0,0 +1,142 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ASIN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +asin, asinf, asinl \- arc sine function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double asin(double " x ); +.BI "float asinf(float " x ); +.BI "long double asinl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR asinf (), +.BR asinl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions calculate the principal value of the arc sine of +.IR x ; +that is the value whose sine is +.IR x . +.SH RETURN VALUE +On success, these functions return the principal value of the arc sine of +.IR x +in radians; the return value is in the range [\-pi/2,\ pi/2]. +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.PP +If +.I x +is outside the range [\-1,\ 1], +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is outside the range [\-1,\ 1] +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR asin (), +.BR asinf (), +.BR asinl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR atan (3), +.BR atan2 (3), +.BR casin (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/asinf.3 b/man3/asinf.3 new file mode 100644 index 0000000..4c88df0 --- /dev/null +++ b/man3/asinf.3 @@ -0,0 +1 @@ +.so man3/asin.3 diff --git a/man3/asinh.3 b/man3/asinh.3 new file mode 100644 index 0000000..ffc07f0 --- /dev/null +++ b/man3/asinh.3 @@ -0,0 +1,134 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ASINH 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +asinh, asinhf, asinhl \- inverse hyperbolic sine function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double asinh(double " x ); +.BI "float asinhf(float " x ); +.BI "long double asinhl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR asinh (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.PP +.BR asinhf (), +.BR asinhl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions calculate the inverse hyperbolic sine of +.IR x ; +that is the value whose hyperbolic sine is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic sine of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.PP +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR asinh (), +.BR asinhf (), +.BR asinhl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR acosh (3), +.BR atanh (3), +.BR casinh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/asinhf.3 b/man3/asinhf.3 new file mode 100644 index 0000000..93c5034 --- /dev/null +++ b/man3/asinhf.3 @@ -0,0 +1 @@ +.so man3/asinh.3 diff --git a/man3/asinhl.3 b/man3/asinhl.3 new file mode 100644 index 0000000..93c5034 --- /dev/null +++ b/man3/asinhl.3 @@ -0,0 +1 @@ +.so man3/asinh.3 diff --git a/man3/asinl.3 b/man3/asinl.3 new file mode 100644 index 0000000..4c88df0 --- /dev/null +++ b/man3/asinl.3 @@ -0,0 +1 @@ +.so man3/asin.3 diff --git a/man3/asprintf.3 b/man3/asprintf.3 new file mode 100644 index 0000000..da391db --- /dev/null +++ b/man3/asprintf.3 @@ -0,0 +1,93 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Text fragments inspired by Martin Schulze . +.\" +.TH ASPRINTF 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +asprintf, vasprintf \- print to allocated string +.SH SYNOPSIS +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.PP +.BI "int asprintf(char **" strp ", const char *" fmt ", ...);" +.PP +.BI "int vasprintf(char **" strp ", const char *" fmt ", va_list " ap ); +.SH DESCRIPTION +The functions +.BR asprintf () +and +.BR vasprintf () +are analogs of +.BR sprintf (3) +and +.BR vsprintf (3), +except that they allocate a string large enough to hold the output +including the terminating null byte (\(aq\\0\(aq), +and return a pointer to it via the first argument. +This pointer should be passed to +.BR free (3) +to release the allocated storage when it is no longer needed. +.SH RETURN VALUE +When successful, these functions return the number of bytes printed, +just like +.BR sprintf (3). +If memory allocation wasn't possible, or some other error occurs, +these functions will return \-1, and the contents of +.I strp +are undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR asprintf (), +.BR vasprintf () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +These functions are GNU extensions, not in C or POSIX. +They are also available under *BSD. +The FreeBSD implementation sets +.I strp +to NULL on error. +.SH SEE ALSO +.BR free (3), +.BR malloc (3), +.BR printf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/assert.3 b/man3/assert.3 new file mode 100644 index 0000000..3c6e79a --- /dev/null +++ b/man3/assert.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith +.\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond +.\" Modified Thu Jun 2 23:44:11 2016 by Nikos Mavrogiannopoulos +.TH ASSERT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +assert \- abort the program if assertion is false +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void assert(scalar " expression ); +.fi +.SH DESCRIPTION +This macro can help programmers find bugs in their programs, +or handle exceptional cases +via a crash that will produce limited debugging output. +.PP +If +.I expression +is false (i.e., compares equal to zero), +.BR assert () +prints an error message to standard error +and terminates the program by calling +.BR abort (3). +The error message includes the name of the file and function containing the +.BR assert () +call, the source code line number of the call, and the text of the argument; +something like: +.PP + prog: some_file.c:16: some_func: Assertion `val == 0' failed. +.PP +If the macro +.B NDEBUG +is defined at the moment +.I +was last included, the macro +.BR assert () +generates no code, and hence does nothing at all. +It is not recommended to define +.B NDEBUG +if using +.BR assert () +to detect error conditions since the software +may behave non-deterministically. +.SH RETURN VALUE +No value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR assert () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +In C89, +.I expression +is required to be of type +.I int +and undefined behavior results if it is not, but in C99 +it may have any scalar type. +.\" See Defect Report 107 for more details. +.SH BUGS +.BR assert () +is implemented as a macro; if the expression tested has side-effects, +program behavior will be different depending on whether +.B NDEBUG +is defined. +This may create Heisenbugs which go away when debugging +is turned on. +.SH SEE ALSO +.BR abort (3), +.BR assert_perror (3), +.BR exit (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/assert_perror.3 b/man3/assert_perror.3 new file mode 100644 index 0000000..f9d4a90 --- /dev/null +++ b/man3/assert_perror.3 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH ASSERT_PERROR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +assert_perror \- test errnum and abort +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void assert_perror(int " errnum ); +.fi +.SH DESCRIPTION +If the macro +.B NDEBUG +was defined at the moment +.I +was last included, the macro +.BR assert_perror () +generates no code, and hence does nothing at all. +Otherwise, the macro +.BR assert_perror () +prints an error message to standard error and terminates the program +by calling +.BR abort (3) +if +.I errnum +is nonzero. +The message contains the filename, function name and +line number of the macro call, and the output of +.IR strerror(errnum) . +.SH RETURN VALUE +No value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR assert_perror () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +This is a GNU extension. +.SH BUGS +The purpose of the assert macros is to help programmers find bugs in +their programs, things that cannot happen unless there was a coding mistake. +However, with system or library calls the situation is rather different, +and error returns can happen, and will happen, and should be tested for. +Not by an assert, where the test goes away when +.B NDEBUG +is defined, +but by proper error handling code. +Never use this macro. +.SH SEE ALSO +.BR abort (3), +.BR assert (3), +.BR exit (3), +.BR strerror (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/atan.3 b/man3/atan.3 new file mode 100644 index 0000000..c394af2 --- /dev/null +++ b/man3/atan.3 @@ -0,0 +1,128 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ATAN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +atan, atanf, atanl \- arc tangent function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double atan(double " x ); +.BI "float atanf(float " x ); +.BI "long double atanl( long double " x ); +.PP +.fi +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR atanf (), +.BR atanl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions calculate the principal value of the arc tangent of +.IR x ; +that is the value whose tangent is +.IR x . +.SH RETURN VALUE +On success, these functions return the principal value of the arc tangent of +.IR x +in radians; the return value is in the range [\-pi/2,\ pi/2]. +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.PP +If +.I x +is positive infinity (negative infinity), +pi/2 (\-pi/2) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR atan (), +.BR atanf (), +.BR atanl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan2 (3), +.BR carg (3), +.BR catan (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/atan2.3 b/man3/atan2.3 new file mode 100644 index 0000000..691a21c --- /dev/null +++ b/man3/atan2.3 @@ -0,0 +1,199 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ATAN2 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +atan2, atan2f, atan2l \- arc tangent function of two variables +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double atan2(double " y ", double " x ); +.BI "float atan2f(float " y ", float " x ); +.BI "long double atan2l(long double " y ", long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR atan2f (), +.BR atan2l (): +.RS +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions calculate the principal value of the arc tangent of +.IR y/x , +using the signs of the two arguments to determine +the quadrant of the result. +.SH RETURN VALUE +On success, these functions return the principal value of the arc tangent of +.IR y/x +in radians; the return value is in the range [\-pi,\ pi]. +.PP +If +.I y +is +0 (\-0) and +.I x +is less than 0, +pi (\-pi) is returned. +.PP +If +.I y +is +0 (\-0) and +.I x +is greater than 0, +0 (\-0) is returned. +.PP +If +.I y +is less than 0 and +.I x +is +0 or \-0, \-pi/2 is returned. +.PP +If +.I y +is greater than 0 and +.I x +is +0 or \-0, pi/2 is returned. +.PP +.\" POSIX.1 says: +.\" If +.\" .I x +.\" is 0, a pole error shall not occur. +.\" +If either +.I x +or +.I y +is NaN, a NaN is returned. +.PP +.\" POSIX.1 says: +.\" If the result underflows, a range error may occur and +.\" .I y/x +.\" should be returned. +.\" +If +.I y +is +0 (\-0) and +.I x +is \-0, +pi (\-pi) is returned. +.PP +If +.I y +is +0 (\-0) and +.I x +is +0, +0 (\-0) is returned. +.PP +If +.I y +is a finite value greater (less) than 0, and +.I x +is negative infinity, +pi (\-pi) is returned. +.PP +If +.I y +is a finite value greater (less) than 0, and +.I x +is positive infinity, +0 (\-0) is returned. +.PP +If +.I y +is positive infinity (negative infinity), and +.I x +is finite, +pi/2 (\-pi/2) is returned. +.PP +If +.I y +is positive infinity (negative infinity) and +.I x +is negative infinity, +3*pi/4 (\-3*pi/4) is returned. +.PP +If +.I y +is positive infinity (negative infinity) and +.I x +is positive infinity, +pi/4 (\-pi/4) is returned. +.\" +.\" POSIX.1 says: +.\" If both arguments are 0, a domain error shall not occur. +.SH ERRORS +No errors occur. +.\" POSIX.1 documents an optional underflow error +.\" glibc 2.8 does not do this. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR atan2 (), +.BR atan2f (), +.BR atan2l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR carg (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/atan2f.3 b/man3/atan2f.3 new file mode 100644 index 0000000..e445b12 --- /dev/null +++ b/man3/atan2f.3 @@ -0,0 +1 @@ +.so man3/atan2.3 diff --git a/man3/atan2l.3 b/man3/atan2l.3 new file mode 100644 index 0000000..e445b12 --- /dev/null +++ b/man3/atan2l.3 @@ -0,0 +1 @@ +.so man3/atan2.3 diff --git a/man3/atanf.3 b/man3/atanf.3 new file mode 100644 index 0000000..784b32a --- /dev/null +++ b/man3/atanf.3 @@ -0,0 +1 @@ +.so man3/atan.3 diff --git a/man3/atanh.3 b/man3/atanh.3 new file mode 100644 index 0000000..472c3dd --- /dev/null +++ b/man3/atanh.3 @@ -0,0 +1,179 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ATANH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +atanh, atanhf, atanhl \- inverse hyperbolic tangent function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double atanh(double " x ); +.BI "float atanhf(float " x ); +.BI "long double atanhl(long double " x ); +.PP +.fi +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR atanh (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.PP +.BR atanhf (), +.BR atanhl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions calculate the inverse hyperbolic tangent of +.IR x ; +that is the value whose hyperbolic tangent is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic tangent of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.PP +If +.I x +is +1 or \-1, +a pole error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.PP +If the absolute value of +.I x +is greater than 1, +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP less than \-1 or greater than +1 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is +1 or \-1 +.I errno +is set to +.BR ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR atanh (), +.BR atanhf (), +.BR atanhl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +In glibc 2.9 and earlier, +.\" Bug: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6759 +.\" This can be seen in sysdeps/ieee754/k_standard.c +when a pole error occurs, +.I errno +as set to +.BR EDOM +instead of the POSIX-mandated +.BR ERANGE . +Since version 2.10, glibc does the right thing. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR catanh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/atanhf.3 b/man3/atanhf.3 new file mode 100644 index 0000000..225a339 --- /dev/null +++ b/man3/atanhf.3 @@ -0,0 +1 @@ +.so man3/atanh.3 diff --git a/man3/atanhl.3 b/man3/atanhl.3 new file mode 100644 index 0000000..225a339 --- /dev/null +++ b/man3/atanhl.3 @@ -0,0 +1 @@ +.so man3/atanh.3 diff --git a/man3/atanl.3 b/man3/atanl.3 new file mode 100644 index 0000000..784b32a --- /dev/null +++ b/man3/atanl.3 @@ -0,0 +1 @@ +.so man3/atan.3 diff --git a/man3/atexit.3 b/man3/atexit.3 new file mode 100644 index 0000000..d18a280 --- /dev/null +++ b/man3/atexit.3 @@ -0,0 +1,189 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-10-25, Walter Harms +.\" +.TH ATEXIT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +atexit \- register a function to be called at normal process termination +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int atexit(void (*" function )(void)); +.fi +.SH DESCRIPTION +The +.BR atexit () +function registers the given +.I function +to be +called at normal process termination, either via +.BR exit (3) +or via return from the program's +.IR main (). +Functions so registered are called in +the reverse order of their registration; no arguments are passed. +.PP +The same function may be registered multiple times: +it is called once for each registration. +.PP +POSIX.1 requires that an implementation allow at least +.\" POSIX.1-2001, POSIX.1-2008 +.B ATEXIT_MAX +(32) such functions to be registered. +The actual limit supported by an implementation can be obtained using +.BR sysconf (3). +.PP +When a child process is created via +.BR fork (2), +it inherits copies of its parent's registrations. +Upon a successful call to one of the +.BR exec (3) +functions, +all registrations are removed. +.SH RETURN VALUE +The +.BR atexit () +function returns the value 0 if successful; otherwise +it returns a nonzero value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR atexit () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +Functions registered using +.BR atexit () +(and +.BR on_exit (3)) +are not called if a process terminates abnormally because +of the delivery of a signal. +.PP +If one of the functions registered functions calls +.BR _exit (2), +then any remaining functions are not invoked, +and the other process termination steps performed by +.BR exit (3) +are not performed. +.PP +POSIX.1 says that the result of calling +.\" POSIX.1-2001, POSIX.1-2008 +.BR exit (3) +more than once (i.e., calling +.BR exit (3) +within a function registered using +.BR atexit ()) +is undefined. +On some systems (but not Linux), this can result in an infinite recursion; +.\" This can happen on OpenBSD 4.2 for example, and is documented +.\" as occurring on FreeBSD as well. +.\" Glibc does "the Right Thing" -- invocation of the remaining +.\" exit handlers carries on as normal. +portable programs should not invoke +.BR exit (3) +inside a function registered using +.BR atexit (). +.PP +The +.BR atexit () +and +.BR on_exit (3) +functions register functions on the same list: +at normal process termination, +the registered functions are invoked in reverse order +of their registration by these two functions. +.PP +According to POSIX.1, the result is undefined if +.BR longjmp (3) +is used to terminate execution of one of the functions registered using +.BR atexit (). +.\" In glibc, things seem to be handled okay +.SS Linux notes +Since glibc 2.2.3, +.BR atexit () +(and +.BR on_exit (3)) +can be used within a shared library to establish functions +that are called when the shared library is unloaded. +.SH EXAMPLE +.EX +#include +#include +#include + +void +bye(void) +{ + printf("That was all, folks\en"); +} + +int +main(void) +{ + long a; + int i; + + a = sysconf(_SC_ATEXIT_MAX); + printf("ATEXIT_MAX = %ld\en", a); + + i = atexit(bye); + if (i != 0) { + fprintf(stderr, "cannot set exit function\en"); + exit(EXIT_FAILURE); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR _exit (2), +.BR dlopen (3), +.BR exit (3), +.BR on_exit (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/atof.3 b/man3/atof.3 new file mode 100644 index 0000000..997aac7 --- /dev/null +++ b/man3/atof.3 @@ -0,0 +1,88 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:39:24 1993, David Metcalfe +.\" Modified Sat Jul 24 21:39:22 1993, Rik Faith (faith@cs.unc.edu) +.TH ATOF 3 2016-12-12 "GNU" "Linux Programmer's Manual" +.SH NAME +atof \- convert a string to a double +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double atof(const char *" nptr ); +.fi +.SH DESCRIPTION +The +.BR atof () +function converts the initial portion of the string +pointed to by \fInptr\fP to +.IR double . +The behavior is the same as +.PP +.in +4n +.EX +strtod(nptr, NULL); +.EE +.in +.PP +except that +.BR atof () +does not detect errors. +.SH RETURN VALUE +The converted value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR atof () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR atoi (3), +.BR atol (3), +.BR strfromd (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/atoi.3 b/man3/atoi.3 new file mode 100644 index 0000000..8d55e5a --- /dev/null +++ b/man3/atoi.3 @@ -0,0 +1,131 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:39:41 1993, David Metcalfe +.\" Modified Sat Jul 24 21:38:42 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Dec 17 18:35:06 2000, Joseph S. Myers +.\" +.TH ATOI 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +atoi, atol, atoll \- convert a string to an integer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int atoi(const char *" nptr ); +.BI "long atol(const char *" nptr ); +.BI "long long atoll(const char *" nptr ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR atoll (): +.RS 4 +__ISOC99_SOURCE || + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR atoi () +function converts the initial portion of the string +pointed to by \fInptr\fP to +.IR int . +The behavior is the same as +.PP +.in +4n +.EX +strtol(nptr, NULL, 10); +.EE +.in +.PP +except that +.BR atoi () +does not detect errors. +.PP +The +.BR atol () +and +.BR atoll () +functions behave the same as +.BR atoi (), +except that they convert the initial portion of the +string to their return type of \fIlong\fP or \fIlong long\fP. +.SH RETURN VALUE +The converted value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR atoi (), +.BR atol (), +.BR atoll () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99, SVr4, 4.3BSD. +C89 and +POSIX.1-1996 include the functions +.BR atoi () +and +.BR atol () +only. +.SH NOTES +Linux libc provided +.BR atoq () +as an obsolete name for +.BR atoll (); +.BR atoq () +is not provided by glibc. +.\" The +.\" .BR atoll () +.\" function is present in glibc 2 since version 2.0.2, but +.\" not in libc4 or libc5. +.SH SEE ALSO +.BR atof (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/atol.3 b/man3/atol.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man3/atol.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man3/atoll.3 b/man3/atoll.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man3/atoll.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man3/atoq.3 b/man3/atoq.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man3/atoq.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man3/auth_destroy.3 b/man3/auth_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/auth_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/authnone_create.3 b/man3/authnone_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/authnone_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/authunix_create.3 b/man3/authunix_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/authunix_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/authunix_create_default.3 b/man3/authunix_create_default.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/authunix_create_default.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/backtrace.3 b/man3/backtrace.3 new file mode 100644 index 0000000..ad4b6a5 --- /dev/null +++ b/man3/backtrace.3 @@ -0,0 +1,299 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" drawing on material by Justin Pryzby +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.TH BACKTRACE 3 2017-09-15 GNU "Linux Programmer's Manual" +.SH NAME +backtrace, backtrace_symbols, backtrace_symbols_fd \- support +for application self-debugging +.SH SYNOPSIS +.B #include +.PP +.B int backtrace(void +.BI ** buffer , +.B int +.IB size ); +.PP +.B char **backtrace_symbols(void *const +.BI * buffer , +.B int +.IB size ); +.PP +.B void backtrace_symbols_fd(void *const +.BI * buffer , +.B int +.IB size , +.B int +.IB fd ); +.SH DESCRIPTION +.BR backtrace () +returns a backtrace for the calling program, +in the array pointed to by +.IR buffer . +A backtrace is the series of currently active function calls for +the program. +Each item in the array pointed to by +.I buffer +is of type +.IR "void\ *" , +and is the return address from +the corresponding stack frame. +The +.I size +argument specifies the maximum number of addresses +that can be stored in +.IR buffer . +If the backtrace is larger than +.IR size , +then the addresses corresponding to the +.I size +most recent function calls are returned; +to obtain the complete backtrace, make sure that +.I buffer +and +.I size +are large enough. +.PP +Given the set of addresses returned by +.BR backtrace () +in +.IR buffer , +.BR backtrace_symbols () +translates the addresses into an array of strings that describe +the addresses symbolically. +The +.I size +argument specifies the number of addresses in +.IR buffer . +The symbolic representation of each address consists of the function name +(if this can be determined), a hexadecimal offset into the function, +and the actual return address (in hexadecimal). +The address of the array of string pointers is returned +as the function result of +.BR backtrace_symbols (). +This array is +.BR malloc (3)ed +by +.BR backtrace_symbols (), +and must be freed by the caller. +(The strings pointed to by the array of pointers +need not and should not be freed.) +.PP +.BR backtrace_symbols_fd () +takes the same +.I buffer +and +.I size +arguments as +.BR backtrace_symbols (), +but instead of returning an array of strings to the caller, +it writes the strings, one per line, to the file descriptor +.IR fd . +.BR backtrace_symbols_fd () +does not call +.BR malloc (3), +and so can be employed in situations where the latter function might +fail, but see NOTES. +.SH RETURN VALUE +.BR backtrace () +returns the number of addresses returned in +.IR buffer , +which is not greater than +.IR size . +If the return value is less than +.IR size , +then the full backtrace was stored; if it is equal to +.IR size , +then it may have been truncated, in which case the addresses of the +oldest stack frames are not returned. +.PP +On success, +.BR backtrace_symbols () +returns a pointer to the array +.BR malloc (3)ed +by the call; +on error, NULL is returned. +.SH VERSIONS +.BR backtrace (), +.BR backtrace_symbols (), +and +.BR backtrace_symbols_fd () +are provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw22 lb lb +l l l. +Interface Attribute Value +T{ +.BR backtrace (), +.br +.BR backtrace_symbols (), +.br +.BR backtrace_symbols_fd () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +These functions make some assumptions about how a function's return +address is stored on the stack. +Note the following: +.IP * 3 +Omission of the frame pointers (as +implied by any of +.BR gcc (1)'s +nonzero optimization levels) may cause these assumptions to be +violated. +.IP * +Inlined functions do not have stack frames. +.IP * +Tail-call optimization causes one stack frame to replace another. +.IP * +.BR backtrace () +and +.BR backtrace_symbols_fd () +don't call +.BR malloc () +explicitly, but they are part of +.IR libgcc , +which gets loaded dynamically when first used. +Dynamic loading usually triggers a call to +.BR malloc (3). +If you need certain calls to these two functions to not allocate memory +(in signal handlers, for example), you need to make sure +.I libgcc +is loaded beforehand. +.PP +The symbol names may be unavailable without the use of special linker +options. +For systems using the GNU linker, it is necessary to use the +.I \-rdynamic +linker option. +Note that names of "static" functions are not exposed, +and won't be available in the backtrace. +.SH EXAMPLE +The program below demonstrates the use of +.BR backtrace () +and +.BR backtrace_symbols (). +The following shell session shows what we might see when running the +program: +.PP +.in +4n +.EX +.RB "$" " cc \-rdynamic prog.c \-o prog" +.RB "$" " ./prog 3" +backtrace() returned 8 addresses +\&./prog(myfunc3+0x5c) [0x80487f0] +\&./prog [0x8048871] +\&./prog(myfunc+0x21) [0x8048894] +\&./prog(myfunc+0x1a) [0x804888d] +\&./prog(myfunc+0x1a) [0x804888d] +\&./prog(main+0x65) [0x80488fb] +\&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c] +\&./prog [0x8048711] +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include + +#define BT_BUF_SIZE 100 + +void +myfunc3(void) +{ + int j, nptrs; + void *buffer[BT_BUF_SIZE]; + char **strings; + + nptrs = backtrace(buffer, BT_BUF_SIZE); + printf("backtrace() returned %d addresses\\n", nptrs); + + /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO) + would produce similar output to the following: */ + + strings = backtrace_symbols(buffer, nptrs); + if (strings == NULL) { + perror("backtrace_symbols"); + exit(EXIT_FAILURE); + } + + for (j = 0; j < nptrs; j++) + printf("%s\\n", strings[j]); + + free(strings); +} + +static void /* "static" means don\(aqt export the symbol... */ +myfunc2(void) +{ + myfunc3(); +} + +void +myfunc(int ncalls) +{ + if (ncalls > 1) + myfunc(ncalls \- 1); + else + myfunc2(); +} + +int +main(int argc, char *argv[]) +{ + if (argc != 2) { + fprintf(stderr, "%s num\-calls\\n", argv[0]); + exit(EXIT_FAILURE); + } + + myfunc(atoi(argv[1])); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR addr2line (1), +.BR gcc (1), +.BR gdb (1), +.BR ld (1), +.BR dlopen (3), +.BR malloc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/backtrace_symbols.3 b/man3/backtrace_symbols.3 new file mode 100644 index 0000000..936a6b9 --- /dev/null +++ b/man3/backtrace_symbols.3 @@ -0,0 +1 @@ +.so man3/backtrace.3 diff --git a/man3/backtrace_symbols_fd.3 b/man3/backtrace_symbols_fd.3 new file mode 100644 index 0000000..936a6b9 --- /dev/null +++ b/man3/backtrace_symbols_fd.3 @@ -0,0 +1 @@ +.so man3/backtrace.3 diff --git a/man3/basename.3 b/man3/basename.3 new file mode 100644 index 0000000..ac26fd9 --- /dev/null +++ b/man3/basename.3 @@ -0,0 +1,209 @@ +.\" Copyright (c) 2000 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created, 14 Dec 2000 by Michael Kerrisk +.\" +.TH BASENAME 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +basename, dirname \- parse pathname components +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *dirname(char *" path ); +.PP +.BI "char *basename(char *" path ); +.fi +.SH DESCRIPTION +Warning: there are two different functions +.BR basename () +- see below. +.PP +The functions +.BR dirname () +and +.BR basename () +break a null-terminated pathname string into directory +and filename components. +In the usual case, +.BR dirname () +returns the string up to, but not including, the final \(aq/\(aq, and +.BR basename () +returns the component following the final \(aq/\(aq. +Trailing \(aq/\(aq characters are not counted as part of the pathname. +.PP +If +.I path +does not contain a slash, +.BR dirname () +returns the string "." while +.BR basename () +returns a copy of +.IR path . +If +.I path +is the string "/", then both +.BR dirname () +and +.BR basename () +return the string "/". +If +.I path +is a null pointer or points to an empty string, then both +.BR dirname () +and +.BR basename () +return the string ".". +.PP +Concatenating the string returned by +.BR dirname (), +a "/", and the string returned by +.BR basename () +yields a complete pathname. +.PP +Both +.BR dirname () +and +.BR basename () +may modify the contents of +.IR path , +so it may be desirable to pass a copy when calling one of +these functions. +.PP +These functions may return pointers to statically allocated memory +which may be overwritten by subsequent calls. +Alternatively, they may return a pointer to some part of +.IR path , +so that the string referred to by +.I path +should not be modified or freed until the pointer returned by +the function is no longer required. +.PP +The following list of examples (taken from SUSv2) +shows the strings returned by +.BR dirname () +and +.BR basename () +for different paths: +.RS +.TS +lb lb lb +l l l l. +path dirname basename +/usr/lib /usr lib +/usr/ / usr +usr . usr +/ / / +\&. . . +\&.. . .. +.TE +.RE +.SH RETURN VALUE +Both +.BR dirname () +and +.BR basename () +return pointers to null-terminated strings. +(Do not pass these pointers to +.BR free (3).) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR basename (), +.BR dirname () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +There are two different versions of +.BR basename () +- the POSIX version described above, and the GNU version, which one gets +after +.PP +.in +4n +.EX +.BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B " #include " +.EE +.in +.PP +The GNU version never modifies its argument, and returns the +empty string when +.I path +has a trailing slash, and in particular also when it is "/". +There is no GNU version of +.BR dirname (). +.PP +With glibc, one gets the POSIX version of +.BR basename () +when +.I +is included, and the GNU version otherwise. +.SH BUGS +In the glibc implementation, +the POSIX versions of these functions modify the +.I path +argument, and segfault when called with a static string +such as "/usr/". +.PP +Before glibc 2.2.1, the glibc version of +.BR dirname () +did not correctly handle pathnames with trailing \(aq/\(aq characters, +and generated a segfault if given a NULL argument. +.SH EXAMPLE +The following code snippet demonstrates the use of +.BR basename () +and +.BR dirname (): +.in +4n +.EX +char *dirc, *basec, *bname, *dname; +char *path = "/etc/passwd"; + +dirc = strdup(path); +basec = strdup(path); +dname = dirname(dirc); +bname = basename(basec); +printf("dirname=%s, basename=%s\\n", dname, bname); +.EE +.in +.SH SEE ALSO +.BR basename (1), +.BR dirname (1) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/bcmp.3 b/man3/bcmp.3 new file mode 100644 index 0000000..dfc3461 --- /dev/null +++ b/man3/bcmp.3 @@ -0,0 +1,96 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:36:50 1993 by Rik Faith +.\" Modified Tue Oct 22 23:47:36 1996 by Eric S. Raymond +.TH BCMP 3 2017-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +bcmp \- compare byte sequences +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int bcmp(const void *" s1 ", const void *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR bcmp () +function compares the two byte sequences +.I s1 +and +.I s2 +of length +.I n +each. +If they are equal, and in particular if +.I n +is zero, +.BR bcmp () +returns 0. +Otherwise, it returns a nonzero result. +.SH RETURN VALUE +The +.BR bcmp () +function returns 0 if the byte sequences are equal, +otherwise a nonzero result is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR bcmp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.3BSD. +This function is deprecated (marked as LEGACY in POSIX.1-2001): use +.BR memcmp (3) +in new programs. +POSIX.1-2008 removes the specification of +.BR bcmp (). +.SH SEE ALSO +.BR bstring (3), +.BR memcmp (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strncasecmp (3), +.BR strncmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/bcopy.3 b/man3/bcopy.3 new file mode 100644 index 0000000..4800783 --- /dev/null +++ b/man3/bcopy.3 @@ -0,0 +1,95 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sun Feb 26 14:52:00 1995 by Rik Faith +.\" Modified Tue Oct 22 23:48:10 1996 by Eric S. Raymond +.\" " +.TH BCOPY 3 2017-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +bcopy \- copy byte sequence +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void bcopy(const void *" src ", void *" dest ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR bcopy () +function copies +.I n +bytes from +.I src +to +.IR dest . +The result is correct, even when both areas overlap. +.SH RETURN VALUE +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR bcopy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.3BSD. +This function is deprecated (marked as LEGACY in POSIX.1-2001): use +.BR memcpy (3) +or +.BR memmove (3) +in new programs. +Note that the first two arguments +are interchanged for +.BR memcpy (3) +and +.BR memmove (3). +POSIX.1-2008 removes the specification of +.BR bcopy (). +.SH SEE ALSO +.BR bstring (3), +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3), +.BR strncpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/be16toh.3 b/man3/be16toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/be16toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/be32toh.3 b/man3/be32toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/be32toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/be64toh.3 b/man3/be64toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/be64toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/bindresvport.3 b/man3/bindresvport.3 new file mode 100644 index 0000000..ae96720 --- /dev/null +++ b/man3/bindresvport.3 @@ -0,0 +1,138 @@ +.\" Copyright (C) 2007, Michael Kerrisk +.\" and Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-05-31, mtk: Rewrite and substantial additional text. +.\" 2008-12-03, mtk: Rewrote some pieces and fixed some errors +.\" +.TH BINDRESVPORT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +bindresvport \- bind a socket to a privileged IP port +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int bindresvport(int " sockfd ", struct sockaddr_in *" sin ); +.fi +.SH DESCRIPTION +.PP +.BR bindresvport () +is used to bind the socket referred to by the +file descriptor +.I sockfd +to a privileged anonymous IP port, +that is, a port number arbitrarily selected from the range 512 to 1023. +.\" Glibc actually starts searching with a port # in the range 600 to 1023 +.PP +If the +.BR bind (2) +performed by +.BR bindresvport () +is successful, and +.I sin +is not NULL, then +.I sin\->sin_port +returns the port number actually allocated. +.PP +.I sin +can be NULL, in which case +.I sin\->sin_family +is implicitly taken to be +.BR AF_INET . +However, in this case, +.BR bindresvport () +has no way to return the port number actually allocated. +(This information can later be obtained using +.BR getsockname (2).) +.SH RETURN VALUE +.BR bindresvport () +returns 0 on success; otherwise \-1 is returned and +.I errno +set to indicate the cause of the error. +.SH ERRORS +.BR bindresvport () +can fail for any of the same reasons as +.BR bind (2). +In addition, the following errors may occur: +.TP +.BR EACCES +The calling process was not privileged +(on Linux: the calling process did not have the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace). +.TP +.B EADDRINUSE +All privileged ports are in use. +.TP +.BR EAFNOSUPPORT " (" EPFNOSUPPORT " in glibc 2.7 and earlier)" +.I sin +is not NULL and +.I sin->sin_family +is not +.BR AF_INET . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l lw23. +Interface Attribute Value +T{ +.BR bindresvport () +T} Thread safety T{ +glibc >= 2.17: MT-Safe +.\" commit f6da27e53695ad1cc0e2a9490358decbbfdff5e5 +.br +glibc < 2.17: MT-Unsafe +T} +.TE +.PP +The +.BR bindresvport () +function uses a static variable that was not protected by a lock +before glibc 2.17, rendering the function MT-Unsafe. +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs, Solaris, and many other systems. +.SH NOTES +Unlike some +.BR bindresvport () +implementations, +the glibc implementation ignores any value that the caller supplies in +.IR sin\->sin_port . +.SH SEE ALSO +.BR bind (2), +.BR getsockname (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/bsd_signal.3 b/man3/bsd_signal.3 new file mode 100644 index 0000000..f98ed1a --- /dev/null +++ b/man3/bsd_signal.3 @@ -0,0 +1,135 @@ +.\" Copyright (c) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH BSD_SIGNAL 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +bsd_signal \- signal handling with BSD semantics +.SH SYNOPSIS +.B #include +.PP +.B typedef void (*sighandler_t)(int); +.PP +.BI "sighandler_t bsd_signal(int " signum ", sighandler_t " handler ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR bsd_signal (): +.RS 4 +Since glibc 2.26: + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + && ! (_POSIX_C_SOURCE\ >=\ 200112L) +.br +Glibc 2.25 and earlier: + _XOPEN_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR bsd_signal () +function takes the same arguments, and performs the same task, as +.BR signal (2). +.PP +The difference between the two is that +.BR bsd_signal () +is guaranteed to provide reliable signal semantics, that is: +a) the disposition of the signal is not reset to the default +when the handler is invoked; +b) delivery of further instances of the signal is blocked while +the signal handler is executing; and +c) if the handler interrupts a blocking system call, +then the system call is automatically restarted. +A portable application cannot rely on +.BR signal (2) +to provide these guarantees. +.SH RETURN VALUE +The +.BR bsd_signal () +function returns the previous value of the signal handler, or +.B SIG_ERR +on error. +.SH ERRORS +As for +.BR signal (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR bsd_signal () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.2BSD, POSIX.1-2001. +POSIX.1-2008 removes the specification of +.BR bsd_signal (), +recommending the use of +.BR sigaction (2) +instead. +.SH NOTES +Use of +.BR bsd_signal () +should be avoided; use +.BR sigaction (2) +instead. +.PP +On modern Linux systems, +.BR bsd_signal () +and +.BR signal (2) +are equivalent. +But on older systems, +.BR signal (2) +provided unreliable signal semantics; see +.BR signal (2) +for details. +.PP +The use of +.I sighandler_t +is a GNU extension; +this type is defined only if the +.B _GNU_SOURCE +feature test macro is defined. +.SH SEE ALSO +.BR sigaction (2), +.BR signal (2), +.BR sysv_signal (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/bsearch.3 b/man3/bsearch.3 new file mode 100644 index 0000000..17f2dc7 --- /dev/null +++ b/man3/bsearch.3 @@ -0,0 +1,155 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:41:16 1993, David Metcalfe +.\" Modified Sat Jul 24 21:35:16 1993, Rik Faith (faith@cs.unc.edu) +.TH BSEARCH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +bsearch \- binary search of a sorted array +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *bsearch(const void *" key ", const void *" base , +.BI " size_t " nmemb ", size_t " size , +.BI " int (*" compar ")(const void *, const void *));" +.fi +.SH DESCRIPTION +The +.BR bsearch () +function searches an array of +.I nmemb +objects, +the initial member of which is pointed to by +.IR base , +for a member +that matches the object pointed to by +.IR key . +The size of each member +of the array is specified by +.IR size . +.PP +The contents of the array should be in ascending sorted order according +to the comparison function referenced by +.IR compar . +The +.I compar +routine is expected to have two arguments which point to the +.I key +object and to an array member, in that order, and should return an integer +less than, equal to, or greater than zero if the +.I key +object is found, +respectively, to be less than, to match, or be greater than the array +member. +.SH RETURN VALUE +The +.BR bsearch () +function returns a pointer to a matching member of the +array, or NULL if no match is found. +If there are multiple elements that +match the key, the element returned is unspecified. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR bsearch () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH EXAMPLE +The example below first sorts an array of structures using +.BR qsort (3), +then retrieves desired elements using +.BR bsearch (). +.PP +.EX +#include +#include +#include + +struct mi { + int nr; + char *name; +} months[] = { + { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" }, + { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" }, + { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" } +}; + +#define nr_of_months (sizeof(months)/sizeof(months[0])) + +static int +compmi(const void *m1, const void *m2) +{ + struct mi *mi1 = (struct mi *) m1; + struct mi *mi2 = (struct mi *) m2; + return strcmp(mi1\->name, mi2\->name); +} + +int +main(int argc, char **argv) +{ + int i; + + qsort(months, nr_of_months, sizeof(struct mi), compmi); + for (i = 1; i < argc; i++) { + struct mi key, *res; + key.name = argv[i]; + res = bsearch(&key, months, nr_of_months, + sizeof(struct mi), compmi); + if (res == NULL) + printf("\(aq%s\(aq: unknown month\en", argv[i]); + else + printf("%s: month #%d\en", res\->name, res\->nr); + } + exit(EXIT_SUCCESS); +} +.EE +.\" this example referred to in qsort.3 +.SH SEE ALSO +.BR hsearch (3), +.BR lsearch (3), +.BR qsort (3), +.BR tsearch (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/bstring.3 b/man3/bstring.3 new file mode 100644 index 0000000..693b972 --- /dev/null +++ b/man3/bstring.3 @@ -0,0 +1,102 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-04-12, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-01-20, Walter Harms +.TH BSTRING 3 2014-05-28 "" "Linux Programmer's Manual" +.SH NAME +bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, +memmove, memset \- byte string operations +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int bcmp(const void *" s1 ", const void *" s2 ", size_t " n ); +.PP +.BI "void bcopy(const void *" src ", void *" dest ", size_t " n ); +.PP +.BI "void bzero(void *" s ", size_t " n ); +.PP +.BI "void *memccpy(void *" dest ", const void *" src ", int " c ", size_t " n ); +.PP +.BI "void *memchr(const void *" s ", int " c ", size_t " n ); +.PP +.BI "int memcmp(const void *" s1 ", const void *" s2 ", size_t " n ); +.PP +.BI "void *memcpy(void *" dest ", const void *" src ", size_t " n ); +.PP +.BI "void *memfrob(void *" s ", size_t " n ); +.PP +.BI "void *memmem(const void *" needle ", size_t " needlelen , +.BI " const void *" haystack ", size_t " haystacklen ); +.PP +.BI "void *memmove(void *" dest ", const void *" src ", size_t " n ); +.PP +.BI "void *memset(void *" s ", int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The byte string functions perform operations on strings (byte arrays) +that are not necessarily null-terminated. +See the individual man pages +for descriptions of each function. +.SH NOTES +The functions +.BR bcmp (), +.BR bcopy () +and +.BR bzero () +are obsolete. +Use +.BR memcmp (), +.BR memcpy () +and +.BR memset () +instead. +.\" The old functions are not even available on some non-GNU/Linux systems. +.SH SEE ALSO +.BR bcmp (3), +.BR bcopy (3), +.BR bzero (3), +.BR memccpy (3), +.BR memchr (3), +.BR memcmp (3), +.BR memcpy (3), +.BR memfrob (3), +.BR memmem (3), +.BR memmove (3), +.BR memset (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/bswap.3 b/man3/bswap.3 new file mode 100644 index 0000000..a1b6d32 --- /dev/null +++ b/man3/bswap.3 @@ -0,0 +1,92 @@ +.\" Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH BSWAP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +bswap_16, bswap_32, bswap_64 \- reverse order of bytes +.SH SYNOPSIS +.nf +.B #include +.PP +.BI bswap_16( x ); +.BI bswap_32( x ); +.BI bswap_64( x ); +.fi +.SH DESCRIPTION +These macros return a value in which the order of the bytes +in their 2-, 4-, or 8-byte arguments is reversed. +.SH RETURN VALUE +These macros return the value of their argument with the bytes reversed. +.SH ERRORS +These macros always succeed. +.SH CONFORMING TO +These macros are GNU extensions. +.SH EXAMPLE +The program below swaps the bytes of the 8-byte integer supplied as +its command-line argument. +The following shell session demonstrates the use of the program: +.PP +.in +4n +.EX +$ \fB./a.out 0x0123456789abcdef\fP +0x123456789abcdef ==> 0xefcdab8967452301 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + uint64_t x; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + x = strtoul(argv[1], NULL, 0); + printf("0x%" PRIx64 " ==> 0x%" PRIx64 "\\n", x, bswap_64(x)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR byteorder (3), +.BR endian (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/bswap_16.3 b/man3/bswap_16.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man3/bswap_16.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man3/bswap_32.3 b/man3/bswap_32.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man3/bswap_32.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man3/bswap_64.3 b/man3/bswap_64.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man3/bswap_64.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man3/btowc.3 b/man3/btowc.3 new file mode 100644 index 0000000..6e932c8 --- /dev/null +++ b/man3/btowc.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH BTOWC 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +btowc \- convert single byte to wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wint_t btowc(int " c ); +.fi +.SH DESCRIPTION +The +.BR btowc () +function converts \fIc\fP, +interpreted as a multibyte sequence +of length 1, starting in the initial shift state, to a wide character and +returns it. +If \fIc\fP is +.B EOF +or not a valid multibyte sequence of length 1, +the +.BR btowc () +function returns +.BR WEOF . +.SH RETURN VALUE +The +.BR btowc () +function returns the wide character +converted from the single byte \fIc\fP. +If \fIc\fP is +.B EOF +or not a valid multibyte sequence of length 1, +it returns +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR btowc () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR btowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +This function should never be used. +It does not work for encodings which have +state, and unnecessarily treats single bytes differently from multibyte +sequences. +Use either +.BR mbtowc (3) +or the thread-safe +.BR mbrtowc (3) +instead. +.SH SEE ALSO +.BR mbrtowc (3), +.BR mbtowc (3), +.BR wctob (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/btree.3 b/man3/btree.3 new file mode 100644 index 0000000..66c7bea --- /dev/null +++ b/man3/btree.3 @@ -0,0 +1,263 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)btree.3 8.4 (Berkeley) 8/18/94 +.\" +.TH BTREE 3 2017-09-15 "" "Linux Programmer's Manual" +.\".UC 7 +.SH NAME +btree \- btree database access method +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided in glibc up until version 2.1. +Since version 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.PP +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is btree files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the btree-specific information. +.PP +The btree data structure is a sorted, balanced tree structure storing +associated key/data pairs. +.PP +The btree access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I +include file as follows: +.PP +.in +4n +.EX +typedef struct { + unsigned long flags; + unsigned int cachesize; + int maxkeypage; + int minkeypage; + unsigned int psize; + int (*compare)(const DBT *key1, const DBT *key2); + size_t (*prefix)(const DBT *key1, const DBT *key2); + int lorder; +} BTREEINFO; +.EE +.in +.PP +The elements of this structure are as follows: +.TP +.I flags +The flag value is specified by ORing any of the following values: +.RS +.TP +.B R_DUP +Permit duplicate keys in the tree, that is, +permit insertion if the key to be +inserted already exists in the tree. +The default behavior, as described in +.BR dbopen (3), +is to overwrite a matching key when inserting a new key or to fail if +the +.B R_NOOVERWRITE +flag is specified. +The +.B R_DUP +flag is overridden by the +.B R_NOOVERWRITE +flag, and if the +.B R_NOOVERWRITE +flag is specified, attempts to insert duplicate keys into +the tree will fail. +.IP +If the database contains duplicate keys, the order of retrieval of +key/data pairs is undefined if the +.I get +routine is used, however, +.I seq +routine calls with the +.B R_CURSOR +flag set will always return the logical +"first" of any group of duplicate keys. +.RE +.TP +.I cachesize +A suggested maximum size (in bytes) of the memory cache. +This value is +.I only +advisory, and the access method will allocate more memory rather than fail. +Since every search examines the root page of the tree, caching the most +recently used pages substantially improves access time. +In addition, physical writes are delayed as long as possible, so a moderate +cache can reduce the number of I/O operations significantly. +Obviously, using a cache increases (but only increases) the likelihood of +corruption or lost data if the system crashes while a tree is being modified. +If +.I cachesize +is 0 (no size is specified), a default cache is used. +.TP +.I maxkeypage +The maximum number of keys which will be stored on any single page. +Not currently implemented. +.\" The maximum number of keys which will be stored on any single page. +.\" Because of the way the btree data structure works, +.\" .I maxkeypage +.\" must always be greater than or equal to 2. +.\" If +.\" .I maxkeypage +.\" is 0 (no maximum number of keys is specified), the page fill factor is +.\" made as large as possible (which is almost invariably what is wanted). +.TP +.I minkeypage +The minimum number of keys which will be stored on any single page. +This value is used to determine which keys will be stored on overflow +pages, that is, if a key or data item is longer than the pagesize divided +by the minkeypage value, it will be stored on overflow pages instead +of in the page itself. +If +.I minkeypage +is 0 (no minimum number of keys is specified), a value of 2 is used. +.TP +.I psize +Page size is the size (in bytes) of the pages used for nodes in the tree. +The minimum page size is 512 bytes and the maximum page size is 64\ KiB. +If +.I psize +is 0 (no page size is specified), a page size is chosen based on the +underlying filesystem I/O block size. +.TP +.I compare +Compare is the key comparison function. +It must return an integer less than, equal to, or greater than zero if the +first key argument is considered to be respectively less than, equal to, +or greater than the second key argument. +The same comparison function must be used on a given tree every time it +is opened. +If +.I compare +is NULL (no comparison function is specified), the keys are compared +lexically, with shorter keys considered less than longer keys. +.TP +.I prefix +Prefix is the prefix comparison function. +If specified, this routine must return the number of bytes of the second key +argument which are necessary to determine that it is greater than the first +key argument. +If the keys are equal, the key length should be returned. +Note, the usefulness of this routine is very data-dependent, but, in some +data sets can produce significantly reduced tree sizes and search times. +If +.I prefix +is NULL (no prefix function is specified), +.I and +no comparison function is specified, a default lexical comparison routine +is used. +If +.I prefix +is NULL and a comparison routine is specified, no prefix comparison is +done. +.TP +.I lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +.PP +If the file already exists (and the +.B O_TRUNC +flag is not specified), the +values specified for the arguments +.IR flags , +.I lorder +and +.I psize +are ignored +in favor of the values used when the tree was created. +.PP +Forward sequential scans of a tree are from the least key to the greatest. +.PP +Space freed up by deleting key/data pairs from the tree is never reclaimed, +although it is normally made available for reuse. +This means that the btree storage structure is grow-only. +The only solutions are to avoid excessive deletions, or to create a fresh +tree periodically from a scan of an existing one. +.PP +Searches, insertions, and deletions in a btree will all complete in +O lg base N where base is the average fill factor. +Often, inserting ordered data into btrees results in a low fill factor. +This implementation has been modified to make ordered insertion the best +case, resulting in a much better than normal page fill factor. +.SH ERRORS +The +.I btree +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3). +.SH BUGS +Only big and little endian byte order is supported. +.SH SEE ALSO +.BR dbopen (3), +.BR hash (3), +.BR mpool (3), +.BR recno (3) +.PP +.IR "The Ubiquitous B-tree" , +Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138. +.PP +.IR "Prefix B-trees" , +Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1 +(March 1977), 11-26. +.PP +.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" , +D.E. Knuth, 1968, pp 471-480. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/byteorder.3 b/man3/byteorder.3 new file mode 100644 index 0000000..b8f69ca --- /dev/null +++ b/man3/byteorder.3 @@ -0,0 +1,111 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:29:05 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Jul 26 14:06:20 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH BYTEORDER 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +htonl, htons, ntohl, ntohs \- convert values between host and network +byte order +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "uint32_t htonl(uint32_t " hostlong ); +.PP +.BI "uint16_t htons(uint16_t " hostshort ); +.PP +.BI "uint32_t ntohl(uint32_t " netlong ); +.PP +.BI "uint16_t ntohs(uint16_t " netshort ); +.fi +.SH DESCRIPTION +The +.BR htonl () +function converts the unsigned integer +.I hostlong +from host byte order to network byte order. +.PP +The +.BR htons () +function converts the unsigned short integer +.I hostshort +from host byte order to network byte order. +.PP +The +.BR ntohl () +function converts the unsigned integer +.I netlong +from network byte order to host byte order. +.PP +The +.BR ntohs () +function converts the unsigned short integer +.I netshort +from network byte order to host byte order. +.PP +On the i386 the host byte order is Least Significant Byte first, +whereas the network byte order, as used on the Internet, is Most +Significant Byte first. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw34 lb lb +l l l. +Interface Attribute Value +T{ +.BR htonl (), +.BR htons (), +.BR ntohl (), +.BR ntohs () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.PP +Some systems require the inclusion of +.I +instead of +.IR . +.SH SEE ALSO +.BR bswap (3), +.BR endian (3), +.BR gethostbyname (3), +.BR getservent (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/bzero.3 b/man3/bzero.3 new file mode 100644 index 0000000..4d1c315 --- /dev/null +++ b/man3/bzero.3 @@ -0,0 +1,184 @@ +.\" Copyright (C) 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH BZERO 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +bzero, explicit_bzero \- zero a byte string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void bzero(void *" s ", size_t " n ); +.PP +.B #include +.PP +.BI "void explicit_bzero(void *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR bzero () +function erases the data in the +.I n +bytes of the memory starting at the location pointed to by +.IR s , +by writing zeroes (bytes containing \(aq\\0\(aq) to that area. +.PP +The +.BR explicit_bzero () +function performs the same task as +.BR bzero (). +It differs from +.BR bzero () +in that it guarantees that compiler optimizations will not remove the +erase operation if the compiler deduces that the operation is "unnecessary". +.SH RETURN VALUE +None. +.SH VERSIONS +.BR explicit_bzero () +first appeared in glibc 2.25. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR bzero (), +.br +.BR explicit_bzero () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The +.BR bzero () +function is deprecated (marked as LEGACY in POSIX.1-2001); use +.BR memset (3) +in new programs. +POSIX.1-2008 removes the specification of +.BR bzero (). +The +.BR bzero () +function first appeared in 4.3BSD. +.PP +The +.BR explicit_bzero () +function is a nonstandard extension that is also present on some of the BSDs. +Some other implementations have a similar function, such as +.BR memset_explicit () +or +.BR memset_s (). +.SH NOTES +The +.BR explicit_bzero () +function addresses a problem that security-conscious applications +may run into when using +.BR bzero (): +if the compiler can deduce that the location to zeroed will +never again be touched by a +.I correct +program, then it may remove the +.BR bzero () +call altogether. +This is a problem if the intent of the +.BR bzero () +call was to erase sensitive data (e.g., passwords) +to prevent the possibility that the data was leaked +by an incorrect or compromised program. +Calls to +.BR explicit_bzero () +are never optimized away by the compiler. +.PP +The +.BR explicit_bzero () +function does not solve all problems associated with erasing sensitive data: +.IP 1. 3 +The +.BR explicit_bzero () +function does +.I not +guarantee that sensitive data is completely erased from memory. +(The same is true of +.BR bzero ().) +For example, there may be copies of the sensitive data in +a register and in "scratch" stack areas. +The +.BR explicit_bzero () +function is not aware of these copies, and can't erase them. +.IP 2. +In some circumstances, +.BR explicit_bzero () +can +.I decrease +security. +If the compiler determined that the variable containing the +sensitive data could be optimized to be stored in a register +(because it is small enough to fit in a register, +and no operation other than the +.BR explicit_bzero () +call would need to take the address of the variable), then the +.BR explicit_bzero () +call will force the data to be copied from the register +to a location in RAM that is then immediately erased +(while the copy in the register remains unaffected). +The problem here is that data in RAM is more likely to be exposed +by a bug than data in a register, and thus the +.BR explicit_bzero () +call creates a brief time window where the sensitive data is more +vulnerable than it would otherwise have been +if no attempt had been made to erase the data. +.PP +Note that declaring the sensitive variable with the +.B volatile +qualifier does +.I not +eliminate the above problems. +Indeed, it will make them worse, since, for example, +it may force a variable that would otherwise have been optimized +into a register to instead be maintained in (more vulnerable) +RAM for its entire lifetime. +.PP +Notwithstanding the above details, for security-conscious applications, using +.BR explicit_bzero () +is generally preferable to not using it. +The developers of +.BR explicit_bzero () +anticipate that future compilers will recognize calls to +.BR explicit_bzero () +and take steps to ensure that all copies of the sensitive data are erased, +including copies in registers or in "scratch" stack areas. +.SH SEE ALSO +.BR bstring (3), +.BR memset (3), +.BR swab (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cabs.3 b/man3/cabs.3 new file mode 100644 index 0000000..d8d3be8 --- /dev/null +++ b/man3/cabs.3 @@ -0,0 +1,60 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CABS 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +cabs, cabsf, cabsl \- absolute value of a complex number +.SH SYNOPSIS +.B #include +.PP +.BI "double cabs(double complex " z ); +.br +.BI "float cabsf(float complex " z ); +.br +.BI "long double cabsl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions return the absolute value of the complex number +.IR z . +The result is a real number. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR cabs (), +.BR cabsf (), +.BR cabsl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The function is actually an alias for +.I "hypot(a,\ b)" +(or, equivalently, +.IR "sqrt(a*a\ +\ b*b)" ). +.SH SEE ALSO +.BR abs (3), +.BR cimag (3), +.BR hypot (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cabsf.3 b/man3/cabsf.3 new file mode 100644 index 0000000..e50ac96 --- /dev/null +++ b/man3/cabsf.3 @@ -0,0 +1 @@ +.so man3/cabs.3 diff --git a/man3/cabsl.3 b/man3/cabsl.3 new file mode 100644 index 0000000..e50ac96 --- /dev/null +++ b/man3/cabsl.3 @@ -0,0 +1 @@ +.so man3/cabs.3 diff --git a/man3/cacos.3 b/man3/cacos.3 new file mode 100644 index 0000000..6c8c203 --- /dev/null +++ b/man3/cacos.3 @@ -0,0 +1,97 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CACOS 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +cacos, cacosf, cacosl \- complex arc cosine +.SH SYNOPSIS +.B #include +.PP +.BI "double complex cacos(double complex " z ); +.br +.BI "float complex cacosf(float complex " z ); +.br +.BI "long double complex cacosl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex arc cosine of +.IR z . +If \fIy\ =\ cacos(z)\fP, then \fIz\ =\ ccos(y)\fP. +The real part of +.I y +is chosen in the interval [0,pi]. +.PP +One has: +.PP +.nf + cacos(z) = \-i * clog(z + i * csqrt(1 \- z * z)) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR cacos (), +.BR cacosf (), +.BR cacosl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +.EX +/* Link with "\-lm" */ + +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + double complex z, c, f; + double complex i = I; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + z = atof(argv[1]) + atof(argv[2]) * I; + + c = cacos(z); + + printf("cacos() = %6.3f %6.3f*i\\n", creal(c), cimag(c)); + + f = \-i * clog(z + i * csqrt(1 \- z * z)); + + printf("formula = %6.3f %6.3f*i\\n", creal(f), cimag(f)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ccos (3), +.BR clog (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cacosf.3 b/man3/cacosf.3 new file mode 100644 index 0000000..a4f10e1 --- /dev/null +++ b/man3/cacosf.3 @@ -0,0 +1 @@ +.so man3/cacos.3 diff --git a/man3/cacosh.3 b/man3/cacosh.3 new file mode 100644 index 0000000..17966f7 --- /dev/null +++ b/man3/cacosh.3 @@ -0,0 +1,99 @@ +.\" Copyright 2002 Walter Harms(walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CACOSH 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine +.SH SYNOPSIS +.B #include +.PP +.BI "double complex cacosh(double complex " z ); +.br +.BI "float complex cacoshf(float complex " z ); +.br +.BI "long double complex cacoshl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic cosine of +.IR z . +If \fIy\ =\ cacosh(z)\fP, then \fIz\ =\ ccosh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi,pi]. +The real part of +.I y +is chosen nonnegative. +.PP +One has: +.PP +.nf + cacosh(z) = 2 * clog(csqrt((z + 1) / 2) + csqrt((z \- 1) / 2)) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR cacosh (), +.BR cacoshf (), +.BR cacoshl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +.EX +/* Link with "\-lm" */ + +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + double complex z, c, f; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + z = atof(argv[1]) + atof(argv[2]) * I; + + c = cacosh(z); + printf("cacosh() = %6.3f %6.3f*i\\n", creal(c), cimag(c)); + + f = 2 * clog(csqrt((z + 1)/2) + csqrt((z \- 1)/2)); + printf("formula = %6.3f %6.3f*i\\n", creal(f2), cimag(f2)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR acosh (3), +.BR cabs (3), +.BR ccosh (3), +.BR cimag (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cacoshf.3 b/man3/cacoshf.3 new file mode 100644 index 0000000..c89c010 --- /dev/null +++ b/man3/cacoshf.3 @@ -0,0 +1 @@ +.so man3/cacosh.3 diff --git a/man3/cacoshl.3 b/man3/cacoshl.3 new file mode 100644 index 0000000..c89c010 --- /dev/null +++ b/man3/cacoshl.3 @@ -0,0 +1 @@ +.so man3/cacosh.3 diff --git a/man3/cacosl.3 b/man3/cacosl.3 new file mode 100644 index 0000000..a4f10e1 --- /dev/null +++ b/man3/cacosl.3 @@ -0,0 +1 @@ +.so man3/cacos.3 diff --git a/man3/calloc.3 b/man3/calloc.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man3/calloc.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man3/callrpc.3 b/man3/callrpc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/callrpc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/canonicalize_file_name.3 b/man3/canonicalize_file_name.3 new file mode 100644 index 0000000..9bb253e --- /dev/null +++ b/man3/canonicalize_file_name.3 @@ -0,0 +1,98 @@ +.\" Copyright 2013 Michael Kerrisk +.\" (Replaces an earlier page by Walter Harms and Michael Kerrisk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH CANONICALIZE_FILE_NAME 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +canonicalize_file_name \- return the canonicalized absolute pathname +.SH SYNOPSIS +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.PP +.BI "char *canonicalize_file_name(const char *" path ");" +.SH DESCRIPTION +The +.BR canonicalize_file_name () +function returns a null-terminated string containing +the canonicalized absolute pathname corresponding to +.IR path . +In the returned string, symbolic links are resolved, as are +.I . +and +.I .. +pathname components. +Consecutive slash +.RI ( / ) +characters are replaced by a single slash. +.PP +The returned string is dynamically allocated by +.BR canonicalize_file_name () +and the caller should deallocate it with +.BR free (3) +when it is no longer required. +.PP +The call +.I canonicalize_file_name(path) +is equivalent to the call: +.PP + realpath(path, NULL); +.SH RETURN VALUE +On success, +.BR canonicalize_file_name () +returns a null-terminated string. +On error (e.g., a pathname component is unreadable or does not exist), +.BR canonicalize_file_name () +returns NULL and sets +.I errno +to indicate the error. +.SH ERRORS +See +.BR realpath (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR canonicalize_file_name () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is a GNU extension. +.SH SEE ALSO +.BR readlink (2), +.BR realpath (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/carg.3 b/man3/carg.3 new file mode 100644 index 0000000..a2b9f64 --- /dev/null +++ b/man3/carg.3 @@ -0,0 +1,88 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CARG 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +carg, cargf, cargl \- calculate the complex argument +.SH SYNOPSIS +.B #include +.PP +.BI "double carg(double complex " z ");" +.br +.BI "float cargf(float complex " z ");" +.br +.BI "long double cargl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex argument (also called phase angle) of +.IR z , +with a branch cut along the negative real axis. +.PP +A complex number can be described by two real coordinates. +One may use rectangular coordinates and gets +.PP +.nf + z = x + I * y +.fi +.PP +where +.IR "x\ =\ creal(z)" +and +.IR "y\ =\ cimag(z)" . +.PP +Or one may use polar coordinates and gets +.PP +.nf + z = r * cexp(I * a) +.fi +.PP +where +.IR "r\ =\ cabs(z)" +is the "radius", the "modulus", the absolute value of +.IR z , +and +.IR "a\ =\ carg(z)" +is the "phase angle", the argument of +.IR z . +.PP +One has: +.PP +.nf + tan(carg(z)) = cimag(z) / creal(z) +.fi +.SH RETURN VALUE +The return value is the range of [\-pi,pi]. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR carg (), +.BR cargf (), +.BR cargl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cargf.3 b/man3/cargf.3 new file mode 100644 index 0000000..c181aa4 --- /dev/null +++ b/man3/cargf.3 @@ -0,0 +1 @@ +.so man3/carg.3 diff --git a/man3/cargl.3 b/man3/cargl.3 new file mode 100644 index 0000000..c181aa4 --- /dev/null +++ b/man3/cargl.3 @@ -0,0 +1 @@ +.so man3/carg.3 diff --git a/man3/casin.3 b/man3/casin.3 new file mode 100644 index 0000000..77c998c --- /dev/null +++ b/man3/casin.3 @@ -0,0 +1,63 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CASIN 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +casin, casinf, casinl \- complex arc sine +.SH SYNOPSIS +.B #include +.PP +.BI "double complex casin(double complex " z ); +.br +.BI "float complex casinf(float complex " z ); +.br +.BI "long double complex casinl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex arc sine of +.IR z . +If \fIy\ =\ casin(z)\fP, then \fIz\ =\ csin(y)\fP. +The real part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.PP +One has: +.PP +.nf + casin(z) = \-i clog(iz + csqrt(1 \- z * z)) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR casin (), +.BR casinf (), +.BR casinl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR clog (3), +.BR csin (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/casinf.3 b/man3/casinf.3 new file mode 100644 index 0000000..582875f --- /dev/null +++ b/man3/casinf.3 @@ -0,0 +1 @@ +.so man3/casin.3 diff --git a/man3/casinh.3 b/man3/casinh.3 new file mode 100644 index 0000000..bcefb2c --- /dev/null +++ b/man3/casinh.3 @@ -0,0 +1,65 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CASINH 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +casinh, casinhf, casinhl \- complex arc sine hyperbolic +.SH SYNOPSIS +.B #include +.PP +.BI "double complex casinh(double complex " z ); +.br +.BI "float complex casinhf(float complex " z ); +.br +.BI "long double complex casinhl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic sine of +.IR z . +If \fIy\ =\ casinh(z)\fP, then \fIz\ =\ csinh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.PP +One has: +.PP +.nf + casinh(z) = clog(z + csqrt(z * z + 1)) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR casinh (), +.BR casinhf (), +.BR casinhl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR asinh (3), +.BR cabs (3), +.BR cimag (3), +.BR csinh (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/casinhf.3 b/man3/casinhf.3 new file mode 100644 index 0000000..c2eada8 --- /dev/null +++ b/man3/casinhf.3 @@ -0,0 +1 @@ +.so man3/casinh.3 diff --git a/man3/casinhl.3 b/man3/casinhl.3 new file mode 100644 index 0000000..c2eada8 --- /dev/null +++ b/man3/casinhl.3 @@ -0,0 +1 @@ +.so man3/casinh.3 diff --git a/man3/casinl.3 b/man3/casinl.3 new file mode 100644 index 0000000..582875f --- /dev/null +++ b/man3/casinl.3 @@ -0,0 +1 @@ +.so man3/casin.3 diff --git a/man3/catan.3 b/man3/catan.3 new file mode 100644 index 0000000..3d8fc57 --- /dev/null +++ b/man3/catan.3 @@ -0,0 +1,94 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CATAN 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +catan, catanf, catanl \- complex arc tangents +.SH SYNOPSIS +.B #include +.PP +.BI "double complex catan(double complex " z ); +.br +.BI "float complex catanf(float complex " z ); +.br +.BI "long double complex catanl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex arc tangent of +.IR z . +If \fIy\ =\ catan(z)\fP, then \fIz\ =\ ctan(y)\fP. +The real part of y is chosen in the interval [\-pi/2,pi/2]. +.PP +One has: +.PP +.nf + catan(z) = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR catan (), +.BR catanf (), +.BR catanl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +.EX +/* Link with "\-lm" */ + +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + double complex z, c, f; + double complex i = I; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + z = atof(argv[1]) + atof(argv[2]) * I; + + c = catan(z); + printf("catan() = %6.3f %6.3f*i\\n", creal(c), cimag(c)); + + f = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i); + printf("formula = %6.3f %6.3f*i\\n", creal(f2), cimag(f2)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ccos (3), +.BR clog (3), +.BR ctan (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/catanf.3 b/man3/catanf.3 new file mode 100644 index 0000000..d1e2522 --- /dev/null +++ b/man3/catanf.3 @@ -0,0 +1 @@ +.so man3/catan.3 diff --git a/man3/catanh.3 b/man3/catanh.3 new file mode 100644 index 0000000..899505a --- /dev/null +++ b/man3/catanh.3 @@ -0,0 +1,96 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CATANH 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +catanh, catanhf, catanhl \- complex arc tangents hyperbolic +.SH SYNOPSIS +.B #include +.PP +.BI "double complex catanh(double complex " z ); +.br +.BI "float complex catanhf(float complex " z ); +.br +.BI "long double complex catanhl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic tangent of +.IR z . +If \fIy\ =\ catanh(z)\fP, then \fIz\ =\ ctanh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.PP +One has: +.PP +.nf + catanh(z) = 0.5 * (clog(1 + z) \- clog(1 \- z)) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR catanh (), +.BR catanhf (), +.BR catanhl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +.EX +/* Link with "\-lm" */ + +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + double complex z, c, f; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + z = atof(argv[1]) + atof(argv[2]) * I; + + c = catanh(z); + printf("catanh() = %6.3f %6.3f*i\\n", creal(c), cimag(c)); + + f = 0.5 * (clog(1 + z) \- clog(1 \- z)); + printf("formula = %6.3f %6.3f*i\\n", creal(f2), cimag(f2)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR atanh (3), +.BR cabs (3), +.BR cimag (3), +.BR ctanh (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/catanhf.3 b/man3/catanhf.3 new file mode 100644 index 0000000..23f22a4 --- /dev/null +++ b/man3/catanhf.3 @@ -0,0 +1 @@ +.so man3/catanh.3 diff --git a/man3/catanhl.3 b/man3/catanhl.3 new file mode 100644 index 0000000..23f22a4 --- /dev/null +++ b/man3/catanhl.3 @@ -0,0 +1 @@ +.so man3/catanh.3 diff --git a/man3/catanl.3 b/man3/catanl.3 new file mode 100644 index 0000000..d1e2522 --- /dev/null +++ b/man3/catanl.3 @@ -0,0 +1 @@ +.so man3/catan.3 diff --git a/man3/catclose.3 b/man3/catclose.3 new file mode 100644 index 0000000..92ff666 --- /dev/null +++ b/man3/catclose.3 @@ -0,0 +1 @@ +.so man3/catopen.3 diff --git a/man3/catgets.3 b/man3/catgets.3 new file mode 100644 index 0000000..257c833 --- /dev/null +++ b/man3/catgets.3 @@ -0,0 +1,109 @@ +.\" Copyright 1993 Mitchum DSouza +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Updated, aeb, 980809 +.TH CATGETS 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +catgets \- get message from a message catalog +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *catgets(nl_catd " catalog ", int " set_number \ +", int " message_number , +.BI " const char *" message ); +.fi +.SH DESCRIPTION +.BR catgets () +reads the message +.IR message_number , +in set +.IR set_number , +from the message catalog identified by +.IR catalog , +where +.I catalog +is a catalog descriptor returned from an earlier call to +.BR catopen (3). +The fourth argument, +.IR message , +points to a default message string which will be returned by +.BR catgets () +if the identified message catalog is not currently available. +The +message-text is contained in an internal buffer area and should be copied by +the application if it is to be saved or modified. +The return string is +always terminated with a null byte (\(aq\\0\(aq). +.SH RETURN VALUE +.PP +On success, +.BR catgets () +returns a pointer to an internal buffer area +containing the null-terminated message string. +On failure, +.BR catgets () +returns the value +.IR message . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR catgets () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The +.BR catgets () +function is available only in libc.so.4.4.4c and above. +The Jan 1987 X/Open Portability Guide specifies a more subtle +error return: +.I message +is returned if the message catalog specified by +.I catalog +is not available, while an empty string is returned +when the message catalog is available but does not contain +the specified message. +These two possible error returns seem to be discarded in SUSv2 +in favor of always returning +.IR message . +.SH SEE ALSO +.BR catopen (3), +.BR setlocale (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/catopen.3 b/man3/catopen.3 new file mode 100644 index 0000000..d1e57f6 --- /dev/null +++ b/man3/catopen.3 @@ -0,0 +1,217 @@ +.\" Copyright 1993 Mitchum DSouza +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze +.\" Modified 2001-12-14 aeb +.\" +.TH CATOPEN 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +catopen, catclose \- open/close a message catalog +.SH SYNOPSIS +.B #include +.PP +.BI "nl_catd catopen(const char *" name ", int " flag ); +.PP +.BI "int catclose(nl_catd " catalog ); +.SH DESCRIPTION +The function +.BR catopen () +opens a message catalog and returns a catalog descriptor. +The descriptor remains valid until +.BR catclose () +or +.BR execve (2). +If a file descriptor is used to implement catalog descriptors, +then the +.B FD_CLOEXEC +flag will be set. +.PP +The argument +.I name +specifies the name of the message catalog to be opened. +If +.I name +specifies an absolute path (i.e., contains a \(aq/\(aq), +then +.I name +specifies a pathname for the message catalog. +Otherwise, the environment variable +.B NLSPATH +is used with +.I name +substituted for +.B %N +(see +.BR locale (7)). +It is unspecified whether +.B NLSPATH +will be used when the process has root privileges. +If +.B NLSPATH +does not exist in the environment, +or if a message catalog cannot be opened +in any of the paths specified by it, +then an implementation defined path is used. +This latter default path may depend on the +.B LC_MESSAGES +locale setting when the +.I flag +argument is +.B NL_CAT_LOCALE +and on the +.B LANG +environment variable when the +.I flag +argument is 0. +Changing the +.B LC_MESSAGES +part of the locale may invalidate +open catalog descriptors. +.PP +The +.I flag +argument to +.BR catopen () +is used to indicate the source for the language to use. +If it is set to +.BR NL_CAT_LOCALE , +then it will use the current locale setting for +.BR LC_MESSAGES . +Otherwise, it will use the +.B LANG +environment variable. +.PP +The function +.BR catclose () +closes the message catalog identified by +.IR catalog . +It invalidates any subsequent references to the message catalog +defined by +.IR catalog . +.SH RETURN VALUE +The function +.BR catopen () +returns a message catalog descriptor of type +.I nl_catd +on success. +On failure, it returns +.IR "(nl_catd)\ \-1" +and sets +.I errno +to indicate the error. +The possible error values include all +possible values for the +.BR open (2) +call. +.PP +The function +.BR catclose () +returns 0 on success, or \-1 on failure. +.SH ENVIRONMENT +.TP +.B LC_MESSAGES +May be the source of the +.B LC_MESSAGES +locale setting, and thus +determine the language to use if +.I flag +is set to +.BR NL_CAT_LOCALE . +.TP +.B LANG +The language to use if +.I flag +is 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR catopen () +T} Thread safety MT-Safe env +T{ +.BR catclose () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.\" In XPG 1987, Vol. 3 it says: +.\" .I "The flag argument of catopen is reserved for future use" +.\" .IR "and should be set to 0" . +.\" +.\" It is unclear what the source was for the constants +.\" .B MCLoadBySet +.\" and +.\" .B MCLoadAll +.\" (see below). +.SH NOTES +The above is the POSIX.1 description. +The glibc value for +.B NL_CAT_LOCALE +is 1. +.\" (Compare +.\" .B MCLoadAll +.\" below.) +The default path varies, but usually looks at a number of places below +.IR /usr/share/locale . +.\" .SS Linux notes +.\" These functions are available for Linux since libc 4.4.4c. +.\" In the case of linux libc4 and libc5, the catalog descriptor +.\" .I nl_catd +.\" is a +.\" .BR mmap (2)'ed +.\" area of memory and not a file descriptor. +.\" The +.\" .I flag +.\" argument to +.\" .BR catopen () +.\" should be either +.\" .B MCLoadBySet +.\" (=0) or +.\" .B MCLoadAll +.\" (=1). +.\" The former value indicates that a set from the catalog is to be +.\" loaded when needed, whereas the latter causes the initial call to +.\" .BR catopen () +.\" to load the entire catalog into memory. +.\" The default search path varies, but usually looks at a number of places below +.\" .I /etc/locale +.\" and +.\" .IR /usr/lib/locale . +.SH SEE ALSO +.BR catgets (3), +.BR setlocale (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cbc_crypt.3 b/man3/cbc_crypt.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man3/cbc_crypt.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man3/cbrt.3 b/man3/cbrt.3 new file mode 100644 index 0000000..d0e633e --- /dev/null +++ b/man3/cbrt.3 @@ -0,0 +1,112 @@ +.\" Copyright 1995 Jim Van Zandt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" changed `square root' into `cube root' - aeb, 950919 +.\" +.\" Modified 2002-07-27 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH CBRT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +cbrt, cbrtf, cbrtl \- cube root function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double cbrt(double " x ); +.BI "float cbrtf(float " x ); +.BI "long double cbrtl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR cbrt (): +.br +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.BR cbrtf (), +.BR cbrtl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return the (real) cube root of +.IR x . +This function cannot fail; every representable real value has a +representable real cube root. +.SH RETURN VALUE +These functions return the cube root of +.IR x . +.PP +If +.I x +is +0, \-0, positive infinity, negative infinity, or NaN, +.I x +is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR cbrt (), +.BR cbrtf (), +.BR cbrtl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.\" .BR cbrt () +.\" was a GNU extension. It is now a C99 requirement. +.SH SEE ALSO +.BR pow (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cbrtf.3 b/man3/cbrtf.3 new file mode 100644 index 0000000..b662c9e --- /dev/null +++ b/man3/cbrtf.3 @@ -0,0 +1 @@ +.so man3/cbrt.3 diff --git a/man3/cbrtl.3 b/man3/cbrtl.3 new file mode 100644 index 0000000..b662c9e --- /dev/null +++ b/man3/cbrtl.3 @@ -0,0 +1 @@ +.so man3/cbrt.3 diff --git a/man3/ccos.3 b/man3/ccos.3 new file mode 100644 index 0000000..4ba6f1e --- /dev/null +++ b/man3/ccos.3 @@ -0,0 +1,62 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CCOS 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ccos, ccosf, ccosl \- complex cosine function +.SH SYNOPSIS +.B #include +.PP +.BI "double complex ccos(double complex " z ");" +.br +.BI "float complex ccosf(float complex " z ");" +.br +.BI "long double complex ccosl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex cosine of +.IR z . +.PP +The complex cosine function is defined as: +.PP +.nf + ccos(z) = (exp(i * z) + exp(\-i * z)) / 2 +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR ccos (), +.BR ccosf (), +.BR ccosl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR cacos (3), +.BR csin (3), +.BR ctan (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ccosf.3 b/man3/ccosf.3 new file mode 100644 index 0000000..b4323ff --- /dev/null +++ b/man3/ccosf.3 @@ -0,0 +1 @@ +.so man3/ccos.3 diff --git a/man3/ccosh.3 b/man3/ccosh.3 new file mode 100644 index 0000000..f022f06 --- /dev/null +++ b/man3/ccosh.3 @@ -0,0 +1,47 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CCOSH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ccosh, ccoshf, ccoshl \- complex hyperbolic cosine +.SH SYNOPSIS +.B #include +.PP +.BI "double complex ccosh(double complex " z ");" +.br +.BI "float complex ccoshf(float complex " z ");" +.br +.BI "long double complex ccoshl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex hyperbolic cosine of +.IR z . +.PP +The complex hyperbolic cosine function is defined as: +.PP +.nf + ccosh(z) = (exp(z)+exp(\-z))/2 +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR cacosh (3), +.BR csinh (3), +.BR ctanh (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ccoshf.3 b/man3/ccoshf.3 new file mode 100644 index 0000000..a777fbf --- /dev/null +++ b/man3/ccoshf.3 @@ -0,0 +1 @@ +.so man3/ccosh.3 diff --git a/man3/ccoshl.3 b/man3/ccoshl.3 new file mode 100644 index 0000000..a777fbf --- /dev/null +++ b/man3/ccoshl.3 @@ -0,0 +1 @@ +.so man3/ccosh.3 diff --git a/man3/ccosl.3 b/man3/ccosl.3 new file mode 100644 index 0000000..b4323ff --- /dev/null +++ b/man3/ccosl.3 @@ -0,0 +1 @@ +.so man3/ccos.3 diff --git a/man3/ceil.3 b/man3/ceil.3 new file mode 100644 index 0000000..ce08a40 --- /dev/null +++ b/man3/ceil.3 @@ -0,0 +1,138 @@ +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH CEIL 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ceil, ceilf, ceill \- ceiling function: smallest integral value not +less than argument +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double ceil(double " x ); +.BI "float ceilf(float " x ); +.BI "long double ceill(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR ceilf (), +.BR ceill (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the smallest integral value that is not less than +.IR x . +.PP +For example, +.IR ceil(0.5) +is 1.0, and +.IR ceil(\-0.5) +is 0.0. +.SH RETURN VALUE +These functions return the ceiling of +.IR x . +.PP +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR ceil (), +.BR ceilf (), +.BR ceill () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH NOTES +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 128 (respectively, 1024), +and the number of mantissa bits is 24 (respectively, 53).) +.PP +The integral value returned by these functions may be too large +to store in an integer type +.RI ( int , +.IR long , +etc.). +To avoid an overflow, which will produce undefined results, +an application should perform a range check on the returned value +before assigning it to an integer type. +.SH SEE ALSO +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3), +.BR trunc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ceilf.3 b/man3/ceilf.3 new file mode 100644 index 0000000..569d1ba --- /dev/null +++ b/man3/ceilf.3 @@ -0,0 +1 @@ +.so man3/ceil.3 diff --git a/man3/ceill.3 b/man3/ceill.3 new file mode 100644 index 0000000..569d1ba --- /dev/null +++ b/man3/ceill.3 @@ -0,0 +1 @@ +.so man3/ceil.3 diff --git a/man3/cexp.3 b/man3/cexp.3 new file mode 100644 index 0000000..88fbcff --- /dev/null +++ b/man3/cexp.3 @@ -0,0 +1,63 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CEXP 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +cexp, cexpf, cexpl \- complex exponential function +.SH SYNOPSIS +.B #include +.PP +.BI "double complex cexp(double complex " z ");" +.br +.BI "float complex cexpf(float complex " z ");" +.br +.BI "long double complex cexpl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate e (2.71828..., the base of natural logarithms) +raised to the power of +.IR z . +.PP +One has: +.PP +.nf + cexp(I * z) = ccos(z) + I * csin(z) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR cexp (), +.BR cexpf (), +.BR cexpl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR cexp2 (3), +.BR clog (3), +.BR cpow (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cexp2.3 b/man3/cexp2.3 new file mode 100644 index 0000000..d4ff8de --- /dev/null +++ b/man3/cexp2.3 @@ -0,0 +1,41 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CEXP2 3 2014-08-19 "" "Linux Programmer's Manual" +.SH NAME +cexp2, cexp2f, cexp2l \- base-2 exponent of a complex number +.SH SYNOPSIS +.B #include +.PP +.BI "double complex cexp2(double complex " z ");" +.br +.BI "float complex cexp2f(float complex " z ");" +.br +.BI "long double complex cexp2l(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +The function returns 2 raised to the power of +.IR z . +.SH CONFORMING TO +These function names are reserved for future use in C99. +.SH AVAILABILITY +Not yet in glibc, as at version 2.19. +.\" But reserved in NAMESPACE. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog10 (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cexp2f.3 b/man3/cexp2f.3 new file mode 100644 index 0000000..759ad34 --- /dev/null +++ b/man3/cexp2f.3 @@ -0,0 +1 @@ +.so man3/cexp2.3 diff --git a/man3/cexp2l.3 b/man3/cexp2l.3 new file mode 100644 index 0000000..759ad34 --- /dev/null +++ b/man3/cexp2l.3 @@ -0,0 +1 @@ +.so man3/cexp2.3 diff --git a/man3/cexpf.3 b/man3/cexpf.3 new file mode 100644 index 0000000..794d707 --- /dev/null +++ b/man3/cexpf.3 @@ -0,0 +1 @@ +.so man3/cexp.3 diff --git a/man3/cexpl.3 b/man3/cexpl.3 new file mode 100644 index 0000000..794d707 --- /dev/null +++ b/man3/cexpl.3 @@ -0,0 +1 @@ +.so man3/cexp.3 diff --git a/man3/cfgetispeed.3 b/man3/cfgetispeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/cfgetispeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfgetospeed.3 b/man3/cfgetospeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/cfgetospeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfmakeraw.3 b/man3/cfmakeraw.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/cfmakeraw.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfree.3 b/man3/cfree.3 new file mode 100644 index 0000000..a962b0b --- /dev/null +++ b/man3/cfree.3 @@ -0,0 +1,151 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH CFREE 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +cfree \- free allocated memory +.SH SYNOPSIS +.nf +.PP +.B "#include " +.PP +/* In SunOS 4 */ +.BI "int cfree(void *" ptr ); +.PP +/* In glibc or FreeBSD libcompat */ +.BI "void cfree(void *" ptr ); +.PP +/* In SCO OpenServer */ +.BI "void cfree(char *" ptr ", unsigned " num ", unsigned " size ); +.PP +/* In Solaris watchmalloc.so.1 */ +.BI "void cfree(void *" ptr ", size_t " nelem ", size_t " elsize ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR cfree (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +This function should never be used. +Use +.BR free (3) +instead. +Starting with version 2.26, it has been removed from glibc. +.SS 1-arg cfree +In glibc, the function +.BR cfree () +is a synonym for +.BR free (3), +"added for compatibility with SunOS". +.PP +Other systems have other functions with this name. +The declaration is sometimes in +.I +and sometimes in +.IR . +.SS 3-arg cfree +Some SCO and Solaris versions have malloc libraries with a 3-argument +.BR cfree (), +apparently as an analog to +.BR calloc (3). +.PP +If you need it while porting something, add +.PP +.in +4n +.EX +#define cfree(p, n, s) free((p)) +.EE +.in +.PP +to your file. +.PP +A frequently asked question is "Can I use +.BR free (3) +to free memory allocated with +.BR calloc (3), +or do I need +.BR cfree ()?" +Answer: use +.BR free (3). +.PP +An SCO manual writes: "The cfree routine is provided for compliance +to the iBCSe2 standard and simply calls free. +The num and size +arguments to cfree are not used." +.SH RETURN VALUE +The SunOS version of +.BR cfree () +(which is a synonym for +.BR free (3)) +returns 1 on success and 0 on failure. +In case of error, +.I errno +is set to +.BR EINVAL : +the value of +.I ptr +was not a pointer to a block previously allocated by +one of the routines in the +.BR malloc (3) +family. +.SH VERSIONS +The +.BR cfree () +function was removed +.\" commit 025b33ae84bb8f15b2748a1d8605dca453fce112 +from glibc in version 2.26. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR cfree () +T} Thread safety MT-Safe /* In glibc */ +.TE +.SH CONFORMING TO +The 3-argument version of +.BR cfree () +as used by SCO conforms to the iBCSe2 standard: +Intel386 Binary Compatibility Specification, Edition 2. +.SH SEE ALSO +.BR malloc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cfsetispeed.3 b/man3/cfsetispeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/cfsetispeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfsetospeed.3 b/man3/cfsetospeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/cfsetospeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cfsetspeed.3 b/man3/cfsetspeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/cfsetspeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/cimag.3 b/man3/cimag.3 new file mode 100644 index 0000000..d721274 --- /dev/null +++ b/man3/cimag.3 @@ -0,0 +1,62 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CIMAG 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +cimag, cimagf, cimagl \- get imaginary part of a complex number +.SH SYNOPSIS +.B #include +.PP +.BI "double cimag(double complex " z ");" +.br +.BI "float cimagf(float complex " z ");" +.br +.BI "long double cimagl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions return the imaginary part of the complex number +.IR z . +.PP +One has: +.PP +.nf + z = creal(z) + I * cimag(z) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR cimag (), +.BR cimagf (), +.BR cimagl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +gcc also supports __imag__. +That is a GNU extension. +.SH SEE ALSO +.BR cabs (3), +.BR creal (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cimagf.3 b/man3/cimagf.3 new file mode 100644 index 0000000..e806455 --- /dev/null +++ b/man3/cimagf.3 @@ -0,0 +1 @@ +.so man3/cimag.3 diff --git a/man3/cimagl.3 b/man3/cimagl.3 new file mode 100644 index 0000000..e806455 --- /dev/null +++ b/man3/cimagl.3 @@ -0,0 +1 @@ +.so man3/cimag.3 diff --git a/man3/clearenv.3 b/man3/clearenv.3 new file mode 100644 index 0000000..f79387e --- /dev/null +++ b/man3/clearenv.3 @@ -0,0 +1,146 @@ +.\" Copyright 2001 John Levon +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Additions, aeb, 2001-10-17. +.TH CLEARENV 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +clearenv \- clear the environment +.SH SYNOPSIS +.nf +.B #include +.PP +.B "int clearenv(void);" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR clearenv (): + /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.SH DESCRIPTION +The +.BR clearenv () +function clears the environment of all name-value +pairs and sets the value of the external variable +.I environ +to NULL. +After this call, new variables can be added to the environment using +.BR putenv (3) +and +.BR setenv (3). +.SH RETURN VALUE +The +.BR clearenv () +function returns zero on success, and a nonzero +value on failure. +.\" Most versions of UNIX return -1 on error, or do not even have errors. +.\" Glibc info and the Watcom C library document "a nonzero value". +.SH VERSIONS +Available since glibc 2.0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR clearenv () +T} Thread safety MT-Unsafe const:env +.TE +.sp 1 +.SH CONFORMING TO +Various UNIX variants (DG/UX, HP-UX, QNX, ...). +POSIX.9 (bindings for FORTRAN77). +POSIX.1-1996 did not accept +.BR clearenv () +and +.BR putenv (3), +but changed its mind and scheduled these functions for some +later issue of this standard (see \[sc]B.4.6.1). +However, POSIX.1-2001 +adds only +.BR putenv (3), +and rejected +.BR clearenv (). +.SH NOTES +On systems where +.BR clearenv () +is unavailable, the assignment +.PP +.in +4n +.EX +environ = NULL; +.EE +.in +.PP +will probably do. +.PP +The +.BR clearenv () +function may be useful in security-conscious applications that want to +precisely control the environment that is passed to programs +executed using +.BR exec (3). +The application would do this by first clearing the environment +and then adding select environment variables. +.PP +Note that the main effect of +.BR clearenv () +is to adjust the value of the pointer +.BR environ (7); +this function does not erase the contents of the buffers +containing the environment definitions. +.PP +The DG/UX and Tru64 man pages write: If +.I environ +has been modified by anything other than the +.BR putenv (3), +.BR getenv (3), +or +.BR clearenv () +functions, then +.BR clearenv () +will return an error and the process environment will remain unchanged. +.\" .LP +.\" HP-UX has a ENOMEM error return. +.SH SEE ALSO +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/clearerr.3 b/man3/clearerr.3 new file mode 100644 index 0000000..3a95cca --- /dev/null +++ b/man3/clearerr.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man3/clearerr_unlocked.3 b/man3/clearerr_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/clearerr_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/clnt_broadcast.3 b/man3/clnt_broadcast.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_broadcast.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_call.3 b/man3/clnt_call.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_call.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_control.3 b/man3/clnt_control.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_control.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_create.3 b/man3/clnt_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_destroy.3 b/man3/clnt_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_freeres.3 b/man3/clnt_freeres.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_freeres.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_geterr.3 b/man3/clnt_geterr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_geterr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_pcreateerror.3 b/man3/clnt_pcreateerror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_pcreateerror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_perrno.3 b/man3/clnt_perrno.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_perrno.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_perror.3 b/man3/clnt_perror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_perror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_spcreateerror.3 b/man3/clnt_spcreateerror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_spcreateerror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_sperrno.3 b/man3/clnt_sperrno.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_sperrno.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnt_sperror.3 b/man3/clnt_sperror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnt_sperror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clntraw_create.3 b/man3/clntraw_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clntraw_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clnttcp_create.3 b/man3/clnttcp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clnttcp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clntudp_bufcreate.3 b/man3/clntudp_bufcreate.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clntudp_bufcreate.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clntudp_create.3 b/man3/clntudp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/clntudp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/clock.3 b/man3/clock.3 new file mode 100644 index 0000000..8b60cca --- /dev/null +++ b/man3/clock.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 21:27:01 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 14 Jun 2002, Michael Kerrisk +.\" Added notes on differences from other UNIX systems with respect to +.\" waited-for children. +.TH CLOCK 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +clock \- determine processor time +.SH SYNOPSIS +.nf +.B #include +.PP +.B clock_t clock(void); +.fi +.SH DESCRIPTION +The +.BR clock () +function returns an approximation of processor time used by the program. +.SH RETURN VALUE +The value returned is the CPU time used so far as a +.IR clock_t ; +to get the number of seconds used, divide by +.BR CLOCKS_PER_SEC . +If the processor time used is not available or its value cannot +be represented, the function returns the value +.IR (clock_t)\ \-1 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR clock () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +XSI requires that +.B CLOCKS_PER_SEC +equals 1000000 independent +of the actual resolution. +.SH NOTES +The C standard allows for arbitrary values at the start of the program; +subtract the value returned from a call to +.BR clock () +at the start of the program to get maximum portability. +.PP +Note that the time can wrap around. +On a 32-bit system where +.B CLOCKS_PER_SEC +equals 1000000 this function will return the same +value approximately every 72 minutes. +.PP +On several other implementations, +the value returned by +.BR clock () +also includes the times of any children whose status has been +collected via +.BR wait (2) +(or another wait-type call). +Linux does not include the times of waited-for children in the +value returned by +.BR clock (). +.\" I have seen this behavior on Irix 6.3, and the OSF/1, HP/UX, and +.\" Solaris manual pages say that clock() also does this on those systems. +.\" POSIX.1-2001 doesn't explicitly allow this, nor is there an +.\" explicit prohibition. -- MTK +The +.BR times (2) +function, which explicitly returns (separate) information about the +caller and its children, may be preferable. +.PP +In glibc 2.17 and earlier, +.BR clock () +was implemented on top of +.BR times (2). +For improved accuracy, +since glibc 2.18, it is implemented on top of +.BR clock_gettime (2) +(using the +.BR CLOCK_PROCESS_CPUTIME_ID +clock). +.SH SEE ALSO +.BR clock_gettime (2), +.BR getrusage (2), +.BR times (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/clock_getcpuclockid.3 b/man3/clock_getcpuclockid.3 new file mode 100644 index 0000000..c5b7d85 --- /dev/null +++ b/man3/clock_getcpuclockid.3 @@ -0,0 +1,174 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH CLOCK_GETCPUCLOCKID 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +clock_getcpuclockid \- obtain ID of a process CPU-time clock +.SH SYNOPSIS +.B #include +.nf +.PP +.BI "int clock_getcpuclockid(pid_t " pid ", clockid_t *" clock_id ); +.fi +.PP +Link with \fI\-lrt\fP (only for glibc versions before 2.17). +.PP +.ad l +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR clock_getcpuclockid (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +The +.BR clock_getcpuclockid () +function obtains the ID of the CPU-time clock of the process whose ID is +.IR pid , +and returns it in the location pointed to by +.IR clock_id . +If +.I pid +is zero, then the clock ID of the CPU-time clock +of the calling process is returned. +.SH RETURN VALUE +On success, +.BR clock_getcpuclockid () +returns 0; +on error, it returns one of the positive error numbers listed in ERRORS. +.SH ERRORS +.TP +.B ENOSYS +The kernel does not support obtaining the per-process +CPU-time clock of another process, and +.I pid +does not specify the calling process. +.TP +.B EPERM +The caller does not have permission to access +the CPU-time clock of the process specified by +.IR pid . +(Specified in POSIX.1-2001; +does not occur on Linux unless the kernel does not support +obtaining the per-process CPU-time clock of another process.) +.TP +.B ESRCH +There is no process with the ID +.IR pid . +.SH VERSIONS +The +.BR clock_getcpuclockid () +function is available in glibc since version 2.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR clock_getcpuclockid () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +Calling +.BR clock_gettime (2) +with the clock ID obtained by a call to +.BR clock_getcpuclockid () +with a +.I pid +of 0, +is the same as using the clock ID +.BR CLOCK_PROCESS_CPUTIME_ID . +.SH EXAMPLE +The example program below obtains the +CPU-time clock ID of the process whose ID is given on the command line, +and then uses +.BR clock_gettime (2) +to obtain the time on that clock. +An example run is the following: +.PP +.in +4n +.EX +.RB "$" " ./a.out 1" " # Show CPU clock of init process" +CPU-time clock for PID 1 is 2.213466748 seconds +.EE +.in +.SS Program source +\& +.EX +#define _XOPEN_SOURCE 600 +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + clockid_t clockid; + struct timespec ts; + + if (argc != 2) { + fprintf(stderr, "%s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + if (clock_getcpuclockid(atoi(argv[1]), &clockid) != 0) { + perror("clock_getcpuclockid"); + exit(EXIT_FAILURE); + } + + if (clock_gettime(clockid, &ts) == \-1) { + perror("clock_gettime"); + exit(EXIT_FAILURE); + } + + printf("CPU-time clock for PID %s is %ld.%09ld seconds\\n", + argv[1], (long) ts.tv_sec, (long) ts.tv_nsec); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR clock_getres (2), +.BR timer_create (2), +.BR pthread_getcpuclockid (3), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/clock_getres.3 b/man3/clock_getres.3 new file mode 100644 index 0000000..5b14883 --- /dev/null +++ b/man3/clock_getres.3 @@ -0,0 +1,3 @@ +.so man2/clock_getres.2 +.\" This link provided in Section 3 because, by historical accident, +.\" the page was originally in Section 3 -- mtk, Feb 2009 diff --git a/man3/clock_gettime.3 b/man3/clock_gettime.3 new file mode 100644 index 0000000..5b14883 --- /dev/null +++ b/man3/clock_gettime.3 @@ -0,0 +1,3 @@ +.so man2/clock_getres.2 +.\" This link provided in Section 3 because, by historical accident, +.\" the page was originally in Section 3 -- mtk, Feb 2009 diff --git a/man3/clock_settime.3 b/man3/clock_settime.3 new file mode 100644 index 0000000..5b14883 --- /dev/null +++ b/man3/clock_settime.3 @@ -0,0 +1,3 @@ +.so man2/clock_getres.2 +.\" This link provided in Section 3 because, by historical accident, +.\" the page was originally in Section 3 -- mtk, Feb 2009 diff --git a/man3/clog.3 b/man3/clog.3 new file mode 100644 index 0000000..f3a3fcb --- /dev/null +++ b/man3/clog.3 @@ -0,0 +1,75 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CLOG 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +clog, clogf, clogl \- natural logarithm of a complex number +.SH SYNOPSIS +.B #include +.PP +.BI "double complex clog(double complex " z ); +.br +.BI "float complex clogf(float complex " z ); +.br +.BI "long double complex clogl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex natural logarithm of +.IR z , +with a branch cut along the negative real axis. +.PP +The logarithm +.BR clog () +is the inverse function of the exponential +.BR cexp (3). +Thus, if \fIy\ =\ clog(z)\fP, then \fIz\ =\ cexp(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi,pi]. +.PP +One has: +.PP +.nf + clog(z) = log(cabs(z)) + I * carg(z) +.fi +.PP +Note that +.I z +close to zero will cause an overflow. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR clog (), +.BR clogf (), +.BR clogl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog10 (3), +.BR clog2 (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/clog10.3 b/man3/clog10.3 new file mode 100644 index 0000000..8aaef9e --- /dev/null +++ b/man3/clog10.3 @@ -0,0 +1,74 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CLOG10 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +clog10, clog10f, clog10l \- base-10 logarithm of a complex number +.SH SYNOPSIS +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.PP +.BI "double complex clog10(double complex " z ); +.br +.BI "float complex clog10f(float complex " z ); +.br +.BI "long double complex clog10l(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +The call +.I clog10(z) +is equivalent to: +.PP + clog(z)/log(10) +.PP +or equally: +.PP + log10(cabs(c)) + I * carg(c) / log(10) +.PP +The other functions perform the same task for +.I float +and +.IR "long double" . +.PP +Note that +.I z +close to zero will cause an overflow. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR clog10 (), +.BR clog10f (), +.BR clog10l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are GNU extensions. +The identifiers are reserved for future use in C99 and C11. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog (3), +.BR clog2 (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/clog10f.3 b/man3/clog10f.3 new file mode 100644 index 0000000..5840d54 --- /dev/null +++ b/man3/clog10f.3 @@ -0,0 +1 @@ +.so man3/clog10.3 diff --git a/man3/clog10l.3 b/man3/clog10l.3 new file mode 100644 index 0000000..5840d54 --- /dev/null +++ b/man3/clog10l.3 @@ -0,0 +1 @@ +.so man3/clog10.3 diff --git a/man3/clog2.3 b/man3/clog2.3 new file mode 100644 index 0000000..4e5ccc7 --- /dev/null +++ b/man3/clog2.3 @@ -0,0 +1,53 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CLOG2 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +clog2, clog2f, clog2l \- base-2 logarithm of a complex number +.SH SYNOPSIS +.B #include +.PP +.BI "double complex clog2(double complex " z ); +.br +.BI "float complex clog2f(float complex " z ); +.br +.BI "long double complex clog2l(long double complex " z ); +.\" .PP +.\" Link with \fI\-lm\fP. +.SH DESCRIPTION +The call +.I clog2(z) +is equivalent to +.IR clog(z)/log(2) . +.PP +The other functions perform the same task for +.I float +and +.IR "long double" . +.PP +Note that +.I z +close to zero will cause an overflow. +.SH CONFORMING TO +These function names are reserved for future use in C99. +.SH AVAILABILITY +Not yet in glibc, as at version 2.19. +.\" But reserved in NAMESPACE. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog (3), +.BR clog10 (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/clog2f.3 b/man3/clog2f.3 new file mode 100644 index 0000000..23d6834 --- /dev/null +++ b/man3/clog2f.3 @@ -0,0 +1 @@ +.so man3/clog2.3 diff --git a/man3/clog2l.3 b/man3/clog2l.3 new file mode 100644 index 0000000..23d6834 --- /dev/null +++ b/man3/clog2l.3 @@ -0,0 +1 @@ +.so man3/clog2.3 diff --git a/man3/clogf.3 b/man3/clogf.3 new file mode 100644 index 0000000..3cd9533 --- /dev/null +++ b/man3/clogf.3 @@ -0,0 +1 @@ +.so man3/clog.3 diff --git a/man3/clogl.3 b/man3/clogl.3 new file mode 100644 index 0000000..3cd9533 --- /dev/null +++ b/man3/clogl.3 @@ -0,0 +1 @@ +.so man3/clog.3 diff --git a/man3/closedir.3 b/man3/closedir.3 new file mode 100644 index 0000000..c34d1d6 --- /dev/null +++ b/man3/closedir.3 @@ -0,0 +1,97 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:25:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH CLOSEDIR 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +closedir \- close a directory +.SH SYNOPSIS +.nf +.B #include +.PP +.B #include +.PP +.BI "int closedir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR closedir () +function closes the directory stream associated with +.IR dirp . +A successful call to +.BR closedir () +also closes the underlying file descriptor associated with +.IR dirp . +The directory stream descriptor +.I dirp +is not available +after this call. +.SH RETURN VALUE +The +.BR closedir () +function returns 0 on success. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor +.IR dirp . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR closedir () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH SEE ALSO +.BR close (2), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/closelog.3 b/man3/closelog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man3/closelog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man3/cmsg.3 b/man3/cmsg.3 new file mode 100644 index 0000000..b2d107f --- /dev/null +++ b/man3/cmsg.3 @@ -0,0 +1,249 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ +.TH CMSG 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data +.SH SYNOPSIS +.B #include +.PP +.BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); +.br +.BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg ); +.br +.BI "size_t CMSG_ALIGN(size_t " length ); +.br +.BI "size_t CMSG_SPACE(size_t " length ); +.br +.BI "size_t CMSG_LEN(size_t " length ); +.br +.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); +.PP +.SH DESCRIPTION +These macros are used to create and access control messages (also called +ancillary data) that are not a part of the socket payload. +This control information may +include the interface the packet was received on, various rarely used header +fields, an extended error description, a set of file descriptors or UNIX +credentials. +For instance, control messages can be used to send +additional header fields such as IP options. +Ancillary data is sent by calling +.BR sendmsg (2) +and received by calling +.BR recvmsg (2). +See their manual pages for more information. +.PP +Ancillary data is a sequence of +.I cmsghdr +structures with appended data. +See the specific protocol man pages for the available control message types. +The maximum ancillary buffer size allowed per socket can be set using +.IR /proc/sys/net/core/optmem_max ; +see +.BR socket (7). +.PP +The +.I cmsghdr +structure is defined as follows: +.PP +.in +4n +.EX +struct cmsghdr { + size_t cmsg_len; /* Data byte count, including header + (type is socklen_t in POSIX) */ + int cmsg_level; /* Originating protocol */ + int cmsg_type; /* Protocol-specific type */ +/* followed by + unsigned char cmsg_data[]; */ +}; +.EE +.in +.PP +The sequence of +.I cmsghdr +structures should never be accessed directly. +Instead, use only the following macros: +.IP * 3 +.BR CMSG_FIRSTHDR () +returns a pointer to the first +.I cmsghdr +in the ancillary +data buffer associated with the passed +.IR msghdr . +.IP * +.BR CMSG_NXTHDR () +returns the next valid +.I cmsghdr +after the passed +.IR cmsghdr . +It returns NULL when there isn't enough space left in the buffer. +.IP * +.BR CMSG_ALIGN (), +given a length, returns it including the required alignment. +This is a +constant expression. +.IP * +.BR CMSG_SPACE () +returns the number of bytes an ancillary element with payload of the +passed data length occupies. +This is a constant expression. +.IP * +.BR CMSG_DATA () +returns a pointer to the data portion of a +.IR cmsghdr . +.IP * +.BR CMSG_LEN () +returns the value to store in the +.I cmsg_len +member of the +.I cmsghdr +structure, taking into account any necessary +alignment. +It takes the data length as an argument. +This is a constant +expression. +.PP +To create ancillary data, first initialize the +.I msg_controllen +member of the +.I msghdr +with the length of the control message buffer. +Use +.BR CMSG_FIRSTHDR () +on the +.I msghdr +to get the first control message and +.BR CMSG_NXTHDR () +to get all subsequent ones. +In each control message, initialize +.I cmsg_len +(with +.BR CMSG_LEN ()), +the other +.I cmsghdr +header fields, and the data portion using +.BR CMSG_DATA (). +Finally, the +.I msg_controllen +field of the +.I msghdr +should be set to the sum of the +.BR CMSG_SPACE () +of the length of +all control messages in the buffer. +For more information on the +.IR msghdr , +see +.BR recvmsg (2). +.PP +When the control message buffer is too short to store all messages, the +.B MSG_CTRUNC +flag is set in the +.I msg_flags +member of the +.IR msghdr . +.SH CONFORMING TO +This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, +the IPv6 advanced API described in RFC\ 2292 and SUSv2. +.BR CMSG_ALIGN () +is a Linux extension. +.SH NOTES +For portability, ancillary data should be accessed using only the macros +described here. +.BR CMSG_ALIGN () +is a Linux extension and should not be used in portable programs. +.PP +In Linux, +.BR CMSG_LEN (), +.BR CMSG_DATA (), +and +.BR CMSG_ALIGN () +are constant expressions (assuming their argument is constant); +this could be used to declare the size of global +variables. +This may not be portable, however. +.SH EXAMPLE +This code looks for the +.B IP_TTL +option in a received ancillary buffer: +.PP +.in +4n +.EX +struct msghdr msgh; +struct cmsghdr *cmsg; +int *ttlptr; +int received_ttl; + +/* Receive auxiliary data in msgh */ + +for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL; + cmsg = CMSG_NXTHDR(&msgh, cmsg)) { + if (cmsg\->cmsg_level == IPPROTO_IP + && cmsg\->cmsg_type == IP_TTL) { + ttlptr = (int *) CMSG_DATA(cmsg); + received_ttl = *ttlptr; + break; + } +} + +if (cmsg == NULL) { + /* Error: IP_TTL not enabled or small buffer or I/O error */ +} +.EE +.in +.PP +The code below passes an array of file descriptors over a +UNIX domain socket using +.BR SCM_RIGHTS : +.PP +.in +4n +.EX +struct msghdr msg = { 0 }; +struct cmsghdr *cmsg; +int myfds[NUM_FD]; /* Contains the file descriptors to pass */ +int *fdptr; +char iobuf[1]; +struct iovec io = { + .iov_base = iobuf, + .iov_len = sizeof(iobuf) +}; +union { /* Ancillary data buffer, wrapped in a union + in order to ensure it is suitably aligned */ + char buf[CMSG_SPACE(sizeof(myfds))]; + struct cmsghdr align; +} u; + +msg.msg_iov = &io; +msg.msg_iovlen = 1; +msg.msg_control = u.buf; +msg.msg_controllen = sizeof(u.buf); +cmsg = CMSG_FIRSTHDR(&msg); +cmsg\->cmsg_level = SOL_SOCKET; +cmsg\->cmsg_type = SCM_RIGHTS; +cmsg\->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD); +fdptr = (int *) CMSG_DATA(cmsg); /* Initialize the payload */ +memcpy(fdptr, myfds, NUM_FD * sizeof(int)); +.EE +.in +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2) +.PP +RFC\ 2292 +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/confstr.3 b/man3/confstr.3 new file mode 100644 index 0000000..08f8b74 --- /dev/null +++ b/man3/confstr.3 @@ -0,0 +1,175 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 19:53:02 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" FIXME Many more values for 'name' are supported, some of which +.\" are documented under 'info confstr'. +.\" See for the rest. +.\" These should all be added to this page. +.\" See also the POSIX.1-2001 specification of confstr() +.\" +.TH CONFSTR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +confstr \- get configuration dependent string variables +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t confstr(int " "name" ", char *" buf ", size_t " len ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR confstr (): +_POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE +.SH DESCRIPTION +.BR confstr () +gets the value of configuration-dependent string variables. +.PP +The +.I name +argument is the system variable to be queried. +The following variables are supported: +.TP +.BR _CS_GNU_LIBC_VERSION " (GNU C library only; since glibc 2.3.2)" +A string which identifies the GNU C library version on this system +(e.g., "glibc 2.3.4"). +.TP +.BR _CS_GNU_LIBPTHREAD_VERSION " (GNU C library only; since glibc 2.3.2)" +A string which identifies the POSIX implementation supplied by this +C library (e.g., "NPTL 2.3.4" or "linuxthreads-0.10"). +.TP +.B _CS_PATH +A value for the +.B PATH +variable which indicates where all the POSIX.2 standard utilities can +be found. +.PP +If +.I buf +is not NULL and +.I len +is not zero, +.BR confstr () +copies the value of the string to +.I buf +truncated to +.I len \- 1 +bytes if necessary, with a null byte (\(aq\\0\(aq) as terminator. +This can be detected by comparing the return value of +.BR confstr () +against +.IR len . +.PP +If +.I len +is zero and +.I buf +is NULL, +.BR confstr () +just returns the value as defined below. +.SH RETURN VALUE +If +.I name +is a valid configuration variable, +.BR confstr () +returns the number of bytes (including the terminating null byte) +that would be required to hold the entire value of that variable. +This value may be greater than +.IR len , +which means that the value in +.I buf +is truncated. +.PP +If +.I name +is a valid configuration variable, +but that variable does not have a value, then +.BR confstr () +returns 0. +If +.I name +does not correspond to a valid configuration variable, +.BR confstr () +returns 0, and +.I errno +is set to +.BR EINVAL . +.SH ERRORS +.TP +.B EINVAL +The value of +.I name +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR confstr () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +The following code fragment determines the path where to find +the POSIX.2 system utilities: +.PP +.in +4n +.EX +char *pathbuf; +size_t n; + +n = confstr(_CS_PATH, NULL, (size_t) 0); +pathbuf = malloc(n); +if (pathbuf == NULL) + abort(); +confstr(_CS_PATH, pathbuf, n); +.EE +.in +.SH SEE ALSO +.BR getconf (1), +.BR sh (1), +.BR exec (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR sysconf (3), +.BR system (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/conj.3 b/man3/conj.3 new file mode 100644 index 0000000..1fe6bf3 --- /dev/null +++ b/man3/conj.3 @@ -0,0 +1,60 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CONJ 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +conj, conjf, conjl \- calculate the complex conjugate +.SH SYNOPSIS +.B #include +.PP +.BI "double complex conj(double complex " z ); +.br +.BI "float complex conjf(float complex " z ); +.br +.BI "long double complex conjl(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions return the complex conjugate value of +.IR z . +That is the value obtained by changing the sign of the imaginary part. +.PP +One has: +.PP +.nf + cabs(z) = csqrt(z * conj(z)) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR conj (), +.BR conjf (), +.BR conjl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR csqrt (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/conjf.3 b/man3/conjf.3 new file mode 100644 index 0000000..ef6093f --- /dev/null +++ b/man3/conjf.3 @@ -0,0 +1 @@ +.so man3/conj.3 diff --git a/man3/conjl.3 b/man3/conjl.3 new file mode 100644 index 0000000..ef6093f --- /dev/null +++ b/man3/conjl.3 @@ -0,0 +1 @@ +.so man3/conj.3 diff --git a/man3/copysign.3 b/man3/copysign.3 new file mode 100644 index 0000000..85f0abc --- /dev/null +++ b/man3/copysign.3 @@ -0,0 +1,118 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.TH COPYSIGN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +copysign, copysignf, copysignl \- copy sign of a number +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double copysign(double " x ", double " y ); +.BI "float copysignf(float " x ", float " y ); +.BI "long double copysignl(long double " x ", long double " y ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR copysign (), +.BR copysignf (), +.BR copysignl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return a value whose absolute value matches that of +.IR x , +but whose sign bit matches that of +.IR y . +.PP +For example, +.I "copysign(42.0,\ \-1.0)" +and +.I "copysign(\-42.0, \-1.0)" +both return \-42.0. +.SH RETURN VALUE +On success, these functions return a value whose magnitude is taken from +.I x +and whose sign is taken from +.IR y . +.PP +If +.I x +is a NaN, +a NaN with the sign bit of +.I y +is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw36 lb lb +l l l. +Interface Attribute Value +T{ +.BR copysign (), +.BR copysignf (), +.BR copysignl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.\" 4.3BSD. +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH NOTES +On architectures where the floating-point formats are not IEEE 754 compliant, +these +functions may treat a negative zero as positive. +.SH SEE ALSO +.BR signbit (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/copysignf.3 b/man3/copysignf.3 new file mode 100644 index 0000000..46ef5e6 --- /dev/null +++ b/man3/copysignf.3 @@ -0,0 +1 @@ +.so man3/copysign.3 diff --git a/man3/copysignl.3 b/man3/copysignl.3 new file mode 100644 index 0000000..46ef5e6 --- /dev/null +++ b/man3/copysignl.3 @@ -0,0 +1 @@ +.so man3/copysign.3 diff --git a/man3/cos.3 b/man3/cos.3 new file mode 100644 index 0000000..0404577 --- /dev/null +++ b/man3/cos.3 @@ -0,0 +1,143 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH COS 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +cos, cosf, cosl \- cosine function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double cos(double " x ); +.BI "float cosf(float " x ); +.BI "long double cosl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR cosf (), +.BR cosl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the cosine of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the cosine of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.BR EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR cos (), +.BR cosf (), +.BR cosl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +Before version 2.10, the glibc implementation did not set +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6780 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR ccos (3), +.BR sin (3), +.BR sincos (3), +.BR tan (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cosf.3 b/man3/cosf.3 new file mode 100644 index 0000000..9abaea4 --- /dev/null +++ b/man3/cosf.3 @@ -0,0 +1 @@ +.so man3/cos.3 diff --git a/man3/cosh.3 b/man3/cosh.3 new file mode 100644 index 0000000..0e8abab --- /dev/null +++ b/man3/cosh.3 @@ -0,0 +1,153 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-06-08 by aeb +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH COSH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +cosh, coshf, coshl \- hyperbolic cosine function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double cosh(double " x ); +.BI "float coshf(float " x ); +.BI "long double coshl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR coshf (), +.BR coshl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the hyperbolic cosine of +.IR x , +which is defined mathematically as: +.PP +.nf + cosh(x) = (exp(x) + exp(\-x)) / 2 +.fi +.SH RETURN VALUE +On success, these functions return the hyperbolic cosine of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 or \-0, 1 is returned. +.PP +If +.I x +is positive infinity or negative infinity, +positive infinity is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR cosh (), +.BR coshf (), +.BR coshl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +In glibc version 2.3.4 and earlier, +an overflow floating-point +.RB ( FE_OVERFLOW ) +exception is not raised when an overflow occurs. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR ccos (3), +.BR sinh (3), +.BR tanh (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/coshf.3 b/man3/coshf.3 new file mode 100644 index 0000000..e9bab10 --- /dev/null +++ b/man3/coshf.3 @@ -0,0 +1 @@ +.so man3/cosh.3 diff --git a/man3/coshl.3 b/man3/coshl.3 new file mode 100644 index 0000000..e9bab10 --- /dev/null +++ b/man3/coshl.3 @@ -0,0 +1 @@ +.so man3/cosh.3 diff --git a/man3/cosl.3 b/man3/cosl.3 new file mode 100644 index 0000000..9abaea4 --- /dev/null +++ b/man3/cosl.3 @@ -0,0 +1 @@ +.so man3/cos.3 diff --git a/man3/cpow.3 b/man3/cpow.3 new file mode 100644 index 0000000..e7f6ec0 --- /dev/null +++ b/man3/cpow.3 @@ -0,0 +1,59 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CPOW 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +cpow, cpowf, cpowl \- complex power function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double complex cpow(double complex " x ", complex double " z ");" +.BI "float complex cpowf(float complex " x ", complex float " z ");" +.BI "long double complex cpowl(long double complex " x , +.BI " complex long double " z ");" +.PP +Link with \fI\-lm\fP. +.fi +.SH DESCRIPTION +These functions calculate +.I x +raised to the power +.IR z +(with a branch cut for +.I x +along the negative real axis.) +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR cpow (), +.BR cpowf (), +.BR cpowl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR pow (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cpowf.3 b/man3/cpowf.3 new file mode 100644 index 0000000..7577fcd --- /dev/null +++ b/man3/cpowf.3 @@ -0,0 +1 @@ +.so man3/cpow.3 diff --git a/man3/cpowl.3 b/man3/cpowl.3 new file mode 100644 index 0000000..7577fcd --- /dev/null +++ b/man3/cpowl.3 @@ -0,0 +1 @@ +.so man3/cpow.3 diff --git a/man3/cproj.3 b/man3/cproj.3 new file mode 100644 index 0000000..084e866 --- /dev/null +++ b/man3/cproj.3 @@ -0,0 +1,65 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CPROJ 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +cproj, cprojf, cprojl \- project into Riemann Sphere +.SH SYNOPSIS +.B #include +.PP +.BI "double complex cproj(double complex " z ");" +.br +.BI "float complex cprojf(float complex " z ");" +.br +.BI "long double complex cprojl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions project a point in the plane onto the surface of a +Riemann Sphere, the one-point compactification of the complex plane. +Each finite point +.I z +projects to +.I z +itself. +Every complex infinite value is projected to a single infinite value, +namely to positive infinity on the real axis. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR cproj (), +.BR cprojf (), +.BR cprojl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +In glibc 2.11 and earlier, the implementation does something different +(a +.I stereographic +projection onto a Riemann Sphere). +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=10401 +.SH SEE ALSO +.BR cabs (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/cprojf.3 b/man3/cprojf.3 new file mode 100644 index 0000000..0a3f31c --- /dev/null +++ b/man3/cprojf.3 @@ -0,0 +1 @@ +.so man3/cproj.3 diff --git a/man3/cprojl.3 b/man3/cprojl.3 new file mode 100644 index 0000000..0a3f31c --- /dev/null +++ b/man3/cprojl.3 @@ -0,0 +1 @@ +.so man3/cproj.3 diff --git a/man3/creal.3 b/man3/creal.3 new file mode 100644 index 0000000..16ace7d --- /dev/null +++ b/man3/creal.3 @@ -0,0 +1,62 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CREAL 3 2015-04-19 "" "Linux Programmer's Manual" +.SH NAME +creal, crealf, creall \- get real part of a complex number +.SH SYNOPSIS +.B #include +.PP +.BI "double creal(double complex " z ); +.br +.BI "float crealf(float complex " z ); +.br +.BI "long double creall(long double complex " z ); +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions return the real part of the complex number +.IR z . +.PP +One has: +.PP +.nf + z = creal(z) + I * cimag(z) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR creal (), +.BR crealf (), +.BR creall () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The gcc supports also __real__. +That is a GNU extension. +.SH SEE ALSO +.BR cabs (3), +.BR cimag (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/crealf.3 b/man3/crealf.3 new file mode 100644 index 0000000..4289f71 --- /dev/null +++ b/man3/crealf.3 @@ -0,0 +1 @@ +.so man3/creal.3 diff --git a/man3/creall.3 b/man3/creall.3 new file mode 100644 index 0000000..4289f71 --- /dev/null +++ b/man3/creall.3 @@ -0,0 +1 @@ +.so man3/creal.3 diff --git a/man3/crypt.3 b/man3/crypt.3 new file mode 100644 index 0000000..c742b0c --- /dev/null +++ b/man3/crypt.3 @@ -0,0 +1,289 @@ +.\" Michael Haardt (michael@cantor.informatik.rwth.aachen.de) +.\" Sat Sep 3 22:00:30 MET DST 1994 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Sun Feb 19 21:32:25 1995, faith@cs.unc.edu edited details away +.\" +.\" TO DO: This manual page should go more into detail how DES is perturbed, +.\" which string will be encrypted, and what determines the repetition factor. +.\" Is a simple repetition using ECB used, or something more advanced? I hope +.\" the presented explanations are at least better than nothing, but by no +.\" means enough. +.\" +.\" added _XOPEN_SOURCE, aeb, 970705 +.\" added GNU MD5 stuff, aeb, 011223 +.\" +.TH CRYPT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +crypt, crypt_r \- password and data encryption +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "char *crypt(const char *" key ", const char *" salt ); + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "char *crypt_r(const char *" key ", const char *" salt , +.BI " struct crypt_data *" data ); +.fi +.PP +Link with \fI\-lcrypt\fP. +.SH DESCRIPTION +.BR crypt () +is the password encryption function. +It is based on the Data Encryption +Standard algorithm with variations intended (among other things) to +discourage use of hardware implementations of a key search. +.PP +.I key +is a user's typed password. +.PP +.I salt +is a two-character string chosen from the set +[\fBa\-zA\-Z0\-9./\fP]. +This string is used to +perturb the algorithm in one of 4096 different ways. +.PP +By taking the lowest 7 bits of each of the first eight characters of the +.IR key , +a 56-bit key is obtained. +This 56-bit key is used to encrypt repeatedly a +constant string (usually a string consisting of all zeros). +The returned +value points to the encrypted password, a series of 13 printable ASCII +characters (the first two characters represent the salt itself). +The return value points to static data whose content is +overwritten by each call. +.PP +Warning: the key space consists of +.if t 2\s-2\u56\s0\d +.if n 2**56 +equal 7.2e16 possible values. +Exhaustive searches of this key space are +possible using massively parallel computers. +Software, such as +.BR crack (1), +is available which will search the portion of this key space that is +generally used by humans for passwords. +Hence, password selection should, +at minimum, avoid common words and names. +The use of a +.BR passwd (1) +program that checks for crackable passwords during the selection process is +recommended. +.PP +The DES algorithm itself has a few quirks which make the use of the +.BR crypt () +interface a very poor choice for anything other than password +authentication. +If you are planning on using the +.BR crypt () +interface for a cryptography project, don't do it: get a good book on +encryption and one of the widely available DES libraries. +.PP +.BR crypt_r () +is a reentrant version of +.BR crypt (). +The structure pointed to by +.I data +is used to store result data and bookkeeping information. +Other than allocating it, +the only thing that the caller should do with this structure is to set +.I data->initialized +to zero before the first call to +.BR crypt_r (). +.SH RETURN VALUE +On success, a pointer to the encrypted password is returned. +On error, NULL is returned. +.SH ERRORS +.TP +.B EINVAL +.I salt +has the wrong format. +.TP +.B ENOSYS +The +.BR crypt () +function was not implemented, probably because of U.S.A. export restrictions. +.\" This level of detail is not necessary in this man page. . . +.\" .PP +.\" When encrypting a plain text P using DES with the key K results in the +.\" encrypted text C, then the complementary plain text P' being encrypted +.\" using the complementary key K' will result in the complementary encrypted +.\" text C'. +.\" .PP +.\" Weak keys are keys which stay invariant under the DES key transformation. +.\" The four known weak keys 0101010101010101, fefefefefefefefe, +.\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided. +.\" .PP +.\" There are six known half weak key pairs, which keys lead to the same +.\" encrypted data. Keys which are part of such key clusters should be +.\" avoided. +.\" Sorry, I could not find out what they are. +.\"" +.\" .PP +.\" Heavily redundant data causes trouble with DES encryption, when used in the +.\" .I codebook +.\" mode that +.\" .BR crypt () +.\" implements. The +.\" .BR crypt () +.\" interface should be used only for its intended purpose of password +.\" verification, and should not be used as part of a data encryption tool. +.\" .PP +.\" The first and last three output bits of the fourth S-box can be +.\" represented as function of their input bits. Empiric studies have +.\" shown that S-boxes partially compute the same output for similar input. +.\" It is suspected that this may contain a back door which could allow the +.\" NSA to decrypt DES encrypted data. +.\" .PP +.\" Making encrypted data computed using crypt() publicly available has +.\" to be considered insecure for the given reasons. +.TP +.B EPERM +.I /proc/sys/crypto/fips_enabled +has a nonzero value, +and an attempt was made to use a weak encryption type, such as DES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR crypt () +T} Thread safety MT-Unsafe race:crypt +T{ +.BR crypt_r () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR crypt (): +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.BR crypt_r () +is a GNU extension. +.SH NOTES +.SS Glibc notes +The glibc2 version of this function supports additional +encryption algorithms. +.PP +If +.I salt +is a character string starting with the characters "$\fIid\fP$" +followed by a string optionally terminated by "$", +then the result has the form: +.RS +.PP +$\fIid\fP$\fIsalt\fP$\fIencrypted\fP +.PP +.RE +.I id +identifies the encryption method used instead of DES and this then determines how the rest +of the password string is interpreted. +The following values of +.I id +are supported: +.RS +.TS +l l. +ID | Method +_ +1 | MD5 +2a | Blowfish (not in mainline glibc; added in some + | Linux distributions) +.\" openSUSE has Blowfish, but AFAICS, this option is not supported +.\" natively by glibc -- mtk, Jul 08 +.\" +.\" md5 | Sun MD5 +.\" glibc doesn't appear to natively support Sun MD5; I don't know +.\" if any distros add the support. +5 | SHA-256 (since glibc 2.7) +6 | SHA-512 (since glibc 2.7) +.TE +.RE +.PP +Thus, $5$\fIsalt\fP$\fIencrypted\fP and $6$\fIsalt\fP$\fIencrypted\fP +contain the password encrypted with, respectively, functions +based on SHA-256 and SHA-512. +.PP +"\fIsalt\fP" stands for the up to 16 characters +following "$\fIid\fP$" in the salt. +The "\fIencrypted\fP" +part of the password string is the actual computed password. +The size of this string is fixed: +.TS +l l. +MD5 | 22 characters +SHA-256 | 43 characters +SHA-512 | 86 characters +.TE +.sp 1 +The characters in "\fIsalt\fP" and "\fIencrypted\fP" are drawn from the set +[\fBa\-zA\-Z0\-9./\fP]. +In the MD5 and SHA implementations the entire +.I key +is significant (instead of only the first +8 bytes in DES). +.PP +Since glibc 2.7, +.\" glibc commit 9425cb9eea6a62fc21d99aafe8a60f752b934b05 +the SHA-256 and SHA-512 implementations support a user-supplied number of +hashing rounds, defaulting to 5000. +If the "$\fIid\fP$" characters in the salt are +followed by "rounds=\fIxxx\fP$", where \fIxxx\fP is an integer, then the +result has the form +.RS +.PP +$\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIencrypted\fP +.PP +.RE +where \fIyyy\fP is the number of hashing rounds actually used. +The number of rounds actually used is 1000 if +.I xxx +is less than +1000, 999999999 if +.I xxx +is greater than 999999999, and +is equal to +.I xxx +otherwise. +.SH SEE ALSO +.BR login (1), +.BR passwd (1), +.BR encrypt (3), +.BR getpass (3), +.BR passwd (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/crypt_r.3 b/man3/crypt_r.3 new file mode 100644 index 0000000..3944ebd --- /dev/null +++ b/man3/crypt_r.3 @@ -0,0 +1 @@ +.so man3/crypt.3 diff --git a/man3/csin.3 b/man3/csin.3 new file mode 100644 index 0000000..5243520 --- /dev/null +++ b/man3/csin.3 @@ -0,0 +1,62 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CSIN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +csin, csinf, csinl \- complex sine function +.SH SYNOPSIS +.B #include +.PP +.BI "double complex csin(double complex " z ");" +.br +.BI "float complex csinf(float complex " z ); +.br +.BI "long double complex csinl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex sine of +.IR z . +.PP +The complex sine function is defined as: +.PP +.nf + csin(z) = (exp(i * z) \- exp(\-i * z)) / (2 * i) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR csin (), +.BR csinf (), +.BR csinl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR casin (3), +.BR ccos (3), +.BR ctan (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/csinf.3 b/man3/csinf.3 new file mode 100644 index 0000000..1ed2a3e --- /dev/null +++ b/man3/csinf.3 @@ -0,0 +1 @@ +.so man3/csin.3 diff --git a/man3/csinh.3 b/man3/csinh.3 new file mode 100644 index 0000000..b84cd9e --- /dev/null +++ b/man3/csinh.3 @@ -0,0 +1,62 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CSINH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +csinh, csinhf, csinhl \- complex hyperbolic sine +.SH SYNOPSIS +.B #include +.PP +.BI "double complex csinh(double complex " z ");" +.br +.BI "float complex csinhf(float complex " z ");" +.br +.BI "long double complex csinhl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex hyperbolic sine of +.IR z . +.PP +The complex hyperbolic sine function is defined as: +.PP +.nf + csinh(z) = (exp(z)\-exp(\-z))/2 +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR csinh (), +.BR csinhf (), +.BR csinhl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR casinh (3), +.BR ccosh (3), +.BR ctanh (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/csinhf.3 b/man3/csinhf.3 new file mode 100644 index 0000000..9f6d66f --- /dev/null +++ b/man3/csinhf.3 @@ -0,0 +1 @@ +.so man3/csinh.3 diff --git a/man3/csinhl.3 b/man3/csinhl.3 new file mode 100644 index 0000000..9f6d66f --- /dev/null +++ b/man3/csinhl.3 @@ -0,0 +1 @@ +.so man3/csinh.3 diff --git a/man3/csinl.3 b/man3/csinl.3 new file mode 100644 index 0000000..1ed2a3e --- /dev/null +++ b/man3/csinl.3 @@ -0,0 +1 @@ +.so man3/csin.3 diff --git a/man3/csqrt.3 b/man3/csqrt.3 new file mode 100644 index 0000000..958a2b9 --- /dev/null +++ b/man3/csqrt.3 @@ -0,0 +1,58 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CSQRT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +csqrt, csqrtf, csqrtl \- complex square root +.SH SYNOPSIS +.B #include +.PP +.BI "double complex csqrt(double complex " z ");" +.br +.BI "float complex csqrtf(float complex " z ");" +.br +.BI "long double complex csqrtl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex square root of +.IR z , +with a branch cut along the negative real axis. +(That means that \fIcsqrt(\-1+eps*I)\fP will be close to I while +\fIcsqrt(\-1\-eps*I)\fP will be close to \-I, \fIif eps\fP is a small positive +real number.) +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR csqrt (), +.BR csqrtf (), +.BR csqrtl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/csqrtf.3 b/man3/csqrtf.3 new file mode 100644 index 0000000..e3cf329 --- /dev/null +++ b/man3/csqrtf.3 @@ -0,0 +1 @@ +.so man3/csqrt.3 diff --git a/man3/csqrtl.3 b/man3/csqrtl.3 new file mode 100644 index 0000000..e3cf329 --- /dev/null +++ b/man3/csqrtl.3 @@ -0,0 +1 @@ +.so man3/csqrt.3 diff --git a/man3/ctan.3 b/man3/ctan.3 new file mode 100644 index 0000000..ffd98fa --- /dev/null +++ b/man3/ctan.3 @@ -0,0 +1,62 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CTAN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ctan, ctanf, ctanl \- complex tangent function +.SH SYNOPSIS +.B #include +.PP +.BI "double complex ctan(double complex " z ");" +.br +.BI "float complex ctanf(float complex " z ); +.br +.BI "long double complex ctanl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex tangent of +.IR z . +.PP +The complex tangent function is defined as: +.PP +.nf + ctan(z) = csin(z) / ccos(z) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR ctan (), +.BR ctanf (), +.BR ctanl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR catan (3), +.BR ccos (3), +.BR csin (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ctanf.3 b/man3/ctanf.3 new file mode 100644 index 0000000..c0f4a66 --- /dev/null +++ b/man3/ctanf.3 @@ -0,0 +1 @@ +.so man3/ctan.3 diff --git a/man3/ctanh.3 b/man3/ctanh.3 new file mode 100644 index 0000000..7b6195a --- /dev/null +++ b/man3/ctanh.3 @@ -0,0 +1,63 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH CTANH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ctanh, ctanhf, ctanhl \- complex hyperbolic tangent +.SH SYNOPSIS +.B #include +.PP +.BI "double complex ctanh(double complex " z ");" +.br +.BI "float complex ctanhf(float complex " z ); +.br +.BI "long double complex ctanhl(long double complex " z ");" +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions calculate the complex hyperbolic tangent of +.IR z . +.PP +The complex hyperbolic tangent function is defined +mathematically as: +.PP +.nf + ctanh(z) = csinh(z) / ccosh(z) +.fi +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR ctanh (), +.BR ctanhf (), +.BR ctanhl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR cabs (3), +.BR catanh (3), +.BR ccosh (3), +.BR csinh (3), +.BR complex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ctanhf.3 b/man3/ctanhf.3 new file mode 100644 index 0000000..49b9217 --- /dev/null +++ b/man3/ctanhf.3 @@ -0,0 +1 @@ +.so man3/ctanh.3 diff --git a/man3/ctanhl.3 b/man3/ctanhl.3 new file mode 100644 index 0000000..49b9217 --- /dev/null +++ b/man3/ctanhl.3 @@ -0,0 +1 @@ +.so man3/ctanh.3 diff --git a/man3/ctanl.3 b/man3/ctanl.3 new file mode 100644 index 0000000..c0f4a66 --- /dev/null +++ b/man3/ctanl.3 @@ -0,0 +1 @@ +.so man3/ctan.3 diff --git a/man3/ctermid.3 b/man3/ctermid.3 new file mode 100644 index 0000000..3c8ba34 --- /dev/null +++ b/man3/ctermid.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 19:51:06 1993 by Rik Faith (faith@cs.unc.edu) +.TH CTERMID 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +ctermid \- get controlling terminal name +.SH SYNOPSIS +.nf +.B #include +.\" POSIX also requires this function to be declared in , +.\" and glibc does so if suitable feature test macros are defined. +.PP +.BI "char *ctermid(char *" "s" ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR ctermid (): +_POSIX_C_SOURCE +.SH DESCRIPTION +.BR ctermid () +returns a string which is the pathname for the current +controlling terminal for this process. +If +.I s +is NULL, +a static buffer is used, otherwise +.I s +points to a buffer used to hold the terminal pathname. +The symbolic constant +.B L_ctermid +is the maximum number of characters in the returned pathname. +.SH RETURN VALUE +The pointer to the pathname. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ctermid () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, Svr4. +.SH BUGS +The path returned may not uniquely identify the controlling +terminal; it may, for example, be +.IR /dev/tty . +.PP +It is not assured that the program can open the terminal. +.\" in glibc 2.3.x, x >= 4, the glibc headers threw an error +.\" if ctermid() was given an argument; fixed in 2.4. +.SH SEE ALSO +.BR ttyname (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ctime.3 b/man3/ctime.3 new file mode 100644 index 0000000..17ccb26 --- /dev/null +++ b/man3/ctime.3 @@ -0,0 +1,454 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de) +.\" Modified 2001-11-13, aeb +.\" Modified 2001-12-13, joey, aeb +.\" Modified 2004-11-16, mtk +.\" +.TH CTIME 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, +localtime_r \- transform date and time to broken-down time or ASCII +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *asctime(const struct tm *" tm ); +.BI "char *asctime_r(const struct tm *" tm ", char *" buf ); +.PP +.BI "char *ctime(const time_t *" timep ); +.BI "char *ctime_r(const time_t *" timep ", char *" buf ); +.PP +.BI "struct tm *gmtime(const time_t *" timep ); +.BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result ); +.PP +.BI "struct tm *localtime(const time_t *" timep ); +.BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result ); +.PP +.BI "time_t mktime(struct tm *" tm ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.PP +.BR asctime_r (), +.BR ctime_r (), +.BR gmtime_r (), +.BR localtime_r (): +.RS +_POSIX_C_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR ctime (), +.BR gmtime () +and +.BR localtime () +functions all take +an argument of data type \fItime_t\fP, which represents calendar time. +When interpreted as an absolute time value, it represents the number of +seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.PP +The +.BR asctime () +and +.BR mktime () +functions both take an argument +representing broken-down time, which is a representation +separated into year, month, day, and so on. +.PP +Broken-down time is stored +in the structure \fItm\fP, which is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct tm { + int tm_sec; /* Seconds (0\-60) */ + int tm_min; /* Minutes (0\-59) */ + int tm_hour; /* Hours (0\-23) */ + int tm_mday; /* Day of the month (1\-31) */ + int tm_mon; /* Month (0\-11) */ + int tm_year; /* Year \- 1900 */ + int tm_wday; /* Day of the week (0\-6, Sunday = 0) */ + int tm_yday; /* Day in the year (0\-365, 1 Jan = 0) */ + int tm_isdst; /* Daylight saving time */ +}; +.EE +.in +.PP +The members of the \fItm\fP structure are: +.TP 10 +.I tm_sec +The number of seconds after the minute, normally in the range 0 to 59, +but can be up to 60 to allow for leap seconds. +.TP +.I tm_min +The number of minutes after the hour, in the range 0 to 59. +.TP +.I tm_hour +The number of hours past midnight, in the range 0 to 23. +.TP +.I tm_mday +The day of the month, in the range 1 to 31. +.TP +.I tm_mon +The number of months since January, in the range 0 to 11. +.TP +.I tm_year +The number of years since 1900. +.TP +.I tm_wday +The number of days since Sunday, in the range 0 to 6. +.TP +.I tm_yday +The number of days since January 1, in the range 0 to 365. +.TP +.I tm_isdst +A flag that indicates whether daylight saving time is in effect at the +time described. +The value is positive if daylight saving time is in +effect, zero if it is not, and negative if the information is not +available. +.PP +The call +.BI ctime( t ) +is equivalent to +.BI asctime(localtime( t )) \fR. +It converts the calendar time \fIt\fP into a +null-terminated string of the form +.PP +.in +4n +.EX +"Wed Jun 30 21:49:08 1993\\n" +.EE +,in +.PP +The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed", +"Thu", "Fri", and "Sat". +The abbreviations for the months are "Jan", +"Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and +"Dec". +The return value points to a statically allocated string which +might be overwritten by subsequent calls to any of the date and time +functions. +The function also sets the external +variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see +.BR tzset (3)) +with information about the current timezone. +The reentrant version +.BR ctime_r () +does the same, but stores the +string in a user-supplied buffer +which should have room for at least 26 bytes. +It need not +set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. +.PP +The +.BR gmtime () +function converts the calendar time \fItimep\fP to +broken-down time representation, expressed in Coordinated Universal Time +(UTC). +It may return NULL when the year does not fit into an integer. +The return value points to a statically allocated struct which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR gmtime_r () +function does the same, but stores the data in a +user-supplied struct. +.PP +The +.BR localtime () +function converts the calendar time \fItimep\fP to +broken-down time representation, +expressed relative to the user's specified timezone. +The function acts as if it called +.BR tzset (3) +and sets the external variables \fItzname\fP with +information about the current timezone, \fItimezone\fP with the difference +between Coordinated Universal Time (UTC) and local standard time in +seconds, and \fIdaylight\fP to a nonzero value if daylight savings +time rules apply during some part of the year. +The return value points to a statically allocated struct which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR localtime_r () +function does the same, but stores the data in a +user-supplied struct. +It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. +.PP +The +.BR asctime () +function converts the broken-down time value +\fItm\fP into a null-terminated string with the same format as +.BR ctime (). +The return value points to a statically allocated string which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR asctime_r () +function does the same, but stores the string in +a user-supplied buffer which should have room for at least 26 bytes. +.PP +The +.BR mktime () +function converts a broken-down time structure, expressed +as local time, to calendar time representation. +The function ignores +the values supplied by the caller in the +.I tm_wday +and +.I tm_yday +fields. +The value specified in the +.I tm_isdst +field informs +.BR mktime () +whether or not daylight saving time (DST) +is in effect for the time supplied in the +.I tm +structure: +a positive value means DST is in effect; +zero means that DST is not in effect; +and a negative value means that +.BR mktime () +should (use timezone information and system databases to) +attempt to determine whether DST is in effect at the specified time. +.PP +The +.BR mktime () +function modifies the fields of the +.IR tm +structure as follows: +.I tm_wday +and +.I tm_yday +are set to values determined from the contents of the other fields; +if structure members are outside their valid interval, they will be +normalized (so that, for example, 40 October is changed into 9 November); +.I tm_isdst +is set (regardless of its initial value) +to a positive value or to 0, respectively, +to indicate whether DST is or is not in effect at the specified time. +Calling +.BR mktime () +also sets the external variable \fItzname\fP with +information about the current timezone. +.PP +If the specified broken-down +time cannot be represented as calendar time (seconds since the Epoch), +.BR mktime () +returns +.I (time_t)\ \-1 +and does not alter the +members of the broken-down time structure. +.SH RETURN VALUE +On success, +.BR gmtime () +and +.BR localtime () +return a pointer to a +.IR "struct\ tm" . +.PP +On success, +.BR gmtime_r () +and +.BR localtime_r () +return the address of the structure pointed to by +.IR result . +.PP +On success, +.BR asctime () +and +.BR ctime () +return a pointer to a string. +.PP +On success, +.BR asctime_r () +and +.BR ctime_r () +return a pointer to the string pointed to by +.IR buf . +.PP +On success, +.BR mktime () +returns the calendar time (seconds since the Epoch), +expressed as a value of type +.IR time_t . +.PP +On error, +.BR mktime () +returns the value +.IR "(time_t)\ -1" . +The remaining functions return NULL on error. +On error, +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.TP +.B EOVERFLOW +The result cannot be represented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw14 lb lbw31 +l l l. +Interface Attribute Value +T{ +.BR asctime () +T} Thread safety MT-Unsafe race:asctime locale +T{ +.BR asctime_r () +T} Thread safety MT-Safe locale +T{ +.BR ctime () +T} Thread safety T{ +MT-Unsafe race:tmbuf +.br +race:asctime env locale +T} +T{ +.BR ctime_r (), +.BR gmtime_r (), +.BR localtime_r (), +.BR mktime () +T} Thread safety MT-Safe env locale +T{ +.BR gmtime (), +.BR localtime () +T} Thread safety MT-Unsafe race:tmbuf env locale +.TE +.ad +.SH CONFORMING TO +POSIX.1-2001. +C89 and C99 specify +.BR asctime (), +.BR ctime (), +.BR gmtime (), +.BR localtime (), +and +.BR mktime (). +POSIX.1-2008 marks +.BR asctime (), +.BR asctime_r (), +.BR ctime (), +and +.BR ctime_r () +as obsolete, +recommending the use of +.BR strftime (3) +instead. +.SH NOTES +The four functions +.BR asctime (), +.BR ctime (), +.BR gmtime () +and +.BR localtime () +return a pointer to static data and hence are not thread-safe. +The thread-safe versions, +.BR asctime_r (), +.BR ctime_r (), +.BR gmtime_r () +and +.BR localtime_r (), +are specified by SUSv2. +.PP +POSIX.1-2001 says: +"The +.BR asctime (), +.BR ctime (), +.BR gmtime (), +and +.BR localtime () +functions shall return values in one of two static objects: +a broken-down time structure and an array of type +.IR char . +Execution of any of the functions may overwrite the information returned +in either of these objects by any of the other functions." +This can occur in the glibc implementation. +.PP +In many implementations, including glibc, a 0 in +.I tm_mday +is interpreted as meaning the last day of the preceding month. +.PP +The glibc version of \fIstruct tm\fP has additional fields +.PP +.in +4n +.EX +const char *tm_zone; /* Timezone abbreviation */ +.EE +.in +.PP +defined when +.B _BSD_SOURCE +was set before including +.IR . +This is a BSD extension, present in 4.3BSD-Reno. +.PP +According to POSIX.1-2004, +.BR localtime () +is required to behave as though +.BR tzset (3) +was called, while +.BR localtime_r () +does not have this requirement. +.\" See http://thread.gmane.org/gmane.comp.time.tz/2034/ +For portable code, +.BR tzset (3) +should be called before +.BR localtime_r (). +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR utime (2), +.BR clock (3), +.BR difftime (3), +.BR strftime (3), +.BR strptime (3), +.BR timegm (3), +.BR tzset (3), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ctime_r.3 b/man3/ctime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man3/ctime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/cuserid.3 b/man3/cuserid.3 new file mode 100644 index 0000000..b6d53bf --- /dev/null +++ b/man3/cuserid.3 @@ -0,0 +1 @@ +.so man3/getlogin.3 diff --git a/man3/daemon.3 b/man3/daemon.3 new file mode 100644 index 0000000..b74a6bc --- /dev/null +++ b/man3/daemon.3 @@ -0,0 +1,158 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)daemon.3 8.1 (Berkeley) 6/9/93 +.\" Added mentioning of glibc weirdness wrt unistd.h. 5/11/98, Al Viro +.TH DAEMON 3 2017-11-26 "GNU" "Linux Programmer's Manual" +.SH NAME +daemon \- run in the background +.SH SYNOPSIS +.B #include +.PP +.BI "int daemon(int " nochdir ", int " noclose ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR daemon (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.fi +.SH DESCRIPTION +The +.BR daemon () +function is for programs wishing to detach themselves from the +controlling terminal and run in the background as system daemons. +.PP +If +.I nochdir +is zero, +.BR daemon () +changes the process's current working directory +to the root directory ("/"); +otherwise, the current working directory is left unchanged. +.PP +If +.I noclose +is zero, +.BR daemon () +redirects standard input, standard output and standard error +to +.IR /dev/null ; +otherwise, no changes are made to these file descriptors. +.SH RETURN VALUE +(This function forks, and if the +.BR fork (2) +succeeds, the parent calls +.\" not .IR in order not to underline _ +.BR _exit (2), +so that further errors are seen by the child only.) +On success +.BR daemon () +returns zero. +If an error occurs, +.BR daemon () +returns \-1 and sets +.I errno +to any of the errors specified for the +.BR fork (2) +and +.BR setsid (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR daemon () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +Not in POSIX.1. +A similar function appears on the BSDs. +The +.BR daemon () +function first appeared in 4.4BSD. +.SH NOTES +The glibc implementation can also return \-1 when +.I /dev/null +exists but is not a character device with the expected +major and minor numbers. +In this case, +.I errno +need not be set. +.SH BUGS +The GNU C library implementation of this function was taken from BSD, +and does not employ the double-fork technique (i.e., +.BR fork (2), +.BR setsid (2), +.BR fork (2)) +that is necessary to ensure that the resulting daemon process is +not a session leader. +Instead, the resulting daemon +.I is +a session leader. +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=19144 +.\" Tested using a program that uses daemon() and then opens an +.\" otherwise unused console device (/dev/ttyN) that does not +.\" have an associated getty process. +On systems that follow System V semantics (e.g., Linux), +this means that if the daemon opens a terminal that is not +already a controlling terminal for another session, +then that terminal will inadvertently become +the controlling terminal for the daemon. +.SH SEE ALSO +.BR fork (2), +.BR setsid (2), +.BR daemon (7), +.BR logrotate (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/daylight.3 b/man3/daylight.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man3/daylight.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man3/db.3 b/man3/db.3 new file mode 100644 index 0000000..03ede66 --- /dev/null +++ b/man3/db.3 @@ -0,0 +1 @@ +.so man3/dbopen.3 diff --git a/man3/dbopen.3 b/man3/dbopen.3 new file mode 100644 index 0000000..bad6045 --- /dev/null +++ b/man3/dbopen.3 @@ -0,0 +1,570 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 +.\" +.TH DBOPEN 3 2017-09-15 "" "Linux Programmer's Manual" +.UC 7 +.SH NAME +dbopen \- database access methods +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.PP +.BI "DB *dbopen(const char *" file ", int " flags ", int " mode \ +", DBTYPE " type , +.BI " const void *" openinfo ); +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided in glibc up until version 2.1. +Since version 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.PP +.BR dbopen () +is the library interface to database files. +The supported file formats are btree, hashed and UNIX file oriented. +The btree format is a representation of a sorted, balanced tree structure. +The hashed format is an extensible, dynamic hashing scheme. +The flat-file format is a byte stream file with fixed or variable length +records. +The formats and file-format-specific information are described in detail +in their respective manual pages +.BR btree (3), +.BR hash (3), +and +.BR recno (3). +.PP +.BR dbopen () +opens +.I file +for reading and/or writing. +Files never intended to be preserved on disk may be created by setting +the +.I file +argument to NULL. +.PP +The +.I flags +and +.I mode +arguments are as specified to the +.BR open (2) +routine, however, only the +.BR O_CREAT , +.BR O_EXCL , +.BR O_EXLOCK , +.BR O_NONBLOCK , +.BR O_RDONLY , +.BR O_RDWR , +.BR O_SHLOCK , +and +.B O_TRUNC +flags are meaningful. +(Note, opening a database file +.B O_WRONLY +is not possible.) +.\"Three additional options may be specified by ORing +.\"them into the +.\".I flags +.\"argument. +.\".TP +.\"DB_LOCK +.\"Do the necessary locking in the database to support concurrent access. +.\"If concurrent access isn't needed or the database is read-only this +.\"flag should not be set, as it tends to have an associated performance +.\"penalty. +.\".TP +.\"DB_SHMEM +.\"Place the underlying memory pool used by the database in shared +.\"memory. +.\"Necessary for concurrent access. +.\".TP +.\"DB_TXN +.\"Support transactions in the database. +.\"The DB_LOCK and DB_SHMEM flags must be set as well. +.PP +The +.I type +argument is of type +.I DBTYPE +(as defined in the +.I +include file) and +may be set to +.BR DB_BTREE , +.BR DB_HASH , +or +.BR DB_RECNO . +.PP +The +.I openinfo +argument is a pointer to an access-method-specific structure described +in the access method's manual page. +If +.I openinfo +is NULL, each access method will use defaults appropriate for the system +and the access method. +.PP +.BR dbopen () +returns a pointer to a +.I DB +structure on success and NULL on error. +The +.I DB +structure is defined in the +.I +include file, and contains at +least the following fields: +.PP +.in +4n +.EX +typedef struct { + DBTYPE type; + int (*close)(const DB *db); + int (*del)(const DB *db, const DBT *key, unsigned int flags); + int (*fd)(const DB *db); + int (*get)(const DB *db, DBT *key, DBT *data, + unsigned int flags); + int (*put)(const DB *db, DBT *key, const DBT *data, + unsigned int flags); + int (*sync)(const DB *db, unsigned int flags); + int (*seq)(const DB *db, DBT *key, DBT *data, + unsigned int flags); +} DB; +.EE +.in +.PP +These elements describe a database type and a set of functions performing +various actions. +These functions take a pointer to a structure as returned by +.BR dbopen (), +and sometimes one or more pointers to key/data structures and a flag value. +.TP +.I type +The type of the underlying access method (and file format). +.TP +.I close +A pointer to a routine to flush any cached information to disk, free any +allocated resources, and close the underlying file(s). +Since key/data pairs may be cached in memory, failing to sync the file +with a +.I close +or +.I sync +function may result in inconsistent or lost information. +.I close +routines return \-1 on error (setting +.IR errno ) +and 0 on success. +.TP +.I del +A pointer to a routine to remove key/data pairs from the database. +.IP +The argument +.I flag +may be set to the following value: +.RS +.TP +.B R_CURSOR +Delete the record referenced by the cursor. +The cursor must have previously been initialized. +.RE +.IP +.I delete +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the specified +.I key +was not in the file. +.TP +.I fd +A pointer to a routine which returns a file descriptor representative +of the underlying database. +A file descriptor referencing the same file will be returned to all +processes which call +.BR dbopen () +with the same +.I file +name. +This file descriptor may be safely used as an argument to the +.BR fcntl (2) +and +.BR flock (2) +locking functions. +The file descriptor is not necessarily associated with any of the +underlying files used by the access method. +No file descriptor is available for in memory databases. +.I fd +routines return \-1 on error (setting +.IR errno ), +and the file descriptor on success. +.TP +.I get +A pointer to a routine which is the interface for keyed retrieval from +the database. +The address and length of the data associated with the specified +.I key +are returned in the structure referenced by +.IR data . +.I get +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the +.I key +was not in the file. +.TP +.I put +A pointer to a routine to store key/data pairs in the database. +.IP +The argument +.I flag +may be set to one of the following values: +.RS +.TP +.B R_CURSOR +Replace the key/data pair referenced by the cursor. +The cursor must have previously been initialized. +.TP +.B R_IAFTER +Append the data immediately after the data referenced by +.IR key , +creating a new key/data pair. +The record number of the appended key/data pair is returned in the +.I key +structure. +(Applicable only to the +.B DB_RECNO +access method.) +.TP +.B R_IBEFORE +Insert the data immediately before the data referenced by +.IR key , +creating a new key/data pair. +The record number of the inserted key/data pair is returned in the +.I key +structure. +(Applicable only to the +.B DB_RECNO +access method.) +.TP +.B R_NOOVERWRITE +Enter the new key/data pair only if the key does not previously exist. +.TP +.B R_SETCURSOR +Store the key/data pair, setting or initializing the position of the +cursor to reference it. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.RE +.IP +.B R_SETCURSOR +is available only for the +.B DB_BTREE +and +.B DB_RECNO +access +methods because it implies that the keys have an inherent order +which does not change. +.IP +.B R_IAFTER +and +.B R_IBEFORE +are available only for the +.B DB_RECNO +access method because they each imply that the access method is able to +create new keys. +This is true only if the keys are ordered and independent, record numbers +for example. +.IP +The default behavior of the +.I put +routines is to enter the new key/data pair, replacing any previously +existing key. +.IP +.I put +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the +.B R_NOOVERWRITE +.I flag +was set and the key already exists in the file. +.TP +.I seq +A pointer to a routine which is the interface for sequential +retrieval from the database. +The address and length of the key are returned in the structure +referenced by +.IR key , +and the address and length of the data are returned in the +structure referenced +by +.IR data . +.IP +Sequential key/data pair retrieval may begin at any time, and the +position of the "cursor" is not affected by calls to the +.IR del , +.IR get , +.IR put , +or +.I sync +routines. +Modifications to the database during a sequential scan will be reflected +in the scan, that is, +records inserted behind the cursor will not be returned +while records inserted in front of the cursor will be returned. +.IP +The flag value +.B must +be set to one of the following values: +.RS +.TP +.B R_CURSOR +The data associated with the specified key is returned. +This differs from the +.I get +routines in that it sets or initializes the cursor to the location of +the key as well. +(Note, for the +.B DB_BTREE +access method, the returned key is not necessarily an +exact match for the specified key. +The returned key is the smallest key greater than or equal to the specified +key, permitting partial key matches and range searches.) +.TP +.B R_FIRST +The first key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +.TP +.B R_LAST +The last key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.TP +.B R_NEXT +Retrieve the key/data pair immediately after the cursor. +If the cursor is not yet set, this is the same as the +.B R_FIRST +flag. +.TP +.B R_PREV +Retrieve the key/data pair immediately before the cursor. +If the cursor is not yet set, this is the same as the +.B R_LAST +flag. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.RE +.IP +.B R_LAST +and +.B R_PREV +are available only for the +.B DB_BTREE +and +.B DB_RECNO +access methods because they each imply that the keys have an inherent +order which does not change. +.IP +.I seq +routines return \-1 on error (setting +.IR errno ), +0 on success and 1 if there are no key/data pairs less than or greater +than the specified or current key. +If the +.B DB_RECNO +access method is being used, and if the database file +is a character special file and no complete key/data pairs are currently +available, the +.I seq +routines return 2. +.TP +.I sync +A pointer to a routine to flush any cached information to disk. +If the database is in memory only, the +.I sync +routine has no effect and will always succeed. +.IP +The flag value may be set to the following value: +.RS +.TP +.B R_RECNOSYNC +If the +.B DB_RECNO +access method is being used, this flag causes +the sync routine to apply to the btree file which underlies the +recno file, not the recno file itself. +(See the +.I bfname +field of the +.BR recno (3) +manual page for more information.) +.RE +.IP +.I sync +routines return \-1 on error (setting +.IR errno ) +and 0 on success. +.SS Key/data pairs +Access to all file types is based on key/data pairs. +Both keys and data are represented by the following data structure: +.PP +.in +4n +.EX +typedef struct { + void *data; + size_t size; +} DBT; +.EE +.in +.PP +The elements of the +.I DBT +structure are defined as follows: +.TP +.I data +A pointer to a byte string. +.TP +.I size +The length of the byte string. +.PP +Key and data byte strings may reference strings of essentially unlimited +length although any two of them must fit into available memory at the same +time. +It should be noted that the access methods provide no guarantees about +byte string alignment. +.SH ERRORS +The +.BR dbopen () +routine may fail and set +.I errno +for any of the errors specified for the library routines +.BR open (2) +and +.BR malloc (3) +or the following: +.TP +.B EFTYPE +A file is incorrectly formatted. +.TP +.B EINVAL +A parameter has been specified (hash function, pad byte, etc.) that is +incompatible with the current file specification or which is not +meaningful for the function (for example, use of the cursor without +prior initialization) or there is a mismatch between the version +number of file and the software. +.PP +The +.I close +routines may fail and set +.I errno +for any of the errors specified for the library routines +.BR close (2), +.BR read (2), +.BR write (2), +.BR free (3), +or +.BR fsync (2). +.PP +The +.IR del , +.IR get , +.IR put , +and +.I seq +routines may fail and set +.I errno +for any of the errors specified for the library routines +.BR read (2), +.BR write (2), +.BR free (3) +or +.BR malloc (3). +.PP +The +.I fd +routines will fail and set +.I errno +to +.B ENOENT +for in memory databases. +.PP +The +.I sync +routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR fsync (2). +.SH BUGS +The typedef +.I DBT +is a mnemonic for "data base thang", and was used +because no one could think of a reasonable name that wasn't already used. +.PP +The file descriptor interface is a kludge and will be deleted in a +future version of the interface. +.PP +None of the access methods provide any form of concurrent access, +locking, or transactions. +.SH SEE ALSO +.BR btree (3), +.BR hash (3), +.BR mpool (3), +.BR recno (3) +.PP +.IR "LIBTP: Portable, Modular Transactions for UNIX" , +Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/des_crypt.3 b/man3/des_crypt.3 new file mode 100644 index 0000000..224e0a4 --- /dev/null +++ b/man3/des_crypt.3 @@ -0,0 +1,163 @@ +.\" @(#)des_crypt.3 2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI; +.\" +.\" Taken from libc4 sources, which say: +.\" Copyright (C) 1993 Eric Young - can be distributed under GPL. +.\" +.\" However, the above header line suggests that this file in fact is +.\" Copyright Sun Microsystems, Inc (and is provided for unrestricted use, +.\" see other Sun RPC sources). +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" can be distributed under GPL. +.\" %%%LICENSE_END +.\" +.TH DES_CRYPT 3 2015-03-02 "" "Linux Programmer's Manual" +.SH NAME +des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast +DES encryption +.SH SYNOPSIS +.nf +.\" Sun version +.\" .B #include +.B #include +.PP +.BI "int ecb_crypt(char *" key ", char *" data ", unsigned " datalen , +.BI " unsigned " mode ); +.PP +.BI "int cbc_crypt(char *" key ", char *" data ", unsigned " datalen , +.BI " unsigned " mode ", char *" ivec ); +.PP +.BI "void des_setparity(char *" key ); +.PP +.BI "int DES_FAILED(int " status ); +.fi +.SH DESCRIPTION +.BR ecb_crypt () +and +.BR cbc_crypt () +implement the +NBS +DES +(Data Encryption Standard). +These routines are faster and more general purpose than +.BR crypt (3). +They also are able to utilize +DES +hardware if it is available. +.BR ecb_crypt () +encrypts in +ECB +(Electronic Code Book) +mode, which encrypts blocks of data independently. +.BR cbc_crypt () +encrypts in +CBC +(Cipher Block Chaining) +mode, which chains together +successive blocks. +CBC +mode protects against insertions, deletions and +substitutions of blocks. +Also, regularities in the clear text will +not appear in the cipher text. +.PP +Here is how to use these routines. +The first argument, +.IR key , +is the 8-byte encryption key with parity. +To set the key's parity, which for +DES +is in the low bit of each byte, use +.BR des_setparity (). +The second argument, +.IR data , +contains the data to be encrypted or decrypted. +The +third argument, +.IR datalen , +is the length in bytes of +.IR data , +which must be a multiple of 8. +The fourth argument, +.IR mode , +is formed by ORing together some things. +For the encryption direction OR in either +.BR DES_ENCRYPT +or +.BR DES_DECRYPT . +For software versus hardware +encryption, OR in either +.BR DES_HW +or +.BR DES_SW . +If +.BR DES_HW +is specified, and there is no hardware, then the encryption is performed +in software and the routine returns +.BR DESERR_NOHWDEVICE . +For +.BR cbc_crypt (), +the argument +.I ivec +is the 8-byte initialization +vector for the chaining. +It is updated to the next initialization +vector upon return. +.SH RETURN VALUE +.PD 0 +.TP 20 +.BR DESERR_NONE +No error. +.TP +.BR DESERR_NOHWDEVICE +Encryption succeeded, but done in software instead of the requested hardware. +.TP +.BR DESERR_HWERROR +An error occurred in the hardware or driver. +.TP +.BR DESERR_BADPARAM +Bad argument to routine. +.PD +.PP +Given a result status +.IR stat , +the macro +.\" .BR DES_FAILED\c +.\" .BR ( stat ) +.BI DES_FAILED( stat ) +is false only for the first two statuses. +.\" So far the Sun page +.\" Some additions - aeb +.SH VERSIONS +These functions are present in +glibc 2.1 and later. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR ecb_crypt (), +.BR cbc_crypt (), +.BR des_setparity () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.3BSD. +Not in POSIX.1. +.SH SEE ALSO +.BR des (1), +.BR crypt (3), +.BR xcrypt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/des_setparity.3 b/man3/des_setparity.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man3/des_setparity.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man3/difftime.3 b/man3/difftime.3 new file mode 100644 index 0000000..e2d99e7 --- /dev/null +++ b/man3/difftime.3 @@ -0,0 +1,90 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:48:17 1993 by Rik Faith (faith@cs.unc.edu) +.TH DIFFTIME 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +difftime \- calculate time difference +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double difftime(time_t " time1 ", time_t " time0 ); +.fi +.SH DESCRIPTION +The +.BR difftime () +function returns the number of seconds elapsed +between time \fItime1\fP and time \fItime0\fP, represented as a +.IR double . +Each of the times is specified in calendar time, which means its +value is a measurement (in seconds) relative to the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR difftime () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +On a POSIX system, +.I time_t +is an arithmetic type, and one could just +define +.PP +.in +4n +.EX +#define difftime(t1,t0) (double)(t1 \- t0) +.EE +.in +.PP +when the possible overflow in the subtraction is not a concern. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR ctime (3), +.BR gmtime (3), +.BR localtime (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dirfd.3 b/man3/dirfd.3 new file mode 100644 index 0000000..d5a1b3c --- /dev/null +++ b/man3/dirfd.3 @@ -0,0 +1,116 @@ +.\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH DIRFD 3 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +dirfd \- get directory stream file descriptor +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.BI "int dirfd(DIR *" dirp ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR dirfd (): +.br +.RS 4 +.PD 0 +.ad l +/* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.PD +.RE +.ad +.SH DESCRIPTION +The function +.BR dirfd () +returns the file descriptor associated with the directory stream +.IR dirp . +.PP +This file descriptor is the one used internally by the directory stream. +As a result, it is useful only for functions which do not depend on +or alter the file position, such as +.BR fstat (2) +and +.BR fchdir (2). +It will be automatically closed when +.BR closedir (3) +is called. +.SH RETURN VALUE +On success, a nonnegative file descriptor is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +POSIX.1-2008 specifies two errors, +neither of which is returned by the current +.\" glibc 2.8 +implementation. +.TP +.B EINVAL +.I dirp +does not refer to a valid directory stream. +.TP +.B ENOTSUP +The implementation does not support the association of a file +descriptor with a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR dirfd () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2008. +This function was a BSD extension, present in 4.3BSD-Reno, not in 4.2BSD. +.\" It is present in libc5 (since 5.1.2) and in glibc2. +.SH SEE ALSO +.BR open (2), +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dirname.3 b/man3/dirname.3 new file mode 100644 index 0000000..9099c1a --- /dev/null +++ b/man3/dirname.3 @@ -0,0 +1 @@ +.so man3/basename.3 diff --git a/man3/div.3 b/man3/div.3 new file mode 100644 index 0000000..38cc300 --- /dev/null +++ b/man3/div.3 @@ -0,0 +1,128 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10, 2003-11-01 Walter Harms, aeb +.\" +.TH DIV 3 2016-03-15 "" "Linux Programmer's Manual" +.SH NAME +div, ldiv, lldiv, imaxdiv \- compute quotient and remainder of +an integer division +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "div_t div(int " numerator ", int " denominator ); +.BI "ldiv_t ldiv(long " numerator ", long " denominator ); +.BI "lldiv_t lldiv(long long " numerator ", long long " denominator ); +.PP +.B #include +.PP +.BI "imaxdiv_t imaxdiv(intmax_t " numerator ", intmax_t " denominator ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.PP +.BR lldiv (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +The +.BR div () +function computes the value +\fInumerator\fP/\fIdenominator\fP and +returns the quotient and remainder in a structure +named \fIdiv_t\fP that contains +two integer members (in unspecified order) named \fIquot\fP and \fIrem\fP. +The quotient is rounded toward zero. +The result satisfies \fIquot\fP*\fIdenominator\fP+\fIrem\fP = \fInumerator\fP. +.PP +The +.BR ldiv (), +.BR lldiv (), +and +.BR imaxdiv () +functions do the same, +dividing numbers of the indicated type and +returning the result in a structure +of the indicated name, in all cases with fields \fIquot\fP and \fIrem\fP +of the same type as the function arguments. +.SH RETURN VALUE +The \fIdiv_t\fP (etc.) structure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw33 lb lb +l l l. +Interface Attribute Value +T{ +.BR div (), +.BR ldiv (), +.BR lldiv (), +.BR imaxdiv () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +The functions +.BR lldiv () +and +.BR imaxdiv () +were added in C99. +.SH EXAMPLE +After +.PP +.in +4n +.EX +div_t q = div(\-5, 3); +.EE +.in +.PP +the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively. +.SH SEE ALSO +.BR abs (3), +.BR remainder (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dl_iterate_phdr.3 b/man3/dl_iterate_phdr.3 new file mode 100644 index 0000000..244ca62 --- /dev/null +++ b/man3/dl_iterate_phdr.3 @@ -0,0 +1,369 @@ +.\" Copyright (c) 2003, 2017 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH DL_ITERATE_PHDR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +dl_iterate_phdr \- walk through list of shared objects +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int dl_iterate_phdr(" +.BI " int (*" callback ") (struct dl_phdr_info *" info , +.BI " size_t " size ", void *" data ")," +.BI " void *" data ");" +.fi +.SH DESCRIPTION +The +.BR dl_iterate_phdr () +function allows an application to inquire at run time to find +out which shared objects it has loaded, +and the order in which they were loaded. +.PP +The +.BR dl_iterate_phdr () +function walks through the list of an +application's shared objects and calls the function +.I callback +once for each object, +until either all shared objects have been processed or +.I callback +returns a nonzero value. +.PP +Each call to +.I callback +receives three arguments: +.IR info , +which is a pointer to a structure containing information +about the shared object; +.IR size , +which is the size of the structure pointed to by +.IR info ; +and +.IR data , +which is a copy of whatever value was passed by the calling +program as the second argument (also named +.IR data ) +in the call to +.BR dl_iterate_phdr (). +.PP +The +.I info +argument is a structure of the following type: +.PP +.in +4n +.EX +struct dl_phdr_info { + ElfW(Addr) dlpi_addr; /* Base address of object */ + const char *dlpi_name; /* (Null-terminated) name of + object */ + const ElfW(Phdr) *dlpi_phdr; /* Pointer to array of + ELF program headers + for this object */ + ElfW(Half) dlpi_phnum; /* # of items in \fIdlpi_phdr\fP */ + + /* The following fields were added in glibc 2.4, after the first + version of this structure was available. Check the \fIsize\fP + argument passed to the dl_iterate_phdr callback to determine + whether or not each later member is available. */ + + unsigned long long int dlpi_adds; + /* Incremented when a new object may + have been added */ + unsigned long long int dlpi_subs; + /* Incremented when an object may + have been removed */ + size_t dlpi_tls_modid; + /* If there is a PT_TLS segment, its module + ID as used in TLS relocations, else zero */ + void *dlpi_tls_data; + /* The address of the calling thread's instance + of this module's PT_TLS segment, if it has + one and it has been allocated in the calling + thread, otherwise a null pointer */ +}; +.EE +.in +.PP +(The +.IR ElfW () +macro definition turns its argument into the name of an ELF data +type suitable for the hardware architecture. +For example, on a 32-bit platform, +.I ElfW(Addr) +yields the data type name +.IR Elf32_Addr . +Further information on these types can be found in the +.IR " and " +header files.) +.PP +The +.I dlpi_addr +field indicates the base address of the shared object +(i.e., the difference between the virtual memory address of +the shared object and the offset of that object in the file +from which it was loaded). +The +.I dlpi_name +field is a null-terminated string giving the pathname +from which the shared object was loaded. +.PP +To understand the meaning of the +.I dlpi_phdr +and +.I dlpi_phnum +fields, we need to be aware that an ELF shared object consists +of a number of segments, each of which has a corresponding +program header describing the segment. +The +.I dlpi_phdr +field is a pointer to an array of the program headers for this +shared object. +The +.I dlpi_phnum +field indicates the size of this array. +.PP +These program headers are structures of the following form: +.PP +.in +4n +.EX +typedef struct { + Elf32_Word p_type; /* Segment type */ + Elf32_Off p_offset; /* Segment file offset */ + Elf32_Addr p_vaddr; /* Segment virtual address */ + Elf32_Addr p_paddr; /* Segment physical address */ + Elf32_Word p_filesz; /* Segment size in file */ + Elf32_Word p_memsz; /* Segment size in memory */ + Elf32_Word p_flags; /* Segment flags */ + Elf32_Word p_align; /* Segment alignment */ +} Elf32_Phdr; +.EE +.in +.PP +Note that we can calculate the location of a particular program header, +.IR x , +in virtual memory using the formula: +.PP +.in +4n +.EX +addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr; +.EE +.in +.PP +Possible values for +.I p_type +include the following (see +.IR +for further details): +.PP +.in +4n +.EX +#define PT_LOAD 1 /* Loadable program segment */ +#define PT_DYNAMIC 2 /* Dynamic linking information */ +#define PT_INTERP 3 /* Program interpreter */ +#define PT_NOTE 4 /* Auxiliary information */ +#define PT_SHLIB 5 /* Reserved */ +#define PT_PHDR 6 /* Entry for header table itself */ +#define PT_TLS 7 /* Thread-local storage segment */ +#define PT_GNU_EH_FRAME 0x6474e550 /* GCC .eh_frame_hdr segment */ +#define PT_GNU_STACK 0x6474e551 /* Indicates stack executability */ +.\" For PT_GNU_STACK, see http://www.airs.com/blog/archives/518 +#define PT_GNU_RELRO 0x6474e552 /* Read-only after relocation */ +.EE +.in +.SH RETURN VALUE +The +.BR dl_iterate_phdr () +function returns whatever value was returned by the last call to +.IR callback . +.SH VERSIONS +.BR dl_iterate_phdr () +has been supported in glibc since version 2.2.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR dl_iterate_phdr () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +The +.BR dl_iterate_phdr () +function is not specified in any standard. +Various other systems provide a version of this function, +although details of the returned +.I dl_phdr_info +structure differ. +On the BSDs and Solaris, the structure includes the fields +.IR dlpi_addr , +.IR dlpi_name , +.IR dlpi_phdr , +and +.IR dlpi_phnum +in addition to other implementation-specific fields. +.SH NOTES +Future versions of the C library may add further fields to the +.IR dl_phdr_info +structure; in that event, the +.I size +argument provides a mechanism for the callback function to discover +whether it is running on a system with added fields. +.PP +The first object visited by +.IR callback +is the main program. +For the main program, the +.I dlpi_name +field will be an empty string. +.SH EXAMPLE +The following program displays a list of pathnames of the +shared objects it has loaded. +For each shared object, the program lists some information +(virtual address, size, flags, and type) +for each of the objects ELF segments. +.PP +The following shell session demonstrates the output +produced by the program on an x86-64 system. +The first shared object for which output is displayed +(where the name is an empty string) +is the main program. +.PP +.in +4n +.EX +$ \fB./a.out\fP +Name: "" (9 segments) + 0: [ 0x400040; memsz: 1f8] flags: 0x5; PT_PHDR + 1: [ 0x400238; memsz: 1c] flags: 0x4; PT_INTERP + 2: [ 0x400000; memsz: ac4] flags: 0x5; PT_LOAD + 3: [ 0x600e10; memsz: 240] flags: 0x6; PT_LOAD + 4: [ 0x600e28; memsz: 1d0] flags: 0x6; PT_DYNAMIC + 5: [ 0x400254; memsz: 44] flags: 0x4; PT_NOTE + 6: [ 0x400970; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME + 7: [ (nil); memsz: 0] flags: 0x6; PT_GNU_STACK + 8: [ 0x600e10; memsz: 1f0] flags: 0x4; PT_GNU_RELRO +Name: "linux-vdso.so.1" (4 segments) + 0: [0x7ffc6edd1000; memsz: e89] flags: 0x5; PT_LOAD + 1: [0x7ffc6edd1360; memsz: 110] flags: 0x4; PT_DYNAMIC + 2: [0x7ffc6edd17b0; memsz: 3c] flags: 0x4; PT_NOTE + 3: [0x7ffc6edd17ec; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME +Name: "/lib64/libc.so.6" (10 segments) + 0: [0x7f55712ce040; memsz: 230] flags: 0x5; PT_PHDR + 1: [0x7f557145b980; memsz: 1c] flags: 0x4; PT_INTERP + 2: [0x7f55712ce000; memsz: 1b6a5c] flags: 0x5; PT_LOAD + 3: [0x7f55716857a0; memsz: 9240] flags: 0x6; PT_LOAD + 4: [0x7f5571688b80; memsz: 1f0] flags: 0x6; PT_DYNAMIC + 5: [0x7f55712ce270; memsz: 44] flags: 0x4; PT_NOTE + 6: [0x7f55716857a0; memsz: 78] flags: 0x4; PT_TLS + 7: [0x7f557145b99c; memsz: 544c] flags: 0x4; PT_GNU_EH_FRAME + 8: [0x7f55712ce000; memsz: 0] flags: 0x6; PT_GNU_STACK + 9: [0x7f55716857a0; memsz: 3860] flags: 0x4; PT_GNU_RELRO +Name: "/lib64/ld-linux-x86-64.so.2" (7 segments) + 0: [0x7f557168f000; memsz: 20828] flags: 0x5; PT_LOAD + 1: [0x7f55718afba0; memsz: 15a8] flags: 0x6; PT_LOAD + 2: [0x7f55718afe10; memsz: 190] flags: 0x6; PT_DYNAMIC + 3: [0x7f557168f1c8; memsz: 24] flags: 0x4; PT_NOTE + 4: [0x7f55716acec4; memsz: 604] flags: 0x4; PT_GNU_EH_FRAME + 5: [0x7f557168f000; memsz: 0] flags: 0x6; PT_GNU_STACK + 6: [0x7f55718afba0; memsz: 460] flags: 0x4; PT_GNU_RELRO +.EE +.in +.PP +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include + +static int +callback(struct dl_phdr_info *info, size_t size, void *data) +{ + char *type; + int p_type, j; + + printf("Name: \\"%s\\" (%d segments)\\n", info\->dlpi_name, + info\->dlpi_phnum); + + for (j = 0; j < info\->dlpi_phnum; j++) { + p_type = info\->dlpi_phdr[j].p_type; + type = (p_type == PT_LOAD) ? "PT_LOAD" : + (p_type == PT_DYNAMIC) ? "PT_DYNAMIC" : + (p_type == PT_INTERP) ? "PT_INTERP" : + (p_type == PT_NOTE) ? "PT_NOTE" : + (p_type == PT_INTERP) ? "PT_INTERP" : + (p_type == PT_PHDR) ? "PT_PHDR" : + (p_type == PT_TLS) ? "PT_TLS" : + (p_type == PT_GNU_EH_FRAME) ? "PT_GNU_EH_FRAME" : + (p_type == PT_GNU_STACK) ? "PT_GNU_STACK" : + (p_type == PT_GNU_RELRO) ? "PT_GNU_RELRO" : NULL; + + printf(" %2d: [%14p; memsz:%7lx] flags: 0x%x; ", j, + (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr), + info\->dlpi_phdr[j].p_memsz, + info\->dlpi_phdr[j].p_flags); + if (type != NULL) + printf("%s\\n", type); + else + printf("[other (0x%x)]\\n", p_type); + } + + return 0; +} + +int +main(int argc, char *argv[]) +{ + dl_iterate_phdr(callback, NULL); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ldd (1), +.BR objdump (1), +.BR readelf (1), +.BR dladdr (3), +.BR dlopen (3), +.BR elf (5), +.BR ld.so (8) +.PP +.IR "Executable and Linking Format Specification" , +available at various locations online. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dladdr.3 b/man3/dladdr.3 new file mode 100644 index 0000000..74dae54 --- /dev/null +++ b/man3/dladdr.3 @@ -0,0 +1,299 @@ +'\" t +.\" Copyright (C) 2015 Michael Kerrisk +.\" and Copyright (C) 2008 Petr Baudis (dladdr caveat) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH DLADDR 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +dladdr, dladdr1 \- translate address to symbolic information +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.PP +.BI "int dladdr(void *" addr ", Dl_info *" info ); +.PP +.BI "int dladdr1(void *" addr ", Dl_info *" info ", void **" \ + extra_info ", int " flags ); +.PP +Link with \fI\-ldl\fP. +.fi +.SH DESCRIPTION +The function +.BR dladdr () +determines whether the address specified in +.IR addr +is located in one of the shared objects loaded by the calling application. +If it is, then +.BR dladdr () +returns information about the shared object and symbol that overlaps +.IR addr . +This information is returned in a +.I Dl_info +structure: +.PP +.in +4n +.EX +typedef struct { + const char *dli_fname; /* Pathname of shared object that + contains address */ + void *dli_fbase; /* Base address at which shared + object is loaded */ + const char *dli_sname; /* Name of symbol whose definition + overlaps \fIaddr\fP */ + void *dli_saddr; /* Exact address of symbol named + in \fIdli_sname\fP */ +} Dl_info; +.EE +.in +.PP +If no symbol matching +.I addr +could be found, then +.I dli_sname +and +.I dli_saddr +are set to NULL. +.PP +The function +.BR dladdr1 () +is like +.BR dladdr (), +but returns additional information via the argument +.IR extra_info . +The information returned depends on the value specified in +.IR flags , +which can have one of the following values: +.TP +.B RTLD_DL_LINKMAP +Obtain a pointer to the link map for the matched file. +The +.IR extra_info +argument points to a pointer to a +.I link_map +structure (i.e., +.IR "struct link_map\ **" ), +defined in +.I +as: +.IP +.in +4n +.EX +struct link_map { + ElfW(Addr) l_addr; /* Difference between the + address in the ELF file and + the address in memory */ + char *l_name; /* Absolute pathname where + object was found */ + ElfW(Dyn) *l_ld; /* Dynamic section of the + shared object */ + struct link_map *l_next, *l_prev; + /* Chain of loaded objects */ + + /* Plus additional fields private to the + implementation */ +}; +.EE +.in +.TP +.B RTLD_DL_SYMENT +Obtain a pointer to the ELF symbol table entry of the matching symbol. +The +.IR extra_info +argument is a pointer to a symbol pointer: +.IR "const ElfW(Sym) **" . +The +.IR ElfW () +macro definition turns its argument into the name of an ELF data +type suitable for the hardware architecture. +For example, on a 64-bit platform, +.I ElfW(Sym) +yields the data type name +.IR Elf64_Sym , +which is defined in +.IR +as: +.IP +.in +4n +.EX +typedef struct { + Elf64_Word st_name; /* Symbol name */ + unsigned char st_info; /* Symbol type and binding */ + unsigned char st_other; /* Symbol visibility */ + Elf64_Section st_shndx; /* Section index */ + Elf64_Addr st_value; /* Symbol value */ + Elf64_Xword st_size; /* Symbol size */ +} Elf64_Sym; +.EE +.in +.IP +The +.I st_name +field is an index into the string table. +.IP +The +.I st_info +field encodes the symbol's type and binding. +The type can be extracted using the macro +.BR ELF64_ST_TYPE(st_info) +(or +.BR ELF32_ST_TYPE() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STT_NOTYPE Symbol type is unspecified +STT_OBJECT Symbol is a data object +STT_FUNC Symbol is a code object +STT_SECTION Symbol associated with a section +STT_FILE Symbol's name is file name +STT_COMMON Symbol is a common data object +STT_TLS Symbol is thread-local data object +STT_GNU_IFUNC Symbol is indirect code object +.TE +.in +.IP +The symbol binding can be extracted from the +.I st_info +field using the macro +.BR ELF64_ST_BIND(st_info) +(or +.BR ELF32_ST_BIND() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STB_LOCAL Local symbol +STB_GLOBAL Global symbol +STB_WEAK Weak symbol +STB_GNU_UNIQUE Unique symbol +.TE +.in +.IP +The +.I st_other +field contains the symbol's visibility, which can be extracted using the macro +.BR ELF64_ST_VISIBILITY(st_info) +(or +.BR ELF32_ST_VISIBILITY() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STV_DEFAULT Default symbol visibility rules +STV_INTERNAL Processor-specific hidden class +STV_HIDDEN Symbol unavailable in other modules +STV_PROTECTED Not preemptible, not exported +.TE +.in +.SH RETURN VALUE +On success, these functions return a nonzero value. +If the address specified in +.I addr +could be matched to a shared object, +but not to a symbol in the shared object, then the +.I info->dli_sname +and +.I info->dli_saddr +fields are set to NULL. +.PP +If the address specified in +.I addr +could not be matched to a shared object, then these functions return 0. +In this case, an error message is +.I not +.\" According to the FreeBSD man page, dladdr1() does signal an +.\" error via dlerror() for this case. +available via +.BR dlerror (3). +.SH VERSIONS +.BR dladdr () +is present in glibc 2.0 and later. +.BR dladdr1 () +first appeared in glibc 2.3.3. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR dladdr (), +.BR dladdr1 () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are nonstandard GNU extensions +that are also present on Solaris. +.SH BUGS +Sometimes, the function pointers you pass to +.BR dladdr () +may surprise you. +On some architectures (notably i386 and x86-64), +.I dli_fname +and +.I dli_fbase +may end up pointing back at the object from which you called +.BR dladdr (), +even if the function used as an argument should come from +a dynamically linked library. +.PP +The problem is that the function pointer will still be resolved +at compile time, but merely point to the +.I plt +(Procedure Linkage Table) +section of the original object (which dispatches the call after +asking the dynamic linker to resolve the symbol). +To work around this, +you can try to compile the code to be position-independent: +then, the compiler cannot prepare the pointer +at compile time any more and +.BR gcc (1) +will generate code that just loads the final symbol address from the +.I got +(Global Offset Table) at run time before passing it to +.BR dladdr (). +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR dlsym (3), +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dladdr1.3 b/man3/dladdr1.3 new file mode 100644 index 0000000..43979e5 --- /dev/null +++ b/man3/dladdr1.3 @@ -0,0 +1 @@ +.so man3/dladdr.3 diff --git a/man3/dlclose.3 b/man3/dlclose.3 new file mode 100644 index 0000000..15d0968 --- /dev/null +++ b/man3/dlclose.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man3/dlerror.3 b/man3/dlerror.3 new file mode 100644 index 0000000..69b6e2c --- /dev/null +++ b/man3/dlerror.3 @@ -0,0 +1,100 @@ +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" and Copyright 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH DLERROR 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +dlerror \- obtain error diagnostic for functions in the dlopen API +.SH SYNOPSIS +.B #include +.PP +.B "char *dlerror(void);" +.PP +Link with \fI\-ldl\fP. +.SH DESCRIPTION +The +.BR dlerror () +function returns a human-readable, +null-terminated string describing the most recent error +that occurred from a call to one of the functions in the dlopen API +since the last call to +.BR dlerror (). +The returned string does +.I not +include a trailing newline. +.PP +.BR dlerror () +returns NULL if no errors have occurred since initialization or since +it was last called. +.SH VERSIONS +.BR dlerror () +is present in glibc 2.0 and later. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR dlerror () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES +The message returned by +.BR dlerror () +may reside in a statically allocated buffer that is +overwritten by subsequent +.BR dlerror () +calls. +.\" .LP +.\" The string returned by +.\" .BR dlerror () +.\" should not be modified. +.\" Some systems give the prototype as +.\" .sp +.\" .in +5 +.\" .B "const char *dlerror(void);" +.\" .in +.SS History +This function is part of the dlopen API, derived from SunOS. +.SH EXAMPLE +See +.BR dlopen (3). +.SH SEE ALSO +.BR dladdr (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR dlsym (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dlinfo.3 b/man3/dlinfo.3 new file mode 100644 index 0000000..0ebea67 --- /dev/null +++ b/man3/dlinfo.3 @@ -0,0 +1,344 @@ +'\" t +.\" Copyright (C) 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH DLINFO 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +dlinfo \- obtain information about a dynamically loaded object +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.B #include +.PP +.BR "int dlinfo(void *" handle ", int " request ", void *" info ); +.PP +Link with \fI\-ldl\fP. +.fi +.SH DESCRIPTION +The +.BR dlinfo () +function obtains information about the dynamically loaded object +referred to by +.IR handle +(typically obtained by an earlier call to +.BR dlopen (3) +or +.BR dlmopen (3)). +The +.I request +argument specifies which information is to be returned. +The +.I info +argument is a pointer to a buffer used to store information +returned by the call; the type of this argument depends on +.IR request . +.PP +The following values are supported for +.IR request +(with the corresponding type for +.IR info +shown in parentheses): +.TP +.BR RTLD_DI_LMID " (\fILmid_t *\fP)" +Obtain the ID of the link-map list (namespace) in which +.I handle +is loaded. +.TP +.BR RTLD_DI_LINKMAP " (\fIstruct link_map **\fP)" +Obtain a pointer to the +.I link_map +structure corresponding to +.IR handle . +The +.IR info +argument points to a pointer to a +.I link_map +structure, defined in +.I +as: +.IP +.in +4n +.EX +struct link_map { + ElfW(Addr) l_addr; /* Difference between the + address in the ELF file and + the address in memory */ + char *l_name; /* Absolute pathname where + object was found */ + ElfW(Dyn) *l_ld; /* Dynamic section of the + shared object */ + struct link_map *l_next, *l_prev; + /* Chain of loaded objects */ + + /* Plus additional fields private to the + implementation */ +}; +.EE +.in +.TP +.BR RTLD_DI_ORIGIN " (\fIchar *\fP)" +Copy the pathname of the origin of the shared object corresponding to +.IR handle +to the location pointed to by +.IR info . +.TP +.BR RTLD_DI_SERINFO " (\fIDl_serinfo *\fP)" +Obtain the library search paths for the shared object referred to by +.IR handle . +The +.I info +argument is a pointer to a +.I Dl_serinfo +that contains the search paths. +Because the number of search paths may vary, +the size of the structure pointed to by +.IR info +can vary. +The +.B RTLD_DI_SERINFOSIZE +request described below allows applications to size the buffer suitably. +The caller must perform the following steps: +.RS +.IP 1. 3 +Use a +.B RTLD_DI_SERINFOSIZE +request to populate a +.I Dl_serinfo +structure with the size +.RI ( dls_size ) +of the structure needed for the subsequent +.B RTLD_DI_SERINFO +request. +.IP 2. +Allocate a +.I Dl_serinfo +buffer of the correct size +.RI ( dls_size ). +.IP 3. +Use a further +.B RTLD_DI_SERINFOSIZE +request to populate the +.I dls_size +and +.I dls_cnt +fields of the buffer allocated in the previous step. +.IP 4. +Use a +.B RTLD_DI_SERINFO +to obtain the library search paths. +.IP +.RE +.IP +The +.I Dl_serinfo +structure is defined as follows: +.IP +.in +4n +.EX +typedef struct { + size_t dls_size; /* Size in bytes of + the whole buffer */ + unsigned int dls_cnt; /* Number of elements + in 'dls_serpath' */ + Dl_serpath dls_serpath[1]; /* Actually longer, + 'dls_cnt' elements */ +} Dl_serinfo; +.EE +.in +.IP +Each of the +.I dls_serpath +elements in the above structure is a structure of the following form: +.IP +.in +4n +.EX +typedef struct { + char *dls_name; /* Name of library search + path directory */ + unsigned int dls_flags; /* Indicates where this + directory came from */ +} Dl_serpath; +.EE +.in +.IP +The +.I dls_flags +field is currently unused, and always contains zero. +.TP +.BR RTLD_DI_SERINFOSIZE " (\fIDl_serinfo *\fP)" +Populate the +.I dls_size +and +.I dls_cnt +fields of the +.I Dl_serinfo +structure pointed to by +.IR info +with values suitable for allocating a buffer for use in a subsequent +.B RTLD_DI_SERINFO +request. +.TP +.BR RTLD_DI_TLS_MODID " (\fIsize_t *\fP, since glibc 2.4)" +Obtain the module ID of this shared object's TLS (thread-local storage) +segment, as used in TLS relocations. +If this object does not define a TLS segment, zero is placed in +.IR *info . +.TP +.BR RTLD_DI_TLS_DATA " (\fIvoid **\fP, since glibc 2.4)" +Obtain a pointer to the calling +thread's TLS block corresponding to this shared object's TLS segment. +If this object does not define a PT_TLS segment, +or if the calling thread has not allocated a block for it, +NULL is placed in +.IR *info . +.SH RETURN VALUE +On success, +.BR dlinfo () +returns 0. +On failure, it returns \-1; the cause of the error can be diagnosed using +.BR dlerror (3). +.SH VERSIONS +.BR dlinfo () +first appeared in glibc 2.3.3. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR dlinfo () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is a nonstandard GNU extension. +.SH NOTES +This function derives from the Solaris function of the same name +and also appears on some other systems. +The sets of requests supported by the various implementations +overlaps only partially. +.SH EXAMPLE +The program below opens a shared objects using +.BR dlopen (3) +and then uses the +.B RTLD_DI_SERINFOSIZE +and +.B RTLD_DI_SERINFO +requests to obtain the library search path list for the library. +Here is an example of what we might see when running the program: +.PP +.in +4n +.EX +$ \fB./a.out /lib64/libm.so.6\fP +dls_serpath[0].dls_name = /lib64 +dls_serpath[1].dls_name = /usr/lib64 +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + void *handle; + Dl_serinfo serinfo; + Dl_serinfo *sip; + int j; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* Obtain a handle for shared objects specified on command line */ + + handle = dlopen(argv[1], RTLD_NOW); + if (handle == NULL) { + fprintf(stderr, "dlopen() failed: %s\\n", dlerror()); + exit(EXIT_FAILURE); + } + + /* Discover the size of the buffer that we must pass to + RTLD_DI_SERINFO */ + + if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\\n", dlerror()); + exit(EXIT_FAILURE); + } + + /* Allocate the buffer for use with RTLD_DI_SERINFO */ + + sip = malloc(serinfo.dls_size); + if (sip == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + + /* Initialize the \(aqdls_size\(aq and \(aqdls_cnt\(aq fields in the newly + allocated buffer */ + + if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\\n", dlerror()); + exit(EXIT_FAILURE); + } + + /* Fetch and print library search list */ + + if (dlinfo(handle, RTLD_DI_SERINFO, sip) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFO failed: %s\\n", dlerror()); + exit(EXIT_FAILURE); + } + + for (j = 0; j < serinfo.dls_cnt; j++) + printf("dls_serpath[%d].dls_name = %s\\n", + j, sip\->dls_serpath[j].dls_name); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlopen (3), +.BR dlsym (3), +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dlmopen.3 b/man3/dlmopen.3 new file mode 100644 index 0000000..15d0968 --- /dev/null +++ b/man3/dlmopen.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man3/dlopen.3 b/man3/dlopen.3 new file mode 100644 index 0000000..22b9091 --- /dev/null +++ b/man3/dlopen.3 @@ -0,0 +1,607 @@ +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" written by Adam J. Richter (adam@yggdrasil.com), +.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com). +.\" and Copyright 2003, 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified by David A. Wheeler 2000-11-28. +.\" Applied patch by Terran Melconian, aeb, 2001-12-14. +.\" Modified by Hacksaw 2003-03-13. +.\" Modified by Matt Domsch, 2003-04-09: _init and _fini obsolete +.\" Modified by Michael Kerrisk 2003-05-16. +.\" Modified by Walter Harms: dladdr, dlvsym +.\" Modified by Petr Baudis , 2008-12-04: dladdr caveat +.\" +.TH DLOPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +dlclose, dlopen, dlmopen \- +open and close a shared object +.SH SYNOPSIS +.B #include +.PP +.BI "void *dlopen(const char *" filename ", int " flags ); +.PP +.BI "int dlclose(void *" handle ); +.PP +.B #define _GNU_SOURCE +.br +.B #include +.PP +.BI "void *dlmopen (Lmid_t " lmid ", const char *" filename ", int " flags ); +.PP +Link with \fI\-ldl\fP. +.SH DESCRIPTION +.SS dlopen() +The function +.BR dlopen () +loads the dynamic shared object (shared library) +file named by the null-terminated +string +.I filename +and returns an opaque "handle" for the loaded object. +This handle is employed with other functions in the dlopen API, such as +.BR dlsym (3), +.BR dladdr (3), +.BR dlinfo (3), +and +.BR dlclose (). +.PP +If +.I filename +.\" FIXME On Solaris, when handle is NULL, we seem to get back +.\" a handle for (something like) the root of the namespace. +.\" The point here is that if we do a dlmopen(LM_ID_NEWLM), then +.\" the filename==NULL case returns a different handle than +.\" in the initial namespace. But, on glibc, the same handle is +.\" returned. This is probably a bug in glibc. +.\" +is NULL, then the returned handle is for the main program. +If +.I filename +contains a slash ("/"), then it is interpreted as a (relative +or absolute) pathname. +Otherwise, the dynamic linker searches for the object as follows +(see +.BR ld.so (8) +for further details): +.IP o 4 +(ELF only) If the executable file for the calling program +contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, +then the directories listed in the DT_RPATH tag are searched. +.IP o +If, at the time that the program was started, the environment variable +.B LD_LIBRARY_PATH +was defined to contain a colon-separated list of directories, +then these are searched. +(As a security measure, this variable is ignored for set-user-ID and +set-group-ID programs.) +.IP o +(ELF only) If the executable file for the calling program +contains a DT_RUNPATH tag, then the directories listed in that tag +are searched. +.IP o +The cache file +.I /etc/ld.so.cache +(maintained by +.BR ldconfig (8)) +is checked to see whether it contains an entry for +.IR filename . +.IP o +The directories +.I /lib +and +.I /usr/lib +are searched (in that order). +.PP +If the object specified by +.I filename +has dependencies on other shared objects, +then these are also automatically loaded by the dynamic linker +using the same rules. +(This process may occur recursively, +if those objects in turn have dependencies, and so on.) +.PP +One of the following two values must be included in +.IR flags : +.TP +.B RTLD_LAZY +Perform lazy binding. +Resolve symbols only as the code that references them is executed. +If the symbol is never referenced, then it is never resolved. +(Lazy binding is performed only for function references; +references to variables are always immediately bound when +the shared object is loaded.) +Since glibc 2.1.1, +.\" commit 12b5b6b7f78ea111e89bbf638294a5413c791072 +this flag is overridden by the effect of the +.B LD_BIND_NOW +environment variable. +.TP +.B RTLD_NOW +If this value is specified, or the environment variable +.B LD_BIND_NOW +is set to a nonempty string, +all undefined symbols in the shared object are resolved before +.BR dlopen () +returns. +If this cannot be done, an error is returned. +.PP +Zero or more of the following values may also be ORed in +.IR flags : +.TP +.B RTLD_GLOBAL +The symbols defined by this shared object will be +made available for symbol resolution of subsequently loaded shared objects. +.TP +.B RTLD_LOCAL +This is the converse of +.BR RTLD_GLOBAL , +and the default if neither flag is specified. +Symbols defined in this shared object are not made available to resolve +references in subsequently loaded shared objects. +.TP +.BR RTLD_NODELETE " (since glibc 2.2)" +Do not unload the shared object during +.BR dlclose (). +Consequently, the object's static variables are not reinitialized +if the object is reloaded with +.BR dlopen () +at a later time. +.TP +.BR RTLD_NOLOAD " (since glibc 2.2)" +Don't load the shared object. +This can be used to test if the object is already resident +.RB ( dlopen () +returns NULL if it is not, or the object's handle if it is resident). +This flag can also be used to promote the flags on a shared object +that is already loaded. +For example, a shared object that was previously loaded with +.B RTLD_LOCAL +can be reopened with +.BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . +.\" +.TP +.BR RTLD_DEEPBIND " (since glibc 2.3.4)" +.\" Inimitably described by UD in +.\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. +Place the lookup scope of the symbols in this +shared object ahead of the global scope. +This means that a self-contained object will use +its own symbols in preference to global symbols with the same name +contained in objects that have already been loaded. +.PP +If +.I filename +is NULL, then the returned handle is for the main program. +When given to +.BR dlsym (), +this handle causes a search for a symbol in the main program, +followed by all shared objects loaded at program startup, +and then all shared objects loaded by +.BR dlopen () +with the flag +.BR RTLD_GLOBAL . +.PP +External references in the shared object are resolved using the +shared objects in that object's dependency list and any other +objects previously opened with the +.B RTLD_GLOBAL +flag. +If the executable was linked with the flag "\-rdynamic" +(or, synonymously, "\-\-export\-dynamic"), +then the global symbols in the executable will also be used +to resolve references in a dynamically loaded shared object. +.PP +If the same shared object is loaded again with +.BR dlopen (), +the same object handle is returned. +The dynamic linker maintains reference +counts for object handles, so a dynamically loaded shared object is not +deallocated until +.BR dlclose () +has been called on it as many times as +.BR dlopen () +has succeeded on it. +Any initialization returns (see below) are called just once. +However, a subsequent +.BR dlopen () +call that loads the same shared object with +.B RTLD_NOW +may force symbol resolution for a shared object earlier loaded with +.BR RTLD_LAZY . +.PP +If +.BR dlopen () +fails for any reason, it returns NULL. +.\" +.SS dlmopen() +This function performs the same task as +.BR dlopen ()\(emthe +.I filename +and +.I flags +arguments, as well as the return value, are the same, +except for the differences noted below. +.PP +The +.BR dlmopen () +function differs from +.BR dlopen () +primarily in that it accepts an additional argument, +.IR lmid , +that specifies the link-map list (also referred to as a +.IR namespace ) +in which the shared object should be loaded. +(By comparison, +.BR dlopen () +adds the dynamically loaded shared object to the same namespace as +the shared object from which the +.BR dlopen () +call is made.) +The +.I Lmid_t +type is an opaque handle that refers to a namespace. +.PP +The +.I lmid +argument is either the ID of an existing namespace +.\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique? +(which can be obtained using the +.BR dlinfo (3) +.B RTLD_DI_LMID +request) or one of the following special values: +.TP +.B LM_ID_BASE +Load the shared object in the initial namespace +(i.e., the application's namespace). +.TP +.B LM_ID_NEWLM +Create a new namespace and load the shared object in that namespace. +The object must have been correctly linked +to reference all of the other shared objects that it requires, +since the new namespace is initially empty. +.PP +If +.I filename +is NULL, then the only permitted value for +.I lmid +is +.BR LM_ID_BASE . +.SS dlclose() +The function +.BR dlclose () +decrements the reference count on the +dynamically loaded shared object referred to by +.IR handle . +If the reference count drops to zero, +then the object is unloaded. +All shared objects that were automatically loaded when +.BR dlopen () +was invoked on the object referred to by +.I handle +are recursively closed in the same manner. +.PP +A successful return from +.BR dlclose () +does not guarantee that the symbols associated with +.I handle +are removed from the caller's address space. +In addition to references resulting from explicit +.BR dlopen () +calls, a shared object may have been implicitly loaded +(and reference counted) because of dependencies in other shared objects. +Only when all references have been released can the shared object +be removed from the address space. +.SH RETURN VALUE +On success, +.BR dlopen () +and +.BR dlmopen () +return a non-NULL handle for the loaded library. +On error +(file could not be found, was not readable, had the wrong format, +or caused errors during loading), +these functions return NULL. +.PP +On success, +.BR dlclose () +returns 0; on error, it returns a nonzero value. +.PP +Errors from these functions can be diagnosed using +.BR dlerror (3). +.SH VERSIONS +.BR dlopen () +and +.BR dlclose () +are present in glibc 2.0 and later. +.BR dlmopen () +first appeared in glibc 2.3.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR dlopen (), +.BR dlmopen (), +.BR dlclose () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001 describes +.BR dlclose () +and +.BR dlopen (). +The +.BR dlmopen () +function is a GNU extension. +.PP +The +.BR RTLD_NOLOAD , +.BR RTLD_NODELETE , +and +.BR RTLD_DEEPBIND +flags are GNU extensions; +the first two of these flags are also present on Solaris. +.SH NOTES +.SS dlmopen() and namespaces +A link-map list defines an isolated namespace for the +resolution of symbols by the dynamic linker. +Within a namespace, +dependent shared objects are implicitly loaded according to the usual rules, +and symbol references are likewise resolved according to the usual rules, +but such resolution is confined to the definitions provided by the +objects that have been (explicitly and implicitly) loaded into the namespace. +.PP +The +.BR dlmopen () +function permits object-load isolation\(emthe ability +to load a shared object in a new namespace without +exposing the rest of the application to the symbols +made available by the new object. +Note that the use of the +.B RTLD_LOCAL +flag is not sufficient for this purpose, +since it prevents a shared object's symbols from being available to +.I any +other shared object. +In some cases, +we may want to make the symbols provided by a dynamically +loaded shared object available to (a subset of) other shared objects +without exposing those symbols to the entire application. +This can be achieved by using a separate namespace and the +.B RTLD_GLOBAL +flag. +.PP +The +.BR dlmopen () +function also can be used to provide better isolation than the +.BR RTLD_LOCAL +flag. +In particular, shared objects loaded with +.BR RTLD_LOCAL +may be promoted to +.BR RTLD_GLOBAL +if they are dependencies of another shared object loaded with +.BR RTLD_GLOBAL . +Thus, +.BR RTLD_LOCAL +is insufficient to isolate a loaded shared object except in the (uncommon) +case where one has explicit control over all shared object dependencies. +.PP +Possible uses of +.BR dlmopen () +are plugins where the author of the plugin-loading framework +can't trust the plugin authors and does not wish +any undefined symbols from the plugin framework to be resolved to plugin +symbols. +Another use is to load the same object more than once. +Without the use of +.BR dlmopen (), +this would require the creation of distinct copies of the shared object file. +Using +.BR dlmopen (), +this can be achieved by loading the same shared object file into +different namespaces. +.PP +The glibc implementation supports a maximum of +.\" DL_NNS +16 namespaces. +.\" +.SS Initialization and finalization functions +Shared objects may export functions using the +.B __attribute__((constructor)) +and +.B __attribute__((destructor)) +function attributes. +Constructor functions are executed before +.BR dlopen () +returns, and destructor functions are executed before +.BR dlclose () +returns. +A shared object may export multiple constructors and destructors, +and priorities can be associated with each function +to determine the order in which they are executed. +See the +.BR gcc +info pages (under "Function attributes") +.\" info gcc "C Extensions" "Function attributes" +for further information. +.PP +An older method of (partially) achieving the same result is via the use of +two special symbols recognized by the linker: +.B _init +and +.BR _fini . +If a dynamically loaded shared object exports a routine named +.BR _init (), +then that code is executed after loading a shared object, before +.BR dlopen () +returns. +If the shared object exports a routine named +.BR _fini (), +then that routine is called just before the object is unloaded. +In this case, one must avoid linking against the system startup files, +which contain default versions of these files; +this can be done by using the +.BR gcc (1) +.I \-nostartfiles +command-line option. +.PP +Use of +.B _init +and +.BR _fini +is now deprecated in favor of the aforementioned +constructors and destructors, +which among other advantages, +permit multiple initialization and finalization functions to be defined. +.\" +.\" Using these routines, or the gcc +.\" .B \-nostartfiles +.\" or +.\" .B \-nostdlib +.\" options, is not recommended. +.\" Their use may result in undesired behavior, +.\" since the constructor/destructor routines will not be executed +.\" (unless special measures are taken). +.\" .\" void _init(void) __attribute__((constructor)); +.\" .\" void _fini(void) __attribute__((destructor)); +.\" +.PP +Since glibc 2.2.3, +.BR atexit (3) +can be used to register an exit handler that is automatically +called when a shared object is unloaded. +.SS History +These functions are part of the dlopen API, derived from SunOS. +.SH BUGS +As at glibc 2.24, specifying the +.BR RTLD_GLOBAL +flag when calling +.BR dlmopen () +.\" dlerror(): "invalid mode" +generates an error. +Furthermore, specifying +.BR RTLD_GLOBAL +when calling +.BR dlopen () +results in a program crash +.RB ( SIGSEGV ) +if the call is made from any object loaded in a +namespace other than the initial namespace. +.SH EXAMPLE +The program below loads the (glibc) math library, +looks up the address of the +.BR cos (3) +function, and prints the cosine of 2.0. +The following is an example of building and running the program: +.PP +.in +4n +.EX +$ \fBcc dlopen_demo.c \-ldl\fP +$ \fB./a.out\fP +\-0.416147 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include /* Defines LIBM_SO (which will be a + string such as "libm.so.6") */ +int +main(void) +{ + void *handle; + double (*cosine)(double); + char *error; + + handle = dlopen(LIBM_SO, RTLD_LAZY); + if (!handle) { + fprintf(stderr, "%s\en", dlerror()); + exit(EXIT_FAILURE); + } + + dlerror(); /* Clear any existing error */ + + cosine = (double (*)(double)) dlsym(handle, "cos"); + + /* According to the ISO C standard, casting between function + pointers and 'void *', as done above, produces undefined results. + POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and + proposed the following workaround: + + *(void **) (&cosine) = dlsym(handle, "cos"); + + This (clumsy) cast conforms with the ISO C standard and will + avoid any compiler warnings. + + The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a. + POSIX.1-2013) improved matters by requiring that conforming + implementations support casting 'void *' to a function pointer. + Nevertheless, some compilers (e.g., gcc with the '-pedantic' + option) may complain about the cast used in this program. */ +.\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08 +.\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07 +.\" http://austingroupbugs.net/view.php?id=74 + + error = dlerror(); + if (error != NULL) { + fprintf(stderr, "%s\en", error); + exit(EXIT_FAILURE); + } + + printf("%f\en", (*cosine)(2.0)); + dlclose(handle); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ld (1), +.BR ldd (1), +.BR pldd (1), +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlinfo (3), +.BR dlsym (3), +.BR rtld-audit (7), +.BR ld.so (8), +.BR ldconfig (8) +.PP +gcc info pages, ld info pages +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dlsym.3 b/man3/dlsym.3 new file mode 100644 index 0000000..3f6d448 --- /dev/null +++ b/man3/dlsym.3 @@ -0,0 +1,169 @@ +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" and Copyright 2003, 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH DLSYM 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +dlsym, dlvsym \- obtain address of a symbol in a shared object or executable +.SH SYNOPSIS +.B #include +.PP +.BI "void *dlsym(void *" handle ", const char *" symbol ); +.PP +.B #define _GNU_SOURCE +.br +.B #include +.PP +.BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version ); +.PP +Link with \fI\-ldl\fP. +.SH DESCRIPTION +The function +.BR dlsym () +takes a "handle" of a dynamic loaded shared object returned by +.BR dlopen (3) +along with a null-terminated symbol name, +and returns the address where that symbol is +loaded into memory. +If the symbol is not found, in the specified +object or any of the shared objects that were automatically loaded by +.BR dlopen (3) +when that object was loaded, +.BR dlsym () +returns NULL. +(The search performed by +.BR dlsym () +is breadth first through the dependency tree of these shared objects.) +.PP +Since the value of the symbol could actually be NULL (so that a +NULL return from +.BR dlsym () +need not indicate an error), the correct way to test for an error +is to call +.BR dlerror (3) +to clear any old error conditions, then call +.BR dlsym (), +and then call +.BR dlerror (3) +again, saving its return value into a variable, and check whether +this saved value is not NULL. +.PP +There are two special pseudo-handles that may be specified in +.IR handle : +.TP +.B RTLD_DEFAULT +Find the first occurrence of the desired symbol +using the default shared object search order. +The search will include global symbols in the executable +and its dependencies, +as well as symbols in shared objects that were dynamically loaded with the +.BR RTLD_GLOBAL +flag. +.TP +.BR RTLD_NEXT +Find the next occurrence of the desired symbol in the search order +after the current object. +This allows one to provide a wrapper +around a function in another shared object, so that, for example, +the definition of a function in a preloaded shared object +(see +.B LD_PRELOAD +in +.BR ld.so (8)) +can find and invoke the "real" function provided in another shared object +(or for that matter, the "next" definition of the function in cases +where there are multiple layers of preloading). +.PP +The +.B _GNU_SOURCE +feature test macro must be defined in order to obtain the +definitions of +.B RTLD_DEFAULT +and +.B RTLD_NEXT +from +.IR . +.PP +.PP +The function +.BR dlvsym () +does the same as +.BR dlsym () +but takes a version string as an additional argument. +.SH RETURN VALUE +On success, +these functions return the address associated with +.IR symbol . +On failure, they return NULL; +the cause of the error can be diagnosed using +.BR dlerror (3). +.SH VERSIONS +.BR dlsym () +is present in glibc 2.0 and later. +.BR dlvsym () +first appeared in glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR dlsym (), +.BR dlvsym () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001 describes +.BR dlsym (). +The +.BR dlvsym () +function is a GNU extension. +.SH NOTES +.SS History +The +.BR dlsym () +function is part of the dlopen API, derived from SunOS. +That system does not have +.BR dlvsym (). +.SH EXAMPLE +See +.BR dlopen (3). +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dlvsym.3 b/man3/dlvsym.3 new file mode 100644 index 0000000..df2ca09 --- /dev/null +++ b/man3/dlvsym.3 @@ -0,0 +1 @@ +.so man3/dlsym.3 diff --git a/man3/dn_comp.3 b/man3/dn_comp.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/dn_comp.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/dn_expand.3 b/man3/dn_expand.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/dn_expand.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/dprintf.3 b/man3/dprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man3/dprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/drand48.3 b/man3/drand48.3 new file mode 100644 index 0000000..2be166a --- /dev/null +++ b/man3/drand48.3 @@ -0,0 +1,288 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH DRAND48 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, +lcong48 \- generate uniformly distributed pseudo-random numbers +.SH SYNOPSIS +.nf +.B #include +.PP +.B double drand48(void); +.PP +.BI "double erand48(unsigned short " xsubi [3]); +.PP +.B long int lrand48(void); +.PP +.BI "long int nrand48(unsigned short " xsubi [3]); +.PP +.B long int mrand48(void); +.PP +.BI "long int jrand48(unsigned short " xsubi [3]); +.PP +.BI "void srand48(long int " seedval ); +.PP +.BI "unsigned short *seed48(unsigned short " seed16v [3]); +.PP +.BI "void lcong48(unsigned short " param [7]); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +All functions shown above: +.\" .BR drand48 (), +.\" .BR erand48 (), +.\" .BR lrand48 (), +.\" .BR nrand48 (), +.\" .BR mrand48 (), +.\" .BR jrand48 (), +.\" .BR srand48 (), +.\" .BR seed48 (), +.\" .BR lcong48 (): +_XOPEN_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.ad b +.SH DESCRIPTION +These functions generate pseudo-random numbers using the linear congruential +algorithm and 48-bit integer arithmetic. +.PP +The +.BR drand48 () +and +.BR erand48 () +functions return nonnegative +double-precision floating-point values uniformly distributed over the interval +[0.0,\ 1.0). +.PP +The +.BR lrand48 () +and +.BR nrand48 () +functions return nonnegative +long integers uniformly distributed over the interval [0,\ 2^31). +.PP +The +.BR mrand48 () +and +.BR jrand48 () +functions return signed long +integers uniformly distributed over the interval [\-2^31,\ 2^31). +.PP +The +.BR srand48 (), +.BR seed48 () +and +.BR lcong48 () +functions are +initialization functions, one of which should be called before using +.BR drand48 (), +.BR lrand48 () +or +.BR mrand48 (). +The functions +.BR erand48 (), +.BR nrand48 () +and +.BR jrand48 () +do not require +an initialization function to be called first. +.PP +All the functions work by generating a sequence of 48-bit integers, +.IR Xi , +according to the linear congruential formula: +.PP +.in +4n +.EX +.B Xn+1 = (aXn + c) mod m, where n >= 0 +.EE +.in +.PP +The parameter +.I m += 2^48, hence 48-bit integer arithmetic is performed. +Unless +.BR lcong48 () +is called, +.IR a +and +.I c +are given by: +.PP +.in +4n +.EX +.B a = 0x5DEECE66D +.B c = 0xB +.EE +.in +.PP +The value returned by any of the functions +.BR drand48 (), +.BR erand48 (), +.BR lrand48 (), +.BR nrand48 (), +.BR mrand48 () +or +.BR jrand48 () +is +computed by first generating the next 48-bit +.I Xi +in the sequence. +Then the appropriate number of bits, according to the type of data item to +be returned, is copied from the high-order bits of +.I Xi +and transformed +into the returned value. +.PP +The functions +.BR drand48 (), +.BR lrand48 () +and +.BR mrand48 () +store +the last 48-bit +.I Xi +generated in an internal buffer. +The functions +.BR erand48 (), +.BR nrand48 () +and +.BR jrand48 () +require the calling +program to provide storage for the successive +.I Xi +values in the array +argument +.IR xsubi . +The functions are initialized by placing the initial +value of +.I Xi +into the array before calling the function for the first +time. +.PP +The initializer function +.BR srand48 () +sets the high order 32-bits of +.I Xi +to the argument +.IR seedval . +The low order 16-bits are set +to the arbitrary value 0x330E. +.PP +The initializer function +.BR seed48 () +sets the value of +.I Xi +to +the 48-bit value specified in the array argument +.IR seed16v . +The +previous value of +.I Xi +is copied into an internal buffer and a +pointer to this buffer is returned by +.BR seed48 (). +.PP +The initialization function +.BR lcong48 () +allows the user to specify +initial values for +.IR Xi , +.I a +and +.IR c . +Array argument +elements +.I param[0\-2] +specify +.IR Xi , +.I param[3\-5] +specify +.IR a , +and +.I param[6] +specifies +.IR c . +After +.BR lcong48 () +has been called, a subsequent call to either +.BR srand48 () +or +.BR seed48 () +will restore the standard values of +.I a +and +.IR c . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lb lb lb +lw21 l lw22. +Interface Attribute Value +T{ +.BR drand48 (), +.BR erand48 (), +.BR lrand48 (), +.BR nrand48 (), +.BR mrand48 (), +.BR jrand48 (), +.BR srand48 (), +.BR seed48 (), +.BR lcong48 () +T} Thread safety T{ +MT-Unsafe race:drand48 +T} +.TE +.ad +.PP +The above +functions record global state information for the random number generator, +so they are not thread-safe. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.SH SEE ALSO +.BR rand (3), +.BR random (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/drand48_r.3 b/man3/drand48_r.3 new file mode 100644 index 0000000..fc49374 --- /dev/null +++ b/man3/drand48_r.3 @@ -0,0 +1,130 @@ +.\" Copyright 2003 Walter Harms, 2004 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Created 2004-10-31. Text taken from a page by Walter Harms, 2003-09-08 +.\" +.TH DRAND48_R 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +drand48_r, erand48_r, lrand48_r, nrand48_r, mrand48_r, jrand48_r, +srand48_r, seed48_r, lcong48_r +\- generate uniformly distributed pseudo-random numbers reentrantly +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int drand48_r(struct drand48_data *" buffer ", double *" result ); +.PP +.BI "int erand48_r(unsigned short " xsubi [3] "," +.BI " struct drand48_data *"buffer ", double *" result ");" +.PP +.BI "int lrand48_r(struct drand48_data *" buffer ", long int *" result ); +.PP +.BI "int nrand48_r(unsigned short int " xsubi[3] "," +.BI " struct drand48_data *"buffer ", long int *" result ");" +.PP +.BI "int mrand48_r(struct drand48_data *" buffer ",long int *" result ");" +.PP +.BI "int jrand48_r(unsigned short int " xsubi[3] "," +.BI " struct drand48_data *" buffer ", long int *" result ");" +.PP +.BI "int srand48_r(long int " seedval ", struct drand48_data *" buffer ");" +.PP +.BI "int seed48_r(unsigned short int " seed16v[3] "," +.BI " struct drand48_data *" buffer ");" +.PP +.BI "int lcong48_r(unsigned short int " param[7] "," +.BI " struct drand48_data *" buffer ");" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +All functions shown above: +.\" .BR drand48_r (), +.\" .BR erand48_r (), +.\" .BR lrand48_r (), +.\" .BR nrand48_r (), +.\" .BR mrand48_r (), +.\" .BR jrand48_r (), +.\" .BR srand48_r (), +.\" .BR seed48_r (), +.\" .BR lcong48_r (): + /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.ad b +.SH DESCRIPTION +These functions are the reentrant analogs of the functions described in +.BR drand48 (3). +Instead of modifying the global random generator state, they use +the supplied data +.IR buffer . +.PP +Before the first use, this struct must be initialized, for example, +by filling it with zeros, or by calling one of the functions +.BR srand48_r (), +.BR seed48_r (), +or +.BR lcong48_r (). +.SH RETURN VALUE +The return value is 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR drand48_r (), +.BR erand48_r (), +.BR lrand48_r (), +.BR nrand48_r (), +.BR mrand48_r (), +.BR jrand48_r (), +.BR srand48_r (), +.BR seed48_r (), +.BR lcong48_r () +T} Thread safety MT-Safe race:buffer +.TE +.ad +.SH CONFORMING TO +These functions are GNU extensions and are not portable. +.SH SEE ALSO +.BR drand48 (3), +.BR rand (3), +.BR random (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/drem.3 b/man3/drem.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man3/drem.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/dremf.3 b/man3/dremf.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man3/dremf.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/dreml.3 b/man3/dreml.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man3/dreml.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/duplocale.3 b/man3/duplocale.3 new file mode 100644 index 0000000..92ce7ee --- /dev/null +++ b/man3/duplocale.3 @@ -0,0 +1,196 @@ +'\" t +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH DUPLOCALE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +duplocale \- duplicate a locale object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "locale_t duplocale(locale_t " locobj ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR duplocale (): +.PD 0 +.RS 4 +.TP +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.SH DESCRIPTION +The +.BR duplocale () +function creates a duplicate of the locale object referred to by +.IR locobj . +.PP +If +.I locobj +is +.BR LC_GLOBAL_LOCALE , +.BR duplocale () +creates a locale object containing a copy of the global locale +determined by +.BR setlocale (3). +.SH RETURN VALUE +On success, +.BR duplocale () +returns a handle for the new locale object. +On error, it returns +.IR "(locale_t)\ 0", +and sets +.I errno +to indicate the cause of the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to create the duplicate locale object. +.SH VERSIONS +The +.BR duplocale () +function first appeared in version 2.3 of the GNU C library. +.SH CONFORMING TO +POSIX.1-2008. +.SH NOTES +Duplicating a locale can serve the following purposes: +.IP * 3 +To create a copy of a locale object in which one of more categories +are to be modified (using +.BR newlocale (3)). +.IP * +To obtain a handle for the current locale which can used in +other functions that employ a locale handle, such as +.BR toupper_l (3). +This is done by applying +.BR duplocale () +to the value returned by the following call: +.IP + loc = uselocale((locale_t) 0); +.IP +This technique is necessary, because the above +.BR uselocale (3) +call may return the value +.BR LC_GLOBAL_LOCALE , +which results in undefined behavior if passed to functions such as +.BR toupper_l (3). +Calling +.BR duplocale () +can be used to ensure that the +.BR LC_GLOBAL_LOCALE +value is converted into a usable locale object. +See EXAMPLE, below. +.PP +Each locale object created by +.BR duplocale () +should be deallocated using +.BR freelocale (3). +.SH EXAMPLE +The program below uses +.BR uselocale (3) +and +.BR duplocale () +to obtain a handle for the current locale which is then passed to +.BR toupper_l (3). +The program takes one command-line argument, +a string of characters that is converted to uppercase and +displayed on standard output. +An example of its use is the following: +.PP +.in +4n +.EX +$ \fB./a.out abc\fP +ABC +.EE +.in +.SS Program source +\& +.EX +#define _XOPEN_SOURCE 700 +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + locale_t loc, nloc; + char *p; + + if (argc != 2) { + fprintf(stderr, "Usage: %s string\\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* This sequence is necessary, because uselocale() might return + the value LC_GLOBAL_LOCALE, which can\(aqt be passed as an + argument to toupper_l() */ + + loc = uselocale((locale_t) 0); + if (loc == (locale_t) 0) + errExit("uselocale"); + + nloc = duplocale(loc); + if (nloc == (locale_t) 0) + errExit("duplocale"); + + for (p = argv[1]; *p; p++) + putchar(toupper_l(*p, nloc)); + + printf("\\n"); + + freelocale(nloc); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR freelocale (3), +.BR newlocale (3), +.BR setlocale (3), +.BR uselocale (3), +.BR locale (5), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/dysize.3 b/man3/dysize.3 new file mode 100644 index 0000000..2bf776e --- /dev/null +++ b/man3/dysize.3 @@ -0,0 +1,86 @@ +.\" Copyright 2001 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" aeb: some corrections +.TH DYSIZE 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +dysize \- get number of days for a given year +.SH SYNOPSIS +.B "#include " +.PP +.BI "int dysize(int " year ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR dysize (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +The function returns 365 for a normal year and 366 for a leap year. +The calculation for leap year is based on: +.PP +.in +4n +.EX +(year) %4 == 0 && ((year) %100 != 0 || (year) %400 == 0) +.EE +.in +.PP +The formula is defined in the macro +.I __isleap(year) +also found in +.IR . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR dysize () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function occurs in SunOS 4.x. +.SH NOTES +This is a compatibility function only. +Don't use it in new programs. +.\" The SCO version of this function had a year-2000 problem. +.SH SEE ALSO +.BR strftime (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/eaccess.3 b/man3/eaccess.3 new file mode 100644 index 0000000..9e50351 --- /dev/null +++ b/man3/eaccess.3 @@ -0,0 +1 @@ +.so man3/euidaccess.3 diff --git a/man3/ecb_crypt.3 b/man3/ecb_crypt.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man3/ecb_crypt.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man3/ecvt.3 b/man3/ecvt.3 new file mode 100644 index 0000000..c828aee --- /dev/null +++ b/man3/ecvt.3 @@ -0,0 +1,156 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:40:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Jun 25 12:10:47 1999 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH ECVT 3 2016-03-15 "" "Linux Programmer's Manual" +.SH NAME +ecvt, fcvt \- convert a floating-point number to a string +.SH SYNOPSIS +.B #include +.PP +.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ); +.PP +.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR ecvt (), +.BR fcvt (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.12: +.nf +(_XOPEN_SOURCE\ >=\ 500) ! (_POSIX_C_SOURCE\ >=\ 200112L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.fi +.TP 4 +Before glibc 2.12: +_SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH DESCRIPTION +The +.BR ecvt () +function converts \fInumber\fP to a null-terminated +string of \fIndigits\fP digits (where \fIndigits\fP is reduced to a +system-specific limit determined by the precision of a +.IR double ), +and returns a pointer to the string. +The high-order digit is nonzero, unless +.I number +is zero. +The low order digit is rounded. +The string itself does not contain a decimal point; however, +the position of the decimal point relative to the start of the string +is stored in \fI*decpt\fP. +A negative value for \fI*decpt\fP means that +the decimal point is to the left of the start of the string. +If the sign of +\fInumber\fP is negative, \fI*sign\fP is set to a nonzero value, +otherwise it is set to 0. +If +.I number +is zero, it is unspecified whether \fI*decpt\fP is 0 or 1. +.PP +The +.BR fcvt () +function is identical to +.BR ecvt (), +except that +\fIndigits\fP specifies the number of digits after the decimal point. +.SH RETURN VALUE +Both the +.BR ecvt () +and +.BR fcvt () +functions return a pointer to a +static string containing the ASCII representation of \fInumber\fP. +The static string is overwritten by each call to +.BR ecvt () +or +.BR fcvt (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ecvt () +T} Thread safety MT-Unsafe race:ecvt +T{ +.BR fcvt () +T} Thread safety MT-Unsafe race:fcvt +.TE +.SH CONFORMING TO +SVr2; +marked as LEGACY in POSIX.1-2001. +POSIX.1-2008 removes the specifications of +.BR ecvt () +and +.BR fcvt (), +recommending the use of +.BR sprintf (3) +instead (though +.BR snprintf (3) +may be preferable). +.SH NOTES +.\" Linux libc4 and libc5 specified the type of +.\" .I ndigits +.\" as +.\" .IR size_t . +Not all locales use a point as the radix character ("decimal point"). +.SH SEE ALSO +.BR ecvt_r (3), +.BR gcvt (3), +.BR qecvt (3), +.BR setlocale (3), +.BR sprintf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ecvt_r.3 b/man3/ecvt_r.3 new file mode 100644 index 0000000..7735b33 --- /dev/null +++ b/man3/ecvt_r.3 @@ -0,0 +1,124 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.\" Corrected return types; from Fabian; 2004-10-05 +.\" +.TH ECVT_R 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int ecvt_r(double " number ", int " ndigits ", int *" decpt , +.BI " int *" sign ", char *" buf ", size_t " len ); +.PP +.BI "int fcvt_r(double " number ", int " ndigits ", int *" decpt , +.BI " int *" sign ", char *" buf ", size_t " len ); +.PP +.BI "int qecvt_r(long double " number ", int " ndigits ", int *" decpt , +.BI " int *" sign ", char *" buf ", size_t " len ); +.PP +.BI "int qfcvt_r(long double " number ", int " ndigits ", int *" decpt , +.BI " int *" sign ", char *" buf ", size_t " len ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR ecvt_r (), +.BR fcvt_r (), +.BR qecvt_r (), +.BR qfcvt_r (): +.RS 4 +/* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.ad b +.SH DESCRIPTION +The functions +.BR ecvt_r (), +.BR fcvt_r (), +.BR qecvt_r (), +and +.BR qfcvt_r () +are identical to +.BR ecvt (3), +.BR fcvt (3), +.BR qecvt (3), +and +.BR qfcvt (3), +respectively, except that they do not return their result in a static +buffer, but instead use the supplied +.I buf +of size +.IR len . +See +.BR ecvt (3) +and +.BR qecvt (3). +.SH RETURN VALUE +These functions return 0 on success, and \-1 otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR ecvt_r (), +.BR fcvt_r (), +.br +.BR qecvt_r (), +.BR qfcvt_r () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +These functions are obsolete. +Instead, +.BR sprintf (3) +is recommended. +.SH SEE ALSO +.BR ecvt (3), +.BR qecvt (3), +.BR sprintf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/edata.3 b/man3/edata.3 new file mode 100644 index 0000000..94843fb --- /dev/null +++ b/man3/edata.3 @@ -0,0 +1 @@ +.so man3/end.3 diff --git a/man3/encrypt.3 b/man3/encrypt.3 new file mode 100644 index 0000000..a7fb0ba --- /dev/null +++ b/man3/encrypt.3 @@ -0,0 +1,213 @@ +.\" Copyright 2000 Nicolás Lichtmaier +.\" Created 2000-07-22 00:52-0300 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 2002-07-23 19:21:35 CEST 2002 Walter Harms +.\" +.\" +.\" Modified 2003-04-04, aeb +.\" +.TH ENCRYPT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +encrypt, setkey, encrypt_r, setkey_r \- encrypt 64-bit messages +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void encrypt(char " block "[64], int " edflag ); + +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void setkey(const char *" key ); + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B "#include " +.PP +.BI "void setkey_r(const char *" key ", struct crypt_data *" data ); +.BI "void encrypt_r(char *" block ", int " edflag \ +", struct crypt_data *" data ); +.fi +.PP +Each of these requires linking with \fI\-lcrypt\fP. +.SH DESCRIPTION +These functions encrypt and decrypt 64-bit messages. +The +.BR setkey () +function sets the key used by +.BR encrypt (). +The +.I key +argument used here is an array of 64 bytes, each of which has +numerical value 1 or 0. +The bytes key[n] where n=8*i-1 are ignored, +so that the effective key length is 56 bits. +.PP +The +.BR encrypt () +function modifies the passed buffer, encoding if +.I edflag +is 0, and decoding if 1 is being passed. +Like the +.I key +argument, also +.I block +is a bit vector representation of the actual value that is encoded. +The result is returned in that same vector. +.PP +These two functions are not reentrant, that is, the key data is +kept in static storage. +The functions +.BR setkey_r () +and +.BR encrypt_r () +are the reentrant versions. +They use the following +structure to hold the key data: +.PP +.in +4n +.EX +struct crypt_data { + char keysched[16 * 8]; + char sb0[32768]; + char sb1[32768]; + char sb2[32768]; + char sb3[32768]; + char crypt_3_buf[14]; + char current_salt[2]; + long int current_saltbits; + int direction; + int initialized; +}; +.EE +.in +.PP +Before calling +.BR setkey_r () +set +.I data\->initialized +to zero. +.SH RETURN VALUE +These functions do not return any value. +.SH ERRORS +Set +.I errno +to zero before calling the above functions. +On success, it is unchanged. +.TP +.B ENOSYS +The function is not provided. +(For example because of former USA export restrictions.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR encrypt (), +.BR setkey () +T} Thread safety MT-Unsafe race:crypt +T{ +.BR encrypt_r (), +.BR setkey_r () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR encrypt (), +.BR setkey (): +POSIX.1-2001, POSIX.1-2008, SUS, SVr4. +.PP +The functions +.BR encrypt_r () +and +.BR setkey_r () +are GNU extensions. +.SH NOTES +In glibc 2.2, these functions use the DES algorithm. +.SH EXAMPLE +.EX +#define _XOPEN_SOURCE +#include +#include +#include +#include + +int +main(void) +{ + char key[64]; + char orig[9] = "eggplant"; + char buf[64]; + char txt[9]; + int i, j; + + for (i = 0; i < 64; i++) { + key[i] = rand() & 1; + } + + for (i = 0; i < 8; i++) { + for (j = 0; j < 8; j++) { + buf[i * 8 + j] = orig[i] >> j & 1; + } + setkey(key); + } + printf("Before encrypting: %s\\n", orig); + + encrypt(buf, 0); + for (i = 0; i < 8; i++) { + for (j = 0, txt[i] = \(aq\\0\(aq; j < 8; j++) { + txt[i] |= buf[i * 8 + j] << j; + } + txt[8] = \(aq\\0\(aq; + } + printf("After encrypting: %s\\n", txt); + + encrypt(buf, 1); + for (i = 0; i < 8; i++) { + for (j = 0, txt[i] = \(aq\\0\(aq; j < 8; j++) { + txt[i] |= buf[i * 8 + j] << j; + } + txt[8] = \(aq\\0\(aq; + } + printf("After decrypting: %s\\n", txt); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR cbc_crypt (3), +.BR crypt (3), +.BR ecb_crypt (3), +.\" .BR fcrypt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/encrypt_r.3 b/man3/encrypt_r.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man3/encrypt_r.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man3/end.3 b/man3/end.3 new file mode 100644 index 0000000..626adc9 --- /dev/null +++ b/man3/end.3 @@ -0,0 +1,121 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH END 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +etext, edata, end \- end of program segments +.SH SYNOPSIS +.nf +.BI extern " etext" ; +.BI extern " edata" ; +.BI extern " end" ; +.fi +.SH DESCRIPTION +The addresses of these symbols indicate the end of various program +segments: +.TP +.I etext +This is the first address past the end of the text segment +(the program code). +.TP +.I edata +This is the first address past the end of the +initialized data segment. +.TP +.I end +This is the first address past the end of the +uninitialized data segment (also known as the BSS segment). +.SH CONFORMING TO +Although these symbols have long been provided on most UNIX systems, +they are not standardized; use with caution. +.SH NOTES +The program must explicitly declare these symbols; +they are not defined in any header file. +.PP +On some systems the names of these symbols are preceded by underscores, +thus: +.IR _etext , +.IR _edata , +and +.IR _end . +These symbols are also defined for programs compiled on Linux. +.PP +At the start of program execution, +the program break will be somewhere near +.IR &end +(perhaps at the start of the following page). +However, the break will change as memory is allocated via +.BR brk (2) +or +.BR malloc (3). +Use +.BR sbrk (2) +with an argument of zero to find the current value of the program break. +.SH EXAMPLE +When run, the program below produces output such as the following: +.PP +.in +4n +.EX +.RB "$" " ./a.out" +First address past: + program text (etext) 0x8048568 + initialized data (edata) 0x804a01c + uninitialized data (end) 0x804a024 +.EE +.in +.SS Program source +\& +.EX +#include +#include + +extern char etext, edata, end; /* The symbols must have some type, + or "gcc \-Wall" complains */ + +int +main(int argc, char *argv[]) +{ + printf("First address past:\\n"); + printf(" program text (etext) %10p\\n", &etext); + printf(" initialized data (edata) %10p\\n", &edata); + printf(" uninitialized data (end) %10p\\n", &end); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR objdump (1), +.BR readelf (1), +.BR sbrk (2), +.BR elf (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/endaliasent.3 b/man3/endaliasent.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man3/endaliasent.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/endfsent.3 b/man3/endfsent.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man3/endfsent.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man3/endgrent.3 b/man3/endgrent.3 new file mode 100644 index 0000000..bde736f --- /dev/null +++ b/man3/endgrent.3 @@ -0,0 +1 @@ +.so man3/getgrent.3 diff --git a/man3/endhostent.3 b/man3/endhostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/endhostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/endian.3 b/man3/endian.3 new file mode 100644 index 0000000..9c2c95e --- /dev/null +++ b/man3/endian.3 @@ -0,0 +1,185 @@ +.\" Copyright (C) 2009, Linux Foundation, written by Michael Kerrisk +.\" +.\" a few pieces remain from an earlier version +.\" Copyright (C) 2008, Nanno Langstraat +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ENDIAN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +htobe16, htole16, be16toh, le16toh, htobe32, htole32, be32toh, le32toh, +htobe64, htole64, be64toh, le64toh \- +convert values between host and big-/little-endian byte order +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "uint16_t htobe16(uint16_t " host_16bits ); +.BI "uint16_t htole16(uint16_t " host_16bits ); +.BI "uint16_t be16toh(uint16_t " big_endian_16bits ); +.BI "uint16_t le16toh(uint16_t " little_endian_16bits ); +.PP +.BI "uint32_t htobe32(uint32_t " host_32bits ); +.BI "uint32_t htole32(uint32_t " host_32bits ); +.BI "uint32_t be32toh(uint32_t " big_endian_32bits ); +.BI "uint32_t le32toh(uint32_t " little_endian_32bits ); +.PP +.BI "uint64_t htobe64(uint64_t " host_64bits ); +.BI "uint64_t htole64(uint64_t " host_64bits ); +.BI "uint64_t be64toh(uint64_t " big_endian_64bits ); +.BI "uint64_t le64toh(uint64_t " little_endian_64bits ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR htobe16 (), +.BR htole16 (), +.BR be16toh (), +.BR le16toh (), +.BR htobe32 (), +.BR htole32 (), +.BR be32toh (), +.BR le32toh (), +.BR htobe64 (), +.BR htole64 (), +.BR be64toh (), +.BR le64toh (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions convert the byte encoding of integer values from +the byte order that the current CPU (the "host") uses, +to and from little-endian and big-endian byte order. +.PP +The number, +.IR nn , +in the name of each function indicates the size of +integer handled by the function, either 16, 32, or 64 bits. +.PP +The functions with names of the form "htobe\fInn\fP" convert +from host byte order to big-endian order. +.PP +The functions with names of the form "htole\fInn\fP" convert +from host byte order to little-endian order. +.PP +The functions with names of the form "be\fInn\fPtoh" convert +from big-endian order to host byte order. +.PP +The functions with names of the form "le\fInn\fPtoh" convert +from little-endian order to host byte order. +.SH VERSIONS +These functions were added to glibc in version 2.9. +.SH CONFORMING TO +These functions are nonstandard. +Similar functions are present on the BSDs, +where the required header file is +.I +instead of +.IR . +Unfortunately, +NetBSD, FreeBSD, and glibc haven't followed the original +OpenBSD naming convention for these functions, +whereby the +.I nn +component always appears at the end of the function name +(thus, for example, in NetBSD, FreeBSD, and glibc, +the equivalent of OpenBSDs "betoh32" is "be32toh"). +.SH NOTES +These functions are similar to the older +.BR byteorder (3) +family of functions. +For example, +.BR be32toh () +is identical to +.BR ntohl (). +.PP +The advantage of the +.BR byteorder (3) +functions is that they are standard functions available +on all UNIX systems. +On the other hand, the fact that they were designed +for use in the context of TCP/IP means that +they lack the 64-bit and little-endian variants described in this page. +.SH EXAMPLE +The program below display the results of converting an integer +from host byte order to both little-endian and big-endian byte order. +Since host byte order is either little-endian or big-endian, +only one of these conversions will have an effect. +When we run this program on a little-endian system such as x86-32, +we see the following: +.PP +.in +4n +.EX +$ \fB./a.out\fP +x.u32 = 0x44332211 +htole32(x.u32) = 0x44332211 +htobe32(x.u32) = 0x11223344 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + union { + uint32_t u32; + uint8_t arr[4]; + } x; + + x.arr[0] = 0x11; /* Lowest-address byte */ + x.arr[1] = 0x22; + x.arr[2] = 0x33; + x.arr[3] = 0x44; /* Highest-address byte */ + + printf("x.u32 = 0x%x\\n", x.u32); + printf("htole32(x.u32) = 0x%x\\n", htole32(x.u32)); + printf("htobe32(x.u32) = 0x%x\\n", htobe32(x.u32)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bswap (3), +.BR byteorder (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/endmntent.3 b/man3/endmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man3/endmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/endnetent.3 b/man3/endnetent.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man3/endnetent.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man3/endnetgrent.3 b/man3/endnetgrent.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man3/endnetgrent.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man3/endprotoent.3 b/man3/endprotoent.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man3/endprotoent.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man3/endpwent.3 b/man3/endpwent.3 new file mode 100644 index 0000000..f2d121b --- /dev/null +++ b/man3/endpwent.3 @@ -0,0 +1 @@ +.so man3/getpwent.3 diff --git a/man3/endrpcent.3 b/man3/endrpcent.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man3/endrpcent.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man3/endservent.3 b/man3/endservent.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man3/endservent.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man3/endspent.3 b/man3/endspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/endspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/endttyent.3 b/man3/endttyent.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man3/endttyent.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man3/endusershell.3 b/man3/endusershell.3 new file mode 100644 index 0000000..718ed12 --- /dev/null +++ b/man3/endusershell.3 @@ -0,0 +1 @@ +.so man3/getusershell.3 diff --git a/man3/endutent.3 b/man3/endutent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/endutent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/endutxent.3 b/man3/endutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/endutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/envz.3 b/man3/envz.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man3/envz.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_add.3 b/man3/envz_add.3 new file mode 100644 index 0000000..986f8d7 --- /dev/null +++ b/man3/envz_add.3 @@ -0,0 +1,173 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH ENVZ_ADD 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +envz_add, envz_entry, envz_get, envz_merge, +envz_remove, envz_strip \- environment string support +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "error_t envz_add(char **" envz ", size_t *" envz_len , +.BI " const char *" name ", const char *" value ); +.PP +.BI "char *envz_entry(const char *" envz ", size_t " envz_len \ +", const char *" name ); +.PP +.BI "char *envz_get(const char *" envz ", size_t " envz_len \ +", const char *" name ); +.PP +.BI "error_t envz_merge(char **" envz ", size_t *" envz_len , +.BI " const char *" envz2 ", size_t " envz2_len \ +", int " override ); +.PP +.BI "void envz_remove(char **" envz ", size_t *" envz_len \ +", const char *" name ); +.PP +.BI "void envz_strip(char **" envz ", size_t *" envz_len ); +.fi +.SH DESCRIPTION +These functions are glibc-specific. +.PP +An argz vector is a pointer to a character buffer together with a length, +see +.BR argz_add (3). +An envz vector is a special argz vector, namely one where the strings +have the form "name=value". +Everything after the first \(aq=\(aq is considered +to be the value. +If there is no \(aq=\(aq, the value is taken to be NULL. +(While the value in case of a trailing \(aq=\(aq is the empty string "".) +.PP +These functions are for handling envz vectors. +.PP +.BR envz_add () +adds the string +.RI \&" name = value \&" +(in case +.I value +is non-NULL) or +.RI \&" name \&" +(in case +.I value +is NULL) to the envz vector +.RI ( *envz ,\ *envz_len ) +and updates +.I *envz +and +.IR *envz_len . +If an entry with the same +.I name +existed, it is removed. +.PP +.BR envz_entry () +looks for +.I name +in the envz vector +.RI ( envz ,\ envz_len ) +and returns the entry if found, or NULL if not. +.PP +.BR envz_get () +looks for +.I name +in the envz vector +.RI ( envz ,\ envz_len ) +and returns the value if found, or NULL if not. +(Note that the value can also be NULL, namely when there is +an entry for +.I name +without \(aq=\(aq sign.) +.PP +.BR envz_merge () +adds each entry in +.I envz2 +to +.IR *envz , +as if with +.BR envz_add (). +If +.I override +is true, then values in +.I envz2 +will supersede those with the same name in +.IR *envz , +otherwise not. +.PP +.BR envz_remove () +removes the entry for +.I name +from +.RI ( *envz ,\ *envz_len ) +if there was one. +.PP +.BR envz_strip () +removes all entries with value NULL. +.SH RETURN VALUE +All envz functions that do memory allocation have a return type of +.IR error_t , +and return 0 for success, and +.B ENOMEM +if an allocation error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR envz_add (), +.BR envz_entry (), +.br +.BR envz_get (), +.BR envz_merge (), +.br +.BR envz_remove (), +.BR envz_strip () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +These functions are a GNU extension. +Handle with care. +.SH EXAMPLE +.EX +#include +#include +#include + +int +main(int argc, char *argv[], char *envp[]) +{ + int i, e_len = 0; + char *str; + + for (i = 0; envp[i] != NULL; i++) + e_len += strlen(envp[i]) + 1; + + str = envz_entry(*envp, e_len, "HOME"); + printf("%s\en", str); + str = envz_get(*envp, e_len, "HOME"); + printf("%s\en", str); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR argz_add (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/envz_entry.3 b/man3/envz_entry.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man3/envz_entry.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_get.3 b/man3/envz_get.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man3/envz_get.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_merge.3 b/man3/envz_merge.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man3/envz_merge.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_remove.3 b/man3/envz_remove.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man3/envz_remove.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/envz_strip.3 b/man3/envz_strip.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man3/envz_strip.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man3/erand48.3 b/man3/erand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man3/erand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/erand48_r.3 b/man3/erand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man3/erand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/erf.3 b/man3/erf.3 new file mode 100644 index 0000000..e713d4a --- /dev/null +++ b/man3/erf.3 @@ -0,0 +1,152 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ERF 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +erf, erff, erfl, \- error function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double erf(double " x ); +.BI "float erff(float " x ); +.BI "long double erfl(long double " x ); +.PP +.fi +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR erf (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR erff (), +.BR erfl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return the error function of +.IR x , +defined as +.TP + erf(x) = 2/sqrt(pi)* integral from 0 to x of exp(\-t*t) dt +.SH RETURN VALUE +On success, these functions return the error function of +.IR x , +a value in the range [\-1,\ 1]. +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.PP +If +.I x +is positive infinity (negative infinity), ++1 (\-1) is returned. +.PP +If +.I x +is subnormal, +a range error occurs, +and the return value is 2*x/sqrt(pi). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error: result underflow (\fIx\fP is subnormal) +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6785 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR erf (), +.BR erff (), +.BR erfl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cerf (3), +.BR erfc (3), +.BR exp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/erfc.3 b/man3/erfc.3 new file mode 100644 index 0000000..5e76227 --- /dev/null +++ b/man3/erfc.3 @@ -0,0 +1,159 @@ +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ERFC 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +erfc, erfcf, erfcl \- complementary error function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double erfc(double " x ); +.BI "float erfcf(float " x ); +.BI "long double erfcl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR erfc (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR erfcf (), +.BR erfcl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return the complementary error function of +.IR x , +that is, 1.0 \- erf(x). +.SH RETURN VALUE +On success, these functions return the complementary error function of +.IR x , +a value in the range [0,2]. +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 or \-0, 1 is returned. +.PP +If +.I x +is positive infinity, ++0 is returned. +.PP +If +.I x +is negative infinity, ++2 is returned. +.PP +If the function result underflows and produces an unrepresentable value, +the return value is 0.0. +.PP +If the function result underflows but produces a representable +(i.e., subnormal) value, +.\" e.g., erfc(27) on x86-32 +that value is returned, and +a range error occurs. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error: result underflow (result is subnormal) +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6785 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR erfc (), +.BR erfcf (), +.BR erfcl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH NOTES +The +.BR erfc (), +.BR erfcf (), +and +.BR erfcl () +functions are provided to avoid the loss accuracy that +would occur for the calculation 1-erf(x) for large values of +.IR x +(for which the value of erf(x) approaches 1). +.SH SEE ALSO +.BR cerf (3), +.BR erf (3), +.BR exp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/erfcf.3 b/man3/erfcf.3 new file mode 100644 index 0000000..371bd6b --- /dev/null +++ b/man3/erfcf.3 @@ -0,0 +1 @@ +.so man3/erfc.3 diff --git a/man3/erfcl.3 b/man3/erfcl.3 new file mode 100644 index 0000000..371bd6b --- /dev/null +++ b/man3/erfcl.3 @@ -0,0 +1 @@ +.so man3/erfc.3 diff --git a/man3/erff.3 b/man3/erff.3 new file mode 100644 index 0000000..fc5471f --- /dev/null +++ b/man3/erff.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man3/erfl.3 b/man3/erfl.3 new file mode 100644 index 0000000..fc5471f --- /dev/null +++ b/man3/erfl.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man3/err.3 b/man3/err.3 new file mode 100644 index 0000000..1fb92f6 --- /dev/null +++ b/man3/err.3 @@ -0,0 +1,193 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" From: @(#)err.3 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD: src/lib/libc/gen/err.3,v 1.11.2.5 2001/08/17 15:42:32 ru Exp $ +.\" +.\" 2011-09-10, mtk, Converted from mdoc to man macros +.\" +.TH ERR 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void err(int " eval ", const char *" fmt ", ...);" +.PP +.BI "void errx(int " eval ", const char *" fmt ", ...);" +.PP +.BI "void warn(const char *" fmt ", ...);" +.PP +.BI "void warnx(const char *" fmt ", ...);" + +.B #include +.PP +.BI "void verr(int " eval ", const char *" fmt ", va_list " args ); +.PP +.BI "void verrx(int " eval ", const char *" fmt ", va_list " args ); +.PP +.BI "void vwarn(const char *" fmt ", va_list " args ); +.PP +.BI "void vwarnx(const char *" fmt ", va_list " args ); +.fi +.SH DESCRIPTION +The +.BR err () +and +.BR warn () +family of functions display a formatted error message on the standard +error output. +In all cases, the last component of the program name, a colon character, +and a space are output. +If the +.I fmt +argument is not NULL, the +.BR printf (3)-like +formatted error message is output. +The output is terminated by a newline character. +.PP +The +.BR err (), +.BR verr (), +.BR warn (), +and +.BR vwarn () +functions append an error message obtained from +.BR strerror (3) +based on the global variable +.IR errno , +preceded by another colon and space unless the +.I fmt +argument is +NULL. +.PP +The +.BR errx () +and +.BR warnx () +functions do not append an error message. +.PP +The +.BR err (), +.BR verr (), +.BR errx (), +and +.BR verrx () +functions do not return, but exit with the value of the argument +.IR eval . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw17 lb lb +l l l. +Interface Attribute Value +T{ +.BR err (), +.BR errx (), +.br +.BR warn (), +.BR warnx (), +.br +.BR verr (), +.BR verrx (), +.br +.BR vwarn (), +.BR vwarnx () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +These functions are nonstandard BSD extensions. +.\" .SH HISTORY +.\" The +.\" .BR err () +.\" and +.\" .BR warn () +.\" functions first appeared in +.\" 4.4BSD. +.SH EXAMPLE +Display the current +.I errno +information string and exit: +.PP +.in +4n +.EX +p = malloc(size); +if (p == NULL) + err(1, NULL); +fd = open(file_name, O_RDONLY, 0); +if (fd == \-1) + err(1, "%s", file_name); +.EE +.in +.PP +Display an error message and exit: +.PP +.in +4n +.EX +if (tm.tm_hour < START_TIME) + errx(1, "too early, wait until %s", start_time_string); +.EE +.in +.PP +Warn of an error: +.PP +.in +4n +.EX +fd = open(raw_device, O_RDONLY, 0); +if (fd == \-1) + warnx("%s: %s: trying the block device", + raw_device, strerror(errno)); +fd = open(block_device, O_RDONLY, 0); +if (fd == \-1) + err(1, "%s", block_device); +.EE +.in +.SH SEE ALSO +.BR error (3), +.BR exit (3), +.BR perror (3), +.BR printf (3), +.BR strerror (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/errno.3 b/man3/errno.3 new file mode 100644 index 0000000..2fe2a42 --- /dev/null +++ b/man3/errno.3 @@ -0,0 +1,654 @@ +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 5 Oct 2002, Modified by Michael Kerrisk +.\" Updated for POSIX.1 2001 +.\" 2004-12-17 Martin Schulze , mtk +.\" Removed errno declaration prototype, added notes +.\" 2006-02-09 Kurt Wall, mtk +.\" Added non-POSIX errors +.\" +.TH ERRNO 3 2018-02-02 "" "Linux Programmer's Manual" +.SH NAME +errno \- number of last error +.SH SYNOPSIS +.B #include +.\".PP +.\".BI "extern int " errno ; +.SH DESCRIPTION +The +.I +header file defines the integer variable +.IR errno , +which is set by system calls and some library functions in the event +of an error to indicate what went wrong. +.\" +.SS errno +The value in +.I errno +is significant only when the return value of +the call indicated an error +(i.e., \-1 from most system calls; +\-1 or NULL from most library functions); +a function that succeeds +.I is +allowed to change +.IR errno . +The value of +.I errno +is never set to zero by any system call or library function. +.PP +For some system calls and library functions (e.g., +.BR getpriority (2)), +\-1 is a valid return on success. +In such cases, a successful return can be distinguished from an error +return by setting +.I errno +to zero before the call, and then, +if the call returns a status that indicates that an error +may have occurred, checking to see if +.I errno +has a nonzero value. +.PP +.I errno +is defined by the ISO C standard to be a modifiable lvalue +of type +.IR int , +and must not be explicitly declared; +.I errno +may be a macro. +.I errno +is thread-local; setting it in one thread +does not affect its value in any other thread. +.\" +.SS Error numbers and names +Valid error numbers are all positive numbers. +The +.I +header file defines symbolic names for each +of the possible error numbers that may appear in +.IR errno . +.PP +All the error names specified by POSIX.1 +must have distinct values, with the exception of +.B EAGAIN +and +.BR EWOULDBLOCK , +which may be the same. +.PP +The error numbers that correspond to each symbolic name +vary across UNIX systems, +and even across different architectures on Linux. +Therefore, numeric values are not included as part of the list of +error names below. +The +.BR perror (3) +and +.BR strerror (3) +functions can be used to convert these names to +corresponding textual error messages. +.PP +On any particular Linux system, +one can obtain a list of all symbolic error names and +the corresponding error numbers using the +.BR errno (1) +command: +.PP +.in +4n +.EX +$ \fBerrno \-l\fP +EPERM 1 Operation not permitted +ENOENT 2 No such file or directory +ESRCH 3 No such process +EINTR 4 Interrupted system call +EIO 5 Input/output error +\&... +.EE +.in +.PP +The +.BR errno (1) +command can also be used to look up individual error numbers and names, +and to search for errors using strings from the error description, +as in the following examples: +.PP +.in +4n +.EX +$ \fBerrno 2\fP +ENOENT 2 No such file or directory +$ \fBerrno ESRCH\fP +ESRCH 3 No such process +$ \fBerrno \-s permission\fP +EACCES 13 Permission denied +.EE +.in +.PP +.\" POSIX.1 (2001 edition) lists the following symbolic error names. Of +.\" these, \fBEDOM\fP and \fBERANGE\fP are in the ISO C standard. ISO C +.\" Amendment 1 defines the additional error number \fBEILSEQ\fP for +.\" coding errors in multibyte or wide characters. +.\" +.SS List of error names +In the list of the symbolic error names below, +various names are marked as follows: +.IP * 3 +.IR POSIX.1-2001 : +The name is defined by POSIX.1-2001, +and is defined in later POSIX.1 versions, unless otherwise indicated. +.IP * +.IR POSIX.1-2008 : +The name is defined in POSIX.1-2008, +but was not present in earlier POSIX.1 standards. +.IP * +.IR C99 : +The name is defined by C99. +Below is a list of the symbolic error names that are defined on Linux: +.TP 16 +.B E2BIG +Argument list too long (POSIX.1-2001). +.TP +.B EACCES +Permission denied (POSIX.1-2001). +.TP +.B EADDRINUSE +Address already in use (POSIX.1-2001). +.TP +.B EADDRNOTAVAIL +Address not available (POSIX.1-2001). +.\" EADV is only an error on HURD(?) +.TP +.B EAFNOSUPPORT +Address family not supported (POSIX.1-2001). +.TP +.B EAGAIN +Resource temporarily unavailable (may be the same value as +.BR EWOULDBLOCK ) +(POSIX.1-2001). +.TP +.B EALREADY +Connection already in progress (POSIX.1-2001). +.TP +.B EBADE +Invalid exchange. +.TP +.B EBADF +Bad file descriptor (POSIX.1-2001). +.TP +.B EBADFD +File descriptor in bad state. +.TP +.B EBADMSG +Bad message (POSIX.1-2001). +.TP +.B EBADR +Invalid request descriptor. +.TP +.B EBADRQC +Invalid request code. +.TP +.B EBADSLT +Invalid slot. +.\" EBFONT is defined but appears not to be used by kernel or glibc. +.TP +.B EBUSY +Device or resource busy (POSIX.1-2001). +.TP +.B ECANCELED +Operation canceled (POSIX.1-2001). +.TP +.B ECHILD +No child processes (POSIX.1-2001). +.TP +.B ECHRNG +Channel number out of range. +.TP +.B ECOMM +Communication error on send. +.TP +.B ECONNABORTED +Connection aborted (POSIX.1-2001). +.TP +.B ECONNREFUSED +Connection refused (POSIX.1-2001). +.TP +.B ECONNRESET +Connection reset (POSIX.1-2001). +.TP +.B EDEADLK +Resource deadlock avoided (POSIX.1-2001). +.TP +.B EDEADLOCK +Synonym for +.BR EDEADLK . +.TP +.B EDESTADDRREQ +Destination address required (POSIX.1-2001). +.TP +.B EDOM +Mathematics argument out of domain of function (POSIX.1, C99). +.\" EDOTDOT is defined but appears to be unused +.TP +.B EDQUOT +.\" POSIX just says "Reserved" +Disk quota exceeded (POSIX.1-2001). +.TP +.B EEXIST +File exists (POSIX.1-2001). +.TP +.B EFAULT +Bad address (POSIX.1-2001). +.TP +.B EFBIG +File too large (POSIX.1-2001). +.TP +.B EHOSTDOWN +Host is down. +.TP +.B EHOSTUNREACH +Host is unreachable (POSIX.1-2001). +.TP +.B EHWPOISON +Memory page has hardware error. +.TP +.B EIDRM +Identifier removed (POSIX.1-2001). +.TP +.B EILSEQ +Invalid or incomplete multibyte or wide character (POSIX.1, C99). +.IP +The text shown here is the glibc error description; +in POSIX.1, this error is described as "Illegal byte sequence". +.TP +.B EINPROGRESS +Operation in progress (POSIX.1-2001). +.TP +.B EINTR +Interrupted function call (POSIX.1-2001); see +.BR signal (7). +.TP +.B EINVAL +Invalid argument (POSIX.1-2001). +.TP +.B EIO +Input/output error (POSIX.1-2001). +.TP +.B EISCONN +Socket is connected (POSIX.1-2001). +.TP +.B EISDIR +Is a directory (POSIX.1-2001). +.TP +.B EISNAM +Is a named type file. +.TP +.B EKEYEXPIRED +Key has expired. +.TP +.B EKEYREJECTED +Key was rejected by service. +.TP +.B EKEYREVOKED +Key has been revoked. +.TP +.B EL2HLT +Level 2 halted. +.TP +.B EL2NSYNC +Level 2 not synchronized. +.TP +.B EL3HLT +Level 3 halted. +.TP +.B EL3RST +Level 3 reset. +.TP +.B ELIBACC +Cannot access a needed shared library. +.TP +.B ELIBBAD +Accessing a corrupted shared library. +.TP +.B ELIBMAX +Attempting to link in too many shared libraries. +.TP +.B ELIBSCN +\&.lib section in a.out corrupted +.TP +.B ELIBEXEC +Cannot exec a shared library directly. +.TP +.B ELNRANGE +.\" ELNRNG appears to be used by a few drivers +Link number out of range. +.TP +.B ELOOP +Too many levels of symbolic links (POSIX.1-2001). +.TP +.B EMEDIUMTYPE +Wrong medium type. +.TP +.B EMFILE +Too many open files (POSIX.1-2001). +Commonly caused by exceeding the +.BR RLIMIT_NOFILE +resource limit described in +.BR getrlimit (2). +.TP +.B EMLINK +Too many links (POSIX.1-2001). +.TP +.B EMSGSIZE +Message too long (POSIX.1-2001). +.TP +.B EMULTIHOP +.\" POSIX says "Reserved" +Multihop attempted (POSIX.1-2001). +.TP +.B ENAMETOOLONG +Filename too long (POSIX.1-2001). +.\" ENAVAIL is defined, but appears not to be used +.TP +.B ENETDOWN +Network is down (POSIX.1-2001). +.TP +.B ENETRESET +Connection aborted by network (POSIX.1-2001). +.TP +.B ENETUNREACH +Network unreachable (POSIX.1-2001). +.TP +.B ENFILE +Too many open files in system (POSIX.1-2001). +On Linux, this is probably a result of encountering the +.IR /proc/sys/fs/file-max +limit (see +.BR proc (5)). +.TP +.B ENOANO +.\" ENOANO appears to be used by a few drivers +No anode. +.TP +.B ENOBUFS +No buffer space available (POSIX.1 (XSI STREAMS option)). +.\" ENOCSI is defined but appears to be unused. +.TP +.B ENODATA +No message is available on the STREAM head read queue (POSIX.1-2001). +.TP +.B ENODEV +No such device (POSIX.1-2001). +.TP +.B ENOENT +No such file or directory (POSIX.1-2001). +.IP +Typically, this error results when a specified pathname does not exist, +or one of the components in the directory prefix of a pathname does not exist, +or the specified pathname is a dangling symbolic link. +.TP +.B ENOEXEC +Exec format error (POSIX.1-2001). +.TP +.B ENOKEY +Required key not available. +.TP +.B ENOLCK +No locks available (POSIX.1-2001). +.TP +.B ENOLINK +.\" POSIX says "Reserved" +Link has been severed (POSIX.1-2001). +.TP +.B ENOMEDIUM +No medium found. +.TP +.B ENOMEM +Not enough space/cannot allocate memory (POSIX.1-2001). +.TP +.B ENOMSG +No message of the desired type (POSIX.1-2001). +.TP +.B ENONET +Machine is not on the network. +.TP +.B ENOPKG +Package not installed. +.TP +.B ENOPROTOOPT +Protocol not available (POSIX.1-2001). +.TP +.B ENOSPC +No space left on device (POSIX.1-2001). +.TP +.B ENOSR +No STREAM resources (POSIX.1 (XSI STREAMS option)). +.TP +.B ENOSTR +Not a STREAM (POSIX.1 (XSI STREAMS option)). +.TP +.B ENOSYS +Function not implemented (POSIX.1-2001). +.TP +.B ENOTBLK +Block device required. +.TP +.B ENOTCONN +The socket is not connected (POSIX.1-2001). +.TP +.B ENOTDIR +Not a directory (POSIX.1-2001). +.TP +.B ENOTEMPTY +Directory not empty (POSIX.1-2001). +.\" ENOTNAM is defined but appears to be unused. +.TP +.B ENOTRECOVERABLE +State not recoverable (POSIX.1-2008). +.TP +.B ENOTSOCK +Not a socket (POSIX.1-2001). +.TP +.B ENOTSUP +Operation not supported (POSIX.1-2001). +.TP +.B ENOTTY +Inappropriate I/O control operation (POSIX.1-2001). +.TP +.B ENOTUNIQ +Name not unique on network. +.TP +.B ENXIO +No such device or address (POSIX.1-2001). +.TP +.B EOPNOTSUPP +Operation not supported on socket (POSIX.1-2001). +.IP +.RB ( ENOTSUP +and +.B EOPNOTSUPP +have the same value on Linux, but +according to POSIX.1 these error values should be distinct.) +.TP +.B EOVERFLOW +Value too large to be stored in data type (POSIX.1-2001). +.TP +.B EOWNERDEAD +.\" Used at least by the user-space side of rubost mutexes +Owner died (POSIX.1-2008). +.TP +.B EPERM +Operation not permitted (POSIX.1-2001). +.TP +.B EPFNOSUPPORT +Protocol family not supported. +.TP +.B EPIPE +Broken pipe (POSIX.1-2001). +.TP +.B EPROTO +Protocol error (POSIX.1-2001). +.TP +.B EPROTONOSUPPORT +Protocol not supported (POSIX.1-2001). +.TP +.B EPROTOTYPE +Protocol wrong type for socket (POSIX.1-2001). +.TP +.B ERANGE +Result too large (POSIX.1, C99). +.TP +.B EREMCHG +Remote address changed. +.TP +.B EREMOTE +Object is remote. +.TP +.B EREMOTEIO +Remote I/O error. +.TP +.B ERESTART +Interrupted system call should be restarted. +.TP +.B ERFKILL +.\" ERFKILL appears to be used by various drivers +Operation not possible due to RF-kill. +.TP +.B EROFS +Read-only filesystem (POSIX.1-2001). +.TP +.B ESHUTDOWN +Cannot send after transport endpoint shutdown. +.TP +.B ESPIPE +Invalid seek (POSIX.1-2001). +.TP +.B ESOCKTNOSUPPORT +Socket type not supported. +.TP +.B ESRCH +No such process (POSIX.1-2001). +.\" ESRMNT is defined but appears not to be used +.TP +.B ESTALE +Stale file handle (POSIX.1-2001). +.IP +This error can occur for NFS and for other filesystems. +.TP +.B ESTRPIPE +Streams pipe error. +.TP +.B ETIME +Timer expired +(POSIX.1 (XSI STREAMS option)). +.IP +(POSIX.1 says "STREAM +.BR ioctl (2) +timeout".) +.TP +.B ETIMEDOUT +Connection timed out (POSIX.1-2001). +.TP +.B ETOOMANYREFS +.\" ETOOMANYREFS seems to be used in net/unix/af_unix.c +Too many references: cannot splice. +.TP +.B ETXTBSY +Text file busy (POSIX.1-2001). +.TP +.B EUCLEAN +Structure needs cleaning. +.TP +.B EUNATCH +Protocol driver not attached. +.TP +.B EUSERS +Too many users. +.TP +.B EWOULDBLOCK +Operation would block (may be same value as +.BR EAGAIN ) +(POSIX.1-2001). +.TP +.B EXDEV +Improper link (POSIX.1-2001). +.TP +.B EXFULL +Exchange full. +.SH NOTES +A common mistake is to do +.PP +.in +4n +.EX +if (somecall() == \-1) { + printf("somecall() failed\en"); + if (errno == ...) { ... } +} +.EE +.in +.PP +where +.I errno +no longer needs to have the value it had upon return from +.IR somecall () +(i.e., it may have been changed by the +.BR printf (3)). +If the value of +.I errno +should be preserved across a library call, it must be saved: +.PP +.in +4n +.EX +if (somecall() == \-1) { + int errsv = errno; + printf("somecall() failed\en"); + if (errsv == ...) { ... } +} +.EE +.in +.PP +On some ancient systems, +.I +was not present or did not declare +.IR errno , +so that it was necessary to declare +.I errno +manually +(i.e., +.IR "extern int errno" ). +.BR "Do not do this" . +It long ago ceased to be necessary, +and it will cause problems with modern versions of the C library. +.SH SEE ALSO +.BR errno (1), \" In the moreutils package +.BR err (3), +.BR error (3), +.BR perror (3), +.BR strerror (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/error.3 b/man3/error.3 new file mode 100644 index 0000000..353984e --- /dev/null +++ b/man3/error.3 @@ -0,0 +1,174 @@ +.\" Copyright (C) 2006 Justin Pryzby +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.TH ERROR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +error, error_at_line, error_message_count, error_one_per_line, +error_print_progname \- glibc error reporting functions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void error(int " status ", int " errnum ", const char *" format ", ...);" +.PP +.BI "void error_at_line(int " status ", int " errnum ", const char *" filename , +.BI " unsigned int " linenum ", const char *" format ", ...);" +.PP +.BI "extern unsigned int " error_message_count ; +.PP +.BI "extern int " error_one_per_line ; +.PP +.BI "extern void (*" error_print_progname ") (void);" +.fi +.SH DESCRIPTION +.BR error () +is a general error-reporting function. +It flushes +.IR stdout , +and then outputs to +.I stderr +the program name, a colon and a space, the message specified by the +.BR printf (3)-style +format string \fIformat\fP, and, if \fIerrnum\fP is +nonzero, a second colon and a space followed by the string given by +.IR strerror(errnum) . +Any arguments required for +.I format +should follow +.I format +in the argument list. +The output is terminated by a newline character. +.PP +The program name printed by +.BR error () +is the value of the global variable +.BR program_invocation_name (3). +.I program_invocation_name +initially has the same value as +.IR main ()'s +.IR argv[0] . +The value of this variable can be modified to change the output of +.BR error (). +.PP +If \fIstatus\fP has a nonzero value, then +.BR error () +calls +.BR exit (3) +to terminate the program using the given value as the exit status. +.PP +The +.BR error_at_line () +function is exactly the same as +.BR error (), +except for the addition of the arguments +.I filename +and +.IR linenum . +The output produced is as for +.BR error (), +except that after the program name are written: a colon, the value of +.IR filename , +a colon, and the value of +.IR linenum . +The preprocessor values \fB__LINE__\fP and +\fB__FILE__\fP may be useful when calling +.BR error_at_line (), +but other values can also be used. +For example, these arguments could refer to a location in an input file. +.PP +If the global variable \fIerror_one_per_line\fP is set nonzero, +a sequence of +.BR error_at_line () +calls with the +same value of \fIfilename\fP and \fIlinenum\fP will result in only +one message (the first) being output. +.PP +The global variable \fIerror_message_count\fP counts the number of +messages that have been output by +.BR error () +and +.BR error_at_line (). +.PP +If the global variable \fIerror_print_progname\fP +is assigned the address of a function +(i.e., is not NULL), then that function is called +instead of prefixing the message with the program name and colon. +The function should print a suitable string to +.IR stderr . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lb lb lbw33 +l l l. +Interface Attribute Value +T{ +.BR error () +T} Thread safety MT-Safe locale +T{ +.BR error_at_line () +T} Thread safety T{ +MT-Unsafe\ race: error_at_line/error_one_per_line locale +T} +.TE +.ad +.PP +The internal +.I error_one_per_line +variable is accessed (without any form of synchronization, but since it's an +.I int +used once, it should be safe enough) and, if +.I error_one_per_line +is set nonzero, the internal static variables (not exposed to users) +used to hold the last printed filename and line number are accessed +and modified without synchronization; the update is not atomic and it +occurs before disabling cancellation, so it can be interrupted only after +one of the two variables is modified. +After that, +.BR error_at_line () +is very much like +.BR error (). +.SH CONFORMING TO +These functions and variables are GNU extensions, and should not be +used in programs intended to be portable. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR exit (3), +.BR perror (3), +.BR program_invocation_name (3), +.BR strerror (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/error_at_line.3 b/man3/error_at_line.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man3/error_at_line.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man3/error_message_count.3 b/man3/error_message_count.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man3/error_message_count.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man3/error_one_per_line.3 b/man3/error_one_per_line.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man3/error_one_per_line.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man3/error_print_progname.3 b/man3/error_print_progname.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man3/error_print_progname.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man3/errx.3 b/man3/errx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man3/errx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/etext.3 b/man3/etext.3 new file mode 100644 index 0000000..94843fb --- /dev/null +++ b/man3/etext.3 @@ -0,0 +1 @@ +.so man3/end.3 diff --git a/man3/ether_aton.3 b/man3/ether_aton.3 new file mode 100644 index 0000000..9aad3fb --- /dev/null +++ b/man3/ether_aton.3 @@ -0,0 +1,167 @@ +.\" Copyright 2002 Ian Redfern (redferni@logica.com) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" FreeBSD 4.4 man pages +.\" +.\" Minor additions, aeb, 2013-06-21 +.\" +.TH ETHER_ATON 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line, +ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *ether_ntoa(const struct ether_addr *" addr ); +.PP +.BI "struct ether_addr *ether_aton(const char *" asc ); +.PP +.BI "int ether_ntohost(char *" hostname ", const struct ether_addr *" addr ); +.PP +.BI "int ether_hostton(const char *" hostname ", struct ether_addr *" addr ); +.PP +.BI "int ether_line(const char *" line ", struct ether_addr *" addr , +.BI " char *" hostname ); +.PP +/* GNU extensions */ +.br +.BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf ); +.PP +.BI "struct ether_addr *ether_aton_r(const char *" asc , +.BI " struct ether_addr *" addr ); +.fi +.SH DESCRIPTION +.BR ether_aton () +converts the 48-bit Ethernet host address +.I asc +from the standard hex-digits-and-colons notation into binary data in +network byte order and returns a pointer to it in a statically +allocated buffer, which subsequent calls will +overwrite. +.BR ether_aton () +returns NULL if the address is invalid. +.PP +The +.BR ether_ntoa () +function converts the Ethernet host address +.I addr +given in network byte order to a string in standard +hex-digits-and-colons notation, omitting leading zeros. +The string is returned in a statically allocated buffer, +which subsequent calls will overwrite. +.PP +The +.BR ether_ntohost () +function maps an Ethernet address to the +corresponding hostname in +.I /etc/ethers +and returns nonzero if it cannot be found. +.PP +The +.BR ether_hostton () +function maps a hostname to the +corresponding Ethernet address in +.I /etc/ethers +and returns nonzero if it cannot be found. +.PP +The +.BR ether_line () +function parses a line in +.I /etc/ethers +format (ethernet address followed by whitespace followed by +hostname; \(aq#\(aq introduces a comment) and returns an address +and hostname pair, or nonzero if it cannot be parsed. +The buffer pointed to by +.I hostname +must be sufficiently long, for example, have the same length as +.IR line . +.PP +The functions +.BR ether_ntoa_r () +and +.BR ether_aton_r () +are reentrant +thread-safe versions of +.BR ether_ntoa () +and +.BR ether_aton () +respectively, and do not use static buffers. +.PP +The structure +.I ether_addr +is defined in +.I +as: +.PP +.in +4n +.EX +struct ether_addr { + uint8_t ether_addr_octet[6]; +} +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw33 lb lb +l l l. +Interface Attribute Value +T{ +.BR ether_aton (), +.BR ether_ntoa () +T} Thread safety MT-Unsafe +T{ +.BR ether_ntohost (), +.BR ether_hostton (), +.BR ether_line (), +.BR ether_ntoa_r (), +.BR ether_aton_r () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +4.3BSD, SunOS. +.SH BUGS +In glibc 2.2.5 and earlier, the implementation of +.BR ether_line () +.\" The fix was presumably commit c0a0f9a32c8baa6ab93d00eb42d92c02e9e146d7 +.\" which was in glibc 2.3 +is broken. +.SH SEE ALSO +.BR ethers (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ether_aton_r.3 b/man3/ether_aton_r.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man3/ether_aton_r.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_hostton.3 b/man3/ether_hostton.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man3/ether_hostton.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_line.3 b/man3/ether_line.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man3/ether_line.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_ntoa.3 b/man3/ether_ntoa.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man3/ether_ntoa.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_ntoa_r.3 b/man3/ether_ntoa_r.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man3/ether_ntoa_r.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/ether_ntohost.3 b/man3/ether_ntohost.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man3/ether_ntohost.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man3/euidaccess.3 b/man3/euidaccess.3 new file mode 100644 index 0000000..96551dd --- /dev/null +++ b/man3/euidaccess.3 @@ -0,0 +1,126 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH EUIDACCESS 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +euidaccess, eaccess \- check effective user's permissions for a file +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int euidaccess(const char *" pathname ", int " mode ); +.BI "int eaccess(const char *" pathname ", int " mode ); +.fi +.SH DESCRIPTION +Like +.BR access (2), +.BR euidaccess () +checks permissions and existence of the file identified by its argument +.IR pathname . +However, whereas +.BR access (2) +performs checks using the real user and group identifiers of the process, +.BR euidaccess () +uses the effective identifiers. +.PP +.I mode +is a mask consisting of one or more of +.BR R_OK ", " W_OK ", " X_OK ", and " F_OK , +with the same meanings as for +.BR access (2). +.PP +.BR eaccess () +is a synonym for +.BR euidaccess (), +provided for compatibility with some other systems. +.SH RETURN VALUE +On success (all requested permissions granted), zero is returned. +On error (at least one bit in +.I mode +asked for a permission that is denied, or some other error occurred), +\-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +As for +.BR access (2). +.SH VERSIONS +The +.BR eaccess () +function was added to glibc in version 2.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR euidaccess (), +.BR eaccess () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are nonstandard. +Some other systems have an +.\" e.g., FreeBSD 6.1. +.BR eaccess () +function. +.SH NOTES +.IR Warning : +Using this function to check a process's permissions on a file before +performing some operation based on that information leads to race conditions: +the file permissions may change between the two steps. +Generally, it is safer just to attempt the desired operation and handle +any permission error that occurs. +.PP +This function always dereferences symbolic links. +If you need to check the permissions on a symbolic link, use +.BR faccessat (2) +with the flags +.BR AT_EACCESS +and +.BR AT_SYMLINK_NOFOLLOW . +.SH SEE ALSO +.BR access (2), +.BR chmod (2), +.BR chown (2), +.BR faccessat (2), +.BR open (2), +.BR setgid (2), +.BR setuid (2), +.BR stat (2), +.BR credentials (7), +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/eventfd_read.3 b/man3/eventfd_read.3 new file mode 100644 index 0000000..eddfaa8 --- /dev/null +++ b/man3/eventfd_read.3 @@ -0,0 +1 @@ +.so man2/eventfd.2 diff --git a/man3/eventfd_write.3 b/man3/eventfd_write.3 new file mode 100644 index 0000000..eddfaa8 --- /dev/null +++ b/man3/eventfd_write.3 @@ -0,0 +1 @@ +.so man2/eventfd.2 diff --git a/man3/exec.3 b/man3/exec.3 new file mode 100644 index 0000000..6edc3be --- /dev/null +++ b/man3/exec.3 @@ -0,0 +1,297 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)exec.3 6.4 (Berkeley) 4/19/91 +.\" +.\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu +.\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com +.\" Modified, 24 Jun 2004, Michael Kerrisk +.\" Added note on casting NULL +.\" +.TH EXEC 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +execl, execlp, execle, execv, execvp, execvpe \- execute a file +.SH SYNOPSIS +.nf +.B #include +.PP +.B extern char **environ; +.PP +.BI "int execl(const char *" path ", const char *" arg ", ..." +.B " /* (char *) NULL */);" +.BI "int execlp(const char *" file ", const char *" arg ", ..." +.B " /* (char *) NULL */);" +.BI "int execle(const char *" path ", const char *" arg ", ..." +.BI " /*, (char *) NULL, char * const " envp "[] */);" +.BI "int execv(const char *" path ", char *const " argv "[]);" +.BI "int execvp(const char *" file ", char *const " argv "[]);" +.BI "int execvpe(const char *" file ", char *const " argv "[]," +.BI " char *const " envp "[]);" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR execvpe (): +_GNU_SOURCE +.SH DESCRIPTION +The +.BR exec () +family of functions replaces the current process image with a new process +image. +The functions described in this manual page are front-ends for +.BR execve (2). +(See the manual page for +.BR execve (2) +for further details about the replacement of the current process image.) +.PP +The initial argument for these functions is the name of a file that is +to be executed. +.PP +The +.I "const char\ *arg" +and subsequent ellipses in the +.BR execl (), +.BR execlp (), +and +.BR execle () +functions can be thought of as +.IR arg0 , +.IR arg1 , +\&..., +.IR argn . +Together they describe a list of one or more pointers to null-terminated +strings that represent the argument list available to the executed program. +The first argument, by convention, should point to the filename associated +with the file being executed. +The list of arguments +.I must +be terminated by a null pointer, +and, since these are variadic functions, this pointer must be cast +.IR "(char\ *) NULL" . +.PP +The +.BR execv (), +.BR execvp (), +and +.BR execvpe () +functions provide an array of pointers to null-terminated strings that +represent the argument list available to the new program. +The first argument, by convention, should point to the filename +associated with the file being executed. +The array of pointers +.I must +be terminated by a null pointer. +.PP +The +.BR execle () +and +.BR execvpe () +functions allow the caller to specify the environment of the +executed program via the argument +.IR envp . +The +.I envp +argument is an array of pointers to null-terminated strings and +.I must +be terminated by a null pointer. +The other functions take the environment for the new process +image from the external variable +.I environ +in the calling process. +.SS Special semantics for execlp() and execvp() +.PP +The +.BR execlp (), +.BR execvp (), +and +.BR execvpe () +functions duplicate the actions of the shell in +searching for an executable file +if the specified filename does not contain a slash (/) character. +The file is sought in the colon-separated list of directory pathnames +specified in the +.B PATH +environment variable. +If this variable isn't defined, the path list defaults to +a list that includes the directories returned by +.IR confstr(_CS_PATH) +(which typically returns the value "/bin:/usr/bin") +and possibly also the current working directory; +see NOTES for further details. +.PP +If the specified filename includes a slash character, then +.B PATH +is ignored, and the file at the specified pathname is executed. +.PP +In addition, certain errors are treated specially. +.PP +If permission is denied for a file (the attempted +.BR execve (2) +failed with the error +.BR EACCES ), +these functions will continue searching the rest of the search path. +If no other file is found, however, +they will return with +.I errno +set to +.BR EACCES . +.PP +If the header of a file isn't recognized (the attempted +.BR execve (2) +failed with the error +.BR ENOEXEC ), +these functions will execute the shell +.RI ( /bin/sh ) +with the path of the file as its first argument. +(If this attempt fails, no further searching is done.) +.SH RETURN VALUE +The +.BR exec () +functions return only if an error has occurred. +The return value is \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +All of these functions may fail and set +.I errno +for any of the errors specified for +.BR execve (2). +.SH VERSIONS +The +.BR execvpe () +function first appeared in glibc 2.11. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw29 lb lb +l l l. +Interface Attribute Value +T{ +.BR execl (), +.BR execle (), +.BR execv () +T} Thread safety MT-Safe +T{ +.BR execlp (), +.BR execvp (), +.BR execvpe () +T} Thread safety MT-Safe env +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.PP +The +.BR execvpe () +function is a GNU extension. +.SH NOTES +The default search path (used when the environment +does not contain the variable \fBPATH\fR) +shows some variation across systems. +It generally includes +.I /bin +and +.IR /usr/bin +(in that order) and may also include the current working directory. +On some other systems, the current working is included after +.I /bin +and +.IR /usr/bin , +as an anti-Trojan-horse measure. +The glibc implementation long followed the traditional default where +the current working directory is included at the start of the search path. +However, some code refactoring during the development of glibc 2.24 +.\" glibc commit 1eb8930608705702d5746e5491bab4e4429fcb83 +caused the current working directory to be dropped altogether +from the default search path. +This accidental behavior change is considered mildly beneficial, +and won't be reverted. +.PP +The behavior of +.BR execlp () +and +.BR execvp () +when errors occur while attempting to execute the file is historic +practice, but has not traditionally been documented and is not specified by +the POSIX standard. +BSD (and possibly other systems) do an automatic +sleep and retry if +.B ETXTBSY +is encountered. +Linux treats it as a hard +error and returns immediately. +.PP +Traditionally, the functions +.BR execlp () +and +.BR execvp () +ignored all errors except for the ones described above and +.B ENOMEM +and +.BR E2BIG , +upon which they returned. +They now return if any error other than the ones +described above occurs. +.SH BUGS +Before glibc 2.24, +.BR execl () +and +.BR execle () +employed +.BR realloc (3) +internally and were consequently not async-signal-safe, +in violation of the requirements of POSIX.1. +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534 +This was fixed in glibc 2.24. +.SH SEE ALSO +.BR sh (1), +.BR execve (2), +.BR execveat (2), +.BR fork (2), +.BR ptrace (2), +.BR fexecve (3), +.BR system (3), +.BR environ (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/execl.3 b/man3/execl.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man3/execl.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execle.3 b/man3/execle.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man3/execle.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execlp.3 b/man3/execlp.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man3/execlp.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execv.3 b/man3/execv.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man3/execv.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execvp.3 b/man3/execvp.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man3/execvp.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/execvpe.3 b/man3/execvpe.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man3/execvpe.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man3/exit.3 b/man3/exit.3 new file mode 100644 index 0000000..8693ca3 --- /dev/null +++ b/man3/exit.3 @@ -0,0 +1,222 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" FIXME . There are a lot of other process termination actions that +.\" could be listed on this page. See, for example, the list in the +.\" POSIX exit(3p) page. +.\" +.TH EXIT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +exit \- cause normal process termination +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void exit(int " status ); +.fi +.SH DESCRIPTION +The +.BR exit () +function causes normal process termination and the +value of \fIstatus & 0377\fP is returned to the parent +(see +.BR wait (2)). +.PP +All functions registered with +.BR atexit (3) +and +.BR on_exit (3) +are called, in the reverse order of their registration. +(It is possible for one of these functions to use +.BR atexit (3) +or +.BR on_exit (3) +to register an additional +function to be executed during exit processing; +the new registration is added to the front of the list of functions +that remain to be called.) +If one of these functions does not return +(e.g., it calls +.BR _exit (2), +or kills itself with a signal), +then none of the remaining functions is called, +and further exit processing (in particular, flushing of +.BR stdio (3) +streams) is abandoned. +If a function has been registered multiple times using +.BR atexit (3) +or +.BR on_exit (3), +then it is called as many times as it was registered. +.PP +All open +.BR stdio (3) +streams are flushed and closed. +Files created by +.BR tmpfile (3) +are removed. +.PP +The C standard specifies two constants, +\fBEXIT_SUCCESS\fP and \fBEXIT_FAILURE\fP, +that may be passed to +.BR exit () +to indicate successful or unsuccessful +termination, respectively. +.SH RETURN VALUE +The +.BR exit () +function does not return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR exit () +T} Thread safety MT-Unsafe race:exit +.TE +.PP +The +.BR exit () +function uses a global variable that is not protected, +so it is not thread-safe. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +.PP +The behavior is undefined if one of the functions registered using +.BR atexit (3) +and +.BR on_exit (3) +calls either +.BR exit () +or +.BR longjmp (3). +Note that a call to +.BR execve (2) +removes registrations created using +.BR atexit (3) +and +.BR on_exit (3). +.PP +The use of +.B EXIT_SUCCESS +and +.B EXIT_FAILURE +is slightly more portable +(to non-UNIX environments) than the use of 0 and some nonzero value +like 1 or \-1. +In particular, VMS uses a different convention. +.PP +BSD has attempted to standardize exit codes; see the file +.IR . +.PP +After +.BR exit (), +the exit status must be transmitted to the +parent process. +There are three cases: +.IP \(bu 3 +If the parent has set +.BR SA_NOCLDWAIT , +or has set the +.B SIGCHLD +handler to +.BR SIG_IGN , +the status is discarded and the child dies immediately. +.IP \(bu +If the parent was waiting on the child, +it is notified of the exit status and the child dies immediately. +.IP \(bu +Otherwise, +the child becomes a "zombie" process: +most of the process resources are recycled, +but a slot containing minimal information about the child process +(termination status, resource usage statistics) is retained in process table. +This allows the parent to subsequently use +.BR waitpid (2) +(or similar) to learn the termination status of the child; +at that point the zombie process slot is released. +.PP +If the implementation supports the +.B SIGCHLD +signal, this signal +is sent to the parent. +If the parent has set +.BR SA_NOCLDWAIT , +it is undefined whether a +.B SIGCHLD +signal is sent. +.\" +.SS Signals sent to other processes +If the exiting process is a session leader and its controlling terminal +is the controlling terminal of the session, then each process in +the foreground process group of this controlling terminal +is sent a +.B SIGHUP +signal, and the terminal is disassociated +from this session, allowing it to be acquired by a new controlling +process. +.PP +If the exit of the process causes a process group to become orphaned, +and if any member of the newly orphaned process group is stopped, +then a +.B SIGHUP +signal followed by a +.B SIGCONT +signal will be +sent to each process in this process group. +See +.BR setpgid (2) +for an explanation of orphaned process groups. +.PP +Except in the above cases, +where the signalled processes may be children of the terminating process, +termination of a process does +.I not +in general cause a signal to be sent to children of that process. +However, a process can use the +.BR prctl (2) +.B PR_SET_PDEATHSIG +operation to arrange that it receives a signal if its parent terminates. +.SH SEE ALSO +.BR _exit (2), +.BR get_robust_list (2), +.BR setpgid (2), +.BR wait (2), +.BR atexit (3), +.BR on_exit (3), +.BR tmpfile (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/exp.3 b/man3/exp.3 new file mode 100644 index 0000000..47c4399 --- /dev/null +++ b/man3/exp.3 @@ -0,0 +1,158 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH EXP 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +exp, expf, expl \- base-e exponential function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double exp(double " x ); +.BI "float expf(float " x ); +.BI "long double expl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR expf (), +.BR expl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return the value of e (the base of natural +logarithms) raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the exponential value of +.IR x . +.PP +If +.I x +is a NaN, +a NaN is returned. +.PP +If +.I x +is positive infinity, +positive infinity is returned. +.PP +If +.I x +is negative infinity, ++0 is returned. +.PP +If the result underflows, +a range error occurs, +and zero is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR exp (), +.BR expf (), +.BR expl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR cexp (3), +.BR exp10 (3), +.BR exp2 (3), +.BR expm1 (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/exp10.3 b/man3/exp10.3 new file mode 100644 index 0000000..37d7f99 --- /dev/null +++ b/man3/exp10.3 @@ -0,0 +1,107 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH EXP10 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +exp10, exp10f, exp10l \- base-10 exponential function +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "double exp10(double " x ); +.BI "float exp10f(float " x ); +.BI "long double exp10l(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions return the value of 10 +raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-10 exponential value of +.IR x . +.PP +For various special cases, including the handling of infinity and NaN, +as well as overflows and underflows, see +.BR exp (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +For a discussion of the errors that can occur for these functions, see +.BR exp (3). +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR exp10 (), +.BR exp10f (), +.BR exp10l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are GNU extensions. +.SH BUGS +Prior to version 2.19, the glibc implementation of these functions did not set +.I errno +to +.B ERANGE +when an underflow error occurred. +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6787 +.SH SEE ALSO +.BR cbrt (3), +.BR exp (3), +.BR exp2 (3), +.BR log10 (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/exp10f.3 b/man3/exp10f.3 new file mode 100644 index 0000000..705b75e --- /dev/null +++ b/man3/exp10f.3 @@ -0,0 +1 @@ +.so man3/exp10.3 diff --git a/man3/exp10l.3 b/man3/exp10l.3 new file mode 100644 index 0000000..705b75e --- /dev/null +++ b/man3/exp10l.3 @@ -0,0 +1 @@ +.so man3/exp10.3 diff --git a/man3/exp2.3 b/man3/exp2.3 new file mode 100644 index 0000000..e723bc4 --- /dev/null +++ b/man3/exp2.3 @@ -0,0 +1,118 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH EXP2 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +exp2, exp2f, exp2l \- base-2 exponential function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double exp2(double " x ); +.BI "float exp2f(float " x ); +.BI "long double exp2l(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR exp2 (), +.BR exp2f (), +.BR exp2l (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad b +.SH DESCRIPTION +These functions return the value of 2 raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-2 exponential value of +.IR x . +.PP +For various special cases, including the handling of infinity and NaN, +as well as overflows and underflows, see +.BR exp (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +For a discussion of the errors that can occur for these functions, see +.BR exp (3). +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR exp2 (), +.BR exp2f (), +.BR exp2l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cbrt (3), +.BR cexp2 (3), +.BR exp (3), +.BR exp10 (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/exp2f.3 b/man3/exp2f.3 new file mode 100644 index 0000000..b69beea --- /dev/null +++ b/man3/exp2f.3 @@ -0,0 +1 @@ +.so man3/exp2.3 diff --git a/man3/exp2l.3 b/man3/exp2l.3 new file mode 100644 index 0000000..b69beea --- /dev/null +++ b/man3/exp2l.3 @@ -0,0 +1 @@ +.so man3/exp2.3 diff --git a/man3/expf.3 b/man3/expf.3 new file mode 100644 index 0000000..4b1efda --- /dev/null +++ b/man3/expf.3 @@ -0,0 +1 @@ +.so man3/exp.3 diff --git a/man3/expl.3 b/man3/expl.3 new file mode 100644 index 0000000..4b1efda --- /dev/null +++ b/man3/expl.3 @@ -0,0 +1 @@ +.so man3/exp.3 diff --git a/man3/explicit_bzero.3 b/man3/explicit_bzero.3 new file mode 100644 index 0000000..8a43e76 --- /dev/null +++ b/man3/explicit_bzero.3 @@ -0,0 +1 @@ +.so man3/bzero.3 diff --git a/man3/expm1.3 b/man3/expm1.3 new file mode 100644 index 0000000..0a71bab --- /dev/null +++ b/man3/expm1.3 @@ -0,0 +1,189 @@ +.\" Copyright 1995 Jim Van Zandt +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 2002-07-27 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH EXPM1 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +expm1, expm1f, expm1l \- exponential minus 1 +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double expm1(double " x ); +.BI "float expm1f(float " x ); +.BI "long double expm1l(long double " x ); +.PP +.fi +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR expm1 (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR expm1f (), +.BR expm1l (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return a value equivalent to +.PP +.nf + exp(x) \- 1 +.fi +.PP +The result is computed in a way that is accurate even if the value of +.I x +is near +zero\(ema case where +.I "exp(x) \- 1" +would be inaccurate due to +subtraction of two numbers that are nearly equal. +.SH RETURN VALUE +On success, these functions return +.IR "exp(x)\ \-\ 1" . +.PP +If +.I x +is a NaN, +a NaN is returned. +.PP +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.PP +If +.I x +is positive infinity, positive infinity is returned. +.PP +If +.I x +is negative infinity, \-1 is returned. +.PP +If the result overflows, a range error occurs, +and the functions return +.RB - HUGE_VAL , +.RB - HUGE_VALF , +or +.RB - HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE +(but see BUGS). +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.\" +.\" POSIX.1 specifies an optional range error (underflow) if +.\" x is subnormal. Glibc does not implement this. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR expm1 (), +.BR expm1f (), +.BR expm1l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.\" BSD. +.SH BUGS +For some large negative +.I x +values (where the function result approaches \-1), +.BR expm1 () +raises a bogus underflow floating-point exception. +.\" FIXME . +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6778 +.PP +For some large positive +.I x +values, +.BR expm1 () +raises a bogus invalid floating-point exception in addition to the expected +overflow exception, and returns a NaN instead of positive infinity. +.\" FIXME . +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6814 +.\" e.g., expm1(1e5) through expm1(1.00199970127e5), +.\" but not expm1(1.00199970128e5) and beyond. +.PP +Before version 2.11, +.\" It looks like the fix was in 2.11, or possibly 2.12. +.\" I have no test system for 2.11, but 2.12 passes. +.\" From the source (sysdeps/i386/fpu/s_expm1.S) it looks +.\" like the changes were in 2.11. +the glibc implementation did not set +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6788 +.I errno +to +.B ERANGE +when a range error occurred. +.SH SEE ALSO +.BR exp (3), +.BR log (3), +.BR log1p (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/expm1f.3 b/man3/expm1f.3 new file mode 100644 index 0000000..2c9e4ea --- /dev/null +++ b/man3/expm1f.3 @@ -0,0 +1 @@ +.so man3/expm1.3 diff --git a/man3/expm1l.3 b/man3/expm1l.3 new file mode 100644 index 0000000..2c9e4ea --- /dev/null +++ b/man3/expm1l.3 @@ -0,0 +1 @@ +.so man3/expm1.3 diff --git a/man3/fabs.3 b/man3/fabs.3 new file mode 100644 index 0000000..dc31ed3 --- /dev/null +++ b/man3/fabs.3 @@ -0,0 +1,117 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:42:04 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added fabsl, fabsf, aeb, 2001-06-07 +.\" +.TH FABS 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fabs, fabsf, fabsl \- absolute value of floating-point number +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double fabs(double " x ); +.BI "float fabsf(float " x ); +.BI "long double fabsl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR fabsf (), +.BR fabsl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return the absolute value of the floating-point +number +.IR x . +.SH RETURN VALUE +These functions return the absolute value of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is \-0, +0 is returned. +.PP +If +.I x +is negative infinity or positive infinity, positive infinity is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR fabs (), +.BR fabsf (), +.BR fabsl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR abs (3), +.BR cabs (3), +.BR ceil (3), +.BR floor (3), +.BR labs (3), +.BR rint (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fabsf.3 b/man3/fabsf.3 new file mode 100644 index 0000000..0426cf0 --- /dev/null +++ b/man3/fabsf.3 @@ -0,0 +1 @@ +.so man3/fabs.3 diff --git a/man3/fabsl.3 b/man3/fabsl.3 new file mode 100644 index 0000000..0426cf0 --- /dev/null +++ b/man3/fabsl.3 @@ -0,0 +1 @@ +.so man3/fabs.3 diff --git a/man3/fclose.3 b/man3/fclose.3 new file mode 100644 index 0000000..f3e5729 --- /dev/null +++ b/man3/fclose.3 @@ -0,0 +1,129 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)fclose.3 6.7 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:19:14 1993, faith@cs.unc.edu +.\" +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" +.TH FCLOSE 3 2016-12-12 "GNU" "Linux Programmer's Manual" +.SH NAME +fclose \- close a stream +.SH SYNOPSIS +.B #include +.PP +.BI "int fclose(FILE *" stream ); +.SH DESCRIPTION +The +.BR fclose () +function flushes the stream pointed to by +.I stream +(writing any buffered output data using +.BR fflush (3)) +and closes the underlying file descriptor. +.SH RETURN VALUE +Upon successful completion, 0 is returned. +Otherwise, +.B EOF +is returned and +.I errno +is set to indicate the error. +In either case, any further access +(including another call to +.BR fclose ()) +to the stream results in undefined behavior. +.SH ERRORS +.TP +.B EBADF +The file descriptor underlying +.I stream +is not valid. +.\" This error cannot occur unless you are mixing ANSI C stdio operations and +.\" low-level file operations on the same stream. If you do get this error, +.\" you must have closed the stream's low-level file descriptor using +.\" something like close(fileno(stream)). +.PP +The +.BR fclose () +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR close (2), +.BR write (2), +or +.BR fflush (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fclose () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.SH NOTES +Note that +.BR fclose () +flushes only the user-space buffers provided by the +C library. +To ensure that the data is physically stored +on disk the kernel buffers must be flushed too, for example, with +.BR sync (2) +or +.BR fsync (2). +.SH SEE ALSO +.BR close (2), +.BR fcloseall (3), +.BR fflush (3), +.BR fileno (3), +.BR fopen (3), +.BR setbuf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fcloseall.3 b/man3/fcloseall.3 new file mode 100644 index 0000000..ae24d54 --- /dev/null +++ b/man3/fcloseall.3 @@ -0,0 +1,87 @@ +.\" Copyright (c) 2006 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FCLOSEALL 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fcloseall \- close all open streams +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.B int fcloseall(void); +.fi +.SH DESCRIPTION +The +.BR fcloseall () +function closes all of the calling process's open streams. +Buffered output for each stream is written before it is closed +(as for +.BR fflush (3)); +buffered input is discarded. +.PP +The standard streams, +.IR stdin , +.IR stdout , +and +.I stderr +are also closed. +.SH RETURN VALUE +This function returns 0 if all files were successfully closed; +on error, +.B EOF +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fcloseall () +T} Thread safety MT-Unsafe race:streams +.TE +.PP +The +.BR fcloseall () +function does not lock the streams, so it is not thread-safe. +.SH CONFORMING TO +This function is a GNU extension. +.SH SEE ALSO +.BR close (2), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR setbuf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fcvt.3 b/man3/fcvt.3 new file mode 100644 index 0000000..39d3770 --- /dev/null +++ b/man3/fcvt.3 @@ -0,0 +1 @@ +.so man3/ecvt.3 diff --git a/man3/fcvt_r.3 b/man3/fcvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man3/fcvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man3/fdim.3 b/man3/fdim.3 new file mode 100644 index 0000000..bb1aa3a --- /dev/null +++ b/man3/fdim.3 @@ -0,0 +1,103 @@ +.\" Copyright 2003 Walter Harms, Andries Brouwer +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH FDIM 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fdim, fdimf, fdiml \- positive difference +.SH SYNOPSIS +.B #include +.PP +.BI "double fdim(double " x ", double " y ); +.br +.BI "float fdimf(float " x ", float " y ); +.br +.BI "long double fdiml(long double " x ", long double " y ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR fdimf (), +.BR fdiml (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions return the positive difference, max(\fIx\fP-\fIy\fP,0), +between their arguments. +.SH RETURN VALUE +On success, these functions return the positive difference. +.PP +If +.I x +or +.I y +is a NaN, a NaN is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error: result overflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6796 +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR fdim (), +.BR fdimf (), +.BR fdiml () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR fmax (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fdimf.3 b/man3/fdimf.3 new file mode 100644 index 0000000..a4058e4 --- /dev/null +++ b/man3/fdimf.3 @@ -0,0 +1 @@ +.so man3/fdim.3 diff --git a/man3/fdiml.3 b/man3/fdiml.3 new file mode 100644 index 0000000..a4058e4 --- /dev/null +++ b/man3/fdiml.3 @@ -0,0 +1 @@ +.so man3/fdim.3 diff --git a/man3/fdopen.3 b/man3/fdopen.3 new file mode 100644 index 0000000..9a40124 --- /dev/null +++ b/man3/fdopen.3 @@ -0,0 +1 @@ +.so man3/fopen.3 diff --git a/man3/fdopendir.3 b/man3/fdopendir.3 new file mode 100644 index 0000000..55b720e --- /dev/null +++ b/man3/fdopendir.3 @@ -0,0 +1 @@ +.so man3/opendir.3 diff --git a/man3/feclearexcept.3 b/man3/feclearexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/feclearexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fedisableexcept.3 b/man3/fedisableexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fedisableexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/feenableexcept.3 b/man3/feenableexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/feenableexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fegetenv.3 b/man3/fegetenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fegetenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fegetexcept.3 b/man3/fegetexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fegetexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fegetexceptflag.3 b/man3/fegetexceptflag.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fegetexceptflag.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fegetround.3 b/man3/fegetround.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fegetround.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/feholdexcept.3 b/man3/feholdexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/feholdexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fenv.3 b/man3/fenv.3 new file mode 100644 index 0000000..03df987 --- /dev/null +++ b/man3/fenv.3 @@ -0,0 +1,352 @@ +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2000-08-14 added GNU additions from Andreas Jaeger +.\" 2000-12-05 some changes inspired by acahalan's remarks +.\" +.TH FENV 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, +fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, +fesetenv, feupdateenv, feenableexcept, fedisableexcept, +fegetexcept \- floating-point rounding and exception handling +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int feclearexcept(int " excepts ); +.BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts ); +.BI "int feraiseexcept(int " excepts ); +.BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts ); +.BI "int fetestexcept(int " excepts ); +.PP +.B "int fegetround(void);" +.BI "int fesetround(int " rounding_mode ); +.PP +.BI "int fegetenv(fenv_t *" envp ); +.BI "int feholdexcept(fenv_t *" envp ); +.BI "int fesetenv(const fenv_t *" envp ); +.BI "int feupdateenv(const fenv_t *" envp ); +.fi +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These eleven functions were defined in C99, and describe the handling +of floating-point rounding and exceptions (overflow, zero-divide, etc.). +.SS Exceptions +The +.I divide-by-zero +exception occurs when an operation on finite numbers +produces infinity as exact answer. +.PP +The +.I overflow +exception occurs when a result has to be represented as a +floating-point number, but has (much) larger absolute value than the +largest (finite) floating-point number that is representable. +.PP +The +.I underflow +exception occurs when a result has to be represented as a +floating-point number, but has smaller absolute value than the smallest +positive normalized floating-point number (and would lose much accuracy +when represented as a denormalized number). +.PP +The +.I inexact +exception occurs when the rounded result of an operation +is not equal to the infinite precision result. +It may occur whenever +.I overflow +or +.I underflow +occurs. +.PP +The +.I invalid +exception occurs when there is no well-defined result +for an operation, as for 0/0 or infinity \- infinity or sqrt(\-1). +.SS Exception handling +Exceptions are represented in two ways: as a single bit +(exception present/absent), and these bits correspond in some +implementation-defined way with bit positions in an integer, +and also as an opaque structure that may contain more information +about the exception (perhaps the code address where it occurred). +.PP +Each of the macros +.BR FE_DIVBYZERO , +.BR FE_INEXACT , +.BR FE_INVALID , +.BR FE_OVERFLOW , +.B FE_UNDERFLOW +is defined when the implementation supports handling +of the corresponding exception, and if so then +defines the corresponding bit(s), so that one can call +exception handling functions, for example, using the integer argument +.BR FE_OVERFLOW | FE_UNDERFLOW . +Other exceptions may be supported. +The macro +.B FE_ALL_EXCEPT +is the bitwise OR of all bits corresponding to supported exceptions. +.PP +The +.BR feclearexcept () +function clears the supported exceptions represented by the bits +in its argument. +.PP +The +.BR fegetexceptflag () +function stores a representation of the state of the exception flags +represented by the argument +.I excepts +in the opaque object +.IR *flagp . +.PP +The +.BR feraiseexcept () +function raises the supported exceptions represented by the bits in +.IR excepts . +.PP +The +.BR fesetexceptflag () +function sets the complete status for the exceptions represented by +.I excepts +to the value +.IR *flagp . +This value must have been obtained by an earlier call of +.BR fegetexceptflag () +with a last argument that contained all bits in +.IR excepts . +.PP +The +.BR fetestexcept () +function returns a word in which the bits are set that were +set in the argument +.I excepts +and for which the corresponding exception is currently set. +.SS Rounding mode +The rounding mode determines how the result of floating-point operations +is treated when the result cannot be exactly represented in the significand. +Various rounding modes may be provided: +round to nearest (the default), +round up (toward positive infinity), +round down (toward negative infinity), and +round toward zero. +.PP +Each of the macros +.BR FE_TONEAREST , +.BR FE_UPWARD , +.BR FE_DOWNWARD , +and +.BR FE_TOWARDZERO +is defined when the implementation supports getting and setting +the corresponding rounding direction. +.PP +The +.BR fegetround () +function returns the macro corresponding to the current +rounding mode. +.PP +The +.BR fesetround () +function sets the rounding mode as specified by its argument +and returns zero when it was successful. +.PP +C99 and POSIX.1-2008 specify an identifier, +.BR FLT_ROUNDS , +defined in +.IR , +which indicates the implementation-defined rounding +behavior for floating-point addition. +This identifier has one of the following values: +.IP \-1 +The rounding mode is not determinable. +.IP 0 +Rounding is toward 0. +.IP 1 +Rounding is toward nearest number. +.IP 2 +Rounding is toward positive infinity. +.IP 3 +Rounding is toward negative infinity. +.PP +Other values represent machine-dependent, nonstandard rounding modes. +.PP +The value of +.BR FLT_ROUNDS +should reflect the current rounding mode as set by +.BR fesetround () +(but see BUGS). +.SS Floating-point environment +The entire floating-point environment, including +control modes and status flags, can be handled +as one opaque object, of type +.IR fenv_t . +The default environment is denoted by +.B FE_DFL_ENV +(of type +.IR "const fenv_t\ *" ). +This is the environment setup at program start and it is defined by +ISO C to have round to nearest, all exceptions cleared and a nonstop +(continue on exceptions) mode. +.PP +The +.BR fegetenv () +function saves the current floating-point environment in the object +.IR *envp . +.PP +The +.BR feholdexcept () +function does the same, then clears all exception flags, +and sets a nonstop (continue on exceptions) mode, +if available. +It returns zero when successful. +.PP +The +.BR fesetenv () +function restores the floating-point environment from +the object +.IR *envp . +This object must be known to be valid, for example, the result of a call to +.BR fegetenv () +or +.BR feholdexcept () +or equal to +.BR FE_DFL_ENV . +This call does not raise exceptions. +.PP +The +.BR feupdateenv () +function installs the floating-point environment represented by +the object +.IR *envp , +except that currently raised exceptions are not cleared. +After calling this function, the raised exceptions will be a bitwise OR +of those previously set with those in +.IR *envp . +As before, the object +.I *envp +must be known to be valid. +.SH RETURN VALUE +These functions return zero on success and nonzero if an error occurred. +.\" Earlier seven of these functions were listed as returning void. +.\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E)) +.\" of the C99 Standard. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.nh +.ad l +.TS +allbox; +lb lb lb +lw35 l l. +Interface Attribute Value +T{ +.BR feclearexcept (), +.BR fegetexceptflag (), +.BR feraiseexcept (), +.BR fesetexceptflag (), +.BR fetestexcept (), +.BR fegetround (), +.BR fesetround (), +.BR fegetenv (), +.BR feholdexcept (), +.BR fesetenv (), +.BR feupdateenv (), +.BR feenableexcept (), +.BR fedisableexcept (), +.BR fegetexcept () +T} Thread safety T{ +MT-Safe +T} +.TE +.ad +.hy +.SH CONFORMING TO +IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001. +.SH NOTES +.SS Glibc notes +If possible, the GNU C Library defines a macro +.B FE_NOMASK_ENV +which represents an environment where every exception raised causes a +trap to occur. +You can test for this macro using +.BR #ifdef . +It is defined only if +.B _GNU_SOURCE +is defined. +The C99 standard does not define a way to set individual bits in the +floating-point mask, for example, to trap on specific flags. +Since version 2.2, glibc supports the functions +.BR feenableexcept () +and +.BR fedisableexcept () +to set individual floating-point traps, and +.BR fegetexcept () +to query the state. +.PP +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B "#include " +.PP +.BI "int feenableexcept(int " excepts ); +.BI "int fedisableexcept(int " excepts ); +.B "int fegetexcept(void);" +.fi +.PP +The +.BR feenableexcept () +and +.BR fedisableexcept () +functions enable (disable) traps for each of the exceptions represented by +.I excepts +and return the previous set of enabled exceptions when successful, +and \-1 otherwise. +The +.BR fegetexcept () +function returns the set of all currently enabled exceptions. +.SH BUGS +C99 specifies that the value of +.B FLT_ROUNDS +should reflect changes to the current rounding mode, as set by +.BR fesetround (). +Currently, +.\" Aug 08, glibc 2.8 +this does not occur: +.B FLT_ROUNDS +always has the value 1. +.\" See http://gcc.gnu.org/ml/gcc/2002-02/msg01535.html +.SH SEE ALSO +.BR math_error (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/feof.3 b/man3/feof.3 new file mode 100644 index 0000000..3a95cca --- /dev/null +++ b/man3/feof.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man3/feof_unlocked.3 b/man3/feof_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/feof_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/feraiseexcept.3 b/man3/feraiseexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/feraiseexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/ferror.3 b/man3/ferror.3 new file mode 100644 index 0000000..ec91a5b --- /dev/null +++ b/man3/ferror.3 @@ -0,0 +1,146 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)ferror.3 6.8 (Berkeley) 6/29/91 +.\" +.\" +.\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu +.\" Added remark on EBADF for fileno, aeb, 2001-03-22 +.\" +.TH FERROR 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +clearerr, feof, ferror, fileno \- check and reset stream status +.SH SYNOPSIS +.B #include +.PP +.BI "void clearerr(FILE *" stream ); +.PP +.BI "int feof(FILE *" stream ); +.PP +.BI "int ferror(FILE *" stream ); +.PP +.BI "int fileno(FILE *" stream ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fileno (): +_POSIX_C_SOURCE +.SH DESCRIPTION +The function +.BR clearerr () +clears the end-of-file and error indicators for the stream pointed to by +.IR stream . +.PP +The function +.BR feof () +tests the end-of-file indicator for the stream pointed to by +.IR stream , +returning nonzero if it is set. +The end-of-file indicator can be cleared only by the function +.BR clearerr (). +.PP +The function +.BR ferror () +tests the error indicator for the stream pointed to by +.IR stream , +returning nonzero if it is set. +The error indicator can be reset only by the +.BR clearerr () +function. +.PP +The function +.BR fileno () +examines the argument +.I stream +and returns its integer file descriptor. +.PP +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH ERRORS +These functions should not fail and do not set the external variable +.IR errno . +(However, in case +.BR fileno () +detects that its argument is not a valid stream, it must +return \-1 and set +.I errno +to +.BR EBADF .) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR clearerr (), +.BR feof (), +.br +.BR ferror (), +.BR fileno () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The functions +.BR clearerr (), +.BR feof (), +and +.BR ferror () +conform to C89, C99, POSIX.1-2001, and POSIX.1-2008. +.PP +The function +.BR fileno () +conforms to POSIX.1-2001 and POSIX.1-2008. +.SH SEE ALSO +.BR open (2), +.BR fdopen (3), +.BR stdio (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ferror_unlocked.3 b/man3/ferror_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/ferror_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fesetenv.3 b/man3/fesetenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fesetenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fesetexceptflag.3 b/man3/fesetexceptflag.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fesetexceptflag.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fesetround.3 b/man3/fesetround.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fesetround.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fetestexcept.3 b/man3/fetestexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/fetestexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/feupdateenv.3 b/man3/feupdateenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man3/feupdateenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man3/fexecve.3 b/man3/fexecve.3 new file mode 100644 index 0000000..ae6c4e4 --- /dev/null +++ b/man3/fexecve.3 @@ -0,0 +1,196 @@ +.\" Copyright (c) 2006, 2014, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FEXECVE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +fexecve \- execute program specified via file descriptor +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fexecve (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +.BR fexecve () +performs the same task as +.BR execve (2), +with the difference that the file to be executed +is specified via a file descriptor, +.IR fd , +rather than via a pathname. +The file descriptor +.I fd +must be opened read-only +.RB ( O_RDONLY ) +or with the +.B O_PATH +flag +and the caller must have permission to execute the file that it refers to. +.SH RETURN VALUE +A successful call to +.BR fexecve () +never returns. +On error, the function does return, with a result value of \-1, and +.I errno +is set appropriately. +.SH ERRORS +Errors are as for +.BR execve (2), +with the following additions: +.TP +.B EINVAL +.I fd +is not a valid file descriptor, or +.I argv +is NULL, or +.I envp +is NULL. +.TP +.B ENOSYS +The +.I /proc +filesystem could not be accessed. +.SH VERSIONS +.BR fexecve () +is implemented since glibc 2.3.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fexecve () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2008. +This function is not specified in POSIX.1-2001, +and is not widely available on other systems. +It is specified in POSIX.1-2008. +.SH NOTES +On Linux with glibc versions 2.26 and earlier, +.BR fexecve () +is implemented using the +.BR proc (5) +filesystem, so +.I /proc +needs to be mounted and available at the time of the call. +Since glibc 2.27, +.\" glibc commit 43ffc53a352a67672210c9dd4959f6c6b7407e60 +if the underlying kernel supports the +.BR execveat (2) +system call, then +.BR fexecve () +is implemented using that system call, with the benefit that +.IR /proc +does not need to be mounted. +.PP +The idea behind +.BR fexecve () +is to allow the caller to verify (checksum) the contents of +an executable before executing it. +Simply opening the file, checksumming the contents, and then doing an +.BR execve (2) +would not suffice, since, between the two steps, the filename, +or a directory prefix of the pathname, could have been exchanged +(by, for example, modifying the target of a symbolic link). +.BR fexecve () +does not mitigate the problem that the +.I contents +of a file could be changed between the checksumming and the call to +.BR fexecve (); +for that, the solution is to ensure that the permissions on the file +prevent it from being modified by malicious users. +.PP +The natural idiom when using +.BR fexecve () +is to set the close-on-exec flag on +.IR fd , +so that the file descriptor does not leak through to the program +that is executed. +This approach is natural for two reasons. +First, it prevents file descriptors being consumed unnecessarily. +(The executed program normally has no need of a file descriptor +that refers to the program itself.) +Second, if +.BR fexecve () +is used recursively, +employing the close-on-exec flag prevents the file descriptor exhaustion +that would result from the fact that each step in the recursion would +cause one more file descriptor to be passed to the new program. +(But see BUGS.) +.SH BUGS +If +.I fd +refers to a script (i.e., it is an executable text file that names +a script interpreter with a first line that begins with the characters +.IR #! ) +and the close-on-exec flag has been set for +.IR fd , +then +.BR fexecve () +fails with the error +.BR ENOENT . +This error occurs because, +by the time the script interpreter is executed, +.I fd +has already been closed because of the close-on-exec flag. +Thus, the close-on-exec flag can't be set on +.I fd +if it refers to a script, leading to the problems described in NOTES. +.SH SEE ALSO +.BR execve (2), +.BR execveat (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fflush.3 b/man3/fflush.3 new file mode 100644 index 0000000..617091c --- /dev/null +++ b/man3/fflush.3 @@ -0,0 +1,141 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)fflush.3 5.4 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" Modified 2001-10-16 by John Levon +.\" +.TH FFLUSH 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fflush \- flush a stream +.SH SYNOPSIS +.B #include +.PP +.BI "int fflush(FILE *" stream ); +.SH DESCRIPTION +For output streams, +.BR fflush () +forces a write of all user-space buffered data for the given output or update +.I stream +via the stream's underlying write function. +.PP +For input streams associated with seekable files +(e.g., disk files, but not pipes or terminals), +.BR fflush () +discards any buffered data that has been fetched from the underlying file, +but has not been consumed by the application. +.PP +The open status of the stream is unaffected. +.PP +If the +.I stream +argument is NULL, +.BR fflush () +flushes +.I all +open output streams. +.\" mtk: POSIX specifies that only output streams are flushed for this case. +.\" Also verified for glibc by experiment. +.PP +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +Upon successful completion 0 is returned. +Otherwise, +.B EOF +is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I stream +is not an open stream, or is not open for writing. +.PP +The function +.BR fflush () +may also fail and set +.I errno +for any of the errors specified for +.BR write (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fflush () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C89, C99, POSIX.1-2001, POSIX.1-2008. +.PP +POSIX.1-2001 did not specify the behavior for flushing of input streams, +but the behavior is specified in POSIX.1-2008. +.SH NOTES +Note that +.BR fflush () +flushes only the user-space buffers provided by the C library. +To ensure that the data is physically stored on disk +the kernel buffers must be flushed too, for example, with +.BR sync (2) +or +.BR fsync (2). +.SH SEE ALSO +.BR fsync (2), +.BR sync (2), +.BR write (2), +.BR fclose (3), +.BR fileno (3), +.BR fopen (3), +.BR setbuf (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fflush_unlocked.3 b/man3/fflush_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fflush_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/ffs.3 b/man3/ffs.3 new file mode 100644 index 0000000..d84b409 --- /dev/null +++ b/man3/ffs.3 @@ -0,0 +1,137 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:39:35 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" Modified 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH FFS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +ffs, ffsl, ffsll \- find first bit set in a word +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int ffs(int " i ); +.PP +.B #include +.PP +.BI "int ffsl(long int " i ); +.PP +.BI "int ffsll(long long int " i ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.PD 0 +.ad l +.BR ffs (): +.RS 4 +.TP 4 +Since glibc 2.12: + _XOPEN_SOURCE >= 700 + || ! (_POSIX_C_SOURCE\ >=\ 200809L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.TP +Before glibc 2.12: +none +.RE +.PP +.BR ffsl (), +.BR ffsll (): +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.27: +.\" glibc commit 68fe16dd327c895c08b9ee443b234c49c13b36e9 + _DEFAULT_SOURCE +.TP +Before glibc 2.27: + _GNU_SOURCE +.PD +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR ffs () +function returns the position of the first +(least significant) bit set in the word \fIi\fP. +The least significant bit is position 1 and the +most significant position is, for example, 32 or 64. +The functions +.BR ffsll () +and +.BR ffsl () +do the same but take +arguments of possibly different size. +.SH RETURN VALUE +These functions return the position of the first bit set, +or 0 if no bits are set in +.IR i . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw22 lb lb +l l l. +Interface Attribute Value +T{ +.BR ffs (), +.BR ffsl (), +.BR ffsll () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR ffs (): +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.PP +The +.BR ffsl () +and +.BR ffsll () +functions are glibc extensions. +.SH NOTES +BSD systems have a prototype in +.IR . +.SH SEE ALSO +.BR memchr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ffsl.3 b/man3/ffsl.3 new file mode 100644 index 0000000..23c4024 --- /dev/null +++ b/man3/ffsl.3 @@ -0,0 +1 @@ +.so man3/ffs.3 diff --git a/man3/ffsll.3 b/man3/ffsll.3 new file mode 100644 index 0000000..23c4024 --- /dev/null +++ b/man3/ffsll.3 @@ -0,0 +1 @@ +.so man3/ffs.3 diff --git a/man3/fgetc.3 b/man3/fgetc.3 new file mode 100644 index 0000000..7f9262a --- /dev/null +++ b/man3/fgetc.3 @@ -0,0 +1,176 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) +.TH FGETC 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetc, fgets, getc, getchar, ungetc \- input of characters and strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fgetc(FILE *" stream ); +.PP +.BI "char *fgets(char *" "s" ", int " "size" ", FILE *" "stream" ); +.PP +.BI "int getc(FILE *" stream ); +.PP +.B "int getchar(void);" +.PP +.BI "int ungetc(int " c ", FILE *" stream ); +.fi +.SH DESCRIPTION +.BR fgetc () +reads the next character from +.I stream +and returns it as an +.I unsigned char +cast to an +.IR int , +or +.B EOF +on end of file or error. +.PP +.BR getc () +is equivalent to +.BR fgetc () +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.PP +.BR getchar () +is equivalent to +.BI "getc(" stdin ) \fR. +.PP +.BR fgets () +reads in at most one less than +.I size +characters from +.I stream +and stores them into the buffer pointed to by +.IR s . +Reading stops after an +.B EOF +or a newline. +If a newline is read, it is stored into the buffer. +A terminating null byte (\(aq\e0\(aq) +is stored after the last character in the buffer. +.PP +.BR ungetc () +pushes +.I c +back to +.IR stream , +cast to +.IR "unsigned char" , +where it is available for subsequent read operations. +Pushed-back characters +will be returned in reverse order; only one pushback is guaranteed. +.PP +Calls to the functions described here can be mixed with each other and with +calls to other input functions from the +.I stdio +library for the same input stream. +.PP +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +.BR fgetc (), +.BR getc () +and +.BR getchar () +return the character read as an +.I unsigned char +cast to an +.I int +or +.B EOF +on end of file or error. +.PP +.BR fgets () +returns +.I s +on success, and NULL +on error or when end of file occurs while no characters have been read. +.PP +.BR ungetc () +returns +.I c +on success, or +.B EOF +on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR fgetc (), +.BR fgets (), +.BR getc (), +.br +.BR getchar (), +.BR ungetc () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.PP +It is not advisable to mix calls to input functions from the +.I stdio +library with low-level calls to +.BR read (2) +for the file descriptor associated with the input stream; the results +will be undefined and very probably not what you want. +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR ferror (3), +.BR fgetwc (3), +.BR fgetws (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR getline (3), +.BR gets (3), +.BR getwchar (3), +.BR puts (3), +.BR scanf (3), +.BR ungetwc (3), +.BR unlocked_stdio (3), +.BR feature_test_macros (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fgetc_unlocked.3 b/man3/fgetc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fgetc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fgetgrent.3 b/man3/fgetgrent.3 new file mode 100644 index 0000000..5f17893 --- /dev/null +++ b/man3/fgetgrent.3 @@ -0,0 +1,137 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:38:44 1993 by Rik Faith (faith@cs.unc.edu) +.TH FGETGRENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetgrent \- get group file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "struct group *fgetgrent(FILE *" stream ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fgetgrent (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +The +.BR fgetgrent () +function returns a pointer to a structure containing +the group information from the file referred to by +.IR stream . +The first time it is called +it returns the first entry; thereafter, it returns successive entries. +The file referred to by +.I stream +must have the same format as +.I /etc/group +(see +.BR group (5)). +.PP +The \fIgroup\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL-terminated array of pointers + to names of group members */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR fgetgrent () +function returns a pointer to a +.I group +structure, +or NULL if there are no more entries or an error occurs. +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate +.I group +structure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fgetgrent () +T} Thread safety MT-Unsafe race:fgetgrent +.TE +.\" FIXME The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" fgetgrent: MT-Unsafe race:fgrent +.\" +.\" We think race:fgrent in glibc may be hard for users to understand, +.\" and have sent a patch to the GNU libc community for changing it to +.\" race:fgetgrent, however, something about the copyright impeded the +.\" progress. +.SH CONFORMING TO +SVr4. +.SH SEE ALSO +.BR endgrent (3), +.BR fgetgrent_r (3), +.BR fopen (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR putgrent (3), +.BR setgrent (3), +.BR group (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fgetgrent_r.3 b/man3/fgetgrent_r.3 new file mode 100644 index 0000000..7c6dfe4 --- /dev/null +++ b/man3/fgetgrent_r.3 @@ -0,0 +1 @@ +.so man3/getgrent_r.3 diff --git a/man3/fgetpos.3 b/man3/fgetpos.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man3/fgetpos.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man3/fgetpwent.3 b/man3/fgetpwent.3 new file mode 100644 index 0000000..09ee145 --- /dev/null +++ b/man3/fgetpwent.3 @@ -0,0 +1,146 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:37:37 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 22:40:48 1996 by Martin Schulze (joey@linux.de) +.\" +.TH FGETPWENT 3 2018-02-02 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetpwent \- get password file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "struct passwd *fgetpwent(FILE *" stream ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fgetpwent (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +The +.BR fgetpwent () +function returns a pointer to a structure containing +the broken out fields of a line in the file \fIstream\fP. +The first time it is called it returns the first entry; +thereafter, it returns successive entries. +The file referred to by +.I stream +must have the same format as +.I /etc/passwd +(see +.BR passwd (5)). +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR fgetpwent () +function returns a pointer to a +.I passwd +structure, or NULL if +there are no more entries or an error occurs. +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate +.I passwd +structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fgetpwent () +T} Thread safety MT-Unsafe race:fgetpwent +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" fgetpwent: MT-Unsafe race:fpwent +.\" +.\" We think race:fpwent in glibc maybe hard for users to understand, +.\" and have sent a patch to the GNU libc community for changing it to +.\" race:fgetpwent, however, something about the copyright impeded the +.\" progress. +.SH CONFORMING TO +SVr4. +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent_r (3), +.BR fopen (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fgetpwent_r.3 b/man3/fgetpwent_r.3 new file mode 100644 index 0000000..b2393bb --- /dev/null +++ b/man3/fgetpwent_r.3 @@ -0,0 +1 @@ +.so man3/getpwent_r.3 diff --git a/man3/fgets.3 b/man3/fgets.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man3/fgets.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man3/fgets_unlocked.3 b/man3/fgets_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fgets_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fgetspent.3 b/man3/fgetspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/fgetspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/fgetspent_r.3 b/man3/fgetspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/fgetspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/fgetwc.3 b/man3/fgetwc.3 new file mode 100644 index 0000000..4298f2b --- /dev/null +++ b/man3/fgetwc.3 @@ -0,0 +1,112 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon +.TH FGETWC 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetwc, getwc \- read a wide character from a FILE stream +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "wint_t fgetwc(FILE *" stream ); +.BI "wint_t getwc(FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fgetwc () +function is the wide-character equivalent +of the +.BR fgetc (3) +function. +It reads a wide character from \fIstream\fP and returns it. +If the end of stream is reached, or if \fIferror(stream)\fP becomes true, +it returns +.BR WEOF . +If a wide-character conversion error occurs, it sets +\fIerrno\fP to \fBEILSEQ\fP and returns +.BR WEOF . +.PP +The +.BR getwc () +function or macro functions identically to +.BR fgetwc (). +It may be implemented as a macro, and may evaluate its argument +more than once. +There is no reason ever to use it. +.PP +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR fgetwc () +function returns the next wide-character +from the stream, or +.BR WEOF . +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +Apart from the usual ones, there is +.TP +.B EILSEQ +The data obtained from the input stream does not +form a valid character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw17 lb lb +l l l. +Interface Attribute Value +T{ +.BR fgetwc (), +.BR getwc () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR fgetwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fgetwc () +will actually read a multibyte sequence +from the stream and then convert it to a wide character. +.SH SEE ALSO +.BR fgetws (3), +.BR fputwc (3), +.BR ungetwc (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fgetwc_unlocked.3 b/man3/fgetwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fgetwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fgetws.3 b/man3/fgetws.3 new file mode 100644 index 0000000..0bc0da0 --- /dev/null +++ b/man3/fgetws.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon +.TH FGETWS 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetws \- read a wide-character string from a FILE stream +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *fgetws(wchar_t *" ws ", int " n ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fgetws () +function is the wide-character equivalent +of the +.BR fgets (3) +function. +It reads a string of at most \fIn\-1\fP wide characters into the +wide-character array pointed to by \fIws\fP, +and adds a terminating null wide character (L\(aq\\0\(aq). +It stops reading wide characters after it has encountered and +stored a newline wide character. +It also stops when end of stream is reached. +.PP +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIws\fP. +.PP +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR fgetws () +function, if successful, returns \fIws\fP. +If end of stream +was already reached or if an error occurred, it returns NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fgetws () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR fgetws () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fgetws () +will actually read a multibyte string +from the stream and then convert it to a wide-character string. +.PP +This function is unreliable, +because it does not permit to deal properly with +null wide characters that may be present in the input. +.SH SEE ALSO +.BR fgetwc (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fgetws_unlocked.3 b/man3/fgetws_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fgetws_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fileno.3 b/man3/fileno.3 new file mode 100644 index 0000000..3a95cca --- /dev/null +++ b/man3/fileno.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man3/fileno_unlocked.3 b/man3/fileno_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fileno_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/finite.3 b/man3/finite.3 new file mode 100644 index 0000000..306b25f --- /dev/null +++ b/man3/finite.3 @@ -0,0 +1,169 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FINITE 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +finite, finitef, finitel, isinf, isinff, isinfl, isnan, isnanf, isnanl \- +BSD floating-point classification functions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int finite(double " x ); +.BI "int finitef(float " x ); +.BI "int finitel(long double " x ); +.PP +.BI "int isinf(double " x ); +.BI "int isinff(float " x ); +.BI "int isinfl(long double " x ); +.PP +.BI "int isnan(double " x ); +.BI "int isnanf(float " x ); +.BI "int isnanl(long double " x ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR finite (), +.BR finitef (), +.BR finitel (): +.RS 4 +/* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.BR isinf (): +.RS 4 +_XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR isinff (), +.BR isinfl (): +.RS 4 +/* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.BR isnan (): +.RS 4 +_XOPEN_SOURCE || _ISOC99_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.BR isnanf (), +.BR isnanl (): +.RS 4 +_XOPEN_SOURCE\ >=\ 600 + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR finite (), +.BR finitef (), +and +.BR finitel () +functions return a nonzero value if +.I x +is neither infinite +nor a "not-a-number" (NaN) value, and 0 otherwise. +.PP +The +.BR isnan (), +.BR isnanf (), +and +.BR isnanl () +functions return a nonzero value if +.I x +is a NaN value, +and 0 otherwise. +.PP +The +.BR isinf (), +.BR isinff (), +and +.BR isinfl () +functions return 1 if +.I x +is positive infinity, \-1 if +.I x +is negative infinity, and 0 otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR finite (), +.BR finitef (), +.BR finitel (), +.br +.BR isinf (), +.BR isinff (), +.BR isinfl (), +.br +.BR isnan (), +.BR isnanf (), +.BR isnanl () +T} Thread safety MT-Safe +.TE +.SH NOTES +Note that these functions are obsolete. +C99 defines macros +.BR isfinite (), +.BR isinf (), +and +.BR isnan () +(for all types) replacing them. +Further note that the C99 +.BR isinf () +has weaker guarantees on the return value. +See +.BR fpclassify (3). +.\" +.\" finite* not on HP-UX; they exist on Tru64. +.\" .SH HISTORY +.\" The +.\" .BR finite () +.\" function occurs in 4.3BSD. +.\" see IEEE.3 in the 4.3BSD manual +.SH SEE ALSO +.BR fpclassify (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/finitef.3 b/man3/finitef.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man3/finitef.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/finitel.3 b/man3/finitel.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man3/finitel.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/flockfile.3 b/man3/flockfile.3 new file mode 100644 index 0000000..bf221be --- /dev/null +++ b/man3/flockfile.3 @@ -0,0 +1,156 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FLOCKFILE 3 2017-07-13 "" "Linux Programmer's Manual" +.SH NAME +flockfile, ftrylockfile, funlockfile \- lock FILE for stdio +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void flockfile(FILE *" filehandle ); +.BI "int ftrylockfile(FILE *" filehandle ); +.BI "void funlockfile(FILE *" filehandle ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.PP +All functions shown above: +.RS 4 +/* Since glibc 2.24: */ _POSIX_C_SOURCE\ >=\ 199309L + || /* Glibc versions <= 2.23: */ _POSIX_C_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +The stdio functions are thread-safe. +This is achieved by assigning +to each +.I FILE +object a lockcount and (if the lockcount is nonzero) +an owning thread. +For each library call, these functions wait until the +.I FILE +object +is no longer locked by a different thread, then lock it, do the +requested I/O, and unlock the object again. +.PP +(Note: this locking has nothing to do with the file locking done +by functions like +.BR flock (2) +and +.BR lockf (3).) +.PP +All this is invisible to the C-programmer, but there may be two +reasons to wish for more detailed control. +On the one hand, maybe +a series of I/O actions by one thread belongs together, and should +not be interrupted by the I/O of some other thread. +On the other hand, maybe the locking overhead should be avoided +for greater efficiency. +.PP +To this end, a thread can explicitly lock the +.I FILE +object, +then do its series of I/O actions, then unlock. +This prevents +other threads from coming in between. +If the reason for doing +this was to achieve greater efficiency, one does the I/O with +the nonlocking versions of the stdio functions: with +.BR getc_unlocked (3) +and +.BR putc_unlocked (3) +instead of +.BR getc (3) +and +.BR putc (3). +.PP +The +.BR flockfile () +function waits for +.I *filehandle +to be +no longer locked by a different thread, then makes the +current thread owner of +.IR *filehandle , +and increments +the lockcount. +.PP +The +.BR funlockfile () +function decrements the lock count. +.PP +The +.BR ftrylockfile () +function is a nonblocking version +of +.BR flockfile (). +It does nothing in case some other thread +owns +.IR *filehandle , +and it obtains ownership and increments +the lockcount otherwise. +.SH RETURN VALUE +The +.BR ftrylockfile () +function returns zero for success +(the lock was obtained), and nonzero for failure. +.SH ERRORS +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw29 lb lb +l l l. +Interface Attribute Value +T{ +.BR flockfile (), +.BR ftrylockfile (), +.BR funlockfile () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH AVAILABILITY +These functions are available when +.B _POSIX_THREAD_SAFE_FUNCTIONS +is defined. +.SH SEE ALSO +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/floor.3 b/man3/floor.3 new file mode 100644 index 0000000..065b2c9 --- /dev/null +++ b/man3/floor.3 @@ -0,0 +1,128 @@ +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FLOOR 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +floor, floorf, floorl \- largest integral value not greater than argument +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double floor(double " x ); +.BI "float floorf(float " x ); +.BI "long double floorl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR floorf (), +.BR floorl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the largest integral value that is not greater than +.IR x . +.PP +For example, +.IR floor(0.5) +is 0.0, and +.IR floor(\-0.5) +is \-1.0. +.SH RETURN VALUE +These functions return the floor of +.IR x . +.PP +If +.I x +is integral, +0, \-0, NaN, or an infinity, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR floor (), +.BR floorf (), +.BR floorl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH NOTES +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 128 (respectively, 1024), +and the number of mantissa bits is 24 (respectively, 53).) +.SH SEE ALSO +.BR ceil (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3), +.BR trunc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/floorf.3 b/man3/floorf.3 new file mode 100644 index 0000000..1d8e79b --- /dev/null +++ b/man3/floorf.3 @@ -0,0 +1 @@ +.so man3/floor.3 diff --git a/man3/floorl.3 b/man3/floorl.3 new file mode 100644 index 0000000..1d8e79b --- /dev/null +++ b/man3/floorl.3 @@ -0,0 +1 @@ +.so man3/floor.3 diff --git a/man3/fma.3 b/man3/fma.3 new file mode 100644 index 0000000..5b59c87 --- /dev/null +++ b/man3/fma.3 @@ -0,0 +1,175 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Modified 2004-11-15, Added further text on FLT_ROUNDS +.\" as suggested by AEB and Fabian Kreutz +.\" +.TH FMA 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fma, fmaf, fmal \- floating-point multiply and add +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double fma(double " x ", double " y ", double " z ); +.BI "float fmaf(float " x ", float " y ", float " z ); +.BI "long double fmal(long double " x ", long double " y ", long double " z ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR fma (), +.BR fmaf (), +.BR fmal (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions compute +.IR x " * " y " + " z . +The result is rounded as one ternary operation according to the +current rounding mode (see +.BR fenv (3)). +.SH RETURN VALUE +These functions return the value of +.IR x " * " y " + " z , +rounded as one ternary operation. +.PP +If +.I x +or +.I y +is a NaN, a NaN is returned. +.PP +If +.I x +times +.I y +is an exact infinity, and +.I z +is an infinity with the opposite sign, +a domain error occurs, +and a NaN is returned. +.PP +.\" POSIX.1-2008 allows some possible differences for the following two +.\" domain error cases, but on Linux they are treated the same (AFAICS). +.\" Nevertheless, we'll mirror POSIX.1 and describe the two cases +.\" separately. +If one of +.I x +or +.I y +is an infinity, the other is 0, and +.I z +is not a NaN, +a domain error occurs, and +a NaN is returned. +.\" POSIX.1 says that a NaN or an implementation-defined value shall +.\" be returned for this case. +.PP +If one of +.I x +or +.I y +is an infinity, and the other is 0, and +.I z +is a NaN, +.\" POSIX.1 makes the domain error optional for this case. +a domain error occurs, and +a NaN is returned. +.PP +If +.I x +times +.I y +is not an infinity times zero (or vice versa), and +.I z +is a NaN, +a NaN is returned. +.PP +If the result overflows, +a range error occurs, and +an infinity with the correct sign is returned. +.PP +If the result underflows, +a range error occurs, and +a signed 0 is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP * \fIy\fP + \fIz\fP, \ +or \fIx\fP * \fIy\fP is invalid and \fIz\fP is not a NaN +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error: result overflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result underflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6801 +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR fma (), +.BR fmaf (), +.BR fmal () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR remainder (3), +.BR remquo (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fmaf.3 b/man3/fmaf.3 new file mode 100644 index 0000000..e050da0 --- /dev/null +++ b/man3/fmaf.3 @@ -0,0 +1 @@ +.so man3/fma.3 diff --git a/man3/fmal.3 b/man3/fmal.3 new file mode 100644 index 0000000..e050da0 --- /dev/null +++ b/man3/fmal.3 @@ -0,0 +1 @@ +.so man3/fma.3 diff --git a/man3/fmax.3 b/man3/fmax.3 new file mode 100644 index 0000000..38e72ca --- /dev/null +++ b/man3/fmax.3 @@ -0,0 +1,79 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH FMAX 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fmax, fmaxf, fmaxl \- determine maximum of two floating-point numbers +.SH SYNOPSIS +.B #include +.PP +.BI "double fmax(double " x ", double " y ); +.BI "float fmaxf(float " x ", float " y ); +.BI "long double fmaxl(long double " x ", long double " y ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR fmax (), +.BR fmaxf (), +.BR fmaxl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions return the larger value of +.I x +and +.IR y . +.SH RETURN VALUE +These functions return the maximum of +.I x +and +.IR y . +.PP +If one argument is a NaN, the other argument is returned. +.PP +If both arguments are NaN, a NaN is returned. +.SH ERRORS +No errors occur. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR fmax (), +.BR fmaxf (), +.BR fmaxl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR fdim (3), +.BR fmin (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fmaxf.3 b/man3/fmaxf.3 new file mode 100644 index 0000000..5f68a86 --- /dev/null +++ b/man3/fmaxf.3 @@ -0,0 +1 @@ +.so man3/fmax.3 diff --git a/man3/fmaxl.3 b/man3/fmaxl.3 new file mode 100644 index 0000000..5f68a86 --- /dev/null +++ b/man3/fmaxl.3 @@ -0,0 +1 @@ +.so man3/fmax.3 diff --git a/man3/fmemopen.3 b/man3/fmemopen.3 new file mode 100644 index 0000000..19be935 --- /dev/null +++ b/man3/fmemopen.3 @@ -0,0 +1,361 @@ +.\" Copyright 2005, 2012, 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under the GPL. +.\" %%%LICENSE_END +.\" +.TH FMEMOPEN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fmemopen \- open memory as stream +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fmemopen (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR fmemopen () +function opens a stream that permits the access specified by +.IR mode . +The stream allows I/O to be performed on the string or memory buffer +pointed to by +.IR buf . +.PP +The +.I mode +argument specifies the semantics of I/O on the stream, +and is one of the following: +.TP 8 +.I r +The stream is opened for reading. +.TP +.I w +The stream is opened for writing. +.TP +.I a +Append; open the stream for writing, +with the initial buffer position set to the first null byte. +.TP +.I r+ +Open the stream for reading and writing. +.TP +.I w+ +Open the stream for reading and writing. +The buffer contents are truncated +(i.e., \(aq\\0\(aq is placed in the first byte of the buffer). +.TP +.I a+ +Append; open the stream for reading and writing, +with the initial buffer position set to the first null byte. +.PP +The stream maintains the notion of a current position, +the location where the next I/O operation will be performed. +The current position is implicitly updated by I/O operations. +It can be explicitly updated using +.BR fseek (3), +and determined using +.BR ftell (3). +In all modes other than append, +the initial position is set to the start of the buffer. +In append mode, if no null byte is found within the buffer, +then the initial position is +.IR size+1 . +.PP +If +.I buf +is specified as NULL, then +.BR fmemopen () +allocates a buffer of +.I size +bytes. +This is useful for an application that wants to write data to +a temporary buffer and then read it back again. +The initial position is set to the start of the buffer. +The buffer is automatically freed when the stream is closed. +Note that the caller has no way to obtain a pointer to the +temporary buffer allocated by this call (but see +.BR open_memstream (3)). +.PP +If +.I buf +is not NULL, then it should point to a buffer of at least +.I len +bytes allocated by the caller. +.PP +When a stream that has been opened for writing is flushed +.RB ( fflush (3)) +or closed +.RB ( fclose (3)), +a null byte is written at the end of the buffer if there is space. +The caller should ensure that an extra byte is available in the +buffer +(and that +.I size +counts that byte) +to allow for this. +.PP +In a stream opened for reading, +null bytes (\(aq\\0\(aq) in the buffer do not cause read +operations to return an end-of-file indication. +A read from the buffer will indicate end-of-file +only when the current buffer position advances +.I size +bytes past the start of the buffer. +.PP +Write operations take place either at the current position +(for modes other than append), or at the current size of the stream +(for append modes). +.PP +Attempts to write more than +.I size +bytes to the buffer result in an error. +By default, such errors will be visible +(by the absence of data) only when the +.I stdio +buffer is flushed. +Disabling buffering with the following call +may be useful to detect errors at the time of an output operation: +.PP + setbuf(stream, NULL); +.SH RETURN VALUE +Upon successful completion, +.BR fmemopen () +returns a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH VERSIONS +.BR fmemopen () +was already available in glibc 1.0.x. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fmemopen (), +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2008. +This function is not specified in POSIX.1-2001, +and is not widely available on other systems. +.PP +POSIX.1-2008 specifies that \(aqb\(aq in +.IR mode +shall be ignored. +However, Technical Corrigendum 1 +.\" http://austingroupbugs.net/view.php?id=396 +adjusts the standard to allow implementation-specific treatment for this case, +thus permitting the glibc treatment of \(aqb\(aq. +.SH NOTES +There is no file descriptor associated with the file stream +returned by this function +(i.e., +.BR fileno (3) +will return an error if called on the returned stream). +.PP +With version 2.22, binary mode (see below) was removed, +many longstanding bugs in the implementation of +.BR fmemopen () +were fixed, and a new versioned symbol was created for this interface. +.\" +.SS Binary mode +From version 2.9 to 2.21, the glibc implementation of +.BR fmemopen () +supported a "binary" mode, +enabled by specifying the letter \(aqb\(aq as the second character in +.IR mode . +In this mode, +writes don't implicitly add a terminating null byte, and +.BR fseek (3) +.B SEEK_END +is relative to the end of the buffer (i.e., the value specified by the +.I size +argument), rather than the current string length. +.PP +An API bug afflicted the implementation of binary mode: +to specify binary mode, the \(aqb\(aq must be the +.I second +character in +.IR mode . +Thus, for example, "wb+" has the desired effect, but "w+b" does not. +This is inconsistent with the treatment of +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12836 +.IR mode +by +.BR fopen (3). +.PP +Binary mode was removed in glibc 2.22; a \(aqb\(aq specified in +.I mode +has no effect. +.SH BUGS +In versions of glibc before 2.22, if +.I size +is specified as zero, +.BR fmemopen () +fails with the error +.BR EINVAL . +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=11216 +It would be more consistent if this case successfully created +a stream that then returned end-of-file on the first attempt at reading; +since version 2.22, the glibc implementation provides that behavior. +.PP +In versions of glibc before 2.22, +specifying append mode ("a" or "a+") for +.BR fmemopen () +sets the initial buffer position to the first null byte, but +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=13152 +(if the current position is reset to a location other than +the end of the stream) +does not force subsequent writes to append at the end of the stream. +This bug is fixed in glibc 2.22. +.PP +In versions of glibc before 2.22, if the +.I mode +argument to +.BR fmemopen () +specifies append ("a" or "a+"), and the +.I size +argument does not cover a null byte in +.IR buf , +then, according to POSIX.1-2008, +the initial buffer position should be set to +the next byte after the end of the buffer. +However, in this case the glibc +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=13151 +.BR fmemopen () +sets the buffer position to \-1. +This bug is fixed in glibc 2.22. +.PP +In versions of glibc before 2.22, +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14292 +when a call to +.BR fseek (3) +with a +.I whence +value of +.B SEEK_END +was performed on a stream created by +.BR fmemopen (), +the +.I offset +was +.IR subtracted +from the end-of-stream position, instead of being added. +This bug is fixed in glibc 2.22. +.PP +The glibc 2.9 addition of "binary" mode for +.BR fmemopen () +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544 +silently changed the ABI: previously, +.BR fmemopen () +ignored \(aqb\(aq in +.IR mode . +.SH EXAMPLE +The program below uses +.BR fmemopen () +to open an input buffer, and +.BR open_memstream (3) +to open a dynamically sized output buffer. +The program scans its input string (taken from the program's +first command-line argument) reading integers, +and writes the squares of these integers to the output buffer. +An example of the output produced by this program is the following: +.PP +.in +4n +.EX +.RB "$" " ./a.out \(aq1 23 43\(aq" +size=11; ptr=1 529 1849 +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +int +main(int argc, char *argv[]) +{ + FILE *out, *in; + int v, s; + size_t size; + char *ptr; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \(aq...\(aq\\n", argv[0]); + exit(EXIT_FAILURE); + } + + in = fmemopen(argv[1], strlen(argv[1]), "r"); + if (in == NULL) + handle_error("fmemopen"); + + out = open_memstream(&ptr, &size); + if (out == NULL) + handle_error("open_memstream"); + + for (;;) { + s = fscanf(in, "%d", &v); + if (s <= 0) + break; + + s = fprintf(out, "%d ", v * v); + if (s == \-1) + handle_error("fprintf"); + } + + fclose(in); + fclose(out); + + printf("size=%zu; ptr=%s\\n", size, ptr); + + free(ptr); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fopen (3), +.BR fopencookie (3), +.BR open_memstream (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fmin.3 b/man3/fmin.3 new file mode 100644 index 0000000..5d42809 --- /dev/null +++ b/man3/fmin.3 @@ -0,0 +1,81 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH FMIN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fmin, fminf, fminl \- determine minimum of two floating-point numbers +.SH SYNOPSIS +.B #include +.PP +.BI "double fmin(double " x ", double " y ); +.br +.BI "float fminf(float " x ", float " y ); +.br +.BI "long double fminl(long double " x ", long double " y ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR fmin (), +.BR fminf (), +.BR fminl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions return the lesser value of +.I x +and +.IR y . +.SH RETURN VALUE +These functions return the minimum of +.I x +and +.IR y . +.PP +If one argument is a NaN, the other argument is returned. +.PP +If both arguments are NaN, a NaN is returned. +.SH ERRORS +No errors occur. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR fmin (), +.BR fminf (), +.BR fminl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR fdim (3), +.BR fmax (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fminf.3 b/man3/fminf.3 new file mode 100644 index 0000000..a86d77d --- /dev/null +++ b/man3/fminf.3 @@ -0,0 +1 @@ +.so man3/fmin.3 diff --git a/man3/fminl.3 b/man3/fminl.3 new file mode 100644 index 0000000..a86d77d --- /dev/null +++ b/man3/fminl.3 @@ -0,0 +1 @@ +.so man3/fmin.3 diff --git a/man3/fmod.3 b/man3/fmod.3 new file mode 100644 index 0000000..08f8bad --- /dev/null +++ b/man3/fmod.3 @@ -0,0 +1,179 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH FMOD 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fmod, fmodf, fmodl \- floating-point remainder function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double fmod(double " x ", double " y ); +.BI "float fmodf(float " x ", float " y ); +.BI "long double fmodl(long double " x ", long double " y ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR fmodf (), +.BR fmodl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions compute the floating-point remainder of dividing +.I x +by +.IR y . +The return value is +.IR x +\- +.I n +* +.IR y , +where +.I n +is the quotient of +.I x +/ +.IR y , +rounded toward zero to an integer. +.SH RETURN VALUE +On success, these +functions return the value \fIx\fP\ \-\ \fIn\fP*\fIy\fP, +for some integer +.IR n , +such that the returned value has the same sign as +.I x +and a magnitude less than the magnitude of +.IR y . +.PP +If +.I x +or +.I y +is a NaN, a NaN is returned. +.PP +If +.I x +is an infinity, +a domain error occurs, and +a NaN is returned. +.PP +If +.I y +is zero, +a domain error occurs, and +a NaN is returned. +.PP +If +.I x +is +0 (\-0), and +.I y +is not zero, +0 (\-0) is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.BR EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Domain error: \fIy\fP is zero +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.\" POSIX.1 documents an optional underflow error, but AFAICT it doesn't +.\" (can't?) occur -- mtk, Jul 2008 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR fmod (), +.BR fmodf (), +.BR fmodl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before version 2.10, the glibc implementation did not set +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6784 +.I errno +to +.B EDOM +when a domain error occurred for an infinite +.IR x . +.SH SEE ALSO +.BR remainder (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fmodf.3 b/man3/fmodf.3 new file mode 100644 index 0000000..d014cc0 --- /dev/null +++ b/man3/fmodf.3 @@ -0,0 +1 @@ +.so man3/fmod.3 diff --git a/man3/fmodl.3 b/man3/fmodl.3 new file mode 100644 index 0000000..d014cc0 --- /dev/null +++ b/man3/fmodl.3 @@ -0,0 +1 @@ +.so man3/fmod.3 diff --git a/man3/fmtmsg.3 b/man3/fmtmsg.3 new file mode 100644 index 0000000..05546a3 --- /dev/null +++ b/man3/fmtmsg.3 @@ -0,0 +1,340 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" adapted glibc info page +.\" +.\" This should run as 'Guru Meditation' (amiga joke :) +.\" The function is quite complex and deserves an example +.\" +.\" Polished, aeb, 2003-11-01 +.TH FMTMSG 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fmtmsg \- print formatted error messages +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fmtmsg(long " classification ", const char *" label , +.BI " int " severity ", const char *" text , +.BI " const char *" action ", const char *" tag ); +.fi +.SH DESCRIPTION +This function displays a message described by its arguments on the device(s) +specified in the +.I classification +argument. +For messages written to +.IR stderr , +the format depends on the +.B MSGVERB +environment variable. +.PP +The +.I label +argument identifies the source of the message. +The string must consist +of two colon separated parts where the first part has not more +than 10 and the second part not more than 14 characters. +.PP +The +.I text +argument describes the condition of the error. +.PP +The +.I action +argument describes possible steps to recover from the error. +If it is printed, it is prefixed by "TO FIX: ". +.PP +The +.I tag +argument is a reference to the online documentation where more +information can be found. +It should contain the +.I label +value and a unique identification number. +.SS Dummy arguments +Each of the arguments can have a dummy value. +The dummy classification value +.B MM_NULLMC +(0L) does not specify any output, so nothing is printed. +The dummy severity value +.B NO_SEV +(0) says that no severity is supplied. +The values +.BR MM_NULLLBL , +.BR MM_NULLTXT , +.BR MM_NULLACT , +.B MM_NULLTAG +are synonyms for +.IR "((char\ *)\ 0)" , +the empty string, and +.B MM_NULLSEV +is a synonym for +.BR NO_SEV . +.SS The classification argument +The +.I classification +argument is the sum of values describing 4 types of information. +.PP +The first value defines the output channel. +.TP 12n +.B MM_PRINT +Output to +.IR stderr . +.TP +.B MM_CONSOLE +Output to the system console. +.TP +.B "MM_PRINT | MM_CONSOLE" +Output to both. +.PP +The second value is the source of the error: +.TP 12n +.B MM_HARD +A hardware error occurred. +.TP +.B MM_FIRM +A firmware error occurred. +.TP +.B MM_SOFT +A software error occurred. +.PP +The third value encodes the detector of the problem: +.TP 12n +.B MM_APPL +It is detected by an application. +.TP +.B MM_UTIL +It is detected by a utility. +.TP +.B MM_OPSYS +It is detected by the operating system. +.PP +The fourth value shows the severity of the incident: +.TP 12n +.B MM_RECOVER +It is a recoverable error. +.TP +.B MM_NRECOV +It is a nonrecoverable error. +.SS The severity argument +The +.I severity +argument can take one of the following values: +.TP 12n +.B MM_NOSEV +No severity is printed. +.TP +.B MM_HALT +This value is printed as HALT. +.TP +.B MM_ERROR +This value is printed as ERROR. +.TP +.B MM_WARNING +This value is printed as WARNING. +.TP +.B MM_INFO +This value is printed as INFO. +.PP +The numeric values are between 0 and 4. +Using +.BR addseverity (3) +or the environment variable +.B SEV_LEVEL +you can add more levels and strings to print. +.SH RETURN VALUE +The function can return 4 values: +.TP 12n +.B MM_OK +Everything went smooth. +.TP +.B MM_NOTOK +Complete failure. +.TP +.B MM_NOMSG +Error writing to +.IR stderr . +.TP +.B MM_NOCON +Error writing to the console. +.SH ENVIRONMENT +The environment variable +.B MSGVERB +("message verbosity") can be used to suppress parts of +the output to +.IR stderr . +(It does not influence output to the console.) +When this variable is defined, is non-NULL, and is a colon-separated +list of valid keywords, then only the parts of the message corresponding +to these keywords is printed. +Valid keywords are "label", "severity", "text", "action" and "tag". +.PP +The environment variable +.B SEV_LEVEL +can be used to introduce new severity levels. +By default, only the five severity levels described +above are available. +Any other numeric value would make +.BR fmtmsg () +print nothing. +If the user puts +.B SEV_LEVEL +with a format like +.PP +.RS +SEV_LEVEL=[description[:description[:...]]] +.RE +.PP +in the environment of the process before the first call to +.BR fmtmsg (), +where each description is of the form +.PP +.RS +severity-keyword,level,printstring +.RE +.PP +then +.BR fmtmsg () +will also accept the indicated values for the level (in addition to +the standard levels 0\(en4), and use the indicated printstring when +such a level occurs. +.PP +The severity-keyword part is not used by +.BR fmtmsg () +but it has to be present. +The level part is a string representation of a number. +The numeric value must be a number greater than 4. +This value must be used in the severity argument of +.BR fmtmsg () +to select this class. +It is not possible to overwrite +any of the predefined classes. +The printstring +is the string printed when a message of this class is processed by +.BR fmtmsg (). +.SH VERSIONS +.BR fmtmsg () +is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw23 +l l l. +Interface Attribute Value +T{ +.BR fmtmsg () +T} Thread safety T{ +glibc >= 2.16: MT-Safe +.br +glibc < 2.16: MT-Unsafe +T} +.TE +.PP +Before glibc 2.16, the +.BR fmtmsg () +function uses a static variable that is not protected, +so it is not thread-safe. +.PP +Since glibc 2.16, +.\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94 +the +.BR fmtmsg () +function uses a lock to protect the static variable, so it is thread-safe. +.SH CONFORMING TO +The functions +.BR fmtmsg () +and +.BR addseverity (3), +and environment variables +.B MSGVERB +and +.B SEV_LEVEL +come from System V. +.PP +The function +.BR fmtmsg () +and the environment variable +.B MSGVERB +are described in POSIX.1-2001 and POSIX.1-2008. +.SH NOTES +System V and UnixWare man pages tell us that these functions +have been replaced by "pfmt() and addsev()" or by "pfmt(), +vpfmt(), lfmt(), and vlfmt()", and will be removed later. +.SH EXAMPLE +.EX +#include +#include +#include + +int +main(void) +{ + long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER; + int err; + + err = fmtmsg(class, "util\-linux:mount", MM_ERROR, + "unknown mount option", "See mount(8).", + "util\-linux:mount:017"); + switch (err) { + case MM_OK: + break; + case MM_NOTOK: + printf("Nothing printed\en"); + break; + case MM_NOMSG: + printf("Nothing printed to stderr\en"); + break; + case MM_NOCON: + printf("No console output\en"); + break; + default: + printf("Unknown error from fmtmsg()\en"); + } + exit(EXIT_SUCCESS); +} +.EE +.PP +The output should be: +.PP +.in +4n +.EX +util\-linux:mount: ERROR: unknown mount option +TO FIX: See mount(8). util\-linux:mount:017 +.EE +.in +.PP +and after +.PP +.in +4n +.EX +MSGVERB=text:action; export MSGVERB +.EE +.in +.PP +the output becomes: +.PP +.in +4n +.EX +unknown mount option +TO FIX: See mount(8). +.EE +.in +.PP +.SH SEE ALSO +.BR addseverity (3), +.BR perror (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fnmatch.3 b/man3/fnmatch.3 new file mode 100644 index 0000000..0b7c098 --- /dev/null +++ b/man3/fnmatch.3 @@ -0,0 +1,153 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 19:35:54 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Oct 16 00:16:29 2000 following Joseph S. Myers +.\" +.TH FNMATCH 3 2015-12-28 "GNU" "Linux Programmer's Manual" +.SH NAME +fnmatch \- match filename or pathname +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fnmatch(const char *" "pattern" ", const char *" string ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR fnmatch () +function checks whether the +.I string +argument matches the +.I pattern +argument, which is a shell wildcard pattern. +.PP +The +.I flags +argument modifies the behavior; it is the bitwise OR of zero or more +of the following flags: +.TP +.B FNM_NOESCAPE +If this flag is set, treat backslash as an ordinary character, +instead of an escape character. +.TP +.B FNM_PATHNAME +If this flag is set, match a slash in +.I string +only with a slash in +.I pattern +and not by an asterisk (*) or a question mark (?) metacharacter, +nor by a bracket expression ([]) containing a slash. +.TP +.B FNM_PERIOD +If this flag is set, a leading period in +.I string +has to be matched exactly by a period in +.IR pattern . +A period is considered to be leading if it is the first character in +.IR string , +or if both +.B FNM_PATHNAME +is set and the period immediately follows a slash. +.TP +.B FNM_FILE_NAME +This is a GNU synonym for +.BR FNM_PATHNAME . +.TP +.B FNM_LEADING_DIR +If this flag (a GNU extension) is set, the pattern is considered to be +matched if it matches an initial segment of +.I string +which is followed by a slash. +This flag is mainly for the internal +use of glibc and is implemented only in certain cases. +.TP +.B FNM_CASEFOLD +If this flag (a GNU extension) is set, the pattern is matched +case-insensitively. +.TP +.B FNM_EXTMATCH +If this flag (a GNU extension) is set, extended patterns are +supported, as introduced by \&'ksh' and now supported by other shells. +The extended format is as follows, with \fIpattern\-list\fR +being a \&'|' separated list of patterns. +.TP +\&'?(\fIpattern\-list\fR)' +The pattern matches if zero or one occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'*(\fIpattern\-list\fR)' +The pattern matches if zero or more occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'+(\fIpattern\-list\fR)' +The pattern matches if one or more occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'@(\fIpattern\-list\fR)' +The pattern matches if exactly one occurrence of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'!(\fIpattern\-list\fR)' +The pattern matches if the input \fIstring\fR cannot be matched with +any of the patterns in the \fIpattern\-list\fR. +.SH RETURN VALUE +Zero if +.I string +matches +.IR pattern , +.B FNM_NOMATCH +if there is no match or another nonzero value if there is an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fnmatch () +T} Thread safety MT-Safe env locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, POSIX.2. +The +.BR FNM_FILE_NAME ", " FNM_LEADING_DIR ", and " FNM_CASEFOLD +flags are GNU extensions. +.SH SEE ALSO +.BR sh (1), +.BR glob (3), +.BR scandir (3), +.BR wordexp (3), +.BR glob (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fopen.3 b/man3/fopen.3 new file mode 100644 index 0000000..85154fe --- /dev/null +++ b/man3/fopen.3 @@ -0,0 +1,419 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)fopen.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" Modified, aeb, 960421, 970806 +.\" Modified, joey, aeb, 2002-01-03 +.\" +.TH FOPEN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fopen, fdopen, freopen \- stream open functions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "FILE *fopen(const char *" pathname ", const char *" mode ); +.PP +.BI "FILE *fdopen(int " fd ", const char *" mode ); +.PP +.BI "FILE *freopen(const char *" pathname ", const char *" mode ", FILE *" stream ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fdopen (): +_POSIX_C_SOURCE +.SH DESCRIPTION +The +.BR fopen () +function opens the file whose name is the string pointed to by +.I pathname +and associates a stream with it. +.PP +The argument +.I mode +points to a string beginning with one of the following sequences +(possibly followed by additional characters, as described below): +.TP +.B r +Open text file for reading. +The stream is positioned at the beginning of the file. +.TP +.B r+ +Open for reading and writing. +The stream is positioned at the beginning of the file. +.TP +.B w +Truncate file to zero length or create text file for writing. +The stream is positioned at the beginning of the file. +.TP +.B w+ +Open for reading and writing. +The file is created if it does not exist, otherwise it is truncated. +The stream is positioned at the beginning of +the file. +.TP +.B a +Open for appending (writing at end of file). +The file is created if it does not exist. +The stream is positioned at the end of the file. +.TP +.B a+ +Open for reading and appending (writing at end of file). +The file is created if it does not exist. +The initial file position for reading is at the beginning of the file, +but output is always appended to the end of the file. +.PP +The +.I mode +string can also include the letter \(aqb\(aq either as a last character or as +a character between the characters in any of the two-character strings +described above. +This is strictly for compatibility with C89 +and has no effect; the \(aqb\(aq is ignored on all POSIX +conforming systems, including Linux. +(Other systems may treat text files and binary files differently, +and adding the \(aqb\(aq may be a good idea if you do I/O to a binary +file and expect that your program may be ported to non-UNIX +environments.) +.PP +See NOTES below for details of glibc extensions for +.IR mode . +.PP +Any created file will have the mode +.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH +(0666), as modified by the process's umask value (see +.BR umask (2)). +.PP +Reads and writes may be intermixed on read/write streams in any order. +Note that ANSI C requires that a file positioning function intervene +between output and input, unless an input operation encounters end-of-file. +(If this condition is not met, then a read is allowed to return the +result of writes other than the most recent.) +Therefore it is good practice (and indeed sometimes necessary +under Linux) to put an +.BR fseek (3) +or +.BR fgetpos (3) +operation between write and read operations on such a stream. +This operation may be an apparent no-op +(as in \fIfseek(..., 0L, SEEK_CUR)\fP +called for its synchronizing side effect). +.PP +Opening a file in append mode (\fBa\fP as the first character of +.IR mode ) +causes all subsequent write operations to this stream to occur +at end-of-file, as if preceded the call: +.PP +.in +4n +.EX +fseek(stream, 0, SEEK_END); +.EE +.in +.PP +The file descriptor associated with the stream is opened as if by a call to +.BR open (2) +with the following flags: +.RS +.TS +allbox; +lb lb +c l. +fopen() mode open() flags +\fIr\fP O_RDONLY +\fIw\fP O_WRONLY | O_CREAT | O_TRUNC +\fIa\fP O_WRONLY | O_CREAT | O_APPEND +\fIr+\fP O_RDWR +\fIw+\fP O_RDWR | O_CREAT | O_TRUNC +\fIa+\fP O_RDWR | O_CREAT | O_APPEND +.TE +.RE +.\" +.SS fdopen() +The +.BR fdopen () +function associates a stream with the existing file descriptor, +.IR fd . +The +.I mode +of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") +must be compatible with the mode of the file descriptor. +The file position indicator of the new stream is set to that +belonging to +.IR fd , +and the error and end-of-file indicators are cleared. +Modes "w" or "w+" do not cause truncation of the file. +The file descriptor is not dup'ed, and will be closed when +the stream created by +.BR fdopen () +is closed. +The result of applying +.BR fdopen () +to a shared memory object is undefined. +.\" +.SS freopen() +The +.BR freopen () +function opens the file whose name is the string pointed to by +.I pathname +and associates the stream pointed to by +.I stream +with it. +The original stream (if it exists) is closed. +The +.I mode +argument is used just as in the +.BR fopen () +function. +.PP +If the +.I pathname +argument is a null pointer, +.BR freopen () +changes the mode of the stream to that specified in +.IR mode ; +that is, +.BR freopen () +reopens the pathname that is associated with the stream. +The specification for this behavior was added in the C99 standard, which says: +.PP +.RS +In this case, +the file descriptor associated with the stream need not be closed +if the call to +.BR freopen () +succeeds. +It is implementation-defined which changes of mode are permitted (if any), +and under what circumstances. +.RE +.PP +The primary use of the +.BR freopen () +function is to change the file associated with a standard text stream +.RI ( stderr ", " stdin ", or " stdout ). +.SH RETURN VALUE +Upon successful completion +.BR fopen (), +.BR fdopen () +and +.BR freopen () +return a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I mode +provided to +.BR fopen (), +.BR fdopen (), +or +.BR freopen () +was invalid. +.PP +The +.BR fopen (), +.BR fdopen () +and +.BR freopen () +functions may also fail and set +.I errno +for any of the errors specified for the routine +.BR malloc (3). +.PP +The +.BR fopen () +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR open (2). +.PP +The +.BR fdopen () +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR fcntl (2). +.PP +The +.BR freopen () +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR open (2), +.BR fclose (3), +and +.BR fflush (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR fopen (), +.BR fdopen (), +.BR freopen () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR fopen (), +.BR freopen (): +POSIX.1-2001, POSIX.1-2008, C89, C99. +.PP +.BR fdopen (): +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +.SS Glibc notes +The GNU C library allows the following extensions for the string specified in +.IR mode : +.TP +.BR c " (since glibc 2.3.3)" +Do not make the open operation, +or subsequent read and write operations, +thread cancellation points. +This flag is ignored for +.BR fdopen (). +.TP +.BR e " (since glibc 2.7)" +Open the file with the +.B O_CLOEXEC +flag. +See +.BR open (2) +for more information. +This flag is ignored for +.BR fdopen (). +.TP +.BR m " (since glibc 2.3)" +Attempt to access the file using +.BR mmap (2), +rather than I/O system calls +.RB ( read (2), +.BR write (2)). +Currently, +.\" As at glibc 2.4: +use of +.BR mmap (2) +is attempted only for a file opened for reading. +.TP +.B x +.\" Since glibc 2.0? +.\" FIXME . C11 specifies this flag +Open the file exclusively +(like the +.B O_EXCL +flag of +.BR open (2)). +If the file already exists, +.BR fopen () +fails, and sets +.I errno +to +.BR EEXIST . +This flag is ignored for +.BR fdopen (). +.PP +In addition to the above characters, +.BR fopen () +and +.BR freopen () +support the following syntax +in +.IR mode : +.PP +.BI " ,ccs=" string +.PP +The given +.I string +is taken as the name of a coded character set and +the stream is marked as wide-oriented. +Thereafter, internal conversion functions convert I/O +to and from the character set +.IR string . +If the +.BI ,ccs= string +syntax is not specified, +then the wide-orientation of the stream is +determined by the first file operation. +If that operation is a wide-character operation, +the stream is marked wide-oriented, +and functions to convert to the coded character set are loaded. +.SH BUGS +When parsing for individual flag characters in +.IR mode +(i.e., the characters preceding the "ccs" specification), +the glibc implementation of +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685 +.BR fopen () +and +.BR freopen () +limits the number of characters examined in +.I mode +to 7 (or, in glibc versions before 2.14, to 6, +which was not enough to include possible specifications such as "rb+cmxe"). +The current implementation of +.BR fdopen () +parses at most 5 characters in +.IR mode . +.SH SEE ALSO +.BR open (2), +.BR fclose (3), +.BR fileno (3), +.BR fmemopen (3), +.BR fopencookie (3), +.BR open_memstream (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fopencookie.3 b/man3/fopencookie.3 new file mode 100644 index 0000000..0ea2d0d --- /dev/null +++ b/man3/fopencookie.3 @@ -0,0 +1,462 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FOPENCOOKIE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +fopencookie \- opening a custom stream +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "FILE *fopencookie(void *" cookie ", const char *" mode , +.BI " cookie_io_functions_t " io_funcs ); +.fi +.SH DESCRIPTION +The +.BR fopencookie () +function allows the programmer to create a custom implementation +for a standard I/O stream. +This implementation can store the stream's data at a location of +its own choosing; for example, +.BR fopencookie () +is used to implement +.BR fmemopen (3), +which provides a stream interface to data that is stored in a +buffer in memory. +.PP +In order to create a custom stream the programmer must: +.IP * 3 +Implement four "hook" functions that are used internally by the +standard I/O library when performing I/O on the stream. +.IP * +Define a "cookie" data type, +a structure that provides bookkeeping information +(e.g., where to store data) used by the aforementioned hook functions. +The standard I/O package knows nothing about the contents of this cookie +(thus it is typed as +.IR "void\ *" +when passed to +.BR fopencookie ()), +but automatically supplies the cookie +as the first argument when calling the hook functions. +.IP * +Call +.BR fopencookie () +to open a new stream and associate the cookie and hook functions +with that stream. +.PP +The +.BR fopencookie () +function serves a purpose similar to +.BR fopen (3): +it opens a new stream and returns a pointer to a +.I FILE +object that is used to operate on that stream. +.PP +The +.I cookie +argument is a pointer to the caller's cookie structure +that is to be associated with the new stream. +This pointer is supplied as the first argument when the standard I/O +library invokes any of the hook functions described below. +.PP +The +.I mode +argument serves the same purpose as for +.BR fopen (3). +The following modes are supported: +.IR r , +.IR w , +.IR a , +.IR r+ , +.IR w+ , +and +.IR a+ . +See +.BR fopen (3) +for details. +.PP +The +.I io_funcs +argument is a structure that contains four fields pointing to the +programmer-defined hook functions that are used to implement this stream. +The structure is defined as follows +.PP +.in +4n +.EX +typedef struct { + cookie_read_function_t *read; + cookie_write_function_t *write; + cookie_seek_function_t *seek; + cookie_close_function_t *close; +} cookie_io_functions_t; +.EE +.in +.PP +The four fields are as follows: +.TP +.I cookie_read_function_t *read +This function implements read operations for the stream. +When called, it receives three arguments: +.IP + ssize_t read(void *cookie, char *buf, size_t size); +.IP +The +.I buf +and +.I size +arguments are, respectively, +a buffer into which input data can be placed and the size of that buffer. +As its function result, the +.I read +function should return the number of bytes copied into +.IR buf , +0 on end of file, or \-1 on error. +The +.I read +function should update the stream offset appropriately. +.IP +If +.I *read +is a null pointer, +then reads from the custom stream always return end of file. +.TP +.I cookie_write_function_t *write +This function implements write operations for the stream. +When called, it receives three arguments: +.IP + ssize_t write(void *cookie, const char *buf, size_t size); +.IP +The +.I buf +and +.I size +arguments are, respectively, +a buffer of data to be output to the stream and the size of that buffer. +As its function result, the +.I write +function should return the number of bytes copied from +.IR buf , +or 0 on error. +(The function must not return a negative value.) +The +.I write +function should update the stream offset appropriately. +.IP +If +.I *write +is a null pointer, +then output to the stream is discarded. +.TP +.I cookie_seek_function_t *seek +This function implements seek operations on the stream. +When called, it receives three arguments: +.IP + int seek(void *cookie, off64_t *offset, int whence); +.IP +The +.I *offset +argument specifies the new file offset depending on which +of the following three values is supplied in +.IR whence : +.RS +.TP 10 +.B SEEK_SET +The stream offset should be set +.I *offset +bytes from the start of the stream. +.TP +.B SEEK_CUR +.I *offset +should be added to the current stream offset. +.TP +.B SEEK_END +The stream offset should be set to the size of the stream plus +.IR *offset . +.RE +.IP +Before returning, the +.I seek +function should update +.I *offset +to indicate the new stream offset. +.IP +As its function result, the +.I seek +function should return 0 on success, and \-1 on error. +.IP +If +.I *seek +is a null pointer, +then it is not possible to perform seek operations on the stream. +.TP +.I cookie_close_function_t *close +This function closes the stream. +The hook function can do things such as freeing buffers allocated +for the stream. +When called, it receives one argument: +.IP + int close(void *cookie); +.IP +The +.I cookie +argument is the cookie that the programmer supplied when calling +.BR fopencookie (). +.IP +As its function result, the +.I close +function should return 0 on success, and +.B EOF +on error. +.IP +If +.I *close +is NULL, then no special action is performed when the stream is closed. +.SH RETURN VALUE +On success +.BR fopencookie () +returns a pointer to the new stream. +On error, NULL is returned. +.\" .SH ERRORS +.\" It's not clear if errno ever gets set... +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fopencookie () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is a nonstandard GNU extension. +.SH EXAMPLE +The program below implements a custom stream whose functionality +is similar (but not identical) to that available via +.BR fmemopen (3). +It implements a stream whose data is stored in a memory buffer. +The program writes its command-line arguments to the stream, +and then seeks through the stream reading two out of every +five characters and writing them to standard output. +The following shell session demonstrates the use of the program: +.PP +.in +4n +.EX +.RB "$" " ./a.out \(aqhello world\(aq" +/he/ +/ w/ +/d/ +Reached end of file +.EE +.in +.PP +Note that a more general version of the program below +could be improved to more robustly handle various error situations +(e.g., opening a stream with a cookie that already has an open stream; +closing a stream that has already been closed). +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include + +#define INIT_BUF_SIZE 4 + +struct memfile_cookie { + char *buf; /* Dynamically sized buffer for data */ + size_t allocated; /* Size of buf */ + size_t endpos; /* Number of characters in buf */ + off_t offset; /* Current file offset in buf */ +}; + +ssize_t +memfile_write(void *c, const char *buf, size_t size) +{ + char *new_buff; + struct memfile_cookie *cookie = c; + + /* Buffer too small? Keep doubling size until big enough */ + + while (size + cookie\->offset > cookie\->allocated) { + new_buff = realloc(cookie\->buf, cookie\->allocated * 2); + if (new_buff == NULL) { + return \-1; + } else { + cookie\->allocated *= 2; + cookie\->buf = new_buff; + } + } + + memcpy(cookie\->buf + cookie\->offset, buf, size); + + cookie\->offset += size; + if (cookie\->offset > cookie\->endpos) + cookie\->endpos = cookie\->offset; + + return size; +} + +ssize_t +memfile_read(void *c, char *buf, size_t size) +{ + ssize_t xbytes; + struct memfile_cookie *cookie = c; + + /* Fetch minimum of bytes requested and bytes available */ + + xbytes = size; + if (cookie\->offset + size > cookie\->endpos) + xbytes = cookie\->endpos \- cookie\->offset; + if (xbytes < 0) /* offset may be past endpos */ + xbytes = 0; + + memcpy(buf, cookie\->buf + cookie\->offset, xbytes); + + cookie\->offset += xbytes; + return xbytes; +} + +int +memfile_seek(void *c, off64_t *offset, int whence) +{ + off64_t new_offset; + struct memfile_cookie *cookie = c; + + if (whence == SEEK_SET) + new_offset = *offset; + else if (whence == SEEK_END) + new_offset = cookie\->endpos + *offset; + else if (whence == SEEK_CUR) + new_offset = cookie\->offset + *offset; + else + return \-1; + + if (new_offset < 0) + return \-1; + + cookie\->offset = new_offset; + *offset = new_offset; + return 0; +} + +int +memfile_close(void *c) +{ + struct memfile_cookie *cookie = c; + + free(cookie\->buf); + cookie\->allocated = 0; + cookie\->buf = NULL; + + return 0; +} + +int +main(int argc, char *argv[]) +{ + cookie_io_functions_t memfile_func = { + .read = memfile_read, + .write = memfile_write, + .seek = memfile_seek, + .close = memfile_close + }; + FILE *stream; + struct memfile_cookie mycookie; + ssize_t nread; + long p; + int j; + char buf[1000]; + + /* Set up the cookie before calling fopencookie() */ + + mycookie.buf = malloc(INIT_BUF_SIZE); + if (mycookie.buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + + mycookie.allocated = INIT_BUF_SIZE; + mycookie.offset = 0; + mycookie.endpos = 0; + + stream = fopencookie(&mycookie,"w+", memfile_func); + if (stream == NULL) { + perror("fopencookie"); + exit(EXIT_FAILURE); + } + + /* Write command\-line arguments to our file */ + + for (j = 1; j < argc; j++) + if (fputs(argv[j], stream) == EOF) { + perror("fputs"); + exit(EXIT_FAILURE); + } + + /* Read two bytes out of every five, until EOF */ + + for (p = 0; ; p += 5) { + if (fseek(stream, p, SEEK_SET) == \-1) { + perror("fseek"); + exit(EXIT_FAILURE); + } + nread = fread(buf, 1, 2, stream); + if (nread == \-1) { + perror("fread"); + exit(EXIT_FAILURE); + } + if (nread == 0) { + printf("Reached end of file\\n"); + break; + } + + printf("/%.*s/\\n", nread, buf); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fclose (3), +.BR fmemopen (3), +.BR fopen (3), +.BR fseek (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/forkpty.3 b/man3/forkpty.3 new file mode 100644 index 0000000..fb4952d --- /dev/null +++ b/man3/forkpty.3 @@ -0,0 +1 @@ +.so man3/openpty.3 diff --git a/man3/fpathconf.3 b/man3/fpathconf.3 new file mode 100644 index 0000000..93c343c --- /dev/null +++ b/man3/fpathconf.3 @@ -0,0 +1,294 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (C) 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 28 11:12:26 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" FIXME Probably all of the following should be documented: +.\" _PC_SYNC_IO, +.\" _PC_ASYNC_IO, +.\" _PC_PRIO_IO, +.\" _PC_SOCK_MAXBUF, +.\" _PC_FILESIZEBITS, +.\" _PC_REC_INCR_XFER_SIZE, +.\" _PC_REC_MAX_XFER_SIZE, +.\" _PC_REC_MIN_XFER_SIZE, +.\" _PC_REC_XFER_ALIGN, +.\" _PC_ALLOC_SIZE_MIN, +.\" _PC_SYMLINK_MAX, +.\" _PC_2_SYMLINKS +.\" +.TH FPATHCONF 3 2017-07-13 "GNU" "Linux Programmer's Manual" +.SH NAME +fpathconf, pathconf \- get configuration values for files +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long fpathconf(int " fd ", int " name ); +.BI "long pathconf(const char *" path ", int " name ); +.fi +.SH DESCRIPTION +.BR fpathconf () +gets a value for the configuration option +.I name +for the open file descriptor +.IR fd . +.PP +.BR pathconf () +gets a value for configuration option +.I name +for the filename +.IR path . +.PP +The corresponding macros defined in +.I +are minimum values; if an application wants to take advantage of values +which may change, a call to +.BR fpathconf () +or +.BR pathconf () +can be made, which may yield more liberal results. +.PP +Setting +.I name +equal to one of the following constants returns the following +configuration options: +.TP +.B _PC_LINK_MAX +The maximum number of links to the file. +If +.I fd +or +.I path +refer to a directory, then the value applies to the whole directory. +The corresponding macro is +.BR _POSIX_LINK_MAX . +.TP +.B _PC_MAX_CANON +The maximum length of a formatted input line, where +.I fd +or +.I path +must refer to a terminal. +The corresponding macro is +.BR _POSIX_MAX_CANON . +.TP +.B _PC_MAX_INPUT +The maximum length of an input line, where +.I fd +or +.I path +must refer to a terminal. +The corresponding macro is +.BR _POSIX_MAX_INPUT . +.TP +.B _PC_NAME_MAX +The maximum length of a filename in the directory +.I path +or +.IR fd +that the process is allowed to create. +The corresponding macro is +.BR _POSIX_NAME_MAX . +.TP +.B _PC_PATH_MAX +The maximum length of a relative pathname when +.I path +or +.I fd +is the current working directory. +The corresponding macro is +.BR _POSIX_PATH_MAX . +.TP +.B _PC_PIPE_BUF +The maximum number of bytes that can be written atomically to a pipe of FIFO. +For +.BR fpathconf (), +.I fd +should refer to a pipe or FIFO. +For +.BR fpathconf (), +.I path +should refer to a FIFO or a directory; in the latter case, +the returned value corresponds to FIFOs created in that directory. +The corresponding macro is +.BR _POSIX_PIPE_BUF . +.TP +.B _PC_CHOWN_RESTRICTED +This returns a positive value if the use of +.BR chown (2) +and +.BR fchown (2) +for changing a file's user ID is restricted to a process +with appropriate privileges, +and changing a file's group ID to a value other than the process's +effective group ID or one of its supplementary group IDs +is restricted to a process with appropriate privileges. +According to POSIX.1, +this variable shall always be defined with a value other than \-1. +The corresponding macro is +.BR _POSIX_CHOWN_RESTRICTED . +.IP +If +.I fd +or +.I path +refers to a directory, +then the return value applies to all files in that directory. +.TP +.B _PC_NO_TRUNC +This returns nonzero if accessing filenames longer than +.B _POSIX_NAME_MAX +generates an error. +The corresponding macro is +.BR _POSIX_NO_TRUNC . +.TP +.B _PC_VDISABLE +This returns nonzero if special character processing can be disabled, where +.I fd +or +.I path +must refer to a terminal. +.SH RETURN VALUE +The return value of these functions is one of the following: +.IP * 3 +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error +(for example, +.BR EINVAL , +indicating that +.I name +is invalid). +.IP * +If +.I name +corresponds to a maximum or minimum limit, and that limit is indeterminate, +\-1 is returned and +.I errno +is not changed. +(To distinguish an indeterminate limit from an error, set +.I errno +to zero before the call, and then check whether +.I errno +is nonzero when \-1 is returned.) +.IP * +If +.I name +corresponds to an option, +a positive value is returned if the option is supported, +and \-1 is returned if the option is not supported. +.IP * +Otherwise, +the current value of the option or limit is returned. +This value will not be more restrictive than +the corresponding value that was described to the application in +.I +or +.I +when the application was compiled. +.SH ERRORS +.TP +.B EACCES +.RB ( pathconf ()) +Search permission is denied for one of the directories in the path prefix of +.IR path . +.TP +.B EBADF +.RB ( fpathconf ()) +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I name +is invalid. +.TP +.B EINVAL +The implementation does not support an association of +.I name +with the specified file. +.TP +.B ELOOP +.RB ( pathconf ()) +Too many symbolic links were encountered while resolving +.IR path . +.TP +.B ENAMETOOLONG +.RB ( pathconf ()) +.I path +is too long. +.TP +.B ENOENT +.RB ( pathconf ()) +A component of +.I path +does not exist, or +.I path +is an empty string. +.TP +.B ENOTDIR +.RB ( pathconf ()) +A component used as a directory in +.I path +is not in fact a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR fpathconf (), +.BR pathconf () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +Files with name lengths longer than the value returned for +.I name +equal to +.B _PC_NAME_MAX +may exist in the given directory. +.PP +Some returned values may be huge; they are not suitable for allocating +memory. +.SH SEE ALSO +.BR getconf (1), +.BR open (2), +.BR statfs (2), +.BR confstr (3), +.BR sysconf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fpclassify.3 b/man3/fpclassify.3 new file mode 100644 index 0000000..eb0f37d --- /dev/null +++ b/man3/fpclassify.3 @@ -0,0 +1,156 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" This was done with the help of the glibc manual. +.\" +.\" 2004-10-31, aeb, corrected +.TH FPCLASSIFY 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fpclassify, isfinite, isnormal, isnan, isinf \- floating-point +classification macros +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fpclassify(" x ); +.PP +.BI "int isfinite(" x ); +.PP +.BI "int isnormal(" x ); +.PP +.BI "int isnan(" x ); +.PP +.BI "int isinf(" x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.\" I haven't fully grokked the source to determine the FTM requirements; +.\" in part, the following has been tested by experiment. +.ad l +.BR fpclassify (), +.BR isfinite (), +.BR isnormal (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.BR isnan (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.BR isinf (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +Floating point numbers can have special values, such as +infinite or NaN. +With the macro +.BI fpclassify( x ) +you can find out what type +.I x +is. +The macro takes any floating-point expression as argument. +The result is one of the following values: +.TP 14 +.B FP_NAN +.I x +is "Not a Number". +.TP +.B FP_INFINITE +.I x +is either positive infinity or negative infinity. +.TP +.B FP_ZERO +.I x +is zero. +.TP +.B FP_SUBNORMAL +.I x +is too small to be represented in normalized format. +.TP +.B FP_NORMAL +if nothing of the above is correct then it must be a +normal floating-point number. +.PP +The other macros provide a short answer to some standard questions. +.TP 14 +.BI isfinite( x ) +returns a nonzero value if +.br +(fpclassify(x) != FP_NAN && fpclassify(x) != FP_INFINITE) +.TP +.BI isnormal( x ) +returns a nonzero value if +(fpclassify(x) == FP_NORMAL) +.TP +.BI isnan( x ) +returns a nonzero value if +(fpclassify(x) == FP_NAN) +.TP +.BI isinf( x ) +returns 1 if +.I x +is positive infinity, and \-1 if +.I x +is negative infinity. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR fpclassify (), +.BR isfinite (), +.BR isnormal (), +.BR isnan (), +.BR isinf () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.PP +For +.BR isinf (), +the standards merely say that the return value is nonzero +if and only if the argument has an infinite value. +.SH NOTES +In glibc 2.01 and earlier, +.BR isinf () +returns a nonzero value (actually: 1) if +.I x +is positive infinity or negative infinity. +(This is all that C99 requires.) +.SH SEE ALSO +.BR finite (3), +.BR INFINITY (3), +.BR isgreater (3), +.BR signbit (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fprintf.3 b/man3/fprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man3/fprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/fpurge.3 b/man3/fpurge.3 new file mode 100644 index 0000000..ba1ec91 --- /dev/null +++ b/man3/fpurge.3 @@ -0,0 +1,105 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FPURGE 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fpurge, __fpurge \- purge a stream +.SH SYNOPSIS +.nf +/* unsupported */ +.B #include +.PP +.BI "int fpurge(FILE *" stream ); + +/* supported */ +.B #include +.B #include +.PP +.BI "void __fpurge(FILE *" stream ); +.fi +.SH DESCRIPTION +The function +.BR fpurge () +clears the buffers of the given stream. +For output streams this discards any unwritten output. +For input streams this discards any input read from the underlying object +but not yet obtained via +.BR getc (3); +this includes any text pushed back via +.BR ungetc (3). +See also +.BR fflush (3). +.PP +The function +.BR __fpurge () +does precisely the same, but without returning a value. +.SH RETURN VALUE +Upon successful completion +.BR fpurge () +returns 0. +On error, it returns \-1 and sets +.I errno +appropriately. +.SH ERRORS +.TP +.B EBADF +.I stream +is not an open stream. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR __fpurge () +T} Thread safety MT-Safe race:stream +.TE +.sp 1 +.SH CONFORMING TO +These functions are nonstandard and not portable. +The function +.BR fpurge () +was introduced in 4.4BSD and is not available under Linux. +The function +.BR __fpurge () +was introduced in Solaris, and is present in glibc 2.1.95 and later. +.SH NOTES +Usually it is a mistake to want to discard input buffers. +.SH SEE ALSO +.\" .BR fclean (3), +.BR fflush (3), +.BR setbuf (3), +.BR stdio_ext (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fputc.3 b/man3/fputc.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man3/fputc.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man3/fputc_unlocked.3 b/man3/fputc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fputc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fputs.3 b/man3/fputs.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man3/fputs.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man3/fputs_unlocked.3 b/man3/fputs_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fputs_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fputwc.3 b/man3/fputwc.3 new file mode 100644 index 0000000..746294f --- /dev/null +++ b/man3/fputwc.3 @@ -0,0 +1,110 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH FPUTWC 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fputwc, putwc \- write a wide character to a FILE stream +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "wint_t fputwc(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwc(wchar_t " wc ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fputwc () +function is the wide-character +equivalent of the +.BR fputc (3) +function. +It writes the wide character \fIwc\fP to \fIstream\fP. +If +\fIferror(stream)\fP becomes true, it returns +.BR WEOF . +If a wide-character conversion error occurs, +it sets \fIerrno\fP to \fBEILSEQ\fP and returns +.BR WEOF . +Otherwise, it returns \fIwc\fP. +.PP +The +.BR putwc () +function or macro functions identically to +.BR fputwc (). +It may be implemented as a macro, and may evaluate its argument +more than once. +There is no reason ever to use it. +.PP +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR fputwc () +function returns \fIwc\fP if no error occurred, or +.B WEOF +to indicate an error. +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +Apart from the usual ones, there is +.TP +.B EILSEQ +Conversion of \fIwc\fP to the stream's encoding fails. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw17 lb lb +l l l. +Interface Attribute Value +T{ +.BR fputwc (), +.BR putwc () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR fputwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fputwc () +will actually write the multibyte +sequence corresponding to the wide character \fIwc\fP. +.SH SEE ALSO +.BR fgetwc (3), +.BR fputws (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fputwc_unlocked.3 b/man3/fputwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fputwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fputws.3 b/man3/fputws.3 new file mode 100644 index 0000000..f86d29d --- /dev/null +++ b/man3/fputws.3 @@ -0,0 +1,84 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH FPUTWS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fputws \- write a wide-character string to a FILE stream +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fputws(const wchar_t *" ws ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fputws () +function is the wide-character equivalent of +the +.BR fputs (3) +function. +It writes the wide-character string starting at \fIws\fP, up to but +not including the terminating null wide character (L\(aq\\0\(aq), to \fIstream\fP. +.PP +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR fputws () +function returns a +nonnegative integer if the operation was +successful, or \-1 to indicate an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR fputws () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR fputws () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fputws () +will actually write the multibyte +string corresponding to the wide-character string \fIws\fP. +.SH SEE ALSO +.BR fputwc (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fputws_unlocked.3 b/man3/fputws_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fputws_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/fread.3 b/man3/fread.3 new file mode 100644 index 0000000..3997078 --- /dev/null +++ b/man3/fread.3 @@ -0,0 +1,130 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)fread.3 6.6 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:37:33 1993, faith@cs.unc.edu +.\" Sun Feb 19 21:26:54 1995 by faith, return values +.\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt +.\" Modified Fri May 17 10:21:51 1996 by Martin Schulze +.\" +.TH FREAD 3 2015-07-23 "GNU" "Linux Programmer's Manual" +.SH NAME +fread, fwrite \- binary stream input/output +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t fread(void *" ptr ", size_t " size ", size_t " nmemb \ +", FILE *" stream ); +.PP +.BI "size_t fwrite(const void *" ptr ", size_t " size ", size_t " nmemb , +.BI " FILE *" stream ); +.fi +.SH DESCRIPTION +The function +.BR fread () +reads +.I nmemb +items of data, each +.I size +bytes long, from the stream pointed to by +.IR stream , +storing them at the location given by +.IR ptr . +.PP +The function +.BR fwrite () +writes +.I nmemb +items of data, each +.I size +bytes long, to the stream pointed to by +.IR stream , +obtaining them from the location given by +.IR ptr . +.PP +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fread () +and +.BR fwrite () +return the number of items read or written. +This number equals the number of bytes transferred only when +.I size +is 1. +If an error occurs, or the end of the file is reached, +the return value is a short item count (or zero). +.PP +.BR fread () +does not distinguish between end-of-file and error, and callers must use +.BR feof (3) +and +.BR ferror (3) +to determine which occurred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw17 lb lb +l l l. +Interface Attribute Value +T{ +.BR fread (), +.BR fwrite () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89. +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR feof (3), +.BR ferror (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fread_unlocked.3 b/man3/fread_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fread_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/free.3 b/man3/free.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man3/free.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man3/freeaddrinfo.3 b/man3/freeaddrinfo.3 new file mode 100644 index 0000000..17f7236 --- /dev/null +++ b/man3/freeaddrinfo.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo.3 diff --git a/man3/freehostent.3 b/man3/freehostent.3 new file mode 100644 index 0000000..82e01df --- /dev/null +++ b/man3/freehostent.3 @@ -0,0 +1 @@ +.so man3/getipnodebyname.3 diff --git a/man3/freeifaddrs.3 b/man3/freeifaddrs.3 new file mode 100644 index 0000000..38f977d --- /dev/null +++ b/man3/freeifaddrs.3 @@ -0,0 +1 @@ +.so man3/getifaddrs.3 diff --git a/man3/freelocale.3 b/man3/freelocale.3 new file mode 100644 index 0000000..a4246c5 --- /dev/null +++ b/man3/freelocale.3 @@ -0,0 +1 @@ +.so man3/newlocale.3 diff --git a/man3/freopen.3 b/man3/freopen.3 new file mode 100644 index 0000000..9a40124 --- /dev/null +++ b/man3/freopen.3 @@ -0,0 +1 @@ +.so man3/fopen.3 diff --git a/man3/frexp.3 b/man3/frexp.3 new file mode 100644 index 0000000..7961f59 --- /dev/null +++ b/man3/frexp.3 @@ -0,0 +1,165 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH FREXP 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +frexp, frexpf, frexpl \- convert floating-point number to fractional +and integral components +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double frexp(double " x ", int *" exp ); +.BI "float frexpf(float " x ", int *" exp ); +.BI "long double frexpl(long double " x ", int *" exp ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR frexpf (), +.BR frexpl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions are used to split the number +.I x +into a +normalized fraction and an exponent which is stored in +.IR exp . +.SH RETURN VALUE +These functions return the normalized fraction. +If the argument +.I x +is not zero, +the normalized fraction is +.I x +times a power of two, +and its absolute value is always in the range 1/2 (inclusive) to +1 (exclusive), that is, [0.5,1). +.PP +If +.I x +is zero, then the normalized fraction is +zero and zero is stored in +.IR exp . +.PP +If +.I x +is a NaN, +a NaN is returned, and the value of +.I *exp +is unspecified. +.PP +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned, and the value of +.I *exp +is unspecified. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR frexp (), +.BR frexpf (), +.BR frexpl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH EXAMPLE +The program below produces results such as the following: +.PP +.in +4n +.EX +.RB "$" " ./a.out 2560" +frexp(2560, &e) = 0.625: 0.625 * 2^12 = 2560 +.RB "$" " ./a.out \-4" +frexp(\-4, &e) = \-0.5: \-0.5 * 2^3 = \-4 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + double x, r; + int exp; + + x = strtod(argv[1], NULL); + r = frexp(x, &exp); + + printf("frexp(%g, &e) = %g: %g * %d^%d = %g\\n", + x, r, r, FLT_RADIX, exp, x); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ldexp (3), +.BR modf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/frexpf.3 b/man3/frexpf.3 new file mode 100644 index 0000000..980426f --- /dev/null +++ b/man3/frexpf.3 @@ -0,0 +1 @@ +.so man3/frexp.3 diff --git a/man3/frexpl.3 b/man3/frexpl.3 new file mode 100644 index 0000000..980426f --- /dev/null +++ b/man3/frexpl.3 @@ -0,0 +1 @@ +.so man3/frexp.3 diff --git a/man3/fscanf.3 b/man3/fscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man3/fscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/fseek.3 b/man3/fseek.3 new file mode 100644 index 0000000..774d4d5 --- /dev/null +++ b/man3/fseek.3 @@ -0,0 +1,200 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)fseek.3 6.11 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" +.TH FSEEK 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream +.SH SYNOPSIS +.B #include +.PP +.BI "int fseek(FILE *" stream ", long " offset ", int " whence ); +.PP +.BI "long ftell(FILE *" stream ); +.PP +.BI "void rewind(FILE *" stream ); +.PP +.BI "int fgetpos(FILE *" stream ", fpos_t *" pos ); +.PP +.BI "int fsetpos(FILE *" stream ", const fpos_t *" pos ); +.SH DESCRIPTION +The +.BR fseek () +function sets the file position indicator for the stream pointed to by +.IR stream . +The new position, measured in bytes, is obtained by adding +.I offset +bytes to the position specified by +.IR whence . +If +.I whence +is set to +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +the offset is relative to the start of the file, the current position +indicator, or end-of-file, respectively. +A successful call to the +.BR fseek () +function clears the end-of-file indicator for the stream and undoes +any effects of the +.BR ungetc (3) +function on the same stream. +.PP +The +.BR ftell () +function obtains the current value of the file position indicator for the +stream pointed to by +.IR stream . +.PP +The +.BR rewind () +function sets the file position indicator for the stream pointed to by +.I stream +to the beginning of the file. +It is equivalent to: +.PP +.RS +(void) fseek(stream, 0L, SEEK_SET) +.RE +.PP +except that the error indicator for the stream is also cleared (see +.BR clearerr (3)). +.PP +The +.BR fgetpos () +and +.BR fsetpos () +functions are alternate interfaces equivalent to +.BR ftell () +and +.BR fseek () +(with +.I whence +set to +.BR SEEK_SET ), +setting and storing the current value of the file offset into or from the +object referenced by +.IR pos . +On some non-UNIX systems, an +.I fpos_t +object may be a complex object and these routines may be the only way to +portably reposition a text stream. +.SH RETURN VALUE +The +.BR rewind () +function returns no value. +Upon successful completion, +.BR fgetpos (), +.BR fseek (), +.BR fsetpos () +return 0, +and +.BR ftell () +returns the current offset. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The +.I stream +specified is not a seekable stream. +.TP +.B EINVAL +The +.I whence +argument to +.BR fseek () +was not +.BR SEEK_SET , +.BR SEEK_END , +or +.BR SEEK_CUR . +Or: the resulting file offset would be negative. +.PP +The functions +.BR fgetpos (), +.BR fseek (), +.BR fsetpos (), +and +.BR ftell () +may also fail and set +.I errno +for any of the errors specified for the routines +.BR fflush (3), +.BR fstat (2), +.BR lseek (2), +and +.BR malloc (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR fseek (), +.BR ftell (), +.BR rewind (), +.br +.BR fgetpos (), +.BR fsetpos () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.SH SEE ALSO +.BR lseek (2), +.BR fseeko (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fseeko.3 b/man3/fseeko.3 new file mode 100644 index 0000000..53e560c --- /dev/null +++ b/man3/fseeko.3 @@ -0,0 +1,127 @@ +.\" Copyright 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FSEEKO 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +fseeko, ftello \- seek to or report file position +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fseeko(FILE *" stream ", off_t " offset ", int " whence ); +.PP +.BI "off_t ftello(FILE *" stream ); +.BI +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fseeko (), +.BR ftello (): +.br +.RS 4 +.ad l +_FILE_OFFSET_BITS\ ==\ 64 || _POSIX_C_SOURCE\ >=\ 200112L +.br +(defining the obsolete _LARGEFILE_SOURCE macro also works) +.RE +.ad +.SH DESCRIPTION +The +.BR fseeko () +and +.BR ftello () +functions are identical to +.BR fseek (3) +and +.BR ftell (3) +(see +.BR fseek (3)), +respectively, except that the +.I offset +argument of +.BR fseeko () +and the return value of +.BR ftello () +is of type +.I off_t +instead of +.IR long . +.PP +On some architectures, both +.IR off_t +and +.I long +are 32-bit types, but defining +.BR _FILE_OFFSET_BITS +with the value 64 (before including +.I any +header files) +will turn +.I off_t +into a 64-bit type. +.SH RETURN VALUE +On successful completion, +.BR fseeko () +returns 0, while +.BR ftello () +returns the current offset. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +See the ERRORS in +.BR fseek (3). +.SH VERSIONS +These functions are available under glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw18 lb lb +l l l. +Interface Attribute Value +T{ +.BR fseeko (), +.BR ftello () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SUSv2. +.SH SEE ALSO +.BR fseek (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fsetpos.3 b/man3/fsetpos.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man3/fsetpos.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man3/fstatvfs.3 b/man3/fstatvfs.3 new file mode 100644 index 0000000..adec9dd --- /dev/null +++ b/man3/fstatvfs.3 @@ -0,0 +1 @@ +.so man3/statvfs.3 diff --git a/man3/ftell.3 b/man3/ftell.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man3/ftell.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man3/ftello.3 b/man3/ftello.3 new file mode 100644 index 0000000..d5628f4 --- /dev/null +++ b/man3/ftello.3 @@ -0,0 +1 @@ +.so man3/fseeko.3 diff --git a/man3/ftime.3 b/man3/ftime.3 new file mode 100644 index 0000000..31a5ddc --- /dev/null +++ b/man3/ftime.3 @@ -0,0 +1,118 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 14:23:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Oct 18 17:31:43 1998 by Andries Brouwer (aeb@cwi.nl) +.\" 2008-06-23, mtk, minor rewrites, added some details +.\" +.TH FTIME 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +ftime \- return date and time +.SH SYNOPSIS +.B "#include " +.PP +.BI "int ftime(struct timeb *" tp ); +.SH DESCRIPTION +This function returns the current time as seconds and milliseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +The time is returned in +.IR tp , +which is declared as follows: +.PP +.in +4n +.EX +struct timeb { + time_t time; + unsigned short millitm; + short timezone; + short dstflag; +}; +.EE +.in +.PP +Here \fItime\fP is the number of seconds since the Epoch, +and \fImillitm\fP is the number of milliseconds since \fItime\fP +seconds since the Epoch. +The \fItimezone\fP field is the local timezone measured in minutes +of time west of Greenwich (with a negative value indicating minutes +east of Greenwich). +The \fIdstflag\fP field +is a flag that, if nonzero, indicates that Daylight Saving time +applies locally during the appropriate part of the year. +.PP +POSIX.1-2001 says that the contents of the \fItimezone\fP and \fIdstflag\fP +fields are unspecified; avoid relying on them. +.SH RETURN VALUE +This function always returns 0. +(POSIX.1-2001 specifies, and some systems document, a \-1 error return.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ftime () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.2BSD, POSIX.1-2001. +POSIX.1-2008 removes the specification of +.BR ftime (). +.PP +This function is obsolete. +Don't use it. +If the time in seconds +suffices, +.BR time (2) +can be used; +.BR gettimeofday (2) +gives microseconds; +.BR clock_gettime (2) +gives nanoseconds but is not as widely available. +.SH BUGS +.PP +Early glibc2 is buggy and returns 0 in the +.I millitm +field; +glibc 2.1.1 is correct again. +.\" .SH HISTORY +.\" The +.\" .BR ftime () +.\" function appeared in 4.2BSD. +.SH SEE ALSO +.BR gettimeofday (2), +.BR time (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ftok.3 b/man3/ftok.3 new file mode 100644 index 0000000..214f733 --- /dev/null +++ b/man3/ftok.3 @@ -0,0 +1,129 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 2001-11-28, by Michael Kerrisk, +.\" Changed data type of proj_id; minor fixes +.\" aeb: further fixes; added notes. +.\" +.TH FTOK 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +ftok \- convert a pathname and a project identifier to a System V IPC key +.SH SYNOPSIS +.nf +.B #include +.B #include +.fi +.PP +.BI "key_t ftok(const char *" pathname ", int " proj_id ); +.SH DESCRIPTION +The +.BR ftok () +function uses the identity of the file named by the given +.I pathname +(which must refer to an existing, accessible file) +and the least significant 8 bits of +.I proj_id +(which must be nonzero) to generate a +.I key_t +type System V IPC key, suitable for use with +.BR msgget (2), +.BR semget (2), +or +.BR shmget (2). +.PP +The resulting value is the same for all pathnames that +name the same file, when the same value of +.I proj_id +is used. +The value returned should be different when the +(simultaneously existing) files or the project IDs differ. +.SH RETURN VALUE +On success, the generated +.I key_t +value is returned. +On failure \-1 is returned, with +.I errno +indicating the error as for the +.BR stat (2) +system call. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ftok () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +On some ancient systems, the prototype was: +.PP +.in +4n +.EX +.BI "key_t ftok(char *" pathname ", char " proj_id ); +.EE +.in +.PP +Today, +.I proj_id +is an +.IR int , +but still only 8 bits are used. +Typical usage has an ASCII character +.IR proj_id , +that is why the behavior is said to be undefined when +.I proj_id +is zero. +.PP +Of course, no guarantee can be given that the resulting +.I key_t +is unique. +Typically, a best-effort attempt combines the given +.I proj_id +byte, the lower 16 bits of the inode number, and the +lower 8 bits of the device number into a 32-bit result. +Collisions may easily happen, for example between files on +.I /dev/hda1 +and files on +.IR /dev/sda1 . +.SH SEE ALSO +.BR msgget (2), +.BR semget (2), +.BR shmget (2), +.BR stat (2), +.BR svipc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ftrylockfile.3 b/man3/ftrylockfile.3 new file mode 100644 index 0000000..b33c2ee --- /dev/null +++ b/man3/ftrylockfile.3 @@ -0,0 +1 @@ +.so man3/flockfile.3 diff --git a/man3/fts.3 b/man3/fts.3 new file mode 100644 index 0000000..af80e37 --- /dev/null +++ b/man3/fts.3 @@ -0,0 +1,848 @@ +.\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)fts.3 8.5 (Berkeley) 4/16/94 +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH FTS 3 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \ +traverse a file hierarchy +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "FTS *fts_open(char * const *" path_argv ", int " options ", " +.BI " int (*" compar ")(const FTSENT **, const FTSENT **));" +.PP +.BI "FTSENT *fts_read(FTS *" ftsp ); +.PP +.BI "FTSENT *fts_children(FTS *" ftsp ", int " instr ); +.PP +.BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr ); +.PP +.BI "int fts_close(FTS *" ftsp ); +.fi +.SH DESCRIPTION +The +fts functions are provided for traversing +file hierarchies. +A simple overview is that the +.BR fts_open () +function returns a "handle" (of type +.IR "FTS\ *" ) +that refers to a file hierarchy "stream". +This handle is then supplied to the other +fts functions. +The function +.BR fts_read () +returns a pointer to a structure describing one of the files in the file +hierarchy. +The function +.BR fts_children () +returns a pointer to a linked list of structures, each of which describes +one of the files contained in a directory in the hierarchy. +.PP +In general, directories are visited two distinguishable times; in preorder +(before any of their descendants are visited) and in postorder (after all +of their descendants have been visited). +Files are visited once. +It is possible to walk the hierarchy "logically" (visiting the files that +symbolic links point to) +or physically (visiting the symbolic links themselves), +order the walk of the hierarchy or +prune and/or revisit portions of the hierarchy. +.PP +Two structures (and associated types) are defined in the include file +.IR . +The first type is +.IR FTS , +the structure that represents the file hierarchy itself. +The second type is +.IR FTSENT , +the structure that represents a file in the file +hierarchy. +Normally, an +.I FTSENT +structure is returned for every file in the file +hierarchy. +In this manual page, "file" and +"FTSENT structure" +are generally interchangeable. +.PP +The +.I FTSENT +structure contains fields describing a file. +The structure contains at least the following fields +(there are additional fields that +should be considered private to the implementation): +.PP +.in +4n +.EX +typedef struct _ftsent { + unsigned short fts_info; /* flags for FTSENT structure */ + char *fts_accpath; /* access path */ + char *fts_path; /* root path */ + short fts_pathlen; /* strlen(fts_path) + + strlen(fts_name) */ + char *fts_name; /* filename */ + short fts_namelen; /* strlen(fts_name) */ + short fts_level; /* depth (\-1 to N) */ + int fts_errno; /* file errno */ + long fts_number; /* local numeric value */ + void *fts_pointer; /* local address value */ + struct _ftsent *fts_parent; /* parent directory */ + struct _ftsent *fts_link; /* next file structure */ + struct _ftsent *fts_cycle; /* cycle structure */ + struct stat *fts_statp; /* stat(2) information */ +.\" Also: +.\" ino_t fts_ino; /* inode (only for directories)*/ +.\" dev_t fts_dev; /* device (only for directories)*/ +.\" nlink_t fts_nlink; /* link count (only for directories)*/ +.\" u_short fts_flags; /* private flags for FTSENT structure */ +.\" u_short fts_instr; /* fts_set() instructions */ +} FTSENT; +.EE +.in +.PP +These fields are defined as follows: +.\" .Bl -tag -width "fts_namelen" +.TP 12 +.IR fts_info +One of the following values describing the returned +.I FTSENT +structure and +the file it represents. +With the exception of directories without errors +.RB ( FTS_D ), +all of these +entries are terminal, that is, they will not be revisited, nor will any +of their descendants be visited. +.\" .Bl -tag -width FTS_DEFAULT +.RS 12 +.TP 12 +.BR FTS_D +A directory being visited in preorder. +.TP +.BR FTS_DC +A directory that causes a cycle in the tree. +(The +.I fts_cycle +field of the +.I FTSENT +structure will be filled in as well.) +.TP +.BR FTS_DEFAULT +Any +.I FTSENT +structure that represents a file type not explicitly described +by one of the other +.I fts_info +values. +.TP +.BR FTS_DNR +A directory which cannot be read. +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.BR FTS_DOT +A file named +"." +or +".." +which was not specified as a filename to +.BR fts_open () +(see +.BR FTS_SEEDOT ). +.TP +.BR FTS_DP +A directory being visited in postorder. +The contents of the +.I FTSENT +structure will be unchanged from when +it was returned in preorder, that is, with the +.I fts_info +field set to +.BR FTS_D . +.TP +.BR FTS_ERR +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.BR FTS_F +A regular file. +.TP +.BR FTS_NS +A file for which no +.BR stat (2) +information was available. +The contents of the +.I fts_statp +field are undefined. +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.BR FTS_NSOK +A file for which no +.BR stat (2) +information was requested. +The contents of the +.I fts_statp +field are undefined. +.TP +.BR FTS_SL +A symbolic link. +.TP +.BR FTS_SLNONE +A symbolic link with a nonexistent target. +The contents of the +.I fts_statp +field reference the file characteristic information for the symbolic link +itself. +.\" .El +.RE +.TP +.IR fts_accpath +A path for accessing the file from the current directory. +.TP +.IR fts_path +The path for the file relative to the root of the traversal. +This path contains the path specified to +.BR fts_open () +as a prefix. +.TP +.IR fts_pathlen +The sum of the lengths of the strings referenced by +.IR fts_path +and +.IR fts_name . +.TP +.IR fts_name +The name of the file. +.TP +.IR fts_namelen +The length of the string referenced by +.IR fts_name . +.TP +.IR fts_level +The depth of the traversal, numbered from \-1 to N, where this file +was found. +The +.I FTSENT +structure representing the parent of the starting point (or root) +of the traversal is numbered \-1, and the +.I FTSENT +structure for the root +itself is numbered 0. +.TP +.IR fts_errno +If +.BR fts_children () +or +.BR fts_read () +returns an +.I FTSENT +structure whose +.I fts_info +field is set to +.BR FTS_DNR , +.BR FTS_ERR , +or +.BR FTS_NS , +the +.I fts_errno +field contains the error number (i.e., the +.IR errno +value) +specifying the cause of the error. +Otherwise, the contents of the +.I fts_errno +field are undefined. +.TP +.IR fts_number +This field is provided for the use of the application program and is +not modified by the +fts functions. +It is initialized to 0. +.TP +.IR fts_pointer +This field is provided for the use of the application program and is +not modified by the +fts functions. +It is initialized to +NULL. +.TP +.IR fts_parent +A pointer to the +.I FTSENT +structure referencing the file in the hierarchy +immediately above the current file, that is, the directory of which this +file is a member. +A parent structure for the initial entry point is provided as well, +however, only the +.IR fts_level , +.IR fts_number , +and +.I fts_pointer +fields are guaranteed to be initialized. +.TP +.IR fts_link +Upon return from the +.BR fts_children () +function, the +.I fts_link +field points to the next structure in the NULL-terminated linked list of +directory members. +Otherwise, the contents of the +.I fts_link +field are undefined. +.TP +.IR fts_cycle +If a directory causes a cycle in the hierarchy (see +.BR FTS_DC ), +either because +of a hard link between two directories, or a symbolic link pointing to a +directory, the +.I fts_cycle +field of the structure will point to the +.I FTSENT +structure in the hierarchy that references the same file as the current +.I FTSENT +structure. +Otherwise, the contents of the +.I fts_cycle +field are undefined. +.TP +.IR fts_statp +A pointer to +.BR stat (2) +information for the file. +.\" .El +.PP +A single buffer is used for all of the paths of all of the files in the +file hierarchy. +Therefore, the +.I fts_path +and +.I fts_accpath +fields are guaranteed to be +null-terminated +.I only +for the file most recently returned by +.BR fts_read (). +To use these fields to reference any files represented by other +.I FTSENT +structures will require that the path buffer be modified using the +information contained in that +.I FTSENT +structure's +.I fts_pathlen +field. +Any such modifications should be undone before further calls to +.BR fts_read () +are attempted. +The +.I fts_name +field is always +null-terminated. +.SS fts_open() +The +.BR fts_open () +function takes a pointer to an array of character pointers naming one +or more paths which make up a logical file hierarchy to be traversed. +The array must be terminated by a +null pointer. +.PP +There are +a number of options, at least one of which (either +.BR FTS_LOGICAL +or +.BR FTS_PHYSICAL ) +must be specified. +The options are selected by ORing +the following values: +.\" .Bl -tag -width "FTS_PHYSICAL" +.TP 14 +.BR FTS_COMFOLLOW +This option causes any symbolic link specified as a root path to be +followed immediately whether or not +.BR FTS_LOGICAL +is also specified. +.TP +.BR FTS_LOGICAL +This option causes the +fts routines to return +.I FTSENT +structures for the targets of symbolic links +instead of the symbolic links themselves. +If this option is set, the only symbolic links for which +.I FTSENT +structures +are returned to the application are those referencing nonexistent files. +Either +.BR FTS_LOGICAL +or +.BR FTS_PHYSICAL +.I must +be provided to the +.BR fts_open () +function. +.TP +.BR FTS_NOCHDIR +As a performance optimization, the +fts functions change directories as they walk the file hierarchy. +This has the side-effect that an application cannot rely on being +in any particular directory during the traversal. +The +.BR FTS_NOCHDIR +option turns off this optimization, and the +fts functions will not change the current directory. +Note that applications should not themselves change their current directory +and try to access files unless +.BR FTS_NOCHDIR +is specified and absolute +pathnames were provided as arguments to +.BR fts_open (). +.TP +.BR FTS_NOSTAT +By default, returned +.I FTSENT +structures reference file characteristic information (the +.I statp +field) for each file visited. +This option relaxes that requirement as a performance optimization, +allowing the +fts functions to set the +.I fts_info +field to +.BR FTS_NSOK +and leave the contents of the +.I statp +field undefined. +.TP +.BR FTS_PHYSICAL +This option causes the +fts routines to return +.I FTSENT +structures for symbolic links themselves instead +of the target files they point to. +If this option is set, +.I FTSENT +structures for all symbolic links in the +hierarchy are returned to the application. +Either +.BR FTS_LOGICAL +or +.BR FTS_PHYSICAL +.I must +be provided to the +.BR fts_open () +function. +.TP +.BR FTS_SEEDOT +By default, unless they are specified as path arguments to +.BR fts_open (), +any files named +"." +or +".." +encountered in the file hierarchy are ignored. +This option causes the +fts routines to return +.I FTSENT +structures for them. +.TP +.BR FTS_XDEV +This option prevents +fts from descending into directories that have a different device number +than the file from which the descent began. +.\" .El +.PP +The argument +.BR compar () +specifies a user-defined function which may be used to order the traversal +of the hierarchy. +It +takes two pointers to pointers to +.I FTSENT +structures as arguments and +should return a negative value, zero, or a positive value to indicate +if the file referenced by its first argument comes before, in any order +with respect to, or after, the file referenced by its second argument. +The +.IR fts_accpath , +.IR fts_path , +and +.I fts_pathlen +fields of the +.I FTSENT +structures may +.I never +be used in this comparison. +If the +.I fts_info +field is set to +.BR FTS_NS +or +.BR FTS_NSOK , +the +.I fts_statp +field may not either. +If the +.BR compar () +argument is +NULL, +the directory traversal order is in the order listed in +.I path_argv +for the root paths, and in the order listed in the directory for +everything else. +.SS fts_read() +The +.BR fts_read () +function returns a pointer to an +.I FTSENT +structure describing a file in +the hierarchy. +Directories (that are readable and do not cause cycles) are visited at +least twice, once in preorder and once in postorder. +All other files are visited at least once. +(Hard links between directories that do not cause cycles or symbolic +links to symbolic links may cause files to be visited more than once, +or directories more than twice.) +.PP +If all the members of the hierarchy have been returned, +.BR fts_read () +returns +NULL +and sets the external variable +.I errno +to 0. +If an error unrelated to a file in the hierarchy occurs, +.BR fts_read () +returns +NULL +and sets +.I errno +appropriately. +If an error related to a returned file occurs, a pointer to an +.I FTSENT +structure is returned, and +.I errno +may or may not have been set (see +.IR fts_info ). +.PP +The +.I FTSENT +structures returned by +.BR fts_read () +may be overwritten after a call to +.BR fts_close () +on the same file hierarchy stream, or, after a call to +.BR fts_read () +on the same file hierarchy stream unless they represent a file of type +directory, in which case they will not be overwritten until after a call to +.BR fts_read () +after the +.I FTSENT +structure has been returned by the function +.BR fts_read () +in postorder. +.SS fts_children() +The +.BR fts_children () +function returns a pointer to an +.I FTSENT +structure describing the first entry in a NULL-terminated linked list of +the files in the directory represented by the +.I FTSENT +structure most recently returned by +.BR fts_read (). +The list is linked through the +.I fts_link +field of the +.I FTSENT +structure, and is ordered by the user-specified comparison function, if any. +Repeated calls to +.BR fts_children () +will re-create this linked list. +.PP +As a special case, if +.BR fts_read () +has not yet been called for a hierarchy, +.BR fts_children () +will return a pointer to the files in the logical directory specified to +.BR fts_open (), +that is, the arguments specified to +.BR fts_open (). +Otherwise, if the +.I FTSENT +structure most recently returned by +.BR fts_read () +is not a directory being visited in preorder, +or the directory does not contain any files, +.BR fts_children () +returns +NULL +and sets +.I errno +to zero. +If an error occurs, +.BR fts_children () +returns +NULL +and sets +.I errno +appropriately. +.PP +The +.I FTSENT +structures returned by +.BR fts_children () +may be overwritten after a call to +.BR fts_children (), +.BR fts_close (), +or +.BR fts_read () +on the same file hierarchy stream. +.PP +The +.I instr +argument is either zero or the following value: +.\" .Bl -tag -width FTS_NAMEONLY +.TP 13 +.BR FTS_NAMEONLY +Only the names of the files are needed. +The contents of all the fields in the returned linked list of structures +are undefined with the exception of the +.I fts_name +and +.I fts_namelen +fields. +.\" .El +.SS fts_set() +The function +.BR fts_set () +allows the user application to determine further processing for the +file +.I f +of the stream +.IR ftsp . +The +.BR fts_set () +function +returns 0 on success, and \-1 if an error occurs. +.PP +The +.I instr +argument is either 0 (meaning "do nothing") or one of the following values: +.\" .Bl -tag -width FTS_PHYSICAL +.TP 13 +.BR FTS_AGAIN +Revisit the file; any file type may be revisited. +The next call to +.BR fts_read () +will return the referenced file. +The +.I fts_stat +and +.I fts_info +fields of the structure will be reinitialized at that time, +but no other fields will have been changed. +This option is meaningful only for the most recently returned +file from +.BR fts_read (). +Normal use is for postorder directory visits, where it causes the +directory to be revisited (in both preorder and postorder) as well as all +of its descendants. +.TP +.BR FTS_FOLLOW +The referenced file must be a symbolic link. +If the referenced file is the one most recently returned by +.BR fts_read (), +the next call to +.BR fts_read () +returns the file with the +.I fts_info +and +.I fts_statp +fields reinitialized to reflect the target of the symbolic link instead +of the symbolic link itself. +If the file is one of those most recently returned by +.BR fts_children (), +the +.I fts_info +and +.I fts_statp +fields of the structure, when returned by +.BR fts_read (), +will reflect the target of the symbolic link instead of the symbolic link +itself. +In either case, if the target of the symbolic link does not exist, the +fields of the returned structure will be unchanged and the +.I fts_info +field will be set to +.BR FTS_SLNONE . +.IP +If the target of the link is a directory, the preorder return, followed +by the return of all of its descendants, followed by a postorder return, +is done. +.TP +.BR FTS_SKIP +No descendants of this file are visited. +The file may be one of those most recently returned by either +.BR fts_children () +or +.BR fts_read (). +.\" .El +.SS fts_close() +The +.BR fts_close () +function closes the file hierarchy stream referred to by +.I ftsp +and restores the current directory to the directory from which +.BR fts_open () +was called to open +.IR ftsp . +The +.BR fts_close () +function +returns 0 on success, and \-1 if an error occurs. +.SH ERRORS +The function +.BR fts_open () +may fail and set +.I errno +for any of the errors specified for +.BR open (2) +and +.BR malloc (3). +.PP +The function +.BR fts_close () +may fail and set +.I errno +for any of the errors specified for +.BR chdir (2) +and +.BR close (2). +.PP +The functions +.BR fts_read () +and +.BR fts_children () +may fail and set +.I errno +for any of the errors specified for +.BR chdir (2), +.BR malloc (3), +.BR opendir (3), +.BR readdir (3), +and +.BR stat (2). +.PP +In addition, +.BR fts_children (), +.BR fts_open (), +and +.BR fts_set () +may fail and set +.I errno +as follows: +.TP +.B EINVAL +.I options +or +.I instr +was invalid. +.SH VERSIONS +These functions are available in Linux since glibc2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw34 lb lb +l l l. +Interface Attribute Value +T{ +.BR fts_open (), +.BR fts_set (), +.BR fts_close () +T} Thread safety MT-Safe +T{ +.BR fts_read (), +.BR fts_children () +T} Thread safety MT-Unsafe +.TE +.sp 1 +.SH CONFORMING TO +4.4BSD. +.SH BUGS +In versions of glibc before 2.23, +.\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5 +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838 +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460 +all of the APIs described in this man page are not safe when compiling +a program using the LFS APIs (e.g., when compiling with +.IR -D_FILE_OFFSET_BITS=64 ). +.\" +.\" The following statement is years old, and seems no closer to +.\" being true -- mtk +.\" The +.\" .I fts +.\" utility is expected to be included in a future +.\" POSIX.1 +.\" revision. +.SH SEE ALSO +.BR find (1), +.BR chdir (2), +.BR stat (2), +.BR ftw (3), +.BR qsort (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fts_children.3 b/man3/fts_children.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man3/fts_children.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/fts_close.3 b/man3/fts_close.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man3/fts_close.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/fts_open.3 b/man3/fts_open.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man3/fts_open.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/fts_read.3 b/man3/fts_read.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man3/fts_read.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/fts_set.3 b/man3/fts_set.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man3/fts_set.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man3/ftw.3 b/man3/ftw.3 new file mode 100644 index 0000000..5c6a62e --- /dev/null +++ b/man3/ftw.3 @@ -0,0 +1,530 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" and copyright (c) 2006 Justin Pryzby +.\" and copyright (c) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) +.\" 2006-05-24, Justin Pryzby +.\" document FTW_ACTIONRETVAL; include .SH RETURN VALUE; +.\" 2006-05-24, Justin Pryzby and +.\" Michael Kerrisk +.\" reorganized and rewrote much of the page +.\" 2006-05-24, Michael Kerrisk +.\" Added an example program. +.\" +.TH FTW 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ftw, nftw \- file tree walk +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int nftw(const char *" dirpath , +.BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb , +.BI " int " typeflag ", struct FTW *" ftwbuf ), +.BI " int " nopenfd ", int " flags ); +.PP +.B #include +.PP +.BI "int ftw(const char *" dirpath , +.BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb , +.BI " int " typeflag ), +.BI " int " nopenfd ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR nftw (): +_XOPEN_SOURCE >= 500 +.SH DESCRIPTION +.BR nftw () +walks through the directory tree that is +located under the directory \fIdirpath\fP, +and calls \fIfn\fP() once for each entry in the tree. +By default, directories are handled before the files and +subdirectories they contain (preorder traversal). +.PP +To avoid using up all of the calling process's file descriptors, +\fInopenfd\fP specifies the maximum number of directories that +.BR nftw () +will hold open simultaneously. +When +the search depth exceeds this, +.BR nftw () +will become slower because +directories have to be closed and reopened. +.BR nftw () +uses at most +one file descriptor for each level in the directory tree. +.PP +For each entry found in the tree, +.BR nftw () +calls +\fIfn\fP() with four arguments: +.IR fpath , +.IR sb , +.IR typeflag , +and +.IR ftwbuf . +.I fpath +is the pathname of the entry, +and is expressed either as a pathname relative to the calling process's +current working directory at the time of the call to +.BR nftw (), +if +.IR dirpath +was expressed as a relative pathname, +or as an absolute pathname, if +.I dirpath +was expressed as an absolute pathname. +.I sb +is a pointer to the +.I stat +structure returned by a call to +.BR stat (2) +for +.IR fpath . +.PP +The +.I typeflag +argument passed to +.IR fn () +is an integer that has one of the following values: +.TP +.B FTW_F +.I fpath +is a regular file. +.TP +.B FTW_D +.I fpath +is a directory. +.TP +.B FTW_DNR +.I fpath +is a directory which can't be read. +.TP +.B FTW_DP +.I fpath +is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP. +(If +.B FTW_DEPTH +was not specified in +.IR flags , +then directories will always be visited with +.I typeflag +set to +.BR FTW_D .) +All of the files +and subdirectories within \fIfpath\fP have been processed. +.TP +.B FTW_NS +The +.BR stat (2) +call failed on +.IR fpath , +which is not a symbolic link. +The probable cause for this is that the caller had read permission +on the parent directory, so that the filename +.I fpath +could be seen, +but did not have execute permission, +so that the file could not be reached for +.BR stat (2). +The contents of the buffer pointed to by +.I sb +are undefined. +.TP +.B FTW_SL +.I fpath +is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP. +.\" To obtain the definition of this constant from +.\" .IR , +.\" either +.\" .B _BSD_SOURCE +.\" must be defined, or +.\" .BR _XOPEN_SOURCE +.\" must be defined with a value of 500 or more. +.TP +.B FTW_SLN +.I fpath +is a symbolic link pointing to a nonexistent file. +(This occurs only if \fBFTW_PHYS\fP is not set.) +On most implementations, in this case the +.I sb +argument passed to +.IR fn () +contains information returned by performing +.BR lstat (2) +on the symbolic link. +For the details on Linux, see BUGS. +.PP +The fourth argument +.RI ( ftwbuf ) +that +.BR nftw () +supplies when calling +\fIfn\fP() +is a pointer to a structure of type \fIFTW\fP: +.PP +.in +4n +.EX +struct FTW { + int base; + int level; +}; +.EE +.in +.PP +.I base +is the offset of the filename (i.e., basename component) +in the pathname given in +.IR fpath . +.I level +is the depth of +.I fpath +in the directory tree, relative to the root of the tree +.RI ( dirpath , +which has depth 0). +.PP +To stop the tree walk, \fIfn\fP() returns a nonzero value; this +value will become the return value of +.BR nftw (). +As long as \fIfn\fP() returns 0, +.BR nftw () +will continue either until it has traversed the entire tree, +in which case it will return zero, +or until it encounters an error (such as a +.BR malloc (3) +failure), in which case it will return \-1. +.PP +Because +.BR nftw () +uses dynamic data structures, the only safe way to +exit out of a tree walk is to return a nonzero value from \fIfn\fP(). +To allow a signal to terminate the walk without causing a memory leak, +have the handler set a global flag that is checked by \fIfn\fP(). +\fIDon't\fP use +.BR longjmp (3) +unless the program is going to terminate. +.PP +The \fIflags\fP argument of +.BR nftw () +is formed by ORing zero or more of the +following flags: +.TP +.BR FTW_ACTIONRETVAL " (since glibc 2.3.3)" +If this glibc-specific flag is set, then +.BR nftw () +handles the return value from +.IR fn () +differently. +.IR fn () +should return one of the following values: +.RS +.TP +.B FTW_CONTINUE +Instructs +.BR nftw () +to continue normally. +.TP +.B FTW_SKIP_SIBLINGS +If \fIfn\fP() returns this value, then +siblings of the current entry will be skipped, +and processing continues in the parent. +.\" If \fBFTW_DEPTH\fP +.\" is set, the entry's parent directory is processed next (with +.\" \fIflag\fP set to \fBFTW_DP\fP). +.TP +.B FTW_SKIP_SUBTREE +If \fIfn\fP() is called with an entry that is a directory +(\fItypeflag\fP is \fBFTW_D\fP), this return +value will prevent objects within that directory from being passed as +arguments to \fIfn\fP(). +.BR nftw () +continues processing with the next sibling of the directory. +.TP +.B FTW_STOP +Causes +.BR nftw () +to return immediately with the return value +\fBFTW_STOP\fP. +.PP +Other return values could be associated with new actions in the future; +\fIfn\fP() should not return values other than those listed above. +.PP +The feature test macro +.B _GNU_SOURCE +must be defined +(before including +.I any +header files) +in order to +obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI\fP. +.RE +.TP +.B FTW_CHDIR +If set, do a +.BR chdir (2) +to each directory before handling its contents. +This is useful if the program needs to perform some action +in the directory in which \fIfpath\fP resides. +(Specifying this flag has no effect on the pathname that is passed in the +.I fpath +argument of +.IR fn .) +.TP +.B FTW_DEPTH +If set, do a post-order traversal, that is, call \fIfn\fP() for +the directory itself \fIafter\fP handling the contents of the directory +and its subdirectories. +(By default, each directory is handled \fIbefore\fP its contents.) +.TP +.B FTW_MOUNT +If set, stay within the same filesystem +(i.e., do not cross mount points). +.TP +.B FTW_PHYS +If set, do not follow symbolic links. +(This is what you want.) +If not set, symbolic links are followed, but no file is reported twice. +.IP +If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, +then the function +.IR fn () +is never called for a directory that would be a descendant of itself. +.SS ftw() +.BR ftw () +is an older function that offers a subset of the functionality of +.BR nftw (). +The notable differences are as follows: +.IP * 3 +.BR ftw () +has no +.IR flags +argument. +It behaves the same as when +.BR nftw () +is called with +.I flags +specified as zero. +.IP * +The callback function, +.IR fn (), +is not supplied with a fourth argument. +.IP * +The range of values that is passed via the +.I typeflag +argument supplied to +.IR fn () +is smaller: just +.BR FTW_F , +.BR FTW_D , +.BR FTW_DNR , +.BR FTW_NS , +and (possibly) +.BR FTW_SL . +.SH RETURN VALUE +These functions return 0 on success, and \-1 if an error occurs. +.PP +If \fIfn\fP() returns nonzero, +then the tree walk is terminated and the value returned by \fIfn\fP() +is returned as the result of +.BR ftw () +or +.BR nftw (). +.PP +If +.BR nftw () +is called with the \fBFTW_ACTIONRETVAL\fP flag, +then the only nonzero value that should be used by \fIfn\fP() +to terminate the tree walk is \fBFTW_STOP\fP, +and that value is returned as the result of +.BR nftw (). +.SH VERSIONS +.BR nftw () +is available under glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR nftw () +T} Thread safety MT-Safe cwd +T{ +.BR ftw () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, SUSv1. +POSIX.1-2008 marks +.BR ftw () +as obsolete. +.SH NOTES +POSIX.1-2008 notes that the results are unspecified if +.I fn +does not preserve the current working directory. +.PP +The function +.BR nftw () +and the use of \fBFTW_SL\fP with +.BR ftw () +were introduced in SUSv1. +.PP +In some implementations (e.g., glibc), +.BR ftw () +will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only +for symbolic links that do not point to an existing file, +and again on other systems +.BR ftw () +will use \fBFTW_SL\fP for each symbolic link. +If +.I fpath +is a symbolic link and +.BR stat (2) +failed, POSIX.1-2008 states +that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP +is passed in +.IR typeflag . +For predictable results, use +.BR nftw (). +.SH BUGS +In the specification of +.BR nftw (), +POSIX.1 notes that when +.B FTW_NS +is passed as the +.I typeflag +argument of +.IR fn (), +then the contents of the buffer pointed to by the +.I sb +argument are undefined. +The standard makes no such statement for the case where +.B FTW_SLN +is passed in +.IR typeflag , +with the implication that the contents of the buffer pointed to by +.I sb +are defined. +And indeed this is the case on most implementations: the buffer pointed to by +.I sb +contains the results produced by applying +.BR lstat (2) +to the symbolic link. +In early glibc, the behavior was the same. +However, since glibc 2.4, the contents of the buffer pointed to by +.I sb +are undefined when +.B FTW_SLN +is passed in +.IR typeflag . +This change +.I appears +to be an unintended regression, +but it is not (yet) clear if the behavior will be restored to that +provided in the original glibc implementation (and on other implementations). +.\" FIXME . +.\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736 +.\" http://austingroupbugs.net/view.php?id=1121 +.SH EXAMPLE +The following program traverses the directory tree under the path named +in its first command-line argument, or under the current directory +if no argument is supplied. +It displays various information about each file. +The second command-line argument can be used to specify characters that +control the value assigned to the \fIflags\fP +argument when calling +.BR nftw (). +.SS Program source +\& +.EX +#define _XOPEN_SOURCE 500 +#include +#include +#include +#include +#include + +static int +display_info(const char *fpath, const struct stat *sb, + int tflag, struct FTW *ftwbuf) +{ + printf("%\-3s %2d ", + (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : + (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" : + (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : + (tflag == FTW_SLN) ? "sln" : "???", + ftwbuf\->level); + + if (tflag == FTW_NS) + printf("\-\-\-\-\-\-\-"); + else + printf("%7jd", (intmax_t) sb\->st_size); + + printf(" %\-40s %d %s\\n", + fpath, ftwbuf\->base, fpath + ftwbuf\->base); + + return 0; /* To tell nftw() to continue */ +} + +int +main(int argc, char *argv[]) +{ + int flags = 0; + + if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL) + flags |= FTW_DEPTH; + if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL) + flags |= FTW_PHYS; + + if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) + == \-1) { + perror("nftw"); + exit(EXIT_FAILURE); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR stat (2), +.BR fts (3), +.BR readdir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/funlockfile.3 b/man3/funlockfile.3 new file mode 100644 index 0000000..b33c2ee --- /dev/null +++ b/man3/funlockfile.3 @@ -0,0 +1 @@ +.so man3/flockfile.3 diff --git a/man3/futimens.3 b/man3/futimens.3 new file mode 100644 index 0000000..a365c7b --- /dev/null +++ b/man3/futimens.3 @@ -0,0 +1 @@ +.so man2/utimensat.2 diff --git a/man3/futimes.3 b/man3/futimes.3 new file mode 100644 index 0000000..6a7bce2 --- /dev/null +++ b/man3/futimes.3 @@ -0,0 +1,124 @@ +.\" Copyright (c) 2006, 2008, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FUTIMES 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +futimes, lutimes \- change file timestamps +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int futimes(int " fd ", const struct timeval " tv [2]); +.PP +.BI "int lutimes(const char *" filename ", const struct timeval " tv [2]); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR futimes (), +.BR lutimes (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +.BR futimes () +changes the access and modification times of a file in the same way as +.BR utimes (2), +with the difference that the file whose timestamps are to be changed +is specified via a file descriptor, +.IR fd , +rather than via a pathname. +.PP +.BR lutimes () +changes the access and modification times of a file in the same way as +.BR utimes (2), +with the difference that if +.I filename +refers to a symbolic link, then the link is not dereferenced: +instead, the timestamps of the symbolic link are changed. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +Errors are as for +.BR utimes (2), +with the following additions for +.BR futimes (): +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOSYS +The +.I /proc +filesystem could not be accessed. +.PP +The following additional error may occur for +.BR lutimes (): +.TP +.B ENOSYS +The kernel does not support this call; Linux 2.6.22 or later is required. +.SH VERSIONS +.BR futimes () +is available since glibc 2.3. +.BR lutimes () +is available since glibc 2.6, and is implemented using the +.BR utimensat (2) +system call, which is supported since kernel 2.6.22. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR futimes (), +.BR lutimes () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are not specified in any standard. +Other than Linux, they are available only on the BSDs. +.SH SEE ALSO +.BR utime (2), +.BR utimensat (2), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fwide.3 b/man3/fwide.3 new file mode 100644 index 0000000..8046e20 --- /dev/null +++ b/man3/fwide.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH FWIDE 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +fwide \- set and determine the orientation of a FILE stream +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fwide(FILE *" stream ", int " mode ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.PP +.BR fwide (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE || +.br +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +When \fImode\fP is zero, the +.BR fwide () +function determines the current +orientation of \fIstream\fP. +It returns a positive value if \fIstream\fP is +wide-character oriented, that is, if wide-character I/O is permitted but char +I/O is disallowed. +It returns a negative value if \fIstream\fP is byte oriented\(emthat is, +if char I/O is permitted but wide-character I/O is disallowed. +It +returns zero if \fIstream\fP has no orientation yet; in this case the next +I/O operation might change the orientation (to byte oriented if it is a char +I/O operation, or to wide-character oriented if it is a wide-character I/O +operation). +.PP +Once a stream has an orientation, it cannot be changed and persists until +the stream is closed. +.PP +When \fImode\fP is nonzero, the +.BR fwide () +function first attempts to set +\fIstream\fP's orientation (to wide-character oriented +if \fImode\fP is greater than 0, or +to byte oriented if \fImode\fP is less than 0). +It then returns a value denoting the +current orientation, as above. +.SH RETURN VALUE +The +.BR fwide () +function returns the stream's orientation, after possibly +changing it. +A positive return value means wide-character oriented. +A negative return value means byte oriented. +A return value of zero means undecided. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +Wide-character output to a byte oriented stream can be performed through the +.BR fprintf (3) +function with the +.B %lc +and +.B %ls +directives. +.PP +Char oriented output to a wide-character oriented stream can be performed +through the +.BR fwprintf (3) +function with the +.B %c +and +.B %s +directives. +.SH SEE ALSO +.BR fprintf (3), +.BR fwprintf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/fwprintf.3 b/man3/fwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man3/fwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/fwrite.3 b/man3/fwrite.3 new file mode 100644 index 0000000..86906ed --- /dev/null +++ b/man3/fwrite.3 @@ -0,0 +1 @@ +.so man3/fread.3 diff --git a/man3/fwrite_unlocked.3 b/man3/fwrite_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/fwrite_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/gai_cancel.3 b/man3/gai_cancel.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man3/gai_cancel.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man3/gai_error.3 b/man3/gai_error.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man3/gai_error.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man3/gai_strerror.3 b/man3/gai_strerror.3 new file mode 100644 index 0000000..17f7236 --- /dev/null +++ b/man3/gai_strerror.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo.3 diff --git a/man3/gai_suspend.3 b/man3/gai_suspend.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man3/gai_suspend.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man3/gamma.3 b/man3/gamma.3 new file mode 100644 index 0000000..5de3a8c --- /dev/null +++ b/man3/gamma.3 @@ -0,0 +1,127 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Modified 2003-11-18, aeb: historical remarks +.\" +.TH GAMMA 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +gamma, gammaf, gammal \- (logarithm of the) gamma function +.SH SYNOPSIS +.B #include +.PP +.BI "double gamma(double " x ");" +.br +.BI "float gammaf(float " x ");" +.br +.BI "long double gammal(long double " x ");" +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR gamma (): +.RS 4 +_XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.BR gammaf (), +.BR gammal (): +.RS 4 +_XOPEN_SOURCE >= 600 || (_XOPEN_SOURCE && _ISOC99_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions are deprecated: instead, use either the +.BR tgamma (3) +or the +.BR lgamma (3) +functions, as appropriate. +.PP +For the definition of the Gamma function, see +.BR tgamma (3). +.SS *BSD version +The libm in 4.4BSD and some versions of FreeBSD had a +.BR gamma () +function that computes the Gamma function, as one would expect. +.SS glibc version +Glibc has a +.BR gamma () +function that is equivalent to +.BR lgamma (3) +and computes the natural logarithm of the Gamma function. +.SH RETURN VALUE +See +.BR lgamma (3). +.SH ERRORS +See +.BR lgamma (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR gamma (), +.BR gammaf (), +.BR gammal () +T} Thread safety MT-Unsafe race:signgam +.TE +.SH CONFORMING TO +Because of historical variations in behavior across systems, +this function is not specified in any recent standard. +It was documented in SVID 2. +.SH NOTES +.SS History +4.2BSD had a +.BR gamma () +that computed +.RI ln(|Gamma(| x |)|), +leaving the sign of +.RI Gamma(| x |) +in the external integer +.IR signgam . +In 4.3BSD the name was changed to +.BR lgamma (3), +and the man page promises +.PP +.in +4n +"At some time in the future the name gamma will be rehabilitated +and used for the Gamma function" +.in +.PP +This did indeed happen in 4.4BSD, where +.BR gamma () +computes the Gamma function (with no effect on +.IR signgam ). +However, this came too late, and we now have +.BR tgamma (3), +the "true gamma" function. +.\" The FreeBSD man page says about gamma() that it is like lgamma() +.\" except that is does not set signgam. +.\" Also, that 4.4BSD has a gamma() that computes the true gamma function. +.SH SEE ALSO +.BR lgamma (3), +.BR signgam (3), +.BR tgamma (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/gammaf.3 b/man3/gammaf.3 new file mode 100644 index 0000000..64ab6ee --- /dev/null +++ b/man3/gammaf.3 @@ -0,0 +1 @@ +.so man3/gamma.3 diff --git a/man3/gammal.3 b/man3/gammal.3 new file mode 100644 index 0000000..64ab6ee --- /dev/null +++ b/man3/gammal.3 @@ -0,0 +1 @@ +.so man3/gamma.3 diff --git a/man3/gcvt.3 b/man3/gcvt.3 new file mode 100644 index 0000000..d5a613a --- /dev/null +++ b/man3/gcvt.3 @@ -0,0 +1,110 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:32:25 1993 by Rik Faith (faith@cs.unc.edu) +.TH GCVT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +gcvt \- convert a floating-point number to a string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *gcvt(double " number ", int " ndigit ", char *" buf ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR gcvt (): +.ad l +.PD 0 +.RS 4 +.TP 4 +Since glibc 2.12: +.nf +(_XOPEN_SOURCE\ >=\ 500) ! (_POSIX_C_SOURCE\ >=\ 200112L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.fi +.TP 4 +Before glibc 2.12: +_SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.RE +.PD +.ad b +.SH DESCRIPTION +The +.BR gcvt () +function converts \fInumber\fP to a minimal length null-terminated +ASCII string and stores the result in \fIbuf\fP. +It produces \fIndigit\fP significant digits in either +.BR printf (3) +F format or E format. +.SH RETURN VALUE +The +.BR gcvt () +function returns the address of the string pointed to +by \fIbuf\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR gcvt () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +Marked as LEGACY in POSIX.1-2001. +POSIX.1-2008 removes the specification of +.BR gcvt (), +recommending the use of +.BR sprintf (3) +instead (though +.BR snprintf (3) +may be preferable). +.SH SEE ALSO +.BR ecvt (3), +.BR fcvt (3), +.BR sprintf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/get_avphys_pages.3 b/man3/get_avphys_pages.3 new file mode 100644 index 0000000..cbd22cc --- /dev/null +++ b/man3/get_avphys_pages.3 @@ -0,0 +1 @@ +.so man3/get_phys_pages.3 diff --git a/man3/get_current_dir_name.3 b/man3/get_current_dir_name.3 new file mode 100644 index 0000000..f73c157 --- /dev/null +++ b/man3/get_current_dir_name.3 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man3/get_myaddress.3 b/man3/get_myaddress.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/get_myaddress.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/get_nprocs.3 b/man3/get_nprocs.3 new file mode 100644 index 0000000..63c03ba --- /dev/null +++ b/man3/get_nprocs.3 @@ -0,0 +1 @@ +.so man3/get_nprocs_conf.3 diff --git a/man3/get_nprocs_conf.3 b/man3/get_nprocs_conf.3 new file mode 100644 index 0000000..4774f9e --- /dev/null +++ b/man3/get_nprocs_conf.3 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2012, Petr Benas +.\" and Copyright (c) 2012, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume +.\" no responsibility for errors or omissions, or for damages resulting +.\" from the use of the information contained herein. The author(s) may +.\" not have taken the same level of care in the production of this +.\" manual, which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GET_NPROCS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +get_nprocs, get_nprocs_conf \- get number of processors +.SH SYNOPSIS +.B #include +.PP +.BI "int get_nprocs(void);" +.br +.BI "int get_nprocs_conf(void);" +.SH DESCRIPTION +The function +.BR get_nprocs_conf () +returns the number of processors configured by the operating system. +.PP +The function +.BR get_nprocs () +returns the number of processors currently available in the system. +This may be less than the number returned by +.BR get_nprocs_conf () +because processors may be offline (e.g., on hotpluggable systems). +.SH RETURN VALUE +As given in DESCRIPTION. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR get_nprocs (), +.br +.BR get_nprocs_conf () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +The current +.\" glibc 2.15 +implementation of these functions is rather expensive, +since they open and parse files in the +.I /sys +filesystem each time they are called. +.PP +The following +.BR sysconf (3) +calls make use of the functions documented on this page +to return the same information. +.PP +.in +4n +.EX +np = sysconf(_SC_NPROCESSORS_CONF); /* processors configured */ +np = sysconf(_SC_NPROCESSORS_ONLN); /* processors available */ +.EE +.in +.SH EXAMPLE +The following example shows how +.BR get_nprocs () +and +.BR get_nprocs_conf () +can be used. +.PP +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + printf("This system has %d processors configured and " + "%d processors available.\\n", + get_nprocs_conf(), get_nprocs()); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR nproc (1) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/get_phys_pages.3 b/man3/get_phys_pages.3 new file mode 100644 index 0000000..6ab58ab --- /dev/null +++ b/man3/get_phys_pages.3 @@ -0,0 +1,110 @@ +.\" Copyright (c) 2015 William Woodruff (william@tuffbizz.com) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GET_PHYS_PAGES 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +get_phys_pages, get_avphys_pages \- get total and available physical +page counts +.SH SYNOPSIS +.nf +.B "#include " +.PP +.B long int get_phys_pages(void); +.B long int get_avphys_pages(void); +.fi +.SH DESCRIPTION +The function +.BR get_phys_pages () +returns the total number of physical pages of memory available on the system. +.PP +The function +.BR get_avphys_pages () +returns the number of currently available physical pages of memory on the +system. +.SH RETURN VALUE +On success, +these functions return a nonnegative value as given in DESCRIPTION. +On failure, they return \-1 and set +.I errno +to indicate the cause of the error. +.SH ERRORS +.TP +.B ENOSYS +The system could not provide the required information +(possibly because the +.I /proc +filesystem was not mounted). +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +These functions obtain the required information by scanning the +.I MemTotal +and +.I MemFree +fields of +.IR /proc/meminfo . +.PP +The following +.BR sysconf (3) +calls provide a portable means of obtaining the same information as the +functions described on this page. +.PP +.in +4n +.EX +total_pages = sysconf(_SC_PHYS_PAGES); /* total pages */ +avl_pages = sysconf(_SC_AVPHYS_PAGES); /* available pages */ +.EE +.in +.SH EXAMPLE +The following example shows how +.BR get_phys_pages () +and +.BR get_avphys_pages () +can be used. +.PP +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + printf("This system has %ld pages of physical memory and " + "%ld pages of physical memory available.\\n", + get_phys_pages(), get_avphys_pages()); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR sysconf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getaddrinfo.3 b/man3/getaddrinfo.3 new file mode 100644 index 0000000..ef741d4 --- /dev/null +++ b/man3/getaddrinfo.3 @@ -0,0 +1,863 @@ +.\" Copyright (c) 2007, 2008 Michael Kerrisk +.\" and Copyright (c) 2006 Ulrich Drepper +.\" A few pieces of an earlier version remain: +.\" Copyright 2000, Sam Varshavchik +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References: RFC 2553 +.\" +.\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED, +.\" and AI_NUMERICSERV. +.\" 2006-11-25, Ulrich Drepper +.\" Add text describing Internationalized Domain Name extensions. +.\" 2007-06-08, mtk: added example programs +.\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other +.\" minor rewrites. +.\" 2008-06-18, mtk: many parts rewritten +.\" 2008-12-04, Petr Baudis +.\" Describe results ordering and reference /etc/gai.conf. +.\" +.\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support +.\" and is SCTP support now also there? +.\" +.TH GETADDRINFO 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getaddrinfo, freeaddrinfo, gai_strerror \- network address and +service translation +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int getaddrinfo(const char *" "node" ", const char *" "service" , +.BI " const struct addrinfo *" "hints" , +.BI " struct addrinfo **" "res" ); +.PP +.BI "void freeaddrinfo(struct addrinfo *" "res" ); +.PP +.BI "const char *gai_strerror(int " "errcode" ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getaddrinfo (), +.BR freeaddrinfo (), +.BR gai_strerror (): + Since glibc 2.22: _POSIX_C_SOURCE >= 200112L + Glibc 2.21 and earlier: _POSIX_C_SOURCE +.ad b +.SH DESCRIPTION +Given +.I node +and +.IR service , +which identify an Internet host and a service, +.BR getaddrinfo () +returns one or more +.I addrinfo +structures, each of which contains an Internet address +that can be specified in a call to +.BR bind (2) +or +.BR connect (2). +The +.BR getaddrinfo () +function combines the functionality provided by the +.\" .BR getipnodebyname (3), +.\" .BR getipnodebyaddr (3), +.BR gethostbyname (3) +and +.BR getservbyname (3) +functions into a single interface, but unlike the latter functions, +.BR getaddrinfo () +is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies. +.PP +The +.I addrinfo +structure used by +.BR getaddrinfo () +contains the following fields: +.PP +.in +4n +.EX +struct addrinfo { + int ai_flags; + int ai_family; + int ai_socktype; + int ai_protocol; + socklen_t ai_addrlen; + struct sockaddr *ai_addr; + char *ai_canonname; + struct addrinfo *ai_next; +}; +.EE +.in +.PP +The +.I hints +argument points to an +.I addrinfo +structure that specifies criteria for selecting the socket address +structures returned in the list pointed to by +.IR res . +If +.I hints +is not NULL it points to an +.I addrinfo +structure whose +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +specify criteria that limit the set of socket addresses returned by +.BR getaddrinfo (), +as follows: +.TP 12 +.I ai_family +This field specifies the desired address family for the returned addresses. +Valid values for this field include +.BR AF_INET +and +.BR AF_INET6 . +The value +.B AF_UNSPEC +indicates that +.BR getaddrinfo () +should return socket addresses for any address family +(either IPv4 or IPv6, for example) that can be used with +.I node +and +.IR service . +.TP +.I ai_socktype +This field specifies the preferred socket type, for example +.BR SOCK_STREAM +or +.BR SOCK_DGRAM . +Specifying 0 in this field indicates that socket addresses of any type +can be returned by +.BR getaddrinfo (). +.TP +.I ai_protocol +This field specifies the protocol for the returned socket addresses. +Specifying 0 in this field indicates that socket addresses with +any protocol can be returned by +.BR getaddrinfo (). +.TP +.I ai_flags +This field specifies additional options, described below. +Multiple flags are specified by bitwise OR-ing them together. +.PP +All the other fields in the structure pointed to by +.I hints +must contain either 0 or a null pointer, as appropriate. +.PP +Specifying +.I hints +as NULL is equivalent to setting +.I ai_socktype +and +.I ai_protocol +to 0; +.I ai_family +to +.BR AF_UNSPEC ; +and +.I ai_flags +to +.BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" . +(POSIX specifies different defaults for +.IR ai_flags ; +see NOTES.) +.I node +specifies either a numerical network address +(for IPv4, numbers-and-dots notation as supported by +.BR inet_aton (3); +for IPv6, hexadecimal string format as supported by +.BR inet_pton (3)), +or a network hostname, whose network addresses are looked up and resolved. +If +.I hints.ai_flags +contains the +.B AI_NUMERICHOST +flag, then +.I node +must be a numerical network address. +The +.B AI_NUMERICHOST +flag suppresses any potentially lengthy network host address lookups. +.PP +If the +.B AI_PASSIVE +flag is specified in +.IR hints.ai_flags , +and +.I node +is NULL, +then the returned socket addresses will be suitable for +.BR bind (2)ing +a socket that will +.BR accept (2) +connections. +The returned socket address will contain the "wildcard address" +.RB ( INADDR_ANY +for IPv4 addresses, +.BR IN6ADDR_ANY_INIT +for IPv6 address). +The wildcard address is used by applications (typically servers) +that intend to accept connections on any of the host's network addresses. +If +.I node +is not NULL, then the +.B AI_PASSIVE +flag is ignored. +.PP +If the +.B AI_PASSIVE +flag is not set in +.IR hints.ai_flags , +then the returned socket addresses will be suitable for use with +.BR connect (2), +.BR sendto (2), +or +.BR sendmsg (2). +If +.I node +is NULL, +then the network address will be set to the loopback interface address +.RB ( INADDR_LOOPBACK +for IPv4 addresses, +.BR IN6ADDR_LOOPBACK_INIT +for IPv6 address); +this is used by applications that intend to communicate +with peers running on the same host. +.PP +.I service +sets the port in each returned address structure. +If this argument is a service name (see +.BR services (5)), +it is translated to the corresponding port number. +This argument can also be specified as a decimal number, +which is simply converted to binary. +If +.I service +is NULL, then the port number of the returned socket addresses +will be left uninitialized. +If +.B AI_NUMERICSERV +is specified in +.I hints.ai_flags +and +.I service +is not NULL, then +.I service +must point to a string containing a numeric port number. +This flag is used to inhibit the invocation of a name resolution service +in cases where it is known not to be required. +.PP +Either +.I node +or +.IR service , +but not both, may be NULL. +.PP +The +.BR getaddrinfo () +function allocates and initializes a linked list of +.I addrinfo +structures, one for each network address that matches +.I node +and +.IR service , +subject to any restrictions imposed by +.IR hints , +and returns a pointer to the start of the list in +.IR res . +The items in the linked list are linked by the +.I ai_next +field. +.PP +There are several reasons why +the linked list may have more than one +.I addrinfo +structure, including: the network host is multihomed, accessible +over multiple protocols (e.g., both +.BR AF_INET +and +.BR AF_INET6 ); +or the same service is available from multiple socket types (one +.B SOCK_STREAM +address and another +.B SOCK_DGRAM +address, for example). +Normally, the application should try +using the addresses in the order in which they are returned. +The sorting function used within +.BR getaddrinfo () +is defined in RFC\ 3484; the order can be tweaked for a particular +system by editing +.IR /etc/gai.conf +(available since glibc 2.5). +.PP +If +.I hints.ai_flags +includes the +.B AI_CANONNAME +flag, then the +.I ai_canonname +field of the first of the +.I addrinfo +structures in the returned list is set to point to the +official name of the host. +.\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo +.\" structure was set pointing to the canonical name; that was +.\" more than POSIX.1-2001 specified, or other implementations provided. +.\" MTK, Aug 05 +.PP +The remaining fields of each returned +.I addrinfo +structure are initialized as follows: +.IP * 2 +The +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +fields return the socket creation parameters (i.e., these fields have +the same meaning as the corresponding arguments of +.BR socket (2)). +For example, +.I ai_family +might return +.B AF_INET +or +.BR AF_INET6 ; +.I ai_socktype +might return +.B SOCK_DGRAM +or +.BR SOCK_STREAM ; +and +.I ai_protocol +returns the protocol for the socket. +.IP * +A pointer to the socket address is placed in the +.I ai_addr +field, and the length of the socket address, in bytes, +is placed in the +.I ai_addrlen +field. +.PP +If +.I hints.ai_flags +includes the +.B AI_ADDRCONFIG +flag, then IPv4 addresses are returned in the list pointed to by +.I res +only if the local system has at least one +IPv4 address configured, and IPv6 addresses are returned +only if the local system has at least one IPv6 address configured. +The loopback address is not considered for this case as valid +as a configured address. +This flag is useful on, for example, +IPv4-only systems, to ensure that +.BR getaddrinfo () +does not return IPv6 socket addresses that would always fail in +.BR connect (2) +or +.BR bind (2). +.PP +If +.I hints.ai_flags +specifies the +.B AI_V4MAPPED +flag, and +.I hints.ai_family +was specified as +.BR AF_INET6 , +and no matching IPv6 addresses could be found, +then return IPv4-mapped IPv6 addresses in the list pointed to by +.IR res . +If both +.B AI_V4MAPPED +and +.B AI_ALL +are specified in +.IR hints.ai_flags , +then return both IPv6 and IPv4-mapped IPv6 addresses +in the list pointed to by +.IR res . +.B AI_ALL +is ignored if +.B AI_V4MAPPED +is not also specified. +.PP +The +.BR freeaddrinfo () +function frees the memory that was allocated +for the dynamically allocated linked list +.IR res . +.SS Extensions to getaddrinfo() for Internationalized Domain Names +.PP +Starting with glibc 2.3.4, +.BR getaddrinfo () +has been extended to selectively allow the incoming and outgoing +hostnames to be transparently converted to and from the +Internationalized Domain Name (IDN) format (see RFC 3490, +.IR "Internationalizing Domain Names in Applications (IDNA)" ). +Four new flags are defined: +.TP +.B AI_IDN +If this flag is specified, then the node name given in +.I node +is converted to IDN format if necessary. +The source encoding is that of the current locale. +.IP +If the input name contains non-ASCII characters, then the IDN encoding +is used. +Those parts of the node name (delimited by dots) that contain +non-ASCII characters are encoded using ASCII Compatible Encoding (ACE) +before being passed to the name resolution functions. +.\" Implementation Detail: +.\" To minimize effects on system performance the implementation might +.\" want to check whether the input string contains any non-ASCII +.\" characters. If there are none the IDN step can be skipped completely. +.\" On systems which allow not-ASCII safe encodings for a locale this +.\" might be a problem. +.TP +.B AI_CANONIDN +After a successful name lookup, and if the +.B AI_CANONNAME +flag was specified, +.BR getaddrinfo () +will return the canonical name of the +node corresponding to the +.I addrinfo +structure value passed back. +The return value is an exact copy of the value returned by the name +resolution function. +.IP +If the name is encoded using ACE, then it will contain the +.I xn\-\- +prefix for one or more components of the name. +To convert these components into a readable form the +.B AI_CANONIDN +flag can be passed in addition to +.BR AI_CANONNAME . +The resulting string is encoded using the current locale's encoding. +.\" +.\"Implementation Detail: +.\"If no component of the returned name starts with xn\-\- the IDN +.\"step can be skipped, therefore avoiding unnecessary slowdowns. +.TP +.BR AI_IDN_ALLOW_UNASSIGNED ", " AI_IDN_USE_STD3_ASCII_RULES +Setting these flags will enable the +IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and +IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 +conforming hostname) +flags respectively to be used in the IDNA handling. +.SH RETURN VALUE +.\" FIXME glibc defines the following additional errors, some which +.\" can probably be returned by getaddrinfo(); they need to +.\" be documented. +.\" #ifdef __USE_GNU +.\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ +.\" #define EAI_CANCELED -101 /* Request canceled. */ +.\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ +.\" #define EAI_ALLDONE -103 /* All requests done. */ +.\" #define EAI_INTR -104 /* Interrupted by a signal. */ +.\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ +.\" #endif +.BR getaddrinfo () +returns 0 if it succeeds, or one of the following nonzero error codes: +.TP +.B EAI_ADDRFAMILY +.\" Not in SUSv3 +The specified network host does not have any network addresses in the +requested address family. +.TP +.B EAI_AGAIN +The name server returned a temporary failure indication. +Try again later. +.TP +.B EAI_BADFLAGS +.I hints.ai_flags +contains invalid flags; or, +.I hints.ai_flags +included +.B AI_CANONNAME +and +.I name +was NULL. +.TP +.B EAI_FAIL +The name server returned a permanent failure indication. +.TP +.B EAI_FAMILY +The requested address family is not supported. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_NODATA +.\" Not in SUSv3 +The specified network host exists, but does not have any +network addresses defined. +.TP +.B EAI_NONAME +The +.I node +or +.I service +is not known; or both +.I node +and +.I service +are NULL; or +.B AI_NUMERICSERV +was specified in +.I hints.ai_flags +and +.I service +was not a numeric port-number string. +.TP +.B EAI_SERVICE +The requested service is not available for the requested socket type. +It may be available through another socket type. +For example, this error could occur if +.I service +was "shell" (a service available only on stream sockets), and either +.I hints.ai_protocol +was +.BR IPPROTO_UDP , +or +.I hints.ai_socktype +was +.BR SOCK_DGRAM ; +or the error could occur if +.I service +was not NULL, and +.I hints.ai_socktype +was +.BR SOCK_RAW +(a socket type that does not support the concept of services). +.TP +.B EAI_SOCKTYPE +The requested socket type is not supported. +This could occur, for example, if +.I hints.ai_socktype +and +.I hints.ai_protocol +are inconsistent (e.g., +.BR SOCK_DGRAM +and +.BR IPPROTO_TCP , +respectively). +.TP +.B EAI_SYSTEM +Other system error, check +.I errno +for details. +.PP +The +.BR gai_strerror () +function translates these error codes to a human readable string, +suitable for error reporting. +.SH FILES +.I /etc/gai.conf +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw15 lb lb +l l l. +Interface Attribute Value +T{ +.BR getaddrinfo () +T} Thread safety MT-Safe env locale +T{ +.BR freeaddrinfo (), +.BR gai_strerror () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +The +.BR getaddrinfo () +function is documented in RFC\ 2553. +.SH NOTES +.BR getaddrinfo () +supports the +.IB address % scope-id +notation for specifying the IPv6 scope-ID. +.PP +.BR AI_ADDRCONFIG , +.BR AI_ALL , +and +.B AI_V4MAPPED +are available since glibc 2.3.3. +.B AI_NUMERICSERV +is available since glibc 2.3.4. +.PP +According to POSIX.1, specifying +.\" POSIX.1-2001, POSIX.1-2008 +.I hints +as NULL should cause +.I ai_flags +to be assumed as 0. +The GNU C library instead assumes a value of +.BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" +for this case, +since this value is considered an improvement on the specification. +.SH EXAMPLE +.\" getnameinfo.3 refers to this example +.\" socket.2 refers to this example +.\" bind.2 refers to this example +.\" connect.2 refers to this example +.\" recvfrom.2 refers to this example +.\" sendto.2 refers to this example +The following programs demonstrate the use of +.BR getaddrinfo (), +.BR gai_strerror (), +.BR freeaddrinfo (), +and +.BR getnameinfo (3). +The programs are an echo server and client for UDP datagrams. +.SS Server program +\& +.EX +#include +#include +#include +#include +#include +#include +#include + +#define BUF_SIZE 500 + +int +main(int argc, char *argv[]) +{ + struct addrinfo hints; + struct addrinfo *result, *rp; + int sfd, s; + struct sockaddr_storage peer_addr; + socklen_t peer_addr_len; + ssize_t nread; + char buf[BUF_SIZE]; + + if (argc != 2) { + fprintf(stderr, "Usage: %s port\\n", argv[0]); + exit(EXIT_FAILURE); + } + + memset(&hints, 0, sizeof(struct addrinfo)); + hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */ + hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */ + hints.ai_flags = AI_PASSIVE; /* For wildcard IP address */ + hints.ai_protocol = 0; /* Any protocol */ + hints.ai_canonname = NULL; + hints.ai_addr = NULL; + hints.ai_next = NULL; + + s = getaddrinfo(NULL, argv[1], &hints, &result); + if (s != 0) { + fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s)); + exit(EXIT_FAILURE); + } + + /* getaddrinfo() returns a list of address structures. + Try each address until we successfully bind(2). + If socket(2) (or bind(2)) fails, we (close the socket + and) try the next address. */ + + for (rp = result; rp != NULL; rp = rp\->ai_next) { + sfd = socket(rp\->ai_family, rp\->ai_socktype, + rp\->ai_protocol); + if (sfd == \-1) + continue; + + if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0) + break; /* Success */ + + close(sfd); + } + + if (rp == NULL) { /* No address succeeded */ + fprintf(stderr, "Could not bind\\n"); + exit(EXIT_FAILURE); + } + + freeaddrinfo(result); /* No longer needed */ + + /* Read datagrams and echo them back to sender */ + + for (;;) { + peer_addr_len = sizeof(struct sockaddr_storage); + nread = recvfrom(sfd, buf, BUF_SIZE, 0, + (struct sockaddr *) &peer_addr, &peer_addr_len); + if (nread == \-1) + continue; /* Ignore failed request */ + + char host[NI_MAXHOST], service[NI_MAXSERV]; + + s = getnameinfo((struct sockaddr *) &peer_addr, + peer_addr_len, host, NI_MAXHOST, + service, NI_MAXSERV, NI_NUMERICSERV); + if (s == 0) + printf("Received %zd bytes from %s:%s\\n", + nread, host, service); + else + fprintf(stderr, "getnameinfo: %s\\n", gai_strerror(s)); + + if (sendto(sfd, buf, nread, 0, + (struct sockaddr *) &peer_addr, + peer_addr_len) != nread) + fprintf(stderr, "Error sending response\\n"); + } +} +.EE +.SS Client program +\& +.EX +#include +#include +#include +#include +#include +#include +#include + +#define BUF_SIZE 500 + +int +main(int argc, char *argv[]) +{ + struct addrinfo hints; + struct addrinfo *result, *rp; + int sfd, s, j; + size_t len; + ssize_t nread; + char buf[BUF_SIZE]; + + if (argc < 3) { + fprintf(stderr, "Usage: %s host port msg...\\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* Obtain address(es) matching host/port */ + + memset(&hints, 0, sizeof(struct addrinfo)); + hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */ + hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */ + hints.ai_flags = 0; + hints.ai_protocol = 0; /* Any protocol */ + + s = getaddrinfo(argv[1], argv[2], &hints, &result); + if (s != 0) { + fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s)); + exit(EXIT_FAILURE); + } + + /* getaddrinfo() returns a list of address structures. + Try each address until we successfully connect(2). + If socket(2) (or connect(2)) fails, we (close the socket + and) try the next address. */ + + for (rp = result; rp != NULL; rp = rp\->ai_next) { + sfd = socket(rp\->ai_family, rp\->ai_socktype, + rp\->ai_protocol); + if (sfd == \-1) + continue; + + if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1) + break; /* Success */ + + close(sfd); + } + + if (rp == NULL) { /* No address succeeded */ + fprintf(stderr, "Could not connect\\n"); + exit(EXIT_FAILURE); + } + + freeaddrinfo(result); /* No longer needed */ + + /* Send remaining command\-line arguments as separate + datagrams, and read responses from server */ + + for (j = 3; j < argc; j++) { + len = strlen(argv[j]) + 1; + /* +1 for terminating null byte */ + + if (len + 1 > BUF_SIZE) { + fprintf(stderr, + "Ignoring long message in argument %d\\n", j); + continue; + } + + if (write(sfd, argv[j], len) != len) { + fprintf(stderr, "partial/failed write\\n"); + exit(EXIT_FAILURE); + } + + nread = read(sfd, buf, BUF_SIZE); + if (nread == \-1) { + perror("read"); + exit(EXIT_FAILURE); + } + + printf("Received %zd bytes: %s\\n", nread, buf); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.\" .BR getipnodebyaddr (3), +.\" .BR getipnodebyname (3), +.BR getaddrinfo_a (3), +.BR gethostbyname (3), +.BR getnameinfo (3), +.BR inet (3), +.BR gai.conf (5), +.BR hostname (7), +.BR ip (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getaddrinfo_a.3 b/man3/getaddrinfo_a.3 new file mode 100644 index 0000000..150a2e8 --- /dev/null +++ b/man3/getaddrinfo_a.3 @@ -0,0 +1,632 @@ +.\" Copyright (c) 2009 Petr Baudis +.\" and clean-ups and additions (C) Copyright 2010 Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References: http://people.redhat.com/drepper/asynchnl.pdf, +.\" http://www.imperialviolet.org/2005/06/01/asynchronous-dns-lookups-with-glibc.html +.\" +.TH GETADDRINFO_A 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getaddrinfo_a, gai_suspend, gai_error, gai_cancel \- asynchronous +network address and service translation +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int getaddrinfo_a(int " "mode" ", struct gaicb *" "list[]" , +.BI " int " "nitems" ", struct sigevent *" "sevp" ); +.PP +.BI "int gai_suspend(const struct gaicb * const " "list[]" ", int " "nitems" , +.BI " const struct timespec *" "timeout" ); +.PP +.BI "int gai_error(struct gaicb *" "req" ); +.PP +.BI "int gai_cancel(struct gaicb *" "req" ); +.PP +Link with \fI\-lanl\fP. +.fi +.SH DESCRIPTION +The +.BR getaddrinfo_a () +function performs the same task as +.BR getaddrinfo (3), +but allows multiple name look-ups to be performed asynchronously, +with optional notification on completion of look-up operations. +.PP +The +.I mode +argument has one of the following values: +.TP +.B GAI_WAIT +Perform the look-ups synchronously. +The call blocks until the look-ups have completed. +.TP +.B GAI_NOWAIT +Perform the look-ups asynchronously. +The call returns immediately, +and the requests are resolved in the background. +See the discussion of the +.I sevp +argument below. +.PP +The array +.I list +specifies the look-up requests to process. +The +.I nitems +argument specifies the number of elements in +.IR list . +The requested look-up operations are started in parallel. +NULL elements in +.I list +are ignored. +Each request is described by a +.I gaicb +structure, defined as follows: +.PP +.in +4n +.EX +struct gaicb { + const char *ar_name; + const char *ar_service; + const struct addrinfo *ar_request; + struct addrinfo *ar_result; +}; +.EE +.in +.PP +The elements of this structure correspond to the arguments of +.BR getaddrinfo (3). +Thus, +.I ar_name +corresponds to the +.I node +argument and +.I ar_service +to the +.I service +argument, identifying an Internet host and a service. +The +.I ar_request +element corresponds to the +.I hints +argument, specifying the criteria for selecting +the returned socket address structures. +Finally, +.I ar_result +corresponds to the +.I res +argument; you do not need to initialize this element, +it will be automatically set when the request +is resolved. +The +.I addrinfo +structure referenced by the last two elements is described in +.BR getaddrinfo (3). +.PP +When +.I mode +is specified as +.BR GAI_NOWAIT , +notifications about resolved requests +can be obtained by employing the +.I sigevent +structure pointed to by the +.I sevp +argument. +For the definition and general details of this structure, see +.BR sigevent (7). +The +.I sevp\->sigev_notify +field can have the following values: +.TP +.BR SIGEV_NONE +Don't provide any notification. +.TP +.BR SIGEV_SIGNAL +When a look-up completes, generate the signal +.I sigev_signo +for the process. +See +.BR sigevent (7) +for general details. +The +.I si_code +field of the +.I siginfo_t +structure will be set to +.BR SI_ASYNCNL . +.\" si_pid and si_uid are also set, to the values of the calling process, +.\" which doesn't provide useful information, so we'll skip mentioning it. +.TP +.BR SIGEV_THREAD +When a look-up completes, invoke +.I sigev_notify_function +as if it were the start function of a new thread. +See +.BR sigevent (7) +for details. +.PP +For +.BR SIGEV_SIGNAL +and +.BR SIGEV_THREAD , +it may be useful to point +.IR sevp\->sigev_value.sival_ptr +to +.IR list . +.PP +The +.BR gai_suspend () +function suspends execution of the calling thread, +waiting for the completion of one or more requests in the array +.IR list . +The +.I nitems +argument specifies the size of the array +.IR list . +The call blocks until one of the following occurs: +.IP * 3 +One or more of the operations in +.I list +completes. +.IP * +The call is interrupted by a signal that is caught. +.IP * +The time interval specified in +.I timeout +elapses. +This argument specifies a timeout in seconds plus nanoseconds (see +.BR nanosleep (2) +for details of the +.I timespec +structure). +If +.I timeout +is NULL, then the call blocks indefinitely +(until one of the events above occurs). +.PP +No explicit indication of which request was completed is given; +you must determine which request(s) have completed by iterating with +.BR gai_error () +over the list of requests. +.PP +The +.BR gai_error () +function returns the status of the request +.IR req : +either +.B EAI_INPROGRESS +if the request was not completed yet, +0 if it was handled successfully, +or an error code if the request could not be resolved. +.PP +The +.BR gai_cancel () +function cancels the request +.IR req . +If the request has been canceled successfully, +the error status of the request will be set to +.B EAI_CANCELED +and normal asynchronous notification will be performed. +The request cannot be canceled if it is currently being processed; +in that case, it will be handled as if +.BR gai_cancel () +has never been called. +If +.I req +is NULL, an attempt is made to cancel all outstanding requests +that the process has made. +.SH RETURN VALUE +The +.BR getaddrinfo_a () +function returns 0 if all of the requests have been enqueued successfully, +or one of the following nonzero error codes: +.TP +.B EAI_AGAIN +The resources necessary to enqueue the look-up requests were not available. +The application may check the error status of each +request to determine which ones failed. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_SYSTEM +.I mode +is invalid. +.PP +The +.BR gai_suspend () +function returns 0 if at least one of the listed requests has been completed. +Otherwise, it returns one of the following nonzero error codes: +.TP +.B EAI_AGAIN +The given timeout expired before any of the requests could be completed. +.TP +.B EAI_ALLDONE +There were no actual requests given to the function. +.TP +.B EAI_INTR +A signal has interrupted the function. +Note that this interruption might have been +caused by signal notification of some completed look-up request. +.PP +The +.BR gai_error () +function can return +.B EAI_INPROGRESS +for an unfinished look-up request, +0 for a successfully completed look-up +(as described above), one of the error codes that could be returned by +.BR getaddrinfo (3), +or the error code +.B EAI_CANCELED +if the request has been canceled explicitly before it could be finished. +.PP +The +.BR gai_cancel () +function can return one of these values: +.TP +.B EAI_CANCELED +The request has been canceled successfully. +.TP +.B EAI_NOTCANCELED +The request has not been canceled. +.TP +.B EAI_ALLDONE +The request has already completed. +.PP +The +.BR gai_strerror (3) +function translates these error codes to a human readable string, +suitable for error reporting. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR getaddrinfo_a (), +.BR gai_suspend (), +.BR gai_error (), +.BR gai_cancel () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +These functions are GNU extensions; +they first appeared in glibc in version 2.2.3. +.SH NOTES +The interface of +.BR getaddrinfo_a () +was modeled after the +.BR lio_listio (3) +interface. +.SH EXAMPLE +Two examples are provided: a simple example that resolves +several requests in parallel synchronously, and a complex example +showing some of the asynchronous capabilities. +.SS Synchronous example +The program below simply resolves several hostnames in parallel, +giving a speed-up compared to resolving the hostnames sequentially using +.BR getaddrinfo (3). +The program might be used like this: +.PP +.in +4n +.EX +$ \fB./a.out ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz\fP +ftp.us.kernel.org: 128.30.2.36 +enoent.linuxfoundation.org: Name or service not known +gnu.cz: 87.236.197.13 +.EE +.in +.PP +Here is the program source code +.PP +.EX +#define _GNU_SOURCE +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + int i, ret; + struct gaicb *reqs[argc \- 1]; + char host[NI_MAXHOST]; + struct addrinfo *res; + + if (argc < 2) { + fprintf(stderr, "Usage: %s HOST...\\n", argv[0]); + exit(EXIT_FAILURE); + } + + for (i = 0; i < argc \- 1; i++) { + reqs[i] = malloc(sizeof(*reqs[0])); + if (reqs[i] == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + memset(reqs[i], 0, sizeof(*reqs[0])); + reqs[i]\->ar_name = argv[i + 1]; + } + + ret = getaddrinfo_a(GAI_WAIT, reqs, argc \- 1, NULL); + if (ret != 0) { + fprintf(stderr, "getaddrinfo_a() failed: %s\\n", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } + + for (i = 0; i < argc \- 1; i++) { + printf("%s: ", reqs[i]\->ar_name); + ret = gai_error(reqs[i]); + if (ret == 0) { + res = reqs[i]\->ar_result; + + ret = getnameinfo(res\->ai_addr, res\->ai_addrlen, + host, sizeof(host), + NULL, 0, NI_NUMERICHOST); + if (ret != 0) { + fprintf(stderr, "getnameinfo() failed: %s\\n", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } + puts(host); + + } else { + puts(gai_strerror(ret)); + } + } + exit(EXIT_SUCCESS); +} +.EE +.SS Asynchronous example +This example shows a simple interactive +.BR getaddrinfo_a () +front-end. +The notification facility is not demonstrated. +.PP +An example session might look like this: +.PP +.in +4n +.EX +$ \fB./a.out\fP +> a ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz +> c 2 +[2] gnu.cz: Request not canceled +> w 0 1 +[00] ftp.us.kernel.org: Finished +> l +[00] ftp.us.kernel.org: 216.165.129.139 +[01] enoent.linuxfoundation.org: Processing request in progress +[02] gnu.cz: 87.236.197.13 +> l +[00] ftp.us.kernel.org: 216.165.129.139 +[01] enoent.linuxfoundation.org: Name or service not known +[02] gnu.cz: 87.236.197.13 +.EE +.in +.PP +The program source is as follows: +.PP +.EX +#define _GNU_SOURCE +#include +#include +#include +#include + +static struct gaicb **reqs = NULL; +static int nreqs = 0; + +static char * +getcmd(void) +{ + static char buf[256]; + + fputs("> ", stdout); fflush(stdout); + if (fgets(buf, sizeof(buf), stdin) == NULL) + return NULL; + + if (buf[strlen(buf) \- 1] == \(aq\\n\(aq) + buf[strlen(buf) \- 1] = 0; + + return buf; +} + +/* Add requests for specified hostnames */ +static void +add_requests(void) +{ + int nreqs_base = nreqs; + char *host; + int ret; + + while ((host = strtok(NULL, " "))) { + nreqs++; + reqs = realloc(reqs, nreqs * sizeof(reqs[0])); + + reqs[nreqs \- 1] = calloc(1, sizeof(*reqs[0])); + reqs[nreqs \- 1]\->ar_name = strdup(host); + } + + /* Queue nreqs_base..nreqs requests. */ + + ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base], + nreqs \- nreqs_base, NULL); + if (ret) { + fprintf(stderr, "getaddrinfo_a() failed: %s\\n", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } +} + +/* Wait until at least one of specified requests completes */ +static void +wait_requests(void) +{ + char *id; + int i, ret, n; + struct gaicb const **wait_reqs = calloc(nreqs, sizeof(*wait_reqs)); + /* NULL elements are ignored by gai_suspend(). */ + + while ((id = strtok(NULL, " ")) != NULL) { + n = atoi(id); + + if (n >= nreqs) { + printf("Bad request number: %s\\n", id); + return; + } + + wait_reqs[n] = reqs[n]; + } + + ret = gai_suspend(wait_reqs, nreqs, NULL); + if (ret) { + printf("gai_suspend(): %s\\n", gai_strerror(ret)); + return; + } + + for (i = 0; i < nreqs; i++) { + if (wait_reqs[i] == NULL) + continue; + + ret = gai_error(reqs[i]); + if (ret == EAI_INPROGRESS) + continue; + + printf("[%02d] %s: %s\\n", i, reqs[i]\->ar_name, + ret == 0 ? "Finished" : gai_strerror(ret)); + } +} + +/* Cancel specified requests */ +static void +cancel_requests(void) +{ + char *id; + int ret, n; + + while ((id = strtok(NULL, " ")) != NULL) { + n = atoi(id); + + if (n >= nreqs) { + printf("Bad request number: %s\\n", id); + return; + } + + ret = gai_cancel(reqs[n]); + printf("[%s] %s: %s\\n", id, reqs[atoi(id)]\->ar_name, + gai_strerror(ret)); + } +} + +/* List all requests */ +static void +list_requests(void) +{ + int i, ret; + char host[NI_MAXHOST]; + struct addrinfo *res; + + for (i = 0; i < nreqs; i++) { + printf("[%02d] %s: ", i, reqs[i]\->ar_name); + ret = gai_error(reqs[i]); + + if (!ret) { + res = reqs[i]\->ar_result; + + ret = getnameinfo(res\->ai_addr, res\->ai_addrlen, + host, sizeof(host), + NULL, 0, NI_NUMERICHOST); + if (ret) { + fprintf(stderr, "getnameinfo() failed: %s\\n", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } + puts(host); + } else { + puts(gai_strerror(ret)); + } + } +} + +int +main(int argc, char *argv[]) +{ + char *cmdline; + char *cmd; + + while ((cmdline = getcmd()) != NULL) { + cmd = strtok(cmdline, " "); + + if (cmd == NULL) { + list_requests(); + } else { + switch (cmd[0]) { + case \(aqa\(aq: + add_requests(); + break; + case \(aqw\(aq: + wait_requests(); + break; + case \(aqc\(aq: + cancel_requests(); + break; + case \(aql\(aq: + list_requests(); + break; + default: + fprintf(stderr, "Bad command: %c\\n", cmd[0]); + break; + } + } + } + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getaddrinfo (3), +.BR inet (3), +.BR lio_listio (3), +.BR hostname (7), +.BR ip (7), +.BR sigevent (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getaliasbyname.3 b/man3/getaliasbyname.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man3/getaliasbyname.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/getaliasbyname_r.3 b/man3/getaliasbyname_r.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man3/getaliasbyname_r.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/getaliasent.3 b/man3/getaliasent.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man3/getaliasent.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/getaliasent_r.3 b/man3/getaliasent_r.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man3/getaliasent_r.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man3/getauxval.3 b/man3/getauxval.3 new file mode 100644 index 0000000..c721dd0 --- /dev/null +++ b/man3/getauxval.3 @@ -0,0 +1,262 @@ +.\" Copyright 2012 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" See also https://lwn.net/Articles/519085/ +.\" +.TH GETAUXVAL 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getauxval \- retrieve a value from the auxiliary vector +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "unsigned long getauxval(unsigned long " type ); +.fi +.SH DESCRIPTION +The +.BR getauxval () +function retrieves values from the auxiliary vector, +a mechanism that the kernel's ELF binary loader +uses to pass certain information to +user space when a program is executed. +.PP +Each entry in the auxiliary vector consists of a pair of values: +a type that identifies what this entry represents, +and a value for that type. +Given the argument +.IR type , +.BR getauxval () +returns the corresponding value. +.PP +The value returned for each +.I type +is given in the following list. +Not all +.I type +values are present on all architectures. +.TP +.BR AT_BASE +The base address of the program interpreter (usually, the dynamic linker). +.TP +.BR AT_BASE_PLATFORM +A string identifying the real platform; may differ from +.BR AT_PLATFORM +(PowerPC only). +.TP +.BR AT_CLKTCK +The frequency with which +.BR times (2) +counts. +This value can also be obtained via +.IR sysconf(_SC_CLK_TCK) . +.TP +.BR AT_DCACHEBSIZE +The data cache block size. +.TP +.BR AT_EGID +The effective group ID of the thread. +.TP +.BR AT_ENTRY +The entry address of the executable. +.TP +.BR AT_EUID +The effective user ID of the thread. +.TP +.BR AT_EXECFD +File descriptor of program. +.TP +.BR AT_EXECFN +Pathname used to execute program. +.TP +.BR AT_FLAGS +Flags (unused). +.TP +.BR AT_FPUCW +Used FPU control word (SuperH architecture only). +This gives some information about the FPU initialization +performed by the kernel. +.TP +.BR AT_GID +The real group ID of the thread. +.TP +.BR AT_HWCAP +An architecture and ABI dependent bit-mask whose settings +indicate detailed processor capabilities. +The contents of the bit mask are hardware dependent +(for example, see the kernel source file +.IR arch/x86/include/asm/cpufeature.h +for details relating to the Intel x86 architecture; the value +returned is the first 32-bit word of the array described there). +A human-readable version of the same information is available via +.IR /proc/cpuinfo . +.TP +.BR AT_HWCAP2 " (since glibc 2.18)" +Further machine-dependent hints about processor capabilities. +.TP +.BR AT_ICACHEBSIZE +The instruction cache block size. +.\" .TP +.\" .BR AT_IGNORE +.\" .TP +.\" .BR AT_IGNOREPPC +.\" .TP +.\" .BR AT_NOTELF +.TP +.BR AT_PAGESZ +The system page size (the same value returned by +.IR sysconf(_SC_PAGESIZE) ). +.TP +.BR AT_PHDR +The address of the program headers of the executable. +.TP +.BR AT_PHENT +The size of program header entry. +.TP +.BR AT_PHNUM +The number of program headers. +.TP +.BR AT_PLATFORM +A pointer to a string that identifies the hardware platform +that the program is running on. +The dynamic linker uses this in the interpretation of +.IR rpath +values. +.TP +.BR AT_RANDOM +The address of sixteen bytes containing a random value. +.TP +.BR AT_SECURE +Has a nonzero value if this executable should be treated securely. +Most commonly, a nonzero value indicates that the process is +executing a set-user-ID or set-group-ID binary +(so that its real and effective UIDs or GIDs differ from one another), +or that it gained capabilities by executing +a binary file that has capabilities (see +.BR capabilities (7)). +Alternatively, +a nonzero value may be triggered by a Linux Security Module. +When this value is nonzero, +the dynamic linker disables the use of certain environment variables (see +.BR ld-linux.so (8)) +and glibc changes other aspects of its behavior. +(See also +.BR secure_getenv (3).) +.TP +.BR AT_SYSINFO +The entry point to the system call function in the vDSO. +Not present/needed on all architectures (e.g., absent on x86-64). +.TP +.BR AT_SYSINFO_EHDR +The address of a page containing the virtual Dynamic Shared Object (vDSO) +that the kernel creates in order to provide fast implementations of +certain system calls. +.TP +.BR AT_UCACHEBSIZE +The unified cache block size. +.TP +.BR AT_UID +The real user ID of the thread. +.SH RETURN VALUE +On success, +.BR getauxval () +returns the value corresponding to +.IR type . +If +.I type +is not found, 0 is returned. +.SH ERRORS +.TP +.BR ENOENT " (since glibc 2.19)" +.\" commit b9ab448f980e296eac21ac65f53783967cc6037b +No entry corresponding to +.IR type +could be found in the auxiliary vector. +.SH VERSIONS +The +.BR getauxval () +function was added to glibc in version 2.16. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getauxval () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is a nonstandard glibc extension. +.SH NOTES +The primary consumer of the information in the auxiliary vector +is the dynamic linker +.BR ld-linux.so (8). +The auxiliary vector is a convenient and efficient shortcut +that allows the kernel to communicate a certain set of standard +information that the dynamic linker usually or always needs. +In some cases, the same information could be obtained by system calls, +but using the auxiliary vector is cheaper. +.PP +The auxiliary vector resides just above the argument list and +environment in the process address space. +The auxiliary vector supplied to a program can be viewed by setting the +.B LD_SHOW_AUXV +environment variable when running a program: +.PP +.in +4n +.EX +$ LD_SHOW_AUXV=1 sleep 1 +.EE +.in +.PP +The auxiliary vector of any process can (subject to file permissions) +be obtained via +.IR /proc/[pid]/auxv ; +see +.BR proc (5) +for more information. +.SH BUGS +Before the addition of the +.B ENOENT +error in glibc 2.19, +there was no way to unambiguously distinguish the case where +.I type +could not be found from the case where the value corresponding to +.I type +was zero. +.SH SEE ALSO +.BR secure_getenv (3), +.BR vdso (7), +.BR ld-linux.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getc.3 b/man3/getc.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man3/getc.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man3/getc_unlocked.3 b/man3/getc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/getc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/getchar.3 b/man3/getchar.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man3/getchar.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man3/getchar_unlocked.3 b/man3/getchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/getchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/getcontext.3 b/man3/getcontext.3 new file mode 100644 index 0000000..a7bfd31 --- /dev/null +++ b/man3/getcontext.3 @@ -0,0 +1,215 @@ +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETCONTEXT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getcontext, setcontext \- get or set the user context +.SH SYNOPSIS +.B #include +.PP +.BI "int getcontext(ucontext_t *" ucp ); +.br +.BI "int setcontext(const ucontext_t *" ucp ); +.SH DESCRIPTION +In a System V-like environment, one has the two types +.I mcontext_t +and +.I ucontext_t +defined in +.I +and the four functions +.BR getcontext (), +.BR setcontext (), +.BR makecontext (3), +and +.BR swapcontext (3) +that allow user-level context switching between multiple +threads of control within a process. +.PP +The +.I mcontext_t +type is machine-dependent and opaque. +The +.I ucontext_t +type is a structure that has at least +the following fields: +.PP +.in +4 +.EX +typedef struct ucontext_t { + struct ucontext_t *uc_link; + sigset_t uc_sigmask; + stack_t uc_stack; + mcontext_t uc_mcontext; + ... +} ucontext_t; +.EE +.in +.PP +with +.IR sigset_t +and +.I stack_t +defined in +.IR . +Here +.I uc_link +points to the context that will be resumed +when the current context terminates (in case the current context +was created using +.BR makecontext (3)), +.I uc_sigmask +is the +set of signals blocked in this context (see +.BR sigprocmask (2)), +.I uc_stack +is the stack used by this context (see +.BR sigaltstack (2)), +and +.I uc_mcontext +is the +machine-specific representation of the saved context, +that includes the calling thread's machine registers. +.PP +The function +.BR getcontext () +initializes the structure +pointed at by +.I ucp +to the currently active context. +.PP +The function +.BR setcontext () +restores the user context +pointed at by +.IR ucp . +A successful call does not return. +The context should have been obtained by a call of +.BR getcontext (), +or +.BR makecontext (3), +or passed as third argument to a signal +handler. +.PP +If the context was obtained by a call of +.BR getcontext (), +program execution continues as if this call just returned. +.PP +If the context was obtained by a call of +.BR makecontext (3), +program execution continues by a call to the function +.I func +specified as the second argument of that call to +.BR makecontext (3). +When the function +.I func +returns, we continue with the +.I uc_link +member of the structure +.I ucp +specified as the +first argument of that call to +.BR makecontext (3). +When this member is NULL, the thread exits. +.PP +If the context was obtained by a call to a signal handler, +then old standard text says that "program execution continues with the +program instruction following the instruction interrupted +by the signal". +However, this sentence was removed in SUSv2, +and the present verdict is "the result is unspecified". +.SH RETURN VALUE +When successful, +.BR getcontext () +returns 0 and +.BR setcontext () +does not return. +On error, both return \-1 and set +.I errno +appropriately. +.SH ERRORS +None defined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw26 lb lb +l l l. +Interface Attribute Value +T{ +.BR getcontext (), +.BR setcontext () +T} Thread safety MT-Safe race:ucp +.TE +.SH CONFORMING TO +SUSv2, POSIX.1-2001. +POSIX.1-2008 removes the specification of +.BR getcontext (), +citing portability issues, and +recommending that applications be rewritten to use POSIX threads instead. +.SH NOTES +The earliest incarnation of this mechanism was the +.BR setjmp (3)/ longjmp (3) +mechanism. +Since that does not define +the handling of the signal context, the next stage was the +.BR sigsetjmp (3)/ siglongjmp (3) +pair. +The present mechanism gives much more control. +On the other hand, +there is no easy way to detect whether a return from +.BR getcontext () +is from the first call, or via a +.BR setcontext () +call. +The user has to invent her own bookkeeping device, and a register +variable won't do since registers are restored. +.PP +When a signal occurs, the current user context is saved and +a new context is created by the kernel for the signal handler. +Do not leave the handler using +.BR longjmp (3): +it is undefined what would happen with contexts. +Use +.BR siglongjmp (3) +or +.BR setcontext () +instead. +.SH SEE ALSO +.BR sigaction (2), +.BR sigaltstack (2), +.BR sigprocmask (2), +.BR longjmp (3), +.BR makecontext (3), +.BR sigsetjmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getcwd.3 b/man3/getcwd.3 new file mode 100644 index 0000000..7923d50 --- /dev/null +++ b/man3/getcwd.3 @@ -0,0 +1,297 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 21 22:35:42 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 18 Mar 1996 by Martin Schulze (joey@infodrom.north.de): +.\" Corrected description of getwd(). +.\" Modified Sat Aug 21 12:32:12 MET 1999 by aeb - applied fix by aj +.\" Modified Mon Dec 11 13:32:51 MET 2000 by aeb +.\" Modified Thu Apr 22 03:49:15 CEST 2002 by Roger Luethi +.\" +.TH GETCWD 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getcwd, getwd, get_current_dir_name \- get current working directory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *getcwd(char *" buf ", size_t " size ); +.PP +.BI "char *getwd(char *" buf ); +.PP +.B "char *get_current_dir_name(void);" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR get_current_dir_name (): +.RS +_GNU_SOURCE +.RE +.PP +.BR getwd (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.12: +.nf +(_XOPEN_SOURCE\ >=\ 500) && ! (_POSIX_C_SOURCE\ >=\ 200809L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.TP 4 +.fi +Before glibc 2.12: +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH DESCRIPTION +These functions return a null-terminated string containing an +absolute pathname that is the current working directory of +the calling process. +The pathname is returned as the function result and via the argument +.IR buf , +if present. +.PP +If the current directory is not below the root directory of the current +process (e.g., because the process set a new filesystem root using +.BR chroot (2) +without changing its current directory into the new root), +then, since Linux 2.6.36, +.\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74 +the returned path will be prefixed with the string "(unreachable)". +Such behavior can also be caused by an unprivileged user by changing +the current directory into another mount namespace. +When dealing with paths from untrusted sources, callers of these +functions should consider checking whether the returned path starts +with '/' or '(' to avoid misinterpreting an unreachable path +as a relative path. +.PP +The +.BR getcwd () +function copies an absolute pathname of the current working directory +to the array pointed to by +.IR buf , +which is of length +.IR size . +.PP +If the length of the absolute pathname of the current working directory, +including the terminating null byte, exceeds +.I size +bytes, NULL is returned, and +.I errno +is set to +.BR ERANGE ; +an application should check for this error, and allocate a larger +buffer if necessary. +.PP +As an extension to the POSIX.1-2001 standard, glibc's +.BR getcwd () +allocates the buffer dynamically using +.BR malloc (3) +if +.I buf +is NULL. +In this case, the allocated buffer has the length +.I size +unless +.I size +is zero, when +.I buf +is allocated as big as necessary. +The caller should +.BR free (3) +the returned buffer. +.PP +.BR get_current_dir_name () +will +.BR malloc (3) +an array big enough to hold the absolute pathname of +the current working directory. +If the environment +variable +.B PWD +is set, and its value is correct, then that value will be returned. +The caller should +.BR free (3) +the returned buffer. +.PP +.BR getwd () +does not +.BR malloc (3) +any memory. +The +.I buf +argument should be a pointer to an array at least +.B PATH_MAX +bytes long. +If the length of the absolute pathname of the current working directory, +including the terminating null byte, exceeds +.B PATH_MAX +bytes, NULL is returned, and +.I errno +is set to +.BR ENAMETOOLONG . +(Note that on some systems, +.B PATH_MAX +may not be a compile-time constant; +furthermore, its value may depend on the filesystem, see +.BR pathconf (3).) +For portability and security reasons, use of +.BR getwd () +is deprecated. +.SH RETURN VALUE +On success, these functions return a pointer to a string containing +the pathname of the current working directory. +In the case +.BR getcwd () +and +.BR getwd () +this is the same value as +.IR buf . +.PP +On failure, these functions return NULL, and +.I errno +is set to indicate the error. +The contents of the array pointed to by +.I buf +are undefined on error. +.SH ERRORS +.TP +.B EACCES +Permission to read or search a component of the filename was denied. +.TP +.B EFAULT +.I buf +points to a bad address. +.TP +.B EINVAL +The +.I size +argument is zero and +.I buf +is not a null pointer. +.TP +.B EINVAL +.BR getwd (): +.I buf +is NULL. +.TP +.B ENAMETOOLONG +.BR getwd (): +The size of the null-terminated absolute pathname string exceeds +.B PATH_MAX +bytes. +.TP +.B ENOENT +The current working directory has been unlinked. +.TP +.B ENOMEM +Out of memory. +.TP +.B ERANGE +The +.I size +argument is less than the length of the absolute pathname of the +working directory, including the terminating null byte. +You need to allocate a bigger array and try again. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw22 lb lb +l l l. +Interface Attribute Value +T{ +.BR getcwd (), +.BR getwd () +T} Thread safety MT-Safe +T{ +.BR get_current_dir_name () +T} Thread safety MT-Safe env +.TE +.SH CONFORMING TO +.BR getcwd () +conforms to POSIX.1-2001. +Note however that POSIX.1-2001 leaves the behavior of +.BR getcwd () +unspecified if +.I buf +is NULL. +.PP +.BR getwd () +is present in POSIX.1-2001, but marked LEGACY. +POSIX.1-2008 removes the specification of +.BR getwd (). +Use +.BR getcwd () +instead. +POSIX.1-2001 +does not define any errors for +.BR getwd (). +.PP +.BR get_current_dir_name () +is a GNU extension. +.SH NOTES +Under Linux, the function +.BR getcwd () +is a system call (since 2.1.92). +On older systems it would query +.IR /proc/self/cwd . +If both system call and proc filesystem are missing, a +generic implementation is called. +Only in that case can +these calls fail under Linux with +.BR EACCES . +.PP +These functions are often used to save the location of the current working +directory for the purpose of returning to it later. +Opening the current +directory (".") and calling +.BR fchdir (2) +to return is usually a faster and more reliable alternative when sufficiently +many file descriptors are available, especially on platforms other than Linux. +.SH SEE ALSO +.BR pwd (1), +.BR chdir (2), +.BR fchdir (2), +.BR open (2), +.BR unlink (2), +.BR free (3), +.BR malloc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getdate.3 b/man3/getdate.3 new file mode 100644 index 0000000..fb94464 --- /dev/null +++ b/man3/getdate.3 @@ -0,0 +1,333 @@ +.\" Copyright 2001 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified, 2001-12-26, aeb +.\" 2008-09-07, mtk, Various rewrites; added an example program. +.\" +.TH GETDATE 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +getdate, getdate_r \- convert a date-plus-time string to broken-down time +.SH SYNOPSIS +.B "#include " +.PP +.BI "struct tm *getdate(const char *" string ); +.PP +.B "extern int getdate_err;" +.PP +.B "#include " +.PP +.BI "int getdate_r(const char *" string ", struct tm *" res ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getdate (): +.ad l +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.RE +.br +.BR getdate_r (): +.ad l +.RS 4 +_GNU_SOURCE +.RE +.ad +.SH DESCRIPTION +The function +.BR getdate () +converts a string representation of a date and time, +contained in the buffer pointed to by +.IR string , +into a broken-down time. +The broken-down time is stored in a +.I tm +structure, and a pointer to this +structure is returned as the function result. +This +.I tm +structure is allocated in static storage, +and consequently it will be overwritten by further calls to +.BR getdate (). +.PP +In contrast to +.BR strptime (3), +(which has a +.I format +argument), +.BR getdate () +uses the formats found in the file +whose full pathname is given in the environment variable +.BR DATEMSK . +The first line in the file that matches the given input string +is used for the conversion. +.PP +The matching is done case insensitively. +Superfluous whitespace, either in the pattern or in the string to +be converted, is ignored. +.PP +The conversion specifications that a pattern can contain are those given for +.BR strptime (3). +One more conversion specification is specified in POSIX.1-2001: +.TP +.B %Z +Timezone name. +.\" FIXME Is it (still) true that %Z is not supported in glibc? +.\" Looking at the glibc 2.21 source code, where the implementation uses +.\" strptime(), suggests that it might be supported. +This is not implemented in glibc. +.PP +When +.B %Z +is given, the structure containing the broken-down time +is initialized with values corresponding to the current +time in the given timezone. +Otherwise, the structure is initialized to the broken-down time +corresponding to the current local time (as by a call to +.BR localtime (3)). +.PP +When only the day of the week is given, +the day is taken to be the first such day +on or after today. +.PP +When only the month is given (and no year), the month is taken to +be the first such month equal to or after the current month. +If no day is given, it is the first day of the month. +.PP +When no hour, minute and second are given, the current +hour, minute and second are taken. +.PP +If no date is given, but we know the hour, then that hour is taken +to be the first such hour equal to or after the current hour. +.PP +.BR getdate_r () +is a GNU extension that provides a reentrant version of +.BR getdate (). +Rather than using a global variable to report errors and a static buffer +to return the broken down time, +it returns errors via the function result value, +and returns the resulting broken-down time in the +caller-allocated buffer pointed to by the argument +.IR res . +.SH RETURN VALUE +When successful, +.BR getdate () +returns a pointer to a +.IR "struct tm" . +Otherwise, it returns NULL and sets the global variable +.IR getdate_err +to one of the error numbers shown below. +Changes to +.I errno +are unspecified. +.PP +On success +.BR getdate_r () +returns 0; +on error it returns one of the error numbers shown below. +.SH ERRORS +The following errors are returned via +.IR getdate_err +(for +.BR getdate ()) +or as the function result (for +.BR getdate_r ()): +.TP 4n +.B 1 +The +.B DATEMSK +environment variable is not defined, or its value is an empty string. +.TP +.B 2 +The template file specified by +.B DATEMSK +cannot be opened for reading. +.TP +.B 3 +Failed to get file status information. +.\" stat() +.TP +.B 4 +The template file is not a regular file. +.TP +.B 5 +An error was encountered while reading the template file. +.TP +.B 6 +Memory allocation failed (not enough memory available). +.\" Error 6 doesn't seem to occur in glibc +.TP +.B 7 +There is no line in the file that matches the input. +.TP +.B 8 +Invalid input specification. +.SH ENVIRONMENT +.TP +.B DATEMSK +File containing format patterns. +.TP +.BR TZ ", " LC_TIME +Variables used by +.BR strptime (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getdate () +T} Thread safety MT-Unsafe race:getdate env locale +T{ +.BR getdate_r () +T} Thread safety MT-Safe env locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The POSIX.1 specification for +.BR strptime (3) +contains conversion specifications using the +.B %E +or +.B %O +modifier, while such specifications are not given for +.BR getdate (). +In glibc, +.BR getdate () +is implemented using +.BR strptime (3), +so that precisely the same conversions are supported by both. +.SH EXAMPLE +The program below calls +.BR getdate () +for each of its command-line arguments, +and for each call displays the values in the fields of the returned +.I tm +structure. +The following shell session demonstrates the operation of the program: +.PP +.in +4n +.EX +.RB "$" " TFILE=$PWD/tfile" +.RB "$" " echo \(aq%A\(aq > $TFILE " " # Full name of the day of the week" +.RB "$" " echo \(aq%T\(aq >> $TFILE" " # ISO date (YYYY-MM-DD)" +.RB "$" " echo \(aq%F\(aq >> $TFILE" " # Time (HH:MM:SS)" +.RB "$" " date" +.RB "$" " export DATEMSK=$TFILE" +.RB "$" " ./a.out Tuesday \(aq2009-12-28\(aq \(aq12:22:33\(aq" +Sun Sep 7 06:03:36 CEST 2008 +Call 1 ("Tuesday") succeeded: + tm_sec = 36 + tm_min = 3 + tm_hour = 6 + tm_mday = 9 + tm_mon = 8 + tm_year = 108 + tm_wday = 2 + tm_yday = 252 + tm_isdst = 1 +Call 2 ("2009-12-28") succeeded: + tm_sec = 36 + tm_min = 3 + tm_hour = 6 + tm_mday = 28 + tm_mon = 11 + tm_year = 109 + tm_wday = 1 + tm_yday = 361 + tm_isdst = 0 +Call 3 ("12:22:33") succeeded: + tm_sec = 33 + tm_min = 22 + tm_hour = 12 + tm_mday = 7 + tm_mon = 8 + tm_year = 108 + tm_wday = 0 + tm_yday = 250 + tm_isdst = 1 +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct tm *tmp; + int j; + + for (j = 1; j < argc; j++) { + tmp = getdate(argv[j]); + + if (tmp == NULL) { + printf("Call %d failed; getdate_err = %d\\n", + j, getdate_err); + continue; + } + + printf("Call %d (\\"%s\\") succeeded:\\n", j, argv[j]); + printf(" tm_sec = %d\\n", tmp\->tm_sec); + printf(" tm_min = %d\\n", tmp\->tm_min); + printf(" tm_hour = %d\\n", tmp\->tm_hour); + printf(" tm_mday = %d\\n", tmp\->tm_mday); + printf(" tm_mon = %d\\n", tmp\->tm_mon); + printf(" tm_year = %d\\n", tmp\->tm_year); + printf(" tm_wday = %d\\n", tmp\->tm_wday); + printf(" tm_yday = %d\\n", tmp\->tm_yday); + printf(" tm_isdst = %d\\n", tmp\->tm_isdst); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR time (2), +.BR localtime (3), +.BR setlocale (3), +.BR strftime (3), +.BR strptime (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getdate_err.3 b/man3/getdate_err.3 new file mode 100644 index 0000000..c78ed34 --- /dev/null +++ b/man3/getdate_err.3 @@ -0,0 +1 @@ +.so man3/getdate.3 diff --git a/man3/getdate_r.3 b/man3/getdate_r.3 new file mode 100644 index 0000000..c78ed34 --- /dev/null +++ b/man3/getdate_r.3 @@ -0,0 +1 @@ +.so man3/getdate.3 diff --git a/man3/getdelim.3 b/man3/getdelim.3 new file mode 100644 index 0000000..caf4e48 --- /dev/null +++ b/man3/getdelim.3 @@ -0,0 +1 @@ +.so man3/getline.3 diff --git a/man3/getdirentries.3 b/man3/getdirentries.3 new file mode 100644 index 0000000..3209d57 --- /dev/null +++ b/man3/getdirentries.3 @@ -0,0 +1,98 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/dirent.h are: +.\" Copyright 1991, 1992 Free Software Foundation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETDIRENTRIES 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getdirentries \- get directory entries in a filesystem-independent format +.SH SYNOPSIS +.B #include +.PP +.BI "ssize_t getdirentries(int " fd ", char *" buf ", size_t " nbytes +.BI ", off_t *" basep ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getdirentries (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +Read directory entries from the directory specified by +.I fd +into +.IR buf . +At most +.I nbytes +are read. +Reading starts at offset +.IR *basep , +and +.I *basep +is updated with the new position after reading. +.SH RETURN VALUE +.BR getdirentries () +returns the number of bytes read or zero when at the end of the directory. +If an error occurs, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +See the Linux library source code for details. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getdirentries () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs, and a few other systems. +Use +.BR opendir (3) +and +.BR readdir (3) +instead. +.SH SEE ALSO +.BR lseek (2), +.BR open (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getdtablesize.3 b/man3/getdtablesize.3 new file mode 100644 index 0000000..6d08dd3 --- /dev/null +++ b/man3/getdtablesize.3 @@ -0,0 +1,116 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 2002-04-15 by Roger Luethi and aeb +.\" +.TH GETDTABLESIZE 3 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getdtablesize \- get file descriptor table size +.SH SYNOPSIS +.B #include +.PP +.B int getdtablesize(void); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getdtablesize (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.12: +.nf +/* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE + || ! (_POSIX_C_SOURCE\ >=\ 200112L) +.TP 4 +.fi +Before glibc 2.12: +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH DESCRIPTION +.BR getdtablesize () +returns the maximum number of files a process can have open, +one more than the largest possible value for a file descriptor. +.SH RETURN VALUE +The current limit on the number of open files per process. +.SH ERRORS +On Linux, +.BR getdtablesize () +can return any of the errors described for +.BR getrlimit (2); +see NOTES below. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getdtablesize () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +SVr4, 4.4BSD (the +.BR getdtablesize () +function first appeared in 4.2BSD). +It is not specified in POSIX.1; +portable applications should employ +.I sysconf(_SC_OPEN_MAX) +instead of this call. +.SH NOTES +.BR getdtablesize () +is implemented as a libc library function. +The glibc version calls +.BR getrlimit (2) +and returns the current +.B RLIMIT_NOFILE +limit, or +.B OPEN_MAX +when that fails. +.\" The libc4 and libc5 versions return +.\" .B OPEN_MAX +.\" (set to 256 since Linux 0.98.4). +.SH SEE ALSO +.BR close (2), +.BR dup (2), +.BR getrlimit (2), +.BR open (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getentropy.3 b/man3/getentropy.3 new file mode 100644 index 0000000..4bac7e0 --- /dev/null +++ b/man3/getentropy.3 @@ -0,0 +1,132 @@ +.\" Copyright (C) 2017, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETENTROPY 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getentropy \- fill a buffer with random bytes +.SH SYNOPSIS +.B #include +.PP +.BI "int getentropy(void *" buffer ", size_t " length ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getentropy (): +.br +.RS 4 +.ad l +_DEFAULT_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR getentropy () +function writes +.I length +bytes of high-quality random data to the buffer starting +at the location pointed to by +.IR buffer . +The maximum permitted value for the +.I length +argument is 256. +.PP +A successful call to +.BR getentropy () +always provides the requested number of bytes of entropy. +.SH RETURN VALUE +On success, this function returns zero. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +Part or all of the buffer specified by +.I buffer +and +.I length +is not in valid addressable memory. +.TP +.B EIO +.I length +is greater than 256. +.TP +.B EIO +An unspecified error occurred while trying to overwrite +.I buffer +with random data. +.TP +.B ENOSYS +This kernel version does not implement the +.BR getrandom (2) +system call required to implement this function. +.SH VERSIONS +The +.BR getentropy () +function first appeared in glibc 2.25. +.SH CONFORMING TO +This function is nonstandard. +It is also present on OpenBSD. +.SH NOTES +The +.BR getentropy () +function is implemented using +.BR getrandom (2). +.PP +Whereas the glibc wrapper makes +.BR getrandom (2) +a cancellation point, +.BR getentropy () +is not a cancellation point. +.PP +.BR getentropy () +is also declared in +.BR . +(No feature test macro need be defined to obtain the declaration from +that header file.) +.PP +A call to +.BR getentropy () +may block if the system has just booted and the kernel has +not yet collected enough randomness to initialize the entropy pool. +In this case, +.BR getentropy () +will keep blocking even if a signal is handled, +and will return only once the entropy pool has been initialized. +.SH SEE ALSO +.BR getrandom (2), +.BR urandom (4), +.BR random (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getenv.3 b/man3/getenv.3 new file mode 100644 index 0000000..0b60d26 --- /dev/null +++ b/man3/getenv.3 @@ -0,0 +1,158 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2007, 2012 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:30:29 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH GETENV 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getenv, secure_getenv \- get an environment variable +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *getenv(const char *" name ); +.PP +.BI "char *secure_getenv(const char *" name ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR secure_getenv (): +_GNU_SOURCE +.SH DESCRIPTION +The +.BR getenv () +function searches the environment list to find the +environment variable +.IR name , +and returns a pointer to the corresponding +.I value +string. +.PP +The GNU-specific +.BR secure_getenv () +function is just like +.BR getenv () +except that it returns NULL in cases where "secure execution" is required. +Secure execution is required if one of the following conditions +was true when the program run by the calling process was loaded: +.IP * 3 +the process's effective user ID did not match its real user ID or +the process's effective group ID did not match its real group ID +(typically this is the result of executing a set-user-ID or +set-group-ID program); +.IP * +the effective capability bit was set on the executable file; or +.IP * +the process has a nonempty permitted capability set. +.PP +Secure execution may also be required if triggered +by some Linux security modules. +.PP +The +.BR secure_getenv () +function is intended for use in general-purpose libraries +to avoid vulnerabilities that could occur if +set-user-ID or set-group-ID programs accidentally +trusted the environment. +.SH RETURN VALUE +The +.BR getenv () +function returns a pointer to the value in the +environment, or NULL if there is no match. +.SH VERSIONS +.BR secure_getenv () +first appeared in glibc 2.17. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR getenv (), +.BR secure_getenv () +T} Thread safety MT-Safe env +.TE +.SH CONFORMING TO +.BR getenv (): +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.PP +.BR secure_getenv () +is a GNU extension. +.SH NOTES +The strings in the environment list are of the form \fIname=value\fP. +.PP +As typically implemented, +.BR getenv () +returns a pointer to a string within the environment list. +The caller must take care not to modify this string, +since that would change the environment of the process. +.PP +The implementation of +.BR getenv () +is not required to be reentrant. +The string pointed to by the return value of +.BR getenv () +may be statically allocated, +and can be modified by a subsequent call to +.BR getenv (), +.BR putenv (3), +.BR setenv (3), +or +.BR unsetenv (3). +.PP +The "secure execution" mode of +.BR secure_getenv () +is controlled by the +.B AT_SECURE +flag contained in the auxiliary vector passed from the kernel to user space. +.SH SEE ALSO +.BR clearenv (3), +.BR getauxval (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR capabilities (7), +.BR environ (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getfsent.3 b/man3/getfsent.3 new file mode 100644 index 0000000..73c1599 --- /dev/null +++ b/man3/getfsent.3 @@ -0,0 +1,171 @@ +.\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Inspired by a page written by Walter Harms. +.\" +.TH GETFSENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getfsent, getfsspec, getfsfile, setfsent, endfsent \- handle fstab entries +.SH SYNOPSIS +.B #include +.PP +.B "void endfsent(void);" +.PP +.B "struct fstab *getfsent(void);" +.PP +.BI "struct fstab *getfsfile(const char *" mount_point ); +.PP +.BI "struct fstab *getfsspec(const char *" special_file ); +.PP +.B "int setfsent(void);" +.SH DESCRIPTION +These functions read from the file +.IR /etc/fstab . +The +.IR "struct fstab" +is defined by: +.PP +.in +4n +.EX +struct fstab { + char *fs_spec; /* block device name */ + char *fs_file; /* mount point */ + char *fs_vfstype; /* file-system type */ + char *fs_mntops; /* mount options */ + const char *fs_type; /* rw/rq/ro/sw/xx option */ + int fs_freq; /* dump frequency, in days */ + int fs_passno; /* pass number on parallel dump */ +}; +.EE +.in +.PP +Here the field +.I fs_type +contains (on a *BSD system) +one of the five strings "rw", "rq", "ro", "sw", "xx" +(read-write, read-write with quota, read-only, swap, ignore). +.PP +The function +.BR setfsent () +opens the file when required and positions it at the first line. +.PP +The function +.BR getfsent () +parses the next line from the file. +(After opening it when required.) +.PP +The function +.BR endfsent () +closes the file when required. +.PP +The function +.BR getfsspec () +searches the file from the start and returns the first entry found +for which the +.I fs_spec +field matches the +.I special_file +argument. +.PP +The function +.BR getfsfile () +searches the file from the start and returns the first entry found +for which the +.I fs_file +field matches the +.I mount_point +argument. +.SH RETURN VALUE +Upon success, the functions +.BR getfsent (), +.BR getfsfile (), +and +.BR getfsspec () +return a pointer to a +.IR "struct fstab" , +while +.BR setfsent () +returns 1. +Upon failure or end-of-file, these functions return NULL and 0, respectively. +.\" .SH HISTORY +.\" The +.\" .BR getfsent () +.\" function appeared in 4.0BSD; the other four functions appeared in 4.3BSD. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw24 +l l l. +Interface Attribute Value +T{ +.BR endfsent (), +.br +.BR setfsent () +T} Thread safety MT-Unsafe race:fsent +T{ +.BR getfsent (), +.br +.BR getfsspec (), +.br +.BR getfsfile () +T} Thread safety MT-Unsafe race:fsent locale +.TE +.SH CONFORMING TO +These functions are not in POSIX.1. +Several operating systems have them, for example, +*BSD, SunOS, Digital UNIX, AIX (which also has a +.BR getfstype ()). +HP-UX has functions of the same names, +that however use a +.IR "struct checklist" +instead of a +.IR "struct fstab" , +and calls these functions obsolete, superseded by +.BR getmntent (3). +.SH NOTES +These functions are not thread-safe. +.PP +Since Linux allows mounting a block special device in several places, +and since several devices can have the same mount point, where the +last device with a given mount point is the interesting one, +while +.BR getfsfile () +and +.BR getfsspec () +only return the first occurrence, these two functions are not suitable +for use under Linux. +.SH SEE ALSO +.BR getmntent (3), +.BR fstab (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getfsfile.3 b/man3/getfsfile.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man3/getfsfile.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man3/getfsspec.3 b/man3/getfsspec.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man3/getfsspec.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man3/getgrent.3 b/man3/getgrent.3 new file mode 100644 index 0000000..6c66676 --- /dev/null +++ b/man3/getgrent.3 @@ -0,0 +1,225 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:29:54 1993 by Rik Faith (faith@cs.unc.edu) +.TH GETGRENT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +getgrent, setgrent, endgrent \- get group file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.B struct group *getgrent(void); +.PP +.B void setgrent(void); +.PP +.B void endgrent(void); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.PD 0 +.ad l +.BR setgrent (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.PP +.BR getgrent (), +.BR endgrent (): +.RS 4 +Since glibc 2.22: + _XOPEN_SOURCE\ >=\ 500 || +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + _DEFAULT_SOURCE +.br +Glibc 2.21 and earlier + _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.PD +.ad b +.SH DESCRIPTION +The +.BR getgrent () +function returns a pointer to a structure containing +the broken-out fields of a record in the group database +(e.g., the local group file +.IR /etc/group , +NIS, and LDAP). +The first time +.BR getgrent () +is called, +it returns the first entry; thereafter, it returns successive entries. +.PP +The +.BR setgrent () +function rewinds to the beginning +of the group database, to allow repeated scans. +.PP +The +.BR endgrent () +function is used to close the group database +after all processing has been performed. +.PP +The \fIgroup\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL-terminated array of pointers + to names of group members */ +}; +.EE +.in +.PP +For more information about the fields of this structure, see +.BR group (5). +.SH RETURN VALUE +The +.BR getgrent () +function returns a pointer to a +.I group +structure, +or NULL if there are no more entries or an error occurs. +.PP +Upon error, +.I errno +may be set. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.PP +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getgrent (), +.BR getgrgid (3), +or +.BR getgrnam (3). +(Do not pass the returned pointer to +.BR free (3).) +.SH ERRORS +.TP +.B EAGAIN +The service was temporarily unavailable; try again later. +For NSS backends in glibc this indicates a temporary error talking to the backend. +The error may correct itself, retrying later is suggested. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.\" not in POSIX +.B ENOENT +A necessary input file cannot be found. +For NSS backends in glibc this indicates the backend is not correctly configured. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I group +structure. +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +local group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw11 lb lb +l l l. +Interface Attribute Value +T{ +.BR getgrent () +T} Thread safety T{ +MT-Unsafe race:grent +.br +race:grentbuf locale +T} +T{ +.BR setgrent (), +.BR endgrent () +T} Thread safety MT-Unsafe race:grent locale +.TE +.PP +In the above table, +.I grent +in +.I race:grent +signifies that if any of the functions +.BR setgrent (), +.BR getgrent (), +or +.BR endgrent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent_r (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR getgrouplist (3), +.BR putgrent (3), +.BR group (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getgrent_r.3 b/man3/getgrent_r.3 new file mode 100644 index 0000000..18481da --- /dev/null +++ b/man3/getgrent_r.3 @@ -0,0 +1,228 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH GETGRENT_R 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getgrent_r, fgetgrent_r \- get group file entry reentrantly +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getgrent_r(struct group *" gbuf ", char *" buf , +.BI " size_t " buflen ", struct group **" gbufp ); +.PP +.BI "int fgetgrent_r(FILE *" stream ", struct group *" gbuf ", char *" buf , +.BI " size_t " buflen ", struct group **" gbufp ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getgrent_r (): +_GNU_SOURCE +.\" FIXME . The FTM requirements seem inconsistent here. File a glibc bug? +.br +.BR fgetgrent_r (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +The functions +.BR getgrent_r () +and +.BR fgetgrent_r () +are the reentrant versions of +.BR getgrent (3) +and +.BR fgetgrent (3). +The former reads the next group entry from the stream initialized by +.BR setgrent (3). +The latter reads the next group entry from +.IR stream . +.PP +The \fIgroup\fP structure is defined in +.I +as follows: +.PP +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL-terminated array of pointers + to names of group members */ +}; +.EE +.in +.PP +For more information about the fields of this structure, see +.BR group (5). +.PP +The nonreentrant functions return a pointer to static storage, +where this static storage contains further pointers to group +name, password and members. +The reentrant functions described here return all of that in +caller-provided buffers. +First of all there is the buffer +.I gbuf +that can hold a \fIstruct group\fP. +And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the \fIstruct group\fP read from the stream, +is stored in the provided buffer +.IR *gbuf , +and a pointer to this \fIstruct group\fP is returned in +.IR *gbufp . +.SH RETURN VALUE +On success, these functions return 0 and +.I *gbufp +is a pointer to the \fIstruct group\fP. +On error, these functions return an error value and +.I *gbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. +Try again with larger buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw27 +l l l. +Interface Attribute Value +T{ +.BR getgrent_r () +T} Thread safety MT-Unsafe race:grent locale +T{ +.BR fgetgrent_r () +T} Thread safety MT-Safe +.TE +.sp 1 +In the above table, +.I grent +in +.I race:grent +signifies that if any of the functions +.BR setgrent (), +.BR getgrent (), +.BR endgrent (), +or +.BR getgrent_r () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +These functions are GNU extensions, done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +Other systems use the prototype +.PP +.in +4n +.EX +struct group *getgrent_r(struct group *grp, char *buf, + int buflen); +.EE +.in +.PP +or, better, +.PP +.in +4n +.EX +int getgrent_r(struct group *grp, char *buf, int buflen, + FILE **gr_fp); +.EE +.in +.SH NOTES +The function +.BR getgrent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH EXAMPLE +.EX +#define _GNU_SOURCE +#include +#include +#include +#define BUFLEN 4096 + +int +main(void) +{ + struct group grp, *grpp; + char buf[BUFLEN]; + int i; + + setgrent(); + while (1) { + i = getgrent_r(&grp, buf, BUFLEN, &grpp); + if (i) + break; + printf("%s (%d):", grpp\->gr_name, grpp\->gr_gid); + for (i = 0; ; i++) { + if (grpp\->gr_mem[i] == NULL) + break; + printf(" %s", grpp\->gr_mem[i]); + } + printf("\en"); + } + endgrent(); + exit(EXIT_SUCCESS); +} +.EE +.\" perhaps add error checking - should use strerror_r +.\" #include +.\" #include +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getgrent_r: %s", strerror(i)); +.\" exit(EXIT_FAILURE); +.\" } +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR putgrent (3), +.BR group (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getgrgid.3 b/man3/getgrgid.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man3/getgrgid.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man3/getgrgid_r.3 b/man3/getgrgid_r.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man3/getgrgid_r.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man3/getgrnam.3 b/man3/getgrnam.3 new file mode 100644 index 0000000..e0e8a13 --- /dev/null +++ b/man3/getgrnam.3 @@ -0,0 +1,267 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-11-15 by aeb +.\" +.TH GETGRNAM 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "struct group *getgrnam(const char *" name ); +.PP +.BI "struct group *getgrgid(gid_t " gid ); +.PP +.BI "int getgrnam_r(const char *" name ", struct group *" grp , +.BI " char *" buf ", size_t " buflen ", struct group **" result ); +.PP +.BI "int getgrgid_r(gid_t " gid ", struct group *" grp , +.BI " char *" buf ", size_t " buflen ", struct group **" result ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getgrnam_r (), +.BR getgrgid_r (): +.RS 4 +_POSIX_C_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR getgrnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the group database +(e.g., the local group file +.IR /etc/group , +NIS, and LDAP) +that matches the group name +.IR name . +.PP +The +.BR getgrgid () +function returns a pointer to a structure containing +the broken-out fields of the record in the group database +that matches the group ID +.IR gid . +.PP +The \fIgroup\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL-terminated array of pointers + to names of group members */ +}; +.EE +.in +.PP +For more information about the fields of this structure, see +.BR group (5). +.PP +The +.BR getgrnam_r () +and +.BR getgrgid_r () +functions obtain the same information as +.BR getgrnam () +and +.BR getgrgid (), +but store the retrieved +.I group +structure +in the space pointed to by +.IR grp . +The string fields pointed to by the members of the +.I group +structure are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *result . +.PP +The call +.PP + sysconf(_SC_GETGR_R_SIZE_MAX) +.PP +returns either \-1, without changing +.IR errno , +or an initial suggested size for +.IR buf . +(If this size is too small, +the call fails with +.BR ERANGE , +in which case the caller can retry with a larger buffer.) +.SH RETURN VALUE +The +.BR getgrnam () +and +.BR getgrgid () +functions return a pointer to a +.I group +structure, or NULL if the matching entry +is not found or an error occurs. +If an error occurs, +.I errno +is set appropriately. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.PP +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getgrent (3), +.BR getgrgid (), +or +.BR getgrnam (). +(Do not pass the returned pointer to +.BR free (3).) +.PP +On success, +.BR getgrnam_r () +and +.BR getgrgid_r () +return zero, and set +.IR *result +to +.IR grp . +If no matching group record was found, +these functions return 0 and store NULL in +.IR *result . +In case of error, an error number is returned, and NULL is stored in +.IR *result . +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... " +The given +.I name +or +.I gid +was not found. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I group +structure. +.\" to allocate the group structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +local group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getgrnam () +T} Thread safety MT-Unsafe race:grnam locale +T{ +.BR getgrgid () +T} Thread safety MT-Unsafe race:grgid locale +T{ +.BR getgrnam_r (), +.br +.BR getgrgid_r () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +The formulation given above under "RETURN VALUE" is from POSIX.1. +.\" POSIX.1-2001, POSIX.1-2008 +It does not call "not found" an error, hence does not specify what value +.I errno +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX +.I errno +should be left unchanged if an entry is not found. +Experiments on various +UNIX-like systems show that lots of different values occur in this +situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc up to version 2.6, Irix 6.5 - give ENOENT +.\" glibc since version 2.7 - give 0 +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.SH SEE ALSO +.BR endgrent (3), +.BR fgetgrent (3), +.BR getgrent (3), +.BR getpwnam (3), +.BR setgrent (3), +.BR group (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getgrnam_r.3 b/man3/getgrnam_r.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man3/getgrnam_r.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man3/getgrouplist.3 b/man3/getgrouplist.3 new file mode 100644 index 0000000..9d31595 --- /dev/null +++ b/man3/getgrouplist.3 @@ -0,0 +1,219 @@ +.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" A few pieces remain from an earlier version written in +.\" 2002 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETGROUPLIST 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getgrouplist \- get list of groups to which a user belongs +.SH SYNOPSIS +.B #include +.PP +.BI "int getgrouplist(const char *" user ", gid_t " group , +.br +.BI " gid_t *" groups ", int *" ngroups ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getgrouplist (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The +.BR getgrouplist () +function scans the group database (see +.BR group (5)) +to obtain the list of groups that +.I user +belongs to. +Up to +.I *ngroups +of these groups are returned in the array +.IR groups . +.PP +If it was not among the groups defined for +.I user +in the group database, then +.I group +is included in the list of groups returned by +.BR getgrouplist (); +typically this argument is specified as the group ID from +the password record for +.IR user . +.PP +The +.I ngroups +argument is a value-result argument: +on return it always contains the number of groups found for +.IR user , +including +.IR group ; +this value may be greater than the number of groups stored in +.IR groups . +.SH RETURN VALUE +If the number of groups of which +.I user +is a member is less than or equal to +.IR *ngroups , +then the value +.I *ngroups +is returned. +.PP +If the user is a member of more than +.I *ngroups +groups, then +.BR getgrouplist () +returns \-1. +In this case, the value returned in +.IR *ngroups +can be used to resize the buffer passed to a further call +.BR getgrouplist (). +.SH VERSIONS +This function is present since glibc 2.2.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getgrouplist () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +This function is nonstandard; it appears on most BSDs. +.SH BUGS +In glibc versions before 2.3.3, +the implementation of this function contains a buffer-overrun bug: +it returns the complete list of groups for +.IR user +in the array +.IR groups , +even when the number of groups exceeds +.IR *ngroups . +.SH EXAMPLE +.PP +The program below displays the group list for the user named in its +first command-line argument. +The second command-line argument specifies the +.I ngroups +value to be supplied to +.BR getgrouplist (). +The following shell session shows examples of the use of this program: +.PP +.in +4n +.EX +.RB "$" " ./a.out cecilia 0" +getgrouplist() returned \-1; ngroups = 3 +.RB "$" " ./a.out cecilia 3" +ngroups = 3 +16 (dialout) +33 (video) +100 (users) +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + int j, ngroups; + gid_t *groups; + struct passwd *pw; + struct group *gr; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + ngroups = atoi(argv[2]); + + groups = malloc(ngroups * sizeof (gid_t)); + if (groups == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + + /* Fetch passwd structure (contains first group ID for user) */ + + pw = getpwnam(argv[1]); + if (pw == NULL) { + perror("getpwnam"); + exit(EXIT_SUCCESS); + } + + /* Retrieve group list */ + + if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) { + fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\\n", + ngroups); + exit(EXIT_FAILURE); + } + + /* Display list of retrieved groups, along with group names */ + + fprintf(stderr, "ngroups = %d\\n", ngroups); + for (j = 0; j < ngroups; j++) { + printf("%d", groups[j]); + gr = getgrgid(groups[j]); + if (gr != NULL) + printf(" (%s)", gr\->gr_name); + printf("\\n"); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getgroups (2), +.BR setgroups (2), +.BR getgrent (3), +.BR group_member (3), +.BR group (5), +.BR passwd (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/gethostbyaddr.3 b/man3/gethostbyaddr.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/gethostbyaddr.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostbyaddr_r.3 b/man3/gethostbyaddr_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/gethostbyaddr_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3 new file mode 100644 index 0000000..da687ea --- /dev/null +++ b/man3/gethostbyname.3 @@ -0,0 +1,559 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-05-22, David Metcalfe +.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) +.\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl) +.\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2002-08-05, Michael Kerrisk +.\" Modified 2004-10-31, Andries Brouwer +.\" +.TH GETHOSTBYNAME 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, +h_errno, +herror, hstrerror, +gethostbyaddr_r, +gethostbyname2, gethostbyname2_r, gethostbyname_r, +gethostent_r \- get network host entry +.SH SYNOPSIS +.nf +.B #include +.B extern int h_errno; +.PP +.BI "struct hostent *gethostbyname(const char *" name ); + +.BR "#include " " /* for AF_INET */" +.BI "struct hostent *gethostbyaddr(const void *" addr , +.BI " socklen_t " len ", int " type ); +.PP +.BI "void sethostent(int " stayopen ); +.PP +.B void endhostent(void); +.PP +.BI "void herror(const char *" s ); +.PP +.BI "const char *hstrerror(int " err ); +.PP +/* System V/POSIX extension */ +.B struct hostent *gethostent(void); +.PP +/* GNU extensions */ +.BI "struct hostent *gethostbyname2(const char *" name ", int " af ); +.PP +.B "int gethostent_r(" +.BI " struct hostent *" ret ", char *" buf ", size_t " buflen , +.BI " struct hostent **" result ", int *" h_errnop ); +.PP +.BI "int gethostbyaddr_r(const void *" addr ", socklen_t " len ", int " type , +.BI " struct hostent *" ret ", char *" buf ", size_t " buflen , +.BI " struct hostent **" result ", int *" h_errnop ); +.PP +.BI "int gethostbyname_r(const char *" name , +.BI " struct hostent *" ret ", char *" buf ", size_t " buflen , +.BI " struct hostent **" result ", int *" h_errnop ); +.PP +.BI "int gethostbyname2_r(const char *" name ", int " af, +.BI " struct hostent *" ret ", char *" buf ", size_t " buflen , +.BI " struct hostent **" result ", int *" h_errnop ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.PD 0 +.ad l +.BR gethostbyname2 (), +.BR gethostent_r (), +.BR gethostbyaddr_r (), +.BR gethostbyname_r (), +.BR gethostbyname2_r (): +.RS 4 +.TP 4 +Since glibc 2.19: +_DEFAULT_SOURCE +.TP 4 +Glibc versions up to and including 2.19: +_BSD_SOURCE || _SVID_SOURCE +.RE +.PD +.PP +.PD 0 +.BR herror (), +.BR hstrerror (): +.RS 4 +.TP 4 +Since glibc 2.19: +_DEFAULT_SOURCE +.TP 4 +Glibc 2.8 to 2.19: +_BSD_SOURCE || _SVID_SOURCE +.TP +Before glibc 2.8: +none +.RE +.PD +.PP +.PD 0 +.BR h_errno : +.RS 4 +.TP 4 +Since glibc 2.19 +_DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L +.TP 4 +Glibc 2.12 to 2.19: +_BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L +.TP +Before glibc 2.12: +none +.RE +.ad b +.PD +.SH DESCRIPTION +The +.BR gethostbyname* (), +.BR gethostbyaddr* (), +.BR herror (), +and +.BR hstrerror () +functions are obsolete. +Applications should use +.BR getaddrinfo (3), +.BR getnameinfo (3), +and +.BR gai_strerror (3) +instead. +.PP +The +.BR gethostbyname () +function returns a structure of type +.I hostent +for the given host +.IR name . +Here +.I name +is either a hostname or an IPv4 address in standard dot notation (as for +.BR inet_addr (3)). +If +.I name +is an IPv4 address, no lookup is performed and +.BR gethostbyname () +simply copies +.I name +into the +.I h_name +field and its +.I struct in_addr +equivalent into the +.I h_addr_list[0] +field of the returned +.I hostent +structure. +If +.I name +doesn't end in a dot and the environment variable +.B HOSTALIASES +is set, the alias file pointed to by +.B HOSTALIASES +will first be searched for +.I name +(see +.BR hostname (7) +for the file format). +The current domain and its parents are searched unless \fIname\fP +ends in a dot. +.PP +The +.BR gethostbyaddr () +function returns a structure of type \fIhostent\fP +for the given host address \fIaddr\fP of length \fIlen\fP and address type +\fItype\fP. +Valid address types are +.B AF_INET +and +.BR AF_INET6 . +The host address argument is a pointer to a struct of a type depending +on the address type, for example a \fIstruct in_addr *\fP (probably +obtained via a call to +.BR inet_addr (3)) +for address type +.BR AF_INET . +.PP +The +.BR sethostent () +function specifies, if \fIstayopen\fP is true (1), +that a connected TCP socket should be used for the name server queries and +that the connection should remain open during successive queries. +Otherwise, name server queries will use UDP datagrams. +.PP +The +.BR endhostent () +function ends the use of a TCP connection for name +server queries. +.PP +The (obsolete) +.BR herror () +function prints the error message associated +with the current value of \fIh_errno\fP on \fIstderr\fP. +.PP +The (obsolete) +.BR hstrerror () +function takes an error number +(typically \fIh_errno\fP) and returns the corresponding message string. +.PP +The domain name queries carried out by +.BR gethostbyname () +and +.BR gethostbyaddr () +rely on the Name Service Switch +.RB ( nsswitch.conf (5)) +configured sources or a local name server +.RB ( named (8)). +The default action is to query the Name Service Switch +.RB ( nsswitch.conf(5)) +configured sources, failing that, a local name server +.RB ( named (8)). +.\" +.SS Historical +The +.BR nsswitch.conf (5) +file is the modern way of controlling the order of host lookups. +.PP +In glibc 2.4 and earlier, the +.I order +keyword was used to control the order of host lookups as defined in +.IR /etc/host.conf +.RB ( host.conf (5)). +.PP +.PP +The \fIhostent\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses */ +} +#define h_addr h_addr_list[0] /* for backward compatibility */ +.EE +.in +.PP +The members of the \fIhostent\fP structure are: +.TP +.I h_name +The official name of the host. +.TP +.I h_aliases +An array of alternative names for the host, terminated by a null pointer. +.TP +.I h_addrtype +The type of address; always +.B AF_INET +or +.B AF_INET6 +at present. +.TP +.I h_length +The length of the address in bytes. +.TP +.I h_addr_list +An array of pointers to network addresses for the host (in network byte +order), terminated by a null pointer. +.TP +.I h_addr +The first address in \fIh_addr_list\fP for backward compatibility. +.SH RETURN VALUE +The +.BR gethostbyname () +and +.BR gethostbyaddr () +functions return the +.I hostent +structure or a null pointer if an error occurs. +On error, the +.I h_errno +variable holds an error number. +When non-NULL, the return value may point at static data, see the notes below. +.SH ERRORS +The variable \fIh_errno\fP can have the following values: +.TP +.B HOST_NOT_FOUND +The specified host is unknown. +.TP +.BR NO_DATA +The requested name is valid but does not have an IP address. +Another type of request to the name server for this domain +may return an answer. +The constant +.BR NO_ADDRESS +is a synonym for +.BR NO_DATA . +.TP +.B NO_RECOVERY +A nonrecoverable name server error occurred. +.TP +.B TRY_AGAIN +A temporary error occurred on an authoritative name server. +Try again later. +.SH FILES +.TP +.I /etc/host.conf +resolver configuration file +.TP +.I /etc/hosts +host database file +.TP +.I /etc/nsswitch.conf +name service switch configuration +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw18 lb lbw29 +l l l. +Interface Attribute Value +T{ +.BR gethostbyname () +T} Thread safety T{ +MT-Unsafe race:hostbyname env +.br +locale +T} +T{ +.BR gethostbyaddr () +T} Thread safety T{ +MT-Unsafe race:hostbyaddr env +.br +locale +T} +T{ +.BR sethostent (), +.br +.BR endhostent (), +.br +.BR gethostent_r () +T} Thread safety T{ +MT-Unsafe race:hostent env +.br +locale +T} +T{ +.BR herror (), +.br +.BR hstrerror () +T} Thread safety MT-Safe +T{ +.BR gethostent () +T} Thread safety T{ +MT-Unsafe race:hostent +.br +race:hostentbuf env locale +T} +T{ +.BR gethostbyname2 () +T} Thread safety T{ +MT-Unsafe race:hostbyname2 +.br +env locale +T} +T{ +.BR gethostbyaddr_r (), +.BR gethostbyname_r (), +.BR gethostbyname2_r () +T} Thread safety MT-Safe env locale +.TE +.sp 1 +In the above table, +.I hostent +in +.I race:hostent +signifies that if any of the functions +.BR sethostent (), +.BR gethostent (), +.BR gethostent_r (), +or +.BR endhostent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +POSIX.1-2001 specifies +.BR gethostbyname (), +.BR gethostbyaddr (), +.BR sethostent (), +.BR endhostent (), +.BR gethostent (), +and +.IR h_errno ; +.BR gethostbyname (), +.BR gethostbyaddr (), +and +.IR h_errno +are marked obsolescent in that standard. +POSIX.1-2008 removes the specifications of +.BR gethostbyname (), +.BR gethostbyaddr (), +and +.IR h_errno , +recommending the use of +.BR getaddrinfo (3) +and +.BR getnameinfo (3) +instead. +.SH NOTES +The functions +.BR gethostbyname () +and +.BR gethostbyaddr () +may return pointers to static data, which may be overwritten by +later calls. +Copying the +.I struct hostent +does not suffice, since it contains pointers; a deep copy is required. +.PP +In the original BSD implementation the +.I len +argument +of +.BR gethostbyname () +was an +.IR int . +The SUSv2 standard is buggy and declares the +.I len +argument of +.BR gethostbyaddr () +to be of type +.IR size_t . +(That is wrong, because it has to be +.IR int , +and +.I size_t +is not. +POSIX.1-2001 makes it +.IR socklen_t , +which is OK.) +See also +.BR accept (2). +.PP +The BSD prototype for +.BR gethostbyaddr () +uses +.I "const char\ *" +for the first argument. +.SS System V/POSIX extension +POSIX requires the +.BR gethostent () +call, which should return the next entry in the host data base. +When using DNS/BIND this does not make much sense, but it may +be reasonable if the host data base is a file that can be read +line by line. +On many systems, a routine of this name reads +from the file +.IR /etc/hosts . +.\" e.g., Linux, FreeBSD, UnixWare, HP-UX +It may be available only when the library was built without DNS support. +.\" e.g., FreeBSD, AIX +The glibc version will ignore ipv6 entries. +This function is not reentrant, +and glibc adds a reentrant version +.BR gethostent_r (). +.SS GNU extensions +Glibc2 also has a +.BR gethostbyname2 () +that works like +.BR gethostbyname (), +but permits to specify the address family to which the address must belong. +.PP +Glibc2 also has reentrant versions +.BR gethostent_r (), +.BR gethostbyaddr_r (), +.BR gethostbyname_r () +and +.BR gethostbyname2_r (). +The caller supplies a +.I hostent +structure +.I ret +which will be filled in on success, and a temporary work buffer +.I buf +of size +.IR buflen . +After the call, +.I result +will point to the result on success. +In case of an error +or if no entry is found +.I result +will be NULL. +The functions return 0 on success and a nonzero error number on failure. +In addition to the errors returned by the nonreentrant +versions of these functions, if +.I buf +is too small, the functions will return +.BR ERANGE , +and the call should be retried with a larger buffer. +The global variable +.I h_errno +is not modified, but the address of a variable in which to store error numbers +is passed in +.IR h_errnop . +.SH BUGS +.BR gethostbyname () +does not recognize components of a dotted IPv4 address string +that are expressed in hexadecimal. +.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973 +.SH SEE ALSO +.BR getaddrinfo (3), +.\" .BR getipnodebyaddr (3), +.\" .BR getipnodebyname (3), +.BR getnameinfo (3), +.BR inet (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR resolver (3), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR hostname (7), +.BR named (8) +.\" .BR resolv+ (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/gethostbyname2.3 b/man3/gethostbyname2.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/gethostbyname2.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostbyname2_r.3 b/man3/gethostbyname2_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/gethostbyname2_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostbyname_r.3 b/man3/gethostbyname_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/gethostbyname_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostent.3 b/man3/gethostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/gethostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostent_r.3 b/man3/gethostent_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/gethostent_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/gethostid.3 b/man3/gethostid.3 new file mode 100644 index 0000000..96aeeb9 --- /dev/null +++ b/man3/gethostid.3 @@ -0,0 +1,158 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Updated with additions from Mitchum DSouza +.\" Portions Copyright 1993 Mitchum DSouza +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.TH GETHOSTID 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +gethostid, sethostid \- get or set the unique identifier of the current host +.SH SYNOPSIS +.B #include +.PP +.B long gethostid(void); +.br +.BI "int sethostid(long " hostid ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.br +.BR gethostid (): +.RS 4 +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.RE +.BR sethostid (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.fi +.ad b +.SH DESCRIPTION +.BR gethostid () +and +.BR sethostid () +respectively get or set a unique 32-bit identifier for the current machine. +The 32-bit identifier is intended to be unique among all UNIX systems in +existence. +This normally resembles the Internet address for the local +machine, as returned by +.BR gethostbyname (3), +and thus usually never needs to be set. +.PP +The +.BR sethostid () +call is restricted to the superuser. +.SH RETURN VALUE +.BR gethostid () +returns the 32-bit identifier for the current host as set by +.BR sethostid (). +.PP +On success, +.BR sethostid () +returns 0; on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR sethostid () +can fail with the following errors: +.TP +.B EACCES +The caller did not have permission to write to the file used +to store the host ID. +.TP +.B EPERM +The calling process's effective user or group ID is not the same +as its corresponding real ID. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw25 +l l l. +Interface Attribute Value +T{ +.BR gethostid () +T} Thread safety MT-Safe hostid env locale +T{ +.BR sethostid () +T} Thread safety MT-Unsafe const:hostid +.TE +.sp 1 +.SH CONFORMING TO +4.2BSD; these functions were dropped in 4.4BSD. +SVr4 includes +.BR gethostid () +but not +.BR sethostid (). +.PP +POSIX.1-2001 and POSIX.1-2008 specify +.BR gethostid () +but not +.BR sethostid (). +.SH NOTES +In the glibc implementation, the +.I hostid +is stored in the file +.IR /etc/hostid . +(In glibc versions before 2.2, the file +.I /var/adm/hostid +was used.) +.\" libc5 used /etc/hostid; libc4 didn't have these functions +.PP +In the glibc implementation, if +.BR gethostid () +cannot open the file containing the host ID, +then it obtains the hostname using +.BR gethostname (2), +passes that hostname to +.BR gethostbyname_r (3) +in order to obtain the host's IPv4 address, +and returns a value obtained by bit-twiddling the IPv4 address. +(This value may not be unique.) +.SH BUGS +It is impossible to ensure that the identifier is globally unique. +.SH SEE ALSO +.BR hostid (1), +.BR gethostbyname (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getifaddrs.3 b/man3/getifaddrs.3 new file mode 100644 index 0000000..a8c70bd --- /dev/null +++ b/man3/getifaddrs.3 @@ -0,0 +1,337 @@ +.\" Copyright (c) 2008 Petr Baudis +.\" and copyright (c) 2009, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 2008-12-08 Petr Baudis +.\" Rewrite the BSD manpage in the Linux man pages style and account +.\" for glibc specificities, provide an example. +.\" 2009-01-14 mtk, many edits and changes, rewrote example program. +.\" +.TH GETIFADDRS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getifaddrs, freeifaddrs \- get interface addresses +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int getifaddrs(struct ifaddrs **" "ifap" ); +.PP +.BI "void freeifaddrs(struct ifaddrs *" "ifa" ); +.fi +.SH DESCRIPTION +The +.BR getifaddrs () +function creates a linked list of structures describing +the network interfaces of the local system, +and stores the address of the first item of the list in +.IR *ifap . +The list consists of +.I ifaddrs +structures, defined as follows: +.PP +.in +4n +.EX +struct ifaddrs { + struct ifaddrs *ifa_next; /* Next item in list */ + char *ifa_name; /* Name of interface */ + unsigned int ifa_flags; /* Flags from SIOCGIFFLAGS */ + struct sockaddr *ifa_addr; /* Address of interface */ + struct sockaddr *ifa_netmask; /* Netmask of interface */ + union { + struct sockaddr *ifu_broadaddr; + /* Broadcast address of interface */ + struct sockaddr *ifu_dstaddr; + /* Point-to-point destination address */ + } ifa_ifu; +#define ifa_broadaddr ifa_ifu.ifu_broadaddr +#define ifa_dstaddr ifa_ifu.ifu_dstaddr + void *ifa_data; /* Address-specific data */ +}; +.EE +.in +.PP +The +.I ifa_next +field contains a pointer to the next structure on the list, +or NULL if this is the last item of the list. +.PP +The +.I ifa_name +points to the null-terminated interface name. +.\" The constant +.\" .B IF NAMESIZE +.\" indicates the maximum length of this field. +.PP +The +.I ifa_flags +field contains the interface flags, as returned by the +.B SIOCGIFFLAGS +.BR ioctl (2) +operation (see +.BR netdevice (7) +for a list of these flags). +.PP +The +.I ifa_addr +field points to a structure containing the interface address. +(The +.I sa_family +subfield should be consulted to determine the format of the +address structure.) +This field may contain a null pointer. +.PP +The +.I ifa_netmask +field points to a structure containing the netmask associated with +.IR ifa_addr , +if applicable for the address family. +This field may contain a null pointer. +.PP +Depending on whether the bit +.B IFF_BROADCAST +or +.B IFF_POINTOPOINT +is set in +.I ifa_flags +(only one can be set at a time), +either +.I ifa_broadaddr +will contain the broadcast address associated with +.I ifa_addr +(if applicable for the address family) or +.I ifa_dstaddr +will contain the destination address of the point-to-point interface. +.PP +The +.I ifa_data +field points to a buffer containing address-family-specific data; +this field may be NULL if there is no such data for this interface. +.PP +The data returned by +.BR getifaddrs () +is dynamically allocated and should be freed using +.BR freeifaddrs () +when no longer needed. +.SH RETURN VALUE +On success, +.BR getifaddrs () +returns zero; +on error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.BR getifaddrs () +may fail and set +.I errno +for any of the errors specified for +.BR socket (2), +.BR bind (2), +.BR getsockname (2), +.BR recvmsg (2), +.BR sendto (2), +.BR malloc (3), +or +.BR realloc (3). +.SH VERSIONS +The +.BR getifaddrs () +function first appeared in glibc 2.3, but before glibc 2.3.3, +the implementation supported only IPv4 addresses; +IPv6 support was added in glibc 2.3.3. +Support of address families other than IPv4 is available only +on kernels that support netlink. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR getifaddrs (), +.BR freeifaddrs () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +Not in POSIX.1. +This function first appeared in BSDi and is +present on the BSD systems, but with slightly different +semantics documented\(emreturning one entry per interface, +not per address. +This means +.I ifa_addr +and other fields can actually be NULL if the interface has no address, +and no link-level address is returned if the interface has an IP address +assigned. +Also, the way of choosing either +.I ifa_broadaddr +or +.I ifa_dstaddr +differs on various systems. +.\" , but the BSD-derived documentation generally +.\" appears to be confused and obsolete on this point. +.\" i.e., commonly it still says one of them will be NULL, even if +.\" the ifa_ifu union is already present +.SH NOTES +The addresses returned on Linux will usually be the IPv4 and IPv6 addresses +assigned to the interface, but also one +.B AF_PACKET +address per interface containing lower-level details about the interface +and its physical layer. +In this case, the +.I ifa_data +field may contain a pointer to a +.IR "struct rtnl_link_stats" , +defined in +.IR +(in Linux 2.4 and earlier, +.IR "struct net_device_stats" , +defined in +.IR ), +which contains various interface attributes and statistics. +.SH EXAMPLE +The program below demonstrates the use of +.BR getifaddrs (), +.BR freeifaddrs (), +and +.BR getnameinfo (3). +Here is what we see when running this program on one system: +.PP +.in +4n +.EX +$ \fB./a.out\fP +lo AF_PACKET (17) + tx_packets = 524; rx_packets = 524 + tx_bytes = 38788; rx_bytes = 38788 +wlp3s0 AF_PACKET (17) + tx_packets = 108391; rx_packets = 130245 + tx_bytes = 30420659; rx_bytes = 94230014 +em1 AF_PACKET (17) + tx_packets = 0; rx_packets = 0 + tx_bytes = 0; rx_bytes = 0 +lo AF_INET (2) + address: <127.0.0.1> +wlp3s0 AF_INET (2) + address: <192.168.235.137> +lo AF_INET6 (10) + address: <::1> +wlp3s0 AF_INET6 (10) + address: +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE /* To get defns of NI_MAXSERV and NI_MAXHOST */ +#include +#include +#include +#include +#include +#include +#include +#include + +int main(int argc, char *argv[]) +{ + struct ifaddrs *ifaddr, *ifa; + int family, s, n; + char host[NI_MAXHOST]; + + if (getifaddrs(&ifaddr) == \-1) { + perror("getifaddrs"); + exit(EXIT_FAILURE); + } + + /* Walk through linked list, maintaining head pointer so we + can free list later */ + + for (ifa = ifaddr, n = 0; ifa != NULL; ifa = ifa\->ifa_next, n++) { + if (ifa\->ifa_addr == NULL) + continue; + + family = ifa\->ifa_addr\->sa_family; + + /* Display interface name and family (including symbolic + form of the latter for the common families) */ + + printf("%\-8s %s (%d)\\n", + ifa\->ifa_name, + (family == AF_PACKET) ? "AF_PACKET" : + (family == AF_INET) ? "AF_INET" : + (family == AF_INET6) ? "AF_INET6" : "???", + family); + + /* For an AF_INET* interface address, display the address */ + + if (family == AF_INET || family == AF_INET6) { + s = getnameinfo(ifa\->ifa_addr, + (family == AF_INET) ? sizeof(struct sockaddr_in) : + sizeof(struct sockaddr_in6), + host, NI_MAXHOST, + NULL, 0, NI_NUMERICHOST); + if (s != 0) { + printf("getnameinfo() failed: %s\\n", gai_strerror(s)); + exit(EXIT_FAILURE); + } + + printf("\\t\\taddress: <%s>\\n", host); + + } else if (family == AF_PACKET && ifa\->ifa_data != NULL) { + struct rtnl_link_stats *stats = ifa\->ifa_data; + + printf("\\t\\ttx_packets = %10u; rx_packets = %10u\\n" + "\\t\\ttx_bytes = %10u; rx_bytes = %10u\\n", + stats\->tx_packets, stats\->rx_packets, + stats\->tx_bytes, stats\->rx_bytes); + } + } + + freeifaddrs(ifaddr); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bind (2), +.BR getsockname (2), +.BR socket (2), +.BR packet (7), +.BR ifconfig (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getipnodebyaddr.3 b/man3/getipnodebyaddr.3 new file mode 100644 index 0000000..82e01df --- /dev/null +++ b/man3/getipnodebyaddr.3 @@ -0,0 +1 @@ +.so man3/getipnodebyname.3 diff --git a/man3/getipnodebyname.3 b/man3/getipnodebyname.3 new file mode 100644 index 0000000..82354bb --- /dev/null +++ b/man3/getipnodebyname.3 @@ -0,0 +1,279 @@ +.\" Copyright 2000 Sam Varshavchik +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References: RFC 2553 +.TH GETIPNODEBYNAME 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getipnodebyname, getipnodebyaddr, freehostent \- get network +hostnames and addresses +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "struct hostent *getipnodebyname(const char *" name ", int " af , +.BI " int " flags ", int *" error_num ); +.PP +.BI "struct hostent *getipnodebyaddr(const void *" addr ", size_t " len , +.BI " int " af ", int *" "error_num" ); +.PP +.BI "void freehostent(struct hostent *" "ip" ); +.fi +.SH DESCRIPTION +These functions are deprecated (and unavailable in glibc). +Use +.BR getaddrinfo (3) +and +.BR getnameinfo (3) +instead. +.PP +The +.BR getipnodebyname () +and +.BR getipnodebyaddr () +functions return the names and addresses of a network host. +These functions return a pointer to the +following structure: +.PP +.in +4n +.EX +struct hostent { + char *h_name; + char **h_aliases; + int h_addrtype; + int h_length; + char **h_addr_list; +}; +.EE +.in +.PP +These functions replace the +.BR gethostbyname (3) +and +.BR gethostbyaddr (3) +functions, which could access only the IPv4 network address family. +The +.BR getipnodebyname () +and +.BR getipnodebyaddr () +functions can access multiple network address families. +.PP +Unlike the +.B gethostby +functions, +these functions return pointers to dynamically allocated memory. +The +.BR freehostent () +function is used to release the dynamically allocated memory +after the caller no longer needs the +.I hostent +structure. +.SS getipnodebyname() arguments +The +.BR getipnodebyname () +function +looks up network addresses for the host +specified by the +.I name +argument. +The +.I af +argument specifies one of the following values: +.TP +.B AF_INET +The +.I name +argument points to a dotted-quad IPv4 address or a name +of an IPv4 network host. +.TP +.B AF_INET6 +The +.I name +argument points to a hexadecimal IPv6 address or a name +of an IPv6 network host. +.PP +The +.I flags +argument specifies additional options. +More than one option can be specified by bitwise OR-ing +them together. +.I flags +should be set to 0 +if no options are desired. +.TP +.B AI_V4MAPPED +This flag is used with +.B AF_INET6 +to request a query for IPv4 addresses instead of +IPv6 addresses; the IPv4 addresses will +be mapped to IPv6 addresses. +.TP +.B AI_ALL +This flag is used with +.B AI_V4MAPPED +to request a query for both IPv4 and IPv6 addresses. +Any IPv4 address found will be mapped to an IPv6 address. +.TP +.B AI_ADDRCONFIG +This flag is used with +.B AF_INET6 +to +further request that queries for IPv6 addresses should not be made unless +the system has at least one IPv6 address assigned to a network interface, +and that queries for IPv4 addresses should not be made unless the +system has at least one IPv4 address assigned to a network interface. +This flag may be used by itself or with the +.B AI_V4MAPPED +flag. +.TP +.B AI_DEFAULT +This flag is equivalent to +.BR "(AI_ADDRCONFIG | AI_V4MAPPED)" . +.SS getipnodebyaddr() arguments +The +.BR getipnodebyaddr () +function +looks up the name of the host whose +network address is +specified by the +.I addr +argument. +The +.I af +argument specifies one of the following values: +.TP +.B AF_INET +The +.I addr +argument points to a +.I struct in_addr +and +.I len +must be set to +.IR "sizeof(struct in_addr)" . +.TP +.B AF_INET6 +The +.I addr +argument points to a +.I struct in6_addr +and +.I len +must be set to +.IR "sizeof(struct in6_addr)" . +.SH RETURN VALUE +NULL is returned if an error occurred, and +.I error_num +will contain an error code from the following list: +.TP +.B HOST_NOT_FOUND +The hostname or network address was not found. +.TP +.B NO_ADDRESS +The domain name server recognized the network address or name, +but no answer was returned. +This can happen if the network host has only IPv4 addresses and +a request has been made for IPv6 information only, or vice versa. +.TP +.B NO_RECOVERY +The domain name server returned a permanent failure response. +.TP +.B TRY_AGAIN +The domain name server returned a temporary failure response. +You might have better luck next time. +.PP +A successful query returns a pointer to a +.I hostent +structure that contains the following fields: +.TP +.I h_name +This is the official name of this network host. +.TP +.I h_aliases +This is an array of pointers to unofficial aliases for the same host. +The array is terminated by a null pointer. +.TP +.I h_addrtype +This is a copy of the +.I af +argument to +.BR getipnodebyname () +or +.BR getipnodebyaddr (). +.I h_addrtype +will always be +.B AF_INET +if the +.I af +argument was +.BR AF_INET . +.I h_addrtype +will always be +.B AF_INET6 +if the +.I af +argument was +.BR AF_INET6 . +.TP +.I h_length +This field will be set to +.I sizeof(struct in_addr) +if +.I h_addrtype +is +.BR AF_INET , +and to +.I sizeof(struct in6_addr) +if +.I h_addrtype +is +.BR AF_INET6 . +.TP +.I h_addr_list +This is an array of one or more pointers to network address structures for the +network host. +The array is terminated by a null pointer. +.SH CONFORMING TO +RFC\ 2553. +.\" Not in POSIX.1-2001. +.SH NOTES +These functions were present in glibc 2.1.91-95, but were +removed again. +Several UNIX-like systems support them, but all +call them deprecated. +.SH SEE ALSO +.BR getaddrinfo (3), +.BR getnameinfo (3), +.BR inet_ntop (3), +.BR inet_pton (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getline.3 b/man3/getline.3 new file mode 100644 index 0000000..0b42764 --- /dev/null +++ b/man3/getline.3 @@ -0,0 +1,210 @@ +.\" Copyright (c) 2001 John Levon +.\" Based in part on GNU libc documentation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETLINE 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getline, getdelim \- delimited string input +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "ssize_t getline(char **" lineptr ", size_t *" n ", FILE *" stream ); +.PP +.BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim \ +", FILE *" stream ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR getline (), +.BR getdelim (): +.PD 0 +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.ad +.SH DESCRIPTION +.BR getline () +reads an entire line from \fIstream\fP, +storing the address of the buffer containing the text into +.IR "*lineptr" . +The buffer is null-terminated and includes the newline character, if +one was found. +.PP +If +.I "*lineptr" +is set to NULL and +.I *n +is set 0 before the call, then +.BR getline () +will allocate a buffer for storing the line. +This buffer should be freed by the user program +even if +.BR getline () +failed. +.PP +Alternatively, before calling +.BR getline (), +.I "*lineptr" +can contain a pointer to a +.BR malloc (3)\-allocated +buffer +.I "*n" +bytes in size. +If the buffer is not large enough to hold the line, +.BR getline () +resizes it with +.BR realloc (3), +updating +.I "*lineptr" +and +.I "*n" +as necessary. +.PP +In either case, on a successful call, +.I "*lineptr" +and +.I "*n" +will be updated to reflect the buffer address and allocated size respectively. +.PP +.BR getdelim () +works like +.BR getline (), +except that a line delimiter other than newline can be specified as the +.I delimiter +argument. +As with +.BR getline (), +a delimiter character is not added if one was not present +in the input before end of file was reached. +.SH RETURN VALUE +On success, +.BR getline () +and +.BR getdelim () +return the number of characters read, including the delimiter character, +but not including the terminating null byte (\(aq\\0\(aq). +This value can be used +to handle embedded null bytes in the line read. +.PP +Both functions return \-1 on failure to read a line (including end-of-file +condition). +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +.TP +.B EINVAL +Bad arguments +.RI ( n +or +.I lineptr +is NULL, or +.I stream +is not valid). +.TP +.B ENOMEM +Allocation or reallocation of the line buffer failed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR getline (), +.BR getdelim () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +Both +.BR getline () +and +.BR getdelim () +were originally GNU extensions. +They were standardized in POSIX.1-2008. +.SH EXAMPLE +.EX +#define _GNU_SOURCE +#include +#include + +int +main(int argc, char *argv[]) +{ + FILE *stream; + char *line = NULL; + size_t len = 0; + ssize_t nread; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } + + stream = fopen(argv[1], "r"); + if (stream == NULL) { + perror("fopen"); + exit(EXIT_FAILURE); + } + + while ((nread = getline(&line, &len, stream)) != \-1) { + printf("Retrieved line of length %zu:\en", nread); + fwrite(line, nread, 1, stdout); + } + + free(line); + fclose(stream); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR read (2), +.BR fgets (3), +.BR fopen (3), +.BR fread (3), +.BR scanf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getloadavg.3 b/man3/getloadavg.3 new file mode 100644 index 0000000..7e1b6ea --- /dev/null +++ b/man3/getloadavg.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)getloadavg.3 8.1 (Berkeley) 6/4/93 +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH GETLOADAVG 3 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getloadavg \- get system load averages +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getloadavg(double " loadavg[] ", int " nelem ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getloadavg (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR getloadavg () +function returns the number of processes in the system run queue +averaged over various periods of time. +Up to +.I nelem +samples are retrieved and assigned to successive elements of +.IR loadavg []. +The system imposes a maximum of 3 samples, representing averages +over the last 1, 5, and 15 minutes, respectively. +.SH RETURN VALUE +If the load average was unobtainable, \-1 is returned; otherwise, +the number of samples actually retrieved is returned. +.\" .SH HISTORY +.\" The +.\" BR getloadavg () +.\" function appeared in +.\" 4.3BSD Reno . +.SH VERSIONS +This function is available in glibc since version 2.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getloadavg () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs and Solaris. +.\" mdoc seems to have a bug - there must be no newline here +.SH SEE ALSO +.BR uptime (1), +.BR proc (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getlogin.3 b/man3/getlogin.3 new file mode 100644 index 0000000..7e7ca33 --- /dev/null +++ b/man3/getlogin.3 @@ -0,0 +1,258 @@ +.\" Copyright 1995 James R. Van Zandt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3 +.\" added ref to /etc/utmp, added BUGS section, etc. +.\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use +.TH GETLOGIN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getlogin, getlogin_r, cuserid \- get username +.SH SYNOPSIS +.B #include +.PP +.B "char *getlogin(void);" +.br +.BI "int getlogin_r(char *" buf ", size_t " bufsize ); +.PP +.B #include +.PP +.BI "char *cuserid(char *" string ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getlogin_r (): +.\" Deprecated: _REENTRANT || +_POSIX_C_SOURCE\ >=\ 199506L +.PP +.BR cuserid (): +.nf + Since glibc 2.24: + (_XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || __GNU_SOURCE + Up to and including glibc 2.23: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +.BR getlogin () +returns a pointer to a string containing the name of +the user logged in on the controlling terminal of the process, or a +null pointer if this information cannot be determined. +The string is +statically allocated and might be overwritten on subsequent calls to +this function or to +.BR cuserid (). +.PP +.BR getlogin_r () +returns this same username in the array +.I buf +of size +.IR bufsize . +.PP +.BR cuserid () +returns a pointer to a string containing a username +associated with the effective user ID of the process. +If \fIstring\fP +is not a null pointer, it should be an array that can hold at least +\fBL_cuserid\fP characters; the string is returned in this array. +Otherwise, a pointer to a string in a static area is returned. +This +string is statically allocated and might be overwritten on subsequent +calls to this function or to +.BR getlogin (). +.PP +The macro \fBL_cuserid\fP is an integer constant that indicates how +long an array you might need to store a username. +\fBL_cuserid\fP is declared in \fI\fP. +.PP +These functions let your program identify positively the user who is +running +.RB ( cuserid ()) +or the user who logged in this session +.RB ( getlogin ()). +(These can differ when set-user-ID programs are involved.) +.PP +For most purposes, it is more useful to use the environment variable +\fBLOGNAME\fP to find out who the user is. +This is more flexible +precisely because the user can set \fBLOGNAME\fP arbitrarily. +.SH RETURN VALUE +.BR getlogin () +returns a pointer to the username when successful, +and NULL on failure, with +.I errno +set to indicate the cause of the error. +.BR getlogin_r () +returns 0 when successful, and nonzero on failure. +.SH ERRORS +POSIX specifies +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENXIO +The calling process has no controlling terminal. +.TP +.B ERANGE +(getlogin_r) +The length of the username, including the terminating null byte (\(aq\\0\(aq), +is larger than +.IR bufsize . +.PP +Linux/glibc also has +.TP +.B ENOENT +There was no corresponding entry in the utmp-file. +.TP +.B ENOMEM +Insufficient memory to allocate passwd structure. +.TP +.B ENOTTY +Standard input didn't refer to a terminal. +(See BUGS.) +.SH FILES +.TP +\fI/etc/passwd\fP +password database file +.TP +\fI/var/run/utmp\fP +(traditionally \fI/etc/utmp\fP; +some libc versions used \fI/var/adm/utmp\fP) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getlogin () +T} Thread safety T{ +MT-Unsafe race:getlogin race:utent +.br +sig:ALRM timer locale +T} +T{ +.BR getlogin_r () +T} Thread safety T{ +MT-Unsafe race:utent sig:ALRM timer +.br +locale +T} +T{ +.BR cuserid () +T} Thread safety MT-Unsafe race:cuserid/!string locale +.TE +.sp 1 +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR getlogin () +and +.BR getlogin_r () +call those functions, +so we use race:utent to remind users. +.SH CONFORMING TO +.BR getlogin () +and +.BR getlogin_r (): +POSIX.1-2001, POSIX.1-2008. +.PP +System V has a +.BR cuserid () +function which uses the real +user ID rather than the effective user ID. +The +.BR cuserid () +function +was included in the 1988 version of POSIX, +but removed from the 1990 version. +It was present in SUSv2, but removed in POSIX.1-2001. +.PP +OpenBSD has +.BR getlogin () +and +.BR setlogin (), +and a username +associated with a session, even if it has no controlling terminal. +.SH BUGS +Unfortunately, it is often rather easy to fool +.BR getlogin (). +Sometimes it does not work at all, because some program messed up +the utmp file. +Often, it gives only the first 8 characters of +the login name. +The user currently logged in on the controlling terminal +of our program need not be the user who started it. +Avoid +.BR getlogin () +for security-related purposes. +.PP +Note that glibc does not follow the POSIX specification and uses +.I stdin +instead of +.IR /dev/tty . +A bug. +(Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8 +all return the login name also when +.I stdin +is redirected.) +.PP +Nobody knows precisely what +.BR cuserid () +does; avoid it in portable programs. +Or avoid it altogether: use +.I getpwuid(geteuid()) +instead, if that is +what you meant. +.B Do not use +.BR cuserid (). +.SH SEE ALSO +.BR logname (1), +.BR geteuid (2), +.BR getuid (2), +.BR utmp (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getlogin_r.3 b/man3/getlogin_r.3 new file mode 100644 index 0000000..b6d53bf --- /dev/null +++ b/man3/getlogin_r.3 @@ -0,0 +1 @@ +.so man3/getlogin.3 diff --git a/man3/getmntent.3 b/man3/getmntent.3 new file mode 100644 index 0000000..f3ff061 --- /dev/null +++ b/man3/getmntent.3 @@ -0,0 +1,265 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:46:57 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 961109, 031115, aeb +.\" +.TH GETMNTENT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +getmntent, setmntent, addmntent, endmntent, hasmntopt, +getmntent_r \- get filesystem descriptor file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "FILE *setmntent(const char *" filename ", const char *" type ); +.PP +.BI "struct mntent *getmntent(FILE *" stream ); +.PP +.BI "int addmntent(FILE *" stream ", const struct mntent *" mnt ); +.PP +.BI "int endmntent(FILE *" streamp ); +.PP +.BI "char *hasmntopt(const struct mntent *" mnt ", const char *" opt ); + +/* GNU extension */ +.B #include +.PP +.BI "struct mntent *getmntent_r(FILE *" streamp ", struct mntent *" mntbuf , +.BI " char *" buf ", int " buflen ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getmntent_r (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +These routines are used to access the filesystem description file +.I /etc/fstab +and the mounted filesystem description file +.IR /etc/mtab . +.PP +The +.BR setmntent () +function opens the filesystem description file +.I filename +and returns a file pointer which can be used by +.BR getmntent (). +The argument +.I type +is the type of access +required and can take the same values as the +.I mode +argument of +.BR fopen (3). +.PP +The +.BR getmntent () +function reads the next line of the filesystem +description file from +.I stream +and returns a pointer to a structure +containing the broken out fields from a line in the file. +The pointer +points to a static area of memory which is overwritten by subsequent +calls to +.BR getmntent (). +.PP +The +.BR addmntent () +function adds the +.I mntent +structure +.I mnt +to +the end of the open +.IR stream . +.PP +The +.BR endmntent () +function closes the +.IR stream +associated with the filesystem description file. +.PP +The +.BR hasmntopt () +function scans the +.I mnt_opts +field (see below) +of the +.I mntent +structure +.I mnt +for a substring that matches +.IR opt . +See +.I +and +.BR mount (8) +for valid mount options. +.PP +The reentrant +.BR getmntent_r () +function is similar to +.BR getmntent (), +but stores the +.IR "struct mount" +in the provided +.I *mntbuf +and stores the strings pointed to by the entries in that struct +in the provided array +.I buf +of size +.IR buflen . +.PP +The +.I mntent +structure is defined in +.I +as follows: +.PP +.in +4n +.EX +struct mntent { + char *mnt_fsname; /* name of mounted filesystem */ + char *mnt_dir; /* filesystem path prefix */ + char *mnt_type; /* mount type (see mntent.h) */ + char *mnt_opts; /* mount options (see mntent.h) */ + int mnt_freq; /* dump frequency in days */ + int mnt_passno; /* pass number on parallel fsck */ +}; +.EE +.in +.PP +Since fields in the mtab and fstab files are separated by whitespace, +octal escapes are used to represent the characters space (\e040), +tab (\e011), newline (\e012), and backslash (\e\e) in those files +when they occur in one of the four strings in a +.I mntent +structure. +The routines +.BR addmntent () +and +.BR getmntent () +will convert +from string representation to escaped representation and back. +When converting from escaped representation, the sequence \e134 is +also converted to a backslash. +.SH RETURN VALUE +The +.BR getmntent () +and +.BR getmntent_r () +functions return +a pointer to the +.I mntent +structure or NULL on failure. +.PP +The +.BR addmntent () +function returns 0 on success and 1 on failure. +.PP +The +.BR endmntent () +function always returns 1. +.PP +The +.BR hasmntopt () +function returns the address of the substring if +a match is found and NULL otherwise. +.SH FILES +.TP +.I /etc/fstab +filesystem description file +.TP +.I /etc/mtab +mounted filesystem description file +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw13 lb lbw31 +l l l. +Interface Attribute Value +T{ +.BR setmntent (), +.BR endmntent (), +.BR hasmntopt () +T} Thread safety MT-Safe +T{ +.BR getmntent () +T} Thread safety MT-Unsafe race:mntentbuf locale +T{ +.BR addmntent () +T} Thread safety MT-Safe race:stream locale +T{ +.BR getmntent_r () +T} Thread safety MT-Safe locale +.TE +.ad +.SH CONFORMING TO +The nonreentrant functions are from SunOS 4.1.3. +A routine +.BR getmntent_r () +was introduced in HP-UX 10, but it returns an int. +The prototype shown above is glibc-only. +.SH NOTES +System V also has a +.BR getmntent () +function but the calling sequence +differs, and the returned structure is different. +Under System V +.I /etc/mnttab +is used. +4.4BSD and Digital UNIX have a routine +.BR getmntinfo (), +a wrapper around the system call +.BR getfsstat (). +.SH SEE ALSO +.BR fopen (3), +.BR fstab (5), +.BR mount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getmntent_r.3 b/man3/getmntent_r.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man3/getmntent_r.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/getnameinfo.3 b/man3/getnameinfo.3 new file mode 100644 index 0000000..97b4487 --- /dev/null +++ b/man3/getnameinfo.3 @@ -0,0 +1,341 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. +.\" %%%LICENSE_END +.\" +.\" Almost all details are from RFC 2553. +.\" +.\" 2004-12-14, mtk, Added EAI_OVERFLOW error +.\" 2004-12-14 Fixed description of error return +.\" +.TH GETNAMEINFO 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getnameinfo \- address-to-name translation in protocol-independent manner +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int getnameinfo(const struct sockaddr *" "addr" ", socklen_t " "addrlen" , +.BI " char *" "host" ", socklen_t " "hostlen" , +.BI " char *" "serv" ", socklen_t " "servlen" ", int " "flags" ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getnameinfo (): + Since glibc 2.22: _POSIX_C_SOURCE >= 201112L + Glibc 2.21 and earlier: _POSIX_C_SOURCE +.ad b +.SH DESCRIPTION +The +.BR getnameinfo () +function is the inverse of +.BR getaddrinfo (3): +it converts a socket address to a corresponding host and service, +in a protocol-independent manner. +It combines the functionality of +.BR gethostbyaddr (3) +and +.BR getservbyport (3), +but unlike those functions, +.BR getnameinfo () +is reentrant and allows programs to eliminate +IPv4-versus-IPv6 dependencies. +.PP +The +.I addr +argument is a pointer to a generic socket address structure +(of type +.I sockaddr_in +or +.IR sockaddr_in6 ) +of size +.I addrlen +that holds the input IP address and port number. +The arguments +.I host +and +.I serv +are pointers to caller-allocated buffers (of size +.I hostlen +and +.I servlen +respectively) into which +.BR getnameinfo () +places null-terminated strings containing the host and +service names respectively. +.PP +The caller can specify that no hostname (or no service name) +is required by providing a NULL +.I host +(or +.IR serv ) +argument or a zero +.I hostlen +(or +.IR servlen ) +argument. +However, at least one of hostname or service name +must be requested. +.PP +The +.I flags +argument modifies the behavior of +.BR getnameinfo () +as follows: +.TP +.B NI_NAMEREQD +If set, then an error is returned if the hostname cannot be determined. +.TP +.B NI_DGRAM +If set, then the service is datagram (UDP) based rather than +stream (TCP) based. +This is required for the few ports (512\(en514) +that have different services for UDP and TCP. +.TP +.B NI_NOFQDN +If set, return only the hostname part of the fully qualified domain name +for local hosts. +.TP +.B NI_NUMERICHOST +If set, then the numeric form of the hostname is returned. +.\" For example, by calling +.\" .BR inet_ntop () +.\" instead of +.\" .BR gethostbyaddr (). +(When not set, this will still happen in case the node's name +cannot be determined.) +.\" POSIX.1-2003 has NI_NUMERICSCOPE, but glibc doesn't have it. +.TP +.B NI_NUMERICSERV +If set, then the numeric form of the service address is returned. +(When not set, this will still happen in case the service's name +cannot be determined.) +.SS Extensions to getnameinfo() for Internationalized Domain Names +.PP +Starting with glibc 2.3.4, +.BR getnameinfo () +has been extended to selectively allow +hostnames to be transparently converted to and from the +Internationalized Domain Name (IDN) format (see RFC 3490, +.IR "Internationalizing Domain Names in Applications (IDNA)" ). +Three new flags are defined: +.TP +.B NI_IDN +If this flag is used, then the name found in the lookup process is +converted from IDN format to the locale's encoding if necessary. +ASCII-only names are not affected by the conversion, which +makes this flag usable in existing programs and environments. +.TP +.BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES +Setting these flags will enable the +IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and +IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 +conforming hostname) +flags respectively to be used in the IDNA handling. +.SH RETURN VALUE +.\" FIXME glibc defines the following additional errors, some which +.\" can probably be returned by getnameinfo(); they need to +.\" be documented. +.\" +.\" #ifdef __USE_GNU +.\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ +.\" #define EAI_CANCELED -101 /* Request canceled. */ +.\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ +.\" #define EAI_ALLDONE -103 /* All requests done. */ +.\" #define EAI_INTR -104 /* Interrupted by a signal. */ +.\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ +.\" #endif +On success, 0 is returned, and node and service names, if requested, +are filled with null-terminated strings, possibly truncated to fit +the specified buffer lengths. +On error, one of the following nonzero error codes is returned: +.TP +.B EAI_AGAIN +The name could not be resolved at this time. +Try again later. +.TP +.B EAI_BADFLAGS +The +.I flags +argument has an invalid value. +.TP +.B EAI_FAIL +A nonrecoverable error occurred. +.TP +.B EAI_FAMILY +The address family was not recognized, +or the address length was invalid for the specified family. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_NONAME +The name does not resolve for the supplied arguments. +.B NI_NAMEREQD +is set and the host's name cannot be located, +or neither hostname nor service name were requested. +.TP +.B EAI_OVERFLOW +The buffer pointed to by +.I host +or +.I serv +was too small. +.TP +.B EAI_SYSTEM +A system error occurred. +The error code can be found in +.IR errno . +.PP +The +.BR gai_strerror (3) +function translates these error codes to a human readable string, +suitable for error reporting. +.SH FILES +.I /etc/hosts +.br +.I /etc/nsswitch.conf +.br +.I /etc/resolv.conf +.SH VERSIONS +.BR getnameinfo () +is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getnameinfo () +T} Thread safety MT-Safe env locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, RFC\ 2553. +.SH NOTES +In order to assist the programmer in choosing reasonable sizes +for the supplied buffers, +.I +defines the constants +.PP +.in +4n +.EX +#define NI_MAXHOST 1025 +#define NI_MAXSERV 32 +.EE +.in +.PP +Since glibc 2.8, +these definitions are exposed only if suitable +feature test macros are defined, namely: +.BR _GNU_SOURCE , +.BR _DEFAULT_SOURCE +(since glibc 2.19), +or (in glibc versions up to and including 2.19) +.BR _BSD_SOURCE +or +.BR _SVID_SOURCE . +.PP +The former is the constant +.B MAXDNAME +in recent versions of BIND's +.I +header file. +The latter is a guess based on the services listed +in the current Assigned Numbers RFC. +.PP +Before glibc version 2.2, the +.I hostlen +and +.I servlen +arguments were typed as +.IR size_t . +.SH EXAMPLE +The following code tries to get the numeric hostname and service name, +for a given socket address. +Note that there is no hardcoded reference to +a particular address family. +.PP +.in +4n +.EX +struct sockaddr *addr; /* input */ +socklen_t addrlen; /* input */ +char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; + +if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf, + sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0) + printf("host=%s, serv=%s\en", hbuf, sbuf); +.EE +.in +.PP +The following version checks if the socket address has a +reverse address mapping. +.PP +.in +4n +.EX +struct sockaddr *addr; /* input */ +socklen_t addrlen; /* input */ +char hbuf[NI_MAXHOST]; + +if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), + NULL, 0, NI_NAMEREQD)) + printf("could not resolve hostname"); +else + printf("host=%s\en", hbuf); +.EE +.in +.PP +An example program using +.BR getnameinfo () +can be found in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR accept (2), +.BR getpeername (2), +.BR getsockname (2), +.BR recvfrom (2), +.BR socket (2), +.BR getaddrinfo (3), +.BR gethostbyaddr (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR inet_ntop (3), +.BR hosts (5), +.BR services (5), +.BR hostname (7), +.BR named (8) +.PP +R. Gilligan, S. Thomson, J. Bound and W. Stevens, +.IR "Basic Socket Interface Extensions for IPv6" , +RFC\ 2553, March 1999. +.PP +Tatsuya Jinmei and Atsushi Onoe, +.IR "An Extension of Format for IPv6 Scoped Addresses" , +internet draft, work in progress +.UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt +.UE . +.PP +Craig Metz, +.IR "Protocol Independence Using the Sockets API" , +Proceedings of the freenix track: +2000 USENIX annual technical conference, June 2000 +.ad l +.UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html +.UE . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getnetbyaddr.3 b/man3/getnetbyaddr.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man3/getnetbyaddr.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man3/getnetbyaddr_r.3 b/man3/getnetbyaddr_r.3 new file mode 100644 index 0000000..316d315 --- /dev/null +++ b/man3/getnetbyaddr_r.3 @@ -0,0 +1 @@ +.so man3/getnetent_r.3 diff --git a/man3/getnetbyname.3 b/man3/getnetbyname.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man3/getnetbyname.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man3/getnetbyname_r.3 b/man3/getnetbyname_r.3 new file mode 100644 index 0000000..316d315 --- /dev/null +++ b/man3/getnetbyname_r.3 @@ -0,0 +1 @@ +.so man3/getnetent_r.3 diff --git a/man3/getnetent.3 b/man3/getnetent.3 new file mode 100644 index 0000000..bac4677 --- /dev/null +++ b/man3/getnetent.3 @@ -0,0 +1,220 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) +.TH GETNETENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getnetent, getnetbyname, getnetbyaddr, setnetent, endnetent \- +get network entry +.SH SYNOPSIS +.nf +.B #include +.PP +.B struct netent *getnetent(void); +.PP +.BI "struct netent *getnetbyname(const char *" name ); +.PP +.BI "struct netent *getnetbyaddr(uint32_t " net ", int " type ); +.PP +.BI "void setnetent(int " stayopen ); +.PP +.B void endnetent(void); +.fi +.SH DESCRIPTION +The +.BR getnetent () +function reads the next entry from the networks database +and returns a +.I netent +structure containing +the broken-out fields from the entry. +A connection is opened to the database if necessary. +.PP +The +.BR getnetbyname () +function returns a +.I netent +structure +for the entry from the database +that matches the network +.IR name . +.PP +The +.BR getnetbyaddr () +function returns a +.I netent +structure +for the entry from the database +that matches the network number +.I net +of type +.IR type . +The +.I net +argument must be in host byte order. +.PP +The +.BR setnetent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getnet* () +functions. +.PP +The +.BR endnetent () +function closes the connection to the database. +.PP +The +.I netent +structure is defined in +.I +as follows: +.PP +.in +4n +.EX +struct netent { + char *n_name; /* official network name */ + char **n_aliases; /* alias list */ + int n_addrtype; /* net address type */ + uint32_t n_net; /* network number */ +} +.EE +.in +.PP +The members of the +.I netent +structure are: +.TP +.I n_name +The official name of the network. +.TP +.I n_aliases +A NULL-terminated list of alternative names for the network. +.TP +.I n_addrtype +The type of the network number; always +.BR AF_INET . +.TP +.I n_net +The network number in host byte order. +.SH RETURN VALUE +The +.BR getnetent (), +.BR getnetbyname () +and +.BR getnetbyaddr () +functions return a pointer to a +statically allocated +.I netent +structure, or a null pointer if an +error occurs or the end of the file is reached. +.SH FILES +.TP +.I /etc/networks +networks database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw14 lb lbw25 +l l l. +Interface Attribute Value +T{ +.BR getnetent () +T} Thread safety T{ +MT-Unsafe race:netent +.br +race:netentbuf env locale +T} +T{ +.BR getnetbyname () +T} Thread safety T{ +MT-Unsafe race:netbyname +.br +env locale +T} +T{ +.BR getnetbyaddr () +T} Thread safety T{ +MT-Unsafe race:netbyaddr +.br +locale +T} +T{ +.BR setnetent (), +.br +.BR endnetent () +T} Thread safety T{ +MT-Unsafe race:netent env +.br +locale +T} +.TE +.sp 1 +In the above table, +.I netent +in +.I race:netent +signifies that if any of the functions +.BR setnetent (), +.BR getnetent (), +or +.BR endnetent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH NOTES +In glibc versions before 2.2, the +.I net +argument of +.BR getnetbyaddr () +was of type +.IR long . +.SH SEE ALSO +.BR getnetent_r (3), +.BR getprotoent (3), +.BR getservent (3) +.\" .BR networks (5) +.br +RFC\ 1101 +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getnetent_r.3 b/man3/getnetent_r.3 new file mode 100644 index 0000000..7a60319 --- /dev/null +++ b/man3/getnetent_r.3 @@ -0,0 +1,173 @@ +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETNETENT_R 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getnetent_r, getnetbyname_r, getnetbyaddr_r \- get +network entry (reentrant) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getnetent_r(struct netent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct netent **" result , +.BI " int *" h_errnop ); +.PP +.BI "int getnetbyname_r(const char *" name , +.BI " struct netent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct netent **" result , +.BI " int *" h_errnop ); +.PP +.BI "int getnetbyaddr_r(uint32_t " net ", int " type , +.BI " struct netent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct netent **" result , +.BI " int *" h_errnop ); +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getnetent_r (), +.BR getnetbyname_r (), +.BR getnetbyaddr_r (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.ad b +.SH DESCRIPTION +The +.BR getnetent_r (), +.BR getnetbyname_r (), +and +.BR getnetbyaddr_r () +functions are the reentrant equivalents of, respectively, +.BR getnetent (3), +.BR getnetbyname (3), +and +.BR getnetbynumber (3). +They differ in the way that the +.I netent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.PP +Instead of returning a pointer to a statically allocated +.I netent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.PP +The +.I buf +array is used to store the string fields pointed to by the returned +.I netent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.PP +If the function call successfully obtains a network record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.PP +The buffer pointed to by +.I h_errnop +is used to return the value that would be stored in the global variable +.I h_errno +by the nonreentrant versions of these functions. +.\" getnetent.3 doesn't document any use of h_errno, but nevertheless +.\" the nonreentrant functions no seem to set h_errno. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.PP +On error, record not found +.RB ( getnetbyname_r (), +.BR getnetbyaddr_r ()), +or end of input +.RB ( getnetent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getnetent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw17 lb lb +l l l. +Interface Attribute Value +T{ +.BR getnetent_r (), +.BR getnetbyname_r (), +.BR getnetbyaddr_r () +T} Thread safety MT-Safe locale +.TE +.ad +.SH CONFORMING TO +These functions are GNU extensions. +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH SEE ALSO +.BR getnetent (3), +.BR networks (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getnetgrent.3 b/man3/getnetgrent.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man3/getnetgrent.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man3/getnetgrent_r.3 b/man3/getnetgrent_r.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man3/getnetgrent_r.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man3/getopt.3 b/man3/getopt.3 new file mode 100644 index 0000000..8e59945 --- /dev/null +++ b/man3/getopt.3 @@ -0,0 +1,547 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt +.\" longindex is a pointer, has_arg can take 3 values, using consistent +.\" names for optstring and longindex, "\n" in formats fixed. Documenting +.\" opterr and getopt_long_only. Clarified explanations (borrowing heavily +.\" from the source code). +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX +.\" says; moreover, EOF is not defined in . +.\" Modified 2002-02-16, joey: added information about nonexistent +.\" option character and colon as first option character +.\" Modified 2004-07-28, Michael Kerrisk +.\" Added text to explain how to order both '[-+]' and ':' at +.\" the start of optstring +.\" Modified 2006-12-15, mtk, Added getopt() example program. +.\" +.TH GETOPT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getopt, getopt_long, getopt_long_only, +optarg, optind, opterr, optopt \- Parse command-line options +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getopt(int " argc ", char * const " argv[] , +.BI " const char *" optstring ); +.PP +.BI "extern char *" optarg ; +.BI "extern int " optind ", " opterr ", " optopt ; +.PP +.B #include +.PP +.BI "int getopt_long(int " argc ", char * const " argv[] , +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.PP +.BI "int getopt_long_only(int " argc ", char * const " argv[] , +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getopt (): +_POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE +.br +.BR getopt_long (), +.BR getopt_long_only (): +_GNU_SOURCE +.ad b +.SH DESCRIPTION +The +.BR getopt () +function parses the command-line arguments. +Its arguments +.I argc +and +.I argv +are the argument count and array as passed to the +.IR main () +function on program invocation. +An element of \fIargv\fP that starts with \(aq\-\(aq +(and is not exactly "\-" or "\-\-") +is an option element. +The characters of this element +(aside from the initial \(aq\-\(aq) are option characters. +If +.BR getopt () +is called repeatedly, it returns successively each of the option characters +from each of the option elements. +.PP +The variable +.I optind +is the index of the next element to be processed in +.IR argv . +The system initializes this value to 1. +The caller can reset it to 1 to restart scanning of the same +.IR argv , +or when scanning a new argument vector. +.PP +If +.BR getopt () +finds another option character, it returns that +character, updating the external variable \fIoptind\fP and a static +variable \fInextchar\fP so that the next call to +.BR getopt () +can +resume the scan with the following option character or +\fIargv\fP-element. +.PP +If there are no more option characters, +.BR getopt () +returns \-1. +Then \fIoptind\fP is the index in \fIargv\fP of the first +\fIargv\fP-element that is not an option. +.PP +.I optstring +is a string containing the legitimate option characters. +If such a +character is followed by a colon, the option requires an argument, so +.BR getopt () +places a pointer to the following text in the same +\fIargv\fP-element, or the text of the following \fIargv\fP-element, in +.IR optarg . +Two colons mean an option takes +an optional arg; if there is text in the current \fIargv\fP-element +(i.e., in the same word as the option name itself, for example, "\-oarg"), +then it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero. +This is a GNU extension. +If +.I optstring +contains +.B W +followed by a semicolon, then +.B \-W foo +is treated as the long option +.BR \-\-foo . +(The +.B \-W +option is reserved by POSIX.2 for implementation extensions.) +This behavior is a GNU extension, not available with libraries before +glibc 2. +.PP +By default, +.BR getopt () +permutes the contents of \fIargv\fP as it +scans, so that eventually all the nonoptions are at the end. +Two other modes are also implemented. +If the first character of +\fIoptstring\fP is \(aq+\(aq or the environment variable +.B POSIXLY_CORRECT +is set, then option processing stops as soon as a nonoption argument is +encountered. +If the first character of \fIoptstring\fP is \(aq\-\(aq, then +each nonoption \fIargv\fP-element is handled as if it were the argument of +an option with character code 1. (This is used by programs that were +written to expect options and other \fIargv\fP-elements in any order +and that care about the ordering of the two.) +The special argument "\-\-" forces an end of option-scanning regardless +of the scanning mode. +.PP +While processing the option list, +.BR getopt () +can detect two kinds of errors: +(1) an option character that was not specified in +.IR optstring +and (2) a missing option argument +(i.e., an option at the end of the command line without an expected argument). +Such errors are handled and reported as follows: +.IP * 3 +By default, +.BR getopt () +prints an error message on standard error, +places the erroneous option character in +.IR optopt , +and returns \(aq?\(aq as the function result. +.IP * +If the caller has set the global variable +.IR opterr +to zero, then +.BR getopt () +does not print an error message. +The caller can determine that there was an error by testing whether +the function return value is \(aq?\(aq. +(By default, +.IR opterr +has a nonzero value.) +.IP * +If the first character +(following any optional \(aq+\(aq or \(aq\-\(aq described above) +of \fIoptstring\fP +is a colon (\(aq:\(aq), then +.BR getopt () +likewise does not print an error message. +In addition, it returns \(aq:\(aq instead of \(aq?\(aq to +indicate a missing option argument. +This allows the caller to distinguish the two different types of errors. +.\" +.SS getopt_long() and getopt_long_only() +The +.BR getopt_long () +function works like +.BR getopt () +except that it also accepts long options, started with two dashes. +(If the program accepts only long options, then +.I optstring +should be specified as an empty string (""), not NULL.) +Long option names may be abbreviated if the abbreviation is +unique or is an exact match for some defined option. +A long option +may take a parameter, of the form +.B \-\-arg=param +or +.BR "\-\-arg param" . +.PP +.I longopts +is a pointer to the first element of an array of +.I struct option +declared in +.I +as +.PP +.in +4n +.EX +struct option { + const char *name; + int has_arg; + int *flag; + int val; +}; +.EE +.in +.PP +The meanings of the different fields are: +.TP +.I name +is the name of the long option. +.TP +.I has_arg +is: +\fBno_argument\fP (or 0) if the option does not take an argument; +\fBrequired_argument\fP (or 1) if the option requires an argument; or +\fBoptional_argument\fP (or 2) if the option takes an optional argument. +.TP +.I flag +specifies how results are returned for a long option. +If \fIflag\fP +is NULL, then +.BR getopt_long () +returns \fIval\fP. +(For example, the calling program may set \fIval\fP to the equivalent short +option character.) +Otherwise, +.BR getopt_long () +returns 0, and +\fIflag\fP points to a variable which is set to \fIval\fP if the +option is found, but left unchanged if the option is not found. +.TP +\fIval\fP +is the value to return, or to load into the variable pointed +to by \fIflag\fP. +.PP +The last element of the array has to be filled with zeros. +.PP +If \fIlongindex\fP is not NULL, it +points to a variable which is set to the index of the long option relative to +.IR longopts . +.PP +.BR getopt_long_only () +is like +.BR getopt_long (), +but \(aq\-\(aq as well +as "\-\-" can indicate a long option. +If an option that starts with \(aq\-\(aq +(not "\-\-") doesn't match a long option, but does match a short option, +it is parsed as a short option instead. +.SH RETURN VALUE +If an option was successfully found, then +.BR getopt () +returns the option character. +If all command-line options have been parsed, then +.BR getopt () +returns \-1. +If +.BR getopt () +encounters an option character that was not in +.IR optstring , +then \(aq?\(aq is returned. +If +.BR getopt () +encounters an option with a missing argument, +then the return value depends on the first character in +.IR optstring : +if it is \(aq:\(aq, then \(aq:\(aq is returned; otherwise \(aq?\(aq is returned. +.PP +.BR getopt_long () +and +.BR getopt_long_only () +also return the option +character when a short option is recognized. +For a long option, they +return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise. +Error and \-1 returns are the same as for +.BR getopt (), +plus \(aq?\(aq for an +ambiguous match or an extraneous parameter. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +If this is set, then option processing stops as soon as a nonoption +argument is encountered. +.TP +.B __GNU_nonoption_argv_flags_ +This variable was used by +.BR bash (1) +2.0 to communicate to glibc which arguments are the results of +wildcard expansion and so should not be considered as options. +This behavior was removed in +.BR bash (1) +version 2.01, but the support remains in glibc. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR getopt (), +.BR getopt_long (), +.BR getopt_long_only () +T} Thread safety MT-Unsafe race:getopt env +.TE +.SH CONFORMING TO +.TP +.BR getopt (): +POSIX.1-2001, POSIX.1-2008, and POSIX.2, +provided the environment variable +.B POSIXLY_CORRECT +is set. +Otherwise, the elements of \fIargv\fP aren't really +.IR const , +because we permute them. +We pretend they're +.I const +in the prototype to be compatible with other systems. +.IP +The use of \(aq+\(aq and \(aq\-\(aq in +.I optstring +is a GNU extension. +.IP +On some older implementations, +.BR getopt () +was declared in +.IR . +SUSv1 permitted the declaration to appear in either +.I +or +.IR . +POSIX.1-1996 marked the use of +.I +for this purpose as LEGACY. +POSIX.1-2001 does not require the declaration to appear in +.IR . +.TP +.BR getopt_long "() and " getopt_long_only (): +These functions are GNU extensions. +.SH NOTES +A program that scans multiple argument vectors, +or rescans the same vector more than once, +and wants to make use of GNU extensions such as \(aq+\(aq +and \(aq\-\(aq at the start of +.IR optstring , +or changes the value of +.B POSIXLY_CORRECT +between scans, +must reinitialize +.BR getopt () +by resetting +.I optind +to 0, rather than the traditional value of 1. +(Resetting to 0 forces the invocation of an internal initialization +routine that rechecks +.B POSIXLY_CORRECT +and checks for GNU extensions in +.IR optstring .) +.SH EXAMPLE +.SS getopt() +The following trivial example program uses +.BR getopt () +to handle two program options: +.IR \-n , +with no associated value; and +.IR "\-t val" , +which expects an associated value. +.PP +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + int flags, opt; + int nsecs, tfnd; + + nsecs = 0; + tfnd = 0; + flags = 0; + while ((opt = getopt(argc, argv, "nt:")) != \-1) { + switch (opt) { + case \(aqn\(aq: + flags = 1; + break; + case \(aqt\(aq: + nsecs = atoi(optarg); + tfnd = 1; + break; + default: /* \(aq?\(aq */ + fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\\n", + argv[0]); + exit(EXIT_FAILURE); + } + } + + printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\\n", + flags, tfnd, nsecs, optind); + + if (optind >= argc) { + fprintf(stderr, "Expected argument after options\\n"); + exit(EXIT_FAILURE); + } + + printf("name argument = %s\\n", argv[optind]); + + /* Other code omitted */ + + exit(EXIT_SUCCESS); +} +.EX +.SS getopt_long() +The following example program illustrates the use of +.BR getopt_long () +with most of its features. +.PP +.EE +#include /* for printf */ +#include /* for exit */ +#include +.PP +int +main(int argc, char **argv) +{ + int c; + int digit_optind = 0; +.PP + while (1) { + int this_option_optind = optind ? optind : 1; + int option_index = 0; + static struct option long_options[] = { + {"add", required_argument, 0, 0 }, + {"append", no_argument, 0, 0 }, + {"delete", required_argument, 0, 0 }, + {"verbose", no_argument, 0, 0 }, + {"create", required_argument, 0, \(aqc\(aq}, + {"file", required_argument, 0, 0 }, + {0, 0, 0, 0 } + }; +.PP + c = getopt_long(argc, argv, "abc:d:012", + long_options, &option_index); + if (c == \-1) + break; +.PP + switch (c) { + case 0: + printf("option %s", long_options[option_index].name); + if (optarg) + printf(" with arg %s", optarg); + printf("\\n"); + break; +.PP + case \(aq0\(aq: + case \(aq1\(aq: + case \(aq2\(aq: + if (digit_optind != 0 && digit_optind != this_option_optind) + printf("digits occur in two different argv\-elements.\\n"); + digit_optind = this_option_optind; + printf("option %c\\n", c); + break; +.PP + case \(aqa\(aq: + printf("option a\\n"); + break; +.PP + case \(aqb\(aq: + printf("option b\\n"); + break; +.PP + case \(aqc\(aq: + printf("option c with value \(aq%s\(aq\\n", optarg); + break; +.PP + case \(aqd\(aq: + printf("option d with value \(aq%s\(aq\\n", optarg); + break; +.PP + case \(aq?\(aq: + break; +.PP + default: + printf("?? getopt returned character code 0%o ??\\n", c); + } + } +.PP + if (optind < argc) { + printf("non\-option ARGV\-elements: "); + while (optind < argc) + printf("%s ", argv[optind++]); + printf("\\n"); + } +.PP + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getopt (1), +.BR getsubopt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getopt_long.3 b/man3/getopt_long.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man3/getopt_long.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man3/getopt_long_only.3 b/man3/getopt_long_only.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man3/getopt_long_only.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man3/getpass.3 b/man3/getpass.3 new file mode 100644 index 0000000..8d21e4f --- /dev/null +++ b/man3/getpass.3 @@ -0,0 +1,175 @@ +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH GETPASS 3 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +getpass \- get a password +.SH SYNOPSIS +.B #include +.PP +.BI "char *getpass(const char *" prompt ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getpass (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.2.2: +.nf +_XOPEN_SOURCE && ! (_POSIX_C_SOURCE\ >=\ 200112L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.fi +.TP 4 +Before glibc 2.2.2: +none +.PD +.RE +.ad b +.SH DESCRIPTION +This function is obsolete. +Do not use it. +If you want to read input without terminal echoing enabled, +see the description of the +.I ECHO +flag in +.BR termios (3). +.PP +The +.BR getpass () +function opens +.I /dev/tty +(the controlling terminal of the process), outputs the string +.IR prompt , +turns off echoing, reads one line (the "password"), +restores the terminal state and closes +.I /dev/tty +again. +.SH RETURN VALUE +The function +.BR getpass () +returns a pointer to a static buffer containing (the first +.B PASS_MAX +bytes of) the password without the trailing +newline, terminated by a null byte (\(aq\\0\(aq). +This buffer may be overwritten by a following call. +On error, the terminal state is restored, +.I errno +is set appropriately, and NULL is returned. +.SH ERRORS +The function may fail if +.TP +.B ENXIO +The process does not have a controlling terminal. +.SH FILES +.I /dev/tty +.\" .SH HISTORY +.\" A +.\" .BR getpass () +.\" function appeared in Version 7 AT&T UNIX. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getpass () +T} Thread safety MT-Unsafe term +.TE +.SH CONFORMING TO +Present in SUSv2, but marked LEGACY. +Removed in POSIX.1-2001. +.SH NOTES +.\" For libc4 and libc5, the prompt is not written to +.\" .I /dev/tty +.\" but to +.\" .IR stderr . +.\" Moreover, if +.\" .I /dev/tty +.\" cannot be opened, the password is read from +.\" .IR stdin . +.\" The static buffer has length 128 so that only the first 127 +.\" bytes of the password are returned. +.\" While reading the password, signal generation +.\" .RB ( SIGINT , +.\" .BR SIGQUIT , +.\" .BR SIGSTOP , +.\" .BR SIGTSTP ) +.\" is disabled and the corresponding characters +.\" (usually control-C, control-\e, control-Z and control-Y) +.\" are transmitted as part of the password. +.\" Since libc 5.4.19 also line editing is disabled, so that also +.\" backspace and the like will be seen as part of the password. +.PP +In the GNU C library implementation, if +.I /dev/tty +cannot be opened, the prompt is written to +.I stderr +and the password is read from +.IR stdin . +There is no limit on the length of the password. +Line editing is not disabled. +.PP +According to SUSv2, the value of +.B PASS_MAX +must be defined in +.I +in case it is smaller than 8, and can in any case be obtained using +.IR sysconf(_SC_PASS_MAX) . +However, POSIX.2 withdraws the constants +.B PASS_MAX +and +.BR _SC_PASS_MAX , +and the function +.BR getpass (). +.\" Libc4 and libc5 have never supported +.\" .B PASS_MAX +.\" or +.\" .BR _SC_PASS_MAX . +The glibc version accepts +.B _SC_PASS_MAX +and returns +.B BUFSIZ +(e.g., 8192). +.SH BUGS +The calling process should zero the password as soon as possible to avoid +leaving the cleartext password visible in the process's address space. +.SH SEE ALSO +.BR crypt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getprotobyname.3 b/man3/getprotobyname.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man3/getprotobyname.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man3/getprotobyname_r.3 b/man3/getprotobyname_r.3 new file mode 100644 index 0000000..9936ea8 --- /dev/null +++ b/man3/getprotobyname_r.3 @@ -0,0 +1 @@ +.so man3/getprotoent_r.3 diff --git a/man3/getprotobynumber.3 b/man3/getprotobynumber.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man3/getprotobynumber.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man3/getprotobynumber_r.3 b/man3/getprotobynumber_r.3 new file mode 100644 index 0000000..9936ea8 --- /dev/null +++ b/man3/getprotobynumber_r.3 @@ -0,0 +1 @@ +.so man3/getprotoent_r.3 diff --git a/man3/getprotoent.3 b/man3/getprotoent.3 new file mode 100644 index 0000000..34379e8 --- /dev/null +++ b/man3/getprotoent.3 @@ -0,0 +1,206 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH GETPROTOENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getprotoent, getprotobyname, getprotobynumber, setprotoent, +endprotoent \- get protocol entry +.SH SYNOPSIS +.nf +.B #include +.PP +.B struct protoent *getprotoent(void); +.PP +.BI "struct protoent *getprotobyname(const char *" name ); +.PP +.BI "struct protoent *getprotobynumber(int " proto ); +.PP +.BI "void setprotoent(int " stayopen ); +.PP +.B void endprotoent(void); +.fi +.SH DESCRIPTION +The +.BR getprotoent () +function reads the next entry from the protocols database (see +.BR protocols (5)) +and returns a +.I protoent +structure +containing the broken-out fields from the entry. +A connection is opened to the database if necessary. +.PP +The +.BR getprotobyname () +function returns a +.I protoent +structure +for the entry from the database +that matches the protocol name +.IR name . +A connection is opened to the database if necessary. +.PP +The +.BR getprotobynumber () +function returns a +.I protoent +structure +for the entry from the database +that matches the protocol number +.IR number . +A connection is opened to the database if necessary. +.PP +The +.BR setprotoent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getproto* () +functions. +.PP +The +.BR endprotoent () +function closes the connection to the database. +.PP +The +.I protoent +structure is defined in +.I +as follows: +.PP +.in +4n +.EX +struct protoent { + char *p_name; /* official protocol name */ + char **p_aliases; /* alias list */ + int p_proto; /* protocol number */ +} +.EE +.in +.PP +The members of the +.I protoent +structure are: +.TP +.I p_name +The official name of the protocol. +.TP +.I p_aliases +A NULL-terminated list of alternative names for the protocol. +.TP +.I p_proto +The protocol number. +.SH RETURN VALUE +The +.BR getprotoent (), +.BR getprotobyname () +and +.BR getprotobynumber () +functions return a pointer to a +statically allocated +.I protoent +structure, or a null pointer if an +error occurs or the end of the file is reached. +.SH FILES +.PD 0 +.TP +.I /etc/protocols +protocol database file +.PD +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw18 lb lbw28 +l l l. +Interface Attribute Value +T{ +.BR getprotoent () +T} Thread safety T{ +MT-Unsafe race:protoent +.br +race:protoentbuf locale +T} +T{ +.BR getprotobyname () +T} Thread safety T{ +MT-Unsafe race:protobyname +.br +locale +T} +T{ +.BR getprotobynumber () +T} Thread safety T{ +MT-Unsafe race:protobynumber +.br +locale +T} +T{ +.BR setprotoent (), +.br +.BR endprotoent () +T} Thread safety T{ +MT-Unsafe race:protoent +.br +locale +T} +.TE +.sp 1 +In the above table, +.I protoent +in +.I race:protoent +signifies that if any of the functions +.BR setprotoent (), +.BR getprotoent (), +or +.BR endprotoent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH SEE ALSO +.BR getnetent (3), +.BR getprotoent_r (3), +.BR getservent (3), +.BR protocols (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getprotoent_r.3 b/man3/getprotoent_r.3 new file mode 100644 index 0000000..d2e3021 --- /dev/null +++ b/man3/getprotoent_r.3 @@ -0,0 +1,266 @@ +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETPROTOENT_R 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getprotoent_r, getprotobyname_r, getprotobynumber_r \- get +protocol entry (reentrant) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getprotoent_r(struct protoent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct protoent **" result ); +.PP +.BI "int getprotobyname_r(const char *" name , +.BI " struct protoent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct protoent **" result ); +.PP +.BI "int getprotobynumber_r(int " proto , +.BI " struct protoent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct protoent **" result ); +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getprotoent_r (), +.BR getprotobyname_r (), +.BR getprotobynumber_r (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.ad b +.SH DESCRIPTION +The +.BR getprotoent_r (), +.BR getprotobyname_r (), +and +.BR getprotobynumber_r () +functions are the reentrant equivalents of, respectively, +.BR getprotoent (3), +.BR getprotobyname (3), +and +.BR getprotobynumber (3). +They differ in the way that the +.I protoent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.PP +Instead of returning a pointer to a statically allocated +.I protoent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.PP +The +.I buf +array is used to store the string fields pointed to by the returned +.I protoent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer. +.\" The 1024 byte value is also what the Solaris man page suggests. -- mtk +.PP +If the function call successfully obtains a protocol record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.PP +On error, record not found +.RB ( getprotobyname_r (), +.BR getprotobynumber_r ()), +or end of input +.RB ( getprotoent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getprotoent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR getprotoent_r (), +.br +.BR getprotobyname_r (), +.br +.BR getprotobynumber_r () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +These functions are GNU extensions. +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH EXAMPLE +The program below uses +.BR getprotobyname_r () +to retrieve the protocol record for the protocol named +in its first command-line argument. +If a second (integer) command-line argument is supplied, +it is used as the initial value for +.IR buflen ; +if +.BR getprotobyname_r () +fails with the error +.BR ERANGE , +the program retries with larger buffer sizes. +The following shell session shows a couple of sample runs: +.PP +.in +4n +.EX +.RB "$" " ./a.out tcp 1" +ERANGE! Retrying with larger buffer +getprotobyname_r() returned: 0 (success) (buflen=78) +p_name=tcp; p_proto=6; aliases=TCP +.RB "$" " ./a.out xxx 1" +ERANGE! Retrying with larger buffer +getprotobyname_r() returned: 0 (success) (buflen=100) +Call failed/record not found +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +#define MAX_BUF 10000 + +int +main(int argc, char *argv[]) +{ + int buflen, erange_cnt, s; + struct protoent result_buf; + struct protoent *result; + char buf[MAX_BUF]; + char **p; + + if (argc < 2) { + printf("Usage: %s proto\-name [buflen]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + buflen = 1024; + if (argc > 2) + buflen = atoi(argv[2]); + + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\\n", MAX_BUF); + exit(EXIT_FAILURE); + } + + erange_cnt = 0; + do { + s = getprotobyname_r(argv[1], &result_buf, + buf, buflen, &result); + if (s == ERANGE) { + if (erange_cnt == 0) + printf("ERANGE! Retrying with larger buffer\\n"); + erange_cnt++; + + /* Increment a byte at a time so we can see exactly + what size buffer was required */ + + buflen++; + + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\\n", MAX_BUF); + exit(EXIT_FAILURE); + } + } + } while (s == ERANGE); + + printf("getprotobyname_r() returned: %s (buflen=%d)\\n", + (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" : + strerror(s), buflen); + + if (s != 0 || result == NULL) { + printf("Call failed/record not found\\n"); + exit(EXIT_FAILURE); + } + + printf("p_name=%s; p_proto=%d; aliases=", + result_buf.p_name, result_buf.p_proto); + for (p = result_buf.p_aliases; *p != NULL; p++) + printf("%s ", *p); + printf("\\n"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getprotoent (3), +.BR protocols (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getpt.3 b/man3/getpt.3 new file mode 100644 index 0000000..eb71548 --- /dev/null +++ b/man3/getpt.3 @@ -0,0 +1,77 @@ +.\" This man page was written by Jeremy Phelps . +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" Redistribute and modify at will. +.\" %%%LICENSE_END +.\" +.TH GETPT 3 2015-03-02 "GNU" "Linux Programmer's Manual" +.SH NAME +getpt \- open the pseudoterminal master (PTM) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.B "int getpt(void);" +.fi +.SH DESCRIPTION +.BR getpt () +opens a pseudoterminal master and returns its file descriptor. +It is equivalent to +.PP +.in +4n +.EX +open(/dev/ptmx, O_RDWR | O_NOCTTY); +.EE +.in +.PP +on Linux systems, though the pseudoterminal master is located +elsewhere on some systems that use GNU Libc. +.SH RETURN VALUE +.BR getpt () +returns an open file descriptor upon successful completion. +Otherwise, it +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.BR getpt () +can fail with various errors described in +.BR open (2). +.SH VERSIONS +.BR getpt () +is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getpt () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR getpt () +is glibc-specific; +use +.BR posix_openpt (3) +instead. +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR ptmx (4), +.BR pty (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getpw.3 b/man3/getpw.3 new file mode 100644 index 0000000..8959276 --- /dev/null +++ b/man3/getpw.3 @@ -0,0 +1,147 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:23:25 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH GETPW 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getpw \- reconstruct password line entry +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.B #include +.PP +.BI "int getpw(uid_t " uid ", char *" buf ); +.fi +.SH DESCRIPTION +The +.BR getpw () +function reconstructs the password line entry for +the given user ID \fIuid\fP in the buffer \fIbuf\fP. +The returned buffer contains a line of format +.PP +.in +4n +.EX +.B name:passwd:uid:gid:gecos:dir:shell +.EE +.in +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.PP +For more information about the fields of this structure, see +.BR passwd (5). +.SH RETURN VALUE +The +.BR getpw () +function returns 0 on success; on error, it returns \-1, and +.I errno +is set to indicate the error. +.PP +If +.I uid +is not found in the password database, +.BR getpw () +returns \-1, sets +.I errno +to 0, and leaves +.I buf +unchanged. +.SH ERRORS +.TP +.BR 0 " or " ENOENT +No user corresponding to +.IR uid . +.TP +.B EINVAL +.I buf +is NULL. +.TP +.B ENOMEM +Insufficient memory to allocate +.I passwd +structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getpw () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +SVr2. +.SH BUGS +The +.BR getpw () +function is dangerous as it may overflow the provided buffer +.IR buf . +It is obsoleted by +.BR getpwuid (3). +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getpwent.3 b/man3/getpwent.3 new file mode 100644 index 0000000..6073906 --- /dev/null +++ b/man3/getpwent.3 @@ -0,0 +1,209 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:22:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH GETPWENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getpwent, setpwent, endpwent \- get password file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.B struct passwd *getpwent(void); +.PP +.B void setpwent(void); +.PP +.B void endpwent(void); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR getpwent (), +.BR setpwent (), +.BR endpwent (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR getpwent () +function returns a pointer to a structure containing +the broken-out fields of a record from the password database +(e.g., the local password file +.IR /etc/passwd , +NIS, and LDAP). +The first time +.BR getpwent () +is called, it returns the first entry; thereafter, it returns successive +entries. +.PP +The +.BR setpwent () +function rewinds to the beginning +of the password database. +.PP +The +.BR endpwent () +function is used to close the password database +after all processing has been performed. +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.PP +For more information about the fields of this structure, see +.BR passwd (5). +.SH RETURN VALUE +The +.BR getpwent () +function returns a pointer to a +.I passwd +structure, or NULL if +there are no more entries or an error occurred. +If an error occurs, +.I errno +is set appropriately. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.PP +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getpwent (), +.BR getpwnam (3), +or +.BR getpwuid (3). +(Do not pass the returned pointer to +.BR free (3).) +.SH ERRORS +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I passwd +structure. +.\" to allocate the passwd structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/passwd +local password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw11 lb lb +l l l. +Interface Attribute Value +T{ +.BR getpwent () +T} Thread safety T{ +MT-Unsafe race:pwent +.br +race:pwentbuf locale +T} +T{ +.BR setpwent (), +.br +.BR endpwent () +T} Thread safety MT-Unsafe race:pwent locale +.TE +.sp 1 +In the above table, +.I pwent +in +.I race:pwent +signifies that if any of the functions +.BR setpwent (), +.BR getpwent (), +or +.BR endpwent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +The +.I pw_gecos +field is not specified in POSIX, but is present on most implementations. +.SH SEE ALSO +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent_r (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getpwent_r.3 b/man3/getpwent_r.3 new file mode 100644 index 0000000..335d30d --- /dev/null +++ b/man3/getpwent_r.3 @@ -0,0 +1,228 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH GETPWENT_R 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getpwent_r, fgetpwent_r \- get passwd file entry reentrantly +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getpwent_r(struct passwd *" pwbuf ", char *" buf , +.BI " size_t " buflen ", struct passwd **" pwbufp ); +.PP +.BI "int fgetpwent_r(FILE *" stream ", struct passwd *" pwbuf ", char *" buf , +.BI " size_t " buflen ", struct passwd **" pwbufp ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getpwent_r (), + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.br +.BR fgetpwent_r (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +The functions +.BR getpwent_r () +and +.BR fgetpwent_r () +are the reentrant versions of +.BR getpwent (3) +and +.BR fgetpwent (3). +The former reads the next passwd entry from the stream initialized by +.BR setpwent (3). +The latter reads the next passwd entry from +.IR stream . +.PP +The \fIpasswd\fP structure is defined in +.I +as follows: +.PP +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.PP +For more information about the fields of this structure, see +.BR passwd (5). +.PP +The nonreentrant functions return a pointer to static storage, +where this static storage contains further pointers to user +name, password, gecos field, home directory and shell. +The reentrant functions described here return all of that in +caller-provided buffers. +First of all there is the buffer +.I pwbuf +that can hold a \fIstruct passwd\fP. +And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the \fIstruct passwd\fP read from the stream, +is stored in the provided buffer +.IR *pwbuf , +and a pointer to this \fIstruct passwd\fP is returned in +.IR *pwbufp . +.SH RETURN VALUE +On success, these functions return 0 and +.I *pwbufp +is a pointer to the \fIstruct passwd\fP. +On error, these functions return an error value and +.I *pwbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. +Try again with larger buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw27 +l l l. +Interface Attribute Value +T{ +.BR getpwent_r () +T} Thread safety MT-Unsafe race:pwent locale +T{ +.BR fgetpwent_r () +T} Thread safety MT-Safe +.TE +.sp 1 +In the above table, +.I pwent +in +.I race:pwent +signifies that if any of the functions +.BR setpwent (), +.BR getpwent (), +.BR endpwent (), +or +.BR getpwent_r () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +These functions are GNU extensions, done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +Other systems use the prototype +.PP +.in +4n +.EX +struct passwd * +getpwent_r(struct passwd *pwd, char *buf, int buflen); +.EE +.in +.PP +or, better, +.PP +.in +4n +.EX +int +getpwent_r(struct passwd *pwd, char *buf, int buflen, + FILE **pw_fp); +.EE +.in +.SH NOTES +The function +.BR getpwent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH EXAMPLE +.EX +#define _GNU_SOURCE +#include +#include +#define BUFLEN 4096 + +int +main(void) +{ + struct passwd pw, *pwp; + char buf[BUFLEN]; + int i; + + setpwent(); + while (1) { + i = getpwent_r(&pw, buf, BUFLEN, &pwp); + if (i) + break; + printf("%s (%d)\etHOME %s\etSHELL %s\en", pwp\->pw_name, + pwp\->pw_uid, pwp\->pw_dir, pwp\->pw_shell); + } + endpwent(); + exit(EXIT_SUCCESS); +} +.EE +.\" perhaps add error checking - should use strerror_r +.\" #include +.\" #include +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getpwent_r: %s", strerror(i)); +.\" exit(EXIT_SUCCESS); +.\" } +.SH SEE ALSO +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getpwnam.3 b/man3/getpwnam.3 new file mode 100644 index 0000000..849eb08 --- /dev/null +++ b/man3/getpwnam.3 @@ -0,0 +1,348 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-05-27 by Martin Schulze (joey@linux.de) +.\" Modified 2003-11-15 by aeb +.\" 2008-11-07, mtk, Added an example program for getpwnam_r(). +.\" +.TH GETPWNAM 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "struct passwd *getpwnam(const char *" name ); +.PP +.BI "struct passwd *getpwuid(uid_t " uid ); +.PP +.BI "int getpwnam_r(const char *" name ", struct passwd *" pwd , +.BI " char *" buf ", size_t " buflen ", struct passwd **" result ); +.PP +.BI "int getpwuid_r(uid_t " uid ", struct passwd *" pwd , +.BI " char *" buf ", size_t " buflen ", struct passwd **" result ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR getpwnam_r (), +.BR getpwuid_r (): +.RS 4 +_POSIX_C_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR getpwnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the password database +(e.g., the local password file +.IR /etc/passwd , +NIS, and LDAP) +that matches the username +.IR name . +.PP +The +.BR getpwuid () +function returns a pointer to a structure containing +the broken-out fields of the record in the password database +that matches the user ID +.IR uid . +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.PP +See +.BR passwd (5) +for more information about these fields. +.PP +The +.BR getpwnam_r () +and +.BR getpwuid_r () +functions obtain the same information as +.BR getpwnam () +and +.BR getpwuid (), +but store the retrieved +.I passwd +structure in the space pointed to by +.IR pwd . +The string fields pointed to by the members of the +.I passwd +structure are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *result . +.PP +The call +.PP + sysconf(_SC_GETPW_R_SIZE_MAX) +.PP +returns either \-1, without changing +.IR errno , +or an initial suggested size for +.IR buf . +(If this size is too small, +the call fails with +.BR ERANGE , +in which case the caller can retry with a larger buffer.) +.SH RETURN VALUE +The +.BR getpwnam () +and +.BR getpwuid () +functions return a pointer to a +.I passwd +structure, or NULL if the matching entry is not found or +an error occurs. +If an error occurs, +.I errno +is set appropriately. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.PP +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getpwent (3), +.BR getpwnam (), +or +.BR getpwuid (). +(Do not pass the returned pointer to +.BR free (3).) +.PP +On success, +.BR getpwnam_r () +and +.BR getpwuid_r () +return zero, and set +.IR *result +to +.IR pwd . +If no matching password record was found, +these functions return 0 and store NULL in +.IR *result . +In case of error, an error number is returned, and NULL is stored in +.IR *result . +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... " +The given +.I name +or +.I uid +was not found. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I passwd +structure. +.\" This structure is static, allocated 0 or 1 times. No memory leak. (libc45) +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/passwd +local password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getpwnam () +T} Thread safety MT-Unsafe race:pwnam locale +T{ +.BR getpwuid () +T} Thread safety MT-Unsafe race:pwuid locale +T{ +.BR getpwnam_r (), +.br +.BR getpwuid_r () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +The +.I pw_gecos +field is not specified in POSIX, but is present on most implementations. +.SH NOTES +The formulation given above under "RETURN VALUE" is from POSIX.1-2001. +It does not call "not found" an error, and hence does not specify what value +.I errno +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX +.I errno +should be left unchanged if an entry is not found. +Experiments on various +UNIX-like systems show that lots of different values occur in this +situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc up to version 2.6, Irix 6.5 - give ENOENT +.\" glibc since version 2.7 - give 0 +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.PP +The +.I pw_dir +field contains the name of the initial working directory of the user. +Login programs use the value of this field to initialize the +.B HOME +environment variable for the login shell. +An application that wants to determine its user's home directory +should inspect the value of +.B HOME +(rather than the value +.IR getpwuid(getuid())\->pw_dir ) +since this allows the user to modify their notion of +"the home directory" during a login session. +To determine the (initial) home directory of another user, +it is necessary to use +.I getpwnam("username")\->pw_dir +or similar. +.SH EXAMPLE +The program below demonstrates the use of +.BR getpwnam_r () +to find the full username and user ID for the username +supplied as a command-line argument. +.PP +.EX +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct passwd pwd; + struct passwd *result; + char *buf; + size_t bufsize; + int s; + + if (argc != 2) { + fprintf(stderr, "Usage: %s username\\n", argv[0]); + exit(EXIT_FAILURE); + } + + bufsize = sysconf(_SC_GETPW_R_SIZE_MAX); + if (bufsize == \-1) /* Value was indeterminate */ + bufsize = 16384; /* Should be more than enough */ + + buf = malloc(bufsize); + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + + s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result); + if (result == NULL) { + if (s == 0) + printf("Not found\\n"); + else { + errno = s; + perror("getpwnam_r"); + } + exit(EXIT_FAILURE); + } + + printf("Name: %s; UID: %ld\\n", pwd.pw_gecos, (long) pwd.pw_uid); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getgrnam (3), +.BR getpw (3), +.BR getpwent (3), +.BR getspnam (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getpwnam_r.3 b/man3/getpwnam_r.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man3/getpwnam_r.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man3/getpwuid.3 b/man3/getpwuid.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man3/getpwuid.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man3/getpwuid_r.3 b/man3/getpwuid_r.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man3/getpwuid_r.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man3/getrpcbyname.3 b/man3/getrpcbyname.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man3/getrpcbyname.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man3/getrpcbyname_r.3 b/man3/getrpcbyname_r.3 new file mode 100644 index 0000000..78323ea --- /dev/null +++ b/man3/getrpcbyname_r.3 @@ -0,0 +1 @@ +.so man3/getrpcent_r.3 diff --git a/man3/getrpcbynumber.3 b/man3/getrpcbynumber.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man3/getrpcbynumber.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man3/getrpcbynumber_r.3 b/man3/getrpcbynumber_r.3 new file mode 100644 index 0000000..78323ea --- /dev/null +++ b/man3/getrpcbynumber_r.3 @@ -0,0 +1 @@ +.so man3/getrpcent_r.3 diff --git a/man3/getrpcent.3 b/man3/getrpcent.3 new file mode 100644 index 0000000..5b04e07 --- /dev/null +++ b/man3/getrpcent.3 @@ -0,0 +1,143 @@ +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI +.TH GETRPCENT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +getrpcent, getrpcbyname, getrpcbynumber, setrpcent, endrpcent \- get +RPC entry +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "struct rpcent *getrpcent(void);" +.PP +.BI "struct rpcent *getrpcbyname(const char *" name ); +.PP +.BI "struct rpcent *getrpcbynumber(int " number ); +.PP +.BI "void setrpcent(int " stayopen ); +.PP +.BI "void endrpcent(void);" +.fi +.SH DESCRIPTION +.PP +The +.BR getrpcent (), +.BR getrpcbyname (), +and +.BR getrpcbynumber () +functions each return a pointer to an object with the +following structure containing the broken-out +fields of an entry in the RPC program number data base. +.PP +.in +4n +.EX +struct rpcent { + char *r_name; /* name of server for this RPC program */ + char **r_aliases; /* alias list */ + long r_number; /* RPC program number */ +}; +.EE +.in +.PP +The members of this structure are: +.RS 4 +.TP 12 +.I r_name +The name of the server for this RPC program. +.TP +.I r_aliases +A NULL-terminated list of alternate names for the RPC program. +.TP +.I r_number +The RPC program number for this service. +.RE +.PP +The +.BR getrpcent () +function reads the next entry from the database. +A connection is opened to the database if necessary. +.PP +The +.BR setrpcent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getrpc* () +functions. +.PP +The +.BR endrpcent () +function closes the connection to the database. +.PP +The +.BR getrpcbyname () +and +.BR getrpcbynumber () +functions sequentially search from the beginning +of the file until a matching RPC program name or +program number is found, or until end-of-file is encountered. +.SH RETURN VALUE +On success, +.BR getrpcent (), +.BR getrpcbyname (), +and +.BR getrpcbynumber () +return a pointer to a statically allocated +.I rpcent +structure. +NULL is returned on EOF or error. +.SH FILES +.TP +.I /etc/rpc +RPC program number database. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR getrpcent (), +.BR getrpcbyname (), +.br +.BR getrpcbynumber () +T} Thread safety MT-Unsafe +T{ +.BR setrpcent (), +.BR endrpcent () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs, Solaris, and many other systems. +.SH BUGS +All information +is contained in a static area +so it must be copied if it is +to be saved. +.SH SEE ALSO +.BR getrpcent_r (3), +.BR rpc (5), +.BR rpcinfo (8), +.BR ypserv (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getrpcent_r.3 b/man3/getrpcent_r.3 new file mode 100644 index 0000000..d92603e --- /dev/null +++ b/man3/getrpcent_r.3 @@ -0,0 +1,162 @@ +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETRPCENT_R 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getrpcent_r, getrpcbyname_r, getrpcbynumber_r \- get +RPC entry (reentrant) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getrpcent_r(struct rpcent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct rpcent **" result ); +.PP +.BI "int getrpcbyname_r(const char *" name , +.BI " struct rpcent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct rpcent **" result ); +.PP +.BI "int getrpcbynumber_r(int " number , +.BI " struct rpcent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct rpcent **" result ); +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getrpcent_r (), +.BR getrpcbyname_r (), +.BR getrpcbynumber_r (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.ad b +.SH DESCRIPTION +The +.BR getrpcent_r (), +.BR getrpcbyname_r (), +and +.BR getrpcbynumber_r () +functions are the reentrant equivalents of, respectively, +.BR getrpcent (3), +.BR getrpcbyname (3), +and +.BR getrpcbynumber (3). +They differ in the way that the +.I rpcent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.PP +Instead of returning a pointer to a statically allocated +.I rpcent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.PP +The +.I buf +array is used to store the string fields pointed to by the returned +.I rpcent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.PP +If the function call successfully obtains an RPC record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.PP +On error, record not found +.RB ( getrpcbyname_r (), +.BR getrpcbynumber_r ()), +or end of input +.RB ( getrpcent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getrpcent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR getrpcent_r (), +.BR getrpcbyname_r (), +.BR getrpcbynumber_r () +T} Thread safety MT-Safe locale +.TE +.ad +.SH CONFORMING TO +These functions are GNU extensions. +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH SEE ALSO +.BR getrpcent (3), +.BR rpc (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getrpcport.3 b/man3/getrpcport.3 new file mode 100644 index 0000000..74521d7 --- /dev/null +++ b/man3/getrpcport.3 @@ -0,0 +1,62 @@ +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI +.TH GETRPCPORT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +getrpcport \- get RPC port number +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "int getrpcport(const char *" host ", unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned " proto ); +.fi +.SH DESCRIPTION +.BR getrpcport () +returns the port number for version +.I versnum +of the RPC program +.I prognum +running on +.I host +and using protocol +.IR proto . +It returns 0 if it cannot contact the portmapper, or if +.I prognum +is not registered. +If +.I prognum +is registered but not with version +.IR versnum , +it will still return a port number (for some version of the program) +indicating that the program is indeed registered. +The version mismatch will be detected upon the first call to the service. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getrpcport () +T} Thread safety MT-Safe env locale +.TE +.sp 1 +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs, Solaris, and many other systems. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/gets.3 b/man3/gets.3 new file mode 100644 index 0000000..7434efa --- /dev/null +++ b/man3/gets.3 @@ -0,0 +1,129 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 2013-12-31, David Malcolm +.\" Split gets(3) into its own page; fgetc() et al. move to fgetc(3) +.TH GETS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +gets \- get a string from standard input (DEPRECATED) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *gets(char *" "s" ); +.fi +.SH DESCRIPTION +.IR "Never use this function" . +.PP +.BR gets () +reads a line from +.I stdin +into the buffer pointed to by +.I s +until either a terminating newline or +.BR EOF , +which it replaces with a null byte (\(aq\e0\(aq). +No check for buffer overrun is performed (see BUGS below). +.SH RETURN VALUE +.BR gets () +returns +.I s +on success, and NULL +on error or when end of file occurs while no characters have been read. +However, given the lack of buffer overrun checking, there can be no +guarantees that the function will even return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR gets () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C89, C99, POSIX.1-2001. +.PP +LSB deprecates +.BR gets (). +POSIX.1-2008 marks +.BR gets () +obsolescent. +ISO C11 removes the specification of +.BR gets () +from the C language, and since version 2.16, +glibc header files don't expose the function declaration if the +.B _ISOC11_SOURCE +feature test macro is defined. +.SH BUGS +Never use +.BR gets (). +Because it is impossible to tell without knowing the data in advance how many +characters +.BR gets () +will read, and because +.BR gets () +will continue to store characters past the end of the buffer, +it is extremely dangerous to use. +It has been used to break computer security. +Use +.BR fgets () +instead. +.PP +For more information, see CWE-242 (aka "Use of Inherently Dangerous +Function") at +http://cwe.mitre.org/data/definitions/242.html +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR ferror (3), +.BR fgetc (3), +.BR fgets (3), +.BR fgetwc (3), +.BR fgetws (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR getline (3), +.BR getwchar (3), +.BR puts (3), +.BR scanf (3), +.BR ungetwc (3), +.BR unlocked_stdio (3), +.BR feature_test_macros (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getservbyname.3 b/man3/getservbyname.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man3/getservbyname.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man3/getservbyname_r.3 b/man3/getservbyname_r.3 new file mode 100644 index 0000000..b36a442 --- /dev/null +++ b/man3/getservbyname_r.3 @@ -0,0 +1 @@ +.so man3/getservent_r.3 diff --git a/man3/getservbyport.3 b/man3/getservbyport.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man3/getservbyport.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man3/getservbyport_r.3 b/man3/getservbyport_r.3 new file mode 100644 index 0000000..b36a442 --- /dev/null +++ b/man3/getservbyport_r.3 @@ -0,0 +1 @@ +.so man3/getservent_r.3 diff --git a/man3/getservent.3 b/man3/getservent.3 new file mode 100644 index 0000000..7859191 --- /dev/null +++ b/man3/getservent.3 @@ -0,0 +1,223 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Oct 18 20:23:54 1995 by Martin Schulze +.\" Modified Mon Apr 22 01:50:54 1996 by Martin Schulze +.\" 2001-07-25 added a clause about NULL proto (Martin Michlmayr or David N. Welton) +.\" +.TH GETSERVENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getservent, getservbyname, getservbyport, setservent, endservent \- +get service entry +.SH SYNOPSIS +.nf +.B #include +.PP +.B struct servent *getservent(void); +.PP +.BI "struct servent *getservbyname(const char *" name ", const char *" proto ); +.PP +.BI "struct servent *getservbyport(int " port ", const char *" proto ); +.PP +.BI "void setservent(int " stayopen ); +.PP +.B void endservent(void); +.fi +.SH DESCRIPTION +The +.BR getservent () +function reads the next entry from the services database (see +.BR services (5)) +and returns a +.I servent +structure containing +the broken-out fields from the entry. +A connection is opened to the database if necessary. +.PP +The +.BR getservbyname () +function returns a +.I servent +structure +for the entry from the database +that matches the service +.I name +using protocol +.IR proto . +If +.I proto +is NULL, any protocol will be matched. +A connection is opened to the database if necessary. +.PP +The +.BR getservbyport () +function returns a +.I servent +structure +for the entry from the database +that matches the port +.I port +(given in network byte order) +using protocol +.IR proto . +If +.I proto +is NULL, any protocol will be matched. +A connection is opened to the database if necessary. +.PP +The +.BR setservent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getserv* () +functions. +.PP +The +.BR endservent () +function closes the connection to the database. +.PP +The +.I servent +structure is defined in +.I +as follows: +.PP +.in +4n +.EX +struct servent { + char *s_name; /* official service name */ + char **s_aliases; /* alias list */ + int s_port; /* port number */ + char *s_proto; /* protocol to use */ +} +.EE +.in +.PP +The members of the +.I servent +structure are: +.TP +.I s_name +The official name of the service. +.TP +.I s_aliases +A NULL-terminated list of alternative names for the service. +.TP +.I s_port +The port number for the service given in network byte order. +.TP +.I s_proto +The name of the protocol to use with this service. +.SH RETURN VALUE +The +.BR getservent (), +.BR getservbyname () +and +.BR getservbyport () +functions return a pointer to a +statically allocated +.I servent +structure, or NULL if an +error occurs or the end of the file is reached. +.SH FILES +.TP +.I /etc/services +services database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw15 lb lbw25 +l l l. +Interface Attribute Value +T{ +.BR getservent () +T} Thread safety T{ +MT-Unsafe race:servent +.br +race:serventbuf locale +T} +T{ +.BR getservbyname () +T} Thread safety T{ +MT-Unsafe race:servbyname +.br +locale +T} +T{ +.BR getservbyport () +T} Thread safety T{ +MT-Unsafe race:servbyport +.br +locale +T} +T{ +.BR setservent (), +.br +.BR endservent () +T} Thread safety T{ +MT-Unsafe race:servent +.br +locale +T} +.TE +.sp 1 +In the above table, +.I servent +in +.I race:servent +signifies that if any of the functions +.BR setservent (), +.BR getservent (), +or +.BR endservent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH SEE ALSO +.BR getnetent (3), +.BR getprotoent (3), +.BR getservent_r (3), +.BR services (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getservent_r.3 b/man3/getservent_r.3 new file mode 100644 index 0000000..7abf930 --- /dev/null +++ b/man3/getservent_r.3 @@ -0,0 +1,269 @@ +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETSERVENT_R 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getservent_r, getservbyname_r, getservbyport_r \- get +service entry (reentrant) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getservent_r(struct servent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct servent **" result ); +.PP +.BI "int getservbyname_r(const char *" name ", const char *" proto , +.BI " struct servent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct servent **" result ); +.PP +.BI "int getservbyport_r(int " port ", const char *" proto , +.BI " struct servent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct servent **" result ); +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getservent_r (), +.BR getservbyname_r (), +.BR getservbyport_r (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.ad b +.SH DESCRIPTION +The +.BR getservent_r (), +.BR getservbyname_r (), +and +.BR getservbyport_r () +functions are the reentrant equivalents of, respectively, +.BR getservent (3), +.BR getservbyname (3), +and +.BR getservbyport (3). +They differ in the way that the +.I servent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.PP +Instead of returning a pointer to a statically allocated +.I servent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.PP +The +.I buf +array is used to store the string fields pointed to by the returned +.I servent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.PP +If the function call successfully obtains a service record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in errors. +.PP +On error, record not found +.RB ( getservbyname_r (), +.BR getservbyport_r ()), +or end of input +.RB ( getservent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getservent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw18 lb lb +l l l. +Interface Attribute Value +T{ +.BR getservent_r (), +.BR getservbyname_r (), +.BR getservbyport_r () +T} Thread safety MT-Safe locale +.TE +.ad +.SH CONFORMING TO +These functions are GNU extensions. +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH EXAMPLE +The program below uses +.BR getservbyport_r () +to retrieve the service record for the port and protocol named +in its first command-line argument. +If a third (integer) command-line argument is supplied, +it is used as the initial value for +.IR buflen ; +if +.BR getservbyport_r () +fails with the error +.BR ERANGE , +the program retries with larger buffer sizes. +The following shell session shows a couple of sample runs: +.PP +.in +4n +.EX +.RB "$" " ./a.out 7 tcp 1" +ERANGE! Retrying with larger buffer +getservbyport_r() returned: 0 (success) (buflen=87) +s_name=echo; s_proto=tcp; s_port=7; aliases= +.RB "$" " ./a.out 77777 tcp" +getservbyport_r() returned: 0 (success) (buflen=1024) +Call failed/record not found +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +#define MAX_BUF 10000 + +int +main(int argc, char *argv[]) +{ + int buflen, erange_cnt, port, s; + struct servent result_buf; + struct servent *result; + char buf[MAX_BUF]; + char *protop; + char **p; + + if (argc < 3) { + printf("Usage: %s port\-num proto\-name [buflen]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + port = htons(atoi(argv[1])); + protop = (strcmp(argv[2], "null") == 0 || + strcmp(argv[2], "NULL") == 0) ? NULL : argv[2]; + + buflen = 1024; + if (argc > 3) + buflen = atoi(argv[3]); + + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\\n", MAX_BUF); + exit(EXIT_FAILURE); + } + + erange_cnt = 0; + do { + s = getservbyport_r(port, protop, &result_buf, + buf, buflen, &result); + if (s == ERANGE) { + if (erange_cnt == 0) + printf("ERANGE! Retrying with larger buffer\\n"); + erange_cnt++; + + /* Increment a byte at a time so we can see exactly + what size buffer was required */ + + buflen++; + + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\\n", MAX_BUF); + exit(EXIT_FAILURE); + } + } + } while (s == ERANGE); + + printf("getservbyport_r() returned: %s (buflen=%d)\\n", + (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" : + strerror(s), buflen); + + if (s != 0 || result == NULL) { + printf("Call failed/record not found\\n"); + exit(EXIT_FAILURE); + } + + printf("s_name=%s; s_proto=%s; s_port=%d; aliases=", + result_buf.s_name, result_buf.s_proto, + ntohs(result_buf.s_port)); + for (p = result_buf.s_aliases; *p != NULL; p++) + printf("%s ", *p); + printf("\\n"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getservent (3), +.BR services (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getspent.3 b/man3/getspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/getspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/getspent_r.3 b/man3/getspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/getspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/getspnam.3 b/man3/getspnam.3 new file mode 100644 index 0000000..d050ab4 --- /dev/null +++ b/man3/getspnam.3 @@ -0,0 +1,324 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and +.\" Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH GETSPNAM 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, +fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, +lckpwdf, ulckpwdf \- get shadow password file entry +.SH SYNOPSIS +.nf +/* General shadow password file API */ +.B #include +.PP +.BI "struct spwd *getspnam(const char *" name ); +.PP +.B struct spwd *getspent(void); +.PP +.B void setspent(void); +.PP +.B void endspent(void); +.PP +.BI "struct spwd *fgetspent(FILE *" stream ); +.PP +.BI "struct spwd *sgetspent(const char *" s ); +.PP +.BI "int putspent(const struct spwd *" p ", FILE *" stream ); +.PP +.B int lckpwdf(void); +.PP +.B int ulckpwdf(void); + +/* GNU extension */ +.B #include +.PP +.BI "int getspent_r(struct spwd *" spbuf , +.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); +.PP +.BI "int getspnam_r(const char *" name ", struct spwd *" spbuf , +.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); +.PP +.BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf , +.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); +.PP +.BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf , +.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR getspent_r (), +.BR getspnam_r (), +.BR fgetspent_r (), +.BR sgetspent_r (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.ad b +.SH DESCRIPTION +Long ago it was considered safe to have encrypted passwords openly +visible in the password file. +When computers got faster and people +got more security-conscious, this was no longer acceptable. +Julianne Frances Haugh implemented the shadow password suite +that keeps the encrypted passwords in +the shadow password database +(e.g., the local shadow password file +.IR /etc/shadow , +NIS, and LDAP), +readable only by root. +.PP +The functions described below resemble those for +the traditional password database +(e.g., see +.BR getpwnam (3) +and +.BR getpwent (3)). +.\" FIXME . I've commented out the following for the +.\" moment. The relationship between PAM and nsswitch.conf needs +.\" to be clearly documented in one place, which is pointed to by +.\" the pages for the user, group, and shadow password functions. +.\" (Jul 2005, mtk) +.\" +.\" This shadow password setup has been superseded by PAM +.\" (pluggable authentication modules), and the file +.\" .I /etc/nsswitch.conf +.\" now describes the sources to be used. +.PP +The +.BR getspnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the shadow password database +that matches the username +.IR name . +.PP +The +.BR getspent () +function returns a pointer to the next entry in the shadow password +database. +The position in the input stream is initialized by +.BR setspent (). +When done reading, the program may call +.BR endspent () +so that resources can be deallocated. +.\" some systems require a call of setspent() before the first getspent() +.\" glibc does not +.PP +The +.BR fgetspent () +function is similar to +.BR getspent () +but uses the supplied stream instead of the one implicitly opened by +.BR setspent (). +.PP +The +.BR sgetspent () +function parses the supplied string +.I s +into a struct +.IR spwd . +.PP +The +.BR putspent () +function writes the contents of the supplied struct +.I spwd +.I *p +as a text line in the shadow password file format to +.IR stream . +String entries with value NULL and numerical entries with value \-1 +are written as an empty string. +.PP +The +.BR lckpwdf () +function is intended to protect against multiple simultaneous accesses +of the shadow password database. +It tries to acquire a lock, and returns 0 on success, +or \-1 on failure (lock not obtained within 15 seconds). +The +.BR ulckpwdf () +function releases the lock again. +Note that there is no protection against direct access of the shadow +password file. +Only programs that use +.BR lckpwdf () +will notice the lock. +.PP +These were the functions that formed the original shadow API. +They are widely available. +.\" Also in libc5 +.\" SUN doesn't have sgetspent() +.SS Reentrant versions +Analogous to the reentrant functions for the password database, glibc +also has reentrant functions for the shadow password database. +The +.BR getspnam_r () +function is like +.BR getspnam () +but stores the retrieved shadow password structure in the space pointed to by +.IR spbuf . +This shadow password structure contains pointers to strings, and these strings +are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *spbufp . +.PP +The functions +.BR getspent_r (), +.BR fgetspent_r (), +and +.BR sgetspent_r () +are similarly analogous to their nonreentrant counterparts. +.PP +Some non-glibc systems also have functions with these names, +often with different prototypes. +.\" SUN doesn't have sgetspent_r() +.SS Structure +The shadow password structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct spwd { + char *sp_namp; /* Login name */ + char *sp_pwdp; /* Encrypted password */ + long sp_lstchg; /* Date of last change + (measured in days since + 1970-01-01 00:00:00 +0000 (UTC)) */ + long sp_min; /* Min # of days between changes */ + long sp_max; /* Max # of days between changes */ + long sp_warn; /* # of days before password expires + to warn user to change it */ + long sp_inact; /* # of days after password expires + until account is disabled */ + long sp_expire; /* Date when account expires + (measured in days since + 1970-01-01 00:00:00 +0000 (UTC)) */ + unsigned long sp_flag; /* Reserved */ +}; +.EE +.in +.SH RETURN VALUE +The functions that return a pointer return NULL if no more entries +are available or if an error occurs during processing. +The functions which have \fIint\fP as the return value return 0 for +success and \-1 for failure, with +.I errno +set to indicate the cause of the error. +.PP +For the nonreentrant functions, the return value may point to static area, +and may be overwritten by subsequent calls to these functions. +.PP +The reentrant functions return zero on success. +In case of error, an error number is returned. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to access the shadow password file. +.TP +.B ERANGE +Supplied buffer is too small. +.SH FILES +.TP +.I /etc/shadow +local shadow password database file +.TP +.I /etc/.pwd.lock +lock file +.PP +The include file +.I +defines the constant +.B _PATH_SHADOW +to the pathname of the shadow password file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw13 lb lbw30 +l l l. +Interface Attribute Value +T{ +.BR getspnam () +T} Thread safety T{ +MT-Unsafe race:getspnam locale +T} +T{ +.BR getspent () +T} Thread safety T{ +MT-Unsafe race:getspent +.br +race:spentbuf locale +T} +T{ +.BR setspent (), +.br +.BR endspent (), +.br +.BR getspent_r () +T} Thread safety T{ +MT-Unsafe race:getspent locale +T} +T{ +.BR fgetspent () +T} Thread safety MT-Unsafe race:fgetspent +T{ +.BR sgetspent () +T} Thread safety MT-Unsafe race:sgetspent +T{ +.BR putspent (), +.br +.BR getspnam_r (), +.br +.BR sgetspent_r () +T} Thread safety MT-Safe locale +T{ +.BR lckpwdf (), +.br +.BR ulckpwdf (), +.br +.BR fgetspent_r () +T} Thread safety MT-Safe +.TE +.sp 1 +In the above table, +.I getspent +in +.I race:getspent +signifies that if any of the functions +.BR setspent (), +.BR getspent (), +.BR getspent_r (), +or +.BR endspent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +The shadow password database and its associated API are +not specified in POSIX.1. +However, many other systems provide a similar API. +.SH SEE ALSO +.BR getgrnam (3), +.BR getpwnam (3), +.BR getpwnam_r (3), +.BR shadow (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getspnam_r.3 b/man3/getspnam_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/getspnam_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/getsubopt.3 b/man3/getsubopt.3 new file mode 100644 index 0000000..5b011a5 --- /dev/null +++ b/man3/getsubopt.3 @@ -0,0 +1,251 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" and Copyright (C) 2007 Justin Pryzby +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.TH GETSUBOPT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getsubopt \- parse suboption arguments from a string +.SH SYNOPSIS +.B #include +.PP +.BI "int getsubopt(char **"optionp ", char * const *" tokens \ +", char **" valuep ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getsubopt (): +.ad l +.RS 4 +.PD 0 +_XOPEN_SOURCE\ >= 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.br + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L +.PD +.RE +.ad +.SH DESCRIPTION +.BR getsubopt () +parses the list of comma-separated suboptions provided in +.IR optionp . +(Such a suboption list is typically produced when +.BR getopt (3) +is used to parse a command line; +see for example the \fI-o\fP option of +.BR mount (8).) +Each suboption may include an associated value, +which is separated from the suboption name by an equal sign. +The following is an example of the kind of string +that might be passed in +.IR optionp : +.PP +.in +4n +.EX +.B ro,name=xyz +.EE +.in +.PP +The +.I tokens +argument is a pointer to a NULL-terminated array of pointers to the tokens that +.BR getsubopt () +will look for in +.IR optionp . +The tokens should be distinct, null-terminated strings containing at +least one character, with no embedded equal signs or commas. +.PP +Each call to +.BR getsubopt () +returns information about the next unprocessed suboption in +.IR optionp . +The first equal sign in a suboption (if any) is interpreted as a +separator between the name and the value of that suboption. +The value extends to the next comma, +or (for the last suboption) to the end of the string. +If the name of the suboption matches a known name from +.IR tokens , +and a value string was found, +.BR getsubopt () +sets +.I *valuep +to the address of that string. +The first comma in +.I optionp +is overwritten with a null byte, so +.I *valuep +is precisely the "value string" for that suboption. +.PP +If the suboption is recognized, but no value string was found, +.I *valuep +is set to NULL. +.PP +When +.BR getsubopt () +returns, +.I optionp +points to the next suboption, +or to the null byte (\(aq\\0\(aq) at the end of the +string if the last suboption was just processed. +.SH RETURN VALUE +If the first suboption in +.I optionp +is recognized, +.BR getsubopt () +returns the index of the matching suboption element in +.IR tokens . +Otherwise, \-1 is returned and +.I *valuep +is the entire +.IB name [= value ] +string. +.PP +Since +.I *optionp +is changed, the first suboption before the call to +.BR getsubopt () +is not (necessarily) the same as the first suboption after +.BR getsubopt (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getsubopt () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +.PP +Since +.BR getsubopt () +overwrites any commas it finds in the string +.IR *optionp , +that string must be writable; it cannot be a string constant. +.SH EXAMPLE +The following program expects suboptions following a "\-o" option. +.PP +.EX +#define _XOPEN_SOURCE 500 +#include +#include +#include + +int +main(int argc, char **argv) +{ + enum { + RO_OPT = 0, + RW_OPT, + NAME_OPT + }; + char *const token[] = { + [RO_OPT] = "ro", + [RW_OPT] = "rw", + [NAME_OPT] = "name", + NULL + }; + char *subopts; + char *value; + int opt; + + int readonly = 0; + int readwrite = 0; + char *name = NULL; + int errfnd = 0; + + while ((opt = getopt(argc, argv, "o:")) != \-1) { + switch (opt) { + case \(aqo\(aq: + subopts = optarg; + while (*subopts != \(aq\\0\(aq && !errfnd) { + + switch (getsubopt(&subopts, token, &value)) { + case RO_OPT: + readonly = 1; + break; + + case RW_OPT: + readwrite = 1; + break; + + case NAME_OPT: + if (value == NULL) { + fprintf(stderr, "Missing value for " + "suboption \(aq%s\(aq\\n", token[NAME_OPT]); + errfnd = 1; + continue; + } + + name = value; + break; + + default: + fprintf(stderr, "No match found " + "for token: /%s/\\n", value); + errfnd = 1; + break; + } + } + if (readwrite && readonly) { + fprintf(stderr, "Only one of \(aq%s\(aq and \(aq%s\(aq can be " + "specified\\n", token[RO_OPT], token[RW_OPT]); + errfnd = 1; + } + break; + + default: + errfnd = 1; + } + } + + if (errfnd || argc == 1) { + fprintf(stderr, "\\nUsage: %s \-o \\n", argv[0]); + fprintf(stderr, "suboptions are \(aqro\(aq, \(aqrw\(aq, " + "and \(aqname=\(aq\\n"); + exit(EXIT_FAILURE); + } + + /* Remainder of program... */ + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getopt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getttyent.3 b/man3/getttyent.3 new file mode 100644 index 0000000..7802419 --- /dev/null +++ b/man3/getttyent.3 @@ -0,0 +1,106 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH GETTTYENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getttyent, getttynam, setttyent, endttyent \- get ttys file entry +.SH SYNOPSIS +.B "#include " +.PP +.B "struct ttyent *getttyent(void);" +.PP +.BI "struct ttyent *getttynam(const char *" name ); +.PP +.B "int setttyent(void);" +.PP +.B "int endttyent(void);" +.SH DESCRIPTION +These functions provide an interface to the file +.B _PATH_TTYS +(e.g., +.IR /etc/ttys ). +.PP +The function +.BR setttyent () +opens the file or rewinds it if already open. +.PP +The function +.BR endttyent () +closes the file. +.PP +The function +.BR getttynam () +searches for a given terminal name in the file. +It returns a pointer to a +.I ttyent +structure (description below). +.PP +The function +.BR getttyent () +opens the file +.B _PATH_TTYS +(if necessary) and returns the first entry. +If the file is already open, the next entry. +The +.I ttyent +structure has the form: +.PP +.in +4n +.EX +struct ttyent { + char *ty_name; /* terminal device name */ + char *ty_getty; /* command to execute, usually getty */ + char *ty_type; /* terminal type for termcap */ + int ty_status; /* status flags */ + char *ty_window; /* command to start up window manager */ + char *ty_comment; /* comment field */ +}; +.EE +.in +.PP +.I ty_status +can be: +.PP +.in +4n +.EX +#define TTY_ON 0x01 /* enable logins (start ty_getty program) */ +#define TTY_SECURE 0x02 /* allow UID 0 to login */ +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR getttyent (), +.BR setttyent (), +.BR endttyent (), +.BR getttynam () +T} Thread safety MT-Unsafe race:ttyent +.TE +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs, and perhaps other systems. +.SH NOTES +Under Linux, the file +.IR /etc/ttys , +and the functions described above, are not used. +.SH SEE ALSO +.BR ttyname (3), +.BR ttyslot (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getttynam.3 b/man3/getttynam.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man3/getttynam.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man3/getumask.3 b/man3/getumask.3 new file mode 100644 index 0000000..0eab863 --- /dev/null +++ b/man3/getumask.3 @@ -0,0 +1,76 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH GETUMASK 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getumask \- get file creation mask +.SH SYNOPSIS +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.br +.B "#include " +.br +.B "#include " +.PP +.B "mode_t getumask(void);" +.SH DESCRIPTION +This function returns the current file creation mask. +It is equivalent to +.PP +.in +4n +.EX +mode_t getumask(void) +{ + mode_t mask = umask( 0 ); + umask(mask); + return mask; +} +.EE +.in +.PP +except that it is documented to be thread-safe (that is, shares +a lock with the +.BR umask (2) +library call). +.SH CONFORMING TO +This is a vaporware GNU extension. +.SH NOTES +This function is documented in the glibc manual, but, +as at glibc version 2.24, it is not implemented on Linux. +(See +.BR umask (2) +for a thread-safe method of discovering a process's umask.) +.SH SEE ALSO +.BR umask (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getusershell.3 b/man3/getusershell.3 new file mode 100644 index 0000000..94c0503 --- /dev/null +++ b/man3/getusershell.3 @@ -0,0 +1,126 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:17:53 1993 by Rik Faith (faith@cs.unc.edu) +.TH GETUSERSHELL 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getusershell, setusershell, endusershell \- get permitted user shells +.SH SYNOPSIS +.nf +.B #include +.PP +.B char *getusershell(void); +.PP +.B void setusershell(void); +.PP +.B void endusershell(void); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR getusershell (), +.BR setusershell (), +.BR endusershell (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.fi +.ad b +.SH DESCRIPTION +The +.BR getusershell () +function returns the next line from the file +.IR /etc/shells , +opening the file if necessary. +The line should contain +the pathname of a valid user shell. +If +.I /etc/shells +does not exist or +is unreadable, +.BR getusershell () +behaves as if +.I /bin/sh +and +.I /bin/csh +were listed in the file. +.PP +The +.BR setusershell () +function rewinds +.IR /etc/shells . +.PP +The +.BR endusershell () +function closes +.IR /etc/shells . +.SH RETURN VALUE +The +.BR getusershell () +function returns NULL on end-of-file. +.SH FILES +.nf +/etc/shells +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR getusershell (), +.BR setusershell (), +.br +.BR endusershell () +T} Thread safety MT-Unsafe +.TE +.SH CONFORMING TO +4.3BSD. +.SH SEE ALSO +.BR shells (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getutent.3 b/man3/getutent.3 new file mode 100644 index 0000000..831358b --- /dev/null +++ b/man3/getutent.3 @@ -0,0 +1,372 @@ +.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Solaris manpages +.\" +.\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt +.\" +.\" +.TH GETUTENT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +getutent, getutid, getutline, pututline, setutent, endutent, +utmpname \- access utmp file entries +.SH SYNOPSIS +.B #include +.PP +.B struct utmp *getutent(void); +.br +.BI "struct utmp *getutid(const struct utmp *" ut ); +.br +.BI "struct utmp *getutline(const struct utmp *" ut ); +.PP +.BI "struct utmp *pututline(const struct utmp *" ut ); +.PP +.B void setutent(void); +.br +.B void endutent(void); +.PP +.BI "int utmpname(const char *" file ); +.SH DESCRIPTION +New applications should use the POSIX.1-specified "utmpx" versions of +these functions; see CONFORMING TO. +.PP +.BR utmpname () +sets the name of the utmp-format file for the other utmp +functions to access. +If +.BR utmpname () +is not used to set the filename +before the other functions are used, they assume \fB_PATH_UTMP\fP, as +defined in \fI\fP. +.PP +.BR setutent () +rewinds the file pointer to the beginning of the utmp file. +It is generally a good idea to call it before any of the other +functions. +.PP +.BR endutent () +closes the utmp file. +It should be called when the user +code is done accessing the file with the other functions. +.PP +.BR getutent () +reads a line from the current file position in the utmp file. +It returns a pointer to a structure containing the fields of +the line. +The definition of this structure is shown in +.BR utmp (5). +.PP +.BR getutid () +searches forward from the current file position in the utmp +file based upon \fIut\fP. +If \fIut\->ut_type\fP is one of \fBRUN_LVL\fP, +\fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, +.BR getutid () +will +find the first entry whose \fIut_type\fP field matches \fIut\->ut_type\fP. +If \fIut\->ut_type\fP is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, +\fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP, +.BR getutid () +will find the +first entry whose +.I ut_id +field matches \fIut\->ut_id\fP. +.PP +.BR getutline () +searches forward from the current file position in the utmp file. +It scans entries whose +.I ut_type +is \fBUSER_PROCESS\fP +or \fBLOGIN_PROCESS\fP and returns the first one whose +.I ut_line +field +matches \fIut\->ut_line\fP. +.PP +.BR pututline () +writes the +.I utmp +structure \fIut\fP into the utmp file. +It uses +.BR getutid () +to search for the proper place in the file to insert +the new entry. +If it cannot find an appropriate slot for \fIut\fP, +.BR pututline () +will append the new entry to the end of the file. +.SH RETURN VALUE +.BR getutent (), +.BR getutid (), +and +.BR getutline () +return a pointer to a \fIstruct utmp\fP on success, +and NULL on failure (which includes the "record not found" case). +This \fIstruct utmp\fP is allocated in static storage, and may be +overwritten by subsequent calls. +.PP +On success +.BR pututline () +returns +.IR ut ; +on failure, it returns NULL. +.PP +.BR utmpname () +returns 0 if the new name was successfully stored, or \-1 on failure. +.PP +In the event of an error, these functions +.I errno +set to indicate the cause. +.SH ERRORS +.TP +.B ENOMEM +Out of memory. +.TP +.B ESRCH +Record not found. +.PP +.BR setutent (), +.BR pututline (), +and the +.BR getut* () +functions can also fail for the reasons described in +.BR open (2). +.SH FILES +.TP +.I /var/run/utmp +database of currently logged-in users +.TP +.I /var/log/wtmp +database of past user logins +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw28 +l l l. +Interface Attribute Value +T{ +.BR getutent () +T} Thread safety T{ +MT-Unsafe init race:utent +.br +race:utentbuf sig:ALRM timer +T} +T{ +.BR getutid (), +.br +.BR getutline () +T} Thread safety T{ +MT-Unsafe init race:utent +.br +sig:ALRM timer +T} +T{ +.BR pututline () +T} Thread safety T{ +MT-Unsafe race:utent +.br +sig:ALRM timer +T} +T{ +.BR setutent (), +.br +.BR endutent (), +.br +.BR utmpname () +T} Thread safety MT-Unsafe race:utent +.TE +.sp 1 +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (), +.BR getutent (), +.BR getutid (), +.BR getutline (), +.BR pututline (), +.BR utmpname (), +or +.BR endutent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +XPG2, SVr4. +.PP +In XPG2 and SVID 2 the function +.BR pututline () +is documented to return void, and that is what it does on many systems +(AIX, HP-UX). +HP-UX introduces a new function +.BR _pututline () +with the prototype given above for +.BR pututline (). +.PP +All these functions are obsolete now on non-Linux systems. +POSIX.1-2001 and POSIX.1-2008, following SUSv1, +does not have any of these functions, but instead uses +.PP +.in +4n +.EX +.B #include +.PP +.B struct utmpx *getutxent(void); +.B struct utmpx *getutxid(const struct utmpx *); +.B struct utmpx *getutxline(const struct utmpx *); +.B struct utmpx *pututxline(const struct utmpx *); +.B void setutxent(void); +.B void endutxent(void); +.EE +.in +.PP +These functions are provided by glibc, +and perform the same task as their equivalents without the "x", but use +.IR "struct utmpx" , +defined on Linux to be the same as +.IR "struct utmp" . +For completeness, glibc also provides +.BR utmpxname (), +although this function is not specified by POSIX.1. +.PP +On some other systems, +the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, +with additional fields, and larger versions of the existing fields, +and parallel files are maintained, often +.I /var/*/utmpx +and +.IR /var/*/wtmpx . +.PP +Linux glibc on the other hand does not use a parallel \fIutmpx\fP file +since its \fIutmp\fP structure is already large enough. +The "x" functions listed above are just aliases for +their counterparts without the "x" (e.g., +.BR getutxent () +is an alias for +.BR getutent ()). +.SH NOTES +.SS Glibc notes +The above functions are not thread-safe. +Glibc adds reentrant versions +.PP +.in +4n +.EX +.B #include +.PP +.BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp ); +.PP +.BI "int getutid_r(struct utmp *" ut , +.BI " struct utmp *" ubuf ", struct utmp **" ubufp ); +.PP +.BI "int getutline_r(struct utmp *" ut , +.BI " struct utmp *" ubuf ", struct utmp **" ubufp ); +.EE +.in +.PP +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getutent_r (), +.BR getutid_r (), +.BR getutline_r (): +.nf + _GNU_SOURCE + || /* since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.PP +These functions are GNU extensions, analogs of the functions of the +same name without the _r suffix. +The +.I ubuf +argument gives these functions a place to store their result. +On success, they return 0, and a pointer to the result is written in +.IR *ubufp . +On error, these functions return \-1. +There are no utmpx equivalents of the above functions. +(POSIX.1 does not specify such functions.) +.SH EXAMPLE +The following example adds and removes a utmp record, assuming it is run +from within a pseudo terminal. +For usage in a real application, you +should check the return values of +.BR getpwuid (3) +and +.BR ttyname (3). +.PP +.EX +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct utmp entry; + + system("echo before adding entry:;who"); + + entry.ut_type = USER_PROCESS; + entry.ut_pid = getpid(); + strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/")); + /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */ + strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty")); + time(&entry.ut_time); + strcpy(entry.ut_user, getpwuid(getuid())\->pw_name); + memset(entry.ut_host, 0, UT_HOSTSIZE); + entry.ut_addr = 0; + setutent(); + pututline(&entry); + + system("echo after adding entry:;who"); + + entry.ut_type = DEAD_PROCESS; + memset(entry.ut_line, 0, UT_LINESIZE); + entry.ut_time = 0; + memset(entry.ut_user, 0, UT_NAMESIZE); + setutent(); + pututline(&entry); + + system("echo after removing entry:;who"); + + endutent(); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getutmp (3), +.BR utmp (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getutent_r.3 b/man3/getutent_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/getutent_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutid.3 b/man3/getutid.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/getutid.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutid_r.3 b/man3/getutid_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/getutid_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutline.3 b/man3/getutline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/getutline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutline_r.3 b/man3/getutline_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/getutline_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutmp.3 b/man3/getutmp.3 new file mode 100644 index 0000000..f50721b --- /dev/null +++ b/man3/getutmp.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETUTMP 3 2015-03-02 "Linux" "Linux Programmer's Manual" +.SH NAME +getutmp, getutmpx \- copy utmp structure to utmpx, and vice versa +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI " void getutmp(const struct utmpx *" ux ", struct utmp *" u ); +.BI " void getutmpx(const struct utmp *" u ", struct utmpx *" ux ); +.fi +.SH DESCRIPTION +The +.BR getutmp () +function copies the fields of the +.I utmpx +structure pointed to by +.I ux +to the corresponding fields of the +.I utmp +structure pointed to by +.IR u . +The +.BR getutmpx () +function performs the converse operation. +.SH RETURN VALUE +These functions do not return a value. +.SH VERSIONS +These functions first appeared in glibc in version 2.1.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR getutmp (), +.BR getutmpx () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are nonstandard, but appear on a few other systems, +such as Solaris and NetBSD. +.SH NOTES +These functions exist primarily for compatibility with other +systems where the +.I utmp +and +.I utmpx +structures contain different fields, +or the size of corresponding fields differs. +.\" e.g., on Solaris, the utmpx structure is rather larger than utmp. +On Linux, the two structures contain the same fields, +and the fields have the same sizes. +.SH SEE ALSO +.BR utmpdump (1), +.BR getutent (3), +.BR utmp (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getutmpx.3 b/man3/getutmpx.3 new file mode 100644 index 0000000..668ecb5 --- /dev/null +++ b/man3/getutmpx.3 @@ -0,0 +1 @@ +.so man3/getutmp.3 diff --git a/man3/getutxent.3 b/man3/getutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/getutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutxid.3 b/man3/getutxid.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/getutxid.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getutxline.3 b/man3/getutxline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/getutxline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/getw.3 b/man3/getw.3 new file mode 100644 index 0000000..e514906 --- /dev/null +++ b/man3/getw.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 1995 by Jim Van Zandt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GETW 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getw, putw \- input and output of words (ints) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getw(FILE *" stream ); +.PP +.BI "int putw(int " w ", FILE *" stream ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR getw (), +.BR putw (): +.ad l +.PD 0 +.RS 4 +.TP 4 +Since glibc 2.3.3: +_XOPEN_SOURCE && ! (_POSIX_C_SOURCE\ >=\ 200112L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.TP +Before glibc 2.3.3: +_SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE +.RE +.PD +.ad +.SH DESCRIPTION +.BR getw () +reads a word (that is, an \fIint\fP) from \fIstream\fP. +It's provided for compatibility with SVr4. +We recommend you use +.BR fread (3) +instead. +.PP +.BR putw () +writes the word \fIw\fP (that is, +an \fIint\fP) to \fIstream\fP. +It is provided for compatibility with SVr4, but we recommend you use +.BR fwrite (3) +instead. +.SH RETURN VALUE +Normally, +.BR getw () +returns the word read, and +.BR putw () +returns 0. +On error, they return \fBEOF\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw14 lb lb +l l l. +Interface Attribute Value +T{ +.BR getw (), +.BR putw () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +SVr4, SUSv2. +Not present in POSIX.1. +.SH BUGS +The value returned on error is also a legitimate data value. +.BR ferror (3) +can be used to distinguish between the two cases. +.SH SEE ALSO +.BR ferror (3), +.BR fread (3), +.BR fwrite (3), +.BR getc (3), +.BR putc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getwc.3 b/man3/getwc.3 new file mode 100644 index 0000000..358c2d2 --- /dev/null +++ b/man3/getwc.3 @@ -0,0 +1 @@ +.so man3/fgetwc.3 diff --git a/man3/getwc_unlocked.3 b/man3/getwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/getwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/getwchar.3 b/man3/getwchar.3 new file mode 100644 index 0000000..54300f6 --- /dev/null +++ b/man3/getwchar.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH GETWCHAR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +getwchar \- read a wide character from standard input +.SH SYNOPSIS +.nf +.B #include +.PP +.B "wint_t getwchar(void);" +.fi +.SH DESCRIPTION +The +.BR getwchar () +function is the wide-character equivalent of the +.BR getchar (3) +function. +It reads a wide character from +.I stdin +and returns +it. +If the end of stream is reached, or if +.I ferror(stdin) +becomes true, it returns +.BR WEOF . +If a wide-character conversion error occurs, it sets +.I errno +to +.B EILSEQ +and returns +.BR WEOF . +.PP +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR getwchar () +function returns the next wide-character from +standard input, or +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR getwchar () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR getwchar () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +It is reasonable to expect that +.BR getwchar () +will actually +read a multibyte sequence from standard input and then +convert it to a wide character. +.SH SEE ALSO +.BR fgetwc (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/getwchar_unlocked.3 b/man3/getwchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/getwchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/getwd.3 b/man3/getwd.3 new file mode 100644 index 0000000..f73c157 --- /dev/null +++ b/man3/getwd.3 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man3/glob.3 b/man3/glob.3 new file mode 100644 index 0000000..0afcb53 --- /dev/null +++ b/man3/glob.3 @@ -0,0 +1,370 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de) +.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990912 by aeb +.\" 2007-10-10 mtk +.\" Added description of GLOB_TILDE_NOMATCH +.\" Expanded the description of various flags +.\" Various wording fixes. +.\" +.TH GLOB 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +glob, globfree \- find pathnames matching a pattern, free memory from glob() +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int glob(const char *" pattern ", int " flags , +.BI " int (*" errfunc ") (const char *" epath ", int " eerrno ), +.BI " glob_t *" pglob ); +.BI "void globfree(glob_t *" pglob ); +.fi +.SH DESCRIPTION +The +.BR glob () +function searches for all the pathnames matching +.I pattern +according to the rules used by the shell (see +.BR glob (7)). +No tilde expansion or parameter substitution is done; if you want +these, use +.BR wordexp (3). +.PP +The +.BR globfree () +function frees the dynamically allocated storage from an earlier call +to +.BR glob (). +.PP +The results of a +.BR glob () +call are stored in the structure pointed to by +.IR pglob . +This structure is of type +.I glob_t +(declared in +.IR ) +and includes the following elements defined by POSIX.2 (more may be +present as an extension): +.PP +.in +4n +.EX +typedef struct { + size_t gl_pathc; /* Count of paths matched so far */ + char **gl_pathv; /* List of matched pathnames. */ + size_t gl_offs; /* Slots to reserve in \fIgl_pathv\fP. */ +} glob_t; +.EE +.in +.PP +Results are stored in dynamically allocated storage. +.PP +The argument +.I flags +is made up of the bitwise OR of zero or more the following symbolic +constants, which modify the behavior of +.BR glob (): +.TP +.B GLOB_ERR +Return upon a read error (because a directory does not +have read permission, for example). +By default, +.BR glob () +attempts carry on despite errors, +reading all of the directories that it can. +.TP +.B GLOB_MARK +Append a slash to each path which corresponds to a directory. +.TP +.B GLOB_NOSORT +Don't sort the returned pathnames. +The only reason to do this is to save processing time. +By default, the returned pathnames are sorted. +.TP +.B GLOB_DOOFFS +Reserve +.I pglob\->gl_offs +slots at the beginning of the list of strings in +.IR pglob\->pathv . +The reserved slots contain null pointers. +.TP +.B GLOB_NOCHECK +If no pattern matches, return the original pattern. +By default, +.BR glob () +returns +.B GLOB_NOMATCH +if there are no matches. +.TP +.B GLOB_APPEND +Append the results of this call to the vector of results +returned by a previous call to +.BR glob (). +Do not set this flag on the first invocation of +.BR glob (). +.TP +.B GLOB_NOESCAPE +Don't allow backslash (\(aq\\\(aq) to be used as an escape +character. +Normally, a backslash can be used to quote the following character, +providing a mechanism to turn off the special meaning +metacharacters. +.PP +.I flags +may also include any of the following, which are GNU +extensions and not defined by POSIX.2: +.TP +.B GLOB_PERIOD +Allow a leading period to be matched by metacharacters. +By default, metacharacters can't match a leading period. +.TP +.B GLOB_ALTDIRFUNC +Use alternative functions +.IR pglob\->gl_closedir , +.IR pglob\->gl_readdir , +.IR pglob\->gl_opendir , +.IR pglob\->gl_lstat ", and" +.I pglob\->gl_stat +for filesystem access instead of the normal library +functions. +.TP +.B GLOB_BRACE +Expand +.BR csh (1) +style brace expressions of the form +.BR {a,b} . +Brace expressions can be nested. +Thus, for example, specifying the pattern +"{foo/{,cat,dog},bar}" would return the same results as four separate +.BR glob () +calls using the strings: +"foo/", +"foo/cat", +"foo/dog", +and +"bar". +.TP +.B GLOB_NOMAGIC +If the pattern contains no metacharacters, +then it should be returned as the sole matching word, +even if there is no file with that name. +.TP +.B GLOB_TILDE +Carry out tilde expansion. +If a tilde (\(aq~\(aq) is the only character in the pattern, +or an initial tilde is followed immediately by a slash (\(aq/\(aq), +then the home directory of the caller is substituted for +the tilde. +If an initial tilde is followed by a username (e.g., "~andrea/bin"), +then the tilde and username are substituted by the home directory +of that user. +If the username is invalid, or the home directory cannot be +determined, then no substitution is performed. +.TP +.B GLOB_TILDE_CHECK +This provides behavior similar to that of +.BR GLOB_TILDE . +The difference is that if the username is invalid, or the +home directory cannot be determined, then +instead of using the pattern itself as the name, +.BR glob () +returns +.BR GLOB_NOMATCH +to indicate an error. +.TP +.B GLOB_ONLYDIR +This is a +.I hint +to +.BR glob () +that the caller is interested only in directories that match the pattern. +If the implementation can easily determine file-type information, +then nondirectory files are not returned to the caller. +However, the caller must still check that returned files +are directories. +(The purpose of this flag is merely to optimize performance when +the caller is interested only in directories.) +.PP +If +.I errfunc +is not NULL, +it will be called in case of an error with the arguments +.IR epath , +a pointer to the path which failed, and +.IR eerrno , +the value of +.I errno +as returned from one of the calls to +.BR opendir (3), +.BR readdir (3), +or +.BR stat (2). +If +.I errfunc +returns nonzero, or if +.B GLOB_ERR +is set, +.BR glob () +will terminate after the call to +.IR errfunc . +.PP +Upon successful return, +.I pglob\->gl_pathc +contains the number of matched pathnames and +.I pglob\->gl_pathv +contains a pointer to the list of pointers to matched pathnames. +The list of pointers is terminated by a null pointer. +.PP +It is possible to call +.BR glob () +several times. +In that case, the +.B GLOB_APPEND +flag has to be set in +.I flags +on the second and later invocations. +.PP +As a GNU extension, +.I pglob\->gl_flags +is set to the flags specified, +.BR or ed +with +.B GLOB_MAGCHAR +if any metacharacters were found. +.SH RETURN VALUE +On successful completion, +.BR glob () +returns zero. +Other possible returns are: +.TP +.B GLOB_NOSPACE +for running out of memory, +.TP +.B GLOB_ABORTED +for a read error, and +.TP +.B GLOB_NOMATCH +for no found matches. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw24 +l l l. +Interface Attribute Value +T{ +.BR glob () +T} Thread safety T{ +MT-Unsafe race:utent env +.br +sig:ALRM timer locale +T} +T{ +.BR globfree () +T} Thread safety MT-Safe +.TE +.sp 1 +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR glob () +calls those functions, +so we use race:utent to remind users. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, POSIX.2. +.SH NOTES +The structure elements +.I gl_pathc +and +.I gl_offs +are declared as +.I size_t +in glibc 2.1, as they should be according to POSIX.2, +but are declared as +.I int +in glibc 2.0. +.SH BUGS +The +.BR glob () +function may fail due to failure of underlying function calls, such as +.BR malloc (3) +or +.BR opendir (3). +These will store their error code in +.IR errno . +.SH EXAMPLE +One example of use is the following code, which simulates typing +.PP +.in +4n +.EX +ls \-l *.c ../*.c +.EE +.in +.PP +in the shell: +.PP +.in +4n +.EX +glob_t globbuf; + +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf); +globbuf.gl_pathv[0] = "ls"; +globbuf.gl_pathv[1] = "\-l"; +execvp("ls", &globbuf.gl_pathv[0]); +.EE +.in +.SH SEE ALSO +.BR ls (1), +.BR sh (1), +.BR stat (2), +.BR exec (3), +.BR fnmatch (3), +.BR malloc (3), +.BR opendir (3), +.BR readdir (3), +.BR wordexp (3), +.BR glob (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/globfree.3 b/man3/globfree.3 new file mode 100644 index 0000000..20056c6 --- /dev/null +++ b/man3/globfree.3 @@ -0,0 +1 @@ +.so man3/glob.3 diff --git a/man3/gmtime.3 b/man3/gmtime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man3/gmtime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/gmtime_r.3 b/man3/gmtime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man3/gmtime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/gnu_dev_major.3 b/man3/gnu_dev_major.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man3/gnu_dev_major.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man3/gnu_dev_makedev.3 b/man3/gnu_dev_makedev.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man3/gnu_dev_makedev.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man3/gnu_dev_minor.3 b/man3/gnu_dev_minor.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man3/gnu_dev_minor.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man3/gnu_get_libc_release.3 b/man3/gnu_get_libc_release.3 new file mode 100644 index 0000000..7f84005 --- /dev/null +++ b/man3/gnu_get_libc_release.3 @@ -0,0 +1 @@ +.so man3/gnu_get_libc_version.3 diff --git a/man3/gnu_get_libc_version.3 b/man3/gnu_get_libc_version.3 new file mode 100644 index 0000000..e9ec8b8 --- /dev/null +++ b/man3/gnu_get_libc_version.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GNU_GET_LIBC_VERSION 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +gnu_get_libc_version, gnu_get_libc_release \- get glibc version and release +.SH SYNOPSIS +.nf +.B #include +.PP +.B const char *gnu_get_libc_version(void); +.B const char *gnu_get_libc_release(void); +.fi +.SH DESCRIPTION +The function +.BR gnu_get_libc_version () +returns a string that identifies the glibc version available on the system. +.PP +The function +.BR gnu_get_libc_release () +returns a string indicates the release status of the glibc version +available on the system. +This will be a string such as +.IR "stable" . +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR gnu_get_libc_version (), +.BR gnu_get_libc_release () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are glibc-specific. +.SH EXAMPLE +When run, the program below will produce output such as the following: +.PP +.in +4n +.EX +.RB "$" " ./a.out" +GNU libc version: 2.8 +GNU libc release: stable +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + printf("GNU libc version: %s\\n", gnu_get_libc_version()); + printf("GNU libc release: %s\\n", gnu_get_libc_release()); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR confstr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/grantpt.3 b/man3/grantpt.3 new file mode 100644 index 0000000..278060f --- /dev/null +++ b/man3/grantpt.3 @@ -0,0 +1,115 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.TH GRANTPT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +grantpt \- grant access to the slave pseudoterminal +.SH SYNOPSIS +.B #include +.PP +.BI "int grantpt(int " fd ");" +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR grantpt (): +.br +.RS 4 +Since glibc 2.24: + _XOPEN_SOURCE\ >=\ 500 || + (_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) +.br +Glibc 2.23 and earlier: + _XOPEN_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR grantpt () +function changes the mode and owner of the slave pseudoterminal device +corresponding to the master pseudoterminal referred to by +.IR fd . +The user ID of the slave is set to the real UID of the calling process. +The group ID is set to an unspecified value (e.g., +.IR tty ). +The mode of the slave is set to 0620 (crw\-\-w\-\-\-\-). +.PP +The behavior of +.BR grantpt () +is unspecified if a signal handler is installed to catch +.B SIGCHLD +signals. +.SH RETURN VALUE +When successful, +.BR grantpt () +returns 0. +Otherwise, it returns \-1 and sets +.I errno +appropriately. +.SH ERRORS +.TP +.B EACCES +The corresponding slave pseudoterminal could not be accessed. +.TP +.B EBADF +The +.I fd +argument is not a valid open file descriptor. +.TP +.B EINVAL +The +.I fd +argument is valid but not associated with a master pseudoterminal. +.SH VERSIONS +.BR grantpt () +is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR grantpt () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +This is part of the UNIX 98 pseudoterminal support, see +.BR pts (4). +.PP +Many systems implement this function via a set-user-ID helper binary +called "pt_chown". +On Linux systems with a devpts filesystem (present since Linux 2.2), +the kernel normally sets the correct ownership and permissions +for the pseudoterminal slave when the master is opened +.RB ( posix_openpt (3)), +so that nothing must be done by +.BR grantpt (). +Thus, no such helper binary is required +(and indeed it is configured to be absent during the +glibc build that is typical on many systems). +.SH SEE ALSO +.BR open (2), +.BR posix_openpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/group_member.3 b/man3/group_member.3 new file mode 100644 index 0000000..caed659 --- /dev/null +++ b/man3/group_member.3 @@ -0,0 +1,70 @@ +.\" Copyright (C) 2014, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH GROUP_MEMBER 3 2014-03-30 "GNU" "Linux Programmer's Manual" +.SH NAME +group_member \- test whether a process is in a group +.SH SYNOPSIS +.B #include +.PP +.BI "int group_member(gid_t " gid ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR group_member (): +_GNU_SOURCE +.SH DESCRIPTION +The +.BR group_member () +function tests whether any of the caller's supplementary group IDs +(as returned by +.BR getgroups (2)) +matches +.IR gid . +.SH RETURN VALUE +The +.BR group_member () +function returns nonzero if any of the caller's +supplementary group IDs matches +.IR gid , +and zero otherwise. +.SH CONFORMING TO +This function is a nonstandard GNU extension. +.SH SEE ALSO +.BR getgid (2), +.BR getgroups (2), +.BR getgrouplist (3), +.BR group (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/gsignal.3 b/man3/gsignal.3 new file mode 100644 index 0000000..7cf6f49 --- /dev/null +++ b/man3/gsignal.3 @@ -0,0 +1,134 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.TH GSIGNAL 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +gsignal, ssignal \- software signal facility +.SH SYNOPSIS +.nf +.B #include +.PP +.B typedef void (*sighandler_t)(int); +.PP +.BI "int gsignal(int " signum ); +.PP +.BI "sighandler_t ssignal(int " signum ", sighandler_t " action ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR gsignal (), +.BR ssignal (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +Don't use these functions under Linux. +Due to a historical mistake, under Linux these functions are +aliases for +.BR raise (3) +and +.BR signal (2), +respectively. +.PP +Elsewhere, on System V-like systems, these functions implement +software signaling, entirely independent of the classical +.BR signal (2) +and +.BR kill (2) +functions. +The function +.BR ssignal () +defines the action to take when the software signal with +number +.I signum +is raised using the function +.BR gsignal (), +and returns the previous such action or +.BR SIG_DFL . +The function +.BR gsignal () +does the following: if no action (or the action +.BR SIG_DFL ) +was +specified for +.IR signum , +then it does nothing and returns 0. +If the action +.B SIG_IGN +was specified for +.IR signum , +then it does nothing and returns 1. +Otherwise, it resets the action to +.B SIG_DFL +and calls +the action function with argument +.IR signum , +and returns the value returned by that function. +The range of possible values +.I signum +varies (often 1\(en15 or 1\(en17). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR gsignal () +T} Thread safety MT-Safe +T{ +.BR ssignal () +T} Thread safety MT-Safe sigintr +.TE +.sp 1 +.SH CONFORMING TO +These functions are available under AIX, DG/UX, HP-UX, SCO, Solaris, Tru64. +They are called obsolete under most of these systems, and are +broken under Linux libc and glibc. +Some systems also have +.BR gsignal_r () +and +.BR ssignal_r (). +.SH SEE ALSO +.BR kill (2), +.BR signal (2), +.BR raise (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/h_errno.3 b/man3/h_errno.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/h_errno.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/hash.3 b/man3/hash.3 new file mode 100644 index 0000000..5f08bca --- /dev/null +++ b/man3/hash.3 @@ -0,0 +1,179 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)hash.3 8.6 (Berkeley) 8/18/94 +.\" +.TH HASH 3 2017-09-15 "" "Linux Programmer's Manual" +.UC 7 +.SH NAME +hash \- hash database access method +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided in glibc up until version 2.1. +Since version 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.PP +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is hash files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the hash-specific information. +.PP +The hash data structure is an extensible, dynamic hashing scheme. +.PP +The access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I +include file as follows: +.PP +.in +4n +.EX +typedef struct { + unsigned int bsize; + unsigned int ffactor; + unsigned int nelem; + unsigned int cachesize; + uint32_t (*hash)(const void *, size_t); + int lorder; +} HASHINFO; +.EE +.in +.PP +The elements of this structure are as follows: +.TP 10 +.I bsize +defines the hash table bucket size, and is, by default, 256 bytes. +It may be preferable to increase the page size for disk-resident tables +and tables with large data items. +.TP +.I ffactor +indicates a desired density within the hash table. +It is an approximation of the number of keys allowed to accumulate in any +one bucket, determining when the hash table grows or shrinks. +The default value is 8. +.TP +.I nelem +is an estimate of the final size of the hash table. +If not set or set too low, hash tables will expand gracefully as keys +are entered, although a slight performance degradation may be noticed. +The default value is 1. +.TP +.I cachesize +is the suggested maximum size, in bytes, of the memory cache. +This value is +.IR "only advisory" , +and the access method will allocate more memory rather than fail. +.TP +.I hash +is a user-defined hash function. +Since no hash function performs equally well on all possible data, the +user may find that the built-in hash function does poorly on a particular +data set. +A user-specified hash functions must take two arguments (a pointer to a byte +string and a length) and return a 32-bit quantity to be used as the hash +value. +.TP +.I lorder +is the byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +If the file already exists, the specified value is ignored and the +value specified when the tree was created is used. +.PP +If the file already exists (and the +.B O_TRUNC +flag is not specified), the +values specified for +.IR bsize , +.IR ffactor , +.IR lorder , +and +.I nelem +are +ignored and the values specified when the tree was created are used. +.PP +If a hash function is specified, +.I hash_open +attempts to determine if the hash function specified is the same as +the one with which the database was created, and fails if it is not. +.PP +Backward-compatible interfaces to the routines described in +.BR dbm (3), +and +.BR ndbm (3) +are provided, however these interfaces are not compatible with +previous file formats. +.SH ERRORS +The +.I hash +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3). +.SH BUGS +Only big and little endian byte order are supported. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR mpool (3), +.BR recno (3) +.PP +.IR "Dynamic Hash Tables" , +Per-Ake Larson, Communications of the ACM, April 1988. +.PP +.IR "A New Hash Package for UNIX" , +Margo Seltzer, USENIX Proceedings, Winter 1991. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/hasmntopt.3 b/man3/hasmntopt.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man3/hasmntopt.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/hcreate.3 b/man3/hcreate.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man3/hcreate.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/hcreate_r.3 b/man3/hcreate_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man3/hcreate_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/hdestroy.3 b/man3/hdestroy.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man3/hdestroy.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/hdestroy_r.3 b/man3/hdestroy_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man3/hdestroy_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/herror.3 b/man3/herror.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/herror.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/hsearch.3 b/man3/hsearch.3 new file mode 100644 index 0000000..fdf8404 --- /dev/null +++ b/man3/hsearch.3 @@ -0,0 +1,363 @@ +.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" SunOS 4.1.1 man pages +.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt +.\" Remarks from dhw@gamgee.acad.emich.edu Fri Jun 19 06:46:31 1998 +.\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb +.\" 2008-09-02, mtk: various additions and rewrites +.\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from +.\" Timothy S. Nelson +.\" +.TH HSEARCH 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, +hsearch_r \- hash table management +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int hcreate(size_t " nel ); +.PP +.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action ); +.PP +.B "void hdestroy(void);" +.PP +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab ); +.PP +.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval , +.BI " struct hsearch_data *" htab ); +.PP +.BI "void hdestroy_r(struct hsearch_data *" htab ); +.fi +.SH DESCRIPTION +The three functions +.BR hcreate (), +.BR hsearch (), +and +.BR hdestroy () +allow the caller to create and manage a hash search table +containing entries consisting of a key (a string) and associated data. +Using these functions, only one hash table can be used at a time. +.PP +The three functions +.BR hcreate_r (), +.BR hsearch_r (), +.BR hdestroy_r () +are reentrant versions that allow a program to use +more than one hash search table at the same time. +The last argument, +.IR htab , +points to a structure that describes the table +on which the function is to operate. +The programmer should treat this structure as opaque +(i.e., do not attempt to directly access or modify +the fields in this structure). +.PP +First a hash table must be created using +.BR hcreate (). +The argument \fInel\fP specifies the maximum number of entries +in the table. +(This maximum cannot be changed later, so choose it wisely.) +The implementation may adjust this value upward to improve the +performance of the resulting hash table. +.\" e.g., in glibc it is raised to the next higher prime number +.PP +The +.BR hcreate_r () +function performs the same task as +.BR hcreate (), +but for the table described by the structure +.IR *htab . +The structure pointed to by +.I htab +must be zeroed before the first call to +.BR hcreate_r (). +.PP +The function +.BR hdestroy () +frees the memory occupied by the hash table that was created by +.BR hcreate (). +After calling +.BR hdestroy (), +a new hash table can be created using +.BR hcreate (). +The +.BR hdestroy_r () +function performs the analogous task for a hash table described by +.IR *htab , +which was previously created using +.BR hcreate_r (). +.PP +The +.BR hsearch () +function searches the hash table for an +item with the same key as \fIitem\fP (where "the same" is determined using +.BR strcmp (3)), +and if successful returns a pointer to it. +.PP +The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in +\fI\fP as follows: +.PP +.in +4n +.EX +typedef struct entry { + char *key; + void *data; +} ENTRY; +.EE +.in +.PP +The field \fIkey\fP points to a null-terminated string which is the +search key. +The field \fIdata\fP points to data that is associated with that key. +.PP +The argument \fIaction\fP determines what +.BR hsearch () +does after an unsuccessful search. +This argument must either have the value +.BR ENTER , +meaning insert a copy of +.IR item +(and return a pointer to the new hash table entry as the function result), +or the value +.BR FIND , +meaning that NULL should be returned. +(If +.I action +is +.BR FIND , +then +.I data +is ignored.) +.PP +The +.BR hsearch_r () +function is like +.BR hsearch () +but operates on the hash table described by +.IR *htab . +The +.BR hsearch_r () +function differs from +.BR hsearch () +in that a pointer to the found item is returned in +.IR *retval , +rather than as the function result. +.SH RETURN VALUE +.BR hcreate () +and +.BR hcreate_r () +return nonzero on success. +They return 0 on error, with +.I errno +set to indicate the cause of the error. +.PP +On success, +.BR hsearch () +returns a pointer to an entry in the hash table. +.BR hsearch () +returns NULL on error, that is, +if \fIaction\fP is \fBENTER\fP and +the hash table is full, or \fIaction\fP is \fBFIND\fP and \fIitem\fP +cannot be found in the hash table. +.BR hsearch_r () +returns nonzero on success, and 0 on error. +In the event of an error, these two functions set +.I errno +to indicate the cause of the error. +.SH ERRORS +.PP +.BR hcreate_r () +and +.BR hdestroy_r () +can fail for the following reasons: +.TP +.B EINVAL +.I htab +is NULL. +.PP +.BR hsearch () +and +.BR hsearch_r () +can fail for the following reasons: +.TP +.B ENOMEM +.I action +was +.BR ENTER , +.I key +was not found in the table, +and there was no room in the table to add a new entry. +.TP +.B ESRCH +.I action +was +.BR FIND , +and +.I key +was not found in the table. +.PP +POSIX.1 specifies only the +.\" PROX.1-2001, POSIX.1-2008 +.B ENOMEM +error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR hcreate (), +.BR hsearch (), +.br +.BR hdestroy () +T} Thread safety MT-Unsafe race:hsearch +T{ +.BR hcreate_r (), +.BR hsearch_r (), +.br +.BR hdestroy_r () +T} Thread safety MT-Safe race:htab +.TE +.SH CONFORMING TO +The functions +.BR hcreate (), +.BR hsearch (), +and +.BR hdestroy () +are from SVr4, and are described in POSIX.1-2001 and POSIX.1-2008. +.PP +The functions +.BR hcreate_r (), +.BR hsearch_r (), +and +.BR hdestroy_r () +are GNU extensions. +.SH NOTES +Hash table implementations are usually more efficient when the +table contains enough free space to minimize collisions. +Typically, this means that +.I nel +should be at least 25% larger than the maximum number of elements +that the caller expects to store in the table. +.PP +The +.BR hdestroy () +and +.BR hdestroy_r () +functions do not free the buffers pointed to by the +.I key +and +.I data +elements of the hash table entries. +(It can't do this because it doesn't know +whether these buffers were allocated dynamically.) +If these buffers need to be freed (perhaps because the program +is repeatedly creating and destroying hash tables, +rather than creating a single table whose lifetime +matches that of the program), +then the program must maintain bookkeeping data structures that +allow it to free them. +.SH BUGS +SVr4 and POSIX.1-2001 specify that \fIaction\fP +is significant only for unsuccessful searches, so that an \fBENTER\fP +should not do anything for a successful search. +In libc and glibc (before version 2.3), the +implementation violates the specification, +updating the \fIdata\fP for the given \fIkey\fP in this case. +.PP +Individual hash table entries can be added, but not deleted. +.SH EXAMPLE +.PP +The following program inserts 24 items into a hash table, then prints +some of them. +.PP +.EX +#include +#include +#include + +static char *data[] = { "alpha", "bravo", "charlie", "delta", + "echo", "foxtrot", "golf", "hotel", "india", "juliet", + "kilo", "lima", "mike", "november", "oscar", "papa", + "quebec", "romeo", "sierra", "tango", "uniform", + "victor", "whisky", "x\-ray", "yankee", "zulu" +}; + +int +main(void) +{ + ENTRY e, *ep; + int i; + + hcreate(30); + + for (i = 0; i < 24; i++) { + e.key = data[i]; + /* data is just an integer, instead of a + pointer to something */ + e.data = (void *) i; + ep = hsearch(e, ENTER); + /* there should be no failures */ + if (ep == NULL) { + fprintf(stderr, "entry failed\\n"); + exit(EXIT_FAILURE); + } + } + + for (i = 22; i < 26; i++) { + /* print two entries from the table, and + show that two are not in the table */ + e.key = data[i]; + ep = hsearch(e, FIND); + printf("%9.9s \-> %9.9s:%d\\n", e.key, + ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0); + } + hdestroy(); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bsearch (3), +.BR lsearch (3), +.BR malloc (3), +.BR tsearch (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/hsearch_r.3 b/man3/hsearch_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man3/hsearch_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man3/hstrerror.3 b/man3/hstrerror.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/hstrerror.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/htobe16.3 b/man3/htobe16.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/htobe16.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/htobe32.3 b/man3/htobe32.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/htobe32.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/htobe64.3 b/man3/htobe64.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/htobe64.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/htole16.3 b/man3/htole16.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/htole16.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/htole32.3 b/man3/htole32.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/htole32.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/htole64.3 b/man3/htole64.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/htole64.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/htonl.3 b/man3/htonl.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man3/htonl.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man3/htons.3 b/man3/htons.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man3/htons.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man3/hypot.3 b/man3/hypot.3 new file mode 100644 index 0000000..28e5eef --- /dev/null +++ b/man3/hypot.3 @@ -0,0 +1,184 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH HYPOT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +hypot, hypotf, hypotl \- Euclidean distance function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double hypot(double " x ", double " y ); +.BI "float hypotf(float " x ", float " y ); +.BI "long double hypotl(long double " x ", long double " y ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR hypot (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR hypotf (), +.BR hypotl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return +.RI sqrt( x * x + y * y ). +This is the length of the hypotenuse of a right-angled triangle +with sides of length +.I x +and +.IR y , +or the distance of the point +.RI ( x , y ) +from the origin. +.PP +The calculation is performed without undue overflow or underflow +during the intermediate steps of the calculation. +.\" e.g., hypot(DBL_MIN, DBL_MIN) does the right thing, as does, say +.\" hypot(DBL_MAX/2.0, DBL_MAX/2.0). +.SH RETURN VALUE +On success, these functions return the length of a right-angled triangle +with sides of length +.I x +and +.IR y . +.PP +If +.I x +or +.I y +is an infinity, +positive infinity is returned. +.PP +If +.I x +or +.I y +is a NaN, +and the other argument is not an infinity, +a NaN is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively. +.PP +If both arguments are subnormal, and the result is subnormal, +.\" Actually, could the result not be subnormal if both arguments +.\" are subnormal? I think not -- mtk, Jul 2008 +a range error occurs, +and the correct result is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result underflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.IP +These functions do not set +.IR errno +for this case. +.\" FIXME . Is it intentional that these functions do not set errno? +.\" They do set errno for the overflow case. +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6795 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR hypot (), +.BR hypotf (), +.BR hypotl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cabs (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/hypotf.3 b/man3/hypotf.3 new file mode 100644 index 0000000..e5c8ab8 --- /dev/null +++ b/man3/hypotf.3 @@ -0,0 +1 @@ +.so man3/hypot.3 diff --git a/man3/hypotl.3 b/man3/hypotl.3 new file mode 100644 index 0000000..e5c8ab8 --- /dev/null +++ b/man3/hypotl.3 @@ -0,0 +1 @@ +.so man3/hypot.3 diff --git a/man3/iconv.3 b/man3/iconv.3 new file mode 100644 index 0000000..3a8265a --- /dev/null +++ b/man3/iconv.3 @@ -0,0 +1,199 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" +.\" 2000-06-30 correction by Yuichi SATO +.\" 2000-11-15 aeb, fixed prototype +.\" +.TH ICONV 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +iconv \- perform character set conversion +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t iconv(iconv_t " cd , +.BI " char **" inbuf ", size_t *" inbytesleft , +.BI " char **" outbuf ", size_t *" outbytesleft ); +.fi +.SH DESCRIPTION +The +.BR iconv () +function converts a sequence of characters in one character encoding +to a sequence of characters in another character encoding. +The +.I cd +argument is a conversion descriptor, +previously created by a call to +.BR iconv_open (3); +the conversion descriptor defines the character encodings that +.BR iconv () +uses for the conversion. +The +.I inbuf +argument is the address of a variable that points to +the first character of the input sequence; +.I inbytesleft +indicates the number of bytes in that buffer. +The +.I outbuf +argument is the address of a variable that points to +the first byte available in the output buffer; +.I outbytesleft +indicates the number of bytes available in the output buffer. +.PP +The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL. +In this case, the +.BR iconv () +function converts the multibyte sequence +starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP. +At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read. +At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. +.PP +The +.BR iconv () +function converts one multibyte character at a time, and for +each character conversion it increments \fI*inbuf\fP and decrements +\fI*inbytesleft\fP by the number of converted input bytes, it increments +\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted +output bytes, and it updates the conversion state contained in \fIcd\fP. +If the character encoding of the input is stateful, the +.BR iconv () +function can also convert a sequence of input bytes +to an update to the conversion state without producing any output bytes; +such input is called a \fIshift sequence\fP. +The conversion can stop for four reasons: +.IP 1. 3 +An invalid multibyte sequence is encountered in the input. +In this case, +it sets \fIerrno\fP to \fBEILSEQ\fP and returns +.IR (size_t)\ \-1 . +\fI*inbuf\fP +is left pointing to the beginning of the invalid multibyte sequence. +.IP 2. +The input byte sequence has been entirely converted, +that is, \fI*inbytesleft\fP has gone down to 0. +In this case, +.BR iconv () +returns the number of +nonreversible conversions performed during this call. +.IP 3. +An incomplete multibyte sequence is encountered in the input, and the +input byte sequence terminates after it. +In this case, it sets \fIerrno\fP to +\fBEINVAL\fP and returns +.IR (size_t)\ \-1 . +\fI*inbuf\fP is left pointing to the +beginning of the incomplete multibyte sequence. +.IP 4. +The output buffer has no more room for the next converted character. +In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns +.IR (size_t)\ \-1 . +.PP +A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but +\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. +In this case, the +.BR iconv () +function attempts to set \fIcd\fP's conversion state to the +initial state and store a corresponding shift sequence at \fI*outbuf\fP. +At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. +If the output buffer has no more room for this reset sequence, it sets +\fIerrno\fP to \fBE2BIG\fP and returns +.IR (size_t)\ \-1 . +Otherwise, it increments +\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes +written. +.PP +A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and +\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. +In this case, the +.BR iconv () +function sets \fIcd\fP's conversion state to the initial state. +.SH RETURN VALUE +The +.BR iconv () +function returns the number of characters converted in a +nonreversible way during this call; reversible conversions are not counted. +In case of error, it sets \fIerrno\fP and returns +.IR (size_t)\ \-1 . +.SH ERRORS +The following errors can occur, among others: +.TP +.B E2BIG +There is not sufficient room at \fI*outbuf\fP. +.TP +.B EILSEQ +An invalid multibyte sequence has been encountered in the input. +.TP +.B EINVAL +An incomplete multibyte sequence has been encountered in the input. +.SH VERSIONS +This function is available in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iconv () +T} Thread safety MT-Safe race:cd +.TE +.PP +The +.BR iconv () +function is MT-Safe, as long as callers arrange for +mutual exclusion on the +.I cd +argument. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +In each series of calls to +.BR iconv (), +the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL, +in order to flush out any partially converted input. +.PP +Although +.I inbuf +and +.I outbuf +are typed as +.IR "char\ **" , +this does not mean that the objects they point can be interpreted +as C strings or as arrays of characters: +the interpretation of character byte sequences is +handled internally by the conversion functions. +In some encodings, a zero byte may be a valid part of a multibyte character. +.PP +The caller of +.BR iconv () +must ensure that the pointers passed to the function are suitable +for accessing characters in the appropriate character set. +This includes ensuring correct alignment on platforms that have +tight restrictions on alignment. +.SH SEE ALSO +.BR iconv_close (3), +.BR iconv_open (3), +.BR iconvconfig (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iconv_close.3 b/man3/iconv_close.3 new file mode 100644 index 0000000..3e43787 --- /dev/null +++ b/man3/iconv_close.3 @@ -0,0 +1,65 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH ICONV_CLOSE 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +iconv_close \- deallocate descriptor for character set conversion +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iconv_close(iconv_t " cd ); +.fi +.SH DESCRIPTION +The +.BR iconv_close () +function deallocates a conversion descriptor +.I cd +previously allocated using +.BR iconv_open (3). +.SH RETURN VALUE +When successful, the +.BR iconv_close () +function returns 0. +In case of error, it sets +.I errno +and returns \-1. +.SH VERSIONS +This function is available in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iconv_close () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SUSv2. +.SH SEE ALSO +.BR iconv (3), +.BR iconv_open (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iconv_open.3 b/man3/iconv_open.3 new file mode 100644 index 0000000..2604f02 --- /dev/null +++ b/man3/iconv_open.3 @@ -0,0 +1,132 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" +.\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT +.\" and //IGNORE extensions for 'tocode'. +.\" +.TH ICONV_OPEN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +iconv_open \- allocate descriptor for character set conversion +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode ); +.fi +.SH DESCRIPTION +The +.BR iconv_open () +function allocates a conversion descriptor suitable +for converting byte sequences from character encoding +.I fromcode +to +character encoding +.IR tocode . +.PP +The values permitted for +.IR fromcode +and +.I tocode +and the supported +combinations are system-dependent. +For the GNU C library, the permitted +values are listed by the +.I "iconv \-\-list" +command, and all combinations +of the listed values are supported. +Furthermore the GNU C library and the +GNU libiconv library support the following two suffixes: +.TP +//TRANSLIT +When the string "//TRANSLIT" is appended to +.IR tocode , +transliteration +is activated. +This means that when a character cannot be represented in the +target character set, it can be approximated through one or several +similarly looking characters. +.TP +//IGNORE +When the string "//IGNORE" is appended to +.IR tocode , +characters that +cannot be represented in the target character set will be silently discarded. +.PP +The resulting conversion descriptor can be used with +.BR iconv (3) +any number of times. +It remains valid until deallocated using +.BR iconv_close (3). +.PP +A conversion descriptor contains a conversion state. +After creation using +.BR iconv_open (), +the state is in the initial state. +Using +.BR iconv (3) +modifies the descriptor's conversion state. +To bring the state back to the initial state, use +.BR iconv (3) +with NULL as +.I inbuf +argument. +.SH RETURN VALUE +The +.BR iconv_open () +function returns a freshly allocated conversion +descriptor. +In case of error, it sets +.I errno +and returns +.IR (iconv_t)\ \-1 . +.SH ERRORS +The following error can occur, among others: +.TP +.B EINVAL +The conversion from +.IR fromcode +to +.I tocode +is not supported by the +implementation. +.SH VERSIONS +This function is available in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iconv_open () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SUSv2. +.SH SEE ALSO +.BR iconv (1), +.BR iconv (3), +.BR iconv_close (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/if_freenameindex.3 b/man3/if_freenameindex.3 new file mode 100644 index 0000000..d8aac84 --- /dev/null +++ b/man3/if_freenameindex.3 @@ -0,0 +1 @@ +.so man3/if_nameindex.3 diff --git a/man3/if_indextoname.3 b/man3/if_indextoname.3 new file mode 100644 index 0000000..4379659 --- /dev/null +++ b/man3/if_indextoname.3 @@ -0,0 +1 @@ +.so man3/if_nametoindex.3 diff --git a/man3/if_nameindex.3 b/man3/if_nameindex.3 new file mode 100644 index 0000000..6764ba7 --- /dev/null +++ b/man3/if_nameindex.3 @@ -0,0 +1,177 @@ +.\" Copyright (c) 2012 YOSHIFUJI Hideaki +.\" and Copyright (c) 2012 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume +.\" no responsibility for errors or omissions, or for damages resulting +.\" from the use of the information contained herein. The author(s) may +.\" not have taken the same level of care in the production of this +.\" manual, which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH IF_NAMEINDEX 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +if_nameindex, if_freenameindex \- get network interface names and indexes +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "struct if_nameindex *if_nameindex(void); +.BI "void if_freenameindex(struct if_nameindex *" "ptr" ); +.fi +.SH DESCRIPTION +The +.BR if_nameindex () +function returns an array of +.I if_nameindex +structures, each containing information +about one of the network interfaces on the local system. +The +.I if_nameindex +structure contains at least the following entries: +.PP +.in +4n +.EX +unsigned int if_index; /* Index of interface (1, 2, ...) */ +char *if_name; /* Null-terminated name ("eth0", etc.) */ +.EE +.in +.PP +The +.I if_index +field contains the interface index. +The +.I if_name +field points to the null-terminated interface name. +The end of the array is indicated by entry with +.I if_index +set to zero and +.I if_name +set to NULL. +.PP +The data structure returned by +.BR if_nameindex () +is dynamically allocated and should be freed using +.BR if_freenameindex () +when no longer needed. +.SH RETURN VALUE +On success, +.BR if_nameindex () +returns pointer to the array; +on error, NULL is returned, and +.I errno +is set appropriately. +.SH ERRORS +.BR if_nameindex () +may fail and set +.I errno +if: +.TP +.B ENOBUFS +Insufficient resources available. +.PP +.BR if_nameindex () +may also fail for any of the errors specified for +.BR socket (2), +.BR bind (2), +.BR ioctl (2), +.BR getsockname (2), +.BR recvmsg (2), +.BR sendto (2), +or +.BR malloc (3). +.SH VERSIONS +The +.BR if_nameindex () +function first appeared in glibc 2.1, but before glibc 2.3.4, +the implementation supported only interfaces with IPv4 addresses. +Support of interfaces that don't have IPv4 addresses is available only +on kernels that support netlink. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR if_nameindex (), +.br +.BR if_freenameindex () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, RFC\ 3493. +.PP +This function first appeared in BSDi. +.SH EXAMPLE +The program below demonstrates the use of the functions described +on this page. +An example of the output this program might produce is the following: +.PP +.in +4n +.EX +$ \fB./a.out\fI +1: lo +2: wlan0 +3: em1 +.EE +.in +.SS Program source +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct if_nameindex *if_ni, *i; + + if_ni = if_nameindex(); + if (if_ni == NULL) { + perror("if_nameindex"); + exit(EXIT_FAILURE); + } + + for (i = if_ni; ! (i\->if_index == 0 && i\->if_name == NULL); i++) + printf("%u: %s\\n", i\->if_index, i\->if_name); + + if_freenameindex(if_ni); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getsockopt (2), +.BR setsockopt (2), +.BR getifaddrs (3), +.BR if_indextoname (3), +.BR if_nametoindex (3), +.BR ifconfig (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/if_nametoindex.3 b/man3/if_nametoindex.3 new file mode 100644 index 0000000..8fabcc1 --- /dev/null +++ b/man3/if_nametoindex.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2012 YOSHIFUJI Hideaki +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume +.\" no responsibility for errors or omissions, or for damages resulting +.\" from the use of the information contained herein. The author(s) may +.\" not have taken the same level of care in the production of this +.\" manual, which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH IF_NAMETOINDEX 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +if_nametoindex, if_indextoname \- mappings between network interface +names and indexes +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "unsigned int if_nametoindex(const char *" "ifname" ); +.PP +.BI "char *if_indextoname(unsigned int ifindex, char *" ifname ); +.fi +.SH DESCRIPTION +The +.BR if_nametoindex () +function returns the index of the network interface +corresponding to the name +.IR ifname . +.PP +The +.BR if_indextoname () +function returns the name of the network interface +corresponding to the interface index +.IR ifindex . +The name is placed in the buffer pointed to by +.IR ifname . +The buffer must allow for the storage of at least +.B IF_NAMESIZE +bytes. +.SH RETURN VALUE +On success, +.BR if_nametoindex () +returns the index number of the network interface; +on error, 0 is returned and +.I errno +is set appropriately. +.PP +On success, +.BR if_indextoname () +returns +.IR ifname ; +on error, NULL is returned and +.I errno +is set appropriately. +.SH ERRORS +.BR if_nametoindex () +may fail and set +.I errno +if: +.TP +.B ENODEV +No interface found with given name. +.PP +.BR if_indextoname () +may fail and set +.I errno +if: +.TP +.B ENXIO +No interface found for the index. +.PP +.BR if_nametoindex () +and +.BR if_indextoname () +may also fail for any of the errors specified for +.BR socket (2) +or +.BR ioctl (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw34 lb lb +l l l. +Interface Attribute Value +T{ +.BR if_nametoindex (), +.BR if_indextoname () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, RFC\ 3493. +.PP +This function first appeared in BSDi. +.SH SEE ALSO +.BR getifaddrs (3), +.BR if_nameindex (3), +.BR ifconfig (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ilogb.3 b/man3/ilogb.3 new file mode 100644 index 0000000..eb72561 --- /dev/null +++ b/man3/ilogb.3 @@ -0,0 +1,176 @@ +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Inspired by a page by Walter Harms created 2002-08-10 +.\" +.TH ILOGB 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ilogb, ilogbf, ilogbl \- get integer exponent of a floating-point value +.SH SYNOPSIS +.B #include +.PP +.BI "int ilogb(double " x ); +.br +.BI "int ilogbf(float " x ); +.br +.BI "int ilogbl(long double " x ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR ilogb (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR ilogbf (), +.BR ilogbl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return the exponent part of their argument +as a signed integer. +When no error occurs, these functions +are equivalent to the corresponding +.BR logb (3) +functions, cast to +.IR int . +.SH RETURN VALUE +On success, these functions return the exponent of +.IR x , +as a signed integer. +.PP +If +.I x +is zero, then a domain error occurs, and the functions return +.\" the POSIX.1 spec for logb() says logb() gives pole error for this +.\" case, but for ilogb() it says domain error. +.BR FP_ILOGB0 . +.\" glibc: The numeric value is either `INT_MIN' or `-INT_MAX'. +.PP +If +.I x +is a NaN, then a domain error occurs, and the functions return +.BR FP_ILOGBNAN . +.\" glibc: The numeric value is either `INT_MIN' or `INT_MAX'. +.\" On i386, FP_ILOGB0 and FP_ILOGBNAN have the same value. +.PP +If +.I x +is negative infinity or positive infinity, then +a domain error occurs, and the functions return +.BR INT_MAX . +.\" +.\" POSIX.1-2001 also says: +.\" If the correct value is greater than {INT_MAX}, {INT_MAX} +.\" shall be returned and a domain error shall occur. +.\" +.\" If the correct value is less than {INT_MIN}, {INT_MIN} +.\" shall be returned and a domain error shall occur. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is 0 or a NaN +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised, and +.I errno +is set to +.BR EDOM +(but see BUGS). +.IP +.TP +Domain error: \fIx\fP is an infinity +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised, and +.I errno +is set to +.BR EDOM +(but see BUGS). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR ilogb (), +.BR ilogbf (), +.BR ilogbl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH BUGS +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6794 +Before version 2.16, the following bugs existed in the +glibc implementation of these functions: +.IP * 3 +The domain error case where +.I x +is 0 or a NaN did not cause +.I errno +to be set or (on some architectures) raise a floating-point exception. +.IP * 3 +The domain error case where +.I x +is an infinity did not cause +.I errno +to be set or raise a floating-point exception. +.SH SEE ALSO +.BR log (3), +.BR logb (3), +.BR significand (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ilogbf.3 b/man3/ilogbf.3 new file mode 100644 index 0000000..213d00a --- /dev/null +++ b/man3/ilogbf.3 @@ -0,0 +1 @@ +.so man3/ilogb.3 diff --git a/man3/ilogbl.3 b/man3/ilogbl.3 new file mode 100644 index 0000000..213d00a --- /dev/null +++ b/man3/ilogbl.3 @@ -0,0 +1 @@ +.so man3/ilogb.3 diff --git a/man3/imaxabs.3 b/man3/imaxabs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man3/imaxabs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man3/imaxdiv.3 b/man3/imaxdiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man3/imaxdiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man3/index.3 b/man3/index.3 new file mode 100644 index 0000000..0117bca --- /dev/null +++ b/man3/index.3 @@ -0,0 +1,104 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Apr 12 12:54:34 1993, David Metcalfe +.\" Modified Sat Jul 24 19:13:52 1993, Rik Faith (faith@cs.unc.edu) +.TH INDEX 3 2015-03-02 "GNU" "Linux Programmer's Manual" +.SH NAME +index, rindex \- locate character in string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *index(const char *" s ", int " c ); +.PP +.BI "char *rindex(const char *" s ", int " c ); +.fi +.SH DESCRIPTION +The +.BR index () +function returns a pointer to the first occurrence +of the character \fIc\fP in the string \fIs\fP. +.PP +The +.BR rindex () +function returns a pointer to the last occurrence +of the character \fIc\fP in the string \fIs\fP. +.PP +The terminating null byte (\(aq\\0\(aq) is considered to be a part of the +strings. +.SH RETURN VALUE +The +.BR index () +and +.BR rindex () +functions return a pointer to +the matched character or NULL if the character is not found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR index (), +.BR rindex () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.3BSD; marked as LEGACY in POSIX.1-2001. +POSIX.1-2008 removes the specifications of +.BR index () +and +.BR rindex (), +recommending +.BR strchr (3) +and +.BR strrchr (3) +instead. +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/inet.3 b/man3/inet.3 new file mode 100644 index 0000000..02c5dd6 --- /dev/null +++ b/man3/inet.3 @@ -0,0 +1,350 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" libc.info (from glibc distribution) +.\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith +.\" Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt +.\" Changed network into host byte order (for inet_network), +.\" Andreas Jaeger , 980130. +.\" 2008-06-19, mtk +.\" Describe the various address forms supported by inet_aton(). +.\" Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr(). +.\" Add discussion of Classful Addressing, noting that it is obsolete. +.\" Added an EXAMPLE program. +.\" +.TH INET 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, +inet_netof \- Internet address manipulation routines +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int inet_aton(const char *" cp ", struct in_addr *" inp ); +.PP +.BI "in_addr_t inet_addr(const char *" cp ); +.PP +.BI "in_addr_t inet_network(const char *" cp ); +.PP +.BI "char *inet_ntoa(struct in_addr " in ); +.PP +.BI "struct in_addr inet_makeaddr(in_addr_t " net ", in_addr_t " host ); +.PP +.BI "in_addr_t inet_lnaof(struct in_addr " in ); +.PP +.BI "in_addr_t inet_netof(struct in_addr " in ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR inet_aton (), +.BR inet_ntoa (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR inet_aton () +converts the Internet host address \fIcp\fP from the +IPv4 numbers-and-dots notation into binary form (in network byte order) +and stores it in the structure that \fIinp\fP points to. +.BR inet_aton () +returns nonzero if the address is valid, zero if not. +The address supplied in +.I cp +can have one of the following forms: +.TP 10 +.I a.b.c.d +Each of the four numeric parts specifies a byte of the address; +the bytes are assigned in left-to-right order to produce the binary address. +.TP +.I a.b.c +Parts +.I a +and +.I b +specify the first two bytes of the binary address. +Part +.I c +is interpreted as a 16-bit value that defines the rightmost two bytes +of the binary address. +This notation is suitable for specifying (outmoded) Class B +network addresses. +.TP +.I a.b +Part +.I a +specifies the first byte of the binary address. +Part +.I b +is interpreted as a 24-bit value that defines the rightmost three bytes +of the binary address. +This notation is suitable for specifying (outmoded) Class A +network addresses. +.TP +.I a +The value +.I a +is interpreted as a 32-bit value that is stored directly +into the binary address without any byte rearrangement. +.PP +In all of the above forms, +components of the dotted address can be specified in decimal, +octal (with a leading +.IR 0 ), +or hexadecimal, with a leading +.IR 0X ). +Addresses in any of these forms are collectively termed +.IR "IPV4 numbers-and-dots notation" . +The form that uses exactly four decimal numbers is referred to as +.IR "IPv4 dotted-decimal notation" +(or sometimes: +.IR "IPv4 dotted-quad notation" ). +.PP +.BR inet_aton () +returns 1 if the supplied string was successfully interpreted, +or 0 if the string is invalid +.RB ( errno +is +.I not +set on error). +.PP +The +.BR inet_addr () +function converts the Internet host address +\fIcp\fP from IPv4 numbers-and-dots notation into binary data in network +byte order. +If the input is invalid, +.B INADDR_NONE +(usually \-1) is returned. +Use of this function is problematic because \-1 is a valid address +(255.255.255.255). +Avoid its use in favor of +.BR inet_aton (), +.BR inet_pton (3), +or +.BR getaddrinfo (3), +which provide a cleaner way to indicate error return. +.PP +The +.BR inet_network () +function converts +.IR cp , +a string in IPv4 numbers-and-dots notation, +into a number in host byte order suitable for use as an +Internet network address. +On success, the converted address is returned. +If the input is invalid, \-1 is returned. +.PP +The +.BR inet_ntoa () +function converts the Internet host address +\fIin\fP, given in network byte order, to a string in IPv4 +dotted-decimal notation. +The string is returned in a statically +allocated buffer, which subsequent calls will overwrite. +.PP +The +.BR inet_lnaof () +function returns the local network address part +of the Internet address \fIin\fP. +The returned value is in host byte order. +.PP +The +.BR inet_netof () +function returns the network number part of +the Internet address \fIin\fP. +The returned value is in host byte order. +.PP +The +.BR inet_makeaddr () +function is the converse of +.BR inet_netof () +and +.BR inet_lnaof (). +It returns an Internet host address in network byte order, +created by combining the network number \fInet\fP +with the local address \fIhost\fP, both in +host byte order. +.PP +The structure \fIin_addr\fP as used in +.BR inet_ntoa (), +.BR inet_makeaddr (), +.BR inet_lnaof () +and +.BR inet_netof () +is defined in +.I +as: +.PP +.in +4n +.EX +typedef uint32_t in_addr_t; + +struct in_addr { + in_addr_t s_addr; +}; +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR inet_aton (), +.BR inet_addr (), +.br +.BR inet_network (), +.BR inet_ntoa () +T} Thread safety MT-Safe locale +T{ +.BR inet_makeaddr (), +.BR inet_lnaof (), +.br +.BR inet_netof () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR inet_addr (), +.BR inet_ntoa (): +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.PP +.BR inet_aton () +is not specified in POSIX.1, but is available on most systems. +.SH NOTES +On x86 architectures, the host byte order is Least Significant Byte +first (little endian), whereas the network byte order, as used on the +Internet, is Most Significant Byte first (big endian). +.PP +.BR inet_lnaof (), +.BR inet_netof (), +and +.BR inet_makeaddr () +are legacy functions that assume they are dealing with +.IR "classful network addresses" . +Classful networking divides IPv4 network addresses into host and network +components at byte boundaries, as follows: +.TP 10 +Class A +This address type is indicated by the value 0 in the +most significant bit of the (network byte ordered) address. +The network address is contained in the most significant byte, +and the host address occupies the remaining three bytes. +.TP +Class B +This address type is indicated by the binary value 10 in the +most significant two bits of the address. +The network address is contained in the two most significant bytes, +and the host address occupies the remaining two bytes. +.TP +Class C +This address type is indicated by the binary value 110 in the +most significant three bits of the address. +The network address is contained in the three most significant bytes, +and the host address occupies the remaining byte. +.PP +Classful network addresses are now obsolete, +having been superseded by Classless Inter-Domain Routing (CIDR), +which divides addresses into network and host components at +arbitrary bit (rather than byte) boundaries. +.SH EXAMPLE +An example of the use of +.BR inet_aton () +and +.BR inet_ntoa () +is shown below. +Here are some example runs: +.PP +.in +4n +.EX +.RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal" +226.0.0.31 +.RB "$" " ./a.out 0x7f.1 " " # First byte is in hex" +127.0.0.1 +.EE +.in +.SS Program source +\& +.EX +#define _BSD_SOURCE +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct in_addr addr; + + if (argc != 2) { + fprintf(stderr, "%s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + if (inet_aton(argv[1], &addr) == 0) { + fprintf(stderr, "Invalid address\\n"); + exit(EXIT_FAILURE); + } + + printf("%s\\n", inet_ntoa(addr)); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR byteorder (3), +.BR getaddrinfo (3), +.BR gethostbyname (3), +.BR getnameinfo (3), +.BR getnetent (3), +.BR inet_net_pton (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR hosts (5), +.BR networks (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/inet_addr.3 b/man3/inet_addr.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man3/inet_addr.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_aton.3 b/man3/inet_aton.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man3/inet_aton.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_lnaof.3 b/man3/inet_lnaof.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man3/inet_lnaof.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_makeaddr.3 b/man3/inet_makeaddr.3 new file mode 100644 index 0000000..4a9e0fd --- /dev/null +++ b/man3/inet_makeaddr.3 @@ -0,0 +1 @@ +.so man3/inet_addr.3 diff --git a/man3/inet_net_ntop.3 b/man3/inet_net_ntop.3 new file mode 100644 index 0000000..10b8d44 --- /dev/null +++ b/man3/inet_net_ntop.3 @@ -0,0 +1 @@ +.so man3/inet_net_pton.3 diff --git a/man3/inet_net_pton.3 b/man3/inet_net_pton.3 new file mode 100644 index 0000000..3f13644 --- /dev/null +++ b/man3/inet_net_pton.3 @@ -0,0 +1,401 @@ +'\" t +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH INET_NET_PTON 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +inet_net_pton, inet_net_ntop \- Internet network number conversion +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int inet_net_pton(int " af ", const char *" pres , +.BI " void *" netp ", size_t " nsize ); + +.BI "char *inet_net_ntop(int " af ", const void *" netp ", int " bits , +.BI " char *" pres ", size_t " psize ); +.fi +.PP +Link with \fI\-lresolv\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR inet_net_pton (), +.BR inet_net_ntop (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.20: +_DEFAULT_SOURCE +.TP 4 +Before glibc 2.20: +_BSD_SOURCE || _SVID_SOURCE +.PD +.RE +.ad b +.SH DESCRIPTION +These functions convert network numbers between +presentation (i.e., printable) format and network (i.e., binary) format. +.PP +For both functions, +.I af +specifies the address family for the conversion; +the only supported value is +.BR AF_INET . +.SS inet_net_pton() +The +.BR inet_net_pton () +function converts +.IR pres , +a null-terminated string containing an Internet network number in +presentation format to network format. +The result of the conversion, which is in network byte order, +is placed in the buffer pointed to by +.IR net . +(The +.I netp +argument typically points to an +.I in_addr +structure.) +The +.I nsize +argument specifies the number of bytes available in +.IR netp . +.PP +On success, +.BR inet_net_pton () +returns the number of bits in the network number field +of the result placed in +.IR netp . +For a discussion of the input presentation format and the return value, +see NOTES. +.PP +.IR Note : +the buffer pointed to by +.I netp +should be zeroed out before calling +.BR inet_net_pton (), +since the call writes only as many bytes as are required +for the network number (or as are explicitly specified by +.IR pres ), +which may be less than the number of bytes in a complete network address. +.SS inet_net_ntop() +The +.BR inet_net_ntop () +function converts the network number in the buffer pointed to by +.IR netp +to presentation format; +.I *netp +is interpreted as a value in network byte order. +The +.I bits +argument specifies the number of bits in the network number in +.IR *netp . +.PP +The null-terminated presentation-format string +is placed in the buffer pointed to by +.IR pres . +The +.I psize +argument specifies the number of bytes available in +.IR pres . +The presentation string is in CIDR format: +a dotted-decimal number representing the network address, +followed by a slash, and the size of the network number in bits. +.SH RETURN VALUE +On success, +.BR inet_net_pton () +returns the number of bits in the network number. +On error, it returns \-1, and +.I errno +is set to indicate the cause of the error. +.PP +On success, +.BR inet_net_ntop () +returns +.IR pres . +On error, it returns NULL, and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.TP +.B EAFNOSUPPORT +.I af +specified a value other than +.BR AF_INET . +.TP +.B EMSGSIZE +The size of the output buffer was insufficient. +.TP +.B ENOENT +.RB ( inet_net_pton ()) +.IR pres +was not in correct presentation format. +.SH CONFORMING TO +The +.BR inet_net_pton () +and +.BR inet_net_ntop () +functions are nonstandard, but widely available. +.SH NOTES +.SS Input presentation format for inet_net_pton() +The network number may be specified either +as a hexadecimal value +or in dotted-decimal notation. +.PP +Hexadecimal values are indicated by an initial "0x" or "0X". +The hexadecimal digits populate the nibbles (half octets) of the +network number from left to right in network byte order. +.\" If the hexadecimal string is short, the remaining nibbles are zeroed. +.PP +In dotted-decimal notation, up to four octets are specified, +as decimal numbers separated by dots. +Thus, any of the following forms are accepted: +.PP + a.b.c.d + a.b.c + a.b + a +.PP +Each part is a number in the range 0 to 255 that +populates one byte of the resulting network number, +going from left to right, in network-byte (big endian) order. +Where a part is omitted, the resulting byte in the network number is zero. +.\" Reading other man pages, some other implementations treat +.\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes +.\" 'b' in a.b as a 24-bit number that populates right-most three bytes +.PP +For either hexadecimal or dotted-decimal format, +the network number can optionally be followed by a slash +and a number in the range 0 to 32, +which specifies the size of the network number in bits. +.SS Return value of inet_net_pton() +The return value of +.BR inet_net_pton () +is the number of bits in the network number field. +If the input presentation string terminates with a slash and +an explicit size value, then that size becomes the return value of +.BR inet_net_pton (). +Otherwise, the return value, +.IR bits , +is inferred as follows: +.IP * 3 +If the most significant byte of the network number is +greater than or equal to 240, +then +.I bits +is 32. +.IP * 3 +Otherwise, +if the most significant byte of the network number is +greater than or equal to 224, +then +.I bits +is 4. +.IP * 3 +Otherwise, +if the most significant byte of the network number is +greater than or equal to 192, +then +.I bits +is 24. +.IP * 3 +Otherwise, +if the most significant byte of the network number is +greater than or equal to 128, +then +.I bits +is 16. +.IP * +Otherwise, +.I bits +is 8. +.PP +If the resulting +.I bits +value from the above steps is greater than or equal to 8, +but the number of octets specified in the network number exceed +.IR "bits/8" , +then +.I bits +is set to 8 times the number of octets actually specified. +.SH EXAMPLE +The program below demonstrates the use of +.BR inet_net_pton () +and +.BR inet_net_ntop (). +It uses +.BR inet_net_pton () +to convert the presentation format network address provided in +its first command-line argument to binary form, displays the return value from +.BR inet_net_pton (). +It then uses +.BR inet_net_ntop () +to convert the binary form back to presentation format, +and displays the resulting string. +.PP +In order to demonstrate that +.BR inet_net_pton () +may not write to all bytes of its +.I netp +argument, the program allows an optional second command-line argument, +a number used to initialize the buffer before +.BR inet_net_pton () +is called. +As its final line of output, +the program displays all of the bytes of the buffer returned by +.BR inet_net_pton () +allowing the user to see which bytes have not been touched by +.BR inet_net_pton (). +.PP +An example run, showing that +.BR inet_net_pton () +infers the number of bits in the network number: +.PP +.in +4n +.EX +$ \fB./a.out 193.168\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.0/24 +Raw address: c1a80000 +.EE +.in +.PP +Demonstrate that +.BR inet_net_pton () +does not zero out unused bytes in its result buffer: +.PP +.in +4n +.EX +$ \fB./a.out 193.168 0xffffffff\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.0/24 +Raw address: c1a800ff +.EE +.in +.PP +Demonstrate that +.BR inet_net_pton () +will widen the inferred size of the network number, +if the supplied number of bytes in the presentation +string exceeds the inferred value: +.PP +.in +4n +.EX +$ \fB./a.out 193.168.1.128\fP +inet_net_pton() returned: 32 +inet_net_ntop() yielded: 193.168.1.128/32 +Raw address: c1a80180 +.EE +.in +.PP +Explicitly specifying the size of the network number overrides any +inference about its size +(but any extra bytes that are explicitly specified will still be used by +.BR inet_net_pton (): +to populate the result buffer): +.PP +.in +4n +.EX +$ \fB./a.out 193.168.1.128/24\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.1/24 +Raw address: c1a80180 +.EE +.in +.SS Program source +.EX +/* Link with "\-lresolv" */ + +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + char buf[100]; + struct in_addr addr; + int bits; + + if (argc < 2) { + fprintf(stderr, + "Usage: %s presentation\-form [addr\-init\-value]\\n", + argv[0]); + exit(EXIT_FAILURE); + } + + /* If argv[2] is supplied (a numeric value), use it to initialize + the output buffer given to inet_net_pton(), so that we can see + that inet_net_pton() initializes only those bytes needed for + the network number. If argv[2] is not supplied, then initialize + the buffer to zero (as is recommended practice). */ + + addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0; + + /* Convert presentation network number in argv[1] to binary */ + + bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr)); + if (bits == \-1) + errExit("inet_net_ntop"); + + printf("inet_net_pton() returned: %d\\n", bits); + + /* Convert binary format back to presentation, using \(aqbits\(aq + returned by inet_net_pton() */ + + if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL) + errExit("inet_net_ntop"); + + printf("inet_net_ntop() yielded: %s\\n", buf); + + /* Display \(aqaddr\(aq in raw form (in network byte order), so we can + see bytes not displayed by inet_net_ntop(); some of those bytes + may not have been touched by inet_net_ntop(), and so will still + have any initial value that was specified in argv[2]. */ + + printf("Raw address: %x\\n", htonl(addr.s_addr)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR inet (3), +.BR networks (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/inet_netof.3 b/man3/inet_netof.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man3/inet_netof.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_network.3 b/man3/inet_network.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man3/inet_network.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_ntoa.3 b/man3/inet_ntoa.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man3/inet_ntoa.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man3/inet_ntop.3 b/man3/inet_ntop.3 new file mode 100644 index 0000000..56d728d --- /dev/null +++ b/man3/inet_ntop.3 @@ -0,0 +1,143 @@ +.\" Copyright 2000 Sam Varshavchik +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References: RFC 2553 +.TH INET_NTOP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +inet_ntop \- convert IPv4 and IPv6 addresses from binary to text form +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "const char *inet_ntop(int " "af" ", const void *" "src" , +.BI " char *" "dst" ", socklen_t " "size" ); +.fi +.SH DESCRIPTION +This function converts the network address structure +.I src +in the +.I af +address family into a character string. +The resulting string is copied to the buffer pointed to by +.IR dst , +which must be a non-null pointer. +The caller specifies the number of bytes available in this buffer in +the argument +.IR size . +.PP +.BR inet_ntop () +extends the +.BR inet_ntoa (3) +function to support multiple address families, +.BR inet_ntoa (3) +is now considered to be deprecated in favor of +.BR inet_ntop (). +The following address families are currently supported: +.TP +.B AF_INET +.I src +points to a +.I struct in_addr +(in network byte order) +which is converted to an IPv4 network address in +the dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP". +The buffer +.I dst +must be at least +.B INET_ADDRSTRLEN +bytes long. +.TP +.B AF_INET6 +.I src +points to a +.I struct in6_addr +(in network byte order) +which is converted to a representation of this address in the +most appropriate IPv6 network address format for this address. +The buffer +.I dst +must be at least +.B INET6_ADDRSTRLEN +bytes long. +.SH RETURN VALUE +On success, +.BR inet_ntop () +returns a non-null pointer to +.IR dst . +NULL is returned if there was an error, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAFNOSUPPORT +.I af +was not a valid address family. +.TP +.B ENOSPC +The converted address string would exceed the size given by +.IR size . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR inet_ntop () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +Note that RFC\ 2553 defines a prototype where the last argument +.I size +is of type +.IR size_t . +Many systems follow RFC\ 2553. +Glibc 2.0 and 2.1 have +.IR size_t , +but 2.2 and later have +.IR socklen_t . +.\" 2.1.3: size_t, 2.1.91: socklen_t +.SH BUGS +.B AF_INET6 +converts IPv4-mapped IPv6 addresses into an IPv6 format. +.SH EXAMPLE +See +.BR inet_pton (3). +.SH SEE ALSO +.BR getnameinfo (3), +.BR inet (3), +.BR inet_pton (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/inet_pton.3 b/man3/inet_pton.3 new file mode 100644 index 0000000..d811dd5 --- /dev/null +++ b/man3/inet_pton.3 @@ -0,0 +1,241 @@ +.\" Copyright 2000 Sam Varshavchik +.\" and Copyright (c) 2008 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References: RFC 2553 +.TH INET_PTON 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +inet_pton \- convert IPv4 and IPv6 addresses from text to binary form +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int inet_pton(int " "af" ", const char *" "src" ", void *" "dst" ); +.fi +.SH DESCRIPTION +This function converts the character string +.I src +into a network address structure in the +.I af +address family, then +copies +the network address structure to +.IR dst . +The +.I af +argument must be either +.B AF_INET +or +.BR AF_INET6 . +.IR dst +is written in network byte order. +.PP +The following address families are currently supported: +.TP +.B AF_INET +.I src +points to a character string containing an IPv4 network address in +dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP", where +.I ddd +is a decimal number of up to three digits in the range 0 to 255. +The address is converted to a +.I struct in_addr +and copied to +.IR dst , +which must be +.I sizeof(struct in_addr) +(4) bytes (32 bits) long. +.TP +.B AF_INET6 +.I src +points to a character string containing an IPv6 network address. +The address is converted to a +.I struct in6_addr +and copied to +.IR dst , +which must be +.I sizeof(struct in6_addr) +(16) bytes (128 bits) long. +The allowed formats for IPv6 addresses follow these rules: +.RS +.IP 1. 3 +The preferred format is +.IR x:x:x:x:x:x:x:x . +This form consists of eight hexadecimal numbers, +each of which expresses a 16-bit value (i.e., each +.I x +can be up to 4 hex digits). +.IP 2. +A series of contiguous zero values in the preferred format +can be abbreviated to +.IR :: . +Only one instance of +.I :: +can occur in an address. +For example, the loopback address +.I 0:0:0:0:0:0:0:1 +can be abbreviated as +.IR ::1 . +The wildcard address, consisting of all zeros, can be written as +.IR :: . +.IP 3. +An alternate format is useful for expressing IPv4-mapped IPv6 addresses. +This form is written as +.IR x:x:x:x:x:x:d.d.d.d , +where the six leading +.IR x s +are hexadecimal values that define the six most-significant +16-bit pieces of the address (i.e., 96 bits), and the +.IR d s +express a value in dotted-decimal notation that +defines the least significant 32 bits of the address. +An example of such an address is +.IR ::FFFF:204.152.189.116 . +.RE +.IP +See RFC 2373 for further details on the representation of IPv6 addresses. +.SH RETURN VALUE +.BR inet_pton () +returns 1 on success (network address was successfully converted). +0 is returned if +.I src +does not contain a character string representing a valid network +address in the specified address family. +If +.I af +does not contain a valid address family, \-1 is returned and +.I errno +is set to +.BR EAFNOSUPPORT . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR inet_pton () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +Unlike +.BR inet_aton (3) +and +.BR inet_addr (3), +.BR inet_pton () +supports IPv6 addresses. +On the other hand, +.BR inet_pton () +accepts only IPv4 addresses in dotted-decimal notation, whereas +.BR inet_aton (3) +and +.BR inet_addr (3) +allow the more general numbers-and-dots notation (hexadecimal +and octal number formats, and formats that don't require all +four bytes to be explicitly written). +For an interface that handles both IPv6 addresses, and IPv4 +addresses in numbers-and-dots notation, see +.BR getaddrinfo (3). +.SH BUGS +.B AF_INET6 +does not recognize IPv4 addresses. +An explicit IPv4-mapped IPv6 address must be supplied in +.I src +instead. +.SH EXAMPLE +The program below demonstrates the use of +.BR inet_pton () +and +.BR inet_ntop (3). +Here are some example runs: +.PP +.in +4n +.EX +.RB "$" " ./a.out i6 0:0:0:0:0:0:0:0" +:: +.RB "$" " ./a.out i6 1:0:0:0:0:0:0:8" +1::8 +.RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116" +::ffff:204.152.189.116 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + unsigned char buf[sizeof(struct in6_addr)]; + int domain, s; + char str[INET6_ADDRSTRLEN]; + + if (argc != 3) { + fprintf(stderr, "Usage: %s {i4|i6|} string\\n", argv[0]); + exit(EXIT_FAILURE); + } + + domain = (strcmp(argv[1], "i4") == 0) ? AF_INET : + (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]); + + s = inet_pton(domain, argv[2], buf); + if (s <= 0) { + if (s == 0) + fprintf(stderr, "Not in presentation format"); + else + perror("inet_pton"); + exit(EXIT_FAILURE); + } + + if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) { + perror("inet_ntop"); + exit(EXIT_FAILURE); + } + + printf("%s\\n", str); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getaddrinfo (3), +.BR inet (3), +.BR inet_ntop (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/initgroups.3 b/man3/initgroups.3 new file mode 100644 index 0000000..3462a99 --- /dev/null +++ b/man3/initgroups.3 @@ -0,0 +1,118 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 2004-10-10 by aeb +.\" +.TH INITGROUPS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +initgroups \- initialize the supplementary group access list +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int initgroups(const char *" user ", gid_t " group ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR initgroups (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The +.BR initgroups () +function initializes the group access list by +reading the group database +.I /etc/group +and using all groups of +which +.I user +is a member. +The additional group +.I group +is +also added to the list. +.PP +The +.I user +argument must be non-NULL. +.SH RETURN VALUE +The +.BR initgroups () +function returns 0 on success. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate group information structure. +.TP +.B EPERM +The calling process has insufficient privilege. +See the underlying system call +.BR setgroups (2). +.SH FILES +.TP +.I /etc/group +group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR initgroups () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +SVr4, 4.3BSD. +.SH SEE ALSO +.BR getgroups (2), +.BR setgroups (2), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/initstate.3 b/man3/initstate.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man3/initstate.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man3/initstate_r.3 b/man3/initstate_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man3/initstate_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man3/innetgr.3 b/man3/innetgr.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man3/innetgr.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man3/insque.3 b/man3/insque.3 new file mode 100644 index 0000000..bb7d7e3 --- /dev/null +++ b/man3/insque.3 @@ -0,0 +1,271 @@ +.\" peter memishian -- meem@gnu.ai.mit.edu +.\" $Id: insque.3,v 1.2 1996/10/30 21:03:39 meem Exp meem $ +.\" and Copyright (c) 2010, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code (5.4.7) +.\" Solaris 2.x, OSF/1, and HP-UX manpages +.\" Curry's "UNIX Systems Programming for SVR4" (O'Reilly & Associates 1996) +.\" +.\" Changed to POSIX, 2003-08-11, aeb+wh +.\" mtk, 2010-09-09: Noted glibc 2.4 bug, added info on circular +.\" lists, added example program +.\" +.TH INSQUE 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +insque, remque \- insert/remove an item from a queue +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void insque(void *" elem ", void *" prev ); +.PP +.BI "void remque(void *" elem ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR insque (), +.BR remque (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR insque () +and +.BR remque () +functions manipulate doubly-linked lists. +Each element in the list is a structure of +which the first two elements are a forward and a +backward pointer. +The linked list may be linear (i.e., NULL forward pointer at +the end of the list and NULL backward pointer at the start of the list) +or circular. +.PP +The +.BR insque () +function inserts the element pointed to by \fIelem\fP +immediately after the element pointed to by \fIprev\fP. +.PP +If the list is linear, then the call +.I "insque(elem, NULL)" +can be used to insert the initial list element, +and the call sets the forward and backward pointers of +.I elem +to NULL. +.PP +If the list is circular, +the caller should ensure that the forward and backward pointers of the +first element are initialized to point to that element, +and the +.I prev +argument of the +.BR insque () +call should also point to the element. +.PP +The +.BR remque () +function removes the element pointed to by \fIelem\fP from the +doubly-linked list. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR insque (), +.BR remque () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +On ancient systems, +.\" e.g., SunOS, Linux libc4 and libc5 +the arguments of these functions were of type \fIstruct qelem *\fP, +defined as: +.PP +.in +4n +.EX +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; + char q_data[1]; +}; +.EE +.in +.PP +This is still what you will get if +.B _GNU_SOURCE +is defined before +including \fI\fP. +.PP +The location of the prototypes for these functions differs among several +versions of UNIX. +The above is the POSIX version. +Some systems place them in \fI\fP. +.\" Linux libc4 and libc 5 placed them +.\" in \fI\fP. +.SH BUGS +In glibc 2.4 and earlier, it was not possible to specify +.I prev +as NULL. +Consequently, to build a linear list, the caller had to build a list +using an initial call that contained the first two elements of the list, +with the forward and backward pointers in each element suitably initialized. +.SH EXAMPLE +The program below demonstrates the use of +.BR insque (). +Here is an example run of the program: +.PP +.in +4n +.EX +.RB "$ " "./a.out -c a b c" +Traversing completed list: + a + b + c +That was a circular list +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include + +struct element { + struct element *forward; + struct element *backward; + char *name; +}; + +static struct element * +new_element(void) +{ + struct element *e; + + e = malloc(sizeof(struct element)); + if (e == NULL) { + fprintf(stderr, "malloc() failed\\n"); + exit(EXIT_FAILURE); + } + + return e; +} + +int +main(int argc, char *argv[]) +{ + struct element *first, *elem, *prev; + int circular, opt, errfnd; + + /* The "\-c" command\-line option can be used to specify that the + list is circular */ + + errfnd = 0; + circular = 0; + while ((opt = getopt(argc, argv, "c")) != \-1) { + switch (opt) { + case 'c': + circular = 1; + break; + default: + errfnd = 1; + break; + } + } + + if (errfnd || optind >= argc) { + fprintf(stderr, "Usage: %s [\-c] string...\\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* Create first element and place it in the linked list */ + + elem = new_element(); + first = elem; + + elem\->name = argv[optind]; + + if (circular) { + elem\->forward = elem; + elem\->backward = elem; + insque(elem, elem); + } else { + insque(elem, NULL); + } + + /* Add remaining command\-line arguments as list elements */ + + while (++optind < argc) { + prev = elem; + + elem = new_element(); + elem\->name = argv[optind]; + insque(elem, prev); + } + + /* Traverse the list from the start, printing element names */ + + printf("Traversing completed list:\\n"); + elem = first; + do { + printf(" %s\\n", elem\->name); + elem = elem\->forward; + } while (elem != NULL && elem != first); + + if (elem == first) + printf("That was a circular list\\n"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR queue (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/intro.3 b/man3/intro.3 new file mode 100644 index 0000000..8698c15 --- /dev/null +++ b/man3/intro.3 @@ -0,0 +1,118 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-10-23 mtk, Nearly a complete rewrite of the earlier page. +.TH INTRO 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- introduction to library functions +.SH DESCRIPTION +Section 3 of the manual describes all library functions excluding the library +functions (system call wrappers) described in Section 2, +which implement system calls. +.PP +Many of the functions described in the section are part of the +Standard C Library +.RI ( libc ). +Some functions are part of other libraries (e.g., +the math library, +.IR libm , +or the real-time library, +.IR librt ) +in which case the manual page will indicate the linker +option needed to link against the required library +(e.g., +.I \-lm +and +.IR \-lrt , +respectively, +for the aforementioned libraries). +.PP +In some cases, +the programmer must define a feature test macro in order to obtain +the declaration of a function from the header file specified +in the man page SYNOPSIS section. +(Where required, these feature test macros must be defined before including +.I any +header files.) +In such cases, the required macro is described in the man page. +For further information on feature test macros, see +.BR feature_test_macros (7). +.\" +.\" There +.\" are various function groups which can be identified by a letter which +.\" is appended to the chapter number: +.\" .IP (3C) +.\" These functions, the functions from chapter 2 and from chapter 3S are +.\" contained in the C standard library libc, which will be used by +.\" .BR cc (1) +.\" by default. +.\" .IP (3S) +.\" These functions are parts of the +.\" .BR stdio (3) +.\" library. They are contained in the standard C library libc. +.\" .IP (3M) +.\" These functions are contained in the arithmetic library libm. They are +.\" used by the +.\" .BR f77 (1) +.\" FORTRAN compiler by default, but not by the +.\" .BR cc (1) +.\" C compiler, which needs the option \fI\-lm\fP. +.\" .IP (3F) +.\" These functions are part of the FORTRAN library libF77. There are no +.\" special compiler flags needed to use these functions. +.\" .IP (3X) +.\" Various special libraries. The manual pages documenting their functions +.\" specify the library names. +.SH CONFORMING TO +Certain terms and abbreviations are used to indicate UNIX variants +and standards to which calls in this section conform. +See +.BR standards (7). +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR intro (2), +.BR errno (3), +.BR capabilities (7), +.BR credentials (7), +.BR environ (7), +.BR feature_test_macros (7), +.BR libc (7), +.BR math_error (7), +.BR path_resolution (7), +.BR pthreads (7), +.BR signal (7), +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iruserok.3 b/man3/iruserok.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man3/iruserok.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/iruserok_af.3 b/man3/iruserok_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man3/iruserok_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/isalnum.3 b/man3/isalnum.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isalnum.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isalnum_l.3 b/man3/isalnum_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isalnum_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isalpha.3 b/man3/isalpha.3 new file mode 100644 index 0000000..57ded07 --- /dev/null +++ b/man3/isalpha.3 @@ -0,0 +1,383 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 19:10:00 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 21 17:51:50 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Sep 2 21:52:01 1995 by Jim Van Zandt +.\" Modified Mon May 27 22:55:26 1996 by Martin Schulze (joey@linux.de) +.\" +.TH ISALPHA 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, +isprint, ispunct, isspace, isupper, isxdigit, +isalnum_l, isalpha_l, isascii_l, isblank_l, iscntrl_l, +isdigit_l, isgraph_l, islower_l, +isprint_l, ispunct_l, isspace_l, isupper_l, isxdigit_l +\- character classification functions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int isalnum(int " c ); +.BI "int isalpha(int " c ); +.BI "int iscntrl(int " c ); +.BI "int isdigit(int " c ); +.BI "int isgraph(int " c ); +.BI "int islower(int " c ); +.BI "int isprint(int " c ); +.BI "int ispunct(int " c ); +.BI "int isspace(int " c ); +.BI "int isupper(int " c ); +.BI "int isxdigit(int " c ); +.PP +.BI "int isascii(int " c ); +.BI "int isblank(int " c ); +.PP +.BI "int isalnum_l(int " c ", locale_t " locale ); +.BI "int isalpha_l(int " c ", locale_t " locale ); +.BI "int isblank_l(int " c ", locale_t " locale ); +.BI "int iscntrl_l(int " c ", locale_t " locale ); +.BI "int isdigit_l(int " c ", locale_t " locale ); +.BI "int isgraph_l(int " c ", locale_t " locale ); +.BI "int islower_l(int " c ", locale_t " locale ); +.BI "int isprint_l(int " c ", locale_t " locale ); +.BI "int ispunct_l(int " c ", locale_t " locale ); +.BI "int isspace_l(int " c ", locale_t " locale ); +.BI "int isupper_l(int " c ", locale_t " locale ); +.BI "int isxdigit_l(int " c ", locale_t " locale ); +.PP +.BI "int isascii_l(int " c ", locale_t " locale ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR isascii (): +.RS 4 +_XOPEN_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.RE +.PP +.BR isblank (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.PP +.BR isalnum_l (), +.BR isalpha_l (), +.BR isblank_l (), +.BR iscntrl_l (), +.BR isdigit_l (), +.BR isgraph_l (), +.BR islower_l (), +.BR isprint_l (), +.BR ispunct_l (), +.BR isspace_l (), +.BR isupper_l (), +.BR isxdigit_l (): +.PD 0 +.RS 4 +.TP +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.PP +.BR isascii_l (): +.PD 0 +.RS 4 +.TP +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 && (_SVID_SOURCE || _BSD_SOURCE) +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.ad +.SH DESCRIPTION +These functions check whether +.IR c , +which must have the value of an +.I unsigned char +or +.BR EOF , +falls into a certain character class according to the specified locale. +The functions without the +"_l" suffix perform the check based on the current locale. +.PP +The functions with the "_l" suffix perform the check +based on the locale specified by the locale object +.IR locale . +The behavior of these functions is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.PP +The list below explains the operation of the functions without +the "_l" suffix; +the functions with the "_l" suffix differ only in using the locale object +.I locale +instead of the current locale. +.TP +.BR isalnum () +checks for an alphanumeric character; it is equivalent to +.BI "(isalpha(" c ") || isdigit(" c "))" \fR. +.TP +.BR isalpha () +checks for an alphabetic character; in the standard \fB"C"\fP +locale, it is equivalent to +.BI "(isupper(" c ") || islower(" c "))" \fR. +In some locales, there may be additional characters for which +.BR isalpha () +is true\(emletters which are neither uppercase nor lowercase. +.TP +.BR isascii () +checks whether \fIc\fP is a 7-bit +.I unsigned char +value that fits into +the ASCII character set. +.TP +.BR isblank () +checks for a blank character; that is, a space or a tab. +.TP +.BR iscntrl () +checks for a control character. +.TP +.BR isdigit () +checks for a digit (0 through 9). +.TP +.BR isgraph () +checks for any printable character except space. +.TP +.BR islower () +checks for a lowercase character. +.TP +.BR isprint () +checks for any printable character including space. +.TP +.BR ispunct () +checks for any printable character which is not a space or an +alphanumeric character. +.TP +.BR isspace () +checks for white-space characters. +In the +.B """C""" +and +.B """POSIX""" +locales, these are: space, form-feed +.RB ( \(aq\ef\(aq ), +newline +.RB ( \(aq\en\(aq ), +carriage return +.RB ( \(aq\er\(aq ), +horizontal tab +.RB ( \(aq\et\(aq ), +and vertical tab +.RB ( \(aq\ev\(aq ). +.TP +.BR isupper () +checks for an uppercase letter. +.TP +.BR isxdigit () +checks for hexadecimal digits, that is, one of +.br +.BR "0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F" . +.SH RETURN VALUE +The values returned are nonzero if the character +.I c +falls into the tested class, and zero if not. +.SH VERSIONS +.BR isalnum_l (), +.BR isalpha_l (), +.BR isblank_l (), +.BR iscntrl_l (), +.BR isdigit_l (), +.BR isgraph_l (), +.BR islower_l (), +.BR isprint_l (), +.BR ispunct_l (), +.BR isspace_l (), +.BR isupper_l (), +.BR isxdigit_l (), +and +.BR isascii_l () +are available since glibc 2.3. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw32 lb lb +l l l. +Interface Attribute Value +T{ +.BR isalnum (), +.BR isalpha (), +.BR isascii (), +.BR isblank (), +.BR iscntrl (), +.BR isdigit (), +.BR isgraph (), +.BR islower (), +.BR isprint (), +.BR ispunct (), +.BR isspace (), +.BR isupper (), +.BR isxdigit () +T} Thread safety MT-Safe +.TE +.ad +.\" FIXME: need a thread-safety statement about the *_l functions +.SH CONFORMING TO +C89 specifies +.BR isalnum (), +.BR isalpha (), +.BR iscntrl (), +.BR isdigit (), +.BR isgraph (), +.BR islower (), +.BR isprint (), +.BR ispunct (), +.BR isspace (), +.BR isupper (), +and +.BR isxdigit (), +but not +.BR isascii () +and +.BR isblank (). +POSIX.1-2001 +also specifies those functions, and also +.BR isascii () +(as an XSI extension) +and +.BR isblank (). +C99 specifies all of the preceding functions, except +.BR isascii (). +.PP +POSIX.1-2008 marks +.BR isascii () +as obsolete, +noting that it cannot be used portably in a localized application. +.PP +POSIX.1-2008 specifies +.BR isalnum_l (), +.BR isalpha_l (), +.BR isblank_l (), +.BR iscntrl_l (), +.BR isdigit_l (), +.BR isgraph_l (), +.BR islower_l (), +.BR isprint_l (), +.BR ispunct_l (), +.BR isspace_l (), +.BR isupper_l (), +and +.BR isxdigit_l (). +.PP +.BR isascii_l () +is a GNU extension. +.SH NOTES +The standards require that the argument +.I c +for these functions is either +.B EOF +or a value that is representable in the type +.IR "unsigned char" . +If the argument +.I c +is of type +.IR char , +it must be cast to +.IR "unsigned char" , +as in the following example: +.PP +.in +4n +.EX +char c; +\&... +res = toupper((unsigned char) c); +.EE +.in +.PP +This is necessary because +.I char +may be the equivalent of +.IR "signed char" , +in which case a byte where the top bit is set would be sign extended when +converting to +.IR int , +yielding a value that is outside the range of +.IR "unsigned char" . +.PP +The details of what characters belong to which class depend on the +locale. +For example, +.BR isupper () +will not recognize an A-umlaut (\(:A) as an uppercase letter in the default +.B "C" +locale. +.SH SEE ALSO +.BR iswalnum (3), +.BR iswalpha (3), +.BR iswblank (3), +.BR iswcntrl (3), +.BR iswdigit (3), +.BR iswgraph (3), +.BR iswlower (3), +.BR iswprint (3), +.BR iswpunct (3), +.BR iswspace (3), +.BR iswupper (3), +.BR iswxdigit (3), +.BR newlocale (3), +.BR setlocale (3), +.BR toascii (3), +.BR tolower (3), +.BR toupper (3), +.BR uselocale (3), +.BR ascii (7), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/isalpha_l.3 b/man3/isalpha_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isalpha_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isascii.3 b/man3/isascii.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isascii.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isascii_l.3 b/man3/isascii_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isascii_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isatty.3 b/man3/isatty.3 new file mode 100644 index 0000000..f658e9f --- /dev/null +++ b/man3/isatty.3 @@ -0,0 +1,87 @@ +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ISATTY 3 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +isatty \- test whether a file descriptor refers to a terminal +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int isatty(int " fd ); +.fi +.SH DESCRIPTION +The +.BR isatty () +function tests whether +.I fd +is an open file descriptor referring to a terminal. +.SH RETURN VALUE +.BR isatty () +returns 1 if +.I fd +is an open file descriptor referring to a terminal; +otherwise 0 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I fd +refers to a file other than a terminal. +POSIX.1 specifies the error +.BR ENOTTY +.\" FIXME . File a bug for this? +for this case. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR isatty () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fstat (2), +.BR ttyname (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/isblank.3 b/man3/isblank.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isblank.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isblank_l.3 b/man3/isblank_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isblank_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/iscntrl.3 b/man3/iscntrl.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/iscntrl.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/iscntrl_l.3 b/man3/iscntrl_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/iscntrl_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isdigit.3 b/man3/isdigit.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isdigit.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isdigit_l.3 b/man3/isdigit_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isdigit_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isfdtype.3 b/man3/isfdtype.3 new file mode 100644 index 0000000..602ab01 --- /dev/null +++ b/man3/isfdtype.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ISFDTYPE 3 2014-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +isfdtype \- test file type of a file descriptor +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int isfdtype(int " fd ", int " fdtype ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR isfdtype (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.20: +_DEFAULT_SOURCE +.TP 4 +Before glibc 2.20: +_BSD_SOURCE || _SVID_SOURCE +.PD +.RE +.ad b +.SH DESCRIPTION +The +.BR isfdtype () +function tests whether the file descriptor +.I fd +refers to a file of type +.IR fdtype . +The +.I fdtype +argument specifies one of the +.B S_IF* +constants defined in +.I +and documented in +.BR stat (2) +(e.g., +.BR S_IFREG ). +.SH RETURN VALUE +The +.BR isfdtype () +function returns 1 if the file descriptor +.I fd +is of type +.IR fdtype +and 0 if it is not. +On error, -1 is returned and +.I errno +is set to indicate the cause. +.SH ERRORS +The +.BR isfdtype () +function can fail with any of the same errors as +.BR fstat (3). +.SH CONFORMING TO +The +.BR isfdtype () +function is not specified in any standard, +but did appear in the draft POSIX.1g standard. +It is present on OpenBSD and Tru64 UNIX +(where the required header file in both cases is just +.IR , +as shown in the POSIX.1g draft), +and possibly other systems. +.SH NOTES +Portable applications should use +.BR fstat (3) +instead. +.SH SEE ALSO +.BR fstat (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/isfinite.3 b/man3/isfinite.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man3/isfinite.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man3/isgraph.3 b/man3/isgraph.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isgraph.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isgraph_l.3 b/man3/isgraph_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isgraph_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isgreater.3 b/man3/isgreater.3 new file mode 100644 index 0000000..91d4d5c --- /dev/null +++ b/man3/isgreater.3 @@ -0,0 +1,158 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" 2002-07-27 Walter Harms +.\" this was done with the help of the glibc manual +.\" +.TH ISGREATER 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +isgreater, isgreaterequal, isless, islessequal, islessgreater, +isunordered \- floating-point relational tests without exception for NaN +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int isgreater(" x ", " y ); +.PP +.BI "int isgreaterequal(" x ", " y ); +.PP +.BI "int isless(" x ", " y ); +.PP +.BI "int islessequal(" x ", " y ); +.PP +.BI "int islessgreater(" x ", " y ); +.PP +.BI "int isunordered(" x ", " y ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +All functions described here: +.RS +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad b +.SH DESCRIPTION +The normal relational operations (like +.BR < , +"less than") +fail if one of the operands is NaN. +This will cause an exception. +To avoid this, C99 defines the macros listed below. +.PP +These macros are guaranteed to evaluate their arguments only once. +The arguments must be of real floating-point type (note: do not pass +integer values as arguments to these macros, since the arguments will +.I not +be promoted to real-floating types). +.TP +.BR isgreater () +determines \fI(x)\ >\ (y)\fP without an exception +if +.IR x +or +.I y +is NaN. +.TP +.BR isgreaterequal () +determines \fI(x)\ >=\ (y)\fP without an exception +if +.IR x +or +.I y +is NaN. +.TP +.BR isless () +determines \fI(x)\ <\ (y)\fP without an exception +if +.IR x +or +.I y +is NaN. +.TP +.BR islessequal () +determines \fI(x)\ <=\ (y)\fP without an exception +if +.IR x +or +.I y +is NaN. +.TP +.BR islessgreater () +determines \fI(x)\ < (y) || (x) >\ (y)\fP +without an exception if +.IR x +or +.I y +is NaN. +This macro is not equivalent to \fIx\ !=\ y\fP because that expression is +true if +.IR x +or +.I y +is NaN. +.TP +.BR isunordered () +determines whether its arguments are unordered, that is, whether +at least one of the arguments is a NaN. +.SH RETURN VALUE +The macros other than +.BR isunordered () +return the result of the relational comparison; +these macros return 0 if either argument is a NaN. +.PP +.BR isunordered () +returns 1 if +.IR x +or +.I y +is NaN and 0 otherwise. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR isgreater (), +.BR isgreaterequal (), +.BR isless (), +.BR islessequal (), +.BR islessgreater (), +.BR isunordered () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +Not all hardware supports these functions, +and where hardware support isn't provided, they will be emulated by macros. +This will result in a performance penalty. +Don't use these functions if NaN is of no concern for you. +.SH SEE ALSO +.BR fpclassify (3), +.BR isnan (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/isgreaterequal.3 b/man3/isgreaterequal.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man3/isgreaterequal.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/isinf.3 b/man3/isinf.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man3/isinf.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man3/isinff.3 b/man3/isinff.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man3/isinff.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/isinfl.3 b/man3/isinfl.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man3/isinfl.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/isless.3 b/man3/isless.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man3/isless.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/islessequal.3 b/man3/islessequal.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man3/islessequal.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/islessgreater.3 b/man3/islessgreater.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man3/islessgreater.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/islower.3 b/man3/islower.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/islower.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/islower_l.3 b/man3/islower_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/islower_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isnan.3 b/man3/isnan.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man3/isnan.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man3/isnanf.3 b/man3/isnanf.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man3/isnanf.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/isnanl.3 b/man3/isnanl.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man3/isnanl.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man3/isnormal.3 b/man3/isnormal.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man3/isnormal.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man3/isprint.3 b/man3/isprint.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isprint.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isprint_l.3 b/man3/isprint_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isprint_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/ispunct.3 b/man3/ispunct.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/ispunct.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/ispunct_l.3 b/man3/ispunct_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/ispunct_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isspace.3 b/man3/isspace.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isspace.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isspace_l.3 b/man3/isspace_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isspace_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isunordered.3 b/man3/isunordered.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man3/isunordered.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man3/isupper.3 b/man3/isupper.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isupper.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isupper_l.3 b/man3/isupper_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isupper_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/iswalnum.3 b/man3/iswalnum.3 new file mode 100644 index 0000000..0b9e1d9 --- /dev/null +++ b/man3/iswalnum.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWALNUM 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswalnum \- test for alphanumeric wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswalnum(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswalnum () +function is the wide-character equivalent of the +.BR isalnum (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "alnum". +.PP +The wide-character class "alnum" is a subclass of the wide-character class +"graph", and therefore also a subclass of the wide-character class "print". +.PP +Being a subclass of the wide-character class "print", +the wide-character class +"alnum" is disjoint from the wide-character class "cntrl". +.PP +Being a subclass of the wide-character class "graph", +the wide-character class "alnum" is disjoint from +the wide-character class "space" and its subclass "blank". +.PP +The wide-character class "alnum" is disjoint from the wide-character class +"punct". +.PP +The wide-character class "alnum" is the union of the wide-character classes +"alpha" and "digit". +As such, it also contains the wide-character class +"xdigit". +.PP +The wide-character class "alnum" always contains at least the letters \(aqA\(aq +to \(aqZ\(aq, \(aqa\(aq to \(aqz\(aq and the digits \(aq0\(aq to \(aq9\(aq. +.SH RETURN VALUE +The +.BR iswalnum () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "alnum". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswalnum () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswalnum () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isalnum (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswalpha.3 b/man3/iswalpha.3 new file mode 100644 index 0000000..4f23d2b --- /dev/null +++ b/man3/iswalpha.3 @@ -0,0 +1,102 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWALPHA 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswalpha \- test for alphabetic wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswalpha(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswalpha () +function is the wide-character equivalent of the +.BR isalpha (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "alpha". +.PP +The wide-character class "alpha" is a subclass of the +wide-character class "alnum", +and therefore also a subclass of the wide-character class "graph" and +of the wide-character class "print". +.PP +Being a subclass of the wide-character class "print", +the wide-character class +"alpha" is disjoint from the wide-character class "cntrl". +.PP +Being a subclass of the wide-character class "graph", +the wide-character class "alpha" is disjoint from +the wide-character class "space" and its subclass "blank". +.PP +Being a subclass of the wide-character class "alnum", +the wide-character class "alpha" is disjoint from the +wide-character class "punct". +.PP +The wide-character class "alpha" is disjoint from the wide-character class +"digit". +.PP +The wide-character class "alpha" contains the wide-character classes "upper" +and "lower". +.PP +The wide-character class "alpha" always contains at least the +letters \(aqA\(aq to \(aqZ\(aq and \(aqa\(aq to \(aqz\(aq. +.SH RETURN VALUE +The +.BR iswalpha () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "alpha". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswalpha () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswalpha () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isalpha (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswblank.3 b/man3/iswblank.3 new file mode 100644 index 0000000..c5d89db --- /dev/null +++ b/man3/iswblank.3 @@ -0,0 +1,97 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWBLANK 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +iswblank \- test for whitespace wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswblank(wint_t " wc ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR iswblank (): +.RS +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +The +.BR iswblank () +function is the wide-character equivalent of the +.BR isblank (3) +function. +It tests whether \fIwc\fP is a wide character +belonging to the wide-character class "blank". +.PP +The wide-character class "blank" is a subclass of the wide-character class +"space". +.PP +Being a subclass of the wide-character class "space", +the wide-character class "blank" is disjoint from the +wide-character class "graph" and therefore also disjoint +from its subclasses "alnum", "alpha", "upper", "lower", "digit", +"xdigit", "punct". +.PP +The wide-character class "blank" always contains +at least the space character +and the control character \(aq\\t\(aq. +.SH RETURN VALUE +The +.BR iswblank () +function returns nonzero +if \fIwc\fP is a wide character +belonging to the wide-character class "blank". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswblank () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The behavior of +.BR iswblank () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isblank (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswcntrl.3 b/man3/iswcntrl.3 new file mode 100644 index 0000000..891a24a --- /dev/null +++ b/man3/iswcntrl.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWCNTRL 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswcntrl \- test for control wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswcntrl(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswcntrl () +function is the wide-character equivalent of the +.BR iscntrl (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "cntrl". +.PP +The wide-character class "cntrl" is disjoint from the wide-character class +"print" and therefore also disjoint from its subclasses "graph", "alpha", +"upper", "lower", "digit", "xdigit", "punct". +.PP +For an unsigned char +.IR c , +.I iscntrl(c) +implies +.IR iswcntrl(btowc(c)) , +but not vice versa. +.SH RETURN VALUE +The +.BR iswcntrl () +function returns nonzero if +.I wc +is a +wide character belonging to the wide-character class "cntrl". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswcntrl () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswcntrl () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iscntrl (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswctype.3 b/man3/iswctype.3 new file mode 100644 index 0000000..e0f5847 --- /dev/null +++ b/man3/iswctype.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWCTYPE 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswctype \- wide-character classification +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswctype(wint_t " wc ", wctype_t " desc ); +.fi +.SH DESCRIPTION +If +.I wc +is a wide character having the character property designated by +.I desc +(or in other words: belongs to the character class designated by +.IR desc ), +the +.BR iswctype () +function returns nonzero. +Otherwise, it +returns zero. +If +.I wc +is +.BR WEOF , +zero is returned. +.PP +.I desc +must be a character property descriptor +returned by the +.BR wctype (3) +function. +.SH RETURN VALUE +The +.BR iswctype () +function returns nonzero if +the +.I wc +has the designated +property. +Otherwise, it returns 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswctype () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswctype () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswalnum (3), +.BR iswalpha (3), +.BR iswblank (3), +.BR iswcntrl (3), +.BR iswdigit (3), +.BR iswgraph (3), +.BR iswlower (3), +.BR iswprint (3), +.BR iswpunct (3), +.BR iswspace (3), +.BR iswupper (3), +.BR iswxdigit (3), +.BR wctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswdigit.3 b/man3/iswdigit.3 new file mode 100644 index 0000000..949e231 --- /dev/null +++ b/man3/iswdigit.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWDIGIT 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswdigit \- test for decimal digit wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswdigit(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswdigit () +function is the wide-character equivalent of the +.BR isdigit (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "digit". +.PP +The wide-character class "digit" is a subclass of the wide-character class +"xdigit", and therefore also a subclass +of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.PP +Being a subclass of the wide character +class "print", the wide-character class +"digit" is disjoint from the wide-character class "cntrl". +.PP +Being a subclass of the wide-character class "graph", +the wide-character class +"digit" is disjoint from the wide-character class "space" and its subclass +"blank". +.PP +Being a subclass of the wide-character +class "alnum", the wide-character class +"digit" is disjoint from the wide-character class "punct". +.PP +The wide-character class "digit" is +disjoint from the wide-character class +"alpha" and therefore also disjoint from its subclasses "lower", "upper". +.PP +The wide-character class "digit" always +contains exactly the digits \(aq0\(aq to \(aq9\(aq. +.SH RETURN VALUE +The +.BR iswdigit () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "digit". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswdigit () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswdigit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isdigit (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswgraph.3 b/man3/iswgraph.3 new file mode 100644 index 0000000..7d8ffb0 --- /dev/null +++ b/man3/iswgraph.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWGRAPH 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswgraph \- test for graphic wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswgraph(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswgraph () +function is the wide-character equivalent of the +.BR isgraph (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "graph". +.PP +The wide-character class "graph" is a subclass of the wide-character class +"print". +.PP +Being a subclass of the wide-character class "print", +the wide-character class +"graph" is disjoint from the wide-character class "cntrl". +.PP +The wide-character class "graph" is disjoint from the wide-character class +"space" and therefore also disjoint from its subclass "blank". +.\" Note: UNIX98 (susv2/xbd/locale.html) says that "graph" and "space" may +.\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999 +.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. +.PP +The wide-character class "graph" contains all the wide characters from the +wide-character class "print" except the space character. +It therefore contains +the wide-character classes "alnum" and "punct". +.SH RETURN VALUE +The +.BR iswgraph () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "graph". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswgraph () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswgraph () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isgraph (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswlower.3 b/man3/iswlower.3 new file mode 100644 index 0000000..fde3352 --- /dev/null +++ b/man3/iswlower.3 @@ -0,0 +1,112 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWLOWER 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswlower \- test for lowercase wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswlower(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswlower () +function is the wide-character equivalent of the +.BR islower (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "lower". +.PP +The wide-character class "lower" is a subclass of the wide-character class +"alpha", and therefore also a subclass +of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.PP +Being a subclass of the wide-character class "print", +the wide-character class +"lower" is disjoint from the wide-character class "cntrl". +.PP +Being a subclass of the wide-character class "graph", +the wide-character class "lower" is disjoint from the +wide-character class "space" and its subclass "blank". +.PP +Being a subclass of the wide-character class "alnum", +the wide-character class +"lower" is disjoint from the wide-character class "punct". +.PP +Being a subclass of the wide-character class "alpha", +the wide-character class +"lower" is disjoint from the wide-character class "digit". +.PP +The wide-character class "lower" contains at least +those characters +.I wc +which are equal to +.I towlower(wc) +and different from +.IR towupper(wc) . +.PP +The wide-character class "lower" always contains +at least the letters \(aqa\(aq to \(aqz\(aq. +.SH RETURN VALUE +The +.BR iswlower () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "lower". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswlower () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswlower () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower and title case. +.SH SEE ALSO +.BR islower (3), +.BR iswctype (3), +.BR towlower (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswprint.3 b/man3/iswprint.3 new file mode 100644 index 0000000..9c2353a --- /dev/null +++ b/man3/iswprint.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWPRINT 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswprint \- test for printing wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswprint(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswprint () +function is the wide-character equivalent of the +.BR isprint (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "print". +.PP +The wide-character class "print" is disjoint from the wide-character class +"cntrl". +.PP +The wide-character class "print" contains the wide-character class "graph". +.SH RETURN VALUE +The +.BR iswprint () +function returns nonzero if +.I wc +is a +wide character belonging to the wide-character class "print". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswprint () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswprint () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isprint (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswpunct.3 b/man3/iswpunct.3 new file mode 100644 index 0000000..1dffaad --- /dev/null +++ b/man3/iswpunct.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWPUNCT 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswpunct \- test for punctuation or symbolic wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswpunct(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswpunct () +function is the wide-character equivalent of the +.BR ispunct (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "punct". +.PP +The wide-character class "punct" is a subclass of the wide-character class +"graph", and therefore also a subclass of the wide-character class "print". +.PP +The wide-character class "punct" is disjoint from the wide-character class +"alnum" and therefore also disjoint from its subclasses "alpha", "upper", +"lower", "digit", "xdigit". +.PP +Being a subclass of the wide-character class "print", +the wide-character class +"punct" is disjoint from the wide-character class "cntrl". +.PP +Being a subclass of the wide-character class "graph", +the wide-character class +"punct" is disjoint from the wide-character class "space" and its subclass +"blank". +.SH RETURN VALUE +The +.BR iswpunct () +function returns nonzero +if +.I wc +is a wide-character +belonging to the wide-character class "punct". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswpunct () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswpunct () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +This function's name is a misnomer when dealing with Unicode characters, +because the wide-character class "punct" contains both punctuation characters +and symbol (math, currency, etc.) characters. +.SH SEE ALSO +.BR ispunct (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswspace.3 b/man3/iswspace.3 new file mode 100644 index 0000000..ac42d70 --- /dev/null +++ b/man3/iswspace.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWSPACE 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswspace \- test for whitespace wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswspace(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswspace () +function is the wide-character equivalent of the +.BR isspace (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "space". +.PP +The wide-character class "space" is disjoint from the wide-character class +"graph" and therefore also disjoint from its subclasses "alnum", "alpha", +"upper", "lower", "digit", "xdigit", "punct". +.\" Note: UNIX98 (susv2/xbd/locale.html) says that "space" and "graph" may +.\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999 +.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. +.PP +The wide-character class "space" contains the wide-character class "blank". +.PP +The wide-character class "space" always contains at least the space character +and the control +characters \(aq\\f\(aq, \(aq\\n\(aq, \(aq\\r\(aq, \(aq\\t\(aq, \(aq\\v\(aq. +.SH RETURN VALUE +The +.BR iswspace () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "space". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswspace () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswspace () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isspace (3), +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswupper.3 b/man3/iswupper.3 new file mode 100644 index 0000000..1e0728d --- /dev/null +++ b/man3/iswupper.3 @@ -0,0 +1,106 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWUPPER 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswupper \- test for uppercase wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswupper(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswupper () +function is the wide-character equivalent of the +.BR isupper (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "upper". +.PP +The wide-character class "upper" is a subclass of the wide-character class +"alpha", and therefore also a subclass of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.PP +Being a subclass of the wide-character class "print", the wide-character class +"upper" is disjoint from the wide-character class "cntrl". +.PP +Being a subclass of the wide-character class "graph", the wide-character class +"upper" is disjoint from the wide-character class "space" and its subclass +"blank". +.PP +Being a subclass of the wide-character class "alnum", the wide-character class +"upper" is disjoint from the wide-character class "punct". +.PP +Being a subclass of the wide-character class "alpha", the wide-character class +"upper" is disjoint from the wide-character class "digit". +.PP +The wide-character class "upper" contains at least those characters +.I wc +which are equal to +.I towupper(wc) +and different from +.IR towlower(wc) . +.PP +The wide-character class "upper" always contains at least the +letters \(aqA\(aq to \(aqZ\(aq. +.SH RETURN VALUE +The +.BR iswupper () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "upper". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswupper () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswupper () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower and title case. +.SH SEE ALSO +.BR isupper (3), +.BR iswctype (3), +.BR towupper (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/iswxdigit.3 b/man3/iswxdigit.3 new file mode 100644 index 0000000..231ab2f --- /dev/null +++ b/man3/iswxdigit.3 @@ -0,0 +1,93 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ISWXDIGIT 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +iswxdigit \- test for hexadecimal digit wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int iswxdigit(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswxdigit () +function is the wide-character equivalent of the +.BR isxdigit (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "xdigit". +.PP +The wide-character class "xdigit" is a subclass of the wide-character class +"alnum", and therefore also a subclass of the wide-character class "graph" and +of the wide-character class "print". +.PP +Being a subclass of the wide-character class "print", the wide-character class +"xdigit" is disjoint from the wide-character class "cntrl". +.PP +Being a subclass of the wide-character class "graph", the wide-character class +"xdigit" is disjoint from the wide-character class "space" and its subclass +"blank". +.PP +Being a subclass of the wide-character class "alnum", the wide-character class +"xdigit" is disjoint from the wide-character class "punct". +.PP +The wide-character class "xdigit" always contains at least the +letters \(aqA\(aq to \(aqF\(aq, \(aqa\(aq to \(aqf\(aq +and the digits \(aq0\(aq to \(aq9\(aq. +.SH RETURN VALUE +The +.BR iswxdigit () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "xdigit". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR iswxdigit () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR iswxdigit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswctype (3), +.BR isxdigit (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/isxdigit.3 b/man3/isxdigit.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isxdigit.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/isxdigit_l.3 b/man3/isxdigit_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man3/isxdigit_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man3/j0.3 b/man3/j0.3 new file mode 100644 index 0000000..3fc8e51 --- /dev/null +++ b/man3/j0.3 @@ -0,0 +1,204 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:08:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-25, aeb +.\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB +.\" 2008-07-24, mtk, moved yxx() material into separate y0.3 page +.\" +.TH J0 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +j0, j0f, j0l, j1, j1f, j1l, jn, jnf, jnl \- +Bessel functions of the first kind +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double j0(double " x ); +.BI "double j1(double " x ); +.BI "double jn(int " n ", double " x ); +.PP +.BI "float j0f(float " x ); +.BI "float j1f(float " x ); +.BI "float jnf(int " n ", float " x ); +.PP +.BI "long double j0l(long double " x ); +.BI "long double j1l(long double " x ); +.BI "long double jnl(int " n ", long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR j0 (), +.BR j1 (), +.BR jn (): +.RS 4 +_XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.br +.BR j0f (), +.BR j0l (), +.BR j1f (), +.BR j1l (), +.BR jnf (), +.BR jnl (): +.RS 4 +_XOPEN_SOURCE \ >=\ 600 + || (_ISOC99_SOURCE && _XOPEN_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR j0 () +and +.BR j1 () +functions return Bessel functions of +.I x +of the first kind of orders 0 and 1, respectively. +The +.BR jn () +function +returns the Bessel function of +.I x +of the first kind of order +.IR n . +.PP +The +.BR j0f (), +.BR j1f (), +and +.BR jnf (), +functions are versions that take and return +.I float +values. +The +.BR j0l (), +.BR j1l (), +and +.BR jnl () +functions are versions that take and return +.I "long double" +values. +.SH RETURN VALUE +On success, these functions return the appropriate +Bessel value of the first kind for +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is too large in magnitude, +or the result underflows, +a range error occurs, +and the return value is 0. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error: result underflow, or \fIx\fP is too large in magnitude +.I errno +is set to +.BR ERANGE . +.\" An underflow floating-point exception +.\" .RB ( FE_UNDERFLOW ) +.\" is raised. +.PP +These functions do not raise exceptions for +.BR fetestexcept (3). +.\" FIXME . Is it intentional that these functions do not raise exceptions? +.\" e.g., j0(1.5e16) +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6805 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR j0 (), +.BR j0f (), +.BR j0l () +T} Thread safety MT-Safe +T{ +.BR j1 (), +.BR j1f (), +.BR j1l () +T} Thread safety MT-Safe +T{ +.BR jn (), +.BR jnf (), +.BR jnl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The functions returning +.I double +conform to SVr4, 4.3BSD, +POSIX.1-2001, and POSIX.1-2008. +The others are nonstandard functions that also exist on the BSDs. +.SH BUGS +There are errors of up to 2e\-16 in the values returned by +.BR j0 (), +.BR j1 () +and +.BR jn () +for values of +.I x +between \-8 and 8. +.SH SEE ALSO +.BR y0 (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/j0f.3 b/man3/j0f.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man3/j0f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/j0l.3 b/man3/j0l.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man3/j0l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/j1.3 b/man3/j1.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man3/j1.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/j1f.3 b/man3/j1f.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man3/j1f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/j1l.3 b/man3/j1l.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man3/j1l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/jn.3 b/man3/jn.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man3/jn.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/jnf.3 b/man3/jnf.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man3/jnf.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/jnl.3 b/man3/jnl.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man3/jnl.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man3/jrand48.3 b/man3/jrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man3/jrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/jrand48_r.3 b/man3/jrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man3/jrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/key_decryptsession.3 b/man3/key_decryptsession.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man3/key_decryptsession.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man3/key_encryptsession.3 b/man3/key_encryptsession.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man3/key_encryptsession.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man3/key_gendes.3 b/man3/key_gendes.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man3/key_gendes.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man3/key_secretkey_is_set.3 b/man3/key_secretkey_is_set.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man3/key_secretkey_is_set.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man3/key_setsecret.3 b/man3/key_setsecret.3 new file mode 100644 index 0000000..a7758e7 --- /dev/null +++ b/man3/key_setsecret.3 @@ -0,0 +1,99 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" I had no way the check the functions out +.\" be careful +.TH KEY_SETSECRET 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +key_decryptsession, key_encryptsession, key_setsecret, key_gendes, +key_secretkey_is_set \- interfaces to rpc keyserver daemon +.SH SYNOPSIS +.B "#include " +.PP +.BI "int key_decryptsession(char *" remotename , +.BI "des_block *" deskey ); +.PP +.BI "int key_encryptsession(char *" remotename , +.BI "des_block *" deskey ); +.PP +.BI "int key_gendes(des_block *" deskey ); +.PP +.BI "int key_setsecret(char *" key ); +.PP +.B "int key_secretkey_is_set(void);" +.SH DESCRIPTION +The functions here are used within the RPC's secure authentication +mechanism (AUTH_DES). +There should be no need for user programs to +use this functions. +.PP +The function +.BR key_decryptsession () +uses the (remote) server netname and takes the DES key +for decrypting. +It uses the public key of the server and the +secret key associated with the effective UID of the calling process. +.PP +The function +.BR key_encryptsession () +is the inverse of +.BR key_decryptsession (). +It encrypts the DES keys with the public key of the server and +the secret key associated with the effective UID of the calling process. +.PP +The function +.BR key_gendes () +is used to ask the keyserver for a secure conversation key. +.PP +The function +.BR key_setsecret () +is used to set the key for the effective UID of the calling process. +.PP +The function +.BR key_secretkey_is_set () +can be used to determine whether a key has been +set for the effective UID of the calling process. +.SH RETURN VALUE +These functions return 1 on success and 0 on failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw22 lb lb +l l l. +Interface Attribute Value +T{ +.BR key_decryptsession (), +.br +.BR key_encryptsession (), +.br +.BR key_gendes (), +.br +.BR key_setsecret (), +.br +.BR key_secretkey_is_set () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH NOTES +Note that we talk about two types of encryption here. +One is asymmetric using a public and secret key. +The other is symmetric, the +64-bit DES. +.PP +These routines were part of the Linux/Doors-project, abandoned by now. +.SH SEE ALSO +.BR crypt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/killpg.3 b/man3/killpg.3 new file mode 100644 index 0000000..103ab72 --- /dev/null +++ b/man3/killpg.3 @@ -0,0 +1,144 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)killpg.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified Fri Jul 23 21:55:01 1993 by Rik Faith +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added notes on CAP_KILL +.\" Modified 2004-06-21 by aeb +.\" +.TH KILLPG 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +killpg \- send signal to a process group +.SH SYNOPSIS +.B #include +.PP +.BI "int killpg(int " pgrp ", int " sig ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.TP 4 +.BR killpg (): +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.ad +.SH DESCRIPTION +.BR killpg () +sends the signal +.I sig +to the process group +.IR pgrp . +See +.BR signal (7) +for a list of signals. +.PP +If +.I pgrp +is 0, +.BR killpg () +sends the signal to the calling process's process group. +(POSIX says: if +.I pgrp +is less than or equal to 1, the behavior is undefined.) +.PP +For the permissions required to send a signal to another process, see +.BR kill (2). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +.I sig +is not a valid signal number. +.TP +.B EPERM +The process does not have permission to send the signal +to any of the target processes. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process can be found in the process group specified by +.IR pgrp . +.TP +.B ESRCH +The process group was given as 0 but the sending process does not +have a process group. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD +.RB ( killpg () +first appeared in 4BSD). +.SH NOTES +There are various differences between the permission checking +in BSD-type systems and System\ V-type systems. +See the POSIX rationale for +.BR kill (). +A difference not mentioned by POSIX concerns the return +value +.BR EPERM : +BSD documents that no signal is sent and +.B EPERM +returned when the permission check failed for at least one target process, +while POSIX documents +.B EPERM +only when the permission check failed for all target processes. +.SS C library/kernel differences +On Linux, +.BR killpg () +is implemented as a library function that makes the call +.IR "kill(-pgrp,\ sig)" . +.SH SEE ALSO +.BR getpgrp (2), +.BR kill (2), +.BR signal (2), +.BR capabilities (7), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/klogctl.3 b/man3/klogctl.3 new file mode 100644 index 0000000..bbe6ab2 --- /dev/null +++ b/man3/klogctl.3 @@ -0,0 +1 @@ +.so man2/syslog.2 diff --git a/man3/l64a.3 b/man3/l64a.3 new file mode 100644 index 0000000..e54ce27 --- /dev/null +++ b/man3/l64a.3 @@ -0,0 +1 @@ +.so man3/a64l.3 diff --git a/man3/labs.3 b/man3/labs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man3/labs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man3/lckpwdf.3 b/man3/lckpwdf.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/lckpwdf.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/lcong48.3 b/man3/lcong48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man3/lcong48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/lcong48_r.3 b/man3/lcong48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man3/lcong48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/ldexp.3 b/man3/ldexp.3 new file mode 100644 index 0000000..5ba2317 --- /dev/null +++ b/man3/ldexp.3 @@ -0,0 +1,156 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2004-10-31 by aeb +.\" +.TH LDEXP 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ldexp, ldexpf, ldexpl \- multiply floating-point number by integral power of 2 +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double ldexp(double " x ", int " exp ); +.BI "float ldexpf(float " x ", int " exp ); +.BI "long double ldexpl(long double " x ", int " exp ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR ldexpf (), +.BR ldexpl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the result of multiplying the floating-point number +.I x +by 2 raised to the power +.IR exp . +.SH RETURN VALUE +On success, these functions return +.IR "x * (2^exp)" . +.PP +If +.I exp +is zero, then +.I x +is returned. +.PP +If +.I x +is a NaN, +a NaN is returned. +.PP +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.PP +If the result underflows, +a range error occurs, +and zero is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR ldexp (), +.BR ldexpf (), +.BR ldexpl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR frexp (3), +.BR modf (3), +.BR scalbln (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ldexpf.3 b/man3/ldexpf.3 new file mode 100644 index 0000000..0e74a02 --- /dev/null +++ b/man3/ldexpf.3 @@ -0,0 +1 @@ +.so man3/ldexp.3 diff --git a/man3/ldexpl.3 b/man3/ldexpl.3 new file mode 100644 index 0000000..0e74a02 --- /dev/null +++ b/man3/ldexpl.3 @@ -0,0 +1 @@ +.so man3/ldexp.3 diff --git a/man3/ldiv.3 b/man3/ldiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man3/ldiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man3/le16toh.3 b/man3/le16toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/le16toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/le32toh.3 b/man3/le32toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/le32toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/le64toh.3 b/man3/le64toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man3/le64toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man3/lfind.3 b/man3/lfind.3 new file mode 100644 index 0000000..24179b4 --- /dev/null +++ b/man3/lfind.3 @@ -0,0 +1 @@ +.so man3/lsearch.3 diff --git a/man3/lgamma.3 b/man3/lgamma.3 new file mode 100644 index 0000000..92bc1d3 --- /dev/null +++ b/man3/lgamma.3 @@ -0,0 +1,185 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" based on glibc infopages +.\" +.TH LGAMMA 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +lgamma, lgammaf, lgammal, lgamma_r, lgammaf_r, lgammal_r, signgam \- +log gamma function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double lgamma(double " x ); +.BI "float lgammaf(float " x ); +.BI "long double lgammal(long double " x ); +.PP +.BI "double lgamma_r(double " x ", int *" signp ); +.BI "float lgammaf_r(float " x ", int *" signp ); +.BI "long double lgammal_r(long double " x ", int *" signp ); +.PP +.BI "extern int " signgam ; +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR lgamma (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR lgammaf (), +.BR lgammal (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.BR lgamma_r (), +.BR lgammaf_r (), +.BR lgammal_r (): +.RS 4 +/* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.IR signgam : +.RS 4 +_XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +For the definition of the Gamma function, see +.BR tgamma (3). +.PP +The +.BR lgamma (), +.BR lgammaf (), +and +.BR lgammal () +functions return the natural logarithm of +the absolute value of the Gamma function. +The sign of the Gamma function is returned in the +external integer +.I signgam +declared in +.IR . +It is 1 when the Gamma function is positive or zero, \-1 +when it is negative. +.PP +Since using a constant location +.I signgam +is not thread-safe, the functions +.BR lgamma_r (), +.BR lgammaf_r (), +and +.BR lgammal_r () +have been introduced; they return the sign via the argument +.IR signp . +.SH RETURN VALUE +On success, these functions return the natural logarithm of Gamma(x). +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is 1 or 2, +0 is returned. +.PP +If +.I x +is positive infinity or negative infinity, +positive infinity is returned. +.PP +If +.I x +is a nonpositive integer, +a pole error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.PP +If the result overflows, +a range error occurs, +.\" e.g., lgamma(DBL_MAX) +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Pole error: \fIx\fP is a nonpositive integer +.I errno +is set to +.BR ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.\" glibc (as at 2.8) also supports an inexact +.\" exception for various cases. +.SH CONFORMING TO +The +.BR lgamma () +functions are specified in C99, POSIX.1-2001, and POSIX.1-2008. +.I signgam +is specified in POSIX.1-2001 and POSIX.1-2008, but not in C99. +The +.BR lgamma_r () +functions are nonstandard, but present on several other systems. +.SH BUGS +In glibc 2.9 and earlier, +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6777 +when a pole error occurs, +.I errno +is set to +.BR EDOM ; +instead of the POSIX-mandated +.BR ERANGE . +Since version 2.10, glibc does the right thing. +.SH SEE ALSO +.BR tgamma (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/lgamma_r.3 b/man3/lgamma_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man3/lgamma_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lgammaf.3 b/man3/lgammaf.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man3/lgammaf.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lgammaf_r.3 b/man3/lgammaf_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man3/lgammaf_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lgammal.3 b/man3/lgammal.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man3/lgammal.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lgammal_r.3 b/man3/lgammal_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man3/lgammal_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/lio_listio.3 b/man3/lio_listio.3 new file mode 100644 index 0000000..18b1910 --- /dev/null +++ b/man3/lio_listio.3 @@ -0,0 +1,249 @@ +.\" Copyright (C) 2010, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH LIO_LISTIO 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +lio_listio \- initiate a list of I/O requests +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "int lio_listio(int " mode ", struct aiocb *const " aiocb_list [], +.BI " int " nitems ", struct sigevent *" sevp ); +.PP +Link with \fI\-lrt\fP. +.fi +.SH DESCRIPTION +The +.BR lio_listio () +function initiates the list of I/O operations described by the array +.IR aiocb_list . +.PP +The +.I mode +operation has one of the following values: +.TP 12 +.B LIO_WAIT +The call blocks until all operations are complete. +The +.I sevp +argument is ignored. +.TP +.B LIO_NOWAIT +The I/O operations are queued for processing and the call returns immediately. +When all of the I/O operations complete, asynchronous notification occurs, +as specified by the +.IR sevp +argument; see +.BR sigevent (7) +for details. +If +.IR sevp +is NULL, no asynchronous notification occurs. +.PP +The +.I aiocb_list +argument is an array of pointers to +.I aiocb +structures that describe I/O operations. +These operations are executed in an unspecified order. +The +.I nitems +argument specifies the size of the array +.IR aiocb_list . +null pointers in +.I aiocb_list +are ignored. +.PP +In each control block in +.IR aiocb_list , +the +.I aio_lio_opcode +field specifies the I/O operation to be initiated, as follows: +.TP 10 +.BR LIO_READ +Initiate a read operation. +The operation is queued as for a call to +.BR aio_read (3) +specifying this control block. +.TP +.BR LIO_WRITE +Initiate a write operation. +The operation is queued as for a call to +.BR aio_write (3) +specifying this control block. +.TP +.BR LIO_NOP +Ignore this control block. +.PP +The remaining fields in each control block have the same meanings as for +.BR aio_read (3) +and +.BR aio_write (3). +The +.I aio_sigevent +fields of each control block can be used to specify notifications +for the individual I/O operations (see +.BR sigevent (7)). +.SH RETURN VALUE +If +.I mode +is +.BR LIO_NOWAIT , +.BR lio_listio () +returns 0 if all I/O operations are successfully queued. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.PP +If +.I mode +is +.BR LIO_WAIT , +.BR lio_listio () +returns 0 when all of the I/O operations have completed successfully. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.PP +The return status from +.BR lio_listio () +provides information only about the call itself, +not about the individual I/O operations. +One or more of the I/O operations may fail, +but this does not prevent other operations completing. +The status of individual I/O operations in +.IR aiocb_list +can be determined using +.BR aio_error (3). +When an operation has completed, +its return status can be obtained using +.BR aio_return (3). +Individual I/O operations can fail for the reasons described in +.BR aio_read (3) +and +.BR aio_write (3). +.SH ERRORS +The +.BR lio_listio () +function may fail for the following reasons: +.TP +.B EAGAIN +Out of resources. +.TP +.B EAGAIN +.\" Doesn't happen in glibc(?) +The number of I/O operations specified by +.I nitems +would cause the limit +.BR AIO_MAX +to be exceeded. +.TP +.B EINTR +.I mode +was +.BR LIO_WAIT +and a signal +was caught before all I/O operations completed; see +.BR signal (7). +(This may even be one of the signals used for +asynchronous I/O completion notification.) +.TP +.B EINVAL +.I mode +is invalid, or +.\" Doesn't happen in glibc(?) +.I nitems +exceeds the limit +.BR AIO_LISTIO_MAX . +.TP +.B EIO +One of more of the operations specified by +.IR aiocb_list +failed. +.\" e.g., ioa_reqprio or aio_lio_opcode was invalid +The application can check the status of each operation using +.BR aio_return (3). +.PP +If +.BR lio_listio () +fails with the error +.BR EAGAIN , +.BR EINTR , +or +.BR EIO , +then some of the operations in +.IR aiocb_list +may have been initiated. +If +.BR lio_listio () +fails for any other reason, +then none of the I/O operations has been initiated. +.SH VERSIONS +The +.BR lio_listio () +function is available since glibc 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR lio_listio () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +It is a good idea to zero out the control blocks before use. +The control blocks must not be changed while the I/O operations +are in progress. +The buffer areas being read into or written from +.\" or the control block of the operation +must not be accessed during the operations or undefined results may occur. +The memory areas involved must remain valid. +.PP +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR aio (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/llabs.3 b/man3/llabs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man3/llabs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man3/lldiv.3 b/man3/lldiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man3/lldiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man3/llrint.3 b/man3/llrint.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man3/llrint.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/llrintf.3 b/man3/llrintf.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man3/llrintf.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/llrintl.3 b/man3/llrintl.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man3/llrintl.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/llround.3 b/man3/llround.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man3/llround.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/llroundf.3 b/man3/llroundf.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man3/llroundf.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/llroundl.3 b/man3/llroundl.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man3/llroundl.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/localeconv.3 b/man3/localeconv.3 new file mode 100644 index 0000000..44fd8dc --- /dev/null +++ b/man3/localeconv.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 19:01:20 1993 by Rik Faith (faith@cs.unc.edu) +.TH LOCALECONV 3 2015-03-02 "GNU" "Linux Programmer's Manual" +.SH NAME +localeconv \- get numeric formatting information +.SH SYNOPSIS +.nf +.B #include +.PP +.B struct lconv *localeconv(void); +.fi +.SH DESCRIPTION +The +.BR localeconv () +function returns a pointer to a +.I struct lconv +for the current locale. +This structure is shown in +.BR locale (7), +and contains all values associated with the locale categories +.B LC_NUMERIC +and +.BR LC_MONETARY . +Programs may also use the functions +.BR printf (3) +and +.BR strfmon (3), +which behave according to the actual locale in use. +.SH RETURN VALUE +The +.BR localeconv () +function returns a pointer to a filled in +.IR "struct lconv" . +This structure may be (in glibc, +.IR is ) +statically allocated, and may be overwritten by subsequent calls. +According to POSIX, +the caller should not modify the contents of this structure. +The +.BR localeconv () +function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR localeconv () +T} Thread safety MT-Unsafe race:localeconv locale +.TE +.SH CONFORMING TO +C89, C99. +.SH BUGS +The +.BR printf (3) +family of functions may or may not honor the current locale. +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR isalpha (3), +.BR nl_langinfo (3), +.BR setlocale (3), +.BR strcoll (3), +.BR strftime (3), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/localtime.3 b/man3/localtime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man3/localtime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/localtime_r.3 b/man3/localtime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man3/localtime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/lockf.3 b/man3/lockf.3 new file mode 100644 index 0000000..722aa1f --- /dev/null +++ b/man3/lockf.3 @@ -0,0 +1,193 @@ +.\" Copyright 1997 Nicolás Lichtmaier +.\" Created Thu Aug 7 00:44:00 ART 1997 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Added section stuff, aeb, 2002-04-22. +.\" Corrected include file, drepper, 2003-06-15. +.\" +.TH LOCKF 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +lockf \- apply, test or remove a POSIX lock on an open file +.SH SYNOPSIS +.B #include +.PP +.BI "int lockf(int " fd ", int " cmd ", off_t " len ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR lockf (): +.ad l +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +Apply, test or remove a POSIX lock on a section of an open file. +The file is specified by +.IR fd , +a file descriptor open for writing, the action by +.IR cmd , +and the section consists of byte positions +.IR pos .. pos + len \-1 +if +.I len +is positive, and +.IR pos \- len .. pos \-1 +if +.I len +is negative, where +.I pos +is the current file position, and if +.I len +is zero, the section extends from the current file position to +infinity, encompassing the present and future end-of-file positions. +In all cases, the section may extend past current end-of-file. +.PP +On Linux, +.BR lockf () +is just an interface on top of +.BR fcntl (2) +locking. +Many other systems implement +.BR lockf () +in this way, but note that POSIX.1 leaves the relationship between +.BR lockf () +and +.BR fcntl (2) +locks unspecified. +A portable application should probably avoid mixing calls +to these interfaces. +.PP +Valid operations are given below: +.TP +.B F_LOCK +Set an exclusive lock on the specified section of the file. +If (part of) this section is already locked, the call +blocks until the previous lock is released. +If this section overlaps an earlier locked section, +both are merged. +File locks are released as soon as the process holding the locks +closes some file descriptor for the file. +A child process does not inherit these locks. +.TP +.B F_TLOCK +Same as +.B F_LOCK +but the call never blocks and returns an error instead if the file is +already locked. +.TP +.B F_ULOCK +Unlock the indicated section of the file. +This may cause a locked section to be split into two locked sections. +.TP +.B F_TEST +Test the lock: return 0 if the specified section +is unlocked or locked by this process; return \-1, set +.I errno +to +.B EAGAIN +.RB ( EACCES +on some other systems), +if another process holds a lock. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.BR EACCES " or " EAGAIN +The file is locked and +.B F_TLOCK +or +.B F_TEST +was specified, or the operation is prohibited because the file has +been memory-mapped by another process. +.TP +.B EBADF +.I fd +is not an open file descriptor; or +.I cmd +is +.B F_LOCK +or +.BR F_TLOCK +and +.I fd +is not a writable file descriptor. +.TP +.B EDEADLK +The command was +.B F_LOCK +and this lock operation would cause a deadlock. +.TP +.B EINVAL +An invalid operation was specified in +.IR cmd . +.TP +.B ENOLCK +Too many segment locks open, lock table is full. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR lockf () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +.SH SEE ALSO +.BR fcntl (2), +.BR flock (2) +.PP +.I locks.txt +and +.I mandatory-locking.txt +in the Linux kernel source directory +.IR Documentation/filesystems +(on older kernels, these files are directly under the +.I Documentation +directory, and +.I mandatory-locking.txt +is called +.IR mandatory.txt ) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/log.3 b/man3/log.3 new file mode 100644 index 0000000..e2221eb --- /dev/null +++ b/man3/log.3 @@ -0,0 +1,165 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH LOG 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +log, logf, logl \- natural logarithmic function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double log(double " x ); +.BI "float logf(float " x ); +.BI "long double logl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR logf (), +.BR logl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the natural logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the natural logarithm of +.IR x . +.PP +If +.I x +is a NaN, +a NaN is returned. +.PP +If +.I x +is 1, the result is +0. +.PP +If +.I x +is positive infinity, +positive infinity is returned. +.PP +If +.I x +is zero, +then a pole error occurs, and the functions return +.RB - HUGE_VAL , +.RB - HUGE_VALF , +or +.RB - HUGE_VALL , +respectively. +.PP +If +.I x +is negative (including negative infinity), then +a domain error occurs, and a NaN (not a number) is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is negative +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is zero +.I errno +is set to +.BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR log (), +.BR logf (), +.BR logl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +In glibc 2.5 and earlier, +taking the +.BR log () +of a NaN produces a bogus invalid floating-point +.RB ( FE_INVALID ) +exception. +.SH SEE ALSO +.BR cbrt (3), +.BR clog (3), +.BR log10 (3), +.BR log1p (3), +.BR log2 (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/log10.3 b/man3/log10.3 new file mode 100644 index 0000000..efa442f --- /dev/null +++ b/man3/log10.3 @@ -0,0 +1,119 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH LOG10 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +log10, log10f, log10l \- base-10 logarithmic function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double log10(double " x ); +.BI "float log10f(float " x ); +.BI "long double log10l(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR log10f (), +.BR log10l (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the base 10 logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the base 10 logarithm of +.IR x . +.PP +For special cases, including where +.I x +is 0, 1, negative, infinity, or NaN, see +.BR log (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +For a discussion of the errors that can occur for these functions, see +.BR log (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR log10 (), +.BR log10f (), +.BR log10l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR clog10 (3), +.BR exp10 (3), +.BR log (3), +.BR log2 (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/log10f.3 b/man3/log10f.3 new file mode 100644 index 0000000..dfa5796 --- /dev/null +++ b/man3/log10f.3 @@ -0,0 +1 @@ +.so man3/log10.3 diff --git a/man3/log10l.3 b/man3/log10l.3 new file mode 100644 index 0000000..dfa5796 --- /dev/null +++ b/man3/log10l.3 @@ -0,0 +1 @@ +.so man3/log10.3 diff --git a/man3/log1p.3 b/man3/log1p.3 new file mode 100644 index 0000000..ea76b2d --- /dev/null +++ b/man3/log1p.3 @@ -0,0 +1,175 @@ +.\" Copyright 1995 Jim Van Zandt +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH LOG1P 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +log1p, log1pf, log1pl \- logarithm of 1 plus argument +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double log1p(double " x ); +.BI "float log1pf(float " x ); +.BI "long double log1pl(long double " x ); +.PP +.fi +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR log1p (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR log1pf (), +.BR log1pl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return a value equivalent to +.PP +.nf + log (1 + \fIx\fP) +.fi +.PP +The result is computed in a way +that is accurate even if the value of +.I x +is near zero. +.SH RETURN VALUE +On success, these functions return the natural logarithm of +.IR "(1\ +\ x)" . +.PP +If +.I x +is a NaN, +a NaN is returned. +.PP +If +.I x +is positive infinity, positive infinity is returned. +.PP +If +.I x +is \-1, a pole error occurs, +and the functions return +.RB - HUGE_VAL , +.RB - HUGE_VALF , +or +.RB - HUGE_VALL , +respectively. +.PP +If +.I x +is less than \-1 (including negative infinity), +a domain error occurs, +and a NaN (not a number) is returned. +.\" POSIX.1 specifies a possible range error if x is subnormal +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is less than \-1 +.I errno +is set to +.BR EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is \-1 +.I errno +is set to +.BR ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR log1p (), +.BR log1pf (), +.BR log1pl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.\" BSD +.SH BUGS +Before version 2.22, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6792 +.I errno +to +.B EDOM +when a domain error occurred. +.PP +Before version 2.22, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6792 +.I errno +to +.B ERANGE +when a range error occurred. +.SH SEE ALSO +.BR exp (3), +.BR expm1 (3), +.BR log (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/log1pf.3 b/man3/log1pf.3 new file mode 100644 index 0000000..a4dec80 --- /dev/null +++ b/man3/log1pf.3 @@ -0,0 +1 @@ +.so man3/log1p.3 diff --git a/man3/log1pl.3 b/man3/log1pl.3 new file mode 100644 index 0000000..a4dec80 --- /dev/null +++ b/man3/log1pl.3 @@ -0,0 +1 @@ +.so man3/log1p.3 diff --git a/man3/log2.3 b/man3/log2.3 new file mode 100644 index 0000000..5528548 --- /dev/null +++ b/man3/log2.3 @@ -0,0 +1,119 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH LOG2 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +log2, log2f, log2l \- base-2 logarithmic function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double log2(double " x ); +.BI "float log2f(float " x ); +.BI "long double log2l(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR log2 (), +.BR log2f (), +.BR log2l (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad b +.SH DESCRIPTION +These functions return the base 2 logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the base 2 logarithm of +.IR x . +.PP +For special cases, including where +.I x +is 0, 1, negative, infinity, or NaN, see +.BR log (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +For a discussion of the errors that can occur for these functions, see +.BR log (3). +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR log2 (), +.BR log2f (), +.BR log2l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cbrt (3), +.BR clog2 (3), +.BR log (3), +.BR log10 (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/log2f.3 b/man3/log2f.3 new file mode 100644 index 0000000..23aeb4a --- /dev/null +++ b/man3/log2f.3 @@ -0,0 +1 @@ +.so man3/log2.3 diff --git a/man3/log2l.3 b/man3/log2l.3 new file mode 100644 index 0000000..23aeb4a --- /dev/null +++ b/man3/log2l.3 @@ -0,0 +1 @@ +.so man3/log2.3 diff --git a/man3/logb.3 b/man3/logb.3 new file mode 100644 index 0000000..6a5581c --- /dev/null +++ b/man3/logb.3 @@ -0,0 +1,167 @@ +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Inspired by a page by Walter Harms created 2002-08-10 +.\" +.TH LOGB 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +logb, logbf, logbl \- get exponent of a floating-point value +.SH SYNOPSIS +.B #include +.PP +.BI "double logb(double " x ); +.br +.BI "float logbf(float " x ); +.br +.BI "long double logbl(long double " x ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR logb (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR logbf (), +.BR logbl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions extract the exponent from the +internal floating-point representation of +.I x +and return it as a floating-point value. +The integer constant +.BR FLT_RADIX , +defined in +.IR , +indicates the radix used for the system's floating-point representation. +If +.B FLT_RADIX +is 2, +.BI logb( x ) +is equal to +.BI floor(log2( x ))\fR, +except that it is probably faster. +.PP +If +.I x +is subnormal, +.BR logb () +returns the exponent +.I x +would have if it were normalized. +.SH RETURN VALUE +On success, these functions return the exponent of +.IR x . +.PP +If +.I x +is a NaN, +a NaN is returned. +.PP +If +.I x +is zero, then a pole error occurs, and the functions return +.RB - HUGE_VAL , +.RB - HUGE_VALF , +or +.RB - HUGE_VALL , +respectively. +.PP +If +.I x +is negative infinity or positive infinity, then +positive infinity is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Pole error: \fIx\fP is 0 +.\" .I errno +.\" is set to +.\" .BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" log(), log2(), log10() do set errno +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6793 +.\" +.\" .SH HISTORY +.\" The +.\" .BR logb () +.\" function occurs in 4.3BSD. +.\" see IEEE.3 in the 4.3BSD manual +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR logb (), +.BR logbf (), +.BR logbl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR ilogb (3), +.BR log (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/logbf.3 b/man3/logbf.3 new file mode 100644 index 0000000..4a70936 --- /dev/null +++ b/man3/logbf.3 @@ -0,0 +1 @@ +.so man3/logb.3 diff --git a/man3/logbl.3 b/man3/logbl.3 new file mode 100644 index 0000000..4a70936 --- /dev/null +++ b/man3/logbl.3 @@ -0,0 +1 @@ +.so man3/logb.3 diff --git a/man3/logf.3 b/man3/logf.3 new file mode 100644 index 0000000..7807e76 --- /dev/null +++ b/man3/logf.3 @@ -0,0 +1 @@ +.so man3/log.3 diff --git a/man3/login.3 b/man3/login.3 new file mode 100644 index 0000000..4bf37c9 --- /dev/null +++ b/man3/login.3 @@ -0,0 +1,176 @@ +.\" Derived from text written by Martin Schulze (or taken from glibc.info) +.\" and text written by Paul Thompson - both copyright 2002. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH LOGIN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +login, logout \- write utmp and wtmp entries +.SH SYNOPSIS +.B #include +.PP +.BI "void login(const struct utmp *" ut ); +.PP +.BI "int logout(const char *" ut_line ); +.PP +Link with \fI\-lutil\fP. +.SH DESCRIPTION +The utmp file records who is currently using the system. +The wtmp file records all logins and logouts. +See +.BR utmp (5). +.PP +The function +.BR login () +takes the supplied +.IR "struct utmp" , +.IR ut , +and writes it to both the utmp and the wtmp file. +.PP +The function +.BR logout () +clears the entry in the utmp file again. +.SS GNU details +More precisely, +.BR login () +takes the argument +.I ut +struct, fills the field +.I ut\->ut_type +(if there is such a field) with the value +.BR USER_PROCESS , +and fills the field +.I ut\->ut_pid +(if there is such a field) with the process ID of the calling process. +Then it tries to fill the field +.IR ut\->ut_line . +It takes the first of +.IR stdin , +.IR stdout , +.I stderr +that is a terminal, and +stores the corresponding pathname minus a possible leading +.I /dev/ +into this field, and then writes the struct to the utmp file. +On the other hand, +if no terminal name was found, this field is filled with "???" +and the struct is not written to the utmp file. +After this, the struct is written to the wtmp file. +.PP +The +.BR logout () +function searches the utmp file for an entry matching the +.I ut_line +argument. +If a record is found, it is updated by zeroing out the +.I ut_name +and +.I ut_host +fields, updating the +.I ut_tv +timestamp field and setting +.I ut_type +(if there is such a field) to +.BR DEAD_PROCESS . +.SH RETURN VALUE +The +.BR logout () +function returns 1 if the entry was successfully written to the +database, or 0 if an error occurred. +.SH FILES +.TP +.I /var/run/utmp +user accounting database, configured through +.B _PATH_UTMP +in +.I +.TP +.I /var/log/wtmp +user accounting log file, configured through +.B _PATH_WTMP +in +.I +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw20 +l l l. +Interface Attribute Value +T{ +.BR login (), +.br +.BR logout () +T} Thread safety T{ +MT-Unsafe race:utent +.br +sig:ALRM timer +T} +.TE +.sp 1 +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR login () +and +.BR logout () +calls those functions, +so we use race:utent to remind users. +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs. +.SH NOTES +Note that the +member +.I ut_user +of +.I struct utmp +is called +.I ut_name +in BSD. +Therefore, +.I ut_name +is defined as an alias for +.I ut_user +in +.IR . +.SH SEE ALSO +.BR getutent (3), +.BR utmp (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/login_tty.3 b/man3/login_tty.3 new file mode 100644 index 0000000..fb4952d --- /dev/null +++ b/man3/login_tty.3 @@ -0,0 +1 @@ +.so man3/openpty.3 diff --git a/man3/logl.3 b/man3/logl.3 new file mode 100644 index 0000000..7807e76 --- /dev/null +++ b/man3/logl.3 @@ -0,0 +1 @@ +.so man3/log.3 diff --git a/man3/logout.3 b/man3/logout.3 new file mode 100644 index 0000000..a1ee672 --- /dev/null +++ b/man3/logout.3 @@ -0,0 +1 @@ +.so man3/login.3 diff --git a/man3/logwtmp.3 b/man3/logwtmp.3 new file mode 100644 index 0000000..0dc4dea --- /dev/null +++ b/man3/logwtmp.3 @@ -0,0 +1 @@ +.so man3/updwtmp.3 diff --git a/man3/longjmp.3 b/man3/longjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man3/longjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man3/lrand48.3 b/man3/lrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man3/lrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/lrand48_r.3 b/man3/lrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man3/lrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/lrint.3 b/man3/lrint.3 new file mode 100644 index 0000000..6b1c449 --- /dev/null +++ b/man3/lrint.3 @@ -0,0 +1,137 @@ +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH LRINT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +lrint, lrintf, lrintl, llrint, llrintf, llrintl \- round to nearest integer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long int lrint(double " x ); +.BI "long int lrintf(float " x ); +.BI "long int lrintl(long double " x ); +.PP +.BI "long long int llrint(double " x ); +.BI "long long int llrintf(float " x ); +.BI "long long int llrintl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +All functions shown above: +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions round their argument to the nearest integer value, +using the current rounding direction (see +.BR fesetround (3)). +.PP +Note that unlike the +.BR rint (3) +family of functions, +the return type of these functions differs from +that of their arguments. +.SH RETURN VALUE +These functions return the rounded integer value. +.PP +If +.I x +is a NaN or an infinity, +or the rounded value is too large to be stored in a +.I long +.RI ( "long long" +in the case of the +.B ll* +functions), +then a domain error occurs, and the return value is unspecified. +.\" The return value is -(LONG_MAX - 1) or -(LLONG_MAX -1) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6798 +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR lrint (), +.BR lrintf (), +.BR lrintl (), +.br +.BR llrint (), +.BR llrintf (), +.BR llrintl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lround (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/lrintf.3 b/man3/lrintf.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man3/lrintf.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/lrintl.3 b/man3/lrintl.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man3/lrintl.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man3/lround.3 b/man3/lround.3 new file mode 100644 index 0000000..8fde408 --- /dev/null +++ b/man3/lround.3 @@ -0,0 +1,140 @@ +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH LROUND 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +lround, lroundf, lroundl, llround, llroundf, llroundl \- round to +nearest integer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long int lround(double " x ); +.BI "long int lroundf(float " x ); +.BI "long int lroundl(long double " x ); +.PP +.BI "long long int llround(double " x ); +.BI "long long int llroundf(float " x ); +.BI "long long int llroundl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +All functions shown above: +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions round their argument to the nearest integer value, +rounding halfway cases away from zero, +regardless of the current rounding direction (see +.BR fenv (3)). +.PP +Note that unlike the +.BR round (3) +and +.BR ceil (3), +functions, the return type of these functions differs from +that of their arguments. +.SH RETURN VALUE +These functions return the rounded integer value. +.PP +If +.I x +is a NaN or an infinity, +or the rounded value is too large to be stored in a +.I long +.RI ( "long long" +in the case of the +.B ll* +functions), +then a domain error occurs, and the return value is unspecified. +.\" The return value is -(LONG_MAX - 1) or -(LLONG_MAX -1) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6797 +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw33 lb lb +l l l. +Interface Attribute Value +T{ +.BR lround (), +.BR lroundf (), +.BR lroundl (), +.br +.BR llround (), +.BR llroundf (), +.BR llroundl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/lroundf.3 b/man3/lroundf.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man3/lroundf.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/lroundl.3 b/man3/lroundl.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man3/lroundl.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man3/lsearch.3 b/man3/lsearch.3 new file mode 100644 index 0000000..a22eb1b --- /dev/null +++ b/man3/lsearch.3 @@ -0,0 +1,111 @@ +.\" Copyright 1995 Jim Van Zandt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Corrected prototype and include, aeb, 990927 +.TH LSEARCH 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +lfind, lsearch \- linear search of an array +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *lfind(const void *" key ", const void *" base ", size_t *" nmemb , +.BI " size_t " size ", int(*" compar ")(const void *, const void *));" +.PP +.BI "void *lsearch(const void *" key ", void *" base ", size_t *" nmemb , +.BI " size_t " size ", int(*" compar ")(const void *, const void *));" +.fi +.SH DESCRIPTION +.BR lfind () +and +.BR lsearch () +perform a linear search for +.I key +in the array +.IR base +which has +.I *nmemb +elements of +.I size +bytes each. +The comparison function referenced by +.I compar +is expected to have two arguments which point to the +.I key +object and to an array member, in that order, and which +returns zero if the +.I key +object matches the array member, and +nonzero otherwise. +.PP +If +.BR lsearch () +does not find a matching element, then the +.I key +object is inserted at the end of the table, and +.I *nmemb +is +incremented. +In particular, one should know that a matching element +exists, or that more room is available. +.SH RETURN VALUE +.BR lfind () +returns a pointer to a matching member of the array, or +NULL if no match is found. +.BR lsearch () +returns a pointer to +a matching member of the array, or to the newly added member if no +match is found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw18 lb lb +l l l. +Interface Attribute Value +T{ +.BR lfind (), +.BR lsearch () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +Present in libc since libc-4.6.27. +.SH BUGS +The naming is unfortunate. +.SH SEE ALSO +.BR bsearch (3), +.BR hsearch (3), +.BR tsearch (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/lseek64.3 b/man3/lseek64.3 new file mode 100644 index 0000000..9f201cc --- /dev/null +++ b/man3/lseek64.3 @@ -0,0 +1,187 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH LSEEK64 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +lseek64 \- reposition 64-bit read/write file offset +.SH SYNOPSIS +.BR "#define _LARGEFILE64_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.br +.B #include +.PP +.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); +.SH DESCRIPTION +The +.BR lseek (2) +family of functions reposition the offset of the open file associated +with the file descriptor +.I fd +to +.I offset +bytes relative to the start, current position, or end of the file, +when +.I whence +has the value +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +respectively. +.PP +For more details, return value, and errors, see +.BR lseek (2). +.PP +Four interfaces are available: +.BR lseek (2), +.BR lseek64 (), +.BR llseek (2), +and +.BR _llseek (2). +.SS lseek() +Prototype: +.PP +.in +4n +.EX +.BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); +.EE +.in +.PP +.BR lseek (2) +uses the type +.IR off_t . +This is a 32-bit signed type on 32-bit architectures, unless one +compiles with +.PP +.in +4n +.EX +#define _FILE_OFFSET_BITS 64 +.EE +.in +.PP +in which case it is a 64-bit signed type. +.SS lseek64() +Prototype: +.PP +.in +4n +.EX +.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); +.EE +.in +.PP +The library routine +.BR lseek64 () +uses a 64-bit type even when +.I off_t +is a 32-bit type. +Its prototype (and the type +.IR off64_t ) +is available only when one compiles with +.PP +.in +4n +.EX +#define _LARGEFILE64_SOURCE +.EE +.in +.PP +The function +.BR lseek64 () +.\" in glibc 2.0.94, not in 2.0.6 +is available since glibc 2.1, and is defined to be an alias for +.BR llseek (). +.SS llseek() +Prototype: +.PP +.in +4n +.EX +.BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence ); +.EE +.in +.PP +The type +.I loff_t +is a 64-bit signed type. +The library routine +.BR llseek () +.\" in libc 5.0.9, not in 4.7.6 +is available in glibc and works without special defines. +However, the glibc headers do not provide a prototype. +Users should add +the above prototype, or something equivalent, to their own source. +When users complained about data loss caused by a miscompilation of +.BR e2fsck (8), +glibc 2.1.3 added the link-time warning +.PP +.in +4n +"the \`llseek\' function may be dangerous; use \`lseek64\' instead." +.in +.PP +This makes this function unusable if one desires a warning-free +compilation. +.SS _llseek() +On 32-bit architectures, +this is the system call that is used to implement all of the above functions. +The prototype is: +.PP +.in +4n +.EX +.BI "int _llseek(int " fd ", off_t " offset_hi ", off_t " offset_lo , +.BI " loff_t *" result ", int " whence ); +.EE +.in +.PP +For more details, see +.BR llseek (2). +.PP +64-bit systems don't need an +.BR _llseek () +system call. +Instead, they have an +.BR lseek (2) +system call that supports 64-bit file offsets. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR lseek64 () +T} Thread safety MT-Safe +.TE +.SH SEE ALSO +.BR llseek (2), +.BR lseek (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/lutimes.3 b/man3/lutimes.3 new file mode 100644 index 0000000..3145980 --- /dev/null +++ b/man3/lutimes.3 @@ -0,0 +1 @@ +.so man3/futimes.3 diff --git a/man3/major.3 b/man3/major.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man3/major.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man3/makecontext.3 b/man3/makecontext.3 new file mode 100644 index 0000000..1b74c29 --- /dev/null +++ b/man3/makecontext.3 @@ -0,0 +1,249 @@ +\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2006-08-02, mtk, Added example program +.\" +.TH MAKECONTEXT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +makecontext, swapcontext \- manipulate user context +.SH SYNOPSIS +.B #include +.PP +.BI "void makecontext(ucontext_t *" ucp ", void (*" func )(), +.BI "int " argc ", ...);" +.PP +.BI "int swapcontext(ucontext_t *" oucp ", const ucontext_t *" ucp ); +.SH DESCRIPTION +In a System V-like environment, one has the type \fIucontext_t\fP defined in +.I +and the four functions +.BR getcontext (3), +.BR setcontext (3), +.BR makecontext () +and +.BR swapcontext () +that allow user-level context switching +between multiple threads of control within a process. +.PP +For the type and the first two functions, see +.BR getcontext (3). +.PP +The +.BR makecontext () +function modifies the context pointed to +by \fIucp\fP (which was obtained from a call to +.BR getcontext (3)). +Before invoking +.BR makecontext (), +the caller must allocate a new stack +for this context and assign its address to \fIucp\->uc_stack\fP, +and define a successor context and +assign its address to \fIucp\->uc_link\fP. +.PP +When this context is later activated (using +.BR setcontext (3) +or +.BR swapcontext ()) +the function \fIfunc\fP is called, +and passed the series of integer +.RI ( int ) +arguments that follow +.IR argc ; +the caller must specify the number of these arguments in +.IR argc . +When this function returns, the successor context is activated. +If the successor context pointer is NULL, the thread exits. +.PP +The +.BR swapcontext () +function saves the current context in +the structure pointed to by \fIoucp\fP, and then activates the +context pointed to by \fIucp\fP. +.SH RETURN VALUE +When successful, +.BR swapcontext () +does not return. +(But we may return later, in case \fIoucp\fP is +activated, in which case it looks like +.BR swapcontext () +returns 0.) +On error, +.BR swapcontext () +returns \-1 and +sets \fIerrno\fP appropriately. +.SH ERRORS +.TP +.B ENOMEM +Insufficient stack space left. +.SH VERSIONS +.BR makecontext () +and +.BR swapcontext () +are provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR makecontext () +T} Thread safety MT-Safe race:ucp +T{ +.BR swapcontext () +T} Thread safety MT-Safe race:oucp race:ucp +.TE +.SH CONFORMING TO +SUSv2, POSIX.1-2001. +POSIX.1-2008 removes the specifications of +.BR makecontext () +and +.BR swapcontext (), +citing portability issues, and +recommending that applications be rewritten to use POSIX threads instead. +.SH NOTES +The interpretation of \fIucp\->uc_stack\fP is just as in +.BR sigaltstack (2), +namely, this struct contains the start and length of a memory area +to be used as the stack, regardless of the direction of growth of +the stack. +Thus, it is not necessary for the user program to +worry about this direction. +.PP +On architectures where +.I int +and pointer types are the same size +(e.g., x86-32, where both types are 32 bits), +you may be able to get away with passing pointers as arguments to +.BR makecontext () +following +.IR argc . +However, doing this is not guaranteed to be portable, +is undefined according to the standards, +and won't work on architectures where pointers are larger than +.IR int s. +Nevertheless, starting with version 2.8, glibc makes some changes to +.BR makecontext (), +to permit this on some 64-bit architectures (e.g., x86-64). +.SH EXAMPLE +.PP +The example program below demonstrates the use of +.BR getcontext (3), +.BR makecontext (), +and +.BR swapcontext (). +Running the program produces the following output: +.PP +.in +4n +.EX +.RB "$" " ./a.out" +main: swapcontext(&uctx_main, &uctx_func2) +func2: started +func2: swapcontext(&uctx_func2, &uctx_func1) +func1: started +func1: swapcontext(&uctx_func1, &uctx_func2) +func2: returning +func1: returning +main: exiting +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include + +static ucontext_t uctx_main, uctx_func1, uctx_func2; + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +static void +func1(void) +{ + printf("func1: started\\n"); + printf("func1: swapcontext(&uctx_func1, &uctx_func2)\\n"); + if (swapcontext(&uctx_func1, &uctx_func2) == \-1) + handle_error("swapcontext"); + printf("func1: returning\\n"); +} + +static void +func2(void) +{ + printf("func2: started\\n"); + printf("func2: swapcontext(&uctx_func2, &uctx_func1)\\n"); + if (swapcontext(&uctx_func2, &uctx_func1) == \-1) + handle_error("swapcontext"); + printf("func2: returning\\n"); +} + +int +main(int argc, char *argv[]) +{ + char func1_stack[16384]; + char func2_stack[16384]; + + if (getcontext(&uctx_func1) == \-1) + handle_error("getcontext"); + uctx_func1.uc_stack.ss_sp = func1_stack; + uctx_func1.uc_stack.ss_size = sizeof(func1_stack); + uctx_func1.uc_link = &uctx_main; + makecontext(&uctx_func1, func1, 0); + + if (getcontext(&uctx_func2) == \-1) + handle_error("getcontext"); + uctx_func2.uc_stack.ss_sp = func2_stack; + uctx_func2.uc_stack.ss_size = sizeof(func2_stack); + /* Successor context is f1(), unless argc > 1 */ + uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1; + makecontext(&uctx_func2, func2, 0); + + printf("main: swapcontext(&uctx_main, &uctx_func2)\\n"); + if (swapcontext(&uctx_main, &uctx_func2) == \-1) + handle_error("swapcontext"); + + printf("main: exiting\\n"); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR sigaction (2), +.BR sigaltstack (2), +.BR sigprocmask (2), +.BR getcontext (3), +.BR sigsetjmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/makedev.3 b/man3/makedev.3 new file mode 100644 index 0000000..145f961 --- /dev/null +++ b/man3/makedev.3 @@ -0,0 +1,114 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MAKEDEV 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +makedev, major, minor \- manage a device number +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "dev_t makedev(unsigned int " maj ", unsigned int " min ); +.PP +.BI "unsigned int major(dev_t " dev ); +.BI "unsigned int minor(dev_t " dev ); +.fi +.SH DESCRIPTION +A device ID consists of two parts: +a major ID, identifying the class of the device, +and a minor ID, identifying a specific instance of a device in that class. +A device ID is represented using the type +.IR dev_t . +.PP +Given major and minor device IDs, +.BR makedev () +combines these to produce a device ID, returned as the function result. +This device ID can be given to +.BR mknod (2), +for example. +.PP +The +.BR major () +and +.BR minor () +functions perform the converse task: given a device ID, +they return, respectively, the major and minor components. +These macros can be useful to, for example, +decompose the device IDs in the structure returned by +.BR stat (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR makedev (), +.BR major (), +.BR minor () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The +.BR makedev (), +.BR major (), +and +.BR minor () +functions are not specified in POSIX.1, +but are present on many other systems. +.\" The BSDs, HP-UX, Solaris, AIX, Irix. +.\" The header location is inconsistent: +.\" Could be sys/mkdev.h, sys/sysmacros.h, or sys/types.h. +.SH NOTES +These interfaces are defined as macros. +Since glibc 2.3.3, +they have been aliases for three GNU-specific functions: +.BR gnu_dev_makedev (), +.BR gnu_dev_major (), +and +.BR gnu_dev_minor (). +The latter names are exported, but the traditional names are more portable. +.PP +The BSDs expose the definitions for these macros via +.IR . +glibc also exposes definitions for these macros from that +header file if suitable feature test macros are defined, +but this is deprecated since glibc 2.25 +.\" glibc commit dbab6577c6684c62bd2521c1c29dc25c3cac966f +and will be removed in the future. +.SH SEE ALSO +.BR mknod (2), +.BR stat (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mallinfo.3 b/man3/mallinfo.3 new file mode 100644 index 0000000..883139d --- /dev/null +++ b/man3/mallinfo.3 @@ -0,0 +1,320 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MALLINFO 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mallinfo \- obtain memory allocation information +.SH SYNOPSIS +.B #include +.PP +.B struct mallinfo mallinfo(void); +.SH DESCRIPTION +The +.BR mallinfo () +function returns a copy of a structure containing information about +memory allocations performed by +.BR malloc (3) +and related functions. +This structure is defined as follows: +.PP +.in +4n +.EX +struct mallinfo { + int arena; /* Non-mmapped space allocated (bytes) */ + int ordblks; /* Number of free chunks */ + int smblks; /* Number of free fastbin blocks */ + int hblks; /* Number of mmapped regions */ + int hblkhd; /* Space allocated in mmapped regions (bytes) */ + int usmblks; /* Maximum total allocated space (bytes) */ + int fsmblks; /* Space in freed fastbin blocks (bytes) */ + int uordblks; /* Total allocated space (bytes) */ + int fordblks; /* Total free space (bytes) */ + int keepcost; /* Top-most, releasable space (bytes) */ +}; +.EE +.in +.PP +The fields of the +.I mallinfo +structure contain the following information: +.TP 10 +.I arena +The total amount of memory allocated by means other than +.BR mmap (2) +(i.e., memory allocated on the heap). +This figure includes both in-use blocks and blocks on the free list. +.TP +.I ordblks +The number of ordinary (i.e., non-fastbin) free blocks. +.TP +.I smblks +The number of fastbin free blocks (see +.BR mallopt (3)). +.TP +.I hblks +The number of blocks currently allocated using +.BR mmap (2). +(See the discussion of +.B M_MMAP_THRESHOLD +in +.BR mallopt (3).) +.TP +.I hblkhd +The number of bytes in blocks currently allocated using +.BR mmap (2). +.TP +.I usmblks +The "highwater mark" for allocated space\(emthat is, +the maximum amount of space that was ever allocated. +This field is maintained only in nonthreading environments. +.TP +.I fsmblks +The total number of bytes in fastbin free blocks. +.TP +.I uordblks +The total number of bytes used by in-use allocations. +.TP +.I fordblks +The total number of bytes in free blocks. +.TP +.I keepcost +The total amount of releasable free space at the top +of the heap. +This is the maximum number of bytes that could ideally +(i.e., ignoring page alignment restrictions, and so on) be released by +.BR malloc_trim (3). +.\" .SH VERSIONS +.\" Available already in glibc 2.0, possibly earlier +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw28 +l l l. +Interface Attribute Value +T{ +.BR mallinfo () +T} Thread safety MT-Unsafe init const:mallopt +.TE +.sp 1 +.BR mallinfo () +would access some global internal objects. +If modify them with non-atomically, +may get inconsistent results. +The identifier +.I mallopt +in +.I const:mallopt +mean that +.BR mallopt () +would modify the global internal objects with atomics, that make sure +.BR mallinfo () +is safe enough, others modify with non-atomically maybe not. +.SH CONFORMING TO +This function is not specified by POSIX or the C standards. +A similar function exists on many System V derivatives, +and was specified in the SVID. +.SH BUGS +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208 +.\" See the 24 Aug 2011 mail by Paul Pluzhnikov: +.\" "[patch] Fix mallinfo() to accumulate results for all arenas" +.\" on libc-alpha@sourceware.org +.B Information is returned for only the main memory allocation area. +Allocations in other arenas are excluded. +See +.BR malloc_stats (3) +and +.BR malloc_info (3) +for alternatives that include information about other arenas. +.PP +The fields of the +.I mallinfo +structure are typed as +.IR int . +However, because some internal bookkeeping values may be of type +.IR long , +the reported values may wrap around zero and thus be inaccurate. +.SH EXAMPLE +The program below employs +.BR mallinfo () +to retrieve memory allocation statistics before and after +allocating and freeing some blocks of memory. +The statistics are displayed on standard output. +.PP +The first two command-line arguments specify the number and size of +blocks to be allocated with +.BR malloc (3). +.PP +The remaining three arguments specify which of the allocated blocks +should be freed with +.BR free (3). +These three arguments are optional, and specify (in order): +the step size to be used in the loop that frees blocks +(the default is 1, meaning free all blocks in the range); +the ordinal position of the first block to be freed +(default 0, meaning the first allocated block); +and a number one greater than the ordinal position +of the last block to be freed +(default is one greater than the maximum block number). +If these three arguments are omitted, +then the defaults cause all allocated blocks to be freed. +.PP +In the following example run of the program, +1000 allocations of 100 bytes are performed, +and then every second allocated block is freed: +.PP +.in +4n +.EX +$ \fB./a.out 1000 100 2\fP +============== Before allocating blocks ============== +Total non\-mmapped bytes (arena): 0 +# of free chunks (ordblks): 1 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 0 +Total free space (fordblks): 0 +Topmost releasable block (keepcost): 0 + +============== After allocating blocks ============== +Total non\-mmapped bytes (arena): 135168 +# of free chunks (ordblks): 1 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 104000 +Total free space (fordblks): 31168 +Topmost releasable block (keepcost): 31168 + +============== After freeing blocks ============== +Total non\-mmapped bytes (arena): 135168 +# of free chunks (ordblks): 501 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 52000 +Total free space (fordblks): 83168 +Topmost releasable block (keepcost): 31168 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include + +static void +display_mallinfo(void) +{ + struct mallinfo mi; + + mi = mallinfo(); + + printf("Total non\-mmapped bytes (arena): %d\\n", mi.arena); + printf("# of free chunks (ordblks): %d\\n", mi.ordblks); + printf("# of free fastbin blocks (smblks): %d\\n", mi.smblks); + printf("# of mapped regions (hblks): %d\\n", mi.hblks); + printf("Bytes in mapped regions (hblkhd): %d\\n", mi.hblkhd); + printf("Max. total allocated space (usmblks): %d\\n", mi.usmblks); + printf("Free bytes held in fastbins (fsmblks): %d\\n", mi.fsmblks); + printf("Total allocated space (uordblks): %d\\n", mi.uordblks); + printf("Total free space (fordblks): %d\\n", mi.fordblks); + printf("Topmost releasable block (keepcost): %d\\n", mi.keepcost); +} + +int +main(int argc, char *argv[]) +{ +#define MAX_ALLOCS 2000000 + char *alloc[MAX_ALLOCS]; + int numBlocks, j, freeBegin, freeEnd, freeStep; + size_t blockSize; + + if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) { + fprintf(stderr, "%s num\-blocks block\-size [free\-step " + "[start\-free [end\-free]]]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + numBlocks = atoi(argv[1]); + blockSize = atoi(argv[2]); + freeStep = (argc > 3) ? atoi(argv[3]) : 1; + freeBegin = (argc > 4) ? atoi(argv[4]) : 0; + freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks; + + printf("============== Before allocating blocks ==============\\n"); + display_mallinfo(); + + for (j = 0; j < numBlocks; j++) { + if (numBlocks >= MAX_ALLOCS) { + fprintf(stderr, "Too many allocations\\n"); + exit(EXIT_FAILURE); + } + + alloc[j] = malloc(blockSize); + if (alloc[j] == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + } + + printf("\\n============== After allocating blocks ==============\\n"); + display_mallinfo(); + + for (j = freeBegin; j < freeEnd; j += freeStep) + free(alloc[j]); + + printf("\\n============== After freeing blocks ==============\\n"); + display_mallinfo(); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR malloc (3), +.BR malloc_info (3), +.BR malloc_stats (3), +.BR malloc_trim (3), +.BR mallopt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/malloc.3 b/man3/malloc.3 new file mode 100644 index 0000000..e440ecf --- /dev/null +++ b/man3/malloc.3 @@ -0,0 +1,383 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu) +.\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701 +.\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de) +.\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap(). +.\" +.\" FIXME . Review http://austingroupbugs.net/view.php?id=374 +.\" to see what changes are required on this page. +.\" +.TH MALLOC 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +malloc, free, calloc, realloc \- allocate and free dynamic memory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *malloc(size_t " "size" ); +.BI "void free(void " "*ptr" ); +.BI "void *calloc(size_t " "nmemb" ", size_t " "size" ); +.BI "void *realloc(void " "*ptr" ", size_t " "size" ); +.BI "void *reallocarray(void " "*ptr" ", size_t " nmemb ", size_t " "size" ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR reallocarray (): +.br +.RS 4 +.ad l +_GNU_SOURCE +.RE +.ad +.SH DESCRIPTION +.PP +The +.BR malloc () +function allocates +.I size +bytes and returns a pointer to the allocated memory. +.IR "The memory is not initialized" . +If +.I size +is 0, then +.BR malloc () +returns either NULL, +.\" glibc does this: +or a unique pointer value that can later be successfully passed to +.BR free (). +.PP +The +.BR free () +function frees the memory space pointed to by +.IR ptr , +which must have been returned by a previous call to +.BR malloc (), +.BR calloc (), +or +.BR realloc (). +Otherwise, or if +.I free(ptr) +has already been called before, undefined behavior occurs. +If +.I ptr +is NULL, no operation is performed. +.PP +The +.BR calloc () +function allocates memory for an array of +.I nmemb +elements of +.I size +bytes each and returns a pointer to the allocated memory. +The memory is set to zero. +If +.I nmemb +or +.I size +is 0, then +.BR calloc () +returns either NULL, +.\" glibc does this: +or a unique pointer value that can later be successfully passed to +.BR free (). +.PP +The +.BR realloc () +function changes the size of the memory block pointed to by +.I ptr +to +.I size +bytes. +The contents will be unchanged in the range from the start of the region +up to the minimum of the old and new sizes. +If the new size is larger than the old size, the added memory will +.I not +be initialized. +If +.I ptr +is NULL, then the call is equivalent to +.IR malloc(size) , +for all values of +.IR size ; +if +.I size +is equal to zero, +and +.I ptr +is not NULL, then the call is equivalent to +.IR free(ptr) . +Unless +.I ptr +is NULL, it must have been returned by an earlier call to +.BR malloc (), +.BR calloc (), +or +.BR realloc (). +If the area pointed to was moved, a +.I free(ptr) +is done. +.PP +The +.BR reallocarray () +function changes the size of the memory block pointed to by +.I ptr +to be large enough for an array of +.I nmemb +elements, each of which is +.I size +bytes. +It is equivalent to the call +.PP +.in +4n + realloc(ptr, nmemb * size); +.in +.PP +However, unlike that +.BR realloc () +call, +.BR reallocarray () +fails safely in the case where the multiplication would overflow. +If such an overflow occurs, +.BR reallocarray () +returns NULL, sets +.I errno +to +.BR ENOMEM , +and leaves the original block of memory unchanged. +.SH RETURN VALUE +The +.BR malloc () +and +.BR calloc () +functions return a pointer to the allocated memory, +which is suitably aligned for any built-in type. +On error, these functions return NULL. +NULL may also be returned by a successful call to +.BR malloc () +with a +.I size +of zero, +or by a successful call to +.BR calloc () +with +.I nmemb +or +.I size +equal to zero. +.PP +The +.BR free () +function returns no value. +.PP +The +.BR realloc () +function returns a pointer to the newly allocated memory, which is suitably +aligned for any built-in type and may be different from +.IR ptr , +or NULL if the request fails. +If +.I size +was equal to 0, either NULL or a pointer suitable to be passed to +.BR free () +is returned. +If +.BR realloc () +fails, the original block is left untouched; it is not freed or moved. +.PP +On success, the +.BR reallocarray () +function returns a pointer to the newly allocated memory. +On failure, +it returns NULL and the original block of memory is left untouched. +.SH ERRORS +.BR calloc (), +.BR malloc (), +.BR realloc (), +and +.BR reallocarray () +can fail with the following error: +.TP +.B ENOMEM +Out of memory. +Possibly, the application hit the +.BR RLIMIT_AS +or +.BR RLIMIT_DATA +limit described in +.BR getrlimit (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR malloc (), +.BR free (), +.br +.BR calloc (), +.BR realloc () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR malloc (), +.BR free (), +.BR calloc (), +.BR realloc (): +POSIX.1-2001, POSIX.1-2008, C89, C99. +.PP +.BR reallocarray () +is a nonstandard extension that first appeared in OpenBSD 5.6 and FreeBSD 11.0. +.SH NOTES +By default, Linux follows an optimistic memory allocation strategy. +This means that when +.BR malloc () +returns non-NULL there is no guarantee that the memory really +is available. +In case it turns out that the system is out of memory, +one or more processes will be killed by the OOM killer. +For more information, see the description of +.IR /proc/sys/vm/overcommit_memory +and +.IR /proc/sys/vm/oom_adj +in +.BR proc (5), +and the Linux kernel source file +.IR Documentation/vm/overcommit-accounting . +.PP +Normally, +.BR malloc () +allocates memory from the heap, and adjusts the size of the heap +as required, using +.BR sbrk (2). +When allocating blocks of memory larger than +.B MMAP_THRESHOLD +bytes, the glibc +.BR malloc () +implementation allocates the memory as a private anonymous mapping using +.BR mmap (2). +.B MMAP_THRESHOLD +is 128\ kB by default, but is adjustable using +.BR mallopt (3). +Prior to Linux 4.7 +allocations performed using +.BR mmap (2) +were unaffected by the +.B RLIMIT_DATA +resource limit; +since Linux 4.7, this limit is also enforced for allocations performed using +.BR mmap (2). +.PP +To avoid corruption in multithreaded applications, +mutexes are used internally to protect the memory-management +data structures employed by these functions. +In a multithreaded application in which threads simultaneously +allocate and free memory, +there could be contention for these mutexes. +To scalably handle memory allocation in multithreaded applications, +glibc creates additional +.IR "memory allocation arenas" +if mutex contention is detected. +Each arena is a large region of memory that is internally allocated +by the system +(using +.BR brk (2) +or +.BR mmap (2)), +and managed with its own mutexes. +.PP +SUSv2 requires +.BR malloc (), +.BR calloc (), +and +.BR realloc () +to set +.I errno +to +.B ENOMEM +upon failure. +Glibc assumes that this is done +(and the glibc versions of these routines do this); if you +use a private malloc implementation that does not set +.IR errno , +then certain library routines may fail without having +a reason in +.IR errno . +.PP +Crashes in +.BR malloc (), +.BR calloc (), +.BR realloc (), +or +.BR free () +are almost always related to heap corruption, such as overflowing +an allocated chunk or freeing the same pointer twice. +.PP +The +.BR malloc () +implementation is tunable via environment variables; see +.BR mallopt (3) +for details. +.SH SEE ALSO +.\" http://g.oswego.edu/dl/html/malloc.html +.\" A Memory Allocator - by Doug Lea +.\" +.\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html +.\" Linux Heap, Contention in free() - David Boreham +.\" +.\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html +.\" malloc() Performance in a Multithreaded Linux Environment - +.\" Check Lever, David Boreham +.\" +.ad l +.nh +.BR valgrind (1), +.BR brk (2), +.BR mmap (2), +.BR alloca (3), +.BR malloc_get_state (3), +.BR malloc_info (3), +.BR malloc_trim (3), +.BR malloc_usable_size (3), +.BR mallopt (3), +.BR mcheck (3), +.BR mtrace (3), +.BR posix_memalign (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/malloc_get_state.3 b/man3/malloc_get_state.3 new file mode 100644 index 0000000..c515c7d --- /dev/null +++ b/man3/malloc_get_state.3 @@ -0,0 +1,139 @@ +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MALLOC_GET_STATE 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +malloc_get_state, malloc_set_state \- record and restore state of malloc implementation +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void* malloc_get_state(void);" +.PP +.BI "int malloc_set_state(void *" state ); +.fi +.SH DESCRIPTION +.IR Note : +these function are removed in glibc version 2.25. +.PP +The +.BR malloc_get_state () +function records the current state of all +.BR malloc (3) +internal bookkeeping variables +(but not the actual contents of the heap +or the state of +.BR malloc_hook (3) +functions pointers). +The state is recorded in a system-dependent opaque data structure +dynamically allocated via +.BR malloc (3), +and a pointer to that data structure is returned as the function result. +(It is the caller's responsibility to +.BR free (3) +this memory.) +.PP +The +.BR malloc_set_state () +function restores the state of all +.BR malloc (3) +internal bookkeeping variables to the values recorded in +the opaque data structure pointed to by +.IR state . +.SH RETURN VALUE +On success, +.BR malloc_get_state () +returns a pointer to a newly allocated opaque data structure. +On error (for example, memory could not be allocated for the data structure), +.BR malloc_get_state () +returns NULL. +.PP +On success, +.BR malloc_set_state () +returns 0. +If the implementation detects that +.I state +does not point to a correctly formed data structure, +.\" if(ms->magic != MALLOC_STATE_MAGIC) return -1; +.BR malloc_set_state () +returns \-1. +If the implementation detects that +the version of the data structure referred to by +.I state +is a more recent version than this implementation knows about, +.\" /* Must fail if the major version is too high. */ +.\" if((ms->version & ~0xffl) > (MALLOC_STATE_VERSION & ~0xffl)) return -2; +.BR malloc_set_state () +returns \-2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR malloc_get_state (), +.BR malloc_set_state () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +These functions are useful when using this +.BR malloc (3) +implementation as part of a shared library, +and the heap contents are saved/restored via some other method. +This technique is used by GNU Emacs to implement its "dumping" function. +.PP +Hook function pointers are never saved or restored by these +functions, with two exceptions: +if malloc checking (see +.BR mallopt (3)) +was in use when +.BR malloc_get_state () +was called, then +.BR malloc_set_state () +resets malloc checking hooks +.\" i.e., calls __malloc_check_init() +if possible; +.\" i.e., malloc checking is not already in use +.\" and the caller requested malloc checking +if malloc checking was not in use in the recorded state, +but the caller has requested malloc checking, +then the hooks are reset to 0. +.SH SEE ALSO +.BR malloc (3), +.BR mallopt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3 new file mode 100644 index 0000000..24225f5 --- /dev/null +++ b/man3/malloc_hook.3 @@ -0,0 +1,155 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Heavily based on glibc documentation +.\" Polished, added docs, removed glibc doc bug, 2002-07-20, aeb +.\" +.TH MALLOC_HOOK 3 2016-07-17 "GNU" "Linux Programmer's Manual" +.SH NAME +__malloc_hook, __malloc_initialize_hook, +__memalign_hook, __free_hook, __realloc_hook, +__after_morecore_hook \- malloc debugging variables +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "void *(*__malloc_hook)(size_t " size ", const void *" caller ); +.PP +.BI "void *(*__realloc_hook)(void *" ptr ", size_t " size \ +", const void *" caller ); +.PP +.BI "void *(*__memalign_hook)(size_t " alignment ", size_t " size , +.BI " const void *" caller ); +.PP +.BI "void (*__free_hook)(void *" ptr ", const void *" caller ); +.PP +.B "void (*__malloc_initialize_hook)(void);" +.PP +.B "void (*__after_morecore_hook)(void);" +.fi +.SH DESCRIPTION +The GNU C library lets you modify the behavior of +.BR malloc (3), +.BR realloc (3), +and +.BR free (3) +by specifying appropriate hook functions. +You can use these hooks +to help you debug programs that use dynamic memory allocation, +for example. +.PP +The variable +.B __malloc_initialize_hook +points at a function that is called once when the malloc implementation +is initialized. +This is a weak variable, so it can be overridden in +the application with a definition like the following: +.PP +.in +4n +.EX +void (*__malloc_initialize_hook)(void) = my_init_hook; +.EE +.in +.PP +Now the function +.IR my_init_hook () +can do the initialization of all hooks. +.PP +The four functions pointed to by +.BR __malloc_hook , +.BR __realloc_hook , +.BR __memalign_hook , +.B __free_hook +have a prototype like the functions +.BR malloc (3), +.BR realloc (3), +.BR memalign (3), +.BR free (3), +respectively, except that they have a final argument +.I caller +that gives the address of the caller of +.BR malloc (3), +etc. +.PP +The variable +.B __after_morecore_hook +points at a function that is called each time after +.BR sbrk (2) +was asked for more memory. +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +The use of these hook functions is not safe in multithreaded programs, +and they are now deprecated. +From glibc 2.24 onwards, the +.B __malloc_initialize_hook +variable has been removed from the API. +.\" https://bugzilla.redhat.com/show_bug.cgi?id=450187 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957 +Programmers should instead preempt calls to the relevant functions +by defining and exporting functions such as "malloc" and "free". +.SH EXAMPLE +Here is a short example of how to use these variables. +.PP +.EX +#include +#include + +/* Prototypes for our hooks. */ +static void my_init_hook(void); +static void *my_malloc_hook(size_t, const void *); + +/* Variables to save original hooks. */ +static void *(*old_malloc_hook)(size_t, const void *); + +/* Override initializing hook from the C library. */ +void (*__malloc_initialize_hook) (void) = my_init_hook; + +static void +my_init_hook(void) +{ + old_malloc_hook = __malloc_hook; + __malloc_hook = my_malloc_hook; +} + +static void * +my_malloc_hook(size_t size, const void *caller) +{ + void *result; + + /* Restore all old hooks */ + __malloc_hook = old_malloc_hook; + + /* Call recursively */ + result = malloc(size); + + /* Save underlying hooks */ + old_malloc_hook = __malloc_hook; + + /* printf() might call malloc(), so protect it too. */ + printf("malloc(%u) called from %p returns %p\\n", + (unsigned int) size, caller, result); + + /* Restore our own hooks */ + __malloc_hook = my_malloc_hook; + + return result; +} +.EE +.SH SEE ALSO +.BR mallinfo (3), +.BR malloc (3), +.BR mcheck (3), +.BR mtrace (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/malloc_info.3 b/man3/malloc_info.3 new file mode 100644 index 0000000..608a7e2 --- /dev/null +++ b/man3/malloc_info.3 @@ -0,0 +1,282 @@ +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MALLOC_INFO 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +malloc_info \- export malloc state to a stream +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int malloc_info(int " options ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR malloc_info () +function exports an XML string that describes the current state +of the memory-allocation +implementation in the caller. +The string is printed on the file stream +.IR stream . +The exported string includes information about all arenas (see +.BR malloc (3)). +.PP +As currently implemented, +.I options +must be zero. +.SH RETURN VALUE +On success, +.BR malloc_info () +returns 0; +on error, it returns \-1, with +.I errno +set to indicate the cause. +.SH ERRORS +.TP +.B EINVAL +.I options +was nonzero. +.SH VERSIONS +.BR malloc_info () +was added to glibc in version 2.10. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR malloc_info () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +This function is a GNU extension. +.SH NOTES +The memory-allocation information is provided as an XML string +(rather than a C structure) +because the information may change over time +(according to changes in the underlying implementation). +The output XML string includes a version field. +.PP +The +.BR open_memstream (3) +function can be used to send the output of +.BR malloc_info () +directly into a buffer in memory, rather than to a file. +.PP +The +.BR malloc_info () +function is designed to address deficiencies in +.BR malloc_stats (3) +and +.BR mallinfo (3). +.SH EXAMPLE +The program below takes up to four command-line arguments, +of which the first three are mandatory. +The first argument specifies the number of threads that +the program should create. +All of the threads, including the main thread, +allocate the number of blocks of memory specified by the second argument. +The third argument controls the size of the blocks to be allocated. +The main thread creates blocks of this size, +the second thread created by the program allocates blocks of twice this size, +the third thread allocates blocks of three times this size, and so on. +.PP +The program calls +.BR malloc_info () +twice to display the memory-allocation state. +The first call takes place before any threads +are created or memory allocated. +The second call is performed after all threads have allocated memory. +.PP +In the following example, +the command-line arguments specify the creation of one additional thread, +and both the main thread and the additional thread +allocate 10000 blocks of memory. +After the blocks of memory have been allocated, +.BR malloc_info () +shows the state of two allocation arenas. +.PP +.in +4 +.EX +.RB "$ " "getconf GNU_LIBC_VERSION" +glibc 2.13 +.RB "$ " "./a.out 1 10000 100" +============ Before allocating blocks ============ + + + + + + + + + + + + + + + + + + + +============ After allocating blocks ============ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.EE +.in +.SS Program source +.EX +#include +#include +#include +#include +#include + +static size_t blockSize; +static int numThreads, numBlocks; + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +static void * +thread_func(void *arg) +{ + int j; + int tn = (int) arg; + + /* The multiplier \(aq(2 + tn)\(aq ensures that each thread (including + the main thread) allocates a different amount of memory */ + + for (j = 0; j < numBlocks; j++) + if (malloc(blockSize * (2 + tn)) == NULL) + errExit("malloc\-thread"); + + sleep(100); /* Sleep until main thread terminates */ + return NULL; +} + +int +main(int argc, char *argv[]) +{ + int j, tn, sleepTime; + pthread_t *thr; + + if (argc < 4) { + fprintf(stderr, + "%s num\-threads num\-blocks block\-size [sleep\-time]\\n", + argv[0]); + exit(EXIT_FAILURE); + } + + numThreads = atoi(argv[1]); + numBlocks = atoi(argv[2]); + blockSize = atoi(argv[3]); + sleepTime = (argc > 4) ? atoi(argv[4]) : 0; + + thr = calloc(numThreads, sizeof(pthread_t)); + if (thr == NULL) + errExit("calloc"); + + printf("============ Before allocating blocks ============\\n"); + malloc_info(0, stdout); + + /* Create threads that allocate different amounts of memory */ + + for (tn = 0; tn < numThreads; tn++) { + errno = pthread_create(&thr[tn], NULL, thread_func, + (void *) tn); + if (errno != 0) + errExit("pthread_create"); + + /* If we add a sleep interval after the start\-up of each + thread, the threads likely won\(aqt contend for malloc + mutexes, and therefore additional arenas won\(aqt be + allocated (see malloc(3)). */ + + if (sleepTime > 0) + sleep(sleepTime); + } + + /* The main thread also allocates some memory */ + + for (j = 0; j < numBlocks; j++) + if (malloc(blockSize) == NULL) + errExit("malloc"); + + sleep(2); /* Give all threads a chance to + complete allocations */ + + printf("\\n============ After allocating blocks ============\\n"); + malloc_info(0, stdout); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_stats (3), +.BR mallopt (3), +.BR open_memstream (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/malloc_set_state.3 b/man3/malloc_set_state.3 new file mode 100644 index 0000000..ff16dd7 --- /dev/null +++ b/man3/malloc_set_state.3 @@ -0,0 +1 @@ +.so man3/malloc_get_state.3 diff --git a/man3/malloc_stats.3 b/man3/malloc_stats.3 new file mode 100644 index 0000000..07895de --- /dev/null +++ b/man3/malloc_stats.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MALLOC_STATS 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +malloc_stats \- print memory allocation statistics +.SH SYNOPSIS +.B #include +.PP +.B void malloc_stats(void); +.SH DESCRIPTION +The +.BR malloc_stats () +function prints (on standard error) statistics about memory allocated by +.BR malloc (3) +and related functions. +For each arena (allocation area), this function prints +the total amount of memory allocated +and the total number of bytes consumed by in-use allocations. +(These two values correspond to the +.I arena +and +.I uordblks +fields retrieved by +.BR mallinfo (3).) +In addition, +the function prints the sum of these two statistics for all arenas, +and the maximum number of blocks and bytes that were ever simultaneously +allocated using +.BR mmap (2). +.\" .SH VERSIONS +.\" Available already in glibc 2.0, possibly earlier +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR malloc_stats () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +This function is a GNU extension. +.SH NOTES +More detailed information about memory allocations in the main arena +can be obtained using +.BR mallinfo (3). +.SH SEE ALSO +.BR mmap (2), +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_info (3), +.BR mallopt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/malloc_trim.3 b/man3/malloc_trim.3 new file mode 100644 index 0000000..77d1319 --- /dev/null +++ b/man3/malloc_trim.3 @@ -0,0 +1,103 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MALLOC_TRIM 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +malloc_trim \- release free memory from the top of the heap +.SH SYNOPSIS +.B #include +.PP +.BI "int malloc_trim(size_t " pad ); +.SH DESCRIPTION +The +.BR malloc_trim () +function attempts to release free memory at the top of the heap +(by calling +.BR sbrk (2) +with a suitable argument). +.PP +The +.I pad +argument specifies the amount of free space to leave untrimmed +at the top of the heap. +If this argument is 0, only the minimum amount of memory is maintained +at the top of the heap (i.e., one page or less). +A nonzero argument can be used to maintain some trailing space +at the top of the heap in order to allow future allocations +to be made without having to extend the heap with +.BR sbrk (2). +.SH RETURN VALUE +The +.BR malloc_trim () +function returns 1 if memory was actually released back to the system, +or 0 if it was not possible to release any memory. +.SH ERRORS +No errors are defined. +.\" .SH VERSIONS +.\" Available already in glibc 2.0, possibly earlier +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR malloc_trim () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +This function is a GNU extension. +.SH NOTES +This function is automatically called by +.BR free (3) +in certain circumstances; see the discussion of +.B M_TOP_PAD +and +.B M_TRIM_THRESHOLD +in +.BR mallopt (3). +.PP +This function cannot release free memory located at places +other than the top of the heap. +.PP +This function releases only memory in the main arena. +.\" malloc/malloc.c::mTRIm(): +.\" return result | (av == &main_arena ? sYSTRIm (pad, av) : 0); +.SH SEE ALSO +.BR sbrk (2), +.BR malloc (3), +.BR mallopt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/malloc_usable_size.3 b/man3/malloc_usable_size.3 new file mode 100644 index 0000000..c3bfec3 --- /dev/null +++ b/man3/malloc_usable_size.3 @@ -0,0 +1,84 @@ +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MALLOC_USABLE_SIZE 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +malloc_usable_size \- obtain size of block of memory allocated from heap +.SH SYNOPSIS +.B #include +.PP +.BI "size_t malloc_usable_size (void *" ptr ); +.SH DESCRIPTION +The +.BR malloc_usable_size () +function returns the number of usable bytes in the block pointed to by +.IR ptr , +a pointer to a block of memory allocated by +.BR malloc (3) +or a related function. +.SH RETURN VALUE +.BR malloc_usable_size () +returns the number of usable bytes in +the block of allocated memory pointed to by +.IR ptr . +If +.I ptr +is NULL, 0 is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR malloc_usable_size () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is a GNU extension. +.SH NOTES +The value returned by +.BR malloc_usable_size () +may be greater than the requested size of the allocation because +of alignment and minimum size constraints. +Although the excess bytes can be overwritten by the application +without ill effects, +this is not good programming practice: +the number of excess bytes in an allocation depends on +the underlying implementation. +.PP +The main use of this function is for debugging and introspection. +.SH SEE ALSO +.BR malloc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mallopt.3 b/man3/mallopt.3 new file mode 100644 index 0000000..2150f6a --- /dev/null +++ b/man3/mallopt.3 @@ -0,0 +1,636 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MALLOPT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mallopt \- set memory allocation parameters +.SH SYNOPSIS +.B #include +.PP +.BI "int mallopt(int " param ", int " value ); +.SH DESCRIPTION +The +.BR mallopt () +function adjusts parameters that control the behavior of the +memory-allocation functions (see +.BR malloc (3)). +The +.IR param +argument specifies the parameter to be modified, and +.I value +specifies the new value for that parameter. +.PP +The following values can be specified for +.IR param : +.TP +.BR M_ARENA_MAX +If this parameter has a nonzero value, +it defines a hard limit on the maximum number of arenas that can be created. +An arena represents a pool of memory that can be used by +.BR malloc (3) +(and similar) calls to service allocation requests. +Arenas are thread safe and +therefore may have multiple concurrent memory requests. +The trade-off is between the number of threads and the number of arenas. +The more arenas you have, the lower the per-thread contention, +but the higher the memory usage. +.IP +The default value of this parameter is 0, +meaning that the limit on the number of arenas is determined +according to the setting of +.BR M_ARENA_TEST . +.IP +This parameter has been available since glibc 2.10 via +.BR \-\-enable\-experimental\-malloc , +and since glibc 2.15 by default. +In some versions of the allocator there was no limit on the number +of created arenas (e.g., CentOS 5, RHEL 5). +.IP +When employing newer glibc versions, applications may in +some cases exhibit high contention when accessing arenas. +In these cases, it may be beneficial to increase +.B M_ARENA_MAX +to match the number of threads. +This is similar in behavior to strategies taken by tcmalloc and jemalloc +(e.g., per-thread allocation pools). +.TP +.BR M_ARENA_TEST +This parameter specifies a value, in number of arenas created, +at which point the system configuration will be examined +to determine a hard limit on the number of created arenas. +(See +.B M_ARENA_MAX +for the definition of an arena.) +.IP +The computation of the arena hard limit is implementation-defined +and is usually calculated as a multiple of the number of available CPUs. +Once the hard limit is computed, the result is final and constrains +the total number of arenas. +.IP +The default value for the +.B M_ARENA_TEST +parameter is 2 on systems where +.IR sizeof(long) +is 4; otherwise the default value is 8. +.IP +This parameter has been available since glibc 2.10 via +.BR \-\-enable\-experimental\-malloc , +and since glibc 2.15 by default. +.IP +The value of +.B M_ARENA_TEST +is not used when +.B M_ARENA_MAX +has a nonzero value. +.TP +.BR M_CHECK_ACTION +Setting this parameter controls how glibc responds when various kinds +of programming errors are detected (e.g., freeing the same pointer twice). +The 3 least significant bits (2, 1, and 0) of the value assigned +to this parameter determine the glibc behavior, as follows: +.RS +.TP +Bit 0 +If this bit is set, then print a one-line message on +.I stderr +that provides details about the error. +The message starts with the string "***\ glibc detected\ ***", +followed by the program name, +the name of the memory-allocation function in which the error was detected, +a brief description of the error, +and the memory address where the error was detected. +.TP +Bit 1 +If this bit is set, then, +after printing any error message specified by bit 0, +the program is terminated by calling +.BR abort (3). +In glibc versions since 2.4, +if bit 0 is also set, +then, between printing the error message and aborting, +the program also prints a stack trace in the manner of +.BR backtrace (3), +and prints the process's memory mapping in the style of +.IR /proc/[pid]/maps +(see +.BR proc (5)). +.TP +Bit 2 (since glibc 2.4) +This bit has an effect only if bit 0 is also set. +If this bit is set, +then the one-line message describing the error is simplified +to contain just the name of the function where the error +was detected and the brief description of the error. +.RE +.IP +The remaining bits in +.I value +are ignored. +.IP +Combining the above details, +the following numeric values are meaningful for +.BR M_CHECK_ACTION : +.RS 12 +.IP 0 3 +Ignore error conditions; continue execution (with undefined results). +.IP 1 +Print a detailed error message and continue execution. +.IP 2 +Abort the program. +.IP 3 +Print detailed error message, stack trace, and memory mappings, +and abort the program. +.IP 5 +Print a simple error message and continue execution. +.IP 7 +Print simple error message, stack trace, and memory mappings, +and abort the program. +.RE +.IP +Since glibc 2.3.4, the default value for the +.BR M_CHECK_ACTION +parameter is 3. +In glibc version 2.3.3 and earlier, the default value is 1. +.IP +Using a nonzero +.B M_CHECK_ACTION +value can be useful because otherwise a crash may happen much later, +and the true cause of the problem is then very hard to track down. +.TP +.BR M_MMAP_MAX +.\" The following text adapted from comments in the glibc source: +This parameter specifies the maximum number of allocation requests that +may be simultaneously serviced using +.BR mmap (2). +This parameter exists because some systems have a limited number +of internal tables for use by +.BR mmap (2), +and using more than a few of them may degrade performance. +.IP +The default value is 65,536, +a value which has no special significance and +which serves only as a safeguard. +Setting this parameter to 0 disables the use of +.BR mmap (2) +for servicing large allocation requests. +.TP +.BR M_MMAP_THRESHOLD +For allocations greater than or equal to the limit specified (in bytes) by +.BR M_MMAP_THRESHOLD +that can't be satisfied from the free list, +the memory-allocation functions employ +.BR mmap (2) +instead of increasing the program break using +.BR sbrk (2). +.IP +Allocating memory using +.BR mmap (2) +has the significant advantage that the allocated memory blocks +can always be independently released back to the system. +(By contrast, +the heap can be trimmed only if memory is freed at the top end.) +On the other hand, there are some disadvantages to the use of +.BR mmap (2): +deallocated space is not placed on the free list +for reuse by later allocations; +memory may be wasted because +.BR mmap (2) +allocations must be page-aligned; +and the kernel must perform the expensive task of zeroing out +memory allocated via +.BR mmap (2). +Balancing these factors leads to a default setting of 128*1024 for the +.BR M_MMAP_THRESHOLD +parameter. +.IP +The lower limit for this parameter is 0. +The upper limit is +.BR DEFAULT_MMAP_THRESHOLD_MAX : +512*1024 on 32-bit systems or +.IR 4*1024*1024*sizeof(long) +on 64-bit systems. +.IP +.IR Note: +Nowadays, glibc uses a dynamic mmap threshold by default. +The initial value of the threshold is 128*1024, +but when blocks larger than the current threshold and less than or equal to +.BR DEFAULT_MMAP_THRESHOLD_MAX +are freed, +the threshold is adjusted upward to the size of the freed block. +When dynamic mmap thresholding is in effect, +the threshold for trimming the heap is also dynamically adjusted +to be twice the dynamic mmap threshold. +Dynamic adjustment of the mmap threshold is disabled if any of the +.BR M_TRIM_THRESHOLD , +.BR M_TOP_PAD , +.BR M_MMAP_THRESHOLD , +or +.BR M_MMAP_MAX +parameters is set. +.TP +.BR M_MXFAST " (since glibc 2.3)" +.\" The following text adapted from comments in the glibc sources: +Set the upper limit for memory allocation requests that are satisfied +using "fastbins". +(The measurement unit for this parameter is bytes.) +Fastbins are storage areas that hold deallocated blocks of memory +of the same size without merging adjacent free blocks. +Subsequent reallocation of blocks of the same size can be handled +very quickly by allocating from the fastbin, +although memory fragmentation and the overall memory footprint +of the program can increase. +.IP +The default value for this parameter is +.IR "64*sizeof(size_t)/4" +(i.e., 64 on 32-bit architectures). +The range for this parameter is 0 to +.IR "80*sizeof(size_t)/4" . +Setting +.B M_MXFAST +to 0 disables the use of fastbins. +.TP +.BR M_PERTURB " (since glibc 2.4)" +If this parameter is set to a nonzero value, +then bytes of allocated memory (other than allocations via +.BR calloc (3)) +are initialized to the complement of the value +in the least significant byte of +.IR value , +and when allocated memory is released using +.BR free (3), +the freed bytes are set to the least significant byte of +.IR value . +This can be useful for detecting errors where programs +incorrectly rely on allocated memory being initialized to zero, +or reuse values in memory that has already been freed. +.IP +The default value for this parameter is 0. +.TP +.BR M_TOP_PAD +This parameter defines the amount of padding to employ when calling +.BR sbrk (2) +to modify the program break. +(The measurement unit for this parameter is bytes.) +This parameter has an effect in the following circumstances: +.RS +.IP * 3 +When the program break is increased, then +.BR M_TOP_PAD +bytes are added to the +.BR sbrk (2) +request. +.IP * +When the heap is trimmed as a consequence of calling +.BR free (3) +(see the discussion of +.BR M_TRIM_THRESHOLD ) +this much free space is preserved at the top of the heap. +.RE +.IP +In either case, +the amount of padding is always rounded to a system page boundary. +.IP +Modifying +.BR M_TOP_PAD +is a trade-off between increasing the number of system calls +(when the parameter is set low) +and wasting unused memory at the top of the heap +(when the parameter is set high). +.IP +The default value for this parameter is 128*1024. +.\" DEFAULT_TOP_PAD in glibc source +.TP +.BR M_TRIM_THRESHOLD +When the amount of contiguous free memory at the top of the heap +grows sufficiently large, +.BR free (3) +employs +.BR sbrk (2) +to release this memory back to the system. +(This can be useful in programs that continue to execute for +a long period after freeing a significant amount of memory.) +The +.BR M_TRIM_THRESHOLD +parameter specifies the minimum size (in bytes) that +this block of memory must reach before +.BR sbrk (2) +is used to trim the heap. +.IP +The default value for this parameter is 128*1024. +Setting +.BR M_TRIM_THRESHOLD +to \-1 disables trimming completely. +.IP +Modifying +.BR M_TRIM_THRESHOLD +is a trade-off between increasing the number of system calls +(when the parameter is set low) +and wasting unused memory at the top of the heap +(when the parameter is set high). +.\" +.SS Environment variables +A number of environment variables can be defined +to modify some of the same parameters as are controlled by +.BR mallopt (). +Using these variables has the advantage that the source code +of the program need not be changed. +To be effective, these variables must be defined before the +first call to a memory-allocation function. +(If the same parameters are adjusted via +.BR mallopt (), +then the +.BR mallopt () +settings take precedence.) +For security reasons, +these variables are ignored in set-user-ID and set-group-ID programs. +.PP +The environment variables are as follows +(note the trailing underscore at the end of the name of some variables): +.TP +.BR MALLOC_ARENA_MAX +Controls the same parameter as +.BR mallopt () +.BR M_ARENA_MAX . +.TP +.BR MALLOC_ARENA_TEST +Controls the same parameter as +.BR mallopt () +.BR M_ARENA_TEST . +.TP +.BR MALLOC_CHECK_ +This environment variable controls the same parameter as +.BR mallopt () +.BR M_CHECK_ACTION . +If this variable is set to a nonzero value, +then a special implementation of the memory-allocation functions is used. +(This is accomplished using the +.BR malloc_hook (3) +feature.) +This implementation performs additional error checking, +but is slower +.\" On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower +.\" when MALLOC_CHECK_ was set. +than the standard set of memory-allocation functions. +(This implementation does not detect all possible errors; +memory leaks can still occur.) +.IP +The value assigned to this environment variable should be a single digit, +whose meaning is as described for +.BR M_CHECK_ACTION . +Any characters beyond the initial digit are ignored. +.IP +For security reasons, the effect of +.BR MALLOC_CHECK_ +is disabled by default for set-user-ID and set-group-ID programs. +However, if the file +.IR /etc/suid\-debug +exists (the content of the file is irrelevant), then +.BR MALLOC_CHECK_ +also has an effect for set-user-ID and set-group-ID programs. +.TP +.BR MALLOC_MMAP_MAX_ +Controls the same parameter as +.BR mallopt () +.BR M_MMAP_MAX . +.TP +.BR MALLOC_MMAP_THRESHOLD_ +Controls the same parameter as +.BR mallopt () +.BR M_MMAP_THRESHOLD . +.TP +.BR MALLOC_PERTURB_ +Controls the same parameter as +.BR mallopt () +.BR M_PERTURB . +.TP +.BR MALLOC_TRIM_THRESHOLD_ +Controls the same parameter as +.BR mallopt () +.BR M_TRIM_THRESHOLD . +.TP +.BR MALLOC_TOP_PAD_ +Controls the same parameter as +.BR mallopt () +.BR M_TOP_PAD . +.SH RETURN VALUE +On success, +.BR mallopt () +returns 1. +On error, it returns 0. +.SH ERRORS +On error, +.I errno +is +.I not +set. +.\" .SH VERSIONS +.\" Available already in glibc 2.0, possibly earlier +.SH CONFORMING TO +This function is not specified by POSIX or the C standards. +A similar function exists on many System V derivatives, +but the range of values for +.IR param +varies across systems. +The SVID defined options +.BR M_MXFAST , +.BR M_NLBLKS , +.BR M_GRAIN , +and +.BR M_KEEP , +but only the first of these is implemented in glibc. +.\" .SH NOTES +.SH BUGS +Specifying an invalid value for +.I param +does not generate an error. +.PP +A calculation error within the glibc implementation means that +a call of the form: +.\" FIXME . This looks buggy: +.\" setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK) +.\" malloc requests are rounded up: +.\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=12129 +.PP +.in +4n +.EX +mallopt(M_MXFAST, n) +.EE +.in +.PP +does not result in fastbins being employed for all allocations of size up to +.IR n . +To ensure desired results, +.I n +should be rounded up to the next multiple greater than or equal to +.IR (2k+1)*sizeof(size_t) , +where +.I k +is an integer. +.\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t) +.PP +If +.BR mallopt () +is used to set +.BR M_PERTURB , +then, as expected, the bytes of allocated memory are initialized +to the complement of the byte in +.IR value , +and when that memory is freed, +the bytes of the region are initialized to the byte specified in +.IR value . +However, there is an +.RI off-by- sizeof(size_t) +error in the implementation: +.\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12140 +instead of initializing precisely the block of memory +being freed by the call +.IR free(p) , +the block starting at +.I p+sizeof(size_t) +is initialized. +.SH EXAMPLE +The program below demonstrates the use of +.BR M_CHECK_ACTION . +If the program is supplied with an (integer) command-line argument, +then that argument is used to set the +.BR M_CHECK_ACTION +parameter. +The program then allocates a block of memory, +and frees it twice (an error). +.PP +The following shell session shows what happens when we run this program +under glibc, with the default value for +.BR M_CHECK_ACTION : +.PP +.in +4n +.EX +$ \fB./a.out\fP +main(): returned from first free() call +*** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 *** +======= Backtrace: ========= +/lib/libc.so.6(+0x6c501)[0x523501] +/lib/libc.so.6(+0x6dd70)[0x524d70] +/lib/libc.so.6(cfree+0x6d)[0x527e5d] +\&./a.out[0x80485db] +/lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7] +\&./a.out[0x8048471] +======= Memory map: ======== +001e4000\-001fe000 r\-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1 +001fe000\-001ff000 r\-\-p 00019000 08:06 1083555 /lib/libgcc_s.so.1 +[some lines omitted] +b7814000\-b7817000 rw\-p 00000000 00:00 0 +bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack] +Aborted (core dumped) +.EE +.in +.PP +The following runs show the results when employing other values for +.BR M_CHECK_ACTION : +.PP +.in +4n +.EX +$ \fB./a.out 1\fP # Diagnose error and continue +main(): returned from first free() call +*** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 *** +main(): returned from second free() call +$ \fB./a.out 2\fP # Abort without error message +main(): returned from first free() call +Aborted (core dumped) +$ \fB./a.out 0\fP # Ignore error and continue +main(): returned from first free() call +main(): returned from second free() call +.EE +.in +.PP +The next run shows how to set the same parameter using the +.B MALLOC_CHECK_ +environment variable: +.PP +.in +4n +.EX +$ \fBMALLOC_CHECK_=1 ./a.out\fP +main(): returned from first free() call +*** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 *** +main(): returned from second free() call +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + char *p; + + if (argc > 1) { + if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) { + fprintf(stderr, "mallopt() failed"); + exit(EXIT_FAILURE); + } + } + + p = malloc(1000); + if (p == NULL) { + fprintf(stderr, "malloc() failed"); + exit(EXIT_FAILURE); + } + + free(p); + printf("main(): returned from first free() call\\n"); + + free(p); + printf("main(): returned from second free() call\\n"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR sbrk (2), +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_hook (3), +.BR malloc_info (3), +.BR malloc_stats (3), +.BR malloc_trim (3), +.BR mcheck (3), +.BR mtrace (3), +.BR posix_memalign (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/matherr.3 b/man3/matherr.3 new file mode 100644 index 0000000..91a6443 --- /dev/null +++ b/man3/matherr.3 @@ -0,0 +1,451 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MATHERR 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +matherr \- SVID math library exception handling +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int matherr(struct exception *" exc ); +.PP +.B extern _LIB_VERSION_TYPE _LIB_VERSION; +.fi +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +.IR Note : +the mechanism described in this page is no longer supported by glibc. +Before glibc 2.27, it had been marked as obsolete. +Since glibc 2.27, +.\" glibc commit 813378e9fe17e029caf627cab76fe23eb46815fa +the mechanism has been removed altogether. +New applications should use the techniques described in +.BR math_error (7) +and +.BR fenv (3). +This page documents the +.BR matherr () +mechanism as an aid for maintaining and porting older applications. +.PP +The System V Interface Definition (SVID) specifies that various +math functions should invoke a function called +.BR matherr () +if a math exception is detected. +This function is called before the math function returns; +after +.BR matherr () +returns, the system then returns to the math function, +which in turn returns to the caller. +.PP +To employ +.BR matherr (), +the programmer must define the +.B _SVID_SOURCE +feature test macro +(before including +.I any +header files), +and assign the value +.B _SVID_ +to the external variable +.BR _LIB_VERSION . +.PP +The system provides a default version of +.BR matherr (). +This version does nothing, and returns zero +(see below for the significance of this). +The default +.BR matherr () +can be overridden by a programmer-defined +version, which will be invoked when an exception occurs. +The function is invoked with one argument, a pointer to an +.I exception +structure, defined as follows: +.PP +.in +4n +.EX +struct exception { + int type; /* Exception type */ + char *name; /* Name of function causing exception */ + double arg1; /* 1st argument to function */ + double arg2; /* 2nd argument to function */ + double retval; /* Function return value */ +} +.EE +.in +.PP +The +.I type +field has one of the following values: +.TP 12 +.B DOMAIN +A domain error occurred (the function argument was outside the range +for which the function is defined). +The return value depends on the function; +.I errno +is set to +.BR EDOM . +.TP +.B SING +A pole error occurred (the function result is an infinity). +The return value in most cases is +.B HUGE +(the largest single precision floating-point number), +appropriately signed. +In most cases, +.I errno +is set to +.BR EDOM . +.TP +.B OVERFLOW +An overflow occurred. +In most cases, the value +.B HUGE +is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B UNDERFLOW +An underflow occurred. +0.0 is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B TLOSS +Total loss of significance. +0.0 is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B PLOSS +Partial loss of significance. +This value is unused on glibc +(and many other systems). +.PP +The +.I arg1 +and +.I arg2 +fields are the arguments supplied to the function +.RI ( arg2 +is undefined for functions that take only one argument). +.PP +The +.I retval +field specifies the return value that the math +function will return to its caller. +The programmer-defined +.BR matherr () +can modify this field to change the return value of the math function. +.PP +If the +.BR matherr () +function returns zero, then the system sets +.I errno +as described above, and may print an error message on standard error +(see below). +.PP +If the +.BR matherr () +function returns a nonzero value, then the system does not set +.IR errno , +and doesn't print an error message. +.SS Math functions that employ matherr() +The table below lists the functions and circumstances in which +.BR matherr () +is called. +The "Type" column indicates the value assigned to +.I exc\->type +when calling +.BR matherr (). +The "Result" column is the default return value assigned to +.IR exc\->retval . +.PP +The "Msg?" and "errno" columns describe the default behavior if +.BR matherr () +returns zero. +If the "Msg?" columns contains "y", +then the system prints an error message on standard error. +.PP +The table uses the following notations and abbreviations: +.PP +.RS +.nf +x first argument to function +y second argument to function +fin finite value for argument +neg negative value for argument +int integral value for argument +o/f result overflowed +u/f result underflowed +|x| absolute value of x +X_TLOSS is a constant defined in \fI\fP +.fi +.RE +.\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c +.\" A subset of cases were test by experimental programs. +.TS +lB lB lB cB lB +l l l c l. +Function Type Result Msg? errno +acos(|x|>1) DOMAIN HUGE y EDOM +asin(|x|>1) DOMAIN HUGE y EDOM +atan2(0,0) DOMAIN HUGE y EDOM +acosh(x<1) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +atanh(|x|>1) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +atanh(|x|==1) SING (x>0.0)? y EDOM \" retval is x/0.0 +\ \ HUGE_VAL : +\ \ \-HUGE_VAL +cosh(fin) o/f OVERFLOW HUGE n ERANGE +sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE +\ \ HUGE : \-HUGE +sqrt(x<0) DOMAIN 0.0 y EDOM +hypot(fin,fin) o/f OVERFLOW HUGE n ERANGE +exp(fin) o/f OVERFLOW HUGE n ERANGE +exp(fin) u/f UNDERFLOW 0.0 n ERANGE +exp2(fin) o/f OVERFLOW HUGE n ERANGE +exp2(fin) u/f UNDERFLOW 0.0 n ERANGE +exp10(fin) o/f OVERFLOW HUGE n ERANGE +exp10(fin) u/f UNDERFLOW 0.0 n ERANGE +j0(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +j1(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +jn(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +y0(x>X_TLOSS) TLOSS 0.0 y ERANGE +y1(x>X_TLOSS) TLOSS 0.0 y ERANGE +yn(x>X_TLOSS) TLOSS 0.0 y ERANGE +y0(0) DOMAIN \-HUGE y EDOM +y0(x<0) DOMAIN \-HUGE y EDOM +y1(0) DOMAIN \-HUGE y EDOM +y1(x<0) DOMAIN \-HUGE y EDOM +yn(n,0) DOMAIN \-HUGE y EDOM +yn(x<0) DOMAIN \-HUGE y EDOM +lgamma(fin) o/f OVERFLOW HUGE n ERANGE +lgamma(\-int) or SING HUGE y EDOM +\ \ lgamma(0) +tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE +tgamma(\-int) SING NAN y EDOM +tgamma(0) SING copysign( y ERANGE +\ \ HUGE_VAL,x) +log(0) SING \-HUGE y EDOM +log(x<0) DOMAIN \-HUGE y EDOM +log2(0) SING \-HUGE n EDOM \" different from log() +log2(x<0) DOMAIN \-HUGE n EDOM \" different from log() +log10(0) SING \-HUGE y EDOM +log10(x<0) DOMAIN \-HUGE y EDOM +pow(0.0,0.0) DOMAIN 0.0 y EDOM +pow(x,y) o/f OVERFLOW HUGE n ERANGE +pow(x,y) u/f UNDERFLOW 0.0 n ERANGE +pow(NaN,0.0) DOMAIN x n EDOM +0**neg DOMAIN 0.0 y EDOM \" +0 and -0 +neg**non-int DOMAIN 0.0 y EDOM +scalb() o/f OVERFLOW (x>0.0) ? n ERANGE +\ \ HUGE_VAL : +\ \ \-HUGE_VAL +scalb() u/f UNDERFLOW copysign( n ERANGE +\ \ \ \ 0.0,x) +fmod(x,0) DOMAIN x y EDOM +remainder(x,0) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +.TE +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR matherr () +T} Thread safety MT-Safe +.TE +.SH EXAMPLE +The example program demonstrates the use of +.BR matherr () +when calling +.BR log (3). +The program takes up to three command-line arguments. +The first argument is the floating-point number to be given to +.BR log (3). +If the optional second argument is provided, then +.B _LIB_VERSION +is set to +.B _SVID_ +so that +.BR matherr () +is called, and the integer supplied in the +command-line argument is used as the return value from +.BR matherr (). +If the optional third command-line argument is supplied, +then it specifies an alternative return value that +.BR matherr () +should assign as the return value of the math function. +.PP +The following example run, where +.BR log (3) +is given an argument of 0.0, does not use +.BR matherr (): +.PP +.in +4n +.EX +.RB "$" " ./a.out 0.0" +errno: Numerical result out of range +x=-inf +.EE +.in +.PP +In the following run, +.BR matherr () +is called, and returns 0: +.PP +.in +4n +.EX +.RB "$" " ./a.out 0.0 0" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +log: SING error +errno: Numerical argument out of domain +x=-340282346638528859811704183484516925440.000000 +.EE +.in +.PP +The message "log: SING error" was printed by the C library. +.PP +In the following run, +.BR matherr () +is called, and returns a nonzero value: +.PP +.in +4n +.EX +.RB "$" " ./a.out 0.0 1" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +x=-340282346638528859811704183484516925440.000000 +.EE +.in +.PP +In this case, the C library did not print a message, and +.I errno +was not set. +.PP +In the following run, +.BR matherr () +is called, changes the return value of the math function, +and returns a nonzero value: +.PP +.in +4n +.EX +.RB "$" " ./a.out 0.0 1 12345.0" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +x=12345.000000 +.EE +.in +.SS Program source +\& +.EX +#define _SVID_SOURCE +#include +#include +#include +#include + +static int matherr_ret = 0; /* Value that matherr() + should return */ +static int change_retval = 0; /* Should matherr() change + function\(aqs return value? */ +static double new_retval; /* New function return value */ + +int +matherr(struct exception *exc) +{ + fprintf(stderr, "matherr %s exception in %s() function\\n", + (exc\->type == DOMAIN) ? "DOMAIN" : + (exc\->type == OVERFLOW) ? "OVERFLOW" : + (exc\->type == UNDERFLOW) ? "UNDERFLOW" : + (exc\->type == SING) ? "SING" : + (exc\->type == TLOSS) ? "TLOSS" : + (exc\->type == PLOSS) ? "PLOSS" : "???", + exc\->name); + fprintf(stderr, " args: %f, %f\\n", + exc\->arg1, exc\->arg2); + fprintf(stderr, " retval: %f\\n", exc\->retval); + + if (change_retval) + exc\->retval = new_retval; + + return matherr_ret; +} + +int +main(int argc, char *argv[]) +{ + double x; + + if (argc < 2) { + fprintf(stderr, "Usage: %s " + " [ []]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + if (argc > 2) { + _LIB_VERSION = _SVID_; + matherr_ret = atoi(argv[2]); + } + + if (argc > 3) { + change_retval = 1; + new_retval = atof(argv[3]); + } + + x = log(atof(argv[1])); + if (errno != 0) + perror("errno"); + + printf("x=%f\\n", x); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fenv (3), +.BR math_error (7), +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mblen.3 b/man3/mblen.3 new file mode 100644 index 0000000..7a64810 --- /dev/null +++ b/man3/mblen.3 @@ -0,0 +1,123 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBLEN 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +mblen \- determine number of bytes in next multibyte character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mblen(const char *" s ", size_t " n ); +.fi +.SH DESCRIPTION +If +.I s +is not NULL, the +.BR mblen () +function inspects at most +.I n +bytes of the multibyte string starting at +.I s +and extracts the +next complete multibyte character. +It uses a static anonymous shift state known only to the +.BR mblen () +function. +If the multibyte character is not the null wide +character, it returns the number of bytes that were consumed from +.IR s . +If the multibyte character is the null wide character, it returns 0. +.PP +If the +.IR n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mblen () +returns \-1. +This can happen even if +.I n +is greater than or equal to +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift sequences. +.PP +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mblen () +also returns \-1. +.PP +If +.I s +is NULL, the +.BR mblen () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, known to only this function, to the initial state, and +returns nonzero if the encoding has nontrivial shift state, or zero if the +encoding is stateless. +.SH RETURN VALUE +The +.BR mblen () +function returns the number of +bytes parsed from the multibyte +sequence starting at +.IR s , +if a non-null wide character was recognized. +It returns 0, if a null wide character was recognized. +It returns \-1, if an +invalid multibyte sequence was encountered or if it couldn't parse a complete +multibyte character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mblen () +T} Thread safety MT-Unsafe race +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR mblen () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +The function +.BR mbrlen (3) +provides a better interface to the same +functionality. +.SH SEE ALSO +.BR mbrlen (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mbrlen.3 b/man3/mbrlen.3 new file mode 100644 index 0000000..a8406f9 --- /dev/null +++ b/man3/mbrlen.3 @@ -0,0 +1,135 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBRLEN 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +mbrlen \- determine number of bytes in next multibyte character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t mbrlen(const char *" s ", size_t " n ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The +.BR mbrlen () +function inspects at most +.I n +bytes of the multibyte +string starting at +.I s +and extracts the next complete multibyte character. +It updates the shift state +.IR *ps . +If the multibyte character is not the +null wide character, it returns the number of bytes that were consumed from +.IR s . +If the multibyte character is the null wide character, it resets the +shift state +.I *ps +to the initial state and returns 0. +.PP +If the +.IR n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mbrlen () +returns +.IR "(size_t)\ \-2" . +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift +sequences. +.PP +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mbrlen () +returns +.IR "(size_t)\ \-1" +and sets +.I errno +to +.BR EILSEQ . +In this case, +the effects on +.I *ps +are undefined. +.PP +If +.I ps +is NULL, a static anonymous state known only to the +.BR mbrlen () +function is used instead. +.SH RETURN VALUE +The +.BR mbrlen () +function returns the number of bytes +parsed from the multibyte +sequence starting at +.IR s , +if a non-null wide character was recognized. +It returns 0, if a null wide character was recognized. +It returns +.I "(size_t)\ \-1" +and sets +.I errno +to +.BR EILSEQ , +if an invalid multibyte sequence was +encountered. +It returns +.IR "(size_t)\ \-2" +if it couldn't parse a complete multibyte +character, meaning that +.I n +should be increased. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mbrlen () +T} Thread safety MT-Unsafe race:mbrlen/!ps +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR mbrlen () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbrtowc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mbrtowc.3 b/man3/mbrtowc.3 new file mode 100644 index 0000000..f8ab86c --- /dev/null +++ b/man3/mbrtowc.3 @@ -0,0 +1,207 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBRTOWC 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +mbrtowc \- convert a multibyte sequence to a wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t mbrtowc(wchar_t *" pwc ", const char *" s ", size_t " n \ +", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The main case for this function is when +.IR s +is not NULL and +.I pwc +is +not NULL. +In this case, the +.BR mbrtowc () +function inspects at most +.I n +bytes of the multibyte string starting at +.IR s , +extracts the next complete +multibyte character, converts it to a wide character and stores it at +.IR *pwc . +It updates the shift state +.IR *ps . +If the converted wide +character is not L\(aq\\0\(aq (the null wide character), +it returns the number of bytes that were consumed +from +.IR s . +If the converted wide character is L\(aq\\0\(aq, it resets the shift +state +.I *ps +to the initial state and returns 0. +.PP +If the +.IR n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mbrtowc () +returns +.IR "(size_t)\ \-2" . +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift +sequences. +.PP +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mbrtowc () +returns +.IR "(size_t)\ \-1" +and sets +.I errno +to +.BR EILSEQ . +In this case, +the effects on +.I *ps +are undefined. +.PP +A different case is when +.IR s +is not NULL but +.I pwc +is NULL. +In this case, the +.BR mbrtowc () +function behaves as above, except that it does not +store the converted wide character in memory. +.PP +A third case is when +.I s +is NULL. +In this case, +.IR pwc +and +.I n +are +ignored. +If the conversion state represented by +.I *ps +denotes an +incomplete multibyte character conversion, the +.BR mbrtowc () +function +returns +.IR "(size_t)\ \-1" , +sets +.I errno +to +.BR EILSEQ , +and +leaves +.I *ps +in an undefined state. +Otherwise, the +.BR mbrtowc () +function +puts +.I *ps +in the initial state and returns 0. +.PP +In all of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbrtowc () +function is used instead. +Otherwise, +.IR *ps +must be a valid +.I mbstate_t +object. +An +.IR mbstate_t +object +.I a +can be initialized to the initial state +by zeroing it, for example using +.PP +.in +4n +.EX +memset(&a, 0, sizeof(a)); +.EE +.in +.SH RETURN VALUE +The +.BR mbrtowc () +function returns the number of bytes parsed from the +multibyte sequence starting at +.IR s , +if a non-L\(aq\\0\(aq wide character +was recognized. +It returns 0, if a L\(aq\\0\(aq wide character was recognized. +It returns +.I (size_t)\ \-1 +and sets +.I errno +to +.BR EILSEQ , +if an invalid multibyte sequence was +encountered. +It returns +.I "(size_t)\ \-2" +if it couldn't parse a complete multibyte +character, meaning that +.I n +should be increased. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mbrtowc () +T} Thread safety MT-Unsafe race:mbrtowc/!ps +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR mbrtowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbsinit (3), +.BR mbsrtowcs (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mbsinit.3 b/man3/mbsinit.3 new file mode 100644 index 0000000..c38a4b0 --- /dev/null +++ b/man3/mbsinit.3 @@ -0,0 +1,123 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBSINIT 3 2016-10-08 "GNU" "Linux Programmer's Manual" +.SH NAME +mbsinit \- test for initial shift state +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mbsinit(const mbstate_t *" ps ); +.fi +.SH DESCRIPTION +Character conversion between the multibyte representation and the wide +character representation uses conversion state, of type +.IR mbstate_t . +Conversion of a string uses a finite-state machine; when it is interrupted +after the complete conversion of a number of characters, it may need to +save a state for processing the remaining characters. +Such a conversion +state is needed for the sake of encodings such as ISO-2022 and UTF-7. +.PP +The initial state is the state at the beginning of conversion of a string. +There are two kinds of state: the one used by multibyte to wide character +conversion functions, such as +.BR mbsrtowcs (3), +and the one used by wide +character to multibyte conversion functions, such as +.BR wcsrtombs (3), +but they both fit in a +.IR mbstate_t , +and they both have the same +representation for an initial state. +.PP +For 8-bit encodings, all states are equivalent to the initial state. +For multibyte encodings like UTF-8, EUC-*, BIG5 or SJIS, the wide character +to multibyte conversion functions never produce non-initial states, but the +multibyte to wide-character conversion functions like +.BR mbrtowc (3) +do +produce non-initial states when interrupted in the middle of a character. +.PP +One possible way to create an +.I mbstate_t +in initial state is to set it to zero: +.PP +.in +4n +.EX +mbstate_t state; +memset(&state,0,sizeof(mbstate_t)); +.EE +.in +.PP +On Linux, the following works as well, but might generate compiler warnings: +.PP +.in +4n +.EX +mbstate_t state = { 0 }; +.EE +.in +.PP +The function +.BR mbsinit () +tests whether +.I *ps +corresponds to an +initial state. +.SH RETURN VALUE +.BR mbsinit () +returns nonzero if +.I *ps +is an initial state, or if +.I ps +is NULL. +Otherwise, it returns 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mbsinit () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR mbsinit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbrlen (3), +.BR mbrtowc (3), +.BR mbsrtowcs (3), +.BR wcrtomb (3), +.BR wcsrtombs (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mbsnrtowcs.3 b/man3/mbsnrtowcs.3 new file mode 100644 index 0000000..577c14d --- /dev/null +++ b/man3/mbsnrtowcs.3 @@ -0,0 +1,209 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH MBSNRTOWCS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +mbsnrtowcs \- convert a multibyte string to a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t mbsnrtowcs(wchar_t *" dest ", const char **" src , +.BI " size_t " nms ", size_t " len ", mbstate_t *" ps ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mbsnrtowcs (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR mbsnrtowcs () +function is like the +.BR mbsrtowcs (3) +function, except that +the number of bytes to be converted, starting at +.IR *src , +is limited to at most +.IR nms +bytes. +.PP +If +.I dest +is not NULL, the +.BR mbsnrtowcs () +function converts at +most +.I nms +bytes from the +multibyte string +.I *src +to a wide-character string starting at +.IR dest . +At most +.I len +wide characters are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.I "mbrtowc(dest, *src, n, ps)" +where +.I n +is some +positive number, as long as this call succeeds, and then incrementing +.I dest +by one and +.I *src +by the number of bytes consumed. +The +conversion can stop for three reasons: +.IP 1. 3 +An invalid multibyte sequence has been encountered. +In this case, +.I *src +is left pointing to the invalid multibyte sequence, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP 2. +The +.I nms +limit forces a stop, +or +.I len +non-L\(aq\\0\(aq wide characters +have been stored at +.IR dest . +In this case, +.I *src +is left pointing to the +next multibyte sequence to be converted, and the number of wide characters +written to +.I dest +is returned. +.IP 3. +The multibyte string has been completely converted, including the +terminating null wide character (\(aq\\0\(aq) +(which has the side effect of bringing back +.I *ps +to the +initial state). +In this case, +.I *src +is set to NULL, and the number of wide +characters written to +.IR dest , +excluding the terminating null wide character, +is returned. +.PP +According to POSIX.1, +if the input buffer ends with an incomplete character, +it is unspecified whether conversion stops at the end of +the previous character (if any), or at the end of the input buffer. +The glibc implementation adopts the former behavior. +.PP +If +.IR dest +is NULL, +.I len +is ignored, and the conversion proceeds as +above, except that the converted wide characters +are not written out to memory, +and that no destination length limit exists. +.PP +In both of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbsnrtowcs () +function is used instead. +.PP +The programmer must ensure that there is room for at least +.I len +wide +characters at +.IR dest . +.SH RETURN VALUE +The +.BR mbsnrtowcs () +function returns the number of wide characters +that make up the converted part of the wide-character string, +not including the terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw29 +l l l. +Interface Attribute Value +T{ +.BR mbsnrtowcs () +T} Thread safety MT-Unsafe race:mbsnrtowcs/!ps +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2008. +.SH NOTES +The behavior of +.BR mbsnrtowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbrtowc (3) +.BR mbsinit (3), +.BR mbsrtowcs (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3 new file mode 100644 index 0000000..143b402 --- /dev/null +++ b/man3/mbsrtowcs.3 @@ -0,0 +1,166 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBSRTOWCS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +mbsrtowcs \- convert a multibyte string to a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t mbsrtowcs(wchar_t *" dest ", const char **" src , +.BI " size_t " len ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, the +.BR mbsrtowcs () +function converts the +multibyte string +.I *src +to a wide-character string starting at +.IR dest . +At most +.I len +wide characters are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.I "mbrtowc(dest, *src, n, ps)" +where +.I n +is some +positive number, as long as this call succeeds, and then incrementing +.I dest +by one and +.I *src +by the number of bytes consumed. +The conversion can stop for three reasons: +.IP 1. 3 +An invalid multibyte sequence has been encountered. +In this case, +.I *src +is left pointing to the invalid multibyte sequence, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP 2. +.I len +non-L\(aq\\0\(aq wide characters have been stored at +.IR dest . +In this case, +.I *src +is left pointing to the next +multibyte sequence to be converted, +and the number of wide characters written to +.I dest +is returned. +.IP 3. +The multibyte string has been completely converted, including the +terminating null wide character (\(aq\\0\(aq), which has the side +effect of bringing back +.I *ps +to the +initial state. +In this case, +.I *src +is set to NULL, and the number of wide +characters written to +.IR dest , +excluding the terminating null wide character, is returned. +.PP +If +.IR dest +is NULL, +.I len +is ignored, +and the conversion proceeds as above, +except that the converted wide characters are not written out to memory, +and that no length limit exists. +.PP +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbsrtowcs () +function is used instead. +.PP +The programmer must ensure that there is room for at least +.I len +wide +characters at +.IR dest . +.SH RETURN VALUE +The +.BR mbsrtowcs () +function returns the number of wide characters that make +up the converted part of the wide-character string, not including the +terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw28 +l l l. +Interface Attribute Value +T{ +.BR mbsrtowcs () +T} Thread safety MT-Unsafe race:mbsrtowcs/!ps +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR mbsrtowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbrtowc (3), +.BR mbsinit (3), +.BR mbsnrtowcs (3), +.BR mbstowcs (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mbstowcs.3 b/man3/mbstowcs.3 new file mode 100644 index 0000000..5c9e192 --- /dev/null +++ b/man3/mbstowcs.3 @@ -0,0 +1,245 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright (c) Bruno Haible +.\" and Copyright 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBSTOWCS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +mbstowcs \- convert a multibyte string to a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +the +.BR mbstowcs () +function converts the +multibyte string +.I src +to a wide-character string starting at +.IR dest . +At most +.I n +wide characters are written to +.IR dest . +The sequence of characters in the string +.I src +shall begin in the initial shift state. +The conversion can stop for three reasons: +.IP 1. 3 +An invalid multibyte sequence has been encountered. +In this case, +.I (size_t)\ \-1 +is returned. +.IP 2. +.I n +non-L\(aq\\0\(aq wide characters have been stored at +.IR dest . +In this case, the number of wide characters written to +.I dest +is returned, but the +shift state at this point is lost. +.IP 3. +The multibyte string has been completely converted, including the +terminating null character (\(aq\\0\(aq). +In this case, the number of wide characters written to +.IR dest , +excluding the terminating null wide character, is returned. +.PP +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.PP +If +.IR dest +is NULL, +.I n +is ignored, and the conversion proceeds as +above, except that the converted wide characters are not written out to memory, +and that no length limit exists. +.PP +In order to avoid the case 2 above, the programmer should make sure +.I n +is +greater than or equal to +.IR "mbstowcs(NULL,src,0)+1" . +.SH RETURN VALUE +The +.BR mbstowcs () +function returns the number of wide characters that make +up the converted part of the wide-character string, not including the +terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mbstowcs () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR mbstowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +The function +.BR mbsrtowcs (3) +provides a better interface to the same +functionality. +.SH EXAMPLE +The program below illustrates the use of +.BR mbstowcs (), +as well as some of the wide character classification functions. +An example run is the following: +.PP +.in +4n +.EX +$ ./t_mbstowcs de_DE.UTF\-8 Grüße! +Length of source string (excluding terminator): + 8 bytes + 6 multibyte characters + +Wide character string is: Grüße! (6 characters) + G alpha upper + r alpha lower + ü alpha lower + ß alpha lower + e alpha lower + ! !alpha +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + size_t mbslen; /* Number of multibyte characters in source */ + wchar_t *wcs; /* Pointer to converted wide character string */ + wchar_t *wp; + + if (argc < 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* Apply the specified locale */ + + if (setlocale(LC_ALL, argv[1]) == NULL) { + perror("setlocale"); + exit(EXIT_FAILURE); + } + + /* Calculate the length required to hold argv[2] converted to + a wide character string */ + + mbslen = mbstowcs(NULL, argv[2], 0); + if (mbslen == (size_t) \-1) { + perror("mbstowcs"); + exit(EXIT_FAILURE); + } + + /* Describe the source string to the user */ + + printf("Length of source string (excluding terminator):\\n"); + printf(" %zu bytes\\n", strlen(argv[2])); + printf(" %zu multibyte characters\\n\\n", mbslen); + + /* Allocate wide character string of the desired size. Add 1 + to allow for terminating null wide character (L\(aq\\0\(aq). */ + + wcs = calloc(mbslen + 1, sizeof(wchar_t)); + if (wcs == NULL) { + perror("calloc"); + exit(EXIT_FAILURE); + } + + /* Convert the multibyte character string in argv[2] to a + wide character string */ + + if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) { + perror("mbstowcs"); + exit(EXIT_FAILURE); + } + + printf("Wide character string is: %ls (%zu characters)\\n", + wcs, mbslen); + + /* Now do some inspection of the classes of the characters in + the wide character string */ + + for (wp = wcs; *wp != 0; wp++) { + printf(" %lc ", (wint_t) *wp); + + if (!iswalpha(*wp)) + printf("!"); + printf("alpha "); + + if (iswalpha(*wp)) { + if (iswupper(*wp)) + printf("upper "); + + if (iswlower(*wp)) + printf("lower "); + } + + putchar(\(aq\\n\(aq); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR mblen (3), +.BR mbsrtowcs (3), +.BR mbtowc (3), +.BR wcstombs (3), +.BR wctomb (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mbtowc.3 b/man3/mbtowc.3 new file mode 100644 index 0000000..c8805e2 --- /dev/null +++ b/man3/mbtowc.3 @@ -0,0 +1,155 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH MBTOWC 3 2016-10-08 "GNU" "Linux Programmer's Manual" +.SH NAME +mbtowc \- convert a multibyte sequence to a wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mbtowc(wchar_t *" pwc ", const char *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The main case for this function is when +.IR s +is not NULL and +.I pwc +is +not NULL. +In this case, the +.BR mbtowc () +function inspects at most +.I n +bytes of the multibyte string starting at +.IR s , +extracts the next complete +multibyte character, converts it to a wide character and stores it at +.IR *pwc . +It updates an internal shift state known only to the +.BR mbtowc () +function. +If +.I s +does not point to a null byte (\(aq\\0\(aq), it returns the number +of bytes that were consumed from +.IR s , +otherwise it returns 0. +.PP +If the +.IR n +bytes starting at +.I s +do not contain a complete multibyte +character, or if they contain an invalid multibyte sequence, +.BR mbtowc () +returns \-1. +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift sequences. +.PP +A different case is when +.IR s +is not NULL but +.I pwc +is NULL. +In this case, the +.BR mbtowc () +function behaves as above, except that it does not +store the converted wide character in memory. +.PP +A third case is when +.I s +is NULL. +In this case, +.IR pwc +and +.I n +are +ignored. +The +.BR mbtowc () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, only known to this function, +to the initial state, and +returns nonzero if the encoding has nontrivial shift state, or zero if the +encoding is stateless. +.SH RETURN VALUE +If +.I s +is not NULL, the +.BR mbtowc () +function returns the number of +consumed bytes starting at +.IR s , +or 0 if +.I s +points to a null byte, +or \-1 upon failure. +.PP +If +.I s +is NULL, the +.BR mbtowc () +function +returns nonzero if the encoding +has nontrivial shift state, or zero if the encoding is stateless. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mbtowc () +T} Thread safety MT-Unsafe race +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR mbtowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +This function is not multithread safe. +The function +.BR mbrtowc (3) +provides +a better interface to the same functionality. +.SH SEE ALSO +.BR MB_CUR_MAX (3), +.BR mblen (3), +.BR mbrtowc (3), +.BR mbstowcs (3), +.BR wcstombs (3), +.BR wctomb (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mcheck.3 b/man3/mcheck.3 new file mode 100644 index 0000000..786817f --- /dev/null +++ b/man3/mcheck.3 @@ -0,0 +1,237 @@ +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MCHECK 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +mcheck, mcheck_check_all, mcheck_pedantic, mprobe \- heap consistency checking +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mcheck(void (*" abortfunc ")(enum mcheck_status " mstatus )); +.PP +.BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus )); +.PP +.B void mcheck_check_all(void); +.PP +.BI "enum mcheck_status mprobe(void *" ptr ); +.fi +.SH DESCRIPTION +The +.BR mcheck () +function installs a set of debugging hooks for the +.BR malloc (3) +family of memory-allocation functions. +These hooks cause certain consistency checks to be performed +on the state of the heap. +The checks can detect application errors such as freeing a block of memory +more than once or corrupting the bookkeeping data structures +that immediately precede a block of allocated memory. +.PP +To be effective, the +.BR mcheck () +function must be called before the first call to +.BR malloc (3) +or a related function. +In cases where this is difficult to ensure, linking the program with +.IR \-lmcheck +inserts an implicit call to +.BR mcheck () +(with a NULL argument) +before the first call to a memory-allocation function. +.PP +The +.BR mcheck_pedantic () +function is similar to +.BR mcheck (), +but performs checks on all allocated blocks whenever +one of the memory-allocation functions is called. +This can be very slow! +.PP +The +.BR mcheck_check_all () +function causes an immediate check on all allocated blocks. +This call is effective only if +.BR mcheck () +is called beforehand. +.PP +If the system detects an inconsistency in the heap, +the caller-supplied function pointed to by +.I abortfunc +is invoked with a single argument, +.IR mstatus , +that indicates what type of inconsistency was detected. +If +.I abortfunc +is NULL, a default function prints an error message on +.IR stderr +and calls +.BR abort (3). +.PP +The +.BR mprobe () +function performs a consistency check on +the block of allocated memory pointed to by +.IR ptr . +The +.BR mcheck () +function should be called beforehand (otherwise +.BR mprobe () +returns +.BR MCHECK_DISABLED ). +.PP +The following list describes the values returned by +.BR mprobe () +or passed as the +.I mstatus +argument when +.I abortfunc +is invoked: +.TP +.BR MCHECK_DISABLED " (" mprobe "() only)" +.BR mcheck () +was not called before the first memory allocation function was called. +Consistency checking is not possible. +.TP +.BR MCHECK_OK " (" mprobe "() only)" +No inconsistency detected. +.TP +.B MCHECK_HEAD +Memory preceding an allocated block was clobbered. +.TP +.B MCHECK_TAIL +Memory following an allocated block was clobbered. +.TP +.B +MCHECK_FREE +A block of memory was freed twice. +.SH RETURN VALUE +.BR mcheck () +and +.BR mcheck_pedantic () +return 0 on success, or \-1 on error. +.SH VERSIONS +The +.BR mcheck_pedantic () +and +.BR mcheck_check_all () +functions are available since glibc 2.2. +The +.BR mcheck () +and +.BR mprobe () +functions are present since at least glibc 2.0 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lbw21 +l l l. +Interface Attribute Value +T{ +.BR mcheck (), +.BR mcheck_pedantic (), +.br +.BR mcheck_check_all (), +.BR mprobe () +T} Thread safety T{ +MT-Unsafe race:mcheck +.br +const:malloc_hooks +T} +.TE +.sp 1 +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +Linking a program with +.I \-lmcheck +and using the +.B MALLOC_CHECK_ +environment variable (described in +.BR mallopt (3)) +cause the same kinds of errors to be detected. +But, using +.B MALLOC_CHECK_ +does not require the application to be relinked. +.\" But is MALLOC_CHECK_ slower? +.SH EXAMPLE +The program below calls +.BR mcheck () +with a NULL argument and then frees the same block of memory twice. +The following shell session demonstrates what happens +when running the program: +.PP +.in +4n +.EX +.RB "$" " ./a.out" +About to free + +About to free a second time +block freed twice +Aborted (core dumped) +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + char *p; + + if (mcheck(NULL) != 0) { + fprintf(stderr, "mcheck() failed\\n"); + + exit(EXIT_FAILURE); + } + + p = malloc(1000); + + fprintf(stderr, "About to free\\n"); + free(p); + fprintf(stderr, "\\nAbout to free a second time\\n"); + free(p); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR malloc (3), +.BR mallopt (3), +.BR mtrace (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mcheck_check_all.3 b/man3/mcheck_check_all.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man3/mcheck_check_all.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man3/mcheck_pedantic.3 b/man3/mcheck_pedantic.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man3/mcheck_pedantic.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man3/memalign.3 b/man3/memalign.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man3/memalign.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man3/memccpy.3 b/man3/memccpy.3 new file mode 100644 index 0000000..6efdd76 --- /dev/null +++ b/man3/memccpy.3 @@ -0,0 +1,99 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:57:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMCCPY 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +memccpy \- copy memory area +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *memccpy(void *" dest ", const void *" src ", int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memccpy () +function copies no more than +.I n +bytes from +memory area +.I src +to memory area +.IR dest , +stopping when the +character +.I c +is found. +.PP +If the memory areas overlap, the results are undefined. +.SH RETURN VALUE +The +.BR memccpy () +function returns a pointer to the next character +in +.IR dest +after +.IR c , +or NULL if +.I c +was not found in the +first +.I n +characters of +.IR src . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR memccpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3), +.BR strncpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/memchr.3 b/man3/memchr.3 new file mode 100644 index 0000000..455ba56 --- /dev/null +++ b/man3/memchr.3 @@ -0,0 +1,170 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Mon Apr 12 12:49:57 1993, David Metcalfe +.\" Modified Sat Jul 24 18:56:22 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Feb 20 21:09:36 2002, Ian Redfern (redferni@logica.com) +.\" 2008-07-09, mtk, add rawmemchr() +.\" +.TH MEMCHR 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +memchr, memrchr, rawmemchr \- scan memory for a character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *memchr(const void *" s ", int " c ", size_t " n ); +.PP +.BI "void *memrchr(const void *" s ", int " c ", size_t " n ); +.PP +.BI "void *rawmemchr(const void *" s ", int " c ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR memrchr (), +.BR rawmemchr (): +_GNU_SOURCE +.SH DESCRIPTION +The +.BR memchr () +function scans the initial +.I n +bytes of the memory +area pointed to by +.I s +for the first instance of +.IR c . +Both +.I c +and the bytes of the memory area pointed to by +.I s +are interpreted as +.IR "unsigned char" . +.PP +The +.BR memrchr () +function is like the +.BR memchr () +function, +except that it searches backward from the end of the +.I n +bytes pointed to by +.I s +instead of forward from the beginning. +.PP +The +.BR rawmemchr () +function is similar to +.BR memchr (): +it assumes (i.e., the programmer knows for certain) +that an instance of +.I c +lies somewhere in the memory area starting at the location pointed to by +.IR s , +and so performs an optimized search for +.IR c +(i.e., no use of a count argument to limit the range of the search). +If an instance of +.I c +is not found, the results are unpredictable. +The following call is a fast means of locating a string's +terminating null byte: +.PP +.in +4n +.EX +char *p = rawmemchr(s,\ \(aq\\0\(aq); +.EE +.in +.SH RETURN VALUE +The +.BR memchr () +and +.BR memrchr () +functions return a pointer +to the matching byte or NULL if the character does not occur in +the given memory area. +.PP +The +.BR rawmemchr () +function returns a pointer to the matching byte, if one is found. +If no matching byte is found, the result is unspecified. +.SH VERSIONS +.BR rawmemchr () +first appeared in glibc in version 2.1. +.PP +.BR memrchr () +first appeared in glibc in version 2.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw32 lb lb +l l l. +Interface Attribute Value +T{ +.BR memchr (), +.BR memrchr (), +.BR rawmemchr () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR memchr (): +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.PP +The +.BR memrchr () +function is a GNU extension, available since glibc 2.1.91. +.PP +The +.BR rawmemchr () +function is a GNU extension, available since glibc 2.1. +.SH SEE ALSO +.BR bstring (3), +.BR ffs (3), +.BR index (3), +.BR memmem (3), +.BR rindex (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR wmemchr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/memcmp.3 b/man3/memcmp.3 new file mode 100644 index 0000000..9018081 --- /dev/null +++ b/man3/memcmp.3 @@ -0,0 +1,106 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMCMP 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +memcmp \- compare memory areas +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int memcmp(const void *" s1 ", const void *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memcmp () +function compares the first \fIn\fP bytes (each interpreted as +.IR "unsigned char" ) +of the memory areas \fIs1\fP and \fIs2\fP. +.SH RETURN VALUE +The +.BR memcmp () +function returns an integer less than, equal to, or +greater than zero if the first \fIn\fP bytes of \fIs1\fP is found, +respectively, to be less than, to match, or be greater than the first +\fIn\fP bytes of \fIs2\fP. +.PP +For a nonzero return value, the sign is determined by the sign of +the difference between the first pair of bytes (interpreted as +.IR "unsigned char" ) +that differ in +.I s1 +and +.IR s2 . +.PP +If +.I n +is zero, the return value is zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR memcmp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +.PP +Do not use +.BR memcmp () +to compare security critical data, such as cryptographic secrets, +because the required CPU time depends on the number of equal bytes. +Instead, a function that performs comparisons in constant time is required. +Some operating systems provide such a function (e.g., NetBSD's +.BR consttime_memequal ()), +but no such function is specified in POSIX. +On Linux, it may be necessary to implement such a function oneself. +.SH SEE ALSO +.BR bcmp (3), +.BR bstring (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strncasecmp (3), +.BR strncmp (3), +.BR wmemcmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/memcpy.3 b/man3/memcpy.3 new file mode 100644 index 0000000..b0dec3c --- /dev/null +++ b/man3/memcpy.3 @@ -0,0 +1,126 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:09 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMCPY 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +memcpy \- copy memory area +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *memcpy(void *" dest ", const void *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memcpy () +function copies \fIn\fP bytes from memory area +\fIsrc\fP to memory area \fIdest\fP. +The memory areas must not overlap. +Use +.BR memmove (3) +if the memory areas do overlap. +.SH RETURN VALUE +The +.BR memcpy () +function returns a pointer to \fIdest\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR memcpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +Failure to observe the requirement that the memory areas +do not overlap has been the source of significant bugs. +(POSIX and the C standards are explicit that employing +.BR memcpy () +with overlapping areas produces undefined behavior.) +Most notably, in glibc 2.13 +.\" glibc commit 6fb8cbcb58a29fff73eb2101b34caa19a7f88eba +a performance optimization of +.BR memcpy () +on some platforms (including x86-64) included changing the order +.\" From forward copying to backward copying +in which bytes were copied from +.I src +to +.IR dest . +.PP +This change revealed breakages in a number of applications that performed +copying with overlapping areas. +.\" Adobe Flash player was the highest profile example: +.\" https://bugzilla.redhat.com/show_bug.cgi?id=638477 +.\" Reported: 2010-09-29 02:35 EDT by JCHuynh +.\" Bug 638477 - Strange sound on mp3 flash website +.\" +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=12518 +.\" Bug 12518 - memcpy acts randomly (and differently) with overlapping areas +.\" Reported: 2011-02-25 02:26 UTC by Linus Torvalds +.\" +Under the previous implementation, +the order in which the bytes were copied had fortuitously hidden the bug, +which was revealed when the copying order was reversed. +In glibc 2.14, +.\" glibc commit 0354e355014b7bfda32622e0255399d859862fcd +a versioned symbol was added so that old binaries +(i.e., those linked against glibc versions earlier than 2.14) +employed a +.BR memcpy () +implementation that safely handles the overlapping buffers case +(by providing an "older" +.BR memcpy () +implementation that was aliased to +.BR memmove (3)). +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memccpy (3), +.BR memmove (3), +.BR mempcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wmemcpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/memfrob.3 b/man3/memfrob.3 new file mode 100644 index 0000000..98d6b89 --- /dev/null +++ b/man3/memfrob.3 @@ -0,0 +1,86 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:54:45 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMFROB 3 2017-03-13 "GNU" "Linux Programmer's Manual" +.SH NAME +memfrob \- frobnicate (encrypt) a memory area +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void *memfrob(void *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memfrob () +function encrypts the first \fIn\fP bytes of the +memory area \fIs\fP by exclusive-ORing each character with the number +42. +The effect can be reversed by using +.BR memfrob () +on the +encrypted memory area. +.PP +Note that this function is not a proper encryption routine as the XOR +constant is fixed, and is suitable only for hiding strings. +.SH RETURN VALUE +The +.BR memfrob () +function returns a pointer to the encrypted memory +area. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR memfrob () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The +.BR memfrob () +function is unique to the +GNU C Library. +.SH SEE ALSO +.BR bstring (3), +.BR strfry (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/memmem.3 b/man3/memmem.3 new file mode 100644 index 0000000..9d9e10b --- /dev/null +++ b/man3/memmem.3 @@ -0,0 +1,110 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:50:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" Interchanged 'needle' and 'haystack'; added history, aeb, 980113. +.TH MEMMEM 3 2017-03-13 "GNU" "Linux Programmer's Manual" +.SH NAME +memmem \- locate a substring +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void *memmem(const void *" haystack ", size_t " haystacklen , +.BI " const void *" needle ", size_t " needlelen ); +.fi +.SH DESCRIPTION +The +.BR memmem () +function finds the start of the first occurrence +of the substring +.IR needle +of length +.I needlelen +in the memory +area +.I haystack +of length +.IR haystacklen . +.SH RETURN VALUE +The +.BR memmem () +function returns a pointer to the beginning of the +substring, or NULL if the substring is not found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR memmem () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is not specified in POSIX.1, +but is present on a number of other systems. +.SH BUGS +.\" This function was broken in Linux libraries up to and including libc 5.0.9; +.\" there the +.\" .IR needle +.\" and +.\" .I haystack +.\" arguments were interchanged, +.\" and a pointer to the end of the first occurrence of +.\" .I needle +.\" was returned. +.\" +.\" Both old and new libc's have the bug that if +.\" .I needle +.\" is empty, +.\" .I haystack\-1 +.\" (instead of +.\" .IR haystack ) +.\" is returned. +In glibc 2.0, if +.I needle +is empty, +.BR memmem () +returns a pointer to the last byte of +.IR haystack . +This is fixed in glibc 2.1. +.SH SEE ALSO +.BR bstring (3), +.BR strstr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/memmove.3 b/man3/memmove.3 new file mode 100644 index 0000000..4486b43 --- /dev/null +++ b/man3/memmove.3 @@ -0,0 +1,92 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:49:59 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMMOVE 3 2017-03-13 "GNU" "Linux Programmer's Manual" +.SH NAME +memmove \- copy memory area +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *memmove(void *" dest ", const void *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memmove () +function copies +.I n +bytes from memory area +.I src +to memory area +.IR dest . +The memory areas may overlap: copying takes place as though +the bytes in +.I src +are first copied into a temporary array that does not overlap +.I src +or +.IR dest , +and the bytes are then copied from the temporary array to +.IR dest . +.SH RETURN VALUE +The +.BR memmove () +function returns a pointer to +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR memmove () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memccpy (3), +.BR memcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wmemmove (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mempcpy.3 b/man3/mempcpy.3 new file mode 100644 index 0000000..df3824c --- /dev/null +++ b/man3/mempcpy.3 @@ -0,0 +1,97 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Heavily based on glibc infopages, copyright Free Software Foundation +.\" +.\" aeb, 2003, polished a little +.TH MEMPCPY 3 2015-03-02 "GNU" "Linux Programmer's Manual" +.SH NAME +mempcpy, wmempcpy \- copy memory area +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void *mempcpy(void *" dest ", const void *" src ", size_t " n ); + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "wchar_t *wmempcpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR mempcpy () +function is nearly identical to the +.BR memcpy (3) +function. +It copies +.I n +bytes from the object beginning at +.I src +into the object pointed to by +.IR dest . +But instead of returning the value of +.I dest +it returns a pointer to the byte following the last written byte. +.PP +This function is useful in situations where a number of objects +shall be copied to consecutive memory positions. +.PP +The +.BR wmempcpy () +function is identical but takes +.I wchar_t +type arguments and copies +.I n +wide characters. +.SH RETURN VALUE +.I dest ++ +.IR n . +.SH VERSIONS +.BR mempcpy () +first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR mempcpy (), +.BR wmempcpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is a GNU extension. +.SH EXAMPLE +.EX +void * +combine(void *o1, size_t s1, void *o2, size_t s2) +{ + void *result = malloc(s1 + s2); + if (result != NULL) + mempcpy(mempcpy(result, o1, s1), o2, s2); + return result; +} +.EE +.SH SEE ALSO +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR wmemcpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/memrchr.3 b/man3/memrchr.3 new file mode 100644 index 0000000..b62c8f1 --- /dev/null +++ b/man3/memrchr.3 @@ -0,0 +1 @@ +.so man3/memchr.3 diff --git a/man3/memset.3 b/man3/memset.3 new file mode 100644 index 0000000..2d6bf61 --- /dev/null +++ b/man3/memset.3 @@ -0,0 +1,81 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:49:23 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEMSET 3 2017-03-13 "GNU" "Linux Programmer's Manual" +.SH NAME +memset \- fill memory with a constant byte +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *memset(void *" s ", int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memset () +function fills the first +.I n +bytes of the +memory area pointed to by +.I s +with the constant byte +.IR c . +.SH RETURN VALUE +The +.BR memset () +function returns a pointer to the memory area +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR memset () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bstring (3), +.BR bzero (3), +.BR swab (3), +.BR wmemset (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/minor.3 b/man3/minor.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man3/minor.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man3/mkdtemp.3 b/man3/mkdtemp.3 new file mode 100644 index 0000000..2b8436f --- /dev/null +++ b/man3/mkdtemp.3 @@ -0,0 +1,119 @@ +.\" Copyright 2001 John Levon +.\" Based on mkstemp(3), Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and GNU libc documentation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.TH MKDTEMP 3 2016-07-17 "GNU" "Linux Programmer's Manual" +.SH NAME +mkdtemp \- create a unique temporary directory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *mkdtemp(char *" template ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mkdtemp (): +.br +.ad l +.RS 4 +.PD 0 +/* Since glibc 2.19: */ _DEFAULT_SOURCE +.br +|| /* Glibc 2.19 and earlier: */ _BSD_SOURCE +.br +|| /* Since glibc 2.10: */ +_POSIX_C_SOURCE\ >=\ 200809L +.ad +.PD +.RE +.SH DESCRIPTION +The +.BR mkdtemp () +function generates a uniquely named temporary +directory from \fItemplate\fP. +The last six characters of \fItemplate\fP +must be XXXXXX and these are replaced with a string that makes the +directory name unique. +The directory is then created with +permissions 0700. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.SH RETURN VALUE +The +.BR mkdtemp () +function returns a pointer to the modified template +string on success, and NULL on failure, in which case +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +Now \fItemplate\fP is unchanged. +.PP +Also see +.BR mkdir (2) +for other possible values for \fIerrno\fP. +.SH VERSIONS +Available since glibc 2.1.91. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mkdtemp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2008. +This function is present on the BSDs. +.\" As at 2006, this function is being considered for a revision of POSIX.1 +.\" Also in NetBSD 1.4. +.SH SEE ALSO +.BR mktemp (1), +.BR mkdir (2), +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mkfifo.3 b/man3/mkfifo.3 new file mode 100644 index 0000000..c7781eb --- /dev/null +++ b/man3/mkfifo.3 @@ -0,0 +1,220 @@ +.\" This manpage is Copyright (C) 1995 James R. Van Zandt +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" changed section from 2 to 3, aeb, 950919 +.\" +.TH MKFIFO 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +mkfifo, mkfifoat \- make a FIFO special file (a named pipe) +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int mkfifo(const char *" pathname ", mode_t " mode ); + +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.PP +.BI "int mkfifoat(int " dirfd ", const char *" pathname ", mode_t " mode ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mkfifoat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +.BR mkfifo () +makes a FIFO special file with name \fIpathname\fP. +\fImode\fP specifies the FIFO's permissions. +It is modified by the +process's \fBumask\fP in the usual way: the permissions of the created +file are \fB(\fP\fImode\fP\fB & ~umask)\fP. +.PP +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 filesystem by +calling +.BR mkfifo (). +.PP +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. +See +.BR fifo (7) +for nonblocking handling of FIFO special files. +.SS mkfifoat() +The +.BR mkfifoat () +function operates in exactly the same way as +.BR mkfifo (), +except for the differences described here. +.PP +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR mkfifo () +for a relative pathname). +.PP +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR mkfifo ()). +.PP +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.SH RETURN VALUE +On success +.BR mkfifo () +and +.BR mkfifoat () +return 0. +In the case of an error, \-1 is returned (in which case, \fIerrno\fP +is set appropriately). +.SH ERRORS +.TP +.B EACCES +One of the directories in \fIpathname\fP did not allow search +(execute) permission. +.TP +.B EDQUOT +The user's quota of disk blocks or inodes on the filesystem has been +exhausted. +.TP +.B EEXIST +\fIpathname\fP already exists. +This includes the case where +.I pathname +is a symbolic link, dangling or not. +.TP +.B ENAMETOOLONG +Either the total length of \fIpathname\fP is greater than +\fBPATH_MAX\fP, or an individual filename component has a length +greater than \fBNAME_MAX\fP. +In the GNU system, there is no imposed +limit on overall filename length, but some filesystems may place +limits on the length of a component. +.TP +.B ENOENT +A directory component in \fIpathname\fP does not exist or is a +dangling symbolic link. +.TP +.B ENOSPC +The directory or filesystem has no room for the new file. +.TP +.B ENOTDIR +A component used as a directory in \fIpathname\fP is not, in fact, a +directory. +.TP +.B EROFS +\fIpathname\fP refers to a read-only filesystem. +.PP +The following additional errors can occur for +.BR mkfifoat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I pathname +is a relative path and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR mkfifoat () +was added to glibc in version 2.4. +It is implemented using +.BR mknodat (2), +available on Linux since kernel 2.6.16. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR mkfifo (), +.BR mkfifoat () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR mkfifo (): +POSIX.1-2001, POSIX.1-2008. +.PP +.BR mkfifoat (): +POSIX.1-2008. +.SH SEE ALSO +.BR mkfifo (1), +.BR close (2), +.BR open (2), +.BR read (2), +.BR stat (2), +.BR umask (2), +.BR write (2), +.BR fifo (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mkfifoat.3 b/man3/mkfifoat.3 new file mode 100644 index 0000000..25f4896 --- /dev/null +++ b/man3/mkfifoat.3 @@ -0,0 +1 @@ +.so man3/mkfifo.3 diff --git a/man3/mkostemp.3 b/man3/mkostemp.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man3/mkostemp.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man3/mkostemps.3 b/man3/mkostemps.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man3/mkostemps.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man3/mkstemp.3 b/man3/mkstemp.3 new file mode 100644 index 0000000..462dd35 --- /dev/null +++ b/man3/mkstemp.3 @@ -0,0 +1,264 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2008, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:48:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 980310, aeb +.\" Modified 990328, aeb +.\" 2008-06-19, mtk, Added mkostemp(); various other changes +.\" +.TH MKSTEMP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +mkstemp, mkostemp, mkstemps, mkostemps \- create a unique temporary file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mkstemp(char *" template ); +.PP +.BI "int mkostemp(char *" template ", int " flags ); +.PP +.BI "int mkstemps(char *" template ", int " suffixlen ); +.PP +.BI "int mkostemps(char *" template ", int " suffixlen ", int " flags ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mkstemp (): +.ad l +.RS 4 +.PD 0 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.PD +.RE +.ad b +.PP +.BR mkostemp (): +_GNU_SOURCE +.br +.BR mkstemps (): + /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.br +.BR mkostemps (): +_GNU_SOURCE +.SH DESCRIPTION +The +.BR mkstemp () +function generates a unique temporary filename from +.IR template , +creates and opens the file, +and returns an open file descriptor for the file. +.PP +The last six characters of +.I template +must be "XXXXXX" and these are replaced with a string that makes the +filename unique. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.PP +The file is created with +permissions 0600, that is, read plus write for owner only. +The returned file descriptor provides both read and write access to the file. +The file is opened with the +.BR open (2) +.B O_EXCL +flag, guaranteeing that the caller is the process that creates the file. +.PP +The +.BR mkostemp () +function is like +.BR mkstemp (), +with the difference that the following bits\(emwith the same meaning as for +.BR open (2)\(emmay +be specified in +.IR flags : +.BR O_APPEND , +.BR O_CLOEXEC , +and +.BR O_SYNC . +Note that when creating the file, +.BR mkostemp () +includes the values +.BR O_RDWR , +.BR O_CREAT , +and +.BR O_EXCL +in the +.I flags +argument given to +.BR open (2); +including these values in the +.I flags +argument given to +.BR mkostemp () +is unnecessary, and produces errors on some +.\" Reportedly, FreeBSD +systems. +.PP +The +.BR mkstemps () +function is like +.BR mkstemp (), +except that the string in +.I template +contains a suffix of +.I suffixlen +characters. +Thus, +.I template +is of the form +.IR "prefixXXXXXXsuffix" , +and the string XXXXXX is modified as for +.BR mkstemp (). +.PP +The +.BR mkostemps () +function is to +.BR mkstemps () +as +.BR mkostemp () +is to +.BR mkstemp (). +.SH RETURN VALUE +On success, these functions return the file descriptor +of the temporary file. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EEXIST +Could not create a unique temporary filename. +Now the contents of \fItemplate\fP are undefined. +.TP +.B EINVAL +For +.BR mkstemp () +and +.BR mkostemp (): +The last six characters of \fItemplate\fP were not XXXXXX; +now \fItemplate\fP is unchanged. +.IP +For +.BR mkstemps () +and +.BR mkostemps (): +.I template +is less than +.I "(6 + suffixlen)" +characters long, or the last 6 characters before the suffix in +.I template +were not XXXXXX. +.PP +These functions may also fail with any of the errors described for +.BR open (2). +.SH VERSIONS +.BR mkostemp () +is available since glibc 2.7. +.BR mkstemps () +and +.BR mkostemps () +are available since glibc 2.11. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR mkstemp (), +.BR mkostemp (), +.br +.BR mkstemps (), +.BR mkostemps () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR mkstemp (): +4.3BSD, POSIX.1-2001. +.PP +.BR mkstemps (): +unstandardized, but appears on several other systems. +.\" mkstemps() appears to be at least on the BSDs, Mac OS X, Solaris, +.\" and Tru64. +.PP +.BR mkostemp () +and +.BR mkostemps (): +are glibc extensions. +.SH NOTES +In glibc versions 2.06 and earlier, the file is created with permissions 0666, +that is, read and write for all users. +This old behavior may be +a security risk, especially since other UNIX flavors use 0600, +and somebody might overlook this detail when porting programs. +POSIX.1-2008 adds a requirement that the file be created with mode 0600. +.PP +More generally, the POSIX specification of +.BR mkstemp () +does not say anything +about file modes, so the application should make sure its +file mode creation mask (see +.BR umask (2)) +is set appropriately before calling +.BR mkstemp () +(and +.BR mkostemp ()). +.\" +.\" The prototype for +.\" .BR mkstemp () +.\" is in +.\" .I +.\" for libc4, libc5, glibc1; glibc2 follows POSIX.1 and has the prototype in +.\" .IR . +.SH SEE ALSO +.BR mkdtemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mkstemps.3 b/man3/mkstemps.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man3/mkstemps.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man3/mktemp.3 b/man3/mktemp.3 new file mode 100644 index 0000000..9ccf08b --- /dev/null +++ b/man3/mktemp.3 @@ -0,0 +1,146 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:48:06 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Jun 23 01:26:34 1995 by Andries Brouwer (aeb@cwi.nl) +.\" (prompted by Scott Burkett ) +.\" Modified Sun Mar 28 23:44:38 1999 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH MKTEMP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +mktemp \- make a unique temporary filename +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *mktemp(char *" template ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mktemp (): +.ad l +.PD 0 +.RS 4 +.TP 4 +Since glibc 2.12: +(_XOPEN_SOURCE\ >=\ 500) && ! (_POSIX_C_SOURCE\ >=\ 200112L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.TP +Before glibc 2.12: +_BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.RE +.PD +.ad b +.SH DESCRIPTION +.IR "Never use this function" ; +see BUGS. +.PP +The +.BR mktemp () +function generates a unique temporary filename +from \fItemplate\fP. +The last six characters of \fItemplate\fP must +be XXXXXX and these are replaced with a string that makes the +filename unique. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.SH RETURN VALUE +The +.BR mktemp () +function always returns \fItemplate\fP. +If a unique name was created, the last six bytes of \fItemplate\fP will +have been modified in such a way that the resulting name is unique +(i.e., does not exist already) +If a unique name could not be created, +\fItemplate\fP is made an empty string, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mktemp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.3BSD, POSIX.1-2001. +POSIX.1-2008 removes the specification of +.BR mktemp (). +.\" .SH NOTES +.\" The prototype is in +.\" .I +.\" for libc4, libc5, glibc1; glibc2 follows the Single UNIX Specification +.\" and has the prototype in +.\" .IR . +.SH BUGS +Never use +.BR mktemp (). +Some implementations follow 4.3BSD +and replace XXXXXX by the current process ID and a single letter, +so that at most 26 different names can be returned. +Since on the one hand the names are easy to guess, and on the other +hand there is a race between testing whether the name exists and +opening the file, every use of +.BR mktemp () +is a security risk. +The race is avoided by +.BR mkstemp (3) +and +.BR mkdtemp (3). +.SH SEE ALSO +.BR mktemp (1), +.BR mkdtemp (3), +.BR mkstemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mktime.3 b/man3/mktime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man3/mktime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man3/mmap64.3 b/man3/mmap64.3 new file mode 100644 index 0000000..8902d1b --- /dev/null +++ b/man3/mmap64.3 @@ -0,0 +1 @@ +.so man2/mmap.2 diff --git a/man3/modf.3 b/man3/modf.3 new file mode 100644 index 0000000..93a0148 --- /dev/null +++ b/man3/modf.3 @@ -0,0 +1,119 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH MODF 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +modf, modff, modfl \- extract signed integral and fractional values from +floating-point number +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double modf(double " x ", double *" iptr ); +.BI "float modff(float " x ", float *" iptr ); +.BI "long double modfl(long double " x ", long double *" iptr ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR modf (), +.BR modfl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions break the argument +.I x +into an integral +part and a fractional part, each of which has the same sign as +.IR x . +The integral part is stored in the location pointed to by +.IR iptr . +.SH RETURN VALUE +These functions return the fractional part of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned, and +.IR *iptr +is set to a NaN. +.PP +If +.I x +is positive infinity (negative infinity), +0 (\-0) is returned, and +.IR *iptr +is set to positive infinity (negative infinity). +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR modf (), +.BR modff (), +.BR modfl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR frexp (3), +.BR ldexp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/modff.3 b/man3/modff.3 new file mode 100644 index 0000000..84af2e3 --- /dev/null +++ b/man3/modff.3 @@ -0,0 +1 @@ +.so man3/modf.3 diff --git a/man3/modfl.3 b/man3/modfl.3 new file mode 100644 index 0000000..84af2e3 --- /dev/null +++ b/man3/modfl.3 @@ -0,0 +1 @@ +.so man3/modf.3 diff --git a/man3/mpool.3 b/man3/mpool.3 new file mode 100644 index 0000000..fa76ef9 --- /dev/null +++ b/man3/mpool.3 @@ -0,0 +1,243 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 +.\" +.TH MPOOL 3 2017-09-15 "" "Linux Programmer's Manual" +.UC 7 +.SH NAME +mpool \- shared memory buffer pool +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \ +", pgno_t " maxcache ); +.PP +.BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *)," +.BI " void (*" pgout ")(void *, pgno_t, void *)," +.BI " void *" pgcookie ); +.PP +.BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr ); +.PP +.BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags ); +.PP +.BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags ); +.PP +.BI "int mpool_sync(MPOOL *" mp ); +.PP +.BI "int mpool_close(MPOOL *" mp ); +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided in glibc up until version 2.1. +Since version 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.PP +.I Mpool +is the library interface intended to provide page oriented buffer management +of files. +The buffers may be shared between processes. +.PP +The function +.BR mpool_open () +initializes a memory pool. +The +.I key +argument is the byte string used to negotiate between multiple +processes wishing to share buffers. +If the file buffers are mapped in shared memory, all processes using +the same key will share the buffers. +If +.I key +is NULL, the buffers are mapped into private memory. +The +.I fd +argument is a file descriptor for the underlying file, which must be seekable. +If +.I key +is non-NULL and matches a file already being mapped, the +.I fd +argument is ignored. +.PP +The +.I pagesize +argument is the size, in bytes, of the pages into which the file is broken up. +The +.I maxcache +argument is the maximum number of pages from the underlying file to cache +at any one time. +This value is not relative to the number of processes which share a file's +buffers, but will be the largest value specified by any of the processes +sharing the file. +.PP +The +.BR mpool_filter () +function is intended to make transparent input and output processing of the +pages possible. +If the +.I pgin +function is specified, it is called each time a buffer is read into the memory +pool from the backing file. +If the +.I pgout +function is specified, it is called each time a buffer is written into the +backing file. +Both functions are called with the +.I pgcookie +pointer, the page number and a pointer to the page to being read or written. +.PP +The function +.BR mpool_new () +takes an +.I MPOOL +pointer and an address as arguments. +If a new page can be allocated, a pointer to the page is returned and +the page number is stored into the +.I pgnoaddr +address. +Otherwise, NULL is returned and +.I errno +is set. +.PP +The function +.BR mpool_get () +takes an +.I MPOOL +pointer and a page number as arguments. +If the page exists, a pointer to the page is returned. +Otherwise, NULL is returned and +.I errno +is set. +The +.I flags +argument is not currently used. +.PP +The function +.BR mpool_put () +unpins the page referenced by +.IR pgaddr . +.I pgaddr +must be an address previously returned by +.BR mpool_get () +or +.BR mpool_new (). +The flag value is specified by ORing +any of the following values: +.TP +.B MPOOL_DIRTY +The page has been modified and needs to be written to the backing file. +.PP +.BR mpool_put () +returns 0 on success and \-1 if an error occurs. +.PP +The function +.BR mpool_sync () +writes all modified pages associated with the +.I MPOOL +pointer to the +backing file. +.BR mpool_sync () +returns 0 on success and \-1 if an error occurs. +.PP +The +.BR mpool_close () +function free's up any allocated memory associated with the memory pool +cookie. +Modified pages are +.B not +written to the backing file. +.BR mpool_close () +returns 0 on success and \-1 if an error occurs. +.SH ERRORS +The +.BR mpool_open () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR malloc (3). +.PP +The +.BR mpool_get () +function may fail and set +.I errno +for the following: +.TP 15 +.B EINVAL +The requested record doesn't exist. +.PP +The +.BR mpool_new () +and +.BR mpool_get () +functions may fail and set +.I errno +for any of the errors specified for the library routines +.BR read (2), +.BR write (2), +and +.BR malloc (3). +.PP +The +.BR mpool_sync () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR write (2). +.PP +The +.BR mpool_close () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR free (3). +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR hash (3), +.BR recno (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mprobe.3 b/man3/mprobe.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man3/mprobe.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man3/mq_close.3 b/man3/mq_close.3 new file mode 100644 index 0000000..133b223 --- /dev/null +++ b/man3/mq_close.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_CLOSE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_close \- close a message queue descriptor +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mq_close(mqd_t " mqdes ); +.fi +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +.BR mq_close () +closes the message queue descriptor +.IR mqdes . +.PP +If the calling process has attached a notification request (see +.RB ( mq_notify (3)) +to this message queue via +.IR mqdes , +then this request is removed, +and another process can now attach a notification request. +.SH RETURN VALUE +On success +.BR mq_close () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mq_close () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +All open message queues are automatically closed on process termination, +or upon +.BR execve (2). +.SH SEE ALSO +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mq_getattr.3 b/man3/mq_getattr.3 new file mode 100644 index 0000000..deb1c0a --- /dev/null +++ b/man3/mq_getattr.3 @@ -0,0 +1,252 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_GETATTR 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_getattr, mq_setattr \- get/set message queue attributes +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr ); +.PP +.BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *" newattr "," +.BI " struct mq_attr *" oldattr ); +.fi +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +.BR mq_getattr () +and +.BR mq_setattr () +respectively retrieve and modify attributes of the message queue +referred to by the message queue descriptor +.IR mqdes . +.PP +.BR mq_getattr () +returns an +.I mq_attr +structure in the buffer pointed by +.IR attr . +This structure is defined as: +.PP +.in +4n +.EX +struct mq_attr { + long mq_flags; /* Flags: 0 or O_NONBLOCK */ + long mq_maxmsg; /* Max. # of messages on queue */ + long mq_msgsize; /* Max. message size (bytes) */ + long mq_curmsgs; /* # of messages currently in queue */ +}; +.EE +.in +.PP +The +.I mq_flags +field contains flags associated with the open message queue description. +This field is initialized when the queue is created by +.BR mq_open (3). +The only flag that can appear in this field is +.BR O_NONBLOCK . +.PP +The +.I mq_maxmsg +and +.I mq_msgsize +fields are set when the message queue is created by +.BR mq_open (3). +The +.I mq_maxmsg +field is an upper limit on the number of messages +that may be placed on the queue using +.BR mq_send (3). +The +.I mq_msgsize +field is an upper limit on the size of messages +that may be placed on the queue. +Both of these fields must have a value greater than zero. +Two +.I /proc +files that place ceilings on the values for these fields are described in +.BR mq_overview (7). +.PP +The +.I mq_curmsgs +field returns the number of messages currently held in the queue. +.PP +.BR mq_setattr () +sets message queue attributes using information supplied in the +.I mq_attr +structure pointed to by +.IR newattr . +The only attribute that can be modified is the setting of the +.B O_NONBLOCK +flag in +.IR mq_flags . +The other fields in +.I newattr +are ignored. +If the +.I oldattr +field is not NULL, +then the buffer that it points to is used to return an +.I mq_attr +structure that contains the same information that is returned by +.BR mq_getattr (). +.SH RETURN VALUE +On success +.BR mq_getattr () +and +.BR mq_setattr () +return 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.TP +.B EINVAL +.I newattr\->mq_flags +contained set bits other than +.BR O_NONBLOCK . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw26 lb lb +l l l. +Interface Attribute Value +T{ +.BR mq_getattr (), +.BR mq_setattr () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +On Linux, +.BR mq_getattr () +and +.BR mq_setattr () +are library functions layered on top of the +.BR mq_getsetattr (2) +system call. +.SH EXAMPLE +The program below can be used to show the default +.I mq_maxmsg +and +.I mq_msgsize +values that are assigned to a message queue that is created with a call to +.BR mq_open (3) +in which the +.I attr +argument is NULL. +Here is an example run of the program: +.PP +.in +4n +.EX +$ \fB./a.out /testq\fP +Maximum # of messages on queue: 10 +Maximum message size: 8192 +.EE +.in +.PP +Since Linux 3.5, the following +.I /proc +files (described in +.BR mq_overview (7)) +can be used to control the defaults: +.PP +.in +4n +.EX +$ \fBuname -sr\fP +Linux 3.8.0 +$ \fBcat /proc/sys/fs/mqueue/msg_default\fP +10 +$ \fBcat /proc/sys/fs/mqueue/msgsize_default\fP +8192 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + mqd_t mqd; + struct mq_attr attr; + + if (argc != 2) { + fprintf(stderr, "Usage: %s mq\-name\\n", argv[0]); + exit(EXIT_FAILURE); + } + + mqd = mq_open(argv[1], O_CREAT | O_EXCL, S_IRUSR | S_IWUSR, NULL); + if (mqd == (mqd_t) \-1) + errExit("mq_open"); + + if (mq_getattr(mqd, &attr) == \-1) + errExit("mq_getattr"); + + printf("Maximum # of messages on queue: %ld\\n", attr.mq_maxmsg); + printf("Maximum message size: %ld\\n", attr.mq_msgsize); + + if (mq_unlink(argv[1]) == \-1) + errExit("mq_unlink"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR mq_close (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mq_notify.3 b/man3/mq_notify.3 new file mode 100644 index 0000000..6cc6ebd --- /dev/null +++ b/man3/mq_notify.3 @@ -0,0 +1,295 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_NOTIFY 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_notify \- register for notification when a message is available +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp ); +.fi +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +.BR mq_notify () +allows the calling process to register or unregister for delivery of +an asynchronous notification when a new message arrives on +the empty message queue referred to by the message queue descriptor +.IR mqdes . +.PP +The +.I sevp +argument is a pointer to a +.I sigevent +structure. +For the definition and general details of this structure, see +.BR sigevent (7). +.PP +If +.I sevp +is a non-null pointer, then +.BR mq_notify () +registers the calling process to receive message notification. +The +.I sigev_notify +field of the +.I sigevent +structure to which +.I sevp +points specifies how notification is to be performed. +This field has one of the following values: +.TP +.B SIGEV_NONE +A "null" notification: the calling process is registered as the target +for notification, but when a message arrives, no notification is sent. +.\" When is SIGEV_NONE useful? +.TP +.B SIGEV_SIGNAL +Notify the process by sending the signal specified in +.IR sigev_signo . +See +.BR sigevent (7) +for general details. +The +.I si_code +field of the +.I siginfo_t +structure will be set to +.BR SI_MESGQ . +In addition, +.\" I don't know of other implementations that set +.\" si_pid and si_uid -- MTK +.I si_pid +will be set to the PID of the process that sent the message, and +.I si_uid +will be set to the real user ID of the sending process. +.TP +.B SIGEV_THREAD +Upon message delivery, invoke +.I sigev_notify_function +as if it were the start function of a new thread. +See +.BR sigevent (7) +for details. +.PP +Only one process can be registered to receive notification +from a message queue. +.PP +If +.I sevp +is NULL, and the calling process is currently registered to receive +notifications for this message queue, then the registration is removed; +another process can then register to receive a message notification +for this queue. +.PP +Message notification occurs only when a new message arrives and +the queue was previously empty. +If the queue was not empty at the time +.BR mq_notify () +was called, then a notification will occur only after +the queue is emptied and a new message arrives. +.PP +If another process or thread is waiting to read a message +from an empty queue using +.BR mq_receive (3), +then any message notification registration is ignored: +the message is delivered to the process or thread calling +.BR mq_receive (3), +and the message notification registration remains in effect. +.PP +Notification occurs once: after a notification is delivered, +the notification registration is removed, +and another process can register for message notification. +If the notified process wishes to receive the next notification, +it can use +.BR mq_notify () +to request a further notification. +This should be done before emptying all unread messages from the queue. +(Placing the queue in nonblocking mode is useful for emptying +the queue of messages without blocking once it is empty.) +.SH RETURN VALUE +On success +.BR mq_notify () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.TP +.B EBUSY +Another process has already registered to receive notification +for this message queue. +.TP +.B EINVAL +.I sevp\->sigev_notify +is not one of the permitted values; or +.I sevp\->sigev_notify +is +.B SIGEV_SIGNAL +and +.I sevp\->sigev_signo +is not a valid signal number. +.TP +.B ENOMEM +Insufficient memory. +.PP +POSIX.1-2008 says that an implementation +.I may +generate an +.B EINVAL +.\" Linux does not do this +error if +.I sevp +is NULL, and the caller is not currently registered to receive +notifications for the queue +.IR mqdes . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mq_notify () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES +.\" +.SS C library/kernel differences +In the glibc implementation, the +.BR mq_notify () +library function is implemented on top of the system call of the same name. +When +.I sevp +is NULL, or specifies a notification mechanism other than +.BR SIGEV_THREAD , +the library function directly invokes the system call. +For +.BR SIGEV_THREAD , +much of the implementation resides within the library, +rather than the kernel. +(This is necessarily so, +since the thread involved in handling the notification is one +that must be managed by the C library POSIX threads implementation.) +The implementation involves the use of a raw +.BR netlink (7) +socket and creates a new thread for each notification that is +delivered to the process. +.SH EXAMPLE +The following program registers a notification request for the +message queue named in its command-line argument. +Notification is performed by creating a thread. +The thread executes a function which reads one message from the +queue and then terminates the process. +.SS Program source +.EX +#include +#include +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +static void /* Thread start function */ +tfunc(union sigval sv) +{ + struct mq_attr attr; + ssize_t nr; + void *buf; + mqd_t mqdes = *((mqd_t *) sv.sival_ptr); + + /* Determine max. msg size; allocate buffer to receive msg */ + + if (mq_getattr(mqdes, &attr) == \-1) + handle_error("mq_getattr"); + buf = malloc(attr.mq_msgsize); + if (buf == NULL) + handle_error("malloc"); + + nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); + if (nr == \-1) + handle_error("mq_receive"); + + printf("Read %zd bytes from MQ\\n", nr); + free(buf); + exit(EXIT_SUCCESS); /* Terminate the process */ +} + +int +main(int argc, char *argv[]) +{ + mqd_t mqdes; + struct sigevent sev; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + mqdes = mq_open(argv[1], O_RDONLY); + if (mqdes == (mqd_t) \-1) + handle_error("mq_open"); + + sev.sigev_notify = SIGEV_THREAD; + sev.sigev_notify_function = tfunc; + sev.sigev_notify_attributes = NULL; + sev.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */ + if (mq_notify(mqdes, &sev) == \-1) + handle_error("mq_notify"); + + pause(); /* Process will be terminated by thread function */ +} +.EE +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7), +.BR sigevent (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mq_open.3 b/man3/mq_open.3 new file mode 100644 index 0000000..6db0608 --- /dev/null +++ b/man3/mq_open.3 @@ -0,0 +1,323 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_OPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_open \- open a message queue +.SH SYNOPSIS +.nf +.BR "#include " " /* For O_* constants */" +.BR "#include " " /* For mode constants */" +.B #include +.PP +.BI "mqd_t mq_open(const char *" name ", int " oflag ); +.BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode , +.BI " struct mq_attr *" attr ); +.fi +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +.BR mq_open () +creates a new POSIX message queue or opens an existing queue. +The queue is identified by +.IR name . +For details of the construction of +.IR name , +see +.BR mq_overview (7). +.PP +The +.I oflag +argument specifies flags that control the operation of the call. +(Definitions of the flags values can be obtained by including +.IR .) +Exactly one of the following must be specified in +.IR oflag : +.TP +.B O_RDONLY +Open the queue to receive messages only. +.TP +.B O_WRONLY +Open the queue to send messages only. +.TP +.B O_RDWR +Open the queue to both send and receive messages. +.PP +Zero or more of the following flags can additionally be +.IR OR ed +in +.IR oflag : +.TP +.BR O_CLOEXEC " (since Linux 2.6.26)" +.\" commit 269f21344b23e552c21c9e2d7ca258479dcd7a0a +Set the close-on-exec flag for the message queue descriptor. +See +.BR open (2) +for a discussion of why this flag is useful. +.TP +.B O_CREAT +Create the message queue if it does not exist. +The owner (user ID) of the message queue is set to the effective +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID +of the calling process. +.\" In reality the filesystem IDs are used on Linux. +.TP +.B O_EXCL +If +.B O_CREAT +was specified in +.IR oflag , +and a queue with the given +.I name +already exists, then fail with the error +.BR EEXIST . +.TP +.B O_NONBLOCK +Open the queue in nonblocking mode. +In circumstances where +.BR mq_receive (3) +and +.BR mq_send (3) +would normally block, these functions instead fail with the error +.BR EAGAIN . +.PP +If +.B O_CREAT +is specified in +.IR oflag , +then two additional arguments must be supplied. +The +.I mode +argument specifies the permissions to be placed on the new queue, +as for +.BR open (2). +(Symbolic definitions for the permissions bits can be obtained by including +.IR .) +The permissions settings are masked against the process umask. +.PP +The fields of the +.IR "struct mq_attr" +pointed to +.I attr +specify the maximum number of messages and +the maximum size of messages that the queue will allow. +This structure is defined as follows: +.PP +.PP +.in +4n +.EX +struct mq_attr { + long mq_flags; /* Flags (ignored for mq_open()) */ + long mq_maxmsg; /* Max. # of messages on queue */ + long mq_msgsize; /* Max. message size (bytes) */ + long mq_curmsgs; /* # of messages currently in queue + (ignored for mq_open()) */ +}; +.EE +.in +.PP +Only the +.I mq_maxmsg +and +.I mq_msgsize +fields are employed when calling +.BR mq_open (); +the values in the remaining fields are ignored. +.PP +If +.I attr +is NULL, then the queue is created with implementation-defined +default attributes. +Since Linux 3.5, two +.I /proc +files can be used to control these defaults; see +.BR mq_overview (7) +for details. +.SH RETURN VALUE +On success, +.BR mq_open () +returns a message queue descriptor for use by other +message queue functions. +On error, +.BR mq_open () +returns +.IR "(mqd_t)\ \-1", +with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The queue exists, but the caller does not have permission to +open it in the specified mode. +.TP +.B EACCES +.I name +contained more than one slash. +.\" Note that this isn't consistent with the same case for sem_open() +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified in +.IR oflag , +but a queue with this +.I name +already exists. +.TP +.B EINVAL +.\" glibc checks whether the name starts with a "/" and if not, +.\" gives this error +.I name +doesn't follow the format in +.BR mq_overview (7). +.TP +.B EINVAL +.B O_CREAT +was specified in +.IR oflag , +and +.I attr +was not NULL, but +.I attr\->mq_maxmsg +or +.I attr\->mq_msqsize +was invalid. +Both of these fields must be greater than zero. +In a process that is unprivileged (does not have the +.B CAP_SYS_RESOURCE +capability), +.I attr\->mq_maxmsg +must be less than or equal to the +.I msg_max +limit, and +.I attr\->mq_msgsize +must be less than or equal to the +.I msgsize_max +limit. +In addition, even in a privileged process, +.I attr\->mq_maxmsg +cannot exceed the +.B HARD_MAX +limit. +(See +.BR mq_overview (7) +for details of these limits.) +.TP +.B EMFILE +The per-process limit on the number of open file +and message queue descriptors has been reached +(see the description of +.BR RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files +and message queues has been reached. +.TP +.B ENOENT +The +.B O_CREAT +flag was not specified in +.IR oflag , +and no queue with this +.I name +exists. +.TP +.B ENOENT +.I name +was just "/" followed by no other characters. +.\" Note that this isn't consistent with the same case for sem_open() +.TP +.B ENOMEM +Insufficient memory. +.TP +.B ENOSPC +Insufficient space for the creation of a new message queue. +This probably occurred because the +.I queues_max +limit was encountered; see +.BR mq_overview (7). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mq_open () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +.SS C library/kernel differences +The +.BR mq_open () +library function is implemented on top of a system call of the same name. +The library function performs the check that the +.I name +starts with a slash (/), giving the +.B EINVAL +error if it does not. +The kernel system call expects +.I name +to contain no preceding slash, +so the C library function passes +.I name +without the preceding slash (i.e., +.IR name+1 ) +to the system call. +.SH BUGS +In kernels before 2.6.14, +the process umask was not applied to the permissions specified in +.IR mode . +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mq_receive.3 b/man3/mq_receive.3 new file mode 100644 index 0000000..9086d7c --- /dev/null +++ b/man3/mq_receive.3 @@ -0,0 +1,193 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_RECEIVE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_receive, mq_timedreceive \- receive a message from a message queue +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "ssize_t mq_receive(mqd_t " mqdes ", char *" msg_ptr , +.BI " size_t " msg_len ", unsigned int *" msg_prio ); +.PP +.B #include +.B #include +.PP +.BI "ssize_t mq_timedreceive(mqd_t " mqdes ", char *" msg_ptr , +.BI " size_t " msg_len ", unsigned int *" msg_prio , +.BI " const struct timespec *" abs_timeout ); +.fi +.PP +Link with \fI\-lrt\fP. +.PP +.ad l +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mq_timedreceive (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +.BR mq_receive () +removes the oldest message with the highest priority from +the message queue referred to by the message queue descriptor +.IR mqdes , +and places it in the buffer pointed to by +.IR msg_ptr . +The +.I msg_len +argument specifies the size of the buffer pointed to by +.IR msg_ptr ; +this must be greater than or equal to the +.I mq_msgsize +attribute of the queue (see +.BR mq_getattr (3)). +If +.I msg_prio +is not NULL, then the buffer to which it points is used +to return the priority associated with the received message. +.PP +If the queue is empty, then, by default, +.BR mq_receive () +blocks until a message becomes available, +or the call is interrupted by a signal handler. +If the +.B O_NONBLOCK +flag is enabled for the message queue description, +then the call instead fails immediately with the error +.BR EAGAIN . +.PP +.BR mq_timedreceive () +behaves just like +.BR mq_receive (), +except that if the queue is empty and the +.B O_NONBLOCK +flag is not enabled for the message queue description, then +.I abs_timeout +points to a structure which specifies how long the call will block. +This value is an absolute timeout in seconds and nanoseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), +specified in the following structure: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.PP +If no message is available, +and the timeout has already expired by the time of the call, +.BR mq_timedreceive () +returns immediately. +.SH RETURN VALUE +On success, +.BR mq_receive () +and +.BR mq_timedreceive () +return the number of bytes in the received message; +on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The queue was empty, and the +.B O_NONBLOCK +flag was set for the message queue description referred to by +.IR mqdes . +.TP +.B EBADF +The descriptor specified in +.I mqdes +was invalid or not opened for reading. +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The call would have blocked, and +.I abs_timeout +was invalid, either because +.I tv_sec +was less than zero, or because +.I tv_nsec +was less than zero or greater than 1000 million. +.TP +.B EMSGSIZE +.I msg_len +was less than the +.I mq_msgsize +attribute of the message queue. +.TP +.B ETIMEDOUT +The call timed out before a message could be transferred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR mq_receive (), +.BR mq_timedreceive () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +On Linux, +.BR mq_timedreceive () +is a system call, and +.BR mq_receive () +is a library function layered on top of that system call. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mq_send.3 b/man3/mq_send.3 new file mode 100644 index 0000000..3b58b9a --- /dev/null +++ b/man3/mq_send.3 @@ -0,0 +1,201 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_SEND 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_send, mq_timedsend \- send a message to a message queue +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mq_send(mqd_t " mqdes ", const char *" msg_ptr , +.BI " size_t " msg_len ", unsigned int " msg_prio ); +.PP +.B #include +.B #include +.PP +.BI "int mq_timedsend(mqd_t " mqdes ", const char *" msg_ptr , +.BI " size_t " msg_len ", unsigned int " msg_prio , +.BI " const struct timespec *" abs_timeout ); +.fi +.PP +Link with \fI\-lrt\fP. +.PP +.ad l +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR mq_timedsend (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +.BR mq_send () +adds the message pointed to by +.I msg_ptr +to the message queue referred to by the message queue descriptor +.IR mqdes . +The +.I msg_len +argument specifies the length of the message pointed to by +.IR msg_ptr ; +this length must be less than or equal to the queue's +.I mq_msgsize +attribute. +Zero-length messages are allowed. +.PP +The +.I msg_prio +argument is a nonnegative integer that specifies the priority +of this message. +Messages are placed on the queue in decreasing order of priority, +with newer messages of the same priority being placed after +older messages with the same priority. +See +.BR mq_overview (7) +for details on the range for the message priority. +.PP +If the message queue is already full +(i.e., the number of messages on the queue equals the queue's +.I mq_maxmsg +attribute), then, by default, +.BR mq_send () +blocks until sufficient space becomes available to allow the message +to be queued, or until the call is interrupted by a signal handler. +If the +.B O_NONBLOCK +flag is enabled for the message queue description, +then the call instead fails immediately with the error +.BR EAGAIN . +.PP +.BR mq_timedsend () +behaves just like +.BR mq_send (), +except that if the queue is full and the +.B O_NONBLOCK +flag is not enabled for the message queue description, then +.I abs_timeout +points to a structure which specifies how long the call will block. +This value is an absolute timeout in seconds and nanoseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), +specified in the following structure: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.PP +If the message queue is full, +and the timeout has already expired by the time of the call, +.BR mq_timedsend () +returns immediately. +.SH RETURN VALUE +On success, +.BR mq_send () +and +.BR mq_timedsend () +return zero; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The queue was full, and the +.B O_NONBLOCK +flag was set for the message queue description referred to by +.IR mqdes . +.TP +.B EBADF +The descriptor specified in +.I mqdes +was invalid or not opened for writing. +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The call would have blocked, and +.I abs_timeout +was invalid, either because +.I tv_sec +was less than zero, or because +.I tv_nsec +was less than zero or greater than 1000 million. +.TP +.B EMSGSIZE +.I msg_len +was greater than the +.I mq_msgsize +attribute of the message queue. +.TP +.B ETIMEDOUT +The call timed out before a message could be transferred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR mq_send (), +.BR mq_timedsend () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +On Linux, +.BR mq_timedsend () +is a system call, and +.BR mq_send () +is a library function layered on top of that system call. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_unlink (3), +.BR mq_overview (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mq_setattr.3 b/man3/mq_setattr.3 new file mode 100644 index 0000000..a3818a2 --- /dev/null +++ b/man3/mq_setattr.3 @@ -0,0 +1 @@ +.so man3/mq_getattr.3 diff --git a/man3/mq_timedreceive.3 b/man3/mq_timedreceive.3 new file mode 100644 index 0000000..9fed5f2 --- /dev/null +++ b/man3/mq_timedreceive.3 @@ -0,0 +1 @@ +.so man3/mq_receive.3 diff --git a/man3/mq_timedsend.3 b/man3/mq_timedsend.3 new file mode 100644 index 0000000..28b1eff --- /dev/null +++ b/man3/mq_timedsend.3 @@ -0,0 +1 @@ +.so man3/mq_send.3 diff --git a/man3/mq_unlink.3 b/man3/mq_unlink.3 new file mode 100644 index 0000000..7de1601 --- /dev/null +++ b/man3/mq_unlink.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_UNLINK 3 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_unlink \- remove a message queue +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int mq_unlink(const char *" name ); +.fi +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +.BR mq_unlink () +removes the specified message queue +.IR name . +The message queue name is removed immediately. +The queue itself is destroyed once any other processes that have +the queue open close their descriptors referring to the queue. +.SH RETURN VALUE +On success +.BR mq_unlink () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to unlink this message queue. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENOENT +There is no message queue with the given +.IR name . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR mq_unlink () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/mrand48.3 b/man3/mrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man3/mrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/mrand48_r.3 b/man3/mrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man3/mrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/mtrace.3 b/man3/mtrace.3 new file mode 100644 index 0000000..5bee2a1 --- /dev/null +++ b/man3/mtrace.3 @@ -0,0 +1,202 @@ +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MTRACE 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +mtrace, muntrace \- malloc tracing +.SH SYNOPSIS +.B "#include " +.PP +.B "void mtrace(void);" +.PP +.B "void muntrace(void);" +.SH DESCRIPTION +The +.BR mtrace () +function installs hook functions for the memory-allocation functions +.RB ( malloc (3), +.BR realloc (3) +.BR memalign (3), +.BR free (3)). +These hook functions record tracing information about memory allocation +and deallocation. +The tracing information can be used to discover memory leaks and +attempts to free nonallocated memory in a program. +.PP +The +.BR muntrace () +function disables the hook functions installed by +.BR mtrace (), +so that tracing information is no longer recorded +for the memory-allocation functions. +If no hook functions were successfully installed by +.BR mtrace (), +.BR muntrace () +does nothing. +.PP +When +.BR mtrace () +is called, it checks the value of the environment variable +.BR MALLOC_TRACE , +which should contain the pathname of a file in which +the tracing information is to be recorded. +If the pathname is successfully opened, it is truncated to zero length. +.PP +If +.BR MALLOC_TRACE +is not set, +or the pathname it specifies is invalid or not writable, +then no hook functions are installed, and +.BR mtrace () +has no effect. +In set-user-ID and set-group-ID programs, +.BR MALLOC_TRACE +is ignored, and +.BR mtrace () +has no effect. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR mtrace (), +.BR muntrace () +T} Thread safety MT-Unsafe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" markings in glibc manual are more detailed: +.\" +.\" mtrace: MT-Unsafe env race:mtrace const:malloc_hooks init +.\" muntrace: MT-Unsafe race:mtrace const:malloc_hooks locale +.\" +.\" But there is something wrong in glibc manual, for example: +.\" glibc manual says muntrace should have marking locale because it calls +.\" fprintf(), but muntrace does not execute area which cause locale problem. +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +In normal usage, +.BR mtrace () +is called once at the start of execution of a program, and +.BR muntrace () +is never called. +.PP +The tracing output produced after a call to +.BR mtrace () +is textual, but not designed to be human readable. +The GNU C library provides a Perl script, +.BR mtrace (1), +that interprets the trace log and produces human-readable output. +For best results, +the traced program should be compiled with debugging enabled, +so that line-number information is recorded in the executable. +.PP +The tracing performed by +.BR mtrace () +incurs a performance penalty (if +.B MALLOC_TRACE +points to a valid, writable pathname). +.SH BUGS +The line-number information produced by +.BR mtrace (1) +is not always precise: +the line number references may refer to the previous or following (nonblank) +line of the source code. +.SH EXAMPLE +The shell session below demonstrates the use of the +.BR mtrace () +function and the +.BR mtrace (1) +command in a program that has memory leaks at two different locations. +The demonstration uses the following program: +.PP +.in +4 +.EX +.RB "$ " "cat t_mtrace.c" +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + int j; + + mtrace(); + + for (j = 0; j < 2; j++) + malloc(100); /* Never freed\-\-a memory leak */ + + calloc(16, 16); /* Never freed\-\-a memory leak */ + exit(EXIT_SUCCESS); +} +.EE +.in +.PP +When we run the program as follows, we see that +.BR mtrace () +diagnosed memory leaks at two different locations in the program: +.PP +.in +4n +.EX +.RB "$ " "cc \-g t_mtrace.c \-o t_mtrace" +.RB "$ " "export MALLOC_TRACE=/tmp/t" +.RB "$ " "./t_mtrace" +.RB "$ " "mtrace ./t_mtrace $MALLOC_TRACE" +Memory not freed: +----------------- + Address Size Caller +0x084c9378 0x64 at /home/cecilia/t_mtrace.c:12 +0x084c93e0 0x64 at /home/cecilia/t_mtrace.c:12 +0x084c9448 0x100 at /home/cecilia/t_mtrace.c:16 +.EE +.in +.PP +The first two messages about unfreed memory correspond to the two +.BR malloc (3) +calls inside the +.I for +loop. +The final message corresponds to the call to +.BR calloc (3) +(which in turn calls +.BR malloc (3)). +.SH SEE ALSO +.BR mtrace (1), +.BR malloc (3), +.BR malloc_hook (3), +.BR mcheck (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/muntrace.3 b/man3/muntrace.3 new file mode 100644 index 0000000..2b03d10 --- /dev/null +++ b/man3/muntrace.3 @@ -0,0 +1 @@ +.so man3/mtrace.3 diff --git a/man3/nan.3 b/man3/nan.3 new file mode 100644 index 0000000..a299431 --- /dev/null +++ b/man3/nan.3 @@ -0,0 +1,103 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Based on glibc infopages +.\" +.\" Corrections by aeb +.\" +.TH NAN 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +nan, nanf, nanl \- return 'Not a Number' +.SH SYNOPSIS +.B #include +.PP +.BI "double nan(const char *" tagp ); +.br +.BI "float nanf(const char *" tagp ); +.br +.BI "long double nanl(const char *" tagp ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR nan (), +.BR nanf (), +.BR nanl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions return a representation (determined by +.IR tagp ) +of a quiet NaN. +If the implementation does not support +quiet NaNs, these functions return zero. +.PP +The call +.I nan("char-sequence") +is equivalent to: +.PP +.in +4n +.EX +strtod("NAN(char-sequence)", NULL); +.EE +.in +.PP +Similarly, calls to +.BR nanf () +and +.BR nanl () +are equivalent to analogous calls to +.BR strtof (3) +and +.BR strtold (3). +.PP +The argument +.I tagp +is used in an unspecified manner. +On IEEE 754 systems, there are many representations of NaN, and +.I tagp +selects one. +On other systems it may do nothing. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR nan (), +.BR nanf (), +.BR nanl () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +See also IEC 559 and the appendix with +recommended functions in IEEE 754/IEEE 854. +.SH SEE ALSO +.BR isnan (3), +.BR strtod (3), +.BR math_error (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/nanf.3 b/man3/nanf.3 new file mode 100644 index 0000000..08e9aa7 --- /dev/null +++ b/man3/nanf.3 @@ -0,0 +1 @@ +.so man3/nan.3 diff --git a/man3/nanl.3 b/man3/nanl.3 new file mode 100644 index 0000000..08e9aa7 --- /dev/null +++ b/man3/nanl.3 @@ -0,0 +1 @@ +.so man3/nan.3 diff --git a/man3/nearbyint.3 b/man3/nearbyint.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man3/nearbyint.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/nearbyintf.3 b/man3/nearbyintf.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man3/nearbyintf.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/nearbyintl.3 b/man3/nearbyintl.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man3/nearbyintl.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/netlink.3 b/man3/netlink.3 new file mode 100644 index 0000000..1296582 --- /dev/null +++ b/man3/netlink.3 @@ -0,0 +1,95 @@ +.\" This manpage copyright 1998 by Andi Kleen. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Subject to the GPL. +.\" %%%LICENSE_END +.\" +.\" Based on the original comments from Alexey Kuznetsov +.\" $Id: netlink.3,v 1.1 1999/05/14 17:17:24 freitag Exp $ +.\" +.TH NETLINK 3 2014-03-20 "GNU" "Linux Programmer's Manual" +.SH NAME +netlink \- Netlink macros +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int NLMSG_ALIGN(size_t " len ); +.BI "int NLMSG_LENGTH(size_t " len ); +.BI "int NLMSG_SPACE(size_t " len ); +.BI "void *NLMSG_DATA(struct nlmsghdr *" nlh ); +.BI "struct nlmsghdr *NLMSG_NEXT(struct nlmsghdr *" nlh ", int " len ); +.BI "int NLMSG_OK(struct nlmsghdr *" nlh ", int " len ); +.BI "int NLMSG_PAYLOAD(struct nlmsghdr *" nlh ", int " len ); +.fi +.SH DESCRIPTION +.I +defines several standard macros to access or create a netlink datagram. +They are similar in spirit to the macros defined in +.BR cmsg (3) +for auxiliary data. +The buffer passed to and from a netlink socket should +be accessed using only these macros. +.TP +.BR NLMSG_ALIGN () +Round the length of a netlink message up to align it properly. +.TP +.BR NLMSG_LENGTH () +Given the payload length, +.IR len , +this macro returns the aligned length to store in the +.I nlmsg_len +field of the +.IR nlmsghdr . +.TP +.BR NLMSG_SPACE () +Return the number of bytes that a netlink message with payload of +.I len +would occupy. +.TP +.BR NLMSG_DATA () +Return a pointer to the payload associated with the passed +.IR nlmsghdr . +.TP +.\" this is bizarre, maybe the interface should be fixed. +.BR NLMSG_NEXT () +Get the next +.I nlmsghdr +in a multipart message. +The caller must check if the current +.I nlmsghdr +didn't have the +.B NLMSG_DONE +set\(emthis function doesn't return NULL on end. +The +.I len +argument is an lvalue containing the remaining length +of the message buffer. +This macro decrements it by the length of the message header. +.TP +.BR NLMSG_OK () +Return true if the netlink message is not truncated and +is in a form suitable for parsing. +.TP +.BR NLMSG_PAYLOAD () +Return the length of the payload associated with the +.IR nlmsghdr . +.SH CONFORMING TO +These macros are nonstandard Linux extensions. +.SH NOTES +It is often better to use netlink via +.I libnetlink +than via the low-level kernel interface. +.SH SEE ALSO +.BR libnetlink (3), +.BR netlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/newlocale.3 b/man3/newlocale.3 new file mode 100644 index 0000000..dac9d7a --- /dev/null +++ b/man3/newlocale.3 @@ -0,0 +1,389 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH NEWLOCALE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +newlocale, freelocale \- create, modify, and free a locale object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "locale_t newlocale(int " category_mask ", const char *" locale ", +.BI " locale_t " base ); +.PP +.BI "void freelocale(locale_t " locobj ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR newlocale (), +.BR freelocale (): +.PD 0 +.RS 4 +.TP +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.SH DESCRIPTION +The +.BR newlocale () +function creates a new locale object, or modifies an existing object, +returning a reference to the new or modified object as the function result. +Whether the call creates a new object or modifies an existing object +is determined by the value of +.IR base : +.IP * 3 +If +.I base +is +.IR "(locale_t)\ 0" , +a new object is created. +.IP * +If +.I base +refers to valid existing locale object +(i.e., an object returned by a previous call to +.BR newlocale () +or +.BR duplocale (3)), +then that object is modified by the call. +If the call is successful, the contents of +.I base +are unspecified (in particular, the object referred to by +.I base +may be freed, and a new object created). +Therefore, the caller should ensure that it stops using +.I base +before the call to +.BR newlocale (), +and should subsequently refer to the modified object via the +reference returned as the function result. +If the call fails, the contents of +.I base +remain valid and unchanged. +.PP +If +.I base +is the special locale object +.BR LC_GLOBAL_LOCALE +(see +.BR duplocale (3)), +or is not +.IR "(locale_t)\ 0" +and is not a valid locale object handle, +the behavior is undefined. +.PP +The +.I category_mask +argument is a bit mask that specifies the locale categories +that are to be set in a newly created locale object +or modified in an existing object. +The mask is constructed by a bitwise OR of the constants +.BR LC_ADDRESS_MASK , +.BR LC_CTYPE_MASK , +.BR LC_COLLATE_MASK , +.BR LC_IDENTIFICATION_MASK , +.BR LC_MEASUREMENT_MASK , +.BR LC_MESSAGES_MASK , +.BR LC_MONETARY_MASK , +.BR LC_NUMERIC_MASK , +.BR LC_NAME_MASK , +.BR LC_PAPER_MASK , +.BR LC_TELEPHONE_MASK , +and +.BR LC_TIME_MASK . +Alternatively, the mask can be specified as +.BR LC_ALL_MASK , +which is equivalent to ORing all of the preceding constants. +.PP +For each category specified in +.IR category_mask , +the locale data from +.I locale +will be used in the object returned by +.BR newlocale (). +If a new locale object is being created, +data for all categories not specified in +.IR category_mask +is taken from the default ("POSIX") locale. +.PP +The following preset values of +.I locale +are defined for all categories that can be specified in +.IR category_mask : +.TP +"POSIX" +A minimal locale environment for C language programs. +.TP +"C" +Equivalent to "POSIX". +.TP +"" +An implementation-defined native environment +corresponding to the values of the +.BR LC_* +and +.B LANG +environment variables (see +.BR locale (7)). +.SS freelocale() +The +.BR freelocale () +function deallocates the resources associated with +.IR locobj , +a locale object previously returned by a call to +.BR newlocale () +or +.BR duplocale (3). +If +.I locobj +is +.BR LC_GLOBAL_LOCALE +or is not valid locale object handle, the results are undefined. +.PP +Once a locale object has been freed, +the program should make no further use of it. +.SH RETURN VALUE +On success, +.BR newlocale () +returns a handle that can be used in calls to +.BR duplocale (3), +.BR freelocale (), +and other functions that take a +.I locale_t +argument. +On error, +.BR newlocale () +returns +.IR "(locale_t)\ 0", +and sets +.I errno +to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +One or more bits in +.I category_mask +do not correspond to a valid locale category. +.TP +.B EINVAL +.I locale +is NULL. +.TP +.B ENOENT +.I locale +is not a string pointer referring to a valid locale. +.TP +.B ENOMEM +Insufficient memory to create a locale object. +.SH VERSIONS +The +.BR newlocale () +and +.BR freelocale () +functions first appeared in version 2.3 of the GNU C library. +.SH CONFORMING TO +POSIX.1-2008. +.SH NOTES +Each locale object created by +.BR newlocale () +should be deallocated using +.BR freelocale (). +.SH EXAMPLE +The program below takes up to two command-line arguments, +which each identify locales. +The first argument is required, and is used to set the +.B LC_NUMERIC +category in a locale object created using +.BR newlocale (). +The second command-line argument is optional; +if it is present, it is used to set the +.B LC_TIME +category of the locale object. +.PP +Having created and initialized the locale object, +the program then applies it using +.BR uselocale (3), +and then tests the effect of the locale changes by: +.IP 1. 3 +Displaying a floating-point number with a fractional part. +This output will be affected by the +.B LC_NUMERIC +setting. +In many European-language locales, +the fractional part of the number is separated from the integer part +using a comma, rather than a period. +.IP 2. +Displaying the date. +The format and language of the output will be affected by the +.B LC_TIME +setting. +.PP +The following shell sessions show some example runs of this program. +.PP +Set the +.B LC_NUMERIC +category to +.IR fr_FR +(French): +.PP +.in +4n +.EX +$ \fB./a.out fr_FR\fP +123456,789 +Fri Mar 7 00:25:08 2014 +.EE +.in +.PP +Set the +.B LC_NUMERIC +category to +.IR fr_FR +(French), +and the +.B LC_TIME +category to +.IR it_IT +(Italian): +.PP +.in +4n +.EX +$ \fB./a.out fr_FR it_IT\fP +123456,789 +ven 07 mar 2014 00:26:01 CET +.EE +.in +.PP +Specify the +.B LC_TIME +setting as an empty string, +which causes the value to be taken from environment variable settings +(which, here, specify +.IR mi_NZ , +New Zealand Māori): +.PP +.in +4n +.EX +$ LC_ALL=mi_NZ ./a.out fr_FR "" +123456,789 +Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET +.EE +.in +.SS Program source +.EX +#define _XOPEN_SOURCE 700 +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + char buf[100]; + time_t t; + size_t s; + struct tm *tm; + locale_t loc, nloc; + + if (argc < 2) { + fprintf(stderr, "Usage: %s locale1 [locale2]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + /* Create a new locale object, taking the LC_NUMERIC settings + from the locale specified in argv[1] */ + + loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0); + if (loc == (locale_t) 0) + errExit("newlocale"); + + /* If a second command\-line argument was specified, modify the + locale object to take the LC_TIME settings from the locale + specified in argv[2]. We assign the result of this newlocale() + call to 'nloc' rather than 'loc', since in some cases, we might + want to preserve 'loc' if this call fails. */ + + if (argc > 2) { + nloc = newlocale(LC_TIME_MASK, argv[2], loc); + if (nloc == (locale_t) 0) + errExit("newlocale"); + loc = nloc; + } + + /* Apply the newly created locale to this thread */ + + uselocale(loc); + + /* Test effect of LC_NUMERIC */ + + printf("%8.3f\\n", 123456.789); + + /* Test effect of LC_TIME */ + + t = time(NULL); + tm = localtime(&t); + if (tm == NULL) + errExit("time"); + + s = strftime(buf, sizeof(buf), "%c", tm); + if (s == 0) + errExit("strftime"); + + printf("%s\\n", buf); + + /* Free the locale object */ + + freelocale(loc); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR locale (1), +.BR duplocale (3), +.BR setlocale (3), +.BR uselocale (3), +.BR locale (5), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/nextafter.3 b/man3/nextafter.3 new file mode 100644 index 0000000..d53292d --- /dev/null +++ b/man3/nextafter.3 @@ -0,0 +1,210 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Based on glibc infopages +.\" +.TH NEXTAFTER 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \- +floating-point number manipulation +.SH SYNOPSIS +.B #include +.PP +.BI "double nextafter(double " x ", double " y ); +.br +.BI "float nextafterf(float " x ", float " y ); +.br +.BI "long double nextafterl(long double " x ", long double " y ); +.PP +.BI "double nexttoward(double " x ", long double " y ); +.br +.BI "float nexttowardf(float " x ", long double " y ); +.br +.BI "long double nexttowardl(long double " x ", long double " y ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR nextafter (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR nextafterf (), +.BR nextafterl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR nexttoward (), +.BR nexttowardf (), +.BR nexttowardl (): +.RS 4 +_XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE || +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad b +.SH DESCRIPTION +The +.BR nextafter (), +.BR nextafterf (), +and +.BR nextafterl () +functions return the next representable floating-point value following +.I x +in the direction of +.IR y . +If +.I y +is less than +.IR x , +these functions will return the largest representable number less than +.IR x . +.PP +If +.I x +equals +.IR y , +the functions return +.IR y . +.PP +The +.BR nexttoward (), +.BR nexttowardf (), +and +.BR nexttowardl () +functions do the same as the corresponding +.BR nextafter () +functions, except that they have a +.I "long double" +second argument. +.SH RETURN VALUE +On success, +these functions return the next representable floating-point value after +.I x +in the direction of +.IR y . +.PP +If +.I x +equals +.IR y , +then +.I y +(cast to the same type as +.IR x ) +is returned. +.PP +If +.I x +or +.I y +is a NaN, +a NaN is returned. +.PP +If +.I x +is finite, +.\" e.g., DBL_MAX +and the result would overflow, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.PP +If +.I x +is not equal to +.IR y , +and the correct function result would be subnormal, zero, or underflow, +a range error occurs, +and either the correct value (if it can be represented), +or 0.0, is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error: result overflow +.\" e.g., nextafter(DBL_MAX, HUGE_VAL); +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result is subnormal or underflows +.\" e.g., nextafter(DBL_MIN, 0.0); +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6799 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR nextafter (), +.BR nextafterf (), +.br +.BR nextafterl (), +.BR nexttoward (), +.br +.BR nexttowardf (), +.BR nexttowardl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH BUGS +In glibc version 2.5 and earlier, these functions do not raise an underflow +floating-point +.RB ( FE_UNDERFLOW ) +exception when an underflow occurs. +.SH SEE ALSO +.BR nearbyint (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/nextafterf.3 b/man3/nextafterf.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man3/nextafterf.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nextafterl.3 b/man3/nextafterl.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man3/nextafterl.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nextdown.3 b/man3/nextdown.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man3/nextdown.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man3/nextdownf.3 b/man3/nextdownf.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man3/nextdownf.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man3/nextdownl.3 b/man3/nextdownl.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man3/nextdownl.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man3/nexttoward.3 b/man3/nexttoward.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man3/nexttoward.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nexttowardf.3 b/man3/nexttowardf.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man3/nexttowardf.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nexttowardl.3 b/man3/nexttowardl.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man3/nexttowardl.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man3/nextup.3 b/man3/nextup.3 new file mode 100644 index 0000000..7108927 --- /dev/null +++ b/man3/nextup.3 @@ -0,0 +1,120 @@ +.\" Copyright (C) 2016, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH NEXTUP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +nextup, nextupf, nextupl, nextdown, nextdownf, nextdownl \- +return next floating-point number toward positive/negative infinity +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "double nextup(double " x ); +.BI "float nextupf(float " x ); +.BI "long double nextupl(long double " x ); +.PP +.BI "double nextdown(double " x ); +.BI "float nextdownf(float " x ); +.BI "long double nextdownl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +The +.BR nextup (), +.BR nextupf (), +and +.BR nextupl () +functions return the next representable floating-point number greater than +.IR x . +.PP +If +.I x +is the smallest representable negative number in the corresponding type, +these functions return \-0. +If +.I x +is 0, the returned value is the smallest representable positive number +of the corresponding type. +.PP +If +.I x +is positive infinity, the returned value is positive infinity. +If +.I x +is negative infinity, +the returned value is the largest representable finite negative number +of the corresponding type. +.PP +If +.I x +is Nan, +the returned value is NaN. +.PP +The value returned by +.IR nextdown(x) +is +.IR \-nextup(\-x) , +and similarly for the other types. +.SH RETURN VALUE +See DESCRIPTION. +.\" .SH ERRORS +.SH VERSIONS +These functions first appeared in glibc in version 2.24. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw36 lb lb +l l l. +Interface Attribute Value +T{ +.BR nextup (), +.BR nextupf (), +.BR nextupl (), +.br +.BR nextdown (), +.BR nextdownf (), +.BR nextdownl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are described in +.IR "IEEE Std 754-2008 - Standard for Floating-Point Arithmetic" +and +.IR "ISO/IEC TS 18661". +.SH SEE ALSO +.BR nearbyint (3), +.BR nextafter (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/nextupf.3 b/man3/nextupf.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man3/nextupf.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man3/nextupl.3 b/man3/nextupl.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man3/nextupl.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man3/nftw.3 b/man3/nftw.3 new file mode 100644 index 0000000..1a5c9c9 --- /dev/null +++ b/man3/nftw.3 @@ -0,0 +1 @@ +.so man3/ftw.3 diff --git a/man3/nl_langinfo.3 b/man3/nl_langinfo.3 new file mode 100644 index 0000000..e37f07b --- /dev/null +++ b/man3/nl_langinfo.3 @@ -0,0 +1,231 @@ +.\" Copyright (c) 2001 Markus Kuhn +.\" and Copyright (c) 2015 Sam Varshavchik +.\" and Copyright (c) 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 manual +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Corrected prototype, 2002-10-18, aeb +.\" +.TH NL_LANGINFO 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +nl_langinfo, nl_langinfo_l \- query language and locale information +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *nl_langinfo(nl_item " item ); +.PP +.BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR nl_langinfo_l (): +.RS 4 +Since glibc 2.24: + _POSIX_C_SOURCE\ >=\ 200809L +.br +Glibc 2.23 and earlier: + _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad b +.SH DESCRIPTION +The +.BR nl_langinfo () +and +.BR nl_langinfo_l () +functions provide access to locale information +in a more flexible way than +.BR localeconv (3). +.BR nl_langinfo() +returns a string which is the value corresponding to +\fIitem\fP in the program's current global +locale. +.BR nl_langinfo() +returns a string which is the value corresponding to \fIitem\fP +for the locale identified by the locale object \fIlocale\fP, +which was previously created by +.BR newlocale (1). +Individual and additional elements of the locale categories can +be queried. +.PP +Examples for the locale elements that can be specified in \fIitem\fP +using the constants defined in \fI\fP are: +.TP +.BR CODESET \ (LC_CTYPE) +Return a string with the name of the character encoding used in the +selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968" +(better known as US-ASCII). +This is the same string that you get with +"locale charmap". +For a list of character encoding names, +try "locale \-m" (see +.BR locale (1)). +.TP +.BR D_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent time and date in a locale-specific way. +.TP +.BR D_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a date in a locale-specific way. +.TP +.BR T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a time in a locale-specific way. +.TP +.BR DAY_ "{1\(en7} (LC_TIME)" +Return name of the \fIn\fP-th day of the week. [Warning: this follows +the US convention DAY_1 = Sunday, not the international convention +(ISO 8601) that Monday is the first day of the week.] +.TP +.BR ABDAY_ "{1\(en7} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th day of the week. +.TP +.BR MON_ "{1\(en12} (LC_TIME)" +Return name of the \fIn\fP-th month. +.TP +.BR ABMON_ "{1\(en12} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th month. +.TP +.BR RADIXCHAR \ (LC_NUMERIC) +Return radix character (decimal dot, decimal comma, etc.). +.TP +.BR THOUSEP \ (LC_NUMERIC) +Return separator character for thousands (groups of three digits). +.TP +.BR YESEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a positive response to a yes/no question. +.TP +.BR NOEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a negative response to a yes/no question. +.TP +.BR CRNCYSTR \ (LC_MONETARY) +Return the currency symbol, preceded by "\-" if the symbol should +appear before the value, "+" if the symbol should appear after the +value, or "." if the symbol should replace the radix character. +.PP +The above list covers just some examples of items that can be requested. +For a more detailed list, consult +.IR "The GNU C Library Reference Manual" . +.SH RETURN VALUE +On success, these functions return a pointer to a string which +is the value corresponding to +.I item +in the specified locale. +.PP +If no locale has been selected by +.BR setlocale (3) +for the appropriate category, +.BR nl_langinfo () +return a pointer to the corresponding string in the "C" locale. +The same is true of +.BR nl_langinfo_l () +if +.I locale +specifies a locale where +.I langinfo +data is not defined. +.PP +If \fIitem\fP is not valid, a pointer to an empty string is returned. +.PP +The pointer returned by these functions may point to static data that +may be overwritten, or the pointer itself may be invalidated, +by a subsequent call to +.BR nl_langinfo (), +.BR nl_langinfo_l (), +or +.BR setlocale (3). +The same statements apply to +.BR nl_langinfo_l () +if the locale object referred to by +.I locale +is freed or modified by +.BR freelocale (3) +or +.BR newlocale (3). +.PP +POSIX specifies that the application may not modify +the string returned by these functions. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR nl_langinfo () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SUSv2. +.SH NOTES +The behavior of +.BR nl_langinfo_l () +is undefined if +.I locale +is the special locale object +.BR LC_GLOBAL_LOCALE +or is not a valid locale object handle. +.SH EXAMPLE +The following program sets the character type and the numeric locale +according to the environment and queries the terminal character set and +the radix character. +.PP +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + setlocale(LC_CTYPE, ""); + setlocale(LC_NUMERIC, ""); + + printf("%s\\n", nl_langinfo(CODESET)); + printf("%s\\n", nl_langinfo(RADIXCHAR)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR locale (1), +.BR localeconv (3), +.BR setlocale (3), +.BR charsets (7), +.BR locale (7) +.PP +The GNU C Library Reference Manual +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/nl_langinfo_l.3 b/man3/nl_langinfo_l.3 new file mode 100644 index 0000000..36c3e35 --- /dev/null +++ b/man3/nl_langinfo_l.3 @@ -0,0 +1 @@ +.so man3/nl_langinfo.3 diff --git a/man3/nrand48.3 b/man3/nrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man3/nrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/nrand48_r.3 b/man3/nrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man3/nrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/ntohl.3 b/man3/ntohl.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man3/ntohl.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man3/ntohs.3 b/man3/ntohs.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man3/ntohs.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man3/ntp_adjtime.3 b/man3/ntp_adjtime.3 new file mode 100644 index 0000000..b08b9c8 --- /dev/null +++ b/man3/ntp_adjtime.3 @@ -0,0 +1 @@ +.so man2/adjtimex.2 diff --git a/man3/ntp_gettime.3 b/man3/ntp_gettime.3 new file mode 100644 index 0000000..c337406 --- /dev/null +++ b/man3/ntp_gettime.3 @@ -0,0 +1,158 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH NTP_GETTIME 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ntp_gettime, ntp_gettimex \- get time parameters (NTP daemon interface) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int ntp_gettime(struct ntptimeval *" ntv ); +.PP +.BI "int ntp_gettimex(struct ntptimeval *" ntv ); +.fi +.SH DESCRIPTION +Both of these APIs return information to the caller via the +.I ntv +argument, a structure of the following type: +.PP +.in +4n +.EX +struct ntptimeval { + struct timeval time; /* Current time */ + long int maxerror; /* Maximum error */ + long int esterror; /* Estimated error */ + long int tai; /* TAI offset */ + + /* Further padding bytes allowing for future expansion */ +}; +.EE +.in +.PP +The fields of this structure are as follows: +.TP +.I time +The current time, expressed as a +.I timeval +structure: +.IP +.in +4n +.EX +struct timeval { + time_t tv_sec; /* Seconds since the Epoch */ + suseconds_t tv_usec; /* Microseconds */ +}; +.EE +.in +.IP +.TP +.I maxerror +Maximum error, in microseconds. +This value can be initialized by +.BR ntp_adjtime (3), +and is increased periodically (on Linux: each second), +but is clamped to an upper limit (the kernel constant +.BR NTP_PHASE_MAX , +with a value of 16,000). +.TP +.I esterror +Estimated error, in microseconds. +This value can be set via +.BR ntp_adjtime (3) +to contain an estimate of the difference between the system clock +and the true time. +This value is not used inside the kernel. +.TP +.I tai +TAI (Atomic International Time) offset. +.PP +.BR ntp_gettime () +returns an +.I ntptimeval +structure in which the +.IR time , +.IR maxerror , +and +.IR esterror +fields are filled in. +.PP +.BR ntp_gettimex () +performs the same task as +.BR ntp_gettime (), +but also returns information in the +.I tai +field. +.SH RETURN VALUE +The return values for +.BR ntp_gettime () +and +.BR ntp_gettimex () +are as for +.BR adjtimex (2). +Given a correct pointer argument, these functions always succeed. +.\" FIXME . the info page incorrectly describes the return values. +.SH VERSIONS +The +.BR ntp_gettime () +function is available since glibc 2.1. +The +.BR ntp_gettimex () +function is available since glibc 2.12. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR ntp_gettime (), +.BR ntp_gettimex () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR ntp_gettime () +is described in the NTP Kernel Application Program Interface. +.BR ntp_gettimex () +is a GNU extension. +.SH SEE ALSO +.BR adjtimex (2) +.BR ntp_adjtime (3), +.BR time (7) +.PP +.ad l +.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm +NTP "Kernel Application Program Interface" +.UE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ntp_gettimex.3 b/man3/ntp_gettimex.3 new file mode 100644 index 0000000..142d76b --- /dev/null +++ b/man3/ntp_gettimex.3 @@ -0,0 +1 @@ +.so man3/ntp_gettime.3 diff --git a/man3/offsetof.3 b/man3/offsetof.3 new file mode 100644 index 0000000..47cce85 --- /dev/null +++ b/man3/offsetof.3 @@ -0,0 +1,112 @@ +.\" Copyright (C) 2006 Justin Pryzby +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" /usr/lib/gcc/i486-linux-gnu/4.1.1/include/stddef.h +.\" glibc-doc +.TH OFFSETOF 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +offsetof \- offset of a structure member +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t offsetof(" type ", " member ); +.fi +.SH DESCRIPTION +The macro +.BR offsetof () +returns the offset of the field +.I member +from the start of the structure +.IR type . +.PP +This macro is useful because the sizes of the fields that compose +a structure can vary across implementations, +and compilers may insert different numbers of padding +bytes between fields. +Consequently, an element's offset is not necessarily +given by the sum of the sizes of the previous elements. +.PP +A compiler error will result if +.I member +is not aligned to a byte boundary +(i.e., it is a bit field). +.SH RETURN VALUE +.BR offsetof () +returns the offset of the given +.I member +within the given +.IR type , +in units of bytes. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.SH EXAMPLE +On a Linux/i386 system, when compiled using the default +.BR gcc (1) +options, the program below produces the following output: +.PP +.in +4n +.EX +.RB "$" " ./a.out" +offsets: i=0; c=4; d=8 a=16 +sizeof(struct s)=16 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include + +int +main(void) +{ + struct s { + int i; + char c; + double d; + char a[]; + }; + + /* Output is compiler dependent */ + + printf("offsets: i=%zd; c=%zd; d=%zd a=%zd\\n", + offsetof(struct s, i), offsetof(struct s, c), + offsetof(struct s, d), offsetof(struct s, a)); + printf("sizeof(struct s)=%zd\\n", sizeof(struct s)); + + exit(EXIT_SUCCESS); +} +.EE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/on_exit.3 b/man3/on_exit.3 new file mode 100644 index 0000000..e6b4382 --- /dev/null +++ b/man3/on_exit.3 @@ -0,0 +1,115 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-04-02, David Metcalfe +.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) +.TH ON_EXIT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +on_exit \- register a function to be called at normal process termination +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int on_exit(void (*" function ")(int , void *), void *" arg ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR on_exit (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +The +.BR on_exit () +function registers the given +.I function +to be +called at normal process termination, whether via +.BR exit (3) +or via return from the program's +.IR main (). +The +.I function +is passed the status argument given to the last call to +.BR exit (3) +and the +.I arg +argument from +.BR on_exit (). +.PP +The same function may be registered multiple times: +it is called once for each registration. +.PP +When a child process is created via +.BR fork (2), +it inherits copies of its parent's registrations. +Upon a successful call to one of the +.BR exec (3) +functions, all registrations are removed. +.SH RETURN VALUE +The +.BR on_exit () +function returns the value 0 if successful; otherwise +it returns a nonzero value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR on_exit () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +This function comes from SunOS 4, but is also present in glibc. +It no longer occurs in Solaris (SunOS 5). +Portable application should avoid this function, and use the standard +.BR atexit (3) +instead. +.SH SEE ALSO +.BR _exit (2), +.BR atexit (3), +.BR exit (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/open_memstream.3 b/man3/open_memstream.3 new file mode 100644 index 0000000..ab5e117 --- /dev/null +++ b/man3/open_memstream.3 @@ -0,0 +1,154 @@ +.\" Copyright 2005, 2012, 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under the GPL. +.\" %%%LICENSE_END +.\" +.\" 2008-12-04, Petr Baudis : Document open_wmemstream() +.\" +.TH OPEN_MEMSTREAM 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +open_memstream, open_wmemstream \- open a dynamic memory buffer stream +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc ); + +.B #include +.PP +.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR open_memstream (), +.BR open_wmemstream (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR open_memstream () +function opens a stream for writing to a memory buffer. +The function dynamically allocates the buffer, +and the buffer automatically grows as needed. +Initially, the buffer has a size of zero. +After closing the stream, the caller should +.BR free (3) +this buffer. +.PP +The locations pointed to by +.IR ptr +and +.I sizeloc +are used to report, respectively, +the current location and the size of the buffer. +The locations referred to by these pointers are updated +each time the stream is flushed +.RB ( fflush (3)) +and when the stream is closed +.RB ( fclose (3)). +These values remain valid only as long as the caller +performs no further output on the stream. +If further output is performed, then the stream +must again be flushed before trying to access these values. +.PP +A null byte is maintained at the end of the buffer. +This byte is +.I not +included in the size value stored at +.IR sizeloc . +.PP +The stream maintains the notion of a current position, +which is initially zero (the start of the buffer). +Each write operation implicitly adjusts the buffer position. +The stream's buffer position can be explicitly changed with +.BR fseek (3) +or +.BR fseeko (3). +Moving the buffer position past the end +of the data already written fills the intervening space with +null characters. +.PP +The +.BR open_wmemstream () +is similar to +.BR open_memstream (), +but operates on wide characters instead of bytes. +.SH RETURN VALUE +Upon successful completion, +.BR open_memstream () +and +.BR open_wmemstream () +return a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH VERSIONS +.BR open_memstream () +was already available in glibc 1.0.x. +.BR open_wmemstream () +is available since glibc 2.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR open_memstream (), +.br +.BR open_wmemstream +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2008. +These functions are not specified in POSIX.1-2001, +and are not widely available on other systems. +.SH NOTES +There is no file descriptor associated with the file stream +returned by these functions +(i.e., +.BR fileno (3) +will return an error if called on the returned stream). +.SH BUGS +In glibc before version 2.7, seeking past the end of a stream created by +.BR open_memstream () +does not enlarge the buffer; instead the +.BR fseek (3) +call fails, returning \-1. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996 +.SH EXAMPLE +See +.BR fmemopen (3). +.SH SEE ALSO +.BR fmemopen (3), +.BR fopen (3), +.BR setbuf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/open_wmemstream.3 b/man3/open_wmemstream.3 new file mode 100644 index 0000000..a113f13 --- /dev/null +++ b/man3/open_wmemstream.3 @@ -0,0 +1 @@ +.so man3/open_memstream.3 diff --git a/man3/opendir.3 b/man3/opendir.3 new file mode 100644 index 0000000..3228a49 --- /dev/null +++ b/man3/opendir.3 @@ -0,0 +1,172 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:46:01 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-07-30 Ulrich Drepper : document fdopendir(). +.TH OPENDIR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +opendir, fdopendir \- open a directory +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "DIR *opendir(const char *" name ); +.BI "DIR *fdopendir(int " fd ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR fdopendir (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR opendir () +function opens a directory stream corresponding to the +directory \fIname\fP, and returns a pointer to the directory stream. +The stream is positioned at the first entry in the directory. +.PP +The +.BR fdopendir () +function +is like +.BR opendir (), +but returns a directory stream for the directory referred +to by the open file descriptor +.IR fd . +After a successful call to +.BR fdopendir (), +.I fd +is used internally by the implementation, +and should not otherwise be used by the application. +.SH RETURN VALUE +The +.BR opendir () +and +.BR fdopendir () +functions return a pointer to the directory stream. +On error, NULL is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Permission denied. +.TP +.B EBADF +.I fd +is not a valid file descriptor opened for reading. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +Directory does not exist, or \fIname\fP is an empty string. +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.TP +.B ENOTDIR +\fIname\fP is not a directory. +.SH VERSIONS +.BR fdopendir () +is available in glibc since version 2.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw22 lb lb +l l l. +Interface Attribute Value +T{ +.BR opendir (), +.BR fdopendir () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR opendir () +is present on SVr4, 4.3BSD, and specified in POSIX.1-2001. +.BR fdopendir () +is specified in POSIX.1-2008. +.SH NOTES +Filename entries can be read from a directory stream using +.BR readdir (3). +.PP +The underlying file descriptor of the directory stream can be obtained using +.BR dirfd (3). +.PP +The +.BR opendir () +function sets the close-on-exec flag for the file descriptor underlying the +.IR "DIR *" . +The +.BR fdopendir () +function leaves the setting of the close-on-exec +flag unchanged for the file descriptor, +.IR fd . +POSIX.1-200x leaves it unspecified whether a successful call to +.BR fdopendir () +will set the close-on-exec flag for the file descriptor, +.IR fd . +.SH SEE ALSO +.BR open (2), +.BR closedir (3), +.BR dirfd (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/openlog.3 b/man3/openlog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man3/openlog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man3/openpty.3 b/man3/openpty.3 new file mode 100644 index 0000000..0b9ab30 --- /dev/null +++ b/man3/openpty.3 @@ -0,0 +1,208 @@ +.\" Copyright (c) OpenBSD Group +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" Converted into a manpage again by Martin Schulze +.\" +.\" Added -lutil remark, 030718 +.\" +.TH OPENPTY 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +openpty, login_tty, forkpty \- terminal utility functions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int openpty(int *" amaster ", int *" aslave ", char *" name , +.BI " const struct termios *" termp , +.BI " const struct winsize *" winp ); +.PP +.BI "pid_t forkpty(int *" amaster ", char *" name , +.BI " const struct termios *" termp , +.BI " const struct winsize *" winp ); + +.B #include +.PP +.BI "int login_tty(int " fd ); +.PP +Link with \fI\-lutil\fP. +.fi +.SH DESCRIPTION +The +.BR openpty () +function finds an available pseudoterminal and returns file descriptors +for the master and slave in +.I amaster +and +.IR aslave . +If +.I name +is not NULL, the filename of the slave is returned in +.IR name . +If +.I termp +is not NULL, the terminal parameters of the slave will be set to the +values in +.IR termp . +If +.I winp +is not NULL, the window size of the slave will be set to the values in +.IR winp . +.PP +The +.BR login_tty () +function prepares for a login on the terminal +.I fd +(which may be a real terminal device, or the slave of a pseudoterminal as +returned by +.BR openpty ()) +by creating a new session, making +.I fd +the controlling terminal for the calling process, setting +.I fd +to be the standard input, output, and error streams of the current +process, and closing +.IR fd . +.PP +The +.BR forkpty () +function combines +.BR openpty (), +.BR fork (2), +and +.BR login_tty () +to create a new process operating in a pseudoterminal. +The file +descriptor of the master side of the pseudoterminal is returned in +.IR amaster . +If +.I name +is not NULL, the buffer it points to is used to return the +filename of the slave. +The +.I termp +and +.I winp +arguments, if not NULL, +will determine the terminal attributes and window size of the slave +side of the pseudoterminal. +.SH RETURN VALUE +If a call to +.BR openpty (), +.BR login_tty (), +or +.BR forkpty () +is not successful, \-1 is returned and +.I errno +is set to indicate the error. +Otherwise, +.BR openpty (), +.BR login_tty (), +and the child process of +.BR forkpty () +return 0, and the parent process of +.BR forkpty () +returns the process ID of the child process. +.SH ERRORS +.BR openpty () +fails if: +.TP +.B ENOENT +There are no available terminals. +.PP +.BR login_tty () +fails if +.BR ioctl (2) +fails to set +.I fd +to the controlling terminal of the calling process. +.PP +.BR forkpty () +fails if either +.BR openpty () +or +.BR fork (2) +fails. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR forkpty (), +.BR openpty () +T} Thread safety MT-Safe locale +T{ +.BR login_tty () +T} Thread safety MT-Unsafe race:ttyname +.TE +.sp 1 +.SH CONFORMING TO +These are BSD functions, present in glibc. +They are not standardized in POSIX. +.SH NOTES +The +.B const +modifiers were added to the structure pointer arguments of +.BR openpty () +and +.BR forkpty () +in glibc 2.8. +.PP +In versions of glibc before 2.0.92, +.BR openpty () +returns file descriptors for a BSD pseudoterminal pair; +since glibc 2.0.92, +it first attempts to open a UNIX 98 pseudoterminal pair, +and falls back to opening a BSD pseudoterminal pair if that fails. +.SH BUGS +Nobody knows how much space should be reserved for +.IR name . +So, calling +.BR openpty () +or +.BR forkpty () +with non-NULL +.I name +may not be secure. +.SH SEE ALSO +.BR fork (2), +.BR ttyname (3), +.BR pty (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/optarg.3 b/man3/optarg.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man3/optarg.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man3/opterr.3 b/man3/opterr.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man3/opterr.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man3/optind.3 b/man3/optind.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man3/optind.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man3/optopt.3 b/man3/optopt.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man3/optopt.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man3/passwd2des.3 b/man3/passwd2des.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man3/passwd2des.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man3/pathconf.3 b/man3/pathconf.3 new file mode 100644 index 0000000..46d8c8b --- /dev/null +++ b/man3/pathconf.3 @@ -0,0 +1 @@ +.so man3/fpathconf.3 diff --git a/man3/pclose.3 b/man3/pclose.3 new file mode 100644 index 0000000..663d4a0 --- /dev/null +++ b/man3/pclose.3 @@ -0,0 +1 @@ +.so man3/popen.3 diff --git a/man3/perror.3 b/man3/perror.3 new file mode 100644 index 0000000..6821b51 --- /dev/null +++ b/man3/perror.3 @@ -0,0 +1,165 @@ +.\" Copyright (c) 1994 Michael Haardt (michael@moria.de), 1994-06-04 +.\" Copyright (c) 1995 Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de), 1995-03-16 +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl), 1996-01-13 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1996-01-13 aeb: merged in some text contributed by Melvin Smith +.\" (msmith@falcon.mercer.peachnet.edu) and various other changes. +.\" Modified 1996-05-16 by Martin Schulze (joey@infodrom.north.de) +.\" +.TH PERROR 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +perror \- print a system error message +.SH SYNOPSIS +.B #include +.PP +.BI "void perror(const char *" s ); + +.B #include +.PP +.BI "const char * const " sys_errlist []; +.br +.BI "int " sys_nerr ; +.br +.BI "int " errno "; \fR/* Not really declared this way; see errno(3) */" +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.IR sys_errlist , +.IR sys_nerr : + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The +.BR perror () +function produces a message on standard error describing the last +error encountered during a call to a system or library function. +.PP +First (if +.I s +is not NULL and +.I *s +is not a null byte (\(aq\\0\(aq)), the argument string +.I s +is printed, followed by a colon and a blank. +Then an error message corresponding to the current value of +.I errno +and a new-line. +.PP +To be of most use, the argument string should include the name +of the function that incurred the error. +.PP +The global error list +.IR sys_errlist "[]," +which can be indexed by +.IR errno , +can be used to obtain the error message without the newline. +The largest message number provided in the table is +.IR sys_nerr "\-1." +Be careful when directly accessing this list, because new error values +may not have been added to +.IR sys_errlist "[]." +The use of +.IR sys_errlist "[]" +is nowadays deprecated; use +.BR strerror (3) +instead. +.PP +When a system call fails, it usually returns \-1 and sets the +variable +.I errno +to a value describing what went wrong. +(These values can be found in +.IR .) +Many library functions do likewise. +The function +.BR perror () +serves to translate this error code into human-readable form. +Note that +.I errno +is undefined after a successful system call or library function call: +this call may well change this variable, even though it succeeds, +for example because it internally used some other library function that failed. +Thus, if a failing call is not immediately followed by a call to +.BR perror (), +the value of +.I errno +should be saved. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR perror () +T} Thread safety MT-Safe race:stderr +.TE +.sp 1 +.SH CONFORMING TO +.BR perror (), +.IR errno : +POSIX.1-2001, POSIX.1-2008, C89, C99, 4.3BSD. +.PP +The externals +.I sys_nerr +and +.I sys_errlist +derive from BSD, but are not specified in POSIX.1. +.SH NOTES +The externals +.I sys_nerr +and +.I sys_errlist +are defined by glibc, but in +.IR . +.\" and only when _BSD_SOURCE is defined. +.\" When +.\" .B _GNU_SOURCE +.\" is defined, the symbols +.\" .I _sys_nerr +.\" and +.\" .I _sys_errlist +.\" are provided. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR error (3), +.BR strerror (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pmap_getmaps.3 b/man3/pmap_getmaps.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/pmap_getmaps.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/pmap_getport.3 b/man3/pmap_getport.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/pmap_getport.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/pmap_rmtcall.3 b/man3/pmap_rmtcall.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/pmap_rmtcall.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/pmap_set.3 b/man3/pmap_set.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/pmap_set.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/pmap_unset.3 b/man3/pmap_unset.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/pmap_unset.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/popen.3 b/man3/popen.3 new file mode 100644 index 0000000..a6ba452 --- /dev/null +++ b/man3/popen.3 @@ -0,0 +1,242 @@ +.\" Copyright 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)popen.3 6.4 (Berkeley) 4/30/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu +.\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de) +.\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" +.TH POPEN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +popen, pclose \- pipe stream to or from a process +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "FILE *popen(const char *" command ", const char *" type ); +.PP +.BI "int pclose(FILE *" stream ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR popen (), +.BR pclose (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 2 + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR popen () +function opens a process by creating a pipe, forking, and invoking the +shell. +Since a pipe is by definition unidirectional, the +.I type +argument may specify only reading or writing, not both; the resulting +stream is correspondingly read-only or write-only. +.PP +The +.I command +argument is a pointer to a null-terminated string containing a shell +command line. +This command is passed to +.I /bin/sh +using the +.B \-c +flag; interpretation, if any, is performed by the shell. +.PP +The +.I type +argument is a pointer to a null-terminated string which must contain +either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing. +Since glibc 2.9, +this argument can additionally include the letter \(aqe\(aq, +which causes the close-on-exec flag +.RB ( FD_CLOEXEC ) +to be set on the underlying file descriptor; +see the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.PP +The return value from +.BR popen () +is a normal standard I/O stream in all respects save that it must be closed +with +.BR pclose () +rather than +.BR fclose (3). +Writing to such a stream writes to the standard input of the command; the +command's standard output is the same as that of the process that called +.BR popen (), +unless this is altered by the command itself. +Conversely, reading from +the stream reads the command's standard output, and the command's +standard input is the same as that of the process that called +.BR popen (). +.PP +Note that output +.BR popen () +streams are block buffered by default. +.PP +The +.BR pclose () +function waits for the associated process to terminate and returns the exit +status of the command as returned by +.BR wait4 (2). +.SH RETURN VALUE +.BR popen (): +on success, returns a pointer to an open stream that +can be used to read or write to the pipe; +if the +.BR fork (2) +or +.BR pipe (2) +calls fail, or if the function cannot allocate memory, +NULL is returned. +.PP +.BR pclose (): +on success, returns the exit status of the command; if +.\" These conditions actually give undefined results, so I commented +.\" them out. +.\" .I stream +.\" is not associated with a "popen()ed" command, if +.\".I stream +.\" already "pclose()d", or if +.BR wait4 (2) +returns an error, or some other error is detected, +\-1 is returned. +.PP +Both functions set +.I errno +to an appropriate value in the case of an error. +.SH ERRORS +The +.BR popen () +function does not set +.I errno +if memory allocation fails. +If the underlying +.BR fork (2) +or +.BR pipe (2) +fails, +.I errno +is set appropriately. +If the +.I type +argument is invalid, and this condition is detected, +.I errno +is set to +.BR EINVAL . +.PP +If +.BR pclose () +cannot obtain the child status, +.I errno +is set to +.BR ECHILD . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw17 lb lb +l l l. +Interface Attribute Value +T{ +.BR popen (), +.BR pclose () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.PP +The \(aqe\(aq value for +.I type +is a Linux extension. +.SH NOTES +.BR Note : +carefully read Caveats in +.BR system (3). +.SH BUGS +Since the standard input of a command opened for reading shares its seek +offset with the process that called +.BR popen (), +if the original process has done a buffered read, the command's input +position may not be as expected. +Similarly, the output from a command +opened for writing may become intermingled with that of the original +process. +The latter can be avoided by calling +.BR fflush (3) +before +.BR popen (). +.PP +Failure to execute the shell is indistinguishable from the shell's failure +to execute command, or an immediate exit of the command. +The only hint is an exit status of 127. +.\" .SH HISTORY +.\" A +.\" .BR popen () +.\" and a +.\" .BR pclose () +.\" function appeared in Version 7 AT&T UNIX. +.SH SEE ALSO +.BR sh (1), +.BR fork (2), +.BR pipe (2), +.BR wait4 (2), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR stdio (3), +.BR system (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/posix_fallocate.3 b/man3/posix_fallocate.3 new file mode 100644 index 0000000..b3aaa08 --- /dev/null +++ b/man3/posix_fallocate.3 @@ -0,0 +1,194 @@ +.\" Copyright (c) 2006, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH POSIX_FALLOCATE 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +posix_fallocate \- allocate file space +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len ); +.fi +.PP +.ad l +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR posix_fallocate (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +The function +.BR posix_fallocate () +ensures that disk space is allocated for the file referred to by the +file descriptor +.I fd +for the bytes in the range starting at +.I offset +and continuing for +.I len +bytes. +After a successful call to +.BR posix_fallocate (), +subsequent writes to bytes in the specified range are +guaranteed not to fail because of lack of disk space. +.PP +If the size of the file is less than +.IR offset + len , +then the file is increased to this size; +otherwise the file size is left unchanged. +.SH RETURN VALUE +.BR posix_fallocate () +returns zero on success, or an error number on failure. +Note that +.I errno +is not set. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor, or is not opened for writing. +.TP +.B EFBIG +.I offset+len +exceeds the maximum file size. +.TP +.B EINTR +A signal was caught during execution. +.TP +.B EINVAL +.I offset +was less than 0, or +.I len +was less than or equal to 0, or the underlying filesystem does not +support the operation. +.TP +.B ENODEV +.I fd +does not refer to a regular file. +.TP +.B ENOSPC +There is not enough space left on the device containing the file +referred to by +.IR fd . +.TP +.B ESPIPE +.I fd +refers to a pipe. +.SH VERSIONS +.BR posix_fallocate () +is available since glibc 2.1.94. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR posix_fallocate () +T} Thread safety MT-Safe (but see NOTES) +.TE +.SH CONFORMING TO +POSIX.1-2001. +.PP +POSIX.1-2008 says that an implementation +.I shall +give the +.B EINVAL +error if +.I len +was 0, or +.I offset +was less than 0. +POSIX.1-2001 says that an implementation +.I shall +give the +.B EINVAL +error if +.I len +is less than 0, or +.I offset +was less than 0, and +.I may +give the error if +.I len +equals zero. +.SH NOTES +In the glibc implementation, +.BR posix_fallocate () +is implemented using the +.BR fallocate (2) +system call, which is MT-safe. +If the underlying filesystem does not support +.BR fallocate (2), +then the operation is emulated with the following caveats: +.IP * 2 +The emulation is inefficient. +.IP * +There is a race condition where concurrent writes from another thread or +process could be overwritten with null bytes. +.IP * +There is a race condition where concurrent file size increases by +another thread or process could result in a file whose size is smaller +than expected. +.IP * +If +.I fd +has been opened with the +.B O_APPEND +or +.B O_WRONLY +flags, the function fails with the error +.BR EBADF . +.PP +In general, the emulation is not MT-safe. +On Linux, applications may use +.BR fallocate (2) +if they cannot tolerate the emulation caveats. +In general, this is +only recommended if the application plans to terminate the operation if +.B EOPNOTSUPP +is returned, otherwise the application itself will need to implement a +fallback with all the same problems as the emulation provided by glibc. +.SH SEE ALSO +.BR fallocate (1), +.BR fallocate (2), +.BR lseek (2), +.BR posix_fadvise (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/posix_madvise.3 b/man3/posix_madvise.3 new file mode 100644 index 0000000..a776201 --- /dev/null +++ b/man3/posix_madvise.3 @@ -0,0 +1,137 @@ +.\" Copyright (C) 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+) +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH POSIX_MADVISE 3 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +posix_madvise \- give advice about patterns of memory usage +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int posix_madvise(void *" addr ", size_t " len ", int " advice ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR posix_madvise (): +.br +.RS 4 +.ad l +_POSIX_C_SOURCE >= 200112L +.RE +.ad +.SH DESCRIPTION +The +.BR posix_madvise () +function allows an application to advise the system about its expected +patterns of usage of memory in the address range starting at +.I addr +and continuing for +.I len +bytes. +The system is free to use this advice in order to improve the performance +of memory accesses (or to ignore the advice altogether), but calling +.BR posix_madvise () +shall not affect the semantics of access to memory in the specified range. +.PP +The +.I advice +argument is one of the following: +.TP +.B POSIX_MADV_NORMAL +The application has no special advice regarding its memory usage patterns +for the specified address range. +This is the default behavior. +.TP +.B POSIX_MADV_SEQUENTIAL +The application expects to access the specified address range sequentially, +running from lower addresses to higher addresses. +Hence, pages in this region can be aggressively read ahead, +and may be freed soon after they are accessed. +.TP +.B POSIX_MADV_RANDOM +The application expects to access the specified address range randomly. +Thus, read ahead may be less useful than normally. +.TP +.B POSIX_MADV_WILLNEED +The application expects to access the specified address range +in the near future. +Thus, read ahead may be beneficial. +.TP +.B POSIX_MADV_DONTNEED +The application expects that it will not access the specified address range +in the near future. +.SH RETURN VALUE +On success, +.BR posix_madvise () +returns 0. +On failure, it returns a positive error number. +.SH ERRORS +.TP +.B EINVAL +.I addr +is not a multiple of the system page size or +.I len +is negative. +.TP +.B EINVAL +.I advice +is invalid. +.TP +.B ENOMEM +Addresses in the specified range are partially or completely outside +the caller's address space. +.SH VERSIONS +Support for +.BR posix_madvise () +first appeared in glibc version 2.2. +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES +POSIX.1 permits an implementation to generate an error if +.I len +is 0. +On Linux, specifying +.I len +as 0 is permitted (as a successful no-op). +.PP +In glibc, this function is implemented using +.BR madvise (2). +However, since glibc 2.6, +.BR POSIX_MADV_DONTNEED +is treated as a no-op, because the corresponding +.BR madvise (2) +value, +.BR MADV_DONTNEED , +has destructive semantics. +.SH SEE ALSO +.BR madvise (2), +.BR posix_fadvise (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3 new file mode 100644 index 0000000..45f13e2 --- /dev/null +++ b/man3/posix_memalign.3 @@ -0,0 +1,312 @@ +.\" Copyright (c) 2001 by John Levon +.\" Based in part on GNU libc documentation. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2001-10-11, 2003-08-22, aeb, added some details +.\" 2012-03-23, Michael Kerrisk +.\" Document pvalloc() and aligned_alloc() +.TH POSIX_MEMALIGN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- allocate aligned memory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); +.BI "void *aligned_alloc(size_t " alignment ", size_t " size ); +.BI "void *valloc(size_t " size ); + +.B #include +.PP +.BI "void *memalign(size_t " alignment ", size_t " size ); +.BI "void *pvalloc(size_t " size ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR posix_memalign (): +_POSIX_C_SOURCE\ >=\ 200112L +.PP +.BR aligned_alloc (): +_ISOC11_SOURCE +.PP +.BR valloc (): +.br +.PD 0 +.RS 4 +.TP 4 +Since glibc 2.12: +.nf +(_XOPEN_SOURCE\ >=\ 500) && !(_POSIX_C_SOURCE\ >=\ 200112L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.br +.fi +.TP +Before glibc 2.12: +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.ad b +.br +(The (nonstandard) header file +.I +also exposes the declaration of +.BR valloc (); +no feature test macros are required.) +.RE +.PD +.SH DESCRIPTION +The function +.BR posix_memalign () +allocates +.I size +bytes and places the address of the allocated memory in +.IR "*memptr" . +The address of the allocated memory will be a multiple of +.IR "alignment" , +which must be a power of two and a multiple of +.IR "sizeof(void\ *)" . +If +.I size +is 0, then +the value placed in +.IR "*memptr" +is either NULL, +.\" glibc does this: +or a unique pointer value that can later be successfully passed to +.BR free (3). +.PP +The obsolete function +.BR memalign () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of +.IR alignment , +which must be a power of two. +.\" The behavior of memalign() for size==0 is as for posix_memalign() +.\" but no standards govern this. +.PP +The function +.BR aligned_alloc () +is the same as +.BR memalign (), +except for the added restriction that +.I size +should be a multiple of +.IR alignment . +.PP +The obsolete function +.BR valloc () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of the page size. +It is equivalent to +.IR "memalign(sysconf(_SC_PAGESIZE),size)" . +.PP +The obsolete function +.BR pvalloc () +is similar to +.BR valloc (), +but rounds the size of the allocation up to +the next multiple of the system page size. +.PP +For all of these functions, the memory is not zeroed. +.SH RETURN VALUE +.BR aligned_alloc (), +.BR memalign (), +.BR valloc (), +and +.BR pvalloc () +return a pointer to the allocated memory, or NULL if the request fails. +.PP +.BR posix_memalign () +returns zero on success, or one of the error values listed in the +next section on failure. +The value of +.I errno +is not set. +On Linux (and other systems), +.BR posix_memalign () +does not modify +.I memptr +on failure. +A requirement standardizing this behavior was added in POSIX.1-2016. +.\" http://austingroupbugs.net/view.php?id=520 +.SH ERRORS +.TP +.B EINVAL +The +.I alignment +argument was not a power of two, or was not a multiple of +.IR "sizeof(void\ *)" . +.TP +.B ENOMEM +There was insufficient memory to fulfill the allocation request. +.SH VERSIONS +The functions +.BR memalign (), +.BR valloc (), +and +.BR pvalloc () +have been available in all Linux libc libraries. +.PP +The function +.BR aligned_alloc () +was added to glibc in version 2.16. +.PP +The function +.BR posix_memalign () +is available since glibc 2.1.91. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR aligned_alloc (), +.br +.BR memalign (), +.br +.BR posix_memalign () +T} Thread safety MT-Safe +T{ +.BR valloc (), +.br +.BR pvalloc () +T} Thread safety MT-Unsafe init +.TE +.sp 1 +.SH CONFORMING TO +The function +.BR valloc () +appeared in 3.0BSD. +It is documented as being obsolete in 4.3BSD, +and as legacy in SUSv2. +It does not appear in POSIX.1. +.PP +The function +.BR pvalloc () +is a GNU extension. +.PP +The function +.BR memalign () +appears in SunOS 4.1.3 but not in 4.4BSD. +.PP +The function +.BR posix_memalign () +comes from POSIX.1d and is specified in POSIX.1-2001 and POSIX.1-2008. +.PP +The function +.BR aligned_alloc () +is specified in the C11 standard. +.\" +.SS Headers +Everybody agrees that +.BR posix_memalign () +is declared in \fI\fP. +.PP +On some systems +.BR memalign () +is declared in \fI\fP instead of \fI\fP. +.PP +According to SUSv2, +.BR valloc () +is declared in \fI\fP. +Libc4,5 and glibc declare it in \fI\fP, and also in +\fI\fP +if suitable feature test macros are defined (see above). +.SH NOTES +On many systems there are alignment restrictions, for example, on buffers +used for direct block device I/O. +POSIX specifies the +.I "pathconf(path,_PC_REC_XFER_ALIGN)" +call that tells what alignment is needed. +Now one can use +.BR posix_memalign () +to satisfy this requirement. +.PP +.BR posix_memalign () +verifies that +.I alignment +matches the requirements detailed above. +.BR memalign () +may not check that the +.I alignment +argument is correct. +.PP +POSIX requires that memory obtained from +.BR posix_memalign () +can be freed using +.BR free (3). +Some systems provide no way to reclaim memory allocated with +.BR memalign () +or +.BR valloc () +(because one can pass to +.BR free (3) +only a pointer obtained from +.BR malloc (3), +while, for example, +.BR memalign () +would call +.BR malloc (3) +and then align the obtained value). +.\" Other systems allow passing the result of +.\" .IR valloc () +.\" to +.\" .IR free (3), +.\" but not to +.\" .IR realloc (3). +The glibc implementation +allows memory obtained from any of these functions to be +reclaimed with +.BR free (3). +.PP +The glibc +.BR malloc (3) +always returns 8-byte aligned memory addresses, so these functions are +needed only if you require larger alignment values. +.SH SEE ALSO +.BR brk (2), +.BR getpagesize (2), +.BR free (3), +.BR malloc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/posix_openpt.3 b/man3/posix_openpt.3 new file mode 100644 index 0000000..a9fdfc2 --- /dev/null +++ b/man3/posix_openpt.3 @@ -0,0 +1,132 @@ +.\" Copyright (C) 2004 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH POSIX_OPENPT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +posix_openpt \- open a pseudoterminal device +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int posix_openpt(int " flags ");" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR posix_openpt (): +_XOPEN_SOURCE\ >=\ 600 +.ad b +.SH DESCRIPTION +The +.BR posix_openpt () +function opens an unused pseudoterminal master device, returning a +file descriptor that can be used to refer to that device. +.PP +The +.I flags +argument is a bit mask that ORs together zero or more of +the following flags: +.TP +.B O_RDWR +Open the device for both reading and writing. +It is usual to specify this flag. +.TP +.B O_NOCTTY +Do not make this device the controlling terminal for the process. +.SH RETURN VALUE +On success, +.BR posix_openpt () +returns a nonnegative file descriptor which is the lowest +numbered unused file descriptor. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +See +.BR open (2). +.SH VERSIONS +Glibc support for +.BR posix_openpt () +has been provided since version 2.2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR posix_openpt () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.PP +.BR posix_openpt () +is part of the UNIX 98 pseudoterminal support (see +.BR pts (4)). +.SH NOTES +Some older UNIX implementations that support System V +(aka UNIX 98) pseudoterminals don't have this function, but it +is easy to implement: +.PP +.in +4n +.EX +int +posix_openpt(int flags) +{ + return open("/dev/ptmx", flags); +} +.EE +.in +.PP +Calling +.BR posix_openpt () +creates a pathname for the corresponding pseudoterminal slave device. +The pathname of the slave device can be obtained using +.BR ptsname (3). +The slave device pathname exists only as long as the master device is open. +.SH SEE ALSO +.BR open (2), +.BR getpt (3), +.BR grantpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/posix_spawn.3 b/man3/posix_spawn.3 new file mode 100644 index 0000000..3877dd5 --- /dev/null +++ b/man3/posix_spawn.3 @@ -0,0 +1,817 @@ +.\" Copyright (c) 2009 Bill O. Gallmeister (bgallmeister@gmail.com) +.\" and Copyright 2010 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux glibc source code +.\" POSIX 1003.1-2004 documentation +.\" (http://www.opengroup.org/onlinepubs/009695399) +.\" +.TH POSIX_SPAWN 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +posix_spawn, posix_spawnp \- spawn a process +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int posix_spawn(pid_t *" pid ", const char *" path , +.BI " const posix_spawn_file_actions_t *" file_actions , +.BI " const posix_spawnattr_t *" attrp , +.BI " char *const " argv[] ", char *const " envp[] ); +.PP +.BI "int posix_spawnp(pid_t *" pid ", const char *" file , +.BI " const posix_spawn_file_actions_t *" file_actions , +.BI " const posix_spawnattr_t *" attrp , +.BI " char *const " argv[] ", char *const " envp[] ); +.fi +.SH DESCRIPTION +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions are used to create a new child process that executes +a specified file. +These functions were specified by POSIX to provide a standardized method +of creating new processes on machines that lack the capability +to support the +.BR fork (2) +system call. +These machines are generally small, embedded systems lacking MMU support. +.PP +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions provide the functionality of a combined +.BR fork (2) +and +.BR exec (3), +with some optional housekeeping steps in the child process before the +.BR exec (3). +These functions are not meant to replace the +.BR fork (2) +and +.BR execve (2) +system calls. +In fact, they provide only a subset of the functionality +that can be achieved by using the system calls. +.PP +The only difference between +.BR posix_spawn () +and +.BR posix_spawnp () +is the manner in which they specify the file to be executed by +the child process. +With +.BR posix_spawn (), +the executable file is specified as a pathname +(which can be absolute or relative). +With +.BR posix_spawnp (), +the executable file is specified as a simple filename; +the system searches for this file in the list of directories specified by +.BR PATH +(in the same way as for +.BR execvp (3)). +For the remainder of this page, the discussion is phrased in terms of +.BR posix_spawn (), +with the understanding that +.BR posix_spawnp () +differs only on the point just described. +.PP +The remaining arguments to these two functions are as follows: +.IP * 3 +The +.I pid +argument points to a buffer that is used to return the process ID +of the new child process. +.IP * +The +.I file_actions +argument points to a +.I "spawn file actions object" +that specifies file-related actions to be performed in the child +between the +.BR fork (2) +and +.BR exec (3) +steps. +This object is initialized and populated before the +.BR posix_spawn () +call using +.BR posix_spawn_file_actions_init (3) +and the +.BR posix_spawn_file_actions_* () +functions. +.IP * +The +.I attrp +argument points to an +.I attributes objects +that specifies various attributes of the created child process. +This object is initialized and populated before the +.BR posix_spawn () +call using +.BR posix_spawnattr_init (3) +and the +.BR posix_spawnattr_* () +functions. +.IP * +The +.I argv +and +.I envp +arguments specify the argument list and environment for the program +that is executed in the child process, as for +.BR execve (2). +.PP +Below, the functions are described in terms of a three-step process: the +.BR fork() +step, the +.RB pre- exec () +step (executed in the child), +and the +.BR exec () +step (executed in the child). +.SS fork() step +The +.BR posix_spawn () +function commences by calling +.BR fork (2), +or possibly +.BR vfork (2) +(see below). +.PP +The PID of the new child process is placed in +.IR *pid . +The +.BR posix_spawn () +function then returns control to the parent process. +.PP +Subsequently, the parent can use one of the system calls described in +.BR wait (2) +to check the status of the child process. +If the child fails in any of the housekeeping steps described below, +or fails to execute the desired file, +it exits with a status of 127. +.PP +The child process is created using +.BR vfork (2) +instead of +.BR fork (2) +when either of the following is true: +.IP * 3 +the +.I spawn-flags +element of the attributes object pointed to by +.I attrp +contains the GNU-specific flag +.BR POSIX_SPAWN_USEVFORK ; +or +.IP * +.I file_actions +is NULL and the +.I spawn-flags +element of the attributes object pointed to by +.I attrp +does \fInot\fP contain +.BR POSIX_SPAWN_SETSIGMASK , +.BR POSIX_SPAWN_SETSIGDEF , +.BR POSIX_SPAWN_SETSCHEDPARAM , +.BR POSIX_SPAWN_SETSCHEDULER , +.BR POSIX_SPAWN_SETPGROUP , +or +.BR POSIX_SPAWN_RESETIDS . +.PP +In other words, +.BR vfork (2) +is used if the caller requests it, +or if there is no cleanup expected in the child before it +.BR exec (3)s +the requested file. +.PP +.SS pre-exec() step: housekeeping +In between the +.BR fork (2) +and the +.BR exec (3), +a child process may need to perform a set of housekeeping actions. +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions support a small, well-defined set of system tasks that the child +process can accomplish before it executes the executable file. +These operations are controlled by the attributes object pointed to by +.IR attrp +and the file actions object pointed to by +.IR file_actions . +In the child, processing is done in the following sequence: +.IP 1. 3 +Process attribute actions: signal mask, signal default handlers, +scheduling algorithm and parameters, +process group, and effective user and group IDs +are changed as specified by the attributes object pointed to by +.IR attrp . +.IP 2. +File actions, as specified in the +.I file_actions +argument, +are performed in the order that they were specified using calls to the +.BR posix_spawn_file_actions_add* () +functions. +.IP 3. +File descriptors with the +.B FD_CLOEXEC +flag set are closed. +.PP +All process attributes in the child, +other than those affected by attributes specified in the +object pointed to by +.IR attrp +and the file actions in the object pointed to by +.IR file_actions , +will be affected as though the child was created with +.BR fork (2) +and it executed the program with +.BR execve (2). +.PP +The process attributes actions are defined by the attributes object +pointed to by +.IR attrp . +The +.I spawn-flags +attribute (set using +.BR posix_spawnattr_setflags (3)) +controls the general actions that occur, +and other attributes in the object specify values +to be used during those actions. +.PP +The effects of the flags that may be specified in +.IR spawn-flags +are as follows: +.TP 8 +.B POSIX_SPAWN_SETSIGMASK +Set the signal mask to the signal set specified in the +.I spawn-sigmask +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setsigmask (3)) +of the object pointed to by +.IR attrp . +If the +.B POSIX_SPAWN_SETSIGMASK +flag is not set, then the child inherits the parent's signal mask. +.TP +.B POSIX_SPAWN_SETSIGDEF +Reset the disposition of all signals in the set specified in the +.I spawn-sigdefault +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setsigdefault (3)) +of the object pointed to by +.IR attrp +to the default. +For the treatment of the dispositions of signals not specified in the +.I spawn-sigdefault +attribute, or the treatment when +.B POSIX_SPAWN_SETSIGDEF +is not specified, see +.BR execve (2). +.TP +.B POSIX_SPAWN_SETSCHEDPARAM +.\" (POSIX_PRIORITY_SCHEDULING only) +If this flag is set, and the +.B POSIX_SPAWN_SETSCHEDULER +flag is not set, then set the scheduling parameters +to the parameters specified in the +.I spawn-schedparam +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setschedparam (3)) +of the object pointed to by +.IR attrp . +.TP +.B POSIX_SPAWN_SETSCHEDULER +Set the scheduling policy algorithm and parameters of the child, +as follows: +.RS +.IP * 3 +The scheduling policy is set to the value specified in the +.I spawn-schedpolicy +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setpolicy (3)) +of the object pointed to by +.IR attrp . +.IP * +The scheduling parameters are set to the value specified in the +.I spawn-schedparam +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setschedparam (3)) +of the object pointed to by +.IR attrp +(but see BUGS). +.PP +If the +.B POSIX_SPAWN_SETSCHEDPARAM +and +.B POSIX_SPAWN_SETSCHEDPOLICY +flags are not specified, +the child inherits the corresponding scheduling attributes from the parent. +.RE +.TP +.B POSIX_SPAWN_RESETIDS +If this flag is set, +reset the effective UID and GID to the +real UID and GID of the parent process. +If this flag is not set, +then the child retains the effective UID and GID of the parent. +In either case, if the set-user-ID and set-group-ID permission +bits are enabled on the executable file, their effect will override +the setting of the effective UID and GID (se +.BR execve (2)). +.TP +.B POSIX_SPAWN_SETPGROUP +Set the process group to the value specified in the +.I spawn-pgroup +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setpgroup (3)) +of the object pointed to by +.IR attrp . +If the +.I spawn-pgroup +attribute has the value 0, +the child's process group ID is made the same as its process ID. +If the +.B POSIX_SPAWN_SETPGROUP +flag is not set, the child inherits the parent's process group ID. +.PP +If +.I attrp +is NULL, then the default behaviors described above for each flag apply. +.\" mtk: I think we probably don't want to say the following, since it +.\" could lead people to do the wrong thing +.\" The POSIX standard tells you to call +.\" this function to de-initialize the attributes object pointed to by +.\" .I attrp +.\" when you are done with it; +.\" however, on Linux systems this operation is a no-op. +.PP +The +.I file_actions +argument specifies a sequence of file operations +that are performed in the child process after +the general processing described above, and before it performs the +.BR exec (3). +If +.I file_actions +is NULL, then no special action is taken, and standard +.BR exec (3) +semantics apply--file descriptors open before the exec +remain open in the new process, +except those for which the +.B FD_CLOEXEC +flag has been set. +File locks remain in place. +.PP +If +.I file_actions +is not NULL, then it contains an ordered set of requests to +.BR open (2), +.BR close (2), +and +.BR dup2 (2) +files. +These requests are added to the +.I file_actions +by +.BR posix_spawn_file_actions_addopen (3), +.BR posix_spawn_file_actions_addclose (3), +and +.BR posix_spawn_file_actions_adddup2 (3). +The requested operations are performed in the order they were added to +.IR file_actions . +.\" FIXME . I think the following is best placed in the +.\" posix_spawn_file_actions_adddup2(3) page, and a similar statement is +.\" also needed in posix_spawn_file_actions_addclose(3) +.\" Note that you can specify file descriptors in +.\" .I posix_spawn_file_actions_adddup2 (3) +.\" which would not be usable if you called +.\" .BR dup2 (2) +.\" at that time--i.e., file descriptors that are opened or +.\" closed by the earlier operations +.\" added to +.\" .I file_actions . +.PP +If any of the housekeeping actions fails +(due to bogus values being passed or other reasons why signal handling, +process scheduling, process group ID functions, +and file descriptor operations might fail), +the child process exits with exit value 127. +.SS exec() step +Once the child has successfully forked and performed +all requested pre-exec steps, +the child runs the requested executable. +.PP +The child process takes its environment from the +.I envp +argument, which is interpreted as if it had been passed to +.BR execve (2). +The arguments to the created process come from the +.I argv +argument, which is processed as for +.BR execve (2). +.SH RETURN VALUE +Upon successful completion, +.BR posix_spawn () +and +.BR posix_spawnp () +place the PID of the child process in +.IR pid , +and return 0. +If there is an error before or during the +.BR fork (2), +then no child is created, +the contents of +.IR *pid +are unspecified, +and these functions return an error number as described below. +.PP +Even when these functions return a success status, +the child process may still fail for a plethora of reasons related to its +pre-\fBexec\fR() initialization. +In addition, the +.BR exec (3) +may fail. +In all of these cases, the child process will exit with the exit value of 127. +.SH ERRORS +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions fail only in the case where the underlying +.BR fork (2) +or +.BR vfork (2) +call fails; in these cases, these functions return an error number, +which will be one of the errors described for +.BR fork (2) +or +.BR vfork (2). +.PP +In addition, these functions fail if: +.TP +.B ENOSYS +Function not supported on this system. +.SH VERSIONS +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions are available since glibc 2.2. +.SH CONFORMING TO +.PP +POSIX.1-2001, POSIX.1-2008. +.\" FIXME . This piece belongs in spawnattr_setflags(3) +.\" The +.\" .B POSIX_SPAWN_USEVFORK +.\" flag is a GNU extension; the +.\" .B _GNU_SOURCE +.\" feature test macro must be defined (before including any header files) +.\" to obtain the definition of this constant. +.SH NOTES +The housekeeping activities in the child are controlled by +the objects pointed to by +.I attrp +(for non-file actions) and +.I file_actions +In POSIX parlance, the +.I posix_spawnattr_t +and +.I posix_spawn_file_actions_t +data types are referred to as objects, +and their elements are not specified by name. +Portable programs should initialize these objects using +only the POSIX-specified functions. +(In other words, +although these objects may be implemented as structures containing fields, +portable programs must avoid dependence on such implementation details.) +.PP +According to POSIX, it unspecified whether fork handlers established with +.BR pthread_atfork (3) +are called when +.BR posix_spawn () +is invoked. +On glibc, +.\" Tested on glibc 2.12 +fork handlers are called only if the child is created using +.BR fork (2). +.PP +There is no "posix_fspawn" function (i.e., a function that is to +.BR posix_spawn () +as +.BR fexecve (3) +is to +.BR execve (2)). +However, this functionality can be obtained by specifying the +.I path +argument as one of the files in the caller's +.IR /proc/self/fd +directory. +.SH BUGS +POSIX.1 says that when +.B POSIX_SPAWN_SETSCHEDULER +is specified in +.IR spawn-flags , +then the +.B POSIX_SPAWN_SETSCHEDPARAM +(if present) is ignored. +However, before glibc 2.14, calls to +.BR posix_spawn () +failed with an error if +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12052 +.BR POSIX_SPAWN_SETSCHEDULER +was specified without also specifying +.BR POSIX_SPAWN_SETSCHEDPARAM . +.SH EXAMPLE +The program below demonstrates the use of various functions in the +POSIX spawn API. +The program accepts command-line attributes that can be used +to create file actions and attributes objects. +The remaining command-line arguments are used as the executable name +and command-line arguments of the program that is executed in the child. +.PP +In the first run, the +.BR date (1) +command is executed in the child, and the +.BR posix_spawn () +call employs no file actions or attributes objects. +.PP +.in +4 +.EX +$ \fB./a.out date\fP +PID of child: 7634 +Tue Feb 1 19:47:50 CEST 2011 +Child status: exited, status=0 +.EE +.in +.PP +In the next run, the +.I \-c +command-line option is used to create a file actions object that closes +standard output in the child. +Consequently, +.BR date (1) +fails when trying to perform output and exits with a status of 1. +.PP +.in +4 +.EX +$ \fB./a.out -c date\fP +PID of child: 7636 +date: write error: Bad file descriptor +Child status: exited, status=1 +.EE +.in +.PP +In the next run, the +.I \-s +command-line option is used to create an attributes object that +specifies that all (blockable) signals in the child should be blocked. +Consequently, trying to kill child with the default signal sent by +.BR kill (1) +(i.e., +.BR SIGTERM ) +fails, because that signal is blocked. +Therefore, to kill the child, +.BR SIGKILL +is necessary +.RB ( SIGKILL +can't be blocked). +.PP +.in +4 +.EX +$ \fB./a.out -s sleep 60 &\fP +[1] 7637 +$ PID of child: 7638 + +$ \fBkill 7638\fP +$ \fBkill -KILL 7638\fP +$ Child status: killed by signal 9 +[1]+ Done ./a.out -s sleep 60 +.EE +.in +.PP +When we try to execute a nonexistent command in the child, the +.BR exec (3) +fails and the child exits with a status of 127. +.PP +.in +4 +.EX +$ \fB./a.out xxxxx +PID of child: 10190 +Child status: exited, status=127 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); \\ + exit(EXIT_FAILURE); } while (0) + +#define errExitEN(en, msg) \\ + do { errno = en; perror(msg); \\ + exit(EXIT_FAILURE); } while (0) + +char **environ; + +int +main(int argc, char *argv[]) +{ + pid_t child_pid; + int s, opt, status; + sigset_t mask; + posix_spawnattr_t attr; + posix_spawnattr_t *attrp; + posix_spawn_file_actions_t file_actions; + posix_spawn_file_actions_t *file_actionsp; + + /* Parse command\-line options, which can be used to specify an + attributes object and file actions object for the child. */ + + attrp = NULL; + file_actionsp = NULL; + + while ((opt = getopt(argc, argv, "sc")) != \-1) { + switch (opt) { + case \(aqc\(aq: /* \-c: close standard output in child */ + + /* Create a file actions object and add a "close" + action to it */ + + s = posix_spawn_file_actions_init(&file_actions); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_init"); + + s = posix_spawn_file_actions_addclose(&file_actions, + STDOUT_FILENO); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_addclose"); + + file_actionsp = &file_actions; + break; + + case \(aqs\(aq: /* \-s: block all signals in child */ + + /* Create an attributes object and add a "set signal mask" + action to it */ + + s = posix_spawnattr_init(&attr); + if (s != 0) + errExitEN(s, "posix_spawnattr_init"); + s = posix_spawnattr_setflags(&attr, POSIX_SPAWN_SETSIGMASK); + if (s != 0) + errExitEN(s, "posix_spawnattr_setflags"); + + sigfillset(&mask); + s = posix_spawnattr_setsigmask(&attr, &mask); + if (s != 0) + errExitEN(s, "posix_spawnattr_setsigmask"); + + attrp = &attr; + break; + } + } + + /* Spawn the child. The name of the program to execute and the + command\-line arguments are taken from the command\-line arguments + of this program. The environment of the program execed in the + child is made the same as the parent\(aqs environment. */ + + s = posix_spawnp(&child_pid, argv[optind], file_actionsp, attrp, + &argv[optind], environ); + if (s != 0) + errExitEN(s, "posix_spawn"); + + /* Destroy any objects that we created earlier */ + + if (attrp != NULL) { + s = posix_spawnattr_destroy(attrp); + if (s != 0) + errExitEN(s, "posix_spawnattr_destroy"); + } + + if (file_actionsp != NULL) { + s = posix_spawn_file_actions_destroy(file_actionsp); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_destroy"); + } + + printf("PID of child: %ld\\n", (long) child_pid); + + /* Monitor status of the child until it terminates */ + + do { + s = waitpid(child_pid, &status, WUNTRACED | WCONTINUED); + if (s == \-1) + errExit("waitpid"); + + printf("Child status: "); + if (WIFEXITED(status)) { + printf("exited, status=%d\\n", WEXITSTATUS(status)); + } else if (WIFSIGNALED(status)) { + printf("killed by signal %d\\n", WTERMSIG(status)); + } else if (WIFSTOPPED(status)) { + printf("stopped by signal %d\\n", WSTOPSIG(status)); + } else if (WIFCONTINUED(status)) { + printf("continued\\n"); + } + } while (!WIFEXITED(status) && !WIFSIGNALED(status)); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.nh \" Disable hyphenation +.ad l +.BR close (2), +.BR dup2 (2), +.BR execl (2), +.BR execlp (2), +.BR fork (2), +.BR open (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR setpgid (2), +.BR setuid (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR posix_spawn_file_actions_addclose (3), +.BR posix_spawn_file_actions_adddup2 (3), +.BR posix_spawn_file_actions_addopen (3), +.BR posix_spawn_file_actions_destroy (3), +.BR posix_spawn_file_actions_init (3), +.BR posix_spawnattr_destroy (3), +.BR posix_spawnattr_getflags (3), +.BR posix_spawnattr_getpgroup (3), +.BR posix_spawnattr_getschedparam (3), +.BR posix_spawnattr_getschedpolicy (3), +.BR posix_spawnattr_getsigdefault (3), +.BR posix_spawnattr_getsigmask (3), +.BR posix_spawnattr_init (3), +.BR posix_spawnattr_setflags (3), +.BR posix_spawnattr_setpgroup (3), +.BR posix_spawnattr_setschedparam (3), +.BR posix_spawnattr_setschedpolicy (3), +.BR posix_spawnattr_setsigdefault (3), +.BR posix_spawnattr_setsigmask (3), +.BR pthread_atfork (3), +.BR , +Base Definitions volume of POSIX.1-2001, +.I http://www.opengroup.org/unix/online.html +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/posix_spawnp.3 b/man3/posix_spawnp.3 new file mode 100644 index 0000000..a6f49d0 --- /dev/null +++ b/man3/posix_spawnp.3 @@ -0,0 +1 @@ +.so man3/posix_spawn.3 diff --git a/man3/pow.3 b/man3/pow.3 new file mode 100644 index 0000000..7fd3483 --- /dev/null +++ b/man3/pow.3 @@ -0,0 +1,399 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH POW 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +pow, powf, powl \- power functions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double pow(double " x ", double " y ); +.BI "float powf(float " x ", float " y ); +.BI "long double powl(long double " x ", long double " y ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR powf (), +.BR powl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the value of +.I x +raised to the +power of +.IR y . +.SH RETURN VALUE +On success, these functions return the value of +.I x +to the power of +.IR y . +.PP +If +.I x +is a finite value less than 0, and +.I y +is a finite noninteger, a domain error occurs, +.\" The domain error is generated at least as far back as glibc 2.4 +and a NaN is returned. +.PP +If the result overflows, +a range error occurs, +.\" The range error is generated at least as far back as glibc 2.4 +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.PP +If result underflows, and is not representable, +a range error occurs, +and 0.0 is returned. +.\" POSIX.1 does not specify the sign of the zero, +.\" but http://sources.redhat.com/bugzilla/show_bug.cgi?id=2678 +.\" points out that the zero has the wrong sign in some cases. +.PP +Except as specified below, if +.I x +or +.I y +is a NaN, the result is a NaN. +.PP +If +.I x +is +1, the result is 1.0 (even if +.I y +is a NaN). +.PP +If +.I y +is 0, the result is 1.0 (even if +.I x +is a NaN). +.PP +If +.I x +is +0 (\-0), +and +.I y +is an odd integer greater than 0, +the result is +0 (\-0). +.PP +If +.I x +is 0, +and +.I y +greater than 0 and not an odd integer, +the result is +0. +.PP +If +.I x +is \-1, +and +.I y +is positive infinity or negative infinity, +the result is 1.0. +.PP +If the absolute value of +.I x +is less than 1, +and +.I y +is negative infinity, +the result is positive infinity. +.PP +If the absolute value of +.I x +is greater than 1, +and +.I y +is negative infinity, +the result is +0. +.PP +If the absolute value of +.I x +is less than 1, +and +.I y +is positive infinity, +the result is +0. +.PP +If the absolute value of +.I x +is greater than 1, +and +.I y +is positive infinity, +the result is positive infinity. +.PP +If +.I x +is negative infinity, +and +.I y +is an odd integer less than 0, +the result is \-0. +.PP +If +.I x +is negative infinity, +and +.I y +less than 0 and not an odd integer, +the result is +0. +.PP +If +.I x +is negative infinity, +and +.I y +is an odd integer greater than 0, +the result is negative infinity. +.PP +If +.I x +is negative infinity, +and +.I y +greater than 0 and not an odd integer, +the result is positive infinity. +.PP +If +.I x +is positive infinity, +and +.I y +less than 0, +the result is +0. +.PP +If +.I x +is positive infinity, +and +.I y +greater than 0, +the result is positive infinity. +.PP +If +.I x +is +0 or \-0, +and +.I y +is an odd integer less than 0, +a pole error occurs and +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +is returned, +with the same sign as +.IR x . +.PP +If +.I x +is +0 or \-0, +and +.I y +is less than 0 and not an odd integer, +a pole error occurs and +.\" The pole error is generated at least as far back as glibc 2.4 +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +is returned. +.SH ERRORS +.\" FIXME . review status of this error +.\" longstanding bug report for glibc: +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=369 +.\" For negative x, and -large and +large y, glibc 2.8 gives incorrect +.\" results +.\" pow(-0.5,-DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF) +.\" +.\" pow(-1.5,-DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0) +.\" +.\" pow(-0.5,DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0) +.\" +.\" pow(-1.5,DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF) +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is negative, and \fIy\fP is a finite noninteger +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is zero, and \fIy\fP is negative +.I errno +is set to +.BR ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: the result overflows +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: the result underflows +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR pow (), +.BR powf (), +.BR powl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +On 64-bits, +.\" +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=13932 +.BR pow () +may be more than 10,000 times slower for some (rare) inputs +than for other nearby inputs. +This affects only +.BR pow (), +and not +.BR powf () +nor +.BR powl (). +.PP +In glibc 2.9 and earlier, +.\" +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6776 +when a pole error occurs, +.I errno +is set to +.BR EDOM +instead of the POSIX-mandated +.BR ERANGE . +Since version 2.10, +.\" or possibly 2.9, I haven't found the source code change +.\" and I don't have a 2.9 system to test +glibc does the right thing. +.PP +If +.I x +is negative, +then large negative or positive +.I y +values yield a NaN as the function result, with +.I errno +set to +.BR EDOM , +and an invalid +.RB ( FE_INVALID ) +floating-point exception. +For example, with +.BR pow (), +one sees this behavior when the absolute value of +.I y +is greater than about 9.223373e18. +.\" see bug http://sources.redhat.com/bugzilla/show_bug.cgi?id=3866 +.\" and http://sources.redhat.com/bugzilla/show_bug.cgi?id=369 +.PP +In version 2.3.2 and earlier, +.\" FIXME . Actually, 2.3.2 is the earliest test result I have; so yet +.\" to confirm if this error occurs only in 2.3.2. +when an overflow or underflow error occurs, glibc's +.BR pow () +generates a bogus invalid floating-point exception +.RB ( FE_INVALID ) +in addition to the overflow or underflow exception. +.SH SEE ALSO +.BR cbrt (3), +.BR cpow (3), +.BR sqrt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pow10.3 b/man3/pow10.3 new file mode 100644 index 0000000..d37c8a5 --- /dev/null +++ b/man3/pow10.3 @@ -0,0 +1,82 @@ +.\" Copyright 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH POW10 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +pow10, pow10f, pow10l \- base-10 power functions +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "double pow10(double " x ); +.BI "float pow10f(float " x ); +.BI "long double pow10l(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +These functions return the value of 10 raised to the power +.IR x . +.PP +.BR "Note well" : +These functions perform exactly the same task as the functions described in +.BR exp10 (3), +with the difference that the latter functions are now standardized +in TS\ 18661-4:2015. +Those latter functions should be used in preference +to the functions described in this page. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +Since glibc 2.27, +.\" glibc commit 5a80d39d0d2587e9bd8e72f19e92eeb2a66fbe9e +the use of these functions in new programs is no longer supported. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR pow10 (), +.BR pow10f (), +.BR pow10l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This functions are nonstandard GNU extensions. +.SH SEE ALSO +.BR exp10 (3), +.BR pow (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pow10f.3 b/man3/pow10f.3 new file mode 100644 index 0000000..8a71580 --- /dev/null +++ b/man3/pow10f.3 @@ -0,0 +1 @@ +.so man3/pow10.3 diff --git a/man3/pow10l.3 b/man3/pow10l.3 new file mode 100644 index 0000000..8a71580 --- /dev/null +++ b/man3/pow10l.3 @@ -0,0 +1 @@ +.so man3/pow10.3 diff --git a/man3/powf.3 b/man3/powf.3 new file mode 100644 index 0000000..63da756 --- /dev/null +++ b/man3/powf.3 @@ -0,0 +1 @@ +.so man3/pow.3 diff --git a/man3/powl.3 b/man3/powl.3 new file mode 100644 index 0000000..63da756 --- /dev/null +++ b/man3/powl.3 @@ -0,0 +1 @@ +.so man3/pow.3 diff --git a/man3/printf.3 b/man3/printf.3 new file mode 100644 index 0000000..b6dcb77 --- /dev/null +++ b/man3/printf.3 @@ -0,0 +1,1185 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Earlier versions of this page influenced the present text. +.\" It was derived from a Berkeley page with version +.\" @(#)printf.3 6.14 (Berkeley) 7/30/91 +.\" converted for Linux by faith@cs.unc.edu, updated by +.\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99. +.\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes +.\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes +.\" +.TH PRINTF 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, +vsprintf, vsnprintf \- formatted output conversion +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int printf(const char *" format ", ...);" +.BI "int fprintf(FILE *" stream ", const char *" format ", ...);" +.BI "int dprintf(int " fd ", const char *" format ", ...);" +.BI "int sprintf(char *" str ", const char *" format ", ...);" +.BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);" + +.B #include +.PP +.BI "int vprintf(const char *" format ", va_list " ap ); +.BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap ); +.BI "int vdprintf(int " fd ", const char *" format ", va_list " ap ); +.BI "int vsprintf(char *" str ", const char *" format ", va_list " ap ); +.BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \ +", va_list " ap ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR snprintf (), +.BR vsnprintf (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE || + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.PP +.BR dprintf (), +.BR vdprintf (): +.PD 0 +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The functions in the +.BR printf () +family produce output according to a +.I format +as described below. +The functions +.BR printf () +and +.BR vprintf () +write output to +.IR stdout , +the standard output stream; +.BR fprintf () +and +.BR vfprintf () +write output to the given output +.IR stream ; +.BR sprintf (), +.BR snprintf (), +.BR vsprintf () +and +.BR vsnprintf () +write to the character string +.IR str . +.PP +The function +.BR dprintf () +is the same as +.BR fprintf () +except that it outputs to a file descriptor, +.IR fd , +instead of to a +.I stdio +stream. +.PP +The functions +.BR snprintf () +and +.BR vsnprintf () +write at most +.I size +bytes (including the terminating null byte (\(aq\e0\(aq)) to +.IR str . +.PP +The functions +.BR vprintf (), +.BR vfprintf (), +.BR vdprintf (), +.BR vsprintf (), +.BR vsnprintf () +are equivalent to the functions +.BR printf (), +.BR fprintf (), +.BR dprintf (), +.BR sprintf (), +.BR snprintf (), +respectively, except that they are called with a +.I va_list +instead of a variable number of arguments. +These functions do not call the +.I va_end +macro. +Because they invoke the +.I va_arg +macro, the value of +.I ap +is undefined after the call. +See +.BR stdarg (3). +.PP +All of these functions write the output under the control of a +.I format +string that specifies how subsequent arguments (or arguments accessed via +the variable-length argument facilities of +.BR stdarg (3)) +are converted for output. +.PP +C99 and POSIX.1-2001 specify that the results are undefined if a call to +.BR sprintf (), +.BR snprintf (), +.BR vsprintf (), +or +.BR vsnprintf () +would cause copying to take place between objects that overlap +(e.g., if the target string array and one of the supplied input arguments +refer to the same buffer). +See NOTES. +.SS Format of the format string +The format string is a character string, beginning and ending +in its initial shift state, if any. +The format string is composed of zero or more directives: ordinary +characters (not +.BR % ), +which are copied unchanged to the output stream; +and conversion specifications, each of which results in fetching zero or +more subsequent arguments. +Each conversion specification is introduced by +the character +.BR % , +and ends with a +.IR "conversion specifier" . +In between there may be (in this order) zero or more +.IR flags , +an optional minimum +.IR "field width" , +an optional +.I precision +and an optional +.IR "length modifier" . +.PP +The arguments must correspond properly (after type promotion) with the +conversion specifier. +By default, the arguments are used in the order +given, where each \(aq*\(aq (see +.I "Field width" +and +.I Precision +below) and each conversion specifier asks for the next +argument (and it is an error if insufficiently many arguments are given). +One can also specify explicitly which argument is taken, +at each place where an argument is required, by writing "%m$" instead +of \(aq%\(aq and "*m$" instead of \(aq*\(aq, +where the decimal integer \fIm\fP denotes +the position in the argument list of the desired argument, indexed starting +from 1. +Thus, +.PP +.in +4n +.EX +printf("%*d", width, num); +.EE +.in +.PP +and +.PP +.in +4n +.EX +printf("%2$*1$d", width, num); +.EE +.in +.PP +are equivalent. +The second style allows repeated references to the +same argument. +The C99 standard does not include the style using \(aq$\(aq, +which comes from the Single UNIX Specification. +If the style using +\(aq$\(aq is used, it must be used throughout for all conversions taking an +argument and all width and precision arguments, but it may be mixed +with "%%" formats, which do not consume an argument. +There may be no +gaps in the numbers of arguments specified using \(aq$\(aq; for example, if +arguments 1 and 3 are specified, argument 2 must also be specified +somewhere in the format string. +.PP +For some numeric conversions a radix character ("decimal point") or +thousands' grouping character is used. +The actual character used +depends on the +.B LC_NUMERIC +part of the locale. +(See +.BR setlocale (3).) +The POSIX locale +uses \(aq.\(aq as radix character, and does not have a grouping character. +Thus, +.PP +.in +4n +.EX + printf("%\(aq.2f", 1234567.89); +.EE +.in +.PP +results in "1234567.89" in the POSIX locale, in "1234567,89" in the +nl_NL locale, and in "1.234.567,89" in the da_DK locale. +.SS Flag characters +The character % is followed by zero or more of the following flags: +.TP +.B # +The value should be converted to an "alternate form". +For +.B o +conversions, the first character of the output string is made zero +(by prefixing a 0 if it was not zero already). +For +.B x +and +.B X +conversions, a nonzero result has the string "0x" (or "0X" for +.B X +conversions) prepended to it. +For +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.B G +conversions, the result will always contain a decimal point, even if no +digits follow it (normally, a decimal point appears in the results of those +conversions only if a digit follows). +For +.B g +and +.B G +conversions, trailing zeros are not removed from the result as they would +otherwise be. +For other conversions, the result is undefined. +.TP +.B \&0 +The value should be zero padded. +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.B G +conversions, the converted value is padded on the left with zeros rather +than blanks. +If the +.B \&0 +and +.B \- +flags both appear, the +.B \&0 +flag is ignored. +If a precision is given with a numeric conversion +.RB ( d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X ), +the +.B \&0 +flag is ignored. +For other conversions, the behavior is undefined. +.TP +.B \- +The converted value is to be left adjusted on the field boundary. +(The default is right justification.) +The converted value is padded on the right with blanks, rather +than on the left with blanks or zeros. +A +.B \- +overrides a +.B \&0 +if both are given. +.TP +.B \(aq \(aq +(a space) A blank should be left before a positive number +(or empty string) produced by a signed conversion. +.TP +.B + +A sign (+ or \-) should always be placed before a number produced by a signed +conversion. +By default, a sign is used only for negative numbers. +A +.B + +overrides a space if both are used. +.PP +The five flag characters above are defined in the C99 standard. +The Single UNIX Specification specifies one further flag character. +.TP +.B \(aq +For decimal conversion +.RB ( i , +.BR d , +.BR u , +.BR f , +.BR F , +.BR g , +.BR G ) +the output is to be grouped with thousands' grouping characters +if the locale information indicates any. +(See +.BR setlocale (3).) +Note that many versions of +.BR gcc (1) +cannot parse this option and will issue a warning. +(SUSv2 did not +include \fI%\(aqF\fP, but SUSv3 added it.) +.PP +glibc 2.2 adds one further flag character. +.TP +.B I +For decimal integer conversion +.RB ( i , +.BR d , +.BR u ) +the output uses the locale's alternative output digits, if any. +For example, since glibc 2.2.3 this will give Arabic-Indic digits +in the Persian ("fa_IR") locale. +.\" outdigits keyword in locale file +.SS Field width +An optional decimal digit string (with nonzero first digit) specifying +a minimum field width. +If the converted value has fewer characters +than the field width, it will be padded with spaces on the left +(or right, if the left-adjustment flag has been given). +Instead of a decimal digit string one may write "*" or "*m$" +(for some decimal integer \fIm\fP) to specify that the field width +is given in the next argument, or in the \fIm\fP-th argument, respectively, +which must be of type +.IR int . +A negative field width is taken as a \(aq\-\(aq flag followed by a +positive field width. +In no case does a nonexistent or small field width cause truncation of a +field; if the result of a conversion is wider than the field width, the +field is expanded to contain the conversion result. +.SS Precision +An optional precision, in the form of a period (\(aq.\(aq) followed by an +optional decimal digit string. +Instead of a decimal digit string one may write "*" or "*m$" +(for some decimal integer \fIm\fP) to specify that the precision +is given in the next argument, or in the \fIm\fP-th argument, respectively, +which must be of type +.IR int . +If the precision is given as just \(aq.\(aq, the precision is taken to +be zero. +A negative precision is taken as if the precision were omitted. +This gives the minimum number of digits to appear for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.B X +conversions, the number of digits to appear after the radix character for +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +and +.B F +conversions, the maximum number of significant digits for +.B g +and +.B G +conversions, or the maximum number of characters to be printed from a +string for +.B s +and +.B S +conversions. +.SS Length modifier +Here, "integer conversion" stands for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.B X +conversion. +.TP +.B hh +A following integer conversion corresponds to a +.I signed char +or +.I unsigned char +argument, or a following +.B n +conversion corresponds to a pointer to a +.I signed char +argument. +.TP +.B h +A following integer conversion corresponds to a +.I short int +or +.I unsigned short int +argument, or a following +.B n +conversion corresponds to a pointer to a +.I short int +argument. +.TP +.B l +(ell) A following integer conversion corresponds to a +.I long int +or +.I unsigned long int +argument, or a following +.B n +conversion corresponds to a pointer to a +.I long int +argument, or a following +.B c +conversion corresponds to a +.I wint_t +argument, or a following +.B s +conversion corresponds to a pointer to +.I wchar_t +argument. +.TP +.B ll +(ell-ell). +A following integer conversion corresponds to a +.I long long int +or +.I unsigned long long int +argument, or a following +.B n +conversion corresponds to a pointer to a +.I long long int +argument. +.TP +.B q +A synonym for +.BR ll . +This is a nonstandard extension, derived from BSD; +avoid its use in new code. +.TP +.B L +A following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.B G +conversion corresponds to a +.I long double +argument. +(C99 allows %LF, but SUSv2 does not.) +.TP +.B j +A following integer conversion corresponds to an +.I intmax_t +or +.I uintmax_t +argument, or a following +.B n +conversion corresponds to a pointer to an +.I intmax_t +argument. +.TP +.B z +A following integer conversion corresponds to a +.I size_t +or +.I ssize_t +argument, or a following +.B n +conversion corresponds to a pointer to a +.I size_t +argument. +.TP +.B Z +A nonstandard synonym for +.BR z +that predates the appearance of +.BR z . +Do not use in new code. +.TP +.B t +A following integer conversion corresponds to a +.I ptrdiff_t +argument, or a following +.B n +conversion corresponds to a pointer to a +.I ptrdiff_t +argument. +.PP +SUSv3 specifies all of the above, +except for those modifiers explicitly noted as being nonstandard extensions. +SUSv2 specified only the length modifiers +.B h +(in +.BR hd , +.BR hi , +.BR ho , +.BR hx , +.BR hX , +.BR hn ) +and +.B l +(in +.BR ld , +.BR li , +.BR lo , +.BR lx , +.BR lX , +.BR ln , +.BR lc , +.BR ls ) +and +.B L +(in +.BR Le , +.BR LE , +.BR Lf , +.BR Lg , +.BR LG ). +.PP +As a nonstandard extension, the GNU implementations treats +.B ll +and +.B L +as synonyms, so that one can, for example, write +.BR llg +(as a synonym for the standards-compliant +.RB Lg ) +and +.BR Ld +(as a synonym for the standards compliant +.BR lld ). +Such usage is nonportable. +.\" +.SS Conversion specifiers +A character that specifies the type of conversion to be applied. +The conversion specifiers and their meanings are: +.TP +.BR d ", " i +The +.I int +argument is converted to signed decimal notation. +The precision, if any, gives the minimum number of digits +that must appear; if the converted value requires fewer digits, it is +padded on the left with zeros. +The default precision is 1. +When 0 is printed with an explicit precision 0, the output is empty. +.TP +.BR o ", " u ", " x ", " X +The +.I "unsigned int" +argument is converted to unsigned octal +.RB ( o ), +unsigned decimal +.RB ( u ), +or unsigned hexadecimal +.RB ( x +and +.BR X ) +notation. +The letters +.B abcdef +are used for +.B x +conversions; the letters +.B ABCDEF +are used for +.B X +conversions. +The precision, if any, gives the minimum number of digits +that must appear; if the converted value requires fewer digits, it is +padded on the left with zeros. +The default precision is 1. +When 0 is printed with an explicit precision 0, the output is empty. +.TP +.BR e ", " E +The +.I double +argument is rounded and converted in the style +.RB [\-]d \&. ddd e \(+-dd +where there is one digit before the decimal-point character and the number +of digits after it is equal to the precision; if the precision is missing, +it is taken as 6; if the precision is zero, no decimal-point character +appears. +An +.B E +conversion uses the letter +.B E +(rather than +.BR e ) +to introduce the exponent. +The exponent always contains at least two +digits; if the value is zero, the exponent is 00. +.TP +.BR f ", " F +The +.I double +argument is rounded and converted to decimal notation in the style +.RB [\-]ddd \&. ddd, +where the number of digits after the decimal-point character is equal to +the precision specification. +If the precision is missing, it is taken as +6; if the precision is explicitly zero, no decimal-point character appears. +If a decimal point appears, at least one digit appears before it. +.IP +(SUSv2 does not know about +.B F +and says that character string representations for infinity and NaN +may be made available. +SUSv3 adds a specification for +.BR F . +The C99 standard specifies "[\-]inf" or "[\-]infinity" +for infinity, and a string starting with "nan" for NaN, in the case of +.B f +conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of +.B F +conversion.) +.TP +.BR g ", " G +The +.I double +argument is converted in style +.B f +or +.B e +(or +.B F +or +.B E +for +.B G +conversions). +The precision specifies the number of significant digits. +If the precision is missing, 6 digits are given; if the precision is zero, +it is treated as 1. +Style +.B e +is used if the exponent from its conversion is less than \-4 or greater +than or equal to the precision. +Trailing zeros are removed from the +fractional part of the result; a decimal point appears only if it is +followed by at least one digit. +.TP +.BR a ", " A +(C99; not in SUSv2, but added in SUSv3) +For +.B a +conversion, the +.I double +argument is converted to hexadecimal notation (using the letters abcdef) +in the style +.RB [\-] 0x h \&. hhhh p \(+-; +for +.B A +conversion the prefix +.BR 0X , +the letters ABCDEF, and the exponent separator +.B P +is used. +There is one hexadecimal digit before the decimal point, +and the number of digits after it is equal to the precision. +The default precision suffices for an exact representation of the value +if an exact representation in base 2 exists +and otherwise is sufficiently large to distinguish values of type +.IR double . +The digit before the decimal point is unspecified for nonnormalized +numbers, and nonzero but otherwise unspecified for normalized numbers. +.TP +.B c +If no +.B l +modifier is present, the +.I int +argument is converted to an +.IR "unsigned char" , +and the resulting character is written. +If an +.B l +modifier is present, the +.I wint_t +(wide character) argument is converted to a multibyte sequence by a call +to the +.BR wcrtomb (3) +function, with a conversion state starting in the initial state, and the +resulting multibyte string is written. +.TP +.B s +If no +.B l +modifier is present: the +.I "const char\ *" +argument is expected to be a pointer to an array of character type (pointer +to a string). +Characters from the array are written up to (but not +including) a terminating null byte (\(aq\\0\(aq); +if a precision is specified, no more than the number specified +are written. +If a precision is given, no null byte need be present; +if the precision is not specified, or is greater than the size of the +array, the array must contain a terminating null byte. +.IP +If an +.B l +modifier is present: the +.I "const wchar_t\ *" +argument is expected to be a pointer to an array of wide characters. +Wide characters from the array are converted to multibyte characters +(each by a call to the +.BR wcrtomb (3) +function, with a conversion state starting in the initial state before +the first wide character), up to and including a terminating null +wide character. +The resulting multibyte characters are written up to +(but not including) the terminating null byte. +If a precision is +specified, no more bytes than the number specified are written, but +no partial multibyte characters are written. +Note that the precision +determines the number of +.I bytes +written, not the number of +.I wide characters +or +.IR "screen positions" . +The array must contain a terminating null wide character, unless a +precision is given and it is so small that the number of bytes written +exceeds it before the end of the array is reached. +.TP +.B C +(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) +Synonym for +.BR lc . +Don't use. +.TP +.B S +(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) +Synonym for +.BR ls . +Don't use. +.TP +.B p +The +.I "void\ *" +pointer argument is printed in hexadecimal (as if by +.B %#x +or +.BR %#lx ). +.TP +.B n +The number of characters written so far is stored into the integer +pointed to by the corresponding argument. +That argument shall be an +.IR "int\ *" , +or variant whose size matches the (optionally) +supplied integer length modifier. +No argument is converted. +(This specifier is not supported by the bionic C library.) +The behavior is undefined if the conversion specification includes +any flags, a field width, or a precision. +.TP +.B m +(Glibc extension; supported by uClibc and musl.) +Print output of +.IR strerror(errno) . +No argument is required. +.TP +.B % +A \(aq%\(aq is written. +No argument is converted. +The complete conversion +specification is \(aq%%\(aq. +.SH RETURN VALUE +Upon successful return, these functions return the number of characters +printed (excluding the null byte used to end output to strings). +.PP +The functions +.BR snprintf () +and +.BR vsnprintf () +do not write more than +.I size +bytes (including the terminating null byte (\(aq\e0\(aq)). +If the output was truncated due to this limit, then the return value +is the number of characters (excluding the terminating null byte) +which would have been written to the final string if enough space +had been available. +Thus, a return value of +.I size +or more means that the output was truncated. +(See also below under NOTES.) +.PP +If an output error is encountered, a negative value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR printf (), +.BR fprintf (), +.br +.BR sprintf (), +.BR snprintf (), +.br +.BR vprintf (), +.BR vfprintf (), +.br +.BR vsprintf (), +.BR vsnprintf () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +.BR fprintf (), +.BR printf (), +.BR sprintf (), +.BR vprintf (), +.BR vfprintf (), +.BR vsprintf (): +POSIX.1-2001, POSIX.1-2008, C89, C99. +.PP +.BR snprintf (), +.BR vsnprintf (): +POSIX.1-2001, POSIX.1-2008, C99. +.PP +The +.BR dprintf () +and +.BR vdprintf () +functions were originally GNU extensions that were later standardized +in POSIX.1-2008. +.PP +Concerning the return value of +.BR snprintf (), +SUSv2 and C99 contradict each other: when +.BR snprintf () +is called with +.IR size =0 +then SUSv2 stipulates an unspecified return value less than 1, +while C99 allows +.I str +to be NULL in this case, and gives the return value (as always) +as the number of characters that would have been written in case +the output string has been large enough. +POSIX.1-2001 and later align their specification of +.BR snprintf () +with C99. +.\" .PP +.\" Linux libc4 knows about the five C standard flags. +.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, +.\" and the conversions +.\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, +.\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP, +.\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP, +.\" where \fBF\fP is a synonym for \fBf\fP. +.\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms +.\" for \fBld\fP, \fBlo\fP, and \fBlu\fP. +.\" (This is bad, and caused serious bugs later, when +.\" support for \fB%D\fP disappeared.) +.\" No locale-dependent radix character, +.\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$". +.\" .PP +.\" Linux libc5 knows about the five C standard flags and the \(aq flag, +.\" locale, "%m$" and "*m$". +.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, +.\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP +.\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug). +.\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP, +.\" but adds the conversion character +.\" .BR m , +.\" which outputs +.\" .IR strerror(errno) . +.\" .PP +.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP. +.PP +glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP +and conversion characters \fBa\fP and \fBA\fP. +.PP +glibc 2.2 adds the conversion character \fBF\fP with C99 semantics, +and the flag character \fBI\fP. +.SH NOTES +Some programs imprudently rely on code such as the following +.PP + sprintf(buf, "%s some further text", buf); +.PP +to append text to +.IR buf . +However, the standards explicitly note that the results are undefined +if source and destination buffers overlap when calling +.BR sprintf (), +.BR snprintf (), +.BR vsprintf (), +and +.BR vsnprintf (). +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075 +Depending on the version of +.BR gcc (1) +used, and the compiler options employed, calls such as the above will +.B not +produce the expected results. +.PP +The glibc implementation of the functions +.BR snprintf () +and +.BR vsnprintf () +conforms to the C99 standard, that is, behaves as described above, +since glibc version 2.1. +Until glibc 2.0.6, they would return \-1 +when the output was truncated. +.\" .SH HISTORY +.\" UNIX V7 defines the three routines +.\" .BR printf (), +.\" .BR fprintf (), +.\" .BR sprintf (), +.\" and has the flag \-, the width or precision *, the length modifier l, +.\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx. +.\" This is still true for 2.9.1BSD, but 2.10BSD has the flags +.\" #, + and and no longer mentions D,O,U,X. +.\" 2.11BSD has +.\" .BR vprintf (), +.\" .BR vfprintf (), +.\" .BR vsprintf (), +.\" and warns not to use D,O,U,X. +.\" 4.3BSD Reno has the flag 0, the length modifiers h and L, +.\" and the conversions n, p, E, G, X (with current meaning) +.\" and deprecates D,O,U. +.\" 4.4BSD introduces the functions +.\" .BR snprintf () +.\" and +.\" .BR vsnprintf (), +.\" and the length modifier q. +.\" FreeBSD also has functions +.\" .BR asprintf () +.\" and +.\" .BR vasprintf (), +.\" that allocate a buffer large enough for +.\" .BR sprintf (). +.\" In glibc there are functions +.\" .BR dprintf () +.\" and +.\" .BR vdprintf () +.\" that print to a file descriptor instead of a stream. +.SH BUGS +Because +.BR sprintf () +and +.BR vsprintf () +assume an arbitrarily long string, callers must be careful not to overflow +the actual space; this is often impossible to assure. +Note that the length +of the strings produced is locale-dependent and difficult to predict. +Use +.BR snprintf () +and +.BR vsnprintf () +instead (or +.BR asprintf (3) +and +.BR vasprintf (3)). +.\" .PP +.\" Linux libc4.[45] does not have a +.\" .BR snprintf (), +.\" but provides a libbsd that contains an +.\" .BR snprintf () +.\" equivalent to +.\" .BR sprintf (), +.\" that is, one that ignores the +.\" .I size +.\" argument. +.\" Thus, the use of +.\" .BR snprintf () +.\" with early libc4 leads to serious security problems. +.PP +Code such as +.BI printf( foo ); +often indicates a bug, since +.I foo +may contain a % character. +If +.I foo +comes from untrusted user input, it may contain \fB%n\fP, causing the +.BR printf () +call to write to memory and creating a security hole. +.\" .PP +.\" Some floating-point conversions under early libc4 +.\" caused memory leaks. +.SH EXAMPLE +To print +.I Pi +to five decimal places: +.PP +.in +4n +.EX +#include +#include +fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); +.EE +.in +.PP +To print a date and time in the form "Sunday, July 3, 10:02", +where +.I weekday +and +.I month +are pointers to strings: +.PP +.in +4n +.EX +#include +fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", + weekday, month, day, hour, min); +.EE +.in +.PP +Many countries use the day-month-year order. +Hence, an internationalized version must be able to print +the arguments in an order specified by the format: +.PP +.in +4n +.EX +#include +fprintf(stdout, format, + weekday, month, day, hour, min); +.EE +.in +.PP +where +.I format +depends on locale, and may permute the arguments. +With the value: +.PP +.in +4n +.EX +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.EE +.in +.PP +one might obtain "Sonntag, 3. Juli, 10:02". +.PP +To allocate a sufficiently large string and print into it +(code correct for both glibc 2.0 and glibc 2.1): +.PP +.EX +#include +#include +#include + +char * +make_message(const char *fmt, ...) +{ + int size = 0; + char *p = NULL; + va_list ap; + + /* Determine required size */ + + va_start(ap, fmt); + size = vsnprintf(p, size, fmt, ap); + va_end(ap); + + if (size < 0) + return NULL; + + size++; /* For '\\0' */ + p = malloc(size); + if (p == NULL) + return NULL; + + va_start(ap, fmt); + size = vsnprintf(p, size, fmt, ap); + va_end(ap); + + if (size < 0) { + free(p); + return NULL; + } + + return p; +} +.EE +.PP +If truncation occurs in glibc versions prior to 2.0.6, this is treated as an +error instead of being handled gracefully. +.SH SEE ALSO +.BR printf (1), +.BR asprintf (3), +.BR puts (3), +.BR scanf (3), +.BR setlocale (3), +.BR strfromd (3), +.BR wcrtomb (3), +.BR wprintf (3), +.BR locale (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/profil.3 b/man3/profil.3 new file mode 100644 index 0000000..a03c67a --- /dev/null +++ b/man3/profil.3 @@ -0,0 +1,116 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Fri Jun 23 01:35:19 1995 Andries Brouwer +.\" (prompted by Bas V. de Bakker ) +.\" Corrected (and moved to man3), 980612, aeb +.TH PROFIL 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +profil \- execution time profile +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int profil(unsigned short *" buf ", size_t " bufsiz , +.BI " size_t " offset ", unsigned int " scale ); +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR profil (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.fi +.SH DESCRIPTION +This routine provides a means to find out in what areas your program +spends most of its time. +The argument +.I buf +points to +.I bufsiz +bytes of core. +Every virtual 10 milliseconds, the user's program counter (PC) +is examined: +.I offset +is subtracted and the result is multiplied by +.I scale +and divided by 65536. +If the resulting value is less than +.IR bufsiz , +then the corresponding entry in +.I buf +is incremented. +If +.I buf +is NULL, profiling is disabled. +.SH RETURN VALUE +Zero is always returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR profil () +T} Thread safety MT-Unsafe +.TE +.sp 1 +.SH CONFORMING TO +Similar to a call in SVr4 (but not POSIX.1). +.SH BUGS +.BR profil () +cannot be used on a program that also uses +.B ITIMER_PROF +interval timers (see +.BR setitimer (2)). +.PP +True kernel profiling provides more accurate results. +Libc 4.4 contained a kernel patch providing a system call profil. +.SH SEE ALSO +.BR gprof (1), +.BR sprof (1), +.BR setitimer (2), +.BR sigaction (2), +.BR signal (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/program_invocation_name.3 b/man3/program_invocation_name.3 new file mode 100644 index 0000000..8b0f5cc --- /dev/null +++ b/man3/program_invocation_name.3 @@ -0,0 +1,73 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.TH INVOCATION_NAME 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +program_invocation_name, program_invocation_short_name \- \ +obtain name used to invoke calling program +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "extern char *" program_invocation_name ; +.BI "extern char *" program_invocation_short_name ; +.fi +.SH DESCRIPTION +.I program_invocation_name +contains the name that was used to invoke the calling program. +This is the same as the value of +.I argv[0] +in +.IR main (), +with the difference that the scope of +.I program_invocation_name +is global. +.PP +.I program_invocation_short_name +contains the basename component of name that was used to invoke +the calling program. +That is, it is the same value as +.IR program_invocation_name , +with all text up to and including the final slash (/), if any, removed. +.PP +These variables are automatically initialized by the glibc run-time +startup code. +.SH CONFORMING TO +These variables are GNU extensions, and should not be +used in programs intended to be portable. +.SH NOTES +The Linux-specific +.I /proc/[number]/cmdline +file provides access to similar information. +.SH SEE ALSO +.BR proc (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/program_invocation_short_name.3 b/man3/program_invocation_short_name.3 new file mode 100644 index 0000000..f603f6c --- /dev/null +++ b/man3/program_invocation_short_name.3 @@ -0,0 +1 @@ +.so man3/program_invocation_name.3 diff --git a/man3/psiginfo.3 b/man3/psiginfo.3 new file mode 100644 index 0000000..cd748fa --- /dev/null +++ b/man3/psiginfo.3 @@ -0,0 +1 @@ +.so man3/psignal.3 diff --git a/man3/psignal.3 b/man3/psignal.3 new file mode 100644 index 0000000..ef00ef5 --- /dev/null +++ b/man3/psignal.3 @@ -0,0 +1,146 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:45:17 1993 by Rik Faith (faith@cs.unc.edu) +.TH PSIGNAL 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +psignal, psiginfo \- print signal message +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void psignal(int " sig ", const char *" s ); +.BI "void psiginfo(const siginfo_t *" pinfo ", const char *" s ); +.PP +.BI "extern const char *const " sys_siglist []; +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR psignal (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.br +.BR psiginfo (): +_POSIX_C_SOURCE\ >=\ 200809L +.br +.IR sys_siglist : + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The +.BR psignal () +function displays a message on \fIstderr\fP +consisting of the string \fIs\fP, a colon, a space, a string +describing the signal number \fIsig\fP, and a trailing newline. +If the string \fIs\fP is NULL or empty, the colon and space are omitted. +If \fIsig\fP is invalid, +the message displayed will indicate an unknown signal. +.PP +The +.BR psiginfo () +function is like +.BR psignal (), +except that it displays information about the signal described by +.IR pinfo , +which should point to a valid +.I siginfo_t +structure. +As well as the signal description, +.BR psiginfo () +displays information about the origin of the signal, +and other information relevant to the signal +(e.g., the relevant memory address for hardware-generated signals, +the child process ID for +.BR SIGCHLD , +and the user ID and process ID of the sender, for signals set using +.BR kill (2) +or +.BR sigqueue (3)). +.PP +The array \fIsys_siglist\fP holds the signal description strings +indexed by signal number. +.SH RETURN VALUE +The +.BR psignal () +and +.BR psiginfo () +functions return no value. +.SH VERSIONS +The +.BR psiginfo () +function was added to glibc in version 2.10. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR psignal (), +.BR psiginfo () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2008, 4.3BSD. +.SH BUGS +In glibc versions up to 2.12, +.BR psiginfo () +had the following bugs: +.IP * 3 +In some circumstances, a trailing newline is not printed. +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12107 +.\" Reportedly now fixed; check glibc 2.13 +.IP * +Additional details are not displayed for real-time signals. +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12108 +.\" Reportedly now fixed; check glibc 2.13 +.SH SEE ALSO +.BR sigaction (2), +.BR perror (3), +.BR strsignal (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3 new file mode 100644 index 0000000..d8335bc --- /dev/null +++ b/man3/pthread_atfork.3 @@ -0,0 +1,136 @@ +'\" t +.\" Copyright (C) 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATFORK 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_atfork \- register fork handlers +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void)," +.BI " void (*" child ")(void));" +.fi +.PP +Link with \fI\-pthread\fP. +.SH DESCRIPTION +The +.BR pthread_atfork () +function registers fork handlers that are to be executed when +.BR fork (2) +is called by this thread. +The handlers are executed in the context of the thread that calls +.BR fork (2). +.PP +Three kinds of handler can be registered: +.IP * 3 +.IR prepare +specifies a handler that is executed before +.BR fork (2) +processing starts. +.IP * +.I parent +specifies a handler that is executed in the parent process after +.BR fork (2) +processing completes. +.IP * +.I child +specifies a handler that is executed in the child process after +.BR fork (2) +processing completes. +.PP +Any of the three arguments may be NULL if no handler is needed +in the corresponding phase of +.BR fork (2) +processing. +.PP +.SH RETURN VALUE +On success, +.BR pthread_atfork () +returns zero. +On error, it returns an error number. +.BR pthread_atfork () +may be called multiple times by a thread, +to register multiple handlers for each phase. +The handlers for each phase are called in a specified order: the +.I prepare +handlers are called in reverse order of registration; the +.I parent +and +.I child +handlers are called in the order of registration. +.SH ERRORS +.TP +.B ENOMEM +Could not allocate memory to record the form handler entry. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +When +.BR fork (2) +is called in a multithreaded process, +only the calling thread is duplicated in the child process. +The original intention of +.BR pthread_atfork () +was to allow the calling thread to be returned to a consistent state. +For example, at the time of the call to +.BR fork (2), +other threads may have locked mutexes that are visible in the +user-space memory duplicated in the child. +Such mutexes would never be unlocked, +since the threads that placed the locks are not duplicated in the child. +The intent of +.BR pthread_atfork () +was to provide a mechanism whereby the application (or a library) +could ensure that mutexes and other process and thread state would be +restored to a consistent state. +In practice, this task is generally too difficult to be practicable. +.PP +After a +.BR fork (2) +in a multithreaded process returns in the child, +the child should call only async-signal-safe functions (see +.BR signal-safety (7)) +until such time as it calls +.BR execve (2) +to execute a new program. +.PP +POSIX.1 specifies that +.BR pthread_atfork () +shall not fail with the error +.BR EINTR . +.SH SEE ALSO +.BR fork (2), +.BR atexit (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_destroy.3 b/man3/pthread_attr_destroy.3 new file mode 100644 index 0000000..4e7c949 --- /dev/null +++ b/man3/pthread_attr_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_init.3 diff --git a/man3/pthread_attr_getaffinity_np.3 b/man3/pthread_attr_getaffinity_np.3 new file mode 100644 index 0000000..c6af8fa --- /dev/null +++ b/man3/pthread_attr_getaffinity_np.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setaffinity_np.3 diff --git a/man3/pthread_attr_getdetachstate.3 b/man3/pthread_attr_getdetachstate.3 new file mode 100644 index 0000000..c57ecd5 --- /dev/null +++ b/man3/pthread_attr_getdetachstate.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setdetachstate.3 diff --git a/man3/pthread_attr_getguardsize.3 b/man3/pthread_attr_getguardsize.3 new file mode 100644 index 0000000..766ca2f --- /dev/null +++ b/man3/pthread_attr_getguardsize.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setguardsize.3 diff --git a/man3/pthread_attr_getinheritsched.3 b/man3/pthread_attr_getinheritsched.3 new file mode 100644 index 0000000..65239cb --- /dev/null +++ b/man3/pthread_attr_getinheritsched.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setinheritsched.3 diff --git a/man3/pthread_attr_getschedparam.3 b/man3/pthread_attr_getschedparam.3 new file mode 100644 index 0000000..3f830fd --- /dev/null +++ b/man3/pthread_attr_getschedparam.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setschedparam.3 diff --git a/man3/pthread_attr_getschedpolicy.3 b/man3/pthread_attr_getschedpolicy.3 new file mode 100644 index 0000000..10f740c --- /dev/null +++ b/man3/pthread_attr_getschedpolicy.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setschedpolicy.3 diff --git a/man3/pthread_attr_getscope.3 b/man3/pthread_attr_getscope.3 new file mode 100644 index 0000000..965fd62 --- /dev/null +++ b/man3/pthread_attr_getscope.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setscope.3 diff --git a/man3/pthread_attr_getstack.3 b/man3/pthread_attr_getstack.3 new file mode 100644 index 0000000..2b20d7e --- /dev/null +++ b/man3/pthread_attr_getstack.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstack.3 diff --git a/man3/pthread_attr_getstackaddr.3 b/man3/pthread_attr_getstackaddr.3 new file mode 100644 index 0000000..49d8a85 --- /dev/null +++ b/man3/pthread_attr_getstackaddr.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstackaddr.3 diff --git a/man3/pthread_attr_getstacksize.3 b/man3/pthread_attr_getstacksize.3 new file mode 100644 index 0000000..52431f5 --- /dev/null +++ b/man3/pthread_attr_getstacksize.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstacksize.3 diff --git a/man3/pthread_attr_init.3 b/man3/pthread_attr_init.3 new file mode 100644 index 0000000..d4de219 --- /dev/null +++ b/man3/pthread_attr_init.3 @@ -0,0 +1,337 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_INIT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_init, pthread_attr_destroy \- initialize and destroy +thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_init(pthread_attr_t *" attr ); +.BI "int pthread_attr_destroy(pthread_attr_t *" attr ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_init () +function initializes the thread attributes object pointed to by +.IR attr +with default attribute values. +After this call, individual attributes of the object can be set +using various related functions (listed under SEE ALSO), +and then the object can be used in one or more +.BR pthread_create (3) +calls that create threads. +.PP +Calling +.BR pthread_attr_init () +on a thread attributes object that has already been initialized +results in undefined behavior. +.PP +When a thread attributes object is no longer required, +it should be destroyed using the +.BR pthread_attr_destroy () +function. +Destroying a thread attributes object has no effect +on threads that were created using that object. +.PP +Once a thread attributes object has been destroyed, +it can be reinitialized using +.BR pthread_attr_init (). +Any other use of a destroyed thread attributes object +has undefined results. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +POSIX.1 documents an +.B ENOMEM +error for +.BR pthread_attr_init (); +on Linux these functions always succeed +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw22 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_init (), +.BR pthread_attr_destroy () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The +.I pthread_attr_t +type should be treated as opaque: +any access to the object other than via pthreads functions +is nonportable and produces undefined results. +.SH EXAMPLE +The program below optionally makes use of +.BR pthread_attr_init () +and various related functions to initialize a thread attributes +object that is used to create a single thread. +Once created, the thread uses the +.BR pthread_getattr_np (3) +function (a nonstandard GNU extension) to retrieve the thread's +attributes, and then displays those attributes. +.PP +If the program is run with no command-line argument, +then it passes NULL as the +.I attr +argument of +.BR pthread_create (3), +so that the thread is created with default attributes. +Running the program on Linux/x86-32 with the NPTL threading implementation, +we see the following: +.PP +.in +4n +.EX +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +.RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" +unlimited +.RB "$" " ./a.out" +Thread attributes: + Detach state = PTHREAD_CREATE_JOINABLE + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_INHERIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 4096 bytes + Stack address = 0x40196000 + Stack size = 0x201000 bytes +.EE +.in +.PP +When we supply a stack size as a command-line argument, +the program initializes a thread attributes object, +sets various attributes in that object, +and passes a pointer to the object in the call to +.BR pthread_create (3). +Running the program on Linux/x86-32 with the NPTL threading implementation, +we see the following: +.PP +.in +4n +.EX +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +.RB "$" " ./a.out 0x3000000" +posix_memalign() allocated at 0x40197000 +Thread attributes: + Detach state = PTHREAD_CREATE_DETACHED + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_EXPLICIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 0 bytes + Stack address = 0x40197000 + Stack size = 0x3000000 bytes +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void +display_pthread_attr(pthread_attr_t *attr, char *prefix) +{ + int s, i; + size_t v; + void *stkaddr; + struct sched_param sp; + + s = pthread_attr_getdetachstate(attr, &i); + if (s != 0) + handle_error_en(s, "pthread_attr_getdetachstate"); + printf("%sDetach state = %s\\n", prefix, + (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : + (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : + "???"); + + s = pthread_attr_getscope(attr, &i); + if (s != 0) + handle_error_en(s, "pthread_attr_getscope"); + printf("%sScope = %s\\n", prefix, + (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : + (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : + "???"); + + s = pthread_attr_getinheritsched(attr, &i); + if (s != 0) + handle_error_en(s, "pthread_attr_getinheritsched"); + printf("%sInherit scheduler = %s\\n", prefix, + (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : + (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : + "???"); + + s = pthread_attr_getschedpolicy(attr, &i); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedpolicy"); + printf("%sScheduling policy = %s\\n", prefix, + (i == SCHED_OTHER) ? "SCHED_OTHER" : + (i == SCHED_FIFO) ? "SCHED_FIFO" : + (i == SCHED_RR) ? "SCHED_RR" : + "???"); + + s = pthread_attr_getschedparam(attr, &sp); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedparam"); + printf("%sScheduling priority = %d\\n", prefix, sp.sched_priority); + + s = pthread_attr_getguardsize(attr, &v); + if (s != 0) + handle_error_en(s, "pthread_attr_getguardsize"); + printf("%sGuard size = %d bytes\\n", prefix, v); + + s = pthread_attr_getstack(attr, &stkaddr, &v); + if (s != 0) + handle_error_en(s, "pthread_attr_getstack"); + printf("%sStack address = %p\\n", prefix, stkaddr); + printf("%sStack size = 0x%zx bytes\\n", prefix, v); +} + +static void * +thread_start(void *arg) +{ + int s; + pthread_attr_t gattr; + + /* pthread_getattr_np() is a non\-standard GNU extension that + retrieves the attributes of the thread specified in its + first argument */ + + s = pthread_getattr_np(pthread_self(), &gattr); + if (s != 0) + handle_error_en(s, "pthread_getattr_np"); + + printf("Thread attributes:\\n"); + display_pthread_attr(&gattr, "\\t"); + + exit(EXIT_SUCCESS); /* Terminate all threads */ +} + +int +main(int argc, char *argv[]) +{ + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp; /* NULL or &attr */ + int s; + + attrp = NULL; + + /* If a command\-line argument was supplied, use it to set the + stack\-size attribute and set a few other thread attributes, + and set attrp pointing to thread attributes object */ + + if (argc > 1) { + int stack_size; + void *sp; + + attrp = &attr; + + s = pthread_attr_init(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); + + s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); + if (s != 0) + handle_error_en(s, "pthread_attr_setdetachstate"); + + s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); + if (s != 0) + handle_error_en(s, "pthread_attr_setinheritsched"); + + stack_size = strtoul(argv[1], NULL, 0); + + s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); + if (s != 0) + handle_error_en(s, "posix_memalign"); + + printf("posix_memalign() allocated at %p\\n", sp); + + s = pthread_attr_setstack(&attr, sp, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstack"); + } + + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); + } + + pause(); /* Terminates when other thread calls exit() */ +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_setaffinity_np (3), +.BR pthread_attr_setdetachstate (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_attr_setscope (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstackaddr (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthread_getattr_np (3), +.BR pthread_setattr_default_np (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setaffinity_np.3 b/man3/pthread_attr_setaffinity_np.3 new file mode 100644 index 0000000..6c3e61f --- /dev/null +++ b/man3/pthread_attr_setaffinity_np.3 @@ -0,0 +1,146 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETAFFINITY_NP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get +CPU affinity attribute in thread attributes object +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int pthread_attr_setaffinity_np(pthread_attr_t *" attr , +.BI " size_t " cpusetsize ", const cpu_set_t *" cpuset ); +.BI "int pthread_attr_getaffinity_np(const pthread_attr_t *" attr , +.BI " size_t " cpusetsize ", cpu_set_t *" cpuset ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setaffinity_np () +function +sets the CPU affinity mask attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR cpuset . +This attribute determines the CPU affinity mask +of a thread created using the thread attributes object +.IR attr . +.PP +The +.BR pthread_attr_getaffinity_np () +function +returns the CPU affinity mask attribute of the thread attributes object +referred to by +.IR attr +in the buffer pointed to by +.IR cpuset . +.PP +The argument +.I cpusetsize +is the length (in bytes) of the buffer pointed to by +.IR cpuset . +Typically, this argument would be specified as +.IR sizeof(cpu_set_t) . +.PP +For more details on CPU affinity masks, see +.BR sched_setaffinity (2). +For a description of a set of macros +that can be used to manipulate and inspect CPU sets, see +.BR CPU_SET (3). +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.TP +.BR EINVAL +.RB ( pthread_attr_setaffinity_np ()) +.I cpuset +specified a CPU that was outside the set supported by the kernel. +(The kernel configuration option +.BR CONFIG_NR_CPUS +defines the range of the set supported by the kernel data type +.\" cpumask_t +used to represent CPU sets.) +.\" The raw sched_getaffinity() system call returns the size (in bytes) +.\" of the cpumask_t type. +.TP +.B EINVAL +.RB ( pthread_attr_getaffinity_np ()) +A CPU in the affinity mask of the thread attributes object referred to by +.I attr +lies outside the range specified by +.IR cpusetsize +(i.e., +.IR cpuset / cpusetsize +is too small). +.TP +.B ENOMEM +.RB ( pthread_attr_setaffinity_np ()) +Could not allocate memory. +.SH VERSIONS +These functions are provided by glibc since version 2.3.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setaffinity_np (), +.BR pthread_attr_getaffinity_np () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +These functions are nonstandard GNU extensions; +hence the suffix "_np" (nonportable) in the names. +.SH NOTES +In glibc 2.3.3 only, +versions of these functions were provided that did not have a +.I cpusetsize +argument. +Instead the CPU set size given to the underlying system calls was always +.IR sizeof(cpu_set_t) . +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR pthread_attr_init (3), +.BR pthread_setaffinity_np (3), +.BR cpuset (7), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setdetachstate.3 b/man3/pthread_attr_setdetachstate.3 new file mode 100644 index 0000000..d56119f --- /dev/null +++ b/man3/pthread_attr_setdetachstate.3 @@ -0,0 +1,138 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETDETACHSTATE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setdetachstate, pthread_attr_getdetachstate \- +set/get detach state attribute in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setdetachstate(pthread_attr_t *" attr \ +", int " detachstate ); +.BI "int pthread_attr_getdetachstate(const pthread_attr_t *" attr \ +", int *" detachstate ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setdetachstate () +function sets the detach state attribute of the +thread attributes object referred to by +.IR attr +to the value specified in +.IR detachstate . +The detach state attribute determines whether a thread created using +the thread attributes object +.I attr +will be created in a joinable or a detached state. +.PP +The following values may be specified in +.IR detachstate : +.TP +.B PTHREAD_CREATE_DETACHED +Threads that are created using +.I attr +will be created in a detached state. +.TP +.B PTHREAD_CREATE_JOINABLE +Threads that are created using +.I attr +will be created in a joinable state. +.PP +The default setting of the detach state attribute in a newly initialized +thread attributes object is +.BR PTHREAD_CREATE_JOINABLE . +.PP +The +.BR pthread_attr_getdetachstate () +returns the detach state attribute of the thread attributes object +.IR attr +in the buffer pointed to by +.IR detachstate . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setdetachstate () +can fail with the following error: +.TP +.B EINVAL +An invalid value was specified in +.IR detachstate . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setdetachstate (), +.BR pthread_attr_getdetachstate () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +See +.BR pthread_create (3) +for more details on detached and joinable threads. +.PP +A thread that is created in a joinable state should +eventually either be joined using +.BR pthread_join (3) +or detached using +.BR pthread_detach (3); +see +.BR pthread_create (3). +.PP +It is an error to specify the thread ID of +a thread that was created in a detached state +in a later call to +.BR pthread_detach (3) +or +.BR pthread_join (3). +.SH EXAMPLE +See +.BR pthread_attr_init (3). +.SH SEE ALSO +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthread_detach (3), +.BR pthread_join (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setguardsize.3 b/man3/pthread_attr_setguardsize.3 new file mode 100644 index 0000000..a82e2ef --- /dev/null +++ b/man3/pthread_attr_setguardsize.3 @@ -0,0 +1,187 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETGUARDSIZE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard size +attribute in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \ +", size_t " guardsize ); +.BI "int pthread_attr_getguardsize(const pthread_attr_t *" attr \ +", size_t *" guardsize ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setguardsize () +function sets the guard size attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR guardsize . +.PP +If +.I guardsize +is greater than 0, +then for each new thread created using +.I attr +the system allocates an additional region of at least +.I guardsize +bytes at the end of the thread's stack to act as the guard area +for the stack (but see BUGS). +.PP +If +.I guardsize +is 0, then new threads created with +.I attr +will not have a guard area. +.PP +The default guard size is the same as the system page size. +.PP +If the stack address attribute has been set in +.I attr +(using +.BR pthread_attr_setstack (3) +or +.BR pthread_attr_setstackaddr (3)), +meaning that the caller is allocating the thread's stack, +then the guard size attribute is ignored +(i.e., no guard area is created by the system): +it is the application's responsibility to handle stack overflow +(perhaps by using +.BR mprotect (2) +to manually define a guard area at the end of the stack +that it has allocated). +.PP +The +.BR pthread_attr_getguardsize () +function returns the guard size attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR guardsize . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +POSIX.1 documents an +.B EINVAL +error if +.I attr +or +.I guardsize +is invalid. +On Linux these functions always succeed +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH VERSIONS +These functions are provided by glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setguardsize (), +.BR pthread_attr_getguardsize () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +A guard area consists of virtual memory pages that are protected +to prevent read and write access. +If a thread overflows its stack into the guard area, +then, on most hard architectures, it receives a +.B SIGSEGV +signal, thus notifying it of the overflow. +Guard areas start on page boundaries, +and the guard size is internally rounded up to +the system page size when creating a thread. +(Nevertheless, +.BR pthread_attr_getguardsize () +returns the guard size that was set by +.BR pthread_attr_setguardsize ().) +.PP +Setting a guard size of 0 may be useful to save memory +in an application that creates many threads +and knows that stack overflow can never occur. +.PP +Choosing a guard size larger than the default size +may be necessary for detecting stack overflows +if a thread allocates large data structures on the stack. +.SH BUGS +As at glibc 2.8, the NPTL threading implementation includes +the guard area within the stack size allocation, +rather than allocating extra space at the end of the stack, +as POSIX.1 requires. +(This can result in an +.B EINVAL +error from +.BR pthread_create (3) +if the guard size value is too large, +leaving no space for the actual stack.) +.PP +The obsolete LinuxThreads implementation did the right thing, +allocating extra space at the end of the stack for the guard area. +.\" glibc includes the guardsize within the allocated stack size, +.\" which looks pretty clearly to be in violation of POSIX. +.\" +.\" Filed bug, 22 Oct 2008: +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6973 +.\" +.\" Older reports: +.\" https//bugzilla.redhat.com/show_bug.cgi?id=435337 +.\" Reportedly, LinuxThreads did the right thing, allocating +.\" extra space at the end of the stack: +.\" http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html +.SH EXAMPLE +See +.BR pthread_getattr_np (3). +.SH SEE ALSO +.BR mmap (2), +.BR mprotect (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setinheritsched.3 b/man3/pthread_attr_setinheritsched.3 new file mode 100644 index 0000000..bf1e211 --- /dev/null +++ b/man3/pthread_attr_setinheritsched.3 @@ -0,0 +1,164 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETINHERITSCHED 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setinheritsched, pthread_attr_getinheritsched \- set/get +inherit-scheduler attribute in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setinheritsched(pthread_attr_t *" attr , +.BI " int " inheritsched ); +.BI "int pthread_attr_getinheritsched(const pthread_attr_t *" attr , +.BI " int *" inheritsched ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setinheritsched () +function sets the inherit-scheduler attribute of the +thread attributes object referred to by +.IR attr +to the value specified in +.IR inheritsched . +The inherit-scheduler attribute determines whether a thread created using +the thread attributes object +.I attr +will inherit its scheduling attributes from the calling thread +or whether it will take them from +.IR attr . +.PP +The following scheduling attributes are affected by the +inherit-scheduler attribute: +scheduling policy +.RB ( pthread_attr_setschedpolicy (3)), +scheduling priority +.RB ( pthread_attr_setschedparam (3)), +and contention scope +.RB ( pthread_attr_setscope (3)). +.PP +The following values may be specified in +.IR inheritsched : +.TP +.B PTHREAD_INHERIT_SCHED +Threads that are created using +.I attr +inherit scheduling attributes from the creating thread; +the scheduling attributes in +.I attr +are ignored. +.TP +.B PTHREAD_EXPLICIT_SCHED +Threads that are created using +.I attr +take their scheduling attributes from the values specified +by the attributes object. +.\" FIXME Document the defaults for scheduler settings +.PP +The default setting of the inherit-scheduler attribute in +a newly initialized thread attributes object is +.BR PTHREAD_INHERIT_SCHED . +.PP +The +.BR pthread_attr_getinheritsched () +returns the inherit-scheduler attribute of the thread attributes object +.IR attr +in the buffer pointed to by +.IR inheritsched . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setinheritsched () +can fail with the following error: +.TP +.B EINVAL +Invalid value in +.IR inheritsched . +.PP +POSIX.1 also documents an optional +.B ENOTSUP +error ("attempt was made to set the attribute to an unsupported value") for +.BR pthread_attr_setinheritsched (). +.\" .SH VERSIONS +.\" Available since glibc 2.0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setinheritsched (), +.BR pthread_attr_getinheritsched () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH BUGS +As at glibc 2.8, if a thread attributes object is initialized using +.BR pthread_attr_init (3), +then the scheduling policy of the attributes object is set to +.BR SCHED_OTHER +and the scheduling priority is set to 0. +However, if the inherit-scheduler attribute is then set to +.BR PTHREAD_EXPLICIT_SCHED , +then a thread created using the attribute object +wrongly inherits its scheduling attributes from the creating thread. +This bug does not occur if either the scheduling policy or +scheduling priority attribute is explicitly set +in the thread attributes object before calling +.BR pthread_create (3). +.\" FIXME . Track status of the following bug: +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7007 +.SH EXAMPLE +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_attr_setscope (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setschedparam.3 b/man3/pthread_attr_setschedparam.3 new file mode 100644 index 0000000..fd56841 --- /dev/null +++ b/man3/pthread_attr_setschedparam.3 @@ -0,0 +1,149 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETSCHEDPARAM 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setschedparam, pthread_attr_getschedparam \- set/get +scheduling parameter attributes in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setschedparam(pthread_attr_t *" attr , +.BI " const struct sched_param *" param ); +.BI "int pthread_attr_getschedparam(const pthread_attr_t *" attr , +.BI " struct sched_param *" param ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setschedparam () +function sets the scheduling parameter attributes of the +thread attributes object referred to by +.IR attr +to the values specified in the buffer pointed to by +.IR param . +These attributes determine the scheduling parameters of +a thread created using the thread attributes object +.IR attr . +.PP +The +.BR pthread_attr_getschedparam () +returns the scheduling parameter attributes of the thread attributes object +.IR attr +in the buffer pointed to by +.IR param . +.PP +Scheduling parameters are maintained in the following structure: +.PP +.in +4n +.EX +struct sched_param { + int sched_priority; /* Scheduling priority */ +}; +.EE +.in +.PP +As can be seen, only one scheduling parameter is supported. +For details of the permitted ranges for scheduling priorities +in each scheduling policy, see +.BR sched (7). +.PP +In order for the parameter setting made by +.BR pthread_attr_setschedparam () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setschedparam () +can fail with the following error: +.TP +.B EINVAL +The priority specified in +.I param +does not make sense for the current scheduling policy of +.IR attr . +.PP +POSIX.1 also documents an +.B ENOTSUP +error for +.BR pthread_attr_setschedparam (). +This value is never returned on Linux +(but portable and future-proof applications should nevertheless +handle this error return value). +.\" .SH VERSIONS +.\" Available since glibc 2.0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw29 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setschedparam (), +.BR pthread_attr_getschedparam () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +See +.BR pthread_attr_setschedpolicy (3) +for a list of the thread scheduling policies supported on Linux. +.SH EXAMPLE +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setschedpolicy.3 b/man3/pthread_attr_setschedpolicy.3 new file mode 100644 index 0000000..e791fad --- /dev/null +++ b/man3/pthread_attr_setschedpolicy.3 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETSCHEDPOLICY 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setschedpolicy, pthread_attr_getschedpolicy \- set/get +scheduling policy attribute in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setschedpolicy(pthread_attr_t *" attr \ +", int " policy ); +.BI "int pthread_attr_getschedpolicy(const pthread_attr_t *" attr \ +", int " *policy ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setschedpolicy () +function sets the scheduling policy attribute of the +thread attributes object referred to by +.IR attr +to the value specified in +.IR policy . +This attribute determines the scheduling policy of +a thread created using the thread attributes object +.IR attr . +.PP +The supported values for +.I policy +are +.BR SCHED_FIFO , +.BR SCHED_RR , +and +.BR SCHED_OTHER , +with the semantics described in +.BR sched (7). +.\" FIXME . pthread_setschedparam() places no restriction on the policy, +.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 +.PP +The +.BR pthread_attr_getschedpolicy () +returns the scheduling policy attribute of the thread attributes object +.IR attr +in the buffer pointed to by +.IR policy . +.PP +In order for the policy setting made by +.BR pthread_attr_setschedpolicy () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setschedpolicy () +can fail with the following error: +.TP +.B EINVAL +Invalid value in +.IR policy . +.PP +POSIX.1 also documents an optional +.B ENOTSUP +error ("attempt was made to set the attribute to an unsupported value") for +.BR pthread_attr_setschedpolicy (). +.\" .SH VERSIONS +.\" Available since glibc 2.0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setschedpolicy (), +.BR pthread_attr_getschedpolicy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setscope.3 b/man3/pthread_attr_setscope.3 new file mode 100644 index 0000000..4229a97 --- /dev/null +++ b/man3/pthread_attr_setscope.3 @@ -0,0 +1,163 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETSCOPE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope +attribute in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setscope(pthread_attr_t *" attr \ +", int " scope ); +.BI "int pthread_attr_getscope(const pthread_attr_t *" attr \ +", int *" scope ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setscope () +function sets the contention scope attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR scope . +The contention scope attribute defines the set of threads +against which a thread competes for resources such as the CPU. +POSIX.1 specifies two possible values for +.IR scope : +.TP +.B PTHREAD_SCOPE_SYSTEM +The thread competes for resources with all other threads +in all processes on the system that are in the same scheduling +allocation domain (a group of one or more processors). +.B PTHREAD_SCOPE_SYSTEM +threads are scheduled relative to one another +according to their scheduling policy and priority. +.TP +.B PTHREAD_SCOPE_PROCESS +The thread competes for resources with all other threads +in the same process that were also created with the +.BR PTHREAD_SCOPE_PROCESS +contention scope. +.BR PTHREAD_SCOPE_PROCESS +threads are scheduled relative to other threads in the process +according to their scheduling policy and priority. +POSIX.1 leaves it unspecified how these threads contend +with other threads in other process on the system or +with other threads in the same process that +were created with the +.B PTHREAD_SCOPE_SYSTEM +contention scope. +.PP +POSIX.1 requires that an implementation support at least one of these +contention scopes. +Linux supports +.BR PTHREAD_SCOPE_SYSTEM , +but not +.BR PTHREAD_SCOPE_PROCESS . +.PP +On systems that support multiple contention scopes, then, +in order for the parameter setting made by +.BR pthread_attr_setscope () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.PP +The +.BR pthread_attr_getscope () +function returns the contention scope attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR scope . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setscope () +can fail with the following errors: +.TP +.B EINVAL +An invalid value was specified in +.IR scope . +.TP +.B ENOTSUP +.IR scope +specified the value +.BR PTHREAD_SCOPE_PROCESS , +which is not supported on Linux. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setscope (), +.BR pthread_attr_getscope () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The +.B PTHREAD_SCOPE_SYSTEM +contention scope typically indicates that a user-space thread is +bound directly to a single kernel-scheduling entity. +This is the case on Linux for the obsolete LinuxThreads implementation +and the modern NPTL implementation, +which are both 1:1 threading implementations. +.PP +POSIX.1 specifies that the default contention scope is +implementation-defined. +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setstack.3 b/man3/pthread_attr_setstack.3 new file mode 100644 index 0000000..94f7741 --- /dev/null +++ b/man3/pthread_attr_setstack.3 @@ -0,0 +1,188 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETSTACK 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setstack, pthread_attr_getstack \- set/get stack +attributes in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setstack(pthread_attr_t *" attr , +.BI " void *" stackaddr ", size_t " stacksize ); +.BI "int pthread_attr_getstack(const pthread_attr_t *" attr , +.BI " void **" stackaddr ", size_t *" stacksize ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR pthread_attr_getstack (), +.BR pthread_attr_setstack (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad b +.SH DESCRIPTION +The +.BR pthread_attr_setstack () +function sets the stack address and stack size attributes of the +thread attributes object referred to by +.I attr +to the values specified in +.IR stackaddr +and +.IR stacksize , +respectively. +These attributes specify the location and size of the stack that should +be used by a thread that is created using the thread attributes object +.IR attr . +.PP +.I stackaddr +should point to the lowest addressable byte of a buffer of +.I stacksize +bytes that was allocated by the caller. +The pages of the allocated buffer should be both readable and writable. +.PP +The +.BR pthread_attr_getstack () +function returns the stack address and stack size attributes of the +thread attributes object referred to by +.I attr +in the buffers pointed to by +.IR stackaddr +and +.IR stacksize , +respectively. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setstack () +can fail with the following error: +.TP +.B EINVAL +.I stacksize +is less than +.BR PTHREAD_STACK_MIN +(16384) bytes. +On some systems, this error may also occur if +.IR stackaddr +or +.IR "stackaddr\ +\ stacksize" +is not suitably aligned. +.PP +POSIX.1 also documents an +.BR EACCES +error if the stack area described by +.I stackaddr +and +.I stacksize +is not both readable and writable by the caller. +.SH VERSIONS +These functions are provided by glibc since version 2.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setstack (), +.BR pthread_attr_getstack () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +These functions are provided for applications that must ensure that +a thread's stack is placed in a particular location. +For most applications, this is not necessary, +and the use of these functions should be avoided. +(Use +.BR pthread_attr_setstacksize (3) +if an application simply requires a stack size other than the default.) +.PP +When an application employs +.BR pthread_attr_setstack (), +it takes over the responsibility of allocating the stack. +Any guard size value that was set using +.BR pthread_attr_setguardsize (3) +is ignored. +If deemed necessary, +it is the application's responsibility to allocate a guard area +(one or more pages protected against reading and writing) +to handle the possibility of stack overflow. +.PP +The address specified in +.I stackaddr +should be suitably aligned: +for full portability, align it on a page boundary +.RI ( sysconf(_SC_PAGESIZE) ). +.BR posix_memalign (3) +may be useful for allocation. +Probably, +.IR stacksize +should also be a multiple of the system page size. +.PP +If +.I attr +is used to create multiple threads, then the caller must change the +stack address attribute between calls to +.BR pthread_create (3); +otherwise, the threads will attempt to use the same memory area +for their stacks, and chaos will ensue. +.SH EXAMPLE +See +.BR pthread_attr_init (3). +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR mprotect (2), +.BR posix_memalign (3), +.BR pthread_attr_init (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setstackaddr (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setstackaddr.3 b/man3/pthread_attr_setstackaddr.3 new file mode 100644 index 0000000..1321cfa --- /dev/null +++ b/man3/pthread_attr_setstackaddr.3 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETSTACKADDR 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setstackaddr, pthread_attr_getstackaddr \- +set/get stack address attribute in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setstackaddr(pthread_attr_t *" attr \ +", void *" stackaddr ); +.BI "int pthread_attr_getstackaddr(const pthread_attr_t *" attr \ +", void **" stackaddr ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +These functions are obsolete: +.B do not use them. +Use +.BR pthread_attr_setstack (3) +and +.BR pthread_attr_getstack (3) +instead. +.PP +The +.BR pthread_attr_setstackaddr () +function sets the stack address attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR stackaddr . +This attribute specifies the location of the stack that should +be used by a thread that is created using the thread attributes object +.IR attr . +.PP +.I stackaddr +should point to a buffer of at least +.B PTHREAD_STACK_MIN +bytes that was allocated by the caller. +The pages of the allocated buffer should be both readable and writable. +.PP +The +.BR pthread_attr_getstackaddr () +function returns the stack address attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR stackaddr . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +No errors are defined +(but applications should nevertheless +handle a possible error return). +.SH VERSIONS +These functions are provided by glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setstackaddr (), +.BR pthread_attr_getstackaddr () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001 specifies these functions but marks them as obsolete. +POSIX.1-2008 removes the specification of these functions. +.SH NOTES +.I Do not use these functions! +They cannot be portably used, since they provide no way of specifying +the direction of growth or the range of the stack. +For example, on architectures with a stack that grows downward, +.I stackaddr +specifies the next address past the +.I highest +address of the allocated stack area. +However, on architectures with a stack that grows upward, +.I stackaddr +specifies the +.I lowest +address in the allocated stack area. +By contrast, the +.I stackaddr +used by +.BR pthread_attr_setstack (3) +and +.BR pthread_attr_getstack (3), +is always a pointer to the lowest address in the allocated stack area +(and the +.I stacksize +argument specifies the range of the stack). +.SH SEE ALSO +.BR pthread_attr_init (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_attr_setstacksize.3 b/man3/pthread_attr_setstacksize.3 new file mode 100644 index 0000000..b79b8b7 --- /dev/null +++ b/man3/pthread_attr_setstacksize.3 @@ -0,0 +1,139 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_ATTR_SETSTACKSIZE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_attr_setstacksize, pthread_attr_getstacksize \- set/get stack size +attribute in thread attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_attr_setstacksize(pthread_attr_t *" attr \ +", size_t " stacksize ); +.BI "int pthread_attr_getstacksize(const pthread_attr_t *" attr \ +", size_t *" stacksize ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setstacksize () +function sets the stack size attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR stacksize . +.PP +The stack size attribute determines the minimum size (in bytes) that +will be allocated for threads created using the thread attributes object +.IR attr . +.PP +The +.BR pthread_attr_getstacksize () +function returns the stack size attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR stacksize . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setstacksize () +can fail with the following error: +.TP +.B EINVAL +The stack size is less than +.BR PTHREAD_STACK_MIN +(16384) bytes. +.PP +On some systems, +.\" e.g., MacOS +.BR pthread_attr_setstacksize () +can fail with the error +.B EINVAL +if +.I stacksize +is not a multiple of the system page size. +.SH VERSIONS +These functions are provided by glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_attr_setstacksize (), +.BR pthread_attr_getstacksize () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +For details on the default stack size of new threads, see +.BR pthread_create (3). +.PP +A thread's stack size is fixed at the time of thread creation. +Only the main thread can dynamically grow its stack. +.PP +The +.BR pthread_attr_setstack (3) +function allows an application to set both the size and location +of a caller-allocated stack that is to be used by a thread. +.SH BUGS +As at glibc 2.8, +if the specified +.I stacksize +is not a multiple of +.BR STACK_ALIGN +(16 bytes on most architectures), it may be rounded +.IR downward , +in violation of POSIX.1, which says that the allocated stack will +be at least +.I stacksize +bytes. +.SH EXAMPLE +See +.BR pthread_create (3). +.SH SEE ALSO +.BR getrlimit (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setstack (3), +.BR pthread_create (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_cancel.3 b/man3/pthread_cancel.3 new file mode 100644 index 0000000..ee1df32 --- /dev/null +++ b/man3/pthread_cancel.3 @@ -0,0 +1,259 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_CANCEL 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_cancel \- send a cancellation request to a thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_cancel(pthread_t " thread ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_cancel () +function sends a cancellation request to the thread +.IR thread . +Whether and when the target thread +reacts to the cancellation request depends on +two attributes that are under the control of that thread: +its cancelability +.I state +and +.IR type . +.PP +A thread's cancelability state, determined by +.BR pthread_setcancelstate (3), +can be +.I enabled +(the default for new threads) or +.IR disabled . +If a thread has disabled cancellation, +then a cancellation request remains queued until the thread +enables cancellation. +If a thread has enabled cancellation, +then its cancelability type determines when cancellation occurs. +.PP +A thread's cancellation type, determined by +.BR pthread_setcanceltype (3), +may be either +.IR asynchronous +or +.IR deferred +(the default for new threads). +Asynchronous cancelability +means that the thread can be canceled at any time +(usually immediately, but the system does not guarantee this). +Deferred cancelability means that cancellation will be delayed until +the thread next calls a function that is a +.IR "cancellation point" . +A list of functions that are or may be cancellation points is provided in +.BR pthreads (7). +.PP +When a cancellation requested is acted on, the following steps occur for +.IR thread +(in this order): +.IP 1. 3 +Cancellation clean-up handlers are popped +(in the reverse of the order in which they were pushed) and called. +(See +.BR pthread_cleanup_push (3).) +.IP 2. +Thread-specific data destructors are called, +in an unspecified order. +(See +.BR pthread_key_create (3).) +.IP 3. +The thread is terminated. +(See +.BR pthread_exit (3).) +.PP +The above steps happen asynchronously with respect to the +.BR pthread_cancel () +call; +the return status of +.BR pthread_cancel () +merely informs the caller whether the cancellation request +was successfully queued. +.PP +After a canceled thread has terminated, +a join with that thread using +.BR pthread_join (3) +obtains +.B PTHREAD_CANCELED +as the thread's exit status. +(Joining with a thread is the only way to know that cancellation +has completed.) +.SH RETURN VALUE +On success, +.BR pthread_cancel () +returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.\" .SH VERSIONS +.\" Available since glibc 2.0 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_cancel () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +On Linux, cancellation is implemented using signals. +Under the NPTL threading implementation, +the first real-time signal (i.e., signal 32) is used for this purpose. +On LinuxThreads, the second real-time signal is used, +if real-time signals are available, otherwise +.B SIGUSR2 +is used. +.SH EXAMPLE +The program below creates a thread and then cancels it. +The main thread joins with the canceled thread to check +that its exit status was +.BR PTHREAD_CANCELED . +The following shell session shows what happens when we run the program: +.PP +.in +4n +.EX +$ ./a.out +thread_func(): started; cancellation disabled +main(): sending cancellation request +thread_func(): about to enable cancellation +main(): thread was canceled +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void * +thread_func(void *ignored_argument) +{ + int s; + + /* Disable cancellation for a while, so that we don\(aqt + immediately react to a cancellation request */ + + s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); + if (s != 0) + handle_error_en(s, "pthread_setcancelstate"); + + printf("thread_func(): started; cancellation disabled\\n"); + sleep(5); + printf("thread_func(): about to enable cancellation\\n"); + + s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL); + if (s != 0) + handle_error_en(s, "pthread_setcancelstate"); + + /* sleep() is a cancellation point */ + + sleep(1000); /* Should get canceled while we sleep */ + + /* Should never get here */ + + printf("thread_func(): not canceled!\\n"); + return NULL; +} + +int +main(void) +{ + pthread_t thr; + void *res; + int s; + + /* Start a thread and then send it a cancellation request */ + + s = pthread_create(&thr, NULL, &thread_func, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + sleep(2); /* Give thread a chance to get started */ + + printf("main(): sending cancellation request\\n"); + s = pthread_cancel(thr); + if (s != 0) + handle_error_en(s, "pthread_cancel"); + + /* Join with thread to see what its exit status was */ + + s = pthread_join(thr, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); + + if (res == PTHREAD_CANCELED) + printf("main(): thread was canceled\\n"); + else + printf("main(): thread wasn\(aqt canceled (shouldn\(aqt happen!)\\n"); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR pthread_cleanup_push (3), +.BR pthread_create (3), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR pthread_key_create (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthread_testcancel (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_cleanup_pop.3 b/man3/pthread_cleanup_pop.3 new file mode 100644 index 0000000..fb0e68b --- /dev/null +++ b/man3/pthread_cleanup_pop.3 @@ -0,0 +1 @@ +.so man3/pthread_cleanup_push.3 diff --git a/man3/pthread_cleanup_pop_restore_np.3 b/man3/pthread_cleanup_pop_restore_np.3 new file mode 100644 index 0000000..c47e20a --- /dev/null +++ b/man3/pthread_cleanup_pop_restore_np.3 @@ -0,0 +1 @@ +.so man3/pthread_cleanup_push_defer_np.3 diff --git a/man3/pthread_cleanup_push.3 b/man3/pthread_cleanup_push.3 new file mode 100644 index 0000000..52e0ec1 --- /dev/null +++ b/man3/pthread_cleanup_push.3 @@ -0,0 +1,343 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_CLEANUP_PUSH 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_cleanup_push, pthread_cleanup_pop \- push and pop +thread cancellation clean-up handlers +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void pthread_cleanup_push(void (*" routine ")(void *)," +.BI " void *" arg ); +.BI "void pthread_cleanup_pop(int " execute ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +These functions manipulate the calling thread's stack of +thread-cancellation clean-up handlers. +A clean-up handler is a function that is automatically executed +when a thread is canceled (or in various other circumstances +described below); +it might, for example, unlock a mutex so that +it becomes available to other threads in the process. +.PP +The +.BR pthread_cleanup_push () +function pushes +.I routine +onto the top of the stack of clean-up handlers. +When +.I routine +is later invoked, it will be given +.I arg +as its argument. +.PP +The +.BR pthread_cleanup_pop () +function removes the routine at the top of the stack of clean-up handlers, +and optionally executes it if +.I execute +is nonzero. +.PP +A cancellation clean-up handler is popped from the stack +and executed in the following circumstances: +.IP 1. 3 +When a thread is canceled, +all of the stacked clean-up handlers are popped and executed in +the reverse of the order in which they were pushed onto the stack. +.IP 2. +When a thread terminates by calling +.BR pthread_exit (3), +all clean-up handlers are executed as described in the preceding point. +(Clean-up handlers are +.I not +called if the thread terminates by +performing a +.I return +from the thread start function.) +.IP 3. +When a thread calls +.BR pthread_cleanup_pop () +with a nonzero +.I execute +argument, the top-most clean-up handler is popped and executed. +.PP +POSIX.1 permits +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +to be implemented as macros that expand to text +containing \(aq\fB{\fP\(aq and \(aq\fB}\fP\(aq, respectively. +For this reason, the caller must ensure that calls to these +functions are paired within the same function, +and at the same lexical nesting level. +(In other words, a clean-up handler is established only +during the execution of a specified section of code.) +.PP +Calling +.BR longjmp (3) +.RB ( siglongjmp (3)) +produces undefined results if any call has been made to +.BR pthread_cleanup_push () +or +.BR pthread_cleanup_pop () +without the matching call of the pair since the jump buffer +was filled by +.BR setjmp (3) +.RB ( sigsetjmp (3)). +Likewise, calling +.BR longjmp (3) +.RB ( siglongjmp (3)) +from inside a clean-up handler produces undefined results +unless the jump buffer was also filled by +.BR setjmp (3) +.RB ( sigsetjmp (3)) +inside the handler. +.SH RETURN VALUE +These functions do not return a value. +.SH ERRORS +There are no errors. +.\" SH VERSIONS +.\" Available since glibc 2.0 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_cleanup_push (), +.BR pthread_cleanup_pop () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +On Linux, the +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +functions +.I are +implemented as macros that expand to text +containing \(aq\fB{\fP\(aq and \(aq\fB}\fP\(aq, respectively. +This means that variables declared within the scope of +paired calls to these functions will be visible within only that scope. +.PP +POSIX.1 +.\" The text was actually added in the 2004 TC2 +says that the effect of using +.IR return , +.IR break , +.IR continue , +or +.IR goto +to prematurely leave a block bracketed +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +is undefined. +Portable applications should avoid doing this. +.SH EXAMPLE +The program below provides a simple example of the use of the functions +described in this page. +The program creates a thread that executes a loop bracketed by +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop (). +This loop increments a global variable, +.IR cnt , +once each second. +Depending on what command-line arguments are supplied, +the main thread sends the other thread a cancellation request, +or sets a global variable that causes the other thread +to exit its loop and terminate normally (by doing a +.IR return ). +.PP +In the following shell session, +the main thread sends a cancellation request to the other thread: +.PP +.in +4n +.EX +$ \fB./a.out\fP +New thread started +cnt = 0 +cnt = 1 +Canceling thread +Called clean-up handler +Thread was canceled; cnt = 0 +.EE +.in +.PP +From the above, we see that the thread was canceled, +and that the cancellation clean-up handler was called +and it reset the value of the global variable +.I cnt +to 0. +.PP +In the next run, the main program sets a +global variable that causes other thread to terminate normally: +.PP +.in +4n +.EX +$ \fB./a.out x\fP +New thread started +cnt = 0 +cnt = 1 +Thread terminated normally; cnt = 2 +.EE +.in +.PP +From the above, we see that the clean-up handler was not executed (because +.I cleanup_pop_arg +was 0), and therefore the value of +.I cnt +was not reset. +.PP +In the next run, the main program sets a global variable that +causes the other thread to terminate normally, +and supplies a nonzero value for +.IR cleanup_pop_arg : +.PP +.in +4n +.EX +$ \fB./a.out x 1\fP +New thread started +cnt = 0 +cnt = 1 +Called clean-up handler +Thread terminated normally; cnt = 0 +.EE +.in +.PP +In the above, we see that although the thread was not canceled, +the clean-up handler was executed, because the argument given to +.BR pthread_cleanup_pop () +was nonzero. +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static int done = 0; +static int cleanup_pop_arg = 0; +static int cnt = 0; + +static void +cleanup_handler(void *arg) +{ + printf("Called clean\-up handler\\n"); + cnt = 0; +} + +static void * +thread_start(void *arg) +{ + time_t start, curr; + + printf("New thread started\\n"); + + pthread_cleanup_push(cleanup_handler, NULL); + + curr = start = time(NULL); + + while (!done) { + pthread_testcancel(); /* A cancellation point */ + if (curr < time(NULL)) { + curr = time(NULL); + printf("cnt = %d\\n", cnt); /* A cancellation point */ + cnt++; + } + } + + pthread_cleanup_pop(cleanup_pop_arg); + return NULL; +} + +int +main(int argc, char *argv[]) +{ + pthread_t thr; + int s; + void *res; + + s = pthread_create(&thr, NULL, thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + sleep(2); /* Allow new thread to run a while */ + + if (argc > 1) { + if (argc > 2) + cleanup_pop_arg = atoi(argv[2]); + done = 1; + + } else { + printf("Canceling thread\\n"); + s = pthread_cancel(thr); + if (s != 0) + handle_error_en(s, "pthread_cancel"); + } + + s = pthread_join(thr, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); + + if (res == PTHREAD_CANCELED) + printf("Thread was canceled; cnt = %d\\n", cnt); + else + printf("Thread terminated normally; cnt = %d\\n", cnt); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push_defer_np (3), +.BR pthread_setcancelstate (3), +.BR pthread_testcancel (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_cleanup_push_defer_np.3 b/man3/pthread_cleanup_push_defer_np.3 new file mode 100644 index 0000000..93c6428 --- /dev/null +++ b/man3/pthread_cleanup_push_defer_np.3 @@ -0,0 +1,131 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_CLEANUP_PUSH_DEFER_NP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- push and pop +thread cancellation clean-up handlers while saving cancelability type +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void pthread_cleanup_push_defer_np(void (*" routine ")(void *)," +.BI " void *" arg ); +.BI "void pthread_cleanup_pop_restore_np(int " execute ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR pthread_cleanup_push_defer_np (), +.BR pthread_cleanup_pop_defer_np (): +.RS 4 +_GNU_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions are the same as +.BR pthread_cleanup_push (3) +and +.BR pthread_cleanup_pop (3), +except for the differences noted on this page. +.PP +Like +.BR pthread_cleanup_push (3), +.BR pthread_cleanup_push_defer_np () +pushes +.I routine +onto the thread's stack of cancellation clean-up handlers. +In addition, it also saves the thread's current cancelability type, +and sets the cancelability type to "deferred" (see +.BR pthread_setcanceltype (3)); +this ensures that cancellation clean-up will occur +even if the thread's cancelability type was "asynchronous" +before the call. +.PP +Like +.BR pthread_cleanup_pop (3), +.BR pthread_cleanup_pop_restore_np () +pops the top-most clean-up handler from the thread's +stack of cancellation clean-up handlers. +In addition, it restores the thread's cancelability +type to its value at the time of the matching +.BR pthread_cleanup_push_defer_np (). +.PP +The caller must ensure that calls to these +functions are paired within the same function, +and at the same lexical nesting level. +Other restrictions apply, as described in +.BR pthread_cleanup_push (3). +.PP +This sequence of calls: +.PP +.in +4n +.EX +pthread_cleanup_push_defer_np(routine, arg); +pthread_cleanup_pop_restore_np(execute); +.EE +.in +.PP +is equivalent to (but shorter and more efficient than): +.PP +.\" As far as I can see, LinuxThreads reverses the two substeps +.\" in the push and pop below. +.in +4n +.EX +int oldtype; + +pthread_cleanup_push(routine, arg); +pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype); +\&... +pthread_setcanceltype(oldtype, NULL); +pthread_cleanup_pop(execute); +.EE +.in +.\" SH VERSIONS +.\" Available since glibc 2.0 +.SH CONFORMING TO +These functions are nonstandard GNU extensions; +hence the suffix "_np" (nonportable) in the names. +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_setcancelstate (3), +.BR pthread_testcancel (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_create.3 b/man3/pthread_create.3 new file mode 100644 index 0000000..ad55471 --- /dev/null +++ b/man3/pthread_create.3 @@ -0,0 +1,411 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_CREATE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_create \- create a new thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_create(pthread_t *" thread ", const pthread_attr_t *" attr , +.BI " void *(*" start_routine ") (void *), void *" arg ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +The +.BR pthread_create () +function starts a new thread in the calling process. +The new thread starts execution by invoking +.IR start_routine (); +.IR arg +is passed as the sole argument of +.IR start_routine (). +.PP +The new thread terminates in one of the following ways: +.IP * 2 +It calls +.BR pthread_exit (3), +specifying an exit status value that is available to another thread +in the same process that calls +.BR pthread_join (3). +.IP * +It returns from +.IR start_routine (). +This is equivalent to calling +.BR pthread_exit (3) +with the value supplied in the +.I return +statement. +.IP * +It is canceled (see +.BR pthread_cancel (3)). +.IP * +Any of the threads in the process calls +.BR exit (3), +or the main thread performs a return from +.IR main (). +This causes the termination of all threads in the process. +.PP +The +.I attr +argument points to a +.I pthread_attr_t +structure whose contents are used at thread creation time to +determine attributes for the new thread; +this structure is initialized using +.BR pthread_attr_init (3) +and related functions. +If +.I attr +is NULL, +then the thread is created with default attributes. +.PP +Before returning, a successful call to +.BR pthread_create () +stores the ID of the new thread in the buffer pointed to by +.IR thread ; +this identifier is used to refer to the thread +in subsequent calls to other pthreads functions. +.PP +The new thread inherits a copy of the creating thread's signal mask +.RB ( pthread_sigmask (3)). +The set of pending signals for the new thread is empty +.RB ( sigpending (2)). +The new thread does not inherit the creating thread's +alternate signal stack +.RB ( sigaltstack (2)). +.PP +The new thread inherits the calling thread's floating-point environment +.RB ( fenv (3)). +.PP +The initial value of the new thread's CPU-time clock is 0 +(see +.BR pthread_getcpuclockid (3)). +.\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2) +.SS Linux-specific details +The new thread inherits copies of the calling thread's capability sets +(see +.BR capabilities (7)) +and CPU affinity mask (see +.BR sched_setaffinity (2)). +.SH RETURN VALUE +On success, +.BR pthread_create () +returns 0; +on error, it returns an error number, and the contents of +.IR *thread +are undefined. +.SH ERRORS +.TP +.B EAGAIN +Insufficient resources to create another thread. +.TP +.B EAGAIN +.\" NOTE! The following should match the description in fork(2) +A system-imposed limit on the number of threads was encountered. +There are a number of limits that may trigger this error: the +.BR RLIMIT_NPROC +soft resource limit (set via +.BR setrlimit (2)), +which limits the number of processes and threads for a real user ID, +was reached; +the kernel's system-wide limit on the number of processes and threads, +.IR /proc/sys/kernel/threads-max , +was reached (see +.BR proc (5)); +or the maximum number of PIDs, +.IR /proc/sys/kernel/pid_max , +was reached (see +.BR proc (5)). +.TP +.B EINVAL +Invalid settings in +.IR attr . +.TP +.\" FIXME . Test the following +.B EPERM +No permission to set the scheduling policy and parameters specified in +.IR attr . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_create () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +See +.BR pthread_self (3) +for further information on the thread ID returned in +.IR *thread +by +.BR pthread_create (). +Unless real-time scheduling policies are being employed, +after a call to +.BR pthread_create (), +it is indeterminate which thread\(emthe caller or the new thread\(emwill +next execute. +.PP +A thread may either be +.I joinable +or +.IR detached . +If a thread is joinable, then another thread can call +.BR pthread_join (3) +to wait for the thread to terminate and fetch its exit status. +Only when a terminated joinable thread has been joined are +the last of its resources released back to the system. +When a detached thread terminates, +its resources are automatically released back to the system: +it is not possible to join with the thread in order to obtain +its exit status. +Making a thread detached is useful for some types of daemon threads +whose exit status the application does not need to care about. +By default, a new thread is created in a joinable state, unless +.I attr +was set to create the thread in a detached state (using +.BR pthread_attr_setdetachstate (3)). +.PP +.\" FIXME . Perhaps some of the following detail should be in +.\" a future pthread_attr_setstacksize(3) page. +On Linux/x86-32, the default stack size for a new thread is 2 megabytes. +Under the NPTL threading implementation, if the +.BR RLIMIT_STACK +soft resource limit +.IR "at the time the program started" +has any value other than "unlimited", +then it determines the default stack size of new threads. +Using +.BR pthread_attr_setstacksize (3), +the stack size attribute can be explicitly set in the +.I attr +argument used to create a thread, +in order to obtain a stack size other than the default. +.SH BUGS +In the obsolete LinuxThreads implementation, +each of the threads in a process has a different process ID. +This is in violation of the POSIX threads specification, +and is the source of many other nonconformances to the standard; see +.BR pthreads (7). +.SH EXAMPLE +The program below demonstrates the use of +.BR pthread_create (), +as well as a number of other functions in the pthreads API. +.PP +In the following run, +on a system providing the NPTL threading implementation, +the stack size defaults to the value given by the +"stack size" resource limit: +.PP +.in +4n +.EX +.RB "$" " ulimit \-s" +8192 # The stack size limit is 8 MB (0x800000 bytes) +.RB "$" " ./a.out hola salut servus" +Thread 1: top of stack near 0xb7dd03b8; argv_string=hola +Thread 2: top of stack near 0xb75cf3b8; argv_string=salut +Thread 3: top of stack near 0xb6dce3b8; argv_string=servus +Joined with thread 1; returned value was HOLA +Joined with thread 2; returned value was SALUT +Joined with thread 3; returned value was SERVUS +.EE +.in +.PP +In the next run, the program explicitly sets a stack size of 1\ MB (using +.BR pthread_attr_setstacksize (3)) +for the created threads: +.PP +.in +4n +.EX +.RB "$" " ./a.out \-s 0x100000 hola salut servus" +Thread 1: top of stack near 0xb7d723b8; argv_string=hola +Thread 2: top of stack near 0xb7c713b8; argv_string=salut +Thread 3: top of stack near 0xb7b703b8; argv_string=servus +Joined with thread 1; returned value was HOLA +Joined with thread 2; returned value was SALUT +Joined with thread 3; returned value was SERVUS +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +struct thread_info { /* Used as argument to thread_start() */ + pthread_t thread_id; /* ID returned by pthread_create() */ + int thread_num; /* Application\-defined thread # */ + char *argv_string; /* From command\-line argument */ +}; + +/* Thread start function: display address near top of our stack, + and return upper\-cased copy of argv_string */ + +static void * +thread_start(void *arg) +{ + struct thread_info *tinfo = arg; + char *uargv, *p; + + printf("Thread %d: top of stack near %p; argv_string=%s\\n", + tinfo\->thread_num, &p, tinfo\->argv_string); + + uargv = strdup(tinfo\->argv_string); + if (uargv == NULL) + handle_error("strdup"); + + for (p = uargv; *p != \(aq\\0\(aq; p++) + *p = toupper(*p); + + return uargv; +} + +int +main(int argc, char *argv[]) +{ + int s, tnum, opt, num_threads; + struct thread_info *tinfo; + pthread_attr_t attr; + int stack_size; + void *res; + + /* The "\-s" option specifies a stack size for our threads */ + + stack_size = \-1; + while ((opt = getopt(argc, argv, "s:")) != \-1) { + switch (opt) { + case \(aqs\(aq: + stack_size = strtoul(optarg, NULL, 0); + break; + + default: + fprintf(stderr, "Usage: %s [\-s stack-size] arg...\\n", + argv[0]); + exit(EXIT_FAILURE); + } + } + + num_threads = argc \- optind; + + /* Initialize thread creation attributes */ + + s = pthread_attr_init(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); + + if (stack_size > 0) { + s = pthread_attr_setstacksize(&attr, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } + + /* Allocate memory for pthread_create() arguments */ + + tinfo = calloc(num_threads, sizeof(struct thread_info)); + if (tinfo == NULL) + handle_error("calloc"); + + /* Create one thread for each command\-line argument */ + + for (tnum = 0; tnum < num_threads; tnum++) { + tinfo[tnum].thread_num = tnum + 1; + tinfo[tnum].argv_string = argv[optind + tnum]; + + /* The pthread_create() call stores the thread ID into + corresponding element of tinfo[] */ + + s = pthread_create(&tinfo[tnum].thread_id, &attr, + &thread_start, &tinfo[tnum]); + if (s != 0) + handle_error_en(s, "pthread_create"); + } + + /* Destroy the thread attributes object, since it is no + longer needed */ + + s = pthread_attr_destroy(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); + + /* Now join with each thread, and display its returned value */ + + for (tnum = 0; tnum < num_threads; tnum++) { + s = pthread_join(tinfo[tnum].thread_id, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); + + printf("Joined with thread %d; returned value was %s\\n", + tinfo[tnum].thread_num, (char *) res); + free(res); /* Free memory allocated by thread */ + } + + free(tinfo); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR pthread_attr_init (3), +.BR pthread_cancel (3), +.BR pthread_detach (3), +.BR pthread_equal (3), +.BR pthread_exit (3), +.BR pthread_getattr_np (3), +.BR pthread_join (3), +.BR pthread_self (3), +.BR pthread_setattr_default_np (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_detach.3 b/man3/pthread_detach.3 new file mode 100644 index 0000000..59e1abd --- /dev/null +++ b/man3/pthread_detach.3 @@ -0,0 +1,125 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_DETACH 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_detach \- detach a thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_detach(pthread_t " thread ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +The +.BR pthread_detach () +function marks the thread identified by +.IR thread +as detached. +When a detached thread terminates, +its resources are automatically released back to the system without +the need for another thread to join with the terminated thread. +.PP +Attempting to detach an already detached thread results +in unspecified behavior. +.SH RETURN VALUE +On success, +.BR pthread_detach () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EINVAL +.I thread +is not a joinable thread. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_detach () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +Once a thread has been detached, it can't be joined with +.BR pthread_join (3) +or be made joinable again. +.PP +A new thread can be created in a detached state using +.BR pthread_attr_setdetachstate (3) +to set the detached attribute of the +.I attr +argument of +.BR pthread_create (3). +.PP +The detached attribute merely determines the behavior of the system +when the thread terminates; +it does not prevent the thread from being terminated +if the process terminates using +.BR exit (3) +(or equivalently, if the main thread returns). +.PP +Either +.BR pthread_join (3) +or +.BR pthread_detach () +should be called for each thread that an application creates, +so that system resources for the thread can be released. +(But note that the resources of any threads for which one of these +actions has not been done will be freed when the process terminates.) +.SH EXAMPLE +The following statement detaches the calling thread: +.PP + pthread_detach(pthread_self()); +.SH SEE ALSO +.BR pthread_attr_setdetachstate (3), +.BR pthread_cancel (3), +.BR pthread_create (3), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_equal.3 b/man3/pthread_equal.3 new file mode 100644 index 0000000..3a80a75 --- /dev/null +++ b/man3/pthread_equal.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_EQUAL 3 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_equal \- compare thread IDs +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_equal(pthread_t " t1 ", pthread_t " t2 ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_equal () +function compares two thread identifiers. +.SH RETURN VALUE +If the two thread IDs are equal, +.BR pthread_equal () +returns a nonzero value; otherwise, it returns 0. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_equal () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The +.BR pthread_equal () +function is necessary because thread IDs should be considered opaque: +there is no portable way for applications to directly compare two +.I pthread_t +values. +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_exit.3 b/man3/pthread_exit.3 new file mode 100644 index 0000000..22ce67b --- /dev/null +++ b/man3/pthread_exit.3 @@ -0,0 +1,129 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_EXIT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_exit \- terminate calling thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void pthread_exit(void *" retval ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_exit () +function terminates the calling thread and returns a value via +.I retval +that (if the thread is joinable) +is available to another thread in the same process that calls +.BR pthread_join (3). +.PP +Any clean-up handlers established by +.BR pthread_cleanup_push (3) +that have not yet been popped, +are popped (in the reverse of the order in which they were pushed) +and executed. +If the thread has any thread-specific data, then, +after the clean-up handlers have been executed, +the corresponding destructor functions are called, +in an unspecified order. +.PP +When a thread terminates, +process-shared resources (e.g., mutexes, condition variables, +semaphores, and file descriptors) are not released, +and functions registered using +.BR atexit (3) +are not called. +.PP +After the last thread in a process terminates, +the process terminates as by calling +.BR exit (3) +with an exit status of zero; +thus, process-shared resources +are released and functions registered using +.BR atexit (3) +are called. +.SH RETURN VALUE +This function does not return to the caller. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_exit () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +Performing a return from the start function of any thread other +than the main thread results in an implicit call to +.BR pthread_exit (), +using the function's return value as the thread's exit status. +.PP +To allow other threads to continue execution, +the main thread should terminate by calling +.BR pthread_exit () +rather than +.BR exit (3). +.PP +The value pointed to by +.IR retval +should not be located on the calling thread's stack, +since the contents of that stack are undefined after the thread terminates. +.SH BUGS +Currently, +.\" Linux 2.6.27 +there are limitations in the kernel implementation logic for +.BR wait (2)ing +on a stopped thread group with a dead thread group leader. +This can manifest in problems such as a locked terminal if a stop signal is +sent to a foreground process whose thread group leader has already called +.BR pthread_exit (). +.\" FIXME . review a later kernel to see if this gets fixed +.\" http://thread.gmane.org/gmane.linux.kernel/611611 +.\" http://marc.info/?l=linux-kernel&m=122525468300823&w=2 +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_join (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_getaffinity_np.3 b/man3/pthread_getaffinity_np.3 new file mode 100644 index 0000000..c4cd6af --- /dev/null +++ b/man3/pthread_getaffinity_np.3 @@ -0,0 +1 @@ +.so man3/pthread_setaffinity_np.3 diff --git a/man3/pthread_getattr_default_np.3 b/man3/pthread_getattr_default_np.3 new file mode 100644 index 0000000..f6f2593 --- /dev/null +++ b/man3/pthread_getattr_default_np.3 @@ -0,0 +1,221 @@ +.\" Copyright (c) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_GETATTR_DEFAULT_NP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_getattr_default_np, pthread_setattr_default_np, \- +get or set default thread-creation attributes +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int pthread_getattr_default_np(pthread_attr_t *" attr ); +.BI "int pthread_setattr_default_np(pthread_attr_t *" attr ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_setattr_default_np () +function sets the default attributes used for creation of a new +thread\(emthat is, the attributes that are used when +.BR pthread_create (3) +is called with a second argument that is NULL. +The default attributes are set using the attributes supplied in +.IR *attr , +a previously initialized thread attributes object. +Note the following details about the supplied attributes object: +.IP * 3 +The attribute settings in the object must be valid. +.IP * +The +.IR "stack address" +attribute must not be set in the object. +.IP * +Setting the +.IR "stack size" +attribute to zero means leave the default stack size unchanged. +.PP +The +.BR pthread_getattr_default_np () +function initializes the thread attributes object referred to by +.I attr +so that it contains the default attributes used for thread creation. +.SH ERRORS +.TP +.B EINVAL +.RB ( pthread_setattr_default_np ()) +One of the attribute settings in +.IR attr +is invalid, or the stack address attribute is set in +.IR attr . +.TP +.B ENOMEM +.\" Can happen (but unlikely) while trying to allocate memory for cpuset +.RB ( pthread_setattr_default_np ()) +Insufficient memory. +.SH VERSIONS +These functions are available in glibc since version 2.18. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_getattr_default_np (), +.BR pthread_setattr_default_np () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +These functions are nonstandard GNU extensions; +hence the suffix "_np" (nonportable) in their names. +.SH EXAMPLE +The program below uses +.BR pthread_getattr_default_np () +to fetch the default thread-creation attributes and then displays +various settings from the returned thread attributes object. +When running the program, we see the following output: +.PP +.in +4n +.EX +$ \fB./a.out\fP +Stack size: 8388608 +Guard size: 4096 +Scheduling policy: SCHED_OTHER +Scheduling priority: 0 +Detach state: JOINABLE +Inherit scheduler: INHERIT +.EE +.in +.PP +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include + +#define errExitEN(en, msg) \\ + do { errno = en; perror(msg); \\ + exit(EXIT_FAILURE); } while (0) + +static void +display_pthread_attr(pthread_attr_t *attr) +{ + int s; + size_t stacksize; + size_t guardsize; + int policy; + struct sched_param schedparam; + int detachstate; + int inheritsched; + + s = pthread_attr_getstacksize(attr, &stacksize); + if (s != 0) + errExitEN(s, "pthread_attr_getstacksize"); + printf("Stack size: %zd\\n", stacksize); + + s = pthread_attr_getguardsize(attr, &guardsize); + if (s != 0) + errExitEN(s, "pthread_attr_getguardsize"); + printf("Guard size: %zd\\n", guardsize); + + s = pthread_attr_getschedpolicy(attr, &policy); + if (s != 0) + errExitEN(s, "pthread_attr_getschedpolicy"); + printf("Scheduling policy: %s\\n", + (policy == SCHED_FIFO) ? "SCHED_FIFO" : + (policy == SCHED_RR) ? "SCHED_RR" : + (policy == SCHED_OTHER) ? "SCHED_OTHER" : "[unknown]"); + + s = pthread_attr_getschedparam(attr, &schedparam); + if (s != 0) + errExitEN(s, "pthread_attr_getschedparam"); + printf("Scheduling priority: %d\\n", schedparam.sched_priority); + + s = pthread_attr_getdetachstate(attr, &detachstate); + if (s != 0) + errExitEN(s, "pthread_attr_getdetachstate"); + printf("Detach state: %s\\n", + (detachstate == PTHREAD_CREATE_DETACHED) ? "DETACHED" : + (detachstate == PTHREAD_CREATE_JOINABLE) ? "JOINABLE" : + "???"); + + s = pthread_attr_getinheritsched(attr, &inheritsched); + if (s != 0) + errExitEN(s, "pthread_attr_getinheritsched"); + printf("Inherit scheduler: %s\\n", + (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" : + (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" : + "???"); +} + +int +main(int argc, char *argv[]) +{ + int s; + pthread_attr_t attr; + + s = pthread_getattr_default_np(&attr); + if (s != 0) + errExitEN(s, "pthread_getattr_default_np"); + + display_pthread_attr(&attr); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_getaffinity_np (3), +.BR pthread_attr_getdetachstate (3), +.BR pthread_attr_getguardsize (3), +.BR pthread_attr_getinheritsched (3), +.BR pthread_attr_getschedparam (3), +.BR pthread_attr_getschedpolicy (3), +.BR pthread_attr_getscope (3), +.BR pthread_attr_getstack (3), +.BR pthread_attr_getstackaddr (3), +.BR pthread_attr_getstacksize (3), +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_getattr_np.3 b/man3/pthread_getattr_np.3 new file mode 100644 index 0000000..1f339f9 --- /dev/null +++ b/man3/pthread_getattr_np.3 @@ -0,0 +1,383 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_GETATTR_NP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_getattr_np \- get attributes of created thread +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_getattr_np () +function initializes the thread attributes object referred to by +.I attr +so that it contains actual attribute values describing the running thread +.IR thread . +.PP +The returned attribute values may differ from +the corresponding attribute values passed in the +.I attr +object that was used to create the thread using +.BR pthread_create (3). +In particular, the following attributes may differ: +.IP * 2 +the detach state, since a joinable thread may have detached itself +after creation; +.IP * +the stack size, +which the implementation may align to a suitable boundary. +.IP * +and the guard size, +which the implementation may round upward to a multiple of the page size, +or ignore (i.e., treat as 0), +if the application is allocating its own stack. +.PP +Furthermore, if the stack address attribute was not set +in the thread attributes object used to create the thread, +then the returned thread attributes object will report the actual +stack address that the implementation selected for the thread. +.PP +When the thread attributes object returned by +.BR pthread_getattr_np () +is no longer required, it should be destroyed using +.BR pthread_attr_destroy (3). +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ENOMEM +.\" Can happen (but unlikely) while trying to allocate memory for cpuset +Insufficient memory. +.PP +In addition, if +.I thread +refers to the main thread, then +.BR pthread_getattr_np () +can fail because of errors from various underlying calls: +.BR fopen (3), +if +.IR /proc/self/maps +can't be opened; +and +.BR getrlimit (2), +if the +.BR RLIMIT_STACK +resource limit is not supported. +.SH VERSIONS +This function is available in glibc since version 2.2.3. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_getattr_np () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +This function is a nonstandard GNU extension; +hence the suffix "_np" (nonportable) in the name. +.SH EXAMPLE +The program below demonstrates the use of +.BR pthread_getattr_np (). +The program creates a thread that then uses +.BR pthread_getattr_np () +to retrieve and display its guard size, stack address, +and stack size attributes. +Command-line arguments can be used to set these attributes +to values other than the default when creating the thread. +The shell sessions below demonstrate the use of the program. +.PP +In the first run, on an x86-32 system, +a thread is created using default attributes: +.PP +.in +4n +.EX +.RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" +unlimited +.RB "$" " ./a.out" +Attributes of created thread: + Guard size = 4096 bytes + Stack address = 0x40196000 (EOS = 0x40397000) + Stack size = 0x201000 (2101248) bytes +.EE +.in +.PP +In the following run, we see that if a guard size is specified, +it is rounded up to the next multiple of the system page size +(4096 bytes on x86-32): +.PP +.in +4n +.EX +.RB "$" " ./a.out \-g 4097" +Thread attributes object after initializations: + Guard size = 4097 bytes + Stack address = (nil) + Stack size = 0x0 (0) bytes + +Attributes of created thread: + Guard size = 8192 bytes + Stack address = 0x40196000 (EOS = 0x40397000) + Stack size = 0x201000 (2101248) bytes +.EE +.in +.\".in +4n +.\".nf +.\"$ ./a.out \-s 0x8000 +.\"Thread attributes object after initializations: +.\" Guard size = 4096 bytes +.\" Stack address = 0xffff8000 (EOS = (nil)) +.\" Stack size = 0x8000 (32768) bytes +.\" +.\"Attributes of created thread: +.\" Guard size = 4096 bytes +.\" Stack address = 0x4001e000 (EOS = 0x40026000) +.\" Stack size = 0x8000 (32768) bytes +.\".fi +.\".in +.PP +In the last run, the program manually allocates a stack for the thread. +In this case, the guard size attribute is ignored. +.PP +.in +4n +.EX +.RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a" +Allocated thread stack at 0x804d000 + +Thread attributes object after initializations: + Guard size = 4096 bytes + Stack address = 0x804d000 (EOS = 0x8055000) + Stack size = 0x8000 (32768) bytes + +Attributes of created thread: + Guard size = 0 bytes + Stack address = 0x804d000 (EOS = 0x8055000) + Stack size = 0x8000 (32768) bytes +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void +display_stack_related_attributes(pthread_attr_t *attr, char *prefix) +{ + int s; + size_t stack_size, guard_size; + void *stack_addr; + + s = pthread_attr_getguardsize(attr, &guard_size); + if (s != 0) + handle_error_en(s, "pthread_attr_getguardsize"); + printf("%sGuard size = %d bytes\\n", prefix, guard_size); + + s = pthread_attr_getstack(attr, &stack_addr, &stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_getstack"); + printf("%sStack address = %p", prefix, stack_addr); + if (stack_size > 0) + printf(" (EOS = %p)", (char *) stack_addr + stack_size); + printf("\\n"); + printf("%sStack size = 0x%x (%d) bytes\\n", + prefix, stack_size, stack_size); +} + +static void +display_thread_attributes(pthread_t thread, char *prefix) +{ + int s; + pthread_attr_t attr; + + s = pthread_getattr_np(thread, &attr); + if (s != 0) + handle_error_en(s, "pthread_getattr_np"); + + display_stack_related_attributes(&attr, prefix); + + s = pthread_attr_destroy(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); +} + +static void * /* Start function for thread we create */ +thread_start(void *arg) +{ + printf("Attributes of created thread:\\n"); + display_thread_attributes(pthread_self(), "\\t"); + + exit(EXIT_SUCCESS); /* Terminate all threads */ +} + +static void +usage(char *pname, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); + fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]" + " [\-g guard\-size]\\n", pname); + fprintf(stderr, "\\t\\t\-a means program should allocate stack\\n"); + exit(EXIT_FAILURE); +} + +static pthread_attr_t * /* Get thread attributes from command line */ +get_thread_attributes_from_cl(int argc, char *argv[], + pthread_attr_t *attrp) +{ + int s, opt, allocate_stack; + long stack_size, guard_size; + void *stack_addr; + pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize + a thread attributes object */ + allocate_stack = 0; + stack_size = \-1; + guard_size = \-1; + + while ((opt = getopt(argc, argv, "ag:s:")) != \-1) { + switch (opt) { + case \(aqa\(aq: allocate_stack = 1; break; + case \(aqg\(aq: guard_size = strtoul(optarg, NULL, 0); break; + case \(aqs\(aq: stack_size = strtoul(optarg, NULL, 0); break; + default: usage(argv[0], NULL); + } + } + + if (allocate_stack && stack_size == \-1) + usage(argv[0], "Specifying \-a without \-s makes no sense\\n"); + + if (argc > optind) + usage(argv[0], "Extraneous command\-line arguments\\n"); + + if (stack_size >= 0 || guard_size > 0) { + ret_attrp = attrp; + + s = pthread_attr_init(attrp); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); + } + + if (stack_size >= 0) { + if (!allocate_stack) { + s = pthread_attr_setstacksize(attrp, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } else { + s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE), + stack_size); + if (s != 0) + handle_error_en(s, "posix_memalign"); + printf("Allocated thread stack at %p\\n\\n", stack_addr); + + s = pthread_attr_setstack(attrp, stack_addr, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } + } + + if (guard_size >= 0) { + s = pthread_attr_setguardsize(attrp, guard_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } + + return ret_attrp; +} + +int +main(int argc, char *argv[]) +{ + int s; + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize + a thread attributes object */ + + attrp = get_thread_attributes_from_cl(argc, argv, &attr); + + if (attrp != NULL) { + printf("Thread attributes object after initializations:\\n"); + display_stack_related_attributes(attrp, "\\t"); + printf("\\n"); + } + + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); + } + + pause(); /* Terminates when other thread calls exit() */ +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_getaffinity_np (3), +.BR pthread_attr_getdetachstate (3), +.BR pthread_attr_getguardsize (3), +.BR pthread_attr_getinheritsched (3), +.BR pthread_attr_getschedparam (3), +.BR pthread_attr_getschedpolicy (3), +.BR pthread_attr_getscope (3), +.BR pthread_attr_getstack (3), +.BR pthread_attr_getstackaddr (3), +.BR pthread_attr_getstacksize (3), +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_getconcurrency.3 b/man3/pthread_getconcurrency.3 new file mode 100644 index 0000000..8b2d543 --- /dev/null +++ b/man3/pthread_getconcurrency.3 @@ -0,0 +1 @@ +.so man3/pthread_setconcurrency.3 diff --git a/man3/pthread_getcpuclockid.3 b/man3/pthread_getcpuclockid.3 new file mode 100644 index 0000000..5a1f15f --- /dev/null +++ b/man3/pthread_getcpuclockid.3 @@ -0,0 +1,198 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_GETCPUCLOCKID 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_getcpuclockid \- retrieve ID of a thread's CPU time clock +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clock_id ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_getcpuclockid () +function returns the clock ID for the CPU time clock of the thread +.IR thread . +.\" The clockid is constructed as follows: +.\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE) +.\" where CLOCK_IDFIELD_SIZE is 3. +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ENOENT +.\" CLOCK_THREAD_CPUTIME_ID not defined +Per-thread CPU time clocks are not supported by the system. +.\" +.\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would +.\" be possible if kernel thread IDs took more than 29 bits (which +.\" they currently cannot). +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH VERSIONS +This function is available in glibc since version 2.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_getcpuclockid () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +When +.I thread +refers to the calling thread, +this function returns an identifier that refers to the same clock +manipulated by +.BR clock_gettime (2) +and +.BR clock_settime (2) +when given the clock ID +.BR CLOCK_THREAD_CPUTIME_ID . +.SH EXAMPLE +The program below creates a thread and then uses +.BR clock_gettime (2) +to retrieve the total process CPU time, +and the per-thread CPU time consumed by the two threads. +The following shell session shows an example run: +.PP +.in +4n +.EX +$ \fB./a.out\fP +Main thread sleeping +Subthread starting infinite loop +Main thread consuming some CPU time... +Process total CPU time: 1.368 +Main thread CPU time: 0.376 +Subthread CPU time: 0.992 +.EE +.in +.SS Program source +\& +.EX +/* Link with "\-lrt" */ + +#include +#include +#include +#include +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void * +thread_start(void *arg) +{ + printf("Subthread starting infinite loop\\n"); + for (;;) + continue; +} + +static void +pclock(char *msg, clockid_t cid) +{ + struct timespec ts; + + printf("%s", msg); + if (clock_gettime(cid, &ts) == \-1) + handle_error("clock_gettime"); + printf("%4ld.%03ld\\n", ts.tv_sec, ts.tv_nsec / 1000000); +} + +int +main(int argc, char *argv[]) +{ + pthread_t thread; + clockid_t cid; + int j, s; + + s = pthread_create(&thread, NULL, thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + printf("Main thread sleeping\\n"); + sleep(1); + + printf("Main thread consuming some CPU time...\\n"); + for (j = 0; j < 2000000; j++) + getppid(); + + pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID); + + s = pthread_getcpuclockid(pthread_self(), &cid); + if (s != 0) + handle_error_en(s, "pthread_getcpuclockid"); + pclock("Main thread CPU time: ", cid); + + /* The preceding 4 lines of code could have been replaced by: + pclock("Main thread CPU time: ", CLOCK_THREAD_CPUTIME_ID); */ + + s = pthread_getcpuclockid(thread, &cid); + if (s != 0) + handle_error_en(s, "pthread_getcpuclockid"); + pclock("Subthread CPU time: 1 ", cid); + + exit(EXIT_SUCCESS); /* Terminates both threads */ +} +.EE +.SH SEE ALSO +.BR clock_gettime (2), +.BR clock_settime (2), +.BR timer_create (2), +.BR clock_getcpuclockid (3), +.BR pthread_self (3), +.BR pthreads (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_getname_np.3 b/man3/pthread_getname_np.3 new file mode 100644 index 0000000..a385c6e --- /dev/null +++ b/man3/pthread_getname_np.3 @@ -0,0 +1 @@ +.so man3/pthread_setname_np.3 diff --git a/man3/pthread_getschedparam.3 b/man3/pthread_getschedparam.3 new file mode 100644 index 0000000..67299c5 --- /dev/null +++ b/man3/pthread_getschedparam.3 @@ -0,0 +1 @@ +.so man3/pthread_setschedparam.3 diff --git a/man3/pthread_join.3 b/man3/pthread_join.3 new file mode 100644 index 0000000..481a6d4 --- /dev/null +++ b/man3/pthread_join.3 @@ -0,0 +1,158 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_JOIN 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_join \- join with a terminated thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_join(pthread_t " thread ", void **" retval ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +The +.BR pthread_join () +function waits for the thread specified by +.IR thread +to terminate. +If that thread has already terminated, then +.BR pthread_join () +returns immediately. +The thread specified by +.I thread +must be joinable. +.PP +If +.I retval +is not NULL, then +.BR pthread_join () +copies the exit status of the target thread +(i.e., the value that the target thread supplied to +.BR pthread_exit (3)) +into the location pointed to by +.IR retval . +If the target thread was canceled, then +.B PTHREAD_CANCELED +is placed in the location pointed to by +.IR retval . +.PP +If multiple threads simultaneously try to join with the same thread, +the results are undefined. +If the thread calling +.BR pthread_join () +is canceled, then the target thread will remain joinable +(i.e., it will not be detached). +.SH RETURN VALUE +On success, +.BR pthread_join () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EDEADLK +A deadlock was detected +.\" The following verified by testing on glibc 2.8/NPTL: +(e.g., two threads tried to join with each other); +or +.\" The following verified by testing on glibc 2.8/NPTL: +.I thread +specifies the calling thread. +.TP +.B EINVAL +.I thread +is not a joinable thread. +.TP +.B EINVAL +Another thread is already waiting to join with this thread. +.\" POSIX.1-2001 does not specify this error case. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_join () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +After a successful call to +.BR pthread_join (), +the caller is guaranteed that the target thread has terminated. +The caller may then choose to do any clean-up that is required +after termination of the thread (e.g., freeing memory or other +resources that were allocated to the target thread). +.PP +Joining with a thread that has previously been joined results in +undefined behavior. +.PP +Failure to join with a thread that is joinable +(i.e., one that is not detached), +produces a "zombie thread". +Avoid doing this, +since each zombie thread consumes some system resources, +and when enough zombie threads have accumulated, +it will no longer be possible to create new threads (or processes). +.PP +There is no pthreads analog of +.IR "waitpid(-1,\ &status,\ 0)" , +that is, "join with any terminated thread". +If you believe you need this functionality, +you probably need to rethink your application design. +.PP +All of the threads in a process are peers: +any thread can join with any other thread in the process. +.SH EXAMPLE +See +.BR pthread_create (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_create (3), +.BR pthread_detach (3), +.BR pthread_exit (3), +.BR pthread_tryjoin_np (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_kill.3 b/man3/pthread_kill.3 new file mode 100644 index 0000000..a119944 --- /dev/null +++ b/man3/pthread_kill.3 @@ -0,0 +1,133 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_KILL 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_kill \- send a signal to a thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_kill(pthread_t " thread ", int " sig ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR pthread_kill (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 199506L || _XOPEN_SOURCE\ >=\ 500 +.RE +.ad b +.SH DESCRIPTION +The +.BR pthread_kill () +function sends the signal +.I sig +to +.IR thread , +a thread in the same process as the caller. +The signal is asynchronously directed to +.IR thread . +.PP +If +.I sig +is 0, then no signal is sent, but error checking is still performed. +.SH RETURN VALUE +On success, +.BR pthread_kill () +returns 0; +on error, it returns an error number, and no signal is sent. +.SH ERRORS +.TP +.B EINVAL +An invalid signal was specified. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_kill () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +Signal dispositions are process-wide: +if a signal handler is installed, +the handler will be invoked in the thread +.IR thread , +but if the disposition of the signal is "stop", "continue", or "terminate", +this action will affect the whole process. +.PP +The glibc implementation of +.BR pthread_kill () +gives an error +.RB ( EINVAL ) +on attempts to send either of the real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.PP +POSIX.1-2008 recommends that if an implementation detects the use +of a thread ID after the end of its lifetime, +.BR pthread_kill () +should return the error +.BR ESRCH . +The glibc implementation returns this error in the cases where +an invalid thread ID can be detected. +But note also that POSIX says that an attempt to use a thread ID whose +lifetime has ended produces undefined behavior, +and an attempt to use an invalid thread ID in a call to +.BR pthread_kill () +can, for example, cause a segmentation fault. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR sigpending (2), +.BR pthread_self (3), +.BR pthread_sigmask (3), +.BR raise (3), +.BR pthreads (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_kill_other_threads_np.3 b/man3/pthread_kill_other_threads_np.3 new file mode 100644 index 0000000..f11707b --- /dev/null +++ b/man3/pthread_kill_other_threads_np.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_KILL_OTHER_THREADS_NP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_kill_other_threads_np \- terminate all other threads in process +.SH SYNOPSIS +.nf +.B #include +.PP +.B void pthread_kill_other_threads_np(void); +.fi +.SH DESCRIPTION +.BR pthread_kill_other_threads_np () +has an effect only in the LinuxThreads threading implementation. +On that implementation, +calling this function causes the immediate termination of +all threads in the application, +except the calling thread. +The cancellation state and cancellation type of the +to-be-terminated threads are ignored, +and the cleanup handlers are not called in those threads. +.\" .SH VERSIONS +.\" Available since glibc 2.0 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_kill_other_threads_np () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is a nonstandard GNU extension; +hence the suffix "_np" (nonportable) in the name. +.SH NOTES +.BR pthread_kill_other_threads_np () +is intended to be called just before a thread calls +.BR execve (2) +or a similar function. +This function is designed to address a limitation in the obsolete +LinuxThreads implementation whereby the other threads of an application +are not automatically terminated (as POSIX.1-2001 requires) during +.BR execve (2). +.PP +In the NPTL threading implementation, +.BR pthread_kill_other_threads_np () +exists, but does nothing. +(Nothing needs to be done, +because the implementation does the right thing during an +.BR execve (2).) +.SH SEE ALSO +.BR execve (2), +.BR pthread_cancel (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_mutex_consistent.3 b/man3/pthread_mutex_consistent.3 new file mode 100644 index 0000000..cd13dbd --- /dev/null +++ b/man3/pthread_mutex_consistent.3 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2017, Yubin Ruan +.\" and Copyright (c) 2017, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_MUTEX_CONSISTENT 3 2017-08-20 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_mutex_consistent \- make a robust mutex consistent +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_mutex_consistent(pthread_mutex_t *" mutex ");" +.fi +.PP +Compile and link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR pthread_mutex_consistent (): +.br +.RS 4 +.ad l +_POSIX_C_SOURCE >= 200809L +.RE +.ad +.SH DESCRIPTION +This function makes a robust mutex consistent if it is in an inconsistent +state. +A mutex can be left in an inconsistent state if its owner terminates +while holding the mutex, in which case the next owner who acquires the +mutex will succeed and be notified by a return value of +.BR EOWNERDEAD +from a call to +.BR pthread_mutex_lock (). +.SH RETURN VALUE +On success, +.IR pthread_mutex_consistent() +returns 0. +Otherwise, +it returns a positive error number to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +The mutex is either not robust or is not in an inconsistent state. +.SH VERSIONS +.BR pthread_mutex_consistent () +was added to glibc in version 2.12. +.SH CONFORMING TO +POSIX.1-2008. +.SH NOTES +.BR pthread_mutex_consistent () +simply informs the implementation that the state (shared data) +guarded by the mutex has been restored to a consistent state and that +normal operations can now be performed with the mutex. +It is the application's responsibility to ensure that the +shared data has been restored to a consistent state before calling +.BR pthread_mutex_consistent (). +.PP +Before the addition of +.BR pthread_mutex_consistent () +to POSIX, +glibc defined the following equivalent nonstandard function if +.BR _GNU_SOURCE +was defined: +.PP +.nf +.BI "int pthread_mutex_consistent(const pthread_mutex_t *" mutex ); +.fi +.PP +This GNU-specific API, which first appeared in glibc 2.4, +is nowadays obsolete and should not be used in new programs. +.SH EXAMPLE +See +.BR pthread_mutexattr_setrobust (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutexattr_init (3), +.BR pthread_mutex_lock (3), +.BR pthread_mutexattr_setrobust (3), +.BR pthread_mutexattr_getrobust (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_mutex_consistent_np.3 b/man3/pthread_mutex_consistent_np.3 new file mode 100644 index 0000000..a45bea4 --- /dev/null +++ b/man3/pthread_mutex_consistent_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_consistent.3 diff --git a/man3/pthread_mutexattr_destroy.3 b/man3/pthread_mutexattr_destroy.3 new file mode 100644 index 0000000..eadaa9b --- /dev/null +++ b/man3/pthread_mutexattr_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_init.3 diff --git a/man3/pthread_mutexattr_getpshared.3 b/man3/pthread_mutexattr_getpshared.3 new file mode 100644 index 0000000..0bdf815 --- /dev/null +++ b/man3/pthread_mutexattr_getpshared.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) 2017, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_MUTEXATTR_GETPSHARED 3 2017-09-13 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_mutexattr_getpshared, pthread_mutexattr_setpshared \- get/set +process-shared mutex attribute +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_mutexattr_getpshared(const pthread_mutexattr_t *" attr , +.BI " int *" pshared ); +.BI "int pthread_mutexattr_setpshared(pthread_mutexattr_t *" attr , +.BI " int " pshared ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +These functions get and set the process-shared attribute +in a mutex attributes object. +This attribute must be appropriately set to ensure correct, +efficient operation of a mutex created using this attributes object. +.PP +The process-shared attribute can have one of the following values: +.TP +.B PTHREAD_PROCESS_PRIVATE +Mutexes created with this attributes object are to be shared +only among threads in the same process that initialized the mutex. +This is the default value for the process-shared mutex attribute. +.TP +.B PTHREAD_PROCESS_SHARED +Mutexes created with this attributes object can be shared between +any threads that have access to the memory containing the object, +including threads in different processes. +.PP +.BR pthread_mutexattr_getpshared () +places the value of the process-shared attribute of +the mutex attributes object referred to by +.IR attr +in the location pointed to by +.IR pshared . +.PP +.BR pthread_mutexattr_setpshared () +sets the value of the process-shared attribute of +the mutex attributes object referred to by +.IR attr +to the value specified in +.BR pshared . +.PP +If +.I attr +does not refer to an initialized mutex attributes object, +the behavior is undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.SH ERRORS +.BR pthread_mutexattr_setpshared () +can fail with the following errors: +.TP +.B EINVAL +The value specified in +.I pshared +is invalid. +.TP +.B ENOTSUP +.I pshared is +.BR PTHREAD_PROCESS_SHARED +but the implementation does not support process-shared mutexes. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutexattr_init (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_mutexattr_getrobust.3 b/man3/pthread_mutexattr_getrobust.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man3/pthread_mutexattr_getrobust.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man3/pthread_mutexattr_getrobust_np.3 b/man3/pthread_mutexattr_getrobust_np.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man3/pthread_mutexattr_getrobust_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man3/pthread_mutexattr_init.3 b/man3/pthread_mutexattr_init.3 new file mode 100644 index 0000000..5959cc6 --- /dev/null +++ b/man3/pthread_mutexattr_init.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 2017, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_MUTEXATTR_INIT 3 2017-08-20 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_mutexattr_init, pthread_mutexattr_destroy \- initialize and +destroy a mutex attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_mutexattr_init(pthread_mutexattr_t *" attr ");" +.BI "int pthread_mutexattr_destroy(pthread_mutexattr_t *" attr ");" +.fi +.PP +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +The +.BR pthread_mutexattr_init () +function initializes the mutex attributes object pointed to by +.I attr +with default values for all attributes defined by the implementation. +.PP +The results of initializing an already initialized mutex attributes +object are undefined. +.PP +The +.BR pthread_mutexattr_destroy () +function destroys a mutex attribute object (making it uninitialized). +Once a mutex attributes object has been destroyed, it can be reinitialized with +.BR pthread_mutexattr_init (). +.PP +The results of destroying an uninitialized mutex attributes +object are undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +Subsequent changes to a mutex attributes object do not affect mutex that +have already been initialized using that object. +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutex_init (3), +.BR pthread_mutexattr_getrobust (3), +.BR pthread_mutexattr_getpshared (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_mutexattr_setpshared.3 b/man3/pthread_mutexattr_setpshared.3 new file mode 100644 index 0000000..07899fd --- /dev/null +++ b/man3/pthread_mutexattr_setpshared.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_getpshared.3 diff --git a/man3/pthread_mutexattr_setrobust.3 b/man3/pthread_mutexattr_setrobust.3 new file mode 100644 index 0000000..748b53f --- /dev/null +++ b/man3/pthread_mutexattr_setrobust.3 @@ -0,0 +1,294 @@ +.\" Copyright (c) 2017, Yubin Ruan +.\" and Copyright (c) 2017, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_MUTEXATTR_SETROBUST 3 2017-08-20 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_mutexattr_getrobust, pthread_mutexattr_setrobust +\- get and set the robustness attribute of a mutex attributes object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr , +.BI " int *" robustness ");" +.BI "int pthread_mutexattr_setrobust(const pthread_mutexattr_t *" attr , +.BI " int " robustness ");" +.fi +.PP +Compile and link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR pthread_mutexattr_getrobust (), +.BR pthread_mutexattr_setrobust (): +.br +.RS 4 +.ad l +_POSIX_C_SOURCE >= 200809L +.\" FIXME . +.\" But see https://sourceware.org/bugzilla/show_bug.cgi?id=22125 +.RE +.ad +.SH DESCRIPTION +The +.BR pthread_mutexattr_getrobust () +function places the value of the robustness attribute of +the mutex attributes object referred to by +.I attr +in +.IR *robustness . +The +.BR pthread_mutexattr_setrobust () +function sets the value of the robustness attribute of +the mutex attributes object referred to by +.I attr +to the value specified in +.IR *robustness . +.PP +The robustness attribute specifies the behavior of the mutex when +the owning thread dies without unlocking the mutex. +The following values are valid for +.IR robustness : +.TP +.BR PTHREAD_MUTEX_STALLED +This is the default value for a mutex attributes object. +If a mutex is initialized with the +.BR PTHREAD_MUTEX_STALLED +attribute and its owner dies without unlocking it, +the mutex remains locked afterwards and any future attempts to call +.BR pthread_mutex_lock (3) +on the mutex will block indefinitely. +.TP +.B PTHREAD_MUTEX_ROBUST +If a mutex is initialized with the +.BR PTHREAD_MUTEX_ROBUST +attribute and its owner dies without unlocking it, +any future attempts to call +.BR pthread_mutex_lock (3) +on this mutex will succeed and return +.B EOWNERDEAD +to indicate that the original owner no longer exists and the mutex is in +an inconsistent state. +Usually after +.B EOWNERDEAD +is returned, the next owner should call +.BR pthread_mutex_consistent (3) +on the acquired mutex to make it consistent again before using it any further. +.IP +If the next owner unlocks the mutex using +.BR pthread_mutex_unlock (3) +before making it consistent, the mutex will be permanently unusable and any +subsequent attempts to lock it using +.BR pthread_mutex_lock (3) +will fail with the error +.BR ENOTRECOVERABLE . +The only permitted operation on such a mutex is +.BR pthread_mutex_destroy (3). +.IP +If the next owner terminates before calling +.BR pthread_mutex_consistent (3), +further +.BR pthread_mutex_lock (3) +operations on this mutex will still return +.BR EOWNERDEAD . +.PP +Note that the +.IR attr +argument of +.BR pthread_mutexattr_getrobust () +and +.BR pthread_mutexattr_setrobust () +should refer to a mutex attributes object that was initialized by +.BR pthread_mutexattr_init (3), +otherwise the behavior is undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.PP +In the glibc implementation, +.BR pthread_mutexattr_getrobust () +always return zero. +.SH ERRORS +.TP +.B EINVAL +A value other than +.B PTHREAD_MUTEX_STALLED +or +.B PTHREAD_MUTEX_ROBUST +was passed to +.BR pthread_mutexattr_setrobust (). +.SH VERSIONS +.BR pthread_mutexattr_getrobust () +and +.BR pthread_mutexattr_setrobust () +were added to glibc in version 2.12. +.SH CONFORMING TO +POSIX.1-2008. +.SH NOTES +In the Linux implementation, +when using process-shared robust mutexes, a waiting thread also receives the +.B EOWNERDEAD +notification if the owner of a robust mutex performs an +.BR execve (2) +without first unlocking the mutex. +POSIX.1 does not specify this detail, +but the same behavior also occurs in at least some +.\" E.g., Solaris, according to its manual page +other implementations. +.PP +Before the addition of +.BR pthread_mutexattr_getrobust () +and +.BR pthread_mutexattr_setrobust () +to POSIX, +glibc defined the following equivalent nonstandard functions if +.BR _GNU_SOURCE +was defined: +.PP +.nf +.BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr , +.BI " int *" robustness ");" +.BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr , +.BI " int " robustness ");" +.fi +.PP +Correspondingly, the constants +.B PTHREAD_MUTEX_STALLED_NP +and +.B PTHREAD_MUTEX_ROBUST_NP +were also defined. +.PP +These GNU-specific APIs, which first appeared in glibc 2.4, +are nowadays obsolete and should not be used in new programs. +.SH EXAMPLE +.PP +The program below demonstrates the use of the robustness attribute of a +mutex attributes object. +In this program, a thread holding the mutex +dies prematurely without unlocking the mutex. +The main thread subsequently acquires the mutex +successfully and gets the error +.BR EOWNERDEAD , +after which it makes the mutex consistent. +.PP +The following shell session shows what we see when running this program: +.PP +.in +4n +.EX +$ \fB./a.out\fP +[original owner] Setting lock... +[original owner] Locked. Now exiting without unlocking. +[main thread] Attempting to lock the robust mutex. +[main thread] pthread_mutex_lock() returned EOWNERDEAD +[main thread] Now make the mutex consistent +[main thread] Mutex is now consistent; unlocking +.EE +.in +.SS Program source +.EX +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static pthread_mutex_t mtx; + +static void * +original_owner_thread(void *ptr) +{ + printf("[original owner] Setting lock...\\n"); + pthread_mutex_lock(&mtx); + printf("[original owner] Locked. Now exiting without unlocking.\\n"); + pthread_exit(NULL); +} + +int +main(int argc, char *argv[]) +{ + pthread_t thr; + pthread_mutexattr_t attr; + int s; + + pthread_mutexattr_init(&attr); + /* initialize the attributes object */ + pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST); + /* set robustness */ + + pthread_mutex_init(&mtx, &attr); /* initialize the mutex */ + + pthread_create(&thr, NULL, original_owner_thread, NULL); + + sleep(2); + + /* "original_owner_thread" should have exited by now */ + + printf("[main thread] Attempting to lock the robust mutex.\\n"); + s = pthread_mutex_lock(&mtx); + if (s == EOWNERDEAD) { + printf("[main thread] pthread_mutex_lock() returned EOWNERDEAD\\n"); + printf("[main thread] Now make the mutex consistent\\n"); + s = pthread_mutex_consistent(&mtx); + if (s != 0) + handle_error_en(s, "pthread_mutex_consistent"); + printf("[main thread] Mutex is now consistent; unlocking\\n"); + s = pthread_mutex_unlock(&mtx); + if (s != 0) + handle_error_en(s, "pthread_mutex_unlock"); + + exit(EXIT_SUCCESS); + } else if (s == 0) { + printf("[main thread] pthread_mutex_lock() unexpectedly succeeded\\n"); + exit(EXIT_FAILURE); + } else { + printf("[main thread] pthread_mutex_lock() unexpectedly failed\\n"); + handle_error_en(s, "pthread_mutex_lock"); + } +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR get_robust_list (2), +.BR set_robust_list (2), +.BR pthread_mutex_init (3), +.BR pthread_mutex_consistent (3), +.BR pthread_mutex_lock (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_mutexattr_setrobust_np.3 b/man3/pthread_mutexattr_setrobust_np.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man3/pthread_mutexattr_setrobust_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man3/pthread_rwlockattr_getkind_np.3 b/man3/pthread_rwlockattr_getkind_np.3 new file mode 100644 index 0000000..6f3f740 --- /dev/null +++ b/man3/pthread_rwlockattr_getkind_np.3 @@ -0,0 +1 @@ +.so man3/pthread_rwlockattr_setkind_np.3 diff --git a/man3/pthread_rwlockattr_setkind_np.3 b/man3/pthread_rwlockattr_setkind_np.3 new file mode 100644 index 0000000..b5bae67 --- /dev/null +++ b/man3/pthread_rwlockattr_setkind_np.3 @@ -0,0 +1,140 @@ +.\"Copyright (c) 2010 Novell Inc., written by Robert Schweikert +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_RWLOCKATTR_SETKIND_NP 3 2018-02-02 "Linux Programmer's Manual" +.SH NAME +pthread_rwlockattr_setkind_np, pthread_rwlockattr_getkind_np \- set/get +the read-write lock kind of the thread read-write lock attribute object +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_rwlockattr_setkind_np(pthread_rwlockattr_t *" attr , +.BI " int " pref ); +.BI "int pthread_rwlockattr_getkind_np(const pthread_rwlockattr_t *" attr , +.BI " int *" pref ); +.PP +Compile and link with \fI\-pthread\fP. +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR pthread_rwlockattr_setkind_np (), +.BR pthread_rwlockattr_getkind_np (): +.br +.RS 4 +.ad l +_XOPEN_SOURCE\ >=\ 500 || _POSIX_C_SOURCE >= 200809L +.RE +.ad +.SH DESCRIPTION +The +.BR pthread_rwlockattr_setkind_np () +function sets the "lock kind" attribute of the +read-write lock attribute object referred to by +.I attr +to the value specified in +.IR pref . +The argument +.I pref +may be set to one of the following: +.TP +.B PTHREAD_RWLOCK_PREFER_READER_NP +This is the default. +A thread may hold multiple read locks; that is, read locks are recursive. +According to The Single Unix Specification, the behavior is unspecified when a +reader tries to place a lock, and there is no write lock but writers are +waiting. +Giving preference to the reader, as is set by +.BR PTHREAD_RWLOCK_PREFER_READER_NP , +implies that the reader will receive the requested lock, even if +a writer is waiting. +As long as there are readers, the writer will be +starved. +.TP +.B PTHREAD_RWLOCK_PREFER_WRITER_NP +This is intended as the write lock analog of +.BR PTHREAD_RWLOCK_PREFER_READER_NP . +But see BUGS. +.TP +.B PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP +Setting the lock kind to this +avoids writer starvation as long as any read locking is not done in a +recursive fashion. +.PP +The +.BR pthread_rwlockattr_getkind_np () +function returns the value of the lock kind attribute of the +read-write lock attribute object referred to by +.IR attr +in the pointer +.IR pref . +.SH RETURN VALUE +On success, these functions return 0. +Given valid pointer arguments, +.BR pthread_rwlockattr_getkind_np () +always succeeds. +On error, +.BR pthread_rwlockattr_setkind_np () +returns a nonzero error number. +.SH ERRORS +.TP +.BR EINVAL +.I pref +specifies an unsupported value. +.SH VERSIONS +The +.BR pthread_rwlockattr_getkind_np () +and +.BR pthread_rwlockattr_setkind_np () +functions first appeared in glibc 2.1. +.SH CONFORMING TO +These functions are non-standard GNU extensions; +hence the suffix "_np" (non-portable) in the names. +.SH BUGS +Setting the value read-write lock kind to +.BR PTHREAD_RWLOCK_PREFER_WRITER_NP +results in the same behavior as setting the value to +.BR PTHREAD_RWLOCK_PREFER_READER_NP . +As long as a reader thread holds the lock, the thread holding a +write lock will be starved. +Setting the lock kind to +.BR PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP +allows writers to run, but, as the name implies a writer +may not lock recursively. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7057 +.SH SEE ALSO +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_self.3 b/man3/pthread_self.3 new file mode 100644 index 0000000..a11e27c --- /dev/null +++ b/man3/pthread_self.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SELF 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_self \- obtain ID of the calling thread +.SH SYNOPSIS +.nf +.B #include +.PP +.B pthread_t pthread_self(void); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_self () +function returns the ID of the calling thread. +This is the same value that is returned in +.IR *thread +in the +.BR pthread_create (3) +call that created this thread. +.SH RETURN VALUE +This function always succeeds, returning the calling thread's ID. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_self () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +POSIX.1 allows an implementation wide freedom in choosing +the type used to represent a thread ID; +for example, representation using either an arithmetic type or +a structure is permitted. +Therefore, variables of type +.I pthread_t +can't portably be compared using the C equality operator (\fB==\fP); +use +.BR pthread_equal (3) +instead. +.PP +Thread identifiers should be considered opaque: +any attempt to use a thread ID other than in pthreads calls +is nonportable and can lead to unspecified results. +.PP +Thread IDs are guaranteed to be unique only within a process. +A thread ID may be reused after a terminated thread has been joined, +or a detached thread has terminated. +.PP +The thread ID returned by +.BR pthread_self () +is not the same thing as the kernel thread ID returned by a call to +.BR gettid (2). +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_equal (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_setaffinity_np.3 b/man3/pthread_setaffinity_np.3 new file mode 100644 index 0000000..70acb98 --- /dev/null +++ b/man3/pthread_setaffinity_np.3 @@ -0,0 +1,232 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SETAFFINITY_NP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_setaffinity_np, pthread_getaffinity_np \- set/get +CPU affinity of a thread +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize , +.BI " const cpu_set_t *" cpuset ); +.BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize , +.BI " cpu_set_t *" cpuset ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_setaffinity_np () +function +sets the CPU affinity mask of the thread +.I thread +to the CPU set pointed to by +.IR cpuset . +If the call is successful, +and the thread is not currently running on one of the CPUs in +.IR cpuset , +then it is migrated to one of those CPUs. +.PP +The +.BR pthread_getaffinity_np () +function returns the CPU affinity mask of the thread +.I thread +in the buffer pointed to by +.IR cpuset . +.PP +For more details on CPU affinity masks, see +.BR sched_setaffinity (2). +For a description of a set of macros +that can be used to manipulate and inspect CPU sets, see +.BR CPU_SET (3). +.PP +The argument +.I cpusetsize +is the length (in bytes) of the buffer pointed to by +.IR cpuset . +Typically, this argument would be specified as +.IR sizeof(cpu_set_t) . +(It may be some other value, if using the macros described in +.BR CPU_SET (3) +for dynamically allocating a CPU set.) +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.TP +.B EFAULT +A supplied memory address was invalid. +.TP +.B EINVAL +.RB ( pthread_setaffinity_np ()) +The affinity bit mask +.I mask +contains no processors that are currently physically on the system +and permitted to the thread according to any restrictions that +may be imposed by the "cpuset" mechanism described in +.BR cpuset (7). +.TP +.BR EINVAL +.RB ( pthread_setaffinity_np ()) +.I cpuset +specified a CPU that was outside the set supported by the kernel. +(The kernel configuration option +.BR CONFIG_NR_CPUS +defines the range of the set supported by the kernel data type +.\" cpumask_t +used to represent CPU sets.) +.\" The raw sched_getaffinity() system call returns the size (in bytes) +.\" of the cpumask_t type. +.TP +.B EINVAL +.RB ( pthread_getaffinity_np ()) +.I cpusetsize +is smaller than the size of the affinity mask used by the kernel. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH VERSIONS +These functions are provided by glibc since version 2.3.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_setaffinity_np (), +.BR pthread_getaffinity_np () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are nonstandard GNU extensions; +hence the suffix "_np" (nonportable) in the names. +.SH NOTES +After a call to +.BR pthread_setaffinity_np (), +the set of CPUs on which the thread will actually run is +the intersection of the set specified in the +.I cpuset +argument and the set of CPUs actually present on the system. +The system may further restrict the set of CPUs on which the thread +runs if the "cpuset" mechanism described in +.BR cpuset (7) +is being used. +These restrictions on the actual set of CPUs on which the thread +will run are silently imposed by the kernel. +.PP +These functions are implemented on top of the +.BR sched_setaffinity (2) +and +.BR sched_getaffinity (2) +system calls. +.PP +In glibc 2.3.3 only, +versions of these functions were provided that did not have a +.I cpusetsize +argument. +Instead the CPU set size given to the underlying system calls was always +.IR sizeof(cpu_set_t) . +.PP +A new thread created by +.BR pthread_create (3) +inherits a copy of its creator's CPU affinity mask. +.SH EXAMPLE +In the following program, the main thread uses +.BR pthread_setaffinity_np () +to set its CPU affinity mask to include CPUs 0 to 7 +(which may not all be available on the system), +and then calls +.BR pthread_getaffinity_np () +to check the resulting CPU affinity mask of the thread. +.PP +.EX +#define _GNU_SOURCE +#include +#include +#include +#include + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +int +main(int argc, char *argv[]) +{ + int s, j; + cpu_set_t cpuset; + pthread_t thread; + + thread = pthread_self(); + + /* Set affinity mask to include CPUs 0 to 7 */ + + CPU_ZERO(&cpuset); + for (j = 0; j < 8; j++) + CPU_SET(j, &cpuset); + + s = pthread_setaffinity_np(thread, sizeof(cpu_set_t), &cpuset); + if (s != 0) + handle_error_en(s, "pthread_setaffinity_np"); + + /* Check the actual affinity mask assigned to the thread */ + + s = pthread_getaffinity_np(thread, sizeof(cpu_set_t), &cpuset); + if (s != 0) + handle_error_en(s, "pthread_getaffinity_np"); + + printf("Set returned by pthread_getaffinity_np() contained:\\n"); + for (j = 0; j < CPU_SETSIZE; j++) + if (CPU_ISSET(j, &cpuset)) + printf(" CPU %d\\n", j); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR CPU_SET (3), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_self (3), +.BR sched_getcpu (3), +.BR cpuset (7), +.BR pthreads (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_setattr_default_np.3 b/man3/pthread_setattr_default_np.3 new file mode 100644 index 0000000..1ea2ab6 --- /dev/null +++ b/man3/pthread_setattr_default_np.3 @@ -0,0 +1 @@ +.so man3/pthread_getattr_default_np.3 diff --git a/man3/pthread_setcancelstate.3 b/man3/pthread_setcancelstate.3 new file mode 100644 index 0000000..a4606f3 --- /dev/null +++ b/man3/pthread_setcancelstate.3 @@ -0,0 +1,216 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SETCANCELSTATE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_setcancelstate, pthread_setcanceltype \- +set cancelability state and type +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_setcancelstate(int " state ", int *" oldstate ); +.BI "int pthread_setcanceltype(int " type ", int *" oldtype ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_setcancelstate () +sets the cancelability state of the calling thread to the value +given in +.IR state . +The previous cancelability state of the thread is returned +in the buffer pointed to by +.IR oldstate . +The +.I state +argument must have one of the following values: +.TP +.B PTHREAD_CANCEL_ENABLE +The thread is cancelable. +This is the default cancelability state in all new threads, +including the initial thread. +The thread's cancelability type determines when a cancelable thread +will respond to a cancellation request. +.TP +.B PTHREAD_CANCEL_DISABLE +The thread is not cancelable. +If a cancellation request is received, +it is blocked until cancelability is enabled. +.PP +The +.BR pthread_setcanceltype () +sets the cancelability type of the calling thread to the value +given in +.IR type . +The previous cancelability type of the thread is returned +in the buffer pointed to by +.IR oldtype . +The +.I type +argument must have one of the following values: +.TP +.B PTHREAD_CANCEL_DEFERRED +A cancellation request is deferred until the thread next calls +a function that is a cancellation point (see +.BR pthreads (7)). +This is the default cancelability type in all new threads, +including the initial thread. +.TP +.B PTHREAD_CANCEL_ASYNCHRONOUS +The thread can be canceled at any time. +(Typically, +it will be canceled immediately upon receiving a cancellation request, +but the system doesn't guarantee this.) +.PP +The set-and-get operation performed by each of these functions +is atomic with respect to other threads in the process +calling the same function. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +The +.BR pthread_setcancelstate () +can fail with the following error: +.TP +.B EINVAL +Invalid value for +.IR state . +.PP +The +.BR pthread_setcanceltype () +can fail with the following error: +.TP +.B EINVAL +Invalid value for +.IR type . +.\" .SH VERSIONS +.\" Available since glibc 2.0 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lb lb lb +lw25 l l. +Interface Attribute Value +T{ +.BR pthread_setcancelstate (), +.BR pthread_setcanceltype () +T} Thread safety T{ +MT-Safe +T} +T{ +.BR pthread_setcancelstate (), +.BR pthread_setcanceltype () +T} Async-cancel-safety T{ +AC-Safe +T} +.TE +.ad +.hy +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +For details of what happens when a thread is canceled, see +.BR pthread_cancel (3). +.PP +Briefly disabling cancelability is useful +if a thread performs some critical action +that must not be interrupted by a cancellation request. +Beware of disabling cancelability for long periods, +or around operations that may block for long periods, +since that will render the thread unresponsive to cancellation requests. +.SS Asynchronous cancelability +Setting the cancelability type to +.B PTHREAD_CANCEL_ASYNCHRONOUS +is rarely useful. +Since the thread could be canceled at +.I any +time, it cannot safely reserve resources (e.g., allocating memory with +.BR malloc (3)), +acquire mutexes, semaphores, or locks, and so on. +Reserving resources is unsafe because the application has no way of +knowing what the state of these resources is when the thread is canceled; +that is, did cancellation occur before the resources were reserved, +while they were reserved, or after they were released? +Furthermore, some internal data structures +(e.g., the linked list of free blocks managed by the +.BR malloc (3) +family of functions) may be left in an inconsistent state +if cancellation occurs in the middle of the function call. +Consequently, clean-up handlers cease to be useful. +.PP +Functions that can be safely asynchronously canceled are called +.IR "async-cancel-safe functions" . +POSIX.1-2001 and POSIX.1-2008 require only that +.BR pthread_cancel (3), +.BR pthread_setcancelstate (), +and +.BR pthread_setcanceltype () +be async-cancel-safe. +In general, other library functions +can't be safely called from an asynchronously cancelable thread. +.PP +One of the few circumstances in which asynchronous cancelability is useful +is for cancellation of a thread that is in a pure compute-bound loop. +.SS Portability notes +The Linux threading implementations permit the +.I oldstate +argument of +.BR pthread_setcancelstate () +to be NULL, in which case the information about the previous +cancelability state is not returned to the caller. +Many other implementations also permit a NULL +.I oldstat +argument, +.\" It looks like at least Solaris, FreeBSD and Tru64 support this. +but POSIX.1 does not specify this point, +so portable applications should always specify a non-NULL value in +.IR oldstate . +A precisely analogous set of statements applies for the +.I oldtype +argument of +.BR pthread_setcanceltype (). +.SH EXAMPLE +See +.BR pthread_cancel (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_testcancel (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_setcanceltype.3 b/man3/pthread_setcanceltype.3 new file mode 100644 index 0000000..9625bc2 --- /dev/null +++ b/man3/pthread_setcanceltype.3 @@ -0,0 +1 @@ +.so man3/pthread_setcancelstate.3 diff --git a/man3/pthread_setconcurrency.3 b/man3/pthread_setconcurrency.3 new file mode 100644 index 0000000..547ddf1 --- /dev/null +++ b/man3/pthread_setconcurrency.3 @@ -0,0 +1,124 @@ +.\" Copyright (c) 2009 Michael Kerrisk, +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SETCONCURRENCY 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_setconcurrency, pthread_getconcurrency \- set/get +the concurrency level +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_setconcurrency(int " new_level ); +.BI "int pthread_getconcurrency(void); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_setconcurrency () +function informs the implementation of the application's +desired concurrency level, specified in +.IR new_level . +The implementation takes this only as a hint: +POSIX.1 does not specify the level of concurrency that +should be provided as a result of calling +.BR pthread_setconcurrency (). +.PP +Specifying +.I new_level +as 0 instructs the implementation to manage the concurrency level +as it deems appropriate. +.PP +.BR pthread_getconcurrency () +returns the current value of the concurrency level for this process. +.SH RETURN VALUE +On success, +.BR pthread_setconcurrency () +returns 0; +on error, it returns a nonzero error number. +.PP +.BR pthread_getconcurrency () +always succeeds, returning the concurrency level set by a previous call to +.BR pthread_setconcurrency (), +or 0, if +.BR pthread_setconcurrency () +has not previously been called. +.SH ERRORS +.BR pthread_setconcurrency () +can fail with the following error: +.TP +.B EINVAL +.I new_level +is negative. +.PP +POSIX.1 also documents an +.BR EAGAIN +error ("the value specified by +.I new_level +would cause a system resource to be exceeded"). +.SH VERSIONS +These functions are available in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_setconcurrency (), +.BR pthread_getconcurrency () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The default concurrency level is 0. +.PP +Concurrency levels are meaningful only for M:N threading implementations, +where at any moment a subset of a process's set of user-level threads +may be bound to a smaller number of kernel-scheduling entities. +Setting the concurrency level allows the application to +give the system a hint as to the number of kernel-scheduling entities +that should be provided for efficient execution of the application. +.PP +Both LinuxThreads and NPTL are 1:1 threading implementations, +so setting the concurrency level has no meaning. +In other words, +on Linux these functions merely exist for compatibility with other systems, +and they have no effect on the execution of a program. +.SH SEE ALSO +.BR pthread_attr_setscope (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_setname_np.3 b/man3/pthread_setname_np.3 new file mode 100644 index 0000000..fd7f7c4 --- /dev/null +++ b/man3/pthread_setname_np.3 @@ -0,0 +1,228 @@ +.\" Copyright (C) 2012 Chandan Apsangi +.\" and Copyright (C) 2013 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SETNAME_NP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_setname_np, pthread_getname_np \- set/get the name of a thread +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.BI "int pthread_setname_np(pthread_t " thread ", const char *" name "); +.BI "int pthread_getname_np(pthread_t " thread , +.BI " char *" name ", size_t " len ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +By default, all the threads created using +.BR pthread_create () +inherit the program name. +The +.BR pthread_setname_np () +function can be used to set a unique name for a thread, +which can be useful for debugging +multithreaded applications. +The thread name is a meaningful C language string, whose length is +restricted to 16 characters, including the terminating null byte (\(aq\\0\(aq). +The +.I thread +argument specifies the thread whose name is to be changed; +.I name +specifies the new name. +.PP +The +.BR pthread_getname_np () +function can be used to retrieve the name of the thread. +The +.I thread +argument specifies the thread whose name is to be retrieved. +The buffer +.I name +is used to return the thread name; +.I len +specifies the number of bytes available in +.IR name . +The buffer specified by +.I name +should be at least 16 characters in length. +The returned thread name in the output buffer will be null terminated. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +The +.BR pthread_setname_np () +function can fail with the following error: +.TP +.B ERANGE +The length of the string specified pointed to by +.I name +exceeds the allowed limit. +.PP +The +.BR pthread_getname_np () +function can fail with the following error: +.TP +.B ERANGE +The buffer specified by +.I name +and +.I len +is too small to hold the thread name. +.PP +If either of these functions fails to open +.IR /proc/self/task/[tid]/comm , +then the call may fail with one of the errors described in +.BR open (2). +.SH VERSIONS +These functions first appeared in glibc in version 2.12. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_setname_np (), +.BR pthread_getname_np () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +These functions are nonstandard GNU extensions. +.SH NOTES +.BR pthread_setname_np () +internally writes to the thread-specific +.I comm +file under the +.IR /proc +filesystem: +.IR /proc/self/task/[tid]/comm . +.BR pthread_getname_np () +retrieves it from the same location. +.SH EXAMPLE +.PP +The program below demonstrates the use of +.BR pthread_setname_np () +and +.BR pthread_getname_np (). +.PP +The following shell session shows a sample run of the program: +.PP +.in +4n +.EX +.RB "$" " ./a.out" +Created a thread. Default name is: a.out +The thread name after setting it is THREADFOO. +\fB^Z\fP # Suspend the program +[1]+ Stopped ./a.out +.RB "$ " "ps H -C a.out -o 'pid tid cmd comm'" + PID TID CMD COMMAND + 5990 5990 ./a.out a.out + 5990 5991 ./a.out THREADFOO +.RB "$ " "cat /proc/5990/task/5990/comm" +a.out +.RB "$ " "cat /proc/5990/task/5991/comm" +THREADFOO +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +#define NAMELEN 16 + +#define errExitEN(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +static void * +threadfunc(void *parm) +{ + sleep(5); // allow main program to set the thread name + return NULL; +} + +int +main(int argc, char **argv) +{ + pthread_t thread; + int rc; + char thread_name[NAMELEN]; + + rc = pthread_create(&thread, NULL, threadfunc, NULL); + if (rc != 0) + errExitEN(rc, "pthread_create"); + + rc = pthread_getname_np(thread, thread_name, NAMELEN); + if (rc != 0) + errExitEN(rc, "pthread_getname_np"); + + printf("Created a thread. Default name is: %s\\n", thread_name); + rc = pthread_setname_np(thread, (argc > 1) ? argv[1] : "THREADFOO"); + if (rc != 0) + errExitEN(rc, "pthread_setname_np"); + + sleep(2); + + rc = pthread_getname_np(thread, thread_name, + (argc > 2) ? atoi(argv[1]) : NAMELEN); + if (rc != 0) + errExitEN(rc, "pthread_getname_np"); + printf("The thread name after setting it is %s.\\n", thread_name); + + rc = pthread_join(thread, NULL); + if (rc != 0) + errExitEN(rc, "pthread_join"); + + printf("Done\\n"); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR prctl (2), +.BR pthread_create (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_setschedparam.3 b/man3/pthread_setschedparam.3 new file mode 100644 index 0000000..de984b1 --- /dev/null +++ b/man3/pthread_setschedparam.3 @@ -0,0 +1,468 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SETSCHEDPARAM 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_setschedparam, pthread_getschedparam \- set/get +scheduling policy and parameters of a thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_setschedparam(pthread_t " thread ", int " policy , +.BI " const struct sched_param *" param ); +.BI "int pthread_getschedparam(pthread_t " thread ", int *" policy , +.BI " struct sched_param *" param ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_setschedparam () +function sets the scheduling policy and parameters of the thread +.IR thread . +.PP +.I policy +specifies the new scheduling policy for +.IR thread . +The supported values for +.IR policy , +and their semantics, are described in +.BR sched (7). +.\" FIXME . pthread_setschedparam() places no restriction on the policy, +.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 +.PP +The structure pointed to by +.I param +specifies the new scheduling parameters for +.IR thread . +Scheduling parameters are maintained in the following structure: +.PP +.in +4n +.EX +struct sched_param { + int sched_priority; /* Scheduling priority */ +}; +.EE +.in +.PP +As can be seen, only one scheduling parameter is supported. +For details of the permitted ranges for scheduling priorities +in each scheduling policy, see +.BR sched (7). +.PP +The +.BR pthread_getschedparam () +function returns the scheduling policy and parameters of the thread +.IR thread , +in the buffers pointed to by +.I policy +and +.IR param , +respectively. +The returned priority value is that set by the most recent +.BR pthread_setschedparam (), +.BR pthread_setschedprio (3), +or +.BR pthread_create (3) +call that affected +.IR thread . +The returned priority does not reflect any temporary priority adjustments +as a result of calls to any priority inheritance or +priority ceiling functions (see, for example, +.BR pthread_mutexattr_setprioceiling (3) +and +.BR pthread_mutexattr_setprotocol (3)). +.\" FIXME . nptl/pthread_setschedparam.c has the following +.\" /* If the thread should have higher priority because of some +.\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */ +.\" Eventually (perhaps after writing the mutexattr pages), we +.\" may want to add something on the topic to this page. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +If +.BR pthread_setschedparam () +fails, the scheduling policy and parameters of +.I thread +are not changed. +.SH ERRORS +Both of these functions can fail with the following error: +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.PP +.BR pthread_setschedparam () +may additionally fail with the following errors: +.TP +.B EINVAL +.I policy +is not a recognized policy, or +.I param +does not make sense for the +.IR policy . +.TP +.B EPERM +The caller does not have appropriate privileges +to set the specified scheduling policy and parameters. +.PP +POSIX.1 also documents an +.B ENOTSUP +("attempt was made to set the policy or scheduling parameters +to an unsupported value") error for +.BR pthread_setschedparam (). +.\" .SH VERSIONS +.\" Available since glibc 2.0 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_setschedparam (), +.BR pthread_getschedparam () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +For a description of the permissions required to, and the effect of, +changing a thread's scheduling policy and priority, +and details of the permitted ranges for priorities +in each scheduling policy, see +.BR sched (7). +.SH EXAMPLE +The program below demonstrates the use of +.BR pthread_setschedparam () +and +.BR pthread_getschedparam (), +as well as the use of a number of other scheduling-related +pthreads functions. +.PP +In the following run, the main thread sets its scheduling policy to +.BR SCHED_FIFO +with a priority of 10, +and initializes a thread attributes object with +a scheduling policy attribute of +.BR SCHED_RR +and a scheduling priority attribute of 20. +The program then sets (using +.BR pthread_attr_setinheritsched (3)) +the inherit scheduler attribute of the thread attributes object to +.BR PTHREAD_EXPLICIT_SCHED , +meaning that threads created using this attributes object should +take their scheduling attributes from the thread attributes object. +The program then creates a thread using the thread attributes object, +and that thread displays its scheduling policy and priority. +.PP +.in +4n +.EX +$ \fBsu\fP # Need privilege to set real-time scheduling policies +Password: +# \fB./a.out \-mf10 \-ar20 \-i e\fP +Scheduler settings of main thread + policy=SCHED_FIFO, priority=10 + +Scheduler settings in \(aqattr\(aq + policy=SCHED_RR, priority=20 + inheritsched is EXPLICIT + +Scheduler attributes of new thread + policy=SCHED_RR, priority=20 +.EE +.in +.PP +In the above output, one can see that the scheduling policy and priority +were taken from the values specified in the thread attributes object. +.PP +The next run is the same as the previous, +except that the inherit scheduler attribute is set to +.BR PTHREAD_INHERIT_SCHED , +meaning that threads created using the thread attributes object should +ignore the scheduling attributes specified in the attributes object +and instead take their scheduling attributes from the creating thread. +.PP +.in +4n +.EX +# \fB./a.out \-mf10 \-ar20 \-i i\fP +Scheduler settings of main thread + policy=SCHED_FIFO, priority=10 + +Scheduler settings in \(aqattr\(aq + policy=SCHED_RR, priority=20 + inheritsched is INHERIT + +Scheduler attributes of new thread + policy=SCHED_FIFO, priority=10 +.EE +.in +.PP +In the above output, one can see that the scheduling policy and priority +were taken from the creating thread, +rather than the thread attributes object. +.PP +Note that if we had omitted the +.IR "\-i\ i" +option, the output would have been the same, since +.BR PTHREAD_INHERIT_SCHED +is the default for the inherit scheduler attribute. +.SS Program source +\& +.EX +/* pthreads_sched_test.c */ + +#include +#include +#include +#include +#include + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void +usage(char *prog_name, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); + + fprintf(stderr, "Usage: %s [options]\\n", prog_name); + fprintf(stderr, "Options are:\\n"); +#define fpe(msg) fprintf(stderr, "\\t%s", msg); /* Shorter */ + fpe("\-a Set scheduling policy and priority in\\n"); + fpe(" thread attributes object\\n"); + fpe(" can be\\n"); + fpe(" f SCHED_FIFO\\n"); + fpe(" r SCHED_RR\\n"); + fpe(" o SCHED_OTHER\\n"); + fpe("\-A Use default thread attributes object\\n"); + fpe("\-i {e|i} Set inherit scheduler attribute to\\n"); + fpe(" \(aqexplicit\(aq or \(aqinherit\(aq\\n"); + fpe("\-m Set scheduling policy and priority on\\n"); + fpe(" main thread before pthread_create() call\\n"); + exit(EXIT_FAILURE); +} + +static int +get_policy(char p, int *policy) +{ + switch (p) { + case \(aqf\(aq: *policy = SCHED_FIFO; return 1; + case \(aqr\(aq: *policy = SCHED_RR; return 1; + case \(aqo\(aq: *policy = SCHED_OTHER; return 1; + default: return 0; + } +} + +static void +display_sched_attr(int policy, struct sched_param *param) +{ + printf(" policy=%s, priority=%d\\n", + (policy == SCHED_FIFO) ? "SCHED_FIFO" : + (policy == SCHED_RR) ? "SCHED_RR" : + (policy == SCHED_OTHER) ? "SCHED_OTHER" : + "???", + param\->sched_priority); +} + +static void +display_thread_sched_attr(char *msg) +{ + int policy, s; + struct sched_param param; + + s = pthread_getschedparam(pthread_self(), &policy, ¶m); + if (s != 0) + handle_error_en(s, "pthread_getschedparam"); + + printf("%s\\n", msg); + display_sched_attr(policy, ¶m); +} + +static void * +thread_start(void *arg) +{ + display_thread_sched_attr("Scheduler attributes of new thread"); + + return NULL; +} + +int +main(int argc, char *argv[]) +{ + int s, opt, inheritsched, use_null_attrib, policy; + pthread_t thread; + pthread_attr_t attr; + pthread_attr_t *attrp; + char *attr_sched_str, *main_sched_str, *inheritsched_str; + struct sched_param param; + + /* Process command\-line options */ + + use_null_attrib = 0; + attr_sched_str = NULL; + main_sched_str = NULL; + inheritsched_str = NULL; + + while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) { + switch (opt) { + case \(aqa\(aq: attr_sched_str = optarg; break; + case \(aqA\(aq: use_null_attrib = 1; break; + case \(aqi\(aq: inheritsched_str = optarg; break; + case \(aqm\(aq: main_sched_str = optarg; break; + default: usage(argv[0], "Unrecognized option\\n"); + } + } + + if (use_null_attrib && + (inheritsched_str != NULL || attr_sched_str != NULL)) + usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\\n"); + + /* Optionally set scheduling attributes of main thread, + and display the attributes */ + + if (main_sched_str != NULL) { + if (!get_policy(main_sched_str[0], &policy)) + usage(argv[0], "Bad policy for main thread (\-m)\\n"); + param.sched_priority = strtol(&main_sched_str[1], NULL, 0); + + s = pthread_setschedparam(pthread_self(), policy, ¶m); + if (s != 0) + handle_error_en(s, "pthread_setschedparam"); + } + + display_thread_sched_attr("Scheduler settings of main thread"); + printf("\\n"); + + /* Initialize thread attributes object according to options */ + + attrp = NULL; + + if (!use_null_attrib) { + s = pthread_attr_init(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); + attrp = &attr; + } + + if (inheritsched_str != NULL) { + if (inheritsched_str[0] == \(aqe\(aq) + inheritsched = PTHREAD_EXPLICIT_SCHED; + else if (inheritsched_str[0] == \(aqi\(aq) + inheritsched = PTHREAD_INHERIT_SCHED; + else + usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\\n"); + + s = pthread_attr_setinheritsched(&attr, inheritsched); + if (s != 0) + handle_error_en(s, "pthread_attr_setinheritsched"); + } + + if (attr_sched_str != NULL) { + if (!get_policy(attr_sched_str[0], &policy)) + usage(argv[0], + "Bad policy for \(aqattr\(aq (\-a)\\n"); + param.sched_priority = strtol(&attr_sched_str[1], NULL, 0); + + s = pthread_attr_setschedpolicy(&attr, policy); + if (s != 0) + handle_error_en(s, "pthread_attr_setschedpolicy"); + s = pthread_attr_setschedparam(&attr, ¶m); + if (s != 0) + handle_error_en(s, "pthread_attr_setschedparam"); + } + + /* If we initialized a thread attributes object, display + the scheduling attributes that were set in the object */ + + if (attrp != NULL) { + s = pthread_attr_getschedparam(&attr, ¶m); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedparam"); + s = pthread_attr_getschedpolicy(&attr, &policy); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedpolicy"); + + printf("Scheduler settings in \(aqattr\(aq\\n"); + display_sched_attr(policy, ¶m); + + s = pthread_attr_getinheritsched(&attr, &inheritsched); + printf(" inheritsched is %s\\n", + (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" : + (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" : + "???"); + printf("\\n"); + } + + /* Create a thread that will display its scheduling attributes */ + + s = pthread_create(&thread, attrp, &thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); + + /* Destroy unneeded thread attributes object */ + + if (!use_null_attrib) { + s = pthread_attr_destroy(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); + } + + s = pthread_join(thread, NULL); + if (s != 0) + handle_error_en(s, "pthread_join"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_setschedprio.3 b/man3/pthread_setschedprio.3 new file mode 100644 index 0000000..924e83f --- /dev/null +++ b/man3/pthread_setschedprio.3 @@ -0,0 +1,125 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SETSCHEDPRIO 3 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_setschedprio \- set scheduling priority of a thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_setschedprio(pthread_t " thread ", int " prio ); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +The +.BR pthread_setschedprio () +function sets the scheduling priority of the thread +.I thread +to the value specified in +.IR prio . +(By contrast +.BR pthread_setschedparam (3) +changes both the scheduling policy and priority of a thread.) +.\" FIXME . nptl/pthread_setschedprio.c has the following +.\" /* If the thread should have higher priority because of some +.\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */ +.\" Eventually (perhaps after writing the mutexattr pages), we +.\" may want to add something on the topic to this page. +.\" nptl/pthread_setschedparam.c has a similar case. +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +If +.BR pthread_setschedprio () +fails, the scheduling priority of +.I thread +is not changed. +.SH ERRORS +.TP +.B EINVAL +.I prio +is not valid for the scheduling policy of the specified thread. +.TP +.B EPERM +The caller does not have appropriate privileges +to set the specified priority. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.PP +POSIX.1 also documents an +.B ENOTSUP +("attempt was made to set the priority +to an unsupported value") error for +.BR pthread_setschedparam (3). +.SH VERSIONS +This function is available in glibc since version 2.3.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw22 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_setschedprio () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +For a description of the permissions required to, and the effect of, +changing a thread's scheduling priority, +and details of the permitted ranges for priorities +in each scheduling policy, see +.BR sched (7). +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthread_setschedparam (3), +.BR pthreads (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_sigmask.3 b/man3/pthread_sigmask.3 new file mode 100644 index 0000000..2b01c06 --- /dev/null +++ b/man3/pthread_sigmask.3 @@ -0,0 +1,184 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SIGMASK 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_sigmask \- examine and change mask of blocked signals +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_sigmask(int " how ", const sigset_t *" set \ +", sigset_t *" oldset ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR pthread_sigmask (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 199506L || _XOPEN_SOURCE\ >=\ 500 +.RE +.ad b +.SH DESCRIPTION +The +.BR pthread_sigmask () +function is just like +.BR sigprocmask (2), +with the difference that its use in multithreaded programs +is explicitly specified by POSIX.1. +Other differences are noted in this page. +.PP +For a description of the arguments and operation of this function, see +.BR sigprocmask (2). +.SH RETURN VALUE +On success, +.BR pthread_sigmask () +returns 0; +on error, it returns an error number. +.SH ERRORS +See +.BR sigprocmask (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_sigmask () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +A new thread inherits a copy of its creator's signal mask. +.PP +The glibc +.BR pthread_sigmask () +function silently ignores attempts to block the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH EXAMPLE +The program below blocks some signals in the main thread, +and then creates a dedicated thread to fetch those signals via +.BR sigwait (3). +The following shell session demonstrates its use: +.PP +.in +4n +.EX +.RB "$" " ./a.out &" +[1] 5423 +.RB "$" " kill \-QUIT %1" +Signal handling thread got signal 3 +.RB "$" " kill \-USR1 %1" +Signal handling thread got signal 10 +.RB "$" " kill \-TERM %1" +[1]+ Terminated ./a.out +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include + +/* Simple error handling functions */ + +#define handle_error_en(en, msg) \\ + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) + +static void * +sig_thread(void *arg) +{ + sigset_t *set = arg; + int s, sig; + + for (;;) { + s = sigwait(set, &sig); + if (s != 0) + handle_error_en(s, "sigwait"); + printf("Signal handling thread got signal %d\\n", sig); + } +} + +int +main(int argc, char *argv[]) +{ + pthread_t thread; + sigset_t set; + int s; + + /* Block SIGQUIT and SIGUSR1; other threads created by main() + will inherit a copy of the signal mask. */ + + sigemptyset(&set); + sigaddset(&set, SIGQUIT); + sigaddset(&set, SIGUSR1); + s = pthread_sigmask(SIG_BLOCK, &set, NULL); + if (s != 0) + handle_error_en(s, "pthread_sigmask"); + + s = pthread_create(&thread, NULL, &sig_thread, (void *) &set); + if (s != 0) + handle_error_en(s, "pthread_create"); + + /* Main thread carries on to create other threads and/or do + other work */ + + pause(); /* Dummy pause so we can test program */ +} +.EE +.SH SEE ALSO +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR pthread_create (3), +.BR pthread_kill (3), +.BR sigsetops (3), +.BR pthreads (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_sigqueue.3 b/man3/pthread_sigqueue.3 new file mode 100644 index 0000000..686b169 --- /dev/null +++ b/man3/pthread_sigqueue.3 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2010 Michael Kerrisk, +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SIGQUEUE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_sigqueue \- queue a signal and data to a thread +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int pthread_sigqueue(pthread_t " thread ", int " sig , +.BI " const union sigval " value ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR pthread_sigqueue (): +_GNU_SOURCE +.SH DESCRIPTION +The +.BR pthread_sigqueue () +function performs a similar task to +.BR sigqueue (3), +but, rather than sending a signal to a process, +it sends a signal to a thread in the same process as the +calling thread. +.PP +The +.I thread +argument is the ID of a thread in the same process as the caller. +The +.I sig +argument specifies the signal to be sent. +The +.I value +argument specifies data to accompany the signal; see +.BR sigqueue (3) +for details. +.SH RETURN VALUE +On success, +.BR pthread_sigqueue () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.I sig +was invalid. +.TP +.B ENOSYS +.BR pthread_sigqueue () +is not supported on this system. +.TP +.B ESRCH +.I thread +is not valid. +.SH VERSIONS +The +.BR pthread_sigqueue () +function first appeared in glibc 2.11. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_sigqueue () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is a GNU extension. +.SH NOTES +The glibc implementation of +.BR pthread_sigqueue () +gives an error +.RB ( EINVAL ) +on attempts to send either of the real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH SEE ALSO +.BR rt_tgsigqueueinfo (2), +.BR sigaction (2), +.BR pthread_sigmask (3), +.BR sigqueue (3), +.BR sigwait (3), +.BR pthreads (7), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_spin_destroy.3 b/man3/pthread_spin_destroy.3 new file mode 100644 index 0000000..f19c345 --- /dev/null +++ b/man3/pthread_spin_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_init.3 diff --git a/man3/pthread_spin_init.3 b/man3/pthread_spin_init.3 new file mode 100644 index 0000000..f111dfc --- /dev/null +++ b/man3/pthread_spin_init.3 @@ -0,0 +1,178 @@ +.\" Copyright (c) 2017, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SPIN_INIT 3 2017-09-30 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_spin_init(pthread_spinlock_t *" lock " int " pshared ");" +.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");" +.fi +.PP +Compile and link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR pthread_spin_init (), +.BR pthread_spin_destroy (): +.br +.RS 4 +.ad l +_POSIX_C_SOURCE >= 200112L +.RE +.ad +.SH DESCRIPTION +.IR "General note" : +Most programs should use mutexes +instead of spin locks. +Spin locks are primarily useful in conjunction with real-time +scheduling policies. +See NOTES. +.PP +The +.BR pthread_spin_init () +function allocates any resources required for the use of +the spin lock referred to by +.I lock +and initializes the lock to be in the unlocked state. +The +.I pshared +argument must have one of the following values: +.TP +.B PTHREAD_PROCESS_PRIVATE +The spin lock is to be operated on only by threads in the same process +as the thread that calls +.BR pthread_spin_init (). +(Attempting to share the spin lock between processes +results in undefined behavior.) +.TP +.B PTHREAD_PROCESS_SHARED +The spin lock may be operated on by any thread in any process that +has access to the memory containing the lock +(i.e., the lock may be in a shared memory object that is +shared among multiple processes). +.PP +Calling +.BR pthread_spin_init () +on a spin lock that has already been initialized results +in undefined behavior. +.PP +The +.BR pthread_spin_destroy () +function destroys a previously initialized spin lock, +freeing any resources that were allocated for that lock. +Destroying a spin lock that has not been previously been initialized +or destroying a spin lock while another thread holds the lock +results in undefined behavior. +.PP +Once a spin lock has been destroyed, +performing any operation on the lock other than +once more initializing it with +.BR pthread_spin_init () +results in undefined behavior. +.PP +The result of performing operations such as +.BR pthread_spin_lock (3), +.BR pthread_spin_unlock (3), +and +.BR pthread_spin_destroy (3) +on +.I copies +of the object referred to by +.I lock +is undefined. +.SH RETURN VALUE +On success, there functions return zero. +On failure, they return an error number. +In the event that +.BR pthread_spin_init () +fails, the lock is not initialized. +.SH ERRORS +.BR pthread_spin_init () +may fail with the following errors: +.\" These errors don't occur on the glibc implementation +.TP +.B EAGAIN +The system has insufficient resources to initialize +a new spin lock. +.TP +.B ENOMEM +Insufficient memory to initialize the spin lock. +.SH VERSIONS +These functions first appeared in glibc in version 2.2. +.SH CONFORMING TO +POSIX.1-2001. +.PP +Support for process-shared spin locks is a POSIX option. +The option is supported in the glibc implementation. +.SH NOTES +Spin locks should be employed in conjunction with +real-time scheduling policies +.RB ( SCHED_FIFO , +or possibly +.BR SCHED_RR ). +Use of spin locks with nondeterministic scheduling policies such as +.BR SCHED_OTHER +probably indicates a design mistake. +The problem is that if a thread operating under such a policy +is scheduled off the CPU while it holds a spin lock, +then other threads will waste time spinning on the lock +until the lock holder is once more rescheduled and releases the lock. +.PP +If threads create a deadlock situation while employing spin locks, +those threads will spin forever consuming CPU time. +.PP +User-space spin locks are +.I not +applicable as a general locking solution. +They are, by definition, +prone to priority inversion and unbounded spin times. +A programmer using spin locks must be exceptionally careful not +only in the code, but also in terms of system configuration, +thread placement, and priority assignment. +.\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document +.\" make reference to it here +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutex_init (3), +.BR pthread_mutex_lock (3), +.BR pthread_spin_lock (3), +.BR pthread_spin_unlock (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_spin_lock.3 b/man3/pthread_spin_lock.3 new file mode 100644 index 0000000..3f6a024 --- /dev/null +++ b/man3/pthread_spin_lock.3 @@ -0,0 +1,132 @@ +.\" Copyright (c) 2017, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_SPIN_LOCK 3 2017-09-30 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_spin_lock, pthread_spin_trylock, pthread_spin_unlock \- +lock and unlock a spin lock +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int pthread_spin_lock(pthread_spinlock_t *" lock ); +.BI "int pthread_spin_trylock(pthread_spinlock_t *" lock ); +.BI "int pthread_spin_unlock(pthread_spinlock_t *" lock ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR pthread_spin_lock (), +.BR pthread_spin_trylock (): +.br +.RS 4 +.ad l +_POSIX_C_SOURCE >= 200112L +.RE +.ad +.SH DESCRIPTION +The +.BR pthread_spin_lock () +function locks the spin lock referred to by +.IR lock . +If the spin lock is currently unlocked, +the calling thread acquires the lock immediately. +If the spin lock is currently locked by another thread, +the calling thread spins, testing the lock until it becomes available, +at which point the calling thread acquires the lock. +.PP +Calling +.BR pthread_spin_lock () +on a lock that is already held by the caller +or a lock that has not been initialized with +.BR pthread_spin_init (3) +results in undefined behavior. +.PP +The +.BR pthread_spin_trylock () +function is like +.BR pthread_spin_lock (), +except that if the spin lock referred to by +.I lock +is currently locked, +then, instead of spinning, the call returns immediately with the error +.BR EBUSY . +.PP +The +.BR pthread_spin_unlock () +function unlocks the spin lock referred to +.IR lock . +If any threads are spinning on the lock, +one of those threads will then acquire the lock. +.PP +Calling +.BR pthread_spin_unlock () +on a lock that is not held by the caller results in undefined behavior. +.SH RETURN VALUE +On success, these functions return zero. +On failure, they return an error number. +.SH ERRORS +.BR pthread_spin_lock () +may fail with the following errors: +.TP +.B EDEADLOCK +.\" Not detected in glibc +The system detected a deadlock condition. +.PP +.BR pthread_spin_trylock () +fails with the following errors: +.TP +.B EBUSY +The spin lock is currently locked by another thread. +.SH VERSIONS +These functions first appeared in glibc in version 2.2. +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES +Applying any of the functions described on this page to +an uninitialized spin lock results in undefined behavior. +.PP +Carefully read NOTES in +.BR pthread_spin_init (3). +.SH SEE ALSO +.ad l +.nh +.\" FIXME . .BR pthread_mutex_lock (3), +.BR pthread_spin_destroy (3), +.BR pthread_spin_init (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_spin_trylock.3 b/man3/pthread_spin_trylock.3 new file mode 100644 index 0000000..ad2969a --- /dev/null +++ b/man3/pthread_spin_trylock.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_lock.3 diff --git a/man3/pthread_spin_unlock.3 b/man3/pthread_spin_unlock.3 new file mode 100644 index 0000000..ad2969a --- /dev/null +++ b/man3/pthread_spin_unlock.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_lock.3 diff --git a/man3/pthread_testcancel.3 b/man3/pthread_testcancel.3 new file mode 100644 index 0000000..507fbbd --- /dev/null +++ b/man3/pthread_testcancel.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_TESTCANCEL 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_testcancel \- request delivery of any pending cancellation request +.SH SYNOPSIS +.nf +.B #include +.PP +.B void pthread_testcancel(void); +.PP +Compile and link with \fI\-pthread\fP. +.fi +.SH DESCRIPTION +Calling +.BR pthread_testcancel () +creates a cancellation point within the calling thread, +so that a thread that is otherwise executing code that contains +no cancellation points will respond to a cancellation request. +.PP +If cancelability is disabled (using +.BR pthread_setcancelstate (3)), +or no cancellation request is pending, +then a call to +.BR pthread_testcancel () +has no effect. +.SH RETURN VALUE +This function does not return a value. +If the calling thread is canceled as a consequence of a call +to this function, then the function does not return. +.SH ERRORS +This function always succeeds. +.\" SH VERSIONS +.\" Available since glibc 2.0 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_testcancel () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +See +.BR pthread_cleanup_push (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_setcancelstate (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_timedjoin_np.3 b/man3/pthread_timedjoin_np.3 new file mode 100644 index 0000000..a741f46 --- /dev/null +++ b/man3/pthread_timedjoin_np.3 @@ -0,0 +1 @@ +.so man3/pthread_tryjoin_np.3 diff --git a/man3/pthread_tryjoin_np.3 b/man3/pthread_tryjoin_np.3 new file mode 100644 index 0000000..c9fcc6f --- /dev/null +++ b/man3/pthread_tryjoin_np.3 @@ -0,0 +1,173 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_TRYJOIN_NP 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_tryjoin_np, pthread_timedjoin_np \- try to join with a +terminated thread +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int pthread_tryjoin_np(pthread_t " thread ", void **" retval ); +.PP +.BI "int pthread_timedjoin_np(pthread_t " thread ", void **" retval , +.BI " const struct timespec *" abstime ); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +These functions operate in the same way as +.BR pthread_join (3), +except for the differences described on this page. +.PP +The +.BR pthread_tryjoin_np () +function performs a nonblocking join with the thread +.IR thread , +returning the exit status of the thread in +.IR *retval . +If +.I thread +has not yet terminated, then instead of blocking, as is done by +.BR pthread_join (3), +the call returns an error. +.PP +The +.BR pthread_timedjoin_np () +function performs a join-with-timeout. +If +.I thread +has not yet terminated, +then the call blocks until a maximum time, specified in +.IR abstime . +If the timeout expires before +.I thread +terminates, +the call returns an error. +The +.I abstime +argument is a structure of the following form, +specifying an absolute time measured since the Epoch (see +.BR time (2)): +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ +}; +.EE +.in +.SH RETURN VALUE +On success, +these functions return 0; +on error, they return an error number. +.SH ERRORS +These functions can fail with the same errors as +.BR pthread_join (3). +.BR pthread_tryjoin_np () +can in addition fail with the following error: +.TP +.B EBUSY +.I thread +had not yet terminated at the time of the call. +.PP +.BR pthread_timedjoin_np () +can in addition fail with the following errors: +.TP +.BR ETIMEDOUT +The call timed out before +.I thread +terminated. +.TP +.BR EINVAL +.I abstime +value is invalid +.RI ( tv_sec +is less than 0 or +.IR tv_nsec +is greater than 1e9). +.PP +.BR pthread_timedjoin_np () +never returns the error +.BR EINTR . +.SH VERSIONS +These functions first appeared in glibc in version 2.3.3. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw22 lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_tryjoin_np (), +.BR pthread_timedjoin_np () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +These functions are nonstandard GNU extensions; +hence the suffix "_np" (nonportable) in the names. +.SH EXAMPLE +The following code waits to join for up to 5 seconds: +.PP +.in +4n +.EX +struct timespec ts; +int s; + +\&... + +if (clock_gettime(CLOCK_REALTIME, &ts) == \-1) { + /* Handle error */ +} + +ts.tv_sec += 5; + +s = pthread_timedjoin_np(thread, NULL, &ts); +if (s != 0) { + /* Handle error */ +} +.EE +.in +.SH SEE ALSO +.BR clock_gettime (2), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/pthread_yield.3 b/man3/pthread_yield.3 new file mode 100644 index 0000000..fec33dc --- /dev/null +++ b/man3/pthread_yield.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 2009 Michael Kerrisk, +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREAD_YIELD 3 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_yield \- yield the processor +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.B int pthread_yield(void); +.fi +.PP +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +.BR pthread_yield () +causes the calling thread to relinquish the CPU. +The thread is placed at the end of the run queue for its static +priority and another thread is scheduled to run. +For further details, see +.BR sched_yield (2) +.SH RETURN VALUE +On success, +.BR pthread_yield () +returns 0; +on error, it returns an error number. +.SH ERRORS +On Linux, this call always succeeds +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR pthread_yield () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This call is nonstandard, but present on several other systems. +Use the standardized +.BR sched_yield (2) +instead. +.\" e.g., the BSDs, Tru64, AIX, and Irix. +.SH NOTES +On Linux, this function is implemented as a call to +.BR sched_yield (2). +.PP +.BR pthread_yield () +is intended for use with real-time scheduling policies (i.e., +.BR SCHED_FIFO +or +.BR SCHED_RR ). +Use of +.BR pthread_yield () +with nondeterministic scheduling policies such as +.BR SCHED_OTHER +is unspecified and very likely means your application design is broken. +.SH SEE ALSO +.BR sched_yield (2), +.\" FIXME . .BR pthread_cond_wait (3), +.BR pthreads (7), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ptsname.3 b/man3/ptsname.3 new file mode 100644 index 0000000..c32a595 --- /dev/null +++ b/man3/ptsname.3 @@ -0,0 +1,144 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS +.\" +.TH PTSNAME 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ptsname, ptsname_r \- get the name of the slave pseudoterminal +.SH SYNOPSIS +.B #include +.PP +.BI "char *ptsname(int " fd ");" +.br +.BI "int ptsname_r(int " fd ", char *" buf ", size_t " buflen ");" +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR ptsname (): +.br +.RS 4 +Since glibc 2.24: + _XOPEN_SOURCE\ >=\ 500 || + (_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) +.br +Glibc 2.23 and earlier: + _XOPEN_SOURCE +.RE +.PP +.BR ptsname_r (): + _GNU_SOURCE +.ad +.SH DESCRIPTION +The +.BR ptsname () +function returns the name of the slave pseudoterminal device +corresponding to the master referred to by +.IR fd . +.PP +The +.BR ptsname_r () +function is the reentrant equivalent of +.BR ptsname (). +It returns the name of the slave pseudoterminal device as a +null-terminated string in the buffer pointed to by +.IR buf . +The +.I buflen +argument specifies the number of bytes available in +.IR buf . +.SH RETURN VALUE +On success, +.BR ptsname () +returns a pointer to a string in static storage which will be +overwritten by subsequent calls. +This pointer must not be freed. +On failure, NULL is returned. +.PP +On success, +.BR ptsname_r () +returns 0. +On failure, a nonzero value is returned +and +.I errno +is set to indicate the error. +.\" In fact the errno value is also returned as the function +.\" result -- MTK, Dec 04 +.SH ERRORS +.TP +.B EINVAL +.RB ( ptsname_r () +only) +.I buf +is NULL. +(This error is returned only for +.\" glibc commit 8f0a947cf55f3b0c4ebdf06953c57eff67a22fa9 +glibc 2.25 and earlier.) +.TP +.B ENOTTY +.I fd +does not refer to a pseudoterminal master device. +.TP +.B ERANGE +.RB ( ptsname_r () +only) +.I buf +is too small. +.SH VERSIONS +.BR ptsname () +is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ptsname () +T} Thread safety MT-Unsafe race:ptsname +T{ +.BR ptsname_r () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR ptsname (): + POSIX.1-2001, POSIX.1-2008. +.PP +.BR ptsname () +is part of the UNIX 98 pseudoterminal support (see +.BR pts (4)). +.PP +.BR ptsname_r () +is a Linux extension, that is proposed for inclusion +.\" FIXME . for later review when Issue 8 is one day released +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=508 +in the next major revision of POSIX.1 (Issue 8). +A version of this function is documented on Tru64 and HP-UX, but +on those implementations, \-1 is returned on error, with +.I errno +set to indicate the error. +Avoid using this function in portable programs. +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ttyname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ptsname_r.3 b/man3/ptsname_r.3 new file mode 100644 index 0000000..0a5f98d --- /dev/null +++ b/man3/ptsname_r.3 @@ -0,0 +1 @@ +.so man3/ptsname.3 diff --git a/man3/putc.3 b/man3/putc.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man3/putc.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man3/putc_unlocked.3 b/man3/putc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/putc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/putchar.3 b/man3/putchar.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man3/putchar.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man3/putchar_unlocked.3 b/man3/putchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/putchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/putenv.3 b/man3/putenv.3 new file mode 100644 index 0000000..27e5ec4 --- /dev/null +++ b/man3/putenv.3 @@ -0,0 +1,146 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Single UNIX Specification, Version 2 +.\" Modified Thu Apr 8 15:00:12 1993, David Metcalfe +.\" Modified Sat Jul 24 18:44:45 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl) +.TH PUTENV 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +putenv \- change or add an environment variable +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int putenv(char *" string ); +.\" Not: const char * +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR putenv (): +_XOPEN_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.SH DESCRIPTION +The +.BR putenv () +function adds or changes the value of environment +variables. +The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP. +If \fIname\fP does not already exist in the environment, then +\fIstring\fP is added to the environment. +If \fIname\fP does exist, +then the value of \fIname\fP in the environment is changed to +\fIvalue\fP. +The string pointed to by \fIstring\fP becomes part of the environment, +so altering the string changes the environment. +.SH RETURN VALUE +The +.BR putenv () +function returns zero on success, +or nonzero if an error occurs. +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +.TP +.B ENOMEM +Insufficient space to allocate new environment. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR putenv () +T} Thread safety MT-Unsafe const:env +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +The +.BR putenv () +function is not required to be reentrant, and the +one in glibc 2.0 is not, but the glibc 2.1 version is. +.\" .LP +.\" Description for libc4, libc5, glibc: +.\" If the argument \fIstring\fP is of the form \fIname\fP, +.\" and does not contain an \(aq=\(aq character, then the variable \fIname\fP +.\" is removed from the environment. +.\" If +.\" .BR putenv () +.\" has to allocate a new array \fIenviron\fP, +.\" and the previous array was also allocated by +.\" .BR putenv (), +.\" then it will be freed. +.\" In no case will the old storage associated +.\" to the environment variable itself be freed. +.PP +Since version 2.1.2, the glibc implementation conforms to SUSv2: +the pointer \fIstring\fP given to +.BR putenv () +is used. +In particular, this string becomes part of the environment; +changing it later will change the environment. +(Thus, it is an error is to call +.BR putenv () +with an automatic variable +as the argument, then return from the calling function while \fIstring\fP +is still part of the environment.) +However, glibc versions 2.0 to 2.1.1 differ: a copy of the string is used. +On the one hand this causes a memory leak, and on the other hand +it violates SUSv2. +.PP +The 4.4BSD version, like glibc 2.0, uses a copy. +.PP +SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3. +.SH SEE ALSO +.BR clearenv (3), +.BR getenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/putgrent.3 b/man3/putgrent.3 new file mode 100644 index 0000000..32c31d1 --- /dev/null +++ b/man3/putgrent.3 @@ -0,0 +1,70 @@ +.\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH PUTGRENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +putgrent \- write a group database entry to a file +.SH SYNOPSIS +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.PP +.BI "int putgrent(const struct group *" grp ", FILE *" stream ); +.SH DESCRIPTION +The +.BR putgrent () +function is the counterpart for +.BR fgetgrent (3). +The function writes the content of the provided +.IR "struct group" +into the +.IR stream . +The list of group members must be NULL-terminated or NULL-initialized. +.PP +The +.IR "struct group" +is defined as follows: +.PP +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* group members */ +}; +.EE +.in +.SH RETURN VALUE +The function returns zero on success, and a nonzero value on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR putgrent () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +This function is a GNU extension. +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent (3), +.BR group (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/putpwent.3 b/man3/putpwent.3 new file mode 100644 index 0000000..020e69a --- /dev/null +++ b/man3/putpwent.3 @@ -0,0 +1,116 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:43:46 1993 by Rik Faith (faith@cs.unc.edu) +.TH PUTPWENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +putpwent \- write a password file entry +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "int putpwent(const struct passwd *" p ", FILE *" stream ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR putpwent (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +The +.BR putpwent () +function writes a password entry from the +structure \fIp\fP in the file associated with \fIstream\fP. +.PP +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.PP +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR putpwent () +function returns 0 on success, or \-1 if an error +occurs. +In the event of an error, +.I errno +is set to indicate the cause. +.SH ERRORS +.TP +.B EINVAL +Invalid (NULL) argument given. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR putpwent () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +SVr4. +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR setpwent (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/puts.3 b/man3/puts.3 new file mode 100644 index 0000000..03d5930 --- /dev/null +++ b/man3/puts.3 @@ -0,0 +1,148 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 18:42:59 1993 by Rik Faith (faith@cs.unc.edu) +.TH PUTS 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +fputc, fputs, putc, putchar, puts \- output of characters and strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int fputc(int " c ", FILE *" stream ); +.PP +.BI "int fputs(const char *" "s" ", FILE *" "stream" ); +.PP +.BI "int putc(int " c ", FILE *" stream ); +.PP +.BI "int putchar(int " c ); +.PP +.BI "int puts(const char *" "s" ); +.fi +.SH DESCRIPTION +.BR fputc () +writes the character +.IR c , +cast to an +.IR "unsigned char" , +to +.IR stream . +.PP +.BR fputs () +writes the string +.I s +to +.IR stream , +without its terminating null byte (\(aq\e0\(aq). +.PP +.BR putc () +is equivalent to +.BR fputc () +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.PP +.BI "putchar(" c ) +is equivalent to +.BI "putc(" c ", " stdout ). +.PP +.BR puts () +writes the string +.I s +and a trailing newline +to +.IR stdout . +.PP +Calls to the functions described here can be mixed with each other and with +calls to other output functions from the +.I stdio +library for the same output stream. +.PP +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +.BR fputc (), +.BR putc () +and +.BR putchar () +return the character written as an +.I unsigned char +cast to an +.I int +or +.B EOF +on error. +.PP +.BR puts () +and +.BR fputs () +return a nonnegative number on success, or +.B EOF +on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR fputc (), +.BR fputs (), +.BR putc (), +.BR putchar (), +.BR puts () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.SH BUGS +It is not advisable to mix calls to output functions from the +.I stdio +library with low-level calls to +.BR write (2) +for the file descriptor associated with the same output stream; the results +will be undefined and very probably not what you want. +.SH SEE ALSO +.BR write (2), +.BR ferror (3), +.BR fgets (3), +.BR fopen (3), +.BR fputwc (3), +.BR fputws (3), +.BR fseek (3), +.BR fwrite (3), +.BR putwchar (3), +.BR scanf (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/putspent.3 b/man3/putspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/putspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/pututline.3 b/man3/pututline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/pututline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/pututxline.3 b/man3/pututxline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/pututxline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/putw.3 b/man3/putw.3 new file mode 100644 index 0000000..7509345 --- /dev/null +++ b/man3/putw.3 @@ -0,0 +1 @@ +.so man3/getw.3 diff --git a/man3/putwc.3 b/man3/putwc.3 new file mode 100644 index 0000000..81826be --- /dev/null +++ b/man3/putwc.3 @@ -0,0 +1 @@ +.so man3/fputwc.3 diff --git a/man3/putwc_unlocked.3 b/man3/putwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/putwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/putwchar.3 b/man3/putwchar.3 new file mode 100644 index 0000000..f579504 --- /dev/null +++ b/man3/putwchar.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH PUTWCHAR 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +putwchar \- write a wide character to standard output +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wint_t putwchar(wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR putwchar () +function is the wide-character equivalent of the +.BR putchar (3) +function. +It writes the wide character +.I wc +to +.IR stdout . +If +.I ferror(stdout) +becomes true, it returns +.BR WEOF . +If a wide character +conversion error occurs, it sets +.IR errno +to +.B EILSEQ +and returns +.BR WEOF . +Otherwise, it returns +.IR wc . +.PP +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR putwchar () +function returns +.I wc +if no error occurred, or +.B WEOF +to indicate an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR putwchar () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR putwchar () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +It is reasonable to expect that +.BR putwchar () +will actually write +the multibyte sequence corresponding to the wide character +.IR wc . +.SH SEE ALSO +.BR fputwc (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/putwchar_unlocked.3 b/man3/putwchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man3/putwchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man3/pvalloc.3 b/man3/pvalloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man3/pvalloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man3/qecvt.3 b/man3/qecvt.3 new file mode 100644 index 0000000..fe2cfa5 --- /dev/null +++ b/man3/qecvt.3 @@ -0,0 +1,127 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH QECVT 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +qecvt, qfcvt, qgcvt \- convert a floating-point number to a string +.SH SYNOPSIS +.B #include +.PP +.BI "char *qecvt(long double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ); +.PP +.BI "char *qfcvt(long double " number ", int " ndigits ", int *" decpt , +.BI "int *" sign ); +.PP +.BI "char *qgcvt(long double " number ", int " ndigit ", char *" buf ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR qecvt (), +.BR qfcvt (), +.BR qgcvt (): +_SVID_SOURCE +.ad b +.\" FIXME . The full FTM picture looks to have be something like the +.\" following mess: +.\" glibc 2.20 onward +.\" _DEFAULT_SOURCE +.\" glibc 2.18 to glibc 2.19 +.\" _BSD_SOURCE || _SVID_SOURCE +.\" glibc 2.10 to glibc 2.17 +.\" _SVID_SOURCE || (_XOPEN_SOURCE >= 500 || +.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) && +.\" ! (_POSIX_C_SOURCE >= 200809L)) +.\" Before glibc 2.10: +.\" _SVID_SOURCE || _XOPEN_SOURCE >= 500 || +.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.SH DESCRIPTION +The functions +.BR qecvt (), +.BR qfcvt (), +and +.BR qgcvt () +are identical to +.BR ecvt (3), +.BR fcvt (3), +and +.BR gcvt (3) +respectively, except that they use a +.I "long double" +argument +.IR number . +See +.BR ecvt (3) +and +.BR gcvt (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR qecvt () +T} Thread safety MT-Unsafe race:qecvt +T{ +.BR qfcvt () +T} Thread safety MT-Unsafe race:qfcvt +T{ +.BR qgcvt () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +SVr4. +Not seen in most common UNIX implementations, +but occurs in SunOS. +.\" Not supported by libc4 and libc5. +Supported by glibc. +.SH NOTES +These functions are obsolete. +Instead, +.BR snprintf (3) +is recommended. +.SH SEE ALSO +.BR ecvt (3), +.BR ecvt_r (3), +.BR gcvt (3), +.BR sprintf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/qecvt_r.3 b/man3/qecvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man3/qecvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man3/qfcvt.3 b/man3/qfcvt.3 new file mode 100644 index 0000000..7e58310 --- /dev/null +++ b/man3/qfcvt.3 @@ -0,0 +1 @@ +.so man3/qecvt.3 diff --git a/man3/qfcvt_r.3 b/man3/qfcvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man3/qfcvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man3/qgcvt.3 b/man3/qgcvt.3 new file mode 100644 index 0000000..7e58310 --- /dev/null +++ b/man3/qgcvt.3 @@ -0,0 +1 @@ +.so man3/qecvt.3 diff --git a/man3/qsort.3 b/man3/qsort.3 new file mode 100644 index 0000000..8c3095d --- /dev/null +++ b/man3/qsort.3 @@ -0,0 +1,173 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" 2006-01-15, mtk, Added example program. +.\" Modified 2012-03-08, Mark R. Bannister +.\" and Ben Bacarisse +.\" Document qsort_r() +.\" +.TH QSORT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +qsort, qsort_r \- sort an array +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void qsort(void *" base ", size_t " nmemb ", size_t " size , +.BI " int (*" compar ")(const void *, const void *));" +.PP +.BI "void qsort_r(void *" base ", size_t " nmemb ", size_t " size , +.BI " int (*" compar ")(const void *, const void *, void *)," +.BI " void *" arg ");" +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR qsort_r (): +_GNU_SOURCE +.ad b +.SH DESCRIPTION +The +.BR qsort () +function sorts an array with \fInmemb\fP elements of +size \fIsize\fP. +The \fIbase\fP argument points to the start of the +array. +.PP +The contents of the array are sorted in ascending order according to a +comparison function pointed to by \fIcompar\fP, which is called with two +arguments that point to the objects being compared. +.PP +The comparison function must return an integer less than, equal to, or +greater than zero if the first argument is considered to be respectively +less than, equal to, or greater than the second. +If two members compare as equal, +their order in the sorted array is undefined. +.PP +The +.BR qsort_r () +function is identical to +.BR qsort () +except that the comparison function +.I compar +takes a third argument. +A pointer is passed to the comparison function via +.IR arg . +In this way, the comparison function does not need to use global variables to +pass through arbitrary arguments, and is therefore reentrant and safe to +use in threads. +.SH RETURN VALUE +The +.BR qsort () +and +.BR qsort_r () +functions return no value. +.SH VERSIONS +.BR qsort_r () +was added to glibc in version 2.8. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw18 lb lb +l l l. +Interface Attribute Value +T{ +.BR qsort (), +.BR qsort_r () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +.BR qsort (): +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +To compare C strings, the comparison function can call +.BR strcmp (3), +as shown in the example below. +.SH EXAMPLE +For one example of use, see the example under +.BR bsearch (3). +.PP +Another example is the following program, +which sorts the strings given in its command-line arguments: +.PP +.EX +#include +#include +#include + +static int +cmpstringp(const void *p1, const void *p2) +{ + /* The actual arguments to this function are "pointers to + pointers to char", but strcmp(3) arguments are "pointers + to char", hence the following cast plus dereference */ + + return strcmp(* (char * const *) p1, * (char * const *) p2); +} + +int +main(int argc, char *argv[]) +{ + int j; + + if (argc < 2) { + fprintf(stderr, "Usage: %s ...\\n", argv[0]); + exit(EXIT_FAILURE); + } + + qsort(&argv[1], argc \- 1, sizeof(char *), cmpstringp); + + for (j = 1; j < argc; j++) + puts(argv[j]); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR sort (1), +.BR alphasort (3), +.BR strcmp (3), +.BR versionsort (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/qsort_r.3 b/man3/qsort_r.3 new file mode 100644 index 0000000..d073335 --- /dev/null +++ b/man3/qsort_r.3 @@ -0,0 +1 @@ +.so man3/qsort.3 diff --git a/man3/queue.3 b/man3/queue.3 new file mode 100644 index 0000000..8eb84df --- /dev/null +++ b/man3/queue.3 @@ -0,0 +1,1252 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)queue.3 8.2 (Berkeley) 1/24/94 +.\" $FreeBSD$ +.\" +.Dd February 7, 2015 +.Dt QUEUE 3 +.Os +.Sh NAME +.Nm SLIST_EMPTY , +.Nm SLIST_ENTRY , +.Nm SLIST_FIRST , +.Nm SLIST_FOREACH , +.\" .Nm SLIST_FOREACH_FROM , +.\" .Nm SLIST_FOREACH_SAFE , +.\" .Nm SLIST_FOREACH_FROM_SAFE , +.Nm SLIST_HEAD , +.Nm SLIST_HEAD_INITIALIZER , +.Nm SLIST_INIT , +.Nm SLIST_INSERT_AFTER , +.Nm SLIST_INSERT_HEAD , +.Nm SLIST_NEXT , +.\" .Nm SLIST_REMOVE_AFTER , +.Nm SLIST_REMOVE_HEAD , +.Nm SLIST_REMOVE , +.\" .Nm SLIST_SWAP , +.Nm STAILQ_CONCAT , +.Nm STAILQ_EMPTY , +.Nm STAILQ_ENTRY , +.Nm STAILQ_FIRST , +.Nm STAILQ_FOREACH , +.\" .Nm STAILQ_FOREACH_FROM , +.\" .Nm STAILQ_FOREACH_SAFE , +.\" .Nm STAILQ_FOREACH_FROM_SAFE , +.Nm STAILQ_HEAD , +.Nm STAILQ_HEAD_INITIALIZER , +.Nm STAILQ_INIT , +.Nm STAILQ_INSERT_AFTER , +.Nm STAILQ_INSERT_HEAD , +.Nm STAILQ_INSERT_TAIL , +.\" .Nm STAILQ_LAST , +.Nm STAILQ_NEXT , +.\" .Nm STAILQ_REMOVE_AFTER , +.Nm STAILQ_REMOVE_HEAD , +.Nm STAILQ_REMOVE , +.\" .Nm STAILQ_SWAP , +.Nm LIST_EMPTY , +.Nm LIST_ENTRY , +.Nm LIST_FIRST , +.Nm LIST_FOREACH , +.\" .Nm LIST_FOREACH_FROM , +.\" .Nm LIST_FOREACH_SAFE , +.\" .Nm LIST_FOREACH_FROM_SAFE , +.Nm LIST_HEAD , +.Nm LIST_HEAD_INITIALIZER , +.Nm LIST_INIT , +.Nm LIST_INSERT_AFTER , +.Nm LIST_INSERT_BEFORE , +.Nm LIST_INSERT_HEAD , +.Nm LIST_NEXT , +.\" .Nm LIST_PREV , +.Nm LIST_REMOVE , +.\" .Nm LIST_SWAP , +.Nm TAILQ_CONCAT , +.Nm TAILQ_EMPTY , +.Nm TAILQ_ENTRY , +.Nm TAILQ_FIRST , +.Nm TAILQ_FOREACH , +.\" .Nm TAILQ_FOREACH_FROM , +.\" .Nm TAILQ_FOREACH_SAFE , +.\" .Nm TAILQ_FOREACH_FROM_SAFE , +.Nm TAILQ_FOREACH_REVERSE , +.\" .Nm TAILQ_FOREACH_REVERSE_FROM , +.\" .Nm TAILQ_FOREACH_REVERSE_SAFE , +.\" .Nm TAILQ_FOREACH_REVERSE_FROM_SAFE , +.Nm TAILQ_HEAD , +.Nm TAILQ_HEAD_INITIALIZER , +.Nm TAILQ_INIT , +.Nm TAILQ_INSERT_AFTER , +.Nm TAILQ_INSERT_BEFORE , +.Nm TAILQ_INSERT_HEAD , +.Nm TAILQ_INSERT_TAIL , +.Nm TAILQ_LAST , +.Nm TAILQ_NEXT , +.Nm TAILQ_PREV , +.Nm TAILQ_REMOVE , +.Nm TAILQ_SWAP +.Nd implementations of singly-linked lists, singly-linked tail queues, +lists and tail queues +.Sh SYNOPSIS +.In sys/queue.h +.\" +.Fn SLIST_EMPTY "SLIST_HEAD *head" +.Fn SLIST_ENTRY "TYPE" +.Fn SLIST_FIRST "SLIST_HEAD *head" +.Fn SLIST_FOREACH "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.\" .Fn SLIST_FOREACH_FROM "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.\" .Fn SLIST_FOREACH_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" +.\" .Fn SLIST_FOREACH_FROM_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" +.Fn SLIST_HEAD "HEADNAME" "TYPE" +.Fn SLIST_HEAD_INITIALIZER "SLIST_HEAD head" +.Fn SLIST_INIT "SLIST_HEAD *head" +.Fn SLIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_INSERT_HEAD "SLIST_HEAD *head" "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_NEXT "TYPE *elm" "SLIST_ENTRY NAME" +.\" .Fn SLIST_REMOVE_AFTER "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_REMOVE_HEAD "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.Fn SLIST_REMOVE "SLIST_HEAD *head" "TYPE *elm" "TYPE" "SLIST_ENTRY NAME" +.\" .Fn SLIST_SWAP "SLIST_HEAD *head1" "SLIST_HEAD *head2" "SLIST_ENTRY NAME" +.\" +.Fn STAILQ_CONCAT "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" +.Fn STAILQ_EMPTY "STAILQ_HEAD *head" +.Fn STAILQ_ENTRY "TYPE" +.Fn STAILQ_FIRST "STAILQ_HEAD *head" +.Fn STAILQ_FOREACH "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.\" .Fn STAILQ_FOREACH_FROM "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.\" .Fn STAILQ_FOREACH_SAFE "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" "TYPE *temp_var" +.\" .Fn STAILQ_FOREACH_FROM_SAFE "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn STAILQ_HEAD "HEADNAME" "TYPE" +.Fn STAILQ_HEAD_INITIALIZER "STAILQ_HEAD head" +.Fn STAILQ_INIT "STAILQ_HEAD *head" +.Fn STAILQ_INSERT_AFTER "STAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_INSERT_HEAD "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_INSERT_TAIL "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.\" .Fn STAILQ_LAST "STAILQ_HEAD *head" "TYPE" "STAILQ_ENTRY NAME" +.Fn STAILQ_NEXT "TYPE *elm" "STAILQ_ENTRY NAME" +.\" .Fn STAILQ_REMOVE_AFTER "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_REMOVE_HEAD "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.Fn STAILQ_REMOVE "STAILQ_HEAD *head" "TYPE *elm" "TYPE" "STAILQ_ENTRY NAME" +.\" .Fn STAILQ_SWAP "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" "STAILQ_ENTRY NAME" +.\" +.Fn LIST_EMPTY "LIST_HEAD *head" +.Fn LIST_ENTRY "TYPE" +.Fn LIST_FIRST "LIST_HEAD *head" +.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.\" .Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.\" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.\" .Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.Fn LIST_HEAD "HEADNAME" "TYPE" +.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" +.Fn LIST_INIT "LIST_HEAD *head" +.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" +.\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" +.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" +.\" +.Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY NAME" +.Fn TAILQ_EMPTY "TAILQ_HEAD *head" +.Fn TAILQ_ENTRY "TYPE" +.Fn TAILQ_FIRST "TAILQ_HEAD *head" +.Fn TAILQ_FOREACH "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" +.\" .Fn TAILQ_FOREACH_FROM "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" +.\" .Fn TAILQ_FOREACH_SAFE "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.\" .Fn TAILQ_FOREACH_FROM_SAFE "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_FOREACH_REVERSE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" +.\" .Fn TAILQ_FOREACH_REVERSE_FROM "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" +.\" .Fn TAILQ_FOREACH_REVERSE_SAFE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.\" .Fn TAILQ_FOREACH_REVERSE_FROM_SAFE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_HEAD "HEADNAME" "TYPE" +.Fn TAILQ_HEAD_INITIALIZER "TAILQ_HEAD head" +.Fn TAILQ_INIT "TAILQ_HEAD *head" +.Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_HEAD "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_TAIL "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_LAST "TAILQ_HEAD *head" "HEADNAME" +.Fn TAILQ_NEXT "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME" +.Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" "TAILQ_ENTRY NAME" +.\" +.Sh DESCRIPTION +These macros define and operate on four types of data structures: +singly-linked lists, singly-linked tail queues, lists, and tail queues. +All four structures support the following functionality: +.Pp +.Bl -enum -compact -offset indent +.It +Insertion of a new entry at the head of the list. +.It +Insertion of a new entry after any element in the list. +.It +O(1) removal of an entry from the head of the list. +.It +Forward traversal through the list. +.It +Swapping the contents of two lists. +.El +.Pp +Singly-linked lists are the simplest of the four data structures +and support only the above functionality. +Singly-linked lists are ideal for applications with large datasets +and few or no removals, +or for implementing a LIFO queue. +Singly-linked lists add the following functionality: +.Pp +.Bl -enum -compact -offset indent +.It +O(n) removal of any entry in the list. +.El +.Pp +Singly-linked tail queues add the following functionality: +.Pp +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.It +O(n) removal of any entry in the list. +.It +They may be concatenated. +.El +.Pp +However: +.Pp +.Bl -enum -compact -offset indent +.It +All list insertions must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +Code size is about 15% greater and operations run about 20% slower +than singly-linked lists. +.El +.Pp +Singly-linked tail queues are ideal for applications with large datasets and +few or no removals, +or for implementing a FIFO queue. +.Pp +All doubly linked types of data structures (lists and tail queues) +additionally allow: +.Pp +.Bl -enum -compact -offset indent +.It +Insertion of a new entry before any element in the list. +.It +O(1) removal of any entry in the list. +.El +.Pp +However: +.Pp +.Bl -enum -compact -offset indent +.It +Each element requires two pointers rather than one. +.It +Code size and execution time of operations (except for removal) is about +twice that of the singly-linked data-structures. +.El +.Pp +Linked lists are the simplest of the doubly linked data structures. +They add the following functionality over the above: +.Pp +.Bl -enum -compact -offset indent +.It +They may be traversed backwards. +.El +.Pp +However: +.Pp +.Bl -enum -compact -offset indent +.It +To traverse backwards, an entry to begin the traversal and the list in +which it is contained must be specified. +.El +.Pp +Tail queues add the following functionality: +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.It +They may be traversed backwards, from tail to head. +.It +They may be concatenated. +.El +.Pp +However: +.Pp +.Bl -enum -compact -offset indent +.It +All list insertions and removals must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +Code size is about 15% greater and operations run about 20% slower +than singly-linked lists. +.El +.Pp +In the macro definitions, +.Fa TYPE +is the name of a user defined structure, +that must contain a field of type +.Li SLIST_ENTRY , +.Li STAILQ_ENTRY , +.Li LIST_ENTRY , +or +.Li TAILQ_ENTRY , +named +.Fa NAME . +The argument +.Fa HEADNAME +is the name of a user defined structure that must be declared +using the macros +.Li SLIST_HEAD , +.Li STAILQ_HEAD , +.Li LIST_HEAD , +or +.Li TAILQ_HEAD . +See the examples below for further explanation of how these +macros are used. +.Ss Singly-linked lists +A singly-linked list is headed by a structure defined by the +.Nm SLIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are singly linked for minimum space and pointer manipulation +overhead at the expense of O(n) removal for arbitrary elements. +New elements can be added to the list after an existing element or +at the head of the list. +An +.Fa SLIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +SLIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm SLIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Nm SLIST_EMPTY +evaluates to true if there are no elements in the list. +.Pp +The macro +.Nm SLIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm SLIST_FIRST +returns the first element in the list or NULL if the list is empty. +.Pp +The macro +.Nm SLIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in +turn to +.Fa var . +.\" .Pp +.\" The macro +.\" .Nm SLIST_FOREACH_FROM +.\" behaves identically to +.\" .Nm SLIST_FOREACH +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found SLIST element and begins the loop at +.\" .Fa var +.\" instead of the first element in the SLIST referenced by +.\" .Fa head . +.\" .Pp +.\" The macro +.\" .Nm SLIST_FOREACH_SAFE +.\" traverses the list referenced by +.\" .Fa head +.\" in the forward direction, assigning each element in +.\" turn to +.\" .Fa var . +.\" However, unlike +.\" .Fn SLIST_FOREACH +.\" here it is permitted to both remove +.\" .Fa var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .Pp +.\" The macro +.\" .Nm SLIST_FOREACH_FROM_SAFE +.\" behaves identically to +.\" .Nm SLIST_FOREACH_SAFE +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found SLIST element and begins the loop at +.\" .Fa var +.\" instead of the first element in the SLIST referenced by +.\" .Fa head . +.Pp +The macro +.Nm SLIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm SLIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm SLIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm SLIST_NEXT +returns the next element in the list. +.\" .Pp +.\" The macro +.\" .Nm SLIST_REMOVE_AFTER +.\" removes the element after +.\" .Fa elm +.\" from the list. +.\" Unlike +.\" .Fa SLIST_REMOVE , +.\" this macro does not traverse the entire list. +.Pp +The macro +.Nm SLIST_REMOVE_HEAD +removes the element +.Fa elm +from the head of the list. +For optimum efficiency, +elements being removed from the head of the list should explicitly use +this macro instead of the generic +.Fa SLIST_REMOVE +macro. +.Pp +The macro +.Nm SLIST_REMOVE +removes the element +.Fa elm +from the list. +.\" .Pp +.\" The macro +.\" .Nm SLIST_SWAP +.\" swaps the contents of +.\" .Fa head1 +.\" and +.\" .Fa head2 . +.Ss Singly-linked list example +.Bd -literal +SLIST_HEAD(slisthead, entry) head = + SLIST_HEAD_INITIALIZER(head); +struct slisthead *headp; /* Singly-linked List + head. */ +struct entry { + ... + SLIST_ENTRY(entry) entries; /* Singly-linked List. */ + ... +} *n1, *n2, *n3, *np; + +SLIST_INIT(&head); /* Initialize the list. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +SLIST_INSERT_HEAD(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +SLIST_INSERT_AFTER(n1, n2, entries); + +SLIST_REMOVE(&head, n2, entry, entries);/* Deletion. */ +free(n2); + +n3 = SLIST_FIRST(&head); +SLIST_REMOVE_HEAD(&head, entries); /* Deletion from the head. */ +free(n3); + /* Forward traversal. */ +SLIST_FOREACH(np, &head, entries) + np\-> ... +.\" /* Safe forward traversal. */ +.\"SLIST_FOREACH_SAFE(np, &head, entries, np_temp) { +.\" np\->do_stuff(); +.\" ... +.\" SLIST_REMOVE(&head, np, entry, entries); +.\" free(np); +.\"} + +while (!SLIST_EMPTY(&head)) { /* List Deletion. */ + n1 = SLIST_FIRST(&head); + SLIST_REMOVE_HEAD(&head, entries); + free(n1); +} +.Ed +.Ss Singly-linked tail queues +A singly-linked tail queue is headed by a structure defined by the +.Nm STAILQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are singly linked for minimum space and pointer +manipulation overhead at the expense of O(n) removal for arbitrary +elements. +New elements can be added to the tail queue after an existing element, +at the head of the tail queue, or at the end of the tail queue. +A +.Fa STAILQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +STAILQ_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Li HEADNAME +is the name of the structure to be defined, and +.Li TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm STAILQ_HEAD_INITIALIZER +evaluates to an initializer for the tail queue +.Fa head . +.Pp +The macro +.Nm STAILQ_CONCAT +concatenates the tail queue headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +.Pp +The macro +.Nm STAILQ_EMPTY +evaluates to true if there are no items on the tail queue. +.Pp +The macro +.Nm STAILQ_ENTRY +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Nm STAILQ_FIRST +returns the first item on the tail queue or NULL if the tail queue +is empty. +.Pp +The macro +.Nm STAILQ_FOREACH +traverses the tail queue referenced by +.Fa head +in the forward direction, assigning each element +in turn to +.Fa var . +.\" .Pp +.\" The macro +.\" .Nm STAILQ_FOREACH_FROM +.\" behaves identically to +.\" .Nm STAILQ_FOREACH +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found STAILQ element and begins the loop at +.\" .Fa var +.\" instead of the first element in the STAILQ referenced by +.\" .Fa head . +.\" .Pp +.\" The macro +.\" .Nm STAILQ_FOREACH_SAFE +.\" traverses the tail queue referenced by +.\" .Fa head +.\" in the forward direction, assigning each element +.\" in turn to +.\" .Fa var . +.\" However, unlike +.\" .Fn STAILQ_FOREACH +.\" here it is permitted to both remove +.\" .Fa var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .Pp +.\" The macro +.\" .Nm STAILQ_FOREACH_FROM_SAFE +.\" behaves identically to +.\" .Nm STAILQ_FOREACH_SAFE +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found STAILQ element and begins the loop at +.\" .Fa var +.\" instead of the first element in the STAILQ referenced by +.\" .Fa head . +.Pp +The macro +.Nm STAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Nm STAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Nm STAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Nm STAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.\" .Pp +.\" The macro +.\" .Nm STAILQ_LAST +.\" returns the last item on the tail queue. +.\" If the tail queue is empty the return value is +.\" .Dv NULL . +.Pp +The macro +.Nm STAILQ_NEXT +returns the next item on the tail queue, or NULL this item is the last. +.\" .Pp +.\" The macro +.\" .Nm STAILQ_REMOVE_AFTER +.\" removes the element after +.\" .Fa elm +.\" from the tail queue. +.\" Unlike +.\" .Fa STAILQ_REMOVE , +.\" this macro does not traverse the entire tail queue. +.Pp +The macro +.Nm STAILQ_REMOVE_HEAD +removes the element at the head of the tail queue. +For optimum efficiency, +elements being removed from the head of the tail queue should +use this macro explicitly rather than the generic +.Fa STAILQ_REMOVE +macro. +.Pp +The macro +.Nm STAILQ_REMOVE +removes the element +.Fa elm +from the tail queue. +.\" .Pp +.\" The macro +.\" .Nm STAILQ_SWAP +.\" swaps the contents of +.\" .Fa head1 +.\" and +.\" .Fa head2 . +.Ss Singly-linked tail queue example +.Bd -literal +STAILQ_HEAD(stailhead, entry) head = + STAILQ_HEAD_INITIALIZER(head); +struct stailhead *headp; /* Singly-linked tail queue head. */ +struct entry { + ... + STAILQ_ENTRY(entry) entries; /* Tail queue. */ + ... +} *n1, *n2, *n3, *np; + +STAILQ_INIT(&head); /* Initialize the queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +STAILQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +STAILQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +STAILQ_INSERT_AFTER(&head, n1, n2, entries); + /* Deletion. */ +STAILQ_REMOVE(&head, n2, entry, entries); +free(n2); + /* Deletion from the head. */ +n3 = STAILQ_FIRST(&head); +STAILQ_REMOVE_HEAD(&head, entries); +free(n3); + /* Forward traversal. */ +STAILQ_FOREACH(np, &head, entries) + np\-> ... +.\" /* Safe forward traversal. */ +.\"STAILQ_FOREACH_SAFE(np, &head, entries, np_temp) { +.\" np\->do_stuff(); +.\" ... +.\" STAILQ_REMOVE(&head, np, entry, entries); +.\" free(np); +.\"} + /* TailQ Deletion. */ +while (!STAILQ_EMPTY(&head)) { + n1 = STAILQ_FIRST(&head); + STAILQ_REMOVE_HEAD(&head, entries); + free(n1); +} + /* Faster TailQ Deletion. */ +n1 = STAILQ_FIRST(&head); +while (n1 != NULL) { + n2 = STAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; +} +STAILQ_INIT(&head); +.Ed +.Ss Lists +A list is headed by a structure defined by the +.Nm LIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the list. +New elements can be added to the list after an existing element, +before an existing element, or at the head of the list. +A +.Fa LIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +LIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm LIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Nm LIST_EMPTY +evaluates to true if there are no elements in the list. +.Pp +The macro +.Nm LIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm LIST_FIRST +returns the first element in the list or NULL if the list +is empty. +.Pp +The macro +.Nm LIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.\" .Pp +.\" The macro +.\" .Nm LIST_FOREACH_FROM +.\" behaves identically to +.\" .Nm LIST_FOREACH +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found LIST element and begins the loop at +.\" .Fa var +.\" instead of the first element in the LIST referenced by +.\" .Fa head . +.\" .Pp +.\" The macro +.\" .Nm LIST_FOREACH_SAFE +.\" traverses the list referenced by +.\" .Fa head +.\" in the forward direction, assigning each element in turn to +.\" .Fa var . +.\" However, unlike +.\" .Fn LIST_FOREACH +.\" here it is permitted to both remove +.\" .Fa var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .Pp +.\" The macro +.\" .Nm LIST_FOREACH_FROM_SAFE +.\" behaves identically to +.\" .Nm LIST_FOREACH_SAFE +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found LIST element and begins the loop at +.\" .Fa var +.\" instead of the first element in the LIST referenced by +.\" .Fa head . +.Pp +The macro +.Nm LIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm LIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm LIST_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm LIST_NEXT +returns the next element in the list, or NULL if this is the last. +.\" .Pp +.\" The macro +.\" .Nm LIST_PREV +.\" returns the previous element in the list, or NULL if this is the first. +.\" List +.\" .Fa head +.\" must contain element +.\" .Fa elm . +.Pp +The macro +.Nm LIST_REMOVE +removes the element +.Fa elm +from the list. +.\" .Pp +.\" The macro +.\" .Nm LIST_SWAP +.\" swaps the contents of +.\" .Fa head1 +.\" and +.\" .Fa head2 . +.Ss List example +.Bd -literal +LIST_HEAD(listhead, entry) head = + LIST_HEAD_INITIALIZER(head); +struct listhead *headp; /* List head. */ +struct entry { + ... + LIST_ENTRY(entry) entries; /* List. */ + ... +} *n1, *n2, *n3, *np, *np_temp; + +LIST_INIT(&head); /* Initialize the list. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +LIST_INSERT_HEAD(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +LIST_INSERT_AFTER(n1, n2, entries); + +n3 = malloc(sizeof(struct entry)); /* Insert before. */ +LIST_INSERT_BEFORE(n2, n3, entries); + +LIST_REMOVE(n2, entries); /* Deletion. */ +free(n2); + /* Forward traversal. */ +LIST_FOREACH(np, &head, entries) + np\-> ... + +.\" /* Safe forward traversal. */ +.\" LIST_FOREACH_SAFE(np, &head, entries, np_temp) { +.\" np\->do_stuff(); +.\" ... +.\" LIST_REMOVE(np, entries); +.\" free(np); +.\" } +.\" +while (!LIST_EMPTY(&head)) { /* List Deletion. */ + n1 = LIST_FIRST(&head); + LIST_REMOVE(n1, entries); + free(n1); +} + +n1 = LIST_FIRST(&head); /* Faster List Deletion. */ +while (n1 != NULL) { + n2 = LIST_NEXT(n1, entries); + free(n1); + n1 = n2; +} +LIST_INIT(&head); +.Ed +.Ss Tail queues +A tail queue is headed by a structure defined by the +.Nm TAILQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the tail queue. +New elements can be added to the tail queue after an existing element, +before an existing element, at the head of the tail queue, +or at the end of the tail queue. +A +.Fa TAILQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +TAILQ_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Li HEADNAME +is the name of the structure to be defined, and +.Li TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm TAILQ_HEAD_INITIALIZER +evaluates to an initializer for the tail queue +.Fa head . +.Pp +The macro +.Nm TAILQ_CONCAT +concatenates the tail queue headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +.Pp +The macro +.Nm TAILQ_EMPTY +evaluates to true if there are no items on the tail queue. +.Pp +The macro +.Nm TAILQ_ENTRY +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Nm TAILQ_FIRST +returns the first item on the tail queue or NULL if the tail queue +is empty. +.Pp +The macro +.Nm TAILQ_FOREACH +traverses the tail queue referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.Fa var +is set to +.Dv NULL +if the loop completes normally, or if there were no elements. +.\" .Pp +.\" The macro +.\" .Nm TAILQ_FOREACH_FROM +.\" behaves identically to +.\" .Nm TAILQ_FOREACH +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found TAILQ element and begins the loop at +.\" .Fa var +.\" instead of the first element in the TAILQ referenced by +.\" .Fa head . +.Pp +The macro +.Nm TAILQ_FOREACH_REVERSE +traverses the tail queue referenced by +.Fa head +in the reverse direction, assigning each element in turn to +.Fa var . +.\" .Pp +.\" The macro +.\" .Nm TAILQ_FOREACH_REVERSE_FROM +.\" behaves identically to +.\" .Nm TAILQ_FOREACH_REVERSE +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found TAILQ element and begins the reverse loop at +.\" .Fa var +.\" instead of the last element in the TAILQ referenced by +.\" .Fa head . +.\" .Pp +.\" The macros +.\" .Nm TAILQ_FOREACH_SAFE +.\" and +.\" .Nm TAILQ_FOREACH_REVERSE_SAFE +.\" traverse the list referenced by +.\" .Fa head +.\" in the forward or reverse direction respectively, +.\" assigning each element in turn to +.\" .Fa var . +.\" However, unlike their unsafe counterparts, +.\" .Nm TAILQ_FOREACH +.\" and +.\" .Nm TAILQ_FOREACH_REVERSE +.\" permit to both remove +.\" .Fa var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .Pp +.\" The macro +.\" .Nm TAILQ_FOREACH_FROM_SAFE +.\" behaves identically to +.\" .Nm TAILQ_FOREACH_SAFE +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found TAILQ element and begins the loop at +.\" .Fa var +.\" instead of the first element in the TAILQ referenced by +.\" .Fa head . +.\" .Pp +.\" The macro +.\" .Nm TAILQ_FOREACH_REVERSE_FROM_SAFE +.\" behaves identically to +.\" .Nm TAILQ_FOREACH_REVERSE_SAFE +.\" when +.\" .Fa var +.\" is NULL, else it treats +.\" .Fa var +.\" as a previously found TAILQ element and begins the reverse loop at +.\" .Fa var +.\" instead of the last element in the TAILQ referenced by +.\" .Fa head . +.Pp +The macro +.Nm TAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm TAILQ_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm TAILQ_LAST +returns the last item on the tail queue. +If the tail queue is empty the return value is +.Dv NULL . +.Pp +The macro +.Nm TAILQ_NEXT +returns the next item on the tail queue, or NULL if this item is the last. +.Pp +The macro +.Nm TAILQ_PREV +returns the previous item on the tail queue, or NULL if this item +is the first. +.Pp +The macro +.Nm TAILQ_REMOVE +removes the element +.Fa elm +from the tail queue. +.Pp +The macro +.Nm TAILQ_SWAP +swaps the contents of +.Fa head1 +and +.Fa head2 . +.Ss Tail queue example +.Bd -literal +TAILQ_HEAD(tailhead, entry) head = + TAILQ_HEAD_INITIALIZER(head); +struct tailhead *headp; /* Tail queue head. */ +struct entry { + ... + TAILQ_ENTRY(entry) entries; /* Tail queue. */ + ... +} *n1, *n2, *n3, *np; + +TAILQ_INIT(&head); /* Initialize the queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +TAILQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +TAILQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +TAILQ_INSERT_AFTER(&head, n1, n2, entries); + +n3 = malloc(sizeof(struct entry)); /* Insert before. */ +TAILQ_INSERT_BEFORE(n2, n3, entries); + +TAILQ_REMOVE(&head, n2, entries); /* Deletion. */ +free(n2); + /* Forward traversal. */ +TAILQ_FOREACH(np, &head, entries) + np\-> ... +.\" /* Safe forward traversal. */ +.\" TAILQ_FOREACH_SAFE(np, &head, entries, np_temp) { +.\" np\->do_stuff(); +.\" ... +.\" TAILQ_REMOVE(&head, np, entries); +.\" free(np); +.\" } + /* Reverse traversal. */ +TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries) + np\-> ... + /* TailQ Deletion. */ +while (!TAILQ_EMPTY(&head)) { + n1 = TAILQ_FIRST(&head); + TAILQ_REMOVE(&head, n1, entries); + free(n1); +} + /* Faster TailQ Deletion. */ +n1 = TAILQ_FIRST(&head); +while (n1 != NULL) { + n2 = TAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; +} + +TAILQ_INIT(&head); +n2 = malloc(sizeof(struct entry)); /* Insert before. */ +CIRCLEQ_INSERT_BEFORE(&head, n1, n2, entries); + /* Forward traversal. */ +for (np = head.cqh_first; np != (void *)&head; + np = np\->entries.cqe_next) + np\-> ... + /* Reverse traversal. */ +for (np = head.cqh_last; np != (void *)&head; np = np\->entries.cqe_prev) + np\-> ... + /* Delete. */ +while (head.cqh_first != (void *)&head) + CIRCLEQ_REMOVE(&head, head.cqh_first, entries); +.Ed +.Sh CONFORMING TO +Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. +Present on the BSDs. +.Nm queue +functions first appeared in +.Bx 4.4 . +.Sh SEE ALSO +.Xr insque 3 +.\" .Xr tree 3 +.Sh COLOPHON +This page is part of release 4.15 of the Linux +.Em man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/raise.3 b/man3/raise.3 new file mode 100644 index 0000000..e6b2caa --- /dev/null +++ b/man3/raise.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (C) 2008 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 18:40:56 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) +.\" +.TH RAISE 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +raise \- send a signal to the caller +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int raise(int " sig ); +.fi +.SH DESCRIPTION +The +.BR raise () +function sends a signal to the calling process or thread. +In a single-threaded program it is equivalent to +.PP +.in +4n +.EX +kill(getpid(), sig); +.EE +.in +.PP +In a multithreaded program it is equivalent to +.PP +.in +4n +.EX +pthread_kill(pthread_self(), sig); +.EE +.in +.PP +If the signal causes a handler to be called, +.BR raise () +will return only after the signal handler has returned. +.SH RETURN VALUE +.BR raise () +returns 0 on success, and nonzero for failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR raise () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.SH NOTES +Since version 2.3.3, glibc implements +.BR raise () +by calling +.BR tgkill (2), +.\" 2.3.2 used the obsolete tkill(), if available. +if the kernel supports that system call. +Older glibc versions implemented +.BR raise () +using +.BR kill (2). +.SH SEE ALSO +.BR getpid (2), +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR pthread_kill (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rand.3 b/man3/rand.3 new file mode 100644 index 0000000..40a8030 --- /dev/null +++ b/man3/rand.3 @@ -0,0 +1,248 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-04-28, Lars Wirzenius +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-05-18, Rik Faith (faith@cs.unc.edu) to add +.\" better discussion of problems with rand on other systems. +.\" (Thanks to Esa Hyyti{ (ehyytia@snakemail.hut.fi).) +.\" Modified 1998-04-10, Nicolás Lichtmaier +.\" with contribution from Francesco Potorti +.\" Modified 2003-11-15, aeb, added rand_r +.\" 2010-09-13, mtk, added example program +.\" +.TH RAND 3 2017-07-13 "" "Linux Programmer's Manual" +.SH NAME +rand, rand_r, srand \- pseudo-random number generator +.SH SYNOPSIS +.nf +.B #include +.PP +.B int rand(void); +.PP +.BI "int rand_r(unsigned int *" seedp ); +.PP +.BI "void srand(unsigned int " seed ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR rand_r (): +.RS 4 +Since glibc 2.24: + _POSIX_C_SOURCE >= 199506L +.br +Glibc 2.23 and earlier + _POSIX_C_SOURCE +.RE +.SH DESCRIPTION +The +.BR rand () +function returns a pseudo-random integer in the range 0 to +.BR RAND_MAX +inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]). +.PP +The +.BR srand () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR rand (). +These sequences are repeatable by calling +.BR srand () +with the same seed value. +.PP +If no seed value is provided, the +.BR rand () +function is automatically seeded with a value of 1. +.PP +The function +.BR rand () +is not reentrant, since it +uses hidden state that is modified on each call. +This might just be the seed value to be used by the next call, +or it might be something more elaborate. +In order to get reproducible behavior in a threaded +application, this state must be made explicit; +this can be done using the reentrant function +.BR rand_r (). +.PP +Like +.BR rand (), +.BR rand_r () +returns a pseudo-random integer in the range [0,\ \fBRAND_MAX\fR]. +The +.I seedp +argument is a pointer to an +.IR "unsigned int" +that is used to store state between calls. +If +.BR rand_r () +is called with the same initial value for the integer pointed to by +.IR seedp , +and that value is not modified between calls, +then the same pseudo-random sequence will result. +.PP +The value pointed to by the +.I seedp +argument of +.BR rand_r () +provides only a very small amount of state, +so this function will be a weak pseudo-random generator. +Try +.BR drand48_r (3) +instead. +.SH RETURN VALUE +The +.BR rand () +and +.BR rand_r () +functions return a value between 0 and +.BR RAND_MAX +(inclusive). +The +.BR srand () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw25 lb lb +l l l. +Interface Attribute Value +T{ +.BR rand (), +.BR rand_r (), +.BR srand () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The functions +.BR rand () +and +.BR srand () +conform to SVr4, 4.3BSD, C89, C99, POSIX.1-2001. +The function +.BR rand_r () +is from POSIX.1-2001. +POSIX.1-2008 marks +.BR rand_r () +as obsolete. +.SH NOTES +The versions of +.BR rand () +and +.BR srand () +in the Linux C Library use the same random number generator as +.BR random (3) +and +.BR srandom (3), +so the lower-order bits should be as random as the higher-order bits. +However, on older +.BR rand () +implementations, and on current implementations on different systems, +the lower-order bits are much less random than the higher-order bits. +Do not use this function in applications intended to be portable +when good randomness is needed. +(Use +.BR random (3) +instead.) +.SH EXAMPLE +POSIX.1-2001 gives the following example of an implementation of +.BR rand () +and +.BR srand (), +possibly useful when one needs the same sequence on two different machines. +.PP +.in +4n +.EX +static unsigned long next = 1; + +/* RAND_MAX assumed to be 32767 */ +int myrand(void) { + next = next * 1103515245 + 12345; + return((unsigned)(next/65536) % 32768); +} + +void mysrand(unsigned int seed) { + next = seed; +} +.EE +.in +.PP +The following program can be used to display the +pseudo-random sequence produced by +.BR rand () +when given a particular seed. +.PP +.in +4n +.EX +#include +#include + +int +main(int argc, char *argv[]) +{ + int j, r, nloops; + unsigned int seed; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + seed = atoi(argv[1]); + nloops = atoi(argv[2]); + + srand(seed); + for (j = 0; j < nloops; j++) { + r = rand(); + printf("%d\\n", r); + } + + exit(EXIT_SUCCESS); +} +.EE +.in +.SH SEE ALSO +.BR drand48 (3), +.BR random (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rand_r.3 b/man3/rand_r.3 new file mode 100644 index 0000000..b007c2f --- /dev/null +++ b/man3/rand_r.3 @@ -0,0 +1 @@ +.so man3/rand.3 diff --git a/man3/random.3 b/man3/random.3 new file mode 100644 index 0000000..2bf8b67 --- /dev/null +++ b/man3/random.3 @@ -0,0 +1,219 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Mar 28 00:25:51 1993, David Metcalfe +.\" Modified Sat Jul 24 18:13:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 20 21:47:07 2000, aeb +.\" +.TH RANDOM 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +random, srandom, initstate, setstate \- random number generator +.SH SYNOPSIS +.nf +.B #include +.PP +.B long int random(void); +.PP +.BI "void srandom(unsigned int " seed ); +.PP +.BI "char *initstate(unsigned int " seed ", char *" state ", size_t " n ); +.PP +.BI "char *setstate(char *" state ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR random (), +.BR srandom (), +.BR initstate (), +.BR setstate (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR random () +function uses a nonlinear additive feedback random +number generator employing a default table of size 31 long integers to +return successive pseudo-random numbers in +the range from 0 to \fBRAND_MAX\fR. +The period of this random number generator is very large, approximately +.IR "16\ *\ ((2^31)\ \-\ 1)" . +.PP +The +.BR srandom () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR random (). +These sequences are repeatable by calling +.BR srandom () +with the same +seed value. +If no seed value is provided, the +.BR random () +function +is automatically seeded with a value of 1. +.PP +The +.BR initstate () +function allows a state array \fIstate\fP to +be initialized for use by +.BR random (). +The size of the state array +\fIn\fP is used by +.BR initstate () +to decide how sophisticated a +random number generator it should use\(emthe larger the state array, +the better the random numbers will be. +Current "optimal" values for the size of the state array \fIn\fP are +8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to +the nearest known amount. +Using less than 8 bytes results in an error. +\fIseed\fP is the seed for the +initialization, which specifies a starting point for the random number +sequence, and provides for restarting at the same point. +.PP +The +.BR setstate () +function changes the state array used by the +.BR random () +function. +The state array \fIstate\fP is used for +random number generation until the next call to +.BR initstate () +or +.BR setstate (). +\fIstate\fP must first have been initialized +using +.BR initstate () +or be the result of a previous call of +.BR setstate (). +.SH RETURN VALUE +The +.BR random () +function returns a value between 0 and +.BR RAND_MAX . +The +.BR srandom () +function returns no value. +.PP +The +.BR initstate () +function returns a pointer to the previous state array. +On error, +.I errno +is set to indicate the cause. +.PP +On success, +.BR setstate () +returns a pointer to the previous state array. +On error, it returns NULL, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +The +.I state +argument given to +.BR setstate () +was NULL. +.TP +.B EINVAL +A state array of less than 8 bytes was specified to +.BR initstate (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR random (), +.BR srandom (), +.br +.BR initstate (), +.BR setstate () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH NOTES +The +.BR random () +function should not be used in multithreaded programs +where reproducible behavior is required. +Use +.BR random_r (3) +for that purpose. +.PP +Random-number generation is a complex topic. +.I Numerical Recipes in C: The Art of Scientific Computing +(William H. Press, Brian P. Flannery, Saul A. Teukolsky, William +T. Vetterling; New York: Cambridge University Press, 2007, 3rd ed.) +provides an excellent discussion of practical random-number generation +issues in Chapter 7 (Random Numbers). +.PP +For a more theoretical discussion which also covers many practical issues +in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth's +.IR "The Art of Computer Programming" , +volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts: +Addison-Wesley Publishing Company, 1981. +.SH BUGS +According to POSIX, +.BR initstate () +should return NULL on error. +In the glibc implementation, +.I errno +is (as specified) set on error, but the function does not return NULL. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=15380 +.SH SEE ALSO +.BR getrandom (2), +.BR drand48 (3), +.BR rand (3), +.BR random_r (3), +.BR srand (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/random_r.3 b/man3/random_r.3 new file mode 100644 index 0000000..9577ac2 --- /dev/null +++ b/man3/random_r.3 @@ -0,0 +1,201 @@ +.\" Copyright 2008 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH RANDOM_R 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +random_r, srandom_r, initstate_r, setstate_r \- reentrant +random number generator +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int random_r(struct random_data *" buf ", int32_t *" result ); +.PP +.BI "int srandom_r(unsigned int " seed ", struct random_data *" buf ); +.PP +.BI "int initstate_r(unsigned int " seed ", char *" statebuf , +.BI " size_t " statelen ", struct random_data *" buf ); +.PP +.BI "int setstate_r(char *" statebuf ", struct random_data *" buf ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR random_r (), +.BR srandom_r (), +.BR initstate_r (), +.BR setstate_r (): +.RS 4 +/* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions are the reentrant equivalents +of the functions described in +.BR random (3). +They are suitable for use in multithreaded programs where each thread +needs to obtain an independent, reproducible sequence of random numbers. +.PP +The +.BR random_r () +function is like +.BR random (3), +except that instead of using state information maintained +in a global variable, +it uses the state information in the argument pointed to by +.IR buf , +which must have been previously initialized by +.BR initstate_r (). +The generated random number is returned in the argument +.IR result . +.PP +The +.BR srandom_r () +function is like +.BR srandom (3), +except that it initializes the seed for the random number generator +whose state is maintained in the object pointed to by +.IR buf , +which must have been previously initialized by +.BR initstate_r (), +instead of the seed associated with the global state variable. +.PP +The +.BR initstate_r () +function is like +.BR initstate (3) +except that it initializes the state in the object pointed to by +.IR buf , +rather than initializing the global state variable. +Before calling this function, the +.IR buf.state +field must be initialized to NULL. +The +.BR initstate_r () +function records a pointer to the +.I statebuf +argument inside the structure pointed to by +.IR buf . +Thus, +.IR statebuf +should not be deallocated so long as +.IR buf +is still in use. +(So, +.I statebuf +should typically be allocated as a static variable, +or allocated on the heap using +.BR malloc (3) +or similar.) +.PP +The +.BR setstate_r () +function is like +.BR setstate (3) +except that it modifies the state in the object pointed to by +.IR buf , +rather than modifying the global state variable. +\fIstate\fP must first have been initialized +using +.BR initstate_r () +or be the result of a previous call of +.BR setstate_r (). +.SH RETURN VALUE +All of these functions return 0 on success. +On error, \-1 is returned, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +A state array of less than 8 bytes was specified to +.BR initstate_r (). +.TP +.B EINVAL +The +.I statebuf +or +.I buf +argument to +.BR setstate_r () +was NULL. +.TP +.B EINVAL +The +.I buf +or +.I result +argument to +.BR random_r () +was NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR random_r (), +.BR srandom_r (), +.br +.BR initstate_r (), +.BR setstate_r () +T} Thread safety MT-Safe race:buf +.TE +.SH CONFORMING TO +These functions are nonstandard glibc extensions. +.\" These functions appear to be on Tru64, but don't seem to be on +.\" Solaris, HP-UX, or FreeBSD. +.SH BUGS +The +.BR initstate_r () +interface is confusing. +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=3662 +It appears that the +.IR random_data +type is intended to be opaque, +but the implementation requires the user to either initialize the +.I buf.state +field to NULL or zero out the entire structure before the call. +.SH SEE ALSO +.BR drand48 (3), +.BR rand (3), +.BR random (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rawmemchr.3 b/man3/rawmemchr.3 new file mode 100644 index 0000000..b62c8f1 --- /dev/null +++ b/man3/rawmemchr.3 @@ -0,0 +1 @@ +.so man3/memchr.3 diff --git a/man3/rcmd.3 b/man3/rcmd.3 new file mode 100644 index 0000000..2d10b30 --- /dev/null +++ b/man3/rcmd.3 @@ -0,0 +1,331 @@ +.\" $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 +.\" +.\" Contributed as Linux man page by David A. Holland, 970908 +.\" I have not checked whether the Linux situation is exactly the same. +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH RCMD 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +rcmd, rresvport, iruserok, ruserok, rcmd_af, +rresvport_af, iruserok_af, ruserok_af \- routines for returning a +stream to a remote command +.SH SYNOPSIS +.nf +.B #include \ \ \fP/* Or on some systems */ +.PP +.BI "int rcmd(char **" ahost ", unsigned short " inport ", const char *" locuser ", " +.BI " const char *" remuser ", const char *" cmd ", int *" fd2p ); +.PP +.BI "int rresvport(int *" port ); +.PP +.BI "int iruserok(uint32_t " raddr ", int " superuser ", " +.BI " const char *" ruser ", const char *" luser ); +.PP +.BI "int ruserok(const char *" rhost ", int " superuser ", " +.BI " const char *" ruser ", const char *" luser ); +.PP +.BI "int rcmd_af(char **" ahost ", unsigned short " inport ", const char *" locuser ", " +.BI " const char *" remuser ", const char *" cmd ", int *" fd2p , +.BI " sa_family_t " af ); +.PP +.BI "int rresvport_af(int *" port ", sa_family_t " af ); +.PP +.BI "int iruserok_af(const void *" raddr ", int " superuser ", " +.BI " const char *" ruser ", const char *" luser \ +", sa_family_t " af ); +.PP +.BI "int ruserok_af(const char *" rhost ", int " superuser ", " +.BI " const char *" ruser ", const char *" luser \ +", sa_family_t " af ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR rcmd (), +.BR rcmd_af (), +.BR rresvport (), +.BR rresvport_af (), +.BR iruserok (), +.BR iruserok_af (), +.BR ruserok (), +.BR ruserok_af (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The +.BR rcmd () +function is used by the superuser to execute a command on +a remote machine using an authentication scheme based +on privileged port numbers. +The +.BR rresvport () +function +returns a file descriptor to a socket +with an address in the privileged port space. +The +.BR iruserok () +and +.BR ruserok () +functions are used by servers +to authenticate clients requesting service with +.BR rcmd (). +All four functions are used by the +.BR rshd (8) +server (among others). +.SS rcmd() +.PP +The +.BR rcmd () +function +looks up the host +.I *ahost +using +.BR gethostbyname (3), +returning \-1 if the host does not exist. +Otherwise, +.I *ahost +is set to the standard name of the host +and a connection is established to a server +residing at the well-known Internet port +.IR inport . +.PP +If the connection succeeds, +a socket in the Internet domain of type +.BR SOCK_STREAM +is returned to the caller, and given to the remote +command as +.IR stdin +and +.IR stdout . +If +.I fd2p +is nonzero, then an auxiliary channel to a control +process will be set up, and a file descriptor for it will be placed +in +.IR *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being UNIX signal numbers, to be +forwarded to the process group of the command. +If +.I fd2p +is 0, then the +.IR stderr +(unit 2 of the remote +command) will be made the same as the +.IR stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.PP +The protocol is described in detail in +.BR rshd (8). +.SS rresvport() +.PP +The +.BR rresvport () +function is used to obtain a socket with a privileged +port bound to it. +This socket is suitable for use by +.BR rcmd () +and several other functions. +Privileged ports are those in the range 0 to 1023. +Only a privileged process +(on Linux: a process that has the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace). +is allowed to bind to a privileged port. +In the glibc implementation, +this function restricts its search to the ports from 512 to 1023. +The +.I port +argument is value-result: +the value it supplies to the call is used as the starting point +for a circular search of the port range; +on (successful) return, it contains the port number that was bound to. +.\" +.SS iruserok() and ruserok() +.PP +The +.BR iruserok () +and +.BR ruserok () +functions take a remote host's IP address or name, respectively, +two usernames and a flag indicating whether the local user's +name is that of the superuser. +Then, if the user is +.I not +the superuser, it checks the +.IR /etc/hosts.equiv +file. +If that lookup is not done, or is unsuccessful, the +.IR .rhosts +in the local user's home directory is checked to see if the request for +service is allowed. +.PP +If this file does not exist, is not a regular file, is owned by anyone +other than the user or the superuser, is writable by anyone other +than the owner, or is hardlinked anywhere, the check automatically fails. +Zero is returned if the machine name is listed in the +.IR hosts.equiv +file, or the host and remote username are found in the +.IR .rhosts +file; otherwise +.BR iruserok () +and +.BR ruserok () +return \-1. +If the local domain (as obtained from +.BR gethostname (2)) +is the same as the remote domain, only the machine name need be specified. +.PP +If the IP address of the remote host is known, +.BR iruserok () +should be used in preference to +.BR ruserok (), +as it does not require trusting the DNS server for the remote host's domain. +.SS *_af() variants +All of the functions described above work with IPv4 +.RB ( AF_INET ) +sockets. +The "_af" variants take an extra argument that allows the +socket address family to be specified. +For these functions, the +.I af +argument can be specified as +.BR AF_INET +or +.BR AF_INET6 . +In addition, +.BR rcmd_af () +supports the use of +.BR AF_UNSPEC . +.SH RETURN VALUE +The +.BR rcmd () +function +returns a valid socket descriptor on success. +It returns \-1 on error and prints a diagnostic message on the standard error. +.PP +The +.BR rresvport () +function +returns a valid, bound socket descriptor on success. +It returns \-1 on error with the global value +.I errno +set according to the reason for failure. +The error code +.BR EAGAIN +is overloaded to mean "All network ports in use." +.PP +For information on the return from +.BR ruserok () +and +.BR iruserok (), +see above. +.SH VERSIONS +The functions +.BR iruserok_af (), +.BR rcmd_af (), +.BR rresvport_af (), +and +.BR ruserok_af () +functions are provide in glibc since version 2.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR rcmd (), +.BR rcmd_af () +T} Thread safety MT-Unsafe +T{ +.BR rresvport (), +.BR rresvport_af () +T} Thread safety MT-Safe +T{ +.BR iruserok (), +.BR ruserok (), +.br +.BR iruserok_af (), +.BR ruserok_af () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +Not in POSIX.1. +Present on the BSDs, Solaris, and many other systems. +These +functions appeared in +4.2BSD. +The "_af" variants are more recent additions, +and are not present on as wide a range of systems. +.SH BUGS +.BR iruserok () +and +.BR iruserok_af () +are declared in glibc headers only since version 2.12. +.\" Bug filed 25 Nov 2007: +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=5399 +.SH SEE ALSO +.BR rlogin (1), +.BR rsh (1), +.BR intro (2), +.BR rexec (3), +.BR rexecd (8), +.BR rlogind (8), +.BR rshd (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rcmd_af.3 b/man3/rcmd_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man3/rcmd_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/re_comp.3 b/man3/re_comp.3 new file mode 100644 index 0000000..df3cd1c --- /dev/null +++ b/man3/re_comp.3 @@ -0,0 +1,97 @@ +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@@ee.surrey.ac.uk) +.\" +.TH RE_COMP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +re_comp, re_exec \- BSD regex functions +.SH SYNOPSIS +.B #define _REGEX_RE_COMP +.br +.B #include +.br +.B #include +.PP +.BI "char *re_comp(const char *" regex ); +.PP +.BI "int re_exec(const char *" string ); +.SH DESCRIPTION +.BR re_comp () +is used to compile the null-terminated regular expression pointed to by +.IR regex . +The compiled pattern occupies a static area, the pattern buffer, +which is overwritten by subsequent use of +.BR re_comp (). +If +.I regex +is NULL, +no operation is performed and the pattern buffer's contents are not +altered. +.PP +.BR re_exec () +is used to assess whether the null-terminated string pointed to by +.I string +matches the previously compiled +.IR regex . +.SH RETURN VALUE +.BR re_comp () +returns NULL on successful compilation of +.I regex +otherwise it returns a pointer to an appropriate error message. +.PP +.BR re_exec () +returns 1 for a successful match, zero for failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR re_comp (), +.BR re_exec () +T} Thread safety MT-Unsafe +.TE +.SH CONFORMING TO +4.3BSD. +.SH NOTES +These functions are obsolete; the functions documented in +.BR regcomp (3) +should be used instead. +.SH SEE ALSO +.BR regcomp (3), +.BR regex (7), +GNU regex manual +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/re_exec.3 b/man3/re_exec.3 new file mode 100644 index 0000000..36aba39 --- /dev/null +++ b/man3/re_exec.3 @@ -0,0 +1 @@ +.so man3/re_comp.3 diff --git a/man3/readdir.3 b/man3/readdir.3 new file mode 100644 index 0000000..9f618bf --- /dev/null +++ b/man3/readdir.3 @@ -0,0 +1,322 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2008, 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-07-30 Ulrich Drepper , mtk: +.\" Rework discussion of nonstandard structure fields. +.\" +.TH READDIR 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +readdir \- read a directory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "struct dirent *readdir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR readdir () +function returns a pointer to a \fIdirent\fP structure +representing the next directory entry in the directory stream pointed +to by \fIdirp\fP. +It returns NULL on reaching the end of the directory stream or if +an error occurred. +.PP +In the glibc implementation, the +.I dirent +structure is defined as follows: +.PP +.in +4n +.EX +struct dirent { + ino_t d_ino; /* Inode number */ + off_t d_off; /* Not an offset; see below */ + unsigned short d_reclen; /* Length of this record */ + unsigned char d_type; /* Type of file; not supported + by all filesystem types */ + char d_name[256]; /* Null-terminated filename */ +}; +.EE +.in +.PP +The only fields in the +.I dirent +structure that are mandated by POSIX.1 are +.IR d_name +and +.IR d_ino . +The other fields are unstandardized, and not present on all systems; +see NOTES below for some further details. +.PP +The fields of the +.I dirent +structure are as follows: +.TP +.I d_ino +This is the inode number of the file. +.TP +.I d_off +The value returned in +.I d_off +is the same as would be returned by calling +.BR telldir (3) +at the current position in the directory stream. +Be aware that despite its type and name, the +.I d_off +field is seldom any kind of directory offset on modern filesystems. +.\" https://lwn.net/Articles/544298/ +Applications should treat this field as an opaque value, +making no assumptions about its contents; see also +.BR telldir (3). +.TP +.I d_reclen +This is the size (in bytes) of the returned record. +This may not match the size of the structure definition shown above; +see NOTES. +.TP +.I d_type +This field contains a value indicating the file type, +making it possible to avoid the expense of calling +.BR lstat (2) +if further actions depend on the type of the file. +.IP +When a suitable feature test macro is defined +.RB ( _DEFAULT_SOURCE +on glibc versions since 2.19, or +.BR _BSD_SOURCE +on glibc versions 2.19 and earlier), +glibc defines the following macro constants for the value returned in +.IR d_type : +.RS +.TP 12 +.B DT_BLK +This is a block device. +.TP +.B DT_CHR +This is a character device. +.TP +.B DT_DIR +This is a directory. +.TP +.B DT_FIFO +This is a named pipe (FIFO). +.TP +.B DT_LNK +This is a symbolic link. +.TP +.B DT_REG +This is a regular file. +.TP +.B DT_SOCK +This is a UNIX domain socket. +.TP +.B DT_UNKNOWN +The file type could not be determined. +.RE +.IP +Currently, +.\" kernel 2.6.27 +.\" The same sentence is in getdents.2 +only some filesystems (among them: Btrfs, ext2, ext3, and ext4) +have full support for returning the file type in +.IR d_type . +All applications must properly handle a return of +.BR DT_UNKNOWN . +.TP +.I d_name +This field contains the null terminated filename. +.IR "See NOTES" . +.PP +The data returned by +.BR readdir () +may be overwritten by subsequent calls to +.BR readdir () +for the same directory stream. +.SH RETURN VALUE +On success, +.BR readdir () +returns a pointer to a +.I dirent +structure. +(This structure may be statically allocated; do not attempt to +.BR free (3) +it.) +.PP +If the end of the directory stream is reached, NULL is returned and +.I errno +is not changed. +If an error occurs, NULL is returned and +.I errno +is set appropriately. +To distinguish end of stream and from an error, set +.I errno +to zero before calling +.BR readdir () +and then check the value of +.I errno +if NULL is returned. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR readdir () +T} Thread safety MT-Unsafe race:dirstream +.TE +.sp 1 +.PP +In the current POSIX.1 specification (POSIX.1-2008), +.BR readdir () +is not required to be thread-safe. +However, in modern implementations (including the glibc implementation), +concurrent calls to +.BR readdir () +that specify different directory streams are thread-safe. +In cases where multiple threads must read from the same directory stream, +using +.BR readdir () +with external synchronization is still preferable to the use of the deprecated +.BR readdir_r (3) +function. +It is expected that a future version of POSIX.1 +.\" FIXME . +.\" http://www.austingroupbugs.net/view.php?id=696 +will require that +.BR readdir () +be thread-safe when concurrently employed on different directory streams. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +A directory stream is opened using +.BR opendir (3). +.PP +The order in which filenames are read by successive calls to +.BR readdir () +depends on the filesystem implementation; +it is unlikely that the names will be sorted in any fashion. +.PP +Only the fields +.I d_name +and (as an XSI extension) +.I d_ino +are specified in POSIX.1. +.\" POSIX.1-2001, POSIX.1-2008 +Other than Linux, the +.I d_type +field is available mainly only on BSD systems. +The remaining fields are available on many, but not all systems. +Under glibc, +programs can check for the availability of the fields not defined +in POSIX.1 by testing whether the macros +.BR _DIRENT_HAVE_D_NAMLEN , +.BR _DIRENT_HAVE_D_RECLEN , +.BR _DIRENT_HAVE_D_OFF , +or +.B _DIRENT_HAVE_D_TYPE +are defined. +.\" +.SS The d_name field +The +.I dirent +structure definition shown above is taken from the glibc headers, +and shows the +.I d_name +field with a fixed size. +.PP +.IR Warning : +applications should avoid any dependence on the size of the +.I d_name +field. +POSIX defines it as +.IR "char\ d_name[]", +a character array of unspecified size, with at most +.B NAME_MAX +characters preceding the terminating null byte (\(aq\\0\(aq). +.PP +POSIX.1 explicitly notes that this field should not be used as an lvalue. +The standard also notes that the use of +.I sizeof(d_name) +is incorrect; use +.IR strlen(d_name) +instead. +(On some systems, this field is defined as +.IR char\ d_name[1] !) +By implication, the use +.IR "sizeof(struct dirent)" +to capture the size of the record including the size of +.IR d_name +is also incorrect. +.PP +Note that while the call +.PP + fpathconf(fd, _PC_NAME_MAX) +.PP +returns the value 255 for most filesystems, +on some filesystems (e.g., CIFS, Windows SMB servers), +the null-terminated filename that is (correctly) returned in +.I d_name +can actually exceed this size. +In such cases, the +.I d_reclen +field will contain a value that exceeds the size of the glibc +.I dirent +structure shown above. +.SH SEE ALSO +.BR getdents (2), +.BR read (2), +.BR closedir (3), +.BR dirfd (3), +.BR ftw (3), +.BR offsetof (3), +.BR opendir (3), +.BR readdir_r (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/readdir_r.3 b/man3/readdir_r.3 new file mode 100644 index 0000000..65ac75d --- /dev/null +++ b/man3/readdir_r.3 @@ -0,0 +1,167 @@ +.\" Copyright (C) 2008, 2016 Michael Kerrisk +.\" and Copyright (C) 2016 Florian Weimer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH READDIR_R 3 2016-03-01 "" "Linux Programmer's Manual" +.SH NAME +readdir_r \- read a directory +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int readdir_r(DIR *" dirp ", struct dirent *" entry \ +", struct dirent **" result ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR readdir_r (): +.RS 4 +_POSIX_C_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +This function is deprecated; use +.BR readdir (3) +instead. +.PP +The +.BR readdir_r () +function was invented as a reentrant version of +.BR readdir (3). +It reads the next directory entry from the directory stream +.IR dirp , +and returns it in the caller-allocated buffer pointed to by +.IR entry . +For details of the +.IR dirent +structure, see +.BR readdir (3). +.PP +A pointer to the returned buffer is placed in +.IR *result ; +if the end of the directory stream was encountered, +then NULL is instead returned in +.IR *result . +.PP +It is recommended that applications use +.BR readdir (3) +instead of +.BR readdir_r (). +Furthermore, since version 2.24, glibc deprecates +.BR readdir_r (). +The reasons are as follows: +.IP * 3 +On systems where +.BR NAME_MAX +is undefined, calling +.BR readdir_r () +may be unsafe because the interface does not allow the caller to specify +the length of the buffer used for the returned directory entry. +.IP * +On some systems, +.BR readdir_r () +can't read directory entries with very long names. +When the glibc implementation encounters such a name, +.BR readdir_r () +fails with the error +.B ENAMETOOLONG +.IR "after the final directory entry has been read" . +On some other systems, +.BR readdir_r () +may return a success status, but the returned +.IR d_name +field may not be null terminated or may be truncated. +.IP * +In the current POSIX.1 specification (POSIX.1-2008), +.BR readdir (3) +is not required to be thread-safe. +However, in modern implementations (including the glibc implementation), +concurrent calls to +.BR readdir (3) +that specify different directory streams are thread-safe. +Therefore, the use of +.BR readdir_r () +is generally unnecessary in multithreaded programs. +In cases where multiple threads must read from the same directory stream, +using +.BR readdir (3) +with external synchronization is still preferable to the use of +.BR readdir_r (), +for the reasons given in the points above. +.IP * +It is expected that a future version of POSIX.1 +.\" FIXME . +.\" http://www.austingroupbugs.net/view.php?id=696 +will make +.BR readdir_r () +obsolete, and require that +.BR readdir (3) +be thread-safe when concurrently employed on different directory streams. +.SH RETURN VALUE +The +.BR readdir_r () +function returns 0 on success. +On error, it returns a positive error number (listed under ERRORS). +If the end of the directory stream is reached, +.BR readdir_r () +returns 0, and returns NULL in +.IR *result . +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.TP +.B ENAMETOOLONG +A directory entry whose name was too long to be read was encountered. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR readdir_r () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR readdir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/realloc.3 b/man3/realloc.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man3/realloc.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man3/realpath.3 b/man3/realpath.3 new file mode 100644 index 0000000..4e040ab --- /dev/null +++ b/man3/realpath.3 @@ -0,0 +1,256 @@ +.\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Rewritten old page, 990824, aeb@cwi.nl +.\" 2004-12-14, mtk, added discussion of resolved_path == NULL +.\" +.TH REALPATH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +realpath \- return the canonicalized absolute pathname +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "char *realpath(const char *" path ", char *" resolved_path ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR realpath (): +.ad l +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.ad +.SH DESCRIPTION +.BR realpath () +expands all symbolic links and resolves references +to +.IR "/./" ", " "/../" +and extra \(aq/\(aq +characters in the null-terminated string named by +.I path +to produce a canonicalized absolute pathname. +The resulting pathname is stored as a null-terminated string, +up to a maximum of +.B PATH_MAX +bytes, +in the buffer pointed to by +.IR resolved_path . +The resulting path will have no symbolic link, +.I "/./" +or +.I "/../" +components. +.PP +If +.I resolved_path +is specified as NULL, then +.BR realpath () +uses +.BR malloc (3) +to allocate a buffer of up to +.B PATH_MAX +bytes to hold the resolved pathname, +and returns a pointer to this buffer. +The caller should deallocate this buffer using +.BR free (3). +.\" Even if we use resolved_path == NULL, then realpath() will still +.\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX +.\" bytes -- MTK, Dec 04 +.\" .SH HISTORY +.\" The +.\" .BR realpath () +.\" function first appeared in 4.4BSD, contributed by Jan-Simon Pendry. +.SH RETURN VALUE +If there is no error, +.BR realpath () +returns a pointer to the +.IR resolved_path . +.PP +Otherwise, it returns NULL, the contents +of the array +.I resolved_path +are undefined, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Read or search permission was denied for a component of the path prefix. +.TP +.B EINVAL +.I path +is NULL. +.\" (In libc5 this would just cause a segfault.) +(In glibc versions before 2.3, +this error is also returned if +.IR resolved_path +is NULL.) +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a pathname exceeded +.B NAME_MAX +characters, or an entire pathname exceeded +.B PATH_MAX +characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR realpath () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.4BSD, POSIX.1-2001. +.PP +POSIX.1-2001 says that the behavior if +.I resolved_path +is NULL is implementation-defined. +POSIX.1-2008 specifies the behavior described in this page. +.SH NOTES +In 4.4BSD and Solaris, the limit on the pathname length is +.B MAXPATHLEN +(found in \fI\fP). +SUSv2 prescribes +.B PATH_MAX +and +.BR NAME_MAX , +as found in \fI\fP or provided by the +.BR pathconf (3) +function. +A typical source fragment would be +.PP +.in +4n +.EX +#ifdef PATH_MAX + path_max = PATH_MAX; +#else + path_max = pathconf(path, _PC_PATH_MAX); + if (path_max <= 0) + path_max = 4096; +#endif +.EE +.in +.PP +(But see the BUGS section.) +.PP +.\" 2012-05-05, According to Casper Dik, the statement about +.\" Solaris was not true at least as far back as 1997, and +.\" may never have been true. +.\" +.\" The 4.4BSD, Linux and SUSv2 versions always return an absolute +.\" pathname. +.\" Solaris may return a relative pathname when the +.\" .I path +.\" argument is relative. +.\" The prototype of +.\" .BR realpath () +.\" is given in \fI\fP in libc4 and libc5, +.\" but in \fI\fP everywhere else. +.SS GNU extensions +If the call fails with either +.BR EACCES +or +.BR ENOENT +and +.I resolved_path +is not NULL, then the prefix of +.I path +that is not readable or does not exist is returned in +.IR resolved_path . +.SH BUGS +The POSIX.1-2001 standard version of this function is broken by design, +since it is impossible to determine a suitable size for the output buffer, +.IR resolved_path . +According to POSIX.1-2001 a buffer of size +.B PATH_MAX +suffices, but +.B PATH_MAX +need not be a defined constant, and may have to be obtained using +.BR pathconf (3). +And asking +.BR pathconf (3) +does not really help, since, on the one hand POSIX warns that +the result of +.BR pathconf (3) +may be huge and unsuitable for mallocing memory, +and on the other hand +.BR pathconf (3) +may return \-1 to signify that +.B PATH_MAX +is not bounded. +The +.I "resolved_path\ ==\ NULL" +feature, not standardized in POSIX.1-2001, +but standardized in POSIX.1-2008, allows this design problem to be avoided. +.\" .LP +.\" The libc4 and libc5 implementation contained a buffer overflow +.\" (fixed in libc-5.4.13). +.\" Thus, set-user-ID programs like +.\" .BR mount (8) +.\" needed a private version. +.SH SEE ALSO +.BR realpath (1), +.BR readlink (2), +.BR canonicalize_file_name (3), +.BR getcwd (3), +.BR pathconf (3), +.BR sysconf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/recno.3 b/man3/recno.3 new file mode 100644 index 0000000..680ffb5 --- /dev/null +++ b/man3/recno.3 @@ -0,0 +1,241 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)recno.3 8.5 (Berkeley) 8/18/94 +.\" +.TH RECNO 3 2017-09-15 "" "Linux Programmer's Manual" +.UC 7 +.SH NAME +recno \- record number database access method +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided in glibc up until version 2.1. +Since version 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.PP +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is record number files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the recno-specific information. +.PP +The record number data structure is either variable or fixed-length +records stored in a flat-file format, accessed by the logical record +number. +The existence of record number five implies the existence of records +one through four, and the deletion of record number one causes +record number five to be renumbered to record number four, as well +as the cursor, if positioned after record number one, to shift down +one record. +.PP +The recno access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I +include file as follows: +.PP +.in +4n +.EX +typedef struct { + unsigned long flags; + unsigned int cachesize; + unsigned int psize; + int lorder; + size_t reclen; + unsigned char bval; + char *bfname; +} RECNOINFO; +.EE +.in +.PP +The elements of this structure are defined as follows: +.TP +.I flags +The flag value is specified by ORing +any of the following values: +.RS +.TP +.B R_FIXEDLEN +The records are fixed-length, not byte delimited. +The structure element +.I reclen +specifies the length of the record, and the structure element +.I bval +is used as the pad character. +Any records, inserted into the database, that are less than +.I reclen +bytes long are automatically padded. +.TP +.B R_NOKEY +In the interface specified by +.BR dbopen (3), +the sequential record retrieval fills in both the caller's key and +data structures. +If the +.B R_NOKEY +flag is specified, the +.I cursor +routines are not required to fill in the key structure. +This permits applications to retrieve records at the end of files without +reading all of the intervening records. +.TP +.B R_SNAPSHOT +This flag requires that a snapshot of the file be taken when +.BR dbopen (3) +is called, instead of permitting any unmodified records to be read from +the original file. +.RE +.TP +.I cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.B only +advisory, and the access method will allocate more memory rather than fail. +If +.I cachesize +is 0 (no size is specified), a default cache is used. +.TP +.I psize +The recno access method stores the in-memory copies of its records +in a btree. +This value is the size (in bytes) of the pages used for nodes in that tree. +If +.I psize +is 0 (no page size is specified), a page size is chosen based on the +underlying filesystem I/O block size. +See +.BR btree (3) +for more information. +.TP +.I lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +.TP +.I reclen +The length of a fixed-length record. +.TP +.I bval +The delimiting byte to be used to mark the end of a record for +variable-length records, and the pad character for fixed-length +records. +If no value is specified, newlines ("\en") are used to mark the end +of variable-length records and fixed-length records are padded with +spaces. +.TP +.I bfname +The recno access method stores the in-memory copies of its records +in a btree. +If +.I bfname +is non-NULL, it specifies the name of the btree file, +as if specified as the filename for a +.BR dbopen (3) +of a btree file. +.PP +The data part of the key/data pair used by the +.I recno +access method +is the same as other access methods. +The key is different. +The +.I data +field of the key should be a pointer to a memory location of type +.IR recno_t , +as defined in the +.I +include file. +This type is normally the largest unsigned integral type available to +the implementation. +The +.I size +field of the key should be the size of that type. +.PP +Because there can be no metadata associated with the underlying +recno access method files, any changes made to the default values +(e.g., fixed record length or byte separator value) must be explicitly +specified each time the file is opened. +.PP +In the interface specified by +.BR dbopen (3), +using the +.I put +interface to create a new record will cause the creation of multiple, +empty records if the record number is more than one greater than the +largest record currently in the database. +.SH ERRORS +The +.I recno +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3) +or the following: +.TP +.B EINVAL +An attempt was made to add a record to a fixed-length database that +was too large to fit. +.SH BUGS +Only big and little endian byte order is supported. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR hash (3), +.BR mpool (3) +.PP +.IR "Document Processing in a Relational Database System" , +Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman, +Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/regcomp.3 b/man3/regcomp.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man3/regcomp.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man3/regerror.3 b/man3/regerror.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man3/regerror.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man3/regex.3 b/man3/regex.3 new file mode 100644 index 0000000..b022c4c --- /dev/null +++ b/man3/regex.3 @@ -0,0 +1,339 @@ +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" Tiny change in formatting - aeb, 950812 +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" +.\" show the synopsis section nicely +.TH REGEX 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +regcomp, regexec, regerror, regfree \- POSIX regex functions +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int regcomp(regex_t *" preg ", const char *" regex ", int " cflags ); +.PP +.BI "int regexec(const regex_t *" preg ", const char *" string \ +", size_t " nmatch , +.BI " regmatch_t " pmatch[] ", int " eflags ); +.PP +.BI "size_t regerror(int " errcode ", const regex_t *" preg ", char *" errbuf , +.BI " size_t " errbuf_size ); +.PP +.BI "void regfree(regex_t *" preg ); +.fi +.SH DESCRIPTION +.SS POSIX regex compiling +.BR regcomp () +is used to compile a regular expression into a form that is suitable +for subsequent +.BR regexec () +searches. +.PP +.BR regcomp () +is supplied with +.IR preg , +a pointer to a pattern buffer storage area; +.IR regex , +a pointer to the null-terminated string and +.IR cflags , +flags used to determine the type of compilation. +.PP +All regular expression searching must be done via a compiled pattern +buffer, thus +.BR regexec () +must always be supplied with the address of a +.BR regcomp () +initialized pattern buffer. +.PP +.I cflags +may be the +.RB bitwise- or +of zero or more of the following: +.TP +.B REG_EXTENDED +Use +.B POSIX +Extended Regular Expression syntax when interpreting +.IR regex . +If not set, +.B POSIX +Basic Regular Expression syntax is used. +.TP +.B REG_ICASE +Do not differentiate case. +Subsequent +.BR regexec () +searches using this pattern buffer will be case insensitive. +.TP +.B REG_NOSUB +Do not report position of matches. +The +.I nmatch +and +.I pmatch +arguments to +.BR regexec () +are ignored if the pattern buffer supplied was compiled with this flag set. +.TP +.B REG_NEWLINE +Match-any-character operators don't match a newline. +.IP +A nonmatching list +.RB ( [^...] ) +not containing a newline does not match a newline. +.IP +Match-beginning-of-line operator +.RB ( ^ ) +matches the empty string immediately after a newline, regardless of +whether +.IR eflags , +the execution flags of +.BR regexec (), +contains +.BR REG_NOTBOL . +.IP +Match-end-of-line operator +.RB ( $ ) +matches the empty string immediately before a newline, regardless of +whether +.I eflags +contains +.BR REG_NOTEOL . +.SS POSIX regex matching +.BR regexec () +is used to match a null-terminated string +against the precompiled pattern buffer, +.IR preg . +.I nmatch +and +.I pmatch +are used to provide information regarding the location of any matches. +.I eflags +may be the +.RB bitwise- or +of one or both of +.B REG_NOTBOL +and +.B REG_NOTEOL +which cause changes in matching behavior described below. +.TP +.B REG_NOTBOL +The match-beginning-of-line operator always fails to match (but see the +compilation flag +.B REG_NEWLINE +above). +This flag may be used when different portions of a string are passed to +.BR regexec () +and the beginning of the string should not be interpreted as the +beginning of the line. +.TP +.B REG_NOTEOL +The match-end-of-line operator always fails to match (but see the +compilation flag +.B REG_NEWLINE +above). +.SS Byte offsets +Unless +.B REG_NOSUB +was set for the compilation of the pattern buffer, it is possible to +obtain match addressing information. +.I pmatch +must be dimensioned to have at least +.I nmatch +elements. +These are filled in by +.BR regexec () +with substring match addresses. +The offsets of the subexpression starting at the +.IR i th +open parenthesis are stored in +.IR pmatch[i] . +The entire regular expression's match addresses are stored in +.IR pmatch[0] . +(Note that to return the offsets of +.I N +subexpression matches, +.I nmatch +must be at least +.IR N+1 .) +Any unused structure elements will contain the value \-1. +.PP +The +.I regmatch_t +structure which is the type of +.I pmatch +is defined in +.IR . +.PP +.in +4n +.EX +typedef struct { + regoff_t rm_so; + regoff_t rm_eo; +} regmatch_t; +.EE +.in +.PP +Each +.I rm_so +element that is not \-1 indicates the start offset of the next largest +substring match within the string. +The relative +.I rm_eo +element indicates the end offset of the match, +which is the offset of the first character after the matching text. +.SS POSIX error reporting +.BR regerror () +is used to turn the error codes that can be returned by both +.BR regcomp () +and +.BR regexec () +into error message strings. +.PP +.BR regerror () +is passed the error code, +.IR errcode , +the pattern buffer, +.IR preg , +a pointer to a character string buffer, +.IR errbuf , +and the size of the string buffer, +.IR errbuf_size . +It returns the size of the +.I errbuf +required to contain the null-terminated error message string. +If both +.I errbuf +and +.I errbuf_size +are nonzero, +.I errbuf +is filled in with the first +.I "errbuf_size \- 1" +characters of the error message and a terminating null byte (\(aq\\0\(aq). +.SS POSIX pattern buffer freeing +Supplying +.BR regfree () +with a precompiled pattern buffer, +.I preg +will free the memory allocated to the pattern buffer by the compiling +process, +.BR regcomp (). +.SH RETURN VALUE +.BR regcomp () +returns zero for a successful compilation or an error code for failure. +.PP +.BR regexec () +returns zero for a successful match or +.B REG_NOMATCH +for failure. +.SH ERRORS +The following errors can be returned by +.BR regcomp (): +.TP +.B REG_BADBR +Invalid use of back reference operator. +.TP +.B REG_BADPAT +Invalid use of pattern operators such as group or list. +.TP +.B REG_BADRPT +Invalid use of repetition operators such as using \(aq*\(aq +as the first character. +.TP +.B REG_EBRACE +Un-matched brace interval operators. +.TP +.B REG_EBRACK +Un-matched bracket list operators. +.TP +.B REG_ECOLLATE +Invalid collating element. +.TP +.B REG_ECTYPE +Unknown character class name. +.TP +.B REG_EEND +Nonspecific error. +This is not defined by POSIX.2. +.TP +.B REG_EESCAPE +Trailing backslash. +.TP +.B REG_EPAREN +Un-matched parenthesis group operators. +.TP +.B REG_ERANGE +Invalid use of the range operator; for example, the ending point of the range +occurs prior to the starting point. +.TP +.B REG_ESIZE +Compiled regular expression requires a pattern buffer larger than 64\ kB. +This is not defined by POSIX.2. +.TP +.B REG_ESPACE +The regex routines ran out of memory. +.TP +.B REG_ESUBREG +Invalid back reference to a subexpression. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR regcomp (), +.BR regexec () +T} Thread safety MT-Safe locale +T{ +.BR regerror () +T} Thread safety MT-Safe env +T{ +.BR regfree () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR grep (1), +.BR regex (7) +.PP +The glibc manual section, +.I "Regular Expressions" +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/regexec.3 b/man3/regexec.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man3/regexec.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man3/regfree.3 b/man3/regfree.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man3/regfree.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man3/registerrpc.3 b/man3/registerrpc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/registerrpc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/remainder.3 b/man3/remainder.3 new file mode 100644 index 0000000..f2d8f43 --- /dev/null +++ b/man3/remainder.3 @@ -0,0 +1,252 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" Modified 2003-11-18, 2004-10-05 aeb +.\" +.TH REMAINDER 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +drem, dremf, dreml, remainder, remainderf, remainderl \- \ +floating-point remainder function +.SH SYNOPSIS +.nf +.B #include +.PP +/* The C99 versions */ +.BI "double remainder(double " x ", double " y ); +.BI "float remainderf(float " x ", float " y ); +.BI "long double remainderl(long double " x ", long double " y ); +.PP +/* Obsolete synonyms */ +.BI "double drem(double " x ", double " y ); +.BI "float dremf(float " x ", float " y ); +.BI "long double dreml(long double " x ", long double " y ); +.PP +.fi +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR remainder (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR remainderf (), +.BR remainderl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR drem (), +.BR dremf (), +.BR dreml (): +.RS 4 +/* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These +functions compute the remainder of dividing +.I x +by +.IR y . +The return value is +\fIx\fP\-\fIn\fP*\fIy\fP, +where +.I n +is the value +.IR "x\ /\ y" , +rounded to the nearest integer. +If the absolute value of +\fIx\fP\-\fIn\fP*\fIy\fP +is 0.5, +.I n +is chosen to be even. +.PP +These functions are unaffected by the current rounding mode (see +.BR fenv (3)). +.PP +The +.BR drem () +function does precisely the same thing. +.SH RETURN VALUE +On success, these +functions return the floating-point remainder, +\fIx\fP\-\fIn\fP*\fIy\fP. +If the return value is 0, it has the sign of +.IR x . +.PP +If +.I x +or +.I y +is a NaN, a NaN is returned. +.PP +If +.I x +is an infinity, +and +.I y +is not a NaN, +a domain error occurs, and +a NaN is returned. +.PP +If +.I y +is zero, +.\" FIXME . Instead, glibc gives a domain error even if x is a NaN +and +.I x +is not a NaN, +.\" Interestingly, remquo(3) does not have the same problem. +a domain error occurs, and +a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN +.I errno +is set to +.BR EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.IP +These functions do not set +.IR errno +for this case. +.TP +Domain error: \fIy\fP is zero\" [XXX see bug above] and \fIx\fP is not a NaN +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw26 lb lb +l l l. +Interface Attribute Value +T{ +.BR drem (), +.BR dremf (), +.BR dreml (), +.br +.BR remainder (), +.BR remainderf (), +.br +.BR remainderl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.\" IEC 60559. +The functions +.BR remainder (), +.BR remainderf (), +and +.BR remainderl () +are specified in C99, POSIX.1-2001, and POSIX.1-2008. +.PP +The function +.BR drem () +is from 4.3BSD. +The +.I float +and +.I "long double" +variants +.BR dremf () +and +.BR dreml () +exist on some systems, such as Tru64 and glibc2. +Avoid the use of these functions in favor of +.BR remainder () +etc. +.SH BUGS +Before glibc 2.15, +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6779 +the call +.PP + remainder(nan(""), 0); +.PP +returned a NaN, as expected, but wrongly caused a domain error. +Since glibc 2.15, a silent NaN (i.e., no domain error) is returned. +.PP +Before glibc 2.15, +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783 +.I errno +was not set to +.BR EDOM +for the domain error that occurs when +.I x +is an infinity and +.I y +is not a NaN. +.I errno was not set +.SH EXAMPLE +The call "remainder(29.0, 3.0)" returns \-1. +.SH SEE ALSO +.BR div (3), +.BR fmod (3), +.BR remquo (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/remainderf.3 b/man3/remainderf.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man3/remainderf.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/remainderl.3 b/man3/remainderl.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man3/remainderl.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man3/remove.3 b/man3/remove.3 new file mode 100644 index 0000000..45dcec7 --- /dev/null +++ b/man3/remove.3 @@ -0,0 +1,112 @@ +.\" This file is derived from unlink.2, which has the following copyright: +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Ian Jackson. +.\" +.\" Edited into remove.3 shape by: +.\" Graeme W. Wilford (G.Wilford@ee.surrey.ac.uk) on 13th July 1994 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH REMOVE 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +remove \- remove a file or directory +.SH SYNOPSIS +.B #include +.PP +.BI "int remove(const char *" pathname ); +.SH DESCRIPTION +.BR remove () +deletes a name from the filesystem. +It calls +.BR unlink (2) +for files, and +.BR rmdir (2) +for directories. +.PP +If the removed name was the +last link to a file and no processes have the file open, the file is +deleted and the space it was using is made available for reuse. +.PP +If the name was the last link to a file, +but any processes still have the file open, +the file will remain in existence until the last file +descriptor referring to it is closed. +.PP +If the name referred to a symbolic link, the link is removed. +.PP +If the name referred to a socket, FIFO, or device, the name is removed, +but processes which have the object open may continue to use it. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +The errors that occur are those for +.BR unlink (2) +and +.BR rmdir (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR remove () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, 4.3BSD. +.\" .SH NOTES +.\" Under libc4 and libc5, +.\" .BR remove () +.\" was an alias for +.\" .BR unlink (2) +.\" (and hence would not remove directories). +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of files which are still being used. +.SH SEE ALSO +.BR rm (1), +.BR unlink (1), +.BR link (2), +.BR mknod (2), +.BR open (2), +.BR rename (2), +.BR rmdir (2), +.BR unlink (2), +.BR mkfifo (3), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/remque.3 b/man3/remque.3 new file mode 100644 index 0000000..a0c8836 --- /dev/null +++ b/man3/remque.3 @@ -0,0 +1 @@ +.so man3/insque.3 diff --git a/man3/remquo.3 b/man3/remquo.3 new file mode 100644 index 0000000..db87d66 --- /dev/null +++ b/man3/remquo.3 @@ -0,0 +1,146 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" based on glibc infopages +.\" polished, aeb +.\" +.TH REMQUO 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +remquo, remquof, remquol \- remainder and part of quotient +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double remquo(double " x ", double " y ", int *" quo ); +.BI "float remquof(float " x ", float " y ", int *" quo ); +.BI "long double remquol(long double " x ", long double " y ", int *" quo ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR remquo (), +.BR remquof (), +.BR remquol (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions compute the remainder and part of the quotient +upon division of +.I x +by +.IR y . +A few bits of the quotient are stored via the +.I quo +pointer. +The remainder is returned as the function result. +.PP +The value of the remainder is the same as that computed by the +.BR remainder (3) +function. +.PP +The value stored via the +.I quo +pointer has the sign of +.IR "x\ /\ y" +and agrees with the quotient in at least the low order 3 bits. +.PP +For example, \fIremquo(29.0,\ 3.0)\fP returns \-1.0 and might store 2. +Note that the actual quotient might not fit in an integer. +.\" A possible application of this function might be the computation +.\" of sin(x). Compute remquo(x, pi/2, &quo) or so. +.\" +.\" glibc, UnixWare: return 3 bits +.\" MacOS 10: return 7 bits +.SH RETURN VALUE +On success, these functions return the same value as +the analogous functions described in +.BR remainder (3). +.PP +If +.I x +or +.I y +is a NaN, a NaN is returned. +.PP +If +.I x +is an infinity, +and +.I y +is not a NaN, +a domain error occurs, and +a NaN is returned. +.PP +If +.I y +is zero, +and +.I x +is not a NaN, +a domain error occurs, and +a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity or \fIy\fP is 0, \ +and the other argument is not a NaN +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6802 +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR remquo (), +.BR remquof (), +.BR remquol () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR fmod (3), +.BR logb (3), +.BR remainder (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/remquof.3 b/man3/remquof.3 new file mode 100644 index 0000000..458f051 --- /dev/null +++ b/man3/remquof.3 @@ -0,0 +1 @@ +.so man3/remquo.3 diff --git a/man3/remquol.3 b/man3/remquol.3 new file mode 100644 index 0000000..458f051 --- /dev/null +++ b/man3/remquol.3 @@ -0,0 +1 @@ +.so man3/remquo.3 diff --git a/man3/res_init.3 b/man3/res_init.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_init.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_mkquery.3 b/man3/res_mkquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_mkquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_ninit.3 b/man3/res_ninit.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_ninit.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_nmkquery.3 b/man3/res_nmkquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_nmkquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_nquery.3 b/man3/res_nquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_nquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_nquerydomain.3 b/man3/res_nquerydomain.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_nquerydomain.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_nsearch.3 b/man3/res_nsearch.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_nsearch.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_nsend.3 b/man3/res_nsend.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_nsend.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_query.3 b/man3/res_query.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_query.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_querydomain.3 b/man3/res_querydomain.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_querydomain.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_search.3 b/man3/res_search.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_search.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/res_send.3 b/man3/res_send.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man3/res_send.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man3/resolver.3 b/man3/resolver.3 new file mode 100644 index 0000000..6c3ebe3 --- /dev/null +++ b/man3/resolver.3 @@ -0,0 +1,504 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and (C) Copyright 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2004-10-31 by aeb +.\" +.TH RESOLVER 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend, +res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, +dn_comp, dn_expand \- resolver routines +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.B struct __res_state; +.B typedef struct __res_state *res_state; +.PP +.BI "int res_ninit(res_state " statep ); +.PP +.BI "int res_nquery(res_state " statep , +.BI " const char *" dname ", int " class ", int " type , +.BI " unsigned char *" answer ", int " anslen ); +.PP +.BI "int res_nsearch(res_state " statep , +.BI " const char *" dname ", int " class ", int " type , +.BI " unsigned char *" answer ", int " anslen ); +.PP +.BI "int res_nquerydomain(res_state " statep , +.BI " const char *" name ", const char *" domain , +.BI " int " class ", int " type ", unsigned char *" answer , +.BI " int " anslen ); +.PP +.BI "int res_nmkquery(res_state " statep , +.BI " int " op ", const char *" dname ", int " class , +.BI " int " type ", const unsigned char *" data ", int " datalen , +.BI " const unsigned char *" newrr , +.BI " unsigned char *" buf ", int " buflen ); +.PP +.BI "int res_nsend(res_state " statep , +.BI " const unsigned char *" msg ", int " msglen , +.BI " unsigned char *" answer ", int " anslen ); +.PP +.BI "int dn_comp(const char *" exp_dn ", unsigned char *" comp_dn , +.BI " int " length ", unsigned char **" dnptrs , +.BI " unsigned char **" lastdnptr ); +.PP +.BI "int dn_expand(const unsigned char *" msg , +.BI " const unsigned char *" eomorig , +.BI " const unsigned char *" comp_dn ", char *" exp_dn , +.BI " int " length ); +.fi +.\" +.SS Deprecated +.nf +.B extern struct __res_state _res; +.PP +.B int res_init(void); +.PP +.BI "int res_query(const char *" dname ", int " class ", int " type , +.BI " unsigned char *" answer ", int " anslen ); +.PP +.BI "int res_search(const char *" dname ", int " class ", int " type , +.BI " unsigned char *" answer ", int " anslen ); +.PP +.BI "int res_querydomain(const char *" name ", const char *" domain , +.BI " int " class ", int " type ", unsigned char *" answer , +.BI " int " anslen ); +.PP +.BI "int res_mkquery(int " op ", const char *" dname ", int " class , +.BI " int " type ", const unsigned char *" data ", int " datalen , +.BI " const unsigned char *" newrr , +.BI " unsigned char *" buf ", int " buflen ); +.PP +.BI "int res_send(const unsigned char *" msg ", int " msglen , +.BI " unsigned char *" answer ", int " anslen ); +.fi +.PP +Link with \fI\-lresolv\fP. +.SH DESCRIPTION +.B Note: +This page is incomplete (various resolver functions provided by glibc +are not described) and likely out of date. +.PP +The functions described below make queries to and interpret +the responses from Internet domain name servers. +.PP +The API consists of a set of more modern, reentrant functions +and an older set of nonreentrant functions that have been superseded. +The traditional resolver interfaces such as +.BR res_init () +and +.BR res_query () +use some static (global) state stored in the +.I _res +structure, rendering these functions non-thread-safe. +BIND 8.2 introduced a set of new interfaces +.BR res_ninit (), +.BR res_nquery (), +and so on, which take a +.I res_state +as their first argument, so you can use a per-thread resolver state. +.PP +The +.BR res_ninit () +and +.BR res_init () +functions read the configuration files (see +.BR resolv.conf (5)) +to get the default domain name and name +server address(es). +If no server is given, the local host is tried. +If no domain is given, that associated with the local host is used. +It can be overridden with the environment variable +.BR LOCALDOMAIN . +.BR res_ninit () +or +.BR res_init () +is normally executed by the first call to one of the +other functions. +.PP +The +.BR res_nquery () +and +.BR res_query () +functions query the name server for the +fully qualified domain name \fIname\fP of specified \fItype\fP and +\fIclass\fP. +The reply is left in the buffer \fIanswer\fP of length +\fIanslen\fP supplied by the caller. +.PP +The +.BR res_nsearch () +and +.BR res_search () +functions make a query and waits for the response like +.BR res_nquery () +and +.BR res_query (), +but in addition they implement the default and search +rules controlled by +.B RES_DEFNAMES +and +.B RES_DNSRCH +(see description of +\fI_res\fP options below). +.PP +The +.BR res_nquerydomain () +and +.BR res_querydomain () +functions make a query using +.BR res_nquery ()/ res_query () +on the concatenation of \fIname\fP and \fIdomain\fP. +.PP +The following functions are lower-level routines used by +.BR res_query ()/ res_query (). +.PP +The +.BR res_nmkquery () +and +.BR res_mkquery () +functions construct a query message in \fIbuf\fP +of length \fIbuflen\fP for the domain name \fIdname\fP. +The query type +\fIop\fP is one of the following (typically +.BR QUERY ): +.TP +.B QUERY +Standard query. +.TP +.B IQUERY +Inverse query. +This option was removed in glibc 2.26, +.\" commit e4e794841e3140875f2aa86b90e2ada3d61e1244 +since it has not been supported by DNS servers for a very long time. +.TP +.B NS_NOTIFY_OP +Notify secondary of SOA (Start of Authority) change. +.PP +\fInewrr\fP is currently unused. +.PP +The +.BR res_nsend () +and +.BR res_send () +function send a preformatted query given in +\fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP +which is of length \fIanslen\fP. +They will call +.BR res_ninit ()/ res_init () +if it has not already been called. +.PP +The +.BR dn_comp () +function compresses the domain name \fIexp_dn\fP +and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP. +The compression uses an array of pointers \fIdnptrs\fP to previously +compressed names in the current message. +The first pointer points +to the beginning of the message and the list ends with NULL. +The limit of the array is specified by \fIlastdnptr\fP. +If \fIdnptr\fP is NULL, domain names are not compressed. +If \fIlastdnptr\fP is NULL, the list +of labels is not updated. +.PP +The +.BR dn_expand () +function expands the compressed domain name +\fIcomp_dn\fP to a full domain name, which is placed in the buffer +\fIexp_dn\fP of size \fIlength\fP. +The compressed name is contained +in a query or reply message, and \fImsg\fP points to the beginning of +the message. +.PP +The resolver routines use configuration and state information +contained in a +.IR __res_state +structure (either passed as the +.IR statep +argument, or in the global variable +.IR _res , +in the case of the older nonreentrant functions). +The only field of this structure that is normally manipulated by the +user is the +.IR options +field. +This field can contain the bitwise "OR" +of the following options: +.TP +.B RES_INIT +True if +.BR res_ninit () +or +.BR res_init () +has been called. +.TP +.B RES_DEBUG +Print debugging messages. +This option is available only if glibc was built with debugging enabled, +.\" See resolv/README. +.\" Support for RES_DEBUG was made conditional in glibc 2.2. +which is not the default. +.TP +.BR RES_AAONLY " (unimplemented; deprecated in glibc 2.25)" +Accept authoritative answers only. +.BR res_send () +continues until +it finds an authoritative answer or returns an error. +This option was present but unimplemented in glibc until version 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_USEVC +Use TCP connections for queries rather than UDP datagrams. +.TP +.BR RES_PRIMARY " (unimplemented; deprecated in glibc 2.25)" +Query primary domain name server only. +This option was present but unimplemented in glibc until version 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_IGNTC +Ignore truncation errors. +Don't retry with TCP. +.TP +.B RES_RECURSE +Set the recursion desired bit in queries. +Recursion is carried out +by the domain name server, not by +.BR res_send (). +[Enabled by default]. +.TP +.B RES_DEFNAMES +If set, +.BR res_search () +will append the default domain name to +single component names\(emthat is, those that do not contain a dot. +[Enabled by default]. +.TP +.B RES_STAYOPEN +Used with +.B RES_USEVC +to keep the TCP connection open between queries. +.TP +.B RES_DNSRCH +If set, +.BR res_search () +will search for hostnames in the current +domain and in parent domains. +This option is used by +.BR gethostbyname (3). +[Enabled by default]. +.TP +.B RES_INSECURE1 +Accept a response from a wrong server. +This can be used to detect potential security hazards, +but you need to compile glibc with debugging enabled and use +.B RES_DEBUG +option (for debug purpose only). +.TP +.B RES_INSECURE2 +Accept a response which contains a wrong query. +This can be used to detect potential security hazards, +but you need to compile glibc with debugging enabled and use +.B RES_DEBUG +option (for debug purpose only). +.TP +.B RES_NOALIASES +Disable usage of +.B HOSTALIASES +environment variable. +.TP +.B RES_USE_INET6 +Try an AAAA query before an A query inside the +.BR gethostbyname (3) +function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records +are found but an A record set exists. +Since glibc 2.25, this option is deprecated, +and its usage produces a warning; +applications should use +.BR getaddrinfo (3), +rather than +.BR gethostbyname (3). +.TP +.B RES_ROTATE +Causes round-robin selection of name servers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every +time. +.TP +.BR RES_NOCHECKNAME " (unimplemented; deprecated in glibc 2.25)" +Disable the modern BIND checking of incoming hostnames and mail names +for invalid characters such as underscore (_), non-ASCII, +or control characters. +This option was present in glibc until version 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_KEEPTSIG " (unimplemented; deprecated in glibc 2.25)" +Do not strip TSIG records. +This option was present but unimplemented in glibc until version 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_BLAST " (unimplemented; deprecated in glibc 2.25)" +Send each query simultaneously and recursively to all servers. +This option was present but unimplemented in glibc until version 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_USEBSTRING " (glibc 2.3.4 to 2.24)" +Make reverse IPv6 lookups using the bit-label format described in RFC 2673; +if this option is not set (which is the default), then nibble format is used. +This option was removed in glibc 2.25, +since it relied on a backward-incompatible +DNS extension that was never deployed on the Internet. +.TP +.BR RES_NOIP6DOTINT " (glibc 2.24 and earlier)" +Use +.I ip6.arpa +zone in IPv6 reverse lookup instead of +.IR ip6.int , +which is deprecated since glibc 2.3.4. +This option is present in glibc up to and including version 2.24, +where it is enabled by default. +In glibc 2.25, this option was removed. +.TP +.BR RES_USE_EDNS0 " (since glibc 2.6)" +Enables support for the DNS extensions (EDNS0) described in RFC 2671. +.TP +.BR RES_SNGLKUP " (since glibc 2.10)" +By default, glibc performs IPv4 and IPv6 lookups in parallel since +version 2.9. +Some appliance DNS servers cannot handle these queries properly +and make the requests time out. +This option disables the behavior and makes glibc +perform the IPv6 and IPv4 requests sequentially +(at the cost of some slowdown of the resolving process). +.TP +.B RES_SNGLKUPREOP +When +.B RES_SNGLKUP +option is enabled, opens a new socket for the each request. +.TP +.B RES_USE_DNSSEC +Use DNSSEC with OK bit in OPT record. +This option implies +.BR RES_USE_EDNS0 . +.TP +.B RES_NOTLDQUERY +Do not look up unqualified name as a top-level domain (TLD). +.TP +.B RES_DEFAULT +Default option which implies: +.BR RES_RECURSE , +.BR RES_DEFNAMES , +.BR RES_DNSRCH +and +.BR RES_NOIP6DOTINT . +.\" +.SH RETURN VALUE +The +.BR res_ninit () +and +.BR res_init () +functions return 0 on success, or \-1 if an error +occurs. +.PP +The +.BR res_nquery (), +.BR res_query (), +.BR res_nsearch (), +.BR res_search (), +.BR res_nquerydomain (), +.BR res_querydomain (), +.BR res_nmkquery (), +.BR res_mkquery (), +.BR res_nsend (), +and +.BR res_send () +functions return the length +of the response, or \-1 if an error occurs. +.PP +The +.BR dn_comp () +and +.BR dn_expand () +functions return the length +of the compressed name, or \-1 if an error occurs. +.SH FILES +.TP +.I /etc/resolv.conf +resolver configuration file +.TP +.I /etc/host.conf +resolver configuration file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw34 lb lb +l l l. +Interface Attribute Value +T{ +.BR res_ninit (), +.BR res_nquery (), +.br +.BR res_nsearch (), +.BR res_nquerydomain (), +.BR res_nsend () +T} Thread safety MT-Safe locale +T{ +.BR res_nmkquery (), +.BR dn_comp (), +.br +.BR dn_expand () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +4.3BSD. +.SH SEE ALSO +.BR gethostbyname (3), +.BR resolv.conf (5), +.BR resolver (5), +.BR hostname (7), +.BR named (8) +.PP +The GNU C library source file +.IR resolv/README . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rewind.3 b/man3/rewind.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man3/rewind.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man3/rewinddir.3 b/man3/rewinddir.3 new file mode 100644 index 0000000..9cd9d0f --- /dev/null +++ b/man3/rewinddir.3 @@ -0,0 +1,82 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:29:11 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH REWINDDIR 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +rewinddir \- reset directory stream +.SH SYNOPSIS +.nf +.B #include +.PP +.B #include +.PP +.BI "void rewinddir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR rewinddir () +function resets the position of the directory +stream +.I dirp +to the beginning of the directory. +.SH RETURN VALUE +The +.BR rewinddir () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR rewinddir () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH SEE ALSO +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rexec.3 b/man3/rexec.3 new file mode 100644 index 0000000..7f1801e --- /dev/null +++ b/man3/rexec.3 @@ -0,0 +1,192 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)rexec.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD: src/lib/libcompat/4.3/rexec.3,v 1.12 2004/07/02 23:52:14 ru Exp $ +.\" +.\" Taken from FreeBSD 5.4; not checked against Linux reality (mtk) +.\" +.\" 2013-06-21, mtk, Converted from mdoc to man macros +.\" +.TH REXEC 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +rexec, rexec_af \- return stream to a remote command +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int rexec(char **" ahost ", int " inport ", const char *" user ", " +.BI " const char *" passwd ", const char *" cmd ", int *" fd2p ); +.PP +.BI "int rexec_af(char **" ahost ", int " inport ", const char *" user ", " +.BI " const char *" passwd ", const char *" cmd ", int *" fd2p , +.BI " sa_family_t " af ); +.fi +.PP +.BR rexec (), +.BR rexec_af (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.SH DESCRIPTION +This interface is obsoleted by +.BR rcmd (3). +.PP +The +.BR rexec () +function +looks up the host +.IR *ahost +using +.BR gethostbyname (3), +returning \-1 if the host does not exist. +Otherwise, +.IR *ahost +is set to the standard name of the host. +If a username and password are both specified, then these +are used to authenticate to the foreign host; otherwise +the environment and then the +.I .netrc +file in user's +home directory are searched for appropriate information. +If all this fails, the user is prompted for the information. +.PP +The port +.I inport +specifies which well-known DARPA Internet port to use for +the connection; the call +.I "getservbyname(""exec"", ""tcp"")" +(see +.BR getservent (3)) +will return a pointer to a structure that contains the necessary port. +The protocol for connection is described in detail in +.BR rexecd (8). +.PP +If the connection succeeds, +a socket in the Internet domain of type +.BR SOCK_STREAM +is returned to +the caller, and given to the remote command as +.IR stdin +and +.IR stdout . +If +.I fd2p +is nonzero, then an auxiliary channel to a control +process will be setup, and a file descriptor for it will be placed +in +.IR *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being UNIX signal numbers, to be +forwarded to the process group of the command. +The diagnostic +information returned does not include remote authorization failure, +as the secondary connection is set up after authorization has been +verified. +If +.I fd2p +is 0, then the +.IR stderr +(unit 2 of the remote +command) will be made the same as the +.IR stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.SS rexec_af() +The +.BR rexec () +function works over IPv4 +.RB ( AF_INET ). +By contrast, the +.BR rexec_af () +function provides an extra argument, +.IR af , +that allows the caller to select the protocol. +This argument can be specified as +.BR AF_INET , +.BR AF_INET6 , +or +.BR AF_UNSPEC +(to allow the implementation to select the protocol). +.SH VERSIONS +The +.BR rexec_af () +function was added to glibc in version 2.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR rexec (), +.BR rexec_af () +T} Thread safety MT-Unsafe +.TE +.SH CONFORMING TO +These functions are not in POSIX.1. +The +.BR rexec () +function first appeared in +4.2BSD, and is present on the BSDs, Solaris, and many other systems. +The +.BR rexec_af () +function is more recent, and less widespread. +.SH BUGS +The +.BR rexec () +function sends the unencrypted password across the network. +.PP +The underlying service is considered a big security hole and therefore +not enabled on many sites; see +.BR rexecd (8) +for explanations. +.SH SEE ALSO +.BR rcmd (3), +.BR rexecd (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rexec_af.3 b/man3/rexec_af.3 new file mode 100644 index 0000000..517a2d2 --- /dev/null +++ b/man3/rexec_af.3 @@ -0,0 +1 @@ +.so man3/rexec.3 diff --git a/man3/rindex.3 b/man3/rindex.3 new file mode 100644 index 0000000..a9cd4b3 --- /dev/null +++ b/man3/rindex.3 @@ -0,0 +1 @@ +.so man3/index.3 diff --git a/man3/rint.3 b/man3/rint.3 new file mode 100644 index 0000000..92a123e --- /dev/null +++ b/man3/rint.3 @@ -0,0 +1,170 @@ +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH RINT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +nearbyint, nearbyintf, nearbyintl, rint, rintf, rintl \- round +to nearest integer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double nearbyint(double " x ); +.BI "float nearbyintf(float " x ); +.BI "long double nearbyintl(long double " x ); +.PP +.BI "double rint(double " x ); +.BI "float rintf(float " x ); +.BI "long double rintl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR nearbyint (), +.BR nearbyintf (), +.BR nearbyintl (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L || _ISOC99_SOURCE +.RE +.br +.BR rint (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR rintf (), +.BR rintl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR nearbyint (), +.BR nearbyintf (), +and +.BR nearbyintl () +functions round their argument to an integer value in floating-point +format, using the current rounding direction (see +.BR fesetround (3)) +and without raising the +.I inexact +exception. +When the current rounding direction is to nearest, these +functions round halfway cases to the even integer in accordance with +IEEE-754. +.PP +The +.BR rint (), +.BR rintf (), +and +.BR rintl () +functions do the same, but will raise the +.I inexact +exception +.RB ( FE_INEXACT , +checkable via +.BR fetestexcept (3)) +when the result differs in value from the argument. +.SH RETURN VALUE +These functions return the rounded integer value. +.PP +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw26 lb lb +l l l. +Interface Attribute Value +T{ +.BR nearbyint (), +.BR nearbyintf (), +.br +.BR nearbyintl (), +.BR rint (), +.br +.BR rintf (), +.BR rintl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 128 (respectively, 1024), +and the number of mantissa bits is 24 (respectively, 53).) +.PP +If you want to store the rounded value in an integer type, +you probably want to use one of the functions described in +.BR lrint (3) +instead. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR round (3), +.BR trunc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rintf.3 b/man3/rintf.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man3/rintf.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/rintl.3 b/man3/rintl.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man3/rintl.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man3/round.3 b/man3/round.3 new file mode 100644 index 0000000..88b2d50 --- /dev/null +++ b/man3/round.3 @@ -0,0 +1,134 @@ +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ROUND 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +round, roundf, roundl \- round to nearest integer, away from zero +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double round(double " x ); +.BI "float roundf(float " x ); +.BI "long double roundl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR round (), +.BR roundf (), +.BR roundl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions round +.I x +to the nearest integer, but +round halfway cases away from zero (regardless of the current rounding +direction, see +.BR fenv (3)), +instead of to the nearest even integer like +.BR rint (3). +.PP +For example, +.IR round(0.5) +is 1.0, and +.IR round(\-0.5) +is \-1.0. +.SH RETURN VALUE +These functions return the rounded integer value. +.PP +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR round (), +.BR roundf (), +.BR roundl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +POSIX.1-2001 contains text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 128 (respectively, 1024), +and the number of mantissa bits is 24 (respectively, 53).) +.PP +If you want to store the rounded value in an integer type, +you probably want to use one of the functions described in +.BR lround (3) +instead. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lround (3), +.BR nearbyint (3), +.BR rint (3), +.BR trunc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/roundf.3 b/man3/roundf.3 new file mode 100644 index 0000000..f7ab386 --- /dev/null +++ b/man3/roundf.3 @@ -0,0 +1 @@ +.so man3/round.3 diff --git a/man3/roundl.3 b/man3/roundl.3 new file mode 100644 index 0000000..f7ab386 --- /dev/null +++ b/man3/roundl.3 @@ -0,0 +1 @@ +.so man3/round.3 diff --git a/man3/rpc.3 b/man3/rpc.3 new file mode 100644 index 0000000..0a1c263 --- /dev/null +++ b/man3/rpc.3 @@ -0,0 +1,1240 @@ +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI +.\" +.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax +.\" +.TH RPC 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +rpc \- library routines for remote procedure calls +.SH SYNOPSIS AND DESCRIPTION +These routines allow C programs to make procedure +calls on other machines across the network. +First, the client calls a procedure to send a data packet to the server. +Upon receipt of the packet, the server calls a dispatch routine +to perform the requested service, and then sends back a reply. +Finally, the procedure call returns to the client. +.\" .LP +.\" We don't have an rpc_secure.3 page at the moment -- MTK, 19 Sep 05 +.\" Routines that are used for Secure RPC (DES authentication) are described in +.\" .BR rpc_secure (3). +.\" Secure RPC can be used only if DES encryption is available. +.PP +To take use of these routines, include the header file +.IR "" . + +The prototypes below make use of the following types: +.PP +.in +4n +.EX +.BI "typedef int " bool_t ; +.PP +.BI "typedef bool_t (*" xdrproc_t ") (XDR *, void *, ...);" +.PP +.BI "typedef bool_t (*" resultproc_t ") (caddr_t " resp , +.BI " struct sockaddr_in *" raddr ); +.EE +.in +.PP +See the header files for the declarations of the +.IR AUTH , +.IR CLIENT , +.IR SVCXPRT , +and +.IR XDR +types. +.PP +.nf +.BI "void auth_destroy(AUTH *" auth ); +.fi +.IP +A macro that destroys the authentication information associated with +.IR auth . +Destruction usually involves deallocation of private data structures. +The use of +.I auth +is undefined after calling +.BR auth_destroy (). +.PP +.nf +.BI "AUTH *authnone_create(void);" +.fi +.IP +Create and return an RPC +authentication handle that passes nonusable authentication +information with each remote procedure call. +This is the default authentication used by RPC. +.PP +.nf +.BI "AUTH *authunix_create(char *" host ", int " uid ", int " gid , +.BI " int " len ", int *" aup_gids ); +.fi +.IP +Create and return an RPC authentication handle that contains +authentication information. +The parameter +.I host +is the name of the machine on which the information was created; +.I uid +is the user's user ID; +.I gid +is the user's current group ID; +.I len +and +.I aup_gids +refer to a counted array of groups to which the user belongs. +It is easy to impersonate a user. +.PP +.nf +.BI "AUTH *authunix_create_default(void);" +.fi +.IP +Calls +.BR authunix_create () +with the appropriate parameters. +.PP +.nf +.BI "int callrpc(char *" host ", unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out ); +.fi +.IP +Call the remote procedure associated with +.IR prognum , +.IR versnum , +and +.I procnum +on the machine, +.IR host . +The parameter +.I in +is the address of the procedure's argument(s), and +.I out +is the address of where to place the result(s); +.I inproc +is used to encode the procedure's parameters, and +.I outproc +is used to decode the procedure's results. +This routine returns zero if it succeeds, or the value of +.B "enum clnt_stat" +cast to an integer if it fails. +The routine +.BR clnt_perrno () +is handy for translating failure statuses into messages. +.IP +Warning: calling remote procedures with this routine +uses UDP/IP as a transport; see +.BR clntudp_create () +for restrictions. +You do not have control of timeouts or authentication using this routine. +.PP +.nf +.BI "enum clnt_stat clnt_broadcast(unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " resultproc_t " eachresult ); +.fi +.IP +Like +.BR callrpc (), +except the call message is broadcast to all locally +connected broadcast nets. +Each time it receives a response, this routine calls +.BR eachresult (), +whose form is: +.IP +.in +4n +.EX +.BI "eachresult(char *" out ", struct sockaddr_in *" addr ); +.EE +.in +.IP +where +.I out +is the same as +.I out +passed to +.BR clnt_broadcast (), +except that the remote procedure's output is decoded there; +.I addr +points to the address of the machine that sent the results. +If +.BR eachresult () +returns zero, +.BR clnt_broadcast () +waits for more replies; otherwise it returns with appropriate status. +.IP +Warning: broadcast sockets are limited in size to the +maximum transfer unit of the data link. +For ethernet, this value is 1500 bytes. +.PP +.nf +.BI "enum clnt_stat clnt_call(CLIENT *" clnt ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " struct timeval " tout ); +.fi +.IP +A macro that calls the remote procedure +.I procnum +associated with the client handle, +.IR clnt , +which is obtained with an RPC client creation routine such as +.BR clnt_create (). +The parameter +.I in +is the address of the procedure's argument(s), and +.I out +is the address of where to place the result(s); +.I inproc +is used to encode the procedure's parameters, and +.I outproc +is used to decode the procedure's results; +.I tout +is the time allowed for results to come back. +.PP +.nf +.BI "clnt_destroy(CLIENT *" clnt ); +.fi +.IP +A macro that destroys the client's RPC handle. +Destruction usually involves deallocation +of private data structures, including +.I clnt +itself. +Use of +.I clnt +is undefined after calling +.BR clnt_destroy (). +If the RPC library opened the associated socket, it will close it also. +Otherwise, the socket remains open. +.PP +.nf +.BI "CLIENT *clnt_create(char *" host ", unsigned long " prog , +.BI " unsigned long " vers ", char *" proto ); +.fi +.IP +Generic client creation routine. +.I host +identifies the name of the remote host where the server is located. +.I proto +indicates which kind of transport protocol to use. +The currently supported values for this field are \(lqudp\(rq +and \(lqtcp\(rq. +Default timeouts are set, but can be modified using +.BR clnt_control (). +.IP +Warning: using UDP has its shortcomings. +Since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data, +this transport cannot be used for procedures that take +large arguments or return huge results. +.PP +.nf +.BI "bool_t clnt_control(CLIENT *" cl ", int " req ", char *" info ); +.fi +.IP +A macro used to change or retrieve various information +about a client object. +.I req +indicates the type of operation, and +.I info +is a pointer to the information. +For both UDP and TCP, the supported values of +.I req +and their argument types and what they do are: +.IP +.in +4n +.EX +\fBCLSET_TIMEOUT\fP \fIstruct timeval\fP // set total timeout +\fBCLGET_TIMEOUT\fP \fIstruct timeval\fP // get total timeout +.EE +.in +.IP +Note: if you set the timeout using +.BR clnt_control (), +the timeout parameter passed to +.BR clnt_call () +will be ignored in all future calls. +.IP +.in +4n +.EX +\fBCLGET_SERVER_ADDR\fP \fIstruct sockaddr_in \fP // get server's address +.EE +.in +.IP +The following operations are valid for UDP only: +.IP +.in +4n +.EX +\fBCLSET_RETRY_TIMEOUT\fP \fIstruct timeval\fP // set the retry timeout +\fBCLGET_RETRY_TIMEOUT\fP \fIstruct timeval\fP // get the retry timeout +.EE +.in +.IP +The retry timeout is the time that "UDP RPC" +waits for the server to reply before +retransmitting the request. +.PP +.nf +.BI "clnt_freeres(CLIENT * " clnt ", xdrproc_t " outproc ", char *" out ); +.fi +.IP +A macro that frees any data allocated by the RPC/XDR +system when it decoded the results of an RPC call. +The parameter +.I out +is the address of the results, and +.I outproc +is the XDR routine describing the results. +This routine returns one if the results were successfully freed, +and zero otherwise. +.PP +.nf +.BI "void clnt_geterr(CLIENT *" clnt ", struct rpc_err *" errp ); +.fi +.IP +A macro that copies the error structure out of the client +handle to the structure at address +.IR errp . +.PP +.nf +.BI "void clnt_pcreateerror(char *" s ); +.fi +.IP +Print a message to standard error indicating why a client RPC +handle could not be created. +The message is prepended with string +.I s +and a colon. +Used when a +.BR clnt_create (), +.BR clntraw_create (), +.BR clnttcp_create (), +or +.BR clntudp_create () +call fails. +.PP +.nf +.BI "void clnt_perrno(enum clnt_stat " stat ); +.fi +.IP +Print a message to standard error corresponding +to the condition indicated by +.IR stat . +Used after +.BR callrpc (). +.PP +.nf +.BI "clnt_perror(CLIENT *" clnt ", char *" s ); +.fi +.IP +Print a message to standard error indicating why an RPC call failed; +.I clnt +is the handle used to do the call. +The message is prepended with string +.I s +and a colon. +Used after +.BR clnt_call (). +.PP +.nf +.BI "char *clnt_spcreateerror(char *" s ); +.fi +.IP +Like +.BR clnt_pcreateerror (), +except that it returns a string instead of printing to the standard error. +.IP +Bugs: returns pointer to static data that is overwritten on each call. +.PP +.nf +.BI "char *clnt_sperrno(enum clnt_stat " stat ); +.fi +.IP +Take the same arguments as +.BR clnt_perrno (), +but instead of sending a message to the standard error indicating why an RPC +call failed, return a pointer to a string which contains the message. +The string ends with a NEWLINE. +.IP +.BR clnt_sperrno () +is used instead of +.BR clnt_perrno () +if the program does not have a standard error (as a program +running as a server quite likely does not), or if the programmer +does not want the message to be output with +.BR printf (3), +or if a message format different than that supported by +.BR clnt_perrno () +is to be used. +Note: unlike +.BR clnt_sperror () +and +.BR clnt_spcreateerror (), +.BR clnt_sperrno () +returns pointer to static data, but the +result will not get overwritten on each call. +.PP +.nf +.BI "char *clnt_sperror(CLIENT *" rpch ", char *" s ); +.fi +.IP +Like +.BR clnt_perror (), +except that (like +.BR clnt_sperrno ()) +it returns a string instead of printing to standard error. +.IP +Bugs: returns pointer to static data that is overwritten on each call. +.PP +.nf +.BI "CLIENT *clntraw_create(unsigned long " prognum \ +", unsigned long " versnum ); +.fi +.IP +This routine creates a toy RPC client for the remote program +.IR prognum , +version +.IR versnum . +The transport used to pass messages to the service is +actually a buffer within the process's address space, so the +corresponding RPC server should live in the same address space; see +.BR svcraw_create (). +This allows simulation of RPC and acquisition of RPC +overheads, such as round trip times, without any kernel interference. +This routine returns NULL if it fails. +.PP +.nf +.BI "CLIENT *clnttcp_create(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " int *" sockp ", unsigned int " sendsz \ +", unsigned int " recvsz ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +version +.IR versnum ; +the client uses TCP/IP as a transport. +The remote program is located at Internet address +.IR *addr . +If +.\"The following inline font conversion is necessary for the hyphen indicator +.I addr\->sin_port +is zero, then it is set to the actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +Since TCP-based RPC uses buffered I/O, +the user may specify the size of the send and receive buffers +with the parameters +.I sendsz +and +.IR recvsz ; +values of zero choose suitable defaults. +This routine returns NULL if it fails. +.PP +.nf +.BI "CLIENT *clntudp_create(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " struct timeval " wait ", int *" sockp ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +version +.IR versnum ; +the client uses use UDP/IP as a transport. +The remote program is located at Internet address +.IR addr . +If +.I addr\->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +The UDP transport resends the call message in intervals of +.I wait +time until a response is received or until the call times out. +The total time for the call to time out is specified by +.BR clnt_call (). +.IP +Warning: since UDP-based RPC messages can hold only up to 8 Kbytes +of encoded data, this transport cannot be used for procedures +that take large arguments or return huge results. +.PP +.nf +.BI "CLIENT *clntudp_bufcreate(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " struct timeval " wait ", int *" sockp , +.BI " unsigned int " sendsize ", unsigned int "recosize ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +on +.IR versnum ; +the client uses use UDP/IP as a transport. +The remote program is located at Internet address +.IR addr . +If +.I addr\->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +The UDP transport resends the call message in intervals of +.I wait +time until a response is received or until the call times out. +The total time for the call to time out is specified by +.BR clnt_call (). +.IP +This allows the user to specify the maximum packet +size for sending and receiving UDP-based RPC messages. +.PP +.nf +.BI "void get_myaddress(struct sockaddr_in *" addr ); +.fi +.IP +Stuff the machine's IP address into +.IR *addr , +without consulting the library routines that deal with +.IR /etc/hosts . +The port number is always set to +.BR htons(PMAPPORT) . +.PP +.nf +.BI "struct pmaplist *pmap_getmaps(struct sockaddr_in *" addr ); +.fi +.IP +A user interface to the +.B portmap +service, which returns a list of the current RPC +program-to-port mappings on the host located at IP address +.IR *addr . +This routine can return NULL. +The command +.IR "rpcinfo\ \-p" +uses this routine. +.PP +.nf +.BI "unsigned short pmap_getport(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned int " protocol ); +.fi +.IP +A user interface to the +.B portmap +service, which returns the port number +on which waits a service that supports program number +.IR prognum , +version +.IR versnum , +and speaks the transport protocol associated with +.IR protocol . +The value of +.I protocol +is most likely +.B IPPROTO_UDP +or +.BR IPPROTO_TCP . +A return value of zero means that the mapping does not exist +or that the RPC system failed to contact the remote +.B portmap +service. +In the latter case, the global variable +.I rpc_createerr +contains the RPC status. +.PP +.nf +.BI "enum clnt_stat pmap_rmtcall(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " struct timeval " tout ", unsigned long *" portp ); +.fi +.IP +A user interface to the +.B portmap +service, which instructs +.B portmap +on the host at IP address +.I *addr +to make an RPC call on your behalf to a procedure on that host. +The parameter +.I *portp +will be modified to the program's port number if the procedure succeeds. +The definitions of other parameters are discussed +in +.BR callrpc () +and +.BR clnt_call (). +This procedure should be used for a \(lqping\(rq and nothing else. +See also +.BR clnt_broadcast (). +.PP +.nf +.BI "bool_t pmap_set(unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned int " protocol ", unsigned short " port ); +.fi +.IP +A user interface to the +.B portmap +service, which establishes a mapping between the triple +.RI [ prognum , versnum , protocol ] +and +.I port +on the machine's +.B portmap +service. +The value of +.I protocol +is most likely +.B IPPROTO_UDP +or +.BR IPPROTO_TCP . +This routine returns one if it succeeds, zero otherwise. +Automatically done by +.BR svc_register (). +.PP +.nf +.BI "bool_t pmap_unset(unsigned long " prognum ", unsigned long " versnum ); +.fi +.IP +A user interface to the +.B portmap +service, which destroys all mapping between the triple +.RI [ prognum , versnum , * ] +and +.B ports +on the machine's +.B portmap +service. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "int registerrpc(unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned long " procnum ", char *(*" procname ")(char *)," +.BI " xdrproc_t " inproc ", xdrproc_t " outproc ); +.fi +.IP +Register procedure +.I procname +with the RPC service package. +If a request arrives for program +.IR prognum , +version +.IR versnum , +and procedure +.IR procnum , +.I procname +is called with a pointer to its parameter(s); +.I procname +should return a pointer to its static result(s); +.I inproc +is used to decode the parameters while +.I outproc +is used to encode the results. +This routine returns zero if the registration succeeded, \-1 otherwise. +.IP +Warning: remote procedures registered in this form +are accessed using the UDP/IP transport; see +.BR svcudp_create () +for restrictions. +.PP +.nf +.BI "struct rpc_createerr " rpc_createerr ; +.fi +.IP +A global variable whose value is set by any RPC client creation routine +that does not succeed. +Use the routine +.BR clnt_pcreateerror () +to print the reason why. +.PP +.nf +.BI "void svc_destroy(SVCXPRT *" xprt ); +.fi +.IP +A macro that destroys the RPC service transport handle, +.IR xprt . +Destruction usually involves deallocation +of private data structures, including +.I xprt +itself. +Use of +.I xprt +is undefined after calling this routine. +.PP +.nf +.BI "fd_set " svc_fdset ; +.fi +.IP +A global variable reflecting the RPC service side's +read file descriptor bit mask; it is suitable as a parameter to the +.BR select (2) +system call. +This is of interest only if a service implementor does their own +asynchronous event processing, instead of calling +.BR svc_run (). +This variable is read-only (do not pass its address to +.BR select (2)!), +yet it may change after calls to +.BR svc_getreqset () +or any creation routines. +.PP +.nf +.BI "int " svc_fds ; +.fi +.IP +Similar to +.BR svc_fdset , +but limited to 32 file descriptors. +This interface is obsoleted by +.BR svc_fdset . +.PP +.nf +.BI "svc_freeargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in ); +.fi +.IP +A macro that frees any data allocated by the RPC/XDR +system when it decoded the arguments to a service procedure using +.BR svc_getargs (). +This routine returns 1 if the results were successfully freed, +and zero otherwise. +.PP +.nf +.BI "svc_getargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in ); +.fi +.IP +A macro that decodes the arguments of an RPC request +associated with the RPC service transport handle, +.IR xprt . +The parameter +.I in +is the address where the arguments will be placed; +.I inproc +is the XDR routine used to decode the arguments. +This routine returns one if decoding succeeds, and zero otherwise. +.PP +.nf +.BI "struct sockaddr_in *svc_getcaller(SVCXPRT *" xprt ); +.fi +.IP +The approved way of getting the network address of the caller +of a procedure associated with the RPC service transport handle, +.IR xprt . +.PP +.nf +.BI "void svc_getreqset(fd_set *" rdfds ); +.fi +.IP +This routine is of interest only if a service implementor does not call +.BR svc_run (), +but instead implements custom asynchronous event processing. +It is called when the +.BR select (2) +system call has determined that an RPC request has arrived on some +RPC socket(s); +.I rdfds +is the resultant read file descriptor bit mask. +The routine returns when all sockets associated with the value of +.I rdfds +have been serviced. +.PP +.nf +.BI "void svc_getreq(int " rdfds ); +.fi +.IP +Similar to +.BR svc_getreqset (), +but limited to 32 file descriptors. +This interface is obsoleted by +.BR svc_getreqset (). +.PP +.nf +.BI "bool_t svc_register(SVCXPRT *" xprt ", unsigned long " prognum , +.BI " unsigned long " versnum , +.BI " void (*" dispatch ")(svc_req *, SVCXPRT *)," +.BI " unsigned long " protocol ); +.fi +.IP +Associates +.I prognum +and +.I versnum +with the service dispatch procedure, +.IR dispatch . +If +.I protocol +is zero, the service is not registered with the +.B portmap +service. +If +.I protocol +is nonzero, then a mapping of the triple +.RI [ prognum , versnum , protocol ] +to +.I xprt\->xp_port +is established with the local +.B portmap +service (generally +.I protocol +is zero, +.B IPPROTO_UDP +or +.BR IPPROTO_TCP ). +The procedure +.I dispatch +has the following form: +.IP +.in +4n +.EX +dispatch(struct svc_req *request, SVCXPRT *xprt); +.EE +.in +.IP +The +.BR svc_register () +routine returns one if it succeeds, and zero otherwise. +.PP +.nf +.B "void svc_run(void);" +.fi +.IP +This routine never returns. +It waits for RPC requests to arrive, and calls the appropriate service +procedure using +.BR svc_getreq () +when one arrives. +This procedure is usually waiting for a +.BR select (2) +system call to return. +.PP +.nf +.BI "bool_t svc_sendreply(SVCXPRT *" xprt ", xdrproc_t " outproc \ +", char *" out ); +.fi +.IP +Called by an RPC service's dispatch routine to send the results of a +remote procedure call. +The parameter +.I xprt +is the request's associated transport handle; +.I outproc +is the XDR routine which is used to encode the results; and +.I out +is the address of the results. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "void svc_unregister(unsigned long " prognum ", unsigned long " versnum ); +.fi +.IP +Remove all mapping of the double +.RI [ prognum , versnum ] +to dispatch routines, and of the triple +.RI [ prognum , versnum , * ] +to port number. +.PP +.nf +.BI "void svcerr_auth(SVCXPRT *" xprt ", enum auth_stat " why ); +.fi +.IP +Called by a service dispatch routine that refuses to perform +a remote procedure call due to an authentication error. +.PP +.nf +.BI "void svcerr_decode(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that cannot successfully +decode its parameters. +See also +.BR svc_getargs (). +.PP +.nf +.BI "void svcerr_noproc(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that does not implement +the procedure number that the caller requests. +.PP +.nf +.BI "void svcerr_noprog(SVCXPRT *" xprt ); +.fi +.IP +Called when the desired program is not registered with the RPC package. +Service implementors usually do not need this routine. +.PP +.nf +.BI "void svcerr_progvers(SVCXPRT *" xprt ); +.fi +.IP +Called when the desired version of a program is not registered +with the RPC package. +Service implementors usually do not need this routine. +.PP +.nf +.BI "void svcerr_systemerr(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine when it detects a system +error not covered by any particular protocol. +For example, if a service can no longer allocate storage, +it may call this routine. +.PP +.nf +.BI "void svcerr_weakauth(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that refuses to perform +a remote procedure call due to insufficient authentication parameters. +The routine calls +.BR "svcerr_auth(xprt, AUTH_TOOWEAK)" . +.PP +.nf +.BI "SVCXPRT *svcfd_create(int " fd ", unsigned int " sendsize , +.BI " unsigned int " recvsize ); +.fi +.IP +Create a service on top of any open file descriptor. +Typically, this file descriptor is a connected socket for a stream protocol such +as TCP. +.I sendsize +and +.I recvsize +indicate sizes for the send and receive buffers. +If they are zero, a reasonable default is chosen. +.PP +.nf +.BI "SVCXPRT *svcraw_create(void);" +.fi +.IP +This routine creates a toy RPC +service transport, to which it returns a pointer. +The transport is really a buffer within the process's address space, +so the corresponding RPC client should live in the same address space; see +.BR clntraw_create (). +This routine allows simulation of RPC and acquisition of RPC +overheads (such as round trip times), without any kernel interference. +This routine returns NULL if it fails. +.PP +.nf +.BI "SVCXPRT *svctcp_create(int " sock ", unsigned int " send_buf_size , +.BI " unsigned int " recv_buf_size ); +.fi +.IP +This routine creates a TCP/IP-based RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.IR sock , +which may be +.BR RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local TCP +port, then this routine binds it to an arbitrary port. +Upon completion, +.I xprt\->xp_sock +is the transport's socket descriptor, and +.I xprt\->xp_port +is the transport's port number. +This routine returns NULL if it fails. +Since TCP-based RPC uses buffered I/O, +users may specify the size of buffers; values of zero +choose suitable defaults. +.PP +.nf +.BI "SVCXPRT *svcudp_bufcreate(int " sock ", unsigned int " sendsize , +.BI " unsigned int " recosize ); +.fi +.IP +This routine creates a UDP/IP-based RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.IR sock , +which may be +.BR RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local UDP +port, then this routine binds it to an arbitrary port. +Upon completion, +.I xprt\->xp_sock +is the transport's socket descriptor, and +.I xprt\->xp_port +is the transport's port number. +This routine returns NULL if it fails. +.IP +This allows the user to specify the maximum packet size for sending and +receiving UDP-based RPC messages. +.PP +.nf +.BI "SVCXPRT *svcudp_create(int " sock ); +.fi +.IP +This call is equivalent to +.I svcudp_bufcreate(sock,SZ,SZ) +for some default size +.IR SZ . +.PP +.nf +.BI "bool_t xdr_accepted_reply(XDR *" xdrs ", struct accepted_reply *" ar ); +.fi +.IP +Used for encoding RPC reply messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.PP +.nf +.BI "bool_t xdr_authunix_parms(XDR *" xdrs ", struct authunix_parms *" aupp ); +.fi +.IP +Used for describing UNIX credentials. +This routine is useful for users +who wish to generate these credentials without using the RPC +authentication package. +.PP +.nf +.BI "void xdr_callhdr(XDR *" xdrs ", struct rpc_msg *" chdr ); +.fi +.IP +Used for describing RPC call header messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.PP +.nf +.BI "bool_t xdr_callmsg(XDR *" xdrs ", struct rpc_msg *" cmsg ); +.fi +.IP +Used for describing RPC call messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.PP +.nf +.BI "bool_t xdr_opaque_auth(XDR *" xdrs ", struct opaque_auth *" ap ); +.fi +.IP +Used for describing RPC authentication information messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.PP +.nf +.BI "bool_t xdr_pmap(XDR *" xdrs ", struct pmap *" regs ); +.fi +.IP +Used for describing parameters to various +.B portmap +procedures, externally. +This routine is useful for users who wish to generate +these parameters without using the +.B pmap +interface. +.PP +.nf +.BI "bool_t xdr_pmaplist(XDR *" xdrs ", struct pmaplist **" rp ); +.fi +.IP +Used for describing a list of port mappings, externally. +This routine is useful for users who wish to generate +these parameters without using the +.B pmap +interface. +.PP +.nf +.BI "bool_t xdr_rejected_reply(XDR *" xdrs ", struct rejected_reply *" rr ); +.fi +.IP +Used for describing RPC reply messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.PP +.nf +.BI "bool_t xdr_replymsg(XDR *" xdrs ", struct rpc_msg *" rmsg ); +.fi +.IP +Used for describing RPC reply messages. +This routine is useful for users who wish to generate +RPC style messages without using the RPC package. +.PP +.nf +.BI "void xprt_register(SVCXPRT *" xprt ); +.fi +.IP +After RPC service transport handles are created, +they should register themselves with the RPC service package. +This routine modifies the global variable +.IR svc_fds . +Service implementors usually do not need this routine. +.PP +.nf +.BI "void xprt_unregister(SVCXPRT *" xprt ); +.fi +.IP +Before an RPC service transport handle is destroyed, +it should unregister itself with the RPC service package. +This routine modifies the global variable +.IR svc_fds . +Service implementors usually do not need this routine. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw35 lb lb +l l l. +Interface Attribute Value +T{ +.BR auth_destroy (), +.BR authnone_create (), +.br +.BR authunix_create (), +.br +.BR authunix_create_default (), +.br +.BR callrpc (), +.BR clnt_broadcast (), +.br +.BR clnt_call (), +.BR clnt_destroy (), +.br +.BR clnt_create (), +.BR clnt_control (), +.br +.BR clnt_freeres (), +.BR clnt_geterr (), +.br +.BR clnt_pcreateerror (), +.BR clnt_perrno (), +.br +.BR clnt_perror (), +.br +.BR clnt_spcreateerror (), +.br +.BR clnt_sperrno (), +.BR clnt_sperror (), +.br +.BR clntraw_create (), +.BR clnttcp_create (), +.br +.BR clntudp_create (), +.br +.BR clntudp_bufcreate (), +.br +.BR get_myaddress (), +.BR pmap_getmaps (), +.br +.BR pmap_getport (), +.BR pmap_rmtcall (), +.br +.BR pmap_set (), +.BR pmap_unset (), +.br +.BR registerrpc (), +.BR svc_destroy (), +.br +.BR svc_freeargs (), +.BR svc_getargs (), +.br +.BR svc_getcaller (), +.BR svc_getreqset (), +.br +.BR svc_getreq (), +.BR svc_register (), +.br +.BR svc_run (), +.BR svc_sendreply (), +.br +.BR svc_unregister (), +.BR svcerr_auth (), +.br +.BR svcerr_decode (), +.BR svcerr_noproc (), +.br +.BR svcerr_noprog (), +.BR svcerr_progvers (), +.br +.BR svcerr_systemerr (), +.BR svcerr_weakauth (), +.br +.BR svcfd_create (), +.BR svcraw_create (), +.br +.BR svctcp_create (), +.br +.BR svcudp_bufcreate (), +.br +.BR svcudp_create (), +.BR xdr_accepted_reply (), +.br +.BR xdr_authunix_parms (), +.br +.BR xdr_callhdr (), +.br +.BR xdr_callmsg (), +.BR xdr_opaque_auth (), +.br +.BR xdr_pmap (), +.BR xdr_pmaplist (), +.br +.BR xdr_rejected_reply (), +.br +.BR xdr_replymsg (), +.br +.BR xprt_register (), +.BR xprt_unregister () +T} Thread safety MT-Safe +.TE +.ad +.SH SEE ALSO +.\" We don't have an rpc_secure.3 page in the set at the moment -- MTK, 19 Sep 05 +.\" .BR rpc_secure (3), +.BR xdr (3) +.PP +The following manuals: +.RS +Remote Procedure Calls: Protocol Specification +.br +Remote Procedure Call Programming Guide +.br +rpcgen Programming Guide +.br +.RE +.PP +.IR "RPC: Remote Procedure Call Protocol Specification" , +RFC\ 1050, Sun Microsystems, Inc., +USC-ISI. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rpmatch.3 b/man3/rpmatch.3 new file mode 100644 index 0000000..132f072 --- /dev/null +++ b/man3/rpmatch.3 @@ -0,0 +1,174 @@ +.\" Copyright (C) 2006 Justin Pryzby +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.\" +.\" 2006-05-19, mtk, various edits and example program +.\" +.TH RPMATCH 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +rpmatch \- determine if the answer to a question is affirmative or negative +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int rpmatch(const char *" response ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR rpmatch (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _SVID_SOURCE +.SH DESCRIPTION +.BR rpmatch () +handles a user response to yes or no questions, with +support for internationalization. +.PP +.I response +should be a null-terminated string containing a +user-supplied response, perhaps obtained with +.BR fgets (3) +or +.BR getline (3). +.PP +The user's language preference is taken into account per the +environment variables +.BR LANG , +.BR LC_MESSAGES , +and +.BR LC_ALL , +if the program has called +.BR setlocale (3) +to effect their changes. +.PP +Regardless of the locale, responses matching +.B ^[Yy] +are always accepted as affirmative, and those matching +.B ^[Nn] +are always accepted as negative. +.SH RETURN VALUE +After examining +.IR response , +.BR rpmatch () +returns 0 for a recognized negative response ("no"), 1 +for a recognized positive response ("yes"), and \-1 when the value +of +.I response +is unrecognized. +.SH ERRORS +A return value of \-1 may indicate either an invalid input, or some +other error. +It is incorrect to only test if the return value is nonzero. +.PP +.BR rpmatch () +can fail for any of the reasons that +.BR regcomp (3) +or +.BR regexec (3) +can fail; the cause of the error +is not available from +.I errno +or anywhere else, but indicates a +failure of the regex engine (but this case is indistinguishable from +that of an unrecognized value of +.IR response ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR rpmatch () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +.BR rpmatch () +is not required by any standard, but +is available on a few other systems. +.\" It is available on at least AIX 5.1 and FreeBSD 6.0. +.SH BUGS +The +.BR rpmatch () +implementation looks at only the first character +of +.IR response . +As a consequence, "nyes" returns 0, and +"ynever; not in a million years" returns 1. +It would be preferable to accept input strings much more +strictly, for example (using the extended regular +expression notation described in +.BR regex (7)): +.B ^([yY]|yes|YES)$ +and +.BR ^([nN]|no|NO)$ . +.SH EXAMPLE +The following program displays the results when +.BR rpmatch () +is applied to the string given in the program's command-line argument. +.PP +.EX +#define _SVID_SOURCE +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + if (argc != 2 || strcmp(argv[1], "\-\-help") == 0) { + fprintf(stderr, "%s response\\n", argv[0]); + exit(EXIT_FAILURE); + } + + setlocale(LC_ALL, ""); + printf("rpmatch() returns: %d\\n", rpmatch(argv[1])); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fgets (3), +.BR getline (3), +.BR nl_langinfo (3), +.BR regcomp (3), +.BR setlocale (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rresvport.3 b/man3/rresvport.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man3/rresvport.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/rresvport_af.3 b/man3/rresvport_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man3/rresvport_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/rtime.3 b/man3/rtime.3 new file mode 100644 index 0000000..bdc539f --- /dev/null +++ b/man3/rtime.3 @@ -0,0 +1,153 @@ +.\" Copyright 2003 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Modified 2003-04-04 Walter Harms +.\" +.\" +.\" Slightly polished, aeb, 2003-04-06 +.\" +.TH RTIME 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +rtime \- get time from a remote machine +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "int rtime(struct sockaddr_in *" addrp ", struct rpc_timeval *" timep , +.BI " struct rpc_timeval *" timeout ); +.fi +.SH DESCRIPTION +This function uses the Time Server Protocol as described in +RFC\ 868 to obtain the time from a remote machine. +.PP +The Time Server Protocol gives the time in seconds since +00:00:00 UTC, 1 Jan 1900, +and this function subtracts the appropriate constant in order to +convert the result to seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.PP +When +.I timeout +is non-NULL, the udp/time socket (port 37) is used. +Otherwise, the tcp/time socket (port 37) is used. +.SH RETURN VALUE +On success, 0 is returned, and the obtained 32-bit time value is stored in +.IR timep\->tv_sec . +In case of error \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +All errors for underlying functions +.RB ( sendto (2), +.BR poll (2), +.BR recvfrom (2), +.BR connect (2), +.BR read (2)) +can occur. +Moreover: +.TP +.B EIO +The number of returned bytes is not 4. +.TP +.B ETIMEDOUT +The waiting time as defined in timeout has expired. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR rtime () +T} Thread safety MT-Safe +.TE +.SH NOTES +Only IPv4 is supported. +.PP +Some +.I in.timed +versions support only TCP. +Try the example program with +.I use_tcp +set to 1. +.PP +Libc5 uses the prototype +.PP +.nf + int rtime(struct sockaddr_in *, struct timeval *, struct timeval *); +.fi +.PP +and requires +.I +instead of +.IR . +.SH BUGS +.BR rtime () +in glibc 2.2.5 and earlier does not work properly on 64-bit machines. +.SH EXAMPLE +This example requires that port 37 is up and open. +You may check +that the time entry within +.I /etc/inetd.conf +is not commented out. +.PP +The program connects to a computer called "linux". +Using "localhost" does not work. +The result is the localtime of the computer "linux". +.PP +.EX +#include +#include +#include +#include +#include +#include +#include + +static int use_tcp = 0; +static char *servername = "linux"; + +int +main(void) +{ + struct sockaddr_in name; + struct rpc_timeval time1 = {0,0}; + struct rpc_timeval timeout = {1,0}; + struct hostent *hent; + int ret; + + memset(&name, 0, sizeof(name)); + sethostent(1); + hent = gethostbyname(servername); + memcpy(&name.sin_addr, hent\->h_addr, hent\->h_length); + + ret = rtime(&name, &time1, use_tcp ? NULL : &timeout); + if (ret < 0) + perror("rtime error"); + else { + time_t t = time1.tv_sec; + printf("%s\\n", ctime(&t)); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.\" .BR netdate (1), +.BR ntpdate (1), +.\" .BR rdate (1), +.BR inetd (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/rtnetlink.3 b/man3/rtnetlink.3 new file mode 100644 index 0000000..3167111 --- /dev/null +++ b/man3/rtnetlink.3 @@ -0,0 +1,136 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: rtnetlink.3,v 1.2 1999/05/18 10:35:10 freitag Exp $ +.\" +.TH RTNETLINK 3 2014-09-06 "GNU" "Linux Programmer's Manual" +.SH NAME +rtnetlink \- macros to manipulate rtnetlink messages +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type \ +", NETLINK_ROUTE);" +.PP +.BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen ); +.PP +.BI "void *RTA_DATA(struct rtattr *" rta ); +.PP +.BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta ); +.PP +.BI "struct rtattr *RTA_NEXT(struct rtattr *" rta \ +", unsigned int " rtabuflen ); +.PP +.BI "unsigned int RTA_LENGTH(unsigned int " length ); +.PP +.BI "unsigned int RTA_SPACE(unsigned int "length ); +.SH DESCRIPTION +All +.BR rtnetlink (7) +messages consist of a +.BR netlink (7) +message header and appended attributes. +The attributes should be manipulated only using the macros provided here. +.PP +.BI RTA_OK( rta ", " attrlen ) +returns true if +.I rta +points to a valid routing attribute; +.I attrlen +is the running length of the attribute buffer. +When not true then you must assume there are no more attributes in the +message, even if +.I attrlen +is nonzero. +.PP +.BI RTA_DATA( rta ) +returns a pointer to the start of this attribute's data. +.PP +.BI RTA_PAYLOAD( rta ) +returns the length of this attribute's data. +.PP +.BI RTA_NEXT( rta ", " attrlen ) +gets the next attribute after +.IR rta . +Calling this macro will update +.IR attrlen . +You should use +.B RTA_OK +to check the validity of the returned pointer. +.PP +.BI RTA_LENGTH( len ) +returns the length which is required for +.I len +bytes of data plus the header. +.PP +.BI RTA_SPACE( len ) +returns the amount of space which will be needed in a message with +.I len +bytes of data. +.SH CONFORMING TO +These macros are nonstandard Linux extensions. +.SH BUGS +This manual page is incomplete. +.SH EXAMPLE +.\" FIXME . ? would be better to use libnetlink in the EXAMPLE code here +Creating a rtnetlink message to set the MTU of a device: +.PP +.in +4n +.EX +#include + +\&... + +struct { + struct nlmsghdr nh; + struct ifinfomsg if; + char attrbuf[512]; +} req; + +struct rtattr *rta; +unsigned int mtu = 1000; + +int rtnetlink_sk = socket(AF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE); + +memset(&req, 0, sizeof(req)); +req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(struct ifinfomsg)); +req.nh.nlmsg_flags = NLM_F_REQUEST; +req.nh.nlmsg_type = RTM_NEWLINK; +req.if.ifi_family = AF_UNSPEC; +req.if.ifi_index = INTERFACE_INDEX; +req.if.ifi_change = 0xffffffff; /* ??? */ +rta = (struct rtattr *)(((char *) &req) + + NLMSG_ALIGN(req.nh.nlmsg_len)); +rta\->rta_type = IFLA_MTU; +rta\->rta_len = RTA_LENGTH(sizeof(unsigned int)); +req.nh.nlmsg_len = NLMSG_ALIGN(req.nh.nlmsg_len) + + RTA_LENGTH(sizeof(mtu)); +memcpy(RTA_DATA(rta), &mtu, sizeof(mtu)); +send(rtnetlink_sk, &req, req.nh.nlmsg_len, 0); +.EE +.in +.SH SEE ALSO +.BR netlink (3), +.BR netlink (7), +.BR rtnetlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ruserok.3 b/man3/ruserok.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man3/ruserok.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/ruserok_af.3 b/man3/ruserok_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man3/ruserok_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man3/scalb.3 b/man3/scalb.3 new file mode 100644 index 0000000..02f8720 --- /dev/null +++ b/man3/scalb.3 @@ -0,0 +1,229 @@ +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SCALB 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +scalb, scalbf, scalbl \- multiply floating-point number +by integral power of radix (OBSOLETE) +.SH SYNOPSIS +.B #include +.PP +.BI "double scalb(double " x ", double " exp ); +.br +.BI "float scalbf(float " x ", float " exp ); +.br +.BI "long double scalbl(long double " x ", long double " exp ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR scalb (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.br +.BR scalbf (), +.BR scalbl (): +.RS 4 +_XOPEN_SOURCE\ >=\ 600 + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions multiply their first argument +.I x +by +.B FLT_RADIX +(probably 2) +to the power of +.IR exp , +that is: +.PP +.nf + x * FLT_RADIX ** exp +.fi +.PP +The definition of +.B FLT_RADIX +can be obtained by including +.IR . +.\" not in /usr/include but in a gcc lib +.SH RETURN VALUE +On success, these functions return +.IR x +* +.B FLT_RADIX +** +.IR exp . +.PP +If +.I x +or +.I exp +is a NaN, a NaN is returned. +.PP +If +.I x +is positive infinity (negative infinity), +and +.I exp +is not negative infinity, +positive infinity (negative infinity) is returned. +.PP +If +.I x +is +0 (\-0), and +.I exp +is not positive infinity, +0 (\-0) is returned. +.PP +If +.I x +is zero, and +.I exp +is positive infinity, +a domain error occurs, and +a NaN is returned. +.PP +If +.I x +is an infinity, +and +.I exp +is negative infinity, +a domain error occurs, and +a NaN is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.PP +If the result underflows, +a range error occurs, +and the functions return zero, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is 0, and \fIexp\fP is positive infinity, \ +or \fIx\fP is positive infinity and \fIexp\fP is negative infinity \ +and the other argument is not a NaN +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error, overflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6803 +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6804 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR scalb (), +.BR scalbf (), +.BR scalbl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR scalb () +is specified in POSIX.1-2001, but marked obsolescent. +POSIX.1-2008 removes the specification of +.BR scalb (), +recommending the use of +.BR scalbln (3), +.BR scalblnf (3), +or +.BR scalblnl (3) +instead. +The +.BR scalb () +function is from 4.3BSD. +.PP +.BR scalbf () +and +.BR scalbl () +are unstandardized; +.BR scalbf () +is nevertheless present on several other systems +.\" Looking at header files: scalbf() is present on the +.\" BSDs, Tru64, HP-UX 11, Irix 6.5; scalbl() is on HP-UX 11 and Tru64. +.SH SEE ALSO +.BR ldexp (3), +.BR scalbln (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/scalbf.3 b/man3/scalbf.3 new file mode 100644 index 0000000..5a33fb8 --- /dev/null +++ b/man3/scalbf.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalbl.3 b/man3/scalbl.3 new file mode 100644 index 0000000..5a33fb8 --- /dev/null +++ b/man3/scalbl.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man3/scalbln.3 b/man3/scalbln.3 new file mode 100644 index 0000000..4362d60 --- /dev/null +++ b/man3/scalbln.3 @@ -0,0 +1,202 @@ +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SCALBLN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl \- +multiply floating-point number by integral power of radix +.SH SYNOPSIS +.B #include +.PP +.BI "double scalbln(double " x ", long int " exp ); +.br +.BI "float scalblnf(float " x ", long int " exp ); +.br +.BI "long double scalblnl(long double " x ", long int " exp ); +.PP +.BI "double scalbn(double " x ", int " exp ); +.br +.BI "float scalbnf(float " x ", int " exp ); +.br +.BI "long double scalbnl(long double " x ", int " exp ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR scalbln (), +.BR scalblnf (), +.BR scalblnl (): +.RS +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE +.RE +.br +.BR scalbn (), +.BR scalbnf (), +.BR scalbnl (): +.RS +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions multiply their first argument +.I x +by +.B FLT_RADIX +(probably 2) +to the power of +.IR exp , +that is: +.PP +.nf + x * FLT_RADIX ** exp +.fi +.PP +The definition of +.B FLT_RADIX +can be obtained by including +.IR . +.\" not in /usr/include but in a gcc lib +.SH RETURN VALUE +On success, these functions return +.IR x +* +.B FLT_RADIX +** +.IR exp . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.PP +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.PP +If the result underflows, +a range error occurs, +and the functions return zero, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error, overflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6803 +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw33 lb lb +l l l. +Interface Attribute Value +T{ +.BR scalbn (), +.BR scalbnf (), +.BR scalbnl (), +.br +.BR scalbln (), +.BR scalblnf (), +.BR scalblnl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +These functions differ from the obsolete functions described in +.BR scalb (3) +in the type of their second argument. +The functions described on this page have a second argument +of an integral type, while those in +.BR scalb (3) +have a second argument of type +.IR double . +.PP +If +.B FLT_RADIX +equals 2 (which is usual), then +.BR scalbn () +is equivalent to +.BR ldexp (3). +.SH SEE ALSO +.BR ldexp (3), +.BR scalb (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/scalblnf.3 b/man3/scalblnf.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man3/scalblnf.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man3/scalblnl.3 b/man3/scalblnl.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man3/scalblnl.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man3/scalbn.3 b/man3/scalbn.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man3/scalbn.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man3/scalbnf.3 b/man3/scalbnf.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man3/scalbnf.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man3/scalbnl.3 b/man3/scalbnl.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man3/scalbnl.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man3/scandir.3 b/man3/scandir.3 new file mode 100644 index 0000000..2a95ee1 --- /dev/null +++ b/man3/scandir.3 @@ -0,0 +1,342 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:26:16 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Apr 11 17:11:33 1996 by Andries Brouwer (aeb@cwi.nl): +.\" Corrected type of compar routines, as suggested by +.\" Miguel Barreiro (enano@avalon.yaix.es). Added example. +.\" Modified Sun Sep 24 20:15:46 2000 by aeb, following Petter Reinholdtsen. +.\" Modified 2001-12-26 by aeb, following Joey. Added versionsort. +.\" +.\" The pieces on scandirat(3) were copyright and licensed as follows. +.\" +.\" Copyright (c) 2012, Mark R. Bannister +.\" based on text in mkfifoat.3 Copyright (c) 2006, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH SCANDIR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +scandir, scandirat, alphasort, versionsort \- scan +a directory for matching entries +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int scandir(const char *" dirp ", struct dirent ***" namelist , +.RS +.BI "int (*" filter ")(const struct dirent *)," +.BI "int (*" compar ")(const struct dirent **, const struct dirent **));" +.RE +.PP +.BI "int alphasort(const struct dirent **" a ", const struct dirent **" b ); +.PP +.BI "int versionsort(const struct dirent **" a ", const struct dirent **" b ); + +.BR "#include " " /* Definition of AT_* constants */" +.B #include +.PP +.fi +.BI "int scandirat(int " dirfd ", const char *" dirp "," +.BI "struct dirent ***" namelist , +.nf +.RS +.BI "int (*" filter ")(const struct dirent *)," +.BI "int (*" compar ")(const struct dirent **, const struct dirent **));" +.RE +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR scandir (), +.BR alphasort (): +.br +.RS 4 +.PD 0 +.ad b +/* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.PD +.RE +.PP +.BR versionsort (): +_GNU_SOURCE +.PP +.BR scandirat (): +_GNU_SOURCE +.SH DESCRIPTION +The +.BR scandir () +function scans the directory \fIdirp\fP, calling +\fIfilter\fP() on each directory entry. +Entries for which +\fIfilter\fP() returns nonzero are stored in strings allocated via +.BR malloc (3), +sorted using +.BR qsort (3) +with the comparison +function \fIcompar\fP(), and collected in array \fInamelist\fP +which is allocated via +.BR malloc (3). +If \fIfilter\fP is NULL, all entries are selected. +.PP +The +.BR alphasort () +and +.BR versionsort () +functions can be used as the comparison function +.IR compar (). +The former sorts directory entries using +.BR strcoll (3), +the latter using +.BR strverscmp (3) +on the strings \fI(*a)\->d_name\fP and \fI(*b)\->d_name\fP. +.SS scandirat() +The +.BR scandirat () +function operates in exactly the same way as +.BR scandir (), +except for the differences described here. +.PP +If the pathname given in +.I dirp +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR scandir () +for a relative pathname). +.PP +If +.I dirp +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I dirp +is interpreted relative to the current working +directory of the calling process (like +.BR scandir ()). +.PP +If +.I dirp +is absolute, then +.I dirfd +is ignored. +.PP +See +.BR openat (2) +for an explanation of the need for +.BR scandirat (). +.SH RETURN VALUE +The +.BR scandir () +function returns the number of directory entries +selected. +On error, \-1 is returned, with +.I errno +set to indicate the cause of the error. +.PP +The +.BR alphasort () +and +.BR versionsort () +functions return an integer less than, equal to, +or greater than zero if the first argument is considered to be +respectively less than, equal to, or greater than the second. +.SH ERRORS +.TP +.B ENOENT +The path in \fIdirp\fR does not exist. +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.TP +.B ENOTDIR +The path in \fIdirp\fR is not a directory. +.PP +The following additional errors can occur for +.BR scandirat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I dirp +is a relative path and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR versionsort () +was added to glibc in version 2.1. +.PP +.BR scandirat () +was added to glibc in version 2.15. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw26 lb lb +l l l. +Interface Attribute Value +T{ +.BR scandir (), +.BR scandirat () +T} Thread safety MT-Safe +T{ +.BR alphasort (), +.BR versionsort () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +.BR alphasort (), +.BR scandir (): +4.3BSD, POSIX.1-2008. +.PP +.BR versionsort () +and +.BR scandirat () +are GNU extensions. +.\" .LP +.\" The functions +.\" .BR scandir () +.\" and +.\" .BR alphasort () +.\" are from 4.3BSD, and have been available under Linux since libc4. +.\" Libc4 and libc5 use the more precise prototype +.\" .sp +.\" .nf +.\" int alphasort(const struct dirent ** a, +.\" const struct dirent **b); +.\" .fi +.\" .sp +.\" but glibc 2.0 returns to the imprecise BSD prototype. +.SH NOTES +Since glibc 2.1, +.BR alphasort () +calls +.BR strcoll (3); +earlier it used +.BR strcmp (3). +.PP +Before glibc 2.10, the two arguments of +.BR alphasort () +and +.BR versionsort () +were typed as +.IR "const void\ *" . +When +.BR alphasort () +was standardized in POSIX.1-2008, +the argument type was specified as the type-safe +.IR "const struct dirent\ **", +and glibc 2.10 changed the definition of +.BR alphasort () +(and the nonstandard +.BR versionsort ()) +to match the standard. +.SH EXAMPLE +The program below prints a list of the files in the current directory +in reverse order. +.\" +.SS Program source +\& +.EX +#define _DEFAULT_SOURCE +#include +#include +#include + +int +main(void) +{ + struct dirent **namelist; + int n; + + n = scandir(".", &namelist, NULL, alphasort); + if (n == -1) { + perror("scandir"); + exit(EXIT_FAILURE); + } + + while (n\-\-) { + printf("%s\en", namelist[n]\->d_name); + free(namelist[n]); + } + free(namelist); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR closedir (3), +.BR fnmatch (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR seekdir (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strverscmp (3), +.BR telldir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/scandirat.3 b/man3/scandirat.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man3/scandirat.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man3/scanf.3 b/man3/scanf.3 new file mode 100644 index 0000000..3b7ec52 --- /dev/null +++ b/man3/scanf.3 @@ -0,0 +1,778 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)scanf.3 6.14 (Berkeley) 1/8/93 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" modified to resemble the GNU libio setup used in the Linux libc +.\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de +.\" Modified, aeb, 970121 +.\" 2005-07-14, mtk, added description of %n$ form; various text +.\" incorporated from the GNU C library documentation ((C) The +.\" Free Software Foundation); other parts substantially rewritten. +.\" +.\" 2008-06-23, mtk +.\" Add ERRORS section. +.\" Document the 'a' and 'm' modifiers for dynamic string allocation. +.\" +.TH SCANF 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int scanf(const char *" format ", ...);" +.BI "int fscanf(FILE *" stream ", const char *" format ", ...);" +.BI "int sscanf(const char *" str ", const char *" format ", ...);" + +.B #include +.PP +.BI "int vscanf(const char *" format ", va_list " ap ); +.BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap ); +.BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.PP +.BR vscanf (), +.BR vsscanf (), +.BR vfscanf (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.ad +.RE +.SH DESCRIPTION +The +.BR scanf () +family of functions scans input according to +.I format +as described below. +This format may contain +.IR "conversion specifications" ; +the results from such conversions, if any, +are stored in the locations pointed to by the +.I pointer +arguments that follow +.IR format . +Each +.I pointer +argument must be of a type that is appropriate for the value returned +by the corresponding conversion specification. +.PP +If the number of conversion specifications in +.I format +exceeds the number of +.I pointer +arguments, the results are undefined. +If the number of +.I pointer +arguments exceeds the number of conversion specifications, then the excess +.I pointer +arguments are evaluated, but are otherwise ignored. +.PP +The +.BR scanf () +function reads input from the standard input stream +.IR stdin , +.BR fscanf () +reads input from the stream pointer +.IR stream , +and +.BR sscanf () +reads its input from the character string pointed to by +.IR str . +.PP +The +.BR vfscanf () +function is analogous to +.BR vfprintf (3) +and reads input from the stream pointer +.I stream +using a variable argument list of pointers (see +.BR stdarg (3). +The +.BR vscanf () +function scans a variable argument list from the standard input and the +.BR vsscanf () +function scans it from a string; these are analogous to the +.BR vprintf (3) +and +.BR vsprintf (3) +functions respectively. +.PP +The +.I format +string consists of a sequence of +.I directives +which describe how to process the sequence of input characters. +If processing of a directive fails, no further input is read, and +.BR scanf () +returns. +A "failure" can be either of the following: +.IR "input failure" , +meaning that input characters were unavailable, or +.IR "matching failure" , +meaning that the input was inappropriate (see below). +.PP +A directive is one of the following: +.TP +\(bu +A sequence of white-space characters (space, tab, newline, etc.; see +.BR isspace (3)). +This directive matches any amount of white space, +including none, in the input. +.TP +\(bu +An ordinary character (i.e., one other than white space or \(aq%\(aq). +This character must exactly match the next character of input. +.TP +\(bu +A conversion specification, +which commences with a \(aq%\(aq (percent) character. +A sequence of characters from the input is converted according to +this specification, and the result is placed in the corresponding +.I pointer +argument. +If the next item of input does not match the conversion specification, +the conversion fails\(emthis is a +.IR "matching failure" . +.PP +Each +.I conversion specification +in +.I format +begins with either the character \(aq%\(aq or the character sequence +"\fB%\fP\fIn\fP\fB$\fP" +(see below for the distinction) followed by: +.TP +\(bu +An optional \(aq*\(aq assignment-suppression character: +.BR scanf () +reads input as directed by the conversion specification, +but discards the input. +No corresponding +.I pointer +argument is required, and this specification is not +included in the count of successful assignments returned by +.BR scanf (). +.TP +\(bu +For decimal conversions, an optional quote character (\(aq). +This specifies that the input number may include thousands' +separators as defined by the +.BR LC_NUMERIC +category of the current locale. +(See +.BR setlocale (3).) +The quote character may precede or follow the \(aq*\(aq +assignment-suppression character. +.TP +\(bu +An optional \(aqm\(aq character. +This is used with string conversions +.RI ( %s , +.IR %c , +.IR %[ ), +and relieves the caller of the +need to allocate a corresponding buffer to hold the input: instead, +.BR scanf () +allocates a buffer of sufficient size, +and assigns the address of this buffer to the corresponding +.I pointer +argument, which should be a pointer to a +.I "char\ *" +variable (this variable does not need to be initialized before the call). +The caller should subsequently +.BR free (3) +this buffer when it is no longer required. +.TP +\(bu +An optional decimal integer which specifies the +.IR "maximum field width" . +Reading of characters stops either when this maximum is reached or +when a nonmatching character is found, whichever happens first. +Most conversions discard initial white space characters (the exceptions +are noted below), +and these discarded characters don't count toward the maximum field width. +String input conversions store a terminating null byte (\(aq\\0\(aq) +to mark the end of the input; +the maximum field width does not include this terminator. +.TP +\(bu +An optional +.IR "type modifier character" . +For example, the +.B l +type modifier is used with integer conversions such as +.B %d +to specify that the corresponding +.I pointer +argument refers to a +.I "long int" +rather than a pointer to an +.IR int . +.TP +\(bu +A +.I "conversion specifier" +that specifies the type of input conversion to be performed. +.PP +The conversion specifications in +.I format +are of two forms, either beginning with \(aq%\(aq or beginning with +"\fB%\fP\fIn\fP\fB$\fP". +The two forms should not be mixed in the same +.I format +string, except that a string containing +"\fB%\fP\fIn\fP\fB$\fP" +specifications can include +.B %% +and +.BR %* . +If +.I format +contains \(aq%\(aq +specifications, then these correspond in order with successive +.I pointer +arguments. +In the +"\fB%\fP\fIn\fP\fB$\fP" +form (which is specified in POSIX.1-2001, but not C99), +.I n +is a decimal integer that specifies that the converted input should +be placed in the location referred to by the +.IR n -th +.I pointer +argument following +.IR format . +.SS Conversions +The following +.I "type modifier characters" +can appear in a conversion specification: +.TP +.B h +Indicates that the conversion will be one of +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP +and the next pointer is a pointer to a +.I short int +or +.I unsigned short int +(rather than +.IR int ). +.TP +.B hh +As for +.BR h , +but the next pointer is a pointer to a +.I signed char +or +.IR "unsigned char" . +.TP +.B j +As for +.BR h , +but the next pointer is a pointer to an +.I intmax_t +or a +.IR uintmax_t . +This modifier was introduced in C99. +.TP +.B l +Indicates either that the conversion will be one of +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP +and the next pointer is a pointer to a +.I long int +or +.I unsigned long int +(rather than +.IR int ), +or that the conversion will be one of +\fBe\fP, \fBf\fP, or \fBg\fP +and the next pointer is a pointer to +.I double +(rather than +.IR float ). +Specifying two +.B l +characters is equivalent to +.BR L . +If used with +.B %c +or +.BR %s , +the corresponding parameter is considered +as a pointer to a wide character or wide-character string respectively. +.\" This use of l was introduced in Amendment 1 to ISO C90. +.TP +.B L +Indicates that the conversion will be either +\fBe\fP, \fBf\fP, or \fBg\fP +and the next pointer is a pointer to +.I "long double" +or the conversion will be +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, or \fBx\fP +and the next pointer is a pointer to +.IR "long long" . +.\" MTK, Jul 05: The following is no longer true for modern +.\" ANSI C (i.e., C99): +.\" (Note that long long is not an +.\" ANSI C +.\" type. Any program using this will not be portable to all +.\" architectures). +.TP +.B q +equivalent to +.BR L . +This specifier does not exist in ANSI C. +.TP +.B t +As for +.BR h , +but the next pointer is a pointer to a +.IR ptrdiff_t . +This modifier was introduced in C99. +.TP +.B z +As for +.BR h , +but the next pointer is a pointer to a +.IR size_t . +This modifier was introduced in C99. +.PP +The following +.I "conversion specifiers" +are available: +.TP +.B % +Matches a literal \(aq%\(aq. +That is, +.B %\&% +in the format string matches a +single input \(aq%\(aq character. +No conversion is done (but initial white space characters are discarded), +and assignment does not occur. +.TP +.B d +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.IR int . +.TP +.B D +Equivalent to +.IR ld ; +this exists only for backward compatibility. +(Note: thus only in libc4. +In libc5 and glibc the +.B %D +is silently ignored, causing old programs to fail mysteriously.) +.TP +.B i +Matches an optionally signed integer; the next pointer must be a pointer to +.IR int . +The integer is read in base 16 if it begins with +.I 0x +or +.IR 0X , +in base 8 if it begins with +.IR 0 , +and in base 10 otherwise. +Only characters that correspond to the base are used. +.TP +.B o +Matches an unsigned octal integer; the next pointer must be a pointer to +.IR "unsigned int" . +.TP +.B u +Matches an unsigned decimal integer; the next pointer must be a +pointer to +.IR "unsigned int" . +.TP +.B x +Matches an unsigned hexadecimal integer; the next pointer must +be a pointer to +.IR "unsigned int" . +.TP +.B X +Equivalent to +.BR x . +.TP +.B f +Matches an optionally signed floating-point number; the next pointer must +be a pointer to +.IR float . +.TP +.B e +Equivalent to +.BR f . +.TP +.B g +Equivalent to +.BR f . +.TP +.B E +Equivalent to +.BR f . +.TP +.B a +(C99) Equivalent to +.BR f . +.TP +.B s +Matches a sequence of non-white-space characters; +the next pointer must be a pointer to the initial element of a +character array that is long enough to hold the input sequence and +the terminating null byte (\(aq\\0\(aq), which is added automatically. +The input string stops at white space or at the maximum field +width, whichever occurs first. +.TP +.B c +Matches a sequence of characters whose length is specified by the +.I maximum field width +(default 1); the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters +(no terminating null byte is added). +The usual skip of leading white space is suppressed. +To skip white space first, use an explicit space in the format. +.TP +.B \&[ +Matches a nonempty sequence of characters from the specified set of +accepted characters; the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters in the string, plus a +terminating null byte. +The usual skip of leading white space is suppressed. +The string is to be made up of characters in (or not in) a particular set; +the set is defined by the characters between the open bracket +.B [ +character and a close bracket +.B ] +character. +The set +.I excludes +those characters if the first character after the open bracket is a +circumflex +.RB ( ^ ). +To include a close bracket in the set, make it the first character after +the open bracket or the circumflex; any other position will end the set. +The hyphen character +.B \- +is also special; when placed between two other characters, it adds all +intervening characters to the set. +To include a hyphen, make it the last +character before the final close bracket. +For instance, +.B [^]0\-9\-] +means +the set "everything except close bracket, zero through nine, and hyphen". +The string ends with the appearance of a character not in the (or, with a +circumflex, in) set or when the field width runs out. +.TP +.B p +Matches a pointer value (as printed by +.B %p +in +.BR printf (3); +the next pointer must be a pointer to a pointer to +.IR void . +.TP +.B n +Nothing is expected; instead, the number of characters consumed thus far +from the input is stored through the next pointer, which must be a pointer +to +.IR int . +This is +.I not +a conversion and does +.I not +increase the count returned by the function. +The assignment can be suppressed with the +.B * +assignment-suppression character, but the effect on the +return value is undefined. +Therefore +.B %*n +conversions should not be used. +.SH RETURN VALUE +On success, these functions return the number of input items +successfully matched and assigned; +this can be fewer than provided for, +or even zero, in the event of an early matching failure. +.PP +The value +.B EOF +is returned if the end of input is reached before either the first +successful conversion or a matching failure occurs. +.B EOF +is also returned if a read error occurs, +in which case the error indicator for the stream (see +.BR ferror (3)) +is set, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The file descriptor underlying +.I stream +is marked nonblocking, and the read operation would block. +.TP +.B EBADF +The file descriptor underlying +.I stream +is invalid, or not open for reading. +.TP +.B EILSEQ +Input byte sequence does not form a valid character. +.TP +.B EINTR +The read operation was interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +Not enough arguments; or +.I format +is NULL. +.TP +.B ENOMEM +Out of memory. +.TP +.B ERANGE +The result of an integer conversion would exceed the size +that can be stored in the corresponding integer type. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR scanf (), +.BR fscanf (), +.br +.BR sscanf (), +.BR vscanf (), +.br +.BR vsscanf (), +.BR vfscanf () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +The functions +.BR fscanf (), +.BR scanf (), +and +.BR sscanf () +conform to C89 and C99 and POSIX.1-2001. +These standards do not specify the +.B ERANGE +error. +.PP +The +.B q +specifier is the 4.4BSD notation for +.IR "long long" , +while +.B ll +or the usage of +.B L +in integer conversions is the GNU notation. +.PP +The Linux version of these functions is based on the +.I GNU +.I libio +library. +Take a look at the +.I info +documentation of +.I GNU +.I libc (glibc-1.08) +for a more concise description. +.SH NOTES +.SS The 'a' assignment-allocation modifier +Originally, the GNU C library supported dynamic allocation for string inputs +(as a nonstandard extension) via the +.B a +character. +(This feature is present at least as far back as glibc 2.0.) +Thus, one could write the following to have +.BR scanf () +allocate a buffer for an input string, +with a pointer to that buffer being returned in +.IR *buf : +.PP + char *buf; + scanf("%as", &buf); +.PP +The use of the letter +.B a +for this purpose was problematic, since +.B a +is also specified by the ISO C standard as a synonym for +.B f +(floating-point input). +POSIX.1-2008 instead specifies the +.B m +modifier for assignment allocation (as documented in DESCRIPTION, above). +.PP +Note that the +.B a +modifier is not available if the program is compiled with +.I "gcc -std=c99" +or +.IR "gcc -D_ISOC99_SOURCE" +(unless +.B _GNU_SOURCE +is also specified), in which case the +.B a +is interpreted as a specifier for floating-point numbers (see above). +.PP +Support for the +.B m +modifier was added to glibc starting with version 2.7, +and new programs should use that modifier instead of +.BR a . +.PP +As well as being standardized by POSIX, the +.B m +modifier has the following further advantages over +the use of +.BR a: +.IP * 2 +It may also be applied to +.B %c +conversion specifiers (e.g., +.BR %3mc ). +.IP * +It avoids ambiguity with respect to the +.B %a +floating-point conversion specifier (and is unaffected by +.IR "gcc -std=c99" +etc.). +.SH BUGS +All functions are fully C89 conformant, but provide the +additional specifiers +.B q +and +.B a +as well as an additional behavior of the +.B L +and +.B l +specifiers. +The latter may be considered to be a bug, as it changes the +behavior of specifiers defined in C89. +.PP +Some combinations of the type modifiers and conversion +specifiers defined by ANSI C do not make sense +(e.g., +.BR "%Ld" ). +While they may have a well-defined behavior on Linux, this need not +to be so on other architectures. +Therefore it usually is better to use +modifiers that are not defined by ANSI C at all, that is, use +.B q +instead of +.B L +in combination with +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP +conversions or +.BR ll . +.PP +The usage of +.B q +is not the same as on 4.4BSD, +as it may be used in float conversions equivalently to +.BR L . +.SH EXAMPLE +To use the dynamic allocation conversion specifier, specify +.B m +as a length modifier (thus +.B %ms +or +\fB%m[\fP\fIrange\fP\fB]\fP). +The caller must +.BR free (3) +the returned string, as in the following example: +.PP +.in +4n +.EX +char *p; +int n; + +errno = 0; +n = scanf("%m[a-z]", &p); +if (n == 1) { + printf("read: %s\\n", p); + free(p); +} else if (errno != 0) { + perror("scanf"); +} else { + fprintf(stderr, "No matching characters\\n"); +} +.EE +.in +.PP +As shown in the above example, it is necessary to call +.BR free (3) +only if the +.BR scanf () +call successfully read a string. +.SH SEE ALSO +.BR getc (3), +.BR printf (3), +.BR setlocale (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sched_getcpu.3 b/man3/sched_getcpu.3 new file mode 100644 index 0000000..3577f7b --- /dev/null +++ b/man3/sched_getcpu.3 @@ -0,0 +1,118 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SCHED_GETCPU 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sched_getcpu \- determine CPU on which the calling thread is running +.SH SYNOPSIS +.nf +.B #include +.PP +.B int sched_getcpu(void); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR sched_getcpu (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.14: +_GNU_SOURCE +.TP 4 +Before glibc 2.14: +_BSD_SOURCE || _SVID_SOURCE + /* _GNU_SOURCE also suffices */ +.PD +.RE +.ad b +.SH DESCRIPTION +.BR sched_getcpu () +returns the number of the CPU on which the calling thread is currently executing. +.SH RETURN VALUE +On success, +.BR sched_getcpu () +returns a nonnegative CPU number. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOSYS +This kernel does not implement +.BR getcpu (2). +.SH VERSIONS +This function is available since glibc 2.6. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sched_getcpu () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR sched_getcpu () +is glibc-specific. +.SH NOTES +The call +.PP +.in +4n +.EX +cpu = sched_getcpu(); +.EE +.in +.PP +is equivalent to the following +.BR getcpu (2) +call: +.PP +.in +4n +.EX +int c, s; +s = getcpu(&c, NULL, NULL); +cpu = (s == \-1) ? s : c; +.EE +.in +.SH SEE ALSO +.BR getcpu (2), +.BR sched (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/secure_getenv.3 b/man3/secure_getenv.3 new file mode 100644 index 0000000..5142bef --- /dev/null +++ b/man3/secure_getenv.3 @@ -0,0 +1 @@ +.so man3/getenv.3 diff --git a/man3/seed48.3 b/man3/seed48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man3/seed48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/seed48_r.3 b/man3/seed48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man3/seed48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/seekdir.3 b/man3/seekdir.3 new file mode 100644 index 0000000..d745f24 --- /dev/null +++ b/man3/seekdir.3 @@ -0,0 +1,108 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:25:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.TH SEEKDIR 3 2016-03-15 "" "Linux Programmer's Manual" +.SH NAME +seekdir \- set the position of the next readdir() call in the directory +stream. +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void seekdir(DIR *" dirp ", long " loc ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR seekdir (): + _XOPEN_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +The +.BR seekdir () +function sets the location in the directory stream +from which the next +.BR readdir (2) +call will start. +The +.I loc +argument should be a value returned by a previous call to +.BR telldir (3). +.SH RETURN VALUE +The +.BR seekdir () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR seekdir () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH NOTES +In glibc up to version 2.1.1, the type of the +.I loc +argument was +.IR off_t . +POSIX.1-2001 specifies +.IR long , +and this is the type used since glibc 2.1.2. +See +.BR telldir (3) +for information on why you should be careful in making any +assumptions about the value in this argument. +.SH SEE ALSO +.BR lseek (2), +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR telldir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sem_close.3 b/man3/sem_close.3 new file mode 100644 index 0000000..1f26618 --- /dev/null +++ b/man3/sem_close.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_CLOSE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_close \- close a named semaphore +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sem_close(sem_t *" sem ); +.fi +.PP +Link with \fI\-pthread\fP. +.SH DESCRIPTION +.BR sem_close () +closes the named semaphore referred to by +.IR sem , +allowing any resources that the system has allocated to +the calling process for this semaphore to be freed. +.SH RETURN VALUE +On success +.BR sem_close () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sem_close () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +All open named semaphores are automatically closed on process +termination, or upon +.BR execve (2). +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR sem_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sem_destroy.3 b/man3/sem_destroy.3 new file mode 100644 index 0000000..ff4a745 --- /dev/null +++ b/man3/sem_destroy.3 @@ -0,0 +1,99 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_DESTROY 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_destroy \- destroy an unnamed semaphore +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sem_destroy(sem_t *" sem ); +.fi +.PP +Link with \fI\-pthread\fP. +.SH DESCRIPTION +.BR sem_destroy () +destroys the unnamed semaphore at the address pointed to by +.IR sem . +.PP +Only a semaphore that has been initialized by +.BR sem_init (3) +should be destroyed using +.BR sem_destroy (). +.PP +Destroying a semaphore that other processes or threads are +currently blocked on (in +.BR sem_wait (3)) +produces undefined behavior. +.PP +Using a semaphore that has been destroyed produces undefined results, +until the semaphore has been reinitialized using +.BR sem_init (3). +.SH RETURN VALUE +.BR sem_destroy () +returns 0 on success; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sem_destroy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +An unnamed semaphore should be destroyed with +.BR sem_destroy () +before the memory in which it is located is deallocated. +Failure to do this can result in resource leaks on some implementations. +.\" But not on NPTL, where sem_destroy () is a no-op.. +.SH SEE ALSO +.BR sem_init (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sem_getvalue.3 b/man3/sem_getvalue.3 new file mode 100644 index 0000000..8e0b7fc --- /dev/null +++ b/man3/sem_getvalue.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_GETVALUE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_getvalue \- get the value of a semaphore +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sem_getvalue(sem_t *" sem ", int *" sval ); +.fi +.PP +Link with \fI\-pthread\fP. +.SH DESCRIPTION +.BR sem_getvalue () +places the current value of the semaphore pointed to +.I sem +into the integer pointed to by +.IR sval . +.PP +If one or more processes or threads are blocked +waiting to lock the semaphore with +.BR sem_wait (3), +POSIX.1 permits two possibilities for the value returned in +.IR sval : +either 0 is returned; +or a negative number whose absolute value is the count +of the number of processes and threads currently blocked in +.BR sem_wait (3). +Linux adopts the former behavior. +.SH RETURN VALUE +.BR sem_getvalue () +returns 0 on success; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sem_getvalue () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The value of the semaphore may already have changed by the time +.BR sem_getvalue () +returns. +.SH SEE ALSO +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sem_init.3 b/man3/sem_init.3 new file mode 100644 index 0000000..a1cd493 --- /dev/null +++ b/man3/sem_init.3 @@ -0,0 +1,127 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_INIT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_init \- initialize an unnamed semaphore +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sem_init(sem_t *" sem ", int " pshared ", unsigned int " value ); +.fi +.PP +Link with \fI\-pthread\fP. +.SH DESCRIPTION +.BR sem_init () +initializes the unnamed semaphore at the address pointed to by +.IR sem . +The +.I value +argument specifies the initial value for the semaphore. +.PP +The +.I pshared +argument indicates whether this semaphore is to be shared +between the threads of a process, or between processes. +.PP +If +.I pshared +has the value 0, +then the semaphore is shared between the threads of a process, +and should be located at some address that is visible to all threads +(e.g., a global variable, or a variable allocated dynamically on +the heap). +.PP +If +.I pshared +is nonzero, then the semaphore is shared between processes, +and should be located in a region of shared memory (see +.BR shm_open (3), +.BR mmap (2), +and +.BR shmget (2)). +(Since a child created by +.BR fork (2) +inherits its parent's memory mappings, it can also access the semaphore.) +Any process that can access the shared memory region +can operate on the semaphore using +.BR sem_post (3), +.BR sem_wait (3), +and so on. +.PP +Initializing a semaphore that has already been initialized +results in undefined behavior. +.SH RETURN VALUE +.BR sem_init () +returns 0 on success; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I value +exceeds +.BR SEM_VALUE_MAX . +.TP +.B ENOSYS +.I pshared +is nonzero, +but the system does not support process-shared semaphores (see +.BR sem_overview (7)). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sem_init () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES +Bizarrely, POSIX.1-2001 does not specify the value that should +be returned by a successful call to +.BR sem_init (). +POSIX.1-2008 rectifies this, specifying the zero return on success. +.SH SEE ALSO +.BR sem_destroy (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sem_open.3 b/man3/sem_open.3 new file mode 100644 index 0000000..3bbbc6a --- /dev/null +++ b/man3/sem_open.3 @@ -0,0 +1,200 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_OPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_open \- initialize and open a named semaphore +.SH SYNOPSIS +.nf +.BR "#include " " /* For O_* constants */" +.BR "#include " " /* For mode constants */" +.B #include +.PP +.BI "sem_t *sem_open(const char *" name ", int " oflag ); +.BI "sem_t *sem_open(const char *" name ", int " oflag ", " +.BI " mode_t " mode ", unsigned int " value ); +.fi +.PP +Link with \fI\-pthread\fP. +.SH DESCRIPTION +.BR sem_open () +creates a new POSIX semaphore or opens an existing semaphore. +The semaphore is identified by +.IR name . +For details of the construction of +.IR name , +see +.BR sem_overview (7). +.PP +The +.I oflag +argument specifies flags that control the operation of the call. +(Definitions of the flags values can be obtained by including +.IR .) +If +.B O_CREAT +is specified in +.IR oflag , +then the semaphore is created if +it does not already exist. +The owner (user ID) of the semaphore is set to the effective +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID +of the calling process. +.\" In reality the filesystem IDs are used on Linux. +If both +.B O_CREAT +and +.B O_EXCL +are specified in +.IR oflag , +then an error is returned if a semaphore with the given +.I name +already exists. +.PP +If +.B O_CREAT +is specified in +.IR oflag , +then two additional arguments must be supplied. +The +.I mode +argument specifies the permissions to be placed on the new semaphore, +as for +.BR open (2). +(Symbolic definitions for the permissions bits can be obtained by including +.IR .) +The permissions settings are masked against the process umask. +Both read and write permission should be granted to each class of +user that will access the semaphore. +The +.I value +argument specifies the initial value for the new semaphore. +If +.B O_CREAT +is specified, and a semaphore with the given +.I name +already exists, then +.I mode +and +.I value +are ignored. +.SH RETURN VALUE +On success, +.BR sem_open () +returns the address of the new semaphore; +this address is used when calling other semaphore-related functions. +On error, +.BR sem_open () +returns +.BR SEM_FAILED , +with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The semaphore exists, but the caller does not have permission to +open it. +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified in +.IR oflag , +but a semaphore with this +.I name +already exists. +.TP +.B EINVAL +.I value +was greater than +.BR SEM_VALUE_MAX . +.TP +.B EINVAL +.I name +consists of just "/", followed by no other characters. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The +.B O_CREAT +flag was not specified in +.IR oflag +and no semaphore with this +.I name +exists; +or, +.\" this error can occur if we have a name of the (nonportable) form +.\" /dir/name, and the directory /dev/shm/dir does not exist. +.B O_CREAT +was specified, but +.I name +wasn't well formed. +.TP +.B ENOMEM +Insufficient memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sem_open () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR sem_close (3), +.BR sem_getvalue (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR sem_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sem_post.3 b/man3/sem_post.3 new file mode 100644 index 0000000..6c7233d --- /dev/null +++ b/man3/sem_post.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_POST 3 2017-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_post \- unlock a semaphore +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sem_post(sem_t *" sem ); +.fi +.PP +Link with \fI\-pthread\fP. +.SH DESCRIPTION +.BR sem_post () +increments (unlocks) the semaphore pointed to by +.IR sem . +If the semaphore's value consequently becomes greater than zero, +then another process or thread blocked in a +.BR sem_wait (3) +call will be woken up and proceed to lock the semaphore. +.SH RETURN VALUE +.BR sem_post () +returns 0 on success; +on error, the value of the semaphore is left unchanged, +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.TP +.B EOVERFLOW +.\" Added in POSIX.1-2008 TC1 (Austin Interpretation 213) +The maximum allowable value for a semaphore would be exceeded. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sem_post () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES +.BR sem_post () +is async-signal-safe: +it may be safely called within a signal handler. +.SH EXAMPLE +See +.BR sem_wait (3). +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_wait (3), +.BR sem_overview (7), +.BR signal-safety (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sem_timedwait.3 b/man3/sem_timedwait.3 new file mode 100644 index 0000000..c7b43fa --- /dev/null +++ b/man3/sem_timedwait.3 @@ -0,0 +1 @@ +.so man3/sem_wait.3 diff --git a/man3/sem_trywait.3 b/man3/sem_trywait.3 new file mode 100644 index 0000000..c7b43fa --- /dev/null +++ b/man3/sem_trywait.3 @@ -0,0 +1 @@ +.so man3/sem_wait.3 diff --git a/man3/sem_unlink.3 b/man3/sem_unlink.3 new file mode 100644 index 0000000..6ae209b --- /dev/null +++ b/man3/sem_unlink.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_UNLINK 3 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_unlink \- remove a named semaphore +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sem_unlink(const char *" name ); +.fi +.PP +Link with \fI\-pthread\fP. +.SH DESCRIPTION +.BR sem_unlink () +removes the named semaphore referred to by +.IR name . +The semaphore name is removed immediately. +The semaphore is destroyed once all other processes that have +the semaphore open close it. +.SH RETURN VALUE +On success +.BR sem_unlink () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to unlink this semaphore. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENOENT +There is no semaphore with the given +.IR name . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sem_unlink () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sem_wait.3 b/man3/sem_wait.3 new file mode 100644 index 0000000..1efb216 --- /dev/null +++ b/man3/sem_wait.3 @@ -0,0 +1,282 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_WAIT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_wait, sem_timedwait, sem_trywait \- lock a semaphore +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sem_wait(sem_t *" sem ); +.PP +.BI "int sem_trywait(sem_t *" sem ); +.PP +.BI "int sem_timedwait(sem_t *" sem ", const struct timespec *" abs_timeout ); +.fi +.PP +Link with \fI\-pthread\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR sem_timedwait (): +_POSIX_C_SOURCE\ >=\ 200112L +.SH DESCRIPTION +.BR sem_wait () +decrements (locks) the semaphore pointed to by +.IR sem . +If the semaphore's value is greater than zero, +then the decrement proceeds, and the function returns, immediately. +If the semaphore currently has the value zero, +then the call blocks until either it becomes possible to perform +the decrement (i.e., the semaphore value rises above zero), +or a signal handler interrupts the call. +.PP +.BR sem_trywait () +is the same as +.BR sem_wait (), +except that if the decrement cannot be immediately performed, +then call returns an error +.RI ( errno +set to +.BR EAGAIN ) +instead of blocking. +.PP +.BR sem_timedwait () +is the same as +.BR sem_wait (), +except that +.I abs_timeout +specifies a limit on the amount of time that the call +should block if the decrement cannot be immediately performed. +The +.I abs_timeout +argument points to a structure that specifies an absolute timeout +in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +This structure is defined as follows: +.PP +.in +4n +.EX +struct timespec { + time_t tv_sec; /* Seconds */ + long tv_nsec; /* Nanoseconds [0 .. 999999999] */ +}; +.EE +.in +.PP +If the timeout has already expired by the time of the call, +and the semaphore could not be locked immediately, +then +.BR sem_timedwait () +fails with a timeout error +.RI ( errno +set to +.BR ETIMEDOUT ). +.PP +If the operation can be performed immediately, then +.BR sem_timedwait () +never fails with a timeout error, regardless of the value of +.IR abs_timeout . +Furthermore, the validity of +.I abs_timeout +is not checked in this case. +.SH RETURN VALUE +All of these functions return 0 on success; +on error, the value of the semaphore is left unchanged, +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.PP +The following additional error can occur for +.BR sem_trywait (): +.TP +.B EAGAIN +The operation could not be performed without blocking (i.e., the +semaphore currently has the value zero). +.PP +The following additional errors can occur for +.BR sem_timedwait (): +.TP +.B EINVAL +The value of +.I abs_timeout.tv_nsecs +is less than 0, or greater than or equal to 1000 million. +.TP +.B ETIMEDOUT +The call timed out before the semaphore could be locked. +.\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition +.\" was detected", but this does not occur on Linux(?). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw26 lb lb +l l l. +Interface Attribute Value +T{ +.BR sem_wait (), +.BR sem_trywait (), +.BR sem_timedwait () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +.PP +The (somewhat trivial) program shown below operates on an +unnamed semaphore. +The program expects two command-line arguments. +The first argument specifies a seconds value that is used to +set an alarm timer to generate a +.B SIGALRM +signal. +This handler performs a +.BR sem_post (3) +to increment the semaphore that is being waited on in +.I main() +using +.BR sem_timedwait (). +The second command-line argument specifies the length +of the timeout, in seconds, for +.BR sem_timedwait (). +The following shows what happens on two different runs of the program: +.PP +.in +4n +.EX +.RB "$" " ./a.out 2 3" +About to call sem_timedwait() +sem_post() from handler +sem_timedwait() succeeded +.RB "$" " ./a.out 2 1" +About to call sem_timedwait() +sem_timedwait() timed out +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +#include +#include + +sem_t sem; + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +static void +handler(int sig) +{ + write(STDOUT_FILENO, "sem_post() from handler\\n", 24); + if (sem_post(&sem) == \-1) { + write(STDERR_FILENO, "sem_post() failed\\n", 18); + _exit(EXIT_FAILURE); + } +} + +int +main(int argc, char *argv[]) +{ + struct sigaction sa; + struct timespec ts; + int s; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", + argv[0]); + exit(EXIT_FAILURE); + } + + if (sem_init(&sem, 0, 0) == \-1) + handle_error("sem_init"); + + /* Establish SIGALRM handler; set alarm timer using argv[1] */ + + sa.sa_handler = handler; + sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + if (sigaction(SIGALRM, &sa, NULL) == \-1) + handle_error("sigaction"); + + alarm(atoi(argv[1])); + + /* Calculate relative interval as current time plus + number of seconds given argv[2] */ + + if (clock_gettime(CLOCK_REALTIME, &ts) == \-1) + handle_error("clock_gettime"); + + ts.tv_sec += atoi(argv[2]); + + printf("main() about to call sem_timedwait()\\n"); + while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR) + continue; /* Restart if interrupted by handler */ + + /* Check what happened */ + + if (s == \-1) { + if (errno == ETIMEDOUT) + printf("sem_timedwait() timed out\\n"); + else + perror("sem_timedwait"); + } else + printf("sem_timedwait() succeeded\\n"); + + exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE); +} +.EE +.SH SEE ALSO +.BR clock_gettime (2), +.BR sem_getvalue (3), +.BR sem_post (3), +.BR sem_overview (7), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/setaliasent.3 b/man3/setaliasent.3 new file mode 100644 index 0000000..213b002 --- /dev/null +++ b/man3/setaliasent.3 @@ -0,0 +1,183 @@ +.\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Polished a bit, added a little, aeb +.\" +.TH SETALIASENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +setaliasent, endaliasent, getaliasent, getaliasent_r, +getaliasbyname, getaliasbyname_r \- read an alias entry +.SH SYNOPSIS +.B #include +.PP +.B "void setaliasent(void);" +.PP +.B "void endaliasent(void);" +.PP +.B "struct aliasent *getaliasent(void);" +.PP +.BI "int getaliasent_r(struct aliasent *" result "," +.br +.BI " char *" buffer ", size_t " buflen ", struct aliasent **" res ); +.PP +.BI "struct aliasent *getaliasbyname(const char *" name ); +.PP +.BI "int getaliasbyname_r(const char *" name ", struct aliasent *" result , +.br +.BI " char *" buffer ", size_t " buflen ", struct aliasent **" res ); +.SH DESCRIPTION +One of the databases available with the Name Service Switch (NSS) +is the aliases database, that contains mail aliases. +(To find out which databases are supported, try +.IR "getent \-\-help" .) +Six functions are provided to access the aliases database. +.PP +The +.BR getaliasent () +function returns a pointer to a structure containing +the group information from the aliases database. +The first time it is called it returns the first entry; +thereafter, it returns successive entries. +.PP +The +.BR setaliasent () +function rewinds the file pointer to the beginning of the +aliases database. +.PP +The +.BR endaliasent () +function closes the aliases database. +.PP +.BR getaliasent_r () +is the reentrant version of the previous function. +The requested structure +is stored via the first argument but the programmer needs to fill the other +arguments also. +Not providing enough space causes the function to fail. +.PP +The function +.BR getaliasbyname () +takes the name argument and searches the aliases database. +The entry is returned as a pointer to a +.IR "struct aliasent" . +.PP +.BR getaliasbyname_r () +is the reentrant version of the previous function. +The requested structure +is stored via the second argument but the programmer needs to fill the other +arguments also. +Not providing enough space causes the function to fail. +.PP +The +.I "struct aliasent" +is defined in +.IR : +.PP +.in +4n +.EX +struct aliasent { + char *alias_name; /* alias name */ + size_t alias_members_len; + char **alias_members; /* alias name list */ + int alias_local; +}; +.EE +.in +.SH RETURN VALUE +The functions +.BR getaliasent_r () +and +.BR getaliasbyname_r () +return a nonzero value on error. +.SH FILES +The default alias database is the file +.IR /etc/aliases . +This can be changed in the +.I /etc/nsswitch.conf +file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR setaliasent (), +.BR endaliasent (), +.BR getaliasent_r (), +.BR getaliasbyname_r () +T} Thread safety MT-Safe locale +T{ +.BR getaliasent (), +.BR getaliasbyname () +T} Thread safety MT-Unsafe +.TE +.ad +.SH CONFORMING TO +These routines are glibc-specific. +The NeXT system has similar routines: +.PP +.in +4n +.EX +#include + +void alias_setent(void); +void alias_endent(void); +alias_ent *alias_getent(void); +alias_ent *alias_getbyname(char *name); +.EE +.in +.SH EXAMPLE +The following example compiles with +.IR "gcc example.c \-o example" . +It will dump all names in the alias database. +.PP +.EX +#include +#include +#include +#include + +int +main(void) +{ + struct aliasent *al; + setaliasent(); + for (;;) { + al = getaliasent(); + if (al == NULL) + break; + printf("Name: %s\\n", al\->alias_name); + } + if (errno) { + perror("reading alias"); + exit(EXIT_FAILURE); + } + endaliasent(); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR getgrent (3), +.BR getpwent (3), +.BR getspent (3), +.BR aliases (5) +.\" +.\" /etc/sendmail/aliases +.\" Yellow Pages +.\" newaliases, postalias +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/setbuf.3 b/man3/setbuf.3 new file mode 100644 index 0000000..32fc212 --- /dev/null +++ b/man3/setbuf.3 @@ -0,0 +1,234 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)setbuf.3 6.10 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu +.\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995, +.\" Thomas.Koenig@ciw.uni-karlsruhe.de +.\" Correction, Sun, 11 Apr 1999 15:55:18, +.\" Martin Vicente +.\" Correction, 2000-03-03, Andreas Jaeger +.\" Added return value for setvbuf, aeb, +.\" +.TH SETBUF 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void setbuf(FILE *" stream ", char *" buf ); +.PP +.BI "void setbuffer(FILE *" stream ", char *" buf ", size_t " size ); +.PP +.BI "void setlinebuf(FILE *" stream ); +.PP +.BI "int setvbuf(FILE *" stream ", char *" buf ", int " mode \ +", size_t " size ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR setbuffer (), +.BR setlinebuf (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The three types of buffering available are unbuffered, block buffered, and +line buffered. +When an output stream is unbuffered, information appears on +the destination file or terminal as soon as written; when it is block +buffered many characters are saved up and written as a block; when it is +line buffered characters are saved up until a newline is output or input is +read from any stream attached to a terminal device (typically \fIstdin\fP). +The function +.BR fflush (3) +may be used to force the block out early. +(See +.BR fclose (3).) +.PP +Normally all files are block buffered. +If a stream refers to a terminal (as +.I stdout +normally does), it is line buffered. +The standard error stream +.I stderr +is always unbuffered by default. +.PP +The +.BR setvbuf () +function may be used on any open stream to change its buffer. +The +.I mode +argument must be one of the following three macros: +.RS +.TP +.B _IONBF +unbuffered +.TP +.B _IOLBF +line buffered +.TP +.B _IOFBF +fully buffered +.RE +.PP +Except for unbuffered files, the +.I buf +argument should point to a buffer at least +.I size +bytes long; this buffer will be used instead of the current buffer. +If the argument +.I buf +is NULL, +only the mode is affected; a new buffer will be allocated on the next read +or write operation. +The +.BR setvbuf () +function may be used only after opening a stream and before any other +operations have been performed on it. +.PP +The other three calls are, in effect, simply aliases for calls to +.BR setvbuf (). +The +.BR setbuf () +function is exactly equivalent to the call +.PP +.in +4n +setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); +.in +.PP +The +.BR setbuffer () +function is the same, except that the size of the buffer is up to the +caller, rather than being determined by the default +.BR BUFSIZ . +The +.BR setlinebuf () +function is exactly equivalent to the call: +.PP +.in +4n +setvbuf(stream, NULL, _IOLBF, 0); +.in +.SH RETURN VALUE +The function +.BR setvbuf () +returns 0 on success. +It returns nonzero on failure +.RI ( mode +is invalid or the request cannot be honored). +It may set +.I errno +on failure. +.PP +The other functions do not return a value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR setbuf (), +.BR setbuffer (), +.br +.BR setlinebuf (), +.BR setvbuf () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The +.BR setbuf () +and +.BR setvbuf () +functions conform to C89 and C99. +.SH BUGS +.\" The +.\" .BR setbuffer () +.\" and +.\" .BR setlinebuf () +.\" functions are not portable to versions of BSD before 4.2BSD, and +.\" are available under Linux since libc 4.5.21. +.\" On 4.2BSD and 4.3BSD systems, +.\" .BR setbuf () +.\" always uses a suboptimal buffer size and should be avoided. +.PP +You must make sure that the space that +.I buf +points to still exists by the time +.I stream +is closed, which also happens at program termination. +For example, the following is invalid: +.PP +.EX +#include + +int +main(void) +{ + char buf[BUFSIZ]; + setbuf(stdin, buf); + printf("Hello, world!\\n"); + return 0; +} +.EE +.SH SEE ALSO +.BR stdbuf (1), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR fread (3), +.BR malloc (3), +.BR printf (3), +.BR puts (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/setbuffer.3 b/man3/setbuffer.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man3/setbuffer.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man3/setcontext.3 b/man3/setcontext.3 new file mode 100644 index 0000000..b01818d --- /dev/null +++ b/man3/setcontext.3 @@ -0,0 +1 @@ +.so man3/getcontext.3 diff --git a/man3/setenv.3 b/man3/setenv.3 new file mode 100644 index 0000000..8868e22 --- /dev/null +++ b/man3/setenv.3 @@ -0,0 +1,182 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2004, 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:20:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 9 Jun 2004, Michael Kerrisk +.\" Changed unsetenv() prototype; added EINVAL error +.\" Noted nonstandard behavior of setenv() if name contains '=' +.\" 2005-08-12, mtk, glibc 2.3.4 fixed the "name contains '='" bug +.\" +.TH SETENV 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +setenv \- change or add an environment variable +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int setenv(const char *" name ", const char *" value ", int " overwrite ); +.PP +.BI "int unsetenv(const char *" name ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR setenv (), +.BR unsetenv (): +.RS 4 +_POSIX_C_SOURCE\ >=\ 200112L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR setenv () +function adds the variable +.I name +to the +environment with the value +.IR value , +if +.I name +does not +already exist. +If +.I name +does exist in the environment, then +its value is changed to +.IR value +if +.I overwrite +is nonzero; +if +.IR overwrite +is zero, then the value of +.I name +is not changed (and +.BR setenv () +returns a success status). +This function makes copies of the strings pointed to by +.I name +and +.I value +(by contrast with +.BR putenv (3)). +.PP +The +.BR unsetenv () +function deletes the variable +.I name +from +the environment. +If +.I name +does not exist in the environment, +then the function succeeds, and the environment is unchanged. +.SH RETURN VALUE +The +.BR setenv () +function returns zero on success, +or \-1 on error, with +.I errno +set to indicate the cause of the error. +.PP +The +.BR unsetenv () +function returns zero on success, +or \-1 on error, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +.I name +is NULL, points to a string of length 0, +or contains an \(aq=\(aq character. +.TP +.B ENOMEM +Insufficient memory to add a new variable to the environment. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR setenv (), +.BR unsetenv () +T} Thread safety MT-Unsafe const:env +.TE +.ad +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH NOTES +POSIX.1 does not require +.BR setenv () +or +.BR unsetenv () +to be reentrant. +.PP +Prior to glibc 2.2.2, +.BR unsetenv () +was prototyped +as returning +.IR void ; +more recent glibc versions follow the +POSIX.1-compliant prototype shown in the SYNOPSIS. +.SH BUGS +POSIX.1 specifies that if +.I name +contains an \(aq=\(aq character, then +.BR setenv () +should fail with the error +.BR EINVAL ; +however, versions of glibc before 2.3.4 allowed an \(aq=\(aq sign in +.IR name . +.SH SEE ALSO +.BR clearenv (3), +.BR getenv (3), +.BR putenv (3), +.BR environ (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/setfsent.3 b/man3/setfsent.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man3/setfsent.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man3/setgrent.3 b/man3/setgrent.3 new file mode 100644 index 0000000..bde736f --- /dev/null +++ b/man3/setgrent.3 @@ -0,0 +1 @@ +.so man3/getgrent.3 diff --git a/man3/sethostent.3 b/man3/sethostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man3/sethostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man3/sethostid.3 b/man3/sethostid.3 new file mode 100644 index 0000000..3210db0 --- /dev/null +++ b/man3/sethostid.3 @@ -0,0 +1 @@ +.so man3/gethostid.3 diff --git a/man3/setjmp.3 b/man3/setjmp.3 new file mode 100644 index 0000000..afd5026 --- /dev/null +++ b/man3/setjmp.3 @@ -0,0 +1,338 @@ +.\" Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH SETJMP 3 2017-03-13 "" "Linux Programmer's Manual" +.SH NAME +setjmp, sigsetjmp, longjmp, siglongjmp \- performing a nonlocal goto +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int setjmp(jmp_buf " env ); +.BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs ); +.PP +.BI "void longjmp(jmp_buf " env ", int " val ); +.BI "void siglongjmp(sigjmp_buf " env ", int " val ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR setjmp (): +see NOTES. +.PP +.BR sigsetjmp (): +_POSIX_C_SOURCE +.SH DESCRIPTION +The functions described on this page are used for performing "nonlocal gotos": +transferring execution from one function to a predetermined location +in another function. +The +.BR setjmp () +function dynamically establishes the target to which control +will later be transferred, and +.BR longjmp () +performs the transfer of execution. +.PP +The +.BR setjmp () +function saves various information about the calling environment +(typically, the stack pointer, the instruction pointer, +possibly the values of other registers and the signal mask) +in the buffer +.IR env +for later use by +.BR longjmp (). +In this case, +.BR setjmp () +returns 0. +.PP +The +.BR longjmp () +function uses the information saved in +.IR env +to transfer control back to the point where +.BR setjmp () +was called and to restore ("rewind") the stack to its state at the time of the +.BR setjmp () +call. +In addition, and depending on the implementation (see NOTES), +the values of some other registers and the process signal mask +may be restored to their state at the time of the +.BR setjmp () +call. +.PP +Following a successful +.BR longjmp (), +execution continues as if +.BR setjmp () +had returned for a second time. +This "fake" return can be distinguished from a true +.BR setjmp () +call because the "fake" return returns the value provided in +.IR val . +If the programmer mistakenly passes the value 0 in +.IR val , +the "fake" return will instead return 1. +.PP +.SS sigsetjmp() and siglongjmp() +.BR sigsetjmp () +and +.BR siglongjmp () +also perform nonlocal gotos, but provide predictable handling of +the process signal mask. +.PP +If, and only if, the +.I savesigs +argument provided to +.BR sigsetjmp () +is nonzero, the process's current signal mask is saved in +.I env +and will be restored if a +.BR siglongjmp () +is later performed with this +.IR env . +.SH RETURN VALUE +.BR setjmp () +and +.BR sigsetjmp () +return 0 when called directly; +on the "fake" return that occurs after +.BR longjmp () +or +.BR siglongjmp (), +the nonzero value specified in +.I val +is returned. +.PP +The +.BR longjmp () +or +.BR siglongjmp () +functions do not return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR setjmp (), +.BR sigsetjmp () +T} Thread safety MT-Safe +T{ +.BR longjmp (), +.BR siglongjmp () +T} Thread safety MT-Safe +.TE +.PP +.SH CONFORMING TO +.BR setjmp (), +.BR longjmp (): +POSIX.1-2001, POSIX.1-2008, C89, C99. +.PP +.BR sigsetjmp (), +.BR siglongjmp (): +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +POSIX does not specify whether +.BR setjmp () +will save the signal mask +(to be later restored during +.BR longjmp ()). +In System V it will not. +In 4.3BSD it will, and there +is a function +.BR _setjmp () +that will not. +The behavior under Linux depends on the glibc version +and the setting of feature test macros. +On Linux with glibc versions before 2.19, +.BR setjmp () +follows the System V behavior by default, +but the BSD behavior is provided if the +.BR _BSD_SOURCE +feature test macro is explicitly defined +.\" so that _FAVOR_BSD is triggered +and none of +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.\" .BR _XOPEN_SOURCE_EXTENDED , +.BR _GNU_SOURCE , +or +.B _SVID_SOURCE +is defined. +Since glibc 2.19, +.IR +exposes only the System V version of +.BR setjmp (). +Programs that need the BSD semantics should replace calls to +.BR setjmp () +with calls to +.BR sigsetjmp () +with a nonzero +.I savesigs +argument. +.PP +.BR setjmp () +and +.BR longjmp () +can be useful for dealing with errors inside deeply nested function calls +or to allow a signal handler to pass control to +a specific point in the program, +rather than returning to the point where the handler interrupted +the main program. +In the latter case, +if you want to portably save and restore signal masks, use +.BR sigsetjmp () +and +.BR siglongjmp (). +See also the discussion of program readability below. +.PP +The compiler may optimize variables into registers, and +.BR longjmp () +may restore the values of other registers in addition to the +stack pointer and program counter. +Consequently, the values of automatic variables are unspecified +after a call to +.BR longjmp () +if they meet all the following criteria: +.IP \(bu 3 +they are local to the function that made the corresponding +.BR setjmp () +call; +.IP \(bu +their values are changed between the calls to +.BR setjmp () +and +.BR longjmp (); +and +.IP \(bu +they are not declared as +.IR volatile . +.PP +Analogous remarks apply for +.BR siglongjmp (). +.\" +.SS Nonlocal gotos and program readability +While it can be abused, +the traditional C "goto" statement at least has the benefit that lexical cues +(the goto statement and the target label) +allow the programmer to easily perceive the flow of control. +Nonlocal gotos provide no such cues: multiple +.BR setjmp () +calls might employ the same +.IR jmp_buf +variable so that the content of the variable may change +over the lifetime of the application. +Consequently, the programmer may be forced to perform detailed +reading of the code to determine the dynamic target of a particular +.BR longjmp () +call. +(To make the programmer's life easier, each +.BR setjmp () +call should employ a unique +.IR jmp_buf +variable.) +.PP +Adding further difficulty, the +.BR setjmp () +and +.BR longjmp () +calls may not even be in the same source code module. +.PP +In summary, nonlocal gotos can make programs harder to understand +and maintain, and an alternative should be used if possible. +.\" +.SS Caveats +If the function which called +.BR setjmp () +returns before +.BR longjmp () +is called, the behavior is undefined. +Some kind of subtle or unsubtle chaos is sure to result. +.PP +If, in a multithreaded program, a +.BR longjmp () +call employs an +.I env +buffer that was initialized by a call to +.BR setjmp () +in a different thread, the behavior is undefined. +.\" +.\" The following statement appeared in versions up to POSIX.1-2008 TC1, +.\" but is set to be removed in POSIX.1-2008 TC2: +.\" +.\" According to POSIX.1, if a +.\" .BR longjmp () +.\" call is performed from a nested signal handler +.\" (i.e., from a handler that was invoked in response to a signal that was +.\" generated while another signal was already in the process of being +.\" handled), the behavior is undefined. +.PP +POSIX.1-2008 Technical Corrigendum 2 adds +.\" http://austingroupbugs.net/view.php?id=516#c1195 +.BR longjmp () +and +.BR siglongjmp () +to the list of async-signal-safe functions. +However, the standard recommends avoiding the use of these functions +from signal handlers and goes on to point out that +if these functions are called from a signal handler that interrupted +a call to a non-async-signal-safe function (or some equivalent, +such as the steps equivalent to +.BR exit (3) +that occur upon a return from the initial call to +.IR main ()), +the behavior is undefined if the program subsequently makes a call to +a non-async-signal-safe function. +The only way of avoiding undefined behavior is to ensure one of the following: +.IP * 3 +After long jumping from the signal handler, +the program does not call any non-async-signal-safe functions +and does not return from the initial call to +.IR main (). +.IP * +Any signal whose handler performs a long jump must be blocked during +.I every +call to a non-async-signal-safe function and +no non-async-signal-safe functions are called after +returning from the initial call to +.IR main (). +.SH SEE ALSO +.BR signal (7), +.BR signal-safety (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/setkey.3 b/man3/setkey.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man3/setkey.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man3/setkey_r.3 b/man3/setkey_r.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man3/setkey_r.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man3/setlinebuf.3 b/man3/setlinebuf.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man3/setlinebuf.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man3/setlocale.3 b/man3/setlocale.3 new file mode 100644 index 0000000..f8bdd23 --- /dev/null +++ b/man3/setlocale.3 @@ -0,0 +1,222 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 1999 by Bruno Haible (haible@clisp.cons.org) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 18:20:12 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Jul 15 16:49:10 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Jul 4 14:52:16 1999 by Bruno Haible (haible@clisp.cons.org) +.\" Modified Tue Aug 24 17:11:01 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Tue Feb 6 03:31:55 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH SETLOCALE 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +setlocale \- set the current locale +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *setlocale(int " category ", const char *" locale ); +.fi +.SH DESCRIPTION +The +.BR setlocale () +function is used to set or query the program's current locale. +.PP +If +.I locale +is not NULL, +the program's current locale is modified according to the arguments. +The argument +.I category +determines which parts of the program's current locale should be modified. +.TS +lB lB +lB l. +Category Governs +LC_ALL All of the locale +LC_ADDRESS T{ +Formatting of addresses and +.br +geography-related items (*) +T} +LC_COLLATE String collation +LC_CTYPE Character classification +LC_IDENTIFICATION Metadata describing the locale (*) +LC_MEASUREMENT T{ +Settings related to measurements +.br +(metric versus US customary) (*) +T} +LC_MESSAGES Localizable natural-language messages +LC_MONETARY Formatting of monetary values +LC_NAME Formatting of salutations for persons (*) +LC_NUMERIC Formatting of nonmonetary numeric values +LC_PAPER Settings related to the standard paper size (*) +LC_TELEPHONE Formats to be used with telephone services (*) +LC_TIME Formatting of date and time values +.TE +.PP +The categories marked with an asterisk in the above table +are GNU extensions. +For further information on these locale categories, see +.BR locale (7). +.PP +The argument +.I locale +is a pointer to a character string containing the +required setting of +.IR category . +Such a string is either a well-known constant like "C" or "da_DK" +(see below), or an opaque string that was returned by another call of +.BR setlocale (). +.PP +If +.I locale +is an empty string, +.BR """""" , +each part of the locale that should be modified is set according to the +environment variables. +The details are implementation-dependent. +For glibc, first (regardless of +.IR category ), +the environment variable +.B LC_ALL +is inspected, +next the environment variable with the same name as the category +(see the table above), +and finally the environment variable +.BR LANG . +The first existing environment variable is used. +If its value is not a valid locale specification, the locale +is unchanged, and +.BR setlocale () +returns NULL. +.PP +The locale +.B """C""" +or +.B """POSIX""" +is a portable locale; +it exists on all conforming systems. +.PP +A locale name is typically of the form +.IR language "[_" territory "][." codeset "][@" modifier "]," +where +.I language +is an ISO 639 language code, +.I territory +is an ISO 3166 country code, and +.I codeset +is a character set or encoding identifier like +.B "ISO-8859-1" +or +.BR "UTF-8" . +For a list of all supported locales, try "locale \-a" (see +.BR locale (1)). +.PP +If +.I locale +is NULL, the current locale is only queried, not modified. +.PP +On startup of the main program, the portable +.B """C""" +locale is selected as default. +A program may be made portable to all locales by calling: +.PP +.in +4n +.EX +setlocale(LC_ALL, ""); +.EE +.in +.PP +after program initialization, by using the values returned +from a +.BR localeconv (3) +call +for locale-dependent information, by using the multibyte and wide +character functions for text processing if +.BR "MB_CUR_MAX > 1" , +and by using +.BR strcoll (3), +.BR wcscoll (3) +or +.BR strxfrm (3), +.BR wcsxfrm (3) +to compare strings. +.SH RETURN VALUE +A successful call to +.BR setlocale () +returns an opaque string that corresponds to the locale set. +This string may be allocated in static storage. +The string returned is such that a subsequent call with that string +and its associated category will restore that part of the process's +locale. +The return value is NULL if the request cannot be honored. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw26 +l l l. +Interface Attribute Value +T{ +.BR setlocale () +T} Thread safety MT-Unsafe const:locale env +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.PP +The C standards specify only the categories +.BR LC_ALL , +.BR LC_COLLATE , +.BR LC_CTYPE , +.BR LC_MONETARY , +.BR LC_NUMERIC , +and +.BR LC_TIME . +POSIX.1 adds +.BR LC_MESSAGES . +The remaining categories are GNU extensions. +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR isalpha (3), +.BR localeconv (3), +.BR nl_langinfo (3), +.BR rpmatch (3), +.BR strcoll (3), +.BR strftime (3), +.BR charsets (7), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/setlogmask.3 b/man3/setlogmask.3 new file mode 100644 index 0000000..494cab5 --- /dev/null +++ b/man3/setlogmask.3 @@ -0,0 +1,103 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SETLOGMASK 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +setlogmask \- set log priority mask +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int setlogmask(int " mask ); +.fi +.SH DESCRIPTION +A process has a log priority mask that determines which calls to +.BR syslog (3) +may be logged. +All other calls will be ignored. +Logging is enabled for the priorities that have the corresponding +bit set in +.IR mask . +The initial mask is such that logging is enabled for all priorities. +.PP +The +.BR setlogmask () +function sets this logmask for the calling process, +and returns the previous mask. +If the mask argument is 0, the current logmask is not modified. +.PP +The eight priorities are +.BR LOG_EMERG , +.BR LOG_ALERT , +.BR LOG_CRIT , +.BR LOG_ERR , +.BR LOG_WARNING , +.BR LOG_NOTICE , +.BR LOG_INFO , +and +.BR LOG_DEBUG . +The bit corresponding to a priority +.I p +is +.IR LOG_MASK(p) . +Some systems also provide a macro +.IR LOG_UPTO(p) +for the mask +of all priorities in the above list up to and including +.IR p . +.SH RETURN VALUE +This function returns the previous log priority mask. +.SH ERRORS +None. +.\" .SH NOTES +.\" The glibc logmask handling was broken in versions before glibc 2.1.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw22 +l l l. +Interface Attribute Value +T{ +.BR setlogmask () +T} Thread safety MT-Unsafe race:LogMask +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.\" Note that the description in POSIX.1-2001 is flawed. +.SH SEE ALSO +.BR closelog (3), +.BR openlog (3), +.BR syslog (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/setmntent.3 b/man3/setmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man3/setmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man3/setnetent.3 b/man3/setnetent.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man3/setnetent.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man3/setnetgrent.3 b/man3/setnetgrent.3 new file mode 100644 index 0000000..3d63558 --- /dev/null +++ b/man3/setnetgrent.3 @@ -0,0 +1,166 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" based on glibc infopages +.\" polished - aeb +.\" +.TH SETNETGRENT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr \- +handle network group entries +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int setnetgrent(const char *" netgroup ); +.PP +.B "void endnetgrent(void);" +.PP +.BI "int getnetgrent(char **" host ", char **" user ", char **" domain ); +.PP +.BI "int getnetgrent_r(char **" host ", char **" user "," +.BI " char **" domain ", char *" buf ", size_t " buflen ); +.PP +.BI "int innetgr(const char *" netgroup ", const char *" host "," +.BI " const char *" user ", const char *" domain ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR setnetgrent (), +.BR endnetgrent (), +.BR getnetgrent (), +.BR getnetgrent_r (), +.BR innetgr (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.ad b +.SH DESCRIPTION +The +.I netgroup +is a SunOS invention. +A netgroup database is a list of string triples +.RI ( hostname ", " username ", " domainname ) +or other netgroup names. +Any of the elements in a triple can be empty, +which means that anything matches. +The functions described here allow access to the netgroup databases. +The file +.I /etc/nsswitch.conf +defines what database is searched. +.PP +The +.BR setnetgrent () +call defines the netgroup that will be searched by subsequent +.BR getnetgrent () +calls. +The +.BR getnetgrent () +function retrieves the next netgroup entry, and returns pointers in +.IR host , +.IR user , +.IR domain . +A null pointer means that the corresponding entry matches any string. +The pointers are valid only as long as there is no call to other +netgroup-related functions. +To avoid this problem you can use the GNU function +.BR getnetgrent_r () +that stores the strings in the supplied buffer. +To free all allocated buffers use +.BR endnetgrent (). +.PP +In most cases you want to check only if the triplet +.RI ( hostname ", " username ", " domainname ) +is a member of a netgroup. +The function +.BR innetgr () +can be used for this without calling the above three functions. +Again, a null pointer is a wildcard and matches any string. +The function is thread-safe. +.SH RETURN VALUE +These functions return 1 on success and 0 for failure. +.SH FILES +.I /etc/netgroup +.br +.I /etc/nsswitch.conf +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw16 lb lbw23 +l l l. +Interface Attribute Value +T{ +.BR setnetgrent (), +.br +.BR getnetgrent_r (), +.br +.BR innetgr () +T} Thread safety T{ +MT-Unsafe race:netgrent +.br +locale +T} +T{ +.BR endnetgrent () +T} Thread safety MT-Unsafe race:netgrent +T{ +.BR getnetgrent () +T} Thread safety T{ +MT-Unsafe race:netgrent +.br +race:netgrentbuf locale +T} +.TE +.sp 1 +In the above table, +.I netgrent +in +.I race:netgrent +signifies that if any of the functions +.BR setnetgrent (), +.BR getnetgrent_r (), +.BR innetgr (), +.BR getnetgrent (), +or +.BR endnetgrent () +are used in parallel in different threads of a program, +then data races could occur. +.SH CONFORMING TO +These functions are not in POSIX.1, but +.BR setnetgrent (), +.BR endnetgrent (), +.BR getnetgrent (), +and +.BR innetgr () +are available on most UNIX systems. +.BR getnetgrent_r () +is not widely available on other systems. +.\" getnetgrent_r() is on Solaris 8 and AIX 5.1, but not the BSDs. +.SH NOTES +In the BSD implementation, +.BR setnetgrent () +returns void. +.SH SEE ALSO +.BR sethostent (3), +.BR setprotoent (3), +.BR setservent (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/setprotoent.3 b/man3/setprotoent.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man3/setprotoent.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man3/setpwent.3 b/man3/setpwent.3 new file mode 100644 index 0000000..f2d121b --- /dev/null +++ b/man3/setpwent.3 @@ -0,0 +1 @@ +.so man3/getpwent.3 diff --git a/man3/setrpcent.3 b/man3/setrpcent.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man3/setrpcent.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man3/setservent.3 b/man3/setservent.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man3/setservent.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man3/setspent.3 b/man3/setspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/setspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/setstate.3 b/man3/setstate.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man3/setstate.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man3/setstate_r.3 b/man3/setstate_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man3/setstate_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man3/setttyent.3 b/man3/setttyent.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man3/setttyent.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man3/setusershell.3 b/man3/setusershell.3 new file mode 100644 index 0000000..718ed12 --- /dev/null +++ b/man3/setusershell.3 @@ -0,0 +1 @@ +.so man3/getusershell.3 diff --git a/man3/setutent.3 b/man3/setutent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/setutent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/setutxent.3 b/man3/setutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/setutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/setvbuf.3 b/man3/setvbuf.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man3/setvbuf.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man3/sgetspent.3 b/man3/sgetspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/sgetspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/sgetspent_r.3 b/man3/sgetspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/sgetspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/shm_open.3 b/man3/shm_open.3 new file mode 100644 index 0000000..65c8c54 --- /dev/null +++ b/man3/shm_open.3 @@ -0,0 +1,309 @@ +.\" Copyright (C) 2002 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" FIXME . Add an example to this page +.TH SHM_OPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +shm_open, shm_unlink \- create/open or unlink POSIX shared memory objects +.SH SYNOPSIS +.B #include +.br +.BR "#include " " /* For mode constants */" +.br +.BR "#include " " /* For O_* constants */" +.PP +.BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); +.PP +.BI "int shm_unlink(const char *" name ); +.PP +Link with \fI\-lrt\fP. +.SH DESCRIPTION +.BR shm_open () +creates and opens a new, or opens an existing, POSIX shared memory object. +A POSIX shared memory object is in effect a handle which can +be used by unrelated processes to +.BR mmap (2) +the same region of shared memory. +The +.BR shm_unlink () +function performs the converse operation, +removing an object previously created by +.BR shm_open (). +.PP +The operation of +.BR shm_open () +is analogous to that of +.BR open (2). +.I name +specifies the shared memory object to be created or opened. +For portable use, +a shared memory object should be identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.BI NAME_MAX +(i.e., 255) characters consisting of an initial slash, +.\" glibc allows the initial slash to be omitted, and makes +.\" multiple initial slashes equivalent to a single slash. +.\" This differs from the implementation of POSIX message queues. +followed by one or more characters, none of which are slashes. +.\" glibc allows subdirectory components in the name, in which +.\" case the subdirectory must exist under /dev/shm, and allow the +.\" required permissions if a user wants to create a shared memory +.\" object in that subdirectory. +.PP +.I oflag +is a bit mask created by ORing together exactly one of +.B O_RDONLY +or +.B O_RDWR +and any of the other flags listed here: +.TP 1.1i +.B O_RDONLY +Open the object for read access. +A shared memory object opened in this way can be +.BR mmap (2)ed +only for read +.RB ( PROT_READ ) +access. +.TP +.B O_RDWR +Open the object for read-write access. +.TP +.B O_CREAT +Create the shared memory object if it does not exist. +The user and group ownership of the object are taken +from the corresponding effective IDs of the calling process, +.\" In truth it is actually the filesystem IDs on Linux, but these +.\" are nearly always the same as the effective IDs. (MTK, Jul 05) +and the object's +permission bits are set according to the low-order 9 bits of +.IR mode , +except that those bits set in the process file mode +creation mask (see +.BR umask (2)) +are cleared for the new object. +A set of macro constants which can be used to define +.I mode +is listed in +.BR open (2). +(Symbolic definitions of these constants can be obtained by including +.IR .) +.IP +A new shared memory object initially has zero length\(emthe size of the +object can be set using +.BR ftruncate (2). +The newly allocated bytes of a shared memory +object are automatically initialized to 0. +.TP +.B O_EXCL +If +.B O_CREAT +was also specified, and a shared memory object with the given +.I name +already exists, return an error. +The check for the existence of the object, and its creation if it +does not exist, are performed atomically. +.TP +.B O_TRUNC +If the shared memory object already exists, truncate it to zero bytes. +.PP +Definitions of these flag values can be obtained by including +.IR . +.PP +On successful completion +.BR shm_open () +returns a new file descriptor referring to the shared memory object. +This file descriptor is guaranteed to be the lowest-numbered file descriptor +not previously opened within the process. +The +.B FD_CLOEXEC +flag (see +.BR fcntl (2)) +is set for the file descriptor. +.PP +The file descriptor is normally used in subsequent calls +to +.BR ftruncate (2) +(for a newly created object) and +.BR mmap (2). +After a call to +.BR mmap (2) +the file descriptor may be closed without affecting the memory mapping. +.PP +The operation +of +.BR shm_unlink () +is analogous to +.BR unlink (2): +it removes a shared memory object name, and, once all processes +have unmapped the object, de-allocates and +destroys the contents of the associated memory region. +After a successful +.BR shm_unlink (), +attempts to +.BR shm_open () +an object with the same +.I name +fail (unless +.B O_CREAT +was specified, in which case a new, distinct object is created). +.SH RETURN VALUE +On success, +.BR shm_open () +returns a nonnegative file descriptor. +On failure, +.BR shm_open () +returns \-1. +.BR shm_unlink () +returns 0 on success, or \-1 on error. +.SH ERRORS +On failure, +.I errno +is set to indicate the cause of the error. +Values which may appear in +.I errno +include the following: +.TP +.B EACCES +Permission to +.BR shm_unlink () +the shared memory object was denied. +.TP +.B EACCES +Permission was denied to +.BR shm_open () +.I name +in the specified +.IR mode , +or +.B O_TRUNC +was specified and the caller does not have write permission on the object. +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified to +.BR shm_open () +and the shared memory object specified by +.I name +already exists. +.TP +.B EINVAL +The +.I name +argument to +.BR shm_open () +was invalid. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +The length of +.I name +exceeds +.BR PATH_MAX . +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +An attempt was made to +.BR shm_open () +a +.I name +that did not exist, and +.B O_CREAT +was not specified. +.TP +.B ENOENT +An attempt was to made to +.BR shm_unlink () +a +.I name +that does not exist. +.SH VERSIONS +These functions are provided in glibc 2.2 and later. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR shm_open (), +.BR shm_unlink () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.PP +POSIX.1-2001 says that the group ownership of a newly created shared +memory object is set to either the calling process's effective group ID +or "a system default group ID". +POSIX.1-2008 says that the group ownership +may be set to either the calling process's effective group ID +or, if the object is visible in the filesystem, +the group ID of the parent directory. +.SH NOTES +.PP +POSIX leaves the behavior of the combination of +.B O_RDONLY +and +.B O_TRUNC +unspecified. +On Linux, this will successfully truncate an existing +shared memory object\(emthis may not be so on other UNIX systems. +.PP +The POSIX shared memory object implementation on Linux makes use +of a dedicated +.BR tmpfs (5) +filesystem that is normally mounted under +.IR /dev/shm . +.SH SEE ALSO +.BR close (2), +.BR fchmod (2), +.BR fchown (2), +.BR fcntl (2), +.BR fstat (2), +.BR ftruncate (2), +.BR memfd_create (2), +.BR mmap (2), +.BR open (2), +.BR umask (2), +.BR shm_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/shm_unlink.3 b/man3/shm_unlink.3 new file mode 100644 index 0000000..74f2986 --- /dev/null +++ b/man3/shm_unlink.3 @@ -0,0 +1 @@ +.so man3/shm_open.3 diff --git a/man3/sigaddset.3 b/man3/sigaddset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man3/sigaddset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigandset.3 b/man3/sigandset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man3/sigandset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigblock.3 b/man3/sigblock.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man3/sigblock.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man3/sigdelset.3 b/man3/sigdelset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man3/sigdelset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigemptyset.3 b/man3/sigemptyset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man3/sigemptyset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigfillset.3 b/man3/sigfillset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man3/sigfillset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/siggetmask.3 b/man3/siggetmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man3/siggetmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man3/sighold.3 b/man3/sighold.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man3/sighold.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man3/sigignore.3 b/man3/sigignore.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man3/sigignore.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man3/siginterrupt.3 b/man3/siginterrupt.3 new file mode 100644 index 0000000..a7d7788 --- /dev/null +++ b/man3/siginterrupt.3 @@ -0,0 +1,118 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:40:51 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Apr 14 16:20:34 1996 by Andries Brouwer (aeb@cwi.nl) +.TH SIGINTERRUPT 3 2016-03-15 "" "Linux Programmer's Manual" +.SH NAME +siginterrupt \- allow signals to interrupt system calls +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int siginterrupt(int " sig ", int " flag ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR siginterrupt (): +.ad l +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR siginterrupt () +function changes the restart behavior when +a system call is interrupted by the signal \fIsig\fP. +If the \fIflag\fP +argument is false (0), then system calls will be restarted if interrupted +by the specified signal \fIsig\fP. +This is the default behavior in Linux. +.PP +If the \fIflag\fP argument is true (1) and no data has been transferred, +then a system call interrupted by the signal \fIsig\fP will return \-1 +and \fIerrno\fP will be set to +.BR EINTR . +.PP +If the \fIflag\fP argument is true (1) and data transfer has started, +then the system call will be interrupted and will return the actual +amount of data transferred. +.SH RETURN VALUE +The +.BR siginterrupt () +function returns 0 on success. +It returns \-1 if the +signal number +.I sig +is invalid, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +The specified signal number is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR siginterrupt () +T} Thread safety MT-Unsafe const:sigintr +.TE +.SH CONFORMING TO +4.3BSD, POSIX.1-2001. +POSIX.1-2008 marks +.BR siginterrupt () +as obsolete, recommending the use of +.BR sigaction (2) +with the +.B SA_RESTART +flag instead. +.SH SEE ALSO +.BR signal (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sigisemptyset.3 b/man3/sigisemptyset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man3/sigisemptyset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigismember.3 b/man3/sigismember.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man3/sigismember.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/siglongjmp.3 b/man3/siglongjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man3/siglongjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man3/sigmask.3 b/man3/sigmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man3/sigmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man3/signbit.3 b/man3/signbit.3 new file mode 100644 index 0000000..acc691b --- /dev/null +++ b/man3/signbit.3 @@ -0,0 +1,83 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Based on glibc infopages, copyright Free Software Foundation +.\" +.TH SIGNBIT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +signbit \- test sign of a real floating-point number +.SH SYNOPSIS +.B "#include " +.PP +.BI "int signbit(" x ");" +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR signbit (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +.BR signbit () +is a generic macro which can work on all real floating-point types. +It returns a nonzero value if the value of +.I x +has its sign bit set. +.PP +This is not the same as +.IR "x < 0.0" , +because IEEE 754 floating point allows zero to be signed. +The comparison +.IR "-0.0 < 0.0" +is false, but +.IR "signbit(\-0.0)" +will return a nonzero value. +.PP +NaNs and infinities have a sign bit. +.SH RETURN VALUE +The +.BR signbit () +macro returns nonzero if the sign of +.I x +is negative; otherwise it returns zero. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR signbit () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH SEE ALSO +.BR copysign (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/signgam.3 b/man3/signgam.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man3/signgam.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man3/significand.3 b/man3/significand.3 new file mode 100644 index 0000000..9a6aa9c --- /dev/null +++ b/man3/significand.3 @@ -0,0 +1,86 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" heavily based on glibc infopages, copyright Free Software Foundation +.\" +.TH SIGNIFICAND 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +significand, significandf, significandl \- +get mantissa of floating-point number +.SH SYNOPSIS +.B #include +.PP +.BI "double significand(double " x ); +.br +.BI "float significandf(float " x ); +.br +.BI "long double significandl(long double " x ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR significand (), +.BR significandf (), +.BR significandl (): +.RS 4 +/* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions return the mantissa of +.I x +scaled to the range [1,2). +They are equivalent to +.PP +.in +4n +.EX +scalb(x, (double) \-ilogb(x)) +.EE +.in +.PP +This function exists mainly for use in certain standardized tests +for IEEE 754 conformance. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR significand (), +.br +.BR significandf (), +.br +.BR significandl () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +These functions are nonstandard; the +.I double +version is available on a number of other systems. +.\" .SH HISTORY +.\" This function came from BSD. +.SH SEE ALSO +.BR ilogb (3), +.BR scalb (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/significandf.3 b/man3/significandf.3 new file mode 100644 index 0000000..4ae39f5 --- /dev/null +++ b/man3/significandf.3 @@ -0,0 +1 @@ +.so man3/significand.3 diff --git a/man3/significandl.3 b/man3/significandl.3 new file mode 100644 index 0000000..4ae39f5 --- /dev/null +++ b/man3/significandl.3 @@ -0,0 +1 @@ +.so man3/significand.3 diff --git a/man3/sigorset.3 b/man3/sigorset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man3/sigorset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man3/sigpause.3 b/man3/sigpause.3 new file mode 100644 index 0000000..ae4ae47 --- /dev/null +++ b/man3/sigpause.3 @@ -0,0 +1,149 @@ +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SIGPAUSE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigpause \- atomically release blocked signals and wait for interrupt +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int sigpause(int " sigmask "); /* BSD (but see NOTES) */" +.PP +.BI "int sigpause(int " sig "); /* System V / UNIX 95 */" +.fi +.SH DESCRIPTION +Don't use this function. +Use +.BR sigsuspend (2) +instead. +.PP +The function +.BR sigpause () +is designed to wait for some signal. +It changes the process's signal mask (set of blocked signals), +and then waits for a signal to arrive. +Upon arrival of a signal, the original signal mask is restored. +.SH RETURN VALUE +If +.BR sigpause () +returns, it was interrupted by a signal and the return value is \-1 +with +.I errno +set to +.BR EINTR . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sigpause () +T} Thread safety MT-Safe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" marking in glibc manual is more detailed: +.\" +.\" sigpause: MT-Unsafe race:sigprocmask/!bsd!linux +.\" +.\" glibc manual says /!linux!bsd indicate the preceding marker only applies +.\" when the underlying kernel is neither Linux nor a BSD kernel. +.\" So, it is safe in Linux kernel. +.SH CONFORMING TO +The System V version of +.BR sigpause () +is standardized in POSIX.1-2001. +It is also specified in POSIX.1-2008, where it is marked obsolete. +.SH NOTES +.SS History +The classical BSD version of this function appeared in 4.2BSD. +It sets the process's signal mask to +.IR sigmask . +UNIX 95 standardized the incompatible System V version of +this function, which removes only the specified signal +.I sig +from the process's signal mask. +.\" __xpg_sigpause: UNIX 95, spec 1170, SVID, SVr4, XPG +The unfortunate situation with two incompatible functions with the +same name was solved by the +.BR \%sigsuspend (2) +function, that takes a +.I "sigset_t\ *" +argument (instead of an +.IR int ). +.SS Linux notes +On Linux, this routine is a system call only on the Sparc (sparc64) +architecture. +.PP +.\" Libc4 and libc5 know only about the BSD version. +.\" +Glibc uses the BSD version if the +.B _BSD_SOURCE +feature test macro is defined and none of +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.BR _GNU_SOURCE , +or +.B _SVID_SOURCE +is defined. +Otherwise, the System V version is used, +and feature test macros must be defined as follows to obtain the declaration: +.IP * 3 +Since glibc 2.26: +_XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.IP * +Glibc 2.25 and earlier: _XOPEN_SOURCE +.PP +Since glibc 2.19, only the System V version is exposed by +.IR ; +applications that formerly used the BSD +.BR sigpause () +should be amended to use +.BR sigsuspend (2). +.\" +.\" For the BSD version, one usually uses a zero +.\" .I sigmask +.\" to indicate that no signals are to be blocked. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigblock (3), +.BR sigvec (3), +.BR feature_test_macros (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sigqueue.3 b/man3/sigqueue.3 new file mode 100644 index 0000000..227ca44 --- /dev/null +++ b/man3/sigqueue.3 @@ -0,0 +1,182 @@ +.\" Copyright (c) 2002 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" added note on self-signaling, aeb, 2002-06-07 +.\" added note on CAP_KILL, mtk, 2004-06-16 +.\" +.TH SIGQUEUE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigqueue \- queue a signal and data to a process +.SH SYNOPSIS +.B #include +.PP +.BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR sigqueue (): +_POSIX_C_SOURCE\ >=\ 199309L +.SH DESCRIPTION +.BR sigqueue () +sends the signal specified in +.I sig +to the process whose PID is given in +.IR pid . +The permissions required to send a signal are the same as for +.BR kill (2). +As with +.BR kill (2), +the null signal (0) can be used to check if a process with a given +PID exists. +.PP +The +.I value +argument is used to specify an accompanying item of data (either an integer +or a pointer value) to be sent with the signal, and has the following type: +.PP +.in +4n +.EX +union sigval { + int sival_int; + void *sival_ptr; +}; +.EE +.in +.PP +If the receiving process has installed a handler for this signal using the +.B SA_SIGINFO +flag to +.BR sigaction (2), +then it can obtain this data via the +.I si_value +field of the +.I siginfo_t +structure passed as the second argument to the handler. +Furthermore, the +.I si_code +field of that structure will be set to +.BR SI_QUEUE . +.SH RETURN VALUE +On success, +.BR sigqueue () +returns 0, indicating that the signal was successfully +queued to the receiving process. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.I sig +was invalid. +.TP +.B EPERM +The process does not have permission to send the signal +to the receiving process. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process has a PID matching +.IR pid . +.SH VERSIONS +.BR sigqueue () +and the underlying +.BR rt_sigqueueinfo () +system call first appeared in Linux 2.2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sigqueue () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +If this function results in the sending of a signal to the process +that invoked it, and that signal was not blocked by the calling thread, +and no other threads were willing to handle this signal (either by +having it unblocked, or by waiting for it using +.BR sigwait (3)), +then at least some signal must be delivered to this thread before this +function returns. +.SS C library/kernel differences +On Linux, +.BR sigqueue () +is implemented using the +.BR rt_sigqueueinfo (2) +system call. +The system call differs in its third argument, which is the +.I siginfo_t +structure that will be supplied to the receiving process's +signal handler or returned by the receiving process's +.BR sigtimedwait (2) +call. +Inside the glibc +.BR sigqueue () +wrapper, this argument, +.IR uinfo , +is initialized as follows: +.PP +.in +4n +.EX +uinfo.si_signo = sig; /* Argument supplied to sigqueue() */ +uinfo.si_code = SI_QUEUE; +uinfo.si_pid = getpid(); /* Process ID of sender */ +uinfo.si_uid = getuid(); /* Real UID of sender */ +uinfo.si_value = val; /* Argument supplied to sigqueue() */ +.EE +.in +.SH SEE ALSO +.BR kill (2), +.BR rt_sigqueueinfo (2), +.BR sigaction (2), +.BR signal (2), +.BR pthread_sigqueue (3), +.BR sigwait (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sigrelse.3 b/man3/sigrelse.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man3/sigrelse.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man3/sigset.3 b/man3/sigset.3 new file mode 100644 index 0000000..7c02f17 --- /dev/null +++ b/man3/sigset.3 @@ -0,0 +1,300 @@ +'\" t +.\" Copyright (c) 2005 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SIGSET 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigset, sighold, sigrelse, sigignore \- System V signal API +.SH SYNOPSIS +.B #include +.PP +.B typedef void (*sighandler_t)(int); +.PP +.BI "sighandler_t sigset(int " sig ", sighandler_t " disp ); +.PP +.BI "int sighold(int " sig ); +.PP +.BI "int sigrelse(int " sig ); +.PP +.BI "int sigignore(int " sig ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sigset (), +.BR sighold (), +.BR sigrelse (), +.BR sigignore (): +.br +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.RE +.ad +.SH DESCRIPTION +These functions are provided in glibc as a compatibility interface +for programs that make use of the historical System V signal API. +This API is obsolete: new applications should use the POSIX signal API +.RB ( sigaction (2), +.BR sigprocmask (2), +etc.) +.PP +The +.BR sigset () +function modifies the disposition of the signal +.IR sig . +The +.I disp +argument can be the address of a signal handler function, +or one of the following constants: +.TP +.B SIG_DFL +Reset the disposition of +.I sig +to the default. +.TP +.B SIG_IGN +Ignore +.IR sig . +.TP +.B SIG_HOLD +Add +.I sig +to the process's signal mask, but leave the disposition of +.I sig +unchanged. +.PP +If +.I disp +specifies the address of a signal handler, then +.I sig +is added to the process's signal mask during execution of the handler. +.PP +If +.I disp +was specified as a value other than +.BR SIG_HOLD , +then +.I sig +is removed from the process's signal mask. +.PP +The dispositions for +.B SIGKILL +and +.B SIGSTOP +cannot be changed. +.PP +The +.BR sighold () +function adds +.I sig +to the calling process's signal mask. +.PP +The +.BR sigrelse () +function removes +.I sig +from the calling process's signal mask. +.PP +The +.BR sigignore () +function sets the disposition of +.I sig +to +.BR SIG_IGN . +.SH RETURN VALUE +On success, +.BR sigset () +returns +.B SIG_HOLD +if +.I sig +was blocked before the call, +or the signal's previous disposition +if it was not blocked before the call. +On error, +.BR sigset () +returns \-1, with +.I errno +set to indicate the error. +(But see BUGS below.) +.PP +The +.BR sighold (), +.BR sigrelse (), +and +.BR sigignore () +functions return 0 on success; on error, these functions return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +For +.BR sigset () +see the ERRORS under +.BR sigaction (2) +and +.BR sigprocmask (2). +.PP +For +.BR sighold () +and +.BR sigrelse () +see the ERRORS under +.BR sigprocmask (2). +.PP +For +.BR sigignore (), +see the errors under +.BR sigaction (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw23 lb lb +l l l. +Interface Attribute Value +T{ +.BR sigset (), +.BR sighold (), +.br +.BR sigrelse (), +.BR sigignore () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +SVr4, POSIX.1-2001, POSIX.1-2008. +These functions are obsolete: do not use them in new programs. +POSIX.1-2008 marks +.BR sighold (), +.BR sigignore (), +.BR sigpause (3), +.BR sigrelse (), +and +.BR sigset () +as obsolete, recommending the use of +.BR sigaction (2), +.BR sigprocmask (2), +.BR pthread_sigmask (3), +and +.BR sigsuspend (2) +instead. +.SH NOTES +These functions appeared in glibc version 2.1. +.PP +The +.I sighandler_t +type is a GNU extension; it is used on this page only to make the +.BR sigset () +prototype more easily readable. +.PP +The +.BR sigset () +function provides reliable signal handling semantics (as when calling +.BR sigaction (2) +with +.I sa_mask +equal to 0). +.PP +On System V, the +.BR signal () +function provides unreliable semantics (as when calling +.BR sigaction (2) +with +.I sa_mask +equal to +.IR "SA_RESETHAND | SA_NODEFER" ). +On BSD, +.BR signal () +provides reliable semantics. +POSIX.1-2001 leaves these aspects of +.BR signal () +unspecified. +See +.BR signal (2) +for further details. +.PP +In order to wait for a signal, +BSD and System V both provided a function named +.BR sigpause (3), +but this function has a different argument on the two systems. +See +.BR sigpause (3) +for details. +.SH BUGS +In versions of glibc before 2.2, +.BR sigset () +did not unblock +.I sig +if +.I disp +was specified as a value other than +.BR SIG_HOLD . +.PP +In versions of glibc before 2.5, +.BR sigset () +does not correctly return the previous disposition of the signal +in two cases. +First, if +.I disp +is specified as +.BR SIG_HOLD , +then a successful +.BR sigset () +always returns +.BR SIG_HOLD . +Instead, it should return the previous disposition of the signal +(unless the signal was blocked, in which case +.B SIG_HOLD +should be returned). +Second, if the signal is currently blocked, then +the return value of a successful +.BR sigset () +should be +.BR SIG_HOLD . +Instead, the previous disposition of the signal is returned. +These problems have been fixed since glibc 2.5. +.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1951 +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR raise (3), +.BR sigpause (3), +.BR sigvec (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sigsetjmp.3 b/man3/sigsetjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man3/sigsetjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man3/sigsetmask.3 b/man3/sigsetmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man3/sigsetmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man3/sigsetops.3 b/man3/sigsetops.3 new file mode 100644 index 0000000..cbedd25 --- /dev/null +++ b/man3/sigsetops.3 @@ -0,0 +1,216 @@ +.\" Copyright (c) 1994 Mike Battersby +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified by aeb, 960721 +.\" 2005-11-21, mtk, added descriptions of sigisemptyset(), sigandset(), +.\" and sigorset() +.\" 2007-10-26 mdw added wording that a sigset_t must be initialized +.\" prior to use +.\" +.TH SIGSETOPS 3 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigemptyset, sigfillset, sigaddset, sigdelset, sigismember \- POSIX +signal set operations +.SH SYNOPSIS +.B #include +.PP +.BI "int sigemptyset(sigset_t *" set ); +.PP +.BI "int sigfillset(sigset_t *" set ); +.PP +.BI "int sigaddset(sigset_t *" set ", int " signum ); +.PP +.BI "int sigdelset(sigset_t *" set ", int " signum ); +.PP +.BI "int sigismember(const sigset_t *" set ", int " signum ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sigemptyset (), +.BR sigfillset (), +.BR sigaddset (), +.BR sigdelset (), +.BR sigismember (): +.RS 4 +_POSIX_C_SOURCE +.RE +.ad b +.SH DESCRIPTION +These functions allow the manipulation of POSIX signal sets. +.PP +.BR sigemptyset () +initializes the signal set given by +.I set +to empty, with all signals excluded from the set. +.PP +.BR sigfillset () +initializes +.I set +to full, including all signals. +.PP +.BR sigaddset () +and +.BR sigdelset () +add and delete respectively signal +.I signum +from +.IR set . +.PP +.BR sigismember () +tests whether +.I signum +is a member of +.IR set . +.PP +Objects of type +.I sigset_t +must be initialized by a call to either +.BR sigemptyset () +or +.BR sigfillset () +before being passed to the functions +.BR sigaddset (), +.BR sigdelset () +and +.BR sigismember () +or the additional glibc functions described below +.RB ( sigisemptyset (), +.BR sigandset (), +and +.BR sigorset ()). +The results are undefined if this is not done. +.SH RETURN VALUE +.BR sigemptyset (), +.BR sigfillset (), +.BR sigaddset (), +and +.BR sigdelset () +return 0 on success and \-1 on error. +.PP +.BR sigismember () +returns 1 if +.I signum +is a member of +.IR set , +0 if +.I signum +is not a member, and \-1 on error. +.PP +On error, these functions set +.I errno +to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +.I signum +is not a valid signal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR sigemptyset (), +.BR sigfillset (), +.br +.BR sigaddset (), +.BR sigdelset (), +.br +.BR sigismember (), +.BR sigisemptyset (), +.br +.BR sigorset (), +.BR sigandset () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +When creating a filled signal set, the glibc +.BR sigfillset () +function does not include the two real-time signals used internally +by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.\" +.SS Glibc extensions +If the +.B _GNU_SOURCE +feature test macro is defined, then \fI\fP +exposes three other functions for manipulating signal +sets: +.PP +.nf +.BI "int sigisemptyset(const sigset_t *" set ); +.BI "int sigorset(sigset_t *" dest ", const sigset_t *" left , +.BI " const sigset_t *" right ); +.BI "int sigandset(sigset_t *" dest ", const sigset_t *" left , +.BI " const sigset_t *" right ); +.fi +.PP +.BR sigisemptyset () +returns 1 if +.I set +contains no signals, and 0 otherwise. +.PP +.BR sigorset () +places the union of the sets +.I left +and +.I right +in +.IR dest . +.BR sigandset () +places the intersection of the sets +.I left +and +.I right +in +.IR dest . +Both functions return 0 on success, and \-1 on failure. +.PP +These functions are nonstandard (a few other systems provide similar +functions) and their use should be avoided in portable applications. +.SH SEE ALSO +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigsuspend (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sigstack.3 b/man3/sigstack.3 new file mode 100644 index 0000000..bf85961 --- /dev/null +++ b/man3/sigstack.3 @@ -0,0 +1,3 @@ +.so man2/sigaltstack.2 +.\" No new programs should use sigstack(3). +.\" sigaltstack(2) briefly discusses sigstack(3), so point the user there. diff --git a/man3/sigvec.3 b/man3/sigvec.3 new file mode 100644 index 0000000..1793cbb --- /dev/null +++ b/man3/sigvec.3 @@ -0,0 +1,298 @@ +'\" t +.\" Copyright (c) 2005 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SIGVEC 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sigvec, sigblock, sigsetmask, siggetmask, sigmask \- BSD signal API +.SH SYNOPSIS +.B #include +.PP +.BI "int sigvec(int " sig ", const struct sigvec *" vec ", struct sigvec *" ovec ); +.PP +.BI "int sigmask(int " signum ); +.PP +.BI "int sigblock(int " mask ); +.PP +.BI "int sigsetmask(int " mask ); +.PP +.B int siggetmask(void); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +All functions shown above: + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +These functions are provided in glibc as a compatibility interface +for programs that make use of the historical BSD signal API. +This API is obsolete: new applications should use the POSIX signal API +.RB ( sigaction (2), +.BR sigprocmask (2), +etc.). +.PP +The +.BR sigvec () +function sets and/or gets the disposition of the signal +.I sig +(like the POSIX +.BR sigaction (2)). +If +.I vec +is not NULL, it points to a +.I sigvec +structure that defines the new disposition for +.IR sig . +If +.I ovec +is not NULL, it points to a +.I sigvec +structure that is used to return the previous disposition of +.IR sig . +To obtain the current disposition of +.I sig +without changing it, specify NULL for +.IR vec , +and a non-null pointer for +.IR ovec . +.PP +The dispositions for +.B SIGKILL +and +.B SIGSTOP +cannot be changed. +.PP +The +.I sigvec +structure has the following form: +.PP +.in +4n +.EX +struct sigvec { + void (*sv_handler)(int); /* Signal disposition */ + int sv_mask; /* Signals to be blocked in handler */ + int sv_flags; /* Flags */ +}; +.EE +.in +.PP +The +.I sv_handler +field specifies the disposition of the signal, and is either: +the address of a signal handler function; +.BR SIG_DFL , +meaning the default disposition applies for the signal; or +.BR SIG_IGN , +meaning that the signal is ignored. +.PP +If +.I sv_handler +specifies the address of a signal handler, then +.I sv_mask +specifies a mask of signals that are to be blocked while +the handler is executing. +In addition, the signal for which the handler is invoked is +also blocked. +Attempts to block +.B SIGKILL +or +.B SIGSTOP +are silently ignored. +.PP +If +.I sv_handler +specifies the address of a signal handler, then the +.I sv_flags +field specifies flags controlling what happens when the handler is called. +This field may contain zero or more of the following flags: +.TP +.B SV_INTERRUPT +If the signal handler interrupts a blocking system call, +then upon return from the handler the system call s not be restarted: +instead it fails with the error +.BR EINTR . +If this flag is not specified, then system calls are restarted +by default. +.TP +.B SV_RESETHAND +Reset the disposition of the signal to the default +before calling the signal handler. +If this flag is not specified, then the handler remains established +until explicitly removed by a later call to +.BR sigvec () +or until the process performs an +.BR execve (2). +.TP +.B SV_ONSTACK +Handle the signal on the alternate signal stack +(historically established under BSD using the obsolete +.BR sigstack () +function; the POSIX replacement is +.BR sigaltstack (2)). +.PP +The +.BR sigmask () +macro constructs and returns a "signal mask" for +.IR signum . +For example, we can initialize the +.I vec.sv_mask +field given to +.BR sigvec () +using code such as the following: +.PP +.in +4n +.EX +vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT); + /* Block SIGQUIT and SIGABRT during + handler execution */ +.EE +.in +.PP +The +.BR sigblock () +function adds the signals in +.I mask +to the process's signal mask +(like POSIX +.IR sigprocmask(SIG_BLOCK) ), +and returns the process's previous signal mask. +Attempts to block +.B SIGKILL +or +.B SIGSTOP +are silently ignored. +.PP +The +.BR sigsetmask () +function sets the process's signal mask to the value given in +.I mask +(like POSIX +.IR sigprocmask(SIG_SETMASK) ), +and returns the process's previous signal mask. +.PP +The +.BR siggetmask () +function returns the process's current signal mask. +This call is equivalent to +.IR sigblock(0) . +.SH RETURN VALUE +The +.BR sigvec () +function returns 0 on success; on error, it returns \-1 and sets +.I errno +to indicate the error. +.PP +The +.BR sigblock () +and +.BR sigsetmask () +functions return the previous signal mask. +.PP +The +.BR sigmask () +macro returns the signal mask for +.IR signum . +.SH ERRORS +See the ERRORS under +.BR sigaction (2) +and +.BR sigprocmask (2). +.SH VERSIONS +Starting with version 2.21, the GNU C library no longer exports the +.BR sigvec () +function as part of the ABI. +(To ensure backward compatibility, +the glibc symbol versioning scheme continues to export the interface +to binaries linked against older versions of the library.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw32 lb lb +l l l. +Interface Attribute Value +T{ +.BR sigvec (), +.BR sigmask (), +.BR sigblock (), +.BR sigsetmask (), +.BR siggetmask () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +All of these functions were in +4.3BSD, except +.BR siggetmask (), +whose origin is unclear. +These functions are obsolete: do not use them in new programs. +.SH NOTES +On 4.3BSD, the +.BR signal () +function provided reliable semantics (as when calling +.BR sigvec () +with +.I vec.sv_mask +equal to 0). +On System V, +.BR signal () +provides unreliable semantics. +POSIX.1 leaves these aspects of +.BR signal () +unspecified. +See +.BR signal (2) +for further details. +.PP +In order to wait for a signal, +BSD and System V both provided a function named +.BR sigpause (3), +but this function has a different argument on the two systems. +See +.BR sigpause (3) +for details. +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR raise (3), +.BR sigpause (3), +.BR sigset (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sigwait.3 b/man3/sigwait.3 new file mode 100644 index 0000000..9f944ee --- /dev/null +++ b/man3/sigwait.3 @@ -0,0 +1,131 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SIGWAIT 3 2017-07-13 "Linux" "Linux Programmer's Manual" +.SH NAME +sigwait \- wait for a signal +.SH SYNOPSIS +.nf +.B #include +.PP +.BI " int sigwait(const sigset_t *" set ", int *" sig ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sigwait (): +.RS 4 +Since glibc 2.26: + _POSIX_C_SOURCE >= 199506L +.br +Glibc 2.25 and earlier: + _POSIX_C_SOURCE +.RE +.ad b +.SH DESCRIPTION +The +.BR sigwait () +function suspends execution of the calling thread until +one of the signals specified in the signal set +.IR set +becomes pending. +The function accepts the signal +(removes it from the pending list of signals), +and returns the signal number in +.IR sig . +.PP +The operation of +.BR sigwait () +is the same as +.BR sigwaitinfo (2), +except that: +.IP * 2 +.BR sigwait () +returns only the signal number, rather than a +.I siginfo_t +structure describing the signal. +.IP * +The return values of the two functions are different. +.SH RETURN VALUE +On success, +.BR sigwait () +returns 0. +On error, it returns a positive error number (listed in ERRORS). +.SH ERRORS +.TP +.B EINVAL +.\" Does not occur for glibc. +.I set +contains an invalid signal number. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sigwait () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +.BR sigwait () +is implemented using +.BR sigtimedwait (2). +.PP +The glibc implementation of +.BR sigwait () +silently ignores attempts to wait for the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH EXAMPLE +See +.BR pthread_sigmask (3). +.SH SEE ALSO +.BR sigaction (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigsuspend (2), +.BR sigwaitinfo (2), +.BR sigsetops (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sin.3 b/man3/sin.3 new file mode 100644 index 0000000..8541ff4 --- /dev/null +++ b/man3/sin.3 @@ -0,0 +1,147 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH SIN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +sin, sinf, sinl \- sine function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double sin(double " x ); +.BI "float sinf(float " x ); +.BI "long double sinl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sinf (), +.BR sinl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the sine of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the sine of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1 allows an optional range error for subnormal x +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.BR EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR sin (), +.BR sinf (), +.BR sinl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before version 2.10, the glibc implementation did not set +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6781 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR csin (3), +.BR sincos (3), +.BR tan (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sincos.3 b/man3/sincos.3 new file mode 100644 index 0000000..039cf34 --- /dev/null +++ b/man3/sincos.3 @@ -0,0 +1,118 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH SINCOS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +sincos, sincosf, sincosl \- calculate sin and cos simultaneously +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void sincos(double " x ", double *" sin ", double *" cos ); +.BI "void sincosf(float " x ", float *" sin ", float *" cos ); +.BI "void sincosl(long double " x ", long double *" sin ", long double *" cos ); +.fi +.PP +Link with \fI\-lm\fP. +.SH DESCRIPTION +Several applications need sine and cosine of the same angle +.IR x . +These functions compute both at the same time, and store the results in +.I *sin +and +.IR *cos . +Using this function can be more efficient than two separate calls to +.BR sin (3) +and +.BR cos (3). +.PP +If +.I x +is a NaN, +a NaN is returned in +.I *sin +and +.IR *cos . +.PP +If +.I x +is positive infinity or negative infinity, +a domain error occurs, and +a NaN is returned in +.I *sin +and +.IR *cos . +.SH RETURN VALUE +These functions return +.IR void . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.PP +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" sin() and cos() also don't set errno; bugs have been raised for +.\" those functions. +.\" See https://www.sourceware.org/bugzilla/show_bug.cgi?id=15467 +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR sincos (), +.BR sincosf (), +.BR sincosl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +These functions are GNU extensions. +.SH NOTES +To see the performance advantage of +.BR sincos (), +it may be necessary to disable +.BR gcc (1) +builtin optimizations, using flags such as: +.PP +.in +4n +.EX +cc -O \-lm \-fno\-builtin prog.c +.EE +.in +.SH SEE ALSO +.BR cos (3), +.BR sin (3), +.BR tan (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sincosf.3 b/man3/sincosf.3 new file mode 100644 index 0000000..9faef65 --- /dev/null +++ b/man3/sincosf.3 @@ -0,0 +1 @@ +.so man3/sincos.3 diff --git a/man3/sincosl.3 b/man3/sincosl.3 new file mode 100644 index 0000000..9faef65 --- /dev/null +++ b/man3/sincosl.3 @@ -0,0 +1 @@ +.so man3/sincos.3 diff --git a/man3/sinf.3 b/man3/sinf.3 new file mode 100644 index 0000000..eab51f4 --- /dev/null +++ b/man3/sinf.3 @@ -0,0 +1 @@ +.so man3/sin.3 diff --git a/man3/sinh.3 b/man3/sinh.3 new file mode 100644 index 0000000..aa2bb7d --- /dev/null +++ b/man3/sinh.3 @@ -0,0 +1,154 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-06-08 by aeb +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH SINH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +sinh, sinhf, sinhl \- hyperbolic sine function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double sinh(double " x ); +.BI "float sinhf(float " x ); +.BI "long double sinhl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sinhf (), +.BR sinhl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the hyperbolic sine of +.IR x , +which +is defined mathematically as: +.PP +.nf + sinh(x) = (exp(x) \- exp(\-x)) / 2 +.fi +.SH RETURN VALUE +On success, these functions return the hyperbolic sine of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.PP +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the same sign as +.IR x . +.\" +.\" POSIX.1-2001 documents an optional range error (underflow) +.\" for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR sinh (), +.BR sinhf (), +.BR sinhl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR csinh (3), +.BR tanh (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sinhf.3 b/man3/sinhf.3 new file mode 100644 index 0000000..dc3ce94 --- /dev/null +++ b/man3/sinhf.3 @@ -0,0 +1 @@ +.so man3/sinh.3 diff --git a/man3/sinhl.3 b/man3/sinhl.3 new file mode 100644 index 0000000..dc3ce94 --- /dev/null +++ b/man3/sinhl.3 @@ -0,0 +1 @@ +.so man3/sinh.3 diff --git a/man3/sinl.3 b/man3/sinl.3 new file mode 100644 index 0000000..eab51f4 --- /dev/null +++ b/man3/sinl.3 @@ -0,0 +1 @@ +.so man3/sin.3 diff --git a/man3/sleep.3 b/man3/sleep.3 new file mode 100644 index 0000000..2cf24b4 --- /dev/null +++ b/man3/sleep.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 18:16:02 1993 by Rik Faith (faith@cs.unc.edu) +.TH SLEEP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +sleep \- sleep for a specified number of seconds +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "unsigned int sleep(unsigned int " "seconds" ); +.fi +.SH DESCRIPTION +.BR sleep () +causes the calling thread to sleep either until +the number of real-time seconds specified in +.I seconds +have elapsed or until a signal arrives which is not ignored. +.SH RETURN VALUE +Zero if the requested time has elapsed, +or the number of seconds left to sleep, +if the call was interrupted by a signal handler. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw27 +l l l. +Interface Attribute Value +T{ +.BR sleep () +T} Thread safety MT-Unsafe sig:SIGCHLD/linux +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +On Linux, +.BR sleep () +is implemented via +.BR nanosleep (2). +See the +.BR nanosleep (2) +man page for a discussion of the clock used. +.SS Portability notes +On some systems, +.BR sleep () +may be implemented using +.BR alarm (2) +and +.BR SIGALRM +(POSIX.1 permits this); +mixing calls to +.BR alarm (2) +and +.BR sleep () +is a bad idea. +.PP +Using +.BR longjmp (3) +from a signal handler or modifying the handling of +.B SIGALRM +while sleeping will cause undefined results. +.SH SEE ALSO +.BR sleep (1), +.BR alarm (2), +.BR nanosleep (2), +.BR signal (2), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/snprintf.3 b/man3/snprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man3/snprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/sockatmark.3 b/man3/sockatmark.3 new file mode 100644 index 0000000..a44ae6c --- /dev/null +++ b/man3/sockatmark.3 @@ -0,0 +1,159 @@ +.\" Copyright (c) 2006, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SOCKATMARK 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sockatmark \- determine whether socket is at out-of-band mark +.SH SYNOPSIS +.B #include +.PP +.BI "int sockatmark(int " sockfd ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sockatmark (): +_POSIX_C_SOURCE\ >=\ 200112L +.ad b +.SH DESCRIPTION +.BR sockatmark () +returns a value indicating whether or not the socket referred +to by the file descriptor +.I sockfd +is at the out-of-band mark. +If the socket is at the mark, then 1 is returned; +if the socket is not at the mark, 0 is returned. +This function does not remove the out-of-band mark. +.SH RETURN VALUE +A successful call to +.BR sockatmark () +returns 1 if the socket is at the out-of-band mark, or 0 if it is not. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I sockfd +is not a valid file descriptor. +.TP +.B EINVAL +.\" POSIX.1 says ENOTTY for this case +.I sockfd +is not a file descriptor to which +.BR sockatmark () +can be applied. +.SH VERSIONS +.BR sockatmark () +was added to glibc in version 2.2.4. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sockatmark () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +If +.BR sockatmark () +returns 1, then the out-of-band data can be read using the +.B MSG_OOB +flag of +.BR recv (2). +.PP +Out-of-band data is supported only on some stream socket protocols. +.PP +.BR sockatmark () +can safely be called from a handler for the +.B SIGURG +signal. +.PP +.BR sockatmark () +is implemented using the +.B SIOCATMARK +.BR ioctl (2) +operation. +.SH BUGS +Prior to glibc 2.4, +.BR sockatmark () +did not work. +.SH EXAMPLE +The following code can be used after receipt of a +.B SIGURG +signal to read (and discard) all data up to the mark, +and then read the byte of data at the mark: +.PP +.EX + char buf[BUF_LEN]; + char oobdata; + int atmark, s; + + for (;;) { + atmark = sockatmark(sockfd); + if (atmark == \-1) { + perror("sockatmark"); + break; + } + + if (atmark) + break; + + s = read(sockfd, buf, BUF_LEN); + if (s == \-1) + perror("read"); + if (s <= 0) + break; + } + + if (atmark == 1) { + if (recv(sockfd, &oobdata, 1, MSG_OOB) == \-1) { + perror("recv"); + ... + } + } +.EE +.SH SEE ALSO +.BR fcntl (2), +.BR recv (2), +.BR send (2), +.BR tcp (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sprintf.3 b/man3/sprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man3/sprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/sqrt.3 b/man3/sqrt.3 new file mode 100644 index 0000000..639ca44 --- /dev/null +++ b/man3/sqrt.3 @@ -0,0 +1,134 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH SQRT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +sqrt, sqrtf, sqrtl \- square root function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double sqrt(double " x ); +.BI "float sqrtf(float " x ); +.BI "long double sqrtl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR sqrtf (), +.BR sqrtl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the nonnegative square root of +.IR x . +.SH RETURN VALUE +On success, these functions return the square root of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.PP +If +.I x +is positive infinity, positive infinity is returned. +.PP +If +.I x +is less than \-0, +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP less than \-0 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR sqrt (), +.BR sqrtf (), +.BR sqrtl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR csqrt (3), +.BR hypot (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sqrtf.3 b/man3/sqrtf.3 new file mode 100644 index 0000000..81258bb --- /dev/null +++ b/man3/sqrtf.3 @@ -0,0 +1 @@ +.so man3/sqrt.3 diff --git a/man3/sqrtl.3 b/man3/sqrtl.3 new file mode 100644 index 0000000..81258bb --- /dev/null +++ b/man3/sqrtl.3 @@ -0,0 +1 @@ +.so man3/sqrt.3 diff --git a/man3/srand.3 b/man3/srand.3 new file mode 100644 index 0000000..b007c2f --- /dev/null +++ b/man3/srand.3 @@ -0,0 +1 @@ +.so man3/rand.3 diff --git a/man3/srand48.3 b/man3/srand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man3/srand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man3/srand48_r.3 b/man3/srand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man3/srand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man3/srandom.3 b/man3/srandom.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man3/srandom.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man3/srandom_r.3 b/man3/srandom_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man3/srandom_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man3/sscanf.3 b/man3/sscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man3/sscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/ssignal.3 b/man3/ssignal.3 new file mode 100644 index 0000000..047cab2 --- /dev/null +++ b/man3/ssignal.3 @@ -0,0 +1 @@ +.so man3/gsignal.3 diff --git a/man3/statvfs.3 b/man3/statvfs.3 new file mode 100644 index 0000000..8553ac5 --- /dev/null +++ b/man3/statvfs.3 @@ -0,0 +1,267 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" The pathconf note is from Walter Harms +.\" This is not a system call on Linux +.\" +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH STATVFS 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +statvfs, fstatvfs \- get filesystem statistics +.SH SYNOPSIS +.B #include +.PP +.BI "int statvfs(const char *" path ", struct statvfs *" buf ); +.br +.BI "int fstatvfs(int " fd ", struct statvfs *" buf ); +.SH DESCRIPTION +The function +.BR statvfs () +returns information about a mounted filesystem. +.I path +is the pathname of any file within the mounted filesystem. +.I buf +is a pointer to a +.I statvfs +structure defined approximately as follows: +.PP +.in +4n +.EX +struct statvfs { + unsigned long f_bsize; /* Filesystem block size */ + unsigned long f_frsize; /* Fragment size */ + fsblkcnt_t f_blocks; /* Size of fs in f_frsize units */ + fsblkcnt_t f_bfree; /* Number of free blocks */ + fsblkcnt_t f_bavail; /* Number of free blocks for + unprivileged users */ + fsfilcnt_t f_files; /* Number of inodes */ + fsfilcnt_t f_ffree; /* Number of free inodes */ + fsfilcnt_t f_favail; /* Number of free inodes for + unprivileged users */ + unsigned long f_fsid; /* Filesystem ID */ + unsigned long f_flag; /* Mount flags */ + unsigned long f_namemax; /* Maximum filename length */ +}; +.EE +.in +.PP +Here the types +.I fsblkcnt_t +and +.I fsfilcnt_t +are defined in +.IR . +Both used to be +.IR "unsigned long" . +.PP +The field +.I f_flag +is a bit mask indicating various options that were employed +when mounting this filesystem. +It contains zero or more of the following flags: +.\" XXX Keep this list in sync with statfs(2) +.TP +.B ST_MANDLOCK +Mandatory locking is permitted on the filesystem (see +.BR fcntl (2)). +.TP +.B ST_NOATIME +Do not update access times; see +.BR mount (2). +.TP +.B ST_NODEV +Disallow access to device special files on this filesystem. +.TP +.B ST_NODIRATIME +Do not update directory access times; see +.BR mount (2). +.TP +.B ST_NOEXEC +Execution of programs is disallowed on this filesystem. +.TP +.B ST_NOSUID +The set-user-ID and set-group-ID bits are ignored by +.BR exec (3) +for executable files on this filesystem +.TP +.B ST_RDONLY +This filesystem is mounted read-only. +.TP +.B ST_RELATIME +Update atime relative to mtime/ctime; see +.BR mount (2). +.TP +.B ST_SYNCHRONOUS +Writes are synched to the filesystem immediately (see the description of +.B O_SYNC +in +.BR open (2)). +.PP +It is unspecified whether all members of the returned struct +have meaningful values on all filesystems. +.PP +.BR fstatvfs () +returns the same information about an open file referenced by descriptor +.IR fd . +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +.RB ( statvfs ()) +Search permission is denied for a component of the path prefix of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( fstatvfs ()) +.I fd +is not a valid open file descriptor. +.TP +.B EFAULT +.I Buf +or +.I path +points to an invalid address. +.TP +.B EINTR +This call was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +.RB ( statvfs ()) +Too many symbolic links were encountered in translating +.IR path . +.TP +.B ENAMETOOLONG +.RB ( statvfs ()) +.I path +is too long. +.TP +.B ENOENT +.RB ( statvfs ()) +The file referred to by +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSYS +The filesystem does not support this call. +.TP +.B ENOTDIR +.RB ( statvfs ()) +A component of the path prefix of +.I path +is not a directory. +.TP +.B EOVERFLOW +Some values were too large to be represented in the returned struct. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR statvfs (), +.BR fstatvfs () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.PP +Only the +.B ST_NOSUID +and +.B ST_RDONLY +flags of the +.I f_flag +field are specified in POSIX.1. +To obtain definitions of the remaining flags, one must define +.BR _GNU_SOURCE . +.SH NOTES +The Linux kernel has system calls +.BR statfs (2) +and +.BR fstatfs (2) +to support this library call. +.PP +In glibc versions before 2.13, +.\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d +.BR statvfs () +populated the bits of the +.IR f_flag +field by scanning the mount options shown in +.IR /proc/mounts . +However, starting with Linux 2.6.36, the underlying +.BR statfs (2) +system call provides the necessary information via the +.IR f_flags +field, and since glibc version 2.13, the +.BR statvfs () +function will use information from that field rather than scanning +.IR /proc/mounts . +.PP +The glibc implementations of +.PP +.in +4n +.EX +pathconf(path, _PC_REC_XFER_ALIGN); +pathconf(path, _PC_ALLOC_SIZE_MIN); +pathconf(path, _PC_REC_MIN_XFER_SIZE); +.EE +.in +.PP +respectively use the +.IR f_frsize , +.IR f_frsize , +and +.I f_bsize +fields returned by a call to +.BR statvfs () +with the argument +.IR path . +.SH SEE ALSO +.BR statfs (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/stdarg.3 b/man3/stdarg.3 new file mode 100644 index 0000000..26c89a6 --- /dev/null +++ b/man3/stdarg.3 @@ -0,0 +1,354 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)stdarg.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu +.\" Additions, 2001-10-14, aeb +.\" +.TH STDARG 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists +.SH SYNOPSIS +.B #include +.PP +.BI "void va_start(va_list " ap ", " last ); +.br +.IB type " va_arg(va_list " ap ", " type ); +.br +.BI "void va_end(va_list " ap ); +.br +.BI "void va_copy(va_list " dest ", va_list " src ); +.SH DESCRIPTION +A function may be called with a varying number of arguments of varying +types. +The include file +.I +declares a type +.I va_list +and defines three macros for stepping through a list of arguments whose +number and types are not known to the called function. +.PP +The called function must declare an object of type +.I va_list +which is used by the macros +.BR va_start (), +.BR va_arg (), +and +.BR va_end (). +.SS va_start() +The +.BR va_start () +macro initializes +.I ap +for subsequent use by +.BR va_arg () +and +.BR va_end (), +and must be called first. +.PP +The argument +.I last +is the name of the last argument before the variable argument list, that is, +the last argument of which the calling function knows the type. +.PP +Because the address of this argument may be used in the +.BR va_start () +macro, it should not be declared as a register variable, +or as a function or an array type. +.SS va_arg() +The +.BR va_arg () +macro expands to an expression that has the type and value of the next +argument in the call. +The argument +.I ap +is the +.I va_list +.I ap +initialized by +.BR va_start (). +Each call to +.BR va_arg () +modifies +.I ap +so that the next call returns the next argument. +The argument +.I type +is a type name specified so that the type of a pointer to an object that +has the specified type can be obtained simply by adding a * to +.IR type . +.PP +The first use of the +.BR va_arg () +macro after that of the +.BR va_start () +macro returns the argument after +.IR last . +Successive invocations return the values of the remaining arguments. +.PP +If there is no next argument, or if +.I type +is not compatible with the type of the actual next argument (as promoted +according to the default argument promotions), random errors will occur. +.PP +If +.I ap +is passed to a function that uses +.BI va_arg( ap , type ), +then the value of +.I ap +is undefined after the return of that function. +.SS va_end() +Each invocation of +.BR va_start () +must be matched by a corresponding invocation of +.BR va_end () +in the same function. +After the call +.BI va_end( ap ) +the variable +.I ap +is undefined. +Multiple traversals of the list, each +bracketed by +.BR va_start () +and +.BR va_end () +are possible. +.BR va_end () +may be a macro or a function. +.SS va_copy() +The +.BR va_copy () +macro copies the (previously initialized) variable argument list +.I src +to +.IR dest . +The behavior is as if +.BR va_start () +were applied to +.IR dest +with the same +.I last +argument, followed by the same number of +.BR va_arg () +invocations that was used to reach the current state of +.IR src . +.PP +.\" Proposal from clive@demon.net, 1997-02-28 +An obvious implementation would have a +.I va_list +be a pointer to the stack frame of the variadic function. +In such a setup (by far the most common) there seems +nothing against an assignment +.PP +.in +4n +.EX +va_list aq = ap; +.EE +.in +.PP +Unfortunately, there are also systems that make it an +array of pointers (of length 1), and there one needs +.PP +.in +4n +.EX +va_list aq; +*aq = *ap; +.EE +.in +.PP +Finally, on systems where arguments are passed in registers, +it may be necessary for +.BR va_start () +to allocate memory, store the arguments there, and also +an indication of which argument is next, so that +.BR va_arg () +can step through the list. +Now +.BR va_end () +can free the allocated memory again. +To accommodate this situation, C99 adds a macro +.BR va_copy (), +so that the above assignment can be replaced by +.PP +.in +4n +.EX +va_list aq; +va_copy(aq, ap); +\&... +va_end(aq); +.EE +.in +.PP +Each invocation of +.BR va_copy () +must be matched by a corresponding invocation of +.BR va_end () +in the same function. +Some systems that do not supply +.BR va_copy () +have +.B __va_copy +instead, since that was the name used in the draft proposal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR va_start (), +.BR va_end (), +.BR va_copy () +T} Thread safety MT-Safe +T{ +.BR va_arg () +T} Thread safety MT-Safe race:ap +.TE +.SH CONFORMING TO +The +.BR va_start (), +.BR va_arg (), +and +.BR va_end () +macros conform to C89. +C99 defines the +.BR va_copy () +macro. +.SH NOTES +These macros are +.I not +compatible with the historic macros they replace. +A backward-compatible version can be found in the include file +.IR . +.PP +The historic setup is: +.PP +.in +4n +.EX +#include + +void +foo(va_alist) + va_dcl +{ + va_list ap; + + va_start(ap); + while (...) { + ... + x = va_arg(ap, type); + ... + } + va_end(ap); +} +.EE +.in +.PP +On some systems, +.I va_end +contains a closing \(aq}\(aq matching a \(aq{\(aq in +.IR va_start , +so that both macros must occur in the same function, and in a way +that allows this. +.SH BUGS +Unlike the +.B varargs +macros, the +.B stdarg +macros do not permit programmers to code a function with no fixed +arguments. +This problem generates work mainly when converting +.B varargs +code to +.B stdarg +code, but it also creates difficulties for variadic functions that wish to +pass all of their arguments on to a function that takes a +.I va_list +argument, such as +.BR vfprintf (3). +.SH EXAMPLE +The function +.I foo +takes a string of format characters and prints out the argument associated +with each format character based on the type. +.PP +.EX +#include +#include + +void +foo(char *fmt, ...) +{ + va_list ap; + int d; + char c, *s; + + va_start(ap, fmt); + while (*fmt) + switch (*fmt++) { + case \(aqs\(aq: /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case \(aqd\(aq: /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case \(aqc\(aq: /* char */ + /* need a cast here since va_arg only + takes fully promoted types */ + c = (char) va_arg(ap, int); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.EE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/stderr.3 b/man3/stderr.3 new file mode 100644 index 0000000..752ae27 --- /dev/null +++ b/man3/stderr.3 @@ -0,0 +1 @@ +.so man3/stdin.3 diff --git a/man3/stdin.3 b/man3/stdin.3 new file mode 100644 index 0000000..c606803 --- /dev/null +++ b/man3/stdin.3 @@ -0,0 +1,168 @@ +.\" From dholland@burgundy.eecs.harvard.edu Tue Mar 24 18:08:15 1998 +.\" +.\" This man page was written in 1998 by David A. Holland +.\" Polished a bit by aeb. +.\" +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" Placed in the Public Domain. +.\" %%%LICENSE_END +.\" +.\" 2005-06-16 mtk, mentioned freopen() +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH STDIN 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +stdin, stdout, stderr \- standard I/O streams +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "extern FILE *" stdin ; +.BI "extern FILE *" stdout ; +.BI "extern FILE *" stderr ; +.fi +.SH DESCRIPTION +Under normal circumstances every UNIX program has three streams opened +for it when it starts up, one for input, one for output, and one for +printing diagnostic or error messages. +These are typically attached to +the user's terminal (see +.BR tty (4)) +but might instead refer to files or other devices, depending on what +the parent process chose to set up. +(See also the "Redirection" section of +.BR sh (1).) +.PP +The input stream is referred to as "standard input"; the output stream is +referred to as "standard output"; and the error stream is referred to +as "standard error". +These terms are abbreviated to form the symbols +used to refer to these files, namely +.IR stdin , +.IR stdout , +and +.IR stderr . +.PP +Each of these symbols is a +.BR stdio (3) +macro of type pointer to +.IR FILE , +and can be used with functions like +.BR fprintf (3) +or +.BR fread (3). +.PP +Since +.IR FILE s +are a buffering wrapper around UNIX file descriptors, the +same underlying files may also be accessed using the raw UNIX file +interface, that is, the functions like +.BR read (2) +and +.BR lseek (2). +.PP +On program startup, the integer file descriptors +associated with the streams +.IR stdin , +.IR stdout , +and +.I stderr +are 0, 1, and 2, respectively. +The preprocessor symbols +.BR STDIN_FILENO , +.BR STDOUT_FILENO , +and +.B STDERR_FILENO +are defined with these values in +.IR . +(Applying +.BR freopen (3) +to one of these streams can change the file descriptor number +associated with the stream.) +.PP +Note that mixing use of +.IR FILE s +and raw file descriptors can produce +unexpected results and should generally be avoided. +(For the masochistic among you: POSIX.1, section 8.2.3, describes +in detail how this interaction is supposed to work.) +A general rule is that file descriptors are handled in the kernel, +while stdio is just a library. +This means for example, that after an +.BR exec (3), +the child inherits all open file descriptors, but all old streams +have become inaccessible. +.PP +Since the symbols +.IR stdin , +.IR stdout , +and +.I stderr +are specified to be macros, assigning to them is nonportable. +The standard streams can be made to refer to different files +with help of the library function +.BR freopen (3), +specially introduced to make it possible to reassign +.IR stdin , +.IR stdout , +and +.IR stderr . +The standard streams are closed by a call to +.BR exit (3) +and by normal program termination. +.SH CONFORMING TO +The +.IR stdin , +.IR stdout , +and +.I stderr +macros conform to C89 +and this standard also stipulates that these three +streams shall be open at program startup. +.SH NOTES +The stream +.I stderr +is unbuffered. +The stream +.I stdout +is line-buffered when it points to a terminal. +Partial lines will not +appear until +.BR fflush (3) +or +.BR exit (3) +is called, or a newline is printed. +This can produce unexpected +results, especially with debugging output. +The buffering mode of the standard streams (or any other stream) +can be changed using the +.BR setbuf (3) +or +.BR setvbuf (3) +call. +Note that in case +.I stdin +is associated with a terminal, there may also be input buffering +in the terminal driver, entirely unrelated to stdio buffering. +(Indeed, normally terminal input is line buffered in the kernel.) +This kernel input handling can be modified using calls like +.BR tcsetattr (3); +see also +.BR stty (1), +and +.BR termios (3). +.SH SEE ALSO +.BR csh (1), +.BR sh (1), +.BR open (2), +.BR fopen (3), +.BR stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/stdio.3 b/man3/stdio.3 new file mode 100644 index 0000000..7e03f80 --- /dev/null +++ b/man3/stdio.3 @@ -0,0 +1,264 @@ +.\" Copyright (c) 1990, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)stdio.3 6.5 (Berkeley) 5/6/91 +.\" +.\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu +.\" Modified, 2001-12-26, aeb +.\" +.TH STDIO 3 2017-11-26 "" "Linux Programmer's Manual" +.SH NAME +stdio \- standard input/output library functions +.SH SYNOPSIS +.B #include +.PP +.BI "FILE *" stdin ; +.br +.BI "FILE *" stdout ; +.br +.BI "FILE *" stderr ; +.SH DESCRIPTION +The standard I/O library provides a simple and efficient buffered stream +I/O interface. +Input and output is mapped into logical data streams and the +physical I/O characteristics are concealed. +The functions and macros are +listed below; more information is available from the individual man pages. +.PP +A stream is associated with an external file (which may be a physical +device) by +.I opening +a file, which may involve creating a new file. +Creating an existing file +causes its former contents to be discarded. +If a file can support positioning requests (such as a disk file, +as opposed to a terminal), then a +.I file position indicator +associated with the stream is positioned at the start of the file (byte +zero), unless the file is opened with append mode. +If append mode is used, +it is unspecified whether the position indicator will be placed at the +start or the end of the file. +The position indicator is maintained by +subsequent reads, writes and positioning requests. +All input occurs as if the characters were read by successive calls to the +.BR fgetc (3) +function; all output takes place as if all characters were written by +successive calls to the +.BR fputc (3) +function. +.PP +A file is disassociated from a stream by +.I closing +the file. +Output streams are flushed (any unwritten buffer contents are +transferred to the host environment) before the stream is disassociated from +the file. +The value of a pointer to a +.I FILE +object is indeterminate after a file is closed (garbage). +.PP +A file may be subsequently reopened, by the same or another program +execution, and its contents reclaimed or modified (if it can be +repositioned at the start). +If the main function returns to its original +caller, or the +.BR exit (3) +function is called, all open files are closed (hence all output streams are +flushed) before program termination. +Other methods of program termination, +such as +.BR abort (3) +do not bother about closing files properly. +.PP +At program startup, three text streams are predefined and need not be +opened explicitly: +.I standard input +(for reading conventional input), +.I standard output +(for writing conventional output), and +.I standard error +(for writing diagnostic output). +These streams are abbreviated +.IR stdin , +.IR stdout , +and +.IR stderr . +When opened, the standard error stream is not fully buffered; the standard +input and output streams are fully buffered if and only if the streams do +not refer to an interactive device. +.PP +Output streams that refer to terminal devices are always line buffered by +default; pending output to such streams is written automatically whenever +an input stream that refers to a terminal device is read. +In cases where a +large amount of computation is done after printing part of a line on an +output terminal, it is necessary to +.BR fflush (3) +the standard output before going off and computing so that the output will +appear. +.PP +The +.I stdio +library is a part of the library +.B libc +and routines are automatically loaded as needed by +.BR cc (1). +The +SYNOPSIS +sections of the following manual pages indicate which include files are to +be used, what the compiler declaration for the function looks like and +which external variables are of interest. +.PP +The following are defined as macros; these names may not be reused without +first removing their current definitions with +.BR #undef : +.BR BUFSIZ , +.BR EOF , +.BR FILENAME_MAX , +.BR FOPEN_MAX , +.BR L_cuserid , +.BR L_ctermid , +.BR L_tmpnam , +.BR NULL , +.BR SEEK_END , +.BR SEEK_SET , +.BR SEEK_CUR , +.BR TMP_MAX , +.BR clearerr , +.BR feof , +.BR ferror , +.BR fileno , +.\" Not on Linux: .BR fropen , +.\" Not on Linux: .BR fwopen , +.BR getc , +.BR getchar , +.BR putc , +.BR putchar , +.BR stderr , +.BR stdin , +.BR stdout . +Function versions of the macro functions +.BR feof , +.BR ferror , +.BR clearerr , +.BR fileno , +.BR getc , +.BR getchar , +.BR putc , +and +.B putchar +exist and will be used if the macros definitions are explicitly removed. +.SS List of functions +.TS +; +lb lb +l l. +Function Description +_ +\fBclearerr\fP(3) check and reset stream status +\fBfclose\fP(3) close a stream +\fBfdopen\fP(3) stream open functions +\fBfeof\fP(3) check and reset stream status +\fBferror\fP(3) check and reset stream status +\fBfflush\fP(3) flush a stream +\fBfgetc\fP(3) get next character or word from input stream +\fBfgetpos\fP(3) reposition a stream +\fBfgets\fP(3) get a line from a stream +\fBfileno\fP(3) return the integer descriptor of the argument stream +\fBfopen\fP(3) stream open functions +\fBfprintf\fP(3) formatted output conversion +\fBfpurge\fP(3) flush a stream +\fBfputc\fP(3) output a character or word to a stream +\fBfputs\fP(3) output a line to a stream +\fBfread\fP(3) binary stream input/output +\fBfreopen\fP(3) stream open functions +\fBfscanf\fP(3) input format conversion +\fBfseek\fP(3) reposition a stream +\fBfsetpos\fP(3) reposition a stream +\fBftell\fP(3) reposition a stream +\fBfwrite\fP(3) binary stream input/output +\fBgetc\fP(3) get next character or word from input stream +\fBgetchar\fP(3) get next character or word from input stream +\fBgets\fP(3) get a line from a stream +\fBgetw\fP(3) get next character or word from input stream +\fBmktemp\fP(3) make temporary filename (unique) +\fBperror\fP(3) system error messages +\fBprintf\fP(3) formatted output conversion +\fBputc\fP(3) output a character or word to a stream +\fBputchar\fP(3) output a character or word to a stream +\fBputs\fP(3) output a line to a stream +\fBputw\fP(3) output a character or word to a stream +\fBremove\fP(3) remove directory entry +\fBrewind\fP(3) reposition a stream +\fBscanf\fP(3) input format conversion +\fBsetbuf\fP(3) stream buffering operations +\fBsetbuffer\fP(3) stream buffering operations +\fBsetlinebuf\fP(3) stream buffering operations +\fBsetvbuf\fP(3) stream buffering operations +\fBsprintf\fP(3) formatted output conversion +\fBsscanf\fP(3) input format conversion +\fBstrerror\fP(3) system error messages +\fBsys_errlist\fP(3) system error messages +\fBsys_nerr\fP(3) system error messages +\fBtempnam\fP(3) temporary file routines +\fBtmpfile\fP(3) temporary file routines +\fBtmpnam\fP(3) temporary file routines +\fBungetc\fP(3) un-get character from input stream +\fBvfprintf\fP(3) formatted output conversion +\fBvfscanf\fP(3) input format conversion +\fBvprintf\fP(3) formatted output conversion +\fBvscanf\fP(3) input format conversion +\fBvsprintf\fP(3) formatted output conversion +\fBvsscanf\fP(3) input format conversion +.TE +.SH CONFORMING TO +The +.I stdio +library conforms to C89. +.SH SEE ALSO +.BR close (2), +.BR open (2), +.BR read (2), +.BR write (2), +.BR stdout (3), +.BR unlocked_stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/stdio_ext.3 b/man3/stdio_ext.3 new file mode 100644 index 0000000..4804609 --- /dev/null +++ b/man3/stdio_ext.3 @@ -0,0 +1,161 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH STDIO_EXT 3 2015-03-02 "" "Linux Programmer's Manual" +.SH NAME +__fbufsize, __flbf, __fpending, __fpurge, __freadable, +__freading, __fsetlocking, __fwritable, __fwriting, _flushlbf \- +interfaces to stdio FILE structure +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "size_t __fbufsize(FILE *" stream ); +.BI "size_t __fpending(FILE *" stream ); +.BI "int __flbf(FILE *" stream ); +.BI "int __freadable(FILE *" stream ); +.BI "int __fwritable(FILE *" stream ); +.BI "int __freading(FILE *" stream ); +.BI "int __fwriting(FILE *" stream ); +.BI "int __fsetlocking(FILE *" stream ", int " type ); +.B "void _flushlbf(void);" +.BI "void __fpurge(FILE *" stream ); +.fi +.SH DESCRIPTION +Solaris introduced routines to allow portable access to the +internals of the +.I FILE +structure, and glibc also implemented these. +.PP +The +.BR __fbufsize () +function returns the size of the buffer currently used +by the given stream. +.PP +The +.BR __fpending () +function returns the number of bytes in the output buffer. +For wide-oriented streams the unit is wide characters. +This function is undefined on buffers in reading mode, +or opened read-only. +.PP +The +.BR __flbf () +function returns a nonzero value if the stream is line-buffered, +and zero otherwise. +.PP +The +.BR __freadable () +function returns a nonzero value if the stream allows reading, +and zero otherwise. +.PP +The +.BR __fwritable () +function returns a nonzero value if the stream allows writing, +and zero otherwise. +.PP +The +.BR __freading () +function returns a nonzero value if the stream is read-only, or +if the last operation on the stream was a read operation, +and zero otherwise. +.PP +The +.BR __fwriting () +function returns a nonzero value if the stream is write-only (or +append-only), or if the last operation on the stream was a write +operation, and zero otherwise. +.PP +The +.BR __fsetlocking () +function can be used to select the desired type of locking on the stream. +It returns the current type. +The +.I type +argument can take the following three values: +.TP +.B FSETLOCKING_INTERNAL +Perform implicit locking around every operation on the given stream +(except for the *_unlocked ones). +This is the default. +.TP +.B FSETLOCKING_BYCALLER +The caller will take care of the locking (possibly using +.BR flockfile (3) +in case there is more than one thread), and the stdio routines +will not do locking until the state is reset to +.BR FSETLOCKING_INTERNAL . +.TP +.B FSETLOCKING_QUERY +Don't change the type of locking. +(Only return it.) +.PP +The +.BR _flushlbf () +function flushes all line-buffered streams. +(Presumably so that +output to a terminal is forced out, say before reading keyboard input.) +.PP +The +.BR __fpurge () +function discards the contents of the stream's buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw28 lb lb +l l l. +Interface Attribute Value +T{ +.BR __fbufsize (), +.BR __fpending (), +.br +.BR __fpurge (), +.BR __fsetlocking () +T} Thread safety MT-Safe race:stream +T{ +.BR __flbf (), +.BR __freadable (), +.br +.BR __freading (), +.BR __fwritable (), +.br +.BR __fwriting (), +.BR _flushlbf () +T} Thread safety MT-Safe +.TE +.SH SEE ALSO +.BR flockfile (3), +.BR fpurge (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/stdout.3 b/man3/stdout.3 new file mode 100644 index 0000000..752ae27 --- /dev/null +++ b/man3/stdout.3 @@ -0,0 +1 @@ +.so man3/stdin.3 diff --git a/man3/stpcpy.3 b/man3/stpcpy.3 new file mode 100644 index 0000000..1cd9ad9 --- /dev/null +++ b/man3/stpcpy.3 @@ -0,0 +1,139 @@ +.\" Copyright 1995 James R. Van Zandt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH STPCPY 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +stpcpy \- copy a string returning a pointer to its end +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *stpcpy(char *" dest ", const char *" src ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR stpcpy (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR stpcpy () +function copies the string pointed to by +.I src +(including the terminating null byte (\(aq\\0\(aq)) to the array pointed to by +.IR dest . +The strings may not overlap, and the destination string +.I dest +must be large enough to receive the copy. +.SH RETURN VALUE +.BR stpcpy () +returns a pointer to the +.B end +of the string +.I dest +(that is, the address of the terminating null byte) +rather than the beginning. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR stpcpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function was added to POSIX.1-2008. +Before that, it was not part of +the C or POSIX.1 standards, nor customary on UNIX systems. +It first appeared at least as early as 1986, +in the Lattice C AmigaDOS compiler, +then in the GNU fileutils and GNU textutils in 1989, +and in the GNU C library by 1992. +It is also present on the BSDs. +.SH BUGS +This function may overrun the buffer +.IR dest . +.SH EXAMPLE +For example, this program uses +.BR stpcpy () +to concatenate +.B foo +and +.B bar +to produce +.BR foobar , +which it then prints. +.PP +.EX +#define _GNU_SOURCE +#include +#include + +int +main(void) +{ + char buffer[20]; + char *to = buffer; + + to = stpcpy(to, "foo"); + to = stpcpy(to, "bar"); + printf("%s\\n", buffer); +} +.EE +.SH SEE ALSO +.BR bcopy (3), +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR stpncpy (3), +.BR strcpy (3), +.BR string (3), +.BR wcpcpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/stpncpy.3 b/man3/stpncpy.3 new file mode 100644 index 0000000..1fbdc0f --- /dev/null +++ b/man3/stpncpy.3 @@ -0,0 +1,118 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" +.\" Corrected, aeb, 990824 +.TH STPNCPY 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +stpncpy \- copy a fixed-size string, returning a pointer to its end +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *stpncpy(char *" dest ", const char *" src ", size_t " n ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR stpncpy (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR stpncpy () +function copies at most +.I n +characters from the string +pointed to by +.IR src , +including the terminating null byte (\(aq\\0\(aq), +to the array pointed to by +.IR dest . +Exactly +.I n +characters are written at +.IR dest . +If the length +.I strlen(src) +is smaller than +.IR n , +the +remaining characters in the array pointed to by +.I dest +are filled +with null bytes (\(aq\\0\(aq), +If the length +.I strlen(src) +is greater than or equal to +.IR n , +the string pointed to by +.I dest +will +not be null-terminated. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least +.I n +characters +at +.IR dest . +.SH RETURN VALUE +.BR stpncpy () +returns a pointer to the terminating null byte +in +.IR dest , +or, if +.I dest +is not null-terminated, +.IR dest + n . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR stpncpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function was added to POSIX.1-2008. +Before that, it was a GNU extension. +It first appeared in version 1.07 of the GNU C library in 1993. +.SH SEE ALSO +.BR strncpy (3), +.BR wcpncpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strcasecmp.3 b/man3/strcasecmp.3 new file mode 100644 index 0000000..cf8abeb --- /dev/null +++ b/man3/strcasecmp.3 @@ -0,0 +1,134 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:12:45 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRCASECMP 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +strcasecmp, strncasecmp \- compare two strings ignoring case +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int strcasecmp(const char *" s1 ", const char *" s2 ); +.PP +.BI "int strncasecmp(const char *" s1 ", const char *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcasecmp () +function performs a byte-by-byte comparison of the strings +.I s1 +and +.IR s2 , +ignoring the case of the characters. +It returns an integer +less than, equal to, or greater than zero if +.I s1 +is found, +respectively, to be less than, to match, or be greater than +.IR s2 . +.PP +The +.BR strncasecmp () +function is similar, except that it compares +no more than +.I n +bytes of +.IR s1 +and +.IR s2 . +.SH RETURN VALUE +The +.BR strcasecmp () +and +.BR strncasecmp () +functions return +an integer less than, equal to, or greater than zero if +.I s1 +is, after ignoring case, found to be +less than, to match, or be greater than +.IR s2 , +respectively. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR strcasecmp (), +.BR strncasecmp () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +4.4BSD, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The +.BR strcasecmp () +and +.BR strncasecmp () +functions first appeared in 4.4BSD, where they were declared in +.IR . +Thus, for reasons of historical compatibility, the glibc +.I +header file also declares these functions, if the +.B _DEFAULT_SOURCE +(or, in glibc 2.19 and earlier, +.BR _BSD_SOURCE ) +feature test macro is defined. +.PP +The POSIX.1-2008 standard says of these functions: +.PP +.RS +When the +.B LC_CTYPE +category of the locale being used is from the POSIX locale, +these functions shall behave as if the strings had been converted +to lowercase and then a byte comparison performed. +Otherwise, the results are unspecified. +.RE +.SH SEE ALSO +.BR bcmp (3), +.BR memcmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR string (3), +.BR strncmp (3), +.BR wcscasecmp (3), +.BR wcsncasecmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strcasestr.3 b/man3/strcasestr.3 new file mode 100644 index 0000000..2feb2c5 --- /dev/null +++ b/man3/strcasestr.3 @@ -0,0 +1 @@ +.so man3/strstr.3 diff --git a/man3/strcat.3 b/man3/strcat.3 new file mode 100644 index 0000000..e8d30cc --- /dev/null +++ b/man3/strcat.3 @@ -0,0 +1,243 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:11:47 1993 by Rik Faith (faith@cs.unc.edu) +.\" 2007-06-15, Marc Boyer + mtk +.\" Improve discussion of strncat(). +.TH STRCAT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strcat, strncat \- concatenate two strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strcat(char *" dest ", const char *" src ); +.PP +.BI "char *strncat(char *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcat () +function appends the +.I src +string to the +.I dest +string, +overwriting the terminating null byte (\(aq\\0\(aq) at the end of +.IR dest , +and then adds a terminating null byte. +The strings may not overlap, and the +.I dest +string must have +enough space for the result. +If +.I dest +is not large enough, program behavior is unpredictable; +.IR "buffer overruns are a favorite avenue for attacking secure programs" . +.PP +The +.BR strncat () +function is similar, except that +.IP * 3 +it will use at most +.I n +bytes from +.IR src ; +and +.IP * +.I src +does not need to be null-terminated if it contains +.I n +or more bytes. +.PP +As with +.BR strcat (), +the resulting string in +.I dest +is always null-terminated. +.PP +If +.IR src +contains +.I n +or more bytes, +.BR strncat () +writes +.I n+1 +bytes to +.I dest +.RI ( n +from +.I src +plus the terminating null byte). +Therefore, the size of +.I dest +must be at least +.IR "strlen(dest)+n+1" . +.PP +A simple implementation of +.BR strncat () +might be: +.PP +.in +4n +.EX +char * +strncat(char *dest, const char *src, size_t n) +{ + size_t dest_len = strlen(dest); + size_t i; + + for (i = 0 ; i < n && src[i] != \(aq\\0\(aq ; i++) + dest[dest_len + i] = src[i]; + dest[dest_len + i] = \(aq\\0\(aq; + + return dest; +} +.EE +.in +.SH RETURN VALUE +The +.BR strcat () +and +.BR strncat () +functions return a pointer to the resulting string +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR strcat (), +.BR strncat () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +Some systems (the BSDs, Solaris, and others) provide the following function: +.PP + size_t strlcat(char *dest, const char *src, size_t size); +.PP +This function appends the null-terminated string +.I src +to the string +.IR dest , +copying at most +.IR "size\-strlen(dest)\-1" +from +.IR src , +and adds a terminating null byte to the result, +.I unless +.IR size +is less than +.IR strlen(dest) . +This function fixes the buffer overrun problem of +.BR strcat (), +but the caller must still handle the possibility of data loss if +.I size +is too small. +The function returns the length of the string +.BR strlcat () +tried to create; if the return value is greater than or equal to +.IR size , +data loss occurred. +If data loss matters, the caller +.I must +either check the arguments before the call, or test the function return value. +.BR strlcat () +is not present in glibc and is not standardized by POSIX, +.\" https://lwn.net/Articles/506530/ +but is available on Linux via the +.IR libbsd +library. +.\" +.SH EXAMPLE +Because +.BR strcat () +and +.BR strncat () +must find the null byte that terminates the string +.I dest +using a search that starts at the beginning of the string, +the execution time of these functions +scales according to the length of the string +.IR dest . +This can be demonstrated by running the program below. +(If the goal is to concatenate many strings to one target, +then manually copying the bytes from each source string +while maintaining a pointer to the end of the target string +will provide better performance.) +.\" +.SS Program source +\& +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ +#define LIM 4000000 + int j; + char p[LIM]; + time_t base; + + base = time(NULL); + p[0] = \(aq\\0\(aq; + + for (j = 0; j < LIM; j++) { + if ((j % 10000) == 0) + printf("%d %ld\\n", j, (long) (time(NULL) \- base)); + strcat(p, "a"); + } +} +.EE +.\" +.SH SEE ALSO +.BR bcopy (3), +.BR memccpy (3), +.BR memcpy (3), +.BR strcpy (3), +.BR string (3), +.BR strncpy (3), +.BR wcscat (3), +.BR wcsncat (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strchr.3 b/man3/strchr.3 new file mode 100644 index 0000000..8f2092e --- /dev/null +++ b/man3/strchr.3 @@ -0,0 +1,147 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Apr 12 12:51:24 1993, David Metcalfe +.\" 2006-05-19, Justin Pryzby +.\" Document strchrnul(3). +.\" +.TH STRCHR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strchr, strrchr, strchrnul \- locate character in string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strchr(const char *" s ", int " c ); +.PP +.BI "char *strrchr(const char *" s ", int " c ); + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "char *strchrnul(const char *" s ", int " c ); +.fi +.SH DESCRIPTION +The +.BR strchr () +function returns a pointer to the first occurrence +of the character +.I c +in the string +.IR s . +.PP +The +.BR strrchr () +function returns a pointer to the last occurrence +of the character +.I c +in the string +.IR s . +.PP +The +.BR strchrnul () +function is like +.BR strchr () +except that if +.I c +is not found in +.IR s , +then it returns a pointer to the null byte +at the end of +.IR s , +rather than NULL. +.PP +Here "character" means "byte"; these functions do not work with +wide or multibyte characters. +.SH RETURN VALUE +The +.BR strchr () +and +.BR strrchr () +functions return a pointer to +the matched character or NULL if the character is not found. +The terminating null byte is considered part of the string, +so that if +.I c +is specified as \(aq\\0\(aq, +these functions return a pointer to the terminator. +.PP +The +.BR strchrnul () +function returns a pointer to the matched character, +or a pointer to the null byte at the end of +.I s +(i.e., +.IR "s+strlen(s)" ) +if the character is not found. +.SH VERSIONS +.BR strchrnul () +first appeared in glibc in version 2.1.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw32 lb lb +l l l. +Interface Attribute Value +T{ +.BR strchr (), +.BR strrchr (), +.BR strchrnul () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR strchr (), +.BR strrchr (): +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.PP +.BR strchrnul () +is a GNU extension. +.SH SEE ALSO +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR string (3), +.BR strlen (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR wcschr (3), +.BR wcsrchr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strchrnul.3 b/man3/strchrnul.3 new file mode 100644 index 0000000..322b7a8 --- /dev/null +++ b/man3/strchrnul.3 @@ -0,0 +1 @@ +.so man3/strchr.3 diff --git a/man3/strcmp.3 b/man3/strcmp.3 new file mode 100644 index 0000000..cf63273 --- /dev/null +++ b/man3/strcmp.3 @@ -0,0 +1,112 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-08-31, aeb +.\" +.TH STRCMP 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +strcmp, strncmp \- compare two strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +.PP +.BI "int strncmp(const char *" s1 ", const char *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcmp () +function compares the two strings +.I s1 +and +.IR s2 . +It returns an integer less than, equal to, or greater +than zero if +.I s1 +is found, respectively, to be less than, +to match, or be greater than +.IR s2 . +.PP +The +.BR strncmp () +function is similar, except it compares +only the first (at most) +.IR n +bytes of +.I s1 +and +.IR s2 . +.SH RETURN VALUE +The +.BR strcmp () +and +.BR strncmp () +functions return an integer +less than, equal to, or greater than zero if +.I s1 +(or the first +.I n +bytes thereof) is found, respectively, to be less than, to +match, or be greater than +.IR s2 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR strcmp (), +.BR strncmp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bcmp (3), +.BR memcmp (3), +.BR strcasecmp (3), +.BR strcoll (3), +.BR string (3), +.BR strncasecmp (3), +.BR strverscmp (3), +.BR wcscmp (3), +.BR wcsncmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strcoll.3 b/man3/strcoll.3 new file mode 100644 index 0000000..56ef462 --- /dev/null +++ b/man3/strcoll.3 @@ -0,0 +1,109 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:40:44 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRCOLL 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strcoll \- compare two strings using the current locale +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int strcoll(const char *" s1 ", const char *" s2 ); +.fi +.SH DESCRIPTION +The +.BR strcoll () +function compares the two strings +.I s1 +and +.IR s2 . +It returns an integer less than, equal to, or greater +than zero if +.I s1 +is found, respectively, to be less than, +to match, or be greater than +.IR s2 . +The comparison is based on +strings interpreted as appropriate for the program's current locale +for category +.BR LC_COLLATE . +(See +.BR setlocale (3).) +.SH RETURN VALUE +The +.BR strcoll () +function returns an integer less than, equal to, +or greater than zero if +.I s1 +is found, respectively, to be less +than, to match, or be greater than +.IR s2 , +when both are interpreted +as appropriate for the current locale. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strcoll () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +In the +.I "POSIX" +or +.I "C" +locales +.BR strcoll () +is equivalent to +.BR strcmp (3). +.SH SEE ALSO +.BR bcmp (3), +.BR memcmp (3), +.BR setlocale (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR string (3), +.BR strxfrm (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strcpy.3 b/man3/strcpy.3 new file mode 100644 index 0000000..502701b --- /dev/null +++ b/man3/strcpy.3 @@ -0,0 +1,251 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:06:49 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Aug 25 23:17:51 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Dec 18 00:47:18 1996 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-06-15, Marc Boyer + mtk +.\" Improve discussion of strncpy(). +.\" +.TH STRCPY 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strcpy, strncpy \- copy a string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strcpy(char *" dest ", const char *" src ); +.PP +.BI "char *strncpy(char *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcpy () +function copies the string pointed to by +.IR src , +including the terminating null byte (\(aq\\0\(aq), +to the buffer pointed to by +.IR dest . +The strings may not overlap, and the destination string +.I dest +must be large enough to receive the copy. +.IR "Beware of buffer overruns!" +(See BUGS.) +.PP +The +.BR strncpy () +function is similar, except that at most +.I n +bytes of +.I src +are copied. +.BR Warning : +If there is no null byte +among the first +.I n +bytes of +.IR src , +the string placed in +.I dest +will not be null-terminated. +.PP +If the length of +.I src +is less than +.IR n , +.BR strncpy () +writes additional null bytes to +.I dest +to ensure that a total of +.I n +bytes are written. +.PP +A simple implementation of +.BR strncpy () +might be: +.PP +.in +4n +.EX +char * +strncpy(char *dest, const char *src, size_t n) +{ + size_t i; + + for (i = 0; i < n && src[i] != \(aq\\0\(aq; i++) + dest[i] = src[i]; + for ( ; i < n; i++) + dest[i] = \(aq\\0\(aq; + + return dest; +} +.EE +.in +.SH RETURN VALUE +The +.BR strcpy () +and +.BR strncpy () +functions return a pointer to +the destination string +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR strcpy (), +.BR strncpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH NOTES +Some programmers consider +.BR strncpy () +to be inefficient and error prone. +If the programmer knows (i.e., includes code to test!) +that the size of +.I dest +is greater than +the length of +.IR src , +then +.BR strcpy () +can be used. +.PP +One valid (and intended) use of +.BR strncpy () +is to copy a C string to a fixed-length buffer +while ensuring both that the buffer is not overflowed +and that unused bytes in the target buffer are zeroed out +(perhaps to prevent information leaks if the buffer is to be +written to media or transmitted to another process via an +interprocess communication technique). +.PP +If there is no terminating null byte in the first +.I n +bytes of +.IR src , +.BR strncpy () +produces an unterminated string in +.IR dest . +If +.I buf +has length +.IR buflen , +you can force termination using something like the following: +.PP +.in +4n +.EX +strncpy(buf, str, buflen \- 1); +if (buflen > 0) + buf[buflen \- 1]= \(aq\\0\(aq; +.EE +.in +.PP +(Of course, the above technique ignores the fact that, if +.I src +contains more than +.I "buflen\ \-\ 1" +bytes, information is lost in the copying to +.IR dest .) +.\" +.SS strlcpy() +Some systems (the BSDs, Solaris, and others) provide the following function: +.PP + size_t strlcpy(char *dest, const char *src, size_t size); +.PP +.\" http://static.usenix.org/event/usenix99/full_papers/millert/millert_html/index.html +.\" "strlcpy and strlcat - consistent, safe, string copy and concatenation" +.\" 1999 USENIX Annual Technical Conference +This function is similar to +.BR strncpy (), +but it copies at most +.I size\-1 +bytes to +.IR dest , +always adds a terminating null byte, +and does not pad the target with (further) null bytes. +This function fixes some of the problems of +.BR strcpy () +and +.BR strncpy (), +but the caller must still handle the possibility of data loss if +.I size +is too small. +The return value of the function is the length of +.IR src , +which allows truncation to be easily detected: +if the return value is greater than or equal to +.IR size , +truncation occurred. +If loss of data matters, the caller +.I must +either check the arguments before the call, +or test the function return value. +.BR strlcpy () +is not present in glibc and is not standardized by POSIX, +.\" https://lwn.net/Articles/506530/ +but is available on Linux via the +.IR libbsd +library. +.SH BUGS +If the destination string of a +.BR strcpy () +is not large enough, then anything might happen. +Overflowing fixed-length string buffers is a favorite cracker technique +for taking complete control of the machine. +Any time a program reads or copies data into a buffer, +the program first needs to check that there's enough space. +This may be unnecessary if you can show that overflow is impossible, +but be careful: programs can get changed over time, +in ways that may make the impossible possible. +.SH SEE ALSO +.BR bcopy (3), +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR stpcpy (3), +.BR stpncpy (3), +.BR strdup (3), +.BR string (3), +.BR wcscpy (3), +.BR wcsncpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strcspn.3 b/man3/strcspn.3 new file mode 100644 index 0000000..26284f2 --- /dev/null +++ b/man3/strcspn.3 @@ -0,0 +1 @@ +.so man3/strspn.3 diff --git a/man3/strdup.3 b/man3/strdup.3 new file mode 100644 index 0000000..e5fa0b3 --- /dev/null +++ b/man3/strdup.3 @@ -0,0 +1,164 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:34 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Oct 17 01:12:26 2001 by John Levon +.TH STRDUP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strdup, strndup, strdupa, strndupa \- duplicate a string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strdup(const char *" s ); +.PP +.BI "char *strndup(const char *" s ", size_t " n ); +.BI "char *strdupa(const char *" s ); +.BI "char *strndupa(const char *" s ", size_t " n ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.PD 0 +.ad l +.BR strdup (): +.RS 4 +_XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.PP +.BR strndup (): +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PP +.BR strdupa (), +.BR strndupa (): +_GNU_SOURCE +.ad +.PD +.SH DESCRIPTION +The +.BR strdup () +function returns a pointer to a new string which +is a duplicate of the string +.IR s . +Memory for the new string is +obtained with +.BR malloc (3), +and can be freed with +.BR free (3). +.PP +The +.BR strndup () +function is similar, but copies at most +.I n +bytes. +If +.I s +is longer than +.IR n , +only +.I n +bytes are copied, and a terminating null byte (\(aq\\0\(aq) is added. +.PP +.BR strdupa () +and +.BR strndupa () +are similar, but use +.BR alloca (3) +to allocate the buffer. +They are available only when using the GNU +GCC suite, and suffer from the same limitations described in +.BR alloca (3). +.SH RETURN VALUE +On success, the +.BR strdup () +function returns a pointer to the duplicated +string. +It returns NULL if insufficient memory was available, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR strdup (), +.BR strndup (), +.BR strdupa (), +.br +.BR strndupa () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +.\" 4.3BSD-Reno, not (first) 4.3BSD. +.BR strdup () +conforms to SVr4, 4.3BSD, POSIX.1-2001. +.BR strndup () +conforms to POSIX.1-2008. +.BR strdupa () +and +.BR strndupa () +are GNU extensions. +.SH SEE ALSO +.BR alloca (3), +.BR calloc (3), +.BR free (3), +.BR malloc (3), +.BR realloc (3), +.BR string (3), +.BR wcsdup (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strdupa.3 b/man3/strdupa.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man3/strdupa.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man3/strerror.3 b/man3/strerror.3 new file mode 100644 index 0000000..3ad8153 --- /dev/null +++ b/man3/strerror.3 @@ -0,0 +1,283 @@ +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2005, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith +.\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer +.\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer +.\" Modified Mon Oct 15 21:16:25 2001 by John Levon +.\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer +.\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer +.\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description +.\" Addition of extra material on portability and standards. +.\" +.TH STRERROR 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +strerror, strerror_r, strerror_l \- return string describing error number +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strerror(int " errnum ); +.PP +.BI "int strerror_r(int " errnum ", char *" buf ", size_t " buflen ); + /* XSI-compliant */ +.PP +.BI "char *strerror_r(int " errnum ", char *" buf ", size_t " buflen ); + /* GNU-specific */ +.PP +.BI "char *strerror_l(int " errnum ", locale_t " locale ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.PP +.BR strerror_r (): +.RS 4 +The XSI-compliant version is provided if: +.br +(_POSIX_C_SOURCE\ >=\ 200112L) && ! \ _GNU_SOURCE +.br +Otherwise, the GNU-specific version is provided. +.RE +.ad +.SH DESCRIPTION +The +.BR strerror () +function returns a pointer to a string that describes the error +code passed in the argument +.IR errnum , +possibly using the +.B LC_MESSAGES +part of the current locale to select the appropriate language. +(For example, if +.I errnum +is +.BR EINVAL , +the returned description will be "Invalid argument".) +This string must not be modified by the application, but may be +modified by a subsequent call to +.BR strerror () +or +.BR strerror_l (). +No other library function, including +.BR perror (3), +will modify this string. +.\" +.SS strerror_r() +The +.BR strerror_r () +function is similar to +.BR strerror (), +but is +thread safe. +This function is available in two versions: +an XSI-compliant version specified in POSIX.1-2001 +(available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), +and a GNU-specific version (available since glibc 2.0). +The XSI-compliant version is provided with the feature test macros +settings shown in the SYNOPSIS; +otherwise the GNU-specific version is provided. +If no feature test macros are explicitly defined, +then (since glibc 2.4) +.B _POSIX_C_SOURCE +is defined by default with the value +200112L, so that the XSI-compliant version of +.BR strerror_r () +is provided by default. +.PP +The XSI-compliant +.BR strerror_r () +is preferred for portable applications. +It returns the error string in the user-supplied buffer +.I buf +of length +.IR buflen . +.PP +The GNU-specific +.BR strerror_r () +returns a pointer to a string containing the error message. +This may be either a pointer to a string that the function stores in +.IR buf , +or a pointer to some (immutable) static string +(in which case +.I buf +is unused). +If the function stores a string in +.IR buf , +then at most +.I buflen +bytes are stored (the string may be truncated if +.I buflen +is too small and +.I errnum +is unknown). +The string always includes a terminating null byte (\(aq\\0\(aq). +.\" +.SS strerror_l() +.BR strerror_l () +is like +.BR strerror (), +but maps +.I errnum +to a locale-dependent error message in the locale specified by +.IR locale . +The behavior of +.BR strerror_l () +is undefined if +.I locale +is the special locale object +.BR LC_GLOBAL_LOCALE +or is not a valid locale object handle. +.SH RETURN VALUE +The +.BR strerror (), +.BR strerror_l (), +and the GNU-specific +.BR strerror_r () +functions return +the appropriate error description string, +or an "Unknown error nnn" message if the error number is unknown. +.PP +The XSI-compliant +.BR strerror_r () +function returns 0 on success. +On error, +a (positive) error number is returned (since glibc 2.13), +or \-1 is returned and +.I errno +is set to indicate the error (glibc versions before 2.13). +.PP +POSIX.1-2001 and POSIX.1-2008 require that a successful call to +.BR strerror () +or +.BR strerror_l () +shall leave +.I errno +unchanged, and note that, +since no function return value is reserved to indicate an error, +an application that wishes to check for errors should initialize +.I errno +to zero before the call, +and then check +.I errno +after the call. +.SH ERRORS +.TP +.B EINVAL +The value of +.I errnum +is not a valid error number. +.TP +.B ERANGE +Insufficient storage was supplied to contain the error description string. +.SH VERSIONS +The +.BR strerror_l () +function first appeared in glibc 2.6. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw14 lb lb +l l l. +Interface Attribute Value +T{ +.BR strerror () +T} Thread safety MT-Unsafe race:strerror +T{ +.BR strerror_r (), +.br +.BR strerror_l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR strerror () +is specified by POSIX.1-2001, POSIX.1-2008, C89, and C99. +.BR strerror_r () +is specified by POSIX.1-2001 and POSIX.1-2008. +.\" FIXME . for later review when Issue 8 is one day released... +.\" A future POSIX.1 may remove strerror_r() +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=508 +.PP +.BR strerror_l () +is specified in POSIX.1-2008. +.PP +The GNU-specific +.BR strerror_r () +function is a nonstandard extension. +.PP +POSIX.1-2001 permits +.BR strerror () +to set +.I errno +if the call encounters an error, but does not specify what +value should be returned as the function result in the event of an error. +On some systems, +.\" e.g., Solaris 8, HP-UX 11 +.BR strerror () +returns NULL if the error number is unknown. +On other systems, +.\" e.g., FreeBSD 5.4, Tru64 5.1B +.BR strerror () +returns a string something like "Error nnn occurred" and sets +.I errno +to +.B EINVAL +if the error number is unknown. +C99 and POSIX.1-2008 require the return value to be non-NULL. +.SH NOTES +The GNU C Library uses a buffer of 1024 characters for +.BR strerror (). +This buffer size therefore should be sufficient to avoid an +.B ERANGE +error when calling +.BR strerror_r () +and +.BR strerror_l (). +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR error (3), +.BR perror (3), +.BR strsignal (3), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strerror_l.3 b/man3/strerror_l.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man3/strerror_l.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man3/strerror_r.3 b/man3/strerror_r.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man3/strerror_r.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man3/strfmon.3 b/man3/strfmon.3 new file mode 100644 index 0000000..9b121c7 --- /dev/null +++ b/man3/strfmon.3 @@ -0,0 +1,228 @@ +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH STRFMON 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +strfmon, strfmon_l \- convert monetary value to a string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "ssize_t strfmon(char *" s ", size_t " max ", const char *" format , +.B "...);" +.PP +.BI "ssize_t strfmon_l(char *" s ", size_t " max ", locale_t " locale ", +.B const char *" format , "...);" +.fi +.SH DESCRIPTION +The +.BR strfmon () +function formats the specified monetary amount +according to the current locale +and format specification +.I format +and places the +result in the character array +.I s +of size +.IR max . +.PP +The +.BR strfmon_l () +function performs the same task, +but uses +the locale specified by +.IR locale . +The behavior of +.BR strfmon_l () +is undefined if +.I locale +is the special locale object +.BR LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.PP +Ordinary characters in +.I format +are copied to +.I s +without conversion. +Conversion specifiers are introduced by a \(aq%\(aq +character. +Immediately following it there can be zero or more +of the following flags: +.TP +.BI = f +The single-byte character +.I f +is used as the numeric fill character (to be used with +a left precision, see below). +When not specified, the space character is used. +.TP +.B ^ +Do not use any grouping characters that might be defined +for the current locale. +By default, grouping is enabled. +.TP +.BR ( " or " + +The ( flag indicates that negative amounts should be enclosed between +parentheses. +The + flag indicates that signs should be handled +in the default way, that is, amounts are preceded by the locale's +sign indication, for example, nothing for positive, "\-" for negative. +.TP +.B ! +Omit the currency symbol. +.TP +.B \- +Left justify all fields. +The default is right justification. +.PP +Next, there may be a field width: a decimal digit string specifying +a minimum field width in bytes. +The default is 0. +A result smaller than this width is padded with spaces +(on the left, unless the left-justify flag was given). +.PP +Next, there may be a left precision of the form "#" followed by +a decimal digit string. +If the number of digits left of the +radix character is smaller than this, the representation is +padded on the left with the numeric fill character. +Grouping characters are not counted in this field width. +.PP +Next, there may be a right precision of the form "." followed by +a decimal digit string. +The amount being formatted is rounded to +the specified number of digits prior to formatting. +The default is specified in the +.I frac_digits +and +.I int_frac_digits +items of the current locale. +If the right precision is 0, no radix character is printed. +(The radix character here is determined by +.BR LC_MONETARY , +and may differ from that specified by +.BR LC_NUMERIC .) +.PP +Finally, the conversion specification must be ended with a +conversion character. +The three conversion characters are +.TP +.B % +(In this case, the entire specification must be exactly "%%".) +Put a \(aq%\(aq character in the result string. +.TP +.B i +One argument of type +.I double +is converted using the locale's international currency format. +.TP +.B n +One argument of type +.I double +is converted using the locale's national currency format. +.SH RETURN VALUE +The +.BR strfmon () +function returns the number of characters placed +in the array +.IR s , +not including the terminating null byte, +provided the string, including the terminating null byte, fits. +Otherwise, it sets +.I errno +to +.BR E2BIG , +returns \-1, and the contents of the array is undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strfmon () +T} Thread safety MT-Safe locale +T{ +.BR strfmon_l () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +The call +.PP +.in +4n +.EX +strfmon(buf, sizeof(buf), "[%^=*#6n] [%=*#6i]", + 1234.567, 1234.567); +.EE +.in +.PP +outputs +.PP +.in +4n +.EX +[€ **1234,57] [EUR **1 234,57] +.EE +.in +.PP +in the +.I nl_NL +locale. +The +.IR de_DE , +.IR de_CH , +.IR en_AU , +and +.I en_GB +locales yield +.PP +.in +4n +.EX +[ **1234,57 €] [ **1.234,57 EUR] +[ Fr. **1234.57] [ CHF **1'234.57] +[ $**1234.57] [ AUD**1,234.57] +[ £**1234.57] [ GBP**1,234.57] +.EE +.in +.SH SEE ALSO +.BR duplocale (3), +.BR setlocale (3), +.BR sprintf (3), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strfmon_l.3 b/man3/strfmon_l.3 new file mode 100644 index 0000000..cdbc310 --- /dev/null +++ b/man3/strfmon_l.3 @@ -0,0 +1 @@ +.so man3/strfmon.3 diff --git a/man3/strfromd.3 b/man3/strfromd.3 new file mode 100644 index 0000000..62f89d7 --- /dev/null +++ b/man3/strfromd.3 @@ -0,0 +1,260 @@ +.\" Copyright (c) 2016, IBM Corporation. +.\" Written by Wainer dos Santos Moschetta +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Glibc 2.25 source code and manual. +.\" C99 standard document. +.\" ISO/IEC TS 18661-1 technical specification. +.\" snprintf and other man.3 pages. +.\" +.TH STRFROMD 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strfromd, strfromf, strfroml \- convert a floating-point value into +a string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int strfromd(char *restrict " str ", size_t " n ", +.BI " const char *restrict " format ", double " fp ");" +.BI "int strfromf(char *restrict " str ", size_t " n ", +.BI " const char *restrict " format ", float "fp ");" +.BI "int strfroml(char *restrict " str ", size_t " n ", +.BI " const char *restrict " format ", long double " fp ");" +.fi +.PP +.in -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR strfromd (), +.BR strfromf (), +.BR strfroml (): +.RS 4 +__STDC_WANT_IEC_60559_BFP_EXT__ +.RE +.ad b +.SH DESCRIPTION +These functions convert a floating-point value, +.IR fp , +into a string of characters, +.IR str , +with a configurable +.IR format +string. +At most +.I n +characters are stored into +.IR str . +.PP +The terminating null character ('\\0') is written if and only if +.I n +is sufficiently large, otherwise the written string is truncated at +.I n +characters. +.PP +The +.BR strfromd (), +.BR strfromf (), +and +.BR strfroml () +functions are equivalent to +.PP +.in +4n +.EX +snprintf(str, n, format, fp); +.EE +.in +.PP +except for the +.I format +string. +.SS Format of the format string +The +.I format +string must start with the character \(aq%\(aq. +This is followed by an optional precision which starts with the period +character (.), followed by an optional decimal integer. +If no integer is specified after the period character, +a precision of zero is used. +Finally, the format string should have one of the conversion specifiers +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G . +.PP +The conversion specifier is applied based on the floating-point type +indicated by the function suffix. +Therefore, unlike +.BR snprintf (), +the format string does not have a length modifier character. +See +.BR snprintf (3) +for a detailed description of these conversion specifiers. +.PP +The implementation conforms to the C99 standard on conversion of NaN and +infinity values: +.PP +.RS +If +.I fp +is a NaN, +NaN, or -NaN, and +.BR f +(or +.BR a , +.BR e , +.BR g ) +is the conversion specifier, the conversion is to "nan", "nan", or "-nan", +respectively. +If +.B F +(or +.BR A , +.BR E , +.BR G ) +is the conversion specifier, the conversion is to "NAN" or "-NAN". +.PP +Likewise if +.I fp +is infinity, it is converted to [-]inf or [-]INF. +.RE +.PP +A malformed +.I format +string results in undefined behavior. +.SH RETURN VALUE +The +.BR strfromd (), +.BR strfromf (), +and +.BR strfroml () +functions return the number of characters that would have been written in +.I str +if +.I n +had enough space, +not counting the terminating null character. +Thus, a return value of +.I n +or greater means that the output was truncated. +.SH VERSIONS +The +.BR strfromd (), +.BR strfromf (), +and +.BR strfroml () +functions are available in glibc since version 2.25. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7) +and the +.B POSIX Safety Concepts +section in GNU C Library manual. +.PP +.TS +allbox; +lbw11 lb lb +l l l. +Interface Attribute Value +T{ +.BR strfromd (), +.BR strfromf (), +.BR strfroml () +T} Thread safety MT-Safe locale +\^ Asynchronous signal safety AS-Unsafe heap +\^ Asynchronous cancellation safety AC-Unsafe mem +.TE +.sp 1 +Note: these attributes are preliminary. +.SH CONFORMING TO +C99, ISO/IEC TS 18661-1. +.SH NOTES +The +.BR strfromd (), +.BR strfromf (), +and +.BR strfroml () +functions take account of the +.B LC_NUMERIC +category of the current locale. +.SH EXAMPLES +To convert the value 12.1 as a float type to a string using decimal +notation, resulting in "12.100000": +.PP +.in +4 +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include +int ssize = 10; +char s[ssize]; +strfromf(s, ssize, "%f", 12.1); +.EE +.in +.PP +To convert the value 12.3456 as a float type to a string using +decimal notation with two digits of precision, resulting in "12.35": +.PP +.in +4 +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include +int ssize = 10; +char s[ssize]; +strfromf(s, ssize, "%.2f", 12.3456); +.EE +.in +.PP +To convert the value 12.345e19 as a double type to a string using +scientific notation with zero digits of precision, resulting in "1E+20": +.PP +.in +4 +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include +int ssize = 10; +char s[ssize]; +strfromd(s, ssize, "%.E", 12.345e19); +.EE +.in +.SH SEE ALSO +.BR atof (3), +.BR snprintf (3), +.BR strtod (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strfromf.3 b/man3/strfromf.3 new file mode 100644 index 0000000..d20099d --- /dev/null +++ b/man3/strfromf.3 @@ -0,0 +1 @@ +.so man3/strfromd.3 diff --git a/man3/strfroml.3 b/man3/strfroml.3 new file mode 100644 index 0000000..d20099d --- /dev/null +++ b/man3/strfroml.3 @@ -0,0 +1 @@ +.so man3/strfromd.3 diff --git a/man3/strfry.3 b/man3/strfry.3 new file mode 100644 index 0000000..06ef18f --- /dev/null +++ b/man3/strfry.3 @@ -0,0 +1,84 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:39:43 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRFRY 3 2015-03-02 "GNU" "Linux Programmer's Manual" +.SH NAME +strfry \- randomize a string +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "char *strfry(char *" string ); +.fi +.SH DESCRIPTION +The +.BR strfry () +function randomizes the contents of +.I string +by +using +.BR rand (3) +to randomly swap characters in the string. +The result is an anagram of +.IR string . +.SH RETURN VALUE +The +.BR strfry () +functions returns a pointer to the randomized +string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strfry () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The +.BR strfry () +function is unique to the +GNU C Library. +.SH SEE ALSO +.BR memfrob (3), +.BR string (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strftime.3 b/man3/strftime.3 new file mode 100644 index 0000000..7ffec80 --- /dev/null +++ b/man3/strftime.3 @@ -0,0 +1,665 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" GNU texinfo documentation on glibc date/time functions. +.\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Applied fix by Wolfgang Franke, aeb, 961011 +.\" Corrected return value, aeb, 970307 +.\" Added Single UNIX Spec conversions and %z, aeb/esr, 990329. +.\" 2005-11-22 mtk, added Glibc Notes covering optional 'flag' and +.\" 'width' components of conversion specifications. +.\" +.TH STRFTIME 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strftime \- format date and time +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t strftime(char *" s ", size_t " max ", const char *" format , +.BI " const struct tm *" tm ); +.fi +.SH DESCRIPTION +The +.BR strftime () +function formats the broken-down time +.I tm +according to the format specification +.I format +and places the +result in the character array +.I s +of size +.IR max . +The broken-down time structure +.I tm +is defined in +.IR . +See also +.BR ctime (3). +.\" FIXME . POSIX says: Local timezone information is used as though +.\" strftime() called tzset(). But this doesn't appear to be the case +.PP +The format specification is a null-terminated string and may contain +special character sequences called +.IR "conversion specifications", +each of which is introduced by a \(aq%\(aq character and terminated by +some other character known as a +.IR "conversion specifier character". +All other character sequences are +.IR "ordinary character sequences". +.PP +The characters of ordinary character sequences (including the null byte) +are copied verbatim from +.I format +to +.IR s . +However, the characters +of conversion specifications are replaced as shown in the list below. +In this list, the field(s) employed from the +.I tm +structure are also shown. +.TP +.B %a +The abbreviated name of the day of the week according to the current locale. +(Calculated from +.IR tm_wday .) +.TP +.B %A +The full name of the day of the week according to the current locale. +(Calculated from +.IR tm_wday .) +.TP +.B %b +The abbreviated month name according to the current locale. +(Calculated from +.IR tm_mon .) +.TP +.B %B +The full month name according to the current locale. +(Calculated from +.IR tm_mon .) +.TP +.B %c +The preferred date and time representation for the current locale. +.TP +.B %C +The century number (year/100) as a 2-digit integer. (SU) +(Calculated from +.IR tm_year .) +.TP +.B %d +The day of the month as a decimal number (range 01 to 31). +(Calculated from +.IR tm_mday .) +.TP +.B %D +Equivalent to +.BR %m/%d/%y . +(Yecch\(emfor Americans only. +Americans should note that in other countries +.B %d/%m/%y +is rather common. +This means that in international context this format is +ambiguous and should not be used.) (SU) +.TP +.B %e +Like +.BR %d , +the day of the month as a decimal number, but a leading +zero is replaced by a space. (SU) +(Calculated from +.IR tm_mday .) +.TP +.B %E +Modifier: use alternative format, see below. (SU) +.TP +.B %F +Equivalent to +.B %Y-%m-%d +(the ISO\ 8601 date format). (C99) +.TP +.B %G +The ISO\ 8601 week-based year (see NOTES) with century as a decimal number. +The 4-digit year corresponding to the ISO week number (see +.BR %V ). +This has the same format and value as +.BR %Y , +except that if the ISO week number belongs to the previous or next year, +that year is used instead. (TZ) +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +.TP +.B %g +Like +.BR %G , +but without century, that is, with a 2-digit year (00\(en99). (TZ) +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +.TP +.B %h +Equivalent to +.BR %b . +(SU) +.TP +.B %H +The hour as a decimal number using a 24-hour clock (range 00 to 23). +(Calculated from +.IR tm_hour .) +.TP +.B %I +The hour as a decimal number using a 12-hour clock (range 01 to 12). +(Calculated from +.IR tm_hour .) +.TP +.B %j +The day of the year as a decimal number (range 001 to 366). +(Calculated from +.IR tm_yday .) +.TP +.B %k +The hour (24-hour clock) as a decimal number (range 0 to 23); +single digits are preceded by a blank. +(See also +.BR %H .) +(Calculated from +.IR tm_hour .) +(TZ) +.TP +.B %l +The hour (12-hour clock) as a decimal number (range 1 to 12); +single digits are preceded by a blank. +(See also +.BR %I .) +(Calculated from +.IR tm_hour .) +(TZ) +.TP +.B %m +The month as a decimal number (range 01 to 12). +(Calculated from +.IR tm_mon .) +.TP +.B %M +The minute as a decimal number (range 00 to 59). +(Calculated from +.IR tm_min .) +.TP +.B %n +A newline character. (SU) +.TP +.B %O +Modifier: use alternative format, see below. (SU) +.TP +.B %p +Either "AM" or "PM" according to the given time value, or the +corresponding strings for the current locale. +Noon is treated as "PM" and midnight as "AM". +(Calculated from +.IR tm_hour .) +.TP +.B %P +Like +.B %p +but in lowercase: "am" or "pm" or a corresponding +string for the current locale. +(Calculated from +.IR tm_hour .) +(GNU) +.TP +.B %r +The time in a.m. or p.m. notation. +In the POSIX locale this is equivalent to +.BR "%I:%M:%S %p" . +(SU) +.TP +.B %R +The time in 24-hour notation +.RB ( %H:%M ). +(SU) +For a version including the seconds, see +.B %T +below. +.TP +.B %s +The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ) +(Calculated from +.IR mktime(tm) .) +.TP +.B %S +The second as a decimal number (range 00 to 60). +(The range is up to 60 to allow for occasional leap seconds.) +(Calculated from +.IR tm_sec .) +.TP +.B %t +A tab character. (SU) +.TP +.B %T +The time in 24-hour notation +.RB ( %H:%M:%S ). +(SU) +.TP +.B %u +The day of the week as a decimal, range 1 to 7, Monday being 1. +See also +.BR %w . +(Calculated from +.IR tm_wday .) +(SU) +.TP +.B %U +The week number of the current year as a decimal number, +range 00 to 53, starting with the first Sunday as the first day +of week 01. +See also +.B %V +and +.BR %W . +(Calculated from +.IR tm_yday +and +.IR tm_wday .) +.TP +.B %V +The ISO\ 8601 week number (see NOTES) of the current year as a decimal number, +range 01 to 53, where week 1 is the first week that has at least +4 days in the new year. +See also +.B %U +and +.BR %W . +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +(SU) +.TP +.B %w +The day of the week as a decimal, range 0 to 6, Sunday being 0. +See also +.BR %u . +(Calculated from +.IR tm_wday .) +.TP +.B %W +The week number of the current year as a decimal number, +range 00 to 53, starting with the first Monday as the first day of week 01. +(Calculated from +.IR tm_yday +and +.IR tm_wday .) +.TP +.B %x +The preferred date representation for the current locale without the time. +.TP +.B %X +The preferred time representation for the current locale without the date. +.TP +.B %y +The year as a decimal number without a century (range 00 to 99). +(Calculated from +.IR tm_year ) +.TP +.B %Y +The year as a decimal number including the century. +(Calculated from +.IR tm_year ) +.TP +.B %z +The +.I +hhmm +or +.I -hhmm +numeric timezone (that is, the hour and minute offset from UTC). (SU) +.TP +.B %Z +The timezone name or abbreviation. +.TP +.B %+ +.\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to +.\" their man pages) +The date and time in +.BR date (1) +format. (TZ) +(Not supported in glibc2.) +.TP +.B %% +A literal \(aq%\(aq character. +.PP +Some conversion specifications can be modified by preceding the +conversion specifier character by the +.B E +or +.B O +.I modifier +to indicate that an alternative format should be used. +If the alternative format or specification does not exist for +the current locale, the behavior will be as if the unmodified +conversion specification were used. (SU) +The Single UNIX Specification mentions +.BR %Ec , +.BR %EC , +.BR %Ex , +.BR %EX , +.BR %Ey , +.BR %EY , +.BR %Od , +.BR %Oe , +.BR %OH , +.BR %OI , +.BR %Om , +.BR %OM , +.BR %OS , +.BR %Ou , +.BR %OU , +.BR %OV , +.BR %Ow , +.BR %OW , +.BR %Oy , +where the effect of the +.B O +modifier is to use +alternative numeric symbols (say, roman numerals), and that of the +E modifier is to use a locale-dependent alternative representation. +.SH RETURN VALUE +Provided that the result string, +including the terminating null byte, does not exceed +.I max +bytes, +.BR strftime () +returns the number of bytes (excluding the terminating null byte) +placed in the array +.IR s . +If the length of the result string (including the terminating null byte) +would exceed +.I max +bytes, then +.BR strftime () +returns 0, and the contents of the array are undefined. +.\" (This behavior applies since at least libc 4.4.4; +.\" very old versions of libc, such as libc 4.4.1, +.\" would return +.\" .I max +.\" if the array was too small.) +.PP +Note that the return value 0 does not necessarily indicate an error. +For example, in many locales +.B %p +yields an empty string. +An empty +.I format +string will likewise yield an empty string. +.SH ENVIRONMENT +The environment variables +.B TZ +and +.B LC_TIME +are used. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strftime () +T} Thread safety MT-Safe env locale +.TE +.SH CONFORMING TO +SVr4, C89, C99. +.\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details +.\" in the standards changed across versions. Investigate and +.\" write up. +There are strict inclusions between the set of conversions +given in ANSI C (unmarked), those given in the Single UNIX Specification +(marked SU), those given in Olson's timezone package (marked TZ), +and those given in glibc (marked GNU), except that +.B %+ +is not supported in glibc2. +On the other hand glibc2 has several more extensions. +POSIX.1 only refers to ANSI C; POSIX.2 describes under +.BR date (1) +several extensions that could apply to +.BR strftime () +as well. +The +.B %F +conversion is in C99 and POSIX.1-2001. +.PP +In SUSv2, the +.B %S +specifier allowed a range of 00 to 61, +to allow for the theoretical possibility of a minute that +included a double leap second +(there never has been such a minute). +.SH NOTES +.SS ISO 8601 week dates +.BR %G , +.BR %g , +and +.BR %V +yield values calculated from the week-based year defined by the +ISO\ 8601 standard. +In this system, weeks start on a Monday, and are numbered from 01, +for the first week, up to 52 or 53, for the last week. +Week 1 is the first week where four or more days fall within the +new year (or, synonymously, week 01 is: +the first week of the year that contains a Thursday; +or, the week that has 4 January in it). +When three of fewer days of the first calendar week of the new year fall +within that year, +then the ISO 8601 week-based system counts those days as part of week 53 +of the preceding year. +For example, 1 January 2010 is a Friday, +meaning that just three days of that calendar week fall in 2010. +Thus, the ISO\ 8601 week-based system considers these days to be part of +week 53 +.RB ( %V ) +of the year 2009 +.RB ( %G ); +week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010. +.SS Glibc notes +Glibc provides some extensions for conversion specifications. +(These extensions are not specified in POSIX.1-2001, but a few other +systems provide similar features.) +.\" HP-UX and Tru64 also have features like this. +Between the \(aq%\(aq character and the conversion specifier character, +an optional +.I flag +and field +.I width +may be specified. +(These precede the +.B E +or +.B O +modifiers, if present.) +.PP +The following flag characters are permitted: +.TP +.B _ +(underscore) +Pad a numeric result string with spaces. +.TP +.B \- +(dash) +Do not pad a numeric result string. +.TP +.B 0 +Pad a numeric result string with zeros even if the conversion +specifier character uses space-padding by default. +.TP +.B ^ +Convert alphabetic characters in result string to uppercase. +.TP +.B # +Swap the case of the result string. +(This flag works only with certain conversion specifier characters, +and of these, it is only really useful with +.BR %Z .) +.PP +An optional decimal width specifier may follow the (possibly absent) flag. +If the natural size of the field is smaller than this width, +then the result string is padded (on the left) to the specified width. +.SH BUGS +If the output string would exceed +.I max +bytes, +.I errno +is +.I not +set. +This makes it impossible to distinguish this error case from cases where the +.I format +string legitimately produces a zero-length output string. +POSIX.1-2001 +does +.I not +specify any +.I errno +settings for +.BR strftime (). +.PP +Some buggy versions of +.BR gcc (1) +complain about the use of +.BR %c : +.IR "warning: `%c' yields only last 2 digits of year in some locales" . +Of course programmers are encouraged to use +.BR %c , +it gives the preferred date and time representation. +One meets all kinds of strange obfuscations +to circumvent this +.BR gcc (1) +problem. +A relatively clean one is to add an +intermediate function +.PP +.in +4n +.EX +size_t +my_strftime(char *s, size_t max, const char *fmt, + const struct tm *tm) +{ + return strftime(s, max, fmt, tm); +} +.EE +.in +.PP +Nowadays, +.BR gcc (1) +provides the +.IR \-Wno\-format\-y2k +option to prevent the warning, +so that the above workaround is no longer required. +.SH EXAMPLE +.BR "RFC\ 2822-compliant date format" +(with an English locale for %a and %b) +.PP +.in +2n +"%a,\ %d\ %b\ %Y\ %T\ %z" +.PP +.BR "RFC\ 822-compliant date format" +(with an English locale for %a and %b) +.PP +.in +2n +"%a,\ %d\ %b\ %y\ %T\ %z" +.SS Example program +The program below can be used to experiment with +.BR strftime (). +.PP +Some examples of the result string produced by the glibc implementation of +.BR strftime () +are as follows: +.PP +.in +4n +.EX +.RB "$" " ./a.out \(aq%m\(aq" +Result string is "11" +.RB "$" " ./a.out \(aq%5m\(aq" +Result string is "00011" +.RB "$" " ./a.out \(aq%_5m\(aq" +Result string is " 11" +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + char outstr[200]; + time_t t; + struct tm *tmp; + + t = time(NULL); + tmp = localtime(&t); + if (tmp == NULL) { + perror("localtime"); + exit(EXIT_FAILURE); + } + + if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) { + fprintf(stderr, "strftime returned 0"); + exit(EXIT_FAILURE); + } + + printf("Result string is \\"%s\\"\\n", outstr); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR date (1), +.BR time (2), +.BR ctime (3), +.BR setlocale (3), +.BR sprintf (3), +.BR strptime (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/string.3 b/man3/string.3 new file mode 100644 index 0000000..0c768e4 --- /dev/null +++ b/man3/string.3 @@ -0,0 +1,241 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:31 1993, Rik Faith (faith@cs.unc.edu) +.TH STRING 3 2014-01-04 "" "Linux Programmer's Manual" +.SH NAME +stpcpy, strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, +strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, strpbrk, +strrchr, strsep, strspn, strstr, strtok, strxfrm, index, rindex +\- string operations +.SH SYNOPSIS +.B #include +.TP +.BI "int strcasecmp(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +and +.I s2 +ignoring case. +.TP +.BI "int strncasecmp(const char *" s1 ", const char *" s2 ", size_t " n ); +Compare the first +.I n +characters of the strings +.I s1 +and +.I s2 +ignoring case. +.TP +.BI "char *index(const char *" s ", int " c ); +Return a pointer to the first occurrence of the character +.I c +in the string +.IR s . +.TP +.BI "char *rindex(const char *" s ", int " c ); +Return a pointer to the last occurrence of the character +.I c +in the string +.IR s . +.TP +.B #include +.TP +.BI "char *stpcpy(char *" dest ", const char *" src ); +Copy a string from +.I src +to +.IR dest , +returning a pointer to the end of the resulting string at +.IR dest . +.TP +.BI "char *strcat(char *" dest ", const char *" src ); +Append the string +.I src +to the string +.IR dest , +returning a pointer +.IR dest . +.TP +.BI "char *strchr(const char *" s ", int " c ); +Return a pointer to the first occurrence of the character +.I c +in the string +.IR s . +.TP +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +with +.IR s2 . +.TP +.BI "int strcoll(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +with +.I s2 +using the current locale. +.TP +.BI "char *strcpy(char *" dest ", const char *" src ); +Copy the string +.I src +to +.IR dest , +returning a pointer to the start of +.IR dest . +.TP +.BI "size_t strcspn(const char *" s ", const char *" reject ); +Calculate the length of the initial segment of the string +.I s +which does not contain any of bytes in the string +.IR reject , +.TP +.BI "char *strdup(const char *" s ); +Return a duplicate of the string +.I s +in memory allocated using +.BR malloc (3). +.TP +.BI "char *strfry(char *" string ); +Randomly swap the characters in +.IR string . +.TP +.BI "size_t strlen(const char *" s ); +Return the length of the string +.IR s . +.TP +.BI "char *strncat(char *" dest ", const char *" src ", size_t " n ); +Append at most +.I n +characters from the string +.I src +to the string +.IR dest , +returning a pointer to +.IR dest . +.TP +.BI "int strncmp(const char *" s1 ", const char *" s2 ", size_t " n ); +Compare at most +.I n +bytes of the strings +.I s1 +and +.IR s2 . +.TP +.BI "char *strncpy(char *" dest ", const char *" src ", size_t " n ); +Copy at most +.I n +bytes from string +.I src +to +.IR dest , +returning a pointer to the start of +.IR dest . +.TP +.BI "char *strpbrk(const char *" s ", const char *" accept ); +Return a pointer to the first occurrence in the string +.I s +of one of the bytes in the string +.IR accept . +.TP +.BI "char *strrchr(const char *" s ", int " c ); +Return a pointer to the last occurrence of the character +.I c +in the string +.IR s . +.TP +.BI "char *strsep(char **" stringp ", const char *" delim ); +Extract the initial token in +.I stringp +that is delimited by one of the bytes in +.IR delim . +.TP +.BI "size_t strspn(const char *" s ", const char *" accept ); +Calculate the length of the starting segment in the string +.I s +that consists entirely of bytes in +.IR accept . +.TP +.BI "char *strstr(const char *" haystack ", const char *" needle ); +Find the first occurrence of the substring +.I needle +in the string +.IR haystack , +returning a pointer to the found substring. +.TP +.BI "char *strtok(char *" s ", const char *" delim ); +Extract tokens from the string +.I s +that are delimited by one of the bytes in +.IR delim . +.TP +.BI "size_t strxfrm(char *" dest ", const char *" src ", size_t " n ); +Transforms +.I src +to the current locale and copies the first +.I n +characters to +.IR dest . +.SH DESCRIPTION +The string functions perform operations on null-terminated +strings. +See the individual man pages for descriptions of each function. +.SH SEE ALSO +.BR index (3), +.BR rindex (3), +.BR stpcpy (3), +.BR strcasecmp (3), +.BR strcat (3), +.BR strchr (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strcpy (3), +.BR strcspn (3), +.BR strdup (3), +.BR strfry (3), +.BR strlen (3), +.BR strncasecmp (3), +.BR strncat (3), +.BR strncmp (3), +.BR strncpy (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR strxfrm (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strlen.3 b/man3/strlen.3 new file mode 100644 index 0000000..4cd8d8e --- /dev/null +++ b/man3/strlen.3 @@ -0,0 +1,77 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:02:26 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRLEN 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strlen \- calculate the length of a string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t strlen(const char *" s ); +.fi +.SH DESCRIPTION +The +.BR strlen () +function calculates the length of the string pointed to by +.IR s , +excluding the terminating null byte (\(aq\\0\(aq). +.SH RETURN VALUE +The +.BR strlen () +function returns the number of characters in the string pointed to by +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strlen () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, C11, SVr4, 4.3BSD. +.SH SEE ALSO +.BR string (3), +.BR strnlen (3), +.BR wcslen (3), +.BR wcsnlen (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strncasecmp.3 b/man3/strncasecmp.3 new file mode 100644 index 0000000..fd3b671 --- /dev/null +++ b/man3/strncasecmp.3 @@ -0,0 +1 @@ +.so man3/strcasecmp.3 diff --git a/man3/strncat.3 b/man3/strncat.3 new file mode 100644 index 0000000..dc3a1ca --- /dev/null +++ b/man3/strncat.3 @@ -0,0 +1 @@ +.so man3/strcat.3 diff --git a/man3/strncmp.3 b/man3/strncmp.3 new file mode 100644 index 0000000..1007f43 --- /dev/null +++ b/man3/strncmp.3 @@ -0,0 +1 @@ +.so man3/strcmp.3 diff --git a/man3/strncpy.3 b/man3/strncpy.3 new file mode 100644 index 0000000..ff7476a --- /dev/null +++ b/man3/strncpy.3 @@ -0,0 +1 @@ +.so man3/strcpy.3 diff --git a/man3/strndup.3 b/man3/strndup.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man3/strndup.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man3/strndupa.3 b/man3/strndupa.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man3/strndupa.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man3/strnlen.3 b/man3/strnlen.3 new file mode 100644 index 0000000..8450a26 --- /dev/null +++ b/man3/strnlen.3 @@ -0,0 +1,95 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" +.TH STRNLEN 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strnlen \- determine the length of a fixed-size string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t strnlen(const char *" s ", size_t " maxlen ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR strnlen (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR strnlen () +function returns the number of characters in the string +pointed to by +.IR s , +excluding the terminating null byte (\(aq\\0\(aq), +but at most +.IR maxlen . +In doing this, +.BR strnlen () +looks only at the first +.I maxlen +characters in the string pointed to by +.I s +and never beyond +.IR s+maxlen . +.SH RETURN VALUE +The +.BR strnlen () +function returns +.IR strlen(s) , +if that is less than +.IR maxlen , +or +.I maxlen +if there is no null terminating (\(aq\\0\(aq) among the first +.I maxlen +characters pointed to by +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strnlen () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2008. +.SH SEE ALSO +.BR strlen (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strpbrk.3 b/man3/strpbrk.3 new file mode 100644 index 0000000..6285ae0 --- /dev/null +++ b/man3/strpbrk.3 @@ -0,0 +1,89 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:01:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRPBRK 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +strpbrk \- search a string for any of a set of bytes +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strpbrk(const char *" s ", const char *" accept ); +.fi +.SH DESCRIPTION +The +.BR strpbrk () +function locates the first occurrence in the +string +.I s +of any of the bytes in the string +.IR accept . +.SH RETURN VALUE +The +.BR strpbrk () +function returns a pointer to the byte in +.I s +that matches one of the bytes in +.IR accept , +or NULL +if no such byte is found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strpbrk () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR string (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR wcspbrk (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strptime.3 b/man3/strptime.3 new file mode 100644 index 0000000..25b5c1c --- /dev/null +++ b/man3/strptime.3 @@ -0,0 +1,454 @@ +.\" Copyright 1993 Mitchum DSouza +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08 +.\" Modified, aeb, 2000-04-07 +.\" Updated from glibc docs, C. Scott Ananian, 2001-08-25 +.\" Modified, aeb, 2001-08-31 +.\" Modified, wharms 2001-11-12, remark on white space and example +.\" +.TH STRPTIME 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strptime \- convert a string representation of time to a time tm structure +.SH SYNOPSIS +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.PP +.BI "char *strptime(const char *" s ", const char *" format , +.BI "struct tm *" tm ); +.SH DESCRIPTION +The +.BR strptime () +function is the converse of +.BR strftime (3); +it converts the character string pointed to by +.I s +to values which are stored in the +"broken-down time" +structure pointed to by +.IR tm , +using the format specified by +.IR format . +.PP +The broken-down time structure +.I tm +is defined in +.IR +as follows: +.PP +.in +4n +.EX +struct tm { + int tm_sec; /* Seconds (0\-60) */ + int tm_min; /* Minutes (0\-59) */ + int tm_hour; /* Hours (0\-23) */ + int tm_mday; /* Day of the month (1\-31) */ + int tm_mon; /* Month (0\-11) */ + int tm_year; /* Year \- 1900 */ + int tm_wday; /* Day of the week (0\-6, Sunday = 0) */ + int tm_yday; /* Day in the year (0\-365, 1 Jan = 0) */ + int tm_isdst; /* Daylight saving time */ +}; +.EE +.in +.PP +For more details on the +.I tm +structure, see +.BR ctime (3). +.PP +The +.I format +argument +is a character string that consists of field descriptors and text characters, +reminiscent of +.BR scanf (3). +Each field descriptor consists of a +.B % +character followed by another character that specifies the replacement +for the field descriptor. +All other characters in the +.I format +string must have a matching character in the input string, +except for whitespace, which matches zero or more +whitespace characters in the input string. +There should be white\%space or other alphanumeric characters +between any two field descriptors. +.PP +The +.BR strptime () +function processes the input string from left +to right. +Each of the three possible input elements (whitespace, +literal, or format) are handled one after the other. +If the input cannot be matched to the format string, the function stops. +The remainder of the format and input strings are not processed. +.PP +The supported input field descriptors are listed below. +In case a text string (such as the name of a day of the week or a month name) +is to be matched, the comparison is case insensitive. +In case a number is to be matched, leading zeros are +permitted but not required. +.TP +.B %% +The +.B % +character. +.TP +.BR %a " or " %A +The name of the day of the week according to the current locale, +in abbreviated form or the full name. +.TP +.BR %b " or " %B " or " %h +The month name according to the current locale, +in abbreviated form or the full name. +.TP +.B %c +The date and time representation for the current locale. +.TP +.B %C +The century number (0\(en99). +.TP +.BR %d " or " %e +The day of month (1\(en31). +.TP +.B %D +Equivalent to +.BR %m/%d/%y . +(This is the American style date, very confusing +to non-Americans, especially since +.B %d/%m/%y +is widely used in Europe. +The ISO 8601 standard format is +.BR %Y-%m-%d .) +.TP +.B %H +The hour (0\(en23). +.TP +.B %I +The hour on a 12-hour clock (1\(en12). +.TP +.B %j +The day number in the year (1\(en366). +.TP +.B %m +The month number (1\(en12). +.TP +.B %M +The minute (0\(en59). +.TP +.B %n +Arbitrary whitespace. +.TP +.B %p +The locale's equivalent of AM or PM. +(Note: there may be none.) +.TP +.B %r +The 12-hour clock time (using the locale's AM or PM). +In the POSIX locale equivalent to +.BR "%I:%M:%S %p" . +If +.I t_fmt_ampm +is empty in the +.B LC_TIME +part of the current locale, +then the behavior is undefined. +.TP +.B %R +Equivalent to +.BR %H:%M . +.TP +.B %S +The second (0\(en60; 60 may occur for leap seconds; +earlier also 61 was allowed). +.TP +.B %t +Arbitrary whitespace. +.TP +.B %T +Equivalent to +.BR %H:%M:%S . +.TP +.B %U +The week number with Sunday the first day of the week (0\(en53). +The first Sunday of January is the first day of week 1. +.TP +.B %w +The ordinal number of the day of the week (0\(en6), with Sunday = 0. +.TP +.B %W +The week number with Monday the first day of the week (0\(en53). +The first Monday of January is the first day of week 1. +.TP +.B %x +The date, using the locale's date format. +.TP +.B %X +The time, using the locale's time format. +.TP +.B %y +The year within century (0\(en99). +When a century is not otherwise specified, values in the range 69\(en99 refer +to years in the twentieth century (1969\(en1999); values in the +range 00\(en68 refer to years in the twenty-first century (2000\(en2068). +.TP +.B %Y +The year, including century (for example, 1991). +.PP +Some field descriptors can be modified by the E or O modifier characters +to indicate that an alternative format or specification should be used. +If the +alternative format or specification does not exist in the current locale, the +unmodified field descriptor is used. +.PP +The E modifier specifies that the input string may contain +alternative locale-dependent versions of the date and time representation: +.TP +.B %Ec +The locale's alternative date and time representation. +.TP +.B %EC +The name of the base year (period) in the locale's alternative representation. +.TP +.B %Ex +The locale's alternative date representation. +.TP +.B %EX +The locale's alternative time representation. +.TP +.B %Ey +The offset from +.B %EC +(year only) in the locale's alternative representation. +.TP +.B %EY +The full alternative year representation. +.PP +The O modifier specifies that the numerical input may be in an +alternative locale-dependent format: +.TP +.BR %Od " or " %Oe +The day of the month using the locale's alternative numeric symbols; +leading zeros are permitted but not required. +.TP +.B %OH +The hour (24-hour clock) using the locale's alternative numeric symbols. +.TP +.B %OI +The hour (12-hour clock) using the locale's alternative numeric symbols. +.TP +.B %Om +The month using the locale's alternative numeric symbols. +.TP +.B %OM +The minutes using the locale's alternative numeric symbols. +.TP +.B %OS +The seconds using the locale's alternative numeric symbols. +.TP +.B %OU +The week number of the year (Sunday as the first day of the week) +using the locale's alternative numeric symbols. +.TP +.B %Ow +The ordinal number of the day of the week (Sunday=0), + using the locale's alternative numeric symbols. +.TP +.B %OW +The week number of the year (Monday as the first day of the week) +using the locale's alternative numeric symbols. +.TP +.B %Oy +The year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.SH RETURN VALUE +The return value of the function is a pointer to the first character +not processed in this function call. +In case the input string +contains more characters than required by the format string, the return +value points right after the last consumed input character. +In case the whole input string is consumed, +the return value points to the null byte at the end of the string. +If +.BR strptime () +fails to match all +of the format string and therefore an error occurred, the function +returns NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strptime () +T} Thread safety MT-Safe env locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SUSv2. +.SH NOTES +.PP +In principle, this function does not initialize +.I tm +but +stores only the values specified. +This means that +.I tm +should be initialized before the call. +Details differ a bit between different UNIX systems. +The glibc implementation does not touch those fields which are not +explicitly specified, except that it recomputes the +.I tm_wday +and +.I tm_yday +field if any of the year, month, or day elements changed. +.\" .PP +.\" This function is available since libc 4.6.8. +.\" Linux libc4 and libc5 includes define the prototype unconditionally; +.\" glibc2 includes provide a prototype only when +.\" .B _XOPEN_SOURCE +.\" or +.\" .B _GNU_SOURCE +.\" are defined. +.\" .PP +.\" Before libc 5.4.13 whitespace +.\" (and the \(aqn\(aq and \(aqt\(aq specifications) was not handled, +.\" no \(aqE\(aq and \(aqO\(aq locale modifier characters were accepted, +.\" and the \(aqC\(aq specification was a synonym for the \(aqc\(aq specification. +.PP +The \(aqy\(aq (year in century) specification is taken to specify a year +.\" in the 20th century by libc4 and libc5. +.\" It is taken to be a year +in the range 1950\(en2049 by glibc 2.0. +It is taken to be a year in +1969\(en2068 since glibc 2.1. +.\" In libc4 and libc5 the code for %I is broken (fixed in glibc; +.\" %OI was fixed in glibc 2.2.4). +.SS Glibc notes +For reasons of symmetry, glibc tries to support for +.BR strptime () +the same format characters as for +.BR strftime (3). +(In most cases, the corresponding fields are parsed, but no field in +.I tm +is changed.) +This leads to +.TP +.B %F +Equivalent to +.BR %Y-%m-%d , +the ISO 8601 date format. +.TP +.B %g +The year corresponding to the ISO week number, but without the century +(0\(en99). +.TP +.B %G +The year corresponding to the ISO week number. +(For example, 1991.) +.TP +.B %u +The day of the week as a decimal number (1\(en7, where Monday = 1). +.TP +.B %V +The ISO 8601:1988 week number as a decimal number (1\(en53). +If the week (starting on Monday) containing 1 January has four or more days +in the new year, then it is considered week 1. +Otherwise, it is the last week +of the previous year, and the next week is week 1. +.TP +.B %z +An RFC-822/ISO 8601 standard timezone specification. +.TP +.B %Z +The timezone name. +.PP +Similarly, because of GNU extensions to +.BR strftime (3), +.B %k +is accepted as a synonym for +.BR %H , +and +.B %l +should be accepted +as a synonym for +.BR %I , +and +.B %P +is accepted as a synonym for +.BR %p . +Finally +.TP +.B %s +The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +Leap seconds are not counted unless leap second support is available. +.PP +The glibc implementation does not require whitespace between +two field descriptors. +.SH EXAMPLE +The following example demonstrates the use of +.BR strptime () +and +.BR strftime (3). +.PP +.EX +#define _XOPEN_SOURCE +#include +#include +#include +#include + +int +main(void) +{ + struct tm tm; + char buf[255]; + + memset(&tm, 0, sizeof(struct tm)); + strptime("2001\-11\-12 18:31:01", "%Y\-%m\-%d %H:%M:%S", &tm); + strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); + puts(buf); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR time (2), +.BR getdate (3), +.BR scanf (3), +.BR setlocale (3), +.BR strftime (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strrchr.3 b/man3/strrchr.3 new file mode 100644 index 0000000..322b7a8 --- /dev/null +++ b/man3/strrchr.3 @@ -0,0 +1 @@ +.so man3/strchr.3 diff --git a/man3/strsep.3 b/man3/strsep.3 new file mode 100644 index 0000000..a2584c2 --- /dev/null +++ b/man3/strsep.3 @@ -0,0 +1,132 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:00:10 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Jan 20 12:04:18 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Tue Jan 23 20:23:07 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH STRSEP 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strsep \- extract token from string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strsep(char **" stringp ", const char *" delim ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR strsep (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +If +.I *stringp +is NULL, the +.BR strsep () +function returns NULL +and does nothing else. +Otherwise, this function finds the first token +in the string +.IR *stringp , +that is delimited by one of the bytes in the string +.IR delim . +This token is terminated by overwriting the delimiter +with a null byte (\(aq\\0\(aq), +and +.I *stringp +is updated to point past the token. +In case no delimiter was found, the token is taken to be +the entire string +.IR *stringp , +and +.I *stringp +is made NULL. +.SH RETURN VALUE +The +.BR strsep () +function returns a pointer to the token, +that is, it returns the original value of +.IR *stringp . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strsep () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.4BSD. +.SH NOTES +The +.BR strsep () +function was introduced as a replacement for +.BR strtok (3), +since the latter cannot handle empty fields. +However, +.BR strtok (3) +conforms to C89/C99 and hence is more portable. +.SH BUGS +Be cautious when using this function. +If you do use it, note that: +.IP * 2 +This function modifies its first argument. +.IP * +This function cannot be used on constant strings. +.IP * +The identity of the delimiting character is lost. +.SH SEE ALSO +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strsignal.3 b/man3/strsignal.3 new file mode 100644 index 0000000..051f566 --- /dev/null +++ b/man3/strsignal.3 @@ -0,0 +1,111 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:59:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRSIGNAL 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strsignal \- return string describing signal +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strsignal(int " sig ); +.PP +.BI "extern const char * const " sys_siglist []; +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR strsignal (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR strsignal () +function returns a string describing the signal +number passed in the argument +.IR sig . +The string can be used only until the next call to +.BR strsignal (). +.PP +The array +.I sys_siglist +holds the signal description strings +indexed by signal number. +The +.BR strsignal () +function should be +used if possible instead of this array. +.SH RETURN VALUE +The +.BR strsignal () +function returns the appropriate description +string, or an unknown signal message if the signal number is invalid. +On some systems (but not on Linux), NULL may instead be +returned for an invalid signal number. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw31 +l l l. +Interface Attribute Value +T{ +.BR strsignal () +T} Thread safety MT-Unsafe race:strsignal locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2008. +Present on Solaris and the BSDs. +.SH SEE ALSO +.BR psignal (3), +.BR strerror (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strspn.3 b/man3/strspn.3 new file mode 100644 index 0000000..b7c6f73 --- /dev/null +++ b/man3/strspn.3 @@ -0,0 +1,109 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:57:50 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRSPN 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +strspn, strcspn \- get length of a prefix substring +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t strspn(const char *" s ", const char *" accept ); +.PP +.BI "size_t strcspn(const char *" s ", const char *" reject ); +.fi +.SH DESCRIPTION +The +.BR strspn () +function calculates the length (in bytes) of the initial +segment of +.I s +which consists entirely of bytes in +.IR accept . +.PP +The +.BR strcspn () +function calculates the length of the initial +segment of +.I s +which consists entirely of bytes not in +.IR reject . +.SH RETURN VALUE +The +.BR strspn () +function returns the number of bytes in +the initial segment of +.I s +which consist only of bytes +from +.IR accept . +.PP +The +.BR strcspn () +function returns the number of bytes in +the initial segment of +.I s +which are not in the string +.IR reject . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw19 lb lb +l l l. +Interface Attribute Value +T{ +.BR strspn (), +.BR strcspn () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strstr (3), +.BR strtok (3), +.BR wcscspn (3), +.BR wcsspn (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strstr.3 b/man3/strstr.3 new file mode 100644 index 0000000..986d0a4 --- /dev/null +++ b/man3/strstr.3 @@ -0,0 +1,120 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:56:43 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added history, aeb, 980113. +.\" 2005-05-05 mtk: added strcasestr() +.\" +.TH STRSTR 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strstr, strcasestr \- locate a substring +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strstr(const char *" haystack ", const char *" needle ); +.PP +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.PP +.B #include +.PP +.BI "char *strcasestr(const char *" haystack ", const char *" needle ); +.fi +.SH DESCRIPTION +The +.BR strstr () +function finds the first occurrence of the substring +.I needle +in the string +.IR haystack . +The terminating null bytes (\(aq\\0\(aq) are not compared. +.PP +The +.BR strcasestr () +function is like +.BR strstr (), +but ignores the case of both arguments. +.SH RETURN VALUE +These functions return a pointer to the beginning of the +located substring, or NULL if the substring is not found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strstr () +T} Thread safety MT-Safe +T{ +.BR strcasestr () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +.BR strstr (): +POSIX.1-2001, POSIX.1-2008, C89, C99. +.PP +The +.BR strcasestr () +function is a nonstandard extension. +.\" .SH BUGS +.\" Early versions of Linux libc (like 4.5.26) would not allow +.\" an empty +.\" .I needle +.\" argument for +.\" .BR strstr (). +.\" Later versions (like 4.6.27) work correctly, +.\" and return +.\" .IR haystack +.\" when +.\" .I needle +.\" is empty. +.SH SEE ALSO +.BR index (3), +.BR memchr (3), +.BR memmem (3), +.BR rindex (3), +.BR strcasecmp (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strtok (3), +.BR wcsstr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strtod.3 b/man3/strtod.3 new file mode 100644 index 0000000..16227e7 --- /dev/null +++ b/man3/strtod.3 @@ -0,0 +1,223 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)strtod.3 5.3 (Berkeley) 6/29/91 +.\" +.\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de) +.\" Added strof, strtold, aeb, 2001-06-07 +.\" +.TH STRTOD 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +strtod, strtof, strtold \- convert ASCII string to floating-point number +.SH SYNOPSIS +.B #include +.PP +.BI "double strtod(const char *" nptr ", char **" endptr ); +.br +.BI "float strtof(const char *" nptr ", char **" endptr ); +.br +.BI "long double strtold(const char *" nptr ", char **" endptr ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.ad l +.PP +.BR strtof (), +.BR strtold (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +The +.BR strtod (), +.BR strtof (), +and +.BR strtold () +functions convert the initial portion of the string pointed to by +.I nptr +to +.IR double , +.IR float , +and +.I long double +representation, respectively. +.PP +The expected form of the (initial portion of the) string is +optional leading white space as recognized by +.BR isspace (3), +an optional plus (\(aq+\(aq) or minus sign (\(aq\-\(aq) and then either +(i) a decimal number, or (ii) a hexadecimal number, +or (iii) an infinity, or (iv) a NAN (not-a-number). +.PP +A +.I "decimal number" +consists of a nonempty sequence of decimal digits +possibly containing a radix character (decimal point, locale-dependent, +usually \(aq.\(aq), optionally followed by a decimal exponent. +A decimal exponent consists of an \(aqE\(aq or \(aqe\(aq, followed by an +optional plus or minus sign, followed by a nonempty sequence of +decimal digits, and indicates multiplication by a power of 10. +.PP +A +.I "hexadecimal number" +consists of a "0x" or "0X" followed by a nonempty sequence of +hexadecimal digits possibly containing a radix character, +optionally followed by a binary exponent. +A binary exponent +consists of a \(aqP\(aq or \(aqp\(aq, followed by an optional +plus or minus sign, followed by a nonempty sequence of +decimal digits, and indicates multiplication by a power of 2. +At least one of radix character and binary exponent must be present. +.PP +An +.I infinity +is either "INF" or "INFINITY", disregarding case. +.PP +A +.I NAN +is "NAN" (disregarding case) optionally followed by a string, +.IR (n-char-sequence) , +where +.IR n-char-sequence +specifies in an implementation-dependent +way the type of NAN (see NOTES). +.SH RETURN VALUE +These functions return the converted value, if any. +.PP +If +.I endptr +is not NULL, +a pointer to the character after the last character used in the conversion +is stored in the location referenced by +.IR endptr . +.PP +If no conversion is performed, zero is returned and (unless +.I endptr +is null) the value of +.I nptr +is stored in the location referenced by +.IR endptr . +.PP +If the correct value would cause overflow, plus or minus +.B HUGE_VAL +.RB ( HUGE_VALF , +.BR HUGE_VALL ) +is returned (according to the sign of the value), and +.B ERANGE +is stored in +.IR errno . +If the correct value would cause underflow, zero is +returned and +.B ERANGE +is stored in +.IR errno . +.SH ERRORS +.TP +.B ERANGE +Overflow or underflow occurred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw29 lb lb +l l l. +Interface Attribute Value +T{ +.BR strtod (), +.BR strtof (), +.BR strtold () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.PP +.BR strtod () +was also described in C89. +.SH NOTES +Since +0 can legitimately be returned +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno +has a nonzero value after the call. +.PP +In the glibc implementation, the +.IR n-char-sequence +that optionally follows "NAN" +is interpreted as an integer number +(with an optional '0' or '0x' prefix to select base 8 or 16) +that is to be placed in the +mantissa component of the returned value. +.\" From glibc 2.8's stdlib/strtod_l.c: +.\" We expect it to be a number which is put in the +.\" mantissa of the number. +.\" It looks as though at least FreeBSD (according to the manual) does +.\" something similar. +.\" C11 says: "An implementation may use the n-char sequence to determine +.\" extra information to be represented in the NaN's significant." +.SH EXAMPLE +See the example on the +.BR strtol (3) +manual page; +the use of the functions described in this manual page is similar. +.SH SEE ALSO +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR nan (3), +.BR nanf (3), +.BR nanl (3), +.BR strfromd (3), +.BR strtol (3), +.BR strtoul (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strtof.3 b/man3/strtof.3 new file mode 100644 index 0000000..ac3e4a5 --- /dev/null +++ b/man3/strtof.3 @@ -0,0 +1 @@ +.so man3/strtod.3 diff --git a/man3/strtoimax.3 b/man3/strtoimax.3 new file mode 100644 index 0000000..1b61df6 --- /dev/null +++ b/man3/strtoimax.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH STRTOIMAX 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +strtoimax, strtoumax \- convert string to integer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "intmax_t strtoimax(const char *" nptr ", char **" endptr ", int " base ); +.BI "uintmax_t strtoumax(const char *" nptr ", char **" endptr ", int " base ); +.fi +.SH DESCRIPTION +These functions are just like +.BR strtol (3) +and +.BR strtoul (3), +except that they return a value of type +.I intmax_t +and +.IR uintmax_t , +respectively. +.SH RETURN VALUE +On success, the converted value is returned. +If nothing was found to convert, zero is returned. +On overflow or underflow +.B INTMAX_MAX +or +.B INTMAX_MIN +or +.B UINTMAX_MAX +is returned, and +.I errno +is set to +.BR ERANGE . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR strtoimax (), +.BR strtoumax () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR imaxabs (3), +.BR imaxdiv (3), +.BR strtol (3), +.BR strtoul (3), +.BR wcstoimax (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strtok.3 b/man3/strtok.3 new file mode 100644 index 0000000..8f4a2f9 --- /dev/null +++ b/man3/strtok.3 @@ -0,0 +1,293 @@ +.\" Copyright (C) 2005, 2013 Michael Kerrisk +.\" a few fragments from an earlier (1996) version by +.\" Andries Brouwer (aeb@cwi.nl) remain. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Rewritten old page, 960210, aeb@cwi.nl +.\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier +.\" 2005-11-17, mtk: Substantial parts rewritten +.\" 2013-05-19, mtk: added much further detail on the operation of strtok() +.\" +.TH STRTOK 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strtok, strtok_r \- extract tokens from strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *strtok(char *" str ", const char *" delim ); +.PP +.BI "char *strtok_r(char *" str ", const char *" delim ", char **" saveptr ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR strtok_r (): +_POSIX_C_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.ad b +.SH DESCRIPTION +The +.BR strtok () +function breaks a string into a sequence of zero or more nonempty tokens. +On the first call to +.BR strtok (), +the string to be parsed should be +specified in +.IR str . +In each subsequent call that should parse the same string, +.I str +must be NULL. +.PP +The +.I delim +argument specifies a set of bytes that +delimit the tokens in the parsed string. +The caller may specify different strings in +.I delim +in successive +calls that parse the same string. +.PP +Each call to +.BR strtok () +returns a pointer to a +null-terminated string containing the next token. +This string does not include the delimiting byte. +If no more tokens are found, +.BR strtok () +returns NULL. +.PP +A sequence of calls to +.BR strtok () +that operate on the same string maintains a pointer +that determines the point from which to start searching for the next token. +The first call to +.BR strtok () +sets this pointer to point to the first byte of the string. +The start of the next token is determined by scanning forward +for the next nondelimiter byte in +.IR str . +If such a byte is found, it is taken as the start of the next token. +If no such byte is found, +then there are no more tokens, and +.BR strtok () +returns NULL. +(A string that is empty or that contains only delimiters +will thus cause +.BR strtok () +to return NULL on the first call.) +.PP +The end of each token is found by scanning forward until either +the next delimiter byte is found or until the +terminating null byte (\(aq\\0\(aq) is encountered. +If a delimiter byte is found, it is overwritten with +a null byte to terminate the current token, and +.BR strtok () +saves a pointer to the following byte; +that pointer will be used as the starting point +when searching for the next token. +In this case, +.BR strtok () +returns a pointer to the start of the found token. +.PP +From the above description, +it follows that a sequence of two or more contiguous delimiter bytes in +the parsed string is considered to be a single delimiter, and that +delimiter bytes at the start or end of the string are ignored. +Put another way: the tokens returned by +.BR strtok () +are always nonempty strings. +Thus, for example, given the string "\fIaaa;;bbb,\fP", +successive calls to +.BR strtok () +that specify the delimiter string "\fI;,\fP" +would return the strings "\fIaaa\fP" and "\fIbbb\fP", +and then a null pointer. +.PP +The +.BR strtok_r () +function is a reentrant version +.BR strtok (). +The +.I saveptr +argument is a pointer to a +.IR "char\ *" +variable that is used internally by +.BR strtok_r () +in order to maintain context between successive calls that parse the +same string. +.PP +On the first call to +.BR strtok_r (), +.I str +should point to the string to be parsed, and the value of +.I saveptr +is ignored. +In subsequent calls, +.I str +should be NULL, and +.I saveptr +should be unchanged since the previous call. +.PP +Different strings may be parsed concurrently using sequences of calls to +.BR strtok_r () +that specify different +.I saveptr +arguments. +.SH RETURN VALUE +The +.BR strtok () +and +.BR strtok_r () +functions return a pointer to +the next token, or NULL if there are no more tokens. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strtok () +T} Thread safety MT-Unsafe race:strtok +T{ +.BR strtok_r () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.TP +.BR strtok () +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.TP +.BR strtok_r () +POSIX.1-2001, POSIX.1-2008. +.SH BUGS +Be cautious when using these functions. +If you do use them, note that: +.IP * 2 +These functions modify their first argument. +.IP * +These functions cannot be used on constant strings. +.IP * +The identity of the delimiting byte is lost. +.IP * +The +.BR strtok () +function uses a static buffer while parsing, so it's not thread safe. +Use +.BR strtok_r () +if this matters to you. +.SH EXAMPLE +The program below uses nested loops that employ +.BR strtok_r () +to break a string into a two-level hierarchy of tokens. +The first command-line argument specifies the string to be parsed. +The second argument specifies the delimiter byte(s) +to be used to separate that string into "major" tokens. +The third argument specifies the delimiter byte(s) +to be used to separate the "major" tokens into subtokens. +.PP +An example of the output produced by this program is the following: +.PP +.in +4n +.EX +.RB "$" " ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq" +1: a/bbb///cc + \-\-> a + \-\-> bbb + \-\-> cc +2: xxx + \-\-> xxx +3: yyy + \-\-> yyy +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + char *str1, *str2, *token, *subtoken; + char *saveptr1, *saveptr2; + int j; + + if (argc != 4) { + fprintf(stderr, "Usage: %s string delim subdelim\\n", + argv[0]); + exit(EXIT_FAILURE); + } + + for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) { + token = strtok_r(str1, argv[2], &saveptr1); + if (token == NULL) + break; + printf("%d: %s\\n", j, token); + + for (str2 = token; ; str2 = NULL) { + subtoken = strtok_r(str2, argv[3], &saveptr2); + if (subtoken == NULL) + break; + printf("\t \-\-> %s\\n", subtoken); + } + } + + exit(EXIT_SUCCESS); +} +.EE +.PP +Another example program using +.BR strtok () +can be found in +.BR getaddrinfo_a (3). +.SH SEE ALSO +.BR index (3), +.BR memchr (3), +.BR rindex (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR wcstok (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strtok_r.3 b/man3/strtok_r.3 new file mode 100644 index 0000000..19095a0 --- /dev/null +++ b/man3/strtok_r.3 @@ -0,0 +1 @@ +.so man3/strtok.3 diff --git a/man3/strtol.3 b/man3/strtol.3 new file mode 100644 index 0000000..1257a24 --- /dev/null +++ b/man3/strtol.3 @@ -0,0 +1,311 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610 +.TH STRTOL 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strtol, strtoll, strtoq \- convert a string to a long integer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long int strtol(const char *" nptr ", char **" endptr ", int " base ); +.PP +.BI "long long int strtoll(const char *" nptr ", char **" endptr \ +", int " base ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR strtoll (): +.RS 4 +_ISOC99_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR strtol () +function converts the initial part of the string +in +.I nptr +to a long integer value according to the given +.IR base , +which must be between 2 and 36 inclusive, or be the special value 0. +.PP +The string may begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional \(aq+\(aq or \(aq\-\(aq sign. +If +.I base +is zero or 16, the string may then include a +"0x" or "0X" prefix, and the number will be read in base 16; otherwise, a +zero +.I base +is taken as 10 (decimal) unless the next character +is \(aq0\(aq, in which case it is taken as 8 (octal). +.PP +The remainder of the string is converted to a +.I long int +value +in the obvious manner, stopping at the first character which is not a +valid digit in the given base. +(In bases above 10, the letter \(aqA\(aq in +either uppercase or lowercase represents 10, \(aqB\(aq represents 11, and so +forth, with \(aqZ\(aq representing 35.) +.PP +If +.I endptr +is not NULL, +.BR strtol () +stores the address of the +first invalid character in +.IR *endptr . +If there were no digits at +all, +.BR strtol () +stores the original value of +.I nptr +in +.I *endptr +(and returns 0). +In particular, if +.I *nptr +is not \(aq\\0\(aq but +.I **endptr +is \(aq\\0\(aq on return, the entire string is valid. +.PP +The +.BR strtoll () +function works just like the +.BR strtol () +function but returns a long long integer value. +.SH RETURN VALUE +The +.BR strtol () +function returns the result of the conversion, +unless the value would underflow or overflow. +If an underflow occurs, +.BR strtol () +returns +.BR LONG_MIN . +If an overflow occurs, +.BR strtol () +returns +.BR LONG_MAX . +In both cases, +.I errno +is set to +.BR ERANGE . +Precisely the same holds for +.BR strtoll () +(with +.B LLONG_MIN +and +.B LLONG_MAX +instead of +.B LONG_MIN +and +.BR LONG_MAX ). +.SH ERRORS +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.PP +The implementation may also set +.IR errno +to +.B EINVAL +in case +no conversion was performed (no digits seen, and 0 returned). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw29 lb lb +l l l. +Interface Attribute Value +T{ +.BR strtol (), +.BR strtoll (), +.BR strtoq () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +.BR strtol (): +POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4, 4.3BSD. +.PP +.BR strtoll (): +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +Since +.BR strtol () +can legitimately return 0, +.BR LONG_MAX , +or +.B LONG_MIN +.RB ( LLONG_MAX +or +.B LLONG_MIN +for +.BR strtoll ()) +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno +has a nonzero value after the call. +.PP +According to POSIX.1, +in locales other than the "C" and "POSIX", +these functions may accept other, +implementation-defined numeric strings. +.PP +BSD also has +.PP +.in +4n +.EX +.BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base ); +.EE +.in +.PP +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.BR strtoll () +or to +.BR strtol (). +.SH EXAMPLE +The program shown below demonstrates the use of +.BR strtol (). +The first command-line argument specifies a string from which +.BR strtol () +should parse a number. +The second (optional) argument specifies the base to be used for +the conversion. +(This argument is converted to numeric form using +.BR atoi (3), +a function that performs no error checking and +has a simpler interface than +.BR strtol ().) +Some examples of the results produced by this program are the following: +.PP +.in +4n +.EX +.RB "$" " ./a.out 123" +strtol() returned 123 +.RB "$" " ./a.out \(aq 123\(aq" +strtol() returned 123 +.RB "$" " ./a.out 123abc" +strtol() returned 123 +Further characters after number: abc +.RB "$" " ./a.out 123abc 55" +strtol: Invalid argument +.RB "$" " ./a.out \(aq\(aq" +No digits were found +.RB "$" " ./a.out 4000000000" +strtol: Numerical result out of range +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + int base; + char *endptr, *str; + long val; + + if (argc < 2) { + fprintf(stderr, "Usage: %s str [base]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + str = argv[1]; + base = (argc > 2) ? atoi(argv[2]) : 10; + + errno = 0; /* To distinguish success/failure after call */ + val = strtol(str, &endptr, base); + + /* Check for various possible errors */ + + if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN)) + || (errno != 0 && val == 0)) { + perror("strtol"); + exit(EXIT_FAILURE); + } + + if (endptr == str) { + fprintf(stderr, "No digits were found\\n"); + exit(EXIT_FAILURE); + } + + /* If we got here, strtol() successfully parsed a number */ + + printf("strtol() returned %ld\\n", val); + + if (*endptr != \(aq\\0\(aq) /* Not necessarily an error... */ + printf("Further characters after number: %s\\n", endptr); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtoul (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strtold.3 b/man3/strtold.3 new file mode 100644 index 0000000..ac3e4a5 --- /dev/null +++ b/man3/strtold.3 @@ -0,0 +1 @@ +.so man3/strtod.3 diff --git a/man3/strtoll.3 b/man3/strtoll.3 new file mode 100644 index 0000000..d090393 --- /dev/null +++ b/man3/strtoll.3 @@ -0,0 +1 @@ +.so man3/strtol.3 diff --git a/man3/strtoq.3 b/man3/strtoq.3 new file mode 100644 index 0000000..d090393 --- /dev/null +++ b/man3/strtoq.3 @@ -0,0 +1 @@ +.so man3/strtol.3 diff --git a/man3/strtoul.3 b/man3/strtoul.3 new file mode 100644 index 0000000..0113ae0 --- /dev/null +++ b/man3/strtoul.3 @@ -0,0 +1,240 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:03 1993 by Rik Faith (faith@cs.unc.edu) +.\" Fixed typo, aeb, 950823 +.\" 2002-02-22, joey, mihtjel: Added strtoull() +.\" +.TH STRTOUL 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strtoul, strtoull, strtouq \- convert a string to an unsigned long integer +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "unsigned long int strtoul(const char *" nptr ", char **" endptr \ +", int " base ); +.PP +.BI "unsigned long long int strtoull(const char *" nptr ", char **" endptr , +.BI " int " base ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR strtoull (): +.RS 4 +_ISOC99_SOURCE || + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR strtoul () +function converts the initial part of the string +in +.I nptr +to an +.I "unsigned long int" +value according to the +given +.IR base , +which must be between 2 and 36 inclusive, or be +the special value 0. +.PP +The string may begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional \(aq+\(aq or \(aq\-\(aq +sign. +If +.I base +is zero or 16, the string may then include a +"0x" prefix, and the number will be read in base 16; otherwise, a +zero +.I base +is taken as 10 (decimal) unless the next character +is \(aq0\(aq, in which case it is taken as 8 (octal). +.PP +The remainder of the string is converted to an +.I "unsigned long int" +value in the obvious manner, +stopping at the first character which is not a +valid digit in the given base. +(In bases above 10, the letter \(aqA\(aq in +either uppercase or lowercase represents 10, \(aqB\(aq represents 11, and so +forth, with \(aqZ\(aq representing 35.) +.PP +If +.I endptr +is not NULL, +.BR strtoul () +stores the address of the +first invalid character in +.IR *endptr . +If there were no digits at +all, +.BR strtoul () +stores the original value of +.I nptr +in +.I *endptr +(and returns 0). +In particular, if +.I *nptr +is not \(aq\\0\(aq but +.I **endptr +is \(aq\\0\(aq on return, the entire string is valid. +.PP +The +.BR strtoull () +function works just like the +.BR strtoul () +function but returns an +.I "unsigned long long int" +value. +.SH RETURN VALUE +The +.BR strtoul () +function returns either the result of the conversion +or, if there was a leading minus sign, the negation of the result of the +conversion represented as an unsigned value, +unless the original (nonnegated) value would overflow; in +the latter case, +.BR strtoul () +returns +.B ULONG_MAX +and sets +.I errno +to +.BR ERANGE . +Precisely the same holds for +.BR strtoull () +(with +.B ULLONG_MAX +instead of +.BR ULONG_MAX ). +.SH ERRORS +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.PP +The implementation may also set +.IR errno +to +.B EINVAL +in case +no conversion was performed (no digits seen, and 0 returned). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw32 lb lb +l l l. +Interface Attribute Value +T{ +.BR strtoul (), +.BR strtoull (), +.BR strtouq () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +.BR strtoul (): +POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4. +.PP +.BR strtoull (): +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +Since +.BR strtoul () +can legitimately return 0 or +.B ULONG_MAX +.RB ( ULLONG_MAX +for +.BR strtoull ()) +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno +has a nonzero value after the call. +.PP +In locales other than the "C" locale, other strings may be accepted. +(For example, the thousands separator of the current locale may be +supported.) +.PP +BSD also has +.PP +.in +4n +.EX +.BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base ); +.EE +.in +.PP +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.BR strtoull () +or to +.BR strtoul (). +.PP +Negative values are considered valid input and are +silently converted to the equivalent +.I "unsigned long int" +value. +.SH EXAMPLE +See the example on the +.BR strtol (3) +manual page; +the use of the functions described in this manual page is similar. +.SH SEE ALSO +.BR a64l (3), +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtol (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strtoull.3 b/man3/strtoull.3 new file mode 100644 index 0000000..3340a83 --- /dev/null +++ b/man3/strtoull.3 @@ -0,0 +1 @@ +.so man3/strtoul.3 diff --git a/man3/strtoumax.3 b/man3/strtoumax.3 new file mode 100644 index 0000000..753be84 --- /dev/null +++ b/man3/strtoumax.3 @@ -0,0 +1 @@ +.so man3/strtoimax.3 diff --git a/man3/strtouq.3 b/man3/strtouq.3 new file mode 100644 index 0000000..3340a83 --- /dev/null +++ b/man3/strtouq.3 @@ -0,0 +1 @@ +.so man3/strtoul.3 diff --git a/man3/strverscmp.3 b/man3/strverscmp.3 new file mode 100644 index 0000000..c55fb29 --- /dev/null +++ b/man3/strverscmp.3 @@ -0,0 +1,167 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH STRVERSCMP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +strverscmp \- compare two version strings +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int strverscmp(const char *" s1 ", const char *" s2 ); +.fi +.SH DESCRIPTION +Often one has files +.IR jan1 ", " jan2 ", ..., " jan9 ", " jan10 ", ..." +and it feels wrong when +.BR ls (1) +orders them +.IR jan1 ", " jan10 ", ..., " jan2 ", ..., " jan9 . +.\" classical solution: "rename jan jan0 jan?" +In order to rectify this, GNU introduced the +.I \-v +option to +.BR ls (1), +which is implemented using +.BR versionsort (3), +which again uses +.BR strverscmp (). +.PP +Thus, the task of +.BR strverscmp () +is to compare two strings and find the "right" order, while +.BR strcmp (3) +finds only the lexicographic order. +This function does not use +the locale category +.BR LC_COLLATE , +so is meant mostly for situations +where the strings are expected to be in ASCII. +.PP +What this function does is the following. +If both strings are equal, return 0. +Otherwise, find the position +between two bytes with the property that before it both strings are equal, +while directly after it there is a difference. +Find the largest consecutive digit strings containing (or starting at, +or ending at) this position. +If one or both of these is empty, +then return what +.BR strcmp (3) +would have returned (numerical ordering of byte values). +Otherwise, compare both digit strings numerically, where digit strings with +one or more leading zeros are interpreted as if they have a decimal point +in front (so that in particular digit strings with more leading zeros +come before digit strings with fewer leading zeros). +Thus, the ordering is +.IR 000 ", " 00 ", " 01 ", " 010 ", " 09 ", " 0 ", " 1 ", " 9 ", " 10 . +.SH RETURN VALUE +The +.BR strverscmp () +function returns an integer +less than, equal to, or greater than zero if +.I s1 +is found, respectively, to be earlier than, equal to, +or later than +.IR s2 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strverscmp () +T} Thread safety MT-Safe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" strverscmp: MT-Safe locale +.\" +.\" glibc manual says strverscmp should have marking locale because it calls +.\" isdigit() multiple times and isdigit() uses locale variable. +.\" But isdigit() has two implementations. With different compiling conditions, +.\" we may call isdigit() in macro, then strverscmp() should not have locale +.\" problem. +.SH CONFORMING TO +This function is a GNU extension. +.SH EXAMPLE +The program below can be used to demonstrate the behavior of +.BR strverscmp (). +It uses +.BR strverscmp () +to compare the two strings given as its command-line arguments. +An example of its use is the following: +.PP +.in +4n +.EX +$ \fB./a.out jan1 jan10\fP +jan1 < jan10 +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + int res; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + exit(EXIT_FAILURE); + } + + res = strverscmp(argv[1], argv[2]); + + printf("%s %s %s\\n", argv[1], + (res < 0) ? "<" : (res == 0) ? "==" : ">", argv[2]); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR rename (1), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/strxfrm.3 b/man3/strxfrm.3 new file mode 100644 index 0000000..8f306fc --- /dev/null +++ b/man3/strxfrm.3 @@ -0,0 +1,106 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:28 1993 by Rik Faith (faith@cs.unc.edu) +.TH STRXFRM 3 2016-07-17 "GNU" "Linux Programmer's Manual" +.SH NAME +strxfrm \- string transformation +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t strxfrm(char *" dest ", const char *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strxfrm () +function transforms the +.I src +string into a +form such that the result of +.BR strcmp (3) +on two strings that have +been transformed with +.BR strxfrm () +is the same as the result of +.BR strcoll (3) +on the two strings before their transformation. +The first +.I n +bytes of the transformed string are placed in +.IR dest . +The transformation is based on the program's current +locale for category +.BR LC_COLLATE . +(See +.BR setlocale (3)). +.SH RETURN VALUE +The +.BR strxfrm () +function returns the number of bytes required to +store the transformed string in +.I dest +excluding the +terminating null byte (\(aq\\0\(aq). +If the value returned is +.I n +or more, the +contents of +.I dest +are indeterminate. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR strxfrm () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bcmp (3), +.BR memcmp (3), +.BR setlocale (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR string (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/svc_destroy.3 b/man3/svc_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_freeargs.3 b/man3/svc_freeargs.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_freeargs.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_getargs.3 b/man3/svc_getargs.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_getargs.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_getcaller.3 b/man3/svc_getcaller.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_getcaller.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_getreq.3 b/man3/svc_getreq.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_getreq.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_getreqset.3 b/man3/svc_getreqset.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_getreqset.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_register.3 b/man3/svc_register.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_register.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_run.3 b/man3/svc_run.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_run.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_sendreply.3 b/man3/svc_sendreply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_sendreply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svc_unregister.3 b/man3/svc_unregister.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svc_unregister.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_auth.3 b/man3/svcerr_auth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcerr_auth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_decode.3 b/man3/svcerr_decode.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcerr_decode.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_noproc.3 b/man3/svcerr_noproc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcerr_noproc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_noprog.3 b/man3/svcerr_noprog.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcerr_noprog.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_progvers.3 b/man3/svcerr_progvers.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcerr_progvers.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_systemerr.3 b/man3/svcerr_systemerr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcerr_systemerr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcerr_weakauth.3 b/man3/svcerr_weakauth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcerr_weakauth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcfd_create.3 b/man3/svcfd_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcfd_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcraw_create.3 b/man3/svcraw_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcraw_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svctcp_create.3 b/man3/svctcp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svctcp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcudp_bufcreate.3 b/man3/svcudp_bufcreate.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcudp_bufcreate.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/svcudp_create.3 b/man3/svcudp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/svcudp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/swab.3 b/man3/swab.3 new file mode 100644 index 0000000..24713de --- /dev/null +++ b/man3/swab.3 @@ -0,0 +1,96 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:52:15 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-12-15, aeb +.TH SWAB 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +swab \- swap adjacent bytes +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void swab(const void *" from ", void *" to ", ssize_t " n ); +.fi +.SH DESCRIPTION +The +.BR swab () +function copies +.I n +bytes from the array pointed +to by +.I from +to the array pointed to by +.IR to , +exchanging +adjacent even and odd bytes. +This function is used to exchange data +between machines that have different low/high byte ordering. +.PP +This function does nothing when +.I n +is negative. +When +.I n +is positive and odd, it handles +.I n\-1 +bytes +as above, and does something unspecified with the last byte. +(In other words, +.I n +should be even.) +.SH RETURN VALUE +The +.BR swab () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR swab () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bstring (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/swapcontext.3 b/man3/swapcontext.3 new file mode 100644 index 0000000..cdccd64 --- /dev/null +++ b/man3/swapcontext.3 @@ -0,0 +1 @@ +.so man3/makecontext.3 diff --git a/man3/swprintf.3 b/man3/swprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man3/swprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/sys_errlist.3 b/man3/sys_errlist.3 new file mode 100644 index 0000000..837f1a1 --- /dev/null +++ b/man3/sys_errlist.3 @@ -0,0 +1 @@ +.so man3/perror.3 diff --git a/man3/sys_nerr.3 b/man3/sys_nerr.3 new file mode 100644 index 0000000..837f1a1 --- /dev/null +++ b/man3/sys_nerr.3 @@ -0,0 +1 @@ +.so man3/perror.3 diff --git a/man3/sysconf.3 b/man3/sysconf.3 new file mode 100644 index 0000000..bbeedb1 --- /dev/null +++ b/man3/sysconf.3 @@ -0,0 +1,403 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:51:42 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Aug 17 11:42:20 1999 by Ariel Scolnicov (ariels@compugen.co.il) +.TH SYSCONF 3 2017-11-26 "GNU" "Linux Programmer's Manual" +.SH NAME +sysconf \- get configuration information at run time +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long sysconf(int " "name" ); +.fi +.SH DESCRIPTION +POSIX allows an application to test at compile or run time +whether certain options are supported, or what the value is +of certain configurable constants or limits. +.PP +At compile time this is done by including +.I +and/or +.I +and testing the value of certain macros. +.PP +At run time, one can ask for numerical values using the present function +.BR sysconf (). +One can ask for numerical values that may depend +on the filesystem in which a file resides using +.BR fpathconf (3) +and +.BR pathconf (3). +One can ask for string values using +.BR confstr (3). +.PP +The values obtained from these functions are system configuration constants. +They do not change during the lifetime of a process. +.\" except that sysconf(_SC_OPEN_MAX) may change answer after a call +.\" to setrlimit( ) which changes the RLIMIT_NOFILE soft limit +.PP +For options, typically, there is a constant +.B _POSIX_FOO +that may be defined in +.IR . +If it is undefined, one should ask at run time. +If it is defined to \-1, then the option is not supported. +If it is defined to 0, then relevant functions and headers exist, +but one has to ask at run time what degree of support is available. +If it is defined to a value other than \-1 or 0, then the option is +supported. +Usually the value (such as 200112L) indicates the year and month +of the POSIX revision describing the option. +Glibc uses the value 1 +to indicate support as long as the POSIX revision has not been published yet. +.\" and 999 to indicate support for options no longer present in the latest +.\" standard. (?) +The +.BR sysconf () +argument will be +.BR _SC_FOO . +For a list of options, see +.BR posixoptions (7). +.PP +For variables or limits, typically, there is a constant +.BR _FOO , +maybe defined in +.IR , +or +.BR _POSIX_FOO , +maybe defined in +.IR . +The constant will not be defined if the limit is unspecified. +If the constant is defined, it gives a guaranteed value, and +a greater value might actually be supported. +If an application wants to take advantage of values which may change +between systems, a call to +.BR sysconf () +can be made. +The +.BR sysconf () +argument will be +.BR _SC_FOO . +.SS POSIX.1 variables +We give the name of the variable, the name of the +.BR sysconf () +argument used to inquire about its value, +and a short description. +.PP +First, the POSIX.1 compatible values. +.\" [for the moment: only the things that are unconditionally present] +.\" .TP +.\" .BR AIO_LISTIO_MAX " - " _SC_AIO_LISTIO_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" Maximum number of I/O operations in a single list I/O call. +.\" Must not be less than _POSIX_AIO_LISTIO_MAX. +.\" .TP +.\" .BR AIO_MAX " - " _SC_AIO_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" Maximum number of outstanding asynchronous I/O operations. +.\" Must not be less than _POSIX_AIO_MAX. +.\" .TP +.\" .BR AIO_PRIO_DELTA_MAX " - " _SC_AIO_PRIO_DELTA_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" The maximum amount by which a process can decrease its +.\" asynchronous I/O priority level from its own scheduling priority. +.\" Must be nonnegative. +.TP +.BR ARG_MAX " - " _SC_ARG_MAX +The maximum length of the arguments to the +.BR exec (3) +family of functions. +Must not be less than +.B _POSIX_ARG_MAX +(4096). +.TP +.BR CHILD_MAX " - " _SC_CHILD_MAX +The maximum number of simultaneous processes per user ID. +Must not be less than +.B _POSIX_CHILD_MAX +(25). +.TP +.BR HOST_NAME_MAX " - " _SC_HOST_NAME_MAX +Maximum length of a hostname, not including the terminating null byte, +as returned by +.BR gethostname (2). +Must not be less than +.B _POSIX_HOST_NAME_MAX +(255). +.TP +.BR LOGIN_NAME_MAX " - " _SC_LOGIN_NAME_MAX +Maximum length of a login name, including the terminating null byte. +Must not be less than +.B _POSIX_LOGIN_NAME_MAX +(9). +.TP +.BR NGROUPS_MAX " - " _SC_NGROUPS_MAX +Maximum number of supplementary group IDs. +.TP +.BR "" "clock ticks - " _SC_CLK_TCK +The number of clock ticks per second. +The corresponding variable is obsolete. +It was of course called +.BR CLK_TCK . +(Note: the macro +.B CLOCKS_PER_SEC +does not give information: it must equal 1000000.) +.TP +.BR OPEN_MAX " - " _SC_OPEN_MAX +The maximum number of files that a process can have open at any time. +Must not be less than +.B _POSIX_OPEN_MAX +(20). +.TP +.BR PAGESIZE " - " _SC_PAGESIZE +Size of a page in bytes. +Must not be less than 1. +(Some systems use PAGE_SIZE instead.) +.TP +.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX +The number of repeated occurrences of a BRE permitted by +.BR regexec (3) +and +.BR regcomp (3). +Must not be less than +.B _POSIX2_RE_DUP_MAX +(255). +.TP +.BR STREAM_MAX " - " _SC_STREAM_MAX +The maximum number of streams that a process can have open at any +time. +If defined, it has the same value as the standard C macro +.BR FOPEN_MAX . +Must not be less than +.B _POSIX_STREAM_MAX +(8). +.TP +.BR SYMLOOP_MAX " - " _SC_SYMLOOP_MAX +The maximum number of symbolic links seen in a pathname before resolution +returns +.BR ELOOP . +Must not be less than +.B _POSIX_SYMLOOP_MAX +(8). +.TP +.BR TTY_NAME_MAX " - " _SC_TTY_NAME_MAX +The maximum length of terminal device name, +including the terminating null byte. +Must not be less than +.B _POSIX_TTY_NAME_MAX +(9). +.TP +.BR TZNAME_MAX " - " _SC_TZNAME_MAX +The maximum number of bytes in a timezone name. +Must not be less than +.B _POSIX_TZNAME_MAX +(6). +.TP +.BR _POSIX_VERSION " - " _SC_VERSION +indicates the year and month the POSIX.1 standard was approved in the +format +.BR YYYYMML ; +the value +.B 199009L +indicates the Sept. 1990 revision. +.SS POSIX.2 variables +Next, the POSIX.2 values, giving limits for utilities. +.TP +.BR BC_BASE_MAX " - " _SC_BC_BASE_MAX +indicates the maximum +.I obase +value accepted by the +.BR bc (1) +utility. +.TP +.BR BC_DIM_MAX " - " _SC_BC_DIM_MAX +indicates the maximum value of elements permitted in an array by +.BR bc (1). +.TP +.BR BC_SCALE_MAX " - " _SC_BC_SCALE_MAX +indicates the maximum +.I scale +value allowed by +.BR bc (1). +.TP +.BR BC_STRING_MAX " - " _SC_BC_STRING_MAX +indicates the maximum length of a string accepted by +.BR bc (1). +.TP +.BR COLL_WEIGHTS_MAX " - " _SC_COLL_WEIGHTS_MAX +indicates the maximum numbers of weights that can be assigned to an +entry of the +.B LC_COLLATE order +keyword in the locale definition file, +.TP +.BR EXPR_NEST_MAX " - " _SC_EXPR_NEST_MAX +is the maximum number of expressions which can be nested within +parentheses by +.BR expr (1). +.TP +.BR LINE_MAX " - " _SC_LINE_MAX +The maximum length of a utility's input line, either from +standard input or from a file. +This includes space for a trailing +newline. +.TP +.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX +The maximum number of repeated occurrences of a regular expression when +the interval notation +.B \e{m,n\e} +is used. +.TP +.BR POSIX2_VERSION " - " _SC_2_VERSION +indicates the version of the POSIX.2 standard in the format of +YYYYMML. +.TP +.BR POSIX2_C_DEV " - " _SC_2_C_DEV +indicates whether the POSIX.2 C language development facilities are +supported. +.TP +.BR POSIX2_FORT_DEV " - " _SC_2_FORT_DEV +indicates whether the POSIX.2 FORTRAN development utilities are +supported. +.TP +.BR POSIX2_FORT_RUN " - " _SC_2_FORT_RUN +indicates whether the POSIX.2 FORTRAN run-time utilities are supported. +.TP +.BR _POSIX2_LOCALEDEF " - " _SC_2_LOCALEDEF +indicates whether the POSIX.2 creation of locates via +.BR localedef (1) +is supported. +.TP +.BR POSIX2_SW_DEV " - " _SC_2_SW_DEV +indicates whether the POSIX.2 software development utilities option is +supported. +.PP +These values also exist, but may not be standard. +.TP +.BR "" " - " _SC_PHYS_PAGES +The number of pages of physical memory. +Note that it is possible +for the product of this value and the value of +.B _SC_PAGESIZE +to overflow. +.TP +.BR "" " - " _SC_AVPHYS_PAGES +The number of currently available pages of physical memory. +.TP +.BR "" " - " _SC_NPROCESSORS_CONF +The number of processors configured. +See also +.BR get_nprocs_conf (3). +.TP +.BR "" " - " _SC_NPROCESSORS_ONLN +The number of processors currently online (available). +See also +.BR get_nprocs_conf (3). +.SH RETURN VALUE +The return value of +.BR sysconf () +is one of the following: +.IP * 3 +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error +(for example, +.BR EINVAL , +indicating that +.I name +is invalid). +.IP * +If +.I name +corresponds to a maximum or minimum limit, and that limit is indeterminate, +\-1 is returned and +.I errno +is not changed. +(To distinguish an indeterminate limit from an error, set +.I errno +to zero before the call, and then check whether +.I errno +is nonzero when \-1 is returned.) +.IP * +If +.I name +corresponds to an option, +a positive value is returned if the option is supported, +and \-1 is returned if the option is not supported. +.IP * +Otherwise, +the current value of the option or limit is returned. +This value will not be more restrictive than +the corresponding value that was described to the application in +.I +or +.I +when the application was compiled. +.SH ERRORS +.TP +.B EINVAL +.I name +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sysconf () +T} Thread safety MT-Safe env +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH BUGS +It is difficult to use +.B ARG_MAX +because it is not specified how much of the argument space for +.BR exec (3) +is consumed by the user's environment variables. +.PP +Some returned values may be huge; they are not suitable for allocating +memory. +.SH SEE ALSO +.BR bc (1), +.BR expr (1), +.BR getconf (1), +.BR locale (1), +.BR confstr (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR posixoptions (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/syslog.3 b/man3/syslog.3 new file mode 100644 index 0000000..96537f6 --- /dev/null +++ b/man3/syslog.3 @@ -0,0 +1,373 @@ +.\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) +.\" and Copyright 2001, 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Updated 1999.12.19 by Karl M. Hegbloom +.\" +.\" Updated 13 Oct 2001, Michael Kerrisk +.\" Added description of vsyslog +.\" Added descriptions of LOG_ODELAY and LOG_NOWAIT +.\" Added brief description of facility and option arguments +.\" Added CONFORMING TO section +.\" 2001-10-13, aeb, minor changes +.\" Modified 13 Dec 2001, Martin Schulze +.\" Modified 3 Jan 2002, Michael Kerrisk +.\" +.TH SYSLOG 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +closelog, openlog, syslog, vsyslog \- send messages to the system logger +.SH SYNOPSIS +.B #include +.PP +.BI "void openlog(const char *" ident ", int " option ", int " facility ); +.br +.BI "void syslog(int " priority ", const char *" format ", ...);" +.br +.B "void closelog(void);" +.PP +.BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR vsyslog (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +.SS openlog() +.BR openlog () +opens a connection to the system logger for a program. +.PP +The string pointed to by +.I ident +is prepended to every message, and is typically set to the program name. +If +.I ident +is NULL, the program name is used. +(POSIX.1-2008 does not specify the behavior when +.I ident +is NULL.) +.PP +The +.I option +argument specifies flags which control the operation of +.BR openlog () +and subsequent calls to +.BR syslog (). +The +.I facility +argument establishes a default to be used if +none is specified in subsequent calls to +.BR syslog (). +The values that may be specified for +.I option +and +.I facility +are described below. +.PP +The use of +.BR openlog () +is optional; it will automatically be called by +.BR syslog () +if necessary, in which case +.I ident +will default to NULL. +.\" +.SS syslog() and vsyslog() +.BR syslog () +generates a log message, which will be distributed by +.BR syslogd (8). +.PP +The +.I priority +argument is formed by ORing together a +.I facility +value and a +.I level +value (described below). +If no +.I facility +value is ORed into +.IR priority , +then the default value set by +.BR openlog () +is used, or, if there was no preceding +.BR openlog () +call, a default of +.BR LOG_USER +is employed. +.PP +The remaining arguments are a +.IR format , +as in +.BR printf (3), +and any arguments required by the +.IR format , +except that the two-character sequence +.B %m +will be replaced by +the error message string +.IR strerror ( errno ). +The format string need not include a terminating newline character. +.PP +The function +.BR vsyslog () +performs the same task as +.BR syslog () +with the difference that it takes a set of arguments which have +been obtained using the +.BR stdarg (3) +variable argument list macros. +.\" +.SS closelog() +.BR closelog () +closes the file descriptor being used to write to the system logger. +The use of +.BR closelog () +is optional. +.\" +.SS Values for \fIoption\fP +The +.I option +argument to +.BR openlog () +is a bit mask constructed by ORing together any of the following values: +.TP 15 +.B LOG_CONS +Write directly to the system console if there is an error while sending to +the system logger. +.TP +.B LOG_NDELAY +Open the connection immediately (normally, the connection is opened when +the first message is logged). +This may be useful, for example, if a subsequent +.BR chroot (2) +would make the pathname used internally by the logging facility unreachable. +.TP +.B LOG_NOWAIT +Don't wait for child processes that may have been created while logging +the message. +(The GNU C library does not create a child process, so this +option has no effect on Linux.) +.TP +.B LOG_ODELAY +The converse of +.BR LOG_NDELAY ; +opening of the connection is delayed until +.BR syslog () +is called. +(This is the default, and need not be specified.) +.TP +.B LOG_PERROR +(Not in POSIX.1-2001 or POSIX.1-2008.) +Also log the message to +.IR stderr . +.TP +.B LOG_PID +Include the caller's PID with each message. +.\" +.SS Values for \fIfacility\fP +The +.I facility +argument is used to specify what type of program is logging the message. +This lets the configuration file specify that messages from different +facilities will be handled differently. +.TP 15 +.B LOG_AUTH +security/authorization messages +.TP +.B LOG_AUTHPRIV +security/authorization messages (private) +.TP +.B LOG_CRON +clock daemon +.RB ( cron " and " at ) +.TP +.B LOG_DAEMON +system daemons without separate facility value +.TP +.B LOG_FTP +ftp daemon +.TP +.B LOG_KERN +kernel messages (these can't be generated from user processes) +.\" LOG_KERN has the value 0; if used as a facility, zero translates to: +.\" "use the default facility". +.TP +.BR LOG_LOCAL0 " through " LOG_LOCAL7 +reserved for local use +.TP +.B LOG_LPR +line printer subsystem +.TP +.B LOG_MAIL +mail subsystem +.TP +.B LOG_NEWS +USENET news subsystem +.TP +.B LOG_SYSLOG +messages generated internally by +.BR syslogd (8) +.TP +.BR LOG_USER " (default)" +generic user-level messages +.TP +.B LOG_UUCP +UUCP subsystem +.\" +.SS Values for \fIlevel\fP +This determines the importance of the message. +The levels are, in order of decreasing importance: +.TP 15 +.B LOG_EMERG +system is unusable +.TP +.B LOG_ALERT +action must be taken immediately +.TP +.B LOG_CRIT +critical conditions +.TP +.B LOG_ERR +error conditions +.TP +.B LOG_WARNING +warning conditions +.TP +.B LOG_NOTICE +normal, but significant, condition +.TP +.B LOG_INFO +informational message +.TP +.B LOG_DEBUG +debug-level message +.PP +The function +.BR setlogmask (3) +can be used to restrict logging to specified levels only. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR openlog (), +.BR closelog () +T} Thread safety MT-Safe +T{ +.BR syslog (), +.BR vsyslog () +T} Thread safety MT-Safe env locale +.TE +.SH CONFORMING TO +The functions +.BR openlog (), +.BR closelog (), +and +.BR syslog () +(but not +.BR vsyslog ()) +are specified in SUSv2, POSIX.1-2001, and POSIX.1-2008. +.PP +POSIX.1-2001 specifies only the +.B LOG_USER +and +.B LOG_LOCAL* +values for +.IR facility . +However, with the exception of +.B LOG_AUTHPRIV +and +.BR LOG_FTP , +the other +.I facility +values appear on most UNIX systems. +.PP +The +.B LOG_PERROR +value for +.I option +is not specified by POSIX.1-2001 or POSIX.1-2008, but is available +in most versions of UNIX. +.\" .SH HISTORY +.\" A +.\" .BR syslog () +.\" function call appeared in 4.2BSD. +.\" 4.3BSD documents +.\" .BR openlog (), +.\" .BR syslog (), +.\" .BR closelog (), +.\" and +.\" .BR setlogmask (). +.\" 4.3BSD-Reno also documents +.\" .BR vsyslog (). +.\" Of course early v* functions used the +.\" .I +.\" mechanism, which is not compatible with +.\" .IR . +.SH NOTES +The argument +.I ident +in the call of +.BR openlog () +is probably stored as-is. +Thus, if the string it points to +is changed, +.BR syslog () +may start prepending the changed string, and if the string +it points to ceases to exist, the results are undefined. +Most portable is to use a string constant. +.PP +Never pass a string with user-supplied data as a format, +use the following instead: +.PP +.in +4n +.EX +syslog(priority, "%s", string); +.EE +.in +.SH SEE ALSO +.BR journalctl (1), +.BR logger (1), +.BR setlogmask (3), +.BR syslog.conf (5), +.BR syslogd (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/system.3 b/man3/system.3 new file mode 100644 index 0000000..0e2d410 --- /dev/null +++ b/man3/system.3 @@ -0,0 +1,261 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (c) 2014 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:51:15 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 14 May 2001, 23 Sep 2001 by aeb +.\" 2004-12-20, mtk +.\" +.TH SYSTEM 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +system \- execute a shell command +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int system(const char *" "command" ); +.fi +.SH DESCRIPTION +The +.BR system () +library function uses +.BR fork (2) +to create a child process that executes the shell command specified in +.I command +using +.BR execl (3) +as follows: +.PP + execl("/bin/sh", "sh", "-c", command, (char *) 0); +.PP +.BR system () +returns after the command has been completed. +.PP +During execution of the command, +.B SIGCHLD +will be blocked, and +.B SIGINT +and +.B SIGQUIT +will be ignored, in the process that calls +.BR system () +(these signals will be handled according to their defaults inside +the child process that executes +.IR command ). +.PP +If +.I command +is NULL, then +.BR system () +returns a status indicating whether a shell is available on the system. +.SH RETURN VALUE +The return value of +.BR system () +is one of the following: +.IP * 3 +If +.I command +is NULL, then a nonzero value if a shell is available, +or 0 if no shell is available. +.IP * +If a child process could not be created, +or its status could not be retrieved, +the return value is \-1. +.IP * +If a shell could not be executed in the child process, +then the return value is as though the child shell terminated by calling +.BR _exit (2) +with the status 127. +.IP * +If all system calls succeed, +then the return value is the termination status of the child shell +used to execute +.IR command . +(The termination status of a shell is the termination status of +the last command it executes.) +.PP +In the last two cases, +the return value is a "wait status" that can be examined using +the macros described in +.BR waitpid (2). +(i.e., +.BR WIFEXITED (), +.BR WEXITSTATUS (), +and so on). +.PP +.BR system () +does not affect the wait status of any other children. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR system () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99. +.SH NOTES +.BR system () +provides simplicity and convenience: +it handles all of the details of calling +.BR fork (2), +.BR execl (3), +and +.BR waitpid (2), +as well as the necessary manipulations of signals; +in addition, +the shell performs the usual substitutions and I/O redirections for +.IR command . +The main cost of +.BR system () +is inefficiency: +additional system calls are required to create the process that +runs the shell and to execute the shell. +.PP +If the +.B _XOPEN_SOURCE +feature test macro is defined +(before including +.I any +header files), +then the macros described in +.BR waitpid (2) +.RB ( WEXITSTATUS (), +etc.) are made available when including +.IR . +.PP +As mentioned, +.BR system () +ignores +.B SIGINT +and +.BR SIGQUIT . +This may make programs that call it +from a loop uninterruptible, unless they take care themselves +to check the exit status of the child. +For example: +.PP +.in +4n +.EX +while (something) { + int ret = system("foo"); + + if (WIFSIGNALED(ret) && + (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) + break; +} +.EE +.in +.PP +According to POSIX.1, it is unspecified whether handlers registered using +.BR pthread_atfork (3) +are called during the execution of +.BR system (). +In the glibc implementation, such handlers are not called. +.PP +In versions of glibc before 2.1.3, the check for the availability of +.I /bin/sh +was not actually performed if +.I command +was NULL; instead it was always assumed to be available, and +.BR system () +always returned 1 in this case. +Since glibc 2.1.3, this check is performed because, even though +POSIX.1-2001 requires a conforming implementation to provide +a shell, that shell may not be available or executable if +the calling program has previously called +.BR chroot (2) +(which is not specified by POSIX.1-2001). +.PP +It is possible for the shell command to terminate with a status of 127, +which yields a +.BR system () +return value that is indistinguishable from the case +where a shell could not be executed in the child process. +.\" +.SS Caveats +.PP +Do not use +.BR system () +from a privileged program +(a set-user-ID or set-group-ID program, or a program with capabilities) +because strange values for some environment variables +might be used to subvert system integrity. +For example, +.BR PATH +could be manipulated so that an arbitrary program +is executed with privilege. +Use the +.BR exec (3) +family of functions instead, but not +.BR execlp (3) +or +.BR execvp (3) +(which also use the +.B PATH +environment variable to search for an executable). +.PP +.BR system () +will not, in fact, work properly from programs with set-user-ID or +set-group-ID privileges on systems on which +.I /bin/sh +is bash version 2: as a security measure, bash 2 drops privileges on startup. +(Debian uses a different shell, +.BR dash (1), +which does not do this when invoked as +.BR sh .) +.PP +Any user input that is employed as part of +.I command +should be +.I carefully +sanitized, to ensure that unexpected shell commands or command options +are not executed. +Such risks are especially grave when using +.BR system () +from a privileged program. +.SH SEE ALSO +.BR sh (1), +.BR execve (2), +.BR fork (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR wait (2), +.BR exec (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/sysv_signal.3 b/man3/sysv_signal.3 new file mode 100644 index 0000000..233ef4b --- /dev/null +++ b/man3/sysv_signal.3 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SYSV_SIGNAL 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +sysv_signal \- signal handling with System V semantics +.SH SYNOPSIS +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.br +.B #include +.PP +.B typedef void (*sighandler_t)(int); +.PP +.BI "sighandler_t sysv_signal(int " signum ", sighandler_t " handler ); +.SH DESCRIPTION +The +.BR sysv_signal () +function takes the same arguments, and performs the same task, as +.BR signal (2). +.PP +However +.BR sysv_signal () +provides the System V unreliable signal semantics, that is: +a) the disposition of the signal is reset to the default +when the handler is invoked; +b) delivery of further instances of the signal is not blocked while +the signal handler is executing; and +c) if the handler interrupts (certain) blocking system calls, +then the system call is not automatically restarted. +.SH RETURN VALUE +The +.BR sysv_signal () +function returns the previous value of the signal handler, or +.B SIG_ERR +on error. +.SH ERRORS +As for +.BR signal (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR sysv_signal () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +This function is nonstandard. +.SH NOTES +Use of +.BR sysv_signal () +should be avoided; use +.BR sigaction (2) +instead. +.PP +On older Linux systems, +.BR sysv_signal () +and +.BR signal (2) +were equivalent. +But on newer systems, +.BR signal (2) +provides reliable signal semantics; see +.BR signal (2) +for details. +.PP +The use of +.I sighandler_t +is a GNU extension; +this type is defined only if +the +.B _GNU_SOURCE +feature test macro is defined. +.SH SEE ALSO +.BR sigaction (2), +.BR signal (2), +.BR bsd_signal (3), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tan.3 b/man3/tan.3 new file mode 100644 index 0000000..37145b7 --- /dev/null +++ b/man3/tan.3 @@ -0,0 +1,171 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH TAN 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +tan, tanf, tanl \- tangent function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double tan(double " x ); +.BI "float tanf(float " x ); +.BI "long double tanl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR tanf (), +.BR tanl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the tangent of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the tangent of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.PP +If the correct result would overflow, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.\" I think overflow can't occur, because the closest floating-point +.\" representation of pi/2 is still not close enough to pi/2 to +.\" produce a large enough value to overflow. +.\" Testing certainly seems to bear this out. -- mtk, Jul 08 +.\" +.\" POSIX.1 allows an optional underflow error; +.\" glibc 2.8 doesn't do this +.\" POSIX.1 an optional range error for subnormal x; +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.BR EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error: result overflow +.\" Unable to test this case, since the best approximation of +.\" pi/2 in double precision only yields a tan() value of 1.633e16. +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR tan (), +.BR tanf (), +.BR tanl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before version 2.10, the glibc implementation did not set +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6782 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR ctan (3), +.BR sin (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tanf.3 b/man3/tanf.3 new file mode 100644 index 0000000..58e5a16 --- /dev/null +++ b/man3/tanf.3 @@ -0,0 +1 @@ +.so man3/tan.3 diff --git a/man3/tanh.3 b/man3/tanh.3 new file mode 100644 index 0000000..1fe00d6 --- /dev/null +++ b/man3/tanh.3 @@ -0,0 +1,130 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH TANH 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +tanh, tanhf, tanhl \- hyperbolic tangent function +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double tanh(double " x ); +.BI "float tanhf(float " x ); +.BI "long double tanhl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR tanhf (), +.BR tanhl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.SH DESCRIPTION +These functions return the hyperbolic tangent of +.IR x , +which +is defined mathematically as: +.PP +.nf + tanh(x) = sinh(x) / cosh(x) +.fi +.SH RETURN VALUE +On success, these functions return the hyperbolic tangent of +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.PP +If +.I x +is positive infinity (negative infinity), ++1 (\-1) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error (underflow) +.\" for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR tanh (), +.BR tanhf (), +.BR tanhl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.PP +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR ctanh (3), +.BR sinh (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tanhf.3 b/man3/tanhf.3 new file mode 100644 index 0000000..3556edb --- /dev/null +++ b/man3/tanhf.3 @@ -0,0 +1 @@ +.so man3/tanh.3 diff --git a/man3/tanhl.3 b/man3/tanhl.3 new file mode 100644 index 0000000..3556edb --- /dev/null +++ b/man3/tanhl.3 @@ -0,0 +1 @@ +.so man3/tanh.3 diff --git a/man3/tanl.3 b/man3/tanl.3 new file mode 100644 index 0000000..58e5a16 --- /dev/null +++ b/man3/tanl.3 @@ -0,0 +1 @@ +.so man3/tan.3 diff --git a/man3/tcdrain.3 b/man3/tcdrain.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/tcdrain.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcflow.3 b/man3/tcflow.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/tcflow.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcflush.3 b/man3/tcflush.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/tcflush.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcgetattr.3 b/man3/tcgetattr.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/tcgetattr.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcgetpgrp.3 b/man3/tcgetpgrp.3 new file mode 100644 index 0000000..3ceb14d --- /dev/null +++ b/man3/tcgetpgrp.3 @@ -0,0 +1,145 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TCGETPGRP 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +tcgetpgrp, tcsetpgrp \- get and set terminal foreground process group +.SH SYNOPSIS +.B "#include " +.PP +.BI "pid_t tcgetpgrp(int " fd ); +.PP +.BI "int tcsetpgrp(int " fd ", pid_t " pgrp ); +.SH DESCRIPTION +The function +.BR tcgetpgrp () +returns the process group ID of the foreground process group on the +terminal associated to +.IR fd , +which must be the controlling terminal of the calling process. +.\" The process itself may be a background process. +.PP +The function +.BR tcsetpgrp () +makes the process group with process group ID +.I pgrp +the foreground process group on the terminal associated to +.IR fd , +which must be the controlling terminal of the calling process, +and still be associated with its session. +Moreover, +.I pgrp +must be a (nonempty) process group belonging to +the same session as the calling process. +.PP +If +.BR tcsetpgrp () +is called by a member of a background process group in its session, +and the calling process is not blocking or ignoring +.BR SIGTTOU , +a +.B SIGTTOU +signal is sent to all members of this background process group. +.SH RETURN VALUE +When +.I fd +refers to the controlling terminal of the calling process, +the function +.BR tcgetpgrp () +will return the foreground process group ID of that terminal +if there is one, and some value larger than 1 that is not +presently a process group ID otherwise. +When +.I fd +does not refer to the controlling terminal of the calling process, +\-1 is returned, and +.I errno +is set appropriately. +.PP +When successful, +.BR tcsetpgrp () +returns 0. +Otherwise, it returns \-1, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I pgrp +has an unsupported value. +.TP +.B ENOTTY +The calling process does not have a controlling terminal, or +it has one but it is not described by +.IR fd , +or, for +.BR tcsetpgrp (), +this controlling terminal is no longer associated with the session +of the calling process. +.TP +.B EPERM +.I pgrp +has a supported value, but is not the process group ID of a +process in the same session as the calling process. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR tcgetpgrp (), +.BR tcsetpgrp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +These functions are implemented via the +.B TIOCGPGRP +and +.B TIOCSPGRP +ioctls. +.SS History +The ioctls appeared in 4.2BSD. +The functions are POSIX inventions. +.SH SEE ALSO +.BR setpgid (2), +.BR setsid (2), +.BR credentials (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tcgetsid.3 b/man3/tcgetsid.3 new file mode 100644 index 0000000..5cc2d36 --- /dev/null +++ b/man3/tcgetsid.3 @@ -0,0 +1,95 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TCGETSID 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +tcgetsid \- get session ID +.SH SYNOPSIS +.BR "#define _XOPEN_SOURCE 500" " /* See feature_test_macros(7) */" +.br +.B "#include " +.PP +.BI "pid_t tcgetsid(int " fd ); +.SH DESCRIPTION +The function +.BR tcgetsid () +returns the session ID of the current session that has the +terminal associated to +.I fd +as controlling terminal. +This terminal must be the controlling terminal of the calling process. +.SH RETURN VALUE +When +.I fd +refers to the controlling terminal of our session, +the function +.BR tcgetsid () +will return the session ID of this session. +Otherwise, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOTTY +The calling process does not have a controlling terminal, or +it has one but it is not described by +.IR fd . +.SH VERSIONS +.BR tcgetsid () +is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR tcgetsid () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +This function is implemented via the +.B TIOCGSID +.BR ioctl (2), +present +since Linux 2.1.71. +.SH SEE ALSO +.BR getsid (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tcsendbreak.3 b/man3/tcsendbreak.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/tcsendbreak.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcsetattr.3 b/man3/tcsetattr.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man3/tcsetattr.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man3/tcsetpgrp.3 b/man3/tcsetpgrp.3 new file mode 100644 index 0000000..1a8b360 --- /dev/null +++ b/man3/tcsetpgrp.3 @@ -0,0 +1 @@ +.so man3/tcgetpgrp.3 diff --git a/man3/tdelete.3 b/man3/tdelete.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man3/tdelete.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man3/tdestroy.3 b/man3/tdestroy.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man3/tdestroy.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man3/telldir.3 b/man3/telldir.3 new file mode 100644 index 0000000..b04ff27 --- /dev/null +++ b/man3/telldir.3 @@ -0,0 +1,119 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith (faith@cs.unc.edu) +.TH TELLDIR 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +telldir \- return current location in directory stream +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "long telldir(DIR *" dirp ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR telldir (): + _XOPEN_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +The +.BR telldir () +function returns the current location associated with +the directory stream \fIdirp\fP. +.SH RETURN VALUE +On success, the +.BR telldir () +function returns the current location +in the directory stream. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR telldir () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.SH NOTES +In glibc up to version 2.1.1, the return type of +.BR telldir () +was +.IR off_t . +POSIX.1-2001 specifies +.IR long , +and this is the type used since glibc 2.1.2. +.PP +In early filesystems, the value returned by +.BR telldir () +was a simple file offset within a directory. +Modern filesystems use tree or hash structures, rather than flat tables, +to represent directories. +On such filesystems, the value returned by +.BR telldir () +(and used internally by +.BR readdir (3)) +is a "cookie" that is used by the implementation +to derive a position within a directory. +.\" https://lwn.net/Articles/544298/ +Application programs should treat this strictly as an opaque value, making +.I no +assumptions about its contents. +.SH SEE ALSO +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tempnam.3 b/man3/tempnam.3 new file mode 100644 index 0000000..62cf0f5 --- /dev/null +++ b/man3/tempnam.3 @@ -0,0 +1,196 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TEMPNAM 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +tempnam \- create a name for a temporary file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *tempnam(const char *" dir ", const char *" pfx ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR tempnam (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +.I "Never use this function." +Use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.PP +The +.BR tempnam () +function returns a pointer to a string that is a valid filename, +and such that a file with this name did not exist when +.BR tempnam () +checked. +The filename suffix of the pathname generated will start with +.I pfx +in case +.I pfx +is a non-NULL string of at most five bytes. +The directory prefix part of the pathname generated is required to +be "appropriate" (often that at least implies writable). +.PP +Attempts to find an appropriate directory go through the following +steps: +.TP 3 +a) +In case the environment variable +.B TMPDIR +exists and +contains the name of an appropriate directory, that is used. +.TP +b) +Otherwise, if the +.I dir +argument is non-NULL and appropriate, it is used. +.TP +c) +Otherwise, +.I P_tmpdir +(as defined in +.IR ) +is used when appropriate. +.TP +d) +Finally an implementation-defined directory may be used. +.PP +The string returned by +.BR tempnam () +is allocated using +.BR malloc (3) +and hence should be freed by +.BR free (3). +.SH RETURN VALUE +On success, the +.BR tempnam () +function returns a pointer to a unique temporary filename. +It returns NULL if a unique name cannot be generated, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B ENOMEM +Allocation of storage failed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR tempnam () +T} Thread safety MT-Safe env +.TE +.SH CONFORMING TO +SVr4, 4.3BSD, POSIX.1-2001. +POSIX.1-2008 marks +.BR tempnam () +as obsolete. +.SH NOTES +Although +.BR tempnam () +generates names that are difficult to guess, +it is nevertheless possible that between the time that +.BR tempnam () +returns a pathname, and the time that the program opens it, +another program might create that pathname using +.BR open (2), +or create it as a symbolic link. +This can lead to security holes. +To avoid such possibilities, use the +.BR open (2) +.B O_EXCL +flag to open the pathname. +Or better yet, use +.BR mkstemp (3) +or +.BR tmpfile (3). +.PP +SUSv2 does not mention the use of +.BR TMPDIR ; +glibc will use it only +when the program is not set-user-ID. +On SVr4, the directory used under \fBd)\fP is +.I /tmp +(and this is what glibc does). +.PP +Because it dynamically allocates memory used to return the pathname, +.BR tempnam () +is reentrant, and thus thread safe, unlike +.BR tmpnam (3). +.PP +The +.BR tempnam () +function generates a different string each time it is called, +up to +.B TMP_MAX +(defined in +.IR ) +times. +If it is called more than +.B TMP_MAX +times, +the behavior is implementation defined. +.PP +.BR tempnam () +uses at most the first five bytes from +.IR pfx . +.PP +The glibc implementation of +.BR tempnam () +fails with the error +.B EEXIST +upon failure to find a unique name. +.SH BUGS +The precise meaning of "appropriate" is undefined; +it is unspecified how accessibility of a directory is determined. +.SH SEE ALSO +.BR mkstemp (3), +.BR mktemp (3), +.BR tmpfile (3), +.BR tmpnam (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/termios.3 b/man3/termios.3 new file mode 100644 index 0000000..f54e8c6 --- /dev/null +++ b/man3/termios.3 @@ -0,0 +1,1106 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-02-25 by Jim Van Zandt +.\" Modified 1995-09-02 by Jim Van Zandt +.\" moved to man3, aeb, 950919 +.\" Modified 2001-09-22 by Michael Kerrisk +.\" Modified 2001-12-17, aeb +.\" Modified 2004-10-31, aeb +.\" 2006-12-28, mtk: +.\" Added .SS headers to give some structure to this page; and a +.\" small amount of reordering. +.\" Added a section on canonical and noncanonical mode. +.\" Enhanced the discussion of "raw" mode for cfmakeraw(). +.\" Document CMSPAR. +.\" +.TH TERMIOS 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, +cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \- +get and set terminal attributes, line control, get and set baud rate +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int tcgetattr(int " fd ", struct termios *" termios_p ); +.PP +.BI "int tcsetattr(int " fd ", int " optional_actions , +.BI " const struct termios *" termios_p ); +.PP +.BI "int tcsendbreak(int " fd ", int " duration ); +.PP +.BI "int tcdrain(int " fd ); +.PP +.BI "int tcflush(int " fd ", int " queue_selector ); +.PP +.BI "int tcflow(int " fd ", int " action ); +.PP +.BI "void cfmakeraw(struct termios *" termios_p ); +.PP +.BI "speed_t cfgetispeed(const struct termios *" termios_p ); +.PP +.BI "speed_t cfgetospeed(const struct termios *" termios_p ); +.PP +.BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed ); +.PP +.BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed ); +.PP +.BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR cfsetspeed (), +.BR cfmakeraw (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The termios functions describe a general terminal interface that is +provided to control asynchronous communications ports. +.SS The termios structure +.PP +Many of the functions described here have a \fItermios_p\fP argument +that is a pointer to a \fItermios\fP structure. +This structure contains at least the following members: +.PP +.in +4n +.EX +tcflag_t c_iflag; /* input modes */ +tcflag_t c_oflag; /* output modes */ +tcflag_t c_cflag; /* control modes */ +tcflag_t c_lflag; /* local modes */ +cc_t c_cc[NCCS]; /* special characters */ +.EE +.in +.PP +The values that may be assigned to these fields are described below. +In the case of the first four bit-mask fields, +the definitions of some of the associated flags that may be set are +exposed only if a specific feature test macro (see +.BR feature_test_macros (7)) +is defined, as noted in brackets ("[]"). +.PP +In the descriptions below, "not in POSIX" means that the +value is not specified in POSIX.1-2001, +and "XSI" means that the value is specified in POSIX.1-2001 +as part of the XSI extension. +.PP +\fIc_iflag\fP flag constants: +.TP +.B IGNBRK +Ignore BREAK condition on input. +.TP +.B BRKINT +If \fBIGNBRK\fP is set, a BREAK is ignored. +If it is not set +but \fBBRKINT\fP is set, then a BREAK causes the input and output +queues to be flushed, and if the terminal is the controlling +terminal of a foreground process group, it will cause a +\fBSIGINT\fP to be sent to this foreground process group. +When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK +reads as a null byte (\(aq\\0\(aq), except when \fBPARMRK\fP is set, +in which case it reads as the sequence \\377 \\0 \\0. +.TP +.B IGNPAR +Ignore framing errors and parity errors. +.TP +.B PARMRK +If this bit is set, input bytes with parity or framing errors are +marked when passed to the program. +This bit is meaningful only when +\fBINPCK\fP is set and \fBIGNPAR\fP is not set. +The way erroneous bytes are marked is with two preceding bytes, +\\377 and \\0. +Thus, the program actually reads three bytes for one +erroneous byte received from the terminal. +If a valid byte has the value \\377, +and \fBISTRIP\fP (see below) is not set, +the program might confuse it with the prefix that marks a +parity error. +Therefore, a valid byte \\377 is passed to the program as two +bytes, \\377 \\377, in this case. +.IP +If neither \fBIGNPAR\fP nor \fBPARMRK\fP +is set, read a character with a parity error or framing error +as \\0. +.TP +.B INPCK +Enable input parity checking. +.TP +.B ISTRIP +Strip off eighth bit. +.TP +.B INLCR +Translate NL to CR on input. +.TP +.B IGNCR +Ignore carriage return on input. +.TP +.B ICRNL +Translate carriage return to newline on input (unless \fBIGNCR\fP is set). +.TP +.B IUCLC +(not in POSIX) Map uppercase characters to lowercase on input. +.TP +.B IXON +Enable XON/XOFF flow control on output. +.TP +.B IXANY +(XSI) Typing any character will restart stopped output. +(The default is to allow just the START character to restart output.) +.TP +.B IXOFF +Enable XON/XOFF flow control on input. +.TP +.B IMAXBEL +(not in POSIX) Ring bell when input queue is full. +Linux does not implement this bit, and acts as if it is always set. +.TP +.BR IUTF8 " (since Linux 2.6.4)" +(not in POSIX) Input is UTF8; +this allows character-erase to be correctly performed in cooked mode. +.PP +.I c_oflag +flag constants: +.TP +.B OPOST +Enable implementation-defined output processing. +.TP +.B OLCUC +(not in POSIX) Map lowercase characters to uppercase on output. +.TP +.B ONLCR +(XSI) Map NL to CR-NL on output. +.TP +.B OCRNL +Map CR to NL on output. +.TP +.B ONOCR +Don't output CR at column 0. +.TP +.B ONLRET +Don't output CR. +.TP +.B OFILL +Send fill characters for a delay, rather than using a timed delay. +.TP +.B OFDEL +Fill character is ASCII DEL (0177). +If unset, fill character is ASCII NUL (\(aq\\0\(aq). +(Not implemented on Linux.) +.TP +.B NLDLY +Newline delay mask. +Values are \fBNL0\fP and \fBNL1\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B CRDLY +Carriage return delay mask. +Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B TABDLY +Horizontal tab delay mask. +Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP). +A value of TAB3, that is, XTABS, expands tabs to spaces +(with tab stops every eight columns). +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B BSDLY +Backspace delay mask. +Values are \fBBS0\fP or \fBBS1\fP. +(Has never been implemented.) +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B VTDLY +Vertical tab delay mask. +Values are \fBVT0\fP or \fBVT1\fP. +.TP +.B FFDLY +Form feed delay mask. +Values are \fBFF0\fP or \fBFF1\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.PP +\fIc_cflag\fP flag constants: +.TP +.B CBAUD +(not in POSIX) Baud speed mask (4+1 bits). +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B CBAUDEX +(not in POSIX) Extra baud speed mask (1 bit), included in +.BR CBAUD . +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.IP +(POSIX says that the baud speed is stored in the +.I termios +structure without specifying where precisely, and provides +.BR cfgetispeed () +and +.BR cfsetispeed () +for getting at it. +Some systems use bits selected by +.B CBAUD +in +.IR c_cflag , +other systems use separate fields, for example, +.I sg_ispeed +and +.IR sg_ospeed .) +.TP +.B CSIZE +Character size mask. +Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP. +.TP +.B CSTOPB +Set two stop bits, rather than one. +.TP +.B CREAD +Enable receiver. +.TP +.B PARENB +Enable parity generation on output and parity checking for input. +.TP +.B PARODD +If set, then parity for input and output is odd; +otherwise even parity is used. +.TP +.B HUPCL +Lower modem control lines after last process closes the device (hang up). +.TP +.B CLOCAL +Ignore modem control lines. +.TP +.B LOBLK +(not in POSIX) Block output from a noncurrent shell layer. +For use by \fBshl\fP (shell layers). (Not implemented on Linux.) +.TP +.B CIBAUD +(not in POSIX) Mask for input speeds. +The values for the +.B CIBAUD +bits are +the same as the values for the +.B CBAUD +bits, shifted left +.B IBSHIFT +bits. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +(Not implemented on Linux.) +.TP +.B CMSPAR +(not in POSIX) +Use "stick" (mark/space) parity (supported on certain serial +devices): if +.B PARODD +is set, the parity bit is always 1; if +.B PARODD +is not set, then the parity bit is always 0. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B CRTSCTS +(not in POSIX) Enable RTS/CTS (hardware) flow control. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.PP +\fIc_lflag\fP flag constants: +.TP +.B ISIG +When any of the characters INTR, QUIT, SUSP, or DSUSP are received, +generate the corresponding signal. +.TP +.B ICANON +Enable canonical mode (described below). +.TP +.B XCASE +(not in POSIX; not supported under Linux) +If \fBICANON\fP is also set, terminal is uppercase only. +Input is converted to lowercase, except for characters preceded by \\. +On output, uppercase characters are preceded by \\ and lowercase +characters are converted to uppercase. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.\" glibc is probably now wrong to allow +.\" Define +.\" .B _XOPEN_SOURCE +.\" to expose +.\" .BR XCASE . +.TP +.B ECHO +Echo input characters. +.TP +.B ECHOE +If \fBICANON\fP is also set, the ERASE character erases the preceding +input character, and WERASE erases the preceding word. +.TP +.B ECHOK +If \fBICANON\fP is also set, the KILL character erases the current line. +.TP +.B ECHONL +If \fBICANON\fP is also set, echo the NL character even if ECHO is not set. +.TP +.B ECHOCTL +(not in POSIX) If \fBECHO\fP is also set, +terminal special characters other than +TAB, NL, START, and STOP are echoed as \fB^X\fP, +where X is the character with +ASCII code 0x40 greater than the special character. +For example, character +0x08 (BS) is echoed as \fB^H\fP. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B ECHOPRT +(not in POSIX) If \fBICANON\fP and \fBECHO\fP are also set, characters +are printed as they are being erased. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B ECHOKE +(not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing +each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B DEFECHO +(not in POSIX) Echo only when a process is reading. +(Not implemented on Linux.) +.TP +.B FLUSHO +(not in POSIX; not supported under Linux) +Output is being flushed. +This flag is toggled by typing +the DISCARD character. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B NOFLSH +Disable flushing the input and output queues when generating signals for the +INT, QUIT, and SUSP characters. +.\" Stevens lets SUSP only flush the input queue +.TP +.B TOSTOP +Send the +.B SIGTTOU +signal to the process group of a background process +which tries to write to its controlling terminal. +.TP +.B PENDIN +(not in POSIX; not supported under Linux) +All characters in the input queue are reprinted when +the next character is read. +.RB ( bash (1) +handles typeahead this way.) +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B IEXTEN +Enable implementation-defined input processing. +This flag, as well as \fBICANON\fP must be enabled for the +special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted, +and for the \fBIUCLC\fP flag to be effective. +.PP +The \fIc_cc\fP array defines the terminal special characters. +The symbolic indices (initial values) and meaning are: +.TP +.B VDISCARD +(not in POSIX; not supported under Linux; 017, SI, Ctrl-O) +Toggle: start/stop discarding pending output. +Recognized when +.B IEXTEN +is set, and then not passed as input. +.TP +.B VDSUSP +(not in POSIX; not supported under Linux; 031, EM, Ctrl-Y) +Delayed suspend character (DSUSP): +send +.B SIGTSTP +signal when the character is read by the user program. +Recognized when +.B IEXTEN +and +.B ISIG +are set, and the system supports +job control, and then not passed as input. +.TP +.B VEOF +(004, EOT, Ctrl-D) +End-of-file character (EOF). +More precisely: this character causes the pending tty buffer to be sent +to the waiting user program without waiting for end-of-line. +If it is the first character of the line, the +.BR read (2) +in the user program returns 0, which signifies end-of-file. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VEOL +(0, NUL) +Additional end-of-line character (EOL). +Recognized when +.B ICANON +is set. +.TP +.B VEOL2 +(not in POSIX; 0, NUL) +Yet another end-of-line character (EOL2). +Recognized when +.B ICANON +is set. +.TP +.B VERASE +(0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) +Erase character (ERASE). +This erases the previous not-yet-erased character, +but does not erase past EOF or beginning-of-line. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VINTR +(003, ETX, Ctrl-C, or also 0177, DEL, rubout) +Interrupt character (INTR). +Send a +.B SIGINT +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VKILL +(025, NAK, Ctrl-U, or Ctrl-X, or also @) +Kill character (KILL). +This erases the input since the last EOF or beginning-of-line. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VLNEXT +(not in POSIX; 026, SYN, Ctrl-V) +Literal next (LNEXT). +Quotes the next input character, depriving it of +a possible special meaning. +Recognized when +.B IEXTEN +is set, and then not passed as input. +.TP +.B VMIN +Minimum number of characters for noncanonical read (MIN). +.TP +.B VQUIT +(034, FS, Ctrl-\e) +Quit character (QUIT). +Send +.B SIGQUIT +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VREPRINT +(not in POSIX; 022, DC2, Ctrl-R) +Reprint unread characters (REPRINT). +Recognized when +.B ICANON +and +.B IEXTEN +are set, and then not passed as input. +.TP +.B VSTART +(021, DC1, Ctrl-Q) +Start character (START). +Restarts output stopped by the Stop character. +Recognized when +.B IXON +is set, and then not passed as input. +.TP +.B VSTATUS +(not in POSIX; not supported under Linux; +status request: 024, DC4, Ctrl-T). +Status character (STATUS). +Display status information at terminal, +including state of foreground process and amount of CPU time it has consumed. +Also sends a +.BR SIGINFO +signal (not supported on Linux) to the foreground process group. +.TP +.B VSTOP +(023, DC3, Ctrl-S) +Stop character (STOP). +Stop output until Start character typed. +Recognized when +.B IXON +is set, and then not passed as input. +.TP +.B VSUSP +(032, SUB, Ctrl-Z) +Suspend character (SUSP). +Send +.B SIGTSTP +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VSWTCH +(not in POSIX; not supported under Linux; 0, NUL) +Switch character (SWTCH). +Used in System V to switch shells in +.IR "shell layers" , +a predecessor to shell job control. +.TP +.B VTIME +Timeout in deciseconds for noncanonical read (TIME). +.TP +.B VWERASE +(not in POSIX; 027, ETB, Ctrl-W) +Word erase (WERASE). +Recognized when +.B ICANON +and +.B IEXTEN +are set, and then not passed as input. +.PP +An individual terminal special character can be disabled by setting +the value of the corresponding +.I c_cc +element to +.BR _POSIX_VDISABLE . +.PP +The above symbolic subscript values are all different, except that +.BR VTIME , +.B VMIN +may have the same value as +.BR VEOL , +.BR VEOF , +respectively. +In noncanonical mode the special character meaning is replaced +by the timeout meaning. +For an explanation of +.B VMIN +and +.BR VTIME , +see the description of +noncanonical mode below. +.SS Retrieving and changing terminal settings +.PP +.BR tcgetattr () +gets the parameters associated with the object referred by \fIfd\fP and +stores them in the \fItermios\fP structure referenced by +\fItermios_p\fP. +This function may be invoked from a background process; +however, the terminal attributes may be subsequently changed by a +foreground process. +.PP +.BR tcsetattr () +sets the parameters associated with the terminal (unless support is +required from the underlying hardware that is not available) from the +\fItermios\fP structure referred to by \fItermios_p\fP. +\fIoptional_actions\fP specifies when the changes take effect: +.IP \fBTCSANOW\fP +the change occurs immediately. +.IP \fBTCSADRAIN\fP +the change occurs after all output written to +.I fd +has been transmitted. +This option should be used when changing +parameters that affect output. +.IP \fBTCSAFLUSH\fP +the change occurs after all output written to the object referred by +.I fd +has been transmitted, and all input that has been received but not read +will be discarded before the change is made. +.SS Canonical and noncanonical mode +The setting of the +.B ICANON +canon flag in +.I c_lflag +determines whether the terminal is operating in canonical mode +.RB ( ICANON +set) or +noncanonical mode +.RB ( ICANON +unset). +By default, +.B ICANON +is set. +.PP +In canonical mode: +.IP * 2 +Input is made available line by line. +An input line is available when one of the line delimiters +is typed (NL, EOL, EOL2; or EOF at the start of line). +Except in the case of EOF, the line delimiter is included +in the buffer returned by +.BR read (2). +.IP * 2 +Line editing is enabled (ERASE, KILL; +and if the +.B IEXTEN +flag is set: WERASE, REPRINT, LNEXT). +A +.BR read (2) +returns at most one line of input; if the +.BR read (2) +requested fewer bytes than are available in the current line of input, +then only as many bytes as requested are read, +and the remaining characters will be available for a future +.BR read (2). +.IP * 2 +The maximum line length is 4096 chars +(including the terminating newline character); +lines longer than 4096 chars are truncated. +After 4095 characters, input processing (e.g., +.B ISIG +and +.B ECHO* +processing) continues, but any input data after 4095 characters up to +(but not including) any terminating newline is discarded. +This ensures that the terminal can always receive +more input until at least one line can be read. +.PP +In noncanonical mode input is available immediately (without +the user having to type a line-delimiter character), +no input processing is performed, +and line editing is disabled. +The read buffer will only accept 4095 chars; this provides the +necessary space for a newline char if the input mode is switched +to canonical. +The settings of MIN +.RI ( c_cc[VMIN] ) +and TIME +.RI ( c_cc[VTIME] ) +determine the circumstances in which a +.BR read (2) +completes; there are four distinct cases: +.TP +MIN == 0, TIME == 0 (polling read) +If data is available, +.BR read (2) +returns immediately, with the lesser of the number of bytes +available, or the number of bytes requested. +If no data is available, +.BR read (2) +returns 0. +.TP +MIN > 0, TIME == 0 (blocking read) +.BR read (2) +blocks until MIN bytes are available, +and returns up to the number of bytes requested. +.TP +MIN == 0, TIME > 0 (read with timeout) +TIME specifies the limit for a timer in tenths of a second. +The timer is started when +.BR read (2) +is called. +.BR read (2) +returns either when at least one byte of data is available, +or when the timer expires. +If the timer expires without any input becoming available, +.BR read (2) +returns 0. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.TP +MIN > 0, TIME > 0 (read with interbyte timeout) +TIME specifies the limit for a timer in tenths of a second. +Once an initial byte of input becomes available, +the timer is restarted after each further byte is received. +.BR read (2) +returns when any of the following conditions is met: +.RS +.IP * 3 +MIN bytes have been received. +.IP * +The interbyte timer expires. +.IP * +The number of bytes requested by +.BR read (2) +has been received. +(POSIX does not specify this termination condition, +and on some other implementations +.\" e.g., Solaris +.BR read (2) +does not return in this case.) +.RE +.IP +Because the timer is started only after the initial byte +becomes available, at least one byte will be read. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.PP +POSIX +.\" POSIX.1-2008 XBD 11.1.7 +does not specify whether the setting of the +.B O_NONBLOCK +file status flag takes precedence over the MIN and TIME settings. +If +.B O_NONBLOCK +is set, a +.BR read (2) +in noncanonical mode may return immediately, +regardless of the setting of MIN or TIME. +Furthermore, if no data is available, +POSIX permits a +.BR read (2) +in noncanonical mode to return either 0, or \-1 with +.I errno +set to +.BR EAGAIN . +.SS Raw mode +.PP +.BR cfmakeraw () +sets the terminal to something like the +"raw" mode of the old Version 7 terminal driver: +input is available character by character, +echoing is disabled, and all special processing of +terminal input and output characters is disabled. +The terminal attributes are set as follows: +.PP +.in +4n +.EX +termios_p\->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP + | INLCR | IGNCR | ICRNL | IXON); +termios_p\->c_oflag &= ~OPOST; +termios_p\->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN); +termios_p\->c_cflag &= ~(CSIZE | PARENB); +termios_p\->c_cflag |= CS8; +.EE +.in +.\" +.SS Line control +.PP +.BR tcsendbreak () +transmits a continuous stream of zero-valued bits for a specific +duration, if the terminal is using asynchronous serial data +transmission. +If \fIduration\fP is zero, it transmits zero-valued bits +for at least 0.25 seconds, and not more that 0.5 seconds. +If \fIduration\fP is not zero, it sends zero-valued bits for some +implementation-defined length of time. +.PP +If the terminal is not using asynchronous serial data transmission, +.BR tcsendbreak () +returns without taking any action. +.PP +.BR tcdrain () +waits until all output written to the object referred to by +.I fd +has been transmitted. +.PP +.BR tcflush () +discards data written to the object referred to by +.I fd +but not transmitted, or data received but not read, depending on the +value of +.IR queue_selector : +.IP \fBTCIFLUSH\fP +flushes data received but not read. +.IP \fBTCOFLUSH\fP +flushes data written but not transmitted. +.IP \fBTCIOFLUSH\fP +flushes both data received but not read, and data written but not +transmitted. +.PP +.BR tcflow () +suspends transmission or reception of data on the object referred to by +.IR fd , +depending on the value of +.IR action : +.IP \fBTCOOFF\fP +suspends output. +.IP \fBTCOON\fP +restarts suspended output. +.IP \fBTCIOFF\fP +transmits a STOP character, which stops the terminal device from +transmitting data to the system. +.IP \fBTCION\fP +transmits a START character, which starts the terminal device +transmitting data to the system. +.PP +The default on open of a terminal file is that neither its input nor its +output is suspended. +.SS Line speed +The baud rate functions are provided for getting and setting the values +of the input and output baud rates in the \fItermios\fP structure. +The new values do not take effect +until +.BR tcsetattr () +is successfully called. +.PP +Setting the speed to \fBB0\fP instructs the modem to "hang up". +The actual bit rate corresponding to \fBB38400\fP may be altered with +.BR setserial (8). +.PP +The input and output baud rates are stored in the \fItermios\fP +structure. +.PP +.BR cfgetospeed () +returns the output baud rate stored in the \fItermios\fP structure +pointed to by +.IR termios_p . +.PP +.BR cfsetospeed () +sets the output baud rate stored in the \fItermios\fP structure pointed +to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: +.PP +.nf +.ft B + B0 + B50 + B75 + B110 + B134 + B150 + B200 + B300 + B600 + B1200 + B1800 + B2400 + B4800 + B9600 + B19200 + B38400 + B57600 + B115200 + B230400 +.ft P +.fi +.PP +The zero baud rate, \fBB0\fP, +is used to terminate the connection. +If B0 is specified, the modem control lines shall no longer be asserted. +Normally, this will disconnect the line. +\fBCBAUDEX\fP is a mask +for the speeds beyond those defined in POSIX.1 (57600 and above). +Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero. +.PP +.BR cfgetispeed () +returns the input baud rate stored in the \fItermios\fP structure. +.PP +.BR cfsetispeed () +sets the input baud rate stored in the \fItermios\fP structure to +.IR speed , +which must be specified as one of the \fBBnnn\fP constants listed above for +.BR cfsetospeed (). +If the input baud rate is set to zero, the input baud rate will be +equal to the output baud rate. +.PP +.BR cfsetspeed () +is a 4.4BSD extension. +It takes the same arguments as +.BR cfsetispeed (), +and sets both input and output speed. +.SH RETURN VALUE +.PP +.BR cfgetispeed () +returns the input baud rate stored in the +\fItermios\fP +structure. +.PP +.BR cfgetospeed () +returns the output baud rate stored in the \fItermios\fP structure. +.PP +All other functions return: +.IP 0 +on success. +.IP \-1 +on failure and set +.I errno +to indicate the error. +.PP +Note that +.BR tcsetattr () +returns success if \fIany\fP of the requested changes could be +successfully carried out. +Therefore, when making multiple changes +it may be necessary to follow this call with a further call to +.BR tcgetattr () +to check that all changes have been performed successfully. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.nh +.ad l +.TS +allbox; +lbw36 lb lb +l l l. +Interface Attribute Value +T{ +.BR tcgetattr (), +.BR tcsetattr (), +.BR tcdrain (), +.BR tcflush (), +.BR tcflow (), +.BR tcsendbreak (), +.BR cfmakeraw (), +.BR cfgetispeed (), +.BR cfgetospeed (), +.BR cfsetispeed (), +.BR cfsetospeed (), +.BR cfsetspeed () +T} Thread safety MT-Safe +.TE +.\" FIXME: The markings are different from that in the glibc manual. +.\" markings in glibc manual are more detailed: +.\" +.\" tcsendbreak: MT-Unsafe race:tcattr(filedes)/bsd +.\" tcflow: MT-Unsafe race:tcattr(filedes)/bsd +.\" +.\" glibc manual says /bsd indicate the preceding marker only applies +.\" when the underlying kernel is a BSD kernel. +.\" So, it is safety in Linux kernel. +.ad +.hy +.SH CONFORMING TO +.BR tcgetattr (), +.BR tcsetattr (), +.BR tcsendbreak (), +.BR tcdrain (), +.BR tcflush (), +.BR tcflow (), +.BR cfgetispeed (), +.BR cfgetospeed (), +.BR cfsetispeed (), +and +.BR cfsetospeed () +are specified in POSIX.1-2001. +.PP +.BR cfmakeraw () +and +.BR cfsetspeed () +are nonstandard, but available on the BSDs. +.SH NOTES +UNIX\ V7 and several later systems have a list of baud rates +where after the fourteen values B0, ..., B9600 one finds the +two constants EXTA, EXTB ("External A" and "External B"). +Many systems extend the list with much higher baud rates. +.PP +The effect of a nonzero \fIduration\fP with +.BR tcsendbreak () +varies. +SunOS specifies a break of +.I "duration\ *\ N" +seconds, where \fIN\fP is at least 0.25, and not more than 0.5. +Linux, AIX, DU, Tru64 send a break of +.I duration +milliseconds. +FreeBSD and NetBSD and HP-UX and MacOS ignore the value of +.IR duration . +Under Solaris and UnixWare, +.BR tcsendbreak () +with nonzero +.I duration +behaves like +.BR tcdrain (). +.\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0. +.\" libc4.7.6, libc5, glibc for unix: duration in ms. +.\" glibc for bsd: duration in us +.\" glibc for sunos4: ignore duration +.SH SEE ALSO +.BR reset (1), +.BR setterm (1), +.BR stty (1), +.BR tput (1), +.BR tset (1), +.BR tty (1), +.BR ioctl_console (2), +.BR ioctl_tty (2), +.BR setserial (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tfind.3 b/man3/tfind.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man3/tfind.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man3/tgamma.3 b/man3/tgamma.3 new file mode 100644 index 0000000..40776c6 --- /dev/null +++ b/man3/tgamma.3 @@ -0,0 +1,226 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" Based on glibc infopages +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" Modified 2004-11-15, fixed error noted by Fabian Kreutz +.\" +.\" +.TH TGAMMA 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +tgamma, tgammaf, tgammal \- true gamma function +.SH SYNOPSIS +.B #include +.PP +.BI "double tgamma(double " x ); +.br +.BI "float tgammaf(float " x ); +.br +.BI "long double tgammal(long double " x ); +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR tgamma (), +.BR tgammaf (), +.BR tgammal (): +.RS 4 +_ISOC99_SOURCE || +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions calculate the Gamma function of +.IR x . +.PP +The Gamma function is defined by +.PP +.RS +Gamma(x) = integral from 0 to infinity of t^(x\-1) e^\-t dt +.RE +.PP +It is defined for every real number except for nonpositive integers. +For nonnegative integral +.I m +one has +.PP +.RS +Gamma(m+1) = m! +.RE +.PP +and, more generally, for all +.IR x : +.PP +.RS +Gamma(x+1) = x * Gamma(x) +.RE +.PP +Furthermore, the following is valid for all values of +.I x +outside the poles: +.PP +.RS +Gamma(x) * Gamma(1 \- x) = PI / sin(PI * x) +.RE +.SH RETURN VALUE +On success, these functions return Gamma(x). +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is positive infinity, positive infinity is returned. +.PP +If +.I x +is a negative integer, or is negative infinity, +a domain error occurs, +and a NaN is returned. +.PP +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.PP +If the result underflows, +a range error occurs, +and the functions return 0, with the correct mathematical sign. +.PP +If +.I x +is \-0 or +0, +a pole error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the same sign as the 0. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is a negative integer, or negative infinity +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised (but see BUGS). +.TP +Pole error: \fIx\fP is +0 or \-0 +.I errno +is set to +.BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.PP +glibc also gives the following error which is not specified +in C99 or POSIX.1-2001. +.TP +Range error: result underflow +.\" e.g., tgamma(-172.5) on glibc 2.8/x86-32 +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised, and +.I errno +is set to +.BR ERANGE . +.\" glibc (as at 2.8) also supports an inexact +.\" exception for various cases. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw30 lb lb +l l l. +Interface Attribute Value +T{ +.BR tgamma (), +.BR tgammaf (), +.BR tgammal () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +This function had to be called "true gamma function" +since there is already a function +.BR gamma (3) +that returns something else (see +.BR gamma (3) +for details). +.SH BUGS +Before version 2.18, the glibc implementation of these functions did not set +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6809 +.I errno +to +.B EDOM +when +.I x +is negative infinity. +.PP +Before glibc 2.19, +.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6810 +the glibc implementation of these functions did not set +.I errno +to +.B ERANGE +on an underflow range error. +.I x +.PP +.\" +In glibc versions 2.3.3 and earlier, +an argument of +0 or \-0 incorrectly produced a domain error +.RI ( errno +set to +.B EDOM +and an +.B FE_INVALID +exception raised), rather than a pole error. +.SH SEE ALSO +.BR gamma (3), +.BR lgamma (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tgammaf.3 b/man3/tgammaf.3 new file mode 100644 index 0000000..4a0248a --- /dev/null +++ b/man3/tgammaf.3 @@ -0,0 +1 @@ +.so man3/tgamma.3 diff --git a/man3/tgammal.3 b/man3/tgammal.3 new file mode 100644 index 0000000..4a0248a --- /dev/null +++ b/man3/tgammal.3 @@ -0,0 +1 @@ +.so man3/tgamma.3 diff --git a/man3/timegm.3 b/man3/timegm.3 new file mode 100644 index 0000000..865b2ef --- /dev/null +++ b/man3/timegm.3 @@ -0,0 +1,114 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TIMEGM 3 2016-12-12 "GNU" "Linux Programmer's Manual" +.SH NAME +timegm, timelocal \- inverses of gmtime and localtime +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "time_t timelocal(struct tm *" tm ); +.PP +.BI "time_t timegm(struct tm *" tm ); +.PP +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR timelocal (), +.BR timegm (): + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.SH DESCRIPTION +The functions +.BR timelocal () +and +.BR timegm () +are the inverses of +.BR localtime (3) +and +.BR gmtime (3). +Both functions take a broken-down time and convert it to calendar time +(seconds since the Epoch, 1970-01-01 00:00:00 +0000, UTC). +The difference between the two functions is that +.BR timelocal () +takes the local timezone into account when doing the conversion, while +.BR timegm () +takes the input value to be Coordinated Universal Time (UTC). +.SH RETURN VALUE +On success, +these functions return the calendar time (seconds since the Epoch), +expressed as a value of type +.IR time_t . +On error, they return the value +.IR "(time_t)\ -1" +and set +.I errno +to indicate the cause of the error. +.SH ERRORS +.TP +.B EOVERFLOW +The result cannot be represented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw21 lb lb +l l l. +Interface Attribute Value +T{ +.BR timelocal (), +.BR timegm () +T} Thread safety MT-Safe env locale +.TE +.SH CONFORMING TO +These functions are nonstandard GNU extensions +that are also present on the BSDs. +Avoid their use. +.SH NOTES +The +.BR timelocal () +function is equivalent to the POSIX standard function +.BR mktime (3). +There is no reason to ever use it. +.SH SEE ALSO +.BR gmtime (3), +.BR localtime (3), +.BR mktime (3), +.BR tzset (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/timelocal.3 b/man3/timelocal.3 new file mode 100644 index 0000000..45d4c09 --- /dev/null +++ b/man3/timelocal.3 @@ -0,0 +1 @@ +.so man3/timegm.3 diff --git a/man3/timeradd.3 b/man3/timeradd.3 new file mode 100644 index 0000000..45680c1 --- /dev/null +++ b/man3/timeradd.3 @@ -0,0 +1,164 @@ +.\" Copyright (c) 2007 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-07-31, mtk, Created +.\" +.TH TIMERADD 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +timeradd, timersub, timercmp, timerclear, timerisset \- timeval operations +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void timeradd(struct timeval *" a ", struct timeval *" b , +.BI " struct timeval *" res ); +.PP +.BI "void timersub(struct timeval *" a ", struct timeval *" b , +.BI " struct timeval *" res ); +.PP +.BI "void timerclear(struct timeval *" tvp ); +.PP +.BI "int timerisset(struct timeval *" tvp ); +.PP +.BI "int timercmp(struct timeval *" a ", struct timeval *" b ", " CMP ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +All functions shown above: + Since glibc 2.19: + _DEFAULT_SOURCE + Glibc 2.19 and earlier: + _BSD_SOURCE +.SH DESCRIPTION +The macros are provided to operate on +.I timeval +structures, defined in +.I +as: +.PP +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.PP +.BR timeradd () +adds the time values in +.I a +and +.IR b , +and places the sum in the +.I timeval +pointed to by +.IR res . +The result is normalized such that +.I res\->tv_usec +has a value in the range 0 to 999,999. +.PP +.BR timersub () +subtracts the time value in +.I b +from the time value in +.IR a , +and places the result in the +.I timeval +pointed to by +.IR res . +The result is normalized such that +.I res\->tv_usec +has a value in the range 0 to 999,999. +.PP +.BR timerclear () +zeros out the +.I timeval +structure pointed to by +.IR tvp , +so that it represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC). +.PP +.BR timerisset () +returns true (nonzero) if either field of the +.I timeval +structure pointed to by +.I tvp +contains a nonzero value. +.PP +.BR timercmp () +compares the timer values in +.I a +and +.I b +using the comparison operator +.IR CMP , +and returns true (nonzero) or false (0) depending on +the result of the comparison. +Some systems (but not Linux/glibc), +have a broken +.BR timercmp () +implementation, +.\" HP-UX, Tru64, Irix have a definition like: +.\"#define timercmp(tvp, uvp, cmp) \ +.\" ((tvp)->tv_sec cmp (uvp)->tv_sec || \ +.\" (tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec) +in which +.I CMP +of +.IR >= , +.IR <= , +and +.I == +do not work; +portable applications can instead use +.PP + !timercmp(..., <) + !timercmp(..., >) + !timercmp(..., !=) +.SH RETURN VALUE +.BR timerisset () +and +.BR timercmp () +return true (nonzero) or false (0). +.SH ERRORS +No errors are defined. +.SH CONFORMING TO +Not in POSIX.1. +Present on most BSD derivatives. +.SH SEE ALSO +.BR gettimeofday (2), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/timerclear.3 b/man3/timerclear.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man3/timerclear.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man3/timercmp.3 b/man3/timercmp.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man3/timercmp.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man3/timerisset.3 b/man3/timerisset.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man3/timerisset.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man3/timersub.3 b/man3/timersub.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man3/timersub.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man3/timezone.3 b/man3/timezone.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man3/timezone.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man3/tmpfile.3 b/man3/tmpfile.3 new file mode 100644 index 0000000..f573ef1 --- /dev/null +++ b/man3/tmpfile.3 @@ -0,0 +1,124 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:46:57 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-11-17, aeb +.TH TMPFILE 3 2016-03-15 "" "Linux Programmer's Manual" +.SH NAME +tmpfile \- create a temporary file +.SH SYNOPSIS +.nf +.B #include +.PP +.B FILE *tmpfile(void); +.fi +.SH DESCRIPTION +The +.BR tmpfile () +function opens a unique temporary file +in binary read/write (w+b) mode. +The file will be automatically deleted when it is closed or the +program terminates. +.SH RETURN VALUE +The +.BR tmpfile () +function returns a stream descriptor, or NULL if +a unique filename cannot be generated or the unique file cannot be +opened. +In the latter case, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission denied for directory in file's path prefix. +.TP +.B EEXIST +Unable to generate a unique filename. +.TP +.B EINTR +The call was interrupted by a signal; see +.BR signal (7). +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOSPC +There was no room in the directory to add the new filename. +.TP +.B EROFS +Read-only filesystem. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR tmpfile () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD, SUSv2. +.SH NOTES +POSIX.1-2001 specifies: +an error message may be written to +.I stdout +if the stream +cannot be opened. +.PP +The standard does not specify the directory that +.BR tmpfile () +will use. +Glibc will try the path prefix +.I P_tmpdir +defined +in +.IR , +and if that fails the directory +.IR /tmp . +.SH SEE ALSO +.BR exit (3), +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpnam (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tmpnam.3 b/man3/tmpnam.3 new file mode 100644 index 0000000..7613ce0 --- /dev/null +++ b/man3/tmpnam.3 @@ -0,0 +1,191 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2003-11-15, aeb, added tmpnam_r +.\" +.TH TMPNAM 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +tmpnam, tmpnam_r \- create a name for a temporary file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *tmpnam(char *" s ); +.BI "char *tmpnam_r(char *" s ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR tmpnam_r () +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.19: +_DEFAULT_SOURCE +.TP +Up to and including glibc 2.19: +_BSD_SOURCE || _SVID_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +.B Note: +avoid using these functions; use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.PP +The +.BR tmpnam () +function returns a pointer to a string that is a valid filename, +and such that a file with this name did not exist at some point +in time, so that naive programmers may think it +a suitable name for a temporary file. +If the argument +.I s +is NULL, this name is generated in an internal static buffer +and may be overwritten by the next call to +.BR tmpnam (). +If +.I s +is not NULL, the name is copied to the character array (of length +at least +.IR L_tmpnam ) +pointed to by +.I s +and the value +.I s +is returned in case of success. +.PP +The created pathname has a directory prefix +.IR P_tmpdir . +(Both +.I L_tmpnam +and +.I P_tmpdir +are defined in +.IR , +just like the +.B TMP_MAX +mentioned below.) +.PP +The +.BR tmpnam_r () +function performs the same task as +.BR tmpnam (), +but returns NULL (to indicate an error) if +.I s +is NULL. +.SH RETURN VALUE +These functions return a pointer to a unique temporary +filename, or NULL if a unique name cannot be generated. +.SH ERRORS +No errors are defined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR tmpnam () +T} Thread safety MT-Unsafe race:tmpnam/!s +T{ +.BR tmpnam_r () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR tmpnam (): +SVr4, 4.3BSD, C89, C99, POSIX.1-2001. +POSIX.1-2008 marks +.BR tmpnam () +as obsolete. +.PP +.BR tmpnam_r () +is a nonstandard extension that is also available +.\" Appears to be on Solaris +on a few other systems. +.SH NOTES +The +.BR tmpnam () +function generates a different string each time it is called, +up to +.B TMP_MAX +times. +If it is called more than +.B TMP_MAX +times, +the behavior is implementation defined. +.PP +Although these functions generate names that are difficult to guess, +it is nevertheless possible that between the time that +the pathname is returned and the time that the program opens it, +another program might create that pathname using +.BR open (2), +or create it as a symbolic link. +This can lead to security holes. +To avoid such possibilities, use the +.BR open (2) +.B O_EXCL +flag to open the pathname. +Or better yet, use +.BR mkstemp (3) +or +.BR tmpfile (3). +.PP +Portable applications that use threads cannot call +.BR tmpnam () +with a NULL argument if either +.B _POSIX_THREADS +or +.B _POSIX_THREAD_SAFE_FUNCTIONS +is defined. +.SH BUGS +Never use these functions. +Use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.SH SEE ALSO +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tmpnam_r.3 b/man3/tmpnam_r.3 new file mode 100644 index 0000000..c1bd6dc --- /dev/null +++ b/man3/tmpnam_r.3 @@ -0,0 +1 @@ +.so man3/tmpnam.3 diff --git a/man3/toascii.3 b/man3/toascii.3 new file mode 100644 index 0000000..bba24bf --- /dev/null +++ b/man3/toascii.3 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1995 by Jim Van Zandt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Added BUGS section, aeb, 950919 +.\" +.TH TOASCII 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +toascii \- convert character to ASCII +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int toascii(int " "c" ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR toascii (): +_XOPEN_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.SH DESCRIPTION +.BR toascii () +converts +.I c +to a 7-bit +.I "unsigned char" +value that fits into the ASCII character set, by clearing the +high-order bits. +.SH RETURN VALUE +The value returned is that of the converted character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR toascii () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +SVr4, BSD, POSIX.1-2001. +POSIX.1-2008 marks +.BR toascii () +as obsolete, +noting that it cannot be used portably in a localized application. +.SH BUGS +Many people will be unhappy if you use this function. +This function will convert accented letters into random characters. +.SH SEE ALSO +.BR isascii (3), +.BR tolower (3), +.BR toupper (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/tolower.3 b/man3/tolower.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man3/tolower.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man3/tolower_l.3 b/man3/tolower_l.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man3/tolower_l.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man3/toupper.3 b/man3/toupper.3 new file mode 100644 index 0000000..67f6771 --- /dev/null +++ b/man3/toupper.3 @@ -0,0 +1,199 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2000-02-13 by Nicolás Lichtmaier +.TH TOUPPER 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int toupper(int " "c" ); +.BI "int tolower(int " "c" ); +.PP +.BI "int toupper_l(int " c ", locale_t " locale ); +.BI "int tolower_l(int " c ", locale_t " locale ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR toupper_l (), +.BR tolower_l (): +.PD 0 +.RS 4 +.TP +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.SH DESCRIPTION +These functions convert lowercase letters to uppercase, and vice versa. +.PP +If +.I c +is a lowercase letter, +.BR toupper () +returns its uppercase equivalent, +if an uppercase representation exists in the current locale. +Otherwise, it returns +.IR c . +The +.BR toupper_l () +function performs the same task, +but uses the locale referred to by the locale handle +.IR locale . +.PP +If +.I c +is an uppercase letter, +.BR tolower () +returns its lowercase equivalent, +if a lowercase representation exists in the current locale. +Otherwise, it returns +.IR c . +The +.BR tolower_l () +function performs the same task, +but uses the locale referred to by the locale handle +.IR locale . +.PP +If +.I c +is neither an +.I "unsigned char" +value nor +.BR EOF , +the behavior of these functions +is undefined. +.PP +The behavior of +.BR toupper_l () +and +.BR tolower_l () +is undefined if +.I locale +is the special locale object +.BR LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.SH RETURN VALUE +The value returned is that of the converted letter, or +.I c +if the conversion was not possible. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR toupper (), +.BR tolower (), +.br +.BR toupper_l (), +.BR tolower_l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR toupper (), +.BR tolower (): +C89, C99, 4.3BSD, POSIX.1-2001, POSIX.1-2008. +.PP +.BR toupper_l (), +.BR tolower_l (): +POSIX.1-2008. +.SH NOTES +The standards require that the argument +.I c +for these functions is either +.B EOF +or a value that is representable in the type +.IR "unsigned char" . +If the argument +.I c +is of type +.IR char , +it must be cast to +.IR "unsigned char" , +as in the following example: +.PP +.in +4n +.EX +char c; +\&... +res = toupper((unsigned char) c); +.EE +.in +.PP +This is necessary because +.I char +may be the equivalent +.IR "signed char" , +in which case a byte where the top bit is set would be sign extended when +converting to +.IR int , +yielding a value that is outside the range of +.IR "unsigned char" . +.PP +The details of what constitutes an uppercase or lowercase letter depend +on the locale. +For example, the default +.B """C""" +locale does not know about umlauts, so no conversion is done for them. +.PP +In some non-English locales, there are lowercase letters with no +corresponding uppercase equivalent; +.\" FIXME One day the statement about "sharp s" needs to be reworked, +.\" since there is nowadays a capital "sharp s" that has a codepoint +.\" in Unicode 5.0; see https://en.wikipedia.org/wiki/Capital_%E1%BA%9E +the German sharp s is one example. +.SH SEE ALSO +.BR isalpha (3), +.BR newlocale (3), +.BR setlocale (3), +.BR towlower (3), +.BR towupper (3), +.BR uselocale (3), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/toupper_l.3 b/man3/toupper_l.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man3/toupper_l.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man3/towctrans.3 b/man3/towctrans.3 new file mode 100644 index 0000000..8a3b2bf --- /dev/null +++ b/man3/towctrans.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH TOWCTRANS 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +towctrans \- wide-character transliteration +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc ); +.fi +.SH DESCRIPTION +If +.I wc +is a wide character, the +.BR towctrans () +function +translates it according to the transliteration descriptor +.IR desc . +If +.IR wc +is +.BR WEOF , +.B WEOF +is returned. +.PP +.I desc +must be a transliteration descriptor returned by +the +.BR wctrans (3) +function. +.SH RETURN VALUE +The +.BR towctrans () +function returns the translated wide character, +or +.BR WEOF +if +.I wc +is +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR towctrans () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR towctrans () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR towlower (3), +.BR towupper (3), +.BR wctrans (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/towlower.3 b/man3/towlower.3 new file mode 100644 index 0000000..03b2c77 --- /dev/null +++ b/man3/towlower.3 @@ -0,0 +1,137 @@ +.\" Copyright (c) Bruno Haible +.\" and Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH TOWLOWER 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +towlower, towlower_l \- convert a wide character to lowercase +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wint_t towlower(wint_t " wc ); +.PP +.BI "wint_t towlower_l(wint_t " wc ", locale_t " locale ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR towlower_l (): +.PD 0 +.RS 4 +.TP +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.SH DESCRIPTION +The +.BR towlower () +function is the wide-character equivalent of the +.BR tolower (3) +function. +If +.I wc +is an uppercase wide character, +and there exists a lowercase equivalent in the current locale, +it returns the lowercase equivalent of +.IR wc . +In all other cases, +.I wc +is returned unchanged. +.PP +The +.BR towlower_l () +function performs the same task, +but performs the conversion based on the character type information in +the locale specified by +.IR locale . +The behavior of +.BR towlower_l () +is undefined if +.I locale +is the special locale object +.BR LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.PP +The argument +.I wc +must be representable as a +.IR wchar_t +and be a valid character in the locale or be the value +.BR WEOF . +.SH RETURN VALUE +If +.I wc +was convertible to lowercase, +.BR towlower () +returns its lowercase equivalent; +otherwise it returns +.IR wc . +.SH VERSIONS +The +.BR towlower_l () +function first appeared in glibc 2.3. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR towlower () +T} Thread safety MT-Safe locale +T{ +.BR towlower_l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR towlower (): +C99, POSIX.1-2001 (XSI); +present as an XSI extension in POSIX.1-2008, but marked obsolete. +.PP +.BR towlower_l (): +POSIX.1-2008. +.SH NOTES +The behavior of these functions depends on the +.B LC_CTYPE +category of the locale. +.PP +These functions are not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower and title case. +.SH SEE ALSO +.BR iswlower (3), +.BR towctrans (3), +.BR towupper (3), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/towlower_l.3 b/man3/towlower_l.3 new file mode 100644 index 0000000..6135f86 --- /dev/null +++ b/man3/towlower_l.3 @@ -0,0 +1 @@ +.so man3/towlower.3 diff --git a/man3/towupper.3 b/man3/towupper.3 new file mode 100644 index 0000000..5b5b732 --- /dev/null +++ b/man3/towupper.3 @@ -0,0 +1,137 @@ + +.\" and Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH TOWUPPER 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +towupper, towupper_l \- convert a wide character to uppercase +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wint_t towupper(wint_t " wc ); +.PP +.BI "wint_t towupper_l(wint_t " wc ", locale_t " locale ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR towupper_l (): +.PD 0 +.RS 4 +.TP +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.SH DESCRIPTION +The +.BR towupper () +function is the wide-character equivalent of the +.BR toupper (3) +function. +If +.I wc +is a lowercase wide character, +and there exists an uppercase equivalent in the current locale, +it returns the uppercase equivalent of +.IR wc . +In all other cases, +.I wc +is returned unchanged. +.PP +The +.BR towupper_l () +function performs the same task, +but performs the conversion based on the character type information in +the locale specified by +.IR locale . +The behavior of +.BR towupper_l () +is undefined if +.I locale +is the special locale object +.BR LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.PP +The argument +.I wc +must be representable as a +.IR wchar_t +and be a valid character in the locale or be the value +.BR WEOF . +.SH RETURN VALUE +If +.I wc +was convertible to uppercase, +.BR towupper () +returns its uppercase equivalent; +otherwise it returns +.IR wc . +.SH VERSIONS +The +.BR towupper_l () +function first appeared in glibc 2.3. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR towupper () +T} Thread safety MT-Safe locale +T{ +.BR towupper_l () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +.BR towupper (): +C99, POSIX.1-2001 (XSI); +present as an XSI extension in POSIX.1-2008, but marked obsolete. +.PP +.BR towupper_l (): +POSIX.1-2008. +.SH NOTES +The behavior of these functions depends on the +.B LC_CTYPE +category of the locale. +.PP +These functions are not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower and title case. +.SH SEE ALSO +.BR iswupper (3), +.BR towctrans (3), +.BR towlower (3), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/towupper_l.3 b/man3/towupper_l.3 new file mode 100644 index 0000000..a0b0e89 --- /dev/null +++ b/man3/towupper_l.3 @@ -0,0 +1 @@ +.so man3/towupper.3 diff --git a/man3/trunc.3 b/man3/trunc.3 new file mode 100644 index 0000000..33a1348 --- /dev/null +++ b/man3/trunc.3 @@ -0,0 +1,109 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TRUNC 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +trunc, truncf, truncl \- round to integer, toward zero +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double trunc(double " x ); +.BI "float truncf(float " x ); +.BI "long double truncl(long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR trunc (), +.BR truncf (), +.BR truncl (): +.RS 4 +_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +These functions round +.I x +to the nearest integer +not larger in absolute value. +.SH RETURN VALUE +These functions return the rounded integer value. +.PP +If +.IR x +is integral, infinite, or NaN, +.I x +itself is returned. +.SH ERRORS +No errors occur. +.SH VERSIONS +These functions first appeared in glibc in version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw27 lb lb +l l l. +Interface Attribute Value +T{ +.BR trunc (), +.BR truncf (), +.BR truncl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +C99, POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The integral value returned by these functions may be too large +to store in an integer type +.RI ( int , +.IR long , +etc.). +To avoid an overflow, which will produce undefined results, +an application should perform a range check on the returned value +before assigning it to an integer type. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/truncf.3 b/man3/truncf.3 new file mode 100644 index 0000000..b859341 --- /dev/null +++ b/man3/truncf.3 @@ -0,0 +1 @@ +.so man3/trunc.3 diff --git a/man3/truncl.3 b/man3/truncl.3 new file mode 100644 index 0000000..b859341 --- /dev/null +++ b/man3/truncl.3 @@ -0,0 +1 @@ +.so man3/trunc.3 diff --git a/man3/tsearch.3 b/man3/tsearch.3 new file mode 100644 index 0000000..a58a2f7 --- /dev/null +++ b/man3/tsearch.3 @@ -0,0 +1,322 @@ +.\" Copyright 1995 by Jim Van Zandt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TSEARCH 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +tsearch, tfind, tdelete, twalk, tdestroy \- manage a binary tree +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void *tsearch(const void *" key ", void **" rootp , +.BI " int (*" compar ")(const void *, const void *));" +.PP +.BI "void *tfind(const void *" key ", void *const *" rootp , +.BI " int (*" compar ")(const void *, const void *));" +.PP +.BI "void *tdelete(const void *" key ", void **" rootp , +.BI " int (*" compar ")(const void *, const void *));" +.PP +.BI "void twalk(const void *" root ", void (*" action ")(const void *" nodep , +.BI " const VISIT " which , +.BI " const int " depth "));" + +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "void tdestroy(void *" root ", void (*" free_node ")(void *" nodep )); +.fi +.SH DESCRIPTION +.BR tsearch (), +.BR tfind (), +.BR twalk (), +and +.BR tdelete () +manage a +binary tree. +They are generalized from Knuth (6.2.2) Algorithm T. +The first field in each node of the tree is a pointer to the +corresponding data item. +(The calling program must store the actual data.) +.IR compar +points to a comparison routine, which takes +pointers to two items. +It should return an integer which is negative, +zero, or positive, depending on whether the first item is less than, +equal to, or greater than the second. +.PP +.BR tsearch () +searches the tree for an item. +.IR key +points to the item to be searched for. +.IR rootp +points to a variable which points to the root of the tree. +If the tree is empty, +then the variable that +.IR rootp +points to should be set to NULL. +If the item is found in the tree, then +.BR tsearch () +returns a pointer +to it. +If it is not found, then +.BR tsearch () +adds it, and returns a +pointer to the newly added item. +.PP +.BR tfind () +is like +.BR tsearch (), +except that if the item is not +found, then +.BR tfind () +returns NULL. +.PP +.BR tdelete () +deletes an item from the tree. +Its arguments are the same as for +.BR tsearch (). +.PP +.BR twalk () +performs depth-first, left-to-right traversal of a binary +tree. +.IR root +points to the starting node for the traversal. +If that node is not the root, then only part of the tree will be visited. +.BR twalk () +calls the user function +.IR action +each time a node is +visited (that is, three times for an internal node, and once for a +leaf). +.IR action , +in turn, takes three arguments. +The first argument is a pointer to the node being visited. +The structure of the node is unspecified, +but it is possible to cast the pointer to a pointer-to-pointer-to-element +in order to access the element stored within the node. +The application must not modify the structure pointed to by this argument. +The second argument is an integer which +takes one of the values +.BR preorder , +.BR postorder , +or +.BR endorder +depending on whether this is the first, second, or +third visit to the internal node, +or the value +.BR leaf +if this is the single visit to a leaf node. +(These symbols are defined in +.IR .) +The third argument is the depth of the node; +the root node has depth zero. +.PP +(More commonly, +.BR preorder , +.BR postorder , +and +.BR endorder +are known as +.BR preorder , +.BR inorder , +and +.BR postorder : +before visiting the children, after the first and before the second, +and after visiting the children. +Thus, the choice of name +.BR post\%order +is rather confusing.) +.PP +.BR tdestroy () +removes the whole tree pointed to by +.IR root , +freeing all resources allocated by the +.BR tsearch () +function. +For the data in each tree node the function +.IR free_node +is called. +The pointer to the data is passed as the argument to the function. +If no such work is necessary, +.IR free_node +must point to a function +doing nothing. +.SH RETURN VALUE +.BR tsearch () +returns a pointer to a matching item in the tree, or to +the newly added item, or NULL if there was insufficient memory +to add the item. +.BR tfind () +returns a pointer to the item, or +NULL if no match is found. +If there are multiple elements that match the key, +the element returned is unspecified. +.PP +.BR tdelete () +returns a pointer to the parent of the item deleted, or +NULL if the item was not found. +.PP +.BR tsearch (), +.BR tfind (), +and +.BR tdelete () +also +return NULL if +.IR rootp +was NULL on entry. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR tsearch (), +.BR tfind (), +.br +.BR tdelete () +T} Thread safety MT-Safe race:rootp +T{ +.BR twalk () +T} Thread safety MT-Safe race:root +T{ +.BR tdestroy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4. +The function +.BR tdestroy () +is a GNU extension. +.SH NOTES +.BR twalk () +takes a pointer to the root, while the other functions +take a pointer to a variable which points to the root. +.PP +.BR tdelete () +frees the memory required for the node in the tree. +The user is responsible for freeing the memory for the corresponding +data. +.PP +The example program depends on the fact that +.BR twalk () +makes no +further reference to a node after calling the user function with +argument "endorder" or "leaf". +This works with the GNU library +implementation, but is not in the System V documentation. +.SH EXAMPLE +The following program inserts twelve random numbers into a binary +tree, where duplicate numbers are collapsed, then prints the numbers +in order. +.PP +.EX +#define _GNU_SOURCE /* Expose declaration of tdestroy() */ +#include +#include +#include +#include + +static void *root = NULL; + +static void * +xmalloc(unsigned n) +{ + void *p; + p = malloc(n); + if (p) + return p; + fprintf(stderr, "insufficient memory\\n"); + exit(EXIT_FAILURE); +} + +static int +compare(const void *pa, const void *pb) +{ + if (*(int *) pa < *(int *) pb) + return \-1; + if (*(int *) pa > *(int *) pb) + return 1; + return 0; +} + +static void +action(const void *nodep, const VISIT which, const int depth) +{ + int *datap; + + switch (which) { + case preorder: + break; + case postorder: + datap = *(int **) nodep; + printf("%6d\\n", *datap); + break; + case endorder: + break; + case leaf: + datap = *(int **) nodep; + printf("%6d\\n", *datap); + break; + } +} + +int +main(void) +{ + int i, *ptr; + void *val; + + srand(time(NULL)); + for (i = 0; i < 12; i++) { + ptr = xmalloc(sizeof(int)); + *ptr = rand() & 0xff; + val = tsearch((void *) ptr, &root, compare); + if (val == NULL) + exit(EXIT_FAILURE); + else if ((*(int **) val) != ptr) + free(ptr); + } + twalk(root, action); + tdestroy(root, free); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bsearch (3), +.BR hsearch (3), +.BR lsearch (3), +.BR qsort (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ttyname.3 b/man3/ttyname.3 new file mode 100644 index 0000000..1359d9c --- /dev/null +++ b/man3/ttyname.3 @@ -0,0 +1,128 @@ +.\" Copyright (c) 1995 Jim Van Zandt +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 2001-12-13, Martin Schulze +.\" Added ttyname_r, aeb, 2002-07-20 +.\" +.TH TTYNAME 3 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +ttyname, ttyname_r \- return name of a terminal +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "char *ttyname(int " fd ); +.PP +.BI "int ttyname_r(int " fd ", char *" buf ", size_t " buflen ); +.fi +.SH DESCRIPTION +The function +.BR ttyname () +returns a pointer to the null-terminated pathname of the terminal device +that is open on the file descriptor \fIfd\fP, or NULL on error +(for example, if \fIfd\fP is not connected to a terminal). +The return value may point to static data, possibly overwritten by the +next call. +The function +.BR ttyname_r () +stores this pathname in the buffer +.I buf +of length +.IR buflen . +.SH RETURN VALUE +The function +.BR ttyname () +returns a pointer to a pathname on success. +On error, NULL is returned, and +.I errno +is set appropriately. +The function +.BR ttyname_r () +returns 0 on success, and an error number upon error. +.SH ERRORS +.TP +.B EBADF +Bad file descriptor. +.TP +.B ENOTTY +File descriptor does not refer to a terminal device. +.TP +.B ERANGE +.RB ( ttyname_r ()) +.I buflen +was too small to allow storing the pathname. +.TP +.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23 +.B ENODEV +File descriptor refers to a slave pseudoterminal device +but the corresponding pathname could not be found (see NOTES). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ttyname () +T} Thread safety MT-Unsafe race:ttyname +T{ +.BR ttyname_r () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, 4.2BSD. +.SH NOTES +A process that keeps a file descriptor that refers to a +.BR pts (4) +device open when switching to another mount namespace that uses a different +.IR /dev/ptmx +instance may still accidentally find that a device path of the same name +for that file descriptor exists. +However, this device path refers to a different device and thus +can't be used to access the device that the file descriptor refers to. +Calling +.BR ttyname () +or +.BR ttyname_r () +on the file descriptor in the new mount namespace will cause these +functions to return NULL and set +.I errno +to +.BR ENODEV . +.SH SEE ALSO +.BR tty (1), +.BR fstat (2), +.BR ctermid (3), +.BR isatty (3), +.BR pts (4) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ttyname_r.3 b/man3/ttyname_r.3 new file mode 100644 index 0000000..aaa18ee --- /dev/null +++ b/man3/ttyname_r.3 @@ -0,0 +1 @@ +.so man3/ttyname.3 diff --git a/man3/ttyslot.3 b/man3/ttyslot.3 new file mode 100644 index 0000000..03d2f6b --- /dev/null +++ b/man3/ttyslot.3 @@ -0,0 +1,194 @@ +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH TTYSLOT 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +ttyslot \- find the slot of the current user's terminal in some file +.SH SYNOPSIS +.BR "#include " " /See NOTES */" +.PP +.B "int ttyslot(void);" +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR ttyslot (): +.RS 4 +Since glibc 2.24: + _DEFAULT_SOURCE +.br +From glibc 2.20 to 2.23: + _DEFAULT_SOURCE || + _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_\ <\ 500 +.br +Glibc 2.19 and earlier: + _BSD_SOURCE || + _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_\ <\ 500 +.RE +.ad b +.SH DESCRIPTION +The legacy function +.BR ttyslot () +returns the index of the current user's entry in some file. +.PP +Now "What file?" you ask. +Well, let's first look at some history. +.SS Ancient history +There used to be a file +.I /etc/ttys +in UNIX\ V6, that was read by the +.BR init (1) +program to find out what to do with each terminal line. +Each line consisted of three characters. +The first character was either \(aq0\(aq or \(aq1\(aq, +where \(aq0\(aq meant "ignore". +The second character denoted the terminal: \(aq8\(aq stood for "/dev/tty8". +The third character was an argument to +.BR getty (8) +indicating the sequence of line speeds to try (\(aq\-\(aq was: start trying +110 baud). +Thus a typical line was "18\-". +A hang on some line was solved by changing the \(aq1\(aq to a \(aq0\(aq, +signaling init, changing back again, and signaling init again. +.PP +In UNIX\ V7 the format was changed: here the second character +was the argument to +.BR getty (8) +indicating the sequence of line speeds to try (\(aq0\(aq was: cycle through +300-1200-150-110 baud; \(aq4\(aq was for the on-line console DECwriter) +while the rest of the line contained the name of the tty. +Thus a typical line was "14console". +.PP +Later systems have more elaborate syntax. +System V-like systems have +.I /etc/inittab +instead. +.SS Ancient history (2) +On the other hand, there is the file +.I /etc/utmp +listing the people currently logged in. +It is maintained by +.BR login (1). +It has a fixed size, and the appropriate index in the file was +determined by +.BR login (1) +using the +.BR ttyslot () +call to find the number of the line in +.I /etc/ttys +(counting from 1). +.SS The semantics of ttyslot +Thus, the function +.BR ttyslot () +returns the index of the controlling terminal of the calling process +in the file +.IR /etc/ttys , +and that is (usually) the same as the index of the entry for the +current user in the file +.IR /etc/utmp . +BSD still has the +.I /etc/ttys +file, but System V-like systems do not, and hence cannot refer to it. +Thus, on such systems the documentation says that +.BR ttyslot () +returns the current user's index in the user accounting data base. +.SH RETURN VALUE +If successful, this function returns the slot number. +On error (e.g., if none of the file descriptors 0, 1 or 2 is +associated with a terminal that occurs in this data base) +it returns 0 on UNIX\ V6 and V7 and BSD-like systems, +but \-1 on System V-like systems. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ttyslot () +T} Thread safety MT-Unsafe +.TE +.SH CONFORMING TO +SUSv1; marked as LEGACY in SUSv2; removed in POSIX.1-2001. +SUSv2 requires \-1 on error. +.SH NOTES +The utmp file is found in various places on various systems, such as +.IR /etc/utmp , +.IR /var/adm/utmp , +.IR /var/run/utmp . +.PP +The glibc2 implementation of this function reads the file +.BR _PATH_TTYS , +defined in +.I +as "/etc/ttys". +It returns 0 on error. +Since Linux systems do not usually have "/etc/ttys", it will +always return 0. +.PP +On BSD-like systems and Linux, the declaration of +.BR ttyslot () +is provided by +.IR . +On System V-like systems, the declaration is provided by +.IR . +Since glibc 2.24, +.IR +also provides the declaration with the following +feature test macro definitions: +.PP +.in +4n +.EX +(_XOPEN_SOURCE >= 500 || + (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)) + && ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600) +.EE +.in +.PP +Minix also has +.IR fttyslot ( fd ). +.\" .SH HISTORY +.\" .BR ttyslot () +.\" appeared in UNIX V7. +.SH SEE ALSO +.BR getttyent (3), +.BR ttyname (3), +.BR utmp (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/twalk.3 b/man3/twalk.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man3/twalk.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man3/tzname.3 b/man3/tzname.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man3/tzname.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man3/tzset.3 b/man3/tzset.3 new file mode 100644 index 0000000..bb821c4 --- /dev/null +++ b/man3/tzset.3 @@ -0,0 +1,257 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 11:01:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-11-13, aeb +.\" Modified 2004-12-01 mtk and Martin Schulze +.\" +.TH TZSET 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +tzset, tzname, timezone, daylight \- initialize time conversion information +.SH SYNOPSIS +.nf +.B #include +.PP +.B void tzset (void); +.PP +.BI "extern char *" tzname [2]; +.BI "extern long " timezone ; +.BI "extern int " daylight ; +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR tzset (): +_POSIX_C_SOURCE +.br +.IR tzname : +_POSIX_C_SOURCE +.br +.IR timezone , +.IR daylight : +_XOPEN_SOURCE + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE +.SH DESCRIPTION +The +.BR tzset () +function initializes the \fItzname\fP variable from the +.B TZ +environment variable. +This function is automatically called by the +other time conversion functions that depend on the timezone. +In a System-V-like environment, it will also set the variables \fItimezone\fP +(seconds West of UTC) and \fIdaylight\fP (to 0 if this timezone does not +have any daylight saving time rules, or to nonzero if there is a time, +past, present or future when daylight saving time applies). +.PP +If the +.B TZ +variable does not appear in the environment, the system timezone is used. +The system timezone is configured by copying, or linking, a file in the +.BR tzfile "(5) format to" +.IR /etc/localtime . +A timezone database of these files may be located in the system +timezone directory (see the \fBFILES\fP section below). +.PP +If the +.B TZ +variable does appear in the environment, but its value is empty, +or its value cannot be interpreted using any of the formats specified +below, then Coordinated Universal Time (UTC) is used. +.PP +The value of +.B TZ +can be one of two formats. +The first format is a string of characters that directly represent the +timezone to be used: +.PP +.in +4n +.EX +.IR "std offset" [ dst [ offset ][, start [ /time ], end [ /time ]]] +.EE +.in +.PP +There are no spaces in the specification. +The \fIstd\fP string specifies an abbreviation for the timezone and must be +three or more alphabetic characters. +When enclosed between the less-than (<) and greater-than (>) signs, the +characters set is expanded to include the plus (+) sign, the minus (-) +sign, and digits. +The \fIoffset\fP string immediately +follows \fIstd\fP and specifies the time value to be added to the local +time to get Coordinated Universal Time (UTC). +The \fIoffset\fP is positive +if the local timezone is west of the Prime Meridian and negative if it is +east. +The hour must be between 0 and 24, and the minutes and seconds 00 and 59: +.PP +.in +4n +.EX +.RI [ + | - ] hh [ :mm [ :ss ]] +.EE +.in +.PP +The \fIdst\fP string and \fIoffset\fP specify the name and offset for the +corresponding daylight saving timezone. +If the offset is omitted, +it defaults to one hour ahead of standard time. +.PP +The \fIstart\fP field specifies when daylight saving time goes into +effect and the \fIend\fP field specifies when the change is made back to +standard time. +These fields may have the following formats: +.TP +J\fIn\fP +This specifies the Julian day with \fIn\fP between 1 and 365. +Leap days are not counted. +In this format, February 29 can't be represented; +February 28 is day 59, and March 1 is always day 60. +.TP +.I n +This specifies the zero-based Julian day with \fIn\fP between 0 and 365. +February 29 is counted in leap years. +.TP +M\fIm\fP.\fIw\fP.\fId\fP +This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP +(1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12). +Week 1 is +the first week in which day \fId\fP occurs and week 5 is the last week +in which day \fId\fP occurs. +Day 0 is a Sunday. +.PP +The \fItime\fP fields specify when, in the local time currently in effect, +the change to the other time occurs. +If omitted, the default is 02:00:00. +.PP +Here is an example for New Zealand, +where the standard time (NZST) is 12 hours ahead of UTC, +and daylight saving time (NZDT), 13 hours ahead of UTC, +runs from the first Sunday in October to the third Sunday in March, +and the changeovers happen at the default time of 02:00:00: +.in +4n +.EX +TZ="NZST-12:00:00NZDT-13:00:00,M10.1.0,M3.3.0" +.EE +.in +.PP +The second format specifies that the timezone information should be read +from a file: +.PP +.in +4n +.EX +:[filespec] +.EE +.in +.PP +If the file specification \fIfilespec\fP is omitted, or its value cannot +be interpreted, then Coordinated Universal Time (UTC) is used. +If \fIfilespec\fP is given, it specifies another +.BR tzfile (5)-format +file to read the timezone information from. +If \fIfilespec\fP does not begin with a \(aq/\(aq, the file specification is +relative to the system timezone directory. +If the colon is omitted each +of the above \fBTZ\fP formats will be tried. +.PP +Here's an example, once more for New Zealand: +.PP +.in +4n +.EX +TZ=":Pacific/Auckland" +.EE +.in +.SH ENVIRONMENT +.TP +.B TZ +If this variable is set its value takes precedence over the system +configured timezone. +.TP +.B TZDIR +If this variable is set its value takes precedence over the system +configured timezone database directory path. +.SH FILES +.TP +.I /etc/localtime +The system timezone file. +.TP +.I /usr/share/zoneinfo/ +The system timezone database directory. +.TP +.I /usr/share/zoneinfo/posixrules +When a TZ string includes a dst timezone without anything following it, +then this file is used for the start/end rules. +It is in the +.BR tzfile "(5) format." +By default, the zoneinfo Makefile hard links it to the +.IR America/New_York " tzfile." +.PP +Above are the current standard file locations, but they are +configurable when glibc is compiled. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR tzset () +T} Thread safety MT-Safe env locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +.SH NOTES +.PP +4.3BSD had a function +.BI "char *timezone(" zone ", " dst ) +that returned the +name of the timezone corresponding to its first argument (minutes +West of UTC). +If the second argument was 0, the standard name was used, +otherwise the daylight saving time version. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR ctime (3), +.BR getenv (3), +.BR tzfile (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ualarm.3 b/man3/ualarm.3 new file mode 100644 index 0000000..a30ebe8 --- /dev/null +++ b/man3/ualarm.3 @@ -0,0 +1,170 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH UALARM 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +ualarm \- schedule signal after given number of microseconds +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR ualarm (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.12: +.nf +(_XOPEN_SOURCE\ >=\ 500) && ! (_POSIX_C_SOURCE\ >=\ 200809L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.TP 4 +.fi +Before glibc 2.12: +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH DESCRIPTION +The +.BR ualarm () +function causes the signal +.B SIGALRM +to be sent to the invoking process after (not less than) +.I usecs +microseconds. +The delay may be lengthened slightly by any system activity +or by the time spent processing the call or by the +granularity of system timers. +.PP +Unless caught or ignored, the +.B SIGALRM +signal will terminate the process. +.PP +If the +.I interval +argument is nonzero, further +.B SIGALRM +signals will be sent every +.I interval +microseconds after the first. +.SH RETURN VALUE +This function returns the number of microseconds remaining for +any alarm that was previously set, or 0 if no alarm was pending. +.SH ERRORS +.TP +.B EINTR +Interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +\fIusecs\fP or \fIinterval\fP is not smaller than 1000000. +(On systems where that is considered an error.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ualarm () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.3BSD, POSIX.1-2001. +POSIX.1-2001 marks +.BR ualarm () +as obsolete. +POSIX.1-2008 removes the specification of +.BR ualarm (). +4.3BSD, SUSv2, and POSIX do not define any errors. +.SH NOTES +POSIX.1-2001 does not specify what happens if the +.I usecs +argument is 0. +.\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD! +On Linux (and probably most other systems), +the effect is to cancel any pending alarm. +.PP +The type +.I useconds_t +is an unsigned integer type capable of holding integers +in the range [0,1000000]. +On the original BSD implementation, and in glibc before version 2.1, +the arguments to +.BR ualarm () +were instead typed as +.IR "unsigned int" . +Programs will be more portable if they never mention +.I useconds_t +explicitly. +.PP +The interaction of this function with +other timer functions such as +.BR alarm (2), +.BR sleep (3), +.BR nanosleep (2), +.BR setitimer (2), +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR usleep (3) +is unspecified. +.PP +This function is obsolete. +Use +.BR setitimer (2) +or POSIX interval timers +.RB ( timer_create (2), +etc.) +instead. +.SH SEE ALSO +.BR alarm (2), +.BR getitimer (2), +.BR nanosleep (2), +.BR select (2), +.BR setitimer (2), +.BR usleep (3), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ulckpwdf.3 b/man3/ulckpwdf.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man3/ulckpwdf.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man3/ulimit.3 b/man3/ulimit.3 new file mode 100644 index 0000000..3b16a9d --- /dev/null +++ b/man3/ulimit.3 @@ -0,0 +1,109 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Moved to man3, aeb, 980612 +.\" +.TH ULIMIT 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ulimit \- get and set user limits +.SH SYNOPSIS +.B #include +.PP +.BI "long ulimit(int " cmd ", long " newlimit ); +.SH DESCRIPTION +Warning: this routine is obsolete. +Use +.BR getrlimit (2), +.BR setrlimit (2), +and +.BR sysconf (3) +instead. +For the shell command +.BR ulimit (), +see +.BR bash (1). +.PP +The +.BR ulimit () +call will get or set some limit for the calling process. +The +.I cmd +argument can have one of the following values. +.TP +.B UL_GETFSIZE +Return the limit on the size of a file, in units of 512 bytes. +.TP +.B UL_SETFSIZE +Set the limit on the size of a file. +.TP +.B 3 +(Not implemented for Linux.) +Return the maximum possible address of the data segment. +.TP +.B 4 +(Implemented but no symbolic constant provided.) +Return the maximum number of files that the calling process can open. +.SH RETURN VALUE +On success, +.BR ulimit () +returns a nonnegative value. +On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EPERM +An unprivileged process tried to increase a limit. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ulimit () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +SVr4, POSIX.1-2001. +POSIX.1-2008 marks +.BR ulimit () +as obsolete. +.SH SEE ALSO +.BR bash (1), +.BR getrlimit (2), +.BR setrlimit (2), +.BR sysconf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/undocumented.3 b/man3/undocumented.3 new file mode 100644 index 0000000..40ebd16 --- /dev/null +++ b/man3/undocumented.3 @@ -0,0 +1,187 @@ +.\" Copyright 1995 Jim Van Zandt +.\" From jrv@vanzandt.mv.com Mon Sep 4 21:11:50 1995 +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 1996-11-08, meem@sherilyn.wustl.edu, corrections +.\" 2004-10-31, aeb, changed maintainer address, updated list +.\" 2015-04-20, william@tuffbizz.com, updated list +.\" +.TH UNDOCUMENTED 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +undocumented \- undocumented library functions +.SH SYNOPSIS +Undocumented library functions +.SH DESCRIPTION +This man page mentions those library functions which are implemented in +the standard libraries but not yet documented in man pages. +.SS Solicitation +If you have information about these functions, +please look in the source code, write a man page (using a style +similar to that of the other Linux section 3 man pages), and send it to +.B mtk.manpages@gmail.com +for inclusion in the next man page release. +.SS The list +.PP +.BR authdes_create (3), +.BR authdes_getucred (3), +.BR authdes_pk_create (3), +.\" .BR chflags (3), +.BR clntunix_create (3), +.BR creat64 (3), +.BR dn_skipname (3), +.\" .BR fattach (3), +.\" .BR fchflags (3), +.\" .BR fclean (3), +.BR fcrypt (3), +.\" .BR fdetach (3), +.BR fp_nquery (3), +.BR fp_query (3), +.BR fp_resstat (3), +.BR freading (3), +.BR freopen64 (3), +.BR fseeko64 (3), +.BR ftello64 (3), +.BR ftw64 (3), +.BR fwscanf (3), +.BR get_avphys_pages (3), +.BR getdirentries64 (3), +.BR getmsg (3), +.BR getnetname (3), +.BR get_phys_pages (3), +.BR getpublickey (3), +.BR getsecretkey (3), +.BR h_errlist (3), +.BR host2netname (3), +.BR hostalias (3), +.BR inet_nsap_addr (3), +.BR inet_nsap_ntoa (3), +.BR init_des (3), +.BR libc_nls_init (3), +.BR mstats (3), +.BR netname2host (3), +.BR netname2user (3), +.BR nlist (3), +.BR obstack_free (3), +.\" .BR obstack stuff (3), +.BR parse_printf_format (3), +.BR p_cdname (3), +.BR p_cdnname (3), +.BR p_class (3), +.BR p_fqname (3), +.BR p_option (3), +.BR p_query (3), +.BR printf_size (3), +.BR printf_size_info (3), +.BR p_rr (3), +.BR p_time (3), +.BR p_type (3), +.BR putlong (3), +.BR putshort (3), +.BR re_compile_fastmap (3), +.BR re_compile_pattern (3), +.BR register_printf_function (3), +.BR re_match (3), +.BR re_match_2 (3), +.BR re_rx_search (3), +.BR re_search (3), +.BR re_search_2 (3), +.BR re_set_registers (3), +.BR re_set_syntax (3), +.BR res_send_setqhook (3), +.BR res_send_setrhook (3), +.BR ruserpass (3), +.BR setfileno (3), +.BR sethostfile (3), +.BR svc_exit (3), +.BR svcudp_enablecache (3), +.BR tell (3), +.BR tr_break (3), +.BR tzsetwall (3), +.BR ufc_dofinalperm (3), +.BR ufc_doit (3), +.BR user2netname (3), +.BR wcschrnul (3), +.BR wcsftime (3), +.BR wscanf (3), +.BR xdr_authdes_cred (3), +.BR xdr_authdes_verf (3), +.BR xdr_cryptkeyarg (3), +.BR xdr_cryptkeyres (3), +.BR xdr_datum (3), +.BR xdr_des_block (3), +.BR xdr_domainname (3), +.BR xdr_getcredres (3), +.BR xdr_keybuf (3), +.BR xdr_keystatus (3), +.BR xdr_mapname (3), +.BR xdr_netnamestr (3), +.BR xdr_netobj (3), +.BR xdr_passwd (3), +.BR xdr_peername (3), +.BR xdr_rmtcall_args (3), +.BR xdr_rmtcallres (3), +.BR xdr_unixcred (3), +.BR xdr_yp_buf (3), +.BR xdr_yp_inaddr (3), +.BR xdr_ypbind_binding (3), +.BR xdr_ypbind_resp (3), +.BR xdr_ypbind_resptype (3), +.BR xdr_ypbind_setdom (3), +.BR xdr_ypdelete_args (3), +.BR xdr_ypmaplist (3), +.BR xdr_ypmaplist_str (3), +.BR xdr_yppasswd (3), +.BR xdr_ypreq_key (3), +.BR xdr_ypreq_nokey (3), +.BR xdr_ypresp_all (3), +.BR xdr_ypresp_all_seq (3), +.BR xdr_ypresp_key_val (3), +.BR xdr_ypresp_maplist (3), +.BR xdr_ypresp_master (3), +.BR xdr_ypresp_order (3), +.BR xdr_ypresp_val (3), +.BR xdr_ypstat (3), +.BR xdr_ypupdate_args (3), +.BR yp_all (3), +.BR yp_bind (3), +.BR yperr_string (3), +.BR yp_first (3), +.BR yp_get_default_domain (3), +.BR yp_maplist (3), +.BR yp_master (3), +.BR yp_match (3), +.BR yp_next (3), +.BR yp_order (3), +.BR ypprot_err (3), +.BR yp_unbind (3), +.BR yp_update (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/ungetc.3 b/man3/ungetc.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man3/ungetc.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man3/ungetwc.3 b/man3/ungetwc.3 new file mode 100644 index 0000000..f6e54ee --- /dev/null +++ b/man3/ungetwc.3 @@ -0,0 +1,108 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH UNGETWC 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +ungetwc \- push back a wide character onto a FILE stream +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wint_t ungetwc(wint_t " wc ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR ungetwc () +function is the wide-character equivalent of the +.BR ungetc (3) +function. +It pushes back a wide character onto +.I stream +and returns it. +.PP +If +.I wc +is +.BR WEOF , +it returns +.BR WEOF . +If +.I wc +is an invalid wide character, +it sets +.IR errno +to +.B EILSEQ +and returns +.BR WEOF . +.PP +If +.I wc +is a valid wide character, it is pushed back onto the stream +and thus becomes available for future wide-character read operations. +The file-position indicator is decremented by one or more. +The end-of-file +indicator is cleared. +The backing storage of the file is not affected. +.PP +Note: +.I wc +need not be the last wide-character read from the stream; +it can be any other valid wide character. +.PP +If the implementation supports multiple push-back operations in a row, the +pushed-back wide characters will be read in reverse order; however, only one +level of push-back is guaranteed. +.SH RETURN VALUE +The +.BR ungetwc () +function returns +.IR wc +when successful, or +.B WEOF +upon +failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR ungetwc () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR ungetwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR fgetwc (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/unlocked_stdio.3 b/man3/unlocked_stdio.3 new file mode 100644 index 0000000..ed65d7d --- /dev/null +++ b/man3/unlocked_stdio.3 @@ -0,0 +1,191 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH UNLOCKED_STDIO 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +getc_unlocked, getchar_unlocked, putc_unlocked, +putchar_unlocked \- nonlocking stdio functions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int getc_unlocked(FILE *" stream ); +.B "int getchar_unlocked(void);" +.BI "int putc_unlocked(int " c ", FILE *" stream ); +.BI "int putchar_unlocked(int " c ); +.PP +.BI "void clearerr_unlocked(FILE *" stream ); +.BI "int feof_unlocked(FILE *" stream ); +.BI "int ferror_unlocked(FILE *" stream ); +.BI "int fileno_unlocked(FILE *" stream ); +.BI "int fflush_unlocked(FILE *" stream ); +.BI "int fgetc_unlocked(FILE *" stream ); +.BI "int fputc_unlocked(int " c ", FILE *" stream ); +.BI "size_t fread_unlocked(void *" ptr ", size_t " size ", size_t " n , +.BI " FILE *" stream ); +.BI "size_t fwrite_unlocked(const void *" ptr ", size_t " size ", size_t " n , +.BI " FILE *" stream ); +.PP +.BI "char *fgets_unlocked(char *" s ", int " n ", FILE *" stream ); +.BI "int fputs_unlocked(const char *" s ", FILE *" stream ); + +.B #include +.PP +.BI "wint_t getwc_unlocked(FILE *" stream ); +.B "wint_t getwchar_unlocked(void);" +.BI "wint_t fgetwc_unlocked(FILE *" stream ); +.BI "wint_t fputwc_unlocked(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwc_unlocked(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwchar_unlocked(wchar_t " wc ); +.BI "wchar_t *fgetws_unlocked(wchar_t *" ws ", int " n ", FILE *" stream ); +.BI "int fputws_unlocked(const wchar_t *" ws ", FILE *" stream ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.PP +.BR getc_unlocked (), +.BR getchar_unlocked (), +.BR putc_unlocked (), +.BR putchar_unlocked (): +.RS 4 +/* Since glibc 2.24: */ _POSIX_C_SOURCE\ >=\ 199309L + || /* Glibc versions <= 2.23: */ _POSIX_C_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.PP +.BR clearerr_unlocked (), +.BR feof_unlocked (), +.BR ferror_unlocked (), +.BR fileno_unlocked (), +.BR fflush_unlocked (), +.BR fgetc_unlocked (), +.BR fputc_unlocked (), +.BR fread_unlocked (), +.BR fwrite_unlocked (): +.RS 4 +/* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.PP +.BR fgets_unlocked (), +.BR fputs_unlocked (), +.BR getwc_unlocked (), +.BR getwchar_unlocked (), +.BR fgetwc_unlocked (), +.BR fputwc_unlocked (), +.BR putwchar_unlocked (), +.BR fgetws_unlocked (), +.BR fputws_unlocked (): +.RS 4 +_GNU_SOURCE +.RE +.ad b +.SH DESCRIPTION +Each of these functions has the same behavior as its counterpart +without the "_unlocked" suffix, except that they do not use locking +(they do not set locks themselves, and do not test for the presence +of locks set by others) and hence are thread-unsafe. +See +.BR flockfile (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.TS +allbox; +lbw20 lb lb +l l l. +Interface Attribute Value +T{ +.BR getc_unlocked (), +.BR putc_unlocked (), +.BR clearerr_unlocked (), +.BR fflush_unlocked (), +.BR fgetc_unlocked (), +.BR fputc_unlocked (), +.BR fread_unlocked (), +.BR fwrite_unlocked (), +.BR fgets_unlocked (), +.BR fputs_unlocked (), +.BR getwc_unlocked (), +.BR fgetwc_unlocked (), +.BR fputwc_unlocked (), +.BR putwc_unlocked (), +.BR fgetws_unlocked (), +.BR fputws_unlocked () +T} Thread safety MT-Safe race:stream +T{ +.BR getchar_unlocked (), +.BR getwchar_unlocked () +T} Thread safety MT-Unsafe race:stdin +T{ +.BR putchar_unlocked (), +.BR putwchar_unlocked () +T} Thread safety MT-Unsafe race:stdout +T{ +.BR feof_unlocked (), +.BR ferror_unlocked (), +.BR fileno_unlocked () +T} Thread safety MT-Safe +.TE +.ad +.SH CONFORMING TO +The four functions +.BR getc_unlocked (), +.BR getchar_unlocked (), +.BR putc_unlocked (), +.BR putchar_unlocked () +are in POSIX.1-2001 and POSIX.1-2008. +.PP +The nonstandard +.BR *_unlocked () +variants occur on a few UNIX systems, and are available in recent glibc. +.\" E.g., in HP-UX 10.0. In HP-UX 10.30 they are called obsolescent, and +.\" moved to a compatibility library. +.\" Available in HP-UX 10.0: clearerr_unlocked, fclose_unlocked, +.\" feof_unlocked, ferror_unlocked, fflush_unlocked, fgets_unlocked, +.\" fgetwc_unlocked, fgetws_unlocked, fileno_unlocked, fputs_unlocked, +.\" fputwc_unlocked, fputws_unlocked, fread_unlocked, fseek_unlocked, +.\" ftell_unlocked, fwrite_unlocked, getc_unlocked, getchar_unlocked, +.\" getw_unlocked, getwc_unlocked, getwchar_unlocked, putc_unlocked, +.\" putchar_unlocked, puts_unlocked, putws_unlocked, putw_unlocked, +.\" putwc_unlocked, putwchar_unlocked, rewind_unlocked, setvbuf_unlocked, +.\" ungetc_unlocked, ungetwc_unlocked. +They should probably not be used. +.SH SEE ALSO +.BR flockfile (3), +.BR stdio (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/unlockpt.3 b/man3/unlockpt.3 new file mode 100644 index 0000000..6030281 --- /dev/null +++ b/man3/unlockpt.3 @@ -0,0 +1,90 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.TH UNLOCKPT 3 2017-07-13 "" "Linux Programmer's Manual" +.SH NAME +unlockpt \- unlock a pseudoterminal master/slave pair +.SH SYNOPSIS +.B #define _XOPEN_SOURCE +.br +.B #include +.PP +.BI "int unlockpt(int " fd ");" +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR unlockpt (): +.br +.RS 4 +Since glibc 2.24: + _XOPEN_SOURCE\ >=\ 500 || + (_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) +.br +Glibc 2.23 and earlier: + _XOPEN_SOURCE +.RE +.ad +.SH DESCRIPTION +The +.BR unlockpt () +function unlocks the slave pseudoterminal device +corresponding to the master pseudoterminal referred to by +.IR fd . +.PP +.BR unlockpt () +should be called before opening the slave side of a pseudoterminal. +.SH RETURN VALUE +When successful, +.BR unlockpt () +returns 0. +Otherwise, it returns \-1 and sets +.I errno +appropriately. +.SH ERRORS +.TP +.B EBADF +The +.I fd +argument is not a file descriptor open for writing. +.TP +.B EINVAL +The +.I fd +argument is not associated with a master pseudoterminal. +.SH VERSIONS +.BR unlockpt () +is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR unlockpt () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ptsname (3), +.BR pts (4), +.BR pty (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/unsetenv.3 b/man3/unsetenv.3 new file mode 100644 index 0000000..19ec56c --- /dev/null +++ b/man3/unsetenv.3 @@ -0,0 +1 @@ +.so man3/setenv.3 diff --git a/man3/updwtmp.3 b/man3/updwtmp.3 new file mode 100644 index 0000000..589a438 --- /dev/null +++ b/man3/updwtmp.3 @@ -0,0 +1,107 @@ +.\" Copyright 1997 Nicolás Lichtmaier +.\" Created Wed Jul 2 23:27:34 ART 1997 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Added info on availability, aeb, 971207 +.\" Added -lutil remark, 030718 +.\" 2008-07-02, mtk, document updwtmpx() +.\" +.TH UPDWTMP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +updwtmp, logwtmp \- append an entry to the wtmp file +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void updwtmp(const char *" wtmp_file ", const struct utmp *" ut ); +.BI "void logwtmp(const char *" line ", const char *" name \ +", const char *" host ); +.fi +.PP +For +.BR logwtmp (), +link with \fI\-lutil\fP. +.SH DESCRIPTION +.BR updwtmp () +appends the utmp structure +.I ut +to the wtmp file. +.PP +.BR logwtmp () +constructs a utmp structure using +.IR line ", " name ", " host , +current time and current process ID. +Then it calls +.BR updwtmp () +to append the structure to the wtmp file. +.SH FILES +.TP +.I /var/log/wtmp +database of past user logins +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw24 +l l l. +Interface Attribute Value +T{ +.BR updwtmp (), +.br +.BR logwtmp () +T} Thread safety MT-Unsafe sig:ALRM timer +.TE +.sp 1 +.SH CONFORMING TO +Not in POSIX.1. +Present on Solaris, NetBSD, and perhaps other systems. +.SH NOTES +For consistency with the other "utmpx" functions (see +.BR getutxent (3)), +glibc provides (since version 2.1): +.PP +.in +4n +.EX +.B #include +.BI "void updwtmpx (const char *" wtmpx_file ", const struct utmpx *" utx ); +.EE +.in +.PP +This function performs the same task as +.BR updwtmp (), +but differs in that it takes a +.I utmpx +structure as its last argument. +.SH SEE ALSO +.BR getutxent (3), +.BR wtmp (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/updwtmpx.3 b/man3/updwtmpx.3 new file mode 100644 index 0000000..0dc4dea --- /dev/null +++ b/man3/updwtmpx.3 @@ -0,0 +1 @@ +.so man3/updwtmp.3 diff --git a/man3/uselocale.3 b/man3/uselocale.3 new file mode 100644 index 0000000..c7fe1ba --- /dev/null +++ b/man3/uselocale.3 @@ -0,0 +1,134 @@ +'\" t +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH USELOCALE 3 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +uselocale \- set/get the locale for the calling thread +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "locale_t uselocale(locale_t " newloc ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR uselocale (): +.PD 0 +.RS 4 +.TP +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.PD +.SH DESCRIPTION +The +.BR uselocale () +function sets the current locale for the calling thread, +and returns the thread's previously current locale. +After a successful call to +.BR uselocale (), +any calls by this thread to functions that depend on the locale +will operate as though the locale has been set to +.IR newloc . +.PP +The +.I newloc +argument can have one of the following values: +.TP +A handle returned by a call to \fBnewlocale\fP(3) or \fBduplocale\fP(3) +The calling thread's current locale is set to the specified locale. +.TP +The special locale object handle \fBLC_GLOBAL_LOCALE\fP +The calling thread's current locale is set to the global locale determined by +.BR setlocale (3). +.TP +.I "(locale_t) 0" +The calling thread's current locale is left unchanged +(and the current locale is returned as the function result). +.SH RETURN VALUE +On success, +.BR uselocale () +returns the locale handle that was set by the previous call to +.BR uselocale () +in this thread, or +.BR LC_GLOBAL_HANDLE +if there was no such previous call. +On error, it returns +.IR "(locale_t)\ 0", +and sets +.I errno +to indicate the cause of the error. +.SH ERRORS +.TP +.B EINVAL +.I newloc +does not refer to a valid locale object. +.SH VERSIONS +The +.BR uselocale () +function first appeared in version 2.3 of the GNU C library. +.SH CONFORMING TO +POSIX.1-2008. +.SH NOTES +Unlike +.BR setlocale (3), +.BR uselocale () +does not allow selective replacement of individual locale categories. +To employ a locale that differs in only a few categories from the current +locale, use calls to +.BR duplocale (3) +and +.BR newlocale (3) +to obtain a locale object equivalent to the current locale and +modify the desired categories in that object. +.SH EXAMPLE +See +.BR newlocale (3) +and +.BR duplocale (3). +.SH SEE ALSO +.BR locale (1), +.BR duplocale (3), +.BR freelocale (3), +.BR newlocale (3), +.BR setlocale (3), +.BR locale (5), +.BR locale (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/usleep.3 b/man3/usleep.3 new file mode 100644 index 0000000..2afa722 --- /dev/null +++ b/man3/usleep.3 @@ -0,0 +1,170 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-04-01 by aeb +.\" Modified 2003-07-23 by aeb +.\" +.TH USLEEP 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +usleep \- suspend execution for microsecond intervals +.SH SYNOPSIS +.nf +.B "#include " +.PP +.BI "int usleep(useconds_t " usec ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR usleep (): +.ad l +.RS 4 +.PD 0 +.TP 4 +Since glibc 2.12: +.nf +(_XOPEN_SOURCE\ >=\ 500) && ! (_POSIX_C_SOURCE\ >=\ 200809L) + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _BSD_SOURCE +.TP 4 +.fi +Before glibc 2.12: +_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 +.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED +.PD +.RE +.ad b +.SH DESCRIPTION +The +.BR usleep () +function suspends execution of the calling thread for +(at least) \fIusec\fP microseconds. +The sleep may be lengthened slightly +by any system activity or by the time spent processing the call or by the +granularity of system timers. +.SH RETURN VALUE +The +.BR usleep () +function returns 0 on success. +On error, \-1 is returned, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B EINTR +Interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +\fIusec\fP is greater than or equal to 1000000. +(On systems where that is considered an error.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR usleep () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +4.3BSD, POSIX.1-2001. +POSIX.1-2001 declares this function obsolete; use +.BR nanosleep (2) +instead. +POSIX.1-2008 removes the specification of +.BR usleep (). +.PP +On the original BSD implementation, +and in glibc before version 2.2.2, the return type of this function is +.IR void . +The POSIX version returns +.IR int , +and this is also the prototype used since glibc 2.2.2. +.PP +Only the +.B EINVAL +error return is documented by SUSv2 and POSIX.1-2001. +.SH NOTES +The type +.I useconds_t +is an unsigned integer type capable of holding integers +in the range [0,1000000]. +Programs will be more portable +if they never mention this type explicitly. +Use +.PP +.in +4n +.EX +#include +\&... + unsigned int usecs; +\&... + usleep(usecs); +.EE +.in +.PP +The interaction of this function with the +.B SIGALRM +signal, and with other timer functions such as +.BR alarm (2), +.BR sleep (3), +.BR nanosleep (2), +.BR setitimer (2), +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR ualarm (3) +is unspecified. +.SH SEE ALSO +BR alarm (2), +.BR getitimer (2), +.BR nanosleep (2), +.BR select (2), +.BR setitimer (2), +.BR sleep (3), +.BR ualarm (3), +.BR time (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/utmpname.3 b/man3/utmpname.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/utmpname.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/utmpxname.3 b/man3/utmpxname.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man3/utmpxname.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man3/va_arg.3 b/man3/va_arg.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man3/va_arg.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man3/va_copy.3 b/man3/va_copy.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man3/va_copy.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man3/va_end.3 b/man3/va_end.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man3/va_end.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man3/va_start.3 b/man3/va_start.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man3/va_start.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man3/valloc.3 b/man3/valloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man3/valloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man3/vasprintf.3 b/man3/vasprintf.3 new file mode 100644 index 0000000..5a8753a --- /dev/null +++ b/man3/vasprintf.3 @@ -0,0 +1 @@ +.so man3/asprintf.3 diff --git a/man3/vdprintf.3 b/man3/vdprintf.3 new file mode 100644 index 0000000..fa36f35 --- /dev/null +++ b/man3/vdprintf.3 @@ -0,0 +1 @@ +.so man3/dprintf.3 diff --git a/man3/verr.3 b/man3/verr.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man3/verr.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/verrx.3 b/man3/verrx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man3/verrx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/versionsort.3 b/man3/versionsort.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man3/versionsort.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man3/vfprintf.3 b/man3/vfprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man3/vfprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/vfscanf.3 b/man3/vfscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man3/vfscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/vfwprintf.3 b/man3/vfwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man3/vfwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/vlimit.3 b/man3/vlimit.3 new file mode 100644 index 0000000..58a817b --- /dev/null +++ b/man3/vlimit.3 @@ -0,0 +1,3 @@ +.so man2/getrlimit.2 +.\" No new programs should use vlimit(3). +.\" getrlimit(2) briefly discusses vlimit(3), so point the user there. diff --git a/man3/vprintf.3 b/man3/vprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man3/vprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/vscanf.3 b/man3/vscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man3/vscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/vsnprintf.3 b/man3/vsnprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man3/vsnprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/vsprintf.3 b/man3/vsprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man3/vsprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man3/vsscanf.3 b/man3/vsscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man3/vsscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man3/vswprintf.3 b/man3/vswprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man3/vswprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/vsyslog.3 b/man3/vsyslog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man3/vsyslog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man3/vtimes.3 b/man3/vtimes.3 new file mode 100644 index 0000000..4097ab7 --- /dev/null +++ b/man3/vtimes.3 @@ -0,0 +1,3 @@ +.so man2/getrusage.2 +.\" No new programs should use vtimes(3). +.\" getrusage(2) briefly discusses vtimes(3), so point the user there. diff --git a/man3/vwarn.3 b/man3/vwarn.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man3/vwarn.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/vwarnx.3 b/man3/vwarnx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man3/vwarnx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/vwprintf.3 b/man3/vwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man3/vwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man3/warn.3 b/man3/warn.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man3/warn.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/warnx.3 b/man3/warnx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man3/warnx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man3/wcpcpy.3 b/man3/wcpcpy.3 new file mode 100644 index 0000000..e6c6be5 --- /dev/null +++ b/man3/wcpcpy.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCPCPY 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcpcpy \- copy a wide-character string, returning a pointer to its end +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcpcpy(wchar_t *" dest ", const wchar_t *" src ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR wcpcpy (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR wcpcpy () +function is the wide-character equivalent of the +.BR stpcpy (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\(aq\\0\(aq), +to the array pointed to by +.IR dest . +.PP +The strings may not overlap. +.PP +The programmer must ensure that there +is room for at least +.IR wcslen(src)+1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcpcpy () +returns a pointer to the end of the wide-character string +.IR dest , +that is, a pointer to the terminating null wide character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcpcpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2008. +.SH SEE ALSO +.BR strcpy (3), +.BR wcscpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcpncpy.3 b/man3/wcpncpy.3 new file mode 100644 index 0000000..4bfcdc7 --- /dev/null +++ b/man3/wcpncpy.3 @@ -0,0 +1,118 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCPNCPY 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcpncpy \- copy a fixed-size string of wide characters, +returning a pointer to its end +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcpncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR wcpncpy (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR wcpncpy () +function is the wide-character equivalent +of the +.BR stpncpy (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.IR src , +including the terminating null wide (L\(aq\\0\(aq), +to the array pointed to by +.IR dest . +Exactly +.I n +wide characters are +written at +.IR dest . +If the length +.IR wcslen(src) +is smaller than +.IR n , +the remaining wide characters in the array pointed to +by +.I dest +are filled with L\(aq\\0\(aq characters. +If the length +.IR wcslen(src) +is greater than or equal +to +.IR n , +the string pointed to by +.I dest +will +not be L\(aq\\0\(aq terminated. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wcpncpy () +returns a pointer to the last wide character written, that is, +.IR dest + n \-1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcpncpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2008. +.SH SEE ALSO +.BR stpncpy (3), +.BR wcsncpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcrtomb.3 b/man3/wcrtomb.3 new file mode 100644 index 0000000..7f01752 --- /dev/null +++ b/man3/wcrtomb.3 @@ -0,0 +1,146 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCRTOMB 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcrtomb \- convert a wide character to a multibyte sequence +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The main case for this function is when +.I s +is +not NULL and +.I wc +is not a null wide character (L\(aq\\0\(aq). +In this case, the +.BR wcrtomb () +function +converts the wide character +.I wc +to its multibyte representation and stores it +at the beginning of the character +array pointed to by +.IR s . +It updates the shift state +.IR *ps , +and +returns the length of said multibyte representation, +that is, the number of bytes +written at +.IR s . +.PP +A different case is when +.I s +is not NULL, +but +.I wc +is a null wide character (L\(aq\\0\(aq). +In this case, the +.BR wcrtomb () +function stores at +the character array pointed to by +.I s +the shift sequence needed to +bring +.I *ps +back to the initial state, +followed by a \(aq\\0\(aq byte. +It updates the shift state +.I *ps +(i.e., brings +it into the initial state), +and returns the length of the shift sequence plus +one, that is, the number of bytes written at +.IR s . +.PP +A third case is when +.I s +is NULL. +In this case, +.I wc +is ignored, +and the function effectively returns +.PP + wcrtomb(buf, L\(aq\\0\(aq, ps) +.PP +where +.I buf +is an internal anonymous buffer. +.PP +In all of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcrtomb () +function is used instead. +.SH RETURN VALUE +The +.BR wcrtomb () +function returns the number of +bytes that have been or would +have been written to the byte array at +.IR s . +If +.I wc +can not be +represented as a multibyte sequence (according to the current locale), +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw26 +l l l. +Interface Attribute Value +T{ +.BR wcrtomb () +T} Thread safety MT-Unsafe race:wcrtomb/!ps +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR wcrtomb () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR mbsinit (3), +.BR wcsrtombs (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcscasecmp.3 b/man3/wcscasecmp.3 new file mode 100644 index 0000000..70d9e7c --- /dev/null +++ b/man3/wcscasecmp.3 @@ -0,0 +1,117 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSCASECMP 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscasecmp \- compare two wide-character strings, ignoring case +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int wcscasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR wcscasecmp (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR wcscasecmp () +function is the wide-character equivalent of the +.BR strcasecmp (3) +function. +It compares the wide-character string pointed to +by +.I s1 +and the wide-character string pointed to by +.IR s2 , +ignoring +case differences +.RB ( towupper (3), +.BR towlower (3)). +.SH RETURN VALUE +The +.BR wcscasecmp () +function returns zero if the wide-character strings at +.I s1 +and +.I s2 +are equal except for case distinctions. +It returns a +positive integer if +.I s1 +is greater than +.IR s2 , +ignoring case. +It +returns a negative integer if +.I s1 +is smaller +than +.IR s2 , +ignoring case. +.SH VERSIONS +The +.BR wcscasecmp () +function is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcscasecmp () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2008. +This function is not specified in POSIX.1-2001, +and is not widely available on other systems. +.SH NOTES +The behavior of +.BR wcscasecmp () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR strcasecmp (3), +.BR wcscmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcscat.3 b/man3/wcscat.3 new file mode 100644 index 0000000..1c7d567 --- /dev/null +++ b/man3/wcscat.3 @@ -0,0 +1,75 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCAT 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscat \- concatenate two wide-character strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcscat(wchar_t *" dest ", const wchar_t *" src ); +.fi +.SH DESCRIPTION +The +.BR wcscat () +function is the wide-character equivalent +of the +.BR strcat (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\(aq\\0\(aq), +to the end of the wide-character string pointed to by +.IR dest . +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least +.IR wcslen(dest) + wcslen(src) +1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcscat () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcscat () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strcat (3), +.BR wcpcpy (3), +.BR wcscpy (3), +.BR wcsncat (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcschr.3 b/man3/wcschr.3 new file mode 100644 index 0000000..7e8e2af --- /dev/null +++ b/man3/wcschr.3 @@ -0,0 +1,75 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCHR 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcschr \- search a wide character in a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR wcschr () +function is the wide-character equivalent +of the +.BR strchr (3) +function. +It searches the first occurrence of +.I wc +in the wide-character +string pointed to by +.IR wcs . +.SH RETURN VALUE +The +.BR wcschr () +function returns a pointer to the first occurrence of +.I wc +in the wide-character string pointed to by +.IR wcs , +or NULL if +.I wc +does not occur in the string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcschr () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strchr (3), +.BR wcspbrk (3), +.BR wcsrchr (3), +.BR wcsstr (3), +.BR wmemchr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcscmp.3 b/man3/wcscmp.3 new file mode 100644 index 0000000..4c1bc63 --- /dev/null +++ b/man3/wcscmp.3 @@ -0,0 +1,85 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCMP 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscmp \- compare two wide-character strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 ); +.fi +.SH DESCRIPTION +The +.BR wcscmp () +function is the wide-character equivalent +of the +.BR strcmp (3) +function. +It compares the wide-character string pointed to by +.I s1 +and the +wide-character string pointed to by +.IR s2 . +.SH RETURN VALUE +The +.BR wcscmp () +function returns zero if the wide-character strings at +.I s1 +and +.I s2 +are equal. +It returns an integer greater than zero if +at the first differing position +.IR i , +the corresponding wide-character +.I s1[i] +is greater than +.IR s2[i] . +It returns an integer less than zero if +at the first differing position +.IR i , +the corresponding wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcscmp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strcmp (3), +.BR wcscasecmp (3), +.BR wmemcmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcscpy.3 b/man3/wcscpy.3 new file mode 100644 index 0000000..14ef235 --- /dev/null +++ b/man3/wcscpy.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCPY 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscpy \- copy a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcscpy(wchar_t *" dest ", const wchar_t *" src ); +.fi +.SH DESCRIPTION +The +.BR wcscpy () +function is the wide-character equivalent +of the +.BR strcpy (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\(aq\\0\(aq), +to the array pointed to by +.IR dest . +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is +room for at least +.IR "wcslen(src)+1" +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcscpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcscpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strcpy (3), +.BR wcpcpy (3), +.BR wcscat (3), +.BR wcsdup (3), +.BR wmemcpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcscspn.3 b/man3/wcscspn.3 new file mode 100644 index 0000000..92e9e97 --- /dev/null +++ b/man3/wcscspn.3 @@ -0,0 +1,87 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSCSPN 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcscspn \- search a wide-character string for any of a set of wide characters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject ); +.fi +.SH DESCRIPTION +The +.BR wcscspn () +function is the wide-character equivalent +of the +.BR strcspn (3) +function. +It determines the length of the longest initial segment of +.I wcs +which consists entirely of wide-characters not listed in +.IR reject . +In +other words, it searches for the first occurrence in the wide-character +string +.I wcs +of any of the characters in the wide-character string +.IR reject . +.SH RETURN VALUE +The +.BR wcscspn () +function returns the number of +wide characters in the longest +initial segment of +.I wcs +which consists entirely of wide-characters not +listed in +.IR reject . +In other words, it returns the position of the first +occurrence in the wide-character string +.I wcs +of any of the characters in +the wide-character string +.IR reject , +or +.IR wcslen(wcs) +if there is none. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcscspn () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strcspn (3), +.BR wcspbrk (3), +.BR wcsspn (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsdup.3 b/man3/wcsdup.3 new file mode 100644 index 0000000..70d9467 --- /dev/null +++ b/man3/wcsdup.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSDUP 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsdup \- duplicate a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcsdup(const wchar_t *" s ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR wcsdup (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR wcsdup () +function is the wide-character equivalent +of the +.BR strdup (3) +function. +It allocates and returns a new wide-character string whose initial +contents is a duplicate of the wide-character string pointed to by +.IR s . +.PP +Memory for the new wide-character string is +obtained with +.BR malloc (3), +and should be freed with +.BR free (3). +.SH RETURN VALUE +On success, +.BR wcsdup () +returns a pointer to the new wide-character string. +On error, it returns NULL, with +.I errno +set to indicate the cause of the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsdup () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2008. +This function is not specified in POSIX.1-2001, +and is not widely available on other systems. +.\" present in libc5 and glibc 2.0 and later +.SH SEE ALSO +.BR strdup (3), +.BR wcscpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcslen.3 b/man3/wcslen.3 new file mode 100644 index 0000000..1a1c543 --- /dev/null +++ b/man3/wcslen.3 @@ -0,0 +1,66 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSLEN 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcslen \- determine the length of a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t wcslen(const wchar_t *" s ); +.fi +.SH DESCRIPTION +The +.BR wcslen () +function is the wide-character equivalent +of the +.BR strlen (3) +function. +It determines the length of the wide-character string pointed to +by +.IR s , +excluding the terminating null wide character (L\(aq\\0\(aq). +.SH RETURN VALUE +The +.BR wcslen () +function returns the +number of wide characters in +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcslen () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strlen (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsncasecmp.3 b/man3/wcsncasecmp.3 new file mode 100644 index 0000000..b97607f --- /dev/null +++ b/man3/wcsncasecmp.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSNCASECMP 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsncasecmp \- compare two fixed-size wide-character strings, ignoring case +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int wcsncasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR wcsncasecmp (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR wcsncasecmp () +function is the wide-character equivalent of the +.BR strncasecmp (3) +function. +It compares the wide-character string pointed to +by +.I s1 +and the wide-character string +pointed to by +.IR s2 , +but at most +.I n +wide characters from each string, ignoring case differences +.RB ( towupper (3), +.BR towlower (3)). +.SH RETURN VALUE +The +.BR wcsncasecmp () +function returns zero +if the wide-character strings at +.I s1 +and +.IR s2 , +truncated to at most length +.IR n , +are equal except +for case distinctions. +It returns a positive integer if truncated +.I s1 +is +greater than truncated +.IR s2 , +ignoring case. +It returns a negative integer +if truncated +.I s1 +is smaller than truncated +.IR s2 , +ignoring case. +.SH VERSIONS +The +.BR wcsncasecmp () +function is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsncasecmp () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2008. +This function is not specified in POSIX.1-2001, +and is not widely available on other systems. +.SH NOTES +The behavior of +.BR wcsncasecmp () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR strncasecmp (3), +.BR wcsncmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsncat.3 b/man3/wcsncat.3 new file mode 100644 index 0000000..67ab7ad --- /dev/null +++ b/man3/wcsncat.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSNCAT 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsncat \- concatenate two wide-character strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcsncat(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncat () +function is the wide-character equivalent of the +.BR strncat (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.I src +to the end of the wide-character string pointed +to by +.IR dest , +and adds a terminating null wide character (L\(aq\\0\(aq). +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least +.IR wcslen(dest) + n +1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcsncat () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsncat () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strncat (3), +.BR wcscat (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsncmp.3 b/man3/wcsncmp.3 new file mode 100644 index 0000000..5a8cff0 --- /dev/null +++ b/man3/wcsncmp.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSNCMP 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsncmp \- compare two fixed-size wide-character strings +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int wcsncmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncmp () +function is the wide-character equivalent of the +.BR strncmp (3) +function. +It compares the wide-character string pointed to by +.I s1 +and the +wide-character string pointed to by +.IR s2 , +but at most +.I n +wide +characters from each string. +In each string, the comparison extends only up +to the first occurrence of a null wide character (L\(aq\\0\(aq), if any. +.SH RETURN VALUE +The +.BR wcsncmp () +function returns zero if the wide-character strings at +.I s1 +and +.IR s2 , +truncated to at most length +.IR n , +are equal. +It returns an integer greater than zero if at the first differing position +.I i +.RI ( i +< +.IR n ), +the corresponding wide-character +.I s1[i] +is +greater than +.IR s2[i] . +It returns an integer less than zero if at the first +differing position +.I i +.RI (i +< +.IR n ), +the corresponding +wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsncmp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strncmp (3), +.BR wcsncasecmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsncpy.3 b/man3/wcsncpy.3 new file mode 100644 index 0000000..58ddee2 --- /dev/null +++ b/man3/wcsncpy.3 @@ -0,0 +1,93 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSNCPY 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsncpy \- copy a fixed-size string of wide characters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcsncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncpy () +function is the wide-character equivalent of the +.BR strncpy (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.IR src , +including the terminating null wide character (L\(aq\\0\(aq), +to the array pointed to by +.IR dest . +Exactly +.I n +wide characters are +written at +.IR dest . +If the length \fIwcslen(src)\fP is smaller than +.IR n , +the remaining wide characters in the array +pointed to by +.I dest +are filled +with null wide characters. +If the length \fIwcslen(src)\fP is greater than or equal +to +.IR n , +the string pointed to by +.I dest +will not be terminated by a null wide character. +.PP +The strings may not overlap. +.PP +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wcsncpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsncpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strncpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsnlen.3 b/man3/wcsnlen.3 new file mode 100644 index 0000000..bc45fa0 --- /dev/null +++ b/man3/wcsnlen.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSNLEN 3 2016-03-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsnlen \- determine the length of a fixed-size wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t wcsnlen(const wchar_t *" s ", size_t " maxlen ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR wcsnlen (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR wcsnlen () +function is the wide-character equivalent +of the +.BR strnlen (3) +function. +It returns the number of wide-characters in the string pointed to by +.IR s , +not including the terminating null wide character (L\(aq\\0\(aq), +but at most +.I maxlen +wide characters (note: this parameter is not a byte count). +In doing this, +.BR wcsnlen () +looks at only the first +.I maxlen +wide characters at +.I s +and never beyond +.IR s+maxlen . +.SH RETURN VALUE +The +.BR wcsnlen () +function returns +.IR wcslen(s) , +if that is less than +.IR maxlen , +or +.I maxlen +if there is no null wide character among the +first +.I maxlen +wide characters pointed to by +.IR s . +.SH VERSIONS +The +.BR wcsnlen () +function is provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsnlen () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2008. +.SH SEE ALSO +.BR strnlen (3), +.BR wcslen (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsnrtombs.3 b/man3/wcsnrtombs.3 new file mode 100644 index 0000000..f824d49 --- /dev/null +++ b/man3/wcsnrtombs.3 @@ -0,0 +1,198 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSNRTOMBS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsnrtombs \- convert a wide-character string to a multibyte string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t wcsnrtombs(char *" dest ", const wchar_t **" src ", size_t " nwc , +.BI " size_t " len ", mbstate_t *" ps ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR wcsnrtombs (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_GNU_SOURCE +.RE +.ad +.PD +.SH DESCRIPTION +The +.BR wcsnrtombs () +function is like the +.BR wcsrtombs (3) +function, +except that the number of wide characters to be converted, +starting at +.IR *src , +is limited to +.IR nwc . +.PP +If +.I dest +is not NULL, +the +.BR wcsnrtombs () +function converts +at most +.I nwc +wide characters from +the wide-character string +.I *src +to a multibyte string starting at +.IR dest . +At most +.I len +bytes are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.IR "wcrtomb(dest, *src, ps)" , +as long as this call succeeds, +and then incrementing +.I dest +by the +number of bytes written and +.I *src +by one. +The conversion can stop for three reasons: +.IP 1. 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I *src +is left pointing to the invalid wide character, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP 2. +.I nwc +wide characters have been +converted without encountering a null wide character (L\(aq\\0\(aq), +or the length limit forces a stop. +In this case, +.I *src +is left pointing +to the next wide character to be converted, and the number of bytes written +to +.I dest +is returned. +.IP 3. +The wide-character string has been completely converted, including the +terminating null wide character (which has the side effect of bringing back +.I *ps +to the initial state). +In this case, +.I *src +is set to NULL, and the number +of bytes written to +.IR dest , +excluding the terminating null byte (\(aq\\0\(aq), is +returned. +.PP +If +.IR dest +is NULL, +.I len +is ignored, +and the conversion proceeds as above, +except that the converted bytes are not written out to memory, and that +no destination length limit exists. +.PP +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcsnrtombs () +function is used instead. +.PP +The programmer must ensure that there is room for at least +.I len +bytes +at +.IR dest . +.SH RETURN VALUE +The +.BR wcsnrtombs () +function returns +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered which +could not be converted, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw29 +l l l. +Interface Attribute Value +T{ +.BR wcsnrtombs () +T} Thread safety MT-Unsafe race:wcsnrtombs/!ps +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2008. +.SH NOTES +The behavior of +.BR wcsnrtombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbsinit (3), +.BR wcsrtombs (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcspbrk.3 b/man3/wcspbrk.3 new file mode 100644 index 0000000..1fbb61c --- /dev/null +++ b/man3/wcspbrk.3 @@ -0,0 +1,75 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSPBRK 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcspbrk \- search a wide-character string for any of a set of wide characters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept ); +.fi +.SH DESCRIPTION +The +.BR wcspbrk () +function is the wide-character equivalent +of the +.BR strpbrk (3) +function. +It searches for the first occurrence in the wide-character +string pointed to by +.I wcs +of any of the +characters in the wide-character +string pointed to by +.IR accept . +.SH RETURN VALUE +The +.BR wcspbrk () +function returns a pointer to the first occurrence in +.I wcs +of any of the characters listed in +.IR accept . +If +.I wcs +contains none of these characters, NULL is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcspbrk () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strpbrk (3), +.BR wcschr (3), +.BR wcscspn (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsrchr.3 b/man3/wcsrchr.3 new file mode 100644 index 0000000..b7f9be4 --- /dev/null +++ b/man3/wcsrchr.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSRCHR 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsrchr \- search a wide character in a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR wcsrchr () +function is the wide-character equivalent +of the +.BR strrchr (3) +function. +It searches the last occurrence of +.I wc +in the wide-character +string pointed to by +.IR wcs . +.SH RETURN VALUE +The +.BR wcsrchr () +function returns a pointer to the last occurrence of +.I wc +in the wide-character string pointed to by +.IR wcs , +or NULL if +.I wc +does not occur in the string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsrchr () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strrchr (3), +.BR wcschr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsrtombs.3 b/man3/wcsrtombs.3 new file mode 100644 index 0000000..3b856d2 --- /dev/null +++ b/man3/wcsrtombs.3 @@ -0,0 +1,166 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSRTOMBS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsrtombs \- convert a wide-character string to a multibyte string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t wcsrtombs(char *" dest ", const wchar_t **" src , +.BI " size_t " len ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +the +.BR wcsrtombs () +function converts +the wide-character string +.I *src +to a multibyte string starting at +.IR dest . +At most +.I len +bytes are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.IR "wcrtomb(dest, *src, ps)" , +as long as this call succeeds, +and then incrementing +.I dest +by the +number of bytes written and +.I *src +by one. +The conversion can stop for three reasons: +.IP 1. 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I *src +is left pointing to the invalid wide character, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP 2. +The length limit forces a stop. +In this case, +.I *src +is left pointing +to the next wide character to be converted, +and the number of bytes written to +.I dest +is returned. +.IP 3. +The wide-character string has been completely converted, including the +terminating null wide character (L\(aq\\0\(aq), +which has the side effect of bringing back +.I *ps +to the initial state. +In this case, +.I *src +is set to NULL, and the number +of bytes written to +.IR dest , +excluding the terminating null byte (\(aq\\0\(aq), +is returned. +.PP +If +.IR dest +is NULL, +.I len +is ignored, +and the conversion proceeds as above, except that the converted bytes +are not written out to memory, and that +no length limit exists. +.PP +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcsrtombs () +function is used instead. +.PP +The programmer must ensure that there is room for at least +.I len +bytes +at +.IR dest . +.SH RETURN VALUE +The +.BR wcsrtombs () +function returns +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered +which could not be converted, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw28 +l l l. +Interface Attribute Value +T{ +.BR wcsrtombs () +T} Thread safety MT-Unsafe race:wcsrtombs/!ps +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR wcsrtombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbsinit (3), +.BR wcrtomb (3), +.BR wcsnrtombs (3), +.BR wcstombs (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsspn.3 b/man3/wcsspn.3 new file mode 100644 index 0000000..13e89ee --- /dev/null +++ b/man3/wcsspn.3 @@ -0,0 +1,85 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSSPN 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsspn \- advance in a wide-character string, skipping +any of a set of wide characters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t wcsspn(const wchar_t *" wcs ", const wchar_t *" accept ); +.fi +.SH DESCRIPTION +The +.BR wcsspn () +function is the wide-character equivalent of the +.BR strspn (3) +function. +It determines the length of the longest initial segment of +.I wcs +which consists entirely of wide-characters listed in +.IR accept . +In other +words, it searches for the first occurrence in the wide-character string +.I wcs +of a wide-character not contained in the wide-character string +.IR accept . +.SH RETURN VALUE +The +.BR wcsspn () +function returns the number of +wide characters in the longest +initial segment of +.I wcs +which consists entirely of wide-characters listed +in +.IR accept . +In other words, it returns the position of the first +occurrence in the wide-character string +.I wcs +of a wide-character not +contained in the wide-character string +.IR accept , +or +.I wcslen(wcs) +if there is none. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsspn () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strspn (3), +.BR wcscspn (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcsstr.3 b/man3/wcsstr.3 new file mode 100644 index 0000000..667cbb6 --- /dev/null +++ b/man3/wcsstr.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSSTR 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcsstr \- locate a substring in a wide-character string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle ); +.fi +.SH DESCRIPTION +The +.BR wcsstr () +function is the wide-character equivalent of the +.BR strstr (3) +function. +It searches for the first occurrence of the wide-character string +.I needle +(without its terminating null wide character (L\(aq\\0\(aq)) +as a substring in the wide-character string +.IR haystack . +.SH RETURN VALUE +The +.BR wcsstr () +function returns a pointer to the first occurrence of +.I needle +in +.IR haystack . +It returns NULL if +.I needle +does not occur +as a substring in +.IR haystack . +.PP +Note the special case: +If +.I needle +is the empty wide-character string, +the return value is always +.I haystack +itself. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcsstr () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR strstr (3), +.BR wcschr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcstoimax.3 b/man3/wcstoimax.3 new file mode 100644 index 0000000..8a5f943 --- /dev/null +++ b/man3/wcstoimax.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH WCSTOIMAX 3 2015-08-08 "" "Linux Programmer's Manual" +.SH NAME +wcstoimax, wcstoumax \- convert wide-character string to integer +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "intmax_t wcstoimax(const wchar_t *" nptr ", wchar_t **" endptr \ +", int " base ); +.BI "uintmax_t wcstoumax(const wchar_t *" nptr ", wchar_t **" endptr \ +", int " base ); +.fi +.SH DESCRIPTION +These functions are just like +.BR wcstol (3) +and +.BR wcstoul (3), +except that they return a value of type +.I intmax_t +and +.IR uintmax_t , +respectively. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR wcstoimax (), +.BR wcstoumax () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR imaxabs (3), +.BR imaxdiv (3), +.BR strtoimax (3), +.BR strtoumax (3), +.\" FIXME . the pages referred to by the following xrefs are not yet written +.BR wcstol (3), +.BR wcstoul (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcstok.3 b/man3/wcstok.3 new file mode 100644 index 0000000..fe2d151 --- /dev/null +++ b/man3/wcstok.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSTOK 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcstok \- split wide-character string into tokens +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wcstok(wchar_t *" wcs ", const wchar_t *" delim \ +", wchar_t **" ptr ); +.fi +.SH DESCRIPTION +The +.BR wcstok () +function is the wide-character equivalent of the +.BR strtok (3) +function, +with an added argument to make it multithread-safe. +It can be used +to split a wide-character string +.I wcs +into tokens, where a token is +defined as a substring not containing any wide-characters from +.IR delim . +.PP +The search starts at +.IR wcs , +if +.I wcs +is not NULL, +or at +.IR *ptr , +if +.I wcs +is NULL. +First, any delimiter wide-characters are skipped, that is, the +pointer is advanced beyond any wide-characters which occur in +.IR delim . +If the end of the wide-character string is now +reached, +.BR wcstok () +returns NULL, to indicate that no tokens +were found, and stores an appropriate value in +.IR *ptr , +so that subsequent calls to +.BR wcstok () +will continue to return NULL. +Otherwise, the +.BR wcstok () +function recognizes the beginning of a token +and returns a pointer to it, but before doing that, it zero-terminates the +token by replacing the next wide-character which occurs in +.I delim +with +a null wide character (L\(aq\\0\(aq), +and it updates +.I *ptr +so that subsequent calls will +continue searching after the end of recognized token. +.SH RETURN VALUE +The +.BR wcstok () +function returns a pointer to the next token, +or NULL if no further token was found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcstok () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The original +.I wcs +wide-character string is destructively modified during +the operation. +.SH EXAMPLE +The following code loops over the tokens contained in a wide-character string. +.PP +.EX +wchar_t *wcs = ...; +wchar_t *token; +wchar_t *state; +for (token = wcstok(wcs, " \\t\\n", &state); + token != NULL; + token = wcstok(NULL, " \\t\\n", &state)) { + ... +} +.EE +.SH SEE ALSO +.BR strtok (3), +.BR wcschr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcstombs.3 b/man3/wcstombs.3 new file mode 100644 index 0000000..66f0b1e --- /dev/null +++ b/man3/wcstombs.3 @@ -0,0 +1,130 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCSTOMBS 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcstombs \- convert a wide-character string to a multibyte string +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t wcstombs(char *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, the +.BR wcstombs () +function converts +the wide-character string +.I src +to a multibyte string starting at +.IR dest . +At most +.I n +bytes are written to +.IR dest . +The sequence of characters placed in +.IR dest +begins in the initial shift state. +The conversion can stop for three reasons: +.IP 1. 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I (size_t)\ \-1 +is returned. +.IP 2. +The length limit forces a stop. +In this case, the number of bytes written to +.I dest +is returned, but the shift state at this point is lost. +.IP 3. +The wide-character string has been completely converted, including the +terminating null wide character (L\(aq\\0\(aq). +In this case, the conversion ends in the initial shift state. +The number of bytes written to +.IR dest , +excluding the terminating null byte (\(aq\\0\(aq), is returned. +.PP +The programmer must ensure that there is room for at least +.I n +bytes +at +.IR dest . +.PP +If +.IR dest +is NULL, +.I n +is ignored, and the conversion proceeds as +above, except that the converted bytes are not written out to memory, +and no length limit exists. +.PP +In order to avoid the case 2 above, the programmer should make sure +.I n +is greater than or equal to +.IR "wcstombs(NULL,src,0)+1" . +.SH RETURN VALUE +The +.BR wcstombs () +function returns the number of bytes that make up the +converted part of a multibyte sequence, +not including the terminating null byte. +If a wide character was encountered which could not be +converted, +.I (size_t)\ \-1 +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcstombs () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR wcstombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +The function +.BR wcsrtombs (3) +provides a better interface to the same functionality. +.SH SEE ALSO +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcsrtombs (3) +.BR wctomb (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcstoumax.3 b/man3/wcstoumax.3 new file mode 100644 index 0000000..f3aa5d2 --- /dev/null +++ b/man3/wcstoumax.3 @@ -0,0 +1 @@ +.so man3/wcstoimax.3 diff --git a/man3/wcswidth.3 b/man3/wcswidth.3 new file mode 100644 index 0000000..7809eff --- /dev/null +++ b/man3/wcswidth.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCSWIDTH 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wcswidth \- determine columns needed for a fixed-size wide-character string +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int wcswidth(const wchar_t *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcswidth () +function returns the +number of columns needed to represent +the wide-character string pointed to by +.IR s , +but at most +.I n +wide +characters. +If a nonprintable wide character occurs among these characters, +\-1 is returned. +.SH RETURN VALUE +The +.BR wcswidth () +function +returns the number of column positions for the +wide-character string +.IR s , +truncated to at most length +.IR n . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcswidth () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +The behavior of +.BR wcswidth () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswprint (3), +.BR wcwidth (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wctob.3 b/man3/wctob.3 new file mode 100644 index 0000000..6a6ea85 --- /dev/null +++ b/man3/wctob.3 @@ -0,0 +1,93 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCTOB 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wctob \- try to represent a wide character as a single byte +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int wctob(wint_t " c ); +.fi +.SH DESCRIPTION +The +.BR wctob () +function tests whether +the multibyte representation of the +wide character +.IR c , +starting in the initial state, consists of a single +byte. +If so, it is returned as an +.IR "unsigned char" . +.PP +Never use this function. +It cannot help you in writing internationalized +programs. +Internationalized programs must never distinguish single-byte and +multibyte characters. +.SH RETURN VALUE +The +.BR wctob () +function returns the single-byte representation of +.IR c , +if it exists, of +.B EOF +otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wctob () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR wctob () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +This function should never be used. +Internationalized programs must never +distinguish single-byte and multibyte characters. +Use either +.BR wctomb (3) +or the thread-safe +.BR wcrtomb (3) +instead. +.SH SEE ALSO +.BR btowc (3), +.BR wcrtomb (3), +.BR wctomb (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wctomb.3 b/man3/wctomb.3 new file mode 100644 index 0000000..b6ecd0b --- /dev/null +++ b/man3/wctomb.3 @@ -0,0 +1,125 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCTOMB 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wctomb \- convert a wide character to a multibyte sequence +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int wctomb(char *" s ", wchar_t " wc ); +.fi +.SH DESCRIPTION +If +.I s +is not NULL, +the +.BR wctomb () +function converts the wide character +.I wc +to its multibyte representation and stores it at the beginning of +the character array pointed to by +.IR s . +It updates the shift state, which +is stored in a static anonymous variable +known only to the +.BR wctomb () +function, +and returns the length of said multibyte representation, +that is, the number of +bytes written at +.IR s . +.PP +The programmer must ensure that there is +room for at least +.B MB_CUR_MAX +bytes at +.IR s . +.PP +If +.I s +is NULL, the +.BR wctomb () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, known only to this function, +to the initial state, and +returns nonzero if the encoding has nontrivial shift state, +or zero if the encoding is stateless. +.SH RETURN VALUE +If +.I s +is not NULL, the +.BR wctomb () +function +returns the number of bytes +that have been written to the byte array at +.IR s . +If +.I wc +can not be +represented as a multibyte sequence (according +to the current locale), \-1 is returned. +.PP +If +.I s +is NULL, the +.BR wctomb () +function returns nonzero if the +encoding has nontrivial shift state, or zero if the encoding is stateless. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wctomb () +T} Thread safety MT-Unsafe race +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR wctomb () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +The function +.BR wcrtomb (3) +provides +a better interface to the same functionality. +.SH SEE ALSO +.BR MB_CUR_MAX (3), +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcrtomb (3), +.BR wcstombs (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wctrans.3 b/man3/wctrans.3 new file mode 100644 index 0000000..d8c1b5b --- /dev/null +++ b/man3/wctrans.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCTRANS 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wctrans \- wide-character translation mapping +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wctrans_t wctrans(const char *" name ); +.fi +.SH DESCRIPTION +The +.I wctrans_t +type represents a mapping +which can map a wide character to +another wide character. +Its nature is implementation-dependent, but the special +value +.IR "(wctrans_t)\ 0" +denotes an invalid mapping. +Nonzero +.I wctrans_t +values can be passed to the +.BR towctrans (3) +function to actually perform +the wide-character mapping. +.PP +The +.BR wctrans () +function returns a mapping, given by its name. +The set of +valid names depends on the +.B LC_CTYPE +category of the current locale, but the +following names are valid in all locales. +.PP +.nf + "tolower" \- realizes the \fBtolower\fP(3) mapping + "toupper" \- realizes the \fBtoupper\fP(3) mapping +.fi +.SH RETURN VALUE +The +.BR wctrans () +function returns a mapping descriptor if the +.I name +is valid. +Otherwise, it returns +.IR "(wctrans_t)\ 0" . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wctrans () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR wctrans () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR towctrans (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wctype.3 b/man3/wctype.3 new file mode 100644 index 0000000..5d717e6 --- /dev/null +++ b/man3/wctype.3 @@ -0,0 +1,106 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCTYPE 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wctype \- wide-character classification +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wctype_t wctype(const char *" name ); +.fi +.SH DESCRIPTION +The +.I wctype_t +type represents a property which a wide character may or +may not have. +In other words, it represents a class of wide characters. +This type's nature is implementation-dependent, but the special value +.I "(wctype_t) 0" +denotes an invalid property. +Nonzero +.I wctype_t +values +can be passed to the +.BR iswctype (3) +function +to actually test whether a given +wide character has the property. +.PP +The +.BR wctype () +function returns a property, given by its name. +The set of +valid names depends on the +.B LC_CTYPE +category of the current locale, but the +following names are valid in all locales. +.PP +.nf + "alnum" \- realizes the \fBisalnum\fP(3) classification function + "alpha" \- realizes the \fBisalpha\fP(3) classification function + "blank" \- realizes the \fBisblank\fP(3) classification function + "cntrl" \- realizes the \fBiscntrl\fP(3) classification function + "digit" \- realizes the \fBisdigit\fP(3) classification function + "graph" \- realizes the \fBisgraph\fP(3) classification function + "lower" \- realizes the \fBislower\fP(3) classification function + "print" \- realizes the \fBisprint\fP(3) classification function + "punct" \- realizes the \fBispunct\fP(3) classification function + "space" \- realizes the \fBisspace\fP(3) classification function + "upper" \- realizes the \fBisupper\fP(3) classification function + "xdigit" \- realizes the \fBisxdigit\fP(3) classification function +.fi +.SH RETURN VALUE +The +.BR wctype () +function returns a property descriptor +if the +.I name +is valid. +Otherwise, it returns +.IR "(wctype_t) 0" . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wctype () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR wctype () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswctype (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wcwidth.3 b/man3/wcwidth.3 new file mode 100644 index 0000000..5ebd1a0 --- /dev/null +++ b/man3/wcwidth.3 @@ -0,0 +1,83 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WCWIDTH 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wcwidth \- determine columns needed for a wide character +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.PP +.BI "int wcwidth(wchar_t " c ); +.fi +.SH DESCRIPTION +The +.BR wcwidth () +function returns the number of columns +needed to represent the wide character +.IR c . +If +.I c +is a printable wide character, the value +is at least 0. +If +.I c +is null wide character (L\(aq\\0\(aq), the value is 0. +Otherwise, \-1 is returned. +.SH RETURN VALUE +The +.BR wcwidth () +function returns the number of +column positions for +.IR c . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wcwidth () +T} Thread safety MT-Safe locale +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.PP +Note that glibc before 2.2.5 used the prototype +.PP +.nf +.BI "int wcwidth(wint_t " c ); +.fi +.SH NOTES +The behavior of +.BR wcwidth () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswprint (3), +.BR wcswidth (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wmemchr.3 b/man3/wmemchr.3 new file mode 100644 index 0000000..a6d9c5d --- /dev/null +++ b/man3/wmemchr.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WMEMCHR 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemchr \- search a wide character in a wide-character array +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wmemchr(const wchar_t *" s ", wchar_t " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemchr () +function is the wide-character equivalent of the +.BR memchr (3) +function. +It searches the +.IR n +wide characters starting at +.I s +for +the first occurrence of the wide character +.IR c . +.SH RETURN VALUE +The +.BR wmemchr () +function returns a pointer to the first occurrence of +.I c +among the +.IR n +wide characters starting at +.IR s , +or NULL if +.I c +does +not occur among these. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wmemchr () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR memchr (3), +.BR wcschr (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wmemcmp.3 b/man3/wmemcmp.3 new file mode 100644 index 0000000..8684dcd --- /dev/null +++ b/man3/wmemcmp.3 @@ -0,0 +1,95 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH WMEMCMP 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemcmp \- compare two arrays of wide-characters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int wmemcmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemcmp () +function is the wide-character equivalent of the +.BR memcmp (3) +function. +It compares the +.IR n +wide-characters starting at +.I s1 +and the +.I n +wide-characters starting at +.IR s2 . +.SH RETURN VALUE +The +.BR wmemcmp () +function returns +zero if the wide-character arrays of size +.I n +at +.IR s1 +and +.I s2 +are equal. +It returns an integer greater than +zero if at the first differing position +.I i +.RI ( i " <" +.IR n ), +the +corresponding wide-character +.I s1[i] +is greater than +.IR s2[i] . +It returns an integer less than zero if +at the first differing position +.I i +.RI ( i +< +.IR n ), +the corresponding +wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wmemcmp () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR memcmp (3), +.BR wcscmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wmemcpy.3 b/man3/wmemcpy.3 new file mode 100644 index 0000000..4edca58 --- /dev/null +++ b/man3/wmemcpy.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WMEMCPY 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemcpy \- copy an array of wide-characters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wmemcpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemcpy () +function is the wide-character equivalent of the +.BR memcpy (3) +function. +It copies +.I n +wide characters from the array starting at +.I src +to the array starting at +.IR dest . +.PP +The arrays may not overlap; use +.BR wmemmove (3) +to copy between overlapping +arrays. +.PP +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wmemcpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wmemcpy () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR memcpy (3), +.BR wcscpy (3), +.BR wmemmove (3), +.BR wmempcpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wmemmove.3 b/man3/wmemmove.3 new file mode 100644 index 0000000..5b6e493 --- /dev/null +++ b/man3/wmemmove.3 @@ -0,0 +1,75 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WMEMMOVE 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemmove \- copy an array of wide-characters +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wmemmove(wchar_t *" dest ", const wchar_t *" src ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemmove () +function is the wide-character equivalent of the +.BR memmove (3) +function. +It copies +.I n +wide characters from the array +starting at +.I src +to the array starting at +.IR dest . +The arrays may +overlap. +.PP +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wmemmove () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wmemmove () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR memmove (3), +.BR wmemcpy (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wmempcpy.3 b/man3/wmempcpy.3 new file mode 100644 index 0000000..26750cb --- /dev/null +++ b/man3/wmempcpy.3 @@ -0,0 +1 @@ +.so man3/mempcpy.3 diff --git a/man3/wmemset.3 b/man3/wmemset.3 new file mode 100644 index 0000000..2a3caad --- /dev/null +++ b/man3/wmemset.3 @@ -0,0 +1,67 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WMEMSET 3 2015-08-08 "GNU" "Linux Programmer's Manual" +.SH NAME +wmemset \- fill an array of wide-characters with a constant wide character +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "wchar_t *wmemset(wchar_t *" wcs ", wchar_t " wc ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemset () +function is the wide-character equivalent of the +.BR memset (3) +function. +It fills the array of +.I n +wide-characters starting at +.I wcs +with +.I n +copies of the wide character +.IR wc . +.SH RETURN VALUE +.BR wmemset () +returns +.IR wcs . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR wmemset () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH SEE ALSO +.BR memset (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wordexp.3 b/man3/wordexp.3 new file mode 100644 index 0000000..6641868 --- /dev/null +++ b/man3/wordexp.3 @@ -0,0 +1,258 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH WORDEXP 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +wordexp, wordfree \- perform word expansion like a posix-shell +.SH SYNOPSIS +.B "#include " +.PP +.BI "int wordexp(const char *" s ", wordexp_t *" p ", int " flags ); +.PP +.BI "void wordfree(wordexp_t *" p ); +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.BR wordexp (), +.BR wordfree (): +_XOPEN_SOURCE +.SH DESCRIPTION +The function +.BR wordexp () +performs a shell-like expansion of the string +.I s +and returns the result in the structure pointed to by +.IR p . +The data type +.I wordexp_t +is a structure that at least has the fields +.IR we_wordc , +.IR we_wordv , +and +.IR we_offs . +The field +.I we_wordc +is a +.I size_t +that gives the number of words in the expansion of +.IR s . +The field +.I we_wordv +is a +.I "char\ **" +that points to the array of words found. +The field +.I we_offs +of type +.I size_t +is sometimes (depending on +.IR flags , +see below) used to indicate the number of initial elements in the +.I we_wordv +array that should be filled with NULLs. +.PP +The function +.BR wordfree () +frees the allocated memory again. +More precisely, it does not free +its argument, but it frees the array +.I we_wordv +and the strings that points to. +.SS The string argument +Since the expansion is the same as the expansion by the shell (see +.BR sh (1)) +of the parameters to a command, the string +.I s +must not contain characters that would be illegal in shell command +parameters. +In particular, there must not be any unescaped +newline or |, &, ;, <, >, (, ), {, } characters +outside a command substitution or parameter substitution context. +.PP +If the argument +.I s +contains a word that starts with an unquoted comment character #, +then it is unspecified whether that word and all following words +are ignored, or the # is treated as a non-comment character. +.SS The expansion +The expansion done consists of the following stages: +tilde expansion (replacing ~user by user's home directory), +variable substitution (replacing $FOO by the value of the environment +variable FOO), command substitution (replacing $(command) or \`command\` +by the output of command), arithmetic expansion, field splitting, +wildcard expansion, quote removal. +.PP +The result of expansion of special parameters +($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified. +.PP +Field splitting is done using the environment variable $IFS. +If it is not set, the field separators are space, tab and newline. +.SS The output array +The array +.I we_wordv +contains the words found, followed by a NULL. +.SS The flags argument +The +.I flag +argument is a bitwise inclusive OR of the following values: +.TP +.B WRDE_APPEND +Append the words found to the array resulting from a previous call. +.TP +.B WRDE_DOOFFS +Insert +.I we_offs +initial NULLs in the array +.IR we_wordv . +(These are not counted in the returned +.IR we_wordc .) +.TP +.B WRDE_NOCMD +Don't do command substitution. +.TP +.B WRDE_REUSE +The argument +.I p +resulted from a previous call to +.BR wordexp (), +and +.BR wordfree () +was not called. +Reuse the allocated storage. +.TP +.B WRDE_SHOWERR +Normally during command substitution +.I stderr +is redirected to +.IR /dev/null . +This flag specifies that +.I stderr +is not to be redirected. +.TP +.B WRDE_UNDEF +Consider it an error if an undefined shell variable is expanded. +.SH RETURN VALUE +In case of success 0 is returned. +In case of error +one of the following five values is returned. +.TP +.B WRDE_BADCHAR +Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }. +.TP +.B WRDE_BADVAL +An undefined shell variable was referenced, and the +.B WRDE_UNDEF +flag +told us to consider this an error. +.TP +.B WRDE_CMDSUB +Command substitution requested, but the +.B WRDE_NOCMD +flag told us to consider this an error. +.TP +.B WRDE_NOSPACE +Out of memory. +.TP +.B WRDE_SYNTAX +Shell syntax error, such as unbalanced parentheses or +unmatched quotes. +.SH VERSIONS +.BR wordexp () +and +.BR wordfree () +are provided in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbw30 +l l l. +Interface Attribute Value +T{ +.BR wordexp () +T} Thread safety T{ +MT-Unsafe race:utent const:env +.br +env sig:ALRM timer locale +T} +T{ +.BR wordfree () +T} Thread safety MT-Safe +.TE +.sp 1 +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR wordexp () +calls those functions, +so we use race:utent to remind users. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH EXAMPLE +The output of the following example program +is approximately that of "ls [a-c]*.c". +.PP +.EX +#include +#include +#include + +int +main(int argc, char **argv) +{ + wordexp_t p; + char **w; + int i; + + wordexp("[a\-c]*.c", &p, 0); + w = p.we_wordv; + for (i = 0; i < p.we_wordc; i++) + printf("%s\en", w[i]); + wordfree(&p); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR fnmatch (3), +.BR glob (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/wordfree.3 b/man3/wordfree.3 new file mode 100644 index 0000000..f0035e0 --- /dev/null +++ b/man3/wordfree.3 @@ -0,0 +1 @@ +.so man3/wordexp.3 diff --git a/man3/wprintf.3 b/man3/wprintf.3 new file mode 100644 index 0000000..c708f59 --- /dev/null +++ b/man3/wprintf.3 @@ -0,0 +1,283 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WPRINTF 3 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted +wide-character output conversion +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.BI "int wprintf(const wchar_t *" format ", ...);" +.BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);" +.BI "int swprintf(wchar_t *" wcs ", size_t " maxlen , +.BI " const wchar_t *" format ", ...);" +.PP +.BI "int vwprintf(const wchar_t *" format ", va_list " args ); +.BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args ); +.BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen , +.BI " const wchar_t *" format ", va_list " args ); +.fi +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +All functions shown above: +.RS 4 +.\" .BR wprintf (), +.\" .BR fwprintf (), +.\" .BR swprintf (), +.\" .BR vwprintf (), +.\" .BR vfwprintf (), +.\" .BR vswprintf (): +_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE || +.br +_POSIX_C_SOURCE\ >=\ 200112L +.RE +.ad +.SH DESCRIPTION +The +.BR wprintf () +family of functions is +the wide-character equivalent of the +.BR printf (3) +family of functions. +It performs formatted output of wide +characters. +.PP +The +.BR wprintf () +and +.BR vwprintf () +functions +perform wide-character output to +.IR stdout . +.I stdout +must not be byte oriented; see +.BR fwide (3) +for more information. +.PP +The +.BR fwprintf () +and +.BR vfwprintf () +functions +perform wide-character output to +.IR stream . +.I stream +must not be byte oriented; see +.BR fwide (3) +for more information. +.PP +The +.BR swprintf () +and +.BR vswprintf () +functions +perform wide-character output +to an array of wide characters. +The programmer must ensure that there is +room for at least +.I maxlen +wide +characters at +.IR wcs . +.PP +These functions are like +the +.BR printf (3), +.BR vprintf (3), +.BR fprintf (3), +.BR vfprintf (3), +.BR sprintf (3), +.BR vsprintf (3) +functions except for the +following differences: +.TP +.B \(bu +The +.I format +string is a wide-character string. +.TP +.B \(bu +The output consists of wide characters, not bytes. +.TP +.B \(bu +.BR swprintf () +and +.BR vswprintf () +take a +.I maxlen +argument, +.BR sprintf (3) +and +.BR vsprintf (3) +do not. +.RB ( snprintf (3) +and +.BR vsnprintf (3) +take a +.I maxlen +argument, but these functions do not return \-1 upon +buffer overflow on Linux.) +.PP +The treatment of the conversion characters +.BR c +and +.B s +is different: +.TP +.B c +If no +.B l +modifier is present, the +.I int +argument is converted to a wide character by a call to the +.BR btowc (3) +function, and the resulting wide character is written. +If an +.B l +modifier is present, the +.I wint_t +(wide character) argument is written. +.TP +.B s +If no +.B l +modifier is present: the +.I "const\ char\ *" +argument is expected to be a pointer to an array of character type +(pointer to a string) containing a multibyte character sequence beginning +in the initial shift state. +Characters from the array are converted to +wide characters (each by a call to the +.BR mbrtowc (3) +function with a conversion state starting in the initial state before +the first byte). +The resulting wide characters are written up to +(but not including) the terminating null wide character (L\(aq\\0\(aq). +If a precision is +specified, no more wide characters than the number specified are written. +Note that the precision determines the number of +.I wide characters +written, not the number of +.I bytes +or +.IR "screen positions" . +The array must contain a terminating null byte (\(aq\\0\(aq), +unless a precision is given +and it is so small that the number of converted wide characters reaches it +before the end of the array is reached. +If an +.B l +modifier is present: the +.I "const\ wchar_t\ *" +argument is expected to be a pointer to an array of wide characters. +Wide characters from the array are written up to (but not including) a +terminating null wide character. +If a precision is specified, no more than +the number specified are written. +The array must contain a terminating null +wide character, unless a precision is given and it is smaller than or equal +to the number of wide characters in the array. +.SH RETURN VALUE +The functions return the number of wide characters written, excluding the +terminating null wide character in +case of the functions +.BR swprintf () +and +.BR vswprintf (). +They return \-1 when an error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw24 lb lb +l l l. +Interface Attribute Value +T{ +.BR wprintf (), +.BR fwprintf (), +.br +.BR swprintf (), +.BR vwprintf (), +.br +.BR vfwprintf (), +.BR vswprintf () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008, C99. +.SH NOTES +The behavior of +.BR wprintf () +et al. depends +on the +.B LC_CTYPE +category of the +current locale. +.PP +If the +.I format +string contains non-ASCII wide characters, the program +will work correctly only if the +.B LC_CTYPE +category of the current locale at +run time is the same as the +.B LC_CTYPE +category of the current locale at +compile time. +This is because the +.I wchar_t +representation is platform- and locale-dependent. +(The glibc represents +wide characters using their Unicode (ISO-10646) code point, but other +platforms don't do this. +Also, the use of C99 universal character names +of the form \\unnnn does not solve this problem.) +Therefore, in +internationalized programs, the +.I format +string should consist of ASCII +wide characters only, or should be constructed at run time in an +internationalized way (e.g., using +.BR gettext (3) +or +.BR iconv (3), +followed by +.BR mbstowcs (3)). +.SH SEE ALSO +.BR fprintf (3), +.BR fputwc (3), +.BR fwide (3), +.BR printf (3), +.BR snprintf (3) +.\" .BR wscanf (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/xcrypt.3 b/man3/xcrypt.3 new file mode 100644 index 0000000..855b1eb --- /dev/null +++ b/man3/xcrypt.3 @@ -0,0 +1,96 @@ +.\" Copyright 2003 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.\" this is the 3rd type of interface for cryptographic routines +.\" 1. encrypt() expects a bit field +.\" 2. cbc_crypt() byte values +.\" 3. xencrypt() a hexstring +.\" to bad to be true :( +.\" +.TH XCRYPT 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +xencrypt, xdecrypt, passwd2des \- RFS password encryption +.SH SYNOPSIS +.B "#include " +.PP +.BI "void passwd2des(char " *passwd ", char *" key ");" +.PP +.BI "int xencrypt(char *" secret ", char *" passwd ");" +.PP +.BI "int xdecrypt(char *" secret ", char *" passwd ");" +.SH DESCRIPTION +The function +.BR passwd2des () +takes a character string +.I passwd +of arbitrary length and fills a character array +.I key +of length 8. +The array +.I key +is suitable for use as DES key. +It has odd parity set in bit 0 of each byte. +Both other functions described here use this function to turn their +argument +.I passwd +into a DES key. +.PP +The +.BR xencrypt () +function takes the ASCII character string +.I secret +given in hex, +.\" (over the alphabet 0123456789abcdefABCDEF), +which must have a length that is a multiple of 16, +encrypts it using the DES key derived from +.I passwd +by +.BR passwd2des (), +and outputs the result again in +.I secret +as a hex string +.\" (over the alphabet 0123456789abcdef) +of the same length. +.PP +The +.BR xdecrypt () +function performs the converse operation. +.SH RETURN VALUE +The functions +.BR xencrypt () +and +.BR xdecrypt () +return 1 on success and 0 on error. +.SH VERSIONS +These functions are available in glibc since version 2.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw37 lb lb +l l l. +Interface Attribute Value +T{ +.BR passwd2des (), +.BR xencrypt (), +.BR xdecrypt () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH BUGS +The prototypes are missing from the abovementioned include file. +.SH SEE ALSO +.BR cbc_crypt (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/xdecrypt.3 b/man3/xdecrypt.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man3/xdecrypt.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man3/xdr.3 b/man3/xdr.3 new file mode 100644 index 0000000..acf30e6 --- /dev/null +++ b/man3/xdr.3 @@ -0,0 +1,631 @@ +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI +.\" +.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax +.\" +.TH XDR 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +xdr \- library routines for external data representation +.SH SYNOPSIS AND DESCRIPTION +.PP +These routines allow C programmers to describe +arbitrary data structures in a machine-independent fashion. +Data for remote procedure calls are transmitted using these +routines. +.PP +The prototypes below are declared in +.I +and make use of the following types: +.PP +.in +4n +.EX +.BI "typedef int " bool_t ; +.PP +.BI "typedef bool_t (*" xdrproc_t ") (XDR *, void *,...);" +.EE +.in +.PP +For the declaration of the +.I XDR +type, see +.IR . +.PP +.nf +.BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep , +.BI " unsigned int " maxsize ", unsigned int " elsize , +.BI " xdrproc_t " elproc ); +.fi +.IP +A filter primitive that translates between variable-length arrays +and their corresponding external representations. +The argument +.I arrp +is the address of the pointer to the array, while +.I sizep +is the address of the element count of the array; +this element count cannot exceed +.IR maxsize . +The argument +.I elsize +is the +.I sizeof +each of the array's elements, and +.I elproc +is an XDR filter that translates between +the array elements' C form, and their external +representation. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp ); +.fi +.IP +A filter primitive that translates between booleans (C +integers) +and their external representations. +When encoding data, this +filter produces values of either one or zero. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep , +.BI " unsigned int " maxsize ); +.fi +.IP +A filter primitive that translates between counted byte +strings and their external representations. +The argument +.I sp +is the address of the string pointer. +The length of the +string is located at address +.IR sizep ; +strings cannot be longer than +.IR maxsize . +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_char(XDR *" xdrs ", char *" cp ); +.fi +.IP +A filter primitive that translates between C characters +and their external representations. +This routine returns one if it succeeds, zero otherwise. +Note: encoded characters are not packed, and occupy 4 bytes each. +For arrays of characters, it is worthwhile to +consider +.BR xdr_bytes (), +.BR xdr_opaque () +or +.BR xdr_string (). +.PP +.nf +.BI "void xdr_destroy(XDR *" xdrs ); +.fi +.IP +A macro that invokes the destroy routine associated with the XDR stream, +.IR xdrs . +Destruction usually involves freeing private data structures +associated with the stream. +Using +.I xdrs +after invoking +.BR xdr_destroy () +is undefined. +.PP +.nf +.BI "bool_t xdr_double(XDR *" xdrs ", double *" dp ); +.fi +.IP +A filter primitive that translates between C +.I double +precision numbers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep ); +.fi +.IP +A filter primitive that translates between C +.IR enum s +(actually integers) and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_float(XDR *" xdrs ", float *" fp ); +.fi +.IP +A filter primitive that translates between C +.IR float s +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "void xdr_free(xdrproc_t " proc ", char *" objp ); +.fi +.IP +Generic freeing routine. +The first argument is the XDR routine for the object being freed. +The second argument is a pointer to the object itself. +Note: the pointer passed to this routine is +.I not +freed, but what it points to +.I is +freed (recursively). +.PP +.nf +.BI "unsigned int xdr_getpos(XDR *" xdrs ); +.fi +.IP +A macro that invokes the get-position routine +associated with the XDR stream, +.IR xdrs . +The routine returns an unsigned integer, +which indicates the position of the XDR byte stream. +A desirable feature of XDR +streams is that simple arithmetic works with this number, +although the XDR stream instances need not guarantee this. +.PP +.nf +.BI "long *xdr_inline(XDR *" xdrs ", int " len ); +.fi +.IP +A macro that invokes the inline routine associated with the XDR stream, +.IR xdrs . +The routine returns a pointer +to a contiguous piece of the stream's buffer; +.I len +is the byte length of the desired buffer. +Note: pointer is cast to +.IR "long\ *" . +.IP +Warning: +.BR xdr_inline () +may return NULL (0) +if it cannot allocate a contiguous piece of a buffer. +Therefore the behavior may vary among stream instances; +it exists for the sake of efficiency. +.PP +.nf +.BI "bool_t xdr_int(XDR *" xdrs ", int *" ip ); +.fi +.IP +A filter primitive that translates between C integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_long(XDR *" xdrs ", long *" lp ); +.fi +.IP +A filter primitive that translates between C +.I long +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size , +.BI " enum xdr_op " op ); +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The stream's data is written to, or read from, +a chunk of memory at location +.I addr +whose length is no more than +.I size +bytes long. +The +.I op +determines the direction of the XDR stream (either +.BR XDR_ENCODE , +.BR XDR_DECODE , +or +.BR XDR_FREE ). +.PP +.nf +.BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt ); +.fi +.IP +A filter primitive that translates between fixed size opaque data +and its external representation. +The argument +.I cp +is the address of the opaque object, and +.I cnt +is its size in bytes. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp , +.BI " unsigned int " objsize ", xdrproc_t " xdrobj ); +.fi +.IP +Like +.BR xdr_reference () +except that it serializes null pointers, whereas +.BR xdr_reference () +does not. +Thus, +.BR xdr_pointer () +can represent +recursive data structures, such as binary trees or +linked lists. +.PP +.nf +.BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize , +.BI " unsigned int " recvsize ", char *" handle , +.BI " int (*" readit ") (char *, char *, int)," +.BI " int (*" writeit ") (char *, char *, int));" +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The stream's data is written to a buffer of size +.IR sendsize ; +a value of zero indicates the system should use a suitable default. +The stream's data is read from a buffer of size +.IR recvsize ; +it too can be set to a suitable default by passing a zero value. +When a stream's output buffer is full, +.I writeit +is called. +Similarly, when a stream's input buffer is empty, +.I readit +is called. +The behavior of these two routines is similar to +the system calls +.BR read (2) +and +.BR write (2), +except that +.I handle +is passed to the former routines as the first argument. +Note: the XDR stream's +.I op +field must be set by the caller. +.IP +Warning: to read from an XDR stream created by this API, +you'll need to call +.BR xdrrec_skiprecord () +first before calling any other XDR APIs. +This inserts additional bytes in the stream to provide +record boundary information. +Also, XDR streams created with different +.BR xdr*_create +APIs are not compatible for the same reason. +.PP +.nf +.BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow ); +.fi +.IP +This routine can be invoked only on streams created by +.BR xdrrec_create (). +The data in the output buffer is marked as a completed record, +and the output buffer is optionally written out if +.I sendnow +is nonzero. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdrrec_eof(XDR *" xdrs ); +.fi +.IP +This routine can be invoked only on streams created by +.BR xdrrec_create (). +After consuming the rest of the current record in the stream, +this routine returns one if the stream has no more input, +zero otherwise. +.PP +.nf +.BI "bool_t xdrrec_skiprecord(XDR *" xdrs ); +.fi +.IP +This routine can be invoked only on +streams created by +.BR xdrrec_create (). +It tells the XDR implementation that the rest of the current record +in the stream's input buffer should be discarded. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size , +.BI " xdrproc_t " proc ); +.fi +.IP +A primitive that provides pointer chasing within structures. +The argument +.I pp +is the address of the pointer; +.I size +is the +.I sizeof +the structure that +.I *pp +points to; and +.I proc +is an XDR procedure that filters the structure +between its C form and its external representation. +This routine returns one if it succeeds, zero otherwise. +.IP +Warning: this routine does not understand null pointers. +Use +.BR xdr_pointer () +instead. +.PP +.nf +.BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos ); +.fi +.IP +A macro that invokes the set position routine associated with +the XDR stream +.IR xdrs . +The argument +.I pos +is a position value obtained from +.BR xdr_getpos (). +This routine returns one if the XDR stream could be repositioned, +and zero otherwise. +.IP +Warning: it is difficult to reposition some types of XDR +streams, so this routine may fail with one +type of stream and succeed with another. +.PP +.nf +.BI "bool_t xdr_short(XDR *" xdrs ", short *" sp ); +.fi +.IP +A filter primitive that translates between C +.I short +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op ); +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The XDR stream data is written to, or read from, the +.I stdio +stream +.IR file . +The argument +.I op +determines the direction of the XDR stream (either +.BR XDR_ENCODE , +.BR XDR_DECODE , +or +.BR XDR_FREE ). +.IP +Warning: the destroy routine associated with such XDR streams calls +.BR fflush (3) +on the +.I file +stream, but never +.BR fclose (3). +.PP +.nf +.BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize ); +.fi +.IP +A filter primitive that translates between C strings and +their corresponding external representations. +Strings cannot be longer than +.IR maxsize . +Note: +.I sp +is the address of the string's pointer. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp ); +.fi +.IP +A filter primitive that translates between +.I unsigned +C characters and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned *" up ); +.fi +.IP +A filter primitive that translates between C +.I unsigned +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp ); +.fi +.IP +A filter primitive that translates between C +.I "unsigned long" +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp ); +.fi +.IP +A filter primitive that translates between C +.I "unsigned short" +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_union(XDR *" xdrs ", int *" dscmp ", char *" unp , +.BI " struct xdr_discrim *" choices , +.BI " xdrproc_t " defaultarm "); /* may equal NULL */" +.fi +.IP +A filter primitive that translates between a discriminated C +.I union +and its corresponding external representation. +It first +translates the discriminant of the union located at +.IR dscmp . +This discriminant is always an +.IR enum_t . +Next the union located at +.I unp +is translated. +The argument +.I choices +is a pointer to an array of +.BR xdr_discrim () +structures. +Each structure contains an ordered pair of +.RI [ value , proc ]. +If the union's discriminant is equal to the associated +.IR value , +then the +.I proc +is called to translate the union. +The end of the +.BR xdr_discrim () +structure array is denoted by a routine of value NULL. +If the discriminant is not found in the +.I choices +array, then the +.I defaultarm +procedure is called (if it is not NULL). +Returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size , +.BI " unsigned int " elsize ", xdrproc_t " elproc ); +.fi +.IP +A filter primitive that translates between fixed-length arrays +and their corresponding external representations. +The argument +.I arrp +is the address of the pointer to the array, while +.I size +is the element count of the array. +The argument +.I elsize +is the +.I sizeof +each of the array's elements, and +.I elproc +is an XDR filter that translates between +the array elements' C form, and their external +representation. +This routine returns one if it succeeds, zero otherwise. +.PP +.nf +.BI "bool_t xdr_void(void);" +.fi +.IP +This routine always returns one. +It may be passed to RPC routines that require a function argument, +where nothing is to be done. +.PP +.nf +.BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp ); +.fi +.IP +A primitive that calls +.B "xdr_string(xdrs, sp,MAXUN.UNSIGNED );" +where +.B MAXUN.UNSIGNED +is the maximum value of an unsigned integer. +.BR xdr_wrapstring () +is handy because the RPC package passes a maximum of two XDR +routines as arguments, and +.BR xdr_string (), +one of the most frequently used primitives, requires three. +Returns one if it succeeds, zero otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw31 lb lb +l l l. +Interface Attribute Value +T{ +.BR xdr_array (), +.BR xdr_bool (), +.br +.BR xdr_bytes (), +.BR xdr_char (), +.br +.BR xdr_destroy (), +.BR xdr_double (), +.br +.BR xdr_enum (), +.BR xdr_float (), +.br +.BR xdr_free (), +.BR xdr_getpos (), +.br +.BR xdr_inline (), +.BR xdr_int (), +.br +.BR xdr_long (), +.BR xdrmem_create (), +.br +.BR xdr_opaque (), +.BR xdr_pointer (), +.br +.BR xdrrec_create (), +.BR xdrrec_eof (), +.br +.BR xdrrec_endofrecord (), +.br +.BR xdrrec_skiprecord (), +.br +.BR xdr_reference (), +.BR xdr_setpos (), +.br +.BR xdr_short (), +.BR xdrstdio_create (), +.br +.BR xdr_string (), +.BR xdr_u_char (), +.br +.BR xdr_u_int (), +.BR xdr_u_long (), +.br +.BR xdr_u_short (), +.BR xdr_union (), +.br +.BR xdr_vector (), +.BR xdr_void (), +.br +.BR xdr_wrapstring () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH SEE ALSO +.BR rpc (3) +.PP +The following manuals: +.RS +eXternal Data Representation Standard: Protocol Specification +.br +eXternal Data Representation: Sun Technical Notes +.br +.IR "XDR: External Data Representation Standard" , +RFC\ 1014, Sun Microsystems, Inc., +USC-ISI. +.RE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/xdr_accepted_reply.3 b/man3/xdr_accepted_reply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_accepted_reply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_array.3 b/man3/xdr_array.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_array.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_authunix_parms.3 b/man3/xdr_authunix_parms.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_authunix_parms.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_bool.3 b/man3/xdr_bool.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_bool.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_bytes.3 b/man3/xdr_bytes.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_bytes.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_callhdr.3 b/man3/xdr_callhdr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_callhdr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_callmsg.3 b/man3/xdr_callmsg.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_callmsg.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_char.3 b/man3/xdr_char.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_char.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_destroy.3 b/man3/xdr_destroy.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_destroy.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_double.3 b/man3/xdr_double.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_double.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_enum.3 b/man3/xdr_enum.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_enum.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_float.3 b/man3/xdr_float.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_float.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_free.3 b/man3/xdr_free.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_free.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_getpos.3 b/man3/xdr_getpos.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_getpos.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_inline.3 b/man3/xdr_inline.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_inline.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_int.3 b/man3/xdr_int.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_int.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_long.3 b/man3/xdr_long.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_long.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_opaque.3 b/man3/xdr_opaque.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_opaque.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_opaque_auth.3 b/man3/xdr_opaque_auth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_opaque_auth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_pmap.3 b/man3/xdr_pmap.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_pmap.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_pmaplist.3 b/man3/xdr_pmaplist.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_pmaplist.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_pointer.3 b/man3/xdr_pointer.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_pointer.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_reference.3 b/man3/xdr_reference.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_reference.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_rejected_reply.3 b/man3/xdr_rejected_reply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_rejected_reply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_replymsg.3 b/man3/xdr_replymsg.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xdr_replymsg.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xdr_setpos.3 b/man3/xdr_setpos.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_setpos.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_short.3 b/man3/xdr_short.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_short.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_string.3 b/man3/xdr_string.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_string.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_u_char.3 b/man3/xdr_u_char.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_u_char.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_u_int.3 b/man3/xdr_u_int.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_u_int.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_u_long.3 b/man3/xdr_u_long.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_u_long.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_u_short.3 b/man3/xdr_u_short.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_u_short.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_union.3 b/man3/xdr_union.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_union.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_vector.3 b/man3/xdr_vector.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_vector.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_void.3 b/man3/xdr_void.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_void.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdr_wrapstring.3 b/man3/xdr_wrapstring.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdr_wrapstring.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrmem_create.3 b/man3/xdrmem_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdrmem_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrrec_create.3 b/man3/xdrrec_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdrrec_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrrec_endofrecord.3 b/man3/xdrrec_endofrecord.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdrrec_endofrecord.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrrec_eof.3 b/man3/xdrrec_eof.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdrrec_eof.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrrec_skiprecord.3 b/man3/xdrrec_skiprecord.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdrrec_skiprecord.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xdrstdio_create.3 b/man3/xdrstdio_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man3/xdrstdio_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man3/xencrypt.3 b/man3/xencrypt.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man3/xencrypt.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man3/xprt_register.3 b/man3/xprt_register.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xprt_register.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/xprt_unregister.3 b/man3/xprt_unregister.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man3/xprt_unregister.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man3/y0.3 b/man3/y0.3 new file mode 100644 index 0000000..a8b347c --- /dev/null +++ b/man3/y0.3 @@ -0,0 +1,285 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:08:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-25, aeb +.\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB +.\" 2008-07-24, mtk, created this page, based on material from j0.3. +.\" +.TH Y0 3 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \- +Bessel functions of the second kind +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "double y0(double " x ); +.BI "double y1(double " x ); +.BI "double yn(int " n ", double " x ); +.PP +.BI "float y0f(float " x ); +.BI "float y1f(float " x ); +.BI "float ynf(int " n ", float " x ); +.PP +.BI "long double y0l(long double " x ); +.BI "long double y1l(long double " x ); +.BI "long double ynl(int " n ", long double " x ); +.fi +.PP +Link with \fI\-lm\fP. +.PP +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.PP +.ad l +.BR y0 (), +.BR y1 (), +.BR yn (): +.RS 4 +_XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.br +.BR y0f (), +.BR y0l (), +.BR y1f (), +.BR y1l (), +.BR ynf (), +.BR ynl (): +.RS 4 +_XOPEN_SOURCE \ >=\ 600 + || (_ISOC99_SOURCE && _XOPEN_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.RE +.ad b +.SH DESCRIPTION +.PP +The +.BR y0 () +and +.BR y1 () +functions return Bessel functions of +.I x +of the second kind of orders 0 and 1, respectively. +The +.BR yn () +function +returns the Bessel function of +.I x +of the second kind of order +.IR n . +.PP +The value of +.I x +must be positive. +.PP +The +.BR y0f (), +.BR y1f (), +and +.BR ynf () +functions are versions that take and return +.I float +values. +The +.BR y0l (), +.BR y1l (), +and +.BR ynl () +functions are versions that take and return +.I "long double" +values. +.SH RETURN VALUE +On success, these functions return the appropriate +Bessel value of the second kind for +.IR x . +.PP +If +.I x +is a NaN, a NaN is returned. +.PP +If +.I x +is negative, +a domain error occurs, +and the functions return +.RB - HUGE_VAL , +.RB - HUGE_VALF , +or +.RB - HUGE_VALL , +respectively. +(POSIX.1-2001 also allows a NaN return for this case.) +.PP +If +.I x +is 0.0, +a pole error occurs, +and the functions return +.RB - HUGE_VAL , +.RB - HUGE_VALF , +or +.RB - HUGE_VALL , +respectively. +.PP +If the result underflows, +a range error occurs, +and the functions return 0.0 +.PP +If the result overflows, +a range error occurs, +and the functions return +.RB - HUGE_VAL , +.RB - HUGE_VALF , +or +.RB - HUGE_VALL , +respectively. +(POSIX.1-2001 also allows a 0.0 return for this case.) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.PP +The following errors can occur: +.TP +Domain error: \fIx\fP is negative +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is 0.0 +.\" Before POSIX.1-2001 TC2, this was (inconsistently) specified +.\" as a range error. +.I errno +is set to +.\" FIXME . y0(0.0) gives EDOM +.BR ERANGE +(but see BUGS). +No +.B FE_DIVBYZERO +exception is returned by +.BR fetestexcept (3) +for this case. +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6808 +.TP +Range error: result underflow +.\" e.g., y0(1e33) on glibc 2.8/x86-32 +.I errno +is set to +.BR ERANGE . +.\" An underflow floating-point exception +.\" .RB ( FE_UNDERFLOW ) +.\" is raised. +.\" FIXME . Is it intentional that these functions do not use FE_*? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6806 +No +.B FE_UNDERFLOW +exception is returned by +.BR fetestexcept (3) +for this case. +.TP +Range error: result overflow +.\" e.g., yn(10, 1e-40) on glibc 2.8/x86-32 +.\" .I errno +.\" is set to +.\" .BR ERANGE . +.I errno +is not set for this case. +.\" FIXME . Is it intentional that errno is not set? +.\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6808 +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR y0 (), +.BR y0f (), +.BR y0l () +T} Thread safety MT-Safe +T{ +.BR y1 (), +.BR y1f (), +.BR y1l () +T} Thread safety MT-Safe +T{ +.BR yn (), +.BR ynf (), +.BR ynl () +T} Thread safety MT-Safe +.TE +.SH CONFORMING TO +The functions returning +.I double +conform to SVr4, 4.3BSD, +POSIX.1-2001, POSIX.1-2008. +The others are nonstandard functions that also exist on the BSDs. +.SH BUGS +On a pole error, these functions set +.I errno +to +.BR EDOM , +instead of +.BR ERANGE +as POSIX.1-2004 requires. +.\" FIXME . +.\" Bug raised: http://sourceware.org/bugzilla/show_bug.cgi?id=6807 +.PP +In glibc version 2.3.2 and earlier, +.\" FIXME . Actually, 2.3.2 is the earliest test result I have; so yet +.\" to confirm if this error occurs only in 2.3.2. +these functions do not raise an invalid floating-point exception +.RB ( FE_INVALID ) +when a domain error occurs. +.SH SEE ALSO +.BR j0 (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man3/y0f.3 b/man3/y0f.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man3/y0f.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man3/y0l.3 b/man3/y0l.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man3/y0l.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man3/y1.3 b/man3/y1.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man3/y1.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man3/y1f.3 b/man3/y1f.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man3/y1f.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man3/y1l.3 b/man3/y1l.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man3/y1l.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man3/yn.3 b/man3/yn.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man3/yn.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man3/ynf.3 b/man3/ynf.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man3/ynf.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man3/ynl.3 b/man3/ynl.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man3/ynl.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man4/cciss.4 b/man4/cciss.4 new file mode 100644 index 0000000..a7344ff --- /dev/null +++ b/man4/cciss.4 @@ -0,0 +1,390 @@ +.\" Copyright (C) 2011, Hewlett-Packard Development Company, L.P. +.\" Written by Stephen M. Cameron +.\" +.\" %%%LICENSE_START(GPLv2_ONELINE) +.\" Licensed under GNU General Public License version 2 (GPLv2) +.\" %%%LICENSE_END +.\" +.\" shorthand for double quote that works everywhere. +.ds q \N'34' +.TH CCISS 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +cciss \- HP Smart Array block driver +.SH SYNOPSIS +.nf +modprobe cciss [ cciss_allow_hpsa=1 ] +.fi +.SH DESCRIPTION +.\" commit 253d2464df446456c0bba5ed4137a7be0b278aa8 +.BR Note : +This obsolete driver was removed from the kernel in version 4.14, +as it is superseded by the +.BR hpsa (4) +driver in newer kernels. +.PP +.B cciss +is a block driver for older HP Smart Array RAID controllers. +.SS Options +.IR "cciss_allow_hpsa=1" : +This option prevents the +.B cciss +driver from attempting to drive any controllers that the +.BR hpsa (4) +driver is capable of controlling, which is to say, the +.B cciss +driver is restricted by this option to the following controllers: +.PP +.nf + Smart Array 5300 + Smart Array 5i + Smart Array 532 + Smart Array 5312 + Smart Array 641 + Smart Array 642 + Smart Array 6400 + Smart Array 6400 EM + Smart Array 6i + Smart Array P600 + Smart Array P400i + Smart Array E200i + Smart Array E200 + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E500 +.fi +.SS Supported hardware +The +.B cciss +driver supports the following Smart Array boards: +.PP +.nf + Smart Array 5300 + Smart Array 5i + Smart Array 532 + Smart Array 5312 + Smart Array 641 + Smart Array 642 + Smart Array 6400 + Smart Array 6400 U320 Expansion Module + Smart Array 6i + Smart Array P600 + Smart Array P800 + Smart Array E400 + Smart Array P400i + Smart Array E200 + Smart Array E200i + Smart Array E500 + Smart Array P700m + Smart Array P212 + Smart Array P410 + Smart Array P410i + Smart Array P411 + Smart Array P812 + Smart Array P712m + Smart Array P711m +.fi +.SS Configuration details +To configure HP Smart Array controllers, +use the HP Array Configuration Utility +(either +.BR hpacuxe (8) +or +.BR hpacucli (8)) +or the Offline ROM-based Configuration Utility (ORCA) +run from the Smart Array's option ROM at boot time. +.SH FILES +.SS Device nodes +The device naming scheme is as follows: +.PP +.nf +Major numbers: +.PP + 104 cciss0 + 105 cciss1 + 106 cciss2 + 105 cciss3 + 108 cciss4 + 109 cciss5 + 110 cciss6 + 111 cciss7 +.PP +Minor numbers: +.PP + b7 b6 b5 b4 b3 b2 b1 b0 + |----+----| |----+----| + | | + | +-------- Partition ID (0=wholedev, 1\-15 partition) + | + +-------------------- Logical Volume number +.PP +The device naming scheme is: +.PP + /dev/cciss/c0d0 Controller 0, disk 0, whole device + /dev/cciss/c0d0p1 Controller 0, disk 0, partition 1 + /dev/cciss/c0d0p2 Controller 0, disk 0, partition 2 + /dev/cciss/c0d0p3 Controller 0, disk 0, partition 3 +.PP + /dev/cciss/c1d1 Controller 1, disk 1, whole device + /dev/cciss/c1d1p1 Controller 1, disk 1, partition 1 + /dev/cciss/c1d1p2 Controller 1, disk 1, partition 2 + /dev/cciss/c1d1p3 Controller 1, disk 1, partition 3 +.fi +.SS Files in /proc +The files +.I /proc/driver/cciss/cciss[0\-9]+ +contain information about +the configuration of each controller. +For example: +.PP +.in +4n +.EX +$ \fBcd /proc/driver/cciss\fP +$ \fBls -l\fP +total 0 +-rw-r--r-- 1 root root 0 2010\-09\-10 10:38 cciss0 +-rw-r--r-- 1 root root 0 2010\-09\-10 10:38 cciss1 +-rw-r--r-- 1 root root 0 2010\-09\-10 10:38 cciss2 +$ \fBcat cciss2\fP +cciss2: HP Smart Array P800 Controller +Board ID: 0x3223103c +Firmware Version: 7.14 +IRQ: 16 +Logical drives: 1 +Current Q depth: 0 +Current # commands on controller: 0 +Max Q depth since init: 1 +Max # commands on controller since init: 2 +Max SG entries since init: 32 +Sequential access devices: 0 + +cciss/c2d0: 36.38GB RAID 0 +.EE +.in +.\" +.SS Files in /sys +.TP +.I /sys/bus/pci/devices//ccissX/cXdY/model +Displays the SCSI INQUIRY page 0 model for logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices//ccissX/cXdY/rev +Displays the SCSI INQUIRY page 0 revision for logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices//ccissX/cXdY/unique_id +Displays the SCSI INQUIRY page 83 serial number for logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices//ccissX/cXdY/vendor +Displays the SCSI INQUIRY page 0 vendor for logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices//ccissX/cXdY/block:cciss!cXdY +A symbolic link to +.IR /sys/block/cciss!cXdY . +.TP +.I /sys/bus/pci/devices//ccissX/rescan +When this file is written to, the driver rescans the controller +to discover any new, removed, or modified logical drives. +.TP +.I /sys/bus/pci/devices//ccissX/resettable +A value of 1 displayed in this file indicates that +the "reset_devices=1" kernel parameter (used by +.BR kdump ) +is honored by this controller. +A value of 0 indicates that the +"reset_devices=1" kernel parameter will not be honored. +Some models of Smart Array are not able to honor this parameter. +.TP +.I /sys/bus/pci/devices//ccissX/cXdY/lunid +Displays the 8-byte LUN ID used to address logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices//ccissX/cXdY/raid_level +Displays the RAID level of logical drive +.I Y +of controller +.IR X . +.TP +.I /sys/bus/pci/devices//ccissX/cXdY/usage_count +Displays the usage count (number of opens) of logical drive +.I Y +of controller +.IR X . +.SS SCSI tape drive and medium changer support +SCSI sequential access devices and medium changer devices are supported and +appropriate device nodes are automatically created (e.g., +.IR /dev/st0 , +.IR /dev/st1 , +etc.; see +.BR st (4) +for more details.) +You must enable "SCSI tape drive support for Smart Array 5xxx" and +"SCSI support" in your kernel configuration to be able to use SCSI +tape drives with your Smart Array 5xxx controller. +.PP +Additionally, note that the driver will not engage the SCSI core at +init time. +The driver must be directed to dynamically engage the SCSI core via the +.I /proc +filesystem entry, +which the "block" side of the driver creates as +.I /proc/driver/cciss/cciss* +at run time. +This is because at driver init time, +the SCSI core may not yet be initialized (because the driver is a block +driver) and attempting to register it with the SCSI core in such a case +would cause a hang. +This is best done via an initialization script +(typically in +.IR /etc/init.d , +but could vary depending on distribution). +For example: +.PP +.in +4n +.EX +for x in /proc/driver/cciss/cciss[0\-9]* +do + echo "engage scsi" > $x +done +.EE +.in +.PP +Once the SCSI core is engaged by the driver, it cannot be disengaged +(except by unloading the driver, if it happens to be linked as a module.) +.PP +Note also that if no sequential access devices or medium changers are +detected, the SCSI core will not be engaged by the action of the above +script. +.SS Hot plug support for SCSI tape drives +Hot plugging of SCSI tape drives is supported, with some caveats. +The +.B cciss +driver must be informed that changes to the SCSI bus +have been made. +This may be done via the +.I /proc +filesystem. +For example: +.PP + echo "rescan" > /proc/scsi/cciss0/1 +.PP +This causes the driver to: +.RS +.IP 1. 3 +query the adapter about changes to the +physical SCSI buses and/or fibre channel arbitrated loop, and +.IP 2. +make note of any new or removed sequential access devices +or medium changers. +.RE +.PP +The driver will output messages indicating which +devices have been added or removed and the controller, bus, target, and +lun used to address each device. +The driver then notifies the SCSI midlayer +of these changes. +.PP +Note that the naming convention of the +.I /proc +filesystem entries +contains a number in addition to the driver name +(e.g., "cciss0" +instead of just "cciss", which you might expect). +.PP +Note: +.I Only +sequential access devices and medium changers are presented +as SCSI devices to the SCSI midlayer by the +.B cciss +driver. +Specifically, physical SCSI disk drives are +.I not +presented to the SCSI midlayer. +The only disk devices that are presented to the kernel are logical +drives that the array controller constructs from regions on +the physical drives. +The logical drives are presented to the block layer +(not to the SCSI midlayer). +It is important for the driver to prevent the kernel from accessing the +physical drives directly, since these drives are used by the array +controller to construct the logical drives. +.SS SCSI error handling for tape drives and medium changers +The Linux SCSI midlayer provides an error-handling protocol that +is initiated whenever a SCSI command fails to complete within a +certain amount of time (which can vary depending on the command). +The +.B cciss +driver participates in this protocol to some extent. +The normal protocol is a four-step process: +.IP * 3 +First, the device is told to abort the command. +.IP * +If that doesn't work, the device is reset. +.IP * +If that doesn't work, the SCSI bus is reset. +.IP * +If that doesn't work, the host bus adapter is reset. +.PP +The +.B cciss +driver is a block +driver as well as a SCSI driver and only the tape drives and medium +changers are presented to the SCSI midlayer. +Furthermore, unlike more +straightforward SCSI drivers, disk I/O continues through the block +side during the SCSI error-recovery process. +Therefore, the +.B cciss +driver implements only the first two of these actions, +aborting the command, and resetting the device. +Note also that most tape drives will not oblige +in aborting commands, and sometimes it appears they will not even +obey a reset command, though in most circumstances they will. +If the command cannot be aborted and the device cannot be +reset, the device will be set offline. +.PP +In the event that the error-handling code is triggered and a tape drive is +successfully reset or the tardy command is successfully aborted, the +tape drive may still not allow I/O to continue until some command +is issued that positions the tape to a known position. +Typically you must rewind the tape (by issuing +.I "mt -f /dev/st0 rewind" +for example) before I/O can proceed again to a tape drive that was reset. +.SH SEE ALSO +.BR hpsa (4), +.BR cciss_vol_status (8), +.BR hpacucli (8), +.BR hpacuxe (8) +.PP +.UR http://cciss.sf.net +.UE , +and +.I Documentation/blockdev/cciss.txt +and +.I Documentation/ABI/testing/sysfs-bus-pci-devices-cciss +in the Linux kernel source tree +.\" .SH AUTHORS +.\" Don Brace, Steve Cameron, Chase Maupin, Mike Miller, Michael Ni, +.\" Charles White, Francis Wiran +.\" and probably some other people. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/console_codes.4 b/man4/console_codes.4 new file mode 100644 index 0000000..bb4f6da --- /dev/null +++ b/man4/console_codes.4 @@ -0,0 +1,662 @@ +'\" t +.\" Copyright (c) 1996 Andries Brouwer , Mon Oct 31 22:13:04 1996 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" This is combined from many sources. +.\" For Linux, the definitive source is of course console.c. +.\" About vt100-like escape sequences in general there are +.\" the ISO 6429 and ISO 2022 norms, the descriptions of +.\" an actual vt100, and the xterm docs (ctlseqs.ms). +.\" Substantial portions of this text are derived from a write-up +.\" by Eric S. Raymond . +.\" +.\" Tiny correction, aeb, 961107. +.\" +.\" 2006-05-27, Several corrections - Thomas E. Dickey +.\" +.TH CONSOLE_CODES 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +console_codes \- Linux console escape and control sequences +.SH DESCRIPTION +The Linux console implements a large subset of the VT102 and ECMA-48/ISO +6429/ANSI X3.64 terminal controls, plus certain private-mode sequences +for changing the color palette, character-set mapping, and so on. +In the tabular descriptions below, the second column gives ECMA-48 or DEC +mnemonics (the latter if prefixed with DEC) for the given function. +Sequences without a mnemonic are neither ECMA-48 nor VT102. +.PP +After all the normal output processing has been done, and a +stream of characters arrives at the console driver for actual +printing, the first thing that happens is a translation from +the code used for processing to the code used for printing. +.PP +If the console is in UTF-8 mode, then the incoming bytes are +first assembled into 16-bit Unicode codes. +Otherwise, each byte is transformed according to the current mapping table +(which translates it to a Unicode value). +See the \fBCharacter Sets\fP section below for discussion. +.PP +In the normal case, the Unicode value is converted to a font index, +and this is stored in video memory, so that the corresponding glyph +(as found in video ROM) appears on the screen. +Note that the use of Unicode (and the design of the PC hardware) +allows us to use 512 different glyphs simultaneously. +.PP +If the current Unicode value is a control character, or we are +currently processing an escape sequence, the value will treated +specially. +Instead of being turned into a font index and rendered as +a glyph, it may trigger cursor movement or other control functions. +See the \fBLinux Console Controls\fP section below for discussion. +.PP +It is generally not good practice to hard-wire terminal controls into +programs. +Linux supports a +.BR terminfo (5) +database of terminal capabilities. +Rather than emitting console escape sequences by hand, you will almost +always want to use a terminfo-aware screen library or utility such as +.BR ncurses (3), +.BR tput (1), +or +.BR reset (1). +.SS Linux console controls +This section describes all the control characters and escape sequences +that invoke special functions (i.e., anything other than writing a +glyph at the current cursor location) on the Linux console. +.PP +.B "Control characters" +.PP +A character is a control character if (before transformation +according to the mapping table) it has one of the 14 codes +00 (NUL), 07 (BEL), 08 (BS), 09 (HT), 0a (LF), 0b (VT), +0c (FF), 0d (CR), 0e (SO), 0f (SI), 18 (CAN), 1a (SUB), +1b (ESC), 7f (DEL). +One can set a "display control characters" mode (see below), +and allow 07, 09, 0b, 18, 1a, 7f to be displayed as glyphs. +On the other hand, in UTF-8 mode all codes 00\(en1f are regarded +as control characters, regardless of any "display control characters" +mode. +.PP +If we have a control character, it is acted upon immediately +and then discarded (even in the middle of an escape sequence) +and the escape sequence continues with the next character. +(However, ESC starts a new escape sequence, possibly aborting a previous +unfinished one, and CAN and SUB abort any escape sequence.) +The recognized control characters are BEL, BS, HT, LF, VT, FF, +CR, SO, SI, CAN, SUB, ESC, DEL, CSI. +They do what one would expect: +.HP +BEL (0x07, \fB^G\fP) beeps; +.HP +BS (0x08, \fB^H\fP) backspaces one column +(but not past the beginning of the line); +.HP +HT (0x09, \fB^I\fP) goes to the next tab stop or to the end of the line +if there is no earlier tab stop; +.HP +LF (0x0A, \fB^J\fP), VT (0x0B, \fB^K\fP) and +FF (0x0C, \fB^L\fP) all give a linefeed, +and if LF/NL (new-line mode) is set also a carriage return; +.HP +CR (0x0D, \fB^M\fP) gives a carriage return; +.HP +SO (0x0E, \fB^N\fP) activates the G1 character set; +.HP +SI (0x0F, \fB^O\fP) activates the G0 character set; +.HP +CAN (0x18, \fB^X\fP) and SUB (0x1A, \fB^Z\fP) interrupt escape sequences; +.HP +ESC (0x1B, \fB^[\fP) starts an escape sequence; +.HP +DEL (0x7F) is ignored; +.HP +CSI (0x9B) is equivalent to ESC [. +.PP +.B "ESC- but not CSI-sequences" +.TS +l l l. +ESC c RIS Reset. +ESC D IND Linefeed. +ESC E NEL Newline. +ESC H HTS Set tab stop at current column. +ESC M RI Reverse linefeed. +ESC Z DECID T{ +DEC private identification. The kernel +returns the string ESC [ ? 6 c, claiming +that it is a VT102. +T} +ESC 7 DECSC T{ +Save current state (cursor coordinates, +attributes, character sets pointed at by G0, G1). +T} +ESC 8 DECRC Restore state most recently saved by ESC 7. +ESC [ CSI Control sequence introducer +ESC % Start sequence selecting character set +ESC % @ \0\0\0Select default (ISO 646 / ISO 8859-1) +ESC % G \0\0\0Select UTF-8 +ESC % 8 \0\0\0Select UTF-8 (obsolete) +ESC # 8 DECALN DEC screen alignment test \- fill screen with E's. +ESC ( Start sequence defining G0 character set +ESC ( B \0\0\0Select default (ISO 8859-1 mapping) +ESC ( 0 \0\0\0Select VT100 graphics mapping +ESC ( U \0\0\0Select null mapping \- straight to character ROM +ESC ( K \0\0\0Select user mapping \- the map that is loaded by + \0\0\0the utility \fBmapscrn\fP(8). +ESC ) Start sequence defining G1 + (followed by one of B, 0, U, K, as above). +ESC > DECPNM Set numeric keypad mode +ESC = DECPAM Set application keypad mode +ESC ] OSC T{ +(Should be: Operating system command) +ESC ] P \fInrrggbb\fP: set palette, with parameter +given in 7 hexadecimal digits after the final P :-(. +Here \fIn\fP is the color (0\(en15), and \fIrrggbb\fP indicates +the red/green/blue values (0\(en255). +ESC ] R: reset palette +T} +.TE +.PP +.B "ECMA-48 CSI sequences" +.PP +CSI (or ESC [) is followed by a sequence of parameters, +at most NPAR (16), that are decimal numbers separated by +semicolons. +An empty or absent parameter is taken to be 0. +The sequence of parameters may be preceded by a single question mark. +.PP +However, after CSI [ (or ESC [ [) a single character is read +and this entire sequence is ignored. +(The idea is to ignore an echoed function key.) +.PP +The action of a CSI sequence is determined by its final character. +.TS +l l l. +@ ICH Insert the indicated # of blank characters. +A CUU Move cursor up the indicated # of rows. +B CUD Move cursor down the indicated # of rows. +C CUF Move cursor right the indicated # of columns. +D CUB Move cursor left the indicated # of columns. +E CNL Move cursor down the indicated # of rows, to column 1. +F CPL Move cursor up the indicated # of rows, to column 1. +G CHA Move cursor to indicated column in current row. +H CUP Move cursor to the indicated row, column (origin at 1,1). +J ED Erase display (default: from cursor to end of display). + ESC [ 1 J: erase from start to cursor. + ESC [ 2 J: erase whole display. + ESC [ 3 J: erase whole display including scroll-back + buffer (since Linux 3.0). +.\" ESC [ 3 J: commit f8df13e0a901fe55631fed66562369b4dba40f8b +K EL Erase line (default: from cursor to end of line). + ESC [ 1 K: erase from start of line to cursor. + ESC [ 2 K: erase whole line. +L IL Insert the indicated # of blank lines. +M DL Delete the indicated # of lines. +P DCH Delete the indicated # of characters on current line. +X ECH Erase the indicated # of characters on current line. +a HPR Move cursor right the indicated # of columns. +c DA Answer ESC [ ? 6 c: "I am a VT102". +d VPA Move cursor to the indicated row, current column. +e VPR Move cursor down the indicated # of rows. +f HVP Move cursor to the indicated row, column. +g TBC Without parameter: clear tab stop at current position. + ESC [ 3 g: delete all tab stops. +h SM Set Mode (see below). +l RM Reset Mode (see below). +m SGR Set attributes (see below). +n DSR Status report (see below). +q DECLL Set keyboard LEDs. + ESC [ 0 q: clear all LEDs + ESC [ 1 q: set Scroll Lock LED + ESC [ 2 q: set Num Lock LED + ESC [ 3 q: set Caps Lock LED +r DECSTBM Set scrolling region; parameters are top and bottom row. +s ? Save cursor location. +u ? Restore cursor location. +\` HPA Move cursor to indicated column in current row. +.TE +.PP +.B ECMA-48 Set Graphics Rendition +.PP +The ECMA-48 SGR sequence ESC [ \fIparameters\fP m sets display +attributes. +Several attributes can be set in the same sequence, separated by +semicolons. +An empty parameter (between semicolons or string initiator or +terminator) is interpreted as a zero. +.TS +l l. +param result +0 reset all attributes to their defaults +1 set bold +2 set half-bright (simulated with color on a color display) +4 T{ +set underscore (simulated with color on a color display) +(the colors used to simulate dim or underline are set +using ESC ] ...) +T} +5 set blink +7 set reverse video +10 T{ +reset selected mapping, display control flag, +and toggle meta flag (ECMA-48 says "primary font"). +T} +11 T{ +select null mapping, set display control flag, +reset toggle meta flag (ECMA-48 says "first alternate font"). +T} +12 T{ +select null mapping, set display control flag, +set toggle meta flag (ECMA-48 says "second alternate font"). +The toggle meta flag +causes the high bit of a byte to be toggled +before the mapping table translation is done. +T} +21 set normal intensity (ECMA-48 says "doubly underlined") +22 set normal intensity +24 underline off +25 blink off +27 reverse video off +30 set black foreground +31 set red foreground +32 set green foreground +33 set brown foreground +34 set blue foreground +35 set magenta foreground +36 set cyan foreground +37 set white foreground +38 set underscore on, set default foreground color +39 set underscore off, set default foreground color +40 set black background +41 set red background +42 set green background +43 set brown background +44 set blue background +45 set magenta background +46 set cyan background +47 set white background +49 set default background color +.TE +.PP +.B ECMA-48 Mode Switches +.TP +ESC [ 3 h +DECCRM (default off): Display control chars. +.TP +ESC [ 4 h +DECIM (default off): Set insert mode. +.TP +ESC [ 20 h +LF/NL (default off): Automatically follow echo of LF, VT or FF with CR. +.\" +.PP +.B ECMA-48 Status Report Commands +.\" +.TP +ESC [ 5 n +Device status report (DSR): Answer is ESC [ 0 n (Terminal OK). +.TP +ESC [ 6 n +Cursor position report (CPR): Answer is ESC [ \fIy\fP ; \fIx\fP R, +where \fIx,y\fP is the cursor location. +.\" +.PP +.B DEC Private Mode (DECSET/DECRST) sequences +.PP +.\" +These are not described in ECMA-48. +We list the Set Mode sequences; +the Reset Mode sequences are obtained by replacing the final \(aqh\(aq +by \(aql\(aq. +.TP +ESC [ ? 1 h +DECCKM (default off): When set, the cursor keys send an ESC O prefix, +rather than ESC [. +.TP +ESC [ ? 3 h +DECCOLM (default off = 80 columns): 80/132 col mode switch. +The driver sources note that this alone does not suffice; some user-mode +utility such as +.BR resizecons (8) +has to change the hardware registers on the console video card. +.TP +ESC [ ? 5 h +DECSCNM (default off): Set reverse-video mode. +.TP +ESC [ ? 6 h +DECOM (default off): When set, cursor addressing is relative to +the upper left corner of the scrolling region. +.TP +ESC [ ? 7 h +DECAWM (default on): Set autowrap on. +In this mode, a graphic +character emitted after column 80 (or column 132 of DECCOLM is on) +forces a wrap to the beginning of the following line first. +.TP +ESC [ ? 8 h +DECARM (default on): Set keyboard autorepeat on. +.TP +ESC [ ? 9 h +X10 Mouse Reporting (default off): Set reporting mode to 1 (or reset to +0)\(emsee below. +.TP +ESC [ ? 25 h +DECTECM (default on): Make cursor visible. +.TP +ESC [ ? 1000 h +X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset +to 0)\(emsee below. +.\" +.PP +.B Linux Console Private CSI Sequences +.PP +.\" +The following sequences are neither ECMA-48 nor native VT102. +They are native to the Linux console driver. +Colors are in SGR parameters: +0 = black, 1 = red, 2 = green, 3 = brown, 4 = blue, 5 = magenta, 6 = +cyan, 7 = white. +.TS +l l. +ESC [ 1 ; \fIn\fP ] Set color \fIn\fP as the underline color +ESC [ 2 ; \fIn\fP ] Set color \fIn\fP as the dim color +ESC [ 8 ] Make the current color pair the default attributes. +ESC [ 9 ; \fIn\fP ] Set screen blank timeout to \fIn\fP minutes. +ESC [ 10 ; \fIn\fP ] Set bell frequency in Hz. +ESC [ 11 ; \fIn\fP ] Set bell duration in msec. +ESC [ 12 ; \fIn\fP ] Bring specified console to the front. +ESC [ 13 ] Unblank the screen. +ESC [ 14 ; \fIn\fP ] Set the VESA powerdown interval in minutes. +ESC [ 15 ] T{ +Bring the previous console to the front +(since Linux 2.6.0). +T} +ESC [ 16 ; \fIn\fP ] T{ +Set the cursor blink interval in milliseconds +(since Linux 4.2) +T} +.\" commit bd63364caa8df38bad2b25b11b2a1b849475cce5 +.TE +.SS Character sets +The kernel knows about 4 translations of bytes into console-screen +symbols. +The four tables are: a) Latin1 \-> PC, +b) VT100 graphics \-> PC, c) PC \-> PC, d) user-defined. +.PP +There are two character sets, called G0 and G1, and one of them +is the current character set. +(Initially G0.) +Typing \fB^N\fP causes G1 to become current, +\fB^O\fP causes G0 to become current. +.PP +These variables G0 and G1 point at a translation table, and can be +changed by the user. +Initially they point at tables a) and b), respectively. +The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to +point at translation table a), b), c) and d), respectively. +The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to +point at translation table a), b), c) and d), respectively. +.PP +The sequence ESC c causes a terminal reset, which is what you want if the +screen is all garbled. +The oft-advised "echo ^V^O" will make only G0 current, +but there is no guarantee that G0 points at table a). +In some distributions there is a program +.BR reset (1) +that just does "echo ^[c". +If your terminfo entry for the console is correct +(and has an entry rs1=\\Ec), then "tput reset" will also work. +.PP +The user-defined mapping table can be set using +.BR mapscrn (8). +The result of the mapping is that if a symbol c is printed, the symbol +s = map[c] is sent to the video memory. +The bitmap that corresponds to +s is found in the character ROM, and can be changed using +.BR setfont (8). +.SS Mouse tracking +The mouse tracking facility is intended to return +.BR xterm (1)-compatible +mouse status reports. +Because the console driver has no way to know +the device or type of the mouse, these reports are returned in the +console input stream only when the virtual terminal driver receives +a mouse update ioctl. +These ioctls must be generated by a mouse-aware +user-mode application such as the +.BR gpm (8) +daemon. +.PP +The mouse tracking escape sequences generated by +\fBxterm\fP(1) encode numeric parameters in a single character as +\fIvalue\fP+040. +For example, \(aq!\(aq is 1. +The screen coordinate system is 1-based. +.PP +The X10 compatibility mode sends an escape sequence on button press +encoding the location and the mouse button pressed. +It is enabled by sending ESC [ ? 9 h and disabled with ESC [ ? 9 l. +On button press, \fBxterm\fP(1) sends +ESC [ M \fIbxy\fP (6 characters). +Here \fIb\fP is button\-1, +and \fIx\fP and \fIy\fP are the x and y coordinates of the mouse +when the button was pressed. +This is the same code the kernel also produces. +.PP +Normal tracking mode (not implemented in Linux 2.0.24) sends an escape +sequence on both button press and release. +Modifier information is also sent. +It is enabled by sending ESC [ ? 1000 h and disabled with +ESC [ ? 1000 l. +On button press or release, \fBxterm\fP(1) sends ESC [ M +\fIbxy\fP. +The low two bits of \fIb\fP encode button information: +0=MB1 pressed, 1=MB2 pressed, 2=MB3 pressed, 3=release. +The upper bits encode what modifiers were down when the button was +pressed and are added together: 4=Shift, 8=Meta, 16=Control. +Again \fIx\fP and +\fIy\fP are the x and y coordinates of the mouse event. +The upper left corner is (1,1). +.SS Comparisons with other terminals +Many different terminal types are described, like the Linux console, +as being "VT100-compatible". +Here we discuss differences between the +Linux console and the two most important others, the DEC VT102 and +.BR xterm (1). +.\" +.PP +.B Control-character handling +.PP +The VT102 also recognized the following control characters: +.HP +NUL (0x00) was ignored; +.HP +ENQ (0x05) triggered an answerback message; +.HP +DC1 (0x11, \fB^Q\fP, XON) resumed transmission; +.HP +DC3 (0x13, \fB^S\fP, XOFF) caused VT100 to ignore (and stop transmitting) +all codes except XOFF and XON. +.PP +VT100-like DC1/DC3 processing may be enabled by the terminal driver. +.PP +The +.BR xterm (1) +program (in VT100 mode) recognizes the control characters +BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC. +.\" +.PP +.B Escape sequences +.PP +VT100 console sequences not implemented on the Linux console: +.TS +l l l. +ESC N SS2 Single shift 2. (Select G2 character set for the next + character only.) +ESC O SS3 Single shift 3. (Select G3 character set for the next + character only.) +ESC P DCS Device control string (ended by ESC \\) +ESC X SOS Start of string. +ESC ^ PM Privacy message (ended by ESC \\) +ESC \\ ST String terminator +ESC * ... Designate G2 character set +ESC + ... Designate G3 character set +.TE +.PP +The program +.BR xterm (1) +(in VT100 mode) recognizes ESC c, ESC # 8, ESC >, ESC =, +ESC D, ESC E, ESC H, ESC M, ESC N, ESC O, ESC P ... ESC \\, +ESC Z (it answers ESC [ ? 1 ; 2 c, "I am a VT100 with +advanced video option") +and ESC ^ ... ESC \\ with the same meanings as indicated above. +It accepts ESC (, ESC ), ESC *, ESC + followed by 0, A, B for +the DEC special character and line drawing set, UK, and US-ASCII, +respectively. +.PP +The user can configure \fBxterm\fP(1) to respond to VT220-specific +control sequences, and it will identify itself as a VT52, VT100, and +up depending on the way it is configured and initialized. +.PP +It accepts ESC ] (OSC) for the setting of certain resources. +In addition to the ECMA-48 string terminator (ST), +\fBxterm\fP(1) accepts a BEL to terminate an OSC string. +These are a few of the OSC control sequences recognized by \fBxterm\fP(1): +.TS +l l. +ESC ] 0 ; \fItxt\fP ST Set icon name and window title to \fItxt\fP. +ESC ] 1 ; \fItxt\fP ST Set icon name to \fItxt\fP. +ESC ] 2 ; \fItxt\fP ST Set window title to \fItxt\fP. +ESC ] 4 ; \fInum\fP; \fItxt\fP ST Set ANSI color \fInum\fP to \fItxt\fP. +ESC ] 10 ; \fItxt\fP ST Set dynamic text color to \fItxt\fP. +ESC ] 4 6 ; \fIname\fP ST Change log file to \fIname\fP (normally disabled + by a compile-time option) +ESC ] 5 0 ; \fIfn\fP ST Set font to \fIfn\fP. +.TE +.PP +It recognizes the following with slightly modified meaning +(saving more state, behaving closer to VT100/VT220): +.TS +l l l. +ESC 7 DECSC Save cursor +ESC 8 DECRC Restore cursor +.TE +.PP +It also recognizes +.TS +l l l. +ESC F Cursor to lower left corner of screen (if enabled by + \fBxterm\fP(1)'s \fBhpLowerleftBugCompat\fP resource) +ESC l Memory lock (per HP terminals). + Locks memory above the cursor. +ESC m Memory unlock (per HP terminals). +ESC n LS2 Invoke the G2 character set. +ESC o LS3 Invoke the G3 character set. +ESC | LS3R Invoke the G3 character set as GR. +ESC } LS2R Invoke the G2 character set as GR. +ESC ~ LS1R Invoke the G1 character set as GR. +.TE +.PP +It also recognizes ESC % and provides a more complete UTF-8 +implementation than Linux console. +.\" +.PP +.B CSI Sequences +.PP +Old versions of \fBxterm\fP(1), for example, from X11R5, +interpret the blink SGR as a bold SGR. +Later versions which implemented ANSI colors, for example, +XFree86 3.1.2A in 1995, improved this by allowing +the blink attribute to be displayed as a color. +Modern versions of xterm implement blink SGR as blinking text +and still allow colored text as an alternate rendering of SGRs. +Stock X11R6 versions did not recognize the color-setting SGRs until +the X11R6.8 release, which incorporated XFree86 xterm. +All ECMA-48 CSI sequences recognized by Linux are also recognized by +.IR xterm , +however \fBxterm\fP(1) implements several ECMA-48 and DEC control sequences +not recognized by Linux. +.PP +The \fBxterm\fP(1) +program recognizes all of the DEC Private Mode sequences listed +above, but none of the Linux private-mode sequences. +For discussion of \fBxterm\fP(1)'s +own private-mode sequences, refer to the +\fIXterm Control Sequences\fP +document by +Edward Moy, +Stephen Gildea, +and Thomas E. Dickey +available with the X distribution. +That document, though terse, is much longer than this manual page. +For a chronological overview, +.PP +.RS +.UR http://invisible\-island.net\:/xterm\:/xterm.log.html +.UE +.RE +.PP +details changes to xterm. +.PP +The \fIvttest\fP program +.PP +.RS +.UR http://invisible\-island.net\:/vttest/ +.UE +.RE +.PP +demonstrates many of these control sequences. +The \fBxterm\fP(1) source distribution also contains sample +scripts which exercise other features. +.SH NOTES +ESC 8 (DECRC) is not able to restore the character set changed with +ESC %. +.SH BUGS +In 2.0.23, CSI is broken, and NUL is not ignored inside +escape sequences. +.PP +Some older kernel versions (after 2.0) interpret 8-bit control +sequences. +These "C1 controls" use codes between 128 and 159 to replace +ESC [, ESC ] and similar two-byte control sequence initiators. +There are fragments of that in modern kernels (either overlooked or +broken by changes to support UTF-8), +but the implementation is incomplete and should be regarded +as unreliable. +.PP +Linux "private mode" sequences do not follow the rules in ECMA-48 +for private mode control sequences. +In particular, those ending with ] do not use a standard terminating +character. +The OSC (set palette) sequence is a greater problem, +since \fBxterm\fP(1) may interpret this as a control sequence +which requires a string terminator (ST). +Unlike the \fBsetterm\fP(1) sequences which will be ignored (since +they are invalid control sequences), the palette sequence will make +\fBxterm\fP(1) appear to hang (though pressing the return-key +will fix that). +To accommodate applications which have been hardcoded to use Linux +control sequences, +set the \fBxterm\fP(1) resource \fBbrokenLinuxOSC\fP to true. +.PP +An older version of this document implied that Linux recognizes the +ECMA-48 control sequence for invisible text. +It is ignored. +.SH SEE ALSO +.BR ioctl_console (2), +.BR charsets (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/console_ioctl.4 b/man4/console_ioctl.4 new file mode 100644 index 0000000..5dfc68d --- /dev/null +++ b/man4/console_ioctl.4 @@ -0,0 +1,2 @@ +.so man2/ioctl_console.2 +.\" Link for old name of this page diff --git a/man4/cpuid.4 b/man4/cpuid.4 new file mode 100644 index 0000000..cd2a111 --- /dev/null +++ b/man4/cpuid.4 @@ -0,0 +1,108 @@ +.\" Copyright (c) 2009 Intel Corporation, Author Andi Kleen +.\" Description based on comments in arch/x86/kernel/cpuid.c +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH CPUID 4 2009-03-31 "Linux" "Linux Programmer's Manual" +.SH NAME +cpuid \- x86 CPUID access device +.SH DESCRIPTION +CPUID provides an interface for querying information about the x86 CPU. +.PP +This device is accessed by +.BR lseek (2) +or +.BR pread (2) +to the appropriate CPUID level and reading in chunks of 16 bytes. +A larger read size means multiple reads of consecutive levels. +.PP +The lower 32 bits of the file position is used as the incoming +.IR %eax , +and the upper 32 bits of the file position as the incoming +.IR %ecx , +the latter intended for "counting" +.I eax +levels like +.IR eax=4 . +.PP +This driver uses +.IR /dev/cpu/CPUNUM/cpuid , +where +.I CPUNUM +is the minor number, +and on an SMP box will direct the access to CPU +.I CPUNUM +as listed in +.IR /proc/cpuinfo . +.PP +This file is protected so that it can be read only by the user +.IR root , +or members of the group +.IR root . +.SH NOTES +The CPUID instruction can be directly executed by a program +using inline assembler. +However this device allows convenient +access to all CPUs without changing process affinity. +.PP +Most of the information in +.I cpuid +is reported by the kernel in cooked form either in +.I /proc/cpuinfo +or through subdirectories in +.IR /sys/devices/system/cpu . +Direct CPUID access through this device should only +be used in exceptional cases. +.PP +The +.I cpuid +driver is not auto-loaded. +On modular kernels you might need to use the following command +to load it explicitly before use: +.PP +.in +4n +.EX +$ modprobe cpuid +.EE +.in +.PP +There is no support for CPUID functions that require additional +input registers. +.PP +Very old x86 CPUs don't support CPUID. +.SH SEE ALSO +Intel Corporation, Intel 64 and IA-32 Architectures +Software Developer's Manual Volume 2A: +Instruction Set Reference, A-M, 3-180 CPUID reference. +.PP +Intel Corporation, Intel Processor Identification and +the CPUID Instruction, Application note 485. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/dsp56k.4 b/man4/dsp56k.4 new file mode 100644 index 0000000..2a2a8b1 --- /dev/null +++ b/man4/dsp56k.4 @@ -0,0 +1,129 @@ +'\" t +.\" Copyright (c) 2000 lars brinkhoff +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified, Thu Jan 27 19:16:19 CET 2000, lars@nocrew.org +.\" +.TH DSP56K 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +dsp56k \- DSP56001 interface device +.SH SYNOPSIS +.nf +#include +.PP +.BI "ssize_t read(int " fd ", void *" data ", size_t " length ); +.BI "ssize_t write(int " fd ", void *" data ", size_t " length ); +.PP +.BI "int ioctl(int " fd ", DSP56K_UPLOAD, struct dsp56k_upload *" program ); +.BI "int ioctl(int " fd ", DSP56K_SET_TX_WSIZE, int " wsize ); +.BI "int ioctl(int " fd ", DSP56K_SET_RX_WSIZE, int " wsize ); +.BI "int ioctl(int " fd ", DSP56K_HOST_FLAGS, struct dsp56k_host_flags *" flags ); +.BI "int ioctl(int " fd ", DSP56K_HOST_CMD, int " cmd ); +.fi +.SH CONFIGURATION +The dsp56k device is a character device with major number 55 and minor +number 0. +.SH DESCRIPTION +The Motorola DSP56001 is a fully programmable 24-bit digital signal +processor found in Atari Falcon030-compatible computers. +The \fIdsp56k\fP special file is used to control the DSP56001, and +to send and receive data using the bidirectional handshaked host +port. +.PP +To send a data stream to the signal processor, use +.BR write (2) +to the +device, and +.BR read (2) +to receive processed data. +The data can be sent or +received in 8, 16, 24, or 32-bit quantities on the host side, but will +always be seen as 24-bit quantities in the DSP56001. +.PP +The following +.BR ioctl (2) +calls are used to control the +\fIdsp56k\fP device: +.IP \fBDSP56K_UPLOAD\fP +resets the DSP56001 and uploads a program. +The third +.BR ioctl (2) +argument must be a pointer to a \fIstruct dsp56k_binary\fP with members +\fIbin\fP pointing to a DSP56001 binary program, and \fIlen\fP set to +the length of the program, counted in 24-bit words. +.IP \fBDSP56K_SET_TX_WSIZE\fP +sets the transmit word size. +Allowed values are in the range 1 to 4, +and is the number of bytes that will be sent at a time to the +DSP56001. +These data quantities will either be padded with zero +bytes, or truncated to fit the native 24-bit data format of the +DSP56001. +.IP \fBDSP56K_SET_RX_WSIZE\fP +sets the receive word size. +Allowed values are in the range 1 to 4, +and is the number of bytes that will be received at a time from the +DSP56001. +These data quantities will either truncated, or padded with +a null byte (\(aq\\0\(aq) to fit the native 24-bit data format of the DSP56001. +.IP \fBDSP56K_HOST_FLAGS\fP +read and write the host flags. +The host flags are four +general-purpose bits that can be read by both the hosting computer and +the DSP56001. +Bits 0 and 1 can be written by the host, and bits 2 and +3 can be written by the DSP56001. +.IP +To access the host flags, the third +.BR ioctl (2) +argument must be a pointer +to a \fIstruct dsp56k_host_flags\fP. +If bit 0 or 1 is set in the +\fIdir\fP member, the corresponding bit in \fIout\fP will be written +to the host flags. +The state of all host flags will be returned in +the lower four bits of the \fIstatus\fP member. +.IP \fBDSP56K_HOST_CMD\fP +sends a host command. +Allowed values are in the range 0 to 31, and is a +user-defined command handled by the program running in the DSP56001. +.SH FILES +/dev/dsp56k +.\" .SH AUTHORS +.\" Fredrik Noring , lars brinkhoff , +.\" Tomas Berndtsson . +.SH SEE ALSO +.IR linux/include/asm-m68k/dsp56k.h , +.IR linux/drivers/char/dsp56k.c , +.UR http://dsp56k.nocrew.org/ +.UE , +DSP56000/DSP56001 Digital Signal Processor User's Manual +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/fd.4 b/man4/fd.4 new file mode 100644 index 0000000..ab21928 --- /dev/null +++ b/man4/fd.4 @@ -0,0 +1,242 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de) +.\" and 1994,1995 Alain Knaff (Alain.Knaff@imag.fr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified, Sun Feb 26 15:00:02 1995, faith@cs.unc.edu +.\" +.TH FD 4 2014-05-10 "Linux" "Linux Programmer's Manual" +.SH NAME +fd \- floppy disk device +.SH CONFIGURATION +Floppy drives are block devices with major number 2. +Typically they +are owned by +.I root.floppy +(i.e., user root, group floppy) and have +either mode 0660 (access checking via group membership) or mode 0666 +(everybody has access). +The minor +numbers encode the device type, drive number, and controller number. +For each device type (that is, combination of density and track count) +there is a base minor number. +To this base number, add the drive's +number on its controller and 128 if the drive is on the secondary +controller. +In the following device tables, \fIn\fP represents the +drive number. +.PP +\fBWarning: if you use formats with more tracks +than supported by your drive, you may cause it mechanical damage.\fP +Trying once if more tracks than the usual 40/80 are supported should not +damage it, but no warranty is given for that. +If you are not sure, don't create device +entries for those formats, so as to prevent their usage. +.PP +Drive-independent device files which automatically detect the media +format and capacity: +.TS +l c +l c. +Name Base + minor # +_ +\fBfd\fP\fIn\fP 0 +.TE +.PP +5.25 inch double-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBd360\fP 360 40 9 2 4 +.TE +.PP +5.25 inch high-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBh360\fP 360 40 9 2 20 +\fBfd\fP\fIn\fP\fBh410\fP 410 41 10 2 48 +\fBfd\fP\fIn\fP\fBh420\fP 420 42 10 2 64 +\fBfd\fP\fIn\fP\fBh720\fP 720 80 9 2 24 +\fBfd\fP\fIn\fP\fBh880\fP 880 80 11 2 80 +\fBfd\fP\fIn\fP\fBh1200\fP 1200 80 15 2 8 +\fBfd\fP\fIn\fP\fBh1440\fP 1440 80 18 2 40 +\fBfd\fP\fIn\fP\fBh1476\fP 1476 82 18 2 56 +\fBfd\fP\fIn\fP\fBh1494\fP 1494 83 18 2 72 +\fBfd\fP\fIn\fP\fBh1600\fP 1600 80 20 2 92 +.TE +.PP +3.5 inch double-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu360\fP 360 80 9 1 12 +\fBfd\fP\fIn\fP\fBu720\fP 720 80 9 2 16 +\fBfd\fP\fIn\fP\fBu800\fP 800 80 10 2 120 +\fBfd\fP\fIn\fP\fBu1040\fP 1040 80 13 2 84 +\fBfd\fP\fIn\fP\fBu1120\fP 1120 80 14 2 88 +.TE +.PP +3.5 inch high-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu360\fP 360 40 9 2 12 +\fBfd\fP\fIn\fP\fBu720\fP 720 80 9 2 16 +\fBfd\fP\fIn\fP\fBu820\fP 820 82 10 2 52 +\fBfd\fP\fIn\fP\fBu830\fP 830 83 10 2 68 +\fBfd\fP\fIn\fP\fBu1440\fP 1440 80 18 2 28 +\fBfd\fP\fIn\fP\fBu1600\fP 1600 80 20 2 124 +\fBfd\fP\fIn\fP\fBu1680\fP 1680 80 21 2 44 +\fBfd\fP\fIn\fP\fBu1722\fP 1722 82 21 2 60 +\fBfd\fP\fIn\fP\fBu1743\fP 1743 83 21 2 76 +\fBfd\fP\fIn\fP\fBu1760\fP 1760 80 22 2 96 +\fBfd\fP\fIn\fP\fBu1840\fP 1840 80 23 2 116 +\fBfd\fP\fIn\fP\fBu1920\fP 1920 80 24 2 100 +.TE +.PP +3.5 inch extra-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu2880\fP 2880 80 36 2 32 +\fBfd\fP\fIn\fP\fBCompaQ\fP 2880 80 36 2 36 +\fBfd\fP\fIn\fP\fBu3200\fP 3200 80 40 2 104 +\fBfd\fP\fIn\fP\fBu3520\fP 3520 80 44 2 108 +\fBfd\fP\fIn\fP\fBu3840\fP 3840 80 48 2 112 +.TE +.SH DESCRIPTION +\fBfd\fP special files access the floppy disk drives in raw mode. +The following +.BR ioctl (2) +calls are supported by \fBfd\fP devices: +.IP \fBFDCLRPRM\fP +clears the media information of a drive (geometry of disk in drive). +.IP \fBFDSETPRM\fP +sets the media information of a drive. +The media information will be +lost when the media is changed. +.IP \fBFDDEFPRM\fP +sets the media information of a drive (geometry of disk in drive). +The media information will not be lost when the media is changed. +This will disable autodetection. +In order to reenable autodetection, you +have to issue an \fBFDCLRPRM\fP. +.IP \fBFDGETDRVTYP\fP +returns the type of a drive (name parameter). +For formats which work +in several drive types, \fBFDGETDRVTYP\fP returns a name which is +appropriate for the oldest drive type which supports this format. +.IP \fBFDFLUSH\fP +invalidates the buffer cache for the given drive. +.IP \fBFDSETMAXERRS\fP +sets the error thresholds for reporting errors, aborting the operation, +recalibrating, resetting, and reading sector by sector. +.IP \fBFDSETMAXERRS\fP +gets the current error thresholds. +.IP \fBFDGETDRVTYP\fP +gets the internal name of the drive. +.IP \fBFDWERRORCLR\fP +clears the write error statistics. +.IP \fBFDWERRORGET\fP +reads the write error statistics. +These include the total number of +write errors, the location and disk of the first write error, and the +location and disk of the last write error. +Disks are identified by a +generation number which is incremented at (almost) each disk change. +.IP \fBFDTWADDLE\fP +Switch the drive motor off for a few microseconds. +This might be +needed in order to access a disk whose sectors are too close together. +.IP \fBFDSETDRVPRM\fP +sets various drive parameters. +.IP \fBFDGETDRVPRM\fP +reads these parameters back. +.IP \fBFDGETDRVSTAT\fP +gets the cached drive state (disk changed, write protected et al.) +.IP \fBFDPOLLDRVSTAT\fP +polls the drive and return its state. +.IP \fBFDGETFDCSTAT\fP +gets the floppy controller state. +.IP \fBFDRESET\fP +resets the floppy controller under certain conditions. +.IP \fBFDRAWCMD\fP +sends a raw command to the floppy controller. +.PP +For more precise information, consult also the \fI\fP and +\fI\fP include files, as well as the +.BR floppycontrol (1) +manual page. +.SH FILES +.I /dev/fd* +.SH NOTES +The various formats permit reading and writing many types of disks. +However, if a floppy is formatted with an inter-sector gap that is too small, +performance may drop, +to the point of needing a few seconds to access an entire track. +To prevent this, use interleaved formats. +.PP +It is not possible to +read floppies which are formatted using GCR (group code recording), +which is used by Apple II and Macintosh computers (800k disks). +.PP +Reading floppies which are hard sectored (one hole per sector, with +the index hole being a little skewed) is not supported. +This used to be common with older 8-inch floppies. +.\" .SH AUTHORS +.\" Alain Knaff (Alain.Knaff@imag.fr), David Niemi +.\" (niemidc@clark.net), Bill Broadhurst (bbroad@netcom.com). +.SH SEE ALSO +.BR chown (1), +.BR floppycontrol (1), +.BR getfdprm (1), +.BR mknod (1), +.BR superformat (1), +.BR mount (8), +.BR setfdprm (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/full.4 b/man4/full.4 new file mode 100644 index 0000000..e73def1 --- /dev/null +++ b/man4/full.4 @@ -0,0 +1,75 @@ +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" correction, aeb, 970825 +.TH FULL 4 2007-11-24 "Linux" "Linux Programmer's Manual" +.SH NAME +full \- always full device +.SH CONFIGURATION +If your system does not have +.I /dev/full +created already, it +can be created with the following commands: +.PP +.in +4n +.EX +mknod \-m 666 /dev/full c 1 7 +chown root:root /dev/full +.EE +.in +.SH DESCRIPTION +File +.I /dev/full +has major device number 1 +and minor device number 7. +.PP +Writes to the +.I /dev/full +device fail with an +.B ENOSPC +error. +This can be used to test how a program handles disk-full errors. +.PP +Reads from the +.I /dev/full +device will return \\0 characters. +.PP +Seeks on +.I /dev/full +will always succeed. +.SH FILES +.I /dev/full +.SH SEE ALSO +.BR mknod (1), +.BR null (4), +.BR zero (4) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/fuse.4 b/man4/fuse.4 new file mode 100644 index 0000000..ee7c188 --- /dev/null +++ b/man4/fuse.4 @@ -0,0 +1,569 @@ +.\" Copyright (c) 2016 Julia Computing Inc, Keno Fischer +.\" Description based on include/uapi/fuse.h and code in fs/fuse +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FUSE 4 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +fuse \- Filesystem in Userspace (FUSE) device +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +.PP +This device is the primary interface between the FUSE filesystem driver +and a user-space process wishing to provide the filesystem (referred to +in the rest of this manual page as the +.IR "filesystem daemon" ). +This manual page is intended for those +interested in understanding the kernel interface itself. +Those implementing a FUSE filesystem may wish to make use of +a user-space library such as +.I libfuse +that abstracts away the low-level interface. +.PP +At its core, FUSE is a simple client-server protocol, in which the Linux +kernel is the client and the daemon is the server. +After obtaining a file descriptor for this device, the daemon may +.BR read (2) +requests from that file descriptor and is expected to +.BR write (2) +back its replies. +It is important to note that a file descriptor is +associated with a unique FUSE filesystem. +In particular, opening a second copy of this device, +will not allow access to resources created +through the first file descriptor (and vice versa). +.\" +.SS The basic protocol +Every message that is read by the daemon begins with a header described by +the following structure: +.PP +.in +4n +.EX +struct fuse_in_header { + uint32_t len; /* Total length of the data, + including this header */ + uint32_t opcode; /* The kind of operation (see below) */ + uint64_t unique; /* A unique identifier for this request */ + uint64_t nodeid; /* ID of the filesystem object + being operated on */ + uint32_t uid; /* UID of the requesting process */ + uint32_t gid; /* GID of the requesting process */ + uint32_t pid; /* PID of the requesting process */ + uint32_t padding; +}; +.EE +.in +.PP +The header is followed by a variable-length data portion +(which may be empty) specific to the requested operation +(the requested operation is indicated by +.IR opcode ). +.PP +The daemon should then process the request and if applicable send +a reply (almost all operations require a reply; if they do not, +this is documented below), by performing a +.BR write (2) +to the file descriptor. +All replies must start with the following header: +.PP +.in +4n +.EX +struct fuse_out_header { + uint32_t len; /* Total length of data written to + the file descriptor */ + int32_t error; /* Any error that occurred (0 if none) */ + uint64_t unique; /* The value from the + corresponding request */ +}; +.EE +.in +.PP +This header is also followed by (potentially empty) variable-sized +data depending on the executed request. +However, if the reply is an error reply (i.e., +.I error +is set), +then no further payload data should be sent, independent of the request. +.\" +.SS Exchanged messages +This section should contain documentation for each of the messages +in the protocol. +This manual page is currently incomplete, +so not all messages are documented. +For each message, first the struct sent by the kernel is given, +followed by a description of the semantics of the message. +.TP +.BR FUSE_INIT +.IP +.in +4n +.EX +struct fuse_init_in { + uint32_t major; + uint32_t minor; + uint32_t max_readahead; /* Since protocol v7.6 */ + uint32_t flags; /* Since protocol v7.6 */ +}; +.EE +.in +.IP +This is the first request sent by the kernel to the daemon. +It is used to negotiate the protocol version and other filesystem parameters. +Note that the protocol version may affect the layout of any structure +in the protocol (including this structure). +The daemon must thus remember the negotiated version +and flags for each session. +As of the writing of this man page, +the highest supported kernel protocol version is +.IR 7.26 . +.IP +Users should be aware that the descriptions in this manual page +may be incomplete or incorrect for older or more recent protocol versions. +.IP +The reply for this request has the following format: +.IP +.in +4n +.EX +struct fuse_init_out { + uint32_t major; + uint32_t minor; + uint32_t max_readahead; /* Since v7.6 */ + uint32_t flags; /* Since v7.6; some flags bits + were introduced later */ + uint16_t max_background; /* Since v7.13 */ + uint16_t congestion_threshold; /* Since v7.13 */ + uint32_t max_write; /* Since v7.5 */ + uint32_t time_gran; /* Since v7.6 */ + uint32_t unused[9]; +}; +.EE +.in +.IP +If the major version supported by the kernel is larger than that supported +by the daemon, the reply shall consist of only +.I uint32_t major +(following the usual header), +indicating the largest major version supported by the daemon. +The kernel will then issue a new +.B FUSE_INIT +request conforming to the older version. +In the reverse case, the daemon should +quietly fall back to the kernel's major version. +.IP +The negotiated minor version is considered to be the minimum +of the minor versions provided by the daemon and the kernel and +both parties should use the protocol corresponding to said minor version. +.TP +.BR FUSE_GETATTR +.IP +.in +4n +.EX +struct fuse_getattr_in { + uint32_t getattr_flags; + uint32_t dummy; + uint64_t fh; /* Set only if + (getattr_flags & FUSE_GETATTR_FH) +}; +.EE +.in +.IP +The requested operation is to compute the attributes to be returned +by +.BR stat (2) +and similar operations for the given file system object. +The object for which the attributes should be computed is indicated +either by +.IR header\->nodeid +or, if the +.IR FUSE_GETATTR_FH +flag is set, by the file handle +.IR fh. +The latter case of operation is analogous to +.BR fstat (2). +.IP +For performance reasons, these attributes may be cached in the kernel for +a specified duration of time. +While the cache timeout has not been exceeded, +the attributes will be served from the cache and will not cause additional +.B FUSE_GETATTR +requests. +.IP +The computed attributes and the requested +cache timeout should then be returned in the following structure: +.IP +.in +4n +.EX +struct fuse_attr_out { + /* Attribute cache duration (seconds + nanoseconds) */ + uint64_t attr_valid; + uint32_t attr_valid_nsec; + uint32_t dummy; + struct fuse_attr { + uint64_t ino; + uint64_t size; + uint64_t blocks; + uint64_t atime; + uint64_t mtime; + uint64_t ctime; + uint32_t atimensec; + uint32_t mtimensec; + uint32_t ctimensec; + uint32_t mode; + uint32_t nlink; + uint32_t uid; + uint32_t gid; + uint32_t rdev; + uint32_t blksize; + uint32_t padding; + } attr; +}; +.EE +.in +.IP +.TP +.BR FUSE_ACCESS +.IP +.in +4n +.EX +struct fuse_access_in { + uint32_t mask; + uint32_t padding; +}; +.EE +.in +.IP +If the +.I default_permissions +mount options is not used, this request may be used for permissions checking. +No reply data is expected, but errors may be indicated +as usual by setting the +.I error +field in the reply header (in particular, access denied errors +may be indicated by returning +.BR \-EACCES ). +.TP +.BR FUSE_OPEN " and " FUSE_OPENDIR +.in +4n +.EX +struct fuse_open_in { + uint32_t flags; /* The flags that were passed + to the open(2) */ + uint32_t unused; +}; +.EE +.in +.IP +The requested operation is to open the node indicated by +.IR header\->nodeid . +The exact semantics of what this means will depend on the +filesystem being implemented. +However, at the very least the +filesystem should validate that the requested +.I flags +are valid for the indicated resource and then send a reply with the +following format: +.IP +.IP +.in +4n +.EX +struct fuse_open_out { + uint64_t fh; + uint32_t open_flags; + uint32_t padding; +}; +.EE +.in +.IP +.IP +The +.I fh +field is an opaque identifier that the kernel will use to refer +to this resource +The +.I open_flags +field is a bit mask of any number of the flags +that indicate properties of this file handle to the kernel: +.RS 7 +.TP 18 +.BR FOPEN_DIRECT_IO +Bypass page cache for this open file. +.TP +.BR FOPEN_KEEP_CACHE +Don't invalidate the data cache on open. +.TP +.BR FOPEN_NONSEEKABLE +The file is not seekable. +.RE +.TP +.BR FUSE_READ " and " FUSE_READDIR +.IP +.in +4n +.EX +struct fuse_read_in { + uint64_t fh; + uint64_t offset; + uint32_t size; + uint32_t read_flags; + uint64_t lock_owner; + uint32_t flags; + uint32_t padding; +}; +.EE +.in +.IP +.IP +The requested action is to read up to +.I size +bytes of the file or directory, starting at +.IR offset . +The bytes should be returned directly following the usual reply header. +.TP +.BR FUSE_INTERRUPT +.in +4n +.EX +struct fuse_interrupt_in { + uint64_t unique; +}; +.EE +.in +.IP +The requested action is to cancel the pending operation indicated by +.IR unique . +This request requires no response. +However, receipt of this message does +not by itself cancel the indicated operation. +The kernel will still expect a reply to said operation (e.g., an +.I EINTR +error or a short read). +At most one +.B FUSE_INTERRUPT +request will be issued for a given operation. +After issuing said operation, +the kernel will wait uninterruptibly for completion of the indicated request. +.TP +.BR FUSE_LOOKUP +Directly following the header is a filename to be looked up in the directory +indicated by +.IR header\->nodeid . +The expected reply is of the form: +.IP +.in +4n +.EX +struct fuse_entry_out { + uint64_t nodeid; /* Inode ID */ + uint64_t generation; /* Inode generation */ + uint64_t entry_valid; + uint64_t attr_valid; + uint32_t entry_valid_nsec; + uint32_t attr_valid_nsec; + struct fuse_attr attr; +}; +.EE +.in +.IP +The combination of +.I nodeid +and +.I generation +must be unique for the filesystem's lifetime. +.IP +The interpretation of timeouts and +.I attr +is as for +.BR FUSE_GETATTR . +.TP +.BR FUSE_FLUSH +.in +4n +.EX +struct fuse_flush_in { + uint64_t fh; + uint32_t unused; + uint32_t padding; + uint64_t lock_owner; +}; +.EE +.in +.IP +The requested action is to flush any pending changes to the indicated +file handle. +No reply data is expected. +However, an empty reply message +still needs to be issued once the flush operation is complete. +.TP +.BR FUSE_RELEASE " and " FUSE_RELEASEDIR +.in +4n +.EX +struct fuse_release_in { + uint64_t fh; + uint32_t flags; + uint32_t release_flags; + uint64_t lock_owner; +}; +.EE +.in +.IP +These are the converse of +.BR FUSE_OPEN +and +.BR FUSE_OPENDIR +respectively. +The daemon may now free any resources associated with the +file handle +.I fh +as the kernel will no longer refer to it. +There is no reply data associated with this request, +but a reply still needs to be issued once the request has +been completely processed. +.TP +.BR FUSE_STATFS +This operation implements +.BR statfs (2) +for this filesystem. +There is no input data associated with this request. +The expected reply data has the following structure: +.IP +.in +4n +.EX +struct fuse_kstatfs { + uint64_t blocks; + uint64_t bfree; + uint64_t bavail; + uint64_t files; + uint64_t ffree; + uint32_t bsize; + uint32_t namelen; + uint32_t frsize; + uint32_t padding; + uint32_t spare[6]; +}; + +struct fuse_statfs_out { + struct fuse_kstatfs st; +}; +.EE +.in +.IP +For the interpretation of these fields, see +.BR statfs (2). +.SH ERRORS +.TP +.B E2BIG +Returned from +.BR read (2) +operations when the kernel's request is too large for the provided buffer +and the request was +.BR FUSE_SETXATTR . +.TP +.B EINVAL +Returned from +.BR write (2) +if validation of the reply failed. +Not all mistakes in replies will be caught by this validation. +However, basic mistakes, such as short replies or an incorrect +.I unique +value, are detected. +.TP +.B EIO +Returned from +.BR read (2) +operations when the kernel's request is too large for the provided buffer. +.IP +.IR Note : +There are various ways in which incorrect use of these interfaces can cause +operations on the provided filesystem's files and directories to fail with +.BR EIO . +Among the possible incorrect uses are: +.RS +.IP * 3 +changing +.I mode & S_IFMT +for an inode that has previously been reported to the kernel; or +.IP * +giving replies to the kernel that are shorter than what the kernel expected. +.RE +.TP +.B ENODEV +Returned from +.BR read (2) +and +.BR write (2) +if the FUSE filesystem was unmounted. +.TP +.B EPERM +Returned from operations on a +.I /dev/fuse +file descriptor that has not been mounted. +.SH CONFORMING TO +The FUSE filesystem is Linux-specific. +.SH NOTES +The following messages are not yet documented in this manual page: +.PP +.\" FIXME: Document the following. +.in +4n +.EX +.BR FUSE_BATCH_FORGET +.BR FUSE_BMAP +.BR FUSE_CREATE +.BR FUSE_DESTROY +.BR FUSE_FALLOCATE +.BR FUSE_FORGET +.BR FUSE_FSYNC +.BR FUSE_FSYNCDIR +.BR FUSE_GETLK +.BR FUSE_GETXATTR +.BR FUSE_IOCTL +.BR FUSE_LINK +.BR FUSE_LISTXATTR +.BR FUSE_LSEEK +.BR FUSE_MKDIR +.BR FUSE_MKNOD +.BR FUSE_NOTIFY_REPLY +.BR FUSE_POLL +.BR FUSE_READDIRPLUS +.BR FUSE_READLINK +.BR FUSE_REMOVEXATTR +.BR FUSE_RENAME +.BR FUSE_RENAME2 +.BR FUSE_RMDIR +.BR FUSE_SETATTR +.BR FUSE_SETLK +.BR FUSE_SETLKW +.BR FUSE_SYMLINK +.BR FUSE_UNLINK +.BR FUSE_WRITE +.EE +.in +.SH SEE ALSO +.BR fusermount (1), +.BR mount.fuse (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/hd.4 b/man4/hd.4 new file mode 100644 index 0000000..254b5ca --- /dev/null +++ b/man4/hd.4 @@ -0,0 +1,110 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 16:56:20 1993 by Rik Faith +.\" Modified Mon Oct 21 21:38:51 1996 by Eric S. Raymond +.\" (and some more by aeb) +.\" +.TH HD 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +hd \- MFM/IDE hard disk devices +.SH DESCRIPTION +The +.B hd* +devices are block devices to access MFM/IDE hard disk drives +in raw mode. +The master drive on the primary IDE controller (major device +number 3) is +.BR hda ; +the slave drive is +.BR hdb . +The master drive of the second controller (major device number 22) +is +.B hdc +and the slave is +.BR hdd . +.PP +General IDE block device names have the form +.BI hd X\c +, or +.BI hd XP\c +, where +.I X +is a letter denoting the physical drive, and +.I P +is a number denoting the partition on that physical drive. +The first form, +.BI hd X\c +, is used to address the whole drive. +Partition numbers are assigned in the order the partitions +are discovered, and only nonempty, nonextended partitions +get a number. +However, partition numbers 1\(en4 are given to the +four partitions described in the MBR (the "primary" partitions), +regardless of whether they are unused or extended. +Thus, the first logical partition will be +.BI hd X 5\c +\&. +Both DOS-type partitioning and BSD-disklabel partitioning are supported. +You can have at most 63 partitions on an IDE disk. +.PP +For example, +.I /dev/hda +refers to all of the first IDE drive in the system; and +.I /dev/hdb3 +refers to the third DOS "primary" partition on the second one. +.PP +They are typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/hda b 3 0 +mknod \-m 660 /dev/hda1 b 3 1 +mknod \-m 660 /dev/hda2 b 3 2 +\&... +mknod \-m 660 /dev/hda8 b 3 8 +mknod \-m 660 /dev/hdb b 3 64 +mknod \-m 660 /dev/hdb1 b 3 65 +mknod \-m 660 /dev/hdb2 b 3 66 +\&... +mknod \-m 660 /dev/hdb8 b 3 72 +chown root:disk /dev/hd* +.EE +.in +.SH FILES +.I /dev/hd* +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR sd (4), +.BR mount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/hpsa.4 b/man4/hpsa.4 new file mode 100644 index 0000000..f011205 --- /dev/null +++ b/man4/hpsa.4 @@ -0,0 +1,245 @@ +.\" Copyright (C) 2011, Hewlett-Packard Development Company, L.P. +.\" Written by Stephen M. Cameron +.\" +.\" %%%LICENSE_START(GPLv2_ONELINE) +.\" Licensed under GNU General Public License version 2 (GPLv2) +.\" %%%LICENSE_END +.\" +.\" shorthand for double quote that works everywhere. +.ds q \N'34' +.TH HPSA 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +hpsa \- HP Smart Array SCSI driver +.SH SYNOPSIS +.nf +modprobe hpsa [ hpsa_allow_any=1 ] +.fi +.SH DESCRIPTION +.B hpsa +is a SCSI driver for HP Smart Array RAID controllers. +.SS Options +.IR "hpsa_allow_any=1" : +This option allows the driver to attempt to operate on +any HP Smart Array hardware RAID controller, +even if it is not explicitly known to the driver. +This allows newer hardware to work with older drivers. +Typically this is used to allow installation of +operating systems from media that predates the +RAID controller, though it may also be used to enable +.B hpsa +to drive older controllers that would normally be handled by the +.BR cciss (4) +driver. +These older boards have not been tested and are +not supported with +.BR hpsa , +and +.BR cciss (4) +should still be used for these. +.SS Supported hardware +The +.B hpsa +driver supports the following Smart Array boards: +.PP +.nf + Smart Array P700M + Smart Array P212 + Smart Array P410 + Smart Array P410i + Smart Array P411 + Smart Array P812 + Smart Array P712m + Smart Array P711m + StorageWorks P1210m +.fi +.PP +.\" commit 135ae6edeb51979d0998daf1357f149a7d6ebb08 +Since Linux 4.14, the following Smart Array boards are also supported: +.PP +.nf + Smart Array 5300 + Smart Array 5312 + Smart Array 532 + Smart Array 5i + Smart Array 6400 + Smart Array 6400 EM + Smart Array 641 + Smart Array 642 + Smart Array 6i + Smart Array E200 + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E500 + Smart Array P400 + Smart Array P400i + Smart Array P600 + Smart Array P700m + Smart Array P800 +.fi +.SS Configuration details +To configure HP Smart Array controllers, +use the HP Array Configuration Utility (either +.BR hpacuxe (8) +or +.BR hpacucli (8)) +or the Offline ROM-based Configuration Utility (ORCA) +run from the Smart Array's option ROM at boot time. +.SH FILES +.SS Device nodes +Logical drives are accessed via the SCSI disk driver +.RB ( sd (4)), +tape drives via the SCSI tape driver +.RB ( st (4)), +and +the RAID controller via the SCSI generic driver +.RB ( sg (4)), +with device nodes named +.IR /dev/sd* , +.IR /dev/st* , +and +.IR /dev/sg* , +respectively. +.SS HPSA-specific host attribute files in /sys +.TP +.I /sys/class/scsi_host/host*/rescan +This is a write-only attribute. +Writing to this attribute will cause the driver to scan for +new, changed, or removed devices (e.g., hot-plugged tape drives, +or newly configured or deleted logical drives, etc.) +and notify the SCSI midlayer of any changes detected. +Normally a rescan is triggered automatically +by HP's Array Configuration Utility (either the GUI or the +command-line variety); +thus, for logical drive changes, the user should not +normally have to use this attribute. +This attribute may be useful when hot plugging devices like tape drives, +or entire storage boxes containing preconfigured logical drives. +.TP +.I /sys/class/scsi_host/host*/firmware_revision +This attribute contains the firmware version of the Smart Array. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_host/host4\fP +# \fBcat firmware_revision\fP +7.14 +.EE +.in +.\" +.SS HPSA-specific disk attribute files in /sys +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/unique_id +This attribute contains a 32 hex-digit unique ID for each logical drive. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat unique_id\fP +600508B1001044395355323037570F77 +.EE +.in +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/raid_level +This attribute contains the RAID level of each logical drive. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat raid_level\fP +RAID 0 +.EE +.in +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/lunid +This attribute contains the 16 hex-digit (8 byte) LUN ID +by which a logical drive or physical device can be addressed. +.IR c : b : t : l +are the controller, bus, target, and lun of the device. +.PP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat lunid\fP +0x0000004000000000 +.EE +.in +.\" +.SS Supported ioctl() operations +For compatibility with applications written for the +.BR cciss (4) +driver, many, but +not all of the ioctls supported by the +.BR cciss (4) +driver are also supported by the +.B hpsa +driver. +The data structures used by these ioctls are described in +the Linux kernel source file +.IR include/linux/cciss_ioctl.h . +.TP +.BR CCISS_DEREGDISK ", " CCISS_REGNEWDISK ", " CCISS_REGNEWD +These three ioctls all do exactly the same thing, +which is to cause the driver to rescan for new devices. +This does exactly the same thing as writing to the +hpsa-specific host "rescan" attribute. +.TP +.B CCISS_GETPCIINFO +Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID). +.TP +.B CCISS_GETDRIVVER +Returns driver version in three bytes encoded as: +.IP +.in +4n +.EX +(major_version << 16) | (minor_version << 8) | + (subminor_version) +.EE +.in +.TP +.BR CCISS_PASSTHRU ", " CCISS_BIG_PASSTHRU +Allows "BMIC" and "CISS" commands to be passed through to the Smart Array. +These are used extensively by the HP Array Configuration Utility, +SNMP storage agents, and so on. +See +.I cciss_vol_status +at +.UR http://cciss.sf.net +.UE +for some examples. +.SH SEE ALSO +.BR cciss (4), +.BR sd (4), +.BR st (4), +.BR cciss_vol_status (8), +.BR hpacucli (8), +.BR hpacuxe (8), +.PP +.UR http://cciss.sf.net +.UE , +and +.I Documentation/scsi/hpsa.txt +and +.I Documentation/ABI/testing/sysfs-bus-pci-devices-cciss +in the Linux kernel source tree +.\" .SH AUTHORS +.\" Don Brace, Steve Cameron, Tom Lawler, Mike Miller, Scott Teel +.\" and probably some other people. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/initrd.4 b/man4/initrd.4 new file mode 100644 index 0000000..92aff16 --- /dev/null +++ b/man4/initrd.4 @@ -0,0 +1,508 @@ +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and author(s) of this work. +.\" %%%LICENSE_END +.\" +.\" If the you wish to distribute versions of this work under other +.\" conditions than the above, please contact the author(s) at the following +.\" for permission: +.\" +.\" John S. Kallal - +.\" email: +.\" mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA +.\" phone: (302)654-5478 +.\" +.\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $ +.TH INITRD 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +initrd \- boot loader initialized RAM disk +.SH CONFIGURATION +.I /dev/initrd +is a read-only block device assigned +major number 1 and minor number 250. +Typically +.I /dev/initrd +is owned by +.I root.disk +with mode 0400 (read access by root only). +If the Linux system does not have +.I /dev/initrd +already created, it can be created with the following commands: +.PP +.in +4n +.EX +mknod \-m 400 /dev/initrd b 1 250 +chown root:disk /dev/initrd +.EE +.in +.PP +Also, support for both "RAM disk" and "Initial RAM disk" +(e.g., +.BR CONFIG_BLK_DEV_RAM=y +and +.BR CONFIG_BLK_DEV_INITRD=y ) +must be compiled directly into the Linux kernel to use +.IR /dev/initrd . +When using +.IR /dev/initrd , +the RAM disk driver cannot be loaded as a module. +.\" +.\" +.\" +.SH DESCRIPTION +The special file +.I /dev/initrd +is a read-only block device. +This device is a RAM disk that is initialized (e.g., loaded) +by the boot loader before the kernel is started. +The kernel then can use +.IR /dev/initrd "'s " +contents for a two-phase system boot-up. +.PP +In the first boot-up phase, the kernel starts up +and mounts an initial root filesystem from the contents of +.I /dev/initrd +(e.g., RAM disk initialized by the boot loader). +In the second phase, additional drivers or other modules +are loaded from the initial root device's contents. +After loading the additional modules, a new root filesystem +(i.e., the normal root filesystem) is mounted from a +different device. +.\" +.\" +.\" +.SS Boot-up operation +When booting up with +.BR initrd , +the system boots as follows: +.IP 1. 3 +The boot loader loads the kernel program and +.IR /dev/initrd 's +contents into memory. +.IP 2. +On kernel startup, +the kernel uncompresses and copies the contents of the device +.I /dev/initrd +onto device +.I /dev/ram0 +and then frees the memory used by +.IR /dev/initrd . +.IP 3. +The kernel then read-write mounts the device +.I /dev/ram0 +as the initial root filesystem. +.IP 4. +If the indicated normal root filesystem is also the initial +root filesystem (e.g., +.IR /dev/ram0 ) +then the kernel skips to the last step for the usual boot sequence. +.IP 5. +If the executable file +.IR /linuxrc +is present in the initial root filesystem, +.I /linuxrc +is executed with UID 0. +(The file +.I /linuxrc +must have executable permission. +The file +.I /linuxrc +can be any valid executable, including a shell script.) +.IP 6. +If +.I /linuxrc +is not executed or when +.I /linuxrc +terminates, the normal root filesystem is mounted. +(If +.I /linuxrc +exits with any filesystems mounted on the initial root +filesystem, then the behavior of the kernel is +.BR UNSPECIFIED . +See the NOTES section for the current kernel behavior.) +.IP 7. +If the normal root filesystem has a directory +.IR /initrd , +the device +.I /dev/ram0 +is moved from +.IR / +to +.IR /initrd . +Otherwise, if the directory +.IR /initrd +does not exist, the device +.I /dev/ram0 +is unmounted. +(When moved from +.IR / +to +.IR /initrd , +.I /dev/ram0 +is not unmounted and therefore processes can remain running from +.IR /dev/ram0 . +If directory +.I /initrd +does not exist on the normal root filesystem +and any processes remain running from +.IR /dev/ram0 +when +.I /linuxrc +exits, the behavior of the kernel is +.BR UNSPECIFIED . +See the NOTES section for the current kernel behavior.) +.IP 8. +The usual boot sequence (e.g., invocation of +.IR /sbin/init ) +is performed on the normal root filesystem. +.\" +.\" +.\" +.SS Options +The following boot loader options, when used with +.BR initrd , +affect the kernel's boot-up operation: +.TP +.BI initrd= "filename" +Specifies the file to load as the contents of +.IR /dev/initrd . +For +.B LOADLIN +this is a command-line option. +For +.B LILO +you have to use this command in the +.B LILO +configuration file +.IR /etc/lilo.config . +The filename specified with this +option will typically be a gzipped filesystem image. +.TP +.I noinitrd +This boot option disables the two-phase boot-up operation. +The kernel performs the usual boot sequence as if +.I /dev/initrd +was not initialized. +With this option, any contents of +.I /dev/initrd +loaded into memory by the boot loader contents are preserved. +This option permits the contents of +.I /dev/initrd +to be any data and need not be limited to a filesystem image. +However, device +.I /dev/initrd +is read-only and can be read only one time after system startup. +.TP +.BI root= "device-name" +Specifies the device to be used as the normal root filesystem. +For +.B LOADLIN +this is a command-line option. +For +.B LILO +this is a boot time option or +can be used as an option line in the +.B LILO +configuration file +.IR /etc/lilo.config . +The device specified by the this option must be a mountable +device having a suitable root filesystem. +.\" +.\" +.\" +.SS Changing the normal root filesystem +By default, +the kernel's settings +(e.g., set in the kernel file with +.BR rdev (8) +or compiled into the kernel file), +or the boot loader option setting +is used for the normal root filesystems. +For an NFS-mounted normal root filesystem, one has to use the +.B nfs_root_name +and +.B nfs_root_addrs +boot options to give the NFS settings. +For more information on NFS-mounted root see the kernel documentation file +.I Documentation/filesystems/nfs/nfsroot.txt +.\" commit dc7a08166f3a5f23e79e839a8a88849bd3397c32 +(or +.I Documentation/filesystems/nfsroot.txt +before Linux 2.6.33). +For more information on setting the root filesystem see also the +.BR LILO +and +.BR LOADLIN +documentation. +.PP +It is also possible for the +.I /linuxrc +executable to change the normal root device. +For +.I /linuxrc +to change the normal root device, +.IR /proc +must be mounted. +After mounting +.IR /proc , +.I /linuxrc +changes the normal root device by writing into the proc files +.IR /proc/sys/kernel/real-root-dev , +.IR /proc/sys/kernel/nfs-root-name , +and +.IR /proc/sys/kernel/nfs-root-addrs . +For a physical root device, the root device is changed by having +.I /linuxrc +write the new root filesystem device number into +.IR /proc/sys/kernel/real-root-dev . +For an NFS root filesystem, the root device is changed by having +.I /linuxrc +write the NFS setting into files +.IR /proc/sys/kernel/nfs-root-name +and +.I /proc/sys/kernel/nfs-root-addrs +and then writing 0xff (e.g., the pseudo-NFS-device number) into file +.IR /proc/sys/kernel/real-root-dev . +For example, the following shell command line would change +the normal root device to +.IR /dev/hdb1 : +.PP +.in +4n +.EX +echo 0x365 >/proc/sys/kernel/real-root-dev +.EE +.in +.PP +For an NFS example, the following shell command lines would change the +normal root device to the NFS directory +.I /var/nfsroot +on a local networked NFS server with IP number 193.8.232.7 for a system with +IP number 193.8.232.2 and named "idefix": +.PP +.in +4n +.EX +echo /var/nfsroot >/proc/sys/kernel/nfs-root-name +echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \\ + >/proc/sys/kernel/nfs-root-addrs +echo 255 >/proc/sys/kernel/real-root-dev +.EE +.in +.PP +.BR Note : +The use of +.I /proc/sys/kernel/real-root-dev +to change the root filesystem is obsolete. +See the Linux kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10) +as well as +.BR pivot_root (2) +and +.BR pivot_root (8) +for information on the modern method of changing the root filesystem. +.\" FIXME . Should this manual page describe the pivot_root mechanism? +.\" +.\" +.\" +.SS Usage +The main motivation for implementing +.B initrd +was to allow for modular kernel configuration at system installation. +.PP +A possible system installation scenario is as follows: +.IP 1. 3 +The loader program boots from floppy or other media with a minimal kernel +(e.g., support for +.IR /dev/ram , +.IR /dev/initrd , +and the ext2 filesystem) and loads +.IR /dev/initrd +with a gzipped version of the initial filesystem. +.IP 2. +The executable +.I /linuxrc +determines what is needed to (1) mount the normal root filesystem +(i.e., device type, device drivers, filesystem) and (2) the +distribution media (e.g., CD-ROM, network, tape, ...). +This can be done by asking the user, by auto-probing, +or by using a hybrid approach. +.IP 3. +The executable +.I /linuxrc +loads the necessary modules from the initial root filesystem. +.IP 4. +The executable +.I /linuxrc +creates and populates the root filesystem. +(At this stage the normal root filesystem does not have to be a +completed system yet.) +.IP 5. +The executable +.IR /linuxrc +sets +.IR /proc/sys/kernel/real-root-dev , +unmount +.IR /proc , +the normal root filesystem and any other filesystems +it has mounted, and then terminates. +.IP 6. +The kernel then mounts the normal root filesystem. +.IP 7. +Now that the filesystem is accessible and intact, +the boot loader can be installed. +.IP 8. +The boot loader is configured to load into +.I /dev/initrd +a filesystem with the set of modules that was used to bring up the system. +(e.g., Device +.I /dev/ram0 +can be modified, then unmounted, and finally, the image is written from +.I /dev/ram0 +to a file.) +.IP 9. +The system is now bootable and additional installation tasks can be +performed. +.PP +The key role of +.I /dev/initrd +in the above is to reuse the configuration data during normal system operation +without requiring initial kernel selection, a large generic kernel or, +recompiling the kernel. +.PP +A second scenario is for installations where Linux runs on systems with +different hardware configurations in a single administrative network. +In such cases, it may be desirable to use only a small set of kernels +(ideally only one) and to keep the system-specific part of configuration +information as small as possible. +In this case, create a common file +with all needed modules. +Then, only the +.I /linuxrc +file or a file executed by +.I /linuxrc +would be different. +.PP +A third scenario is more convenient recovery disks. +Because information like the location of the root filesystem +partition is not needed at boot time, the system loaded from +.I /dev/initrd +can use a dialog and/or auto-detection followed by a +possible sanity check. +.PP +Last but not least, Linux distributions on CD-ROM may use +.B initrd +for easy installation from the CD-ROM. +The distribution can use +.B LOADLIN +to directly load +.I /dev/initrd +from CD-ROM without the need of any floppies. +The distribution could also use a +.B LILO +boot floppy and then bootstrap a bigger RAM disk via +.IR /dev/initrd +from the CD-ROM. +.\" +.\" +.\" +.SH FILES +.I /dev/initrd +.br +.I /dev/ram0 +.br +.I /linuxrc +.br +.I /initrd +.\" +.\" +.\" +.SH NOTES +.IP 1. 3 +With the current kernel, any filesystems that remain mounted when +.I /dev/ram0 +is moved from +.I / +to +.I /initrd +continue to be accessible. +However, the +.I /proc/mounts +entries are not updated. +.IP 2. +With the current kernel, if directory +.I /initrd +does not exist, then +.I /dev/ram0 +will +.B not +be fully unmounted if +.I /dev/ram0 +is used by any process or has any filesystem mounted on it. +If +.IR /dev/ram0 +is +.B not +fully unmounted, then +.I /dev/ram0 +will remain in memory. +.IP 3. +Users of +.I /dev/initrd +should not depend on the behavior give in the above notes. +The behavior may change in future versions of the Linux kernel. +.\" +.\" +.\" +.\" .SH AUTHORS +.\" The kernel code for device +.\" .BR initrd +.\" was written by Werner Almesberger and +.\" Hans Lermen . +.\" The code for +.\" .BR initrd +.\" was added to the baseline Linux kernel in development version 1.3.73. +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ram (4), +.BR freeramdisk (8), +.BR rdev (8) +.PP +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10) +in the Linux kernel source tree, the LILO documentation, +the LOADLIN documentation, the SYSLINUX documentation +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/intro.4 b/man4/intro.4 new file mode 100644 index 0000000..3bc86be --- /dev/null +++ b/man4/intro.4 @@ -0,0 +1,50 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 16:57:14 1993 by Rik Faith (faith@cs.unc.edu) +.TH INTRO 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- introduction to special files +.SH DESCRIPTION +Section 4 of the manual describes special files (devices). +.SH FILES +/dev/* \(em device files +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR mknod (1), +.BR mknod (2), +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/kmem.4 b/man4/kmem.4 new file mode 100644 index 0000000..d4c1762 --- /dev/null +++ b/man4/kmem.4 @@ -0,0 +1 @@ +.so man4/mem.4 diff --git a/man4/lirc.4 b/man4/lirc.4 new file mode 100644 index 0000000..25e1155 --- /dev/null +++ b/man4/lirc.4 @@ -0,0 +1,484 @@ +.\" Copyright (c) 2015-2016, Alec Leamas +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH LIRC 4 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +lirc \- lirc devices +.SH DESCRIPTION +.PP +The +.B /dev/lirc* +character devices provide a low-level +bi-directional interface to infra-red (IR) remotes. +When receiving data, the driver works in two different modes depending +on the underlying hardware. +.PP +Some hardware (typically TV-cards) decodes the IR signal internally +and just provides decoded button presses as integer values. +Drivers for this kind of hardware work in +.BR LIRC_MODE_LIRCCODE +mode. +Such hardware usually does not support sending IR signals. +Furthermore, it usually only works with a specific remote which is +bundled with, for example, a TV-card. +.PP +Other hardware provides a stream of pulse/space durations. +Such drivers work in +.BR LIRC_MODE_MODE2 +mode. +Sometimes, this kind of hardware also supports +sending IR data. +Such hardware can be used with (almost) any kind of remote. +.PP +The \fBLIRC_GET_REC_MODE\fR ioctl (see below) allows probing for the +mode. +.\" +.SS Reading input with the LIRC_MODE_MODE2 drivers +.PP +In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by +.BR read (2) +provides 32-bit values representing a space or a pulse duration, by +convention typed as +.IR lirc_t . +The time of the duration (microseconds) is encoded in the lower 24 bits. +The upper 8 bit reflects the type of package: +.TP 4 +.BR LIRC_MODE2_SPACE . +Value reflects a space duration (microseconds). +.TP 4 +.BR LIRC_MODE2_PULSE . +Value reflects a pulse duration (microseconds). +.TP 4 +.BR LIRC_MODE2_FREQUENCY . +Value reflects a frequency (Hz); see the +.B LIRC_SET_MEASURE_CARRIER_MODE +ioctl. +.TP 4 +.BR LIRC_MODE2_TIMEOUT . +The package reflects a timeout; see the +.B LIRC_SET_REC_TIMEOUT_REPORTS +ioctl. +.\" +.SS Reading input with the +.B LIRC_MODE_LIRCCODE +drivers +.PP +In the \fBLIRC_MODE_LIRCCODE\fR +mode, the data returned by +.BR read (2) +reflects decoded button presses. +The length of each packet can be retrieved using +the \fBLIRC_GET_LENGTH\fR ioctl. +Reads must be done in blocks matching +the bit count returned by the \fBLIRC_GET_LENGTH\fR ioctl, rounded +up so it matches full bytes. +.\" +.SS Sending data +.PP +When sending data, only the \fBLIRC_MODE_PULSE\fR +mode is supported. +The data written to the character device using +.BR write (2) +is a pulse/space sequence of integer values. +Pulses and spaces are only marked implicitly by their position. +The data must start and end with a pulse, thus it must always include +an odd number of samples. +The +.BR write (2) +function blocks until the data has been transmitted by the +hardware. +If more data is provided than the hardware can send, the +.BR write (2) +call fails with the error +.BR EINVAL +.\" +.SH IOCTL COMMANDS +.PP +The complete list of ioctl commands is maintained in the kernel +documentation, see SEE ALSO. +The ioctl commands presented here is a subset of the kernel +documentation. +.PP +The LIRC device's ioctl definition is bound by the ioctl function +definition of struct file_operations, leaving us with an unsigned +int for the ioctl command and an unsigned long for the argument. +For the purposes of ioctl portability across 32-bit and 64-bit architectures, +these values are capped to their 32-bit sizes. +.PP +.nf +#include /* But see BUGS */ +int ioctl(int fd, int cmd, ...); +.fi +.PP +The following ioctls can be used to probe or change specific lirc +hardware settings. +Many require a third argument, usually an +.IR int . +referred to below as +.IR val . +.PP +In general, each driver should have a default set of settings. +The driver implementation is expected to re-apply the default settings +when the device is closed by user space, so that every application +opening the device can rely on working with the default settings +initially. +.\" +.SS Always Supported Commands +.PP +\fI/dev/lirc*\fR devices always support the following commands: +.TP 4 +.BR LIRC_GET_FEATURES " (\fIvoid\fP)" +Returns a bit mask of combined features bits; see FEATURES. +Some drivers have dynamic features which are not updated until after an +.I init() +command. +If a driver does not announce support of certain features, calling of +the corresponding ioctls is undefined. +.TP +.BR LIRC_GET_REC_MODE +Return the receive mode, which will be one of: +.RS 4 +.TP +.BR LIRC_MODE_MODE2 " (\fIvoid\fP)" +The driver returns a sequence of pulse/space durations. +.TP +.BR LIRC_MODE_LIRCCODE +The driver returns integer values, each of which represents a decoded +button press. +.RE +.PP +If a device returns an error code for +.BR LIRC_GET_REC_MODE , +it is safe to assume it is not a lirc device. +.\" +.SS Optional Commands +.PP +Some lirc devices support commands listed below. +Unless otherwise stated, these fail with the error \fBENOIOCTLCMD\fR +or with the error \fBENOSYS\fR if the operation +isn't supported, or with the error \fBEINVAL\fR if the operation +failed. +.TP +.BR LIRC_SET_REC_MODE " (\fIint\fP)" +Set the receive mode. +.IR val +is either +.BR LIRC_MODE_LIRCCODE +or +.BR LIRC_MODE_MODE2 . +.TP +.BR LIRC_GET_LENGTH " (\fIvoid\fP)" +Return the length of the returned codes for +.BR LIRC_MODE_LIRCCODE -type +drivers, otherwise fail with the error +.BR ENOIOCTLCMD . +.TP +.BR LIRC_GET_SEND_MODE " (\fIvoid\fP)" +Return the send mode. +Currently, only +.BR LIRC_MODE_PULSE +is supported. +.TP +.BR LIRC_SET_SEND_MODE " (\fIint\fP)" +Set the send mode. +Currently serves no purpose since only +.BR LIRC_MODE_PULSE +is supported. +.TP +.BR LIRC_GET_SEND_CARRIER " (\fIvoid\fP)" +Get the modulation frequency (Hz). +.TP +.BR LIRC_SET_SEND_CARRIER " (\fIint\fP)" +Set the modulation frequency. +The argument is the frequency (Hz). +.TP +.BR LIRC_GET_SEND_CARRIER " (\fIvoid\fP)" +Get the modulation frequency used when decoding (Hz). +.TP +.BR SET_SEND_DUTY_CYCLE " (\fIint\fP)" +Set the carrier duty cycle. +.I val +is a number in the range [0,100] which +describes the pulse width as a percentage of the total cycle. +Currently, no special meaning is defined for 0 or 100, but the values +are reserved for future use. +.IP +.TP +.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\ +LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)" +Some devices have internal timers that can be used to detect when +there's no IR activity for a long time. +This can help +.BR lircd (8) +in detecting that an IR signal is finished and can speed up the +decoding process. +These operations +return integer values with the minimum/maximum timeout that can be +set (microseconds). +Some devices have a fixed timeout. +For such drivers, +.BR LIRC_GET_MIN_TIMEOUT +and +.BR LIRC_GET_MAX_TIMEOUT +will return the same value. +.TP +.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" +Set the integer value for IR inactivity timeout (microseconds). +To be accepted, the value must be within the limits defined by +.BR LIRC_GET_MIN_TIMEOUT +and +.BR LIRC_GET_MAX_TIMEOUT . +A value of 0 (if supported by the hardware) disables all hardware +timeouts and data should be reported as soon as possible. +If the exact value cannot be set, then the next possible value +.I greater +than the given value should be set. +.TP +.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)" +Enable +.RI ( val +is 1) or disable +.RI ( val +is 0) timeout packages in +.BR LIRC_MODE_MODE2 . +By default, timeout reports should be turned off. +.TP +.BR LIRC_SET_REC_CARRIER " (\fIint\fP)" +Set the receive carrier frequency (Hz). +.TP +.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)" +After opening device, the first use of this operation +sets the lower bound of the carrier range, +and the second use sets the upper bound (Hz). +.TP +.BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)" +Enable +.RI ( val +is 1) or disable +.RI ( val +is 0) the measure mode. +If enabled, from the next key press on, the driver will send +.BR LIRC_MODE2_FREQUENCY +packets. +By default this should be turned off. +.TP +.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)" +Return the driver resolution (microseconds). +.TP +.BR LIRC_GET_MIN_FILTER_PULSE " (\fIvoid\fP)", " " \ +LIRC_GET_MAX_FILTER_PULSE " (\fIvoid\fP)" +Some devices are able to filter out spikes in the incoming signal +using given filter rules. +These ioctls return the hardware capabilities that describe the bounds +of the possible filters. +Filter settings depend on the IR protocols that are expected. +.BR lircd (8) +derives the settings from all protocols definitions found in its +.BR lircd.conf (5) +config file. +.TP +.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", " " \ +LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)" +See +.BR LIRC_GET_MIN_FILTER_PULSE . +.TP +.BR LIRC_SET_REC_FILTER " (\fIint\fP)" +Pulses/spaces shorter than this (microseconds) are filtered out by +hardware. +.TP +.BR LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", " " \ +LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)" +Pulses/spaces shorter than this (microseconds) are filtered out by +hardware. +If filters cannot be set independently for pulse/space, the +corresponding ioctls must return an error and +.BR LIRC_SET_REC_FILTER +should be used instead. +.TP +.BR LIRC_SET_TRANSMITTER_MASK +Enable the set of transmitters specified in +.IR val , +which contains a bit mask where each enabled transmitter is a 1. +The first transmitter is encoded by the least significant bit, and so on. +When an invalid bit mask is given, for example a bit is set even +though the device does not have so many transmitters, +this operation returns the +number of available transmitters and does nothing otherwise. +.TP +.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" +Some devices are equipped with a special wide band receiver which is +intended to be used to learn the output of an existing remote. +This ioctl can be used to enable +.RI ( val +equals 1) or disable +.RI ( val +equals 0) this functionality. +This might be useful for devices that otherwise have narrow band +receivers that prevent them to be used with certain remotes. +Wide band receivers may also be more precise. +On the other hand its disadvantage usually is reduced range of +reception. +.IP +Note: wide band receiver may be implicitly enabled if you enable +carrier reports. +In that case, it will be disabled as soon as you disable carrier reports. +Trying to disable a wide band receiver while carrier reports are active +will do nothing. +.TP +.BR LIRC_SETUP_START " (\fIvoid\fP), " LIRC_SETUP_END " (\fIvoid\fP)" +Setting of several driver parameters can be optimized by bracketing +the actual ioctl calls +.BR LIRC_SETUP_START +and +.BR LIRC_SETUP_END . +When a driver receives a +.BR LIRC_SETUP_START +ioctl, it can choose to not commit further setting changes to the +hardware until a +.BR LIRC_SETUP_END +is received. +But this is open to the driver implementation and every driver +must also handle parameter changes which are not encapsulated by +.BR LIRC_SETUP_START +and +.BR LIRC_SETUP_END . +Drivers can also choose to ignore these ioctls. +.TP +.BR LIRC_NOTIFY_DECODE " (\fIvoid\fP)" +This ioctl is called by +.BR lircd (8) +whenever a successful decoding of an incoming IR signal is possible. +This can be used by supporting hardware to give visual user +feedback, for example by flashing an LED. +.\" +.SH FEATURES +.PP +The features returned by +The +.BR LIRC_GET_FEATURES +ioctl returns a bit mask describing features of the driver. +The following bits may be returned in the mask: +.TP +.BR LIRC_CAN_REC_RAW +The driver is capable of receiving using +.BR LIRC_MODE_RAW . +.TP +.BR LIRC_CAN_REC_PULSE +The driver is capable of receiving using +.BR LIRC_MODE_PULSE . +.TP +.BR LIRC_CAN_REC_MODE2 +The driver is capable of receiving using +.BR LIRC_MODE_MODE2 . +.TP +.BR LIRC_CAN_REC_LIRCCODE +The driver is capable of receiving using +.BR LIRC_MODE_LIRCCODE . +.TP +.BR LIRC_CAN_SET_SEND_CARRIER +The driver supports changing the modulation frequency using +.BR LIRC_SET_SEND_CARRIER . +.TP +.BR LIRC_CAN_SET_SEND_DUTY_CYCLE +The driver supports changing the duty cycle using +.BR LIRC_SET_SEND_DUTY_CYCLE . +.TP +.BR LIRC_CAN_SET_TRANSMITTER_MASK +The driver supports changing the active transmitter(s) using +.BR LIRC_SET_TRANSMITTER_MASK . +.TP +.BR LIRC_CAN_SET_REC_CARRIER +The driver supports setting the receive carrier frequency using +.BR LIRC_SET_REC_CARRIER . +.TP +.BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE +The driver supports +.BR LIRC_SET_REC_DUTY_CYCLE_RANGE . +.TP +.BR LIRC_CAN_SET_REC_CARRIER_RANGE +The driver supports +.BR LIRC_SET_REC_CARRIER_RANGE . +.TP +.BR LIRC_CAN_GET_REC_RESOLUTION +The driver supports +.BR LIRC_GET_REC_RESOLUTION . +.TP +.BR LIRC_CAN_SET_REC_TIMEOUT +The driver supports +.BR LIRC_SET_REC_TIMEOUT . +.TP +.BR LIRC_CAN_SET_REC_FILTER +The driver supports +.BR LIRC_SET_REC_FILTER . +.TP +.BR LIRC_CAN_MEASURE_CARRIER +The driver supports measuring of the modulation frequency using +.BR LIRC_SET_MEASURE_CARRIER_MODE . +.TP +.BR LIRC_CAN_USE_WIDEBAND_RECEIVER +The driver supports learning mode using +.BR LIRC_SET_WIDEBAND_RECEIVER . +.TP +.BR LIRC_CAN_NOTIFY_DECODE +The driver supports +.BR LIRC_NOTIFY_DECODE . +.TP +.BR LIRC_CAN_SEND_RAW +The driver supports sending using +.BR LIRC_MODE_RAW . +.TP +.BR LIRC_CAN_SEND_PULSE +The driver supports sending using +.BR LIRC_MODE_PULSE . +.TP +.BR LIRC_CAN_SEND_MODE2 +The driver supports sending using +.BR LIRC_MODE_MODE2 . +.TP +.BR LIRC_CAN_SEND_LIRCCODE +The driver supports sending. +(This is uncommon, since +.BR LIRCCODE +drivers reflect hardware like TV-cards which usually dos not support +sending.) +.\" +.SH BUGS +Using these devices requires the kernel source header file +.IR lirc.h . +This file is not available before kernel release 4.6. +Users of older kernels could use the file bundled in +.UR http://www.lirc.org +.UE . +.\" +.SH SEE ALSO +.BR lircd (8) +.PP +https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/loop-control.4 b/man4/loop-control.4 new file mode 100644 index 0000000..251e652 --- /dev/null +++ b/man4/loop-control.4 @@ -0,0 +1 @@ +.so man4/loop.4 diff --git a/man4/loop.4 b/man4/loop.4 new file mode 100644 index 0000000..fc83525 --- /dev/null +++ b/man4/loop.4 @@ -0,0 +1,305 @@ +.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) +.\" and Copyright 2015 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" %%%LICENSE_END +.\" +.TH LOOP 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +loop, loop-control \- loop devices +.SH SYNOPSIS +#include +.SH DESCRIPTION +The loop device is a block device that maps its data blocks not to a +physical device such as a hard disk or optical disk drive, +but to the blocks of +a regular file in a filesystem or to another block device. +This can be useful for example to provide a block device for a filesystem +image stored in a file, so that it can be mounted with the +.BR mount (8) +command. +You could do +.PP +.in +4n +.EX +$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP +$ \fBsudo losetup /dev/loop4 file.img \fP +$ \fBsudo mkfs -t ext4 /dev/loop4\fP +$ \fBsudo mkdir /myloopdev\fP +$ \fBsudo mount /dev/loop4 /myloopdev\fP +.EE +.in +.PP +See +.BR losetup (8) +for another example. +.PP +A transfer function can be specified for each loop device for +encryption and decryption purposes. +.PP +The following +.BR ioctl (2) +operations are provided by the loop block device: +.TP +.B LOOP_SET_FD +Associate the loop device with the open file whose file descriptor is +passed as the (third) +.BR ioctl (2) +argument. +.TP +.B LOOP_CLR_FD +Disassociate the loop device from any file descriptor. +.TP +.B LOOP_SET_STATUS +Set the status of the loop device using the (third) +.BR ioctl (2) +argument. +This argument is a pointer to +.I loop_info +structure, defined in +.I +as: +.IP +.in +4n +.EX +struct loop_info { + int lo_number; /* ioctl r/o */ + dev_t lo_device; /* ioctl r/o */ + unsigned long lo_inode; /* ioctl r/o */ + dev_t lo_rdevice; /* ioctl r/o */ + int lo_offset; + int lo_encrypt_type; + int lo_encrypt_key_size; /* ioctl w/o */ + int lo_flags; /* ioctl r/o */ + char lo_name[LO_NAME_SIZE]; + unsigned char lo_encrypt_key[LO_KEY_SIZE]; + /* ioctl w/o */ + unsigned long lo_init[2]; + char reserved[4]; +}; +.EE +.in +.IP +The encryption type +.RI ( lo_encrypt_type ) +should be one of +.BR LO_CRYPT_NONE , +.BR LO_CRYPT_XOR , +.BR LO_CRYPT_DES , +.BR LO_CRYPT_FISH2 , +.BR LO_CRYPT_BLOW , +.BR LO_CRYPT_CAST128 , +.BR LO_CRYPT_IDEA , +.BR LO_CRYPT_DUMMY , +.BR LO_CRYPT_SKIPJACK , +or (since Linux 2.6.0) +.BR LO_CRYPT_CRYPTOAPI . +.IP +The +.I lo_flags +field is a bit mask that can include zero or more of the following: +.RS +.TP +.BR LO_FLAGS_READ_ONLY +The loopback device is read-only. +.TP +.BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)" +.\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581 +The loopback device will autodestruct on last close. +.TP +.BR LO_FLAGS_PARTSCAN " (since Linux 3.2)" +.\" commit e03c8dd14915fabc101aa495828d58598dc5af98 +Allow automatic partition scanning. +.RE +.TP +.B LOOP_GET_STATUS +Get the status of the loop device. +The (third) +.BR ioctl (2) +argument must be a pointer to a +.IR "struct loop_info" . +.TP +.BR LOOP_CHANGE_FD " (since Linux 2.6.5)" +Switch the backing store of the loop device to the new file identified +file descriptor specified in the (third) +.BR ioctl (2) +argument, which is an integer. +This operation is possible only if the loop device is read-only and +the new backing store is the same size and type as the old backing store. +.TP +.BR LOOP_SET_CAPACITY " (since Linux 2.6.30)" +.\" commit 53d6660836f233df66490707365ab177e5fb2bb4 +Resize a live loop device. +One can change the size of the underlying backing store and then use this +operation so that the loop driver learns about the new size. +This operation takes no argument. +.PP +Since Linux 2.6, there are two new +.BR ioctl (2) +operations: +.TP +.BR LOOP_SET_STATUS64 ", " LOOP_GET_STATUS64 +These are similar to +.BR LOOP_SET_STATUS " and " LOOP_GET_STATUS +described above but use the +.I loop_info64 +structure, +which has some additional fields and a larger range for some other fields: +.IP +.in +4n +.EX +struct loop_info64 { + uint64_t lo_device; /* ioctl r/o */ + uint64_t lo_inode; /* ioctl r/o */ + uint64_t lo_rdevice; /* ioctl r/o */ + uint64_t lo_offset; + uint64_t lo_sizelimit;/* bytes, 0 == max available */ + uint32_t lo_number; /* ioctl r/o */ + uint32_t lo_encrypt_type; + uint32_t lo_encrypt_key_size; /* ioctl w/o */ + uint32_t lo_flags; /* ioctl r/o */ + uint8_t lo_file_name[LO_NAME_SIZE]; + uint8_t lo_crypt_name[LO_NAME_SIZE]; + uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */ + uint64_t lo_init[2]; +}; +.EE +.in +.SS /dev/loop-control +Since Linux 3.1, +.\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844 +the kernel provides the +.I /dev/loop-control +device, which permits an application to dynamically find a free device, +and to add and remove loop devices from the system. +To perform these operations, one first opens +.IR /dev/loop-control +and then employs one of the following +.BR ioctl (2) +operations: +.TP +.B LOOP_CTL_GET_FREE +Allocate or find a free loop device for use. +On success, the device number is returned as the result of the call. +This operation takes no argument. +.TP +.B LOOP_CTL_ADD +Add the new loop device whose device number is specified +as a long integer in the third +.BR ioctl (2) +argument. +On success, the device index is returned as the result of the call. +If the device is already allocated, the call fails with the error +.BR EEXIST . +.TP +.B LOOP_CTL_REMOVE +Remove the loop device whose device number is specified +as a long integer in the third +.BR ioctl (2) +argument. +On success, the device number is returned as the result of the call. +If the device is in use, the call fails with the error +.BR EBUSY . +.SH FILES +.TP +.IR /dev/loop* +The loop block special device files. +.SH EXAMPLE +The program below uses the +.I /dev/loop-control +device to find a free loop device, opens the loop device, +opens a file to be used as the underlying storage for the device, +and then associates the loop device with the backing store. +The following shell session demonstrates the use of the program: +.PP +.in +4n +.EX +$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP +10+0 records in +10+0 records out +10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s +$ \fBsudo ./mnt_loop file.img\fP +loopname = /dev/loop5 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(int argc, char *argv[]) +{ + int loopctlfd, loopfd, backingfile; + long devnr; + char loopname[4096]; + + if (argc != 2) { + fprintf(stderr, "Usage: %s backing\-file\\n", argv[0]); + exit(EXIT_FAILURE); + } + + loopctlfd = open("/dev/loop\-control", O_RDWR); + if (loopctlfd == \-1) + errExit("open: /dev/loop\-control"); + + devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE); + if (devnr == \-1) + errExit("ioctl\-LOOP_CTL_GET_FREE"); + + sprintf(loopname, "/dev/loop%ld", devnr); + printf("loopname = %s\\n", loopname); + + loopfd = open(loopname, O_RDWR); + if (loopfd == \-1) + errExit("open: loopname"); + + backingfile = open(argv[1], O_RDWR); + if (backingfile == \-1) + errExit("open: backing\-file"); + + if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1) + errExit("ioctl\-LOOP_SET_FD"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR losetup (8), +.BR mount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/lp.4 b/man4/lp.4 new file mode 100644 index 0000000..f1d6143 --- /dev/null +++ b/man4/lp.4 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright (c) Michael Haardt (michael@cantor.informatik.rwth-aachen.de), +.\" Sun Jan 15 19:16:33 1995 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified, Sun Feb 26 15:02:58 1995, faith@cs.unc.edu +.TH LP 4 1995-01-15 "Linux" "Linux Programmer's Manual" +.SH NAME +lp \- line printer devices +.SH SYNOPSIS +.B #include +.SH CONFIGURATION +\fBlp\fP[0\(en2] are character devices for the parallel line printers; +they have major number 6 and minor number 0\(en2. +The minor numbers +correspond to the printer port base addresses 0x03bc, 0x0378 and 0x0278. +Usually they have mode 220 and are owned by root and group lp. +You can use printer ports either with polling or with interrupts. +Interrupts are recommended when high traffic is expected, for example, +for laser printers. +For typical dot matrix printers, polling will usually be enough. +The default is polling. +.SH DESCRIPTION +The following +.BR ioctl (2) +calls are supported: +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPTIME, int \fP\fIarg\fP\fB)\fP" +Sets the amount of time that the driver sleeps before rechecking the printer +when the printer's buffer appears to be filled to +.IR arg . +If you have a fast printer, decrease this number; +if you have a slow printer, then increase it. +This is in hundredths of a second, the default 2 +being 0.02 seconds. +It influences only the polling driver. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPCHAR, int \fP\fIarg\fP\fB)\fP" +Sets the maximum number of busy-wait iterations which the polling driver does +while waiting for the printer to get ready for receiving a character to +.IR arg . +If printing is too slow, increase this number; if the +system gets too slow, decrease this number. +The default is 1000. +It influences only the polling driver. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORT, int \fP\fIarg\fP\fB)\fP" +If +.I arg +is 0, the printer driver will retry on errors, otherwise +it will abort. +The default is 0. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPABORTOPEN, int \fP\fIarg\fP\fB)\fP" +If +.I arg +is 0, +.BR open (2) +will be aborted on error, otherwise error will be ignored. +The default is to ignore it. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPCAREFUL, int \fP\fIarg\fP\fB)\fP" +If +.I arg +is 0, then the out-of-paper, offline, and error signals are +required to be false on all writes, otherwise they are ignored. +The default is to ignore them. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPWAIT, int \fP\fIarg\fP\fB)\fP" +Sets the number of busy waiting iterations to wait before strobing the +printer to accept a just-written character, and the number of iterations to +wait before turning the strobe off again, +to +.IR arg . +The specification says this time should be 0.5 +microseconds, but experience has shown the delay caused by the code is +already enough. +For that reason, the default value is 0. +.\" FIXME . Actually, since Linux 2.2, the default is 1 +This is used for both the polling and the interrupt driver. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPSETIRQ, int \fP\fIarg\fP\fB)\fP" +This +.BR ioctl (2) +requires superuser privileges. +It takes an +.I int +containing the new IRQ as argument. +As a side effect, the printer will be reset. +When +.I arg +is 0, the polling driver will be used, which is also default. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETIRQ, int *\fP\fIarg\fP\fB)\fP" +Stores the currently used IRQ in +.IR arg . +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPGETSTATUS, int *\fP\fIarg\fP\fB)\fP" +Stores the value of the status port in +.IR arg . +The bits have the following meaning: +.TS +l l. +LP_PBUSY inverted busy input, active high +LP_PACK unchanged acknowledge input, active low +LP_POUTPA unchanged out-of-paper input, active high +LP_PSELECD unchanged selected input, active high +LP_PERRORP unchanged error input, active low +.TE +.PP +Refer to your printer manual for the meaning of the signals. +Note that undocumented bits may also be set, depending on your printer. +.IP "\fBint ioctl(int \fP\fIfd\fP\fB, LPRESET)\fP" +Resets the printer. +No argument is used. +.SH FILES +.I /dev/lp* +.\" .SH AUTHORS +.\" The printer driver was originally written by Jim Weigand and Linus +.\" Torvalds. +.\" It was further improved by Michael K.\& Johnson. +.\" The interrupt code was written by Nigel Gamble. +.\" Alan Cox modularized it. +.\" LPCAREFUL, LPABORT, LPGETSTATUS were added by Chris Metcalf. +.SH SEE ALSO +.BR chmod (1), +.BR chown (1), +.BR mknod (1), +.BR lpcntl (8), +.BR tunelp (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/mem.4 b/man4/mem.4 new file mode 100644 index 0000000..6bb63b7 --- /dev/null +++ b/man4/mem.4 @@ -0,0 +1,109 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 16:59:10 1993 by Rik Faith (faith@cs.unc.edu) +.TH MEM 4 2015-01-02 "Linux" "Linux Programmer's Manual" +.SH NAME +mem, kmem, port \- system memory, kernel memory and system ports +.SH DESCRIPTION +.IR /dev/mem +is a character device file +that is an image of the main memory of the computer. +It may be used, for example, to examine (and even patch) the system. +.PP +Byte addresses in +.IR /dev/mem +are interpreted as physical memory addresses. +References to nonexistent locations cause errors to be returned. +.PP +Examining and patching is likely to lead to unexpected results +when read-only or write-only bits are present. +.PP +Since Linux 2.6.26, and depending on the architecture, the +.B CONFIG_STRICT_DEVMEM +kernel configuration option limits the areas +which can be accessed through this file. +For example: on x86, RAM access is not allowed but accessing +memory-mapped PCI regions is. +.PP +It is typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/mem c 1 1 +chown root:kmem /dev/mem +.EE +.in +.PP +The file +.IR /dev/kmem +is the same as +.IR /dev/mem , +except that the kernel virtual memory +rather than physical memory is accessed. +Since Linux 2.6.26, this file is available only if the +.B CONFIG_DEVKMEM +kernel configuration option is enabled. +.PP +It is typically created by: +.PP +.in +4n +.EX +mknod \-m 640 /dev/kmem c 1 2 +chown root:kmem /dev/kmem +.EE +.in +.PP +.IR /dev/port +is similar to +.IR /dev/mem , +but the I/O ports are accessed. +.PP +It is typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/port c 1 4 +chown root:kmem /dev/port +.EE +.in +.SH FILES +.I /dev/mem +.br +.I /dev/kmem +.br +.I /dev/port +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ioperm (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/mouse.4 b/man4/mouse.4 new file mode 100644 index 0000000..78aa27c --- /dev/null +++ b/man4/mouse.4 @@ -0,0 +1,200 @@ +'\" t +.\" This manpage is Copyright (C) 1996 Michael Haardt. +.\" Updates Nov 1998, Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.TH MOUSE 4 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +mouse \- serial mouse interface +.SH CONFIGURATION +Serial mice are connected to a serial RS232/V24 dialout line, see +.BR ttyS (4) +for a description. +.SH DESCRIPTION +.SS Introduction +The pinout of the usual 9 pin plug as used for serial mice is: +.PP +.TS +center; +r c l. +pin name used for +2 RX Data +3 TX \-12 V, Imax = 10 mA +4 DTR +12 V, Imax = 10 mA +7 RTS +12 V, Imax = 10 mA +5 GND Ground +.TE +.PP +This is the specification, in fact 9 V suffices with most mice. +.PP +The mouse driver can recognize a mouse by dropping RTS to low and raising +it again. +About 14 ms later the mouse will send 0x4D (\(aqM\(aq) on the data line. +After a further 63 ms, a Microsoft-compatible 3-button mouse will send +0x33 (\(aq3\(aq). +.PP +The relative mouse movement is sent as +.I dx +(positive means right) +and +.I dy +(positive means down). +Various mice can operate at different speeds. +To select speeds, cycle through the +speeds 9600, 4800, 2400, and 1200 bit/s, each time writing the two characters +from the table below and waiting 0.1 seconds. +The following table shows available speeds and the strings that select them: +.PP +.TS +center; +l l. +bit/s string +9600 *q +4800 *p +2400 *o +1200 *n +.TE +.PP +The first byte of a data packet can be used for synchronization purposes. +.SS Microsoft protocol +The +.B Microsoft +protocol uses 1 start bit, 7 data bits, no parity +and one stop bit at the speed of 1200 bits/sec. +Data is sent to RxD in 3-byte packets. +The +.IR dx +and +.I dy +movements are sent as +two's-complement, +.I lb +.RI ( rb ) +are set when the left (right) +button is pressed: +.PP +.TS +center; +r c c c c c c c. +byte d6 d5 d4 d3 d2 d1 d0 +1 1 lb rb dy7 dy6 dx7 dx6 +2 0 dx5 dx4 dx3 dx2 dx1 dx0 +3 0 dy5 dy4 dy3 dy2 dy1 dy0 +.TE +.SS 3-button Microsoft protocol +Original Microsoft mice only have two buttons. +However, there are some +three button mice which also use the Microsoft protocol. +Pressing or +releasing the middle button is reported by sending a packet with zero +movement and no buttons pressed. +(Thus, unlike for the other two buttons, the status of the middle +button is not reported in each packet.) +.SS Logitech protocol +Logitech serial 3-button mice use a different extension of the +Microsoft protocol: when the middle button is up, the above 3-byte +packet is sent. +When the middle button is down a 4-byte packet is +sent, where the 4th byte has value 0x20 (or at least has the 0x20 +bit set). +In particular, a press of the middle button is reported +as 0,0,0,0x20 when no other buttons are down. +.SS Mousesystems protocol +The +.B Mousesystems +protocol uses 1 start bit, 8 data bits, no parity +and two stop bits at the speed of 1200 bits/sec. +Data is sent to RxD in +5-byte packets. +.I dx +is sent as the sum of the two two's-complement +values, +.I dy +is send as negated sum of the two two's-complement +values. +.I lb +.RI ( mb , +.IR rb ) +are cleared when the left (middle, +right) button is pressed: +.PP +.TS +center; +r c c c c c c c c. +byte d7 d6 d5 d4 d3 d2 d1 d0 +1 1 0 0 0 0 lb mb rb +2 0 dxa6 dxa5 dxa4 dxa3 dxa2 dxa1 dxa0 +3 0 dya6 dya5 dya4 dya3 dya2 dya1 dya0 +4 0 dxb6 dxb5 dxb4 dxb3 dxb2 dxb1 dxb0 +5 0 dyb6 dyb5 dyb4 dyb3 dyb2 dyb1 dyb0 +.TE +.PP +Bytes 4 and 5 describe the change that occurred since bytes 2 and 3 +were transmitted. +.SS Sun protocol +The +.B Sun +protocol is the 3-byte version of the above 5-byte +Mousesystems protocol: the last two bytes are not sent. +.SS MM protocol +The +.B MM +protocol uses 1 start bit, 8 data bits, odd parity and one +stop bit at the speed of 1200 bits/sec. +Data is sent to RxD in 3-byte +packets. +.I dx +and +.I dy +are sent as single signed values, the +sign bit indicating a negative value. +.I lb +.RI ( mb , +.IR rb ) +are +set when the left (middle, right) button is pressed: +.PP +.TS +center; +r c c c c c c c c. +byte d7 d6 d5 d4 d3 d2 d1 d0 +1 1 0 0 dxs dys lb mb rb +2 0 dx6 dx5 dx4 dx3 dx2 dx1 dx0 +3 0 dy6 dy5 dy4 dy3 dy2 dy1 dy0 +.TE +.SH FILES +.TP +.I /dev/mouse +A commonly used symbolic link pointing to a mouse device. +.SH SEE ALSO +.BR ttyS (4), +.BR gpm (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/msr.4 b/man4/msr.4 new file mode 100644 index 0000000..392a003 --- /dev/null +++ b/man4/msr.4 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2009 Intel Corporation, Author Andi Kleen +.\" Some sentences copied from comments in arch/x86/kernel/msr.c +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MSR 4 2009-03-31 "Linux" "Linux Programmer's Manual" +.SH NAME +msr \- x86 CPU MSR access device +.SH DESCRIPTION +.I /dev/cpu/CPUNUM/msr +provides an interface to read and write the model-specific +registers (MSRs) of an x86 CPU. +.I CPUNUM +is the number of the CPU to access as listed in +.IR /proc/cpuinfo . +.PP +The register access is done by opening the file and seeking +to the MSR number as offset in the file, and then +reading or writing in chunks of 8 bytes. +An I/O transfer of more than 8 bytes means multiple reads or writes +of the same register. +.PP +This file is protected so that it can be read and written only by the user +.IR root , +or members of the group +.IR root . +.SH NOTES +The +.I msr +driver is not auto-loaded. +On modular kernels you might need to use the following command +to load it explicitly before use: +.PP +.in +4n +.EX +$ modprobe msr +.EE +.in +.PP +.SH SEE ALSO +Intel Corporation Intel 64 and IA-32 Architectures +Software Developer's Manual Volume 3B Appendix B, +for an overview of the Intel CPU MSRs. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/null.4 b/man4/null.4 new file mode 100644 index 0000000..615a661 --- /dev/null +++ b/man4/null.4 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:00:12 1993 by Rik Faith (faith@cs.unc.edu) +.TH NULL 4 2015-07-23 "Linux" "Linux Programmer's Manual" +.SH NAME +null, zero \- data sink +.SH DESCRIPTION +Data written to the +.IR /dev/null +and +.IR /dev/zero +special files is discarded. +.PP +Reads from +.IR /dev/null +always return end of file (i.e., +.BR read (2) +returns 0), whereas reads from +.IR /dev/zero +always return bytes containing zero (\(aq\e0\(aq characters). +.PP +These devices are typically created by: +.PP +.in +4n +.EX +mknod \-m 666 /dev/null c 1 3 +mknod \-m 666 /dev/zero c 1 5 +chown root:root /dev/null /dev/zero +.EE +.in +.SH FILES +.I /dev/null +.br +.I /dev/zero +.SH NOTES +If these devices are not writable and readable for all users, many +programs will act strangely. +.PP +Since Linux 2.6.31, +.\" commit 2b83868723d090078ac0e2120e06a1cc94dbaef0 +reads from +.IR /dev/zero +are interruptible by signals. +(This change was made to help with bad latencies for large reads from +.IR /dev/zero .) +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR full (4) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/port.4 b/man4/port.4 new file mode 100644 index 0000000..d4c1762 --- /dev/null +++ b/man4/port.4 @@ -0,0 +1 @@ +.so man4/mem.4 diff --git a/man4/ptmx.4 b/man4/ptmx.4 new file mode 100644 index 0000000..b50d4e7 --- /dev/null +++ b/man4/ptmx.4 @@ -0,0 +1 @@ +.so man4/pts.4 diff --git a/man4/pts.4 b/man4/pts.4 new file mode 100644 index 0000000..9207bd9 --- /dev/null +++ b/man4/pts.4 @@ -0,0 +1,88 @@ +.\" This man page was written by Jeremy Phelps . +.\" Notes added - aeb +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" Redistribute and revise at will. +.\" %%%LICENSE_END +.\" +.TH PTS 4 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ptmx, pts \- pseudoterminal master and slave +.SH DESCRIPTION +The file +.I /dev/ptmx +is a character file with major number 5 and +minor number 2, usually of mode 0666 and owner.group of root.root. +It is used to create a pseudoterminal master and slave pair. +.PP +When a process opens +.IR /dev/ptmx , +it gets a file +descriptor for a pseudoterminal master (PTM), +and a pseudoterminal slave (PTS) device is created in the +.I /dev/pts +directory. +Each file descriptor obtained by opening +.IR /dev/ptmx +is an independent PTM with its own associated PTS, whose path can +be found by passing the file descriptor to +.BR ptsname (3). +.PP +Before opening the pseudoterminal slave, you must pass the master's file +descriptor to +.BR grantpt (3) +and +.BR unlockpt (3). +.PP +Once both the pseudoterminal master and slave are open, the slave provides +processes with an interface that is identical to that of a real terminal. +.PP +Data written to the slave is presented on the master file descriptor as input. +Data written to the master is presented to the slave as input. +.PP +In practice, pseudoterminals are used for implementing terminal emulators +such as +.BR xterm (1), +in which data read from the pseudoterminal master is interpreted by the +application in the same way +a real terminal would interpret the data, and for implementing remote-login +programs such as +.BR sshd (8), +in which data read from the pseudoterminal master is sent across the network +to a client program that is connected to a terminal or terminal emulator. +.PP +Pseudoterminals can also be used to send input to programs that normally +refuse to read input from pipes (such as +.BR su (1), +and +.BR passwd (1)). +.SH FILES +.IR /dev/ptmx , +.I /dev/pts/* +.SH NOTES +The Linux support for the above (known as UNIX 98 pseudoterminal naming) +is done using the +.I devpts +filesystem, that should be mounted on +.IR /dev/pts . +.PP +Before this UNIX 98 scheme, master pseudoterminals were called +.IR /dev/ptyp0 ", ..." +and slave pseudoterminals +.IR /dev/ttyp0 ", ..." +and one needed lots of preallocated device nodes. +.SH SEE ALSO +.BR getpt (3), +.BR grantpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pty (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/ram.4 b/man4/ram.4 new file mode 100644 index 0000000..901c8d6 --- /dev/null +++ b/man4/ram.4 @@ -0,0 +1,56 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:01:11 1993 by Rik Faith (faith@cs.unc.edu) +.TH RAM 4 1992-11-21 "Linux" "Linux Programmer's Manual" +.SH NAME +ram \- ram disk device +.SH DESCRIPTION +The +.I ram +device is a block device to access the ram disk in raw mode. +.PP +It is typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/ram b 1 1 +chown root:disk /dev/ram +.EE +.in +.SH FILES +.I /dev/ram +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR mount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/random.4 b/man4/random.4 new file mode 100644 index 0000000..4dd5d83 --- /dev/null +++ b/man4/random.4 @@ -0,0 +1,352 @@ +.\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" Some changes by tytso and aeb. +.\" +.\" 2004-12-16, John V. Belmonte/mtk, Updated init and quit scripts +.\" 2004-04-08, AEB, Improved description of read from /dev/urandom +.\" 2008-06-20, George Spelvin , +.\" Matt Mackall +.\" +.TH RANDOM 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +random, urandom \- kernel random number source devices +.SH SYNOPSIS +#include +.PP +.BI "int ioctl(" fd ", RND" request ", " param ");" +.SH DESCRIPTION +The character special files \fI/dev/random\fP and +\fI/dev/urandom\fP (present since Linux 1.3.30) +provide an interface to the kernel's random number generator. +The file +.I /dev/random +has major device number 1 and minor device number 8. +The file +.I /dev/urandom +has major device number 1 and minor device number 9. +.PP +The random number generator gathers environmental noise +from device drivers and other sources into an entropy pool. +The generator also keeps an estimate of the +number of bits of noise in the entropy pool. +From this entropy pool, random numbers are created. +.PP +Linux 3.17 and later provides the simpler and safer +.BR getrandom (2) +interface which requires no special files; +see the +.BR getrandom (2) +manual page for details. +.PP +When read, the +.I /dev/urandom +device returns random bytes using a pseudorandom +number generator seeded from the entropy pool. +Reads from this device do not block (i.e., the CPU is not yielded), +but can incur an appreciable delay when requesting large amounts of data. +.PP +When read during early boot time, +.IR /dev/urandom +may return data prior to the entropy pool being initialized. +.\" This is a real problem; see +.\" commit 9b4d008787f864f17d008c9c15bbe8a0f7e2fc24 +If this is of concern in your application, use +.BR getrandom (2) +or \fI/dev/random\fP instead. +.PP +The \fI/dev/random\fP device is a legacy interface which dates back to +a time where the cryptographic primitives used in the implementation +of \fI/dev/urandom\fP were not widely trusted. +It will return random bytes only within the estimated number of +bits of fresh noise in the entropy pool, blocking if necessary. +\fI/dev/random\fP is suitable for applications that need +high quality randomness, and can afford indeterminate delays. +.PP +When the entropy pool is empty, reads from \fI/dev/random\fP will block +until additional environmental noise is gathered. +If +.BR open (2) +is called for +.I /dev/random +with the +.BR O_NONBLOCK +flag, a subsequent +.BR read (2) +will not block if the requested number of bytes is not available. +Instead, the available bytes are returned. +If no byte is available, +.BR read (2) +will return -1 and +.I errno +will be set to +.BR EAGAIN . +.PP +The +.B O_NONBLOCK +flag has no effect when opening +.IR /dev/urandom . +When calling +.BR read (2) +for the device +.IR /dev/urandom , +reads of up to 256 bytes will return as many bytes as are requested +and will not be interrupted by a signal handler. +Reads with a buffer over this limit may return less than the +requested number of bytes or fail with the error +.BR EINTR , +if interrupted by a signal handler. +.PP +Since Linux 3.16, +.\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc +a +.BR read (2) +from +.IR /dev/urandom +will return at most 32\ MB. +A +.BR read (2) +from +.IR /dev/random +will return at most 512 bytes +.\" SEC_XFER_SIZE in drivers/char/random.c +(340 bytes on Linux kernels before version 2.6.12). +.PP +Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the +entropy pool with the data written, but this will not result in a +higher entropy count. +This means that it will impact the contents +read from both files, but it will not make reads from +\fI/dev/random\fP faster. +.SS Usage +The +.IR /dev/random +interface is considered a legacy interface, and +.IR /dev/urandom +is preferred and sufficient in all use cases, with the exception of +applications which require randomness during early boot time; for +these applications, +.BR getrandom (2) +must be used instead, +because it will block until the entropy pool is initialized. +.PP +If a seed file is saved across reboots as recommended below (all major +Linux distributions have done this since 2000 at least), the output is +cryptographically secure against attackers without local root access as +soon as it is reloaded in the boot sequence, and perfectly adequate for +network encryption session keys. +Since reads from +.I /dev/random +may block, users will usually want to open it in nonblocking mode +(or perform a read with timeout), +and provide some sort of user notification if the desired +entropy is not immediately available. +.\" +.SS Configuration +If your system does not have +\fI/dev/random\fP and \fI/dev/urandom\fP created already, they +can be created with the following commands: +.PP +.in +4n +.EX +mknod \-m 666 /dev/random c 1 8 +mknod \-m 666 /dev/urandom c 1 9 +chown root:root /dev/random /dev/urandom +.EE +.in +.PP +When a Linux system starts up without much operator interaction, +the entropy pool may be in a fairly predictable state. +This reduces the actual amount of noise in the entropy pool +below the estimate. +In order to counteract this effect, it helps to carry +entropy pool information across shut-downs and start-ups. +To do this, add the lines to an appropriate script +which is run during the Linux system start-up sequence: +.PP +.in +4n +.EX +echo "Initializing random number generator..." +random_seed=/var/run/random-seed +# Carry a random seed from start-up to start-up +# Load and then save the whole entropy pool +if [ \-f $random_seed ]; then + cat $random_seed >/dev/urandom +else + touch $random_seed +fi +chmod 600 $random_seed +poolfile=/proc/sys/kernel/random/poolsize +[ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 +bytes=$(expr $bits / 8) +dd if=/dev/urandom of=$random_seed count=1 bs=$bytes +.EE +.in +.PP +Also, add the following lines in an appropriate script which is +run during the Linux system shutdown: +.PP +.in +4n +.EX +# Carry a random seed from shut-down to start-up +# Save the whole entropy pool +echo "Saving random seed..." +random_seed=/var/run/random-seed +touch $random_seed +chmod 600 $random_seed +poolfile=/proc/sys/kernel/random/poolsize +[ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 +bytes=$(expr $bits / 8) +dd if=/dev/urandom of=$random_seed count=1 bs=$bytes +.EE +.in +.PP +In the above examples, we assume Linux 2.6.0 or later, where +.IR /proc/sys/kernel/random/poolsize +returns the size of the entropy pool in bits (see below). +.\" +.SS /proc interfaces +The files in the directory +.I /proc/sys/kernel/random +(present since 2.3.16) provide additional information about the +.I /dev/random +device: +.TP +.I entropy_avail +This read-only file gives the available entropy, in bits. +This will be a number in the range 0 to 4096. +.TP +.I poolsize +This file +gives the size of the entropy pool. +The semantics of this file vary across kernel versions: +.RS +.TP +Linux 2.4: +This file gives the size of the entropy pool in +.IR bytes . +Normally, this file will have the value 512, but it is writable, +and can be changed to any value for which an algorithm is available. +The choices are 32, 64, 128, 256, 512, 1024, or 2048. +.TP +Linux 2.6 and later: +This file is read-only, and gives the size of the entropy pool in +.IR bits . +It contains the value 4096. +.RE +.TP +.I read_wakeup_threshold +This file +contains the number of bits of entropy required for waking up processes +that sleep waiting for entropy from +.IR /dev/random . +The default is 64. +.TP +.I write_wakeup_threshold +This file +contains the number of bits of entropy below which we wake up +processes that do a +.BR select (2) +or +.BR poll (2) +for write access to +.IR /dev/random . +These values can be changed by writing to the files. +.TP +.IR uuid " and " boot_id +These read-only files +contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. +The former is generated afresh for each read, the latter was +generated once. +.\" +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to either \fI/dev/random\fP +or \fI/dev/urandom\fP. +All requests performed will interact with the input +entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. +The +.B CAP_SYS_ADMIN +capability is required for all requests except +.BR RNDGETENTCNT . +.TP +.BR RNDGETENTCNT +Retrieve the entropy count of the input pool, the contents will be the same +as the +.I entropy_avail +file under proc. +The result will be stored in the int pointed to by the argument. +.TP +.BR RNDADDTOENTCNT +Increment or decrement the entropy count of the input pool +by the value pointed to by the argument. +.TP +.BR RNDGETPOOL +Removed in Linux 2.6.9. +.TP +.BR RNDADDENTROPY +Add some additional entropy to the input pool, +incrementing the entropy count. +This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP, +which only adds some +data but does not increment the entropy count. +The following structure is used: +.IP +.in +4n +.EX +struct rand_pool_info { + int entropy_count; + int buf_size; + __u32 buf[0]; +}; +.EE +.in +.IP +Here +.I entropy_count +is the value added to (or subtracted from) the entropy count, and +.I buf +is the buffer of size +.I buf_size +which gets added to the entropy pool. +.TP +.BR RNDZAPENTCNT ", " RNDCLEARPOOL +Zero the entropy count of all pools and add some system data (such as +wall clock) to the pools. +.SH FILES +.I /dev/random +.br +.I /dev/urandom +.SH NOTES +For an overview and comparison of the various interfaces that +can be used to obtain randomness, see +.BR random (7). +.SH BUGS +During early boot time, reads from +.I /dev/urandom +may return data prior to the entropy pool being initialized. +.\" .SH AUTHOR +.\" The kernel's random number generator was written by +.\" Theodore Ts'o (tytso@athena.mit.edu). +.SH SEE ALSO +.BR mknod (1), +.BR getrandom (2), +.BR random (7) +.PP +RFC\ 1750, "Randomness Recommendations for Security" +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/rtc.4 b/man4/rtc.4 new file mode 100644 index 0000000..804ba1f --- /dev/null +++ b/man4/rtc.4 @@ -0,0 +1,351 @@ +.\" rtc.4 +.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $ +.\" +.\" 2006-02-08 Various additions by mtk +.\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell +.\" +.TH RTC 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +rtc \- real-time clock +.SH SYNOPSIS +#include +.PP +.BI "int ioctl(" fd ", RTC_" request ", " param ");" +.SH DESCRIPTION +This is the interface to drivers for real-time clocks (RTCs). +.PP +Most computers have one or more hardware clocks which record the +current "wall clock" time. +These are called "Real Time Clocks" (RTCs). +One of these usually has battery backup power so that it tracks the time +even while the computer is turned off. +RTCs often provide alarms and other interrupts. +.PP +All i386 PCs, and ACPI-based systems, have an RTC that is compatible with +the Motorola MC146818 chip on the original PC/AT. +Today such an RTC is usually integrated into the mainboard's chipset +(south bridge), and uses a replaceable coin-sized backup battery. +.PP +Non-PC systems, such as embedded systems built around system-on-chip +processors, use other implementations. +They usually won't offer the same functionality as the RTC from a PC/AT. +.SS RTC vs system clock +RTCs should not be confused with the system clock, which is +a software clock maintained by the kernel and used to implement +.BR gettimeofday (2) +and +.BR time (2), +as well as setting timestamps on files, and so on. +The system clock reports seconds and microseconds since a start point, +defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC). +(One common implementation counts timer interrupts, once +per "jiffy", at a frequency of 100, 250, or 1000 Hz.) +That is, it is supposed to report wall clock time, which RTCs also do. +.PP +A key difference between an RTC and the system clock is that RTCs +run even when the system is in a low power state (including "off"), +and the system clock can't. +Until it is initialized, the system clock can only report time since +system boot ... not since the POSIX Epoch. +So at boot time, and after resuming from a system low power state, the +system clock will often be set to the current wall clock time using an RTC. +Systems without an RTC need to set the system clock using another clock, +maybe across the network or by entering that data manually. +.SS RTC functionality +RTCs can be read and written with +.BR hwclock (8), +or directly with the ioctl requests listed below. +.PP +Besides tracking the date and time, many RTCs can also generate +interrupts +.IP * 3 +on every clock update (i.e., once per second); +.IP * +at periodic intervals with a frequency that can be set to +any power-of-2 multiple in the range 2 Hz to 8192 Hz; +.IP * +on reaching a previously specified alarm time. +.PP +Each of those interrupt sources can be enabled or disabled separately. +On many systems, the alarm interrupt can be configured as a system wakeup +event, which can resume the system from a low power state such as +Suspend-to-RAM (STR, called S3 in ACPI systems), +Hibernation (called S4 in ACPI systems), +or even "off" (called S5 in ACPI systems). +On some systems, the battery backed RTC can't issue +interrupts, but another one can. +.PP +The +.I /dev/rtc +(or +.IR /dev/rtc0 , +.IR /dev/rtc1 , +etc.) +device can be opened only once (until it is closed) and it is read-only. +On +.BR read (2) +and +.BR select (2) +the calling process is blocked until the next interrupt from that RTC +is received. +Following the interrupt, the process can read a long integer, of which +the least significant byte contains a bit mask encoding +the types of interrupt that occurred, +while the remaining 3 bytes contain the number of interrupts since the +last +.BR read (2). +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to RTC devices: +.TP +.B RTC_RD_TIME +Returns this RTC's time in the following structure: +.IP +.in +4n +.EX +struct rtc_time { + int tm_sec; + int tm_min; + int tm_hour; + int tm_mday; + int tm_mon; + int tm_year; + int tm_wday; /* unused */ + int tm_yday; /* unused */ + int tm_isdst; /* unused */ +}; +.EE +.in +.IP +The fields in this structure have the same meaning and ranges as for the +.I tm +structure described in +.BR gmtime (3). +A pointer to this structure should be passed as the third +.BR ioctl (2) +argument. +.TP +.B RTC_SET_TIME +Sets this RTC's time to the time specified by the +.I rtc_time +structure pointed to by the third +.BR ioctl (2) +argument. +To set the +RTC's time the process must be privileged (i.e., have the +.B CAP_SYS_TIME +capability). +.TP +.BR RTC_ALM_READ ", " RTC_ALM_SET +Read and set the alarm time, for RTCs that support alarms. +The alarm interrupt must be separately enabled or disabled using the +.BR RTC_AIE_ON ", " RTC_AIE_OFF +requests. +The third +.BR ioctl (2) +argument is a pointer to an +.I rtc_time +structure. +Only the +.IR tm_sec , +.IR tm_min , +and +.I tm_hour +fields of this structure are used. +.TP +.BR RTC_IRQP_READ ", " RTC_IRQP_SET +Read and set the frequency for periodic interrupts, +for RTCs that support periodic interrupts. +The periodic interrupt must be separately enabled or disabled using the +.BR RTC_PIE_ON ", " RTC_PIE_OFF +requests. +The third +.BR ioctl (2) +argument is an +.I "unsigned long\ *" +or an +.IR "unsigned long" , +respectively. +The value is the frequency in interrupts per second. +The set of allowable frequencies is the multiples of two +in the range 2 to 8192. +Only a privileged process (i.e., one having the +.B CAP_SYS_RESOURCE +capability) can set frequencies above the value specified in +.IR /proc/sys/dev/rtc/max-user-freq . +(This file contains the value 64 by default.) +.TP +.BR RTC_AIE_ON ", " RTC_AIE_OFF +Enable or disable the alarm interrupt, for RTCs that support alarms. +The third +.BR ioctl (2) +argument is ignored. +.TP +.BR RTC_UIE_ON ", " RTC_UIE_OFF +Enable or disable the interrupt on every clock update, +for RTCs that support this once-per-second interrupt. +The third +.BR ioctl (2) +argument is ignored. +.TP +.BR RTC_PIE_ON ", " RTC_PIE_OFF +Enable or disable the periodic interrupt, +for RTCs that support these periodic interrupts. +The third +.BR ioctl (2) +argument is ignored. +Only a privileged process (i.e., one having the +.B CAP_SYS_RESOURCE +capability) can enable the periodic interrupt if the frequency is +currently set above the value specified in +.IR /proc/sys/dev/rtc/max-user-freq . +.TP +.BR RTC_EPOCH_READ ", " RTC_EPOCH_SET +Many RTCs encode the year in an 8-bit register which is either +interpreted as an 8-bit binary number or as a BCD number. +In both cases, +the number is interpreted relative to this RTC's Epoch. +The RTC's Epoch is +initialized to 1900 on most systems but on Alpha and MIPS it might +also be initialized to 1952, 1980, or 2000, depending on the value of +an RTC register for the year. +With some RTCs, +these operations can be used to read or to set the RTC's Epoch, +respectively. +The third +.BR ioctl (2) +argument is an +.I "unsigned long\ *" +or an +.IR "unsigned long" , +respectively, and the value returned (or assigned) is the Epoch. +To set the RTC's Epoch the process must be privileged (i.e., have the +.B CAP_SYS_TIME +capability). +.TP +.BR RTC_WKALM_RD ", " RTC_WKALM_SET +Some RTCs support a more powerful alarm interface, using these ioctls +to read or write the RTC's alarm time (respectively) with this structure: +.PP +.RS +.in +4n +.EX +struct rtc_wkalrm { + unsigned char enabled; + unsigned char pending; + struct rtc_time time; +}; +.EE +.in +.RE +.IP +The +.I enabled +flag is used to enable or disable the alarm interrupt, +or to read its current status; when using these calls, +.BR RTC_AIE_ON " and " RTC_AIE_OFF +are not used. +The +.I pending +flag is used by +.B RTC_WKALM_RD +to report a pending interrupt +(so it's mostly useless on Linux, except when talking +to the RTC managed by EFI firmware). +The +.I time +field is as used with +.B RTC_ALM_READ +and +.B RTC_ALM_SET +except that the +.IR tm_mday , +.IR tm_mon , +and +.I tm_year +fields are also valid. +A pointer to this structure should be passed as the third +.BR ioctl (2) +argument. +.SH FILES +.TP +.IR /dev/rtc ", " /dev/rtc0 ", " /dev/rtc1 ", etc." +RTC special character device files. +.TP +.IR /proc/driver/rtc +status of the (first) RTC. +.SH NOTES +When the kernel's system time is synchronized with an external +reference using +.BR adjtimex (2) +it will update a designated RTC periodically every 11 minutes. +To do so, the kernel has to briefly turn off periodic interrupts; +this might affect programs using that RTC. +.PP +An RTC's Epoch has nothing to do with the POSIX Epoch which is +used only for the system clock. +.PP +If the year according to the RTC's Epoch and the year register is +less than 1970 it is assumed to be 100 years later, that is, between 2000 +and 2069. +.PP +Some RTCs support "wildcard" values in alarm fields, to support +scenarios like periodic alarms at fifteen minutes after every hour, +or on the first day of each month. +Such usage is nonportable; +portable user-space code expects only a single alarm interrupt, and +will either disable or reinitialize the alarm after receiving it. +.PP +Some RTCs support periodic interrupts with periods that are multiples +of a second rather than fractions of a second; +multiple alarms; +programmable output clock signals; +nonvolatile memory; +and other hardware +capabilities that are not currently exposed by this API. +.SH SEE ALSO +.BR date (1), +.BR adjtimex (2), +.BR gettimeofday (2), +.BR settimeofday (2), +.BR stime (2), +.BR time (2), +.BR gmtime (3), +.BR time (7), +.BR hwclock (8) +.PP +.I Documentation/rtc.txt +in the Linux kernel source tree +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/sd.4 b/man4/sd.4 new file mode 100644 index 0000000..e64a130 --- /dev/null +++ b/man4/sd.4 @@ -0,0 +1,146 @@ +.\" sd.4 +.\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SD 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sd \- driver for SCSI disk drives +.SH SYNOPSIS +.nf +.BR "#include " "/* for HDIO_GETGEO */" +.BR "#include " "/* for BLKGETSIZE and BLKRRPART */" +.fi +.SH CONFIGURATION +The block device name has the following form: +.BI sd lp, +where +.I l +is a letter denoting the physical drive, and +.I p +is a number denoting the partition on that physical drive. +Often, the partition number, +.IR p , +will be left off when the device corresponds to the whole drive. +.PP +SCSI disks have a major device number of 8, and a minor device number of +the form (16 * +.IR drive_number ") + " partition_number , +where +.I drive_number +is the number of the physical drive in order of detection, and +.I partition_number +is as follows: +.IP +3 +partition 0 is the whole drive +.IP +partitions 1\(en4 are the DOS "primary" partitions +.IP +partitions 5\(en8 are the DOS "extended" (or "logical") partitions +.PP +For example, +.I /dev/sda +will have major 8, minor 0, and will refer to all of the first SCSI drive +in the system; and +.I /dev/sdb3 +will have major 8, minor 19, and will refer to the third DOS "primary" +partition on the second SCSI drive in the system. +.PP +At this time, only block devices are provided. +Raw devices have not yet been implemented. +.SH DESCRIPTION +The following +.IR ioctl s +are provided: +.TP +.B HDIO_GETGEO +Returns the BIOS disk parameters in the following structure: +.PP +.in +4n +.EX +struct hd_geometry { + unsigned char heads; + unsigned char sectors; + unsigned short cylinders; + unsigned long start; +}; +.EE +.in +.IP +A pointer to this structure is passed as the +.BR ioctl (2) +parameter. +.IP +The information returned in the parameter is the disk geometry of the drive +.I "as understood by DOS!" +This geometry is +.I not +the physical geometry of the drive. +It is used when constructing the +drive's partition table, however, and is needed for convenient operation +of +.BR fdisk (1), +.BR efdisk (1), +and +.BR lilo (1). +If the geometry information is not available, zero will be returned for all +of the parameters. +.TP +.B BLKGETSIZE +Returns the device size in sectors. +The +.BR ioctl (2) +parameter should be a pointer to a +.IR long . +.TP +.B BLKRRPART +Forces a reread of the SCSI disk partition tables. +No parameter is needed. +.IP +The SCSI +.BR ioctl (2) +operations are also supported. +If the +.BR ioctl (2) +parameter is required, and it is NULL, then +.BR ioctl (2) +fails with the error +.BR EINVAL . +.SH FILES +.TP +.I /dev/sd[a\-h] +the whole device +.TP +.I /dev/sd[a\-h][0\-8] +individual block partitions +.\".SH SEE ALSO +.\".BR scsi (4) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/sk98lin.4 b/man4/sk98lin.4 new file mode 100644 index 0000000..9831ce6 --- /dev/null +++ b/man4/sk98lin.4 @@ -0,0 +1,597 @@ +.\" (C)Copyright 1999-2003 Marvell(R) -- linux@syskonnect.de +.\" sk98lin.4 1.1 2003/12/17 10:03:18 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual;if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" This manpage can be viewed using `groff -Tascii -man sk98lin.4 | less` +.\" +.TH SK98LIN 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sk98lin \- Marvell/SysKonnect Gigabit Ethernet driver v6.21 +.SH SYNOPSIS +.B insmod sk98lin.o +.RB [ Speed_A=\c +.IR i,j,... ] +.RB [ Speed_B=\c +.IR i,j,... ] +.RB [ AutoNeg_A=\c +.IR i,j,... ] +.RB [ AutoNeg_B=\c +.IR i,j,... ] +.RB [ DupCap_A=\c +.IR i,j,... ] +.RB [ DupCap_B=\c +.IR i,j,... ] +.RB [ FlowCtrl_A=\c +.IR i,j,... ] +.RB [ FlowCtrl_B=\c +.IR i,j,... ] +.RB [ Role_A=\c +.IR i,j,... ] +.RB [ Role_B=\c +.IR i,j,... ] +.RB [ ConType=\c +.IR i,j,... ] +.RB [ Moderation=\c +.IR i,j,... ] +.RB [ IntsPerSec=\c +.IR i,j,... ] +.RB [ PrefPort=\c +.IR i,j,... ] +.RB [ RlmtMode=\c +.IR i,j,... ] +.SH DESCRIPTION +.ad l +.hy 0 +.BR Note : +This obsolete driver was removed from the kernel in version 2.6.26. +.PP +.B sk98lin +is the Gigabit Ethernet driver for +Marvell and SysKonnect network adapter cards. +It supports SysKonnect SK-98xx/SK-95xx +compliant Gigabit Ethernet Adapter and +any Yukon compliant chipset. +.PP +When loading the driver using insmod, +parameters for the network adapter cards +might be stated as a sequence of comma separated commands. +If for instance two network adapters are installed and AutoNegotiation on +Port A of the first adapter should be ON, +but on the Port A of the second adapter switched OFF, one must enter: +.PP + insmod sk98lin.o AutoNeg_A=On,Off +.PP +After +.B sk98lin +is bound to one or more adapter cards and the +.I /proc +filesystem is mounted on your system, a dedicated statistics file +will be created in the folder +.I /proc/net/sk98lin +for all ports of the installed network adapter cards. +Those files are named +.IR eth[x] , +where +.I x +is the number of the interface that has been assigned to a +dedicated port by the system. +.PP +If loading is finished, any desired IP address can be +assigned to the respective +.I eth[x] +interface using the +.BR ifconfig (8) +command. +This causes the adapter to connect to the Ethernet and to display a status +message on the console saying "ethx: network connection up using port y" +followed by the configured or detected connection parameters. +.PP +The +.B sk98lin +also supports large frames (also called jumbo frames). +Using jumbo frames can improve throughput tremendously when +transferring large amounts of data. +To enable large frames, the MTU (maximum transfer unit) size +for an interface is to be set to a high value. +The default MTU size is 1500 and can be changed up to 9000 (bytes). +Setting the MTU size can be done when assigning the IP address +to the interface or later by using the +.BR ifconfig (8) +command with the mtu parameter. +If for instance eth0 needs an IP +address and a large frame MTU size, +the following two commands might be used: +.PP + ifconfig eth0 10.1.1.1 + ifconfig eth0 mtu 9000 +.PP +Those two commands might even be combined into one: +.PP + ifconfig eth0 10.1.1.1 mtu 9000 +.PP +Note that large frames can be used only if permitted by +your network infrastructure. +This means, that any switch being used in your Ethernet must +also support large frames. +Quite some switches support large frames, +but need to be configured to do so. +Most of the times, their default setting is to support only +standard frames with an MTU size of 1500 (bytes). +In addition to the switches inside the network, +all network adapters that are to be used must also be +enabled regarding jumbo frames. +If an adapter is not set to receive large frames, it will simply drop them. +.PP +Switching back to the standard Ethernet frame size can be done by using the +.BR ifconfig (8) +command again: +.PP + ifconfig eth0 mtu 1500 +.PP +The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to +support VLAN and Link Aggregation according to +IEEE standards 802.1, 802.1q, and 802.3ad. +Those features are available only after installation of open source modules +which can be found on the Internet: +.PP +.IR VLAN \c +: +.UR http://www.candelatech.com\:/~greear\:/vlan.html +.UE +.br +.I Link +.IR Aggregation \c +: +.UR http://www.st.rim.or.jp\:/~yumo +.UE +.PP +Note that Marvell/SysKonnect does not offer any support for these +open source modules and does not take the responsibility for any +kind of failures or problems arising when using these modules. +.SS Parameters +.TP +.BI Speed_A= i,j,... +This parameter is used to set the speed capabilities of port A of an +adapter card. +It is valid only for Yukon copper adapters. +Possible values are: +.IR 10 , +.IR 100 , +.IR 1000 , +or +.IR Auto ; +.I Auto +is the default. +Usually, the speed is negotiated between the two ports +during link establishment. +If this fails, +a port can be forced to a specific setting with this parameter. +.TP +.BI Speed_B= i,j,... +This parameter is used to set the speed capabilities of port B of +an adapter card. +It is valid only for Yukon copper adapters. +Possible values are: +.IR 10 , +.IR 100 , +.IR 1000 , +or +.IR Auto ; +.I Auto +is the default. +Usually, the speed is negotiated between the two ports during link +establishment. +If this fails, +a port can be forced to a specific setting with this parameter. +.TP +.BI AutoNeg_A= i,j,... +Enables or disables the use of autonegotiation of port A of an adapter card. +Possible values are: +.IR On , +.IR Off , +or +.IR Sense ; +.I On +is the default. +The +.I Sense +mode automatically detects whether the link partner supports +auto-negotiation or not. +.TP +.BI AutoNeg_B= i,j,... +Enables or disables the use of autonegotiation of port B of an adapter card. +Possible values are: +.IR On , +.IR Off , +or +.IR Sense ; +.I On +is the default. +The +.I Sense +mode automatically detects whether the link partner supports +auto-negotiation or not. +.TP +.BI DupCap_A= i,j,... +This parameter indicates the duplex mode to be used for port A +of an adapter card. +Possible values are: +.IR Half , +.IR Full , +or +.IR Both ; +.I Both +is the default. +This parameter is relevant only if AutoNeg_A of port A is not set to +.IR Sense . +If AutoNeg_A is set to +.IR On , +all three values of DupCap_A ( +.IR Half , +.I Full +or +.IR Both ) +might be stated. +If AutoNeg_A is set to +.IR Off , +only DupCap_A values +.I Full +and +.I Half +are allowed. +This DupCap_A parameter is useful if your link partner does not +support all possible duplex combinations. +.TP +.BI DupCap_B= i,j,... +This parameter indicates the duplex mode to be used for port B +of an adapter card. +Possible values are: +.IR Half , +.IR Full , +or +.IR Both ; +.I Both +is the default. +This parameter is relevant only if AutoNeg_B of port B is not set to +.IR Sense . +If AutoNeg_B is set to +.IR On , +all three values of DupCap_B ( +.IR Half , +.I Full +or +.IR Both ) +might be stated. +If AutoNeg_B is set to +.IR Off , +only DupCap_B values +.I Full +and +.I Half +are allowed. +This DupCap_B parameter is useful if your link partner does not +support all possible duplex combinations. +.TP +.BI FlowCtrl_A= i,j,... +This parameter can be used to set the flow control capabilities the +port reports during auto-negotiation. +Possible values are: +.IR Sym , +.IR SymOrRem , +.IR LocSend , +or +.IR None ; +.I SymOrRem +is the default. +The different modes have the following meaning: +.IP +.I Sym += Symmetric + both link partners are allowed to send PAUSE frames +.br +.I SymOrRem += SymmetricOrRemote + both or only remote partner are allowed to send PAUSE frames +.br +.I LocSend += LocalSend + only local link partner is allowed to send PAUSE frames +.br +.I None += None + no link partner is allowed to send PAUSE frames +.IP +Note that this parameter is ignored if AutoNeg_A is set to +.IR Off . +.TP +.BI FlowCtrl_B= i,j,... +This parameter can be used to set the flow control capabilities the +port reports during auto-negotiation. +Possible values are: +.IR Sym , +.IR SymOrRem , +.IR LocSend , +or +.IR None ; +.I SymOrRem +is the default. +The different modes have the following meaning: +.IP +.I Sym += Symmetric + both link partners are allowed to send PAUSE frames +.br +.I SymOrRem += SymmetricOrRemote + both or only remote partner are allowed to send PAUSE frames +.br +.I LocSend += LocalSend + only local link partner is allowed to send PAUSE frames +.br +.I None += None + no link partner is allowed to send PAUSE frames +.br +.IP +Note that this parameter is ignored if AutoNeg_B is set to +.IR Off . +.TP +.BI Role_A= i,j,... +This parameter is valid only for 1000Base-T adapter cards. +For two 1000Base-T ports to communicate, +one must take the role of the master (providing timing information), +while the other must be the slave. +Possible values are: +.IR Auto , +.IR Master , +or +.IR Slave ; +.I Auto +is the default. +Usually, the role of a port is negotiated between two ports during +link establishment, but if that fails the port A of an adapter card +can be forced to a specific setting with this parameter. +.TP +.BI Role_B= i,j,... +This parameter is valid only for 1000Base-T adapter cards. +For two 1000Base-T ports to communicate, one must take +the role of the master (providing timing information), +while the other must be the slave. +Possible values are: +.IR Auto , +.IR Master , +or +.IR Slave ; +.I Auto +is the default. +Usually, the role of a port is negotiated between +two ports during link establishment, but if that fails +the port B of an adapter card can be forced to a +specific setting with this parameter. +.TP +.BI ConType= i,j,... +This parameter is a combination of all five per-port parameters +within one single parameter. +This simplifies the configuration of both ports of an adapter card. +The different values of this variable reflect the +most meaningful combinations of port parameters. +Possible values and their corresponding combination of per-port parameters: +.IP +.nf +ConType | DupCap AutoNeg FlowCtrl Role Speed +--------+------------------------------------------- +\fIAuto\fP | Both On SymOrRem Auto Auto +\fI100FD\fP | Full Off None Auto 100 +\fI100HD\fP | Half Off None Auto 100 +\fI10FD\fP | Full Off None Auto 10 +\fI10HD\fP | Half Off None Auto 10 +.fi +.IP +Stating any other port parameter together with this +.I ConType +parameter will result in a merged configuration of those settings. +This is due to +the fact, that the per-port parameters (e.g., +.IR Speed_A ) +have a higher priority than the combined variable +.IR ConType . +.TP +.BI Moderation= i,j,... +Interrupt moderation is employed to limit the maximum number of interrupts +the driver has to serve. +That is, one or more interrupts (which indicate any transmit or +receive packet to be processed) are queued until the driver processes them. +When queued interrupts are to be served, is determined by the +.I IntsPerSec +parameter, which is explained later below. +Possible moderation modes are: +.IR None , +.IR Static , +or +.IR Dynamic ; +.I None +is the default. +The different modes have the following meaning: +.IP +.I None +No interrupt moderation is applied on the adapter card. +Therefore, each transmit or receive interrupt is served immediately +as soon as it appears on the interrupt line of the adapter card. +.IP +.I Static +Interrupt moderation is applied on the adapter card. +All transmit and receive interrupts are queued until +a complete moderation interval ends. +If such a moderation interval ends, all queued interrupts +are processed in one big bunch without any delay. +The term +.I Static +reflects the fact, that interrupt moderation is always enabled, +regardless how much network load is currently passing via a +particular interface. +In addition, the duration of the moderation interval has a fixed +length that never changes while the driver is operational. +.IP +.I Dynamic +Interrupt moderation might be applied on the adapter card, +depending on the load of the system. +If the driver detects that the system load is too high, +the driver tries to shield the system against too much network +load by enabling interrupt moderation. +If\(emat a later time\(emthe CPU utilization decreases +again (or if the network load is negligible), the interrupt +moderation will automatically be disabled. +.IP +Interrupt moderation should be used when the driver has to +handle one or more interfaces with a high network load, +which\(emas a consequence\(emleads also to a high CPU utilization. +When moderation is applied in such high network load situations, +CPU load might be reduced by 20\(en30% on slow computers. +.IP +Note that the drawback of using interrupt moderation is an increase of +the round-trip-time (RTT), due to the queuing and serving of +interrupts at dedicated moderation times. +.TP +.BI IntsPerSec= i,j,... +This parameter determines the length of any interrupt moderation interval. +Assuming that static interrupt moderation is to be used, an +.I IntsPerSec +parameter value of 2000 will lead to an interrupt moderation interval of +500 microseconds. +Possible values for this parameter are in the range of +30...40000 (interrupts per second). +The default value is 2000. +.IP +This parameter is used only if either static or dynamic interrupt moderation +is enabled on a network adapter card. +This parameter is ignored if no moderation is applied. +.IP +Note that the duration of the moderation interval is to be chosen with care. +At first glance, selecting a very long duration (e.g., only 100 interrupts per +second) seems to be meaningful, but the increase of packet-processing delay +is tremendous. +On the other hand, selecting a very short moderation time might +compensate the use of any moderation being applied. +.TP +.BI PrefPort= i,j,... +This parameter is used to force the preferred port to +A or B (on dual-port network adapters). +The preferred port is the one that is used if both ports A and B are +detected as fully functional. +Possible values are: +.I A +or +.IR B ; +.I A +is the default. +.TP +.BI RlmtMode= i,j,... +RLMT monitors the status of the port. +If the link of the active port fails, +RLMT switches immediately to the standby link. +The virtual link is maintained as long as at least one "physical" link is up. +This parameters states how RLMT should monitor both ports. +Possible values are: +.IR CheckLinkState , +.IR CheckLocalPort , +.IR CheckSeg , +or +.IR DualNet ; +.I CheckLinkState +is the default. +The different modes have the following meaning: +.IP +.I CheckLinkState +Check link state only: RLMT uses the link state reported by the adapter +hardware for each individual port to determine whether a port can be used +for all network traffic or not. +.IP +.I CheckLocalPort +In this mode, RLMT monitors the network path between the two +ports of an adapter by regularly exchanging packets between them. +This mode requires a network configuration in which the +two ports are able to "see" each other (i.e., there +must not be any router between the ports). +.IP +.I CheckSeg +Check local port and segmentation: +This mode supports the same functions as the CheckLocalPort +mode and additionally checks network segmentation between the ports. +Therefore, this mode is to be used only if Gigabit Ethernet +switches are installed on the network that have been +configured to use the Spanning Tree protocol. +.IP +.I DualNet +In this mode, ports A and B are used as separate devices. +If you have a dual port adapter, port A will be configured as +.IR eth[x] +and port B as +.IR eth[x+1] . +Both ports can be used independently with distinct IP addresses. +The preferred port setting is not used. +RLMT is turned off. +.IP +Note that RLMT modes +.I CheckLocalPort +and +.I CheckLinkState +are designed to operate in configurations where a +network path between the ports on one adapter exists. +Moreover, they are not designed to work where adapters are +connected back-to-back. +.SH FILES +.TP +.I /proc/net/sk98lin/eth[x] +The statistics file of a particular interface of an adapter card. +It contains generic information about the adapter card plus a detailed +summary of all transmit and receive counters. +.TP +.I /usr/src/linux/Documentation/networking/sk98lin.txt +This is the +.I README +file of the +.I sk98lin +driver. +It contains a detailed installation HOWTO and describes all parameters +of the driver. +It denotes also common problems and provides the solution to them. +.SH BUGS +Report any bugs to linux@syskonnect.de +.\" .SH AUTHORS +.\" Ralph Roesler \(em rroesler@syskonnect.de +.\" .br +.\" Mirko Lindner \(em mlindner@syskonnect.de +.SH SEE ALSO +.BR ifconfig (8), +.BR insmod (8), +.BR modprobe (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/smartpqi.4 b/man4/smartpqi.4 new file mode 100644 index 0000000..887dabd --- /dev/null +++ b/man4/smartpqi.4 @@ -0,0 +1,244 @@ +.\" Copyright (C) 2016-2017, Microsemi Corporation +.\" Copyright (C) 2016, PMC-Sierra, Inc. +.\" Written by Kevin Barnett +.\" +.\" %%%LICENSE_START(GPLv2_ONELINE) +.\" Licensed under GNU General Public License version 2 (GPLv2) +.\" %%%LICENSE_END +.TH SMARTPQI 4 2017-10-19 "Linux" "Linux Programmer's Manual" +.SH NAME +smartpqi \- Microsemi Smart Family SCSI driver +.SH SYNOPSIS +.SY "modprobe smartpqi" +.RB [ disable_device_id_wildcards= { 0 | 1 }] +.RB [ disable_heartbeat= { 0 | 1 }] +.RB [ disable_ctrl_shutdown= { 0 | 1 }] +.RB [ lockup_action= { none | reboot | panic }] +.YS +.SH DESCRIPTION +.B smartpqi +is a SCSI driver for Microsemi Smart Family controllers. +.SS Supported \f[BI]ioctl\fP\/() operations +For compatibility with applications written for the +.BR cciss (4) +and +.BR hpsa (4) +drivers, many, but not all of the +.BR ioctl (2) +operations supported by the +.B hpsa +driver are also supported by the +.B smartpqi +driver. +The data structures used by these operations +are described in the Linux kernel source file +.IR include/linux/cciss_ioctl.h . +.TP +.BR CCISS_DEREGDISK ", " CCISS_REGNEWDISK ", " CCISS_REGNEWD +These operations +all do exactly the same thing, which is to cause the driver to re-scan +for new devices. +This does exactly the same thing as writing to the +.BR smartpqi -specific +host +.I rescan +attribute. +.TP +.B CCISS_GETPCIINFO +This operation Returns the PCI domain, bus, +device and function and "board ID" (PCI subsystem ID). +.TP +.B CCISS_GETDRIVVER +This operation returns the driver version in four bytes, encoded as: +.IP +.in +4n +.EX +(major_version << 28) | (minor_version << 24) | + (release << 16) | revision +.EE +.in +.TP +.B CCISS_PASSTHRU +Allows BMIC and CISS commands to be passed through to the controller. +.SS Boot options +.TP +.BR disable_device_id_wildcards= { 0 | 1 } +Disables support for device ID wildcards. +The default value is 0. +.TP +.BR disable_heartbeat= { 0 | 1 } +Disables support for the controller's heartbeat check. +This parameter is used for debugging purposes. +The default value is 0, leaving the controller's heartbeat check active. +.TP +.BR disable_ctrl_shutdown= { 0 | 1 } +Disables support for shutting down the controller in the +event of a controller lockup. +The default value is 0. +.TP +.BR lockup_action= { none | reboot | panic } +Specifies the action the driver takes when a controller +lockup is detected. +The default action is +.BR none . +.TS +l l +--- +l l. +parameter action +\fBnone\fP take controller offline only +\fBreboot\fP reboot the system +\fBpanic\fP panic the system +.TE +.RE +.SH FILES +.SS Device nodes +Logical drives are accessed via the SCSI disk driver +.RI ( sd ), +tape drives via the SCSI tape driver +.RI ( st ), +and the RAID controller via the SCSI generic driver +.RI ( sg ), +with device nodes named +.IR /dev/sd *, +.IR /dev/st *, +and +.IR /dev/sg *, +respectively. +.SS SmartPQI-specific host attribute files in \f[BI]/sys\fP +.TP +.IR /sys/class/scsi_host/host * /rescan +The host +.I rescan +attribute is a write-only attribute. +Writing to this attribute will cause the driver to scan for new, +changed, or removed devices (e.g., hot-plugged tape drives, or newly +configured or deleted logical drives) and notify the SCSI mid-layer of +any changes detected. +Usually this action is triggered automatically by configuration +changes, so the user should not normally have to write to this file. +Doing so may be useful when hot-plugging devices such as tape drives or +entire storage boxes containing pre-configured logical drives. +.TP +.IR /sys/class/scsi_host/host * /version +The host +.I version +attribute is a read-only attribute. +This attribute contains the driver version and the controller firmware +version. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/version +driver: 1.1.2\-126 +firmware: 1.29\-112 +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /lockup_action +The host +.I lockup_action +attribute is a read/write attribute. +This attribute will cause the driver to perform a specific action in the +unlikely event that a controller lockup has been detected. +See +.BR OPTIONS +above +for an explanation of the +.I lockup_action +values. +.SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP +In the file specifications below, +.I c +stands for the number of the appropriate SCSI controller, +.I b +is the bus number, +.I t +the target number, and +.I l +is the logical unit number (LUN). +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/raid_level +The +.I raid_level +attribute is read-only. +This attribute contains the RAID level of each logical drive. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/4:0:0:0/device/raid_level +RAID 0 +.EE +.in +.TP +.IR /sys/class/scsi_disk/c : b : t : l/device/sas_address +The +.I sas_address +attribute is read-only. +This attribute contains the unique identifier of the disk. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/1:0:3:0/device/sas_address +0x5001173d028543a2 +.EE +.in +.TP +.IR /sys/class/scsi_disk/c : b : t : l/device/ssd_smart_path_enabled +The +.I ssd_smart_path_enabled +attribute is read-only. +This attribute is for ioaccel-enabled volumes. +(Ioaccel is an alternative driver submission path that allows the +driver to send I/O requests directly to backend SCSI devices, +bypassing the controller firmware. +This results in an increase in performance. +This method is used for HBA disks and for logical volumes comprised of SSDs.) +Contains 1 if ioaccel is enabled for the volume and 0 otherwise. +.IP +For example: +.IP +.in +2n +.EX +$ \c +.B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled +0 +.EE +.in +.SH VERSIONS +The +.B smarpqi +driver was added in Linux 4.9. +.SH NOTES +.SS Configuration +To configure a Microsemi Smart Family controller, +refer to the User Guide for the controller, +which can be found by searching for the specific controller at +.UR https://storage.microsemi.com/ +.UE . +.SH SEE ALSO +.BR cciss (4), +.BR hpsa (4), +.BR sd (4), +.BR st (4) +.PP +.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss +in the Linux kernel source tree. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/st.4 b/man4/st.4 new file mode 100644 index 0000000..30bf7c2 --- /dev/null +++ b/man4/st.4 @@ -0,0 +1,968 @@ +.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com) +.\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.TH ST 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +st \- SCSI tape device +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);" +.BI "int ioctl(int " fd ", MTIOCTOP, (struct mtop *)" mt_cmd ); +.BI "int ioctl(int " fd ", MTIOCGET, (struct mtget *)" mt_status ); +.BI "int ioctl(int " fd ", MTIOCPOS, (struct mtpos *)" mt_pos ); +.fi +.SH DESCRIPTION +The +.B st +driver provides the interface to a variety of SCSI tape devices. +Currently, the driver takes control of all detected devices of type +\(lqsequential-access\(rq. +The +.B st +driver uses major device number 9. +.PP +Each device uses eight minor device numbers. +The lowermost five bits +in the minor numbers are assigned sequentially in the order of +detection. +In the 2.6 kernel, the bits above the eight lowermost bits are +concatenated to the five lowermost bits to form the tape number. +The minor numbers can be grouped into +two sets of four numbers: the principal (auto-rewind) minor device numbers, +.IR n , +and the \(lqno-rewind\(rq device numbers, +.RI ( n " + 128)." +Devices opened using the principal device number will be sent a +.BR REWIND +command when they are closed. +Devices opened using the \(lqno-rewind\(rq device number will not. +(Note that using an auto-rewind device for positioning the tape with, +for instance, mt does not lead to the desired result: the tape is +rewound after the mt command and the next command starts from the +beginning of the tape). +.PP +Within each group, four minor numbers are available to define +devices with different characteristics (block size, compression, +density, etc.) +When the system starts up, only the first device is available. +The other three are activated when the default +characteristics are defined (see below). +(By changing compile-time +constants, it is possible to change the balance between the maximum +number of tape drives and the number of minor numbers for each +drive. +The default allocation allows control of 32 tape drives. +For instance, it is possible to control up to 64 tape drives +with two minor numbers for different options.) +.PP +Devices are typically created by: +.PP +.in +4n +.EX +mknod \-m 666 /dev/st0 c 9 0 +mknod \-m 666 /dev/st0l c 9 32 +mknod \-m 666 /dev/st0m c 9 64 +mknod \-m 666 /dev/st0a c 9 96 +mknod \-m 666 /dev/nst0 c 9 128 +mknod \-m 666 /dev/nst0l c 9 160 +mknod \-m 666 /dev/nst0m c 9 192 +mknod \-m 666 /dev/nst0a c 9 224 +.EE +.in +.PP +There is no corresponding block device. +.PP +The driver uses an internal buffer that has to be large enough to hold +at least one tape block. +In kernels before 2.1.121, the buffer is +allocated as one contiguous block. +This limits the block size to the +largest contiguous block of memory the kernel allocator can provide. +The limit is currently 128\ kB for 32-bit architectures and +256\ kB for 64-bit architectures. +In newer kernels the driver +allocates the buffer in several parts if necessary. +By default, the +maximum number of parts is 16. +This means that the maximum block size +is very large (2\ MB if allocation of 16 blocks of 128\ kB succeeds). +.PP +The driver's internal buffer size is determined by a compile-time +constant which can be overridden with a kernel startup option. +In addition to this, the driver tries to allocate a larger temporary +buffer at run time if necessary. +However, run-time allocation of large +contiguous blocks of memory may fail and it is advisable not to rely +too much on dynamic buffer allocation with kernels older than 2.1.121 +(this applies also to demand-loading the driver with kerneld or kmod). +.PP +The driver does not specifically support any tape drive brand or +model. +After system start-up the tape device options are defined by +the drive firmware. +For example, if the drive firmware selects fixed-block mode, +the tape device uses fixed-block mode. +The options can +be changed with explicit +.BR ioctl (2) +calls and remain in effect when the device is closed and reopened. +Setting the options affects both the auto-rewind and the nonrewind +device. +.PP +Different options can be specified for the different devices within +the subgroup of four. +The options take effect when the device is +opened. +For example, the system administrator can define +one device that writes in fixed-block mode with a certain block size, +and one which writes in variable-block mode (if the drive supports +both modes). +.PP +The driver supports +.B tape partitions +if they are supported by the drive. +(Note that the tape partitions +have nothing to do with disk partitions. +A partitioned tape can be +seen as several logical tapes within one medium.) +Partition support has to be enabled with an +.BR ioctl (2). +The tape +location is preserved within each partition across partition changes. +The partition used for subsequent tape operations is +selected with an +.BR ioctl (2). +The partition switch is executed together with +the next tape operation in order to avoid unnecessary tape +movement. +The maximum number of partitions on a tape is defined by a +compile-time constant (originally four). +The driver contains an +.BR ioctl (2) +that can format a tape with either one or two partitions. +.PP +Device +.I /dev/tape +is usually created as a hard or soft link to the default tape device +on the system. +.PP +Starting from kernel 2.6.2, the driver exports in the sysfs directory +.I /sys/class/scsi_tape +the attached devices and some parameters assigned to the devices. +.SS Data transfer +The driver supports operation in both fixed-block mode and +variable-block mode (if supported by the drive). +In fixed-block mode the drive +writes blocks of the specified size and the block size is not +dependent on the byte counts of the write system calls. +In variable-block mode one tape block is written for each write call +and the byte +count determines the size of the corresponding tape block. +Note that +the blocks on the tape don't contain any information about the +writing mode: when reading, the only important thing is to use +commands that accept the block sizes on the tape. +.PP +In variable-block mode the read byte count does not have to match +the tape block size exactly. +If the byte count is larger than the +next block on tape, the driver returns the data and the function +returns the actual block size. +If the block size is larger than the +byte count, an error is returned. +.PP +In fixed-block mode the read byte counts can be arbitrary if +buffering is enabled, or a multiple of the tape block size if +buffering is disabled. +Kernels before 2.1.121 allow writes with +arbitrary byte count if buffering is enabled. +In all other cases +(kernel before 2.1.121 with buffering disabled or newer kernel) the +write byte count must be a multiple of the tape block size. +.PP +In the 2.6 kernel, the driver tries to use direct transfers between the user +buffer and the device. +If this is not possible, the driver's internal buffer +is used. +The reasons for not using direct transfers include improper alignment +of the user buffer (default is 512 bytes but this can be changed by the HBA +driver), one or more pages of the user buffer not reachable by the +SCSI adapter, and so on. +.PP +A filemark is automatically written to tape if the last tape operation +before close was a write. +.PP +When a filemark is encountered while reading, the following +happens. +If there are data remaining in the buffer when the filemark +is found, the buffered data is returned. +The next read returns zero +bytes. +The following read returns data from the next file. +The end of +recorded data is signaled by returning zero bytes for two consecutive +read calls. +The third read returns an error. +.SS Ioctls +The driver supports three +.BR ioctl (2) +requests. +Requests not recognized by the +.B st +driver are passed to the +.B SCSI +driver. +The definitions below are from +.IR /usr/include/linux/mtio.h : +.SS MTIOCTOP \(em perform a tape operation +.PP +This request takes an argument of type +.IR "(struct mtop\ *)" . +Not all drives support all operations. +The driver returns an +.B EIO +error if the drive rejects an operation. +.PP +.in +4n +.EX +/* Structure for MTIOCTOP \- mag tape op command: */ +struct mtop { + short mt_op; /* operations defined below */ + int mt_count; /* how many of them */ +}; +.EE +.in +.PP +Magnetic Tape operations for normal tape use: +.TP 14 +.B MTBSF +Backward space over +.I mt_count +filemarks. +.TP +.B MTBSFM +Backward space over +.I mt_count +filemarks. +Reposition the tape to the EOT side of the last filemark. +.TP +.B MTBSR +Backward space over +.I mt_count +records (tape blocks). +.TP +.B MTBSS +Backward space over +.I mt_count +setmarks. +.TP +.B MTCOMPRESSION +Enable compression of tape data within the drive if +.I mt_count +is nonzero and disable compression if +.I mt_count +is zero. +This command uses the MODE page 15 supported by most DATs. +.TP +.B MTEOM +Go to the end of the recorded media (for appending files). +.TP +.B MTERASE +Erase tape. +With 2.6 kernel, short erase (mark tape empty) is performed if the +argument is zero. +Otherwise, long erase (erase all) is done. +.TP +.B MTFSF +Forward space over +.I mt_count +filemarks. +.TP +.B MTFSFM +Forward space over +.I mt_count +filemarks. +Reposition the tape to the BOT side of the last filemark. +.TP +.B MTFSR +Forward space over +.I mt_count +records (tape blocks). +.TP +.B MTFSS +Forward space over +.I mt_count +setmarks. +.TP +.B MTLOAD +Execute the SCSI load command. +A special case is available for some HP +autoloaders. +If +.I mt_count +is the constant +.B MT_ST_HPLOADER_OFFSET +plus a number, the number is +sent to the drive to control the autoloader. +.TP +.B MTLOCK +Lock the tape drive door. +.TP +.B MTMKPART +Format the tape into one or two partitions. +If +.I mt_count +is positive, it gives the size of partition 1 and partition +0 contains the rest of the tape. +If +.I mt_count +is zero, the tape is formatted into one partition. +From kernel version 4.6, +.\" commit 8038e6456a3e6f5c4759e0d73c4f9165b90c93e7 +a negative +.I mt_count +specifies the size of partition 0 and +the rest of the tape contains partition 1. +The physical ordering of partitions depends on the drive. +This command is not allowed for a drive unless the partition support +is enabled for the drive (see +.BR MT_ST_CAN_PARTITIONS +below). +.TP +.B MTNOP +No op\(emflushes the driver's buffer as a side effect. +Should be used before reading status with +.BR MTIOCGET . +.TP +.B MTOFFL +Rewind and put the drive off line. +.TP +.B MTRESET +Reset drive. +.TP +.B MTRETEN +Re-tension tape. +.TP +.B MTREW +Rewind. +.TP +.B MTSEEK +Seek to the tape block number specified in +.IR mt_count . +This operation requires either a SCSI-2 drive that supports the +.B LOCATE +command (device-specific address) +or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive +Viper, Wangtek, ...). +The block number should be one that was previously returned by +.BR MTIOCPOS +if device-specific addresses are used. +.TP +.B MTSETBLK +Set the drive's block length to the value specified in +.IR mt_count . +A block length of zero sets the drive to variable block size mode. +.TP +.B MTSETDENSITY +Set the tape density to the code in +.IR mt_count . +The density codes supported by a drive can be found from the drive +documentation. +.TP +.B MTSETPART +The active partition is switched to +.IR mt_count . +The partitions are numbered from zero. +This command is not allowed for +a drive unless the partition support is enabled for the drive (see +.B MT_ST_CAN_PARTITIONS +below). +.TP +.B MTUNLOAD +Execute the SCSI unload command (does not eject the tape). +.TP +.B MTUNLOCK +Unlock the tape drive door. +.TP +.B MTWEOF +Write +.I mt_count +filemarks. +.TP +.B MTWSM +Write +.I mt_count +setmarks. +.PP +Magnetic Tape operations for setting of device options (by the superuser): +.TP 8 +.B MTSETDRVBUFFER +Set various drive and driver options according to bits encoded in +.IR mt_count . +These consist of the drive's buffering mode, a set of Boolean driver +options, the buffer write threshold, defaults for the block size and +density, and timeouts (only in kernels 2.1 and later). +A single operation can affect only one item in the list above (the +Booleans counted as one item.) +.IP +A value having zeros in the high-order 4 bits will be used to set the +drive's buffering mode. +The buffering modes are: +.RS 12 +.IP 0 4 +The drive will not report +.BR GOOD +status on write commands until the data +blocks are actually written to the medium. +.IP 1 +The drive may report +.BR GOOD +status on write commands as soon as all the +data has been transferred to the drive's internal buffer. +.IP 2 +The drive may report +.BR GOOD +status on write commands as soon as (a) all +the data has been transferred to the drive's internal buffer, and +(b) all buffered data from different initiators has been successfully +written to the medium. +.RE +.IP +To control the write threshold the value in +.I mt_count +must include the constant +.BR MT_ST_WRITE_THRESHOLD +bitwise ORed with a block count in the low 28 bits. +The block count refers to 1024-byte blocks, not the physical block +size on the tape. +The threshold cannot exceed the driver's internal buffer size (see +DESCRIPTION, above). +.IP +To set and clear the Boolean options +the value in +.I mt_count +must include one of the constants +.BR MT_ST_BOOLEANS , +.BR MT_ST_SETBOOLEANS , +.BR MT_ST_CLEARBOOLEANS , +or +.BR MT_ST_DEFBOOLEANS +bitwise ORed with +whatever combination of the following options is desired. +Using +.BR MT_ST_BOOLEANS +the options can be set to the values +defined in the corresponding bits. +With +.BR MT_ST_SETBOOLEANS +the options can be selectively set and with +.BR MT_ST_DEFBOOLEANS +selectively cleared. +.IP "" +The default options for a tape device are set with +.BR MT_ST_DEFBOOLEANS . +A nonactive tape device (e.g., device with +minor 32 or 160) is activated when the default options for it are +defined the first time. +An activated device inherits from the device +activated at start-up the options not set explicitly. +.IP "" +The Boolean options are: +.RS +.TP +.BR MT_ST_BUFFER_WRITES " (Default: true)" +Buffer all write operations in fixed-block mode. +If this option is false and the drive uses a fixed block size, then +all write operations must be for a multiple of the block size. +This option must be set false to write reliable multivolume archives. +.TP +.BR MT_ST_ASYNC_WRITES " (Default: true)" +When this option is true, write operations return immediately without +waiting for the data to be transferred to the drive if the data fits +into the driver's buffer. +The write threshold determines how full the buffer must be before a +new SCSI write command is issued. +Any errors reported by the drive will be held until the next +operation. +This option must be set false to write reliable multivolume archives. +.TP +.BR MT_ST_READ_AHEAD " (Default: true)" +This option causes the driver to provide read buffering and +read-ahead in fixed-block mode. +If this option is false and the drive uses a fixed block size, then +all read operations must be for a multiple of the block size. +.TP +.BR MT_ST_TWO_FM " (Default: false)" +This option modifies the driver behavior when a file is closed. +The normal action is to write a single filemark. +If the option is true, the driver will write two filemarks and +backspace over the second one. +.IP +Note: +This option should not be set true for QIC tape drives since they are +unable to overwrite a filemark. +These drives detect the end of recorded data by testing for blank tape +rather than two consecutive filemarks. +Most other current drives also +detect the end of recorded data and using two filemarks is usually +necessary only when interchanging tapes with some other systems. +.TP +.BR MT_ST_DEBUGGING " (Default: false)" +This option turns on various debugging messages from the driver +(effective only if the driver was compiled with +.B DEBUG +defined nonzero). +.TP +.BR MT_ST_FAST_EOM " (Default: false)" +This option causes the +.B MTEOM +operation to be sent directly to the +drive, potentially speeding up the operation but causing the driver to +lose track of the current file number normally returned by the +.B MTIOCGET +request. +If +.B MT_ST_FAST_EOM +is false, the driver will respond to an +.B MTEOM +request by forward spacing over files. +.TP +.BR MT_ST_AUTO_LOCK " (Default: false)" +When this option is true, the drive door is locked when the device is +opened and unlocked when it is closed. +.TP +.BR MT_ST_DEF_WRITES " (Default: false)" +The tape options (block size, mode, compression, etc.) may change +when changing from one device linked to a drive to another device +linked to the same drive depending on how the devices are +defined. +This option defines when the changes are enforced by the +driver using SCSI-commands and when the drives auto-detection +capabilities are relied upon. +If this option is false, the driver +sends the SCSI-commands immediately when the device is changed. +If the +option is true, the SCSI-commands are not sent until a write is +requested. +In this case, the drive firmware is allowed to detect the +tape structure when reading and the SCSI-commands are used only to +make sure that a tape is written according to the correct specification. +.TP +.BR MT_ST_CAN_BSR " (Default: false)" +When read-ahead is used, the tape must sometimes be spaced backward to the +correct position when the device is closed and the SCSI command to +space backward over records is used for this purpose. +Some older +drives can't process this command reliably and this option can be used +to instruct the driver not to use the command. +The end result is that, +with read-ahead and fixed-block mode, the tape may not be correctly +positioned within a file when the device is closed. +With 2.6 kernel, the +default is true for drives supporting SCSI-3. +.TP +.BR MT_ST_NO_BLKLIMS " (Default: false)" +Some drives don't accept the +.B "READ BLOCK LIMITS" +SCSI command. +If this is used, the driver does not use the command. +The drawback is +that the driver can't check before sending commands if the selected +block size is acceptable to the drive. +.TP +.BR MT_ST_CAN_PARTITIONS " (Default: false)" +This option enables support for several partitions within a +tape. +The option applies to all devices linked to a drive. +.TP +.BR MT_ST_SCSI2LOGICAL " (Default: false)" +This option instructs the driver to use the logical block addresses +defined in the SCSI-2 standard when performing the seek and tell +operations (both with +.B MTSEEK +and +.B MTIOCPOS +commands and when changing tape +partition). +Otherwise, the device-specific addresses are used. +It is highly advisable to set this option if the drive supports the +logical addresses because they count also filemarks. +There are some +drives that support only the logical block addresses. +.TP +.BR MT_ST_SYSV " (Default: false)" +When this option is enabled, the tape devices use the SystemV +semantics. +Otherwise, the BSD semantics are used. +The most important +difference between the semantics is what happens when a device used +for reading is closed: in System V semantics the tape is spaced forward +past the next filemark if this has not happened while using the +device. +In BSD semantics the tape position is not changed. +.TP +.BR MT_NO_WAIT " (Default: false)" +Enables immediate mode (i.e., don't wait for the command to finish) for some +commands (e.g., rewind). +.PP +An example: +.PP +.in +4n +.EX +struct mtop mt_cmd; +mt_cmd.mt_op = MTSETDRVBUFFER; +mt_cmd.mt_count = MT_ST_BOOLEANS | + MT_ST_BUFFER_WRITES | MT_ST_ASYNC_WRITES; +ioctl(fd, MTIOCTOP, mt_cmd); +.EE +.in +.RE +.IP "" +The default block size for a device can be set with +.B MT_ST_DEF_BLKSIZE +and the default density code can be set with +.BR MT_ST_DEFDENSITY . +The values for the parameters are or'ed +with the operation code. +.IP "" +With kernels 2.1.x and later, the timeout values can be set with the +subcommand +.B MT_ST_SET_TIMEOUT +ORed with the timeout in seconds. +The long timeout (used for rewinds and other commands +that may take a long time) can be set with +.BR MT_ST_SET_LONG_TIMEOUT . +The kernel defaults are very long to +make sure that a successful command is not timed out with any +drive. +Because of this, the driver may seem stuck even if it is only +waiting for the timeout. +These commands can be used to set more +practical values for a specific drive. +The timeouts set for one device +apply for all devices linked to the same drive. +.IP "" +Starting from kernels 2.4.19 and 2.5.43, the driver supports a status +bit which indicates whether the drive requests cleaning. +The method used by the +drive to return cleaning information is set using the +.B MT_ST_SEL_CLN +subcommand. +If the value is zero, the cleaning +bit is always zero. +If the value is one, the TapeAlert data defined +in the SCSI-3 standard is used (not yet implemented). +Values 2\(en17 are +reserved. +If the lowest eight bits are >= 18, bits from the extended +sense data are used. +The bits 9\(en16 specify a mask to select the bits +to look at and the bits 17\(en23 specify the bit pattern to look for. +If the bit pattern is zero, one or more bits under the mask indicate +the cleaning request. +If the pattern is nonzero, the pattern must match +the masked sense data byte. +.SS MTIOCGET \(em get status +.PP +This request takes an argument of type +.IR "(struct mtget\ *)" . +.PP +.in +4n +.EX +/* structure for MTIOCGET \- mag tape get status command */ +struct mtget { + long mt_type; + long mt_resid; + /* the following registers are device dependent */ + long mt_dsreg; + long mt_gstat; + long mt_erreg; + /* The next two fields are not always used */ + daddr_t mt_fileno; + daddr_t mt_blkno; +}; +.EE +.in +.IP \fImt_type\fP 11 +The header file defines many values for +.IR mt_type , +but the current driver reports only the generic types +.B MT_ISSCSI1 +(Generic SCSI-1 tape) +and +.B MT_ISSCSI2 +(Generic SCSI-2 tape). +.IP \fImt_resid\fP +contains the current tape partition number. +.IP \fImt_dsreg\fP +reports the drive's current settings for block size (in the low 24 +bits) and density (in the high 8 bits). +These fields are defined by +.BR MT_ST_BLKSIZE_SHIFT , +.BR MT_ST_BLKSIZE_MASK , +.BR MT_ST_DENSITY_SHIFT , +and +.BR MT_ST_DENSITY_MASK . +.IP \fImt_gstat\fP +reports generic (device independent) status information. +The header file defines macros for testing these status bits: +.RS +.HP 4 +\fBGMT_EOF\fP(\fIx\fP): +The tape is positioned just after a filemark +(always false after an +.B MTSEEK +operation). +.HP +\fBGMT_BOT\fP(\fIx\fP): +The tape is positioned at the beginning of the first file (always false +after an +.B MTSEEK +operation). +.HP +\fBGMT_EOT\fP(\fIx\fP): +A tape operation has reached the physical End Of Tape. +.HP +\fBGMT_SM\fP(\fIx\fP): +The tape is currently positioned at a setmark +(always false after an +.B MTSEEK +operation). +.HP +\fBGMT_EOD\fP(\fIx\fP): +The tape is positioned at the end of recorded data. +.HP +\fBGMT_WR_PROT\fP(\fIx\fP): +The drive is write-protected. +For some drives this can also mean that the drive does not support +writing on the current medium type. +.HP +\fBGMT_ONLINE\fP(\fIx\fP): +The last +.BR open (2) +found the drive with a tape in place and ready for operation. +.HP +\fBGMT_D_6250\fP(\fIx\fP), \fBGMT_D_1600\fP(\fIx\fP), \fBGMT_D_800\fP(\fIx\fP): +This \(lqgeneric\(rq status information reports the current +density setting for 9-track \(12" tape drives only. +.HP +\fBGMT_DR_OPEN\fP(\fIx\fP): +The drive does not have a tape in place. +.HP +\fBGMT_IM_REP_EN\fP(\fIx\fP): +Immediate report mode. +This bit is set if there are no guarantees that +the data has been physically written to the tape when the write call +returns. +It is set zero only when the driver does not buffer data and +the drive is set not to buffer data. +.HP +\fBGMT_CLN\fP(\fIx\fP): +The drive has requested cleaning. +Implemented in kernels since 2.4.19 and 2.5.43. +.RE +.IP \fImt_erreg\fP +The only field defined in +.I mt_erreg +is the recovered error count in the low 16 bits (as defined by +.BR MT_ST_SOFTERR_SHIFT +and +.BR MT_ST_SOFTERR_MASK . +Due to inconsistencies in the way drives report recovered errors, this +count is often not maintained (most drives do not by default report +soft errors but this can be changed with a SCSI MODE SELECT command). +.IP \fImt_fileno\fP +reports the current file number (zero-based). +This value is set to \-1 when the file number is unknown (e.g., after +.BR MTBSS +or +.BR MTSEEK ). +.IP \fImt_blkno\fP +reports the block number (zero-based) within the current file. +This value is set to \-1 when the block number is unknown (e.g., after +.BR MTBSF , +.BR MTBSS , +or +.BR MTSEEK ). +.SS MTIOCPOS \(em get tape position +.PP +This request takes an argument of type +.I "(struct mtpos\ *)" +and reports the drive's notion of the current tape block number, +which is not the same as +.I mt_blkno +returned by +.BR MTIOCGET . +This drive must be a SCSI-2 drive that supports the +.B "READ POSITION" +command (device-specific address) +or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive +Viper, Wangtek, ... ). +.PP +.in +4n +.EX +/* structure for MTIOCPOS \- mag tape get position command */ +struct mtpos { + long mt_blkno; /* current block number */ +}; +.EE +.in +.SH RETURN VALUE +.TP 14 +.TP +.B EACCES +An attempt was made to write or erase a write-protected tape. +(This error is not detected during +.BR open (2).) +.TP +.B EBUSY +The device is already in use or the driver was unable to allocate a +buffer. +.TP +.B EFAULT +The command parameters point to memory not belonging to the calling +process. +.TP +.B EINVAL +An +.BR ioctl (2) +had an invalid argument, or a requested block size was invalid. +.TP +.B EIO +The requested operation could not be completed. +.TP +.B ENOMEM +The byte count in +.BR read (2) +is smaller than the next physical block on the tape. +(Before 2.2.18 and 2.4.0-test6 the extra bytes have been +silently ignored.) +.TP +.B ENOSPC +A write operation could not be completed because the tape reached +end-of-medium. +.TP +.B ENOSYS +Unknown +.BR ioctl (2). +.TP +.B ENXIO +During opening, the tape device does not exist. +.TP +.B EOVERFLOW +An attempt was made to read or write a variable-length block that is +larger than the driver's internal buffer. +.TP +.B EROFS +Open is attempted with +.B O_WRONLY +or +.B O_RDWR +when the tape in the drive is write-protected. +.SH FILES +.TP +.I /dev/st* +the auto-rewind SCSI tape devices +.TP +.I /dev/nst* +the nonrewind SCSI tape devices +.\" .SH AUTHOR +.\" The driver has been written by Kai M\(:akisara (Kai.Makisara@metla.fi) +.\" starting from a driver written by Dwayne Forsyth. +.\" Several other +.\" people have also contributed to the driver. +.SH NOTES +.IP 1. 4 +When exchanging data between systems, both systems have to agree on +the physical tape block size. +The parameters of a drive after startup +are often not the ones most operating systems use with these +devices. +Most systems use drives in variable-block mode if the drive +supports that mode. +This applies to most modern drives, including +DATs, 8mm helical scan drives, DLTs, etc. +It may be advisable to use +these drives in variable-block mode also in Linux (i.e., use +.B MTSETBLK +or +.B MTSETDEFBLK +at system startup to set the mode), at least when +exchanging data with a foreign system. +The drawback of +this is that a fairly large tape block size has to be used to get +acceptable data transfer rates on the SCSI bus. +.IP 2. +Many programs (e.g., +.BR tar (1)) +allow the user to specify the blocking +factor on the command line. +Note that this determines the physical block +size on tape only in variable-block mode. +.IP 3. +In order to use SCSI tape drives, the basic SCSI driver, +a SCSI-adapter driver and the SCSI tape driver must be either +configured into the kernel or loaded as modules. +If the SCSI-tape +driver is not present, the drive is recognized but the tape support +described in this page is not available. +.IP 4. +The driver writes error messages to the console/log. +The SENSE +codes written into some messages are automatically translated to text +if verbose SCSI messages are enabled in kernel configuration. +.IP 5. +The driver's internal buffering allows good throughput in fixed-block +mode also with small +.BR read (2) +and +.BR write (2) +byte counts. +With direct transfers +this is not possible and may cause a surprise when moving to the 2.6 +kernel. +The solution is to tell the software to use larger transfers (often +telling it to use larger blocks). +If this is not possible, direct transfers can be disabled. +.SH SEE ALSO +.BR mt (1) +.PP +The file +.I drivers/scsi/README.st +or +.I Documentation/scsi/st.txt +(kernel >= 2.6) in the Linux kernel source tree contains +the most recent information about the driver and its configuration +possibilities +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/tty.4 b/man4/tty.4 new file mode 100644 index 0000000..48e0418 --- /dev/null +++ b/man4/tty.4 @@ -0,0 +1,93 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-04-07 by Michael Kerrisk +.\" +.TH TTY 4 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +tty \- controlling terminal +.SH DESCRIPTION +The file +.I /dev/tty +is a character file with major number 5 and +minor number 0, usually of mode 0666 and owner.group root.tty. +It is a synonym for the controlling terminal of a process, if any. +.PP +In addition to the +.BR ioctl (2) +requests supported by the device that +.B tty +refers to, the +.BR ioctl (2) +request +.B TIOCNOTTY +is supported. +.SS TIOCNOTTY +Detach the calling process from its controlling terminal. +.PP +If the process is the session leader, +then +.B SIGHUP +and +.B SIGCONT +signals are sent to the foreground process group +and all processes in the current session lose their controlling tty. +.PP +This +.BR ioctl (2) +call works only on file descriptors connected +to +.IR /dev/tty . +It is used by daemon processes when they are invoked +by a user at a terminal. +The process attempts to open +.IR /dev/tty . +If the open succeeds, it +detaches itself from the terminal by using +.BR TIOCNOTTY , +while if the +open fails, it is obviously not attached to a terminal and does not need +to detach itself. +.SH FILES +.I /dev/tty +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ioctl (2), +.BR ioctl_console (2), +.BR ioctl_tty (2), +.BR termios (3), +.BR ttyS (4), +.BR agetty (8), +.BR mingetty (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/ttyS.4 b/man4/ttyS.4 new file mode 100644 index 0000000..33e7ce2 --- /dev/null +++ b/man4/ttyS.4 @@ -0,0 +1,61 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:03:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH TTYS 4 1992-12-19 "Linux" "Linux Programmer's Manual" +.SH NAME +ttyS \- serial terminal lines +.SH DESCRIPTION +.B ttyS[0\-3] +are character devices for the serial terminal lines. +.PP +They are typically created by: +.PP +.in +4n +.EX +mknod \-m 660 /dev/ttyS0 c 4 64 # base address 0x3f8 +mknod \-m 660 /dev/ttyS1 c 4 65 # base address 0x2f8 +mknod \-m 660 /dev/ttyS2 c 4 66 # base address 0x3e8 +mknod \-m 660 /dev/ttyS3 c 4 67 # base address 0x2e8 +chown root:tty /dev/ttyS[0\-3] +.EE +.in +.SH FILES +.I /dev/ttyS[0\-3] +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR tty (4), +.BR agetty (8), +.BR mingetty (8), +.BR setserial (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/tty_ioctl.4 b/man4/tty_ioctl.4 new file mode 100644 index 0000000..fc4736e --- /dev/null +++ b/man4/tty_ioctl.4 @@ -0,0 +1,2 @@ +.so man2/ioctl_tty.2 +.\" Link for old name of this page diff --git a/man4/urandom.4 b/man4/urandom.4 new file mode 100644 index 0000000..b95979f --- /dev/null +++ b/man4/urandom.4 @@ -0,0 +1 @@ +.so man4/random.4 diff --git a/man4/vcs.4 b/man4/vcs.4 new file mode 100644 index 0000000..cb06278 --- /dev/null +++ b/man4/vcs.4 @@ -0,0 +1,187 @@ +.\" Copyright (c) 1995 James R. Van Zandt +.\" Sat Feb 18 09:11:07 EST 1995 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified, Sun Feb 26 15:08:05 1995, faith@cs.unc.edu +.\" 2007-12-17, Samuel Thibault : +.\" document the VT_GETHIFONTMASK ioctl +.\" " +.TH VCS 4 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +vcs, vcsa \- virtual console memory +.SH DESCRIPTION +.I /dev/vcs0 +is a character device with major number 7 and minor number +0, usually of mode 0644 and owner root.tty. +It refers to the memory of the currently +displayed virtual console terminal. +.PP +.I /dev/vcs[1\-63] +are character devices for virtual console +terminals, they have major number 7 and minor number 1 to 63, usually +mode 0644 and owner root.tty. +.IR /dev/vcsa[0\-63] +are the same, but +using +.IR "unsigned short" s +(in host byte order) that include attributes, +and prefixed with four bytes giving the screen +dimensions and cursor position: +.IR lines , +.IR columns , +.IR x , +.IR y . +.RI ( x += +.I y += 0 at the top left corner of the screen.) +.PP +When a 512-character font is loaded, +the 9th bit position can be fetched by applying the +.BR ioctl (2) +.B VT_GETHIFONTMASK +operation +(available in Linux kernels 2.6.18 and above) +on +.IR /dev/tty[1\-63] ; +the value is returned in the +.I "unsigned short" +pointed to by the third +.BR ioctl (2) +argument. +.PP +These devices replace the screendump +.BR ioctl (2) +operations of +.BR ioctl_console (2), +so the system +administrator can control access using filesystem permissions. +.PP +The devices for the first eight virtual consoles may be created by: +.PP +.in +4n +.EX +for x in 0 1 2 3 4 5 6 7 8; do + mknod \-m 644 /dev/vcs$x c 7 $x; + mknod \-m 644 /dev/vcsa$x c 7 $[$x+128]; +done +chown root:tty /dev/vcs* +.EE +.in +.PP +No +.BR ioctl (2) +requests are supported. +.SH FILES +.I /dev/vcs[0\-63] +.br +.I /dev/vcsa[0\-63] +.\" .SH AUTHOR +.\" Andries Brouwer +.SH VERSIONS +Introduced with version 1.1.92 of the Linux kernel. +.SH EXAMPLE +You may do a screendump on vt3 by switching to vt1 and typing +.PP + cat /dev/vcs3 >foo +.PP +Note that the output does not contain +newline characters, so some processing may be required, like +in +.PP + fold \-w 81 /dev/vcs3 | lpr +.PP +or (horrors) +.PP + xetterm \-dump 3 \-file /proc/self/fd/1 +.PP +The +.I /dev/vcsa0 +device is used for Braille support. +.PP +This program displays the character and screen attributes under the +cursor of the second virtual console, then changes the background color +there: +.PP +.EX +#include +#include +#include +#include +#include +#include + +int +main(void) +{ + int fd; + char *device = "/dev/vcsa2"; + char *console = "/dev/tty2"; + struct {unsigned char lines, cols, x, y;} scrn; + unsigned short s; + unsigned short mask; + unsigned char ch, attrib; + + fd = open(console, O_RDWR); + if (fd < 0) { + perror(console); + exit(EXIT_FAILURE); + } + if (ioctl(fd, VT_GETHIFONTMASK, &mask) < 0) { + perror("VT_GETHIFONTMASK"); + exit(EXIT_FAILURE); + } + (void) close(fd); + fd = open(device, O_RDWR); + if (fd < 0) { + perror(device); + exit(EXIT_FAILURE); + } + (void) read(fd, &scrn, 4); + (void) lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), 0); + (void) read(fd, &s, 2); + ch = s & 0xff; + if (attrib & mask) + ch |= 0x100; + attrib = ((s & ~mask) >> 8); + printf("ch=\(aq%c\(aq attrib=0x%02x\\n", ch, attrib); + attrib ^= 0x10; + (void) lseek(fd, \-1, 1); + (void) write(fd, &attrib, 1); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ioctl_console (2), +.BR tty (4), +.BR ttyS (4), +.BR gpm (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/vcsa.4 b/man4/vcsa.4 new file mode 100644 index 0000000..ffe8d9b --- /dev/null +++ b/man4/vcsa.4 @@ -0,0 +1 @@ +.so man4/vcs.4 diff --git a/man4/veth.4 b/man4/veth.4 new file mode 100644 index 0000000..5af44cd --- /dev/null +++ b/man4/veth.4 @@ -0,0 +1,106 @@ +.\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch), +.\" Fri, 03 Nov 2012 22:35:33 +0100 +.\" and Copyright (c) 2012 Eric W. Biederman +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, +.\" USA. +.\" %%%LICENSE_END +.\" +.\" +.TH veth 4 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +veth \- Virtual Ethernet Device +.SH DESCRIPTION +The +.B veth +devices are virtual Ethernet devices. +They can act as tunnels between network namespaces to create +a bridge to a physical network device in another namespace, +but can also be used as standalone network devices. +.PP +.B veth +devices are always created in interconnected pairs. +A pair can be created using the command: +.PP +.in +4n +.EX +# ip link add type veth peer name +.EE +.in +.PP +In the above, +.I p1-name +and +.I p2-name +are the names assigned to the two connected end points. +.PP +Packets transmitted on one device in the pair are immediately received on +the other device. +When either devices is down the link state of the pair is down. +.PP +.B veth +device pairs are useful for combining the network +facilities of the kernel together in interesting ways. +A particularly interesting use case is to place one end of a +.B veth +pair in one network namespace and the other end in another network namespace, +thus allowing communication between network namespaces. +To do this, one first creates the +.B veth +device as above and then moves one side of the pair to the other namespace: +.PP +.in +4n +.EX +# ip link set netns +.EE +.in +.PP +.BR ethtool (8) +can be used to find the peer of a +.B veth +network interface, using commands something like: +.PP +.in +4n +.EX +# \fBip link add ve_A type veth peer name ve_B\fP # Create veth pair +# \fBethtool -S ve_A\fP # Discover interface index of peer +NIC statistics: + peer_ifindex: 16 +# \fBip link | grep '^16:'\fP # Look up interface +16: ve_B@ve_A: mtu 1500 qdisc ... +.EE +.in +.PP +.SH "SEE ALSO" +.BR clone (2), +.BR network_namespaces (7), +.BR ip (8), +.BR ip-link (8), +.BR ip-netns (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/wavelan.4 b/man4/wavelan.4 new file mode 100644 index 0000000..5766b3e --- /dev/null +++ b/man4/wavelan.4 @@ -0,0 +1,153 @@ +.\" From jt@hplb.hpl.hp.com Thu Dec 19 18:31:49 1996 +.\" From: Jean Tourrilhes +.\" Address: HP Labs, Filton Road, Stoke Gifford, Bristol BS12 6QZ, U.K. +.\" Jean II - HPLB - '96 +.\" wavelan.c.4 +.\" +.\" Provenance of this page is unclear. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Licensed under the GPL, +.\" after inquiries with Jean Tourrilhes and Bruce Janson +.\" (mtk, July 2006) +.\" %%%LICENSE_END +.\" +.TH WAVELAN 4 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +wavelan \- AT&T GIS WaveLAN ISA device driver +.SH SYNOPSIS +.BI "insmod wavelan_cs.o [io=" B,B.. "] [ irq=" I,I.. "] [name=" N,N.. ] +.SH DESCRIPTION +.I This driver is obsolete: +it was removed from the kernel in version 2.6.35. +.PP +.I wavelan +is the low-level device driver for the NCR / AT&T / Lucent +.B WaveLAN ISA +and Digital (DEC) +.B RoamAbout DS +wireless ethernet adapter. +This driver is available as a module or +might be compiled in the kernel. +This driver supports multiple cards +in both forms (up to 4) and allocates the next available ethernet +device (eth0..eth#) for each card found, unless a device name is +explicitly specified (see below). +This device name will be reported +in the kernel log file with the MAC address, NWID and frequency used +by the card. +.SS Parameters +This section apply to the module form (parameters passed on the +.BR insmod (8) +command line). +If the driver is included in the kernel, use the +.I ether=IRQ,IO,NAME +syntax on the kernel command line. +.TP +.B io +Specify the list of base address where to search for wavelan cards +(setting by dip switch on the card). +If you don't specify any io +address, the driver will scan 0x390 and 0x3E0 addresses, which might +conflict with other hardware... +.TP +.B irq +Set the list of irq that each wavelan card should use (the value is +saved in permanent storage for future use). +.TP +.B name +Set the list of name to be used for each wavelan cards device (name +used by +.BR ifconfig (8)). +.SS Wireless extensions +Use +.BR iwconfig (8) +to manipulate wireless extensions. +.SS NWID (or domain) +Set the network ID +.RI [ 0 +to +.IR FFFF ] +or disable it +.RI [ off ]. +As the NWID is stored in the card Permanent Storage Area, it will be +reuse at any further invocation of the driver. +.SS Frequency & channels +For the 2.4\ GHz 2.00 Hardware, you are able to set the frequency by +specifying one of the 10 defined channels +.RI ( 2.412, +.I 2.422, 2.425, 2.4305, 2.432, 2.442, 2.452, 2.460, 2.462 +or +.IR 2.484 ) +or directly by its value. +The frequency is changed immediately and +permanently. +Frequency availability depends on the regulations... +.SS Statistics spy +Set a list of MAC addresses in the driver (up to 8) and get the last +quality of link for each of those (see +.BR iwspy (8)). +.SS /proc/net/wireless +.I status +is the status reported by the modem. +.I Link quality +reports the quality of the modulation on the air (direct sequence +spread spectrum) [max = 16]. +.I Level +and +.I Noise +refer to the signal level and noise level [max = 64]. +The +.I crypt discarded packet +and +.I misc discarded packet +counters are not implemented. +.SS Private ioctl +You may use +.BR iwpriv (8) +to manipulate private ioctls. +.SS Quality and level threshold +Enable you the define the quality and level threshold used by the +modem (packet below that level are discarded). +.SS Histogram +This functionality makes it possible to set a number of +signal level intervals and +to count the number of packets received in each of those defined +intervals. +This distribution might be used to calculate the mean value +and standard deviation of the signal level. +.SS Specific notes +This driver fails to detect some +.B non-NCR/AT&T/Lucent +Wavelan cards. +If this happens for you, you must look in the source code on +how to add your card to the detection routine. +.PP +Some of the mentioned features are optional. +You may enable to disable +them by changing flags in the driver header and recompile. +.\" .SH AUTHOR +.\" Bruce Janson \(em bruce@cs.usyd.edu.au +.\" .br +.\" Jean Tourrilhes \(em jt@hplb.hpl.hp.com +.\" .br +.\" (and others; see source code for details) +.\" +.\" SEE ALSO part +.\" +.SH SEE ALSO +.BR wavelan_cs (4), +.BR ifconfig (8), +.BR insmod (8), +.BR iwconfig (8), +.BR iwpriv (8), +.BR iwspy (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man4/zero.4 b/man4/zero.4 new file mode 100644 index 0000000..15a39be --- /dev/null +++ b/man4/zero.4 @@ -0,0 +1 @@ +.so man4/null.4 diff --git a/man5/acct.5 b/man5/acct.5 new file mode 100644 index 0000000..a3b83cf --- /dev/null +++ b/man5/acct.5 @@ -0,0 +1,187 @@ +.\" Copyright (C) 2008, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH ACCT 5 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +acct \- process accounting file +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +If the kernel is built with the process accounting option enabled +.RB ( CONFIG_BSD_PROCESS_ACCT ), +then calling +.BR acct (2) +starts process accounting, for example: +.PP +.in +4n +acct("/var/log/pacct"); +.in +.PP +When process accounting is enabled, the kernel writes a record +to the accounting file as each process on the system terminates. +This record contains information about the terminated process, +and is defined in +.I +as follows: +.PP +.in +4n +.EX +#define ACCT_COMM 16 + +typedef u_int16_t comp_t; + +struct acct { + char ac_flag; /* Accounting flags */ + u_int16_t ac_uid; /* Accounting user ID */ + u_int16_t ac_gid; /* Accounting group ID */ + u_int16_t ac_tty; /* Controlling terminal */ + u_int32_t ac_btime; /* Process creation time + (seconds since the Epoch) */ + comp_t ac_utime; /* User CPU time */ + comp_t ac_stime; /* System CPU time */ + comp_t ac_etime; /* Elapsed time */ + comp_t ac_mem; /* Average memory usage (kB) */ + comp_t ac_io; /* Characters transferred (unused) */ + comp_t ac_rw; /* Blocks read or written (unused) */ + comp_t ac_minflt; /* Minor page faults */ + comp_t ac_majflt; /* Major page faults */ + comp_t ac_swaps; /* Number of swaps (unused) */ + u_int32_t ac_exitcode; /* Process termination status + (see wait(2)) */ + char ac_comm[ACCT_COMM+1]; + /* Command name (basename of last + executed command; null-terminated) */ + char ac_pad[\fIX\fP]; /* padding bytes */ +}; + +enum { /* Bits that may be set in ac_flag field */ + AFORK = 0x01, /* Has executed fork, but no exec */ + ASU = 0x02, /* Used superuser privileges */ + ACORE = 0x08, /* Dumped core */ + AXSIG = 0x10 /* Killed by a signal */ +}; +.EE +.in +.PP +The +.I comp_t +data type is a floating-point value consisting of a 3-bit, base-8 exponent, +and a 13-bit mantissa. +A value, +.IR c , +of this type can be converted to a (long) integer as follows: +.PP +.nf + v = (c & 0x1fff) << (((c >> 13) & 0x7) * 3); +.fi +.PP +The +.IR ac_utime , +.IR ac_stime , +and +.I ac_etime +fields measure time in "clock ticks"; divide these values by +.I sysconf(_SC_CLK_TCK) +to convert them to seconds. +.SS Version 3 accounting file format +Since kernel 2.6.8, +an optional alternative version of the accounting file can be produced +if the +.B CONFIG_BSD_PROCESS_ACCT_V3 +option is set when building the kernel. +With this option is set, +the records written to the accounting file contain additional fields, +and the width of +.I c_uid +and +.I ac_gid +fields is widened from 16 to 32 bits +(in line with the increased size of UID and GIDs in Linux 2.4 and later). +The records are defined as follows: +.PP +.in +4n +.EX +struct acct_v3 { + char ac_flag; /* Flags */ + char ac_version; /* Always set to ACCT_VERSION (3) */ + u_int16_t ac_tty; /* Controlling terminal */ + u_int32_t ac_exitcode; /* Process termination status */ + u_int32_t ac_uid; /* Real user ID */ + u_int32_t ac_gid; /* Real group ID */ + u_int32_t ac_pid; /* Process ID */ + u_int32_t ac_ppid; /* Parent process ID */ + u_int32_t ac_btime; /* Process creation time */ + float ac_etime; /* Elapsed time */ + comp_t ac_utime; /* User CPU time */ + comp_t ac_stime; /* System time */ + comp_t ac_mem; /* Average memory usage (kB) */ + comp_t ac_io; /* Characters transferred (unused) */ + comp_t ac_rw; /* Blocks read or written + (unused) */ + comp_t ac_minflt; /* Minor page faults */ + comp_t ac_majflt; /* Major page faults */ + comp_t ac_swaps; /* Number of swaps (unused) */ + char ac_comm[ACCT_COMM]; /* Command name */ +}; +.EE +.in +.SH VERSIONS +The +.I acct_v3 +structure is defined in glibc since version 2.6. +.SH CONFORMING TO +Process accounting originated on BSD. +Although it is present on most systems, it is not standardized, +and the details vary somewhat between systems. +.SH NOTES +Records in the accounting file are ordered by termination time of +the process. +.PP +In kernels up to and including 2.6.9, +a separate accounting record is written for each thread created using +the NPTL threading library; +since Linux 2.6.10, +a single accounting record is written for the entire process +on termination of the last thread in the process. +.PP +The +.I /proc/sys/kernel/acct +file, described in +.BR proc (5), +defines settings that control the behavior of process accounting +when disk space runs low. +.SH SEE ALSO +.BR lastcomm (1), +.BR acct (2), +.BR accton (8), +.BR sa (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/attr.5 b/man5/attr.5 new file mode 100644 index 0000000..e979971 --- /dev/null +++ b/man5/attr.5 @@ -0,0 +1,2 @@ +.so man7/xattr.7 +.\" Page was imported from 'attr' project which had it in Section 5 diff --git a/man5/charmap.5 b/man5/charmap.5 new file mode 100644 index 0000000..ad0a639 --- /dev/null +++ b/man5/charmap.5 @@ -0,0 +1,128 @@ +.\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH CHARMAP 5 2016-07-17 "GNU" "Linux Programmer's Manual" +.SH NAME +charmap \- character set description file +.SH DESCRIPTION +A character set description (charmap) defines all available characters +and their encodings in a character set. +.BR localedef (1) +can use charmaps to create locale variants for different character sets. +.SS Syntax +The charmap file starts with a header that may consist of the +following keywords: +.TP +.RI < code_set_name > +is followed by the name of the character map. +.TP +.RI < comment_char > +is followed by a character that will be used as the comment character +for the rest of the file. +It defaults to the number sign (#). +.TP +.RI < escape_char > +is followed by a character that should be used as the escape character +for the rest of the file to mark characters that should be interpreted +in a special way. +It defaults to the backslash (\\). +.TP +.RI < mb_cur_max > +is followed by the maximum number of bytes for a character. +The default value is 1. +.TP +.RI < mb_cur_min > +is followed by the minimum number of bytes for a character. +This value must be less than or equal than +.RI < mb_cur_max >. +If not specified, it defaults to +.RI < mb_cur_max >. +.PP +The character set definition section starts with the keyword +.I CHARMAP +in the first column. +.PP +The following lines may have one of the two following forms to +define the character set: +.TP +.RI < character >\ byte-sequence\ comment +This form defines exactly one character and its byte sequence, +.I comment +being optional. +.TP +.RI < character >..< character >\ byte-sequence\ comment +This form defines a character range and its byte sequence, +.I comment +being optional. +.PP +The character set definition section ends with the string +.IR "END CHARMAP" . +.PP +The character set definition section may optionally be followed by a +section to define widths of characters. +.PP +The +.I WIDTH_DEFAULT +keyword can be used to define the default width for all characters +not explicitly listed. +The default character width is 1. +.PP +The width section for individual characters starts with the keyword +.I WIDTH +in the first column. +.PP +The following lines may have one of the two following forms to +define the widths of the characters: +.TP +.RI < character >\ width +This form defines the width of exactly one character. +.TP +.RI < character >...< character >\ width +This form defines the width for all the characters in the range. +.PP +The width definition section ends with the string +.IR "END WIDTH" . +.SH FILES +.TP +.I /usr/share/i18n/charmaps +Usual default character map path. +.SH CONFORMING TO +POSIX.2. +.SH EXAMPLE +The Euro sign is defined as follows in the +.I UTF\-8 +charmap: +.PP +.nf + /xe2/x82/xac EURO SIGN +.fi +.SH SEE ALSO +.BR iconv (1), +.BR locale (1), +.BR localedef (1), +.BR locale (5), +.BR charsets (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/core.5 b/man5/core.5 new file mode 100644 index 0000000..535c409 --- /dev/null +++ b/man5/core.5 @@ -0,0 +1,665 @@ +.\" Copyright (c) 2006, 2008 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH CORE 5 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +core \- core dump file +.SH DESCRIPTION +The default action of certain signals is to cause a process to terminate +and produce a +.IR "core dump file" , +a disk file containing an image of the process's memory at +the time of termination. +This image can be used in a debugger (e.g., +.BR gdb (1)) +to inspect the state of the program at the time that it terminated. +A list of the signals which cause a process to dump core can be found in +.BR signal (7). +.PP +A process can set its soft +.B RLIMIT_CORE +resource limit to place an upper limit on the size of the core dump file +that will be produced if it receives a "core dump" signal; see +.BR getrlimit (2) +for details. +.PP +There are various circumstances in which a core dump file is +not produced: +.IP * 3 +The process does not have permission to write the core file. +(By default, the core file is called +.IR core +or +.IR core.pid , +where +.I pid +is the ID of the process that dumped core, +and is created in the current working directory. +See below for details on naming.) +Writing the core file fails if the directory in which +it is to be created is nonwritable, +or if a file with the same name exists and +is not writable +or is not a regular file +(e.g., it is a directory or a symbolic link). +.IP * +A (writable, regular) file with the same name as would be used for the +core dump already exists, but there is more than one hard link to that +file. +.IP * +The filesystem where the core dump file would be created is full; +or has run out of inodes; or is mounted read-only; +or the user has reached their quota for the filesystem. +.IP * +The directory in which the core dump file is to be created does +not exist. +.IP * +The +.B RLIMIT_CORE +(core file size) or +.B RLIMIT_FSIZE +(file size) resource limits for the process are set to zero; see +.BR getrlimit (2) +and the documentation of the shell's +.I ulimit +command +.RI ( limit +in +.BR csh (1)). +.IP * +The binary being executed by the process does not have read +permission enabled. +.IP * +The process is executing a set-user-ID (set-group-ID) program +that is owned by a user (group) other than the real user (group) +ID of the process, +or the process is executing a program that has file capabilities (see +.BR capabilities (7)). +(However, see the description of the +.BR prctl (2) +.B PR_SET_DUMPABLE +operation, and the description of the +.I /proc/sys/fs/suid_dumpable +.\" FIXME . Perhaps relocate discussion of /proc/sys/fs/suid_dumpable +.\" and PR_SET_DUMPABLE to this page? +file in +.BR proc (5).) +.IP * +.I /proc/sys/kernel/core_pattern +is empty and +.I /proc/sys/kernel/core_uses_pid +contains the value 0. +(These files are described below.) +Note that if +.I /proc/sys/kernel/core_pattern +is empty and +.I /proc/sys/kernel/core_uses_pid +contains the value 1, +core dump files will have names of the form +.IR .pid , +and such files are hidden unless one uses the +.BR ls (1) +.I -a +option. +.IP * +(Since Linux 3.7) +.\" commit 046d662f481830e652ac34cd112249adde16452a +The kernel was configured without the +.BR CONFIG_COREDUMP +option. +.PP +In addition, +a core dump may exclude part of the address space of the process if the +.BR madvise (2) +.B MADV_DONTDUMP +flag was employed. +.PP +On systems that employ +.BR systemd (1) +as the +.I init +framework, core dumps may instead be placed in a location determined by +.BR systemd (1). +See below for further details. +.\" +.SS Naming of core dump files +By default, a core dump file is named +.IR core , +but the +.I /proc/sys/kernel/core_pattern +file (since Linux 2.6 and 2.4.21) +can be set to define a template that is used to name core dump files. +The template can contain % specifiers which are substituted +by the following values when a core file is created: +.PP +.RS 4 +.PD 0 +.TP 4 +%% +a single % character +.TP +%c +core file size soft resource limit of crashing process (since Linux 2.6.24) +.TP +%d +.\" Added in git commit 12a2b4b2241e318b4f6df31228e4272d2c2968a1 +dump mode\(emsame as value returned by +.BR prctl (2) +.B PR_GET_DUMPABLE +(since Linux 3.7) +.TP +%e +executable filename (without path prefix) +.TP +%E +pathname of executable, +with slashes (\(aq/\(aq) replaced by exclamation marks (\(aq!\(aq) +(since Linux 3.0). +.TP +%g +(numeric) real GID of dumped process +.TP +%h +hostname (same as \fInodename\fP returned by \fBuname\fP(2)) +.TP +%i +TID of thread that triggered core dump, +as seen in the PID namespace in which the thread resides +.\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 +(since Linux 3.18) +.TP +%I +TID of thread that triggered core dump, as seen in the initial PID namespace +.\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 +(since Linux 3.18) +.TP +%p +PID of dumped process, +as seen in the PID namespace in which the process resides +.TP +%P +.\" Added in git commit 65aafb1e7484b7434a0c1d4c593191ebe5776a2f +PID of dumped process, as seen in the initial PID namespace +(since Linux 3.12) +.TP +%s +number of signal causing dump +.TP +%t +time of dump, expressed as seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC) +.TP +%u +(numeric) real UID of dumped process +.PD +.RE +.PP +A single % at the end of the template is dropped from the +core filename, as is the combination of a % followed by any +character other than those listed above. +All other characters in the template become a literal +part of the core filename. +The template may include \(aq/\(aq characters, which are interpreted +as delimiters for directory names. +The maximum size of the resulting core filename is 128 bytes (64 bytes +in kernels before 2.6.19). +The default value in this file is "core". +For backward compatibility, if +.I /proc/sys/kernel/core_pattern +does not include +.I %p +and +.I /proc/sys/kernel/core_uses_pid +(see below) +is nonzero, then .PID will be appended to the core filename. +.PP +Paths are interpreted according to the settings that are active for the +crashing process. +That means the crashing process's mount namespace (see +.BR mount_namespaces (7)), +its current working directory (found via +.BR getcwd (2)), +and its root directory (see +.BR chroot (2)). +.PP +Since version 2.4, Linux has also provided +a more primitive method of controlling +the name of the core dump file. +If the +.I /proc/sys/kernel/core_uses_pid +file contains the value 0, then a core dump file is simply named +.IR core . +If this file contains a nonzero value, then the core dump file includes +the process ID in a name of the form +.IR core.PID . +.PP +Since Linux 3.6, +.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 +if +.I /proc/sys/fs/suid_dumpable +is set to 2 ("suidsafe"), the pattern must be either an absolute pathname +(starting with a leading \(aq/\(aq character) or a pipe, as defined below. +.SS Piping core dumps to a program +Since kernel 2.6.19, Linux supports an alternate syntax for the +.I /proc/sys/kernel/core_pattern +file. +If the first character of this file is a pipe symbol (\fB|\fP), +then the remainder of the line is interpreted as the command-line for +a user-space program (or script) that is to be executed. +Instead of being written to a disk file, the core dump is given as +standard input to the program. +Note the following points: +.IP * 3 +The program must be specified using an absolute pathname (or a +pathname relative to the root directory, \fI/\fP), +and must immediately follow the '|' character. +.IP * +The command-line arguments can include any of +the % specifiers listed above. +For example, to pass the PID of the process that is being dumped, specify +.I %p +in an argument. +.IP * +The process created to run the program runs as user and group +.IR root . +.IP * +Running as +.I root +does not confer any exceptional security bypasses. +Namely, LSMs (e.g., SELinux) are still active and may prevent the handler +from accessing details about the crashed process via +.IR /proc/[pid] . +.IP * +The program pathname is interpreted with respect to the initial mount namespace +as it is always executed there. +It is not affected by the settings +(e.g., root directory, mount namespace, current working directory) +of the crashing process. +.IP * +The process runs in the initial namespaces +(PID, mount, user, and so on) +and not in the namespaces of the crashing process. +One can utilize specifiers such as +.I %P +to find the right +.I /proc/[pid] +directory and probe/enter the crashing process's namespaces if needed. +.IP * +The process starts with its current working directory +as the root directory. +If desired, it is possible change to the working directory of +the dumping process by employing the value provided by the +.I %P +specifier to change to the location of the dumping process via +.IR /proc/[pid]/cwd . +.IP * +Command-line arguments can be supplied to the +program (since Linux 2.6.24), +delimited by white space (up to a total line length of 128 bytes). +.IP * +The +.B RLIMIT_CORE +limit is not enforced for core dumps that are piped to a program +via this mechanism. +.\" +.SS /proc/sys/kernel/core_pipe_limit +When collecting core dumps via a pipe to a user-space program, +it can be useful for the collecting program to gather data about +the crashing process from that process's +.IR /proc/[pid] +directory. +In order to do this safely, +the kernel must wait for the program collecting the core dump to exit, +so as not to remove the crashing process's +.IR /proc/[pid] +files prematurely. +This in turn creates the +possibility that a misbehaving collecting program can block +the reaping of a crashed process by simply never exiting. +.PP +Since Linux 2.6.32, +.\" commit a293980c2e261bd5b0d2a77340dd04f684caff58 +the +.I /proc/sys/kernel/core_pipe_limit +can be used to defend against this possibility. +The value in this file defines how many concurrent crashing +processes may be piped to user-space programs in parallel. +If this value is exceeded, then those crashing processes above this value +are noted in the kernel log and their core dumps are skipped. +.PP +A value of 0 in this file is special. +It indicates that unlimited processes may be captured in parallel, +but that no waiting will take place (i.e., the collecting +program is not guaranteed access to +.IR /proc/ ). +The default value for this file is 0. +.\" +.SS Controlling which mappings are written to the core dump +Since kernel 2.6.23, the Linux-specific +.IR /proc/[pid]/coredump_filter +file can be used to control which memory segments are written to the +core dump file in the event that a core dump is performed for the +process with the corresponding process ID. +.PP +The value in the file is a bit mask of memory mapping types (see +.BR mmap (2)). +If a bit is set in the mask, then memory mappings of the +corresponding type are dumped; otherwise they are not dumped. +The bits in this file have the following meanings: +.PP +.PD 0 +.RS 4 +.TP +bit 0 +Dump anonymous private mappings. +.TP +bit 1 +Dump anonymous shared mappings. +.TP +bit 2 +Dump file-backed private mappings. +.TP +bit 3 +Dump file-backed shared mappings. +.\" file-backed shared mappings of course also update the underlying +.\" mapped file. +.TP +bit 4 (since Linux 2.6.24) +Dump ELF headers. +.TP +bit 5 (since Linux 2.6.28) +Dump private huge pages. +.TP +bit 6 (since Linux 2.6.28) +Dump shared huge pages. +.TP +bit 7 (since Linux 4.4) +.\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 +Dump private DAX pages. +.TP +bit 8 (since Linux 4.4) +.\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 +Dump shared DAX pages. +.RE +.PD +.PP +By default, the following bits are set: 0, 1, 4 (if the +.B CONFIG_CORE_DUMP_DEFAULT_ELF_HEADERS +kernel configuration option is enabled), and 5. +This default can be modified at boot time using the +.I coredump_filter +boot option. +.PP +The value of this file is displayed in hexadecimal. +(The default value is thus displayed as 33.) +.PP +Memory-mapped I/O pages such as frame buffer are never dumped, and +virtual DSO pages are always dumped, regardless of the +.I coredump_filter +value. +.PP +A child process created via +.BR fork (2) +inherits its parent's +.I coredump_filter +value; +the +.I coredump_filter +value is preserved across an +.BR execve (2). +.PP +It can be useful to set +.I coredump_filter +in the parent shell before running a program, for example: +.PP +.in +4n +.EX +.RB "$" " echo 0x7 > /proc/self/coredump_filter" +.RB "$" " ./some_program" +.EE +.in +.PP +This file is provided only if the kernel was built with the +.B CONFIG_ELF_CORE +configuration option. +.\" +.SS Core dumps and systemd +On systems using the +.BR systemd (1) +.I init +framework, core dumps may be placed in a location determined by +.BR systemd (1). +To do this, +.BR systemd (1) +employs the +.I core_pattern +feature that allows piping core dumps to a program. +One can verify this by checking whether core dumps are being piped to the +.BR systemd-coredump (8) +program: +.PP +.in +4n +.EX +$ \fBcat /proc/sys/kernel/core_pattern\fP +|/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %e +.EE +.in +.PP +In this case, core dumps will be placed in the location configured for +.BR systemd-coredump (8), +typically as +.BR lz4 (1) +compressed files in the directory +.IR /var/lib/systemd/coredump/ . +One can list the core dumps that have been recorded by +.BR systemd-coredump (8) +using +.BR coredumpctl (1): +.PP +.in +2n +.EX +$ \fBcoredumpctl list | tail -5\fP +Wed 2017-10-11 22:25:30 CEST 2748 1000 1000 3 present /usr/bin/sleep +Thu 2017-10-12 06:29:10 CEST 2716 1000 1000 3 present /usr/bin/sleep +Thu 2017-10-12 06:30:50 CEST 2767 1000 1000 3 present /usr/bin/sleep +Thu 2017-10-12 06:37:40 CEST 2918 1000 1000 3 present /usr/bin/cat +Thu 2017-10-12 08:13:07 CEST 2955 1000 1000 3 present /usr/bin/cat +.EE +.in +.PP +The information shown for each core dump includes the date and time +of the dump, the PID, UID, and GID of the dumping process, +the signal number that caused the core dump, +and the pathname of the executable that was being run by the dumped process. +Various options to +.BR coredumpctl (1) +allow a specified coredump file to be pulled from the +.BR systemd (1) +location into a specified file. +For example, to extract the core dump for PID 2955 shown above to a file named +.IR core +in the current directory, one could use: +.PP +.in +4n +.EX +$ \fBcoredumpctl dump 2955 -o core\fP +.EE +.in +.PP +For more extensive details, see the +.BR coredumpctl (1) +manual page. +.PP +To disable the +.BR systemd (1) +mechanism that archives core dumps, restoring to something more like +traditional Linux behavior, one can set an override for the +.BR systemd (1) +mechanism, using something like: +.PP +.in +2n +.EX +# echo "kernel.core_pattern=core.%p" > /etc/sysctl.d/50-coredump.conf +# /lib/systemd/systemd-sysctl +.EE +.in +.PP +.\" +.SH NOTES +The +.BR gdb (1) +.I gcore +command can be used to obtain a core dump of a running process. +.PP +In Linux versions up to and including 2.6.27, +.\" Changed with commit 6409324b385f3f63a03645b4422e3be67348d922 +if a multithreaded process (or, more precisely, a process that +shares its memory with another process by being created with the +.B CLONE_VM +flag of +.BR clone (2)) +dumps core, then the process ID is always appended to the core filename, +unless the process ID was already included elsewhere in the +filename via a +.I %p +specification in +.IR /proc/sys/kernel/core_pattern . +(This is primarily useful when employing the obsolete +LinuxThreads implementation, +where each thread of a process has a different PID.) +.\" Always including the PID in the name of the core file made +.\" sense for LinuxThreads, where each thread had a unique PID, +.\" but doesn't seem to serve any purpose with NPTL, where all the +.\" threads in a process share the same PID (as POSIX.1 requires). +.\" Probably the behavior is maintained so that applications using +.\" LinuxThreads continue appending the PID (the kernel has no easy +.\" way of telling which threading implementation the user-space +.\" application is using). -- mtk, April 2006 +.SH EXAMPLE +The program below can be used to demonstrate the use of the +pipe syntax in the +.I /proc/sys/kernel/core_pattern +file. +The following shell session demonstrates the use of this program +(compiled to create an executable named +.IR core_pattern_pipe_test ): +.PP +.in +4n +.EX +.RB "$" " cc \-o core_pattern_pipe_test core_pattern_pipe_test.c" +.RB "$" " su" +Password: +.RB "#" " echo \(dq|$PWD/core_pattern_pipe_test %p \ +UID=%u GID=%g sig=%s\(dq > \e" +.B " /proc/sys/kernel/core_pattern" +.RB "#" " exit" +.RB "$" " sleep 100" +.BR "^\e" " # type control-backslash" +Quit (core dumped) +.RB "$" " cat core.info" +argc=5 +argc[0]= +argc[1]=<20575> +argc[2]= +argc[3]= +argc[4]= +Total bytes in core dump: 282624 +.EE +.in +.SS Program source +\& +.EX +/* core_pattern_pipe_test.c */ + +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +#define BUF_SIZE 1024 + +int +main(int argc, char *argv[]) +{ + int tot, j; + ssize_t nread; + char buf[BUF_SIZE]; + FILE *fp; + char cwd[PATH_MAX]; + + /* Change our current working directory to that of the + crashing process */ + + snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]); + chdir(cwd); + + /* Write output to file "core.info" in that directory */ + + fp = fopen("core.info", "w+"); + if (fp == NULL) + exit(EXIT_FAILURE); + + /* Display command\-line arguments given to core_pattern + pipe program */ + + fprintf(fp, "argc=%d\\n", argc); + for (j = 0; j < argc; j++) + fprintf(fp, "argc[%d]=<%s>\\n", j, argv[j]); + + /* Count bytes in standard input (the core dump) */ + + tot = 0; + while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0) + tot += nread; + fprintf(fp, "Total bytes in core dump: %d\\n", tot); + + fclose(fp); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bash (1), +.BR coredumpctl (1), +.BR gdb (1), +.BR getrlimit (2), +.BR mmap (2), +.BR prctl (2), +.BR sigaction (2), +.BR elf (5), +.BR proc (5), +.BR pthreads (7), +.BR signal (7), +.BR systemd-coredump (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/dir_colors.5 b/man5/dir_colors.5 new file mode 100644 index 0000000..126cf9a --- /dev/null +++ b/man5/dir_colors.5 @@ -0,0 +1,419 @@ +.\" manpage for /etc/dir_colors, config file for dircolors(1) +.\" extracted from color-ls 3.12.0.3 dircolors(1) manpage +.\" +.\" %%%LICENSE_START(LDPv1) +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Dec 22 22:25:33 2001 by Martin Schulze +.\" +.TH DIR_COLORS 5 2013-08-09 "GNU" "Linux User Manual" +.SH NAME +dir_colors \- configuration file for dircolors(1) +.SH DESCRIPTION +The program +.BR ls (1) +uses the environment variable +.B LS_COLORS +to determine the colors in which the filenames are to be displayed. +This environment variable is usually set by a command like +.PP +.RS +eval \`dircolors some_path/dir_colors\` +.RE +.PP +found in a system default shell initialization file, like +.I /etc/profile +or +.IR /etc/csh.cshrc . +(See also +.BR dircolors (1).) +Usually, the file used here is +.I /etc/DIR_COLORS +and can be overridden by a +.I .dir_colors +file in one's home directory. +.PP +This configuration file consists of several statements, one per line. +Anything right of a hash mark (#) is treated as a comment, if the +hash mark is at the beginning of a line or is preceded by at least one +whitespace. +Blank lines are ignored. +.PP +The +.I global +section of the file consists of any statement before the first +.B TERM +statement. +Any statement in the global section of the file is +considered valid for all terminal types. +Following the global section +is one or more +.I terminal-specific +sections, preceded by one or more +.B TERM +statements which specify the terminal types (as given by the +.B TERM +environment variable) the following declarations apply to. +It is always possible to override a global declaration by a subsequent +terminal-specific one. +.PP +The following statements are recognized; case is insignificant: +.TP +.B TERM \fIterminal-type\fR +Starts a terminal-specific section and specifies which terminal it +applies to. +Multiple +.B TERM +statements can be used to create a section which applies for several +terminal types. +.TP +.B COLOR yes|all|no|none|tty +(Slackware only; ignored by GNU +.BR dircolors (1).) +Specifies that colorization should always be enabled (\fIyes\fR or +\fIall\fR), never enabled (\fIno\fR or \fInone\fR), or enabled only if +the output is a terminal (\fItty\fR). +The default is \fIno\fR. +.TP +.B EIGHTBIT yes|no +(Slackware only; ignored by GNU +.BR dircolors (1).) +Specifies that eight-bit ISO 8859 characters should be enabled by +default. +For compatibility reasons, this can also be specified as 1 for +\fIyes\fR or 0 for \fIno\fR. +The default is \fIno\fR. +.TP +.B OPTIONS \fIoptions\fR +(Slackware only; ignored by GNU +.BR dircolors (1).) +Adds command-line options to the default +.B ls +command line. +The options can be any valid +.B ls +command-line options, and should include the leading minus sign. +Note that +.B dircolors +does not verify the validity of these options. +.TP +.B NORMAL \fIcolor-sequence\fR +Specifies the color used for normal (nonfilename) text. +.IP +Synonym: +.BR NORM . +.TP +.B FILE \fIcolor-sequence\fR +Specifies the color used for a regular file. +.TP +.B DIR \fIcolor-sequence\fR +Specifies the color used for directories. +.TP +.B LINK \fIcolor-sequence\fR +Specifies the color used for a symbolic link. +.IP +Synonyms: +.BR LNK , +.BR SYMLINK . +.TP +.B ORPHAN \fIcolor-sequence\fR +Specifies the color used for an orphaned symbolic link (one which +points to a nonexistent file). +If this is unspecified, +.B ls +will use the +.B LINK +color instead. +.TP +.B MISSING \fIcolor-sequence\fR +Specifies the color used for a missing file (a nonexistent file which +nevertheless has a symbolic link pointing to it). +If this is unspecified, +.B ls +will use the +.B FILE +color instead. +.TP +.B FIFO \fIcolor-sequence\fR +Specifies the color used for a FIFO (named pipe). +.IP +Synonym: +.BR PIPE . +.TP +.B SOCK \fIcolor-sequence\fR +Specifies the color used for a socket. +.TP +.B DOOR \fIcolor-sequence\fR +(Supported since fileutils 4.1) +Specifies the color used for a door (Solaris 2.5 and later). +.TP +.B BLK \fIcolor-sequence\fR +Specifies the color used for a block device special file. +.IP +Synonym: +.BR BLOCK . +.TP +.B CHR \fIcolor-sequence\fR +Specifies the color used for a character device special file. +.IP +Synonym: +.BR CHAR . +.TP +.B EXEC \fIcolor-sequence\fR +Specifies the color used for a file with the executable attribute set. +.TP +.B SUID \fIcolor-sequence\fR +Specifies the color used for a file with the set-user-ID attribute set. +.IP +Synonym: +.BR SETUID . +.TP +.B SGID \fIcolor-sequence\fR +Specifies the color used for a file with the set-group-ID attribute set. +.IP +Synonym: +.BR SETGID . +.TP +.B STICKY \fIcolor-sequence\fR +Specifies the color used for a directory with the sticky attribute set. +.TP +.B STICKY_OTHER_WRITABLE \fIcolor-sequence\fR +Specifies the color used for an other-writable directory with the executable attribute set. +.IP +Synonym: +.BR OWT . +.TP +.B OTHER_WRITABLE \fIcolor-sequence\fR +Specifies the color used for an other-writable directory without the executable attribute set. +.IP +Synonym: +.BR OWR . +.TP +.B LEFTCODE \fIcolor-sequence\fR +Specifies the +.I "left code" +for non-ISO\ 6429 terminals (see below). +.IP +Synonym: +.BR LEFT . +.TP +.B RIGHTCODE \fIcolor-sequence\fR +Specifies the +.I "right code" +for non-ISO\ 6429 terminals (see below). +.IP +Synonym: +.BR RIGHT . +.TP +.B ENDCODE \fIcolor-sequence\fR +Specifies the +.I "end code" +for non-ISO\ 6429 terminals (see below). +.IP +Synonym: +.BR END . +.TP +\fB*\fIextension\fR \fIcolor-sequence\fR +Specifies the color used for any file that ends in \fIextension\fR. +.TP +\fB .\fIextension\fR \fIcolor-sequence\fR +Same as \fB*\fR.\fIextension\fR. +Specifies the color used for any file that +ends in .\fIextension\fR. +Note that the period is included in the +extension, which makes it impossible to specify an extension not +starting with a period, such as +.B ~ +for +.B emacs +backup files. +This form should be considered obsolete. +.SS ISO 6429 (ANSI) color sequences +Most color-capable ASCII terminals today use ISO 6429 (ANSI) color sequences, +and many common terminals without color capability, including +.B xterm +and the widely used and cloned DEC VT100, will recognize ISO 6429 color +codes and harmlessly eliminate them from the output or emulate them. +.B ls +uses ISO 6429 codes by default, assuming colorization is enabled. +.PP +ISO 6429 color sequences are composed of sequences of numbers +separated by semicolons. +The most common codes are: +.RS +.TS +l l. + 0 to restore default color + 1 for brighter colors + 4 for underlined text + 5 for flashing text +30 for black foreground +31 for red foreground +32 for green foreground +33 for yellow (or brown) foreground +34 for blue foreground +35 for purple foreground +36 for cyan foreground +37 for white (or gray) foreground +40 for black background +41 for red background +42 for green background +43 for yellow (or brown) background +44 for blue background +45 for purple background +46 for cyan background +47 for white (or gray) background +.TE +.RE +.PP +Not all commands will work on all systems or display devices. +.PP +.B ls +uses the following defaults: +.TS +lb l l. +NORMAL 0 Normal (nonfilename) text +FILE 0 Regular file +DIR 32 Directory +LINK 36 Symbolic link +ORPHAN undefined Orphaned symbolic link +MISSING undefined Missing file +FIFO 31 Named pipe (FIFO) +SOCK 33 Socket +BLK 44;37 Block device +CHR 44;37 Character device +EXEC 35 Executable file +.TE +.PP +A few terminal programs do not recognize the default +properly. +If all text gets colorized after you do a directory +listing, change the +.B NORMAL +and +.B FILE +codes to the numerical codes for your normal foreground and background +colors. +.SS Other terminal types (advanced configuration) +If you have a color-capable (or otherwise highlighting) terminal (or +printer!) which uses a different set of codes, you can still generate +a suitable setup. +To do so, you will have to use the +.BR LEFTCODE , +.BR RIGHTCODE , +and +.B ENDCODE +definitions. +.PP +When writing out a filename, +.B ls +generates the following output sequence: +.B LEFTCODE +.I typecode +.B RIGHTCODE +.I filename +.BR ENDCODE , +where the +.I typecode +is the color sequence that depends on the type or name of file. +If the +.B ENDCODE +is undefined, the sequence +.B "LEFTCODE NORMAL RIGHTCODE" +will be used instead. +The purpose of the left- and rightcodes is +merely to reduce the amount of typing necessary (and to hide ugly +escape codes away from the user). +If they are not appropriate for +your terminal, you can eliminate them by specifying the respective +keyword on a line by itself. +.PP +.B NOTE: +If the +.B ENDCODE +is defined in the global section of the setup file, it +.I cannot +be undefined in a terminal-specific section of the file. +This means any +.B NORMAL +definition will have no effect. +A different +.B ENDCODE +can, however, be specified, which would have the same effect. +.SS Escape sequences +To specify control- or blank characters in the color sequences or +filename extensions, either C-style \e-escaped notation or +.BR stty \-style +^-notation can be used. +The C-style notation +includes the following characters: +.RS +.TS +lb l. +\ea Bell (ASCII 7) +\eb Backspace (ASCII 8) +\ee Escape (ASCII 27) +\ef Form feed (ASCII 12) +\en Newline (ASCII 10) +\er Carriage Return (ASCII 13) +\et Tab (ASCII 9) +\ev Vertical Tab (ASCII 11) +\e? Delete (ASCII 127) +\e\fInnn Any character (octal notation) +\ex\fInnn Any character (hexadecimal notation) +\e_ Space +\e\e Backslash (\e) +\e^ Caret (^) +\e# Hash mark (#) +.TE +.RE +.PP +Note that escapes are necessary to enter a space, backslash, +caret, or any control character anywhere in the string, as well as a +hash mark as the first character. +.SH FILES +.TP +.I /etc/DIR_COLORS +System-wide configuration file. +.TP +.I ~/.dir_colors +Per-user configuration file. +.PP +This page describes the +.B dir_colors +file format as used in the fileutils-4.1 package; +other versions may differ slightly. +.SH NOTES +The default +.B LEFTCODE +and +.B RIGHTCODE +definitions, which are used by ISO 6429 terminals are: +.RS +.TS +lb l. +LEFTCODE \ee[ +RIGHTCODE m +.TE +.RE +.PP +The default +.B ENDCODE +is undefined. +.SH SEE ALSO +.BR dircolors (1), +.BR ls (1), +.BR stty (1), +.BR xterm (1) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/elf.5 b/man5/elf.5 new file mode 100644 index 0000000..8976c1c --- /dev/null +++ b/man5/elf.5 @@ -0,0 +1,2201 @@ +.\" $OpenBSD: elf.5,v 1.12 2003/10/27 20:23:58 jmc Exp $ +.\"Copyright (c) 1999 Jeroen Ruigrok van der Werven +.\"All rights reserved. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\"Redistribution and use in source and binary forms, with or without +.\"modification, are permitted provided that the following conditions +.\"are met: +.\"1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\"2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\"THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\"IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\"ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\"FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\"DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\"OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\"HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\"LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\"OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\"SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" $FreeBSD: src/share/man/man5/elf.5,v 1.21 2001/10/01 16:09:23 ru Exp $ +.\" +.\" Slightly adapted - aeb, 2004-01-01 +.\" 2005-07-15, Mike Frysinger , various fixes +.\" 2007-10-11, Mike Frysinger , various fixes +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH ELF 5 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +elf \- format of Executable and Linking Format (ELF) files +.SH SYNOPSIS +.nf +.\" .B #include +.B #include +.fi +.SH DESCRIPTION +The header file +.I +defines the format of ELF executable binary files. +Amongst these files are +normal executable files, relocatable object files, core files, and shared +objects. +.PP +An executable file using the ELF file format consists of an ELF header, +followed by a program header table or a section header table, or both. +The ELF header is always at offset zero of the file. +The program header +table and the section header table's offset in the file are defined in the +ELF header. +The two tables describe the rest of the particularities of +the file. +.PP +.\" Applications which wish to process ELF binary files for their native +.\" architecture only should include +.\" .I +.\" in their source code. +.\" These applications should need to refer to +.\" all the types and structures by their generic names +.\" "Elf_xxx" +.\" and to the macros by +.\" ELF_xxx". +.\" Applications written this way can be compiled on any architecture, +.\" regardless of whether the host is 32-bit or 64-bit. +.\" .PP +.\" Should an application need to process ELF files of an unknown +.\" architecture, then the application needs to explicitly use either +.\" "Elf32_xxx" +.\" or +.\" "Elf64_xxx" +.\" type and structure names. +.\" Likewise, the macros need to be identified by +.\" "ELF32_xxx" +.\" or +.\" "ELF64_xxx". +.\" .PP +This header file describes the above mentioned headers as C structures +and also includes structures for dynamic sections, relocation sections and +symbol tables. +.\" +.SS Basic types +The following types are used for N-bit architectures (N=32,64, +.I ElfN +stands for +.I Elf32 +or +.IR Elf64 , +.I uintN_t +stands for +.I uint32_t +or +.IR uint64_t ): +.PP +.in +4n +.EX +ElfN_Addr Unsigned program address, uintN_t +ElfN_Off Unsigned file offset, uintN_t +ElfN_Section Unsigned section index, uint16_t +ElfN_Versym Unsigned version symbol information, uint16_t +Elf_Byte unsigned char +ElfN_Half uint16_t +ElfN_Sword int32_t +ElfN_Word uint32_t +ElfN_Sxword int64_t +ElfN_Xword uint64_t +.\" Elf32_Size Unsigned object size +.EE +.in +.PP +(Note: the *BSD terminology is a bit different. +There, +.I Elf64_Half +is +twice as large as +.IR Elf32_Half , +and +.I Elf64Quarter +is used for +.IR uint16_t . +In order to avoid confusion these types are replaced by explicit ones +in the below.) +.PP +All data structures that the file format defines follow the +"natural" +size and alignment guidelines for the relevant class. +If necessary, +data structures contain explicit padding to ensure 4-byte alignment +for 4-byte objects, to force structure sizes to a multiple of 4, and so on. +.\" +.SS ELF header (Ehdr) +The ELF header is described by the type +.I Elf32_Ehdr +or +.IR Elf64_Ehdr : +.PP +.in +4n +.EX +#define EI_NIDENT 16 + +typedef struct { + unsigned char e_ident[EI_NIDENT]; + uint16_t e_type; + uint16_t e_machine; + uint32_t e_version; + ElfN_Addr e_entry; + ElfN_Off e_phoff; + ElfN_Off e_shoff; + uint32_t e_flags; + uint16_t e_ehsize; + uint16_t e_phentsize; + uint16_t e_phnum; + uint16_t e_shentsize; + uint16_t e_shnum; + uint16_t e_shstrndx; +} ElfN_Ehdr; +.EE +.in +.PP +The fields have the following meanings: +.\" +.nr l1_indent 10 +.\" +.TP \n[l1_indent] +.IR e_ident +This array of bytes specifies how to interpret the file, +independent of the processor or the file's remaining contents. +Within this array everything is named by macros, which start with +the prefix +.BR EI_ +and may contain values which start with the prefix +.BR ELF . +The following macros are defined: +.RS +.TP 9 +.BR EI_MAG0 +The first byte of the magic number. +It must be filled with +.BR ELFMAG0 . +(0: 0x7f) +.TP +.BR EI_MAG1 +The second byte of the magic number. +It must be filled with +.BR ELFMAG1 . +(1: \(aqE\(aq) +.TP +.BR EI_MAG2 +The third byte of the magic number. +It must be filled with +.BR ELFMAG2 . +(2: \(aqL\(aq) +.TP +.BR EI_MAG3 +The fourth byte of the magic number. +It must be filled with +.BR ELFMAG3 . +(3: \(aqF\(aq) +.TP +.BR EI_CLASS +The fifth byte identifies the architecture for this binary: +.RS +.TP 14 +.PD 0 +.BR ELFCLASSNONE +This class is invalid. +.TP +.BR ELFCLASS32 +This defines the 32-bit architecture. +It supports machines with files +and virtual address spaces up to 4 Gigabytes. +.TP +.BR ELFCLASS64 +This defines the 64-bit architecture. +.PD +.RE +.TP +.BR EI_DATA +The sixth byte specifies the data encoding of the processor-specific +data in the file. +Currently, these encodings are supported: +.RS 9 +.TP 14 +.PD 0 +.BR ELFDATANONE +Unknown data format. +.TP +.BR ELFDATA2LSB +Two's complement, little-endian. +.TP +.BR ELFDATA2MSB +Two's complement, big-endian. +.PD +.RE +.TP +.BR EI_VERSION +The seventh byte is the version number of the ELF specification: +.IP +.PD 0 +.RS +.TP 14 +.BR EV_NONE +Invalid version. +.TP +.BR EV_CURRENT +Current version. +.PD +.RE +.\".El +.TP +.BR EI_OSABI +The eighth byte identifies the operating system +and ABI to which the object is targeted. +Some fields in other ELF structures have flags +and values that have platform-specific meanings; +the interpretation of those fields is determined by the value of this byte. +For example: +.RS +.TP 21 +.PD 0 +.BR ELFOSABI_NONE +Same as ELFOSABI_SYSV +.\" 0 +.TP +.BR ELFOSABI_SYSV +UNIX System V ABI +.\" 0 +.\" synonym: ELFOSABI_NONE +.TP +.BR ELFOSABI_HPUX +HP-UX ABI +.\" 1 +.TP +.BR ELFOSABI_NETBSD +NetBSD ABI +.\" 2 +.TP +.BR ELFOSABI_LINUX +Linux ABI +.\" 3 +.\" .TP +.\" .BR ELFOSABI_HURD +.\" Hurd ABI +.\" 4 +.\" .TP +.\" .BR ELFOSABI_86OPEN +.\" 86Open Common IA32 ABI +.\" 5 +.TP +.BR ELFOSABI_SOLARIS +Solaris ABI +.\" 6 +.\" .TP +.\" .BR ELFOSABI_MONTEREY +.\" Monterey project ABI +.\" Now replaced by +.\" ELFOSABI_AIX +.\" 7 +.TP +.BR ELFOSABI_IRIX +IRIX ABI +.\" 8 +.TP +.BR ELFOSABI_FREEBSD +FreeBSD ABI +.\" 9 +.TP +.BR ELFOSABI_TRU64 +TRU64 UNIX ABI +.\" 10 +.\" ELFOSABI_MODESTO +.\" 11 +.\" ELFOSABI_OPENBSD +.\" 12 +.TP +.BR ELFOSABI_ARM +ARM architecture ABI +.\" 97 +.TP +.BR ELFOSABI_STANDALONE +Stand-alone (embedded) ABI +.\" 255 +.PD +.RE +.TP +.BR EI_ABIVERSION +The ninth byte identifies the version of the ABI +to which the object is targeted. +This field is used to distinguish among incompatible versions of an ABI. +The interpretation of this version number +is dependent on the ABI identified by the +.B EI_OSABI +field. +Applications conforming to this specification use the value 0. +.TP +.BR EI_PAD +Start of padding. +These bytes are reserved and set to zero. +Programs +which read them should ignore them. +The value for +.B EI_PAD +will change in +the future if currently unused bytes are given meanings. +.\" As reported by Yuri Kozlov and confirmed by Mike Frysinger, EI_BRAND is +.\" not in GABI (http://www.sco.com/developers/gabi/latest/ch4.eheader.html) +.\" It looks to be a BSDism +.\" .TP +.\" .BR EI_BRAND +.\" Start of architecture identification. +.TP +.BR EI_NIDENT +The size of the +.I e_ident +array. +.RE +.TP +.IR e_type +This member of the structure identifies the object file type: +.RS +.TP 16 +.PD 0 +.BR ET_NONE +An unknown type. +.TP +.BR ET_REL +A relocatable file. +.TP +.BR ET_EXEC +An executable file. +.TP +.BR ET_DYN +A shared object. +.TP +.BR ET_CORE +A core file. +.PD +.RE +.TP +.IR e_machine +This member specifies the required architecture for an individual file. +For example: +.RS \n[l1_indent] +.TP 16 +.PD 0 +.BR EM_NONE +An unknown machine +.\" 0 +.TP +.BR EM_M32 +AT&T WE 32100 +.\" 1 +.TP +.BR EM_SPARC +Sun Microsystems SPARC +.\" 2 +.TP +.BR EM_386 +Intel 80386 +.\" 3 +.TP +.BR EM_68K +Motorola 68000 +.\" 4 +.TP +.BR EM_88K +Motorola 88000 +.\" 5 +.\" .TP +.\" .BR EM_486 +.\" Intel 80486 +.\" 6 +.TP +.BR EM_860 +Intel 80860 +.\" 7 +.TP +.BR EM_MIPS +MIPS RS3000 (big-endian only) +.\" 8 +.\" EM_S370 +.\" 9 +.\" .TP +.\" .BR EM_MIPS_RS4_BE +.\" MIPS RS4000 (big-endian only). Deprecated +.\" 10 +.\" EM_MIPS_RS3_LE (MIPS R3000 little-endian) +.\" 10 +.TP +.BR EM_PARISC +HP/PA +.\" 15 +.TP +.BR EM_SPARC32PLUS +SPARC with enhanced instruction set +.\" 18 +.TP +.BR EM_PPC +PowerPC +.\" 20 +.TP +.BR EM_PPC64 +PowerPC 64-bit +.\" 21 +.TP +.BR EM_S390 +IBM S/390 +.\" 22 +.TP +.BR EM_ARM +Advanced RISC Machines +.\" 40 +.TP +.BR EM_SH +Renesas SuperH +.\" 42 +.TP +.BR EM_SPARCV9 +SPARC v9 64-bit +.\" 43 +.TP +.BR EM_IA_64 +Intel Itanium +.\" 50 +.TP +.BR EM_X86_64 +AMD x86-64 +.\" 62 +.TP +.BR EM_VAX +DEC Vax +.\" 75 +.\" EM_CRIS +.\" 76 +.\" .TP +.\" .BR EM_ALPHA +.\" Compaq [DEC] Alpha +.\" .TP +.\" .BR EM_ALPHA_EXP +.\" Compaq [DEC] Alpha with enhanced instruction set +.PD +.RE +.TP +.IR e_version +This member identifies the file version: +.RS +.TP 16 +.PD 0 +.BR EV_NONE +Invalid version +.TP +.BR EV_CURRENT +Current version +.PD +.RE +.TP +.IR e_entry +This member gives the virtual address to which the system first transfers +control, thus starting the process. +If the file has no associated entry +point, this member holds zero. +.TP +.IR e_phoff +This member holds the program header table's file offset in bytes. +If +the file has no program header table, this member holds zero. +.TP +.IR e_shoff +This member holds the section header table's file offset in bytes. +If the +file has no section header table, this member holds zero. +.TP +.IR e_flags +This member holds processor-specific flags associated with the file. +Flag names take the form EF_`machine_flag'. +Currently, no flags have been defined. +.TP +.IR e_ehsize +This member holds the ELF header's size in bytes. +.TP +.IR e_phentsize +This member holds the size in bytes of one entry in the file's +program header table; all entries are the same size. +.TP +.IR e_phnum +This member holds the number of entries in the program header +table. +Thus the product of +.IR e_phentsize +and +.IR e_phnum +gives the table's size +in bytes. +If a file has no program header, +.IR e_phnum +holds the value zero. +.IP +If the number of entries in the program header table is +larger than or equal to +.\" This is a Linux extension, added in Linux 2.6.34. +.BR PN_XNUM +(0xffff), this member holds +.BR PN_XNUM +(0xffff) and the real number of entries in the program header table is held +in the +.IR sh_info +member of the initial entry in section header table. +Otherwise, the +.IR sh_info +member of the initial entry contains the value zero. +.RS \n[l1_indent] +.TP 9 +.BR PN_XNUM +This is defined as 0xffff, the largest number +.IR e_phnum +can have, specifying where the actual number of program headers is assigned. +.PD +.RE +.IP +.TP +.IR e_shentsize +This member holds a sections header's size in bytes. +A section header is one +entry in the section header table; all entries are the same size. +.TP +.IR e_shnum +This member holds the number of entries in the section header table. +Thus +the product of +.IR e_shentsize +and +.IR e_shnum +gives the section header table's size in bytes. +If a file has no section +header table, +.IR e_shnum +holds the value of zero. +.IP +If the number of entries in the section header table is +larger than or equal to +.BR SHN_LORESERVE +(0xff00), +.IR e_shnum +holds the value zero and the real number of entries in the section header +table is held in the +.IR sh_size +member of the initial entry in section header table. +Otherwise, the +.IR sh_size +member of the initial entry in the section header table holds +the value zero. +.TP +.IR e_shstrndx +This member holds the section header table index of the entry associated +with the section name string table. +If the file has no section name string +table, this member holds the value +.BR SHN_UNDEF . +.IP +If the index of section name string table section is +larger than or equal to +.BR SHN_LORESERVE +(0xff00), this member holds +.BR SHN_XINDEX +(0xffff) and the real index of the section name string table section +is held in the +.IR sh_link +member of the initial entry in section header table. +Otherwise, the +.IR sh_link +member of the initial entry in section header table contains the value zero. +.\" +.SS Program header (Phdr) +An executable or shared object file's program header table is an array of +structures, each describing a segment or other information the system needs +to prepare the program for execution. +An object file +.IR segment +contains one or more +.IR sections . +Program headers are meaningful only for executable and shared object files. +A file specifies its own program header size with the ELF header's +.IR e_phentsize +and +.IR e_phnum +members. +The ELF program header is described by the type +.I Elf32_Phdr +or +.I Elf64_Phdr +depending on the architecture: +.PP +.in +4n +.EX +typedef struct { + uint32_t p_type; + Elf32_Off p_offset; + Elf32_Addr p_vaddr; + Elf32_Addr p_paddr; + uint32_t p_filesz; + uint32_t p_memsz; + uint32_t p_flags; + uint32_t p_align; +} Elf32_Phdr; +.EE +.in +.PP +.in +4n +.EX +typedef struct { + uint32_t p_type; + uint32_t p_flags; + Elf64_Off p_offset; + Elf64_Addr p_vaddr; + Elf64_Addr p_paddr; + uint64_t p_filesz; + uint64_t p_memsz; + uint64_t p_align; +} Elf64_Phdr; +.EE +.in +.PP +The main difference between the 32-bit and the 64-bit program header lies +in the location of the +.IR p_flags +member in the total struct. +.TP 10 +.IR p_type +This member of the structure indicates what kind of segment this array +element describes or how to interpret the array element's information. +.RS 10 +.TP 12 +.BR PT_NULL +The array element is unused and the other members' values are undefined. +This lets the program header have ignored entries. +.TP +.BR PT_LOAD +The array element specifies a loadable segment, described by +.IR p_filesz +and +.IR p_memsz . +The bytes from the file are mapped to the beginning of the memory +segment. +If the segment's memory size +.IR p_memsz +is larger than the file size +.IR p_filesz , +the +"extra" +bytes are defined to hold the value 0 and to follow the segment's +initialized area. +The file size may not be larger than the memory size. +Loadable segment entries in the program header table appear in ascending +order, sorted on the +.IR p_vaddr +member. +.TP +.BR PT_DYNAMIC +The array element specifies dynamic linking information. +.TP +.BR PT_INTERP +The array element specifies the location and size of a null-terminated +pathname to invoke as an interpreter. +This segment type is meaningful +only for executable files (though it may occur for shared objects). +However it may not occur more than once in a file. +If it is present, it must precede any loadable segment entry. +.TP +.BR PT_NOTE +The array element specifies the location of notes (ElfN_Nhdr). +.TP +.BR PT_SHLIB +This segment type is reserved but has unspecified semantics. +Programs that +contain an array element of this type do not conform to the ABI. +.TP +.BR PT_PHDR +The array element, if present, +specifies the location and size of the program header table itself, +both in the file and in the memory image of the program. +This segment type may not occur more than once in a file. +Moreover, it may +occur only if the program header table is part of the memory image of the +program. +If it is present, it must precede any loadable segment entry. +.TP +.BR PT_LOPROC ", " PT_HIPROC +Values in the inclusive range +.RB [ PT_LOPROC ", " PT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.BR PT_GNU_STACK +GNU extension which is used by the Linux kernel to control the state of the +stack via the flags set in the +.IR p_flags +member. +.RE +.TP +.IR p_offset +This member holds the offset from the beginning of the file at which +the first byte of the segment resides. +.TP +.IR p_vaddr +This member holds the virtual address at which the first byte of the +segment resides in memory. +.TP +.IR p_paddr +On systems for which physical addressing is relevant, this member is +reserved for the segment's physical address. +Under +BSD +this member is +not used and must be zero. +.TP +.IR p_filesz +This member holds the number of bytes in the file image of the segment. +It may be zero. +.TP +.IR p_memsz +This member holds the number of bytes in the memory image of the segment. +It may be zero. +.TP +.IR p_flags +This member holds a bit mask of flags relevant to the segment: +.RS \n[l1_indent] +.TP +.PD 0 +.BR PF_X +An executable segment. +.TP +.BR PF_W +A writable segment. +.TP +.BR PF_R +A readable segment. +.PD +.RE +.IP +A text segment commonly has the flags +.BR PF_X +and +.BR PF_R . +A data segment commonly has +.BR PF_X , +.BR PF_W , +and +.BR PF_R . +.TP +.IR p_align +This member holds the value to which the segments are aligned in memory +and in the file. +Loadable process segments must have congruent values for +.IR p_vaddr +and +.IR p_offset , +modulo the page size. +Values of zero and one mean no alignment is required. +Otherwise, +.IR p_align +should be a positive, integral power of two, and +.IR p_vaddr +should equal +.IR p_offset , +modulo +.IR p_align . +.\" +.SS Section header (Shdr) +A file's section header table lets one locate all the file's sections. +The +section header table is an array of +.I Elf32_Shdr +or +.I Elf64_Shdr +structures. +The +ELF header's +.IR e_shoff +member gives the byte offset from the beginning of the file to the section +header table. +.IR e_shnum +holds the number of entries the section header table contains. +.IR e_shentsize +holds the size in bytes of each entry. +.PP +A section header table index is a subscript into this array. +Some section +header table indices are reserved: +the initial entry and the indices between +.B SHN_LORESERVE +and +.BR SHN_HIRESERVE . +The initial entry is used in ELF extensions for +.IR e_phnum , +.IR e_shnum +and +.IR e_strndx ; +in other cases, each field in the initial entry is set to zero. +An object file does not have sections for +these special indices: +.TP +.BR SHN_UNDEF +This value marks an undefined, missing, irrelevant, +or otherwise meaningless section reference. +.TP +.BR SHN_LORESERVE +This value specifies the lower bound of the range of reserved indices. +.TP +.BR SHN_LOPROC ", " SHN_HIPROC +Values greater in the inclusive range +.RB [ SHN_LOPROC ", " SHN_HIPROC ] +are reserved for processor-specific semantics. +.TP +.BR SHN_ABS +This value specifies the absolute value for the corresponding reference. +For +example, a symbol defined relative to section number +.BR SHN_ABS +has an absolute value and is not affected by relocation. +.TP +.BR SHN_COMMON +Symbols defined relative to this section are common symbols, +such as FORTRAN COMMON or unallocated C external variables. +.TP +.BR SHN_HIRESERVE +This value specifies the upper bound of the range of reserved indices. +The +system reserves indices between +.BR SHN_LORESERVE +and +.BR SHN_HIRESERVE , +inclusive. +The section header table does not contain entries for the +reserved indices. +.PP +The section header has the following structure: +.PP +.in +4n +.EX +typedef struct { + uint32_t sh_name; + uint32_t sh_type; + uint32_t sh_flags; + Elf32_Addr sh_addr; + Elf32_Off sh_offset; + uint32_t sh_size; + uint32_t sh_link; + uint32_t sh_info; + uint32_t sh_addralign; + uint32_t sh_entsize; +} Elf32_Shdr; +.EE +.in +.PP +.in +4n +.EX +typedef struct { + uint32_t sh_name; + uint32_t sh_type; + uint64_t sh_flags; + Elf64_Addr sh_addr; + Elf64_Off sh_offset; + uint64_t sh_size; + uint32_t sh_link; + uint32_t sh_info; + uint64_t sh_addralign; + uint64_t sh_entsize; +} Elf64_Shdr; +.EE +.in +.PP +No real differences exist between the 32-bit and 64-bit section headers. +.TP \n[l1_indent] +.IR sh_name +This member specifies the name of the section. +Its value is an index +into the section header string table section, giving the location of +a null-terminated string. +.TP +.IR sh_type +This member categorizes the section's contents and semantics. +.RS \n[l1_indent] +.TP 15 +.BR SHT_NULL +This value marks the section header as inactive. +It does not +have an associated section. +Other members of the section header +have undefined values. +.TP +.BR SHT_PROGBITS +This section holds information defined by the program, whose +format and meaning are determined solely by the program. +.TP +.BR SHT_SYMTAB +This section holds a symbol table. +Typically, +.BR SHT_SYMTAB +provides symbols for link editing, though it may also be used +for dynamic linking. +As a complete symbol table, it may contain +many symbols unnecessary for dynamic linking. +An object file can +also contain a +.BR SHT_DYNSYM +section. +.TP +.BR SHT_STRTAB +This section holds a string table. +An object file may have multiple +string table sections. +.TP +.BR SHT_RELA +This section holds relocation entries with explicit addends, such +as type +.IR Elf32_Rela +for the 32-bit class of object files. +An object may have multiple +relocation sections. +.TP +.BR SHT_HASH +This section holds a symbol hash table. +An object participating in +dynamic linking must contain a symbol hash table. +An object file may +have only one hash table. +.TP +.BR SHT_DYNAMIC +This section holds information for dynamic linking. +An object file may +have only one dynamic section. +.TP +.BR SHT_NOTE +This section holds notes (ElfN_Nhdr). +.TP +.BR SHT_NOBITS +A section of this type occupies no space in the file but otherwise +resembles +.BR SHT_PROGBITS . +Although this section contains no bytes, the +.IR sh_offset +member contains the conceptual file offset. +.TP +.BR SHT_REL +This section holds relocation offsets without explicit addends, such +as type +.IR Elf32_Rel +for the 32-bit class of object files. +An object file may have multiple +relocation sections. +.TP +.BR SHT_SHLIB +This section is reserved but has unspecified semantics. +.TP +.BR SHT_DYNSYM +This section holds a minimal set of dynamic linking symbols. +An +object file can also contain a +.BR SHT_SYMTAB +section. +.TP +.BR SHT_LOPROC ", " SHT_HIPROC +Values in the inclusive range +.RB [ SHT_LOPROC ", " SHT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.BR SHT_LOUSER +This value specifies the lower bound of the range of indices reserved for +application programs. +.TP +.BR SHT_HIUSER +This value specifies the upper bound of the range of indices reserved for +application programs. +Section types between +.BR SHT_LOUSER +and +.BR SHT_HIUSER +may be used by the application, without conflicting with current or future +system-defined section types. +.RE +.TP +.IR sh_flags +Sections support one-bit flags that describe miscellaneous attributes. +If a flag bit is set in +.IR sh_flags , +the attribute is +"on" +for the section. +Otherwise, the attribute is +"off" +or does not apply. +Undefined attributes are set to zero. +.RS \n[l1_indent] +.TP 15 +.BR SHF_WRITE +This section contains data that should be writable during process +execution. +.TP +.BR SHF_ALLOC +This section occupies memory during process execution. +Some control +sections do not reside in the memory image of an object file. +This +attribute is off for those sections. +.TP +.BR SHF_EXECINSTR +This section contains executable machine instructions. +.TP +.BR SHF_MASKPROC +All bits included in this mask are reserved for processor-specific +semantics. +.RE +.TP +.IR sh_addr +If this section appears in the memory image of a process, this member +holds the address at which the section's first byte should reside. +Otherwise, the member contains zero. +.TP +.IR sh_offset +This member's value holds the byte offset from the beginning of the file +to the first byte in the section. +One section type, +.BR SHT_NOBITS , +occupies no space in the file, and its +.IR sh_offset +member locates the conceptual placement in the file. +.TP +.IR sh_size +This member holds the section's size in bytes. +Unless the section type +is +.BR SHT_NOBITS , +the section occupies +.IR sh_size +bytes in the file. +A section of type +.BR SHT_NOBITS +may have a nonzero size, but it occupies no space in the file. +.TP +.IR sh_link +This member holds a section header table index link, whose interpretation +depends on the section type. +.TP +.IR sh_info +This member holds extra information, whose interpretation depends on the +section type. +.TP +.IR sh_addralign +Some sections have address alignment constraints. +If a section holds a +doubleword, the system must ensure doubleword alignment for the entire +section. +That is, the value of +.IR sh_addr +must be congruent to zero, modulo the value of +.IR sh_addralign . +Only zero and positive integral powers of two are allowed. +The value 0 or 1 means that the section has no alignment constraints. +.TP +.IR sh_entsize +Some sections hold a table of fixed-sized entries, such as a symbol table. +For such a section, this member gives the size in bytes for each entry. +This member contains zero if the section does not hold a table of +fixed-size entries. +.PP +Various sections hold program and control information: +.TP \n[l1_indent] +.IR .bss +This section holds uninitialized data that contributes to the program's +memory image. +By definition, the system initializes the data with zeros +when the program begins to run. +This section is of type +.BR SHT_NOBITS . +The attribute types are +.BR SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.IR .comment +This section holds version control information. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.IR .ctors +This section holds initialized pointers to the C++ constructor functions. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.BR SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.IR .data +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.BR SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.IR .data1 +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.BR SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.IR .debug +This section holds information for symbolic debugging. +The contents +are unspecified. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.IR .dtors +This section holds initialized pointers to the C++ destructor functions. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.BR SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.IR .dynamic +This section holds dynamic linking information. +The section's attributes +will include the +.BR SHF_ALLOC +bit. +Whether the +.BR SHF_WRITE +bit is set is processor-specific. +This section is of type +.BR SHT_DYNAMIC . +See the attributes above. +.TP +.IR .dynstr +This section holds strings needed for dynamic linking, most commonly +the strings that represent the names associated with symbol table entries. +This section is of type +.BR SHT_STRTAB . +The attribute type used is +.BR SHF_ALLOC . +.TP +.IR .dynsym +This section holds the dynamic linking symbol table. +This section is of type +.BR SHT_DYNSYM . +The attribute used is +.BR SHF_ALLOC . +.TP +.IR .fini +This section holds executable instructions that contribute to the process +termination code. +When a program exits normally the system arranges to +execute the code in this section. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.BR SHF_ALLOC +and +.BR SHF_EXECINSTR . +.TP +.IR .gnu.version +This section holds the version symbol table, an array of +.I ElfN_Half +elements. +This section is of type +.BR SHT_GNU_versym . +The attribute type used is +.BR SHF_ALLOC . +.TP +.IR .gnu.version_d +This section holds the version symbol definitions, a table of +.I ElfN_Verdef +structures. +This section is of type +.BR SHT_GNU_verdef . +The attribute type used is +.BR SHF_ALLOC . +.TP +.IR .gnu.version_r +This section holds the version symbol needed elements, a table of +.I ElfN_Verneed +structures. +This section is of +type +.BR SHT_GNU_versym . +The attribute type used is +.BR SHF_ALLOC . +.TP +.IR .got +This section holds the global offset table. +This section is of type +.BR SHT_PROGBITS . +The attributes are processor-specific. +.TP +.IR .hash +This section holds a symbol hash table. +This section is of type +.BR SHT_HASH . +The attribute used is +.BR SHF_ALLOC . +.TP +.IR .init +This section holds executable instructions that contribute to the process +initialization code. +When a program starts to run the system arranges to execute +the code in this section before calling the main program entry point. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.BR SHF_ALLOC +and +.BR SHF_EXECINSTR . +.TP +.IR .interp +This section holds the pathname of a program interpreter. +If the file has +a loadable segment that includes the section, the section's attributes will +include the +.BR SHF_ALLOC +bit. +Otherwise, that bit will be off. +This section is of type +.BR SHT_PROGBITS . +.TP +.IR .line +This section holds line number information for symbolic debugging, +which describes the correspondence between the program source and +the machine code. +The contents are unspecified. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.IR .note +This section holds various notes. +This section is of type +.BR SHT_NOTE . +No attribute types are used. +.TP +.IR .note.ABI-tag +This section is used to declare the expected runtime ABI of the ELF image. +It may include the operating system name and its runtime versions. +This section is of type +.BR SHT_NOTE . +The only attribute used is +.BR SHF_ALLOC . +.TP +.IR .note.gnu.build-id +This section is used to hold an ID that uniquely identifies +the contents of the ELF image. +Different files with the same build ID should contain the same executable +content. +See the +.BR \-\-build\-id +option to the GNU linker (\fBld\fR (1)) for more details. +This section is of type +.BR SHT_NOTE . +The only attribute used is +.BR SHF_ALLOC . +.TP +.IR .note.GNU-stack +This section is used in Linux object files for declaring stack attributes. +This section is of type +.BR SHT_PROGBITS . +The only attribute used is +.BR SHF_EXECINSTR . +This indicates to the GNU linker that the object file requires an +executable stack. +.TP +.IR .note.openbsd.ident +OpenBSD native executables usually contain this section +to identify themselves so the kernel can bypass any compatibility +ELF binary emulation tests when loading the file. +.TP +.IR .plt +This section holds the procedure linkage table. +This section is of type +.BR SHT_PROGBITS . +The attributes are processor-specific. +.TP +.IR .relNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.BR SHF_ALLOC +bit. +Otherwise, the bit will be off. +By convention, +"NAME" +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.BR .text +normally would have the name +.BR .rel.text . +This section is of type +.BR SHT_REL . +.TP +.IR .relaNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.BR SHF_ALLOC +bit. +Otherwise, the bit will be off. +By convention, +"NAME" +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.BR .text +normally would have the name +.BR .rela.text . +This section is of type +.BR SHT_RELA . +.TP +.IR .rodata +This section holds read-only data that typically contributes to a +nonwritable segment in the process image. +This section is of type +.BR SHT_PROGBITS . +The attribute used is +.BR SHF_ALLOC . +.TP +.IR .rodata1 +This section holds read-only data that typically contributes to a +nonwritable segment in the process image. +This section is of type +.BR SHT_PROGBITS . +The attribute used is +.BR SHF_ALLOC . +.TP +.IR .shstrtab +This section holds section names. +This section is of type +.BR SHT_STRTAB . +No attribute types are used. +.TP +.IR .strtab +This section holds strings, most commonly the strings that represent the +names associated with symbol table entries. +If the file has a loadable +segment that includes the symbol string table, the section's attributes +will include the +.BR SHF_ALLOC +bit. +Otherwise, the bit will be off. +This section is of type +.BR SHT_STRTAB . +.TP +.IR .symtab +This section holds a symbol table. +If the file has a loadable segment +that includes the symbol table, the section's attributes will include +the +.BR SHF_ALLOC +bit. +Otherwise, the bit will be off. +This section is of type +.BR SHT_SYMTAB . +.TP +.IR .text +This section holds the +"text", +or executable instructions, of a program. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.BR SHF_ALLOC +and +.BR SHF_EXECINSTR . +.\" +.SS String and symbol tables +String table sections hold null-terminated character sequences, commonly +called strings. +The object file uses these strings to represent symbol +and section names. +One references a string as an index into the string +table section. +The first byte, which is index zero, is defined to hold +a null byte (\(aq\\0\(aq). +Similarly, a string table's last byte is defined to +hold a null byte, ensuring null termination for all strings. +.PP +An object file's symbol table holds information needed to locate and +relocate a program's symbolic definitions and references. +A symbol table +index is a subscript into this array. +.PP +.in +4n +.EX +typedef struct { + uint32_t st_name; + Elf32_Addr st_value; + uint32_t st_size; + unsigned char st_info; + unsigned char st_other; + uint16_t st_shndx; +} Elf32_Sym; +.EE +.in +.PP +.in +4n +.EX +typedef struct { + uint32_t st_name; + unsigned char st_info; + unsigned char st_other; + uint16_t st_shndx; + Elf64_Addr st_value; + uint64_t st_size; +} Elf64_Sym; +.EE +.in +.PP +The 32-bit and 64-bit versions have the same members, just in a different +order. +.TP \n[l1_indent] +.IR st_name +This member holds an index into the object file's symbol string table, +which holds character representations of the symbol names. +If the value +is nonzero, it represents a string table index that gives the symbol +name. +Otherwise, the symbol has no name. +.TP +.IR st_value +This member gives the value of the associated symbol. +.TP +.IR st_size +Many symbols have associated sizes. +This member holds zero if the symbol +has no size or an unknown size. +.TP +.IR st_info +This member specifies the symbol's type and binding attributes: +.RS \n[l1_indent] +.TP 12 +.BR STT_NOTYPE +The symbol's type is not defined. +.TP +.BR STT_OBJECT +The symbol is associated with a data object. +.TP +.BR STT_FUNC +The symbol is associated with a function or other executable code. +.TP +.BR STT_SECTION +The symbol is associated with a section. +Symbol table entries of +this type exist primarily for relocation and normally have +.BR STB_LOCAL +bindings. +.TP +.BR STT_FILE +By convention, the symbol's name gives the name of the source file +associated with the object file. +A file symbol has +.BR STB_LOCAL +bindings, its section index is +.BR SHN_ABS , +and it precedes the other +.BR STB_LOCAL +symbols of the file, if it is present. +.TP +.BR STT_LOPROC ", " STT_HIPROC +Values in the inclusive range +.RB [ STT_LOPROC ", " STT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.BR STB_LOCAL +Local symbols are not visible outside the object file containing their +definition. +Local symbols of the same name may exist in multiple files +without interfering with each other. +.TP +.BR STB_GLOBAL +Global symbols are visible to all object files being combined. +One file's +definition of a global symbol will satisfy another file's undefined +reference to the same symbol. +.TP +.BR STB_WEAK +Weak symbols resemble global symbols, but their definitions have lower +precedence. +.TP +.BR STB_LOPROC ", " STB_HIPROC +Values in the inclusive range +.RB [ STB_LOPROC ", " STB_HIPROC ] +are reserved for processor-specific semantics. +.RE +.IP +There are macros for packing and unpacking the binding and type fields: +.RS \n[l1_indent] +.TP +.BR ELF32_ST_BIND( \fIinfo\fP ) ", " ELF64_ST_BIND( \fIinfo\fP ) +Extract a binding from an +.I st_info +value. +.TP +.BR ELF32_ST_TYPE( \fIinfo ) ", " ELF64_ST_TYPE( \fIinfo\fP ) +Extract a type from an +.I st_info +value. +.TP +.BR ELF32_ST_INFO( \fIbind\fP ", " \fItype\fP ) ", " \ +ELF64_ST_INFO( \fIbind\fP ", " \fItype\fP ) +Convert a binding and a type into an +.I st_info +value. +.RE +.TP +.IR st_other +This member defines the symbol visibility. +.RS \n[l1_indent] +.TP 16 +.PD 0 +.BR STV_DEFAULT +Default symbol visibility rules. +Global and weak symbols are available to other modules; +references in the local module can be interposed +by definitions in other modules. +.TP +.BR STV_INTERNAL +Processor-specific hidden class. +.TP +.BR STV_HIDDEN +Symbol is unavailable to other modules; +references in the local module always resolve to the local symbol +(i.e., the symbol can't be interposed by definitions in other modules). +.TP +.BR STV_PROTECTED +Symbol is available to other modules, +but references in the local module always resolve to the local symbol. +.PD +.PP +There are macros for extracting the visibility type: +.PP +.BR ELF32_ST_VISIBILITY (other) +or +.BR ELF64_ST_VISIBILITY (other) +.RE +.TP +.IR st_shndx +Every symbol table entry is +"defined" +in relation to some section. +This member holds the relevant section +header table index. +.\" +.SS Relocation entries (Rel & Rela) +Relocation is the process of connecting symbolic references with +symbolic definitions. +Relocatable files must have information that +describes how to modify their section contents, thus allowing executable +and shared object files to hold the right information for a process's +program image. +Relocation entries are these data. +.PP +Relocation structures that do not need an addend: +.PP +.in +4n +.EX +typedef struct { + Elf32_Addr r_offset; + uint32_t r_info; +} Elf32_Rel; +.EE +.in +.PP +.in +4n +.EX +typedef struct { + Elf64_Addr r_offset; + uint64_t r_info; +} Elf64_Rel; +.EE +.in +.PP +Relocation structures that need an addend: +.PP +.in +4n +.EX +typedef struct { + Elf32_Addr r_offset; + uint32_t r_info; + int32_t r_addend; +} Elf32_Rela; +.EE +.in +.PP +.in +4n +.EX +typedef struct { + Elf64_Addr r_offset; + uint64_t r_info; + int64_t r_addend; +} Elf64_Rela; +.EE +.in +.TP \n[l1_indent] +.IR r_offset +This member gives the location at which to apply the relocation action. +For a relocatable file, the value is the byte offset from the beginning +of the section to the storage unit affected by the relocation. +For an +executable file or shared object, the value is the virtual address of +the storage unit affected by the relocation. +.TP +.IR r_info +This member gives both the symbol table index with respect to which the +relocation must be made and the type of relocation to apply. +Relocation +types are processor-specific. +When the text refers to a relocation +entry's relocation type or symbol table index, it means the result of +applying +.BR ELF[32|64]_R_TYPE +or +.BR ELF[32|64]_R_SYM , +respectively, to the entry's +.IR r_info +member. +.TP +.IR r_addend +This member specifies a constant addend used to compute the value to be +stored into the relocatable field. +.\" +.SS Dynamic tags (Dyn) +The +.I .dynamic +section contains a series of structures that hold relevant +dynamic linking information. +The +.I d_tag +member controls the interpretation +of +.IR d_un . +.PP +.in +4n +.EX +typedef struct { + Elf32_Sword d_tag; + union { + Elf32_Word d_val; + Elf32_Addr d_ptr; + } d_un; +} Elf32_Dyn; +extern Elf32_Dyn _DYNAMIC[]; +.EE +.in +.PP +.in +4n +.EX +typedef struct { + Elf64_Sxword d_tag; + union { + Elf64_Xword d_val; + Elf64_Addr d_ptr; + } d_un; +} Elf64_Dyn; +extern Elf64_Dyn _DYNAMIC[]; +.EE +.in +.TP \n[l1_indent] +.IR d_tag +This member may have any of the following values: +.RS \n[l1_indent] +.TP 12 +.BR DT_NULL +Marks end of dynamic section +.TP +.BR DT_NEEDED +String table offset to name of a needed library +.TP +.BR DT_PLTRELSZ +Size in bytes of PLT relocation entries +.TP +.BR DT_PLTGOT +Address of PLT and/or GOT +.TP +.BR DT_HASH +Address of symbol hash table +.TP +.BR DT_STRTAB +Address of string table +.TP +.BR DT_SYMTAB +Address of symbol table +.TP +.BR DT_RELA +Address of Rela relocation table +.TP +.BR DT_RELASZ +Size in bytes of the Rela relocation table +.TP +.BR DT_RELAENT +Size in bytes of a Rela relocation table entry +.TP +.BR DT_STRSZ +Size in bytes of string table +.TP +.BR DT_SYMENT +Size in bytes of a symbol table entry +.TP +.BR DT_INIT +Address of the initialization function +.TP +.BR DT_FINI +Address of the termination function +.TP +.BR DT_SONAME +String table offset to name of shared object +.TP +.BR DT_RPATH +String table offset to library search path (deprecated) +.TP +.BR DT_SYMBOLIC +Alert linker to search this shared object before the executable for symbols +.TP +.BR DT_REL +Address of Rel relocation table +.TP +.BR DT_RELSZ +Size in bytes of Rel relocation table +.TP +.BR DT_RELENT +Size in bytes of a Rel table entry +.TP +.BR DT_PLTREL +Type of relocation entry to which the PLT refers (Rela or Rel) +.TP +.BR DT_DEBUG +Undefined use for debugging +.TP +.BR DT_TEXTREL +Absence of this entry indicates that no relocation entries should +apply to a nonwritable segment +.TP +.BR DT_JMPREL +Address of relocation entries associated solely with the PLT +.TP +.BR DT_BIND_NOW +Instruct dynamic linker to process all relocations before +transferring control to the executable +.TP +.BR DT_RUNPATH +String table offset to library search path +.TP +.BR DT_LOPROC ", " DT_HIPROC +Values in the inclusive range +.RB [ DT_LOPROC ", " DT_HIPROC ] +are reserved for processor-specific semantics +.RE +.TP +.IR d_val +This member represents integer values with various interpretations. +.TP +.IR d_ptr +This member represents program virtual addresses. +When interpreting +these addresses, the actual address should be computed based on the +original file value and memory base address. +Files do not contain +relocation entries to fixup these addresses. +.TP +.I _DYNAMIC +Array containing all the dynamic structures in the +.I .dynamic +section. +This is automatically populated by the linker. +.\" GABI ELF Reference for Note Sections: +.\" http://www.sco.com/developers/gabi/latest/ch5.pheader.html#note_section +.\" +.\" Note that it implies the sizes and alignments of notes depend on the ELF +.\" size (e.g. 32-bit ELFs have three 4-byte words and use 4-byte alignment +.\" while 64-bit ELFs use 8-byte words & alignment), but that is not the case +.\" in the real world. Notes always have three 4-byte words as can be seen +.\" in the source links below (remember that Elf64_Word is a 32-bit quantity). +.\" glibc: https://sourceware.org/git/?p=glibc.git;a=blob;f=elf/elf.h;h=9e59b3275917549af0cebe1f2de9ded3b7b10bf2#l1173 +.\" binutils: https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=binutils/readelf.c;h=274ddd17266aef6e4ad1f67af8a13a21500ff2af#l15943 +.\" Linux: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/elf.h?h=v4.8#n422 +.\" Solaris: https://docs.oracle.com/cd/E23824_01/html/819-0690/chapter6-18048.html +.\" FreeBSD: https://svnweb.freebsd.org/base/head/sys/sys/elf_common.h?revision=303677&view=markup#l33 +.\" NetBSD: https://www.netbsd.org/docs/kernel/elf-notes.html +.\" OpenBSD: https://github.com/openbsd/src/blob/master/sys/sys/exec_elf.h#L533 +.\" +.SS Notes (Nhdr) +ELF notes allow for appending arbitrary information for the system to use. +They are largely used by core files +.RI ( e_type +of +.BR ET_CORE ), +but many projects define their own set of extensions. +For example, +the GNU tool chain uses ELF notes to pass information from +the linker to the C library. +.PP +Note sections contain a series of notes (see the +.I struct +definitions below). +Each note is followed by the name field (whose length is defined in +\fIn_namesz\fR) and then by the descriptor field (whose length is defined in +\fIn_descsz\fR) and whose starting address has a 4 byte alignment. +Neither field is defined in the note struct due to their arbitrary lengths. +.PP +An example for parsing out two consecutive notes should clarify their layout +in memory: +.PP +.in +4n +.EX +void *memory, *name, *desc; +Elf64_Nhdr *note, *next_note; + +/* The buffer is pointing to the start of the section/segment */ +note = memory; + +/* If the name is defined, it follows the note */ +name = note->n_namesz == 0 ? NULL : memory + sizeof(*note); + +/* If the descriptor is defined, it follows the name + (with alignment) */ + +desc = note->n_descsz == 0 ? NULL : + memory + sizeof(*note) + ALIGN_UP(note->n_namesz, 4); + +/* The next note follows both (with alignment) */ +next_note = memory + sizeof(*note) + + ALIGN_UP(note->n_namesz, 4) + + ALIGN_UP(note->n_descsz, 4); +.EE +.in +.PP +Keep in mind that the interpretation of +.I n_type +depends on the namespace defined by the +.I n_namesz +field. +If the +.I n_namesz +field is not set (e.g., is 0), then there are two sets of notes: +one for core files and one for all other ELF types. +If the namespace is unknown, then tools will usually fallback to these sets +of notes as well. +.PP +.in +4n +.EX +typedef struct { + Elf32_Word n_namesz; + Elf32_Word n_descsz; + Elf32_Word n_type; +} Elf32_Nhdr; +.EE +.in +.PP +.in +4n +.EX +typedef struct { + Elf64_Word n_namesz; + Elf64_Word n_descsz; + Elf64_Word n_type; +} Elf64_Nhdr; +.EE +.in +.TP \n[l1_indent] +.IR n_namesz +The length of the name field in bytes. +The contents will immediately follow this note in memory. +The name is null terminated. +For example, if the name is "GNU", then +.I n_namesz +will be set to 4. +.TP +.IR n_descsz +The length of the descriptor field in bytes. +The contents will immediately follow the name field in memory. +.TP +.IR n_type +Depending on the value of the name field, this member may have any of the +following values: +.RS \n[l1_indent] +.TP 5 +.B Core files (e_type = ET_CORE) +Notes used by all core files. +These are highly operating system or architecture specific and often require +close coordination with kernels, C libraries, and debuggers. +These are used when the namespace is the default (i.e., +.I n_namesz +will be set to 0), or a fallback when the namespace is unknown. +.RS +.TP 21 +.PD 0 +.B NT_PRSTATUS +prstatus struct +.TP +.B NT_FPREGSET +fpregset struct +.TP +.B NT_PRPSINFO +prpsinfo struct +.TP +.B NT_PRXREG +prxregset struct +.TP +.B NT_TASKSTRUCT +task structure +.TP +.B NT_PLATFORM +String from sysinfo(SI_PLATFORM) +.TP +.B NT_AUXV +auxv array +.TP +.B NT_GWINDOWS +gwindows struct +.TP +.B NT_ASRS +asrset struct +.TP +.B NT_PSTATUS +pstatus struct +.TP +.B NT_PSINFO +psinfo struct +.TP +.B NT_PRCRED +prcred struct +.TP +.B NT_UTSNAME +utsname struct +.TP +.B NT_LWPSTATUS +lwpstatus struct +.TP +.B NT_LWPSINFO +lwpinfo struct +.TP +.B NT_PRFPXREG +fprxregset struct +.TP +.B NT_SIGINFO +siginfo_t (size might increase over time) +.TP +.B NT_FILE +Contains information about mapped files +.TP +.B NT_PRXFPREG +user_fxsr_struct +.TP +.B NT_PPC_VMX +PowerPC Altivec/VMX registers +.TP +.B NT_PPC_SPE +PowerPC SPE/EVR registers +.TP +.B NT_PPC_VSX +PowerPC VSX registers +.TP +.B NT_386_TLS +i386 TLS slots (struct user_desc) +.TP +.B NT_386_IOPERM +x86 io permission bitmap (1=deny) +.TP +.B NT_X86_XSTATE +x86 extended state using xsave +.TP +.B NT_S390_HIGH_GPRS +s390 upper register halves +.TP +.B NT_S390_TIMER +s390 timer register +.TP +.B NT_S390_TODCMP +s390 time-of-day (TOD) clock comparator register +.TP +.B NT_S390_TODPREG +s390 time-of-day (TOD) programmable register +.TP +.B NT_S390_CTRS +s390 control registers +.TP +.B NT_S390_PREFIX +s390 prefix register +.TP +.B NT_S390_LAST_BREAK +s390 breaking event address +.TP +.B NT_S390_SYSTEM_CALL +s390 system call restart data +.TP +.B NT_S390_TDB +s390 transaction diagnostic block +.TP +.B NT_ARM_VFP +ARM VFP/NEON registers +.TP +.B NT_ARM_TLS +ARM TLS register +.TP +.B NT_ARM_HW_BREAK +ARM hardware breakpoint registers +.TP +.B NT_ARM_HW_WATCH +ARM hardware watchpoint registers +.TP +.B NT_ARM_SYSTEM_CALL +ARM system call number +.PD +.RE +.TP +.B n_name = GNU +Extensions used by the GNU tool chain. +.RS +.TP +.B NT_GNU_ABI_TAG +Operating system (OS) ABI information. +The desc field will be 4 words: +.IP +.PD 0 +.RS +.IP \(bu 2 +word 0: OS descriptor +(\fBELF_NOTE_OS_LINUX\fR, \fBELF_NOTE_OS_GNU\fR, and so on)` +.IP \(bu +word 1: major version of the ABI +.IP \(bu +word 2: minor version of the ABI +.IP \(bu +word 3: subminor version of the ABI +.RE +.PD +.TP +.B NT_GNU_HWCAP +Synthetic hwcap information. +The desc field begins with two words: +.IP +.PD 0 +.RS +.IP \(bu 2 +word 0: number of entries +.IP \(bu +word 1: bit mask of enabled entries +.RE +.PD +.IP +Then follow variable-length entries, one byte followed by a null-terminated +hwcap name string. +The byte gives the bit number to test if enabled, (1U << bit) & bit mask. +.TP +.B NT_GNU_BUILD_ID +Unique build ID as generated by the GNU +.BR ld (1) +.BR \-\-build\-id +option. +The desc consists of any nonzero number of bytes. +.TP +.B NT_GNU_GOLD_VERSION +The desc contains the GNU Gold linker version used. +.RE +.TP +.B Default/unknown namespace (e_type != ET_CORE) +These are used when the namespace is the default (i.e., +.I n_namesz +will be set to 0), or a fallback when the namespace is unknown. +.RS +.TP 21 +.PD 0 +.B NT_VERSION +A version string of some sort. +.TP +.B NT_ARCH +Architecture information. +.PD +.RE +.PP +.RE +.SH NOTES +.\" OpenBSD +.\" ELF support first appeared in +.\" OpenBSD 1.2, +.\" although not all supported platforms use it as the native +.\" binary file format. +ELF first appeared in +System V. +The ELF format is an adopted standard. +.PP +The extensions for +.IR e_phnum , +.IR e_shnum +and +.IR e_strndx +respectively are +Linux extensions. +Sun, BSD and AMD64 also support them; for further information, +look under SEE ALSO. +.\" .SH AUTHORS +.\" The original version of this manual page was written by +.\" .An Jeroen Ruigrok van der Werven +.\" .Aq asmodai@FreeBSD.org +.\" with inspiration from BSDi's +.\" .Bsx +.\" .Nm elf +.\" man page. +.SH SEE ALSO +.BR as (1), +.BR elfedit (1), +.BR gdb (1), +.BR ld (1), +.BR nm (1), +.BR objdump (1), +.BR readelf (1), +.BR size (1), +.BR strings (1), +.BR strip (1), +.BR execve (2), +.BR dl_iterate_phdr (3), +.BR core (5) +.PP +Hewlett-Packard, +.IR "Elf-64 Object File Format" . +.PP +Santa Cruz Operation, +.IR "System V Application Binary Interface" . +.PP +UNIX System Laboratories, +"Object Files", +.IR "Executable and Linking Format (ELF)" . +.PP +Sun Microsystems, +.IR "Linker and Libraries Guide" . +.PP +AMD64 ABI Draft, +.IR "System V Application Binary Interface AMD64 Architecture Processor Supplement" . +.PP +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/filesystems.5 b/man5/filesystems.5 new file mode 100644 index 0000000..83afb68 --- /dev/null +++ b/man5/filesystems.5 @@ -0,0 +1,223 @@ +.\" Copyright 1996 Daniel Quinlan (Daniel.Quinlan@linux.org) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2007-12-14 mtk Added Reiserfs, XFS, JFS. +.\" +.TH FILESYSTEMS 5 2017-09-15 "Linux" "Linux Programmer's Manual" +.nh +.SH NAME +filesystems \- Linux filesystem types: ext, ext2, ext3, ext4, hpfs, iso9660, +JFS, minix, msdos, ncpfs nfs, ntfs, proc, Reiserfs, smb, sysv, umsdos, vfat, +XFS, xiafs, +.SH DESCRIPTION +When, as is customary, the +.B proc +filesystem is mounted on +.IR /proc , +you can find in the file +.I /proc/filesystems +which filesystems your kernel currently supports; +see +.BR proc (5) +for more details. +If you need a currently unsupported filesystem, insert the corresponding +module or recompile the kernel. +.PP +In order to use a filesystem, you have to +.I mount +it; see +.BR mount (8). +.PP +Below a short description of the available or historically available +filesystems in the Linux kernel. +See kernel documentation for a comprehensive +description of all options and limitations. +.TP 10 +.B ext +is an elaborate extension of the +.B minix +filesystem. +It has been completely superseded by the second version +of the extended filesystem +.RB ( ext2 ) +and has been removed from the kernel (in 2.1.21). +.TP +.B ext2 +is the high performance disk filesystem used by Linux for fixed disks +as well as removable media. +The second extended filesystem was designed as an extension of the +extended filesystem +.RB ( ext ). +.RB See " ext2 " (5). +.TP +.B ext3 +is a journaling version of the +.B ext2 +filesystem. +It is easy to +switch back and forth between +.B ext2 +and +.BR ext3 . +.RB See " ext3 " (5). +.TP +.B ext4 +is a set of upgrades to +.B ext3 +including substantial performance and +reliability enhancements, +plus large increases in volume, file, and directory size limits. +.RB See " ext4 " (5). +.TP +.B hpfs +is the High Performance Filesystem, used in OS/2. +This filesystem is +read-only under Linux due to the lack of available documentation. +.TP +.B iso9660 +is a CD-ROM filesystem type conforming to the ISO 9660 standard. +.RS +.TP +.B "High Sierra" +Linux supports High Sierra, the precursor to the ISO 9660 standard for +CD-ROM filesystems. +It is automatically recognized within the +.B iso9660 +filesystem support under Linux. +.TP +.B "Rock Ridge" +Linux also supports the System Use Sharing Protocol records specified +by the Rock Ridge Interchange Protocol. +They are used to further describe the files in the +.B iso9660 +filesystem to a UNIX host, and provide information such as long +filenames, UID/GID, POSIX permissions, and devices. +It is automatically recognized within the +.B iso9660 +filesystem support under Linux. +.RE +.TP +.B JFS +is a journaling filesystem, developed by IBM, +that was integrated into Linux in kernel 2.4.24. +.TP +.B minix +is the filesystem used in the Minix operating system, the first to run +under Linux. +It has a number of shortcomings, including a 64\ MB partition size +limit, short filenames, and a single timestamp. +It remains useful for floppies and RAM disks. +.TP +.B msdos +is the filesystem used by DOS, Windows, and some OS/2 computers. +.B msdos +filenames can be no longer than 8 characters, followed by an +optional period and 3 character extension. +.TP +.B ncpfs +is a network filesystem that supports the NCP protocol, used by +Novell NetWare. +.IP +To use +.BR ncpfs , +you need special programs, which can be found at +.UR ftp://linux01.gwdg.de\:/pub\:/ncpfs +.UE . +.TP +.B nfs +is the network filesystem used to access disks located on remote computers. +.TP +.B ntfs +replaces Microsoft Window's FAT filesystems (VFAT, FAT32). +It has reliability, performance, and space-utilization enhancements +plus features like ACLs, journaling, encryption, and so on. +.TP +.B proc +is a pseudo filesystem which is used as an interface to kernel data +structures rather than reading and interpreting +.IR /dev/kmem . +In particular, its files do not take disk space. +See +.BR proc (5). +.TP +.B Reiserfs +is a journaling filesystem, designed by Hans Reiser, +that was integrated into Linux in kernel 2.4.1. +.TP +.B smb +is a network filesystem that supports the SMB protocol, used by +Windows for Workgroups, Windows NT, and Lan Manager. +See +.UR https://www.samba.org\:/samba\:/smbfs/ +.UE . +.TP +.B sysv +is an implementation of the SystemV/Coherent filesystem for Linux. +It implements all of Xenix FS, SystemV/386 FS, and Coherent FS. +.TP +.B umsdos +is an extended DOS filesystem used by Linux. +It adds capability for +long filenames, UID/GID, POSIX permissions, and special files +(devices, named pipes, etc.) under the DOS filesystem, without +sacrificing compatibility with DOS. +.TP +.B vfat +is an extended FAT filesystem used by Microsoft Windows95 and Windows NT. +.B vfat +adds the capability to use long filenames under the MSDOS filesystem. +.TP +.B XFS +is a journaling filesystem, developed by SGI, +that was integrated into Linux in kernel 2.4.20. +.TP +.B xiafs +was designed and implemented to be a stable, safe filesystem by +extending the Minix filesystem code. +It provides the basic most +requested features without undue complexity. +The +.B xiafs +filesystem is no longer actively developed or maintained. +It was removed from the kernel in 2.1.21. +.SH SEE ALSO +.BR fuse (4), +.BR btrfs (5), +.BR ext2 (5), +.BR ext3 (5), +.BR ext4 (5), +.BR nfs (5), +.BR proc (5), +.BR tmpfs (5), +.BR fsck (8), +.BR mkfs (8), +.BR mount (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/fs.5 b/man5/fs.5 new file mode 100644 index 0000000..3ec300c --- /dev/null +++ b/man5/fs.5 @@ -0,0 +1 @@ +.so man5/filesystems.5 diff --git a/man5/ftpusers.5 b/man5/ftpusers.5 new file mode 100644 index 0000000..2a27fd0 --- /dev/null +++ b/man5/ftpusers.5 @@ -0,0 +1,65 @@ +.\" Copyright (c) 2000 Christoph J. Thompson +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_MISC) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH FTPUSERS 5 2000-08-27 "Linux" "Linux Programmer's Manual" +.SH NAME +ftpusers \- list of users that may not log in via the FTP daemon +.SH DESCRIPTION +The text file +.B ftpusers +contains a list of users that may not log in using the +File Transfer Protocol (FTP) server daemon. +This file is used not merely for +system administration purposes but also for improving security within a TCP/IP +networked environment. +.PP +The +.B ftpusers +file will typically contain a list of the users that +either have no business using ftp or have too many privileges to be allowed +to log in through the FTP server daemon. +Such users usually include root, daemon, bin, uucp, and news. +.PP +If your FTP server daemon doesn't use +.BR ftpusers , +then it is suggested that you read its documentation to find out how to +block access for certain users. +Washington University FTP server Daemon +(wuftpd) and Professional FTP Daemon (proftpd) are known to make use of +.BR ftpusers . +.SS Format +The format of +.B ftpusers +is very simple. +There is one account name (or username) per line. +Lines starting with a # are ignored. +.SH FILES +.I /etc/ftpusers +.SH SEE ALSO +.BR passwd (5), +.BR proftpd (8), +.BR wuftpd (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/gai.conf.5 b/man5/gai.conf.5 new file mode 100644 index 0000000..7628a7f --- /dev/null +++ b/man5/gai.conf.5 @@ -0,0 +1,111 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All rights reserved. +.\" Author: Ulrich Drepper +.\" +.\" %%%LICENSE_START(GPLv2_MISC) +.\" This copyrighted material is made available to anyone wishing to use, +.\" modify, copy, or redistribute it subject to the terms and conditions of the +.\" GNU General Public License v.2. +.\" +.\" This program is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +.\" more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH GAI.CONF 5 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +gai.conf \- getaddrinfo(3) configuration file +.SH DESCRIPTION +A call to +.BR getaddrinfo (3) +might return multiple answers. +According to RFC\ 3484 these answers must be sorted so that +the answer with the highest success rate is first in the list. +The RFC provides an algorithm for the sorting. +The static rules are not always adequate, though. +For this reason, +the RFC also requires that system administrators should have the possibility +to dynamically change the sorting. +For the glibc implementation, this can be achieved with the +.IR /etc/gai.conf +file. +.PP +Each line in the configuration file consists of a keyword and its parameters. +White spaces in any place are ignored. +Lines starting with \(aq#\(aq are comments and are ignored. +.PP +The keywords currently recognized are: +.TP +\fBlabel\fR \fInetmask\fR \fIprecedence\fR +The value is added to the label table used in the RFC\ 3484 sorting. +If any \fBlabel\fR definition is present in the configuration file, +the default table is not used. +All the label definitions +of the default table which are to be maintained have to be duplicated. +Following the keyword, +the line has to contain a network mask and a precedence value. +.TP +\fBprecedence\fR \fInetmask\fR \fIprecedence\fR +This keyword is similar to \fBlabel\fR, but instead the value is added +to the precedence table as specified in RFC\ 3484. +Once again, the +presence of a single \fBprecedence\fR line in the configuration file +causes the default table to not be used. +.TP +\fBreload\fR <\fByes\fR|\fBno\fR> +This keyword controls whether a process checks whether the configuration +file has been changed since the last time it was read. +If the value is +"\fByes\fR", the file is reread. +This might cause problems in multithreaded +applications and is generally a bad idea. +The default is "\fBno\fR". +.TP +\fBscopev4\fR \fImask\fR \fIvalue\fR +Add another rule to the RFC\ 3484 scope table for IPv4 address. +By default, the scope IDs described in section 3.2 in RFC\ 3438 are used. +Changing these defaults should hardly ever be necessary. +.SH FILES +\fI/etc/gai.conf\fR +.SH VERSIONS +The +.I gai.conf +.\" Added in 2006 +file is supported by glibc since version 2.5. +.SH EXAMPLE +The default table according to RFC\ 3484 would be specified with the +following configuration file: +.PP +.in +4n +.EX +label ::1/128 0 +label ::/0 1 +label 2002::/16 2 +label ::/96 3 +label ::ffff:0:0/96 4 +precedence ::1/128 50 +precedence ::/0 40 +precedence 2002::/16 30 +precedence ::/96 20 +precedence ::ffff:0:0/96 10 +.EE +.in +.\" .SH AUTHOR +.\" Ulrich Drepper +.\" +.SH SEE ALSO +.BR getaddrinfo (3), +RFC\ 3484 +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/group.5 b/man5/group.5 new file mode 100644 index 0000000..80bec55 --- /dev/null +++ b/man5/group.5 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:06:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH GROUP 5 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +group \- user group file +.SH DESCRIPTION +The +.I /etc/group +file is a text file that defines the groups on the system. +There is one entry per line, with the following format: +.PP +.in +4n +.EX +group_name:password:GID:user_list +.EE +.in +.PP +The fields are as follows: +.TP 12 +.I group_name +the name of the group. +.TP +.I password +the (encrypted) group password. +If this field is empty, no password is needed. +.TP +.I GID +the numeric group ID. +.TP +.I user_list +a list of the usernames that are members of this group, separated by commas. +.SH FILES +.I /etc/group +.SH BUGS +As the 4.2BSD +.BR initgroups (3) +man page says: no one seems to keep +.I /etc/group +up-to-date. +.SH SEE ALSO +.BR chgrp (1), +.BR gpasswd (1), +.BR groups (1), +.BR login (1), +.BR newgrp (1), +.BR sg (1), +.BR getgrent (3), +.BR getgrnam (3), +.BR gshadow (5), +.BR passwd (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/host.conf.5 b/man5/host.conf.5 new file mode 100644 index 0000000..1f65840 --- /dev/null +++ b/man5/host.conf.5 @@ -0,0 +1,226 @@ +.\" Copyright (c) 1997 Martin Schulze (joey@infodrom.north.de) +.\" Much of the text is copied from the manpage of resolv+(8). +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2003-08-23 Martin Schulze Updated according to glibc 2.3.2 +.TH HOST.CONF 5 2017-09-15 "Linux" "Linux System Administration" +.SH NAME +host.conf \- resolver configuration file +.SH DESCRIPTION +The file +.I /etc/host.conf +contains configuration information specific to the resolver library. +It should contain one configuration keyword per line, followed by +appropriate configuration information. +The following keywords are recognized: +.TP +.I trim +This keyword may be listed more than once. +Each time it should be +followed by a list of domains, separated by colons (\(aq:\(aq), semicolons +(\(aq;\(aq) or commas (\(aq,\(aq), with the leading dot. +When set, the +resolver library will automatically trim the given domain name from the +end of any hostname resolved via DNS. +This is intended for use with +local hosts and domains. +(Related note: +.I trim +will not affect hostnames gathered via NIS or the +.BR hosts (5) +file. +Care should be taken to +ensure that the first hostname for each entry in the hosts file is +fully qualified or unqualified, as appropriate for the local +installation.) +.TP +.I multi +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library will return all valid addresses for a host that +appears in the +.I /etc/hosts +file, +instead of only the first. +This is +.I off +by default, as it may cause a substantial performance loss at sites +with large hosts files. +.TP +.I reorder +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library +will attempt to reorder host addresses so that local addresses +(i.e., on the same subnet) are listed first when a +.BR gethostbyname (3) +is performed. +Reordering is done for all lookup methods. +The default value is +.IR off . +.SH ENVIRONMENT +The following environment variables can be used to allow users to +override the behavior which is configured in +.IR /etc/host.conf : +.TP +.B RESOLV_HOST_CONF +If set, this variable points to a file that should be read instead of +.IR /etc/host.conf . +.TP +.B RESOLV_MULTI +Overrides the +.I multi +command. +.TP +.B RESOLV_REORDER +Overrides the +.I reorder +command. +.TP +.B RESOLV_ADD_TRIM_DOMAINS +A list of domains, separated by colons (\(aq:\(aq), semicolons (\(aq;\(aq) or +commas (\(aq,\(aq), with the leading dot, which will be added to the list of +domains that should be trimmed. +.TP +.B RESOLV_OVERRIDE_TRIM_DOMAINS +A list of domains, separated by colons (\(aq:\(aq), semicolons (\(aq;\(aq) or +commas (\(aq,\(aq), with the leading dot, which will replace the list of +domains that should be trimmed. +Overrides the +.I trim +command. +.SH FILES +.TP +.I /etc/host.conf +Resolver configuration file +.TP +.I /etc/resolv.conf +Resolver configuration file +.TP +.I /etc/hosts +Local hosts database +.SH NOTES +The following differences exist compared to the original implementation. +A new command +.I spoof +and a new environment variable +.B RESOLV_SPOOF_CHECK +can take arguments like +.IR off ", " nowarn ", and " warn . +Line comments can appear anywhere and not only at the beginning of a line. +.SS Historical +The +.BR nsswitch.conf (5) +file is the modern way of controlling the order of host lookups. +.PP +In glibc 2.4 and earlier, the following keyword is recognized: +.TP +.I order +This keyword specifies how host lookups are to be performed. +It should be followed by one or more lookup methods, separated by commas. +Valid methods are +.IR bind ", " hosts ", and " nis . +.TP +.B RESOLV_SERV_ORDER +Overrides the +.I order +command. +.PP +Since glibc 2.0.7, the following keywords and environment variable have +been recognized but never implemented: +.TP +.I nospoof +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library will attempt to prevent hostname spoofing to +enhance the security of +.BR rlogin " and " rsh . +It works as follows: after performing a host address lookup, +the resolver library will perform a hostname lookup for that address. +If the two hostnames +do not match, the query fails. +The default value is +.IR off . +.TP +.I spoofalert +Valid values are +.IR on " and " off . +If this option is set to +.I on +and the +.I nospoof +option is also set, +the resolver library will log a warning of the error via the +syslog facility. +The default value is +.IR off . +.TP +.I spoof +Valid values are +.IR off ", " nowarn ", and " warn . +If this option is set to +.IR off , +spoofed addresses are permitted and no warnings will be emitted +via the syslog facility. +If this option is set to +.IR warn , +the resolver library will attempt to prevent hostname spoofing to +enhance the security and log a warning of the error via the syslog +facility. +If this option is set to +.IR nowarn , +the resolver library will attempt to prevent hostname spoofing to +enhance the security but not emit warnings via the syslog facility. +Setting this option to anything else is equal to setting it to +.IR nowarn . +.TP +.B RESOLV_SPOOF_CHECK +Overrides the +.IR nospoof ", " spoofalert ", and " spoof +commands in the same way as the +.I spoof +command is parsed. +Valid values are +.IR off ", " nowarn ", and " warn . +.SH SEE ALSO +.BR gethostbyname (3), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR resolv.conf (5), +.BR hostname (7), +.BR named (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/hosts.5 b/man5/hosts.5 new file mode 100644 index 0000000..2fb0826 --- /dev/null +++ b/man5/hosts.5 @@ -0,0 +1,145 @@ +.\" Copyright (c) 2000 Manoj Srivastava +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Minor polishing, aeb +.\" Modified, 2002-06-16, Mike Coleman +.\" +.TH HOSTS 5 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +hosts \- static table lookup for hostnames +.SH SYNOPSIS +.B /etc/hosts +.SH DESCRIPTION +This manual page describes the format of the +.I /etc/hosts +file. +This file is a simple text file that associates IP addresses +with hostnames, one line per IP address. +For each host a single +line should be present with the following information: +.RS +.PP +IP_address canonical_hostname [aliases...] +.RE +.PP +Fields of the entry are separated by any number of blanks and/or +tab characters. +Text from a "#" character until the end of the line is +a comment, and is ignored. +Host names may contain only alphanumeric +characters, minus signs ("\-"), and periods ("."). +They must begin with an +alphabetic character and end with an alphanumeric character. +Optional aliases provide for name changes, alternate spellings, +shorter hostnames, or generic hostnames (for example, +.IR localhost ). +.PP +The Berkeley Internet Name Domain (BIND) Server implements the +Internet name server for UNIX systems. +It augments or replaces the +.I /etc/hosts +file or hostname lookup, and frees a host from relying on +.I /etc/hosts +being up to date and complete. +.PP +In modern systems, even though the host table has been superseded by +DNS, it is still widely used for: +.TP +.B bootstrapping +Most systems have a small host table containing the name and address +information for important hosts on the local network. +This is useful +when DNS is not running, for example during system bootup. +.TP +.B NIS +Sites that use NIS use the host table as input to the NIS host +database. +Even though NIS can be used with DNS, most NIS sites still +use the host table with an entry for all local hosts as a backup. +.TP +.B isolated nodes +Very small sites that are isolated from the network use the host table +instead of DNS. +If the local information rarely changes, and the +network is not connected to the Internet, DNS offers little +advantage. +.SH FILES +.I /etc/hosts +.SH NOTES +Modifications to this file normally take effect immediately, +except in cases where the file is cached by applications. +.SS Historical notes +RFC\ 952 gave the original format for the host table, though it has +since changed. +.PP +Before the advent of DNS, the host table was the only way of resolving +hostnames on the fledgling Internet. +Indeed, this file could be +created from the official host data base maintained at the Network +Information Control Center (NIC), though local changes were often +required to bring it up to date regarding unofficial aliases and/or +unknown hosts. +The NIC no longer maintains the hosts.txt files, +though looking around at the time of writing (circa 2000), there are +historical hosts.txt files on the WWW. +I just found three, from 92, +94, and 95. +.SH EXAMPLE +.EX +# The following lines are desirable for IPv4 capable hosts +127.0.0.1 localhost + +# 127.0.1.1 is often used for the FQDN of the machine +127.0.1.1 thishost.mydomain.org thishost +192.168.1.10 foo.mydomain.org foo +192.168.1.13 bar.mydomain.org bar +146.82.138.7 master.debian.org master +209.237.226.90 www.opensource.org + +# The following lines are desirable for IPv6 capable hosts +::1 localhost ip6-localhost ip6-loopback +ff02::1 ip6-allnodes +ff02::2 ip6-allrouters +.EE +.SH SEE ALSO +.BR hostname (1), +.BR resolver (3), +.BR host.conf (5), +.BR resolv.conf (5), +.BR resolver (5), +.BR hostname (7), +.BR named (8) +.PP +Internet RFC\ 952 +.\" .SH AUTHOR +.\" This manual page was written by Manoj Srivastava , +.\" for the Debian GNU/Linux system. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/hosts.equiv.5 b/man5/hosts.equiv.5 new file mode 100644 index 0000000..2e86214 --- /dev/null +++ b/man5/hosts.equiv.5 @@ -0,0 +1,182 @@ +.\" Copyright (c) 1995 Peter Tobias +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" This file may be distributed under the GNU General Public License. +.\" %%%LICENSE_END +.TH HOSTS.EQUIV 5 2015-07-23 "Linux" "Linux Programmer's Manual" +.SH NAME +hosts.equiv \- list of hosts and users that are granted "trusted" +.B r +command access to your system +.SH DESCRIPTION +The file +.I /etc/hosts.equiv +allows or denies hosts and users to use +the \fBr\fP-commands (e.g., +.BR rlogin , +.BR rsh , +or +.BR rcp ) +without +supplying a password. +.PP +The file uses the following format: +.TP +\fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP +.PP +The +.I hostname +is the name of a host which is logically equivalent +to the local host. +Users logged into that host are allowed to access +like-named user accounts on the local host without supplying a password. +The +.I hostname +may be (optionally) preceded by a plus (+) sign. +If the plus sign is used alone, it allows any host to access your system. +You can explicitly deny access to a host by preceding the +.I hostname +by a minus (\-) sign. +Users from that host must always supply additional credentials, +including possibly a password. For security reasons you should always +use the FQDN of the hostname and not the short hostname. +.PP +The +.I username +entry grants a specific user access to all user +accounts (except root) without supplying a password. +That means the +user is NOT restricted to like-named accounts. +The +.I username +may +be (optionally) preceded by a plus (+) sign. +You can also explicitly +deny access to a specific user by preceding the +.I username +with +a minus (\-) sign. +This says that the user is not trusted no matter +what other entries for that host exist. +.PP +Netgroups can be specified by preceding the netgroup by an @ sign. +.PP +Be extremely careful when using the plus (+) sign. +A simple typographical +error could result in a standalone plus sign. +A standalone plus sign is +a wildcard character that means "any host"! +.SH FILES +.I /etc/hosts.equiv +.SH NOTES +Some systems will honor the contents of this file only when it has owner +root and no write permission for anybody else. +Some exceptionally +paranoid systems even require that there be no other hard links to the file. +.PP +Modern systems use the Pluggable Authentication Modules library (PAM). +With PAM a standalone plus sign is considered a wildcard +character which means "any host" only when the word +.I promiscuous +is added to the auth component line in your PAM file for +the particular service +.RB "(e.g., " rlogin ). +.SH EXAMPLE +Below are some example +.I /etc/host.equiv +or +.I ~/.rhosts +files. +.PP +Allow any user to log in from any host: +.PP + + +.PP +Allow any user from +.I host +with a matching local account to log in: +.PP + host +.PP +Note: the use of +.I +host +is never a valid syntax, +including attempting to specify that any user from the host is allowed. +.PP +Allow any user from +.I host +to log in: +.PP + host + +.PP +Note: this is distinct from the previous example +since it does not require a matching local account. +.PP +Allow +.I user +from +.I host +to log in as any non-root user: +.PP + host user +.PP +Allow all users with matching local accounts from +.I host +to log in except for +.IR baduser : +.PP + host \-baduser + host +.PP +Deny all users from +.IR host : +.PP + \-host +.PP +Note: the use of +.I "\-host\ \-user" +is never a valid syntax, +including attempting to specify that a particular user from the host +is not trusted. +.PP +Allow all users with matching local accounts on all hosts in a +.IR netgroup : +.PP + +@netgroup +.PP +Disallow all users on all hosts in a +.IR netgroup : +.PP + \-@netgroup +.PP +Allow all users in a +.I netgroup +to log in from +.IR host +as any non-root user: +.PP + host +@netgroup +.PP +Allow all users with matching local accounts on all hosts in a +.I netgroup +except +.IR baduser : +.PP + +@netgroup \-baduser + +@netgroup +.PP +Note: the deny statements must always precede the allow statements because +the file is processed sequentially until the first matching rule is found. +.SH SEE ALSO +.BR rhosts (5), +.BR rlogind (8), +.BR rshd (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/intro.5 b/man5/intro.5 new file mode 100644 index 0000000..4792d50 --- /dev/null +++ b/man5/intro.5 @@ -0,0 +1,51 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:06:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jan 14 00:34:09 1996 by Andries Brouwer (aeb@cwi.nl) +.TH INTRO 5 2017-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- introduction to file formats and filesystems +.SH DESCRIPTION +Section 5 of the manual describes various file formats, +as well as the corresponding C structures, if any. +.PP +In addition, +this section contains a number of pages that document various filesystems. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/ipc.5 b/man5/ipc.5 new file mode 100644 index 0000000..c5bca41 --- /dev/null +++ b/man5/ipc.5 @@ -0,0 +1 @@ +.so man7/svipc.7 diff --git a/man5/issue.5 b/man5/issue.5 new file mode 100644 index 0000000..85ec2f9 --- /dev/null +++ b/man5/issue.5 @@ -0,0 +1,52 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sun Jul 25 11:06:22 1993 by Rik Faith +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.TH ISSUE 5 1993-07-24 "Linux" "Linux Programmer's Manual" +.SH NAME +issue \- prelogin message and identification file +.SH DESCRIPTION +.I /etc/issue +is a text file which contains a message or +system identification to be printed before the login prompt. +It may contain various \fB@\fP\fIchar\fP and \fB\e\fP\fIchar\fP +sequences, if supported by the +.BR getty -type +program employed on the system. +.SH FILES +.I /etc/issue +.SH SEE ALSO +.BR motd (5), +.BR agetty (8), +.BR mingetty (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/locale.5 b/man5/locale.5 new file mode 100644 index 0000000..ad39173 --- /dev/null +++ b/man5/locale.5 @@ -0,0 +1,1342 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) +.\" Copyright (C) 2008 Petr Baudis (pasky@suse.cz) +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2008-06-17 Petr Baudis +.\" LC_TIME: Describe first_weekday and first_workday +.\" +.TH LOCALE 5 2017-09-15 "Linux" "Linux User Manual" +.SH NAME +locale \- describes a locale definition file +.SH DESCRIPTION +The +.B locale +definition file contains all the information that the +.BR localedef (1) +command needs to convert it into the binary locale database. +.PP +The definition files consist of sections which each describe a +locale category in detail. +See +.BR locale (7) +for additional details for these categories. +.SS Syntax +The locale definition file starts with a header that may consist +of the following keywords: +.TP +.I escape_char +is followed by a character that should be used as the +escape-character for the rest of the file to mark characters that +should be interpreted in a special way. +It defaults to the backslash (\\). +.TP +.I comment_char +is followed by a character that will be used as the +comment-character for the rest of the file. +It defaults to the number sign (#). +.PP +The locale definition has one part for each locale category. +Each part can be copied from another existing locale or +can be defined from scratch. +If the category should be copied, +the only valid keyword in the definition is +.I copy +followed by the name of the locale in double quotes which should be +copied. +The exceptions for this rule are +.B LC_COLLATE +and +.B LC_CTYPE +where a +.I copy +statement can be followed by locale-specific rules and selected overrides. +.PP +When defining a locale or a category from scratch, an existing system- +provided locale definition file should be used as a reference to follow +common glibc conventions. +.SS Locale category sections +The following category sections are defined by POSIX: +.IP * 3 +.B LC_CTYPE +.IP * +.B LC_COLLATE +.IP * +.B LC_MESSAGES +.IP * +.B LC_MONETARY +.IP * +.B LC_NUMERIC +.IP * +.B LC_TIME +.PP +In addition, since version 2.2, +the GNU C library supports the following nonstandard categories: +.IP * 3 +.B LC_ADDRESS +.IP * +.B LC_IDENTIFICATION +.IP * +.B LC_MEASUREMENT +.IP * +.B LC_NAME +.IP * +.B LC_PAPER +.IP * +.B LC_TELEPHONE +.PP +See +.BR locale (7) +for a more detailed description of each category. +.PP +.SS LC_ADDRESS +The definition starts with the string +.I LC_ADDRESS +in the first column. +.PP +The following keywords are allowed: +.TP +.I postal_fmt +followed by a string containing field descriptors that define +the format used for postal addresses in the locale. +The following field descriptors are recognized: +.RS +.TP +%n +Person's name, possibly constructed with the +.B LC_NAME +.I name_fmt +keyword (since glibc 2.24). +.TP 4 +%a +Care of person, or organization. +.TP +%f +Firm name. +.TP +%d +Department name. +.TP +%b +Building name. +.TP +%s +Street or block (e.g., Japanese) name. +.TP +%h +House number or designation. +.TP +%N +Insert an end-of-line if the previous descriptor's value was not an empty +string; otherwise ignore. +.TP +%t +Insert a space if the previous descriptor's value was not an empty string; +otherwise ignore. +.TP +%r +Room number, door designation. +.TP +%e +Floor number. +.TP +%C +Country designation, from the +.I country_post +keyword. +.TP +%l +Local township within town or city (since glibc 2.24). +.TP +%z +Zip number, postal code. +.TP +%T +Town, city. +.TP +%S +State, province, or prefecture. +.TP +%c +Country, as taken from data record. +.PP +Each field descriptor may have an \(aqR\(aq after +the \(aq%\(aq to specify that the +information is taken from a Romanized version string of the +entity. +.RE +.TP +.I country_name +followed by the country name in the language of the current document +(e.g., "Deutschland" for the +.B de_DE +locale). +.TP +.I country_post +followed by the abbreviation of the country (see CERT_MAILCODES). +.TP +.I country_ab2 +followed by the two-letter abbreviation of the country (ISO 3166). +.TP +.I country_ab3 +followed by the three-letter abbreviation of the country (ISO 3166). +.TP +.I country_num +followed by the numeric country code (ISO 3166). +.TP +.I country_car +followed by the international licence plate country code. +.TP +.I country_isbn +followed by the ISBN code (for books). +.TP +.I lang_name +followed by the language name in the language of the current document. +.TP +.I lang_ab +followed by the two-letter abbreviation of the language (ISO 639). +.TP +.I lang_term +followed by the three-letter abbreviation of the language (ISO 639-2/T). +.TP +.I lang_lib +followed by the three-letter abbreviation of the language for library +use (ISO 639-2/B). +Applications should in general prefer +.IR lang_term +over +.IR lang_lib . +.PP +The +.B LC_ADDRESS +definition ends with the string +.IR "END LC_ADDRESS" . +.SS LC_CTYPE +The definition starts with the string +.I LC_CTYPE +in the first column. +.PP +The following keywords are allowed: +.TP +.I upper +followed by a list of uppercase letters. +The letters +.B A +through +.B Z +are included automatically. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I lower +followed by a list of lowercase letters. +The letters +.B a +through +.B z +are included automatically. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I alpha +followed by a list of letters. +All character specified as either +.B upper +or +.B lower +are automatically included. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I digit +followed by the characters classified as numeric digits. +Only the +digits +.B 0 +through +.B 9 +are allowed. +They are included by default in this class. +.TP +.I space +followed by a list of characters defined as white-space +characters. +Characters also specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR graph , +or +.B xdigit +are not allowed. +The characters +.BR , +.BR , +.BR , +.BR , +.BR , +and +.B +are automatically included. +.TP +.I cntrl +followed by a list of control characters. +Characters also specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR punct , +.BR graph , +.BR print , +or +.B xdigit +are not allowed. +.TP +.I punct +followed by a list of punctuation characters. +Characters also +specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR cntrl , +.BR xdigit , +or the +.B +character are not allowed. +.TP +.I graph +followed by a list of printable characters, not including the +.B +character. +The characters defined as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR xdigit , +and +.B punct +are automatically included. +Characters also specified as +.B cntrl +are not allowed. +.TP +.I print +followed by a list of printable characters, including the +.B +character. +The characters defined as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR xdigit , +.BR punct , +and the +.B +character are automatically included. +Characters also specified as +.B cntrl +are not allowed. +.TP +.I xdigit +followed by a list of characters classified as hexadecimal +digits. +The decimal digits must be included followed by one or +more set of six characters in ascending order. +The following +characters are included by default: +.B 0 +through +.BR 9 , +.B a +through +.BR f , +.B A +through +.BR F . +.TP +.I blank +followed by a list of characters classified as +.BR blank . +The characters +.B +and +.B +are automatically included. +.TP +.I charclass +followed by a list of locale-specific character class names +which are then to be defined in the locale. +.TP +.I toupper +followed by a list of mappings from lowercase to uppercase +letters. +Each mapping is a pair of a lowercase and an uppercase letter +separated with a +.B , +and enclosed in parentheses. +.TP +.I tolower +followed by a list of mappings from uppercase to lowercase +letters. +If the keyword tolower is not present, the reverse of the +toupper list is used. +.TP +.I map totitle +followed by a list of mapping pairs of +characters and letters +to be used in titles (headings). +.TP +.I class +followed by a locale-specific character class definition, +starting with the class name followed by the characters +belonging to the class. +.TP +.I charconv +followed by a list of locale-specific character mapping names +which are then to be defined in the locale. +.TP +.I outdigit +followed by a list of alternate output digits for the locale. +.TP +.I map to_inpunct +followed by a list of mapping pairs of +alternate digits and separators +for input digits for the locale. +.TP +.I map to_outpunct +followed by a list of mapping pairs of +alternate separators +for output for the locale. +.TP +.I translit_start +marks the start of the transliteration rules section. +The section can contain the +.I include +keyword in the beginning followed by +locale-specific rules and overrides. +Any rule specified in the locale file +will override any rule +copied or included from other files. +In case of duplicate rule definitions in the locale file, +only the first rule is used. +.IP +A transliteration rule consist of a character to be transliterated +followed by a list of transliteration targets separated by semicolons. +The first target which can be presented in the target character set +is used, if none of them can be used the +.I default_missing +character will be used instead. +.TP +.I include +in the transliteration rules section includes +a transliteration rule file +(and optionally a repertoire map file). +.TP +.I default_missing +in the transliteration rules section +defines the default character to be used for +transliteration where none of the targets cannot be presented +in the target character set. +.TP +.I translit_end +marks the end of the transliteration rules. +.PP +The +.B LC_CTYPE +definition ends with the string +.IR "END LC_CTYPE" . +.SS LC_COLLATE +Note that glibc does not support all POSIX-defined options, +only the options described below are supported (as of glibc 2.23). +.PP +The definition starts with the string +.I LC_COLLATE +in the first column. +.PP +The following keywords are allowed: +.TP +.I coll_weight_max +followed by the number representing used collation levels. +This keyword is recognized but ignored by glibc. +.TP +.I collating-element +followed by the definition of a collating-element symbol +representing a multicharacter collating element. +.TP +.I collating-symbol +followed by the definition of a collating symbol +that can be used in collation order statements. +.TP +.I define +followed by +.B string +to be evaluated in an +.I ifdef +.B string +/ +.I else +/ +.I endif +construct. +.TP +.I reorder-after +followed by a redefinition of a collation rule. +.TP +.I reorder-end +marks the end of the redefinition of a collation rule. +.TP +.I reorder-sections-after +followed by a script name to reorder listed scripts after. +.TP +.I reorder-sections-end +marks the end of the reordering of sections. +.TP +.I script +followed by a declaration of a script. +.TP +.I symbol-equivalence +followed by a collating-symbol to be equivalent to another defined +collating-symbol. +.PP +The collation rule definition starts with a line: +.TP +.I order_start +followed by a list of keywords chosen from +.BR forward , +.BR backward , +or +.BR position . +The order definition consists of lines that describe the collation +order and is terminated with the keyword +.IR order_end . +.PP +The +.B LC_COLLATE +definition ends with the string +.IR "END LC_COLLATE" . +.SS LC_IDENTIFICATION +The definition starts with the string +.I LC_IDENTIFICATION +in the first column. +.PP +The following keywords are allowed: +.TP +.I title +followed by the title of the locale document +(e.g., "Maori language locale for New Zealand"). +.TP +.I source +followed by the name of the organization that maintains this document. +.TP +.I address +followed by the address of the organization that maintains this document. +.TP +.I contact +followed by the name of the contact person at +the organization that maintains this document. +.TP +.I email +followed by the email address of the person or +organization that maintains this document. +.TP +.I tel +followed by the telephone number (in international format) +of the organization that maintains this document. +As of glibc 2.24, this keyword is deprecated in favor of +other contact methods. +.TP +.I fax +followed by the fax number (in international format) +of the organization that maintains this document. +As of glibc 2.24, this keyword is deprecated in favor of +other contact methods. +.TP +.I language +followed by the name of the language to which this document applies. +.TP +.I territory +followed by the name of the country/geographic extent +to which this document applies. +.TP +.I audience +followed by a description of the audience for which this document is +intended. +.TP +.I application +followed by a description of any special application +for which this document is intended. +.TP +.I abbreviation +followed by the short name for provider of the source of this document. +.TP +.I revision +followed by the revision number of this document. +.TP +.I date +followed by the revision date of this document. +.PP +In addition, for each of the categories defined by the document, +there should be a line starting with the keyword +.IR category , +followed by: +.IP * 3 +a string that identifies this locale category definition, +.IP * +a semicolon, and +.IP * +one of the +.BI LC_ * +identifiers. +.PP +The +.B LC_IDENTIFICATION +definition ends with the string +.IR "END LC_IDENTIFICATION" . +.SS LC_MESSAGES +The definition starts with the string +.I LC_MESSAGES +in the first column. +.PP +The following keywords are allowed: +.TP +.I yesexpr +followed by a regular expression that describes possible +yes-responses. +.TP +.I noexpr +followed by a regular expression that describes possible +no-responses. +.TP +.I yesstr +followed by the output string corresponding to "yes". +.TP +.I nostr +followed by the output string corresponding to "no". +.PP +The +.B LC_MESSAGES +definition ends with the string +.IR "END LC_MESSAGES" . +.SS LC_MEASUREMENT +The definition starts with the string +.I LC_MEASUREMENT +in the first column. +.PP +The following keywords are allowed: +.TP +.I measurement +followed by number identifying the standard used for measurement. +The following values are recognized: +.RS +.TP 4 +.B 1 +Metric. +.TP +.B 2 +US customary measurements. +.RE +.PP +The +.B LC_MEASUREMENT +definition ends with the string +.IR "END LC_MEASUREMENT" . +.SS LC_MONETARY +The definition starts with the string +.I LC_MONETARY +in the first column. +.PP +The following keywords are allowed: +.TP +.I int_curr_symbol +followed by the international currency symbol. +This must be a +4-character string containing the international currency symbol as +defined by the ISO 4217 standard (three characters) followed by a +separator. +.TP +.I currency_symbol +followed by the local currency symbol. +.TP +.I mon_decimal_point +followed by the string that will be used as the decimal delimiter +when formatting monetary quantities. +.TP +.I mon_thousands_sep +followed by the string that will be used as a group separator +when formatting monetary quantities. +.TP +.I mon_grouping +followed by a sequence of integers separated by semicolons that +describe the formatting of monetary quantities. +See +.I grouping +below for details. +.TP +.I positive_sign +followed by a string that is used to indicate a positive sign for +monetary quantities. +.TP +.I negative_sign +followed by a string that is used to indicate a negative sign for +monetary quantities. +.TP +.I int_frac_digits +followed by the number of fractional digits that should be used when +formatting with the +.IR int_curr_symbol . +.TP +.I frac_digits +followed by the number of fractional digits that should be used when +formatting with the +.IR currency_symbol . +.TP +.I p_cs_precedes +followed by an integer that indicates the placement of +.I currency_symbol +for a nonnegative formatted monetary quantity: +.RS +.TP 4 +.B 0 +the symbol succeeds the value. +.TP +.B 1 +the symbol precedes the value. +.RE +.TP +.I p_sep_by_space +followed by an integer that indicates the separation of +.IR currency_symbol , +the sign string, and the value for a nonnegative formatted monetary quantity. +The following values are recognized: +.RS +.TP 4 +.B 0 +No space separates the currency symbol and the value. +.TP +.B 1 +If the currency symbol and the sign string are adjacent, +a space separates them from the value; +otherwise a space separates the currency symbol and the value. +.TP +.B 2 +If the currency symbol and the sign string are adjacent, +a space separates them from the value; +otherwise a space separates the sign string and the value. +.RE +.TP +.I n_cs_precedes +followed by an integer that indicates the placement of +.I currency_symbol +for a negative formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I n_sep_by_space +followed by an integer that indicates the separation of +.IR currency_symbol , +the sign string, and the value for a negative formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I p_sign_posn +followed by an integer that indicates where the +.I positive_sign +should be placed for a nonnegative monetary quantity: +.RS +.TP 4 +.B 0 +Parentheses enclose the quantity and the +.I currency_symbol +or +.IR int_curr_symbol . +.TP +.B 1 +The sign string precedes the quantity and the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 2 +The sign string succeeds the quantity and the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 3 +The sign string precedes the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 4 +The sign string succeeds the +.I currency_symbol +or the +.IR int_curr_symbol . +.RE +.TP +.I n_sign_posn +followed by an integer that indicates where the +.I negative_sign +should be placed for a negative monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.TP +.I int_p_cs_precedes +followed by an integer that indicates the placement of +.I int_curr_symbol +for a nonnegative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I int_n_cs_precedes +followed by an integer that indicates the placement of +.I int_curr_symbol +for a negative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I int_p_sep_by_space +followed by an integer that indicates the separation of +.IR int_curr_symbol , +the sign string, +and the value for a nonnegative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I int_n_sep_by_space +followed by an integer that indicates the separation of +.IR int_curr_symbol , +the sign string, +and the value for a negative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I int_p_sign_posn +followed by an integer that indicates where the +.I positive_sign +should be placed for a nonnegative +internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.TP +.I int_n_sign_posn +followed by an integer that indicates where the +.I negative_sign +should be placed for a negative +internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.PP +The +.B LC_MONETARY +definition ends with the string +.IR "END LC_MONETARY" . +.SS LC_NAME +The definition starts with the string +.I LC_NAME +in the first column. +.PP +Various keywords are allowed, but only +.IR name_fmt +is mandatory. +Other keywords are needed only if there is common convention to +use the corresponding salutation in this locale. +The allowed keywords are as follows: +.TP +.I name_fmt +followed by a string containing field descriptors that define +the format used for names in the locale. +The following field descriptors are recognized: +.RS +.TP 4 +%f +Family name(s). +.TP +%F +Family names in uppercase. +.TP +%g +First given name. +.TP +%G +First given initial. +.TP +%l +First given name with Latin letters. +.TP +%o +Other shorter name. +.TP +%m +Additional given name(s). +.TP +%M +Initials for additional given name(s). +.TP +%p +Profession. +.TP +%s +Salutation, such as "Doctor". +.TP +%S +Abbreviated salutation, such as "Mr." or "Dr.". +.TP +%d +Salutation, using the FDCC-sets conventions. +.\" 1 for the name_gen +.\" In glibc 2.19, %d1 is used in only: +.\" /home/mtk/ARCHIVE/GLIBC/glibc-2.19/localedata/locales/bem_ZM +.\" /home/mtk/ARCHIVE/GLIBC/glibc-2.19/localedata/locales/zh_HK +.\" In glibc 2.19, %d[2-5] appear to be not used at all +.\" 2 for name_mr +.\" 3 for name_mrs +.\" 4 for name_miss +.\" 5 for name_ms +.TP +%t +If the preceding field descriptor resulted in an empty string, +then the empty string, otherwise a space character. +.RE +.TP +.I name_gen +followed by the general salutation for any gender. +.TP +.I name_mr +followed by the salutation for men. +.TP +.I name_mrs +followed by the salutation for married women. +.TP +.I name_miss +followed by the salutation for unmarried women. +.TP +.I name_ms +followed by the salutation valid for all women. +.PP +The +.B LC_NAME +definition ends with the string +.IR "END LC_NAME" . +.SS LC_NUMERIC +The definition starts with the string +.I LC_NUMERIC +in the first column. +.PP +The following keywords are allowed: +.TP +.I decimal_point +followed by the string that will be used as the decimal delimiter +when formatting numeric quantities. +.TP +.I thousands_sep +followed by the string that will be used as a group separator +when formatting numeric quantities. +.TP +.I grouping +followed by a sequence of integers separated by semicolons +that describe the formatting of numeric quantities. +.IP +Each integer specifies the number of digits in a group. +The first integer defines the size of the group immediately +to the left of the decimal delimiter. +Subsequent integers define succeeding groups to the +left of the previous group. +If the last integer is not \-1, then the size of the previous group +(if any) is repeatedly used for the remainder of the digits. +If the last integer is \-1, then no further grouping is performed. +.PP +The +.B LC_NUMERIC +definition ends with the string +.IR "END LC_NUMERIC" . +.SS LC_PAPER +The definition starts with the string +.I LC_PAPER +in the first column. +.PP +The following keywords are allowed: +.TP +.I height +followed by the height, in millimeters, of the standard paper format. +.TP +.I width +followed by the width, in millimeters, of the standard paper format. +.PP +The +.B LC_PAPER +definition ends with the string +.IR "END LC_PAPER" . +.SS LC_TELEPHONE +The definition starts with the string +.I LC_TELEPHONE +in the first column. +.PP +The following keywords are allowed: +.TP +.I tel_int_fmt +followed by a string that contains field descriptors that identify +the format used to dial international numbers. +The following field descriptors are recognized: +.RS +.TP 4 +%a +Area code without nationwide prefix (the prefix is often "00"). +.TP +%A +Area code including nationwide prefix. +.TP +%l +Local number (within area code). +.TP +%e +Extension (to local number). +.TP +%c +Country code. +.TP +%C +Alternate carrier service code used for dialing abroad. +.TP +%t +If the preceding field descriptor resulted in an empty string, +then the empty string, otherwise a space character. +.RE +.TP +.I tel_dom_fmt +followed by a string that contains field descriptors that identify +the format used to dial domestic numbers. +The recognized field descriptors are the same as for +.IR tel_int_fmt . +.TP +.I int_select +followed by the prefix used to call international phone numbers. +.TP +.I int_prefix +followed by the prefix used from other countries to dial this country. +.PP +The +.B LC_TELEPHONE +definition ends with the string +.IR "END LC_TELEPHONE" . +.SS LC_TIME +The definition starts with the string +.I LC_TIME +in the first column. +.PP +The following keywords are allowed: +.TP +.I abday +followed by a list of abbreviated names of the days of the week. +The list starts with the first day of the week +as specified by +.I week +(Sunday by default). +See NOTES. +.TP +.I day +followed by a list of names of the days of the week. +The list starts with the first day of the week +as specified by +.I week +(Sunday by default). +See NOTES. +.TP +.I abmon +followed by a list of abbreviated month names. +.TP +.I mon +followed by a list of month names. +.TP +.I d_t_fmt +followed by the appropriate date and time format +(for syntax, see +.BR strftime (3)). +.TP +.I d_fmt +followed by the appropriate date format +(for syntax, see +.BR strftime (3)). +.TP +.I t_fmt +followed by the appropriate time format +(for syntax, see +.BR strftime (3)). +.TP +.I am_pm +followed by the appropriate representation of the +.B am +and +.B pm +strings. +This should be left empty for locales not using AM/PM convention. +.TP +.I t_fmt_ampm +followed by the appropriate time format +(for syntax, see +.BR strftime (3)) +when using 12h clock format. +This should be left empty for locales not using AM/PM convention. +.TP +.I era +followed by semicolon-separated strings that define how years are +counted and displayed for each era in the locale. +Each string has the following format: +.RS +.PP +.IR direction ":" offset ":" start_date ":" end_date ":" era_name ":" era_format +.PP +The fields are to be defined as follows: +.PP +.TP 4 +.I direction +Either +.BR + +or +.BR -. +.BR + +means the years closer to +.IR start_date +have lower numbers than years closer to +.IR end_date . +.BR - +means the opposite. +.TP +.I offset +The number of the year closest to +.IR start_date +in the era, corresponding to the +.IR %Ey +descriptor (see +.BR strptime (3)). +.TP +.I start_date +The start of the era in the form of +.IR yyyy/mm/dd . +Years prior AD 1 are represented as negative numbers. +.TP +.I end_date +The end of the era in the form of +.IR yyyy/mm/dd , +or one of the two special values of +.BR -* +or +.BR +* . +.BR -* +means the ending date is the beginning of time. +.BR +* +means the ending date is the end of time. +.TP +.I era_name +The name of the era corresponding to the +.I %EC +descriptor (see +.BR strptime (3)). +.TP +.I era_format +The format of the year in the era corresponding to the +.I %EY +descriptor (see +.BR strptime (3)). +.RE +.TP +.I era_d_fmt +followed by the format of the date in alternative era notation, +corresponding to the +.I %Ex +descriptor (see +.BR strptime (3)). +.TP +.I era_t_fmt +followed by the format of the time in alternative era notation, +corresponding to the +.I %EX +descriptor (see +.BR strptime (3)). +.TP +.I era_d_t_fmt +followed by the format of the date and time in alternative era notation, +corresponding to the +.I %Ec +descriptor (see +.BR strptime (3)). +.TP +.I alt_digits +followed by the alternative digits used for date and time in the locale. +.TP +.I week +followed by a list of three values separated by semicolons: +The number of days in a week (by default 7), +a date of beginning of the week (by default corresponds to Sunday), +and the minimal length of the first week in year (by default 4). +Regarding the start of the week, +.B 19971130 +shall be used for Sunday and +.B 19971201 +shall be used for Monday. +See NOTES. +.TP +.IR first_weekday " (since glibc 2.2)" +followed by the number of the first day from the +.I day +list to be shown in calendar applications. +The default value of +.B 1 +corresponds to either Sunday or Monday depending +on the value of the second +.I week +list item. +See NOTES. +.TP +.IR first_workday " (since glibc 2.2)" +followed by the number of the first working day from the +.I day +list. +The default value is +.BR 2 . +See NOTES. +.TP +.I cal_direction +followed by a number value that indicates the direction for the +display of calendar dates, as follows: +.RS +.TP 4 +.B 1 +Left-right from top. +.TP +.B 2 +Top-down from left. +.TP +.B 3 +Right-left from top. +.RE +.TP +.I date_fmt +followed by the appropriate date representation for +.BR date (1) +(for syntax, see +.BR strftime (3)). +.PP +The +.B LC_TIME +definition ends with the string +.IR "END LC_TIME" . +.SH FILES +.TP +.I /usr/lib/locale/locale-archive +Usual default locale archive location. +.TP +.I /usr/share/i18n/locales +Usual default path for locale definition files. +.SH CONFORMING TO +POSIX.2. +.SH NOTES +The collective GNU C library community wisdom regarding +.IR abday , +.IR day , +.IR week , +.IR first_weekday , +and +.I first_workday +states at +https://sourceware.org/glibc/wiki/Locales +the following: +.IP * 3 +The value of the second +.I week +list item specifies the base of the +.I abday +and +.I day +lists. +.IP * +.I first_weekday +specifies the offset of the first day-of-week in the +.I abday +and +.I day +lists. +.IP * +For compatibility reasons, all glibc locales should set the value of the +second +.I week +list item to +.B 19971130 +(Sunday) and base the +.I abday +and +.I day +lists appropriately, and set +.I first_weekday +and +.I first_workday +to +.B 1 +or +.BR 2 , +depending on whether the week and work week actually starts on Sunday or +Monday for the locale. +.\" .SH AUTHOR +.\" Jochen Hein (Hein@Student.TU-Clausthal.de) +.SH SEE ALSO +.BR iconv (1), +.BR locale (1), +.BR localedef (1), +.BR localeconv (3), +.BR newlocale (3), +.BR setlocale (3), +.BR strftime (3), +.BR strptime (3), +.BR uselocale (3), +.BR charmap (5), +.BR charsets (7), +.BR locale (7), +.BR unicode (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/motd.5 b/man5/motd.5 new file mode 100644 index 0000000..ab5e3c7 --- /dev/null +++ b/man5/motd.5 @@ -0,0 +1,53 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:08:16 1993 by Rik Faith +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.TH MOTD 5 1992-12-29 "Linux" "Linux Programmer's Manual" +.SH NAME +motd \- message of the day +.SH DESCRIPTION +The contents of +.I /etc/motd +are displayed by +.BR login (1) +after a successful login but just before it executes the login shell. +.PP +The abbreviation "motd" stands for "message of the day", and this file +has been traditionally used for exactly that (it requires much less disk +space than mail to all users). +.SH FILES +.I /etc/motd +.SH SEE ALSO +.BR login (1), +.BR issue (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/networks.5 b/man5/networks.5 new file mode 100644 index 0000000..5cb9839 --- /dev/null +++ b/man5/networks.5 @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001 Martin Schulze +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2008-09-04, mtk, taken from Debian downstream, with a few light edits +.\" +.TH NETWORKS 5 2008-09-04 "GNU/Linux" "Linux System Administration" +.SH NAME +networks \- network name information +.SH DESCRIPTION +The file +.I /etc/networks +is a plain ASCII file that describes known DARPA networks and symbolic +names for these networks. +Each line represents a network and has the following structure: +.PP +.RS +.I name number aliases ... +.RE +.PP +where the fields are delimited by spaces or tabs. +Empty lines are ignored. +The hash character (\fB#\fP) indicates the start of a comment: +this character, and the remaining characters up to +the end of the current line, +are ignored by library functions that process the file. +.PP +The field descriptions are: +.TP +.I name +The symbolic name for the network. +Network names can contain any printable characters except +white-space characters or the comment character. +.TP +.I number +The official number for this network in numbers-and-dots notation (see +.BR inet (3)). +The trailing ".0" (for the host component of the network address) may be omitted. +.TP +.I aliases +Optional aliases for the network. +.PP +.PP +This file is read by the +.BR route (8) +and +.BR netstat (8) +utilities. +Only Class A, B or C networks are supported, partitioned networks +(i.e., network/26 or network/28) are not supported by this facility. +.SH FILES +.TP +.I /etc/networks +The networks definition file. +.SH SEE ALSO +.BR getnetbyaddr (3), +.BR getnetbyname (3), +.BR getnetent (3), +.BR netstat (8), +.BR route (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/nologin.5 b/man5/nologin.5 new file mode 100644 index 0000000..011fefa --- /dev/null +++ b/man5/nologin.5 @@ -0,0 +1,50 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sun Jul 25 11:06:34 1993 by Rik Faith (faith@cs.unc.edu) +.\" Corrected Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) +.TH NOLOGIN 5 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +nologin \- prevent unprivileged users from logging into the system +.SH DESCRIPTION +If the file \fI/etc/nologin\fP exists and is readable, +.BR login (1) +will allow access only to root. +Other users will +be shown the contents of this file and their logins will be refused. +This provides a simple way of temporarily disabling all unprivileged logins. +.SH FILES +.I /etc/nologin +.SH SEE ALSO +.BR login (1), +.BR shutdown (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5 new file mode 100644 index 0000000..e17595b --- /dev/null +++ b/man5/nscd.conf.5 @@ -0,0 +1,252 @@ +.\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of the +.\" License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH NSCD.CONF 5 2014-02-07 "GNU" "Linux Programmer's Manual" +.SH NAME +nscd.conf \- name service cache daemon configuration file +.SH DESCRIPTION +The file +.I /etc/nscd.conf +is read from +.BR nscd (8) +at startup. +Each line specifies either an attribute and a value, or an +attribute, service, and a value. +Fields are separated either by SPACE +or TAB characters. +A \(aq#\(aq (number sign) indicates the beginning of a +comment; following characters, up to the end of the line, +are not interpreted by nscd. +.PP +Valid services are \fIpasswd\fP, \fIgroup\fP, \fIhosts\fP, \fIservices\fP, +or \fInetgroup\fP. +.PP +.B logfile +.I debug-file-name +.RS +Specifies name of the file to which debug info should be written. +.RE +.PP +.B debug-level +.I value +.RS +Sets the desired debug level. +The default is 0. +.RE +.PP +.B threads +.I number +.RS +This is the number of threads that are started to wait for +requests. +At least five threads will always be created. +.RE +.PP +.B max-threads +.I number +.RS +Specifies the maximum number of threads. +The default is 32. +.RE +.PP +.B server-user +.I user +.RS +If this option is set, nscd will run as this user and not as root. +If a separate cache for every user is used (\-S parameter), this +option is ignored. +.RE +.PP +.B stat-user +.I user +.RS +Specifies the user who is allowed to request statistics. +.RE +.PP +.B reload-count +unlimited | +.I number +.RS +Limit on the number of times a cached entry gets reloaded without being used +before it gets removed. +The default is 5. +.RE +.PP +.B paranoia +.I +.RS +Enabling paranoia mode causes nscd to restart itself periodically. +The default is no. +.RE +.PP +.B restart-interval +.I time +.RS +Sets the restart interval to +.I time +seconds +if periodic restart is enabled by enabling +.B paranoia +mode. +The default is 3600. +.RE +.PP +.B enable-cache +.I service +.I +.RS +Enables or disables the specified +.I service +cache. +The default is no. +.RE +.PP +.B positive-time-to-live +.I service +.I value +.RS +Sets the TTL (time-to-live) for positive entries (successful queries) +in the specified cache for +.IR service . +.I Value +is in seconds. +Larger values increase cache hit rates and reduce mean +response times, but increase problems with cache coherence. +.RE +.PP +.B negative-time-to-live +.I service +.I value +.RS +Sets the TTL (time-to-live) for negative entries (unsuccessful queries) +in the specified cache for +.IR service . +.I Value +is in seconds. +Can result in significant performance improvements if there +are several files owned by UIDs (user IDs) not in system databases (for +example untarring the Linux kernel sources as root); should be kept small +to reduce cache coherency problems. +.RE +.PP +.B suggested-size +.I service +.I value +.RS +This is the internal hash table size, +.I value +should remain a prime number for optimum efficiency. +The default is 211. +.RE +.PP +.B check-files +.I service +.I +.RS +Enables or disables checking the file belonging to the specified +.I service +for changes. +The files are +.IR /etc/passwd , +.IR /etc/group , +.IR /etc/hosts , +.I /etc/services +and +.IR /etc/netgroup . +The default is yes. +.RE +.PP +.B persistent +.I service +.I +.RS +Keep the content of the cache for +.I service +over server restarts; useful when +.B paranoia +mode is set. +The default is no. +.RE +.PP +.B shared +.I service +.I +.RS +The memory mapping of the nscd databases for +.I service +is shared with the clients so +that they can directly search in them instead of having to ask the +daemon over the socket each time a lookup is performed. +The default is no. +.RE +.PP +.B max-db-size +.I service +.I bytes +.RS +The maximum allowable size, in bytes, of the database files for the +.IR service . +The default is 33554432. +.RE +.PP +.B auto-propagate +.I service +.I +.RS +When set to +.IR no +for +.I passwd +or +.I group +service, then the +.I .byname +requests are not added to +.IR passwd.byuid +or +.I group.bygid +cache. +This can help with tables containing multiple records for the same ID. +The default is yes. +This option is valid only for services +.IR passwd +and +.IR group . +.RE +.SH NOTES +The default values stated in this manual page originate +from the source code of +.BR nscd (8) +and are used if not overridden in the configuration file. +The default values used in the configuration file of +your distribution might differ. +.SH SEE ALSO +.BR nscd (8) +.\" .SH AUTHOR +.\" .B nscd +.\" was written by Thorsten Kukuk and Ulrich Drepper. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/nss.5 b/man5/nss.5 new file mode 100644 index 0000000..35776b9 --- /dev/null +++ b/man5/nss.5 @@ -0,0 +1,123 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All rights reserved. +.\" Author: Ulrich Drepper +.\" +.\" %%%LICENSE_START(GPLv2_MISC) +.\" This copyrighted material is made available to anyone wishing to use, +.\" modify, copy, or redistribute it subject to the terms and conditions of the +.\" GNU General Public License v.2. +.\" +.\" This program is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +.\" more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH NSS 5 2013-02-13 "Linux" "Linux Programmer's Manual" +.SH NAME +nss \- Name Service Switch configuration file +.SH DESCRIPTION +Each call to a function which retrieves data from a system database +like the password or group database is handled by the Name Service +Switch implementation in the GNU C library. +The various services +provided are implemented by independent modules, each of which +naturally varies widely from the other. +.PP +The default implementations coming with the GNU C library are by +default conservative and do not use unsafe data. +This might be very costly in some situations, especially when the databases +are large. +Some modules allow the system administrator to request +taking shortcuts if these are known to be safe. +It is then the system administrator's responsibility to ensure the assumption +is correct. +.PP +There are other modules where the implementation changed over time. +If an implementation used to sacrifice speed for memory consumption, +it might create problems if the preference is switched. +.PP +The +.I /etc/default/nss +file contains a number of variable assignments. +Each variable controls the behavior of one or more +NSS modules. +White spaces are ignored. +Lines beginning with \(aq#\(aq +are treated as comments. +.PP +The variables currently recognized are: +.TP +\fBNETID_AUTHORITATIVE =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR initgroups (3) +function will accept the information +from the +.I netid.byname +NIS map as authoritative. +This can speed up the function significantly if the +.I group.byname +map is large. +The content of the +.I netid.byname +map is used \fBas is\fR. +The system administrator has to make sure it is correctly generated. +.TP +\fBSERVICES_AUTHORITATIVE =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR getservbyname (3) +and +.BR getservbyname_r (3) +functions will assume that the +.I services.byservicename +NIS map exists and is authoritative, particularly +that it contains both keys with /proto and without /proto for both +primary service names and service aliases. +The system administrator has to make sure it is correctly generated. +.TP +\fBSETENT_BATCH_READ =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR setpwent (3) +and +.BR setgrent (3) +functions will read the entire database at once and then +hand out the requests one by one from memory with every corresponding +.BR getpwent (3) +or +.BR getgrent (3) +call respectively. +Otherwise, each +.BR getpwent (3) +or +.BR getgrent (3) +call might result in a network communication with the server to get +the next entry. +.SH FILES +\fI/etc/default/nss\fR +.SH EXAMPLE +The default configuration corresponds to the following configuration file: +.PP +.in +4n +.EX +NETID_AUTHORITATIVE=FALSE +SERVICES_AUTHORITATIVE=FALSE +SETENT_BATCH_READ=FALSE +.EE +.in +.\" .SH AUTHOR +.\" Ulrich Drepper +.\" +.SH SEE ALSO +\fInsswitch.conf\fR +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/nsswitch.conf.5 b/man5/nsswitch.conf.5 new file mode 100644 index 0000000..38ef64e --- /dev/null +++ b/man5/nsswitch.conf.5 @@ -0,0 +1,443 @@ +.\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de) +.\" Copyright (c) 2011, Mark R. Bannister +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH NSSWITCH.CONF 5 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +nsswitch.conf \- Name Service Switch configuration file +.SH DESCRIPTION +The Name Service Switch (NSS) configuration file, +.IR /etc/nsswitch.conf , +is used by the GNU C Library and certain other applications to determine +the sources from which to obtain name-service information in +a range of categories, +and in what order. +Each category of information is identified by a database name. +.PP +The file is plain ASCII text, with columns separated by spaces or tab +characters. +The first column specifies the database name. +The remaining columns describe the order of sources to query and a +limited set of actions that can be performed by lookup result. +.PP +The following databases are understood by the GNU C Library: +.TP 12 +.B aliases +Mail aliases, used by +.BR getaliasent (3) +and related functions. +.TP +.B ethers +Ethernet numbers. +.TP +.B group +Groups of users, used by +.BR getgrent (3) +and related functions. +.TP +.B hosts +Host names and numbers, used by +.BR gethostbyname (3) +and related functions. +.TP +.B initgroups +Supplementary group access list, used by +.BR getgrouplist (3) +function. +.TP +.B netgroup +Network-wide list of hosts and users, used for access rules. +C libraries before glibc 2.1 supported netgroups only over NIS. +.TP +.B networks +Network names and numbers, used by +.BR getnetent (3) +and related functions. +.TP +.B passwd +User passwords, used by +.BR getpwent (3) +and related functions. +.TP +.B protocols +Network protocols, used by +.BR getprotoent (3) +and related functions. +.TP +.B publickey +Public and secret keys for Secure_RPC used by NFS and NIS+. +.TP +.B rpc +Remote procedure call names and numbers, used by +.BR getrpcbyname (3) +and related functions. +.TP +.B services +Network services, used by +.BR getservent (3) +and related functions. +.TP +.B shadow +Shadow user passwords, used by +.BR getspnam (3) +and related functions. +.PP +The GNU C Library ignores databases with unknown names. Some +applications use this to implement special handling for their own +databases. For example, +.BR sudo (8) +consults the +.B sudoers +database. +.PP +Here is an example +.I /etc/nsswitch.conf +file: +.PP +.in +4n +.EX +passwd: compat +group: compat +shadow: compat + +hosts: dns [!UNAVAIL=return] files +networks: nis [NOTFOUND=return] files +ethers: nis [NOTFOUND=return] files +protocols: nis [NOTFOUND=return] files +rpc: nis [NOTFOUND=return] files +services: nis [NOTFOUND=return] files +.EE +.in +.PP +The first column is the database name. +The remaining columns specify: +.IP * 3 +One or more service specifications, for example, "files", "db", or "nis". +The order of the services on the line determines the order in which +those services will be queried, in turn, until a result is found. +.IP * +Optional actions to perform if a particular result is obtained +from the preceding service, for example, "[NOTFOUND=return]". +.PP +The service specifications supported on your system depend on the +presence of shared libraries, and are therefore extensible. +Libraries called +.IB /lib/libnss_SERVICE.so. X +will provide the named +.IR SERVICE . +On a standard installation, you can use +"files", "db", "nis", and "nisplus". +For the +.B hosts +database, you can additionally specify "dns". +For the +.BR passwd , +.BR group , +and +.BR shadow +databases, you can additionally specify +"compat" (see +.B "Compatibility mode" +below). +The version number +.B X +may be 1 for glibc 2.0, or 2 for glibc 2.1 and later. +On systems with additional libraries installed, you may have access to +further services such as "hesiod", "ldap", "winbind" and "wins". +.PP +An action may also be specified following a service specification. +The action modifies the behavior following a result obtained +from the preceding data source. +Action items take the general form: +.PP +.RS 4 +.RI [ STATUS = ACTION ] +.br +.RI [! STATUS = ACTION ] +.RE +.PP +where +.PP +.RS 4 +.I STATUS +=> +.B success +| +.B notfound +| +.B unavail +| +.B tryagain +.br +.I ACTION +=> +.B return +| +.B continue +| +.B merge +.RE +.PP +The ! negates the test, matching all possible results except the +one specified. +The case of the keywords is not significant. +.PP +The +.I STATUS +value is matched against the result of the lookup function called by +the preceding service specification, and can be one of: +.RS 4 +.TP 12 +.B success +No error occurred and the requested entry is returned. +The default action for this condition is "return". +.TP +.B notfound +The lookup succeeded, but the requested entry was not found. +The default action for this condition is "continue". +.TP +.B unavail +The service is permanently unavailable. +This can mean either that the +required file cannot be read, or, for network services, that the server +is not available or does not allow queries. +The default action for this condition is "continue". +.TP +.B tryagain +The service is temporarily unavailable. +This could mean a file is +locked or a server currently cannot accept more connections. +The default action for this condition is "continue". +.RE +.PP +The +.I ACTION +value can be one of: +.RS 4 +.TP 12 +.B return +Return a result now. +Do not call any further lookup functions. +However, for compatibility reasons, if this is the selected action for the +.B group +database and the +.B notfound +status, and the configuration file does not contain the +.B initgroups +line, the next lookup function is always called, +without affecting the search result. +.TP +.B continue +Call the next lookup function. +.TP +.B merge +.I [SUCCESS=merge] +is used between two database entries. +When a group is located in the first of the two group entries, +processing will continue on to the next one. +If the group is also found in the next entry (and the group name and GID +are an exact match), the member list of the second entry will be added +to the group object to be returned. +Available since glibc 2.24. +Note that merging will not be done for +.BR getgrent (3) +nor will duplicate members be pruned when they occur in both entries +being merged. +.RE +.SS Compatibility mode (compat) +The NSS "compat" service is similar to "files" except that it +additionally permits special entries in corresponding files +for granting users or members of netgroups access to the system. +The following entries are valid in this mode: +.RS 4 +.PP +For +.B passwd +and +.B shadow +databases: +.RS 4 +.TP 12 +.BI + user +Include the specified +.I user +from the NIS passwd/shadow map. +.TP +.BI +@ netgroup +Include all users in the given +.IR netgroup . +.TP +.BI \- user +Exclude the specified +.I user +from the NIS passwd/shadow map. +.TP +.BI \-@ netgroup +Exclude all users in the given +.IR netgroup . +.TP +.B + +Include every user, except previously excluded ones, from the +NIS passwd/shadow map. +.RE +.PP +For +.B group +database: +.RS 4 +.TP 12 +.BI + group +Include the specified +.I group +from the NIS group map. +.TP +.BI \- group +Exclude the specified +.I group +from the NIS group map. +.TP +.B + +Include every group, except previously excluded ones, from the +NIS group map. +.RE +.RE +.PP +By default, the source is "nis", but this may be +overridden by specifying any NSS service except "compat" itself +as the source for the pseudo-databases +.BR passwd_compat , +.BR group_compat , +and +.BR shadow_compat . +.SH FILES +A service named +.I SERVICE +is implemented by a shared object library named +.IB libnss_SERVICE.so. X +that resides in +.IR /lib . +.RS 4 +.TP 25 +.PD 0 +.I /etc/nsswitch.conf +NSS configuration file. +.TP +.IB /lib/libnss_compat.so. X +implements "compat" source. +.TP +.IB /lib/libnss_db.so. X +implements "db" source. +.TP +.IB /lib/libnss_dns.so. X +implements "dns" source. +.TP +.IB /lib/libnss_files.so. X +implements "files" source. +.TP +.IB /lib/libnss_hesiod.so. X +implements "hesiod" source. +.TP +.IB /lib/libnss_nis.so. X +implements "nis" source. +.TP +.IB /lib/libnss_nisplus.so. X +implements "nisplus" source. +.PD +.RE +.PP +The following files are read when "files" source is specified +for respective databases: +.RS 4 +.TP 12 +.PD 0 +.B aliases +.I /etc/aliases +.TP +.B ethers +.I /etc/ethers +.TP +.B group +.I /etc/group +.TP +.B hosts +.I /etc/hosts +.TP +.B initgroups +.I /etc/group +.TP +.B netgroup +.I /etc/netgroup +.TP +.B networks +.I /etc/networks +.TP +.B passwd +.I /etc/passwd +.TP +.B protocols +.I /etc/protocols +.TP +.B publickey +.I /etc/publickey +.TP +.B rpc +.I /etc/rpc +.TP +.B services +.I /etc/services +.TP +.B shadow +.I /etc/shadow +.PD +.RE +.SH NOTES +Within each process that uses +.BR nsswitch.conf , +the entire file is read only once. +If the file is later changed, the +process will continue using the old configuration. +.PP +Traditionally, there was only a single source for service information, +often in the form of a single configuration +file (e.g., \fI/etc/passwd\fP). +However, as other name services, such as the Network Information +Service (NIS) and the Domain Name Service (DNS), became popular, +a method was needed +that would be more flexible than fixed search orders coded into +the C library. +The Name Service Switch mechanism, +which was based on the mechanism used by +Sun Microsystems in the Solaris 2 C library, +introduced a cleaner solution to the problem. +.SH SEE ALSO +.BR getent (1), +.BR nss (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/numa_maps.5 b/man5/numa_maps.5 new file mode 100644 index 0000000..de68c0b --- /dev/null +++ b/man5/numa_maps.5 @@ -0,0 +1,5 @@ +.so man7/numa.7 +.\" As part of the numactl() package, the /proc/PID/numa_maps +.\" documentation was in a numa_maps.5 page; this link +.\" ensures that "man 5 numa_maps" still works. +.\" Eventually, we may want to remove it -- mtk, Aug 2008 diff --git a/man5/passwd.5 b/man5/passwd.5 new file mode 100644 index 0000000..1058b33 --- /dev/null +++ b/man5/passwd.5 @@ -0,0 +1,183 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sun Jul 25 10:46:28 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 21 18:12:27 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jun 18 01:53:57 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Jan 5 20:24:40 MET 1998 by Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de) +.TH PASSWD 5 2015-02-01 "Linux" "Linux Programmer's Manual" +.SH NAME +passwd \- password file +.SH DESCRIPTION +The +.IR /etc/passwd +file is a text file that describes user login accounts for the system. +It should have read permission allowed for all users (many utilities, like +.BR ls (1) +use it to map user IDs to usernames), but write access only for the +superuser. +.PP +In the good old days there was no great problem with this general +read permission. +Everybody could read the encrypted passwords, but the +hardware was too slow to crack a well-chosen password, and moreover the +basic assumption used to be that of a friendly user-community. +These days many people run some version of the shadow password suite, where +.I /etc/passwd +has an \(aqx\(aq character in the password field, +and the encrypted passwords are in +.IR /etc/shadow , +which is readable by the superuser only. +.PP +If the encrypted password, whether in +.I /etc/passwd +or in +.IR /etc/shadow , +is an empty string, login is allowed without even asking for a password. +Note that this functionality may be intentionally disabled in applications, +or configurable (for example using the "nullok" or "nonull" arguments to +pam_unix.so). +.PP +If the encrypted password in +.I /etc/passwd +is "\fI*NP*\fP" (without the quotes), +the shadow record should be obtained from an NIS+ server. +.PP +Regardless of whether shadow passwords are used, many system administrators +use an asterisk (*) in the encrypted password field to make sure +that this user can not authenticate him- or herself using a +password. +(But see NOTES below.) +.PP +If you create a new login, first put an asterisk (*) in the password field, +then use +.BR passwd (1) +to set it. +.PP +Each line of the file describes a single user, +and contains seven colon-separated fields: +.PP +.in +4n +.EX +name:password:UID:GID:GECOS:directory:shell +.EE +.in +.PP +The field are as follows: +.TP 12 +.I name +This is the user's login name. +It should not contain capital letters. +.TP +.I password +This is either the encrypted user password, +an asterisk (*), or the letter \(aqx\(aq. +(See +.BR pwconv (8) +for an explanation of \(aqx\(aq.) +.TP +.I UID +The privileged +.I root +login account (superuser) has the user ID 0. +.TP +.I GID +This is the numeric primary group ID for this user. +(Additional groups for the user are defined in the system group file; see +.BR group (5)). +.TP +.I GECOS +This field (sometimes called the "comment field") +is optional and used only for informational purposes. +Usually, it contains the full username. +Some programs (for example, +.BR finger (1)) +display information from this field. +.IP +GECOS stands for "General Electric Comprehensive Operating System", +which was renamed to GCOS when +GE's large systems division was sold to Honeywell. +Dennis Ritchie has reported: "Sometimes we sent printer output or +batch jobs to the GCOS machine. +The gcos field in the password file was a place to stash the +information for the $IDENTcard. +Not elegant." +.TP +.I directory +This is the user's home directory: +the initial directory where the user is placed after logging in. +The value in this field is used to set the +.B HOME +environment variable. +.TP +.I shell +This is the program to run at login (if empty, use +.IR /bin/sh ). +If set to a nonexistent executable, the user will be unable to login +through +.BR login (1). +The value in this field is used to set the +.B SHELL +environment variable. +.SH FILES +.I /etc/passwd +.SH NOTES +If you want to create user groups, there must be an entry in +.IR /etc/group , +or no group will exist. +.PP +If the encrypted password is set to an asterisk (*), the user will be unable +to login using +.BR login (1), +but may still login using +.BR rlogin (1), +run existing processes and initiate new ones through +.BR rsh (1), +.BR cron (8), +.BR at (1), +or mail filters, etc. +Trying to lock an account by simply changing the +shell field yields the same result and additionally allows the use of +.BR su (1). +.SH SEE ALSO +.BR chfn (1), +.BR chsh (1), +.BR login (1), +.BR passwd (1), +.BR su (1), +.BR crypt (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR group (5), +.BR shadow (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/proc.5 b/man5/proc.5 new file mode 100644 index 0000000..9ae9e02 --- /dev/null +++ b/man5/proc.5 @@ -0,0 +1,6431 @@ +.\" Copyright (C) 1994, 1995 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" and Copyright (C) 2002-2008,2017 Michael Kerrisk +.\" with networking additions from Alan Cox (A.Cox@swansea.ac.uk) +.\" and scsi additions from Michael Neuffer (neuffer@mail.uni-mainz.de) +.\" and sysctl additions from Andries Brouwer (aeb@cwi.nl) +.\" and System V IPC (as well as various other) additions from +.\" Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 1995-05-17 by faith@cs.unc.edu +.\" Minor changes by aeb and Marty Leisner (leisner@sdsp.mc.xerox.com). +.\" Modified 1996-04-13, 1996-07-22 by aeb@cwi.nl +.\" Modified 2001-12-16 by rwhron@earthlink.net +.\" Modified 2002-07-13 by jbelton@shaw.ca +.\" Modified 2002-07-22, 2003-05-27, 2004-04-06, 2004-05-25 +.\" by Michael Kerrisk +.\" 2004-11-17, mtk -- updated notes on /proc/loadavg +.\" 2004-12-01, mtk, rtsig-max and rtsig-nr went away in 2.6.8 +.\" 2004-12-14, mtk, updated 'statm', and fixed error in order of list +.\" 2005-05-12, mtk, updated 'stat' +.\" 2005-07-13, mtk, added /proc/sys/fs/mqueue/* +.\" 2005-09-16, mtk, Added /proc/sys/fs/suid_dumpable +.\" 2005-09-19, mtk, added /proc/zoneinfo +.\" 2005-03-01, mtk, moved /proc/sys/fs/mqueue/* material to mq_overview.7. +.\" 2008-06-05, mtk, Added /proc/[pid]/oom_score, /proc/[pid]/oom_adj, +.\" /proc/[pid]/limits, /proc/[pid]/mountinfo, /proc/[pid]/mountstats, +.\" and /proc/[pid]/fdinfo/*. +.\" 2008-06-19, mtk, Documented /proc/[pid]/status. +.\" 2008-07-15, mtk, added /proc/config.gz +.\" +.\" FIXME cross check against Documentation/filesystems/proc.txt +.\" to see what information could be imported from that file +.\" into this file. +.\" +.TH PROC 5 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +proc \- process information pseudo-filesystem +.SH DESCRIPTION +The +.B proc +filesystem is a pseudo-filesystem which provides an interface to +kernel data structures. +It is commonly mounted at +.IR /proc . +Typically, it is mounted automatically by the system, +but it can also be mounted manually using a command such as: +.PP +.in +4n +.EX +mount \-t proc proc /proc +.EE +.in +.PP +Most of the files in the +.B proc +filesystem are read-only, +but some files are writable, allowing kernel variables to be changed. +.\" +.SS Mount options +The +.B proc +filesystem supports the following mount options: +.TP +.BR hidepid "=\fIn\fP (since Linux 3.3)" +.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201 +This option controls who can access the information in +.IR /proc/[pid] +directories. +The argument, +.IR n , +is one of the following values: +.RS +.TP 4 +0 +Everybody may access all +.IR /proc/[pid] +directories. +This is the traditional behavior, +and the default if this mount option is not specified. +.TP +1 +Users may not access files and subdirectories inside any +.IR /proc/[pid] +directories but their own (the +.IR /proc/[pid] +directories themselves remain visible). +Sensitive files such as +.IR /proc/[pid]/cmdline +and +.IR /proc/[pid]/status +are now protected against other users. +This makes it impossible to learn whether any user is running a +specific program +(so long as the program doesn't otherwise reveal itself by its behavior). +.\" As an additional bonus, since +.\" .IR /proc/[pid]/cmdline +.\" is unaccessible for other users, +.\" poorly written programs passing sensitive information via +.\" program arguments are now protected against local eavesdroppers. +.TP +2 +As for mode 1, but in addition the +.IR /proc/[pid] +directories belonging to other users become invisible. +This means that +.IR /proc/[pid] +entries can no longer be used to discover the PIDs on the system. +This doesn't hide the fact that a process with a specific PID value exists +(it can be learned by other means, for example, by "kill \-0 $PID"), +but it hides a process's UID and GID, +which could otherwise be learned by employing +.BR stat (2) +on a +.IR /proc/[pid] +directory. +This greatly complicates an attacker's task of gathering +information about running processes (e.g., discovering whether +some daemon is running with elevated privileges, +whether another user is running some sensitive program, +whether other users are running any program at all, and so on). +.RE +.TP +.BR gid "=\fIgid\fP (since Linux 3.3)" +.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201 +Specifies the ID of a group whose members are authorized to +learn process information otherwise prohibited by +.BR hidepid +(i.e., users in this group behave as though +.I /proc +was mounted with +.IR hidepid=0 ). +This group should be used instead of approaches such as putting +nonroot users into the +.BR sudoers (5) +file. +.SS Files and directories +The following list describes many of the files and directories under the +.I /proc +hierarchy. +.TP +.I /proc/[pid] +There is a numerical subdirectory for each running process; the +subdirectory is named by the process ID. +.IP +Each +.I /proc/[pid] +subdirectory contains the +pseudo-files and directories described below. +These files are normally owned by the effective user and +effective group ID of the process. +However, as a security measure, the ownership is made +.IR root:root +if the process's "dumpable" attribute is set to a value other than 1. +This attribute may change for the following reasons: +.RS +.IP * 3 +The attribute was explicitly set via the +.BR prctl (2) +.B PR_SET_DUMPABLE +operation. +.IP * +The attribute was reset to the value in the file +.IR /proc/sys/fs/suid_dumpable +(described below), for the reasons described in +.BR prctl (2). +.RE +.IP +Resetting the "dumpable" attribute to 1 reverts the ownership of the +.IR /proc/[pid]/* +files to the process's real UID and real GID. +.TP +.I /proc/[pid]/attr +.\" https://lwn.net/Articles/28222/ +.\" From: Stephen Smalley +.\" To: LKML and others +.\" Subject: [RFC][PATCH] Process Attribute API for Security Modules +.\" Date: 08 Apr 2003 16:17:52 -0400 +.\" +.\" http://www.nsa.gov/research/_files/selinux/papers/module/x362.shtml +.\" +The files in this directory provide an API for security modules. +The contents of this directory are files that can be read and written +in order to set security-related attributes. +This directory was added to support SELinux, +but the intention was that the API be general enough to support +other security modules. +For the purpose of explanation, +examples of how SELinux uses these files are provided below. +.IP +This directory is present only if the kernel was configured with +.BR CONFIG_SECURITY . +.TP +.IR /proc/[pid]/attr/current " (since Linux 2.6.0)" +The contents of this file represent the current +security attributes of the process. +.IP +In SELinux, this file is used to get the security context of a process. +Prior to Linux 2.6.11, this file could not be used to set the security +context (a write was always denied), since SELinux limited process security +transitions to +.BR execve (2) +(see the description of +.IR /proc/[pid]/attr/exec , +below). +Since Linux 2.6.11, SELinux lifted this restriction and began supporting +"set" operations via writes to this node if authorized by policy, +although use of this operation is only suitable for applications that are +trusted to maintain any desired separation between the old and new security +contexts. +Prior to Linux 2.6.28, SELinux did not allow threads within a +multi-threaded process to set their security context via this node +as it would yield an inconsistency among the security contexts of the +threads sharing the same memory space. +Since Linux 2.6.28, SELinux lifted +this restriction and began supporting "set" operations for threads within +a multithreaded process if the new security context is bounded by the old +security context, where the bounded relation is defined in policy and +guarantees that the new security context has a subset of the permissions +of the old security context. +Other security modules may choose to support "set" operations via +writes to this node. +.TP +.IR /proc/[pid]/attr/exec " (since Linux 2.6.0)" +This file represents the attributes to assign to the +process upon a subsequent +.BR execve (2). +.IP +In SELinux, +this is needed to support role/domain transitions, and +.BR execve (2) +is the preferred point to make such transitions because it offers better +control over the initialization of the process in the new security label +and the inheritance of state. +In SELinux, this attribute is reset on +.BR execve (2) +so that the new program reverts to the default behavior for any +.BR execve (2) +calls that it may make. +In SELinux, a process can set +only its own +.I /proc/[pid]/attr/exec +attribute. +.TP +.IR /proc/[pid]/attr/fscreate " (since Linux 2.6.0)" +This file represents the attributes to assign to files +created by subsequent calls to +.BR open (2), +.BR mkdir (2), +.BR symlink (2), +and +.BR mknod (2) +.IP +SELinux employs this file to support creation of a file +(using the aforementioned system calls) +in a secure state, +so that there is no risk of inappropriate access being obtained +between the time of creation and the time that attributes are set. +In SELinux, this attribute is reset on +.BR execve (2), +so that the new program reverts to the default behavior for +any file creation calls it may make, but the attribute will persist +across multiple file creation calls within a program unless it is +explicitly reset. +In SELinux, a process can set only its own +.IR /proc/[pid]/attr/fscreate +attribute. +.TP +.IR /proc/[pid]/attr/keycreate " (since Linux 2.6.18)" +.\" commit 4eb582cf1fbd7b9e5f466e3718a59c957e75254e +If a process writes a security context into this file, +all subsequently created keys +.RB ( add_key (2)) +will be labeled with this context. +For further information, see the kernel source file +.I Documentation/security/keys/core.rst +(or file +.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 +.I Documentation/security/keys.txt +on Linux between 3.0 and 4.13, or +.\" commit d410fa4ef99112386de5f218dd7df7b4fca910b4 +.I Documentation/keys.txt +before Linux 3.0). +.TP +.IR /proc/[pid]/attr/prev " (since Linux 2.6.0)" +This file contains the security context of the process before the last +.BR execve (2); +that is, the previous value of +.IR /proc/[pid]/attr/current . +.TP +.IR /proc/[pid]/attr/socketcreate " (since Linux 2.6.18)" +.\" commit 42c3e03ef6b298813557cdb997bd6db619cd65a2 +If a process writes a security context into this file, +all subsequently created sockets will be labeled with this context. +.TP +.IR /proc/[pid]/autogroup " (since Linux 2.6.38)" +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +See +.BR sched (7). +.TP +.IR /proc/[pid]/auxv " (since 2.6.0-test7)" +This contains the contents of the ELF interpreter information passed +to the process at exec time. +The format is one \fIunsigned long\fP ID +plus one \fIunsigned long\fP value for each entry. +The last entry contains two zeros. +See also +.BR getauxval (3). +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.TP +.IR /proc/[pid]/cgroup " (since Linux 2.6.24)" +See +.BR cgroups (7). +.TP +.IR /proc/[pid]/clear_refs " (since Linux 2.6.22)" +.\" commit b813e931b4c8235bb42e301096ea97dbdee3e8fe (2.6.22) +.\" commit 398499d5f3613c47f2143b8c54a04efb5d7a6da9 (2.6.32) +.\" commit 040fa02077de01c7e08fa75be6125e4ca5636011 (3.11) +.\" +.\" "Clears page referenced bits shown in smaps output" +.\" write-only, writable only by the owner of the process +.IP +This is a write-only file, writable only by owner of the process. +.IP +The following values may be written to the file: +.RS +.TP +1 (since Linux 2.6.22) +.\" Internally: CLEAR_REFS_ALL +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all the pages associated with the process. +(Before kernel 2.6.32, writing any nonzero value to this file +had this effect.) +.TP +2 (since Linux 2.6.32) +.\" Internally: CLEAR_REFS_ANON +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all anonymous pages associated with the process. +.TP +3 (since Linux 2.6.32) +.\" Internally: CLEAR_REFS_MAPPED +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all file-mapped pages associated with the process. +.RE +.IP +Clearing the PG_Referenced and ACCESSED/YOUNG bits provides a method +to measure approximately how much memory a process is using. +One first inspects the values in the "Referenced" fields +for the VMAs shown in +.IR /proc/[pid]/smaps +to get an idea of the memory footprint of the +process. +One then clears the PG_Referenced and ACCESSED/YOUNG bits +and, after some measured time interval, +once again inspects the values in the "Referenced" fields +to get an idea of the change in memory footprint of the +process during the measured interval. +If one is interested only in inspecting the selected mapping types, +then the value 2 or 3 can be used instead of 1. +.IP +Further values can be written to affect different properties: +.RS +.TP +4 (since Linux 3.11) +Clear the soft-dirty bit for all the pages associated with the process. +.\" Internally: CLEAR_REFS_SOFT_DIRTY +This is used (in conjunction with +.IR /proc/[pid]/pagemap ) +by the check-point restore system to discover which pages of a process +have been dirtied since the file +.IR /proc/[pid]/clear_refs +was written to. +.TP +5 (since Linux 4.0) +.\" Internally: CLEAR_REFS_MM_HIWATER_RSS +Reset the peak resident set size ("high water mark") to the process's +current resident set size value. +.RE +.IP +Writing any value to +.IR /proc/[pid]/clear_refs +other than those listed above has no effect. +.IP +The +.IR /proc/[pid]/clear_refs +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.TP +.I /proc/[pid]/cmdline +This read-only file holds the complete command line for the process, +unless the process is a zombie. +.\" In 2.3.26, this also used to be true if the process was swapped out. +In the latter case, there is nothing in this file: +that is, a read on this file will return 0 characters. +The command-line arguments appear in this file as a set of +strings separated by null bytes (\(aq\\0\(aq), +with a further null byte after the last string. +.TP +.IR /proc/[pid]/comm " (since Linux 2.6.33)" +.\" commit 4614a696bd1c3a9af3a08f0e5874830a85b889d4 +This file exposes the process's +.I comm +value\(emthat is, the command name associated with the process. +Different threads in the same process may have different +.I comm +values, accessible via +.IR /proc/[pid]/task/[tid]/comm . +A thread may modify its +.I comm +value, or that of any of other thread in the same thread group (see +the discussion of +.B CLONE_THREAD +in +.BR clone (2)), +by writing to the file +.IR /proc/self/task/[tid]/comm . +Strings longer than +.B TASK_COMM_LEN +(16) characters are silently truncated. +.IP +This file provides a superset of the +.BR prctl (2) +.B PR_SET_NAME +and +.B PR_GET_NAME +operations, and is employed by +.BR pthread_setname_np (3) +when used to rename threads other than the caller. +.TP +.IR /proc/[pid]/coredump_filter " (since Linux 2.6.23)" +See +.BR core (5). +.TP +.IR /proc/[pid]/cpuset " (since Linux 2.6.12)" +.\" and/proc/[pid]/task/[tid]/cpuset +See +.BR cpuset (7). +.TP +.I /proc/[pid]/cwd +This is a symbolic link to the current working directory of the process. +To find out the current working directory of process 20, +for instance, you can do this: +.IP +.in +4n +.EX +.RB "$" " cd /proc/20/cwd; /bin/pwd" +.EE +.in +.IP +Note that the +.I pwd +command is often a shell built-in, and might +not work properly. +In +.BR bash (1), +you may use +.IR "pwd\ \-P" . +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.TP +.I /proc/[pid]/environ +This file contains the initial environment that was set +when the currently executing program was started via +.BR execve (2). +The entries are separated by null bytes (\(aq\\0\(aq), +and there may be a null byte at the end. +Thus, to print out the environment of process 1, you would do: +.IP +.in +4n +.EX +.RB "$" " strings /proc/1/environ" +.EE +.in +.IP +If, after an +.BR execve (2), +the process modifies its environment +(e.g., by calling functions such as +.BR putenv (3) +or modifying the +.BR environ (7) +variable directly), +this file will +.I not +reflect those changes. +.IP +Furthermore, a process may change the memory location that this file refers via +.BR prctl (2) +operations such as +.BR PR_SET_MM_ENV_START . +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.TP +.I /proc/[pid]/exe +Under Linux 2.2 and later, this file is a symbolic link +containing the actual pathname of the executed command. +This symbolic link can be dereferenced normally; attempting to open +it will open the executable. +You can even type +.I /proc/[pid]/exe +to run another copy of the same executable that is being run by +process [pid]. +If the pathname has been unlinked, the symbolic link will contain the +string \(aq(deleted)\(aq appended to the original pathname. +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Under Linux 2.0 and earlier, +.I /proc/[pid]/exe +is a pointer to the binary which was executed, +and appears as a symbolic link. +A +.BR readlink (2) +call on this file under Linux 2.0 returns a string in the format: +.IP + [device]:inode +.IP +For example, [0301]:1502 would be inode 1502 on device major 03 (IDE, +MFM, etc. drives) minor 01 (first partition on the first drive). +.IP +.BR find (1) +with the +.I \-inum +option can be used to locate the file. +.TP +.I /proc/[pid]/fd/ +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor, and which is a +symbolic link to the actual file. +Thus, 0 is standard input, 1 standard output, 2 standard error, and so on. +.IP +For file descriptors for pipes and sockets, +the entries will be symbolic links whose content is the +file type with the inode. +A +.BR readlink (2) +call on this file returns a string in the format: +.IP + type:[inode] +.IP +For example, +.I socket:[2248868] +will be a socket and its inode is 2248868. +For sockets, that inode can be used to find more information +in one of the files under +.IR /proc/net/ . +.IP +For file descriptors that have no corresponding inode +(e.g., file descriptors produced by +.BR bpf (2), +.BR epoll_create (2), +.BR eventfd (2), +.BR inotify_init (2), +.BR perf_event_open (2), +.BR signalfd (2), +.BR timerfd_create (2), +and +.BR userfaultfd (2)), +the entry will be a symbolic link with contents of the form +.IP + anon_inode: +.IP +In many cases (but not all), the +.I file-type +is surrounded by square brackets. +.IP +For example, an epoll file descriptor will have a symbolic link +whose content is the string +.IR "anon_inode:[eventpoll]" . +.IP +.\"The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this directory +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Programs that take a filename as a command-line argument, +but don't take input from standard input if no argument is supplied, +and programs that write to a file named as a command-line argument, +but don't send their output to standard output +if no argument is supplied, can nevertheless be made to use +standard input or standard output by using +.IR /proc/[pid]/fd +files as command-line arguments. +For example, assuming that +.I \-i +is the flag designating an input file and +.I \-o +is the flag designating an output file: +.IP +.in +4n +.EX +.RB "$" " foobar \-i /proc/self/fd/0 \-o /proc/self/fd/1 ..." +.EE +.in +.IP +and you have a working filter. +.\" The following is not true in my tests (MTK): +.\" Note that this will not work for +.\" programs that seek on their files, as the files in the fd directory +.\" are not seekable. +.IP +.I /proc/self/fd/N +is approximately the same as +.I /dev/fd/N +in some UNIX and UNIX-like systems. +Most Linux MAKEDEV scripts symbolically link +.I /dev/fd +to +.IR /proc/self/fd , +in fact. +.IP +Most systems provide symbolic links +.IR /dev/stdin , +.IR /dev/stdout , +and +.IR /dev/stderr , +which respectively link to the files +.IR 0 , +.IR 1 , +and +.IR 2 +in +.IR /proc/self/fd . +Thus the example command above could be written as: +.IP +.in +4n +.EX +.RB "$" " foobar \-i /dev/stdin \-o /dev/stdout ..." +.EE +.in +.IP +Permission to dereference or read +.RB ( readlink (2)) +the symbolic links in this directory is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Note that for file descriptors referring to inodes (pipes and sockets, see above), +those inodes still have permission bits and ownership information +distinct from those of the +.I /proc/[pid]/fd +entry, +and that the owner may differ from the user and group IDs of the process. +An unprivileged process may lack permissions to open them, as in this example: +.IP +.in +4n +.EX +.RB "$" " echo test | sudo -u nobody cat" +test +.RB "$" " echo test | sudo -u nobody cat /proc/self/fd/0" +cat: /proc/self/fd/0: Permission denied +.EE +.in +.IP +File descriptor 0 refers to the pipe created by the shell +and owned by that shell's user, which is not +.IR nobody , +so +.B cat +does not have permission to create a new file descriptor to read from that inode, +even though it can still read from its existing file descriptor 0. +.TP +.IR /proc/[pid]/fdinfo/ " (since Linux 2.6.22)" +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor. +The files in this directory are readable only by the owner of the process. +The contents of each file can be read to obtain information +about the corresponding file descriptor. +The content depends on the type of file referred to by the +corresponding file descriptor. +.IP +For regular files and directories, we see something like: +.IP +.in +4n +.EX +.RB "$" " cat /proc/12015/fdinfo/4" +pos: 1000 +flags: 01002002 +mnt_id: 21 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.I pos +This is a decimal number showing the file offset. +.TP +.I flags +This is an octal number that displays the +file access mode and file status flags (see +.BR open (2)). +If the close-on-exec file descriptor flag is set, then +.I flags +will also include the value +.BR O_CLOEXEC . +.IP +Before Linux 3.1, +.\" commit 1117f72ea0217ba0cc19f05adbbd8b9a397f5ab7 +this field incorrectly displayed the setting of +.B O_CLOEXEC +at the time the file was opened, +rather than the current setting of the close-on-exec flag. +.TP +.I +.I mnt_id +This field, present since Linux 3.15, +.\" commit 49d063cb353265c3af701bab215ac438ca7df36d +is the ID of the mount point containing this file. +See the description of +.IR /proc/[pid]/mountinfo . +.RE +.IP +For eventfd file descriptors (see +.BR eventfd (2)), +we see (since Linux 3.8) +.\" commit cbac5542d48127b546a23d816380a7926eee1c25 +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +eventfd-count: 40 +.EE +.in +.IP +.I eventfd-count +is the current value of the eventfd counter, in hexadecimal. +.IP +For epoll file descriptors (see +.BR epoll (7)), +we see (since Linux 3.8) +.\" commit 138d22b58696c506799f8de759804083ff9effae +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +tfd: 9 events: 19 data: 74253d2500000009 +tfd: 7 events: 19 data: 74253d2500000007 +.EE +.in +.IP +Each of the lines beginning +.I tfd +describes one of the file descriptors being monitored via +the epoll file descriptor (see +.BR epoll_ctl (2) +for some details). +The +.IR tfd +field is the number of the file descriptor. +The +.I events +field is a hexadecimal mask of the events being monitored for this file +descriptor. +The +.I data +field is the data value associated with this file descriptor. +.IP +For signalfd file descriptors (see +.BR signalfd (2)), +we see (since Linux 3.8) +.\" commit 138d22b58696c506799f8de759804083ff9effae +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +sigmask: 0000000000000006 +.EE +.in +.IP +.I sigmask +is the hexadecimal mask of signals that are accepted via this +signalfd file descriptor. +(In this example, bits 2 and 3 are set, corresponding to the signals +.B SIGINT +and +.BR SIGQUIT ; +see +.BR signal (7).) +.IP +For inotify file descriptors (see +.BR inotify (7)), +we see (since Linux 3.8) +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 00 +mnt_id: 11 +inotify wd:2 ino:7ef82a sdev:800001 mask:800afff ignored_mask:0 fhandle-bytes:8 fhandle-type:1 f_handle:2af87e00220ffd73 +inotify wd:1 ino:192627 sdev:800001 mask:800afff ignored_mask:0 fhandle-bytes:8 fhandle-type:1 f_handle:27261900802dfd73 +.EE +.in +.IP +Each of the lines beginning with "inotify" displays information about +one file or directory that is being monitored. +The fields in this line are as follows: +.RS +.TP +.I wd +A watch descriptor number (in decimal). +.TP +.I ino +The inode number of the target file (in hexadecimal). +.TP +.I sdev +The ID of the device where the target file resides (in hexadecimal). +.TP +.I mask +The mask of events being monitored for the target file (in hexadecimal). +.RE +.IP +If the kernel was built with exportfs support, the path to the target +file is exposed as a file handle, via three hexadecimal fields: +.IR fhandle-bytes , +.IR fhandle-type , +and +.IR f_handle . +.IP +For fanotify file descriptors (see +.BR fanotify (7)), +we see (since Linux 3.8) +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 11 +fanotify flags:0 event-flags:88002 +fanotify ino:19264f sdev:800001 mflags:0 mask:1 ignored_mask:0 fhandle-bytes:8 fhandle-type:1 f_handle:4f261900a82dfd73 +.EE +.in +.IP +The fourth line displays information defined when the fanotify group +was created via +.BR fanotify_init (2): +.RS +.TP +.I flags +The +.I flags +argument given to +.BR fanotify_init (2) +(expressed in hexadecimal). +.TP +.I event-flags +The +.I event_f_flags +argument given to +.BR fanotify_init (2) +(expressed in hexadecimal). +.RE +.IP +Each additional line shown in the file contains information +about one of the marks in the fanotify group. +Most of these fields are as for inotify, except: +.RS +.TP +.I mflags +The flags associated with the mark +(expressed in hexadecimal). +.TP +.I mask +The events mask for this mark +(expressed in hexadecimal). +.TP +.I ignored_mask +The mask of events that are ignored for this mark +(expressed in hexadecimal). +.RE +.IP +For details on these fields, see +.BR fanotify_mark (2). +.TP +.IR /proc/[pid]/gid_map " (since Linux 3.5)" +See +.BR user_namespaces (7). +.TP +.IR /proc/[pid]/io " (since kernel 2.6.20)" +.\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2 +This file contains I/O statistics for the process, for example: +.IP +.in +4n +.EX +.RB "#" " cat /proc/3828/io" +rchar: 323934931 +wchar: 323929600 +syscr: 632687 +syscw: 632675 +read_bytes: 0 +write_bytes: 323932160 +cancelled_write_bytes: 0 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.IR rchar ": characters read" +The number of bytes which this task has caused to be read from storage. +This is simply the sum of bytes which this process passed to +.BR read (2) +and similar system calls. +It includes things such as terminal I/O and +is unaffected by whether or not actual +physical disk I/O was required (the read might have been satisfied from +pagecache). +.TP +.IR wchar ": characters written" +The number of bytes which this task has caused, or shall cause to be written +to disk. +Similar caveats apply here as with +.IR rchar . +.TP +.IR syscr ": read syscalls" +Attempt to count the number of read I/O operations\(emthat is, +system calls such as +.BR read (2) +and +.BR pread (2). +.TP +.IR syscw ": write syscalls" +Attempt to count the number of write I/O operations\(emthat is, +system calls such as +.BR write (2) +and +.BR pwrite (2). +.TP +.IR read_bytes ": bytes read" +Attempt to count the number of bytes which this process really did cause to +be fetched from the storage layer. +This is accurate for block-backed filesystems. +.TP +.IR write_bytes ": bytes written" +Attempt to count the number of bytes which this process caused to be sent to +the storage layer. +.TP +.IR cancelled_write_bytes : +The big inaccuracy here is truncate. +If a process writes 1MB to a file and then deletes the file, +it will in fact perform no writeout. +But it will have been accounted as having caused 1MB of write. +In other words: this field represents the number of bytes which this process +caused to not happen, by truncating pagecache. +A task can cause "negative" I/O too. +If this task truncates some dirty pagecache, +some I/O which another task has been accounted for +(in its +.IR write_bytes ) +will not be happening. +.RE +.IP +.IR Note : +In the current implementation, things are a bit racy on 32-bit systems: +if process A reads process B's +.I /proc/[pid]/io +while process B is updating one of these 64-bit counters, +process A could see an intermediate result. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.TP +.IR /proc/[pid]/limits " (since Linux 2.6.24)" +This file displays the soft limit, hard limit, and units of measurement +for each of the process's resource limits (see +.BR getrlimit (2)). +Up to and including Linux 2.6.35, +this file is protected to allow reading only by the real UID of the process. +Since Linux 2.6.36, +.\" commit 3036e7b490bf7878c6dae952eec5fb87b1106589 +this file is readable by all users on the system. +.\" FIXME Describe /proc/[pid]/loginuid +.\" Added in 2.6.11; updating requires CAP_AUDIT_CONTROL +.\" CONFIG_AUDITSYSCALL +.TP +.IR /proc/[pid]/map_files/ " (since kernel 3.3) +.\" commit 640708a2cff7f81e246243b0073c66e6ece7e53e +This subdirectory contains entries corresponding to memory-mapped +files (see +.BR mmap (2)). +Entries are named by memory region start and end +address pair (expressed as hexadecimal numbers), +and are symbolic links to the mapped files themselves. +Here is an example, with the output wrapped and reformatted to fit on an 80-column display: +.IP +.in +4n +.EX +.RB "#" " ls -l /proc/self/map_files/" +lr\-\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:31 + 3252e00000\-3252e20000 \-> /usr/lib64/ld\-2.15.so +\&... +.EE +.in +.IP +Although these entries are present for memory regions that were +mapped with the +.BR MAP_FILE +flag, the way anonymous shared memory (regions created with the +.B MAP_ANON | MAP_SHARED +flags) +is implemented in Linux +means that such regions also appear on this directory. +Here is an example where the target file is the deleted +.I /dev/zero +one: +.IP +.in +4n +.EX +lrw\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:33 + 7fc075d2f000\-7fc075e6f000 \-> /dev/zero (deleted) +.EE +.in +.IP +This directory appears only if the +.B CONFIG_CHECKPOINT_RESTORE +kernel configuration option is enabled. +Privilege +.RB ( CAP_SYS_ADMIN ) +.\" FIXME +.\" This may change. See the mail thread +.\" "[RFC][PATCH v2] procfs: Always expose /proc//map_files/ and make it readable" +.\" from Jan 2015 +is required to view the contents of this directory. +.TP +.I /proc/[pid]/maps +A file containing the currently mapped memory regions and their access +permissions. +See +.BR mmap (2) +for some further information about memory mappings. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +The format of the file is: +.IP +.in 4n +.EX +.I "address perms offset dev inode pathname" +00400000\-00452000 r-xp 00000000 08:02 173521 /usr/bin/dbus-daemon +00651000\-00652000 r--p 00051000 08:02 173521 /usr/bin/dbus-daemon +00652000\-00655000 rw-p 00052000 08:02 173521 /usr/bin/dbus-daemon +00e03000\-00e24000 rw-p 00000000 00:00 0 [heap] +00e24000\-011f7000 rw-p 00000000 00:00 0 [heap] +\&... +35b1800000\-35b1820000 r-xp 00000000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a1f000\-35b1a20000 r--p 0001f000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a20000\-35b1a21000 rw-p 00020000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a21000\-35b1a22000 rw-p 00000000 00:00 0 +35b1c00000\-35b1dac000 r-xp 00000000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1dac000\-35b1fac000 ---p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1fac000\-35b1fb0000 r--p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1fb0000\-35b1fb2000 rw-p 001b0000 08:02 135870 /usr/lib64/libc\-2.15.so +\&... +f2c6ff8c000\-7f2c7078c000 rw-p 00000000 00:00 0 [stack:986] +\&... +7fffb2c0d000\-7fffb2c2e000 rw-p 00000000 00:00 0 [stack] +7fffb2d48000\-7fffb2d49000 r-xp 00000000 00:00 0 [vdso] +.EE +.in +.IP +The +.I address +field is the address space in the process that the mapping occupies. +The +.I perms +field is a set of permissions: +.IP +.in +4 +.EX +r = read +w = write +x = execute +s = shared +p = private (copy on write) +.EE +.in +.IP +The +.I offset +field is the offset into the file/whatever; +.I dev +is the device +(major:minor); +.I inode +is the inode on that device. +0 indicates that no inode is associated with the memory region, +as would be the case with BSS (uninitialized data). +.IP +The +.I pathname +field will usually be the file that is backing the mapping. +For ELF files, +you can easily coordinate with the +.I offset +field by looking at the +Offset field in the ELF program headers +.RI ( "readelf\ \-l" ). +.IP +There are additional helpful pseudo-paths: +.RS 12 +.TP +.IR [stack] +The initial process's (also known as the main thread's) stack. +.TP +.IR [stack:] " (since Linux 3.4)" +.\" commit b76437579d1344b612cf1851ae610c636cec7db0 +A thread's stack (where the +.IR +is a thread ID). +It corresponds to the +.IR /proc/[pid]/task/[tid]/ +path. +.TP +.IR [vdso] +The virtual dynamically linked shared object. +See +.BR vdso (7). +.TP +.IR [heap] +The process's heap. +.in +.RE +.IP +If the +.I pathname +field is blank, +this is an anonymous mapping as obtained via +.BR mmap (2). +There is no easy way to coordinate this back to a process's source, +short of running it through +.BR gdb (1), +.BR strace (1), +or similar. +.IP +Under Linux 2.0, there is no field giving pathname. +.TP +.I /proc/[pid]/mem +This file can be used to access the pages of a process's memory through +.BR open (2), +.BR read (2), +and +.BR lseek (2). +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.TP +.IR /proc/[pid]/mountinfo " (since Linux 2.6.26)" +.\" This info adapted from Documentation/filesystems/proc.txt +.\" commit 2d4d4864ac08caff5c204a752bd004eed4f08760 +This file contains information about mount points +in the process's mount namespace (see +.BR mount_namespaces (7)). +It supplies various information +(e.g., propagation state, root of mount for bind mounts, +identifier for each mount and its parent) that is missing from the (older) +.IR /proc/[pid]/mounts +file, and fixes various other problems with that file +(e.g., nonextensibility, +failure to distinguish per-mount versus per-superblock options). +.IP +The file contains lines of the form: +.IP +.in 0n +.EX +36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 \- ext3 /dev/root rw,errors=continue +(1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11) +.in +.EE +.IP +The numbers in parentheses are labels for the descriptions below: +.RS 7 +.TP 5 +(1) +mount ID: a unique ID for the mount (may be reused after +.BR umount (2)). +.TP +(2) +parent ID: the ID of the parent mount +(or of self for the root of this mount namespace's mount tree). +.IP +If the parent mount point lies outside the process's root directory (see +.BR chroot (2)), +the ID shown here won't have a corresponding record in +.I mountinfo +whose mount ID (field 1) matches this parent mount ID +(because mount points that lie outside the process's root directory +are not shown in +.IR mountinfo ). +As a special case of this point, +the process's root mount point may have a parent mount +(for the initramfs filesystem) that lies +.\" Miklos Szeredi, Nov 2017: The hidden one is the initramfs, I believe +.\" mtk: In the initial mount namespace, this hidden ID has the value 0 +outside the process's root directory, +and an entry for that mount point will not appear in +.IR mountinfo . +.TP +(3) +major:minor: the value of +.I st_dev +for files on this filesystem (see +.BR stat (2)). +.TP +(4) +root: the pathname of the directory in the filesystem +which forms the root of this mount. +.TP +(5) +mount point: the pathname of the mount point relative +to the process's root directory. +.TP +(6) +mount options: per-mount options. +.TP +(7) +optional fields: zero or more fields of the form "tag[:value]"; see below. +.TP +(8) +separator: the end of the optional fields is marked by a single hyphen. +.TP +(9) +filesystem type: the filesystem type in the form "type[.subtype]". +.TP +(10) +mount source: filesystem-specific information or "none". +.TP +(11) +super options: per-superblock options. +.RE +.IP +Currently, the possible optional fields are +.IR shared , +.IR master , +.IR propagate_from , +and +.IR unbindable . +See +.BR mount_namespaces (7) +for a description of these fields. +Parsers should ignore all unrecognized optional fields. +.IP +For more information on mount propagation see: +.I Documentation/filesystems/sharedsubtree.txt +in the Linux kernel source tree. +.TP +.IR /proc/[pid]/mounts " (since Linux 2.4.19)" +This file lists all the filesystems currently mounted in the +process's mount namespace (see +.BR mount_namespaces (7)). +The format of this file is documented in +.BR fstab (5). +.IP +Since kernel version 2.6.15, this file is pollable: +after opening the file for reading, a change in this file +(i.e., a filesystem mount or unmount) causes +.BR select (2) +to mark the file descriptor as having an exceptional condition, and +.BR poll (2) +and +.BR epoll_wait (2) +mark the file as having a priority event +.RB ( POLLPRI ). +(Before Linux 2.6.30, +a change in this file was indicated by the file descriptor +being marked as readable for +.BR select (2), +and being marked as having an error condition for +.BR poll (2) +and +.BR epoll_wait (2).) +.TP +.IR /proc/[pid]/mountstats " (since Linux 2.6.17)" +This file exports information (statistics, configuration information) +about the mount points in the process's mount namespace (see +.BR mount_namespaces (7)). +Lines in this file have the form: +.IP +.in +4n +.EX +device /dev/sda7 mounted on /home with fstype ext3 [statistics] +( 1 ) ( 2 ) (3 ) (4) +.EE +.in +.IP +The fields in each line are: +.RS 7 +.TP 5 +(1) +The name of the mounted device +(or "nodevice" if there is no corresponding device). +.TP +(2) +The mount point within the filesystem tree. +.TP +(3) +The filesystem type. +.TP +(4) +Optional statistics and configuration information. +Currently (as at Linux 2.6.26), only NFS filesystems export +information via this field. +.RE +.IP +This file is readable only by the owner of the process. +.TP +.IR /proc/[pid]/net " (since Linux 2.6.25)" +See the description of +.IR /proc/net . +.TP +.IR /proc/[pid]/ns/ " (since Linux 3.0)" +.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f +This is a subdirectory containing one entry for each namespace that +supports being manipulated by +.BR setns (2). +For more information, see +.BR namespaces (7). +.TP +.IR /proc/[pid]/numa_maps " (since Linux 2.6.14)" +See +.BR numa (7). +.TP +.IR /proc/[pid]/oom_adj " (since Linux 2.6.11)" +This file can be used to adjust the score used to select which process +should be killed in an out-of-memory (OOM) situation. +The kernel uses this value for a bit-shift operation of the process's +.IR oom_score +value: +valid values are in the range \-16 to +15, +plus the special value \-17, +which disables OOM-killing altogether for this process. +A positive score increases the likelihood of this +process being killed by the OOM-killer; +a negative score decreases the likelihood. +.IP +The default value for this file is 0; +a new process inherits its parent's +.I oom_adj +setting. +A process must be privileged +.RB ( CAP_SYS_RESOURCE ) +to update this file. +.IP +Since Linux 2.6.36, use of this file is deprecated in favor of +.IR /proc/[pid]/oom_score_adj . +.TP +.IR /proc/[pid]/oom_score " (since Linux 2.6.11)" +.\" See mm/oom_kill.c::badness() in pre 2.6.36 sources +.\" See mm/oom_kill.c::oom_badness() after 2.6.36 +.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 +This file displays the current score that the kernel gives to +this process for the purpose of selecting a process +for the OOM-killer. +A higher score means that the process is more likely to be +selected by the OOM-killer. +The basis for this score is the amount of memory used by the process, +with increases (+) or decreases (\-) for factors including: +.\" See mm/oom_kill.c::badness() in pre 2.6.36 sources +.\" See mm/oom_kill.c::oom_badness() after 2.6.36 +.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 +.RS +.IP * 2 +whether the process is privileged (\-). +.\" More precisely, if it has CAP_SYS_ADMIN or (pre 2.6.36) CAP_SYS_RESOURCE +.RE +.IP +Before kernel 2.6.36 the following factors were also used in the calculation of oom_score: +.RS +.IP * 2 +whether the process creates a lot of children using +.BR fork (2) +(+); +.IP * +whether the process has been running a long time, +or has used a lot of CPU time (\-); +.IP * +whether the process has a low nice value (i.e., > 0) (+); and +.IP * +whether the process is making direct hardware access (\-). +.\" More precisely, if it has CAP_SYS_RAWIO +.RE +.IP +The +.I oom_score +also reflects the adjustment specified by the +.I oom_score_adj +or +.I oom_adj +setting for the process. +.TP +.IR /proc/[pid]/oom_score_adj " (since Linux 2.6.36)" +.\" Text taken from 3.7 Documentation/filesystems/proc.txt +This file can be used to adjust the badness heuristic used to select which +process gets killed in out-of-memory conditions. +.IP +The badness heuristic assigns a value to each candidate task ranging from 0 +(never kill) to 1000 (always kill) to determine which process is targeted. +The units are roughly a proportion along that range of +allowed memory the process may allocate from, +based on an estimation of its current memory and swap use. +For example, if a task is using all allowed memory, +its badness score will be 1000. +If it is using half of its allowed memory, its score will be 500. +.IP +There is an additional factor included in the badness score: root +processes are given 3% extra memory over other tasks. +.IP +The amount of "allowed" memory depends on the context +in which the OOM-killer was called. +If it is due to the memory assigned to the allocating task's cpuset +being exhausted, +the allowed memory represents the set of mems assigned to that +cpuset (see +.BR cpuset (7)). +If it is due to a mempolicy's node(s) being exhausted, +the allowed memory represents the set of mempolicy nodes. +If it is due to a memory limit (or swap limit) being reached, +the allowed memory is that configured limit. +Finally, if it is due to the entire system being out of memory, the +allowed memory represents all allocatable resources. +.IP +The value of +.I oom_score_adj +is added to the badness score before it +is used to determine which task to kill. +Acceptable values range from \-1000 +(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX). +This allows user space to control the preference for OOM-killing, +ranging from always preferring a certain +task or completely disabling it from OOM killing. +The lowest possible value, \-1000, is +equivalent to disabling OOM-killing entirely for that task, +since it will always report a badness score of 0. +.IP +Consequently, it is very simple for user space to define +the amount of memory to consider for each task. +Setting an +.I oom_score_adj +value of +500, for example, +is roughly equivalent to allowing the remainder of tasks sharing the +same system, cpuset, mempolicy, or memory controller resources +to use at least 50% more memory. +A value of \-500, on the other hand, would be roughly +equivalent to discounting 50% of the task's +allowed memory from being considered as scoring against the task. +.IP +For backward compatibility with previous kernels, +.I /proc/[pid]/oom_adj +can still be used to tune the badness score. +Its value is +scaled linearly with +.IR oom_score_adj . +.IP +Writing to +.IR /proc/[pid]/oom_score_adj +or +.IR /proc/[pid]/oom_adj +will change the other with its scaled value. +.TP +.IR /proc/[pid]/pagemap " (since Linux 2.6.25)" +This file shows the mapping of each of the process's virtual pages +into physical page frames or swap area. +It contains one 64-bit value for each virtual page, +with the bits set as follows: +.RS 12 +.TP +63 +If set, the page is present in RAM. +.TP +62 +If set, the page is in swap space +.TP +61 (since Linux 3.5) +The page is a file-mapped page or a shared anonymous page. +.TP +60\(en57 (since Linux 3.11) +Zero +.\" Not quite true; see commit 541c237c0923f567c9c4cabb8a81635baadc713f +.TP +56 (since Linux 4.2) +.\" commit 77bb499bb60f4b79cca7d139c8041662860fcf87 +.\" commit 83b4b0bb635eee2b8e075062e4e008d1bc110ed7 +The page is exclusively mapped. +.TP +55 (since Linux 3.11) +PTE is soft-dirty +(see the kernel source file +.IR Documentation/vm/soft-dirty.txt ). +.TP +54\(en0 +If the page is present in RAM (bit 63), then these bits +provide the page frame number, which can be used to index +.IR /proc/kpageflags +and +.IR /proc/kpagecount . +If the page is present in swap (bit 62), +then bits 4\(en0 give the swap type, and bits 54\(en5 encode the swap offset. +.RE +.IP +Before Linux 3.11, bits 60\(en55 were +used to encode the base-2 log of the page size. +.IP +To employ +.IR /proc/[pid]/pagemap +efficiently, use +.IR /proc/[pid]/maps +to determine which areas of memory are actually mapped and seek +to skip over unmapped regions. +.IP +The +.IR /proc/[pid]/pagemap +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.TP +.IR /proc/[pid]/personality " (since Linux 2.6.28)" +.\" commit 478307230810d7e2a753ed220db9066dfdf88718 +This read-only file exposes the process's execution domain, as set by +.BR personality (2). +The value is displayed in hexadecimal notation. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.TP +.I /proc/[pid]/root +UNIX and Linux support the idea of a per-process root of the +filesystem, set by the +.BR chroot (2) +system call. +This file is a symbolic link that points to the process's +root directory, and behaves in the same way as +.IR exe , +and +.IR fd/* . +.IP +Note however that this file is not merely a symbolic link. +It provides the same view of the filesystem (including namespaces and the +set of per-process mounts) as the process itself. +An example illustrates this point. +In one terminal, we start a shell in new user and mount namespaces, +and in that shell we create some new mount points: +.IP +.in +4n +.EX +$ \fBPS1='sh1# ' unshare \-Urnm\fP +sh1# \fBmount \-t tmpfs tmpfs /etc\fP # Mount empty tmpfs at /etc +sh1# \fBmount \-\-bind /usr /dev\fP # Mount /usr at /dev +sh1# \fBecho $$\fP +27123 +.EE +.in +.IP +In a second terminal window, in the initial mount namespace, +we look at the contents of the corresponding mounts in +the initial and new namespaces: +.IP +.in +4n +.EX +$ \fBPS1='sh2# ' sudo sh\fP +sh2# \fBls /etc | wc \-l\fP # In initial NS +309 +sh2# \fBls /proc/27123/root/etc | wc \-l\fP # /etc in other NS +0 # The empty tmpfs dir +sh2# \fBls /dev | wc \-l\fP # In initial NS +205 +sh2# \fBls /proc/27123/root/dev | wc \-l\fP # /dev in other NS +11 # Actually bind + # mounted to /usr +sh2# \fBls /usr | wc \-l\fP # /usr in initial NS +11 +.EE +.in +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of the +.I /proc/[pid]/root +symbolic link are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.\" FIXME Describe /proc/[pid]/projid_map +.\" Added in 3.7 +.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d +.TP +.IR /proc/[pid]/seccomp " (Linux 2.6.12 to 2.6.22)" +This file can be used to read and change the process's +secure computing (seccomp) mode setting. +It contains the value 0 if the process is not in seccomp mode, +and 1 if the process is in strict seccomp mode (see +.BR seccomp (2)). +Writing 1 to this file places the process irreversibly in strict seccomp mode. +(Further attempts to write to the file fail with the +.B EPERM +error.) +.IP +In Linux 2.6.23, +this file went away, to be replaced by the +.BR prctl (2) +.BR PR_GET_SECCOMP +and +.BR PR_SET_SECCOMP +operations (and later by +.BR seccomp (2) +and the +.I Seccomp +field in +.IR /proc/[pid]/status ). +.\" FIXME Describe /proc/[pid]/sessionid +.\" commit 1e0bd7550ea9cf474b1ad4c6ff5729a507f75fdc +.\" CONFIG_AUDITSYSCALL +.\" Added in 2.6.25; read-only; only readable by real UID +.\" +.\" FIXME Describe /proc/[pid]/sched +.\" Added in 2.6.23 +.\" CONFIG_SCHED_DEBUG, and additional fields if CONFIG_SCHEDSTATS +.\" Displays various scheduling parameters +.\" This file can be written, to reset stats +.\" The set of fields exposed by this file have changed +.\" significantly over time. +.\" commit 43ae34cb4cd650d1eb4460a8253a8e747ba052ac +.\" +.\" FIXME Describe /proc/[pid]/schedstats and +.\" /proc/[pid]/task/[tid]/schedstats +.\" Added in 2.6.9 +.\" CONFIG_SCHEDSTATS +.TP +.IR /proc/[pid]/setgroups " (since Linux 3.19)" +See +.BR user_namespaces (7). +.TP +.IR /proc/[pid]/smaps " (since Linux 2.6.14)" +This file shows memory consumption for each of the process's mappings. +(The +.BR pmap (1) +command displays similar information, +in a form that may be easier for parsing.) +For each mapping there is a series of lines such as the following: +.IP +.in +4n +.EX +00400000\-0048a000 r\-xp 00000000 fd:03 960637 /bin/bash +Size: 552 kB +Rss: 460 kB +Pss: 100 kB +Shared_Clean: 452 kB +Shared_Dirty: 0 kB +Private_Clean: 8 kB +Private_Dirty: 0 kB +Referenced: 460 kB +Anonymous: 0 kB +AnonHugePages: 0 kB +ShmemHugePages: 0 kB +ShmemPmdMapped: 0 kB +Swap: 0 kB +KernelPageSize: 4 kB +MMUPageSize: 4 kB +KernelPageSize: 4 kB +MMUPageSize: 4 kB +Locked: 0 kB +ProtectionKey: 0 +VmFlags: rd ex mr mw me dw +.EE +.in +.IP +The first of these lines shows the same information as is displayed +for the mapping in +.IR /proc/[pid]/maps . +The following lines show the size of the mapping, +the amount of the mapping that is currently resident in RAM ("Rss"), +the process's proportional share of this mapping ("Pss"), +the number of clean and dirty shared pages in the mapping, +and the number of clean and dirty private pages in the mapping. +"Referenced" indicates the amount of memory currently marked as +referenced or accessed. +"Anonymous" shows the amount of memory +that does not belong to any file. +"Swap" shows how much +would-be-anonymous memory is also used, but out on swap. +.IP +The "KernelPageSize" line (available since Linux 2.6.29) +is the page size used by the kernel to back the virtual memory area. +This matches the size used by the MMU in the majority of cases. +However, one counter-example occurs on PPC64 kernels +whereby a kernel using 64kB as a base page size may still use 4kB +pages for the MMU on older processors. +To distinguish the two attributes, the "MMUPageSize" line +(also available since Linux 2.6.29) +reports the page size used by the MMU. +.IP +The "Locked" indicates whether the mapping is locked in memory +or not. +.IP +The "ProtectionKey" line (available since Linux 4.9, on x86 only) +contains the memory protection key (see +.BR pkeys (7)) +associated with the virtual memory area. +This entry is present only if the kernel was built with the +.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS +configuration option. +.IP +The "VmFlags" line (available since Linux 3.8) +represents the kernel flags associated with the virtual memory area, +encoded using the following two-letter codes: +.IP + rd - readable + wr - writable + ex - executable + sh - shared + mr - may read + mw - may write + me - may execute + ms - may share + gd - stack segment grows down + pf - pure PFN range + dw - disabled write to the mapped file + lo - pages are locked in memory + io - memory mapped I/O area + sr - sequential read advise provided + rr - random read advise provided + dc - do not copy area on fork + de - do not expand area on remapping + ac - area is accountable + nr - swap space is not reserved for the area + ht - area uses huge tlb pages + nl - non-linear mapping + ar - architecture specific flag + dd - do not include area into core dump + sd - soft-dirty flag + mm - mixed map area + hg - huge page advise flag + nh - no-huge page advise flag + mg - mergeable advise flag +.IP +"ProtectionKey" field contains the memory protection key (see +.BR pkeys (5)) +associated with the virtual memory area. +Present only if the kernel was built with the +.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS +configuration option. (since Linux 4.6) +.IP +The +.IR /proc/[pid]/smaps +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.TP +.IR /proc/[pid]/stack " (since Linux 2.6.29)" +.\" 2ec220e27f5040aec1e88901c1b6ea3d135787ad +This file provides a symbolic trace of the function calls in this +process's kernel stack. +This file is provided only if the kernel was built with the +.B CONFIG_STACKTRACE +configuration option. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.TP +.I /proc/[pid]/stat +Status information about the process. +This is used by +.BR ps (1). +It is defined in the kernel source file +.IR fs/proc/array.c "." +.IP +The fields, in order, with their proper +.BR scanf (3) +format specifiers, are listed below. +Whether or not certain of these fields display valid information is governed by +a ptrace access mode +.BR PTRACE_MODE_READ_FSCREDS "\ |\ " PTRACE_MODE_NOAUDIT +check (refer to +.BR ptrace (2)). +If the check denies access, then the field value is displayed as 0. +The affected fields are indicated with the marking [PT]. +.IP +.RS +.TP 10 +(1) \fIpid\fP \ %d +.br +The process ID. +.TP +(2) \fIcomm\fP \ %s +The filename of the executable, in parentheses. +This is visible whether or not the executable is swapped out. +.TP +(3) \fIstate\fP \ %c +One of the following characters, indicating process state: +.RS +.IP R 3 +Running +.IP S +Sleeping in an interruptible wait +.IP D +Waiting in uninterruptible +disk sleep +.IP Z +Zombie +.IP T +Stopped (on a signal) or (before Linux 2.6.33) trace stopped +.IP t +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Tracing stop (Linux 2.6.33 onward) +.IP W +Paging (only before Linux 2.6.0) +.IP X +Dead (from Linux 2.6.0 onward) +.IP x +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Dead (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.IP K +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Wakekill (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.IP W +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Waking (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.IP P +.\" commit f2530dc71cf0822f90bb63ea4600caaef33a66bb +Parked (Linux 3.9 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.RE +.TP +(4) \fIppid\fP \ %d +The PID of the parent of this process. +.TP +(5) \fIpgrp\fP \ %d +The process group ID of the process. +.TP +(6) \fIsession\fP \ %d +The session ID of the process. +.TP +(7) \fItty_nr\fP \ %d +The controlling terminal of the process. +(The minor device number is contained in the combination of bits +31 to 20 and 7 to 0; +the major device number is in bits 15 to 8.) +.TP +(8) \fItpgid\fP \ %d +.\" This field and following, up to and including wchan added 0.99.1 +The ID of the foreground process group of the controlling +terminal of the process. +.TP +(9) \fIflags\fP \ %u +The kernel flags word of the process. +For bit meanings, +see the PF_* defines in the Linux kernel source file +.IR include/linux/sched.h . +Details depend on the kernel version. +.IP +The format for this field was %lu before Linux 2.6. +.TP +(10) \fIminflt\fP \ %lu +The number of minor faults the process has made which have not +required loading a memory page from disk. +.TP +(11) \fIcminflt\fP \ %lu +The number of minor faults that the process's +waited-for children have made. +.TP +(12) \fImajflt\fP \ %lu +The number of major faults the process has made which have +required loading a memory page from disk. +.TP +(13) \fIcmajflt\fP \ %lu +The number of major faults that the process's +waited-for children have made. +.TP +(14) \fIutime\fP \ %lu +Amount of time that this process has been scheduled in user mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +This includes guest time, \fIguest_time\fP +(time spent running a virtual CPU, see below), +so that applications that are not aware of the guest time field +do not lose that time from their calculations. +.TP +(15) \fIstime\fP \ %lu +Amount of time that this process has been scheduled in kernel mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(16) \fIcutime\fP \ %ld +Amount of time that this process's +waited-for children have been scheduled in user mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +(See also +.BR times (2).) +This includes guest time, \fIcguest_time\fP +(time spent running a virtual CPU, see below). +.TP +(17) \fIcstime\fP \ %ld +Amount of time that this process's +waited-for children have been scheduled in kernel mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(18) \fIpriority\fP \ %ld +(Explanation for Linux 2.6) +For processes running a real-time scheduling policy +.RI ( policy +below; see +.BR sched_setscheduler (2)), +this is the negated scheduling priority, minus one; +that is, a number in the range \-2 to \-100, +corresponding to real-time priorities 1 to 99. +For processes running under a non-real-time scheduling policy, +this is the raw nice value +.RB ( setpriority (2)) +as represented in the kernel. +The kernel stores nice values as numbers +in the range 0 (high) to 39 (low), +corresponding to the user-visible nice range of \-20 to 19. +.IP +Before Linux 2.6, this was a scaled value based on +the scheduler weighting given to this process. +.\" And back in kernel 1.2 days things were different again. +.TP +(19) \fInice\fP \ %ld +The nice value (see +.BR setpriority (2)), +a value in the range 19 (low priority) to \-20 (high priority). +.\" Back in kernel 1.2 days things were different. +.\" .TP +.\" \fIcounter\fP %ld +.\" The current maximum size in jiffies of the process's next timeslice, +.\" or what is currently left of its current timeslice, if it is the +.\" currently running process. +.\" .TP +.\" \fItimeout\fP %u +.\" The time in jiffies of the process's next timeout. +.\" timeout was removed sometime around 2.1/2.2 +.TP +(20) \fInum_threads\fP \ %ld +Number of threads in this process (since Linux 2.6). +Before kernel 2.6, this field was hard coded to 0 as a placeholder +for an earlier removed field. +.TP +(21) \fIitrealvalue\fP \ %ld +The time in jiffies before the next +.B SIGALRM +is sent to the process due to an interval timer. +Since kernel 2.6.17, this field is no longer maintained, +and is hard coded as 0. +.TP +(22) \fIstarttime\fP \ %llu +The time the process started after system boot. +In kernels before Linux 2.6, this value was expressed in jiffies. +Since Linux 2.6, the value is expressed in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.IP +The format for this field was %lu before Linux 2.6. +.TP +(23) \fIvsize\fP \ %lu +Virtual memory size in bytes. +.TP +(24) \fIrss\fP \ %ld +Resident Set Size: number of pages the process has in real memory. +This is just the pages which +count toward text, data, or stack space. +This does not include pages +which have not been demand-loaded in, or which are swapped out. +.TP +(25) \fIrsslim\fP \ %lu +Current soft limit in bytes on the rss of the process; +see the description of +.B RLIMIT_RSS +in +.BR getrlimit (2). +.TP +(26) \fIstartcode\fP \ %lu \ [PT] +The address above which program text can run. +.TP +(27) \fIendcode\fP \ %lu \ [PT] +The address below which program text can run. +.TP +(28) \fIstartstack\fP \ %lu \ [PT] +The address of the start (i.e., bottom) of the stack. +.TP +(29) \fIkstkesp\fP \ %lu \ [PT] +The current value of ESP (stack pointer), as found in the +kernel stack page for the process. +.TP +(30) \fIkstkeip\fP \ %lu \ [PT] +The current EIP (instruction pointer). +.TP +(31) \fIsignal\fP \ %lu +The bitmap of pending signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.I /proc/[pid]/status +instead. +.TP +(32) \fIblocked\fP \ %lu +The bitmap of blocked signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.I /proc/[pid]/status +instead. +.TP +(33) \fIsigignore\fP \ %lu +The bitmap of ignored signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.I /proc/[pid]/status +instead. +.TP +(34) \fIsigcatch\fP \ %lu +The bitmap of caught signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.I /proc/[pid]/status +instead. +.TP +(35) \fIwchan\fP \ %lu \ [PT] +This is the "channel" in which the process is waiting. +It is the address of a location in the kernel where the process is sleeping. +The corresponding symbolic name can be found in +.IR /proc/[pid]/wchan . +.TP +(36) \fInswap\fP \ %lu +.\" nswap was added in 2.0 +Number of pages swapped (not maintained). +.TP +(37) \fIcnswap\fP \ %lu +.\" cnswap was added in 2.0 +Cumulative \fInswap\fP for child processes (not maintained). +.TP +(38) \fIexit_signal\fP \ %d \ (since Linux 2.1.22) +Signal to be sent to parent when we die. +.TP +(39) \fIprocessor\fP \ %d \ (since Linux 2.2.8) +CPU number last executed on. +.TP +(40) \fIrt_priority\fP \ %u \ (since Linux 2.5.19) +Real-time scheduling priority, a number in the range 1 to 99 for +processes scheduled under a real-time policy, +or 0, for non-real-time processes (see +.BR sched_setscheduler (2)). +.TP +(41) \fIpolicy\fP \ %u \ (since Linux 2.5.19) +Scheduling policy (see +.BR sched_setscheduler (2)). +Decode using the SCHED_* constants in +.IR linux/sched.h . +.IP +The format for this field was %lu before Linux 2.6.22. +.TP +(42) \fIdelayacct_blkio_ticks\fP \ %llu \ (since Linux 2.6.18) +Aggregated block I/O delays, measured in clock ticks (centiseconds). +.TP +(43) \fIguest_time\fP \ %lu \ (since Linux 2.6.24) +Guest time of the process (time spent running a virtual CPU +for a guest operating system), measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(44) \fIcguest_time\fP \ %ld \ (since Linux 2.6.24) +Guest time of the process's children, measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(45) \fIstart_data\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address above which program initialized and +uninitialized (BSS) data are placed. +.TP +(46) \fIend_data\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address below which program initialized and +uninitialized (BSS) data are placed. +.TP +(47) \fIstart_brk\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address above which program heap can be expanded with +.BR brk (2). +.TP +(48) \fIarg_start\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address above which program command-line arguments +.RI ( argv ) +are placed. +.TP +(49) \fIarg_end\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address below program command-line arguments +.RI ( argv ) +are placed. +.TP +(50) \fIenv_start\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address above which program environment is placed. +.TP +(51) \fIenv_end\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address below which program environment is placed. +.TP +(52) \fIexit_code\fP \ %d \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +The thread's exit status in the form reported by +.BR waitpid (2). +.RE +.TP +.I /proc/[pid]/statm +Provides information about memory usage, measured in pages. +The columns are: +.IP +.in +4n +.EX +size (1) total program size + (same as VmSize in \fI/proc/[pid]/status\fP) +resident (2) resident set size + (same as VmRSS in \fI/proc/[pid]/status\fP) +shared (3) number of resident shared pages (i.e., backed by a file) + (same as RssFile+RssShmem in \fI/proc/[pid]/status\fP) +text (4) text (code) +.\" (not including libs; broken, includes data segment) +lib (5) library (unused since Linux 2.6; always 0) +data (6) data + stack +.\" (including libs; broken, includes library text) +dt (7) dirty pages (unused since Linux 2.6; always 0) +.EE +.in +.TP +.I /proc/[pid]/status +Provides much of the information in +.I /proc/[pid]/stat +and +.I /proc/[pid]/statm +in a format that's easier for humans to parse. +Here's an example: +.IP +.in +4n +.EX +.RB "$" " cat /proc/$$/status" +Name: bash +Umask: 0022 +State: S (sleeping) +Tgid: 17248 +Ngid: 0 +Pid: 17248 +PPid: 17200 +TracerPid: 0 +Uid: 1000 1000 1000 1000 +Gid: 100 100 100 100 +FDSize: 256 +Groups: 16 33 100 +NStgid: 17248 +NSpid: 17248 +NSpgid: 17248 +NSsid: 17200 +VmPeak: 131168 kB +VmSize: 131168 kB +VmLck: 0 kB +VmPin: 0 kB +VmHWM: 13484 kB +VmRSS: 13484 kB +RssAnon: 10264 kB +RssFile: 3220 kB +RssShmem: 0 kB +VmData: 10332 kB +VmStk: 136 kB +VmExe: 992 kB +VmLib: 2104 kB +VmPTE: 76 kB +VmPMD: 12 kB +VmSwap: 0 kB +HugetlbPages: 0 kB # 4.4 +Threads: 1 +SigQ: 0/3067 +SigPnd: 0000000000000000 +ShdPnd: 0000000000000000 +SigBlk: 0000000000010000 +SigIgn: 0000000000384004 +SigCgt: 000000004b813efb +CapInh: 0000000000000000 +CapPrm: 0000000000000000 +CapEff: 0000000000000000 +CapBnd: ffffffffffffffff +CapAmb: 0000000000000000 +NoNewPrivs: 0 +Seccomp: 0 +Cpus_allowed: 00000001 +Cpus_allowed_list: 0 +Mems_allowed: 1 +Mems_allowed_list: 0 +voluntary_ctxt_switches: 150 +nonvoluntary_ctxt_switches: 545 +.EE +.in +.IP +The fields are as follows: +.RS +.IP * 2 +.IR Name : +Command run by this process. +.IP * +.IR Umask : +Process umask, expressed in octal with a leading zero; see +.BR umask (2). +(Since Linux 4.7.) +.IP * +.IR State : +Current state of the process. +One of +"R (running)", +"S (sleeping)", +"D (disk sleep)", +"T (stopped)", +"T (tracing stop)", +"Z (zombie)", +or +"X (dead)". +.IP * +.IR Tgid : +Thread group ID (i.e., Process ID). +.IP * +.IR Ngid : +NUMA group ID (0 if none; since Linux 3.13). +.IP * +.IR Pid : +Thread ID (see +.BR gettid (2)). +.IP * +.IR PPid : +PID of parent process. +.IP * +.IR TracerPid : +PID of process tracing this process (0 if not being traced). +.IP * +.IR Uid ", " Gid : +Real, effective, saved set, and filesystem UIDs (GIDs). +.IP * +.IR FDSize : +Number of file descriptor slots currently allocated. +.IP * +.IR Groups : +Supplementary group list. +.IP * +.I NStgid : +Thread group ID (i.e., PID) in each of the PID namespaces of which +.I [pid] +is a member. +The leftmost entry shows the value with respect to the PID namespace +of the reading process, +followed by the value in successively nested inner namespaces. +.\" commit e4bc33245124db69b74a6d853ac76c2976f472d5 +(Since Linux 4.1.) +.IP * +.IR NSpid: +Thread ID in each of the PID namespaces of which +.I [pid] +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.IP * +.IR NSpgid : +Process group ID in each of the PID namespaces of which +.I [pid] +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.IP * +.IR NSsid : +descendant namespace session ID hierarchy +Session ID in each of the PID namespaces of which +.I [pid] +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.IP * +.IR VmPeak : +Peak virtual memory size. +.IP * +.IR VmSize : +Virtual memory size. +.IP * +.IR VmLck : +Locked memory size (see +.BR mlock (3)). +.IP * +.IR VmPin : +Pinned memory size +.\" commit bc3e53f682d93df677dbd5006a404722b3adfe18 +(since Linux 3.2). +These are pages that can't be moved because something needs to +directly access physical memory. +.IP * +.IR VmHWM : +Peak resident set size ("high water mark"). +.IP * +.IR VmRSS : +Resident set size. +Note that the value here is the sum of +.IR RssAnon , +.IR RssFile , +and +.IR RssShmem . +.IP * +.IR RssAnon : +Size of resident anonymous memory. +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +.IP * +.IR RssFile : +Size of resident file mappings. +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +.IP * +.IR RssShmem : +Size of resident shared memory (includes System V shared memory, +mappings from +.BR tmpfs (5), +and shared anonymous mappings). +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +.IP * +.IR VmData ", " VmStk ", " VmExe : +Size of data, stack, and text segments. +.IP * +.IR VmLib : +Shared library code size. +.IP * +.IR VmPTE : +Page table entries size (since Linux 2.6.10). +.IP * +.IR VmPMD : +.\" commit dc6c9a35b66b520cf67e05d8ca60ebecad3b0479 +Size of second-level page tables (since Linux 4.0). +.IP * +.IR VmSwap : +.\" commit b084d4353ff99d824d3bc5a5c2c22c70b1fba722 +Swapped-out virtual memory size by anonymous private pages; +shmem swap usage is not included (since Linux 2.6.34). +.IP * +.IR HugetlbPages : +Size of hugetlb memory portions. +.\" commit 5d317b2b6536592a9b51fe65faed43d65ca9158e +(since Linux 4.4). +.IP * +.IR Threads : +Number of threads in process containing this thread. +.IP * +.IR SigQ : +This field contains two slash-separated numbers that relate to +queued signals for the real user ID of this process. +The first of these is the number of currently queued +signals for this real user ID, and the second is the +resource limit on the number of queued signals for this process +(see the description of +.BR RLIMIT_SIGPENDING +in +.BR getrlimit (2)). +.IP * +.IR SigPnd ", " ShdPnd : +Number of signals pending for thread and for process as a whole (see +.BR pthreads (7) +and +.BR signal (7)). +.IP * +.IR SigBlk ", " SigIgn ", " SigCgt : +Masks indicating signals being blocked, ignored, and caught (see +.BR signal (7)). +.IP * +.IR CapInh ", " CapPrm ", " CapEff : +Masks of capabilities enabled in inheritable, permitted, and effective sets +(see +.BR capabilities (7)). +.IP * +.IR CapBnd : +Capability Bounding set +(since Linux 2.6.26, see +.BR capabilities (7)). +.IP * +.IR CapAmb : +Ambient capability set +(since Linux 4.3, see +.BR capabilities (7)). +.IP * +.IR NoNewPrivs : +.\" commit af884cd4a5ae62fcf5e321fecf0ec1014730353d +Value of the +.I no_new_privs +bit +(since Linux 4.10, see +.BR prctl (2)). +.IP * +.IR Seccomp : +.\" commit 2f4b3bf6b2318cfaa177ec5a802f4d8d6afbd816 +Seccomp mode of the process +(since Linux 3.8, see +.BR seccomp (2)). +0 means +.BR SECCOMP_MODE_DISABLED ; +1 means +.BR SECCOMP_MODE_STRICT ; +2 means +.BR SECCOMP_MODE_FILTER . +This field is provided only if the kernel was built with the +.BR CONFIG_SECCOMP +kernel configuration option enabled. +.IP * +.IR Cpus_allowed : +Mask of CPUs on which this process may run +(since Linux 2.6.24, see +.BR cpuset (7)). +.IP * +.IR Cpus_allowed_list : +Same as previous, but in "list format" +(since Linux 2.6.26, see +.BR cpuset (7)). +.IP * +.IR Mems_allowed : +Mask of memory nodes allowed to this process +(since Linux 2.6.24, see +.BR cpuset (7)). +.IP * +.IR Mems_allowed_list : +Same as previous, but in "list format" +(since Linux 2.6.26, see +.BR cpuset (7)). +.IP * +.IR voluntary_ctxt_switches ", " nonvoluntary_ctxt_switches : +Number of voluntary and involuntary context switches (since Linux 2.6.23). +.RE +.TP +.IR /proc/[pid]/syscall " (since Linux 2.6.27)" +.\" commit ebcb67341fee34061430f3367f2e507e52ee051b +This file exposes the system call number and argument registers for the +system call currently being executed by the process, +followed by the values of the stack pointer and program counter registers. +The values of all six argument registers are exposed, +although most system calls use fewer registers. +.IP +If the process is blocked, but not in a system call, +then the file displays \-1 in place of the system call number, +followed by just the values of the stack pointer and program counter. +If process is not blocked, then the file contains just the string "running". +.IP +This file is present only if the kernel was configured with +.BR CONFIG_HAVE_ARCH_TRACEHOOK . +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.TP +.IR /proc/[pid]/task " (since Linux 2.6.0-test6)" +This is a directory that contains one subdirectory +for each thread in the process. +The name of each subdirectory is the numerical thread ID +.RI ( [tid] ) +of the thread (see +.BR gettid (2)). +Within each of these subdirectories, there is a set of +files with the same names and contents as under the +.I /proc/[pid] +directories. +For attributes that are shared by all threads, the contents for +each of the files under the +.I task/[tid] +subdirectories will be the same as in the corresponding +file in the parent +.I /proc/[pid] +directory +(e.g., in a multithreaded process, all of the +.I task/[tid]/cwd +files will have the same value as the +.I /proc/[pid]/cwd +file in the parent directory, since all of the threads in a process +share a working directory). +For attributes that are distinct for each thread, +the corresponding files under +.I task/[tid] +may have different values (e.g., various fields in each of the +.I task/[tid]/status +files may be different for each thread), +.\" in particular: "children" :/ +or they might not exist in +.I /proc/[pid] +at all. +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of the +.I /proc/[pid]/task +directory are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +.TP +.IR /proc/[pid]/task/[tid]/children " (since Linux 3.5)" +.\" commit 818411616baf46ceba0cff6f05af3a9b294734f7 +A space-separated list of child tasks of this task. +Each child task is represented by its TID. +.IP +.\" see comments in get_children_pid() in fs/proc/array.c +This option is intended for use by the checkpoint-restore (CRIU) system, +and reliably provides a list of children only if all of the child processes +are stopped or frozen. +It does not work properly if children of the target task exit while +the file is being read! +Exiting children may cause non-exiting children to be omitted from the list. +This makes this interface even more unreliable than classic PID-based +approaches if the inspected task and its children aren't frozen, +and most code should probably not use this interface. +.IP +Until Linux 4.2, the presence of this file was governed by the +.B CONFIG_CHECKPOINT_RESTORE +kernel configuration option. +Since Linux 4.2, +.\" commit 2e13ba54a2682eea24918b87ad3edf70c2cf085b +it is governed by the +.B CONFIG_PROC_CHILDREN +option. +.TP +.IR /proc/[pid]/timers " (since Linux 3.10)" +.\" commit 5ed67f05f66c41e39880a6d61358438a25f9fee5 +.\" commit 48f6a7a511ef8823fdff39afee0320092d43a8a0 +A list of the POSIX timers for this process. +Each timer is listed with a line that starts with the string "ID:". +For example: +.IP +.in +4n +.EX +ID: 1 +signal: 60/00007fff86e452a8 +notify: signal/pid.2634 +ClockID: 0 +ID: 0 +signal: 60/00007fff86e452a8 +notify: signal/pid.2634 +ClockID: 1 +.EE +.in +.IP +The lines shown for each timer have the following meanings: +.RS +.TP +.I ID +The ID for this timer. +This is not the same as the timer ID returned by +.BR timer_create (2); +rather, it is the same kernel-internal ID that is available via the +.I si_timerid +field of the +.IR siginfo_t +structure (see +.BR sigaction (2)). +.TP +.I signal +This is the signal number that this timer uses to deliver notifications +followed by a slash, and then the +.I sigev_value +value supplied to the signal handler. +Valid only for timers that notify via a signal. +.TP +.I notify +The part before the slash specifies the mechanism +that this timer uses to deliver notifications, +and is one of "thread", "signal", or "none". +Immediately following the slash is either the string "tid" for timers +with +.B SIGEV_THREAD_ID +notification, or "pid" for timers that notify by other mechanisms. +Following the "." is the PID of the process +(or the kernel thread ID of the thread) that will be delivered +a signal if the timer delivers notifications via a signal. +.TP +.I ClockID +This field identifies the clock that the timer uses for measuring time. +For most clocks, this is a number that matches one of the user-space +.BR CLOCK_* +constants exposed via +.IR . +.B CLOCK_PROCESS_CPUTIME_ID +timers display with a value of \-6 +in this field. +.B CLOCK_THREAD_CPUTIME_ID +timers display with a value of \-2 +in this field. +.RE +.IP +This file is available only when the kernel was configured with +.BR CONFIG_CHECKPOINT_RESTORE . +.TP +.IR /proc/[pid]/timerslack_ns " (since Linux 4.6)" +.\" commit da8b44d5a9f8bf26da637b7336508ca534d6b319 +.\" commit 5de23d435e88996b1efe0e2cebe242074ce67c9e +This file exposes the process's "current" timer slack value, +expressed in nanoseconds. +The file is writable, +allowing the process's timer slack value to be changed. +Writing 0 to this file resets the "current" timer slack to the +"default" timer slack value. +For further details, see the discussion of +.BR PR_SET_TIMERSLACK +in +.BR prctl (2). +.IP +Initially, +permission to access this file was governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check (see +.BR ptrace (2)). +However, this was subsequently deemed too strict a requirement +(and had the side effect that requiring a process to have the +.B CAP_SYS_PTRACE +capability would also allow it to view and change any process's memory). +Therefore, since Linux 4.9, +.\" commit 7abbaf94049914f074306d960b0f968ffe52e59f +only the (weaker) +.B CAP_SYS_NICE +capability is required to access this file. +.TP +.IR /proc/[pid]/uid_map ", " /proc/[pid]/gid_map " (since Linux 3.5)" +See +.BR user_namespaces (7). +.TP +.IR /proc/[pid]/wchan " (since Linux 2.6.0)" +The symbolic name corresponding to the location +in the kernel where the process is sleeping. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.TP +.I /proc/apm +Advanced power management version and battery information when +.B CONFIG_APM +is defined at kernel compilation time. +.TP +.I /proc/buddyinfo +This file contains information which is used for diagnosing memory +fragmentation issues. +Each line starts with the identification of the node and the name +of the zone which together identify a memory region +This is then +followed by the count of available chunks of a certain order in +which these zones are split. +The size in bytes of a certain order is given by the formula: +.IP + (2^order)\ *\ PAGE_SIZE +.IP +The binary buddy allocator algorithm inside the kernel will split +one chunk into two chunks of a smaller order (thus with half the +size) or combine two contiguous chunks into one larger chunk of +a higher order (thus with double the size) to satisfy allocation +requests and to counter memory fragmentation. +The order matches the column number, when starting to count at zero. +.IP +For example on an x86-64 system: +.IP +.in -12n +.EX +Node 0, zone DMA 1 1 1 0 2 1 1 0 1 1 3 +Node 0, zone DMA32 65 47 4 81 52 28 13 10 5 1 404 +Node 0, zone Normal 216 55 189 101 84 38 37 27 5 3 587 +.EE +.in +.IP +In this example, there is one node containing three zones and there +are 11 different chunk sizes. +If the page size is 4 kilobytes, then the first zone called +.I DMA +(on x86 the first 16 megabyte of memory) has 1 chunk of 4 kilobytes +(order 0) available and has 3 chunks of 4 megabytes (order 10) available. +.IP +If the memory is heavily fragmented, the counters for higher +order chunks will be zero and allocation of large contiguous areas +will fail. +.IP +Further information about the zones can be found in +.IR /proc/zoneinfo . +.TP +.I /proc/bus +Contains subdirectories for installed busses. +.TP +.I /proc/bus/pccard +Subdirectory for PCMCIA devices when +.B CONFIG_PCMCIA +is set at kernel compilation time. +.TP +.I /proc/bus/pccard/drivers +.TP +.I /proc/bus/pci +Contains various bus subdirectories and pseudo-files containing +information about PCI busses, installed devices, and device +drivers. +Some of these files are not ASCII. +.TP +.I /proc/bus/pci/devices +Information about PCI devices. +They may be accessed through +.BR lspci (8) +and +.BR setpci (8). +.TP +.IR /proc/cgroups " (since Linux 2.6.24)" +See +.BR cgroups (7). +.TP +.I /proc/cmdline +Arguments passed to the Linux kernel at boot time. +Often done via a boot manager such as +.BR lilo (8) +or +.BR grub (8). +.TP +.IR /proc/config.gz " (since Linux 2.6)" +This file exposes the configuration options that were used +to build the currently running kernel, +in the same format as they would be shown in the +.I .config +file that resulted when configuring the kernel (using +.IR "make xconfig" , +.IR "make config" , +or similar). +The file contents are compressed; view or search them using +.BR zcat (1) +and +.BR zgrep (1). +As long as no changes have been made to the following file, +the contents of +.I /proc/config.gz +are the same as those provided by: +.IP +.in +4n +.EX +cat /lib/modules/$(uname \-r)/build/.config +.EE +.in +.IP +.I /proc/config.gz +is provided only if the kernel is configured with +.BR CONFIG_IKCONFIG_PROC . +.TP +.I /proc/crypto +A list of the ciphers provided by the kernel crypto API. +For details, see the kernel +.I "Linux Kernel Crypto API" +documentation available under the kernel source directory +.I Documentation/crypto/ +.\" commit 3b72c814a8e8cd638e1ba0da4dfce501e9dff5af +(or +.I Documentation/DocBook +before 4.10; +the documentation can be built using a command such as +.IR "make htmldocs" +in the root directory of the kernel source tree). +.TP +.I /proc/cpuinfo +This is a collection of CPU and system architecture dependent items, +for each supported architecture a different list. +Two common entries are \fIprocessor\fP which gives CPU number and +\fIbogomips\fP; a system constant that is calculated +during kernel initialization. +SMP machines have information for +each CPU. +The +.BR lscpu (1) +command gathers its information from this file. +.TP +.I /proc/devices +Text listing of major numbers and device groups. +This can be used by MAKEDEV scripts for consistency with the kernel. +.TP +.IR /proc/diskstats " (since Linux 2.5.69)" +This file contains disk I/O statistics for each disk device. +See the Linux kernel source file +.I Documentation/iostats.txt +for further information. +.TP +.I /proc/dma +This is a list of the registered \fIISA\fP DMA (direct memory access) +channels in use. +.TP +.I /proc/driver +Empty subdirectory. +.TP +.I /proc/execdomains +List of the execution domains (ABI personalities). +.TP +.I /proc/fb +Frame buffer information when +.B CONFIG_FB +is defined during kernel compilation. +.TP +.I /proc/filesystems +A text listing of the filesystems which are supported by the kernel, +namely filesystems which were compiled into the kernel or whose kernel +modules are currently loaded. +(See also +.BR filesystems (5).) +If a filesystem is marked with "nodev", +this means that it does not require a block device to be mounted +(e.g., virtual filesystem, network filesystem). +.IP +Incidentally, this file may be used by +.BR mount (8) +when no filesystem is specified and it didn't manage to determine the +filesystem type. +Then filesystems contained in this file are tried +(excepted those that are marked with "nodev"). +.TP +.I /proc/fs +.\" FIXME Much more needs to be said about /proc/fs +.\" +Contains subdirectories that in turn contain files +with information about (certain) mounted filesystems. +.TP +.I /proc/ide +This directory +exists on systems with the IDE bus. +There are directories for each IDE channel and attached device. +Files include: +.IP +.in +4n +.EX +cache buffer size in KB +capacity number of sectors +driver driver version +geometry physical and logical geometry +identify in hexadecimal +media media type +model manufacturer's model number +settings drive settings +smart_thresholds in hexadecimal +smart_values in hexadecimal +.EE +.in +.IP +The +.BR hdparm (8) +utility provides access to this information in a friendly format. +.TP +.I /proc/interrupts +This is used to record the number of interrupts per CPU per IO device. +Since Linux 2.6.24, +for the i386 and x86-64 architectures, at least, this also includes +interrupts internal to the system (that is, not associated with a device +as such), such as NMI (nonmaskable interrupt), LOC (local timer interrupt), +and for SMP systems, TLB (TLB flush interrupt), RES (rescheduling +interrupt), CAL (remote function call interrupt), and possibly others. +Very easy to read formatting, done in ASCII. +.TP +.I /proc/iomem +I/O memory map in Linux 2.4. +.TP +.I /proc/ioports +This is a list of currently registered Input-Output port regions that +are in use. +.TP +.IR /proc/kallsyms " (since Linux 2.5.71)" +This holds the kernel exported symbol definitions used by the +.BR modules (X) +tools to dynamically link and bind loadable modules. +In Linux 2.5.47 and earlier, a similar file with slightly different syntax +was named +.IR ksyms . +.TP +.I /proc/kcore +This file represents the physical memory of the system and is stored +in the ELF core file format. +With this pseudo-file, and an unstripped +kernel +.RI ( /usr/src/linux/vmlinux ) +binary, GDB can be used to +examine the current state of any kernel data structures. +.IP +The total length of the file is the size of physical memory (RAM) plus +4\ KiB. +.TP +.IR /proc/keys " (since Linux 2.6.10)" +See +.BR keyrings (7). +.TP +.IR /proc/key-users " (since Linux 2.6.10)" +See +.BR keyrings (7). +.TP +.I /proc/kmsg +This file can be used instead of the +.BR syslog (2) +system call to read kernel messages. +A process must have superuser +privileges to read this file, and only one process should read this +file. +This file should not be read if a syslog process is running +which uses the +.BR syslog (2) +system call facility to log kernel messages. +.IP +Information in this file is retrieved with the +.BR dmesg (1) +program. +.TP +.IR /proc/kpagecgroup " (since Linux 4.3)" +.\" commit 80ae2fdceba8313b0433f899bdd9c6c463291a17 +This file contains a 64-bit inode number of +the memory cgroup each page is charged to, +indexed by page frame number (see the discussion of +.IR /proc/[pid]/pagemap ). +.IP +The +.IR /proc/kpagecgroup +file is present only if the +.B CONFIG_MEMCG +kernel configuration option is enabled. +.TP +.IR /proc/kpagecount " (since Linux 2.6.25)" +This file contains a 64-bit count of the number of +times each physical page frame is mapped, +indexed by page frame number (see the discussion of +.IR /proc/[pid]/pagemap ). +.IP +The +.IR /proc/kpagecount +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.TP +.IR /proc/kpageflags " (since Linux 2.6.25)" +This file contains 64-bit masks corresponding to each physical page frame; +it is indexed by page frame number (see the discussion of +.IR /proc/[pid]/pagemap ). +The bits are as follows: +.IP + 0 - KPF_LOCKED + 1 - KPF_ERROR + 2 - KPF_REFERENCED + 3 - KPF_UPTODATE + 4 - KPF_DIRTY + 5 - KPF_LRU + 6 - KPF_ACTIVE + 7 - KPF_SLAB + 8 - KPF_WRITEBACK + 9 - KPF_RECLAIM + 10 - KPF_BUDDY + 11 - KPF_MMAP (since Linux 2.6.31) + 12 - KPF_ANON (since Linux 2.6.31) + 13 - KPF_SWAPCACHE (since Linux 2.6.31) + 14 - KPF_SWAPBACKED (since Linux 2.6.31) + 15 - KPF_COMPOUND_HEAD (since Linux 2.6.31) + 16 - KPF_COMPOUND_TAIL (since Linux 2.6.31) + 17 - KPF_HUGE (since Linux 2.6.31) + 18 - KPF_UNEVICTABLE (since Linux 2.6.31) + 19 - KPF_HWPOISON (since Linux 2.6.31) + 20 - KPF_NOPAGE (since Linux 2.6.31) + 21 - KPF_KSM (since Linux 2.6.32) + 22 - KPF_THP (since Linux 3.4) + 23 - KPF_BALLOON (since Linux 3.18) +.\" KPF_BALLOON: commit 09316c09dde33aae14f34489d9e3d243ec0d5938 + 24 - KPF_ZERO_PAGE (since Linux 4.0) +.\" KPF_ZERO_PAGE: commit 56873f43abdcd574b25105867a990f067747b2f4 + 25 - KPF_IDLE (since Linux 4.3) +.\" KPF_IDLE: commit f074a8f49eb87cde95ac9d040ad5e7ea4f029738 +.IP +For further details on the meanings of these bits, +see the kernel source file +.IR Documentation/vm/pagemap.txt . +Before kernel 2.6.29, +.\" commit ad3bdefe877afb47480418fdb05ecd42842de65e +.\" commit e07a4b9217d1e97d2f3a62b6b070efdc61212110 +.BR KPF_WRITEBACK , +.BR KPF_RECLAIM , +.BR KPF_BUDDY , +and +.BR KPF_LOCKED +did not report correctly. +.IP +The +.IR /proc/kpageflags +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.TP +.IR /proc/ksyms " (Linux 1.1.23\(en2.5.47)" +See +.IR /proc/kallsyms . +.TP +.I /proc/loadavg +The first three fields in this file are load average figures +giving the number of jobs in the run queue (state R) +or waiting for disk I/O (state D) averaged over 1, 5, and 15 minutes. +They are the same as the load average numbers given by +.BR uptime (1) +and other programs. +The fourth field consists of two numbers separated by a slash (/). +The first of these is the number of currently runnable kernel +scheduling entities (processes, threads). +The value after the slash is the number of kernel scheduling entities +that currently exist on the system. +The fifth field is the PID of the process that was most +recently created on the system. +.TP +.I /proc/locks +This file shows current file locks +.RB ( flock "(2) and " fcntl (2)) +and leases +.RB ( fcntl (2)). +.IP +An example of the content shown in this file is the following: +.IP +.in +4n +.EX +1: POSIX ADVISORY READ 5433 08:01:7864448 128 128 +2: FLOCK ADVISORY WRITE 2001 08:01:7864554 0 EOF +3: FLOCK ADVISORY WRITE 1568 00:2f:32388 0 EOF +4: POSIX ADVISORY WRITE 699 00:16:28457 0 EOF +5: POSIX ADVISORY WRITE 764 00:16:21448 0 0 +6: POSIX ADVISORY READ 3548 08:01:7867240 1 1 +7: POSIX ADVISORY READ 3548 08:01:7865567 1826 2335 +8: OFDLCK ADVISORY WRITE -1 08:01:8713209 128 191 +.EE +.in +.IP +The fields shown in each line are as follows: +.RS +.IP (1) 4 +The ordinal position of the lock in the list. +.IP (2) +The lock type. +Values that may appear here include: +.RS +.TP +.B FLOCK +This is a BSD file lock created using +.BR flock (2). +.TP +.B OFDLCK +This is an open file description (OFD) lock created using +.BR fcntl (2). +.TP +.B POSIX +This is a POSIX byte-range lock created using +.BR fcntl (2). +.RE +.IP (3) +Among the strings that can appear here are the following: +.RS +.TP +.B ADVISORY +This is an advisory lock. +.TP +.B MANDATORY +This is a mandatory lock. +.RE +.IP (4) +The type of lock. +Values that can appear here are: +.RS +.TP +.B READ +This is a POSIX or OFD read lock, or a BSD shared lock. +.TP +.B WRITE +This is a POSIX or OFD write lock, or a BSD exclusive lock. +.RE +.IP (5) +The PID of the process that owns the lock. +.IP +Because OFD locks are not owned by a single process +(since multiple processes may have file descriptors that +refer to the same open file description), +the value \-1 is displayed in this field for OFD locks. +(Before kernel 4.14, +.\" commit 9d5b86ac13c573795525ecac6ed2db39ab23e2a8 +a bug meant that the PID of the process that +initially acquired the lock was displayed instead of the value \-1.) +.IP (6) +Three colon-separated subfields that identify the major and minor device +ID of the device containing the filesystem where the locked file resides, +followed by the inode number of the locked file. +.IP (7) +The byte offset of the first byte of the lock. +For BSD locks, this value is always 0. +.IP (8) +The byte offset of the last byte of the lock. +.B EOF +in this field means that the lock extends to the end of the file. +For BSD locks, the value shown is always +.IR EOF . +.RE +.IP +Since Linux 4.9, +.\" commit d67fd44f697dff293d7cdc29af929241b669affe +the list of locks shown in +.I /proc/locks +is filtered to show just the locks for the processes in the PID +namespace (see +.BR pid_namespaces (7)) +for which the +.I /proc +filesystem was mounted. +(In the initial PID namespace, +there is no filtering of the records shown in this file.) +.IP +The +.BR lslocks (8) +command provides a bit more information about each lock. +.TP +.IR /proc/malloc " (only up to and including Linux 2.2)" +.\" It looks like this only ever did something back in 1.0 days +This file is present only if +.B CONFIG_DEBUG_MALLOC +was defined during compilation. +.TP +.I /proc/meminfo +This file reports statistics about memory usage on the system. +It is used by +.BR free (1) +to report the amount of free and used memory (both physical and swap) +on the system as well as the shared memory and buffers used by the +kernel. +Each line of the file consists of a parameter name, followed by a colon, +the value of the parameter, and an option unit of measurement (e.g., "kB"). +The list below describes the parameter names and +the format specifier required to read the field value. +Except as noted below, +all of the fields have been present since at least Linux 2.6.0. +Some fields are displayed only if the kernel was configured +with various options; those dependencies are noted in the list. +.RS +.TP +.IR MemTotal " %lu" +Total usable RAM (i.e., physical RAM minus a few reserved +bits and the kernel binary code). +.TP +.IR MemFree " %lu" +The sum of +.IR LowFree + HighFree . +.TP +.IR MemAvailable " %lu (since Linux 3.14)" +An estimate of how much memory is available for starting new +applications, without swapping. +.TP +.IR Buffers " %lu" +Relatively temporary storage for raw disk blocks that +shouldn't get tremendously large (20MB or so). +.TP +.IR Cached " %lu" +In-memory cache for files read from the disk (the page cache). +Doesn't include +.IR SwapCached . +.TP +.IR SwapCached " %lu" +Memory that once was swapped out, is swapped back in but +still also is in the swap file. +(If memory pressure is high, these pages +don't need to be swapped out again because they are already +in the swap file. +This saves I/O.) +.TP +.IR Active " %lu" +Memory that has been used more recently and usually not +reclaimed unless absolutely necessary. +.TP +.IR Inactive " %lu" +Memory which has been less recently used. +It is more eligible to be reclaimed for other purposes. +.TP +.IR Active(anon) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Inactive(anon) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Active(file) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Inactive(file) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Unevictable " %lu (since Linux 2.6.28)" +(From Linux 2.6.28 to 2.6.30, +\fBCONFIG_UNEVICTABLE_LRU\fP was required.) +[To be documented.] +.TP +.IR Mlocked " %lu (since Linux 2.6.28)" +(From Linux 2.6.28 to 2.6.30, +\fBCONFIG_UNEVICTABLE_LRU\fP was required.) +[To be documented.] +.TP +.IR HighTotal " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Total amount of highmem. +Highmem is all memory above ~860MB of physical memory. +Highmem areas are for use by user-space programs, +or for the page cache. +The kernel must use tricks to access +this memory, making it slower to access than lowmem. +.TP +.IR HighFree " %lu +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Amount of free highmem. +.TP +.IR LowTotal " %lu +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Total amount of lowmem. +Lowmem is memory which can be used for everything that +highmem can be used for, but it is also available for the +kernel's use for its own data structures. +Among many other things, +it is where everything from +.I Slab +is allocated. +Bad things happen when you're out of lowmem. +.TP +.IR LowFree " %lu +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Amount of free lowmem. +.TP +.IR MmapCopy " %lu (since Linux 2.6.29)" +.RB ( CONFIG_MMU +is required.) +[To be documented.] +.TP +.IR SwapTotal " %lu" +Total amount of swap space available. +.TP +.IR SwapFree " %lu" +Amount of swap space that is currently unused. +.TP +.IR Dirty " %lu" +Memory which is waiting to get written back to the disk. +.TP +.IR Writeback " %lu" +Memory which is actively being written back to the disk. +.TP +.IR AnonPages " %lu (since Linux 2.6.18)" +Non-file backed pages mapped into user-space page tables. +.TP +.IR Mapped " %lu" +Files which have been mapped into memory (with +.BR mmap (2)), +such as libraries. +.TP +.IR Shmem " %lu (since Linux 2.6.32)" +Amount of memory consumed in +.BR tmpfs (5) +filesystems. +.TP +.IR Slab " %lu" +In-kernel data structures cache. +(See +.BR slabinfo (5).) +.TP +.IR SReclaimable " %lu (since Linux 2.6.19)" +Part of +.IR Slab , +that might be reclaimed, such as caches. +.TP +.IR SUnreclaim " %lu (since Linux 2.6.19)" +Part of +.IR Slab , +that cannot be reclaimed on memory pressure. +.TP +.IR KernelStack " %lu (since Linux 2.6.32)" +Amount of memory allocated to kernel stacks. +.TP +.IR PageTables " %lu (since Linux 2.6.18)" +Amount of memory dedicated to the lowest level of page tables. +.TP +.IR Quicklists " %lu (since Linux 2.6.27)" +(\fBCONFIG_QUICKLIST\fP is required.) +[To be documented.] +.TP +.IR NFS_Unstable " %lu (since Linux 2.6.18)" +NFS pages sent to the server, but not yet committed to stable storage. +.TP +.IR Bounce " %lu (since Linux 2.6.18)" +Memory used for block device "bounce buffers". +.TP +.IR WritebackTmp " %lu (since Linux 2.6.26)" +Memory used by FUSE for temporary writeback buffers. +.TP +.IR CommitLimit " %lu (since Linux 2.6.10)" +This is the total amount of memory currently available to +be allocated on the system, expressed in kilobytes. +This limit is adhered to +only if strict overcommit accounting is enabled (mode 2 in +.IR /proc/sys/vm/overcommit_memory ). +The limit is calculated according to the formula described under +.IR /proc/sys/vm/overcommit_memory . +For further details, see the kernel source file +.IR Documentation/vm/overcommit-accounting . +.TP +.IR Committed_AS " %lu" +The amount of memory presently allocated on the system. +The committed memory is a sum of all of the memory which +has been allocated by processes, even if it has not been +"used" by them as of yet. +A process which allocates 1GB of memory (using +.BR malloc (3) +or similar), but touches only 300MB of that memory will show up +as using only 300MB of memory even if it has the address space +allocated for the entire 1GB. +.IP +This 1GB is memory which has been "committed" to by the VM +and can be used at any time by the allocating application. +With strict overcommit enabled on the system (mode 2 in +.IR /proc/sys/vm/overcommit_memory ), +allocations which would exceed the +.I CommitLimit +will not be permitted. +This is useful if one needs to guarantee that processes will not +fail due to lack of memory once that memory has been successfully allocated. +.TP +.IR VmallocTotal " %lu" +Total size of vmalloc memory area. +.TP +.IR VmallocUsed " %lu" +Amount of vmalloc area which is used. +.TP +.IR VmallocChunk " %lu" +Largest contiguous block of vmalloc area which is free. +.TP +.IR HardwareCorrupted " %lu (since Linux 2.6.32)" +(\fBCONFIG_MEMORY_FAILURE\fP is required.) +[To be documented.] +.TP +.IR AnonHugePages " %lu (since Linux 2.6.38)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Non-file backed huge pages mapped into user-space page tables. +.TP +.IR ShmemHugePages " %lu (since Linux 4.8)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Memory used by shared memory (shmem) and +.BR tmpfs (5) +allocated with huge pages +.TP +.IR ShmemPmdMapped " %lu (since Linux 4.8)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Shared memory mapped into user space with huge pages. +.TP +.IR CmaTotal " %lu (since Linux 3.1)" +Total CMA (Contiguous Memory Allocator) pages. +(\fBCONFIG_CMA\fP is required.) +.TP +.IR CmaFree " %lu (since Linux 3.1)" +Free CMA (Contiguous Memory Allocator) pages. +(\fBCONFIG_CMA\fP is required.) +.TP +.IR HugePages_Total " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The size of the pool of huge pages. +.TP +.IR HugePages_Free " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The number of huge pages in the pool that are not yet allocated. +.TP +.IR HugePages_Rsvd " %lu (since Linux 2.6.17)" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +This is the number of huge pages for +which a commitment to allocate from the pool has been made, +but no allocation has yet been made. +These reserved huge pages +guarantee that an application will be able to allocate a +huge page from the pool of huge pages at fault time. +.TP +.IR HugePages_Surp " %lu (since Linux 2.6.24)" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +This is the number of huge pages in +the pool above the value in +.IR /proc/sys/vm/nr_hugepages . +The maximum number of surplus huge pages is controlled by +.IR /proc/sys/vm/nr_overcommit_hugepages . +.TP +.IR Hugepagesize " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The size of huge pages. +.TP +.IR DirectMap4k " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 4kB pages. +(x86.) +.TP +.IR DirectMap4M " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 4MB pages. +(x86 with +.BR CONFIG_X86_64 +or +.BR CONFIG_X86_PAE +enabled.) +.TP +.IR DirectMap2M " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 2MB pages. +(x86 with neither +.BR CONFIG_X86_64 +nor +.BR CONFIG_X86_PAE +enabled.) +.TP +.IR DirectMap1G " %lu (since Linux 2.6.27)" +(x86 with +.BR CONFIG_X86_64 +and +.B CONFIG_X86_DIRECT_GBPAGES +enabled.) +.RE +.TP +.I /proc/modules +A text list of the modules that have been loaded by the system. +See also +.BR lsmod (8). +.TP +.I /proc/mounts +Before kernel 2.4.19, this file was a list +of all the filesystems currently mounted on the system. +With the introduction of per-process mount namespaces in Linux 2.4.19 (see +.BR mount_namespaces (7)), +this file became a link to +.IR /proc/self/mounts , +which lists the mount points of the process's own mount namespace. +The format of this file is documented in +.BR fstab (5). +.TP +.I /proc/mtrr +Memory Type Range Registers. +See the Linux kernel source file +.I Documentation/x86/mtrr.txt +.\" commit 7225e75144b9718cbbe1820d9c011c809d5773fd +(or +.I Documentation/mtrr.txt +before Linux 2.6.28) +for details. +.TP +.I /proc/net +This directory contains various files and subdirectories containing +information about the networking layer. +The files contain ASCII structures and are, +therefore, readable with +.BR cat (1). +However, the standard +.BR netstat (8) +suite provides much cleaner access to these files. +.IP +With the advent of network namespaces, +various information relating to the network stack is virtualized (see +.BR namespaces (7)). +Thus, since Linux 2.6.25, +.\" commit e9720acd728a46cb40daa52c99a979f7c4ff195c +.IR /proc/net +is a symbolic link to the directory +.IR /proc/self/net , +which contains the same files and directories as listed below. +However, these files and directories now expose information +for the network namespace of which the process is a member. +.TP +.I /proc/net/arp +This holds an ASCII readable dump of the kernel ARP table used for +address resolutions. +It will show both dynamically learned and preprogrammed ARP entries. +The format is: +.IP +.in 7n +.EX +IP address HW type Flags HW address Mask Device +192.168.0.50 0x1 0x2 00:50:BF:25:68:F3 * eth0 +192.168.0.250 0x1 0xc 00:00:00:00:00:00 * eth0 +.EE +.in +.IP +Here "IP address" is the IPv4 address of the machine and the "HW type" +is the hardware type of the address from RFC\ 826. +The flags are the internal +flags of the ARP structure (as defined in +.IR /usr/include/linux/if_arp.h ) +and +the "HW address" is the data link layer mapping for that IP address if +it is known. +.TP +.I /proc/net/dev +The dev pseudo-file contains network device status information. +This gives +the number of received and sent packets, the number of errors and +collisions +and other basic statistics. +These are used by the +.BR ifconfig (8) +program to report device status. +The format is: +.IP +.in 1n +.EX +Inter-| Receive | Transmit + face |bytes packets errs drop fifo frame compressed multicast|bytes packets errs drop fifo colls carrier compressed + lo: 2776770 11307 0 0 0 0 0 0 2776770 11307 0 0 0 0 0 0 + eth0: 1215645 2751 0 0 0 0 0 0 1782404 4324 0 0 0 427 0 0 + ppp0: 1622270 5552 1 0 0 0 0 0 354130 5669 0 0 0 0 0 0 + tap0: 7714 81 0 0 0 0 0 0 7714 81 0 0 0 0 0 0 +.EE +.in +.\" .TP +.\" .I /proc/net/ipx +.\" No information. +.\" .TP +.\" .I /proc/net/ipx_route +.\" No information. +.TP +.I /proc/net/dev_mcast +Defined in +.IR /usr/src/linux/net/core/dev_mcast.c : +.IP +.in +4 +.EX +indx interface_name dmi_u dmi_g dmi_address +2 eth0 1 0 01005e000001 +3 eth1 1 0 01005e000001 +4 eth2 1 0 01005e000001 +.EE +.in +.TP +.I /proc/net/igmp +Internet Group Management Protocol. +Defined in +.IR /usr/src/linux/net/core/igmp.c . +.TP +.I /proc/net/rarp +This file uses the same format as the +.I arp +file and contains the current reverse mapping database used to provide +.BR rarp (8) +reverse address lookup services. +If RARP is not configured into the +kernel, +this file will not be present. +.TP +.I /proc/net/raw +Holds a dump of the RAW socket table. +Much of the information is not of +use +apart from debugging. +The "sl" value is the kernel hash slot for the +socket, +the "local_address" is the local address and protocol number pair. +\&"St" is +the internal status of the socket. +The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields are not used by RAW. +The "uid" +field holds the effective UID of the creator of the socket. +.\" .TP +.\" .I /proc/net/route +.\" No information, but looks similar to +.\" .BR route (8). +.TP +.I /proc/net/snmp +This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP +management +information bases for an SNMP agent. +.TP +.I /proc/net/tcp +Holds a dump of the TCP socket table. +Much of the information is not +of use apart from debugging. +The "sl" value is the kernel hash slot +for the socket, the "local_address" is the local address and port number pair. +The "rem_address" is the remote address and port number pair +(if connected). +\&"St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields hold internal information of +the kernel socket state and are useful only for debugging. +The "uid" +field holds the effective UID of the creator of the socket. +.TP +.I /proc/net/udp +Holds a dump of the UDP socket table. +Much of the information is not of +use apart from debugging. +The "sl" value is the kernel hash slot for the +socket, the "local_address" is the local address and port number pair. +The "rem_address" is the remote address and port number pair +(if connected). +"St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the outgoing and incoming data queue +in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields +are not used by UDP. +The "uid" +field holds the effective UID of the creator of the socket. +The format is: +.IP +.in 1n +.EX +sl local_address rem_address st tx_queue rx_queue tr rexmits tm\->when uid + 1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 + 1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0 + 1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 +.EE +.in +.IP +.TP +.I /proc/net/unix +Lists the UNIX domain sockets present within the system and their +status. +The format is: +.IP +.in 1n +.EX +Num RefCount Protocol Flags Type St Path + 0: 00000002 00000000 00000000 0001 03 + 1: 00000001 00000000 00010000 0001 01 /dev/printer +.EE +.in +.IP +The fields are as follows: +.RS +.TP 10 +.IR Num : +the kernel table slot number. +.TP +.IR RefCount : +the number of users of the socket. +.TP +.IR Protocol : +currently always 0. +.TP +.IR Flags : +the internal kernel flags holding the status of the socket. +.TP +.IR Type : +the socket type. +For +.BR SOCK_STREAM +sockets, this is 0001; for +.BR SOCK_DGRAM +sockets, it is 0002; and for +.BR SOCK_SEQPACKET +sockets, it is 0005. +.TP +.IR St : +the internal state of the socket. +.TP +.IR Path : +the bound path (if any) of the socket. +Sockets in the abstract namespace are included in the list, +and are shown with a +.I Path +that commences with the character '@'. +.RE +.TP +.I /proc/net/netfilter/nfnetlink_queue +This file contains information about netfilter user-space queueing, if used. +Each line represents a queue. +Queues that have not been subscribed to +by user space are not shown. +.IP +.in +4n +.EX + 1 4207 0 2 65535 0 0 0 1 + (1) (2) (3)(4) (5) (6) (7) (8) +.EE +.in +.IP +The fields in each line are: +.RS 7 +.TP 5 +(1) +The ID of the queue. +This matches what is specified in the +.B \-\-queue\-num +or +.B \-\-queue\-balance +options to the +.BR iptables (8) +NFQUEUE target. +See +.BR iptables-extensions (8) +for more information. +.TP +(2) +The netlink port ID subscribed to the queue. +.TP +(3) +The number of packets currently queued and waiting to be processed by +the application. +.TP +(4) +The copy mode of the queue. +It is either 1 (metadata only) or 2 +(also copy payload data to user space). +.TP +(5) +Copy range; that is, how many bytes of packet payload should be copied to +user space at most. +.TP +(6) +queue dropped. +Number of packets that had to be dropped by the kernel because +too many packets are already waiting for user space to send back the mandatory +accept/drop verdicts. +.TP +(7) +queue user dropped. +Number of packets that were dropped within the netlink +subsystem. +Such drops usually happen when the corresponding socket buffer is +full; that is, user space is not able to read messages fast enough. +.TP +(8) +sequence number. +Every queued packet is associated with a (32-bit) +monotonically-increasing sequence number. +This shows the ID of the most recent packet queued. +.RE +.IP +The last number exists only for compatibility reasons and is always 1. +.TP +.I /proc/partitions +Contains the major and minor numbers of each partition as well as the number +of 1024-byte blocks and the partition name. +.TP +.I /proc/pci +This is a listing of all PCI devices found during kernel initialization +and their configuration. +.IP +This file has been deprecated in favor of a new +.I /proc +interface for PCI +.RI ( /proc/bus/pci ). +It became optional in Linux 2.2 (available with +.B CONFIG_PCI_OLD_PROC +set at kernel compilation). +It became once more nonoptionally enabled in Linux 2.4. +Next, it was deprecated in Linux 2.6 (still available with +.B CONFIG_PCI_LEGACY_PROC +set), and finally removed altogether since Linux 2.6.17. +.\" FIXME Document /proc/sched_debug (since Linux 2.6.23) +.\" See also /proc/[pid]/sched +.TP +.IR /proc/profile " (since Linux 2.4)" +This file is present only if the kernel was booted with the +.I profile=1 +command-line option. +It exposes kernel profiling information in a binary format for use by +.BR readprofile (1). +Writing (e.g., an empty string) to this file resets the profiling counters; +on some architectures, +writing a binary integer "profiling multiplier" of size +.IR sizeof(int) +sets the profiling interrupt frequency. +.TP +.I /proc/scsi +A directory with the +.I scsi +mid-level pseudo-file and various SCSI low-level +driver directories, +which contain a file for each SCSI host in this system, all of +which give the status of some part of the SCSI IO subsystem. +These files contain ASCII structures and are, therefore, readable with +.BR cat (1). +.IP +You can also write to some of the files to reconfigure the subsystem or +switch certain features on or off. +.TP +.I /proc/scsi/scsi +This is a listing of all SCSI devices known to the kernel. +The listing is similar to the one seen during bootup. +scsi currently supports only the \fIadd-single-device\fP command which +allows root to add a hotplugged device to the list of known devices. +.IP +The command +.IP +.in +4n +.EX +echo \(aqscsi add-single-device 1 0 5 0\(aq > /proc/scsi/scsi +.EE +.in +.IP +will cause +host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. +If there +is already a device known on this address or the address is invalid, an +error will be returned. +.TP +.I /proc/scsi/[drivername] +\fI[drivername]\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740, +aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, +scsi_debug, seagate, t128, u15-24f, ultrastore, or wd7000. +These directories show up for all drivers that registered at least one +SCSI HBA. +Every directory contains one file per registered host. +Every host-file is named after the number the host was assigned during +initialization. +.IP +Reading these files will usually show driver and host configuration, +statistics, and so on. +.IP +Writing to these files allows different things on different hosts. +For example, with the \fIlatency\fP and \fInolatency\fP commands, +root can switch on and off command latency measurement code in the +eata_dma driver. +With the \fIlockup\fP and \fIunlock\fP commands, +root can control bus lockups simulated by the scsi_debug driver. +.TP +.I /proc/self +This directory refers to the process accessing the +.I /proc +filesystem, +and is identical to the +.I /proc +directory named by the process ID of the same process. +.TP +.I /proc/slabinfo +Information about kernel caches. +See +.BR slabinfo (5) +for details. +.TP +.I /proc/stat +kernel/system statistics. +Varies with architecture. +Common +entries include: +.RS +.TP +.I cpu 10132153 290696 3084719 46828483 16683 0 25195 0 175628 0 +.TQ +.I cpu0 1393280 32966 572056 13343292 6130 0 17875 0 23933 0 +The amount of time, measured in units of +USER_HZ (1/100ths of a second on most architectures, use +.IR sysconf(_SC_CLK_TCK) +to obtain the right value), +.\" 1024 on Alpha and ia64 +that the system ("cpu" line) or the specific CPU ("cpu\fIN\fR" line) +spent in various states: +.RS +.TP +.I user +(1) Time spent in user mode. +.TP +.I nice +(2) Time spent in user mode with low priority (nice). +.TP +.I system +(3) Time spent in system mode. +.TP +.I idle +(4) Time spent in the idle task. +.\" FIXME . Actually, the following info about the /proc/stat 'cpu' field +.\" does not seem to be quite right (at least in 2.6.12 or 3.6): +.\" the idle time in /proc/uptime does not quite match this value +This value should be USER_HZ times the +second entry in the +.I /proc/uptime +pseudo-file. +.TP +.IR iowait " (since Linux 2.5.41)" +(5) Time waiting for I/O to complete. +This value is not reliable, for the following reasons: +.\" See kernel commit 9c240d757658a3ae9968dd309e674c61f07c7f48 +.RS +.IP 1. 3 +The CPU will not wait for I/O to complete; +iowait is the time that a task is waiting for I/O to complete. +When a CPU goes into idle state for outstanding task I/O, +another task will be scheduled on this CPU. +.IP 2. +On a multi-core CPU, +the task waiting for I/O to complete is not running on any CPU, +so the iowait of each CPU is difficult to calculate. +.IP 3. +The value in this field may +.I decrease +in certain conditions. +.RE +.TP +.IR irq " (since Linux 2.6.0-test4)" +(6) Time servicing interrupts. +.TP +.IR softirq " (since Linux 2.6.0-test4)" +(7) Time servicing softirqs. +.TP +.IR steal " (since Linux 2.6.11)" +(8) Stolen time, which is the time spent in other operating systems when +running in a virtualized environment +.TP +.IR guest " (since Linux 2.6.24)" +(9) Time spent running a virtual CPU for guest +operating systems under the control of the Linux kernel. +.\" See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de +.TP +.IR guest_nice " (since Linux 2.6.33)" +.\" commit ce0e7b28fb75cb003cfc8d0238613aaf1c55e797 +(10) Time spent running a niced guest (virtual CPU for guest +operating systems under the control of the Linux kernel). +.RE +.TP +\fIpage 5741 1808\fP +The number of pages the system paged in and the number that were paged +out (from disk). +.TP +\fIswap 1 0\fP +The number of swap pages that have been brought in and out. +.TP +.\" FIXME . The following is not the full picture for the 'intr' of +.\" /proc/stat on 2.6: +\fIintr 1462898\fP +This line shows counts of interrupts serviced since boot time, +for each of the possible system interrupts. +The first column is the total of all interrupts serviced +including unnumbered architecture specific interrupts; +each subsequent column is the total for that particular numbered interrupt. +Unnumbered interrupts are not shown, only summed into the total. +.TP +\fIdisk_io: (2,0):(31,30,5764,1,2) (3,0):\fP... +(major,disk_idx):(noinfo, read_io_ops, blks_read, write_io_ops, blks_written) +.br +(Linux 2.4 only) +.TP +\fIctxt 115315\fP +The number of context switches that the system underwent. +.TP +\fIbtime 769041601\fP +boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.TP +\fIprocesses 86031\fP +Number of forks since boot. +.TP +\fIprocs_running 6\fP +Number of processes in runnable state. +(Linux 2.5.45 onward.) +.TP +\fIprocs_blocked 2\fP +Number of processes blocked waiting for I/O to complete. +(Linux 2.5.45 onward.) +.TP +.I softirq 229245889 94 60001584 13619 5175704 2471304 28 51212741 59130143 0 51240672 +.\" commit d3d64df21d3d0de675a0d3ffa7c10514f3644b30 +This line shows the number of softirq for all CPUs. +The first column is the total of all softirqs and +each subsequent column is the total for particular softirq. +(Linux 2.6.31 onward.) +.RE +.TP +.I /proc/swaps +Swap areas in use. +See also +.BR swapon (8). +.TP +.I /proc/sys +This directory (present since 1.3.57) contains a number of files +and subdirectories corresponding to kernel variables. +These variables can be read and sometimes modified using +the \fI/proc\fP filesystem, and the (deprecated) +.BR sysctl (2) +system call. +.IP +String values may be terminated by either \(aq\\0\(aq or \(aq\\n\(aq. +.IP +Integer and long values may be written either in decimal or in +hexadecimal notation (e.g. 0x3FFF). +When writing multiple integer or long values, these may be separated +by any of the following whitespace characters: +\(aq\ \(aq, \(aq\\t\(aq, or \(aq\\n\(aq. +Using other separators leads to the error +.BR EINVAL . +.TP +.IR /proc/sys/abi " (since Linux 2.4.10)" +This directory may contain files with application binary information. +.\" On some systems, it is not present. +See the Linux kernel source file +.I Documentation/sysctl/abi.txt +for more information. +.TP +.I /proc/sys/debug +This directory may be empty. +.TP +.I /proc/sys/dev +This directory contains device-specific information (e.g., +.IR dev/cdrom/info ). +On +some systems, it may be empty. +.TP +.I /proc/sys/fs +This directory contains the files and subdirectories for kernel variables +related to filesystems. +.TP +.I /proc/sys/fs/binfmt_misc +Documentation for files in this directory can be found +in the Linux kernel source in the file +.IR Documentation/admin-guide/binfmt-misc.rst +(or in +.IR Documentation/binfmt_misc.txt +on older kernels). +.TP +.IR /proc/sys/fs/dentry-state " (since Linux 2.2)" +This file contains information about the status of the +directory cache (dcache). +The file contains six numbers, +.IR nr_dentry ", " nr_unused ", " age_limit " (age in seconds), " +.I want_pages +(pages requested by system) and two dummy values. +.RS +.IP * 2 +.I nr_dentry +is the number of allocated dentries (dcache entries). +This field is unused in Linux 2.2. +.IP * +.I nr_unused +is the number of unused dentries. +.IP * +.I age_limit +.\" looks like this is unused in kernels 2.2 to 2.6 +is the age in seconds after which dcache entries +can be reclaimed when memory is short. +.IP * +.I want_pages +.\" looks like this is unused in kernels 2.2 to 2.6 +is nonzero when the kernel has called shrink_dcache_pages() and the +dcache isn't pruned yet. +.RE +.TP +.I /proc/sys/fs/dir-notify-enable +This file can be used to disable or enable the +.I dnotify +interface described in +.BR fcntl (2) +on a system-wide basis. +A value of 0 in this file disables the interface, +and a value of 1 enables it. +.TP +.I /proc/sys/fs/dquot-max +This file shows the maximum number of cached disk quota entries. +On some (2.4) systems, it is not present. +If the number of free cached disk quota entries is very low and +you have some awesome number of simultaneous system users, +you might want to raise the limit. +.TP +.I /proc/sys/fs/dquot-nr +This file shows the number of allocated disk quota +entries and the number of free disk quota entries. +.TP +.IR /proc/sys/fs/epoll " (since Linux 2.6.28)" +This directory contains the file +.IR max_user_watches , +which can be used to limit the amount of kernel memory consumed by the +.I epoll +interface. +For further details, see +.BR epoll (7). +.TP +.I /proc/sys/fs/file-max +This file defines +a system-wide limit on the number of open files for all processes. +System calls that fail when encountering this limit fail with the error +.BR ENFILE . +(See also +.BR setrlimit (2), +which can be used by a process to set the per-process limit, +.BR RLIMIT_NOFILE , +on the number of files it may open.) +If you get lots +of error messages in the kernel log about running out of file handles +(look for "VFS: file-max limit reached"), +try increasing this value: +.IP +.in +4n +.EX +echo 100000 > /proc/sys/fs/file-max +.EE +.in +.IP +Privileged processes +.RB ( CAP_SYS_ADMIN ) +can override the +.I file-max +limit. +.TP +.I /proc/sys/fs/file-nr +This (read-only) file contains three numbers: +the number of allocated file handles +(i.e., the number of files presently opened); +the number of free file handles; +and the maximum number of file handles (i.e., the same value as +.IR /proc/sys/fs/file-max ). +If the number of allocated file handles is close to the +maximum, you should consider increasing the maximum. +Before Linux 2.6, +the kernel allocated file handles dynamically, +but it didn't free them again. +Instead the free file handles were kept in a list for reallocation; +the "free file handles" value indicates the size of that list. +A large number of free file handles indicates that there was +a past peak in the usage of open file handles. +Since Linux 2.6, the kernel does deallocate freed file handles, +and the "free file handles" value is always zero. +.TP +.IR /proc/sys/fs/inode-max " (only present until Linux 2.2)" +This file contains the maximum number of in-memory inodes. +This value should be 3\(en4 times larger +than the value in +.IR file-max , +since \fIstdin\fP, \fIstdout\fP +and network sockets also need an inode to handle them. +When you regularly run out of inodes, you need to increase this value. +.IP +Starting with Linux 2.4, +there is no longer a static limit on the number of inodes, +and this file is removed. +.TP +.I /proc/sys/fs/inode-nr +This file contains the first two values from +.IR inode-state . +.TP +.I /proc/sys/fs/inode-state +This file +contains seven numbers: +.IR nr_inodes , +.IR nr_free_inodes , +.IR preshrink , +and four dummy values (always zero). +.IP +.I nr_inodes +is the number of inodes the system has allocated. +.\" This can be slightly more than +.\" .I inode-max +.\" because Linux allocates them one page full at a time. +.I nr_free_inodes +represents the number of free inodes. +.IP +.I preshrink +is nonzero when the +.I nr_inodes +> +.I inode-max +and the system needs to prune the inode list instead of allocating more; +since Linux 2.4, this field is a dummy value (always zero). +.TP +.IR /proc/sys/fs/inotify " (since Linux 2.6.13)" +This directory contains files +.IR max_queued_events ", " max_user_instances ", and " max_user_watches , +that can be used to limit the amount of kernel memory consumed by the +.I inotify +interface. +For further details, see +.BR inotify (7). +.TP +.I /proc/sys/fs/lease-break-time +This file specifies the grace period that the kernel grants to a process +holding a file lease +.RB ( fcntl (2)) +after it has sent a signal to that process notifying it +that another process is waiting to open the file. +If the lease holder does not remove or downgrade the lease within +this grace period, the kernel forcibly breaks the lease. +.TP +.I /proc/sys/fs/leases-enable +This file can be used to enable or disable file leases +.RB ( fcntl (2)) +on a system-wide basis. +If this file contains the value 0, leases are disabled. +A nonzero value enables leases. +.TP +.IR /proc/sys/fs/mount-max " (since Linux 4.9)" +.\" commit d29216842a85c7970c536108e093963f02714498 +The value in this file specifies the maximum number of mounts that may exist +in a mount namespace. +The default value in this file is 100,000. +.TP +.IR /proc/sys/fs/mqueue " (since Linux 2.6.6)" +This directory contains files +.IR msg_max ", " msgsize_max ", and " queues_max , +controlling the resources used by POSIX message queues. +See +.BR mq_overview (7) +for details. +.TP +.IR /proc/sys/fs/nr_open " (since Linux 2.6.25) +.\" commit 9cfe015aa424b3c003baba3841a60dd9b5ad319b +This file imposes ceiling on the value to which the +.BR RLIMIT_NOFILE +resource limit can be raised (see +.BR getrlimit (2)). +This ceiling is enforced for both unprivileged and privileged process. +The default value in this file is 1048576. +(Before Linux 2.6.25, the ceiling for +.BR RLIMIT_NOFILE +was hard-coded to the same value.) +.TP +.IR /proc/sys/fs/overflowgid " and " /proc/sys/fs/overflowuid +These files +allow you to change the value of the fixed UID and GID. +The default is 65534. +Some filesystems support only 16-bit UIDs and GIDs, although in Linux +UIDs and GIDs are 32 bits. +When one of these filesystems is mounted +with writes enabled, any UID or GID that would exceed 65535 is translated +to the overflow value before being written to disk. +.TP +.IR /proc/sys/fs/pipe-max-size " (since Linux 2.6.35)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/pipe-user-pages-hard " (since Linux 4.5)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/pipe-user-pages-soft " (since Linux 4.5)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/protected_hardlinks " (since Linux 3.6)" +.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 +When the value in this file is 0, +no restrictions are placed on the creation of hard links +(i.e., this is the historical behavior before Linux 3.6). +When the value in this file is 1, +a hard link can be created to a target file +only if one of the following conditions is true: +.RS +.IP * 3 +The calling process has the +.BR CAP_FOWNER +capability in its user namespace +and the file UID has a mapping in the namespace. +.IP * +The filesystem UID of the process creating the link matches +the owner (UID) of the target file +(as described in +.BR credentials (7), +a process's filesystem UID is normally the same as its effective UID). +.IP * +All of the following conditions are true: +.RS 4 +.IP \(bu 3 +the target is a regular file; +.IP \(bu +the target file does not have its set-user-ID mode bit enabled; +.IP \(bu +the target file does not have both its set-group-ID and +group-executable mode bits enabled; and +.IP \(bu +the caller has permission to read and write the target file +(either via the file's permissions mask or because it has +suitable capabilities). +.RE +.RE +.IP +The default value in this file is 0. +Setting the value to 1 +prevents a longstanding class of security issues caused by +hard-link-based time-of-check, time-of-use races, +most commonly seen in world-writable directories such as +.IR /tmp . +The common method of exploiting this flaw +is to cross privilege boundaries when following a given hard link +(i.e., a root process follows a hard link created by another user). +Additionally, on systems without separated partitions, +this stops unauthorized users from "pinning" vulnerable set-user-ID and +set-group-ID files against being upgraded by +the administrator, or linking to special files. +.TP +.IR /proc/sys/fs/protected_symlinks " (since Linux 3.6)" +.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 +When the value in this file is 0, +no restrictions are placed on following symbolic links +(i.e., this is the historical behavior before Linux 3.6). +When the value in this file is 1, symbolic links are followed only +in the following circumstances: +.RS +.IP * 3 +the filesystem UID of the process following the link matches +the owner (UID) of the symbolic link +(as described in +.BR credentials (7), +a process's filesystem UID is normally the same as its effective UID); +.IP * +the link is not in a sticky world-writable directory; or +.IP * +the symbolic link and its parent directory have the same owner (UID) +.RE +.IP +A system call that fails to follow a symbolic link +because of the above restrictions returns the error +.BR EACCES +in +.IR errno . +.IP +The default value in this file is 0. +Setting the value to 1 avoids a longstanding class of security issues +based on time-of-check, time-of-use races when accessing symbolic links. +.TP +.IR /proc/sys/fs/suid_dumpable " (since Linux 2.6.13)" +.\" The following is based on text from Documentation/sysctl/kernel.txt +The value in this file is assigned to a process's "dumpable" flag +in the circumstances described in +.BR prctl (2). +In effect, +the value in this file determines whether core dump files are +produced for set-user-ID or otherwise protected/tainted binaries. +The "dumpable" setting also affects the ownership of files in a process's +.IR /proc/[pid] +directory, as described above. +.IP +Three different integer values can be specified: +.RS +.TP +\fI0\ (default)\fP +.\" In kernel source: SUID_DUMP_DISABLE +This provides the traditional (pre-Linux 2.6.13) behavior. +A core dump will not be produced for a process which has +changed credentials (by calling +.BR seteuid (2), +.BR setgid (2), +or similar, or by executing a set-user-ID or set-group-ID program) +or whose binary does not have read permission enabled. +.TP +\fI1\ ("debug")\fP +.\" In kernel source: SUID_DUMP_USER +All processes dump core when possible. +(Reasons why a process might nevertheless not dump core are described in +.BR core (5).) +The core dump is owned by the filesystem user ID of the dumping process +and no security is applied. +This is intended for system debugging situations only: +this mode is insecure because it allows unprivileged users to +examine the memory contents of privileged processes. +.TP +\fI2\ ("suidsafe")\fP +.\" In kernel source: SUID_DUMP_ROOT +Any binary which normally would not be dumped (see "0" above) +is dumped readable by root only. +This allows the user to remove the core dump file but not to read it. +For security reasons core dumps in this mode will not overwrite one +another or other files. +This mode is appropriate when administrators are +attempting to debug problems in a normal environment. +.IP +Additionally, since Linux 3.6, +.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 +.I /proc/sys/kernel/core_pattern +must either be an absolute pathname +or a pipe command, as detailed in +.BR core (5). +Warnings will be written to the kernel log if +.I core_pattern +does not follow these rules, and no core dump will be produced. +.\" 54b501992dd2a839e94e76aa392c392b55080ce8 +.RE +.IP +For details of the effect of a process's "dumpable" setting +on ptrace access mode checking, see +.BR ptrace (2). +.TP +.I /proc/sys/fs/super-max +This file +controls the maximum number of superblocks, and +thus the maximum number of mounted filesystems the kernel +can have. +You need increase only +.I super-max +if you need to mount more filesystems than the current value in +.I super-max +allows you to. +.TP +.I /proc/sys/fs/super-nr +This file +contains the number of filesystems currently mounted. +.TP +.I /proc/sys/kernel +This directory contains files controlling a range of kernel parameters, +as described below. +.TP +.I /proc/sys/kernel/acct +This file +contains three numbers: +.IR highwater , +.IR lowwater , +and +.IR frequency . +If BSD-style process accounting is enabled, these values control +its behavior. +If free space on filesystem where the log lives goes below +.I lowwater +percent, accounting suspends. +If free space gets above +.I highwater +percent, accounting resumes. +.I frequency +determines +how often the kernel checks the amount of free space (value is in +seconds). +Default values are 4, 2 and 30. +That is, suspend accounting if 2% or less space is free; resume it +if 4% or more space is free; consider information about amount of free space +valid for 30 seconds. +.TP +.IR /proc/sys/kernel/auto_msgmni " (Linux 2.6.27 to 3.18)" +.\" commit 9eefe520c814f6f62c5d36a2ddcd3fb99dfdb30e (introduces feature) +.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 (rendered redundant) +From Linux 2.6.27 to 3.18, +this file was used to control recomputing of the value in +.IR /proc/sys/kernel/msgmni +upon the addition or removal of memory or upon IPC namespace creation/removal. +Echoing "1" into this file enabled +.I msgmni +automatic recomputing (and triggered a recomputation of +.I msgmni +based on the current amount of available memory and number of IPC namespaces). +Echoing "0" disabled automatic recomputing. +(Automatic recomputing was also disabled if a value was explicitly assigned to +.IR /proc/sys/kernel/msgmni .) +The default value in +.I auto_msgmni +was 1. +.IP +Since Linux 3.19, the content of this file has no effect (because +.IR msgmni +.\" FIXME Must document the 3.19 'msgmni' changes. +defaults to near the maximum value possible), +and reads from this file always return the value "0". +.TP +.IR /proc/sys/kernel/cap_last_cap " (since Linux 3.2)" +See +.BR capabilities (7). +.TP +.IR /proc/sys/kernel/cap-bound " (from Linux 2.2 to 2.6.24)" +This file holds the value of the kernel +.I "capability bounding set" +(expressed as a signed decimal number). +This set is ANDed against the capabilities permitted to a process +during +.BR execve (2). +Starting with Linux 2.6.25, +the system-wide capability bounding set disappeared, +and was replaced by a per-thread bounding set; see +.BR capabilities (7). +.TP +.I /proc/sys/kernel/core_pattern +See +.BR core (5). +.TP +.I /proc/sys/kernel/core_pipe_limit +See +.BR core (5). +.TP +.I /proc/sys/kernel/core_uses_pid +See +.BR core (5). +.TP +.I /proc/sys/kernel/ctrl-alt-del +This file +controls the handling of Ctrl-Alt-Del from the keyboard. +When the value in this file is 0, Ctrl-Alt-Del is trapped and +sent to the +.BR init (1) +program to handle a graceful restart. +When the value is greater than zero, Linux's reaction to a Vulcan +Nerve Pinch (tm) will be an immediate reboot, without even +syncing its dirty buffers. +Note: when a program (like dosemu) has the keyboard in "raw" +mode, the ctrl-alt-del is intercepted by the program before it +ever reaches the kernel tty layer, and it's up to the program +to decide what to do with it. +.TP +.IR /proc/sys/kernel/dmesg_restrict " (since Linux 2.6.37)" +The value in this file determines who can see kernel syslog contents. +A value of 0 in this file imposes no restrictions. +If the value is 1, only privileged users can read the kernel syslog. +(See +.BR syslog (2) +for more details.) +Since Linux 3.4, +.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 +only users with the +.BR CAP_SYS_ADMIN +capability may change the value in this file. +.TP +.IR /proc/sys/kernel/domainname " and " /proc/sys/kernel/hostname +can be used to set the NIS/YP domainname and the +hostname of your box in exactly the same way as the commands +.BR domainname (1) +and +.BR hostname (1), +that is: +.IP +.in +4n +.EX +.RB "#" " echo \(aqdarkstar\(aq > /proc/sys/kernel/hostname" +.RB "#" " echo \(aqmydomain\(aq > /proc/sys/kernel/domainname" +.EE +.in +.IP +has the same effect as +.IP +.in +4n +.EX +.RB "#" " hostname \(aqdarkstar\(aq" +.RB "#" " domainname \(aqmydomain\(aq" +.EE +.in +.IP +Note, however, that the classic darkstar.frop.org has the +hostname "darkstar" and DNS (Internet Domain Name Server) +domainname "frop.org", not to be confused with the NIS (Network +Information Service) or YP (Yellow Pages) domainname. +These two +domain names are in general different. +For a detailed discussion +see the +.BR hostname (1) +man page. +.TP +.I /proc/sys/kernel/hotplug +This file +contains the path for the hotplug policy agent. +The default value in this file is +.IR /sbin/hotplug . +.TP +.\" Removed in commit 87f504e5c78b910b0c1d6ffb89bc95e492322c84 (tglx/history.git) +.IR /proc/sys/kernel/htab-reclaim " (before Linux 2.4.9.2)" +(PowerPC only) If this file is set to a nonzero value, +the PowerPC htab +.\" removed in commit 1b483a6a7b2998e9c98ad985d7494b9b725bd228, before 2.6.28 +(see kernel file +.IR Documentation/powerpc/ppc_htab.txt ) +is pruned +each time the system hits the idle loop. +.TP +.IR /proc/sys/kernel/keys/* +This directory contains various files that define parameters and limits +for the key-management facility. +These files are described in +.BR keyrings (7). +.TP +.IR /proc/sys/kernel/kptr_restrict " (since Linux 2.6.38)" +.\" 455cd5ab305c90ffc422dd2e0fb634730942b257 +The value in this file determines whether kernel addresses are exposed via +.I /proc +files and other interfaces. +A value of 0 in this file imposes no restrictions. +If the value is 1, kernel pointers printed using the +.I %pK +format specifier will be replaced with zeros unless the user has the +.BR CAP_SYSLOG +capability. +If the value is 2, kernel pointers printed using the +.I %pK +format specifier will be replaced with zeros regardless +of the user's capabilities. +The initial default value for this file was 1, +but the default was changed +.\" commit 411f05f123cbd7f8aa1edcae86970755a6e2a9d9 +to 0 in Linux 2.6.39. +Since Linux 3.4, +.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 +only users with the +.BR CAP_SYS_ADMIN +capability can change the value in this file. +.TP +.I /proc/sys/kernel/l2cr +(PowerPC only) This file +contains a flag that controls the L2 cache of G3 processor +boards. +If 0, the cache is disabled. +Enabled if nonzero. +.TP +.I /proc/sys/kernel/modprobe +This file contains the path for the kernel module loader. +The default value is +.IR /sbin/modprobe . +The file is present only if the kernel is built with the +.B CONFIG_MODULES +.RB ( CONFIG_KMOD +in Linux 2.6.26 and earlier) +option enabled. +It is described by the Linux kernel source file +.I Documentation/kmod.txt +(present only in kernel 2.4 and earlier). +.TP +.IR /proc/sys/kernel/modules_disabled " (since Linux 2.6.31)" +.\" 3d43321b7015387cfebbe26436d0e9d299162ea1 +.\" From Documentation/sysctl/kernel.txt +A toggle value indicating if modules are allowed to be loaded +in an otherwise modular kernel. +This toggle defaults to off (0), but can be set true (1). +Once true, modules can be neither loaded nor unloaded, +and the toggle cannot be set back to false. +The file is present only if the kernel is built with the +.B CONFIG_MODULES +option enabled. +.TP +.IR /proc/sys/kernel/msgmax " (since Linux 2.2)" +This file defines +a system-wide limit specifying the maximum number of bytes in +a single message written on a System V message queue. +.TP +.IR /proc/sys/kernel/msgmni " (since Linux 2.4)" +This file defines the system-wide limit on the number of +message queue identifiers. +See also +.IR /proc/sys/kernel/auto_msgmni . +.TP +.IR /proc/sys/kernel/msgmnb " (since Linux 2.2)" +This file defines a system-wide parameter used to initialize the +.I msg_qbytes +setting for subsequently created message queues. +The +.I msg_qbytes +setting specifies the maximum number of bytes that may be written to the +message queue. +.TP +.IR /proc/sys/kernel/ngroups_max " (since Linux 2.6.4)" +This is a read-only file that displays the upper limit on the +number of a process's group memberships. +.TP +.IR /proc/sys/kernel/ns_last_pid " (since Linux 3.3)" +See +.BR pid_namespaces (7). +.TP +.IR /proc/sys/kernel/ostype " and " /proc/sys/kernel/osrelease +These files +give substrings of +.IR /proc/version . +.TP +.IR /proc/sys/kernel/overflowgid " and " /proc/sys/kernel/overflowuid +These files duplicate the files +.I /proc/sys/fs/overflowgid +and +.IR /proc/sys/fs/overflowuid . +.TP +.I /proc/sys/kernel/panic +This file gives read/write access to the kernel variable +.IR panic_timeout . +If this is zero, the kernel will loop on a panic; if nonzero, +it indicates that the kernel should autoreboot after this number +of seconds. +When you use the +software watchdog device driver, the recommended setting is 60. +.TP +.IR /proc/sys/kernel/panic_on_oops " (since Linux 2.5.68)" +This file controls the kernel's behavior when an oops +or BUG is encountered. +If this file contains 0, then the system +tries to continue operation. +If it contains 1, then the system +delays a few seconds (to give klogd time to record the oops output) +and then panics. +If the +.I /proc/sys/kernel/panic +file is also nonzero, then the machine will be rebooted. +.TP +.IR /proc/sys/kernel/pid_max " (since Linux 2.5.34)" +This file specifies the value at which PIDs wrap around +(i.e., the value in this file is one greater than the maximum PID). +PIDs greater than this value are not allocated; +thus, the value in this file also acts as a system-wide limit +on the total number of processes and threads. +The default value for this file, 32768, +results in the same range of PIDs as on earlier kernels. +On 32-bit platforms, 32768 is the maximum value for +.IR pid_max . +On 64-bit systems, +.I pid_max +can be set to any value up to 2^22 +.RB ( PID_MAX_LIMIT , +approximately 4 million). +.\" Prior to 2.6.10, pid_max could also be raised above 32768 on 32-bit +.\" platforms, but this broke /proc/[pid] +.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=109513010926152&w=2 +.TP +.IR /proc/sys/kernel/powersave-nap " (PowerPC only)" +This file contains a flag. +If set, Linux-PPC will use the "nap" mode of +powersaving, +otherwise the "doze" mode will be used. +.TP +.I /proc/sys/kernel/printk +See +.BR syslog (2). +.TP +.IR /proc/sys/kernel/pty " (since Linux 2.6.4)" +This directory contains two files relating to the number of UNIX 98 +pseudoterminals (see +.BR pts (4)) +on the system. +.TP +.I /proc/sys/kernel/pty/max +This file defines the maximum number of pseudoterminals. +.\" FIXME Document /proc/sys/kernel/pty/reserve +.\" New in Linux 3.3 +.\" commit e9aba5158a80098447ff207a452a3418ae7ee386 +.TP +.I /proc/sys/kernel/pty/nr +This read-only file +indicates how many pseudoterminals are currently in use. +.TP +.I /proc/sys/kernel/random +This directory +contains various parameters controlling the operation of the file +.IR /dev/random . +See +.BR random (4) +for further information. +.TP +.IR /proc/sys/kernel/random/uuid " (since Linux 2.4)" +Each read from this read-only file returns a randomly generated 128-bit UUID, +as a string in the standard UUID format. +.TP +.IR /proc/sys/kernel/randomize_va_space " (since Linux 2.6.12)" +.\" Some further details can be found in Documentation/sysctl/kernel.txt +Select the address space layout randomization (ASLR) policy for the system +(on architectures that support ASLR). +Three values are supported for this file: +.RS +.IP 0 3 +Turn ASLR off. +This is the default for architectures that don't support ASLR, +and when the kernel is booted with the +.I norandmaps +parameter. +.IP 1 +Make the addresses of +.BR mmap (2) +allocations, the stack, and the VDSO page randomized. +Among other things, this means that shared libraries will be +loaded at randomized addresses. +The text segment of PIE-linked binaries will also be loaded +at a randomized address. +This value is the default if the kernel was configured with +.BR CONFIG_COMPAT_BRK . +.IP 2 +(Since Linux 2.6.25) +.\" commit c1d171a002942ea2d93b4fbd0c9583c56fce0772 +Also support heap randomization. +This value is the default if the kernel was not configured with +.BR CONFIG_COMPAT_BRK . +.RE +.TP +.I /proc/sys/kernel/real-root-dev +This file is documented in the Linux kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10). +.TP +.IR /proc/sys/kernel/reboot-cmd " (Sparc only) " +This file seems to be a way to give an argument to the SPARC +ROM/Flash boot loader. +Maybe to tell it what to do after +rebooting? +.TP +.I /proc/sys/kernel/rtsig-max +(Only in kernels up to and including 2.6.7; see +.BR setrlimit (2)) +This file can be used to tune the maximum number +of POSIX real-time (queued) signals that can be outstanding +in the system. +.TP +.I /proc/sys/kernel/rtsig-nr +(Only in kernels up to and including 2.6.7.) +This file shows the number of POSIX real-time signals currently queued. +.TP +.IR /proc/[pid]/sched_autogroup_enabled " (since Linux 2.6.38)" +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/sched_child_runs_first " (since Linux 2.6.23)" +If this file contains the value zero, then, after a +.BR fork (2), +the parent is first scheduled on the CPU. +If the file contains a nonzero value, +then the child is scheduled first on the CPU. +(Of course, on a multiprocessor system, +the parent and the child might both immediately be scheduled on a CPU.) +.TP +.IR /proc/sys/kernel/sched_rr_timeslice_ms " (since Linux 3.9)" +See +.BR sched_rr_get_interval (2). +.TP +.IR /proc/sys/kernel/sched_rt_period_us " (since Linux 2.6.25)" +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/sched_rt_runtime_us " (since Linux 2.6.25)" +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/seccomp " (since Linux 4.14)" +.\" commit 8e5f1ad116df6b0de65eac458d5e7c318d1c05af +This directory provides additional seccomp information and +configuration. +See +.BR seccomp (2) +for further details. +.TP +.IR /proc/sys/kernel/sem " (since Linux 2.4)" +This file contains 4 numbers defining limits for System V IPC semaphores. +These fields are, in order: +.RS +.IP SEMMSL 8 +The maximum semaphores per semaphore set. +.IP SEMMNS 8 +A system-wide limit on the number of semaphores in all semaphore sets. +.IP SEMOPM 8 +The maximum number of operations that may be specified in a +.BR semop (2) +call. +.IP SEMMNI 8 +A system-wide limit on the maximum number of semaphore identifiers. +.RE +.TP +.I /proc/sys/kernel/sg-big-buff +This file +shows the size of the generic SCSI device (sg) buffer. +You can't tune it just yet, but you could change it at +compile time by editing +.I include/scsi/sg.h +and changing +the value of +.BR SG_BIG_BUFF . +However, there shouldn't be any reason to change this value. +.TP +.IR /proc/sys/kernel/shm_rmid_forced " (since Linux 3.1)" +.\" commit b34a6b1da371ed8af1221459a18c67970f7e3d53 +.\" See also Documentation/sysctl/kernel.txt +If this file is set to 1, all System V shared memory segments will +be marked for destruction as soon as the number of attached processes +falls to zero; +in other words, it is no longer possible to create shared memory segments +that exist independently of any attached process. +.IP +The effect is as though a +.BR shmctl (2) +.B IPC_RMID +is performed on all existing segments as well as all segments +created in the future (until this file is reset to 0). +Note that existing segments that are attached to no process will be +immediately destroyed when this file is set to 1. +Setting this option will also destroy segments that were created, +but never attached, +upon termination of the process that created the segment with +.BR shmget (2). +.IP +Setting this file to 1 provides a way of ensuring that +all System V shared memory segments are counted against the +resource usage and resource limits (see the description of +.B RLIMIT_AS +in +.BR getrlimit (2)) +of at least one process. +.IP +Because setting this file to 1 produces behavior that is nonstandard +and could also break existing applications, +the default value in this file is 0. +Set this file to 1 only if you have a good understanding +of the semantics of the applications using +System V shared memory on your system. +.TP +.IR /proc/sys/kernel/shmall " (since Linux 2.2)" +This file +contains the system-wide limit on the total number of pages of +System V shared memory. +.TP +.IR /proc/sys/kernel/shmmax " (since Linux 2.2)" +This file +can be used to query and set the run-time limit +on the maximum (System V IPC) shared memory segment size that can be +created. +Shared memory segments up to 1GB are now supported in the +kernel. +This value defaults to +.BR SHMMAX . +.TP +.IR /proc/sys/kernel/shmmni " (since Linux 2.4)" +This file +specifies the system-wide maximum number of System V shared memory +segments that can be created. +.TP +.IR /proc/sys/kernel/sysctl_writes_strict " (since Linux 3.16)" +.\" commit f88083005ab319abba5d0b2e4e997558245493c8 +.\" commit 2ca9bb456ada8bcbdc8f77f8fc78207653bbaa92 +.\" commit f4aacea2f5d1a5f7e3154e967d70cf3f711bcd61 +.\" commit 24fe831c17ab8149413874f2fd4e5c8a41fcd294 +The value in this file determines how the file offset affects +the behavior of updating entries in files under +.IR /proc/sys . +The file has three possible values: +.RS +.TP 4 +\-1 +This provides legacy handling, with no printk warnings. +Each +.BR write (2) +must fully contain the value to be written, +and multiple writes on the same file descriptor +will overwrite the entire value, regardless of the file position. +.TP +0 +(default) This provides the same behavior as for \-1, +but printk warnings are written for processes that +perform writes when the file offset is not 0. +.TP +1 +Respect the file offset when writing strings into +.I /proc/sys +files. +Multiple writes will +.I append +to the value buffer. +Anything written beyond the maximum length +of the value buffer will be ignored. +Writes to numeric +.I /proc/sys +entries must always be at file offset 0 and the value must be +fully contained in the buffer provided to +.BR write (2). +.\" FIXME . +.\" With /proc/sys/kernel/sysctl_writes_strict==1, writes at an +.\" offset other than 0 do not generate an error. Instead, the +.\" write() succeeds, but the file is left unmodified. +.\" This is surprising. The behavior may change in the future. +.\" See thread.gmane.org/gmane.linux.man/9197 +.\" From: Michael Kerrisk (man-pages +.\" Subject: sysctl_writes_strict documentation + an oddity? +.\" Newsgroups: gmane.linux.man, gmane.linux.kernel +.\" Date: 2015-05-09 08:54:11 GMT +.RE +.TP +.I /proc/sys/kernel/sysrq +This file controls the functions allowed to be invoked by the SysRq key. +By default, +the file contains 1 meaning that every possible SysRq request is allowed +(in older kernel versions, SysRq was disabled by default, +and you were required to specifically enable it at run-time, +but this is not the case any more). +Possible values in this file are: +.RS +.TP 5 +0 +Disable sysrq completely +.TP +1 +Enable all functions of sysrq +.TP +> 1 +Bit mask of allowed sysrq functions, as follows: +.PD 0 +.RS +.TP 5 +\ \ 2 +Enable control of console logging level +.TP +\ \ 4 +Enable control of keyboard (SAK, unraw) +.TP +\ \ 8 +Enable debugging dumps of processes etc. +.TP +\ 16 +Enable sync command +.TP +\ 32 +Enable remount read-only +.TP +\ 64 +Enable signaling of processes (term, kill, oom-kill) +.TP +128 +Allow reboot/poweroff +.TP +256 +Allow nicing of all real-time tasks +.RE +.PD +.RE +.IP +This file is present only if the +.B CONFIG_MAGIC_SYSRQ +kernel configuration option is enabled. +For further details see the Linux kernel source file +.I Documentation/admin\-guide/sysrq.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/sysrq.txt +before Linux 4.10). +.TP +.I /proc/sys/kernel/version +This file contains a string such as: +.IP + #5 Wed Feb 25 21:49:24 MET 1998 +.IP +The "#5" means that +this is the fifth kernel built from this source base and the +date following it indicates the time the kernel was built. +.TP +.IR /proc/sys/kernel/threads-max " (since Linux 2.3.11)" +.\" The following is based on Documentation/sysctl/kernel.txt +This file specifies the system-wide limit on the number of +threads (tasks) that can be created on the system. +.IP +Since Linux 4.1, +.\" commit 230633d109e35b0a24277498e773edeb79b4a331 +the value that can be written to +.I threads-max +is bounded. +The minimum value that can be written is 20. +The maximum value that can be written is given by the +constant +.B FUTEX_TID_MASK +(0x3fffffff). +If a value outside of this range is written to +.IR threads-max , +the error +.B EINVAL +occurs. +.IP +The value written is checked against the available RAM pages. +If the thread structures would occupy too much (more than 1/8th) +of the available RAM pages, +.I threads-max +is reduced accordingly. +.TP +.IR /proc/sys/kernel/yama/ptrace_scope " (since Linux 3.5)" +See +.BR ptrace (2). +.TP +.IR /proc/sys/kernel/zero-paged " (PowerPC only) " +This file +contains a flag. +When enabled (nonzero), Linux-PPC will pre-zero pages in +the idle loop, possibly speeding up get_free_pages. +.TP +.I /proc/sys/net +This directory contains networking stuff. +Explanations for some of the files under this directory can be found in +.BR tcp (7) +and +.BR ip (7). +.TP +.I /proc/sys/net/core/bpf_jit_enable +See +.BR bpf (2). +.TP +.I /proc/sys/net/core/somaxconn +This file defines a ceiling value for the +.I backlog +argument of +.BR listen (2); +see the +.BR listen (2) +manual page for details. +.TP +.I /proc/sys/proc +This directory may be empty. +.TP +.I /proc/sys/sunrpc +This directory supports Sun remote procedure call for network filesystem +(NFS). +On some systems, it is not present. +.TP +.IR /proc/sys/user " (since Linux 4.9)" +See +.BR namespaces (7). +.TP +.I /proc/sys/vm +This directory contains files for memory management tuning, buffer and +cache management. +.TP +.IR /proc/sys/vm/admin_reserve_kbytes " (since Linux 3.10)" +.\" commit 4eeab4f5580d11bffedc697684b91b0bca0d5009 +This file defines the amount of free memory (in KiB) on the system that +should be reserved for users with the capability +.BR CAP_SYS_ADMIN . +.IP +The default value in this file is the minimum of [3% of free pages, 8MiB] +expressed as KiB. +The default is intended to provide enough for the superuser +to log in and kill a process, if necessary, +under the default overcommit 'guess' mode (i.e., 0 in +.IR /proc/sys/vm/overcommit_memory ). +.IP +Systems running in "overcommit never" mode (i.e., 2 in +.IR /proc/sys/vm/overcommit_memory ) +should increase the value in this file to account +for the full virtual memory size of the programs used to recover (e.g., +.BR login (1) +.BR ssh (1), +and +.BR top (1)) +Otherwise, the superuser may not be able to log in to recover the system. +For example, on x86-64 a suitable value is 131072 (128MiB reserved). +.IP +Changing the value in this file takes effect whenever +an application requests memory. +.TP +.IR /proc/sys/vm/compact_memory " (since Linux 2.6.35)" +When 1 is written to this file, all zones are compacted such that free +memory is available in contiguous blocks where possible. +The effect of this action can be seen by examining +.IR /proc/buddyinfo . +.IP +Present only if the kernel was configured with +.BR CONFIG_COMPACTION . +.TP +.IR /proc/sys/vm/drop_caches " (since Linux 2.6.16)" +Writing to this file causes the kernel to drop clean caches, dentries, and +inodes from memory, causing that memory to become free. +This can be useful for memory management testing and +performing reproducible filesystem benchmarks. +Because writing to this file causes the benefits of caching to be lost, +it can degrade overall system performance. +.IP +To free pagecache, use: +.IP + echo 1 > /proc/sys/vm/drop_caches +.IP +To free dentries and inodes, use: +.IP + echo 2 > /proc/sys/vm/drop_caches +.IP +To free pagecache, dentries and inodes, use: +.IP + echo 3 > /proc/sys/vm/drop_caches +.IP +Because writing to this file is a nondestructive operation and dirty objects +are not freeable, the +user should run +.BR sync (1) +first. +.TP +.IR /proc/sys/vm/legacy_va_layout " (since Linux 2.6.9)" +.\" The following is from Documentation/filesystems/proc.txt +If nonzero, this disables the new 32-bit memory-mapping layout; +the kernel will use the legacy (2.4) layout for all processes. +.TP +.IR /proc/sys/vm/memory_failure_early_kill " (since Linux 2.6.32)" +.\" The following is based on the text in Documentation/sysctl/vm.txt +Control how to kill processes when an uncorrected memory error +(typically a 2-bit error in a memory module) +that cannot be handled by the kernel +is detected in the background by hardware. +In some cases (like the page still having a valid copy on disk), +the kernel will handle the failure +transparently without affecting any applications. +But if there is no other up-to-date copy of the data, +it will kill processes to prevent any data corruptions from propagating. +.IP +The file has one of the following values: +.RS +.IP 1: 4 +Kill all processes that have the corrupted-and-not-reloadable page mapped +as soon as the corruption is detected. +Note that this is not supported for a few types of pages, +such as kernel internally +allocated data or the swap cache, but works for the majority of user pages. +.IP 0: 4 +Unmap the corrupted page from all processes and kill a process +only if it tries to access the page. +.RE +.IP +The kill is performed using a +.B SIGBUS +signal with +.I si_code +set to +.BR BUS_MCEERR_AO . +Processes can handle this if they want to; see +.BR sigaction (2) +for more details. +.IP +This feature is active only on architectures/platforms with advanced machine +check handling and depends on the hardware capabilities. +.IP +Applications can override the +.I memory_failure_early_kill +setting individually with the +.BR prctl (2) +.B PR_MCE_KILL +operation. +.IP +Present only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.IR /proc/sys/vm/memory_failure_recovery " (since Linux 2.6.32)" +.\" The following is based on the text in Documentation/sysctl/vm.txt +Enable memory failure recovery (when supported by the platform) +.RS +.IP 1: 4 +Attempt recovery. +.IP 0: 4 +Always panic on a memory failure. +.RE +.IP +Present only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.IR /proc/sys/vm/oom_dump_tasks " (since Linux 2.6.25)" +.\" The following is from Documentation/sysctl/vm.txt +Enables a system-wide task dump (excluding kernel threads) to be +produced when the kernel performs an OOM-killing. +The dump includes the following information +for each task (thread, process): +thread ID, real user ID, thread group ID (process ID), +virtual memory size, resident set size, +the CPU that the task is scheduled on, +oom_adj score (see the description of +.IR /proc/[pid]/oom_adj ), +and command name. +This is helpful to determine why the OOM-killer was invoked +and to identify the rogue task that caused it. +.IP +If this contains the value zero, this information is suppressed. +On very large systems with thousands of tasks, +it may not be feasible to dump the memory state information for each one. +Such systems should not be forced to incur a performance penalty in +OOM situations when the information may not be desired. +.IP +If this is set to nonzero, this information is shown whenever the +OOM-killer actually kills a memory-hogging task. +.IP +The default value is 0. +.TP +.IR /proc/sys/vm/oom_kill_allocating_task " (since Linux 2.6.24)" +.\" The following is from Documentation/sysctl/vm.txt +This enables or disables killing the OOM-triggering task in +out-of-memory situations. +.IP +If this is set to zero, the OOM-killer will scan through the entire +tasklist and select a task based on heuristics to kill. +This normally selects a rogue memory-hogging task that +frees up a large amount of memory when killed. +.IP +If this is set to nonzero, the OOM-killer simply kills the task that +triggered the out-of-memory condition. +This avoids a possibly expensive tasklist scan. +.IP +If +.I /proc/sys/vm/panic_on_oom +is nonzero, it takes precedence over whatever value is used in +.IR /proc/sys/vm/oom_kill_allocating_task . +.IP +The default value is 0. +.TP +.IR /proc/sys/vm/overcommit_kbytes " (since Linux 3.14)" +.\" commit 49f0ce5f92321cdcf741e35f385669a421013cb7 +This writable file provides an alternative to +.IR /proc/sys/vm/overcommit_ratio +for controlling the +.I CommitLimit +when +.IR /proc/sys/vm/overcommit_memory +has the value 2. +It allows the amount of memory overcommitting to be specified as +an absolute value (in kB), +rather than as a percentage, as is done with +.IR overcommit_ratio . +This allows for finer-grained control of +.IR CommitLimit +on systems with extremely large memory sizes. +.IP +Only one of +.IR overcommit_kbytes +or +.IR overcommit_ratio +can have an effect: +if +.IR overcommit_kbytes +has a nonzero value, then it is used to calculate +.IR CommitLimit , +otherwise +.IR overcommit_ratio +is used. +Writing a value to either of these files causes the +value in the other file to be set to zero. +.TP +.I /proc/sys/vm/overcommit_memory +This file contains the kernel virtual memory accounting mode. +Values are: +.RS +.IP +0: heuristic overcommit (this is the default) +.br +1: always overcommit, never check +.br +2: always check, never overcommit +.RE +.IP +In mode 0, calls of +.BR mmap (2) +with +.B MAP_NORESERVE +are not checked, and the default check is very weak, +leading to the risk of getting a process "OOM-killed". +.IP +In mode 1, the kernel pretends there is always enough memory, +until memory actually runs out. +One use case for this mode is scientific computing applications +that employ large sparse arrays. +In Linux kernel versions before 2.6.0, any nonzero value implies mode 1. +.IP +In mode 2 (available since Linux 2.6), the total virtual address space +that can be allocated +.RI ( CommitLimit +in +.IR /proc/meminfo ) +is calculated as +.IP + CommitLimit = (total_RAM - total_huge_TLB) * + overcommit_ratio / 100 + total_swap +.IP +where: +.RS 12 +.IP * 3 +.I total_RAM +is the total amount of RAM on the system; +.IP * +.I total_huge_TLB +is the amount of memory set aside for huge pages; +.IP * +.I overcommit_ratio +is the value in +.IR /proc/sys/vm/overcommit_ratio ; +and +.IP * +.I total_swap +is the amount of swap space. +.RE +.IP +For example, on a system with 16GB of physical RAM, 16GB +of swap, no space dedicated to huge pages, and an +.I overcommit_ratio +of 50, this formula yields a +.I CommitLimit +of 24GB. +.IP +Since Linux 3.14, if the value in +.I /proc/sys/vm/overcommit_kbytes +is nonzero, then +.I CommitLimit +is instead calculated as: +.IP + CommitLimit = overcommit_kbytes + total_swap +.IP +See also the description of +.IR /proc/sys/vm/admiin_reserve_kbytes +and +.IR /proc/sys/vm/user_reserve_kbytes . +.TP +.IR /proc/sys/vm/overcommit_ratio " (since Linux 2.6.0)" +This writable file defines a percentage by which memory +can be overcommitted. +The default value in the file is 50. +See the description of +.IR /proc/sys/vm/overcommit_memory . +.TP +.IR /proc/sys/vm/panic_on_oom " (since Linux 2.6.18)" +.\" The following is adapted from Documentation/sysctl/vm.txt +This enables or disables a kernel panic in +an out-of-memory situation. +.IP +If this file is set to the value 0, +the kernel's OOM-killer will kill some rogue process. +Usually, the OOM-killer is able to kill a rogue process and the +system will survive. +.IP +If this file is set to the value 1, +then the kernel normally panics when out-of-memory happens. +However, if a process limits allocations to certain nodes +using memory policies +.RB ( mbind (2) +.BR MPOL_BIND ) +or cpusets +.RB ( cpuset (7)) +and those nodes reach memory exhaustion status, +one process may be killed by the OOM-killer. +No panic occurs in this case: +because other nodes' memory may be free, +this means the system as a whole may not have reached +an out-of-memory situation yet. +.IP +If this file is set to the value 2, +the kernel always panics when an out-of-memory condition occurs. +.IP +The default value is 0. +1 and 2 are for failover of clustering. +Select either according to your policy of failover. +.TP +.IR /proc/sys/vm/swappiness +.\" The following is from Documentation/sysctl/vm.txt +The value in this file controls how aggressively the kernel will swap +memory pages. +Higher values increase aggressiveness, lower values +decrease aggressiveness. +The default value is 60. +.TP +.IR /proc/sys/vm/user_reserve_kbytes " (since Linux 3.10)" +.\" commit c9b1d0981fcce3d9976d7b7a56e4e0503bc610dd +Specifies an amount of memory (in KiB) to reserve for user processes, +This is intended to prevent a user from starting a single memory hogging +process, such that they cannot recover (kill the hog). +The value in this file has an effect only when +.IR /proc/sys/vm/overcommit_memory +is set to 2 ("overcommit never" mode). +In this case, the system reserves an amount of memory that is the minimum +of [3% of current process size, +.IR user_reserve_kbytes ]. +.IP +The default value in this file is the minimum of [3% of free pages, 128MiB] +expressed as KiB. +.IP +If the value in this file is set to zero, +then a user will be allowed to allocate all free memory with a single process +(minus the amount reserved by +.IR /proc/sys/vm/admin_reserve_kbytes ). +Any subsequent attempts to execute a command will result in +"fork: Cannot allocate memory". +.IP +Changing the value in this file takes effect whenever +an application requests memory. +.TP +.IR /proc/sysrq-trigger " (since Linux 2.4.21)" +Writing a character to this file triggers the same SysRq function as +typing ALT-SysRq- (see the description of +.IR /proc/sys/kernel/sysrq ). +This file is normally writable only by +.IR root . +For further details see the Linux kernel source file +.I Documentation/admin\-guide/sysrq.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/sysrq.txt +before Linux 4.10). +.TP +.I /proc/sysvipc +Subdirectory containing the pseudo-files +.IR msg ", " sem " and " shm "." +These files list the System V Interprocess Communication (IPC) objects +(respectively: message queues, semaphores, and shared memory) +that currently exist on the system, +providing similar information to that available via +.BR ipcs (1). +These files have headers and are formatted (one IPC object per line) +for easy understanding. +.BR svipc (7) +provides further background on the information shown by these files. +.TP +.IR /proc/thread-self " (since Linux 3.17)" +.\" commit 0097875bd41528922fb3bb5f348c53f17e00e2fd +This directory refers to the thread accessing the +.I /proc +filesystem, +and is identical to the +.I /proc/self/task/[tid] +directory named by the process thread ID +.RI ( [tid] ) +of the same thread. +.TP +.IR /proc/timer_list " (since Linux 2.6.21)" +.\" commit 289f480af87e45f7a6de6ba9b4c061c2e259fe98 +This read-only file exposes a list of all currently pending +(high-resolution) timers, +all clock-event sources, and their parameters in a human-readable form. +.TP +.IR /proc/timer_stats " (from Linux 2.6.21 until Linux 4.10)" +.\" commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221 +.\" Date: Fri Feb 16 01:28:13 2007 -0800 +.\" Text largely derived from Documentation/timers/timer_stats.txt +.\" removed in commit dfb4357da6ddbdf57d583ba64361c9d792b0e0b1 +.\" Date: Wed Feb 8 11:26:59 2017 -0800 +This is a debugging facility to make timer (ab)use in a Linux +system visible to kernel and user-space developers. +It can be used by kernel and user-space developers to verify that +their code does not make undue use of timers. +The goal is to avoid unnecessary wakeups, +thereby optimizing power consumption. +.IP +If enabled in the kernel +.RB ( CONFIG_TIMER_STATS ), +but not used, +it has almost zero runtime overhead and a relatively small +data-structure overhead. +Even if collection is enabled at runtime, overhead is low: +all the locking is per-CPU and lookup is hashed. +.IP +The +.I /proc/timer_stats +file is used both to control sampling facility and to read out the +sampled information. +.IP +The +.I timer_stats +functionality is inactive on bootup. +A sampling period can be started using the following command: +.IP +.in +4n +.EX +# echo 1 > /proc/timer_stats +.EE +.in +.IP +The following command stops a sampling period: +.IP +.in +4n +.EX +# echo 0 > /proc/timer_stats +.EE +.in +.IP +The statistics can be retrieved by: +.IP +.in +4n +.EX +$ cat /proc/timer_stats +.EE +.in +.IP +While sampling is enabled, each readout from +.I /proc/timer_stats +will see +newly updated statistics. +Once sampling is disabled, the sampled information +is kept until a new sample period is started. +This allows multiple readouts. +.IP +Sample output from +.IR /proc/timer_stats : +.IP +.in 4n +.EX +.RB $ " cat /proc/timer_stats" +Timer Stats Version: v0.3 +Sample period: 1.764 s +Collection: active + 255, 0 swapper/3 hrtimer_start_range_ns (tick_sched_timer) + 71, 0 swapper/1 hrtimer_start_range_ns (tick_sched_timer) + 58, 0 swapper/0 hrtimer_start_range_ns (tick_sched_timer) + 4, 1694 gnome-shell mod_delayed_work_on (delayed_work_timer_fn) + 17, 7 rcu_sched rcu_gp_kthread (process_timeout) +\&... + 1, 4911 kworker/u16:0 mod_delayed_work_on (delayed_work_timer_fn) + 1D, 2522 kworker/0:0 queue_delayed_work_on (delayed_work_timer_fn) +1029 total events, 583.333 events/sec +.EE +.in +.IP +The output columns are: +.RS +.IP * 3 +a count of the number of events, +optionally (since Linux 2.6.23) followed by the letter \(aqD\(aq +.\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers +if this is a deferrable timer; +.IP * +the PID of the process that initialized the timer; +.IP * +the name of the process that initialized the timer; +.IP * +the function where the timer was initialized; and +.IP * +(in parentheses) +the callback function that is associated with the timer. +.RE +.IP +During the Linux 4.11 development cycle, +this file was removed because of security concerns, +as it exposes information across namespaces. +Furthermore, it is possible to obtain +the same information via in-kernel tracing facilities such as ftrace. +.TP +.I /proc/tty +Subdirectory containing the pseudo-files and subdirectories for +tty drivers and line disciplines. +.TP +.I /proc/uptime +This file contains two numbers: the uptime of the system (seconds), +and the amount of time spent in idle process (seconds). +.TP +.I /proc/version +This string identifies the kernel version that is currently running. +It includes the contents of +.IR /proc/sys/kernel/ostype , +.I /proc/sys/kernel/osrelease +and +.IR /proc/sys/kernel/version . +For example: +.IP +.in 8n +.EX +Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 +.EE +.in +.\" FIXME 2.6.13 seems to have /proc/vmcore implemented; document this +.\" See Documentation/kdump/kdump.txt +.\" commit 666bfddbe8b8fd4fd44617d6c55193d5ac7edb29 +.\" Needs CONFIG_VMCORE +.\" +.TP +.IR /proc/vmstat " (since Linux 2.6.0)" +This file displays various virtual memory statistics. +Each line of this file contains a single name-value pair, +delimited by white space. +Some lines are present only if the kernel was configured with +suitable options. +(In some cases, the options required for particular files have changed +across kernel versions, so they are not listed here. +Details can be found by consulting the kernel source code.) +The following fields may be present: +.\" FIXME We need explanations for each of the following fields... +.RS +.TP +.IR nr_free_pages " (since Linux 2.6.31)" +.\" commit d23ad42324cc4378132e51f2fc5c9ba6cbe75182 +.TP +.IR nr_alloc_batch " (since Linux 3.12)" +.\" commit 81c0a2bb515fd4daae8cab64352877480792b515 +.TP +.IR nr_inactive_anon " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_active_anon " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_inactive_file " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_active_file " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_unevictable " (since Linux 2.6.28)" +.\" commit 7b854121eb3e5ba0241882ff939e2c485228c9c5 +.TP +.IR nr_mlock " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.TP +.IR nr_anon_pages " (since Linux 2.6.18)" +.\" commit f3dbd34460ff54962d3e3244b6bcb7f5295356e6 +.TP +.IR nr_mapped " (since Linux 2.6.0)" +.TP +.IR nr_file_pages " (since Linux 2.6.18)" +.\" commit 347ce434d57da80fd5809c0c836f206a50999c26 +.TP +.IR nr_dirty " (since Linux 2.6.0)" +.TP +.IR nr_writeback " (since Linux 2.6.0)" +.TP +.IR nr_slab_reclaimable " (since Linux 2.6.19)" +.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 +.\" Linux 2.6.0 had nr_slab +.TP +.IR nr_slab_unreclaimable " (since Linux 2.6.19)" +.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 +.TP +.IR nr_page_table_pages " (since Linux 2.6.0)" +.TP +.IR nr_kernel_stack " (since Linux 2.6.32)" +.\" commit c6a7f5728a1db45d30df55a01adc130b4ab0327c +Amount of memory allocated to kernel stacks. +.TP +.IR nr_unstable " (since Linux 2.6.0)" +.TP +.IR nr_bounce " (since Linux 2.6.12)" +.\" commit edfbe2b0038723e5699ab22695ccd62b5542a5c1 +.TP +.IR nr_vmscan_write " (since Linux 2.6.19)" +.\" commit e129b5c23c2b471d47f1c5d2b8b193fc2034af43 +.TP +.IR nr_vmscan_immediate_reclaim " (since Linux 3.2)" +.\" commit 49ea7eb65e7c5060807fb9312b1ad4c3eab82e2c +.TP +.IR nr_writeback_temp " (since Linux 2.6.26)" +.\" commit fc3ba692a4d19019387c5acaea63131f9eab05dd +.TP +.IR nr_isolated_anon " (since Linux 2.6.32)" +.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 +.TP +.IR nr_isolated_file " (since Linux 2.6.32)" +.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 +.TP +.IR nr_shmem " (since Linux 2.6.32)" +.\" commit 4b02108ac1b3354a22b0d83c684797692efdc395 +Pages used by shmem and +.BR tmpfs (5). +.TP +.IR nr_dirtied " (since Linux 2.6.37)" +.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c +.TP +.IR nr_written " (since Linux 2.6.37)" +.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c +.TP +.IR nr_pages_scanned " (since Linux 3.17)" +.\" commit 0d5d823ab4e608ec7b52ac4410de4cb74bbe0edd +.TP +.IR numa_hit " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_miss " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_foreign " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_interleave " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_local " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_other " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR workingset_refault " (since Linux 3.15)" +.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR workingset_activate " (since Linux 3.15)" +.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR workingset_nodereclaim " (since Linux 3.15)" +.\" commit 449dd6984d0e47643c04c807f609dd56d48d5bcc +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_anon_transparent_hugepages " (since Linux 2.6.38)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_free_cma " (since Linux 3.7)" +.\" commit d1ce749a0db12202b711d1aba1d29e823034648d +Number of free CMA (Contiguous Memory Allocator) pages. +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_dirty_threshold " (since Linux 2.6.37)" +.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_dirty_background_threshold " (since Linux 2.6.37)" +.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgpgin " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgpgout " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pswpin " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pswpout " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_dma " (since Linux 2.6.5)" +.\" Linux 2.6.0 had pgalloc +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_high " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgalloc_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgfree " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgactivate " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgdeactivate " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgfault " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgmajfault " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_dma " (since Linux 2.6.5)" +.\" Linux 2.6.0 had pgrefill +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_high " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgrefill_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.\" Formerly there were +.\" pgsteal_high +.\" pgsteal_normal +.\" pgsteal_dma32 +.\" pgsteal_dma +.\" These were split out into pgsteal_kswapd* and pgsteal_direct* +.\" in commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.TP +.IR pgsteal_kswapd_dma " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Linux 2.6.0 had pgsteal +.\" Present only if the kernel was configured with +.\" .\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_dma32 " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_normal " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_high " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgsteal_kswapd_movable " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_dma +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_dma32 " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_normal " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_high " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgsteal_direct_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_dma +.\" Linux 2.6.0 had pgscan +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_high +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgscan_kswapd_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_dma +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_normal +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_high +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgscan_direct_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_throttle " (since Linux 3.6)" +.\" commit 68243e76ee343d63c6cf76978588a885951e2818 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR zone_reclaim_failed " (since linux 2.6.31)" +.\" commit 24cf72518c79cdcda486ed26074ff8151291cf65 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA . +.TP +.IR pginodesteal " (since linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR slabs_scanned " (since linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_inodesteal " (since linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_low_wmark_hit_quickly " (since 2.6.33)" +.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_high_wmark_hit_quickly " (since 2.6.33)" +.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pageoutrun " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR allocstall " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrotated " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR drop_pagecache " (since Linux 3.15)" +.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR drop_slab " (since Linux 3.15)" +.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR numa_pte_updates " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_huge_pte_updates " (since Linux 3.13)" +.\" commit 72403b4a0fbdf433c1fe0127e49864658f6f6468 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_hint_faults " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_hint_faults_local " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_pages_migrated " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR pgmigrate_success " (since Linux 3.8)" +.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MIGRATION . +.TP +.IR pgmigrate_fail " (since Linux 3.8)" +.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MIGRATION . +.TP +.IR compact_migrate_scanned " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Linux 3.8 dropped compact_blocks_moved, compact_pages_moved, and +.\" compact_pagemigrate_failed +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_free_scanned " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_isolated " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_stall " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_fail " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_success " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR htlb_buddy_alloc_success " (since Linux 2.6.26)" +.\" commit 3b1163006332302117b1b2acf226d4014ff46525 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HUGETLB_PAGE . +.TP +.IR htlb_buddy_alloc_fail " (since Linux 2.6.26)" +.\" commit 3b1163006332302117b1b2acf226d4014ff46525 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HUGETLB_PAGE . +.TP +.IR unevictable_pgs_culled " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_scanned " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_rescued " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_mlocked " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_munlocked " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_cleared " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_stranded " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.\" Linux 3.7 removed unevictable_pgs_mlockfreed +.TP +.IR thp_fault_alloc " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_fault_fallback " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_collapse_alloc " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_collapse_alloc_failed " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_split " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_zero_page_alloc " (since Linux 3.8)" +.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_zero_page_alloc_failed " (since Linux 3.8)" +.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 +See the kernel source file +.IR Documentation/vm/transhuge.txt . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR balloon_inflate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MEMORY_BALLOON . +.TP +.IR balloon_deflate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MEMORY_BALLOON . +.TP +.IR balloon_migrate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS , +.\" .BR CONFIG_MEMORY_BALLOON , +.\" and +.\" .BR CONFIG_BALLOON_COMPACTION . +.TP +.IR nr_tlb_remote_flush " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH +.\" and +.\" .BR CONFIG_SMP . +.TP +.IR nr_tlb_remote_flush_received " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH +.\" and +.\" .BR CONFIG_SMP . +.TP +.IR nr_tlb_local_flush_all " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH . +.TP +.IR nr_tlb_local_flush_one " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH . +.TP +.IR vmacache_find_calls " (since Linux 3.16)" +.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.TP +.IR vmacache_find_hits " (since Linux 3.16)" +.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.TP +.IR vmacache_full_flushes " (since Linux 3.19)" +.\" commit f5f302e21257ebb0c074bbafc37606c26d28cc3d +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.RE +.TP +.IR /proc/zoneinfo " (since Linux 2.6.13)" +This file display information about memory zones. +This is useful for analyzing virtual memory behavior. +.\" FIXME more should be said about /proc/zoneinfo +.SH NOTES +Many strings (i.e., the environment and command line) are in +the internal format, with subfields terminated by null bytes (\(aq\\0\(aq), +so you +may find that things are more readable if you use \fIod \-c\fP or \fItr +"\\000" "\\n"\fP to read them. +Alternatively, \fIecho \`cat \`\fP works well. +.PP +This manual page is incomplete, possibly inaccurate, and is the kind +of thing that needs to be updated very often. +.\" .SH ACKNOWLEDGEMENTS +.\" The material on /proc/sys/fs and /proc/sys/kernel is closely based on +.\" kernel source documentation files written by Rik van Riel. +.SH SEE ALSO +.BR cat (1), +.BR dmesg (1), +.BR find (1), +.BR free (1), +.BR init (1), +.BR ps (1), +.BR tr (1), +.BR uptime (1), +.BR chroot (2), +.BR mmap (2), +.BR readlink (2), +.BR syslog (2), +.BR slabinfo (5), +.BR sysfs (5), +.BR hier (7), +.BR namespaces (7), +.BR time (7), +.BR arp (8), +.BR hdparm (8), +.BR ifconfig (8), +.BR lsmod (8), +.BR lspci (8), +.BR mount (8), +.BR netstat (8), +.BR procinfo (8), +.BR route (8), +.BR sysctl (8) +.PP +The Linux kernel source files: +.IR Documentation/filesystems/proc.txt +.IR Documentation/sysctl/fs.txt , +.IR Documentation/sysctl/kernel.txt , +.IR Documentation/sysctl/net.txt , +and +.IR Documentation/sysctl/vm.txt . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/procfs.5 b/man5/procfs.5 new file mode 100644 index 0000000..d8be74a --- /dev/null +++ b/man5/procfs.5 @@ -0,0 +1 @@ +.so man5/proc.5 diff --git a/man5/protocols.5 b/man5/protocols.5 new file mode 100644 index 0000000..8a11aeb --- /dev/null +++ b/man5/protocols.5 @@ -0,0 +1,94 @@ +.\" Copyright (c) 1995 Martin Schulze +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1995-10-18 Martin Schulze +.\" * first released +.\" 2002-09-22 Seth W. Klein +.\" * protocol numbers are now assigned by the IANA +.\" +.TH PROTOCOLS 5 2012-08-05 "Linux" "Linux Programmer's Manual" +.SH NAME +protocols \- protocols definition file +.SH DESCRIPTION +This file is a plain ASCII file, describing the various DARPA internet +protocols that are available from the TCP/IP subsystem. +It should be +consulted instead of using the numbers in the ARPA include files, or, +even worse, just guessing them. +These numbers will occur in the +protocol field of any IP header. +.PP +Keep this file untouched since changes would result in incorrect IP +packages. +Protocol numbers and names are specified by the IANA +(Internet Assigned Numbers Authority). +.\" .. by the DDN Network Information Center. +.PP +Each line is of the following format: +.PP +.RS +.I protocol number aliases ... +.RE +.PP +where the fields are delimited by spaces or tabs. +Empty lines are ignored. +If a line contains a hash mark (#), the hash mark and the part +of the line following it are ignored. +.PP +The field descriptions are: +.TP +.I protocol +the native name for the protocol. +For example +.IR ip , +.IR tcp , +or +.IR udp . +.TP +.I number +the official number for this protocol as it will appear within the IP +header. +.TP +.I aliases +optional aliases for the protocol. +.PP +This file might be distributed over a network using a network-wide +naming service like Yellow Pages/NIS or BIND/Hesiod. +.SH FILES +.TP +.I /etc/protocols +The protocols definition file. +.SH SEE ALSO +.BR getprotoent (3) +.PP +.UR http://www.iana.org\:/assignments\:/protocol\-numbers +.UE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/repertoiremap.5 b/man5/repertoiremap.5 new file mode 100644 index 0000000..73bc0aa --- /dev/null +++ b/man5/repertoiremap.5 @@ -0,0 +1,87 @@ +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH REPERTOIREMAP 5 2016-07-17 "GNU" "Linux User Manual" +.SH NAME +repertoiremap \- map symbolic character names to Unicode code points +.SH DESCRIPTION +A repertoire map defines mappings between symbolic character names +(mnemonics) and Unicode code points when compiling a locale with +.BR localedef (1). +Using a repertoire map is optional, it is needed only when symbolic +names are used instead of now preferred Unicode code points. +.SS Syntax +The repertoiremap file starts with a header that may consist of the +following keywords: +.TP +.I comment_char +is followed by a character that will be used as the +comment character for the rest of the file. +It defaults to the number sign (#). +.TP +.I escape_char +is followed by a character that should be used as the escape character +for the rest of the file to mark characters that should be interpreted +in a special way. +It defaults to the backslash (\\). +.PP +The mapping section starts with the keyword +.I CHARIDS +in the first column. +.PP +The mapping lines have the following form: +.TP +.I comment +This defines exactly one mapping, +.I comment +being optional. +.PP +The mapping section ends with the string +.IR "END CHARIDS" . +.SH FILES +.TP +.I /usr/share/i18n/repertoiremaps +Usual default repertoire map path. +.SH CONFORMING TO +POSIX.2. +.SH NOTES +Repertoire maps are deprecated in favor of Unicode code points. +.SH EXAMPLE +A mnemonic for the Euro sign can be defined as follows: +.PP +.nf + EURO SIGN +.fi +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR charmap (5), +.BR locale (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/resolv.conf.5 b/man5/resolv.conf.5 new file mode 100644 index 0000000..bc42004 --- /dev/null +++ b/man5/resolv.conf.5 @@ -0,0 +1,349 @@ +.\" Copyright (c) 1986 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Redistribution and use in source and binary forms are permitted +.\" provided that the above copyright notice and this paragraph are +.\" duplicated in all such forms and that any documentation, +.\" advertising materials, and other materials related to such +.\" distribution and use acknowledge that the software was developed +.\" by the University of California, Berkeley. The name of the +.\" University may not be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %%%LICENSE_END +.\" +.\" @(#)resolver.5 5.9 (Berkeley) 12/14/89 +.\" $Id: resolver.5,v 8.6 1999/05/21 00:01:02 vixie Exp $ +.\" +.\" Added ndots remark by Bernhard R. Link - debian bug #182886 +.\" +.TH RESOLV.CONF 5 2017-09-15 "" "Linux Programmer's Manual" +.UC 4 +.SH NAME +resolv.conf \- resolver configuration file +.SH SYNOPSIS +.B /etc/resolv.conf +.SH DESCRIPTION +The +.I resolver +is a set of routines in the C library +that provide access to the Internet Domain Name System (DNS). +The resolver configuration file contains information that is read +by the resolver routines the first time they are invoked by a process. +The file is designed to be human readable and contains a list of +keywords with values that provide various types of resolver information. +The configuration file is considered a trusted source of DNS information +(e.g., DNSSEC AD-bit information will be returned unmodified from this +source). +.PP +If this file does not exist, +only the name server on the local machine will be queried; +the domain name is determined from the hostname +and the domain search path is constructed from the domain name. +.PP +The different configuration options are: +.TP +\fBnameserver\fP Name server IP address +Internet address of a name server that the resolver should query, +either an IPv4 address (in dot notation), +or an IPv6 address in colon (and possibly dot) notation as per RFC 2373. +Up to +.B MAXNS +(currently 3, see \fI\fP) name servers may be listed, +one per keyword. +If there are multiple servers, +the resolver library queries them in the order listed. +If no \fBnameserver\fP entries are present, +the default is to use the name server on the local machine. +(The algorithm used is to try a name server, and if the query times out, +try the next, until out of name servers, +then repeat trying all the name servers +until a maximum number of retries are made.) +.TP +\fBdomain\fP Local domain name. +Most queries for names within this domain can use short names +relative to the local domain. +If set to \(aq.\(aq, the root domain is considered. +If no \fBdomain\fP entry is present, the domain is determined +from the local hostname returned by +.BR gethostname (2); +the domain part is taken to be everything after the first \(aq.\(aq. +Finally, if the hostname does not contain a domain part, the root +domain is assumed. +.TP +\fBsearch\fP Search list for host-name lookup. +The search list is normally determined from the local domain name; +by default, it contains only the local domain name. +This may be changed by listing the desired domain search path +following the \fIsearch\fP keyword with spaces or tabs separating +the names. +Resolver queries having fewer than +.I ndots +dots (default is 1) in them will be attempted using each component +of the search path in turn until a match is found. +For environments with multiple subdomains please read +.BI "options ndots:" n +below to avoid man-in-the-middle attacks and unnecessary +traffic for the root-dns-servers. +.\" When having a resolv.conv with a line +.\" search subdomain.domain.tld domain.tld +.\" and doing a hostlookup, for example by +.\" ping host.anothersubdomain +.\" it sends dns-requests for +.\" host.anothersubdomain. +.\" host.anothersubdomain.subdomain.domain.tld. +.\" host.anothersubdomain.domain.tld. +.\" thus not only causing unnecessary traffic for the root-dns-servers +.\" but broadcasting information to the outside and making man-in-the-middle +.\" attacks possible. +Note that this process may be slow and will generate a lot of network +traffic if the servers for the listed domains are not local, +and that queries will time out if no server is available +for one of the domains. +.IP +The search list is currently limited to six domains +with a total of 256 characters. +.TP +\fBsortlist\fP +This option allows addresses returned by +.BR gethostbyname (3) +to be sorted. +A sortlist is specified by IP-address-netmask pairs. +The netmask is +optional and defaults to the natural netmask of the net. +The IP address +and optional network pairs are separated by slashes. +Up to 10 pairs may +be specified. +Here is an example: +.IP +.in +4n +sortlist 130.155.160.0/255.255.240.0 130.155.0.0 +.in +.TP +\fBoptions\fP +Options allows certain internal resolver variables to be modified. +The syntax is +.RS +.IP +\fBoptions\fP \fIoption\fP \fI...\fP +.PP +where \fIoption\fP is one of the following: +.TP +\fBdebug\fP +.\" Since glibc 2.2? +Sets +.BR RES_DEBUG +in +.IR _res.options +(effective only if glibc was built with debug support; see +.BR resolver (3)). +.TP +.BI ndots: n +.\" Since glibc 2.2 +Sets a threshold for the number of dots which +must appear in a name given to +.BR res_query (3) +(see +.BR resolver (3)) +before an \fIinitial absolute query\fP will be made. +The default for +\fIn\fP is 1, meaning that if there are any dots in a name, the name +will be tried first as an absolute name before any \fIsearch list\fP +elements are appended to it. +The value for this option is silently capped to 15. +.TP +.BI timeout: n +.\" Since glibc 2.2 +Sets the amount of time the resolver will wait for a +response from a remote name server before retrying the +query via a different name server. This may +.BR not +be the total time taken by any resolver API call and there is no +guarantee that a single resolver API call maps to a single timeout. +Measured in seconds, +the default is +.BR RES_TIMEOUT +(currently 5, see \fI\fP). +The value for this option is silently capped to 30. +.TP +.BI attempts: n +Sets the number of times the resolver will send a +query to its name servers before giving up and returning +an error to the calling application. +The default is +.BR RES_DFLRETRY +(currently 2, see \fI\fP). +The value for this option is silently capped to 5. +.TP +.B rotate +.\" Since glibc 2.2 +Sets +.BR RES_ROTATE +in +.IR _res.options , +which causes round-robin selection of name servers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every time. +.TP +.B no\-check\-names +.\" since glibc 2.2 +Sets +.BR RES_NOCHECKNAME +in +.IR _res.options , +which disables the modern BIND checking of incoming hostnames and +mail names for invalid characters such as underscore (_), non-ASCII, +or control characters. +.TP +.B inet6 +.\" Since glibc 2.2 +Sets +.BR RES_USE_INET6 +in +.IR _res.options . +This has the effect of trying an AAAA query before an A query inside the +.BR gethostbyname (3) +function, and of mapping IPv4 responses in IPv6 "tunneled form" +if no AAAA records are found but an A record set exists. +Since glibc 2.25, +.\" b76e065991ec01299225d9da90a627ebe6c1ac97 +this option is deprecated; applications should use +.BR getaddrinfo (3), +rather than +.BR gethostbyname (3). +.TP +.BR ip6\-bytestring " (since glibc 2.3.4)" +Sets +.BR RES_USEBSTRING +in +.IR _res.options . +This causes reverse IPv6 lookups to be made using the bit-label format +described in RFC\ 2673; +if this option is not set (which is the default), then nibble format is used. +This option was removed in glibc 2.25, +since it relied on a backward-incompatible +DNS extension that was never deployed on the Internet. +.TP +.BR ip6\-dotint / no\-ip6\-dotint " (glibc 2.3.4 to 2.24)" +Clear/set +.BR RES_NOIP6DOTINT +in +.IR _res.options . +When this option is clear +.RB ( ip6\-dotint ), +reverse IPv6 lookups are made in the (deprecated) +.I ip6.int +zone; +when this option is set +.RB ( no\-ip6\-dotint ), +reverse IPv6 lookups are made in the +.I ip6.arpa +zone by default. +These options are available in glibc versions up to 2.24, where +.BR no-ip6-dotint +is the default. +Since +.BR ip6\-dotint +support long ago ceased to be available on the Internet, +these options were removed in glibc 2.25. +.TP +.BR edns0 " (since glibc 2.6)" +Sets +.BR RES_USE_EDNSO +in +.IR _res.options . +This enables support for the DNS extensions described in RFC\ 2671. +.TP +.BR single\-request " (since glibc 2.10)" +Sets +.BR RES_SNGLKUP +in +.IR _res.options . +By default, glibc performs IPv4 and IPv6 lookups in parallel since +version 2.9. +Some appliance DNS servers +cannot handle these queries properly and make the requests time out. +This option disables the behavior and makes glibc perform the IPv6 +and IPv4 requests sequentially (at the cost of some slowdown of the +resolving process). +.TP +.BR single\-request\-reopen " (since glibc 2.9)" +Sets +.BR RES_SNGLKUPREOP +in +.IR _res.options . +The resolver uses the same socket for the A and AAAA requests. +Some hardware mistakenly sends back only one reply. +When that happens the client system will sit and wait for the second reply. +Turning this option on changes this behavior +so that if two requests from the same port are not handled correctly it will +close the socket and open a new one before sending the second request. +.TP +.BR no\-tld\-query " (since glibc 2.14)" +Sets +.BR RES_NOTLDQUERY +in +.IR _res.options . +This option causes +.BR res_nsearch () +to not attempt to resolve an unqualified name +as if it were a top level domain (TLD). +This option can cause problems if the site has ``localhost'' as a TLD +rather than having localhost on one or more elements of the search list. +This option has no effect if neither RES_DEFNAMES or RES_DNSRCH is set. +.TP +.BR use\-vc " (since glibc 2.14)" +Sets +.BR RES_USEVC +in +.IR _res.options . +This option forces the use of TCP for DNS resolutions. +.RE +.PP +The \fIdomain\fP and \fIsearch\fP keywords are mutually exclusive. +If more than one instance of these keywords is present, +the last instance wins. +.PP +The \fIsearch\fP keyword of a system's \fIresolv.conf\fP file can be +overridden on a per-process basis by setting the environment variable +.B LOCALDOMAIN +to a space-separated list of search domains. +.PP +The \fIoptions\fP keyword of a system's \fIresolv.conf\fP file can be +amended on a per-process basis by setting the environment variable +.B RES_OPTIONS +to a space-separated list of resolver options +as explained above under \fBoptions\fP. +.PP +The keyword and value must appear on a single line, and the keyword +(e.g., \fBnameserver\fP) must start the line. +The value follows the keyword, separated by white space. +.PP +Lines that contain a semicolon (;) or hash character (#) +in the first column are treated as comments. +.SH FILES +.IR /etc/resolv.conf , +.I +.SH SEE ALSO +.BR gethostbyname (3), +.BR resolver (3), +.BR host.conf (5), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR hostname (7), +.BR named (8) +.PP +Name Server Operations Guide for BIND +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/resolver.5 b/man5/resolver.5 new file mode 100644 index 0000000..86104b9 --- /dev/null +++ b/man5/resolver.5 @@ -0,0 +1 @@ +.so man5/resolv.conf.5 diff --git a/man5/rpc.5 b/man5/rpc.5 new file mode 100644 index 0000000..a649dd5 --- /dev/null +++ b/man5/rpc.5 @@ -0,0 +1,90 @@ +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)rpc.5 2.2 88/08/03 4.0 RPCSRC; from 1.4 87/11/27 SMI; +.TH RPC 5 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +rpc \- RPC program number data base +.SH SYNOPSIS +.B /etc/rpc +.SH DESCRIPTION +The +.I rpc +file contains user readable names that +can be used in place of RPC program numbers. +Each line has the following information: +.PP +.PD 0 +.IP \(bu 3 +name of server for the RPC program +.IP \(bu +RPC program number +.IP \(bu +aliases +.PD +.PP +Items are separated by any number of blanks and/or +tab characters. +A \(aq#\(aq indicates the beginning of a comment; characters from +the \(aq#\(aq to the end of the line are not interpreted by routines +which search the file. +.PP +Here is an example of the +.I /etc/rpc +file from the Sun RPC Source distribution. +.PP +.in +4n +.EX +# +# rpc 88/08/01 4.0 RPCSRC; from 1.12 88/02/07 SMI +# +portmapper 100000 portmap sunrpc +rstatd 100001 rstat rstat_svc rup perfmeter +rusersd 100002 rusers +nfs 100003 nfsprog +ypserv 100004 ypprog +mountd 100005 mount showmount +ypbind 100007 +walld 100008 rwall shutdown +yppasswdd 100009 yppasswd +etherstatd 100010 etherstat +rquotad 100011 rquotaprog quota rquota +sprayd 100012 spray +3270_mapper 100013 +rje_mapper 100014 +selection_svc 100015 selnsvc +database_svc 100016 +rexd 100017 rex +alis 100018 +sched 100019 +llockmgr 100020 +nlockmgr 100021 +x25.inr 100022 +statmon 100023 +status 100024 +bootparam 100026 +ypupdated 100028 ypupdate +keyserv 100029 keyserver +tfsd 100037 +nsed 100038 +nsemntd 100039 +.EE +.in +.SH FILES +.TP +.I /etc/rpc +RPC program number data base +.SH SEE ALSO +.BR getrpcent (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/securetty.5 b/man5/securetty.5 new file mode 100644 index 0000000..c53dd16 --- /dev/null +++ b/man5/securetty.5 @@ -0,0 +1,63 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sun Jul 25 11:06:27 1993 by Rik Faith (faith@cs.unc.edu) +.TH SECURETTY 5 2015-03-29 "Linux" "Linux Programmer's Manual" +.SH NAME +securetty \- file which lists terminals from which root can log in +.SH DESCRIPTION +The file +.I /etc/securetty +contains the names of terminals +(one per line, without leading +.IR /dev/ ) +which are considered secure for the transmission of certain authentication +tokens. +.PP +It is used by (some versions of) +.BR login (1) +to restrict the terminals +on which root is allowed to login. +See +.BR login.defs (5) +if you use the shadow suite. +.PP +On PAM enabled systems, it is used for the same purpose by +.BR pam_securetty (8) +to restrict the terminals on which empty passwords are accepted. +.SH FILES +.I /etc/securetty +.SH SEE ALSO +.BR login (1), +.BR login.defs (5), +.BR pam_securetty (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/services.5 b/man5/services.5 new file mode 100644 index 0000000..380ff89 --- /dev/null +++ b/man5/services.5 @@ -0,0 +1,228 @@ +.\" This manpage is Copyright (C) 1996 Austin Donnelly , +.\" with additional material Copyright (c) 1995 Martin Schulze +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" This manpage was made by merging two independently written manpages, +.\" one written by Martin Schulze (18 Oct 95), the other written by +.\" Austin Donnelly, (9 Jan 96). +.\" +.\" Thu Jan 11 12:14:41 1996 Austin Donnelly +.\" * Merged two services(5) manpages +.\" +.TH SERVICES 5 2010-05-22 "Linux" "Linux Programmer's Manual" +.SH NAME +services \- Internet network services list +.SH DESCRIPTION +.B services +is a plain ASCII file providing a mapping between human-friendly textual +names for internet services, and their underlying assigned port +numbers and protocol types. +Every networking program should look into +this file to get the port number (and protocol) for its service. +The C library routines +.BR getservent (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR setservent (3), +and +.BR endservent (3) +support querying this file from programs. +.PP +Port numbers are assigned by the IANA (Internet Assigned Numbers +Authority), and their current policy is to assign both TCP and UDP +protocols when assigning a port number. +Therefore, most entries will +have two entries, even for TCP-only services. +.PP +Port numbers below 1024 (so-called "low numbered" ports) can be +bound to only by root (see +.BR bind (2), +.BR tcp (7), +and +.BR udp (7)). +This is so clients connecting to low numbered ports can trust +that the service running on the port is the standard implementation, +and not a rogue service run by a user of the machine. +Well-known port numbers specified by the IANA are normally +located in this root-only space. +.PP +The presence of an entry for a service in the +.B services +file does not necessarily mean that the service is currently running +on the machine. +See +.BR inetd.conf (5) +for the configuration of Internet services offered. +Note that not all +networking services are started by +.BR inetd (8), +and so won't appear in +.BR inetd.conf (5). +In particular, news (NNTP) and mail (SMTP) servers are often +initialized from the system boot scripts. +.PP +The location of the +.B services +file is defined by +.B _PATH_SERVICES +in +.IR "." +This is usually set to +.IR /etc/services "." +.PP +Each line describes one service, and is of the form: +.IP +\f2service-name\ \ \ port\f3/\f2protocol\ \ \ \f1[\f2aliases ...\f1] +.TP +where: +.TP 10 +.I service-name +is the friendly name the service is known by and looked up under. +It is case sensitive. +Often, the client program is named after the +.IR service-name "." +.TP +.I port +is the port number (in decimal) to use for this service. +.TP +.I protocol +is the type of protocol to be used. +This field should match an entry +in the +.BR protocols (5) +file. +Typical values include +.B tcp +and +.BR udp . +.TP +.I aliases +is an optional space or tab separated list of other names for this +service. +Again, the names are case +sensitive. +.PP +Either spaces or tabs may be used to separate the fields. +.PP +Comments are started by the hash sign (#) and continue until the end +of the line. +Blank lines are skipped. +.PP +The +.I service-name +should begin in the first column of the file, since leading spaces are +not stripped. +.I service-names +can be any printable characters excluding space and tab. +However, a conservative choice of characters should be used to minimize +compatibility problems. +For example, a\-z, 0\-9, and hyphen (\-) would seem a +sensible choice. +.PP +Lines not matching this format should not be present in the +file. +(Currently, they are silently skipped by +.BR getservent (3), +.BR getservbyname (3), +and +.BR getservbyport (3). +However, this behavior should not be relied on.) +.PP +.\" The following is not true as at glibc 2.8 (a line with a comma is +.\" ignored by getservent()); it's not clear if/when it was ever true. +.\" As a backward compatibility feature, the slash (/) between the +.\" .I port +.\" number and +.\" .I protocol +.\" name can in fact be either a slash or a comma (,). +.\" Use of the comma in +.\" modern installations is deprecated. +.\" +This file might be distributed over a network using a network-wide +naming service like Yellow Pages/NIS or BIND/Hesiod. +.PP +A sample +.B services +file might look like this: +.PP +.in +4n +.EX +netstat 15/tcp +qotd 17/tcp quote +msp 18/tcp # message send protocol +msp 18/udp # message send protocol +chargen 19/tcp ttytst source +chargen 19/udp ttytst source +ftp 21/tcp +# 22 \- unassigned +telnet 23/tcp +.EE +.in +.SH FILES +.TP +.I /etc/services +The Internet network services list +.TP +.I +Definition of +.B _PATH_SERVICES +.\" .SH BUGS +.\" It's not clear when/if the following was ever true; +.\" it isn't true for glibc 2.8: +.\" There is a maximum of 35 aliases, due to the way the +.\" .BR getservent (3) +.\" code is written. +.\" +.\" It's not clear when/if the following was ever true; +.\" it isn't true for glibc 2.8: +.\" Lines longer than +.\" .B BUFSIZ +.\" (currently 1024) characters will be ignored by +.\" .BR getservent (3), +.\" .BR getservbyname (3), +.\" and +.\" .BR getservbyport (3). +.\" However, this will also cause the next line to be mis-parsed. +.SH SEE ALSO +.BR listen (2), +.BR endservent (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR getservent (3), +.BR setservent (3), +.BR inetd.conf (5), +.BR protocols (5), +.BR inetd (8) +.PP +Assigned Numbers RFC, most recently RFC\ 1700, (AKA STD0002). +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/shells.5 b/man5/shells.5 new file mode 100644 index 0000000..cb9d82e --- /dev/null +++ b/man5/shells.5 @@ -0,0 +1,68 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Thu May 20 20:45:48 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:11:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Nov 21 10:49:38 1993 by Michael Haardt +.\" Modified Sun Feb 26 15:09:15 1995 by Rik Faith (faith@cs.unc.edu) +.TH SHELLS 5 2017-11-26 "" "Linux Programmer's Manual" +.SH NAME +shells \- pathnames of valid login shells +.SH DESCRIPTION +.I /etc/shells +is a text file which contains the full pathnames of valid login shells. +This file is consulted by +.BR chsh (1) +and available to be queried by other programs. +.PP +Be aware that there are programs which consult this file to +find out if a user is a normal user; +for example, +FTP daemons traditionally +disallow access to users with shells not included in this file. +.SH FILES +.I /etc/shells +.SH EXAMPLE +.I /etc/shells +may contain the following paths: +.PP +.in +4n +.EX +.I /bin/sh +.I /bin/bash +.I /bin/csh +.EE +.in +.SH SEE ALSO +.BR chsh (1), +.BR getusershell (3), +.BR pam_shells (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/slabinfo.5 b/man5/slabinfo.5 new file mode 100644 index 0000000..4d701a8 --- /dev/null +++ b/man5/slabinfo.5 @@ -0,0 +1,249 @@ +.\" Copyright (c) 2001 Andreas Dilger (adilger@turbolinux.com) +.\" and Copyright (c) 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SLABINFO 5 2017-09-15 "" "Linux Programmer's Manual" +.SH NAME +slabinfo \- kernel slab allocator statistics +.SH SYNOPSIS +.B cat /proc/slabinfo +.SH DESCRIPTION +Frequently used objects in the Linux kernel +(buffer heads, inodes, dentries, etc.) +have their own cache. +The file +.I /proc/slabinfo +gives statistics on these caches. +The following (edited) output shows an example of the +contents of this file: +.PP +.in 0 +.EX +$ \fBsudo cat /proc/slabinfo\fP +slabinfo - version: 2.1 +# name ... +sigqueue 100 100 160 25 1 : tunables 0 0 0 : slabdata 4 4 0 +sighand_cache 355 405 2112 15 8 : tunables 0 0 0 : slabdata 27 27 0 +kmalloc-8192 96 96 8192 4 8 : tunables 0 0 0 : slabdata 24 24 0 +\&... +.EE +.in +.PP +The first line of output includes a version number, +which allows an application that is reading the file to handle changes +in the file format. +(See VERSIONS, below.) +The next line lists the names of the columns in the remaining lines. +.PP +Each of the remaining lines displays information about a specified cache. +Following the cache name, +the output shown in each line shows three components for each cache: +.IP * 3 +statistics +.IP * +tunables +.IP * +slabdata +.PP +The statistics are as follows: +.TP +.I active_objs +The number of objects that are currently active (i.e., in use). +.TP +.I num_objs +The total number of allocated objects +(i.e., objects that are both in use and not in use). +.TP +.I objsize +The size of objects in this slab, in bytes. +.TP +.I objperslab +The number of objects stored in each slab. +.TP +.I pagesperslab +The number of pages allocated for each slab. +.PP +The +.I tunables +entries in each line show tunable parameters for the corresponding cache. +When using the default SLUB allocator, there are no tunables, the +.I /proc/slabinfo +file is not writable, and the value 0 is shown in these fields. +When using the older SLAB allocator, +the tunables for a particular cache can be set by writing +lines of the following form to +.IR /proc/slabinfo : +.PP +.in +4n +.EX +# \fBecho 'name limit batchcount sharedfactor' > /proc/slabinfo\fP +.EE +.in +.PP +Here, +.I name +is the cache name, and +.IR limit , +.IR batchcount , +and +.IR sharedfactor +are integers defining new values for the corresponding tunables. +The +.I limit +value should be a positive value, +.I batchcount +should be a positive value that is less than or equal to +.IR limit , +and +.I sharedfactor +should be nonnegative. +If any of the specified values is invalid, +the cache settings are left unchanged. +.PP +The +.I tunables +entries in each line contain the following fields: +.TP +.I limit +The maximum number of objects that will be cached. +.\" https://lwn.net/Articles/56360/ +.\" This is the limit on the number of free objects that can be stored +.\" in the per-CPU free list for this slab cache. +.TP +.I batchcount +On SMP systems, this specifies the number of objects to transfer at one time +when refilling the available object list. +.\" https://lwn.net/Articles/56360/ +.\" On SMP systems, when we refill the available object list, instead +.\" of doing one object at a time, we do batch-count objects at a time. +.TP +.I sharedfactor +[To be documented] +.\" +.PP +The +.I slabdata +entries in each line contain the following fields: +.TP +.I active_slabs +The number of active slabs. +.TP +.I nums_slabs +The total number of slabs. +.TP +.I sharedavail +[To be documented] +.PP +Note that because of object alignment and slab cache overhead, +objects are not normally packed tightly into pages. +Pages with even one in-use object are considered in-use and cannot be +freed. +.PP +Kernels configured with +.B CONFIG_DEBUG_SLAB +will also have additional statistics fields in each line, +and the first line of the file will contain the string "(statistics)". +The statistics field include : the high water mark of active +objects; the number of times objects have been allocated; +the number of times the cache has grown (new pages added +to this cache); the number of times the cache has been +reaped (unused pages removed from this cache); and the +number of times there was an error allocating new pages +to this cache. +.\" +.\" SMP systems will also have "(SMP)" in the first line of +.\" output, and will have two additional columns for each slab, +.\" reporting the slab allocation policy for the CPU-local +.\" cache (to reduce the need for inter-CPU synchronization +.\" when allocating objects from the cache). +.\" The first column is the per-CPU limit: the maximum number of objects that +.\" will be cached for each CPU. +.\" The second column is the +.\" batchcount: the maximum number of free objects in the +.\" global cache that will be transferred to the per-CPU cache +.\" if it is empty, or the number of objects to be returned +.\" to the global cache if the per-CPU cache is full. +.\" +.\" If both slab cache statistics and SMP are defined, there +.\" will be four additional columns, reporting the per-CPU +.\" cache statistics. +.\" The first two are the per-CPU cache +.\" allocation hit and miss counts: the number of times an +.\" object was or was not available in the per-CPU cache +.\" for allocation. +.\" The next two are the per-CPU cache free +.\" hit and miss counts: the number of times a freed object +.\" could or could not fit within the per-CPU cache limit, +.\" before flushing objects to the global cache. +.SH VERSIONS +The +.I /proc/slabinfo +file first appeared in Linux 2.1.23. +The file is versioned, +and over time there have been a number of versions with different layouts: +.TP +1.0 +Present throughout the Linux 2.2.x kernel series. +.TP +1.1 +Present in the Linux 2.4.x kernel series. +.\" First appeared in 2.4.0-test3 +.TP +1.2 +A format that was briefly present in the Linux 2.5 development series. +.\" from 2.5.45 to 2.5.70 +.TP +2.0 +Present in Linux 2.6.x kernels up to and including Linux 2.6.9. +.\" First appeared in 2.5.71 +.TP +2.1 +The current format, which first appeared in Linux 2.6.10. +.SH NOTES +Only root can read and (if the kernel was configured with +.BR CONFIG_SLAB ) +write the +.IR /proc/slabinfo +file. +.PP +The total amount of memory allocated to the SLAB/SLUB cache is shown in the +.I Slab +field of +.IR /proc/meminfo . +.SH SEE ALSO +.BR slabtop (1) +.PP +The kernel source file +.IR Documentation/vm/slub.txt +and +.IR tools/vm/slabinfo.c . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/sysfs.5 b/man5/sysfs.5 new file mode 100644 index 0000000..e9c718d --- /dev/null +++ b/man5/sysfs.5 @@ -0,0 +1,303 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SYSFS 5 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +sysfs \- a filesystem for exporting kernel objects +.SH DESCRIPTION +The +.B sysfs +filesystem is a pseudo-filesystem which provides an interface to +kernel data structures. +(More precisely, the files and directories in +.B sysfs +provide a view of the +.IR kobject +structures defined internally within the kernel.) +The files under +.B sysfs +provide information about devices, kernel modules, filesystems, +and other kernel components. +.PP +The +.B sysfs +filesystem is commonly mounted at +.IR /sys . +Typically, it is mounted automatically by the system, +but it can also be mounted manually using a command such as: +.PP +.in +4n +.EX +mount \-t sysfs sysfs /sys +.EE +.in +.PP +Many of the files in the +.B sysfs +filesystem are read-only, +but some files are writable, allowing kernel variables to be changed. +To avoid redundancy, +symbolic links are heavily used to connect entries across the filesystem tree. +.\" +.SS Files and directories +The following list describes some of the files and directories under the +.I /sys +hierarchy. +.TP +.IR /sys/block +This subdirectory contains one symbolic link for each block device +that has been discovered on the system. +The symbolic links point to corresponding directories under +.IR /sys/devices . +.TP +.IR /sys/bus +This directory contains one subdirectory for each of the bus types +in the kernel. +Inside each of these directories are two subdirectories: +.RS +.TP +.IR devices +This subdirectory contains symbolic links to entries in +.IR /sys/devices +that correspond to the devices discovered on this bus. +.TP +.IR drivers +This subdirectory contains one subdirectory for each device driver +that is loaded on this bus. +.RE +.TP +.IR /sys/class +This subdirectory contains a single layer of further subdirectories +for each of the device classes that have been registered on the system +(e.g., terminals, network devices, block devices, graphics devices, +sound devices, and so on). +Inside each of these subdirectories are symbolic links for each of the +devices in this class. +These symbolic links refer to entries in the +.IR /sys/devices +directory. +.TP +.IR /sys/class/net +Each of the entries in this directory is a symbolic link +representing one of the real or virtual networking devices +that are visible in the network namespace of the process +that is accessing the directory. +Each of these symbolic links refers to entries in the +.IR /sys/devices +directory. +.TP +.IR /sys/dev +This directory contains two subdirectories +.IR block / +and +.IR char/ , +corresponding, respectively, +to the block and character devices on the system. +Inside each of these subdirectories are symbolic links with names of the form +.IR major-ID : minor-ID , +where the ID values correspond to the major and minor ID of a specific device. +Each symbolic link points to the +.B sysfs +directory for a device. +The symbolic links inside +.IR /sys/dev +thus provide an easy way to look up the +.B sysfs +interface using the device IDs returned by a call to +.BR stat (2) +(or similar). +.IP +The following shell session shows an example from +.IR /sys/dev : +.IP +.in +4n +.EX +$ \fBstat \-c "%t %T" /dev/null\fP +1 3 +$ \fBreadlink /sys/dev/char/1\\:3\fP +\&../../devices/virtual/mem/null +$ \fBls \-Fd /sys/devices/virtual/mem/null\fP +/sys/devices/virtual/mem/null/ +$ \fBls \-d1 /sys/devices/virtual/mem/null/*\fP +/sys/devices/virtual/mem/null/dev +/sys/devices/virtual/mem/null/power/ +/sys/devices/virtual/mem/null/subsystem@ +/sys/devices/virtual/mem/null/uevent +.EE +.in +.TP +.IR /sys/devices +This is a directory that contains a filesystem representation of +the kernel device tree, +which is a hierarchy of +.I device +structures within the kernel. +.TP +.IR /sys/firmware +This subdirectory contains interfaces for viewing and manipulating +firmware-specific objects and attributes. +.TP +.IR /sys/fs +This directory contains subdirectories for some filesystems. +A filesystem will have a subdirectory here only if it chose +to explicitly create the subdirectory. +.TP +.IR /sys/fs/cgroup +This directory conventionally is used as a mount point for a +.BR tmpfs (5) +filesystem containing mount points for +.BR cgroups (7) +filesystems. +.TP +.IR /sys/hypervisor +[To be documented] +.TP +.IR /sys/kernel +This subdirectory contains various files and subdirectories that provide +information about the running kernel. +.TP +.IR /sys/kernel/cgroup/ +For information about the files in this directory, see +.BR cgroups (7). +.TP +.IR /sys/kernel/debug/tracing +Mount point for the +.I tracefs +filesystem used by the kernel's +.I ftrace +facility. +(For information on +.IR ftrace , +see the kernel source file +.IR Documentation/trace/ftrace.txt .) +.TP +.IR /sys/kernel/mm +This subdirectory contains various files and subdirectories that provide +information about the kernel's memory management subsystem. +.TP +.IR /sys/kernel/mm/hugepages +This subdirectory contains one subdirectory for each of the +huge page sizes that the system supports. +The subdirectory name indicates the huge page size (e.g., +.IR hugepages-2048kB ). +Within each of these subdirectories is a set of files +that can be used to view and (in some cases) change settings +associated with that huge page size. +For further information, see the kernel source file +.IR Documentation/vm/hugetlbpage.txt . +.TP +.IR /sys/module +This subdirectory contains one subdirectory +for each module that is loaded into the kernel. +The name of each directory is the name of the module. +In each of the subdirectories, there may be following files: +.RS +.TP +.I coresize +[to be documented] +.TP +.I initsize +[to be documented] +.TP +.I initstate +[to be documented] +.TP +.I refcnt +[to be documented] +.TP +.I srcversion +[to be documented] +.TP +.I taint +[to be documented] +.TP +.I uevent +[to be documented] +.TP +.I version +[to be documented] +.RE +.IP +In each of the subdirectories, there may be following subdirectories: +.RS +.TP +.I drivers +[To be documented] +.TP +.I holders +[To be documented] +.TP +.I notes +[To be documented] +.TP +.I parameters +This directory contains one file for each module parameter, +with each file containing the value of the corresponding parameter. +Some of these files are writable, allowing the +.TP +.I sections +This subdirectories contains files with information about module sections. +This information is mainly used for debugging. +.TP +.I +[To be documented] +.RE +.TP +.IR /sys/power +[To be documented] +.SH VERSIONS +The +.B sysfs +filesystem first appeared in Linux 2.6.0. +.SH CONFORMING TO +The +.B sysfs +filesystem is Linux-specific. +.SH NOTES +This manual page is incomplete, possibly inaccurate, and is the kind +of thing that needs to be updated very often. +.SH SEE ALSO +.BR proc (5), +.BR udev (7) +.PP +P. Mochel. (2005). +.IR "The sysfs filesystem" . +Proceedings of the 2005 Ottawa Linux Symposium. +.\" https://www.kernel.org/pub/linux/kernel/people/mochel/doc/papers/ols-2005/mochel.pdf +.PP +The kernel source file +.I Documentation/filesystems/sysfs.txt +and various other files in +.IR Documentation/ABI +and +.IR Documentation/*/sysfs.txt +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/termcap.5 b/man5/termcap.5 new file mode 100644 index 0000000..0c4a72e --- /dev/null +++ b/man5/termcap.5 @@ -0,0 +1,483 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified formatting Sat Jul 24 17:13:38 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified (extensions and corrections) +.\" Sun May 1 14:21:25 MET DST 1994 Michael Haardt +.\" If mistakes in the capabilities are found, please send a bug report to: +.\" michael@moria.de +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) +.TH TERMCAP 5 1996-10-21 "Linux" "Linux Programmer's Manual" +.SH NAME +termcap \- terminal capability database +.SH DESCRIPTION +The termcap database is an obsolete facility for describing the +capabilities of character-cell terminals and printers. +It is retained only for capability with old programs; +new programs should use the +.BR terminfo (5) +database and associated libraries. +.PP +.I /etc/termcap +is an ASCII file (the database master) that lists the capabilities of +many different types of terminals. +Programs can read termcap to find +the particular escape codes needed to control the visual attributes of +the terminal actually in use. +(Other aspects of the terminal are +handled by +.BR stty (1).) +The termcap database is indexed on the +.B TERM +environment variable. +.PP +Termcap entries must be defined on a single logical line, with \(aq\\\(aq +used to suppress the newline. +Fields are separated by \(aq:\(aq. +The first field of each entry starts at the left-hand margin, +and contains a list of names for the terminal, separated by \(aq|\(aq. +.PP +The first subfield may (in BSD termcap entries from versions 4.3 and +earlier) contain a short name consisting of two characters. +This short name may consist of capital or small letters. +In 4.4BSD, termcap entries this field is omitted. +.PP +The second subfield (first, in the newer 4.4BSD format) contains the +name used by the environment variable +.BR TERM . +It should be spelled in lowercase letters. +Selectable hardware capabilities should be marked +by appending a hyphen and a suffix to this name. +See below for an example. +Usual suffixes are w (more than 80 characters wide), am +(automatic margins), nam (no automatic margins), and rv (reverse video +display). +The third subfield contains a long and descriptive name for +this termcap entry. +.PP +Subsequent fields contain the terminal capabilities; any continued +capability lines must be indented one tab from the left margin. +.PP +Although there is no defined order, it is suggested to write first +boolean, then numeric, and then string capabilities, each sorted +alphabetically without looking at lower or upper spelling. +Capabilities of similar functions can be written in one line. +.PP +Example for: +.nf +.PP +Head line: vt|vt101|DEC VT 101 terminal in 80 character mode:\e +Head line: Vt|vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\e +Boolean: :bs:\e +Numeric: :co#80:\e +String: :sr=\eE[H:\e +.fi +.SS Boolean capabilities +.nf +5i Printer will not echo on screen +am Automatic margins which means automatic line wrap +bs Control-H (8 dec.) performs a backspace +bw Backspace on left margin wraps to previous line and right margin +da Display retained above screen +db Display retained below screen +eo A space erases all characters at cursor position +es Escape sequences and special characters work in status line +gn Generic device +hc This is a hardcopy terminal +HC The cursor is hard to see when not on bottom line +hs Has a status line +hz Hazeltine bug, the terminal can not print tilde characters +in Terminal inserts null bytes, not spaces, to fill whitespace +km Terminal has a meta key +mi Cursor movement works in insert mode +ms Cursor movement works in standout/underline mode +NP No pad character +NR ti does not reverse te +nx No padding, must use XON/XOFF +os Terminal can overstrike +ul Terminal underlines although it can not overstrike +xb Beehive glitch, f1 sends ESCAPE, f2 sends \fB^C\fP +xn Newline/wraparound glitch +xo Terminal uses xon/xoff protocol +xs Text typed over standout text will be displayed in standout +xt Teleray glitch, destructive tabs and odd standout mode +.fi +.SS Numeric capabilities +.nf +co Number of columns +dB Delay in milliseconds for backspace on hardcopy terminals +dC Delay in milliseconds for carriage return on hardcopy terminals +dF Delay in milliseconds for form feed on hardcopy terminals +dN Delay in milliseconds for new line on hardcopy terminals +dT Delay in milliseconds for tabulator stop on hardcopy terminals +dV Delay in milliseconds for vertical tabulator stop on + hardcopy terminals +it Difference between tab positions +lh Height of soft labels +lm Lines of memory +lw Width of soft labels +li Number of lines +Nl Number of soft labels +pb Lowest baud rate which needs padding +sg Standout glitch +ug Underline glitch +vt virtual terminal number +ws Width of status line if different from screen width +.fi +.SS String capabilities +.nf +!1 shifted save key +!2 shifted suspend key +!3 shifted undo key +#1 shifted help key +#2 shifted home key +#3 shifted input key +#4 shifted cursor left key +%0 redo key +%1 help key +%2 mark key +%3 message key +%4 move key +%5 next-object key +%6 open key +%7 options key +%8 previous-object key +%9 print key +%a shifted message key +%b shifted move key +%c shifted next key +%d shifted options key +%e shifted previous key +%f shifted print key +%g shifted redo key +%h shifted replace key +%i shifted cursor right key +%j shifted resume key +&0 shifted cancel key +&1 reference key +&2 refresh key +&3 replace key +&4 restart key +&5 resume key +&6 save key +&7 suspend key +&8 undo key +&9 shifted begin key +*0 shifted find key +*1 shifted command key +*2 shifted copy key +*3 shifted create key +*4 shifted delete character +*5 shifted delete line +*6 select key +*7 shifted end key +*8 shifted clear line key +*9 shifted exit key +@0 find key +@1 begin key +@2 cancel key +@3 close key +@4 command key +@5 copy key +@6 create key +@7 end key +@8 enter/send key +@9 exit key +al Insert one line +AL Insert %1 lines +ac Pairs of block graphic characters to map alternate character set +ae End alternative character set +as Start alternative character set for block graphic characters +bc Backspace, if not \fB^H\fP +bl Audio bell +bt Move to previous tab stop +cb Clear from beginning of line to cursor +cc Dummy command character +cd Clear to end of screen +ce Clear to end of line +ch Move cursor horizontally only to column %1 +cl Clear screen and cursor home +cm Cursor move to row %1 and column %2 (on screen) +CM Move cursor to row %1 and column %2 (in memory) +cr Carriage return +cs Scroll region from line %1 to %2 +ct Clear tabs +cv Move cursor vertically only to line %1 +dc Delete one character +DC Delete %1 characters +dl Delete one line +DL Delete %1 lines +dm Begin delete mode +do Cursor down one line +DO Cursor down #1 lines +ds Disable status line +eA Enable alternate character set +ec Erase %1 characters starting at cursor +ed End delete mode +ei End insert mode +ff Formfeed character on hardcopy terminals +fs Return character to its position before going to status line +F1 The string sent by function key f11 +F2 The string sent by function key f12 +F3 The string sent by function key f13 +\&... \&... +F9 The string sent by function key f19 +FA The string sent by function key f20 +FB The string sent by function key f21 +\&... \&... +FZ The string sent by function key f45 +Fa The string sent by function key f46 +Fb The string sent by function key f47 +\&... \&... +Fr The string sent by function key f63 +hd Move cursor a half line down +ho Cursor home +hu Move cursor a half line up +i1 Initialization string 1 at login +i3 Initialization string 3 at login +is Initialization string 2 at login +ic Insert one character +IC Insert %1 characters +if Initialization file +im Begin insert mode +ip Insert pad time and needed special characters after insert +iP Initialization program +K1 upper left key on keypad +K2 center key on keypad +K3 upper right key on keypad +K4 bottom left key on keypad +K5 bottom right key on keypad +k0 Function key 0 +k1 Function key 1 +k2 Function key 2 +k3 Function key 3 +k4 Function key 4 +k5 Function key 5 +k6 Function key 6 +k7 Function key 7 +k8 Function key 8 +k9 Function key 9 +k; Function key 10 +ka Clear all tabs key +kA Insert line key +kb Backspace key +kB Back tab stop +kC Clear screen key +kd Cursor down key +kD Key for delete character under cursor +ke turn keypad off +kE Key for clear to end of line +kF Key for scrolling forward/down +kh Cursor home key +kH Cursor hown down key +kI Insert character/Insert mode key +kl Cursor left key +kL Key for delete line +kM Key for exit insert mode +kN Key for next page +kP Key for previous page +kr Cursor right key +kR Key for scrolling backward/up +ks Turn keypad on +kS Clear to end of screen key +kt Clear this tab key +kT Set tab here key +ku Cursor up key +l0 Label of zeroth function key, if not f0 +l1 Label of first function key, if not f1 +l2 Label of first function key, if not f2 +\&... \&... +la Label of tenth function key, if not f10 +le Cursor left one character +ll Move cursor to lower left corner +LE Cursor left %1 characters +LF Turn soft labels off +LO Turn soft labels on +mb Start blinking +MC Clear soft margins +md Start bold mode +me End all mode like so, us, mb, md, and mr +mh Start half bright mode +mk Dark mode (Characters invisible) +ML Set left soft margin +mm Put terminal in meta mode +mo Put terminal out of meta mode +mp Turn on protected attribute +mr Start reverse mode +MR Set right soft margin +nd Cursor right one character +nw Carriage return command +pc Padding character +pf Turn printer off +pk Program key %1 to send string %2 as if typed by user +pl Program key %1 to execute string %2 in local mode +pn Program soft label %1 to show string %2 +po Turn the printer on +pO Turn the printer on for %1 (<256) bytes +ps Print screen contents on printer +px Program key %1 to send string %2 to computer +r1 Reset string 1 to set terminal to sane modes +r2 Reset string 2 to set terminal to sane modes +r3 Reset string 3 to set terminal to sane modes +RA disable automatic margins +rc Restore saved cursor position +rf Reset string filename +RF Request for input from terminal +RI Cursor right %1 characters +rp Repeat character %1 for %2 times +rP Padding after character sent in replace mode +rs Reset string +RX Turn off XON/XOFF flow control +sa Set %1 %2 %3 %4 %5 %6 %7 %8 %9 attributes +SA enable automatic margins +sc Save cursor position +se End standout mode +sf Normal scroll one line +SF Normal scroll %1 lines +so Start standout mode +sr Reverse scroll +SR scroll back %1 lines +st Set tabulator stop in all rows at current column +SX Turn on XON/XOFF flow control +ta move to next hardware tab +tc Read in terminal description from another entry +te End program that uses cursor motion +ti Begin program that uses cursor motion +ts Move cursor to column %1 of status line +uc Underline character under cursor and move cursor right +ue End underlining +up Cursor up one line +UP Cursor up %1 lines +us Start underlining +vb Visible bell +ve Normal cursor visible +vi Cursor invisible +vs Standout cursor +wi Set window from line %1 to %2 and column %3 to %4 +XF XOFF character if not \fB^S\fP +.fi +.PP +There are several ways of defining the control codes for string capabilities: +.PP +Every normal character represents itself, +except \(aq^\(aq, \(aq\e\(aq, and \(aq%\(aq. +.PP +A \fB^x\fP means Control-x. +Control-A equals 1 decimal. +.PP +\ex means a special code. +x can be one of the following characters: +.RS +E Escape (27) +.br +n Linefeed (10) +.br +r Carriage return (13) +.br +t Tabulation (9) +.br +b Backspace (8) +.br +f Form feed (12) +.br +0 Null character. +A \exxx specifies the octal character xxx. +.RE +.IP i +Increments parameters by one. +.IP r +Single parameter capability +.IP + +Add value of next character to this parameter and do binary output +.IP 2 +Do ASCII output of this parameter with a field with of 2 +.IP d +Do ASCII output of this parameter with a field with of 3 +.IP % +Print a \(aq%\(aq +.PP +If you use binary output, then you should avoid the null character (\(aq\\0\(aq) +because it terminates the string. +You should reset tabulator expansion +if a tabulator can be the binary output of a parameter. +.IP Warning: +The above metacharacters for parameters may be wrong: they document Minix +termcap which may not be compatible with Linux termcap. +.PP +The block graphic characters can be specified by three string capabilities: +.IP as +start the alternative charset +.IP ae +end the alternative charset +.IP ac +pairs of characters. +The first character is the name of the block graphic +symbol and the second characters is its definition. +.PP +The following names are available: +.PP +.nf ++ right arrow (>) +, left arrow (<) +\&. down arrow (v) +0 full square (#) +I lantern (#) +- upper arrow (^) +\&' rhombus (+) +a chess board (:) +f degree (') +g plus-minus (#) +h square (#) +j right bottom corner (+) +k right upper corner (+) +l left upper corner (+) +m left bottom corner (+) +n cross (+) +o upper horizontal line (-) +q middle horizontal line (-) +s bottom horizontal line (_) +t left tee (+) +u right tee (+) +v bottom tee (+) +w normal tee (+) +x vertical line (|) +~ paragraph (???) +.fi +.PP +The values in parentheses are suggested defaults which are used by the +.IR curses +library, if the capabilities are missing. +.SH SEE ALSO +.BR ncurses (3), +.BR termcap (3), +.BR terminfo (5) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/tmpfs.5 b/man5/tmpfs.5 new file mode 100644 index 0000000..e6c64b0 --- /dev/null +++ b/man5/tmpfs.5 @@ -0,0 +1,153 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH TMPFS 5 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +tmpfs \- a virtual memory filesystem +.SH DESCRIPTION +The +.B tmpfs +facility allows the creation of filesystems whose contents reside +in virtual memory. +Since the files on such filesystems typically reside in RAM, +file access is extremely fast. +.PP +The filesystem is automatically created when mounting +a filesystem with the type +.BR tmpfs +via a command such as the following: +.PP +.in +4n +.EX +$ sudo mount \-t tmpfs -o size=10M tmpfs /mnt/mytmpfs +.EE +.in +.PP +A +.B tmpfs +filesystem has the following properties: +.IP * 3 +The filesystem can employ swap space when physical memory pressure +demands it. +.IP * +The +.I size +option can be used to specify an upper limit on the size of the filesystem. +(The default size is half of the available RAM size.) +The filesystem consumes only as much physical memory and swap space +as is required to store the current contents of the filesystem. +.IP * +During a remount operation +.RI ( "mount\ \-o\ remount" ), +the filesystem size can be changed +(without losing the existing contents of the filesystem). +.PP +If a +.B tmpfs +filesystem is unmounted, its contents are discarded (lost). +.SH VERSIONS +The +.B tmpfs +facility was added in Linux 2.4, as a successor to the older +.B ramfs +facility, which did not provide limit checking or +allow for the use of swap space. +.SH NOTES +For a description of the mount options that may be employed when mounting a +.B tmpfs +filesystem, see +.BR mount (8). +.PP +In order for user-space tools and applications to create +.B tmpfs +filesystems, the kernel must be configured with the +.B CONFIG_TMPFS +option. +.PP +The +.BR tmpfs +filesystem supports extended attributes (see +.BR xattr (7)), +but +.I user +extended attributes are not permitted. +.PP +An internal shared memory filesystem is used for +System V shared memory +.RB ( shmget (2)) +and shared anonymous mappings +.RB ( mmap (2) +with the +.B MAP_SHARED +and +.BR MAP_ANONYMOUS +flags). +This filesystem is available regardless of whether +the kernel was configured with the +.B CONFIG_TMPFS +option. +.PP +A +.B tmpfs +filesystem mounted at +.IR /dev/shm +as used for the implementation of POSIX shared memory +.RB ( shm_overview (7)) +and POSIX semaphores +.RB ( sem_overview (7)). +.PP +The amount of memory consumed by all +.B tmpfs +filesystems is shown in the +.I Shmem +field of +.IR /proc/meminfo +and in the +.I shared +field displayed by +.BR free (1). +.PP +The +.B tmpfs +facility was formerly called +.BR shmfs . +.SH SEE ALSO +.BR df (1), +.BR du (1), +.BR memfd_create (2), +.BR mmap (2), +.BR shm_open (3), +.BR mount (8) +.PP +The kernel source file +.IR Documentation/filesystems/tmpfs.txt . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/ttytype.5 b/man5/ttytype.5 new file mode 100644 index 0000000..3ea9ad8 --- /dev/null +++ b/man5/ttytype.5 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:17:50 1993 by Rik Faith +.\" Modified Thu Oct 19 21:25:21 MET 1995 by Martin Schulze +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.\" xk +.TH TTYTYPE 5 2012-12-31 "Linux" "Linux Programmer's Manual" +.SH NAME +ttytype \- terminal device to default terminal type mapping +.SH DESCRIPTION +The +.I /etc/ttytype +file associates +.BR termcap (5)/ terminfo (5) +terminal type names +with tty lines. +Each line consists of a terminal type, followed by +whitespace, followed by a tty name (a device name without the +.IR /dev/ ") prefix." +.PP +This association is used by the program +.BR tset (1) +to set the environment variable +.B TERM +to the default terminal name for +the user's current tty. +.PP +This facility was designed for a traditional time-sharing environment +featuring character-cell terminals hardwired to a UNIX minicomputer. +It is little used on modern workstation and personal UNIX systems. +.SH FILES +.TP +.I /etc/ttytype +the tty definitions file. +.SH EXAMPLE +A typical +.I /etc/ttytype +is: +.PP +.in +4n +.EX +con80x25 tty1 +vt320 ttys0 +.EE +.in +.SH SEE ALSO +.BR termcap (5), +.BR terminfo (5), +.BR agetty (8), +.BR mingetty (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/tzfile.5 b/man5/tzfile.5 new file mode 100644 index 0000000..c570b3e --- /dev/null +++ b/man5/tzfile.5 @@ -0,0 +1,206 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson . +.\" %%%LICENSE_END +.\" +.\" @(#)tzfile.5 7.11 +.\" +.TH TZFILE 5 2017-08-04 "" "Linux Programmer's Manual" +.SH NAME +tzfile \- timezone information +.SH DESCRIPTION +.ie '\(lq'' .ds lq \&"\" +.el .ds lq \(lq\" +.ie '\(rq'' .ds rq \&"\" +.el .ds rq \(rq\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +The timezone information files used by +.BR tzset (3) +are typically found under a directory with a name like +.IR /usr/share/zoneinfo . +These files begin with a 44-byte header containing the following fields: +.IP * 2 +The magic four-byte ASCII sequence +.q "TZif" +identifies the file as a timezone information file. +.IP * +A byte identifying the version of the file's format +(as of 2017, either an ASCII NUL, or +.q "2", +or +.q "3" ). +.IP * +Fifteen bytes containing zeros reserved for future use. +.IP * +Six four-byte integer values +written in a standard byte order +(the high-order byte of the value is written first). +These values are, +in order: +.RS +.TP +.I tzh_ttisgmtcnt +The number of UT/local indicators stored in the file. +.TP +.I tzh_ttisstdcnt +The number of standard/wall indicators stored in the file. +.TP +.I tzh_leapcnt +The number of leap seconds for which data entries are stored in the file. +.TP +.I tzh_timecnt +The number of transition times for which data entries are stored +in the file. +.TP +.I tzh_typecnt +The number of local time types for which data entries are stored +in the file (must not be zero). +.TP +.I tzh_charcnt +The number of bytes of timezone abbreviation strings +stored in the file. +.RE +.PP +The above header is followed by the following fields, whose lengths +vary depend on the contents of the header: +.IP * 2 +.I tzh_timecnt +four-byte signed integer values sorted in ascending order. +These values are written in standard byte order. +Each is used as a transition time (as returned by +.BR time (2)) +at which the rules for computing local time change. +.IP * +.I tzh_timecnt +one-byte unsigned integer values; +each one tells which of the different types of local time types +described in the file is associated with the time period +starting with the same-indexed transition time. +These values serve as indices into the next field. +.IP * +.I tzh_typecnt +.I ttinfo +entries, each defined as follows: +.PP +.in +4n +.EX +struct ttinfo { + int32_t tt_gmtoff; + unsigned char tt_isdst; + unsigned char tt_abbrind; +}; +.EE +.in +.PP +Each structure is written as a four-byte signed integer value for +.IR tt_gmtoff , +in a standard byte order, followed by a one-byte value for +.I tt_isdst +and a one-byte value for +.IR tt_abbrind . +In each structure, +.I tt_gmtoff +gives the number of seconds to be added to UT, +.I tt_isdst +tells whether +.I tm_isdst +should be set by +.BR localtime (3) +and +.I tt_abbrind +serves as an index into the array of timezone abbreviation bytes +that follow the +.I ttinfo +structure(s) in the file. +.IP * +.I tzh_leapcnt +pairs of four-byte values, written in standard byte order; +the first value of each pair gives the nonnegative time +(as returned by +.BR time (2)) +at which a leap second occurs; +the second gives the +.I total +number of leap seconds to be applied during the time period +starting at the given time. +The pairs of values are sorted in ascending order by time. +Each transition is for one leap second, either positive or negative; +transitions always separated by at least 28 days minus 1 second. +.IP * +.I tzh_ttisstdcnt +standard/wall indicators, each stored as a one-byte value; +they tell whether the transition times associated with local time types +were specified as standard time or wall clock time, +and are used when a timezone file is used in handling POSIX-style +timezone environment variables. +.IP * +.I tzh_ttisgmtcnt +UT/local indicators, each stored as a one-byte value; +they tell whether the transition times associated with local time types +were specified as UT or local time, +and are used when a timezone file is used in handling POSIX-style +timezone environment variables. +.PP +The +.BR localtime (3) +function +uses the first standard-time +.I ttinfo +structure in the file +(or simply the first +.I ttinfo +structure in the absence of a standard-time structure) +if either +.I tzh_timecnt +is zero or the time argument is less than the first transition time recorded +in the file. +.SS Version 2 format +For version-2-format timezone files, +the above header and data are followed by a second header and data, +identical in format except that +eight bytes are used for each transition time or leap second time. +(Leap second counts remain four bytes.) +After the second header and data comes a newline-enclosed, +POSIX-TZ-environment-variable-style string for use in handling instants +after the last transition time stored in the file +(with nothing between the newlines if there is no POSIX representation for +such instants). +The POSIX-style string must agree with the local time type after +both data's last transition times; for example, given the string +.q "WET0WEST,M3.5.0,M10.5.0/3" +then if a last transition time is in July, the transition's local time +type must specify a daylight-saving time abbreviated +.q "WEST" +that is one hour east of UT. +.SS Version 3 format +For version-3-format timezone files, the POSIX-TZ-style string may +use two minor extensions to the POSIX TZ format, as described in +.BR newtzset (3). +First, the hours part of its transition times may be signed and range from +\-167 through 167 instead of the POSIX-required unsigned values +from 0 through 24. +Second, DST is in effect all year if it starts +January 1 at 00:00 and ends December 31 at 24:00 plus the difference +between daylight saving and standard time. +.PP +Future changes to the format may append more data. +.SH SEE ALSO +.BR time (2), +.BR localtime (3), +.BR tzset (3), +.BR tzselect (8), +.BR zdump (8), +.BR zic (8) +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/utmp.5 b/man5/utmp.5 new file mode 100644 index 0000000..6dfe26b --- /dev/null +++ b/man5/utmp.5 @@ -0,0 +1,363 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-02-26 by Michael Haardt +.\" Modified 1996-07-20 by Michael Haardt +.\" Modified 1997-07-02 by Nicolás Lichtmaier +.\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne +.TH UTMP 5 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +utmp, wtmp \- login records +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +The +.I utmp +file allows one to discover information about who is currently using the +system. +There may be more users currently using the system, because not +all programs use utmp logging. +.PP +.B Warning: +.I utmp +must not be writable by the user class "other", +because many system programs (foolishly) +depend on its integrity. +You risk faked system logfiles and +modifications of system files if you leave +.I utmp +writable to any user other than the owner and group owner of the file. +.PP +The file is a sequence of +.I utmp +structures, +declared as follows in +.IR +(note that this is only one of several definitions +around; details depend on the version of libc): +.in +.in +4n +.EX +/* Values for ut_type field, below */ + +#define EMPTY 0 /* Record does not contain valid info + (formerly known as UT_UNKNOWN on Linux) */ +#define RUN_LVL 1 /* Change in system run-level (see + \fBinit\fP(8)) */ +#define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */ +#define NEW_TIME 3 /* Time after system clock change + (in \fIut_tv\fP) */ +#define OLD_TIME 4 /* Time before system clock change + (in \fIut_tv\fP) */ +#define INIT_PROCESS 5 /* Process spawned by \fBinit\fP(8) */ +#define LOGIN_PROCESS 6 /* Session leader process for user login */ +#define USER_PROCESS 7 /* Normal process */ +#define DEAD_PROCESS 8 /* Terminated process */ +#define ACCOUNTING 9 /* Not implemented */ + +#define UT_LINESIZE 32 +#define UT_NAMESIZE 32 +#define UT_HOSTSIZE 256 + +struct exit_status { /* Type for ut_exit, below */ + short int e_termination; /* Process termination status */ + short int e_exit; /* Process exit status */ +}; + +struct utmp { + short ut_type; /* Type of record */ + pid_t ut_pid; /* PID of login process */ + char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */ + char ut_id[4]; /* Terminal name suffix, + or inittab(5) ID */ + char ut_user[UT_NAMESIZE]; /* Username */ + char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or + kernel version for run-level + messages */ + struct exit_status ut_exit; /* Exit status of a process + marked as DEAD_PROCESS; not + used by Linux init (1 */ + /* The ut_session and ut_tv fields must be the same size when + compiled 32- and 64-bit. This allows data files and shared + memory to be shared between 32- and 64-bit applications. */ +#if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32 + int32_t ut_session; /* Session ID (\fBgetsid\fP(2)), + used for windowing */ + struct { + int32_t tv_sec; /* Seconds */ + int32_t tv_usec; /* Microseconds */ + } ut_tv; /* Time entry was made */ +#else + long ut_session; /* Session ID */ + struct timeval ut_tv; /* Time entry was made */ +#endif + + int32_t ut_addr_v6[4]; /* Internet address of remote + host; IPv4 address uses + just ut_addr_v6[0] */ + char __unused[20]; /* Reserved for future use */ +}; + +/* Backward compatibility hacks */ +#define ut_name ut_user +#ifndef _NO_UT_TIME +#define ut_time ut_tv.tv_sec +#endif +#define ut_xtime ut_tv.tv_sec +#define ut_addr ut_addr_v6[0] +.EE +.in +.PP +This structure gives the name of the special file associated with the +user's terminal, the user's login name, and the time of login in the form +of +.BR time (2). +String fields are terminated by a null byte (\(aq\e0\(aq) +if they are shorter than the size +of the field. +.PP +The first entries ever created result from +.BR init (1) +processing +.BR inittab (5). +Before an entry is processed, though, +.BR init (1) +cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing +\fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each +record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP +and where no process with PID \fIut_pid\fP exists. +If no empty record +with the needed \fIut_id\fP can be found, +.BR init (1) +creates a new one. +It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the +current values, and \fIut_type\fP to \fBINIT_PROCESS\fP. +.PP +.BR mingetty (8) +(or +.BR agetty (8)) +locates the entry by the PID, changes \fIut_type\fP to +\fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits +for connection to be established. +.BR login (1), +after a user has been +authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes +\fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP. +Depending on +.BR mingetty (8) +(or +.BR agetty (8)) +and +.BR login (1), +records may be located by +\fIut_line\fP instead of the preferable \fIut_pid\fP. +.PP +When +.BR init (1) +finds that a process has exited, it locates its utmp +entry by \fIut_pid\fP, sets \fIut_type\fP to \fBDEAD_PROCESS\fP, and +clears \fIut_user\fP, \fIut_host\fP and \fIut_time\fP with null bytes. +.PP +.BR xterm (1) +and other terminal emulators directly create a +\fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the +string that suffix part of the terminal name (the characters +following \fI/dev/[pt]ty\fP). +If they find a \fBDEAD_PROCESS\fP for this ID, +they recycle it, otherwise they create a new entry. +If they can, they +will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that +they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP +as well. +.PP +.BR telnetd (8) +sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to +.BR login (1) +as usual. +After the telnet session ends, +.BR telnetd (8) +cleans up utmp in the described way. +.PP +The \fIwtmp\fP file records all logins and logouts. +Its format is exactly like \fIutmp\fP except that a null username +indicates a logout +on the associated terminal. +Furthermore, the terminal name \fB~\fP +with username \fBshutdown\fP or \fBreboot\fP indicates a system +shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP +logs the old/new system time when +.BR date (1) +changes it. +\fIwtmp\fP is maintained by +.BR login (1), +.BR init (1), +and some versions of +.BR getty (8) +(e.g., +.BR mingetty (8) +or +.BR agetty (8)). +None of these programs creates the file, so if it is +removed, record-keeping is turned off. +.SH FILES +.I /var/run/utmp +.br +.I /var/log/wtmp +.SH CONFORMING TO +.PP +POSIX.1 does not specify a +.I utmp +structure, but rather one named +.IR utmpx , +with specifications for the fields +.IR ut_type , +.IR ut_pid , +.IR ut_line , +.IR ut_id , +.IR ut_user , +and +.IR ut_tv . +POSIX.1 does not specify the lengths of the +.I ut_line +and +.I ut_user +fields. +.PP +Linux defines the +.I utmpx +structure to be the same as the +.I utmp +structure. +.SS Comparison with historical systems +Linux utmp entries conform neither to v7/BSD nor to System V; they are a +mix of the two. +.PP +v7/BSD has fewer fields; most importantly it lacks +\fIut_type\fP, which causes native v7/BSD-like programs to display (for +example) dead or login entries. +Further, there is no configuration file +which allocates slots to sessions. +BSD does so because it lacks \fIut_id\fP fields. +.PP +In Linux (as in System V), the \fIut_id\fP field of a +record will never change once it has been set, which reserves that slot +without needing a configuration file. +Clearing \fIut_id\fP may result +in race conditions leading to corrupted utmp entries and potential +security holes. +Clearing the abovementioned fields by filling them +with null bytes is not required by System V semantics, +but makes it possible to run +many programs which assume BSD semantics and which do not modify utmp. +Linux uses the BSD conventions for line contents, as documented above. +.PP +.\" mtk: What is the referrent of "them" in the following sentence? +.\" System V only uses the type field to mark them and logs +.\" informative messages such as \fB"new time"\fP in the line field. +System V has no \fIut_host\fP or \fIut_addr_v6\fP fields. +.SH NOTES +.PP +Unlike various other +systems, where utmp logging can be disabled by removing the file, utmp +must always exist on Linux. +If you want to disable +.BR who (1), +then do not make utmp world readable. +.PP +The file format is machine-dependent, so it is recommended that it be +processed only on the machine architecture where it was created. +.PP +Note that on \fIbiarch\fP platforms, that is, systems which can run both +32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.), +\fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode. +The same goes for \fIut_session\fP and \fIut_time\fP if they are present. +This allows data files and shared memory to be shared between +32-bit and 64-bit applications. +This is achieved by changing the type of +.I ut_session +to +.IR int32_t , +and that of +.I ut_tv +to a struct with two +.I int32_t +fields +.I tv_sec +and +.IR tv_usec . +Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP, +then instead of the call: +.PP +.in +4n +.EX +gettimeofday((struct timeval *) &ut.ut_tv, NULL); +.EE +.in +.PP +the following method of setting this field is recommended: +.PP +.in +4n +.EX +struct utmp ut; +struct timeval tv; + +gettimeofday(&tv, NULL); +ut.ut_tv.tv_sec = tv.tv_sec; +ut.ut_tv.tv_usec = tv.tv_usec; +.EE +.in +.\" .PP +.\" Note that the \fIutmp\fP struct from libc5 has changed in libc6. +.\" Because of this, +.\" binaries using the old libc5 struct will corrupt +.\" .IR /var/run/utmp " and/or " /var/log/wtmp . +.\" .SH BUGS +.\" This man page is based on the libc5 one, things may work differently now. +.SH SEE ALSO +.BR ac (1), +.BR date (1), +.BR init (1), +.BR last (1), +.BR login (1), +.BR logname (1), +.BR lslogins (1), +.BR users (1), +.BR utmpdump (1), +.BR who (1), +.BR getutent (3), +.BR getutmp (3), +.BR login (3), +.BR logout (3), +.BR logwtmp (3), +.BR updwtmp (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man5/utmpx.5 b/man5/utmpx.5 new file mode 100644 index 0000000..1fa9e5a --- /dev/null +++ b/man5/utmpx.5 @@ -0,0 +1 @@ +.so man5/utmp.5 diff --git a/man5/wtmp.5 b/man5/wtmp.5 new file mode 100644 index 0000000..1fa9e5a --- /dev/null +++ b/man5/wtmp.5 @@ -0,0 +1 @@ +.so man5/utmp.5 diff --git a/man6/intro.6 b/man6/intro.6 new file mode 100644 index 0000000..ff15292 --- /dev/null +++ b/man6/intro.6 @@ -0,0 +1,45 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:19:57 1993 by Rik Faith (faith@cs.unc.edu) +.TH INTRO 6 2007-10-23 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- introduction to games +.SH DESCRIPTION +Section 6 of the manual describes the games and funny little programs +available on the system. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/aio.7 b/man7/aio.7 new file mode 100644 index 0000000..c0dfb24 --- /dev/null +++ b/man7/aio.7 @@ -0,0 +1,479 @@ +'\" t +.\" Copyright (c) 2010 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH AIO 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +aio \- POSIX asynchronous I/O overview +.SH DESCRIPTION +The POSIX asynchronous I/O (AIO) interface allows applications +to initiate one or more I/O operations that are performed +asynchronously (i.e., in the background). +The application can elect to be notified of completion of +the I/O operation in a variety of ways: +by delivery of a signal, by instantiation of a thread, +or no notification at all. +.PP +The POSIX AIO interface consists of the following functions: +.TP 16 +.BR aio_read (3) +Enqueue a read request. +This is the asynchronous analog of +.BR read (2). +.TP +.BR aio_write (3) +Enqueue a write request. +This is the asynchronous analog of +.BR write (2). +.TP +.BR aio_fsync (3) +Enqueue a sync request for the I/O operations on a file descriptor. +This is the asynchronous analog of +.BR fsync (2) +and +.BR fdatasync (2). +.TP +.BR aio_error (3) +Obtain the error status of an enqueued I/O request. +.TP +.BR aio_return (3) +Obtain the return status of a completed I/O request. +.TP +.BR aio_suspend (3) +Suspend the caller until one or more of a specified set of +I/O requests completes. +.TP +.BR aio_cancel (3) +Attempt to cancel outstanding I/O requests on a specified +file descriptor. +.TP +.BR lio_listio (3) +Enqueue multiple I/O requests using a single function call. +.PP +The +.I aiocb +("asynchronous I/O control block") structure defines +parameters that control an I/O operation. +An argument of this type is employed with all of the functions listed above. +This structure has the following form: +.PP +.in +4n +.EX +#include + +struct aiocb { + /* The order of these fields is implementation-dependent */ + + int aio_fildes; /* File descriptor */ + off_t aio_offset; /* File offset */ + volatile void *aio_buf; /* Location of buffer */ + size_t aio_nbytes; /* Length of transfer */ + int aio_reqprio; /* Request priority */ + struct sigevent aio_sigevent; /* Notification method */ + int aio_lio_opcode; /* Operation to be performed; + lio_listio() only */ + + /* Various implementation-internal fields not shown */ +}; + +/* Operation codes for \(aqaio_lio_opcode\(aq: */ + +enum { LIO_READ, LIO_WRITE, LIO_NOP }; +.EE +.in +.PP +The fields of this structure are as follows: +.TP 16 +.I aio_fildes +The file descriptor on which the I/O operation is to be performed. +.TP +.I aio_offset +This is the file offset at which the I/O operation is to be performed. +.TP +.I aio_buf +This is the buffer used to transfer data for a read or write operation. +.TP +.I aio_nbytes +This is the size of the buffer pointed to by +.IR aio_buf . +.TP +.I aio_reqprio +This field specifies a value that is subtracted +from the calling thread's real-time priority in order to +determine the priority for execution of this I/O request (see +.BR pthread_setschedparam (3)). +The specified value must be between 0 and the value returned by +.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) . +This field is ignored for file synchronization operations. +.TP +.I aio_sigevent +This field is a structure that specifies how the caller is +to be notified when the asynchronous I/O operation completes. +Possible values for +.IR aio_sigevent.sigev_notify +are +.BR SIGEV_NONE , +.BR SIGEV_SIGNAL , +and +.BR SIGEV_THREAD . +See +.BR sigevent (7) +for further details. +.TP +.I aio_lio_opcode +The type of operation to be performed; used only for +.BR lio_listio (3). +.PP +In addition to the standard functions listed above, +the GNU C library provides the following extension to the POSIX AIO API: +.TP 16 +.BR aio_init (3) +Set parameters for tuning the behavior of the glibc POSIX AIO implementation. +.SH ERRORS +.TP +.B EINVAL +The +.I aio_reqprio +field of the +.I aiocb +structure was less than 0, +or was greater than the limit returned by the call +.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) . +.SH VERSIONS +The POSIX AIO interfaces are provided by glibc since version 2.1. +.SH CONFORMING TO +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +It is a good idea to zero out the control block buffer before use (see +.BR memset (3)). +The control block buffer and the buffer pointed to by +.I aio_buf +must not be changed while the I/O operation is in progress. +These buffers must remain valid until the I/O operation completes. +.PP +Simultaneous asynchronous read or write operations using the same +.I aiocb +structure yield undefined results. +.PP +The current Linux POSIX AIO implementation is provided in user space by glibc. +This has a number of limitations, most notably that maintaining multiple +threads to perform I/O operations is expensive and scales poorly. +Work has been in progress for some time on a kernel +state-machine-based implementation of asynchronous I/O +(see +.BR io_submit (2), +.BR io_setup (2), +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2)), +but this implementation hasn't yet matured to the point where +the POSIX AIO implementation can be completely +reimplemented using the kernel system calls. +.\" http://lse.sourceforge.net/io/aio.html +.\" http://lse.sourceforge.net/io/aionotes.txt +.\" http://lwn.net/Articles/148755/ +.SH EXAMPLE +The program below opens each of the files named in its command-line +arguments and queues a request on the resulting file descriptor using +.BR aio_read (3). +The program then loops, +periodically monitoring each of the I/O operations +that is still in progress using +.BR aio_error (3). +Each of the I/O requests is set up to provide notification by delivery +of a signal. +After all I/O requests have completed, +the program retrieves their status using +.BR aio_return (3). +.PP +The +.B SIGQUIT +signal (generated by typing control-\\) causes the program to request +cancellation of each of the outstanding requests using +.BR aio_cancel (3). +.PP +Here is an example of what we might see when running this program. +In this example, the program queues two requests to standard input, +and these are satisfied by two lines of input containing +"abc" and "x". +.PP +.in +4n +.EX +$ \fB./a.out /dev/stdin /dev/stdin\fP +opened /dev/stdin on descriptor 3 +opened /dev/stdin on descriptor 4 +aio_error(): + for request 0 (descriptor 3): In progress + for request 1 (descriptor 4): In progress +\fBabc\fP +I/O completion signal received +aio_error(): + for request 0 (descriptor 3): I/O succeeded + for request 1 (descriptor 4): In progress +aio_error(): + for request 1 (descriptor 4): In progress +\fBx\fP +I/O completion signal received +aio_error(): + for request 1 (descriptor 4): I/O succeeded +All I/O requests completed +aio_return(): + for request 0 (descriptor 3): 4 + for request 1 (descriptor 4): 2 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +#include + +#define BUF_SIZE 20 /* Size of buffers for read operations */ + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0) + +#define errMsg(msg) do { perror(msg); } while (0) + +struct ioRequest { /* Application\-defined structure for tracking + I/O requests */ + int reqNum; + int status; + struct aiocb *aiocbp; +}; + +static volatile sig_atomic_t gotSIGQUIT = 0; + /* On delivery of SIGQUIT, we attempt to + cancel all outstanding I/O requests */ + +static void /* Handler for SIGQUIT */ +quitHandler(int sig) +{ + gotSIGQUIT = 1; +} + +#define IO_SIGNAL SIGUSR1 /* Signal used to notify I/O completion */ + +static void /* Handler for I/O completion signal */ +aioSigHandler(int sig, siginfo_t *si, void *ucontext) +{ + if (si->si_code == SI_ASYNCIO) { + write(STDOUT_FILENO, "I/O completion signal received\\n", 31); + + /* The corresponding ioRequest structure would be available as + struct ioRequest *ioReq = si\->si_value.sival_ptr; + and the file descriptor would then be available via + ioReq\->aiocbp\->aio_fildes */ + } +} + +int +main(int argc, char *argv[]) +{ + struct ioRequest *ioList; + struct aiocb *aiocbList; + struct sigaction sa; + int s, j; + int numReqs; /* Total number of queued I/O requests */ + int openReqs; /* Number of I/O requests still in progress */ + + if (argc < 2) { + fprintf(stderr, "Usage: %s ...\\n", + argv[0]); + exit(EXIT_FAILURE); + } + + numReqs = argc \- 1; + + /* Allocate our arrays */ + + ioList = calloc(numReqs, sizeof(struct ioRequest)); + if (ioList == NULL) + errExit("calloc"); + + aiocbList = calloc(numReqs, sizeof(struct aiocb)); + if (aiocbList == NULL) + errExit("calloc"); + + /* Establish handlers for SIGQUIT and the I/O completion signal */ + + sa.sa_flags = SA_RESTART; + sigemptyset(&sa.sa_mask); + + sa.sa_handler = quitHandler; + if (sigaction(SIGQUIT, &sa, NULL) == \-1) + errExit("sigaction"); + + sa.sa_flags = SA_RESTART | SA_SIGINFO; + sa.sa_sigaction = aioSigHandler; + if (sigaction(IO_SIGNAL, &sa, NULL) == \-1) + errExit("sigaction"); + + /* Open each file specified on the command line, and queue + a read request on the resulting file descriptor */ + + for (j = 0; j < numReqs; j++) { + ioList[j].reqNum = j; + ioList[j].status = EINPROGRESS; + ioList[j].aiocbp = &aiocbList[j]; + + ioList[j].aiocbp\->aio_fildes = open(argv[j + 1], O_RDONLY); + if (ioList[j].aiocbp\->aio_fildes == \-1) + errExit("open"); + printf("opened %s on descriptor %d\\n", argv[j + 1], + ioList[j].aiocbp\->aio_fildes); + + ioList[j].aiocbp\->aio_buf = malloc(BUF_SIZE); + if (ioList[j].aiocbp\->aio_buf == NULL) + errExit("malloc"); + + ioList[j].aiocbp\->aio_nbytes = BUF_SIZE; + ioList[j].aiocbp\->aio_reqprio = 0; + ioList[j].aiocbp\->aio_offset = 0; + ioList[j].aiocbp\->aio_sigevent.sigev_notify = SIGEV_SIGNAL; + ioList[j].aiocbp\->aio_sigevent.sigev_signo = IO_SIGNAL; + ioList[j].aiocbp\->aio_sigevent.sigev_value.sival_ptr = + &ioList[j]; + + s = aio_read(ioList[j].aiocbp); + if (s == \-1) + errExit("aio_read"); + } + + openReqs = numReqs; + + /* Loop, monitoring status of I/O requests */ + + while (openReqs > 0) { + sleep(3); /* Delay between each monitoring step */ + + if (gotSIGQUIT) { + + /* On receipt of SIGQUIT, attempt to cancel each of the + outstanding I/O requests, and display status returned + from the cancellation requests */ + + printf("got SIGQUIT; canceling I/O requests: \\n"); + + for (j = 0; j < numReqs; j++) { + if (ioList[j].status == EINPROGRESS) { + printf(" Request %d on descriptor %d:", j, + ioList[j].aiocbp\->aio_fildes); + s = aio_cancel(ioList[j].aiocbp\->aio_fildes, + ioList[j].aiocbp); + if (s == AIO_CANCELED) + printf("I/O canceled\\n"); + else if (s == AIO_NOTCANCELED) + printf("I/O not canceled\\n"); + else if (s == AIO_ALLDONE) + printf("I/O all done\\n"); + else + errMsg("aio_cancel"); + } + } + + gotSIGQUIT = 0; + } + + /* Check the status of each I/O request that is still + in progress */ + + printf("aio_error():\\n"); + for (j = 0; j < numReqs; j++) { + if (ioList[j].status == EINPROGRESS) { + printf(" for request %d (descriptor %d): ", + j, ioList[j].aiocbp\->aio_fildes); + ioList[j].status = aio_error(ioList[j].aiocbp); + + switch (ioList[j].status) { + case 0: + printf("I/O succeeded\\n"); + break; + case EINPROGRESS: + printf("In progress\\n"); + break; + case ECANCELED: + printf("Canceled\\n"); + break; + default: + errMsg("aio_error"); + break; + } + + if (ioList[j].status != EINPROGRESS) + openReqs\-\-; + } + } + } + + printf("All I/O requests completed\\n"); + + /* Check status return of all I/O requests */ + + printf("aio_return():\\n"); + for (j = 0; j < numReqs; j++) { + ssize_t s; + + s = aio_return(ioList[j].aiocbp); + printf(" for request %d (descriptor %d): %zd\\n", + j, ioList[j].aiocbp\->aio_fildes, s); + } + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR io_submit (2), +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_init (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_write (3), +.BR lio_listio (3) +.PP +"Asynchronous I/O Support in Linux 2.5", +Bhattacharya, Pratt, Pulavarty, and Morgan, +Proceedings of the Linux Symposium, 2003, +.UR https://www.kernel.org/doc/ols/2003/ols2003\-pages\-351\-366.pdf +.UE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/armscii-8.7 b/man7/armscii-8.7 new file mode 100644 index 0000000..1e5b814 --- /dev/null +++ b/man7/armscii-8.7 @@ -0,0 +1,148 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ARMSCII-8 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +armscii-8 \- Armenian character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The Armenian Standard Code for Information Interchange, +8-bit coded character set. +.SS ArmSCII-8 characters +The following table displays the characters in ArmSCII-8 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +242 162 A2 և ARMENIAN SMALL LIGATURE ECH YIWN +243 163 A3 ։ ARMENIAN FULL STOP +244 164 A4 ) RIGHT PARENTHESIS +245 165 A5 ( LEFT PARENTHESIS +246 166 A6 » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +247 167 A7 « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +250 168 A8 — EM DASH +251 169 A9 . FULL STOP +252 170 AA ՝ ARMENIAN COMMA +253 171 AB , COMMA +254 172 AC - HYPHEN-MINUS +255 173 AD ֊ ARMENIAN HYPHEN +256 174 AE … HORIZONTAL ELLIPSIS +257 175 AF ՜ ARMENIAN EXCLAMATION MARK +260 176 B0 ՛ ARMENIAN EMPHASIS MARK +261 177 B1 ՞ ARMENIAN QUESTION MARK +262 178 B2 Ա ARMENIAN CAPITAL LETTER AYB +263 179 B3 ա ARMENIAN SMALL LETTER AYB +264 180 B4 Բ ARMENIAN CAPITAL LETTER BEN +265 181 B5 բ ARMENIAN SMALL LETTER BEN +266 182 B6 Գ ARMENIAN CAPITAL LETTER GIM +267 183 B7 գ ARMENIAN SMALL LETTER GIM +270 184 B8 Դ ARMENIAN CAPITAL LETTER DA +271 185 B9 դ ARMENIAN SMALL LETTER DA +272 186 BA Ե ARMENIAN CAPITAL LETTER ECH +273 187 BB ե ARMENIAN SMALL LETTER ECH +274 188 BC Զ ARMENIAN CAPITAL LETTER ZA +275 189 BD զ ARMENIAN SMALL LETTER ZA +276 190 BE Է ARMENIAN CAPITAL LETTER EH +277 191 BF է ARMENIAN SMALL LETTER EH +300 192 C0 Ը ARMENIAN CAPITAL LETTER ET +301 193 C1 ը ARMENIAN SMALL LETTER ET +302 194 C2 Թ ARMENIAN CAPITAL LETTER TO +303 195 C3 թ ARMENIAN SMALL LETTER TO +304 196 C4 Ժ ARMENIAN CAPITAL LETTER ZHE +305 197 C5 ժ ARMENIAN SMALL LETTER ZHE +306 198 C6 Ի ARMENIAN CAPITAL LETTER INI +307 199 C7 ի ARMENIAN SMALL LETTER INI +310 200 C8 Լ ARMENIAN CAPITAL LETTER LIWN +311 201 C9 լ ARMENIAN SMALL LETTER LIWN +312 202 CA Խ ARMENIAN CAPITAL LETTER XEH +313 203 CB խ ARMENIAN SMALL LETTER XEH +314 204 CC Ծ ARMENIAN CAPITAL LETTER CA +315 205 CD ծ ARMENIAN SMALL LETTER CA +316 206 CE Կ ARMENIAN CAPITAL LETTER KEN +317 207 CF կ ARMENIAN SMALL LETTER KEN +320 208 D0 Հ ARMENIAN CAPITAL LETTER HO +321 209 D1 հ ARMENIAN SMALL LETTER HO +322 210 D2 Ձ ARMENIAN CAPITAL LETTER JA +323 211 D3 ձ ARMENIAN SMALL LETTER JA +324 212 D4 Ղ ARMENIAN CAPITAL LETTER GHAD +325 213 D5 ղ ARMENIAN SMALL LETTER GHAD +326 214 D6 Ճ ARMENIAN CAPITAL LETTER CHEH +327 215 D7 ճ ARMENIAN SMALL LETTER CHEH +330 216 D8 Մ ARMENIAN CAPITAL LETTER MEN +331 217 D9 մ ARMENIAN SMALL LETTER MEN +332 218 DA Յ ARMENIAN CAPITAL LETTER YI +333 219 DB յ ARMENIAN SMALL LETTER YI +334 220 DC Ն ARMENIAN CAPITAL LETTER NOW +335 221 DD ն ARMENIAN SMALL LETTER NOW +336 222 DE Շ ARMENIAN CAPITAL LETTER SHA +337 223 DF շ ARMENIAN SMALL LETTER SHA +340 224 E0 Ո ARMENIAN CAPITAL LETTER VO +341 225 E1 ո ARMENIAN SMALL LETTER VO +342 226 E2 Չ ARMENIAN CAPITAL LETTER CHA +343 227 E3 չ ARMENIAN SMALL LETTER CHA +344 228 E4 Պ ARMENIAN CAPITAL LETTER PEH +345 229 E5 պ ARMENIAN SMALL LETTER PEH +346 230 E6 Ջ ARMENIAN CAPITAL LETTER JHEH +347 231 E7 ջ ARMENIAN SMALL LETTER JHEH +350 232 E8 Ռ ARMENIAN CAPITAL LETTER RA +351 233 E9 ռ ARMENIAN SMALL LETTER RA +352 234 EA Ս ARMENIAN CAPITAL LETTER SEH +353 235 EB ս ARMENIAN SMALL LETTER SEH +354 236 EC Վ ARMENIAN CAPITAL LETTER VEW +355 237 ED վ ARMENIAN SMALL LETTER VEW +356 238 EE Տ ARMENIAN CAPITAL LETTER TIWN +357 239 EF տ ARMENIAN SMALL LETTER TIWN +360 240 F0 Ր ARMENIAN CAPITAL LETTER REH +361 241 F1 ր ARMENIAN SMALL LETTER REH +362 242 F2 Ց ARMENIAN CAPITAL LETTER CO +363 243 F3 ց ARMENIAN SMALL LETTER CO +364 244 F4 Ւ ARMENIAN CAPITAL LETTER YIWN +365 245 F5 ւ ARMENIAN SMALL LETTER YIWN +366 246 F6 Փ ARMENIAN CAPITAL LETTER PIWR +367 247 F7 փ ARMENIAN SMALL LETTER PIWR +370 248 F8 Ք ARMENIAN CAPITAL LETTER KEH +371 249 F9 ք ARMENIAN SMALL LETTER KEH +372 250 FA Օ ARMENIAN CAPITAL LETTER OH +373 251 FB օ ARMENIAN SMALL LETTER OH +374 252 FC Ֆ ARMENIAN CAPITAL LETTER FEH +375 253 FD ֆ ARMENIAN SMALL LETTER FEH +376 254 FE ՚ ARMENIAN APOSTROPHE +.TE +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/arp.7 b/man7/arp.7 new file mode 100644 index 0000000..c1bc432 --- /dev/null +++ b/man7/arp.7 @@ -0,0 +1,319 @@ +'\" t +.\" This man page is Copyright (C) 1999 Matthew Wilcox . +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" Modified June 1999 Andi Kleen +.\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ +.\" +.TH ARP 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +arp \- Linux ARP kernel module. +.SH DESCRIPTION +This kernel protocol module implements the Address Resolution +Protocol defined in RFC\ 826. +It is used to convert between Layer2 hardware addresses +and IPv4 protocol addresses on directly connected networks. +The user normally doesn't interact directly with this module except to +configure it; +instead it provides a service for other protocols in the kernel. +.PP +A user process can receive ARP packets by using +.BR packet (7) +sockets. +There is also a mechanism for managing the ARP cache +in user-space by using +.BR netlink (7) +sockets. +The ARP table can also be controlled via +.BR ioctl (2) +on any +.B AF_INET +socket. +.PP +The ARP module maintains a cache of mappings between hardware addresses +and protocol addresses. +The cache has a limited size so old and less +frequently used entries are garbage-collected. +Entries which are marked +as permanent are never deleted by the garbage-collector. +The cache can +be directly manipulated by the use of ioctls and its behavior can be +tuned by the +.I /proc +interfaces described below. +.PP +When there is no positive feedback for an existing mapping after some +time (see the +.I /proc +interfaces below), a neighbor cache entry is considered stale. +Positive feedback can be gotten from a higher layer; for example from +a successful TCP ACK. +Other protocols can signal forward progress +using the +.B MSG_CONFIRM +flag to +.BR sendmsg (2). +When there is no forward progress, ARP tries to reprobe. +It first tries to ask a local arp daemon +.B app_solicit +times for an updated MAC address. +If that fails and an old MAC address is known, a unicast probe is sent +.B ucast_solicit +times. +If that fails too, it will broadcast a new ARP +request to the network. +Requests are sent only when there is data queued +for sending. +.PP +Linux will automatically add a nonpermanent proxy arp entry when it +receives a request for an address it forwards to and proxy arp is +enabled on the receiving interface. +When there is a reject route for the target, no proxy arp entry is added. +.SS Ioctls +Three ioctls are available on all +.B AF_INET +sockets. +They take a pointer to a +.I struct arpreq +as their argument. +.PP +.in +4n +.EX +struct arpreq { + struct sockaddr arp_pa; /* protocol address */ + struct sockaddr arp_ha; /* hardware address */ + int arp_flags; /* flags */ + struct sockaddr arp_netmask; /* netmask of protocol address */ + char arp_dev[16]; +}; +.EE +.in +.PP +.BR SIOCSARP ", " SIOCDARP " and " SIOCGARP +respectively set, delete and get an ARP mapping. +Setting and deleting ARP maps are privileged operations and may +be performed only by a process with the +.B CAP_NET_ADMIN +capability or an effective UID of 0. +.PP +.I arp_pa +must be an +.B AF_INET +address and +.I arp_ha +must have the same type as the device which is specified in +.IR arp_dev . +.I arp_dev +is a zero-terminated string which names a device. +.RS +.TS +tab(:) allbox; +c s +l l. +\fIarp_flags\fR +flag:meaning +ATF_COM:Lookup complete +ATF_PERM:Permanent entry +ATF_PUBL:Publish entry +ATF_USETRAILERS:Trailers requested +ATF_NETMASK:Use a netmask +ATF_DONTPUB:Don't answer +.TE +.RE +.PP +If the +.B ATF_NETMASK +flag is set, then +.I arp_netmask +should be valid. +Linux 2.2 does not support proxy network ARP entries, so this +should be set to 0xffffffff, or 0 to remove an existing proxy arp entry. +.B ATF_USETRAILERS +is obsolete and should not be used. +.SS /proc interfaces +ARP supports a range of +.I /proc +interfaces to configure parameters on a global or per-interface basis. +The interfaces can be accessed by reading or writing the +.I /proc/sys/net/ipv4/neigh/*/* +files. +Each interface in the system has its own directory in +.IR /proc/sys/net/ipv4/neigh/ . +The setting in the "default" directory is used for all newly created +devices. +Unless otherwise specified, time-related interfaces are specified +in seconds. +.TP +.IR anycast_delay " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of jiffies to delay before replying to a +IPv6 neighbor solicitation message. +Anycast support is not yet implemented. +Defaults to 1 second. +.TP +.IR app_solicit " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of probes to send to the user space ARP daemon via +netlink before dropping back to multicast probes (see +.IR mcast_solicit ). +Defaults to 0. +.TP +.IR base_reachable_time " (since Linux 2.2)" +.\" Precisely: 2.1.79 +Once a neighbor has been found, the entry is considered to be valid +for at least a random value between +.IR base_reachable_time "/2 and 3*" base_reachable_time /2. +An entry's validity will be extended if it receives positive feedback +from higher level protocols. +Defaults to 30 seconds. +This file is now obsolete in favor of +.IR base_reachable_time_ms . +.TP +.IR base_reachable_time_ms " (since Linux 2.6.12)" +As for +.IR base_reachable_time , +but measures time in milliseconds. +Defaults to 30000 milliseconds. +.TP +.IR delay_first_probe_time " (since Linux 2.2)" +.\" Precisely: 2.1.79 +Delay before first probe after it has been decided that a neighbor +is stale. +Defaults to 5 seconds. +.TP +.IR gc_interval " (since Linux 2.2)" +.\" Precisely: 2.1.79 +How frequently the garbage collector for neighbor entries +should attempt to run. +Defaults to 30 seconds. +.TP +.IR gc_stale_time " (since Linux 2.2)" +.\" Precisely: 2.1.79 +Determines how often to check for stale neighbor entries. +When a neighbor entry is considered stale, it is resolved again before +sending data to it. +Defaults to 60 seconds. +.TP +.IR gc_thresh1 " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The minimum number of entries to keep in the ARP cache. +The garbage collector will not run if there are fewer than +this number of entries in the cache. +Defaults to 128. +.TP +.IR gc_thresh2 " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The soft maximum number of entries to keep in the ARP cache. +The garbage collector will allow the number of entries to exceed +this for 5 seconds before collection will be performed. +Defaults to 512. +.TP +.IR gc_thresh3 " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The hard maximum number of entries to keep in the ARP cache. +The garbage collector will always run if there are more than +this number of entries in the cache. +Defaults to 1024. +.TP +.IR locktime " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The minimum number of jiffies to keep an ARP entry in the cache. +This prevents ARP cache thrashing if there is more than one potential +mapping (generally due to network misconfiguration). +Defaults to 1 second. +.TP +.IR mcast_solicit " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of attempts to resolve an address by +multicast/broadcast before marking the entry as unreachable. +Defaults to 3. +.TP +.IR proxy_delay " (since Linux 2.2)" +.\" Precisely: 2.1.79 +When an ARP request for a known proxy-ARP address is received, delay up to +.I proxy_delay +jiffies before replying. +This is used to prevent network flooding in some cases. +Defaults to 0.8 seconds. +.TP +.IR proxy_qlen " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of packets which may be queued to proxy-ARP addresses. +Defaults to 64. +.TP +.IR retrans_time " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The number of jiffies to delay before retransmitting a request. +Defaults to 1 second. +This file is now obsolete in favor of +.IR retrans_time_ms . +.TP +.IR retrans_time_ms " (since Linux 2.6.12)" +The number of milliseconds to delay before retransmitting a request. +Defaults to 1000 milliseconds. +.TP +.IR ucast_solicit " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of attempts to send unicast probes before asking +the ARP daemon (see +.IR app_solicit ). +Defaults to 3. +.TP +.IR unres_qlen " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of packets which may be queued for each unresolved +address by other network layers. +Defaults to 3. +.SH VERSIONS +The +.I struct arpreq +changed in Linux 2.0 to include the +.I arp_dev +member and the ioctl numbers changed at the same time. +Support for the old ioctls was dropped in Linux 2.2. +.PP +Support for proxy arp entries for networks (netmask not equal 0xffffffff) +was dropped in Linux 2.2. +It is replaced by automatic proxy arp setup by +the kernel for all reachable hosts on other interfaces (when +forwarding and proxy arp is enabled for the interface). +.PP +The +.I neigh/* +interfaces did not exist before Linux 2.2. +.SH BUGS +Some timer settings are specified in jiffies, which is architecture- +and kernel version-dependent; see +.BR time (7). +.PP +There is no way to signal positive feedback from user space. +This means connection-oriented protocols implemented in user space +will generate excessive ARP traffic, because ndisc will regularly +reprobe the MAC address. +The same problem applies for some kernel protocols (e.g., NFS over UDP). +.PP +This man page mashes together functionality that is IPv4-specific +with functionality that is shared between IPv4 and IPv6. +.SH SEE ALSO +.BR capabilities (7), +.BR ip (7), +.BR arpd (8) +.PP +RFC\ 826 for a description of ARP. +RFC\ 2461 for a description of IPv6 neighbor discovery and the base +algorithms used. +Linux 2.2+ IPv4 ARP uses the IPv6 algorithms when applicable. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/ascii.7 b/man7/ascii.7 new file mode 100644 index 0000000..01d49a3 --- /dev/null +++ b/man7/ascii.7 @@ -0,0 +1,211 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Created 1993-04-02 by Michael Haardt (michael@moria.de) +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-05-15 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1994-11-22 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1995-07-11 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1996-12-18 by Michael Haardt and aeb +.\" Modified 1999-05-31 by Dimitri Papadopoulos (dpo@club-internet.fr) +.\" Modified 1999-08-08 by Michael Haardt (michael@moria.de) +.\" Modified 2004-04-01 by aeb +.\" +.TH ASCII 7 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +ascii \- ASCII character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +ASCII is the American Standard Code for Information Interchange. +It is a 7-bit code. +Many 8-bit codes (e.g., ISO 8859-1) contain ASCII as their lower half. +The international counterpart of ASCII is known as ISO 646-IRV. +.PP +The following table contains the 128 ASCII characters. +.PP +C program \f(CW\(aq\eX\(aq\fP escapes are noted. +.if t \{\ +.ft CW +\} +.TS +l l l l l l l l. +Oct Dec Hex Char Oct Dec Hex Char +_ +000 0 00 NUL \(aq\e0\(aq (null character) 100 64 40 @ +001 1 01 SOH (start of heading) 101 65 41 A +002 2 02 STX (start of text) 102 66 42 B +003 3 03 ETX (end of text) 103 67 43 C +004 4 04 EOT (end of transmission) 104 68 44 D +005 5 05 ENQ (enquiry) 105 69 45 E +006 6 06 ACK (acknowledge) 106 70 46 F +007 7 07 BEL \(aq\ea\(aq (bell) 107 71 47 G +010 8 08 BS \(aq\eb\(aq (backspace) 110 72 48 H +011 9 09 HT \(aq\et\(aq (horizontal tab) 111 73 49 I +012 10 0A LF \(aq\en\(aq (new line) 112 74 4A J +013 11 0B VT \(aq\ev\(aq (vertical tab) 113 75 4B K +014 12 0C FF \(aq\ef\(aq (form feed) 114 76 4C L +015 13 0D CR \(aq\er\(aq (carriage ret) 115 77 4D M +016 14 0E SO (shift out) 116 78 4E N +017 15 0F SI (shift in) 117 79 4F O +020 16 10 DLE (data link escape) 120 80 50 P +021 17 11 DC1 (device control 1) 121 81 51 Q +022 18 12 DC2 (device control 2) 122 82 52 R +023 19 13 DC3 (device control 3) 123 83 53 S +024 20 14 DC4 (device control 4) 124 84 54 T +025 21 15 NAK (negative ack.) 125 85 55 U +026 22 16 SYN (synchronous idle) 126 86 56 V +027 23 17 ETB (end of trans. blk) 127 87 57 W +030 24 18 CAN (cancel) 130 88 58 X +031 25 19 EM (end of medium) 131 89 59 Y +032 26 1A SUB (substitute) 132 90 5A Z +033 27 1B ESC (escape) 133 91 5B [ +034 28 1C FS (file separator) 134 92 5C \e \(aq\e\e\(aq +035 29 1D GS (group separator) 135 93 5D ] +036 30 1E RS (record separator) 136 94 5E ^ +037 31 1F US (unit separator) 137 95 5F \&_ +040 32 20 SPACE 140 96 60 \` +041 33 21 ! 141 97 61 a +042 34 22 " 142 98 62 b +043 35 23 # 143 99 63 c +044 36 24 $ 144 100 64 d +045 37 25 % 145 101 65 e +046 38 26 & 146 102 66 f +047 39 27 \(aq 147 103 67 g +050 40 28 ( 150 104 68 h +051 41 29 ) 151 105 69 i +052 42 2A * 152 106 6A j +053 43 2B + 153 107 6B k +054 44 2C , 154 108 6C l +055 45 2D \- 155 109 6D m +056 46 2E . 156 110 6E n +057 47 2F / 157 111 6F o +060 48 30 0 160 112 70 p +061 49 31 1 161 113 71 q +062 50 32 2 162 114 72 r +063 51 33 3 163 115 73 s +064 52 34 4 164 116 74 t +065 53 35 5 165 117 75 u +066 54 36 6 166 118 76 v +067 55 37 7 167 119 77 w +070 56 38 8 170 120 78 x +071 57 39 9 171 121 79 y +072 58 3A : 172 122 7A z +073 59 3B ; 173 123 7B { +074 60 3C < 174 124 7C | +075 61 3D = 175 125 7D } +076 62 3E > 176 126 7E ~ +077 63 3F ? 177 127 7F DEL +.TE +.if t \{\ +.in +.ft P +\} +.SS Tables +For convenience, below are more compact tables in hex and decimal. +.PP +.nf +.if t \{\ +.in 1i +.ft CW +\} + 2 3 4 5 6 7 30 40 50 60 70 80 90 100 110 120 + ------------- --------------------------------- +0: 0 @ P \` p 0: ( 2 < F P Z d n x +1: ! 1 A Q a q 1: ) 3 = G Q [ e o y +2: " 2 B R b r 2: * 4 > H R \e f p z +3: # 3 C S c s 3: ! + 5 ? I S ] g q { +4: $ 4 D T d t 4: " , 6 @ J T ^ h r | +5: % 5 E U e u 5: # \- 7 A K U _ i s } +6: & 6 F V f v 6: $ . 8 B L V \` j t ~ +7: \(aq 7 G W g w 7: % / 9 C M W a k u DEL +8: ( 8 H X h x 8: & 0 : D N X b l v +9: ) 9 I Y i y 9: \(aq 1 ; E O Y c m w +A: * : J Z j z +B: + ; K [ k { +C: , < L \e l | +D: \- = M ] m } +E: . > N ^ n ~ +F: / ? O _ o DEL +.if t \{\ +.in +.ft P +\} +.fi +.SH NOTES +.SS History +An +.B ascii +manual page appeared in Version 7 of AT&T UNIX. +.PP +On older terminals, the underscore code is displayed as a left arrow, +called backarrow, the caret is displayed as an up-arrow and the vertical +bar has a hole in the middle. +.PP +Uppercase and lowercase characters differ by just one bit and the +ASCII character 2 differs from the double quote by just one bit, too. +That made it much easier to encode characters mechanically or with a +non-microcontroller-based electronic keyboard and that pairing was found +on old teletypes. +.PP +The ASCII standard was published by the United States of America +Standards Institute (USASI) in 1968. +.\" +.\" ASA was the American Standards Association and X3 was an ASA sectional +.\" committee on computers and data processing. Its name changed to +.\" American National Standards Committee X3 (ANSC-X3) and now it is known +.\" as Accredited Standards Committee X3 (ASC X3). It is accredited by ANSI +.\" and administered by ITI. The subcommittee X3.2 worked on coded +.\" character sets; the task group working on ASCII appears to have been +.\" designated X3.2.4. In 1966, ASA became the United States of America +.\" Standards Institute (USASI) and published ASCII in 1968. It became the +.\" American National Standards Institute (ANSI) in 1969 and is the +.\" U.S. member body of ISO; private and nonprofit. +.\" +.SH SEE ALSO +.BR charsets (7), +.BR iso_8859-1 (7), +.BR iso_8859-10 (7), +.BR iso_8859-11 (7), +.BR iso_8859-13 (7), +.BR iso_8859-14 (7), +.BR iso_8859-15 (7), +.BR iso_8859-16 (7), +.BR iso_8859-2 (7), +.BR iso_8859-3 (7), +.BR iso_8859-4 (7), +.BR iso_8859-5 (7), +.BR iso_8859-6 (7), +.BR iso_8859-7 (7), +.BR iso_8859-8 (7), +.BR iso_8859-9 (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/attributes.7 b/man7/attributes.7 new file mode 100644 index 0000000..3cf95a3 --- /dev/null +++ b/man7/attributes.7 @@ -0,0 +1,892 @@ +.\" Copyright (c) 2014, Red Hat, Inc +.\" Written by Alexandre Oliva +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH ATTRIBUTES 7 2015-03-02 "Linux" "Linux Programmer's Manual" +.SH NAME +attributes \- POSIX safety concepts +.SH DESCRIPTION +.\" +.\" +.IR Note : +the text of this man page is based on the material taken from +the "POSIX Safety Concepts" section of the GNU C Library manual. +Further details on the topics described here can be found in that +manual. +.PP +Various function manual pages include a section ATTRIBUTES +that describes the safety of calling the function in various contexts. +This section annotates functions with the following safety markings: +.TP +.I MT-Safe +.I MT-Safe +or +Thread-Safe functions are safe to call in the presence +of other threads. +MT, in MT-Safe, stands for Multi Thread. +.IP +Being MT-Safe does not imply a function is atomic, nor that it uses any +of the memory synchronization mechanisms POSIX exposes to users. +It is even possible that calling MT-Safe functions in sequence +does not yield an MT-Safe combination. +For example, having a thread call two MT-Safe +functions one right after the other does not guarantee behavior +equivalent to atomic execution of a combination of both functions, +since concurrent calls in other threads may interfere in a destructive way. +.IP +Whole-program optimizations that could inline functions across library +interfaces may expose unsafe reordering, and so performing inlining +across the GNU C Library interface is not recommended. +The documented +MT-Safety status is not guaranteed under whole-program optimization. +However, functions defined in user-visible headers are designed to be +safe for inlining. +.\" .TP +.\" .I AS-Safe +.\" .I AS-Safe +.\" or Async-Signal-Safe functions are safe to call from +.\" asynchronous signal handlers. +.\" AS, in AS-Safe, stands for Asynchronous Signal. +.\" +.\" Many functions that are AS-Safe may set +.\" .IR errno , +.\" or modify the floating-point environment, +.\" because their doing so does not make them +.\" unsuitable for use in signal handlers. +.\" However, programs could misbehave should asynchronous signal handlers +.\" modify this thread-local state, +.\" and the signal handling machinery cannot be counted on to +.\" preserve it. +.\" Therefore, signal handlers that call functions that may set +.\" .I errno +.\" or modify the floating-point environment +.\" .I must +.\" save their original values, and restore them before returning. +.\" .TP +.\" .I AC-Safe +.\" .I AC-Safe +.\" or Async-Cancel-Safe functions are safe to call when +.\" asynchronous cancellation is enabled. +.\" AC in AC-Safe stands for Asynchronous Cancellation. +.\" +.\" The POSIX standard defines only three functions to be AC-Safe, namely +.\" .BR pthread_cancel (3), +.\" .BR pthread_setcancelstate (3), +.\" and +.\" .BR pthread_setcanceltype (3). +.\" At present the GNU C Library provides no +.\" guarantees beyond these three functions, +.\" but does document which functions are presently AC-Safe. +.\" This documentation is provided for use +.\" by the GNU C Library developers. +.\" +.\" Just like signal handlers, cancellation cleanup routines must configure +.\" the floating point environment they require. +.\" The routines cannot assume a floating point environment, +.\" particularly when asynchronous cancellation is enabled. +.\" If the configuration of the floating point +.\" environment cannot be performed atomically then it is also possible that +.\" the environment encountered is internally inconsistent. +.TP +.IR MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe +.IR MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe +functions are not safe to call in a multithreaded programs. +.\" functions are not +.\" safe to call within the safety contexts described above. +.\" Calling them +.\" within such contexts invokes undefined behavior. +.\" +.\" Functions not explicitly documented as safe in a safety context should +.\" be regarded as Unsafe. +.\" .TP +.\" .I Preliminary +.\" .I Preliminary +.\" safety properties are documented, indicating these +.\" properties may +.\" .I not +.\" be counted on in future releases of +.\" the GNU C Library. +.\" +.\" Such preliminary properties are the result of an assessment of the +.\" properties of our current implementation, +.\" rather than of what is mandated and permitted +.\" by current and future standards. +.\" +.\" Although we strive to abide by the standards, in some cases our +.\" implementation is safe even when the standard does not demand safety, +.\" and in other cases our implementation does not meet the standard safety +.\" requirements. +.\" The latter are most likely bugs; the former, when marked +.\" as +.\" .IR Preliminary , +.\" should not be counted on: future standards may +.\" require changes that are not compatible with the additional safety +.\" properties afforded by the current implementation. +.\" +.\" Furthermore, +.\" the POSIX standard does not offer a detailed definition of safety. +.\" We assume that, by "safe to call", POSIX means that, +.\" as long as the program does not invoke undefined behavior, +.\" the "safe to call" function behaves as specified, +.\" and does not cause other functions to deviate from their specified behavior. +.\" We have chosen to use its loose +.\" definitions of safety, not because they are the best definitions to use, +.\" but because choosing them harmonizes this manual with POSIX. +.\" +.\" Please keep in mind that these are preliminary definitions and annotations, +.\" and certain aspects of the definitions are still under +.\" discussion and might be subject to clarification or change. +.\" +.\" Over time, +.\" we envision evolving the preliminary safety notes into stable commitments, +.\" as stable as those of our interfaces. +.\" As we do, we will remove the +.\" .I Preliminary +.\" keyword from safety notes. +.\" As long as the keyword remains, however, +.\" they are not to be regarded as a promise of future behavior. +.PP +Other keywords that appear in safety notes are defined in subsequent sections. +.\" +.\" +.\" .SS Unsafe features +.\" Functions that are unsafe to call in certain contexts are annotated with +.\" keywords that document their features that make them unsafe to call. +.\" AS-Unsafe features in this section indicate the functions are never safe +.\" to call when asynchronous signals are enabled. +.\" AC-Unsafe features +.\" indicate they are never safe to call when asynchronous cancellation is +.\" .\" enabled. +.\" There are no MT-Unsafe marks in this section. +.\" .TP +.\" .\" .I code +.\" Functions marked with +.\" .I lock +.\" as an AS-Unsafe feature may be +.\" .\" interrupted by a signal while holding a non-recursive lock. +.\" If the signal handler calls another such function that takes the same lock, +.\" the result is a deadlock. +.\" +.\" Functions annotated with +.\" .I lock +.\" as an AC-Unsafe feature may, if canceled asynchronously, +.\" fail to release a lock that would have been released if their execution +.\" had not been interrupted by asynchronous thread cancellation. +.\" Once a lock is left taken, +.\" attempts to take that lock will block indefinitely. +.\" .TP +.\" .I corrupt +.\" Functions marked with +.\" .\" .I corrupt +.\" as an AS-Unsafe feature may corrupt +.\" data structures and misbehave when they interrupt, +.\" or are interrupted by, another such function. +.\" Unlike functions marked with +.\" .IR lock , +.\" these take recursive locks to avoid MT-Safety problems, +.\" but this is not enough to stop a signal handler from observing +.\" a partially-updated data structure. +.\" Further corruption may arise from the interrupted function's +.\" failure to notice updates made by signal handlers. +.\" +.\" Functions marked with +.\" .I corrupt +.\" as an AC-Unsafe feature may leave +.\" data structures in a corrupt, partially updated state. +.\" Subsequent uses of the data structure may misbehave. +.\" +.\" .\" A special case, probably not worth documenting separately, involves +.\" .\" reallocing, or even freeing pointers. Any case involving free could +.\" .\" be easily turned into an ac-safe leak by resetting the pointer before +.\" .\" releasing it; I don't think we have any case that calls for this sort +.\" .\" of fixing. Fixing the realloc cases would require a new interface: +.\" .\" instead of @code{ptr=realloc(ptr,size)} we'd have to introduce +.\" .\" @code{acsafe_realloc(&ptr,size)} that would modify ptr before +.\" .\" releasing the old memory. The ac-unsafe realloc could be implemented +.\" .\" in terms of an internal interface with this semantics (say +.\" .\" __acsafe_realloc), but since realloc can be overridden, the function +.\" .\" we call to implement realloc should not be this internal interface, +.\" .\" but another internal interface that calls __acsafe_realloc if realloc +.\" .\" was not overridden, and calls the overridden realloc with async +.\" .\" cancel disabled. --lxoliva +.\" .TP +.\" .I heap +.\" Functions marked with +.\" .I heap +.\" may call heap memory management functions from the +.\" .BR malloc (3)/ free (3) +.\" family of functions and are only as safe as those functions. +.\" This note is thus equivalent to: +.\" +.\" | AS-Unsafe lock | AC-Unsafe lock fd mem | +.\" .\" @sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +.\" .\" +.\" .\" Check for cases that should have used plugin instead of or in +.\" .\" addition to this. Then, after rechecking gettext, adjust i18n if +.\" .\" needed. +.\" .TP +.\" .I dlopen +.\" Functions marked with +.\" .I dlopen +.\" use the dynamic loader to load +.\" shared libraries into the current execution image. +.\" This involves opening files, mapping them into memory, +.\" allocating additional memory, resolving symbols, +.\" applying relocations and more, +.\" all of this while holding internal dynamic loader locks. +.\" +.\" The locks are enough for these functions to be AS-Unsafe and AC-Unsafe, +.\" but other issues may arise. +.\" At present this is a placeholder for all +.\" potential safety issues raised by +.\" .BR dlopen (3). +.\" +.\" .\" dlopen runs init and fini sections of the module; does this mean +.\" .\" dlopen always implies plugin? +.\" .TP +.\" .I plugin +.\" Functions annotated with +.\" .I plugin +.\" may run code from plugins that +.\" may be external to the GNU C Library. +.\" Such plugin functions are assumed to be +.\" MT-Safe, AS-Unsafe and AC-Unsafe. +.\" Examples of such plugins are stack unwinding libraries, +.\" name service switch (NSS) and character set conversion (iconv) back-ends. +.\" +.\" Although the plugins mentioned as examples are all brought in by means +.\" of dlopen, the +.\" .I plugin +.\" keyword does not imply any direct +.\" involvement of the dynamic loader or the +.\" .I libdl +.\" interfaces, +.\" those are covered by +.\" .IR dlopen . +.\" For example, if one function loads a module and finds the addresses +.\" of some of its functions, +.\" while another just calls those already-resolved functions, +.\" the former will be marked with +.\" .IR dlopen , +.\" whereas the latter will get the +.\" .IR plugin . +.\" When a single function takes all of these actions, then it gets both marks. +.\" .TP +.\" .I i18n +.\" Functions marked with +.\" .I i18n +.\" may call internationalization +.\" functions of the +.\" .BR gettext (3) +.\" family and will be only as safe as those +.\" functions. +.\" This note is thus equivalent to: +.\" +.\" | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt | +.\" +.\" .\" @sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}} +.\" .TP +.\" .I timer +.\" Functions marked with +.\" .I timer +.\" use the +.\" .BR alarm (3) +.\" function or +.\" similar to set a time-out for a system call or a long-running operation. +.\" In a multi-threaded program, there is a risk that the time-out signal +.\" will be delivered to a different thread, +.\" thus failing to interrupt the intended thread. +.\" Besides being MT-Unsafe, such functions are always +.\" AS-Unsafe, because calling them in signal handlers may interfere with +.\" timers set in the interrupted code, and AC-Unsafe, +.\" because there is no safe way to guarantee an earlier timer +.\" will be reset in case of asynchronous cancellation. +.\" +.\" +.SS Conditionally safe features +For some features that make functions unsafe to call in certain contexts, +there are known ways to avoid the safety problem other than +refraining from calling the function altogether. +The keywords that follow refer to such features, +and each of their definitions indicates +how the whole program needs to be constrained in order to remove the +safety problem indicated by the keyword. +Only when all the reasons that +make a function unsafe are observed and addressed, +by applying the documented constraints, +does the function become safe to call in a context. +.TP +.I init +Functions marked with +.I init +as an MT-Unsafe feature perform +MT-Unsafe initialization when they are first called. +.IP +Calling such a function at least once in single-threaded mode removes +this specific cause for the function to be regarded as MT-Unsafe. +If no other cause for that remains, +the function can then be safely called after other threads are started. +.\" +.\" Functions marked with +.\" .I init +.\" as an AS-Unsafe or AC-Unsafe feature use the GNU C Library internal +.\" .I libc_once +.\" machinery or similar to initialize internal data structures. +.\" +.\" If a signal handler interrupts such an initializer, +.\" and calls any function that also performs +.\" .I libc_once +.\" initialization, it will deadlock if the thread library has been loaded. +.\" +.\" Furthermore, if an initializer is partially complete before it is canceled +.\" or interrupted by a signal whose handler requires the same initialization, +.\" some or all of the initialization may be performed more than once, +.\" leaking resources or even resulting in corrupt internal data. +.\" +.\" Applications that need to call functions marked with +.\" .I init +.\" as an AS-Safety or AC-Unsafe feature should ensure +.\" the initialization is performed +.\" before configuring signal handlers or enabling cancellation, +.\" so that the AS-Safety and AC-Safety issues related with +.\" .I libc_once +.\" do not arise. +.\" +.\" .\" We may have to extend the annotations to cover conditions in which +.\" .\" initialization may or may not occur, since an initial call in a safe +.\" .\" context is no use if the initialization doesn't take place at that +.\" .\" time: it doesn't remove the risk for later calls. +.TP +.I race +Functions annotated with +.I race +as an MT-Safety issue operate on +objects in ways that may cause data races or similar forms of +destructive interference out of concurrent execution. +In some cases, +the objects are passed to the functions by users; +in others, they are used by the functions to return values to users; +in others, they are not even exposed to users. +.\" +.\" We consider access to objects passed as (indirect) arguments to +.\" functions to be data race free. +.\" The assurance of data race free objects +.\" is the caller's responsibility. +.\" We will not mark a function as MT-Unsafe or AS-Unsafe +.\" if it misbehaves when users fail to take the measures required by +.\" POSIX to avoid data races when dealing with such objects. +.\" As a general rule, if a function is documented as reading from +.\" an object passed (by reference) to it, or modifying it, +.\" users ought to use memory synchronization primitives +.\" to avoid data races just as they would should they perform +.\" the accesses themselves rather than by calling the library function. +.\" Standard I/O +.\" .RI ( "FILE *" ) +.\" streams are the exception to the general rule, +.\" in that POSIX mandates the library to guard against data races +.\" in many functions that manipulate objects of this specific opaque type. +.\" We regard this as a convenience provided to users, +.\" rather than as a general requirement whose expectations +.\" should extend to other types. +.\" +.\" In order to remind users that guarding certain arguments is their +.\" responsibility, we will annotate functions that take objects of certain +.\" types as arguments. +.\" We draw the line for objects passed by users as follows: +.\" objects whose types are exposed to users, +.\" and that users are expected to access directly, +.\" such as memory buffers, strings, +.\" and various user-visible structured types, do +.\" .I not +.\" give reason for functions to be annotated with +.\" .IR race . +.\" It would be noisy and redundant with the general requirement, +.\" and not many would be surprised by the library's lack of internal +.\" guards when accessing objects that can be accessed directly by users. +.\" +.\" As for objects that are opaque or opaque-like, +.\" in that they are to be manipulated only by passing them +.\" to library functions (e.g., +.\" .IR FILE , +.\" .IR DIR , +.\" .IR obstack , +.\" .IR iconv_t ), +.\" there might be additional expectations as to internal coordination +.\" of access by the library. +.\" We will annotate, with +.\" .I race +.\" followed by a colon and the argument name, +.\" functions that take such objects but that do not take +.\" care of synchronizing access to them by default. +.\" For example, +.\" .I FILE +.\" stream +.\" .I unlocked +.\" functions +.\" .RB ( unlocked_stdio (3)) +.\" will be annotated, +.\" but those that perform implicit locking on +.\" .I FILE +.\" streams by default will not, +.\" even though the implicit locking may be disabled on a per-stream basis. +.\" +.\" In either case, we will not regard as MT-Unsafe functions that may +.\" access user-supplied objects in unsafe ways should users fail to ensure +.\" the accesses are well defined. +.\" The notion prevails that users are expected to safeguard against +.\" data races any user-supplied objects that the library accesses +.\" on their behalf. +.\" +.\" .\" The above describes @mtsrace; @mtasurace is described below. +.\" +.\" This user responsibility does not apply, however, +.\" to objects controlled by the library itself, +.\" such as internal objects and static buffers used +.\" to return values from certain calls. +.\" When the library doesn't guard them against concurrent uses, +.\" these cases are regarded as MT-Unsafe and AS-Unsafe (although the +.\" .I race +.\" mark under AS-Unsafe will be omitted +.\" as redundant with the one under MT-Unsafe). +.\" As in the case of user-exposed objects, +.\" the mark may be followed by a colon and an identifier. +.\" The identifier groups all functions that operate on a +.\" certain unguarded object; users may avoid the MT-Safety issues related +.\" with unguarded concurrent access to such internal objects by creating a +.\" non-recursive mutex related with the identifier, +.\" and always holding the mutex when calling any function marked +.\" as racy on that identifier, +.\" as they would have to should the identifier be +.\" an object under user control. +.\" The non-recursive mutex avoids the MT-Safety issue, +.\" but it trades one AS-Safety issue for another, +.\" so use in asynchronous signals remains undefined. +.\" +.\" When the identifier relates to a static buffer used to hold return values, +.\" the mutex must be held for as long as the buffer remains in use +.\" by the caller. +.\" Many functions that return pointers to static buffers offer reentrant +.\" variants that store return values in caller-supplied buffers instead. +.\" In some cases, such as +.\" .BR tmpname (3), +.\" the variant is chosen not by calling an alternate entry point, +.\" but by passing a non-NULL pointer to the buffer in which the +.\" returned values are to be stored. +.\" These variants are generally preferable in multi-threaded programs, +.\" although some of them are not MT-Safe because of other internal buffers, +.\" also documented with +.\" .I race +.\" notes. +.TP +.I const +Functions marked with +.I const +as an MT-Safety issue non-atomically +modify internal objects that are better regarded as constant, +because a substantial portion of the GNU C Library accesses them without +synchronization. +Unlike +.IR race , +which causes both readers and +writers of internal objects to be regarded as MT-Unsafe, \" and AS-Unsafe, +this mark is applied to writers only. +Writers remain \" equally +MT-Unsafe \" and AS-Unsafe +to call, +but the then-mandatory constness of objects they +modify enables readers to be regarded as MT-Safe \" and AS-Safe +(as long as no other reasons for them to be unsafe remain), +since the lack of synchronization is not a problem when the +objects are effectively constant. +.IP +The identifier that follows the +.I const +mark will appear by itself as a safety note in readers. +Programs that wish to work around this safety issue, +so as to call writers, may use a non-recursive +read-write lock +associated with the identifier, and guard +.I all +calls to functions marked with +.I const +followed by the identifier with a write lock, and +.I all +calls to functions marked with the identifier +by itself with a read lock. +.\" The non-recursive locking removes the MT-Safety problem, +.\" but it trades one AS-Safety problem for another, +.\" so use in asynchronous signals remains undefined. +.\" +.\" .\" But what if, instead of marking modifiers with const:id and readers +.\" .\" with just id, we marked writers with race:id and readers with ro:id? +.\" .\" Instead of having to define each instance of 'id', we'd have a +.\" .\" general pattern governing all such 'id's, wherein race:id would +.\" .\" suggest the need for an exclusive/write lock to make the function +.\" .\" safe, whereas ro:id would indicate 'id' is expected to be read-only, +.\" .\" but if any modifiers are called (while holding an exclusive lock), +.\" .\" then ro:id-marked functions ought to be guarded with a read lock for +.\" .\" safe operation. ro:env or ro:locale, for example, seems to convey +.\" .\" more clearly the expectations and the meaning, than just env or +.\" .\" locale. +.TP +.I sig +Functions marked with +.I sig +as a MT-Safety issue +.\" (that implies an identical AS-Safety issue, omitted for brevity) +may temporarily install a signal handler for internal purposes, +which may interfere with other uses of the signal, +identified after a colon. +.IP +This safety problem can be worked around by ensuring that no other uses +of the signal will take place for the duration of the call. +Holding a non-recursive mutex while calling all functions that use the same +temporary signal; +blocking that signal before the call and resetting its +handler afterwards is recommended. +.\" +.\" There is no safe way to guarantee the original signal handler is +.\" restored in case of asynchronous cancellation, +.\" therefore so-marked functions are also AC-Unsafe. +.\" +.\" .\" fixme: at least deferred cancellation should get it right, and would +.\" .\" obviate the restoring bit below, and the qualifier above. +.\" +.\" Besides the measures recommended to work around the +.\" MT-Safety and AS-Safety problem, +.\" in order to avert the cancellation problem, +.\" disabling asynchronous cancellation +.\" .I and +.\" installing a cleanup handler to restore the signal to the desired state +.\" and to release the mutex are recommended. +.TP +.I term +Functions marked with +.I term +as an MT-Safety issue may change the +terminal settings in the recommended way, namely: call +.BR tcgetattr (3), +modify some flags, and then call +.BR tcsetattr (3), +this creates a window in which changes made by other threads are lost. +Thus, functions marked with +.I term +are MT-Unsafe. +.\" The same window enables changes made by asynchronous signals to be lost. +.\" These functions are also AS-Unsafe, +.\" but the corresponding mark is omitted as redundant. +.IP +It is thus advisable for applications using the terminal to avoid +concurrent and reentrant interactions with it, +by not using it in signal handlers or blocking signals that might use it, +and holding a lock while calling these functions and interacting +with the terminal. +This lock should also be used for mutual exclusion with +functions marked with +.IR race:tcattr(fd) , +where +.I fd +is a file descriptor for the controlling terminal. +The caller may use a single mutex for simplicity, +or use one mutex per terminal, +even if referenced by different file descriptors. +.\" +.\" Functions marked with +.\" .I term +.\" as an AC-Safety issue are supposed to +.\" restore terminal settings to their original state, +.\" after temporarily changing them, but they may fail to do so if canceled. +.\" +.\" .\" fixme: at least deferred cancellation should get it right, and would +.\" .\" obviate the restoring bit below, and the qualifier above. +.\" +.\" Besides the measures recommended to work around the +.\" MT-Safety and AS-Safety problem, +.\" in order to avert the cancellation problem, +.\" disabling asynchronous cancellation +.\" .I and +.\" installing a cleanup handler to +.\" restore the terminal settings to the original state and to release the +.\" mutex are recommended. +.\" +.\" +.SS Other safety remarks +Additional keywords may be attached to functions, +indicating features that do not make a function unsafe to call, +but that may need to be taken into account in certain classes of programs: +.TP +.I locale +Functions annotated with +.I locale +as an MT-Safety issue read from +the locale object without any form of synchronization. +Functions +annotated with +.I locale +called concurrently with locale changes may +behave in ways that do not correspond to any of the locales active +during their execution, but an unpredictable mix thereof. +.IP +We do not mark these functions as MT-Unsafe, \" or AS-Unsafe, +however, +because functions that modify the locale object are marked with +.I const:locale +and regarded as unsafe. +Being unsafe, the latter are not to be called when multiple threads +are running or asynchronous signals are enabled, +and so the locale can be considered effectively constant +in these contexts, +which makes the former safe. +.\" Should the locking strategy suggested under @code{const} be used, +.\" failure to guard locale uses is not as fatal as data races in +.\" general: unguarded uses will @emph{not} follow dangling pointers or +.\" access uninitialized, unmapped or recycled memory. Each access will +.\" read from a consistent locale object that is or was active at some +.\" point during its execution. Without synchronization, however, it +.\" cannot even be assumed that, after a change in locale, earlier +.\" locales will no longer be used, even after the newly-chosen one is +.\" used in the thread. Nevertheless, even though unguarded reads from +.\" the locale will not violate type safety, functions that access the +.\" locale multiple times may invoke all sorts of undefined behavior +.\" because of the unexpected locale changes. +.TP +.I env +Functions marked with +.I env +as an MT-Safety issue access the +environment with +.BR getenv (3) +or similar, without any guards to ensure +safety in the presence of concurrent modifications. +.IP +We do not mark these functions as MT-Unsafe, \" or AS-Unsafe, +however, +because functions that modify the environment are all marked with +.I const:env +and regarded as unsafe. +Being unsafe, the latter are not to be called when multiple threads +are running or asynchronous signals are enabled, +and so the environment can be considered +effectively constant in these contexts, +which makes the former safe. +.TP +.I hostid +The function marked with +.I hostid +as an MT-Safety issue reads from the system-wide data structures that +hold the "host ID" of the machine. +These data structures cannot generally be modified atomically. +Since it is expected that the "host ID" will not normally change, +the function that reads from it +.RB ( gethostid (3)) +is regarded as safe, +whereas the function that modifies it +.RB ( sethostid (3)) +is marked with +.IR const:hostid , +indicating it may require special care if it is to be called. +In this specific case, +the special care amounts to system-wide +(not merely intra-process) coordination. +.TP +.I sigintr +Functions marked with +.I sigintr +as an MT-Safety issue access the +GNU C Library +.I _sigintr +internal data structure without any guards to ensure +safety in the presence of concurrent modifications. +.IP +We do not mark these functions as MT-Unsafe, \" or AS-Unsafe, +however, +because functions that modify this data structure are all marked with +.I const:sigintr +and regarded as unsafe. +Being unsafe, +the latter are not to be called when multiple threads are +running or asynchronous signals are enabled, +and so the data structure can be considered +effectively constant in these contexts, +which makes the former safe. +.\" .TP +.\" .I fd +.\" Functions annotated with +.\" .I fd +.\" as an AC-Safety issue may leak file +.\" descriptors if asynchronous thread cancellation interrupts their +.\" execution. +.\" +.\" Functions that allocate or deallocate file descriptors will generally be +.\" marked as such. +.\" Even if they attempted to protect the file descriptor +.\" allocation and deallocation with cleanup regions, +.\" allocating a new descriptor and storing its number where the cleanup region +.\" could release it cannot be performed as a single atomic operation. +.\" Similarly, +.\" releasing the descriptor and taking it out of the data structure +.\" normally responsible for releasing it cannot be performed atomically. +.\" There will always be a window in which the descriptor cannot be released +.\" because it was not stored in the cleanup handler argument yet, +.\" or it was already taken out before releasing it. +.\" .\" It cannot be taken out after release: +.\" an open descriptor could mean either that the descriptor still +.\" has to be closed, +.\" or that it already did so but the descriptor was +.\" reallocated by another thread or signal handler. +.\" +.\" Such leaks could be internally avoided, with some performance penalty, +.\" by temporarily disabling asynchronous thread cancellation. +.\" However, +.\" since callers of allocation or deallocation functions would have to do +.\" this themselves, to avoid the same sort of leak in their own layer, +.\" it makes more sense for the library to assume they are taking care of it +.\" than to impose a performance penalty that is redundant when the problem +.\" is solved in upper layers, and insufficient when it is not. +.\" +.\" This remark by itself does not cause a function to be regarded as +.\" AC-Unsafe. +.\" However, cumulative effects of such leaks may pose a +.\" problem for some programs. +.\" If this is the case, +.\" suspending asynchronous cancellation for the duration of calls +.\" to such functions is recommended. +.\" .TP +.\" .I mem +.\" Functions annotated with +.\" .I mem +.\" as an AC-Safety issue may leak +.\" memory if asynchronous thread cancellation interrupts their execution. +.\" +.\" The problem is similar to that of file descriptors: there is no atomic +.\" interface to allocate memory and store its address in the argument to a +.\" cleanup handler, +.\" or to release it and remove its address from that argument, +.\" without at least temporarily disabling asynchronous cancellation, +.\" which these functions do not do. +.\" +.\" This remark does not by itself cause a function to be regarded as +.\" generally AC-Unsafe. +.\" However, cumulative effects of such leaks may be +.\" severe enough for some programs that disabling asynchronous cancellation +.\" for the duration of calls to such functions may be required. +.TP +.I cwd +Functions marked with +.I cwd +as an MT-Safety issue may temporarily +change the current working directory during their execution, +which may cause relative pathnames to be resolved in unexpected ways in +other threads or within asynchronous signal or cancellation handlers. +.IP +This is not enough of a reason to mark so-marked functions as MT-Unsafe, +.\" or AS-Unsafe, +but when this behavior is optional (e.g., +.BR nftw (3) +with +.BR FTW_CHDIR ), +avoiding the option may be a good alternative to +using full pathnames or file descriptor-relative (e.g., +.BR openat (2)) +system calls. +.\" .TP +.\" .I !posix +.\" This remark, as an MT-Safety, AS-Safety or AC-Safety +.\" note to a function, +.\" indicates the safety status of the function is known to differ +.\" from the specified status in the POSIX standard. +.\" For example, POSIX does not require a function to be Safe, +.\" but our implementation is, or vice-versa. +.\" +.\" For the time being, the absence of this remark does not imply the safety +.\" properties we documented are identical to those mandated by POSIX for +.\" the corresponding functions. +.TP +.I :identifier +Annotations may sometimes be followed by identifiers, +intended to group several functions that, for example, +access the data structures in an unsafe way, as in +.I race +and +.IR const , +or to provide more specific information, +such as naming a signal in a function marked with +.IR sig . +It is envisioned that it may be applied to +.I lock +and +.I corrupt +as well in the future. +.IP +In most cases, the identifier will name a set of functions, +but it may name global objects or function arguments, +or identifiable properties or logical components associated with them, +with a notation such as, for example, +.I :buf(arg) +to denote a buffer associated with the argument +.IR arg , +or +.I :tcattr(fd) +to denote the terminal attributes of a file descriptor +.IR fd . +.IP +The most common use for identifiers is to provide logical groups of +functions and arguments that need to be protected by the same +synchronization primitive in order to ensure safe operation in a given +context. +.TP +.I /condition +Some safety annotations may be conditional, +in that they only apply if a boolean expression involving arguments, +global variables or even the underlying kernel evaluates to true. +.\" Such conditions as +.\" .I /hurd +.\" or +.\" .I /!linux!bsd +.\" indicate the preceding marker only +.\" applies when the underlying kernel is the HURD, +.\" or when it is neither Linux nor a BSD kernel, respectively. +For example, +.I /!ps +and +.I /one_per_line +indicate the preceding marker only applies when argument +.I ps +is NULL, or global variable +.I one_per_line +is nonzero. +.IP +When all marks that render a function unsafe are +adorned with such conditions, +and none of the named conditions hold, +then the function can be regarded as safe. +.SH SEE ALSO +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/boot.7 b/man7/boot.7 new file mode 100644 index 0000000..52a9b9f --- /dev/null +++ b/man7/boot.7 @@ -0,0 +1,238 @@ +.\" Written by Oron Peled . +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" May be distributed subject to the GPL. +.\" %%%LICENSE_END +.\" +.\" I tried to be as much generic in the description as possible: +.\" - General boot sequence is applicable to almost any +.\" OS/Machine (DOS/PC, Linux/PC, Solaris/SPARC, CMS/S390) +.\" - kernel and init(1) is applicable to almost any UNIX/Linux +.\" - boot scripts are applicable to SYSV-R4 based UNIX/Linux +.\" +.\" Modified 2004-11-03 patch from Martin Schulze +.\" +.TH BOOT 7 2015-03-11 "Linux" "Linux Programmer's Manual" +.SH NAME +boot \- System bootup process based on UNIX System V Release 4 +.SH DESCRIPTION +.PP +The \fBbootup process\fR (or "\fBboot sequence\fR") varies in details +among systems, but can be roughly divided into phases controlled by +the following components: +.IP 1. 4 +hardware +.IP 2. 4 +operating system (OS) loader +.IP 3. 4 +kernel +.IP 4. 4 +root user-space process (\fIinit\fR and \fIinittab\fR) +.IP 5. 4 +boot scripts +.PP +Each of these is described below in more detail. +.SS Hardware +After power-on or hard reset, control is given +to a program stored in read-only memory (normally +PROM); for historical reasons involving the personal +computer, this program is often called "the \fBBIOS\fR". +.PP +This program normally performs a basic self-test of the +machine and accesses nonvolatile memory to read +further parameters. +This memory in the PC is +battery-backed CMOS memory, so most people +refer to it as "the \fBCMOS\fR"; outside +of the PC world, it is usually called "the \fBNVRAM\fR" +(nonvolatile RAM). +.PP +The parameters stored in the NVRAM vary among +systems, but as a minimum, they should specify +which device can supply an OS loader, or at least which +devices may be probed for one; such a device is known as "the +\fBboot device\fR". +The hardware boot stage loads the OS loader from a fixed position on +the boot device, and then transfers control to it. +.TP +Note: +The device from which the OS loader is read may be attached via a network, in which +case the details of booting are further specified by protocols such as +DHCP, TFTP, PXE, Etherboot, etc. +.SS OS loader +The main job of the OS loader is to locate the kernel +on some device, load it, and run it. +Most OS loaders allow +interactive use, in order to enable specification of an alternative +kernel (maybe a backup in case the one last compiled +isn't functioning) and to pass optional parameters +to the kernel. +.PP +In a traditional PC, the OS loader is located in the initial 512-byte block +of the boot device; this block is known as "the \fBMBR\fR" +(Master Boot Record). +.PP +In most systems, the OS loader is very +limited due to various constraints. +Even on non-PC systems, +there are some limitations on the size and complexity +of this loader, but the size limitation of the PC MBR +(512 bytes, including the partition table) makes it +almost impossible to squeeze much functionality into it. +.PP +Therefore, most systems split the role of loading the OS between +a primary OS loader and a secondary OS loader; this secondary +OS loader may be located within a larger portion of persistent +storage, such as a disk partition. +.PP +In Linux, the OS loader is often either +.BR lilo (8) +or +.BR grub (8). +.SS Kernel +When the kernel is loaded, it initializes various components of +the computer and operating system; each portion of software +responsible for such a task is usually consider "a \fBdriver\fR" for +the applicable component. +The kernel starts the virtual memory +swapper (it is a kernel process, called "kswapd" in a modern Linux +kernel), and mounts some filesystem at the root path, +.IR / . +.PP +Some of the parameters that may be passed to the kernel +relate to these activities (for example, the default root filesystem +can be overridden); for further information +on Linux kernel parameters, read +.BR bootparam (7). +.PP +Only then does the kernel create the initial userland +process, which is given the number 1 as its +.B PID +(process ID). +Traditionally, this process executes the +program +.IR /sbin/init , +to which are passed the parameters that haven't already been +handled by the kernel. +.SS Root user-space process +.TP +Note: +The following description applies to an OS based on UNIX System V Release 4. +However, a number of widely used systems have adopted a related but +fundamentally different approach known as +.BR systemd (1), +for which the bootup process is detailed in its associated +.BR bootup (7). +.PP +When +.I /sbin/init +starts, it reads +.I /etc/inittab +for further instructions. +This file defines what should be run when the +.I /sbin/init +program is instructed to enter a particular \fIrun-level\fR, giving +the administrator an easy way to establish an environment +for some usage; each run-level is associated with a set of services +(for example, run-level \fBS\fR is \fIsingle-user\fR mode, +and run-level \fB2\fR entails running most network services). +.PP +The administrator may change the current +run-level via +.BR init (1), +and query the current run-level via +.BR runlevel (8). +.PP +However, since it is not convenient to manage individual services +by editing this file, +.I /etc/inittab +only bootstraps a set of scripts +that actually start/stop the individual services. +.SS Boot scripts +.TP +Note: +The following description applies to an OS based on UNIX System V Release 4. +However, a number of widely used systems (Slackware Linux, FreeBSD, OpenBSD) +have a somewhat different scheme for boot scripts. +.PP +For each managed service (mail, nfs server, cron, etc.), there is +a single startup script located in a specific directory +.RI ( /etc/init.d +in most versions of Linux). +Each of these scripts accepts as a single argument +the word "start" (causing it to start the service) or the word +\&"stop" (causing it to stop the service). +The script may optionally +accept other "convenience" parameters (e.g., "restart" to stop and then +start, "status" to display the service status, etc.). +Running the script +without parameters displays the possible arguments. +.SS Sequencing directories +To make specific scripts start/stop at specific run-levels and in a +specific order, there are \fIsequencing directories\fR, normally +of the form \fI/etc/rc[0\-6S].d\fR. +In each of these directories, +there are links (usually symbolic) to the scripts in the \fI/etc/init.d\fR +directory. +.PP +A primary script (usually \fI/etc/rc\fR) is called from +.BR inittab (5); +this primary script calls each service's script via a link in the +relevant sequencing directory. +Each link whose name begins with \(aqS\(aq is called with +the argument "start" (thereby starting the service). +Each link whose name begins with \(aqK\(aq is called with +the argument "stop" (thereby stopping the service). +.PP +To define the starting or stopping order within the same run-level, +the name of a link contains an \fBorder-number\fR. +Also, for clarity, the name of a link usually +ends with the name of the service to which it refers. +For example, +the link \fI/etc/rc2.d/S80sendmail\fR starts the sendmail service on +runlevel 2. +This happens after \fI/etc/rc2.d/S12syslog\fR is run +but before \fI/etc/rc2.d/S90xfs\fR is run. +.PP +To manage these links is to manage the boot order and run-levels; +under many systems, there are tools to help with this task +(e.g., +.BR chkconfig (8)). +.SS Boot configuration +A program that provides a service is often called a "\fBdaemon\fR". +Usually, a daemon may receive various command-line options +and parameters. +To allow a system administrator to change these +inputs without editing an entire boot script, +some separate configuration file is used, and is located in a specific +directory where an associated boot script may find it +(\fI/etc/sysconfig\fR on older Red Hat systems). +.PP +In older UNIX systems, such a file contained the actual command line +options for a daemon, but in modern Linux systems (and also +in HP-UX), it just contains shell variables. +A boot script in \fI/etc/init.d\fR reads and includes its configuration +file (that is, it "\fBsources\fR" its configuration file) and then uses +the variable values. +.SH FILES +.PP +.IR /etc/init.d/ , +.IR /etc/rc[S0\-6].d/ , +.I /etc/sysconfig/ +.SH SEE ALSO +.BR init (1), +.BR systemd (1), +.BR inittab (5), +.BR bootparam (7), +.BR bootup (7), +.BR runlevel (8), +.BR shutdown (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/bootparam.7 b/man7/bootparam.7 new file mode 100644 index 0000000..0e20d08 --- /dev/null +++ b/man7/bootparam.7 @@ -0,0 +1,690 @@ +.\" Copyright (c) 1995,1997 Paul Gortmaker and Andries Brouwer +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" This man page written 950814 by aeb, based on Paul Gortmaker's HOWTO +.\" (dated v1.0.1, 15/08/95). +.\" Major update, aeb, 970114. +.\" +.TH BOOTPARAM 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +bootparam \- introduction to boot time parameters of the Linux kernel +.SH DESCRIPTION +The Linux kernel accepts certain 'command-line options' or 'boot time +parameters' at the moment it is started. +In general, this is used to +supply the kernel with information about hardware parameters that +the kernel would not be able to determine on its own, or to avoid/override +the values that the kernel would otherwise detect. +.PP +When the kernel is booted directly by the BIOS, +you have no opportunity to specify any parameters. +So, in order to take advantage of this possibility you have to +use a boot loader that is able to pass parameters, such as GRUB. +.SS The argument list +The kernel command line is parsed into a list of strings +(boot arguments) separated by spaces. +Most of the boot arguments have the form: +.PP +.in +4n +.EX +name[=value_1][,value_2]...[,value_10] +.EE +.in +.PP +where 'name' is a unique keyword that is used to identify what part of +the kernel the associated values (if any) are to be given to. +Note the limit of 10 is real, as the present code handles only 10 comma +separated parameters per keyword. +(However, you can reuse the same +keyword with up to an additional 10 parameters in unusually +complicated situations, assuming the setup function supports it.) +.PP +Most of the sorting is coded in the kernel source file +.IR init/main.c . +First, the kernel +checks to see if the argument is any of the special arguments 'root=', +\&'nfsroot=', 'nfsaddrs=', 'ro', 'rw', 'debug' or 'init'. +The meaning of these special arguments is described below. +.PP +Then it walks a list of setup functions +to see if the specified argument string (such as 'foo') has +been associated with a setup function ('foo_setup()') for a particular +device or part of the kernel. +If you passed the kernel the line +foo=3,4,5,6 then the kernel would search the bootsetups array to see +if 'foo' was registered. +If it was, then it would call the setup +function associated with 'foo' (foo_setup()) and hand it the arguments +3, 4, 5, and 6 as given on the kernel command line. +.PP +Anything of the form 'foo=bar' that is not accepted as a setup function +as described above is then interpreted as an environment variable to +be set. +A (useless?) example would be to use 'TERM=vt100' as a boot +argument. +.PP +Any remaining arguments that were not picked up by the kernel and were +not interpreted as environment variables are then passed onto PID 1, +which is usually the +.BR init (1) +program. +The most common argument that +is passed to the +.I init +process is the word 'single' which instructs it +to boot the computer in single user mode, and not launch all the usual +daemons. +Check the manual page for the version of +.BR init (1) +installed on +your system to see what arguments it accepts. +.SS General non-device-specific boot arguments +.TP +.B "'init=...'" +This sets the initial command to be executed by the kernel. +If this is not set, or cannot be found, the kernel will try +.IR /sbin/init , +then +.IR /etc/init , +then +.IR /bin/init , +then +.I /bin/sh +and panic if all of this fails. +.TP +.B "'nfsaddrs=...'" +This sets the NFS boot address to the given string. +This boot address is used in case of a net boot. +.TP +.B "'nfsroot=...'" +This sets the NFS root name to the given string. +If this string +does not begin with '/' or ',' or a digit, then it is prefixed by +\&'/tftpboot/'. +This root name is used in case of a net boot. +.TP +.B "'root=...'" +This argument tells the kernel what device is to be used as the root +filesystem while booting. +The default of this setting is determined +at compile time, and usually is the value of the root device of the +system that the kernel was built on. +To override this value, and +select the second floppy drive as the root device, one would +use 'root=/dev/fd1'. +.IP +The root device can be specified symbolically or numerically. +A symbolic specification has the form +.IR /dev/XXYN , +where XX designates +the device type (e.g., 'hd' for ST-506 compatible hard disk, with Y in +\&'a'-'d'; 'sd' for SCSI compatible disk, with Y in 'a'-'e'), +Y the driver letter or +number, and N the number (in decimal) of the partition on this device. +.IP +Note that this has nothing to do with the designation of these +devices on your filesystem. +The '/dev/' part is purely conventional. +.IP +The more awkward and less portable numeric specification of the above +possible root devices in major/minor format is also accepted. +(For example, +.I /dev/sda3 +is major 8, minor 3, so you could use 'root=0x803' as an +alternative.) +.TP +.BR "'rootdelay='" +This parameter sets the delay (in seconds) to pause before attempting +to mount the root filesystem. +.TP +.BR "'rootflags=...'" +This parameter sets the mount option string for the root filesystem +(see also +.BR fstab (5)). +.TP +.BR "'rootfstype=...'" +The 'rootfstype' option tells the kernel to mount the root filesystem as +if it where of the type specified. +This can be useful (for example) to +mount an ext3 filesystem as ext2 and then remove the journal in the root +filesystem, in fact reverting its format from ext3 to ext2 without the +need to boot the box from alternate media. +.TP +.BR 'ro' " and " 'rw' +The 'ro' option tells the kernel to mount the root filesystem +as 'read-only' so that filesystem consistency check programs (fsck) +can do their work on a quiescent filesystem. +No processes can +write to files on the filesystem in question until it is 'remounted' +as read/write capable, for example, by 'mount \-w \-n \-o remount /'. +(See also +.BR mount (8).) +.IP +The 'rw' option tells the kernel to mount the root filesystem read/write. +This is the default. +.TP +.B "'resume=...'" +This tells the kernel the location of the suspend-to-disk data that you want the machine to resume from after hibernation. +Usually, it is the same as your swap partition or file. +Example: +.IP +.in +4n +.EX +resume=/dev/hda2 +.EE +.in +.TP +.B "'reserve=...'" +This is used to protect I/O port regions from probes. +The form of the command is: +.IP +.in +4n +.EX +.BI reserve= iobase,extent[,iobase,extent]... +.EE +.in +.IP +In some machines it may be necessary to prevent device drivers from +checking for devices (auto-probing) in a specific region. +This may be +because of hardware that reacts badly to the probing, or hardware +that would be mistakenly identified, or merely +hardware you don't want the kernel to initialize. +.IP +The reserve boot-time argument specifies an I/O port region that +shouldn't be probed. +A device driver will not probe a reserved region, +unless another boot argument explicitly specifies that it do so. +.IP +For example, the boot line +.IP +.in +4n +.EX +reserve=0x300,32 blah=0x300 +.EE +.in +.IP +keeps all device drivers except the driver for 'blah' from probing +0x300\-0x31f. +.TP +.B "'panic=N'" +By default, the kernel will not reboot after a panic, but this option +will cause a kernel reboot after N seconds (if N is greater than zero). +This panic timeout can also be set by +.IP +.in +4n +.EX +echo N > /proc/sys/kernel/panic +.EE +.in +.TP +.B "'reboot=[warm|cold][,[bios|hard]]'" +Since Linux 2.0.22, a reboot is by default a cold reboot. +One asks for the old default with 'reboot=warm'. +(A cold reboot may be required to reset certain hardware, +but might destroy not yet written data in a disk cache. +A warm reboot may be faster.) +By default, a reboot is hard, by asking the keyboard controller +to pulse the reset line low, but there is at least one type +of motherboard where that doesn't work. +The option 'reboot=bios' will +instead jump through the BIOS. +.TP +.BR 'nosmp' " and " 'maxcpus=N' +(Only when __SMP__ is defined.) +A command-line option of 'nosmp' or 'maxcpus=0' will disable SMP +activation entirely; an option 'maxcpus=N' limits the maximum number +of CPUs activated in SMP mode to N. +.SS Boot arguments for use by kernel developers +.TP +.B "'debug'" +Kernel messages are handed off to a daemon (e.g., +.BR klogd (8) +or similar) so that they may be logged to disk. +Messages with a priority above +.I console_loglevel +are also printed on the console. +(For a discussion of log levels, see +.BR syslog (2).) +By default, +.I console_loglevel +is set to log messages at levels higher than +.BR KERN_DEBUG . +This boot argument will cause the kernel to also +print messages logged at level +.BR KERN_DEBUG . +The console loglevel can also be set on a booted system via the +.IR /proc/sys/kernel/printk +file (described in +.BR syslog (2)), +the +.BR syslog (2) +.B SYSLOG_ACTION_CONSOLE_LEVEL +operation, or +.BR dmesg (8). +.TP +.B "'profile=N'" +It is possible to enable a kernel profiling function, +if one wishes to find out where the kernel is spending its CPU cycles. +Profiling is enabled by setting the variable +.I prof_shift +to a nonzero value. +This is done either by specifying +.B CONFIG_PROFILE +at compile time, or by giving the 'profile=' option. +Now the value that +.I prof_shift +gets will be N, when given, or +.BR CONFIG_PROFILE_SHIFT , +when that is given, or 2, the default. +The significance of this variable is that it +gives the granularity of the profiling: each clock tick, if the +system was executing kernel code, a counter is incremented: +.IP +.in +4n +.EX +profile[address >> prof_shift]++; +.EE +.in +.IP +The raw profiling information can be read from +.IR /proc/profile . +Probably you'll want to use a tool such as readprofile.c to digest it. +Writing to +.I /proc/profile +will clear the counters. +.SS Boot arguments for ramdisk use +(Only if the kernel was compiled with +.BR CONFIG_BLK_DEV_RAM .) +In general it is a bad idea to use a ramdisk under Linux\(emthe +system will use available memory more efficiently itself. +But while booting, +it is often useful to load the floppy contents into a +ramdisk. +One might also have a system in which first +some modules (for filesystem or hardware) must be loaded +before the main disk can be accessed. +.IP +In Linux 1.3.48, ramdisk handling was changed drastically. +Earlier, the memory was allocated statically, and there was +a 'ramdisk=N' parameter to tell its size. +(This could also be set in the kernel image at compile time.) +These days ram disks use the buffer cache, and grow dynamically. +For a lot of information on the current ramdisk +setup, see the kernel source file +.IR Documentation/blockdev/ramdisk.txt +.RI ( Documentation/ramdisk.txt +in older kernels). +.IP +There are four parameters, two boolean and two integral. +.TP +.B "'load_ramdisk=N'" +If N=1, do load a ramdisk. +If N=0, do not load a ramdisk. +(This is the default.) +.TP +.B "'prompt_ramdisk=N'" +If N=1, do prompt for insertion of the floppy. +(This is the default.) +If N=0, do not prompt. +(Thus, this parameter is never needed.) +.TP +.BR 'ramdisk_size=N' " or (obsolete) " 'ramdisk=N' +Set the maximal size of the ramdisk(s) to N kB. +The default is 4096 (4\ MB). +.TP +.B "'ramdisk_start=N'" +Sets the starting block number (the offset on the floppy where +the ramdisk starts) to N. +This is needed in case the ramdisk follows a kernel image. +.TP +.B "'noinitrd'" +(Only if the kernel was compiled with +.B CONFIG_BLK_DEV_RAM +and +.BR CONFIG_BLK_DEV_INITRD .) +These days it is possible to compile the kernel to use initrd. +When this feature is enabled, the boot process will load the kernel +and an initial ramdisk; then the kernel converts initrd into +a "normal" ramdisk, which is mounted read-write as root device; +then +.I /linuxrc +is executed; afterward the "real" root filesystem is mounted, +and the initrd filesystem is moved over to +.IR /initrd ; +finally +the usual boot sequence (e.g., invocation of +.IR /sbin/init ) +is performed. +.IP +For a detailed description of the initrd feature, see the kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10). +.IP +The 'noinitrd' option tells the kernel that although it was compiled for +operation with initrd, it should not go through the above steps, but +leave the initrd data under +.IR /dev/initrd . +(This device can be used only once: the data is freed as soon as +the last process that used it has closed +.IR /dev/initrd .) +.SS Boot arguments for SCSI devices +General notation for this section: +.PP +.I iobase +-- the first I/O port that the SCSI host occupies. +These are specified in hexadecimal notation, +and usually lie in the range from 0x200 to 0x3ff. +.PP +.I irq +-- the hardware interrupt that the card is configured to use. +Valid values will be dependent on the card in question, but will +usually be 5, 7, 9, 10, 11, 12, and 15. +The other values are usually +used for common peripherals like IDE hard disks, floppies, serial +ports, and so on. +.PP +.I scsi-id +-- the ID that the host adapter uses to identify itself on the +SCSI bus. +Only some host adapters allow you to change this value, as +most have it permanently specified internally. +The usual default value +is 7, but the Seagate and Future Domain TMC-950 boards use 6. +.PP +.I parity +-- whether the SCSI host adapter expects the attached devices +to supply a parity value with all information exchanges. +Specifying a one indicates parity checking is enabled, +and a zero disables parity checking. +Again, not all adapters will support selection of parity +behavior as a boot argument. +.TP +.B "'max_scsi_luns=...'" +A SCSI device can have a number of 'subdevices' contained within +itself. +The most common example is one of the new SCSI CD-ROMs that +handle more than one disk at a time. +Each CD is addressed as a +\&'Logical Unit Number' (LUN) of that particular device. +But most +devices, such as hard disks, tape drives and such are only one device, +and will be assigned to LUN zero. +.IP +Some poorly designed SCSI devices cannot handle being probed for +LUNs not equal to zero. +Therefore, if the compile-time flag +.B CONFIG_SCSI_MULTI_LUN +is not set, newer kernels will by default probe only LUN zero. +.IP +To specify the number of probed LUNs at boot, one enters +\&'max_scsi_luns=n' as a boot arg, where n is a number between one and +eight. +To avoid problems as described above, one would use n=1 to +avoid upsetting such broken devices. +.TP +.B "SCSI tape configuration" +Some boot time configuration of the SCSI tape driver can be achieved +by using the following: +.IP +.in +4n +.EX +.BI st= buf_size[,write_threshold[,max_bufs]] +.EE +.in +.IP +The first two numbers are specified in units of kB. +The default +.I buf_size +is 32k\ B, and the maximum size that can be specified is a +ridiculous 16384\ kB. +The +.I write_threshold +is the value at which the buffer is committed to tape, with a +default value of 30\ kB. +The maximum number of buffers varies +with the number of drives detected, and has a default of two. +An example usage would be: +.IP +.in +4n +.EX +st=32,30,2 +.EE +.in +.IP +Full details can be found in the file +.I Documentation/scsi/st.txt +(or +.I drivers/scsi/README.st +for older kernels) in the Linux kernel source. +.SS Hard disks +.TP +.B "IDE Disk/CD-ROM Driver Parameters" +The IDE driver accepts a number of parameters, which range from disk +geometry specifications, to support for broken controller chips. +Drive-specific options are specified by using 'hdX=' with X in 'a'-'h'. +.IP +Non-drive-specific options are specified with the prefix 'hd='. +Note that using a drive-specific prefix for a non-drive-specific option +will still work, and the option will just be applied as expected. +.IP +Also note that 'hd=' can be used to refer to the next unspecified +drive in the (a, ..., h) sequence. +For the following discussions, +the 'hd=' option will be cited for brevity. +See the file +.I Documentation/ide/ide.txt +(or +.I Documentation/ide.txt +.\" Linux 2.0, 2.2, 2.4 +in older kernels, or +.I drivers/block/README.ide +in ancient kernels) in the Linux kernel source for more details. +.TP +.B "The 'hd=cyls,heads,sects[,wpcom[,irq]]' options" +These options are used to specify the physical geometry of the disk. +Only the first three values are required. +The cylinder/head/sectors +values will be those used by fdisk. +The write precompensation value +is ignored for IDE disks. +The IRQ value specified will be the IRQ +used for the interface that the drive resides on, and is not really a +drive-specific parameter. +.TP +.B "The 'hd=serialize' option" +The dual IDE interface CMD-640 chip is broken as designed such that +when drives on the secondary interface are used at the same time as +drives on the primary interface, it will corrupt your data. +Using this +option tells the driver to make sure that both interfaces are never +used at the same time. +.TP +.B "The 'hd=noprobe' option" +Do not probe for this drive. +For example, +.IP +.in +4n +.EX +hdb=noprobe hdb=1166,7,17 +.EE +.in +.IP +would disable the probe, but still specify the drive geometry so +that it would be registered as a valid block device, and hence +usable. +.TP +.B "The 'hd=nowerr' option" +Some drives apparently have the +.B WRERR_STAT +bit stuck on permanently. +This enables a work-around for these broken devices. +.TP +.B "The 'hd=cdrom' option" +This tells the IDE driver that there is an ATAPI compatible CD-ROM +attached in place of a normal IDE hard disk. +In most cases the CD-ROM +is identified automatically, but if it isn't then this may help. +.TP +.B "Standard ST-506 Disk Driver Options ('hd=')" +The standard disk driver can accept geometry arguments for the disks +similar to the IDE driver. +Note however that it expects only three +values (C/H/S); any more or any less and it will silently ignore you. +Also, it accepts only 'hd=' as an argument, that is, 'hda=' +and so on are not valid here. +The format is as follows: +.IP +.in +4n +.EX +hd=cyls,heads,sects +.EE +.in +.IP +If there are two disks installed, the above is repeated with the +geometry parameters of the second disk. +.SS Ethernet devices +Different drivers make use of different parameters, but they all at +least share having an IRQ, an I/O port base value, and a name. +In its most generic form, it looks something like this: +.PP +.in +4n +.EX +ether=irq,iobase[,param_1[,...param_8]],name +.EE +.in +.PP +The first nonnumeric argument is taken as the name. +The param_n values (if applicable) usually have different meanings for each +different card/driver. +Typical param_n values are used to specify +things like shared memory address, interface selection, DMA channel +and the like. +.PP +The most common use of this parameter is to force probing for a second +ethercard, as the default is to probe only for one. +This can be accomplished with a simple: +.PP +.in +4n +.EX +ether=0,0,eth1 +.EE +.in +.PP +Note that the values of zero for the IRQ and I/O base in the above +example tell the driver(s) to autoprobe. +.PP +The Ethernet-HowTo has extensive documentation on using multiple +cards and on the card/driver-specific implementation +of the param_n values where used. +Interested readers should refer to +the section in that document on their particular card. +.SS The floppy disk driver +There are many floppy driver options, and they are all listed in +.I Documentation/blockdev/floppy.txt +(or +.I Documentation/floppy.txt +in older kernels, or +.I drivers/block/README.fd +for ancient kernels) in the Linux kernel source. +See that file for the details. +.SS The sound driver +The sound driver can also accept boot arguments to override the compiled-in +values. +This is not recommended, as it is rather complex. +It is described in the Linux kernel source file +.IR Documentation/sound/oss/README.OSS +.RI ( drivers/sound/Readme.linux +in older kernel versions). +It accepts +a boot argument of the form: +.PP +.in +4n +.EX +sound=device1[,device2[,device3...[,device10]]] +.EE +.in +.PP +where each deviceN value is of the following format 0xTaaaId and the +bytes are used as follows: +.PP +T \- device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16, +7=SB16-MPU401 +.PP +aaa \- I/O address in hex. +.PP +I \- interrupt line in hex (i.e., 10=a, 11=b, ...) +.PP +d \- DMA channel. +.PP +As you can see, it gets pretty messy, and you are better off to compile +in your own personal values as recommended. +Using a boot argument of +\&'sound=0' will disable the sound driver entirely. +.SS The line printer driver +.TP +.B "'lp='" +.br +Syntax: +.IP +.in +4n +.EX +lp=0 +lp=auto +lp=reset +lp=port[,port...] +.EE +.in +.IP +You can tell the printer driver what ports to use and what ports not +to use. +The latter comes in handy if you don't want the printer driver +to claim all available parallel ports, so that other drivers +(e.g., PLIP, PPA) can use them instead. +.IP +The format of the argument is multiple port names. +For example, +lp=none,parport0 would use the first parallel port for lp1, and +disable lp0. +To disable the printer driver entirely, one can use +lp=0. +.\" .SH AUTHORS +.\" Linus Torvalds (and many others) +.SH SEE ALSO +.BR klogd (8), +.BR mount (8) +.PP +For up-to-date information, see the kernel source file +.IR Documentation/admin-guide/kernel-parameters.txt . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/capabilities.7 b/man7/capabilities.7 new file mode 100644 index 0000000..c34183e --- /dev/null +++ b/man7/capabilities.7 @@ -0,0 +1,1486 @@ +.\" Copyright (c) 2002 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 6 Aug 2002 - Initial Creation +.\" Modified 2003-05-23, Michael Kerrisk, +.\" Modified 2004-05-27, Michael Kerrisk, +.\" 2004-12-08, mtk Added O_NOATIME for CAP_FOWNER +.\" 2005-08-16, mtk, Added CAP_AUDIT_CONTROL and CAP_AUDIT_WRITE +.\" 2008-07-15, Serge Hallyn +.\" Document file capabilities, per-process capability +.\" bounding set, changed semantics for CAP_SETPCAP, +.\" and other changes in 2.6.2[45]. +.\" Add CAP_MAC_ADMIN, CAP_MAC_OVERRIDE, CAP_SETFCAP. +.\" 2008-07-15, mtk +.\" Add text describing circumstances in which CAP_SETPCAP +.\" (theoretically) permits a thread to change the +.\" capability sets of another thread. +.\" Add section describing rules for programmatically +.\" adjusting thread capability sets. +.\" Describe rationale for capability bounding set. +.\" Document "securebits" flags. +.\" Add text noting that if we set the effective flag for one file +.\" capability, then we must also set the effective flag for all +.\" other capabilities where the permitted or inheritable bit is set. +.\" 2011-09-07, mtk/Serge hallyn: Add CAP_SYSLOG +.\" +.TH CAPABILITIES 7 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +capabilities \- overview of Linux capabilities +.SH DESCRIPTION +For the purpose of performing permission checks, +traditional UNIX implementations distinguish two categories of processes: +.I privileged +processes (whose effective user ID is 0, referred to as superuser or root), +and +.I unprivileged +processes (whose effective UID is nonzero). +Privileged processes bypass all kernel permission checks, +while unprivileged processes are subject to full permission +checking based on the process's credentials +(usually: effective UID, effective GID, and supplementary group list). +.PP +Starting with kernel 2.2, Linux divides the privileges traditionally +associated with superuser into distinct units, known as +.IR capabilities , +which can be independently enabled and disabled. +Capabilities are a per-thread attribute. +.\" +.SS Capabilities list +The following list shows the capabilities implemented on Linux, +and the operations or behaviors that each capability permits: +.TP +.BR CAP_AUDIT_CONTROL " (since Linux 2.6.11)" +Enable and disable kernel auditing; change auditing filter rules; +retrieve auditing status and filtering rules. +.TP +.BR CAP_AUDIT_READ " (since Linux 3.16)" +.\" commit a29b694aa1739f9d76538e34ae25524f9c549d59 +.\" commit 3a101b8de0d39403b2c7e5c23fd0b005668acf48 +Allow reading the audit log via a multicast netlink socket. +.TP +.BR CAP_AUDIT_WRITE " (since Linux 2.6.11)" +Write records to kernel auditing log. +.TP +.BR CAP_BLOCK_SUSPEND " (since Linux 3.5)" +Employ features that can block system suspend +.RB ( epoll (7) +.BR EPOLLWAKEUP , +.IR /proc/sys/wake_lock ). +.TP +.B CAP_CHOWN +Make arbitrary changes to file UIDs and GIDs (see +.BR chown (2)). +.TP +.B CAP_DAC_OVERRIDE +Bypass file read, write, and execute permission checks. +(DAC is an abbreviation of "discretionary access control".) +.TP +.B CAP_DAC_READ_SEARCH +.PD 0 +.RS +.IP * 2 +Bypass file read permission checks and +directory read and execute permission checks; +.IP * +invoke +.BR open_by_handle_at (2); +.IP * +use the +.BR linkat (2) +.B AT_EMPTY_PATH +flag to create a link to a file referred to by a file descriptor. +.RE +.PD +.TP +.B CAP_FOWNER +.PD 0 +.RS +.IP * 2 +Bypass permission checks on operations that normally +require the filesystem UID of the process to match the UID of +the file (e.g., +.BR chmod (2), +.BR utime (2)), +excluding those operations covered by +.B CAP_DAC_OVERRIDE +and +.BR CAP_DAC_READ_SEARCH ; +.IP * +set inode flags (see +.BR ioctl_iflags (2)) +on arbitrary files; +.IP * +set Access Control Lists (ACLs) on arbitrary files; +.IP * +ignore directory sticky bit on file deletion; +.IP * +specify +.B O_NOATIME +for arbitrary files in +.BR open (2) +and +.BR fcntl (2). +.RE +.PD +.TP +.B CAP_FSETID +.PD 0 +.RS +.IP * 2 +Don't clear set-user-ID and set-group-ID mode +bits when a file is modified; +.IP * +set the set-group-ID bit for a file whose GID does not match +the filesystem or any of the supplementary GIDs of the calling process. +.RE +.PD +.TP +.B CAP_IPC_LOCK +.\" FIXME . As at Linux 3.2, there are some strange uses of this capability +.\" in other places; they probably should be replaced with something else. +Lock memory +.RB ( mlock (2), +.BR mlockall (2), +.BR mmap (2), +.BR shmctl (2)). +.TP +.B CAP_IPC_OWNER +Bypass permission checks for operations on System V IPC objects. +.TP +.B CAP_KILL +Bypass permission checks for sending signals (see +.BR kill (2)). +This includes use of the +.BR ioctl (2) +.B KDSIGACCEPT +operation. +.\" FIXME . CAP_KILL also has an effect for threads + setting child +.\" termination signal to other than SIGCHLD: without this +.\" capability, the termination signal reverts to SIGCHLD +.\" if the child does an exec(). What is the rationale +.\" for this? +.TP +.BR CAP_LEASE " (since Linux 2.4)" +Establish leases on arbitrary files (see +.BR fcntl (2)). +.TP +.B CAP_LINUX_IMMUTABLE +Set the +.B FS_APPEND_FL +and +.B FS_IMMUTABLE_FL +inode flags (see +.BR ioctl_iflags (2)). +.TP +.BR CAP_MAC_ADMIN " (since Linux 2.6.25)" +Allow MAC configuration or state changes. +Implemented for the Smack Linux Security Module (LSM). +.TP +.BR CAP_MAC_OVERRIDE " (since Linux 2.6.25)" +Override Mandatory Access Control (MAC). +Implemented for the Smack LSM. +.TP +.BR CAP_MKNOD " (since Linux 2.4)" +Create special files using +.BR mknod (2). +.TP +.B CAP_NET_ADMIN +Perform various network-related operations: +.PD 0 +.RS +.IP * 2 +interface configuration; +.IP * +administration of IP firewall, masquerading, and accounting; +.IP * +modify routing tables; +.IP * +bind to any address for transparent proxying; +.IP * +set type-of-service (TOS) +.IP * +clear driver statistics; +.IP * +set promiscuous mode; +.IP * +enabling multicasting; +.IP * +use +.BR setsockopt (2) +to set the following socket options: +.BR SO_DEBUG , +.BR SO_MARK , +.BR SO_PRIORITY +(for a priority outside the range 0 to 6), +.BR SO_RCVBUFFORCE , +and +.BR SO_SNDBUFFORCE . +.RE +.PD +.TP +.B CAP_NET_BIND_SERVICE +Bind a socket to Internet domain privileged ports +(port numbers less than 1024). +.TP +.B CAP_NET_BROADCAST +(Unused) Make socket broadcasts, and listen to multicasts. +.\" FIXME Since Linux 4.2, there are use cases for netlink sockets +.\" commit 59324cf35aba5336b611074028777838a963d03b +.TP +.B CAP_NET_RAW +.PD 0 +.RS +.IP * 2 +Use RAW and PACKET sockets; +.IP * +bind to any address for transparent proxying. +.RE +.PD +.\" Also various IP options and setsockopt(SO_BINDTODEVICE) +.TP +.B CAP_SETGID +.RS +.PD 0 +.IP * 2 +Make arbitrary manipulations of process GIDs and supplementary GID list; +.IP * +forge GID when passing socket credentials via UNIX domain sockets; +.IP * +write a group ID mapping in a user namespace (see +.BR user_namespaces (7)). +.PD +.RE +.TP +.BR CAP_SETFCAP " (since Linux 2.6.24)" +Set arbitrary capabilities on a file. +.TP +.B CAP_SETPCAP +If file capabilities are supported (i.e., since Linux 2.6.24): +add any capability from the calling thread's bounding set +to its inheritable set; +drop capabilities from the bounding set (via +.BR prctl (2) +.BR PR_CAPBSET_DROP ); +make changes to the +.I securebits +flags. +.IP +If file capabilities are not supported (i.e., kernels before Linux 2.6.24): +grant or remove any capability in the +caller's permitted capability set to or from any other process. +(This property of +.B CAP_SETPCAP +is not available when the kernel is configured to support +file capabilities, since +.B CAP_SETPCAP +has entirely different semantics for such kernels.) +.TP +.B CAP_SETUID +.RS +.PD 0 +.IP * 2 +Make arbitrary manipulations of process UIDs +.RB ( setuid (2), +.BR setreuid (2), +.BR setresuid (2), +.BR setfsuid (2)); +.IP * +forge UID when passing socket credentials via UNIX domain sockets; +.IP * +write a user ID mapping in a user namespace (see +.BR user_namespaces (7)). +.PD +.RE +.\" FIXME CAP_SETUID also an effect in exec(); document this. +.TP +.B CAP_SYS_ADMIN +.IR Note : +this capability is overloaded; see +.IR "Notes to kernel developers" , +below. +.IP +.PD 0 +.RS +.IP * 2 +Perform a range of system administration operations including: +.BR quotactl (2), +.BR mount (2), +.BR umount (2), +.BR swapon (2), +.BR swapoff (2), +.BR sethostname (2), +and +.BR setdomainname (2); +.IP * +perform privileged +.BR syslog (2) +operations (since Linux 2.6.37, +.BR CAP_SYSLOG +should be used to permit such operations); +.IP * +perform +.B VM86_REQUEST_IRQ +.BR vm86 (2) +command; +.IP * +perform +.B IPC_SET +and +.B IPC_RMID +operations on arbitrary System V IPC objects; +.IP * +override +.B RLIMIT_NPROC +resource limit; +.IP * +perform operations on +.I trusted +and +.I security +Extended Attributes (see +.BR xattr (7)); +.IP * +use +.BR lookup_dcookie (2); +.IP * +use +.BR ioprio_set (2) +to assign +.B IOPRIO_CLASS_RT +and (before Linux 2.6.25) +.B IOPRIO_CLASS_IDLE +I/O scheduling classes; +.IP * +forge PID when passing socket credentials via UNIX domain sockets; +.IP * +exceed +.IR /proc/sys/fs/file-max , +the system-wide limit on the number of open files, +in system calls that open files (e.g., +.BR accept (2), +.BR execve (2), +.BR open (2), +.BR pipe (2)); +.IP * +employ +.B CLONE_* +flags that create new namespaces with +.BR clone (2) +and +.BR unshare (2) +(but, since Linux 3.8, +creating user namespaces does not require any capability); +.IP * +call +.BR perf_event_open (2); +.IP * +access privileged +.I perf +event information; +.IP * +call +.BR setns (2) +(requires +.B CAP_SYS_ADMIN +in the +.I target +namespace); +.IP * +call +.BR fanotify_init (2); +.IP * +call +.BR bpf (2); +.IP * +perform privileged +.B KEYCTL_CHOWN +and +.B KEYCTL_SETPERM +.BR keyctl (2) +operations; +.IP * +use +.BR ptrace (2) +.B PTRACE_SECCOMP_GET_FILTER +to dump a tracees seccomp filters; +.IP * +perform +.BR madvise (2) +.B MADV_HWPOISON +operation; +.IP * +employ the +.B TIOCSTI +.BR ioctl (2) +to insert characters into the input queue of a terminal other than +the caller's controlling terminal; +.IP * +employ the obsolete +.BR nfsservctl (2) +system call; +.IP * +employ the obsolete +.BR bdflush (2) +system call; +.IP * +perform various privileged block-device +.BR ioctl (2) +operations; +.IP * +perform various privileged filesystem +.BR ioctl (2) +operations; +.IP * +perform privileged +.BR ioctl (2) +operations on the +.IR /dev/random +device (see +.BR random (4)); +.IP * +install a +.BR seccomp (2) +filter without first having to set the +.I no_new_privs +thread attribute; +.IP * +modify allow/deny rules for device control groups; +.IP * +employ the +.BR ptrace (2) +.B PTRACE_SECCOMP_GET_FILTER +operation to dump tracee's seccomp filters; +.IP * +employ the +.BR ptrace (2) +.B PTRACE_SETOPTIONS +operation to suspend the tracee's seccomp protections (i.e., the +.B PTRACE_O_SUSPEND_SECCOMP +flag). +.IP * +perform administrative operations on many device drivers. +.RE +.PD +.TP +.B CAP_SYS_BOOT +Use +.BR reboot (2) +and +.BR kexec_load (2). +.TP +.B CAP_SYS_CHROOT +Use +.BR chroot (2). +.\" FIXME . There is a use case in mntns_install() +.TP +.B CAP_SYS_MODULE +.RS +.PD 0 +.IP * 2 +Load and unload kernel modules +(see +.BR init_module (2) +and +.BR delete_module (2)); +.IP * +in kernels before 2.6.25: +drop capabilities from the system-wide capability bounding set. +.PD +.RE +.TP +.B CAP_SYS_NICE +.PD 0 +.RS +.IP * 2 +Raise process nice value +.RB ( nice (2), +.BR setpriority (2)) +and change the nice value for arbitrary processes; +.IP * +set real-time scheduling policies for calling process, +and set scheduling policies and priorities for arbitrary processes +.RB ( sched_setscheduler (2), +.BR sched_setparam (2), +.BR shed_setattr (2)); +.IP * +set CPU affinity for arbitrary processes +.RB ( sched_setaffinity (2)); +.IP * +set I/O scheduling class and priority for arbitrary processes +.RB ( ioprio_set (2)); +.IP * +apply +.BR migrate_pages (2) +to arbitrary processes and allow processes +to be migrated to arbitrary nodes; +.\" FIXME CAP_SYS_NICE also has the following effect for +.\" migrate_pages(2): +.\" do_migrate_pages(mm, &old, &new, +.\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE); +.\" +.\" Document this. +.IP * +apply +.BR move_pages (2) +to arbitrary processes; +.IP * +use the +.B MPOL_MF_MOVE_ALL +flag with +.BR mbind (2) +and +.BR move_pages (2). +.RE +.PD +.TP +.B CAP_SYS_PACCT +Use +.BR acct (2). +.TP +.B CAP_SYS_PTRACE +.PD 0 +.RS +.IP * 2 +Trace arbitrary processes using +.BR ptrace (2); +.IP * +apply +.BR get_robust_list (2) +to arbitrary processes; +.IP * +transfer data to or from the memory of arbitrary processes using +.BR process_vm_readv (2) +and +.BR process_vm_writev (2); +.IP * +inspect processes using +.BR kcmp (2). +.RE +.PD +.TP +.B CAP_SYS_RAWIO +.PD 0 +.RS +.IP * 2 +Perform I/O port operations +.RB ( iopl (2) +and +.BR ioperm (2)); +.IP * +access +.IR /proc/kcore ; +.IP * +employ the +.B FIBMAP +.BR ioctl (2) +operation; +.IP * +open devices for accessing x86 model-specific registers (MSRs, see +.BR msr (4)); +.IP * +update +.IR /proc/sys/vm/mmap_min_addr ; +.IP * +create memory mappings at addresses below the value specified by +.IR /proc/sys/vm/mmap_min_addr ; +.IP * +map files in +.IR /proc/bus/pci ; +.IP * +open +.IR /dev/mem +and +.IR /dev/kmem ; +.IP * +perform various SCSI device commands; +.IP * +perform certain operations on +.BR hpsa (4) +and +.BR cciss (4) +devices; +.IP * +perform a range of device-specific operations on other devices. +.RE +.PD +.TP +.B CAP_SYS_RESOURCE +.PD 0 +.RS +.IP * 2 +Use reserved space on ext2 filesystems; +.IP * +make +.BR ioctl (2) +calls controlling ext3 journaling; +.IP * +override disk quota limits; +.IP * +increase resource limits (see +.BR setrlimit (2)); +.IP * +override +.B RLIMIT_NPROC +resource limit; +.IP * +override maximum number of consoles on console allocation; +.IP * +override maximum number of keymaps; +.IP * +allow more than 64hz interrupts from the real-time clock; +.IP * +raise +.I msg_qbytes +limit for a System V message queue above the limit in +.I /proc/sys/kernel/msgmnb +(see +.BR msgop (2) +and +.BR msgctl (2)); +.IP * +allow the +.B RLIMIT_NOFILE +resource limit on the number of "in-flight" file descriptors +to be bypassed when passing file descriptors to another process +via a UNIX domain socket (see +.BR unix (7)); +.IP * +override the +.I /proc/sys/fs/pipe-size-max +limit when setting the capacity of a pipe using the +.B F_SETPIPE_SZ +.BR fcntl (2) +command. +.IP * +use +.BR F_SETPIPE_SZ +to increase the capacity of a pipe above the limit specified by +.IR /proc/sys/fs/pipe-max-size ; +.IP * +override +.I /proc/sys/fs/mqueue/queues_max +limit when creating POSIX message queues (see +.BR mq_overview (7)); +.IP * +employ the +.BR prctl (2) +.B PR_SET_MM +operation; +.IP * +set +.IR /proc/[pid]/oom_score_adj +to a value lower than the value last set by a process with +.BR CAP_SYS_RESOURCE . +.RE +.PD +.TP +.B CAP_SYS_TIME +Set system clock +.RB ( settimeofday (2), +.BR stime (2), +.BR adjtimex (2)); +set real-time (hardware) clock. +.TP +.B CAP_SYS_TTY_CONFIG +Use +.BR vhangup (2); +employ various privileged +.BR ioctl (2) +operations on virtual terminals. +.TP +.BR CAP_SYSLOG " (since Linux 2.6.37)" +.RS +.PD 0 +.IP * 2 +Perform privileged +.BR syslog (2) +operations. +See +.BR syslog (2) +for information on which operations require privilege. +.IP * +View kernel addresses exposed via +.I /proc +and other interfaces when +.IR /proc/sys/kernel/kptr_restrict +has the value 1. +(See the discussion of the +.I kptr_restrict +in +.BR proc (5).) +.PD +.RE +.TP +.BR CAP_WAKE_ALARM " (since Linux 3.0)" +Trigger something that will wake up the system (set +.B CLOCK_REALTIME_ALARM +and +.B CLOCK_BOOTTIME_ALARM +timers). +.\" +.SS Past and current implementation +A full implementation of capabilities requires that: +.IP 1. 3 +For all privileged operations, +the kernel must check whether the thread has the required +capability in its effective set. +.IP 2. +The kernel must provide system calls allowing a thread's capability sets to +be changed and retrieved. +.IP 3. +The filesystem must support attaching capabilities to an executable file, +so that a process gains those capabilities when the file is executed. +.PP +Before kernel 2.6.24, only the first two of these requirements are met; +since kernel 2.6.24, all three requirements are met. +.\" +.SS Notes to kernel developers +When adding a new kernel feature that should be governed by a capability, +consider the following points. +.IP * 3 +The goal of capabilities is divide the power of superuser into pieces, +such that if a program that has one or more capabilities is compromised, +its power to do damage to the system would be less than the same program +running with root privilege. +.IP * +You have the choice of either creating a new capability for your new feature, +or associating the feature with one of the existing capabilities. +In order to keep the set of capabilities to a manageable size, +the latter option is preferable, +unless there are compelling reasons to take the former option. +(There is also a technical limit: +the size of capability sets is currently limited to 64 bits.) +.IP * +To determine which existing capability might best be associated +with your new feature, review the list of capabilities above in order +to find a "silo" into which your new feature best fits. +One approach to take is to determine if there are other features +requiring capabilities that will always be use along with the new feature. +If the new feature is useless without these other features, +you should use the same capability as the other features. +.IP * +.IR Don't +choose +.B CAP_SYS_ADMIN +if you can possibly avoid it! +A vast proportion of existing capability checks are associated +with this capability (see the partial list above). +It can plausibly be called "the new root", +since on the one hand, it confers a wide range of powers, +and on the other hand, +its broad scope means that this is the capability +that is required by many privileged programs. +Don't make the problem worse. +The only new features that should be associated with +.B CAP_SYS_ADMIN +are ones that +.I closely +match existing uses in that silo. +.IP * +If you have determined that it really is necessary to create +a new capability for your feature, +don't make or name it as a "single-use" capability. +Thus, for example, the addition of the highly specific +.BR CAP_SYS_PACCT +was probably a mistake. +Instead, try to identify and name your new capability as a broader +silo into which other related future use cases might fit. +.\" +.SS Thread capability sets +Each thread has three capability sets containing zero or more +of the above capabilities: +.TP +.IR Permitted : +This is a limiting superset for the effective +capabilities that the thread may assume. +It is also a limiting superset for the capabilities that +may be added to the inheritable set by a thread that does not have the +.B CAP_SETPCAP +capability in its effective set. +.IP +If a thread drops a capability from its permitted set, +it can never reacquire that capability (unless it +.BR execve (2)s +either a set-user-ID-root program, or +a program whose associated file capabilities grant that capability). +.TP +.IR Inheritable : +This is a set of capabilities preserved across an +.BR execve (2). +Inheritable capabilities remain inheritable when executing any program, +and inheritable capabilities are added to the permitted set when executing +a program that has the corresponding bits set in the file inheritable set. +.IP +Because inheritable capabilities are not generally preserved across +.BR execve (2) +when running as a non-root user, applications that wish to run helper +programs with elevated capabilities should consider using +ambient capabilities, described below. +.TP +.IR Effective : +This is the set of capabilities used by the kernel to +perform permission checks for the thread. +.TP +.IR Ambient " (since Linux 4.3):" +.\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08 +This is a set of capabilities that are preserved across an +.BR execve (2) +of a program that is not privileged. +The ambient capability set obeys the invariant that no capability +can ever be ambient if it is not both permitted and inheritable. +.IP +The ambient capability set can be directly modified using +.BR prctl (2). +Ambient capabilities are automatically lowered if either of +the corresponding permitted or inheritable capabilities is lowered. +.IP +Executing a program that changes UID or GID due to the +set-user-ID or set-group-ID bits or executing a program that has +any file capabilities set will clear the ambient set. +Ambient capabilities are added to the permitted set and +assigned to the effective set when +.BR execve (2) +is called. +.PP +A child created via +.BR fork (2) +inherits copies of its parent's capability sets. +See below for a discussion of the treatment of capabilities during +.BR execve (2). +.PP +Using +.BR capset (2), +a thread may manipulate its own capability sets (see below). +.PP +Since Linux 3.2, the file +.I /proc/sys/kernel/cap_last_cap +.\" commit 73efc0394e148d0e15583e13712637831f926720 +exposes the numerical value of the highest capability +supported by the running kernel; +this can be used to determine the highest bit +that may be set in a capability set. +.\" +.SS File capabilities +Since kernel 2.6.24, the kernel supports +associating capability sets with an executable file using +.BR setcap (8). +The file capability sets are stored in an extended attribute (see +.BR setxattr (2) +and +.BR xattr (7)) +named +.IR "security.capability" . +Writing to this extended attribute requires the +.BR CAP_SETFCAP +capability. +The file capability sets, +in conjunction with the capability sets of the thread, +determine the capabilities of a thread after an +.BR execve (2). +.PP +The three file capability sets are: +.TP +.IR Permitted " (formerly known as " forced ): +These capabilities are automatically permitted to the thread, +regardless of the thread's inheritable capabilities. +.TP +.IR Inheritable " (formerly known as " allowed ): +This set is ANDed with the thread's inheritable set to determine which +inheritable capabilities are enabled in the permitted set of +the thread after the +.BR execve (2). +.TP +.IR Effective : +This is not a set, but rather just a single bit. +If this bit is set, then during an +.BR execve (2) +all of the new permitted capabilities for the thread are +also raised in the effective set. +If this bit is not set, then after an +.BR execve (2), +none of the new permitted capabilities is in the new effective set. +.IP +Enabling the file effective capability bit implies +that any file permitted or inheritable capability that causes a +thread to acquire the corresponding permitted capability during an +.BR execve (2) +(see the transformation rules described below) will also acquire that +capability in its effective set. +Therefore, when assigning capabilities to a file +.RB ( setcap (8), +.BR cap_set_file (3), +.BR cap_set_fd (3)), +if we specify the effective flag as being enabled for any capability, +then the effective flag must also be specified as enabled +for all other capabilities for which the corresponding permitted or +inheritable flags is enabled. +.\" +.SS Transformation of capabilities during execve() +.PP +During an +.BR execve (2), +the kernel calculates the new capabilities of +the process using the following algorithm: +.PP +.in +4n +.EX +P'(ambient) = (file is privileged) ? 0 : P(ambient) + +P'(permitted) = (P(inheritable) & F(inheritable)) | + (F(permitted) & cap_bset) | P'(ambient) + +P'(effective) = F(effective) ? P'(permitted) : P'(ambient) + +P'(inheritable) = P(inheritable) [i.e., unchanged] +.EE +.in +.PP +where: +.RS 4 +.IP P 10 +denotes the value of a thread capability set before the +.BR execve (2) +.IP P' +denotes the value of a thread capability set after the +.BR execve (2) +.IP F +denotes a file capability set +.IP cap_bset +is the value of the capability bounding set (described below). +.RE +.PP +A privileged file is one that has capabilities or +has the set-user-ID or set-group-ID bit set. +.PP +.IR Note : +the capability transitions described above may +.I not +be performed (i.e., file capabilities may be ignored) for the same reasons +that the set-user-ID and set-group-ID bits are ignored; see +.BR execve (2). +.PP +.IR Note : +according to the rules above, +if a process with nonzero user IDs performs an +.BR execve (2) +then any capabilities that are present in +its permitted and effective sets will be cleared. +For the treatment of capabilities when a process with a +user ID of zero performs an +.BR execve (2), +see below under +.IR "Capabilities and execution of programs by root" . +.\" +.SS Safety checking for capability-dumb binaries +A capability-dumb binary is an application that has been +marked to have file capabilities, but has not been converted to use the +.BR libcap (3) +API to manipulate its capabilities. +(In other words, this is a traditional set-user-ID-root program +that has been switched to use file capabilities, +but whose code has not been modified to understand capabilities.) +For such applications, +the effective capability bit is set on the file, +so that the file permitted capabilities are automatically +enabled in the process effective set when executing the file. +The kernel recognizes a file which has the effective capability bit set +as capability-dumb for the purpose of the check described here. +.PP +When executing a capability-dumb binary, +the kernel checks if the process obtained all permitted capabilities +that were specified in the file permitted set, +after the capability transformations described above have been performed. +(The typical reason why this might +.I not +occur is that the capability bounding set masked out some +of the capabilities in the file permitted set.) +If the process did not obtain the full set of +file permitted capabilities, then +.BR execve (2) +fails with the error +.BR EPERM . +This prevents possible security risks that could arise when +a capability-dumb application is executed with less privilege that it needs. +Note that, by definition, +the application could not itself recognize this problem, +since it does not employ the +.BR libcap (3) +API. +.\" +.SS Capabilities and execution of programs by root +In order to provide an all-powerful +.I root +using capability sets, during an +.BR execve (2): +.IP 1. 3 +If a set-user-ID-root program is being executed, +or the real or effective user ID of the process is 0 (root) +then the file inheritable and permitted sets are defined to be all ones +(i.e., all capabilities enabled). +.IP 2. +If a set-user-ID-root program is being executed, +or the effective user ID of the process is 0 (root) +then the file effective bit is defined to be one (enabled). +.PP +The upshot of the above rules, +combined with the capabilities transformations described above, +is as follows: +.IP * 3 +When a process +.BR execve (2)s +a set-user-ID-root program, or when a process with an effective UID of 0 +.BR execve (2)s +a program, +it gains all capabilities in its permitted and effective capability sets, +except those masked out by the capability bounding set. +.IP * +When a process with a real UID of 0 +.BR execve (2)s +a program, +it gains all capabilities in its permitted capability set, +.\" but no effective capabilities +except those masked out by the capability bounding set. +.PP +The above steps yield semantics that are the same as those provided by +traditional UNIX systems. +.\" +.SS Set-user-ID-root programs that have file capabilities +Executing a program that is both set-user-ID root and has +file capabilities will cause the process to gain just the +capabilities granted by the program +(i.e., not all capabilities, +as would occur when executing a set-user-ID-root program +that does not have any associated file capabilities). +Note that one can assign empty capability sets to a program file, +and thus it is possible to create a set-user-ID-root program that +changes the effective and saved set-user-ID of the process +that executes the program to 0, +but confers no capabilities to that process. +.\" +.SS Capability bounding set +The capability bounding set is a security mechanism that can be used +to limit the capabilities that can be gained during an +.BR execve (2). +The bounding set is used in the following ways: +.IP * 2 +During an +.BR execve (2), +the capability bounding set is ANDed with the file permitted +capability set, and the result of this operation is assigned to the +thread's permitted capability set. +The capability bounding set thus places a limit on the permitted +capabilities that may be granted by an executable file. +.IP * +(Since Linux 2.6.25) +The capability bounding set acts as a limiting superset for +the capabilities that a thread can add to its inheritable set using +.BR capset (2). +This means that if a capability is not in the bounding set, +then a thread can't add this capability to its +inheritable set, even if it was in its permitted capabilities, +and thereby cannot have this capability preserved in its +permitted set when it +.BR execve (2)s +a file that has the capability in its inheritable set. +.PP +Note that the bounding set masks the file permitted capabilities, +but not the inheritable capabilities. +If a thread maintains a capability in its inheritable set +that is not in its bounding set, +then it can still gain that capability in its permitted set +by executing a file that has the capability in its inheritable set. +.PP +Depending on the kernel version, the capability bounding set is either +a system-wide attribute, or a per-process attribute. +.PP +.B "Capability bounding set prior to Linux 2.6.25" +.PP +In kernels before 2.6.25, the capability bounding set is a system-wide +attribute that affects all threads on the system. +The bounding set is accessible via the file +.IR /proc/sys/kernel/cap-bound . +(Confusingly, this bit mask parameter is expressed as a +signed decimal number in +.IR /proc/sys/kernel/cap-bound .) +.PP +Only the +.B init +process may set capabilities in the capability bounding set; +other than that, the superuser (more precisely: a process with the +.B CAP_SYS_MODULE +capability) may only clear capabilities from this set. +.PP +On a standard system the capability bounding set always masks out the +.B CAP_SETPCAP +capability. +To remove this restriction (dangerous!), modify the definition of +.B CAP_INIT_EFF_SET +in +.I include/linux/capability.h +and rebuild the kernel. +.PP +The system-wide capability bounding set feature was added +to Linux starting with kernel version 2.2.11. +.\" +.PP +.B "Capability bounding set from Linux 2.6.25 onward" +.PP +From Linux 2.6.25, the +.I "capability bounding set" +is a per-thread attribute. +(There is no longer a system-wide capability bounding set.) +.PP +The bounding set is inherited at +.BR fork (2) +from the thread's parent, and is preserved across an +.BR execve (2). +.PP +A thread may remove capabilities from its capability bounding set using the +.BR prctl (2) +.B PR_CAPBSET_DROP +operation, provided it has the +.B CAP_SETPCAP +capability. +Once a capability has been dropped from the bounding set, +it cannot be restored to that set. +A thread can determine if a capability is in its bounding set using the +.BR prctl (2) +.B PR_CAPBSET_READ +operation. +.PP +Removing capabilities from the bounding set is supported only if file +capabilities are compiled into the kernel. +In kernels before Linux 2.6.33, +file capabilities were an optional feature configurable via the +.B CONFIG_SECURITY_FILE_CAPABILITIES +option. +Since Linux 2.6.33, +.\" commit b3a222e52e4d4be77cc4520a57af1a4a0d8222d1 +the configuration option has been removed +and file capabilities are always part of the kernel. +When file capabilities are compiled into the kernel, the +.B init +process (the ancestor of all processes) begins with a full bounding set. +If file capabilities are not compiled into the kernel, then +.B init +begins with a full bounding set minus +.BR CAP_SETPCAP , +because this capability has a different meaning when there are +no file capabilities. +.PP +Removing a capability from the bounding set does not remove it +from the thread's inheritable set. +However it does prevent the capability from being added +back into the thread's inheritable set in the future. +.\" +.\" +.SS Effect of user ID changes on capabilities +To preserve the traditional semantics for transitions between +0 and nonzero user IDs, +the kernel makes the following changes to a thread's capability +sets on changes to the thread's real, effective, saved set, +and filesystem user IDs (using +.BR setuid (2), +.BR setresuid (2), +or similar): +.IP 1. 3 +If one or more of the real, effective or saved set user IDs +was previously 0, and as a result of the UID changes all of these IDs +have a nonzero value, +then all capabilities are cleared from the permitted, effective, and ambient +capability sets. +.IP 2. +If the effective user ID is changed from 0 to nonzero, +then all capabilities are cleared from the effective set. +.IP 3. +If the effective user ID is changed from nonzero to 0, +then the permitted set is copied to the effective set. +.IP 4. +If the filesystem user ID is changed from 0 to nonzero (see +.BR setfsuid (2)), +then the following capabilities are cleared from the effective set: +.BR CAP_CHOWN , +.BR CAP_DAC_OVERRIDE , +.BR CAP_DAC_READ_SEARCH , +.BR CAP_FOWNER , +.BR CAP_FSETID , +.B CAP_LINUX_IMMUTABLE +(since Linux 2.6.30), +.BR CAP_MAC_OVERRIDE , +and +.B CAP_MKNOD +(since Linux 2.6.30). +If the filesystem UID is changed from nonzero to 0, +then any of these capabilities that are enabled in the permitted set +are enabled in the effective set. +.PP +If a thread that has a 0 value for one or more of its user IDs wants +to prevent its permitted capability set being cleared when it resets +all of its user IDs to nonzero values, it can do so using the +.B SECBIT_KEEP_CAPS +securebits flag described below. +.\" +.SS Programmatically adjusting capability sets +A thread can retrieve and change its capability sets using the +.BR capget (2) +and +.BR capset (2) +system calls. +However, the use of +.BR cap_get_proc (3) +and +.BR cap_set_proc (3), +both provided in the +.I libcap +package, +is preferred for this purpose. +The following rules govern changes to the thread capability sets: +.IP 1. 3 +If the caller does not have the +.B CAP_SETPCAP +capability, +the new inheritable set must be a subset of the combination +of the existing inheritable and permitted sets. +.IP 2. +(Since Linux 2.6.25) +The new inheritable set must be a subset of the combination of the +existing inheritable set and the capability bounding set. +.IP 3. +The new permitted set must be a subset of the existing permitted set +(i.e., it is not possible to acquire permitted capabilities +that the thread does not currently have). +.IP 4. +The new effective set must be a subset of the new permitted set. +.SS The securebits flags: establishing a capabilities-only environment +.\" For some background: +.\" see http://lwn.net/Articles/280279/ and +.\" http://article.gmane.org/gmane.linux.kernel.lsm/5476/ +Starting with kernel 2.6.26, +and with a kernel in which file capabilities are enabled, +Linux implements a set of per-thread +.I securebits +flags that can be used to disable special handling of capabilities for UID 0 +.RI ( root ). +These flags are as follows: +.TP +.B SECBIT_KEEP_CAPS +Setting this flag allows a thread that has one or more 0 UIDs to retain +capabilities in its permitted and effective sets +when it switches all of its UIDs to nonzero values. +If this flag is not set, +then such a UID switch causes the thread to lose all capabilities +in those sets. +This flag is always cleared on an +.BR execve (2). +.IP +The setting of the +.B SECBIT_KEEP_CAPS +flag is ignored if the +.B SECBIT_NO_SETUID_FIXUP +flag is set. +(The latter flag provides a superset of the effect of the former flag.) +.IP +This flag provides the same functionality as the older +.BR prctl (2) +.B PR_SET_KEEPCAPS +operation. +.TP +.B SECBIT_NO_SETUID_FIXUP +Setting this flag stops the kernel from adjusting the process's +permitted, effective, and ambient capability sets when +the thread's effective and filesystem UIDs are switched between +zero and nonzero values. +(See the subsection +.IR "Effect of user ID changes on capabilities" .) +.TP +.B SECBIT_NOROOT +If this bit is set, then the kernel does not grant capabilities +when a set-user-ID-root program is executed, or when a process with +an effective or real UID of 0 calls +.BR execve (2). +(See the subsection +.IR "Capabilities and execution of programs by root" .) +.TP +.B SECBIT_NO_CAP_AMBIENT_RAISE +Setting this flag disallows raising ambient capabilities via the +.BR prctl (2) +.BR PR_CAP_AMBIENT_RAISE +operation. +.PP +Each of the above "base" flags has a companion "locked" flag. +Setting any of the "locked" flags is irreversible, +and has the effect of preventing further changes to the +corresponding "base" flag. +The locked flags are: +.BR SECBIT_KEEP_CAPS_LOCKED , +.BR SECBIT_NO_SETUID_FIXUP_LOCKED , +.BR SECBIT_NOROOT_LOCKED , +and +.BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED . +.PP +The +.I securebits +flags can be modified and retrieved using the +.BR prctl (2) +.B PR_SET_SECUREBITS +and +.B PR_GET_SECUREBITS +operations. +The +.B CAP_SETPCAP +capability is required to modify the flags. +.PP +The +.I securebits +flags are inherited by child processes. +During an +.BR execve (2), +all of the flags are preserved, except +.B SECBIT_KEEP_CAPS +which is always cleared. +.PP +An application can use the following call to lock itself, +and all of its descendants, +into an environment where the only way of gaining capabilities +is by executing a program with associated file capabilities: +.PP +.in +4n +.EX +prctl(PR_SET_SECUREBITS, + /* SECBIT_KEEP_CAPS off */ + SECBIT_KEEP_CAPS_LOCKED | + SECBIT_NO_SETUID_FIXUP | + SECBIT_NO_SETUID_FIXUP_LOCKED | + SECBIT_NOROOT | + SECBIT_NOROOT_LOCKED); + /* Setting/locking SECBIT_NO_CAP_AMBIENT_RAISE + is not required */ +.EE +.in +.SS Interaction with user namespaces +For a discussion of the interaction of capabilities and user namespaces, see +.BR user_namespaces (7). +.SH CONFORMING TO +.PP +No standards govern capabilities, but the Linux capability implementation +is based on the withdrawn POSIX.1e draft standard; see +.UR http://wt.tuxomania.net\:/publications\:/posix.1e/ +.UE . +.SH NOTES +From kernel 2.5.27 to kernel 2.6.26, +.\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed +.\" CONFIG_SECURITY_CAPABILITIES +capabilities were an optional kernel component, +and could be enabled/disabled via the +.B CONFIG_SECURITY_CAPABILITIES +kernel configuration option. +.PP +The +.I /proc/[pid]/task/TID/status +file can be used to view the capability sets of a thread. +The +.I /proc/[pid]/status +file shows the capability sets of a process's main thread. +Before Linux 3.8, nonexistent capabilities were shown as being +enabled (1) in these sets. +Since Linux 3.8, +.\" 7b9a7ec565505699f503b4fcf61500dceb36e744 +all nonexistent capabilities (above +.BR CAP_LAST_CAP ) +are shown as disabled (0). +.PP +The +.I libcap +package provides a suite of routines for setting and +getting capabilities that is more comfortable and less likely +to change than the interface provided by +.BR capset (2) +and +.BR capget (2). +This package also provides the +.BR setcap (8) +and +.BR getcap (8) +programs. +It can be found at +.br +.UR http://www.kernel.org\:/pub\:/linux\:/libs\:/security\:/linux\-privs +.UE . +.PP +Before kernel 2.6.24, and from kernel 2.6.24 to kernel 2.6.32 if +file capabilities are not enabled, a thread with the +.B CAP_SETPCAP +capability can manipulate the capabilities of threads other than itself. +However, this is only theoretically possible, +since no thread ever has +.BR CAP_SETPCAP +in either of these cases: +.IP * 2 +In the pre-2.6.25 implementation the system-wide capability bounding set, +.IR /proc/sys/kernel/cap-bound , +always masks out this capability, and this can not be changed +without modifying the kernel source and rebuilding. +.IP * +If file capabilities are disabled in the current implementation, then +.B init +starts out with this capability removed from its per-process bounding +set, and that bounding set is inherited by all other processes +created on the system. +.SH SEE ALSO +.BR capsh (1), +.BR setpriv (1), +.BR prctl (2), +.BR setfsuid (2), +.BR cap_clear (3), +.BR cap_copy_ext (3), +.BR cap_from_text (3), +.BR cap_get_file (3), +.BR cap_get_proc (3), +.BR cap_init (3), +.BR capgetp (3), +.BR capsetp (3), +.BR libcap (3), +.BR proc (5), +.BR credentials (7), +.BR pthreads (7), +.BR user_namespaces (7), +.BR captest (8), \" from libcap-ng +.BR filecap (8), \" from libcap-ng +.BR getcap (8), +.BR netcap (8), \" from libcap-ng +.BR pscap (8), \" from libcap-ng +.BR setcap (8) +.PP +.I include/linux/capability.h +in the Linux kernel source tree +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/cgroup_namespaces.7 b/man7/cgroup_namespaces.7 new file mode 100644 index 0000000..9529009 --- /dev/null +++ b/man7/cgroup_namespaces.7 @@ -0,0 +1,260 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH CGROUP_NAMESPACES 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +cgroup_namespaces \- overview of Linux cgroup namespaces +.SH DESCRIPTION +For an overview of namespaces, see +.BR namespaces (7). +.PP +Cgroup namespaces virtualize the view of a process's cgroups (see +.BR cgroups (7)) +as seen via +.IR /proc/[pid]/cgroup +and +.IR /proc/[pid]/mountinfo . +.PP +Each cgroup namespace has its own set of cgroup root directories. +These root directories are the base points for the relative +locations displayed in the corresponding records in the +.IR /proc/[pid]/cgroup +file. +When a process creates a new cgroup namespace using +.BR clone (2) +or +.BR unshare (2) +with the +.BR CLONE_NEWCGROUP +flag, it enters a new cgroup namespace in which its current +cgroups directories become the cgroup root directories +of the new namespace. +(This applies both for the cgroups version 1 hierarchies +and the cgroups version 2 unified hierarchy.) +.PP +When viewing +.IR /proc/[pid]/cgroup , +the pathname shown in the third field of each record will be +relative to the reading process's root directory +for the corresponding cgroup hierarchy. +If the cgroup directory of the target process lies outside +the root directory of the reading process's cgroup namespace, +then the pathname will show +.I ../ +entries for each ancestor level in the cgroup hierarchy. +.PP +The following shell session demonstrates the effect of creating +a new cgroup namespace. +First, (as superuser) we create a child cgroup in the +.I freezer +hierarchy, and put the shell into that cgroup: +.PP +.in +4n +.EX +# \fBmkdir \-p /sys/fs/cgroup/freezer/sub\fP +# \fBecho $$\fP # Show PID of this shell +30655 +# \fBsh \-c \(aqecho 30655 > /sys/fs/cgroup/freezer/sub/cgroup.procs\(aq\fP +# \fBcat /proc/self/cgroup | grep freezer\fP +7:freezer:/sub +.EE +.in +.PP +Next, we use +.BR unshare (1) +to create a process running a new shell in new cgroup and mount namespaces: +.PP +.EX +.in +4n +# \fBunshare \-Cm bash\fP +.in +.EE +.PP +We then inspect the +.IR /proc/[pid]/cgroup +files of, respectively, the new shell process started by the +.BR unshare (1) +command, a process that is in the original cgroup namespace +.RI ( init , +with PID 1), and a process in a sibling cgroup +.RI ( sub2 ): +.PP +.EX +.in +4n +$ \fBcat /proc/self/cgroup | grep freezer\fP +7:freezer:/ +$ \fBcat /proc/1/cgroup | grep freezer\fP +7:freezer:/.. +$ \fBcat /proc/20124/cgroup | grep freezer\fP +7:freezer:/../sub2 +.in +.EE +.PP +From the output of the first command, +we see that the freezer cgroup membership of the new shell +(which is in the same cgroup as the initial shell) +is shown defined relative to the freezer cgroup root directory +that was established when the new cgroup namespace was created. +(In absolute terms, +the new shell is in the +.I /sub +freezer cgroup, +and the root directory of the freezer cgroup hierarchy +in the new cgroup namespace is also +.IR /sub . +Thus, the new shell's cgroup membership is displayed as \(aq/\(aq.) +.PP +However, when we look in +.IR /proc/self/mountinfo +we see the following anomaly: +.PP +.EX +.in +4n +# \fBcat /proc/self/mountinfo | grep freezer\fP +155 145 0:32 /.. /sys/fs/cgroup/freezer ... +.in +.EE +.PP +The fourth field of this line +.RI ( /.. ) +should show the +directory in the cgroup filesystem which forms the root of this mount. +Since by the definition of cgroup namespaces, the process's current +freezer cgroup directory became its root freezer cgroup directory, +we should see \(aq/\(aq in this field. +The problem here is that we are seeing a mount entry for the cgroup +filesystem corresponding to our initial shell process's cgroup namespace +(whose cgroup filesystem is indeed rooted in the parent directory of +.IR sub ). +We need to remount the freezer cgroup filesystem +inside this cgroup namespace, after which we see the expected results: +.PP +.EX +.in +4n +# \fBmount \-\-make\-rslave /\fP # Don't propagate mount events + # to other namespaces +# \fBumount /sys/fs/cgroup/freezer\fP +# \fBmount \-t cgroup \-o freezer freezer /sys/fs/cgroup/freezer\fP +# \fBcat /proc/self/mountinfo | grep freezer\fP +155 145 0:32 / /sys/fs/cgroup/freezer rw,relatime ... +.in +.EE +.PP +Use of cgroup namespaces requires a kernel that is configured with the +.B CONFIG_CGROUPS +option. +.\" +.SH CONFORMING TO +Namespaces are a Linux-specific feature. +.SH NOTES +Among the purposes served by the +virtualization provided by cgroup namespaces are the following: +.IP * 2 +It prevents information leaks whereby cgroup directory paths outside of +a container would otherwise be visible to processes in the container. +Such leakages could, for example, +reveal information about the container framework +to containerized applications. +.IP * +It eases tasks such as container migration. +The virtualization provided by cgroup namespaces +allows containers to be isolated from knowledge of +the pathnames of ancestor cgroups. +Without such isolation, the full cgroup pathnames (displayed in +.IR /proc/self/cgroups ) +would need to be replicated on the target system when migrating a container; +those pathnames would also need to be unique, +so that they don't conflict with other pathnames on the target system. +.IP * +It allows better confinement of containerized processes, +because it is possible to mount the container's cgroup filesystems such that +the container processes can't gain access to ancestor cgroup directories. +Consider, for example, the following scenario: +.RS 4 +.IP \(bu 2 +We have a cgroup directory, +.IR /cg/1 , +that is owned by user ID 9000. +.IP \(bu +We have a process, +.IR X , +also owned by user ID 9000, +that is namespaced under the cgroup +.IR /cg/1/2 +(i.e., +.I X +was placed in a new cgroup namespace via +.BR clone (2) +or +.BR unshare (2) +with the +.BR CLONE_NEWCGROUP +flag). +.RE +.IP +In the absence of cgroup namespacing, because the cgroup directory +.IR /cg/1 +is owned (and writable) by UID 9000 and process +.I X +is also owned by user ID 9000, then process +.I X +would be able to modify the contents of cgroups files +(i.e., change cgroup settings) not only in +.IR /cg/1/2 +but also in the ancestor cgroup directory +.IR /cg/1 . +Namespacing process +.IR X +under the cgroup directory +.IR /cg/1/2 , +in combination with suitable mount operations +for the cgroup filesystem (as shown above), +prevents it modifying files in +.IR /cg/1 , +since it cannot even see the contents of that directory +(or of further removed cgroup ancestor directories). +Combined with correct enforcement of hierarchical limits, +this prevents process +.I X +from escaping the limits imposed by ancestor cgroups. +.SH SEE ALSO +.BR unshare (1), +.BR clone (2), +.BR setns (2), +.BR unshare (2), +.BR proc (5), +.BR cgroups (7), +.BR credentials (7), +.BR namespaces (7), +.BR user_namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/cgroups.7 b/man7/cgroups.7 new file mode 100644 index 0000000..8e9b19d --- /dev/null +++ b/man7/cgroups.7 @@ -0,0 +1,1733 @@ +.\" Copyright (C) 2015 Serge Hallyn +.\" and Copyright (C) 2016, 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH CGROUPS 7 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +cgroups \- Linux control groups +.SH DESCRIPTION +Control cgroups, usually referred to as cgroups, +are a Linux kernel feature which allow processes to +be organized into hierarchical groups whose usage of +various types of resources can then be limited and monitored. +The kernel's cgroup interface is provided through +a pseudo-filesystem called cgroupfs. +Grouping is implemented in the core cgroup kernel code, +while resource tracking and limits are implemented in +a set of per-resource-type subsystems (memory, CPU, and so on). +.\" +.SS Terminology +A +.I cgroup +is a collection of processes that are bound to a set of +limits or parameters defined via the cgroup filesystem. +.PP +A +.I subsystem +is a kernel component that modifies the behavior of +the processes in a cgroup. +Various subsystems have been implemented, making it possible to do things +such as limiting the amount of CPU time and memory available to a cgroup, +accounting for the CPU time used by a cgroup, +and freezing and resuming execution of the processes in a cgroup. +Subsystems are sometimes also known as +.IR "resource controllers" +(or simply, controllers). +.PP +The cgroups for a controller are arranged in a +.IR hierarchy . +This hierarchy is defined by creating, removing, and +renaming subdirectories within the cgroup filesystem. +At each level of the hierarchy, attributes (e.g., limits) can be defined. +The limits, control, and accounting provided by cgroups generally have +effect throughout the subhierarchy underneath the cgroup where the +attributes are defined. +Thus, for example, the limits placed on +a cgroup at a higher level in the hierarchy cannot be exceeded +by descendant cgroups. +.\" +.SS Cgroups version 1 and version 2 +The initial release of the cgroups implementation was in Linux 2.6.24. +Over time, various cgroup controllers have been added +to allow the management of various types of resources. +However, the development of these controllers was largely uncoordinated, +with the result that many inconsistencies arose between controllers +and management of the cgroup hierarchies became rather complex. +(A longer description of these problems can be found in +the kernel source file +.IR Documentation/cgroup\-v2.txt .) +.PP +Because of the problems with the initial cgroups implementation +(cgroups version 1), +starting in Linux 3.10, work began on a new, +orthogonal implementation to remedy these problems. +Initially marked experimental, and hidden behind the +.I "\-o\ __DEVEL__sane_behavior" +mount option, the new version (cgroups version 2) +was eventually made official with the release of Linux 4.5. +Differences between the two versions are described in the text below. +.PP +Although cgroups v2 is intended as a replacement for cgroups v1, +the older system continues to exist +(and for compatibility reasons is unlikely to be removed). +Currently, cgroups v2 implements only a subset of the controllers +available in cgroups v1. +The two systems are implemented so that both v1 controllers and +v2 controllers can be mounted on the same system. +Thus, for example, it is possible to use those controllers +that are supported under version 2, +while also using version 1 controllers +where version 2 does not yet support those controllers. +The only restriction here is that a controller can't be simultaneously +employed in both a cgroups v1 hierarchy and in the cgroups v2 hierarchy. +.\" +.SH CGROUPS VERSION 1 +Under cgroups v1, each controller may be mounted against a separate +cgroup filesystem that provides its own hierarchical organization of the +processes on the system. +It is also possible to comount multiple (or even all) cgroups v1 controllers +against the same cgroup filesystem, meaning that the comounted controllers +manage the same hierarchical organization of processes. +.PP +For each mounted hierarchy, +the directory tree mirrors the control group hierarchy. +Each control group is represented by a directory, with each of its child +control cgroups represented as a child directory. +For instance, +.IR /user/joe/1.session +represents control group +.IR 1.session , +which is a child of cgroup +.IR joe , +which is a child of +.IR /user . +Under each cgroup directory is a set of files which can be read or +written to, reflecting resource limits and a few general cgroup +properties. +.\" +.SS Tasks (threads) versus processes +In cgroups v1, a distinction is drawn between +.I processes +and +.IR tasks . +In this view, a process can consist of multiple tasks +(more commonly called threads, from a user-space perspective, +and called such in the remainder of this man page). +In cgroups v1, it is possible to independently manipulate +the cgroup memberships of the threads in a process. +.PP +The cgroups v1 ability to split threads across different cgroups +caused problems in some cases. +For example, it made no sense for the +.I memory +controller, +since all of the threads of a process share a single address space. +Because of these problems, +the ability to independently manipulate the cgroup memberships +of the threads in a process was removed in the initial cgroups v2 +implementation, and subsequently restored in a more limited form +(see the discussion of "thread mode" below). +.\" +.SS Mounting v1 controllers +The use of cgroups requires a kernel built with the +.BR CONFIG_CGROUP +option. +In addition, each of the v1 controllers has an associated +configuration option that must be set in order to employ that controller. +.PP +In order to use a v1 controller, +it must be mounted against a cgroup filesystem. +The usual place for such mounts is under a +.BR tmpfs (5) +filesystem mounted at +.IR /sys/fs/cgroup . +Thus, one might mount the +.I cpu +controller as follows: +.PP +.in +4n +.EX +mount \-t cgroup \-o cpu none /sys/fs/cgroup/cpu +.EE +.in +.PP +It is possible to comount multiple controllers against the same hierarchy. +For example, here the +.IR cpu +and +.IR cpuacct +controllers are comounted against a single hierarchy: +.PP +.in +4n +.EX +mount \-t cgroup \-o cpu,cpuacct none /sys/fs/cgroup/cpu,cpuacct +.EE +.in +.PP +Comounting controllers has the effect that a process is in the same cgroup for +all of the comounted controllers. +Separately mounting controllers allows a process to +be in cgroup +.I /foo1 +for one controller while being in +.I /foo2/foo3 +for another. +.PP +It is possible to comount all v1 controllers against the same hierarchy: +.PP +.in +4n +.EX +mount \-t cgroup \-o all cgroup /sys/fs/cgroup +.EE +.in +.PP +(One can achieve the same result by omitting +.IR "\-o all" , +since it is the default if no controllers are explicitly specified.) +.PP +It is not possible to mount the same controller +against multiple cgroup hierarchies. +For example, it is not possible to mount both the +.I cpu +and +.I cpuacct +controllers against one hierarchy, and to mount the +.I cpu +controller alone against another hierarchy. +It is possible to create multiple mount points with exactly +the same set of comounted controllers. +However, in this case all that results is multiple mount points +providing a view of the same hierarchy. +.PP +Note that on many systems, the v1 controllers are automatically mounted under +.IR /sys/fs/cgroup ; +in particular, +.BR systemd (1) +automatically creates such mount points. +.\" +.SS Unmounting v1 controllers +A mounted cgroup filesystem can be unmounted using the +.BR umount (8) +command, as in the following example: +.PP +.in +4n +.EX +umount /sys/fs/cgroup/pids +.EE +.in +.PP +.IR "But note well" : +a cgroup filesystem is unmounted only if it is not busy, +that is, it has no child cgroups. +If this is not the case, then the only effect of the +.BR umount (8) +is to make the mount invisible. +Thus, to ensure that the mount point is really removed, +one must first remove all child cgroups, +which in turn can be done only after all member processes +have been moved from those cgroups to the root cgroup. +.\" +.SS Cgroups version 1 controllers +Each of the cgroups version 1 controllers is governed +by a kernel configuration option (listed below). +Additionally, the availability of the cgroups feature is governed by the +.BR CONFIG_CGROUPS +kernel configuration option. +.TP +.IR cpu " (since Linux 2.6.24; " \fBCONFIG_CGROUP_SCHED\fP ) +Cgroups can be guaranteed a minimum number of "CPU shares" +when a system is busy. +This does not limit a cgroup's CPU usage if the CPUs are not busy. +For further information, see +.IR Documentation/scheduler/sched-design-CFS.txt . +.IP +In Linux 3.2, +this controller was extended to provide CPU "bandwidth" control. +If the kernel is configured with +.BR CONFIG_CFS_BANDWIDTH , +then within each scheduling period +(defined via a file in the cgroup directory), it is possible to define +an upper limit on the CPU time allocated to the processes in a cgroup. +This upper limit applies even if there is no other competition for the CPU. +Further information can be found in the kernel source file +.IR Documentation/scheduler/sched\-bwc.txt . +.TP +.IR cpuacct " (since Linux 2.6.24; " \fBCONFIG_CGROUP_CPUACCT\fP ) +This provides accounting for CPU usage by groups of processes. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup\-v1/cpuacct.txt . +.TP +.IR cpuset " (since Linux 2.6.24; " \fBCONFIG_CPUSETS\fP ) +This cgroup can be used to bind the processes in a cgroup to +a specified set of CPUs and NUMA nodes. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup\-v1/cpusets.txt . +.TP +.IR memory " (since Linux 2.6.25; " \fBCONFIG_MEMCG\fP ) +The memory controller supports reporting and limiting of process memory, kernel +memory, and swap used by cgroups. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup\-v1/memory.txt . +.TP +.IR devices " (since Linux 2.6.26; " \fBCONFIG_CGROUP_DEVICE\fP ) +This supports controlling which processes may create (mknod) devices as +well as open them for reading or writing. +The policies may be specified as whitelists and blacklists. +Hierarchy is enforced, so new rules must not +violate existing rules for the target or ancestor cgroups. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup-v1/devices.txt . +.TP +.IR freezer " (since Linux 2.6.28; " \fBCONFIG_CGROUP_FREEZER\fP ) +The +.IR freezer +cgroup can suspend and restore (resume) all processes in a cgroup. +Freezing a cgroup +.I /A +also causes its children, for example, processes in +.IR /A/B , +to be frozen. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup-v1/freezer-subsystem.txt . +.TP +.IR net_cls " (since Linux 2.6.29; " \fBCONFIG_CGROUP_NET_CLASSID\fP ) +This places a classid, specified for the cgroup, on network packets +created by a cgroup. +These classids can then be used in firewall rules, +as well as used to shape traffic using +.BR tc (8). +This applies only to packets +leaving the cgroup, not to traffic arriving at the cgroup. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup-v1/net_cls.txt . +.TP +.IR blkio " (since Linux 2.6.33; " \fBCONFIG_BLK_CGROUP\fP ) +The +.I blkio +cgroup controls and limits access to specified block devices by +applying IO control in the form of throttling and upper limits against leaf +nodes and intermediate nodes in the storage hierarchy. +.IP +Two policies are available. +The first is a proportional-weight time-based division +of disk implemented with CFQ. +This is in effect for leaf nodes using CFQ. +The second is a throttling policy which specifies +upper I/O rate limits on a device. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup-v1/blkio-controller.txt . +.TP +.IR perf_event " (since Linux 2.6.39; " \fBCONFIG_CGROUP_PERF\fP ) +This controller allows +.I perf +monitoring of the set of processes grouped in a cgroup. +.IP +Further information can be found in the kernel source file +.IR tools/perf/Documentation/perf-record.txt . +.TP +.IR net_prio " (since Linux 3.3; " \fBCONFIG_CGROUP_NET_PRIO\fP ) +This allows priorities to be specified, per network interface, for cgroups. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup-v1/net_prio.txt . +.TP +.IR hugetlb " (since Linux 3.5; " \fBCONFIG_CGROUP_HUGETLB\fP ) +This supports limiting the use of huge pages by cgroups. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup-v1/hugetlb.txt . +.TP +.IR pids " (since Linux 4.3; " \fBCONFIG_CGROUP_PIDS\fP ) +This controller permits limiting the number of process that may be created +in a cgroup (and its descendants). +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup-v1/pids.txt . +.TP +.IR rdma " (since Linux 4.11; " \fBCONFIG_CGROUP_RDMA\fP ) +The RDMA controller permits limiting the use of +RDMA/IB-specific resources per cgroup. +.IP +Further information can be found in the kernel source file +.IR Documentation/cgroup-v1/rdma.txt . +.\" +.SS Creating cgroups and moving processes +A cgroup filesystem initially contains a single root cgroup, '/', +which all processes belong to. +A new cgroup is created by creating a directory in the cgroup filesystem: +.PP +.in +4n +.EX +mkdir /sys/fs/cgroup/cpu/cg1 +.EE +.in +.PP +This creates a new empty cgroup. +.PP +A process may be moved to this cgroup by writing its PID into the cgroup's +.I cgroup.procs +file: +.PP +.in +4n +.EX +echo $$ > /sys/fs/cgroup/cpu/cg1/cgroup.procs +.EE +.in +.PP +Only one PID at a time should be written to this file. +.PP +Writing the value 0 to a +.IR cgroup.procs +file causes the writing process to be moved to the corresponding cgroup. +.PP +When writing a PID into the +.IR cgroup.procs , +all threads in the process are moved into the new cgroup at once. +.PP +Within a hierarchy, a process can be a member of exactly one cgroup. +Writing a process's PID to a +.IR cgroup.procs +file automatically removes it from the cgroup of +which it was previously a member. +.PP +The +.I cgroup.procs +file can be read to obtain a list of the processes that are +members of a cgroup. +The returned list of PIDs is not guaranteed to be in order. +Nor is it guaranteed to be free of duplicates. +(For example, a PID may be recycled while reading from the list.) +.PP +In cgroups v1, an individual thread can be moved to +another cgroup by writing its thread ID +(i.e., the kernel thread ID returned by +.BR clone (2) +and +.BR gettid (2)) +to the +.IR tasks +file in a cgroup directory. +This file can be read to discover the set of threads +that are members of the cgroup. +.\" +.SS Removing cgroups +To remove a cgroup, +it must first have no child cgroups and contain no (nonzombie) processes. +So long as that is the case, one can simply +remove the corresponding directory pathname. +Note that files in a cgroup directory cannot and need not be +removed. +.\" +.SS Cgroups v1 release notification +Two files can be used to determine whether the kernel provides +notifications when a cgroup becomes empty. +A cgroup is considered to be empty when it contains no child +cgroups and no member processes. +.PP +A special file in the root directory of each cgroup hierarchy, +.IR release_agent , +can be used to register the pathname of a program that may be invoked when +a cgroup in the hierarchy becomes empty. +The pathname of the newly empty cgroup (relative to the cgroup mount point) +is provided as the sole command-line argument when the +.IR release_agent +program is invoked. +The +.IR release_agent +program might remove the cgroup directory, +or perhaps repopulate it with a process. +.PP +The default value of the +.IR release_agent +file is empty, meaning that no release agent is invoked. +.PP +The content of the +.I release_agent +file can also be specified via a mount option when the +cgroup filesystem is mounted: +.PP +.in +4n +.EX +mount -o release_agent=pathname ... +.EE +.in +.PP +Whether or not the +.IR release_agent +program is invoked when a particular cgroup becomes empty is determined +by the value in the +.IR notify_on_release +file in the corresponding cgroup directory. +If this file contains the value 0, then the +.IR release_agent +program is not invoked. +If it contains the value 1, the +.IR release_agent +program is invoked. +The default value for this file in the root cgroup is 0. +At the time when a new cgroup is created, +the value in this file is inherited from the corresponding file +in the parent cgroup. +.\" +.SS Cgroup v1 named hierarchies +In cgroups v1, +it is possible to mount a cgroup hierarchy that has no attached controllers: +.PP +.in +4n +.EX +mount -t cgroup -o none,name=somename none /some/mount/point +.EE +.in +.PP +Multiple instances of such hierarchies can be mounted; +each hierarchy must have a unique name. +The only purpose of such hierarchies is to track processes. +(See the discussion of release notification below.) +An example of this is the +.I name=systemd +cgroup hierarchy that is used by +.BR systemd (1) +to track services and user sessions. +.\" +.SH CGROUPS VERSION 2 +In cgroups v2, +all mounted controllers reside in a single unified hierarchy. +While (different) controllers may be simultaneously +mounted under the v1 and v2 hierarchies, +it is not possible to mount the same controller simultaneously +under both the v1 and the v2 hierarchies. +.PP +The new behaviors in cgroups v2 are summarized here, +and in some cases elaborated in the following subsections. +.IP 1. 3 +Cgroups v2 provides a unified hierarchy against +which all controllers are mounted. +.IP 2. +"Internal" processes are not permitted. +With the exception of the root cgroup, processes may reside +only in leaf nodes (cgroups that do not themselves contain child cgroups). +The details are somewhat more subtle than this, and are described below. +.IP 3. +Active cgroups must be specified via the files +.IR cgroup.controllers +and +.IR cgroup.subtree_control . +.IP 4. +The +.I tasks +file has been removed. +In addition, the +.I cgroup.clone_children +file that is employed by the +.I cpuset +controller has been removed. +.IP 5. +An improved mechanism for notification of empty cgroups is provided by the +.IR cgroup.events +file. +.PP +For more changes, see the +.I Documentation/cgroup-v2.txt +file in the kernel source. +.PP +Some of the new behaviors listed above saw subsequent modification with +the addition in Linux 4.14 of "thread mode" (described below). +.\" +.SS Cgroups v2 unified hierarchy +In cgroups v1, the ability to mount different controllers +against different hierarchies was intended to allow great flexibility +for application design. +In practice, though, the flexibility turned out to less useful than expected, +and in many cases added complexity. +Therefore, in cgroups v2, +all available controllers are mounted against a single hierarchy. +The available controllers are automatically mounted, +meaning that it is not necessary (or possible) to specify the controllers +when mounting the cgroup v2 filesystem using a command such as the following: +.PP +.in +4n +.EX +mount -t cgroup2 none /mnt/cgroup2 +.EE +.in +.PP +A cgroup v2 controller is available only if it is not currently in use +via a mount against a cgroup v1 hierarchy. +Or, to put things another way, it is not possible to employ +the same controller against both a v1 hierarchy and the unified v2 hierarchy. +This means that it may be necessary first to unmount a v1 controller +(as described above) before that controller is available in v2. +Since +.BR systemd (1) +makes heavy use of some v1 controllers by default, +it can in some cases be simpler to boot the system with +selected v1 controllers disabled. +To do this, specify the +.IR cgroup_no_v1=list +option on the kernel boot command line; +.I list +is a comma-separated list of the names of the controllers to disable, +or the word +.I all +to disable all v1 controllers. +(This situation is correctly handled by +.BR systemd (1), +which falls back to operating without the specified controllers.) +.PP +Note that on many modern systems, +.BR systemd (1) +automatically mounts the +.I cgroup2 +filesystem at +.I /sys/fs/cgroup/unified +during the boot process. +.\" +.SS Cgroups v2 controllers +The following controllers, documented in the kernel source file +.IR Documentation/cgroup-v2.txt , +are supported in cgroups version 2: +.TP +.IR io " (since Linux 4.5)" +This is the successor of the version 1 +.I blkio +controller. +.TP +.IR memory " (since Linux 4.5)" +This is the successor of the version 1 +.I memory +controller. +.TP +.IR pids " (since Linux 4.5)" +This is the same as the version 1 +.I pids +controller. +.TP +.IR perf_event " (since Linux 4.11)" +This is the same as the version 1 +.I perf_event +controller. +.TP +.IR rdma " (since Linux 4.11)" +This is the same as the version 1 +.I rdma +controller. +.TP +.IR cpu " (since Linux 4.15)" +This is the successor to the version 1 +.I cpu +and +.I cpuacct +controllers. +.\" +.SS Cgroups v2 subtree control +Each cgroup in the v2 hierarchy contains the following two files: +.TP +.IR cgroup.controllers +This read-only file exposes a list of the controllers that are +.I available +in this cgroup. +The contents of this file match the contents of the +.I cgroup.subtree_control +file in the parent cgroup. +.TP +.I cgroup.subtree_control +This is a list of controllers that are +.IR active +.RI ( enabled ) +in the cgroup. +The set of controllers in this file is a subset of the set in the +.IR cgroup.controllers +of this cgroup. +The set of active controllers is modified by writing strings to this file +containing space-delimited controller names, +each preceded by '+' (to enable a controller) +or '\-' (to disable a controller), as in the following example: +.IP +.in +4n +.EX +echo '+pids -memory' > x/y/cgroup.subtree_control +.EE +.in +.IP +An attempt to enable a controller +that is not present in +.I cgroup.controllers +leads to an +.B ENOENT +error when writing to the +.I cgroup.subtree_control +file. +.PP +Because the list of controllers in +.I cgroup.subtree_control +is a subset of those +.IR cgroup.controllers , +a controller that has been disabled in one cgroup in the hierarchy +can never be re-enabled in the subtree below that cgroup. +.PP +A cgroup's +.I cgroup.subtree_control +file determines the set of controllers that are exercised in the +.I child +cgroups. +When a controller (e.g., +.IR pids ) +is present in the +.I cgroup.subtree_control +file of a parent cgroup, +then the corresponding controller-interface files (e.g., +.IR pids.max ) +are automatically created in the children of that cgroup +and can be used to exert resource control in the child cgroups. +.\" +.SS Cgroups v2 """no internal processes""" rule +Cgroups v2 enforces a so-called "no internal processes" rule. +Roughly speaking, this rule means that, +with the exception of the root cgroup, processes may reside +only in leaf nodes (cgroups that do not themselves contain child cgroups). +This avoids the need to decide how to partition resources between +processes which are members of cgroup A and processes in child cgroups of A. +.PP +For instance, if cgroup +.I /cg1/cg2 +exists, then a process may reside in +.IR /cg1/cg2 , +but not in +.IR /cg1 . +This is to avoid an ambiguity in cgroups v1 +with respect to the delegation of resources between processes in +.I /cg1 +and its child cgroups. +The recommended approach in cgroups v2 is to create a subdirectory called +.I leaf +for any nonleaf cgroup which should contain processes, but no child cgroups. +Thus, processes which previously would have gone into +.I /cg1 +would now go into +.IR /cg1/leaf . +This has the advantage of making explicit +the relationship between processes in +.I /cg1/leaf +and +.IR /cg1 's +other children. +.PP +The "no internal processes" rule is in fact more subtle than stated above. +More precisely, the rule is that a (nonroot) cgroup can't both +(1) have member processes, and +(2) distribute resources into child cgroups\(emthat is, have a nonempty +.I cgroup.subtree_control +file. +Thus, it +.I is +possible for a cgroup to have both member processes and child cgroups, +but before controllers can be enabled for that cgroup, +the member processes must be moved out of the cgroup +(e.g., perhaps into the child cgroups). +.PP +With the Linux 4.14 addition of "thread mode" (described below), +the "no internal processes" rule has been relaxed in some cases. +.\" +.SS Cgroups v2 cgroup.events file +With cgroups v2, a new mechanism is provided to obtain notification +about when a cgroup becomes empty. +The cgroups v1 +.IR release_agent +and +.IR notify_on_release +files are removed, and replaced by a new, more general-purpose file, +.IR cgroup.events . +This read-only file contains key-value pairs +(delimited by newline characters, with the key and value separated by spaces) +that identify events or state for a cgroup. +Currently, only one key appears in this file, +.IR populated , +which has either the value 0, +meaning that the cgroup (and its descendants) +contain no (nonzombie) processes, +or 1, meaning that the cgroup contains member processes. +.PP +The +.IR cgroup.events +file can be monitored, in order to receive notification when a cgroup +transitions between the populated and unpopulated states (or vice versa). +When monitoring this file using +.BR inotify (7), +transitions generate +.BR IN_MODIFY +events, and when monitoring the file using +.BR poll (2), +transitions generate +.B POLLPRI +events. +.PP +The cgroups v2 release-notification mechanism provided by the +.I populated +field of the +.I cgroup.events +file offers at least two advantages over the cgroups v1 +.IR release_agent +mechanism. +First, it allows for cheaper notification, +since a single process can monitor multiple +.IR cgroup.events +files. +By contrast, the cgroups v1 mechanism requires the creation +of a process for each notification. +Second, notification can be delegated to a process that lives inside +a container associated with the newly empty cgroup. +.\" +.SS Cgroups v2 cgroup.stat file +.\" commit ec39225cca42c05ac36853d11d28f877fde5c42e +Each cgroup in the v2 hierarchy contains a read-only +.IR cgroup.stat +file (first introduced in Linux 4.14) +that consists of lines containing key-value pairs. +The following keys currently appear in this file: +.TP +.I nr_descendants +This is the total number of visible (i.e., living) descendant cgroups +underneath this cgroup. +.TP +.I nr_dying_descendants +This is the total number of dying descendant cgroups +underneath this cgroup. +A cgroup enters the dying state after being deleted. +It remains in that state for an undefined period +(which will depend on system load) +while resources are freed before the cgroup is destroyed. +Note that the presence of some cgroups in the dying state is normal, +and is not indicative of any problem. +.IP +A process can't be made a member of a dying cgroup, +and a dying cgroup can't be brought back to life. +.\" +.SS Limiting the number of descendant cgroups +Each cgroup in the v2 hierarchy contains the following files, +which can be used to view and set limits on the number +of descendant cgroups under that cgroup: +.TP +.IR cgroup.max.depth " (since Linux 4.14)" +.\" commit 1a926e0bbab83bae8207d05a533173425e0496d1 +This file defines a limit on the depth of nesting of descendant cgroups. +A value of 0 in this file means that no descendant cgroups can be created. +An attempt to create a descendant whose nesting level exceeds +the limit fails +.RI ( mkdir (2) +fails with the error +.BR EAGAIN ). +.IP +Writing the string +.IR """max""" +to this file means that no limit is imposed. +The default value in this file is +.IR """max""" . +.TP +.IR cgroup.max.descendants " (since Linux 4.14)" +.\" commit 1a926e0bbab83bae8207d05a533173425e0496d1 +This file defines a limit on the number of live descendant cgroups that +this cgroup may have. +An attempt to create more descendants than allowed by the limit fails +.RI ( mkdir (2) +fails with the error +.BR EAGAIN ). +.IP +Writing the string +.IR """max""" +to this file means that no limit is imposed. +The default value in this file is +.IR """max""" . +.\" +.SS Cgroups v2 delegation: delegation to a less privileged user +In the context of cgroups, +delegation means passing management of some subtree +of the cgroup hierarchy to a nonprivileged process. +Cgroups v1 provides support for delegation that was +accidental and not fully secure. +Cgroups v2 supports delegation by explicit design. +.PP +Some terminology is required in order to describe delegation. +A +.I delegater +is a privileged user (i.e., root) who owns a parent cgroup. +A +.I delegatee +is a nonprivileged user who will be granted the permissions needed +to manage some subhierarchy under that parent cgroup, +known as the +.IR "delegated subtree" . +.PP +To perform delegation, +the delegater makes certain directories and files writable by the delegatee, +typically by changing the ownership of the objects to be the user ID +of the delegatee. +Assuming that we want to delegate the hierarchy rooted at (say) +.I /dlgt_grp +and that there are not yet any child cgroups under that cgroup, +the ownership of the following is changed to the user ID of the delegatee: +.TP +.IR /dlgt_grp +Changing the ownership of the root of the subtree means that any new +cgroups created under the subtree (and the files they contain) +will also be owned by the delegatee. +.TP +.IR /dlgt_grp/cgroup.procs +Changing the ownership of this file means that the delegatee +can move processes into the root of the delegated subtree. +.TP +.IR /dlgt_grp/cgroup.subtree_control +Changing the ownership of this file means that that the delegatee +can enable controllers (that are present in +.IR /dlgt_grp/cgroup.controllers ) +in order to further redistribute resources at lower levels in the subtree. +(As an alternative to changing the ownership of this file, +the delegater might instead add selected controllers to this file.) +.TP +.IR /dlgt_grp/cgroup.threads +Changing the ownership of this file is necessary if a threaded subtree +is being delegated (see the description of "thread mode", below). +This permits the delegatee to write thread IDs to the file. +(The ownership of this file can also be changed when delegating +a domain subtree, but currently this serves no purpose, +since, as described below, it is not possible to move a thread between +domain cgroups by writing its thread ID to the +.IR cgroup.tasks +file.) +.PP +The delegater should +.I not +change the ownership of any of the controller interfaces files (e.g., +.IR pids.max , +.IR memory.high ) +in +.IR dlgt_grp . +Those files are used from the next level above the delegated subtree +in order to distribute resources into the subtree, +and the delegatee should not have permission to change +the resources that are distributed into the delegated subtree. +.PP +See also the discussion of the +.IR /sys/kernel/cgroup/delegate +file in NOTES. +.PP +After the aforementioned steps have been performed, +the delegatee can create child cgroups within the delegated subtree +(the cgroup subdirectories and the files they contain +will be owned by the delegatee) +and move processes between cgroups in the subtree. +If some controllers are present in +.IR dlgt_grp/cgroup.subtree_control , +or the ownership of that file was passed to the delegatee, +the delegatee can also control the further redistribution +of the corresponding resources into the delegated subtree. +.\" +.SS Cgroups v2 delegation: nsdelegate and cgroup namespaces +Starting with Linux 4.13, +.\" commit 5136f6365ce3eace5a926e10f16ed2a233db5ba9 +there is a second way to perform cgroup delegation. +This is done by mounting or remounting the cgroup v2 filesystem with the +.I nsdelegate +mount option. +For example, if the cgroup v2 filesystem has already been mounted, +we can remount it with the +.I nsdelegate +option as follows: +.PP +.in +4n +.EX +mount -t cgroup2 -o remount,nsdelegate \\ + none /sys/fs/cgroup/unified +.EE +.in +.\" +.\" ALternatively, we could boot the kernel with the options: +.\" +.\" cgroup_no_v1=all systemd.legacy_systemd_cgroup_controller +.\" +.\" The effect of the latter option is to prevent systemd from employing +.\" its "hybrid" cgroup mode, where it tries to make use of cgroups v2. +.PP +The effect of this mount option is to cause cgroup namespaces +to automatically become delegation boundaries. +More specifically, +the following restrictions apply for processes inside the cgroup namespace: +.IP * 3 +Writes to controller interface files in the root directory of the namespace +will fail with the error +.BR EPERM . +Processes inside the cgroup namespace can still write to delegatable +files in the root directory of the cgroup namespace such as +.IR cgroup.procs +and +.IR cgroup.subtree_control , +and can create subhierarchy underneath the root directory. +.IP * +Attempts to migrate processes across the namespace boundary are denied +(with the error +.BR ENOENT ). +Processes inside the cgroup namespace can still +(subject to the containment rules described below) +move processes between cgroups +.I within +the subhierarchy under the namespace root. +.PP +The ability to define cgroup namespaces as delegation boundaries +makes cgroup namespaces more useful. +To understand why, suppose that we already have one cgroup hierarchy +that has been delegated to a nonprivileged user, +.IR cecilia , +using the older delegation technique described above. +Suppose further that +.I cecilia +wanted to further delegate a subhierarchy +under the existing delegated hierarchy. +(For example, the delegated hierarchy might be associated with +an unprivileged container run by +.IR cecilia .) +Even if a cgroup namespace was employed, +because both hierarchies are owned by the unprivileged user +.IR cecilia , +the following illegitimate actions could be performed: +.IP * 3 +A process in the inferior hierarchy could change the +resource controller settings in the root directory of the that hierarchy. +(These resource controller settings are intended to allow control to +be exercised from the +.I parent +cgroup; +a process inside the child cgroup should not be allowed to modify them.) +.IP * +A process inside the inferior hierarchy could move processes +into and out of the inferior hierarchy if the cgroups in the +superior hierarchy were somehow visible. +.PP +Employing the +.I nsdelegate +mount option prevents both of these possibilities. +.PP +The +.I nsdelegate +mount option only has an effect when performed in +the initial mount namespace; +in other mount namespaces, the option is silently ignored. +.PP +.IR Note : +On some systems, +.BR systemd (1) +automatically mounts the cgroup v2 filesystem. +In order to experiment with the +.I nsdelegate +operation, it may be desirable to +.\" +.SS Cgroup v2 delegation containment rules +Some delegation +.IR "containment rules" +ensure that the delegatee can move processes between cgroups within the +delegated subtree, +but can't move processes from outside the delegated subtree into +the subtree or vice versa. +A nonprivileged process (i.e., the delegatee) can write the PID of +a "target" process into a +.IR cgroup.procs +file only if all of the following are true: +.IP * 3 +The writer has write permission on the +.I cgroup.procs +file in the destination cgroup. +.IP * +The writer has write permission on the +.I cgroup.procs +file in the common ancestor of the source and destination cgroups. +(In some cases, +the common ancestor may be the source or destination cgroup itself.) +.IP * +If the cgroup v2 filesystem was mounted with the +.I nsdelegate +option, the writer must be able to see the source and destination cgroups +from its cgroup namespace. +.IP * +Before Linux 4.11: +.\" commit 576dd464505fc53d501bb94569db76f220104d28 +the effective UID of the writer (i.e., the delegatee) matches the +real user ID or the saved set-user-ID of the target process. +(This was a historical requirement inherited from cgroups v1 +that was later deemed unnecessary, +since the other rules suffice for containment in cgroups v2.) +.PP +.IR Note : +one consequence of these delegation containment rules is that the +unprivileged delegatee can't place the first process into +the delegated subtree; +instead, the delegater must place the first process +(a process owned by the delegatee) into the delegated subtree. +.\" +.SH CGROUPS VERSION 2 THREAD MODE +Among the restrictions imposed by cgroups v2 that were not present +in cgroups v1 are the following: +.IP * 3 +.IR "No thread-granularity control" : +all of the threads of a process must be in the same cgroup. +.IP * +.IR "No internal processes" : +a cgroup can't both have member processes and +exercise controllers on child cgroups. +.PP +Both of these restrictions were added because +the lack of these restrictions had caused problems +in cgroups v1. +In particular, the cgroups v1 ability to allow thread-level granularity +for cgroup membership made no sense for some controllers. +(A notable example was the +.I memory +controller: since threads share an address space, +it made no sense to split threads across different +.I memory +cgroups.) +.PP +Notwithstanding the initial design decision in cgroups v2, +there were use cases for certain controllers, notably the +.IR cpu +controller, +for which thread-level granularity of control was meaningful and useful. +To accommodate such use cases, Linux 4.14 added +.I "thread mode" +for cgroups v2. +.PP +Thread mode allows the following: +.IP * 3 +The creation of +.IR "threaded subtrees" +in which the threads of a process may +be spread across cgroups inside the tree. +(A threaded subtree may contain multiple multithreaded processes.) +.IP * +The concept of +.IR "threaded controllers", +which can distribute resources across the cgroups in a threaded subtree. +.IP * +A relaxation of the "no internal processes rule", +so that, within a threaded subtree, +a cgroup can both contain member threads and +exercise resource control over child cgroups. +.PP +With the addition of thread mode, +each nonroot cgroup now contains a new file, +.IR cgroup.type , +that exposes, and in some circumstances can be used to change, +the "type" of a cgroup. +This file contains one of the following type values: +.TP +.I "domain" +This is a normal v2 cgroup that provides process-granularity control. +If a process is a member of this cgroup, +then all threads of the process are (by definition) in the same cgroup. +This is the default cgroup type, +and provides the same behavior that was provided for +cgroups in the initial cgroups v2 implementation. +.TP +.I "threaded" +This cgroup is a member of a threaded subtree. +Threads can be added to this cgroup, +and controllers can be enabled for the cgroup. +.TP +.I "domain threaded" +This is a domain cgroup that serves as the root of a threaded subtree. +This cgroup type is also known as "threaded root". +.TP +.I "domain invalid" +This is a cgroup inside a threaded subtree +that is in an "invalid" state. +Processes can't be added to the cgroup, +and controllers can't be enabled for the cgroup. +The only thing that can be done with this cgroup (other than deleting it) +is to convert it to a +.IR threaded +cgroup by writing the string +.IR """threaded""" +to the +.I cgroup.type +file. +.IP +The rationale for the existence of this "interim" type +during the creation of a threaded subtree +(rather than the kernel simply immediately converting all cgroups +under the threaded root to the type +.IR threaded ) +is to allow for +possible future extensions to the thread mode model +.\" +.SS Threaded versus domain controllers +With the addition of threads mode, +cgroups v2 now distinguishes two types of resource controllers: +.IP * 3 +.I Threaded +.\" In the kernel source, look for ".threaded[ \t]*= true" in +.\" initializations of struct cgroup_subsys +controllers: these controllers support thread-granularity for +resource control and can be enabled inside threaded subtrees, +with the result that the corresponding controller-interface files +appear inside the cgroups in the threaded subtree. +As at Linux 4.15, the following controllers are threaded: +.IR cpu , +.IR perf_event , +and +.IR pids . +.IP * +.I Domain +controllers: these controllers support only process granularity +for resource control. +From the perspective of a domain controller, +all threads of a process are always in the same cgroup. +Domain controllers can't be enabled inside a threaded subtree. +.\" +.SS Creating a threaded subtree +There are two pathways that lead to the creation of a threaded subtree. +The first pathway proceeds as follows: +.IP 1. 3 +We write the string +.IR """threaded""" +to the +.I cgroup.type +file of a cgroup +.IR y/z +that currently has the type +.IR domain . +This has the following effects: +.RS +.IP * 3 +The type of the cgroup +.IR y/z +becomes +.IR threaded . +.IP * +The type of the parent cgroup, +.IR y , +becomes +.IR "domain threaded" . +The parent cgroup is the root of a threaded subtree +(also known as the "threaded root"). +.IP * +All other cgroups under +.IR y +that were not already of type +.IR threaded +(because they were inside already existing threaded subtrees +under the new threaded root) +are converted to type +.IR "domain invalid" . +Any subsequently created cgroups under +.I y +will also have the type +.IR "domain invalid" . +.RE +.IP 2. +We write the string +.IR """threaded""" +to each of the +.IR "domain invalid" +cgroups under +.IR y , +in order to convert them to the type +.IR threaded . +As a consequence of this step, all threads under the threaded root +now have the type +.IR threaded +and the threaded subtree is now fully usable. +The requirement to write +.IR """threaded""" +to each of these cgroups is somewhat cumbersome, +but allows for possible future extensions to the thread-mode model. +.PP +The second way of creating a threaded subtree is as follows: +.IP 1. 3 +In an existing cgroup, +.IR z , +that currently has the type +.IR domain , +we (1) enable one or more threaded controllers and +(2) make a process a member of +.IR z . +(These two steps can be done in either order.) +This has the following consequences: +.RS +.IP * 3 +The type of +.I z +becomes +.IR "domain threaded" . +.IP * +All of the descendant cgroups of +.I x +that were not already of type +.IR threaded +are converted to type +.IR "domain invalid" . +.RE +.IP 2. +As before, we make the threaded subtree usable by writing the string +.IR """threaded""" +to each of the +.IR "domain invalid" +cgroups under +.IR y , +in order to convert them to the type +.IR threaded . +.PP +One of the consequences of the above pathways to creating a threaded subtree +is that the threaded root cgroup can be a parent only to +.I threaded +(and +.IR "domain invalid" ) +cgroups. +The threaded root cgroup can't be a parent of a +.I domain +cgroups, and a +.I threaded +cgroup +can't have a sibling that is a +.I domain +cgroup. +.\" +.SS Using a threaded subtree +Within a threaded subtree, threaded controllers can be enabled +in each subgroup whose type has been changed to +.IR threaded ; +upon doing so, the corresponding controller interface files +appear in the children of that cgroup. +.PP +A process can be moved into a threaded subtree by writing its PID to the +.I cgroup.procs +file in one of the cgroups inside the tree. +This has the effect of making all of the threads +in the process members of the corresponding cgroup +and makes the process a member of the threaded subtree. +The threads of the process can then be spread across +the threaded subtree by writing their thread IDs (see +.BR gettid (2)) +to the +.I cgroup.threads +files in different cgroups inside the subtree. +The threads of a process must all reside in the same threaded subtree. +.PP +As with writing to +.IR cgroup.procs , +some containment rules apply when writing to the +.I cgroup.threads +file: +.IP * 3 +The writer must have write permission on the +cgroup.threads +file in the destination cgroup. +.IP * +The writer must have write permission on the +.I cgroup.procs +file in the common ancestor of the source and destination cgroups. +(In some cases, +the common ancestor may be the source or destination cgroup itself.) +.IP * +The source and destination cgroups must be in the same threaded subtree. +(Outside a threaded subtree, an attempt to move a thread by writing +its thread ID to the +.I cgroup.threads +file in a different +.I domain +cgroup fails with the error +.BR EOPNOTSUPP .) +.PP +The +.I cgroup.threads +file is present in each cgroup (including +.I domain +cgroups) and can be read in order to discover the set of threads +that is present in the cgroup. +The set of thread IDs obtained when reading this file +is not guaranteed to be ordered or free of duplicates. +.PP +The +.I cgroup.procs +file in the threaded root shows the PIDs of all processes +that are members of the threaded subtree. +The +.I cgroup.procs +files in the other cgroups in the subtree are not readable. +.PP +Domain controllers can't be enabled in a threaded subtree; +no controller-interface files appear inside the cgroups underneath the +threaded root. +From the point of view of a domain controller, +threaded subtrees are invisible: +a multithreaded process inside a threaded subtree appears to a domain +controller as a process that resides in the threaded root cgroup. +.PP +Within a threaded subtree, the "no internal processes" rule does not apply: +a cgroup can both contain member processes (or thread) +and exercise controllers on child cgroups. +.\" +.SS Rules for writing to cgroup.type and creating threaded subtrees +A number of rules apply when writing to the +.I cgroup.type +file: +.IP * 3 +Only the string +.IR """threaded""" +may be written. +In other words, the only explicit transition that is possible is to convert a +.I domain +cgroup to type +.IR threaded . +.IP * +The string +.IR """threaded""" +can be written only if the current value in +.IR cgroup.type +is one of the following +.RS +.IP \(bu 3 +.IR domain , +to start the creation of a threaded subtree via +the first of the pathways described above; +.IP \(bu +.IR "domain\ invalid" , +to convert one of the cgroups in a threaded subtree into a usable (i.e., +.IR threaded ) +state; +.IP \(bu +.IR threaded , +which has no effect (a "no-op"). +.RE +.IP * +We can't write to a +.I cgroup.type +file if the parent's type is +.IR "domain invalid" . +In other words, the cgroups of a threaded subtree must be converted to the +.I threaded +state in a top-down manner. +.PP +There are also some constraints that must be satisfied +in order to create a threaded subtree rooted at the cgroup +.IR x : +.IP * 3 +There can be no member processes in the descendant cgroups of +.IR x . +(The cgroup +.I x +can itself have member processes.) +.IP * +No domain controllers may be enabled in +.IR x 's +.IR cgroup.subtree_control +file. +.PP +If any of the above constraints is violated, then an attempt to write +.IR """threaded""" +to a +.IR cgroup.type +file fails with the error +.BR ENOTSUP . +.\" +.SS The """domain threaded""" cgroup type +According to the pathways described above, +the type of a cgroup can change to +.IR "domain threaded" +in either of the following cases: +.IP * 3 +The string +.IR """threaded""" +is written to a child cgroup. +.IP * +A threaded controller is enabled inside the cgroup and +a process is made a member of the cgroup. +.PP +A +.IR "domain threaded" +cgroup, +.IR x , +can revert to the type +.IR domain +if the above conditions no longer hold true\(emthat is, if all +.I threaded +child cgroups of +.I x +are removed and either +.I x +no longer has threaded controllers enabled or +no longer has member processes. +.PP +When a +.IR "domain threaded" +cgroup +.IR x +reverts to the type +.IR domain : +.IP * 3 +All +.IR "domain invalid" +descendants of +.I x +that are not in lower-level threaded subtrees revert to the type +.IR domain . +.IP * +The root cgroups in any lower-level threaded subtrees revert to the type +.IR "domain threaded" . +.\" +.SS Exceptions for the root cgroup +The root cgroup of the v2 hierarchy is treated exceptionally: +it can be the parent of both +.I domain +and +.I threaded +cgroups. +If the string +.I """threaded""" +is written to the +.I cgroup.type +file of one of the children of the root cgroup, then +.IP * 3 +The type of that cgroup becomes +.IR threaded . +.IP * +The type of any descendants of that cgroup that +are not part of lower-level threaded subtrees changes to +.IR "domain invalid" . +.PP +Note that in this case, there is no cgroup whose type becomes +.IR "domain threaded" . +(Notionally, the root cgroup can be considered as the threaded root +for the cgroup whose type was changed to +.IR threaded .) +.PP +The aim of this exceptional treatment for the root cgroup is to +allow a threaded cgroup that employs the +.I cpu +controller to be placed as high as possible in the hierarchy, +so as to minimize the (small) cost of traversing the cgroup hierarchy. +.\" +.SS The cgroups v2 """cpu""" controller and realtime processes +As at Linux 4.15, the cgroups v2 +.I cpu +controller does not support control of realtime processes, +and the controller can be enabled in the root cgroup only +if all realtime threads are in the root cgroup. +(If there are realtime processes in nonroot cgroups, then a +.BR write (2) +of the string +.IR """+cpu""" +to the +.I cgroup.subtree_control +file fails with the error +.BR EINVAL . +However, on some systems, +.BR systemd (1) +places certain realtime processes in nonroot cgroups in the v2 hierarchy. +On such systems, +these processes must first be moved to the root cgroup before the +.I cpu +controller can be enabled. +.\" +.SH ERRORS +The following errors can occur for +.BR mount (2): +.TP +.B EBUSY +An attempt to mount a cgroup version 1 filesystem specified neither the +.I name= +option (to mount a named hierarchy) nor a controller name (or +.IR all ). +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's cgroup memberships. +A process's cgroup memberships are preserved across +.BR execve (2). +.\" +.SS /proc files +.TP +.IR /proc/cgroups " (since Linux 2.6.24)" +This file contains information about the controllers +that are compiled into the kernel. +An example of the contents of this file (reformatted for readability) +is the following: +.IP +.in +4n +.EX +#subsys_name hierarchy num_cgroups enabled +cpuset 4 1 1 +cpu 8 1 1 +cpuacct 8 1 1 +blkio 6 1 1 +memory 3 1 1 +devices 10 84 1 +freezer 7 1 1 +net_cls 9 1 1 +perf_event 5 1 1 +net_prio 9 1 1 +hugetlb 0 1 0 +pids 2 1 1 +.EE +.in +.IP +The fields in this file are, from left to right: +.RS +.IP 1. 3 +The name of the controller. +.IP 2. +The unique ID of the cgroup hierarchy on which this controller is mounted. +If multiple cgroups v1 controllers are bound to the same hierarchy, +then each will show the same hierarchy ID in this field. +The value in this field will be 0 if: +.RS 5 +.IP a) 3 +the controller is not mounted on a cgroups v1 hierarchy; +.IP b) +the controller is bound to the cgroups v2 single unified hierarchy; or +.IP c) +the controller is disabled (see below). +.RE +.IP 3. +The number of control groups in this hierarchy using this controller. +.IP 4. +This field contains the value 1 if this controller is enabled, +or 0 if it has been disabled (via the +.IR cgroup_disable +kernel command-line boot parameter). +.RE +.TP +.IR /proc/[pid]/cgroup " (since Linux 2.6.24)" +This file describes control groups to which the process +with the corresponding PID belongs. +The displayed information differs for +cgroups version 1 and version 2 hierarchies. +.IP +For each cgroup hierarchy of which the process is a member, +there is one entry containing three colon-separated fields: +.IP +.in +4n +.EX +hierarchy-ID:controller-list:cgroup-path +.EE +.in +.IP +For example: +.IP +.in +4n +.EX +5:cpuacct,cpu,cpuset:/daemons +.EE +.in +.IP +The colon-separated fields are, from left to right: +.RS +.IP 1. 3 +For cgroups version 1 hierarchies, +this field contains a unique hierarchy ID number +that can be matched to a hierarchy ID in +.IR /proc/cgroups . +For the cgroups version 2 hierarchy, this field contains the value 0. +.IP 2. +For cgroups version 1 hierarchies, +this field contains a comma-separated list of the controllers +bound to the hierarchy. +For the cgroups version 2 hierarchy, this field is empty. +.IP 3. +This field contains the pathname of the control group in the hierarchy +to which the process belongs. +This pathname is relative to the mount point of the hierarchy. +.RE +.\" +.SS /sys/kernel/cgroup files +.TP +.IR /sys/kernel/cgroup/delegate " (since Linux 4.15)" +.\" commit 01ee6cfb1483fe57c9cbd8e73817dfbf9bacffd3 +This file exports a list of the cgroups v2 files +(one per line) that are delegatable +(i.e., whose ownership should be changed to the user ID of the delegatee). +In the future, the set of delegatable files may change or grow, +and this file provides a way for the kernel to inform +user-space applications of which files must be delegated. +As at Linux 4.15, one sees the following when inspecting this file: +.IP +.EX +.in +4n +$ \fBcat /sys/kernel/cgroup/delegate\fP +cgroup.procs +cgroup.subtree_control +cgroup.threads +.in +.EE +.TP +.IR /sys/kernel/cgroup/features " (since Linux 4.15)" +.\" commit 5f2e673405b742be64e7c3604ed4ed3ac14f35ce +Over time, the set of cgroups v2 features that are provided by the +kernel may change or grow, +or some features may not be enabled by default. +This file provides a way for user-space applications to discover what +features the running kernel supports and has enabled. +Features are listed one per line: +.IP +.in +4n +.EX +$ \fBcat /sys/kernel/cgroup/features\fP +nsdelegate +.EE +.in +.IP +The entries that can appear in this file are: +.RS +.TP +.IR nsdelegate " (since Linux 4.15)" +The kernel supports the +.I nsdelegate +mount option. +.RE +.SH SEE ALSO +.BR prlimit (1), +.BR systemd (1), +.BR systemd-cgls (1), +.BR systemd-cgtop (1), +.BR clone (2), +.BR ioprio_set (2), +.BR perf_event_open (2), +.BR setrlimit (2), +.BR cgroup_namespaces (7), +.BR cpuset (7), +.BR namespaces (7), +.BR sched (7), +.BR user_namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/charsets.7 b/man7/charsets.7 new file mode 100644 index 0000000..5f91784 --- /dev/null +++ b/man7/charsets.7 @@ -0,0 +1,344 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright (c) 1996 Eric S. Raymond +.\" and Copyright (c) Andries Brouwer +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.\" This is combined from many sources, including notes by aeb and +.\" research by esr. Portions derive from a writeup by Roman Czyborra. +.\" +.\" Changes also by David Starner . +.\" +.TH CHARSETS 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +charsets \- character set standards and internationalization +.SH DESCRIPTION +This manual page gives an overview on different character set standards +and how they were used on Linux before Unicode became ubiquitous. +Some of this information is still helpful for people working with legacy +systems and documents. +.PP +Standards discussed include such as +ASCII, GB 2312, ISO 8859, JIS, KOI8-R, KS, and Unicode. +.PP +The primary emphasis is on character sets that were actually used by +locale character sets, not the myriad others that could be found in data +from other systems. +.SS ASCII +ASCII (American Standard Code For Information Interchange) is the original +7-bit character set, originally designed for American English. +Also known as US-ASCII. +It is currently described by the ISO 646:1991 IRV +(International Reference Version) standard. +.PP +Various ASCII variants replacing the dollar sign with other currency +symbols and replacing punctuation with non-English alphabetic +characters to cover German, French, Spanish, and others in 7 bits +emerged. +All are deprecated; +glibc does not support locales whose character sets are not true +supersets of ASCII. +.PP +As Unicode, when using UTF-8, is ASCII-compatible, plain ASCII text +still renders properly on modern UTF-8 using systems. +.SS ISO 8859 +ISO 8859 is a series of 15 8-bit character sets, all of which have ASCII +in their low (7-bit) half, invisible control characters in positions +128 to 159, and 96 fixed-width graphics in positions 160\(en255. +.PP +Of these, the most important is ISO 8859-1 +("Latin Alphabet No .1" / Latin-1). +It was widely adopted and supported by different systems, +and is gradually being replaced with Unicode. +The ISO 8859-1 characters are also the first 256 characters of Unicode. +.PP +Console support for the other 8859 character sets is available under +Linux through user-mode utilities (such as +.BR setfont (8)) +that modify keyboard bindings and the EGA graphics +table and employ the "user mapping" font table in the console +driver. +.PP +Here are brief descriptions of each set: +.TP +8859-1 (Latin-1) +Latin-1 covers many West European languages such as Albanian, Basque, +Danish, English, Faroese, Galician, Icelandic, Irish, Italian, +Norwegian, Portuguese, Spanish, and Swedish. +The lack of the ligatures Dutch IJ/ij, French œ, and old-style „German“ +quotation marks was considered tolerable. +.TP +8859-2 (Latin-2) +Latin-2 supports many Latin-written Central and East European +languages such as Bosnian, Croatian, Czech, German, Hungarian, Polish, +Slovak, and Slovene. +Replacing Romanian ș/ț with ş/ţ was considered tolerable. +.TP +8859-3 (Latin-3) +Latin-3 was designed to cover of Esperanto, Maltese, and Turkish, but +8859-9 later superseded it for Turkish. +.TP +8859-4 (Latin-4) +Latin-4 introduced letters for North European languages such as +Estonian, Latvian, and Lithuanian, but was superseded by 8859-10 and +8859-13. +.TP +8859-5 +Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian, +Russian, Serbian, and (almost completely) Ukrainian. +It was never widely used, see the discussion of KOI8-R/KOI8-U below. +.TP +8859-6 +Was created for Arabic. +The 8859-6 glyph table is a fixed font of separate +letter forms, but a proper display engine should combine these +using the proper initial, medial, and final forms. +.TP +8859-7 +Was created for Modern Greek in 1987, updated in 2003. +.TP +8859-8 +Supports Modern Hebrew without niqud (punctuation signs). +Niqud and full-fledged Biblical Hebrew were outside the scope of this +character set. +.TP +8859-9 (Latin-5) +This is a variant of Latin-1 that replaces Icelandic letters with +Turkish ones. +.TP +8859-10 (Latin-6) +Latin-6 added the Inuit (Greenlandic) and Sami (Lappish) letters that were +missing in Latin-4 to cover the entire Nordic area. +.TP +8859-11 +Supports the Thai alphabet and is nearly identical to the TIS-620 +standard. +.TP +8859-12 +This set does not exist. +.TP +8859-13 (Latin-7) +Supports the Baltic Rim languages; in particular, it includes Latvian +characters not found in Latin-4. +.TP +8859-14 (Latin-8) +This is the Celtic character set, covering Old Irish, Manx, Gaelic, +Welsh, Cornish, and Breton. +.TP +8859-15 (Latin-9) +Latin-9 is similar to the widely used Latin-1 but replaces some less +common symbols with the Euro sign and French and Finnish letters that +were missing in Latin-1. +.TP +8859-16 (Latin-10) +This set covers many Southeast European languages, and most +importantly supports Romanian more completely than Latin-2. +.SS KOI8-R / KOI8-U +KOI8-R is a non-ISO character set popular in Russia before Unicode. +The lower half is ASCII; +the upper is a Cyrillic character set somewhat better designed than +ISO 8859-5. +KOI8-U, based on KOI8-R, has better support for Ukrainian. +Neither of these sets are ISO-2022 compatible, +unlike the ISO 8859 series. +.PP +Console support for KOI8-R is available under Linux through user-mode +utilities that modify keyboard bindings and the EGA graphics table, +and employ the "user mapping" font table in the console driver. +.SS GB 2312 +GB 2312 is a mainland Chinese national standard character set used +to express simplified Chinese. +Just like JIS X 0208, characters are +mapped into a 94x94 two-byte matrix used to construct EUC-CN. +EUC-CN +is the most important encoding for Linux and includes ASCII and +GB 2312. +Note that EUC-CN is often called as GB, GB 2312, or CN-GB. +.SS Big5 +Big5 was a popular character set in Taiwan to express traditional +Chinese. +(Big5 is both a character set and an encoding.) +It is a superset of ASCII. +Non-ASCII characters are expressed in two bytes. +Bytes 0xa1\(en0xfe are used as leading bytes for two-byte characters. +Big5 and its extension were widely used in Taiwan and Hong Kong. +It is not ISO 2022 compliant. +.\" Thanks to Tomohiro KUBOTA for the following sections about +.\" national standards. +.SS JIS X 0208 +JIS X 0208 is a Japanese national standard character set. +Though there are some more Japanese national standard character sets (like +JIS X 0201, JIS X 0212, and JIS X 0213), this is the most important one. +Characters are mapped into a 94x94 two-byte matrix, +whose each byte is in the range 0x21\(en0x7e. +Note that JIS X 0208 is a character set, not an encoding. +This means that JIS X 0208 +itself is not used for expressing text data. +JIS X 0208 is used +as a component to construct encodings such as EUC-JP, Shift_JIS, +and ISO-2022-JP. +EUC-JP is the most important encoding for Linux +and includes ASCII and JIS X 0208. +In EUC-JP, JIS X 0208 +characters are expressed in two bytes, each of which is the +JIS X 0208 code plus 0x80. +.SS KS X 1001 +KS X 1001 is a Korean national standard character set. +Just as +JIS X 0208, characters are mapped into a 94x94 two-byte matrix. +KS X 1001 is used like JIS X 0208, as a component +to construct encodings such as EUC-KR, Johab, and ISO-2022-KR. +EUC-KR is the most important encoding for Linux and includes +ASCII and KS X 1001. +KS C 5601 is an older name for KS X 1001. +.SS ISO 2022 and ISO 4873 +The ISO 2022 and 4873 standards describe a font-control model +based on VT100 practice. +This model is (partially) supported +by the Linux kernel and by +.BR xterm (1). +Several ISO 2022-based character encodings have been defined, +especially for Japanese. +.PP +There are 4 graphic character sets, called G0, G1, G2, and G3, +and one of them is the current character set for codes with +high bit zero (initially G0), and one of them is the current +character set for codes with high bit one (initially G1). +Each graphic character set has 94 or 96 characters, and is +essentially a 7-bit character set. +It uses codes either +040\(en0177 (041\(en0176) or 0240\(en0377 (0241\(en0376). +G0 always has size 94 and uses codes 041\(en0176. +.PP +Switching between character sets is done using the shift functions +\fB^N\fP (SO or LS1), \fB^O\fP (SI or LS0), ESC n (LS2), ESC o (LS3), +ESC N (SS2), ESC O (SS3), ESC ~ (LS1R), ESC } (LS2R), ESC | (LS3R). +The function LS\fIn\fP makes character set G\fIn\fP the current one +for codes with high bit zero. +The function LS\fIn\fPR makes character set G\fIn\fP the current one +for codes with high bit one. +The function SS\fIn\fP makes character set G\fIn\fP (\fIn\fP=2 or 3) +the current one for the next character only (regardless of the value +of its high order bit). +.PP +A 94-character set is designated as G\fIn\fP character set +by an escape sequence ESC ( xx (for G0), ESC ) xx (for G1), +ESC * xx (for G2), ESC + xx (for G3), where xx is a symbol +or a pair of symbols found in the ISO 2375 International +Register of Coded Character Sets. +For example, ESC ( @ selects the ISO 646 character set as G0, +ESC ( A selects the UK standard character set (with pound +instead of number sign), ESC ( B selects ASCII (with dollar +instead of currency sign), ESC ( M selects a character set +for African languages, ESC ( ! A selects the Cuban character +set, and so on. +.PP +A 96-character set is designated as G\fIn\fP character set +by an escape sequence ESC \- xx (for G1), ESC . xx (for G2) +or ESC / xx (for G3). +For example, ESC \- G selects the Hebrew alphabet as G1. +.PP +A multibyte character set is designated as G\fIn\fP character set +by an escape sequence ESC $ xx or ESC $ ( xx (for G0), +ESC $ ) xx (for G1), ESC $ * xx (for G2), ESC $ + xx (for G3). +For example, ESC $ ( C selects the Korean character set for G0. +The Japanese character set selected by ESC $ B has a more +recent version selected by ESC & @ ESC $ B. +.PP +ISO 4873 stipulates a narrower use of character sets, where G0 +is fixed (always ASCII), so that G1, G2 and G3 +can be invoked only for codes with the high order bit set. +In particular, \fB^N\fP and \fB^O\fP are not used anymore, ESC ( xx +can be used only with xx=B, and ESC ) xx, ESC * xx, ESC + xx +are equivalent to ESC \- xx, ESC . xx, ESC / xx, respectively. +.SS TIS-620 +TIS-620 is a Thai national standard character set and a superset +of ASCII. +In the same fashion as the ISO 8859 series, Thai characters are mapped into +0xa1\(en0xfe. +.SS Unicode +Unicode (ISO 10646) is a standard which aims to unambiguously represent +every character in every human language. +Unicode's structure permits 20.1 bits to encode every character. +Since most computers don't include 20.1-bit integers, Unicode is +usually encoded as 32-bit integers internally and either a series of +16-bit integers (UTF-16) (needing two 16-bit integers only when +encoding certain rare characters) or a series of 8-bit bytes (UTF-8). +.PP +Linux represents Unicode using the 8-bit Unicode Transformation Format +(UTF-8). +UTF-8 is a variable length encoding of Unicode. +It uses 1 +byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes +for 21 bits, 5 bytes for 26 bits, 6 bytes for 31 bits. +.PP +Let 0,1,x stand for a zero, one, or arbitrary bit. +A byte 0xxxxxxx +stands for the Unicode 00000000 0xxxxxxx which codes the same symbol +as the ASCII 0xxxxxxx. +Thus, ASCII goes unchanged into UTF-8, and +people using only ASCII do not notice any change: not in code, and not +in file size. +.PP +A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy +is assembled into 00000xxx xxyyyyyy. +A byte 1110xxxx is the start +of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled +into xxxxyyyy yyzzzzzz. +(When UTF-8 is used to code the 31-bit ISO 10646 +then this progression continues up to 6-byte codes.) +.PP +For most texts in ISO 8859 character sets, this means that the +characters outside of ASCII are now coded with two bytes. +This tends +to expand ordinary text files by only one or two percent. +For Russian +or Greek texts, this expands ordinary text files by 100%, since text in +those languages is mostly outside of ASCII. +For Japanese users this means +that the 16-bit codes now in common use will take three bytes. +While there are algorithmic conversions from some character sets +(especially ISO 8859-1) to Unicode, general conversion requires +carrying around conversion tables, which can be quite large for 16-bit +codes. +.PP +Note that UTF-8 is self-synchronizing: 10xxxxxx is a tail, any other +byte is the head of a code. +Note that the only way ASCII bytes occur +in a UTF-8 stream, is as themselves. +In particular, there are no +embedded NULs (\(aq\\0\(aq) or \(aq/\(aqs that form part of some larger code. +.PP +Since ASCII, and, in particular, NUL and \(aq/\(aq, are unchanged, the +kernel does not notice that UTF-8 is being used. +It does not care at +all what the bytes it is handling stand for. +.PP +Rendering of Unicode data streams is typically handled through +"subfont" tables which map a subset of Unicode to glyphs. +Internally +the kernel uses Unicode to describe the subfont loaded in video RAM. +This means that in the Linux console in UTF-8 mode, one can use a character +set with 512 different symbols. +This is not enough for Japanese, Chinese, and +Korean, but it is enough for most other purposes. +.SH SEE ALSO +.BR iconv (1), +.BR ascii (7), +.BR iso_8859-1 (7), +.BR unicode (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/complex.7 b/man7/complex.7 new file mode 100644 index 0000000..3c7b5e9 --- /dev/null +++ b/man7/complex.7 @@ -0,0 +1,90 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Distributed under GPL +.\" %%%LICENSE_END +.\" +.TH COMPLEX 7 2011-09-16 "" "Linux Programmer's Manual" +.SH NAME +complex \- basics of complex mathematics +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +Complex numbers are numbers of the form z = a+b*i, where a and b are +real numbers and i = sqrt(\-1), so that i*i = \-1. +.PP +There are other ways to represent that number. +The pair (a,b) of real +numbers may be viewed as a point in the plane, given by X- and +Y-coordinates. +This same point may also be described by giving +the pair of real numbers (r,phi), where r is the distance to the origin O, +and phi the angle between the X-axis and the line Oz. +Now +z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)). +.PP +The basic operations are defined on z = a+b*i and w = c+d*i as: +.TP +.B addition: z+w = (a+c) + (b+d)*i +.TP +.B multiplication: z*w = (a*c \- b*d) + (a*d + b*c)*i +.TP +.B division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c \- a*d)/(c*c + d*d))*i +.PP +Nearly all math function have a complex counterpart but there are +some complex-only functions. +.SH EXAMPLE +Your C-compiler can work with complex numbers if it supports the C99 standard. +Link with \fI\-lm\fP. +The imaginary unit is represented by I. +.PP +.EX +/* check that exp(i * pi) == \-1 */ +#include /* for atan */ +#include +#include + +int +main(void) +{ + double pi = 4 * atan(1.0); + double complex z = cexp(I * pi); + printf("%f + %f * i\\n", creal(z), cimag(z)); +} +.EE +.SH SEE ALSO +.BR cabs (3), +.BR cacos (3), +.BR cacosh (3), +.BR carg (3), +.BR casin (3), +.BR casinh (3), +.BR catan (3), +.BR catanh (3), +.BR ccos (3), +.BR ccosh (3), +.BR cerf (3), +.BR cexp (3), +.BR cexp2 (3), +.BR cimag (3), +.BR clog (3), +.BR clog10 (3), +.BR clog2 (3), +.BR conj (3), +.BR cpow (3), +.BR cproj (3), +.BR creal (3), +.BR csin (3), +.BR csinh (3), +.BR csqrt (3), +.BR ctan (3), +.BR ctanh (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/cp1251.7 b/man7/cp1251.7 new file mode 100644 index 0000000..858da34 --- /dev/null +++ b/man7/cp1251.7 @@ -0,0 +1,194 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH CP1251 7 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +cp1251 \- CP\ 1251 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The Windows Code Pages include several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +CP\ 1251 encodes the +characters used in Cyrillic scripts. +.SS CP\ 1251 characters +The following table displays the characters in CP\ 1251 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 Ђ CYRILLIC CAPITAL LETTER DJE +201 129 81 Ѓ CYRILLIC CAPITAL LETTER GJE +202 130 82 ‚ SINGLE LOW-9 QUOTATION MARK +203 131 83 ѓ CYRILLIC SMALL LETTER GJE +204 132 84 „ DOUBLE LOW-9 QUOTATION MARK +205 133 85 … HORIZONTAL ELLIPSIS +206 134 86 † DAGGER +207 135 87 ‡ DOUBLE DAGGER +210 136 88 € EURO SIGN +211 137 89 ‰ PER MILLE SIGN +212 138 8A Љ CYRILLIC CAPITAL LETTER LJE +213 139 8B ‹ SINGLE LEFT-POINTING ANGLE QUOTATION MARK +214 140 8C Њ CYRILLIC CAPITAL LETTER NJE +215 141 8D Ќ CYRILLIC CAPITAL LETTER KJE +216 142 8E Ћ CYRILLIC CAPITAL LETTER TSHE +217 143 8F Џ CYRILLIC CAPITAL LETTER DZHE +220 144 90 ђ CYRILLIC SMALL LETTER DJE +221 145 91 ‘ LEFT SINGLE QUOTATION MARK +222 146 92 ’ RIGHT SINGLE QUOTATION MARK +223 147 93 “ LEFT DOUBLE QUOTATION MARK +224 148 94 ” RIGHT DOUBLE QUOTATION MARK +225 149 95 • BULLET +226 150 96 – EN DASH +227 151 97 — EM DASH +230 152 98 UNDEFINED +231 153 99 ™ TRADE MARK SIGN +232 154 9A љ CYRILLIC SMALL LETTER LJE +233 155 9B › SINGLE RIGHT-POINTING ANGLE QUOTATION MARK +234 156 9C њ CYRILLIC SMALL LETTER NJE +235 157 9D ќ CYRILLIC SMALL LETTER KJE +236 158 9E ћ CYRILLIC SMALL LETTER TSHE +237 159 9F џ CYRILLIC SMALL LETTER DZHE +240 160 A0   NO-BREAK SPACE +241 161 A1 Ў CYRILLIC CAPITAL LETTER SHORT U +242 162 A2 ў CYRILLIC SMALL LETTER SHORT U +243 163 A3 Ј CYRILLIC CAPITAL LETTER JE +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 Ґ CYRILLIC CAPITAL LETTER GHE WITH UPTURN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 Ё CYRILLIC CAPITAL LETTER IO +251 169 A9 © COPYRIGHT SIGN +252 170 AA Є CYRILLIC CAPITAL LETTER UKRAINIAN IE +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF Ї CYRILLIC CAPITAL LETTER YI +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 І T{ +CYRILLIC CAPITAL LETTER +.br +BYELORUSSIAN-UKRAINIAN I +T} +263 179 B3 і CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I +264 180 B4 ґ CYRILLIC SMALL LETTER GHE WITH UPTURN +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ё CYRILLIC SMALL LETTER IO +271 185 B9 № NUMERO SIGN +272 186 BA є CYRILLIC SMALL LETTER UKRAINIAN IE +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ј CYRILLIC SMALL LETTER JE +275 189 BD Ѕ CYRILLIC CAPITAL LETTER DZE +276 190 BE ѕ CYRILLIC SMALL LETTER DZE +277 191 BF ї CYRILLIC SMALL LETTER YI +300 192 C0 А CYRILLIC CAPITAL LETTER A +301 193 C1 Б CYRILLIC CAPITAL LETTER BE +302 194 C2 В CYRILLIC CAPITAL LETTER VE +303 195 C3 Г CYRILLIC CAPITAL LETTER GHE +304 196 C4 Д CYRILLIC CAPITAL LETTER DE +305 197 C5 Е CYRILLIC CAPITAL LETTER IE +306 198 C6 Ж CYRILLIC CAPITAL LETTER ZHE +307 199 C7 З CYRILLIC CAPITAL LETTER ZE +310 200 C8 И CYRILLIC CAPITAL LETTER I +311 201 C9 Й CYRILLIC CAPITAL LETTER SHORT I +312 202 CA К CYRILLIC CAPITAL LETTER KA +313 203 CB Л CYRILLIC CAPITAL LETTER EL +314 204 CC М CYRILLIC CAPITAL LETTER EM +315 205 CD Н CYRILLIC CAPITAL LETTER EN +316 206 CE О CYRILLIC CAPITAL LETTER O +317 207 CF П CYRILLIC CAPITAL LETTER PE +320 208 D0 Р CYRILLIC CAPITAL LETTER ER +321 209 D1 С CYRILLIC CAPITAL LETTER ES +322 210 D2 Т CYRILLIC CAPITAL LETTER TE +323 211 D3 У CYRILLIC CAPITAL LETTER U +324 212 D4 Ф CYRILLIC CAPITAL LETTER EF +325 213 D5 Х CYRILLIC CAPITAL LETTER HA +326 214 D6 Ц CYRILLIC CAPITAL LETTER TSE +327 215 D7 Ч CYRILLIC CAPITAL LETTER CHE +330 216 D8 Ш CYRILLIC CAPITAL LETTER SHA +331 217 D9 Щ CYRILLIC CAPITAL LETTER SHCHA +332 218 DA Ъ CYRILLIC CAPITAL LETTER HARD SIGN +333 219 DB Ы CYRILLIC CAPITAL LETTER YERU +334 220 DC Ь CYRILLIC CAPITAL LETTER SOFT SIGN +335 221 DD Э CYRILLIC CAPITAL LETTER E +336 222 DE Ю CYRILLIC CAPITAL LETTER YU +337 223 DF Я CYRILLIC CAPITAL LETTER YA +340 224 E0 а CYRILLIC SMALL LETTER A +341 225 E1 б CYRILLIC SMALL LETTER BE +342 226 E2 в CYRILLIC SMALL LETTER VE +343 227 E3 г CYRILLIC SMALL LETTER GHE +344 228 E4 д CYRILLIC SMALL LETTER DE +345 229 E5 е CYRILLIC SMALL LETTER IE +346 230 E6 ж CYRILLIC SMALL LETTER ZHE +347 231 E7 з CYRILLIC SMALL LETTER ZE +350 232 E8 и CYRILLIC SMALL LETTER I +351 233 E9 й CYRILLIC SMALL LETTER SHORT I +352 234 EA к CYRILLIC SMALL LETTER KA +353 235 EB л CYRILLIC SMALL LETTER EL +354 236 EC м CYRILLIC SMALL LETTER EM +355 237 ED н CYRILLIC SMALL LETTER EN +356 238 EE о CYRILLIC SMALL LETTER O +357 239 EF п CYRILLIC SMALL LETTER PE +360 240 F0 р CYRILLIC SMALL LETTER ER +361 241 F1 с CYRILLIC SMALL LETTER ES +362 242 F2 т CYRILLIC SMALL LETTER TE +363 243 F3 у CYRILLIC SMALL LETTER U +364 244 F4 ф CYRILLIC SMALL LETTER EF +365 245 F5 х CYRILLIC SMALL LETTER HA +366 246 F6 ц CYRILLIC SMALL LETTER TSE +367 247 F7 ч CYRILLIC SMALL LETTER CHE +370 248 F8 ш CYRILLIC SMALL LETTER SHA +371 249 F9 щ CYRILLIC SMALL LETTER SHCHA +372 250 FA ъ CYRILLIC SMALL LETTER HARD SIGN +373 251 FB ы CYRILLIC SMALL LETTER YERU +374 252 FC ь CYRILLIC SMALL LETTER SOFT SIGN +375 253 FD э CYRILLIC SMALL LETTER E +376 254 FE ю CYRILLIC SMALL LETTER YU +377 255 FF я CYRILLIC SMALL LETTER YA +.TE +.SH NOTES +CP\ 1251 is also known as Windows Cyrillic. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1252 (7), +.BR iso_8859-5 (7), +.BR koi8-r (7), +.BR koi8-u (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/cp1252.7 b/man7/cp1252.7 new file mode 100644 index 0000000..c22d4e3 --- /dev/null +++ b/man7/cp1252.7 @@ -0,0 +1,184 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2014 (C) Marko Myllynen +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH CP1252 7 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +cp1252 \- CP\ 1252 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The Windows Code Pages include several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +CP\ 1252 encodes the +characters used in many West European languages. +.SS CP\ 1252 characters +The following table displays the characters in CP\ 1252 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 € EURO SIGN +202 130 82 ‚ SINGLE LOW-9 QUOTATION MARK +203 131 83 ƒ LATIN SMALL LETTER F WITH HOOK +204 132 84 „ DOUBLE LOW-9 QUOTATION MARK +205 133 85 … HORIZONTAL ELLIPSIS +206 134 86 † DAGGER +207 135 87 ‡ DOUBLE DAGGER +210 136 88 ˆ MODIFIER LETTER CIRCUMFLEX ACCENT +211 137 89 ‰ PER MILLE SIGN +212 138 8A Š LATIN CAPITAL LETTER S WITH CARON +213 139 8B ‹ SINGLE LEFT-POINTING ANGLE QUOTATION MARK +214 140 8C Œ LATIN CAPITAL LIGATURE OE +216 142 8E Ž LATIN CAPITAL LETTER Z WITH CARON +221 145 91 ‘ LEFT SINGLE QUOTATION MARK +222 146 92 ’ RIGHT SINGLE QUOTATION MARK +223 147 93 “ LEFT DOUBLE QUOTATION MARK +224 148 94 ” RIGHT DOUBLE QUOTATION MARK +225 149 95 • BULLET +226 150 96 – EN DASH +227 151 97 — EM DASH +230 152 98 ˜ SMALL TILDE +231 153 99 ™ TRADE MARK SIGN +232 154 9A š LATIN SMALL LETTER S WITH CARON +233 155 9B › SINGLE RIGHT-POINTING ANGLE QUOTATION MARK +234 156 9C œ LATIN SMALL LIGATURE OE +236 158 9E ž LATIN SMALL LETTER Z WITH CARON +237 159 9F Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +CP\ 1252 is also known as Windows-1252. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1251 (7), +.BR iso_8859-1 (7), +.BR iso_8859-15 (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/cpuset.7 b/man7/cpuset.7 new file mode 100644 index 0000000..e894132 --- /dev/null +++ b/man7/cpuset.7 @@ -0,0 +1,1520 @@ +.\" Copyright (c) 2008 Silicon Graphics, Inc. +.\" +.\" Author: Paul Jackson (http://oss.sgi.com/projects/cpusets) +.\" +.\" %%%LICENSE_START(GPLv2_MISC) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" version 2 as published by the Free Software Foundation. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH CPUSET 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +cpuset \- confine processes to processor and memory node subsets +.SH DESCRIPTION +The cpuset filesystem is a pseudo-filesystem interface +to the kernel cpuset mechanism, +which is used to control the processor placement +and memory placement of processes. +It is commonly mounted at +.IR /dev/cpuset . +.PP +On systems with kernels compiled with built in support for cpusets, +all processes are attached to a cpuset, and cpusets are always present. +If a system supports cpusets, then it will have the entry +.B nodev cpuset +in the file +.IR /proc/filesystems . +By mounting the cpuset filesystem (see the +.B EXAMPLE +section below), +the administrator can configure the cpusets on a system +to control the processor and memory placement of processes +on that system. +By default, if the cpuset configuration +on a system is not modified or if the cpuset filesystem +is not even mounted, then the cpuset mechanism, +though present, has no effect on the system's behavior. +.PP +A cpuset defines a list of CPUs and memory nodes. +.PP +The CPUs of a system include all the logical processing +units on which a process can execute, including, if present, +multiple processor cores within a package and Hyper-Threads +within a processor core. +Memory nodes include all distinct +banks of main memory; small and SMP systems typically have +just one memory node that contains all the system's main memory, +while NUMA (non-uniform memory access) systems have multiple memory nodes. +.PP +Cpusets are represented as directories in a hierarchical +pseudo-filesystem, where the top directory in the hierarchy +.RI ( /dev/cpuset ) +represents the entire system (all online CPUs and memory nodes) +and any cpuset that is the child (descendant) of +another parent cpuset contains a subset of that parent's +CPUs and memory nodes. +The directories and files representing cpusets have normal +filesystem permissions. +.PP +Every process in the system belongs to exactly one cpuset. +A process is confined to run only on the CPUs in +the cpuset it belongs to, and to allocate memory only +on the memory nodes in that cpuset. +When a process +.BR fork (2)s, +the child process is placed in the same cpuset as its parent. +With sufficient privilege, a process may be moved from one +cpuset to another and the allowed CPUs and memory nodes +of an existing cpuset may be changed. +.PP +When the system begins booting, a single cpuset is +defined that includes all CPUs and memory nodes on the +system, and all processes are in that cpuset. +During the boot process, or later during normal system operation, +other cpusets may be created, as subdirectories of this top cpuset, +under the control of the system administrator, +and processes may be placed in these other cpusets. +.PP +Cpusets are integrated with the +.BR sched_setaffinity (2) +scheduling affinity mechanism and the +.BR mbind (2) +and +.BR set_mempolicy (2) +memory-placement mechanisms in the kernel. +Neither of these mechanisms let a process make use +of a CPU or memory node that is not allowed by that process's cpuset. +If changes to a process's cpuset placement conflict with these +other mechanisms, then cpuset placement is enforced +even if it means overriding these other mechanisms. +The kernel accomplishes this overriding by silently +restricting the CPUs and memory nodes requested by +these other mechanisms to those allowed by the +invoking process's cpuset. +This can result in these +other calls returning an error, if for example, such +a call ends up requesting an empty set of CPUs or +memory nodes, after that request is restricted to +the invoking process's cpuset. +.PP +Typically, a cpuset is used to manage +the CPU and memory-node confinement for a set of +cooperating processes such as a batch scheduler job, and these +other mechanisms are used to manage the placement of +individual processes or memory regions within that set or job. +.SH FILES +Each directory below +.I /dev/cpuset +represents a cpuset and contains a fixed set of pseudo-files +describing the state of that cpuset. +.PP +New cpusets are created using the +.BR mkdir (2) +system call or the +.BR mkdir (1) +command. +The properties of a cpuset, such as its flags, allowed +CPUs and memory nodes, and attached processes, are queried and modified +by reading or writing to the appropriate file in that cpuset's directory, +as listed below. +.PP +The pseudo-files in each cpuset directory are automatically created when +the cpuset is created, as a result of the +.BR mkdir (2) +invocation. +It is not possible to directly add or remove these pseudo-files. +.PP +A cpuset directory that contains no child cpuset directories, +and has no attached processes, can be removed using +.BR rmdir (2) +or +.BR rmdir (1). +It is not necessary, or possible, +to remove the pseudo-files inside the directory before removing it. +.PP +The pseudo-files in each cpuset directory are +small text files that may be read and +written using traditional shell utilities such as +.BR cat (1), +and +.BR echo (1), +or from a program by using file I/O library functions or system calls, +such as +.BR open (2), +.BR read (2), +.BR write (2), +and +.BR close (2). +.PP +The pseudo-files in a cpuset directory represent internal kernel +state and do not have any persistent image on disk. +Each of these per-cpuset files is listed and described below. +.\" ====================== tasks ====================== +.TP +.I tasks +List of the process IDs (PIDs) of the processes in that cpuset. +The list is formatted as a series of ASCII +decimal numbers, each followed by a newline. +A process may be added to a cpuset (automatically removing +it from the cpuset that previously contained it) by writing its +PID to that cpuset's +.I tasks +file (with or without a trailing newline). +.IP +.B Warning: +only one PID may be written to the +.I tasks +file at a time. +If a string is written that contains more +than one PID, only the first one will be used. +.\" =================== notify_on_release =================== +.TP +.I notify_on_release +Flag (0 or 1). +If set (1), that cpuset will receive special handling +after it is released, that is, after all processes cease using +it (i.e., terminate or are moved to a different cpuset) +and all child cpuset directories have been removed. +See the \fBNotify On Release\fR section, below. +.\" ====================== cpus ====================== +.TP +.I cpuset.cpus +List of the physical numbers of the CPUs on which processes +in that cpuset are allowed to execute. +See \fBList Format\fR below for a description of the +format of +.IR cpus . +.IP +The CPUs allowed to a cpuset may be changed by +writing a new list to its +.I cpus +file. +.\" ==================== cpu_exclusive ==================== +.TP +.I cpuset.cpu_exclusive +Flag (0 or 1). +If set (1), the cpuset has exclusive use of +its CPUs (no sibling or cousin cpuset may overlap CPUs). +By default, this is off (0). +Newly created cpusets also initially default this to off (0). +.IP +Two cpusets are +.I sibling +cpusets if they share the same parent cpuset in the +.I /dev/cpuset +hierarchy. +Two cpusets are +.I cousin +cpusets if neither is the ancestor of the other. +Regardless of the +.I cpu_exclusive +setting, if one cpuset is the ancestor of another, +and if both of these cpusets have nonempty +.IR cpus , +then their +.I cpus +must overlap, because the +.I cpus +of any cpuset are always a subset of the +.I cpus +of its parent cpuset. +.\" ====================== mems ====================== +.TP +.I cpuset.mems +List of memory nodes on which processes in this cpuset are +allowed to allocate memory. +See \fBList Format\fR below for a description of the +format of +.IR mems . +.\" ==================== mem_exclusive ==================== +.TP +.I cpuset.mem_exclusive +Flag (0 or 1). +If set (1), the cpuset has exclusive use of +its memory nodes (no sibling or cousin may overlap). +Also if set (1), the cpuset is a \fBHardwall\fR cpuset (see below). +By default, this is off (0). +Newly created cpusets also initially default this to off (0). +.IP +Regardless of the +.I mem_exclusive +setting, if one cpuset is the ancestor of another, +then their memory nodes must overlap, because the memory +nodes of any cpuset are always a subset of the memory nodes +of that cpuset's parent cpuset. +.\" ==================== mem_hardwall ==================== +.TP +.IR cpuset.mem_hardwall " (since Linux 2.6.26)" +Flag (0 or 1). +If set (1), the cpuset is a \fBHardwall\fR cpuset (see below). +Unlike \fBmem_exclusive\fR, +there is no constraint on whether cpusets +marked \fBmem_hardwall\fR may have overlapping +memory nodes with sibling or cousin cpusets. +By default, this is off (0). +Newly created cpusets also initially default this to off (0). +.\" ==================== memory_migrate ==================== +.TP +.IR cpuset.memory_migrate " (since Linux 2.6.16)" +Flag (0 or 1). +If set (1), then memory migration is enabled. +By default, this is off (0). +See the \fBMemory Migration\fR section, below. +.\" ==================== memory_pressure ==================== +.TP +.IR cpuset.memory_pressure " (since Linux 2.6.16)" +A measure of how much memory pressure the processes in this +cpuset are causing. +See the \fBMemory Pressure\fR section, below. +Unless +.I memory_pressure_enabled +is enabled, always has value zero (0). +This file is read-only. +See the +.B WARNINGS +section, below. +.\" ================= memory_pressure_enabled ================= +.TP +.IR cpuset.memory_pressure_enabled " (since Linux 2.6.16)" +Flag (0 or 1). +This file is present only in the root cpuset, normally +.IR /dev/cpuset . +If set (1), the +.I memory_pressure +calculations are enabled for all cpusets in the system. +By default, this is off (0). +See the +\fBMemory Pressure\fR section, below. +.\" ================== memory_spread_page ================== +.TP +.IR cpuset.memory_spread_page " (since Linux 2.6.17)" +Flag (0 or 1). +If set (1), pages in the kernel page cache +(filesystem buffers) are uniformly spread across the cpuset. +By default, this is off (0) in the top cpuset, +and inherited from the parent cpuset in +newly created cpusets. +See the \fBMemory Spread\fR section, below. +.\" ================== memory_spread_slab ================== +.TP +.IR cpuset.memory_spread_slab " (since Linux 2.6.17)" +Flag (0 or 1). +If set (1), the kernel slab caches +for file I/O (directory and inode structures) are +uniformly spread across the cpuset. +By defaultBy default, is off (0) in the top cpuset, +and inherited from the parent cpuset in +newly created cpusets. +See the \fBMemory Spread\fR section, below. +.\" ================== sched_load_balance ================== +.TP +.IR cpuset.sched_load_balance " (since Linux 2.6.24)" +Flag (0 or 1). +If set (1, the default) the kernel will +automatically load balance processes in that cpuset over +the allowed CPUs in that cpuset. +If cleared (0) the +kernel will avoid load balancing processes in this cpuset, +.I unless +some other cpuset with overlapping CPUs has its +.I sched_load_balance +flag set. +See \fBScheduler Load Balancing\fR, below, for further details. +.\" ================== sched_relax_domain_level ================== +.TP +.IR cpuset.sched_relax_domain_level " (since Linux 2.6.26)" +Integer, between \-1 and a small positive value. +The +.I sched_relax_domain_level +controls the width of the range of CPUs over which the kernel scheduler +performs immediate rebalancing of runnable tasks across CPUs. +If +.I sched_load_balance +is disabled, then the setting of +.I sched_relax_domain_level +does not matter, as no such load balancing is done. +If +.I sched_load_balance +is enabled, then the higher the value of the +.IR sched_relax_domain_level , +the wider +the range of CPUs over which immediate load balancing is attempted. +See \fBScheduler Relax Domain Level\fR, below, for further details. +.\" ================== proc cpuset ================== +.PP +In addition to the above pseudo-files in each directory below +.IR /dev/cpuset , +each process has a pseudo-file, +.IR /proc//cpuset , +that displays the path of the process's cpuset directory +relative to the root of the cpuset filesystem. +.\" ================== proc status ================== +.PP +Also the +.I /proc//status +file for each process has four added lines, +displaying the process's +.I Cpus_allowed +(on which CPUs it may be scheduled) and +.I Mems_allowed +(on which memory nodes it may obtain memory), +in the two formats \fBMask Format\fR and \fBList Format\fR (see below) +as shown in the following example: +.PP +.in +4n +.EX +Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff +Cpus_allowed_list: 0\-127 +Mems_allowed: ffffffff,ffffffff +Mems_allowed_list: 0\-63 +.EE +.in +.PP +The "allowed" fields were added in Linux 2.6.24; +the "allowed_list" fields were added in Linux 2.6.26. +.\" ================== EXTENDED CAPABILITIES ================== +.SH EXTENDED CAPABILITIES +In addition to controlling which +.I cpus +and +.I mems +a process is allowed to use, cpusets provide the following +extended capabilities. +.\" ================== Exclusive Cpusets ================== +.SS Exclusive cpusets +If a cpuset is marked +.I cpu_exclusive +or +.IR mem_exclusive , +no other cpuset, other than a direct ancestor or descendant, +may share any of the same CPUs or memory nodes. +.PP +A cpuset that is +.I mem_exclusive +restricts kernel allocations for +buffer cache pages and other internal kernel data pages +commonly shared by the kernel across +multiple users. +All cpusets, whether +.I mem_exclusive +or not, restrict allocations of memory for user space. +This enables configuring a +system so that several independent jobs can share common kernel data, +while isolating each job's user allocation in +its own cpuset. +To do this, construct a large +.I mem_exclusive +cpuset to hold all the jobs, and construct child, +.RI non- mem_exclusive +cpusets for each individual job. +Only a small amount of kernel memory, +such as requests from interrupt handlers, is allowed to be +placed on memory nodes +outside even a +.I mem_exclusive +cpuset. +.\" ================== Hardwall ================== +.SS Hardwall +A cpuset that has +.I mem_exclusive +or +.I mem_hardwall +set is a +.I hardwall +cpuset. +A +.I hardwall +cpuset restricts kernel allocations for page, buffer, +and other data commonly shared by the kernel across multiple users. +All cpusets, whether +.I hardwall +or not, restrict allocations of memory for user space. +.PP +This enables configuring a system so that several independent +jobs can share common kernel data, such as filesystem pages, +while isolating each job's user allocation in its own cpuset. +To do this, construct a large +.I hardwall +cpuset to hold +all the jobs, and construct child cpusets for each individual +job which are not +.I hardwall +cpusets. +.PP +Only a small amount of kernel memory, such as requests from +interrupt handlers, is allowed to be taken outside even a +.I hardwall +cpuset. +.\" ================== Notify On Release ================== +.SS Notify on release +If the +.I notify_on_release +flag is enabled (1) in a cpuset, +then whenever the last process in the cpuset leaves +(exits or attaches to some other cpuset) +and the last child cpuset of that cpuset is removed, +the kernel will run the command +.IR /sbin/cpuset_release_agent , +supplying the pathname (relative to the mount point of the +cpuset filesystem) of the abandoned cpuset. +This enables automatic removal of abandoned cpusets. +.PP +The default value of +.I notify_on_release +in the root cpuset at system boot is disabled (0). +The default value of other cpusets at creation +is the current value of their parent's +.I notify_on_release +setting. +.PP +The command +.I /sbin/cpuset_release_agent +is invoked, with the name +.RI ( /dev/cpuset +relative path) +of the to-be-released cpuset in +.IR argv[1] . +.PP +The usual contents of the command +.I /sbin/cpuset_release_agent +is simply the shell script: +.PP +.in +4n +.EX +#!/bin/sh +rmdir /dev/cpuset/$1 +.EE +.in +.PP +As with other flag values below, this flag can +be changed by writing an ASCII +number 0 or 1 (with optional trailing newline) +into the file, to clear or set the flag, respectively. +.\" ================== Memory Pressure ================== +.SS Memory pressure +The +.I memory_pressure +of a cpuset provides a simple per-cpuset running average of +the rate that the processes in a cpuset are attempting to free up in-use +memory on the nodes of the cpuset to satisfy additional memory requests. +.PP +This enables batch managers that are monitoring jobs running in dedicated +cpusets to efficiently detect what level of memory pressure that job +is causing. +.PP +This is useful both on tightly managed systems running a wide mix of +submitted jobs, which may choose to terminate or reprioritize jobs that +are trying to use more memory than allowed on the nodes assigned them, +and with tightly coupled, long-running, massively parallel scientific +computing jobs that will dramatically fail to meet required performance +goals if they start to use more memory than allowed to them. +.PP +This mechanism provides a very economical way for the batch manager +to monitor a cpuset for signs of memory pressure. +It's up to the batch manager or other user code to decide +what action to take if it detects signs of memory pressure. +.PP +Unless memory pressure calculation is enabled by setting the pseudo-file +.IR /dev/cpuset/cpuset.memory_pressure_enabled , +it is not computed for any cpuset, and reads from any +.I memory_pressure +always return zero, as represented by the ASCII string "0\en". +See the \fBWARNINGS\fR section, below. +.PP +A per-cpuset, running average is employed for the following reasons: +.IP * 3 +Because this meter is per-cpuset rather than per-process or per virtual +memory region, the system load imposed by a batch scheduler monitoring +this metric is sharply reduced on large systems, because a scan of +the tasklist can be avoided on each set of queries. +.IP * +Because this meter is a running average rather than an accumulating +counter, a batch scheduler can detect memory pressure with a +single read, instead of having to read and accumulate results +for a period of time. +.IP * +Because this meter is per-cpuset rather than per-process, +the batch scheduler can obtain the key information\(emmemory +pressure in a cpuset\(emwith a single read, rather than having to +query and accumulate results over all the (dynamically changing) +set of processes in the cpuset. +.PP +The +.I memory_pressure +of a cpuset is calculated using a per-cpuset simple digital filter +that is kept within the kernel. +For each cpuset, this filter tracks +the recent rate at which processes attached to that cpuset enter the +kernel direct reclaim code. +.PP +The kernel direct reclaim code is entered whenever a process has to +satisfy a memory page request by first finding some other page to +repurpose, due to lack of any readily available already free pages. +Dirty filesystem pages are repurposed by first writing them +to disk. +Unmodified filesystem buffer pages are repurposed +by simply dropping them, though if that page is needed again, it +will have to be reread from disk. +.PP +The +.I cpuset.memory_pressure +file provides an integer number representing the recent (half-life of +10 seconds) rate of entries to the direct reclaim code caused by any +process in the cpuset, in units of reclaims attempted per second, +times 1000. +.\" ================== Memory Spread ================== +.SS Memory spread +There are two Boolean flag files per cpuset that control where the +kernel allocates pages for the filesystem buffers and related +in-kernel data structures. +They are called +.I cpuset.memory_spread_page +and +.IR cpuset.memory_spread_slab . +.PP +If the per-cpuset Boolean flag file +.I cpuset.memory_spread_page +is set, then +the kernel will spread the filesystem buffers (page cache) evenly +over all the nodes that the faulting process is allowed to use, instead +of preferring to put those pages on the node where the process is running. +.PP +If the per-cpuset Boolean flag file +.I cpuset.memory_spread_slab +is set, +then the kernel will spread some filesystem-related slab caches, +such as those for inodes and directory entries, evenly over all the nodes +that the faulting process is allowed to use, instead of preferring to +put those pages on the node where the process is running. +.PP +The setting of these flags does not affect the data segment +(see +.BR brk (2)) +or stack segment pages of a process. +.PP +By default, both kinds of memory spreading are off and the kernel +prefers to allocate memory pages on the node local to where the +requesting process is running. +If that node is not allowed by the +process's NUMA memory policy or cpuset configuration or if there are +insufficient free memory pages on that node, then the kernel looks +for the nearest node that is allowed and has sufficient free memory. +.PP +When new cpusets are created, they inherit the memory spread settings +of their parent. +.PP +Setting memory spreading causes allocations for the affected page or +slab caches to ignore the process's NUMA memory policy and be spread +instead. +However, the effect of these changes in memory placement +caused by cpuset-specified memory spreading is hidden from the +.BR mbind (2) +or +.BR set_mempolicy (2) +calls. +These two NUMA memory policy calls always appear to behave as if +no cpuset-specified memory spreading is in effect, even if it is. +If cpuset memory spreading is subsequently turned off, the NUMA +memory policy most recently specified by these calls is automatically +reapplied. +.PP +Both +.I cpuset.memory_spread_page +and +.I cpuset.memory_spread_slab +are Boolean flag files. +By default, they contain "0", meaning that the feature is off +for that cpuset. +If a "1" is written to that file, that turns the named feature on. +.PP +Cpuset-specified memory spreading behaves similarly to what is known +(in other contexts) as round-robin or interleave memory placement. +.PP +Cpuset-specified memory spreading can provide substantial performance +improvements for jobs that: +.IP a) 3 +need to place thread-local data on +memory nodes close to the CPUs which are running the threads that most +frequently access that data; but also +.IP b) +need to access large filesystem data sets that must to be spread +across the several nodes in the job's cpuset in order to fit. +.PP +Without this policy, +the memory allocation across the nodes in the job's cpuset +can become very uneven, +especially for jobs that might have just a single +thread initializing or reading in the data set. +.\" ================== Memory Migration ================== +.SS Memory migration +Normally, under the default setting (disabled) of +.IR cpuset.memory_migrate , +once a page is allocated (given a physical page +of main memory), then that page stays on whatever node it +was allocated, so long as it remains allocated, even if the +cpuset's memory-placement policy +.I mems +subsequently changes. +.PP +When memory migration is enabled in a cpuset, if the +.I mems +setting of the cpuset is changed, then any memory page in use by any +process in the cpuset that is on a memory node that is no longer +allowed will be migrated to a memory node that is allowed. +.PP +Furthermore, if a process is moved into a cpuset with +.I memory_migrate +enabled, any memory pages it uses that were on memory nodes allowed +in its previous cpuset, but which are not allowed in its new cpuset, +will be migrated to a memory node allowed in the new cpuset. +.PP +The relative placement of a migrated page within +the cpuset is preserved during these migration operations if possible. +For example, +if the page was on the second valid node of the prior cpuset, +then the page will be placed on the second valid node of the new cpuset, +if possible. +.\" ================== Scheduler Load Balancing ================== +.SS Scheduler load balancing +The kernel scheduler automatically load balances processes. +If one CPU is underutilized, +the kernel will look for processes on other more +overloaded CPUs and move those processes to the underutilized CPU, +within the constraints of such placement mechanisms as cpusets and +.BR sched_setaffinity (2). +.PP +The algorithmic cost of load balancing and its impact on key shared +kernel data structures such as the process list increases more than +linearly with the number of CPUs being balanced. +For example, it +costs more to load balance across one large set of CPUs than it does +to balance across two smaller sets of CPUs, each of half the size +of the larger set. +(The precise relationship between the number of CPUs being balanced +and the cost of load balancing depends +on implementation details of the kernel process scheduler, which is +subject to change over time, as improved kernel scheduler algorithms +are implemented.) +.PP +The per-cpuset flag +.I sched_load_balance +provides a mechanism to suppress this automatic scheduler load +balancing in cases where it is not needed and suppressing it would have +worthwhile performance benefits. +.PP +By default, load balancing is done across all CPUs, except those +marked isolated using the kernel boot time "isolcpus=" argument. +(See \fBScheduler Relax Domain Level\fR, below, to change this default.) +.PP +This default load balancing across all CPUs is not well suited to +the following two situations: +.IP * 3 +On large systems, load balancing across many CPUs is expensive. +If the system is managed using cpusets to place independent jobs +on separate sets of CPUs, full load balancing is unnecessary. +.IP * +Systems supporting real-time on some CPUs need to minimize +system overhead on those CPUs, including avoiding process load +balancing if that is not needed. +.PP +When the per-cpuset flag +.I sched_load_balance +is enabled (the default setting), +it requests load balancing across +all the CPUs in that cpuset's allowed CPUs, +ensuring that load balancing can move a process (not otherwise pinned, +as by +.BR sched_setaffinity (2)) +from any CPU in that cpuset to any other. +.PP +When the per-cpuset flag +.I sched_load_balance +is disabled, then the +scheduler will avoid load balancing across the CPUs in that cpuset, +\fIexcept\fR in so far as is necessary because some overlapping cpuset +has +.I sched_load_balance +enabled. +.PP +So, for example, if the top cpuset has the flag +.I sched_load_balance +enabled, then the scheduler will load balance across all +CPUs, and the setting of the +.I sched_load_balance +flag in other cpusets has no effect, +as we're already fully load balancing. +.PP +Therefore in the above two situations, the flag +.I sched_load_balance +should be disabled in the top cpuset, and only some of the smaller, +child cpusets would have this flag enabled. +.PP +When doing this, you don't usually want to leave any unpinned processes in +the top cpuset that might use nontrivial amounts of CPU, as such processes +may be artificially constrained to some subset of CPUs, depending on +the particulars of this flag setting in descendant cpusets. +Even if such a process could use spare CPU cycles in some other CPUs, +the kernel scheduler might not consider the possibility of +load balancing that process to the underused CPU. +.PP +Of course, processes pinned to a particular CPU can be left in a cpuset +that disables +.I sched_load_balance +as those processes aren't going anywhere else anyway. +.\" ================== Scheduler Relax Domain Level ================== +.SS Scheduler relax domain level +The kernel scheduler performs immediate load balancing whenever +a CPU becomes free or another task becomes runnable. +This load +balancing works to ensure that as many CPUs as possible are usefully +employed running tasks. +The kernel also performs periodic load +balancing off the software clock described in +.BR time (7). +The setting of +.I sched_relax_domain_level +applies only to immediate load balancing. +Regardless of the +.I sched_relax_domain_level +setting, periodic load balancing is attempted over all CPUs +(unless disabled by turning off +.IR sched_load_balance .) +In any case, of course, tasks will be scheduled to run only on +CPUs allowed by their cpuset, as modified by +.BR sched_setaffinity (2) +system calls. +.PP +On small systems, such as those with just a few CPUs, immediate load +balancing is useful to improve system interactivity and to minimize +wasteful idle CPU cycles. +But on large systems, attempting immediate +load balancing across a large number of CPUs can be more costly than +it is worth, depending on the particular performance characteristics +of the job mix and the hardware. +.PP +The exact meaning of the small integer values of +.I sched_relax_domain_level +will depend on internal +implementation details of the kernel scheduler code and on the +non-uniform architecture of the hardware. +Both of these will evolve +over time and vary by system architecture and kernel version. +.PP +As of this writing, when this capability was introduced in Linux +2.6.26, on certain popular architectures, the positive values of +.I sched_relax_domain_level +have the following meanings. +.PP +.PD 0 +.IP \fB(1)\fR 4 +Perform immediate load balancing across Hyper-Thread +siblings on the same core. +.IP \fB(2)\fR +Perform immediate load balancing across other cores in the same package. +.IP \fB(3)\fR +Perform immediate load balancing across other CPUs +on the same node or blade. +.IP \fB(4)\fR +Perform immediate load balancing across over several +(implementation detail) nodes [On NUMA systems]. +.IP \fB(5)\fR +Perform immediate load balancing across over all CPUs +in system [On NUMA systems]. +.PD +.PP +The +.I sched_relax_domain_level +value of zero (0) always means +don't perform immediate load balancing, +hence that load balancing is done only periodically, +not immediately when a CPU becomes available or another task becomes +runnable. +.PP +The +.I sched_relax_domain_level +value of minus one (\-1) +always means use the system default value. +The system default value can vary by architecture and kernel version. +This system default value can be changed by kernel +boot-time "relax_domain_level=" argument. +.PP +In the case of multiple overlapping cpusets which have conflicting +.I sched_relax_domain_level +values, then the highest such value +applies to all CPUs in any of the overlapping cpusets. +In such cases, +the value \fBminus one (\-1)\fR is the lowest value, overridden by any +other value, and the value \fBzero (0)\fR is the next lowest value. +.SH FORMATS +The following formats are used to represent sets of +CPUs and memory nodes. +.\" ================== Mask Format ================== +.SS Mask format +The \fBMask Format\fR is used to represent CPU and memory-node bit masks +in the +.I /proc//status +file. +.PP +This format displays each 32-bit +word in hexadecimal (using ASCII characters "0" - "9" and "a" - "f"); +words are filled with leading zeros, if required. +For masks longer than one word, a comma separator is used between words. +Words are displayed in big-endian +order, which has the most significant bit first. +The hex digits within a word are also in big-endian order. +.PP +The number of 32-bit words displayed is the minimum number needed to +display all bits of the bit mask, based on the size of the bit mask. +.PP +Examples of the \fBMask Format\fR: +.PP +.in +4n +.EX +00000001 # just bit 0 set +40000000,00000000,00000000 # just bit 94 set +00000001,00000000,00000000 # just bit 64 set +000000ff,00000000 # bits 32\-39 set +00000000,000e3862 # 1,5,6,11\-13,17\-19 set +.EE +.in +.PP +A mask with bits 0, 1, 2, 4, 8, 16, 32, and 64 set displays as: +.PP +.in +4n +.EX +00000001,00000001,00010117 +.EE +.in +.PP +The first "1" is for bit 64, the +second for bit 32, the third for bit 16, the fourth for bit 8, the +fifth for bit 4, and the "7" is for bits 2, 1, and 0. +.\" ================== List Format ================== +.SS List format +The \fBList Format\fR for +.I cpus +and +.I mems +is a comma-separated list of CPU or memory-node +numbers and ranges of numbers, in ASCII decimal. +.PP +Examples of the \fBList Format\fR: +.PP +.in +4n +.EX +0\-4,9 # bits 0, 1, 2, 3, 4, and 9 set +0\-2,7,12\-14 # bits 0, 1, 2, 7, 12, 13, and 14 set +.EE +.in +.\" ================== RULES ================== +.SH RULES +The following rules apply to each cpuset: +.IP * 3 +Its CPUs and memory nodes must be a (possibly equal) +subset of its parent's. +.IP * +It can be marked +.IR cpu_exclusive +only if its parent is. +.IP * +It can be marked +.IR mem_exclusive +only if its parent is. +.IP * +If it is +.IR cpu_exclusive , +its CPUs may not overlap any sibling. +.IP * +If it is +.IR memory_exclusive , +its memory nodes may not overlap any sibling. +.\" ================== PERMISSIONS ================== +.SH PERMISSIONS +The permissions of a cpuset are determined by the permissions +of the directories and pseudo-files in the cpuset filesystem, +normally mounted at +.IR /dev/cpuset . +.PP +For instance, a process can put itself in some other cpuset (than +its current one) if it can write the +.I tasks +file for that cpuset. +This requires execute permission on the encompassing directories +and write permission on the +.I tasks +file. +.PP +An additional constraint is applied to requests to place some +other process in a cpuset. +One process may not attach another to +a cpuset unless it would have permission to send that process +a signal (see +.BR kill (2)). +.PP +A process may create a child cpuset if it can access and write the +parent cpuset directory. +It can modify the CPUs or memory nodes +in a cpuset if it can access that cpuset's directory (execute +permissions on the each of the parent directories) and write the +corresponding +.I cpus +or +.I mems +file. +.PP +There is one minor difference between the manner in which these +permissions are evaluated and the manner in which normal filesystem +operation permissions are evaluated. +The kernel interprets +relative pathnames starting at a process's current working directory. +Even if one is operating on a cpuset file, relative pathnames +are interpreted relative to the process's current working directory, +not relative to the process's current cpuset. +The only ways that +cpuset paths relative to a process's current cpuset can be used are +if either the process's current working directory is its cpuset +(it first did a +.B cd +or +.BR chdir (2) +to its cpuset directory beneath +.IR /dev/cpuset , +which is a bit unusual) +or if some user code converts the relative cpuset path to a +full filesystem path. +.PP +In theory, this means that user code should specify cpusets +using absolute pathnames, which requires knowing the mount point of +the cpuset filesystem (usually, but not necessarily, +.IR /dev/cpuset ). +In practice, all user level code that this author is aware of +simply assumes that if the cpuset filesystem is mounted, then +it is mounted at +.IR /dev/cpuset . +Furthermore, it is common practice for carefully written +user code to verify the presence of the pseudo-file +.I /dev/cpuset/tasks +in order to verify that the cpuset pseudo-filesystem +is currently mounted. +.\" ================== WARNINGS ================== +.SH WARNINGS +.SS Enabling memory_pressure +By default, the per-cpuset file +.I cpuset.memory_pressure +always contains zero (0). +Unless this feature is enabled by writing "1" to the pseudo-file +.IR /dev/cpuset/cpuset.memory_pressure_enabled , +the kernel does +not compute per-cpuset +.IR memory_pressure . +.SS Using the echo command +When using the +.B echo +command at the shell prompt to change the values of cpuset files, +beware that the built-in +.B echo +command in some shells does not display an error message if the +.BR write (2) +system call fails. +.\" Gack! csh(1)'s echo does this +For example, if the command: +.PP +.in +4n +.EX +echo 19 > cpuset.mems +.EE +.in +.PP +failed because memory node 19 was not allowed (perhaps +the current system does not have a memory node 19), then the +.B echo +command might not display any error. +It is better to use the +.B /bin/echo +external command to change cpuset file settings, as this +command will display +.BR write (2) +errors, as in the example: +.PP +.in +4n +.EX +/bin/echo 19 > cpuset.mems +/bin/echo: write error: Invalid argument +.EE +.in +.\" ================== EXCEPTIONS ================== +.SH EXCEPTIONS +.SS Memory placement +Not all allocations of system memory are constrained by cpusets, +for the following reasons. +.PP +If hot-plug functionality is used to remove all the CPUs that are +currently assigned to a cpuset, then the kernel will automatically +update the +.I cpus_allowed +of all processes attached to CPUs in that cpuset +to allow all CPUs. +When memory hot-plug functionality for removing +memory nodes is available, a similar exception is expected to apply +there as well. +In general, the kernel prefers to violate cpuset placement, +rather than starving a process that has had all its allowed CPUs or +memory nodes taken offline. +User code should reconfigure cpusets to refer only to online CPUs +and memory nodes when using hot-plug to add or remove such resources. +.PP +A few kernel-critical, internal memory-allocation requests, marked +GFP_ATOMIC, must be satisfied immediately. +The kernel may drop some +request or malfunction if one of these allocations fail. +If such a request cannot be satisfied within the current process's cpuset, +then we relax the cpuset, and look for memory anywhere we can find it. +It's better to violate the cpuset than stress the kernel. +.PP +Allocations of memory requested by kernel drivers while processing +an interrupt lack any relevant process context, and are not confined +by cpusets. +.SS Renaming cpusets +You can use the +.BR rename (2) +system call to rename cpusets. +Only simple renaming is supported; that is, changing the name of a cpuset +directory is permitted, but moving a directory into +a different directory is not permitted. +.\" ================== ERRORS ================== +.SH ERRORS +The Linux kernel implementation of cpusets sets +.I errno +to specify the reason for a failed system call affecting cpusets. +.PP +The possible +.I errno +settings and their meaning when set on +a failed cpuset call are as listed below. +.TP +.B E2BIG +Attempted a +.BR write (2) +on a special cpuset file +with a length larger than some kernel-determined upper +limit on the length of such writes. +.TP +.B EACCES +Attempted to +.BR write (2) +the process ID (PID) of a process to a cpuset +.I tasks +file when one lacks permission to move that process. +.TP +.B EACCES +Attempted to add, using +.BR write (2), +a CPU or memory node to a cpuset, when that CPU or memory node was +not already in its parent. +.TP +.B EACCES +Attempted to set, using +.BR write (2), +.I cpuset.cpu_exclusive +or +.I cpuset.mem_exclusive +on a cpuset whose parent lacks the same setting. +.TP +.B EACCES +Attempted to +.BR write (2) +a +.I cpuset.memory_pressure +file. +.TP +.B EACCES +Attempted to create a file in a cpuset directory. +.TP +.B EBUSY +Attempted to remove, using +.BR rmdir (2), +a cpuset with attached processes. +.TP +.B EBUSY +Attempted to remove, using +.BR rmdir (2), +a cpuset with child cpusets. +.TP +.B EBUSY +Attempted to remove +a CPU or memory node from a cpuset +that is also in a child of that cpuset. +.TP +.B EEXIST +Attempted to create, using +.BR mkdir (2), +a cpuset that already exists. +.TP +.B EEXIST +Attempted to +.BR rename (2) +a cpuset to a name that already exists. +.TP +.B EFAULT +Attempted to +.BR read (2) +or +.BR write (2) +a cpuset file using +a buffer that is outside the writing processes accessible address space. +.TP +.B EINVAL +Attempted to change a cpuset, using +.BR write (2), +in a way that would violate a +.I cpu_exclusive +or +.I mem_exclusive +attribute of that cpuset or any of its siblings. +.TP +.B EINVAL +Attempted to +.BR write (2) +an empty +.I cpuset.cpus +or +.I cpuset.mems +list to a cpuset which has attached processes or child cpusets. +.TP +.B EINVAL +Attempted to +.BR write (2) +a +.I cpuset.cpus +or +.I cpuset.mems +list which included a range with the second number smaller than +the first number. +.TP +.B EINVAL +Attempted to +.BR write (2) +a +.I cpuset.cpus +or +.I cpuset.mems +list which included an invalid character in the string. +.TP +.B EINVAL +Attempted to +.BR write (2) +a list to a +.I cpuset.cpus +file that did not include any online CPUs. +.TP +.B EINVAL +Attempted to +.BR write (2) +a list to a +.I cpuset.mems +file that did not include any online memory nodes. +.TP +.B EINVAL +Attempted to +.BR write (2) +a list to a +.I cpuset.mems +file that included a node that held no memory. +.TP +.B EIO +Attempted to +.BR write (2) +a string to a cpuset +.I tasks +file that +does not begin with an ASCII decimal integer. +.TP +.B EIO +Attempted to +.BR rename (2) +a cpuset into a different directory. +.TP +.B ENAMETOOLONG +Attempted to +.BR read (2) +a +.I /proc//cpuset +file for a cpuset path that is longer than the kernel page size. +.TP +.B ENAMETOOLONG +Attempted to create, using +.BR mkdir (2), +a cpuset whose base directory name is longer than 255 characters. +.TP +.B ENAMETOOLONG +Attempted to create, using +.BR mkdir (2), +a cpuset whose full pathname, +including the mount point (typically "/dev/cpuset/") prefix, +is longer than 4095 characters. +.TP +.B ENODEV +The cpuset was removed by another process at the same time as a +.BR write (2) +was attempted on one of the pseudo-files in the cpuset directory. +.TP +.B ENOENT +Attempted to create, using +.BR mkdir (2), +a cpuset in a parent cpuset that doesn't exist. +.TP +.B ENOENT +Attempted to +.BR access (2) +or +.BR open (2) +a nonexistent file in a cpuset directory. +.TP +.B ENOMEM +Insufficient memory is available within the kernel; can occur +on a variety of system calls affecting cpusets, but only if the +system is extremely short of memory. +.TP +.B ENOSPC +Attempted to +.BR write (2) +the process ID (PID) +of a process to a cpuset +.I tasks +file when the cpuset had an empty +.I cpuset.cpus +or empty +.I cpuset.mems +setting. +.TP +.B ENOSPC +Attempted to +.BR write (2) +an empty +.I cpuset.cpus +or +.I cpuset.mems +setting to a cpuset that +has tasks attached. +.TP +.B ENOTDIR +Attempted to +.BR rename (2) +a nonexistent cpuset. +.TP +.B EPERM +Attempted to remove a file from a cpuset directory. +.TP +.B ERANGE +Specified a +.I cpuset.cpus +or +.I cpuset.mems +list to the kernel which included a number too large for the kernel +to set in its bit masks. +.TP +.B ESRCH +Attempted to +.BR write (2) +the process ID (PID) of a nonexistent process to a cpuset +.I tasks +file. +.\" ================== VERSIONS ================== +.SH VERSIONS +Cpusets appeared in version 2.6.12 of the Linux kernel. +.\" ================== NOTES ================== +.SH NOTES +Despite its name, the +.I pid +parameter is actually a thread ID, +and each thread in a threaded group can be attached to a different +cpuset. +The value returned from a call to +.BR gettid (2) +can be passed in the argument +.IR pid . +.\" ================== BUGS ================== +.SH BUGS +.I cpuset.memory_pressure +cpuset files can be opened +for writing, creation, or truncation, but then the +.BR write (2) +fails with +.I errno +set to +.BR EACCES , +and the creation and truncation options on +.BR open (2) +have no effect. +.\" ================== EXAMPLE ================== +.SH EXAMPLE +The following examples demonstrate querying and setting cpuset +options using shell commands. +.SS Creating and attaching to a cpuset. +To create a new cpuset and attach the current command shell to it, +the steps are: +.PP +.PD 0 +.IP 1) 4 +mkdir /dev/cpuset (if not already done) +.IP 2) +mount \-t cpuset none /dev/cpuset (if not already done) +.IP 3) +Create the new cpuset using +.BR mkdir (1). +.IP 4) +Assign CPUs and memory nodes to the new cpuset. +.IP 5) +Attach the shell to the new cpuset. +.PD +.PP +For example, the following sequence of commands will set up a cpuset +named "Charlie", containing just CPUs 2 and 3, and memory node 1, +and then attach the current shell to that cpuset. +.PP +.in +4n +.EX +.RB "$" " mkdir /dev/cpuset" +.RB "$" " mount \-t cpuset cpuset /dev/cpuset" +.RB "$" " cd /dev/cpuset" +.RB "$" " mkdir Charlie" +.RB "$" " cd Charlie" +.RB "$" " /bin/echo 2\-3 > cpuset.cpus" +.RB "$" " /bin/echo 1 > cpuset.mems" +.RB "$" " /bin/echo $$ > tasks" +# The current shell is now running in cpuset Charlie +# The next line should display '/Charlie' +.RB "$" " cat /proc/self/cpuset" +.EE +.in +.\" +.SS Migrating a job to different memory nodes. +To migrate a job (the set of processes attached to a cpuset) +to different CPUs and memory nodes in the system, including moving +the memory pages currently allocated to that job, +perform the following steps. +.PP +.PD 0 +.IP 1) 4 +Let's say we want to move the job in cpuset +.I alpha +(CPUs 4\(en7 and memory nodes 2\(en3) to a new cpuset +.I beta +(CPUs 16\(en19 and memory nodes 8\(en9). +.IP 2) +First create the new cpuset +.IR beta . +.IP 3) +Then allow CPUs 16\(en19 and memory nodes 8\(en9 in +.IR beta . +.IP 4) +Then enable +.I memory_migration +in +.IR beta . +.IP 5) +Then move each process from +.I alpha +to +.IR beta . +.PD +.PP +The following sequence of commands accomplishes this. +.PP +.in +4n +.EX +.RB "$" " cd /dev/cpuset" +.RB "$" " mkdir beta" +.RB "$" " cd beta" +.RB "$" " /bin/echo 16\-19 > cpuset.cpus" +.RB "$" " /bin/echo 8\-9 > cpuset.mems" +.RB "$" " /bin/echo 1 > cpuset.memory_migrate" +.RB "$" " while read i; do /bin/echo $i; done < ../alpha/tasks > tasks" +.EE +.in +.PP +The above should move any processes in +.I alpha +to +.IR beta , +and any memory held by these processes on memory nodes 2\(en3 to memory +nodes 8\(en9, respectively. +.PP +Notice that the last step of the above sequence did not do: +.PP +.in +4n +.EX +.RB "$" " cp ../alpha/tasks tasks" +.EE +.in +.PP +The +.I while +loop, rather than the seemingly easier use of the +.BR cp (1) +command, was necessary because +only one process PID at a time may be written to the +.I tasks +file. +.PP +The same effect (writing one PID at a time) as the +.I while +loop can be accomplished more efficiently, in fewer keystrokes and in +syntax that works on any shell, but alas more obscurely, by using the +.B \-u +(unbuffered) option of +.BR sed (1): +.PP +.in +4n +.EX +.RB "$" " sed \-un p < ../alpha/tasks > tasks" +.EE +.in +.\" ================== SEE ALSO ================== +.SH SEE ALSO +.BR taskset (1), +.BR get_mempolicy (2), +.BR getcpu (2), +.BR mbind (2), +.BR sched_getaffinity (2), +.BR sched_setaffinity (2), +.BR sched_setscheduler (2), +.BR set_mempolicy (2), +.BR CPU_SET (3), +.BR proc (5), +.BR cgroups (7), +.BR numa (7), +.BR sched (7), +.BR migratepages (8), +.BR numactl (8) +.PP +.IR Documentation/cgroup\-v1/cpusets.txt +in the Linux kernel source tree +.\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8 +(or +.IR Documentation/cpusets.txt +before Linux 2.6.29) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/credentials.7 b/man7/credentials.7 new file mode 100644 index 0000000..e3acf3e --- /dev/null +++ b/man7/credentials.7 @@ -0,0 +1,365 @@ +.\" Copyright (c) 2007 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-06-13 Creation +.\" +.TH CREDENTIALS 7 2016-12-12 "Linux" "Linux Programmer's Manual" +.SH NAME +credentials \- process identifiers +.SH DESCRIPTION +.SS Process ID (PID) +Each process has a unique nonnegative integer identifier +that is assigned when the process is created using +.BR fork (2). +A process can obtain its PID using +.BR getpid (2). +A PID is represented using the type +.I pid_t +(defined in +.IR ). +.PP +PIDs are used in a range of system calls to identify the process +affected by the call, for example: +.BR kill (2), +.BR ptrace (2), +.BR setpriority (2) +.\" .BR sched_rr_get_interval (2), +.\" .BR sched_getaffinity (2), +.\" .BR sched_setaffinity (2), +.\" .BR sched_getparam (2), +.\" .BR sched_setparam (2), +.\" .BR sched_setscheduler (2), +.\" .BR sched_getscheduler (2), +.BR setpgid (2), +.\" .BR getsid (2), +.BR setsid (2), +.BR sigqueue (3), +and +.BR waitpid (2). +.\" .BR waitid (2), +.\" .BR wait4 (2), +.PP +A process's PID is preserved across an +.BR execve (2). +.SS Parent process ID (PPID) +A process's parent process ID identifies the process that created +this process using +.BR fork (2). +A process can obtain its PPID using +.BR getppid (2). +A PPID is represented using the type +.IR pid_t . +.PP +A process's PPID is preserved across an +.BR execve (2). +.SS Process group ID and session ID +Each process has a session ID and a process group ID, +both represented using the type +.IR pid_t . +A process can obtain its session ID using +.BR getsid (2), +and its process group ID using +.BR getpgrp (2). +.PP +A child created by +.BR fork (2) +inherits its parent's session ID and process group ID. +A process's session ID and process group ID are preserved across an +.BR execve (2). +.PP +Sessions and process groups are abstractions devised to support shell +job control. +A process group (sometimes called a "job") is a collection of +processes that share the same process group ID; +the shell creates a new process group for the process(es) used +to execute single command or pipeline (e.g., the two processes +created to execute the command "ls\ |\ wc" are placed in the +same process group). +A process's group membership can be set using +.BR setpgid (2). +The process whose process ID is the same as its process group ID is the +\fIprocess group leader\fP for that group. +.PP +A session is a collection of processes that share the same session ID. +All of the members of a process group also have the same session ID +(i.e., all of the members of a process group always belong to the +same session, so that sessions and process groups form a strict +two-level hierarchy of processes.) +A new session is created when a process calls +.BR setsid (2), +which creates a new session whose session ID is the same +as the PID of the process that called +.BR setsid (2). +The creator of the session is called the \fIsession leader\fP. +.PP +All of the processes in a session share a +.IR "controlling terminal" . +The controlling terminal is established when the session leader +first opens a terminal (unless the +.BR O_NOCTTY +flag is specified when calling +.BR open (2)). +A terminal may be the controlling terminal of at most one session. +.PP +At most one of the jobs in a session may be the +.IR "foreground job" ; +other jobs in the session are +.IR "background jobs" . +Only the foreground job may read from the terminal; +when a process in the background attempts to read from the terminal, +its process group is sent a +.BR SIGTTIN +signal, which suspends the job. +If the +.BR TOSTOP +flag has been set for the terminal (see +.BR termios (3)), +then only the foreground job may write to the terminal; +writes from background job cause a +.BR SIGTTOU +signal to be generated, which suspends the job. +When terminal keys that generate a signal (such as the +.I interrupt +key, normally control-C) +are pressed, the signal is sent to the processes in the foreground job. +.PP +Various system calls and library functions +may operate on all members of a process group, +including +.BR kill (2), +.BR killpg (3), +.BR getpriority (2), +.BR setpriority (2), +.BR ioprio_get (2), +.BR ioprio_set (2), +.BR waitid (2), +and +.BR waitpid (2). +See also the discussion of the +.BR F_GETOWN , +.BR F_GETOWN_EX , +.BR F_SETOWN , +and +.BR F_SETOWN_EX +operations in +.BR fcntl (2). +.SS User and group identifiers +Each process has various associated user and group IDs. +These IDs are integers, respectively represented using the types +.I uid_t +and +.I gid_t +(defined in +.IR ). +.PP +On Linux, each process has the following user and group identifiers: +.IP * 3 +Real user ID and real group ID. +These IDs determine who owns the process. +A process can obtain its real user (group) ID using +.BR getuid (2) +.RB ( getgid (2)). +.IP * +Effective user ID and effective group ID. +These IDs are used by the kernel to determine the permissions +that the process will have when accessing shared resources such +as message queues, shared memory, and semaphores. +On most UNIX systems, these IDs also determine the +permissions when accessing files. +However, Linux uses the filesystem IDs described below +for this task. +A process can obtain its effective user (group) ID using +.BR geteuid (2) +.RB ( getegid (2)). +.IP * +Saved set-user-ID and saved set-group-ID. +These IDs are used in set-user-ID and set-group-ID programs to save +a copy of the corresponding effective IDs that were set when +the program was executed (see +.BR execve (2)). +A set-user-ID program can assume and drop privileges by +switching its effective user ID back and forth between the values +in its real user ID and saved set-user-ID. +This switching is done via calls to +.BR seteuid (2), +.BR setreuid (2), +or +.BR setresuid (2). +A set-group-ID program performs the analogous tasks using +.BR setegid (2), +.BR setregid (2), +or +.BR setresgid (2). +A process can obtain its saved set-user-ID (set-group-ID) using +.BR getresuid (2) +.RB ( getresgid (2)). +.IP * +Filesystem user ID and filesystem group ID (Linux-specific). +These IDs, in conjunction with the supplementary group IDs described +below, are used to determine permissions for accessing files; see +.BR path_resolution (7) +for details. +Whenever a process's effective user (group) ID is changed, +the kernel also automatically changes the filesystem user (group) ID +to the same value. +Consequently, the filesystem IDs normally have the same values +as the corresponding effective ID, and the semantics for file-permission +checks are thus the same on Linux as on other UNIX systems. +The filesystem IDs can be made to differ from the effective IDs +by calling +.BR setfsuid (2) +and +.BR setfsgid (2). +.IP * +Supplementary group IDs. +This is a set of additional group IDs that are used for permission +checks when accessing files and other shared resources. +On Linux kernels before 2.6.4, +a process can be a member of up to 32 supplementary groups; +since kernel 2.6.4, +a process can be a member of up to 65536 supplementary groups. +The call +.I sysconf(_SC_NGROUPS_MAX) +can be used to determine the number of supplementary groups +of which a process may be a member. +.\" Since kernel 2.6.4, the limit is visible via the read-only file +.\" /proc/sys/kernel/ngroups_max. +.\" As at 2.6.22-rc2, this file is still read-only. +A process can obtain its set of supplementary group IDs using +.BR getgroups (2), +and can modify the set using +.BR setgroups (2). +.PP +A child process created by +.BR fork (2) +inherits copies of its parent's user and groups IDs. +During an +.BR execve (2), +a process's real user and group ID and supplementary +group IDs are preserved; +the effective and saved set IDs may be changed, as described in +.BR execve (2). +.PP +Aside from the purposes noted above, +a process's user IDs are also employed in a number of other contexts: +.IP * 3 +when determining the permissions for sending signals (see +.BR kill (2)); +.IP * +when determining the permissions for setting +process-scheduling parameters (nice value, real time +scheduling policy and priority, CPU affinity, I/O priority) using +.BR setpriority (2), +.BR sched_setaffinity (2), +.BR sched_setscheduler (2), +.BR sched_setparam (2), +.BR sched_setattr (2), +and +.BR ioprio_set (2); +.IP * +when checking resource limits (see +.BR getrlimit (2)); +.IP * +when checking the limit on the number of inotify instances +that the process may create (see +.BR inotify (7)). +.SH CONFORMING TO +Process IDs, parent process IDs, process group IDs, and session IDs +are specified in POSIX.1. +The real, effective, and saved set user and groups IDs, +and the supplementary group IDs, are specified in POSIX.1. +The filesystem user and group IDs are a Linux extension. +.SH NOTES +The POSIX threads specification requires that +credentials are shared by all of the threads in a process. +However, at the kernel level, Linux maintains separate user and group +credentials for each thread. +The NPTL threading implementation does some work to ensure +that any change to user or group credentials +(e.g., calls to +.BR setuid (2), +.BR setresuid (2)) +is carried through to all of the POSIX threads in a process. +See +.BR nptl (7) +for further details. +.SH SEE ALSO +.BR bash (1), +.BR csh (1), +.BR groups (1), +.BR id (1), +.BR newgrp (1), +.BR ps (1), +.BR runuser (1), +.BR setpriv (1), +.BR sg (1), +.BR su (1), +.BR access (2), +.BR execve (2), +.BR faccessat (2), +.BR fork (2), +.BR getgroups (2), +.BR getpgrp (2), +.BR getpid (2), +.BR getppid (2), +.BR getsid (2), +.BR kill (2), +.BR setegid (2), +.BR seteuid (2), +.BR setfsgid (2), +.BR setfsuid (2), +.BR setgid (2), +.BR setgroups (2), +.BR setpgid (2), +.BR setresgid (2), +.BR setresuid (2), +.BR setsid (2), +.BR setuid (2), +.BR waitpid (2), +.BR euidaccess (3), +.BR initgroups (3), +.BR killpg (3), +.BR tcgetpgrp (3), +.BR tcsetpgrp (3), +.BR group (5), +.BR passwd (5), +.BR shadow (5), +.BR capabilities (7), +.BR namespaces (7), +.BR path_resolution (7), +.BR pid_namespaces (7), +.BR pthreads (7), +.BR signal (7), +.BR unix (7), +.BR user_namespaces (7), +.BR sudo (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/ddp.7 b/man7/ddp.7 new file mode 100644 index 0000000..8f83a70 --- /dev/null +++ b/man7/ddp.7 @@ -0,0 +1,259 @@ +.\" This man page is Copyright (C) 1998 Alan Cox. +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ +.\" +.TH DDP 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ddp \- Linux AppleTalk protocol implementation +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.IB ddp_socket " = socket(AF_APPLETALK, SOCK_DGRAM, 0);" +.br +.IB raw_socket " = socket(AF_APPLETALK, SOCK_RAW, " protocol ");" +.SH DESCRIPTION +Linux implements the AppleTalk protocols described in +.IR "Inside AppleTalk" . +Only the DDP layer and AARP are present in +the kernel. +They are designed to be used via the +.B netatalk +protocol +libraries. +This page documents the interface for those who wish or need to +use the DDP layer directly. +.PP +The communication between AppleTalk and the user program works using a +BSD-compatible socket interface. +For more information on sockets, see +.BR socket (7). +.PP +An AppleTalk socket is created by calling the +.BR socket (2) +function with a +.B AF_APPLETALK +socket family argument. +Valid socket types are +.B SOCK_DGRAM +to open a +.B ddp +socket or +.B SOCK_RAW +to open a +.B raw +socket. +.I protocol +is the AppleTalk protocol to be received or sent. +For +.B SOCK_RAW +you must specify +.BR ATPROTO_DDP . +.PP +Raw sockets may be opened only by a process with effective user ID 0 +or when the process has the +.B CAP_NET_RAW +capability. +.SS Address format +An AppleTalk socket address is defined as a combination of a network number, +a node number, and a port number. +.PP +.in +4n +.EX +struct at_addr { + unsigned short s_net; + unsigned char s_node; +}; + +struct sockaddr_atalk { + sa_family_t sat_family; /* address family */ + unsigned char sat_port; /* port */ + struct at_addr sat_addr; /* net/node */ +}; +.EE +.in +.PP +.I sat_family +is always set to +.BR AF_APPLETALK . +.I sat_port +contains the port. +The port numbers below 129 are known as +.IR "reserved ports" . +Only processes with the effective user ID 0 or the +.B CAP_NET_BIND_SERVICE +capability may +.BR bind (2) +to these sockets. +.I sat_addr +is the host address. +The +.I net +member of +.I struct at_addr +contains the host network in network byte order. +The value of +.B AT_ANYNET +is a +wildcard and also implies \(lqthis network.\(rq +The +.I node +member of +.I struct at_addr +contains the host node number. +The value of +.B AT_ANYNODE +is a +wildcard and also implies \(lqthis node.\(rq The value of +.B ATADDR_BCAST +is a link +local broadcast address. +.\" FIXME . this doesn't make sense [johnl] +.SS Socket options +No protocol-specific socket options are supported. +.SS /proc interfaces +IP supports a set of +.I /proc +interfaces to configure some global AppleTalk parameters. +The parameters can be accessed by reading or writing files in the directory +.IR /proc/sys/net/atalk/ . +.TP +.I aarp-expiry-time +The time interval (in seconds) before an AARP cache entry expires. +.TP +.I aarp-resolve-time +The time interval (in seconds) before an AARP cache entry is resolved. +.TP +.I aarp-retransmit-limit +The number of retransmissions of an AARP query before the node is declared +dead. +.TP +.I aarp-tick-time +The timer rate (in seconds) for the timer driving AARP. +.PP +The default values match the specification and should never need to be +changed. +.SS Ioctls +All ioctls described in +.BR socket (7) +apply to DDP. +.\" FIXME . Add a section about multicasting +.SH ERRORS +.TP +.B EACCES +The user tried to execute an operation without the necessary permissions. +These include sending to a broadcast address without +having the broadcast flag set, +and trying to bind to a reserved port without effective user ID 0 or +.BR CAP_NET_BIND_SERVICE . +.TP +.B EADDRINUSE +Tried to bind to an address already in use. +.TP +.B EADDRNOTAVAIL +A nonexistent interface was requested or the requested source address was +not local. +.TP +.B EAGAIN +Operation on a nonblocking socket would block. +.TP +.B EALREADY +A connection operation on a nonblocking socket is already in progress. +.TP +.B ECONNABORTED +A connection was closed during an +.BR accept (2). +.TP +.B EHOSTUNREACH +No routing table entry matches the destination address. +.TP +.B EINVAL +Invalid argument passed. +.TP +.B EISCONN +.BR connect (2) +was called on an already connected socket. +.TP +.B EMSGSIZE +Datagram is bigger than the DDP MTU. +.TP +.B ENODEV +Network device not available or not capable of sending IP. +.TP +.B ENOENT +.B SIOCGSTAMP +was called on a socket where no packet arrived. +.TP +.BR ENOMEM " and " ENOBUFS +Not enough memory available. +.TP +.B ENOPKG +A kernel subsystem was not configured. +.TP +.BR ENOPROTOOPT " and " EOPNOTSUPP +Invalid socket option passed. +.TP +.B ENOTCONN +The operation is defined only on a connected socket, but the socket wasn't +connected. +.TP +.B EPERM +User doesn't have permission to set high priority, +make a configuration change, +or send signals to the requested process or group. +.TP +.B EPIPE +The connection was unexpectedly closed or shut down by the other end. +.TP +.B ESOCKTNOSUPPORT +The socket was unconfigured, or an unknown socket type was requested. +.SH VERSIONS +AppleTalk is supported by Linux 2.0 or higher. +The +.I /proc +interfaces exist since Linux 2.2. +.SH NOTES +Be very careful with the +.B SO_BROADCAST +option; it is not privileged in Linux. +It is easy to overload the network +with careless sending to broadcast addresses. +.SS Compatibility +The basic AppleTalk socket interface is compatible with +.B netatalk +on BSD-derived systems. +Many BSD systems fail to check +.B SO_BROADCAST +when sending broadcast frames; this can lead to compatibility problems. +.PP +The +raw +socket mode is unique to Linux and exists to support the alternative CAP +package and AppleTalk monitoring tools more easily. +.SH BUGS +There are too many inconsistent error values. +.PP +The ioctls used to configure routing tables, devices, +AARP tables, and other devices are not yet described. +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR capabilities (7), +.BR socket (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/environ.7 b/man7/environ.7 new file mode 100644 index 0000000..54643c2 --- /dev/null +++ b/man7/environ.7 @@ -0,0 +1,307 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" and Andries Brouwer (aeb@cwi.nl), Fri Feb 14 21:47:50 1997. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sun Jul 25 10:45:30 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Oct 21 17:47:19 1996 by Eric S. Raymond (esr@thyrsus.com) +.\" Modified Wed Aug 27 20:28:58 1997 by Nicolás Lichtmaier (nick@debian.org) +.\" Modified Mon Sep 21 00:00:26 1998 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Jan 24 06:37:24 2001 by Eric S. Raymond (esr@thyrsus.com) +.\" Modified Thu Dec 13 23:53:27 2001 by Martin Schulze +.\" +.TH ENVIRON 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +environ \- user environment +.SH SYNOPSIS +.nf +.BI "extern char **" environ ; +.fi +.SH DESCRIPTION +The variable +.I environ +points to an array of pointers to strings called the "environment". +The last pointer in this array has the value NULL. +(This variable must be declared in the user program, +but is declared in the header file +.I +if the +.B _GNU_SOURCE +feature test macro is defined.) +This array of strings is made available to the process by the +.BR exec (3) +call that started the process. +When a child process is created via +.BR fork (2), +it inherits a +.I copy +of its parent's environment. +.PP +By convention the strings in +.I environ +have the form "\fIname\fP\fB=\fP\fIvalue\fP". +Common examples are: +.TP +.B USER +The name of the logged-in user (used by some BSD-derived programs). +.TP +.B LOGNAME +The name of the logged-in user (used by some System-V derived programs). +.TP +.B HOME +A user's login directory, set by +.BR login (1) +from the password file +.BR passwd (5). +.TP +.B LANG +The name of a locale to use for locale categories when not overridden +by +.B LC_ALL +or more specific environment variables such as +.BR LC_COLLATE , +.BR LC_CTYPE , +.BR LC_MESSAGES , +.BR LC_MONETARY , +.BR LC_NUMERIC , +and +.BR LC_TIME +(see +.BR locale (7) +for further details of the +.BR LC_* +environment variables). +.TP +.B PATH +The sequence of directory prefixes that +.BR sh (1) +and many other +programs apply in searching for a file known by an incomplete pathname. +The prefixes are separated by \(aq\fB:\fP\(aq. +(Similarly one has +.B CDPATH +used by some shells to find the target +of a change directory command, +.B MANPATH +used by +.BR man (1) +to find manual pages, and so on) +.TP +.B PWD +The current working directory. +Set by some shells. +.TP +.B SHELL +The pathname of the user's login shell. +.TP +.B TERM +The terminal type for which output is to be prepared. +.TP +.B PAGER +The user's preferred utility to display text files. +.TP +.BR EDITOR / VISUAL +The user's preferred utility to edit text files. +.\" .TP +.\" .B BROWSER +.\" The user's preferred utility to browse URLs. Sequence of colon-separated +.\" browser commands. See http://www.catb.org/~esr/BROWSER/ . +.PP +Names may be placed in the shell's environment by the +.I export +command in +.BR sh (1), +or by the +.I setenv +command if you use +.BR csh (1). +.PP +The initial environment of the shell is populated in various ways, +such as definitions from +.IR /etc/environment +that are processed by +.BR pam_env (8) +for all users at login time (on systems that employ +.BR pam (8)). +In addition, various shell initialization scripts, such as the system-wide +.IR /etc/profile +script and per-user initializations script may include commands +that add variables to the shell's environment; +see the manual page of your preferred shell for details. +.PP +Bourne-style shells support the syntax +.PP + NAME=value command +.PP +to create an environment variable definition only in the scope +of the process that executes +.IR command . +Multiple variable definitions, separated by white space, may precede +.IR command . +.PP +Arguments may also be placed in the +environment at the point of an +.BR exec (3). +A C program can manipulate its environment using the functions +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +and +.BR unsetenv (3). +.PP +Note that the behavior of many programs and library routines is +influenced by the presence or value of certain environment variables. +Examples include the following: +.IP * 3 +The variables +.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH ", " +.BR LC_ALL ", " LC_MESSAGES ", " +and so on influence locale handling; see +.BR catopen (3), +.BR gettext (3), +and +.BR locale (7). +.IP * +.B TMPDIR +influences the path prefix of names created by +.BR tempnam (3) +and other routines, and the temporary directory used by +.BR sort (1) +and other programs. +.IP * +.BR LD_LIBRARY_PATH ", " LD_PRELOAD , +and other +.BR LD_* +variables influence the behavior of the dynamic loader/linker. +.IP * +.B POSIXLY_CORRECT +makes certain programs and library routines follow +the prescriptions of POSIX. +.IP * +The behavior of +.BR malloc (3) +is influenced by +.B MALLOC_* +variables. +.IP * +The variable +.B HOSTALIASES +gives the name of a file containing aliases +to be used with +.BR gethostbyname (3). +.IP * +.BR TZ " and " TZDIR +give timezone information used by +.BR tzset (3) +and through that by functions like +.BR ctime (3), +.BR localtime (3), +.BR mktime (3), +.BR strftime (3). +See also +.BR tzselect (8). +.IP * +.B TERMCAP +gives information on how to address a given terminal +(or gives the name of a file containing such information). +.IP * +.BR COLUMNS " and " LINES +tell applications about the window size, possibly overriding the actual size. +.IP * +.BR PRINTER " or " LPDEST +may specify the desired printer to use. +See +.BR lpr (1). +.SH NOTES +The +.BR prctl (2) +.B PR_SET_MM_ENV_START +and +.B PR_SET_MM_ENV_END +operations can be used to control the location of the process's environment. +.SH BUGS +Clearly there is a security risk here. +Many a system command has been +tricked into mischief by a user who specified unusual values for +.BR IFS " or " LD_LIBRARY_PATH . +.PP +There is also the risk of name space pollution. +Programs like +.I make +and +.I autoconf +allow overriding of default utility names from the +environment with similarly named variables in all caps. +Thus one uses +.B CC +to select the desired C compiler (and similarly +.BR MAKE , +.BR AR , +.BR AS , +.BR FC , +.BR LD , +.BR LEX , +.BR RM , +.BR YACC , +etc.). +However, in some traditional uses such an environment variable +gives options for the program instead of a pathname. +Thus, one has +.BR MORE , +.BR LESS , +and +.BR GZIP . +Such usage is considered mistaken, and to be avoided in new +programs. +The authors of +.I gzip +should consider renaming their option to +.BR GZIP_OPT . +.SH SEE ALSO +.BR bash (1), +.BR csh (1), +.BR env (1), +.BR login (1), +.BR printenv (1), +.BR sh (1), +.BR tcsh (1), +.BR execve (2), +.BR clearenv (3), +.BR exec (3), +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR locale (7), +.BR ld.so (8), +.BR pam_env (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/epoll.7 b/man7/epoll.7 new file mode 100644 index 0000000..d286f15 --- /dev/null +++ b/man7/epoll.7 @@ -0,0 +1,607 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Davide Libenzi +.\" +.TH EPOLL 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +epoll \- I/O event notification facility +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +The +.B epoll +API performs a similar task to +.BR poll (2): +monitoring multiple file descriptors to see if I/O is possible on any of them. +The +.B epoll +API can be used either as an edge-triggered or a level-triggered +interface and scales well to large numbers of watched file descriptors. +The following system calls are provided to +create and manage an +.B epoll +instance: +.IP * 3 +.BR epoll_create (2) +creates a new +.B epoll +instance and returns a file descriptor referring to that instance. +(The more recent +.BR epoll_create1 (2) +extends the functionality of +.BR epoll_create (2).) +.IP * +Interest in particular file descriptors is then registered via +.BR epoll_ctl (2). +The set of file descriptors currently registered on an +.B epoll +instance is sometimes called an +.I epoll +set. +.IP * +.BR epoll_wait (2) +waits for I/O events, +blocking the calling thread if no events are currently available. +.SS Level-triggered and edge-triggered +The +.B epoll +event distribution interface is able to behave both as edge-triggered +(ET) and as level-triggered (LT). +The difference between the two mechanisms +can be described as follows. +Suppose that +this scenario happens: +.IP 1. 3 +The file descriptor that represents the read side of a pipe +.RI ( rfd ) +is registered on the +.B epoll +instance. +.IP 2. +A pipe writer writes 2\ kB of data on the write side of the pipe. +.IP 3. +A call to +.BR epoll_wait (2) +is done that will return +.I rfd +as a ready file descriptor. +.IP 4. +The pipe reader reads 1\ kB of data from +.IR rfd . +.IP 5. +A call to +.BR epoll_wait (2) +is done. +.PP +If the +.I rfd +file descriptor has been added to the +.B epoll +interface using the +.B EPOLLET +(edge-triggered) +flag, the call to +.BR epoll_wait (2) +done in step +.B 5 +will probably hang despite the available data still present in the file +input buffer; +meanwhile the remote peer might be expecting a response based on the +data it already sent. +The reason for this is that edge-triggered mode +delivers events only when changes occur on the monitored file descriptor. +So, in step +.B 5 +the caller might end up waiting for some data that is already present inside +the input buffer. +In the above example, an event on +.I rfd +will be generated because of the write done in +.B 2 +and the event is consumed in +.BR 3 . +Since the read operation done in +.B 4 +does not consume the whole buffer data, the call to +.BR epoll_wait (2) +done in step +.B 5 +might block indefinitely. +.PP +An application that employs the +.B EPOLLET +flag should use nonblocking file descriptors to avoid having a blocking +read or write starve a task that is handling multiple file descriptors. +The suggested way to use +.B epoll +as an edge-triggered +.RB ( EPOLLET ) +interface is as follows: +.RS +.TP 4 +.B i +with nonblocking file descriptors; and +.TP +.B ii +by waiting for an event only after +.BR read (2) +or +.BR write (2) +return +.BR EAGAIN . +.RE +.PP +By contrast, when used as a level-triggered interface +(the default, when +.B EPOLLET +is not specified), +.B epoll +is simply a faster +.BR poll (2), +and can be used wherever the latter is used since it shares the +same semantics. +.PP +Since even with edge-triggered +.BR epoll , +multiple events can be generated upon receipt of multiple chunks of data, +the caller has the option to specify the +.B EPOLLONESHOT +flag, to tell +.B epoll +to disable the associated file descriptor after the receipt of an event with +.BR epoll_wait (2). +When the +.B EPOLLONESHOT +flag is specified, +it is the caller's responsibility to rearm the file descriptor using +.BR epoll_ctl (2) +with +.BR EPOLL_CTL_MOD . +.SS Interaction with autosleep +If the system is in +.B autosleep +mode via +.I /sys/power/autosleep +and an event happens which wakes the device from sleep, the device +driver will keep the device awake only until that event is queued. +To keep the device awake until the event has been processed, +it is necessary to use the +.BR epoll_ctl (2) +.B EPOLLWAKEUP +flag. +.PP +When the +.B EPOLLWAKEUP +flag is set in the +.B events +field for a +.IR "struct epoll_event" , +the system will be kept awake from the moment the event is queued, +through the +.BR epoll_wait (2) +call which returns the event until the subsequent +.BR epoll_wait (2) +call. +If the event should keep the system awake beyond that time, +then a separate +.I wake_lock +should be taken before the second +.BR epoll_wait (2) +call. +.SS /proc interfaces +The following interfaces can be used to limit the amount of +kernel memory consumed by epoll: +.\" Following was added in 2.6.28, but them removed in 2.6.29 +.\" .TP +.\" .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)" +.\" This specifies an upper limit on the number of epoll instances +.\" that can be created per real user ID. +.TP +.IR /proc/sys/fs/epoll/max_user_watches " (since Linux 2.6.28)" +This specifies a limit on the total number of +file descriptors that a user can register across +all epoll instances on the system. +The limit is per real user ID. +Each registered file descriptor costs roughly 90 bytes on a 32-bit kernel, +and roughly 160 bytes on a 64-bit kernel. +Currently, +.\" 2.6.29 (in 2.6.28, the default was 1/32 of lowmem) +the default value for +.I max_user_watches +is 1/25 (4%) of the available low memory, +divided by the registration cost in bytes. +.SS Example for suggested usage +While the usage of +.B epoll +when employed as a level-triggered interface does have the same +semantics as +.BR poll (2), +the edge-triggered usage requires more clarification to avoid stalls +in the application event loop. +In this example, listener is a +nonblocking socket on which +.BR listen (2) +has been called. +The function +.I do_use_fd() +uses the new ready file descriptor until +.B EAGAIN +is returned by either +.BR read (2) +or +.BR write (2). +An event-driven state machine application should, after having received +.BR EAGAIN , +record its current state so that at the next call to +.I do_use_fd() +it will continue to +.BR read (2) +or +.BR write (2) +from where it stopped before. +.PP +.in +4n +.EX +#define MAX_EVENTS 10 +struct epoll_event ev, events[MAX_EVENTS]; +int listen_sock, conn_sock, nfds, epollfd; + +/* Code to set up listening socket, \(aqlisten_sock\(aq, + (socket(), bind(), listen()) omitted */ + +epollfd = epoll_create1(0); +if (epollfd == \-1) { + perror("epoll_create1"); + exit(EXIT_FAILURE); +} + +ev.events = EPOLLIN; +ev.data.fd = listen_sock; +if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == \-1) { + perror("epoll_ctl: listen_sock"); + exit(EXIT_FAILURE); +} + +for (;;) { + nfds = epoll_wait(epollfd, events, MAX_EVENTS, \-1); + if (nfds == \-1) { + perror("epoll_wait"); + exit(EXIT_FAILURE); + } + + for (n = 0; n < nfds; ++n) { + if (events[n].data.fd == listen_sock) { + conn_sock = accept(listen_sock, + (struct sockaddr *) &addr, &addrlen); + if (conn_sock == \-1) { + perror("accept"); + exit(EXIT_FAILURE); + } + setnonblocking(conn_sock); + ev.events = EPOLLIN | EPOLLET; + ev.data.fd = conn_sock; + if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock, + &ev) == \-1) { + perror("epoll_ctl: conn_sock"); + exit(EXIT_FAILURE); + } + } else { + do_use_fd(events[n].data.fd); + } + } +} +.EE +.in +.PP +When used as an edge-triggered interface, for performance reasons, it is +possible to add the file descriptor inside the +.B epoll +interface +.RB ( EPOLL_CTL_ADD ) +once by specifying +.RB ( EPOLLIN | EPOLLOUT ). +This allows you to avoid +continuously switching between +.B EPOLLIN +and +.B EPOLLOUT +calling +.BR epoll_ctl (2) +with +.BR EPOLL_CTL_MOD . +.SS Questions and answers +.TP 4 +.B Q0 +What is the key used to distinguish the file descriptors registered in an +.B epoll +set? +.TP +.B A0 +The key is the combination of the file descriptor number and +the open file description +(also known as an "open file handle", +the kernel's internal representation of an open file). +.TP +.B Q1 +What happens if you register the same file descriptor on an +.B epoll +instance twice? +.TP +.B A1 +You will probably get +.BR EEXIST . +However, it is possible to add a duplicate +.RB ( dup (2), +.BR dup2 (2), +.BR fcntl (2) +.BR F_DUPFD ) +file descriptor to the same +.B epoll +instance. +.\" But a file descriptor duplicated by fork(2) can't be added to the +.\" set, because the [file *, fd] pair is already in the epoll set. +.\" That is a somewhat ugly inconsistency. On the one hand, a child process +.\" cannot add the duplicate file descriptor to the epoll set. (In every +.\" other case that I can think of, file descriptors duplicated by fork have +.\" similar semantics to file descriptors duplicated by dup() and friends.) On +.\" the other hand, the very fact that the child has a duplicate of the +.\" file descriptor means that even if the parent closes its file descriptor, +.\" then epoll_wait() in the parent will continue to receive notifications for +.\" that file descriptor because of the duplicated file descriptor in the child. +.\" +.\" See http://thread.gmane.org/gmane.linux.kernel/596462/ +.\" "epoll design problems with common fork/exec patterns" +.\" +.\" mtk, Feb 2008 +This can be a useful technique for filtering events, +if the duplicate file descriptors are registered with different +.I events +masks. +.TP +.B Q2 +Can two +.B epoll +instances wait for the same file descriptor? +If so, are events reported to both +.B epoll +file descriptors? +.TP +.B A2 +Yes, and events would be reported to both. +However, careful programming may be needed to do this correctly. +.TP +.B Q3 +Is the +.B epoll +file descriptor itself poll/epoll/selectable? +.TP +.B A3 +Yes. +If an +.B epoll +file descriptor has events waiting, then it will +indicate as being readable. +.TP +.B Q4 +What happens if one attempts to put an +.B epoll +file descriptor into its own file descriptor set? +.TP +.B A4 +The +.BR epoll_ctl (2) +call fails +.RB ( EINVAL ). +However, you can add an +.B epoll +file descriptor inside another +.B epoll +file descriptor set. +.TP +.B Q5 +Can I send an +.B epoll +file descriptor over a UNIX domain socket to another process? +.TP +.B A5 +Yes, but it does not make sense to do this, since the receiving process +would not have copies of the file descriptors in the +.B epoll +set. +.TP +.B Q6 +Will closing a file descriptor cause it to be removed from all +.B epoll +sets automatically? +.TP +.B A6 +Yes, but be aware of the following point. +A file descriptor is a reference to an open file description (see +.BR open (2)). +Whenever a file descriptor is duplicated via +.BR dup (2), +.BR dup2 (2), +.BR fcntl (2) +.BR F_DUPFD , +or +.BR fork (2), +a new file descriptor referring to the same open file description is +created. +An open file description continues to exist until all +file descriptors referring to it have been closed. +A file descriptor is removed from an +.B epoll +set only after all the file descriptors referring to the underlying +open file description have been closed +(or before if the file descriptor is explicitly removed using +.BR epoll_ctl (2) +.BR EPOLL_CTL_DEL ). +This means that even after a file descriptor that is part of an +.B epoll +set has been closed, +events may be reported for that file descriptor if other file +descriptors referring to the same underlying file description remain open. +.TP +.B Q7 +If more than one event occurs between +.BR epoll_wait (2) +calls, are they combined or reported separately? +.TP +.B A7 +They will be combined. +.TP +.B Q8 +Does an operation on a file descriptor affect the +already collected but not yet reported events? +.TP +.B A8 +You can do two operations on an existing file descriptor. +Remove would be meaningless for +this case. +Modify will reread available I/O. +.TP +.B Q9 +Do I need to continuously read/write a file descriptor +until +.B EAGAIN +when using the +.B EPOLLET +flag (edge-triggered behavior) ? +.TP +.B A9 +Receiving an event from +.BR epoll_wait (2) +should suggest to you that such +file descriptor is ready for the requested I/O operation. +You must consider it ready until the next (nonblocking) +read/write yields +.BR EAGAIN . +When and how you will use the file descriptor is entirely up to you. +.IP +For packet/token-oriented files (e.g., datagram socket, +terminal in canonical mode), +the only way to detect the end of the read/write I/O space +is to continue to read/write until +.BR EAGAIN . +.IP +For stream-oriented files (e.g., pipe, FIFO, stream socket), the +condition that the read/write I/O space is exhausted can also be detected by +checking the amount of data read from / written to the target file +descriptor. +For example, if you call +.BR read (2) +by asking to read a certain amount of data and +.BR read (2) +returns a lower number of bytes, you +can be sure of having exhausted the read I/O space for the file +descriptor. +The same is true when writing using +.BR write (2). +(Avoid this latter technique if you cannot guarantee that +the monitored file descriptor always refers to a stream-oriented file.) +.SS Possible pitfalls and ways to avoid them +.TP +.B o Starvation (edge-triggered) +.PP +If there is a large amount of I/O space, +it is possible that by trying to drain +it the other files will not get processed causing starvation. +(This problem is not specific to +.BR epoll .) +.PP +The solution is to maintain a ready list +and mark the file descriptor as ready +in its associated data structure, thereby allowing the application to +remember which files need to be processed but still round robin amongst +all the ready files. +This also supports ignoring subsequent events you +receive for file descriptors that are already ready. +.TP +.B o If using an event cache... +.PP +If you use an event cache or store all the file descriptors returned from +.BR epoll_wait (2), +then make sure to provide a way to mark +its closure dynamically (i.e., caused by +a previous event's processing). +Suppose you receive 100 events from +.BR epoll_wait (2), +and in event #47 a condition causes event #13 to be closed. +If you remove the structure and +.BR close (2) +the file descriptor for event #13, then your +event cache might still say there are events waiting for that +file descriptor causing confusion. +.PP +One solution for this is to call, during the processing of event 47, +.BR epoll_ctl ( EPOLL_CTL_DEL ) +to delete file descriptor 13 and +.BR close (2), +then mark its associated +data structure as removed and link it to a cleanup list. +If you find another +event for file descriptor 13 in your batch processing, +you will discover the file descriptor had been +previously removed and there will be no confusion. +.SH VERSIONS +The +.B epoll +API was introduced in Linux kernel 2.5.44. +.\" Its interface should be finalized in Linux kernel 2.5.66. +Support was added to glibc in version 2.3.2. +.SH CONFORMING TO +The +.B epoll +API is Linux-specific. +Some other systems provide similar +mechanisms, for example, FreeBSD has +.IR kqueue , +and Solaris has +.IR /dev/poll . +.SH NOTES +The set of file descriptors that is being monitored via +an epoll file descriptor can be viewed via the entry for +the epoll file descriptor in the process's +.IR /proc/[pid]/fdinfo +directory. +See +.BR proc (5) +for further details. +.PP +The +.BR kcmp (2) +.B KCMP_EPOLL_TFD +operation can be used to test whether a file descriptor +is present in an epoll instance. +.SH SEE ALSO +.BR epoll_create (2), +.BR epoll_create1 (2), +.BR epoll_ctl (2), +.BR epoll_wait (2), +.BR poll (2), +.BR select (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/fanotify.7 b/man7/fanotify.7 new file mode 100644 index 0000000..d7a6bcb --- /dev/null +++ b/man7/fanotify.7 @@ -0,0 +1,772 @@ +.\" Copyright (C) 2013, Heinrich Schuchardt +.\" and Copyright (C) 2014, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.TH FANOTIFY 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +fanotify \- monitoring filesystem events +.SH DESCRIPTION +The fanotify API provides notification and interception of +filesystem events. +Use cases include virus scanning and hierarchical storage management. +Currently, only a limited set of events is supported. +In particular, there is no support for create, delete, and move events. +(See +.BR inotify (7) +for details of an API that does notify those events.) +.PP +Additional capabilities compared to the +.BR inotify (7) +API include the ability to monitor all of the objects +in a mounted filesystem, +the ability to make access permission decisions, and the +possibility to read or modify files before access by other applications. +.PP +The following system calls are used with this API: +.BR fanotify_init (2), +.BR fanotify_mark (2), +.BR read (2), +.BR write (2), +and +.BR close (2). +.SS fanotify_init(), fanotify_mark(), and notification groups +The +.BR fanotify_init (2) +system call creates and initializes an fanotify notification group +and returns a file descriptor referring to it. +.PP +An fanotify notification group is a kernel-internal object that holds +a list of files, directories, and mount points for which events shall be +created. +.PP +For each entry in an fanotify notification group, two bit masks exist: the +.I mark +mask and the +.I ignore +mask. +The mark mask defines file activities for which an event shall be created. +The ignore mask defines activities for which no event shall be generated. +Having these two types of masks permits a mount point or directory to be +marked for receiving events, while at the same time ignoring events for +specific objects under that mount point or directory. +.PP +The +.BR fanotify_mark (2) +system call adds a file, directory, or mount to a notification group +and specifies which events +shall be reported (or ignored), or removes or modifies such an entry. +.PP +A possible usage of the ignore mask is for a file cache. +Events of interest for a file cache are modification of a file and closing +of the same. +Hence, the cached directory or mount point is to be marked to receive these +events. +After receiving the first event informing that a file has been modified, +the corresponding cache entry will be invalidated. +No further modification events for this file are of interest until the file +is closed. +Hence, the modify event can be added to the ignore mask. +Upon receiving the close event, the modify event can be removed from the +ignore mask and the file cache entry can be updated. +.PP +The entries in the fanotify notification groups refer to files and +directories via their inode number and to mounts via their mount ID. +If files or directories are renamed or moved within the same mount, +the respective entries survive. +If files or directories are deleted or moved to another mount or if mounts are +unmounted, the corresponding entries are deleted. +.SS The event queue +As events occur on the filesystem objects monitored by a notification group, +the fanotify system generates events that are collected in a queue. +These events can then be read (using +.BR read (2) +or similar) +from the fanotify file descriptor +returned by +.BR fanotify_init (2). +.PP +Two types of events are generated: +.I notification +events and +.I permission +events. +Notification events are merely informative +and require no action to be taken by +the receiving application except for closing the file descriptor passed +in the event (see below). +Permission events are requests to the receiving application to decide +whether permission for a file access shall be granted. +For these events, the recipient must write a response which decides whether +access is granted or not. +.PP +An event is removed from the event queue of the fanotify group +when it has been read. +Permission events that have been read are kept in an internal list of the +fanotify group until either a permission decision has been taken by +writing to the fanotify file descriptor or the fanotify file descriptor +is closed. +.SS Reading fanotify events +Calling +.BR read (2) +for the file descriptor returned by +.BR fanotify_init (2) +blocks (if the flag +.B FAN_NONBLOCK +is not specified in the call to +.BR fanotify_init (2)) +until either a file event occurs or the call is interrupted by a signal +(see +.BR signal (7)). +.PP +After a successful +.BR read (2), +the read buffer contains one or more of the following structures: +.PP +.in +4n +.EX +struct fanotify_event_metadata { + __u32 event_len; + __u8 vers; + __u8 reserved; + __u16 metadata_len; + __aligned_u64 mask; + __s32 fd; + __s32 pid; +}; +.EE +.in +.PP +For performance reasons, it is recommended to use a large +buffer size (for example, 4096 bytes), +so that multiple events can be retrieved by a single +.BR read (2). +.PP +The return value of +.BR read (2) +is the number of bytes placed in the buffer, +or \-1 in case of an error (but see BUGS). +.PP +The fields of the +.I fanotify_event_metadata +structure are as follows: +.TP +.I event_len +This is the length of the data for the current event and the offset +to the next event in the buffer. +In the current implementation, the value of +.I event_len +is always +.BR FAN_EVENT_METADATA_LEN . +However, the API is designed to allow +variable-length structures to be returned in the future. +.TP +.I vers +This field holds a version number for the structure. +It must be compared to +.B FANOTIFY_METADATA_VERSION +to verify that the structures returned at runtime match +the structures defined at compile time. +In case of a mismatch, the application should abandon trying to use the +fanotify file descriptor. +.TP +.I reserved +This field is not used. +.TP +.I metadata_len +This is the length of the structure. +The field was introduced to facilitate the implementation of +optional headers per event type. +No such optional headers exist in the current implementation. +.TP +.I mask +This is a bit mask describing the event (see below). +.TP +.I fd +This is an open file descriptor for the object being accessed, or +.B FAN_NOFD +if a queue overflow occurred. +The file descriptor can be used to access the contents +of the monitored file or directory. +The reading application is responsible for closing this file descriptor. +.IP +When calling +.BR fanotify_init (2), +the caller may specify (via the +.I event_f_flags +argument) various file status flags that are to be set +on the open file description that corresponds to this file descriptor. +In addition, the (kernel-internal) +.B FMODE_NONOTIFY +file status flag is set on the open file description. +This flag suppresses fanotify event generation. +Hence, when the receiver of the fanotify event accesses the notified file or +directory using this file descriptor, no additional events will be created. +.TP +.I pid +This is the ID of the process that caused the event. +A program listening to fanotify events can compare this PID +to the PID returned by +.BR getpid (2), +to determine whether the event is caused by the listener itself, +or is due to a file access by another process. +.PP +The bit mask in +.I mask +indicates which events have occurred for a single filesystem object. +Multiple bits may be set in this mask, +if more than one event occurred for the monitored filesystem object. +In particular, +consecutive events for the same filesystem object and originating from the +same process may be merged into a single event, with the exception that two +permission events are never merged into one queue entry. +.PP +The bits that may appear in +.I mask +are as follows: +.TP +.B FAN_ACCESS +A file or a directory (but see BUGS) was accessed (read). +.TP +.B FAN_OPEN +A file or a directory was opened. +.TP +.B FAN_MODIFY +A file was modified. +.TP +.B FAN_CLOSE_WRITE +A file that was opened for writing +.RB ( O_WRONLY +or +.BR O_RDWR ) +was closed. +.TP +.B FAN_CLOSE_NOWRITE +A file or directory that was opened read-only +.RB ( O_RDONLY ) +was closed. +.TP +.B FAN_Q_OVERFLOW +The event queue exceeded the limit of 16384 entries. +This limit can be overridden by specifying the +.BR FAN_UNLIMITED_QUEUE +flag when calling +.BR fanotify_init (2). +.TP +.B FAN_ACCESS_PERM +An application wants to read a file or directory, for example using +.BR read (2) +or +.BR readdir (2). +The reader must write a response (as described below) +that determines whether the permission to +access the filesystem object shall be granted. +.TP +.B FAN_OPEN_PERM +An application wants to open a file or directory. +The reader must write a response that determines whether the permission to +open the filesystem object shall be granted. +.PP +To check for any close event, the following bit mask may be used: +.TP +.B FAN_CLOSE +A file was closed. +This is a synonym for: +.IP + FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE +.PP +The following macros are provided to iterate over a buffer containing +fanotify event metadata returned by a +.BR read (2) +from an fanotify file descriptor: +.TP +.B FAN_EVENT_OK(meta, len) +This macro checks the remaining length +.I len +of the buffer +.I meta +against the length of the metadata structure and the +.I event_len +field of the first metadata structure in the buffer. +.TP +.B FAN_EVENT_NEXT(meta, len) +This macro uses the length indicated in the +.I event_len +field of the metadata structure pointed to by +.IR meta +to calculate the address of the next metadata structure that follows +.IR meta . +.I len +is the number of bytes of metadata that currently remain in the buffer. +The macro returns a pointer to the next metadata structure that follows +.IR meta , +and reduces +.I len +by the number of bytes in the metadata structure that +has been skipped over (i.e., it subtracts +.IR meta\->event_len +from +.IR len ). +.PP +In addition, there is: +.TP +.B FAN_EVENT_METADATA_LEN +This macro returns the size (in bytes) of the structure +.IR fanotify_event_metadata . +This is the minimum size (and currently the only size) of any event metadata. +.\" +.SS Monitoring an fanotify file descriptor for events +When an fanotify event occurs, the fanotify file descriptor indicates as +readable when passed to +.BR epoll (7), +.BR poll (2), +or +.BR select (2). +.SS Dealing with permission events +For permission events, the application must +.BR write (2) +a structure of the following form to the +fanotify file descriptor: +.PP +.in +4n +.EX +struct fanotify_response { + __s32 fd; + __u32 response; +}; +.EE +.in +.PP +The fields of this structure are as follows: +.TP +.I fd +This is the file descriptor from the structure +.IR fanotify_event_metadata . +.TP +.I response +This field indicates whether or not the permission is to be granted. +Its value must be either +.B FAN_ALLOW +to allow the file operation or +.B FAN_DENY +to deny the file operation. +.PP +If access is denied, the requesting application call will receive an +.BR EPERM +error. +.SS Closing the fanotify file descriptor +.PP +When all file descriptors referring to the fanotify notification group are +closed, the fanotify group is released and its resources +are freed for reuse by the kernel. +Upon +.BR close (2), +outstanding permission events will be set to allowed. +.SS /proc/[pid]/fdinfo +The file +.I /proc/[pid]/fdinfo/[fd] +contains information about fanotify marks for file descriptor +.I fd +of process +.IR pid . +See +.BR proc (5) +for details. +.SH ERRORS +In addition to the usual errors for +.BR read (2), +the following errors can occur when reading from the +fanotify file descriptor: +.TP +.B EINVAL +The buffer is too small to hold the event. +.TP +.B EMFILE +The per-process limit on the number of open files has been reached. +See the description of +.B RLIMIT_NOFILE +in +.BR getrlimit (2). +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +See +.I /proc/sys/fs/file-max +in +.BR proc (5). +.TP +.B ETXTBSY +This error is returned by +.BR read (2) +if +.B O_RDWR +or +.B O_WRONLY +was specified in the +.I event_f_flags +argument when calling +.BR fanotify_init (2) +and an event occurred for a monitored file that is currently being executed. +.PP +In addition to the usual errors for +.BR write (2), +the following errors can occur when writing to the fanotify file descriptor: +.TP +.B EINVAL +Fanotify access permissions are not enabled in the kernel configuration +or the value of +.I response +in the response structure is not valid. +.TP +.B ENOENT +The file descriptor +.I fd +in the response structure is not valid. +This may occur when a response for the permission event has already been +written. +.SH VERSIONS +The fanotify API was introduced in version 2.6.36 of the Linux kernel and +enabled in version 2.6.37. +Fdinfo support was added in version 3.8. +.SH CONFORMING TO +The fanotify API is Linux-specific. +.SH NOTES +The fanotify API is available only if the kernel was built with the +.B CONFIG_FANOTIFY +configuration option enabled. +In addition, fanotify permission handling is available only if the +.B CONFIG_FANOTIFY_ACCESS_PERMISSIONS +configuration option is enabled. +.SS Limitations and caveats +Fanotify reports only events that a user-space program triggers through the +filesystem API. +As a result, +it does not catch remote events that occur on network filesystems. +.PP +The fanotify API does not report file accesses and modifications that +may occur because of +.BR mmap (2), +.BR msync (2), +and +.BR munmap (2). +.PP +Events for directories are created only if the directory itself is opened, +read, and closed. +Adding, removing, or changing children of a marked directory does not create +events for the monitored directory itself. +.PP +Fanotify monitoring of directories is not recursive: +to monitor subdirectories under a directory, +additional marks must be created. +(But note that the fanotify API provides no way of detecting when a +subdirectory has been created under a marked directory, +which makes recursive monitoring difficult.) +Monitoring mounts offers the capability to monitor a whole directory tree. +.PP +The event queue can overflow. +In this case, events are lost. +.SH BUGS +Before Linux 3.19, +.BR fallocate (2) +did not generate fanotify events. +Since Linux 3.19, +.\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35 +calls to +.BR fallocate (2) +generate +.B FAN_MODIFY +events. +.PP +As of Linux 3.17, +the following bugs exist: +.IP * 3 +On Linux, a filesystem object may be accessible through multiple paths, +for example, a part of a filesystem may be remounted using the +.IR \-\-bind +option of +.BR mount (8). +A listener that marked a mount will be notified only of events that were +triggered for a filesystem object using the same mount. +Any other event will pass unnoticed. +.IP * +.\" FIXME . A patch was proposed. +When an event is generated, +no check is made to see whether the user ID of the +receiving process has authorization to read or write the file +before passing a file descriptor for that file. +This poses a security risk, when the +.B CAP_SYS_ADMIN +capability is set for programs executed by unprivileged users. +.IP * +If a call to +.BR read (2) +processes multiple events from the fanotify queue and an error occurs, +the return value will be the total length of the events successfully +copied to the user-space buffer before the error occurred. +The return value will not be \-1, and +.I errno +will not be set. +Thus, the reading application has no way to detect the error. +.SH EXAMPLE +The following program demonstrates the usage of the fanotify API. +It marks the mount point passed as a command-line argument +and waits for events of type +.B FAN_PERM_OPEN +and +.BR FAN_CLOSE_WRITE . +When a permission event occurs, a +.B FAN_ALLOW +response is given. +.PP +The following output was recorded while editing the file +.IR /home/user/temp/notes . +Before the file was opened, a +.B FAN_OPEN_PERM +event occurred. +After the file was closed, a +.B FAN_CLOSE_WRITE +event occurred. +Execution of the program ends when the user presses the ENTER key. +.SS Example output +.in +4n +.EX +# ./fanotify_example /home +Press enter key to terminate. +Listening for events. +FAN_OPEN_PERM: File /home/user/temp/notes +FAN_CLOSE_WRITE: File /home/user/temp/notes + +Listening for events stopped. +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE /* Needed to get O_LARGEFILE definition */ +#include +#include +#include +#include +#include +#include +#include +#include + +/* Read all available fanotify events from the file descriptor 'fd' */ + +static void +handle_events(int fd) +{ + const struct fanotify_event_metadata *metadata; + struct fanotify_event_metadata buf[200]; + ssize_t len; + char path[PATH_MAX]; + ssize_t path_len; + char procfd_path[PATH_MAX]; + struct fanotify_response response; + + /* Loop while events can be read from fanotify file descriptor */ + + for(;;) { + + /* Read some events */ + + len = read(fd, (void *) &buf, sizeof(buf)); + if (len == \-1 && errno != EAGAIN) { + perror("read"); + exit(EXIT_FAILURE); + } + + /* Check if end of available data reached */ + + if (len <= 0) + break; + + /* Point to the first event in the buffer */ + + metadata = buf; + + /* Loop over all events in the buffer */ + + while (FAN_EVENT_OK(metadata, len)) { + + /* Check that run\-time and compile\-time structures match */ + + if (metadata\->vers != FANOTIFY_METADATA_VERSION) { + fprintf(stderr, + "Mismatch of fanotify metadata version.\\n"); + exit(EXIT_FAILURE); + } + + /* metadata\->fd contains either FAN_NOFD, indicating a + queue overflow, or a file descriptor (a nonnegative + integer). Here, we simply ignore queue overflow. */ + + if (metadata\->fd >= 0) { + + /* Handle open permission event */ + + if (metadata\->mask & FAN_OPEN_PERM) { + printf("FAN_OPEN_PERM: "); + + /* Allow file to be opened */ + + response.fd = metadata\->fd; + response.response = FAN_ALLOW; + write(fd, &response, + sizeof(struct fanotify_response)); + } + + /* Handle closing of writable file event */ + + if (metadata\->mask & FAN_CLOSE_WRITE) + printf("FAN_CLOSE_WRITE: "); + + /* Retrieve and print pathname of the accessed file */ + + snprintf(procfd_path, sizeof(procfd_path), + "/proc/self/fd/%d", metadata\->fd); + path_len = readlink(procfd_path, path, + sizeof(path) \- 1); + if (path_len == \-1) { + perror("readlink"); + exit(EXIT_FAILURE); + } + + path[path_len] = '\\0'; + printf("File %s\\n", path); + + /* Close the file descriptor of the event */ + + close(metadata\->fd); + } + + /* Advance to next event */ + + metadata = FAN_EVENT_NEXT(metadata, len); + } + } +} + +int +main(int argc, char *argv[]) +{ + char buf; + int fd, poll_num; + nfds_t nfds; + struct pollfd fds[2]; + + /* Check mount point is supplied */ + + if (argc != 2) { + fprintf(stderr, "Usage: %s MOUNT\\n", argv[0]); + exit(EXIT_FAILURE); + } + + printf("Press enter key to terminate.\\n"); + + /* Create the file descriptor for accessing the fanotify API */ + + fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK, + O_RDONLY | O_LARGEFILE); + if (fd == \-1) { + perror("fanotify_init"); + exit(EXIT_FAILURE); + } + + /* Mark the mount for: + \- permission events before opening files + \- notification events after closing a write\-enabled + file descriptor */ + + if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT, + FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD, + argv[1]) == \-1) { + perror("fanotify_mark"); + exit(EXIT_FAILURE); + } + + /* Prepare for polling */ + + nfds = 2; + + /* Console input */ + + fds[0].fd = STDIN_FILENO; + fds[0].events = POLLIN; + + /* Fanotify input */ + + fds[1].fd = fd; + fds[1].events = POLLIN; + + /* This is the loop to wait for incoming events */ + + printf("Listening for events.\\n"); + + while (1) { + poll_num = poll(fds, nfds, \-1); + if (poll_num == \-1) { + if (errno == EINTR) /* Interrupted by a signal */ + continue; /* Restart poll() */ + + perror("poll"); /* Unexpected error */ + exit(EXIT_FAILURE); + } + + if (poll_num > 0) { + if (fds[0].revents & POLLIN) { + + /* Console input is available: empty stdin and quit */ + + while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\\n') + continue; + break; + } + + if (fds[1].revents & POLLIN) { + + /* Fanotify events are available */ + + handle_events(fd); + } + } + } + + printf("Listening for events stopped.\\n"); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.BR fanotify_init (2), +.BR fanotify_mark (2), +.BR inotify (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 new file mode 100644 index 0000000..8d7a39c --- /dev/null +++ b/man7/feature_test_macros.7 @@ -0,0 +1,904 @@ +.\" This manpage is Copyright (C) 2006, Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH FEATURE_TEST_MACROS 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +feature_test_macros \- feature test macros +.SH DESCRIPTION +Feature test macros allow the programmer to control the definitions that +are exposed by system header files when a program is compiled. +.PP +.B NOTE: +In order to be effective, a feature test macro +.IR "must be defined before including any header files" . +This can be done either in the compilation command +.RI ( "cc \-DMACRO=value" ) +or by defining the macro within the source code before +including any headers. +.PP +Some feature test macros are useful for creating portable applications, +by preventing nonstandard definitions from being exposed. +Other macros can be used to expose nonstandard definitions that +are not exposed by default. +.PP +The precise effects of each of the feature test macros described below +can be ascertained by inspecting the +.I +header file. +.BR Note : +applications do +.I not +need to directly include +.IR ; +indeed, doing so is actively discouraged. +See NOTES. +.SS Specification of feature test macro requirements in manual pages +When a function requires that a feature test macro is defined, +the manual page SYNOPSIS typically includes a note of the following form +(this example from the +.BR acct (2) +manual page): +.PP +.RS 8 +.B #include +.PP +.BI "int acct(const char *" filename ); +.PP +.EX +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.EE +.in +.PP +.BR acct (): +_BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) +.RE +.PP +The +.B || +means that in order to obtain the declaration of +.BR acct (2) +from +.IR , +.I either +of the following macro +definitions must be made before including any header files: +.PP +.in +4n +.EX +#define _BSD_SOURCE +#define _XOPEN_SOURCE /* or any value < 500 */ +.EE +.in +.PP +Alternatively, equivalent definitions can be included in the +compilation command: +.PP +.in +4n +.EX +cc \-D_BSD_SOURCE +cc \-D_XOPEN_SOURCE # Or any value < 500 +.EE +.in +.PP +Note that, as described below, +.BR "some feature test macros are defined by default" , +so that it may not always be necessary to +explicitly specify the feature test macro(s) shown in the +SYNOPSIS. +.PP +In a few cases, manual pages use a shorthand for expressing the +feature test macro requirements (this example from +.BR readahead (2)): +.PP +.in +4n +.EX +.B #define _GNU_SOURCE +.B #include +.PP +.BI "ssize_t readahead(int " fd ", off64_t *" offset ", size_t " count ); +.EE +.in +.PP +This format is employed in cases where only a single +feature test macro can be used to expose the function +declaration, and that macro is not defined by default. +.SS Feature test macros understood by glibc +The paragraphs below explain how feature test macros are handled +in Linux glibc 2.\fIx\fP, +.I x +> 0. +.PP +First, though a summary of a few details for the impatient: +.IP * 3 +The macros that you most likely need to use in modern source code are +.BR _POSIX_C_SOURCE +(for definitions from various versions of POSIX.1), +.BR _XOPEN_SOURCE +(for definitions from various versions of SUS), +.BR _GNU_SOURCE +(for GNU and/or Linux specific stuff), and +.BR _DEFAULT_SOURCE +(to get definitions that would normally be provided by default). +.IP * +Certain macros are defined with default values. +Thus, although one or more macros may be indicated as being +required in the SYNOPSIS of a man page, +it may not be necessary to define them explicitly. +Full details of the defaults are given later in this man page. +.IP * +Defining +.BR _XOPEN_SOURCE +with a value of 600 or greater produces the same effects as defining +.BR _POSIX_C_SOURCE +with a value of 200112L or greater. +Where one sees +.IP +.in +4n +.EX +_POSIX_C_SOURCE >= 200112L +.EE +.in +.IP +in the feature test macro requirements in the SYNOPSIS of a man page, +it is implicit that the following has the same effect: +.IP +.in +4n +.EX +_XOPEN_SOURCE >= 600 +.EE +.in +.IP * +Defining +.BR _XOPEN_SOURCE +with a value of 700 or greater produces the same effects as defining +.BR _POSIX_C_SOURCE +with a value of 200809L or greater. +Where one sees +.IP +.in +4n +.EX +_POSIX_C_SOURCE >= 200809L +.EE +.in +.IP +in the feature test macro requirements in the SYNOPSIS of a man page, +it is implicit that the following has the same effect: +.IP +.in +4n +.EX +_XOPEN_SOURCE >= 700 +.EE +.in +.\" The details in glibc 2.0 are simpler, but combining a +.\" a description of them with the details in later glibc versions +.\" would make for a complicated description. +.PP +Linux glibc understands the following feature test macros: +.TP 8 +.B __STRICT_ANSI__ +ISO Standard C. +This macro is implicitly defined by +.BR gcc (1) +when invoked with, for example, the +.I -std=c99 +or +.I -ansi +flag. +.TP +.B _POSIX_C_SOURCE +Defining this macro causes header files to expose definitions as follows: +.RS +.IP \(bu 3 +The value 1 exposes definitions conforming to POSIX.1-1990 and +ISO C (1990). +.IP \(bu +The value 2 or greater additionally exposes +definitions for POSIX.2-1992. +.IP \(bu +The value 199309L or greater additionally exposes +definitions for POSIX.1b (real-time extensions). +.\" 199506L functionality is available only since glibc 2.1 +.IP \(bu +The value 199506L or greater additionally exposes +definitions for POSIX.1c (threads). +.IP \(bu +(Since glibc 2.3.3) +The value 200112L or greater additionally exposes definitions corresponding +to the POSIX.1-2001 base specification (excluding the XSI extension). +This value also causes C95 (since glibc 2.12) and +C99 (since glibc 2.10) features to be exposed +(in other words, the equivalent of defining +.BR _ISOC99_SOURCE ). +.IP \(bu +(Since glibc 2.10) +The value 200809L or greater additionally exposes definitions corresponding +to the POSIX.1-2008 base specification (excluding the XSI extension). +.RE +.TP +.B _POSIX_SOURCE +Defining this obsolete macro with any value is equivalent to defining +.B _POSIX_C_SOURCE +with the value 1. +.IP +Since this macro is obsolete, +its usage is generally not documented when discussing +feature test macro requirements in the man pages. +.TP +.B _XOPEN_SOURCE +Defining this macro causes header files to expose definitions as follows: +.RS +.IP \(bu 3 +Defining with any value exposes +definitions conforming to POSIX.1, POSIX.2, and XPG4. +.IP \(bu +The value 500 or greater additionally exposes +definitions for SUSv2 (UNIX 98). +.IP \(bu +(Since glibc 2.2) The value 600 or greater additionally exposes +definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification +plus the XSI extension) and C99 definitions. +.IP \(bu +(Since glibc 2.10) The value 700 or greater additionally exposes +definitions for SUSv4 (i.e., the POSIX.1-2008 base specification +plus the XSI extension). +.RE +.IP +If +.B __STRICT_ANSI__ +is not defined, or +.BR _XOPEN_SOURCE +is defined with a value greater than or equal to 500 +.I and +neither +.B _POSIX_SOURCE +nor +.B _POSIX_C_SOURCE +is explicitly defined, then +the following macros are implicitly defined: +.RS +.IP \(bu 3 +.B _POSIX_SOURCE +is defined with the value 1. +.IP \(bu +.B _POSIX_C_SOURCE +is defined, according to the value of +.BR _XOPEN_SOURCE : +.RS +.TP +.BR _XOPEN_SOURCE " < 500" +.B _POSIX_C_SOURCE +is defined with the value 2. +.TP +.RB "500 <= " _XOPEN_SOURCE " < 600" +.B _POSIX_C_SOURCE +is defined with the value 199506L. +.TP +.RB "600 <= " _XOPEN_SOURCE " < 700" +.B _POSIX_C_SOURCE +is defined with the value 200112L. +.TP +.RB "700 <= " _XOPEN_SOURCE " (since glibc 2.10)" +.B _POSIX_C_SOURCE +is defined with the value 200809L. +.RE +.RE +.IP +In addition, defining +.BR _XOPEN_SOURCE +with a value of 500 or greater produces the same effects as defining +.BR _XOPEN_SOURCE_EXTENDED . +.TP +.B _XOPEN_SOURCE_EXTENDED +If this macro is defined, +.I and +.B _XOPEN_SOURCE +is defined, then expose definitions corresponding to the XPG4v2 +(SUSv1) UNIX extensions (UNIX 95). +Defining +.B _XOPEN_SOURCE +with a value of 500 or more also produces the same effect as defining +.BR _XOPEN_SOURCE_EXTENDED . +Use of +.BR _XOPEN_SOURCE_EXTENDED +in new source code should be avoided. +.IP +Since defining +.B _XOPEN_SOURCE +with a value of 500 or more has the same effect as defining +.BR _XOPEN_SOURCE_EXTENDED , +the latter (obsolete) feature test macro is generally not described in the +SYNOPSIS in man pages. +.TP +.BR _ISOC99_SOURCE " (since glibc 2.1.3)" +Exposes declarations consistent with the ISO C99 standard. +.IP +Earlier glibc 2.1.x versions recognized an equivalent macro named +.B _ISOC9X_SOURCE +(because the C99 standard had not then been finalized). +Although the use of this macro is obsolete, glibc continues +to recognize it for backward compatibility. +.IP +Defining +.B _ISOC99_SOURCE +also exposes ISO C (1990) Amendment 1 ("C95") definitions. +(The primary change in C95 was support for international character sets.) +.IP +Invoking the C compiler with the option +.IR \-std=c99 +produces the same effects as defining this macro. +.TP +.BR _ISOC11_SOURCE " (since glibc 2.16)" +Exposes declarations consistent with the ISO C11 standard. +Defining this macro also enables C99 and C95 features (like +.BR _ISOC99_SOURCE ). +.IP +Invoking the C compiler with the option +.IR \-std=c11 +produces the same effects as defining this macro. +.TP +.B _LARGEFILE64_SOURCE +Expose definitions for the alternative API specified by the +LFS (Large File Summit) as a "transitional extension" to the +Single UNIX Specification. +(See +.UR http:\:/\:/opengroup.org\:/platform\:/lfs.html +.UE .) +The alternative API consists of a set of new objects +(i.e., functions and types) whose names are suffixed with "64" +(e.g., +.I off64_t +versus +.IR off_t , +.BR lseek64 () +versus +.BR lseek (), +etc.). +New programs should not employ this macro; instead +.I _FILE_OFFSET_BITS=64 +should be employed. +.TP +.BR _LARGEFILE_SOURCE +This macro was historically used to expose certain functions (specifically +.BR fseeko (3) +and +.BR ftello (3)) +that address limitations of earlier APIs +.RB ( fseek (3) +and +.BR ftell (3)) +that use +.IR "long int" +for file offsets. +This macro is implicitly defined if +.BR _XOPEN_SOURCE +is defined with a value greater than or equal to 500. +New programs should not employ this macro; +defining +.BR _XOPEN_SOURCE +as just described or defining +.B _FILE_OFFSET_BITS +with the value 64 is the preferred mechanism to achieve the same result. +.TP +.B _FILE_OFFSET_BITS +Defining this macro with the value 64 +automatically converts references to 32-bit functions and data types +related to file I/O and filesystem operations into references to +their 64-bit counterparts. +This is useful for performing I/O on large files (> 2 Gigabytes) +on 32-bit systems. +(Defining this macro permits correctly written programs to use +large files with only a recompilation being required.) +.IP +64-bit systems naturally permit file sizes greater than 2 Gigabytes, +and on those systems this macro has no effect. +.TP +.BR _BSD_SOURCE " (deprecated since glibc 2.20)" +Defining this macro with any value causes header files to expose +BSD-derived definitions. +.IP +In glibc versions up to and including 2.18, +defining this macro also causes BSD definitions to be preferred in +some situations where standards conflict, unless one or more of +.BR _SVID_SOURCE , +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.BR _XOPEN_SOURCE_EXTENDED , +or +.B _GNU_SOURCE +is defined, in which case BSD definitions are disfavored. +Since glibc 2.19, +.B _BSD_SOURCE +no longer causes BSD definitions to be preferred in case of conflicts. +.IP +Since glibc 2.20, this macro is deprecated. +.\" commit c941736c92fa3a319221f65f6755659b2a5e0a20 +.\" commit 498afc54dfee41d33ba519f496e96480badace8e +.\" commit acd7f096d79c181866d56d4aaf3b043e741f1e2c +It now has the same effect as defining +.BR _DEFAULT_SOURCE , +but generates a compile-time warning (unless +.BR _DEFAULT_SOURCE +.\" commit ade40b10ff5fa59a318cf55b9d8414b758e8df78 +is also defined). +Use +.B _DEFAULT_SOURCE +instead. +To allow code that requires +.BR _BSD_SOURCE +in glibc 2.19 and earlier and +.BR _DEFAULT_SOURCE +in glibc 2.20 and later to compile without warnings, define +.I both +.B _BSD_SOURCE +and +.BR _DEFAULT_SOURCE . +.TP +.BR _SVID_SOURCE " (deprecated since glibc 2.20)" +Defining this macro with any value causes header files to expose +System V-derived definitions. +(SVID == System V Interface Definition; see +.BR standards (7).) +.IP +Since glibc 2.20, this macro is deprecated in the same fashion as +.BR _BSD_SOURCE . +.TP +.BR _DEFAULT_SOURCE " (since glibc 2.19)" +This macro can be defined to ensure that the "default" +definitions are provided even when the defaults would otherwise +be disabled, +as happens when individual macros are explicitly defined, +or the compiler is invoked in one of its "standard" modes (e.g., +.IR "cc\ \-std=c99" ). +Defining +.B _DEFAULT_SOURCE +without defining other individual macros +or invoking the compiler in one of its "standard" modes has no effect. +.IP +The "default" definitions comprise those required by POSIX.1-2008 and ISO C99, +as well as various definitions originally derived from BSD and System V. +On glibc 2.19 and earlier, these defaults were approximately equivalent +to explicitly defining the following: +.IP + cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809 +.TP +.BR _ATFILE_SOURCE " (since glibc 2.4)" +Defining this macro with any value causes header files to expose +declarations of a range of functions with the suffix "at"; +see +.BR openat (2). +Since glibc 2.10, this macro is also implicitly defined if +.BR _POSIX_C_SOURCE +is defined with a value greater than or equal to 200809L. +.TP +.B _GNU_SOURCE +Defining this macro (with any value) implicitly defines +.BR _ATFILE_SOURCE , +.BR _LARGEFILE64_SOURCE , +.BR _ISOC99_SOURCE , +.BR _XOPEN_SOURCE_EXTENDED , +.BR _POSIX_SOURCE , +.B _POSIX_C_SOURCE +with the value 200809L +(200112L in glibc versions before 2.10; +199506L in glibc versions before 2.5; +199309L in glibc versions before 2.1) +and +.B _XOPEN_SOURCE +with the value 700 +(600 in glibc versions before 2.10; +500 in glibc versions before 2.2). +In addition, various GNU-specific extensions are also exposed. +.IP +Since glibc 2.19, defining +.BR _GNU_SOURCE +also has the effect of implicitly defining +.BR _DEFAULT_SOURCE . +In glibc versions before 2.20, defining +.BR _GNU_SOURCE +also had the effect of implicitly defining +.BR _BSD_SOURCE +and +.BR _SVID_SOURCE . +.TP +.B _REENTRANT +Historically, on various C libraries +it was necessary to define this macro in all +multithreaded code. +.\" Zack Weinberg +.\" There did once exist C libraries where it was necessary. The ones +.\" I remember were proprietary Unix vendor libcs from the mid-1990s +.\" You would get completely unlocked stdio without _REENTRANT. +(Some C libraries may still require this.) +In glibc, +this macro also exposed definitions of certain reentrant functions. +.IP +However, glibc has been thread-safe by default for many years; +since glibc 2.3, the only effect of defining +.BR _REENTRANT +has been to enable one or two of the same declarations that +are also enabled by defining +.BR _POSIX_C_SOURCE +with a value of 199606L or greater. +.IP +.B _REENTRANT +is now obsolete. +In glibc 2.25 and later, defining +.B _REENTRANT +is equivalent to defining +.B _POSIX_C_SOURCE +with the value 199606L. +If a higher POSIX conformance level is +selected by any other means (such as +.B _POSIX_C_SOURCE +itself, +.BR _XOPEN_SOURCE , +.BR _DEFAULT_SOURCE , +or +.BR _GNU_SOURCE ), +then defining +.B _REENTRANT +has no effect. +.IP +This macro is automatically defined if one compiles with +.IR "cc\ \-pthread" . +.TP +.B _THREAD_SAFE +Synonym for the (deprecated) +.BR _REENTRANT , +provided for compatibility with some other implementations. +.TP +.BR _FORTIFY_SOURCE " (since glibc 2.3.4)" +.\" For more detail, see: +.\" http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html +.\" [PATCH] Object size checking to prevent (some) buffer overflows +.\" * From: Jakub Jelinek +.\" * To: gcc-patches at gcc dot gnu dot org +.\" * Date: Tue, 21 Sep 2004 04:16:40 -0400 +Defining this macro causes some lightweight checks to be performed +to detect some buffer overflow errors when employing +various string and memory manipulation functions (for example, +.BR memcpy (3), +.BR memset (3), +.BR stpcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR strcat (3), +.BR strncat (3), +.BR sprintf (3), +.BR snprintf (3), +.BR vsprintf (3), +.BR vsnprintf (3), +.BR gets (3), +and wide character variants thereof). +For some functions, argument consistency is checked; +for example, a check is made that +.BR open (2) +has been supplied with a +.I mode +argument when the specified flags include +.BR O_CREAT . +Not all problems are detected, just some common cases. +.\" Look for __USE_FORTIFY_LEVEL in the header files +.IP +If +.B _FORTIFY_SOURCE +is set to 1, with compiler optimization level 1 +.RI ( "gcc\ \-O1" ) +and above, checks that shouldn't change the behavior of +conforming programs are performed. +With +.B _FORTIFY_SOURCE +set to 2, some more checking is added, but +some conforming programs might fail. +.\" For example, given the following code +.\" int d; +.\" char buf[1000], buf[1000]; +.\" strcpy(fmt, "Hello world\n%n"); +.\" snprintf(buf, sizeof(buf), fmt, &d); +.\" +.\" Compiling with "gcc -D_FORTIFY_SOURCE=2 -O1" and then running will +.\" cause the following diagnostic at runtime at the snprintf() call +.\" +.\" *** %n in writable segment detected *** +.\" Aborted (core dumped) +.\" +.IP +Some of the checks can be performed at compile time +(via macros logic implemented in header files), +and result in compiler warnings; +other checks take place at run time, +and result in a run-time error if the check fails. +.IP +Use of this macro requires compiler support, available with +.BR gcc (1) +since version 4.0. +.SS Default definitions, implicit definitions, and combining definitions +.PP +If no feature test macros are explicitly defined, +then the following feature test macros are defined by default: +.BR _BSD_SOURCE +(in glibc 2.19 and earlier), +.BR _SVID_SOURCE +(in glibc 2.19 and earlier), +.BR _DEFAULT_SOURCE +(since glibc 2.19), +.BR _POSIX_SOURCE , +and +.BR _POSIX_C_SOURCE =200809L +(200112L in glibc versions before 2.10; +199506L in glibc versions before 2.4; +199309L in glibc versions before 2.1). +.PP +If any of +.BR __STRICT_ANSI__ , +.BR _ISOC99_SOURCE , +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.BR _XOPEN_SOURCE_EXTENDED , +.BR _BSD_SOURCE +(in glibc 2.19 and earlier), +or +.B _SVID_SOURCE +(in glibc 2.19 and earlier) +is explicitly defined, then +.BR _BSD_SOURCE , +.BR _SVID_SOURCE , +and +.BR _DEFAULT_SOURCE +are not defined by default. +.PP +If +.B _POSIX_SOURCE +and +.B _POSIX_C_SOURCE +are not explicitly defined, +and either +.B __STRICT_ANSI__ +is not defined or +.B _XOPEN_SOURCE +is defined with a value of 500 or more, then +.IP * 3 +.B _POSIX_SOURCE +is defined with the value 1; and +.IP * +.B _POSIX_C_SOURCE +is defined with one of the following values: +.RS 3 +.IP \(bu 3 +2, +if +.B _XOPEN_SOURCE +is defined with a value less than 500; +.IP \(bu +199506L, +if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 500 and less than 600; +or +.IP \(bu +(since glibc 2.4) 200112L, +if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 600 and less than 700. +.IP \(bu +(Since glibc 2.10) +200809L, +if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 700. +.IP \(bu +Older versions of glibc do not know about the values +200112L and 200809L for +.BR _POSIX_C_SOURCE , +and the setting of this macro will depend on the glibc version. +.IP \(bu +If +.B _XOPEN_SOURCE +is undefined, then the setting of +.B _POSIX_C_SOURCE +depends on the glibc version: +199506L, in glibc versions before 2.4; +200112L, in glibc 2.4 to 2.9; and +200809L, since glibc 2.10. +.RE +.PP +Multiple macros can be defined; the results are additive. +.SH CONFORMING TO +POSIX.1 specifies +.BR _POSIX_C_SOURCE , +.BR _POSIX_SOURCE , +and +.BR _XOPEN_SOURCE . +.PP +.B _XOPEN_SOURCE_EXTENDED +was specified by XPG4v2 (aka SUSv1), but is not present in SUSv2 and later. +.B _FILE_OFFSET_BITS +is not specified by any standard, +but is employed on some other implementations. +.PP +.BR _BSD_SOURCE , +.BR _SVID_SOURCE , +.BR _DEFAULT_SOURCE , +.BR _ATFILE_SOURCE , +.BR _GNU_SOURCE , +.BR _FORTIFY_SOURCE , +.BR _REENTRANT , +and +.B _THREAD_SAFE +are specific to Linux (glibc). +.SH NOTES +.I +is a Linux/glibc-specific header file. +Other systems have an analogous file, but typically with a different name. +This header file is automatically included by other header files as +required: it is not necessary to explicitly include it in order to +employ feature test macros. +.PP +According to which of the above feature test macros are defined, +.I +internally defines various other macros that are checked by +other glibc header files. +These macros have names prefixed by two underscores (e.g., +.BR __USE_MISC ). +Programs should +.I never +define these macros directly: +instead, the appropriate feature test macro(s) from the +list above should be employed. +.SH EXAMPLE +The program below can be used to explore how the various +feature test macros are set depending on the glibc version +and what feature test macros are explicitly set. +The following shell session, on a system with glibc 2.10, +shows some examples of what we would see: +.PP +.in +4n +.EX +$ \fBcc ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 200809L +_BSD_SOURCE defined +_SVID_SOURCE defined +_ATFILE_SOURCE defined +$ \fBcc \-D_XOPEN_SOURCE=500 ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 199506L +_XOPEN_SOURCE defined: 500 +$ \fBcc \-D_GNU_SOURCE ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 200809L +_ISOC99_SOURCE defined +_XOPEN_SOURCE defined: 700 +_XOPEN_SOURCE_EXTENDED defined +_LARGEFILE64_SOURCE defined +_BSD_SOURCE defined +_SVID_SOURCE defined +_ATFILE_SOURCE defined +_GNU_SOURCE defined +.EE +.in +.SS Program source +\& +.EX +/* ftm.c */ + +#include +#include +#include + +int +main(int argc, char *argv[]) +{ +#ifdef _POSIX_SOURCE + printf("_POSIX_SOURCE defined\\n"); +#endif + +#ifdef _POSIX_C_SOURCE + printf("_POSIX_C_SOURCE defined: %ldL\\n", (long) _POSIX_C_SOURCE); +#endif + +#ifdef _ISOC99_SOURCE + printf("_ISOC99_SOURCE defined\\n"); +#endif + +#ifdef _ISOC11_SOURCE + printf("_ISOC11_SOURCE defined\\n"); +#endif + +#ifdef _XOPEN_SOURCE + printf("_XOPEN_SOURCE defined: %d\\n", _XOPEN_SOURCE); +#endif + +#ifdef _XOPEN_SOURCE_EXTENDED + printf("_XOPEN_SOURCE_EXTENDED defined\\n"); +#endif + +#ifdef _LARGEFILE64_SOURCE + printf("_LARGEFILE64_SOURCE defined\\n"); +#endif + +#ifdef _FILE_OFFSET_BITS + printf("_FILE_OFFSET_BITS defined: %d\\n", _FILE_OFFSET_BITS); +#endif + +#ifdef _BSD_SOURCE + printf("_BSD_SOURCE defined\\n"); +#endif + +#ifdef _SVID_SOURCE + printf("_SVID_SOURCE defined\\n"); +#endif + +#ifdef _DEFAULT_SOURCE + printf("_DEFAULT_SOURCE defined\\n"); +#endif + +#ifdef _ATFILE_SOURCE + printf("_ATFILE_SOURCE defined\\n"); +#endif + +#ifdef _GNU_SOURCE + printf("_GNU_SOURCE defined\\n"); +#endif + +#ifdef _REENTRANT + printf("_REENTRANT defined\\n"); +#endif + +#ifdef _THREAD_SAFE + printf("_THREAD_SAFE defined\\n"); +#endif + +#ifdef _FORTIFY_SOURCE + printf("_FORTIFY_SOURCE defined\\n"); +#endif + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR libc (7), +.BR standards (7) +.PP +The section "Feature Test Macros" under +.IR "info libc" . +.\" But beware: the info libc document is out of date (Jul 07, mtk) +.PP +.I /usr/include/features.h +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/fifo.7 b/man7/fifo.7 new file mode 100644 index 0000000..aaa5f36 --- /dev/null +++ b/man7/fifo.7 @@ -0,0 +1,84 @@ +.\" This man page is Copyright (C) 1999 Claus Fischer. +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" 990620 - page created - aeb@cwi.nl +.\" +.TH FIFO 7 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +fifo \- first-in first-out special file, named pipe +.SH DESCRIPTION +A FIFO special file (a named pipe) is similar to a pipe, +except that it is accessed as part of the filesystem. +It can be opened by multiple processes for reading or +writing. +When processes are exchanging data via the FIFO, +the kernel passes all data internally without writing it +to the filesystem. +Thus, the FIFO special file has no +contents on the filesystem; the filesystem entry merely +serves as a reference point so that processes can access +the pipe using a name in the filesystem. +.PP +The kernel maintains exactly one pipe object for each +FIFO special file that is opened by at least one process. +The FIFO must be opened on both ends (reading and writing) +before data can be passed. +Normally, opening the FIFO blocks +until the other end is opened also. +.PP +A process can open a FIFO in nonblocking mode. +In this +case, opening for read-only succeeds even if no one has +opened on the write side yet and opening for write-only +fails with +.B ENXIO +(no such device or address) unless the other +end has already been opened. +.PP +Under Linux, opening a FIFO for read and write will succeed +both in blocking and nonblocking mode. +POSIX leaves this +behavior undefined. +This can be used to open a FIFO for +writing while there are no readers available. +A process +that uses both ends of the connection in order to communicate +with itself should be very careful to avoid deadlocks. +.SH NOTES +For details of the semantics of I/O on FIFOs, see +.BR pipe (7). +.PP +When a process tries to write to a FIFO that is not opened +for read on the other side, the process is sent a +.B SIGPIPE +signal. +.PP +FIFO special files can be created by +.BR mkfifo (3), +and are indicated by +.IR "ls\ \-l" +with the file type \(aqp\(aq. +.SH SEE ALSO +.BR mkfifo (1), +.BR open (2), +.BR pipe (2), +.BR sigaction (2), +.BR signal (2), +.BR socketpair (2), +.BR mkfifo (3), +.BR pipe (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/futex.7 b/man7/futex.7 new file mode 100644 index 0000000..18b17e4 --- /dev/null +++ b/man7/futex.7 @@ -0,0 +1,136 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng . +.\" +.\" %%%LICENSE_START(MIT) +.\" This page is made available under the MIT license. +.\" %%%LICENSE_END +.\" +.TH FUTEX 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +futex \- fast user-space locking +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +.PP +The Linux kernel provides futexes ("Fast user-space mutexes") +as a building block for fast user-space +locking and semaphores. +Futexes are very basic and lend themselves well for building higher-level +locking abstractions such as +mutexes, condition variables, read-write locks, barriers, and semaphores. +.PP +Most programmers will in fact not be using futexes directly but will +instead rely on system libraries built on them, +such as the Native POSIX Thread Library (NPTL) (see +.BR pthreads (7)). +.PP +A futex is identified by a piece of memory which can be +shared between processes or threads. +In these different processes, the futex need not have identical addresses. +In its bare form, a futex has semaphore semantics; +it is a counter that can be incremented and decremented atomically; +processes can wait for the value to become positive. +.PP +Futex operation occurs entirely in user space for the noncontended case. +The kernel is involved only to arbitrate the contended case. +As any sane design will strive for noncontention, +futexes are also optimized for this situation. +.PP +In its bare form, a futex is an aligned integer which is +touched only by atomic assembler instructions. +This integer is four bytes long on all platforms. +Processes can share this integer using +.BR mmap (2), +via shared memory segments, or because they share memory space, +in which case the application is commonly called multithreaded. +.SS Semantics +.PP +Any futex operation starts in user space, +but it may be necessary to communicate with the kernel using the +.BR futex (2) +system call. +.PP +To "up" a futex, execute the proper assembler instructions that +will cause the host CPU to atomically increment the integer. +Afterward, check if it has in fact changed from 0 to 1, in which case +there were no waiters and the operation is done. +This is the noncontended case which is fast and should be common. +.PP +In the contended case, the atomic increment changed the counter +from \-1 (or some other negative number). +If this is detected, there are waiters. +User space should now set the counter to 1 and instruct the +kernel to wake up any waiters using the +.B FUTEX_WAKE +operation. +.PP +Waiting on a futex, to "down" it, is the reverse operation. +Atomically decrement the counter and check if it changed to 0, +in which case the operation is done and the futex was uncontended. +In all other circumstances, the process should set the counter to \-1 +and request that the kernel wait for another process to up the futex. +This is done using the +.B FUTEX_WAIT +operation. +.PP +The +.BR futex (2) +system call can optionally be passed a timeout specifying how long +the kernel should +wait for the futex to be upped. +In this case, semantics are more complex and the programmer is referred +to +.BR futex (2) +for +more details. +The same holds for asynchronous futex waiting. +.SH VERSIONS +.PP +Initial futex support was merged in Linux 2.5.7 +but with different semantics from those described above. +Current semantics are available from Linux 2.5.40 onward. +.SH NOTES +.PP +To reiterate, bare futexes are not intended as an easy-to-use +abstraction for end users. +Implementors are expected to be assembly literate and to have read +the sources of the futex user-space library referenced +below. +.PP +This man page illustrates the most common use of the +.BR futex (2) +primitives; it is by no means the only one. +.\" .SH AUTHORS +.\" .PP +.\" Futexes were designed and worked on by Hubertus Franke +.\" (IBM Thomas J. Watson Research Center), +.\" Matthew Kirkwood, Ingo Molnar (Red Hat) and +.\" Rusty Russell (IBM Linux Technology Center). +.\" This page written by bert hubert. +.SH SEE ALSO +.BR clone (2), +.BR futex (2), +.BR get_robust_list (2), +.BR set_robust_list (2), +.BR set_tid_address (2), +.BR pthreads (7) +.PP +.IR "Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux" +(proceedings of the Ottawa Linux Symposium 2002), +futex example library, futex-*.tar.bz2 +.UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ +.UE . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/glibc.7 b/man7/glibc.7 new file mode 100644 index 0000000..0d1ed26 --- /dev/null +++ b/man7/glibc.7 @@ -0,0 +1 @@ +.so man7/libc.7 diff --git a/man7/glob.7 b/man7/glob.7 new file mode 100644 index 0000000..662fed0 --- /dev/null +++ b/man7/glob.7 @@ -0,0 +1,222 @@ +.\" Copyright (c) 1998 Andries Brouwer +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2003-08-24 fix for / by John Kristoff + joey +.\" +.TH GLOB 7 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +glob \- globbing pathnames +.SH DESCRIPTION +Long ago, in UNIX\ V6, there was a program +.I /etc/glob +that would expand wildcard patterns. +Soon afterward this became a shell built-in. +.PP +These days there is also a library routine +.BR glob (3) +that will perform this function for a user program. +.PP +The rules are as follows (POSIX.2, 3.13). +.SS Wildcard matching +A string is a wildcard pattern if it contains one of the +characters \(aq?\(aq, \(aq*\(aq or \(aq[\(aq. +Globbing is the operation +that expands a wildcard pattern into the list of pathnames +matching the pattern. +Matching is defined by: +.PP +A \(aq?\(aq (not between brackets) matches any single character. +.PP +A \(aq*\(aq (not between brackets) matches any string, +including the empty string. +.PP +.B "Character classes" +.PP +An expression "\fI[...]\fP" where the first character after the +leading \(aq[\(aq is not an \(aq!\(aq matches a single character, +namely any of the characters enclosed by the brackets. +The string enclosed by the brackets cannot be empty; +therefore \(aq]\(aq can be allowed between the brackets, provided +that it is the first character. +(Thus, "\fI[][!]\fP" matches the +three characters \(aq[\(aq, \(aq]\(aq and \(aq!\(aq.) +.PP +.B Ranges +.PP +There is one special convention: +two characters separated by \(aq\-\(aq denote a range. +(Thus, "\fI[A\-Fa\-f0\-9]\fP" +is equivalent to "\fI[ABCDEFabcdef0123456789]\fP".) +One may include \(aq\-\(aq in its literal meaning by making it the +first or last character between the brackets. +(Thus, "\fI[]\-]\fP" matches just the two characters \(aq]\(aq and \(aq\-\(aq, +and "\fI[\-\-0]\fP" matches the +three characters \(aq\-\(aq, \(aq.\(aq, \(aq0\(aq, since \(aq/\(aq +cannot be matched.) +.PP +.B Complementation +.PP +An expression "\fI[!...]\fP" matches a single character, namely +any character that is not matched by the expression obtained +by removing the first \(aq!\(aq from it. +(Thus, "\fI[!]a\-]\fP" matches any +single character except \(aq]\(aq, \(aqa\(aq and \(aq\-\(aq.) +.PP +One can remove the special meaning of \(aq?\(aq, \(aq*\(aq and \(aq[\(aq by +preceding them by a backslash, or, in case this is part of +a shell command line, enclosing them in quotes. +Between brackets these characters stand for themselves. +Thus, "\fI[[?*\e]\fP" matches the +four characters \(aq[\(aq, \(aq?\(aq, \(aq*\(aq and \(aq\e\(aq. +.SS Pathnames +Globbing is applied on each of the components of a pathname +separately. +A \(aq/\(aq in a pathname cannot be matched by a \(aq?\(aq or \(aq*\(aq +wildcard, or by a range like "\fI[.\-0]\fP". +A range containing an explicit \(aq/\(aq character is syntactically incorrect. +(POSIX requires that syntactically incorrect patterns are left unchanged.) +.PP +If a filename starts with a \(aq.\(aq, +this character must be matched explicitly. +(Thus, \fIrm\ *\fP will not remove .profile, and \fItar\ c\ *\fP will not +archive all your files; \fItar\ c\ .\fP is better.) +.SS Empty lists +The nice and simple rule given above: "expand a wildcard pattern +into the list of matching pathnames" was the original UNIX +definition. +It allowed one to have patterns that expand into +an empty list, as in +.PP +.nf + xv \-wait 0 *.gif *.jpg +.fi +.PP +where perhaps no *.gif files are present (and this is not +an error). +However, POSIX requires that a wildcard pattern is left +unchanged when it is syntactically incorrect, or the list of +matching pathnames is empty. +With +.I bash +one can force the classical behavior using this command: +.PP + shopt \-s nullglob +.\" In Bash v1, by setting allow_null_glob_expansion=true +.PP +(Similar problems occur elsewhere. +For example, where old scripts have +.PP +.nf + rm \`find . \-name "*~"\` +.fi +.PP +new scripts require +.PP +.nf + rm \-f nosuchfile \`find . \-name "*~"\` +.fi +.PP +to avoid error messages from +.I rm +called with an empty argument list.) +.SH NOTES +.SS Regular expressions +Note that wildcard patterns are not regular expressions, +although they are a bit similar. +First of all, they match +filenames, rather than text, and secondly, the conventions +are not the same: for example, in a regular expression \(aq*\(aq means zero or +more copies of the preceding thing. +.PP +Now that regular expressions have bracket expressions where +the negation is indicated by a \(aq^\(aq, POSIX has declared the +effect of a wildcard pattern "\fI[^...]\fP" to be undefined. +.SS Character classes and internationalization +Of course ranges were originally meant to be ASCII ranges, +so that "\fI[\ \-%]\fP" stands for "\fI[\ !"#$%]\fP" and "\fI[a\-z]\fP" stands +for "any lowercase letter". +Some UNIX implementations generalized this so that a range X\-Y +stands for the set of characters with code between the codes for +X and for Y. +However, this requires the user to know the +character coding in use on the local system, and moreover, is +not convenient if the collating sequence for the local alphabet +differs from the ordering of the character codes. +Therefore, POSIX extended the bracket notation greatly, +both for wildcard patterns and for regular expressions. +In the above we saw three types of items that can occur in a bracket +expression: namely (i) the negation, (ii) explicit single characters, +and (iii) ranges. +POSIX specifies ranges in an internationally +more useful way and adds three more types: +.PP +(iii) Ranges X\-Y comprise all characters that fall between X +and Y (inclusive) in the current collating sequence as defined +by the +.B LC_COLLATE +category in the current locale. +.PP +(iv) Named character classes, like +.PP +.nf +[:alnum:] [:alpha:] [:blank:] [:cntrl:] +[:digit:] [:graph:] [:lower:] [:print:] +[:punct:] [:space:] [:upper:] [:xdigit:] +.fi +.PP +so that one can say "\fI[[:lower:]]\fP" instead of "\fI[a\-z]\fP", and have +things work in Denmark, too, where there are three letters past \(aqz\(aq +in the alphabet. +These character classes are defined by the +.B LC_CTYPE +category +in the current locale. +.PP +(v) Collating symbols, like "\fI[.ch.]\fP" or "\fI[.a-acute.]\fP", +where the string between "\fI[.\fP" and "\fI.]\fP" is a collating +element defined for the current locale. +Note that this may +be a multicharacter element. +.PP +(vi) Equivalence class expressions, like "\fI[=a=]\fP", +where the string between "\fI[=\fP" and "\fI=]\fP" is any collating +element from its equivalence class, as defined for the +current locale. +For example, "\fI[[=a=]]\fP" might be equivalent +to "\fI[a\('a\(`a\(:a\(^a]\fP", that is, +to "\fI[a[.a-acute.][.a-grave.][.a-umlaut.][.a-circumflex.]]\fP". +.SH SEE ALSO +.BR sh (1), +.BR fnmatch (3), +.BR glob (3), +.BR locale (7), +.BR regex (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/hier.7 b/man7/hier.7 new file mode 100644 index 0000000..39214fc --- /dev/null +++ b/man7/hier.7 @@ -0,0 +1,660 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sun Jul 25 11:05:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Feb 10 16:18:03 1996 by Urs Thuermann (urs@isnogud.escape.de) +.\" Modified Mon Jun 16 20:02:00 1997 by Nicolás Lichtmaier +.\" Modified Mon Feb 6 16:41:00 1999 by Nicolás Lichtmaier +.\" Modified Tue Feb 8 16:46:45 2000 by Chris Pepper +.\" Modified Fri Sep 7 20:32:45 2001 by Tammy Fox +.TH HIER 7 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +hier \- description of the filesystem hierarchy +.SH DESCRIPTION +A typical Linux system has, among others, the following directories: +.TP +.I / +This is the root directory. +This is where the whole tree starts. +.TP +.I /bin +This directory contains executable programs which are needed in +single user mode and to bring the system up or repair it. +.TP +.I /boot +Contains static files for the boot loader. +This directory holds only +the files which are needed during the boot process. +The map installer +and configuration files should go to +.I /sbin +and +.IR /etc . +The operating system kernel (initrd for example) must be located in either +.I / +or +.IR /boot . +.TP +.I /dev +Special or device files, which refer to physical devices. +See +.BR mknod (1). +.TP +.I /etc +Contains configuration files which are local to the machine. +Some +larger software packages, like X11, can have their own subdirectories +below +.IR /etc . +Site-wide configuration files may be placed here or in +.IR /usr/etc . +Nevertheless, programs should always look for these files in +.I /etc +and you may have links for these files to +.IR /usr/etc . +.TP +.I /etc/opt +Host-specific configuration files for add-on applications installed +in +.IR /opt . +.TP +.I /etc/sgml +This directory contains the configuration files for SGML (optional). +.TP +.I /etc/skel +When a new user account is created, files from this directory are +usually copied into the user's home directory. +.TP +.I /etc/X11 +Configuration files for the X11 window system (optional). +.TP +.I /etc/xml +This directory contains the configuration files for XML (optional). +.TP +.I /home +On machines with home directories for users, these are usually beneath +this directory, directly or not. +The structure of this directory +depends on local administration decisions (optional). +.TP +.I /lib +This directory should hold those shared libraries that are necessary +to boot the system and to run the commands in the root filesystem. +.TP +.I /lib +These directories are variants of +.I /lib +on system which support more than one binary format requiring separate +libraries (optional). +.TP +.I /lib/modules +Loadable kernel modules (optional). +.TP +.I /lost+found +This directory contains items lost in the filesystem. +These items are usually chunks of files mangled as a consequence of +a faulty disk or a system crash. +.TP +.I /media +This directory contains mount points for removable media such as CD +and DVD disks or USB sticks. +On systems where more than one device exists +for mounting a certain type of media, +mount directories can be created by appending a digit +to the name of those available above starting with '0', +but the unqualified name must also exist. +.TP +.I /media/floppy[1\-9] +Floppy drive (optional). +.TP +.I /media/cdrom[1\-9] +CD-ROM drive (optional). +.TP +.I /media/cdrecorder[1\-9] +CD writer (optional). +.TP +.I /media/zip[1\-9] +Zip drive (optional). +.TP +.I /media/usb[1\-9] +USB drive (optional). +.TP +.I /mnt +This directory is a mount point for a temporarily mounted filesystem. +In some distributions, +.I /mnt +contains subdirectories intended to be used as mount points for several +temporary filesystems. +.TP +.I /opt +This directory should contain add-on packages that contain static files. +.TP +.I /proc +This is a mount point for the +.I proc +filesystem, which provides information about running processes and +the kernel. +This pseudo-filesystem is described in more detail in +.BR proc (5). +.TP +.I /root +This directory is usually the home directory for the root user (optional). +.TP +.I /sbin +Like +.IR /bin , +this directory holds commands needed to boot the system, but which are +usually not executed by normal users. +.TP +.I /srv +This directory contains site-specific data that is served by this system. +.TP +.I /sys +This is a mount point for the sysfs filesystem, which provides information +about the kernel like +.IR /proc , +but better structured, following the formalism of kobject infrastructure. +.TP +.I /tmp +This directory contains temporary files which may be deleted with no +notice, such as by a regular job or at system boot up. +.TP +.I /usr +This directory is usually mounted from a separate partition. +It should hold only shareable, read-only data, so that it can be mounted +by various machines running Linux. +.TP +.I /usr/X11R6 +The X\-Window system, version 11 release 6 (optional). +.TP +.I /usr/X11R6/bin +Binaries which belong to the X\-Window system; often, there is a +symbolic link from the more traditional +.I /usr/bin/X11 +to here. +.TP +.I /usr/X11R6/lib +Data files associated with the X\-Window system. +.TP +.I /usr/X11R6/lib/X11 +These contain miscellaneous files needed to run X; Often, there is a +symbolic link from +.I /usr/lib/X11 +to this directory. +.TP +.I /usr/X11R6/include/X11 +Contains include files needed for compiling programs using the X11 +window system. +Often, there is a symbolic link from +.I /usr/include/X11 +to this directory. +.TP +.I /usr/bin +This is the primary directory for executable programs. +Most programs +executed by normal users which are not needed for booting or for +repairing the system and which are not installed locally should be +placed in this directory. +.TP +.I /usr/bin/mh +Commands for the MH mail handling system (optional). +.TP +.I /usr/bin/X11 +is the traditional place to look for X11 executables; on Linux, it +usually is a symbolic link to +.IR /usr/X11R6/bin . +.TP +.I /usr/dict +Replaced by +.IR /usr/share/dict . +.TP +.I /usr/doc +Replaced by +.IR /usr/share/doc . +.TP +.I /usr/etc +Site-wide configuration files to be shared between several machines +may be stored in this directory. +However, commands should always +reference those files using the +.I /etc +directory. +Links from files in +.I /etc +should point to the appropriate files in +.IR /usr/etc . +.TP +.I /usr/games +Binaries for games and educational programs (optional). +.TP +.I /usr/include +Include files for the C compiler. +.TP +.I /usr/include/bsd +BSD compatibility include files (optional). +.TP +.I /usr/include/X11 +Include files for the C compiler and the X\-Window system. +This is +usually a symbolic link to +.IR /usr/X11R6/include/X11 . +.TP +.I /usr/include/asm +Include files which declare some assembler functions. +This used to be a +symbolic link to +.IR /usr/src/linux/include/asm . +.TP +.I /usr/include/linux +This contains information which may change from system release to +system release and used to be a symbolic link to +.I /usr/src/linux/include/linux +to get at operating-system-specific information. +.IP +(Note that one should have include files there that work correctly with +the current libc and in user space. +However, Linux kernel source is not +designed to be used with user programs and does not know anything +about the libc you are using. +It is very likely that things will break +if you let +.I /usr/include/asm +and +.I /usr/include/linux +point at a random kernel tree. +Debian systems don't do this +and use headers from a known good kernel +version, provided in the libc*-dev package.) +.TP +.I /usr/include/g++ +Include files to use with the GNU C++ compiler. +.TP +.I /usr/lib +Object libraries, including dynamic libraries, plus some executables +which usually are not invoked directly. +More complicated programs may +have whole subdirectories there. +.TP +.I /usr/lib +These directories are variants of +.I /usr/lib +on system which support more than one binary format requiring separate +libraries, except that the symbolic link +.I /usr/lib/X11 +is not required (optional). +.TP +.I /usr/lib/X11 +The usual place for data files associated with X programs, and +configuration files for the X system itself. +On Linux, it usually is +a symbolic link to +.IR /usr/X11R6/lib/X11 . +.TP +.I /usr/lib/gcc-lib +contains executables and include files for the GNU C compiler, +.BR gcc (1). +.TP +.I /usr/lib/groff +Files for the GNU groff document formatting system. +.TP +.I /usr/lib/uucp +Files for +.BR uucp (1). +.TP +.I /usr/local +This is where programs which are local to the site typically go. +.TP +.I /usr/local/bin +Binaries for programs local to the site. +.TP +.I /usr/local/doc +Local documentation. +.TP +.I /usr/local/etc +Configuration files associated with locally installed programs. +.TP +.I /usr/local/games +Binaries for locally installed games. +.TP +.I /usr/local/lib +Files associated with locally installed programs. +.TP +.I /usr/local/lib +These directories are variants of +.I /usr/local/lib +on system which support more than one binary format requiring separate +libraries (optional). +.TP +.I /usr/local/include +Header files for the local C compiler. +.TP +.I /usr/local/info +Info pages associated with locally installed programs. +.TP +.I /usr/local/man +Man pages associated with locally installed programs. +.TP +.I /usr/local/sbin +Locally installed programs for system administration. +.TP +.I /usr/local/share +Local application data that can be shared among different architectures +of the same OS. +.TP +.I /usr/local/src +Source code for locally installed software. +.TP +.I /usr/man +Replaced by +.IR /usr/share/man . +.TP +.I /usr/sbin +This directory contains program binaries for system administration +which are not essential for the boot process, for mounting +.IR /usr , +or for system repair. +.TP +.I /usr/share +This directory contains subdirectories with specific application data, that +can be shared among different architectures of the same OS. +Often one finds stuff here that used to live in +.I /usr/doc +or +.I /usr/lib +or +.IR /usr/man . +.TP +.I /usr/share/dict +Contains the word lists used by spell checkers (optional). +.TP +.I /usr/share/dict/words +List of English words (optional). +.TP +.I /usr/share/doc +Documentation about installed programs (optional). +.TP +.I /usr/share/games +Static data files for games in +.I /usr/games +(optional). +.TP +.I /usr/share/info +Info pages go here (optional). +.TP +.I /usr/share/locale +Locale information goes here (optional). +.TP +.I /usr/share/man +Manual pages go here in subdirectories according to the man page sections. +.TP +.I /usr/share/man//man[1\-9] +These directories contain manual pages for the +specific locale in source code form. +Systems which use a unique language and code set for all manual pages +may omit the substring. +.TP +.I /usr/share/misc +Miscellaneous data that can be shared among different architectures of the +same OS. +.TP +.I /usr/share/nls +The message catalogs for native language support go here (optional). +.TP +.I /usr/share/sgml +Files for SGML (optional). +.TP +.I /usr/share/sgml/docbook +DocBook DTD (optional). +.TP +.I /usr/share/sgml/tei +TEI DTD (optional). +.TP +.I /usr/share/sgml/html +HTML DTD (optional). +.TP +.I /usr/share/sgml/mathtml +MathML DTD (optional). +.TP +.I /usr/share/terminfo +The database for terminfo (optional). +.TP +.I /usr/share/tmac +Troff macros that are not distributed with groff (optional). +.TP +.I /usr/share/xml +Files for XML (optional). +.TP +.I /usr/share/xml/docbook +DocBook DTD (optional). +.TP +.I /usr/share/xml/xhtml +XHTML DTD (optional). +.TP +.I /usr/share/xml/mathml +MathML DTD (optional). +.TP +.I /usr/share/zoneinfo +Files for timezone information (optional). +.TP +.I /usr/src +Source files for different parts of the system, included with some packages +for reference purposes. +Don't work here with your own projects, as files +below /usr should be read-only except when installing software (optional). +.TP +.I /usr/src/linux +This was the traditional place for the kernel source. +Some distributions put here the source for the default kernel they ship. +You should probably use another directory when building your own kernel. +.TP +.I /usr/tmp +Obsolete. +This should be a link +to +.IR /var/tmp . +This link is present only for compatibility reasons and shouldn't be used. +.TP +.I /var +This directory contains files which may change in size, such as spool +and log files. +.TP +.I /var/account +Process accounting logs (optional). +.TP +.I /var/adm +This directory is superseded by +.I /var/log +and should be a symbolic link to +.IR /var/log . +.TP +.I /var/backups +Reserved for historical reasons. +.TP +.I /var/cache +Data cached for programs. +.TP +.I /var/cache/fonts +Locally-generated fonts (optional). +.TP +.I /var/cache/man +Locally-formatted man pages (optional). +.TP +.I /var/cache/www +WWW proxy or cache data (optional). +.TP +.I /var/cache/ +Package specific cache data (optional). +.TP +.IR /var/catman/cat[1\-9] " or " /var/cache/man/cat[1\-9] +These directories contain preformatted manual pages according to their +man page section. +(The use of preformatted manual pages is deprecated.) +.TP +.I /var/crash +System crash dumps (optional). +.TP +.I /var/cron +Reserved for historical reasons. +.TP +.I /var/games +Variable game data (optional). +.TP +.I /var/lib +Variable state information for programs. +.TP +.I /var/lib/hwclock +State directory for hwclock (optional). +.TP +.I /var/lib/misc +Miscellaneous state data. +.TP +.I /var/lib/xdm +X display manager variable data (optional). +.TP +.I /var/lib/ +Editor backup files and state (optional). +.TP +.I /var/lib/ +These directories must be used for all distribution packaging support. +.TP +.I /var/lib/ +State data for packages and subsystems (optional). +.TP +.I /var/lib/ +Packaging support files (optional). +.TP +.I /var/local +Variable data for +.IR /usr/local . +.TP +.I /var/lock +Lock files are placed in this directory. +The naming convention for +device lock files is +.I LCK.. +where +.I +is the device's name in the filesystem. +The format used is that of HDU UUCP lock files, that is, lock files +contain a PID as a 10-byte ASCII decimal number, followed by a newline +character. +.TP +.I /var/log +Miscellaneous log files. +.TP +.I /var/opt +Variable data for +.IR /opt . +.TP +.I /var/mail +Users' mailboxes. +Replaces +.IR /var/spool/mail . +.TP +.I /var/msgs +Reserved for historical reasons. +.TP +.I /var/preserve +Reserved for historical reasons. +.TP +.I /var/run +Run-time variable files, like files holding process identifiers (PIDs) +and logged user information +.IR (utmp) . +Files in this directory are usually cleared when the system boots. +.TP +.I /var/spool +Spooled (or queued) files for various programs. +.TP +.I /var/spool/at +Spooled jobs for +.BR at (1). +.TP +.I /var/spool/cron +Spooled jobs for +.BR cron (8). +.TP +.I /var/spool/lpd +Spooled files for printing (optional). +.TP +.I /var/spool/lpd/printer +Spools for a specific printer (optional). +.TP +.I /var/spool/mail +Replaced by +.IR /var/mail . +.TP +.I /var/spool/mqueue +Queued outgoing mail (optional). +.TP +.I /var/spool/news +Spool directory for news (optional). +.TP +.I /var/spool/rwho +Spooled files for +.BR rwhod (8) +(optional). +.TP +.I /var/spool/smail +Spooled files for the +.BR smail (1) +mail delivery program. +.TP +.I /var/spool/uucp +Spooled files for +.BR uucp (1) +(optional). +.TP +.I /var/tmp +Like +.IR /tmp , +this directory holds temporary files stored for an unspecified duration. +.TP +.I /var/yp +Database files for NIS, +formerly known as the Sun Yellow Pages (YP). +.SH CONFORMING TO +The Filesystem Hierarchy Standard, Version 2.3 +.UR http://www.pathname.com\:/fhs/ +.UE . +.SH BUGS +This list is not exhaustive; different systems may be configured +differently. +.SH SEE ALSO +.BR find (1), +.BR ln (1), +.BR proc (5), +.BR file\-hierarchy (7), +.BR mount (8) +.PP +The Filesystem Hierarchy Standard +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/hostname.7 b/man7/hostname.7 new file mode 100644 index 0000000..186c8f7 --- /dev/null +++ b/man7/hostname.7 @@ -0,0 +1,125 @@ +.\" Copyright (c) 1987, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)hostname.7 8.2 (Berkeley) 12/30/93 +.\" $FreeBSD: src/share/man/man7/hostname.7,v 1.7 2004/07/03 18:29:23 ru Exp $ +.\" +.\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and modified for Linux. +.\" +.TH HOSTNAME 7 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +hostname \- hostname resolution description +.SH DESCRIPTION +Hostnames are domains, where a domain is a hierarchical, dot-separated +list of subdomains; for example, the machine "monet", in the "example" +subdomain of the "com" domain would be represented as "monet.example.com". +.PP +Each element of the hostname must be from 1 to 63 characters long and the +entire hostname, including the dots, can be at most 253 characters long. +Valid characters for hostnames are +.BR ASCII (7) +letters from +.I a +to +.IR z , +the digits from +.I 0 +to +.IR 9 , +and the hyphen (\-). +A hostname may not start with a hyphen. +.PP +Hostnames are often used with network client and server programs, +which must generally translate the name to an address for use. +(This task is generally performed by either +.BR getaddrinfo (3) +or the obsolete +.BR gethostbyname (3).) +Hostnames are resolved by the Internet name resolver in the following +fashion. +.PP +If the name consists of a single component, that is, contains no dot, +and if the environment variable +.B HOSTALIASES +is set to the name of a file, +that file is searched for any string matching the input hostname. +The file should consist of lines made up of two white-space separated strings, +the first of which is the hostname alias, +and the second of which is the complete hostname +to be substituted for that alias. +If a case-insensitive match is found between the hostname to be resolved +and the first field of a line in the file, the substituted name is looked +up with no further processing. +.PP +If the input name ends with a trailing dot, +the trailing dot is removed, +and the remaining name is looked up with no further processing. +.PP +If the input name does not end with a trailing dot, it is looked up +by searching through a list of domains until a match is found. +The default search list includes first the local domain, +then its parent domains with at least 2 name components (longest first). +For example, +in the domain cs.example.com, the name lithium.cchem will be checked first +as lithium.cchem.cs.example and then as lithium.cchem.example.com. +lithium.cchem.com will not be tried, as there is only one component +remaining from the local domain. +The search path can be changed from the default +by a system-wide configuration file (see +.BR resolver (5)). +.SH SEE ALSO +.BR getaddrinfo (3), +.BR gethostbyname (3), +.BR resolver (5), +.BR mailaddr (7), +.BR named (8) +.PP +.UR http://www.ietf.org\:/rfc\:/rfc1123.txt +IETF RFC\ 1123 +.UE +.PP +.UR http://www.ietf.org\:/rfc\:/rfc1178.txt +IETF RFC\ 1178 +.UE +.\" .SH HISTORY +.\" Hostname appeared in +.\" 4.2BSD. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/icmp.7 b/man7/icmp.7 new file mode 100644 index 0000000..224eece --- /dev/null +++ b/man7/icmp.7 @@ -0,0 +1,209 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: icmp.7,v 1.6 2000/08/14 08:03:45 ak Exp $ +.\" +.TH ICMP 7 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +icmp \- Linux IPv4 ICMP kernel module. +.SH DESCRIPTION +This kernel protocol module implements the Internet Control +Message Protocol defined in RFC\ 792. +It is used to signal error conditions and for diagnosis. +The user doesn't interact directly with this module; +instead it communicates with the other protocols in the kernel +and these pass the ICMP errors to the application layers. +The kernel ICMP module also answers ICMP requests. +.PP +A user protocol may receive ICMP packets for all local sockets by opening +a raw socket with the protocol +.BR IPPROTO_ICMP . +See +.BR raw (7) +for more information. +The types of ICMP packets passed to the socket can be filtered using the +.B ICMP_FILTER +socket option. +ICMP packets are always processed by the kernel too, even +when passed to a user socket. +.PP +Linux limits the rate of ICMP error packets to each destination. +.B ICMP_REDIRECT +and +.B ICMP_DEST_UNREACH +are also limited by the destination route of the incoming packets. +.SS /proc interfaces +ICMP supports a set of +.I /proc +interfaces to configure some global IP parameters. +The parameters can be accessed by reading or writing files in the directory +.IR /proc/sys/net/ipv4/ . +Most of these parameters are rate limitations for specific ICMP types. +Linux 2.2 uses a token bucket filter to limit ICMPs. +.\" FIXME . better description needed +The value is the timeout in jiffies until the token bucket filter is +cleared after a burst. +A jiffy is a system dependent unit, usually 10ms on i386 and +about 1ms on alpha and ia64. +.TP +.IR icmp_destunreach_rate " (Linux 2.2 to 2.4.9)" +.\" Precisely: from 2.1.102 +Maximum rate to send ICMP Destination Unreachable packets. +This limits the rate at which packets are sent to any individual +route or destination. +The limit does not affect sending of +.B ICMP_FRAG_NEEDED +packets needed for path MTU discovery. +.TP +.IR icmp_echo_ignore_all " (since Linux 2.2)" +.\" Precisely: 2.1.68 +If this value is nonzero, Linux will ignore all +.B ICMP_ECHO +requests. +.TP +.IR icmp_echo_ignore_broadcasts " (since Linux 2.2)" +.\" Precisely: from 2.1.68 +If this value is nonzero, Linux will ignore all +.B ICMP_ECHO +packets sent to broadcast addresses. +.TP +.IR icmp_echoreply_rate " (Linux 2.2 to 2.4.9)" +.\" Precisely: from 2.1.102 +Maximum rate for sending +.B ICMP_ECHOREPLY +packets in response to +.B ICMP_ECHOREQUEST +packets. +.TP +.IR icmp_errors_use_inbound_ifaddr " (Boolean; default: disabled; since Linux 2.6.12)" +.\" The following taken from 2.6.28-rc4 Documentation/networking/ip-sysctl.txt +If disabled, ICMP error messages are sent with the primary address of +the exiting interface. +.IP +If enabled, the message will be sent with the primary address of +the interface that received the packet that caused the ICMP error. +This is the behavior that many network administrators will expect from +a router. +And it can make debugging complicated network layouts much easier. +.IP +Note that if no primary address exists for the interface selected, +then the primary address of the first non-loopback interface that +has one will be used regardless of this setting. +.TP +.IR icmp_ignore_bogus_error_responses " (Boolean; default: disabled; since Linux 2.2)" +.\" precisely: since 2.1.32 +.\" The following taken from 2.6.28-rc4 Documentation/networking/ip-sysctl.txt +Some routers violate RFC1122 by sending bogus responses to broadcast frames. +Such violations are normally logged via a kernel warning. +If this parameter is enabled, the kernel will not give such warnings, +which will avoid log file clutter. +.TP +.IR icmp_paramprob_rate " (Linux 2.2 to 2.4.9)" +.\" Precisely: from 2.1.102 +Maximum rate for sending +.B ICMP_PARAMETERPROB +packets. +These packets are sent when a packet arrives with an invalid IP header. +.TP +.IR icmp_ratelimit " (integer; default: 1000; since Linux 2.4.10)" +.\" The following taken from 2.6.28-rc4 Documentation/networking/ip-sysctl.txt +Limit the maximum rates for sending ICMP packets whose type matches +.IR icmp_ratemask +(see below) to specific targets. +0 to disable any limiting, +otherwise the minimum space between responses in milliseconds. +.TP +.IR icmp_ratemask " (integer; default: see below; since Linux 2.4.10)" +.\" The following taken from 2.6.28-rc4 Documentation/networking/ip-sysctl.txt +Mask made of ICMP types for which rates are being limited. +.IP +Significant bits: IHGFEDCBA9876543210 +.br +Default mask: 0000001100000011000 (0x1818) +.IP +Bit definitions (see the Linux kernel source file +.IR include/linux/icmp.h ): +.RS 12 +.TS +l l. +0 Echo Reply +3 Destination Unreachable * +4 Source Quench * +5 Redirect +8 Echo Request +B Time Exceeded * +C Parameter Problem * +D Timestamp Request +E Timestamp Reply +F Info Request +G Info Reply +H Address Mask Request +I Address Mask Reply +.TE +.RE +.PP +The bits marked with an asterisk are rate limited by default +(see the default mask above). +.TP +.IR icmp_timeexceed_rate " (Linux 2.2 to 2.4.9)" +Maximum rate for sending +.B ICMP_TIME_EXCEEDED +packets. +These packets are +sent to prevent loops when a packet has crossed too many hops. +.TP +.IR ping_group_range " (two integers; default: see below; since Linux 2.6.39)" +Range of the group IDs (minimum and maximum group IDs, inclusive) +that are allowed to create ICMP Echo sockets. +The default is "1 0", which +means no group is allowed to create ICMP Echo sockets. +.SH VERSIONS +Support for the +.B ICMP_ADDRESS +request was removed in 2.2. +.PP +Support for +.B ICMP_SOURCE_QUENCH +was removed in Linux 2.2. +.SH NOTES +As many other implementations don't support +.B IPPROTO_ICMP +raw sockets, this feature +should not be relied on in portable programs. +.\" not really true ATM +.\" .PP +.\" Linux ICMP should be compliant to RFC 1122. +.PP +.B ICMP_REDIRECT +packets are not sent when Linux is not acting as a router. +They are also accepted only from the old gateway defined in the +routing table and the redirect routes are expired after some time. +.PP +The 64-bit timestamp returned by +.B ICMP_TIMESTAMP +is in milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.PP +Linux ICMP internally uses a raw socket to send ICMPs. +This raw socket may appear in +.BR netstat (8) +output with a zero inode. +.SH SEE ALSO +.BR ip (7), +.BR rdisc (8) +.PP +RFC\ 792 for a description of the ICMP protocol. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/inode.7 b/man7/inode.7 new file mode 100644 index 0000000..d0069ad --- /dev/null +++ b/man7/inode.7 @@ -0,0 +1,472 @@ +'\" t +.\" Copyright (c) 2017 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH INODE 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +inode \- file inode information +.SH DESCRIPTION +Each file has an inode containing metadata about the file. +An application can retrieve this metadata using +.BR stat (2) +(or related calls), which returns a +.I stat +structure, or +.BR statx (2), +which returns a +.I statx +structure. +.PP +The following is a list of the information typically found in, +or associated with, the file inode, +with the names of the corresponding structure fields returned by +.BR stat (2) +and +.BR statx (2): +.TP +Device where inode resides +\fIstat.st_dev\fP; \fIstatx.stx_dev_minor\fP and \fIstatx.stx_dev_major\fP +.IP +Each inode (as well as the associated file) resides in a filesystem +that is hosted on a device. +That device is identified by the combination of its major ID +(which identifies the general class of device) +and minor ID (which identifies a specific instance in the general class). +.TP +Inode number +\fIstat.st_ino\fP; \fIstatx.stx_ino\fP +.IP +Each file in a filesystem has a unique inode number. +Inode numbers are guaranteed to be unique only within a filesystem +(i.e., the same inode numbers may be used by different filesystems, +which is the reason that hard links may not cross filesystem boundaries). +This field contains the file's inode number. +.TP +File type and mode +\fIstat.st_mode\fP; \fIstatx.stx_mode\fP +.IP +See the discussion of file type and mode, below. +.TP +Link count +\fIstat.st_nlink\fP; \fIstatx.stx_nlink\fP +.IP +This field contains the number of hard links to the file. +Additional links to an existing file are created using +.BR link (2). +.TP +User ID +.I st_uid +\fIstat.st_uid\fP; \fIstatx.stx_uid\fP +.IP +This field records the user ID of the owner of the file. +For newly created files, +the file user ID is the effective user ID of the creating process. +The user ID of a file can be changed using +.BR chown (2). +.TP +Group ID +\fIstat.st_gid\fP; \fIstatx.stx_gid\fP +.IP +The inode records the ID of the group owner of the file. +For newly created files, +the file group ID is either the group ID of the parent directory or +the effective group ID of the creating process, +depending on whether or not the set-group-ID bit +is set on the parent directory (see below). +The group ID of a file can be changed using +.BR chown (2). +.TP +Device represented by this inode +\fIstat.st_rdev\fP; \fIstatx.stx_rdev_minor\fP and \fIstatx.stx_rdev_major\fP +.IP +If this file (inode) represents a device, +then the inode records the major and minor ID of that device. +.TP +File size +\fIstat.st_size\fP; \fIstatx.stx_size\fP +.IP +This field gives the size of the file (if it is a regular +file or a symbolic link) in bytes. +The size of a symbolic link is the length of the pathname +it contains, without a terminating null byte. +.TP +Preferred block size for I/O +\fIstat.st_blksize\fP; \fIstatx.stx_blksize\fP +.IP +This field gives the "preferred" blocksize for efficient filesystem I/O. +(Writing to a file in smaller chunks may cause +an inefficient read-modify-rewrite.) +.TP +Number of blocks allocated to the file +\fIstat.st_blocks\fP; \fIstatx.stx_size\fP +.IP +This field indicates the number of blocks allocated to the file, +512-byte units, +(This may be smaller than +.IR st_size /512 +when the file has holes.) +.IP +The POSIX.1 standard notes +.\" Rationale for sys/stat.h in POSIX.1-2008 +that the unit for the +.I st_blocks +member of the +.I stat +structure is not defined by the standard. +On many implementations it is 512 bytes; +on a few systems, a different unit is used, such as 1024. +Furthermore, the unit may differ on a per-filesystem basis. +.TP +Last access timestamp (atime) +\fIstat.st_atime\fP; \fIstatx.stx_atime\fP +.IP +This is the file's last access timestamp. +It is changed by file accesses, for example, by +.BR execve (2), +.BR mknod (2), +.BR pipe (2), +.BR utime (2), +and +.BR read (2) +(of more than zero bytes). +Other interfaces, such as +.BR mmap (2), +may or may not update the atime timestamp +.IP +Some filesystem types allow mounting in such a way that file +and/or directory accesses do not cause an update of the atime timestamp. +(See +.IR noatime , +.IR nodiratime , +and +.I relatime +in +.BR mount (8), +and related information in +.BR mount (2).) +In addition, the atime timestamp +is not updated if a file is opened with the +.BR O_NOATIME +flag; see +.BR open (2). +.TP +File creation (birth) timestamp (btime) +(not returned in the \fIstat\fP structure); \fIstatx.stx_btime\fP +.IP +The file's creation timestamp. +This is set on file creation and not changed subsequently. +.IP +The btime timestamp was not historically present on UNIX systems +and is not currently supported by most Linux filesystems. +.\" FIXME Is it supported on ext4 and XFS? +.TP +Last modification timestamp (mtime) +\fIstat.st_atime\fP; \fIstatx.stx_mtime\fP +.IP +This is the file's last modification timestamp. +It is changed by file modifications, for example, by +.BR mknod (2), +.BR truncate (2), +.BR utime (2), +and +.BR write (2) +(of more than zero bytes). +Moreover, the mtime timestamp +of a directory is changed by the creation or deletion of files +in that directory. +The mtime timestamp is +.I not +changed for changes in owner, group, hard link count, or mode. +.TP +Last status change timestamp (ctime) +\fIstat.st_ctime\fP; \fIstatx.stx_ctime\fP +.IP +This is the file's last status change timestamp. +It is changed by writing or by setting inode information +(i.e., owner, group, link count, mode, etc.). +.PP +Nanosecond timestamps are supported on XFS, JFS, Btrfs, and +ext4 (since Linux 2.6.23). +.\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80 +Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs. +On filesystems that do not support subsecond timestamps, +the nanosecond fields in the +.I stat +and +.I statx +structures are returned with the value 0. +.\" +.SS The file type and mode +The +.I stat.st_mode +field (for +.BR statx (2), +the +.I statx.stx_mode +field) contains the file type and mode. +.PP +POSIX refers to the +.I stat.st_mode +bits corresponding to the mask +.B S_IFMT +(see below) as the +.IR "file type" , +the 12 bits corresponding to the mask 07777 as the +.IR "file mode bits" +and the least significant 9 bits (0777) as the +.IR "file permission bits" . +.PP +The following mask values are defined for the file type: +.in +4n +.TS +lB l l. +S_IFMT 0170000 bit mask for the file type bit field + +S_IFSOCK 0140000 socket +S_IFLNK 0120000 symbolic link +S_IFREG 0100000 regular file +S_IFBLK 0060000 block device +S_IFDIR 0040000 directory +S_IFCHR 0020000 character device +S_IFIFO 0010000 FIFO +.TE +.in +.PP +Thus, to test for a regular file (for example), one could write: +.PP +.in +4n +.EX +stat(pathname, &sb); +if ((sb.st_mode & S_IFMT) == S_IFREG) { + /* Handle regular file */ +} +.EE +.in +.PP +Because tests of the above form are common, additional +macros are defined by POSIX to allow the test of the file type in +.I st_mode +to be written more concisely: +.RS 4 +.TP 1.2i +.BR S_ISREG (m) +is it a regular file? +.TP +.BR S_ISDIR (m) +directory? +.TP +.BR S_ISCHR (m) +character device? +.TP +.BR S_ISBLK (m) +block device? +.TP +.BR S_ISFIFO (m) +FIFO (named pipe)? +.TP +.BR S_ISLNK (m) +symbolic link? (Not in POSIX.1-1996.) +.TP +.BR S_ISSOCK (m) +socket? (Not in POSIX.1-1996.) +.RE +.PP +The preceding code snippet could thus be rewritten as: +.PP +.in +4n +.EX +stat(pathname, &sb); +if (S_ISREG(sb.st_mode)) { + /* Handle regular file */ +} +.EE +.in +.PP +The definitions of most of the above file type test macros +are provided if any of the following feature test macros is defined: +.BR _BSD_SOURCE +(in glibc 2.19 and earlier), +.BR _SVID_SOURCE +(in glibc 2.19 and earlier), +or +.BR _DEFAULT_SOURCE +(in glibc 2.20 and later). +In addition, definitions of all of the above macros except +.BR S_IFSOCK +and +.BR S_ISSOCK () +are provided if +.BR _XOPEN_SOURCE +is defined. +.PP +The definition of +.BR S_IFSOCK +can also be exposed either by defining +.BR _XOPEN_SOURCE +with a value of 500 or greater or (since glibc 2.24) by defining both +.BR _XOPEN_SOURCE +and +.BR _XOPEN_SOURCE_EXTENDED . +.PP +The definition of +.BR S_ISSOCK () +is exposed if any of the following feature test macros is defined: +.BR _BSD_SOURCE +(in glibc 2.19 and earlier), +.BR _DEFAULT_SOURCE +(in glibc 2.20 and later), +.BR _XOPEN_SOURCE +with a value of 500 or greater, +.BR _POSIX_C_SOURCE +with a value of 200112L or greater, or (since glibc 2.24) by defining both +.BR _XOPEN_SOURCE +and +.BR _XOPEN_SOURCE_EXTENDED . +.PP +The following mask values are defined for +the file mode component of the +.I st_mode +field: +.in +4n +.TS +lB l l. +S_ISUID 04000 set-user-ID bit +S_ISGID 02000 set-group-ID bit (see below) +S_ISVTX 01000 sticky bit (see below) + +S_IRWXU 00700 owner has read, write, and execute permission +S_IRUSR 00400 owner has read permission +S_IWUSR 00200 owner has write permission +S_IXUSR 00100 owner has execute permission + +S_IRWXG 00070 group has read, write, and execute permission +S_IRGRP 00040 group has read permission +S_IWGRP 00020 group has write permission +S_IXGRP 00010 group has execute permission + +S_IRWXO 00007 T{ +others (not in group) have read, write, and execute permission +T} +S_IROTH 00004 others have read permission +S_IWOTH 00002 others have write permission +S_IXOTH 00001 others have execute permission +.TE +.in +.PP +The set-group-ID bit +.RB ( S_ISGID ) +has several special uses. +For a directory, it indicates that BSD semantics is to be used +for that directory: files created there inherit their group ID from +the directory, not from the effective group ID of the creating process, +and directories created there will also get the +.B S_ISGID +bit set. +For a file that does not have the group execution bit +.RB ( S_IXGRP ) +set, +the set-group-ID bit indicates mandatory file/record locking. +.PP +The sticky bit +.RB ( S_ISVTX ) +on a directory means that a file +in that directory can be renamed or deleted only by the owner +of the file, by the owner of the directory, and by a privileged +process. +.SH CONFORMING TO +If you need to obtain the definition of the +.IR blkcnt_t +or +.IR blksize_t +types from +.IR , +then define +.BR _XOPEN_SOURCE +with the value 500 or greater (before including +.I any +header files). +.PP +POSIX.1-1990 did not describe the +.BR S_IFMT , +.BR S_IFSOCK , +.BR S_IFLNK , +.BR S_IFREG , +.BR S_IFBLK , +.BR S_IFDIR , +.BR S_IFCHR , +.BR S_IFIFO , +.B S_ISVTX +constants, but instead specified the use of +the macros +.BR S_ISDIR (), +and so on. +The +.BR S_IF* +constants are present in POSIX.1-2001 and later. +.PP +The +.BR S_ISLNK () +and +.BR S_ISSOCK () +macros were not in +POSIX.1-1996, but both are present in POSIX.1-2001; +the former is from SVID 4, the latter from SUSv2. +.PP +UNIX\ V7 (and later systems) had +.BR S_IREAD , +.BR S_IWRITE , +.BR S_IEXEC , +where POSIX +prescribes the synonyms +.BR S_IRUSR , +.BR S_IWUSR , +.BR S_IXUSR . +.SH NOTES +For pseudofiles that are autogenerated by the kernel, the file size +(\fIstat.st_size\fP; \fIstatx.stx_size\fP) +reported by the kernel is not accurate. +For example, the value 0 is returned for many files under the +.I /proc +directory, +while various files under +.IR /sys +report a size of 4096 bytes, even though the file content is smaller. +For such files, one should simply try to read as many bytes as possible +(and append \(aq\e0\(aq to the returned buffer +if it is to be interpreted as a string). +.IR st_atimensec . +.SH SEE ALSO +.BR stat (1), +.BR stat (2), +.BR statx (2), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/inotify.7 b/man7/inotify.7 new file mode 100644 index 0000000..84731b7 --- /dev/null +++ b/man7/inotify.7 @@ -0,0 +1,1104 @@ +'\" t +.\" Copyright (C) 2006, 2014 Michael Kerrisk +.\" Copyright (C) 2014 Heinrich Schuchardt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH INOTIFY 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +inotify \- monitoring filesystem events +.SH DESCRIPTION +The +.I inotify +API provides a mechanism for monitoring filesystem events. +Inotify can be used to monitor individual files, +or to monitor directories. +When a directory is monitored, inotify will return events +for the directory itself, and for files inside the directory. +.PP +The following system calls are used with this API: +.IP * 3 +.BR inotify_init (2) +creates an inotify instance and returns a file descriptor +referring to the inotify instance. +The more recent +.BR inotify_init1 (2) +is like +.BR inotify_init (2), +but has a +.IR flags +argument that provides access to some extra functionality. +.IP * +.BR inotify_add_watch (2) +manipulates the "watch list" associated with an inotify instance. +Each item ("watch") in the watch list specifies the pathname of +a file or directory, +along with some set of events that the kernel should monitor for the +file referred to by that pathname. +.BR inotify_add_watch (2) +either creates a new watch item, or modifies an existing watch. +Each watch has a unique "watch descriptor", an integer +returned by +.BR inotify_add_watch (2) +when the watch is created. +.IP * +When events occur for monitored files and directories, +those events are made available to the application as structured data that +can be read from the inotify file descriptor using +.BR read (2) +(see below). +.IP * +.BR inotify_rm_watch (2) +removes an item from an inotify watch list. +.IP * +When all file descriptors referring to an inotify +instance have been closed (using +.BR close (2)), +the underlying object and its resources are +freed for reuse by the kernel; +all associated watches are automatically freed. +.PP +With careful programming, +an application can use inotify to efficiently monitor and cache +the state of a set of filesystem objects. +However, robust applications should allow for the fact that bugs +in the monitoring logic or races of the kind described below +may leave the cache inconsistent with the filesystem state. +It is probably wise to do some consistency checking, +and rebuild the cache when inconsistencies are detected. +.SS Reading events from an inotify file descriptor +To determine what events have occurred, an application +.BR read (2)s +from the inotify file descriptor. +If no events have so far occurred, then, +assuming a blocking file descriptor, +.BR read (2) +will block until at least one event occurs +(unless interrupted by a signal, +in which case the call fails with the error +.BR EINTR ; +see +.BR signal (7)). +.PP +Each successful +.BR read (2) +returns a buffer containing one or more of the following structures: +.PP +.in +4n +.EX +struct inotify_event { + int wd; /* Watch descriptor */ +.\" FIXME . The type of the 'wd' field should probably be "int32_t". +.\" I submitted a patch to fix this. See the LKML thread +.\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008 +.\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040 + uint32_t mask; /* Mask describing event */ + uint32_t cookie; /* Unique cookie associating related + events (for rename(2)) */ + uint32_t len; /* Size of \fIname\fP field */ + char name[]; /* Optional null-terminated name */ +}; +.EE +.in +.PP +.I wd +identifies the watch for which this event occurs. +It is one of the watch descriptors returned by a previous call to +.BR inotify_add_watch (2). +.PP +.I mask +contains bits that describe the event that occurred (see below). +.PP +.I cookie +is a unique integer that connects related events. +Currently, this is used only for rename events, and +allows the resulting pair of +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +events to be connected by the application. +For all other event types, +.I cookie +is set to 0. +.PP +The +.I name +field is present only when an event is returned +for a file inside a watched directory; +it identifies the filename within to the watched directory. +This filename is null-terminated, +and may include further null bytes (\(aq\\0\(aq) to align subsequent reads to a +suitable address boundary. +.PP +The +.I len +field counts all of the bytes in +.IR name , +including the null bytes; +the length of each +.I inotify_event +structure is thus +.IR "sizeof(struct inotify_event)+len" . +.PP +The behavior when the buffer given to +.BR read (2) +is too small to return information about the next event depends +on the kernel version: in kernels before 2.6.21, +.BR read (2) +returns 0; since kernel 2.6.21, +.BR read (2) +fails with the error +.BR EINVAL . +Specifying a buffer of size +.PP + sizeof(struct inotify_event) + NAME_MAX + 1 +.PP +will be sufficient to read at least one event. +.SS inotify events +The +.BR inotify_add_watch (2) +.I mask +argument and the +.I mask +field of the +.I inotify_event +structure returned when +.BR read (2)ing +an inotify file descriptor are both bit masks identifying +inotify events. +The following bits can be specified in +.I mask +when calling +.BR inotify_add_watch (2) +and may be returned in the +.I mask +field returned by +.BR read (2): +.RS 4 +.TP +.BR IN_ACCESS " (+)" +File was accessed (e.g., +.BR read (2), +.BR execve (2)). +.TP +.BR IN_ATTRIB " (*)" +Metadata changed\(emfor example, permissions (e.g., +.BR chmod (2)), +timestamps (e.g., +.BR utimensat (2)), +extended attributes +.RB ( setxattr (2)), +link count (since Linux 2.6.25; e.g., +.\" FIXME . +.\" Events do not occur for link count changes on a file inside a monitored +.\" directory. This differs from other metadata changes for files inside +.\" a monitored directory. +for the target of +.BR link (2) +and for +.BR unlink (2)), +and user/group ID (e.g., +.BR chown (2)). +.TP +.BR IN_CLOSE_WRITE " (+)" +File opened for writing was closed. +.TP +.BR IN_CLOSE_NOWRITE " (*)" +File or directory not opened for writing was closed. +.TP +.BR IN_CREATE " (+)" +File/directory created in watched directory (e.g., +.BR open (2) +.BR O_CREAT , +.BR mkdir (2), +.BR link (2), +.BR symlink (2), +.BR bind (2) +on a UNIX domain socket). +.TP +.BR IN_DELETE " (+)" +File/directory deleted from watched directory. +.TP +.B IN_DELETE_SELF +Watched file/directory was itself deleted. +(This event also occurs if an object is moved to another filesystem, +since +.BR mv (1) +in effect copies the file to the other filesystem and +then deletes it from the original filesystem.) +In addition, an +.B IN_IGNORED +event will subsequently be generated for the watch descriptor. +.TP +.BR IN_MODIFY " (+)" +File was modified (e.g., +.BR write (2), +.BR truncate (2)). +.TP +.B IN_MOVE_SELF +Watched file/directory was itself moved. +.TP +.BR IN_MOVED_FROM " (+)" +Generated for the directory containing the old filename +when a file is renamed. +.TP +.BR IN_MOVED_TO " (+)" +Generated for the directory containing the new filename +when a file is renamed. +.TP +.BR IN_OPEN " (*)" +File or directory was opened. +.RE +.PP +Inotify monitoring is inode-based: when monitoring a file +(but not when monitoring the directory containing a file), +an event can be generated for activity on any link to the file +(in the same or a different directory). +.PP +When monitoring a directory: +.IP * 3 +the events marked above with an asterisk (*) can occur both +for the directory itself and for objects inside the directory; and +.IP * +the events marked with a plus sign (+) occur only for objects +inside the directory (not for the directory itself). +.PP +.IR Note : +when monitoring a directory, +events are not generated for the files inside the directory +when the events are performed via a pathname (i.e., a link) +that lies outside the monitored directory. +.PP +When events are generated for objects inside a watched directory, the +.I name +field in the returned +.I inotify_event +structure identifies the name of the file within the directory. +.PP +The +.B IN_ALL_EVENTS +macro is defined as a bit mask of all of the above events. +This macro can be used as the +.I mask +argument when calling +.BR inotify_add_watch (2). +.PP +Two additional convenience macros are defined: +.RS 4 +.TP +.BR IN_MOVE +Equates to +.BR "IN_MOVED_FROM | IN_MOVED_TO" . +.TP +.BR IN_CLOSE +Equates to +.BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" . +.RE +.PP +The following further bits can be specified in +.I mask +when calling +.BR inotify_add_watch (2): +.RS 4 +.TP +.BR IN_DONT_FOLLOW " (since Linux 2.6.15)" +Don't dereference +.I pathname +if it is a symbolic link. +.TP +.BR IN_EXCL_UNLINK " (since Linux 2.6.36)" +.\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6 +By default, when watching events on the children of a directory, +events are generated for children even after they have been unlinked +from the directory. +This can result in large numbers of uninteresting events for +some applications (e.g., if watching +.IR /tmp , +in which many applications create temporary files whose +names are immediately unlinked). +Specifying +.B IN_EXCL_UNLINK +changes the default behavior, +so that events are not generated for children after +they have been unlinked from the watched directory. +.TP +.B IN_MASK_ADD +If a watch instance already exists for the filesystem object corresponding to +.IR pathname , +add (OR) the events in +.I mask +to the watch mask (instead of replacing the mask). +.TP +.B IN_ONESHOT +Monitor the filesystem object corresponding to +.I pathname +for one event, then remove from +watch list. +.TP +.BR IN_ONLYDIR " (since Linux 2.6.15)" +Watch +.I pathname +only if it is a directory. +Using this flag provides an application with a race-free way of +ensuring that the monitored object is a directory. +.RE +.PP +The following bits may be set in the +.I mask +field returned by +.BR read (2): +.RS 4 +.TP +.B IN_IGNORED +Watch was removed explicitly +.RB ( inotify_rm_watch (2)) +or automatically (file was deleted, or filesystem was unmounted). +See also BUGS. +.TP +.B IN_ISDIR +Subject of this event is a directory. +.TP +.B IN_Q_OVERFLOW +Event queue overflowed +.RI ( wd +is \-1 for this event). +.TP +.B IN_UNMOUNT +Filesystem containing watched object was unmounted. +In addition, an +.B IN_IGNORED +event will subsequently be generated for the watch descriptor. +.RE +.SS Examples +Suppose an application is watching the directory +.I dir +and the file +.IR dir/myfile +for all events. +The examples below show some events that will be generated +for these two objects. +.RS 4 +.TP +fd = open("dir/myfile", O_RDWR); +Generates +.B IN_OPEN +events for both +.I dir +and +.IR dir/myfile . +.TP +read(fd, buf, count); +Generates +.B IN_ACCESS +events for both +.I dir +and +.IR dir/myfile . +.TP +write(fd, buf, count); +Generates +.B IN_MODIFY +events for both +.I dir +and +.IR dir/myfile . +.TP +fchmod(fd, mode); +Generates +.B IN_ATTRIB +events for both +.I dir +and +.IR dir/myfile . +.TP +close(fd); +Generates +.B IN_CLOSE_WRITE +events for both +.I dir +and +.IR dir/myfile . +.RE +.PP +Suppose an application is watching the directories +.I dir1 +and +.IR dir2 , +and the file +.IR dir1/myfile . +The following examples show some events that may be generated. +.RS 4 +.TP +link("dir1/myfile", "dir2/new"); +Generates an +.B IN_ATTRIB +event for +.IR myfile +and an +.B IN_CREATE +event for +.IR dir2 . +.TP +rename("dir1/myfile", "dir2/myfile"); +Generates an +.B IN_MOVED_FROM +event for +.IR dir1 , +an +.B IN_MOVED_TO +event for +.IR dir2 , +and an +.B IN_MOVE_SELF +event for +.IR myfile . +The +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +events will have the same +.I cookie +value. +.RE +.PP +Suppose that +.IR dir1/xx +and +.IR dir2/yy +are (the only) links to the same file, and an application is watching +.IR dir1 , +.IR dir2 , +.IR dir1/xx , +and +.IR dir2/yy . +Executing the following calls in the order given below will generate +the following events: +.RS 4 +.TP +unlink("dir2/yy"); +Generates an +.BR IN_ATTRIB +event for +.IR xx +(because its link count changes) +and an +.B IN_DELETE +event for +.IR dir2 . +.TP +unlink("dir1/xx"); +Generates +.BR IN_ATTRIB , +.BR IN_DELETE_SELF , +and +.BR IN_IGNORED +events for +.IR xx , +and an +.BR IN_DELETE +event for +.IR dir1 . +.RE +.PP +Suppose an application is watching the directory +.IR dir +and (the empty) directory +.IR dir/subdir . +The following examples show some events that may be generated. +.RS 4 +.TP +mkdir("dir/new", mode); +Generates an +.B "IN_CREATE | IN_ISDIR" +event for +.IR dir . +.TP +rmdir("dir/subdir"); +Generates +.B IN_DELETE_SELF +and +.B IN_IGNORED +events for +.IR subdir , +and an +.B "IN_DELETE | IN_ISDIR" +event for +.IR dir . +.RE +.SS /proc interfaces +The following interfaces can be used to limit the amount of +kernel memory consumed by inotify: +.TP +.I /proc/sys/fs/inotify/max_queued_events +The value in this file is used when an application calls +.BR inotify_init (2) +to set an upper limit on the number of events that can be +queued to the corresponding inotify instance. +Events in excess of this limit are dropped, but an +.B IN_Q_OVERFLOW +event is always generated. +.TP +.I /proc/sys/fs/inotify/max_user_instances +This specifies an upper limit on the number of inotify instances +that can be created per real user ID. +.TP +.I /proc/sys/fs/inotify/max_user_watches +This specifies an upper limit on the number of watches +that can be created per real user ID. +.SH VERSIONS +Inotify was merged into the 2.6.13 Linux kernel. +The required library interfaces were added to glibc in version 2.4. +.RB ( IN_DONT_FOLLOW , +.BR IN_MASK_ADD , +and +.B IN_ONLYDIR +were added in glibc version 2.5.) +.SH CONFORMING TO +The inotify API is Linux-specific. +.SH NOTES +Inotify file descriptors can be monitored using +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +When an event is available, the file descriptor indicates as readable. +.PP +Since Linux 2.6.25, +signal-driven I/O notification is available for inotify file descriptors; +see the discussion of +.B F_SETFL +(for setting the +.B O_ASYNC +flag), +.BR F_SETOWN , +and +.B F_SETSIG +in +.BR fcntl (2). +The +.I siginfo_t +structure (described in +.BR sigaction (2)) +that is passed to the signal handler has the following fields set: +.IR si_fd +is set to the inotify file descriptor number; +.IR si_signo +is set to the signal number; +.IR si_code +is set to +.BR POLL_IN ; +and +.B POLLIN +is set in +.IR si_band . +.PP +If successive output inotify events produced on the +inotify file descriptor are identical (same +.IR wd , +.IR mask , +.IR cookie , +and +.IR name ), +then they are coalesced into a single event if the +older event has not yet been read (but see BUGS). +This reduces the amount of kernel memory required for the event queue, +but also means that an application can't use inotify to reliably count +file events. +.PP +The events returned by reading from an inotify file descriptor +form an ordered queue. +Thus, for example, it is guaranteed that when renaming from +one directory to another, events will be produced in the +correct order on the inotify file descriptor. +.PP +The set of watch descriptors that is being monitored via +an inotify file descriptor can be viewed via the entry for +the inotify file descriptor in the process's +.IR /proc/[pid]/fdinfo +directory. +See +.BR proc (5) +for further details. +The +.B FIONREAD +.BR ioctl (2) +returns the number of bytes available to read from an +inotify file descriptor. +.SS Limitations and caveats +The inotify API provides no information about the user or process that +triggered the inotify event. +In particular, there is no easy +way for a process that is monitoring events via inotify +to distinguish events that it triggers +itself from those that are triggered by other processes. +.PP +Inotify reports only events that a user-space program triggers through +the filesystem API. +As a result, it does not catch remote events that occur +on network filesystems. +(Applications must fall back to polling the filesystem +to catch such events.) +Furthermore, various pseudo-filesystems such as +.IR /proc , +.IR /sys , +and +.IR /dev/pts +are not monitorable with inotify. +.PP +The inotify API does not report file accesses and modifications that +may occur because of +.BR mmap (2), +.BR msync (2), +and +.BR munmap (2). +.PP +The inotify API identifies affected files by filename. +However, by the time an application processes an inotify event, +the filename may already have been deleted or renamed. +.PP +The inotify API identifies events via watch descriptors. +It is the application's responsibility to cache a mapping +(if one is needed) between watch descriptors and pathnames. +Be aware that directory renamings may affect multiple cached pathnames. +.PP +Inotify monitoring of directories is not recursive: +to monitor subdirectories under a directory, +additional watches must be created. +This can take a significant amount time for large directory trees. +.PP +If monitoring an entire directory subtree, +and a new subdirectory is created in that tree or an existing directory +is renamed into that tree, +be aware that by the time you create a watch for the new subdirectory, +new files (and subdirectories) may already exist inside the subdirectory. +Therefore, you may want to scan the contents of the subdirectory +immediately after adding the watch (and, if desired, +recursively add watches for any subdirectories that it contains). +.PP +Note that the event queue can overflow. +In this case, events are lost. +Robust applications should handle the possibility of +lost events gracefully. +For example, it may be necessary to rebuild part or all of +the application cache. +(One simple, but possibly expensive, +approach is to close the inotify file descriptor, empty the cache, +create a new inotify file descriptor, +and then re-create watches and cache entries +for the objects to be monitored.) +.PP +If a filesystem is mounted on top of a monitored directory, +no event is generated, and no events are generated +for objects immediately under the new mount point. +If the filesystem is subsequently unmounted, +events will subsequently be generated for the directory and +the objects it contains. +.\" +.SS Dealing with rename() events +As noted above, the +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +event pair that is generated by +.BR rename (2) +can be matched up via their shared cookie value. +However, the task of matching has some challenges. +.PP +These two events are usually consecutive in the event stream available +when reading from the inotify file descriptor. +However, this is not guaranteed. +If multiple processes are triggering events for monitored objects, +then (on rare occasions) an arbitrary number of +other events may appear between the +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +events. +Furthermore, it is not guaranteed that the event pair is atomically +inserted into the queue: there may be a brief interval where the +.B IN_MOVED_FROM +has appeared, but the +.B IN_MOVED_TO +has not. +.PP +Matching up the +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +event pair generated by +.BR rename (2) +is thus inherently racy. +(Don't forget that if an object is renamed outside of a monitored directory, +there may not even be an +.BR IN_MOVED_TO +event.) +Heuristic approaches (e.g., assume the events are always consecutive) +can be used to ensure a match in most cases, +but will inevitably miss some cases, +causing the application to perceive the +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +events as being unrelated. +If watch descriptors are destroyed and re-created as a result, +then those watch descriptors will be inconsistent with +the watch descriptors in any pending events. +(Re-creating the inotify file descriptor and rebuilding the cache may +be useful to deal with this scenario.) +.PP +Applications should also allow for the possibility that the +.B IN_MOVED_FROM +event was the last event that could fit in the buffer +returned by the current call to +.BR read (2), +and the accompanying +.B IN_MOVED_TO +event might be fetched only on the next +.BR read (2), +which should be done with a (small) timeout to allow for the fact that +insertion of the +.BR IN_MOVED_FROM - IN_MOVED_TO +event pair is not atomic, +and also the possibility that there may not be any +.B IN_MOVED_TO +event. +.SH BUGS +Before Linux 3.19, +.BR fallocate (2) +did not create any inotify events. +Since Linux 3.19, +.\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35 +calls to +.BR fallocate (2) +generate +.B IN_MODIFY +events. +.PP +.\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321 +.\" implies that unmount events were buggy 2.6.11 to 2.6.36 +.\" +In kernels before 2.6.16, the +.B IN_ONESHOT +.I mask +flag does not work. +.PP +As originally designed and implemented, the +.B IN_ONESHOT +flag did not cause an +.B IN_IGNORED +event to be generated when the watch was dropped after one event. +However, as an unintended effect of other changes, +since Linux 2.6.36, an +.B IN_IGNORED +event is generated in this case. +.PP +Before kernel 2.6.25, +.\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2 +the kernel code that was intended to coalesce successive identical events +(i.e., the two most recent events could potentially be coalesced +if the older had not yet been read) +instead checked if the most recent event could be coalesced with the +.I oldest +unread event. +.PP +When a watch descriptor is removed by calling +.BR inotify_rm_watch (2) +(or because a watch file is deleted or the filesystem +that contains it is unmounted), +any pending unread events for that watch descriptor remain available to read. +As watch descriptors are subsequently allocated with +.BR inotify_add_watch (2), +the kernel cycles through the range of possible watch descriptors (0 to +.BR INT_MAX ) +incrementally. +When allocating a free watch descriptor, no check is made to see whether that +watch descriptor number has any pending unread events in the inotify queue. +Thus, it can happen that a watch descriptor is reallocated even +when pending unread events exist for a previous incarnation of +that watch descriptor number, with the result that the application +might then read those events and interpret them as belonging to +the file associated with the newly recycled watch descriptor. +In practice, the likelihood of hitting this bug may be extremely low, +since it requires that an application cycle through +.B INT_MAX +watch descriptors, +release a watch descriptor while leaving unread events for that +watch descriptor in the queue, +and then recycle that watch descriptor. +For this reason, and because there have been no reports +of the bug occurring in real-world applications, +as of Linux 3.15, +.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=77111 +no kernel changes have yet been made to eliminate this possible bug. +.SH EXAMPLE +The following program demonstrates the usage of the inotify API. +It marks the directories passed as a command-line arguments +and waits for events of type +.BR IN_OPEN , +.BR IN_CLOSE_NOWRITE +and +.BR IN_CLOSE_WRITE . +.PP +The following output was recorded while editing the file +.I /home/user/temp/foo +and listing directory +.IR /tmp . +Before the file and the directory were opened, +.B IN_OPEN +events occurred. +After the file was closed, an +.B IN_CLOSE_WRITE +event occurred. +After the directory was closed, an +.B IN_CLOSE_NOWRITE +event occurred. +Execution of the program ended when the user pressed the ENTER key. +.SS Example output +.in +4n +.EX +$ \fB./a.out /tmp /home/user/temp\fP +Press enter key to terminate. +Listening for events. +IN_OPEN: /home/user/temp/foo [file] +IN_CLOSE_WRITE: /home/user/temp/foo [file] +IN_OPEN: /tmp/ [directory] +IN_CLOSE_NOWRITE: /tmp/ [directory] + +Listening for events stopped. +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include + +/* Read all available inotify events from the file descriptor 'fd'. + wd is the table of watch descriptors for the directories in argv. + argc is the length of wd and argv. + argv is the list of watched directories. + Entry 0 of wd and argv is unused. */ + +static void +handle_events(int fd, int *wd, int argc, char* argv[]) +{ + /* Some systems cannot read integer variables if they are not + properly aligned. On other systems, incorrect alignment may + decrease performance. Hence, the buffer used for reading from + the inotify file descriptor should have the same alignment as + struct inotify_event. */ + + char buf[4096] + __attribute__ ((aligned(__alignof__(struct inotify_event)))); + const struct inotify_event *event; + int i; + ssize_t len; + char *ptr; + + /* Loop while events can be read from inotify file descriptor. */ + + for (;;) { + + /* Read some events. */ + + len = read(fd, buf, sizeof buf); + if (len == \-1 && errno != EAGAIN) { + perror("read"); + exit(EXIT_FAILURE); + } + + /* If the nonblocking read() found no events to read, then + it returns \-1 with errno set to EAGAIN. In that case, + we exit the loop. */ + + if (len <= 0) + break; + + /* Loop over all events in the buffer */ + + for (ptr = buf; ptr < buf + len; + ptr += sizeof(struct inotify_event) + event\->len) { + + event = (const struct inotify_event *) ptr; + + /* Print event type */ + + if (event\->mask & IN_OPEN) + printf("IN_OPEN: "); + if (event\->mask & IN_CLOSE_NOWRITE) + printf("IN_CLOSE_NOWRITE: "); + if (event\->mask & IN_CLOSE_WRITE) + printf("IN_CLOSE_WRITE: "); + + /* Print the name of the watched directory */ + + for (i = 1; i < argc; ++i) { + if (wd[i] == event\->wd) { + printf("%s/", argv[i]); + break; + } + } + + /* Print the name of the file */ + + if (event\->len) + printf("%s", event\->name); + + /* Print type of filesystem object */ + + if (event\->mask & IN_ISDIR) + printf(" [directory]\\n"); + else + printf(" [file]\\n"); + } + } +} + +int +main(int argc, char* argv[]) +{ + char buf; + int fd, i, poll_num; + int *wd; + nfds_t nfds; + struct pollfd fds[2]; + + if (argc < 2) { + printf("Usage: %s PATH [PATH ...]\\n", argv[0]); + exit(EXIT_FAILURE); + } + + printf("Press ENTER key to terminate.\\n"); + + /* Create the file descriptor for accessing the inotify API */ + + fd = inotify_init1(IN_NONBLOCK); + if (fd == \-1) { + perror("inotify_init1"); + exit(EXIT_FAILURE); + } + + /* Allocate memory for watch descriptors */ + + wd = calloc(argc, sizeof(int)); + if (wd == NULL) { + perror("calloc"); + exit(EXIT_FAILURE); + } + + /* Mark directories for events + \- file was opened + \- file was closed */ + + for (i = 1; i < argc; i++) { + wd[i] = inotify_add_watch(fd, argv[i], + IN_OPEN | IN_CLOSE); + if (wd[i] == \-1) { + fprintf(stderr, "Cannot watch '%s'\\n", argv[i]); + perror("inotify_add_watch"); + exit(EXIT_FAILURE); + } + } + + /* Prepare for polling */ + + nfds = 2; + + /* Console input */ + + fds[0].fd = STDIN_FILENO; + fds[0].events = POLLIN; + + /* Inotify input */ + + fds[1].fd = fd; + fds[1].events = POLLIN; + + /* Wait for events and/or terminal input */ + + printf("Listening for events.\\n"); + while (1) { + poll_num = poll(fds, nfds, \-1); + if (poll_num == \-1) { + if (errno == EINTR) + continue; + perror("poll"); + exit(EXIT_FAILURE); + } + + if (poll_num > 0) { + + if (fds[0].revents & POLLIN) { + + /* Console input is available. Empty stdin and quit */ + + while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\\n') + continue; + break; + } + + if (fds[1].revents & POLLIN) { + + /* Inotify events are available */ + + handle_events(fd, wd, argc, argv); + } + } + } + + printf("Listening for events stopped.\\n"); + + /* Close inotify file descriptor */ + + close(fd); + + free(wd); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR inotifywait (1), +.BR inotifywatch (1), +.BR inotify_add_watch (2), +.BR inotify_init (2), +.BR inotify_init1 (2), +.BR inotify_rm_watch (2), +.BR read (2), +.BR stat (2), +.BR fanotify (7) +.PP +.IR Documentation/filesystems/inotify.txt +in the Linux kernel source tree +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/intro.7 b/man7/intro.7 new file mode 100644 index 0000000..ce12710 --- /dev/null +++ b/man7/intro.7 @@ -0,0 +1,51 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), Fri Apr 2 11:32:09 MET DST +.\" 1993 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified by Thomas Koenig (ig25@rz.uni-karlsruhe.de) 24 Apr 1993 +.\" Modified Sat Jul 24 17:28:08 1993 by Rik Faith (faith@cs.unc.edu) +.TH INTRO 7 2007-10-23 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- introduction to overview and miscellany section +.SH DESCRIPTION +Section 7 of the manual provides overviews on various topics, and +describes conventions and protocols, +character set standards, the standard filesystem layout, +and miscellaneous other things. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/ip.7 b/man7/ip.7 new file mode 100644 index 0000000..2b42919 --- /dev/null +++ b/man7/ip.7 @@ -0,0 +1,1347 @@ +'\" t +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ +.\" +.\" FIXME The following socket options are yet to be documented +.\" +.\" IP_XFRM_POLICY (2.5.48) +.\" Needs CAP_NET_ADMIN +.\" +.\" IP_IPSEC_POLICY (2.5.47) +.\" Needs CAP_NET_ADMIN +.\" +.\" IP_PASSSEC (2.6.17) +.\" Boolean +.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c +.\" Author: Catherine Zhang +.\" +.\" IP_MINTTL (2.6.34) +.\" commit d218d11133d888f9745802146a50255a4781d37a +.\" Author: Stephen Hemminger +.\" +.\" MCAST_JOIN_GROUP (2.4.22 / 2.6) +.\" +.\" MCAST_BLOCK_SOURCE (2.4.22 / 2.6) +.\" +.\" MCAST_UNBLOCK_SOURCE (2.4.22 / 2.6) +.\" +.\" MCAST_LEAVE_GROUP (2.4.22 / 2.6) +.\" +.\" MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6) +.\" +.\" MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6) +.\" +.\" MCAST_MSFILTER (2.4.22 / 2.6) +.\" +.\" IP_UNICAST_IF (3.4) +.\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71 +.\" Author: Erich E. Hoover +.\" +.TH IP 7 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +ip \- Linux IPv4 protocol implementation +.SH SYNOPSIS +.B #include +.br +.\" .B #include -- does not exist anymore +.\" .B #include -- never include +.B #include +.br +.B #include \fR/* superset of previous */ +.PP +.IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" +.br +.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" +.br +.IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" +.SH DESCRIPTION +Linux implements the Internet Protocol, version 4, +described in RFC\ 791 and RFC\ 1122. +.B ip +contains a level 2 multicasting implementation conforming to RFC\ 1112. +It also contains an IP router including a packet filter. +.PP +The programming interface is BSD-sockets compatible. +For more information on sockets, see +.BR socket (7). +.PP +An IP socket is created using +.BR socket (2): +.PP + socket(AF_INET, socket_type, protocol); +.PP +Valid socket types are +.B SOCK_STREAM +to open a +.BR tcp (7) +socket, +.B SOCK_DGRAM +to open a +.BR udp (7) +socket, or +.B SOCK_RAW +to open a +.BR raw (7) +socket to access the IP protocol directly. +.I protocol +is the IP protocol in the IP header to be received or sent. +The only valid values for +.I protocol +are 0 and +.B IPPROTO_TCP +for TCP sockets, and 0 and +.B IPPROTO_UDP +for UDP sockets. +For +.B SOCK_RAW +you may specify a valid IANA IP protocol defined in +RFC\ 1700 assigned numbers. +.PP +When a process wants to receive new incoming packets or connections, it +should bind a socket to a local interface address using +.BR bind (2). +In this case, only one IP socket may be bound to any given local +(address, port) pair. +When +.B INADDR_ANY +is specified in the bind call, the socket will be bound to +.I all +local interfaces. +When +.BR listen (2) +is called on an unbound socket, the socket is automatically bound +to a random free port with the local address set to +.BR INADDR_ANY . +When +.BR connect (2) +is called on an unbound socket, the socket is automatically bound +to a random free port or to a usable shared port with the local address +set to +.BR INADDR_ANY . +.PP +A TCP local socket address that has been bound is unavailable for +some time after closing, unless the +.B SO_REUSEADDR +flag has been set. +Care should be taken when using this flag as it makes TCP less reliable. +.SS Address format +An IP socket address is defined as a combination of an IP interface +address and a 16-bit port number. +The basic IP protocol does not supply port numbers, they +are implemented by higher level protocols like +.BR udp (7) +and +.BR tcp (7). +On raw sockets +.I sin_port +is set to the IP protocol. +.PP +.in +4n +.EX +struct sockaddr_in { + sa_family_t sin_family; /* address family: AF_INET */ + in_port_t sin_port; /* port in network byte order */ + struct in_addr sin_addr; /* internet address */ +}; + +/* Internet address. */ +struct in_addr { + uint32_t s_addr; /* address in network byte order */ +}; +.EE +.in +.PP +.I sin_family +is always set to +.BR AF_INET . +This is required; in Linux 2.2 most networking functions return +.B EINVAL +when this setting is missing. +.I sin_port +contains the port in network byte order. +The port numbers below 1024 are called +.IR "privileged ports" +(or sometimes: +.IR "reserved ports" ). +Only a privileged process +(on Linux: a process that has the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace) may +.BR bind (2) +to these sockets. +Note that the raw IPv4 protocol as such has no concept of a +port, they are implemented only by higher protocols like +.BR tcp (7) +and +.BR udp (7). +.PP +.I sin_addr +is the IP host address. +The +.I s_addr +member of +.I struct in_addr +contains the host interface address in network byte order. +.I in_addr +should be assigned one of the +.BR INADDR_* +values +(e.g., +.BR INADDR_LOOPBACK ) +using +.BR htonl (3) +or set using the +.BR inet_aton (3), +.BR inet_addr (3), +.BR inet_makeaddr (3) +library functions or directly with the name resolver (see +.BR gethostbyname (3)). +.PP +IPv4 addresses are divided into unicast, broadcast, +and multicast addresses. +Unicast addresses specify a single interface of a host, +broadcast addresses specify all hosts on a network, and multicast +addresses address all hosts in a multicast group. +Datagrams to broadcast addresses can be sent or received only when the +.B SO_BROADCAST +socket flag is set. +In the current implementation, connection-oriented sockets are allowed +to use only unicast addresses. +.\" Leave a loophole for XTP @) +.PP +Note that the address and the port are always stored in +network byte order. +In particular, this means that you need to call +.BR htons (3) +on the number that is assigned to a port. +All address/port manipulation +functions in the standard library work in network byte order. +.PP +There are several special addresses: +.B INADDR_LOOPBACK +(127.0.0.1) +always refers to the local host via the loopback device; +.B INADDR_ANY +(0.0.0.0) +means any address for binding; +.B INADDR_BROADCAST +(255.255.255.255) +means any host and has the same effect on bind as +.B INADDR_ANY +for historical reasons. +.SS Socket options +IP supports some protocol-specific socket options that can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2). +The socket option level for IP is +.BR IPPROTO_IP . +.\" or SOL_IP on Linux +A boolean integer flag is zero when it is false, otherwise true. +.PP +When an invalid socket option is specified, +.BR getsockopt (2) +and +.BR setsockopt (2) +fail with the error +.BR ENOPROTOOPT . +.TP +.BR IP_ADD_MEMBERSHIP " (since Linux 1.2)" +Join a multicast group. +Argument is an +.I ip_mreqn +structure. +.PP +.in +4n +.EX +struct ip_mreqn { + struct in_addr imr_multiaddr; /* IP multicast group + address */ + struct in_addr imr_address; /* IP address of local + interface */ + int imr_ifindex; /* interface index */ +}; +.EE +.in +.PP +.I imr_multiaddr +contains the address of the multicast group the application +wants to join or leave. +It must be a valid multicast address +.\" (i.e., within the 224.0.0.0-239.255.255.255 range) +(or +.BR setsockopt (2) +fails with the error +.BR EINVAL ). +.I imr_address +is the address of the local interface with which the system +should join the multicast group; if it is equal to +.BR INADDR_ANY , +an appropriate interface is chosen by the system. +.I imr_ifindex +is the interface index of the interface that should join/leave the +.I imr_multiaddr +group, or 0 to indicate any interface. +.IP +The +.I ip_mreqn +structure is available only since Linux 2.2. +For compatibility, the old +.I ip_mreq +structure (present since Linux 1.2) is still supported; +it differs from +.I ip_mreqn +only by not including the +.I imr_ifindex +field. +(The kernel determines which structure is being passed based +on the size passed in +.IR optlen .) +.IP +.B IP_ADD_MEMBERSHIP +is valid only for +.BR setsockopt (2). +.\" +.TP +.BR IP_ADD_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / 2.5.68)" +Join a multicast group and allow receiving data only +from a specified source. +Argument is an +.I ip_mreq_source +structure. +.PP +.in +4n +.EX +struct ip_mreq_source { + struct in_addr imr_multiaddr; /* IP multicast group + address */ + struct in_addr imr_interface; /* IP address of local + interface */ + struct in_addr imr_sourceaddr; /* IP address of + multicast source */ +}; +.EE +.in +.PP +The +.I ip_mreq_source +structure is similar to +.I ip_mreqn +described under +.BR IP_ADD_MEMBERSIP . +The +.I imr_multiaddr +field contains the address of the multicast group the application +wants to join or leave. +The +.I imr_interface +field is the address of the local interface with which +the system should join the multicast group. +Finally, the +.I imr_sourceaddr +field contains the address of the source the +application wants to receive data from. +.IP +This option can be used multiple times to allow +receiving data from more than one source. +.TP +.BR IP_BIND_ADDRESS_NO_PORT " (since Linux 4.2)" +.\" commit 90c337da1524863838658078ec34241f45d8394d +Inform the kernel to not reserve an ephemeral port when using +.BR bind (2) +with a port number of 0. +The port will later be automatically chosen at +.BR connect (2) +time, +in a way that allows sharing a source port as long as the 4-tuple is unique. +.TP +.BR IP_BLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)" +Stop receiving multicast data from a specific source in a given group. +This is valid only after the application has subscribed +to the multicast group using either +.BR IP_ADD_MEMBERSHIP +or +.BR IP_ADD_SOURCE_MEMBERSHIP . +.IP +Argument is an +.I ip_mreq_source +structure as described under +.BR IP_ADD_SOURCE_MEMBERSHIP . +.TP +.BR IP_DROP_MEMBERSHIP " (since Linux 1.2)" +Leave a multicast group. +Argument is an +.I ip_mreqn +or +.I ip_mreq +structure similar to +.BR IP_ADD_MEMBERSHIP . +.TP +.BR IP_DROP_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / 2.5.68)" +Leave a source-specific group\(emthat is, stop receiving data from +a given multicast group that come from a given source. +If the application has subscribed to multiple sources within +the same group, data from the remaining sources will still be delivered. +To stop receiving data from all sources at once, use +.BR IP_DROP_MEMBERSHIP . +.IP +Argument is an +.I ip_mreq_source +structure as described under +.BR IP_ADD_SOURCE_MEMBERSHIP . +.TP +.BR IP_FREEBIND " (since Linux 2.4)" +.\" Precisely: 2.4.0-test10 +If enabled, this boolean option allows binding to an IP address +that is nonlocal or does not (yet) exist. +This permits listening on a socket, +without requiring the underlying network interface or the +specified dynamic IP address to be up at the time that +the application is trying to bind to it. +This option is the per-socket equivalent of the +.IR ip_nonlocal_bind +.I /proc +interface described below. +.TP +.BR IP_HDRINCL " (since Linux 2.0)" +If enabled, +the user supplies an IP header in front of the user data. +Valid only for +.B SOCK_RAW +sockets; see +.BR raw (7) +for more information. +When this flag is enabled, the values set by +.BR IP_OPTIONS , +.BR IP_TTL , +and +.B IP_TOS +are ignored. +.TP +.BR IP_MSFILTER " (since Linux 2.4.22 / 2.5.68)" +This option provides access to the advanced full-state filtering API. +Argument is an +.I ip_msfilter +structure. +.PP +.in +4n +.EX +struct ip_msfilter { + struct in_addr imsf_multiaddr; /* IP multicast group + address */ + struct in_addr imsf_interface; /* IP address of local + interface */ + uint32_t imsf_fmode; /* Filter-mode */ + + uint32_t imsf_numsrc; /* Number of sources in + the following array */ + struct in_addr imsf_slist[1]; /* Array of source + addresses */ +}; +.EE +.in +.PP +There are two macros, +.BR MCAST_INCLUDE +and +.BR MCAST_EXCLUDE , +which can be used to specify the filtering mode. +Additionally, the +.BR IP_MSFILTER_SIZE (n) +macro exists to determine how much memory is needed to store +.I ip_msfilter +structure with +.I n +sources in the source list. +.IP +For the full description of multicast source filtering +refer to RFC 3376. +.TP +.BR IP_MTU " (since Linux 2.2)" +.\" Precisely: 2.1.124 +Retrieve the current known path MTU of the current socket. +Returns an integer. +.IP +.B IP_MTU +is valid only for +.BR getsockopt (2) +and can be employed only when the socket has been connected. +.TP +.BR IP_MTU_DISCOVER " (since Linux 2.2)" +.\" Precisely: 2.1.124 +Set or receive the Path MTU Discovery setting for a socket. +When enabled, Linux will perform Path MTU Discovery +as defined in RFC\ 1191 on +.B SOCK_STREAM +sockets. +For +.RB non- SOCK_STREAM +sockets, +.B IP_PMTUDISC_DO +forces the don't-fragment flag to be set on all outgoing packets. +It is the user's responsibility to packetize the data +in MTU-sized chunks and to do the retransmits if necessary. +The kernel will reject (with +.BR EMSGSIZE ) +datagrams that are bigger than the known path MTU. +.B IP_PMTUDISC_WANT +will fragment a datagram if needed according to the path MTU, +or will set the don't-fragment flag otherwise. +.IP +The system-wide default can be toggled between +.B IP_PMTUDISC_WANT +and +.B IP_PMTUDISC_DONT +by writing (respectively, zero and nonzero values) to the +.I /proc/sys/net/ipv4/ip_no_pmtu_disc +file. +.TS +tab(:); +c l +l l. +Path MTU discovery value:Meaning +IP_PMTUDISC_WANT:Use per-route settings. +IP_PMTUDISC_DONT:Never do Path MTU Discovery. +IP_PMTUDISC_DO:Always do Path MTU Discovery. +IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. +.TE +.sp 1 +When PMTU discovery is enabled, the kernel automatically keeps track of +the path MTU per destination host. +When it is connected to a specific peer with +.BR connect (2), +the currently known path MTU can be retrieved conveniently using the +.B IP_MTU +socket option (e.g., after an +.B EMSGSIZE +error occurred). +The path MTU may change over time. +For connectionless sockets with many destinations, +the new MTU for a given destination can also be accessed using the +error queue (see +.BR IP_RECVERR ). +A new error will be queued for every incoming MTU update. +.IP +While MTU discovery is in progress, initial packets from datagram sockets +may be dropped. +Applications using UDP should be aware of this and not +take it into account for their packet retransmit strategy. +.IP +To bootstrap the path MTU discovery process on unconnected sockets, it +is possible to start with a big datagram size +(headers up to 64 kilobytes long) and let it shrink by updates of the path MTU. +.IP +To get an initial estimate of the +path MTU, connect a datagram socket to the destination address using +.BR connect (2) +and retrieve the MTU by calling +.BR getsockopt (2) +with the +.B IP_MTU +option. +.IP +It is possible to implement RFC 4821 MTU probing with +.B SOCK_DGRAM +or +.B SOCK_RAW +sockets by setting a value of +.BR IP_PMTUDISC_PROBE +(available since Linux 2.6.22). +This is also particularly useful for diagnostic tools such as +.BR tracepath (8) +that wish to deliberately send probe packets larger than +the observed Path MTU. +.TP +.BR IP_MULTICAST_ALL " (since Linux 2.6.31)" +This option can be used to modify the delivery policy of multicast messages +to sockets bound to the wildcard +.B INADDR_ANY +address. +The argument is a boolean integer (defaults to 1). +If set to 1, +the socket will receive messages from all the groups that have been joined +globally on the whole system. +Otherwise, it will deliver messages only from +the groups that have been explicitly joined (for example via the +.B IP_ADD_MEMBERSHIP +option) on this particular socket. +.TP +.BR IP_MULTICAST_IF " (since Linux 1.2)" +Set the local device for a multicast socket. +The argument for +.BR setsockopt (2) +is an +.I ip_mreqn +or +.\" net: IP_MULTICAST_IF setsockopt now recognizes struct mreq +.\" Commit: 3a084ddb4bf299a6e898a9a07c89f3917f0713f7 +(since Linux 3.5) +.I ip_mreq +structure similar to +.BR IP_ADD_MEMBERSHIP , +or an +.I in_addr +structure. +(The kernel determines which structure is being passed based +on the size passed in +.IR optlen .) +For +.BR getsockopt (2), +the argument is an +.I in_addr +structure. +.TP +.BR IP_MULTICAST_LOOP " (since Linux 1.2)" +Set or read a boolean integer argument that determines whether +sent multicast packets should be looped back to the local sockets. +.TP +.BR IP_MULTICAST_TTL " (since Linux 1.2)" +Set or read the time-to-live value of outgoing multicast packets for this +socket. +It is very important for multicast packets to set the smallest TTL possible. +The default is 1 which means that multicast packets don't leave the local +network unless the user program explicitly requests it. +Argument is an integer. +.TP +.BR IP_NODEFRAG " (since Linux 2.6.36)" +If enabled (argument is nonzero), +the reassembly of outgoing packets is disabled in the netfilter layer. +The argument is an integer. +.IP +This option is valid only for +.B SOCK_RAW +sockets. +.TP +.BR IP_OPTIONS " (since Linux 2.0)" +.\" Precisely: 1.3.30 +Set or get the IP options to be sent with every packet from this socket. +The arguments are a pointer to a memory buffer containing the options +and the option length. +The +.BR setsockopt (2) +call sets the IP options associated with a socket. +The maximum option size for IPv4 is 40 bytes. +See RFC\ 791 for the allowed options. +When the initial connection request packet for a +.B SOCK_STREAM +socket contains IP options, the IP options will be set automatically +to the options from the initial packet with routing headers reversed. +Incoming packets are not allowed to change options after the connection +is established. +The processing of all incoming source routing options +is disabled by default and can be enabled by using the +.I accept_source_route +.I /proc +interface. +Other options like timestamps are still handled. +For datagram sockets, IP options can be only set by the local user. +Calling +.BR getsockopt (2) +with +.B IP_OPTIONS +puts the current IP options used for sending into the supplied buffer. +.TP +.BR IP_PKTINFO " (since Linux 2.2)" +.\" Precisely: 2.1.68 +Pass an +.B IP_PKTINFO +ancillary message that contains a +.I pktinfo +structure that supplies some information about the incoming packet. +This only works for datagram oriented sockets. +The argument is a flag that tells the socket whether the +.B IP_PKTINFO +message should be passed or not. +The message itself can only be sent/retrieved +as control message with a packet using +.BR recvmsg (2) +or +.BR sendmsg (2). +.IP +.in +4n +.EX +struct in_pktinfo { + unsigned int ipi_ifindex; /* Interface index */ + struct in_addr ipi_spec_dst; /* Local address */ + struct in_addr ipi_addr; /* Header Destination + address */ +}; +.EE +.in +.IP +.I ipi_ifindex +is the unique index of the interface the packet was received on. +.I ipi_spec_dst +is the local address of the packet and +.I ipi_addr +is the destination address in the packet header. +If +.B IP_PKTINFO +is passed to +.BR sendmsg (2) +and +.\" This field is grossly misnamed +.I ipi_spec_dst +is not zero, then it is used as the local source address for the routing +table lookup and for setting up IP source route options. +When +.I ipi_ifindex +is not zero, the primary local address of the interface specified by the +index overwrites +.I ipi_spec_dst +for the routing table lookup. +.TP +.BR IP_RECVERR " (since Linux 2.2)" +.\" Precisely: 2.1.15 +Enable extended reliable error message passing. +When enabled on a datagram socket, all +generated errors will be queued in a per-socket error queue. +When the user receives an error from a socket operation, +the errors can be received by calling +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +The +.I sock_extended_err +structure describing the error will be passed in an ancillary message with +the type +.B IP_RECVERR +and the level +.BR IPPROTO_IP . +.\" or SOL_IP on Linux +This is useful for reliable error handling on unconnected sockets. +The received data portion of the error queue contains the error packet. +.IP +The +.B IP_RECVERR +control message contains a +.I sock_extended_err +structure: +.IP +.in +4n +.EX +#define SO_EE_ORIGIN_NONE 0 +#define SO_EE_ORIGIN_LOCAL 1 +#define SO_EE_ORIGIN_ICMP 2 +#define SO_EE_ORIGIN_ICMP6 3 + +struct sock_extended_err { + uint32_t ee_errno; /* error number */ + uint8_t ee_origin; /* where the error originated */ + uint8_t ee_type; /* type */ + uint8_t ee_code; /* code */ + uint8_t ee_pad; + uint32_t ee_info; /* additional information */ + uint32_t ee_data; /* other data */ + /* More data may follow */ +}; + +struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); +.EE +.in +.IP +.I ee_errno +contains the +.I errno +number of the queued error. +.I ee_origin +is the origin code of where the error originated. +The other fields are protocol-specific. +The macro +.B SO_EE_OFFENDER +returns a pointer to the address of the network object +where the error originated from given a pointer to the ancillary message. +If this address is not known, the +.I sa_family +member of the +.I sockaddr +contains +.B AF_UNSPEC +and the other fields of the +.I sockaddr +are undefined. +.IP +IP uses the +.I sock_extended_err +structure as follows: +.I ee_origin +is set to +.B SO_EE_ORIGIN_ICMP +for errors received as an ICMP packet, or +.B SO_EE_ORIGIN_LOCAL +for locally generated errors. +Unknown values should be ignored. +.I ee_type +and +.I ee_code +are set from the type and code fields of the ICMP header. +.I ee_info +contains the discovered MTU for +.B EMSGSIZE +errors. +The message also contains the +.I sockaddr_in of the node +caused the error, which can be accessed with the +.B SO_EE_OFFENDER +macro. +The +.I sin_family +field of the +.B SO_EE_OFFENDER +address is +.B AF_UNSPEC +when the source was unknown. +When the error originated from the network, all IP options +.RB ( IP_OPTIONS ", " IP_TTL ", " +etc.) enabled on the socket and contained in the +error packet are passed as control messages. +The payload of the packet causing the error is returned as normal payload. +.\" FIXME . Is it a good idea to document that? It is a dubious feature. +.\" On +.\" .B SOCK_STREAM +.\" sockets, +.\" .B IP_RECVERR +.\" has slightly different semantics. Instead of +.\" saving the errors for the next timeout, it passes all incoming +.\" errors immediately to the user. +.\" This might be useful for very short-lived TCP connections which +.\" need fast error handling. Use this option with care: +.\" it makes TCP unreliable +.\" by not allowing it to recover properly from routing +.\" shifts and other normal +.\" conditions and breaks the protocol specification. +Note that TCP has no error queue; +.B MSG_ERRQUEUE +is not permitted on +.B SOCK_STREAM +sockets. +.B IP_RECVERR +is valid for TCP, but all errors are returned by socket function return or +.B SO_ERROR +only. +.IP +For raw sockets, +.B IP_RECVERR +enables passing of all received ICMP errors to the +application, otherwise errors are only reported on connected sockets +.IP +It sets or retrieves an integer boolean flag. +.B IP_RECVERR +defaults to off. +.TP +.BR IP_RECVOPTS " (since Linux 2.2)" +.\" Precisely: 2.1.15 +Pass all incoming IP options to the user in a +.B IP_OPTIONS +control message. +The routing header and other options are already filled in +for the local host. +Not supported for +.B SOCK_STREAM +sockets. +.TP +.BR IP_RECVORIGDSTADDR " (since Linux 2.6.29)" +.\" commit e8b2dfe9b4501ed0047459b2756ba26e5a940a69 +This boolean option enables the +.B IP_ORIGDSTADDR +ancillary message in +.BR recvmsg (2), +in which the kernel returns the original destination address +of the datagram being received. +The ancillary message contains a +.IR "struct sockaddr_in" . +.TP +.BR IP_RECVTOS " (since Linux 2.2)" +.\" Precisely: 2.1.68 +If enabled, the +.B IP_TOS +ancillary message is passed with incoming packets. +It contains a byte which specifies the Type of Service/Precedence +field of the packet header. +Expects a boolean integer flag. +.TP +.BR IP_RECVTTL " (since Linux 2.2)" +.\" Precisely: 2.1.68 +When this flag is set, pass a +.B IP_TTL +control message with the time-to-live +field of the received packet as a byte. +Not supported for +.B SOCK_STREAM +sockets. +.TP +.BR IP_RETOPTS " (since Linux 2.2)" +.\" Precisely: 2.1.15 +Identical to +.BR IP_RECVOPTS , +but returns raw unprocessed options with timestamp and route record +options not filled in for this hop. +.TP +.BR IP_ROUTER_ALERT " (since Linux 2.2)" +.\" Precisely: 2.1.68 +Pass all to-be forwarded packets with the +IP Router Alert option set to this socket. +Valid only for raw sockets. +This is useful, for instance, for user-space RSVP daemons. +The tapped packets are not forwarded by the kernel; it is +the user's responsibility to send them out again. +Socket binding is ignored, +such packets are only filtered by protocol. +Expects an integer flag. +.TP +.BR IP_TOS " (since Linux 1.0)" +Set or receive the Type-Of-Service (TOS) field that is sent +with every IP packet originating from this socket. +It is used to prioritize packets on the network. +TOS is a byte. +There are some standard TOS flags defined: +.B IPTOS_LOWDELAY +to minimize delays for interactive traffic, +.B IPTOS_THROUGHPUT +to optimize throughput, +.B IPTOS_RELIABILITY +to optimize for reliability, +.B IPTOS_MINCOST +should be used for "filler data" where slow transmission doesn't matter. +At most one of these TOS values can be specified. +Other bits are invalid and shall be cleared. +Linux sends +.B IPTOS_LOWDELAY +datagrams first by default, +but the exact behavior depends on the configured queueing discipline. +.\" FIXME elaborate on this +Some high-priority levels may require superuser privileges (the +.B CAP_NET_ADMIN +capability). +.\" The priority can also be set in a protocol-independent way by the +.\" .RB ( SOL_SOCKET ", " SO_PRIORITY ) +.\" socket option (see +.\" .BR socket (7)). +.TP +.BR IP_TRANSPARENT " (since Linux 2.6.24)" +.\" commit f5715aea4564f233767ea1d944b2637a5fd7cd2e +.\" This patch introduces the IP_TRANSPARENT socket option: enabling that +.\" will make the IPv4 routing omit the non-local source address check on +.\" output. Setting IP_TRANSPARENT requires NET_ADMIN capability. +.\" http://lwn.net/Articles/252545/ +Setting this boolean option enables transparent proxying on this socket. +This socket option allows +the calling application to bind to a nonlocal IP address and operate +both as a client and a server with the foreign address as the local endpoint. +NOTE: this requires that routing be set up in a way that +packets going to the foreign address are routed through the TProxy box +(i.e., the system hosting the application that employs the +.B IP_TRANSPARENT +socket option). +Enabling this socket option requires superuser privileges +(the +.BR CAP_NET_ADMIN +capability). +.IP +TProxy redirection with the iptables TPROXY target also requires that +this option be set on the redirected socket. +.TP +.BR IP_TTL " (since Linux 1.0)" +Set or retrieve the current time-to-live field that is used in every packet +sent from this socket. +.TP +.BR IP_UNBLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)" +Unblock previously blocked multicast source. +Returns +.BR EADDRNOTAVAIL +when given source is not being blocked. +.IP +Argument is an +.I ip_mreq_source +structure as described under +.BR IP_ADD_SOURCE_MEMBERSHIP . +.SS /proc interfaces +The IP protocol +supports a set of +.I /proc +interfaces to configure some global parameters. +The parameters can be accessed by reading or writing files in the directory +.IR /proc/sys/net/ipv4/ . +.\" FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented: +.\" ip_queue_maxlen +.\" ip_conntrack_max +Interfaces described as +.I Boolean +take an integer value, with a nonzero value ("true") meaning that +the corresponding option is enabled, and a zero value ("false") +meaning that the option is disabled. +.\" +.TP +.IR ip_always_defrag " (Boolean; since Linux 2.2.13)" +[New with kernel 2.2.13; in earlier kernel versions this feature +was controlled at compile time by the +.B CONFIG_IP_ALWAYS_DEFRAG +option; this option is not present in 2.4.x and later] +.IP +When this boolean flag is enabled (not equal 0), incoming fragments +(parts of IP packets +that arose when some host between origin and destination decided +that the packets were too large and cut them into pieces) will be +reassembled (defragmented) before being processed, even if they are +about to be forwarded. +.IP +Enable only if running either a firewall that is the sole link +to your network or a transparent proxy; never ever use it for a +normal router or host. +Otherwise, fragmented communication can be disturbed +if the fragments travel over different links. +Defragmentation also has a large memory and CPU time cost. +.IP +This is automagically turned on when masquerading or transparent +proxying are configured. +.\" +.TP +.IR ip_autoconfig " (since Linux 2.2 to 2.6.17)" +.\" Precisely: since 2.1.68 +.\" FIXME document ip_autoconfig +Not documented. +.\" +.TP +.IR ip_default_ttl " (integer; default: 64; since Linux 2.2)" +.\" Precisely: 2.1.15 +Set the default time-to-live value of outgoing packets. +This can be changed per socket with the +.B IP_TTL +option. +.\" +.TP +.IR ip_dynaddr " (Boolean; default: disabled; since Linux 2.0.31)" +Enable dynamic socket address and masquerading entry rewriting on interface +address change. +This is useful for dialup interface with changing IP addresses. +0 means no rewriting, 1 turns it on and 2 enables verbose mode. +.\" +.TP +.IR ip_forward " (Boolean; default: disabled; since Linux 1.2)" +Enable IP forwarding with a boolean flag. +IP forwarding can be also set on a per-interface basis. +.\" +.TP +.IR ip_local_port_range " (since Linux 2.2)" +.\" Precisely: since 2.1.68 +This file contains two integers that define the default local port range +allocated to sockets that are not explicitly bound to a port number\(emthat +is, the range used for +.IR "ephemeral ports" . +An ephemeral port is allocated to a socket in the following circumstances: +.RS +.IP * 3 +the port number in a socket address is specified as 0 when calling +.BR bind (2); +.IP * +.BR listen (2) +is called on a stream socket that was not previously bound; +.IP * +.BR connect (2) +was called on a socket that was not previously bound; +.IP * +.BR sendto (2) +is called on a datagram socket that was not previously bound. +.RE +.IP +Allocation of ephemeral ports starts with the first number in +.IR ip_local_port_range +and ends with the second number. +If the range of ephemeral ports is exhausted, +then the relevant system call returns an error (but see BUGS). +.IP +Note that the port range in +.IR ip_local_port_range +should not conflict with the ports used by masquerading +(although the case is handled). +Also, arbitrary choices may cause problems with some firewall packet +filters that make assumptions about the local ports in use. +The first number should be at least greater than 1024, +or better, greater than 4096, to avoid clashes +with well known ports and to minimize firewall problems. +.\" +.TP +.IR ip_no_pmtu_disc " (Boolean; default: disabled; since Linux 2.2)" +.\" Precisely: 2.1.15 +If enabled, don't do Path MTU Discovery for TCP sockets by default. +Path MTU discovery may fail if misconfigured firewalls (that drop +all ICMP packets) or misconfigured interfaces (e.g., a point-to-point +link where the both ends don't agree on the MTU) are on the path. +It is better to fix the broken routers on the path than to turn off +Path MTU Discovery globally, because not doing it incurs a high cost +to the network. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR ip_nonlocal_bind " (Boolean; default: disabled; since Linux 2.4)" +.\" Precisely: patch-2.4.0-test10 +If set, allows processes to +.BR bind (2) +to nonlocal IP addresses, +which can be quite useful, but may break some applications. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR ip6frag_time " (integer; default: 30)" +Time in seconds to keep an IPv6 fragment in memory. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR ip6frag_secret_interval " (integer; default: 600)" +Regeneration interval (in seconds) of the hash secret (or lifetime +for the hash secret) for IPv6 fragments. +.TP +.IR ipfrag_high_thresh " (integer), " ipfrag_low_thresh " (integer)" +If the amount of queued IP fragments reaches +.IR ipfrag_high_thresh , +the queue is pruned down to +.IR ipfrag_low_thresh . +Contains an integer with the number of bytes. +.TP +.I neigh/* +See +.BR arp (7). +.\" FIXME Document the conf/*/* interfaces +.\" +.\" FIXME Document the route/* interfaces +.SS Ioctls +All ioctls described in +.BR socket (7) +apply to +.BR ip . +.\" 2006-04-02, mtk +.\" commented out the following because ipchains is obsolete +.\" .PP +.\" The ioctls to configure firewalling are documented in +.\" .BR ipfw (4) +.\" from the +.\" .B ipchains +.\" package. +.PP +Ioctls to configure generic device parameters are described in +.BR netdevice (7). +.\" FIXME Add a discussion of multicasting +.SH ERRORS +.\" FIXME document all errors. +.\" We should really fix the kernels to give more uniform +.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) +.TP +.B EACCES +The user tried to execute an operation without the necessary permissions. +These include: +sending a packet to a broadcast address without having the +.B SO_BROADCAST +flag set; +sending a packet via a +.I prohibit +route; +modifying firewall settings without superuser privileges (the +.B CAP_NET_ADMIN +capability); +binding to a privileged port without superuser privileges (the +.B CAP_NET_BIND_SERVICE +capability). +.TP +.B EADDRINUSE +Tried to bind to an address already in use. +.TP +.B EADDRNOTAVAIL +A nonexistent interface was requested or the requested source +address was not local. +.TP +.B EAGAIN +Operation on a nonblocking socket would block. +.TP +.B EALREADY +A connection operation on a nonblocking socket is already in progress. +.TP +.B ECONNABORTED +A connection was closed during an +.BR accept (2). +.TP +.B EHOSTUNREACH +No valid routing table entry matches the destination address. +This error can be caused by an ICMP message from a remote router or +for the local routing table. +.TP +.B EINVAL +Invalid argument passed. +For send operations this can be caused by sending to a +.I blackhole +route. +.TP +.B EISCONN +.BR connect (2) +was called on an already connected socket. +.TP +.B EMSGSIZE +Datagram is bigger than an MTU on the path and it cannot be fragmented. +.TP +.BR ENOBUFS ", " ENOMEM +Not enough free memory. +This often means that the memory allocation is limited by the socket +buffer limits, not by the system memory, but this is not 100% consistent. +.TP +.B ENOENT +.B SIOCGSTAMP +was called on a socket where no packet arrived. +.TP +.B ENOPKG +A kernel subsystem was not configured. +.TP +.BR ENOPROTOOPT " and " EOPNOTSUPP +Invalid socket option passed. +.TP +.B ENOTCONN +The operation is defined only on a connected socket, but the socket wasn't +connected. +.TP +.B EPERM +User doesn't have permission to set high priority, change configuration, +or send signals to the requested process or group. +.TP +.B EPIPE +The connection was unexpectedly closed or shut down by the other end. +.TP +.B ESOCKTNOSUPPORT +The socket is not configured or an unknown socket type was requested. +.PP +Other errors may be generated by the overlaying protocols; see +.BR tcp (7), +.BR raw (7), +.BR udp (7), +and +.BR socket (7). +.SH NOTES +.BR IP_FREEBIND , +.BR IP_MSFILTER , +.BR IP_MTU , +.BR IP_MTU_DISCOVER , +.BR IP_RECVORIGDSTADDR , +.BR IP_PKTINFO , +.BR IP_RECVERR , +.BR IP_ROUTER_ALERT , +and +.BR IP_TRANSPARENT +are Linux-specific. +.\" IP_PASSSEC is Linux-specific +.\" IP_XFRM_POLICY is Linux-specific +.\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs +.PP +Be very careful with the +.B SO_BROADCAST +option \- it is not privileged in Linux. +It is easy to overload the network +with careless broadcasts. +For new application protocols +it is better to use a multicast group instead of broadcasting. +Broadcasting is discouraged. +.PP +Some other BSD sockets implementations provide +.B IP_RCVDSTADDR +and +.B IP_RECVIF +socket options to get the destination address and the interface of +received datagrams. +Linux has the more general +.B IP_PKTINFO +for the same task. +.PP +Some BSD sockets implementations also provide an +.B IP_RECVTTL +option, but an ancillary message with type +.B IP_RECVTTL +is passed with the incoming packet. +This is different from the +.B IP_TTL +option used in Linux. +.PP +Using the +.B SOL_IP +socket options level isn't portable; BSD-based stacks use the +.B IPPROTO_IP +level. +.PP +.B INADDR_ANY +(0.0.0.0) and +.B INADDR_BROADCAST +(255.255.255.255) are byte-order-neutral. + This means +.BR htonl (3) +has no effect on them. +.SS Compatibility +For compatibility with Linux 2.0, the obsolete +.BI "socket(AF_INET, SOCK_PACKET, " protocol ) +syntax is still supported to open a +.BR packet (7) +socket. +This is deprecated and should be replaced by +.BI "socket(AF_PACKET, SOCK_RAW, " protocol ) +instead. +The main difference is the new +.I sockaddr_ll +address structure for generic link layer information instead of the old +.BR sockaddr_pkt . +.SH BUGS +There are too many inconsistent error values. +.PP +The error used to diagnose exhaustion of the ephemeral port range differs +across the various system calls +.RB ( connect (2), +.BR bind (2), +.BR listen (2), +.BR sendto (2)) +that can assign ephemeral ports. +.PP +The ioctls to configure IP-specific interface options and ARP tables are +not described. +.\" .PP +.\" Some versions of glibc forget to declare +.\" .IR in_pktinfo . +.\" Workaround currently is to copy it into your program from this man page. +.PP +Receiving the original destination address with +.B MSG_ERRQUEUE +in +.I msg_name +by +.BR recvmsg (2) +does not work in some 2.2 kernels. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR byteorder (3), +.BR ipfw (4), +.BR capabilities (7), +.BR icmp (7), +.BR ipv6 (7), +.BR netlink (7), +.BR raw (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR ip (8) +.PP +RFC\ 791 for the original IP specification. +RFC\ 1122 for the IPv4 host requirements. +RFC\ 1812 for the IPv4 router requirements. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/ipv6.7 b/man7/ipv6.7 new file mode 100644 index 0000000..d582851 --- /dev/null +++ b/man7/ipv6.7 @@ -0,0 +1,432 @@ +.\" This man page is Copyright (C) 2000 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: ipv6.7,v 1.3 2000/12/20 18:10:31 ak Exp $ +.\" +.\" The following socket options are undocumented +.\" All of the following are from: +.\" commit 333fad5364d6b457c8d837f7d05802d2aaf8a961 +.\" Author: YOSHIFUJI Hideaki +.\" Support several new sockopt / ancillary data in Advanced API (RFC3542). +.\" IPV6_2292PKTINFO (2.6.14) +.\" Formerly IPV6_PKTINFO +.\" IPV6_2292HOPOPTS (2.6.14) +.\" Formerly IPV6_HOPOPTS, which is documented +.\" IPV6_2292DSTOPTS (2.6.14) +.\" Formerly IPV6_DSTOPTS, which is documented +.\" IPV6_2292RTHDR (2.6.14) +.\" Formerly IPV6_RTHDR, which is documented +.\" IPV6_2292PKTOPTIONS (2.6.14) +.\" Formerly IPV6_PKTOPTIONS +.\" IPV6_2292HOPLIMIT (2.6.14) +.\" Formerly IPV6_HOPLIMIT, which is documented +.\" +.\" IPV6_RECVHOPLIMIT (2.6.14) +.\" IPV6_RECVHOPOPTS (2.6.14) +.\" IPV6_RTHDRDSTOPTS (2.6.14) +.\" IPV6_RECVRTHDR (2.6.14) +.\" IPV6_RECVDSTOPTS (2.6.14) +.\" +.\" IPV6_RECVPATHMTU (2.6.35, flag value added in 2.6.14) +.\" commit 793b14731686595a741d9f47726ad8b9a235385a +.\" Author: Brian Haley +.\" IPV6_PATHMTU (2.6.35, flag value added in 2.6.14) +.\" commit 793b14731686595a741d9f47726ad8b9a235385a +.\" Author: Brian Haley +.\" IPV6_DONTFRAG (2.6.35, flag value added in 2.6.14) +.\" commit 793b14731686595a741d9f47726ad8b9a235385a +.\" Author: Brian Haley +.\" commit 4b340ae20d0e2366792abe70f46629e576adaf5e +.\" Author: Brian Haley +.\" +.\" IPV6_RECVTCLASS (2.6.14) +.\" commit 41a1f8ea4fbfcdc4232f023732584aae2220de31 +.\" Author: YOSHIFUJI Hideaki +.\" Based on patch from David L Stevens +.\" +.\" IPV6_CHECKSUM (2.2) +.\" IPV6_NEXTHOP (2.2) +.\" IPV6_JOIN_ANYCAST (2.4.21 / 2.6) +.\" IPV6_LEAVE_ANYCAST (2.4.21 / 2.6) +.\" IPV6_FLOWLABEL_MGR (2.2.7 / 2.4) +.\" IPV6_FLOWINFO_SEND (2.2.7 / 2.4) +.\" IPV6_IPSEC_POLICY (2.6) +.\" IPV6_XFRM_POLICY (2.6) +.\" IPV6_TCLASS (2.6) +.\" +.\" IPV6_ADDR_PREFERENCES (2.6.26) +.\" commit 7cbca67c073263c179f605bdbbdc565ab29d801d +.\" Author: YOSHIFUJI Hideaki +.\" IPV6_MINHOPCOUNT (2.6.35) +.\" commit e802af9cabb011f09b9c19a82faef3dd315f27eb +.\" Author: Stephen Hemminger +.\" IPV6_ORIGDSTADDR (2.6.37) +.\" Actually a CMSG rather than a sockopt? +.\" In header file, we have IPV6_RECVORIGDSTADDR == IPV6_ORIGDSTADDR +.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 +.\" Author: Balazs Scheidler +.\" IPV6_RECVORIGDSTADDR (2.6.37) +.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 +.\" Author: Balazs Scheidler +.\" Support for IPV6_RECVORIGDSTADDR sockopt for UDP sockets +.\" were contributed by Harry Mason. +.\" IPV6_TRANSPARENT (2.6.37) +.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 +.\" Author: Balazs Scheidler +.\" IPV6_UNICAST_IF (3.4) +.\" commit c4062dfc425e94290ac427a98d6b4721dd2bc91f +.\" Author: Erich E. Hoover +.\" +.TH IPV6 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ipv6 \- Linux IPv6 protocol implementation +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.IB tcp6_socket " = socket(AF_INET6, SOCK_STREAM, 0);" +.br +.IB raw6_socket " = socket(AF_INET6, SOCK_RAW, " protocol ");" +.br +.IB udp6_socket " = socket(AF_INET6, SOCK_DGRAM, " protocol ");" +.SH DESCRIPTION +Linux 2.2 optionally implements the Internet Protocol, version 6. +This man page contains a description of the IPv6 basic API as +implemented by the Linux kernel and glibc 2.1. +The interface +is based on the BSD sockets interface; see +.BR socket (7). +.PP +The IPv6 API aims to be mostly compatible with the +IPv4 API (see +.BR ip (7)). +Only differences are described in this man page. +.PP +To bind an +.B AF_INET6 +socket to any process, the local address should be copied from the +.I in6addr_any +variable which has +.I in6_addr +type. +In static initializations, +.B IN6ADDR_ANY_INIT +may also be used, which expands to a constant expression. +Both of them are in network byte order. +.PP +The IPv6 loopback address (::1) is available in the global +.I in6addr_loopback +variable. +For initializations, +.B IN6ADDR_LOOPBACK_INIT +should be used. +.PP +IPv4 connections can be handled with the v6 API by using the +v4-mapped-on-v6 address type; +thus a program needs to support only this API type to +support both protocols. +This is handled transparently by the address +handling functions in the C library. +.PP +IPv4 and IPv6 share the local port space. +When you get an IPv4 connection +or packet to an IPv6 socket, its source address will be mapped +to v6 and it will be mapped to v6. +.SS Address format +.in +4n +.EX +struct sockaddr_in6 { + sa_family_t sin6_family; /* AF_INET6 */ + in_port_t sin6_port; /* port number */ + uint32_t sin6_flowinfo; /* IPv6 flow information */ + struct in6_addr sin6_addr; /* IPv6 address */ + uint32_t sin6_scope_id; /* Scope ID (new in 2.4) */ +}; + +struct in6_addr { + unsigned char s6_addr[16]; /* IPv6 address */ +}; +.EE +.in +.PP +.I sin6_family +is always set to +.BR AF_INET6 ; +.I sin6_port +is the protocol port (see +.I sin_port +in +.BR ip (7)); +.I sin6_flowinfo +is the IPv6 flow identifier; +.I sin6_addr +is the 128-bit IPv6 address. +.I sin6_scope_id +is an ID depending on the scope of the address. +It is new in Linux 2.4. +Linux supports it only for link-local addresses, in that case +.I sin6_scope_id +contains the interface index (see +.BR netdevice (7)) +.PP +IPv6 supports several address types: unicast to address a single +host, multicast to address a group of hosts, +anycast to address the nearest member of a group of hosts +(not implemented in Linux), IPv4-on-IPv6 to +address an IPv4 host, and other reserved address types. +.PP +The address notation for IPv6 is a group of 8 4-digit hexadecimal +numbers, separated with a \(aq:\(aq. +\&"::" stands for a string of 0 bits. +Special addresses are ::1 for loopback and ::FFFF: +for IPv4-mapped-on-IPv6. +.PP +The port space of IPv6 is shared with IPv4. +.SS Socket options +IPv6 supports some protocol-specific socket options that can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2). +The socket option level for IPv6 is +.BR IPPROTO_IPV6 . +A boolean integer flag is zero when it is false, otherwise true. +.TP +.B IPV6_ADDRFORM +Turn an +.B AF_INET6 +socket into a socket of a different address family. +Only +.B AF_INET +is currently supported for that. +It is allowed only for IPv6 sockets +that are connected and bound to a v4-mapped-on-v6 address. +The argument is a pointer to an integer containing +.BR AF_INET . +This is useful to pass v4-mapped sockets as file descriptors to +programs that don't know how to deal with the IPv6 API. +.TP +.B IPV6_ADD_MEMBERSHIP, IPV6_DROP_MEMBERSHIP +Control membership in multicast groups. +Argument is a pointer to a +.IR "struct ipv6_mreq" . +.TP +.B IPV6_MTU +.BR getsockopt (): +Retrieve the current known path MTU of the current socket. +Valid only when the socket has been connected. +Returns an integer. +.IP +.BR setsockopt (): +Set the MTU to be used for the socket. +The MTU is limited by the device +MTU or the path MTU when path MTU discovery is enabled. +Argument is a pointer to integer. +.TP +.B IPV6_MTU_DISCOVER +Control path-MTU discovery on the socket. +See +.B IP_MTU_DISCOVER +in +.BR ip (7) +for details. +.TP +.B IPV6_MULTICAST_HOPS +Set the multicast hop limit for the socket. +Argument is a pointer to an +integer. +\-1 in the value means use the route default, otherwise it should be +between 0 and 255. +.TP +.B IPV6_MULTICAST_IF +Set the device for outgoing multicast packets on the socket. +This is allowed only for +.B SOCK_DGRAM +and +.B SOCK_RAW +socket. +The argument is a pointer to an interface index (see +.BR netdevice (7)) +in an integer. +.TP +.B IPV6_MULTICAST_LOOP +Control whether the socket sees multicast packets that it has send itself. +Argument is a pointer to boolean. +.TP +.BR IPV6_RECVPKTINFO " (since Linux 2.6.14)" +Set delivery of the +.B IPV6_PKTINFO +control message on incoming datagrams. +Such control messages contain a +.IR "struct in6_pktinfo" , +as per RFC 3542. +Allowed only for +.B SOCK_DGRAM +or +.B SOCK_RAW +sockets. +Argument is a pointer to a boolean value in an integer. +.TP +.nh +.B IPV6_RTHDR, IPV6_AUTHHDR, IPV6_DSTOPTS, IPV6_HOPOPTS, IPV6_FLOWINFO, IPV6_HOPLIMIT +.hy +Set delivery of control messages for incoming datagrams containing +extension headers from the received packet. +.B IPV6_RTHDR +delivers the routing header, +.B IPV6_AUTHHDR +delivers the authentication header, +.B IPV6_DSTOPTS +delivers the destination options, +.B IPV6_HOPOPTS +delivers the hop options, +.B IPV6_FLOWINFO +delivers an integer containing the flow ID, +.B IPV6_HOPLIMIT +delivers an integer containing the hop count of the packet. +The control messages have the same type as the socket option. +All these header options can also be set for outgoing packets +by putting the appropriate control message into the control buffer of +.BR sendmsg (2). +Allowed only for +.B SOCK_DGRAM +or +.B SOCK_RAW +sockets. +Argument is a pointer to a boolean value. +.TP +.B IPV6_RECVERR +Control receiving of asynchronous error options. +See +.B IP_RECVERR +in +.BR ip (7) +for details. +Argument is a pointer to boolean. +.TP +.B IPV6_ROUTER_ALERT +Pass forwarded packets containing a router alert hop-by-hop option to +this socket. +Allowed only for +.B SOCK_RAW +sockets. +The tapped packets are not forwarded by the kernel, it is the +user's responsibility to send them out again. +Argument is a pointer to an integer. +A positive integer indicates a router alert option value to intercept. +Packets carrying a router alert option with a value field containing +this integer will be delivered to the socket. +A negative integer disables delivery of packets with router alert options +to this socket. +.TP +.B IPV6_UNICAST_HOPS +Set the unicast hop limit for the socket. +Argument is a pointer to an integer. +\-1 in the value means use the route default, +otherwise it should be between 0 and 255. +.TP +.BR IPV6_V6ONLY " (since Linux 2.4.21 and 2.6)" +.\" See RFC 3493 +If this flag is set to true (nonzero), then the socket is restricted +to sending and receiving IPv6 packets only. +In this case, an IPv4 and an IPv6 application can bind +to a single port at the same time. +.IP +If this flag is set to false (zero), +then the socket can be used to send and receive packets +to and from an IPv6 address or an IPv4-mapped IPv6 address. +.IP +The argument is a pointer to a boolean value in an integer. +.IP +The default value for this flag is defined by the contents of the file +.IR /proc/sys/net/ipv6/bindv6only . +The default value for that file is 0 (false). +.\" FLOWLABEL_MGR, FLOWINFO_SEND +.SH ERRORS +.TP +.B ENODEV +The user tried to +.BR bind (2) +to a link-local IPv6 address, but the +.I sin6_scope_id +in the supplied +.I sockaddr_in6 +structure is not a valid +interface index. +.SH VERSIONS +Linux 2.4 will break binary compatibility for the +.I sockaddr_in6 +for 64-bit +hosts by changing the alignment of +.I in6_addr +and adding an additional +.I sin6_scope_id +field. +The kernel interfaces stay compatible, but a program including +.I sockaddr_in6 +or +.I in6_addr +into other structures may not be. +This is not +a problem for 32-bit hosts like i386. +.PP +The +.I sin6_flowinfo +field is new in Linux 2.4. +It is transparently passed/read by the kernel +when the passed address length contains it. +Some programs that pass a longer address buffer and then +check the outgoing address length may break. +.SH NOTES +The +.I sockaddr_in6 +structure is bigger than the generic +.IR sockaddr . +Programs that assume that all address types can be stored safely in a +.I struct sockaddr +need to be changed to use +.I struct sockaddr_storage +for that instead. +.PP +.BR SOL_IP , +.BR SOL_IPV6 , +.B SOL_ICMPV6 +and other +.BR SOL_ * +socket options are nonportable variants of +.BR IPPROTO_ *. +See also +.BR ip (7). +.SH BUGS +The IPv6 extended API as in RFC\ 2292 is currently only partly +implemented; +although the 2.2 kernel has near complete support for receiving options, +the macros for generating IPv6 options are missing in glibc 2.1. +.PP +IPSec support for EH and AH headers is missing. +.PP +Flow label management is not complete and not documented here. +.PP +This man page is not complete. +.SH SEE ALSO +.BR cmsg (3), +.BR ip (7) +.PP +RFC\ 2553: IPv6 BASIC API; +Linux tries to be compliant to this. +RFC\ 2460: IPv6 specification. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso-8859-1.7 b/man7/iso-8859-1.7 new file mode 100644 index 0000000..1969dfb --- /dev/null +++ b/man7/iso-8859-1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man7/iso-8859-10.7 b/man7/iso-8859-10.7 new file mode 100644 index 0000000..9b4658f --- /dev/null +++ b/man7/iso-8859-10.7 @@ -0,0 +1 @@ +.so man7/iso_8859-10.7 diff --git a/man7/iso-8859-11.7 b/man7/iso-8859-11.7 new file mode 100644 index 0000000..cbd4cfe --- /dev/null +++ b/man7/iso-8859-11.7 @@ -0,0 +1 @@ +.so man7/iso_8859-11.7 diff --git a/man7/iso-8859-13.7 b/man7/iso-8859-13.7 new file mode 100644 index 0000000..8ad2335 --- /dev/null +++ b/man7/iso-8859-13.7 @@ -0,0 +1 @@ +.so man7/iso_8859-13.7 diff --git a/man7/iso-8859-14.7 b/man7/iso-8859-14.7 new file mode 100644 index 0000000..4aa555d --- /dev/null +++ b/man7/iso-8859-14.7 @@ -0,0 +1 @@ +.so man7/iso_8859-14.7 diff --git a/man7/iso-8859-15.7 b/man7/iso-8859-15.7 new file mode 100644 index 0000000..a4095d7 --- /dev/null +++ b/man7/iso-8859-15.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man7/iso-8859-16.7 b/man7/iso-8859-16.7 new file mode 100644 index 0000000..b9c8e91 --- /dev/null +++ b/man7/iso-8859-16.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man7/iso-8859-2.7 b/man7/iso-8859-2.7 new file mode 100644 index 0000000..da36668 --- /dev/null +++ b/man7/iso-8859-2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man7/iso-8859-3.7 b/man7/iso-8859-3.7 new file mode 100644 index 0000000..75e42ce --- /dev/null +++ b/man7/iso-8859-3.7 @@ -0,0 +1 @@ +.so man7/iso_8859-3.7 diff --git a/man7/iso-8859-4.7 b/man7/iso-8859-4.7 new file mode 100644 index 0000000..15a829e --- /dev/null +++ b/man7/iso-8859-4.7 @@ -0,0 +1 @@ +.so man7/iso_8859-4.7 diff --git a/man7/iso-8859-5.7 b/man7/iso-8859-5.7 new file mode 100644 index 0000000..1f20320 --- /dev/null +++ b/man7/iso-8859-5.7 @@ -0,0 +1 @@ +.so man7/iso_8859-5.7 diff --git a/man7/iso-8859-6.7 b/man7/iso-8859-6.7 new file mode 100644 index 0000000..edcafdf --- /dev/null +++ b/man7/iso-8859-6.7 @@ -0,0 +1 @@ +.so man7/iso_8859-6.7 diff --git a/man7/iso-8859-7.7 b/man7/iso-8859-7.7 new file mode 100644 index 0000000..951384c --- /dev/null +++ b/man7/iso-8859-7.7 @@ -0,0 +1 @@ +.so man7/iso_8859-7.7 diff --git a/man7/iso-8859-8.7 b/man7/iso-8859-8.7 new file mode 100644 index 0000000..07cf216 --- /dev/null +++ b/man7/iso-8859-8.7 @@ -0,0 +1 @@ +.so man7/iso_8859-8.7 diff --git a/man7/iso-8859-9.7 b/man7/iso-8859-9.7 new file mode 100644 index 0000000..0fcc7d4 --- /dev/null +++ b/man7/iso-8859-9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man7/iso_8859-1.7 b/man7/iso_8859-1.7 new file mode 100644 index 0000000..e1d3e61 --- /dev/null +++ b/man7/iso_8859-1.7 @@ -0,0 +1,178 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Slightly rearranged, aeb, 950713 +.\" Updated, dpo, 990531 +.TH ISO_8859-1 7 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-1 \- ISO 8859-1 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-1 encodes the +characters used in many West European languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-1 characters +The following table displays the characters in ISO 8859-1 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO 8859-1 is also known as Latin-1. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1252 (7), +.BR iso_8859-15 (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-10.7 b/man7/iso_8859-10.7 new file mode 100644 index 0000000..a576eec --- /dev/null +++ b/man7/iso_8859-10.7 @@ -0,0 +1,174 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-10 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-10 \- ISO 8859-10 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-10 encodes the +characters used in Nordic languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-10 characters +The following table displays the characters in ISO 8859-10 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ą LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 Ē LATIN CAPITAL LETTER E WITH MACRON +243 163 A3 Ģ LATIN CAPITAL LETTER G WITH CEDILLA +244 164 A4 Ī LATIN CAPITAL LETTER I WITH MACRON +245 165 A5 Ĩ LATIN CAPITAL LETTER I WITH TILDE +246 166 A6 Ķ LATIN CAPITAL LETTER K WITH CEDILLA +247 167 A7 § SECTION SIGN +250 168 A8 Ļ LATIN CAPITAL LETTER L WITH CEDILLA +251 169 A9 Đ LATIN CAPITAL LETTER D WITH STROKE +252 170 AA Š LATIN CAPITAL LETTER S WITH CARON +253 171 AB Ŧ LATIN CAPITAL LETTER T WITH STROKE +254 172 AC Ž LATIN CAPITAL LETTER Z WITH CARON +255 173 AD ­ SOFT HYPHEN +256 174 AE Ū LATIN CAPITAL LETTER U WITH MACRON +257 175 AF Ŋ LATIN CAPITAL LETTER ENG +260 176 B0 ° DEGREE SIGN +261 177 B1 ą LATIN SMALL LETTER A WITH OGONEK +262 178 B2 ē LATIN SMALL LETTER E WITH MACRON +263 179 B3 ģ LATIN SMALL LETTER G WITH CEDILLA +264 180 B4 ī LATIN SMALL LETTER I WITH MACRON +265 181 B5 ĩ LATIN SMALL LETTER I WITH TILDE +266 182 B6 ķ LATIN SMALL LETTER K WITH CEDILLA +267 183 B7 · MIDDLE DOT +270 184 B8 ļ LATIN SMALL LETTER L WITH CEDILLA +271 185 B9 đ LATIN SMALL LETTER D WITH STROKE +272 186 BA š LATIN SMALL LETTER S WITH CARON +273 187 BB ŧ LATIN SMALL LETTER T WITH STROKE +274 188 BC ž LATIN SMALL LETTER Z WITH CARON +275 189 BD ― HORIZONTAL BAR +276 190 BE ū LATIN SMALL LETTER U WITH MACRON +277 191 BF ŋ LATIN SMALL LETTER ENG +300 192 C0 Ā LATIN CAPITAL LETTER A WITH MACRON +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Į LATIN CAPITAL LETTER I WITH OGONEK +310 200 C8 Č LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ę LATIN CAPITAL LETTER E WITH OGONEK +312 202 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ė LATIN CAPITAL LETTER E WITH DOT ABOVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ņ LATIN CAPITAL LETTER N WITH CEDILLA +322 210 D2 Ō LATIN CAPITAL LETTER O WITH MACRON +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 Ũ LATIN CAPITAL LETTER U WITH TILDE +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ų LATIN CAPITAL LETTER U WITH OGONEK +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 ā LATIN SMALL LETTER A WITH MACRON +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 į LATIN SMALL LETTER I WITH OGONEK +350 232 E8 č LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ę LATIN SMALL LETTER E WITH OGONEK +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ė LATIN SMALL LETTER E WITH DOT ABOVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ņ LATIN SMALL LETTER N WITH CEDILLA +362 242 F2 ō LATIN SMALL LETTER O WITH MACRON +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ũ LATIN SMALL LETTER U WITH TILDE +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ų LATIN SMALL LETTER U WITH OGONEK +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ĸ LATIN SMALL LETTER KRA +.TE +.SH NOTES +ISO 8859-10 is also known as Latin-6. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-11.7 b/man7/iso_8859-11.7 new file mode 100644 index 0000000..aba4044 --- /dev/null +++ b/man7/iso_8859-11.7 @@ -0,0 +1,171 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\"Thanomsub Noppaburana made valuable suggestions. +.\" +.TH ISO_8859-11 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-11 \- ISO 8859-11 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-11 encodes the +characters used in the Thai language. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-11 characters +The following table displays the characters in ISO 8859-11 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ก THAI CHARACTER KO KAI +242 162 A2 ข THAI CHARACTER KHO KHAI +243 163 A3 ฃ THAI CHARACTER KHO KHUAT +244 164 A4 ค THAI CHARACTER KHO KHWAI +245 165 A5 ฅ THAI CHARACTER KHO KHON +246 166 A6 ฆ THAI CHARACTER KHO RAKHANG +247 167 A7 ง THAI CHARACTER NGO NGU +250 168 A8 จ THAI CHARACTER CHO CHAN +251 169 A9 ฉ THAI CHARACTER CHO CHING +252 170 AA ช THAI CHARACTER CHO CHANG +253 171 AB ซ THAI CHARACTER SO SO +254 172 AC ฌ THAI CHARACTER CHO CHOE +255 173 AD ญ THAI CHARACTER YO YING +256 174 AE ฎ THAI CHARACTER DO CHADA +257 175 AF ฏ THAI CHARACTER TO PATAK +260 176 B0 ฐ THAI CHARACTER THO THAN +261 177 B1 ฑ THAI CHARACTER THO NANGMONTHO +262 178 B2 ฒ THAI CHARACTER THO PHUTHAO +263 179 B3 ณ THAI CHARACTER NO NEN +264 180 B4 ด THAI CHARACTER DO DEK +265 181 B5 ต THAI CHARACTER TO TAO +266 182 B6 ถ THAI CHARACTER THO THUNG +267 183 B7 ท THAI CHARACTER THO THAHAN +270 184 B8 ธ THAI CHARACTER THO THONG +271 185 B9 น THAI CHARACTER NO NU +272 186 BA บ THAI CHARACTER BO BAIMAI +273 187 BB ป THAI CHARACTER PO PLA +274 188 BC ผ THAI CHARACTER PHO PHUNG +275 189 BD ฝ THAI CHARACTER FO FA +276 190 BE พ THAI CHARACTER PHO PHAN +277 191 BF ฟ THAI CHARACTER FO FAN +300 192 C0 ภ THAI CHARACTER PHO SAMPHAO +301 193 C1 ม THAI CHARACTER MO MA +302 194 C2 ย THAI CHARACTER YO YAK +303 195 C3 ร THAI CHARACTER RO RUA +304 196 C4 ฤ THAI CHARACTER RU +305 197 C5 ล THAI CHARACTER LO LING +306 198 C6 ฦ THAI CHARACTER LU +307 199 C7 ว THAI CHARACTER WO WAEN +310 200 C8 ศ THAI CHARACTER SO SALA +311 201 C9 ษ THAI CHARACTER SO RUSI +312 202 CA ส THAI CHARACTER SO SUA +313 203 CB ห THAI CHARACTER HO HIP +314 204 CC ฬ THAI CHARACTER LO CHULA +315 205 CD อ THAI CHARACTER O ANG +316 206 CE ฮ THAI CHARACTER HO NOKHUK +317 207 CF ฯ THAI CHARACTER PAIYANNOI +320 208 D0 ะ THAI CHARACTER SARA A +321 209 D1 ั THAI CHARACTER MAI HAN-AKAT +322 210 D2 า THAI CHARACTER SARA AA +323 211 D3 ำ THAI CHARACTER SARA AM +324 212 D4 ิ THAI CHARACTER SARA I +325 213 D5 ี THAI CHARACTER SARA II +326 214 D6 ึ THAI CHARACTER SARA UE +327 215 D7 ื THAI CHARACTER SARA UEE +330 216 D8 ุ THAI CHARACTER SARA U +331 217 D9 ู THAI CHARACTER SARA UU +332 218 DA ฺ THAI CHARACTER PHINTHU +337 223 DF ฿ THAI CURRENCY SYMBOL BAHT +340 224 E0 เ THAI CHARACTER SARA E +341 225 E1 แ THAI CHARACTER SARA AE +342 226 E2 โ THAI CHARACTER SARA O +343 227 E3 ใ THAI CHARACTER SARA AI MAIMUAN +344 228 E4 ไ THAI CHARACTER SARA AI MAIMALAI +345 229 E5 ๅ THAI CHARACTER LAKKHANGYAO +346 230 E6 ๆ THAI CHARACTER MAIYAMOK +347 231 E7 ็ THAI CHARACTER MAITAIKHU +350 232 E8 ่ THAI CHARACTER MAI EK +351 233 E9 ้ THAI CHARACTER MAI THO +352 234 EA ๊ THAI CHARACTER MAI TRI +353 235 EB ๋ THAI CHARACTER MAI CHATTAWA +354 236 EC ์ THAI CHARACTER THANTHAKHAT +355 237 ED ํ THAI CHARACTER NIKHAHIT +356 238 EE ๎ THAI CHARACTER YAMAKKAN +357 239 EF ๏ THAI CHARACTER FONGMAN +360 240 F0 ๐ THAI DIGIT ZERO +361 241 F1 ๑ THAI DIGIT ONE +362 242 F2 ๒ THAI DIGIT TWO +363 243 F3 ๓ THAI DIGIT THREE +364 244 F4 ๔ THAI DIGIT FOUR +365 245 F5 ๕ THAI DIGIT FIVE +366 246 F6 ๖ THAI DIGIT SIX +367 247 F7 ๗ THAI DIGIT SEVEN +370 248 F8 ๘ THAI DIGIT EIGHT +371 249 F9 ๙ THAI DIGIT NINE +372 250 FA ๚ THAI CHARACTER ANGKHANKHU +373 251 FB ๛ THAI CHARACTER KHOMUT +.TE +.SH NOTES +ISO 8859-11 is the same as TIS (Thai Industrial Standard) 620-2253, +commonly known as TIS-620, except for the character in position A0: +ISO 8859-11 defines this as NO-BREAK SPACE, +while TIS-620 leaves it undefined. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-13.7 b/man7/iso_8859-13.7 new file mode 100644 index 0000000..4be0d34 --- /dev/null +++ b/man7/iso_8859-13.7 @@ -0,0 +1,174 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-13 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-13 \- ISO 8859-13 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-13 encodes the +characters used in Baltic Rim languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-13 characters +The following table displays the characters in ISO 8859-13 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ” RIGHT DOUBLE QUOTATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 „ DOUBLE LOW-9 QUOTATION MARK +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 Ø LATIN CAPITAL LETTER O WITH STROKE +251 169 A9 © COPYRIGHT SIGN +252 170 AA Ŗ LATIN CAPITAL LETTER R WITH CEDILLA +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF Æ LATIN CAPITAL LETTER AE +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 “ LEFT DOUBLE QUOTATION MARK +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ø LATIN SMALL LETTER O WITH STROKE +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA ŗ LATIN SMALL LETTER R WITH CEDILLA +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF æ LATIN SMALL LETTER AE +300 192 C0 Ą LATIN CAPITAL LETTER A WITH OGONEK +301 193 C1 Į LATIN CAPITAL LETTER I WITH OGONEK +302 194 C2 Ā LATIN CAPITAL LETTER A WITH MACRON +303 195 C3 Ć LATIN CAPITAL LETTER C WITH ACUTE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Ę LATIN CAPITAL LETTER E WITH OGONEK +307 199 C7 Ē LATIN CAPITAL LETTER E WITH MACRON +310 200 C8 Č LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ź LATIN CAPITAL LETTER Z WITH ACUTE +313 203 CB Ė LATIN CAPITAL LETTER E WITH DOT ABOVE +314 204 CC Ģ LATIN CAPITAL LETTER G WITH CEDILLA +315 205 CD Ķ LATIN CAPITAL LETTER K WITH CEDILLA +316 206 CE Ī LATIN CAPITAL LETTER I WITH MACRON +317 207 CF Ļ LATIN CAPITAL LETTER L WITH CEDILLA +320 208 D0 Š LATIN CAPITAL LETTER S WITH CARON +321 209 D1 Ń LATIN CAPITAL LETTER N WITH ACUTE +322 210 D2 Ņ LATIN CAPITAL LETTER N WITH CEDILLA +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ō LATIN CAPITAL LETTER O WITH MACRON +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ų LATIN CAPITAL LETTER U WITH OGONEK +331 217 D9 Ł LATIN CAPITAL LETTER L WITH STROKE +332 218 DA Ś LATIN CAPITAL LETTER S WITH ACUTE +333 219 DB Ū LATIN CAPITAL LETTER U WITH MACRON +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE +336 222 DE Ž LATIN CAPITAL LETTER Z WITH CARON +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 ą LATIN SMALL LETTER A WITH OGONEK +341 225 E1 į LATIN SMALL LETTER I WITH OGONEK +342 226 E2 ā LATIN SMALL LETTER A WITH MACRON +343 227 E3 ć LATIN SMALL LETTER C WITH ACUTE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 ę LATIN SMALL LETTER E WITH OGONEK +347 231 E7 ē LATIN SMALL LETTER E WITH MACRON +350 232 E8 č LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ź LATIN SMALL LETTER Z WITH ACUTE +353 235 EB ė LATIN SMALL LETTER E WITH DOT ABOVE +354 236 EC ģ LATIN SMALL LETTER G WITH CEDILLA +355 237 ED ķ LATIN SMALL LETTER K WITH CEDILLA +356 238 EE ī LATIN SMALL LETTER I WITH MACRON +357 239 EF ļ LATIN SMALL LETTER L WITH CEDILLA +360 240 F0 š LATIN SMALL LETTER S WITH CARON +361 241 F1 ń LATIN SMALL LETTER N WITH ACUTE +362 242 F2 ņ LATIN SMALL LETTER N WITH CEDILLA +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ō LATIN SMALL LETTER O WITH MACRON +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ų LATIN SMALL LETTER U WITH OGONEK +371 249 F9 ł LATIN SMALL LETTER L WITH STROKE +372 250 FA ś LATIN SMALL LETTER S WITH ACUTE +373 251 FB ū LATIN SMALL LETTER U WITH MACRON +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ż LATIN SMALL LETTER Z WITH DOT ABOVE +376 254 FE ž LATIN SMALL LETTER Z WITH CARON +377 255 FF ’ RIGHT SINGLE QUOTATION MARK +.TE +.SH NOTES +ISO 8859-13 is also known as Latin-7. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-14.7 b/man7/iso_8859-14.7 new file mode 100644 index 0000000..9a7c740 --- /dev/null +++ b/man7/iso_8859-14.7 @@ -0,0 +1,174 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-14 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-14 \- ISO 8859-14 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-14 encodes the +characters used in Celtic languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-14 characters +The following table displays the characters in ISO 8859-14 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ḃ LATIN CAPITAL LETTER B WITH DOT ABOVE +242 162 A2 ḃ LATIN SMALL LETTER B WITH DOT ABOVE +243 163 A3 £ POUND SIGN +244 164 A4 Ċ LATIN CAPITAL LETTER C WITH DOT ABOVE +245 165 A5 ċ LATIN SMALL LETTER C WITH DOT ABOVE +246 166 A6 Ḋ LATIN CAPITAL LETTER D WITH DOT ABOVE +247 167 A7 § SECTION SIGN +250 168 A8 Ẁ LATIN CAPITAL LETTER W WITH GRAVE +251 169 A9 © COPYRIGHT SIGN +252 170 AA Ẃ LATIN CAPITAL LETTER W WITH ACUTE +253 171 AB ḋ LATIN SMALL LETTER D WITH DOT ABOVE +254 172 AC Ỳ LATIN CAPITAL LETTER Y WITH GRAVE +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS +260 176 B0 Ḟ LATIN CAPITAL LETTER F WITH DOT ABOVE +261 177 B1 ḟ LATIN SMALL LETTER F WITH DOT ABOVE +262 178 B2 Ġ LATIN CAPITAL LETTER G WITH DOT ABOVE +263 179 B3 ġ LATIN SMALL LETTER G WITH DOT ABOVE +264 180 B4 Ṁ LATIN CAPITAL LETTER M WITH DOT ABOVE +265 181 B5 ṁ LATIN SMALL LETTER M WITH DOT ABOVE +266 182 B6 ¶ PILCROW SIGN +267 183 B7 Ṗ LATIN CAPITAL LETTER P WITH DOT ABOVE +270 184 B8 ẁ LATIN SMALL LETTER W WITH GRAVE +271 185 B9 ṗ LATIN SMALL LETTER P WITH DOT ABOVE +272 186 BA ẃ LATIN SMALL LETTER W WITH ACUTE +273 187 BB Ṡ LATIN CAPITAL LETTER S WITH DOT ABOVE +274 188 BC ỳ LATIN SMALL LETTER Y WITH GRAVE +275 189 BD Ẅ LATIN CAPITAL LETTER W WITH DIAERESIS +276 190 BE ẅ LATIN SMALL LETTER W WITH DIAERESIS +277 191 BF ṡ LATIN SMALL LETTER S WITH DOT ABOVE +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ŵ LATIN CAPITAL LETTER W WITH CIRCUMFLEX +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 Ṫ LATIN CAPITAL LETTER T WITH DOT ABOVE +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Ŷ LATIN CAPITAL LETTER Y WITH CIRCUMFLEX +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ŵ LATIN SMALL LETTER W WITH CIRCUMFLEX +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ṫ LATIN SMALL LETTER T WITH DOT ABOVE +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE ŷ LATIN SMALL LETTER Y WITH CIRCUMFLEX +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO 8859-14 is also known as Latin-8. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-15.7 b/man7/iso_8859-15.7 new file mode 100644 index 0000000..15eb919 --- /dev/null +++ b/man7/iso_8859-15.7 @@ -0,0 +1,177 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" Copyright 1999 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-15 7 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-15 \- ISO 8859-15 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-15 encodes the +characters used in many West European languages and adds the Euro sign. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-15 characters +The following table displays the characters in ISO 8859-15 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 € EURO SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 Š LATIN CAPITAL LETTER S WITH CARON +247 167 A7 § SECTION SIGN +250 168 A8 š LATIN SMALL LETTER S WITH CARON +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 Ž LATIN CAPITAL LETTER Z WITH CARON +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ž LATIN SMALL LETTER Z WITH CARON +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC Œ LATIN CAPITAL LIGATURE OE +275 189 BD œ LATIN SMALL LIGATURE OE +276 190 BE Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO 8859-15 is also known as Latin-9 (or sometimes as Latin-0). +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1252 (7), +.BR iso_8859-1 (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-16.7 b/man7/iso_8859-16.7 new file mode 100644 index 0000000..ade94c0 --- /dev/null +++ b/man7/iso_8859-16.7 @@ -0,0 +1,175 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2002 Ionel Mugurel Ciobîcă (IMCiobica@netscape.net) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-16 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-16 \- ISO 8859-16 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-16 encodes the +Latin characters used in Southeast European languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-16 characters +The following table displays the characters in ISO 8859-16 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ą LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 ą LATIN SMALL LETTER A WITH OGONEK +243 163 A3 Ł LATIN CAPITAL LETTER L WITH STROKE +244 164 A4 € EURO SIGN +245 165 A5 „ DOUBLE LOW-9 QUOTATION MARK +246 166 A6 Š LATIN CAPITAL LETTER S WITH CARON +247 167 A7 § SECTION SIGN +250 168 A8 š LATIN SMALL LETTER S WITH CARON +251 169 A9 © COPYRIGHT SIGN +252 170 AA Ș LATIN CAPITAL LETTER S WITH COMMA BELOW +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC Ź LATIN CAPITAL LETTER Z WITH ACUTE +255 173 AD ­ SOFT HYPHEN +256 174 AE ź LATIN SMALL LETTER Z WITH ACUTE +257 175 AF Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 Č LATIN CAPITAL LETTER C WITH CARON +263 179 B3 ł LATIN SMALL LETTER L WITH STROKE +264 180 B4 Ž LATIN CAPITAL LETTER Z WITH CARON +265 181 B5 ” LEFT DOUBLE QUOTATION MARK +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ž LATIN SMALL LETTER Z WITH CARON +271 185 B9 č LATIN SMALL LETTER C WITH CARON +272 186 BA ș LATIN SMALL LETTER S WITH COMMA BELOW +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC Œ LATIN CAPITAL LIGATURE OE +275 189 BD œ LATIN SMALL LIGATURE OE +276 190 BE Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS +277 191 BF ż LATIN SMALL LETTER Z WITH DOT ABOVE +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 Ă LATIN CAPITAL LETTER A WITH BREVE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Ć LATIN CAPITAL LETTER C WITH ACUTE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Đ LATIN CAPITAL LETTER D WITH STROKE +321 209 D1 Ń LATIN CAPITAL LETTER N WITH ACUTE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Ő LATIN CAPITAL LETTER O WITH DOUBLE ACUTE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 Ś LATIN CAPITAL LETTER S WITH ACUTE +330 216 D8 Ű LATIN CAPITAL LETTER U WITH DOUBLE ACUTE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ę LATIN CAPITAL LETTER E WITH OGONEK +336 222 DE Ț LATIN CAPITAL LETTER T WITH COMMA BELOW +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ă LATIN SMALL LETTER A WITH BREVE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 ć LATIN SMALL LETTER C WITH ACUTE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 đ LATIN SMALL LETTER D WITH STROKE +361 241 F1 ń LATIN SMALL LETTER N WITH ACUTE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 ő LATIN SMALL LETTER O WITH DOUBLE ACUTE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ś LATIN SMALL LETTER S WITH ACUTE +370 248 F8 ű LATIN SMALL LETTER U WITH DOUBLE ACUTE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ę LATIN SMALL LETTER E WITH OGONEK +376 254 FE ț LATIN SMALL LETTER T WITH COMMA BELOW +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO 8859-16 is also known as Latin-10. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR iso_8859-3 (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-2.7 b/man7/iso_8859-2.7 new file mode 100644 index 0000000..fdc9aeb --- /dev/null +++ b/man7/iso_8859-2.7 @@ -0,0 +1,179 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 1999 Roman Maurer (roman.maurer@hermes.si) +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Slightly rearranged, aeb, 950713 +.\" Updated, dpo, 990531 +.TH ISO_8859-2 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-2 \- ISO 8859-2 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-2 encodes the +Latin characters used in many Central and East European languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-2 characters +The following table displays the characters in ISO 8859-2 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ą LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 ˘ BREVE +243 163 A3 Ł LATIN CAPITAL LETTER L WITH STROKE +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 Ľ LATIN CAPITAL LETTER L WITH CARON +246 166 A6 Ś LATIN CAPITAL LETTER S WITH ACUTE +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 Š LATIN CAPITAL LETTER S WITH CARON +252 170 AA Ş LATIN CAPITAL LETTER S WITH CEDILLA +253 171 AB Ť LATIN CAPITAL LETTER T WITH CARON +254 172 AC Ź LATIN CAPITAL LETTER Z WITH ACUTE +255 173 AD ­ SOFT HYPHEN +256 174 AE Ž LATIN CAPITAL LETTER Z WITH CARON +257 175 AF Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE +260 176 B0 ° DEGREE SIGN +261 177 B1 ą LATIN SMALL LETTER A WITH OGONEK +262 178 B2 ˛ OGONEK +263 179 B3 ł LATIN SMALL LETTER L WITH STROKE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 ľ LATIN SMALL LETTER L WITH CARON +266 182 B6 ś LATIN SMALL LETTER S WITH ACUTE +267 183 B7 ˇ CARON +270 184 B8 ¸ CEDILLA +271 185 B9 š LATIN SMALL LETTER S WITH CARON +272 186 BA ş LATIN SMALL LETTER S WITH CEDILLA +273 187 BB ť LATIN SMALL LETTER T WITH CARON +274 188 BC ź LATIN SMALL LETTER Z WITH ACUTE +275 189 BD ˝ DOUBLE ACUTE ACCENT +276 190 BE ž LATIN SMALL LETTER Z WITH CARON +277 191 BF ż LATIN SMALL LETTER Z WITH DOT ABOVE +300 192 C0 Ŕ LATIN CAPITAL LETTER R WITH ACUTE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 Ă LATIN CAPITAL LETTER A WITH BREVE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Ĺ LATIN CAPITAL LETTER L WITH ACUTE +306 198 C6 Ć LATIN CAPITAL LETTER C WITH ACUTE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 Č LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ę LATIN CAPITAL LETTER E WITH OGONEK +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ě LATIN CAPITAL LETTER E WITH CARON +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ď LATIN CAPITAL LETTER D WITH CARON +320 208 D0 Đ LATIN CAPITAL LETTER D WITH STROKE +321 209 D1 Ń LATIN CAPITAL LETTER N WITH ACUTE +322 210 D2 Ň LATIN CAPITAL LETTER N WITH CARON +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Ő LATIN CAPITAL LETTER O WITH DOUBLE ACUTE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ř LATIN CAPITAL LETTER R WITH CARON +331 217 D9 Ů LATIN CAPITAL LETTER U WITH RING ABOVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Ű LATIN CAPITAL LETTER U WITH DOUBLE ACUTE +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Ţ LATIN CAPITAL LETTER T WITH CEDILLA +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 ŕ LATIN SMALL LETTER R WITH ACUTE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ă LATIN SMALL LETTER A WITH BREVE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 ĺ LATIN SMALL LETTER L WITH ACUTE +346 230 E6 ć LATIN SMALL LETTER C WITH ACUTE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 č LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ę LATIN SMALL LETTER E WITH OGONEK +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ě LATIN SMALL LETTER E WITH CARON +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ď LATIN SMALL LETTER D WITH CARON +360 240 F0 đ LATIN SMALL LETTER D WITH STROKE +361 241 F1 ń LATIN SMALL LETTER N WITH ACUTE +362 242 F2 ň LATIN SMALL LETTER N WITH CARON +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 ő LATIN SMALL LETTER O WITH DOUBLE ACUTE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ř LATIN SMALL LETTER R WITH CARON +371 249 F9 ů LATIN SMALL LETTER U WITH RING ABOVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB ű LATIN SMALL LETTER U WITH DOUBLE ACUTE +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE ţ LATIN SMALL LETTER T WITH CEDILLA +377 255 FF ˙ DOT ABOVE +.TE +.SH NOTES +ISO 8859-2 is also known as Latin-2. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR iso_8859-1 (7), +.BR iso_8859-16 (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-3.7 b/man7/iso_8859-3.7 new file mode 100644 index 0000000..ad5c119 --- /dev/null +++ b/man7/iso_8859-3.7 @@ -0,0 +1,167 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-3 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-3 \- ISO 8859-3 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-3 encodes the +characters used in certain Southeast European languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-3 characters +The following table displays the characters in ISO 8859-3 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ħ LATIN CAPITAL LETTER H WITH STROKE +242 162 A2 ˘ BREVE +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +246 166 A6 Ĥ LATIN CAPITAL LETTER H WITH CIRCUMFLEX +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 İ LATIN CAPITAL LETTER I WITH DOT ABOVE +252 170 AA Ş LATIN CAPITAL LETTER S WITH CEDILLA +253 171 AB Ğ LATIN CAPITAL LETTER G WITH BREVE +254 172 AC Ĵ LATIN CAPITAL LETTER J WITH CIRCUMFLEX +255 173 AD ­ SOFT HYPHEN +257 175 AF Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE +260 176 B0 ° DEGREE SIGN +261 177 B1 ħ LATIN SMALL LETTER H WITH STROKE +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ĥ LATIN SMALL LETTER H WITH CIRCUMFLEX +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ı LATIN SMALL LETTER DOTLESS I +272 186 BA ş LATIN SMALL LETTER S WITH CEDILLA +273 187 BB ğ LATIN SMALL LETTER G WITH BREVE +274 188 BC ĵ LATIN SMALL LETTER J WITH CIRCUMFLEX +275 189 BD ½ VULGAR FRACTION ONE HALF +277 191 BF ż LATIN SMALL LETTER Z WITH DOT ABOVE +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Ċ LATIN CAPITAL LETTER C WITH DOT ABOVE +306 198 C6 Ĉ LATIN CAPITAL LETTER C WITH CIRCUMFLEX +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Ġ LATIN CAPITAL LETTER G WITH DOT ABOVE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ĝ LATIN CAPITAL LETTER G WITH CIRCUMFLEX +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ŭ LATIN CAPITAL LETTER U WITH BREVE +336 222 DE Ŝ LATIN CAPITAL LETTER S WITH CIRCUMFLEX +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 ċ LATIN SMALL LETTER C WITH DOT ABOVE +346 230 E6 ĉ LATIN SMALL LETTER C WITH CIRCUMFLEX +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 ġ LATIN SMALL LETTER G WITH DOT ABOVE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ĝ LATIN SMALL LETTER G WITH CIRCUMFLEX +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ŭ LATIN SMALL LETTER U WITH BREVE +376 254 FE ŝ LATIN SMALL LETTER S WITH CIRCUMFLEX +377 255 FF ˙ DOT ABOVE +.TE +.SH NOTES +ISO 8859-3 is also known as Latin-3. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-4.7 b/man7/iso_8859-4.7 new file mode 100644 index 0000000..32bfe1f --- /dev/null +++ b/man7/iso_8859-4.7 @@ -0,0 +1,174 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-4 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-4 \- ISO 8859-4 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-4 encodes the +characters used in Scandinavian and Baltic languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-4 characters +The following table displays the characters in ISO 8859-4 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ą LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 ĸ LATIN SMALL LETTER KRA (Greenlandic) +243 163 A3 Ŗ LATIN CAPITAL LETTER R WITH CEDILLA +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 Ĩ LATIN CAPITAL LETTER I WITH TILDE +246 166 A6 Ļ LATIN CAPITAL LETTER L WITH CEDILLA +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 Š LATIN CAPITAL LETTER S WITH CARON +252 170 AA Ē LATIN CAPITAL LETTER E WITH MACRON +253 171 AB Ģ LATIN CAPITAL LETTER G WITH CEDILLA +254 172 AC Ŧ LATIN CAPITAL LETTER T WITH STROKE +255 173 AD ­ SOFT HYPHEN +256 174 AE Ž LATIN CAPITAL LETTER Z WITH CARON +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ą LATIN SMALL LETTER A WITH OGONEK +262 178 B2 ˛ OGONEK +263 179 B3 ŗ LATIN SMALL LETTER R WITH CEDILLA +264 180 B4 ´ ACUTE ACCENT +265 181 B5 ĩ LATIN SMALL LETTER I WITH TILDE +266 182 B6 ļ LATIN SMALL LETTER L WITH CEDILLA +267 183 B7 ˇ CARON +270 184 B8 ¸ CEDILLA +271 185 B9 š LATIN SMALL LETTER S WITH CARON +272 186 BA ē LATIN SMALL LETTER E WITH MACRON +273 187 BB ģ LATIN SMALL LETTER G WITH CEDILLA +274 188 BC ŧ LATIN SMALL LETTER T WITH STROKE +275 189 BD Ŋ LATIN CAPITAL LETTER ENG +276 190 BE ž LATIN SMALL LETTER Z WITH CARON +277 191 BF ŋ LATIN SMALL LETTER ENG +300 192 C0 Ā LATIN CAPITAL LETTER A WITH MACRON +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Į LATIN CAPITAL LETTER I WITH OGONEK +310 200 C8 Č LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ę LATIN CAPITAL LETTER E WITH OGONEK +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ė LATIN CAPITAL LETTER E WITH DOT ABOVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ī LATIN CAPITAL LETTER I WITH MACRON +320 208 D0 Đ LATIN CAPITAL LETTER D WITH STROKE +321 209 D1 Ņ LATIN CAPITAL LETTER N WITH CEDILLA +322 210 D2 Ō LATIN CAPITAL LETTER O WITH MACRON +323 211 D3 Ķ LATIN CAPITAL LETTER K WITH CEDILLA +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ų LATIN CAPITAL LETTER U WITH OGONEK +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ũ LATIN CAPITAL LETTER U WITH TILDE +336 222 DE Ū LATIN CAPITAL LETTER U WITH MACRON +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 ā LATIN SMALL LETTER A WITH MACRON +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 į LATIN SMALL LETTER I WITH OGONEK +350 232 E8 č LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ę LATIN SMALL LETTER E WITH OGONEK +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ė LATIN SMALL LETTER E WITH DOT ABOVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ī LATIN SMALL LETTER I WITH MACRON +360 240 F0 đ LATIN SMALL LETTER D WITH STROKE +361 241 F1 ņ LATIN SMALL LETTER N WITH CEDILLA +362 242 F2 ō LATIN SMALL LETTER O WITH MACRON +363 243 F3 ķ LATIN SMALL LETTER K WITH CEDILLA +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ų LATIN SMALL LETTER U WITH OGONEK +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ũ LATIN SMALL LETTER U WITH TILDE +376 254 FE ū LATIN SMALL LETTER U WITH MACRON +377 255 FF ˙ DOT ABOVE +.TE +.SH NOTES +ISO 8859-4 is also known as Latin-4. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-5.7 b/man7/iso_8859-5.7 new file mode 100644 index 0000000..9bf2a48 --- /dev/null +++ b/man7/iso_8859-5.7 @@ -0,0 +1,179 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-5 7 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-5 \- ISO 8859-5 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-5 encodes the +Cyrillic characters used in many East European languages. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-5 characters +The following table displays the characters in ISO 8859-5 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ё CYRILLIC CAPITAL LETTER IO +242 162 A2 Ђ CYRILLIC CAPITAL LETTER DJE +243 163 A3 Ѓ CYRILLIC CAPITAL LETTER GJE +244 164 A4 Є CYRILLIC CAPITAL LETTER UKRAINIAN IE +245 165 A5 Ѕ CYRILLIC CAPITAL LETTER DZE +246 166 A6 І T{ +CYRILLIC CAPITAL LETTER +.br +BYELORUSSIAN-UKRAINIAN I +T} +247 167 A7 Ї CYRILLIC CAPITAL LETTER YI +250 168 A8 Ј CYRILLIC CAPITAL LETTER JE +251 169 A9 Љ CYRILLIC CAPITAL LETTER LJE +252 170 AA Њ CYRILLIC CAPITAL LETTER NJE +253 171 AB Ћ CYRILLIC CAPITAL LETTER TSHE +254 172 AC Ќ CYRILLIC CAPITAL LETTER KJE +255 173 AD ­ SOFT HYPHEN +256 174 AE Ў CYRILLIC CAPITAL LETTER SHORT U +257 175 AF Џ CYRILLIC CAPITAL LETTER DZHE +260 176 B0 А CYRILLIC CAPITAL LETTER A +261 177 B1 Б CYRILLIC CAPITAL LETTER BE +262 178 B2 В CYRILLIC CAPITAL LETTER VE +263 179 B3 Г CYRILLIC CAPITAL LETTER GHE +264 180 B4 Д CYRILLIC CAPITAL LETTER DE +265 181 B5 Е CYRILLIC CAPITAL LETTER IE +266 182 B6 Ж CYRILLIC CAPITAL LETTER ZHE +267 183 B7 З CYRILLIC CAPITAL LETTER ZE +270 184 B8 И CYRILLIC CAPITAL LETTER I +271 185 B9 Й CYRILLIC CAPITAL LETTER SHORT I +272 186 BA К CYRILLIC CAPITAL LETTER KA +273 187 BB Л CYRILLIC CAPITAL LETTER EL +274 188 BC М CYRILLIC CAPITAL LETTER EM +275 189 BD Н CYRILLIC CAPITAL LETTER EN +276 190 BE О CYRILLIC CAPITAL LETTER O +277 191 BF П CYRILLIC CAPITAL LETTER PE +300 192 C0 Р CYRILLIC CAPITAL LETTER ER +301 193 C1 С CYRILLIC CAPITAL LETTER ES +302 194 C2 Т CYRILLIC CAPITAL LETTER TE +303 195 C3 У CYRILLIC CAPITAL LETTER U +304 196 C4 Ф CYRILLIC CAPITAL LETTER EF +305 197 C5 Х CYRILLIC CAPITAL LETTER HA +306 198 C6 Ц CYRILLIC CAPITAL LETTER TSE +307 199 C7 Ч CYRILLIC CAPITAL LETTER CHE +310 200 C8 Ш CYRILLIC CAPITAL LETTER SHA +311 201 C9 Щ CYRILLIC CAPITAL LETTER SHCHA +312 202 CA Ъ CYRILLIC CAPITAL LETTER HARD SIGN +313 203 CB Ы CYRILLIC CAPITAL LETTER YERU +314 204 CC Ь CYRILLIC CAPITAL LETTER SOFT SIGN +315 205 CD Э CYRILLIC CAPITAL LETTER E +316 206 CE Ю CYRILLIC CAPITAL LETTER YU +317 207 CF Я CYRILLIC CAPITAL LETTER YA +320 208 D0 а CYRILLIC SMALL LETTER A +321 209 D1 б CYRILLIC SMALL LETTER BE +322 210 D2 в CYRILLIC SMALL LETTER VE +323 211 D3 г CYRILLIC SMALL LETTER GHE +324 212 D4 д CYRILLIC SMALL LETTER DE +325 213 D5 е CYRILLIC SMALL LETTER IE +326 214 D6 ж CYRILLIC SMALL LETTER ZHE +327 215 D7 з CYRILLIC SMALL LETTER ZE +330 216 D8 и CYRILLIC SMALL LETTER I +331 217 D9 й CYRILLIC SMALL LETTER SHORT I +332 218 DA к CYRILLIC SMALL LETTER KA +333 219 DB л CYRILLIC SMALL LETTER EL +334 220 DC м CYRILLIC SMALL LETTER EM +335 221 DD н CYRILLIC SMALL LETTER EN +336 222 DE о CYRILLIC SMALL LETTER O +337 223 DF п CYRILLIC SMALL LETTER PE +340 224 E0 р CYRILLIC SMALL LETTER ER +341 225 E1 с CYRILLIC SMALL LETTER ES +342 226 E2 т CYRILLIC SMALL LETTER TE +343 227 E3 у CYRILLIC SMALL LETTER U +344 228 E4 ф CYRILLIC SMALL LETTER EF +345 229 E5 х CYRILLIC SMALL LETTER HA +346 230 E6 ц CYRILLIC SMALL LETTER TSE +347 231 E7 ч CYRILLIC SMALL LETTER CHE +350 232 E8 ш CYRILLIC SMALL LETTER SHA +351 233 E9 щ CYRILLIC SMALL LETTER SHCHA +352 234 EA ъ CYRILLIC SMALL LETTER HARD SIGN +353 235 EB ы CYRILLIC SMALL LETTER YERU +354 236 EC ь CYRILLIC SMALL LETTER SOFT SIGN +355 237 ED э CYRILLIC SMALL LETTER E +356 238 EE ю CYRILLIC SMALL LETTER YU +357 239 EF я CYRILLIC SMALL LETTER YA +360 240 F0 № NUMERO SIGN +361 241 F1 ё CYRILLIC SMALL LETTER IO +362 242 F2 ђ CYRILLIC SMALL LETTER DJE +363 243 F3 ѓ CYRILLIC SMALL LETTER GJE +364 244 F4 є CYRILLIC SMALL LETTER UKRAINIAN IE +365 245 F5 ѕ CYRILLIC SMALL LETTER DZE +366 246 F6 і CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I +367 247 F7 ї CYRILLIC SMALL LETTER YI +370 248 F8 ј CYRILLIC SMALL LETTER JE +371 249 F9 љ CYRILLIC SMALL LETTER LJE +372 250 FA њ CYRILLIC SMALL LETTER NJE +373 251 FB ј CYRILLIC SMALL LETTER TSHE +374 252 FC ќ CYRILLIC SMALL LETTER KJE +375 253 FD § SECTION SIGN +376 254 FE ў CYRILLIC SMALL LETTER SHORT U +377 255 FF џ CYRILLIC SMALL LETTER DZHE +.TE +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1251 (7), +.BR koi8-r (7), +.BR koi8-u (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-6.7 b/man7/iso_8859-6.7 new file mode 100644 index 0000000..2994a1f --- /dev/null +++ b/man7/iso_8859-6.7 @@ -0,0 +1,130 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-6 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-6 \- ISO 8859-6 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-6 encodes the +characters used in the Arabic language. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-6 characters +The following table displays the characters in ISO 8859-6 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +244 164 A4 ¤ CURRENCY SIGN +254 172 AC ، ARABIC COMMA +255 173 AD ­ SOFT HYPHEN +273 187 BB ؛ ARABIC SEMICOLON +277 191 BF ؟ ARABIC QUESTION MARK +301 193 C1 ء ARABIC LETTER HAMZA +302 194 C2 آ ARABIC LETTER ALEF WITH MADDA ABOVE +303 195 C3 أ ARABIC LETTER ALEF WITH HAMZA ABOVE +304 196 C4 ؤ ARABIC LETTER WAW WITH HAMZA ABOVE +305 197 C5 إ ARABIC LETTER ALEF WITH HAMZA BELOW +306 198 C6 ئ ARABIC LETTER YEH WITH HAMZA ABOVE +307 199 C7 ا ARABIC LETTER ALEF +310 200 C8 ب ARABIC LETTER BEH +311 201 C9 ة ARABIC LETTER TEH MARBUTA +312 202 CA ت ARABIC LETTER TEH +313 203 CB ث ARABIC LETTER THEH +314 204 CC ج ARABIC LETTER JEEM +315 205 CD ح ARABIC LETTER HAH +316 206 CE خ ARABIC LETTER KHAH +317 207 CF د ARABIC LETTER DAL +320 208 D0 ذ ARABIC LETTER THAL +321 209 D1 ر ARABIC LETTER REH +322 210 D2 ز ARABIC LETTER ZAIN +323 211 D3 س ARABIC LETTER SEEN +324 212 D4 ش ARABIC LETTER SHEEN +325 213 D5 ص ARABIC LETTER SAD +326 214 D6 ض ARABIC LETTER DAD +327 215 D7 ط ARABIC LETTER TAH +330 216 D8 ظ ARABIC LETTER ZAH +331 217 D9 ع ARABIC LETTER AIN +332 218 DA غ ARABIC LETTER GHAIN +340 224 E0 ـ ARABIC TATWEEL +341 225 E1 ف ARABIC LETTER FEH +342 226 E2 ق ARABIC LETTER QAF +343 227 E3 ك ARABIC LETTER KAF +344 228 E4 ل ARABIC LETTER LAM +345 229 E5 م ARABIC LETTER MEEM +346 230 E6 ن ARABIC LETTER NOON +347 231 E7 ه ARABIC LETTER HEH +350 232 E8 و ARABIC LETTER WAW +351 233 E9 ى ARABIC LETTER ALEF MAKSURA +352 234 EA ي ARABIC LETTER YEH +353 235 EB ً ARABIC FATHATAN +354 236 EC ٌ ARABIC DAMMATAN +355 237 ED ٍ ARABIC KASRATAN +356 238 EE َ ARABIC FATHA +357 239 EF ُ ARABIC DAMMA +360 240 F0 ِ ARABIC KASRA +361 241 F1 ّ ARABIC SHADDA +362 242 F2 ْ ARABIC SUKUN +.TE +.SH NOTES +ISO 8859-6 lacks the glyphs required for many related languages, +such as Urdu and Persian (Farsi). +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-7.7 b/man7/iso_8859-7.7 new file mode 100644 index 0000000..87b3962 --- /dev/null +++ b/man7/iso_8859-7.7 @@ -0,0 +1,178 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 1999 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-7 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-7 \- ISO 8859-7 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-7 encodes the +characters used in modern monotonic Greek. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-7 characters +The following table displays the characters in ISO 8859-7 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ‘ LEFT SINGLE QUOTATION MARK +242 162 A2 ’ RIGHT SINGLE QUOTATION MARK +243 163 A3 £ POUND SIGN +244 164 A4 € EURO SIGN +245 165 A5 ₯ DRACHMA SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ͺ GREEK YPOGEGRAMMENI +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +257 175 AF ― HORIZONTAL BAR +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ΄ GREEK TONOS +265 181 B5 ΅ GREEK DIALYTIKA TONOS +266 182 B6 Ά GREEK CAPITAL LETTER ALPHA WITH TONOS +267 183 B7 · MIDDLE DOT +270 184 B8 Έ GREEK CAPITAL LETTER EPSILON WITH TONOS +271 185 B9 Ή GREEK CAPITAL LETTER ETA WITH TONOS +272 186 BA Ί GREEK CAPITAL LETTER IOTA WITH TONOS +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC Ό GREEK CAPITAL LETTER OMICRON WITH TONOS +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE Ύ GREEK CAPITAL LETTER UPSILON WITH TONOS +277 191 BF Ώ GREEK CAPITAL LETTER OMEGA WITH TONOS +300 192 C0 ΐ T{ +GREEK SMALL LETTER IOTA WITH +.br +DIALYTIKA AND TONOS +T} +301 193 C1 Α GREEK CAPITAL LETTER ALPHA +302 194 C2 Β GREEK CAPITAL LETTER BETA +303 195 C3 Γ GREEK CAPITAL LETTER GAMMA +304 196 C4 Δ GREEK CAPITAL LETTER DELTA +305 197 C5 Ε GREEK CAPITAL LETTER EPSILON +306 198 C6 Ζ GREEK CAPITAL LETTER ZETA +307 199 C7 Η GREEK CAPITAL LETTER ETA +310 200 C8 Θ GREEK CAPITAL LETTER THETA +311 201 C9 Ι GREEK CAPITAL LETTER IOTA +312 202 CA Κ GREEK CAPITAL LETTER KAPPA +313 203 CB Λ GREEK CAPITAL LETTER LAMBDA +314 204 CC Μ GREEK CAPITAL LETTER MU +315 205 CD Ν GREEK CAPITAL LETTER NU +316 206 CE Ξ GREEK CAPITAL LETTER XI +317 207 CF Ο GREEK CAPITAL LETTER OMICRON +320 208 D0 Π GREEK CAPITAL LETTER PI +321 209 D1 Ρ GREEK CAPITAL LETTER RHO +323 211 D3 Σ GREEK CAPITAL LETTER SIGMA +324 212 D4 Τ GREEK CAPITAL LETTER TAU +325 213 D5 Υ GREEK CAPITAL LETTER UPSILON +326 214 D6 Φ GREEK CAPITAL LETTER PHI +327 215 D7 Χ GREEK CAPITAL LETTER CHI +330 216 D8 Ψ GREEK CAPITAL LETTER PSI +331 217 D9 Ω GREEK CAPITAL LETTER OMEGA +332 218 DA Ϊ GREEK CAPITAL LETTER IOTA WITH DIALYTIKA +333 219 DB Ϋ GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA +334 220 DC ά GREEK SMALL LETTER ALPHA WITH TONOS +335 221 DD έ GREEK SMALL LETTER EPSILON WITH TONOS +336 222 DE ή GREEK SMALL LETTER ETA WITH TONOS +337 223 DF ί GREEK SMALL LETTER IOTA WITH TONOS +340 224 E0 ΰ T{ +GREEK SMALL LETTER UPSILON WITH +DIALYTIKA AND TONOS +T} +341 225 E1 α GREEK SMALL LETTER ALPHA +342 226 E2 β GREEK SMALL LETTER BETA +343 227 E3 γ GREEK SMALL LETTER GAMMA +344 228 E4 δ GREEK SMALL LETTER DELTA +345 229 E5 ε GREEK SMALL LETTER EPSILON +346 230 E6 ζ GREEK SMALL LETTER ZETA +347 231 E7 η GREEK SMALL LETTER ETA +350 232 E8 θ GREEK SMALL LETTER THETA +351 233 E9 ι GREEK SMALL LETTER IOTA +352 234 EA κ GREEK SMALL LETTER KAPPA +353 235 EB λ GREEK SMALL LETTER LAMBDA +354 236 EC μ GREEK SMALL LETTER MU +355 237 ED ν GREEK SMALL LETTER NU +356 238 EE ξ GREEK SMALL LETTER XI +357 239 EF ο GREEK SMALL LETTER OMICRON +360 240 F0 π GREEK SMALL LETTER PI +361 241 F1 ρ GREEK SMALL LETTER RHO +362 242 F2 ς GREEK SMALL LETTER FINAL SIGMA +363 243 F3 σ GREEK SMALL LETTER SIGMA +364 244 F4 τ GREEK SMALL LETTER TAU +365 245 F5 υ GREEK SMALL LETTER UPSILON +366 246 F6 φ GREEK SMALL LETTER PHI +367 247 F7 χ GREEK SMALL LETTER CHI +370 248 F8 ψ GREEK SMALL LETTER PSI +371 249 F9 ω GREEK SMALL LETTER OMEGA +372 250 FA ϊ GREEK SMALL LETTER IOTA WITH DIALYTIKA +373 251 FB ϋ GREEK SMALL LETTER UPSILON WITH DIALYTIKA +374 252 FC ό GREEK SMALL LETTER OMICRON WITH TONOS +375 253 FD ύ GREEK SMALL LETTER UPSILON WITH TONOS +376 254 FE ώ GREEK SMALL LETTER OMEGA WITH TONOS +.TE +.SH NOTES +ISO 8859-7 was formerly known as ELOT-928 or ECMA-118:1986. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-8.7 b/man7/iso_8859-8.7 new file mode 100644 index 0000000..bef8455 --- /dev/null +++ b/man7/iso_8859-8.7 @@ -0,0 +1,142 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Eli Zaretskii made valuable suggestions +.\" +.TH ISO_8859-8 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-8 \- ISO 8859-8 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-8 encodes the +characters used in Modern Hebrew. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-8 characters +The following table displays the characters in ISO 8859-8 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0 NO-BREAK SPACE +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA × MULTIPLICATION SIGN +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA ÷ DIVISION SIGN +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +337 223 DF ‗ DOUBLE LOW LINE +340 224 E0 א HEBREW LETTER ALEF +341 225 E1 ב HEBREW LETTER BET +342 226 E2 ג HEBREW LETTER GIMEL +343 227 E3 ד HEBREW LETTER DALET +344 228 E4 ה HEBREW LETTER HE +345 229 E5 ו HEBREW LETTER VAV +346 230 E6 ז HEBREW LETTER ZAYIN +347 231 E7 ח HEBREW LETTER HET +350 232 E8 ט HEBREW LETTER TET +351 233 E9 י HEBREW LETTER YOD +352 234 EA ך HEBREW LETTER FINAL KAF +353 235 EB כ HEBREW LETTER KAF +354 236 EC ל HEBREW LETTER LAMED +355 237 ED ם HEBREW LETTER FINAL MEM +356 238 EE מ HEBREW LETTER MEM +357 239 EF ן HEBREW LETTER FINAL NUN +360 240 F0 נ HEBREW LETTER NUN +361 241 F1 ס HEBREW LETTER SAMEKH +362 242 F2 ע HEBREW LETTER AYIN +363 243 F3 ף HEBREW LETTER FINAL PE +364 244 F4 פ HEBREW LETTER PE +365 245 F5 ץ HEBREW LETTER FINAL TSADI +366 246 F6 צ HEBREW LETTER TSADI +367 247 F7 ק HEBREW LETTER QOF +370 248 F8 ר HEBREW LETTER RESH +371 249 F9 ש HEBREW LETTER SHIN +372 250 FA ת HEBREW LETTER TAV +375 253 FD ‎ LEFT-TO-RIGHT MARK +376 254 FE ‏ RIGHT-TO-LEFT MARK +.TE +.SH NOTES +ISO 8859-8 was also known as ISO-IR-138. +ISO 8859-8 includes neither short vowels nor diacritical marks, +and Yiddish is not provided for. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859-9.7 b/man7/iso_8859-9.7 new file mode 100644 index 0000000..98239f2 --- /dev/null +++ b/man7/iso_8859-9.7 @@ -0,0 +1,174 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2002 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ISO_8859-9 7 2014-10-02 "Linux" "Linux Programmer's Manual" +.SH NAME +iso_8859-9 \- ISO 8859-9 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO 8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO 646-IRV). +ISO 8859-9 encodes the +characters used in Turkish. +.SS ISO 8859 alphabets +The full set of ISO 8859 alphabets includes: +.TS +l l. +ISO 8859-1 West European languages (Latin-1) +ISO 8859-2 Central and East European languages (Latin-2) +ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO 8859-4 Scandinavian/Baltic languages (Latin-4) +ISO 8859-5 Latin/Cyrillic +ISO 8859-6 Latin/Arabic +ISO 8859-7 Latin/Greek +ISO 8859-8 Latin/Hebrew +ISO 8859-9 Latin-1 modification for Turkish (Latin-5) +ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO 8859-11 Latin/Thai +ISO 8859-13 Baltic Rim languages (Latin-7) +ISO 8859-14 Celtic (Latin-8) +ISO 8859-15 West European languages (Latin-9) +ISO 8859-16 Romanian (Latin-10) +.TE +.SS ISO 8859-9 characters +The following table displays the characters in ISO 8859-9 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ğ LATIN CAPITAL LETTER G WITH BREVE +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD İ LATIN CAPITAL LETTER I WITH DOT ABOVE +336 222 DE Ş LATIN CAPITAL LETTER S WITH CEDILLA +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ğ LATIN SMALL LETTER G WITH BREVE +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ı LATIN SMALL LETTER DOTLESS I +376 254 FE ş LATIN SMALL LETTER S WITH CEDILLA +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO 8859-9 is also known as Latin-5. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/iso_8859_1.7 b/man7/iso_8859_1.7 new file mode 100644 index 0000000..1969dfb --- /dev/null +++ b/man7/iso_8859_1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man7/iso_8859_10.7 b/man7/iso_8859_10.7 new file mode 100644 index 0000000..9b4658f --- /dev/null +++ b/man7/iso_8859_10.7 @@ -0,0 +1 @@ +.so man7/iso_8859-10.7 diff --git a/man7/iso_8859_11.7 b/man7/iso_8859_11.7 new file mode 100644 index 0000000..cbd4cfe --- /dev/null +++ b/man7/iso_8859_11.7 @@ -0,0 +1 @@ +.so man7/iso_8859-11.7 diff --git a/man7/iso_8859_13.7 b/man7/iso_8859_13.7 new file mode 100644 index 0000000..8ad2335 --- /dev/null +++ b/man7/iso_8859_13.7 @@ -0,0 +1 @@ +.so man7/iso_8859-13.7 diff --git a/man7/iso_8859_14.7 b/man7/iso_8859_14.7 new file mode 100644 index 0000000..4aa555d --- /dev/null +++ b/man7/iso_8859_14.7 @@ -0,0 +1 @@ +.so man7/iso_8859-14.7 diff --git a/man7/iso_8859_15.7 b/man7/iso_8859_15.7 new file mode 100644 index 0000000..a4095d7 --- /dev/null +++ b/man7/iso_8859_15.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man7/iso_8859_16.7 b/man7/iso_8859_16.7 new file mode 100644 index 0000000..b9c8e91 --- /dev/null +++ b/man7/iso_8859_16.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man7/iso_8859_2.7 b/man7/iso_8859_2.7 new file mode 100644 index 0000000..da36668 --- /dev/null +++ b/man7/iso_8859_2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man7/iso_8859_3.7 b/man7/iso_8859_3.7 new file mode 100644 index 0000000..75e42ce --- /dev/null +++ b/man7/iso_8859_3.7 @@ -0,0 +1 @@ +.so man7/iso_8859-3.7 diff --git a/man7/iso_8859_4.7 b/man7/iso_8859_4.7 new file mode 100644 index 0000000..15a829e --- /dev/null +++ b/man7/iso_8859_4.7 @@ -0,0 +1 @@ +.so man7/iso_8859-4.7 diff --git a/man7/iso_8859_5.7 b/man7/iso_8859_5.7 new file mode 100644 index 0000000..1f20320 --- /dev/null +++ b/man7/iso_8859_5.7 @@ -0,0 +1 @@ +.so man7/iso_8859-5.7 diff --git a/man7/iso_8859_6.7 b/man7/iso_8859_6.7 new file mode 100644 index 0000000..edcafdf --- /dev/null +++ b/man7/iso_8859_6.7 @@ -0,0 +1 @@ +.so man7/iso_8859-6.7 diff --git a/man7/iso_8859_7.7 b/man7/iso_8859_7.7 new file mode 100644 index 0000000..951384c --- /dev/null +++ b/man7/iso_8859_7.7 @@ -0,0 +1 @@ +.so man7/iso_8859-7.7 diff --git a/man7/iso_8859_8.7 b/man7/iso_8859_8.7 new file mode 100644 index 0000000..07cf216 --- /dev/null +++ b/man7/iso_8859_8.7 @@ -0,0 +1 @@ +.so man7/iso_8859-8.7 diff --git a/man7/iso_8859_9.7 b/man7/iso_8859_9.7 new file mode 100644 index 0000000..0fcc7d4 --- /dev/null +++ b/man7/iso_8859_9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man7/keyrings.7 b/man7/keyrings.7 new file mode 100644 index 0000000..8c7951f --- /dev/null +++ b/man7/keyrings.7 @@ -0,0 +1,894 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH KEYRINGS 7 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +keyrings \- in-kernel key management and retention facility +.SH DESCRIPTION +The Linux key-management facility +is primarily a way for various kernel components +to retain or cache security data, +authentication keys, encryption keys, and other data in the kernel. +.PP +System call interfaces are provided so that user-space programs can manage +those objects and also use the facility for their own purposes; see +.BR add_key (2), +.BR request_key (2), +and +.BR keyctl (2). +.PP +A library and some user-space utilities are provided to allow access to the +facility. +See +.BR keyctl (1), +.BR keyctl (3), +and +.BR keyutils (7) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Keys +A key has the following attributes: +.TP +Serial number (ID) +This is a unique integer handle by which a key is referred to in system calls. +The serial number is sometimes synonymously referred as the key ID. +Programmatically, key serial numbers are represented using the type +.IR key_serial_t . +.TP +Type +A key's type defines what sort of data can be held in the key, +how the proposed content of the key will be parsed, +and how the payload will be used. +.IP +There are a number of general-purpose types available, plus some specialist +types defined by specific kernel components. +.TP +Description (name) +The key description is a printable string that is used as the search term +for the key (in conjunction with the key type) as well as a display name. +During searches, the description may be partially matched or exactly matched. +.TP +Payload (data) +The payload is the actual content of a key. +This is usually set when a key is created, +but it is possible for the kernel to upcall to user space to finish the +instantiation of a key if that key wasn't already known to the kernel +when it was requested. +For further details, see +.BR request_key (2). +.IP +A key's payload can be read and updated if the key type supports it and if +suitable permission is granted to the caller. +.TP +Access rights +Much as files do, +each key has an owning user ID, an owning group ID, and a security label. +Each key also has a set of permissions, +though there are more than for a normal UNIX file, +and there is an additional category\(empossessor\(embeyond the usual user, +group, and other (see +.IR Possession , +below). +.IP +Note that keys are quota controlled, since they require unswappable kernel +memory. +The owning user ID specifies whose quota is to be debited. +.TP +Expiration time +Each key can have an expiration time set. +When that time is reached, +the key is marked as being expired and accesses to it fail with the error +.BR EKEYEXPIRED . +If not deleted, updated, or replaced, then, after a set amount of time, +an expired key is automatically removed (garbage collected) +along with all links to it, +and attempts to access the key fail with the error +.BR ENOKEY . +.TP +Reference count +Each key has a reference count. +Keys are referenced by keyrings, by currently active users, +and by a process's credentials. +When the reference count reaches zero, +the key is scheduled for garbage collection. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Key types +The kernel provides several basic types of key: +.TP +.I """keyring""" +'\" Note that keyrings use different fields in struct key in order to store +'\" their data - index_key instead of type/description and name_link/keys +'\" instead of payload. +Keyrings are special keys which store a set of links +to other keys (including other keyrings), +analogous to a directory holding links to files. +The main purpose of a keyring is to prevent other keys from +being garbage collected because nothing refers to them. +.IP +Keyrings with descriptions (names) +that begin with a period (\(aq.\(aq) are reserved to the implementation. +.TP +.I """user""" +This is a general-purpose key type. +The key is kept entirely within kernel memory. +The payload may be read and updated by user-space applications. +.IP +The payload for keys of this type is a blob of arbitrary data +of up to 32,767 bytes. +.IP +The description may be any valid string, though it is preferred that it +start with a colon-delimited prefix representing the service +to which the key is of interest +(for instance +.IR """afs:mykey""" ). +.TP +.IR """logon""" " (since Linux 3.3)" +.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b +This key type is essentially the same as +.IR """user""" , +but it does not provide reading (i.e., the +.BR keyctl (2) +.BR KEYCTL_READ +operation), +meaning that the key payload is never visible from user space. +This is suitable for storing username-password pairs +that should not be readable from user space. +.IP +The description of a +.IR """logon""" +key +.I must\ +start with a non-empty colon-delimited prefix whose purpose +is to identify the service to which the key belongs. +(Note that this differs from keys of the +.IR """user""" +type, where the inclusion of a prefix is recommended but is not enforced.) +.TP +.IR """big_key""" " (since Linux 3.13)" +.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 +This key type is similar to the +.I """user""" +key type, but it may hold a payload of up to 1\ MiB in size. +This key type is useful for purposes such as holding Kerberos ticket caches. +.IP +The payload data may be stored in a tmpfs filesystem, +rather than in kernel memory, +if the data size exceeds the overhead of storing the data in the filesystem. +(Storing the data in a filesystem requires filesystem structures +to be allocated in the kernel. +The size of these structures determines the size threshold +above which the tmpfs storage method is used.) +Since Linux 4.8, +.\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef +the payload data is encrypted when stored in tmpfs, +thereby preventing it from being written unencrypted into swap space. +.PP +There are more specialized key types available also, +but they aren't discussed here +because they aren't intended for normal user-space use. +.PP +Key type names +that begin with a period (\(aq.\(aq) are reserved to the implementation. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Keyrings +As previously mentioned, keyrings are a special type of key that contain +links to other keys (which may include other keyrings). +Keys may be linked to by multiple keyrings. +Keyrings may be considered as analogous to UNIX directories +where each directory contains a set of hard links to files. +.PP +Various operations (system calls) may be applied only to keyrings: +.IP Adding +A key may be added to a keyring by system calls that create keys. +This prevents the new key from being immediately deleted +when the system call releases its last reference to the key. +.IP Linking +A link may be added to a keyring pointing to a key that is already known, +provided this does not create a self-referential cycle. +.IP Unlinking +A link may be removed from a keyring. +When the last link to a key is removed, +that key will be scheduled for deletion by the garbage collector. +.IP Clearing +All the links may be removed from a keyring. +.IP Searching +A keyring may be considered the root of a tree or subtree in which keyrings +form the branches and non-keyrings the leaves. +This tree may be searched for a key matching +a particular type and description. +.PP +See +.BR keyctl_clear (3), +.BR keyctl_link (3), +.BR keyctl_search (3), +and +.BR keyctl_unlink (3) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Anchoring keys +To prevent a key from being garbage collected, +it must anchored to keep its reference count elevated +when it is not in active use by the kernel. +.PP +Keyrings are used to anchor other keys: +each link is a reference on a key. +Note that keyrings themselves are just keys and +are also subject to the same anchoring requirement to prevent +them being garbage collected. +.PP +The kernel makes available a number of anchor keyrings. +Note that some of these keyrings will be created only when first accessed. +.TP +Process keyrings +Process credentials themselves reference keyrings with specific semantics. +These keyrings are pinned as long as the set of credentials exists, +which is usually as long as the process exists. +.IP +There are three keyrings with different inheritance/sharing rules: +the +.BR session-keyring (7) +(inherited and shared by all child processes), +the +.BR process-keyring (7) +(shared by all threads in a process) and +the +.BR thread-keyring (7) +(specific to a particular thread). +.IP +As an alternative to using the actual keyring IDs, +in calls to +.BR add_key (2), +.BR keyctl (2), +and +.BR request_key (2), +the special keyring values +.BR KEY_SPEC_SESSION_KEYRING , +.BR KEY_SPEC_PROCESS_KEYRING , +and +.BR KEY_SPEC_THREAD_KEYRING +can be used to refer to the caller's own instances of these keyrings. +.TP +User keyrings +Each UID known to the kernel has a record that contains two keyrings: the +.BR user-keyring (7) +and the +.BR user-session-keyring (7). +These exist for as long as the UID record in the kernel exists. +.IP +As an alternative to using the actual keyring IDs, +in calls to +.BR add_key (2), +.BR keyctl (2), +and +.BR request_key (2), +the special keyring values +.BR KEY_SPEC_USER_KEYRING +and +.BR KEY_SPEC_USER_SESSION_KEYRING +can be used to refer to the caller's own instances of these keyrings. +.IP +A link to the user keyring is placed in a new session keyring by +.BR pam_keyinit (8) +when a new login session is initiated. +.TP +Persistent keyrings +There is a +.BR persistent-keyring (7) +available to each UID known to the system. +It may persist beyond the life of the UID record previously mentioned, +but has an expiration time set such that it is automatically cleaned up +after a set time. +The persistent keyring permits, for example, +.BR cron (8) +scripts to use credentials that are left in the persistent keyring after +the user logs out. +.IP +Note that the expiration time of the persistent keyring +is reset every time the persistent key is requested. +.TP +Special keyrings +There are special keyrings owned by the kernel that can anchor keys +for special purposes. +An example of this is the \fIsystem keyring\fR used for holding +encryption keys for module signature verification. +.IP +These special keyrings are usually closed to direct alteration +by user space. +.PP +An originally planned "group keyring", +for storing keys associated with each GID known to the kernel, +is not so far implemented, is unlikely to be implemented. +Nevertheless, the constant +.BR KEY_SPEC_GROUP_KEYRING +has been defined for this keyring. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Possession +The concept of possession is important to understanding the keyrings +security model. +Whether a thread possesses a key is determined by the following rules: +.IP (1) 4 +Any key or keyring that does not grant +.I search +permission to the caller is ignored in all the following rules. +.IP (2) +A thread possesses its +.BR session-keyring (7), +.BR process-keyring (7), +and +.BR thread-keyring (7) +directly because those keyrings are referred to by its credentials. +.IP (3) +If a keyring is possessed, then any key it links to is also possessed. +.IP (4) +If any key a keyring links to is itself a keyring, then rule (3) applies +recursively. +.IP (5) +If a process is upcalled from the kernel to instantiate a key (see +.BR request_key (2)), +then it also possesses the requester's keyrings as in +rule (1) as if it were the requester. +.PP +Note that possession is not a fundamental property of a key, +but must rather be calculated each time the key is needed. +.PP +Possession is designed to allow set-user-ID programs run from, say +a user's shell to access the user's keys. +Granting permissions to the key possessor while denying them +to the key owner and group allows the prevention of access to keys +on the basis of UID and GID matches. +.PP +When it creates the session keyring, +.BR pam_keyinit (8) +adds a link to the +.BR user-keyring (7), +thus making the user keyring and anything it contains possessed by default. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Access rights +Each key has the following security-related attributes: +.IP * 3 +The owning user ID +.IP * +The ID of a group that is permitted to access the key +.IP * +A security label +.IP * +A permissions mask +.PP +The permissions mask contains four sets of rights. +The first three sets are mutually exclusive. +One and only one will be in force for a particular access check. +In order of descending priority, these three sets are: +.IP \fIuser\fR +The set specifies the rights granted +if the key's user ID matches the caller's filesystem user ID. +.IP \fIgroup\fR +The set specifies the rights granted +if the user ID didn't match and the key's group ID matches the caller's +filesystem GID or one of the caller's supplementary group IDs. +.IP \fIother\fR +The set specifies the rights granted +if neither the key's user ID nor group ID matched. +.PP +The fourth set of rights is: +.IP \fIpossessor\fR +The set specifies the rights granted +if a key is determined to be possessed by the caller. +.PP +The complete set of rights for a key is the union of whichever +of the first three sets is applicable plus the fourth set +if the key is possessed. +.PP +The set of rights that may be granted in each of the four masks +is as follows: +.TP +.I view +The attributes of the key may be read. +This includes the type, +description, and access rights (excluding the security label). +.TP +.I read +For a key: the payload of the key may be read. +For a keyring: the list of serial numbers (keys) to +which the keyring has links may be read. +.TP +.I write +The payload of the key may be updated and the key may be revoked. +For a keyring, links may be added to or removed from the keyring, +and the keyring may be cleared completely (all links are removed), +.TP +.I search +For a key (or a keyring): the key may be found by a search. +For a keyring: keys and keyrings that are linked to by the +keyring may be searched. +.TP +.I link +Links may be created from keyrings to the key. +The initial link to a key that is established when the key is created +doesn't require this permission. +.TP +.I setattr +The ownership details and security label of the key may be changed, +the key's expiration time may be set, and the key may be revoked. +.PP +In addition to access rights, any active Linux Security Module (LSM) may +prevent access to a key if its policy so dictates. +A key may be given a +security label or other attribute by the LSM; +this label is retrievable via +.BR keyctl_get_security (3). +.PP +See +.BR keyctl_chown (3), +.BR keyctl_describe (3), +.BR keyctl_get_security (3), +.BR keyctl_setperm (3), +and +.BR selinux (8) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Searching for keys +One of the key features of the Linux key-management facility +is the ability to find a key that a process is retaining. +The +.BR request_key (2) +system call is the primary point of +access for user-space applications to find a key. +(Internally, the kernel has something similar available +for use by internal components that make use of keys.) +.PP +The search algorithm works as follows: +.IP (1) 4 +The process keyrings are searched in the following order: the thread +.BR thread-keyring (7) +if it exists, the +.BR process-keyring (7) +if it exists, and then either the +.BR session-keyring (7) +if it exists or the +.BR user-session-keyring (7) +if that exists. +.IP (2) +If the caller was a process that was invoked by the +.BR request_key (2) +upcall mechanism, then the keyrings of the original caller of +.BR request_key (2) +will be searched as well. +.IP (3) +The search of a keyring tree is in breadth-first order: +each keyring is searched first for a match, +then the keyrings referred to by that keyring are searched. +.IP (4) +If a matching key is found that is valid, +then the search terminates and that key is returned. +.IP (5) +If a matching key is found that has an error state attached, +that error state is noted and the search continues. +.IP (6) +If no valid matching key is found, +then the first noted error state is returned; otherwise, an +.B ENOKEY +error is returned. +.PP +It is also possible to search a specific keyring, in which case only steps +(3) to (6) apply. +.PP +See +.BR request_key (2) +and +.BR keyctl_search (3) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS On-demand key creation +If a key cannot be found, +.BR request_key (2) +will, if given a +.I callout_info +argument, create a new key and then upcall to user space to +instantiate the key. +This allows keys to be created on an as-needed basis. +.PP +Typically, +this will involve the kernel creating a new process that executes the +.BR request-key (8) +program, which will then execute the appropriate handler based on its +configuration. +.PP +The handler is passed a special authorization key that allows it +and only it to instantiate the new key. +This is also used to permit searches performed by the +handler program to also search the requester's keyrings. +.PP +See +.BR request_key (2), +.BR keyctl_assume_authority (3), +.BR keyctl_instantiate (3), +.BR keyctl_negate (3), +.BR keyctl_reject (3), +.BR request-key (8), +and +.BR request-key.conf (5) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS /proc files +The kernel provides various +.I /proc +files that expose information about keys or define limits on key usage. +.TP +.IR /proc/keys " (since Linux 2.6.10)" +This file exposes a list of the keys for which the reading thread has +.I view +permission, providing various information about each key. +The thread need not possess the key for it to be visible in this file. +.\" David Howells, Dec 2016 linux-man@: +.\" This [The thread need not possess the key for it to be visible in +.\" this file.] is correct. See proc_keys_show() in security/keys/proc.c: +.\" +.\" rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW); +.\" if (rc < 0) +.\" return 0; +.\" +.\"Possibly it shouldn't be, but for now it is. +.\" +.IP +The only keys included in the list are those that grant +.I view +permission to the reading process +(regardless of whether or not it possesses them). +LSM security checks are still performed, +and may filter out further keys that the process is not authorized to view. +.IP +An example of the data that one might see in this file +(with the columns numbered for easy reference below) +is the following: +.IP +.in 0n +.EX + (1) (2) (3)(4) (5) (6) (7) (8) (9) +009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12 +1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2 +25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1 +28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1 +2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2 +30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1 +32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2 +32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2 +3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1 +.EE +.in +.IP +The fields shown in each line of this file are as follows: +.RS +.TP +ID (1) +The ID (serial number) of the key, expressed in hexadecimal. +.TP +Flags (2) +A set of flags describing the state of the key: +.RS +.IP I 4 +.\" KEY_FLAG_INSTANTIATED +The key has been instantiated. +.IP R +.\" KEY_FLAG_REVOKED +The key has been revoked. +.IP D +.\" KEY_FLAG_DEAD +The key is dead (i.e., the key type has been unregistered). +.\" unregister_key_type() in the kernel source +(A key may be briefly in this state during garbage collection.) +.IP Q +.\" KEY_FLAG_IN_QUOTA +The key contributes to the user's quota. +.IP U +.\" KEY_FLAG_USER_CONSTRUCT +The key is under construction via a callback to user space; +see +.BR request-key (2). +.IP N +.\" KEY_FLAG_NEGATIVE +The key is negatively instantiated. +.IP i +.\" KEY_FLAG_INVALIDATED +The key has been invalidated. +.RE +.TP +Usage (3) +This is a count of the number of kernel credential +structures that are pinning the key +(approximately: the number of threads and open file references +that refer to this key). +.TP +Timeout (4) +The amount of time until the key will expire, +expressed in human-readable form (weeks, days, hours, minutes, and seconds). +The string +.I perm +here means that the key is permanent (no timeout). +The string +.I expd +means that the key has already expired, +but has not yet been garbage collected. +.TP +Permissions (5) +The key permissions, expressed as four hexadecimal bytes containing, +from left to right, the possessor, user, group, and other permissions. +Within each byte, the permission bits are as follows: +.IP +.PD 0 +.RS 12 +.TP +0x01 +.I view +.TP +Ox02 +.I read +.TP +0x04 +.I write +.TP +0x08 +.I search +.TP +0x10 +.I link +.TP +0x20 +.I setattr +.RE +.PD +.TP +UID (6) +The user ID of the key owner. +.TP +GID (7) +The group ID of the key. +The value \-1 here means that the key has no group ID; +this can occur in certain circumstances for keys created by the kernel. +.TP +Type (8) +The key type (user, keyring, etc.) +.TP +Description (9) +The key description (name). +This field contains descriptive information about the key. +For most key types, it has the form +.IP + name[: extra\-info] +.IP +The +.I name +subfield is the key's description (name). +The optional +.I extra\-info +field provides some further information about the key. +The information that appears here depends on the key type, as follows: +.RS +.TP 4 +.IR """user""" " and " """logon""" +The size in bytes of the key payload (expressed in decimal). +.TP +.IR """keyring""" +The number of keys linked to the keyring, +or the string +.IR empty +if there are no keys linked to the keyring. +.TP +.IR """big_key""" +The payload size in bytes, followed either by the string +.IR [file] , +if the key payload exceeds the threshold that means that the +payload is stored in a (swappable) +.BR tmpfs (5) +filesystem, +or otherwise the string +.IR [buff] , +indicating that the key is small enough to reside in kernel memory. +.RE +.IP +For the +.IR """.request_key_auth""" +key type +(authorization key; see +.BR request_key (2)), +the description field has the form shown in the following example: +.IP + key:c9a9b19 pid:28880 ci:10 +.IP +The three subfields are as follows: +.RS +.TP 5 +.I key +The hexadecimal ID of the key being instantiated in the requesting program. +.TP +.I pid +The PID of the requesting program. +.TP +.I ci +The length of the callout data with which the requested key should +be instantiated +(i.e., the length of the payload associated with the authorization key). +.RE +.RE +.TP +.IR /proc/key-users " (since Linux 2.6.10)" +This file lists various information for each user ID that +has at least one key on the system. +An example of the data that one might see in this file is the following: +.IP +.in +4n +.EX + 0: 10 9/9 2/1000000 22/25000000 + 42: 9 9/9 8/200 106/20000 +1000: 11 11/11 10/200 271/20000 +.EE +.in +.IP +The fields shown in each line are as follows: +.RS +.TP +.I uid +The user ID. +.TP +.I usage +This is a kernel-internal usage count for the kernel structure +used to record key users. +.TP +.IR nkeys / nikeys +The total number of keys owned by the user, +and the number of those keys that have been instantiated. +.TP +.IR qnkeys / maxkeys +The number of keys owned by the user, +and the maximum number of keys that the user may own. +.TP +.IR qnbytes / maxbytes +The number of bytes consumed in payloads of the keys owned by this user, +and the upper limit on the number of bytes in key payloads for that user. +.RE +.TP +.IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)" +.\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b +The value in this file specifies the interval, in seconds, +after which revoked and expired keys will be garbage collected. +The purpose of having such an interval is so that there is a window +of time where user space can see an error (respectively +.BR EKEYREVOKED +and +.BR EKEYEXPIRED ) +that indicates what happened to the key. +.IP +The default value in this file is 300 (i.e., 5 minutes). +.TP +.IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)" +.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e +This file defines an interval, in seconds, +to which the persistent keyring's expiration timer is reset +each time the keyring is accessed (via +.BR keyctl_get_persistent (3) +or the +.BR keyctl (2) +.B KEYCTL_GET_PERSISTENT +operation.) +.IP +The default value in this file is 259200 (i.e., 3 days). +.PP +The following files (which are writable by privileged processes) +are used to enforce quotas on the number of keys +and number of bytes of data that can be stored in key payloads: +.TP +.IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)" +.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 +.\" Previously: KEYQUOTA_MAX_BYTES 10000 +This is the maximum number of bytes of data that a nonroot user +can hold in the payloads of the keys owned by the user. +.IP +The default value in this file is 20,000. +.TP +.IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)" +.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 +.\" Previously: KEYQUOTA_MAX_KEYS 100 +This is the maximum number of keys that a nonroot user may own. +.IP +The default value in this file is 200. +.TP +.IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)" +This is the maximum number of bytes of data that the root user +(UID 0 in the root user namespace) +can hold in the payloads of the keys owned by root. +.IP +.\"738c5d190f6540539a04baf36ce21d46b5da04bd +The default value in this file is 25,000,000 (20,000 before Linux 3.17). +.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 +.TP +.IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)" +.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 +This is the maximum number of keys that the root user +(UID 0 in the root user namespace) +may own. +.IP +.\"738c5d190f6540539a04baf36ce21d46b5da04bd +The default value in this file is 1,000,000 (200 before Linux 3.17). +.PP +With respect to keyrings, +note that each link in a keyring consumes 4 bytes of the keyring payload. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Users +The Linux key-management facility has a number of users and usages, +but is not limited to those that already exist. +.PP +In-kernel users of this facility include: +.TP +Network filesystems - DNS +The kernel uses the upcall mechanism provided by the keys to upcall to +user space to do DNS lookups and then to cache the results. +.TP +AF_RXRPC and kAFS - Authentication +The AF_RXRPC network protocol and the in-kernel AFS filesystem +use keys to store the ticket needed to do secured or encrypted traffic. +These are then looked up by +network operations on AF_RXRPC and filesystem operations on kAFS. +.TP +NFS - User ID mapping +The NFS filesystem uses keys to store mappings of +foreign user IDs to local user IDs. +.TP +CIFS - Password +The CIFS filesystem uses keys to store passwords for accessing remote shares. +.TP +Module verification +The kernel build process can be made to cryptographically sign modules. +That signature is then checked when a module is loaded. +.PP +User-space users of this facility include: +.TP +Kerberos key storage +The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication +tokens which can be made to be automatically cleaned up a set time after +the user last uses them, +but until then permits them to hang around after the user +has logged out so that +.BR cron (8) +scripts can use them. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyutils (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7), +.BR pam_keyinit (8), +.BR request-key (8) +.PP +The kernel source files +.IR Documentation/crypto/asymmetric-keys.txt +and under +.IR Documentation/security/keys +(or, before Linux 4.13, in the file +.IR Documentation/security/keys.txt ). +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/koi8-r.7 b/man7/koi8-r.7 new file mode 100644 index 0000000..6442bb8 --- /dev/null +++ b/man7/koi8-r.7 @@ -0,0 +1,197 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2001 Alexey Mahotkin +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH KOI8-R 7 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +koi8-r \- Russian character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +RFC\ 1489 defines an 8-bit character set, KOI8-R. +KOI8-R encodes the +characters used in Russian. +.SS KOI8-R characters +The following table displays the characters in KOI8-R that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 ─ BOX DRAWINGS LIGHT HORIZONTAL +201 129 81 │ BOX DRAWINGS LIGHT VERTICAL +202 130 82 ┌ BOX DRAWINGS LIGHT DOWN AND RIGHT +203 131 83 ┐ BOX DRAWINGS LIGHT DOWN AND LEFT +204 132 84 └ BOX DRAWINGS LIGHT UP AND RIGHT +205 133 85 ┘ BOX DRAWINGS LIGHT UP AND LEFT +206 134 86 ├ BOX DRAWINGS LIGHT VERTICAL AND RIGHT +207 135 87 ┤ BOX DRAWINGS LIGHT VERTICAL AND LEFT +210 136 88 ┬ BOX DRAWINGS LIGHT DOWN AND HORIZONTAL +211 137 89 ┴ BOX DRAWINGS LIGHT UP AND HORIZONTAL +212 138 8A ┼ BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL +213 139 8B ▀ UPPER HALF BLOCK +214 140 8C ▄ LOWER HALF BLOCK +215 141 8D █ FULL BLOCK +216 142 8E ▌ LEFT HALF BLOCK +217 143 8F ▐ RIGHT HALF BLOCK +220 144 90 ░ LIGHT SHADE +221 145 91 ▒ MEDIUM SHADE +222 146 92 ▓ DARK SHADE +223 147 93 ⌠ TOP HALF INTEGRAL +224 148 94 ■ BLACK SQUARE +225 149 95 ∙ BULLET OPERATOR +226 150 96 √ SQUARE ROOT +227 151 97 ≈ ALMOST EQUAL TO +230 152 98 ≤ LESS-THAN OR EQUAL TO +231 153 99 ≥ GREATER-THAN OR EQUAL TO +232 154 9A   NO-BREAK SPACE +233 155 9B ⌡ BOTTOM HALF INTEGRAL +234 156 9C ° DEGREE SIGN +235 157 9D ² SUPERSCRIPT TWO +236 158 9E · MIDDLE DOT +237 159 9F ÷ DIVISION SIGN +240 160 A0 ═ BOX DRAWINGS DOUBLE HORIZONTAL +241 161 A1 ║ BOX DRAWINGS DOUBLE VERTICAL +242 162 A2 ╒ BOX DRAWINGS DOWN SINGLE AND RIGHT DOUBLE +243 163 A3 ё CYRILLIC SMALL LETTER IO +244 164 A4 ╓ BOX DRAWINGS DOWN DOUBLE AND RIGHT SINGLE +245 165 A5 ╔ BOX DRAWINGS DOUBLE DOWN AND RIGHT +246 166 A6 ╕ BOX DRAWINGS DOWN SINGLE AND LEFT DOUBLE +247 167 A7 ╖ BOX DRAWINGS DOWN DOUBLE AND LEFT SINGLE +250 168 A8 ╗ BOX DRAWINGS DOUBLE DOWN AND LEFT +251 169 A9 ╘ BOX DRAWINGS UP SINGLE AND RIGHT DOUBLE +252 170 AA ╙ BOX DRAWINGS UP DOUBLE AND RIGHT SINGLE +253 171 AB ╚ BOX DRAWINGS DOUBLE UP AND RIGHT +254 172 AC ╛ BOX DRAWINGS UP SINGLE AND LEFT DOUBLE +255 173 AD ╜ BOX DRAWINGS UP DOUBLE AND LEFT SINGLE +256 174 AE ╝ BOX DRAWINGS DOUBLE UP AND LEFT +257 175 AF ╞ BOX DRAWINGS VERTICAL SINGLE AND RIGHT DOUBLE +260 176 B0 ╟ BOX DRAWINGS VERTICAL DOUBLE AND RIGHT SINGLE +261 177 B1 ╠ BOX DRAWINGS DOUBLE VERTICAL AND RIGHT +262 178 B2 ╡ BOX DRAWINGS VERTICAL SINGLE AND LEFT DOUBLE +263 179 B3 Ё CYRILLIC CAPITAL LETTER IO +264 180 B4 ╢ BOX DRAWINGS VERTICAL DOUBLE AND LEFT SINGLE +265 181 B5 ╣ BOX DRAWINGS DOUBLE VERTICAL AND LEFT +266 182 B6 ╤ BOX DRAWINGS DOWN SINGLE AND HORIZONTAL DOUBLE +267 183 B7 ╥ BOX DRAWINGS DOWN DOUBLE AND HORIZONTAL SINGLE +270 184 B8 ╦ BOX DRAWINGS DOUBLE DOWN AND HORIZONTAL +271 185 B9 ╧ BOX DRAWINGS UP SINGLE AND HORIZONTAL DOUBLE +272 186 BA ╨ BOX DRAWINGS UP DOUBLE AND HORIZONTAL SINGLE +273 187 BB ╩ BOX DRAWINGS DOUBLE UP AND HORIZONTAL +274 188 BC ╪ T{ +BOX DRAWINGS VERTICAL SINGLE +.br +AND HORIZONTAL DOUBLE +T} +275 189 BD ╫ T{ +BOX DRAWINGS VERTICAL DOUBLE +.br +AND HORIZONTAL SINGLE +T} +276 190 BE ╬ BOX DRAWINGS DOUBLE VERTICAL AND HORIZONTAL +277 191 BF © COPYRIGHT SIGN +300 192 C0 ю CYRILLIC SMALL LETTER YU +301 193 C1 а CYRILLIC SMALL LETTER A +302 194 C2 б CYRILLIC SMALL LETTER BE +303 195 C3 ц CYRILLIC SMALL LETTER TSE +304 196 C4 д CYRILLIC SMALL LETTER DE +305 197 C5 е CYRILLIC SMALL LETTER IE +306 198 C6 ф CYRILLIC SMALL LETTER EF +307 199 C7 г CYRILLIC SMALL LETTER GHE +310 200 C8 х CYRILLIC SMALL LETTER HA +311 201 C9 и CYRILLIC SMALL LETTER I +312 202 CA й CYRILLIC SMALL LETTER SHORT I +313 203 CB к CYRILLIC SMALL LETTER KA +314 204 CC л CYRILLIC SMALL LETTER EL +315 205 CD м CYRILLIC SMALL LETTER EM +316 206 CE н CYRILLIC SMALL LETTER EN +317 207 CF о CYRILLIC SMALL LETTER O +320 208 D0 п CYRILLIC SMALL LETTER PE +321 209 D1 я CYRILLIC SMALL LETTER YA +322 210 D2 р CYRILLIC SMALL LETTER ER +323 211 D3 с CYRILLIC SMALL LETTER ES +324 212 D4 т CYRILLIC SMALL LETTER TE +325 213 D5 у CYRILLIC SMALL LETTER U +326 214 D6 ж CYRILLIC SMALL LETTER ZHE +327 215 D7 в CYRILLIC SMALL LETTER VE +330 216 D8 ь CYRILLIC SMALL LETTER SOFT SIGN +331 217 D9 ы CYRILLIC SMALL LETTER YERU +332 218 DA з CYRILLIC SMALL LETTER ZE +333 219 DB ш CYRILLIC SMALL LETTER SHA +334 220 DC э CYRILLIC SMALL LETTER E +335 221 DD щ CYRILLIC SMALL LETTER SHCHA +336 222 DE ч CYRILLIC SMALL LETTER CHE +337 223 DF ъ CYRILLIC SMALL LETTER HARD SIGN +340 224 E0 Ю CYRILLIC CAPITAL LETTER YU +341 225 E1 А CYRILLIC CAPITAL LETTER A +342 226 E2 Б CYRILLIC CAPITAL LETTER BE +343 227 E3 Ц CYRILLIC CAPITAL LETTER TSE +344 228 E4 Д CYRILLIC CAPITAL LETTER DE +345 229 E5 Е CYRILLIC CAPITAL LETTER IE +346 230 E6 Ф CYRILLIC CAPITAL LETTER EF +347 231 E7 Г CYRILLIC CAPITAL LETTER GHE +350 232 E8 Х CYRILLIC CAPITAL LETTER HA +351 233 E9 И CYRILLIC CAPITAL LETTER I +352 234 EA Й CYRILLIC CAPITAL LETTER SHORT I +353 235 EB К CYRILLIC CAPITAL LETTER KA +354 236 EC Л CYRILLIC CAPITAL LETTER EL +355 237 ED М CYRILLIC CAPITAL LETTER EM +356 238 EE Н CYRILLIC CAPITAL LETTER EN +357 239 EF О CYRILLIC CAPITAL LETTER O +360 240 F0 П CYRILLIC CAPITAL LETTER PE +361 241 F1 Я CYRILLIC CAPITAL LETTER YA +362 242 F2 Р CYRILLIC CAPITAL LETTER ER +363 243 F3 С CYRILLIC CAPITAL LETTER ES +364 244 F4 Т CYRILLIC CAPITAL LETTER TE +365 245 F5 У CYRILLIC CAPITAL LETTER U +366 246 F6 Ж CYRILLIC CAPITAL LETTER ZHE +367 247 F7 В CYRILLIC CAPITAL LETTER VE +370 248 F8 Ь CYRILLIC CAPITAL LETTER SOFT SIGN +371 249 F9 Ы CYRILLIC CAPITAL LETTER YERU +372 250 FA З CYRILLIC CAPITAL LETTER ZE +373 251 FB Ш CYRILLIC CAPITAL LETTER SHA +374 252 FC Э CYRILLIC CAPITAL LETTER E +375 253 FD Щ CYRILLIC CAPITAL LETTER SHCHA +376 254 FE Ч CYRILLIC CAPITAL LETTER CHE +377 255 FF Ъ CYRILLIC CAPITAL LETTER HARD SIGN +.TE +.SH NOTES +The differences with KOI8-U are in the hex positions +A4, A6, A7, AD, B4, B6, B7, and BD. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1251 (7), +.BR iso_8859-5 (7), +.BR koi8-u (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/koi8-u.7 b/man7/koi8-u.7 new file mode 100644 index 0000000..b5bdae6 --- /dev/null +++ b/man7/koi8-u.7 @@ -0,0 +1,203 @@ +'\" t -*- coding: UTF-8 -*- +.\" Copyright 2009 Lefteris Dimitroulakis +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2009-01-15, mtk, Some edits +.\" +.TH KOI8-U 7 2016-07-17 "Linux" "Linux Programmer's Manual" +.SH NAME +koi8-u \- Ukrainian character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +RFC\ 2310 defines an 8-bit character set, KOI8-U. +KOI8-U encodes the +characters used in Ukrainian and Byelorussian. +.SS KOI8-U characters +The following table displays the characters in KOI8-U that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 ─ BOX DRAWINGS LIGHT HORIZONTAL +201 129 81 │ BOX DRAWINGS LIGHT VERTICAL +202 130 82 ┌ BOX DRAWINGS LIGHT DOWN AND RIGHT +203 131 83 ┐ BOX DRAWINGS LIGHT DOWN AND LEFT +204 132 84 └ BOX DRAWINGS LIGHT UP AND RIGHT +205 133 85 ┘ BOX DRAWINGS LIGHT UP AND LEFT +206 134 86 ├ BOX DRAWINGS LIGHT VERTICAL AND RIGHT +207 135 87 ┤ BOX DRAWINGS LIGHT VERTICAL AND LEFT +210 136 88 ┬ BOX DRAWINGS LIGHT DOWN AND HORIZONTAL +211 137 89 ┴ BOX DRAWINGS LIGHT UP AND HORIZONTAL +212 138 8A ┼ BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL +213 139 8B ▀ UPPER HALF BLOCK +214 140 8C ▄ LOWER HALF BLOCK +215 141 8D █ FULL BLOCK +216 142 8E ▌ LEFT HALF BLOCK +217 143 8F ▐ RIGHT HALF BLOCK +220 144 90 ░ LIGHT SHADE +221 145 91 ▒ MEDIUM SHADE +222 146 92 ▓ DARK SHADE +223 147 93 ⌠ TOP HALF INTEGRAL +224 148 94 ■ BLACK SQUARE +225 149 95 ∙ BULLET OPERATOR +226 150 96 √ SQUARE ROOT +227 151 97 ≈ ALMOST EQUAL TO +230 152 98 ≤ LESS-THAN OR EQUAL TO +231 153 99 ≥ GREATER-THAN OR EQUAL TO +232 154 9A   NO-BREAK SPACE +233 155 9B ⌡ BOTTOM HALF INTEGRAL +234 156 9C ° DEGREE SIGN +235 157 9D ² SUPERSCRIPT TWO +236 158 9E · MIDDLE DOT +237 159 9F ÷ DIVISION SIGN +240 160 A0 ═ BOX DRAWINGS DOUBLE HORIZONTAL +241 161 A1 ║ BOX DRAWINGS DOUBLE VERTICAL +242 162 A2 ╒ BOX DRAWINGS DOWN SINGLE AND RIGHT DOUBLE +243 163 A3 ё CYRILLIC SMALL LETTER IO +244 164 A4 є CYRILLIC SMALL LETTER UKRAINIAN IE +245 165 A5 ╔ BOX DRAWINGS DOUBLE DOWN AND RIGHT +246 166 A6 і T{ +CYRILLIC SMALL LETTER +.br +BYELORUSSIAN-UKRAINIAN I +T} +247 167 A7 ї CYRILLIC SMALL LETTER YI (Ukrainian) +250 168 A8 ╗ BOX DRAWINGS DOUBLE DOWN AND LEFT +251 169 A9 ╘ BOX DRAWINGS UP SINGLE AND RIGHT DOUBLE +252 170 AA ╙ BOX DRAWINGS UP DOUBLE AND RIGHT SINGLE +253 171 AB ╚ BOX DRAWINGS DOUBLE UP AND RIGHT +254 172 AC ╛ BOX DRAWINGS UP SINGLE AND LEFT DOUBLE +255 173 AD ґ CYRILLIC SMALL LETTER GHE WITH UPTURN +256 174 AE ╝ BOX DRAWINGS DOUBLE UP AND LEFT +257 175 AF ╞ BOX DRAWINGS VERTICAL SINGLE AND RIGHT DOUBLE +260 176 B0 ╟ BOX DRAWINGS VERTICAL DOUBLE AND RIGHT SINGLE +261 177 B1 ╠ BOX DRAWINGS DOUBLE VERTICAL AND RIGHT +262 178 B2 ╡ BOX DRAWINGS VERTICAL SINGLE AND LEFT DOUBLE +263 179 B3 Ё CYRILLIC CAPITAL LETTER IO +264 180 B4 Є CYRILLIC CAPITAL LETTER UKRAINIAN IE +265 181 B5 ╣ BOX DRAWINGS DOUBLE VERTICAL AND LEFT +266 182 B6 І T{ +CYRILLIC CAPITAL LETTER +.br +BYELORUSSIAN-UKRAINIAN I +T} +267 183 B7 Ї CYRILLIC CAPITAL LETTER YI (Ukrainian) +270 184 B8 ╦ BOX DRAWINGS DOUBLE DOWN AND HORIZONTAL +271 185 B9 ╧ BOX DRAWINGS UP SINGLE AND HORIZONTAL DOUBLE +272 186 BA ╨ BOX DRAWINGS UP DOUBLE AND HORIZONTAL SINGLE +273 187 BB ╩ BOX DRAWINGS DOUBLE UP AND HORIZONTAL +274 188 BC ╪ T{ +BOX DRAWINGS VERTICAL SINGLE +.br +AND HORIZONTAL DOUBLE +T} +275 189 BD Ґ CYRILLIC CAPITAL LETTER GHE WITH UPTURN +276 190 BE ╬ BOX DRAWINGS DOUBLE VERTICAL AND HORIZONTAL +277 191 BF © COPYRIGHT SIGN +300 192 C0 ю CYRILLIC SMALL LETTER YU +301 193 C1 а CYRILLIC SMALL LETTER A +302 194 C2 б CYRILLIC SMALL LETTER BE +303 195 C3 ц CYRILLIC SMALL LETTER TSE +304 196 C4 д CYRILLIC SMALL LETTER DE +305 197 C5 е CYRILLIC SMALL LETTER IE +306 198 C6 ф CYRILLIC SMALL LETTER EF +307 199 C7 г CYRILLIC SMALL LETTER GHE +310 200 C8 х CYRILLIC SMALL LETTER HA +311 201 C9 и CYRILLIC SMALL LETTER I +312 202 CA й CYRILLIC SMALL LETTER SHORT I +313 203 CB к CYRILLIC SMALL LETTER KA +314 204 CC л CYRILLIC SMALL LETTER EL +315 205 CD м CYRILLIC SMALL LETTER EM +316 206 CE н CYRILLIC SMALL LETTER EN +317 207 CF о CYRILLIC SMALL LETTER O +320 208 D0 п CYRILLIC SMALL LETTER PE +321 209 D1 я CYRILLIC SMALL LETTER YA +322 210 D2 р CYRILLIC SMALL LETTER ER +323 211 D3 с CYRILLIC SMALL LETTER ES +324 212 D4 т CYRILLIC SMALL LETTER TE +325 213 D5 у CYRILLIC SMALL LETTER U +326 214 D6 ж CYRILLIC SMALL LETTER ZHE +327 215 D7 в CYRILLIC SMALL LETTER VE +330 216 D8 ь CYRILLIC SMALL LETTER SOFT SIGN +331 217 D9 ы CYRILLIC SMALL LETTER YERU +332 218 DA з CYRILLIC SMALL LETTER ZE +333 219 DB ш CYRILLIC SMALL LETTER SHA +334 220 DC э CYRILLIC SMALL LETTER E +335 221 DD щ CYRILLIC SMALL LETTER SHCHA +336 222 DE ч CYRILLIC SMALL LETTER CHE +337 223 DF ъ CYRILLIC SMALL LETTER HARD SIGN +340 224 E0 Ю CYRILLIC CAPITAL LETTER YU +341 225 E1 А CYRILLIC CAPITAL LETTER A +342 226 E2 Б CYRILLIC CAPITAL LETTER BE +343 227 E3 Ц CYRILLIC CAPITAL LETTER TSE +344 228 E4 Д CYRILLIC CAPITAL LETTER DE +345 229 E5 Е CYRILLIC CAPITAL LETTER IE +346 230 E6 Ф CYRILLIC CAPITAL LETTER EF +347 231 E7 Г CYRILLIC CAPITAL LETTER GHE +350 232 E8 Х CYRILLIC CAPITAL LETTER HA +351 233 E9 И CYRILLIC CAPITAL LETTER I +352 234 EA Й CYRILLIC CAPITAL LETTER SHORT I +353 235 EB К CYRILLIC CAPITAL LETTER KA +354 236 EC Л CYRILLIC CAPITAL LETTER EL +355 237 ED М CYRILLIC CAPITAL LETTER EM +356 238 EE Н CYRILLIC CAPITAL LETTER EN +357 239 EF О CYRILLIC CAPITAL LETTER O +360 240 F0 П CYRILLIC CAPITAL LETTER PE +361 241 F1 Я CYRILLIC CAPITAL LETTER YA +362 242 F2 Р CYRILLIC CAPITAL LETTER ER +363 243 F3 С CYRILLIC CAPITAL LETTER ES +364 244 F4 Т CYRILLIC CAPITAL LETTER TE +365 245 F5 У CYRILLIC CAPITAL LETTER U +366 246 F6 Ж CYRILLIC CAPITAL LETTER ZHE +367 247 F7 В CYRILLIC CAPITAL LETTER VE +370 248 F8 Ь CYRILLIC CAPITAL LETTER SOFT SIGN +371 249 F9 Ы CYRILLIC CAPITAL LETTER YERU +372 250 FA З CYRILLIC CAPITAL LETTER ZE +373 251 FB Ш CYRILLIC CAPITAL LETTER SHA +374 252 FC Э CYRILLIC CAPITAL LETTER E +375 253 FD Щ CYRILLIC CAPITAL LETTER SHCHA +376 254 FE Ч CYRILLIC CAPITAL LETTER CHE +377 255 FF Ъ CYRILLIC CAPITAL LETTER HARD SIGN +.TE +.SH NOTES +The differences from KOI8-R are in the hex positions +A4, A6, A7, AD, B4, B6, B7, and BD. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1251 (7), +.BR iso_8859-5 (7), +.BR koi8-r (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/latin1.7 b/man7/latin1.7 new file mode 100644 index 0000000..1969dfb --- /dev/null +++ b/man7/latin1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man7/latin10.7 b/man7/latin10.7 new file mode 100644 index 0000000..b9c8e91 --- /dev/null +++ b/man7/latin10.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man7/latin2.7 b/man7/latin2.7 new file mode 100644 index 0000000..da36668 --- /dev/null +++ b/man7/latin2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man7/latin3.7 b/man7/latin3.7 new file mode 100644 index 0000000..75e42ce --- /dev/null +++ b/man7/latin3.7 @@ -0,0 +1 @@ +.so man7/iso_8859-3.7 diff --git a/man7/latin4.7 b/man7/latin4.7 new file mode 100644 index 0000000..15a829e --- /dev/null +++ b/man7/latin4.7 @@ -0,0 +1 @@ +.so man7/iso_8859-4.7 diff --git a/man7/latin5.7 b/man7/latin5.7 new file mode 100644 index 0000000..0fcc7d4 --- /dev/null +++ b/man7/latin5.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man7/latin6.7 b/man7/latin6.7 new file mode 100644 index 0000000..9b4658f --- /dev/null +++ b/man7/latin6.7 @@ -0,0 +1 @@ +.so man7/iso_8859-10.7 diff --git a/man7/latin7.7 b/man7/latin7.7 new file mode 100644 index 0000000..8ad2335 --- /dev/null +++ b/man7/latin7.7 @@ -0,0 +1 @@ +.so man7/iso_8859-13.7 diff --git a/man7/latin8.7 b/man7/latin8.7 new file mode 100644 index 0000000..4aa555d --- /dev/null +++ b/man7/latin8.7 @@ -0,0 +1 @@ +.so man7/iso_8859-14.7 diff --git a/man7/latin9.7 b/man7/latin9.7 new file mode 100644 index 0000000..a4095d7 --- /dev/null +++ b/man7/latin9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man7/libc.7 b/man7/libc.7 new file mode 100644 index 0000000..fe90fcd --- /dev/null +++ b/man7/libc.7 @@ -0,0 +1,131 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH LIBC 7 2016-12-12 "Linux" "Linux Programmer's Manual" +.SH NAME +libc \- overview of standard C libraries on Linux +.SH DESCRIPTION +The term "libc" is commonly used as a shorthand for +the "standard C library", +a library of standard functions that can be used by all C programs +(and sometimes by programs in other languages). +Because of some history (see below), use of the term "libc" +to refer to the standard C library is somewhat ambiguous on Linux. +.SS glibc +By far the most widely used C library on Linux is the GNU C Library +.UR http://www.gnu.org\:/software\:/libc/ +.UE , +often referred to as +.IR glibc . +This is the C library that is nowadays used in all +major Linux distributions. +It is also the C library whose details are documented +in the relevant pages of the +.I man-pages +project (primarily in Section 3 of the manual). +Documentation of glibc is also available in the glibc manual, +available via the command +.IR "info libc" . +Release 1.0 of glibc was made in September 1992. +(There were earlier 0.x releases.) +The next major release of glibc was 2.0, at the beginning of 1997. +.PP +The pathname +.I /lib/libc.so.6 +(or something similar) is normally a symbolic link that +points to the location of the glibc library, +and executing this pathname will cause glibc to display +various information about the version installed on your system. +.SS Linux libc +In the early to mid 1990s, there was for a while +.IR "Linux libc" , +a fork of glibc 1.x created by Linux developers who felt that glibc +development at the time was not sufficing for the needs of Linux. +Often, this library was referred to (ambiguously) as just "libc". +Linux libc released major versions 2, 3, 4, and 5, +as well as many minor versions of those releases. +Linux libc4 was the last version to use the a.out binary format, +and the first version to provide (primitive) shared library support. +Linux libc 5 was the first version to support the ELF binary format; +this version used the shared library soname +.IR libc.so.5 . +For a while, +Linux libc was the standard C library in many Linux distributions. +.PP +However, notwithstanding the original motivations of the Linux libc effort, +by the time glibc 2.0 was released (in 1997), +it was clearly superior to Linux libc, +and all major Linux distributions that had been using Linux libc +soon switched back to glibc. +To avoid any confusion with Linux libc versions, +glibc 2.0 and later used the shared library soname +.IR libc.so.6 . +.PP +Since the switch from Linux libc to glibc 2.0 occurred long ago, +.I man-pages +no longer takes care to document Linux libc details. +Nevertheless, the history is visible in vestiges of information +about Linux libc that remain in a few manual pages, +in particular, references to +.IR libc4 +and +.IR libc5 . +.SS Other C libraries +There are various other less widely used C libraries for Linux. +These libraries are generally smaller than glibc, +both in terms of features and memory footprint, +and often intended for building small binaries, +perhaps targeted at development for embedded Linux systems. +Among such libraries are +.UR http://www.uclibc.org/ +.I uClibc +.UE , +.UR http://www.fefe.de/dietlibc/ +.I dietlibc +.UE , +and +.UR http://www.musl\-libc.org/ +.I "musl libc" +.UE . +Details of these libraries are covered by the +.I man-pages +project, where they are known. +.SH SEE ALSO +.BR syscalls (2), +.BR getauxval (3), +.BR proc (5), +.BR feature_test_macros (7), +.BR man-pages (7), +.BR standards (7), +.BR vdso (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/locale.7 b/man7/locale.7 new file mode 100644 index 0000000..a962738 --- /dev/null +++ b/man7/locale.7 @@ -0,0 +1,409 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (C) 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:28:34 1993 by Rik Faith +.\" Modified Sun Jun 01 17:16:34 1997 by Jochen Hein +.\" +.\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible +.\" +.TH LOCALE 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +locale \- description of multilanguage support +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +A locale is a set of language and cultural rules. +These cover aspects +such as language for messages, different character sets, lexicographic +conventions, and so on. +A program needs to be able to determine its locale +and act accordingly to be portable to different cultures. +.PP +The header +.I +declares data types, functions and macros which are useful in this +task. +.PP +The functions it declares are +.BR setlocale (3) +to set the current locale, and +.BR localeconv (3) +to get information about number formatting. +.PP +There are different categories for locale information a program might +need; they are declared as macros. +Using them as the first argument +to the +.BR setlocale (3) +function, it is possible to set one of these to the desired locale: +.TP +.BR LC_ADDRESS " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change settings that describe the formats (e.g., postal addresses) +used to describe locations and geography-related items. +Applications that need this information can use +.BR nl_langinfo (3) +to retrieve nonstandard elements, such as +.B _NL_ADDRESS_COUNTRY_NAME +(country name, in the language of the locale) +and +.B _NL_ADDRESS_LANG_NAME +(language name, in the language of the locale), +which return strings such as "Deutschland" and "Deutsch" +(for German-language locales). +(Other element names are listed in +.IR .) +.TP +.B LC_COLLATE +This category governs the collation rules used for +sorting and regular expressions, +including character equivalence classes and +multicharacter collating elements. +This locale category changes the behavior of the functions +.BR strcoll (3) +and +.BR strxfrm (3), +which are used to compare strings in the local alphabet. +For example, +the German sharp s is sorted as "ss". +.TP +.B LC_CTYPE +This category determines the interpretation of byte sequences as characters +(e.g., single versus multibyte characters), character classifications +(e.g., alphabetic or digit), and the behavior of character classes. +On glibc systems, this category also determines +the character transliteration rules for +.BR iconv (1) +and +.BR iconv (3). +It changes the behavior of the character handling and +classification functions, such as +.BR isupper (3) +and +.BR toupper (3), +and the multibyte character functions such as +.BR mblen (3) +or +.BR wctomb (3). +.TP +.BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change settings that relate to the metadata for the locale. +Applications that need this information can use +.BR nl_langinfo (3) +to retrieve nonstandard elements, such as +.B _NL_IDENTIFICATION_TITLE +(title of this locale document) +and +.B _NL_IDENTIFICATION_TERRITORY +(geographical territory to which this locale document applies), +which might return strings such as "English locale for the USA" +and "USA". +(Other element names are listed in +.IR .) +.TP +.B LC_MONETARY +This category determines the formatting used for +monetary-related numeric values. +This changes the information returned by +.BR localeconv (3), +which describes the way numbers are usually printed, with details such +as decimal point versus decimal comma. +This information is internally +used by the function +.BR strfmon (3). +.TP +.B LC_MESSAGES +This category affects the language in which messages are displayed +and what an affirmative or negative answer looks like. +The GNU C library contains the +.BR gettext (3), +.BR ngettext (3), +and +.BR rpmatch (3) +functions to ease the use of this information. +The GNU gettext family of +functions also obey the environment variable +.BR LANGUAGE +(containing a colon-separated list of locales) +if the category is set to a valid locale other than +.BR """C""" . +This category also affects the behavior of +.BR catopen (3). +.TP +.BR LC_MEASUREMENT " (GNU extension, since glibc 2.2)" +Change the settings relating to the measurement system in the locale +(i.e., metric versus US customary units). +Applications can use +.BR nl_langinfo (3) +to retrieve the nonstandard +.B _NL_MEASUREMENT_MEASUREMENT +element, which returns a pointer to a character +that has the value 1 (metric) or 2 (US customary units). +.TP +.BR LC_NAME " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change settings that describe the formats used to address persons. +Applications that need this information can use +.BR nl_langinfo (3) +to retrieve nonstandard elements, such as +.B _NL_NAME_NAME_MR +(general salutation for men) +and +.B _NL_NAME_NAME_MS +(general salutation for women) +elements, which return strings such as "Herr" and "Frau" +(for German-language locales). +(Other element names are listed in +.IR .) +.TP +.B LC_NUMERIC +This category determines the formatting rules used for nonmonetary +numeric values\(emfor example, +the thousands separator and the radix character +(a period in most English-speaking countries, +but a comma in many other regions). +It affects functions such as +.BR printf (3), +.BR scanf (3), +and +.BR strtod (3). +This information can also be read with the +.BR localeconv (3) +function. +.TP +.BR LC_PAPER " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change the settings relating to the dimensions of the standard paper size +(e.g., US letter versus A4). +Applications that need the dimensions can obtain them by using +.BR nl_langinfo (3) +to retrieve the nonstandard +.B _NL_PAPER_WIDTH +and +.B _NL_PAPER_HEIGHT +elements, which return +.I int +values specifying the dimensions in millimeters. +.TP +.BR LC_TELEPHONE " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change settings that describe the formats to be used with telephone services. +Applications that need this information can use +.BR nl_langinfo (3) +to retrieve nonstandard elements, such as +.B _NL_TELEPHONE_INT_PREFIX +(international prefix used to call numbers in this locale), +which returns a string such as "49" (for Germany). +(Other element names are listed in +.IR .) +.TP +.B LC_TIME +This category governs the formatting used for date and time values. +For example, most of Europe uses a 24-hour clock versus the +12-hour clock used in the United States. +The setting of this category affects the behavior of functions such as +.BR strftime (3) +and +.BR strptime (3). +.TP +.B LC_ALL +All of the above. +.PP +If the second argument to +.BR setlocale (3) +is an empty string, +.BR """""" , +for the default locale, it is determined using the following steps: +.IP 1. 3 +If there is a non-null environment variable +.BR LC_ALL , +the value of +.B LC_ALL +is used. +.IP 2. +If an environment variable with the same name as one of the categories +above exists and is non-null, its value is used for that category. +.IP 3. +If there is a non-null environment variable +.BR LANG , +the value of +.B LANG +is used. +.PP +Values about local numeric formatting is made available in a +.I struct lconv +returned by the +.BR localeconv (3) +function, which has the following declaration: +.PP +.in +4n +.EX +struct lconv { + + /* Numeric (nonmonetary) information */ + + char *decimal_point; /* Radix character */ + char *thousands_sep; /* Separator for digit groups to left + of radix character */ + char *grouping; /* Each element is the number of digits in + a group; elements with higher indices + are further left. An element with value + CHAR_MAX means that no further grouping + is done. An element with value 0 means + that the previous element is used for + all groups further left. */ + + /* Remaining fields are for monetary information */ + + char *int_curr_symbol; /* First three chars are a currency + symbol from ISO 4217. Fourth char + is the separator. Fifth char + is \(aq\\0\(aq. */ + char *currency_symbol; /* Local currency symbol */ + char *mon_decimal_point; /* Radix character */ + char *mon_thousands_sep; /* Like \fIthousands_sep\fP above */ + char *mon_grouping; /* Like \fIgrouping\fP above */ + char *positive_sign; /* Sign for positive values */ + char *negative_sign; /* Sign for negative values */ + char int_frac_digits; /* International fractional digits */ + char frac_digits; /* Local fractional digits */ + char p_cs_precedes; /* 1 if currency_symbol precedes a + positive value, 0 if succeeds */ + char p_sep_by_space; /* 1 if a space separates + currency_symbol from a positive + value */ + char n_cs_precedes; /* 1 if currency_symbol precedes a + negative value, 0 if succeeds */ + char n_sep_by_space; /* 1 if a space separates + currency_symbol from a negative + value */ + /* Positive and negative sign positions: + 0 Parentheses surround the quantity and currency_symbol. + 1 The sign string precedes the quantity and currency_symbol. + 2 The sign string succeeds the quantity and currency_symbol. + 3 The sign string immediately precedes the currency_symbol. + 4 The sign string immediately succeeds the currency_symbol. */ + char p_sign_posn; + char n_sign_posn; +}; +.EE +.in +.SS POSIX.1-2008 extensions to the locale API +POSIX.1-2008 standardized a number of extensions to the locale API, +based on implementations that first appeared in version 2.3 +of the GNU C library. +These extensions are designed to address the problem that +the traditional locale APIs do not mix well with multithreaded applications +and with applications that must deal with multiple locales. +.PP +The extensions take the form of new functions for creating and +manipulating locale objects +.RB ( newlocale (3), +.BR freelocale (3), +.BR duplocale (3), +and +.BR uselocale (3)) +and various new library functions with the suffix "_l" (e.g., +.BR toupper_l (3)) +that extend the traditional locale-dependent APIs (e.g., +.BR toupper (3)) +to allow the specification of a locale object that should apply when +executing the function. +.SH ENVIRONMENT +The following environment variable is used by +.BR newlocale (3) +and +.BR setlocale (3), +and thus affects all unprivileged localized programs: +.TP +.B LOCPATH +A list of pathnames, separated by colons (\(aq:\(aq), +that should be used to find locale data. +If this variable is set, +only the individual compiled locale data files from +.I LOCPATH +and the system default locale data path are used; +any available locale archives are not used (see +.BR localedef (1)). +The individual compiled locale data files are searched for under +subdirectories which depend on the currently used locale. +For example, when +.I en_GB.UTF-8 +is used for a category, the following subdirectories are searched for, +in this order: +.IR en_GB.UTF-8 , +.IR en_GB.utf8 , +.IR en_GB , +.IR en.UTF-8 , +.IR en.utf8 , +and +.IR en . +.SH FILES +.TP +.I /usr/lib/locale/locale-archive +Usual default locale archive location. +.TP +.I /usr/lib/locale +Usual default path for compiled individual locale files. +.SH CONFORMING TO +POSIX.1-2001. +.\" +.\" The GNU gettext functions are specified in LI18NUX2000. +.SH SEE ALSO +.BR iconv (1), +.BR locale (1), +.BR localedef (1), +.BR catopen (3), +.BR gettext (3), +.BR iconv (3), +.BR localeconv (3), +.BR mbstowcs (3), +.BR newlocale (3), +.BR ngettext (3), +.BR nl_langinfo (3), +.BR rpmatch (3), +.BR setlocale (3), +.BR strcoll (3), +.BR strfmon (3), +.BR strftime (3), +.BR strxfrm (3), +.BR uselocale (3), +.BR wcstombs (3), +.BR locale (5), +.BR charsets (7), +.BR unicode (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/mailaddr.7 b/man7/mailaddr.7 new file mode 100644 index 0000000..9e8f621 --- /dev/null +++ b/man7/mailaddr.7 @@ -0,0 +1,131 @@ +.\" Copyright (c) 1983, 1987 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" @(#)mailaddr.7 6.5 (Berkeley) 2/14/89 +.\" +.\" Extensively rewritten by Arnt Gulbrandsen . My +.\" changes are placed under the same copyright as the original BSD page. +.\" +.\" Adjusted by Arnt Gulbrandsen in 2004 to +.\" account for changes since 1995. Route-addrs are now even less +.\" common, etc. Some minor wording improvements. Same copyright. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Redistribution and use in source and binary forms are permitted +.\" provided that the above copyright notice and this paragraph are +.\" duplicated in all such forms and that any documentation, +.\" advertising materials, and other materials related to such +.\" distribution and use acknowledge that the software was developed +.\" by the University of California, Berkeley. The name of the +.\" University may not be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %%%LICENSE_END +.\" +.TH MAILADDR 7 2017-05-03 "Linux" "Linux User's Manual" +.UC 5 +.SH NAME +mailaddr \- mail addressing description +.SH DESCRIPTION +.nh +This manual page gives a brief introduction to SMTP mail addresses, +as used on the Internet. +These addresses are in the general format +.PP + user@domain +.PP +where a domain is a hierarchical dot-separated list of subdomains. +These examples are valid forms of the same address: +.PP + john.doe@monet.example.com +.br + John Doe +.br + john.doe@monet.example.com (John Doe) +.PP +The domain part ("monet.example.com") is a mail-accepting domain. +It can be a host and in the past it usually was, but it doesn't have to be. +The domain part is not case sensitive. +.PP +The local part ("john.doe") is often a username, +but its meaning is defined by the local software. +Sometimes it is case sensitive, +although that is unusual. +If you see a local-part that looks like garbage, +it is usually because of a gateway between an internal e-mail +system and the net, here are some examples: +.PP + "surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where +.br + USER%SOMETHING@some.where +.br + machine!machine!name@some.where +.br + I2461572@some.where +.PP +(These are, respectively, an X.400 gateway, a gateway to an arbitrary +internal mail system that lacks proper internet support, an UUCP +gateway, and the last one is just boring username policy.) +.PP +The real-name part ("John Doe") can either be placed before +<>, or in () at the end. +(Strictly speaking the two aren't the same, +but the difference is beyond the scope of this page.) +The name may have to be quoted using "", for example, if it contains ".": +.PP + "John Q. Doe" +.SS Abbreviation +.PP +Some mail systems let users abbreviate the domain name. +For instance, +users at example.com may get away with "john.doe@monet" to +send mail to John Doe. +.I "This behavior is deprecated." +Sometimes it works, but you should not depend on it. +.SS Route-addrs +.PP +In the past, sometimes one had to route a message through +several hosts to get it to its final destination. +Addresses which show these relays are termed "route-addrs". +These use the syntax: +.PP + <@hosta,@hostb:user@hostc> +.PP +This specifies that the message should be sent to hosta, +from there to hostb, and finally to hostc. +Many hosts disregard route-addrs and send directly to hostc. +.PP +Route-addrs are very unusual now. +They occur sometimes in old mail archives. +It is generally possible to ignore all but the "user@hostc" +part of the address to determine the actual address. +.SS Postmaster +.PP +Every site is required to have a user or user alias designated +"postmaster" to which problems with the mail system may be +addressed. +The "postmaster" address is not case sensitive. +.SH FILES +.I /etc/aliases +.br +.I ~/.forward +.SH SEE ALSO +.BR mail (1), +.BR aliases (5), +.BR forward (5), +.BR sendmail (8) +.PP +.UR http://www.ietf.org\:/rfc\:/rfc5322.txt +IETF RFC\ 5322 +.UE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/man-pages.7 b/man7/man-pages.7 new file mode 100644 index 0000000..6324890 --- /dev/null +++ b/man7/man-pages.7 @@ -0,0 +1,985 @@ +.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler +.\" (faith@cs.unc.edu and dwheeler@ida.org) +.\" and (C) Copyright 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-05-30 created by mtk, using text from old man.7 plus +.\" rewrites and additional text. +.\" +.TH MAN-PAGES 7 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +man-pages \- conventions for writing Linux man pages +.SH SYNOPSIS +.B man +.RI [ section ] +.I title +.SH DESCRIPTION +This page describes the conventions that should be employed +when writing man pages for the Linux \fIman-pages\fP project, +which documents the user-space API provided by the Linux kernel +and the GNU C library. +The project thus provides most of the pages in Section 2, +many of the pages that appear in Sections 3, 4, and 7, +and a few of the pages that appear in Sections 1, 5, and 8 +of the man pages on a Linux system. +The conventions described on this page may also be useful +for authors writing man pages for other projects. +.SS Sections of the manual pages +.PP +The manual Sections are traditionally defined as follows: +.TP 10 +.B 1 User commands (Programs) +Those commands that can be executed by the user from within +a shell. +.TP +.B 2 System calls +Those functions which wrap operations performed by the kernel. +.TP +.B 3 Library calls +All library functions excluding the system call wrappers +(Most of the +.I libc +functions). +.TP +.B 4 Special files (devices) +Files found in +.I /dev +which allow to access to devices through the kernel. +.TP +.B 5 File formats and configuration files +Describes various human-readable file formats and configuration files. +.TP +.B 6 Games +Games and funny little programs available on the system. +.TP +.B 7 Overview, conventions, and miscellaneous +Overviews or descriptions of various topics, conventions and protocols, +character set standards, the standard filesystem layout, and miscellaneous +other things. +.TP +.B 8 System management commands +Commands like +.BR mount (8), +many of which only root can execute. +.\" .TP +.\" .B 9 Kernel routines +.\" This is an obsolete manual section. +.\" Once it was thought a good idea to document the Linux kernel here, +.\" but in fact very little has been documented, and the documentation +.\" that exists is outdated already. +.\" There are better sources of +.\" information for kernel developers. +.SS Macro package +New manual pages should be marked up using the +.B groff an.tmac +package described in +.BR man (7). +This choice is mainly for consistency: the vast majority of +existing Linux manual pages are marked up using these macros. +.SS Conventions for source file layout +Please limit source code line length to no more than about 75 characters +wherever possible. +This helps avoid line-wrapping in some mail clients when patches are +submitted inline. +.PP +New sentences should be started on new lines. +This makes it easier to see the effect of patches, +which often operate at the level of individual sentences. +.SS Title line +The first command in a man page should be a +.B TH +command: +.PP +.RS +.B \&.TH +.I "title section date source manual" +.RE +.PP +where: +.RS +.TP 10 +.I title +The title of the man page, written in all caps (e.g., +.IR MAN-PAGES ). +.TP +.I section +The section number in which the man page should be placed (e.g., +.IR 7 ). +.TP +.I date +The date of the last nontrivial change that was made to the man page. +(Within the +.I man-pages +project, the necessary updates to these timestamps are handled +automatically by scripts, so there is no need to manually update +them as part of a patch.) +Dates should be written in the form YYYY-MM-DD. +.TP +.I source +The source of the command, function, or system call. +.IP +For those few \fIman-pages\fP pages in Sections 1 and 8, +probably you just want to write +.IR GNU . +.IP +For system calls, just write +.IR "Linux" . +(An earlier practice was to write the version number +of the kernel from which the manual page was being written/checked. +However, this was never done consistently, and so was +probably worse than including no version number. +Henceforth, avoid including a version number.) +.IP +For library calls that are part of glibc or one of the +other common GNU libraries, just use +.IR "GNU C Library" ", " GNU , +or an empty string. +.IP +For Section 4 pages, use +.IR "Linux" . +.IP +In cases of doubt, just write +.IR Linux ", or " GNU . +.TP +.I manual +The title of the manual (e.g., for Section 2 and 3 pages in +the \fIman-pages\fP package, use +.IR "Linux Programmer's Manual" ). +.RE +.SS Sections within a manual page +The list below shows conventional or suggested sections. +Most manual pages should include at least the +.B highlighted +sections. +Arrange a new manual page so that sections +are placed in the order shown in the list. +.PP +.in +4n +.nf +\fBNAME\fP +\fBSYNOPSIS\fP +CONFIGURATION [Normally only in Section 4] +\fBDESCRIPTION\fP +OPTIONS [Normally only in Sections 1, 8] +EXIT STATUS [Normally only in Sections 1, 8] +RETURN VALUE [Normally only in Sections 2, 3] +.\" May 07: Few current man pages have an ERROR HANDLING section,,, +.\" ERROR HANDLING, +ERRORS [Typically only in Sections 2, 3] +.\" May 07: Almost no current man pages have a USAGE section,,, +.\" USAGE, +.\" DIAGNOSTICS, +.\" May 07: Almost no current man pages have a SECURITY section,,, +.\" SECURITY, +ENVIRONMENT +FILES +VERSIONS [Normally only in Sections 2, 3] +ATTRIBUTES [Normally only in Sections 2, 3] +CONFORMING TO +NOTES +BUGS +EXAMPLE +.\" AUTHORS sections are discouraged +.\" AUTHORS [Discouraged] +\fBSEE ALSO\fP +.fi +.in +.PP +.IR "Where a traditional heading would apply" ", " "please use it" ; +this kind of consistency can make the information easier to understand. +If you must, you can create your own +headings if they make things easier to understand (this can +be especially useful for pages in Sections 4 and 5). +However, before doing this, consider whether you could use the +traditional headings, with some subsections (\fI.SS\fP) within +those sections. +.PP +The following list elaborates on the contents of each of +the above sections. +.TP 14 +.B NAME +The name of this manual page. +.IP +See +.BR man (7) +for important details of the line(s) that should follow the +\fB.SH NAME\fP command. +All words in this line (including the word immediately +following the "\\\-") should be in lowercase, +except where English or technical terminological convention +dictates otherwise. +.TP +.B SYNOPSIS +A brief summary of the command or function's interface. +.IP +For commands, this shows the syntax of the command and its arguments +(including options); +boldface is used for as-is text and italics are used to +indicate replaceable arguments. +Brackets ([]) surround optional arguments, vertical bars (|) +separate choices, and ellipses (\&...) can be repeated. +For functions, it shows any required data declarations or +.B #include +directives, followed by the function declaration. +.IP +Where a feature test macro must be defined in order to obtain +the declaration of a function (or a variable) from a header file, +then the SYNOPSIS should indicate this, as described in +.BR feature_test_macros (7). +.\" FIXME . Say something here about compiler options +.TP +.B CONFIGURATION +Configuration details for a device. +.IP +This section normally appears only in Section 4 pages. +.TP +.B DESCRIPTION +An explanation of what the program, function, or format does. +.IP +Discuss how it interacts with files and standard input, and what it +produces on standard output or standard error. +Omit internals and implementation details unless they're critical for +understanding the interface. +Describe the usual case; +for information on command-line options of a program use the +.B OPTIONS +section. +.\" If there is some kind of input grammar or complex set of subcommands, +.\" consider describing them in a separate +.\" .B USAGE +.\" section (and just place an overview in the +.\" .B DESCRIPTION +.\" section). +.IP +When describing new behavior or new flags for +a system call or library function, +be careful to note the kernel or C library version +that introduced the change. +The preferred method of noting this information for flags is as part of a +.B .TP +list, in the following form (here, for a new system call flag): +.RS 22 +.TP +.BR XYZ_FLAG " (since Linux 3.7)" +Description of flag... +.RE +.IP +Including version information is especially useful to users +who are constrained to using older kernel or C library versions +(which is typical in embedded systems, for example). +.TP +.B OPTIONS +A description of the command-line options accepted by a +program and how they change its behavior. +.IP +This section should appear only for Section 1 and 8 manual pages. +.\" .TP +.\" .B USAGE +.\" describes the grammar of any sublanguage this implements. +.TP +.B EXIT STATUS +A list of the possible exit status values of a program and +the conditions that cause these values to be returned. +.IP +This section should appear only for Section 1 and 8 manual pages. +.TP +.B RETURN VALUE +For Section 2 and 3 pages, this section gives a +list of the values the library routine will return to the caller +and the conditions that cause these values to be returned. +.TP +.B ERRORS +For Section 2 and 3 manual pages, this is a list of the +values that may be placed in +.I errno +in the event of an error, along with information about the cause +of the errors. +.IP +Where several different conditions produce the same error, +the preferred approach is to create separate list entries +(with duplicate error names) for each of the conditions. +This makes the separate conditions clear, may make the list easier to read, +and allows metainformation +(e.g., kernel version number where the condition first became applicable) +to be more easily marked for each condition. +.IP +.IR "The error list should be in alphabetical order" . +.TP +.B ENVIRONMENT +A list of all environment variables that affect the program or function +and how they affect it. +.TP +.B FILES +A list of the files the program or function uses, such as +configuration files, startup files, +and files the program directly operates on. +.IP +Give the full pathname of these files, and use the installation +process to modify the directory part to match user preferences. +For many programs, the default installation location is in +.IR /usr/local , +so your base manual page should use +.I /usr/local +as the base. +.\" May 07: Almost no current man pages have a DIAGNOSTICS section; +.\" "RETURN VALUE" or "EXIT STATUS" is preferred. +.\" .TP +.\" .B DIAGNOSTICS +.\" gives an overview of the most common error messages and how to +.\" cope with them. +.\" You don't need to explain system error messages +.\" or fatal signals that can appear during execution of any program +.\" unless they're special in some way to the program. +.\" +.\" May 07: Almost no current man pages have a SECURITY section. +.\".TP +.\".B SECURITY +.\"discusses security issues and implications. +.\"Warn about configurations or environments that should be avoided, +.\"commands that may have security implications, and so on, especially +.\"if they aren't obvious. +.\"Discussing security in a separate section isn't necessary; +.\"if it's easier to understand, place security information in the +.\"other sections (such as the +.\" .B DESCRIPTION +.\" or +.\" .B USAGE +.\" section). +.\" However, please include security information somewhere! +.TP +.B ATTRIBUTES +A summary of various attributes of the function(s) documented on this page. +See +.BR attributes (7) +for further details. +.TP +.B VERSIONS +A brief summary of the Linux kernel or glibc versions where a +system call or library function appeared, +or changed significantly in its operation. +.IP +As a general rule, every new interface should +include a VERSIONS section in its manual page. +Unfortunately, +many existing manual pages don't include this information +(since there was no policy to do so when they were written). +Patches to remedy this are welcome, +but, from the perspective of programmers writing new code, +this information probably matters only in the case of kernel +interfaces that have been added in Linux 2.4 or later +(i.e., changes since kernel 2.2), +and library functions that have been added to glibc since version 2.1 +(i.e., changes since glibc 2.0). +.IP +The +.BR syscalls (2) +manual page also provides information about kernel versions +in which various system calls first appeared. +.TP +.B CONFORMING TO +A description of any standards or conventions that relate to the function +or command described by the manual page. +.IP +The preferred terms to use for the various standards are listed as +headings in +.BR standards (7). +.IP +For a page in Section 2 or 3, +this section should note the POSIX.1 +version(s) that the call conforms to, +and also whether the call is specified in C99. +(Don't worry too much about other standards like SUS, SUSv2, and XPG, +or the SVr4 and 4.xBSD implementation standards, +unless the call was specified in those standards, +but isn't in the current version of POSIX.1.) +.IP +If the call is not governed by any standards but commonly +exists on other systems, note them. +If the call is Linux-specific, note this. +.IP +If this section consists of just a list of standards +(which it commonly does), +terminate the list with a period (\(aq.\(aq). +.TP +.B NOTES +Miscellaneous notes. +.IP +For Section 2 and 3 man pages you may find it useful to include +subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP. +.IP +In Section 2, use the heading +.I "C library/kernel differences" +to mark off notes that describe the differences (if any) between +the C library wrapper function for a system call and +the raw system call interface provided by the kernel. +.TP +.B BUGS +A list of limitations, known defects or inconveniences, +and other questionable activities. +.TP +.B EXAMPLE +One or more examples demonstrating how this function, file or +command is used. +.IP +For details on writing example programs, +see \fIExample Programs\fP below. +.TP +.B AUTHORS +A list of authors of the documentation or program. +.IP +\fBUse of an AUTHORS section is strongly discouraged\fP. +Generally, it is better not to clutter every page with a list +of (over time potentially numerous) authors; +if you write or significantly amend a page, +add a copyright notice as a comment in the source file. +If you are the author of a device driver and want to include +an address for reporting bugs, place this under the BUGS section. +.TP +.B SEE ALSO +A comma-separated list of related man pages, possibly followed by +other related pages or documents. +.IP +The list should be ordered by section number and +then alphabetically by name. +Do not terminate this list with a period. +.IP +Where the SEE ALSO list contains many long manual page names, +to improve the visual result of the output, it may be useful to employ the +.I .ad l +(don't right justify) +and +.I .nh +(don't hyphenate) +directives. +Hyphenation of individual page names can be prevented +by preceding words with the string "\\%". +.IP +Given the distributed, autonomous nature of FOSS projects +and their documentation, it is sometimes necessary\(emand in many cases +desirable\(emthat the SEE ALSO section includes references to +manual pages provided by other projects. +.SH STYLE GUIDE +The following subsections describe the preferred style for the +.IR man-pages +project. +For details not covered below, the Chicago Manual of Style +is usually a good source; +try also grepping for preexisting usage in the project source tree. +.SS Use of gender-neutral language +As far as possible, use gender-neutral language in the text of man +pages. +Use of "they" ("them", "themself", "their") as a gender-neutral singular +pronoun is acceptable. +.\" +.SS Formatting conventions for manual pages describing commands +.PP +For manual pages that describe a command (typically in Sections 1 and 8), +the arguments are always specified using italics, +.IR "even in the SYNOPSIS section" . +.PP +The name of the command, and its options, should +always be formatted in bold. +.\" +.SS Formatting conventions for manual pages describing functions +For manual pages that describe functions (typically in Sections 2 and 3), +the arguments are always specified using italics, +.IR "even in the SYNOPSIS section" , +where the rest of the function is specified in bold: +.PP +.BI " int myfunction(int " argc ", char **" argv ); +.PP +Variable names should, like argument names, be specified in italics. +.PP +Any reference to the subject of the current manual page +should be written with the name in bold followed by +a pair of parentheses in Roman (normal) font. +For example, in the +.BR fcntl (2) +man page, references to the subject of the page would be written as: +.BR fcntl (). +The preferred way to write this in the source file is: +.PP +.EX + .BR fcntl () +.EE +.PP +(Using this format, rather than the use of "\\fB...\\fP()" +makes it easier to write tools that parse man page source files.) +.\" +.SS Formatting conventions (general) +Filenames (whether pathnames, or references to header files) +are always in italics (e.g., +.IR ), +except in the SYNOPSIS section, where included files are in bold (e.g., +.BR "#include " ). +When referring to a standard header file include, +specify the header file surrounded by angle brackets, +in the usual C way (e.g., +.IR ). +.PP +Special macros, which are usually in uppercase, are in bold (e.g., +.BR MAXINT ). +Exception: don't boldface NULL. +.PP +When enumerating a list of error codes, the codes are in bold (this list +usually uses the +.B \&.TP +macro). +.PP +Complete commands should, if long, +be written as an indented line on their own, +with a blank line before and after the command, for example +.PP +.in +4n +.EX +man 7 man-pages +.EE +.in +.PP +If the command is short, then it can be included inline in the text, +in italic format, for example, +.IR "man 7 man-pages" . +In this case, it may be worth using nonbreaking spaces +("\e\ ") at suitable places in the command. +Command options should be written in italics (e.g., +.IR \-l ). +.PP +Expressions, if not written on a separate indented line, should +be specified in italics. +Again, the use of nonbreaking spaces may be appropriate +if the expression is inlined with normal text. +.PP +When showing example shell sessions, user input should be formatted in bold, for example +.PP +.in +4n +.EX +$ \fBdate\fP +Thu Jul 7 13:01:27 CEST 2016 +.EE +.in +.PP +.PP +Any reference to another man page +should be written with the name in bold, +.I always +followed by the section number, +formatted in Roman (normal) font, without any +separating spaces (e.g., +.BR intro (2)). +The preferred way to write this in the source file is: +.PP +.EX + .BR intro (2) +.EE +.PP +(Including the section number in cross references lets tools like +.BR man2html (1) +create properly hyperlinked pages.) +.PP +Control characters should be written in bold face, +with no quotes; for example, +.BR ^X . +.SS Spelling +Starting with release 2.59, +.I man-pages +follows American spelling conventions +(previously, there was a random mix of British and American spellings); +please write all new pages and patches according to these conventions. +.PP +Aside from the well-known spelling differences, +there are a few other subtleties to watch for: +.IP * 3 +American English tends to use the forms "backward", "upward", "toward", +and so on +rather than the British forms "backwards", "upwards", "towards", and so on. +.SS BSD version numbers +The classical scheme for writing BSD version numbers is +.IR x.yBSD , +where +.I x.y +is the version number (e.g., 4.2BSD). +Avoid forms such as +.IR "BSD 4.3" . +.SS Capitalization +In subsection ("SS") headings, +capitalize the first word in the heading, but otherwise use lowercase, +except where English usage (e.g., proper nouns) or programming +language requirements (e.g., identifier names) dictate otherwise. +For example: +.PP +.EX + .SS Unicode under Linux +.EE +.\" +.SS Indentation of structure definitions, shell session logs, and so on +When structure definitions, shell session logs, and so on are included +in running text, indent them by 4 spaces (i.e., a block enclosed by +.I ".in\ +4n" +and +.IR ".in" ), +format them using the +.I .EX +and +.I EE +macros, and surround them with suitable paragraph markers (either +.I .PP +or +.IR .IP ). +For example: +.PP +.in +4n +.EX + .PP + .in +4n + .EX + int + main(int argc, char *argv[]) + { + return 0; + } + .EE + .in + .PP +.EE +.in +.SS Preferred terms +The following table lists some preferred terms to use in man pages, +mainly to ensure consistency across pages. +.TS +l l l +--- +l l l. +Term Avoid using Notes + +bit mask bitmask +built-in builtin +Epoch epoch T{ +For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) +T} +filename file name +filesystem file system +hostname host name +inode i-node +lowercase lower case, lower-case +nonzero non-zero +pathname path name +pseudoterminal pseudo-terminal +privileged port T{ +reserved port, +system port +T} +real-time T{ +realtime, +real time +T} +run time runtime +saved set-group-ID T{ +saved group ID, +saved set-GID +T} +saved set-user-ID T{ +saved user ID, +saved set-UID +T} +set-group-ID set-GID, setgid +set-user-ID set-UID, setuid +superuser T{ +super user, +super-user +T} +superblock T{ +super block, +super-block +T} +timestamp time stamp +timezone time zone +uppercase upper case, upper-case +usable useable +user space userspace +username user name +x86-64 x86_64 T{ +Except if referring to result of "uname\ \-m" or similar +T} +zeros zeroes +.TE +.PP +See also the discussion +.IR "Hyphenation of attributive compounds" +below. +.SS Terms to avoid +The following table lists some terms to avoid using in man pages, +along with some suggested alternatives, +mainly to ensure consistency across pages. +.TS +l l l +--- +l l l. +Avoid Use instead Notes + +32bit 32-bit T{ +same for 8-bit, 16-bit, etc. +T} +current process calling process T{ +A common mistake made by kernel programmers when writing man pages +T} +manpage T{ +man page, manual page +T} +minus infinity negative infinity +non-root unprivileged user +non-superuser unprivileged user +nonprivileged unprivileged +OS operating system +plus infinity positive infinity +pty pseudoterminal +tty terminal +Unices UNIX systems +Unixes UNIX systems +.TE +.SS Trademarks +Use the correct spelling and case for trademarks. +The following is a list of the correct spellings of various +relevant trademarks that are sometimes misspelled: +.PP + DG/UX + HP-UX + UNIX + UnixWare +.SS NULL, NUL, null pointer, and null character +A +.IR "null pointer" +is a pointer that points to nothing, +and is normally indicated by the constant +.IR NULL . +On the other hand, +.I NUL +is the +.IR "null byte", +a byte with the value 0, represented in C via the character constant +.IR \(aq\e0\(aq . +.PP +The preferred term for the pointer is "null pointer" or simply "NULL"; +avoid writing "NULL pointer". +.PP +The preferred term for the byte is "null byte". +Avoid writing "NUL", since it is too easily confused with "NULL". +Avoid also the terms "zero byte" and "null character". +The byte that terminates a C string should be described +as "the terminating null byte"; +strings may be described as "null-terminated", +but avoid the use of "NUL-terminated". +.SS Hyperlinks +For hyperlinks, use the +.IR .UR / .UE +macro pair +(see +.BR groff_man (7)). +This produces proper hyperlinks that can be used in a web browser, +when rendering a page with, say: +.PP + BROWSER=firefox man -H pagename +.SS Use of e.g., i.e., etc., a.k.a., and similar +In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", +"cf.", and "a.k.a." should be avoided, +in favor of suitable full wordings +("for example", "that is", "compare to", "and so on", "also known as"). +.PP +The only place where such abbreviations may be acceptable is in +.I short +parenthetical asides (e.g., like this one). +.PP +Always include periods in such abbreviations, as shown here. +In addition, "e.g." and "i.e." should always be followed by a comma. +.SS Em-dashes +The way to write an em-dash\(emthe glyph that appears +at either end of this subphrase\(emin *roff is with the macro "\\(em". +(On an ASCII terminal, an em-dash typically renders as two hyphens, +but in other typographical contexts it renders as a long dash.) +Em-dashes should be written +.I without +surrounding spaces. +.SS Hyphenation of attributive compounds +Compound terms should be hyphenated when used attributively +(i.e., to qualify a following noun). Some examples: +.PP + 32-bit value + command-line argument + floating-point number + run-time check + user-space function + wide-character string +.SS Hyphenation with multi, non, pre, re, sub, and so on +The general tendency in modern English is not to hyphenate +after prefixes such as "multi", "non", "pre", "re", "sub", and so on. +Manual pages should generally follow this rule when these prefixes are +used in natural English constructions with simple suffixes. +The following list gives some examples of the preferred forms: +.PP + interprocess + multithreaded + multiprocess + nonblocking + nondefault + nonempty + noninteractive + nonnegative + nonportable + nonzero + preallocated + precreate + prerecorded + reestablished + reinitialize + rearm + reread + subcomponent + subdirectory + subsystem +.PP +Hyphens should be retained when the prefixes are used in nonstandard +English words, with trademarks, proper nouns, acronyms, or compound terms. +Some examples: +.PP + non-ASCII + non-English + non-NULL + non-real-time +.PP +Finally, note that "re-create" and "recreate" are two different verbs, +and the former is probably what you want. +.SS Real minus character +Where a real minus character is required (e.g., for numbers such as \-1, +for man page cross references such as +.BR utf\-8 (7), +or when writing options that have a leading dash, such as in +.IR "ls\ \-l"), +use the following form in the man page source: +.PP + \\\- +.PP +This guideline applies also to code examples. +.SS Character constants +To produce single quotes that render well in both ASCII and UTF-8, +use the following form for character constants in the man page source: +.PP + \\(aqC\\(aq +.PP +where +.I C +is the quoted character. +This guideline applies also to character constants used in code examples. +.SS Example programs and shell sessions +Manual pages may include example programs demonstrating how to +use a system call or library function. +However, note the following: +.IP * 3 +Example programs should be written in C. +.IP * +An example program is necessary and useful only if it demonstrates +something beyond what can easily be provided in a textual +description of the interface. +An example program that does nothing +other than call an interface usually serves little purpose. +.IP * +Example programs should be fairly short (preferably less than 100 lines; +ideally less than 50 lines). +.IP * +Example programs should do error checking after system calls and +library function calls. +.IP * +Example programs should be complete, and compile without +warnings when compiled with \fIcc\ \-Wall\fP. +.IP * +Where possible and appropriate, example programs should allow +experimentation, by varying their behavior based on inputs +(ideally from command-line arguments, or alternatively, via +input read by the program). +.IP * +Example programs should be laid out according to Kernighan and +Ritchie style, with 4-space indents. +(Avoid the use of TAB characters in source code!) +The following command can be used to format your source code to +something close to the preferred style: +.IP + indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c +.IP * +For consistency, all example programs should terminate using either of: +.IP + exit(EXIT_SUCCESS); + exit(EXIT_FAILURE); +.IP +Avoid using the following forms to terminate a program: +.IP + exit(0); + exit(1); + return n; +.IP * +If there is extensive explanatory text before the +program source code, mark off the source code +with a subsection heading +.IR "Program source" , +as in: +.IP + .SS Program source +.IP +Always do this if the explanatory text includes a shell session log. +.PP +If you include a shell session log demonstrating the use of a program +or other system feature: +.IP * 3 +Place the session log above the source code listing +.IP * +Indent the session log by four spaces. +.IP * +Boldface the user input text, +to distinguish it from output produced by the system. +.PP +For some examples of what example programs should look like, see +.BR wait (2) +and +.BR pipe (2). +.SH EXAMPLE +For canonical examples of how man pages in the +.I man-pages +package should look, see +.BR pipe (2) +and +.BR fcntl (2). +.SH SEE ALSO +.BR man (1), +.BR man2html (1), +.BR attributes (7), +.BR groff (7), +.BR groff_man (7), +.BR man (7), +.BR mdoc (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/man.7 b/man7/man.7 new file mode 100644 index 0000000..556baa1 --- /dev/null +++ b/man7/man.7 @@ -0,0 +1,534 @@ +.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler +.\" (faith@cs.unc.edu and dwheeler@ida.org) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Jun 8 00:39:52 1996 by aeb +.\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org) +.\" Modified Thu Jul 15 12:43:28 1999 by aeb +.\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze +.\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson +.\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7. +.\" +.TH MAN 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +man \- macros to format man pages +.SH SYNOPSIS +.B groff \-Tascii \-man +.I file +\&... +.PP +.B groff \-Tps \-man +.I file +\&... +.PP +.B man +.RI [ section ] +.I title +.SH DESCRIPTION +This manual page explains the +.B "groff an.tmac" +macro package (often called the +.B man +macro package). +This macro package should be used by developers when +writing or porting man pages for Linux. +It is fairly compatible with other +versions of this macro package, so porting man pages should not be a major +problem (exceptions include the NET-2 BSD release, which uses a totally +different macro package called mdoc; see +.BR mdoc (7)). +.PP +Note that NET-2 BSD mdoc man pages can be used with +.B groff +simply by specifying the +.B \-mdoc +option instead of the +.B \-man +option. +Using the +.B \-mandoc +option is, however, recommended, since this will automatically detect which +macro package is in use. +.PP +For conventions that should be employed when writing man pages +for the Linux \fIman-pages\fP package, see +.BR man-pages (7). +.SS Title line +The first command in a man page (after comment lines, +that is, lines that start with \fB.\\"\fP) should be +.PP +.RS +.B \&.TH +.I "title section date source manual" +.RE +.PP +For details of the arguments that should be supplied to the +.B TH +command, see +.BR man-pages (7). +.PP +Note that BSD mdoc-formatted pages begin with the +.B Dd +command, not the +.B TH +command. +.SS Sections +Sections are started with +.B \&.SH +followed by the heading name. +.\" The following doesn't seem to be required (see Debian bug 411303), +.\" If the name contains spaces and appears +.\" on the same line as +.\" .BR \&.SH , +.\" then place the heading in double quotes. +.PP +The only mandatory heading is NAME, which should be the first section and +be followed on the next line by a one-line description of the program: +.PP +.RS +\&.SH NAME +.br +item \\- description +.RE +.PP +It is extremely important that this format is followed, and that there is a +backslash before the single dash which follows the item name. +This syntax is used by the +.BR mandb (8) +program to create a database of short descriptions for the +.BR whatis (1) +and +.BR apropos (1) +commands. +(See +.BR lexgrog (1) +for further details on the syntax of the NAME section.) +.PP +For a list of other sections that might appear in a manual page, see +.BR man-pages (7). +.SS Fonts +The commands to select the type face are: +.TP 4 +.B \&.B +Bold +.TP +.B \&.BI +Bold alternating with italics +(especially useful for function specifications) +.TP +.B \&.BR +Bold alternating with Roman +(especially useful for referring to other +manual pages) +.TP +.B \&.I +Italics +.TP +.B \&.IB +Italics alternating with bold +.TP +.B \&.IR +Italics alternating with Roman +.TP +.B \&.RB +Roman alternating with bold +.TP +.B \&.RI +Roman alternating with italics +.TP +.B \&.SB +Small alternating with bold +.TP +.B \&.SM +Small (useful for acronyms) +.PP +Traditionally, each command can have up to six arguments, but the GNU +implementation removes this limitation (you might still want to limit +yourself to 6 arguments for portability's sake). +Arguments are delimited by spaces. +Double quotes can be used to specify an argument which contains spaces. +All of the arguments will be printed next to each other without +intervening spaces, so that the +.B \&.BR +command can be used to specify a word in bold followed by a mark of +punctuation in Roman. +If no arguments are given, the command is applied to the following line +of text. +.SS Other macros and strings +.PP +Below are other relevant macros and predefined strings. +Unless noted otherwise, all macros +cause a break (end the current line of text). +Many of these macros set or use the "prevailing indent." +The "prevailing indent" value is set by any macro with the parameter +.I i +below; +macros may omit +.I i +in which case the current prevailing indent will be used. +As a result, successive indented paragraphs can use the same indent without +respecifying the indent value. +A normal (nonindented) paragraph resets the prevailing indent value +to its default value (0.5 inches). +By default, a given indent is measured in ens; +try to use ens or ems as units for +indents, since these will automatically adjust to font size changes. +The other key macro definitions are: +.SS Normal paragraphs +.TP 9m +.B \&.LP +Same as +.B \&.PP +(begin a new paragraph). +.TP +.B \&.P +Same as +.B \&.PP +(begin a new paragraph). +.TP +.B \&.PP +Begin a new paragraph and reset prevailing indent. +.SS Relative margin indent +.TP 9m +.BI \&.RS " i" +Start relative margin indent: moves the left margin +.I i +to the right (if +.I i +is omitted, the prevailing indent value is used). +A new prevailing indent is set to 0.5 inches. +As a result, all following paragraph(s) will be +indented until the corresponding +.BR \&.RE . +.TP +.B \&.RE +End relative margin indent and +restores the previous value of the prevailing indent. +.SS Indented paragraph macros +.TP 9m +.BI \&.HP " i" +Begin paragraph with a hanging indent +(the first line of the paragraph is at the left margin of +normal paragraphs, and the rest of the paragraph's lines are indented). +.TP +.BI \&.IP " x i" +Indented paragraph with optional hanging tag. +If the tag +.I x +is omitted, the entire following paragraph is indented by +.IR i . +If the tag +.I x +is provided, it is hung at the left margin +before the following indented paragraph +(this is just like +.B \&.TP +except the tag is included with the command instead of being on the +following line). +If the tag is too long, the text after the tag will be moved down to the +next line (text will not be lost or garbled). +For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash) +as the tag, and for numbered lists, use the number or letter followed by +a period as the tag; +this simplifies translation to other formats. +.TP +.BI \&.TP " i" +Begin paragraph with hanging tag. +The tag is given on the next line, but +its results are like those of the +.B \&.IP +command. +.SS Hypertext link macros +.TP +.BI \&.UR " url" +Insert a hypertext link to the URI (URL) +.IR url , +with all text up to the following +.B \&.UE +macro as the link text. +.TP +.B \&.UE \c +.RI [ trailer ] +Terminate the link text of the preceding +.B \&.UR +macro, with the optional +.I trailer +(if present, usually a closing parenthesis and/or end-of-sentence +punctuation) immediately following. +For non-HTML output devices (e.g., +.BR "man -Tutf8" ), +the link text is followed by the URL in angle brackets; if there is no +link text, the URL is printed as its own link text, surrounded by angle +brackets. +(Angle brackets may not be available on all output devices.) +For the HTML output device, the link text is hyperlinked to the URL; if +there is no link text, the URL is printed as its own link text. +.PP +These macros have been supported since GNU Troff 1.20 (2009-01-05) and +Heirloom Doctools Troff since 160217 (2016-02-17). +.SS Miscellaneous macros +.TP 9m +.B \&.DT +Reset tabs to default tab values (every 0.5 inches); +does not cause a break. +.TP +.BI \&.PD " d" +Set inter-paragraph vertical distance to d +(if omitted, d=0.4v); +does not cause a break. +.TP +.BI \&.SS " t" +Subheading +.I t +(like +.BR \&.SH , +but used for a subsection inside a section). +.SS Predefined strings +The +.B man +package has the following predefined strings: +.IP \e*R +Registration Symbol: \*R +.IP \e*S +Change to default font size +.IP \e*(Tm +Trademark Symbol: \*(Tm +.IP \e*(lq +Left angled double quote: \*(lq +.IP \e*(rq +Right angled double quote: \*(rq +.SS Safe subset +Although technically +.B man +is a troff macro package, in reality a large number of other tools +process man page files that don't implement all of troff's abilities. +Thus, it's best to avoid some of troff's more exotic abilities +where possible to permit these other tools to work correctly. +Avoid using the various troff preprocessors +(if you must, go ahead and use +.BR tbl (1), +but try to use the +.B IP +and +.B TP +commands instead for two-column tables). +Avoid using computations; most other tools can't process them. +Use simple commands that are easy to translate to other formats. +The following troff macros are believed to be safe (though in many cases +they will be ignored by translators): +.BR \e" , +.BR . , +.BR ad , +.BR bp , +.BR br , +.BR ce , +.BR de , +.BR ds , +.BR el , +.BR ie , +.BR if , +.BR fi , +.BR ft , +.BR hy , +.BR ig , +.BR in , +.BR na , +.BR ne , +.BR nf , +.BR nh , +.BR ps , +.BR so , +.BR sp , +.BR ti , +.BR tr . +.PP +You may also use many troff escape sequences (those sequences beginning +with \e). +When you need to include the backslash character as normal text, +use \ee. +Other sequences you may use, where x or xx are any characters and N +is any digit, include: +.BR \e' , +.BR \e` , +.BR \e- , +.BR \e. , +.BR \e" , +.BR \e% , +.BR \e*x , +.BR \e*(xx , +.BR \e(xx , +.BR \e$N , +.BR \enx , +.BR \en(xx , +.BR \efx , +and +.BR \ef(xx . +Avoid using the escape sequences for drawing graphics. +.PP +Do not use the optional parameter for +.B bp +(break page). +Use only positive values for +.B sp +(vertical space). +Don't define a macro +.RB ( de ) +with the same name as a macro in this or the +mdoc macro package with a different meaning; it's likely that +such redefinitions will be ignored. +Every positive indent +.RB ( in ) +should be paired with a matching negative indent +(although you should be using the +.B RS +and +.B RE +macros instead). +The condition test +.RB ( if,ie ) +should only have \(aqt\(aq or \(aqn\(aq as the condition. +Only translations +.RB ( tr ) +that can be ignored should be used. +Font changes +.RB ( ft +and the \fB\ef\fP escape sequence) +should only have the values 1, 2, 3, 4, R, I, B, P, or CW +(the ft command may also have no parameters). +.PP +If you use capabilities beyond these, check the +results carefully on several tools. +Once you've confirmed that the additional capability is safe, +let the maintainer of this +document know about the safe command or sequence +that should be added to this list. +.SH FILES +.IR /usr/share/groff/ [*/] tmac/an.tmac +.br +.I /usr/man/whatis +.SH NOTES +.PP +By all means include full URLs (or URIs) in the text itself; +some tools such as +.BR man2html (1) +can automatically turn them into hypertext links. +You can also use the +.B UR +and +.B UE +macros to identify links to related information. +If you include URLs, use the full URL +(e.g., +.UR http://www.kernel.org +.UE ) +to ensure that tools can automatically find the URLs. +.PP +Tools processing these files should open the file and examine the first +nonwhitespace character. +A period (.) or single quote (') at the beginning +of a line indicates a troff-based file (such as man or mdoc). +A left angle bracket (<) indicates an SGML/XML-based +file (such as HTML or Docbook). +Anything else suggests simple ASCII +text (e.g., a "catman" result). +.PP +Many man pages begin with \fB\'\e"\fP followed by a +space and a list of characters, +indicating how the page is to be preprocessed. +For portability's sake to non-troff translators we recommend +that you avoid using anything other than +.BR tbl (1), +and Linux can detect that automatically. +However, you might want to include this information so your man page +can be handled by other (less capable) systems. +Here are the definitions of the preprocessors invoked by these characters: +.TP 3 +.B e +eqn(1) +.TP +.B g +grap(1) +.TP +.B p +pic(1) +.TP +.B r +refer(1) +.TP +.B t +tbl(1) +.TP +.B v +vgrind(1) +.SH BUGS +.PP +Most of the macros describe formatting (e.g., font type and spacing) instead +of marking semantic content (e.g., this text is a reference to another page), +compared to formats like mdoc and DocBook (even HTML has more semantic +markings). +This situation makes it harder to vary the +.B man +format for different media, +to make the formatting consistent for a given media, and to automatically +insert cross-references. +By sticking to the safe subset described above, it should be easier to +automate transitioning to a different reference page format in the future. +.PP +The Sun macro +.B TX +is not implemented. +.\" .SH AUTHORS +.\" .IP \(em 3m +.\" James Clark (jjc@jclark.com) wrote the implementation of the macro package. +.\" .IP \(em +.\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of +.\" this manual page. +.\" .IP \(em +.\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO +.\" (which influenced this manual page). +.\" .IP \(em +.\" David A. Wheeler (dwheeler@ida.org) heavily modified this +.\" manual page, such as adding detailed information on sections and macros. +.SH SEE ALSO +.BR apropos (1), +.BR groff (1), +.BR lexgrog (1), +.BR man (1), +.BR man2html (1), +.BR whatis (1), +.BR groff_man (7), +.BR groff_www (7), +.BR man-pages (7), +.BR mdoc (7), +.BR mdoc.samples (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/math_error.7 b/man7/math_error.7 new file mode 100644 index 0000000..63852e8 --- /dev/null +++ b/man7/math_error.7 @@ -0,0 +1,275 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MATH_ERROR 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +math_error \- detecting errors from mathematical functions +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.fi +.SH DESCRIPTION +When an error occurs, +most library functions indicate this fact by returning a special value +(e.g., \-1 or NULL). +Because they typically return a floating-point number, +the mathematical functions declared in +.IR +indicate an error using other mechanisms. +There are two error-reporting mechanisms: +the older one sets +.IR errno ; +the newer one uses the floating-point exception mechanism (the use of +.BR feclearexcept (3) +and +.BR fetestexcept (3), +as outlined below) +described in +.BR fenv (3). +.PP +A portable program that needs to check for an error from a mathematical +function should set +.I errno +to zero, and make the following call +.PP +.in +4n +.EX +feclearexcept(FE_ALL_EXCEPT); +.EE +.in +.PP +before calling a mathematical function. +.PP +Upon return from the mathematical function, if +.I errno +is nonzero, or the following call (see +.BR fenv (3)) +returns nonzero +.PP +.in +4n +.EX +fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | + FE_UNDERFLOW); +.EE +.in +.PP +.\" enum +.\" { +.\" FE_INVALID = 0x01, +.\" __FE_DENORM = 0x02, +.\" FE_DIVBYZERO = 0x04, +.\" FE_OVERFLOW = 0x08, +.\" FE_UNDERFLOW = 0x10, +.\" FE_INEXACT = 0x20 +.\" }; +then an error occurred in the mathematical function. +.PP +The error conditions that can occur for mathematical functions +are described below. +.SS Domain error +A +.I domain error +occurs when a mathematical function is supplied with an argument whose +value falls outside the domain for which the function +is defined (e.g., giving a negative argument to +.BR log (3)). +When a domain error occurs, +math functions commonly return a NaN +(though some functions return a different value in this case); +.I errno +is set to +.BR EDOM , +and an "invalid" +.RB ( FE_INVALID ) +floating-point exception is raised. +.SS Pole error +A +.I pole error +occurs when the mathematical result of a function is an exact infinity +(e.g., the logarithm of 0 is negative infinity). +When a pole error occurs, +the function returns the (signed) value +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +depending on whether the function result type is +.IR double , +.IR float , +or +.IR "long double" . +The sign of the result is that which is mathematically correct for +the function. +.I errno +is set to +.BR ERANGE , +and a "divide-by-zero" +.RB ( FE_DIVBYZERO ) +floating-point exception is raised. +.SS Range error +A +.I range error +occurs when the magnitude of the function result means that it +cannot be represented in the result type of the function. +The return value of the function depends on whether the range error +was an overflow or an underflow. +.PP +A floating result +.I overflows +if the result is finite, +but is too large to represented in the result type. +When an overflow occurs, +the function returns the value +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +depending on whether the function result type is +.IR double , +.IR float , +or +.IR "long double" . +.I errno +is set to +.BR ERANGE , +and an "overflow" +.RB ( FE_OVERFLOW ) +floating-point exception is raised. +.PP +A floating result +.I underflows +if the result is too small to be represented in the result type. +If an underflow occurs, +a mathematical function typically returns 0.0 +(C99 says a function shall return "an implementation-defined value +whose magnitude is no greater than the smallest normalized +positive number in the specified type"). +.I errno +may be set to +.BR ERANGE , +and an "overflow" +.RB ( FE_UNDERFLOW ) +floating-point exception may be raised. +.PP +Some functions deliver a range error if the supplied argument value, +or the correct function result, would be +.IR subnormal . +A subnormal value is one that is nonzero, +but with a magnitude that is so small that +it can't be presented in normalized form +(i.e., with a 1 in the most significant bit of the significand). +The representation of a subnormal number will contain one +or more leading zeros in the significand. +.SH NOTES +The +.I math_errhandling +identifier specified by C99 and POSIX.1 is not supported by glibc. +.\" See CONFORMANCE in the glibc 2.8 (and earlier) source. +This identifier is supposed to indicate which of the two +error-notification mechanisms +.RI ( errno , +exceptions retrievable via +.BR fettestexcept (3)) +is in use. +The standards require that at least one be in use, +but permit both to be available. +The current (version 2.8) situation under glibc is messy. +Most (but not all) functions raise exceptions on errors. +Some also set +.IR errno . +A few functions set +.IR errno , +but don't raise an exception. +A very few functions do neither. +See the individual manual pages for details. +.PP +To avoid the complexities of using +.I errno +and +.BR fetestexcept (3) +for error checking, +it is often advised that one should instead check for bad argument +values before each call. +.\" http://www.securecoding.cert.org/confluence/display/seccode/FLP32-C.+Prevent+or+detect+domain+and+range+errors+in+math+functions +For example, the following code ensures that +.BR log (3)'s +argument is not a NaN and is not zero (a pole error) or +less than zero (a domain error): +.PP +.in +4n +.EX +double x, r; + +if (isnan(x) || islessequal(x, 0)) { + /* Deal with NaN / pole error / domain error */ +} + +r = log(x); +.EE +.in +.PP +The discussion on this page does not apply to the complex +mathematical functions (i.e., those declared by +.IR ), +which in general are not required to return errors by C99 +and POSIX.1. +.PP +The +.BR gcc (1) +.I "-fno-math-errno" +option causes the executable to employ implementations of some +mathematical functions that are faster than the standard +implementations, but do not set +.I errno +on error. +(The +.BR gcc (1) +.I "-ffast-math" +option also enables +.IR "-fno-math-errno" .) +An error can still be tested for using +.BR fetestexcept (3). +.SH SEE ALSO +.BR gcc (1), +.BR errno (3), +.BR fenv (3), +.BR fpclassify (3), +.BR INFINITY (3), +.BR isgreater (3), +.BR matherr (3), +.BR nan (3) +.PP +.I "info libc" +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/mdoc.7 b/man7/mdoc.7 new file mode 100644 index 0000000..0b1f38b --- /dev/null +++ b/man7/mdoc.7 @@ -0,0 +1,444 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)mdoc.7 8.2 (Berkeley) 12/30/93 +.\" $Id: mdoc.7,v 1.8 1998/12/04 00:51:17 jkoshy Exp $ +.\" +.\" The December 30, 1993 version +.\" Modified by David A. Wheeler (dwheeler@ida.org) on 1999-07-11 +.\" to conform to Linux. +.\" +.\" +.Dd July 11, 1999 +.Dt MDOC 7 +.Os Linux +.Sh NAME +.Nm mdoc +.Nd quick reference guide for the +.Nm \-mdoc +macro package +.Sh SYNOPSIS +.Nm groff +.Fl m Ns Ar doc +.Ar files ... +.Sh DESCRIPTION +The +.Nm \-mdoc +package is a set of content-based and domain-based macros +used to format the +.Bx +man pages. +The macro names and their meanings are +listed below for quick reference; for +a detailed explanation on using the package, see +.Xr groff_mdoc 7 +and the tutorial sampler +.Xr mdoc.samples 7 . +.Pp +Note that this is not the usual macro package for Linux documentation, +although it is used for documentation of several widely used programs; +see +.Xr man 7 . +.Pp +The macros are described in two groups, the first +includes the structural and physical page layout macros. +The second contains the manual and general text domain +macros which differentiate the +.Nm \-mdoc +package from other +.Xr troff +formatting packages. +.Sh PAGE STRUCTURE DOMAIN +.Ss Title Macros +To create a valid manual page, these three macros, in this order, +are required: +.Pp +.Bl -tag -width "xxxx.Os OPERATINGxSYSTEM [version/release]" -compact +.It Li "\&.Dd " Ar "Month day, year" +Document date. +.It Li "\&.Dt " Ar "DOCUMENT_TITLE [section] [volume]" +Title, in uppercase. +.It Li "\&.Os " Ar "OPERATING_SYSTEM [version/release]" +Operating system +.Pq Tn BSD . +.El +.Ss Page Layout Macros +Section headers, paragraph breaks, lists and displays. +.Pp +.Bl -tag -width flag -compact +.It Li \&.Sh +Section Headers. +Valid headers, in the order of presentation: +.Bl -tag -width "RETURN VALUE" -compact +.It Ar NAME +Name section, should include the +.Ql \&.Nm +or +.Ql \&.Fn +and the +.Ql \&.Nd +macros. +.It Ar SYNOPSIS +Usage. +.It Ar DESCRIPTION +General description, should include +options and parameters. +.It Ar RETURN VALUE +Sections two and three function calls. +.It Ar ENVIRONMENT +Describe environment variables. +.It Ar FILES +Files associated with the subject. +.It Ar EXAMPLES +Examples and suggestions. +.It Ar DIAGNOSTICS +Normally used for section four device interface diagnostics. +.It Ar ERRORS +Sections two and three error and signal +handling. +.It Ar SEE ALSO +Cross references and citations. +.It Ar CONFORMING TO +Conformance to standards if applicable. +.It Ar HISTORY +If a standard is not applicable, the history +of the subject should be given. +.It Ar BUGS +Gotchas and caveats. +.It Ar other +Customized headers may be added at +the authors discretion. +.El +.It Li \&.Ss +Subsection Headers. +.It Li \&.Pp +Paragraph Break. +Vertical space (one line). +.It Li \&.D1 +(D-one) Display-one +Indent and display one text line. +.It Li \&.Dl +(D-ell) Display-one literal. +Indent and display one line of literal text. +.It Li \&.Bd +Begin-display block. +Display options: +.Bl -tag -width "xoffset string " -compact +.It Fl ragged +Unjustified (ragged edges). +.It Fl filled +Justified. +.It Fl literal +Literal text or code. +.It Fl file Ar name +Read in named +.Ar file +and display. +.It Fl offset Ar string +Offset display. +Acceptable +.Ar string +values: +.Bl -tag -width indent-two -compact +.It Ar left +Align block on left (default). +.It Ar center +Approximate center margin. +.It Ar indent +Six constant width spaces (a tab). +.It Ar indent-two +Two tabs. +.It Ar right +Left aligns block 2 inches from +right. +.It Ar xx Ns Cm n +Where +.Ar xx +is a number from +.No \&4 Ns Cm n +to +.No \&9\&9 Ns Cm n . +.It Ar Aa +Where +.Ar Aa +is a callable macro name. +.It Ar string +The width of +.Ar string +is used. +.El +.El +.It Li \&.Ed +End-display (matches \&.Bd). +.It Li \&.Bl +Begin-list. +Create lists or columns. +Options: +.Bl -tag -width flag -compact +.It Ar List-types +.Bl -column ".Fl bullet" -compact +.It Fl bullet Ta "Bullet Item List" +.It Fl item Ta "Unlabeled List" +.It Fl enum Ta "Enumerated List" +.It Fl tag Ta "Tag Labeled List" +.It Fl diag Ta "Diagnostic List" +.It Fl hang Ta "Hanging Labeled List" +.It Fl ohang Ta "Overhanging Labeled List" +.It Fl inset Ta "Inset or Run-on Labeled List" +.El +.It List-parameters +.Bl -tag -width "xcompact " -compact +.It Fl offset +(All lists.) See +.Ql \&.Bd +begin-display above. +.It Fl width +.Pf ( Fl tag +and +.Fl hang +lists only.) +See +.Ql \&.Bd . +.It Fl compact +(All lists.) +Suppresses blank lines. +.El +.El +.It Li \&.El +End-list. +.It Li \&.It +List item. +.El +.Sh MANUAL AND GENERAL TEXT DOMAIN MACROS +The manual and general text domain macros are special in that +most of them are parsed for callable macros +for example: +.Bl -tag -width ".Op Fl s Ar filex" -offset indent +.It Li "\&.Op Fl s Ar file" +Produces +.Op Fl s Ar file +.El +.Pp +In this example, the option enclosure macro +.Ql \&.Op +is parsed, and calls the callable content macro +.Ql \&Fl +which operates on the argument +.Ql s +and then calls the callable content macro +.Ql \&Ar +which operates on the argument +.Ql file . +Some macros may be callable, but are not parsed and vice versa. +These macros are indicated in the +.Em parsed +and +.Em callable +columns below. +.Pp +Unless stated, manual domain macros share a common syntax: +.Pp +.Dl \&.Va argument [\ .\ ,\ ;\ :\ (\ )\ [\ ]\ argument \...\ ] +.Pp +.Sy Note : +Opening and closing +punctuation characters are recognized as such only if they are presented +one at a time. +The string +.Ql ")," +is not recognized as punctuation and will be output with a leading white +space and in what ever font the calling macro uses. +The +argument list +.Ql "] ) ," +is recognized as three sequential closing punctuation characters +and a leading white space is not output between the characters +and the previous argument (if any). +The special meaning of a punctuation character may be escaped +with the string +.Ql \e& . +For example the following string, +.Bl -tag -width "&.Ar file1\ , file2\ , file3\ )\ ." -offset indent +.It Li "\&.Ar file1\ , file2\ , file3\ )\ ." +Produces +.Ar file1 , file2 , file3 ) . +.El +.ne 1i +.Ss Manual Domain Macros +.Bl -column "Name" "Parsed" Callable" -compact +.It Em "Name Parsed Callable Description" +.It Li \&Ad Ta Yes Ta Yes Ta "Address. (This macro may be deprecated.)" +.It Li \&An Ta Yes Ta Yes Ta "Author name." +.It Li \&Ar Ta Yes Ta Yes Ta "Command-line argument." +.It Li \&Cd Ta \&No Ta \&No Ta "Configuration declaration (section four only)." +.It Li \&Cm Ta Yes Ta Yes Ta "Command-line argument modifier." +.It Li \&Dv Ta Yes Ta Yes Ta "Defined variable (source code)." +.It Li \&Er Ta Yes Ta Yes Ta "Error number (source code)." +.It Li \&Ev Ta Yes Ta Yes Ta "Environment variable." +.It Li \&Fa Ta Yes Ta Yes Ta "Function argument." +.It Li \&Fd Ta Yes Ta Yes Ta "Function declaration." +.It Li \&Fn Ta Yes Ta Yes Ta "Function call (also .Fo and .Fc)." +.It Li \&Ic Ta Yes Ta Yes Ta "Interactive command." +.It Li \&Li Ta Yes Ta Yes Ta "Literal text." +.It Li \&Nm Ta Yes Ta Yes Ta "Command name." +.It Li \&Op Ta Yes Ta Yes Ta "Option (also .Oo and .Oc)." +.It Li \&Ot Ta Yes Ta Yes Ta "Old style function type (Fortran only)." +.It Li \&Pa Ta Yes Ta Yes Ta "Pathname or filename." +.It Li \&St Ta Yes Ta Yes Ta "Standards (\-p1003.2, \-p1003.1 or \-ansiC)" +.It Li \&Va Ta Yes Ta Yes Ta "Variable name." +.It Li \&Vt Ta Yes Ta Yes Ta "Variable type (Fortran only)." +.It Li \&Xr Ta Yes Ta Yes Ta "Manual Page Cross Reference." +.El +.Ss General Text Domain Macros +.Bl -column "Name" "Parsed" Callable" -compact +.It Em "Name Parsed Callable Description" +.It Li \&%A Ta Yes Ta \&No Ta "Reference author." +.It Li \&%B Ta Yes Ta Yes Ta "Reference book title." +.It Li \&%\&C Ta \&No Ta \&No Ta "Reference place of publishing (city)." +.It Li \&%\&D Ta \&No Ta \&No Ta "Reference date." +.It Li \&%J Ta Yes Ta Yes Ta "Reference journal title." +.It Li \&%N Ta \&No Ta \&No Ta "Reference issue number." +.It Li \&%\&O Ta \&No Ta \&No Ta "Reference optional information." +.It Li \&%P Ta \&No Ta \&No Ta "Reference page number(s)." +.It Li \&%R Ta \&No Ta \&No Ta "Reference report Name." +.It Li \&%T Ta Yes Ta Yes Ta "Reference article title." +.It Li \&%V Ta \&No Ta \&No Ta "Reference volume." +.It Li \&Ac Ta Yes Ta Yes Ta "Angle close quote." +.It Li \&Ao Ta Yes Ta Yes Ta "Angle open quote." +.It Li \&Ap Ta Yes Ta Yes Ta "Apostrophe." +.It Li \&Aq Ta Yes Ta Yes Ta "Angle quote." +.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX" +.It Li \&Bc Ta Yes Ta Yes Ta "Bracket close quote." +.It Li \&Bf Ta \&No Ta \&No Ta "Begin font mode." +.It Li \&Bo Ta Yes Ta Yes Ta "Bracket open quote." +.It Li \&Bq Ta Yes Ta Yes Ta "Bracket quote." +.It Li \&Bx Ta Yes Ta Yes Ta Bx . +.It Li \&Db Ta \&No Ta \&No Ta "Debug (default is \*qoff\*q)" +.It Li \&Dc Ta Yes Ta Yes Ta "Double close quote." +.It Li \&Do Ta Yes Ta Yes Ta "Double open quote." +.It Li \&Dq Ta Yes Ta Yes Ta "Double quote." +.It Li \&Ec Ta Yes Ta Yes Ta "Enclose string close quote." +.It Li \&Ef Ta \&No Ta \&No Ta "End font mode." +.It Li \&Em Ta Yes Ta Yes Ta "Emphasis (traditional English)." +.It Li \&Eo Ta Yes Ta Yes Ta "Enclose string open quote." +.It Li \&Fx Ta \&No Ta \&No Ta Tn "FreeBSD operating system" +.It Li \&No Ta Yes Ta Yes Ta "Normal text (no-op)." +.It Li \&Ns Ta Yes Ta Yes Ta "No space." +.It Li \&Pc Ta Yes Ta Yes Ta "Parenthesis close quote." +.It Li \&Pf Ta Yes Ta \&No Ta "Prefix string." +.It Li \&Po Ta Yes Ta Yes Ta "Parenthesis open quote." +.It Li \&Pq Ta Yes Ta Yes Ta "Parentheses quote." +.It Li \&Qc Ta Yes Ta Yes Ta "Straight Double close quote." +.It Li \&Ql Ta Yes Ta Yes Ta "Quoted literal." +.It Li \&Qo Ta Yes Ta Yes Ta "Straight Double open quote." +.It Li \&Qq Ta Yes Ta Yes Ta "Straight Double quote." +.It Li \&Re Ta \&No Ta \&No Ta "Reference end." +.It Li \&Rs Ta \&No Ta \&No Ta "Reference start." +.It Li \&Rv Ta \&No Ta \&No Ta "Return values (sections two and three only)." +.It Li \&Sc Ta Yes Ta Yes Ta "Single close quote." +.It Li \&So Ta Yes Ta Yes Ta "Single open quote." +.It Li \&Sq Ta Yes Ta Yes Ta "Single quote." +.It Li \&Sm Ta \&No Ta \&No Ta "Space mode (default is \\*qon\\*q)" +.It Li \&Sx Ta Yes Ta Yes Ta "Section Cross Reference." +.It Li \&Sy Ta Yes Ta Yes Ta "Symbolic (traditional English)." +.It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)." +.It Li \&Ux Ta Yes Ta Yes Ta Ux +.It Li \&Xc Ta Yes Ta Yes Ta "Extend argument list close." +.It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list open." +.El +.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header" +.Pp +Macro names ending in +.Ql q +quote remaining items on the argument list. +Macro names ending in +.Ql o +begin a quote which may span more than one line of input and +are close quoted with the matching macro name ending in +.Ql c . +Enclosure macros may be nested and are limited to +eight arguments. +.Pp +Note: the extended argument list macros +.Pf ( Ql \&.Xo , +.Ql \&.Xc ) +and the function enclosure macros +.Pf ( Ql \&.Fo , +.Ql \&.Fc ) +are irregular. +The extended list macros are used when the number of macro arguments +would exceed the +.Xr troff +limitation of nine arguments. +.Pp +The macros UR (starting a URI/URL hypertext reference), UE (ending one), +and UN (identifying a target for a reference) are also available. +See +.Xr man 7 +for more information on these macros. +.\" The following does not apply on Linux: +.\" .Sh CONFIGURATION +.\" For site specific configuration of the macro package, +.\" see the file +.\" .Pa /usr/src/share/tmac/README . +.Sh FILES +.Bl -tag -width "tmac.doc-ditroff" -compact +.It Pa doc.tmac +Manual and general text domain macros. +.It Pa tmac/doc-common +Common structural macros and definitions. +.It Pa tmac/doc-nroff +Site dependent +.Xr nroff +style file. +.It Pa tmac/doc-ditroff +Site dependent +.Xr troff +style file. +.It Pa tmac/doc-syms +Special defines (such as the standards macro). +.El +.Sh "SEE ALSO" +.Xr groff_mdoc 7 , +.Xr man 7 , +.Xr man-pages 7 , +.Xr mdoc.samples 7 +.Sh COLOPHON +This page is part of release 4.15 of the Linux +.Em man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/mdoc.samples.7 b/man7/mdoc.samples.7 new file mode 100644 index 0000000..c08726a --- /dev/null +++ b/man7/mdoc.samples.7 @@ -0,0 +1,2965 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93 +.\" $Id: mdoc.samples.7,v 1.17 1998/12/03 03:38:45 jkoshy Exp $ +.\" +.\" This tutorial sampler invokes every macro in the package several +.\" times and is guaranteed to give a worst case performance +.\" for an already extremely slow package. +.\" +.\" String \*(Pu was not defined, probably means punctuation +.ds Pu "[ .,:;()[]?! ] +.Dd December 30, 1993 +.Os +.Dt MDOC.SAMPLES 7 +.Sh NAME +.Nm mdoc.samples +.Nd tutorial sampler for writing +.Bx +manuals with +.Nm \-mdoc +.Sh SYNOPSIS +.Nm man mdoc.samples +.Sh DESCRIPTION +A tutorial sampler for writing +.Bx +manual pages with the +.Nm \-mdoc +macro package, a +.Em content Ns \-based +and +.Em domain Ns \-based +formatting +package for +.Xr troff 1 . +Its predecessor, the +.Xr \-man 7 +package, +addressed page layout, leaving the +manipulation of fonts and other +typesetting details to the individual author. +In +.Nm \-mdoc , +page layout macros +make up the +.Em "page structure domain" +which consists of macros for titles, section headers, displays +and lists. +Essentially items which affect the physical position +of text on a formatted page. +In addition to the page structure domain, there are two more domains, +the manual domain and the general text domain. +The general text domain is defined as macros which +perform tasks such as quoting or emphasizing pieces of text. +The manual domain is defined as macros that are a subset of the +day to day informal language used to describe commands, routines +and related +.Bx +files. +Macros in the manual domain handle +command names, command-line arguments and options, function names, +function parameters, pathnames, variables, cross +references to other manual pages, and so on. +These domain +items have value +for both the author and the future user of the manual page. +It is hoped the consistency gained +across the manual set will provide easier +translation to future documentation tools. +.Pp +Throughout the +.Ux +manual pages, a manual entry +is simply referred +to as a man page, regardless of actual length and without +sexist intention. +.Sh GETTING STARTED +Since a tutorial document is normally read when a person +desires to use the material immediately, the assumption has +been made that the user of this document may be impatient. +The material presented in the remained of this document is +outlined as follows: +.Bl -enum -offset indent +.It +.Tn "TROFF IDIOSYNCRASIES" +.Bl -tag -width flag -compact -offset indent +.It "Macro Usage" . +.It "Passing Space Characters in an Argument" . +.It "Trailing Blank Space Characters (a warning)" . +.It "Escaping Special Characters" . +.El +.It +.Tn "THE ANATOMY OF A MAN PAGE" +.Bl -tag -width flag -compact -offset indent +.It "A manual page template" . +.El +.It +.Tn "TITLE MACROS" . +.It +.Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" . +.Bl -tag -width flag -compact -offset indent +.It "What's in a name..." . +.It "General Syntax" . +.El +.It +.Tn "MANUAL DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "Addresses" . +.It "Author name" . +.It "Arguments" . +.It "Configuration Declarations (section four only)" . +.It "Command Modifier" . +.It "Defined Variables" . +.It "Errno's (Section two only)" . +.It "Environment Variables" . +.It "Function Argument" . +.It "Function Declaration" . +.It "Flags" . +.It "Functions (library routines)" . +.It "Function Types" . +.\" .It "Header File (including source code)" . +.It "Interactive Commands" . +.It "Names" . +.It "Options" . +.It "Pathnames" . +.It "Variables" . +.It "Cross References" . +.El +.It +.Tn "GENERAL TEXT DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "AT&T Macro" . +.It "BSD Macro" . +.It "FreeBSD Macro" . +.It "UNIX Macro" . +.It "Enclosure/Quoting Macros" +.Bl -tag -width flag -compact -offset indent +.It "Angle Bracket Quote/Enclosure" . +.It "Bracket Quotes/Enclosure" . +.It "Double Quote macro/Enclosure" . +.It "Parenthesis Quote/Enclosure" . +.It "Single Quotes/Enclosure" . +.It "Prefix Macro" . +.El +.It "No\-Op or Normal Text Macro" . +.It "No Space Macro" . +.It "Section Cross References" . +.It "References and Citations" . +.It "Return Values (sections two and three only)" +.It "Trade Names (Acronyms and Type Names)" . +.It "Extended Arguments" . +.El +.It +.Tn "PAGE STRUCTURE DOMAIN" +.Bl -tag -width flag -compact -offset indent +.It "Section Headers" . +.It "Paragraphs and Line Spacing" . +.It "Keeps" . +.It "Displays" . +.It "Font Modes (Emphasis, Literal, and Symbolic)" . +.It "Lists and Columns" . +.El +.It +.Tn "PREDEFINED STRINGS" +.It +.Tn "DIAGNOSTICS" +.It +.Tn "FORMATTING WITH GROFF, TROFF AND NROFF" +.It +.Tn "BUGS" +.El +.ne 7 +.Sh TROFF IDIOSYNCRASIES +The +.Nm \-mdoc +package attempts to simplify the process of writing a man page. +Theoretically, one should not have to learn the dirty details of +.Xr troff 1 +to use +.Nm \-mdoc ; +however, there are a few +limitations which are unavoidable and best gotten out +of the way. +And, too, be forewarned, this package is +.Em not +fast. +.Ss Macro Usage +As in +.Xr troff 1 , +a macro is called by placing a +.Ql \&\. +(dot character) +at the beginning of +a line followed by the two character name for the macro. +Arguments may follow the macro separated by spaces. +It is the dot character at the beginning of the line which causes +.Xr troff 1 +to interpret the next two characters as a macro name. +To place a +.Ql \&\. +(dot character) +at the beginning of a line in some context other than +a macro invocation, precede the +.Ql \&\. +(dot) with the +.Ql \e& +escape sequence. +The +.Ql \e& +translates literally to a zero width space, and is never displayed in the +output. +.Pp +In general, +.Xr troff 1 +macros accept up to nine arguments, any +extra arguments are ignored. +Most macros in +.Nm \-mdoc +accept nine arguments and, +in limited cases, arguments may be continued or extended +on the +next line (See +.Sx Extensions ) . +A few macros handle quoted arguments (see +.Sx Passing Space Characters in an Argument +below). +.Pp +Most of the +.Nm \-mdoc +general text domain and manual domain macros are special +in that their argument lists are +.Em parsed +for callable macro names. +This means an argument on the argument list which matches +a general text or manual domain macro name and is determined +to be callable will be executed +or called when it is processed. +In this case, +the argument, although the name of a macro, +is not preceded by a +.Ql \&\. +(dot). +It is in this manner that many macros are nested; for +example +the option macro, +.Ql \&.Op , +may +.Em call +the flag and argument macros, +.Ql \&Fl +and +.Ql \&Ar , +to specify an optional flag with an argument: +.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent +.It Op Fl s Ar bytes +is produced by +.Li \&.Op \&Fl s \&Ar bytes +.El +.Pp +To prevent a two character +string from being interpreted as a macro name, precede +the string with the +escape sequence +.Ql \e& : +.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent +.It Op \&Fl s \&Ar bytes +is produced by +.Li \&.Op \e&Fl s \e&Ar bytes +.El +.Pp +Here the strings +.Ql \&Fl +and +.Ql \&Ar +are not interpreted as macros. +Macros whose argument lists are parsed for callable arguments +are referred to +as parsed and macros which may be called from an argument +list are referred to as callable +throughout this document and in the companion quick reference +manual +.Xr mdoc 7 . +This is a technical +.Em faux pas +as almost all of the macros in +.Nm \-mdoc +are parsed, but as it was cumbersome to constantly refer to macros +as being callable and being able to call other macros, +the term parsed has been used. +.Ss Passing Space Characters in an Argument +Sometimes it is desirable to give as one argument a string +containing one or more blank space characters. +This may be necessary +to defeat the nine argument limit or to specify arguments to macros +which expect particular arrangement of items in the argument list. +For example, +the function macro +.Ql \&.Fn +expects the first argument to be the name of a function and any +remaining arguments to be function parameters. +As +.Tn "ANSI C" +stipulates the declaration of function parameters in the +parenthesized parameter list, each parameter is guaranteed +to be at minimum a two word string. +For example, +.Fa int foo . +.Pp +There are two possible ways to pass an argument which contains +an embedded space. +.Em Implementation note : +Unfortunately, the most convenient way +of passing spaces in between quotes by reassigning individual +arguments before parsing was fairly expensive speed wise +and space wise to implement in all the macros for +.Tn AT&T +.Xr troff . +It is not expensive for +.Xr groff +but for the sake of portability, has been limited +to the following macros which need +it the most: +.Pp +.Bl -tag -width 4n -offset indent -compact +.It Li \&Cd +Configuration declaration (section 4 +.Sx SYNOPSIS ) +.It Li \&Bl +Begin list (for the width specifier). +.It Li \&Em +Emphasized text. +.It Li \&Fn +Functions (sections two and four). +.It Li \&It +List items. +.It Li \&Li +Literal text. +.It Li \&Sy +Symbolic text. +.It Li \&%B +Book titles. +.It Li \&%J +Journal names. +.It Li \&%O +Optional notes for a reference. +.It Li \&%R +Report title (in a reference). +.It Li \&%T +Title of article in a book or journal. +.El +.Pp +One way of passing a string +containing blank spaces is to use the hard or unpaddable space character +.Ql \e\ , +that is, a blank space preceded by the escape character +.Ql \e . +This method may be used with any macro but has the side effect +of interfering with the adjustment of text +over the length of a line. +.Xr Troff +sees the hard space as if it were any other printable character and +cannot split the string into blank or newline separated pieces as one +would expect. +The method is useful for strings which are not expected +to overlap a line boundary. +For example: +.Bl -tag -width "fetch(char *str)" -offset indent +.It Fn fetch char\ *str +is created by +.Ql \&.Fn fetch char\e *str +.It Fn fetch "char *str" +can also be created by +.Ql \&.Fn fetch "\\*qchar *str\\*q" +.El +.Pp +If the +.Ql \e +or quotes +were omitted, +.Ql \&.Fn +would see three arguments and +the result would be: +.Pp +.Dl Fn fetch char *str +.Pp +For an example of what happens when the parameter list overlaps +a newline boundary, see the +.Sx BUGS +section. +.Ss Trailing Blank Space Characters +.Xr Troff +can be confused by blank space characters at the end of a line. +It +is a wise preventive measure to globally remove all blank spaces +from character sequences. +Should the need +arise to force a blank character at the end of a line, +it may be forced with an unpaddable space and the +.Ql \e& +escape character. +For example, +.Ql string\e\ \e& . +.Ss Escaping Special Characters +Special characters +like the newline character +.Ql \en , +are handled by replacing the +.Ql \e +with +.Ql \ee +(e.g., +.Ql \een ) +to preserve +the backslash. +.Sh THE ANATOMY OF A MAN PAGE +The body of a man page is easily constructed from a basic +template found in the file +.Pa /usr/share/misc/mdoc.template . +Several example man pages can also be found +in +.Pa /usr/share/examples/mdoc . +.Pp +.Ss A manual page template +.Bd -literal -offset indent +\&.\e" The following requests are required for all man pages. +\&.Dd Month day, year +\&.Os OPERATING_SYSTEM [version/release] +\&.Dt DOCUMENT_TITLE [section number] [volume] +\&.Sh NAME +\&.Nm name +\&.Nd one line description of name +\&.Sh SYNOPSIS +\&.Sh DESCRIPTION +\&.\e" The following requests should be uncommented and +\&.\e" used where appropriate. This next request is +\&.\e" for sections 2 and 3 function return values only. +\&.\e" .Sh RETURN VALUE +\&.\e" This next request is for sections 1, 6, 7 & 8 only +\&.\e" .Sh ENVIRONMENT +\&.\e" .Sh FILES +\&.\e" .Sh EXAMPLES +\&.\e" This next request is for sections 1, 6, 7 & 8 only +\&.\e" (command return values (to shell) and +\&.\e" fprintf/stderr type diagnostics) +\&.\e" .Sh DIAGNOSTICS +\&.\e" The next request is for sections 2 and 3 error +\&.\e" and signal handling only. +\&.\e" .Sh ERRORS +\&.\e" .Sh SEE ALSO +\&.\e" .Sh CONFORMING TO +\&.\e" .Sh HISTORY +\&.\e" .Sh AUTHORS +\&.\e" .Sh BUGS +.Ed +.Pp +The first items in the template are the macros +.Pq Li \&.Dd , \&.Os , \&.Dt ; +the document date, +the operating system the man page or subject source is developed +or modified for, +and the man page title +.Pq Em in uppercase +along with the section of the manual the page +belongs in. +These macros identify the page, +and are discussed below in +.Sx TITLE MACROS . +.Pp +The remaining items in the template are section headers +.Pq Li \&.Sh ; +of which +.Sx NAME , +.Sx SYNOPSIS +and +.Sx DESCRIPTION +are mandatory. +The +headers are +discussed in +.Sx PAGE STRUCTURE DOMAIN , +after +presentation of +.Sx MANUAL DOMAIN . +Several content macros are used to demonstrate page layout macros; +reading about content macros before page layout macros is +recommended. +.Sh TITLE MACROS +The title macros are the first portion of the page structure +domain, but are presented first and separate for someone who +wishes to start writing a man page yesterday. +Three header macros designate the document title or manual page title, +the operating system, +and the date of authorship. +These macros are one called once at the very beginning of the document +and are used to construct the headers and footers only. +.Bl -tag -width 6n +.It Li \&.Dt DOCUMENT_TITLE section# [volume] +The document title is the +subject of the man page and must be in +.Tn CAPITALS +due to troff +limitations. +The section number may be 1,\ ...,\ 8, +and if it is specified, +the volume title may be omitted. +A volume title may be arbitrary or one of the following: +.\" .Cl +.\" USD UNIX User's Supplementary Documents +.\" .Cl +.\" PS1 UNIX Programmer's Supplementary Documents +.Pp +.Bl -column SMM -offset indent -compact +.It Li "AMD UNIX Ancestral Manual Documents" +.It Li "SMM UNIX System Manager's Manual" +.It Li "URM UNIX Reference Manual" +.It Li "PRM UNIX Programmer's Manual" +.El +.Pp +The default volume labeling is +.Li URM +for sections 1, 6, and 7; +.Li SMM +for section 8; +.Li PRM +for sections 2, 3, 4, and 5. +.\" .Cl +.\" MMI UNIX Manual Master Index +.\" .Cl +.\" CON UNIX Contributed Software Manual +.\" .Cl +.\" LOC UNIX Local Manual +.It Li \&.Os operating_system release# +The name of the operating system +should be the common acronym, for example, +.Tn BSD +or +.Tn FreeBSD +or +.Tn ATT . +The release should be the standard release +nomenclature for the system specified, for example, 4.3, 4.3+Tahoe, V.3, +V.4. +Unrecognized arguments are displayed as given in the page footer. +For instance, a typical footer might be: +.Pp +.Dl \&.Os 4.3BSD +.Pp +or +.Dl \&.Os FreeBSD 2.2 +.Pp +or for a locally produced set +.Pp +.Dl \&.Os CS Department +.Pp +The Berkeley default, +.Ql \&.Os +without an argument, has been defined as +.Tn BSD +in the +site-specific file +.Pa /usr/share/tmac/mdoc/doc-common . +It really should default to +.Tn LOCAL . +Note, if the +.Ql \&.Os +macro is not present, the bottom left corner of the page +will be ugly. +.It Li \&.Dd month day, year +The date should be written formally: +.Pp +.ne 5 +.Dl January 25, 1989 +.El +.Sh INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS +.Ss What's in a name... +The manual domain macro names are derived from the day to day +informal language used to describe commands, subroutines and related +files. +Slightly different variations of this language are used to describe +the three different aspects of writing a man page. +First, there is the description of +.Nm \-mdoc +macro request usage. +Second is the description of a +.Ux +command +.Em with +.Nm \-mdoc +macros and third, +the description of a command to a user in the verbal sense; +that is, discussion of a command in the text of a man page. +.Pp +In the first case, +.Xr troff 1 +macros are themselves a type of command; +the general syntax for a troff command is: +.Bd -filled -offset indent +\&.Va argument1 argument2 ... argument9 +.Ed +.Pp +The +.Ql \&.Va +is a macro command or request, and anything following it is an argument to +be processed. +In the second case, +the description of a +.Ux +command using the content macros is a +bit more involved; +a typical +.Sx SYNOPSIS +command line might be displayed as: +.Bd -filled -offset indent +.Nm filter +.Op Fl flag +.Ar infile outfile +.Ed +.Pp +Here, +.Nm filter +is the command name and the +bracketed string +.Fl flag +is a +.Em flag +argument designated as optional by the option brackets. +In +.Nm \-mdoc +terms, +.Ar infile +and +.Ar outfile +are +called +.Em arguments . +The macros which formatted the above example: +.Bd -literal -offset indent +\&.Nm filter +\&.Op \&Fl flag +\&.Ar infile outfile +.Ed +.Pp +In the third case, discussion of commands and command syntax +includes both examples above, but may add more detail. +The +arguments +.Ar infile +and +.Ar outfile +from the example above might be referred to as +.Em operands +or +.Em file arguments . +Some command-line argument lists are quite long: +.Bl -tag -width make -offset indent +.It Nm make +.Op Fl eiknqrstv +.Op Fl D Ar variable +.Op Fl d Ar flags +.Op Fl f Ar makefile +.Bk -words +.Op Fl I Ar directory +.Ek +.Op Fl j Ar max_jobs +.Op Ar variable=value +.Bk -words +.Op Ar target ... +.Ek +.El +.Pp +Here one might talk about the command +.Nm make +and qualify the argument +.Ar makefile , +as an argument to the flag, +.Fl f , +or discuss the optional +file +operand +.Ar target . +In the verbal context, such detail can prevent confusion, +however the +.Nm \-mdoc +package +does not have a macro for an argument +.Em to +a flag. +Instead the +.Ql \&Ar +argument macro is used for an operand or file argument like +.Ar target +as well as an argument to a flag like +.Ar variable . +The make command line was produced from: +.Bd -literal -offset indent +\&.Nm make +\&.Op Fl eiknqrstv +\&.Op Fl D Ar variable +\&.Op Fl d Ar flags +\&.Op Fl f Ar makefile +\&.Op Fl I Ar directory +\&.Op Fl j Ar max_jobs +\&.Op Ar variable=value +\&.Bk -words +\&.Op Ar target ... +\&.Ek +.Ed +.Pp +The +.Ql \&.Bk +and +.Ql \&.Ek +macros are explained in +.Sx Keeps . +.Ss General Syntax +The manual domain and general text domain macros share a similar +syntax with a few minor deviations: +.Ql \&.Ar , +.Ql \&.Fl , +.Ql \&.Nm , +and +.Ql \&.Pa +differ only when called without arguments; +.Ql \&.Fn +and +.Ql \&.Xr +impose an order on their argument lists +and the +.Ql \&.Op +and +.Ql \&.Fn +macros +have nesting limitations. +All content macros +are capable of recognizing and properly handling punctuation, +provided each punctuation character is separated by a leading space. +If a request is given: +.Pp +.Dl \&.Li sptr, ptr), +.Pp +The result is: +.Pp +.Dl Li sptr, ptr), +.Pp +The punctuation is not recognized and all is output in the +literal font. If the punctuation is separated by a leading +white space: +.Pp +.Dl \&.Li "sptr , ptr ) ," +.Pp +The result is: +.Pp +.Dl Li sptr , ptr ) , +.Pp +The punctuation is now recognized and is output in the +default font distinguishing it from the strings in literal font. +.Pp +To remove the special meaning from a punctuation character +escape it with +.Ql \e& . +.Xr Troff +is limited as a macro language, and has difficulty +when presented with a string containing +a member of the mathematical, logical or +quotation set: +.Bd -literal -offset indent-two +\&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"} +.Ed +.Pp +The problem is that +.Xr troff +may assume it is supposed to actually perform the operation +or evaluation suggested by the characters. +To prevent the accidental evaluation of these characters, +escape them with +.Ql \e& . +Typical syntax is shown in the first content macro displayed +below, +.Ql \&.Ad . +.Sh MANUAL DOMAIN +.Ss Address Macro +The address macro identifies an address construct +of the form addr1[,addr2[,addr3]]. +.Pp +.Dl Usage: .Ad address ... \*(Pu +.Bl -tag -width "\&.Ad f1 , f2 , f3 :" -compact -offset 14n +.It Li \&.Ad addr1 +.Ad addr1 +.It Li \&.Ad addr1\ . +.Ad addr1 . +.It Li \&.Ad addr1\ , file2 +.Ad addr1 , file2 +.It Li \&.Ad f1\ , f2\ , f3\ : +.Ad f1 , f2 , f3 : +.It Li \&.Ad addr\ )\ )\ , +.Ad addr ) ) , +.El +.Pp +It is an error to call +.Ql \&.Ad +without arguments. +.Ql \&.Ad +is callable by other macros and is parsed. +.Ss Author Name +The +.Ql \&.An +macro is used to specify the name of the author of the item being +documented, or the name of the author of the actual manual page. +Any remaining arguments after the name information are assumed +to be punctuation. +.Pp +.Dl Usage: .An author_name \*(Pu +.Bl -tag -width "\&.An Joe Author ) ) ," -compact -offset 14n +.It Li \&.An Joe\ Author +.An Joe Author +.It Li \&.An Joe\ Author\ , +.An Joe\ Author , +.It Li \&.An Joe\ Author\ \&Aq\ nobody@FreeBSD.ORG +.An Joe Author Aq nobody@FreeBSD.ORG +.It Li \&.An Joe\ Author\ )\ )\ , +.An Joe Author ) ) , +.El +.Pp +The +.Ql \&.An +macro is parsed and is callable. +It is an error to call +.Ql \&.An +without +any arguments. +.Ss Argument Macro +The +.Ql \&.Ar +argument macro may be used whenever +a command-line argument is referenced. +.Pp +.Dl Usage: .Ar argument ... \*(Pu +.Bl -tag -width "\&.Ar file1 file2" -compact -offset 15n +.It Li \&.Ar +.Ar +.It Li \&.Ar file1 +.Ar file1 +.It Li \&.Ar file1\ . +.Ar file1 . +.It Li \&.Ar file1 file2 +.Ar file1 file2 +.It Li \&.Ar f1 f2 f3\ : +.Ar f1 f2 f3 : +.It Li \&.Ar file\ )\ )\ , +.Ar file ) ) , +.El +.Pp +If +.Ql \&.Ar +is called without arguments, +.Ql \&Ar +is assumed. +The +.Ql \&.Ar +macro is parsed and is callable. +.Ss Configuration Declaration (section four only) +The +.Ql \&.Cd +macro is used to demonstrate a +.Xr config 8 +declaration for a device interface in a section four manual. +This macro accepts quoted arguments (double quotes only). +.Pp +.Bl -tag -width "device le0 at scode?" -offset indent +.It Cd "device le0 at scode?" +produced by: +.Ql ".Cd device le0 at scode?" . +.El +.Ss Command Modifier +The command modifier is identical to the +.Ql \&.Fl +(flag) command with the exception +the +.Ql \&.Cm +macro does not assert a dash +in front of every argument. +Traditionally flags are marked by the +preceding dash, some commands or subsets of commands do not use them. +Command modifiers may also be specified in conjunction with interactive +commands such as editor commands. +See +.Sx Flags . +.Ss Defined Variables +A variable which is defined in an include file is specified +by the macro +.Ql \&.Dv . +.Pp +.Dl Usage: .Dv defined_variable ... \*(Pu +.Bl -tag -width "\&.Dv MAXHOSTNAMELEN" -compact -offset 14n +.It Li ".Dv MAXHOSTNAMELEN" +.Dv MAXHOSTNAMELEN +.It Li ".Dv TIOCGPGRP )" +.Dv TIOCGPGRP ) +.El +.Pp +It is an error to call +.Ql \&.Dv +without arguments. +.Ql \&.Dv +is parsed and is callable. +.Ss Errno's (Section two only) +The +.Ql \&.Er +errno macro specifies the error return value +for section two library routines. +The second example +below shows +.Ql \&.Er +used with the +.Ql \&.Bq +general text domain macro, as it would be used in +a section two manual page. +.Pp +.Dl Usage: .Er ERRNOTYPE ... \*(Pu +.Bl -tag -width "\&.Bq Er ENOTDIR" -compact -offset 14n +.It Li \&.Er ENOENT +.Er ENOENT +.It Li \&.Er ENOENT\ )\ ; +.Er ENOENT ) ; +.It Li \&.Bq \&Er ENOTDIR +.Bq Er ENOTDIR +.El +.Pp +It is an error to call +.Ql \&.Er +without arguments. +The +.Ql \&.Er +macro is parsed and is callable. +.Ss Environment Variables +The +.Ql \&.Ev +macro specifies an environment variable. +.Pp +.Dl Usage: .Ev argument ... \*(Pu +.Bl -tag -width "\&.Ev PRINTER ) ) ," -compact -offset 14n +.It Li \&.Ev DISPLAY +.Ev DISPLAY +.It Li \&.Ev PATH\ . +.Ev PATH . +.It Li \&.Ev PRINTER\ )\ )\ , +.Ev PRINTER ) ) , +.El +.Pp +It is an error to call +.Ql \&.Ev +without arguments. +The +.Ql \&.Ev +macro is parsed and is callable. +.Ss Function Argument +The +.Ql \&.Fa +macro is used to refer to function arguments (parameters) +outside of the +.Sx SYNOPSIS +section of the manual or inside +the +.Sx SYNOPSIS +section should a parameter list be too +long for the +.Ql \&.Fn +macro and the enclosure macros +.Ql \&.Fo +and +.Ql \&.Fc +must be used. +.Ql \&.Fa +may also be used to refer to structure members. +.Pp +.Dl Usage: .Fa function_argument ... \*(Pu +.Bl -tag -width "\&.Fa d_namlen\ )\ )\ ," -compact -offset 14n +.It Li \&.Fa d_namlen\ )\ )\ , +.Fa d_namlen ) ) , +.It Li \&.Fa iov_len +.Fa iov_len +.El +.Pp +It is an error to call +.Ql \&.Fa +without arguments. +.Ql \&.Fa +is parsed and is callable. +.Ss Function Declaration +The +.Ql \&.Fd +macro is used in the +.Sx SYNOPSIS +section with section two or three +functions. +The +.Ql \&.Fd +macro does not call other macros and is not callable by other +macros. +.Pp +.Dl Usage: .Fd include_file (or defined variable) +.Pp +In the +.Sx SYNOPSIS +section a +.Ql \&.Fd +request causes a line break if a function has already been presented +and a break has not occurred. +This leaves a nice vertical space +in between the previous function call and the declaration for the +next function. +.Ss Flags +The +.Ql \&.Fl +macro handles command-line flags. +It prepends +a dash, +.Ql \- , +to the flag. +For interactive command flags, which +are not prepended with a dash, the +.Ql \&.Cm +(command modifier) +macro is identical, but without the dash. +.Pp +.Dl Usage: .Fl argument ... \*(Pu +.Bl -tag -width "\&.Fl \-s \-t \-v" -compact -offset 14n +.It Li \&.Fl +.Fl +.It Li \&.Fl cfv +.Fl cfv +.It Li \&.Fl cfv\ . +.Fl cfv . +.It Li \&.Fl s v t +.Fl s v t +.It Li \&.Fl -\ , +.Fl - , +.It Li \&.Fl xyz\ )\ , +.Fl xyz ) , +.El +.Pp +The +.Ql \&.Fl +macro without any arguments results +in a dash representing \fIstdin\fP/\fIstdout\fP. +Note that giving +.Ql \&.Fl +a single dash, will result in two dashes. +The +.Ql \&.Fl +macro is parsed and is callable. +.Ss Functions (library routines) +The .Fn macro is modeled on ANSI C conventions. +.Bd -literal +Usage: .Fn [type] function [[type] parameters ... \*(Pu] +.Ed +.Bl -tag -width "\&.Fn _int align_ _const * char *sptrsxx" -compact +.It Li "\&.Fn getchar" +.Fn getchar +.It Li "\&.Fn strlen ) ," +.Fn strlen ) , +.It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" , +.Fn "int align" "const * char *sptrs" , +.El +.Pp +It is an error to call +.Ql \&.Fn +without any arguments. +The +.Ql \&.Fn +macro +is parsed and is callable, +note that any call to another macro signals the end of +the +.Ql \&.Fn +call (it will close-parenthesis at that point). +.Pp +For functions that have more than eight parameters (and this +is rare), the +macros +.Ql \&.Fo +(function open) +and +.Ql \&.Fc +(function close) +may be used with +.Ql \&.Fa +(function argument) +to get around the limitation. +For example: +.Bd -literal -offset indent +\&.Fo "int res_mkquery" +\&.Fa "int op" +\&.Fa "char *dname" +\&.Fa "int class" +\&.Fa "int type" +\&.Fa "char *data" +\&.Fa "int datalen" +\&.Fa "struct rrec *newrr" +\&.Fa "char *buf" +\&.Fa "int buflen" +\&.Fc +.Ed +.Pp +Produces: +.Bd -filled -offset indent +.Fo "int res_mkquery" +.Fa "int op" +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "char *data" +.Fa "int datalen" +.Fa "struct rrec *newrr" +.Fa "char *buf" +.Fa "int buflen" +.Fc +.Ed +.Pp +The +.Ql \&.Fo +and +.Ql \&.Fc +macros are parsed and are callable. +In the +.Sx SYNOPSIS +section, the function will always begin at +the beginning of line. +If there is more than one function +presented in the +.Sx SYNOPSIS +section and a function type has not been +given, a line break will occur, leaving a nice vertical space +between the current function name and the one prior. +At the moment, +.Ql \&.Fn +does not check its word boundaries +against troff line lengths and may split across a newline +ungracefully. +This will be fixed in the near future. +.Ss Function Type +This macro is intended for the +.Sx SYNOPSIS +section. +It may be used +anywhere else in the man page without problems, but its main purpose +is to present the function type in kernel normal form for the +.Sx SYNOPSIS +of sections two and three +(it causes a line break allowing the function name to appear +on the next line). +.Pp +.Dl Usage: .Ft type ... \*(Pu +.Bl -tag -width "\&.Ft struct stat" -offset 14n -compact +.It Li \&.Ft struct stat +.Ft struct stat +.El +.Pp +The +.Ql \&.Ft +request is not callable by other macros. +.Ss Interactive Commands +The +.Ql \&.Ic +macro designates an interactive or internal command. +.Pp +.Dl Usage: .Ic argument ... \*(Pu +.Bl -tag -width "\&.Ic setenv , unsetenvxx" -compact -offset 14n +.It Li \&.Ic :wq +.Ic :wq +.It Li \&.Ic do while {...} +.Ic do while {...} +.It Li \&.Ic setenv\ , unsetenv +.Ic setenv , unsetenv +.El +.Pp +It is an error to call +.Ql \&.Ic +without arguments. +The +.Ql \&.Ic +macro is parsed and is callable. +.Ss Name Macro +The +.Ql \&.Nm +macro is used for the document title or subject name. +It has the peculiarity of remembering the first +argument it was called with, which should +always be the subject name of the page. +When called without +arguments, +.Ql \&.Nm +regurgitates this initial name for the sole purpose +of making less work for the author. +Note: +a section two +or three document function name is addressed with the +.Ql \&.Nm +in the +.Sx NAME +section, and with +.Ql \&.Fn +in the +.Sx SYNOPSIS +and remaining sections. +For interactive commands, such as the +.Ql while +command keyword in +.Xr csh 1 , +the +.Ql \&.Ic +macro should be used. +While the +.Ql \&.Ic +is nearly identical +to +.Ql \&.Nm , +it can not recall the first argument it was invoked with. +.Pp +.Dl Usage: .Nm argument ... \*(Pu +.Bl -tag -width "\&.Nm mdoc.sample" -compact -offset 14n +.It Li \&.Nm mdoc.sample +.Nm mdoc.sample +.It Li \&.Nm \e-mdoc +.Nm \-mdoc . +.It Li \&.Nm foo\ )\ )\ , +.Nm foo ) ) , +.It Li \&.Nm +.Nm +.El +.Pp +The +.Ql \&.Nm +macro is parsed and is callable. +.Ss Options +The +.Ql \&.Op +macro +places option brackets around the any remaining arguments on the command +line, and places any +trailing punctuation outside the brackets. +The macros +.Ql \&.Oc +and +.Ql \&.Oo +may be used across one or more lines. +.Pp +.Dl Usage: .Op options ... \*(Pu +.Bl -tag -width "\&.Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent +.It Li \&.Op +.Op +.It Li ".Op Fl k" +.Op Fl k +.It Li ".Op Fl k ) ." +.Op Fl k ) . +.It Li ".Op Fl k Ar kookfile" +.Op Fl k Ar kookfile +.It Li ".Op Fl k Ar kookfile ," +.Op Fl k Ar kookfile , +.It Li ".Op Ar objfil Op Ar corfil" +.Op Ar objfil Op Ar corfil +.It Li ".Op Fl c Ar objfil Op Ar corfil ," +.Op Fl c Ar objfil Op Ar corfil , +.It Li \&.Op word1 word2 +.Op word1 word2 +.El +.Pp +The +.Ql \&.Oc +and +.Ql \&.Oo +macros: +.Bd -literal -offset indent +\&.Oo +\&.Op \&Fl k \&Ar kilobytes +\&.Op \&Fl i \&Ar interval +\&.Op \&Fl c \&Ar count +\&.Oc +.Ed +.Pp +Produce: +.Oo +.Op Fl k Ar kilobytes +.Op Fl i Ar interval +.Op Fl c Ar count +.Oc +.Pp +The macros +.Ql \&.Op , +.Ql \&.Oc +and +.Ql \&.Oo +are parsed and are callable. +.Ss Pathnames +The +.Ql \&.Pa +macro formats pathnames or filenames. +.Pp +.Dl Usage: .Pa pathname \*(Pu +.Bl -tag -width "\&.Pa /tmp/fooXXXXX ) ." -compact -offset 14n +.It Li \&.Pa /usr/share +.Pa /usr/share +.It Li \&.Pa /tmp/fooXXXXX\ )\ . +.Pa /tmp/fooXXXXX ) . +.El +.Pp +The +.Ql \&.Pa +macro is parsed and is callable. +.Ss Variables +Generic variable reference: +.Pp +.Dl Usage: .Va variable ... \*(Pu +.Bl -tag -width "\&.Va char s ] ) ) ," -compact -offset 14n +.It Li \&.Va count +.Va count +.It Li \&.Va settimer , +.Va settimer , +.It Li \&.Va int\ *prt\ )\ : +.Va int\ *prt ) : +.It Li \&.Va char\ s\ ]\ )\ )\ , +.Va char\ s ] ) ) , +.El +.Pp +It is an error to call +.Ql \&.Va +without any arguments. +The +.Ql \&.Va +macro is parsed and is callable. +.Ss Manual Page Cross References +The +.Ql \&.Xr +macro expects the first argument to be +a manual page name, and the second argument, if it exists, +to be either a section page number or punctuation. +Any +remaining arguments are assumed to be punctuation. +.Pp +.Dl Usage: .Xr man_page [1,...,8] \*(Pu +.Bl -tag -width "\&.Xr mdoc 7 ) ) ," -compact -offset 14n +.It Li \&.Xr mdoc +.Xr mdoc +.It Li \&.Xr mdoc\ , +.Xr mdoc , +.It Li \&.Xr mdoc 7 +.Xr mdoc 7 +.It Li \&.Xr mdoc 7\ )\ )\ , +.Xr mdoc 7 ) ) , +.El +.Pp +The +.Ql \&.Xr +macro is parsed and is callable. +It is an error to call +.Ql \&.Xr +without +any arguments. +.Sh GENERAL TEXT DOMAIN +.Ss AT&T Macro +.Bd -literal -offset indent -compact +Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... \*(Pu +.Ed +.Bl -tag -width "\&.At v6 ) ," -compact -offset 14n +.It Li ".At" +.At +.It Li ".At v6 ." +.At v6 . +.El +.Pp +The +.Ql \&.At +macro is +.Em not +parsed and +.Em not +callable +It accepts at most two arguments. +.Ss BSD Macro +.Dl Usage: .Bx [Version/release] ... \*(Pu +.Bl -tag -width "\&.Bx 4.3 ) ," -compact -offset 14n +.It Li ".Bx" +.Bx +.It Li ".Bx 4.3 ." +.Bx 4.3 . +.El +.Pp +The +.Ql \&.Bx +macro is parsed and is callable. +.Ss FreeBSD Macro +.Bd -literal -offset indent -compact +Usage: .Fx Version.release ... \*(Pu +.Ed +.Bl -tag -width "\&.Fx 2.2 ) ," -compact -offset 14n +.It Li ".Fx 2.2 ." +.Fx 2.2 . +.El +.Pp +The +.Ql \&.Fx +macro is +.Em not +parsed and +.Em not +callable +It accepts at most two arguments. +.Ss UNIX Macro +.Dl Usage: .Ux ... \*(Pu +.Bl -tag -width "\&.Ux 4.3 ) ," -compact -offset 14n +.It Li ".Ux" +.Ux +.El +.Pp +The +.Ql \&.Ux +macro is parsed and is callable. +.Ss Enclosure and Quoting Macros +The concept of enclosure is similar to quoting. +The object being to enclose one or more strings between +a pair of characters like quotes or parentheses. +The terms quoting and enclosure are used +interchangeably throughout this document. +Most of the +one line enclosure macros end +in small letter +.Ql q +to give a hint of quoting, but there are a few irregularities. +For each enclosure macro +there is also a pair of open and close macros which end +in small letters +.Ql o +and +.Ql c +respectively. +These can be used across one or more lines of text +and while they have nesting limitations, the one line quote macros +can be used inside +of them. +.Pp +.ne 5 +.Bd -filled -offset indent +.Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX +.Em " Quote Close Open Function Result" +\&.Aq .Ac .Ao Angle Bracket Enclosure +\&.Bq .Bc .Bo Bracket Enclosure [string] +\&.Dq .Dc .Do Double Quote ``string'' + .Ec .Eo Enclose String (in XX) XXstringXX +\&.Pq .Pc .Po Parenthesis Enclosure (string) +\&.Ql Quoted Literal `st' or string +\&.Qq .Qc .Qo Straight Double Quote "string" +\&.Sq .Sc .So Single Quote `string' +.El +.Ed +.Pp +Except for the irregular macros noted below, all +of the quoting macros are parsed and callable. +All handle punctuation properly, as long as it +is presented one character at a time and separated by spaces. +The quoting macros examine opening and closing punctuation +to determine whether it comes before or after the +enclosing string +This makes some nesting possible. +.Bl -tag -width xxx,xxxx +.It Li \&.Ec , \&.Eo +These macros expect the first argument to be the +opening and closing strings respectively. +.It Li \&.Ql +The quoted literal macro behaves differently for +.Xr troff +than +.Xr nroff . +If formatted with +.Xr nroff , +a quoted literal is always quoted. +If formatted with +troff, an item is quoted only if the width +of the item is less than three constant width characters. +This is to make short strings more visible where the font change +to literal (constant width) is less noticeable. +.It Li \&.Pf +The prefix macro is not callable, but it is parsed: +.Bl -tag -width "(namexx" -offset indent +.It Li ".Pf ( Fa name2" +becomes +.Pf ( Fa name2 . +.El +.Pp +The +.Ql \&.Ns +(no space) macro performs the analogous suffix function. +.El +.Pp +.ne 4 +Examples of quoting: +.Bl -tag -width "\&.Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent +.It Li \&.Aq +.Aq +.It Li \&.Aq \&Ar ctype.h\ )\ , +.Aq Ar ctype.h ) , +.It Li \&.Bq +.Bq +.It Li \&.Bq \&Em Greek \&, French \&. +.Bq Em Greek , French . +.It Li \&.Dq +.Dq +.It Li ".Dq string abc ." +.Dq string abc . +.It Li ".Dq \'^[A-Z]\'" +.Dq \'^[A-Z]\' +.It Li "\&.Ql man mdoc" +.Ql man mdoc +.It Li \&.Qq +.Qq +.It Li "\&.Qq string ) ," +.Qq string ) , +.It Li "\&.Qq string Ns )," +.Qq string Ns ), +.It Li \&.Sq +.Sq +.It Li "\&.Sq string +.Sq string +.El +.Pp +For a good example of nested enclosure macros, see the +.Ql \&.Op +option macro. +It was created from the same +underlying enclosure macros as those presented in the list +above. +The +.Ql \&.Xo +and +.Ql \&.Xc +extended argument list macros +were also built from the same underlying routines and are a good +example of +.Nm \-mdoc +macro usage at its worst. +.Ss No\-Op or Normal Text Macro +The macro +.Ql \&.No +is +a hack for words in a macro command line which should +.Em not +be formatted and follows the conventional syntax +for content macros. +.Ss No Space Macro +The +.Ql \&.Ns +macro eliminates unwanted spaces in between macro requests. +It is useful for old style argument lists where there is no space +between the flag and argument: +.Bl -tag -width "\&.Op Fl I Ns Ar directoryxx" -offset indent +.It Li ".Op Fl I Ns Ar directory" +produces +.Op Fl I Ns Ar directory +.El +.Pp +Note: the +.Ql \&.Ns +macro always invokes the +.Ql \&.No +macro after eliminating the space unless another macro name +follows it. +The macro +.Ql \&.Ns +is parsed and is callable. +.Ss Section Cross References +The +.Ql \&.Sx +macro designates a reference to a section header +within the same document. +It is parsed and is callable. +.Pp +.Bl -tag -width "Li \&.Sx FILES" -offset 14n +.It Li \&.Sx FILES +.Sx FILES +.El +.Ss References and Citations +The following macros make a modest attempt to handle references. +At best, the macros make it convenient to manually drop in a subset of +refer style references. +.Pp +.Bl -tag -width 6n -offset indent -compact +.It Li ".Rs" +Reference Start. +Causes a line break and begins collection +of reference information until the +reference end macro is read. +.It Li ".Re" +Reference End. +The reference is printed. +.It Li ".%A" +Reference author name, one name per invocation. +.It Li ".%B" +Book title. +.It Li ".\&%C" +City/place. +.It Li ".\&%D" +Date. +.It Li ".%J" +Journal name. +.It Li ".%N" +Issue number. +.It Li ".%O" +Optional information. +.It Li ".%P" +Page number. +.It Li ".%R" +Report name. +.It Li ".%T" +Title of article. +.It Li ".%V" +Volume(s). +.El +.Pp +The macros beginning with +.Ql % +are not callable, and are parsed only for the trade name macro which +returns to its caller. +(And not very predictably at the moment either.) +The purpose is to allow trade names +to be pretty printed in +.Xr troff Ns / Ns Xr ditroff +output. +.Ss Return Values +The +.Ql \&.Rv +macro generates text for use in the +.Sx RETURN VALUE +section. +.Pp +.Dl Usage: .Rv [-std function] +.Pp +.Ql \&.Rv -std atexit +will generate the following text: +.Pp +.\" fake section 3 to avoid error message from Rv +.\".ds cH 3 +.ds section 3 +.Rv -std atexit +.\" and back to 7 again +.\".ds cH 7 +.ds section 7 +.Pp +The +.Fl std +option is valid only for manual page sections 2 and 3. +.Ss Trade Names (or Acronyms and Type Names) +The trade name macro is generally a small caps macro for +all uppercase words longer than two characters. +.Pp +.Dl Usage: .Tn symbol ... \*(Pu +.Bl -tag -width "\&.Tn ASCII" -compact -offset 14n +.It Li \&.Tn DEC +.Tn DEC +.It Li \&.Tn ASCII +.Tn ASCII +.El +.Pp +The +.Ql \&.Tn +macro +is parsed and is callable by other macros. +.Ss Extended Arguments +The +.Ql \&.Xo +and +.Ql \&.Xc +macros allow one to extend an argument list +on a macro boundary. +Argument lists cannot +be extended within a macro +which expects all of its arguments on one line such +as +.Ql \&.Op . +.Pp +Here is an example of +.Ql \&.Xo +using the space mode macro to turn spacing off: +.Bd -literal -offset indent +\&.Sm off +\&.It Xo Sy I Ar operation +\&.No \een Ar count No \een +\&.Xc +\&.Sm on +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.Sm off +.It Xo Sy I Ar operation +.No \en Ar count No \en +.Xc +.Sm on +.El +.Ed +.Pp +Another one: +.Bd -literal -offset indent +\&.Sm off +\&.It Cm S No \&/ Ar old_pattern Xo +\&.No \&/ Ar new_pattern +\&.No \&/ Op Cm g +\&.Xc +\&.Sm on +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.Sm off +.It Cm S No \&/ Ar old_pattern Xo +.No \&/ Ar new_pattern +.No \&/ Op Cm g +.Xc +.Sm on +.El +.Ed +.Pp +Another example of +.Ql \&.Xo +and using enclosure macros: +Test the value of a variable. +.Bd -literal -offset indent +\&.It Xo +\&.Ic .ifndef +\&.Oo \e&! Oc Ns Ar variable +\&.Op Ar operator variable ... +\&.Xc +.Ed +.Pp +Produces +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.It Xo +.Ic .ifndef +.Oo \&! Oc Ns Ar variable +.Op Ar operator variable ... +.Xc +.El +.Ed +.Pp +All of the above examples have used the +.Ql \&.Xo +macro on the argument list of the +.Ql \&.It +(list-item) +macro. +The extend macros are not used very often, and when they are +it is usually to extend the list-item argument list. +Unfortunately, this is also where the extend macros are the +most finicky. +In the first two examples, spacing was turned off; +in the third, spacing was desired in part of the output but +not all of it. +To make these macros work in this situation make sure +the +.Ql \&.Xo +and +.Ql \&.Xc +macros are placed as shown in the third example. +If the +.Ql \&.Xo +macro is not alone on the +.Ql \&.It +argument list, spacing will be unpredictable. +The +.Ql \&.Ns +(no space macro) +must not occur as the first or last macro on a line +in this situation. +Out of 900 manual pages (about 1500 actual pages) +currently released with +.Bx +only fifteen use the +.Ql \&.Xo +macro. +.Sh PAGE STRUCTURE DOMAIN +.Ss Section Headers +The first three +.Ql \&.Sh +section header macros +list below are required in every +man page. +The remaining section headers +are recommended at the discretion of the author +writing the manual page. +The +.Ql \&.Sh +macro can take up to nine arguments. +It is parsed and but is not callable. +.Bl -tag -width "\&.Sh SYNOPSIS" +.It \&.Sh NAME +The +.Ql \&.Sh NAME +macro is mandatory. +If not specified, +the headers, footers and page layout defaults +will not be set and things will be rather unpleasant. +The +.Sx NAME +section consists of at least three items. +The first is the +.Ql \&.Nm +name macro naming the subject of the man page. +The second is the Name Description macro, +.Ql \&.Nd , +which separates the subject +name from the third item, which is the description. +The +description should be the most terse and lucid possible, +as the space available is small. +.It \&.Sh SYNOPSIS +The +.Sx SYNOPSIS +section describes the typical usage of the +subject of a man page. +The macros required +are either +.Ql ".Nm" , +.Ql ".Cd" , +.Ql ".Fn" , +(and possibly +.Ql ".Fo" , +.Ql ".Fc" , +.Ql ".Fd" , +.Ql ".Ft" +macros). +The function name +macro +.Ql ".Fn" +is required +for manual page sections 2 and 3, the command and general +name macro +.Ql \&.Nm +is required for sections 1, 5, 6, 7, 8. +Section 4 manuals require a +.Ql ".Nm" , +.Ql ".Fd" +or a +.Ql ".Cd" +configuration device usage macro. +Several other macros may be necessary to produce +the synopsis line as shown below: +.El +.Pp +.Bd -filled -offset indent +.Nm cat +.Op Fl benstuv +.Op Fl +.Ar +.Ed +.Pp +The following macros were used: +.Pp +.Dl \&.Nm cat +.Dl \&.Op \&Fl benstuv +.Dl \&.Op \&Fl +.Dl \&.Ar +.Pp +.Sy Note : +The macros +.Ql \&.Op , +.Ql \&.Fl , +and +.Ql \&.Ar +recognize the pipe bar character +.Ql \*(Ba , +so a command line such as: +.Pp +.Dl ".Op Fl a | Fl b" +.Pp +will not go orbital. +.Xr Troff +normally interprets a \*(Ba as a special operator. +See +.Sx PREDEFINED STRINGS +for a usable \*(Ba +character in other situations. +.Bl -tag +.It \&.Sh DESCRIPTION +In most cases the first text in the +.Sx DESCRIPTION +section +is a brief paragraph on the command, function or file, +followed by a lexical list of options and respective +explanations. +To create such a list, the +.Ql \&.Bl +begin-list, +.Ql \&.It +list-item and +.Ql \&.El +end-list +macros are used (see +.Sx Lists and Columns +below). +.El +.Pp +The following +.Ql \&.Sh +section headers are part of the +preferred manual page layout and must be used appropriately +to maintain consistency. +They are listed in the order +in which they would be used. +.Bl -tag -width SYNOPSIS +.It \&.Sh ENVIRONMENT +The +.Sx ENVIRONMENT +section should reveal any related +environment +variables and clues to their behavior and/or usage. +.It \&.Sh EXAMPLES +There are several ways to create examples. +See +the +.Sx EXAMPLES +section below +for details. +.It \&.Sh FILES +Files which are used or created by the man page subject +should be listed via the +.Ql \&.Pa +macro in the +.Sx FILES +section. +.It \&.Sh SEE ALSO +References to other material on the man page topic and +cross references to other relevant man pages should +be placed in the +.Sx SEE ALSO +section. +Cross references +are specified using the +.Ql \&.Xr +macro. +Cross references in the +.Sx SEE ALSO +section should be sorted by section number, and then +placed in alphabetical order and comma separated. For example: +.Pp +.Xr ls 1 , +.Xr ps 1 , +.Xr group 5 , +.Xr passwd 5 . +.Pp +At this time +.Xr refer 1 +style references are not accommodated. +.It \&.Sh CONFORMING TO +If the command, library function or file adheres to a +specific implementation such as +.St -p1003.2 +or +.St -ansiC +this should be noted here. +If the +command does not adhere to any standard, its history +should be noted in the +.Sx HISTORY +section. +.It \&.Sh HISTORY +Any command which does not adhere to any specific standards +should be outlined historically in this section. +.It \&.Sh AUTHORS +Credits, if need be, should be placed here. +.It \&.Sh DIAGNOSTICS +Diagnostics from a command should be placed in this section. +.It \&.Sh ERRORS +Specific error handling, especially from library functions +(man page sections 2 and 3) should go here. +The +.Ql \&.Er +macro is used to specify an errno. +.It \&.Sh BUGS +Blatant problems with the topic go here... +.El +.Pp +User specified +.Ql \&.Sh +sections may be added, +for example, this section was set with: +.Bd -literal -offset 14n +\&.Sh PAGE STRUCTURE DOMAIN +.Ed +.Ss Paragraphs and Line Spacing. +.Bl -tag -width 6n +.It \&.Pp +The +.Ql \&.Pp +paragraph command may +be used to specify a line space where necessary. +The macro is not necessary after a +.Ql \&.Sh +or +.Ql \&.Ss +macro or before +a +.Ql \&.Bl +macro. +(The +.Ql \&.Bl +macro asserts a vertical distance unless the -compact flag is given). +.El +.\" This worked with version one, need to redo for version three +.\" .Pp +.\" .Ds I +.\" .Cw (ax+bx+c) \ is\ produced\ by\ \& +.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& +.\" .Cl Cx \t\t +.\" .Li \&.Cx\ ( +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va ax +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy \+ +.\" .Cx +.\" .Cl Cx \&(\& +.\" .Va ax +.\" .Cx + +.\" .Va by +.\" .Cx + +.\" .Va c ) +.\" .Cx \t +.\" .Em is produced by +.\" .Cx \t +.\" .Li \&.Va by +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy \+ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va c ) +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.\" This example shows the same equation in a different format. +.\" The spaces +.\" around the +.\" .Li \&+ +.\" signs were forced with +.\" .Li \e : +.\" .Pp +.\" .Ds I +.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& +.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& +.\" .Cl Cx \t\t +.\" .Li \&.Cx\ ( +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va a +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy x +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx \e\ +\e\ \e& +.\" .Cx +.\" .Cl Cx \&(\& +.\" .Va a +.\" .Sy x +.\" .Cx \ +\ \& +.\" .Va b +.\" .Sy y +.\" .Cx \ +\ \& +.\" .Va c ) +.\" .Cx \t +.\" .Em is produced by +.\" .Cl Cx \t\t +.\" .Li \&.Va b +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy y +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx \e\ +\e\ \e& +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va c ) +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.\" The incantation below was +.\" lifted from the +.\" .Xr adb 1 +.\" manual page: +.\" .Pp +.\" .Ds I +.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by +.\" .Cl Cx \t\t +.\" .Li \&.Cx Op Sy ?/ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Nm m +.\" .Cx +.\" .Cl Cx Op Sy ?/ +.\" .Nm m +.\" .Ad \ b1 e1 f1 +.\" .Op Sy ?/ +.\" .Cx \t +.\" .Em is produced by +.\" .Cx \t +.\" .Li \&.Ar \e\ b1 e1 f1 +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Op Sy ?/ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.Ss Keeps +The only keep that is implemented at this time is for words. +The macros are +.Ql \&.Bk +(begin-keep) +and +.Ql \&.Ek +(end-keep). +The only option that +.Ql \&.Bk +accepts is +.Fl words +and is useful for preventing line breaks in the middle of options. +In the example for the make command-line arguments (see +.Sx What's in a name ) , +the keep prevented +.Xr nroff +from placing up the +flag and the argument +on separate lines. +(Actually, the option macro used to prevent this from occurring, +but was dropped when the decision (religious) was made to force +right justified margins in +.Xr troff +as options in general look atrocious when spread across a sparse +line. +More work needs to be done with the keep macros, a +.Fl line +option needs to be added.) +.Ss Examples and Displays +There are five types of displays, a quickie one line indented display +.Ql \&.D1 , +a quickie one line literal display +.Ql \&.Dl , +and a block literal, block filled and block ragged which use +the +.Ql \&.Bd +begin-display +and +.Ql \&.Ed +end-display macros. +.Pp +.Bl -tag -width \&.Dlxx +.It Li \&.D1 +(D-one) Display one line of indented text. +This macro is parsed, but it is not callable. +.Pp +.Dl Fl ldghfstru +.Pp +The above was produced by: +.Li \&.Dl Fl ldghfstru . +.It Li \&.Dl +(D-ell) +Display one line of indented +.Em literal +text. +The +.Ql \&.Dl +example macro has been used throughout this +file. +It allows +the indent (display) of one line of text. +Its default font is set to +constant width (literal) however +it is parsed and will recognized other macros. +It is not callable however. +.Pp +.Dl % ls -ldg /usr/local/bin +.Pp +The above was produced by +.Li \&.Dl % ls -ldg /usr/local/bin . +.It Li \&.Bd +Begin-display. +The +.Ql \&.Bd +display must be ended with the +.Ql \&.Ed +macro. +Displays may be nested within displays and +lists. +.Ql \&.Bd +has the following syntax: +.Pp +.Dl ".Bd display-type [-offset offset_value] [-compact]" +.Pp +The display-type must be one of the following four types and +may have an offset specifier for indentation: +.Ql \&.Bd . +.El +.Pp +.Bl -tag -width "file file_name " -compact +.It Fl ragged +Display a block of text as typed, +right (and left) margin edges are left ragged. +.It Fl filled +Display a filled (formatted) block. +The block of text is formatted (the edges are filled \- +not left unjustified). +.It Fl literal +Display a literal block, useful for source code or +simple tabbed or spaced text. +.It Fl file Ar file_name +The filename following the +.Fl file +flag is read and displayed. +Literal mode is +asserted and tabs are set at 8 constant width character +intervals, however any +.Xr troff/ Ns Nm \-mdoc +commands in file will be processed. +.It Fl offset Ar string +If +.Fl offset +is specified with one of the following strings, the string +is interpreted to indicate the level of indentation for the +forthcoming block of text: +.Pp +.Bl -tag -width "indent-two" -compact +.It Ar left +Align block on the current left margin, +this is the default mode of +.Ql \&.Bd . +.It Ar center +Supposedly center the block. +At this time +unfortunately, the block merely gets +left aligned about an imaginary center margin. +.It Ar indent +Indents by one default indent value or tab. +The default +indent value is also used for the +.Ql \&.D1 +display so one is guaranteed the two types of displays +will line up. +This indent is normally set to 6n or about two +thirds of an inch (six constant width characters). +.It Ar indent-two +Indents two times the default indent value. +.It Ar right +This +.Em left +aligns the block about two inches from +the right side of the page. +This macro needs +work and perhaps may never do the right thing by +.Xr troff . +.El +.It ".Ed" +End-display. +.El +.Ss Font Modes +There are five macros for changing the appearance of the manual page text: +.Bl -tag -width \&.Emxx +.It \&.Em +Text may be stressed or emphasized with the +.Ql \&.Em +macro. +The usual font for emphasis is italic. +.Pp +.Dl Usage: .Em argument ... \*(Pu +.Bl -tag -width "\&.Em vide infra ) ) ," -compact -offset 14n +.It Li ".Em does not" +.Em does not +.It Li ".Em exceed 1024 ." +.Em exceed 1024 . +.It Li ".Em vide infra ) ) ," +.Em vide infra ) ) , +.El +.Pp +The +.Ql \&.Em +macro is parsed and is callable. +It is an error to call +.Ql \&.Em +without arguments. +.It \&.Li +The +.Ql \&.Li +literal macro may be used for special characters, +variable constants, anything which should be displayed as it +would be typed. +.Pp +.Dl Usage: .Li argument ... \*(Pu +.Bl -tag -width "\&.Li cntrl-D ) ," -compact -offset 14n +.It Li \&.Li \een +.Li \en +.It Li \&.Li M1 M2 M3\ ; +.Li M1 M2 M3 ; +.It Li \&.Li cntrl-D\ )\ , +.Li cntrl-D ) , +.It Li \&.Li 1024\ ... +.Li 1024 ... +.El +.Pp +The +.Ql \&.Li +macro is parsed and is callable. +.It \&.Sy +The symbolic emphasis macro is generally a boldface macro in +either the symbolic sense or the traditional English usage. +.Pp +.Dl Usage: .Sy symbol ... \*(Pu +.Bl -tag -width "\&.Sy Important Noticex" -compact -offset 14n +.It Li \&.Sy Important Notice +.Sy Important Notice +.Pp +The +.Ql \&.Sy +macro is parsed and is callable. +Arguments to +.Ql \&.Sy +may be quoted. +.El +.It Li \&.Bf +Begin font mode. +The +.Ql \&.Bf +font mode must be ended with the +.Ql \&.Ef +macro. +Font modes may be nested within other font modes. +.Ql \&.Bf +has the following syntax: +.Pp +.Dl ".Bf font-mode" +.Pp +The font-mode must be one of the following three types: +.Ql \&.Bf . +.Pp +.Bl -tag -width "file file_name " -compact +.It Sy \&Em | Fl emphasis +Same as if the +.Ql \&.Em +macro was used for the entire block of text. +.It Sy \&Li | Fl literal +Same as if the +.Ql \&.Li +macro was used for the entire block of text. +.It Sy \&Sy | Fl symbolic +Same as if the +.Ql \&.Sy +macro was used for the entire block of text. +.El +.It ".Ef" +End font mode. +.El +.Ss Tagged Lists and Columns +There are several types of lists which may be initiated with the +.Ql ".Bl" +begin-list macro. +Items within the list +are specified with the +.Ql ".It" +item macro and +each list must end with the +.Ql ".El" +macro. +Lists may be nested within themselves and within displays. +Columns may be used inside of lists, but lists are unproven +inside of columns. +.Pp +In addition, several list attributes may be specified such as +the width of a tag, the list offset, and compactness +(blank lines between items allowed or disallowed). +Most of this document has been formatted with a tag style list +.Pq Fl tag . +For a change of pace, the list-type used to present the list-types +is an over-hanging list +.Pq Fl ohang . +This type of list is quite popular with +.Tn TeX +users, but might look a bit funny after having read many pages of +tagged lists. +The following list types are accepted by +.Ql ".Bl" : +.Pp +.Bl -ohang -compact +.It Fl bullet +.It Fl item +.It Fl enum +These three are the simplest types of lists. +Once the +.Ql ".Bl" +macro has been given, items in the list are merely +indicated by a line consisting solely of the +.Ql ".It" +macro. +For example, the source text for a simple enumerated list +would look like: +.Bd -literal -offset indent-two +\&.Bl -enum -compact +\&.It +\&Item one goes here. +\&.It +\&And item two here. +\&.It +\&Lastly item three goes here. +\&.El +.Ed +.El +.Pp +The results: +.Pp +.Bl -enum -offset indent-two -compact +.It +Item one goes here. +.It +And item two here. +.It +Lastly item three goes here. +.El +.Pp +A simple bullet list construction: +.Bd -literal -offset indent-two +\&.Bl -bullet -compact +\&.It +\&Bullet one goes here. +\&.It +\&Bullet two here. +\&.El +.Ed +.Pp +Produces: +.Bl -bullet -offset indent-two -compact +.It +Bullet one goes here. +.It +Bullet two here. +.El +.Pp +.Bl -ohang -compact +.It Fl tag +.It Fl diag +.It Fl hang +.It Fl ohang +.It Fl inset +These list-types collect arguments specified with the +.Ql \&.It +macro and create a label which may be +.Em inset +into the forthcoming text, +.Em hanged +from the forthcoming text, +.Em overhanged +from above and not indented or +.Em tagged . +This +list was constructed with the +.Ql \&Fl ohang +list-type. +The +.Ql \&.It +macro is parsed only for the inset, hang +and tag list-types and is not callable. +Here is an example of inset labels: +.El +.Bl -inset -offset indent +.It Em Tag +The tagged list (also called a tagged paragraph) is the +most common type of list used in the Berkeley manuals. +.It Em Diag +Diag lists create section four diagnostic lists +and are similar to inset lists except callable +macros are ignored. +.It Em Hang +Hanged labels are a matter of taste. +.It Em Ohang +Overhanging labels are nice when space is constrained. +.It Em Inset +Inset labels are useful for controlling blocks of +paragraphs and are valuable for converting +.Nm \-mdoc +manuals to other formats. +.El +.Pp +Here is the source text which produced the above example: +.Bd -literal -offset indent +\&.Bl -inset -offset indent +\&.It Em Tag +\&The tagged list (also called a tagged paragraph) is the +\&most common type of list used in the Berkeley manuals. +\&.It Em Diag +\&Diag lists create section four diagnostic lists +\&and are similar to inset lists except callable +\¯os are ignored. +\&.It Em Hang +\&Hanged labels are a matter of taste. +\&.It Em Ohang +\&Overhanging labels are nice when space is constrained. +\&.It Em Inset +\&Inset labels are useful for controlling blocks of +\¶graphs and are valuable for converting +\&.Nm \-mdoc +\&manuals to other formats. +\&.El +.Ed +.Pp +Here is a hanged list with two items: +.Bl -hang -offset indent +.It Em Hanged +labels appear similar to tagged lists when the +label is smaller than the label width. +.It Em Longer hanged list labels +blend in to the paragraph unlike +tagged paragraph labels. +.El +.Pp +And the unformatted text which created it: +.Bd -literal -offset indent +\&.Bl -hang -offset indent +\&.It Em Hanged +\&labels appear similar to tagged lists when the +\&label is smaller than the label width. +\&.It Em Longer hanged list labels +\&blend in to the paragraph unlike +\&tagged paragraph labels. +\&.El +.Ed +.Pp +The tagged list which follows uses an optional width specifier to control +the width of the tag. +.Pp +.Bl -tag -width "PAGEIN" -compact -offset indent +.It SL +sleep time of the process (seconds blocked) +.It PAGEIN +number of disk +.Tn I/O Ns 's +resulting from references +by the process to pages not loaded in core. +.It UID +numerical user-id of process owner +.It PPID +numerical ID of parent of process process priority +(nonpositive when in noninterruptible wait) +.El +.Pp +The raw text: +.Bd -literal -offset indent +\&.Bl -tag -width "PAGEIN" -compact -offset indent +\&.It SL +\&sleep time of the process (seconds blocked) +\&.It PAGEIN +\&number of disk +\&.Tn I/O Ns 's +\&resulting from references +\&by the process to pages not loaded in core. +\&.It UID +\&numerical user ID of process owner +\&.It PPID +\&numerical ID of parent of process process priority +\&(nonpositive when in noninterruptible wait) +\&.El +.Ed +.Pp +Acceptable width specifiers: +.Bl -tag -width Ar -offset indent +.It Fl width Ar "\&Fl" +sets the width to the default width for a flag. +All callable +macros have a default width value. +The +.Ql \&.Fl , +value is presently +set to ten constant width characters or about five sixth of +an inch. +.It Fl width Ar "24n" +sets the width to 24 constant width characters or about two +inches. +The +.Ql n +is absolutely necessary for the scaling to work correctly. +.It Fl width Ar "ENAMETOOLONG" +sets width to the constant width length of the +string given. +.It Fl width Ar "\\*qint mkfifo\\*q" +again, the width is set to the constant width of the string +given. +.El +.Pp +If a width is not specified for the tag list type, the first +time +.Ql \&.It +is invoked, an attempt is made to determine an appropriate +width. +If the first argument to +.Ql ".It" +is a callable macro, the default width for that macro will be used +as if the macro name had been supplied as the width. +However, +if another item in the list is given with a different callable +macro name, a new and nested list is assumed. +.Sh PREDEFINED STRINGS +The following strings are predefined as may be used by +preceding with the troff string interpreting sequence +.Ql \&\e*(xx +where +.Em xx +is the name of the defined string or as +.Ql \&\e*x +where +.Em x +is the name of the string. +The interpreting sequence may be used any where in the text. +.Pp +.Bl -column "String " "Nroff " "Troff " -offset indent +.It Sy "String Nroff Troff" +.It Li "<=" Ta \&<\&= Ta \*(<= +.It Li ">=" Ta \&>\&= Ta \*(>= +.It Li "Rq" Ta "''" Ta \*(Rq +.It Li "Lq" Ta "``" Ta \*(Lq +.It Li "ua" Ta ^ Ta \*(ua +.It Li "aa" Ta ' Ta \*(aa +.It Li "ga" Ta \` Ta \*(ga +.\" .It Li "sL" Ta ` Ta \*(sL +.\" .It Li "sR" Ta ' Ta \*(sR +.It Li "q" Ta \&" Ta \*q +.It Li "Pi" Ta pi Ta \*(Pi +.It Li "Ne" Ta != Ta \*(Ne +.It Li "Le" Ta <= Ta \*(Le +.It Li "Ge" Ta >= Ta \*(Ge +.It Li "Lt" Ta < Ta \*(Gt +.It Li "Gt" Ta > Ta \*(Lt +.It Li "Pm" Ta +- Ta \*(Pm +.It Li "If" Ta infinity Ta \*(If +.It Li "Na" Ta \fINaN\fP Ta \*(Na +.It Li "Ba" Ta \fR\&|\fP Ta \*(Ba +.El +.Pp +.Sy Note : +The string named +.Ql q +should be written as +.Ql \e*q +since it is only one char. +.Sh DIAGNOSTICS +The debugging facilities for +.Nm \-mdoc +are limited, but can help detect subtle errors such +as the collision of an argument name with an internal +register or macro name. +(A what?) +A register is an arithmetic storage class for +.Xr troff +with a one or two character name. +All registers internal to +.Nm \-mdoc +for +.Xr troff +and +.Xr ditroff +are two characters and +of the form such as +.Ql \&Ar , + as +.Ql \&aR +or + as +.Ql \&C\&1 . +And adding to the muddle, +.Xr troff +has its own internal registers all of which are either +two lowercase characters or a dot plus a letter or metacharacter +character. +In one of the introduction examples, it was shown how to +prevent the interpretation of a macro name with the escape sequence +.Ql \e& . +This is sufficient for the internal register names also. +.Pp +.\" Every callable macro name has a corresponding register +.\" of the same name (). +.\" There are also specific registers which have +.\" been used for stacks and arrays and are listed in the +.\" .Sx Appendix . +.\" .Bd -ragged -offset 4n +.\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'') +.\" [a-z][A-Z] registers corresponding to macro names (example ``aR'') +.\" C[0-9] argument types (example C1) +.\" O[0-9] offset stack (displays) +.\" h[0-9] horizontal spacing stack (lists) +.\" o[0-9] offset (stack) (lists) +.\" t[0-9] tag stack (lists) +.\" v[0-9] vertical spacing stack (lists) +.\" w[0-9] width tag/label stack +.\" .Ed +.\" .Pp +If a nonescaped register name is given in the argument list of a request, +unpredictable behavior will occur. +In general, any time huge portions +of text do not appear where expected in the output, or small strings +such as list tags disappear, chances are there is a misunderstanding +about an argument type in the argument list. +Your mother never intended for you to remember this evil stuff - so here +is a way to find out whether or not your arguments are valid: The +.Ql \&.Db +(debug) +macro displays the interpretation of the argument list for most +macros. +Macros such as the +.Ql \&.Pp +(paragraph) +macro do not contain debugging information. +All of the callable macros do, +and it is strongly advised whenever in doubt, +turn on the +.Ql \&.Db +macro. +.Pp +.Dl Usage: \&.Db [on | off] +.Pp +An example of a portion of text with +the debug macro placed above and below an +artificially created problem (a flag argument +.Ql \&aC +which should be +.Ql \e&aC +in order to work): +.Bd -literal -offset indent +\&.Db on +\&.Op Fl aC Ar file ) +\&.Db off +.Ed +.Pp +The resulting output: +.Bd -literal -offset indent +DEBUGGING ON +DEBUG(argv) MACRO: `.Op' Line #: 2 + Argc: 1 Argv: `Fl' Length: 2 + Space: `' Class: Executable + Argc: 2 Argv: `aC' Length: 2 + Space: `' Class: Executable + Argc: 3 Argv: `Ar' Length: 2 + Space: `' Class: Executable + Argc: 4 Argv: `file' Length: 4 + Space: ` ' Class: String + Argc: 5 Argv: `)' Length: 1 + Space: ` ' Class: Closing Punctuation or suffix + MACRO REQUEST: .Op Fl aC Ar file ) +DEBUGGING OFF +.Ed +.Pp +The first line of information tells the name of the calling +macro, here +.Ql \&.Op , +and the line number it appears on. +If one or more files are involved +(especially if text from another file is included), the line number +may be bogus. +If there is only one file, it should be accurate. +The second line gives the argument count, the argument +.Pq Ql \&Fl +and its length. +If the length of an argument is two characters, the +argument is tested to see if it is executable (unfortunately, any +register which contains a nonzero value appears executable). +The third line gives the space allotted for a class, and the +class type. +The problem here is the argument aC should not be +executable. +The four types of classes are string, executable, closing +punctuation and opening punctuation. +The last line shows the entire +argument list as it was read. +In this next example, the offending +.Ql \&aC +is escaped: +.Bd -literal -offset indent +\&.Db on +\&.Em An escaped \e&aC +\&.Db off +.Ed +.Bd -literal -offset indent +DEBUGGING ON +DEBUG(fargv) MACRO: `.Em' Line #: 2 + Argc: 1 Argv: `An' Length: 2 + Space: ` ' Class: String + Argc: 2 Argv: `escaped' Length: 7 + Space: ` ' Class: String + Argc: 3 Argv: `aC' Length: 2 + Space: ` ' Class: String + MACRO REQUEST: .Em An escaped &aC +DEBUGGING OFF +.Ed +.Pp +The argument +.Ql \e&aC +shows up with the same length of 2 as the +.Ql \e& +sequence produces a zero width, but a register +named +.Ql \e&aC +was not found and the type classified as string. +.Pp +Other diagnostics consist of usage statements and are self explanatory. +.Sh GROFF, TROFF AND NROFF +The +.Nm \-mdoc +package does not need compatibility mode with +.Xr groff . +.Pp +The package inhibits page breaks, and the headers and footers +which normally occur at those breaks with +.Xr nroff , +to make the manual more efficient for viewing on-line. +At the moment, +.Xr groff +with +.Fl T Ns Ar ascii +does eject the imaginary remainder of the page at end of file. +The inhibiting of the page breaks makes +.Xr nroff Ns 'd +files unsuitable for hardcopy. +There is a register named +.Ql \&cR +which can be set to zero in the site dependent style file +.Pa /usr/src/share/tmac/doc-nroff +to restore the old style behavior. +.Sh FILES +.Bl -tag -width /usr/share/man0/template.doc -compact +.It Pa /usr/share/tmac/doc.tmac +manual macro package +.It Pa /usr/share/misc/mdoc.template +template for writing a man page +.It Pa /usr/share/examples/mdoc/* +several example man pages +.El +.Sh BUGS +Undesirable hyphenation on the dash of a flag +argument is not yet resolved, and causes +occasional mishaps in the +.Sx DESCRIPTION +section. +(line break on the hyphen). +.Pp +Predefined strings are not declared in documentation. +.Pp +Section 3f has not been added to the header routines. +.Pp +.Ql \&.Nm +font should be changed in +.Sx NAME +section. +.Pp +.Ql \&.Fn +needs to have a check to prevent splitting up +if the line length is too short. +Occasionally it +separates the last parenthesis, and sometimes +looks ridiculous if a line is in fill mode. +.Pp +The method used to prevent header and footer page +breaks (other than the initial header and footer) when using +nroff occasionally places an unsightly partially filled line (blank) +at the would be bottom of the page. +.Pp +The list and display macros to not do any keeps +and certainly should be able to. +.\" Note what happens if the parameter list overlaps a newline +.\" boundary. +.\" to make sure a line boundary is crossed: +.\" .Bd -literal +.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[] +.\" .Ed +.\" .Pp +.\" produces, nudge nudge, +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , +.\" nudge +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] . +.\" .Pp +.\" If double quotes are used, for example: +.\" .Bd -literal +.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q +.\" .Ed +.\" .Pp +.\" produces, nudge nudge, +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , +.\" nudge +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , +.\" nudge +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" . +.\" .Pp +.\" Not a pretty sight... +.\" In a paragraph, a long parameter containing unpaddable spaces as +.\" in the former example will cause +.\" .Xr troff +.\" to break the line and spread +.\" the remaining words out. +.\" The latter example will adjust nicely to +.\" justified margins, but may break in between an argument and its +.\" declaration. +.\" In +.\" .Xr nroff +.\" the right margin adjustment is normally ragged and the problem is +.\" not as severe. +.Sh SEE ALSO +.Xr man 1 , +.Xr troff 1 , +.Xr groff_mdoc 7 , +.Xr mdoc 7 +.Sh COLOPHON +This page is part of release 4.15 of the Linux +.Em man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7 new file mode 100644 index 0000000..846f592 --- /dev/null +++ b/man7/mount_namespaces.7 @@ -0,0 +1,1072 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH MOUNT_NAMESPACES 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mount_namespaces \- overview of Linux mount namespaces +.SH DESCRIPTION +For an overview of namespaces, see +.BR namespaces (7). +.PP +Mount namespaces provide isolation of the list of mount points seen +by the processes in each namespace instance. +Thus, the processes in each of the mount namespace instances +will see distinct single-directory hierarchies. +.PP +The views provided by the +.IR /proc/[pid]/mounts , +.IR /proc/[pid]/mountinfo , +and +.IR /proc/[pid]/mountstats +files (all described in +.BR proc (5)) +correspond to the mount namespace in which the process with the PID +.IR [pid] +resides. +(All of the processes that reside in the same mount namespace +will see the same view in these files.) +.PP +When a process creates a new mount namespace using +.BR clone (2) +or +.BR unshare (2) +with the +.BR CLONE_NEWNS +flag, the mount point list for the new namespace is a +.I copy +of the caller's mount point list. +Subsequent modifications to the mount point list +.RB ( mount (2) +and +.BR umount (2)) +in either mount namespace will not (by default) affect the +mount point list seen in the other namespace +(but see the following discussion of shared subtrees). +.\" +.\" ============================================================ +.\" +.SS Restrictions on mount namespaces +Note the following points with respect to mount namespaces: +.IP * 3 +A mount namespace has an owner user namespace. +A mount namespace whose owner user namespace is different from +the owner user namespace of its parent mount namespace is +considered a less privileged mount namespace. +.IP * +When creating a less privileged mount namespace, +shared mounts are reduced to slave mounts. +(Shared and slave mounts are discussed below.) +This ensures that mappings performed in less +privileged mount namespaces will not propagate to more privileged +mount namespaces. +.IP * +.\" FIXME . +.\" What does "come as a single unit from more privileged mount" mean? +Mounts that come as a single unit from more privileged mount are +locked together and may not be separated in a less privileged mount +namespace. +(The +.BR unshare (2) +.B CLONE_NEWNS +operation brings across all of the mounts from the original +mount namespace as a single unit, +and recursive mounts that propagate between +mount namespaces propagate as a single unit.) +.IP * +The +.BR mount (2) +flags +.BR MS_RDONLY , +.BR MS_NOSUID , +.BR MS_NOEXEC , +and the "atime" flags +.RB ( MS_NOATIME , +.BR MS_NODIRATIME , +.BR MS_RELATIME ) +settings become locked +.\" commit 9566d6742852c527bf5af38af5cbb878dad75705 +.\" Author: Eric W. Biederman +.\" Date: Mon Jul 28 17:26:07 2014 -0700 +.\" +.\" mnt: Correct permission checks in do_remount +.\" +when propagated from a more privileged to +a less privileged mount namespace, +and may not be changed in the less privileged mount namespace. +.IP * +.\" (As of 3.18-rc1 (in Al Viro's 2014-08-30 vfs.git#for-next tree)) +A file or directory that is a mount point in one namespace that is not +a mount point in another namespace, may be renamed, unlinked, or removed +.RB ( rmdir (2)) +in the mount namespace in which it is not a mount point +(subject to the usual permission checks). +.IP +Previously, attempting to unlink, rename, or remove a file or directory +that was a mount point in another mount namespace would result in the error +.BR EBUSY . +That behavior had technical problems of enforcement (e.g., for NFS) +and permitted denial-of-service attacks against more privileged users. +(i.e., preventing individual files from being updated +by bind mounting on top of them). +.\" +.SH SHARED SUBTREES +After the implementation of mount namespaces was completed, +experience showed that the isolation that they provided was, +in some cases, too great. +For example, in order to make a newly loaded optical disk +available in all mount namespaces, +a mount operation was required in each namespace. +For this use case, and others, +the shared subtree feature was introduced in Linux 2.6.15. +This feature allows for automatic, controlled propagation of mount and unmount +.I events +between namespaces +(or, more precisely, between the members of a +.IR "peer group" +that are propagating events to one another). +.PP +Each mount point is marked (via +.BR mount (2)) +as having one of the following +.IR "propagation types" : +.TP +.BR MS_SHARED +This mount point shares events with members of a peer group. +Mount and unmount events immediately under this mount point will propagate +to the other mount points that are members of the peer group. +.I Propagation +here means that the same mount or unmount will automatically occur +under all of the other mount points in the peer group. +Conversely, mount and unmount events that take place under +peer mount points will propagate to this mount point. +.TP +.BR MS_PRIVATE +This mount point is private; it does not have a peer group. +Mount and unmount events do not propagate into or out of this mount point. +.TP +.BR MS_SLAVE +Mount and unmount events propagate into this mount point from +a (master) shared peer group. +Mount and unmount events under this mount point do not propagate to any peer. +.IP +Note that a mount point can be the slave of another peer group +while at the same time sharing mount and unmount events +with a peer group of which it is a member. +(More precisely, one peer group can be the slave of another peer group.) +.TP +.BR MS_UNBINDABLE +This is like a private mount, +and in addition this mount can't be bind mounted. +Attempts to bind mount this mount +.RB ( mount (2) +with the +.BR MS_BIND +flag) will fail. +.IP +When a recursive bind mount +.RB ( mount (2) +with the +.BR MS_BIND +and +.BR MS_REC +flags) is performed on a directory subtree, +any bind mounts within the subtree are automatically pruned +(i.e., not replicated) +when replicating that subtree to produce the target subtree. +.PP +For a discussion of the propagation type assigned to a new mount, +see NOTES. +.PP +The propagation type is a per-mount-point setting; +some mount points may be marked as shared +(with each shared mount point being a member of a distinct peer group), +while others are private +(or slaved or unbindable). +.PP +Note that a mount's propagation type determines whether +mounts and unmounts of mount points +.I "immediately under" +the mount point are propagated. +Thus, the propagation type does not affect propagation of events for +grandchildren and further removed descendant mount points. +What happens if the mount point itself is unmounted is determined by +the propagation type that is in effect for the +.I parent +of the mount point. +.PP +Members are added to a +.IR "peer group" +when a mount point is marked as shared and either: +.IP * 3 +the mount point is replicated during the creation of a new mount namespace; or +.IP * +a new bind mount is created from the mount point. +.PP +In both of these cases, the new mount point joins the peer group +of which the existing mount point is a member. +A mount ceases to be a member of a peer group when either +the mount is explicitly unmounted, +or when the mount is implicitly unmounted because a mount namespace is removed +(because it has no more member processes). +.PP +The propagation type of the mount points in a mount namespace +can be discovered via the "optional fields" exposed in +.IR /proc/[pid]/mountinfo . +(See +.BR proc (5) +for details of this file.) +The following tags can appear in the optional fields +for a record in that file: +.TP +.I shared:X +This mount point is shared in peer group +.IR X . +Each peer group has a unique ID that is automatically +generated by the kernel, +and all mount points in the same peer group will show the same ID. +(These IDs are assigned starting from the value 1, +and may be recycled when a peer group ceases to have any members.) +.TP +.I master:X +This mount is a slave to shared peer group +.IR X . +.TP +.IR propagate_from:X " (since Linux 2.6.26)" +.\" commit 97e7e0f71d6d948c25f11f0a33878d9356d9579e +This mount is a slave and receives propagation from shared peer group +.IR X . +This tag will always appear in conjunction with a +.IR master:X +tag. +Here, +.IR X +is the closest dominant peer group under the process's root directory. +If +.IR X +is the immediate master of the mount, +or if there is no dominant peer group under the same root, +then only the +.IR master:X +field is present and not the +.IR propagate_from:X +field. +For further details, see below. +.TP +.IR unbindable +This is an unbindable mount. +.PP +If none of the above tags is present, then this is a private mount. +.SS MS_SHARED and MS_PRIVATE example +Suppose that on a terminal in the initial mount namespace, +we mark one mount point as shared and another as private, +and then view the mounts in +.IR /proc/self/mountinfo : +.PP +.in +4n +.EX +sh1# \fBmount \-\-make\-shared /mntS\fP +sh1# \fBmount \-\-make\-private /mntP\fP +sh1# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +77 61 8:17 / /mntS rw,relatime shared:1 +83 61 8:15 / /mntP rw,relatime +.EE +.in +.PP +From the +.IR /proc/self/mountinfo +output, we see that +.IR /mntS +is a shared mount in peer group 1, and that +.IR /mntP +has no optional tags, indicating that it is a private mount. +The first two fields in each record in this file are the unique +ID for this mount, and the mount ID of the parent mount. +We can further inspect this file to see that the parent mount point of +.IR /mntS +and +.IR /mntP +is the root directory, +.IR / , +which is mounted as private: +.PP +.in +4n +.EX +sh1# \fBcat /proc/self/mountinfo | awk \(aq$1 == 61\(aq | sed \(aqs/ \- .*//\(aq\fP +61 0 8:2 / / rw,relatime +.EE +.in +.PP +On a second terminal, +we create a new mount namespace where we run a second shell +and inspect the mounts: +.PP +.in +4n +.EX +$ \fBPS1=\(aqsh2# \(aq sudo unshare \-m \-\-propagation unchanged sh\fP +sh2# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +222 145 8:17 / /mntS rw,relatime shared:1 +225 145 8:15 / /mntP rw,relatime +.EE +.in +.PP +The new mount namespace received a copy of the initial mount namespace's +mount points. +These new mount points maintain the same propagation types, +but have unique mount IDs. +(The +.IR \-\-propagation\ unchanged +option prevents +.BR unshare (1) +from marking all mounts as private when creating a new mount namespace, +.\" Since util-linux 2.27 +which it does by default.) +.PP +In the second terminal, we then create submounts under each of +.IR /mntS +and +.IR /mntP +and inspect the set-up: +.PP +.in +4n +.EX +sh2# \fBmkdir /mntS/a\fP +sh2# \fBmount /dev/sdb6 /mntS/a\fP +sh2# \fBmkdir /mntP/b\fP +sh2# \fBmount /dev/sdb7 /mntP/b\fP +sh2# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +222 145 8:17 / /mntS rw,relatime shared:1 +225 145 8:15 / /mntP rw,relatime +178 222 8:22 / /mntS/a rw,relatime shared:2 +230 225 8:23 / /mntP/b rw,relatime +.EE +.in +.PP +From the above, it can be seen that +.IR /mntS/a +was created as shared (inheriting this setting from its parent mount) and +.IR /mntP/b +was created as a private mount. +.PP +Returning to the first terminal and inspecting the set-up, +we see that the new mount created under the shared mount point +.IR /mntS +propagated to its peer mount (in the initial mount namespace), +but the new mount created under the private mount point +.IR /mntP +did not propagate: +.PP +.in +4n +.EX +sh1# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +77 61 8:17 / /mntS rw,relatime shared:1 +83 61 8:15 / /mntP rw,relatime +179 77 8:22 / /mntS/a rw,relatime shared:2 +.EE +.in +.\" +.SS MS_SLAVE example +Making a mount point a slave allows it to receive propagated +mount and unmount events from a master shared peer group, +while preventing it from propagating events to that master. +This is useful if we want to (say) receive a mount event when +an optical disk is mounted in the master shared peer group +(in another mount namespace), +but want to prevent mount and unmount events under the slave mount +from having side effects in other namespaces. +.PP +We can demonstrate the effect of slaving by first marking +two mount points as shared in the initial mount namespace: +.PP +.in +4n +.EX +sh1# \fBmount \-\-make\-shared /mntX\fP +sh1# \fBmount \-\-make\-shared /mntY\fP +sh1# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +132 83 8:23 / /mntX rw,relatime shared:1 +133 83 8:22 / /mntY rw,relatime shared:2 +.EE +.in +.PP +On a second terminal, +we create a new mount namespace and inspect the mount points: +.PP +.in +4n +.EX +sh2# \fBunshare \-m \-\-propagation unchanged sh\fP +sh2# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +168 167 8:23 / /mntX rw,relatime shared:1 +169 167 8:22 / /mntY rw,relatime shared:2 +.EE +.in +.PP +In the new mount namespace, we then mark one of the mount points as a slave: +.PP +.in +4n +.EX +sh2# \fBmount \-\-make\-slave /mntY\fP +sh2# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +168 167 8:23 / /mntX rw,relatime shared:1 +169 167 8:22 / /mntY rw,relatime master:2 +.EE +.in +.PP +From the above output, we see that +.IR /mntY +is now a slave mount that is receiving propagation events from +the shared peer group with the ID 2. +.PP +Continuing in the new namespace, we create submounts under each of +.IR /mntX +and +.IR /mntY : +.PP +.in +4n +.EX +sh2# \fBmkdir /mntX/a\fP +sh2# \fBmount /dev/sda3 /mntX/a\fP +sh2# \fBmkdir /mntY/b\fP +sh2# \fBmount /dev/sda5 /mntY/b\fP +.EE +.in +.PP +When we inspect the state of the mount points in the new mount namespace, +we see that +.IR /mntX/a +was created as a new shared mount +(inheriting the "shared" setting from its parent mount) and +.IR /mntY/b +was created as a private mount: +.PP +.in +4n +.EX +sh2# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +168 167 8:23 / /mntX rw,relatime shared:1 +169 167 8:22 / /mntY rw,relatime master:2 +173 168 8:3 / /mntX/a rw,relatime shared:3 +175 169 8:5 / /mntY/b rw,relatime +.EE +.in +.PP +Returning to the first terminal (in the initial mount namespace), +we see that the mount +.IR /mntX/a +propagated to the peer (the shared +.IR /mntX ), +but the mount +.IR /mntY/b +was not propagated: +.PP +.in +4n +.EX +sh1# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +132 83 8:23 / /mntX rw,relatime shared:1 +133 83 8:22 / /mntY rw,relatime shared:2 +174 132 8:3 / /mntX/a rw,relatime shared:3 +.EE +.in +.PP +Now we create a new mount point under +.IR /mntY +in the first shell: +.PP +.in +4n +.EX +sh1# \fBmkdir /mntY/c\fP +sh1# \fBmount /dev/sda1 /mntY/c\fP +sh1# \fBcat /proc/self/mountinfo | grep '/mnt' | sed 's/ \- .*//'\fP +132 83 8:23 / /mntX rw,relatime shared:1 +133 83 8:22 / /mntY rw,relatime shared:2 +174 132 8:3 / /mntX/a rw,relatime shared:3 +178 133 8:1 / /mntY/c rw,relatime shared:4 +.EE +.in +.PP +When we examine the mount points in the second mount namespace, +we see that in this case the new mount has been propagated +to the slave mount point, +and that the new mount is itself a slave mount (to peer group 4): +.PP +.in +4n +.EX +sh2# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +168 167 8:23 / /mntX rw,relatime shared:1 +169 167 8:22 / /mntY rw,relatime master:2 +173 168 8:3 / /mntX/a rw,relatime shared:3 +175 169 8:5 / /mntY/b rw,relatime +179 169 8:1 / /mntY/c rw,relatime master:4 +.EE +.in +.\" +.SS MS_UNBINDABLE example +One of the primary purposes of unbindable mounts is to avoid +the "mount point explosion" problem when repeatedly performing bind mounts +of a higher-level subtree at a lower-level mount point. +The problem is illustrated by the following shell session. +.PP +Suppose we have a system with the following mount points: +.PP +.in +4n +.EX +# \fBmount | awk \(aq{print $1, $2, $3}\(aq\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +.EE +.in +.PP +Suppose furthermore that we wish to recursively bind mount +the root directory under several users' home directories. +We do this for the first user, and inspect the mount points: +.PP +.in +4n +.EX +# \fBmount \-\-rbind / /home/cecilia/\fP +# \fBmount | awk \(aq{print $1, $2, $3}\(aq\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +/dev/sda1 on /home/cecilia +/dev/sdb6 on /home/cecilia/mntX +/dev/sdb7 on /home/cecilia/mntY +.EE +.in +.PP +When we repeat this operation for the second user, +we start to see the explosion problem: +.PP +.in +4n +.EX +# \fBmount \-\-rbind / /home/henry\fP +# \fBmount | awk \(aq{print $1, $2, $3}\(aq\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +/dev/sda1 on /home/cecilia +/dev/sdb6 on /home/cecilia/mntX +/dev/sdb7 on /home/cecilia/mntY +/dev/sda1 on /home/henry +/dev/sdb6 on /home/henry/mntX +/dev/sdb7 on /home/henry/mntY +/dev/sda1 on /home/henry/home/cecilia +/dev/sdb6 on /home/henry/home/cecilia/mntX +/dev/sdb7 on /home/henry/home/cecilia/mntY +.EE +.in +.PP +Under +.IR /home/henry , +we have not only recursively added the +.IR /mntX +and +.IR /mntY +mounts, but also the recursive mounts of those directories under +.IR /home/cecilia +that were created in the previous step. +Upon repeating the step for a third user, +it becomes obvious that the explosion is exponential in nature: +.PP +.in +4n +.EX +# \fBmount \-\-rbind / /home/otto\fP +# \fBmount | awk \(aq{print $1, $2, $3}\(aq\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +/dev/sda1 on /home/cecilia +/dev/sdb6 on /home/cecilia/mntX +/dev/sdb7 on /home/cecilia/mntY +/dev/sda1 on /home/henry +/dev/sdb6 on /home/henry/mntX +/dev/sdb7 on /home/henry/mntY +/dev/sda1 on /home/henry/home/cecilia +/dev/sdb6 on /home/henry/home/cecilia/mntX +/dev/sdb7 on /home/henry/home/cecilia/mntY +/dev/sda1 on /home/otto +/dev/sdb6 on /home/otto/mntX +/dev/sdb7 on /home/otto/mntY +/dev/sda1 on /home/otto/home/cecilia +/dev/sdb6 on /home/otto/home/cecilia/mntX +/dev/sdb7 on /home/otto/home/cecilia/mntY +/dev/sda1 on /home/otto/home/henry +/dev/sdb6 on /home/otto/home/henry/mntX +/dev/sdb7 on /home/otto/home/henry/mntY +/dev/sda1 on /home/otto/home/henry/home/cecilia +/dev/sdb6 on /home/otto/home/henry/home/cecilia/mntX +/dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY +.EE +.in +.PP +The mount explosion problem in the above scenario can be avoided +by making each of the new mounts unbindable. +The effect of doing this is that recursive mounts of the root +directory will not replicate the unbindable mounts. +We make such a mount for the first user: +.PP +.in +4n +.EX +# \fBmount \-\-rbind \-\-make\-unbindable / /home/cecilia\fP +.EE +.in +.PP +Before going further, we show that unbindable mounts are indeed unbindable: +.PP +.in +4n +.EX +# \fBmkdir /mntZ\fP +# \fBmount \-\-bind /home/cecilia /mntZ\fP +mount: wrong fs type, bad option, bad superblock on /home/cecilia, + missing codepage or helper program, or other error + + In some cases useful info is found in syslog \- try + dmesg | tail or so. +.EE +.in +.PP +Now we create unbindable recursive bind mounts for the other two users: +.PP +.in +4n +.EX +# \fBmount \-\-rbind \-\-make\-unbindable / /home/henry\fP +# \fBmount \-\-rbind \-\-make\-unbindable / /home/otto\fP +.EE +.in +.PP +Upon examining the list of mount points, +we see there has been no explosion of mount points, +because the unbindable mounts were not replicated +under each user's directory: +.PP +.in +4n +.EX +# \fBmount | awk \(aq{print $1, $2, $3}\(aq\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +/dev/sda1 on /home/cecilia +/dev/sdb6 on /home/cecilia/mntX +/dev/sdb7 on /home/cecilia/mntY +/dev/sda1 on /home/henry +/dev/sdb6 on /home/henry/mntX +/dev/sdb7 on /home/henry/mntY +/dev/sda1 on /home/otto +/dev/sdb6 on /home/otto/mntX +/dev/sdb7 on /home/otto/mntY +.EE +.in +.\" +.SS Propagation type transitions +The following table shows the effect that applying a new propagation type +(i.e., +.IR "mount \-\-make\-xxxx") +has on the existing propagation type of a mount point. +The rows correspond to existing propagation types, +and the columns are the new propagation settings. +For reasons of space, "private" is abbreviated as "priv" and +"unbindable" as "unbind". +.TS +lb2 lb2 lb2 lb2 lb1 +lb l l l l l. + make-shared make-slave make-priv make-unbind +shared shared slave/priv [1] priv unbind +slave slave+shared slave [2] priv unbind +slave+shared slave+shared slave priv unbind +private shared priv [2] priv unbind +unbindable shared unbind [2] priv unbind +.TE +.sp 1 +Note the following details to the table: +.IP [1] 4 +If a shared mount is the only mount in its peer group, +making it a slave automatically makes it private. +.IP [2] +Slaving a nonshared mount has no effect on the mount. +.\" +.SS Bind (MS_BIND) semantics +Suppose that the following command is performed: +.PP + mount \-\-bind A/a B/b +.PP +Here, +.I A +is the source mount point, +.I B +is the destination mount point, +.I a +is a subdirectory path under the mount point +.IR A , +and +.I b +is a subdirectory path under the mount point +.IR B . +The propagation type of the resulting mount, +.IR B/b , +depends on the propagation types of the mount points +.IR A +and +.IR B , +and is summarized in the following table. +.PP +.TS +lb2 lb1 lb2 lb2 lb2 lb0 +lb2 lb1 lb2 lb2 lb2 lb0 +lb lb l l l l l. + source(A) + shared private slave unbind +_ +dest(B) shared | shared shared slave+shared invalid + nonshared | shared private slave invalid +.TE +.sp 1 +Note that a recursive bind of a subtree follows the same semantics +as for a bind operation on each mount in the subtree. +(Unbindable mounts are automatically pruned at the target mount point.) +.PP +For further details, see +.I Documentation/filesystems/sharedsubtree.txt +in the kernel source tree. +.\" +.SS Move (MS_MOVE) semantics +Suppose that the following command is performed: +.PP + mount \-\-move A B/b +.PP +Here, +.I A +is the source mount point, +.I B +is the destination mount point, and +.I b +is a subdirectory path under the mount point +.IR B . +The propagation type of the resulting mount, +.IR B/b , +depends on the propagation types of the mount points +.IR A +and +.IR B , +and is summarized in the following table. +.PP +.TS +lb2 lb1 lb2 lb2 lb2 lb0 +lb2 lb1 lb2 lb2 lb2 lb0 +lb lb l l l l l. + source(A) + shared private slave unbind +_ +dest(B) shared | shared shared slave+shared invalid + nonshared | shared private slave unbindable +.TE +.sp 1 +Note: moving a mount that resides under a shared mount is invalid. +.PP +For further details, see +.I Documentation/filesystems/sharedsubtree.txt +in the kernel source tree. +.\" +.SS Mount semantics +Suppose that we use the following command to create a mount point: +.PP + mount device B/b +.PP +Here, +.I B +is the destination mount point, and +.I b +is a subdirectory path under the mount point +.IR B . +The propagation type of the resulting mount, +.IR B/b , +follows the same rules as for a bind mount, +where the propagation type of the source mount +is considered always to be private. +.\" +.SS Unmount semantics +Suppose that we use the following command to tear down a mount point: +.PP + unmount A +.PP +Here, +.I A +is a mount point on +.IR B/b , +where +.I B +is the parent mount and +.I b +is a subdirectory path under the mount point +.IR B . +If +.B B +is shared, then all most-recently-mounted mounts at +.I b +on mounts that receive propagation from mount +.I B +and do not have submounts under them are unmounted. +.\" +.SS The /proc/[pid]/mountinfo "propagate_from" tag +The +.I propagate_from:X +tag is shown in the optional fields of a +.IR /proc/[pid]/mountinfo +record in cases where a process can't see a slave's immediate master +(i.e., the pathname of the master is not reachable from +the filesystem root directory) +and so cannot determine the +chain of propagation between the mounts it can see. +.PP +In the following example, we first create a two-link master-slave chain +between the mounts +.IR /mnt , +.IR /tmp/etc , +and +.IR /mnt/tmp/etc . +Then the +.BR chroot (1) +command is used to make the +.IR /tmp/etc +mount point unreachable from the root directory, +creating a situation where the master of +.IR /mnt/tmp/etc +is not reachable from the (new) root directory of the process. +.PP +First, we bind mount the root directory onto +.IR /mnt +and then bind mount +.IR /proc +at +.IR /mnt/proc +so that after the later +.BR chroot (1) +the +.BR proc (5) +filesystem remains visible at the correct location +in the chroot-ed environment. +.PP +.in +4n +.EX +# \fBmkdir \-p /mnt/proc\fP +# \fBmount \-\-bind / /mnt\fP +# \fBmount \-\-bind /proc /mnt/proc\fP +.EE +.in +.PP +Next, we ensure that the +.IR /mnt +mount is a shared mount in a new peer group (with no peers): +.PP +.in +4n +.EX +# \fBmount \-\-make\-private /mnt\fP # Isolate from any previous peer group +# \fBmount \-\-make\-shared /mnt\fP +# \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP +239 61 8:2 / /mnt ... shared:102 +248 239 0:4 / /mnt/proc ... shared:5 +.EE +.in +.PP +Next, we bind mount +.IR /mnt/etc +onto +.IR /tmp/etc : +.PP +.in +4n +.EX +# \fBmkdir \-p /tmp/etc\fP +# \fBmount \-\-bind /mnt/etc /tmp/etc\fP +# \fBcat /proc/self/mountinfo | egrep \(aq/mnt|/tmp/\(aq | sed \(aqs/ \- .*//\(aq\fP +239 61 8:2 / /mnt ... shared:102 +248 239 0:4 / /mnt/proc ... shared:5 +267 40 8:2 /etc /tmp/etc ... shared:102 +.EE +.in +.PP +Initially, these two mount points are in the same peer group, +but we then make the +.IR /tmp/etc +a slave of +.IR /mnt/etc , +and then make +.IR /tmp/etc +shared as well, +so that it can propagate events to the next slave in the chain: +.PP +.in +4n +.EX +# \fBmount \-\-make\-slave /tmp/etc\fP +# \fBmount \-\-make\-shared /tmp/etc\fP +# \fBcat /proc/self/mountinfo | egrep \(aq/mnt|/tmp/\(aq | sed \(aqs/ \- .*//\(aq\fP +239 61 8:2 / /mnt ... shared:102 +248 239 0:4 / /mnt/proc ... shared:5 +267 40 8:2 /etc /tmp/etc ... shared:105 master:102 +.EE +.in +.PP +Then we bind mount +.IR /tmp/etc +onto +.IR /mnt/tmp/etc . +Again, the two mount points are initially in the same peer group, +but we then make +.IR /mnt/tmp/etc +a slave of +.IR /tmp/etc : +.PP +.in +4n +.EX +# \fBmkdir \-p /mnt/tmp/etc\fP +# \fBmount \-\-bind /tmp/etc /mnt/tmp/etc\fP +# \fBmount \-\-make\-slave /mnt/tmp/etc\fP +# \fBcat /proc/self/mountinfo | egrep \(aq/mnt|/tmp/\(aq | sed \(aqs/ \- .*//\(aq\fP +239 61 8:2 / /mnt ... shared:102 +248 239 0:4 / /mnt/proc ... shared:5 +267 40 8:2 /etc /tmp/etc ... shared:105 master:102 +273 239 8:2 /etc /mnt/tmp/etc ... master:105 +.EE +.in +.PP +From the above, we see that +.IR /mnt +is the master of the slave +.IR /tmp/etc , +which in turn is the master of the slave +.IR /mnt/tmp/etc . +.PP +We then +.BR chroot (1) +to the +.IR /mnt +directory, which renders the mount with ID 267 unreachable +from the (new) root directory: +.PP +.in +4n +.EX +# \fBchroot /mnt\fP +.EE +.in +.PP +When we examine the state of the mounts inside the chroot-ed environment, +we see the following: +.PP +.in +4n +.EX +# \fBcat /proc/self/mountinfo | sed \(aqs/ \- .*//\(aq\fP +239 61 8:2 / / ... shared:102 +248 239 0:4 / /proc ... shared:5 +273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102 +.EE +.in +.PP +Above, we see that the mount with ID 273 +is a slave whose master is the peer group 105. +The mount point for that master is unreachable, and so a +.IR propagate_from +tag is displayed, indicating that the closest dominant peer group +(i.e., the nearest reachable mount in the slave chain) +is the peer group with the ID 102 (corresponding to the +.IR /mnt +mount point before the +.BR chroot (1) +was performed. +.\" +.SH VERSIONS +Mount namespaces first appeared in Linux 2.4.19. +.SH CONFORMING TO +Namespaces are a Linux-specific feature. +.\" +.SH NOTES +The propagation type assigned to a new mount point depends +on the propagation type of the parent directory. +If the mount point has a parent (i.e., it is a non-root mount +point) and the propagation type of the parent is +.BR MS_SHARED , +then the propagation type of the new mount is also +.BR MS_SHARED . +Otherwise, the propagation type of the new mount is +.BR MS_PRIVATE . +But see also NOTES. +.PP +Notwithstanding the fact that the default propagation type +for new mount points is in many cases +.BR MS_PRIVATE , +.BR MS_SHARED +is typically more useful. +For this reason, +.BR systemd (1) +automatically remounts all mount points as +.BR MS_SHARED +on system startup. +Thus, on most modern systems, the default propagation type is in practice +.BR MS_SHARED . +.PP +Since, when one uses +.BR unshare (1) +to create a mount namespace, +the goal is commonly to provide full isolation of the mount points +in the new namespace, +.BR unshare (1) +(since +.IR util-linux +version 2.27) in turn reverses the step performed by +.BR systemd (1), +by making all mount points private in the new namespace. +That is, +.BR unshare (1) +performs the equivalent of the following in the new mount namespace: +.PP + mount \-\-make\-rprivate / +.PP +To prevent this, one can use the +.IR "\-\-propagation\ unchanged" +option to +.BR unshare (1). +.PP +For a discussion of propagation types when moving mounts +.RB ( MS_MOVE ) +and creating bind mounts +.RB ( MS_BIND ), +see +.IR Documentation/filesystems/sharedsubtree.txt . +.SH SEE ALSO +.BR unshare (1), +.BR clone (2), +.BR mount (2), +.BR setns (2), +.BR umount (2), +.BR unshare (2), +.BR proc (5), +.BR namespaces (7), +.BR user_namespaces (7) +.PP +.IR Documentation/filesystems/sharedsubtree.txt +in the kernel source tree. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/mq_overview.7 b/man7/mq_overview.7 new file mode 100644 index 0000000..2ba66f3 --- /dev/null +++ b/man7/mq_overview.7 @@ -0,0 +1,418 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH MQ_OVERVIEW 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +mq_overview \- overview of POSIX message queues +.SH DESCRIPTION +POSIX message queues allow processes to exchange data in +the form of messages. +This API is distinct from that provided by System V message queues +.RB ( msgget (2), +.BR msgsnd (2), +.BR msgrcv (2), +etc.), but provides similar functionality. +.PP +Message queues are created and opened using +.BR mq_open (3); +this function returns a +.I message queue descriptor +.RI ( mqd_t ), +which is used to refer to the open message queue in later calls. +Each message queue is identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.BI NAME_MAX +(i.e., 255) characters consisting of an initial slash, +followed by one or more characters, none of which are slashes. +Two processes can operate on the same queue by passing the same name to +.BR mq_open (3). +.PP +Messages are transferred to and from a queue using +.BR mq_send (3) +and +.BR mq_receive (3). +When a process has finished using the queue, it closes it using +.BR mq_close (3), +and when the queue is no longer required, it can be deleted using +.BR mq_unlink (3). +Queue attributes can be retrieved and (in some cases) modified using +.BR mq_getattr (3) +and +.BR mq_setattr (3). +A process can request asynchronous notification +of the arrival of a message on a previously empty queue using +.BR mq_notify (3). +.PP +A message queue descriptor is a reference to an +.I "open message queue description" +(see +.BR open (2)). +After a +.BR fork (2), +a child inherits copies of its parent's message queue descriptors, +and these descriptors refer to the same open message queue descriptions +as the corresponding message queue descriptors in the parent. +Corresponding message queue descriptors in the two processes share the flags +.RI ( mq_flags ) +that are associated with the open message queue description. +.PP +Each message has an associated +.IR priority , +and messages are always delivered to the receiving process +highest priority first. +Message priorities range from 0 (low) to +.I sysconf(_SC_MQ_PRIO_MAX)\ -\ 1 +(high). +On Linux, +.I sysconf(_SC_MQ_PRIO_MAX) +returns 32768, but POSIX.1 requires only that +an implementation support at least priorities in the range 0 to 31; +some implementations provide only this range. +.PP +The remainder of this section describes some specific details +of the Linux implementation of POSIX message queues. +.SS Library interfaces and system calls +In most cases the +.BR mq_* () +library interfaces listed above are implemented +on top of underlying system calls of the same name. +Deviations from this scheme are indicated in the following table: +.RS +.TS +lB lB +l l. +Library interface System call +mq_close(3) close(2) +mq_getattr(3) mq_getsetattr(2) +mq_notify(3) mq_notify(2) +mq_open(3) mq_open(2) +mq_receive(3) mq_timedreceive(2) +mq_send(3) mq_timedsend(2) +mq_setattr(3) mq_getsetattr(2) +mq_timedreceive(3) mq_timedreceive(2) +mq_timedsend(3) mq_timedsend(2) +mq_unlink(3) mq_unlink(2) +.TE +.RE +.SS Versions +POSIX message queues have been supported on Linux since kernel 2.6.6. +Glibc support has been provided since version 2.3.4. +.SS Kernel configuration +Support for POSIX message queues is configurable via the +.B CONFIG_POSIX_MQUEUE +kernel configuration option. +This option is enabled by default. +.SS Persistence +POSIX message queues have kernel persistence: +if not removed by +.BR mq_unlink (3), +a message queue will exist until the system is shut down. +.SS Linking +Programs using the POSIX message queue API must be compiled with +.I cc \-lrt +to link against the real-time library, +.IR librt . +.SS /proc interfaces +The following interfaces can be used to limit the amount of +kernel memory consumed by POSIX message queues and to set +the default attributes for new message queues: +.TP +.IR /proc/sys/fs/mqueue/msg_default " (since Linux 3.5)" +This file defines the value used for a new queue's +.I mq_maxmsg +setting when the queue is created with a call to +.BR mq_open (3) +where +.I attr +is specified as NULL. +The default value for this file is 10. +The minimum and maximum are as for +.IR /proc/sys/fs/mqueue/msg_max . +A new queue's default +.I mq_maxmsg +value will be the smaller of +.IR msg_default +and +.IR msg_max . +Up until Linux 2.6.28, the default +.I mq_maxmsg +was 10; +from Linux 2.6.28 to Linux 3.4, the default was the value defined for the +.I msg_max +limit. +.TP +.I /proc/sys/fs/mqueue/msg_max +This file can be used to view and change the ceiling value for the +maximum number of messages in a queue. +This value acts as a ceiling on the +.I attr\->mq_maxmsg +argument given to +.BR mq_open (3). +The default value for +.I msg_max +is 10. +The minimum value is 1 (10 in kernels before 2.6.28). +The upper limit is +.BR HARD_MSGMAX . +The +.I msg_max +limit is ignored for privileged processes +.RB ( CAP_SYS_RESOURCE ), +but the +.BR HARD_MSGMAX +ceiling is nevertheless imposed. +.IP +The definition of +.BR HARD_MSGMAX +has changed across kernel versions: +.RS +.IP * 3 +Up to Linux 2.6.32: +.IR "131072\ /\ sizeof(void\ *)" +.IP * +Linux 2.6.33 to 3.4: +.IR "(32768\ *\ sizeof(void\ *) / 4)" +.IP * +Since Linux 3.5: +.\" commit 5b5c4d1a1440e94994c73dddbad7be0676cd8b9a +65,536 +.RE +.TP +.IR /proc/sys/fs/mqueue/msgsize_default " (since Linux 3.5)" +This file defines the value used for a new queue's +.I mq_msgsize +setting when the queue is created with a call to +.BR mq_open (3) +where +.I attr +is specified as NULL. +The default value for this file is 8192 (bytes). +The minimum and maximum are as for +.IR /proc/sys/fs/mqueue/msgsize_max . +If +.IR msgsize_default +exceeds +.IR msgsize_max , +a new queue's default +.I mq_msgsize +value is capped to the +.I msgsize_max +limit. +Up until Linux 2.6.28, the default +.I mq_msgsize +was 8192; +from Linux 2.6.28 to Linux 3.4, the default was the value defined for the +.I msgsize_max +limit. +.TP +.I /proc/sys/fs/mqueue/msgsize_max +This file can be used to view and change the ceiling on the +maximum message size. +This value acts as a ceiling on the +.I attr\->mq_msgsize +argument given to +.BR mq_open (3). +The default value for +.I msgsize_max +is 8192 bytes. +The minimum value is 128 (8192 in kernels before 2.6.28). +The upper limit for +.I msgsize_max +has varied across kernel versions: +.RS +.IP * 3 +Before Linux 2.6.28, the upper limit is +.BR INT_MAX . +.IP * +From Linux 2.6.28 to 3.4, the limit is 1,048,576. +.IP * +Since Linux 3.5, the limit is 16,777,216 +.RB ( HARD_MSGSIZEMAX ). +.RE +.IP +The +.I msgsize_max +limit is ignored for privileged process +.RB ( CAP_SYS_RESOURCE ), +but, since Linux 3.5, the +.BR HARD_MSGSIZEMAX +ceiling is enforced for privileged processes. +.TP +.I /proc/sys/fs/mqueue/queues_max +This file can be used to view and change the system-wide limit on the +number of message queues that can be created. +The default value for +.I queues_max +is 256. +No ceiling is imposed on the +.I queues_max +limit; privileged processes +.RB ( CAP_SYS_RESOURCE ) +can exceed the limit (but see BUGS). +.SS Resource limit +The +.B RLIMIT_MSGQUEUE +resource limit, which places a limit on the amount of space +that can be consumed by all of the message queues +belonging to a process's real user ID, is described in +.BR getrlimit (2). +.SS Mounting the message queue filesystem +On Linux, message queues are created in a virtual filesystem. +(Other implementations may also provide such a feature, +but the details are likely to differ.) +This filesystem can be mounted (by the superuser) using the following +commands: +.PP +.in +4n +.EX +.RB "#" " mkdir /dev/mqueue" +.RB "#" " mount \-t mqueue none /dev/mqueue" +.EE +.in +.PP +The sticky bit is automatically enabled on the mount directory. +.PP +After the filesystem has been mounted, the message queues on the system +can be viewed and manipulated using the commands usually used for files +(e.g., +.BR ls (1) +and +.BR rm (1)). +.PP +The contents of each file in the directory consist of a single line +containing information about the queue: +.PP +.in +4n +.EX +.RB "$" " cat /dev/mqueue/mymq" +QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260 +.EE +.in +.PP +These fields are as follows: +.TP +.B QSIZE +Number of bytes of data in all messages in the queue (but see BUGS). +.TP +.B NOTIFY_PID +If this is nonzero, then the process with this PID has used +.BR mq_notify (3) +to register for asynchronous message notification, +and the remaining fields describe how notification occurs. +.TP +.B NOTIFY +Notification method: +0 is +.BR SIGEV_SIGNAL ; +1 is +.BR SIGEV_NONE ; +and +2 is +.BR SIGEV_THREAD . +.TP +.B SIGNO +Signal number to be used for +.BR SIGEV_SIGNAL . +.SS Linux implementation of message queue descriptors +On Linux, a message queue descriptor is actually a file descriptor. +(POSIX does not require such an implementation.) +This means that a message queue descriptor can be monitored using +.BR select (2), +.BR poll (2), +or +.BR epoll (7). +This is not portable. +.PP +The close-on-exec flag (see +.BR open (2)) +is automatically set on the file descriptor returned by +.BR mq_open (2). +.SS IPC namespaces +For a discussion of the interaction of System V IPC objects and +IPC namespaces, see +.BR namespaces (7). +.SH NOTES +System V message queues +.RB ( msgget (2), +.BR msgsnd (2), +.BR msgrcv (2), +etc.) are an older API for exchanging messages between processes. +POSIX message queues provide a better designed interface than +System V message queues; +on the other hand POSIX message queues are less widely available +(especially on older systems) than System V message queues. +.PP +Linux does not currently (2.6.26) support the use of access control +lists (ACLs) for POSIX message queues. +.SH BUGS +In Linux versions 3.5 to 3.14, the kernel imposed a ceiling of 1024 +.RB ( HARD_QUEUESMAX ) +on the value to which the +.I queues_max +limit could be raised, +and the ceiling was enforced even for privileged processes. +This ceiling value was removed in Linux 3.14, +and patches to stable kernels 3.5.x to 3.13.x also removed the ceiling. +.PP +As originally implemented (and documented), +the QSIZE field displayed the total number of (user-supplied) +bytes in all messages in the message queue. +Some changes in Linux 3.5 +.\" commit d6629859b36d +inadvertently changed the behavior, +so that this field also included a count of kernel overhead bytes +used to store the messages in the queue. +This behavioral regression was rectified in Linux 4.2 +.\" commit de54b9ac253787c366bbfb28d901a31954eb3511 +(and earlier stable kernel series), +so that the count once more included just the bytes of user data +in messages in the queue. +.SH EXAMPLE +An example of the use of various message queue functions is shown in +.BR mq_notify (3). +.SH SEE ALSO +.BR getrlimit (2), +.BR mq_getsetattr (2), +.BR poll (2), +.BR select (2), +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR epoll (7), +.BR namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/namespaces.7 b/man7/namespaces.7 new file mode 100644 index 0000000..d22dae8 --- /dev/null +++ b/man7/namespaces.7 @@ -0,0 +1,438 @@ +.\" Copyright (c) 2013 by Michael Kerrisk +.\" and Copyright (c) 2012 by Eric W. Biederman +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH NAMESPACES 7 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +namespaces \- overview of Linux namespaces +.SH DESCRIPTION +A namespace wraps a global system resource in an abstraction that +makes it appear to the processes within the namespace that they +have their own isolated instance of the global resource. +Changes to the global resource are visible to other processes +that are members of the namespace, but are invisible to other processes. +One use of namespaces is to implement containers. +.PP +Linux provides the following namespaces: +.TS +lB lB lB +l lB l. +Namespace Constant Isolates +Cgroup CLONE_NEWCGROUP Cgroup root directory +IPC CLONE_NEWIPC System V IPC, POSIX message queues +Network CLONE_NEWNET Network devices, stacks, ports, etc. +Mount CLONE_NEWNS Mount points +PID CLONE_NEWPID Process IDs +User CLONE_NEWUSER User and group IDs +UTS CLONE_NEWUTS Hostname and NIS domain name +.TE +.PP +This page describes the various namespaces and the associated +.I /proc +files, and summarizes the APIs for working with namespaces. +.\" +.\" ==================== The namespaces API ==================== +.\" +.SS The namespaces API +As well as various +.I /proc +files described below, +the namespaces API includes the following system calls: +.TP +.BR clone (2) +The +.BR clone (2) +system call creates a new process. +If the +.I flags +argument of the call specifies one or more of the +.B CLONE_NEW* +flags listed below, then new namespaces are created for each flag, +and the child process is made a member of those namespaces. +(This system call also implements a number of features +unrelated to namespaces.) +.TP +.BR setns (2) +The +.BR setns (2) +system call allows the calling process to join an existing namespace. +The namespace to join is specified via a file descriptor that refers to +one of the +.IR /proc/[pid]/ns +files described below. +.TP +.BR unshare (2) +The +.BR unshare (2) +system call moves the calling process to a new namespace. +If the +.I flags +argument of the call specifies one or more of the +.B CLONE_NEW* +flags listed below, then new namespaces are created for each flag, +and the calling process is made a member of those namespaces. +(This system call also implements a number of features +unrelated to namespaces.) +.PP +Creation of new namespaces using +.BR clone (2) +and +.BR unshare (2) +in most cases requires the +.BR CAP_SYS_ADMIN +capability. +User namespaces are the exception: since Linux 3.8, +no privilege is required to create a user namespace. +.\" +.\" ==================== The /proc/[pid]/ns/ directory ==================== +.\" +.SS The /proc/[pid]/ns/ directory +Each process has a +.IR /proc/[pid]/ns/ +.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f +subdirectory containing one entry for each namespace that +supports being manipulated by +.BR setns (2): +.PP +.in +4n +.EX +$ \fBls \-l /proc/$$/ns\fP +total 0 +lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 cgroup \-> cgroup:[4026531835] +lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 ipc \-> ipc:[4026531839] +lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 mnt \-> mnt:[4026531840] +lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 net \-> net:[4026531969] +lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 pid \-> pid:[4026531836] +lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 pid_for_children \-> pid:[4026531834] +lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 user \-> user:[4026531837] +lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 uts \-> uts:[4026531838] +.EE +.in +.PP +Bind mounting (see +.BR mount (2)) +one of the files in this directory +to somewhere else in the filesystem keeps +the corresponding namespace of the process specified by +.I pid +alive even if all processes currently in the namespace terminate. +.PP +Opening one of the files in this directory +(or a file that is bind mounted to one of these files) +returns a file handle for +the corresponding namespace of the process specified by +.IR pid . +As long as this file descriptor remains open, +the namespace will remain alive, +even if all processes in the namespace terminate. +The file descriptor can be passed to +.BR setns (2). +.PP +In Linux 3.7 and earlier, these files were visible as hard links. +Since Linux 3.8, +.\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5 +they appear as symbolic links. +If two processes are in the same namespace, then the inode numbers of their +.IR /proc/[pid]/ns/xxx +symbolic links will be the same; an application can check this using the +.I stat.st_ino +field returned by +.BR stat (2). +The content of this symbolic link is a string containing +the namespace type and inode number as in the following example: +.PP +.in +4n +.EX +$ \fBreadlink /proc/$$/ns/uts\fP +uts:[4026531838] +.EE +.in +.PP +The symbolic links in this subdirectory are as follows: +.TP +.IR /proc/[pid]/ns/cgroup " (since Linux 4.6)" +This file is a handle for the cgroup namespace of the process. +.TP +.IR /proc/[pid]/ns/ipc " (since Linux 3.0)" +This file is a handle for the IPC namespace of the process. +.TP +.IR /proc/[pid]/ns/mnt " (since Linux 3.8)" +.\" commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e +This file is a handle for the mount namespace of the process. +.TP +.IR /proc/[pid]/ns/net " (since Linux 3.0)" +This file is a handle for the network namespace of the process. +.TP +.IR /proc/[pid]/ns/pid " (since Linux 3.8)" +.\" commit 57e8391d327609cbf12d843259c968b9e5c1838f +This file is a handle for the PID namespace of the process. +This handle is permanent for the lifetime of the process +(i.e., a process's PID namespace membership never changes). +.TP +.IR /proc/[pid]/ns/pid_for_children " (since Linux 4.12)" +.\" commit eaa0d190bfe1ed891b814a52712dcd852554cb08 +This file is a handle for the PID namespace of +child processes created by this process. +This can change as a consequence of calls to +.BR unshare (2) +and +.BR setns (2) +(see +.BR pid_namespaces (7)), +so the file may differ from +.IR /proc/[pid]/ns/pid . +.TP +.IR /proc/[pid]/ns/user " (since Linux 3.8)" +.\" commit cde1975bc242f3e1072bde623ef378e547b73f91 +This file is a handle for the user namespace of the process. +.TP +.IR /proc/[pid]/ns/uts " (since Linux 3.0)" +This file is a handle for the UTS namespace of the process. +.PP +Permission to dereference or read +.RB ( readlink (2)) +these symbolic links is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.\" +.\" ==================== The /proc/sys/user directory ==================== +.\" +.SS The /proc/sys/user directory +The files in the +.I /proc/sys/user +directory (which is present since Linux 4.9) expose limits +on the number of namespaces of various types that can be created. +The files are as follows: +.TP +.IR max_cgroup_namespaces +The value in this file defines a per-user limit on the number of +cgroup namespaces that may be created in the user namespace. +.TP +.IR max_ipc_namespaces +The value in this file defines a per-user limit on the number of +ipc namespaces that may be created in the user namespace. +.TP +.IR max_mnt_namespaces +The value in this file defines a per-user limit on the number of +mount namespaces that may be created in the user namespace. +.TP +.IR max_net_namespaces +The value in this file defines a per-user limit on the number of +network namespaces that may be created in the user namespace. +.TP +.IR max_pid_namespaces +The value in this file defines a per-user limit on the number of +pid namespaces that may be created in the user namespace. +.TP +.IR max_user_namespaces +The value in this file defines a per-user limit on the number of +user namespaces that may be created in the user namespace. +.TP +.IR max_uts_namespaces +The value in this file defines a per-user limit on the number of +user namespaces that may be created in the user namespace. +.PP +Note the following details about these files: +.IP * 3 +The values in these files are modifiable by privileged processes. +.IP * +The values exposed by these files are the limits for the user namespace +in which the opening process resides. +.IP * +The limits are per-user. +Each user in the same user namespace +can create namespaces up to the defined limit. +.IP * +The limits apply to all users, including UID 0. +.IP * +These limits apply in addition to any other per-namespace +limits (such as those for PID and user namespaces) that may be enforced. +.IP * +Upon encountering these limits, +.BR clone (2) +and +.BR unshare (2) +fail with the error +.BR ENOSPC . +.IP * +For the initial user namespace, +the default value in each of these files is half the limit on the number +of threads that may be created +.RI ( /proc/sys/kernel/threads-max ). +In all descendant user namespaces, the default value in each file is +.BR MAXINT . +.IP * +When a namespace is created, the object is also accounted +against ancestor namespaces. +More precisely: +.RS +.IP + 3 +Each user namespace has a creator UID. +.IP + +When a namespace is created, +it is accounted against the creator UIDs in each of the +ancestor user namespaces, +and the kernel ensures that the corresponding namespace limit +for the creator UID in the ancestor namespace is not exceeded. +.IP + +The aforementioned point ensures that creating a new user namespace +cannot be used as a means to escape the limits in force +in the current user namespace. +.RE +.PP +.\" +.\" ==================== Cgroup namespaces ==================== +.\" +.SS Cgroup namespaces (CLONE_NEWCGROUP) +See +.BR cgroup_namespaces (7). +.\" +.\" ==================== IPC namespaces ==================== +.\" +.SS IPC namespaces (CLONE_NEWIPC) +IPC namespaces isolate certain IPC resources, +namely, System V IPC objects (see +.BR svipc (7)) +and (since Linux 2.6.30) +.\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f +.\" https://lwn.net/Articles/312232/ +POSIX message queues (see +.BR mq_overview (7)). +The common characteristic of these IPC mechanisms is that IPC +objects are identified by mechanisms other than filesystem +pathnames. +.PP +Each IPC namespace has its own set of System V IPC identifiers and +its own POSIX message queue filesystem. +Objects created in an IPC namespace are visible to all other processes +that are members of that namespace, +but are not visible to processes in other IPC namespaces. +.PP +The following +.I /proc +interfaces are distinct in each IPC namespace: +.IP * 3 +The POSIX message queue interfaces in +.IR /proc/sys/fs/mqueue . +.IP * +The System V IPC interfaces in +.IR /proc/sys/kernel , +namely: +.IR msgmax , +.IR msgmnb , +.IR msgmni , +.IR sem , +.IR shmall , +.IR shmmax , +.IR shmmni , +and +.IR shm_rmid_forced . +.IP * +The System V IPC interfaces in +.IR /proc/sysvipc . +.PP +When an IPC namespace is destroyed +(i.e., when the last process that is a member of the namespace terminates), +all IPC objects in the namespace are automatically destroyed. +.PP +Use of IPC namespaces requires a kernel that is configured with the +.B CONFIG_IPC_NS +option. +.\" +.\" ==================== Network namespaces ==================== +.\" +.SS Network namespaces (CLONE_NEWNET) +See +.BR network_namespaces (7). +.\" +.\" ==================== Mount namespaces ==================== +.\" +.SS Mount namespaces (CLONE_NEWNS) +See +.BR mount_namespaces (7). +.\" +.\" ==================== PID namespaces ==================== +.\" +.SS PID namespaces (CLONE_NEWPID) +See +.BR pid_namespaces (7). +.\" +.\" ==================== User namespaces ==================== +.\" +.SS User namespaces (CLONE_NEWUSER) +See +.BR user_namespaces (7). +.\" +.\" ==================== UTS namespaces ==================== +.\" +.SS UTS namespaces (CLONE_NEWUTS) +UTS namespaces provide isolation of two system identifiers: +the hostname and the NIS domain name. +These identifiers are set using +.BR sethostname (2) +and +.BR setdomainname (2), +and can be retrieved using +.BR uname (2), +.BR gethostname (2), +and +.BR getdomainname (2). +.PP +Use of UTS namespaces requires a kernel that is configured with the +.B CONFIG_UTS_NS +option. +.SH EXAMPLE +See +.BR clone (2) +and +.BR user_namespaces (7). +.SH SEE ALSO +.BR nsenter (1), +.BR readlink (1), +.BR unshare (1), +.BR clone (2), +.BR ioctl_ns (2), +.BR setns (2), +.BR unshare (2), +.BR proc (5), +.BR capabilities (7), +.BR cgroup_namespaces (7), +.BR cgroups (7), +.BR credentials (7), +.BR network_namespaces (7), +.BR pid_namespaces (7), +.BR user_namespaces (7), +.BR lsns (8), +.BR switch_root (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/netdevice.7 b/man7/netdevice.7 new file mode 100644 index 0000000..ac32a5e --- /dev/null +++ b/man7/netdevice.7 @@ -0,0 +1,386 @@ +'\" t +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: netdevice.7,v 1.10 2000/08/17 10:09:54 ak Exp $ +.\" +.\" Modified, 2004-11-25, mtk, formatting and a few wording fixes +.\" +.\" Modified, 2011-11-02, , added many basic +.\" but missing ioctls, such as SIOCGIFADDR. +.\" +.TH NETDEVICE 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +netdevice \- low-level access to Linux network devices +.SH SYNOPSIS +.B "#include " +.br +.B "#include " +.SH DESCRIPTION +This man page describes the sockets interface which is used to configure +network devices. +.PP +Linux supports some standard ioctls to configure network devices. +They can be used on any socket's file descriptor regardless of the +family or type. +Most of them pass an +.I ifreq +structure: +.PP +.in +4n +.EX +struct ifreq { + char ifr_name[IFNAMSIZ]; /* Interface name */ + union { + struct sockaddr ifr_addr; + struct sockaddr ifr_dstaddr; + struct sockaddr ifr_broadaddr; + struct sockaddr ifr_netmask; + struct sockaddr ifr_hwaddr; + short ifr_flags; + int ifr_ifindex; + int ifr_metric; + int ifr_mtu; + struct ifmap ifr_map; + char ifr_slave[IFNAMSIZ]; + char ifr_newname[IFNAMSIZ]; + char *ifr_data; + }; +}; +.EE +.in +.PP +Normally, the user specifies which device to affect by setting +.I ifr_name +to the name of the interface. +All other members of the structure may +share memory. +.SS Ioctls +If an ioctl is marked as privileged, then using it requires an effective +user ID of 0 or the +.B CAP_NET_ADMIN +capability. +If this is not the case, +.B EPERM +will be returned. +.TP +.B SIOCGIFNAME +Given the +.IR ifr_ifindex , +return the name of the interface in +.IR ifr_name . +This is the only ioctl which returns its result in +.IR ifr_name . +.TP +.B SIOCGIFINDEX +Retrieve the interface index of the interface into +.IR ifr_ifindex . +.TP +.BR SIOCGIFFLAGS ", " SIOCSIFFLAGS +Get or set the active flag word of the device. +.I ifr_flags +contains a bit mask of the following values: +.\" Do not right adjust text blocks in tables +.na +.TS +tab(:); +c s +l l. +Device flags +IFF_UP:Interface is running. +IFF_BROADCAST:Valid broadcast address set. +IFF_DEBUG:Internal debugging flag. +IFF_LOOPBACK:Interface is a loopback interface. +IFF_POINTOPOINT:Interface is a point-to-point link. +IFF_RUNNING:Resources allocated. +IFF_NOARP:T{ +No arp protocol, L2 destination address not set. +T} +IFF_PROMISC:Interface is in promiscuous mode. +IFF_NOTRAILERS:Avoid use of trailers. +IFF_ALLMULTI:Receive all multicast packets. +IFF_MASTER:Master of a load balancing bundle. +IFF_SLAVE:Slave of a load balancing bundle. +IFF_MULTICAST:Supports multicast +IFF_PORTSEL:Is able to select media type via ifmap. +IFF_AUTOMEDIA:Auto media selection active. +IFF_DYNAMIC:T{ +The addresses are lost when the interface goes down. +T} +IFF_LOWER_UP:Driver signals L1 up (since Linux 2.6.17) +IFF_DORMANT:Driver signals dormant (since Linux 2.6.17) +IFF_ECHO:Echo sent packets (since Linux 2.6.25) +.TE +.ad +.PP +Setting the active flag word is a privileged operation, but any +process may read it. +.TP +.BR SIOCGIFPFLAGS ", " SIOCSIFPFLAGS +Get or set extended (private) flags for the device. +.I ifr_flags +contains a bit mask of the following values: +.TS +tab(:); +c s +l l. +Private flags +IFF_802_1Q_VLAN:Interface is 802.1Q VLAN device. +IFF_EBRIDGE:Interface is Ethernet bridging device. +IFF_SLAVE_INACTIVE:Interface is inactive bonding slave. +IFF_MASTER_8023AD:Interface is 802.3ad bonding master. +IFF_MASTER_ALB:Interface is balanced-alb bonding master. +IFF_BONDING:Interface is a bonding master or slave. +IFF_SLAVE_NEEDARP:Interface needs ARPs for validation. +IFF_ISATAP:Interface is RFC4214 ISATAP interface. +.TE +.PP +Setting the extended (private) interface flags is a privileged operation. +.TP +.BR SIOCGIFADDR ", " SIOCSIFADDR +Get or set the address of the device using +.IR ifr_addr . +Setting the interface address is a privileged operation. +For compatibility, only +.B AF_INET +addresses are accepted or returned. +.TP +.BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR +Get or set the destination address of a point-to-point device using +.IR ifr_dstaddr . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the destination address is a privileged operation. +.TP +.BR SIOCGIFBRDADDR ", " SIOCSIFBRDADDR +Get or set the broadcast address for a device using +.IR ifr_brdaddr . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the broadcast address is a privileged operation. +.TP +.BR SIOCGIFNETMASK ", " SIOCSIFNETMASK +Get or set the network mask for a device using +.IR ifr_netmask . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the network mask is a privileged operation. +.TP +.BR SIOCGIFMETRIC ", " SIOCSIFMETRIC +Get or set the metric of the device using +.IR ifr_metric . +This is currently not implemented; it sets +.I ifr_metric +to 0 if you attempt to read it and returns +.B EOPNOTSUPP +if you attempt to set it. +.TP +.BR SIOCGIFMTU ", " SIOCSIFMTU +Get or set the MTU (Maximum Transfer Unit) of a device using +.IR ifr_mtu . +Setting the MTU is a privileged operation. +Setting the MTU to +too small values may cause kernel crashes. +.TP +.BR SIOCGIFHWADDR ", " SIOCSIFHWADDR +Get or set the hardware address of a device using +.IR ifr_hwaddr . +The hardware address is specified in a struct +.IR sockaddr . +.I sa_family +contains the ARPHRD_* device type, +.I sa_data +the L2 hardware address starting from byte 0. +Setting the hardware address is a privileged operation. +.TP +.B SIOCSIFHWBROADCAST +Set the hardware broadcast address of a device from +.IR ifr_hwaddr . +This is a privileged operation. +.TP +.BR SIOCGIFMAP ", " SIOCSIFMAP +Get or set the interface's hardware parameters using +.IR ifr_map . +Setting the parameters is a privileged operation. +.IP +.in +4n +.EX +struct ifmap { + unsigned long mem_start; + unsigned long mem_end; + unsigned short base_addr; + unsigned char irq; + unsigned char dma; + unsigned char port; +}; +.EE +.in +.IP +The interpretation of the ifmap structure depends on the device driver +and the architecture. +.TP +.BR SIOCADDMULTI ", " SIOCDELMULTI +Add an address to or delete an address from the device's link layer +multicast filters using +.IR ifr_hwaddr . +These are privileged operations. +See also +.BR packet (7) +for an alternative. +.TP +.BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN +Get or set the transmit queue length of a device using +.IR ifr_qlen . +Setting the transmit queue length is a privileged operation. +.TP +.B SIOCSIFNAME +Changes the name of the interface specified in +.I ifr_name +to +.IR ifr_newname . +This is a privileged operation. +It is allowed only when the interface +is not up. +.TP +.B SIOCGIFCONF +Return a list of interface (transport layer) addresses. +This currently +means only addresses of the +.B AF_INET +(IPv4) family for compatibility. +Unlike the others, this ioctl passes an +.I ifconf +structure: +.IP +.in +4n +.EX +struct ifconf { + int ifc_len; /* size of buffer */ + union { + char *ifc_buf; /* buffer address */ + struct ifreq *ifc_req; /* array of structures */ + }; +}; +.EE +.in +.IP +If +.I ifc_req +is NULL, +.B SIOCGIFCONF +returns the necessary buffer size in bytes +for receiving all available addresses in +.IR ifc_len . +Otherwise, +.I ifc_req +contains a pointer to an array of +.I ifreq +structures to be filled with all currently active L3 interface addresses. +.I ifc_len +contains the size of the array in bytes. +Within each +.I ifreq +structure, +.I ifr_name +will receive the interface name, and +.I ifr_addr +the address. +The actual number of bytes transferred is returned in +.IR ifc_len . +.IP +If the size specified by +.I ifc_len +is insufficient to store all the addresses, +the kernel will skip the exceeding ones and return success. +There is no reliable way of detecting this condition once it has occurred. +It is therefore recommended to either determine the necessary buffer size +beforehand by calling +.B SIOCGIFCONF +with +.I ifc_req +set to NULL, or to retry the call with a bigger buffer whenever +.I ifc_len +upon return differs by less than +.I sizeof(struct ifreq) +from its original value. +.IP +If an error occurs accessing the +.I ifconf +or +.I ifreq +structures, +.B EFAULT +will be returned. +.\" Slaving isn't supported in 2.2 +.\" . +.\" .TP +.\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE +.\" Get or set the slave device using +.\" .IR ifr_slave . +.\" Setting the slave device is a privileged operation. +.\" .PP +.\" FIXME . add amateur radio stuff. +.PP +Most protocols support their own ioctls to configure protocol-specific +interface options. +See the protocol man pages for a description. +For configuring IP addresses, see +.BR ip (7). +.PP +In addition, some devices support private ioctls. +These are not described here. +.SH NOTES +Strictly speaking, +.B SIOCGIFCONF +and the other ioctls that accept or return only +.B AF_INET +socket addresses, +are IP-specific and belong in +.BR ip (7). +.PP +The names of interfaces with no addresses or that don't have the +.B IFF_RUNNING +flag set can be found via +.IR /proc/net/dev . +.PP +Local IPv6 IP addresses can be found via +.I /proc/net +or via +.BR rtnetlink (7). +.SH BUGS +glibc 2.1 is missing the +.I ifr_newname +macro in +.IR . +Add the following to your program as a workaround: +.PP +.in +4n +.EX +#ifndef ifr_newname +#define ifr_newname ifr_ifru.ifru_slave +#endif +.EE +.in +.SH SEE ALSO +.BR proc (5), +.BR capabilities (7), +.BR ip (7), +.BR rtnetlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/netlink.7 b/man7/netlink.7 new file mode 100644 index 0000000..41d5d9d --- /dev/null +++ b/man7/netlink.7 @@ -0,0 +1,585 @@ +'\" t +.\" This man page is Copyright (c) 1998 by Andi Kleen. +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) +.\" Subject to the GPL. +.\" %%%LICENSE_END +.\" +.\" Based on the original comments from Alexey Kuznetsov +.\" Modified 2005-12-27 by Hasso Tepper +.\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ +.TH NETLINK 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +netlink \- communication between kernel and user space (AF_NETLINK) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.PP +.BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family ); +.fi +.SH DESCRIPTION +Netlink is used to transfer information between the kernel and +user-space processes. +It consists of a standard sockets-based interface for user space +processes and an internal kernel API for kernel modules. +The internal kernel interface is not documented in this manual page. +There is also an obsolete netlink interface +via netlink character devices; this interface is not documented here +and is provided only for backward compatibility. +.PP +Netlink is a datagram-oriented service. +Both +.B SOCK_RAW +and +.B SOCK_DGRAM +are valid values for +.IR socket_type . +However, the netlink protocol does not distinguish between datagram +and raw sockets. +.PP +.I netlink_family +selects the kernel module or netlink group to communicate with. +The currently assigned netlink families are: +.TP +.BR NETLINK_ROUTE +Receives routing and link updates and may be used to modify the routing +tables (both IPv4 and IPv6), IP addresses, link parameters, +neighbor setups, queueing disciplines, traffic classes and +packet classifiers (see +.BR rtnetlink (7)). +.TP +.BR NETLINK_W1 " (Linux 2.6.13 to 2.16.17)" +Messages from 1-wire subsystem. +.TP +.BR NETLINK_USERSOCK +Reserved for user-mode socket protocols. +.TP +.BR NETLINK_FIREWALL " (up to and including Linux 3.4)" +.\" removed by commit d16cf20e2f2f13411eece7f7fb72c17d141c4a84 +Transport IPv4 packets from netfilter to user space. +Used by +.I ip_queue +kernel module. +After a long period of being declared obsolete (in favor of the more advanced +.I nfnetlink_queue +feature), +.BR NETLINK_FIREWALL +was removed in Linux 3.5. +.TP +.BR NETLINK_INET_DIAG " (since Linux 2.6.14)" +Query information about sockets of various protocol families from the kernel +(see +.BR sock_diag (7)). +.TP +.BR NETLINK_SOCK_DIAG " (since Linux 3.3)" +.\" commit 7f1fb60c4fc9fb29fbb406ac8c4cfb4e59e168d6 +A synonym for +.BR NETLINK_INET_DIAG . +.TP +.BR NETLINK_NFLOG " (up to and including Linux 3.16)" +Netfilter/iptables ULOG. +.TP +.BR NETLINK_XFRM +.\" FIXME More details on NETLINK_XFRM needed. +IPsec. +.TP +.BR NETLINK_SELINUX " (since Linux 2.6.4)" +SELinux event notifications. +.TP +.BR NETLINK_ISCSI " (since Linux 2.6.15)" +.\" FIXME More details on NETLINK_ISCSI needed. +Open-iSCSI. +.TP +.BR NETLINK_AUDIT " (since Linux 2.6.6)" +.\" FIXME More details on NETLINK_AUDIT needed. +Auditing. +.TP +.BR NETLINK_FIB_LOOKUP " (since Linux 2.6.13)" +.\" FIXME More details on NETLINK_FIB_LOOKUP needed. +Access to FIB lookup from user space. +.TP +.BR NETLINK_CONNECTOR " (since Linux 2.6.14)" +Kernel connector. +See +.I Documentation/connector/* +in the Linux kernel source tree for further information. +.TP +.BR NETLINK_NETFILTER " (since Linux 2.6.14)" +.\" FIXME More details on NETLINK_NETFILTER needed. +Netfilter subsystem. +.TP +.BR NETLINK_SCSITRANSPORT " (since Linux 2.6.19)" +.\" commit 84314fd4740ad73550c76dee4a9578979d84af48 +.\" FIXME More details on NETLINK_SCSITRANSPORT needed. +SCSI Transports. +.TP +.BR NETLINK_RDMA " (since Linux 3.0)" +.\" commit b2cbae2c248776d81cc265ff7d48405b6a4cc463 +.\" FIXME More details on NETLINK_RDMA needed. +Infiniband RDMA. +.TP +.BR NETLINK_IP6_FW " (up to and including Linux 3.4)" +Transport IPv6 packets from netfilter to user space. +Used by +.I ip6_queue +kernel module. +.TP +.B NETLINK_DNRTMSG +DECnet routing messages. +.TP +.BR NETLINK_KOBJECT_UEVENT " (since Linux 2.6.10)" +.\" FIXME More details on NETLINK_KOBJECT_UEVENT needed. +Kernel messages to user space. +.TP +.BR NETLINK_GENERIC " (since Linux 2.6.15)" +Generic netlink family for simplified netlink usage. +.TP +.BR NETLINK_CRYPTO " (since Linux 3.2)" +.\" commit a38f7907b926e4c6c7d389ad96cc38cec2e5a9e9 +.\" Author: Steffen Klassert +Netlink interface to request information about ciphers registered +with the kernel crypto API as well as allow configuration of the +kernel crypto API. +.PP +Netlink messages consist of a byte stream with one or multiple +.I nlmsghdr +headers and associated payload. +The byte stream should be accessed only with the standard +.B NLMSG_* +macros. +See +.BR netlink (3) +for further information. +.PP +In multipart messages (multiple +.I nlmsghdr +headers with associated payload in one byte stream) the first and all +following headers have the +.B NLM_F_MULTI +flag set, except for the last header which has the type +.BR NLMSG_DONE . +.PP +After each +.I nlmsghdr +the payload follows. +.PP +.in +4n +.EX +struct nlmsghdr { + __u32 nlmsg_len; /* Length of message including header */ + __u16 nlmsg_type; /* Type of message content */ + __u16 nlmsg_flags; /* Additional flags */ + __u32 nlmsg_seq; /* Sequence number */ + __u32 nlmsg_pid; /* Sender port ID */ +}; +.EE +.in +.PP +.I nlmsg_type +can be one of the standard message types: +.B NLMSG_NOOP +message is to be ignored, +.B NLMSG_ERROR +message signals an error and the payload contains an +.I nlmsgerr +structure, +.B NLMSG_DONE +message terminates a multipart message. +.PP +.in +4n +.EX +struct nlmsgerr { + int error; /* Negative errno or 0 for acknowledgements */ + struct nlmsghdr msg; /* Message header that caused the error */ +}; +.EE +.in +.PP +A netlink family usually specifies more message types, see the +appropriate manual pages for that, for example, +.BR rtnetlink (7) +for +.BR NETLINK_ROUTE . +.TS +tab(:); +l s +lB l. +Standard flag bits in \fInlmsg_flags\fP +_ +NLM_F_REQUEST:Must be set on all request messages. +NLM_F_MULTI:T{ +The message is part of a multipart message terminated by +.BR NLMSG_DONE . +T} +NLM_F_ACK:Request for an acknowledgment on success. +NLM_F_ECHO:Echo this request. +.TE +.\" No right adjustment for text blocks in tables +.TS +tab(:); +l s +lB l. +Additional flag bits for GET requests +_ +NLM_F_ROOT:Return the complete table instead of a single entry. +NLM_F_MATCH:T{ +Return all entries matching criteria passed in message content. +Not implemented yet. +T} +NLM_F_ATOMIC:Return an atomic snapshot of the table. +NLM_F_DUMP:T{ +Convenience macro; equivalent to +.br +(NLM_F_ROOT|NLM_F_MATCH). +T} +.TE +.\" FIXME NLM_F_ATOMIC is not used anymore? +.PP +Note that +.B NLM_F_ATOMIC +requires the +.B CAP_NET_ADMIN +capability or an effective UID of 0. +.TS +tab(:); +l s +lB l. +Additional flag bits for NEW requests +_ +NLM_F_REPLACE:Replace existing matching object. +NLM_F_EXCL:Don't replace if the object already exists. +NLM_F_CREATE:Create object if it doesn't already exist. +NLM_F_APPEND:Add to the end of the object list. +.TE +.PP +.I nlmsg_seq +and +.I nlmsg_pid +are used to track messages. +.I nlmsg_pid +shows the origin of the message. +Note that there isn't a 1:1 relationship between +.I nlmsg_pid +and the PID of the process if the message originated from a netlink +socket. +See the +.B ADDRESS FORMATS +section for further information. +.PP +Both +.I nlmsg_seq +and +.I nlmsg_pid +.\" FIXME Explain more about nlmsg_seq and nlmsg_pid. +are opaque to netlink core. +.PP +Netlink is not a reliable protocol. +It tries its best to deliver a message to its destination(s), +but may drop messages when an out-of-memory condition or +other error occurs. +For reliable transfer the sender can request an +acknowledgement from the receiver by setting the +.B NLM_F_ACK +flag. +An acknowledgment is an +.B NLMSG_ERROR +packet with the error field set to 0. +The application must generate acknowledgements for +received messages itself. +The kernel tries to send an +.B NLMSG_ERROR +message for every failed packet. +A user process should follow this convention too. +.PP +However, reliable transmissions from kernel to user are impossible +in any case. +The kernel can't send a netlink message if the socket buffer is full: +the message will be dropped and the kernel and the user-space process will +no longer have the same view of kernel state. +It is up to the application to detect when this happens (via the +.B ENOBUFS +error returned by +.BR recvmsg (2)) +and resynchronize. +.SS Address formats +The +.I sockaddr_nl +structure describes a netlink client in user space or in the kernel. +A +.I sockaddr_nl +can be either unicast (only sent to one peer) or sent to +netlink multicast groups +.RI ( nl_groups +not equal 0). +.PP +.in +4n +.EX +struct sockaddr_nl { + sa_family_t nl_family; /* AF_NETLINK */ + unsigned short nl_pad; /* Zero */ + pid_t nl_pid; /* Port ID */ + __u32 nl_groups; /* Multicast groups mask */ +}; +.EE +.in +.PP +.I nl_pid +is the unicast address of netlink socket. +It's always 0 if the destination is in the kernel. +For a user-space process, +.I nl_pid +is usually the PID of the process owning the destination socket. +However, +.I nl_pid +identifies a netlink socket, not a process. +If a process owns several netlink +sockets, then +.I nl_pid +can be equal to the process ID only for at most one socket. +There are two ways to assign +.I nl_pid +to a netlink socket. +If the application sets +.I nl_pid +before calling +.BR bind (2), +then it is up to the application to make sure that +.I nl_pid +is unique. +If the application sets it to 0, the kernel takes care of assigning it. +The kernel assigns the process ID to the first netlink socket the process +opens and assigns a unique +.I nl_pid +to every netlink socket that the process subsequently creates. +.PP +.I nl_groups +is a bit mask with every bit representing a netlink group number. +Each netlink family has a set of 32 multicast groups. +When +.BR bind (2) +is called on the socket, the +.I nl_groups +field in the +.I sockaddr_nl +should be set to a bit mask of the groups which it wishes to listen to. +The default value for this field is zero which means that no multicasts +will be received. +A socket may multicast messages to any of the multicast groups by setting +.I nl_groups +to a bit mask of the groups it wishes to send to when it calls +.BR sendmsg (2) +or does a +.BR connect (2). +Only processes with an effective UID of 0 or the +.B CAP_NET_ADMIN +capability may send or listen to a netlink multicast group. +Since Linux 2.6.13, +.\" commit d629b836d151d43332492651dd841d32e57ebe3b +messages can't be broadcast to multiple groups. +Any replies to a message received for a multicast group should be +sent back to the sending PID and the multicast group. +Some Linux kernel subsystems may additionally allow other users +to send and/or receive messages. +As at Linux 3.0, the +.BR NETLINK_KOBJECT_UEVENT , +.BR NETLINK_GENERIC , +.BR NETLINK_ROUTE , +and +.BR NETLINK_SELINUX +groups allow other users to receive messages. +No groups allow other users to send messages. +.PP +.SS Socket options +To set or get a netlink socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR SOL_NETLINK . +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.TP +.BR NETLINK_PKTINFO " (since Linux 2.6.14)" +.\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 +.\" Author: Patrick McHardy +Enable +.B nl_pktinfo +control messages for received packets to get the extended +destination group number. +.TP +.BR NETLINK_ADD_MEMBERSHIP ,\ NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" +.\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 +.\" Author: Patrick McHardy +Join/leave a group specified by +.IR optval . +.TP +.BR NETLINK_LIST_MEMBERSHIPS " (since Linux 4.2)" +.\" commit b42be38b2778eda2237fc759e55e3b698b05b315 +.\" Author: David Herrmann +Retrieve all groups a socket is a member of. +.I optval +is a pointer to +.B __u32 +and +.I optlen +is the size of the array. +The array is filled with the full membership set of the +socket, and the required array size is returned in +.IR optlen . +.TP +.BR NETLINK_BROADCAST_ERROR " (since Linux 2.6.30)" +.\" commit be0c22a46cfb79ab2342bb28fde99afa94ef868e +.\" Author: Pablo Neira Ayuso +When not set, +.B netlink_broadcast() +only reports +.B ESRCH +errors and silently ignore +.B NOBUFS +errors. +.TP +.BR NETLINK_NO_ENOBUFS " (since Linux 2.6.30)" +.\" commit 38938bfe3489394e2eed5e40c9bb8f66a2ce1405 +.\" Author: Pablo Neira Ayuso +This flag can be used by unicast and broadcast listeners to avoid receiving +.B ENOBUFS +errors. +.TP +.BR NETLINK_LISTEN_ALL_NSID " (since Linux 4.2)" +.\" commit 59324cf35aba5336b611074028777838a963d03b +.\" Author: Nicolas Dichtel +When set, this socket will receive netlink notifications from +all network namespaces that have an +.I nsid +assigned into the network namespace where the socket has been opened. +The +.I nsid +is sent to user space via an ancillary data. +.TP +.BR NETLINK_CAP_ACK " (since Linux 4.2)" +.\" commit 0a6a3a23ea6efde079a5b77688541a98bf202721 +.\" Author: Christophe Ricard +The kernel may fail to allocate the necessary room for the acknowledgment +message back to user space. +This option trims off the payload of the original netlink message. +The netlink message header is still included, so the user can guess from the +sequence number which message triggered the acknowledgment. +.SH VERSIONS +The socket interface to netlink first appeared Linux 2.2. +.PP +Linux 2.0 supported a more primitive device-based netlink interface +(which is still available as a compatibility option). +This obsolete interface is not described here. +.SH NOTES +It is often better to use netlink via +.I libnetlink +or +.I libnl +than via the low-level kernel interface. +.SH BUGS +This manual page is not complete. +.SH EXAMPLE +The following example creates a +.B NETLINK_ROUTE +netlink socket which will listen to the +.B RTMGRP_LINK +(network interface create/delete/up/down events) and +.B RTMGRP_IPV4_IFADDR +(IPv4 addresses add/delete events) multicast groups. +.PP +.in +4n +.EX +struct sockaddr_nl sa; + +memset(&sa, 0, sizeof(sa)); +sa.nl_family = AF_NETLINK; +sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR; + +fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE); +bind(fd, (struct sockaddr *) &sa, sizeof(sa)); +.EE +.in +.PP +The next example demonstrates how to send a netlink message to the +kernel (pid 0). +Note that the application must take care of message sequence numbers +in order to reliably track acknowledgements. +.PP +.in +4n +.EX +struct nlmsghdr *nh; /* The nlmsghdr with payload to send */ +struct sockaddr_nl sa; +struct iovec iov = { nh, nh\->nlmsg_len }; +struct msghdr msg; + +msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 }; +memset(&sa, 0, sizeof(sa)); +sa.nl_family = AF_NETLINK; +nh\->nlmsg_pid = 0; +nh\->nlmsg_seq = ++sequence_number; +/* Request an ack from kernel by setting NLM_F_ACK */ +nh\->nlmsg_flags |= NLM_F_ACK; + +sendmsg(fd, &msg, 0); +.EE +.in +.PP +And the last example is about reading netlink message. +.PP +.in +4n +.EX +int len; +char buf[8192]; /* 8192 to avoid message truncation on + platforms with page size > 4096 */ +struct iovec iov = { buf, sizeof(buf) }; +struct sockaddr_nl sa; +struct msghdr msg; +struct nlmsghdr *nh; + +msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 }; +len = recvmsg(fd, &msg, 0); + +for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); + nh = NLMSG_NEXT (nh, len)) { + /* The end of multipart message */ + if (nh\->nlmsg_type == NLMSG_DONE) + return; + + if (nh\->nlmsg_type == NLMSG_ERROR) + /* Do some error handling */ + ... + + /* Continue with parsing payload */ + ... +} +.EE +.in +.SH SEE ALSO +.BR cmsg (3), +.BR netlink (3), +.BR capabilities (7), +.BR rtnetlink (7), +.BR sock_diag (7) +.PP +.UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2* +information about libnetlink +.UE +.PP +.UR http://www.infradead.org\:/~tgr\:/libnl/ +information about libnl +.UE +.PP +RFC 3549 "Linux Netlink as an IP Services Protocol" +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/network_namespaces.7 b/man7/network_namespaces.7 new file mode 100644 index 0000000..9e2b99b --- /dev/null +++ b/man7/network_namespaces.7 @@ -0,0 +1,87 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH NETWORK_NAMESPACES 7 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +network_namespaces \- overview of Linux network namespaces +.SH DESCRIPTION +Network namespaces provide isolation of the system resources associated +with networking: network devices, IPv4 and IPv6 protocol stacks, +IP routing tables, firewall rules, the +.I /proc/net +directory (which is a symbolic link to +.IR /proc/PID/net ), +the +.I /sys/class/net +directory, various files under +.IR /proc/sys/net , +port numbers (sockets), and so on. +.PP +A physical network device can live in exactly one +network namespace. +When a network namespace is freed +(i.e., when the last process in the namespace terminates), +its physical network devices are moved back to the +initial network namespace (not to the parent of the process). +.PP +A virtual network +.RB ( veth (4)) +device pair provides a pipe-like abstraction +that can be used to create tunnels between network namespaces, +and can be used to create a bridge to a physical network device +in another namespace. +When a namespace is freed, the +.BR veth (4) +devices that it contains are destroyed. +.PP +Use of network namespaces requires a kernel that is configured with the +.B CONFIG_NET_NS +option. +.\" FIXME .SH EXAMPLE +.SH SEE ALSO +.BR nsenter (1), +.BR unshare (1), +.BR clone (2), +.BR veth (4), +.BR proc (5), +.BR sysfs (5), +.BR namespaces (7), +.BR user_namespaces (7), +.BR brctl (8), +.BR ip (8), +.BR ip-address (8), +.BR ip-link (8), +.BR ip-netns (8), +.BR iptables (8), +.BR ovs-vsctl (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/nptl.7 b/man7/nptl.7 new file mode 100644 index 0000000..f2b2122 --- /dev/null +++ b/man7/nptl.7 @@ -0,0 +1,141 @@ +.\" Copyright (c) 2015 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH NPTL 7 2015-08-08 "Linux" "Linux Programmer's Manual" +.SH NAME +nptl \- Native POSIX Threads Library +.SH DESCRIPTION +NPTL (Native POSIX Threads Library) +is the GNU C library POSIX threads implementation that is used on modern +Linux systems. +.\" +.SS NPTL and signals +NPTL makes internal use of the first two real-time signals +(signal numbers 32 and 33). +One of these signals is used to support thread cancellation and POSIX timers +(see +.BR timer_create (2)); +the other is used as part of a mechanism that ensures all threads in +a process always have the same UIDs and GIDs, as required by POSIX. +These signals cannot be used in applications. +.PP +To prevent accidental use of these signals in applications, +which might interfere with the operation of the NPTL implementation, +various glibc library functions and system call wrapper functions +attempt to hide these signals from applications, +as follows: +.IP * 3 +.B SIGRTMIN +is defined with the value 34 (rather than 32). +.IP * +The +.BR sigwaitinfo (2), +.BR sigtimedwait (2), +and +.BR sigwait (3) +interfaces silently ignore requests to wait for these two signals +if they are specified in the signal set argument of these calls. +.IP * +The +.BR sigprocmask (2) +and +.BR pthread_sigmask (3) +interfaces silently ignore attempts to block these two signals. +.IP * +The +.BR sigaction (2), +.BR pthread_kill (3), +and +.BR pthread_sigqueue (3) +interfaces fail with the error +.B EINVAL +(indicating an invalid signal number) if these signals are specified. +.IP * +.BR sigfillset (3) +does not include these two signals when it creates a full signal set. +.\" +.SS NPTL and process credential changes +At the Linux kernel level, +credentials (user and group IDs) are a per-thread attribute. +However, POSIX requires that all of the POSIX threads in a process +have the same credentials. +To accommodate this requirement, +the NPTL implementation wraps all of the system calls that +change process credentials with functions that, +in addition to invoking the underlying system call, +arrange for all other threads in the process to also change their credentials. +.PP +The implementation of each of these system calls involves the use of +a real-time signal that is sent (using +.BR tgkill (2)) +to each of the other threads that must change its credentials. +Before sending these signals, the thread that is changing credentials +saves the new credential(s) and records the system call being employed +in a global buffer. +A signal handler in the receiving thread(s) fetches this information and +then uses the same system call to change its credentials. +.PP +Wrapper functions employing this technique are provided for +.BR setgid (2), +.BR setuid (2), +.BR setegid (2), +.BR seteuid (2), +.BR setregid (2), +.BR setreuid (2), +.BR setresgid (2), +.BR setresuid (2), +and +.BR setgroups (2). +.\" FIXME . +.\" Maybe say something about vfork() not being serialized wrt set*id() APIs? +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14749 +.SH CONFORMING TO +For details of the conformance of NPTL to the POSIX standard, see +.BR pthreads (7). +.SH NOTES +POSIX says +.\" See POSIX.1-2008 specification of pthread_mutexattr_init() +that any thread in any process with access to the memory +containing a process-shared +.RB ( PTHREAD_PROCESS_SHARED ) +mutex can operate on that mutex. +However, on 64-bit x86 systems, the mutex definition for x86-64 +is incompatible with the mutex definition for i386, +.\" See sysdeps/x86/bits/pthreadtypes.h +meaning that 32-bit and 64-bit binaries can't share mutexes on x86-64 systems. +.SH SEE ALSO +.BR credentials (7), +.BR pthreads (7), +.BR signal (7), +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/numa.7 b/man7/numa.7 new file mode 100644 index 0000000..ebef565 --- /dev/null +++ b/man7/numa.7 @@ -0,0 +1,199 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" and Copyright 2003,2004 Andi Kleen, SuSE Labs. +.\" numa_maps material Copyright (c) 2005 Silicon Graphics Incorporated. +.\" Christoph Lameter, . +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH NUMA 7 2012-08-05 "Linux" "Linux Programmer's Manual" +.SH NAME +numa \- overview of Non-Uniform Memory Architecture +.SH DESCRIPTION +Non-Uniform Memory Access (NUMA) refers to multiprocessor systems +whose memory is divided into multiple memory nodes. +The access time of a memory node depends on +the relative locations of the accessing CPU and the accessed node. +(This contrasts with a symmetric multiprocessor system, +where the access time for all of the memory is the same for all CPUs.) +Normally, each CPU on a NUMA system has a local memory node whose +contents can be accessed faster than the memory in +the node local to another CPU +or the memory on a bus shared by all CPUs. +.SS NUMA system calls +The Linux kernel implements the following NUMA-related system calls: +.BR get_mempolicy (2), +.BR mbind (2), +.BR migrate_pages (2), +.BR move_pages (2), +and +.BR set_mempolicy (2). +However, applications should normally use the interface provided by +.IR libnuma ; +see "Library Support" below. +.SS /proc/[number]/numa_maps (since Linux 2.6.14) +.\" See also Changelog-2.6.14 +This file displays information about a process's +NUMA memory policy and allocation. +.PP +Each line contains information about a memory range used by the process, +displaying\(emamong other information\(emthe effective memory policy for +that memory range and on which nodes the pages have been allocated. +.PP +.I numa_maps +is a read-only file. +When +.I /proc//numa_maps +is read, the kernel will scan the virtual address space of the +process and report how memory is used. +One line is displayed for each unique memory range of the process. +.PP +The first field of each line shows the starting address of the memory range. +This field allows a correlation with the contents of the +.I /proc//maps +file, +which contains the end address of the range and other information, +such as the access permissions and sharing. +.PP +The second field shows the memory policy currently in effect for the +memory range. +Note that the effective policy is not necessarily the policy +installed by the process for that memory range. +Specifically, if the process installed a "default" policy for that range, +the effective policy for that range will be the process policy, +which may or may not be "default". +.PP +The rest of the line contains information about the pages allocated in +the memory range, as follows: +.TP +.I N= +The number of pages allocated on +.IR . +.I +includes only pages currently mapped by the process. +Page migration and memory reclaim may have temporarily unmapped pages +associated with this memory range. +These pages may show up again only after the process has +attempted to reference them. +If the memory range represents a shared memory area or file mapping, +other processes may currently have additional pages mapped in a +corresponding memory range. +.TP +.I file= +The file backing the memory range. +If the file is mapped as private, write accesses may have generated +COW (Copy-On-Write) pages in this memory range. +These pages are displayed as anonymous pages. +.TP +.I heap +Memory range is used for the heap. +.TP +.I stack +Memory range is used for the stack. +.TP +.I huge +Huge memory range. +The page counts shown are huge pages and not regular sized pages. +.TP +.I anon= +The number of anonymous page in the range. +.TP +.I dirty= +Number of dirty pages. +.TP +.I mapped= +Total number of mapped pages, if different from +.IR dirty +and +.I anon +pages. +.TP +.I mapmax= +Maximum mapcount (number of processes mapping a single page) encountered +during the scan. +This may be used as an indicator of the degree of sharing occurring in a +given memory range. +.TP +.I swapcache= +Number of pages that have an associated entry on a swap device. +.TP +.I active= +The number of pages on the active list. +This field is shown only if different from the number of pages in this range. +This means that some inactive pages exist in the memory range that may be +removed from memory by the swapper soon. +.TP +.I writeback= +Number of pages that are currently being written out to disk. +.SH CONFORMING TO +No standards govern NUMA interfaces. +.SH NOTES +The Linux NUMA system calls and +.I /proc +interface are available only +if the kernel was configured and built with the +.BR CONFIG_NUMA +option. +.SS Library support +Link with \fI\-lnuma\fP +to get the system call definitions. +.I libnuma +and the required +.I +header are available in the +.I numactl +package. +.PP +However, applications should not use these system calls directly. +Instead, the higher level interface provided by the +.BR numa (3) +functions in the +.I numactl +package is recommended. +The +.I numactl +package is available at +.UR ftp://oss.sgi.com\:/www\:/projects\:/libnuma\:/download/ +.UE . +The package is also included in some Linux distributions. +Some distributions include the development library and header +in the separate +.I numactl-devel +package. +.SH SEE ALSO +.BR get_mempolicy (2), +.BR mbind (2), +.BR move_pages (2), +.BR set_mempolicy (2), +.BR numa (3), +.BR cpuset (7), +.BR numactl (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/operator.7 b/man7/operator.7 new file mode 100644 index 0000000..ab7e1b9 --- /dev/null +++ b/man7/operator.7 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)operator.7 8.1 (Berkeley) 6/9/93 +.\" +.\" Copied shamelessly from FreeBSD with minor changes. 2003-05-21 +.\" Brian M. Carlson +.\" +.\" Restored automatic formatting from FreeBSD. 2003-08-24 +.\" Martin Schulze +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH OPERATOR 7 2011-09-09 "Linux" "Linux Programmer's Manual" +.SH NAME +operator \- C operator precedence and order of evaluation +.SH DESCRIPTION +This manual page lists C operators and their precedence in evaluation. +.PP +.TS +lb lb +l l. +Operator Associativity +() [] \-> . left to right +! ~ ++ \-\- + \- (type) * & sizeof right to left +* / % left to right ++ \- left to right +<< >> left to right +< <= > >= left to right +== != left to right +& left to right +^ left to right +| left to right +&& left to right +|| left to right +?: right to left += += \-= *= /= %= <<= >>= &= ^= |= right to left +, left to right +.TE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/packet.7 b/man7/packet.7 new file mode 100644 index 0000000..c1d61cb --- /dev/null +++ b/man7/packet.7 @@ -0,0 +1,664 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ +.\" +.TH PACKET 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +packet \- packet interface on device level +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include /* the L2 protocols */ +.PP +.BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol ); +.fi +.SH DESCRIPTION +Packet sockets are used to receive or send raw packets at the device driver +(OSI Layer 2) level. +They allow the user to implement protocol modules in user space +on top of the physical layer. +.PP +The +.I socket_type +is either +.B SOCK_RAW +for raw packets including the link-level header or +.B SOCK_DGRAM +for cooked packets with the link-level header removed. +The link-level header information is available in a common format in a +.IR sockaddr_ll +structure. +.I protocol +is the IEEE 802.3 protocol number in network byte order. +See the +.I +include file for a list of allowed protocols. +When protocol +is set to +.BR htons(ETH_P_ALL) , +then all protocols are received. +All incoming packets of that protocol type will be passed to the packet +socket before they are passed to the protocols implemented in the kernel. +.PP +In order to create a packet socket, a process must have the +.B CAP_NET_RAW +capability in the user namespace that governs its network namespace. +.PP +.B SOCK_RAW +packets are passed to and from the device driver without any changes in +the packet data. +When receiving a packet, the address is still parsed and +passed in a standard +.I sockaddr_ll +address structure. +When transmitting a packet, the user-supplied buffer +should contain the physical-layer header. +That packet is then +queued unmodified to the network driver of the interface defined by the +destination address. +Some device drivers always add other headers. +.B SOCK_RAW +is similar to but not compatible with the obsolete +.B AF_INET/SOCK_PACKET +of Linux 2.0. +.PP +.B SOCK_DGRAM +operates on a slightly higher level. +The physical header is removed before the packet is passed to the user. +Packets sent through a +.B SOCK_DGRAM +packet socket get a suitable physical-layer header based on the +information in the +.I sockaddr_ll +destination address before they are queued. +.PP +By default, all packets of the specified protocol type +are passed to a packet socket. +To get packets only from a specific interface use +.BR bind (2) +specifying an address in a +.I struct sockaddr_ll +to bind the packet socket to an interface. +Fields used for binding are +.IR sll_family +(should be +.BR AF_PACKET ), +.IR sll_protocol , +and +.IR sll_ifindex . +.PP +The +.BR connect (2) +operation is not supported on packet sockets. +.PP +When the +.B MSG_TRUNC +flag is passed to +.BR recvmsg (2), +.BR recv (2), +or +.BR recvfrom (2), +the real length of the packet on the wire is always returned, +even when it is longer than the buffer. +.SS Address types +The +.I sockaddr_ll +structure is a device-independent physical-layer address. +.PP +.in +4n +.EX +struct sockaddr_ll { + unsigned short sll_family; /* Always AF_PACKET */ + unsigned short sll_protocol; /* Physical-layer protocol */ + int sll_ifindex; /* Interface number */ + unsigned short sll_hatype; /* ARP hardware type */ + unsigned char sll_pkttype; /* Packet type */ + unsigned char sll_halen; /* Length of address */ + unsigned char sll_addr[8]; /* Physical-layer address */ +}; +.EE +.in +.PP +The fields of this structure are as follows: +.IP * 3 +.I sll_protocol +is the standard ethernet protocol type in network byte order as defined +in the +.I +include file. +It defaults to the socket's protocol. +.IP * +.I sll_ifindex +is the interface index of the interface +(see +.BR netdevice (7)); +0 matches any interface (only permitted for binding). +.I sll_hatype +is an ARP type as defined in the +.I +include file. +.IP * +.I sll_pkttype +contains the packet type. +Valid types are +.B PACKET_HOST +for a packet addressed to the local host, +.B PACKET_BROADCAST +for a physical-layer broadcast packet, +.B PACKET_MULTICAST +for a packet sent to a physical-layer multicast address, +.B PACKET_OTHERHOST +for a packet to some other host that has been caught by a device driver +in promiscuous mode, and +.B PACKET_OUTGOING +for a packet originating from the local host that is looped back to a packet +socket. +These types make sense only for receiving. +.IP * +.I sll_addr +and +.I sll_halen +contain the physical-layer (e.g., IEEE 802.3) address and its length. +The exact interpretation depends on the device. +.PP +When you send packets, it is enough to specify +.IR sll_family , +.IR sll_addr , +.IR sll_halen , +.IR sll_ifindex , +and +.IR sll_protocol . +The other fields should be 0. +.I sll_hatype +and +.I sll_pkttype +are set on received packets for your information. +.SS Socket options +Packet socket options are configured by calling +.BR setsockopt (2) +with level +.BR SOL_PACKET . +.TP +.BR PACKET_ADD_MEMBERSHIP +.PD 0 +.TP +.BR PACKET_DROP_MEMBERSHIP +.PD +Packet sockets can be used to configure physical-layer multicasting +and promiscuous mode. +.B PACKET_ADD_MEMBERSHIP +adds a binding and +.B PACKET_DROP_MEMBERSHIP +drops it. +They both expect a +.I packet_mreq +structure as argument: +.IP +.in +4n +.EX +struct packet_mreq { + int mr_ifindex; /* interface index */ + unsigned short mr_type; /* action */ + unsigned short mr_alen; /* address length */ + unsigned char mr_address[8]; /* physical-layer address */ +}; +.EE +.in +.IP +.I mr_ifindex +contains the interface index for the interface whose status +should be changed. +The +.I mr_type +field specifies which action to perform. +.B PACKET_MR_PROMISC +enables receiving all packets on a shared medium (often known as +"promiscuous mode"), +.B PACKET_MR_MULTICAST +binds the socket to the physical-layer multicast group specified in +.I mr_address +and +.IR mr_alen , +and +.B PACKET_MR_ALLMULTI +sets the socket up to receive all multicast packets arriving at +the interface. +.IP +In addition, the traditional ioctls +.BR SIOCSIFFLAGS , +.BR SIOCADDMULTI , +.B SIOCDELMULTI +can be used for the same purpose. +.TP +.BR PACKET_AUXDATA " (since Linux 2.6.21)" +.\" commit 8dc4194474159660d7f37c495e3fc3f10d0db8cc +If this binary option is enabled, the packet socket passes a metadata +structure along with each packet in the +.BR recvmsg (2) +control field. +The structure can be read with +.BR cmsg (3). +It is defined as +.IP +.in +4n +.EX +struct tpacket_auxdata { + __u32 tp_status; + __u32 tp_len; /* packet length */ + __u32 tp_snaplen; /* captured length */ + __u16 tp_mac; + __u16 tp_net; + __u16 tp_vlan_tci; + __u16 tp_padding; +}; +.EE +.in +.TP +.BR PACKET_FANOUT " (since Linux 3.1)" +.\" commit dc99f600698dcac69b8f56dda9a8a00d645c5ffc +To scale processing across threads, packet sockets can form a fanout +group. +In this mode, each matching packet is enqueued onto only one +socket in the group. +A socket joins a fanout group by calling +.BR setsockopt (2) +with level +.B SOL_PACKET +and option +.BR PACKET_FANOUT . +Each network namespace can have up to 65536 independent groups. +A socket selects a group by encoding the ID in the first 16 bits of +the integer option value. +The first packet socket to join a group implicitly creates it. +To successfully join an existing group, subsequent packet sockets +must have the same protocol, device settings, fanout mode and +flags (see below). +Packet sockets can leave a fanout group only by closing the socket. +The group is deleted when the last socket is closed. +.IP +Fanout supports multiple algorithms to spread traffic between sockets, +as follows: +.RS +.IP * 3 +The default mode, +.BR PACKET_FANOUT_HASH , +sends packets from the same flow to the same socket to maintain +per-flow ordering. +For each packet, it chooses a socket by taking the packet flow hash +modulo the number of sockets in the group, where a flow hash is a hash +over network-layer address and optional transport-layer port fields. +.IP * +The load-balance mode +.BR PACKET_FANOUT_LB +implements a round-robin algorithm. +.IP * +.BR PACKET_FANOUT_CPU +selects the socket based on the CPU that the packet arrived on. +.IP * +.BR PACKET_FANOUT_ROLLOVER +processes all data on a single socket, moving to the next when one +becomes backlogged. +.IP * +.BR PACKET_FANOUT_RND +selects the socket using a pseudo-random number generator. +.IP * +.BR PACKET_FANOUT_QM +.\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd +(available since Linux 3.14) +selects the socket using the recorded queue_mapping of the received skb. +.RE +.IP +Fanout modes can take additional options. +IP fragmentation causes packets from the same flow to have different +flow hashes. +The flag +.BR PACKET_FANOUT_FLAG_DEFRAG , +if set, causes packets to be defragmented before fanout is applied, to +preserve order even in this case. +Fanout mode and options are communicated in the second 16 bits of the +integer option value. +The flag +.BR PACKET_FANOUT_FLAG_ROLLOVER +enables the roll over mechanism as a backup strategy: if the +original fanout algorithm selects a backlogged socket, the packet +rolls over to the next available one. +.TP +.BR PACKET_LOSS " (with " PACKET_TX_RING ) +When a malformed packet is encountered on a transmit ring, +the default is to reset its +.I tp_status +to +.BR TP_STATUS_WRONG_FORMAT +and abort the transmission immediately. +The malformed packet blocks itself and subsequently enqueued packets from +being sent. +The format error must be fixed, the associated +.I tp_status +reset to +.BR TP_STATUS_SEND_REQUEST , +and the transmission process restarted via +.BR send (2). +However, if +.BR PACKET_LOSS +is set, any malformed packet will be skipped, its +.I tp_status +reset to +.BR TP_STATUS_AVAILABLE , +and the transmission process continued. +.TP +.BR PACKET_RESERVE " (with " PACKET_RX_RING ) +By default, a packet receive ring writes packets immediately following the +metadata structure and alignment padding. +This integer option reserves additional headroom. +.TP +.BR PACKET_RX_RING +Create a memory-mapped ring buffer for asynchronous packet reception. +The packet socket reserves a contiguous region of application address +space, lays it out into an array of packet slots and copies packets +(up to +.IR tp_snaplen ) +into subsequent slots. +Each packet is preceded by a metadata structure similar to +.IR tpacket_auxdata . +The protocol fields encode the offset to the data +from the start of the metadata header. +.I tp_net +stores the offset to the network layer. +If the packet socket is of type +.BR SOCK_DGRAM , +then +.I tp_mac +is the same. +If it is of type +.BR SOCK_RAW , +then that field stores the offset to the link-layer frame. +Packet socket and application communicate the head and tail of the ring +through the +.I tp_status +field. +The packet socket owns all slots with +.I tp_status +equal to +.BR TP_STATUS_KERNEL . +After filling a slot, it changes the status of the slot to transfer +ownership to the application. +During normal operation, the new +.I tp_status +value has at least the +.BR TP_STATUS_USER +bit set to signal that a received packet has been stored. +When the application has finished processing a packet, it transfers +ownership of the slot back to the socket by setting +.I tp_status +equal to +.BR TP_STATUS_KERNEL . +.IP +Packet sockets implement multiple variants of the packet ring. +The implementation details are described in +.IR Documentation/networking/packet_mmap.txt +in the Linux kernel source tree. +.TP +.BR PACKET_STATISTICS +Retrieve packet socket statistics in the form of a structure +.IP +.in +4n +.EX +struct tpacket_stats { + unsigned int tp_packets; /* Total packet count */ + unsigned int tp_drops; /* Dropped packet count */ +}; +.EE +.in +.IP +Receiving statistics resets the internal counters. +The statistics structure differs when using a ring of variant +.BR TPACKET_V3 . +.TP +.BR PACKET_TIMESTAMP " (with " PACKET_RX_RING "; since Linux 2.6.36)" +.\" commit 614f60fa9d73a9e8fdff3df83381907fea7c5649 +The packet receive ring always stores a timestamp in the metadata header. +By default, this is a software generated timestamp generated when the +packet is copied into the ring. +This integer option selects the type of timestamp. +Besides the default, it support the two hardware formats described in +.IR Documentation/networking/timestamping.txt +in the Linux kernel source tree. +.TP +.BR PACKET_TX_RING " (since Linux 2.6.31)" +.\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1 +Create a memory-mapped ring buffer for packet transmission. +This option is similar to +.BR PACKET_RX_RING +and takes the same arguments. +The application writes packets into slots with +.I tp_status +equal to +.BR TP_STATUS_AVAILABLE +and schedules them for transmission by changing +.I tp_status +to +.BR TP_STATUS_SEND_REQUEST . +When packets are ready to be transmitted, the application calls +.BR send (2) +or a variant thereof. +The +.I buf +and +.I len +fields of this call are ignored. +If an address is passed using +.BR sendto (2) +or +.BR sendmsg (2), +then that overrides the socket default. +On successful transmission, the socket resets +.I tp_status +to +.BR TP_STATUS_AVAILABLE . +It immediately aborts the transmission on error unless +.BR PACKET_LOSS +is set. +.TP +.BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)" +.\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279 +By default, +.BR PACKET_RX_RING +creates a packet receive ring of variant +.BR TPACKET_V1 . +To create another variant, configure the desired variant by setting this +integer option before creating the ring. +.TP +.BR PACKET_QDISC_BYPASS " (since Linux 3.14)" +.\" commit d346a3fae3ff1d99f5d0c819bf86edf9094a26a1 +By default, packets sent through packet sockets pass through the kernel's +qdisc (traffic control) layer, which is fine for the vast majority of use +cases. +For traffic generator appliances using packet sockets +that intend to brute-force flood the network\(emfor example, +to test devices under load in a similar +fashion to pktgen\(emthis layer can be bypassed by setting +this integer option to 1. +A side effect is that packet buffering in the qdisc layer is avoided, +which will lead to increased drops when network +device transmit queues are busy; +therefore, use at your own risk. +.SS Ioctls +.B SIOCGSTAMP +can be used to receive the timestamp of the last received packet. +Argument is a +.I struct timeval +variable. +.\" FIXME Document SIOCGSTAMPNS +.PP +In addition, all standard ioctls defined in +.BR netdevice (7) +and +.BR socket (7) +are valid on packet sockets. +.SS Error handling +Packet sockets do no error handling other than errors occurred +while passing the packet to the device driver. +They don't have the concept of a pending error. +.SH ERRORS +.TP +.B EADDRNOTAVAIL +Unknown multicast group address passed. +.TP +.B EFAULT +User passed invalid memory address. +.TP +.B EINVAL +Invalid argument. +.TP +.B EMSGSIZE +Packet is bigger than interface MTU. +.TP +.B ENETDOWN +Interface is not up. +.TP +.B ENOBUFS +Not enough memory to allocate the packet. +.TP +.B ENODEV +Unknown device name or interface index specified in interface address. +.TP +.B ENOENT +No packet received. +.TP +.B ENOTCONN +No interface address passed. +.TP +.B ENXIO +Interface address contained an invalid interface index. +.TP +.B EPERM +User has insufficient privileges to carry out this operation. +.PP +In addition, other errors may be generated by the low-level driver. +.SH VERSIONS +.B AF_PACKET +is a new feature in Linux 2.2. +Earlier Linux versions supported only +.BR SOCK_PACKET . +.PP +.SH NOTES +For portable programs it is suggested to use +.B AF_PACKET +via +.BR pcap (3); +although this covers only a subset of the +.B AF_PACKET +features. +.PP +The +.B SOCK_DGRAM +packet sockets make no attempt to create or parse the IEEE 802.2 LLC +header for a IEEE 802.3 frame. +When +.B ETH_P_802_3 +is specified as protocol for sending the kernel creates the +802.3 frame and fills out the length field; the user has to supply the LLC +header to get a fully conforming packet. +Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol +fields; instead they are supplied to the user as protocol +.B ETH_P_802_2 +with the LLC header prefixed. +It is thus not possible to bind to +.BR ETH_P_802_3 ; +bind to +.B ETH_P_802_2 +instead and do the protocol multiplex yourself. +The default for sending is the standard Ethernet DIX +encapsulation with the protocol filled in. +.PP +Packet sockets are not subject to the input or output firewall chains. +.SS Compatibility +In Linux 2.0, the only way to get a packet socket was with the call: +.PP + socket(AF_INET, SOCK_PACKET, protocol) +.PP +This is still supported, but deprecated and strongly discouraged. +The main difference between the two methods is that +.B SOCK_PACKET +uses the old +.I struct sockaddr_pkt +to specify an interface, which doesn't provide physical-layer +independence. +.PP +.in +4n +.EX +struct sockaddr_pkt { + unsigned short spkt_family; + unsigned char spkt_device[14]; + unsigned short spkt_protocol; +}; +.EE +.in +.PP +.I spkt_family +contains +the device type, +.I spkt_protocol +is the IEEE 802.3 protocol type as defined in +.I +and +.I spkt_device +is the device name as a null-terminated string, for example, eth0. +.PP +This structure is obsolete and should not be used in new code. +.SH BUGS +The IEEE 802.2/803.3 LLC handling could be considered as a bug. +.PP +Socket filters are not documented. +.PP +The +.B MSG_TRUNC +.BR recvmsg (2) +extension is an ugly hack and should be replaced by a control message. +There is currently no way to get the original destination address of +packets via +.BR SOCK_DGRAM . +.\" .SH CREDITS +.\" This man page was written by Andi Kleen with help from Matthew Wilcox. +.\" AF_PACKET in Linux 2.2 was implemented +.\" by Alexey Kuznetsov, based on code by Alan Cox and others. +.SH SEE ALSO +.BR socket (2), +.BR pcap (3), +.BR capabilities (7), +.BR ip (7), +.BR raw (7), +.BR socket (7) +.PP +RFC\ 894 for the standard IP Ethernet encapsulation. +RFC\ 1700 for the IEEE 802.3 IP encapsulation. +.PP +The +.I +include file for physical-layer protocols. +.PP +The Linux kernel source tree. +.IR /Documentation/networking/filter.txt +describes how to apply Berkeley Packet Filters to packet sockets. +.IR /tools/testing/selftests/net/psock_tpacket.c +contains example source code for all available versions of +.BR PACKET_RX_RING +and +.BR PACKET_TX_RING . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/path_resolution.7 b/man7/path_resolution.7 new file mode 100644 index 0000000..94e0c97 --- /dev/null +++ b/man7/path_resolution.7 @@ -0,0 +1,267 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PATH_RESOLUTION 7 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +path_resolution \- how a pathname is resolved to a file +.SH DESCRIPTION +Some UNIX/Linux system calls have as parameter one or more filenames. +A filename (or pathname) is resolved as follows. +.SS Step 1: start of the resolution process +If the pathname starts with the \(aq/\(aq character, +the starting lookup directory +is the root directory of the calling process. +(A process inherits its +root directory from its parent. +Usually this will be the root directory +of the file hierarchy. +A process may get a different root directory +by use of the +.BR chroot (2) +system call. +A process may get an entirely private mount namespace in case +it\(emor one of its ancestors\(emwas started by an invocation of the +.BR clone (2) +system call that had the +.B CLONE_NEWNS +flag set.) +This handles the \(aq/\(aq part of the pathname. +.PP +If the pathname does not start with the \(aq/\(aq character, the +starting lookup directory of the resolution process is the current working +directory of the process. +(This is also inherited from the parent. +It can be changed by use of the +.BR chdir (2) +system call.) +.PP +Pathnames starting with a \(aq/\(aq character are called absolute pathnames. +Pathnames not starting with a \(aq/\(aq are called relative pathnames. +.SS Step 2: walk along the path +Set the current lookup directory to the starting lookup directory. +Now, for each nonfinal component of the pathname, where a component +is a substring delimited by \(aq/\(aq characters, this component is looked up +in the current lookup directory. +.PP +If the process does not have search permission on +the current lookup directory, +an +.B EACCES +error is returned ("Permission denied"). +.PP +If the component is not found, an +.B ENOENT +error is returned +("No such file or directory"). +.PP +If the component is found, but is neither a directory nor a symbolic link, +an +.B ENOTDIR +error is returned ("Not a directory"). +.PP +If the component is found and is a directory, we set the +current lookup directory to that directory, and go to the +next component. +.PP +If the component is found and is a symbolic link (symlink), we first +resolve this symbolic link (with the current lookup directory +as starting lookup directory). +Upon error, that error is returned. +If the result is not a directory, an +.B ENOTDIR +error is returned. +If the resolution of the symlink is successful and returns a directory, +we set the current lookup directory to that directory, and go to +the next component. +Note that the resolution process here can involve recursion if the +prefix ('dirname') component of a pathname contains a filename +that is a symbolic link that resolves to a directory (where the +prefix component of that directory may contain a symbolic link, and so on). +In order to protect the kernel against stack overflow, and also +to protect against denial of service, there are limits on the +maximum recursion depth, and on the maximum number of symbolic links +followed. +An +.B ELOOP +error is returned when the maximum is +exceeded ("Too many levels of symbolic links"). +.PP +.\" +.\" presently: max recursion depth during symlink resolution: 5 +.\" max total number of symbolic links followed: 40 +.\" _POSIX_SYMLOOP_MAX is 8 +As currently implemented on Linux, the maximum number +.\" MAXSYMLINKS is 40 +of symbolic links that will be followed while resolving a pathname is 40. +In kernels before 2.6.18, the limit on the recursion depth was 5. +Starting with Linux 2.6.18, this limit +.\" MAX_NESTED_LINKS +was raised to 8. +In Linux 4.2, +.\" commit 894bc8c4662ba9daceafe943a5ba0dd407da5cd3 +the kernel's pathname-resolution code +was reworked to eliminate the use of recursion, +so that the only limit that remains is the maximum of 40 +resolutions for the entire pathname. +.SS Step 3: find the final entry +The lookup of the final component of the pathname goes just like +that of all other components, as described in the previous step, +with two differences: (i) the final component need not be a +directory (at least as far as the path resolution process is +concerned\(emit may have to be a directory, or a nondirectory, because of +the requirements of the specific system call), and (ii) it +is not necessarily an error if the component is not found\(emmaybe +we are just creating it. +The details on the treatment +of the final entry are described in the manual pages of the specific +system calls. +.SS . and .. +By convention, every directory has the entries "." and "..", +which refer to the directory itself and to its parent directory, +respectively. +.PP +The path resolution process will assume that these entries have +their conventional meanings, regardless of whether they are +actually present in the physical filesystem. +.PP +One cannot walk down past the root: "/.." is the same as "/". +.SS Mount points +After a "mount dev path" command, the pathname "path" refers to +the root of the filesystem hierarchy on the device "dev", and no +longer to whatever it referred to earlier. +.PP +One can walk out of a mounted filesystem: "path/.." refers to +the parent directory of "path", +outside of the filesystem hierarchy on "dev". +.SS Trailing slashes +If a pathname ends in a \(aq/\(aq, that forces resolution of the preceding +component as in Step 2: it has to exist and resolve to a directory. +Otherwise, a trailing \(aq/\(aq is ignored. +(Or, equivalently, a pathname with a trailing \(aq/\(aq is equivalent to +the pathname obtained by appending \(aq.\(aq to it.) +.SS Final symlink +If the last component of a pathname is a symbolic link, then it +depends on the system call whether the file referred to will be +the symbolic link or the result of path resolution on its contents. +For example, the system call +.BR lstat (2) +will operate on the symlink, while +.BR stat (2) +operates on the file pointed to by the symlink. +.SS Length limit +There is a maximum length for pathnames. +If the pathname (or some +intermediate pathname obtained while resolving symbolic links) +is too long, an +.B ENAMETOOLONG +error is returned ("Filename too long"). +.SS Empty pathname +In the original UNIX, the empty pathname referred to the current directory. +Nowadays POSIX decrees that an empty pathname must not be resolved +successfully. +Linux returns +.B ENOENT +in this case. +.SS Permissions +The permission bits of a file consist of three groups of three bits; see +.BR chmod (1) +and +.BR stat (2). +The first group of three is used when the effective user ID of +the calling process equals the owner ID of the file. +The second group +of three is used when the group ID of the file either equals the +effective group ID of the calling process, or is one of the +supplementary group IDs of the calling process (as set by +.BR setgroups (2)). +When neither holds, the third group is used. +.PP +Of the three bits used, the first bit determines read permission, +the second write permission, and the last execute permission +in case of ordinary files, or search permission in case of directories. +.PP +Linux uses the fsuid instead of the effective user ID in permission checks. +Ordinarily the fsuid will equal the effective user ID, but the fsuid can be +changed by the system call +.BR setfsuid (2). +.PP +(Here "fsuid" stands for something like "filesystem user ID". +The concept was required for the implementation of a user space +NFS server at a time when processes could send a signal to a process +with the same effective user ID. +It is obsolete now. +Nobody should use +.BR setfsuid (2).) +.PP +Similarly, Linux uses the fsgid ("filesystem group ID") +instead of the effective group ID. +See +.BR setfsgid (2). +.\" FIXME . say something about filesystem mounted read-only ? +.SS Bypassing permission checks: superuser and capabilities +On a traditional UNIX system, the superuser +.RI ( root , +user ID 0) is all-powerful, and bypasses all permissions restrictions +when accessing files. +.\" (but for exec at least one x bit must be set) -- AEB +.\" but there is variation across systems on this point: for +.\" example, HP-UX and Tru64 are as described by AEB. However, +.\" on some implementations (e.g., Solaris, FreeBSD), +.\" access(X_OK) by superuser will report success, regardless +.\" of the file's execute permission bits. -- MTK (Oct 05) +.PP +On Linux, superuser privileges are divided into capabilities (see +.BR capabilities (7)). +Two capabilities are relevant for file permissions checks: +.B CAP_DAC_OVERRIDE +and +.BR CAP_DAC_READ_SEARCH . +(A process has these capabilities if its fsuid is 0.) +.PP +The +.B CAP_DAC_OVERRIDE +capability overrides all permission checking, +but grants execute permission only when at least one +of the file's three execute permission bits is set. +.PP +The +.B CAP_DAC_READ_SEARCH +capability grants read and search permission +on directories, and read permission on ordinary files. +.\" FIXME . say something about immutable files +.\" FIXME . say something about ACLs +.SH SEE ALSO +.BR readlink (2), +.BR capabilities (7), +.BR credentials (7), +.BR symlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/persistent-keyring.7 b/man7/persistent-keyring.7 new file mode 100644 index 0000000..f74762b --- /dev/null +++ b/man7/persistent-keyring.7 @@ -0,0 +1,135 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH "PERSISTENT-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual" +.SH NAME +persistent-keyring \- per-user persistent keyring +.SH DESCRIPTION +The persistent keyring is a keyring used to anchor keys on behalf of a user. +Each UID the kernel deals with has its own persistent keyring that +is shared between all threads owned by that UID. +The persistent keyring has a name (description) of the form +.I _persistent. +where +.I +is the user ID of the corresponding user. +.PP +The persistent keyring may not be accessed directly, +even by processes with the appropriate UID. +.\" FIXME The meaning of the preceding sentence isn't clear. What is meant? +Instead, it must first be linked to one of a process's keyrings, +before that keyring can access the persistent keyring +by virtue of its possessor permits. +This linking is done with the +.BR keyctl_get_persistent (3) +function. +.PP +If a persistent keyring does not exist when it is accessed by the +.BR keyctl_get_persistent (3) +operation, it will be automatically created. +.PP +Each time the +.BR keyctl_get_persistent (3) +operation is performed, +the persistent key's expiration timer is reset to the value in: +.PP + /proc/sys/kernel/keys/persistent_keyring_expiry +.PP +Should the timeout be reached, +the persistent keyring will be removed and +everything it pins can then be garbage collected. +The key will then be re-created on a subsequent call to +.BR keyctl_get_persistent (3). +.PP +The persistent keyring is not directly searched by +.BR request_key (2); +it is searched only if it is linked into one of the keyrings +that is searched by +.BR request_key (2). +.PP +The persistent keyring is independent of +.BR clone (2), +.BR fork (2), +.BR vfork (2), +.BR execve (2), +and +.BR _exit (2). +It persists until its expiration timer triggers, +at which point it is garbage collected. +This allows the persistent keyring to carry keys beyond the life of +the kernel's record of the corresponding UID +(the destruction of which results in the destruction of the +.BR user-keyring (7) +and the +.BR user-session-keyring (7)). +The persistent keyring can thus be used to +hold authentication tokens for processes that run without user interaction, +such as programs started by +.BR cron (8). +.PP +The persistent keyring is used to store UID-specific objects that +themselves have limited lifetimes (e.g., kerberos tokens). +If those tokens cease to be used +(i.e., the persistent keyring is not accessed), +then the timeout of the persistent keyring ensures that +the corresponding objects are automatically discarded. +.\" +.SS Special operations +The +.I keyutils +library provides the +.BR keyctl_get_persistent (3) +function for manipulating persistent keyrings. +(This function is an interface to the +.BR keyctl (2) +.B KEYCTL_GET_PERSISTENT +operation.) +This operation allows the calling thread to get the persistent keyring +corresponding to its own UID or, if the thread has the +.BR CAP_SETUID +capability, the persistent keyring corresponding to some other UID +in the same user namespace. +.SH NOTES +Each user namespace owns a keyring called +.IR .persistent_register +that contains links to all of the persistent keys in that namespace. +(The +.IR .persistent_register +keyring can be seen when reading the contents of the +.IR /proc/keys +file for the UID 0 in the namespace.) +The +.BR keyctl_get_persistent (3) +operation looks for a key with a name of the form +.IR _persistent. +in that keyring, +creates the key if it does not exist, and links it into the keyring. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyctl_get_persistent (3), +.BR keyrings (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/pid_namespaces.7 b/man7/pid_namespaces.7 new file mode 100644 index 0000000..39136b8 --- /dev/null +++ b/man7/pid_namespaces.7 @@ -0,0 +1,385 @@ +.\" Copyright (c) 2013 by Michael Kerrisk +.\" and Copyright (c) 2012 by Eric W. Biederman +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH PID_NAMESPACES 7 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +pid_namespaces \- overview of Linux PID namespaces +.SH DESCRIPTION +For an overview of namespaces, see +.BR namespaces (7). +.PP +PID namespaces isolate the process ID number space, +meaning that processes in different PID namespaces can have the same PID. +PID namespaces allow containers to provide functionality +such as suspending/resuming the set of processes in the container and +migrating the container to a new host +while the processes inside the container maintain the same PIDs. +.PP +PIDs in a new PID namespace start at 1, +somewhat like a standalone system, and calls to +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +will produce processes with PIDs that are unique within the namespace. +.PP +Use of PID namespaces requires a kernel that is configured with the +.B CONFIG_PID_NS +option. +.\" +.\" ============================================================ +.\" +.SS The namespace "init" process +The first process created in a new namespace +(i.e., the process created using +.BR clone (2) +with the +.BR CLONE_NEWPID +flag, or the first child created by a process after a call to +.BR unshare (2) +using the +.BR CLONE_NEWPID +flag) has the PID 1, and is the "init" process for the namespace (see +.BR init (1)). +A child process that is orphaned within the namespace will be reparented +to this process rather than +.BR init (1) +(unless one of the ancestors of the child +in the same PID namespace employed the +.BR prctl (2) +.B PR_SET_CHILD_SUBREAPER +command to mark itself as the reaper of orphaned descendant processes). +.PP +If the "init" process of a PID namespace terminates, +the kernel terminates all of the processes in the namespace via a +.BR SIGKILL +signal. +This behavior reflects the fact that the "init" process +is essential for the correct operation of a PID namespace. +In this case, a subsequent +.BR fork (2) +into this PID namespace fail with the error +.BR ENOMEM ; +it is not possible to create a new processes in a PID namespace whose "init" +process has terminated. +Such scenarios can occur when, for example, +a process uses an open file descriptor for a +.I /proc/[pid]/ns/pid +file corresponding to a process that was in a namespace to +.BR setns (2) +into that namespace after the "init" process has terminated. +Another possible scenario can occur after a call to +.BR unshare (2): +if the first child subsequently created by a +.BR fork (2) +terminates, then subsequent calls to +.BR fork (2) +fail with +.BR ENOMEM . +.PP +Only signals for which the "init" process has established a signal handler +can be sent to the "init" process by other members of the PID namespace. +This restriction applies even to privileged processes, +and prevents other members of the PID namespace from +accidentally killing the "init" process. +.PP +Likewise, a process in an ancestor namespace +can\(emsubject to the usual permission checks described in +.BR kill (2)\(emsend +signals to the "init" process of a child PID namespace only +if the "init" process has established a handler for that signal. +(Within the handler, the +.I siginfo_t +.I si_pid +field described in +.BR sigaction (2) +will be zero.) +.B SIGKILL +or +.B SIGSTOP +are treated exceptionally: +these signals are forcibly delivered when sent from an ancestor PID namespace. +Neither of these signals can be caught by the "init" process, +and so will result in the usual actions associated with those signals +(respectively, terminating and stopping the process). +.PP +Starting with Linux 3.4, the +.BR reboot (2) +system call causes a signal to be sent to the namespace "init" process. +See +.BR reboot (2) +for more details. +.\" +.\" ============================================================ +.\" +.SS Nesting PID namespaces +PID namespaces can be nested: +each PID namespace has a parent, +except for the initial ("root") PID namespace. +The parent of a PID namespace is the PID namespace of the process that +created the namespace using +.BR clone (2) +or +.BR unshare (2). +PID namespaces thus form a tree, +with all namespaces ultimately tracing their ancestry to the root namespace. +Since Linux 3.7, +.\" commit f2302505775fd13ba93f034206f1e2a587017929 +.\" The kernel constant MAX_PID_NS_LEVEL +the kernel limits the maximum nesting depth for PID namespaces to 32. +.PP +A process is visible to other processes in its PID namespace, +and to the processes in each direct ancestor PID namespace +going back to the root PID namespace. +In this context, "visible" means that one process +can be the target of operations by another process using +system calls that specify a process ID. +Conversely, the processes in a child PID namespace can't see +processes in the parent and further removed ancestor namespaces. +More succinctly: a process can see (e.g., send signals with +.BR kill (2), +set nice values with +.BR setpriority (2), +etc.) only processes contained in its own PID namespace +and in descendants of that namespace. +.PP +A process has one process ID in each of the layers of the PID +namespace hierarchy in which is visible, +and walking back though each direct ancestor namespace +through to the root PID namespace. +System calls that operate on process IDs always +operate using the process ID that is visible in the +PID namespace of the caller. +A call to +.BR getpid (2) +always returns the PID associated with the namespace in which +the process was created. +.PP +Some processes in a PID namespace may have parents +that are outside of the namespace. +For example, the parent of the initial process in the namespace +(i.e., the +.BR init (1) +process with PID 1) is necessarily in another namespace. +Likewise, the direct children of a process that uses +.BR setns (2) +to cause its children to join a PID namespace are in a different +PID namespace from the caller of +.BR setns (2). +Calls to +.BR getppid (2) +for such processes return 0. +.PP +While processes may freely descend into child PID namespaces +(e.g., using +.BR setns (2) +with a PID namespace file descriptor), +they may not move in the other direction. +That is to say, processes may not enter any ancestor namespaces +(parent, grandparent, etc.). +Changing PID namespaces is a one-way operation. +.PP +The +.BR NS_GET_PARENT +.BR ioctl (2) +operation can be used to discover the parental relationship +between PID namespaces; see +.BR ioctl_ns (2). +.\" +.\" ============================================================ +.\" +.SS setns(2) and unshare(2) semantics +Calls to +.BR setns (2) +that specify a PID namespace file descriptor +and calls to +.BR unshare (2) +with the +.BR CLONE_NEWPID +flag cause children subsequently created +by the caller to be placed in a different PID namespace from the caller. +(Since Linux 4.12, that PID namespace is shown via the +.IR /proc/[pid]/ns/pid_for_children +file, as described in +.BR namespaces (7).) +These calls do not, however, +change the PID namespace of the calling process, +because doing so would change the caller's idea of its own PID +(as reported by +.BR getpid ()), +which would break many applications and libraries. +.PP +To put things another way: +a process's PID namespace membership is determined when the process is created +and cannot be changed thereafter. +Among other things, this means that the parental relationship +between processes mirrors the parental relationship between PID namespaces: +the parent of a process is either in the same namespace +or resides in the immediate parent PID namespace. +.SS Compatibility of CLONE_NEWPID with other CLONE_* flags +In current versions of Linux, +.BR CLONE_NEWPID +can't be combined with +.BR CLONE_THREAD . +Threads are required to be in the same PID namespace such that +the threads in a process can send signals to each other. +Similarly, it must be possible to see all of the threads +of a processes in the +.BR proc (5) +filesystem. +Additionally, if two threads were in different PID +namespaces, the process ID of the process sending a signal +could not be meaningfully encoded when a signal is sent +(see the description of the +.I siginfo_t +type in +.BR sigaction (2)). +Since this is computed when a signal is enqueued, +a signal queue shared by processes in multiple PID namespaces +would defeat that. +.PP +.\" Note these restrictions were all introduced in +.\" 8382fcac1b813ad0a4e68a838fc7ae93fa39eda0 +.\" when CLONE_NEWPID|CLONE_VM was disallowed +In earlier versions of Linux, +.BR CLONE_NEWPID +was additionally disallowed (failing with the error +.BR EINVAL ) +in combination with +.BR CLONE_SIGHAND +.\" (restriction lifted in faf00da544045fdc1454f3b9e6d7f65c841de302) +(before Linux 4.3) as well as +.\" (restriction lifted in e79f525e99b04390ca4d2366309545a836c03bf1) +.BR CLONE_VM +(before Linux 3.12). +The changes that lifted these restrictions have also been ported to +earlier stable kernels. +.\" +.\" ============================================================ +.\" +.SS /proc and PID namespaces +A +.I /proc +filesystem shows (in the +.I /proc/[pid] +directories) only processes visible in the PID namespace +of the process that performed the mount, even if the +.I /proc +filesystem is viewed from processes in other namespaces. +.PP +After creating a new PID namespace, +it is useful for the child to change its root directory +and mount a new procfs instance at +.I /proc +so that tools such as +.BR ps (1) +work correctly. +If a new mount namespace is simultaneously created by including +.BR CLONE_NEWNS +in the +.IR flags +argument of +.BR clone (2) +or +.BR unshare (2), +then it isn't necessary to change the root directory: +a new procfs instance can be mounted directly over +.IR /proc . +.PP +From a shell, the command to mount +.I /proc +is: +.PP +.in +4n +.EX +$ mount -t proc proc /proc +.EE +.in +.PP +Calling +.BR readlink (2) +on the path +.I /proc/self +yields the process ID of the caller in the PID namespace of the procfs mount +(i.e., the PID namespace of the process that mounted the procfs). +This can be useful for introspection purposes, +when a process wants to discover its PID in other namespaces. +.\" +.\" ============================================================ +.\" +.SS /proc files +.TP +.BR /proc/sys/kernel/ns_last_pid " (since Linux 3.3)" +.\" commit b8f566b04d3cddd192cfd2418ae6d54ac6353792 +This file displays the last PID that was allocated in this PID namespace. +When the next PID is allocated, +the kernel will search for the lowest unallocated PID +that is greater than this value, +and when this file is subsequently read it will show that PID. +.IP +This file is writable by a process that has the +.B CAP_SYS_ADMIN +capability inside its user namespace. +.\" This ability is necessary to support checkpoint restore in user-space +This makes it possible to determine the PID that is allocated +to the next process that is created inside this PID namespace. +.\" +.\" ============================================================ +.\" +.SS Miscellaneous +When a process ID is passed over a UNIX domain socket to a +process in a different PID namespace (see the description of +.B SCM_CREDENTIALS +in +.BR unix (7)), +it is translated into the corresponding PID value in +the receiving process's PID namespace. +.SH CONFORMING TO +Namespaces are a Linux-specific feature. +.SH EXAMPLE +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR clone (2), +.BR reboot (2), +.BR setns (2), +.BR unshare (2), +.BR proc (5), +.BR capabilities (7), +.BR credentials (7), +.BR mount_namespaces (7), +.BR namespaces (7), +.BR user_namespaces (7), +.BR switch_root (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/pipe.7 b/man7/pipe.7 new file mode 100644 index 0000000..e47b791 --- /dev/null +++ b/man7/pipe.7 @@ -0,0 +1,428 @@ +.\" Copyright (C) 2005 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PIPE 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pipe \- overview of pipes and FIFOs +.SH DESCRIPTION +Pipes and FIFOs (also known as named pipes) +provide a unidirectional interprocess communication channel. +A pipe has a +.I read end +and a +.IR "write end" . +Data written to the write end of a pipe can be read +from the read end of the pipe. +.PP +A pipe is created using +.BR pipe (2), +which creates a new pipe and returns two file descriptors, +one referring to the read end of the pipe, +the other referring to the write end. +Pipes can be used to create a communication channel between related +processes; see +.BR pipe (2) +for an example. +.PP +A FIFO (short for First In First Out) has a name within the filesystem +(created using +.BR mkfifo (3)), +and is opened using +.BR open (2). +Any process may open a FIFO, assuming the file permissions allow it. +The read end is opened using the +.B O_RDONLY +flag; the write end is opened using the +.B O_WRONLY +flag. +See +.BR fifo (7) +for further details. +.IR Note : +although FIFOs have a pathname in the filesystem, +I/O on FIFOs does not involve operations on the underlying device +(if there is one). +.SS I/O on pipes and FIFOs +The only difference between pipes and FIFOs is the manner in which +they are created and opened. +Once these tasks have been accomplished, +I/O on pipes and FIFOs has exactly the same semantics. +.PP +If a process attempts to read from an empty pipe, then +.BR read (2) +will block until data is available. +If a process attempts to write to a full pipe (see below), then +.BR write (2) +blocks until sufficient data has been read from the pipe +to allow the write to complete. +Nonblocking I/O is possible by using the +.BR fcntl (2) +.B F_SETFL +operation to enable the +.B O_NONBLOCK +open file status flag. +.PP +The communication channel provided by a pipe is a +.IR "byte stream" : +there is no concept of message boundaries. +.PP +If all file descriptors referring to the write end of a pipe +have been closed, then an attempt to +.BR read (2) +from the pipe will see end-of-file +.RB ( read (2) +will return 0). +If all file descriptors referring to the read end of a pipe +have been closed, then a +.BR write (2) +will cause a +.B SIGPIPE +signal to be generated for the calling process. +If the calling process is ignoring this signal, then +.BR write (2) +fails with the error +.BR EPIPE . +An application that uses +.BR pipe (2) +and +.BR fork (2) +should use suitable +.BR close (2) +calls to close unnecessary duplicate file descriptors; +this ensures that end-of-file and +.BR SIGPIPE / EPIPE +are delivered when appropriate. +.PP +It is not possible to apply +.BR lseek (2) +to a pipe. +.SS Pipe capacity +A pipe has a limited capacity. +If the pipe is full, then a +.BR write (2) +will block or fail, depending on whether the +.B O_NONBLOCK +flag is set (see below). +Different implementations have different limits for the pipe capacity. +Applications should not rely on a particular capacity: +an application should be designed so that a reading process consumes data +as soon as it is available, +so that a writing process does not remain blocked. +.PP +In Linux versions before 2.6.11, the capacity of a pipe was the same as +the system page size (e.g., 4096 bytes on i386). +Since Linux 2.6.11, the pipe capacity is 16 pages +(i.e., 65,536 bytes in a system with a page size of 4096 bytes). +Since Linux 2.6.35, the default pipe capacity is 16 pages, +but the capacity can be queried and set using the +.BR fcntl (2) +.BR F_GETPIPE_SZ +and +.BR F_SETPIPE_SZ +operations. +See +.BR fcntl (2) +for more information. +.PP +The following +.BR ioctl (2) +operation, which can be applied to a file descriptor +that refers to either end of a pipe, +places a count of the number of unread bytes in the pipe in the +.I int +buffer pointed to by the final argument of the call: +.PP + ioctl(fd, FIONREAD, &nbytes); +.PP +The +.B FIONREAD +operation is not specified in any standard, +but is provided on many implementations. +.\" +.SS /proc files +On Linux, the following files control how much memory can be used for pipes: +.TP +.IR /proc/sys/fs/pipe-max-pages " (only in Linux 2.6.34)" +.\" commit b492e95be0ae672922f4734acf3f5d35c30be948 +An upper limit, in pages, on the capacity that an unprivileged user +(one without the +.BR CAP_SYS_RESOURCE +capability) +can set for a pipe. +.IP +The default value for this limit is 16 times the default pipe capacity +(see above); the lower limit is two pages. +.IP +This interface was removed in Linux 2.6.35, in favor of +.IR /proc/sys/fs/pipe-max-size . +.TP +.IR /proc/sys/fs/pipe-max-size " (since Linux 2.6.35)" +.\" commit ff9da691c0498ff81fdd014e7a0731dab2337dac +The maximum size (in bytes) of individual pipes that can be set +.\" This limit is not checked on pipe creation, where the capacity is +.\" always PIPE_DEF_BUFS, regardless of pipe-max-size +by users without the +.B CAP_SYS_RESOURCE +capability. +The value assigned to this file may be rounded upward, +to reflect the value actually employed for a convenient implementation. +To determine the rounded-up value, +display the contents of this file after assigning a value to it. +.IP +The default value for this file is 1048576 (1\ MiB). +The minimum value that can be assigned to this file is the system page size. +Attempts to set a limit less than the page size cause +.BR write (2) +to fail with the error +.BR EINVAL . +.IP +Since Linux 4.9, +.\" commit 086e774a57fba4695f14383c0818994c0b31da7c +the value on this file also acts as a ceiling on the default capacity +of a new pipe or newly opened FIFO. +.TP +.IR /proc/sys/fs/pipe-user-pages-hard " (since Linux 4.5)" +.\" commit 759c01142a5d0f364a462346168a56de28a80f52 +The hard limit on the total size (in pages) of all pipes created or set by +a single unprivileged user (i.e., one with neither the +.B CAP_SYS_RESOURCE +nor the +.B CAP_SYS_ADMIN +capability). +So long as the total number of pages allocated to pipe buffers +for this user is at this limit, +attempts to create new pipes will be denied, +and attempts to increase a pipe's capacity will be denied. +.IP +When the value of this limit is zero (which is the default), +no hard limit is applied. +.\" The default was chosen to avoid breaking existing applications that +.\" make intensive use of pipes (e.g., for splicing). +.TP +.IR /proc/sys/fs/pipe-user-pages-soft " (since Linux 4.5)" +.\" commit 759c01142a5d0f364a462346168a56de28a80f52 +The soft limit on the total size (in pages) of all pipes created or set by +a single unprivileged user (i.e., one with neither the +.B CAP_SYS_RESOURCE +nor the +.B CAP_SYS_ADMIN +capability). +So long as the total number of pages allocated to pipe buffers +for this user is at this limit, +individual pipes created by a user will be limited to one page, +and attempts to increase a pipe's capacity will be denied. +.IP +When the value of this limit is zero, no soft limit is applied. +The default value for this file is 16384, +which permits creating up to 1024 pipes with the default capacity. +.PP +Before Linux 4.9, some bugs affected the handling of the +.IR pipe-user-pages-soft +and +.IR pipe-user-pages-hard +limits; see BUGS. +.\" +.SS PIPE_BUF +POSIX.1 says that +.BR write (2)s +of less than +.B PIPE_BUF +bytes must be atomic: the output data is written to the pipe as a +contiguous sequence. +Writes of more than +.B PIPE_BUF +bytes may be nonatomic: the kernel may interleave the data +with data written by other processes. +POSIX.1 requires +.B PIPE_BUF +to be at least 512 bytes. +(On Linux, +.B PIPE_BUF +is 4096 bytes.) +The precise semantics depend on whether the file descriptor is nonblocking +.RB ( O_NONBLOCK ), +whether there are multiple writers to the pipe, and on +.IR n , +the number of bytes to be written: +.TP +\fBO_NONBLOCK\fP disabled, \fIn\fP <= \fBPIPE_BUF\fP +All +.I n +bytes are written atomically; +.BR write (2) +may block if there is not room for +.I n +bytes to be written immediately +.TP +\fBO_NONBLOCK\fP enabled, \fIn\fP <= \fBPIPE_BUF\fP +If there is room to write +.I n +bytes to the pipe, then +.BR write (2) +succeeds immediately, writing all +.I n +bytes; otherwise +.BR write (2) +fails, with +.I errno +set to +.BR EAGAIN . +.TP +\fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP +The write is nonatomic: the data given to +.BR write (2) +may be interleaved with +.BR write (2)s +by other process; +the +.BR write (2) +blocks until +.I n +bytes have been written. +.TP +\fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP +If the pipe is full, then +.BR write (2) +fails, with +.I errno +set to +.BR EAGAIN . +Otherwise, from 1 to +.I n +bytes may be written (i.e., a "partial write" may occur; +the caller should check the return value from +.BR write (2) +to see how many bytes were actually written), +and these bytes may be interleaved with writes by other processes. +.SS Open file status flags +The only open file status flags that can be meaningfully applied to +a pipe or FIFO are +.B O_NONBLOCK +and +.BR O_ASYNC . +.PP +Setting the +.B O_ASYNC +flag for the read end of a pipe causes a signal +.RB ( SIGIO +by default) to be generated when new input becomes available on the pipe. +The target for delivery of signals must be set using the +.BR fcntl (2) +.B F_SETOWN +command. +On Linux, +.B O_ASYNC +is supported for pipes and FIFOs only since kernel 2.6. +.SS Portability notes +On some systems (but not Linux), pipes are bidirectional: +data can be transmitted in both directions between the pipe ends. +POSIX.1 requires only unidirectional pipes. +Portable applications should avoid reliance on +bidirectional pipe semantics. +.SS BUGS +Before Linux 4.9, some bugs affected the handling of the +.IR pipe-user-pages-soft +and +.IR pipe-user-pages-hard +limits when using the +.BR fcntl (2) +.BR F_SETPIPE_SZ +operation to change a pipe's capacity: +.\" These bugs where remedied by a series of patches, in particular, +.\" commit b0b91d18e2e97b741b294af9333824ecc3fadfd8 and +.\" commit a005ca0e6813e1d796a7422a7e31d8b8d6555df1 +.IP (1) 5 +When increasing the pipe capacity, the checks against the soft and +hard limits were made against existing consumption, +and excluded the memory required for the increased pipe capacity. +The new increase in pipe capacity could then push the total +memory used by the user for pipes (possibly far) over a limit. +(This could also trigger the problem described next.) +.IP +Starting with Linux 4.9, +the limit checking includes the memory required for the new pipe capacity. +.IP (2) +The limit checks were performed even when the new pipe capacity was +less than the existing pipe capacity. +This could lead to problems if a user set a large pipe capacity, +and then the limits were lowered, with the result that the user could +no longer decrease the pipe capacity. +.IP +Starting with Linux 4.9, checks against the limits +are performed only when increasing a pipe's capacity; +an unprivileged user can always decrease a pipe's capacity. +.IP (3) +The accounting and checking against the limits were done as follows: +.IP +.RS +.PD 0 +.IP (a) 4 +Test whether the user has exceeded the limit. +.IP (b) +Make the new pipe buffer allocation. +.IP (c) +Account new allocation against the limits. +.PD +.RE +.IP +This was racey. +Multiple processes could pass point (a) simultaneously, +and then allocate pipe buffers that were accounted for only in step (c), +with the result that the user's pipe buffer +allocation could be pushed over the limit. +.IP +Starting with Linux 4.9, +the accounting step is performed before doing the allocation, +and the operation fails if the limit would be exceeded. +.PP +Before Linux 4.9, bugs similar to points (1) and (3) could also occur +when the kernel allocated memory for a new pipe buffer; +that is, when calling +.BR pipe (2) +and when opening a previously unopened FIFO. +.SH SEE ALSO +.BR mkfifo (1), +.BR dup (2), +.BR fcntl (2), +.BR open (2), +.BR pipe (2), +.BR poll (2), +.BR select (2), +.BR socketpair (2), +.BR splice (2), +.BR stat (2), +.BR tee (2), +.BR vmsplice (2), +.BR mkfifo (3), +.BR epoll (7), +.BR fifo (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/pkeys.7 b/man7/pkeys.7 new file mode 100644 index 0000000..f2e9251 --- /dev/null +++ b/man7/pkeys.7 @@ -0,0 +1,305 @@ +.\" Copyright (C) 2016 Intel Corporation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PKEYS 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pkeys \- overview of Memory Protection Keys +.SH DESCRIPTION +Memory Protection Keys (pkeys) are an extension to existing +page-based memory permissions. +Normal page permissions using +page tables require expensive system calls and TLB invalidations +when changing permissions. +Memory Protection Keys provide a mechanism for changing +protections without requiring modification of the page tables on +every permission change. +.PP +To use pkeys, software must first "tag" a page in the page tables +with a pkey. +After this tag is in place, an application only has +to change the contents of a register in order to remove write +access, or all access to a tagged page. +.PP +Protection keys work in conjunction with the existing +.BR PROT_READ / +.BR PROT_WRITE / +.BR PROT_EXEC +permissions passed to system calls such as +.BR mprotect (2) +and +.BR mmap (2), +but always act to further restrict these traditional permission +mechanisms. +.PP +If a process performs an access that violates pkey +restrictions, it receives a +.BR SIGSEGV +signal. +See +.BR sigaction (2) +for details of the information available with that signal. +.PP +To use the pkeys feature, the processor must support it, and the kernel +must contain support for the feature on a given processor. +As of early 2016 only future Intel x86 processors are supported, +and this hardware supports 16 protection keys in each process. +However, pkey 0 is used as the default key, so a maximum of 15 +are available for actual application use. +The default key is assigned to any memory region for which a +pkey has not been explicitly assigned via +.BR pkey_mprotect (2). +.PP +Protection keys have the potential to add a layer of security and +reliability to applications. +But they have not been primarily designed as +a security feature. +For instance, WRPKRU is a completely unprivileged +instruction, so pkeys are useless in any case that an attacker controls +the PKRU register or can execute arbitrary instructions. +.PP +Applications should be very careful to ensure that they do not "leak" +protection keys. +For instance, before calling +.BR pkey_free (2), +the application should be sure that no memory has that pkey assigned. +If the application left the freed pkey assigned, a future user of +that pkey might inadvertently change the permissions of an unrelated +data structure, which could impact security or stability. +The kernel currently allows in-use pkeys to have +.BR pkey_free (2) +called on them because it would have processor or memory performance +implications to perform the additional checks needed to disallow it. +Implementation of the necessary checks is left up to applications. +Applications may implement these checks by searching the +.IR /proc/[pid]/smaps +file for memory regions with the pkey assigned. +Further details can be found in +.BR proc (5). +.PP +Any application wanting to use protection keys needs to be able +to function without them. +They might be unavailable because the hardware that the +application runs on does not support them, the kernel code does +not contain support, the kernel support has been disabled, or +because the keys have all been allocated, perhaps by a library +the application is using. +It is recommended that applications wanting to use protection +keys should simply call +.BR pkey_alloc (2) +and test whether the call succeeds, +instead of attempting to detect support for the +feature in any other way. +.PP +Although unnecessary, hardware support for protection keys may be +enumerated with the +.I cpuid +instruction. +Details of how to do this can be found in the Intel Software +Developers Manual. +The kernel performs this enumeration and exposes the information in +.IR /proc/cpuinfo +under the "flags" field. +The string "pku" in this field indicates hardware support for protection +keys and the string "ospke" indicates that the kernel contains and has +enabled protection keys support. +.PP +Applications using threads and protection keys should be especially +careful. +Threads inherit the protection key rights of the parent at the time +of the +.BR clone (2), +system call. +Applications should either ensure that their own permissions are +appropriate for child threads at the time when +.BR clone (2) +is called, or ensure that each child thread can perform its +own initialization of protection key rights. +.\" +.SS Signal Handler Behavior +Each time a signal handler is invoked (including nested signals), the +thread is temporarily given a new, default set of protection key rights +that override the rights from the interrupted context. +This means that applications must re-establish their desired protection +key rights upon entering a signal handler if the desired rights differ +from the defaults. +The rights of any interrupted context are restored when the signal +handler returns. +.PP +This signal behavior is unusual and is due to the fact that the x86 PKRU +register (which stores protection key access rights) is managed with the +same hardware mechanism (XSAVE) that manages floating-point registers. +The signal behavior is the same as that of floating-point registers. +.\" +.SS Protection Keys system calls +The Linux kernel implements the following pkey-related system calls: +.BR pkey_mprotect (2), +.BR pkey_alloc (2), +and +.BR pkey_free (2). +.PP +The Linux pkey system calls are available only if the kernel was +configured and built with the +.BR CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS +option. +.SH EXAMPLE +.PP +The program below allocates a page of memory with read and write permissions. +It then writes some data to the memory and successfully reads it +back. +After that, it attempts to allocate a protection key and +disallows access to the page by using the WRPKRU instruction. +It then tries to access the page, +which we now expect to cause a fatal signal to the application. +.PP +.in +4n +.EX +.RB "$" " ./a.out" +buffer contains: 73 +about to read buffer again... +Segmentation fault (core dumped) +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include + +static inline void +wrpkru(unsigned int pkru) +{ + unsigned int eax = pkru; + unsigned int ecx = 0; + unsigned int edx = 0; + + asm volatile(".byte 0x0f,0x01,0xef\\n\\t" + : : "a" (eax), "c" (ecx), "d" (edx)); +} + +int +pkey_set(int pkey, unsigned long rights, unsigned long flags) +{ + unsigned int pkru = (rights << (2 * pkey)); + return wrpkru(pkru); +} + +int +pkey_mprotect(void *ptr, size_t size, unsigned long orig_prot, + unsigned long pkey) +{ + return syscall(SYS_pkey_mprotect, ptr, size, orig_prot, pkey); +} + +int +pkey_alloc(void) +{ + return syscall(SYS_pkey_alloc, 0, 0); +} + +int +pkey_free(unsigned long pkey) +{ + return syscall(SYS_pkey_free, pkey); +} + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +int +main(void) +{ + int status; + int pkey; + int *buffer; + + /* + *Allocate one page of memory + */ + buffer = mmap(NULL, getpagesize(), PROT_READ | PROT_WRITE, + MAP_ANONYMOUS | MAP_PRIVATE, \-1, 0); + if (buffer == MAP_FAILED) + errExit("mmap"); + + /* + * Put some random data into the page (still OK to touch) + */ + *buffer = __LINE__; + printf("buffer contains: %d\\n", *buffer); + + /* + * Allocate a protection key: + */ + pkey = pkey_alloc(); + if (pkey == \-1) + errExit("pkey_alloc"); + + /* + * Disable access to any memory with "pkey" set, + * even though there is none right now + */ + status = pkey_set(pkey, PKEY_DISABLE_ACCESS, 0); + if (status) + errExit("pkey_set"); + + /* + * Set the protection key on "buffer". + * Note that it is still read/write as far as mprotect() is + * concerned and the previous pkey_set() overrides it. + */ + status = pkey_mprotect(buffer, getpagesize(), + PROT_READ | PROT_WRITE, pkey); + if (status == -1) + errExit("pkey_mprotect"); + + printf("about to read buffer again...\\n"); + + /* + * This will crash, because we have disallowed access + */ + printf("buffer contains: %d\\n", *buffer); + + status = pkey_free(pkey); + if (status == -1) + errExit("pkey_free"); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR pkey_alloc (2), +.BR pkey_free (2), +.BR pkey_mprotect (2), +.BR sigaction (2) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/posixoptions.7 b/man7/posixoptions.7 new file mode 100644 index 0000000..35020ef --- /dev/null +++ b/man7/posixoptions.7 @@ -0,0 +1,800 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH POSIXOPTIONS 7 2007-12-21 "" "Linux Programmer's Manual" +.SH NAME +posixoptions \- optional parts of the POSIX standard +.SH DESCRIPTION +The POSIX standard (the information below is from POSIX.1-2001) +describes a set of behaviors and interfaces for a compliant system. +However, many interfaces are optional and there are feature test macros +to test the availability of interfaces at compile time, and functions +.BR sysconf (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR confstr (3) +to do this at run time. +From shell scripts one can use +.BR getconf (1). +For more detail, see +.BR sysconf (3). +.PP +We give the name of the POSIX abbreviation, the option, the name of the +.BR sysconf (3) +parameter used to inquire about the option, and possibly +a very short description. +Much more precise detail can be found in the POSIX standard itself, +versions of which can nowadays be accessed freely on the web. +.SS ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO +The following advisory functions are present: +.PP +.nf +.in +4n +.IR posix_fadvise (), +.IR posix_fallocate (), +.IR posix_memalign (), +.IR posix_madvise (). +.in +.fi +.SS AIO - _POSIX_ASYNCHRONOUS_IO - _SC_ASYNCHRONOUS_IO +The header +.I +is present. +The following functions are present: +.PP +.nf +.in +4n +.IR aio_cancel (), +.IR aio_error (), +.IR aio_fsync (), +.IR aio_read (), +.IR aio_return (), +.IR aio_suspend (), +.IR aio_write (), +.IR lio_listio (). +.in +.fi +.SS BAR - _POSIX_BARRIERS - _SC_BARRIERS +This option implies the +.B _POSIX_THREADS +and +.B _POSIX_THREAD_SAFE_FUNCTIONS +options. +The following functions are present: +.PP +.nf +.in +4n +.IR pthread_barrier_destroy (), +.IR pthread_barrier_init (), +.IR pthread_barrier_wait (), +.IR pthread_barrierattr_destroy (), +.IR pthread_barrierattr_init (). +.in +.fi +.\" .SS BE +.\" Batch environment. +.\" .SS CD +.\" C development. +.SS --- - POSIX_CHOWN_RESTRICTED +If this option is in effect (as it always is under POSIX.1-2001), +then only root may change the owner of a file, and nonroot can +set the group of a file only to one of the groups it belongs to. +This affects the functions +.IR chown (), +.IR fchown (). +.\" What about lchown() ? +.SS CS - _POSIX_CLOCK_SELECTION - _SC_CLOCK_SELECTION +This option implies the +.B _POSIX_TIMERS +option. +The following functions are present: +.PP +.nf +.in +4n +.IR pthread_condattr_getclock (), +.IR pthread_condattr_setclock (), +.IR clock_nanosleep (). +.in +.fi +.PP +If +.B CLOCK_REALTIME +is changed by the function +.IR clock_settime (), +then this affects all timers set for an absolute time. +.SS CPT - _POSIX_CPUTIME - _SC_CPUTIME +The clockID CLOCK_PROCESS_CPUTIME_ID is supported. +The initial value of this clock is 0 for each process. +This option implies the +.B _POSIX_TIMERS +option. +The function +.IR clock_getcpuclockid () +is present. +.\" .SS FD +.\" Fortran development +.\" .SS FR +.\" Fortran runtime +.SS --- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING +This option has been deleted. +Not in final XPG6. +.SS FSC - _POSIX_FSYNC - _SC_FSYNC +The function +.IR fsync () +is present. +.SS IP6 - _POSIX_IPV6 - _SC_IPV6 +Internet Protocol Version 6 is supported. +.SS --- - _POSIX_JOB_CONTROL - _SC_JOB_CONTROL +If this option is in effect (as it always is under POSIX.1-2001), +then the system implements POSIX-style job control, +and the following functions are present: +.PP +.nf +.in +4n +.IR setpgid (), +.IR tcdrain (), +.IR tcflush (), +.IR tcgetpgrp (), +.IR tcsendbreak (), +.IR tcsetattr (), +.IR tcsetpgrp (). +.in +.fi +.SS MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES +Shared memory is supported. +The include file +.I +is present. +The following functions are present: +.IR mmap (), +.IR msync (), +.IR munmap (). +.SS ML - _POSIX_MEMLOCK - _SC_MEMLOCK +Shared memory can be locked into core. +The functions +.IR mlockall (), +.IR munlockall () +are present. +.SS MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE +More precisely, ranges can be locked into core. +The functions +.IR mlock (), +.IR munlock () +are present. +.SS MPR - _POSIX_MEMORY_PROTECTION - _SC_MEMORY_PROTECTION +The function +.IR mprotect () +is present. +.SS MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING +The include file +.I +is present. +The following functions are present: +.PP +.nf +.in +4n +.IR mq_close (), +.IR mq_getattr (), +.IR mq_notify (), +.IR mq_open (), +.IR mq_receive (), +.IR mq_send (), +.IR mq_setattr (), +.IR mq_unlink (). +.in +.fi +.SS MON - _POSIX_MONOTONIC_CLOCK - _SC_MONOTONIC_CLOCK +.B CLOCK_MONOTONIC +is supported. +This option implies the +.B _POSIX_TIMERS +option. +Affected functions are +.PP +.nf +.in +4n +.IR aio_suspend (), +.IR clock_getres (), +.IR clock_gettime (), +.IR clock_settime (), +.IR timer_create (). +.in +.fi +.SS --- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS +This option has been deleted. +Not in final XPG6. +.\" .SS MX +.\" IEC 60559 Floating-Point Option. +.SS --- - _POSIX_NO_TRUNC +If this option is in effect (as it always is under POSIX.1-2001) +then pathname components longer than +.B NAME_MAX +are not truncated, +but give an error. +This property may be dependent on the path prefix of the component. +.SS PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO +This option says that one can specify priorities for asynchronous I/O. +This affects the functions +.PP +.nf +.in +4n +.IR aio_read (), +.IR aio_write (). +.in +.fi +.SS PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING +The include file +.I +is present. +The following functions are present: +.PP +.nf +.in +4n +.IR sched_get_priority_max (), +.IR sched_get_priority_min (), +.IR sched_getparam (), +.IR sched_getscheduler (), +.IR sched_rr_get_interval (), +.IR sched_setparam (), +.IR sched_setscheduler (), +.IR sched_yield (). +.in +.fi +If also +.B _POSIX_SPAWN +is in effect, then the following functions are present: +.PP +.nf +.in +4n +.IR posix_spawnattr_getschedparam (), +.IR posix_spawnattr_getschedpolicy (), +.IR posix_spawnattr_setschedparam (), +.IR posix_spawnattr_setschedpolicy (). +.in +.fi +.SS RS - _POSIX_RAW_SOCKETS +Raw sockets are supported. +Affected functions are +.IR getsockopt (), +.IR setsockopt (). +.SS --- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS +This option implies the +.B _POSIX_THREADS +option. +Conversely, +under POSIX.1-2001 the +.B _POSIX_THREADS +option implies this option. +.PP +The following functions are present: +.in +4n +.nf +.IR pthread_rwlock_destroy (), +.IR pthread_rwlock_init (), +.IR pthread_rwlock_rdlock (), +.IR pthread_rwlock_tryrdlock (), +.IR pthread_rwlock_trywrlock (), +.IR pthread_rwlock_unlock (), +.IR pthread_rwlock_wrlock (), +.IR pthread_rwlockattr_destroy (), +.IR pthread_rwlockattr_init (). +.in +.fi +.SS RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS +Realtime signals are supported. +The following functions are present: +.PP +.nf +.in +4n +.IR sigqueue (), +.IR sigtimedwait (), +.IR sigwaitinfo (). +.in +.fi +.SS --- - _POSIX_REGEXP - _SC_REGEXP +If this option is in effect (as it always is under POSIX.1-2001) +then POSIX regular expressions are supported +and the following functions are present: +.PP +.nf +.in +4n +.IR regcomp (), +.IR regerror (), +.IR regexec (), +.IR regfree (). +.in +.fi +.SS --- - _POSIX_SAVED_IDS - _SC_SAVED_IDS +If this option is in effect (as it always is under POSIX.1-2001), +then a process has a saved set-user-ID and a saved set-group-ID. +Affected functions are +.PP +.nf +.in +4n +.IR exec (), +.IR kill (), +.IR seteuid (), +.IR setegid (), +.IR setgid (), +.IR setuid (). +.in +.fi +.\" .SS SD +.\" Software development +.SS SEM - _POSIX_SEMAPHORES - _SC_SEMAPHORES +The include file +.I +is present. +The following functions are present: +.PP +.nf +.in +4n +.IR sem_close (), +.IR sem_destroy (), +.IR sem_getvalue (), +.IR sem_init (), +.IR sem_open (), +.IR sem_post (), +.IR sem_trywait (), +.IR sem_unlink (), +.IR sem_wait (). +.in +.fi +.SS SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS +The following functions are present: +.PP +.nf +.in +4n +.IR mmap (), +.IR munmap (), +.IR shm_open (), +.IR shm_unlink (). +.in +.fi +.SS --- - _POSIX_SHELL - _SC_SHELL +If this option is in effect (as it always is under POSIX.1-2001), +the function +.IR system () +is present. +.SS SPN - _POSIX_SPAWN - _SC_SPAWN +This option describes support for process creation in a context where +it is difficult or impossible to use +.IR fork (), +for example, because no MMU is present. +If +.B _POSIX_SPAWN +is in effect, then the include file +.I +and the following functions are present: +.PP +.nf +.in +4n +.IR posix_spawn (), +.IR posix_spawn_file_actions_addclose (), +.IR posix_spawn_file_actions_adddup2 (), +.IR posix_spawn_file_actions_addopen (), +.IR posix_spawn_file_actions_destroy (), +.IR posix_spawn_file_actions_init (), +.IR posix_spawnattr_destroy (), +.IR posix_spawnattr_getsigdefault (), +.IR posix_spawnattr_getflags (), +.IR posix_spawnattr_getpgroup (), +.IR posix_spawnattr_getsigmask (), +.IR posix_spawnattr_init (), +.IR posix_spawnattr_setsigdefault (), +.IR posix_spawnattr_setflags (), +.IR posix_spawnattr_setpgroup (), +.IR posix_spawnattr_setsigmask (), +.IR posix_spawnp (). +.in +.fi +If also +.B _POSIX_PRIORITY_SCHEDULING +is in effect, then +the following functions are present: +.PP +.nf +.in +4n +.IR posix_spawnattr_getschedparam (), +.IR posix_spawnattr_getschedpolicy (), +.IR posix_spawnattr_setschedparam (), +.IR posix_spawnattr_setschedpolicy (). +.in +.fi +.SS SPI - _POSIX_SPIN_LOCKS - _SC_SPIN_LOCKS +This option implies the +.B _POSIX_THREADS +and +.B _POSIX_THREAD_SAFE_FUNCTIONS +options. +The following functions are present: +.PP +.nf +.in +4n +.IR pthread_spin_destroy (), +.IR pthread_spin_init (), +.IR pthread_spin_lock (), +.IR pthread_spin_trylock (), +.IR pthread_spin_unlock (). +.in -4n +.fi +.SS SS - _POSIX_SPORADIC_SERVER - _SC_SPORADIC_SERVER +The scheduling policy +.B SCHED_SPORADIC +is supported. +This option implies the +.B _POSIX_PRIORITY_SCHEDULING +option. +Affected functions are +.PP +.nf +.in +4n +.IR sched_setparam (), +.IR sched_setscheduler (). +.in +.fi +.SS SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO +Affected functions are +.IR open (), +.IR msync (), +.IR fsync (), +.IR fdatasync (). +.SS TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR +Affected functions are +.PP +.nf +.in +4n +.IR pthread_attr_getstack (), +.IR pthread_attr_getstackaddr (), +.IR pthread_attr_setstack (), +.IR pthread_attr_setstackaddr (). +.in +.fi +.SS TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE +Affected functions are +.PP +.nf +.in +4n +.IR pthread_attr_getstack (), +.IR pthread_attr_getstacksize (), +.IR pthread_attr_setstack (), +.IR pthread_attr_setstacksize (). +.in +.fi +.SS TCT - _POSIX_THREAD_CPUTIME - _SC_THREAD_CPUTIME +The clockID CLOCK_THREAD_CPUTIME_ID is supported. +This option implies the +.B _POSIX_TIMERS +option. +Affected functions are +.PP +.nf +.in +4n +.IR pthread_getcpuclockid (), +.IR clock_getres (), +.IR clock_gettime (), +.IR clock_settime (), +.IR timer_create (). +.in +.fi +.SS TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT +Affected functions are +.PP +.nf +.in +4n +.IR pthread_mutexattr_getprotocol (), +.IR pthread_mutexattr_setprotocol (). +.in +.fi +.SS TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT +Affected functions are +.PP +.nf +.in +4n +.IR pthread_mutex_getprioceiling (), +.IR pthread_mutex_setprioceiling (), +.IR pthread_mutexattr_getprioceiling (), +.IR pthread_mutexattr_getprotocol (), +.IR pthread_mutexattr_setprioceiling (), +.IR pthread_mutexattr_setprotocol (). +.in +.fi +.SS TPS - _POSIX_THREAD_PRIORITY_SCHEDULING - _SC_THREAD_PRIORITY_SCHEDULING +If this option is in effect, the different threads inside a process +can run with different priorities and/or different schedulers. +Affected functions are +.PP +.nf +.in +4n +.IR pthread_attr_getinheritsched (), +.IR pthread_attr_getschedpolicy (), +.IR pthread_attr_getscope (), +.IR pthread_attr_setinheritsched (), +.IR pthread_attr_setschedpolicy (), +.IR pthread_attr_setscope (), +.IR pthread_getschedparam (), +.IR pthread_setschedparam (), +.IR pthread_setschedprio (). +.in +.fi +.SS TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED +Affected functions are +.PP +.nf +.in +4n +.IR pthread_barrierattr_getpshared (), +.IR pthread_barrierattr_setpshared (), +.IR pthread_condattr_getpshared (), +.IR pthread_condattr_setpshared (), +.IR pthread_mutexattr_getpshared (), +.IR pthread_mutexattr_setpshared (), +.IR pthread_rwlockattr_getpshared (), +.IR pthread_rwlockattr_setpshared (). +.in +.fi +.SS TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS +Affected functions are +.PP +.nf +.in +4n +.IR readdir_r (), +.IR getgrgid_r (), +.IR getgrnam_r (), +.IR getpwnam_r (), +.IR getpwuid_r (), +.IR flockfile (), +.IR ftrylockfile (), +.IR funlockfile (), +.IR getc_unlocked (), +.IR getchar_unlocked (), +.IR putc_unlocked (), +.IR putchar_unlocked (), +.IR rand_r (), +.IR strerror_r (), +.IR strtok_r (), +.IR asctime_r (), +.IR ctime_r (), +.IR gmtime_r (), +.IR localtime_r (). +.in +.fi +.SS TSP - _POSIX_THREAD_SPORADIC_SERVER - _SC_THREAD_SPORADIC_SERVER +This option implies the +.B _POSIX_THREAD_PRIORITY_SCHEDULING +option. +Affected functions are +.PP +.nf +.in +4n +.IR sched_getparam (), +.IR sched_setparam (), +.IR sched_setscheduler (). +.in +.fi +.SS THR - _POSIX_THREADS - _SC_THREADS +Basic support for POSIX threads is available. +The following functions are present: +.PP +.nf +.in +4n +.IR pthread_atfork (), +.IR pthread_attr_destroy (), +.IR pthread_attr_getdetachstate (), +.IR pthread_attr_getschedparam (), +.IR pthread_attr_init (), +.IR pthread_attr_setdetachstate (), +.IR pthread_attr_setschedparam (), +.IR pthread_cancel (), +.IR pthread_cleanup_push (), +.IR pthread_cleanup_pop (), +.IR pthread_cond_broadcast (), +.IR pthread_cond_destroy (), +.IR pthread_cond_init (), +.IR pthread_cond_signal (), +.IR pthread_cond_timedwait (), +.IR pthread_cond_wait (), +.IR pthread_condattr_destroy (), +.IR pthread_condattr_init (), +.IR pthread_create (), +.IR pthread_detach (), +.IR pthread_equal (), +.IR pthread_exit (), +.IR pthread_getspecific (), +.IR pthread_join (), +.IR pthread_key_create (), +.IR pthread_key_delete (), +.IR pthread_mutex_destroy (), +.IR pthread_mutex_init (), +.IR pthread_mutex_lock (), +.IR pthread_mutex_trylock (), +.IR pthread_mutex_unlock (), +.IR pthread_mutexattr_destroy (), +.IR pthread_mutexattr_init (), +.IR pthread_once (), +.IR pthread_rwlock_destroy (), +.IR pthread_rwlock_init (), +.IR pthread_rwlock_rdlock (), +.IR pthread_rwlock_tryrdlock (), +.IR pthread_rwlock_trywrlock (), +.IR pthread_rwlock_unlock (), +.IR pthread_rwlock_wrlock (), +.IR pthread_rwlockattr_destroy (), +.IR pthread_rwlockattr_init (), +.IR pthread_self (), +.IR pthread_setcancelstate (), +.IR pthread_setcanceltype (), +.IR pthread_setspecific (), +.IR pthread_testcancel (). +.in +.fi +.SS TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS +The following functions are present: +.PP +.nf +.in +4n +.IR mq_timedreceive (), +.IR mq_timedsend (), +.IR pthread_mutex_timedlock (), +.IR pthread_rwlock_timedrdlock (), +.IR pthread_rwlock_timedwrlock (), +.IR sem_timedwait (), +.IR posix_trace_timedgetnext_event (). +.in +.fi +.SS TMR - _POSIX_TIMERS - _SC_TIMERS +The following functions are present: +.PP +.nf +.in +4n +.IR clock_getres (), +.IR clock_gettime (), +.IR clock_settime (), +.IR nanosleep (), +.IR timer_create (), +.IR timer_delete (), +.IR timer_gettime (), +.IR timer_getoverrun (), +.IR timer_settime (). +.in +.fi +.SS TRC - _POSIX_TRACE - _SC_TRACE +POSIX tracing is available. +The following functions are present: +.PP +.nf +.in +4n +.IR posix_trace_attr_destroy (), +.IR posix_trace_attr_getclockres (), +.IR posix_trace_attr_getcreatetime (), +.IR posix_trace_attr_getgenversion (), +.IR posix_trace_attr_getmaxdatasize (), +.IR posix_trace_attr_getmaxsystemeventsize (), +.IR posix_trace_attr_getmaxusereventsize (), +.IR posix_trace_attr_getname (), +.IR posix_trace_attr_getstreamfullpolicy (), +.IR posix_trace_attr_getstreamsize (), +.IR posix_trace_attr_init (), +.IR posix_trace_attr_setmaxdatasize (), +.IR posix_trace_attr_setname (), +.IR posix_trace_attr_setstreamsize (), +.IR posix_trace_attr_setstreamfullpolicy (), +.IR posix_trace_clear (), +.IR posix_trace_create (), +.IR posix_trace_event (), +.IR posix_trace_eventid_equal (), +.IR posix_trace_eventid_get_name (), +.IR posix_trace_eventid_open (), +.IR posix_trace_eventtypelist_getnext_id (), +.IR posix_trace_eventtypelist_rewind (), +.IR posix_trace_flush (), +.IR posix_trace_get_attr (), +.IR posix_trace_get_status (), +.IR posix_trace_getnext_event (), +.IR posix_trace_shutdown (), +.IR posix_trace_start (), +.IR posix_trace_stop (), +.IR posix_trace_trygetnext_event (). +.in +.fi +.SS TEF - _POSIX_TRACE_EVENT_FILTER - _SC_TRACE_EVENT_FILTER +This option implies the +.B _POSIX_TRACE +option. +The following functions are present: +.PP +.nf +.in +4n +.IR posix_trace_eventset_add (), +.IR posix_trace_eventset_del (), +.IR posix_trace_eventset_empty (), +.IR posix_trace_eventset_fill (), +.IR posix_trace_eventset_ismember (), +.IR posix_trace_get_filter (), +.IR posix_trace_set_filter (), +.IR posix_trace_trid_eventid_open (). +.in +.fi +.SS TRI - _POSIX_TRACE_INHERIT - _SC_TRACE_INHERIT +Tracing children of the traced process is supported. +This option implies the +.B _POSIX_TRACE +option. +The following functions are present: +.PP +.nf +.in +4n +.IR posix_trace_attr_getinherited (), +.IR posix_trace_attr_setinherited (). +.in +.fi +.SS TRL - _POSIX_TRACE_LOG - _SC_TRACE_LOG +This option implies the +.B _POSIX_TRACE +option. +The following functions are present: +.PP +.nf +.in +4n +.IR posix_trace_attr_getlogfullpolicy (), +.IR posix_trace_attr_getlogsize (), +.IR posix_trace_attr_setlogfullpolicy (), +.IR posix_trace_attr_setlogsize (), +.IR posix_trace_close (), +.IR posix_trace_create_withlog (), +.IR posix_trace_open (), +.IR posix_trace_rewind (). +.in +.fi +.SS TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT +The following functions are present: +.PP +.nf +.in +4n +.IR posix_mem_offset (), +.IR posix_typed_mem_get_info (), +.IR posix_typed_mem_open (). +.in +.fi +.SS --- - _POSIX_VDISABLE +Always present (probably 0). +Value to set a changeable special control +character to indicate that it is disabled. +.SH XOPEN EXTENSIONS +.BR _XOPEN_CRYPT , +.BR _XOPEN_LEGACY , +.BR _XOPEN_REALTIME , +.BR _XOPEN_REALTIME_THREADS , +.BR _XOPEN_UNIX . +.\" To be described. +.SH SEE ALSO +.BR sysconf (3), +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/process-keyring.7 b/man7/process-keyring.7 new file mode 100644 index 0000000..1264f68 --- /dev/null +++ b/man7/process-keyring.7 @@ -0,0 +1,70 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH "PROCESS-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual" +.SH NAME +process-keyring \- per-process shared keyring +.SH DESCRIPTION +The process keyring is a keyring used to anchor keys on behalf of a process. +It is created only when a process requests it. +The process keyring has the name (description) +.IR _pid . +.PP +A special serial number value, +.BR KEY_SPEC_PROCESS_KEYRING , +is defined that can be used in lieu of the actual serial number of +the calling process's process keyring. +.PP +From the +.BR keyctl (1) +utility, '\fB@p\fP' can be used instead of a numeric key ID in +much the same way, but since +.BR keyctl (1) +is a program run after forking, this is of no utility. +.PP +A thread created using the +.BR clone (2) +.B CLONE_THREAD +flag has the same process keyring as the caller of +.BR clone (2). +When a new process is created using +.BR fork () +it initially has no process keyring. +A process's process keyring is cleared on +.BR execve (2). +The process keyring is destroyed when the last +thread that refers to it terminates. +.PP +If a process doesn't have a process keyring when it is accessed, +then the process keyring will be created if the keyring is to be modified; +otherwise, the error +.B ENOKEY +results. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/pthreads.7 b/man7/pthreads.7 new file mode 100644 index 0000000..2fef79f --- /dev/null +++ b/man7/pthreads.7 @@ -0,0 +1,949 @@ +'\" t +.\" Copyright (c) 2005 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTHREADS 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pthreads \- POSIX threads +.SH DESCRIPTION +POSIX.1 specifies a set of interfaces (functions, header files) for +threaded programming commonly known as POSIX threads, or Pthreads. +A single process can contain multiple threads, +all of which are executing the same program. +These threads share the same global memory (data and heap segments), +but each thread has its own stack (automatic variables). +.PP +POSIX.1 also requires that threads share a range of other attributes +(i.e., these attributes are process-wide rather than per-thread): +.IP \- 3 +process ID +.IP \- 3 +parent process ID +.IP \- 3 +process group ID and session ID +.IP \- 3 +controlling terminal +.IP \- 3 +user and group IDs +.IP \- 3 +open file descriptors +.IP \- 3 +record locks (see +.BR fcntl (2)) +.IP \- 3 +signal dispositions +.IP \- 3 +file mode creation mask +.RB ( umask (2)) +.IP \- 3 +current directory +.RB ( chdir (2)) +and +root directory +.RB ( chroot (2)) +.IP \- 3 +interval timers +.RB ( setitimer (2)) +and POSIX timers +.RB ( timer_create (2)) +.IP \- 3 +nice value +.RB ( setpriority (2)) +.IP \- 3 +resource limits +.RB ( setrlimit (2)) +.IP \- 3 +measurements of the consumption of CPU time +.RB ( times (2)) +and resources +.RB ( getrusage (2)) +.PP +As well as the stack, POSIX.1 specifies that various other +attributes are distinct for each thread, including: +.IP \- 3 +thread ID (the +.I pthread_t +data type) +.IP \- 3 +signal mask +.RB ( pthread_sigmask (3)) +.IP \- 3 +the +.I errno +variable +.IP \- 3 +alternate signal stack +.RB ( sigaltstack (2)) +.IP \- 3 +real-time scheduling policy and priority +.RB ( sched (7)) +.PP +The following Linux-specific features are also per-thread: +.IP \- 3 +capabilities (see +.BR capabilities (7)) +.IP \- 3 +CPU affinity +.RB ( sched_setaffinity (2)) +.SS Pthreads function return values +Most pthreads functions return 0 on success, and an error number on failure. +Note that the pthreads functions do not set +.IR errno . +For each of the pthreads functions that can return an error, +POSIX.1-2001 specifies that the function can never fail with the error +.BR EINTR . +.SS Thread IDs +Each of the threads in a process has a unique thread identifier +(stored in the type +.IR pthread_t ). +This identifier is returned to the caller of +.BR pthread_create (3), +and a thread can obtain its own thread identifier using +.BR pthread_self (3). +.PP +Thread IDs are guaranteed to be unique only within a process. +(In all pthreads functions that accept a thread ID as an argument, +that ID by definition refers to a thread in +the same process as the caller.) +.PP +The system may reuse a thread ID after a terminated thread has been joined, +or a detached thread has terminated. +POSIX says: "If an application attempts to use a thread ID whose +lifetime has ended, the behavior is undefined." +.SS Thread-safe functions +A thread-safe function is one that can be safely +(i.e., it will deliver the same results regardless of whether it is) +called from multiple threads at the same time. +.PP +POSIX.1-2001 and POSIX.1-2008 require that all functions specified +in the standard shall be thread-safe, +except for the following functions: +.PP +.in +4n +.EX +asctime() +basename() +catgets() +crypt() +ctermid() if passed a non-NULL argument +ctime() +dbm_clearerr() +dbm_close() +dbm_delete() +dbm_error() +dbm_fetch() +dbm_firstkey() +dbm_nextkey() +dbm_open() +dbm_store() +dirname() +dlerror() +drand48() +ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +encrypt() +endgrent() +endpwent() +endutxent() +fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +ftw() +gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +getc_unlocked() +getchar_unlocked() +getdate() +getenv() +getgrent() +getgrgid() +getgrnam() +gethostbyaddr() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +gethostbyname() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +gethostent() +getlogin() +getnetbyaddr() +getnetbyname() +getnetent() +getopt() +getprotobyname() +getprotobynumber() +getprotoent() +getpwent() +getpwnam() +getpwuid() +getservbyname() +getservbyport() +getservent() +getutxent() +getutxid() +getutxline() +gmtime() +hcreate() +hdestroy() +hsearch() +inet_ntoa() +l64a() +lgamma() +lgammaf() +lgammal() +localeconv() +localtime() +lrand48() +mrand48() +nftw() +nl_langinfo() +ptsname() +putc_unlocked() +putchar_unlocked() +putenv() +pututxline() +rand() +readdir() +setenv() +setgrent() +setkey() +setpwent() +setutxent() +strerror() +strsignal() [Added in POSIX.1-2008] +strtok() +system() [Added in POSIX.1-2008] +tmpnam() if passed a non-NULL argument +ttyname() +unsetenv() +wcrtomb() if its final argument is NULL +wcsrtombs() if its final argument is NULL +wcstombs() +wctomb() +.EE +.in +.SS Async-cancel-safe functions +An async-cancel-safe function is one that can be safely called +in an application where asynchronous cancelability is enabled (see +.BR pthread_setcancelstate (3)). +.PP +Only the following functions are required to be async-cancel-safe by +POSIX.1-2001 and POSIX.1-2008: +.PP +.in +4n +.EX +pthread_cancel() +pthread_setcancelstate() +pthread_setcanceltype() +.EE +.in +.SS Cancellation points +POSIX.1 specifies that certain functions must, +and certain other functions may, be cancellation points. +If a thread is cancelable, its cancelability type is deferred, +and a cancellation request is pending for the thread, +then the thread is canceled when it calls a function +that is a cancellation point. +.PP +The following functions are required to be cancellation points by +POSIX.1-2001 and/or POSIX.1-2008: +.PP +.\" FIXME +.\" Document the list of all functions that are cancellation points in glibc +.in +4n +.EX +accept() +aio_suspend() +clock_nanosleep() +close() +connect() +creat() +fcntl() F_SETLKW +fdatasync() +fsync() +getmsg() +getpmsg() +lockf() F_LOCK +mq_receive() +mq_send() +mq_timedreceive() +mq_timedsend() +msgrcv() +msgsnd() +msync() +nanosleep() +open() +openat() [Added in POSIX.1-2008] +pause() +poll() +pread() +pselect() +pthread_cond_timedwait() +pthread_cond_wait() +pthread_join() +pthread_testcancel() +putmsg() +putpmsg() +pwrite() +read() +readv() +recv() +recvfrom() +recvmsg() +select() +sem_timedwait() +sem_wait() +send() +sendmsg() +sendto() +sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)] +sigsuspend() +sigtimedwait() +sigwait() +sigwaitinfo() +sleep() +system() +tcdrain() +usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +wait() +waitid() +waitpid() +write() +writev() +.EE +.in +.PP +The following functions may be cancellation points according to +POSIX.1-2001 and/or POSIX.1-2008: +.PP +.in +4n +.EX +access() +asctime() +asctime_r() +catclose() +catgets() +catopen() +chmod() [Added in POSIX.1-2008] +chown() [Added in POSIX.1-2008] +closedir() +closelog() +ctermid() +ctime() +ctime_r() +dbm_close() +dbm_delete() +dbm_fetch() +dbm_nextkey() +dbm_open() +dbm_store() +dlclose() +dlopen() +dprintf() [Added in POSIX.1-2008] +endgrent() +endhostent() +endnetent() +endprotoent() +endpwent() +endservent() +endutxent() +faccessat() [Added in POSIX.1-2008] +fchmod() [Added in POSIX.1-2008] +fchmodat() [Added in POSIX.1-2008] +fchown() [Added in POSIX.1-2008] +fchownat() [Added in POSIX.1-2008] +fclose() +fcntl() (for any value of cmd argument) +fflush() +fgetc() +fgetpos() +fgets() +fgetwc() +fgetws() +fmtmsg() +fopen() +fpathconf() +fprintf() +fputc() +fputs() +fputwc() +fputws() +fread() +freopen() +fscanf() +fseek() +fseeko() +fsetpos() +fstat() +fstatat() [Added in POSIX.1-2008] +ftell() +ftello() +ftw() +futimens() [Added in POSIX.1-2008] +fwprintf() +fwrite() +fwscanf() +getaddrinfo() +getc() +getc_unlocked() +getchar() +getchar_unlocked() +getcwd() +getdate() +getdelim() [Added in POSIX.1-2008] +getgrent() +getgrgid() +getgrgid_r() +getgrnam() +getgrnam_r() +gethostbyaddr() [SUSv3 only (function removed in POSIX.1-2008)] +gethostbyname() [SUSv3 only (function removed in POSIX.1-2008)] +gethostent() +gethostid() +gethostname() +getline() [Added in POSIX.1-2008] +getlogin() +getlogin_r() +getnameinfo() +getnetbyaddr() +getnetbyname() +getnetent() +getopt() (if opterr is nonzero) +getprotobyname() +getprotobynumber() +getprotoent() +getpwent() +getpwnam() +getpwnam_r() +getpwuid() +getpwuid_r() +gets() +getservbyname() +getservbyport() +getservent() +getutxent() +getutxid() +getutxline() +getwc() +getwchar() +getwd() [SUSv3 only (function removed in POSIX.1-2008)] +glob() +iconv_close() +iconv_open() +ioctl() +link() +linkat() [Added in POSIX.1-2008] +lio_listio() [Added in POSIX.1-2008] +localtime() +localtime_r() +lockf() [Added in POSIX.1-2008] +lseek() +lstat() +mkdir() [Added in POSIX.1-2008] +mkdirat() [Added in POSIX.1-2008] +mkdtemp() [Added in POSIX.1-2008] +mkfifo() [Added in POSIX.1-2008] +mkfifoat() [Added in POSIX.1-2008] +mknod() [Added in POSIX.1-2008] +mknodat() [Added in POSIX.1-2008] +mkstemp() +mktime() +nftw() +opendir() +openlog() +pathconf() +pclose() +perror() +popen() +posix_fadvise() +posix_fallocate() +posix_madvise() +posix_openpt() +posix_spawn() +posix_spawnp() +posix_trace_clear() +posix_trace_close() +posix_trace_create() +posix_trace_create_withlog() +posix_trace_eventtypelist_getnext_id() +posix_trace_eventtypelist_rewind() +posix_trace_flush() +posix_trace_get_attr() +posix_trace_get_filter() +posix_trace_get_status() +posix_trace_getnext_event() +posix_trace_open() +posix_trace_rewind() +posix_trace_set_filter() +posix_trace_shutdown() +posix_trace_timedgetnext_event() +posix_typed_mem_open() +printf() +psiginfo() [Added in POSIX.1-2008] +psignal() [Added in POSIX.1-2008] +pthread_rwlock_rdlock() +pthread_rwlock_timedrdlock() +pthread_rwlock_timedwrlock() +pthread_rwlock_wrlock() +putc() +putc_unlocked() +putchar() +putchar_unlocked() +puts() +pututxline() +putwc() +putwchar() +readdir() +readdir_r() +readlink() [Added in POSIX.1-2008] +readlinkat() [Added in POSIX.1-2008] +remove() +rename() +renameat() [Added in POSIX.1-2008] +rewind() +rewinddir() +scandir() [Added in POSIX.1-2008] +scanf() +seekdir() +semop() +setgrent() +sethostent() +setnetent() +setprotoent() +setpwent() +setservent() +setutxent() +sigpause() [Added in POSIX.1-2008] +stat() +strerror() +strerror_r() +strftime() +symlink() +symlinkat() [Added in POSIX.1-2008] +sync() +syslog() +tmpfile() +tmpnam() +ttyname() +ttyname_r() +tzset() +ungetc() +ungetwc() +unlink() +unlinkat() [Added in POSIX.1-2008] +utime() [Added in POSIX.1-2008] +utimensat() [Added in POSIX.1-2008] +utimes() [Added in POSIX.1-2008] +vdprintf() [Added in POSIX.1-2008] +vfprintf() +vfwprintf() +vprintf() +vwprintf() +wcsftime() +wordexp() +wprintf() +wscanf() +.EE +.in +.PP +An implementation may also mark other functions +not specified in the standard as cancellation points. +In particular, an implementation is likely to mark +any nonstandard function that may block as a cancellation point. +(This includes most functions that can touch files.) +.\" So, scanning "cancellation point" comments in the glibc 2.8 header +.\" files, it looks as though at least the following nonstandard +.\" functions are cancellation points: +.\" endnetgrent +.\" endspent +.\" epoll_pwait +.\" epoll_wait +.\" fcloseall +.\" fdopendir +.\" fflush_unlocked +.\" fgetc_unlocked +.\" fgetgrent +.\" fgetgrent_r +.\" fgetpwent +.\" fgetpwent_r +.\" fgets_unlocked +.\" fgetspent +.\" fgetspent_r +.\" fgetwc_unlocked +.\" fgetws_unlocked +.\" fputc_unlocked +.\" fputs_unlocked +.\" fputwc_unlocked +.\" fputws_unlocked +.\" fread_unlocked +.\" fwrite_unlocked +.\" gai_suspend +.\" getaddrinfo_a +.\" getdate_r +.\" getgrent_r +.\" getgrouplist +.\" gethostbyaddr_r +.\" gethostbyname2 +.\" gethostbyname2_r +.\" gethostbyname_r +.\" gethostent_r +.\" getnetbyaddr_r +.\" getnetbyname_r +.\" getnetent_r +.\" getnetgrent +.\" getnetgrent_r +.\" getprotobyname_r +.\" getprotobynumber_r +.\" getprotoent_r +.\" getpw +.\" getpwent_r +.\" getservbyname_r +.\" getservbyport_r +.\" getservent_r +.\" getspent +.\" getspent_r +.\" getspnam +.\" getspnam_r +.\" getutmp +.\" getutmpx +.\" getw +.\" getwc_unlocked +.\" getwchar_unlocked +.\" initgroups +.\" innetgr +.\" mkostemp +.\" mkostemp64 +.\" mkstemp64 +.\" ppoll +.\" pthread_timedjoin_np +.\" putgrent +.\" putpwent +.\" putspent +.\" putw +.\" putwc_unlocked +.\" putwchar_unlocked +.\" rcmd +.\" rcmd_af +.\" rexec +.\" rexec_af +.\" rresvport +.\" rresvport_af +.\" ruserok +.\" ruserok_af +.\" setnetgrent +.\" setspent +.\" sgetspent +.\" sgetspent_r +.\" updwtmpx +.\" utmpxname +.\" vfscanf +.\" vfwscanf +.\" vscanf +.\" vsyslog +.\" vwscanf +.SS Compiling on Linux +On Linux, programs that use the Pthreads API should be compiled using +.IR "cc \-pthread" . +.SS Linux implementations of POSIX threads +Over time, two threading implementations have been provided by +the GNU C library on Linux: +.TP +.B LinuxThreads +This is the original Pthreads implementation. +Since glibc 2.4, this implementation is no longer supported. +.TP +.BR NPTL " (Native POSIX Threads Library)" +This is the modern Pthreads implementation. +By comparison with LinuxThreads, NPTL provides closer conformance to +the requirements of the POSIX.1 specification and better performance +when creating large numbers of threads. +NPTL is available since glibc 2.3.2, +and requires features that are present in the Linux 2.6 kernel. +.PP +Both of these are so-called 1:1 implementations, meaning that each +thread maps to a kernel scheduling entity. +Both threading implementations employ the Linux +.BR clone (2) +system call. +In NPTL, thread synchronization primitives (mutexes, +thread joining, and so on) are implemented using the Linux +.BR futex (2) +system call. +.SS LinuxThreads +The notable features of this implementation are the following: +.IP \- 3 +In addition to the main (initial) thread, +and the threads that the program creates using +.BR pthread_create (3), +the implementation creates a "manager" thread. +This thread handles thread creation and termination. +(Problems can result if this thread is inadvertently killed.) +.IP \- 3 +Signals are used internally by the implementation. +On Linux 2.2 and later, the first three real-time signals are used +(see also +.BR signal (7)). +On older Linux kernels, +.B SIGUSR1 +and +.B SIGUSR2 +are used. +Applications must avoid the use of whichever set of signals is +employed by the implementation. +.IP \- 3 +Threads do not share process IDs. +(In effect, LinuxThreads threads are implemented as processes which share +more information than usual, but which do not share a common process ID.) +LinuxThreads threads (including the manager thread) +are visible as separate processes using +.BR ps (1). +.PP +The LinuxThreads implementation deviates from the POSIX.1 +specification in a number of ways, including the following: +.IP \- 3 +Calls to +.BR getpid (2) +return a different value in each thread. +.IP \- 3 +Calls to +.BR getppid (2) +in threads other than the main thread return the process ID of the +manager thread; instead +.BR getppid (2) +in these threads should return the same value as +.BR getppid (2) +in the main thread. +.IP \- 3 +When one thread creates a new child process using +.BR fork (2), +any thread should be able to +.BR wait (2) +on the child. +However, the implementation allows only the thread that +created the child to +.BR wait (2) +on it. +.IP \- 3 +When a thread calls +.BR execve (2), +all other threads are terminated (as required by POSIX.1). +However, the resulting process has the same PID as the thread that called +.BR execve (2): +it should have the same PID as the main thread. +.IP \- 3 +Threads do not share user and group IDs. +This can cause complications with set-user-ID programs and +can cause failures in Pthreads functions if an application +changes its credentials using +.BR seteuid (2) +or similar. +.IP \- 3 +Threads do not share a common session ID and process group ID. +.IP \- 3 +Threads do not share record locks created using +.BR fcntl (2). +.IP \- 3 +The information returned by +.BR times (2) +and +.BR getrusage (2) +is per-thread rather than process-wide. +.IP \- 3 +Threads do not share semaphore undo values (see +.BR semop (2)). +.IP \- 3 +Threads do not share interval timers. +.IP \- 3 +Threads do not share a common nice value. +.IP \- 3 +POSIX.1 distinguishes the notions of signals that are directed +to the process as a whole and signals that are directed to individual +threads. +According to POSIX.1, a process-directed signal (sent using +.BR kill (2), +for example) should be handled by a single, +arbitrarily selected thread within the process. +LinuxThreads does not support the notion of process-directed signals: +signals may be sent only to specific threads. +.IP \- 3 +Threads have distinct alternate signal stack settings. +However, a new thread's alternate signal stack settings +are copied from the thread that created it, so that +the threads initially share an alternate signal stack. +(A new thread should start with no alternate signal stack defined. +If two threads handle signals on their shared alternate signal +stack at the same time, unpredictable program failures are +likely to occur.) +.SS NPTL +With NPTL, all of the threads in a process are placed +in the same thread group; +all members of a thread group share the same PID. +NPTL does not employ a manager thread. +.PP +NPTL makes internal use of the first two real-time signals; +these signals cannot be used in applications. +See +.BR nptl (7) +for further details. +.PP +NPTL still has at least one nonconformance with POSIX.1: +.IP \- 3 +Threads do not share a common nice value. +.\" FIXME . bug report filed for NPTL nice nonconformance +.\" http://bugzilla.kernel.org/show_bug.cgi?id=6258 +.\" Sep 08: there is a patch by Denys Vlasenko to address this +.\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension" +.\" Monitor this to see if it makes it into mainline. +.PP +Some NPTL nonconformances occur only with older kernels: +.IP \- 3 +The information returned by +.BR times (2) +and +.BR getrusage (2) +is per-thread rather than process-wide (fixed in kernel 2.6.9). +.IP \- 3 +Threads do not share resource limits (fixed in kernel 2.6.10). +.IP \- 3 +Threads do not share interval timers (fixed in kernel 2.6.12). +.IP \- 3 +Only the main thread is permitted to start a new session using +.BR setsid (2) +(fixed in kernel 2.6.16). +.IP \- 3 +Only the main thread is permitted to make the process into a +process group leader using +.BR setpgid (2) +(fixed in kernel 2.6.16). +.IP \- 3 +Threads have distinct alternate signal stack settings. +However, a new thread's alternate signal stack settings +are copied from the thread that created it, so that +the threads initially share an alternate signal stack +(fixed in kernel 2.6.16). +.PP +Note the following further points about the NPTL implementation: +.IP \- 3 +If the stack size soft resource limit (see the description of +.B RLIMIT_STACK +in +.BR setrlimit (2)) +is set to a value other than +.IR unlimited , +then this value defines the default stack size for new threads. +To be effective, this limit must be set before the program +is executed, perhaps using the +.I ulimit -s +shell built-in command +.RI ( "limit stacksize" +in the C shell). +.SS Determining the threading implementation +Since glibc 2.3.2, the +.BR getconf (1) +command can be used to determine +the system's threading implementation, for example: +.PP +.in +4n +.EX +bash$ getconf GNU_LIBPTHREAD_VERSION +NPTL 2.3.4 +.EE +.in +.PP +With older glibc versions, a command such as the following should +be sufficient to determine the default threading implementation: +.PP +.in +4n +.EX +bash$ $( ldd /bin/ls | grep libc.so | awk \(aq{print $3}\(aq ) | \\ + egrep \-i \(aqthreads|nptl\(aq + Native POSIX Threads Library by Ulrich Drepper et al +.EE +.in +.SS Selecting the threading implementation: LD_ASSUME_KERNEL +On systems with a glibc that supports both LinuxThreads and NPTL +(i.e., glibc 2.3.\fIx\fP), the +.B LD_ASSUME_KERNEL +environment variable can be used to override +the dynamic linker's default choice of threading implementation. +This variable tells the dynamic linker to assume that it is +running on top of a particular kernel version. +By specifying a kernel version that does not +provide the support required by NPTL, we can force the use +of LinuxThreads. +(The most likely reason for doing this is to run a +(broken) application that depends on some nonconformant behavior +in LinuxThreads.) +For example: +.PP +.in +4n +.EX +bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \\ + awk \(aq{print $3}\(aq ) | egrep \-i \(aqthreads|nptl\(aq + linuxthreads-0.10 by Xavier Leroy +.EE +.in +.SH SEE ALSO +.ad l +.nh +.BR clone (2), +.BR fork (2), +.BR futex (2), +.BR gettid (2), +.BR proc (5), +.BR attributes (7), +.BR futex (7), +.BR nptl (7), +.BR sigevent (7), +.BR signal (7) +.PP +Various Pthreads manual pages, for example: +.BR pthread_atfork (3), +.BR pthread_attr_init (3), +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_cond_signal (3), +.BR pthread_cond_wait (3), +.BR pthread_create (3), +.BR pthread_detach (3), +.BR pthread_equal (3), +.BR pthread_exit (3), +.BR pthread_key_create (3), +.BR pthread_kill (3), +.BR pthread_mutex_lock (3), +.BR pthread_mutex_unlock (3), +.BR pthread_mutexattr_destroy (3), +.BR pthread_mutexattr_init (3), +.BR pthread_once (3), +.BR pthread_spin_init (3), +.BR pthread_spin_lock (3), +.BR pthread_rwlockattr_setkind_np (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthread_setspecific (3), +.BR pthread_sigmask (3), +.BR pthread_sigqueue (3), +and +.BR pthread_testcancel (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/pty.7 b/man7/pty.7 new file mode 100644 index 0000000..b868b02 --- /dev/null +++ b/man7/pty.7 @@ -0,0 +1,180 @@ +.\" Copyright (C) 2005 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH PTY 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +pty \- pseudoterminal interfaces +.SH DESCRIPTION +A pseudoterminal (sometimes abbreviated "pty") +is a pair of virtual character devices that +provide a bidirectional communication channel. +One end of the channel is called the +.IR master ; +the other end is called the +.IR slave . +The slave end of the pseudoterminal provides an interface +that behaves exactly like a classical terminal. +A process that expects to be connected to a terminal, +can open the slave end of a pseudoterminal and +then be driven by a program that has opened the master end. +Anything that is written on the master end is provided to the process +on the slave end as though it was input typed on a terminal. +For example, writing the interrupt character (usually control-C) +to the master device would cause an interrupt signal +.RB ( SIGINT ) +to be generated for the foreground process group +that is connected to the slave. +Conversely, anything that is written to the slave end of the +pseudoterminal can be read by the process that is connected to +the master end. +Pseudoterminals are used by applications such as network login services +.RB ( ssh "(1), " rlogin "(1), " telnet (1)), +terminal emulators such as +.BR xterm (1), +.BR script (1), +.BR screen (1), +.BR tmux (1), +.BR unbuffer (1), +and +.BR expect (1). +.PP +Data flow between master and slave is handled asynchronously, +much like data flow with a physical terminal. +Data written to the slave will be available at the master promptly, +but may not be available immediately. +Similarly, there may be a small processing delay between +a write to the master, and the effect being visible at the slave. +.PP +Historically, two pseudoterminal APIs have evolved: BSD and System V. +SUSv1 standardized a pseudoterminal API based on the System V API, +and this API should be employed in all new programs that use +pseudoterminals. +.PP +Linux provides both BSD-style and (standardized) System V-style +pseudoterminals. +System V-style terminals are commonly called UNIX 98 pseudoterminals +on Linux systems. +Since kernel 2.6.4, BSD-style pseudoterminals are considered deprecated +(they can be disabled when configuring the kernel); +UNIX 98 pseudoterminals should be used in new applications. +.SS UNIX 98 pseudoterminals +An unused UNIX 98 pseudoterminal master is opened by calling +.BR posix_openpt (3). +(This function opens the master clone device, +.IR /dev/ptmx ; +see +.BR pts (4).) +After performing any program-specific initializations, +changing the ownership and permissions of the slave device using +.BR grantpt (3), +and unlocking the slave using +.BR unlockpt (3)), +the corresponding slave device can be opened by passing +the name returned by +.BR ptsname (3) +in a call to +.BR open (2). +.PP +The Linux kernel imposes a limit on the number of available +UNIX 98 pseudoterminals. +In kernels up to and including 2.6.3, this limit is configured +at kernel compilation time +.RB ( CONFIG_UNIX98_PTYS ), +and the permitted number of pseudoterminals can be up to 2048, +with a default setting of 256. +Since kernel 2.6.4, the limit is dynamically adjustable via +.IR /proc/sys/kernel/pty/max , +and a corresponding file, +.IR /proc/sys/kernel/pty/nr , +indicates how many pseudoterminals are currently in use. +For further details on these two files, see +.BR proc (5). +.SS BSD pseudoterminals +BSD-style pseudoterminals are provided as precreated pairs, with +names of the form +.I /dev/ptyXY +(master) and +.I /dev/ttyXY +(slave), +where X is a letter from the 16-character set [p\-za\-e], +and Y is a letter from the 16-character set [0\-9a\-f]. +(The precise range of letters in these two sets varies across UNIX +implementations.) +For example, +.I /dev/ptyp1 +and +.I /dev/ttyp1 +constitute a BSD pseudoterminal pair. +A process finds an unused pseudoterminal pair by trying to +.BR open (2) +each pseudoterminal master until an open succeeds. +The corresponding pseudoterminal slave (substitute "tty" +for "pty" in the name of the master) can then be opened. +.SH FILES +.TP +.I /dev/ptmx +UNIX 98 master clone device +.TP +.I /dev/pts/* +UNIX 98 slave devices +.TP +.I /dev/pty[p\-za\-e][0\-9a\-f] +BSD master devices +.TP +.I /dev/tty[p\-za\-e][0\-9a\-f] +BSD slave devices +.SH NOTES +A description of the +.B TIOCPKT +.BR ioctl (2), +which controls packet mode operation, can be found in +.BR ioctl_tty (2). +.PP +The BSD +.BR ioctl (2) +operations +.BR TIOCSTOP , +.BR TIOCSTART , +.BR TIOCUCNTL , +and +.BR TIOCREMOTE +have not been implemented under Linux. +.SH SEE ALSO +.BR ioctl_tty (2), +.BR select (2), +.BR setsid (2), +.BR forkpty (3), +.BR openpty (3), +.BR termios (3), +.BR pts (4), +.BR tty (4) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/random.7 b/man7/random.7 new file mode 100644 index 0000000..aff9afc --- /dev/null +++ b/man7/random.7 @@ -0,0 +1,241 @@ +.\" Copyright (C) 2008, George Spelvin , +.\" and Copyright (C) 2008, Matt Mackall +.\" and Copyright (C) 2016, Laurent Georget +.\" and Copyright (C) 2016, Nikos Mavrogiannopoulos +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" The following web page is quite informative: +.\" http://www.2uo.de/myths-about-urandom/ +.\" +.TH RANDOM 7 2017-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +random \- overview of interfaces for obtaining randomness +.SH DESCRIPTION +The kernel random-number generator relies on entropy gathered from +device drivers and other sources of environmental noise to seed +a cryptographically secure pseudorandom number generator (CSPRNG). +It is designed for security, rather than speed. +.PP +The following interfaces provide access to output from the kernel CSPRNG: +.IP * 3 +The +.I /dev/urandom +and +.I /dev/random +devices, both described in +.BR random (4). +These devices have been present on Linux since early times, +and are also available on many other systems. +.IP * +The Linux-specific +.BR getrandom (2) +system call, available since Linux 3.17. +This system call provides access either to the same source as +.I /dev/urandom +(called the +.I urandom +source in this page) +or to the same source as +.I /dev/random +(called the +.I random +source in this page). +The default is the +.I urandom +source; the +.I random +source is selected by specifying the +.BR GRND_RANDOM +flag to the system call. +(The +.BR getentropy (3) +function provides a slightly more portable interface on top of +.BR getrandom (2).) +.\" +.SS Initialization of the entropy pool +The kernel collects bits of entropy from the environment. +When a sufficient number of random bits has been collected, the +entropy pool is considered to be initialized. +.SS Choice of random source +Unless you are doing long-term key generation (and most likely not even +then), you probably shouldn't be reading from the +.IR /dev/random +device or employing +.BR getrandom (2) +with the +.BR GRND_RANDOM +flag. +Instead, either read from the +.IR /dev/urandom +device or employ +.BR getrandom (2) +without the +.B GRND_RANDOM +flag. +The cryptographic algorithms used for the +.IR urandom +source are quite conservative, and so should be sufficient for all purposes. +.PP +The disadvantage of +.B GRND_RANDOM +and reads from +.I /dev/random +is that the operation can block for an indefinite period of time. +Furthermore, dealing with the partially fulfilled +requests that can occur when using +.B GRND_RANDOM +or when reading from +.I /dev/random +increases code complexity. +.\" +.SS Monte Carlo and other probabilistic sampling applications +Using these interfaces to provide large quantities of data for +Monte Carlo simulations or other programs/algorithms which are +doing probabilistic sampling will be slow. +Furthermore, it is unnecessary, because such applications do not +need cryptographically secure random numbers. +Instead, use the interfaces described in this page to obtain +a small amount of data to seed a user-space pseudorandom +number generator for use by such applications. +.\" +.SS Comparison between getrandom, /dev/urandom, and /dev/random +The following table summarizes the behavior of the various +interfaces that can be used to obtain randomness. +.B GRND_NONBLOCK +is a flag that can be used to control the blocking behavior of +.BR getrandom (2). +The final column of the table considers the case that can occur +in early boot time when the entropy pool is not yet initialized. +.ad l +.TS +allbox; +lbw13 lbw12 lbw14 lbw18 +l l l l. +Interface Pool T{ +Blocking +\%behavior +T} T{ +Behavior when pool is not yet ready +T} +T{ +.I /dev/random +T} T{ +Blocking pool +T} T{ +If entropy too low, blocks until there is enough entropy again +T} T{ +Blocks until enough entropy gathered +T} +T{ +.I /dev/urandom +T} T{ +CSPRNG output +T} T{ +Never blocks +T} T{ +Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography) +T} +T{ +.BR getrandom () +T} T{ +Same as +.I /dev/urandom +T} T{ +Does not block once is pool ready +T} T{ +Blocks until pool ready +T} +T{ +.BR getrandom () +.B GRND_RANDOM +T} T{ +Same as +.I /dev/random +T} T{ +If entropy too low, blocks until there is enough entropy again +T} T{ +Blocks until pool ready +T} +T{ +.BR getrandom () +.B GRND_NONBLOCK +T} T{ +Same as +.I /dev/urandom +T} T{ +Does not block once is pool ready +T} T{ +.B EAGAIN +T} +T{ +.BR getrandom () +.B GRND_RANDOM ++ +.B GRND_NONBLOCK +T} T{ +Same as +.I /dev/random +T} T{ +.B EAGAIN +if not enough entropy available +T} T{ +.B EAGAIN +T} +.TE +.ad +.\" +.SS Generating cryptographic keys +The amount of seed material required to generate a cryptographic key +equals the effective key size of the key. +For example, a 3072-bit RSA +or Diffie-Hellman private key has an effective key size of 128 bits +(it requires about 2^128 operations to break) so a key generator +needs only 128 bits (16 bytes) of seed material from +.IR /dev/random . +.PP +While some safety margin above that minimum is reasonable, as a guard +against flaws in the CSPRNG algorithm, no cryptographic primitive +available today can hope to promise more than 256 bits of security, +so if any program reads more than 256 bits (32 bytes) from the kernel +random pool per invocation, or per reasonable reseed interval (not less +than one minute), that should be taken as a sign that its cryptography is +.I not +skillfully implemented. +.\" +.SH SEE ALSO +.BR getrandom (2), +.BR getauxval (3), +.BR getentropy (3), +.BR random (4), +.BR urandom (4), +.BR signal (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/raw.7 b/man7/raw.7 new file mode 100644 index 0000000..4893ba2 --- /dev/null +++ b/man7/raw.7 @@ -0,0 +1,296 @@ +'\" t +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ +.\" +.TH RAW 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +raw \- Linux IPv4 raw sockets +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.BI "raw_socket = socket(AF_INET, SOCK_RAW, int " protocol ); +.SH DESCRIPTION +Raw sockets allow new IPv4 protocols to be implemented in user space. +A raw socket receives or sends the raw datagram not +including link level headers. +.PP +The IPv4 layer generates an IP header when sending a packet unless the +.B IP_HDRINCL +socket option is enabled on the socket. +When it is enabled, the packet must contain an IP header. +For receiving, the IP header is always included in the packet. +.PP +In order to create a raw socket, a process must have the +.B CAP_NET_RAW +capability in the user namespace that governs its network namespace. +.PP +All packets or errors matching the +.I protocol +number specified +for the raw socket are passed to this socket. +For a list of the allowed protocols, +see the IANA list of assigned protocol numbers at +.UR http://www.iana.org/assignments/protocol\-numbers/ +.UE +and +.BR getprotobyname (3). +.PP +A protocol of +.B IPPROTO_RAW +implies enabled +.B IP_HDRINCL +and is able to send any IP protocol that is specified in the passed +header. +Receiving of all IP protocols via +.B IPPROTO_RAW +is not possible using raw sockets. +.RS +.TS +tab(:) allbox; +c s +l l. +IP Header fields modified on sending by \fBIP_HDRINCL\fP +IP Checksum:Always filled in +Source Address:Filled in when zero +Packet ID:Filled in when zero +Total Length:Always filled in +.TE +.RE +.PP +.PP +If +.B IP_HDRINCL +is specified and the IP header has a nonzero destination address, then +the destination address of the socket is used to route the packet. +When +.B MSG_DONTROUTE +is specified, the destination address should refer to a local interface, +otherwise a routing table lookup is done anyway but gatewayed routes +are ignored. +.PP +If +.B IP_HDRINCL +isn't set, then IP header options can be set on raw sockets with +.BR setsockopt (2); +see +.BR ip (7) +for more information. +.PP +Starting with Linux 2.2, all IP header fields and options can be set using +IP socket options. +This means raw sockets are usually needed only for new +protocols or protocols with no user interface (like ICMP). +.PP +When a packet is received, it is passed to any raw sockets which have +been bound to its protocol before it is passed to other protocol handlers +(e.g., kernel protocol modules). +.SS Address format +For sending and receiving datagrams +.RB ( sendto (2), +.BR recvfrom (2), +and similar), +raw sockets use the standard +.I sockaddr_in +address structure defined in +.BR ip (7). +The +.I sin_port +field could be used to specify the IP protocol number, +but it is ignored for sending in Linux 2.2 and later, and should be always +set to 0 (see BUGS). +For incoming packets, +.I sin_port +.\" commit f59fc7f30b710d45aadf715460b3e60dbe9d3418 +is set to zero. +.SS Socket options +Raw socket options can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2) +by passing the +.B IPPROTO_RAW +.\" Or SOL_RAW on Linux +family flag. +.TP +.B ICMP_FILTER +Enable a special filter for raw sockets bound to the +.B IPPROTO_ICMP +protocol. +The value has a bit set for each ICMP message type which +should be filtered out. +The default is to filter no ICMP messages. +.PP +In addition, all +.BR ip (7) +.B IPPROTO_IP +socket options valid for datagram sockets are supported. +.SS Error handling +Errors originating from the network are passed to the user only when the +socket is connected or the +.B IP_RECVERR +flag is enabled. +For connected sockets, only +.B EMSGSIZE +and +.B EPROTO +are passed for compatibility. +With +.BR IP_RECVERR , +all network errors are saved in the error queue. +.SH ERRORS +.TP +.B EACCES +User tried to send to a broadcast address without having the +broadcast flag set on the socket. +.TP +.B EFAULT +An invalid memory address was supplied. +.TP +.B EINVAL +Invalid argument. +.TP +.B EMSGSIZE +Packet too big. +Either Path MTU Discovery is enabled (the +.B IP_MTU_DISCOVER +socket flag) or the packet size exceeds the maximum allowed IPv4 +packet size of 64\ kB. +.TP +.B EOPNOTSUPP +Invalid flag has been passed to a socket call (like +.BR MSG_OOB ). +.TP +.B EPERM +The user doesn't have permission to open raw sockets. +Only processes with an effective user ID of 0 or the +.B CAP_NET_RAW +attribute may do that. +.TP +.B EPROTO +An ICMP error has arrived reporting a parameter problem. +.SH VERSIONS +.B IP_RECVERR +and +.B ICMP_FILTER +are new in Linux 2.2. +They are Linux extensions and should not be used in portable programs. +.PP +Linux 2.0 enabled some bug-to-bug compatibility with BSD in the +raw socket code when the +.B SO_BSDCOMPAT +socket option was set; since Linux 2.2, +this option no longer has that effect. +.SH NOTES +By default, raw sockets do path MTU (Maximum Transmission Unit) discovery. +This means the kernel +will keep track of the MTU to a specific target IP address and return +.B EMSGSIZE +when a raw packet write exceeds it. +When this happens, the application should decrease the packet size. +Path MTU discovery can be also turned off using the +.B IP_MTU_DISCOVER +socket option or the +.I /proc/sys/net/ipv4/ip_no_pmtu_disc +file, see +.BR ip (7) +for details. +When turned off, raw sockets will fragment outgoing packets +that exceed the interface MTU. +However, disabling it is not recommended +for performance and reliability reasons. +.PP +A raw socket can be bound to a specific local address using the +.BR bind (2) +call. +If it isn't bound, all packets with the specified IP protocol are received. +In addition, a raw socket can be bound to a specific network device using +.BR SO_BINDTODEVICE ; +see +.BR socket (7). +.PP +An +.B IPPROTO_RAW +socket is send only. +If you really want to receive all IP packets, use a +.BR packet (7) +socket with the +.B ETH_P_IP +protocol. +Note that packet sockets don't reassemble IP fragments, +unlike raw sockets. +.PP +If you want to receive all ICMP packets for a datagram socket, +it is often better to use +.B IP_RECVERR +on that particular socket; see +.BR ip (7). +.PP +Raw sockets may tap all IP protocols in Linux, even +protocols like ICMP or TCP which have a protocol module in the kernel. +In this case, the packets are passed to both the kernel module and the raw +socket(s). +This should not be relied upon in portable programs, many other BSD +socket implementation have limitations here. +.PP +Linux never changes headers passed from the user (except for filling +in some zeroed fields as described for +.BR IP_HDRINCL ). +This differs from many other implementations of raw sockets. +.PP +Raw sockets are generally rather unportable and should be avoided in +programs intended to be portable. +.PP +Sending on raw sockets should take the IP protocol from +.IR sin_port ; +this ability was lost in Linux 2.2. +The workaround is to use +.BR IP_HDRINCL . +.SH BUGS +Transparent proxy extensions are not described. +.PP +When the +.B IP_HDRINCL +option is set, datagrams will not be fragmented and are limited to +the interface MTU. +.PP +Setting the IP protocol for sending in +.I sin_port +got lost in Linux 2.2. +The protocol that the socket was bound to or that +was specified in the initial +.BR socket (2) +call is always used. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR capabilities (7), +.BR ip (7), +.BR socket (7) +.PP +.B RFC\ 1191 +for path MTU discovery. +.B RFC\ 791 +and the +.I +header file for the IP protocol. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/regex.7 b/man7/regex.7 new file mode 100644 index 0000000..f2609a1 --- /dev/null +++ b/man7/regex.7 @@ -0,0 +1,300 @@ +.\" From Henry Spencer's regex package (as found in the apache +.\" distribution). The package carries the following copyright: +.\" +.\" Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved. +.\" %%%LICENSE_START(MISC) +.\" This software is not subject to any license of the American Telephone +.\" and Telegraph Company or of the Regents of the University of California. +.\" +.\" Permission is granted to anyone to use this software for any purpose +.\" on any computer system, and to alter it and redistribute it, subject +.\" to the following restrictions: +.\" +.\" 1. The author is not responsible for the consequences of use of this +.\" software, no matter how awful, even if they arise from flaws in it. +.\" +.\" 2. The origin of this software must not be misrepresented, either by +.\" explicit claim or by omission. Since few users ever read sources, +.\" credits must appear in the documentation. +.\" +.\" 3. Altered versions must be plainly marked as such, and must not be +.\" misrepresented as being the original software. Since few users +.\" ever read sources, credits must appear in the documentation. +.\" +.\" 4. This notice may not be removed or altered. +.\" %%%LICENSE_END +.\" +.\" In order to comply with `credits must appear in the documentation' +.\" I added an AUTHOR paragraph below - aeb. +.\" +.\" In the default nroff environment there is no dagger \(dg. +.\" +.\" 2005-05-11 Removed discussion of `[[:<:]]' and `[[:>:]]', which +.\" appear not to be in the glibc implementation of regcomp +.\" +.ie t .ds dg \(dg +.el .ds dg (!) +.TH REGEX 7 2009-01-12 "" "Linux Programmer's Manual" +.SH NAME +regex \- POSIX.2 regular expressions +.SH DESCRIPTION +Regular expressions ("RE"s), +as defined in POSIX.2, come in two forms: +modern REs (roughly those of +.IR egrep ; +POSIX.2 calls these "extended" REs) +and obsolete REs (roughly those of +.BR ed (1); +POSIX.2 "basic" REs). +Obsolete REs mostly exist for backward compatibility in some old programs; +they will be discussed at the end. +POSIX.2 leaves some aspects of RE syntax and semantics open; +"\*(dg" marks decisions on these aspects that +may not be fully portable to other POSIX.2 implementations. +.PP +A (modern) RE is one\*(dg or more nonempty\*(dg \fIbranches\fR, +separated by \(aq|\(aq. +It matches anything that matches one of the branches. +.PP +A branch is one\*(dg or more \fIpieces\fR, concatenated. +It matches a match for the first, followed by a match for the second, +and so on. +.PP +A piece is an \fIatom\fR possibly followed +by a single\*(dg \(aq*\(aq, \(aq+\(aq, \(aq?\(aq, or \fIbound\fR. +An atom followed by \(aq*\(aq +matches a sequence of 0 or more matches of the atom. +An atom followed by \(aq+\(aq +matches a sequence of 1 or more matches of the atom. +An atom followed by \(aq?\(aq +matches a sequence of 0 or 1 matches of the atom. +.PP +A \fIbound\fR is \(aq{\(aq followed by an unsigned decimal integer, +possibly followed by \(aq,\(aq +possibly followed by another unsigned decimal integer, +always followed by \(aq}\(aq. +The integers must lie between 0 and +.B RE_DUP_MAX +(255\*(dg) inclusive, +and if there are two of them, the first may not exceed the second. +An atom followed by a bound containing one integer \fIi\fR +and no comma matches +a sequence of exactly \fIi\fR matches of the atom. +An atom followed by a bound +containing one integer \fIi\fR and a comma matches +a sequence of \fIi\fR or more matches of the atom. +An atom followed by a bound +containing two integers \fIi\fR and \fIj\fR matches +a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom. +.PP +An atom is a regular expression enclosed in "\fI()\fP" +(matching a match for the regular expression), +an empty set of "\fI()\fP" (matching the null string)\*(dg, +a \fIbracket expression\fR (see below), \(aq.\(aq +(matching any single character), \(aq^\(aq (matching the null string at the +beginning of a line), \(aq$\(aq (matching the null string at the +end of a line), a \(aq\e\(aq followed by one of the characters +"\fI^.[$()|*+?{\e\fP" +(matching that character taken as an ordinary character), +a \(aq\e\(aq followed by any other character\*(dg +(matching that character taken as an ordinary character, +as if the \(aq\e\(aq had not been present\*(dg), +or a single character with no other significance (matching that character). +A \(aq{\(aq followed by a character other than a digit is an ordinary +character, not the beginning of a bound\*(dg. +It is illegal to end an RE with \(aq\e\(aq. +.PP +A \fIbracket expression\fR is a list of characters enclosed in "\fI[]\fP". +It normally matches any single character from the list (but see below). +If the list begins with \(aq^\(aq, +it matches any single character +(but see below) \fInot\fR from the rest of the list. +If two characters in the list are separated by \(aq\-\(aq, this is shorthand +for the full \fIrange\fR of characters between those two (inclusive) in the +collating sequence, +for example, "\fI[0\-9]\fP" in ASCII matches any decimal digit. +It is illegal\*(dg for two ranges to share an +endpoint, for example, "\fIa\-c\-e\fP". +Ranges are very collating-sequence-dependent, +and portable programs should avoid relying on them. +.PP +To include a literal \(aq]\(aq in the list, make it the first character +(following a possible \(aq^\(aq). +To include a literal \(aq\-\(aq, make it the first or last character, +or the second endpoint of a range. +To use a literal \(aq\-\(aq as the first endpoint of a range, +enclose it in "\fI[.\fP" and "\fI.]\fP" +to make it a collating element (see below). +With the exception of these and some combinations using \(aq[\(aq (see next +paragraphs), all other special characters, including \(aq\e\(aq, lose their +special significance within a bracket expression. +.PP +Within a bracket expression, a collating element (a character, +a multicharacter sequence that collates as if it were a single character, +or a collating-sequence name for either) +enclosed in "\fI[.\fP" and "\fI.]\fP" stands for the +sequence of characters of that collating element. +The sequence is a single element of the bracket expression's list. +A bracket expression containing a multicharacter collating element +can thus match more than one character, +for example, if the collating sequence includes a "ch" collating element, +then the RE "\fI[[.ch.]]*c\fP" matches the first five characters +of "chchcc". +.PP +Within a bracket expression, a collating element enclosed in "\fI[=\fP" and +"\fI=]\fP" is an equivalence class, standing for the sequences of characters +of all collating elements equivalent to that one, including itself. +(If there are no other equivalent collating elements, +the treatment is as if the enclosing delimiters +were "\fI[.\fP" and "\fI.]\fP".) +For example, if o and \o'o^' are the members of an equivalence class, +then "\fI[[=o=]]\fP", "\fI[[=\o'o^'=]]\fP", +and "\fI[o\o'o^']\fP" are all synonymous. +An equivalence class may not\*(dg be an endpoint +of a range. +.PP +Within a bracket expression, the name of a \fIcharacter class\fR enclosed +in "\fI[:\fP" and "\fI:]\fP" stands for the list +of all characters belonging to that +class. +Standard character class names are: +.PP +.RS +.TS +l l l. +alnum digit punct +alpha graph space +blank lower upper +cntrl print xdigit +.TE +.RE +.PP +These stand for the character classes defined in +.BR wctype (3). +A locale may provide others. +A character class may not be used as an endpoint of a range. +.\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 +.\" The following does not seem to apply in the glibc implementation +.\" .PP +.\" There are two special cases\*(dg of bracket expressions: +.\" the bracket expressions "\fI[[:<:]]\fP" and "\fI[[:>:]]\fP" match +.\" the null string at the beginning and end of a word respectively. +.\" A word is defined as a sequence of +.\" word characters +.\" which is neither preceded nor followed by +.\" word characters. +.\" A word character is an +.\" .I alnum +.\" character (as defined by +.\" .BR wctype (3)) +.\" or an underscore. +.\" This is an extension, +.\" compatible with but not specified by POSIX.2, +.\" and should be used with +.\" caution in software intended to be portable to other systems. +.PP +In the event that an RE could match more than one substring of a given +string, +the RE matches the one starting earliest in the string. +If the RE could match more than one substring starting at that point, +it matches the longest. +Subexpressions also match the longest possible substrings, subject to +the constraint that the whole match be as long as possible, +with subexpressions starting earlier in the RE taking priority over +ones starting later. +Note that higher-level subexpressions thus take priority over +their lower-level component subexpressions. +.PP +Match lengths are measured in characters, not collating elements. +A null string is considered longer than no match at all. +For example, +"\fIbb*\fP" matches the three middle characters of "abbbc", +"\fI(wee|week)(knights|nights)\fP" +matches all ten characters of "weeknights", +when "\fI(.*).*\fP" is matched against "abc" the parenthesized subexpression +matches all three characters, and +when "\fI(a*)*\fP" is matched against "bc" +both the whole RE and the parenthesized +subexpression match the null string. +.PP +If case-independent matching is specified, +the effect is much as if all case distinctions had vanished from the +alphabet. +When an alphabetic that exists in multiple cases appears as an +ordinary character outside a bracket expression, it is effectively +transformed into a bracket expression containing both cases, +for example, \(aqx\(aq becomes "\fI[xX]\fP". +When it appears inside a bracket expression, all case counterparts +of it are added to the bracket expression, so that, for example, "\fI[x]\fP" +becomes "\fI[xX]\fP" and "\fI[^x]\fP" becomes "\fI[^xX]\fP". +.PP +No particular limit is imposed on the length of REs\*(dg. +Programs intended to be portable should not employ REs longer +than 256 bytes, +as an implementation can refuse to accept such REs and remain +POSIX-compliant. +.PP +Obsolete ("basic") regular expressions differ in several respects. +\(aq|\(aq, \(aq+\(aq, and \(aq?\(aq are +ordinary characters and there is no equivalent +for their functionality. +The delimiters for bounds are "\fI\e{\fP" and "\fI\e}\fP", +with \(aq{\(aq and \(aq}\(aq by themselves ordinary characters. +The parentheses for nested subexpressions are "\fI\e(\fP" and "\fI\e)\fP", +with \(aq(\(aq and \(aq)\(aq by themselves ordinary characters. +\(aq^\(aq is an ordinary character except at the beginning of the +RE or\*(dg the beginning of a parenthesized subexpression, +\(aq$\(aq is an ordinary character except at the end of the +RE or\*(dg the end of a parenthesized subexpression, +and \(aq*\(aq is an ordinary character if it appears at the beginning of the +RE or the beginning of a parenthesized subexpression +(after a possible leading \(aq^\(aq). +.PP +Finally, there is one new type of atom, a \fIback reference\fR: +\(aq\e\(aq followed by a nonzero decimal digit \fId\fR +matches the same sequence of characters +matched by the \fId\fRth parenthesized subexpression +(numbering subexpressions by the positions of their opening parentheses, +left to right), +so that, for example, "\fI\e([bc]\e)\e1\fP" matches "bb" or "cc" but not "bc". +.SH BUGS +Having two kinds of REs is a botch. +.PP +The current POSIX.2 spec says that \(aq)\(aq is an ordinary character in +the absence of an unmatched \(aq(\(aq; +this was an unintentional result of a wording error, +and change is likely. +Avoid relying on it. +.PP +Back references are a dreadful botch, +posing major problems for efficient implementations. +They are also somewhat vaguely defined +(does +"\fIa\e(\e(b\e)*\e2\e)*d\fP" match "abbbd"?). +Avoid using them. +.PP +POSIX.2's specification of case-independent matching is vague. +The "one case implies all cases" definition given above +is current consensus among implementors as to the right interpretation. +.\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 +.\" The following does not seem to apply in the glibc implementation +.\" .PP +.\" The syntax for word boundaries is incredibly ugly. +.SH AUTHOR +.\" Sigh... The page license means we must have the author's name +.\" in the formatted output. +This page was taken from Henry Spencer's regex package. +.SH SEE ALSO +.BR grep (1), +.BR regex (3) +.PP +POSIX.2, section 2.8 (Regular Expression Notation). +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7 new file mode 100644 index 0000000..a44e8c6 --- /dev/null +++ b/man7/rtld-audit.7 @@ -0,0 +1,616 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2009-01-12, mtk, Created +.\" +.TH RTLD-AUDIT 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +rtld-audit \- auditing API for the dynamic linker +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.fi +.SH DESCRIPTION +The GNU dynamic linker (run-time linker) +provides an auditing API that allows an application +to be notified when various dynamic linking events occur. +This API is very similar to the auditing interface provided by the +Solaris run-time linker. +The necessary constants and prototypes are defined by including +.IR . +.PP +To use this interface, the programmer creates a shared library +that implements a standard set of function names. +Not all of the functions need to be implemented: in most cases, +if the programmer is not interested in a particular class of auditing event, +then no implementation needs to be provided for the corresponding +auditing function. +.PP +To employ the auditing interface, the environment variable +.BR LD_AUDIT +must be defined to contain a colon-separated list of shared libraries, +each of which can implement (parts of) the auditing API. +When an auditable event occurs, +the corresponding function is invoked in each library, +in the order that the libraries are listed. +.SS la_version() +\& +.nf +.BI "unsigned int la_version(unsigned int " version ); +.fi +.PP +This is the only function that +.I must +be defined by an auditing library: +it performs the initial handshake between the dynamic linker and +the auditing library. +When invoking this function, the dynamic linker passes, in +.IR version , +the highest version of the auditing interface that the linker supports. +If necessary, the auditing library can check that this version +is sufficient for its requirements. +.PP +As its function result, +this function should return the version of the auditing interface +that this auditing library expects to use (returning +.I version +is acceptable). +If the returned value is 0, +or a version that is greater than that supported by the dynamic linker, +then the audit library is ignored. +.SS la_objsearch() +\& +.nf +.BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie , +.BI " unsigned int " flag ); +.fi +.PP +The dynamic linker invokes this function to inform the auditing library +that it is about to search for a shared object. +The +.I name +argument is the filename or pathname that is to be searched for. +.I cookie +identifies the shared object that initiated the search. +.I flag +is set to one of the following values: +.TP 17 +.B LA_SER_ORIG +This is the original name that is being searched for. +Typically, this name comes from an ELF +.B DT_NEEDED +entry, or is the +.I filename +argument given to +.BR dlopen (3). +.TP +.B LA_SER_LIBPATH +.I name +was created using a directory specified in +.BR LD_LIBRARY_PATH . +.TP +.B LA_SER_RUNPATH +.I name +was created using a directory specified in an ELF +.B DT_RPATH +or +.B DT_RUNPATH +list. +.TP +.B LA_SER_CONFIG +.I name +was found via the +.BR ldconfig (8) +cache +.RI ( /etc/ld.so.cache ). +.TP +.B LA_SER_DEFAULT +.I name +was found via a search of one of the default directories. +.TP +.B LA_SER_SECURE +.I name +is specific to a secure object (unused on Linux). +.PP +As its function result, +.BR la_objsearch () +returns the pathname that the dynamic linker should use +for further processing. +If NULL is returned, then this pathname is ignored for further processing. +If this audit library simply intends to monitor search paths, then +.I name +should be returned. +.SS la_activity() +\& +.nf +.BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag ); +.fi +.PP +The dynamic linker calls this function to inform the auditing library +that link-map activity is occurring. +.I cookie +identifies the object at the head of the link map. +When the dynamic linker invokes this function, +.I flag +is set to one of the following values: +.TP 19 +.B LA_ACT_ADD +New objects are being added to the link map. +.TP +.B LA_ACT_DELETE +Objects are being removed from the link map. +.TP +.B LA_ACT_CONSISTENT +Link-map activity has been completed: the map is once again consistent. +.SS la_objopen() +\& +.nf +.BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid , +.BI " uintptr_t *" cookie ); +.fi +.PP +The dynamic linker calls this function when a new shared object is loaded. +The +.I map +argument is a pointer to a link-map structure that describes the object. +The +.I lmid +field has one of the following values +.TP 17 +.B LM_ID_BASE +Link map is part of the initial namespace. +.TP +.B LM_ID_NEWLM +Link map is part of a new namespace requested via +.BR dlmopen (3). +.PP +.I cookie +is a pointer to an identifier for this object. +The identifier is provided to later calls to functions +in the auditing library in order to identify this object. +This identifier is initialized to point to object's link map, +but the audit library can change the identifier to some other value +that it may prefer to use to identify the object. +.PP +As its return value, +.BR la_objopen () +returns a bit mask created by ORing zero or more of the +following constants, +which allow the auditing library to select the objects to be monitored by +.BR la_symbind* (): +.TP 17 +.B LA_FLG_BINDTO +Audit symbol bindings to this object. +.TP +.B LA_FLG_BINDFROM +Audit symbol bindings from this object. +.PP +A return value of 0 from +.BR la_objopen () +indicates that no symbol bindings should be audited for this object. +.SS la_objclose() +\& +.nf +.BI "unsigned int la_objclose(uintptr_t *" cookie ); +.fi +.PP +The dynamic linker invokes this function after any finalization +code for the object has been executed, +before the object is unloaded. +The +.I cookie +argument is the identifier obtained from a previous invocation of +.BR la_objopen (). +.PP +In the current implementation, the value returned by +.BR la_objclose () +is ignored. +.SS la_preinit() +\& +.nf +.BI "void la_preinit(uintptr_t *" cookie ); +.fi +.PP +The dynamic linker invokes this function after all shared objects +have been loaded, before control is passed to the application +(i.e., before calling +.IR main ()). +Note that +.IR main () +may still later dynamically load objects using +.BR dlopen (3). +.SS la_symbind*() +\& +.nf +.BI "uintptr_t la_symbind32(Elf32_Sym *" sym ", unsigned int " ndx , +.BI " uintptr_t *" refcook ", uintptr_t *" defcook , +.BI " unsigned int *" flags ", const char *" symname ); +.BI "uintptr_t la_symbind64(Elf64_Sym *" sym ", unsigned int " ndx , +.BI " uintptr_t *" refcook ", uintptr_t *" defcook , +.BI " unsigned int *" flags ", const char *" symname ); +.fi +.PP +The dynamic linker invokes one of these functions +when a symbol binding occurs between two shared objects +that have been marked for auditing notification by +.BR la_objopen (). +The +.BR la_symbind32 () +function is employed on 32-bit platforms; +the +.BR la_symbind64 () +function is employed on 64-bit platforms. +.PP +The +.I sym +argument is a pointer to a structure +that provides information about the symbol being bound. +The structure definition is shown in +.IR . +Among the fields of this structure, +.I st_value +indicates the address to which the symbol is bound. +.PP +The +.I ndx +argument gives the index of the symbol in the symbol table +of the bound shared object. +.PP +The +.I refcook +argument identifies the shared object that is making the symbol reference; +this is the same identifier that is provided to the +.BR la_objopen () +function that returned +.BR LA_FLG_BINDFROM . +The +.I defcook +argument identifies the shared object that defines the referenced symbol; +this is the same identifier that is provided to the +.BR la_objopen () +function that returned +.BR LA_FLG_BINDTO . +.PP +The +.I symname +argument points a string containing the name of the symbol. +.PP +The +.I flags +argument is a bit mask that both provides information about the symbol +and can be used to modify further auditing of this +PLT (Procedure Linkage Table) entry. +The dynamic linker may supply the following bit values in this argument: +.\" LA_SYMB_STRUCTCALL appears to be unused +.TP 22 +.B LA_SYMB_DLSYM +The binding resulted from a call to +.BR dlsym (3). +.TP +.B LA_SYMB_ALTVALUE +A previous +.BR la_symbind* () +call returned an alternate value for this symbol. +.PP +By default, if the auditing library implements +.BR la_pltenter () +and +.BR la_pltexit () +functions (see below), then these functions are invoked, after +.BR la_symbind (), +for PLT entries, each time the symbol is referenced. +.\" pltenter/pltexit are called for non-dynamically loaded libraries, +.\" but don't seem to be called for dynamically loaded libs? +.\" Is this the same on Solaris? +The following flags can be ORed into +.IR *flags +to change this default behavior: +.TP 22 +.B LA_SYMB_NOPLTENTER +Don't call +.BR la_pltenter () +for this symbol. +.TP 22 +.B LA_SYMB_NOPLTEXIT +Don't call +.BR la_pltexit () +for this symbol. +.PP +The return value of +.BR la_symbind32 () +and +.BR la_symbind64 () +is the address to which control should be passed after the function returns. +If the auditing library is simply monitoring symbol bindings, +then it should return +.IR sym\->st_value . +A different value may be returned if the library wishes to direct control +to an alternate location. +.SS la_pltenter() +The precise name and argument types for this function +depend on the hardware platform. +(The appropriate definition is supplied by +.IR .) +Here is the definition for x86-32: +.PP +.nf +.BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx , +.BI " uintptr_t *" refcook ", uintptr_t *" defcook , +.BI " La_i86_regs *" regs ", unsigned int *" flags , +.BI " const char *" symname ", long int *" framesizep ); +.fi +.PP +This function is invoked just before a PLT entry is called, +between two shared objects that have been marked for binding notification. +.PP +The +.IR sym , +.IR ndx , +.IR refcook , +.IR defcook , +and +.IR symname +are as for +.BR la_symbind* (). +.PP +The +.I regs +argument points to a structure (defined in +.IR ) +containing the values of registers to be used for +the call to this PLT entry. +.PP +The +.I flags +argument points to a bit mask that conveys information about, +and can be used to modify subsequent auditing of, this PLT entry, as for +.BR la_symbind* (). +.PP +.\" FIXME . Is the following correct? +The +.IR framesizep +argument points to a +.IR "long\ int" +buffer that can be used to explicitly set the frame size +used for the call to this PLT entry. +If different +.BR la_pltenter () +invocations for this symbol return different values, +then the maximum returned value is used. +The +.BR la_pltexit () +function is called only if this buffer is +explicitly set to a suitable value. +.PP +The return value of +.BR la_pltenter () +is as for +.BR la_symbind* (). +.SS la_pltexit() +The precise name and argument types for this function +depend on the hardware platform. +(The appropriate definition is supplied by +.IR .) +Here is the definition for x86-32: +.PP +.nf +.BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx , +.BI " uintptr_t *" refcook ", uintptr_t *" defcook , +.BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs , +.BI " const char *" symname ); +.fi +.PP +This function is called when a PLT entry, +made between two shared objects that have been marked +for binding notification, returns. +The function is called just before control returns to the caller +of the PLT entry. +.PP +The +.IR sym , +.IR ndx , +.IR refcook , +.IR defcook , +and +.IR symname +are as for +.BR la_symbind* (). +.PP +The +.I inregs +argument points to a structure (defined in +.IR ) +containing the values of registers used for the call to this PLT entry. +The +.I outregs +argument points to a structure (defined in +.IR ) +containing return values for the call to this PLT entry. +These values can be modified by the caller, +and the changes will be visible to the caller of the PLT entry. +.PP +In the current GNU implementation, the return value of +.BR la_pltexit () +is ignored. +.\" This differs from Solaris, where an audit library that monitors +.\" symbol binding should return the value of the 'retval' argument +.\" (not provided by GNU, but equivalent to returning outregs->lrv_eax +.\" on (say) x86-32). +.SH CONFORMING TO +This API is nonstandard, but very similar to the Solaris API, +described in the Solaris +.IR "Linker and Libraries Guide" , +in the chapter +.IR "Runtime Linker Auditing Interface" . +.SH NOTES +Note the following differences from the Solaris dynamic linker +auditing API: +.IP * 3 +The Solaris +.BR la_objfilter () +interface is not supported by the GNU implementation. +.IP * +The Solaris +.BR la_symbind32 () +and +.BR la_pltexit () +functions do not provide a +.I symname +argument. +.IP * +The Solaris +.BR la_pltexit () +function does not provide +.I inregs +and +.I outregs +arguments (but does provide a +.IR retval +argument with the function return value). +.SH BUGS +In glibc versions up to and include 2.9, +specifying more than one audit library in +.B LD_AUDIT +results in a run-time crash. +This is reportedly fixed in glibc 2.10. +.\" FIXME . Specifying multiple audit libraries doesn't work on GNU. +.\" My simple tests on Solaris work okay, but not on Linux -- mtk, Jan 2009 +.\" glibc bug filed: http://sourceware.org/bugzilla/show_bug.cgi?id=9733 +.\" Reportedly, this is fixed on 16 Mar 2009 (i.e., for glibc 2.10) +.SH EXAMPLE +.EX +#include +#include + +unsigned int +la_version(unsigned int version) +{ + printf("la_version(): %d\\n", version); + + return version; +} + +char * +la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag) +{ + printf("la_objsearch(): name = %s; cookie = %p", name, cookie); + printf("; flag = %s\\n", + (flag == LA_SER_ORIG) ? "LA_SER_ORIG" : + (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" : + (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" : + (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" : + (flag == LA_SER_CONFIG) ? "LA_SER_CONFIG" : + (flag == LA_SER_SECURE) ? "LA_SER_SECURE" : + "???"); + + return name; +} + +void +la_activity (uintptr_t *cookie, unsigned int flag) +{ + printf("la_activity(): cookie = %p; flag = %s\\n", cookie, + (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" : + (flag == LA_ACT_ADD) ? "LA_ACT_ADD" : + (flag == LA_ACT_DELETE) ? "LA_ACT_DELETE" : + "???"); +} + +unsigned int +la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie) +{ + printf("la_objopen(): loading \\"%s\\"; lmid = %s; cookie=%p\\n", + map\->l_name, + (lmid == LM_ID_BASE) ? "LM_ID_BASE" : + (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" : + "???", + cookie); + + return LA_FLG_BINDTO | LA_FLG_BINDFROM; +} + +unsigned int +la_objclose (uintptr_t *cookie) +{ + printf("la_objclose(): %p\\n", cookie); + + return 0; +} + +void +la_preinit(uintptr_t *cookie) +{ + printf("la_preinit(): %p\\n", cookie); +} + +uintptr_t +la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook, + uintptr_t *defcook, unsigned int *flags, const char *symname) +{ + printf("la_symbind32(): symname = %s; sym\->st_value = %p\\n", + symname, sym\->st_value); + printf(" ndx = %d; flags = 0x%x", ndx, *flags); + printf("; refcook = %p; defcook = %p\\n", refcook, defcook); + + return sym\->st_value; +} + +uintptr_t +la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook, + uintptr_t *defcook, unsigned int *flags, const char *symname) +{ + printf("la_symbind64(): symname = %s; sym\->st_value = %p\\n", + symname, sym\->st_value); + printf(" ndx = %d; flags = 0x%x", ndx, *flags); + printf("; refcook = %p; defcook = %p\\n", refcook, defcook); + + return sym\->st_value; +} + +Elf32_Addr +la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx, + uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs, + unsigned int *flags, const char *symname, long int *framesizep) +{ + printf("la_i86_gnu_pltenter(): %s (%p)\\n", symname, sym\->st_value); + + return sym\->st_value; +} +.EE +.SH SEE ALSO +.BR ldd (1), +.BR dlopen (3), +.BR ld.so (8), +.BR ldconfig (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/rtnetlink.7 b/man7/rtnetlink.7 new file mode 100644 index 0000000..db309e1 --- /dev/null +++ b/man7/rtnetlink.7 @@ -0,0 +1,473 @@ +'\" t +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" Based on the original comments from Alexey Kuznetsov, written with +.\" help from Matthew Wilcox. +.\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ +.\" +.TH RTNETLINK 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +rtnetlink \- Linux IPv4 routing socket +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);" +.SH DESCRIPTION +Rtnetlink allows the kernel's routing tables to be read and altered. +It is used within the kernel to communicate between +various subsystems, though this usage is not documented here, and for +communication with user-space programs. +Network routes, IP addresses, link parameters, neighbor setups, queueing +disciplines, traffic classes and packet classifiers may all be controlled +through +.B NETLINK_ROUTE +sockets. +It is based on netlink messages; see +.BR netlink (7) +for more information. +.\" FIXME . ? all these macros could be moved to rtnetlink(3) +.SS Routing attributes +Some rtnetlink messages have optional attributes after the initial header: +.PP +.in +4n +.EX +struct rtattr { + unsigned short rta_len; /* Length of option */ + unsigned short rta_type; /* Type of option */ + /* Data follows */ +}; +.EE +.in +.PP +These attributes should be manipulated using only the RTA_* macros +or libnetlink, see +.BR rtnetlink (3). +.SS Messages +Rtnetlink consists of these message types +(in addition to standard netlink messages): +.TP +.BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK +Create, remove or get information about a specific network interface. +These messages contain an +.I ifinfomsg +structure followed by a series of +.I rtattr +structures. +.IP +.EX +struct ifinfomsg { + unsigned char ifi_family; /* AF_UNSPEC */ + unsigned short ifi_type; /* Device type */ + int ifi_index; /* Interface index */ + unsigned int ifi_flags; /* Device flags */ + unsigned int ifi_change; /* change mask */ +}; +.EE +.IP +.\" FIXME Document ifinfomsg.ifi_type +.I ifi_flags +contains the device flags, see +.BR netdevice (7); +.I ifi_index +is the unique interface index +(since Linux 3.7, it is possible to feed a nonzero value with the +.B RTM_NEWLINK +message, thus creating a link with the given +.IR ifindex ); +.I ifi_change +is reserved for future use and should be always set to 0xFFFFFFFF. +.TS +tab(:); +c s s +l l l. +Routing attributes +rta_type:value type:description +_ +IFLA_UNSPEC:-:unspecified. +IFLA_ADDRESS:hardware address:interface L2 address +IFLA_BROADCAST:hardware address:L2 broadcast address. +IFLA_IFNAME:asciiz string:Device name. +IFLA_MTU:unsigned int:MTU of the device. +IFLA_LINK:int:Link type. +IFLA_QDISC:asciiz string:Queueing discipline. +IFLA_STATS:T{ +see below +T}:Interface Statistics. +.TE +.PP +The value type for +.B IFLA_STATS +is +.IR "struct rtnl_link_stats" +.RI ( "struct net_device_stats" +in Linux 2.4 and earlier). +.TP +.BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR +Add, remove or receive information about an IP address associated with +an interface. +In Linux 2.2, an interface can carry multiple IP addresses, +this replaces the alias device concept in 2.0. +In Linux 2.2, these messages +support IPv4 and IPv6 addresses. +They contain an +.I ifaddrmsg +structure, optionally followed by +.I rtattr +routing attributes. +.IP +.EX +struct ifaddrmsg { + unsigned char ifa_family; /* Address type */ + unsigned char ifa_prefixlen; /* Prefixlength of address */ + unsigned char ifa_flags; /* Address flags */ + unsigned char ifa_scope; /* Address scope */ + int ifa_index; /* Interface index */ +}; +.EE +.IP +.I ifa_family +is the address family type (currently +.B AF_INET +or +.BR AF_INET6 ), +.I ifa_prefixlen +is the length of the address mask of the address if defined for the +family (like for IPv4), +.I ifa_scope +is the address scope, +.I ifa_index +is the interface index of the interface the address is associated with. +.I ifa_flags +is a flag word of +.B IFA_F_SECONDARY +for secondary address (old alias interface), +.B IFA_F_PERMANENT +for a permanent address set by the user and other undocumented flags. +.TS +tab(:); +c s s +l l l. +Attributes +rta_type:value type:description +_ +IFA_UNSPEC:-:unspecified. +IFA_ADDRESS:raw protocol address:interface address +IFA_LOCAL:raw protocol address:local address +IFA_LABEL:asciiz string:name of the interface +IFA_BROADCAST:raw protocol address:broadcast address. +IFA_ANYCAST:raw protocol address:anycast address +IFA_CACHEINFO:struct ifa_cacheinfo:Address information. +.TE +.\" FIXME Document struct ifa_cacheinfo +.TP +.BR RTM_NEWROUTE ", " RTM_DELROUTE ", " RTM_GETROUTE +Create, remove or receive information about a network route. +These messages contain an +.I rtmsg +structure with an optional sequence of +.I rtattr +structures following. +For +.BR RTM_GETROUTE , +setting +.I rtm_dst_len +and +.I rtm_src_len +to 0 means you get all entries for the specified routing table. +For the other fields, except +.I rtm_table +and +.IR rtm_protocol , +0 is the wildcard. +.IP +.EX +struct rtmsg { + unsigned char rtm_family; /* Address family of route */ + unsigned char rtm_dst_len; /* Length of destination */ + unsigned char rtm_src_len; /* Length of source */ + unsigned char rtm_tos; /* TOS filter */ + + unsigned char rtm_table; /* Routing table ID */ + unsigned char rtm_protocol; /* Routing protocol; see below */ + unsigned char rtm_scope; /* See below */ + unsigned char rtm_type; /* See below */ + + unsigned int rtm_flags; +}; +.EE +.TS +tab(:); +l l. +rtm_type:Route type +_ +RTN_UNSPEC:unknown route +RTN_UNICAST:a gateway or direct route +RTN_LOCAL:a local interface route +RTN_BROADCAST:T{ +a local broadcast route (sent as a broadcast) +T} +RTN_ANYCAST:T{ +a local broadcast route (sent as a unicast) +T} +RTN_MULTICAST:a multicast route +RTN_BLACKHOLE:a packet dropping route +RTN_UNREACHABLE:an unreachable destination +RTN_PROHIBIT:a packet rejection route +RTN_THROW:continue routing lookup in another table +RTN_NAT:a network address translation rule +RTN_XRESOLVE:T{ +refer to an external resolver (not implemented) +T} +.TE +.TS +tab(:); +l l. +rtm_protocol:Route origin. +_ +RTPROT_UNSPEC:unknown +RTPROT_REDIRECT:T{ +by an ICMP redirect (currently unused) +T} +RTPROT_KERNEL:by the kernel +RTPROT_BOOT:during boot +RTPROT_STATIC:by the administrator +.TE +.sp 1 +Values larger than +.B RTPROT_STATIC +are not interpreted by the kernel, they are just for user information. +They may be used to tag the source of a routing information or to +distinguish between multiple routing daemons. +See +.I +for the routing daemon identifiers which are already assigned. +.IP +.I rtm_scope +is the distance to the destination: +.TS +tab(:); +l l. +RT_SCOPE_UNIVERSE:global route +RT_SCOPE_SITE:T{ +interior route in the local autonomous system +T} +RT_SCOPE_LINK:route on this link +RT_SCOPE_HOST:route on the local host +RT_SCOPE_NOWHERE:destination doesn't exist +.TE +.sp 1 +The values between +.B RT_SCOPE_UNIVERSE +and +.B RT_SCOPE_SITE +are available to the user. +.IP +The +.I rtm_flags +have the following meanings: +.TS +tab(:); +l l. +RTM_F_NOTIFY:T{ +if the route changes, notify the user via rtnetlink +T} +RTM_F_CLONED:route is cloned from another route +RTM_F_EQUALIZE:a multipath equalizer (not yet implemented) +.TE +.sp 1 +.I rtm_table +specifies the routing table +.TS +tab(:); +l l. +RT_TABLE_UNSPEC:an unspecified routing table +RT_TABLE_DEFAULT:the default table +RT_TABLE_MAIN:the main table +RT_TABLE_LOCAL:the local table +.TE +.sp 1 +The user may assign arbitrary values between +.B RT_TABLE_UNSPEC +and +.BR RT_TABLE_DEFAULT . +.\" Keep table on same page +.bp +1 +.TS +tab(:); +c s s +l l l. +Attributes +rta_type:value type:description +_ +RTA_UNSPEC:-:ignored. +RTA_DST:protocol address:Route destination address. +RTA_SRC:protocol address:Route source address. +RTA_IIF:int:Input interface index. +RTA_OIF:int:Output interface index. +RTA_GATEWAY:protocol address:The gateway of the route +RTA_PRIORITY:int:Priority of route. +RTA_PREFSRC:: +RTA_METRICS:int:Route metric +RTA_MULTIPATH:: +RTA_PROTOINFO:: +RTA_FLOW:: +RTA_CACHEINFO:: +.TE +.sp 1 +.B Fill these values in! +.TP +.BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH +Add, remove or receive information about a neighbor table +entry (e.g., an ARP entry). +The message contains an +.I ndmsg +structure. +.IP +.EX +struct ndmsg { + unsigned char ndm_family; + int ndm_ifindex; /* Interface index */ + __u16 ndm_state; /* State */ + __u8 ndm_flags; /* Flags */ + __u8 ndm_type; +}; + +struct nda_cacheinfo { + __u32 ndm_confirmed; + __u32 ndm_used; + __u32 ndm_updated; + __u32 ndm_refcnt; +}; +.EE +.IP +.I ndm_state +is a bit mask of the following states: +.TS +tab(:); +l l. +NUD_INCOMPLETE:a currently resolving cache entry +NUD_REACHABLE:a confirmed working cache entry +NUD_STALE:an expired cache entry +NUD_DELAY:an entry waiting for a timer +NUD_PROBE:a cache entry that is currently reprobed +NUD_FAILED:an invalid cache entry +NUD_NOARP:a device with no destination cache +NUD_PERMANENT:a static entry +.TE +.sp 1 +Valid +.I ndm_flags +are: +.TS +tab(:); +l l. +NTF_PROXY:a proxy arp entry +NTF_ROUTER:an IPv6 router +.TE +.sp 1 +.\" FIXME . +.\" document the members of the struct better +The +.I rtattr +struct has the following meanings for the +.I rta_type +field: +.TS +tab(:); +l l. +NDA_UNSPEC:unknown type +NDA_DST:a neighbor cache n/w layer destination address +NDA_LLADDR:a neighbor cache link layer address +NDA_CACHEINFO:cache statistics. +.TE +.sp 1 +If the +.I rta_type +field is +.BR NDA_CACHEINFO , +then a +.I struct nda_cacheinfo +header follows +.TP +.BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE +Add, delete or retrieve a routing rule. +Carries a +.I struct rtmsg +.TP +.BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC +Add, remove or get a queueing discipline. +The message contains a +.I struct tcmsg +and may be followed by a series of +attributes. +.IP +.EX +struct tcmsg { + unsigned char tcm_family; + int tcm_ifindex; /* interface index */ + __u32 tcm_handle; /* Qdisc handle */ + __u32 tcm_parent; /* Parent qdisc */ + __u32 tcm_info; +}; +.EE +.TS +tab(:); +c s s +l2 l2 l. +Attributes +rta_type:value type:Description +_ +TCA_UNSPEC:-:unspecified +TCA_KIND:asciiz string:Name of queueing discipline +TCA_OPTIONS:byte sequence:Qdisc-specific options follow +TCA_STATS:struct tc_stats:Qdisc statistics. +TCA_XSTATS:qdisc-specific:Module-specific statistics. +TCA_RATE:struct tc_estimator:Rate limit. +.TE +.sp 1 +In addition, various other qdisc-module-specific attributes are allowed. +For more information see the appropriate include files. +.TP +.BR RTM_NEWTCLASS ", " RTM_DELTCLASS ", " RTM_GETTCLASS +Add, remove or get a traffic class. +These messages contain a +.I struct tcmsg +as described above. +.TP +.BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER +Add, remove or receive information about a traffic filter. +These messages contain a +.I struct tcmsg +as described above. +.SH VERSIONS +.B rtnetlink +is a new feature of Linux 2.2. +.SH BUGS +This manual page is incomplete. +.SH SEE ALSO +.BR cmsg (3), +.BR rtnetlink (3), +.BR ip (7), +.BR netlink (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/sched.7 b/man7/sched.7 new file mode 100644 index 0000000..feacbe6 --- /dev/null +++ b/man7/sched.7 @@ -0,0 +1,1007 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 Peter Zijlstra +.\" and Copyright (C) 2014 Juri Lelli +.\" Various pieces from the old sched_setscheduler(2) page +.\" Copyright (C) Tom Bjorkholm, Markus Kuhn & David A. Wheeler 1996-1999 +.\" and Copyright (C) 2007 Carsten Emde +.\" and Copyright (C) 2008 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Worth looking at: http://rt.wiki.kernel.org/index.php +.\" +.TH SCHED 7 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +sched \- overview of CPU scheduling +.SH DESCRIPTION +Since Linux 2.6.23, the default scheduler is CFS, +the "Completely Fair Scheduler". +The CFS scheduler replaced the earlier "O(1)" scheduler. +.\" +.SS API summary +Linux provides the following system calls for controlling +the CPU scheduling behavior, policy, and priority of processes +(or, more precisely, threads). +.TP +.BR nice (2) +Set a new nice value for the calling thread, +and return the new nice value. +.TP +.BR getpriority (2) +Return the nice value of a thread, a process group, +or the set of threads owned by a specified user. +.TP +.BR setpriority (2) +Set the nice value of a thread, a process group, +or the set of threads owned by a specified user. +.TP +.BR sched_setscheduler (2) +Set the scheduling policy and parameters of a specified thread. +.TP +.BR sched_getscheduler (2) +Return the scheduling policy of a specified thread. +.TP +.BR sched_setparam (2) +Set the scheduling parameters of a specified thread. +.TP +.BR sched_getparam (2) +Fetch the scheduling parameters of a specified thread. +.TP +.BR sched_get_priority_max (2) +Return the maximum priority available in a specified scheduling policy. +.TP +.BR sched_get_priority_min (2) +Return the minimum priority available in a specified scheduling policy. +.TP +.BR sched_rr_get_interval (2) +Fetch the quantum used for threads that are scheduled under +the "round-robin" scheduling policy. +.TP +.BR sched_yield (2) +Cause the caller to relinquish the CPU, +so that some other thread be executed. +.TP +.BR sched_setaffinity (2) +(Linux-specific) +Set the CPU affinity of a specified thread. +.TP +.BR sched_getaffinity (2) +(Linux-specific) +Get the CPU affinity of a specified thread. +.TP +.BR sched_setattr (2) +Set the scheduling policy and parameters of a specified thread. +This (Linux-specific) system call provides a superset of the functionality of +.BR sched_setscheduler (2) +and +.BR sched_setparam (2). +.TP +.BR sched_getattr (2) +Fetch the scheduling policy and parameters of a specified thread. +This (Linux-specific) system call provides a superset of the functionality of +.BR sched_getscheduler (2) +and +.BR sched_getparam (2). +.\" +.SS Scheduling policies +The scheduler is the kernel component that decides which runnable thread +will be executed by the CPU next. +Each thread has an associated scheduling policy and a \fIstatic\fP +scheduling priority, +.IR sched_priority . +The scheduler makes its decisions based on knowledge of the scheduling +policy and static priority of all threads on the system. +.PP +For threads scheduled under one of the normal scheduling policies +(\fBSCHED_OTHER\fP, \fBSCHED_IDLE\fP, \fBSCHED_BATCH\fP), +\fIsched_priority\fP is not used in scheduling +decisions (it must be specified as 0). +.PP +Processes scheduled under one of the real-time policies +(\fBSCHED_FIFO\fP, \fBSCHED_RR\fP) have a +\fIsched_priority\fP value in the range 1 (low) to 99 (high). +(As the numbers imply, real-time threads always have higher priority +than normal threads.) +Note well: POSIX.1 requires an implementation to support only a +minimum 32 distinct priority levels for the real-time policies, +and some systems supply just this minimum. +Portable programs should use +.BR sched_get_priority_min (2) +and +.BR sched_get_priority_max (2) +to find the range of priorities supported for a particular policy. +.PP +Conceptually, the scheduler maintains a list of runnable +threads for each possible \fIsched_priority\fP value. +In order to determine which thread runs next, the scheduler looks for +the nonempty list with the highest static priority and selects the +thread at the head of this list. +.PP +A thread's scheduling policy determines +where it will be inserted into the list of threads +with equal static priority and how it will move inside this list. +.PP +All scheduling is preemptive: if a thread with a higher static +priority becomes ready to run, the currently running thread +will be preempted and +returned to the wait list for its static priority level. +The scheduling policy determines the +ordering only within the list of runnable threads with equal static +priority. +.SS SCHED_FIFO: First in-first out scheduling +\fBSCHED_FIFO\fP can be used only with static priorities higher than +0, which means that when a \fBSCHED_FIFO\fP threads becomes runnable, +it will always immediately preempt any currently running +\fBSCHED_OTHER\fP, \fBSCHED_BATCH\fP, or \fBSCHED_IDLE\fP thread. +\fBSCHED_FIFO\fP is a simple scheduling +algorithm without time slicing. +For threads scheduled under the +\fBSCHED_FIFO\fP policy, the following rules apply: +.IP 1) 3 +A running \fBSCHED_FIFO\fP thread that has been preempted by another thread of +higher priority will stay at the head of the list for its priority and +will resume execution as soon as all threads of higher priority are +blocked again. +.IP 2) +When a blocked \fBSCHED_FIFO\fP thread becomes runnable, it +will be inserted at the end of the list for its priority. +.IP 3) +If a call to +.BR sched_setscheduler (2), +.BR sched_setparam (2), +.BR sched_setattr (2), +.BR pthread_setschedparam (3), +or +.BR pthread_setschedprio (3) +changes the priority of the running or runnable +.B SCHED_FIFO +thread identified by +.I pid +the effect on the thread's position in the list depends on +the direction of the change to threads priority: +.RS +.IP \(bu 3 +If the thread's priority is raised, +it is placed at the end of the list for its new priority. +As a consequence, +it may preempt a currently running thread with the same priority. +.IP \(bu +If the thread's priority is unchanged, +its position in the run list is unchanged. +.IP \(bu +If the thread's priority is lowered, +it is placed at the front of the list for its new priority. +.RE +.IP +According to POSIX.1-2008, +changes to a thread's priority (or policy) using any mechanism other than +.BR pthread_setschedprio (3) +should result in the thread being placed at the end of +the list for its priority. +.\" In 2.2.x and 2.4.x, the thread is placed at the front of the queue +.\" In 2.0.x, the Right Thing happened: the thread went to the back -- MTK +.IP 4) +A thread calling +.BR sched_yield (2) +will be put at the end of the list. +.PP +No other events will move a thread +scheduled under the \fBSCHED_FIFO\fP policy in the wait list of +runnable threads with equal static priority. +.PP +A \fBSCHED_FIFO\fP +thread runs until either it is blocked by an I/O request, it is +preempted by a higher priority thread, or it calls +.BR sched_yield (2). +.SS SCHED_RR: Round-robin scheduling +\fBSCHED_RR\fP is a simple enhancement of \fBSCHED_FIFO\fP. +Everything +described above for \fBSCHED_FIFO\fP also applies to \fBSCHED_RR\fP, +except that each thread is allowed to run only for a maximum time +quantum. +If a \fBSCHED_RR\fP thread has been running for a time +period equal to or longer than the time quantum, it will be put at the +end of the list for its priority. +A \fBSCHED_RR\fP thread that has +been preempted by a higher priority thread and subsequently resumes +execution as a running thread will complete the unexpired portion of +its round-robin time quantum. +The length of the time quantum can be +retrieved using +.BR sched_rr_get_interval (2). +.\" On Linux 2.4, the length of the RR interval is influenced +.\" by the process nice value -- MTK +.\" +.SS SCHED_DEADLINE: Sporadic task model deadline scheduling +Since version 3.14, Linux provides a deadline scheduling policy +.RB ( SCHED_DEADLINE ). +This policy is currently implemented using +GEDF (Global Earliest Deadline First) +in conjunction with CBS (Constant Bandwidth Server). +To set and fetch this policy and associated attributes, +one must use the Linux-specific +.BR sched_setattr (2) +and +.BR sched_getattr (2) +system calls. +.PP +A sporadic task is one that has a sequence of jobs, where each +job is activated at most once per period. +Each job also has a +.IR "relative deadline" , +before which it should finish execution, and a +.IR "computation time" , +which is the CPU time necessary for executing the job. +The moment when a task wakes up +because a new job has to be executed is called the +.IR "arrival time" +(also referred to as the request time or release time). +The +.IR "start time" +is the time at which a task starts its execution. +The +.I "absolute deadline" +is thus obtained by adding the relative deadline to the arrival time. +.PP +The following diagram clarifies these terms: +.PP +.in +4n +.EX +arrival/wakeup absolute deadline + | start time | + | | | + v v v +-----x--------xooooooooooooooooo--------x--------x--- + |<- comp. time ->| + |<------- relative deadline ------>| + |<-------------- period ------------------->| +.EE +.in +.PP +When setting a +.B SCHED_DEADLINE +policy for a thread using +.BR sched_setattr (2), +one can specify three parameters: +.IR Runtime , +.IR Deadline , +and +.IR Period . +These parameters do not necessarily correspond to the aforementioned terms: +usual practice is to set Runtime to something bigger than the average +computation time (or worst-case execution time for hard real-time tasks), +Deadline to the relative deadline, and Period to the period of the task. +Thus, for +.BR SCHED_DEADLINE +scheduling, we have: +.PP +.in +4n +.EX +arrival/wakeup absolute deadline + | start time | + | | | + v v v +-----x--------xooooooooooooooooo--------x--------x--- + |<-- Runtime ------->| + |<----------- Deadline ----------->| + |<-------------- Period ------------------->| +.EE +.in +.PP +The three deadline-scheduling parameters correspond to the +.IR sched_runtime , +.IR sched_deadline , +and +.IR sched_period +fields of the +.I sched_attr +structure; see +.BR sched_setattr (2). +These fields express values in nanoseconds. +.\" FIXME It looks as though specifying sched_period as 0 means +.\" "make sched_period the same as sched_deadline". +.\" This needs to be documented. +If +.IR sched_period +is specified as 0, then it is made the same as +.IR sched_deadline . +.PP +The kernel requires that: +.PP + sched_runtime <= sched_deadline <= sched_period +.PP +.\" See __checkparam_dl in kernel/sched/core.c +In addition, under the current implementation, +all of the parameter values must be at least 1024 +(i.e., just over one microsecond, +which is the resolution of the implementation), and less than 2^63. +If any of these checks fails, +.BR sched_setattr (2) +fails with the error +.BR EINVAL . +.PP +The CBS guarantees non-interference between tasks, by throttling +threads that attempt to over-run their specified Runtime. +.PP +To ensure deadline scheduling guarantees, +the kernel must prevent situations where the set of +.B SCHED_DEADLINE +threads is not feasible (schedulable) within the given constraints. +The kernel thus performs an admittance test when setting or changing +.B SCHED_DEADLINE +policy and attributes. +This admission test calculates whether the change is feasible; +if it is not, +.BR sched_setattr (2) +fails with the error +.BR EBUSY . +.PP +For example, it is required (but not necessarily sufficient) for +the total utilization to be less than or equal to the total number of +CPUs available, where, since each thread can maximally run for +Runtime per Period, that thread's utilization is its +Runtime divided by its Period. +.PP +In order to fulfill the guarantees that are made when +a thread is admitted to the +.BR SCHED_DEADLINE +policy, +.BR SCHED_DEADLINE +threads are the highest priority (user controllable) threads in the +system; if any +.BR SCHED_DEADLINE +thread is runnable, +it will preempt any thread scheduled under one of the other policies. +.PP +A call to +.BR fork (2) +by a thread scheduled under the +.B SCHED_DEADLINE +policy fails with the error +.BR EAGAIN , +unless the thread has its reset-on-fork flag set (see below). +.PP +A +.B SCHED_DEADLINE +thread that calls +.BR sched_yield (2) +will yield the current job and wait for a new period to begin. +.\" +.\" FIXME Calling sched_getparam() on a SCHED_DEADLINE thread +.\" fails with EINVAL, but sched_getscheduler() succeeds. +.\" Is that intended? (Why?) +.\" +.SS SCHED_OTHER: Default Linux time-sharing scheduling +\fBSCHED_OTHER\fP can be used at only static priority 0 +(i.e., threads under real-time policies always have priority over +.B SCHED_OTHER +processes). +\fBSCHED_OTHER\fP is the standard Linux time-sharing scheduler that is +intended for all threads that do not require the special +real-time mechanisms. +.PP +The thread to run is chosen from the static +priority 0 list based on a \fIdynamic\fP priority that is determined only +inside this list. +The dynamic priority is based on the nice value (see below) +and is increased for each time quantum the thread is ready to run, +but denied to run by the scheduler. +This ensures fair progress among all \fBSCHED_OTHER\fP threads. +.\" +.SS The nice value +The nice value is an attribute +that can be used to influence the CPU scheduler to +favor or disfavor a process in scheduling decisions. +It affects the scheduling of +.BR SCHED_OTHER +and +.BR SCHED_BATCH +(see below) processes. +The nice value can be modified using +.BR nice (2), +.BR setpriority (2), +or +.BR sched_setattr (2). +.PP +According to POSIX.1, the nice value is a per-process attribute; +that is, the threads in a process should share a nice value. +However, on Linux, the nice value is a per-thread attribute: +different threads in the same process may have different nice values. +.PP +The range of the nice value +varies across UNIX systems. +On modern Linux, the range is \-20 (high priority) to +19 (low priority). +On some other systems, the range is \-20..20. +Very early Linux kernels (Before Linux 2.0) had the range \-infinity..15. +.\" Linux before 1.3.36 had \-infinity..15. +.\" Since kernel 1.3.43, Linux has the range \-20..19. +.PP +The degree to which the nice value affects the relative scheduling of +.BR SCHED_OTHER +processes likewise varies across UNIX systems and +across Linux kernel versions. +.PP +With the advent of the CFS scheduler in kernel 2.6.23, +Linux adopted an algorithm that causes +relative differences in nice values to have a much stronger effect. +In the current implementation, each unit of difference in the +nice values of two processes results in a factor of 1.25 +in the degree to which the scheduler favors the higher priority process. +This causes very low nice values (+19) to truly provide little CPU +to a process whenever there is any other +higher priority load on the system, +and makes high nice values (\-20) deliver most of the CPU to applications +that require it (e.g., some audio applications). +.PP +On Linux, the +.BR RLIMIT_NICE +resource limit can be used to define a limit to which +an unprivileged process's nice value can be raised; see +.BR setrlimit (2) +for details. +.PP +For further details on the nice value, see the subsections on +the autogroup feature and group scheduling, below. +.\" +.SS SCHED_BATCH: Scheduling batch processes +(Since Linux 2.6.16.) +\fBSCHED_BATCH\fP can be used only at static priority 0. +This policy is similar to \fBSCHED_OTHER\fP in that it schedules +the thread according to its dynamic priority +(based on the nice value). +The difference is that this policy +will cause the scheduler to always assume +that the thread is CPU-intensive. +Consequently, the scheduler will apply a small scheduling +penalty with respect to wakeup behavior, +so that this thread is mildly disfavored in scheduling decisions. +.PP +.\" The following paragraph is drawn largely from the text that +.\" accompanied Ingo Molnar's patch for the implementation of +.\" SCHED_BATCH. +.\" commit b0a9499c3dd50d333e2aedb7e894873c58da3785 +This policy is useful for workloads that are noninteractive, +but do not want to lower their nice value, +and for workloads that want a deterministic scheduling policy without +interactivity causing extra preemptions (between the workload's tasks). +.\" +.SS SCHED_IDLE: Scheduling very low priority jobs +(Since Linux 2.6.23.) +\fBSCHED_IDLE\fP can be used only at static priority 0; +the process nice value has no influence for this policy. +.PP +This policy is intended for running jobs at extremely low +priority (lower even than a +19 nice value with the +.B SCHED_OTHER +or +.B SCHED_BATCH +policies). +.\" +.SS Resetting scheduling policy for child processes +Each thread has a reset-on-fork scheduling flag. +When this flag is set, children created by +.BR fork (2) +do not inherit privileged scheduling policies. +The reset-on-fork flag can be set by either: +.IP * 3 +ORing the +.B SCHED_RESET_ON_FORK +flag into the +.I policy +argument when calling +.BR sched_setscheduler (2) +(since Linux 2.6.32); +or +.IP * +specifying the +.B SCHED_FLAG_RESET_ON_FORK +flag in +.IR attr.sched_flags +when calling +.BR sched_setattr (2). +.PP +Note that the constants used with these two APIs have different names. +The state of the reset-on-fork flag can analogously be retrieved using +.BR sched_getscheduler (2) +and +.BR sched_getattr (2). +.PP +The reset-on-fork feature is intended for media-playback applications, +and can be used to prevent applications evading the +.BR RLIMIT_RTTIME +resource limit (see +.BR getrlimit (2)) +by creating multiple child processes. +.PP +More precisely, if the reset-on-fork flag is set, +the following rules apply for subsequently created children: +.IP * 3 +If the calling thread has a scheduling policy of +.B SCHED_FIFO +or +.BR SCHED_RR , +the policy is reset to +.BR SCHED_OTHER +in child processes. +.IP * +If the calling process has a negative nice value, +the nice value is reset to zero in child processes. +.PP +After the reset-on-fork flag has been enabled, +it can be reset only if the thread has the +.BR CAP_SYS_NICE +capability. +This flag is disabled in child processes created by +.BR fork (2). +.\" +.SS Privileges and resource limits +In Linux kernels before 2.6.12, only privileged +.RB ( CAP_SYS_NICE ) +threads can set a nonzero static priority (i.e., set a real-time +scheduling policy). +The only change that an unprivileged thread can make is to set the +.B SCHED_OTHER +policy, and this can be done only if the effective user ID of the caller +matches the real or effective user ID of the target thread +(i.e., the thread specified by +.IR pid ) +whose policy is being changed. +.PP +A thread must be privileged +.RB ( CAP_SYS_NICE ) +in order to set or modify a +.BR SCHED_DEADLINE +policy. +.PP +Since Linux 2.6.12, the +.B RLIMIT_RTPRIO +resource limit defines a ceiling on an unprivileged thread's +static priority for the +.B SCHED_RR +and +.B SCHED_FIFO +policies. +The rules for changing scheduling policy and priority are as follows: +.IP * 3 +If an unprivileged thread has a nonzero +.B RLIMIT_RTPRIO +soft limit, then it can change its scheduling policy and priority, +subject to the restriction that the priority cannot be set to a +value higher than the maximum of its current priority and its +.B RLIMIT_RTPRIO +soft limit. +.IP * +If the +.B RLIMIT_RTPRIO +soft limit is 0, then the only permitted changes are to lower the priority, +or to switch to a non-real-time policy. +.IP * +Subject to the same rules, +another unprivileged thread can also make these changes, +as long as the effective user ID of the thread making the change +matches the real or effective user ID of the target thread. +.IP * +Special rules apply for the +.BR SCHED_IDLE +policy. +In Linux kernels before 2.6.39, +an unprivileged thread operating under this policy cannot +change its policy, regardless of the value of its +.BR RLIMIT_RTPRIO +resource limit. +In Linux kernels since 2.6.39, +.\" commit c02aa73b1d18e43cfd79c2f193b225e84ca497c8 +an unprivileged thread can switch to either the +.BR SCHED_BATCH +or the +.BR SCHED_OTHER +policy so long as its nice value falls within the range permitted by its +.BR RLIMIT_NICE +resource limit (see +.BR getrlimit (2)). +.PP +Privileged +.RB ( CAP_SYS_NICE ) +threads ignore the +.B RLIMIT_RTPRIO +limit; as with older kernels, +they can make arbitrary changes to scheduling policy and priority. +See +.BR getrlimit (2) +for further information on +.BR RLIMIT_RTPRIO . +.SS Limiting the CPU usage of real-time and deadline processes +A nonblocking infinite loop in a thread scheduled under the +.BR SCHED_FIFO , +.BR SCHED_RR , +or +.BR SCHED_DEADLINE +policy can potentially block all other threads from accessing +the CPU forever. +Prior to Linux 2.6.25, the only way of preventing a runaway real-time +process from freezing the system was to run (at the console) +a shell scheduled under a higher static priority than the tested application. +This allows an emergency kill of tested +real-time applications that do not block or terminate as expected. +.PP +Since Linux 2.6.25, there are other techniques for dealing with runaway +real-time and deadline processes. +One of these is to use the +.BR RLIMIT_RTTIME +resource limit to set a ceiling on the CPU time that +a real-time process may consume. +See +.BR getrlimit (2) +for details. +.PP +Since version 2.6.25, Linux also provides two +.I /proc +files that can be used to reserve a certain amount of CPU time +to be used by non-real-time processes. +Reserving CPU time in this fashion allows some CPU time to be +allocated to (say) a root shell that can be used to kill a runaway process. +Both of these files specify time values in microseconds: +.TP +.IR /proc/sys/kernel/sched_rt_period_us +This file specifies a scheduling period that is equivalent to +100% CPU bandwidth. +The value in this file can range from 1 to +.BR INT_MAX , +giving an operating range of 1 microsecond to around 35 minutes. +The default value in this file is 1,000,000 (1 second). +.TP +.IR /proc/sys/kernel/sched_rt_runtime_us +The value in this file specifies how much of the "period" time +can be used by all real-time and deadline scheduled processes +on the system. +The value in this file can range from \-1 to +.BR INT_MAX \-1. +Specifying \-1 makes the runtime the same as the period; +that is, no CPU time is set aside for non-real-time processes +(which was the Linux behavior before kernel 2.6.25). +The default value in this file is 950,000 (0.95 seconds), +meaning that 5% of the CPU time is reserved for processes that +don't run under a real-time or deadline scheduling policy. +.PP +.SS Response time +A blocked high priority thread waiting for I/O has a certain +response time before it is scheduled again. +The device driver writer +can greatly reduce this response time by using a "slow interrupt" +interrupt handler. +.\" as described in +.\" .BR request_irq (9). +.SS Miscellaneous +Child processes inherit the scheduling policy and parameters across a +.BR fork (2). +The scheduling policy and parameters are preserved across +.BR execve (2). +.PP +Memory locking is usually needed for real-time processes to avoid +paging delays; this can be done with +.BR mlock (2) +or +.BR mlockall (2). +.\" +.SS The autogroup feature +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +Since Linux 2.6.38, +the kernel provides a feature known as autogrouping to improve interactive +desktop performance in the face of multiprocess, CPU-intensive +workloads such as building the Linux kernel with large numbers of +parallel build processes (i.e., the +.BR make (1) +.BR \-j +flag). +.PP +This feature operates in conjunction with the +CFS scheduler and requires a kernel that is configured with +.BR CONFIG_SCHED_AUTOGROUP . +On a running system, this feature is enabled or disabled via the file +.IR /proc/sys/kernel/sched_autogroup_enabled ; +a value of 0 disables the feature, while a value of 1 enables it. +The default value in this file is 1, unless the kernel was booted with the +.IR noautogroup +parameter. +.PP +A new autogroup is created when a new session is created via +.BR setsid (2); +this happens, for example, when a new terminal window is started. +A new process created by +.BR fork (2) +inherits its parent's autogroup membership. +Thus, all of the processes in a session are members of the same autogroup. +An autogroup is automatically destroyed when the last process +in the group terminates. +.PP +When autogrouping is enabled, all of the members of an autogroup +are placed in the same kernel scheduler "task group". +The CFS scheduler employs an algorithm that equalizes the +distribution of CPU cycles across task groups. +The benefits of this for interactive desktop performance +can be described via the following example. +.PP +Suppose that there are two autogroups competing for the same CPU +(i.e., presume either a single CPU system or the use of +.BR taskset (1) +to confine all the processes to the same CPU on an SMP system). +The first group contains ten CPU-bound processes from +a kernel build started with +.IR "make\ \-j10" . +The other contains a single CPU-bound process: a video player. +The effect of autogrouping is that the two groups will +each receive half of the CPU cycles. +That is, the video player will receive 50% of the CPU cycles, +rather than just 9% of the cycles, +which would likely lead to degraded video playback. +The situation on an SMP system is more complex, +.\" Mike Galbraith, 25 Nov 2016: +.\" I'd say something more wishy-washy here, like cycles are +.\" distributed fairly across groups and leave it at that, as your +.\" detailed example is incorrect due to SMP fairness (which I don't +.\" like much because [very unlikely] worst case scenario +.\" renders a box sized group incapable of utilizing more that +.\" a single CPU total). For example, if a group of NR_CPUS +.\" size competes with a singleton, load balancing will try to give +.\" the singleton a full CPU of its very own. If groups intersect for +.\" whatever reason on say my quad lappy, distribution is 80/20 in +.\" favor of the singleton. +but the general effect is the same: +the scheduler distributes CPU cycles across task groups such that +an autogroup that contains a large number of CPU-bound processes +does not end up hogging CPU cycles at the expense of the other +jobs on the system. +.PP +A process's autogroup (task group) membership can be viewed via the file +.IR /proc/[pid]/autogroup : +.PP +.in +4n +.EX +$ \fBcat /proc/1/autogroup\fP +/autogroup-1 nice 0 +.EE +.in +.PP +This file can also be used to modify the CPU bandwidth allocated +to an autogroup. +This is done by writing a number in the "nice" range to the file +to set the autogroup's nice value. +The allowed range is from +19 (low priority) to \-20 (high priority). +(Writing values outside of this range causes +.BR write (2) +to fail with the error +.BR EINVAL .) +.\" FIXME . +.\" Because of a bug introduced in Linux 4.7 +.\" (commit 2159197d66770ec01f75c93fb11dc66df81fd45b made changes +.\" that exposed the fact that autogroup didn't call scale_load()), +.\" it happened that *all* values in this range caused a task group +.\" to be further disfavored by the scheduler, with \-20 resulting +.\" in the scheduler mildly disfavoring the task group and +19 greatly +.\" disfavoring it. +.\" +.\" A patch was posted on 23 Nov 2016 +.\" ("sched/autogroup: Fix 64bit kernel nice adjustment"; +.\" check later to see in which kernel version it lands. +.PP +The autogroup nice setting has the same meaning as the process nice value, +but applies to distribution of CPU cycles to the autogroup as a whole, +based on the relative nice values of other autogroups. +For a process inside an autogroup, the CPU cycles that it receives +will be a product of the autogroup's nice value +(compared to other autogroups) +and the process's nice value +(compared to other processes in the same autogroup. +.PP +The use of the +.BR cgroups (7) +CPU controller to place processes in cgroups other than the +root CPU cgroup overrides the effect of autogrouping. +.PP +The autogroup feature groups only processes scheduled under +non-real-time policies +.RB ( SCHED_OTHER , +.BR SCHED_BATCH , +and +.BR SCHED_IDLE ). +It does not group processes scheduled under real-time and +deadline policies. +Those processes are scheduled according to the rules described earlier. +.\" +.SS The nice value and group scheduling +When scheduling non-real-time processes (i.e., those scheduled under the +.BR SCHED_OTHER , +.BR SCHED_BATCH , +and +.BR SCHED_IDLE +policies), the CFS scheduler employs a technique known as "group scheduling", +if the kernel was configured with the +.BR CONFIG_FAIR_GROUP_SCHED +option (which is typical). +.PP +Under group scheduling, threads are scheduled in "task groups". +Task groups have a hierarchical relationship, +rooted under the initial task group on the system, +known as the "root task group". +Task groups are formed in the following circumstances: +.IP * 3 +All of the threads in a CPU cgroup form a task group. +The parent of this task group is the task group of the +corresponding parent cgroup. +.IP * +If autogrouping is enabled, +then all of the threads that are (implicitly) placed in an autogroup +(i.e., the same session, as created by +.BR setsid (2)) +form a task group. +Each new autogroup is thus a separate task group. +The root task group is the parent of all such autogroups. +.IP * +If autogrouping is enabled, then the root task group consists of +all processes in the root CPU cgroup that were not +otherwise implicitly placed into a new autogroup. +.IP * +If autogrouping is disabled, then the root task group consists of +all processes in the root CPU cgroup. +.IP * +If group scheduling was disabled (i.e., the kernel was configured without +.BR CONFIG_FAIR_GROUP_SCHED ), +then all of the processes on the system are notionally placed +in a single task group. +.PP +Under group scheduling, +a thread's nice value has an effect for scheduling decisions +.IR "only relative to other threads in the same task group" . +This has some surprising consequences in terms of the traditional semantics +of the nice value on UNIX systems. +In particular, if autogrouping +is enabled (which is the default in various distributions), then employing +.BR setpriority (2) +or +.BR nice (1) +on a process has an effect only for scheduling relative +to other processes executed in the same session +(typically: the same terminal window). +.PP +Conversely, for two processes that are (for example) +the sole CPU-bound processes in different sessions +(e.g., different terminal windows, +each of whose jobs are tied to different autogroups), +.IR "modifying the nice value of the process in one of the sessions" +.IR "has no effect" +in terms of the scheduler's decisions relative to the +process in the other session. +.\" More succinctly: the nice(1) command is in many cases a no-op since +.\" Linux 2.6.38. +.\" +A possibly useful workaround here is to use a command such as +the following to modify the autogroup nice value for +.I all +of the processes in a terminal session: +.PP +.in +4n +.EX +$ \fBecho 10 > /proc/self/autogroup\fP +.EE +.in +.SS Real-time features in the mainline Linux kernel +.\" FIXME . Probably this text will need some minor tweaking +.\" ask Carsten Emde about this. +Since kernel version 2.6.18, Linux is gradually +becoming equipped with real-time capabilities, +most of which are derived from the former +.I realtime-preempt +patch set. +Until the patches have been completely merged into the +mainline kernel, +they must be installed to achieve the best real-time performance. +These patches are named: +.PP +.in +4n +.EX +patch-\fIkernelversion\fP-rt\fIpatchversion\fP +.EE +.in +.PP +and can be downloaded from +.UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/ +.UE . +.PP +Without the patches and prior to their full inclusion into the mainline +kernel, the kernel configuration offers only the three preemption classes +.BR CONFIG_PREEMPT_NONE , +.BR CONFIG_PREEMPT_VOLUNTARY , +and +.B CONFIG_PREEMPT_DESKTOP +which respectively provide no, some, and considerable +reduction of the worst-case scheduling latency. +.PP +With the patches applied or after their full inclusion into the mainline +kernel, the additional configuration item +.B CONFIG_PREEMPT_RT +becomes available. +If this is selected, Linux is transformed into a regular +real-time operating system. +The FIFO and RR scheduling policies are then used to run a thread +with true real-time priority and a minimum worst-case scheduling latency. +.SH NOTES +The +.BR cgroups (7) +CPU controller can be used to limit the CPU consumption of +groups of processes. +.PP +Originally, Standard Linux was intended as a general-purpose operating +system being able to handle background processes, interactive +applications, and less demanding real-time applications (applications that +need to usually meet timing deadlines). +Although the Linux kernel 2.6 +allowed for kernel preemption and the newly introduced O(1) scheduler +ensures that the time needed to schedule is fixed and deterministic +irrespective of the number of active tasks, true real-time computing +was not possible up to kernel version 2.6.17. +.SH SEE ALSO +.ad l +.nh +.BR chrt (1), +.BR taskset (1), +.BR getpriority (2), +.BR mlock (2), +.BR mlockall (2), +.BR munlock (2), +.BR munlockall (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getparam (2), +.BR sched_getscheduler (2), +.BR sched_rr_get_interval (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR sched_yield (2), +.BR setpriority (2), +.BR pthread_getaffinity_np (3), +.BR pthread_setaffinity_np (3), +.BR sched_getcpu (3), +.BR capabilities (7), +.BR cpuset (7) +.ad +.PP +.I Programming for the real world \- POSIX.4 +by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0. +.PP +The Linux kernel source files +.IR Documentation/scheduler/sched-deadline.txt , +.IR Documentation/scheduler/sched-rt-group.txt , +.IR Documentation/scheduler/sched-design-CFS.txt , +and +.IR Documentation/scheduler/sched-nice-design.txt +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/sem_overview.7 b/man7/sem_overview.7 new file mode 100644 index 0000000..948358b --- /dev/null +++ b/man7/sem_overview.7 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SEM_OVERVIEW 7 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +sem_overview \- overview of POSIX semaphores +.SH DESCRIPTION +POSIX semaphores allow processes and threads to synchronize their actions. +.PP +A semaphore is an integer whose value is never allowed to fall below zero. +Two operations can be performed on semaphores: +increment the semaphore value by one +.RB ( sem_post (3)); +and decrement the semaphore value by one +.RB ( sem_wait (3)). +If the value of a semaphore is currently zero, then a +.BR sem_wait (3) +operation will block until the value becomes greater than zero. +.PP +POSIX semaphores come in two forms: named semaphores and +unnamed semaphores. +.TP +.B Named semaphores +A named semaphore is identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.BI NAME_MAX \-4 +(i.e., 251) characters consisting of an initial slash, +.\" glibc allows the initial slash to be omitted, and makes +.\" multiple initial slashes equivalent to a single slash. +.\" This differs from the implementation of POSIX message queues. +followed by one or more characters, none of which are slashes. +.\" glibc allows subdirectory components in the name, in which +.\" case the subdirectory tree must exist under /dev/shm, and +.\" the fist subdirectory component must exist as the name +.\" sem.name, and all of the subdirectory components must allow the +.\" required permissions if a user wants to create a semaphore +.\" object in a subdirectory. +Two processes can operate on the same named semaphore by passing +the same name to +.BR sem_open (3). +.IP +The +.BR sem_open (3) +function creates a new named semaphore or opens an existing +named semaphore. +After the semaphore has been opened, it can be operated on using +.BR sem_post (3) +and +.BR sem_wait (3). +When a process has finished using the semaphore, it can use +.BR sem_close (3) +to close the semaphore. +When all processes have finished using the semaphore, +it can be removed from the system using +.BR sem_unlink (3). +.TP +.B Unnamed semaphores (memory-based semaphores) +An unnamed semaphore does not have a name. +Instead the semaphore is placed in a region of memory that +is shared between multiple threads (a +.IR "thread-shared semaphore" ) +or processes (a +.IR "process-shared semaphore" ). +A thread-shared semaphore is placed in an area of memory shared +between the threads of a process, for example, a global variable. +A process-shared semaphore must be placed in a shared memory region +(e.g., a System V shared memory segment created using +.BR shmget (2), +or a POSIX shared memory object built created using +.BR shm_open (3)). +.IP +Before being used, an unnamed semaphore must be initialized using +.BR sem_init (3). +It can then be operated on using +.BR sem_post (3) +and +.BR sem_wait (3). +When the semaphore is no longer required, +and before the memory in which it is located is deallocated, +the semaphore should be destroyed using +.BR sem_destroy (3). +.PP +The remainder of this section describes some specific details +of the Linux implementation of POSIX semaphores. +.SS Versions +Prior to kernel 2.6, Linux supported only unnamed, +thread-shared semaphores. +On a system with Linux 2.6 and a glibc that provides the NPTL +threading implementation, +a complete implementation of POSIX semaphores is provided. +.SS Persistence +POSIX named semaphores have kernel persistence: +if not removed by +.BR sem_unlink (3), +a semaphore will exist until the system is shut down. +.SS Linking +Programs using the POSIX semaphores API must be compiled with +.I cc \-pthread +to link against the real-time library, +.IR librt . +.SS Accessing named semaphores via the filesystem +On Linux, named semaphores are created in a virtual filesystem, +normally mounted under +.IR /dev/shm , +with names of the form +.IR \fBsem.\fPsomename . +(This is the reason that semaphore names are limited to +.BI NAME_MAX \-4 +rather than +.B NAME_MAX +characters.) +.PP +Since Linux 2.6.19, ACLs can be placed on files under this directory, +to control object permissions on a per-user and per-group basis. +.SH NOTES +System V semaphores +.RB ( semget (2), +.BR semop (2), +etc.) are an older semaphore API. +POSIX semaphores provide a simpler, and better designed interface than +System V semaphores; +on the other hand POSIX semaphores are less widely available +(especially on older systems) than System V semaphores. +.SH EXAMPLE +An example of the use of various POSIX semaphore functions is shown in +.BR sem_wait (3). +.SH SEE ALSO +.BR sem_close (3), +.BR sem_destroy (3), +.BR sem_getvalue (3), +.BR sem_init (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR pthreads (7), +.BR shm_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/session-keyring.7 b/man7/session-keyring.7 new file mode 100644 index 0000000..314432b --- /dev/null +++ b/man7/session-keyring.7 @@ -0,0 +1,125 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH "SESSION-KEYRING" 7 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +session-keyring \- session shared process keyring +.SH DESCRIPTION +The session keyring is a keyring used to anchor keys on behalf of a process. +It is typically created by +.BR pam_keyinit (8) +when a user logs in and a link will be added that refers to the +.BR user-keyring (7). +Optionally, PAM may revoke the session keyring on logout. +(In typical configurations, PAM does do this revocation.) +The session keyring has the name (description) +.IR _ses . +.PP +A special serial number value, +.BR KEY_SPEC_SESSION_KEYRING , +is defined that can be used in lieu of the actual serial number of +the calling process's session keyring. +.PP +From the +.BR keyctl (1) +utility, '\fB@s\fP' can be used instead of a numeric key ID in +much the same way. +.PP +A process's session keyring is inherited across +.BR clone (2), +.BR fork (2), +and +.BR vfork (2). +The session keyring +is preserved across +.BR execve (2), +even when the executable is set-user-ID or set-group-ID or has capabilities. +The session keyring is destroyed when the last process that +refers to it exits. +.PP +If a process doesn't have a session keyring when it is accessed, then, +under certain circumstances, the +.BR user-session-keyring (7) +will be attached as the session keyring +and under others a new session keyring will be created. +(See +.BR user-session-keyring (7) +for further details.) +.SS Special operations +The +.I keyutils +library provides the following special operations for manipulating +session keyrings: +.TP +.BR keyctl_join_session_keyring (3) +This operation allows the caller to change the session keyring +that it subscribes to. +The caller can join an existing keyring with a specified name (description), +create a new keyring with a given name, +or ask the kernel to create a new "anonymous" +session keyring with the name "_ses". +(This function is an interface to the +.BR keyctl (2) +.B KEYCTL_JOIN_SESSION_KEYRING +operation.) +.TP +.BR keyctl_session_to_parent (3) +This operation allows the caller to make the parent process's +session keyring to the same as its own. +For this to succeed, the parent process must have +identical security attributes and must be single threaded. +(This function is an interface to the +.BR keyctl (2) +.B KEYCTL_SESSION_TO_PARENT +operation.) +.PP +These operations are also exposed through the +.BR keyctl (1) +utility as: +.PP +.in +4n +.EX +keyctl session +keyctl session - [ ...] +keyctl session [ ...] +.EE +.in +.PP +and: +.PP +.in +4n +.EX +keyctl new_session +.EE +.in +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyctl_join_session_keyring (3), +.BR keyctl_session_to_parent (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7), +.BR pam_keyinit (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/shm_overview.7 b/man7/shm_overview.7 new file mode 100644 index 0000000..216c26f --- /dev/null +++ b/man7/shm_overview.7 @@ -0,0 +1,133 @@ +'\" t +.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SHM_OVERVIEW 7 2016-12-12 "Linux" "Linux Programmer's Manual" +.SH NAME +shm_overview \- overview of POSIX shared memory +.SH DESCRIPTION +The POSIX shared memory API allows processes to communicate information +by sharing a region of memory. +.PP +The interfaces employed in the API are: +.TP 15 +.BR shm_open (3) +Create and open a new object, or open an existing object. +This is analogous to +.BR open (2). +The call returns a file descriptor for use by the other +interfaces listed below. +.TP +.BR ftruncate (2) +Set the size of the shared memory object. +(A newly created shared memory object has a length of zero.) +.TP +.BR mmap (2) +Map the shared memory object into the virtual address space +of the calling process. +.TP +.BR munmap (2) +Unmap the shared memory object from the virtual address space +of the calling process. +.TP +.BR shm_unlink (3) +Remove a shared memory object name. +.TP +.BR close (2) +Close the file descriptor allocated by +.BR shm_open (3) +when it is no longer needed. +.TP +.BR fstat (2) +Obtain a +.I stat +structure that describes the shared memory object. +Among the information returned by this call are the object's +size +.RI ( st_size ), +permissions +.RI ( st_mode ), +owner +.RI ( st_uid ), +and group +.RI ( st_gid ). +.TP +.BR fchown (2) +To change the ownership of a shared memory object. +.TP +.BR fchmod (2) +To change the permissions of a shared memory object. +.SS Versions +POSIX shared memory is supported since Linux 2.4 and glibc 2.2. +.SS Persistence +POSIX shared memory objects have kernel persistence: +a shared memory object will exist until the system is shut down, +or until all processes have unmapped the object and it has been deleted with +.BR shm_unlink (3) +.SS Linking +Programs using the POSIX shared memory API must be compiled with +.I cc \-lrt +to link against the real-time library, +.IR librt . +.SS Accessing shared memory objects via the filesystem +On Linux, shared memory objects are created in a +.RI ( tmpfs (5)) +virtual filesystem, normally mounted under +.IR /dev/shm . +Since kernel 2.6.19, Linux supports the use of access control lists (ACLs) +to control the permissions of objects in the virtual filesystem. +.SH NOTES +Typically, processes must synchronize their access to a shared +memory object, using, for example, POSIX semaphores. +.PP +System V shared memory +.RB ( shmget (2), +.BR shmop (2), +etc.) is an older shared memory API. +POSIX shared memory provides a simpler, and better designed interface; +on the other hand POSIX shared memory is somewhat less widely available +(especially on older systems) than System V shared memory. +.SH SEE ALSO +.BR fchmod (2), +.BR fchown (2), +.BR fstat (2), +.BR ftruncate (2), +.BR mmap (2), +.BR mprotect (2), +.BR munmap (2), +.BR shmget (2), +.BR shmop (2), +.BR shm_open (3), +.BR shm_unlink (3), +.BR sem_overview (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/sigevent.7 b/man7/sigevent.7 new file mode 100644 index 0000000..2b4a8b5 --- /dev/null +++ b/man7/sigevent.7 @@ -0,0 +1,149 @@ +.\" Copyright (C) 2006, 2010 Michael Kerrisk +.\" Copyright (C) 2009 Petr Baudis +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SIGEVENT 7 2017-07-13 "GNU" "Linux Programmer's Manual" +.SH NAME +sigevent \- structure for notification from asynchronous routines +.SH SYNOPSIS +.nf +#include +.PP +union sigval { /* Data passed with notification */ + int sival_int; /* Integer value */ + void *sival_ptr; /* Pointer value */ +}; +.PP +struct sigevent { + int sigev_notify; /* Notification method */ + int sigev_signo; /* Notification signal */ + union sigval sigev_value; /* Data passed with + notification */ + void (*sigev_notify_function) (union sigval); + /* Function used for thread + notification (SIGEV_THREAD) */ + void *sigev_notify_attributes; + /* Attributes for notification thread + (SIGEV_THREAD) */ + pid_t sigev_notify_thread_id; + /* ID of thread to signal (SIGEV_THREAD_ID) */ +}; +.fi +.SH DESCRIPTION +.PP +The +.I sigevent +structure is used by various APIs +to describe the way a process is to be notified about an event +(e.g., completion of an asynchronous request, expiration of a timer, +or the arrival of a message). +.PP +The definition shown in the SYNOPSIS is approximate: +some of the fields in the +.I sigevent +structure may be defined as part of a union. +Programs should employ only those fields relevant +to the value specified in +.IR sigev_notify . +.PP +The +.I sigev_notify +field specifies how notification is to be performed. +This field can have one of the following values: +.TP 8 +.BR SIGEV_NONE +A "null" notification: don't do anything when the event occurs. +.TP +.BR SIGEV_SIGNAL +Notify the process by sending the signal specified in +.IR sigev_signo . +.IP +If the signal is caught with a signal handler that was registered using the +.BR sigaction (2) +.B SA_SIGINFO +flag, then the following fields are set in the +.I siginfo_t +structure that is passed as the second argument of the handler: +.RS 8 +.TP 10 +.I si_code +This field is set to a value that depends on the API +delivering the notification. +.TP +.I si_signo +This field is set to the signal number (i.e., the same value as in +.IR sigev_signo ). +.TP +.I si_value +This field is set to the value specified in +.IR sigev_value . +.RE +.IP +Depending on the API, other fields may also be set in the +.I siginfo_t +structure. +.IP +The same information is also available if the signal is accepted using +.BR sigwaitinfo (2). +.TP +.BR SIGEV_THREAD +Notify the process by invoking +.I sigev_notify_function +"as if" it were the start function of a new thread. +(Among the implementation possibilities here are that +each timer notification could result in the creation of a new thread, +or that a single thread is created to receive all notifications.) +The function is invoked with +.I sigev_value +as its sole argument. +If +.I sigev_notify_attributes +is not NULL, it should point to a +.I pthread_attr_t +structure that defines attributes for the new thread (see +.BR pthread_attr_init (3)). +.TP +.BR SIGEV_THREAD_ID " (Linux-specific)" +.\" | SIGEV_SIGNAL vs not? +Currently used only by POSIX timers; see +.BR timer_create (2). +.SH SEE ALSO +.BR timer_create (2), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_write (3), +.BR getaddrinfo_a (3), +.BR lio_listio (3), +.BR mq_notify (3), +.BR aio (7), +.BR pthreads (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/signal-safety.7 b/man7/signal-safety.7 new file mode 100644 index 0000000..97c1ad7 --- /dev/null +++ b/man7/signal-safety.7 @@ -0,0 +1,349 @@ +.\" Copyright (c) 2016 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SIGNAL-SAFETY 7 2017-03-13 "Linux" "Linux Programmer's Manual" +.SH NAME +signal-safety \- async-signal-safe functions +.SH DESCRIPTION +An +.I async-signal-safe +function is one that can be safely called from within a signal handler. +Many functions are +.I not +async-signal-safe. +In particular, +nonreentrant functions are generally unsafe to call from a signal handler. +.PP +The kinds of issues that render a function +unsafe can be quickly understood when one considers +the implementation of the +.I stdio +library, all of whose functions are not async-signal-safe. +.PP +When performing buffered I/O on a file, the +.I stdio +functions must maintain a statically allocated data buffer +along with associated counters and indexes (or pointers) +that record the amount of data and the current position in the buffer. +Suppose that the main program is in the middle of a call to a +.I stdio +function such as +.BR printf (3) +where the buffer and associated variables have been partially updated. +If, at that moment, +the program is interrupted by a signal handler that also calls +.BR printf (3), +then the second call to +.BR printf (3) +will operate on inconsistent data, with unpredictable results. +.PP +To avoid problems with unsafe functions, there are two possible choices: +.IP 1. 3 +Ensure that +(a) the signal handler calls only async-signal-safe functions, +and +(b) the signal handler itself is reentrant +with respect to global variables in the main program. +.IP 2. +Block signal delivery in the main program when calling functions +that are unsafe or operating on global data that is also accessed +by the signal handler. +.PP +Generally, the second choice is difficult in programs of any complexity, +so the first choice is taken. +.PP +POSIX.1 specifies a set of functions that an implementation +must make async-signal-safe. +(An implementation may provide safe implementations of additional functions, +but this is not required by the standard and other implementations +may not provide the same guarantees.) +In general, a function is async-signal-safe either because it is reentrant +or because it is atomic with respect to signals +(i.e., its execution can't be interrupted by a signal handler). +.PP +The set of functions required to be async-signal-safe by POSIX.1 +is shown in the following table. +The functions not otherwise noted were required to be async-signal-safe +in POSIX.1-2001; +the table details changes in the subsequent standards. +.PP +.TS +lb lb +l l. +Function Notes +\fBabort\fP(3) Added in POSIX.1-2003 +\fBaccept\fP(2) +\fBaccess\fP(2) +\fBaio_error\fP(3) +\fBaio_return\fP(3) +\fBaio_suspend\fP(3) See notes below +\fBalarm\fP(2) +\fBbind\fP(2) +\fBcfgetispeed\fP(3) +\fBcfgetospeed\fP(3) +\fBcfsetispeed\fP(3) +\fBcfsetospeed\fP(3) +\fBchdir\fP(2) +\fBchmod\fP(2) +\fBchown\fP(2) +\fBclock_gettime\fP(2) +\fBclose\fP(2) +\fBconnect\fP(2) +\fBcreat\fP(2) +\fBdup\fP(2) +\fBdup2\fP(2) +\fBexecl\fP(3) Added in POSIX.1-2008; see notes below +\fBexecle\fP(3) See notes below +\fBexecv\fP(3) Added in POSIX.1-2008 +\fBexecve\fP(2) +\fB_exit\fP(2) +\fB_Exit\fP(2) +\fBfaccessat\fP(2) Added in POSIX.1-2008 +\fBfchdir\fP(2) Added in POSIX.1-2013 +\fBfchmod\fP(2) +\fBfchmodat\fP(2) Added in POSIX.1-2008 +\fBfchown\fP(2) +\fBfchownat\fP(2) Added in POSIX.1-2008 +\fBfcntl\fP(2) +\fBfdatasync\fP(2) +\fBfexecve\fP(3) Added in POSIX.1-2008 +\fBffs\fP(3) Added in POSIX.1-2016 +\fBfork\fP(2) See notes below +\fBfstat\fP(2) +\fBfstatat\fP(2) Added in POSIX.1-2008 +\fBfsync\fP(2) +\fBftruncate\fP(2) +\fBfutimens\fP(3) Added in POSIX.1-2008 +\fBgetegid\fP(2) +\fBgeteuid\fP(2) +\fBgetgid\fP(2) +\fBgetgroups\fP(2) +\fBgetpeername\fP(2) +\fBgetpgrp\fP(2) +\fBgetpid\fP(2) +\fBgetppid\fP(2) +\fBgetsockname\fP(2) +\fBgetsockopt\fP(2) +\fBgetuid\fP(2) +\fBhtonl\fP(3) Added in POSIX.1-2016 +\fBhtons\fP(3) Added in POSIX.1-2016 +\fBkill\fP(2) +\fBlink\fP(2) +\fBlinkat\fP(2) Added in POSIX.1-2008 +\fBlisten\fP(2) +\fBlongjmp\fP(3) Added in POSIX.1-2016; see notes below +\fBlseek\fP(2) +\fBlstat\fP(2) +\fBmemccpy\fP(3) Added in POSIX.1-2016 +\fBmemchr\fP(3) Added in POSIX.1-2016 +\fBmemcmp\fP(3) Added in POSIX.1-2016 +\fBmemcpy\fP(3) Added in POSIX.1-2016 +\fBmemmove\fP(3) Added in POSIX.1-2016 +\fBmemset\fP(3) Added in POSIX.1-2016 +\fBmkdir\fP(2) +\fBmkdirat\fP(2) Added in POSIX.1-2008 +\fBmkfifo\fP(3) +\fBmkfifoat\fP(3) Added in POSIX.1-2008 +\fBmknod\fP(2) Added in POSIX.1-2008 +\fBmknodat\fP(2) Added in POSIX.1-2008 +\fBntohl\fP(3) Added in POSIX.1-2016 +\fBntohs\fP(3) Added in POSIX.1-2016 +\fBopen\fP(2) +\fBopenat\fP(2) Added in POSIX.1-2008 +\fBpause\fP(2) +\fBpipe\fP(2) +\fBpoll\fP(2) +\fBposix_trace_event\fP(3) +\fBpselect\fP(2) +\fBpthread_kill\fP(3) Added in POSIX.1-2013 +\fBpthread_self\fP(3) Added in POSIX.1-2013 +\fBpthread_sigmask\fP(3) Added in POSIX.1-2013 +\fBraise\fP(3) +\fBread\fP(2) +\fBreadlink\fP(2) +\fBreadlinkat\fP(2) Added in POSIX.1-2008 +\fBrecv\fP(2) +\fBrecvfrom\fP(2) +\fBrecvmsg\fP(2) +\fBrename\fP(2) +\fBrenameat\fP(2) Added in POSIX.1-2008 +\fBrmdir\fP(2) +\fBselect\fP(2) +\fBsem_post\fP(3) +\fBsend\fP(2) +\fBsendmsg\fP(2) +\fBsendto\fP(2) +\fBsetgid\fP(2) +\fBsetpgid\fP(2) +\fBsetsid\fP(2) +\fBsetsockopt\fP(2) +\fBsetuid\fP(2) +\fBshutdown\fP(2) +\fBsigaction\fP(2) +\fBsigaddset\fP(3) +\fBsigdelset\fP(3) +\fBsigemptyset\fP(3) +\fBsigfillset\fP(3) +\fBsigismember\fP(3) +\fBsiglongjmp\fP(3) Added in POSIX.1-2016; see notes below +\fBsignal\fP(2) +\fBsigpause\fP(3) +\fBsigpending\fP(2) +\fBsigprocmask\fP(2) +\fBsigqueue\fP(2) +\fBsigset\fP(3) +\fBsigsuspend\fP(2) +\fBsleep\fP(3) +\fBsockatmark\fP(3) Added in POSIX.1-2004 +\fBsocket\fP(2) +\fBsocketpair\fP(2) +\fBstat\fP(2) +\fBstpcpy\fP(3) Added in POSIX.1-2016 +\fBstpncpy\fP(3) Added in POSIX.1-2016 +\fBstrcat\fP(3) Added in POSIX.1-2016 +\fBstrchr\fP(3) Added in POSIX.1-2016 +\fBstrcmp\fP(3) Added in POSIX.1-2016 +\fBstrcpy\fP(3) Added in POSIX.1-2016 +\fBstrcspn\fP(3) Added in POSIX.1-2016 +\fBstrlen\fP(3) Added in POSIX.1-2016 +\fBstrncat\fP(3) Added in POSIX.1-2016 +\fBstrncmp\fP(3) Added in POSIX.1-2016 +\fBstrncpy\fP(3) Added in POSIX.1-2016 +\fBstrnlen\fP(3) Added in POSIX.1-2016 +\fBstrpbrk\fP(3) Added in POSIX.1-2016 +\fBstrrchr\fP(3) Added in POSIX.1-2016 +\fBstrspn\fP(3) Added in POSIX.1-2016 +\fBstrstr\fP(3) Added in POSIX.1-2016 +\fBstrtok_r\fP(3) Added in POSIX.1-2016 +\fBsymlink\fP(2) +\fBsymlinkat\fP(2) Added in POSIX.1-2008 +\fBtcdrain\fP(3) +\fBtcflow\fP(3) +\fBtcflush\fP(3) +\fBtcgetattr\fP(3) +\fBtcgetpgrp\fP(3) +\fBtcsendbreak\fP(3) +\fBtcsetattr\fP(3) +\fBtcsetpgrp\fP(3) +\fBtime\fP(2) +\fBtimer_getoverrun\fP(2) +\fBtimer_gettime\fP(2) +\fBtimer_settime\fP(2) +\fBtimes\fP(2) +\fBumask\fP(2) +\fBuname\fP(2) +\fBunlink\fP(2) +\fBunlinkat\fP(2) Added in POSIX.1-2008 +\fButime\fP(2) +\fButimensat\fP(2) Added in POSIX.1-2008 +\fButimes\fP(2) Added in POSIX.1-2008 +\fBwait\fP(2) +\fBwaitpid\fP(2) +\fBwcpcpy\fP(3) Added in POSIX.1-2016 +\fBwcpncpy\fP(3) Added in POSIX.1-2016 +\fBwcscat\fP(3) Added in POSIX.1-2016 +\fBwcschr\fP(3) Added in POSIX.1-2016 +\fBwcscmp\fP(3) Added in POSIX.1-2016 +\fBwcscpy\fP(3) Added in POSIX.1-2016 +\fBwcscspn\fP(3) Added in POSIX.1-2016 +\fBwcslen\fP(3) Added in POSIX.1-2016 +\fBwcsncat\fP(3) Added in POSIX.1-2016 +\fBwcsncmp\fP(3) Added in POSIX.1-2016 +\fBwcsncpy\fP(3) Added in POSIX.1-2016 +\fBwcsnlen\fP(3) Added in POSIX.1-2016 +\fBwcspbrk\fP(3) Added in POSIX.1-2016 +\fBwcsrchr\fP(3) Added in POSIX.1-2016 +\fBwcsspn\fP(3) Added in POSIX.1-2016 +\fBwcsstr\fP(3) Added in POSIX.1-2016 +\fBwcstok\fP(3) Added in POSIX.1-2016 +\fBwmemchr\fP(3) Added in POSIX.1-2016 +\fBwmemcmp\fP(3) Added in POSIX.1-2016 +\fBwmemcpy\fP(3) Added in POSIX.1-2016 +\fBwmemmove\fP(3) Added in POSIX.1-2016 +\fBwmemset\fP(3) Added in POSIX.1-2016 +\fBwrite\fP(2) +.TE +.sp 1 +Notes: +.IP * 3 +POSIX.1-2001 and POSIX.1-2004 required the functions +.BR fpathconf (3), +.BR pathconf (3), +and +.BR sysconf (3) +to be async-signal-safe, but this requirement was removed in POSIX.1-2008. +.IP * +If a signal handler interrupts the execution of an unsafe function, +and the handler terminates via a call to +.BR longjmp (3) +or +.BR siglongjmp (3) +and the program subsequently calls an unsafe function, +then the behavior of the program is undefined. +.IP * +POSIX.1-2003 clarified +that if an application calls +.BR fork (2) +from a signal handler and any of the fork handlers registered by +.BR pthread_atfork (3) +calls a function that is not async-signal-safe, the behavior is undefined. +A future revision of the standard +.\" http://www.opengroup.org/austin/aardvark/latest/xshbug3.txt +is likely to remove +.BR fork (2) +from the list of async-signal-safe functions. +.\" +.SS Deviations in the GNU C library +The following known deviations from the standard occur in +the GNU C library: +.IP * 3 +Before glibc 2.24, +.BR execl (3) +and +.BR execle (3) +employed +.BR realloc (3) +internally and were consequently not async-signal-safe. +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534 +This was fixed in glibc 2.24. +.IP * +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172 +The glibc implementation of +.BR aio_suspend (3) +is not async-signal-safe because it uses +.BR pthread_mutex_lock (3) +internally. +.SH SEE ALSO +.BR sigaction (2), +.BR signal (7), +.BR standards (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/signal.7 b/man7/signal.7 new file mode 100644 index 0000000..7febd12 --- /dev/null +++ b/man7/signal.7 @@ -0,0 +1,795 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (c) 2002, 2006 by Michael Kerrisk +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:34:08 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jan 7 01:41:27 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Apr 14 12:02:29 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sat Nov 13 16:28:23 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 10 Apr 2002, by Michael Kerrisk +.\" Modified 7 Jun 2002, by Michael Kerrisk +.\" Added information on real-time signals +.\" Modified 13 Jun 2002, by Michael Kerrisk +.\" Noted that SIGSTKFLT is in fact unused +.\" 2004-12-03, Modified mtk, added notes on RLIMIT_SIGPENDING +.\" 2006-04-24, mtk, Added text on changing signal dispositions, +.\" signal mask, and pending signals. +.\" 2008-07-04, mtk: +.\" Added section on system call restarting (SA_RESTART) +.\" Added section on stop/cont signals interrupting syscalls. +.\" 2008-10-05, mtk: various additions +.\" +.TH SIGNAL 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +signal \- overview of signals +.SH DESCRIPTION +Linux supports both POSIX reliable signals (hereinafter +"standard signals") and POSIX real-time signals. +.SS Signal dispositions +Each signal has a current +.IR disposition , +which determines how the process behaves when it is delivered +the signal. +.PP +The entries in the "Action" column of the tables below specify +the default disposition for each signal, as follows: +.IP Term +Default action is to terminate the process. +.IP Ign +Default action is to ignore the signal. +.IP Core +Default action is to terminate the process and dump core (see +.BR core (5)). +.IP Stop +Default action is to stop the process. +.IP Cont +Default action is to continue the process if it is currently stopped. +.PP +A process can change the disposition of a signal using +.BR sigaction (2) +or +.BR signal (2). +(The latter is less portable when establishing a signal handler; +see +.BR signal (2) +for details.) +Using these system calls, a process can elect one of the +following behaviors to occur on delivery of the signal: +perform the default action; ignore the signal; +or catch the signal with a +.IR "signal handler" , +a programmer-defined function that is automatically invoked +when the signal is delivered. +(By default, the signal handler is invoked on the +normal process stack. +It is possible to arrange that the signal handler +uses an alternate stack; see +.BR sigaltstack (2) +for a discussion of how to do this and when it might be useful.) +.PP +The signal disposition is a per-process attribute: +in a multithreaded application, the disposition of a +particular signal is the same for all threads. +.PP +A child created via +.BR fork (2) +inherits a copy of its parent's signal dispositions. +During an +.BR execve (2), +the dispositions of handled signals are reset to the default; +the dispositions of ignored signals are left unchanged. +.SS Sending a signal +The following system calls and library functions allow +the caller to send a signal: +.TP 16 +.BR raise (3) +Sends a signal to the calling thread. +.TP +.BR kill (2) +Sends a signal to a specified process, +to all members of a specified process group, +or to all processes on the system. +.TP +.BR killpg (3) +Sends a signal to all of the members of a specified process group. +.TP +.BR pthread_kill (3) +Sends a signal to a specified POSIX thread in the same process as +the caller. +.TP +.BR tgkill (2) +Sends a signal to a specified thread within a specific process. +(This is the system call used to implement +.BR pthread_kill (3).) +.TP +.BR sigqueue (3) +Sends a real-time signal with accompanying data to a specified process. +.SS Waiting for a signal to be caught +The following system calls suspend execution of the calling process +or thread until a signal is caught +(or an unhandled signal terminates the process): +.TP 16 +.BR pause (2) +Suspends execution until any signal is caught. +.TP +.BR sigsuspend (2) +Temporarily changes the signal mask (see below) and suspends +execution until one of the unmasked signals is caught. +.SS Synchronously accepting a signal +Rather than asynchronously catching a signal via a signal handler, +it is possible to synchronously accept the signal, that is, +to block execution until the signal is delivered, +at which point the kernel returns information about the +signal to the caller. +There are two general ways to do this: +.IP * 2 +.BR sigwaitinfo (2), +.BR sigtimedwait (2), +and +.BR sigwait (3) +suspend execution until one of the signals in a specified +set is delivered. +Each of these calls returns information about the delivered signal. +.IP * +.BR signalfd (2) +returns a file descriptor that can be used to read information +about signals that are delivered to the caller. +Each +.BR read (2) +from this file descriptor blocks until one of the signals +in the set specified in the +.BR signalfd (2) +call is delivered to the caller. +The buffer returned by +.BR read (2) +contains a structure describing the signal. +.SS Signal mask and pending signals +A signal may be +.IR blocked , +which means that it will not be delivered until it is later unblocked. +Between the time when it is generated and when it is delivered +a signal is said to be +.IR pending . +.PP +Each thread in a process has an independent +.IR "signal mask" , +which indicates the set of signals that the thread is currently blocking. +A thread can manipulate its signal mask using +.BR pthread_sigmask (3). +In a traditional single-threaded application, +.BR sigprocmask (2) +can be used to manipulate the signal mask. +.PP +A child created via +.BR fork (2) +inherits a copy of its parent's signal mask; +the signal mask is preserved across +.BR execve (2). +.PP +A signal may be generated (and thus pending) +for a process as a whole (e.g., when sent using +.BR kill (2)) +or for a specific thread (e.g., certain signals, +such as +.B SIGSEGV +and +.BR SIGFPE , +generated as a +consequence of executing a specific machine-language instruction +are thread directed, as are signals targeted at a specific thread using +.BR pthread_kill (3)). +A process-directed signal may be delivered to any one of the +threads that does not currently have the signal blocked. +If more than one of the threads has the signal unblocked, then the +kernel chooses an arbitrary thread to which to deliver the signal. +.PP +A thread can obtain the set of signals that it currently has pending +using +.BR sigpending (2). +This set will consist of the union of the set of pending +process-directed signals and the set of signals pending for +the calling thread. +.PP +A child created via +.BR fork (2) +initially has an empty pending signal set; +the pending signal set is preserved across an +.BR execve (2). +.SS Standard signals +Linux supports the standard signals listed below. +Several signal numbers +are architecture-dependent, as indicated in the "Value" column. +(Where three values are given, the first one is usually valid for +alpha and sparc, +the middle one for x86, arm, and most other architectures, +and the last one for mips. +(Values for parisc are +.I not +shown; see the Linux kernel source for signal numbering on that architecture.) +A dash (\-) denotes that a signal is absent on the corresponding architecture. +.PP +First the signals described in the original POSIX.1-1990 standard. +.TS +l c c l +____ +lB c c l. +Signal Value Action Comment +SIGHUP \01 Term Hangup detected on controlling terminal + or death of controlling process +SIGINT \02 Term Interrupt from keyboard +SIGQUIT \03 Core Quit from keyboard +SIGILL \04 Core Illegal Instruction +SIGABRT \06 Core Abort signal from \fBabort\fP(3) +SIGFPE \08 Core Floating-point exception +SIGKILL \09 Term Kill signal +SIGSEGV 11 Core Invalid memory reference +SIGPIPE 13 Term Broken pipe: write to pipe with no + readers; see \fBpipe\fP(7) +SIGALRM 14 Term Timer signal from \fBalarm\fP(2) +SIGTERM 15 Term Termination signal +SIGUSR1 30,10,16 Term User-defined signal 1 +SIGUSR2 31,12,17 Term User-defined signal 2 +SIGCHLD 20,17,18 Ign Child stopped or terminated +SIGCONT 19,18,25 Cont Continue if stopped +SIGSTOP 17,19,23 Stop Stop process +SIGTSTP 18,20,24 Stop Stop typed at terminal +SIGTTIN 21,21,26 Stop Terminal input for background process +SIGTTOU 22,22,27 Stop Terminal output for background process +.TE +.sp 1 +The signals +.B SIGKILL +and +.B SIGSTOP +cannot be caught, blocked, or ignored. +.PP +Next the signals not in the POSIX.1-1990 standard but described in +SUSv2 and POSIX.1-2001. +.TS +l c c l +____ +lB c c l. +Signal Value Action Comment +SIGBUS 10,7,10 Core Bus error (bad memory access) +SIGPOLL Term Pollable event (Sys V). + Synonym for \fBSIGIO\fP +SIGPROF 27,27,29 Term Profiling timer expired +SIGSYS 12,31,12 Core Bad system call (SVr4); + see also \fBseccomp\fP(2) +SIGTRAP 5 Core Trace/breakpoint trap +SIGURG 16,23,21 Ign Urgent condition on socket (4.2BSD) +SIGVTALRM 26,26,28 Term Virtual alarm clock (4.2BSD) +SIGXCPU 24,24,30 Core CPU time limit exceeded (4.2BSD); + see \fBsetrlimit\fP(2) +SIGXFSZ 25,25,31 Core File size limit exceeded (4.2BSD); + see \fBsetrlimit\fP(2) +.TE +.sp 1 +Up to and including Linux 2.2, the default behavior for +.BR SIGSYS ", " SIGXCPU ", " SIGXFSZ ", " +and (on architectures other than SPARC and MIPS) +.B SIGBUS +was to terminate the process (without a core dump). +(On some other UNIX systems the default action for +.BR SIGXCPU " and " SIGXFSZ +is to terminate the process without a core dump.) +Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals, +terminating the process with a core dump. +.PP +Next various other signals. +.TS +l c c l +____ +lB c c l. +Signal Value Action Comment +SIGIOT 6 Core IOT trap. A synonym for \fBSIGABRT\fP +SIGEMT 7,\-,7 Term Emulator trap +SIGSTKFLT \-,16,\- Term Stack fault on coprocessor (unused) +SIGIO 23,29,22 Term I/O now possible (4.2BSD) +SIGCLD \-,\-,18 Ign A synonym for \fBSIGCHLD\fP +SIGPWR 29,30,19 Term Power failure (System V) +SIGINFO 29,\-,\- A synonym for \fBSIGPWR\fP +SIGLOST \-,\-,\- Term File lock lost (unused) +SIGWINCH 28,28,20 Ign Window resize signal (4.3BSD, Sun) +SIGUNUSED \-,31,\- Core Synonymous with \fBSIGSYS\fP +.TE +.sp 1 +(Signal 29 is +.B SIGINFO +/ +.B SIGPWR +on an alpha but +.B SIGLOST +on a sparc.) +.PP +.B SIGEMT +is not specified in POSIX.1-2001, but nevertheless appears +on most other UNIX systems, +where its default action is typically to terminate +the process with a core dump. +.PP +.B SIGPWR +(which is not specified in POSIX.1-2001) is typically ignored +by default on those other UNIX systems where it appears. +.PP +.B SIGIO +(which is not specified in POSIX.1-2001) is ignored by default +on several other UNIX systems. +.PP +Where defined, +.B SIGUNUSED +is synonymous with +.\" parisc is the only exception: SIGSYS is 12, SIGUNUSED is 31 +.B SIGSYS +on most architectures. +Since glibc 2.26, +.B SIGUNUSED +is no longer defined on any architecture. +.SS Real-time signals +Starting with version 2.2, +Linux supports real-time signals as originally defined in the POSIX.1b +real-time extensions (and now included in POSIX.1-2001). +The range of supported real-time signals is defined by the macros +.B SIGRTMIN +and +.BR SIGRTMAX . +POSIX.1-2001 requires that an implementation support at least +.B _POSIX_RTSIG_MAX +(8) real-time signals. +.PP +The Linux kernel supports a range of 33 different real-time +signals, numbered 32 to 64. +However, the glibc POSIX threads implementation internally uses +two (for NPTL) or three (for LinuxThreads) real-time signals +(see +.BR pthreads (7)), +and adjusts the value of +.B SIGRTMIN +suitably (to 34 or 35). +Because the range of available real-time signals varies according +to the glibc threading implementation (and this variation can occur +at run time according to the available kernel and glibc), +and indeed the range of real-time signals varies across UNIX systems, +programs should +.IR "never refer to real-time signals using hard-coded numbers" , +but instead should always refer to real-time signals using the notation +.BR SIGRTMIN +n, +and include suitable (run-time) checks that +.BR SIGRTMIN +n +does not exceed +.BR SIGRTMAX . +.PP +Unlike standard signals, real-time signals have no predefined meanings: +the entire set of real-time signals can be used for application-defined +purposes. +.PP +The default action for an unhandled real-time signal is to terminate the +receiving process. +.PP +Real-time signals are distinguished by the following: +.IP 1. 4 +Multiple instances of real-time signals can be queued. +By contrast, if multiple instances of a standard signal are delivered +while that signal is currently blocked, then only one instance is queued. +.IP 2. 4 +If the signal is sent using +.BR sigqueue (3), +an accompanying value (either an integer or a pointer) can be sent +with the signal. +If the receiving process establishes a handler for this signal using the +.B SA_SIGINFO +flag to +.BR sigaction (2), +then it can obtain this data via the +.I si_value +field of the +.I siginfo_t +structure passed as the second argument to the handler. +Furthermore, the +.I si_pid +and +.I si_uid +fields of this structure can be used to obtain the PID +and real user ID of the process sending the signal. +.IP 3. 4 +Real-time signals are delivered in a guaranteed order. +Multiple real-time signals of the same type are delivered in the order +they were sent. +If different real-time signals are sent to a process, they are delivered +starting with the lowest-numbered signal. +(I.e., low-numbered signals have highest priority.) +By contrast, if multiple standard signals are pending for a process, +the order in which they are delivered is unspecified. +.PP +If both standard and real-time signals are pending for a process, +POSIX leaves it unspecified which is delivered first. +Linux, like many other implementations, gives priority +to standard signals in this case. +.PP +According to POSIX, an implementation should permit at least +.B _POSIX_SIGQUEUE_MAX +(32) real-time signals to be queued to +a process. +However, Linux does things differently. +In kernels up to and including 2.6.7, Linux imposes +a system-wide limit on the number of queued real-time signals +for all processes. +This limit can be viewed and (with privilege) changed via the +.I /proc/sys/kernel/rtsig-max +file. +A related file, +.IR /proc/sys/kernel/rtsig-nr , +can be used to find out how many real-time signals are currently queued. +In Linux 2.6.8, these +.I /proc +interfaces were replaced by the +.B RLIMIT_SIGPENDING +resource limit, which specifies a per-user limit for queued +signals; see +.BR setrlimit (2) +for further details. +.PP +The addition of real-time signals required the widening +of the signal set structure +.RI ( sigset_t ) +from 32 to 64 bits. +Consequently, various system calls were superseded by new system calls +that supported the larger signal sets. +The old and new system calls are as follows: +.TS +lb lb +l l. +Linux 2.0 and earlier Linux 2.2 and later +\fBsigaction\fP(2) \fBrt_sigaction\fP(2) +\fBsigpending\fP(2) \fBrt_sigpending\fP(2) +\fBsigprocmask\fP(2) \fBrt_sigprocmask\fP(2) +\fBsigreturn\fP(2) \fBrt_sigreturn\fP(2) +\fBsigsuspend\fP(2) \fBrt_sigsuspend\fP(2) +\fBsigtimedwait\fP(2) \fBrt_sigtimedwait\fP(2) +.TE +.\" +.SS Interruption of system calls and library functions by signal handlers +If a signal handler is invoked while a system call or library +function call is blocked, then either: +.IP * 2 +the call is automatically restarted after the signal handler returns; or +.IP * +the call fails with the error +.BR EINTR . +.PP +Which of these two behaviors occurs depends on the interface and +whether or not the signal handler was established using the +.BR SA_RESTART +flag (see +.BR sigaction (2)). +The details vary across UNIX systems; +below, the details for Linux. +.PP +If a blocked call to one of the following interfaces is interrupted +by a signal handler, then the call is automatically restarted +after the signal handler returns if the +.BR SA_RESTART +flag was used; otherwise the call fails with the error +.BR EINTR : +.\" The following system calls use ERESTARTSYS, +.\" so that they are restartable +.IP * 2 +.BR read (2), +.BR readv (2), +.BR write (2), +.BR writev (2), +and +.BR ioctl (2) +calls on "slow" devices. +A "slow" device is one where the I/O call may block for an +indefinite time, for example, a terminal, pipe, or socket. +If an I/O call on a slow device has already transferred some +data by the time it is interrupted by a signal handler, +then the call will return a success status +(normally, the number of bytes transferred). +Note that a (local) disk is not a slow device according to this definition; +I/O operations on disk devices are not interrupted by signals. +.IP * +.BR open (2), +if it can block (e.g., when opening a FIFO; see +.BR fifo (7)). +.IP * +.BR wait (2), +.BR wait3 (2), +.BR wait4 (2), +.BR waitid (2), +and +.BR waitpid (2). +.IP * +Socket interfaces: +.\" If a timeout (setsockopt()) is in effect on the socket, then these +.\" system calls switch to using EINTR. Consequently, they and are not +.\" automatically restarted, and they show the stop/cont behavior +.\" described below. (Verified from 2.6.26 source, and by experiment; mtk) +.BR accept (2), +.BR connect (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmmsg (2), +.BR recvmsg (2), +.BR send (2), +.BR sendto (2), +and +.BR sendmsg (2), +.\" FIXME What about sendmmsg()? +unless a timeout has been set on the socket (see below). +.IP * +File locking interfaces: +.BR flock (2) +and +the +.BR F_SETLKW +and +.BR F_OFD_SETLKW +operations of +.BR fcntl (2) +.IP * +POSIX message queue interfaces: +.BR mq_receive (3), +.BR mq_timedreceive (3), +.BR mq_send (3), +and +.BR mq_timedsend (3). +.IP * +.BR futex (2) +.B FUTEX_WAIT +(since Linux 2.6.22; +.\" commit 72c1bbf308c75a136803d2d76d0e18258be14c7a +beforehand, always failed with +.BR EINTR ). +.IP * +.BR getrandom (2). +.IP * +.BR pthread_mutex_lock (3), +.BR pthread_cond_wait (3), +and related APIs. +.IP * +.BR futex (2) +.BR FUTEX_WAIT_BITSET . +.IP * +POSIX semaphore interfaces: +.BR sem_wait (3) +and +.BR sem_timedwait (3) +(since Linux 2.6.22; +.\" as a consequence of the 2.6.22 changes in the futex() implementation +beforehand, always failed with +.BR EINTR ). +.IP * +.BR read (2) +from an +.BR inotify (7) +file descriptor +(since Linux 3.8; +.\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06 +beforehand, always failed with +.BR EINTR ). +.PP +The following interfaces are never restarted after +being interrupted by a signal handler, +regardless of the use of +.BR SA_RESTART ; +they always fail with the error +.B EINTR +when interrupted by a signal handler: +.\" These are the system calls that give EINTR or ERESTARTNOHAND +.\" on interruption by a signal handler. +.IP * 2 +"Input" socket interfaces, when a timeout +.RB ( SO_RCVTIMEO ) +has been set on the socket using +.BR setsockopt (2): +.BR accept (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmmsg (2) +(also with a non-NULL +.IR timeout +argument), +and +.BR recvmsg (2). +.IP * +"Output" socket interfaces, when a timeout +.RB ( SO_RCVTIMEO ) +has been set on the socket using +.BR setsockopt (2): +.BR connect (2), +.BR send (2), +.BR sendto (2), +and +.BR sendmsg (2). +.\" FIXME What about sendmmsg()? +.IP * +Interfaces used to wait for signals: +.BR pause (2), +.BR sigsuspend (2), +.BR sigtimedwait (2), +and +.BR sigwaitinfo (2). +.IP * +File descriptor multiplexing interfaces: +.BR epoll_wait (2), +.BR epoll_pwait (2), +.BR poll (2), +.BR ppoll (2), +.BR select (2), +and +.BR pselect (2). +.IP * +System V IPC interfaces: +.\" On some other systems, SA_RESTART does restart these system calls +.BR msgrcv (2), +.BR msgsnd (2), +.BR semop (2), +and +.BR semtimedop (2). +.IP * +Sleep interfaces: +.BR clock_nanosleep (2), +.BR nanosleep (2), +and +.BR usleep (3). +.IP * +.BR io_getevents (2). +.PP +The +.BR sleep (3) +function is also never restarted if interrupted by a handler, +but gives a success return: the number of seconds remaining to sleep. +.SS Interruption of system calls and library functions by stop signals +On Linux, even in the absence of signal handlers, +certain blocking interfaces can fail with the error +.BR EINTR +after the process is stopped by one of the stop signals +and then resumed via +.BR SIGCONT . +This behavior is not sanctioned by POSIX.1, and doesn't occur +on other systems. +.PP +The Linux interfaces that display this behavior are: +.IP * 2 +"Input" socket interfaces, when a timeout +.RB ( SO_RCVTIMEO ) +has been set on the socket using +.BR setsockopt (2): +.BR accept (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmmsg (2) +(also with a non-NULL +.IR timeout +argument), +and +.BR recvmsg (2). +.IP * +"Output" socket interfaces, when a timeout +.RB ( SO_RCVTIMEO ) +has been set on the socket using +.BR setsockopt (2): +.BR connect (2), +.BR send (2), +.BR sendto (2), +and +.\" FIXME What about sendmmsg()? +.BR sendmsg (2), +if a send timeout +.RB ( SO_SNDTIMEO ) +has been set. +.IP * 2 +.BR epoll_wait (2), +.BR epoll_pwait (2). +.IP * +.BR semop (2), +.BR semtimedop (2). +.IP * +.BR sigtimedwait (2), +.BR sigwaitinfo (2). +.IP * +Linux 3.7 and earlier: +.BR read (2) +from an +.BR inotify (7) +file descriptor +.\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06 +.IP * +Linux 2.6.21 and earlier: +.BR futex (2) +.BR FUTEX_WAIT , +.BR sem_timedwait (3), +.BR sem_wait (3). +.IP * +Linux 2.6.8 and earlier: +.BR msgrcv (2), +.BR msgsnd (2). +.IP * +Linux 2.4 and earlier: +.BR nanosleep (2). +.SH CONFORMING TO +POSIX.1, except as noted. +.\" It must be a *very* long time since this was true: +.\" .SH BUGS +.\" .B SIGIO +.\" and +.\" .B SIGLOST +.\" have the same value. +.\" The latter is commented out in the kernel source, but +.\" the build process of some software still thinks that +.\" signal 29 is +.\" .BR SIGLOST . +.SH NOTES +For a discussion of async-signal-safe functions, see +.BR signal-safety (7). +.SH SEE ALSO +.BR kill (1), +.BR getrlimit (2), +.BR kill (2), +.BR restart_syscall (2), +.BR rt_sigqueueinfo (2), +.BR setitimer (2), +.BR setrlimit (2), +.BR sgetmask (2), +.BR sigaction (2), +.BR sigaltstack (2), +.BR signal (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigreturn (2), +.BR sigsuspend (2), +.BR sigwaitinfo (2), +.BR abort (3), +.BR bsd_signal (3), +.BR killpg (3), +.BR longjmp (3), +.BR pthread_sigqueue (3), +.BR raise (3), +.BR sigqueue (3), +.BR sigset (3), +.BR sigsetops (3), +.BR sigvec (3), +.BR sigwait (3), +.BR strsignal (3), +.BR sysv_signal (3), +.BR core (5), +.BR proc (5), +.BR nptl (7), +.BR pthreads (7), +.BR sigevent (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/sock_diag.7 b/man7/sock_diag.7 new file mode 100644 index 0000000..4509f0a --- /dev/null +++ b/man7/sock_diag.7 @@ -0,0 +1,851 @@ +.\" Copyright (c) 2016 Pavel Emelyanov +.\" Copyright (c) 2016 Dmitry V. Levin +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.TH SOCK_DIAG 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +sock_diag \- obtaining information about sockets +.SH SYNOPSIS +.nf +.B #include +.B #include +.BR "#include " " /* for UNIX domain sockets */" +.BR "#include " " /* for IPv4 and IPv6 sockets */" +.PP +.BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);" +.fi +.SH DESCRIPTION +The sock_diag netlink subsystem provides a mechanism for obtaining +information about sockets of various address families from the kernel. +This subsystem can be used to obtain information about individual +sockets or request a list of sockets. +.PP +In the request, the caller can specify additional information it would +like to obtain about the socket, for example, memory information or +information specific to the address family. +.PP +When requesting a list of sockets, the caller can specify filters that +would be applied by the kernel to select a subset of sockets to report. +For now, there is only the ability to filter sockets by state (connected, +listening, and so on.) +.PP +Note that sock_diag reports only those sockets that have a name; +that is, either sockets bound explicitly with +.BR bind (2) +or sockets that were automatically bound to an address (e.g., by +.BR connect (2)). +This is the same set of sockets that is available via +.IR /proc/net/unix , +.IR /proc/net/tcp , +.IR /proc/net/udp , +and so on. +.\" +.SS Request +The request starts with a +.I "struct nlmsghdr" +header described in +.BR netlink (7) +with +.I nlmsg_type +field set to +.BR SOCK_DIAG_BY_FAMILY . +It is followed by a header specific to the address family that starts with +a common part shared by all address families: +.PP +.in +4n +.EX +struct sock_diag_req { + __u8 sdiag_family; + __u8 sdiag_protocol; +}; +.EE +.in +.PP +The fields of this structure are as follows: +.TP +.I sdiag_family +An address family. +It should be set to the appropriate +.B AF_* +constant. +.TP +.I sdiag_protocol +Depends on +.IR sdiag_family . +It should be set to the appropriate +.B IPPROTO_* +constant for +.B AF_INET +and +.BR AF_INET6, +and to 0 otherwise. +.PP +If the +.I nlmsg_flags +field of the +.I "struct nlmsghdr" +header has the +.BR NLM_F_DUMP +flag set, it means that a list of sockets is being requested; +otherwise it is a query about an individual socket. +.\" +.SS Response +The response starts with a +.I "struct nlmsghdr" +header and is followed by an array of objects specific to the address family. +The array is to be accessed with the standard +.B NLMSG_* +macros from the +.BR netlink (3) +API. +.PP +Each object is the NLA (netlink attributes) list that is to be accessed +with the +.B RTA_* +macros from +.BR rtnetlink (3) +API. +.\" +.SS UNIX domain sockets +For UNIX domain sockets the request is represented in the following structure: +.PP +.in +4n +.EX +struct unix_diag_req { + __u8 sdiag_family; + __u8 sdiag_protocol; + __u16 pad; + __u32 udiag_states; + __u32 udiag_ino; + __u32 udiag_show; + __u32 udiag_cookie[2]; +}; +.EE +.in +.PP +The fields of this structure are as follows: +.TP +.I sdiag_family +The address family; it should be set to +.BR AF_UNIX . +.PP +.I sdiag_protocol +.PD 0 +.TP +.PD +.I pad +These fields should be set to 0. +.TP +.I udiag_states +This is a bit mask that defines a filter of sockets states. +Only those sockets whose states are in this mask will be reported. +Ignored when querying for an individual socket. +Supported values are: +.PP +.RS 12 +1 << +.B TCP_ESTABLISHED +.PP +1 << +.B TCP_LISTEN +.RE +.TP +.I udiag_ino +This is an inode number when querying for an individual socket. +Ignored when querying for a list of sockets. +.TP +.I udiag_show +This is a set of flags defining what kind of information to report. +Each requested kind of information is reported back as a netlink +attribute as described below: +.RS +.TP +.B UDIAG_SHOW_NAME +The attribute reported in answer to this request is +.BR UNIX_DIAG_NAME . +The payload associated with this attribute is the pathname to which +the socket was bound (a sequence of bytes up to +.B UNIX_PATH_MAX +length). +.TP +.B UDIAG_SHOW_VFS +The attribute reported in answer to this request is +.BR UNIX_DIAG_VFS . +The payload associated with this attribute is represented in the following +structure: +.IP +.in +4n +.EX +struct unix_diag_vfs { + __u32 udiag_vfs_dev; + __u32 udiag_vfs_ino; +}; +.EE +.in +.IP +The fields of this structure are as follows: +.RS +.TP +.I udiag_vfs_dev +The device number of the corresponding on-disk socket inode. +.TP +.I udiag_vfs_ino +The inode number of the corresponding on-disk socket inode. +.RE +.TP +.B UDIAG_SHOW_PEER +The attribute reported in answer to this request is +.BR UNIX_DIAG_PEER . +The payload associated with this attribute is a __u32 value +which is the peer's inode number. +This attribute is reported for connected sockets only. +.TP +.B UDIAG_SHOW_ICONS +The attribute reported in answer to this request is +.BR UNIX_DIAG_ICONS . +The payload associated with this attribute is an array of __u32 values +which are inode numbers of sockets that has passed the +.BR connect (2) +call, but hasn't been processed with +.BR accept (2) +yet. +This attribute is reported for listening sockets only. +.TP +.B UDIAG_SHOW_RQLEN +The attribute reported in answer to this request is +.BR UNIX_DIAG_RQLEN . +The payload associated with this attribute is represented in the following +structure: +.IP +.in +4n +.EX +struct unix_diag_rqlen { + __u32 udiag_rqueue; + __u32 udiag_wqueue; +}; +.EE +.in +.IP +The fields of this structure are as follows: +.RS +.TP +.I udiag_rqueue +For listening sockets: +the number of pending connections. +The length of the array associated with the +.B UNIX_DIAG_ICONS +response attribute is equal to this value. +.IP +For established sockets: +the amount of data in incoming queue. +.TP +.I udiag_wqueue +For listening sockets: +the backlog length which equals to the value passed as the second argument to +.BR listen (2). +.IP +For established sockets: +the amount of memory available for sending. +.RE +.TP +.B UDIAG_SHOW_MEMINFO +The attribute reported in answer to this request is +.BR UNIX_DIAG_MEMINFO . +The payload associated with this attribute is an array of __u32 values +described below in the subsection "Socket memory information". +.PP +The following attributes are reported back without any specific request: +.TP +.BR UNIX_DIAG_SHUTDOWN +The payload associated with this attribute is __u8 value which represents +bits of +.BR shutdown (2) +state. +.RE +.TP +.I udiag_cookie +This is an array of opaque identifiers that could be used along with +.I udiag_ino +to specify an individual socket. +It is ignored when querying for a list +of sockets, as well as when all its elements are set to \-1. +.PP +The response to a query for UNIX domain sockets is represented as an array of +.PP +.in +4n +.EX +struct unix_diag_msg { + __u8 udiag_family; + __u8 udiag_type; + __u8 udiag_state; + __u8 pad; + __u32 udiag_ino; + __u32 udiag_cookie[2]; +}; +.EE +.in +.PP +followed by netlink attributes. +.PP +The fields of this structure are as follows: +.TP +.I udiag_family +This field has the same meaning as in +.IR "struct unix_diag_req" . +.TP +.I udiag_type +This is set to one of +.BR SOCK_PACKET , +.BR SOCK_STREAM , +or +.BR SOCK_SEQPACKET . +.TP +.I udiag_state +This is set to one of +.BR TCP_LISTEN +or +.BR TCP_ESTABLISHED . +.TP +.I pad +This field is set to 0. +.TP +.I udiag_ino +This is the socket inode number. +.TP +.I udiag_cookie +This is an array of opaque identifiers that could be used in subsequent +queries. +.\" +.SS IPv4 and IPv6 sockets +For IPv4 and IPv6 sockets, +the request is represented in the following structure: +.PP +.in +4n +.EX +struct inet_diag_req_v2 { + __u8 sdiag_family; + __u8 sdiag_protocol; + __u8 idiag_ext; + __u8 pad; + __u32 idiag_states; + struct inet_diag_sockid id; +}; +.EE +.in +.PP +where +.I "struct inet_diag_sockid" +is defined as follows: +.PP +.in +4n +.EX +struct inet_diag_sockid { + __be16 idiag_sport; + __be16 idiag_dport; + __be32 idiag_src[4]; + __be32 idiag_dst[4]; + __u32 idiag_if; + __u32 idiag_cookie[2]; +}; +.EE +.in +.PP +The fields of +.I "struct inet_diag_req_v2" +are as follows: +.TP +.I sdiag_family +This should be set to either +.B AF_INET +or +.B AF_INET6 +for IPv4 or IPv6 sockets respectively. +.TP +.I sdiag_protocol +This should be set to one of +.BR IPPROTO_TCP , +.BR IPPROTO_UDP , +or +.BR IPPROTO_UDPLITE . +.TP +.I idiag_ext +This is a set of flags defining what kind of extended information to report. +Each requested kind of information is reported back as a netlink attribute +as described below: +.RS +.TP +.B INET_DIAG_TOS +The payload associated with this attribute is a __u8 value +which is the TOS of the socket. +.TP +.B INET_DIAG_TCLASS +The payload associated with this attribute is a __u8 value +which is the TClass of the socket. +IPv6 sockets only. +For LISTEN and CLOSE sockets, this is followed by +.B INET_DIAG_SKV6ONLY +attribute with associated __u8 payload value meaning whether the socket +is IPv6-only or not. +.TP +.B INET_DIAG_MEMINFO +The payload associated with this attribute is represented in the following +structure: +.IP +.in +4n +.EX +struct inet_diag_meminfo { + __u32 idiag_rmem; + __u32 idiag_wmem; + __u32 idiag_fmem; + __u32 idiag_tmem; +}; +.EE +.in +.IP +The fields of this structure are as follows: +.RS +.TP 12 +.I idiag_rmem +The amount of data in the receive queue. +.TP +.I idiag_wmem +The amount of data that is queued by TCP but not yet sent. +.TP +.I idiag_fmem +The amount of memory scheduled for future use (TCP only). +.TP +.I idiag_tmem +The amount of data in send queue. +.RE +.TP +.B INET_DIAG_SKMEMINFO +The payload associated with this attribute is an array of __u32 values +described below in the subsection "Socket memory information". +.TP +.B INET_DIAG_INFO +The payload associated with this attribute is specific to the address family. +For TCP sockets, it is an object of type +.IR "struct tcp_info" . +.TP +.B INET_DIAG_CONG +The payload associated with this attribute is a string that describes the +congestion control algorithm used. +For TCP sockets only. +.RE +.TP +.I pad +This should be set to 0. +.TP +.I idiag_states +This is a bit mask that defines a filter of socket states. +Only those sockets whose states are in this mask will be reported. +Ignored when querying for an individual socket. +.TP +.I id +This is a socket ID object that is used in dump requests, in queries +about individual sockets, and is reported back in each response. +Unlike UNIX domain sockets, IPv4 and IPv6 sockets are identified +using addresses and ports. +All values are in network byte order. +.PP +The fields of +.I "struct inet_diag_sockid" +are as follows: +.TP +.I idiag_sport +The source port. +.TP +.I idiag_dport +The destination port. +.TP +.I idiag_src +The source address. +.TP +.I idiag_dst +The destination address. +.TP +.I idiag_if +The interface number the socket is bound to. +.TP +.I idiag_cookie +This is an array of opaque identifiers that could be used along with +other fields of this structure to specify an individual socket. +It is ignored when querying for a list of sockets, as well as +when all its elements are set to \-1. +.PP +The response to a query for IPv4 or IPv6 sockets is represented as an array of +.PP +.in +4n +.EX +struct inet_diag_msg { + __u8 idiag_family; + __u8 idiag_state; + __u8 idiag_timer; + __u8 idiag_retrans; + + struct inet_diag_sockid id; + + __u32 idiag_expires; + __u32 idiag_rqueue; + __u32 idiag_wqueue; + __u32 idiag_uid; + __u32 idiag_inode; +}; +.EE +.in +.PP +followed by netlink attributes. +.PP +The fields of this structure are as follows: +.TP +.I idiag_family +This is the same field as in +.IR "struct inet_diag_req_v2" . +.TP +.I idiag_state +This denotes socket state as in +.IR "struct inet_diag_req_v2" . +.TP +.I idiag_timer +For TCP sockets, this field describes the type of timer that is currently +active for the socket. +It is set to one of the following constants: +.IP +.PD 0 +.RS 12 +.TP +.B 0 +no timer is active +.TP +.B 1 +a retransmit timer +.TP +.B 2 +a keep-alive timer +.TP +.B 3 +a TIME_WAIT timer +.TP +.B 4 +a zero window probe timer +.RE +.PD +.IP +For non-TCP sockets, this field is set to 0. +.TP +.I idiag_retrans +For +.I idiag_timer +values 1, 2, and 4, this field contains the number of retransmits. +For other +.I idiag_timer +values, this field is set to 0. +.TP +.I idiag_expires +For TCP sockets that have an active timer, this field describes its expiration +time in milliseconds. +For other sockets, this field is set to 0. +.TP +.I idiag_rqueue +For listening sockets: +the number of pending connections. +.IP +For other sockets: +the amount of data in the incoming queue. +.TP +.I idiag_wqueue +For listening sockets: +the backlog length. +.IP +For other sockets: +the amount of memory available for sending. +.TP +.I idiag_uid +This is the socket owner UID. +.TP +.I idiag_inode +This is the socket inode number. +.\" +.SS Socket memory information +The payload associated with +.B UNIX_DIAG_MEMINFO +and +.BR INET_DIAG_SKMEMINFO +netlink attributes is an array of the following __u32 values: +.TP +.B SK_MEMINFO_RMEM_ALLOC +The amount of data in receive queue. +.TP +.B SK_MEMINFO_RCVBUF +The receive socket buffer as set by +.BR SO_RCVBUF . +.TP +.B SK_MEMINFO_WMEM_ALLOC +The amount of data in send queue. +.TP +.B SK_MEMINFO_SNDBUF +The send socket buffer as set by +.BR SO_SNDBUF . +.TP +.B SK_MEMINFO_FWD_ALLOC +The amount of memory scheduled for future use (TCP only). +.TP +.B SK_MEMINFO_WMEM_QUEUED +The amount of data queued by TCP, but not yet sent. +.TP +.B SK_MEMINFO_OPTMEM +The amount of memory allocated for the socket's service needs (e.g., socket +filter). +.TP +.B SK_MEMINFO_BACKLOG +The amount of packets in the backlog (not yet processed). +.SH VERSIONS +.B NETLINK_INET_DIAG +was introduced in Linux 2.6.14 and supported +.B AF_INET +and +.B AF_INET6 +sockets only. +In Linux 3.3, it was renamed to +.B NETLINK_SOCK_DIAG +and extended to support +.B AF_UNIX +sockets. +.PP +.B UNIX_DIAG_MEMINFO +and +.BR INET_DIAG_SKMEMINFO +were introduced in Linux 3.6. +.SH CONFORMING TO +The NETLINK_SOCK_DIAG API is Linux-specific. +.SH EXAMPLE +The following example program prints inode number, peer's inode number, +and name of all UNIX domain sockets in the current namespace. +.PP +.EX +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +static int +send_query(int fd) +{ + struct sockaddr_nl nladdr = { + .nl_family = AF_NETLINK + }; + struct + { + struct nlmsghdr nlh; + struct unix_diag_req udr; + } req = { + .nlh = { + .nlmsg_len = sizeof(req), + .nlmsg_type = SOCK_DIAG_BY_FAMILY, + .nlmsg_flags = NLM_F_REQUEST | NLM_F_DUMP + }, + .udr = { + .sdiag_family = AF_UNIX, + .udiag_states = \-1, + .udiag_show = UDIAG_SHOW_NAME | UDIAG_SHOW_PEER + } + }; + struct iovec iov = { + .iov_base = &req, + .iov_len = sizeof(req) + }; + struct msghdr msg = { + .msg_name = (void *) &nladdr, + .msg_namelen = sizeof(nladdr), + .msg_iov = &iov, + .msg_iovlen = 1 + }; + + for (;;) { + if (sendmsg(fd, &msg, 0) < 0) { + if (errno == EINTR) + continue; + + perror("sendmsg"); + return \-1; + } + + return 0; + } +} + +static int +print_diag(const struct unix_diag_msg *diag, unsigned int len) +{ + if (len < NLMSG_LENGTH(sizeof(*diag))) { + fputs("short response\\n", stderr); + return \-1; + } + if (diag\->udiag_family != AF_UNIX) { + fprintf(stderr, "unexpected family %u\\n", diag\->udiag_family); + return \-1; + } + + struct rtattr *attr; + unsigned int rta_len = len \- NLMSG_LENGTH(sizeof(*diag)); + unsigned int peer = 0; + size_t path_len = 0; + char path[sizeof(((struct sockaddr_un *) 0)\->sun_path) + 1]; + + for (attr = (struct rtattr *) (diag + 1); + RTA_OK(attr, rta_len); attr = RTA_NEXT(attr, rta_len)) { + switch (attr\->rta_type) { + case UNIX_DIAG_NAME: + if (!path_len) { + path_len = RTA_PAYLOAD(attr); + if (path_len > sizeof(path) \- 1) + path_len = sizeof(path) \- 1; + memcpy(path, RTA_DATA(attr), path_len); + path[path_len] = '\\0'; + } + break; + + case UNIX_DIAG_PEER: + if (RTA_PAYLOAD(attr) >= sizeof(peer)) + peer = *(unsigned int *) RTA_DATA(attr); + break; + } + } + + printf("inode=%u", diag->udiag_ino); + + if (peer) + printf(", peer=%u", peer); + + if (path_len) + printf(", name=%s%s", *path ? "" : "@", + *path ? path : path + 1); + + putchar('\\n'); + return 0; +} + +static int +receive_responses(int fd) +{ + long buf[8192 / sizeof(long)]; + struct sockaddr_nl nladdr = { + .nl_family = AF_NETLINK + }; + struct iovec iov = { + .iov_base = buf, + .iov_len = sizeof(buf) + }; + int flags = 0; + + for (;;) { + struct msghdr msg = { + .msg_name = (void *) &nladdr, + .msg_namelen = sizeof(nladdr), + .msg_iov = &iov, + .msg_iovlen = 1 + }; + + ssize_t ret = recvmsg(fd, &msg, flags); + + if (ret < 0) { + if (errno == EINTR) + continue; + + perror("recvmsg"); + return \-1; + } + if (ret == 0) + return 0; + + const struct nlmsghdr *h = (struct nlmsghdr *) buf; + + if (!NLMSG_OK(h, ret)) { + fputs("!NLMSG_OK\\n", stderr); + return \-1; + } + + for (; NLMSG_OK(h, ret); h = NLMSG_NEXT(h, ret)) { + if (h\->nlmsg_type == NLMSG_DONE) + return 0; + + if (h\->nlmsg_type == NLMSG_ERROR) { + const struct nlmsgerr *err = NLMSG_DATA(h); + + if (h\->nlmsg_len < NLMSG_LENGTH(sizeof(*err))) { + fputs("NLMSG_ERROR\\n", stderr); + } else { + errno = \-err\->error; + perror("NLMSG_ERROR"); + } + + return \-1; + } + + if (h\->nlmsg_type != SOCK_DIAG_BY_FAMILY) { + fprintf(stderr, "unexpected nlmsg_type %u\\n", + (unsigned) h\->nlmsg_type); + return \-1; + } + + if (print_diag(NLMSG_DATA(h), h\->nlmsg_len)) + return \-1; + } + } +} + +int +main(void) +{ + int fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_SOCK_DIAG); + + if (fd < 0) { + perror("socket"); + return 1; + } + + int ret = send_query(fd) || receive_responses(fd); + + close(fd); + return ret; +} +.EE +.SH SEE ALSO +.BR netlink (3), +.BR rtnetlink (3), +.BR netlink (7), +.BR tcp (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/socket.7 b/man7/socket.7 new file mode 100644 index 0000000..06c50cb --- /dev/null +++ b/man7/socket.7 @@ -0,0 +1,1181 @@ +'\" t +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" and copyright (c) 1999 Matthew Wilcox. +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" 2002-10-30, Michael Kerrisk, +.\" Added description of SO_ACCEPTCONN +.\" 2004-05-20, aeb, added SO_RCVTIMEO/SO_SNDTIMEO text. +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" A few small grammar fixes +.\" 2010-06-13 Jan Engelhardt +.\" Documented SO_DOMAIN and SO_PROTOCOL. +.\" +.\" FIXME +.\" The following are not yet documented: +.\" +.\" SO_PEERNAME (2.4?) +.\" get only +.\" Seems to do something similar to getpeername(), but then +.\" why is it necessary / how does it differ? +.\" +.\" SO_TIMESTAMPNS (2.6.22) +.\" Documentation/networking/timestamping.txt +.\" commit 92f37fd2ee805aa77925c1e64fd56088b46094fc +.\" Author: Eric Dumazet +.\" +.\" SO_TIMESTAMPING (2.6.30) +.\" Documentation/networking/timestamping.txt +.\" commit cb9eff097831007afb30d64373f29d99825d0068 +.\" Author: Patrick Ohly +.\" +.\" SO_WIFI_STATUS (3.3) +.\" commit 6e3e939f3b1bf8534b32ad09ff199d88800835a0 +.\" Author: Johannes Berg +.\" Also: SCM_WIFI_STATUS +.\" +.\" SO_NOFCS (3.4) +.\" commit 3bdc0eba0b8b47797f4a76e377dd8360f317450f +.\" Author: Ben Greear +.\" +.\" SO_GET_FILTER (3.8) +.\" commit a8fc92778080c845eaadc369a0ecf5699a03bef0 +.\" Author: Pavel Emelyanov +.\" +.\" SO_SELECT_ERR_QUEUE (3.10) +.\" commit 7d4c04fc170087119727119074e72445f2bb192b +.\" Author: Keller, Jacob E +.\" +.\" SO_MAX_PACING_RATE (3.13) +.\" commit 62748f32d501f5d3712a7c372bbb92abc7c62bc7 +.\" Author: Eric Dumazet +.\" +.\" SO_BPF_EXTENSIONS (3.14) +.\" commit ea02f9411d9faa3553ed09ce0ec9f00ceae9885e +.\" Author: Michal Sekletar +.\" +.TH SOCKET 7 2018-02-02 Linux "Linux Programmer's Manual" +.SH NAME +socket \- Linux socket interface +.SH SYNOPSIS +.B #include +.PP +.IB sockfd " = socket(int " socket_family ", int " socket_type ", int " protocol ); +.SH DESCRIPTION +This manual page describes the Linux networking socket layer user +interface. +The BSD compatible sockets +are the uniform interface +between the user process and the network protocol stacks in the kernel. +The protocol modules are grouped into +.I protocol families +such as +.BR AF_INET ", " AF_IPX ", and " AF_PACKET , +and +.I socket types +such as +.B SOCK_STREAM +or +.BR SOCK_DGRAM . +See +.BR socket (2) +for more information on families and types. +.SS Socket-layer functions +These functions are used by the user process to send or receive packets +and to do other socket operations. +For more information see their respective manual pages. +.PP +.BR socket (2) +creates a socket, +.BR connect (2) +connects a socket to a remote socket address, +the +.BR bind (2) +function binds a socket to a local socket address, +.BR listen (2) +tells the socket that new connections shall be accepted, and +.BR accept (2) +is used to get a new socket with a new incoming connection. +.BR socketpair (2) +returns two connected anonymous sockets (implemented only for a few +local families like +.BR AF_UNIX ) +.PP +.BR send (2), +.BR sendto (2), +and +.BR sendmsg (2) +send data over a socket, and +.BR recv (2), +.BR recvfrom (2), +.BR recvmsg (2) +receive data from a socket. +.BR poll (2) +and +.BR select (2) +wait for arriving data or a readiness to send data. +In addition, the standard I/O operations like +.BR write (2), +.BR writev (2), +.BR sendfile (2), +.BR read (2), +and +.BR readv (2) +can be used to read and write data. +.PP +.BR getsockname (2) +returns the local socket address and +.BR getpeername (2) +returns the remote socket address. +.BR getsockopt (2) +and +.BR setsockopt (2) +are used to set or get socket layer or protocol options. +.BR ioctl (2) +can be used to set or read some other options. +.PP +.BR close (2) +is used to close a socket. +.BR shutdown (2) +closes parts of a full-duplex socket connection. +.PP +Seeking, or calling +.BR pread (2) +or +.BR pwrite (2) +with a nonzero position is not supported on sockets. +.PP +It is possible to do nonblocking I/O on sockets by setting the +.B O_NONBLOCK +flag on a socket file descriptor using +.BR fcntl (2). +Then all operations that would block will (usually) +return with +.B EAGAIN +(operation should be retried later); +.BR connect (2) +will return +.B EINPROGRESS +error. +The user can then wait for various events via +.BR poll (2) +or +.BR select (2). +.TS +tab(:) allbox; +c s s +l l l. +I/O events +Event:Poll flag:Occurrence +Read:POLLIN:T{ +New data arrived. +T} +Read:POLLIN:T{ +A connection setup has been completed +(for connection-oriented sockets) +T} +Read:POLLHUP:T{ +A disconnection request has been initiated by the other end. +T} +Read:POLLHUP:T{ +A connection is broken (only for connection-oriented protocols). +When the socket is written +.B SIGPIPE +is also sent. +T} +Write:POLLOUT:T{ +Socket has enough send buffer space for writing new data. +T} +Read/Write:T{ +POLLIN | +.br +POLLOUT +T}:T{ +An outgoing +.BR connect (2) +finished. +T} +Read/Write:POLLERR:An asynchronous error occurred. +Read/Write:POLLHUP:The other end has shut down one direction. +Exception:POLLPRI:T{ +Urgent data arrived. +.B SIGURG +is sent then. +T} +.\" FIXME . The following is not true currently: +.\" It is no I/O event when the connection +.\" is broken from the local end using +.\" .BR shutdown (2) +.\" or +.\" .BR close (2). +.TE +.PP +An alternative to +.BR poll (2) +and +.BR select (2) +is to let the kernel inform the application about events +via a +.B SIGIO +signal. +For that the +.B O_ASYNC +flag must be set on a socket file descriptor via +.BR fcntl (2) +and a valid signal handler for +.B SIGIO +must be installed via +.BR sigaction (2). +See the +.I Signals +discussion below. +.SS Socket address structures +Each socket domain has its own format for socket addresses, +with a domain-specific address structure. +Each of these structures begins with an +integer "family" field (typed as +.IR sa_family_t ) +that indicates the type of the address structure. +This allows +the various system calls (e.g., +.BR connect (2), +.BR bind (2), +.BR accept (2), +.BR getsockname (2), +.BR getpeername (2)), +which are generic to all socket domains, +to determine the domain of a particular socket address. +.PP +To allow any type of socket address to be passed to +interfaces in the sockets API, +the type +.IR "struct sockaddr" +is defined. +The purpose of this type is purely to allow casting of +domain-specific socket address types to a "generic" type, +so as to avoid compiler warnings about type mismatches in +calls to the sockets API. +.PP +In addition, the sockets API provides the data type +.IR "struct sockaddr_storage". +This type +is suitable to accommodate all supported domain-specific socket +address structures; it is large enough and is aligned properly. +(In particular, it is large enough to hold +IPv6 socket addresses.) +The structure includes the following field, which can be used to identify +the type of socket address actually stored in the structure: +.PP +.in +4n +.EX + sa_family_t ss_family; +.EE +.in +.PP +The +.I sockaddr_storage +structure is useful in programs that must handle socket addresses +in a generic way +(e.g., programs that must deal with both IPv4 and IPv6 socket addresses). +.SS Socket options +The socket options listed below can be set by using +.BR setsockopt (2) +and read with +.BR getsockopt (2) +with the socket level set to +.B SOL_SOCKET +for all sockets. +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.\" FIXME . +.\" In the list below, the text used to describe argument types +.\" for each socket option should be more consistent +.\" +.\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in +.\" W R Stevens, UNPv1 +.TP +.B SO_ACCEPTCONN +Returns a value indicating whether or not this socket has been marked +to accept connections with +.BR listen (2). +The value 0 indicates that this is not a listening socket, +the value 1 indicates that this is a listening socket. +This socket option is read-only. +.TP +.BR SO_ATTACH_FILTER " (since Linux 2.2), " SO_ATTACH_BPF " (since Linux 3.19)" +Attach a classic BPF +.RB ( SO_ATTACH_FILTER ) +or an extended BPF +.RB ( SO_ATTACH_BPF ) +program to the socket for use as a filter of incoming packets. +A packet will be dropped if the filter program returns zero. +If the filter program returns a +nonzero value which is less than the packet's data length, +the packet will be truncated to the length returned. +If the value returned by the filter is greater than or equal to the +packet's data length, the packet is allowed to proceed unmodified. +.IP +The argument for +.BR SO_ATTACH_FILTER +is a +.I sock_fprog +structure, defined in +.IR : +.IP +.in +4n +.EX +struct sock_fprog { + unsigned short len; + struct sock_filter *filter; +}; +.EE +.in +.IP +The argument for +.BR SO_ATTACH_BPF +is a file descriptor returned by the +.BR bpf (2) +system call and must refer to a program of type +.BR BPF_PROG_TYPE_SOCKET_FILTER. +.IP +These options may be set multiple times for a given socket, +each time replacing the previous filter program. +The classic and extended versions may be called on the same socket, +but the previous filter will always be replaced such that a socket +never has more than one filter defined. +.IP +Both classic and extended BPF are explained in the kernel source file +.I Documentation/networking/filter.txt +.TP +.BR SO_ATTACH_REUSEPORT_CBPF ", " SO_ATTACH_REUSEPORT_EBPF +For use with the +.BR SO_REUSEPORT +option, these options allow the user to set a classic BPF +.RB ( SO_ATTACH_REUSEPORT_CBPF ) +or an extended BPF +.RB ( SO_ATTACH_REUSEPORT_EBPF ) +program which defines how packets are assigned to +the sockets in the reuseport group (that is, all sockets which have +.BR SO_REUSEPORT +set and are using the same local address to receive packets). +.IP +The BPF program must return an index between 0 and N\-1 representing +the socket which should receive the packet +(where N is the number of sockets in the group). +If the BPF program returns an invalid index, +socket selection will fall back to the plain +.BR SO_REUSEPORT +mechanism. +.IP +Sockets are numbered in the order in which they are added to the group +(that is, the order of +.BR bind (2) +calls for UDP sockets or the order of +.BR listen (2) +calls for TCP sockets). +New sockets added to a reuseport group will inherit the BPF program. +When a socket is removed from a reuseport group (via +.BR close (2)), +the last socket in the group will be moved into the closed socket's +position. +.IP +These options may be set repeatedly at any time on any socket in the group +to replace the current BPF program used by all sockets in the group. +.IP +.BR SO_ATTACH_REUSEPORT_CBPF +takes the same argument type as +.BR SO_ATTACH_FILTER +and +.BR SO_ATTACH_REUSEPORT_EBPF +takes the same argument type as +.BR SO_ATTACH_BPF. +.IP +UDP support for this feature is available since Linux 4.5; +TCP support is available since Linux 4.6. +.TP +.B SO_BINDTODEVICE +Bind this socket to a particular device like \(lqeth0\(rq, +as specified in the passed interface name. +If the +name is an empty string or the option length is zero, the socket device +binding is removed. +The passed option is a variable-length null-terminated +interface name string with the maximum size of +.BR IFNAMSIZ . +If a socket is bound to an interface, +only packets received from that particular interface are processed by the +socket. +Note that this works only for some socket types, particularly +.B AF_INET +sockets. +It is not supported for packet sockets (use normal +.BR bind (2) +there). +.IP +Before Linux 3.8, +this socket option could be set, but could not retrieved with +.BR getsockopt (2). +Since Linux 3.8, it is readable. +The +.I optlen +argument should contain the buffer size available +to receive the device name and is recommended to be +.BR IFNAMSIZ +bytes. +The real device name length is reported back in the +.I optlen +argument. +.TP +.B SO_BROADCAST +Set or get the broadcast flag. +When enabled, datagram sockets are allowed to send +packets to a broadcast address. +This option has no effect on stream-oriented sockets. +.TP +.B SO_BSDCOMPAT +Enable BSD bug-to-bug compatibility. +This is used by the UDP protocol module in Linux 2.0 and 2.2. +If enabled, ICMP errors received for a UDP socket will not be passed +to the user program. +In later kernel versions, support for this option has been phased out: +Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning +(printk()) if a program uses this option. +Linux 2.0 also enabled BSD bug-to-bug compatibility +options (random header changing, skipping of the broadcast flag) for raw +sockets with this option, but that was removed in Linux 2.2. +.TP +.B SO_DEBUG +Enable socket debugging. +Allowed only for processes with the +.B CAP_NET_ADMIN +capability or an effective user ID of 0. +.TP +.BR SO_DETACH_FILTER " (since Linux 2.2), " SO_DETACH_BPF " (since Linux 3.19)" +These two options, which are synonyms, +may be used to remove the classic or extended BPF +program attached to a socket with either +.BR SO_ATTACH_FILTER +or +.BR SO_ATTACH_BPF . +The option value is ignored. +.TP +.BR SO_DOMAIN " (since Linux 2.6.32)" +Retrieves the socket domain as an integer, returning a value such as +.BR AF_INET6 . +See +.BR socket (2) +for details. +This socket option is read-only. +.TP +.B SO_ERROR +Get and clear the pending socket error. +This socket option is read-only. +Expects an integer. +.TP +.B SO_DONTROUTE +Don't send via a gateway, send only to directly connected hosts. +The same effect can be achieved by setting the +.B MSG_DONTROUTE +flag on a socket +.BR send (2) +operation. +Expects an integer boolean flag. +.TP +.BR SO_INCOMING_CPU " (gettable since Linux 3.19, settable since Linux 4.4)" +.\" getsockopt 2c8c56e15df3d4c2af3d656e44feb18789f75837 +.\" setsockopt 70da268b569d32a9fddeea85dc18043de9d89f89 +Sets or gets the CPU affinity of a socket. +Expects an integer flag. +.IP +.in +4n +.EX +int cpu = 1; +socklen_t len = sizeof(cpu); +setsockopt(fd, SOL_SOCKET, SO_INCOMING_CPU, &cpu, &len); +.EE +.in +.IP +Because all of the packets for a single stream +(i.e., all packets for the same 4-tuple) +arrive on the single RX queue that is associated with a particular CPU, +the typical use case is to employ one listening process per RX queue, +with the incoming flow being handled by a listener +on the same CPU that is handling the RX queue. +This provides optimal NUMA behavior and keeps CPU caches hot. +.\" +.\" From an email conversation with Eric Dumazet: +.\" >> Note that setting the option is not supported if SO_REUSEPORT is used. +.\" > +.\" > Please define "not supported". Does this yield an API diagnostic? +.\" > If so, what is it? +.\" > +.\" >> Socket will be selected from an array, either by a hash or BPF program +.\" >> that has no access to this information. +.\" > +.\" > Sorry -- I'm lost here. How does this comment relate to the proposed +.\" > man page text above? +.\" +.\" Simply that : +.\" +.\" If an application uses both SO_INCOMING_CPU and SO_REUSEPORT, then +.\" SO_REUSEPORT logic, selecting the socket to receive the packet, ignores +.\" SO_INCOMING_CPU setting. +.TP +.B SO_KEEPALIVE +Enable sending of keep-alive messages on connection-oriented sockets. +Expects an integer boolean flag. +.TP +.B SO_LINGER +Sets or gets the +.B SO_LINGER +option. +The argument is a +.I linger +structure. +.IP +.in +4n +.EX +struct linger { + int l_onoff; /* linger active */ + int l_linger; /* how many seconds to linger for */ +}; +.EE +.in +.IP +When enabled, a +.BR close (2) +or +.BR shutdown (2) +will not return until all queued messages for the socket have been +successfully sent or the linger timeout has been reached. +Otherwise, +the call returns immediately and the closing is done in the background. +When the socket is closed as part of +.BR exit (2), +it always lingers in the background. +.TP +.B SO_LOCK_FILTER +.\" commit d59577b6ffd313d0ab3be39cb1ab47e29bdc9182 +When set, this option will prevent +changing the filters associated with the socket. +These filters include any set using the socket options +.BR SO_ATTACH_FILTER, +.BR SO_ATTACH_BPF, +.BR SO_ATTACH_REUSEPORT_CBPF +and +.BR SO_ATTACH_REUSEPORT_EPBF . +.IP +The typical use case is for a privileged process to set up a raw socket +(an operation that requires the +.BR CAP_NET_RAW +capability), apply a restrictive filter, set the +.BR SO_LOCK_FILTER +option, +and then either drop its privileges or pass the socket file descriptor +to an unprivileged process via a UNIX domain socket. +.IP +Once the +.BR SO_LOCK_FILTER +option has been enabled, attempts to change or remove the filter +attached to a socket, or to disable the +.BR SO_LOCK_FILTER +option will fail with the error +.BR EPERM . +.TP +.BR SO_MARK " (since Linux 2.6.25)" +.\" commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0 +.\" and 914a9ab386a288d0f22252fc268ecbc048cdcbd5 +Set the mark for each packet sent through this socket +(similar to the netfilter MARK target but socket-based). +Changing the mark can be used for mark-based +routing without netfilter or for packet filtering. +Setting this option requires the +.B CAP_NET_ADMIN +capability. +.TP +.B SO_OOBINLINE +If this option is enabled, +out-of-band data is directly placed into the receive data stream. +Otherwise, out-of-band data is passed only when the +.B MSG_OOB +flag is set during receiving. +.\" don't document it because it can do too much harm. +.\".B SO_NO_CHECK +.\" The kernel has support for the SO_NO_CHECK socket +.\" option (boolean: 0 == default, calculate checksum on xmit, +.\" 1 == do not calculate checksum on xmit). +.\" Additional note from Andi Kleen on SO_NO_CHECK (2010-08-30) +.\" On Linux UDP checksums are essentially free and there's no reason +.\" to turn them off and it would disable another safety line. +.\" That is why I didn't document the option. +.TP +.B SO_PASSCRED +Enable or disable the receiving of the +.B SCM_CREDENTIALS +control message. +For more information see +.BR unix (7). +.\" FIXME Document SO_PASSSEC, added in 2.6.18; there is some info +.\" in the 2.6.18 ChangeLog +.TP +.BR SO_PEEK_OFF " (since Linux 3.4)" +.\" commit ef64a54f6e558155b4f149bb10666b9e914b6c54 +This option, which is currently supported only for +.BR unix (7) +sockets, sets the value of the "peek offset" for the +.BR recv (2) +system call when used with +.BR MSG_PEEK +flag. +.IP +When this option is set to a negative value +(it is set to \-1 for all new sockets), +traditional behavior is provided: +.BR recv (2) +with the +.BR MSG_PEEK +flag will peek data from the front of the queue. +.IP +When the option is set to a value greater than or equal to zero, +then the next peek at data queued in the socket will occur at +the byte offset specified by the option value. +At the same time, the "peek offset" will be +incremented by the number of bytes that were peeked from the queue, +so that a subsequent peek will return the next data in the queue. +.IP +If data is removed from the front of the queue via a call to +.BR recv (2) +(or similar) without the +.BR MSG_PEEK +flag, the "peek offset" will be decreased by the number of bytes removed. +In other words, receiving data without the +.B MSG_PEEK +flag will cause the "peek offset" to be adjusted to maintain +the correct relative position in the queued data, +so that a subsequent peek will retrieve the data that would have been +retrieved had the data not been removed. +.IP +For datagram sockets, if the "peek offset" points to the middle of a packet, +the data returned will be marked with the +.BR MSG_TRUNC +flag. +.IP +The following example serves to illustrate the use of +.BR SO_PEEK_OFF . +Suppose a stream socket has the following queued input data: +.IP + aabbccddeeff +.IP +The following sequence of +.BR recv (2) +calls would have the effect noted in the comments: +.IP +.in +4n +.EX +int ov = 4; // Set peek offset to 4 +setsockopt(fd, SOL_SOCKET, SO_PEEK_OFF, &ov, sizeof(ov)); + +recv(fd, buf, 2, MSG_PEEK); // Peeks "cc"; offset set to 6 +recv(fd, buf, 2, MSG_PEEK); // Peeks "dd"; offset set to 8 +recv(fd, buf, 2, 0); // Reads "aa"; offset set to 6 +recv(fd, buf, 2, MSG_PEEK); // Peeks "ee"; offset set to 8 +.EE +.in +.TP +.B SO_PEERCRED +Return the credentials of the foreign process connected to this socket. +This is possible only for connected +.B AF_UNIX +stream sockets and +.B AF_UNIX +stream and datagram socket pairs created using +.BR socketpair (2); +see +.BR unix (7). +The returned credentials are those that were in effect at the time +of the call to +.BR connect (2) +or +.BR socketpair (2). +The argument is a +.I ucred +structure; define the +.B _GNU_SOURCE +feature test macro to obtain the definition of that structure from +.IR . +This socket option is read-only. +.TP +.B SO_PRIORITY +Set the protocol-defined priority for all packets to be sent on +this socket. +Linux uses this value to order the networking queues: +packets with a higher priority may be processed first depending +on the selected device queueing discipline. +.\" For +.\" .BR ip (7), +.\" this also sets the IP type-of-service (TOS) field for outgoing packets. +Setting a priority outside the range 0 to 6 requires the +.B CAP_NET_ADMIN +capability. +.TP +.BR SO_PROTOCOL " (since Linux 2.6.32)" +Retrieves the socket protocol as an integer, returning a value such as +.BR IPPROTO_SCTP . +See +.BR socket (2) +for details. +This socket option is read-only. +.TP +.B SO_RCVBUF +Sets or gets the maximum socket receive buffer in bytes. +The kernel doubles this value (to allow space for bookkeeping overhead) +when it is set using +.\" Most (all?) other implementations do not do this -- MTK, Dec 05 +.BR setsockopt (2), +and this doubled value is returned by +.BR getsockopt (2). +.\" The following thread on LMKL is quite informative: +.\" getsockopt/setsockopt with SO_RCVBUF and SO_SNDBUF "non-standard" behavior +.\" 17 July 2012 +.\" http://thread.gmane.org/gmane.linux.kernel/1328935 +The default value is set by the +.I /proc/sys/net/core/rmem_default +file, and the maximum allowed value is set by the +.I /proc/sys/net/core/rmem_max +file. +The minimum (doubled) value for this option is 256. +.TP +.BR SO_RCVBUFFORCE " (since Linux 2.6.14)" +Using this socket option, a privileged +.RB ( CAP_NET_ADMIN ) +process can perform the same task as +.BR SO_RCVBUF , +but the +.I rmem_max +limit can be overridden. +.TP +.BR SO_RCVLOWAT " and " SO_SNDLOWAT +Specify the minimum number of bytes in the buffer until the socket layer +will pass the data to the protocol +.RB ( SO_SNDLOWAT ) +or the user on receiving +.RB ( SO_RCVLOWAT ). +These two values are initialized to 1. +.B SO_SNDLOWAT +is not changeable on Linux +.RB ( setsockopt (2) +fails with the error +.BR ENOPROTOOPT ). +.B SO_RCVLOWAT +is changeable +only since Linux 2.4. +The +.BR select (2) +and +.BR poll (2) +system calls currently do not respect the +.B SO_RCVLOWAT +setting on Linux, +and mark a socket readable when even a single byte of data is available. +A subsequent read from the socket will block until +.B SO_RCVLOWAT +bytes are available. +.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2 +.\" Tested on kernel 2.6.14 -- mtk, 30 Nov 05 +.TP +.BR SO_RCVTIMEO " and " SO_SNDTIMEO +.\" Not implemented in 2.0. +.\" Implemented in 2.1.11 for getsockopt: always return a zero struct. +.\" Implemented in 2.3.41 for setsockopt, and actually used. +Specify the receiving or sending timeouts until reporting an error. +The argument is a +.IR "struct timeval" . +If an input or output function blocks for this period of time, and +data has been sent or received, the return value of that function +will be the amount of data transferred; if no data has been transferred +and the timeout has been reached, then \-1 is returned with +.I errno +set to +.BR EAGAIN +or +.BR EWOULDBLOCK , +.\" in fact to EAGAIN +or +.B EINPROGRESS +(for +.BR connect (2)) +just as if the socket was specified to be nonblocking. +If the timeout is set to zero (the default), +then the operation will never timeout. +Timeouts only have effect for system calls that perform socket I/O (e.g., +.BR read (2), +.BR recvmsg (2), +.BR send (2), +.BR sendmsg (2)); +timeouts have no effect for +.BR select (2), +.BR poll (2), +.BR epoll_wait (2), +and so on. +.TP +.B SO_REUSEADDR +.\" commit c617f398edd4db2b8567a28e899a88f8f574798d +.\" https://lwn.net/Articles/542629/ +Indicates that the rules used in validating addresses supplied in a +.BR bind (2) +call should allow reuse of local addresses. +For +.B AF_INET +sockets this +means that a socket may bind, except when there +is an active listening socket bound to the address. +When the listening socket is bound to +.B INADDR_ANY +with a specific port then it is not possible +to bind to this port for any local address. +Argument is an integer boolean flag. +.TP +.BR SO_REUSEPORT " (since Linux 3.9)" +Permits multiple +.B AF_INET +or +.B AF_INET6 +sockets to be bound to an identical socket address. +This option must be set on each socket (including the first socket) +prior to calling +.BR bind (2) +on the socket. +To prevent port hijacking, +all of the processes binding to the same address must have the same +effective UID. +This option can be employed with both TCP and UDP sockets. +.IP +For TCP sockets, this option allows +.BR accept (2) +load distribution in a multi-threaded server to be improved by +using a distinct listener socket for each thread. +This provides improved load distribution as compared +to traditional techniques such using a single +.BR accept (2)ing +thread that distributes connections, +or having multiple threads that compete to +.BR accept (2) +from the same socket. +.IP +For UDP sockets, +the use of this option can provide better distribution +of incoming datagrams to multiple processes (or threads) as compared +to the traditional technique of having multiple processes +compete to receive datagrams on the same socket. +.TP +.BR SO_RXQ_OVFL " (since Linux 2.6.33)" +.\" commit 3b885787ea4112eaa80945999ea0901bf742707f +Indicates that an unsigned 32-bit value ancillary message (cmsg) +should be attached to received skbs indicating +the number of packets dropped by the socket since its creation. +.TP +.B SO_SNDBUF +Sets or gets the maximum socket send buffer in bytes. +The kernel doubles this value (to allow space for bookkeeping overhead) +when it is set using +.\" Most (all?) other implementations do not do this -- MTK, Dec 05 +.\" See also the comment to SO_RCVBUF (17 Jul 2012 LKML mail) +.BR setsockopt (2), +and this doubled value is returned by +.BR getsockopt (2). +The default value is set by the +.I /proc/sys/net/core/wmem_default +file and the maximum allowed value is set by the +.I /proc/sys/net/core/wmem_max +file. +The minimum (doubled) value for this option is 2048. +.TP +.BR SO_SNDBUFFORCE " (since Linux 2.6.14)" +Using this socket option, a privileged +.RB ( CAP_NET_ADMIN ) +process can perform the same task as +.BR SO_SNDBUF , +but the +.I wmem_max +limit can be overridden. +.TP +.B SO_TIMESTAMP +Enable or disable the receiving of the +.B SO_TIMESTAMP +control message. +The timestamp control message is sent with level +.B SOL_SOCKET +and the +.I cmsg_data +field is a +.I "struct timeval" +indicating the +reception time of the last packet passed to the user in this call. +See +.BR cmsg (3) +for details on control messages. +.TP +.B SO_TYPE +Gets the socket type as an integer (e.g., +.BR SOCK_STREAM ). +This socket option is read-only. +.TP +.BR SO_BUSY_POLL " (since Linux 3.11)" +Sets the approximate time in microseconds to busy poll on a blocking receive +when there is no data. +Increasing this value requires +.BR CAP_NET_ADMIN . +The default for this option is controlled by the +.I /proc/sys/net/core/busy_read +file. +.IP +The value in the +.I /proc/sys/net/core/busy_poll +file determines how long +.BR select (2) +and +.BR poll (2) +will busy poll when they operate on sockets with +.BR SO_BUSY_POLL +set and no events to report are found. +.IP +In both cases, +busy polling will only be done when the socket last received data +from a network device that supports this option. +.IP +While busy polling may improve latency of some applications, +care must be taken when using it since this will increase +both CPU utilization and power usage. +.SS Signals +When writing onto a connection-oriented socket that has been shut down +(by the local or the remote end) +.B SIGPIPE +is sent to the writing process and +.B EPIPE +is returned. +The signal is not sent when the write call +specified the +.B MSG_NOSIGNAL +flag. +.PP +When requested with the +.B FIOSETOWN +.BR fcntl (2) +or +.B SIOCSPGRP +.BR ioctl (2), +.B SIGIO +is sent when an I/O event occurs. +It is possible to use +.BR poll (2) +or +.BR select (2) +in the signal handler to find out which socket the event occurred on. +An alternative (in Linux 2.2) is to set a real-time signal using the +.B F_SETSIG +.BR fcntl (2); +the handler of the real time signal will be called with +the file descriptor in the +.I si_fd +field of its +.IR siginfo_t . +See +.BR fcntl (2) +for more information. +.PP +Under some circumstances (e.g., multiple processes accessing a +single socket), the condition that caused the +.B SIGIO +may have already disappeared when the process reacts to the signal. +If this happens, the process should wait again because Linux +will resend the signal later. +.\" .SS Ancillary messages +.SS /proc interfaces +The core socket networking parameters can be accessed +via files in the directory +.IR /proc/sys/net/core/ . +.TP +.I rmem_default +contains the default setting in bytes of the socket receive buffer. +.TP +.I rmem_max +contains the maximum socket receive buffer size in bytes which a user may +set by using the +.B SO_RCVBUF +socket option. +.TP +.I wmem_default +contains the default setting in bytes of the socket send buffer. +.TP +.I wmem_max +contains the maximum socket send buffer size in bytes which a user may +set by using the +.B SO_SNDBUF +socket option. +.TP +.IR message_cost " and " message_burst +configure the token bucket filter used to load limit warning messages +caused by external network events. +.TP +.I netdev_max_backlog +Maximum number of packets in the global input queue. +.TP +.I optmem_max +Maximum length of ancillary data and user control data like the iovecs +per socket. +.\" netdev_fastroute is not documented because it is experimental +.SS Ioctls +These operations can be accessed using +.BR ioctl (2): +.PP +.in +4n +.EX +.IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" +.EE +.in +.TP +.B SIOCGSTAMP +Return a +.I struct timeval +with the receive timestamp of the last packet passed to the user. +This is useful for accurate round trip time measurements. +See +.BR setitimer (2) +for a description of +.IR "struct timeval" . +.\" +This ioctl should be used only if the socket option +.B SO_TIMESTAMP +is not set on the socket. +Otherwise, it returns the timestamp of the +last packet that was received while +.B SO_TIMESTAMP +was not set, or it fails if no such packet has been received, +(i.e., +.BR ioctl (2) +returns \-1 with +.I errno +set to +.BR ENOENT ). +.TP +.B SIOCSPGRP +Set the process or process group that is to receive +.B SIGIO +or +.B SIGURG +signals when I/O becomes possible or urgent data is available. +The argument is a pointer to a +.IR pid_t . +For further details, see the description of +.BR F_SETOWN +in +.BR fcntl (2). +.TP +.B FIOASYNC +Change the +.B O_ASYNC +flag to enable or disable asynchronous I/O mode of the socket. +Asynchronous I/O mode means that the +.B SIGIO +signal or the signal set with +.B F_SETSIG +is raised when a new I/O event occurs. +.IP +Argument is an integer boolean flag. +(This operation is synonymous with the use of +.BR fcntl (2) +to set the +.B O_ASYNC +flag.) +.\" +.TP +.B SIOCGPGRP +Get the current process or process group that receives +.B SIGIO +or +.B SIGURG +signals, +or 0 +when none is set. +.PP +Valid +.BR fcntl (2) +operations: +.TP +.B FIOGETOWN +The same as the +.B SIOCGPGRP +.BR ioctl (2). +.TP +.B FIOSETOWN +The same as the +.B SIOCSPGRP +.BR ioctl (2). +.SH VERSIONS +.B SO_BINDTODEVICE +was introduced in Linux 2.0.30. +.B SO_PASSCRED +is new in Linux 2.2. +The +.I /proc +interfaces were introduced in Linux 2.2. +.B SO_RCVTIMEO +and +.B SO_SNDTIMEO +are supported since Linux 2.3.41. +Earlier, timeouts were fixed to +a protocol-specific setting, and could not be read or written. +.SH NOTES +Linux assumes that half of the send/receive buffer is used for internal +kernel structures; thus the values in the corresponding +.I /proc +files are twice what can be observed on the wire. +.PP +Linux will allow port reuse only with the +.B SO_REUSEADDR +option +when this option was set both in the previous program that performed a +.BR bind (2) +to the port and in the program that wants to reuse the port. +This differs from some implementations (e.g., FreeBSD) +where only the later program needs to set the +.B SO_REUSEADDR +option. +Typically this difference is invisible, since, for example, a server +program is designed to always set this option. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR wireshark (1), +.BR bpf (2), +.BR connect (2), +.BR getsockopt (2), +.BR setsockopt (2), +.BR socket (2), +.BR pcap (3), +.BR capabilities (7), +.BR ddp (7), +.BR ip (7), +.BR packet (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7), +.BR tcpdump (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/spufs.7 b/man7/spufs.7 new file mode 100644 index 0000000..204245e --- /dev/null +++ b/man7/spufs.7 @@ -0,0 +1,781 @@ +.\" Copyright (c) International Business Machines Corp., 2006 +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See +.\" the GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" HISTORY: +.\" 2005-09-28, created by Arnd Bergmann , +.\" Mark Nutter and +.\" Ulrich Weigand +.\" 2006-06-16, revised by Eduardo M. Fleury +.\" 2007-07-10, quite a lot of polishing by mtk +.\" 2007-09-28, updates for newer kernels by Jeremy Kerr +.\" +.TH SPUFS 7 2017-09-15 Linux "Linux Programmer's Manual" +.SH NAME +spufs \- SPU filesystem +.SH DESCRIPTION +The SPU filesystem is used on PowerPC machines that implement the +Cell Broadband Engine Architecture in order to access Synergistic +Processor Units (SPUs). +.PP +The filesystem provides a name space similar to POSIX shared +memory or message queues. +Users that have write permissions +on the filesystem can use +.BR spu_create (2) +to establish SPU contexts under the +.B spufs +root directory. +.PP +Every SPU context is represented by a directory containing +a predefined set of files. +These files can be +used for manipulating the state of the logical SPU. +Users can change permissions on the files, but can't +add or remove files. +.SS Mount options +.TP +.B uid= +Set the user owning the mount point; the default is 0 (root). +.TP +.B gid= +Set the group owning the mount point; the default is 0 (root). +.TP +.B mode= +Set the mode of the top-level directory in +.BR spufs , +as an octal mode string. +The default is 0775. +.SS Files +The files in +.B spufs +mostly follow the standard behavior for regular system calls like +.BR read (2) +or +.BR write (2), +but often support only a subset of the operations +supported on regular filesystems. +This list details the supported +operations and the deviations from the standard behavior described +in the respective man pages. +.PP +All files that support the +.BR read (2) +operation also support +.BR readv (2) +and all files that support the +.BR write (2) +operation also support +.BR writev (2). +All files support the +.BR access (2) +and +.BR stat (2) +family of operations, but for the latter call, +the only fields of the returned +.I stat +structure that contain reliable information are +.IR st_mode , +.IR st_nlink , +.IR st_uid , +and +.IR st_gid . +.PP +All files support the +.BR chmod (2)/ fchmod (2) +and +.BR chown (2)/ fchown (2) +operations, but will not be able to grant permissions that contradict +the possible operations (e.g., read access on the +.I wbox +file). +.PP +The current set of files is: +.TP +.I /capabilities +Contains a comma-delimited string representing the capabilities of this +SPU context. +Possible capabilities are: +.RS +.TP +.B sched +This context may be scheduled. +.TP +.B step +This context can be run in single-step mode, for debugging. +.PP +New capabilities flags may be added in the future. +.RE +.TP +.I /mem +the contents of the local storage memory of the SPU. +This can be accessed like a regular shared memory +file and contains both code and data in the address +space of the SPU. +The possible operations on an open +.I mem +file are: +.RS +.TP +.BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2) +These operate as usual, with the exception that +.BR lseek (2), +.BR write (2), +and +.BR pwrite (2) +are not supported beyond the end of the file. +The file size +is the size of the local storage of the SPU, +which is normally 256 kilobytes. +.TP +.BR mmap (2) +Mapping +.I mem +into the process address space provides access to the SPU local +storage within the process address space. +Only +.B MAP_SHARED +mappings are allowed. +.RE +.TP +.I /regs +Contains the saved general-purpose registers of the SPU context. +This file contains the 128-bit values of each register, +from register 0 to register 127, in order. +This allows the general-purpose registers to be +inspected for debugging. +.IP +Reading to or writing from this file requires that the context is +scheduled out, so use of this file is not recommended in normal +program operation. +.IP +The +.I regs +file is not present on contexts that have been created with the +.B SPU_CREATE_NOSCHED +flag. +.TP +.I /mbox +The first SPU-to-CPU communication mailbox. +This file is read-only and can be read in units of 4 bytes. +The file can be used only in nonblocking mode \- even +.BR poll (2) +cannot be used to block on this file. +The only possible operation on an open +.I mbox +file is: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +If there is no data available in the mailbox (i.e., the SPU has not +sent a mailbox message), the return value is set to \-1 and +.I errno +is set to +.BR EAGAIN . +When data +has been read successfully, four bytes are placed in +the data buffer and the value four is returned. +.RE +.TP +.I /ibox +The second SPU-to-CPU communication mailbox. +This file is similar to the first mailbox file, but can be read +in blocking I/O mode, thus calling +.BR read (2) +on an open +.I ibox +file will block until the SPU has written data to its interrupt mailbox +channel (unless the file has been opened with +.BR O_NONBLOCK , +see below). +Also, +.BR poll (2) +and similar system calls can be used to monitor for the presence +of mailbox data. +.IP +The possible operations on an open +.I ibox +file are: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +If there is no data available in the mailbox and the file +descriptor has been opened with +.BR O_NONBLOCK , +the return value is set to \-1 and +.I errno +is set to +.BR EAGAIN . +.IP +If there is no data available in the mailbox and the file +descriptor has been opened without +.BR O_NONBLOCK , +the call will +block until the SPU writes to its interrupt mailbox channel. +When data has been read successfully, four bytes are placed in +the data buffer and the value four is returned. +.TP +.BR poll (2) +Poll on the +.I ibox +file returns +.I "(POLLIN | POLLRDNORM)" +whenever data is available for reading. +.RE +.TP +.I /wbox +The CPU-to-SPU communication mailbox. +It is write-only and can be written in units of four bytes. +If the mailbox is full, +.BR write (2) +will block, and +.BR poll (2) +can be used to block until the mailbox is available for writing again. +The possible operations on an open +.I wbox +file are: +.RS +.TP +.BR write (2) +If +.I count +is smaller than four, +.BR write (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +If there is no space available in the mailbox and the file +descriptor has been opened with +.BR O_NONBLOCK , +the return +value is set to \-1 and +.I errno +is set to +.BR EAGAIN . +.IP +If there is no space available in the mailbox and the file +descriptor has been opened without +.BR O_NONBLOCK , +the call will block until the SPU reads from its +PPE (PowerPC Processing Element) +mailbox channel. +When data has been written successfully, +the system call returns four as its function result. +.TP +.BR poll (2) +A poll on the +.I wbox +file returns +.I "(POLLOUT | POLLWRNORM)" +whenever space is available for writing. +.RE +.TP +.IR /mbox_stat ", " /ibox_stat ", " /wbox_stat +These are read-only files that contain the length of the current +queue of each mailbox\(emthat is, how many words can be read from +.IR mbox " or " ibox +or how many words can be written to +.I wbox +without blocking. +The files can be read only in four-byte units and return +a big-endian binary integer number. +The only possible operation on an open +.I *box_stat +file is: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is placed in the data buffer. +This value is the number of elements that can be read from (for +.IR mbox_stat +and +.IR ibox_stat ) +or written to (for +.IR wbox_stat ) +the respective mailbox without blocking or returning an +.BR EAGAIN +error. +.RE +.TP +.IR /npc ", " /decr ", " /decr_status ", " /spu_tag_mask ", " \ +/event_mask ", " /event_status ", " /srr0 ", " /lslr +Internal registers of the SPU. +These files contain an ASCII string +representing the hex value of the specified register. +Reads and writes on these +files (except for +.IR npc , +see below) require that the SPU context be scheduled out, +so frequent access to +these files is not recommended for normal program operation. +.IP +The contents of these files are: +.RS +.TP 16 +.I npc +Next Program Counter \- valid only when the SPU is in a stopped state. +.TP +.I decr +SPU Decrementer +.TP +.I decr_status +Decrementer Status +.TP +.I spu_tag_mask +MFC tag mask for SPU DMA +.TP +.I event_mask +Event mask for SPU interrupts +.TP +.I event_status +Number of SPU events pending (read-only) +.TP +.I srr0 +Interrupt Return address register +.TP +.I lslr +Local Store Limit Register +.RE +.IP +The possible operations on these files are: +.RS +.TP +.BR read (2) +Reads the current register value. +If the register value is larger than the buffer passed to the +.BR read (2) +system call, subsequent reads will continue reading from the same +buffer, until the end of the buffer is reached. +.IP +When a complete string has been read, all subsequent read operations +will return zero bytes and a new file descriptor needs to be opened +to read a new value. +.TP +.BR write (2) +A +.BR write (2) +operation on the file sets the register to the +value given in the string. +The string is parsed from the beginning +until the first nonnumeric character or the end of the buffer. +Subsequent writes to the same file descriptor overwrite the +previous setting. +.IP +Except for the +.I npc +file, these files are not present on contexts that have been created with +the +.B SPU_CREATE_NOSCHED +flag. +.RE +.TP +.IR /fpcr +This file provides access to the Floating Point Status and +Control Register (fcpr) as a binary, four-byte file. +The operations on the +.I fpcr +file are: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is placed in the data buffer; +this is the current value of the +.I fpcr +register. +.TP +.BR write (2) +If +.I count +is smaller than four, +.BR write (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is copied from the data buffer, +updating the value of the +.I fpcr +register. +.RE +.TP +.IR /signal1 ", " /signal2 +The files provide access to the two signal notification channels +of an SPU. +These are read-write files that operate on four-byte words. +Writing to one of these files triggers an interrupt on the SPU. +The value written to the signal files can +be read from the SPU through a channel read or from +host user space through the file. +After the value has been read by the SPU, it is reset to zero. +The possible operations on an open +.I signal1 +or +.I signal2 +file are: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is placed in the data buffer; +this is the current value of the specified signal notification +register. +.TP +.BR write (2) +If +.I count +is smaller than four, +.BR write (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is copied from the data buffer, +updating the value of the specified signal notification +register. +The signal notification register will either be replaced with +the input data or will be updated to the bitwise OR operation +of the old value and the input data, depending on the contents +of the +.IR signal1_type +or +.IR signal2_type +files respectively. +.RE +.TP +.IR /signal1_type ", " /signal2_type +These two files change the behavior of the +.IR signal1 +and +.IR signal2 +notification files. +They contain a numeric ASCII string which is read +as either "1" or "0". +In mode 0 (overwrite), the hardware replaces the contents +of the signal channel with the data that is written to it. +In mode 1 (logical OR), the hardware accumulates the bits +that are subsequently written to it. +The possible operations on an open +.I signal1_type +or +.I signal2_type +file are: +.RS +.TP +.BR read (2) +When the count supplied to the +.BR read (2) +call is shorter than the required length for the digit (plus a newline +character), subsequent reads from the same file descriptor will +complete the string. +When a complete string has been read, all subsequent read operations +will return zero bytes and a new file descriptor needs to be opened +to read the value again. +.TP +.BR write (2) +A +.BR write (2) +operation on the file sets the register to the +value given in the string. +The string is parsed from the beginning +until the first nonnumeric character or the end of the buffer. +Subsequent writes to the same file descriptor overwrite the +previous setting. +.RE +.TP +.IR /mbox_info ", " /ibox_info ", " /wbox_info ", " /dma_into ", " /proxydma_info +Read-only files that contain the saved state of the SPU mailboxes and +DMA queues. +This allows the SPU status to be inspected, mainly for debugging. +The +.I mbox_info +and +.I ibox_info +files each contain the four-byte mailbox message that has been written +by the SPU. +If no message has been written to these mailboxes, then +contents of these files is undefined. +The +.IR mbox_stat , +.I ibox_stat +and +.I wbox_stat +files contain the available message count. +.IP +The +.I wbox_info +file contains an array of four-byte mailbox messages, which have been +sent to the SPU. +With current CBEA machines, the array is four items in +length, so up to 4 * 4 = 16 bytes can be read from this file. +If any mailbox queue entry is empty, +then the bytes read at the corresponding location are undefined. +.IP +The +.I dma_info +file contains the contents of the SPU MFC DMA queue, represented as the +following structure: +.IP +.in +4n +.EX +struct spu_dma_info { + uint64_t dma_info_type; + uint64_t dma_info_mask; + uint64_t dma_info_status; + uint64_t dma_info_stall_and_notify; + uint64_t dma_info_atomic_command_status; + struct mfc_cq_sr dma_info_command_data[16]; +}; +.EE +.in +.IP +The last member of this data structure is the actual DMA queue, +containing 16 entries. +The +.I mfc_cq_sr +structure is defined as: +.IP +.in +4n +.EX +struct mfc_cq_sr { + uint64_t mfc_cq_data0_RW; + uint64_t mfc_cq_data1_RW; + uint64_t mfc_cq_data2_RW; + uint64_t mfc_cq_data3_RW; +}; +.EE +.in +.IP +The +.I proxydma_info +file contains similar information, but describes the proxy DMA queue +(i.e., DMAs initiated by entities outside the SPU) instead. +The file is in the following format: +.IP +.in +4n +.EX +struct spu_proxydma_info { + uint64_t proxydma_info_type; + uint64_t proxydma_info_mask; + uint64_t proxydma_info_status; + struct mfc_cq_sr proxydma_info_command_data[8]; +}; +.EE +.in +.IP +Accessing these files requires that the SPU context is scheduled out - +frequent use can be inefficient. +These files should not be used for normal program operation. +.IP +These files are not present on contexts that have been created with the +.B SPU_CREATE_NOSCHED +flag. +.TP +.IR /cntl +This file provides access to the SPU Run Control and SPU status +registers, as an ASCII string. +The following operations are supported: +.RS +.TP +.BR read (2) +Reads from the +.I cntl +file will return an ASCII string with the hex +value of the SPU Status register. +.TP +.BR write (2) +Writes to the +.I cntl +file will set the context's SPU Run Control register. +.RE +.TP +.I /mfc +Provides access to the Memory Flow Controller of the SPU. +Reading from the file returns the contents of the +SPU's MFC Tag Status register, and +writing to the file initiates a DMA from the MFC. +The following operations are supported: +.RS +.TP +.BR write (2) +Writes to this file need to be in the format of a MFC DMA command, +defined as follows: +.IP +.in +4n +.EX +struct mfc_dma_command { + int32_t pad; /* reserved */ + uint32_t lsa; /* local storage address */ + uint64_t ea; /* effective address */ + uint16_t size; /* transfer size */ + uint16_t tag; /* command tag */ + uint16_t class; /* class ID */ + uint16_t cmd; /* command opcode */ +}; +.EE +.in +.IP +Writes are required to be exactly +.I sizeof(struct mfc_dma_command) +bytes in size. +The command will be sent to the SPU's MFC proxy queue, and the +tag stored in the kernel (see below). +.TP +.BR read (2) +Reads the contents of the tag status register. +If the file is opened in blocking mode (i.e., without +.BR O_NONBLOCK ), +then the read will block until a +DMA tag (as performed by a previous write) is complete. +In nonblocking mode, +the MFC tag status register will be returned without waiting. +.TP +.BR poll (2) +Calling +.BR poll (2) +on the +.I mfc +file will block until a new DMA can be +started (by checking for +.BR POLLOUT ) +or until a previously started DMA +(by checking for +.BR POLLIN ) +has been completed. +.IP +.I /mss +Provides access to the MFC MultiSource Synchronization (MSS) facility. +By +.BR mmap (2)-ing +this file, processes can access the MSS area of the SPU. +.IP +The following operations are supported: +.TP +.BR mmap (2) +Mapping +.B mss +into the process address space gives access to the SPU MSS area +within the process address space. +Only +.B MAP_SHARED +mappings are allowed. +.RE +.TP +.I /psmap +Provides access to the whole problem-state mapping of the SPU. +Applications can use this area to interface to the SPU, rather than +writing to individual register files in +.BR spufs . +.IP +The following operations are supported: +.RS +.TP +.BR mmap (2) +Mapping +.B psmap +gives a process a direct map of the SPU problem state area. +Only +.B MAP_SHARED +mappings are supported. +.RE +.TP +.I /phys-id +Read-only file containing the physical SPU number that the SPU context +is running on. +When the context is not running, this file contains the +string "\-1". +.IP +The physical SPU number is given by an ASCII hex string. +.TP +.I /object-id +Allows applications to store (or retrieve) a single 64-bit ID into the +context. +This ID is later used by profiling tools to uniquely identify +the context. +.RS +.TP +.BR write (2) +By writing an ASCII hex value into this file, applications can set the +object ID of the SPU context. +Any previous value of the object ID is overwritten. +.TP +.BR read (2) +Reading this file gives an ASCII hex string representing the object ID +for this SPU context. +.RE +.SH EXAMPLE +.TP +.IR /etc/fstab " entry" +none /spu spufs gid=spu 0 0 +.\" .SH AUTHORS +.\" Arnd Bergmann , Mark Nutter , +.\" Ulrich Weigand , Jeremy Kerr +.SH SEE ALSO +.BR close (2), +.BR spu_create (2), +.BR spu_run (2), +.BR capabilities (7) +.PP +.I The Cell Broadband Engine Architecture (CBEA) specification +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/standards.7 b/man7/standards.7 new file mode 100644 index 0000000..a081bad --- /dev/null +++ b/man7/standards.7 @@ -0,0 +1,298 @@ +.\" Copyright (c) 2006, Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH STANDARDS 7 2017-11-26 "Linux" "Linux Programmer's Manual" +.SH NAME +standards \- C and UNIX Standards +.SH DESCRIPTION +The CONFORMING TO section that appears in many manual pages identifies +various standards to which the documented interface conforms. +The following list briefly describes these standards. +.TP +.B V7 +Version 7 (also known as Seventh Edition) UNIX, +released by AT&T/Bell Labs in 1979. +After this point, UNIX systems diverged into two main dialects: +BSD and System V. +.TP +.B 4.2BSD +This is an implementation standard defined by the 4.2 release +of the +.IR "Berkeley Software Distribution", +released by the University of California at Berkeley. +This was the first Berkeley release that contained a TCP/IP +stack and the sockets API. +4.2BSD was released in 1983. +.IP +Earlier major BSD releases included +.IR 3BSD +(1980), +.I 4BSD +(1980), +and +.I 4.1BSD +(1981). +.TP +.B 4.3BSD +The successor to 4.2BSD, released in 1986. +.TP +.B 4.4BSD +The successor to 4.3BSD, released in 1993. +This was the last major Berkeley release. +.TP +.B System V +This is an implementation standard defined by AT&T's milestone 1983 +release of its commercial System V (five) release. +The previous major AT&T release was +.IR "System III" , +released in 1981. +.TP +.B System V release 2 (SVr2) +This was the next System V release, made in 1985. +The SVr2 was formally described in the +.I "System V Interface Definition version 1" +.RI ( "SVID 1" ) +published in 1985. +.TP +.B System V release 3 (SVr3) +This was the successor to SVr2, released in 1986. +This release was formally described in the +.I "System V Interface Definition version 2" +.RI ( "SVID 2" ). +.TP +.B System V release 4 (SVr4) +This was the successor to SVr3, released in 1989. +This version of System V is described in the "Programmer's Reference +Manual: Operating System API (Intel processors)" (Prentice-Hall +1992, ISBN 0-13-951294-2) +This release was formally described in the +.I "System V Interface Definition version 3" +.RI ( "SVID 3" ), +and is considered the definitive System V release. +.TP +.B SVID 4 +System V Interface Definition version 4, issued in 1995. +Available online at +.UR http://www.sco.com\:/developers\:/devspecs/ +.UE . +.TP +.B C89 +This was the first C language standard, ratified by ANSI +(American National Standards Institute) in 1989 +.RI ( X3.159-1989 ). +Sometimes this is known as +.IR "ANSI C" , +but since C99 is also an +ANSI standard, this term is ambiguous. +This standard was also ratified by +ISO (International Standards Organization) in 1990 +.RI ( "ISO/IEC 9899:1990" ), +and is thus occasionally referred to as +.IR "ISO C90" . +.TP +.B C99 +This revision of the C language standard was ratified by ISO in 1999 +.RI ( "ISO/IEC 9899:1999" ). +Available online at +.UR http://www.open\-std.org\:/jtc1\:/sc22\:/wg14\:/www\:/standards +.UE . +.TP +.B C11 +This revision of the C language standard was ratified by ISO in 2011 +.RI ( "ISO/IEC 9899:2011" ). +.TP +.B POSIX.1-1990 +"Portable Operating System Interface for Computing Environments". +IEEE 1003.1-1990 part 1, ratified by ISO in 1990 +.RI ( "ISO/IEC 9945-1:1990" ). +The term "POSIX" was coined by Richard Stallman. +.TP +.B POSIX.2 +IEEE Std 1003.2-1992, +describing commands and utilities, ratified by ISO in 1993 +.RI ( "ISO/IEC 9945-2:1993" ). +.TP +.BR POSIX.1b " (formerly known as \fIPOSIX.4\fP)" +IEEE Std 1003.1b-1993, +describing real-time facilities +for portable operating systems, ratified by ISO in 1996 +.RI ( "ISO/IEC 9945-1:1996" ). +.TP +.B POSIX.1c +IEEE Std 1003.1c-1995, which describes the POSIX threads interfaces. +.TP +.B POSIX.1d +IEEE Std 1003.1c-1999, which describes additional real-time extensions. +.TP +.B POSIX.1g +IEEE Std 1003.1g-2000, which describes networking APIs (including sockets). +.TP +.B POSIX.1j +IEEE Std 1003.1j-2000, which describes advanced real-time extensions. +.TP +.B POSIX.1-1996 +A 1996 revision of POSIX.1 which incorporated POSIX.1b and POSIX.1c. +.TP +.B XPG3 +Released in 1989, this was the first significant release of the +.IR "X/Open Portability Guide" , +produced by the +X/Open Company, a multivendor consortium. +This multivolume guide was based on the POSIX standards. +.TP +.B XPG4 +A revision of the X/Open Portability Guide, released in 1992. +.TP +.B XPG4v2 +A 1994 revision of XPG4. +This is also referred to as +.IR "Spec 1170" , +where 1170 referred to the number of interfaces +defined by this standard. +.TP +.B "SUS (SUSv1)" +Single UNIX Specification. +This was a repackaging of XPG4v2 and other X/Open standards +(X/Open Curses Issue 4 version 2, +X/Open Networking Service (XNS) Issue 4). +Systems conforming to this standard can be branded +.IR "UNIX 95" . +.TP +.B SUSv2 +Single UNIX Specification version 2. +Sometimes also referred to as +.IR XPG5 . +This standard appeared in 1997. +Systems conforming to this standard can be branded +.IR "UNIX 98" . +See also +.UR http://www.UNIX\-systems.org\:/version2/ +.UE .) +.TP +.B POSIX.1-2001, SUSv3 +This was a 2001 revision and consolidation of the +POSIX.1, POSIX.2, and SUS standards into a single document, +conducted under the auspices of the Austin Group +.UR http://www.opengroup.org\:/austin/ +.UE . +The standard is available online at +.UR http://www.unix\-systems.org\:/version3/ +.UE , +and the interfaces that it describes are also available in the Linux +manual pages package under sections 1p and 3p (e.g., "man 3p open"). +.IP +The standard defines two levels of conformance: +.IR "POSIX conformance" , +which is a baseline set of interfaces required of a conforming system; +and +.IR "XSI Conformance", +which additionally mandates a set of interfaces +(the "XSI extension") which are only optional for POSIX conformance. +XSI-conformant systems can be branded +.IR "UNIX 03" . +(XSI conformance constitutes the +.I "Single UNIX Specification version 3" +.RI ( SUSv3 ).) +.IP +The POSIX.1-2001 document is broken into four parts: +.IP +.BR XBD : +Definitions, terms and concepts, header file specifications. +.IP +.BR XSH : +Specifications of functions (i.e., system calls and library +functions in actual implementations). +.IP +.BR XCU : +Specifications of commands and utilities +(i.e., the area formerly described by POSIX.2). +.IP +.BR XRAT : +Informative text on the other parts of the standard. +.IP +POSIX.1-2001 is aligned with C99, so that all of the +library functions standardized in C99 are also +standardized in POSIX.1-2001. +.IP +Two Technical Corrigenda (minor fixes and improvements) +of the original 2001 standard have occurred: +TC1 in 2003 (also known as +.IR POSIX.1-2003 ), +and TC2 in 2004 (also known as +.IR POSIX.1-2004 ). +.TP +.B POSIX.1-2008, SUSv4 +Work on the next revision of POSIX.1/SUS was completed and +ratified in 2008. +.IP +The changes in this revision are not as large as those +that occurred for POSIX.1-2001/SUSv3, +but a number of new interfaces are added +and various details of existing specifications are modified. +Many of the interfaces that were optional in +POSIX.1-2001 become mandatory in the 2008 revision of the standard. +A few interfaces that are present in POSIX.1-2001 are marked +as obsolete in POSIX.1-2008, or removed from the standard altogether. +.IP +The revised standard is broken into the same four parts as POSIX.1-2001, +and again there are two levels of conformance: the baseline +.IR "POSIX Conformance" , +and +.IR "XSI Conformance" , +which mandates an additional set of interfaces +beyond those in the base specification. +.IP +In general, where the CONFORMING TO section of a manual page +lists POSIX.1-2001, it can be assumed that the interface also +conforms to POSIX.1-2008, unless otherwise noted. +.IP +Technical Corrigendum 1 (minor fixes and improvements) +of this standard was released in 2013 +(also known as +.IR POSIX.1-2013 ). +.IP +Technical Corrigendum 2 of this standard was released in 2016 +(also known as +.IR POSIX.1-2016 ). +.IP +Further information can be found on the Austin Group web site, +.UR http://www.opengroup.org\:/austin/ +.UE . +.SH SEE ALSO +.BR getconf (1), +.BR confstr (3), +.BR pathconf (3), +.BR sysconf (3), +.BR attributes (7), +.BR feature_test_macros (7), +.BR libc (7), +.BR posixoptions (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/suffixes.7 b/man7/suffixes.7 new file mode 100644 index 0000000..a771c36 --- /dev/null +++ b/man7/suffixes.7 @@ -0,0 +1,291 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:35:15 1993 by Rik Faith +.\" Modified Sun Feb 19 22:02:32 1995 by Rik Faith +.\" Modified Tue Oct 22 23:28:12 1996 by Eric S. Raymond +.\" Modified Sun Jan 26 21:56:56 1997 by Ralph Schleicher +.\" +.\" Modified Mon Jun 16 20:24:58 1997 by Nicolás Lichtmaier +.\" Modified Sun Oct 18 22:11:28 1998 by Joseph S. Myers +.\" Modified Mon Nov 16 17:24:47 1998 by Andries Brouwer +.\" Modified Thu Nov 16 23:28:25 2000 by David A. Wheeler +.\" +.\" +.\" "nroff" ("man") (or "tbl") needs a long page to avoid warnings +.\" from "grotty" (at imagined page breaks). Bug in grotty? +.if n .pl 1000v +.TH SUFFIXES 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +suffixes \- list of file suffixes +.SH DESCRIPTION +It is customary to indicate the contents of a file with the file suffix, +which consists of a period, followed by one or more letters. +Many standard utilities, such as compilers, use this to recognize the type of +file they are dealing with. +The +.BR make (1) +utility is driven by rules based on file suffix. +.PP +Following is a list of suffixes which are likely to be found on a +Linux system. +.PP +.TS +l | l +_ | _ +lI | l . +Suffix File type + ,v files for RCS (Revision Control System) + - backup file + .C C++ source code, equivalent to \fI.cc\fP + .F Fortran source with \fBcpp\fP(1) directives + or file compressed using freeze + .S assembler source with \fBcpp\fP(1) directives + .Y file compressed using yabba + .Z file compressed using \fBcompress\fP(1) + .[0-\9]+gf TeX generic font files + .[0\-9]+pk TeX packed font files + .[1\-9] manual page for the corresponding section + .[1\-9][a-z] manual page for section plus subsection + .a static object code library + .ad X application default resource file + .ada Ada source (may be body, spec, or combination) + .adb Ada body source + .ads Ada spec source + .afm PostScript font metrics + .al Perl autoload file + .am \fBautomake\fP(1) input file + .arc \fBarc\fP(1) archive + .arj \fBarj\fP(1) archive + .asc PGP ASCII-armored data + .asm (GNU) assembler source file + .au Audio sound file + .aux LaTeX auxiliary file + .avi (msvideo) movie + .awk AWK language program + .b LILO boot loader image + .bak backup file + .bash \fBbash\fP(1) shell script + .bb basic block list data produced by + gcc \-ftest\-coverage + .bbg basic block graph data produced by + gcc \-ftest\-coverage + .bbl BibTeX output + .bdf X font file + .bib TeX bibliographic database, BibTeX input + .bm bitmap source + .bmp bitmap + .bz2 file compressed using \fBbzip2\fP(1) + .c C source + .cat message catalog files + .cc C++ source + .cf configuration file + .cfg configuration file + .cgi WWW content generating script or program + .cls LaTeX Class definition + .class Java compiled byte-code + .conf configuration file + .config configuration file + .cpp equivalent to \fI.cc\fR + .csh \fBcsh\fP(1) shell script + .cxx equivalent to \fI.cc\fR + .dat data file + .deb Debian software package + .def Modula-2 source for definition modules + .def other definition files + .desc initial part of mail message unpacked with + \fBmunpack\fP(1) + .diff file differences (\fBdiff\fP(1) command output) + .dir dbm data base directory file + .doc documentation file + .dsc Debian Source Control (source package) + .dtx LaTeX package source file + .dvi TeX's device independent output + .el Emacs-Lisp source + .elc compiled Emacs-Lisp source + .eps encapsulated PostScript + .exp Expect source code + .f Fortran source + .f77 Fortran 77 source + .f90 Fortran 90 source + .fas precompiled Common-Lisp + .fi Fortran include files + .fig FIG image file (used by \fBxfig\fP(1)) + .fmt TeX format file + .gif Compuserve Graphics Image File format + .gmo GNU format message catalog + .gsf Ghostscript fonts + .gz file compressed using \fBgzip\fP(1) + .h C or C++ header files + .help help file + .hf equivalent to \fI.help\fP + .hlp equivalent to \fI.help\fP + .htm poor man's \fI.html\fP + .html HTML document used with the World Wide Web + .hqx 7-bit encoded Macintosh file + .i C source after preprocessing + .icon bitmap source + .idx reference or datum-index file for hypertext + or database system + .image bitmap source + .in configuration template, especially for GNU Autoconf + .info files for the Emacs info browser + .info-[0\-9]+ split info files + .ins LaTeX package install file for docstrip + .itcl itcl source code; + itcl ([incr Tcl]) is an OO extension of tcl + .java a Java source file + .jpeg Joint Photographic Experts Group format + .jpg poor man's \fI.jpeg\fP + .kmap \fBlyx\fP(1) keymap + .l equivalent to \fI.lex\fP or \fI.lisp\fP + .lex \fBlex\fP(1) or \fBflex\fP(1) files + .lha lharc archive + .lib Common-Lisp library + .lisp Lisp source + .ln files for use with \fBlint\fP(1) + .log log file, in particular produced by TeX + .lsm Linux Software Map entry + .lsp Common-Lisp source + .lzh lharc archive + .m Objective-C source code + .m4 \fBm4\fP(1) source + .mac macro files for various programs + .man manual page (usually source rather than formatted) + .map map files for various programs + .me Nroff source using the me macro package + .mf Metafont (font generator for TeX) source + .mgp MagicPoint file + .mm sources for \fBgroff\fP(1) in mm - format + .mo Message catalog binary file + .mod Modula-2 source for implementation modules + .mov (quicktime) movie + .mp Metapost source + .mp2 MPEG Layer 2 (audio) file + .mp3 MPEG Layer 3 (audio) file + .mpeg movie file + .o object file + .old old or backup file + .orig backup (original) version of a file, from \fBpatch\fP(1) + .out output file, often executable program (a.out) + .p Pascal source + .pag dbm data base data file + .patch file differences for \fBpatch\fP(1) + .pbm portable bitmap format + .pcf X11 font files + .pdf Adobe Portable Data Format + (use Acrobat/\fBacroread\fP or \fBxpdf\fP) + .perl Perl source (see .ph, .pl and .pm) + .pfa PostScript font definition files, ASCII format + .pfb PostScript font definition files, binary format + .pgm portable greymap format + .pgp PGP binary data + .ph Perl header file + .php PHP program file + .php3 PHP3 program file + .pid File to store daemon PID (e.g., crond.pid) + .pl TeX property list file or Perl library file + .pm Perl module + .png Portable Network Graphics file + .po Message catalog source + .pod \fBperldoc\fP(1) file + .ppm portable pixmap format + .pr bitmap source + .ps PostScript file + .py Python source + .pyc compiled python + .qt quicktime movie + .r RATFOR source (obsolete) + .rej patches that \fBpatch\fP(1) couldn't apply + .rpm RPM software package + .rtf Rich Text Format file + .rules rules for something + .s assembler source + .sa stub libraries for a.out shared libraries + .sc \fBsc\fP(1) spreadsheet commands + .scm Scheme source code + .sed sed source file + .sgml SGML source file + .sh \fBsh\fP(1) scripts + .shar archive created by the \fBshar\fP(1) utility + .so Shared library or dynamically loadable object + .sql SQL source + .sqml SQML schema or query program + .sty LaTeX style files + .sym Modula-2 compiled definition modules + .tar archive created by the \fBtar\fP(1) utility + .tar.Z tar(1) archive compressed with \fBcompress\fP(1) + .tar.bz2 tar(1) archive compressed with \fBbzip2\fP(1) + .tar.gz tar(1) archive compressed with \fBgzip\fP(1) + .taz tar(1) archive compressed with \fBcompress\fP(1) + .tcl tcl source code + .tex TeX or LaTeX source + .texi equivalent to \fI.texinfo\fP + .texinfo Texinfo documentation source + .text text file + .tfm TeX font metric file + .tgz tar archive compressed with \fBgzip\fP(1) + .tif poor man's \fI.tiff\fP + .tiff Tagged Image File Format + .tk tcl/tk script + .tmp temporary file + .tmpl template files + .txt equivalent to \fI.text\fP + .uu equivalent to \fI.uue\fP + .uue binary file encoded with \fBuuencode\fP(1) + .vf TeX virtual font file + .vpl TeX virtual property list file + .w Silvio Levi's CWEB + .wav wave sound file + .web Donald Knuth's WEB + .wml Source file for Web Meta Language + .xbm X11 bitmap source + .xcf GIMP graphic + .xml eXtended Markup Language file + .xpm X11 pixmap source + .xs Perl xsub file produced by h2xs + .xsl XSL stylesheet + .y \fByacc\fP(1) or \fBbison\fP(1) (parser generator) files + .z File compressed using \fBpack\fP(1) (or an old \fBgzip\fP(1)) + .zip \fBzip\fP(1) archive + .zoo \fBzoo\fP(1) archive + ~ Emacs or \fBpatch\fP(1) backup file + rc startup (`run control') file, e.g., \fI.newsrc\fP +.TE +.SH CONFORMING TO +General UNIX conventions. +.SH BUGS +This list is not exhaustive. +.SH SEE ALSO +.BR file (1), +.BR make (1) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/svipc.7 b/man7/svipc.7 new file mode 100644 index 0000000..e0fe1c8 --- /dev/null +++ b/man7/svipc.7 @@ -0,0 +1,360 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" FIXME . There is now duplication of some of the information +.\" below in semctl.2, msgctl.2, and shmctl.2 -- MTK, Nov 04 +.\" +.\" FIXME . Ultimately, there should probably be +.\" svmq_overview(7), svshm_overview(7), and svsem_overview(7) +.\" that provide an overview of each System V IPC mechanism. +.\" In that case: +.\" * Those files should add a discussion of the /proc/sysvipc +.\" interfaces. +.\" * Documentation of the various /proc interfaces should move into +.\" those files (from proc(5)), and references in the various *.2 +.\" pages that refer to the /proc files should be adjusted. +.\" * The only part that uniquely belongs in svipc(7) is perhaps +.\" the discussion of ipc_perm. +.\" +.TH SVIPC 7 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +svipc \- System V interprocess communication mechanisms +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.fi +.SH DESCRIPTION +This manual page refers to the Linux implementation of the System V +interprocess communication (IPC) mechanisms: +message queues, semaphore sets, and shared memory segments. +In the following, the word +.I resource +means an instantiation of one among such mechanisms. +.SS Resource access permissions +For each resource, the system uses a common structure of type +.I "struct ipc_perm" +to store information needed in determining permissions to perform an +IPC operation. +The +.I ipc_perm +structure includes the following members: +.PP +.in +4n +.EX +struct ipc_perm { + uid_t cuid; /* creator user ID */ + gid_t cgid; /* creator group ID */ + uid_t uid; /* owner user ID */ + gid_t gid; /* owner group ID */ + unsigned short mode; /* r/w permissions */ +}; +.EE +.in +.PP +The +.I mode +member of the +.I ipc_perm +structure defines, with its lower 9 bits, the access permissions to the +resource for a process executing an IPC system call. +The permissions are interpreted as follows: +.PP +.nf + 0400 Read by user. + 0200 Write by user. + 0040 Read by group. + 0020 Write by group. + 0004 Read by others. + 0002 Write by others. +.fi +.PP +Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. +Furthermore, +"write" +effectively means +"alter" +for a semaphore set. +.PP +The same system header file also defines the following symbolic +constants: +.TP 14 +.B IPC_CREAT +Create entry if key doesn't exist. +.TP +.B IPC_EXCL +Fail if key exists. +.TP +.B IPC_NOWAIT +Error if request must wait. +.TP +.B IPC_PRIVATE +Private key. +.TP +.B IPC_RMID +Remove resource. +.TP +.B IPC_SET +Set resource options. +.TP +.B IPC_STAT +Get resource options. +.PP +Note that +.B IPC_PRIVATE +is a +.I key_t +type, while all the other symbolic constants are flag fields and can +be OR'ed into an +.I int +type variable. +.SS Message queues +A message queue is uniquely identified by a positive integer +.RI "(its " msqid ) +and has an associated data structure of type +.IR "struct msqid_ds" , +defined in +.IR , +containing the following members: +.PP +.in +4n +.EX +struct msqid_ds { + struct ipc_perm msg_perm; + msgqnum_t msg_qnum; /* no of messages on queue */ + msglen_t msg_qbytes; /* bytes max on a queue */ + pid_t msg_lspid; /* PID of last msgsnd(2) call */ + pid_t msg_lrpid; /* PID of last msgrcv(2) call */ + time_t msg_stime; /* last msgsnd(2) time */ + time_t msg_rtime; /* last msgrcv(2) time */ + time_t msg_ctime; /* last change time */ +}; +.EE +.in +.TP 11 +.I msg_perm +.I ipc_perm +structure that specifies the access permissions on the message +queue. +.TP +.I msg_qnum +Number of messages currently on the message queue. +.TP +.I msg_qbytes +Maximum number of bytes of message text allowed on the message +queue. +.TP +.I msg_lspid +ID of the process that performed the last +.BR msgsnd (2) +system call. +.TP +.I msg_lrpid +ID of the process that performed the last +.BR msgrcv (2) +system call. +.TP +.I msg_stime +Time of the last +.BR msgsnd (2) +system call. +.TP +.I msg_rtime +Time of the last +.BR msgrcv (2) +system call. +.TP +.I msg_ctime +Time of the last +system call that changed a member of the +.I msqid_ds +structure. +.SS Semaphore sets +A semaphore set is uniquely identified by a positive integer +.RI "(its " semid ) +and has an associated data structure of type +.IR "struct semid_ds" , +defined in +.IR , +containing the following members: +.IP +.in +4n +.EX +struct semid_ds { + struct ipc_perm sem_perm; + time_t sem_otime; /* last operation time */ + time_t sem_ctime; /* last change time */ + unsigned long sem_nsems; /* count of sems in set */ +}; +.EE +.in +.TP 11 +.I sem_perm +.I ipc_perm +structure that specifies the access permissions on the semaphore +set. +.TP +.I sem_otime +Time of last +.BR semop (2) +system call. +.TP +.I sem_ctime +Time of last +.BR semctl (2) +system call that changed a member of the above structure or of one +semaphore belonging to the set. +.TP +.I sem_nsems +Number of semaphores in the set. +Each semaphore of the set is referenced by a nonnegative integer +ranging from +.B 0 +to +.IR sem_nsems\-1 . +.PP +A semaphore is a data structure of type +.I "struct sem" +containing the following members: +.PP +.in +4n +.EX +struct sem { + int semval; /* semaphore value */ + int sempid; /* PID of process that last modified */ +.\" unsigned short semncnt; /* nr awaiting semval to increase */ +.\" unsigned short semzcnt; /* nr awaiting semval = 0 */ +}; +.EE +.in +.TP 11 +.I semval +Semaphore value: a nonnegative integer. +.TP +.I sempid +PID of the last process that modified the value of +this semaphore. +.\".TP +.\".I semncnt +.\"Number of processes suspended awaiting for +.\".I semval +.\"to increase. +.\".TP +.\".I semznt +.\"Number of processes suspended awaiting for +.\".I semval +.\"to become zero. +.SS Shared memory segments +A shared memory segment is uniquely identified by a positive integer +.RI "(its " shmid ) +and has an associated data structure of type +.IR "struct shmid_ds" , +defined in +.IR , +containing the following members: +.PP +.in +4n +.EX +struct shmid_ds { + struct ipc_perm shm_perm; + size_t shm_segsz; /* size of segment */ + pid_t shm_cpid; /* PID of creator */ + pid_t shm_lpid; /* PID, last operation */ + shmatt_t shm_nattch; /* no. of current attaches */ + time_t shm_atime; /* time of last attach */ + time_t shm_dtime; /* time of last detach */ + time_t shm_ctime; /* time of last change */ +}; +.EE +.in +.TP 11 +.I shm_perm +.I ipc_perm +structure that specifies the access permissions on the shared memory +segment. +.TP +.I shm_segsz +Size in bytes of the shared memory segment. +.TP +.I shm_cpid +ID of the process that created the shared memory segment. +.TP +.I shm_lpid +ID of the last process that executed a +.BR shmat (2) +or +.BR shmdt (2) +system call. +.TP +.I shm_nattch +Number of current alive attaches for this shared memory segment. +.TP +.I shm_atime +Time of the last +.BR shmat (2) +system call. +.TP +.I shm_dtime +Time of the last +.BR shmdt (2) +system call. +.TP +.I shm_ctime +Time of the last +.BR shmctl (2) +system call that changed +.IR shmid_ds . +.SS IPC namespaces +For a discussion of the interaction of System V IPC objects and +IPC namespaces, see +.BR namespaces (7). +.SH SEE ALSO +.BR ipcmk (1), +.BR ipcrm (1), +.BR ipcs (1), +.BR lsipc (1), +.BR ipc (2), +.BR msgctl (2), +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR semctl (2), +.BR semget (2), +.BR semop (2), +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR shmget (2), +.BR ftok (3), +.BR namespaces (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/symlink.7 b/man7/symlink.7 new file mode 100644 index 0000000..c198662 --- /dev/null +++ b/man7/symlink.7 @@ -0,0 +1,543 @@ +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (C) 2008, 2014 Michael Kerrisk +.\" +.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" @(#)symlink.7 8.3 (Berkeley) 3/31/94 +.\" $FreeBSD: src/bin/ln/symlink.7,v 1.30 2005/02/13 22:25:09 ru Exp $ +.\" +.\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for +.\" specific Linux details, improved readability, and man-pages style. +.\" +.TH SYMLINK 7 2016-10-08 "Linux" "Linux Programmer's Manual" +.SH NAME +symlink \- symbolic link handling +.SH DESCRIPTION +Symbolic links are files that act as pointers to other files. +To understand their behavior, you must first understand how hard links +work. +.PP +A hard link to a file is indistinguishable from the original file because +it is a reference to the object underlying the original filename. +(To be precise: each of the hard links to a file is a reference to +the same +.IR "inode number" , +where an inode number is an index into the inode table, +which contains metadata about all files on a filesystem. +See +.BR stat (2).) +Changes to a file are independent of the name used to reference the file. +Hard links may not refer to directories +(to prevent the possibility of loops within the filesystem tree, +which would confuse many programs) +and may not refer to files on different filesystems +(because inode numbers are not unique across filesystems). +.PP +A symbolic link is a special type of file whose contents are a string +that is the pathname of another file, the file to which the link refers. +(The contents of a symbolic link can be read using +.BR readlink (2).) +In other words, a symbolic link is a pointer to another name, +and not to an underlying object. +For this reason, symbolic links may refer to directories and may cross +filesystem boundaries. +.PP +There is no requirement that the pathname referred to by a symbolic link +should exist. +A symbolic link that refers to a pathname that does not exist is said +to be a +.IR "dangling link" . +.PP +Because a symbolic link and its referenced object coexist in the filesystem +name space, confusion can arise in distinguishing between the link itself +and the referenced object. +On historical systems, +commands and system calls adopted their own link-following +conventions in a somewhat ad-hoc fashion. +Rules for a more uniform approach, +as they are implemented on Linux and other systems, +are outlined here. +It is important that site-local applications also conform to these rules, +so that the user interface can be as consistent as possible. +.SS Symbolic link ownership, permissions, and timestamps +The owner and group of an existing symbolic link can be changed +using +.BR lchown (2). +The only time that the ownership of a symbolic link matters is +when the link is being removed or renamed in a directory that +has the sticky bit set (see +.BR stat (2)). +.PP +The last access and last modification timestamps +of a symbolic link can be changed using +.BR utimensat (2) +or +.BR lutimes (3). +.PP +On Linux, the permissions of a symbolic link are not used +in any operations; the permissions are always +0777 (read, write, and execute for all user categories), +.\" Linux does not currently implement an lchmod(2). +and can't be changed. +(Note that there are some "magic" symbolic links in the +.I /proc +directory tree\(emfor example, the +.IR /proc/[pid]/fd/* +files\(emthat have different permissions.) +.\" +.\" The +.\" 4.4BSD +.\" system differs from historical +.\" 4BSD +.\" systems in that the system call +.\" .BR chown (2) +.\" has been changed to follow symbolic links. +.\" The +.\" .BR lchown (2) +.\" system call was added later when the limitations of the new +.\" .BR chown (2) +.\" became apparent. +.SS Obtaining a file descriptor that refers to a symbolic link +Using the combination of the +.B O_PATH +and +.BR O_NOFOLLOW +flags to +.BR open (2) +yields a file descriptor that can be passed as the +.IR dirfd +argument in system calls such as +.BR fstatat (2), +.BR fchownat (2), +.BR fchmodat (2), +.BR linkat (2), +and +.BR readlinkat (2), +in order to operate on the symbolic link itself +(rather than the file to which it refers). +.PP +By default +(i.e., if the +.BR AT_SYMLINK_FOLLOW +flag is not specified), if +.BR name_to_handle_at (2) +is applied to a symbolic link, it yields a handle for the symbolic link +(rather than the file to which it refers). +One can then obtain a file descriptor for the symbolic link +(rather than the file to which it refers) +by specifying the +.B O_PATH +flag in a subsequent call to +.BR open_by_handle_at (2). +Again, that file descriptor can be used in the +aforementioned system calls to operate on the symbolic link itself. +.SS Handling of symbolic links by system calls and commands +Symbolic links are handled either by operating on the link itself, +or by operating on the object referred to by the link. +In the latter case, +an application or system call is said to +.I follow +the link. +Symbolic links may refer to other symbolic links, +in which case the links are dereferenced until an object that is +not a symbolic link is found, +a symbolic link that refers to a file which does not exist is found, +or a loop is detected. +(Loop detection is done by placing an upper limit on the number of +links that may be followed, and an error results if this limit is +exceeded.) +.PP +There are three separate areas that need to be discussed. +They are as follows: +.IP 1. 3 +Symbolic links used as filename arguments for system calls. +.IP 2. +Symbolic links specified as command-line arguments to utilities that +are not traversing a file tree. +.IP 3. +Symbolic links encountered by utilities that are traversing a file tree +(either specified on the command line or encountered as part of the +file hierarchy walk). +.SS System calls +The first area is symbolic links used as filename arguments for +system calls. +.PP +Except as noted below, all system calls follow symbolic links. +For example, if there were a symbolic link +.I slink +which pointed to a file named +.IR afile , +the system call +.I "open(""slink"" ...\&)" +would return a file descriptor referring to the file +.IR afile . +.PP +Various system calls do not follow links, and operate +on the symbolic link itself. +They are: +.BR lchown (2), +.BR lgetxattr (2), +.BR llistxattr (2), +.BR lremovexattr (2), +.BR lsetxattr (2), +.BR lstat (2), +.BR readlink (2), +.BR rename (2), +.BR rmdir (2), +and +.BR unlink (2). +.PP +Certain other system calls optionally follow symbolic links. +They are: +.BR faccessat (2), +.\" Maybe one day: .BR fchownat (2) +.BR fchownat (2), +.BR fstatat (2), +.BR linkat (2), +.BR name_to_handle_at (2), +.BR open (2), +.BR openat (2), +.BR open_by_handle_at (2), +and +.BR utimensat (2); +see their manual pages for details. +Because +.BR remove (3) +is an alias for +.BR unlink (2), +that library function also does not follow symbolic links. +When +.BR rmdir (2) +is applied to a symbolic link, it fails with the error +.BR ENOTDIR . +.PP +.BR link (2) +warrants special discussion. +POSIX.1-2001 specifies that +.BR link (2) +should dereference +.I oldpath +if it is a symbolic link. +However, Linux does not do this. +(By default, Solaris is the same, +but the POSIX.1-2001 specified behavior can be obtained with +suitable compiler options.) +POSIX.1-2008 changed the specification to allow +either behavior in an implementation. +.SS Commands not traversing a file tree +The second area is symbolic links, specified as command-line +filename arguments, to commands which are not traversing a file tree. +.PP +Except as noted below, commands follow symbolic links named as +command-line arguments. +For example, if there were a symbolic link +.I slink +which pointed to a file named +.IR afile , +the command +.I "cat slink" +would display the contents of the file +.IR afile . +.PP +It is important to realize that this rule includes commands which may +optionally traverse file trees; for example, the command +.I "chown file" +is included in this rule, while the command +.IR "chown\ \-R file" , +which performs a tree traversal, is not. +(The latter is described in the third area, below.) +.PP +If it is explicitly intended that the command operate on the symbolic +link instead of following the symbolic link\(emfor example, it is desired that +.I "chown slink" +change the ownership of the file that +.I slink +is, whether it is a symbolic link or not\(emthe +.I \-h +option should be used. +In the above example, +.I "chown root slink" +would change the ownership of the file referred to by +.IR slink , +while +.I "chown\ \-h root slink" +would change the ownership of +.I slink +itself. +.PP +There are some exceptions to this rule: +.IP * 2 +The +.BR mv (1) +and +.BR rm (1) +commands do not follow symbolic links named as arguments, +but respectively attempt to rename and delete them. +(Note, if the symbolic link references a file via a relative path, +moving it to another directory may very well cause it to stop working, +since the path may no longer be correct.) +.IP * +The +.BR ls (1) +command is also an exception to this rule. +For compatibility with historic systems (when +.BR ls (1) +is not doing a tree walk\(emthat is, +.I \-R +option is not specified), +the +.BR ls (1) +command follows symbolic links named as arguments if the +.I \-H +or +.I \-L +option is specified, +or if the +.IR \-F , +.IR \-d , +or +.I \-l +options are not specified. +(The +.BR ls (1) +command is the only command where the +.I \-H +and +.I \-L +options affect its behavior even though it is not doing a walk of +a file tree.) +.IP * +The +.BR file (1) +command is also an exception to this rule. +The +.BR file (1) +command does not follow symbolic links named as argument by default. +The +.BR file (1) +command does follow symbolic links named as argument if the +.I \-L +option is specified. +.\" +.\"The 4.4BSD system differs from historical 4BSD systems in that the +.\".BR chown (1) +.\"and +.\".BR chgrp (1) +.\"commands follow symbolic links specified on the command line. +.SS Commands traversing a file tree +The following commands either optionally or always traverse file trees: +.BR chgrp (1), +.BR chmod (1), +.BR chown (1), +.BR cp (1), +.BR du (1), +.BR find (1), +.BR ls (1), +.BR pax (1), +.BR rm (1), +and +.BR tar (1). +.PP +It is important to realize that the following rules apply equally to +symbolic links encountered during the file tree traversal and symbolic +links listed as command-line arguments. +.PP +The \fIfirst rule\fP applies to symbolic links that reference files other +than directories. +Operations that apply to symbolic links are performed on the links +themselves, but otherwise the links are ignored. +.PP +The command +.I "rm\ \-r slink directory" +will remove +.IR slink , +as well as any symbolic links encountered in the tree traversal of +.IR directory , +because symbolic links may be removed. +In no case will +.BR rm (1) +affect the file referred to by +.IR slink . +.PP +The \fIsecond rule\fP applies to symbolic links that refer to directories. +Symbolic links that refer to directories are never followed by default. +This is often referred to as a "physical" walk, as opposed to a "logical" +walk (where symbolic links that refer to directories are followed). +.PP +Certain conventions are (should be) followed as consistently as +possible by commands that perform file tree walks: +.IP * 2 +A command can be made to follow +any symbolic links named on the command line, +regardless of the type of file they reference, by specifying the +.I \-H +(for "half-logical") flag. +This flag is intended to make the command-line name space look +like the logical name space. +(Note, for commands that do not always do file tree traversals, the +.I \-H +flag will be ignored if the +.I \-R +flag is not also specified.) +.IP +For example, the command +.I "chown\ \-HR user slink" +will traverse the file hierarchy rooted in the file pointed to by +.IR slink . +Note, the +.I \-H +is not the same as the previously discussed +.I \-h +flag. +The +.I \-H +flag causes symbolic links specified on the command line to be +dereferenced for the purposes of both the action to be performed +and the tree walk, and it is as if the user had specified the +name of the file to which the symbolic link pointed. +.IP * +A command can be made to +follow any symbolic links named on the command line, +as well as any symbolic links encountered during the traversal, +regardless of the type of file they reference, by specifying the +.I \-L +(for "logical") flag. +This flag is intended to make the entire name space look like +the logical name space. +(Note, for commands that do not always do file tree traversals, the +.I \-L +flag will be ignored if the +.I \-R +flag is not also specified.) +.IP +For example, the command +.I "chown\ \-LR user slink" +will change the owner of the file referred to by +.IR slink . +If +.I slink +refers to a directory, +.B chown +will traverse the file hierarchy rooted in the directory that it +references. +In addition, if any symbolic links are encountered in any file tree that +.B chown +traverses, they will be treated in the same fashion as +.IR slink . +.IP * +A command can be made to +provide the default behavior by specifying the +.I \-P +(for "physical") flag. +This flag is intended to make the entire name space look like the +physical name space. +.PP +For commands that do not by default do file tree traversals, the +.IR \-H , +.IR \-L , +and +.I \-P +flags are ignored if the +.I \-R +flag is not also specified. +In addition, you may specify the +.IR \-H , +.IR \-L , +and +.I \-P +options more than once; +the last one specified determines the command's behavior. +This is intended to permit you to alias commands to behave one way +or the other, and then override that behavior on the command line. +.PP +The +.BR ls (1) +and +.BR rm (1) +commands have exceptions to these rules: +.IP * 2 +The +.BR rm (1) +command operates on the symbolic link, and not the file it references, +and therefore never follows a symbolic link. +The +.BR rm (1) +command does not support the +.IR \-H , +.IR \-L , +or +.I \-P +options. +.IP * +To maintain compatibility with historic systems, +the +.BR ls (1) +command acts a little differently. +If you do not specify the +.IR \-F , +.IR \-d +or +.I \-l +options, +.BR ls (1) +will follow symbolic links specified on the command line. +If the +.I \-L +flag is specified, +.BR ls (1) +follows all symbolic links, +regardless of their type, +whether specified on the command line or encountered in the tree walk. +.SH SEE ALSO +.BR chgrp (1), +.BR chmod (1), +.BR find (1), +.BR ln (1), +.BR ls (1), +.BR mv (1), +.BR namei (1), +.BR rm (1), +.BR lchown (2), +.BR link (2), +.BR lstat (2), +.BR readlink (2), +.BR rename (2), +.BR symlink (2), +.BR unlink (2), +.BR utimensat (2), +.BR lutimes (3), +.BR path_resolution (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/tcp.7 b/man7/tcp.7 new file mode 100644 index 0000000..0ff5030 --- /dev/null +++ b/man7/tcp.7 @@ -0,0 +1,1385 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" and Copyright (C) 2008 Michael Kerrisk +.\" Note also that many pieces are drawn from the kernel source file +.\" Documentation/networking/ip-sysctl.txt. +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" 2.4 Updates by Nivedita Singhvi 4/20/02 . +.\" Modified, 2004-11-11, Michael Kerrisk and Andries Brouwer +.\" Updated details of interaction of TCP_CORK and TCP_NODELAY. +.\" +.\" 2008-11-21, mtk, many, many updates. +.\" The descriptions of /proc files and socket options should now +.\" be more or less up to date and complete as at Linux 2.6.27 +.\" (other than the remaining FIXMEs in the page source below). +.\" +.\" FIXME The following need to be documented +.\" TCP_MD5SIG (2.6.20) +.\" commit cfb6eeb4c860592edd123fdea908d23c6ad1c7dc +.\" Author was yoshfuji@linux-ipv6.org +.\" Needs CONFIG_TCP_MD5SIG +.\" From net/inet/Kconfig: +.\" bool "TCP: MD5 Signature Option support (RFC2385) (EXPERIMENTAL)" +.\" RFC2385 specifies a method of giving MD5 protection to TCP sessions. +.\" Its main (only?) use is to protect BGP sessions between core routers +.\" on the Internet. +.\" +.\" There is a TCP_MD5SIG option documented in FreeBSD's tcp(4), +.\" but probably many details are different on Linux +.\" http://thread.gmane.org/gmane.linux.network/47490 +.\" http://www.daemon-systems.org/man/tcp.4.html +.\" http://article.gmane.org/gmane.os.netbsd.devel.network/3767/match=tcp_md5sig+freebsd +.\" +.\" TCP_COOKIE_TRANSACTIONS (2.6.33) +.\" commit 519855c508b9a17878c0977a3cdefc09b59b30df +.\" Author: William Allen Simpson +.\" commit e56fb50f2b7958b931c8a2fc0966061b3f3c8f3a +.\" Author: William Allen Simpson +.\" +.\" REMOVED in Linux 3.10 +.\" commit 1a2c6181c4a1922021b4d7df373bba612c3e5f04 +.\" Author: Christoph Paasch +.\" +.\" TCP_THIN_LINEAR_TIMEOUTS (2.6.34) +.\" commit 36e31b0af58728071e8023cf8e20c5166b700717 +.\" Author: Andreas Petlund +.\" +.\" TCP_THIN_DUPACK (2.6.34) +.\" commit 7e38017557bc0b87434d184f8804cadb102bb903 +.\" Author: Andreas Petlund +.\" +.\" TCP_REPAIR (3.5) +.\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37 +.\" Author: Pavel Emelyanov +.\" See also +.\" http://criu.org/TCP_connection +.\" https://lwn.net/Articles/495304/ +.\" +.\" TCP_REPAIR_QUEUE (3.5) +.\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37 +.\" Author: Pavel Emelyanov +.\" +.\" TCP_QUEUE_SEQ (3.5) +.\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37 +.\" Author: Pavel Emelyanov +.\" +.\" TCP_REPAIR_OPTIONS (3.5) +.\" commit b139ba4e90dccbf4cd4efb112af96a5c9e0b098c +.\" Author: Pavel Emelyanov +.\" +.\" TCP_FASTOPEN (3.6) +.\" (Fast Open server side implementation completed in 3.7) +.\" http://lwn.net/Articles/508865/ +.\" +.\" TCP_TIMESTAMP (3.9) +.\" commit 93be6ce0e91b6a94783e012b1857a347a5e6e9f2 +.\" Author: Andrey Vagin +.\" +.\" TCP_NOTSENT_LOWAT (3.12) +.\" commit c9bee3b7fdecb0c1d070c7b54113b3bdfb9a3d36 +.\" Author: Eric Dumazet +.\" +.\" TCP_CC_INFO (4.1) +.\" commit 6e9250f59ef9efb932c84850cd221f22c2a03c4a +.\" Author: Eric Dumazet +.\" +.\" TCP_SAVE_SYN, TCP_SAVED_SYN (4.2) +.\" commit cd8ae85299d54155702a56811b2e035e63064d3d +.\" Author: Eric Dumazet +.\" +.TH TCP 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +tcp \- TCP protocol +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B tcp_socket = socket(AF_INET, SOCK_STREAM, 0); +.SH DESCRIPTION +This is an implementation of the TCP protocol defined in +RFC\ 793, RFC\ 1122 and RFC\ 2001 with the NewReno and SACK +extensions. +It provides a reliable, stream-oriented, +full-duplex connection between two sockets on top of +.BR ip (7), +for both v4 and v6 versions. +TCP guarantees that the data arrives in order and +retransmits lost packets. +It generates and checks a per-packet checksum to catch +transmission errors. +TCP does not preserve record boundaries. +.PP +A newly created TCP socket has no remote or local address and is not +fully specified. +To create an outgoing TCP connection use +.BR connect (2) +to establish a connection to another TCP socket. +To receive new incoming connections, first +.BR bind (2) +the socket to a local address and port and then call +.BR listen (2) +to put the socket into the listening state. +After that a new socket for each incoming connection can be accepted using +.BR accept (2). +A socket which has had +.BR accept (2) +or +.BR connect (2) +successfully called on it is fully specified and may transmit data. +Data cannot be transmitted on listening or not yet connected sockets. +.PP +Linux supports RFC\ 1323 TCP high performance +extensions. +These include Protection Against Wrapped +Sequence Numbers (PAWS), Window Scaling and Timestamps. +Window scaling allows the use +of large (> 64\ kB) TCP windows in order to support links with high +latency or bandwidth. +To make use of them, the send and receive buffer sizes must be increased. +They can be set globally with the +.I /proc/sys/net/ipv4/tcp_wmem +and +.I /proc/sys/net/ipv4/tcp_rmem +files, or on individual sockets by using the +.B SO_SNDBUF +and +.B SO_RCVBUF +socket options with the +.BR setsockopt (2) +call. +.PP +The maximum sizes for socket buffers declared via the +.B SO_SNDBUF +and +.B SO_RCVBUF +mechanisms are limited by the values in the +.I /proc/sys/net/core/rmem_max +and +.I /proc/sys/net/core/wmem_max +files. +Note that TCP actually allocates twice the size of +the buffer requested in the +.BR setsockopt (2) +call, and so a succeeding +.BR getsockopt (2) +call will not return the same size of buffer as requested in the +.BR setsockopt (2) +call. +TCP uses the extra space for administrative purposes and internal +kernel structures, and the +.I /proc +file values reflect the +larger sizes compared to the actual TCP windows. +On individual connections, the socket buffer size must be set prior to the +.BR listen (2) +or +.BR connect (2) +calls in order to have it take effect. +See +.BR socket (7) +for more information. +.PP +TCP supports urgent data. +Urgent data is used to signal the +receiver that some important message is part of the data +stream and that it should be processed as soon as possible. +To send urgent data specify the +.B MSG_OOB +option to +.BR send (2). +When urgent data is received, the kernel sends a +.B SIGURG +signal to the process or process group that has been set as the +socket "owner" using the +.B SIOCSPGRP +or +.B FIOSETOWN +ioctls (or the POSIX.1-specified +.BR fcntl (2) +.B F_SETOWN +operation). +When the +.B SO_OOBINLINE +socket option is enabled, urgent data is put into the normal +data stream (a program can test for its location using the +.B SIOCATMARK +ioctl described below), +otherwise it can be received only when the +.B MSG_OOB +flag is set for +.BR recv (2) +or +.BR recvmsg (2). +.PP +When out-of-band data is present, +.BR select (2) +indicates the file descriptor as having an exceptional condition and +.I poll (2) +indicates a +.B POLLPRI +event. +.PP +Linux 2.4 introduced a number of changes for improved +throughput and scaling, as well as enhanced functionality. +Some of these features include support for zero-copy +.BR sendfile (2), +Explicit Congestion Notification, new +management of TIME_WAIT sockets, keep-alive socket options +and support for Duplicate SACK extensions. +.SS Address formats +TCP is built on top of IP (see +.BR ip (7)). +The address formats defined by +.BR ip (7) +apply to TCP. +TCP supports point-to-point communication only; +broadcasting and multicasting are not +supported. +.SS /proc interfaces +System-wide TCP parameter settings can be accessed by files in the directory +.IR /proc/sys/net/ipv4/ . +In addition, most IP +.I /proc +interfaces also apply to TCP; see +.BR ip (7). +Variables described as +.I Boolean +take an integer value, with a nonzero value ("true") meaning that +the corresponding option is enabled, and a zero value ("false") +meaning that the option is disabled. +.TP +.IR tcp_abc " (Integer; default: 0; Linux 2.6.15 to Linux 3.8)" +.\" Since 2.6.15; removed in 3.9 +.\" commit ca2eb5679f8ddffff60156af42595df44a315ef0 +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +Control the Appropriate Byte Count (ABC), defined in RFC 3465. +ABC is a way of increasing the congestion window +.RI ( cwnd ) +more slowly in response to partial acknowledgments. +Possible values are: +.RS +.IP 0 3 +increase +.I cwnd +once per acknowledgment (no ABC) +.IP 1 +increase +.I cwnd +once per acknowledgment of full sized segment +.IP 2 +allow increase +.I cwnd +by two if acknowledgment is +of two segments to compensate for delayed acknowledgments. +.RE +.TP +.IR tcp_abort_on_overflow " (Boolean; default: disabled; since Linux 2.4)" +.\" Since 2.3.41 +Enable resetting connections if the listening service is too +slow and unable to keep up and accept them. +It means that if overflow occurred due +to a burst, the connection will recover. +Enable this option +.I only +if you are really sure that the listening daemon +cannot be tuned to accept connections faster. +Enabling this option can harm the clients of your server. +.TP +.IR tcp_adv_win_scale " (integer; default: 2; since Linux 2.4)" +.\" Since 2.4.0-test7 +Count buffering overhead as +.IR "bytes/2^tcp_adv_win_scale" , +if +.I tcp_adv_win_scale +is greater than 0; or +.IR "bytes-bytes/2^(\-tcp_adv_win_scale)" , +if +.I tcp_adv_win_scale +is less than or equal to zero. +.IP +The socket receive buffer space is shared between the +application and kernel. +TCP maintains part of the buffer as +the TCP window, this is the size of the receive window +advertised to the other end. +The rest of the space is used +as the "application" buffer, used to isolate the network +from scheduling and application latencies. +The +.I tcp_adv_win_scale +default value of 2 implies that the space +used for the application buffer is one fourth that of the total. +.TP +.IR tcp_allowed_congestion_control " (String; default: see text; since Linux 2.4.20)" +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +Show/set the congestion control algorithm choices available to unprivileged +processes (see the description of the +.B TCP_CONGESTION +socket option). +The items in the list are separated by white space and +terminated by a newline character. +The list is a subset of those listed in +.IR tcp_available_congestion_control . +The default value for this list is "reno" plus the default setting of +.IR tcp_congestion_control . +.TP +.IR tcp_autocorking " (Boolean; default: enabled; since Linux 3.14)" +.\" commit f54b311142a92ea2e42598e347b84e1655caf8e3 +.\" Text heavily based on Documentation/networking/ip-sysctl.txt +If this option is enabled, the kernel tries to coalesce small writes +(from consecutive +.BR write (2) +and +.BR sendmsg (2) +calls) as much as possible, +in order to decrease the total number of sent packets. +Coalescing is done if at least one prior packet for the flow +is waiting in Qdisc queues or device transmit queue. +Applications can still use the +.B TCP_CORK +socket option to obtain optimal behavior +when they know how/when to uncork their sockets. +.TP +.IR tcp_available_congestion_control " (String; read-only; since Linux 2.4.20)" +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +Show a list of the congestion-control algorithms +that are registered. +The items in the list are separated by white space and +terminated by a newline character. +This list is a limiting set for the list in +.IR tcp_allowed_congestion_control . +More congestion-control algorithms may be available as modules, +but not loaded. +.TP +.IR tcp_app_win " (integer; default: 31; since Linux 2.4)" +.\" Since 2.4.0-test7 +This variable defines how many +bytes of the TCP window are reserved for buffering overhead. +.IP +A maximum of (\fIwindow/2^tcp_app_win\fP, mss) bytes in the window +are reserved for the application buffer. +A value of 0 implies that no amount is reserved. +.\" +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_base_mss " (Integer; default: 512; since Linux 2.6.17) +The initial value of +.I search_low +to be used by the packetization layer Path MTU discovery (MTU probing). +If MTU probing is enabled, +this is the initial MSS used by the connection. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_bic " (Boolean; default: disabled; Linux 2.4.27/2.6.6 to 2.6.13)" +Enable BIC TCP congestion control algorithm. +BIC-TCP is a sender-side-only change that ensures a linear RTT +fairness under large windows while offering both scalability and +bounded TCP-friendliness. +The protocol combines two schemes +called additive increase and binary search increase. +When the congestion window is large, additive increase with a large +increment ensures linear RTT fairness as well as good scalability. +Under small congestion windows, binary search +increase provides TCP friendliness. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_bic_low_window " (integer; default: 14; Linux 2.4.27/2.6.6 to 2.6.13)" +Set the threshold window (in packets) where BIC TCP starts to +adjust the congestion window. +Below this threshold BIC TCP behaves the same as the default TCP Reno. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_bic_fast_convergence " (Boolean; default: enabled; Linux 2.4.27/2.6.6 to 2.6.13)" +Force BIC TCP to more quickly respond to changes in congestion window. +Allows two flows sharing the same connection to converge more rapidly. +.TP +.IR tcp_congestion_control " (String; default: see text; since Linux 2.4.13)" +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +Set the default congestion-control algorithm to be used for new connections. +The algorithm "reno" is always available, +but additional choices may be available depending on kernel configuration. +The default value for this file is set as part of kernel configuration. +.TP +.IR tcp_dma_copybreak " (integer; default: 4096; since Linux 2.6.24)" +Lower limit, in bytes, of the size of socket reads that will be +offloaded to a DMA copy engine, if one is present in the system +and the kernel was configured with the +.B CONFIG_NET_DMA +option. +.TP +.IR tcp_dsack " (Boolean; default: enabled; since Linux 2.4)" +.\" Since 2.4.0-test7 +Enable RFC\ 2883 TCP Duplicate SACK support. +.TP +.IR tcp_ecn " (Integer; default: see below; since Linux 2.4)" +.\" Since 2.4.0-test7 +Enable RFC\ 3168 Explicit Congestion Notification. +.IP +This file can have one of the following values: +.RS +.IP 0 +Disable ECN. +Neither initiate nor accept ECN. +This was the default up to and including Linux 2.6.30. +.IP 1 +Enable ECN when requested by incoming connections and also +request ECN on outgoing connection attempts. +.IP 2 +.\" commit 255cac91c3c9ce7dca7713b93ab03c75b7902e0e +Enable ECN when requested by incoming connections, +but do not request ECN on outgoing connections. +This value is supported, and is the default, since Linux 2.6.31. +.RE +.IP +When enabled, connectivity to some destinations could be affected +due to older, misbehaving middle boxes along the path, causing +connections to be dropped. +However, to facilitate and encourage deployment with option 1, and +to work around such buggy equipment, the +.B tcp_ecn_fallback +option has been introduced. +.TP +.IR tcp_ecn_fallback " (Boolean; default: enabled; since Linux 4.1)" +.\" commit 492135557dc090a1abb2cfbe1a412757e3ed68ab +Enable RFC\ 3168, Section 6.1.1.1. fallback. +When enabled, outgoing ECN-setup SYNs that time out within the +normal SYN retransmission timeout will be resent with CWR and +ECE cleared. +.TP +.IR tcp_fack " (Boolean; default: enabled; since Linux 2.2)" +.\" Since 2.1.92 +Enable TCP Forward Acknowledgement support. +.TP +.IR tcp_fin_timeout " (integer; default: 60; since Linux 2.2)" +.\" Since 2.1.53 +This specifies how many seconds to wait for a final FIN packet before the +socket is forcibly closed. +This is strictly a violation of the TCP specification, +but required to prevent denial-of-service attacks. +In Linux 2.2, the default value was 180. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_frto " (integer; default: see below; since Linux 2.4.21/2.6)" +.\" Since 2.4.21/2.5.43 +Enable F-RTO, an enhanced recovery algorithm for TCP retransmission +timeouts (RTOs). +It is particularly beneficial in wireless environments +where packet loss is typically due to random radio interference +rather than intermediate router congestion. +See RFC 4138 for more details. +.IP +This file can have one of the following values: +.RS +.IP 0 3 +Disabled. +This was the default up to and including Linux 2.6.23. +.IP 1 +The basic version F-RTO algorithm is enabled. +.IP 2 +.\" commit c96fd3d461fa495400df24be3b3b66f0e0b152f9 +Enable SACK-enhanced F-RTO if flow uses SACK. +The basic version can be used also when +SACK is in use though in that case scenario(s) exists where F-RTO +interacts badly with the packet counting of the SACK-enabled TCP flow. +This value is the default since Linux 2.6.24. +.RE +.IP +Before Linux 2.6.22, this parameter was a Boolean value, +supporting just values 0 and 1 above. +.TP +.IR tcp_frto_response " (integer; default: 0; since Linux 2.6.22)" +When F-RTO has detected that a TCP retransmission timeout was spurious +(i.e., the timeout would have been avoided had TCP set a +longer retransmission timeout), +TCP has several options concerning what to do next. +Possible values are: +.RS +.IP 0 3 +Rate halving based; a smooth and conservative response, +results in halved congestion window +.RI ( cwnd ) +and slow-start threshold +.RI ( ssthresh ) +after one RTT. +.IP 1 +Very conservative response; not recommended because even +though being valid, it interacts poorly with the rest of Linux TCP; halves +.I cwnd +and +.I ssthresh +immediately. +.IP 2 +Aggressive response; undoes congestion-control measures +that are now known to be unnecessary +(ignoring the possibility of a lost retransmission that would require +TCP to be more cautious); +.I cwnd +and +.I ssthresh +are restored to the values prior to timeout. +.RE +.TP +.IR tcp_keepalive_intvl " (integer; default: 75; since Linux 2.4)" +.\" Since 2.3.18 +The number of seconds between TCP keep-alive probes. +.TP +.IR tcp_keepalive_probes " (integer; default: 9; since Linux 2.2)" +.\" Since 2.1.43 +The maximum number of TCP keep-alive probes to send +before giving up and killing the connection if +no response is obtained from the other end. +.TP +.IR tcp_keepalive_time " (integer; default: 7200; since Linux 2.2)" +.\" Since 2.1.43 +The number of seconds a connection needs to be idle +before TCP begins sending out keep-alive probes. +Keep-alives are sent only when the +.B SO_KEEPALIVE +socket option is enabled. +The default value is 7200 seconds (2 hours). +An idle connection is terminated after +approximately an additional 11 minutes (9 probes an interval +of 75 seconds apart) when keep-alive is enabled. +.IP +Note that underlying connection tracking mechanisms and +application timeouts may be much shorter. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_low_latency " (Boolean; default: disabled; since Linux 2.4.21/2.6)" +.\" Since 2.4.21/2.5.60 +If enabled, the TCP stack makes decisions that prefer lower +latency as opposed to higher throughput. +It this option is disabled, then higher throughput is preferred. +An example of an application where this default should be +changed would be a Beowulf compute cluster. +.TP +.IR tcp_max_orphans " (integer; default: see below; since Linux 2.4)" +.\" Since 2.3.41 +The maximum number of orphaned (not attached to any user file +handle) TCP sockets allowed in the system. +When this number is exceeded, +the orphaned connection is reset and a warning is printed. +This limit exists only to prevent simple denial-of-service attacks. +Lowering this limit is not recommended. +Network conditions might require you to increase the number of +orphans allowed, but note that each orphan can eat up to ~64\ kB +of unswappable memory. +The default initial value is set equal to the kernel parameter NR_FILE. +This initial default is adjusted depending on the memory in the system. +.TP +.IR tcp_max_syn_backlog " (integer; default: see below; since Linux 2.2)" +.\" Since 2.1.53 +The maximum number of queued connection requests which have +still not received an acknowledgement from the connecting client. +If this number is exceeded, the kernel will begin +dropping requests. +The default value of 256 is increased to +1024 when the memory present in the system is adequate or +greater (>= 128\ MB), and reduced to 128 for those systems with +very low memory (<= 32\ MB). +.IP +Prior to Linux 2.6.20, +.\" commit 72a3effaf633bcae9034b7e176bdbd78d64a71db +it was recommended that if this needed to be increased above 1024, +the size of the SYNACK hash table +.RB ( TCP_SYNQ_HSIZE ) +in +.I include/net/tcp.h +should be modified to keep +.IP + TCP_SYNQ_HSIZE * 16 <= tcp_max_syn_backlog +.IP +and the kernel should be +recompiled. +In Linux 2.6.20, the fixed sized +.B TCP_SYNQ_HSIZE +was removed in favor of dynamic sizing. +.TP +.IR tcp_max_tw_buckets " (integer; default: see below; since Linux 2.4)" +.\" Since 2.3.41 +The maximum number of sockets in TIME_WAIT state allowed in +the system. +This limit exists only to prevent simple denial-of-service attacks. +The default value of NR_FILE*2 is adjusted +depending on the memory in the system. +If this number is +exceeded, the socket is closed and a warning is printed. +.TP +.IR tcp_moderate_rcvbuf " (Boolean; default: enabled; since Linux 2.4.17/2.6.7)" +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +If enabled, TCP performs receive buffer auto-tuning, +attempting to automatically size the buffer (no greater than +.IR tcp_rmem[2] ) +to match the size required by the path for full throughput. +.TP +.IR tcp_mem " (since Linux 2.4) +.\" Since 2.4.0-test7 +This is a vector of 3 integers: [low, pressure, high]. +These bounds, measured in units of the system page size, +are used by TCP to track its memory usage. +The defaults are calculated at boot time from the amount of +available memory. +(TCP can only use +.I "low memory" +for this, which is limited to around 900 megabytes on 32-bit systems. +64-bit systems do not suffer this limitation.) +.RS +.TP 10 +.I low +TCP doesn't regulate its memory allocation when the number +of pages it has allocated globally is below this number. +.TP +.I pressure +When the amount of memory allocated by TCP +exceeds this number of pages, TCP moderates its memory consumption. +This memory pressure state is exited +once the number of pages allocated falls below +the +.I low +mark. +.TP +.I high +The maximum number of pages, globally, that TCP will allocate. +This value overrides any other limits imposed by the kernel. +.RE +.TP +.IR tcp_mtu_probing " (integer; default: 0; since Linux 2.6.17)" +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +This parameter controls TCP Packetization-Layer Path MTU Discovery. +The following values may be assigned to the file: +.RS +.IP 0 3 +Disabled +.IP 1 +Disabled by default, enabled when an ICMP black hole detected +.IP 2 +Always enabled, use initial MSS of +.IR tcp_base_mss . +.RE +.TP +.IR tcp_no_metrics_save " (Boolean; default: disabled; since Linux 2.6.6)" +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +By default, TCP saves various connection metrics in the route cache +when the connection closes, so that connections established in the +near future can use these to set initial conditions. +Usually, this increases overall performance, +but it may sometimes cause performance degradation. +If +.I tcp_no_metrics_save +is enabled, TCP will not cache metrics on closing connections. +.TP +.IR tcp_orphan_retries " (integer; default: 8; since Linux 2.4)" +.\" Since 2.3.41 +The maximum number of attempts made to probe the other +end of a connection which has been closed by our end. +.TP +.IR tcp_reordering " (integer; default: 3; since Linux 2.4)" +.\" Since 2.4.0-test7 +The maximum a packet can be reordered in a TCP packet stream +without TCP assuming packet loss and going into slow start. +It is not advisable to change this number. +This is a packet reordering detection metric designed to +minimize unnecessary back off and retransmits provoked by +reordering of packets on a connection. +.TP +.IR tcp_retrans_collapse " (Boolean; default: enabled; since Linux 2.2)" +.\" Since 2.1.96 +Try to send full-sized packets during retransmit. +.TP +.IR tcp_retries1 " (integer; default: 3; since Linux 2.2)" +.\" Since 2.1.43 +The number of times TCP will attempt to retransmit a +packet on an established connection normally, +without the extra effort of getting the network layers involved. +Once we exceed this number of +retransmits, we first have the network layer +update the route if possible before each new retransmit. +The default is the RFC specified minimum of 3. +.TP +.IR tcp_retries2 " (integer; default: 15; since Linux 2.2)" +.\" Since 2.1.43 +The maximum number of times a TCP packet is retransmitted +in established state before giving up. +The default value is 15, which corresponds to a duration of +approximately between 13 to 30 minutes, depending +on the retransmission timeout. +The RFC\ 1122 specified +minimum limit of 100 seconds is typically deemed too short. +.TP +.IR tcp_rfc1337 " (Boolean; default: disabled; since Linux 2.2)" +.\" Since 2.1.90 +Enable TCP behavior conformant with RFC\ 1337. +When disabled, +if a RST is received in TIME_WAIT state, we close +the socket immediately without waiting for the end +of the TIME_WAIT period. +.TP +.IR tcp_rmem " (since Linux 2.4)" +.\" Since 2.4.0-test7 +This is a vector of 3 integers: [min, default, max]. +These parameters are used by TCP to regulate receive buffer sizes. +TCP dynamically adjusts the size of the +receive buffer from the defaults listed below, in the range +of these values, depending on memory available in the system. +.RS +.TP 10 +.I min +minimum size of the receive buffer used by each TCP socket. +The default value is the system page size. +(On Linux 2.4, the default value is 4\ kB, lowered to +.B PAGE_SIZE +bytes in low-memory systems.) +This value +is used to ensure that in memory pressure mode, +allocations below this size will still succeed. +This is not +used to bound the size of the receive buffer declared +using +.B SO_RCVBUF +on a socket. +.TP +.I default +the default size of the receive buffer for a TCP socket. +This value overwrites the initial default buffer size from +the generic global +.I net.core.rmem_default +defined for all protocols. +The default value is 87380 bytes. +(On Linux 2.4, this will be lowered to 43689 in low-memory systems.) +If larger receive buffer sizes are desired, this value should +be increased (to affect all sockets). +To employ large TCP windows, the +.I net.ipv4.tcp_window_scaling +must be enabled (default). +.TP +.I max +the maximum size of the receive buffer used by each TCP socket. +This value does not override the global +.IR net.core.rmem_max . +This is not used to limit the size of the receive buffer declared using +.B SO_RCVBUF +on a socket. +The default value is calculated using the formula +.IP + max(87380, min(4\ MB, \fItcp_mem\fP[1]*PAGE_SIZE/128)) +.IP +(On Linux 2.4, the default is 87380*2 bytes, +lowered to 87380 in low-memory systems). +.RE +.TP +.IR tcp_sack " (Boolean; default: enabled; since Linux 2.2)" +.\" Since 2.1.36 +Enable RFC\ 2018 TCP Selective Acknowledgements. +.TP +.IR tcp_slow_start_after_idle " (Boolean; default: enabled; since Linux 2.6.18)" +.\" The following is from 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +If enabled, provide RFC 2861 behavior and time out the congestion +window after an idle period. +An idle period is defined as the current RTO (retransmission timeout). +If disabled, the congestion window will not +be timed out after an idle period. +.TP +.IR tcp_stdurg " (Boolean; default: disabled; since Linux 2.2)" +.\" Since 2.1.44 +If this option is enabled, then use the RFC\ 1122 interpretation +of the TCP urgent-pointer field. +.\" RFC 793 was ambiguous in its specification of the meaning of the +.\" urgent pointer. RFC 1122 (and RFC 961) fixed on a particular +.\" resolution of this ambiguity (unfortunately the "wrong" one). +According to this interpretation, the urgent pointer points +to the last byte of urgent data. +If this option is disabled, then use the BSD-compatible interpretation of +the urgent pointer: +the urgent pointer points to the first byte after the urgent data. +Enabling this option may lead to interoperability problems. +.TP +.IR tcp_syn_retries " (integer; default: 5; since Linux 2.2)" +.\" Since 2.1.38 +The maximum number of times initial SYNs for an active TCP +connection attempt will be retransmitted. +This value should not be higher than 255. +The default value is 5, which corresponds to approximately 180 seconds. +.TP +.IR tcp_synack_retries " (integer; default: 5; since Linux 2.2)" +.\" Since 2.1.38 +The maximum number of times a SYN/ACK segment +for a passive TCP connection will be retransmitted. +This number should not be higher than 255. +.TP +.IR tcp_syncookies " (Boolean; since Linux 2.2)" +.\" Since 2.1.43 +Enable TCP syncookies. +The kernel must be compiled with +.BR CONFIG_SYN_COOKIES . +Send out syncookies when the syn backlog queue of a socket overflows. +The syncookies feature attempts to protect a +socket from a SYN flood attack. +This should be used as a last resort, if at all. +This is a violation of the TCP protocol, +and conflicts with other areas of TCP such as TCP extensions. +It can cause problems for clients and relays. +It is not recommended as a tuning mechanism for heavily +loaded servers to help with overloaded or misconfigured conditions. +For recommended alternatives see +.IR tcp_max_syn_backlog , +.IR tcp_synack_retries , +and +.IR tcp_abort_on_overflow . +.TP +.IR tcp_timestamps " (integer; default: 1; since Linux 2.2)" +.\" Since 2.1.36 +Set to one of the following values to enable or disable RFC\ 1323 +TCP timestamps: +.RS +.IP 0 3 +Disable timestamps. +.IP 1 +Enable timestamps as defined in RFC1323 and use random offset for +each connection rather than only using the current time. +.IP 2 +As for the value 1, but without random offsets. +.\" commit 25429d7b7dca01dc4f17205de023a30ca09390d0 +Setting +.I tcp_timestamps +to this value is meaningful since Linux 4.10. +.RE +.TP +.IR tcp_tso_win_divisor " (integer; default: 3; since Linux 2.6.9)" +This parameter controls what percentage of the congestion window +can be consumed by a single TCP Segmentation Offload (TSO) frame. +The setting of this parameter is a tradeoff between burstiness and +building larger TSO frames. +.TP +.IR tcp_tw_recycle " (Boolean; default: disabled; Linux 2.4 to 4.11)" +.\" Since 2.3.15 +.\" removed in 4.12; commit 4396e46187ca5070219b81773c4e65088dac50cc +Enable fast recycling of TIME_WAIT sockets. +Enabling this option is +not recommended as the remote IP may not use monotonically increasing +timestamps (devices behind NAT, devices with per-connection timestamp +offsets). +See RFC 1323 (PAWS) and RFC 6191. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_tw_reuse " (Boolean; default: disabled; since Linux 2.4.19/2.6)" +.\" Since 2.4.19/2.5.43 +Allow to reuse TIME_WAIT sockets for new connections when it is +safe from protocol viewpoint. +It should not be changed without advice/request of technical experts. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_vegas_cong_avoid " (Boolean; default: disabled; Linux 2.2 to 2.6.13)" +.\" Since 2.1.8; removed in 2.6.13 +Enable TCP Vegas congestion avoidance algorithm. +TCP Vegas is a sender-side-only change to TCP that anticipates +the onset of congestion by estimating the bandwidth. +TCP Vegas adjusts the sending rate by modifying the congestion window. +TCP Vegas should provide less packet loss, but it is +not as aggressive as TCP Reno. +.\" +.\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_westwood " (Boolean; default: disabled; Linux 2.4.26/2.6.3 to 2.6.13)" +Enable TCP Westwood+ congestion control algorithm. +TCP Westwood+ is a sender-side-only modification of the TCP Reno +protocol stack that optimizes the performance of TCP congestion control. +It is based on end-to-end bandwidth estimation to set +congestion window and slow start threshold after a congestion episode. +Using this estimation, TCP Westwood+ adaptively sets a +slow start threshold and a congestion window which takes into +account the bandwidth used at the time congestion is experienced. +TCP Westwood+ significantly increases fairness with respect to +TCP Reno in wired networks and throughput over wireless links. +.TP +.IR tcp_window_scaling " (Boolean; default: enabled; since Linux 2.2)" +.\" Since 2.1.36 +Enable RFC\ 1323 TCP window scaling. +This feature allows the use of a large window +(> 64\ kB) on a TCP connection, should the other end support it. +Normally, the 16 bit window length field in the TCP header +limits the window size to less than 64\ kB. +If larger windows are desired, applications can increase the size of +their socket buffers and the window scaling option will be employed. +If +.I tcp_window_scaling +is disabled, TCP will not negotiate the use of window +scaling with the other end during connection setup. +.TP +.IR tcp_wmem " (since Linux 2.4)" +.\" Since 2.4.0-test7 +This is a vector of 3 integers: [min, default, max]. +These parameters are used by TCP to regulate send buffer sizes. +TCP dynamically adjusts the size of the send buffer from the +default values listed below, in the range of these values, +depending on memory available. +.RS +.TP 10 +.I min +Minimum size of the send buffer used by each TCP socket. +The default value is the system page size. +(On Linux 2.4, the default value is 4\ kB.) +This value is used to ensure that in memory pressure mode, +allocations below this size will still succeed. +This is not used to bound the size of the send buffer declared using +.B SO_SNDBUF +on a socket. +.TP +.I default +The default size of the send buffer for a TCP socket. +This value overwrites the initial default buffer size from +the generic global +.I /proc/sys/net/core/wmem_default +defined for all protocols. +The default value is 16\ kB. +.\" True in Linux 2.4 and 2.6 +If larger send buffer sizes are desired, this value +should be increased (to affect all sockets). +To employ large TCP windows, the +.I /proc/sys/net/ipv4/tcp_window_scaling +must be set to a nonzero value (default). +.TP +.I max +The maximum size of the send buffer used by each TCP socket. +This value does not override the value in +.IR /proc/sys/net/core/wmem_max . +This is not used to limit the size of the send buffer declared using +.B SO_SNDBUF +on a socket. +The default value is calculated using the formula +.IP + max(65536, min(4\ MB, \fItcp_mem\fP[1]*PAGE_SIZE/128)) +.IP +(On Linux 2.4, the default value is 128\ kB, +lowered 64\ kB depending on low-memory systems.) +.RE +.TP +.IR tcp_workaround_signed_windows " (Boolean; default: disabled; since Linux 2.6.26)" +If enabled, assume that no receipt of a window-scaling option means that the +remote TCP is broken and treats the window as a signed quantity. +If disabled, assume that the remote TCP is not broken even if we do +not receive a window scaling option from it. +.SS Socket options +To set or get a TCP socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR IPPROTO_TCP . +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.\" or SOL_TCP on Linux +In addition, +most +.B IPPROTO_IP +socket options are valid on TCP sockets. +For more information see +.BR ip (7). +.TP +.BR TCP_CONGESTION " (since Linux 2.6.13)" +.\" commit 5f8ef48d240963093451bcf83df89f1a1364f51d +.\" Author: Stephen Hemminger +The argument for this option is a string. +This option allows the caller to set the TCP congestion control +algorithm to be used, on a per-socket basis. +Unprivileged processes are restricted to choosing one of the algorithms in +.IR tcp_allowed_congestion_control +(described above). +Privileged processes +.RB ( CAP_NET_ADMIN ) +can choose from any of the available congestion-control algorithms +(see the description of +.IR tcp_available_congestion_control +above). +.TP +.BR TCP_CORK " (since Linux 2.2)" +.\" precisely: since 2.1.127 +If set, don't send out partial frames. +All queued partial frames are sent when the option is cleared again. +This is useful for prepending headers before calling +.BR sendfile (2), +or for throughput optimization. +As currently implemented, there is a 200 millisecond ceiling on the time +for which output is corked by +.BR TCP_CORK . +If this ceiling is reached, then queued data is automatically transmitted. +This option can be combined with +.B TCP_NODELAY +only since Linux 2.5.71. +This option should not be used in code intended to be portable. +.TP +.BR TCP_DEFER_ACCEPT " (since Linux 2.4)" +.\" Precisely: since 2.3.38 +.\" Useful references: +.\" http://www.techrepublic.com/article/take-advantage-of-tcp-ip-options-to-optimize-data-transmission/ +.\" http://unix.stackexchange.com/questions/94104/real-world-use-of-tcp-defer-accept +Allow a listener to be awakened only when data arrives on the socket. +Takes an integer value (seconds), this can +bound the maximum number of attempts TCP will make to +complete the connection. +This option should not be used in code intended to be portable. +.TP +.BR TCP_INFO " (since Linux 2.4)" +Used to collect information about this socket. +The kernel returns a \fIstruct tcp_info\fP as defined in the file +.IR /usr/include/linux/tcp.h . +This option should not be used in code intended to be portable. +.TP +.BR TCP_KEEPCNT " (since Linux 2.4)" +.\" Precisely: since 2.3.18 +The maximum number of keepalive probes TCP should send +before dropping the connection. +This option should not be +used in code intended to be portable. +.TP +.BR TCP_KEEPIDLE " (since Linux 2.4)" +.\" Precisely: since 2.3.18 +The time (in seconds) the connection needs to remain idle +before TCP starts sending keepalive probes, if the socket +option +.B SO_KEEPALIVE +has been set on this socket. +This option should not be used in code intended to be portable. +.TP +.BR TCP_KEEPINTVL " (since Linux 2.4)" +.\" Precisely: since 2.3.18 +The time (in seconds) between individual keepalive probes. +This option should not be used in code intended to be portable. +.TP +.BR TCP_LINGER2 " (since Linux 2.4)" +.\" Precisely: since 2.3.41 +The lifetime of orphaned FIN_WAIT2 state sockets. +This option can be used to override the system-wide setting in the file +.I /proc/sys/net/ipv4/tcp_fin_timeout +for this socket. +This is not to be confused with the +.BR socket (7) +level option +.BR SO_LINGER . +This option should not be used in code intended to be portable. +.TP +.B TCP_MAXSEG +.\" Present in Linux 1.0 +The maximum segment size for outgoing TCP packets. +In Linux 2.2 and earlier, and in Linux 2.6.28 and later, +if this option is set before connection establishment, it also +changes the MSS value announced to the other end in the initial packet. +Values greater than the (eventual) interface MTU have no effect. +TCP will also impose +its minimum and maximum bounds over the value provided. +.TP +.B TCP_NODELAY +.\" Present in Linux 1.0 +If set, disable the Nagle algorithm. +This means that segments +are always sent as soon as possible, even if there is only a +small amount of data. +When not set, data is buffered until there +is a sufficient amount to send out, thereby avoiding the +frequent sending of small packets, which results in poor +utilization of the network. +This option is overridden by +.BR TCP_CORK ; +however, setting this option forces an explicit flush of +pending output, even if +.B TCP_CORK +is currently set. +.TP +.BR TCP_QUICKACK " (since Linux 2.4.4)" +Enable quickack mode if set or disable quickack +mode if cleared. +In quickack mode, acks are sent +immediately, rather than delayed if needed in accordance +to normal TCP operation. +This flag is not permanent, +it only enables a switch to or from quickack mode. +Subsequent operation of the TCP protocol will +once again enter/leave quickack mode depending on +internal protocol processing and factors such as +delayed ack timeouts occurring and data transfer. +This option should not be used in code intended to be +portable. +.TP +.BR TCP_SYNCNT " (since Linux 2.4)" +.\" Precisely: since 2.3.18 +Set the number of SYN retransmits that TCP should send before +aborting the attempt to connect. +It cannot exceed 255. +This option should not be used in code intended to be portable. +.TP +.BR TCP_USER_TIMEOUT " (since Linux 2.6.37)" +.\" commit dca43c75e7e545694a9dd6288553f55c53e2a3a3 +.\" Author: Jerry Chu +.\" The following text taken nearly verbatim from Jerry Chu's (excellent) +.\" commit message. +.\" +This option takes an +.IR "unsigned int" +as an argument. +When the value is greater than 0, +it specifies the maximum amount of time in milliseconds that transmitted +data may remain unacknowledged before TCP will forcibly close the +corresponding connection and return +.B ETIMEDOUT +to the application. +If the option value is specified as 0, +TCP will to use the system default. +.IP +Increasing user timeouts allows a TCP connection to survive extended +periods without end-to-end connectivity. +Decreasing user timeouts +allows applications to "fail fast", if so desired. +Otherwise, failure may take up to 20 minutes with +the current system defaults in a normal WAN environment. +.IP +This option can be set during any state of a TCP connection, +but is effective only during the synchronized states of a connection +(ESTABLISHED, FIN-WAIT-1, FIN-WAIT-2, CLOSE-WAIT, CLOSING, and LAST-ACK). +Moreover, when used with the TCP keepalive +.RB ( SO_KEEPALIVE ) +option, +.B TCP_USER_TIMEOUT +will override keepalive to determine when to close a +connection due to keepalive failure. +.IP +The option has no effect on when TCP retransmits a packet, +nor when a keepalive probe is sent. +.IP +This option, like many others, will be inherited by the socket returned by +.BR accept (2), +if it was set on the listening socket. +.IP +Further details on the user timeout feature can be found in +RFC\ 793 and RFC\ 5482 ("TCP User Timeout Option"). +.TP +.BR TCP_WINDOW_CLAMP " (since Linux 2.4)" +.\" Precisely: since 2.3.41 +Bound the size of the advertised window to this value. +The kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. +This option should not be used in code intended to be +portable. +.SS Sockets API +TCP provides limited support for out-of-band data, +in the form of (a single byte of) urgent data. +In Linux this means if the other end sends newer out-of-band +data the older urgent data is inserted as normal data into +the stream (even when +.B SO_OOBINLINE +is not set). +This differs from BSD-based stacks. +.PP +Linux uses the BSD compatible interpretation of the urgent +pointer field by default. +This violates RFC\ 1122, but is +required for interoperability with other stacks. +It can be changed via +.IR /proc/sys/net/ipv4/tcp_stdurg . +.PP +It is possible to peek at out-of-band data using the +.BR recv (2) +.B MSG_PEEK +flag. +.PP +Since version 2.4, Linux supports the use of +.B MSG_TRUNC +in the +.I flags +argument of +.BR recv (2) +(and +.BR recvmsg (2)). +This flag causes the received bytes of data to be discarded, +rather than passed back in a caller-supplied buffer. +Since Linux 2.4.4, +.BR MSG_TRUNC +also has this effect when used in conjunction with +.BR MSG_OOB +to receive out-of-band data. +.SS Ioctls +The following +.BR ioctl (2) +calls return information in +.IR value . +The correct syntax is: +.PP +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.PP +.I ioctl_type +is one of the following: +.TP +.B SIOCINQ +Returns the amount of queued unread data in the receive buffer. +The socket must not be in LISTEN state, otherwise an error +.RB ( EINVAL ) +is returned. +.B SIOCINQ +is defined in +.IR . +.\" FIXME http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002, +.\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers +Alternatively, +you can use the synonymous +.BR FIONREAD , +defined in +.IR . +.TP +.B SIOCATMARK +Returns true (i.e., +.I value +is nonzero) if the inbound data stream is at the urgent mark. +.IP +If the +.B SO_OOBINLINE +socket option is set, and +.B SIOCATMARK +returns true, then the +next read from the socket will return the urgent data. +If the +.B SO_OOBINLINE +socket option is not set, and +.B SIOCATMARK +returns true, then the +next read from the socket will return the bytes following +the urgent data (to actually read the urgent data requires the +.B recv(MSG_OOB) +flag). +.IP +Note that a read never reads across the urgent mark. +If an application is informed of the presence of urgent data via +.BR select (2) +(using the +.I exceptfds +argument) or through delivery of a +.B SIGURG +signal, +then it can advance up to the mark using a loop which repeatedly tests +.B SIOCATMARK +and performs a read (requesting any number of bytes) as long as +.B SIOCATMARK +returns false. +.TP +.B SIOCOUTQ +Returns the amount of unsent data in the socket send queue. +The socket must not be in LISTEN state, otherwise an error +.RB ( EINVAL ) +is returned. +.B SIOCOUTQ +is defined in +.IR . +.\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002, +.\" filed 2010-09-10, may cause SIOCOUTQ to be defined in glibc headers +Alternatively, +you can use the synonymous +.BR TIOCOUTQ , +defined in +.IR . +.SS Error handling +When a network error occurs, TCP tries to resend the packet. +If it doesn't succeed after some time, either +.B ETIMEDOUT +or the last received error on this connection is reported. +.PP +Some applications require a quicker error notification. +This can be enabled with the +.B IPPROTO_IP +level +.B IP_RECVERR +socket option. +When this option is enabled, all incoming +errors are immediately passed to the user program. +Use this option with care \(em it makes TCP less tolerant to routing +changes and other normal network conditions. +.SH ERRORS +.TP +.B EAFNOTSUPPORT +Passed socket address type in +.I sin_family +was not +.BR AF_INET . +.TP +.B EPIPE +The other end closed the socket unexpectedly or a read is +executed on a shut down socket. +.TP +.B ETIMEDOUT +The other end didn't acknowledge retransmitted data after some time. +.PP +Any errors defined for +.BR ip (7) +or the generic socket layer may also be returned for TCP. +.SH VERSIONS +Support for Explicit Congestion Notification, zero-copy +.BR sendfile (2), +reordering support and some SACK extensions +(DSACK) were introduced in 2.4. +Support for forward acknowledgement (FACK), TIME_WAIT recycling, +and per-connection keepalive socket options were introduced in 2.3. +.SH BUGS +Not all errors are documented. +.br +IPv6 is not described. +.\" Only a single Linux kernel version is described +.\" Info for 2.2 was lost. Should be added again, +.\" or put into a separate page. +.\" .SH AUTHORS +.\" This man page was originally written by Andi Kleen. +.\" It was updated for 2.4 by Nivedita Singhvi with input from +.\" Alexey Kuznetsov's Documentation/networking/ip-sysctl.txt +.\" document. +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR getsockopt (2), +.BR listen (2), +.BR recvmsg (2), +.BR sendfile (2), +.BR sendmsg (2), +.BR socket (2), +.BR ip (7), +.BR socket (7) +.PP +RFC\ 793 for the TCP specification. +.br +RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm. +.br +RFC\ 1323 for TCP timestamp and window scaling options. +.br +RFC\ 1337 for a description of TIME_WAIT assassination hazards. +.br +RFC\ 3168 for a description of Explicit Congestion Notification. +.br +RFC\ 2581 for TCP congestion control algorithms. +.br +RFC\ 2018 and RFC\ 2883 for SACK and extensions to SACK. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/termio.7 b/man7/termio.7 new file mode 100644 index 0000000..f5c045f --- /dev/null +++ b/man7/termio.7 @@ -0,0 +1,74 @@ +.\" Copyright (c) 2006 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 28 Dec 2006 - Initial Creation +.\" +.TH TERMIO 7 2017-05-03 "Linux" "Linux Programmer's Manual" +.SH NAME +termio \- System V terminal driver interface +.SH DESCRIPTION +.B termio +is the name of the old System V terminal driver interface. +This interface defined a +.I termio +structure used to store terminal settings, and a range of +.BR ioctl (2) +operations to get and set terminal attributes. +.PP +The +.B termio +interface is now obsolete: POSIX.1-1990 standardized a modified +version of this interface, under the name +.BR termios . +The POSIX.1 data structure differs slightly from the +System V version, and POSIX.1 defined a suite of functions +to replace the various +.BR ioctl (2) +operations that existed in System V. +(This was done because +.BR ioctl (2) +was unstandardized, and its variadic third argument +does not allow argument type checking.) +.PP +If you're looking for a page called "termio", then you can probably +find most of the information that you seek in either +.BR termios (3) +or +.BR ioctl_tty (2). +.SH SEE ALSO +.BR reset (1), +.BR setterm (1), +.BR stty (1), +.BR ioctl_tty (2), +.BR termios (3), +.BR tty (4) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/thread-keyring.7 b/man7/thread-keyring.7 new file mode 100644 index 0000000..d916512 --- /dev/null +++ b/man7/thread-keyring.7 @@ -0,0 +1,65 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH "THREAD-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual" +.SH NAME +thread-keyring \- per-thread keyring +.SH DESCRIPTION +The thread keyring is a keyring used to anchor keys on behalf of a process. +It is created only when a thread requests it. +The thread keyring has the name (description) +.IR _tid . +.PP +A special serial number value, +.BR KEY_SPEC_THREAD_KEYRING , +is defined that can be used in lieu of the actual serial number of +the calling thread's thread keyring. +.PP +From the +.BR keyctl (1) +utility, '\fB@t\fP' can be used instead of a numeric key ID in +much the same way, but as +.BR keyctl (1) +is a program run after forking, this is of no utility. +.PP +Thread keyrings are not inherited across +.BR clone (2) +and +.BR fork (2) +and are cleared by +.BR execve (2). +A thread keyring is destroyed when the thread that refers to it terminates. +.PP +Initially, a thread does not have a thread keyring. +If a thread doesn't have a thread keyring when it is accessed, +then it will be created if it is to be modified; +otherwise the operation fails with the error +.BR ENOKEY . +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/time.7 b/man7/time.7 new file mode 100644 index 0000000..6d12665 --- /dev/null +++ b/man7/time.7 @@ -0,0 +1,231 @@ +.\" Copyright (c) 2006 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2008-06-24, mtk: added some details about where jiffies come into +.\" play; added section on high-resolution timers. +.\" +.TH TIME 7 2016-03-15 "Linux" "Linux Programmer's Manual" +.SH NAME +time \- overview of time and timers +.SH DESCRIPTION +.SS Real time and process time +.I "Real time" +is defined as time measured from some fixed point, +either from a standard point in the past +(see the description of the Epoch and calendar time below), +or from some point (e.g., the start) in the life of a process +.RI ( "elapsed time" ). +.PP +.I "Process time" +is defined as the amount of CPU time used by a process. +This is sometimes divided into +.I user +and +.I system +components. +User CPU time is the time spent executing code in user mode. +System CPU time is the time spent by the kernel executing +in system mode on behalf of the process (e.g., executing system calls). +The +.BR time (1) +command can be used to determine the amount of CPU time consumed +during the execution of a program. +A program can determine the amount of CPU time it has consumed using +.BR times (2), +.BR getrusage (2), +or +.BR clock (3). +.SS The hardware clock +Most computers have a (battery-powered) hardware clock which the kernel +reads at boot time in order to initialize the software clock. +For further details, see +.BR rtc (4) +and +.BR hwclock (8). +.SS The software clock, HZ, and jiffies +The accuracy of various system calls that set timeouts, +(e.g., +.BR select (2), +.BR sigtimedwait (2)) +.\" semtimedop(), mq_timedwait(), io_getevents(), poll() are the same +.\" futexes and thus sem_timedwait() seem to use high-res timers. +and measure CPU time (e.g., +.BR getrusage (2)) +is limited by the resolution of the +.IR "software clock" , +a clock maintained by the kernel which measures time in +.IR jiffies . +The size of a jiffy is determined by the value of the kernel constant +.IR HZ . +.PP +The value of +.I HZ +varies across kernel versions and hardware platforms. +On i386 the situation is as follows: +on kernels up to and including 2.4.x, HZ was 100, +giving a jiffy value of 0.01 seconds; +starting with 2.6.0, HZ was raised to 1000, giving a jiffy of +0.001 seconds. +Since kernel 2.6.13, the HZ value is a kernel +configuration parameter and can be 100, 250 (the default) or 1000, +yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. +Since kernel 2.6.20, a further frequency is available: +300, a number that divides evenly for the common video +frame rates (PAL, 25 HZ; NTSC, 30 HZ). +.PP +The +.BR times (2) +system call is a special case. +It reports times with a granularity defined by the kernel constant +.IR USER_HZ . +User-space applications can determine the value of this constant using +.IR sysconf(_SC_CLK_TCK) . +.\" glibc gets this info with a little help from the ELF loader; +.\" see glibc elf/dl-support.c and kernel fs/binfmt_elf.c. +.\" +.SS High-resolution timers +Before Linux 2.6.21, the accuracy of timer and sleep system calls +(see below) was also limited by the size of the jiffy. +.PP +Since Linux 2.6.21, Linux supports high-resolution timers (HRTs), +optionally configurable via +.BR CONFIG_HIGH_RES_TIMERS . +On a system that supports HRTs, the accuracy of sleep and timer +system calls is no longer constrained by the jiffy, +but instead can be as accurate as the hardware allows +(microsecond accuracy is typical of modern hardware). +You can determine whether high-resolution timers are supported by +checking the resolution returned by a call to +.BR clock_getres (2) +or looking at the "resolution" entries in +.IR /proc/timer_list . +.PP +HRTs are not supported on all hardware architectures. +(Support is provided on x86, arm, and powerpc, among others.) +.SS The Epoch +UNIX systems represent time in seconds since the +.IR Epoch , +1970-01-01 00:00:00 +0000 (UTC). +.PP +A program can determine the +.I "calendar time" +using +.BR gettimeofday (2), +which returns time (in seconds and microseconds) that have +elapsed since the Epoch; +.BR time (2) +provides similar information, but only with accuracy to the +nearest second. +The system time can be changed using +.BR settimeofday (2). +.SS Broken-down time +Certain library functions use a structure of +type +.I tm +to represent +.IR "broken-down time" , +which stores time value separated out into distinct components +(year, month, day, hour, minute, second, etc.). +This structure is described in +.BR ctime (3), +which also describes functions that convert between calendar time and +broken-down time. +Functions for converting between broken-down time and printable +string representations of the time are described in +.BR ctime (3), +.BR strftime (3), +and +.BR strptime (3). +.SS Sleeping and setting timers +Various system calls and functions allow a program to sleep +(suspend execution) for a specified period of time; see +.BR nanosleep (2), +.BR clock_nanosleep (2), +and +.BR sleep (3). +.PP +Various system calls allow a process to set a timer that expires +at some point in the future, and optionally at repeated intervals; +see +.BR alarm (2), +.BR getitimer (2), +.BR timerfd_create (2), +and +.BR timer_create (2). +.SS Timer slack +Since Linux 2.6.28, it is possible to control the "timer slack" +value for a thread. +The timer slack is the length of time by +which the kernel may delay the wake-up of certain +system calls that block with a timeout. +Permitting this delay allows the kernel to coalesce wake-up events, +thus possibly reducing the number of system wake-ups and saving power. +For more details, see the description of +.B PR_SET_TIMERSLACK +in +.BR prctl (2). +.SH SEE ALSO +.ad l +.nh +.BR date (1), +.BR time (1), +.BR timeout (1), +.BR adjtimex (2), +.BR alarm (2), +.BR clock_gettime (2), +.BR clock_nanosleep (2), +.BR getitimer (2), +.BR getrlimit (2), +.BR getrusage (2), +.BR gettimeofday (2), +.BR nanosleep (2), +.BR stat (2), +.BR time (2), +.BR timer_create (2), +.BR timerfd_create (2), +.BR times (2), +.BR utime (2), +.BR adjtime (3), +.BR clock (3), +.BR clock_getcpuclockid (3), +.BR ctime (3), +.BR ntp_adjtime (3), +.BR ntp_gettime (3), +.BR pthread_getcpuclockid (3), +.BR sleep (3), +.BR strftime (3), +.BR strptime (3), +.BR timeradd (3), +.BR usleep (3), +.BR rtc (4), +.BR hwclock (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/tis-620.7 b/man7/tis-620.7 new file mode 100644 index 0000000..cbd4cfe --- /dev/null +++ b/man7/tis-620.7 @@ -0,0 +1 @@ +.so man7/iso_8859-11.7 diff --git a/man7/udp.7 b/man7/udp.7 new file mode 100644 index 0000000..a393447 --- /dev/null +++ b/man7/udp.7 @@ -0,0 +1,274 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ +.\" +.TH UDP 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +udp \- User Datagram Protocol for IPv4 +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.PP +.B udp_socket = socket(AF_INET, SOCK_DGRAM, 0); +.SH DESCRIPTION +This is an implementation of the User Datagram Protocol +described in RFC\ 768. +It implements a connectionless, unreliable datagram packet service. +Packets may be reordered or duplicated before they arrive. +UDP generates and checks checksums to catch transmission errors. +.PP +When a UDP socket is created, +its local and remote addresses are unspecified. +Datagrams can be sent immediately using +.BR sendto (2) +or +.BR sendmsg (2) +with a valid destination address as an argument. +When +.BR connect (2) +is called on the socket, the default destination address is set and +datagrams can now be sent using +.BR send (2) +or +.BR write (2) +without specifying a destination address. +It is still possible to send to other destinations by passing an +address to +.BR sendto (2) +or +.BR sendmsg (2). +In order to receive packets, the socket can be bound to a local +address first by using +.BR bind (2). +Otherwise, the socket layer will automatically assign +a free local port out of the range defined by +.I /proc/sys/net/ipv4/ip_local_port_range +and bind the socket to +.BR INADDR_ANY . +.PP +All receive operations return only one packet. +When the packet is smaller than the passed buffer, only that much +data is returned; when it is bigger, the packet is truncated and the +.B MSG_TRUNC +flag is set. +.B MSG_WAITALL +is not supported. +.PP +IP options may be sent or received using the socket options described in +.BR ip (7). +They are processed by the kernel only when the appropriate +.I /proc +parameter +is enabled (but still passed to the user even when it is turned off). +See +.BR ip (7). +.PP +When the +.B MSG_DONTROUTE +flag is set on sending, the destination address must refer to a local +interface address and the packet is sent only to that interface. +.PP +By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery. +This means the kernel +will keep track of the MTU to a specific target IP address and return +.B EMSGSIZE +when a UDP packet write exceeds it. +When this happens, the application should decrease the packet size. +Path MTU discovery can be also turned off using the +.B IP_MTU_DISCOVER +socket option or the +.I /proc/sys/net/ipv4/ip_no_pmtu_disc +file; see +.BR ip (7) +for details. +When turned off, UDP will fragment outgoing UDP packets +that exceed the interface MTU. +However, disabling it is not recommended +for performance and reliability reasons. +.SS Address format +UDP uses the IPv4 +.I sockaddr_in +address format described in +.BR ip (7). +.SS Error handling +All fatal errors will be passed to the user as an error return even +when the socket is not connected. +This includes asynchronous errors +received from the network. +You may get an error for an earlier packet +that was sent on the same socket. +This behavior differs from many other BSD socket implementations +which don't pass any errors unless the socket is connected. +Linux's behavior is mandated by +.BR RFC\ 1122 . +.PP +For compatibility with legacy code, in Linux 2.0 and 2.2 +it was possible to set the +.B SO_BSDCOMPAT +.B SOL_SOCKET +option to receive remote errors only when the socket has been +connected (except for +.B EPROTO +and +.BR EMSGSIZE ). +Locally generated errors are always passed. +Support for this socket option was removed in later kernels; see +.BR socket (7) +for further information. +.PP +When the +.B IP_RECVERR +option is enabled, all errors are stored in the socket error queue, +and can be received by +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +.SS /proc interfaces +System-wide UDP parameter settings can be accessed by files in the directory +.IR /proc/sys/net/ipv4/ . +.TP +.IR udp_mem " (since Linux 2.6.25)" +This is a vector of three integers governing the number +of pages allowed for queueing by all UDP sockets. +.RS +.TP 10 +.I min +Below this number of pages, UDP is not bothered about its +memory appetite. +When the amount of memory allocated by UDP exceeds +this number, UDP starts to moderate memory usage. +.TP +.I pressure +This value was introduced to follow the format of +.IR tcp_mem +(see +.BR tcp (7)). +.TP +.I max +Number of pages allowed for queueing by all UDP sockets. +.RE +.IP +Defaults values for these three items are +calculated at boot time from the amount of available memory. +.TP +.IR udp_rmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" +Minimal size, in bytes, of receive buffers used by UDP sockets in moderation. +Each UDP socket is able to use the size for receiving data, +even if total pages of UDP sockets exceed +.I udp_mem +pressure. +.TP +.IR udp_wmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" +Minimal size, in bytes, of send buffer used by UDP sockets in moderation. +Each UDP socket is able to use the size for sending data, +even if total pages of UDP sockets exceed +.I udp_mem +pressure. +.SS Socket options +To set or get a UDP socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR IPPROTO_UDP . +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.TP +.BR UDP_CORK " (since Linux 2.5.44)" +If this option is enabled, then all data output on this socket +is accumulated into a single datagram that is transmitted when +the option is disabled. +This option should not be used in code intended to be +portable. +.\" FIXME document UDP_ENCAP (new in kernel 2.5.67) +.\" From include/linux/udp.h: +.\" UDP_ENCAP_ESPINUDP_NON_IKE draft-ietf-ipsec-nat-t-ike-00/01 +.\" UDP_ENCAP_ESPINUDP draft-ietf-ipsec-udp-encaps-06 +.\" UDP_ENCAP_L2TPINUDP rfc2661 +.SS Ioctls +These ioctls can be accessed using +.BR ioctl (2). +The correct syntax is: +.PP +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" udp_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.TP +.BR FIONREAD " (" SIOCINQ ) +Gets a pointer to an integer as argument. +Returns the size of the next pending datagram in the integer in bytes, +or 0 when no datagram is pending. +.B Warning: +Using +.BR FIONREAD , +it is impossible to distinguish the case where no datagram is pending +from the case where the next pending datagram contains zero bytes of data. +It is safer to use +.BR select (2), +.BR poll (2), +or +.BR epoll (7) +to distinguish these cases. +.\" See http://www.securiteam.com/unixfocus/5KP0I15IKO.html +.\" "GNUnet DoS (UDP Socket Unreachable)", 14 May 2006 +.TP +.BR TIOCOUTQ " (" SIOCOUTQ ) +Returns the number of data bytes in the local send queue. +Supported only with Linux 2.4 and above. +.PP +In addition, all ioctls documented in +.BR ip (7) +and +.BR socket (7) +are supported. +.SH ERRORS +All errors documented for +.BR socket (7) +or +.BR ip (7) +may be returned by a send or receive on a UDP socket. +.TP +.B ECONNREFUSED +No receiver was associated with the destination address. +This might be caused by a previous packet sent over the socket. +.SH VERSIONS +.B IP_RECVERR +is a new feature in Linux 2.2. +.\" .SH CREDITS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR ip (7), +.BR raw (7), +.BR socket (7), +.BR udplite (7) +.PP +RFC\ 768 for the User Datagram Protocol. +.br +RFC\ 1122 for the host requirements. +.br +RFC\ 1191 for a description of path MTU discovery. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/udplite.7 b/man7/udplite.7 new file mode 100644 index 0000000..020dd84 --- /dev/null +++ b/man7/udplite.7 @@ -0,0 +1,165 @@ +.\" Copyright (c) 2008 by Gerrit Renker +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" $Id: udplite.7,v 1.12 2008/07/23 15:22:22 gerrit Exp gerrit $ +.\" +.TH UDPLITE 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +udplite \- Lightweight User Datagram Protocol +.SH SYNOPSIS +.B #include +.br +.\" FIXME . see #defines under `BUGS', +.\" when glibc supports this, add +.\" #include +.PP +.B sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE); +.SH DESCRIPTION +This is an implementation of the Lightweight User Datagram Protocol +(UDP-Lite), as described in RFC\ 3828. +.PP +UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length +checksums. +This has advantages for some types of multimedia transport that +may be able to make use of slightly damaged datagrams, +rather than having them discarded by lower-layer protocols. +.PP +The variable-length checksum coverage is set via a +.BR setsockopt (2) +option. +If this option is not set, the only difference from UDP is +in using a different IP protocol identifier (IANA number 136). +.PP +The UDP-Lite implementation is a full extension of +.BR udp (7)\(emthat +is, it shares the same API and API behavior, and in addition +offers two socket options to control the checksum coverage. +.SS Address format +UDP-Litev4 uses the +.I sockaddr_in +address format described in +.BR ip (7). +UDP-Litev6 uses the +.I sockaddr_in6 +address format described in +.BR ipv6 (7). +.SS Socket options +To set or get a UDP-Lite socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR IPPROTO_UDPLITE . +In addition, all +.B IPPROTO_UDP +socket options are valid on a UDP-Lite socket. +See +.BR udp (7) +for more information. +.PP +The following two options are specific to UDP-Lite. +.TP +.BR UDPLITE_SEND_CSCOV +This option sets the sender checksum coverage and takes an +.I int +as argument, with a checksum coverage value in the range 0..2^16-1. +.IP +A value of 0 means that the entire datagram is always covered. +Values from 1\-7 are illegal (RFC\ 3828, 3.1) and are rounded up to +the minimum coverage of 8. +.IP +With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum +coverage is limited to the first 2^16-1 octets, as per RFC\ 3828, 3.5. +Higher values are therefore silently truncated to 2^16-1. +If in doubt, the current coverage value can always be queried using +.BR getsockopt (2). +.TP +.BR UDPLITE_RECV_CSCOV +This is the receiver-side analogue and uses the same argument format +and value range as +.BR UDPLITE_SEND_CSCOV . +This option is not required to enable traffic with partial checksum +coverage. +Its function is that of a traffic filter: when enabled, it +instructs the kernel to drop all packets which have a coverage +.I less +than the specified coverage value. +.IP +When the value of +.B UDPLITE_RECV_CSCOV +exceeds the actual packet coverage, incoming packets are silently dropped, +but may generate a warning message in the system log. +.\" SO_NO_CHECK exists and is supported by UDPv4, but is +.\" commented out in socket(7), hence also commented out here +.\".PP +.\"Since UDP-Lite mandates checksums, checksumming can not be disabled +.\"via the +.\".B SO_NO_CHECK +.\"option from +.\".BR socket (7). +.SH ERRORS +All errors documented for +.BR udp (7) +may be returned. +UDP-Lite does not add further errors. +.SH FILES +.TP +.I /proc/net/snmp +Basic UDP-Litev4 statistics counters. +.TP +.I /proc/net/snmp6 +Basic UDP-Litev6 statistics counters. +.SH VERSIONS +UDP-Litev4/v6 first appeared in Linux 2.6.20. +.SH BUGS +.\" FIXME . remove this section once glibc supports UDP-Lite +Where glibc support is missing, the following definitions are needed: +.PP +.in +4n +.EX +#define IPPROTO_UDPLITE 136 +.\" The following two are defined in the kernel in linux/net/udplite.h +#define UDPLITE_SEND_CSCOV 10 +#define UDPLITE_RECV_CSCOV 11 +.EE +.in +.SH SEE ALSO +.BR ip (7), +.BR ipv6 (7), +.BR socket (7), +.BR udp (7) +.PP +RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite). +.PP +.I Documentation/networking/udplite.txt +in the Linux kernel source tree +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/unicode.7 b/man7/unicode.7 new file mode 100644 index 0000000..7ef4796 --- /dev/null +++ b/man7/unicode.7 @@ -0,0 +1,275 @@ +.\" Copyright (C) Markus Kuhn, 1995, 2001 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" 2001-05-11 Markus Kuhn +.\" Update +.\" +.TH UNICODE 7 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +unicode \- universal character set +.SH DESCRIPTION +The international standard ISO 10646 defines the +Universal Character Set (UCS). +UCS contains all characters of all other character set standards. +It also guarantees "round-trip compatibility"; +in other words, +conversion tables can be built such that no information is lost +when a string is converted from any other encoding to UCS and back. +.PP +UCS contains the characters required to represent practically all +known languages. +This includes not only the Latin, Greek, Cyrillic, +Hebrew, Arabic, Armenian, and Georgian scripts, but also Chinese, +Japanese and Korean Han ideographs as well as scripts such as +Hiragana, Katakana, Hangul, Devanagari, Bengali, Gurmukhi, Gujarati, +Oriya, Tamil, Telugu, Kannada, Malayalam, Thai, Lao, Khmer, Bopomofo, +Tibetan, Runic, Ethiopic, Canadian Syllabics, Cherokee, Mongolian, +Ogham, Myanmar, Sinhala, Thaana, Yi, and others. +For scripts not yet +covered, research on how to best encode them for computer usage is +still going on and they will be added eventually. +This might +eventually include not only Hieroglyphs and various historic +Indo-European languages, but even some selected artistic scripts such +as Tengwar, Cirth, and Klingon. +UCS also covers a large number of +graphical, typographical, mathematical, and scientific symbols, +including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, +Macintosh, OCR fonts, as well as many word processing and publishing +systems, and more are being added. +.PP +The UCS standard (ISO 10646) describes a +31-bit character set architecture +consisting of 128 24-bit +.IR groups , +each divided into 256 16-bit +.I planes +made up of 256 8-bit +.I rows +with 256 +.I column +positions, one for each character. +Part 1 of the standard (ISO 10646-1) +defines the first 65534 code positions (0x0000 to 0xfffd), which form +the +.IR "Basic Multilingual Plane" +(BMP), that is plane 0 in group 0. +Part 2 of the standard (ISO 10646-2) +adds characters to group 0 outside the BMP in several +.I "supplementary planes" +in the range 0x10000 to 0x10ffff. +There are no plans to add characters +beyond 0x10ffff to the standard, therefore of the entire code space, +only a small fraction of group 0 will ever be actually used in the +foreseeable future. +The BMP contains all characters found in the +commonly used other character sets. +The supplemental planes added by +ISO 10646-2 cover only more exotic characters for special scientific, +dictionary printing, publishing industry, higher-level protocol and +enthusiast needs. +.PP +The representation of each UCS character as a 2-byte word is referred +to as the UCS-2 form (only for BMP characters), +whereas UCS-4 is the representation of each character by a 4-byte word. +In addition, there exist two encoding forms UTF-8 +for backward compatibility with ASCII processing software and UTF-16 +for the backward-compatible handling of non-BMP characters up to +0x10ffff by UCS-2 software. +.PP +The UCS characters 0x0000 to 0x007f are identical to those of the +classic US-ASCII +character set and the characters in the range 0x0000 to 0x00ff +are identical to those in +ISO 8859-1 (Latin-1). +.SS Combining characters +Some code points in UCS +have been assigned to +.IR "combining characters" . +These are similar to the nonspacing accent keys on a typewriter. +A combining character just adds an accent to the previous character. +The most important accented characters have codes of their own in UCS, +however, the combining character mechanism allows us to add accents +and other diacritical marks to any character. +The combining characters +always follow the character which they modify. +For example, the German +character Umlaut-A ("Latin capital letter A with diaeresis") can +either be represented by the precomposed UCS code 0x00c4, or +alternatively as the combination of a normal "Latin capital letter A" +followed by a "combining diaeresis": 0x0041 0x0308. +.PP +Combining characters are essential for instance for encoding the Thai +script or for mathematical typesetting and users of the International +Phonetic Alphabet. +.SS Implementation levels +As not all systems are expected to support advanced mechanisms like +combining characters, ISO 10646-1 specifies the following three +.I implementation levels +of UCS: +.TP 0.9i +Level 1 +Combining characters and Hangul Jamo +(a variant encoding of the Korean script, where a Hangul syllable +glyph is coded as a triplet or pair of vowel/consonant codes) are not +supported. +.TP +Level 2 +In addition to level 1, combining characters are now allowed for some +languages where they are essential (e.g., Thai, Lao, Hebrew, +Arabic, Devanagari, Malayalam). +.TP +Level 3 +All UCS characters are supported. +.PP +The Unicode 3.0 Standard +published by the Unicode Consortium +contains exactly the UCS Basic Multilingual Plane +at implementation level 3, as described in ISO 10646-1:2000. +Unicode 3.1 added the supplemental planes of ISO 10646-2. +The Unicode standard and +technical reports published by the Unicode Consortium provide much +additional information on the semantics and recommended usages of +various characters. +They provide guidelines and algorithms for +editing, sorting, comparing, normalizing, converting, and displaying +Unicode strings. +.SS Unicode under Linux +Under GNU/Linux, the C type +.I wchar_t +is a signed 32-bit integer type. +Its values are always interpreted +by the C library as UCS +code values (in all locales), a convention that is signaled by the GNU +C library to applications by defining the constant +.B __STDC_ISO_10646__ +as specified in the ISO C99 standard. +.PP +UCS/Unicode can be used just like ASCII in input/output streams, +terminal communication, plaintext files, filenames, and environment +variables in the ASCII compatible UTF-8 multibyte encoding. +To signal the use of UTF-8 as the character +encoding to all applications, a suitable +.I locale +has to be selected via environment variables (e.g., +"LANG=en_GB.UTF-8"). +.PP +The +.B nl_langinfo(CODESET) +function returns the name of the selected encoding. +Library functions such as +.BR wctomb (3) +and +.BR mbsrtowcs (3) +can be used to transform the internal +.I wchar_t +characters and strings into the system character encoding and back +and +.BR wcwidth (3) +tells, how many positions (0\(en2) the cursor is advanced by the +output of a character. +.PP +.SS Private Use Areas (PUA) +In the Basic Multilingual Plane, +the range 0xe000 to 0xf8ff will never be assigned to any characters by +the standard and is reserved for private usage. +For the Linux +community, this private area has been subdivided further into the +range 0xe000 to 0xefff which can be used individually by any end-user +and the Linux zone in the range 0xf000 to 0xf8ff where extensions are +coordinated among all Linux users. +The registry of the characters +assigned to the Linux zone is maintained by LANANA and the registry +itself is +.I Documentation/admin\-guide/unicode.rst +in the Linux kernel sources +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/unicode.txt +before Linux 4.10). +.PP +Two other planes are reserved for private usage, plane 15 +(Supplementary Private Use Area-A, range 0xf0000 to 0xffffd) +and plane 16 (Supplementary Private Use Area-B, range +0x100000 to 0x10fffd). +.SS Literature +.IP * 3 +Information technology \(em Universal Multiple-Octet Coded Character +Set (UCS) \(em Part 1: Architecture and Basic Multilingual Plane. +International Standard ISO/IEC 10646-1, International Organization +for Standardization, Geneva, 2000. +.IP +This is the official specification of UCS . +Available from +.UR http://www.iso.ch/ +.UE . +.IP * +The Unicode Standard, Version 3.0. +The Unicode Consortium, Addison-Wesley, +Reading, MA, 2000, ISBN 0-201-61633-5. +.IP * +S. Harbison, G. Steele. C: A Reference Manual. Fourth edition, +Prentice Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3. +.IP +A good reference book about the C programming language. +The fourth +edition covers the 1994 Amendment 1 to the ISO C90 standard, which +adds a large number of new C library functions for handling wide and +multibyte character encodings, but it does not yet cover ISO C99, +which improved wide and multibyte character support even further. +.IP * +Unicode Technical Reports. +.RS +.UR http://www.unicode.org\:/reports/ +.UE +.RE +.IP * +Markus Kuhn: UTF-8 and Unicode FAQ for UNIX/Linux. +.RS +.UR http://www.cl.cam.ac.uk\:/~mgk25\:/unicode.html +.UE +.RE +.IP * +Bruno Haible: Unicode HOWTO. +.RS +.UR http://www.tldp.org\:/HOWTO\:/Unicode\-HOWTO.html +.UE +.RE +.\" .SH AUTHOR +.\" Markus Kuhn +.SH SEE ALSO +.BR locale (1), +.BR setlocale (3), +.BR charsets (7), +.BR utf-8 (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/units.7 b/man7/units.7 new file mode 100644 index 0000000..c20c4a2 --- /dev/null +++ b/man7/units.7 @@ -0,0 +1,138 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH UNITS 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +units \- decimal and binary prefixes +.SH DESCRIPTION +.SS Decimal prefixes +The SI system of units uses prefixes that indicate powers of ten. +A kilometer is 1000 meter, and a megawatt is 1000000 watt. +Below the standard prefixes. +.RS +.TS +l l l. +Prefix Name Value +y yocto 10^-24 = 0.000000000000000000000001 +z zepto 10^-21 = 0.000000000000000000001 +a atto 10^-18 = 0.000000000000000001 +f femto 10^-15 = 0.000000000000001 +p pico 10^-12 = 0.000000000001 +n nano 10^-9 = 0.000000001 +\(mc micro 10^-6 = 0.000001 +m milli 10^-3 = 0.001 +c centi 10^-2 = 0.01 +d deci 10^-1 = 0.1 +da deka 10^ 1 = 10 +h hecto 10^ 2 = 100 +k kilo 10^ 3 = 1000 +M mega 10^ 6 = 1000000 +G giga 10^ 9 = 1000000000 +T tera 10^12 = 1000000000000 +P peta 10^15 = 1000000000000000 +E exa 10^18 = 1000000000000000000 +Z zetta 10^21 = 1000000000000000000000 +Y yotta 10^24 = 1000000000000000000000000 +.TE +.RE +.PP +The symbol for micro is the Greek letter mu, often written u +in an ASCII context where this Greek letter is not available. +See also +.PP +.RS +.UR http://physics.nist.gov\:/cuu\:/Units\:/prefixes.html +.UE +.RE +.SS Binary prefixes +The binary prefixes resemble the decimal ones, +but have an additional \(aqi\(aq +(and "Ki" starts with a capital \(aqK\(aq). +The names are formed by taking the +first syllable of the names of the decimal prefix with roughly the same +size, followed by "bi" for "binary". +.RS +.TS +l l l. +Prefix Name Value +Ki kibi 2^10 = 1024 +Mi mebi 2^20 = 1048576 +Gi gibi 2^30 = 1073741824 +Ti tebi 2^40 = 1099511627776 +Pi pebi 2^50 = 1125899906842624 +Ei exbi 2^60 = 1152921504606846976 +.TE +.RE +.PP +See also +.PP +.UR http://physics.nist.gov\:/cuu\:/Units\:/binary.html +.UE +.SS Discussion +Before these binary prefixes were introduced, it was fairly +common to use k=1000 and K=1024, just like b=bit, B=byte. +Unfortunately, the M is capital already, and cannot be +capitalized to indicate binary-ness. +.PP +At first that didn't matter too much, since memory modules +and disks came in sizes that were powers of two, so everyone +knew that in such contexts "kilobyte" and "megabyte" meant +1024 and 1048576 bytes, respectively. +What originally was a +sloppy use of the prefixes "kilo" and "mega" started to become +regarded as the "real true meaning" when computers were involved. +But then disk technology changed, and disk sizes became arbitrary numbers. +After a period of uncertainty all disk manufacturers settled on the +standard, namely k=1000, M=1000\ k, G=1000\ M. +.PP +The situation was messy: in the 14k4 modems, k=1000; in the 1.44\ MB +.\" also common: 14.4k modem +diskettes, M=1024000; and so on. +In 1998 the IEC approved the standard +that defines the binary prefixes given above, enabling people +to be precise and unambiguous. +.PP +Thus, today, MB = 1000000\ B and MiB = 1048576\ B. +.PP +In the free software world programs are slowly +being changed to conform. +When the Linux kernel boots and says +.PP +.in +4n +.EX +hda: 120064896 sectors (61473 MB) w/2048KiB Cache +.EE +.in +.PP +the MB are megabytes and the KiB are kibibytes. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/unix.7 b/man7/unix.7 new file mode 100644 index 0000000..6cba62f --- /dev/null +++ b/man7/unix.7 @@ -0,0 +1,981 @@ +.\" This man page is Copyright (C) 1999 Andi Kleen , +.\" Copyright (C) 2008-2014, Michael Kerrisk , +.\" and Copyright (C) 2016, Heinrich Schuchardt +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" Modified, 2003-12-02, Michael Kerrisk, +.\" Modified, 2003-09-23, Adam Langley +.\" Modified, 2004-05-27, Michael Kerrisk, +.\" Added SOCK_SEQPACKET +.\" 2008-05-27, mtk, Provide a clear description of the three types of +.\" address that can appear in the sockaddr_un structure: pathname, +.\" unnamed, and abstract. +.\" +.TH UNIX 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +unix \- sockets for local interprocess communication +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.IB unix_socket " = socket(AF_UNIX, type, 0);" +.br +.IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" +.SH DESCRIPTION +The +.B AF_UNIX +(also known as +.BR AF_LOCAL ) +socket family is used to communicate between processes on the same machine +efficiently. +Traditionally, UNIX domain sockets can be either unnamed, +or bound to a filesystem pathname (marked as being of type socket). +Linux also supports an abstract namespace which is independent of the +filesystem. +.PP +Valid socket types in the UNIX domain are: +.BR SOCK_STREAM , +for a stream-oriented socket; +.BR SOCK_DGRAM , +for a datagram-oriented socket that preserves message boundaries +(as on most UNIX implementations, UNIX domain datagram +sockets are always reliable and don't reorder datagrams); +and (since Linux 2.6.4) +.BR SOCK_SEQPACKET , +for a sequenced-packet socket that is connection-oriented, +preserves message boundaries, +and delivers messages in the order that they were sent. +.PP +UNIX domain sockets support passing file descriptors or process credentials +to other processes using ancillary data. +.SS Address format +A UNIX domain socket address is represented in the following structure: +.PP +.in +4n +.EX +.\" #define UNIX_PATH_MAX 108 +.\" +struct sockaddr_un { + sa_family_t sun_family; /* AF_UNIX */ + char sun_path[108]; /* pathname */ +}; +.EE +.in +.PP +The +.I sun_family +field always contains +.BR AF_UNIX . +On Linux +.I sun_path +is 108 bytes in size; see also NOTES, below. +.PP +Various systems calls (for example, +.BR bind (2), +.BR connect (2), +and +.BR sendto (2)) +take a +.I sockaddr_un +argument as input. +Some other system calls (for example, +.BR getsockname (2), +.BR getpeername (2), +.BR recvfrom (2), +and +.BR accept (2)) +return an argument of this type. +.PP +Three types of address are distinguished in the +.I sockaddr_un +structure: +.IP * 3 +.IR pathname : +a UNIX domain socket can be bound to a null-terminated +filesystem pathname using +.BR bind (2). +When the address of a pathname socket is returned +(by one of the system calls noted above), +its length is +.IP + offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1 +.IP +and +.I sun_path +contains the null-terminated pathname. +(On Linux, the above +.BR offsetof () +expression equates to the same value as +.IR sizeof(sa_family_t) , +but some other implementations include other fields before +.IR sun_path , +so the +.BR offsetof () +expression more portably describes the size of the address structure.) +.IP +For further details of pathname sockets, see below. +.IP * +.IR unnamed : +A stream socket that has not been bound to a pathname using +.BR bind (2) +has no name. +Likewise, the two sockets created by +.BR socketpair (2) +are unnamed. +When the address of an unnamed socket is returned, +its length is +.IR "sizeof(sa_family_t)" , +and +.I sun_path +should not be inspected. +.\" There is quite some variation across implementations: FreeBSD +.\" says the length is 16 bytes, HP-UX 11 says it's zero bytes. +.IP * +.IR abstract : +an abstract socket address is distinguished (from a pathname socket) +by the fact that +.IR sun_path[0] +is a null byte (\(aq\\0\(aq). +The socket's address in this namespace is given by the additional +bytes in +.IR sun_path +that are covered by the specified length of the address structure. +(Null bytes in the name have no special significance.) +The name has no connection with filesystem pathnames. +When the address of an abstract socket is returned, +the returned +.I addrlen +is greater than +.IR "sizeof(sa_family_t)" +(i.e., greater than 2), and the name of the socket is contained in +the first +.IR "(addrlen \- sizeof(sa_family_t))" +bytes of +.IR sun_path . +.SS Pathname sockets +When binding a socket to a pathname, a few rules should be observed +for maximum portability and ease of coding: +.IP * 3 +The pathname in +.I sun_path +should be null-terminated. +.IP * +The length of the pathname, including the terminating null byte, +should not exceed the size of +.IR sun_path . +.IP * +The +.I addrlen +argument that describes the enclosing +.I sockaddr_un +structure should have a value of at least: +.IP +.nf + offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1 +.fi +.IP +or, more simply, +.I addrlen +can be specified as +.IR "sizeof(struct sockaddr_un)" . +.PP +There is some variation in how implementations handle UNIX domain +socket addresses that do not follow the above rules. +For example, some (but not all) implementations +.\" Linux does this, including for the case where the supplied path +.\" is 108 bytes +append a null terminator if none is present in the supplied +.IR sun_path . +.PP +When coding portable applications, +keep in mind that some implementations +.\" HP-UX +have +.I sun_path +as short as 92 bytes. +.\" Modern BSDs generally have 104, Tru64 and AIX have 104, +.\" Solaris and Irix have 108 +.PP +Various system calls +.RB ( accept (2), +.BR recvfrom (2), +.BR getsockname (2), +.BR getpeername (2)) +return socket address structures. +When applied to UNIX domain sockets, the value-result +.I addrlen +argument supplied to the call should be initialized as above. +Upon return, the argument is set to indicate the +.I actual +size of the address structure. +The caller should check the value returned in this argument: +if the output value exceeds the input value, +then there is no guarantee that a null terminator is present in +.IR sun_path . +(See BUGS.) +.\" +.SS Pathname socket ownership and permissions +In the Linux implementation, +pathname sockets honor the permissions of the directory they are in. +Creation of a new socket fails if the process does not have write and +search (execute) permission on the directory in which the socket is created. +.PP +On Linux, +connecting to a stream socket object requires write permission on that socket; +sending a datagram to a datagram socket likewise +requires write permission on that socket. +POSIX does not make any statement about the effect of the permissions +on a socket file, and on some systems (e.g., older BSDs), +the socket permissions are ignored. +Portable programs should not rely on +this feature for security. +.PP +When creating a new socket, the owner and group of the socket file +are set according to the usual rules. +The socket file has all permissions enabled, +other than those that are turned off by the process +.BR umask (2). +.PP +The owner, group, and permissions of a pathname socket can be changed (using +.BR chown (2) +and +.BR chmod (2)). +.\" However, fchown() and fchmod() do not seem to have an effect +.\" +.SS Abstract sockets +Socket permissions have no meaning for abstract sockets: +the process +.BR umask (2) +has no effect when binding an abstract socket, +and changing the ownership and permissions of the object (via +.BR fchown (2) +and +.BR fchmod (2)) +has no effect on the accessibility of the socket. +.PP +Abstract sockets automatically disappear when all open references +to the socket are closed. +.PP +The abstract socket namespace is a nonportable Linux extension. +.\" +.SS Socket options +For historical reasons, these socket options are specified with a +.B SOL_SOCKET +type even though they are +.B AF_UNIX +specific. +They can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2) +by specifying +.B SOL_SOCKET +as the socket family. +.TP +.B SO_PASSCRED +Enables the receiving of the credentials of the sending process in an +ancillary message. +When this option is set and the socket is not yet connected +a unique name in the abstract namespace will be generated automatically. +Expects an integer boolean flag. +.SS Autobind feature +If a +.BR bind (2) +call specifies +.I addrlen +as +.IR sizeof(sa_family_t) , +.\" i.e., sizeof(short) +or the +.BR SO_PASSCRED +socket option was specified for a socket that was +not explicitly bound to an address, +then the socket is autobound to an abstract address. +The address consists of a null byte +followed by 5 bytes in the character set +.IR [0\-9a\-f] . +Thus, there is a limit of 2^20 autobind addresses. +(From Linux 2.1.15, when the autobind feature was added, +8 bytes were used, and the limit was thus 2^32 autobind addresses. +The change to 5 bytes came in Linux 2.3.15.) +.SS Sockets API +The following paragraphs describe domain-specific details and +unsupported features of the sockets API for UNIX domain sockets on Linux. +.PP +UNIX domain sockets do not support the transmission of +out-of-band data (the +.B MSG_OOB +flag for +.BR send (2) +and +.BR recv (2)). +.PP +The +.BR send (2) +.B MSG_MORE +flag is not supported by UNIX domain sockets. +.PP +Before Linux 3.4, +.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f +the use of +.B MSG_TRUNC +in the +.I flags +argument of +.BR recv (2) +was not supported by UNIX domain sockets. +.PP +The +.B SO_SNDBUF +socket option does have an effect for UNIX domain sockets, but the +.B SO_RCVBUF +option does not. +For datagram sockets, the +.B SO_SNDBUF +value imposes an upper limit on the size of outgoing datagrams. +This limit is calculated as the doubled (see +.BR socket (7)) +option value less 32 bytes used for overhead. +.SS Ancillary messages +Ancillary data is sent and received using +.BR sendmsg (2) +and +.BR recvmsg (2). +For historical reasons the ancillary message types listed below +are specified with a +.B SOL_SOCKET +type even though they are +.B AF_UNIX +specific. +To send them set the +.I cmsg_level +field of the struct +.I cmsghdr +to +.B SOL_SOCKET +and the +.I cmsg_type +field to the type. +For more information see +.BR cmsg (3). +.TP +.B SCM_RIGHTS +Send or receive a set of open file descriptors from another process. +The data portion contains an integer array of the file descriptors. +The passed file descriptors behave as though they have been created with +.BR dup (2). +.TP +.B SCM_CREDENTIALS +Send or receive UNIX credentials. +This can be used for authentication. +The credentials are passed as a +.I struct ucred +ancillary message. +Thus structure is defined in +.I +as follows: +.IP +.in +4n +.EX +struct ucred { + pid_t pid; /* process ID of the sending process */ + uid_t uid; /* user ID of the sending process */ + gid_t gid; /* group ID of the sending process */ +}; +.EE +.in +.IP +Since glibc 2.8, the +.B _GNU_SOURCE +feature test macro must be defined (before including +.I any +header files) in order to obtain the definition +of this structure. +.IP +The credentials which the sender specifies are checked by the kernel. +A process with effective user ID 0 is allowed to specify values that do +not match its own. +The sender must specify its own process ID (unless it has the capability +.BR CAP_SYS_ADMIN ), +its real user ID, effective user ID, or saved set-user-ID (unless it has +.BR CAP_SETUID ), +and its real group ID, effective group ID, or saved set-group-ID +(unless it has +.BR CAP_SETGID ). +To receive a +.I struct ucred +message the +.B SO_PASSCRED +option must be enabled on the socket. +.SS Ioctls +The following +.BR ioctl (2) +calls return information in +.IR value . +The correct syntax is: +.PP +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.PP +.I ioctl_type +can be: +.TP +.B SIOCINQ +For +.B SOCK_STREAM +socket the function returns the amount of queued unread data in the receive buffer. +The socket must not be in LISTEN state, otherwise an error +.RB ( EINVAL ) +is returned. +.B SIOCINQ +is defined in +.IR . +.\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002, +.\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers +Alternatively, +you can use the synonymous +.BR FIONREAD , +defined in +.IR . +.\" SIOCOUTQ also has an effect for UNIX domain sockets, but not +.\" quite what userland might expect. It seems to return the number +.\" of bytes allocated for buffers containing pending output. +.\" That number is normally larger than the number of bytes of pending +.\" output. Since this info is, from userland's point of view, imprecise, +.\" and it may well change, probably best not to document this now. +For +.B SOCK_DGRAM +socket, +the returned value is the same as +for Internet domain datagram socket; +see +.BR udp (7). +.SH ERRORS +.TP +.B EADDRINUSE +The specified local address is already in use or the filesystem socket +object already exists. +.TP +.B ECONNREFUSED +The remote address specified by +.BR connect (2) +was not a listening socket. +This error can also occur if the target pathname is not a socket. +.TP +.B ECONNRESET +Remote socket was unexpectedly closed. +.TP +.B EFAULT +User memory address was not valid. +.TP +.B EINVAL +Invalid argument passed. +A common cause is that the value +.B AF_UNIX +was not specified in the +.I sun_type +field of passed addresses, or the socket was in an +invalid state for the applied operation. +.TP +.B EISCONN +.BR connect (2) +called on an already connected socket or a target address was +specified on a connected socket. +.TP +.B ENOENT +The pathname in the remote address specified to +.BR connect (2) +did not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOTCONN +Socket operation needs a target address, but the socket is not connected. +.TP +.B EOPNOTSUPP +Stream operation called on non-stream oriented socket or tried to +use the out-of-band data option. +.TP +.B EPERM +The sender passed invalid credentials in the +.IR "struct ucred" . +.TP +.B EPIPE +Remote socket was closed on a stream socket. +If enabled, a +.B SIGPIPE +is sent as well. +This can be avoided by passing the +.B MSG_NOSIGNAL +flag to +.BR send (2) +or +.BR sendmsg (2). +.TP +.B EPROTONOSUPPORT +Passed protocol is not +.BR AF_UNIX . +.TP +.B EPROTOTYPE +Remote socket does not match the local socket type +.RB ( SOCK_DGRAM +versus +.BR SOCK_STREAM ). +.TP +.B ESOCKTNOSUPPORT +Unknown socket type. +.TP +.B ETOOMANYREFS +This error can occur for +.BR sendmsg (2) +when sending a file descriptor as ancillary data over +a UNIX domain socket (see the description of +.BR SCM_RIGHTS , +above). +It occurs if the number of "in-flight" file descriptors exceeds the +.B RLIMIT_NOFILE +resource limit and the caller does not have the +.BR CAP_SYS_RESOURCE +capability. +An in-flight file descriptor is one that has been sent using +.BR sendmsg (2) +but has not yet been accepted in the recipient process using +.BR recvmsg (2). +.IP +This error is diagnosed since mainline Linux 4.5 +(and in some earlier kernel versions where the fix has been backported). +.\" commit 712f4aad406bb1ed67f3f98d04c044191f0ff593 +In earlier kernel versions, +it was possible to place an unlimited number of file descriptors in flight, +by sending each file descriptor with +.BR sendmsg (2) +and then closing the file descriptor so that it was not accounted against the +.B RLIMIT_NOFILE +resource limit. +.PP +Other errors can be generated by the generic socket layer or +by the filesystem while generating a filesystem socket object. +See the appropriate manual pages for more information. +.SH VERSIONS +.B SCM_CREDENTIALS +and the abstract namespace were introduced with Linux 2.2 and should not +be used in portable programs. +(Some BSD-derived systems also support credential passing, +but the implementation details differ.) +.SH NOTES +Binding to a socket with a filename creates a socket +in the filesystem that must be deleted by the caller when it is no +longer needed (using +.BR unlink (2)). +The usual UNIX close-behind semantics apply; the socket can be unlinked +at any time and will be finally removed from the filesystem when the last +reference to it is closed. +.PP +To pass file descriptors or credentials over a +.BR SOCK_STREAM , +you need +to send or receive at least one byte of nonancillary data in the same +.BR sendmsg (2) +or +.BR recvmsg (2) +call. +.PP +UNIX domain stream sockets do not support the notion of out-of-band data. +.\" +.SH BUGS +When binding a socket to an address, +Linux is one of the implementations that appends a null terminator +if none is supplied in +.IR sun_path . +In most cases this is unproblematic: +when the socket address is retrieved, +it will be one byte longer than that supplied when the socket was bound. +However, there is one case where confusing behavior can result: +if 108 non-null bytes are supplied when a socket is bound, +then the addition of the null terminator takes the length of +the pathname beyond +.IR sizeof(sun_path) . +Consequently, when retrieving the socket address +(for example, via +.BR accept (2)), +.\" The behavior on Solaris is quite similar. +if the input +.I addrlen +argument for the retrieving call is specified as +.IR "sizeof(struct sockaddr_un)" , +then the returned address structure +.I won't +have a null terminator in +.IR sun_path . +.PP +In addition, some implementations +.\" i.e., traditional BSD +don't require a null terminator when binding a socket (the +.I addrlen +argument is used to determine the length of +.IR sun_path ) +and when the socket address is retrieved on these implementations, +there is no null terminator in +.IR sun_path . +.PP +Applications that retrieve socket addresses can (portably) code +to handle the possibility that there is no null terminator in +.IR sun_path +by respecting the fact that the number of valid bytes in the pathname is: +.PP + strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) +.\" The following patch to amend kernel behavior was rejected: +.\" http://thread.gmane.org/gmane.linux.kernel.api/2437 +.\" Subject: [patch] Fix handling of overlength pathname in AF_UNIX sun_path +.\" 2012-04-17 +.\" And there was a related discussion in the Austin list: +.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/5735 +.\" Subject: Having a sun_path with no null terminator +.\" 2012-04-18 +.\" +.\" FIXME . Track http://austingroupbugs.net/view.php?id=561 +.PP +Alternatively, an application can retrieve +the socket address by allocating a buffer of size +.I "sizeof(struct sockaddr_un)+1" +that is zeroed out before the retrieval. +The retrieving call can specify +.I addrlen +as +.IR "sizeof(struct sockaddr_un)" , +and the extra zero byte ensures that there will be +a null terminator for the string returned in +.IR sun_path : +.PP +.in +4n +.EX +void *addrp; + +addrlen = sizeof(struct sockaddr_un); +addrp = malloc(addrlen + 1); +if (addrp == NULL) + /* Handle error */ ; +memset(addrp, 0, addrlen + 1); + +if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) + /* handle error */ ; + +printf("sun_path = %s\\n", ((struct sockaddr_un *) addrp)\->sun_path); +.EE +.in +.PP +This sort of messiness can be avoided if it is guaranteed +that the applications that +.I create +pathname sockets follow the rules outlined above under +.IR "Pathname sockets" . +.SH EXAMPLE +The following code demonstrates the use of sequenced-packet +sockets for local interprocess communication. +It consists of two programs. +The server program waits for a connection from the client program. +The client sends each of its command-line arguments in separate messages. +The server treats the incoming messages as integers and adds them up. +The client sends the command string "END". +The server sends back a message containing the sum of the client's integers. +The client prints the sum and exits. +The server waits for the next client to connect. +To stop the server, the client is called with the command-line argument "DOWN". +.PP +The following output was recorded while running the server in the background +and repeatedly executing the client. +Execution of the server program ends when it receives the "DOWN" command. +.SS Example output +.in +4n +.EX +$ \fB./server &\fP +[1] 25887 +$ \fB./client 3 4\fP +Result = 7 +$ \fB./client 11 \-5\fP +Result = 6 +$ \fB./client DOWN\fP +Result = 0 +[1]+ Done ./server +$ +.EE +.in +.SS Program source +\& +.EX +/* + * File connection.h + */ + +#define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket" +#define BUFFER_SIZE 12 + +/* + * File server.c + */ + +#include +#include +#include +#include +#include +#include +#include "connection.h" + +int +main(int argc, char *argv[]) +{ + struct sockaddr_un name; + int down_flag = 0; + int ret; + int connection_socket; + int data_socket; + int result; + char buffer[BUFFER_SIZE]; + + /* + * In case the program exited inadvertently on the last run, + * remove the socket. + */ + + unlink(SOCKET_NAME); + + /* Create local socket. */ + + connection_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0); + if (connection_socket == \-1) { + perror("socket"); + exit(EXIT_FAILURE); + } + + /* + * For portability clear the whole structure, since some + * implementations have additional (nonstandard) fields in + * the structure. + */ + + memset(&name, 0, sizeof(struct sockaddr_un)); + + /* Bind socket to socket name. */ + + name.sun_family = AF_UNIX; + strncpy(name.sun_path, SOCKET_NAME, sizeof(name.sun_path) \- 1); + + ret = bind(connection_socket, (const struct sockaddr *) &name, + sizeof(struct sockaddr_un)); + if (ret == \-1) { + perror("bind"); + exit(EXIT_FAILURE); + } + + /* + * Prepare for accepting connections. The backlog size is set + * to 20. So while one request is being processed other requests + * can be waiting. + */ + + ret = listen(connection_socket, 20); + if (ret == \-1) { + perror("listen"); + exit(EXIT_FAILURE); + } + + /* This is the main loop for handling connections. */ + + for (;;) { + + /* Wait for incoming connection. */ + + data_socket = accept(connection_socket, NULL, NULL); + if (data_socket == \-1) { + perror("accept"); + exit(EXIT_FAILURE); + } + + result = 0; + for(;;) { + + /* Wait for next data packet. */ + + ret = read(data_socket, buffer, BUFFER_SIZE); + if (ret == \-1) { + perror("read"); + exit(EXIT_FAILURE); + } + + /* Ensure buffer is 0\-terminated. */ + + buffer[BUFFER_SIZE \- 1] = 0; + + /* Handle commands. */ + + if (!strncmp(buffer, "DOWN", BUFFER_SIZE)) { + down_flag = 1; + break; + } + + if (!strncmp(buffer, "END", BUFFER_SIZE)) { + break; + } + + /* Add received summand. */ + + result += atoi(buffer); + } + + /* Send result. */ + + sprintf(buffer, "%d", result); + ret = write(data_socket, buffer, BUFFER_SIZE); + + if (ret == \-1) { + perror("write"); + exit(EXIT_FAILURE); + } + + /* Close socket. */ + + close(data_socket); + + /* Quit on DOWN command. */ + + if (down_flag) { + break; + } + } + + close(connection_socket); + + /* Unlink the socket. */ + + unlink(SOCKET_NAME); + + exit(EXIT_SUCCESS); +} + +/* + * File client.c + */ + +#include +#include +#include +#include +#include +#include +#include +#include "connection.h" + +int +main(int argc, char *argv[]) +{ + struct sockaddr_un addr; + int i; + int ret; + int data_socket; + char buffer[BUFFER_SIZE]; + + /* Create local socket. */ + + data_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0); + if (data_socket == \-1) { + perror("socket"); + exit(EXIT_FAILURE); + } + + /* + * For portability clear the whole structure, since some + * implementations have additional (nonstandard) fields in + * the structure. + */ + + memset(&addr, 0, sizeof(struct sockaddr_un)); + + /* Connect socket to socket address */ + + addr.sun_family = AF_UNIX; + strncpy(addr.sun_path, SOCKET_NAME, sizeof(addr.sun_path) \- 1); + + ret = connect (data_socket, (const struct sockaddr *) &addr, + sizeof(struct sockaddr_un)); + if (ret == \-1) { + fprintf(stderr, "The server is down.\\n"); + exit(EXIT_FAILURE); + } + + /* Send arguments. */ + + for (i = 1; i < argc; ++i) { + ret = write(data_socket, argv[i], strlen(argv[i]) + 1); + if (ret == \-1) { + perror("write"); + break; + } + } + + /* Request result. */ + + strcpy (buffer, "END"); + ret = write(data_socket, buffer, strlen(buffer) + 1); + if (ret == \-1) { + perror("write"); + exit(EXIT_FAILURE); + } + + /* Receive result. */ + + ret = read(data_socket, buffer, BUFFER_SIZE); + if (ret == \-1) { + perror("read"); + exit(EXIT_FAILURE); + } + + /* Ensure buffer is 0\-terminated. */ + + buffer[BUFFER_SIZE \- 1] = 0; + + printf("Result = %s\\n", buffer); + + /* Close socket. */ + + close(data_socket); + + exit(EXIT_SUCCESS); +} +.EE +.PP +For an example of the use of +.BR SCM_RIGHTS +see +.BR cmsg (3). +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR socket (2), +.BR socketpair (2), +.BR cmsg (3), +.BR capabilities (7), +.BR credentials (7), +.BR socket (7), +.BR udp (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/uri.7 b/man7/uri.7 new file mode 100644 index 0000000..e77c990 --- /dev/null +++ b/man7/uri.7 @@ -0,0 +1,723 @@ +.\" (C) Copyright 1999-2000 David A. Wheeler (dwheeler@dwheeler.com) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Fragments of this document are directly derived from IETF standards. +.\" For those fragments which are directly derived from such standards, +.\" the following notice applies, which is the standard copyright and +.\" rights announcement of The Internet Society: +.\" +.\" Copyright (C) The Internet Society (1998). All Rights Reserved. +.\" This document and translations of it may be copied and furnished to +.\" others, and derivative works that comment on or otherwise explain it +.\" or assist in its implementation may be prepared, copied, published +.\" and distributed, in whole or in part, without restriction of any +.\" kind, provided that the above copyright notice and this paragraph are +.\" included on all such copies and derivative works. However, this +.\" document itself may not be modified in any way, such as by removing +.\" the copyright notice or references to the Internet Society or other +.\" Internet organizations, except as needed for the purpose of +.\" developing Internet standards in which case the procedures for +.\" copyrights defined in the Internet Standards process must be +.\" followed, or as required to translate it into languages other than English. +.\" +.\" Modified Fri Jul 25 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) +.\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) +.\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com) +.\" +.TH URI 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +uri, url, urn \- uniform resource identifier (URI), including a URL or URN +.SH SYNOPSIS +.nf +.HP 0.2i +URI = [ absoluteURI | relativeURI ] [ "#" fragment ] +.HP +absoluteURI = scheme ":" ( hierarchical_part | opaque_part ) +.HP +relativeURI = ( net_path | absolute_path | relative_path ) [ "?" query ] +.HP +scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" | + "file" | "man" | "info" | "whatis" | "ldap" | "wais" | \&... +.HP +hierarchical_part = ( net_path | absolute_path ) [ "?" query ] +.HP +net_path = "//" authority [ absolute_path ] +.HP +absolute_path = "/" path_segments +.HP +relative_path = relative_segment [ absolute_path ] +.fi +.SH DESCRIPTION +.PP +A Uniform Resource Identifier (URI) is a short string of characters +identifying an abstract or physical resource (for example, a web page). +A Uniform Resource Locator (URL) is a URI +that identifies a resource through its primary access +mechanism (e.g., its network "location"), rather than +by name or some other attribute of that resource. +A Uniform Resource Name (URN) is a URI +that must remain globally unique and persistent even when +the resource ceases to exist or becomes unavailable. +.PP +URIs are the standard way to name hypertext link destinations +for tools such as web browsers. +The string "http://www.kernel.org" is a URL (and thus it +is also a URI). +Many people use the term URL loosely as a synonym for URI +(though technically URLs are a subset of URIs). +.PP +URIs can be absolute or relative. +An absolute identifier refers to a resource independent of +context, while a relative +identifier refers to a resource by describing the difference +from the current context. +Within a relative path reference, the complete path segments "." and +".." have special meanings: "the current hierarchy level" and "the +level above this hierarchy level", respectively, just like they do in +UNIX-like systems. +A path segment which contains a colon +character can't be used as the first segment of a relative URI path +(e.g., "this:that"), because it would be mistaken for a scheme name; +precede such segments with ./ (e.g., "./this:that"). +Note that descendants of MS-DOS (e.g., Microsoft Windows) replace +devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|". +.PP +A fragment identifier, if included, refers to a particular named portion +(fragment) of a resource; text after a \(aq#\(aq identifies the fragment. +A URI beginning with \(aq#\(aq refers to that fragment in the current resource. +.SS Usage +There are many different URI schemes, each with specific +additional rules and meanings, but they are intentionally made to be +as similar as possible. +For example, many URL schemes +permit the authority to be the following format, called here an +.I ip_server +(square brackets show what's optional): +.HP +.IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ] +.PP +This format allows you to optionally insert a username, +a user plus password, and/or a port number. +The +.I host +is the name of the host computer, either its name as determined by DNS +or an IP address (numbers separated by periods). +Thus the URI + +logs into a web server on host example.com +as fred (using fredpassword) using port 8080. +Avoid including a password in a URI if possible because of the many +security risks of having a password written down. +If the URL supplies a username but no password, and the remote +server requests a password, the program interpreting the URL +should request one from the user. +.PP +Here are some of the most common schemes in use on UNIX-like systems +that are understood by many tools. +Note that many tools using URIs also have internal schemes or specialized +schemes; see those tools' documentation for information on those schemes. +.PP +.B "http \- Web (HTTP) server" +.PP +.RI http:// ip_server / path +.br +.RI http:// ip_server / path ? query +.PP +This is a URL accessing a web (HTTP) server. +The default port is 80. +If the path refers to a directory, the web server will choose what +to return; usually if there is a file named "index.html" or "index.htm" +its content is returned, otherwise, a list of the files in the current +directory (with appropriate links) is generated and returned. +An example is . +.PP +A query can be given in the archaic "isindex" format, consisting of a +word or phrase and not including an equal sign (=). +A query can also be in the longer "GET" format, which has one or more +query entries of the form +.IR key = value +separated by the ampersand character (&). +Note that +.I key +can be repeated more than once, though it's up to the web server +and its application programs to determine if there's any meaning to that. +There is an unfortunate interaction with HTML/XML/SGML and +the GET query format; when such URIs with more than one key +are embedded in SGML/XML documents (including HTML), the ampersand +(&) has to be rewritten as &. +Note that not all queries use this format; larger forms +may be too long to store as a URI, so they use a different +interaction mechanism (called POST) which does +not include the data in the URI. +See the Common Gateway Interface specification at +.UR http://www.w3.org\:/CGI +.UE +for more information. +.PP +.B "ftp \- File Transfer Protocol (FTP)" +.PP +.RI ftp:// ip_server / path +.PP +This is a URL accessing a file through the file transfer protocol (FTP). +The default port (for control) is 21. +If no username is included, the username "anonymous" is supplied, and +in that case many clients provide as the password the requestor's +Internet email address. +An example is +. +.PP +.B "gopher \- Gopher server" +.PP +.RI gopher:// ip_server / "gophertype selector" +.br +.RI gopher:// ip_server / "gophertype selector" %09 search +.br +.RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string +.br +.PP +The default gopher port is 70. +.I gophertype +is a single-character field to denote the +Gopher type of the resource to +which the URL refers. +The entire path may also be empty, in +which case the delimiting "/" is also optional and the gophertype +defaults to "1". +.PP +.I selector +is the Gopher selector string. +In the Gopher protocol, +Gopher selector strings are a sequence of octets which may contain +any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal +(US-ASCII character LF), and 0D (US-ASCII character CR). +.PP +.B "mailto \- Email address" +.PP +.RI mailto: email-address +.PP +This is an email address, usually of the form +.IR name @ hostname . +See +.BR mailaddr (7) +for more information on the correct format of an email address. +Note that any % character must be rewritten as %25. +An example is . +.PP +.B "news \- Newsgroup or News message" +.PP +.RI news: newsgroup-name +.br +.RI news: message-id +.PP +A +.I newsgroup-name +is a period-delimited hierarchical name, such as +"comp.infosystems.www.misc". +If is "*" (as in ), it is used to refer +to "all available news groups". +An example is . +.PP +A +.I message-id +corresponds to the Message-ID of +.UR http://www.ietf.org\:/rfc\:/rfc1036.txt +IETF RFC\ 1036, +.UE +without the enclosing "<" +and ">"; it takes the form +.IR unique @ full_domain_name . +A message identifier may be distinguished from a news group name by the +presence of the "@" character. +.PP +.B "telnet \- Telnet login" +.PP +.RI telnet:// ip_server / +.PP +The Telnet URL scheme is used to designate interactive text services that +may be accessed by the Telnet protocol. +The final "/" character may be omitted. +The default port is 23. +An example is . +.PP +.B "file \- Normal file" +.PP +.RI file:// ip_server / path_segments +.br +.RI file: path_segments +.PP +This represents a file or directory accessible locally. +As a special case, +.I ip_server +can be the string "localhost" or the empty +string; this is interpreted as "the machine from which the URL is +being interpreted". +If the path is to a directory, the viewer should display the +directory's contents with links to each containee; +not all viewers currently do this. +KDE supports generated files through the URL . +If the given file isn't found, browser writers may want to try to expand +the filename via filename globbing +(see +.BR glob (7) +and +.BR glob (3)). +.PP +The second format (e.g., ) +is a correct format for referring to +a local file. +However, older standards did not permit this format, +and some programs don't recognize this as a URI. +A more portable syntax is to use an empty string as the server name, +for example, +; this form does the same thing +and is easily recognized by pattern matchers and older programs as a URI. +Note that if you really mean to say "start from the current location," don't +specify the scheme at all; use a relative address like <../test.txt>, +which has the side-effect of being scheme-independent. +An example of this scheme is . +.PP +.B "man \- Man page documentation" +.PP +.RI man: command-name +.br +.RI man: command-name ( section ) +.PP +This refers to local online manual (man) reference pages. +The command name can optionally be followed by a +parenthesis and section number; see +.BR man (7) +for more information on the meaning of the section numbers. +This URI scheme is unique to UNIX-like systems (such as Linux) +and is not currently registered by the IETF. +An example is . +.PP +.B "info \- Info page documentation" +.PP +.RI info: virtual-filename +.br +.RI info: virtual-filename # nodename +.br +.RI info:( virtual-filename ) +.br +.RI info:( virtual-filename ) nodename +.PP +This scheme refers to online info reference pages (generated from +texinfo files), +a documentation format used by programs such as the GNU tools. +This URI scheme is unique to UNIX-like systems (such as Linux) +and is not currently registered by the IETF. +As of this writing, GNOME and KDE differ in their URI syntax +and do not accept the other's syntax. +The first two formats are the GNOME format; in nodenames all spaces +are written as underscores. +The second two formats are the KDE format; +spaces in nodenames must be written as spaces, even though this +is forbidden by the URI standards. +It's hoped that in the future most tools will understand all of these +formats and will always accept underscores for spaces in nodenames. +In both GNOME and KDE, if the form without the nodename is used the +nodename is assumed to be "Top". +Examples of the GNOME format are and . +Examples of the KDE format are and . +.PP +.B "whatis \- Documentation search" +.PP +.RI whatis: string +.PP +This scheme searches the database of short (one-line) descriptions of +commands and returns a list of descriptions containing that string. +Only complete word matches are returned. +See +.BR whatis (1). +This URI scheme is unique to UNIX-like systems (such as Linux) +and is not currently registered by the IETF. +.PP +.B "ghelp \- GNOME help documentation" +.PP +.RI ghelp: name-of-application +.PP +This loads GNOME help for the given application. +Note that not much documentation currently exists in this format. +.PP +.B "ldap \- Lightweight Directory Access Protocol" +.PP +.RI ldap:// hostport +.br +.RI ldap:// hostport / +.br +.RI ldap:// hostport / dn +.br +.RI ldap:// hostport / dn ? attributes +.br +.RI ldap:// hostport / dn ? attributes ? scope +.br +.RI ldap:// hostport / dn ? attributes ? scope ? filter +.br +.RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions +.PP +This scheme supports queries to the +Lightweight Directory Access Protocol (LDAP), a protocol for querying +a set of servers for hierarchically organized information +(such as people and computing resources). +See +.UR http://www.ietf.org\:/rfc\:/rfc2255.txt +RFC\ 2255 +.UE +for more information on the LDAP URL scheme. +The components of this URL are: +.IP hostport 12 +the LDAP server to query, written as a hostname optionally followed by +a colon and the port number. +The default LDAP port is TCP port 389. +If empty, the client determines which the LDAP server to use. +.IP dn +the LDAP Distinguished Name, which identifies +the base object of the LDAP search (see +.UR http://www.ietf.org\:/rfc\:/rfc2253.txt +RFC\ 2253 +.UE +section 3). +.IP attributes +a comma-separated list of attributes to be returned; +see RFC\ 2251 section 4.1.5. +If omitted, all attributes should be returned. +.IP scope +specifies the scope of the search, which can be one of +"base" (for a base object search), "one" (for a one-level search), +or "sub" (for a subtree search). +If scope is omitted, "base" is assumed. +.IP filter +specifies the search filter (subset of entries +to return). +If omitted, all entries should be returned. +See +.UR http://www.ietf.org\:/rfc\:/rfc2254.txt +RFC\ 2254 +.UE +section 4. +.IP extensions +a comma-separated list of type=value +pairs, where the =value portion may be omitted for options not +requiring it. +An extension prefixed with a \(aq!\(aq is critical +(must be supported to be valid), otherwise it is noncritical (optional). +.PP +LDAP queries are easiest to explain by example. +Here's a query that asks ldap.itd.umich.edu for information about +the University of Michigan in the U.S.: +.PP +.nf +ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US +.fi +.PP +To just get its postal address attribute, request: +.PP +.nf +ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress +.fi +.PP +To ask a host.com at port 6666 for information about the person +with common name (cn) "Babs Jensen" at University of Michigan, request: +.PP +.nf +ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen) +.fi +.PP +.B "wais \- Wide Area Information Servers" +.PP +.RI wais:// hostport / database +.br +.RI wais:// hostport / database ? search +.br +.RI wais:// hostport / database / wtype / wpath +.PP +This scheme designates a WAIS database, search, or document +(see +.UR http://www.ietf.org\:/rfc\:/rfc1625.txt +IETF RFC\ 1625 +.UE +for more information on WAIS). +Hostport is the hostname, optionally followed by a colon and port number +(the default port number is 210). +.PP +The first form designates a WAIS database for searching. +The second form designates a particular search of the WAIS database +.IR database . +The third form designates a particular document within a WAIS +database to be retrieved. +.I wtype +is the WAIS designation of the type of the object and +.I wpath +is the WAIS document-id. +.PP +.B "other schemes" +.PP +There are many other URI schemes. +Most tools that accept URIs support a set of internal URIs +(e.g., Mozilla has the about: scheme for internal information, +and the GNOME help browser has the toc: scheme for various starting +locations). +There are many schemes that have been defined but are not as widely +used at the current time +(e.g., prospero). +The nntp: scheme is deprecated in favor of the news: scheme. +URNs are to be supported by the urn: scheme, with a hierarchical name space +(e.g., urn:ietf:... would identify IETF documents); at this time +URNs are not widely implemented. +Not all tools support all schemes. +.SS Character encoding +.PP +URIs use a limited number of characters so that they can be +typed in and used in a variety of situations. +.PP +The following characters are reserved, that is, they may appear in a +URI but their use is limited to their reserved purpose +(conflicting data must be escaped before forming the URI): +.IP + ; / ? : @ & = + $ , +.PP +Unreserved characters may be included in a URI. +Unreserved characters +include uppercase and lowercase English letters, +decimal digits, and the following +limited set of punctuation marks and symbols: +.IP + \- _ . ! ~ * ' ( ) +.PP +All other characters must be escaped. +An escaped octet is encoded as a character triplet, consisting of the +percent character "%" followed by the two hexadecimal digits +representing the octet code (you can use uppercase or lowercase letters +for the hexadecimal digits). +For example, a blank space must be escaped +as "%20", a tab character as "%09", and the "&" as "%26". +Because the percent "%" character always has the reserved purpose of +being the escape indicator, it must be escaped as "%25". +It is common practice to escape space characters as the plus symbol (+) +in query text; this practice isn't uniformly defined +in the relevant RFCs (which recommend %20 instead) but any tool accepting +URIs with query text should be prepared for them. +A URI is always shown in its "escaped" form. +.PP +Unreserved characters can be escaped without changing the semantics +of the URI, but this should not be done unless the URI is being used +in a context that does not allow the unescaped character to appear. +For example, "%7e" is sometimes used instead of "~" in an HTTP URL +path, but the two are equivalent for an HTTP URL. +.PP +For URIs which must handle characters outside the US ASCII character set, +the HTML 4.01 specification (section B.2) and +IETF RFC\ 2718 (section 2.2.5) recommend the following approach: +.IP 1. 4 +translate the character sequences into UTF-8 (IETF RFC\ 2279)\(emsee +.BR utf-8 (7)\(emand +then +.IP 2. +use the URI escaping mechanism, that is, +use the %HH encoding for unsafe octets. +.SS Writing a URI +When written, URIs should be placed inside double quotes +(e.g., "http://www.kernel.org"), +enclosed in angle brackets (e.g., ), +or placed on a line by themselves. +A warning for those who use double-quotes: +.B never +move extraneous punctuation (such as the period ending a sentence or the +comma in a list) +inside a URI, since this will change the value of the URI. +Instead, use angle brackets instead, or +switch to a quoting system that never includes extraneous characters +inside quotation marks. +This latter system, called the 'new' or 'logical' quoting system by +"Hart's Rules" and the "Oxford Dictionary for Writers and Editors", +is preferred practice in Great Britain and hackers worldwide +(see the +Jargon File's section on Hacker Writing Style, +.UR http://www.fwi.uva.nl\:/~mes\:/jargon\:/h\:/HackerWritingStyle.html +.UE , +for more information). +Older documents suggested inserting the prefix "URL:" +just before the URI, but this form has never caught on. +.PP +The URI syntax was designed to be unambiguous. +However, as URIs have become commonplace, traditional media +(television, radio, newspapers, billboards, etc.) have increasingly +used abbreviated URI references consisting of +only the authority and path portions of the identified resource +(e.g., ). +Such references are primarily +intended for human interpretation rather than machine, with the +assumption that context-based heuristics are sufficient to complete +the URI (e.g., hostnames beginning with "www" are likely to have +a URI prefix of "http://" and hostnames beginning with "ftp" likely +to have a prefix of "ftp://"). +Many client implementations heuristically resolve these references. +Such heuristics may +change over time, particularly when new schemes are introduced. +Since an abbreviated URI has the same syntax as a relative URL path, +abbreviated URI references cannot be used where relative URIs are +permitted, and can be used only when there is no defined base +(such as in dialog boxes). +Don't use abbreviated URIs as hypertext links inside a document; +use the standard format as described here. +.SH CONFORMING TO +.PP +.UR http://www.ietf.org\:/rfc\:/rfc2396.txt +(IETF RFC\ 2396) +.UE , +.UR http://www.w3.org\:/TR\:/REC\-html40 +(HTML 4.0) +.UE . +.SH NOTES +Any tool accepting URIs (e.g., a web browser) on a Linux system should +be able to handle (directly or indirectly) all of the +schemes described here, including the man: and info: schemes. +Handling them by invoking some other program is +fine and in fact encouraged. +.PP +Technically the fragment isn't part of the URI. +.PP +For information on how to embed URIs (including URLs) in a data format, +see documentation on that format. +HTML uses the format +.I text +. +Texinfo files use the format @uref{\fIuri\fP}. +Man and mdoc have the recently added UR macro, or just include the +URI in the text (viewers should be able to detect :// as part of a URI). +.PP +The GNOME and KDE desktop environments currently vary in the URIs +they accept, in particular in their respective help browsers. +To list man pages, GNOME uses while KDE uses , and +to list info pages, GNOME uses while KDE uses +(the author of this man page prefers the KDE approach here, though a more +regular format would be even better). +In general, KDE uses as a prefix to a set of generated +files. +KDE prefers documentation in HTML, accessed via the +. +GNOME prefers the ghelp scheme to store and find documentation. +Neither browser handles file: references to directories at the time +of this writing, making it difficult to refer to an entire directory with +a browsable URI. +As noted above, these environments differ in how they handle the +info: scheme, probably the most important variation. +It is expected that GNOME and KDE +will converge to common URI formats, and a future +version of this man page will describe the converged result. +Efforts to aid this convergence are encouraged. +.SS Security +.PP +A URI does not in itself pose a security threat. +There is no general guarantee that a URL, which at one time +located a given resource, will continue to do so. +Nor is there any +guarantee that a URL will not locate a different resource at some +later point in time; such a guarantee can be +obtained only from the person(s) controlling that namespace and the +resource in question. +.PP +It is sometimes possible to construct a URL such that an attempt to +perform a seemingly harmless operation, such as the +retrieval of an entity associated with the resource, will in fact +cause a possibly damaging remote operation to occur. +The unsafe URL +is typically constructed by specifying a port number other than that +reserved for the network protocol in question. +The client unwittingly contacts a site that is in fact +running a different protocol. +The content of the URL contains instructions that, when +interpreted according to this other protocol, cause an unexpected +operation. +An example has been the use of a gopher URL to cause an +unintended or impersonating message to be sent via a SMTP server. +.PP +Caution should be used when using any URL that specifies a port +number other than the default for the protocol, especially when it is +a number within the reserved space. +.PP +Care should be taken when a URI contains escaped delimiters for a +given protocol (for example, CR and LF characters for telnet +protocols) that these are not unescaped before transmission. +This might violate the protocol, but avoids the potential for such +characters to be used to simulate an extra operation or parameter in +that protocol, which might lead to an unexpected and possibly harmful +remote operation to be performed. +.PP +It is clearly unwise to use a URI that contains a password which is +intended to be secret. +In particular, the use of a password within +the "userinfo" component of a URI is strongly recommended against except +in those rare cases where the "password" parameter is intended to be public. +.SH BUGS +.PP +Documentation may be placed in a variety of locations, so there +currently isn't a good URI scheme for general online documentation +in arbitrary formats. +References of the form + don't work because different distributions and +local installation requirements may place the files in different +directories +(it may be in /usr/doc, or /usr/local/doc, or /usr/share, +or somewhere else). +Also, the directory ZZZ usually changes when a version changes +(though filename globbing could partially overcome this). +Finally, using the file: scheme doesn't easily support people +who dynamically load documentation from the Internet (instead of +loading the files onto a local filesystem). +A future URI scheme may be added (e.g., "userdoc:") to permit +programs to include cross-references to more detailed documentation +without having to know the exact location of that documentation. +Alternatively, a future version of the filesystem specification may +specify file locations sufficiently so that the file: scheme will +be able to locate documentation. +.PP +Many programs and file formats don't include a way to incorporate +or implement links using URIs. +.PP +Many programs can't handle all of these different URI formats; there +should be a standard mechanism to load an arbitrary URI that automatically +detects the users' environment (e.g., text or graphics, +desktop environment, local user preferences, and currently executing +tools) and invokes the right tool for any URI. +.\" .SH AUTHOR +.\" David A. Wheeler (dwheeler@dwheeler.com) wrote this man page. +.SH SEE ALSO +.BR lynx (1), +.BR man2html (1), +.BR mailaddr (7), +.BR utf-8 (7) +.PP +.UR http://www.ietf.org\:/rfc\:/rfc2255.txt +IETF RFC\ 2255 +.UE +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/url.7 b/man7/url.7 new file mode 100644 index 0000000..079fb5e --- /dev/null +++ b/man7/url.7 @@ -0,0 +1 @@ +.so man7/uri.7 diff --git a/man7/urn.7 b/man7/urn.7 new file mode 100644 index 0000000..079fb5e --- /dev/null +++ b/man7/urn.7 @@ -0,0 +1 @@ +.so man7/uri.7 diff --git a/man7/user-keyring.7 b/man7/user-keyring.7 new file mode 100644 index 0000000..82b89f6 --- /dev/null +++ b/man7/user-keyring.7 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH "USER-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual" +.SH NAME +user-keyring \- per-user keyring +.SH DESCRIPTION +The user keyring is a keyring used to anchor keys on behalf of a user. +Each UID the kernel deals with has its own user keyring that +is shared by all processes with that UID. +The user keyring has a name (description) of the form +.I _uid. +where +.I +is the user ID of the corresponding user. +.PP +The user keyring is associated with the record that the kernel maintains +for the UID. +It comes into existence upon the first attempt to access either the +user keyring, the +.BR user-session-keyring (7), +or the +.BR session-keyring (7). +The keyring remains pinned in existence so long as there are processes +running with that real UID or files opened by those processes remain open. +(The keyring can also be pinned indefinitely by linking it +into another keyring.) +.PP +Typically, the user keyring is created by +.BR pam_keyinit (8) +when a user logs in. +.PP +The user keyring is not searched by default by +.BR request_key (2). +When +.BR pam_keyinit (8) +creates a session keyring, it adds to it a link to the user +keyring so that the user keyring will be searched when the session keyring is. +.PP +A special serial number value, +.BR KEY_SPEC_USER_KEYRING , +is defined that can be used in lieu of the actual serial number of +the calling process's user keyring. +.PP +From the +.BR keyctl (1) +utility, '\fB@u\fP' can be used instead of a numeric key ID in +much the same way. +.PP +User keyrings are independent of +.BR clone (2), +.BR fork (2), +.BR vfork (2), +.BR execve (2), +and +.BR _exit (2) +excepting that the keyring is destroyed when the UID record is destroyed when +the last process pinning it exits. +.PP +If it is necessary for a key associated with a user to exist beyond the UID +record being garbage collected\(emfor example, for use by a +.BR cron (8) +script\(emthen the +.BR persistent-keyring (7) +should be used instead. +.PP +If a user keyring does not exist when it is accessed, it will be created. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-session\-keyring (7), +.BR pam_keyinit (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/user-session-keyring.7 b/man7/user-session-keyring.7 new file mode 100644 index 0000000..5f25c79 --- /dev/null +++ b/man7/user-session-keyring.7 @@ -0,0 +1,107 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" %%%LICENSE_END +.\" +.TH "USER-SESSION-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual" +.SH NAME +user-session-keyring \- per-user default session keyring +.SH DESCRIPTION +The user session keyring is a keyring used to anchor keys on behalf of a user. +Each UID the kernel deals with has its own user session keyring that +is shared by all processes with that UID. +The user session keyring has a name (description) of the form +.I _uid_ses. +where +.I +is the user ID of the corresponding user. +.PP +The user session keyring is associated with the record that +the kernel maintains for the UID. +It comes into existence upon the first attempt to access either the +user session keyring, the +.BR user-keyring (7), +or the +.BR session-keyring (7). +.\" Davis Howells: the user and user-session keyrings are managed as a pair. +The keyring remains pinned in existence so long as there are processes +running with that real UID or files opened by those processes remain open. +(The keyring can also be pinned indefinitely by linking it +into another keyring.) +.PP +The user session keyring is created on demand when a thread requests it +or when a thread asks for its +.BR session-keyring (7) +and that keyring doesn't exist. +In the latter case, a user session keyring will be created and, +if the session keyring wasn't to be created, +the user session keyring will be set as the process's actual session keyring. +.PP +The user session keyring is searched by +.BR request_key (2) +if the actual session keyring does not exist and is ignored otherwise. +.PP +A special serial number value, +.BR KEY_SPEC_USER_SESSION_KEYRING , +is defined +that can be used in lieu of the actual serial number of +the calling process's user session keyring. +.PP +From the +.BR keyctl (1) +utility, '\fB@us\fP' can be used instead of a numeric key ID in +much the same way. +.PP +User session keyrings are independent of +.BR clone (2), +.BR fork (2), +.BR vfork (2), +.BR execve (2), +and +.BR _exit (2) +excepting that the keyring is destroyed when the UID record is destroyed +when the last process pinning it exits. +.PP +If a user session keyring does not exist when it is accessed, +it will be created. +.PP +Rather than relying on the user session keyring, +it is strongly recommended\(emespecially if the process +is running as root\(emthat a +.BR session-keyring (7) +be set explicitly, for example by +.BR pam_keyinit (8). +.SH NOTES +The user session keyring was added to support situations where +a process doesn't have a session keyring, +perhaps because it was created via a pathway that didn't involve PAM +(e.g., perhaps it was a daemon started by +.BR inetd (8)). +In such a scenario, the user session keyring acts as a substitute for the +.BR session-keyring (7). +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7 new file mode 100644 index 0000000..4c36943 --- /dev/null +++ b/man7/user_namespaces.7 @@ -0,0 +1,1339 @@ +.\" Copyright (c) 2013, 2014 by Michael Kerrisk +.\" and Copyright (c) 2012, 2014 by Eric W. Biederman +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH USER_NAMESPACES 7 2018-02-02 "Linux" "Linux Programmer's Manual" +.SH NAME +user_namespaces \- overview of Linux user namespaces +.SH DESCRIPTION +For an overview of namespaces, see +.BR namespaces (7). +.PP +User namespaces isolate security-related identifiers and attributes, +in particular, +user IDs and group IDs (see +.BR credentials (7)), +the root directory, +keys (see +.BR keyrings (7)), +.\" FIXME: This page says very little about the interaction +.\" of user namespaces and keys. Add something on this topic. +and capabilities (see +.BR capabilities (7)). +A process's user and group IDs can be different +inside and outside a user namespace. +In particular, +a process can have a normal unprivileged user ID outside a user namespace +while at the same time having a user ID of 0 inside the namespace; +in other words, +the process has full privileges for operations inside the user namespace, +but is unprivileged for operations outside the namespace. +.\" +.\" ============================================================ +.\" +.SS Nested namespaces, namespace membership +User namespaces can be nested; +that is, each user namespace\(emexcept the initial ("root") +namespace\(emhas a parent user namespace, +and can have zero or more child user namespaces. +The parent user namespace is the user namespace +of the process that creates the user namespace via a call to +.BR unshare (2) +or +.BR clone (2) +with the +.BR CLONE_NEWUSER +flag. +.PP +The kernel imposes (since version 3.11) a limit of 32 nested levels of +.\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8 +user namespaces. +.\" FIXME Explain the rationale for this limit. (What is the rationale?) +Calls to +.BR unshare (2) +or +.BR clone (2) +that would cause this limit to be exceeded fail with the error +.BR EUSERS . +.PP +Each process is a member of exactly one user namespace. +A process created via +.BR fork (2) +or +.BR clone (2) +without the +.BR CLONE_NEWUSER +flag is a member of the same user namespace as its parent. +A single-threaded process can join another user namespace with +.BR setns (2) +if it has the +.BR CAP_SYS_ADMIN +in that namespace; +upon doing so, it gains a full set of capabilities in that namespace. +.PP +A call to +.BR clone (2) +or +.BR unshare (2) +with the +.BR CLONE_NEWUSER +flag makes the new child process (for +.BR clone (2)) +or the caller (for +.BR unshare (2)) +a member of the new user namespace created by the call. +.PP +The +.BR NS_GET_PARENT +.BR ioctl (2) +operation can be used to discover the parental relationship +between user namespaces; see +.BR ioctl_ns (2). +.\" +.\" ============================================================ +.\" +.SS Capabilities +The child process created by +.BR clone (2) +with the +.BR CLONE_NEWUSER +flag starts out with a complete set +of capabilities in the new user namespace. +Likewise, a process that creates a new user namespace using +.BR unshare (2) +or joins an existing user namespace using +.BR setns (2) +gains a full set of capabilities in that namespace. +On the other hand, +that process has no capabilities in the parent (in the case of +.BR clone (2)) +or previous (in the case of +.BR unshare (2) +and +.BR setns (2)) +user namespace, +even if the new namespace is created or joined by the root user +(i.e., a process with user ID 0 in the root namespace). +.PP +Note that a call to +.BR execve (2) +will cause a process's capabilities to be recalculated in the usual way (see +.BR capabilities (7)). +Consequently, +unless the process has a user ID of 0 within the namespace, +or the executable file has a nonempty inheritable capabilities mask, +the process will lose all capabilities. +See the discussion of user and group ID mappings, below. +.PP +A call to +.BR clone (2), +.BR unshare (2), +or +.BR setns (2) +using the +.BR CLONE_NEWUSER +flag sets the "securebits" flags +(see +.BR capabilities (7)) +to their default values (all flags disabled) in the child (for +.BR clone (2)) +or caller (for +.BR unshare (2), +or +.BR setns (2)). +Note that because the caller no longer has capabilities +in its original user namespace after a call to +.BR setns (2), +it is not possible for a process to reset its "securebits" flags while +retaining its user namespace membership by using a pair of +.BR setns (2) +calls to move to another user namespace and then return to +its original user namespace. +.PP +The rules for determining whether or not a process has a capability +in a particular user namespace are as follows: +.IP 1. 3 +A process has a capability inside a user namespace +if it is a member of that namespace and +it has the capability in its effective capability set. +A process can gain capabilities in its effective capability +set in various ways. +For example, it may execute a set-user-ID program or an +executable with associated file capabilities. +In addition, +a process may gain capabilities via the effect of +.BR clone (2), +.BR unshare (2), +or +.BR setns (2), +as already described. +.\" In the 3.8 sources, see security/commoncap.c::cap_capable(): +.IP 2. +If a process has a capability in a user namespace, +then it has that capability in all child (and further removed descendant) +namespaces as well. +.IP 3. +.\" * The owner of the user namespace in the parent of the +.\" * user namespace has all caps. +When a user namespace is created, the kernel records the effective +user ID of the creating process as being the "owner" of the namespace. +.\" (and likewise associates the effective group ID of the creating process +.\" with the namespace). +A process that resides +in the parent of the user namespace +.\" See kernel commit 520d9eabce18edfef76a60b7b839d54facafe1f9 for a fix +.\" on this point +and whose effective user ID matches the owner of the namespace +has all capabilities in the namespace. +.\" This includes the case where the process executes a set-user-ID +.\" program that confers the effective UID of the creator of the namespace. +By virtue of the previous rule, +this means that the process has all capabilities in all +further removed descendant user namespaces as well. +The +.B NS_GET_OWNER_UID +.BR ioctl (2) +operation can be used to discover the user ID of the owner of the namespace; +see +.BR ioctl_ns (2). +.\" +.\" ============================================================ +.\" +.SS Effect of capabilities within a user namespace +Having a capability inside a user namespace +permits a process to perform operations (that require privilege) +only on resources governed by that namespace. +In other words, having a capability in a user namespace permits a process +to perform privileged operations on resources that are governed by (nonuser) +namespaces associated with the user namespace (see the next subsection). +.PP +On the other hand, there are many privileged operations that affect +resources that are not associated with any namespace type, +for example, changing the system time (governed by +.BR CAP_SYS_TIME ), +loading a kernel module (governed by +.BR CAP_SYS_MODULE ), +and creating a device (governed by +.BR CAP_MKNOD ). +Only a process with privileges in the +.I initial +user namespace can perform such operations. +.PP +Holding +.B CAP_SYS_ADMIN +within the user namespace associated with a process's mount namespace +allows that process to create bind mounts +and mount the following types of filesystems: +.\" fs_flags = FS_USERNS_MOUNT in kernel sources +.PP +.RS 4 +.PD 0 +.IP * 2 +.IR /proc +(since Linux 3.8) +.IP * +.IR /sys +(since Linux 3.8) +.IP * +.IR devpts +(since Linux 3.9) +.IP * +.BR tmpfs (5) +(since Linux 3.9) +.IP * +.IR ramfs +(since Linux 3.9) +.IP * +.IR mqueue +(since Linux 3.9) +.IP * +.IR bpf +.\" commit b2197755b2633e164a439682fb05a9b5ea48f706 +(since Linux 4.4) +.PD +.RE +.PP +Holding +.B CAP_SYS_ADMIN +within the user namespace associated with a process's cgroup namespace +allows (since Linux 4.6) +that process to the mount cgroup version 2 filesystem and +cgroup version 1 named hierarchies +(i.e., cgroup filesystems mounted with the +.BR """none,name=""" +option). +.PP +Holding +.B CAP_SYS_ADMIN +within the user namespace associated with a process's PID namespace +allows (since Linux 3.8) +that process to mount +.I /proc +filesystems. +.PP +Note however, that mounting block-based filesystems can be done +only by a process that holds +.BR CAP_SYS_ADMIN +in the initial user namespace. +.\" +.\" ============================================================ +.\" +.SS Interaction of user namespaces and other types of namespaces +Starting in Linux 3.8, unprivileged processes can create user namespaces, +and other the other types of namespaces can be created with just the +.B CAP_SYS_ADMIN +capability in the caller's user namespace. +.PP +When a non-user-namespace is created, +it is owned by the user namespace in which the creating process +was a member at the time of the creation of the namespace. +Actions on the non-user-namespace +require capabilities in the corresponding user namespace. +.PP +If +.BR CLONE_NEWUSER +is specified along with other +.B CLONE_NEW* +flags in a single +.BR clone (2) +or +.BR unshare (2) +call, the user namespace is guaranteed to be created first, +giving the child +.RB ( clone (2)) +or caller +.RB ( unshare (2)) +privileges over the remaining namespaces created by the call. +Thus, it is possible for an unprivileged caller to specify this combination +of flags. +.PP +When a new namespace (other than a user namespace) is created via +.BR clone (2) +or +.BR unshare (2), +the kernel records the user namespace of the creating process against +the new namespace. +(This association can't be changed.) +When a process in the new namespace subsequently performs +privileged operations that operate on global +resources isolated by the namespace, +the permission checks are performed according to the process's capabilities +in the user namespace that the kernel associated with the new namespace. +For example, suppose that a process attempts to change the hostname +.RB ( sethostname (2)), +a resource governed by the UTS namespace. +In this case, +the kernel will determine which user namespace is associated with +the process's UTS namespace, and check whether the process has the +required capability +.RB ( CAP_SYS_ADMIN ) +in that user namespace. +.PP +The +.BR NS_GET_USERNS +.BR ioctl (2) +operation can be used to discover the user namespace with which +a non-user namespace is associated; see +.BR ioctl_ns (2). +.\" +.\" ============================================================ +.\" +.SS User and group ID mappings: uid_map and gid_map +When a user namespace is created, +it starts out without a mapping of user IDs (group IDs) +to the parent user namespace. +The +.IR /proc/[pid]/uid_map +and +.IR /proc/[pid]/gid_map +files (available since Linux 3.5) +.\" commit 22d917d80e842829d0ca0a561967d728eb1d6303 +expose the mappings for user and group IDs +inside the user namespace for the process +.IR pid . +These files can be read to view the mappings in a user namespace and +written to (once) to define the mappings. +.PP +The description in the following paragraphs explains the details for +.IR uid_map ; +.IR gid_map +is exactly the same, +but each instance of "user ID" is replaced by "group ID". +.PP +The +.I uid_map +file exposes the mapping of user IDs from the user namespace +of the process +.IR pid +to the user namespace of the process that opened +.IR uid_map +(but see a qualification to this point below). +In other words, processes that are in different user namespaces +will potentially see different values when reading from a particular +.I uid_map +file, depending on the user ID mappings for the user namespaces +of the reading processes. +.PP +Each line in the +.I uid_map +file specifies a 1-to-1 mapping of a range of contiguous +user IDs between two user namespaces. +(When a user namespace is first created, this file is empty.) +The specification in each line takes the form of +three numbers delimited by white space. +The first two numbers specify the starting user ID in +each of the two user namespaces. +The third number specifies the length of the mapped range. +In detail, the fields are interpreted as follows: +.IP (1) 4 +The start of the range of user IDs in +the user namespace of the process +.IR pid . +.IP (2) +The start of the range of user +IDs to which the user IDs specified by field one map. +How field two is interpreted depends on whether the process that opened +.I uid_map +and the process +.IR pid +are in the same user namespace, as follows: +.RS +.IP a) 3 +If the two processes are in different user namespaces: +field two is the start of a range of +user IDs in the user namespace of the process that opened +.IR uid_map . +.IP b) +If the two processes are in the same user namespace: +field two is the start of the range of +user IDs in the parent user namespace of the process +.IR pid . +This case enables the opener of +.I uid_map +(the common case here is opening +.IR /proc/self/uid_map ) +to see the mapping of user IDs into the user namespace of the process +that created this user namespace. +.RE +.IP (3) +The length of the range of user IDs that is mapped between the two +user namespaces. +.PP +System calls that return user IDs (group IDs)\(emfor example, +.BR getuid (2), +.BR getgid (2), +and the credential fields in the structure returned by +.BR stat (2)\(emreturn +the user ID (group ID) mapped into the caller's user namespace. +.PP +When a process accesses a file, its user and group IDs +are mapped into the initial user namespace for the purpose of permission +checking and assigning IDs when creating a file. +When a process retrieves file user and group IDs via +.BR stat (2), +the IDs are mapped in the opposite direction, +to produce values relative to the process user and group ID mappings. +.PP +The initial user namespace has no parent namespace, +but, for consistency, the kernel provides dummy user and group +ID mapping files for this namespace. +Looking at the +.I uid_map +file +.RI ( gid_map +is the same) from a shell in the initial namespace shows: +.PP +.in +4n +.EX +$ \fBcat /proc/$$/uid_map\fP + 0 0 4294967295 +.EE +.in +.PP +This mapping tells us +that the range starting at user ID 0 in this namespace +maps to a range starting at 0 in the (nonexistent) parent namespace, +and the length of the range is the largest 32-bit unsigned integer. +This leaves 4294967295 (the 32-bit signed \-1 value) unmapped. +This is deliberate: +.IR "(uid_t)\ \-1" +is used in several interfaces (e.g., +.BR setreuid (2)) +as a way to specify "no user ID". +Leaving +.IR "(uid_t)\ \-1" +unmapped and unusable guarantees that there will be no +confusion when using these interfaces. +.\" +.\" ============================================================ +.\" +.SS Defining user and group ID mappings: writing to uid_map and gid_map +.PP +After the creation of a new user namespace, the +.I uid_map +file of +.I one +of the processes in the namespace may be written to +.I once +to define the mapping of user IDs in the new user namespace. +An attempt to write more than once to a +.I uid_map +file in a user namespace fails with the error +.BR EPERM . +Similar rules apply for +.I gid_map +files. +.PP +The lines written to +.IR uid_map +.RI ( gid_map ) +must conform to the following rules: +.IP * 3 +The three fields must be valid numbers, +and the last field must be greater than 0. +.IP * +Lines are terminated by newline characters. +.IP * +There is a limit on the number of lines in the file. +In Linux 4.14 and earlier, this limit was (arbitrarily) +.\" 5*12-byte records could fit in a 64B cache line +set at 5 lines. +Since Linux 4.15, +.\" commit 6397fac4915ab3002dc15aae751455da1a852f25 +the limit is 340 lines. +In addition, the number of bytes written to +the file must be less than the system page size, +and the write must be performed at the start of the file (i.e., +.BR lseek (2) +and +.BR pwrite (2) +can't be used to write to nonzero offsets in the file). +.IP * +The range of user IDs (group IDs) +specified in each line cannot overlap with the ranges +in any other lines. +In the initial implementation (Linux 3.8), this requirement was +satisfied by a simplistic implementation that imposed the further +requirement that +the values in both field 1 and field 2 of successive lines must be +in ascending numerical order, +which prevented some otherwise valid maps from being created. +Linux 3.9 and later +.\" commit 0bd14b4fd72afd5df41e9fd59f356740f22fceba +fix this limitation, allowing any valid set of nonoverlapping maps. +.IP * +At least one line must be written to the file. +.PP +Writes that violate the above rules fail with the error +.BR EINVAL . +.PP +In order for a process to write to the +.I /proc/[pid]/uid_map +.RI ( /proc/[pid]/gid_map ) +file, all of the following requirements must be met: +.IP 1. 3 +The writing process must have the +.BR CAP_SETUID +.RB ( CAP_SETGID ) +capability in the user namespace of the process +.IR pid . +.IP 2. +The writing process must either be in the user namespace of the process +.I pid +or be in the parent user namespace of the process +.IR pid . +.IP 3. +The mapped user IDs (group IDs) must in turn have a mapping +in the parent user namespace. +.IP 4. +One of the following two cases applies: +.RS +.IP * 3 +.IR Either +the writing process has the +.BR CAP_SETUID +.RB ( CAP_SETGID ) +capability in the +.I parent +user namespace. +.RS +.IP + 3 +No further restrictions apply: +the process can make mappings to arbitrary user IDs (group IDs) +in the parent user namespace. +.RE +.IP * 3 +.IR Or +otherwise all of the following restrictions apply: +.RS +.IP + 3 +The data written to +.I uid_map +.RI ( gid_map ) +must consist of a single line that maps +the writing process's effective user ID +(group ID) in the parent user namespace to a user ID (group ID) +in the user namespace. +.IP + +The writing process must have the same effective user ID as the process +that created the user namespace. +.IP + +In the case of +.IR gid_map , +use of the +.BR setgroups (2) +system call must first be denied by writing +.RI \(dq deny \(dq +to the +.I /proc/[pid]/setgroups +file (see below) before writing to +.IR gid_map . +.RE +.RE +.PP +Writes that violate the above rules fail with the error +.BR EPERM . +.\" +.\" ============================================================ +.\" +.SS Interaction with system calls that change process UIDs or GIDs +In a user namespace where the +.I uid_map +file has not been written, the system calls that change user IDs will fail. +Similarly, if the +.I gid_map +file has not been written, the system calls that change group IDs will fail. +After the +.I uid_map +and +.I gid_map +files have been written, only the mapped values may be used in +system calls that change user and group IDs. +.PP +For user IDs, the relevant system calls include +.BR setuid (2), +.BR setfsuid (2), +.BR setreuid (2), +and +.BR setresuid (2). +For group IDs, the relevant system calls include +.BR setgid (2), +.BR setfsgid (2), +.BR setregid (2), +.BR setresgid (2), +and +.BR setgroups (2). +.PP +Writing +.RI \(dq deny \(dq +to the +.I /proc/[pid]/setgroups +file before writing to +.I /proc/[pid]/gid_map +.\" Things changed in Linux 3.19 +.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8 +.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272 +.\" http://lwn.net/Articles/626665/ +will permanently disable +.BR setgroups (2) +in a user namespace and allow writing to +.I /proc/[pid]/gid_map +without having the +.BR CAP_SETGID +capability in the parent user namespace. +.\" +.\" ============================================================ +.\" +.SS The /proc/[pid]/setgroups file +.\" +.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8 +.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272 +.\" http://lwn.net/Articles/626665/ +.\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989 +.\" +The +.I /proc/[pid]/setgroups +file displays the string +.RI \(dq allow \(dq +if processes in the user namespace that contains the process +.I pid +are permitted to employ the +.BR setgroups (2) +system call; it displays +.RI \(dq deny \(dq +if +.BR setgroups (2) +is not permitted in that user namespace. +Note that regardless of the value in the +.I /proc/[pid]/setgroups +file (and regardless of the process's capabilities), calls to +.BR setgroups (2) +are also not permitted if +.IR /proc/[pid]/gid_map +has not yet been set. +.PP +A privileged process (one with the +.BR CAP_SYS_ADMIN +capability in the namespace) may write either of the strings +.RI \(dq allow \(dq +or +.RI \(dq deny \(dq +to this file +.I before +writing a group ID mapping +for this user namespace to the file +.IR /proc/[pid]/gid_map . +Writing the string +.RI \(dq deny \(dq +prevents any process in the user namespace from employing +.BR setgroups (2). +.PP +The essence of the restrictions described in the preceding +paragraph is that it is permitted to write to +.I /proc/[pid]/setgroups +only so long as calling +.BR setgroups (2) +is disallowed because +.I /proc/[pid]gid_map +has not been set. +This ensures that a process cannot transition from a state where +.BR setgroups (2) +is allowed to a state where +.BR setgroups (2) +is denied; +a process can transition only from +.BR setgroups (2) +being disallowed to +.BR setgroups (2) +being allowed. +.PP +The default value of this file in the initial user namespace is +.RI \(dq allow \(dq. +.PP +Once +.IR /proc/[pid]/gid_map +has been written to +(which has the effect of enabling +.BR setgroups (2) +in the user namespace), +it is no longer possible to disallow +.BR setgroups (2) +by writing +.RI \(dq deny \(dq +to +.IR /proc/[pid]/setgroups +(the write fails with the error +.BR EPERM ). +.PP +A child user namespace inherits the +.IR /proc/[pid]/setgroups +setting from its parent. +.PP +If the +.I setgroups +file has the value +.RI \(dq deny \(dq, +then the +.BR setgroups (2) +system call can't subsequently be reenabled (by writing +.RI \(dq allow \(dq +to the file) in this user namespace. +(Attempts to do so fail with the error +.BR EPERM .) +This restriction also propagates down to all child user namespaces of +this user namespace. +.PP +The +.I /proc/[pid]/setgroups +file was added in Linux 3.19, +but was backported to many earlier stable kernel series, +because it addresses a security issue. +The issue concerned files with permissions such as "rwx\-\-\-rwx". +Such files give fewer permissions to "group" than they do to "other". +This means that dropping groups using +.BR setgroups (2) +might allow a process file access that it did not formerly have. +Before the existence of user namespaces this was not a concern, +since only a privileged process (one with the +.BR CAP_SETGID +capability) could call +.BR setgroups (2). +However, with the introduction of user namespaces, +it became possible for an unprivileged process to create +a new namespace in which the user had all privileges. +This then allowed formerly unprivileged +users to drop groups and thus gain file access +that they did not previously have. +The +.I /proc/[pid]/setgroups +file was added to address this security issue, +by denying any pathway for an unprivileged process to drop groups with +.BR setgroups (2). +.\" +.\" /proc/PID/setgroups +.\" [allow == setgroups() is allowed, "deny" == setgroups() is disallowed] +.\" * Can write if have CAP_SYS_ADMIN in NS +.\" * Must write BEFORE writing to /proc/PID/gid_map +.\" +.\" setgroups() +.\" * Must already have written to gid_map +.\" * /proc/PID/setgroups must be "allow" +.\" +.\" /proc/PID/gid_map -- writing +.\" * Must already have written "deny" to /proc/PID/setgroups +.\" +.\" ============================================================ +.\" +.SS Unmapped user and group IDs +.PP +There are various places where an unmapped user ID (group ID) +may be exposed to user space. +For example, the first process in a new user namespace may call +.BR getuid (2) +before a user ID mapping has been defined for the namespace. +In most such cases, an unmapped user ID is converted +.\" from_kuid_munged(), from_kgid_munged() +to the overflow user ID (group ID); +the default value for the overflow user ID (group ID) is 65534. +See the descriptions of +.IR /proc/sys/kernel/overflowuid +and +.IR /proc/sys/kernel/overflowgid +in +.BR proc (5). +.PP +The cases where unmapped IDs are mapped in this fashion include +system calls that return user IDs +.RB ( getuid (2), +.BR getgid (2), +and similar), +credentials passed over a UNIX domain socket, +.\" also SO_PEERCRED +credentials returned by +.BR stat (2), +.BR waitid (2), +and the System V IPC "ctl" +.B IPC_STAT +operations, +credentials exposed by +.IR /proc/[pid]/status +and the files in +.IR /proc/sysvipc/* , +credentials returned via the +.I si_uid +field in the +.I siginfo_t +received with a signal (see +.BR sigaction (2)), +credentials written to the process accounting file (see +.BR acct (5)), +and credentials returned with POSIX message queue notifications (see +.BR mq_notify (3)). +.PP +There is one notable case where unmapped user and group IDs are +.I not +.\" from_kuid(), from_kgid() +.\" Also F_GETOWNER_UIDS is an exception +converted to the corresponding overflow ID value. +When viewing a +.I uid_map +or +.I gid_map +file in which there is no mapping for the second field, +that field is displayed as 4294967295 (\-1 as an unsigned integer). +.\" +.\" ============================================================ +.\" +.SS Set-user-ID and set-group-ID programs +.PP +When a process inside a user namespace executes +a set-user-ID (set-group-ID) program, +the process's effective user (group) ID inside the namespace is changed +to whatever value is mapped for the user (group) ID of the file. +However, if either the user +.I or +the group ID of the file has no mapping inside the namespace, +the set-user-ID (set-group-ID) bit is silently ignored: +the new program is executed, +but the process's effective user (group) ID is left unchanged. +(This mirrors the semantics of executing a set-user-ID or set-group-ID +program that resides on a filesystem that was mounted with the +.BR MS_NOSUID +flag, as described in +.BR mount (2).) +.\" +.\" ============================================================ +.\" +.SS Miscellaneous +.PP +When a process's user and group IDs are passed over a UNIX domain socket +to a process in a different user namespace (see the description of +.B SCM_CREDENTIALS +in +.BR unix (7)), +they are translated into the corresponding values as per the +receiving process's user and group ID mappings. +.\" +.SH CONFORMING TO +Namespaces are a Linux-specific feature. +.\" +.SH NOTES +Over the years, there have been a lot of features that have been added +to the Linux kernel that have been made available only to privileged users +because of their potential to confuse set-user-ID-root applications. +In general, it becomes safe to allow the root user in a user namespace to +use those features because it is impossible, while in a user namespace, +to gain more privilege than the root user of a user namespace has. +.\" +.\" ============================================================ +.\" +.SS Availability +Use of user namespaces requires a kernel that is configured with the +.B CONFIG_USER_NS +option. +User namespaces require support in a range of subsystems across +the kernel. +When an unsupported subsystem is configured into the kernel, +it is not possible to configure user namespaces support. +.PP +As at Linux 3.8, most relevant subsystems supported user namespaces, +but a number of filesystems did not have the infrastructure needed +to map user and group IDs between user namespaces. +Linux 3.9 added the required infrastructure support for many of +the remaining unsupported filesystems +(Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2). +Linux 3.12 added support the last of the unsupported major filesystems, +.\" commit d6970d4b726cea6d7a9bc4120814f95c09571fc3 +XFS. +.\" +.SH EXAMPLE +The program below is designed to allow experimenting with +user namespaces, as well as other types of namespaces. +It creates namespaces as specified by command-line options and then executes +a command inside those namespaces. +The comments and +.I usage() +function inside the program provide a full explanation of the program. +The following shell session demonstrates its use. +.PP +First, we look at the run-time environment: +.PP +.in +4n +.EX +$ \fBuname \-rs\fP # Need Linux 3.8 or later +Linux 3.8.0 +$ \fBid \-u\fP # Running as unprivileged user +1000 +$ \fBid \-g\fP +1000 +.EE +.in +.PP +Now start a new shell in new user +.RI ( \-U ), +mount +.RI ( \-m ), +and PID +.RI ( \-p ) +namespaces, with user ID +.RI ( \-M ) +and group ID +.RI ( \-G ) +1000 mapped to 0 inside the user namespace: +.PP +.in +4n +.EX +$ \fB./userns_child_exec \-p \-m \-U \-M '0 1000 1' \-G '0 1000 1' bash\fP +.EE +.in +.PP +The shell has PID 1, because it is the first process in the new +PID namespace: +.PP +.in +4n +.EX +bash$ \fBecho $$\fP +1 +.EE +.in +Mounting a new +.I /proc +filesystem and listing all of the processes visible +in the new PID namespace shows that the shell can't see +any processes outside the PID namespace: +.PP +.in +4n +.EX +bash$ \fBmount \-t proc proc /proc\fP +bash$ \fBps ax\fP + PID TTY STAT TIME COMMAND + 1 pts/3 S 0:00 bash + 22 pts/3 R+ 0:00 ps ax +.EE +.in +.PP +Inside the user namespace, the shell has user and group ID 0, +and a full set of permitted and effective capabilities: +.PP +.in +4n +.EX +bash$ \fBcat /proc/$$/status | egrep '^[UG]id'\fP +Uid: 0 0 0 0 +Gid: 0 0 0 0 +bash$ \fBcat /proc/$$/status | egrep '^Cap(Prm|Inh|Eff)'\fP +CapInh: 0000000000000000 +CapPrm: 0000001fffffffff +CapEff: 0000001fffffffff +.EE +.in +.SS Program source +\& +.EX +/* userns_child_exec.c + + Licensed under GNU General Public License v2 or later + + Create a child process that executes a shell command in new + namespace(s); allow UID and GID mappings to be specified when + creating a user namespace. +*/ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +/* A simple error\-handling function: print an error message based + on the value in \(aqerrno\(aq and terminate the calling process */ + +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ + } while (0) + +struct child_args { + char **argv; /* Command to be executed by child, with args */ + int pipe_fd[2]; /* Pipe used to synchronize parent and child */ +}; + +static int verbose; + +static void +usage(char *pname) +{ + fprintf(stderr, "Usage: %s [options] cmd [arg...]\\n\\n", pname); + fprintf(stderr, "Create a child process that executes a shell " + "command in a new user namespace,\\n" + "and possibly also other new namespace(s).\\n\\n"); + fprintf(stderr, "Options can be:\\n\\n"); +#define fpe(str) fprintf(stderr, " %s", str); + fpe("\-i New IPC namespace\\n"); + fpe("\-m New mount namespace\\n"); + fpe("\-n New network namespace\\n"); + fpe("\-p New PID namespace\\n"); + fpe("\-u New UTS namespace\\n"); + fpe("\-U New user namespace\\n"); + fpe("\-M uid_map Specify UID map for user namespace\\n"); + fpe("\-G gid_map Specify GID map for user namespace\\n"); + fpe("\-z Map user\(aqs UID and GID to 0 in user namespace\\n"); + fpe(" (equivalent to: \-M \(aq0 1\(aq \-G \(aq0 1\(aq)\\n"); + fpe("\-v Display verbose messages\\n"); + fpe("\\n"); + fpe("If \-z, \-M, or \-G is specified, \-U is required.\\n"); + fpe("It is not permitted to specify both \-z and either \-M or \-G.\\n"); + fpe("\\n"); + fpe("Map strings for \-M and \-G consist of records of the form:\\n"); + fpe("\\n"); + fpe(" ID\-inside\-ns ID\-outside\-ns len\\n"); + fpe("\\n"); + fpe("A map string can contain multiple records, separated" + " by commas;\\n"); + fpe("the commas are replaced by newlines before writing" + " to map files.\\n"); + + exit(EXIT_FAILURE); +} + +/* Update the mapping file \(aqmap_file\(aq, with the value provided in + \(aqmapping\(aq, a string that defines a UID or GID mapping. A UID or + GID mapping consists of one or more newline\-delimited records + of the form: + + ID_inside\-ns ID\-outside\-ns length + + Requiring the user to supply a string that contains newlines is + of course inconvenient for command\-line use. Thus, we permit the + use of commas to delimit records in this string, and replace them + with newlines before writing the string to the file. */ + +static void +update_map(char *mapping, char *map_file) +{ + int fd, j; + size_t map_len; /* Length of \(aqmapping\(aq */ + + /* Replace commas in mapping string with newlines */ + + map_len = strlen(mapping); + for (j = 0; j < map_len; j++) + if (mapping[j] == \(aq,\(aq) + mapping[j] = \(aq\\n\(aq; + + fd = open(map_file, O_RDWR); + if (fd == \-1) { + fprintf(stderr, "ERROR: open %s: %s\\n", map_file, + strerror(errno)); + exit(EXIT_FAILURE); + } + + if (write(fd, mapping, map_len) != map_len) { + fprintf(stderr, "ERROR: write %s: %s\\n", map_file, + strerror(errno)); + exit(EXIT_FAILURE); + } + + close(fd); +} + +/* Linux 3.19 made a change in the handling of setgroups(2) and the + \(aqgid_map\(aq file to address a security issue. The issue allowed + *unprivileged* users to employ user namespaces in order to drop + The upshot of the 3.19 changes is that in order to update the + \(aqgid_maps\(aq file, use of the setgroups() system call in this + user namespace must first be disabled by writing "deny" to one of + the /proc/PID/setgroups files for this namespace. That is the + purpose of the following function. */ + +static void +proc_setgroups_write(pid_t child_pid, char *str) +{ + char setgroups_path[PATH_MAX]; + int fd; + + snprintf(setgroups_path, PATH_MAX, "/proc/%ld/setgroups", + (long) child_pid); + + fd = open(setgroups_path, O_RDWR); + if (fd == \-1) { + + /* We may be on a system that doesn\(aqt support + /proc/PID/setgroups. In that case, the file won\(aqt exist, + and the system won\(aqt impose the restrictions that Linux 3.19 + added. That\(aqs fine: we don\(aqt need to do anything in order + to permit \(aqgid_map\(aq to be updated. + + However, if the error from open() was something other than + the ENOENT error that is expected for that case, let the + user know. */ + + if (errno != ENOENT) + fprintf(stderr, "ERROR: open %s: %s\\n", setgroups_path, + strerror(errno)); + return; + } + + if (write(fd, str, strlen(str)) == \-1) + fprintf(stderr, "ERROR: write %s: %s\\n", setgroups_path, + strerror(errno)); + + close(fd); +} + +static int /* Start function for cloned child */ +childFunc(void *arg) +{ + struct child_args *args = (struct child_args *) arg; + char ch; + + /* Wait until the parent has updated the UID and GID mappings. + See the comment in main(). We wait for end of file on a + pipe that will be closed by the parent process once it has + updated the mappings. */ + + close(args\->pipe_fd[1]); /* Close our descriptor for the write + end of the pipe so that we see EOF + when parent closes its descriptor */ + if (read(args\->pipe_fd[0], &ch, 1) != 0) { + fprintf(stderr, + "Failure in child: read from pipe returned != 0\\n"); + exit(EXIT_FAILURE); + } + + close(args\->pipe_fd[0]); + + /* Execute a shell command */ + + printf("About to exec %s\\n", args\->argv[0]); + execvp(args\->argv[0], args\->argv); + errExit("execvp"); +} + +#define STACK_SIZE (1024 * 1024) + +static char child_stack[STACK_SIZE]; /* Space for child\(aqs stack */ + +int +main(int argc, char *argv[]) +{ + int flags, opt, map_zero; + pid_t child_pid; + struct child_args args; + char *uid_map, *gid_map; + const int MAP_BUF_SIZE = 100; + char map_buf[MAP_BUF_SIZE]; + char map_path[PATH_MAX]; + + /* Parse command\-line options. The initial \(aq+\(aq character in + the final getopt() argument prevents GNU\-style permutation + of command\-line options. That\(aqs useful, since sometimes + the \(aqcommand\(aq to be executed by this program itself + has command\-line options. We don\(aqt want getopt() to treat + those as options to this program. */ + + flags = 0; + verbose = 0; + gid_map = NULL; + uid_map = NULL; + map_zero = 0; + while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != \-1) { + switch (opt) { + case \(aqi\(aq: flags |= CLONE_NEWIPC; break; + case \(aqm\(aq: flags |= CLONE_NEWNS; break; + case \(aqn\(aq: flags |= CLONE_NEWNET; break; + case \(aqp\(aq: flags |= CLONE_NEWPID; break; + case \(aqu\(aq: flags |= CLONE_NEWUTS; break; + case \(aqv\(aq: verbose = 1; break; + case \(aqz\(aq: map_zero = 1; break; + case \(aqM\(aq: uid_map = optarg; break; + case \(aqG\(aq: gid_map = optarg; break; + case \(aqU\(aq: flags |= CLONE_NEWUSER; break; + default: usage(argv[0]); + } + } + + /* \-M or \-G without \-U is nonsensical */ + + if (((uid_map != NULL || gid_map != NULL || map_zero) && + !(flags & CLONE_NEWUSER)) || + (map_zero && (uid_map != NULL || gid_map != NULL))) + usage(argv[0]); + + args.argv = &argv[optind]; + + /* We use a pipe to synchronize the parent and child, in order to + ensure that the parent sets the UID and GID maps before the child + calls execve(). This ensures that the child maintains its + capabilities during the execve() in the common case where we + want to map the child\(aqs effective user ID to 0 in the new user + namespace. Without this synchronization, the child would lose + its capabilities if it performed an execve() with nonzero + user IDs (see the capabilities(7) man page for details of the + transformation of a process\(aqs capabilities during execve()). */ + + if (pipe(args.pipe_fd) == \-1) + errExit("pipe"); + + /* Create the child in new namespace(s) */ + + child_pid = clone(childFunc, child_stack + STACK_SIZE, + flags | SIGCHLD, &args); + if (child_pid == \-1) + errExit("clone"); + + /* Parent falls through to here */ + + if (verbose) + printf("%s: PID of child created by clone() is %ld\\n", + argv[0], (long) child_pid); + + /* Update the UID and GID maps in the child */ + + if (uid_map != NULL || map_zero) { + snprintf(map_path, PATH_MAX, "/proc/%ld/uid_map", + (long) child_pid); + if (map_zero) { + snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1", (long) getuid()); + uid_map = map_buf; + } + update_map(uid_map, map_path); + } + + if (gid_map != NULL || map_zero) { + proc_setgroups_write(child_pid, "deny"); + + snprintf(map_path, PATH_MAX, "/proc/%ld/gid_map", + (long) child_pid); + if (map_zero) { + snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1", (long) getgid()); + gid_map = map_buf; + } + update_map(gid_map, map_path); + } + + /* Close the write end of the pipe, to signal to the child that we + have updated the UID and GID maps */ + + close(args.pipe_fd[1]); + + if (waitpid(child_pid, NULL, 0) == \-1) /* Wait for child */ + errExit("waitpid"); + + if (verbose) + printf("%s: terminating\\n", argv[0]); + + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR newgidmap (1), \" From the shadow package +.BR newuidmap (1), \" From the shadow package +.BR clone (2), +.BR ptrace (2), +.BR setns (2), +.BR unshare (2), +.BR proc (5), +.BR subgid (5), \" From the shadow package +.BR subuid (5), \" From the shadow package +.BR capabilities (7), +.BR cgroup_namespaces (7) +.BR credentials (7), +.BR namespaces (7), +.BR pid_namespaces (7) +.PP +The kernel source file +.IR Documentation/namespaces/resource-control.txt . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/utf-8.7 b/man7/utf-8.7 new file mode 100644 index 0000000..5ec5168 --- /dev/null +++ b/man7/utf-8.7 @@ -0,0 +1,239 @@ +.\" Copyright (C) Markus Kuhn, 1996, 2001 +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" 2001-05-11 Markus Kuhn +.\" Update +.\" +.TH UTF-8 7 2016-07-17 "GNU" "Linux Programmer's Manual" +.SH NAME +UTF-8 \- an ASCII compatible multibyte Unicode encoding +.SH DESCRIPTION +The Unicode 3.0 character set occupies a 16-bit code space. +The most obvious +Unicode encoding (known as UCS-2) +consists of a sequence of 16-bit words. +Such strings can contain\(emas part of many 16-bit characters\(embytes +such as \(aq\\0\(aq or \(aq/\(aq, which have a +special meaning in filenames and other C library function arguments. +In addition, the majority of UNIX tools expect ASCII files and can't +read 16-bit words as characters without major modifications. +For these reasons, +UCS-2 is not a suitable external encoding of Unicode +in filenames, text files, environment variables, and so on. +The ISO 10646 Universal Character Set (UCS), +a superset of Unicode, occupies an even larger code +space\(em31\ bits\(emand the obvious +UCS-4 encoding for it (a sequence of 32-bit words) has the same problems. +.PP +The UTF-8 encoding of Unicode and UCS +does not have these problems and is the common way in which +Unicode is used on UNIX-style operating systems. +.SS Properties +The UTF-8 encoding has the following nice properties: +.TP 0.2i +* +UCS +characters 0x00000000 to 0x0000007f (the classic US-ASCII +characters) are encoded simply as bytes 0x00 to 0x7f (ASCII +compatibility). +This means that files and strings which contain only +7-bit ASCII characters have the same encoding under both +ASCII +and +UTF-8 . +.TP +* +All UCS characters greater than 0x7f are encoded as a multibyte sequence +consisting only of bytes in the range 0x80 to 0xfd, so no ASCII +byte can appear as part of another character and there are no +problems with, for example, \(aq\\0\(aq or \(aq/\(aq. +.TP +* +The lexicographic sorting order of UCS-4 strings is preserved. +.TP +* +All possible 2^31 UCS codes can be encoded using UTF-8. +.TP +* +The bytes 0xc0, 0xc1, 0xfe, and 0xff are never used in the UTF-8 encoding. +.TP +* +The first byte of a multibyte sequence which represents a single non-ASCII +UCS character is always in the range 0xc2 to 0xfd and indicates how long +this multibyte sequence is. +All further bytes in a multibyte sequence +are in the range 0x80 to 0xbf. +This allows easy resynchronization and +makes the encoding stateless and robust against missing bytes. +.TP +* +UTF-8 encoded UCS characters may be up to six bytes long, however the +Unicode standard specifies no characters above 0x10ffff, so Unicode characters +can be only up to four bytes long in +UTF-8. +.SS Encoding +The following byte sequences are used to represent a character. +The sequence to be used depends on the UCS code number of the character: +.TP 0.4i +0x00000000 \- 0x0000007F: +.RI 0 xxxxxxx +.TP +0x00000080 \- 0x000007FF: +.RI 110 xxxxx +.RI 10 xxxxxx +.TP +0x00000800 \- 0x0000FFFF: +.RI 1110 xxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x00010000 \- 0x001FFFFF: +.RI 11110 xxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x00200000 \- 0x03FFFFFF: +.RI 111110 xx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x04000000 \- 0x7FFFFFFF: +.RI 1111110 x +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.PP +The +.I xxx +bit positions are filled with the bits of the character code number in +binary representation, most significant bit first (big-endian). +Only the shortest possible multibyte sequence +which can represent the code number of the character can be used. +.PP +The UCS code values 0xd800\(en0xdfff (UTF-16 surrogates) as well as 0xfffe and +0xffff (UCS noncharacters) should not appear in conforming UTF-8 streams. According +to RFC 3629 no point above U+10FFFF should be used, which limits characters to four +bytes. +.SS Example +The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded +in UTF-8 as +.PP +.RS +11000010 10101001 = 0xc2 0xa9 +.RE +.PP +and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is +encoded as: +.PP +.RS +11100010 10001001 10100000 = 0xe2 0x89 0xa0 +.RE +.SS Application notes +Users have to select a UTF-8 locale, for example with +.PP +.RS +export LANG=en_GB.UTF-8 +.RE +.PP +in order to activate the UTF-8 support in applications. +.PP +Application software that has to be aware of the used character +encoding should always set the locale with for example +.PP +.RS +setlocale(LC_CTYPE, "") +.RE +.PP +and programmers can then test the expression +.PP +.RS +strcmp(nl_langinfo(CODESET), "UTF-8") == 0 +.RE +.PP +to determine whether a UTF-8 locale has been selected and whether +therefore all plaintext standard input and output, terminal +communication, plaintext file content, filenames and environment +variables are encoded in UTF-8. +.PP +Programmers accustomed to single-byte encodings such as US-ASCII or ISO 8859 +have to be aware that two assumptions made so far are no longer valid +in UTF-8 locales. +Firstly, a single byte does not necessarily correspond any +more to a single character. +Secondly, since modern terminal emulators in UTF-8 +mode also support Chinese, Japanese, and Korean +double-width characters as well as nonspacing combining characters, +outputting a single character does not necessarily advance the cursor +by one position as it did in ASCII. +Library functions such as +.BR mbsrtowcs (3) +and +.BR wcswidth (3) +should be used today to count characters and cursor positions. +.PP +The official ESC sequence to switch from an ISO 2022 +encoding scheme (as used for instance by VT100 terminals) to +UTF-8 is ESC % G +("\\x1b%G"). +The corresponding return sequence from +UTF-8 to ISO 2022 is ESC % @ ("\\x1b%@"). +Other ISO 2022 sequences (such as +for switching the G0 and G1 sets) are not applicable in UTF-8 mode. +.SS Security +The Unicode and UCS standards require that producers of UTF-8 +shall use the shortest form possible, for example, producing a two-byte +sequence with first byte 0xc0 is nonconforming. +Unicode 3.1 has added the requirement that conforming programs must not accept +non-shortest forms in their input. +This is for security reasons: if +user input is checked for possible security violations, a program +might check only for the ASCII +version of "/../" or ";" or NUL and overlook that there are many +non-ASCII ways to represent these things in a non-shortest UTF-8 +encoding. +.SS Standards +ISO/IEC 10646-1:2000, Unicode 3.1, RFC\ 3629, Plan 9. +.\" .SH AUTHOR +.\" Markus Kuhn +.SH SEE ALSO +.BR locale (1), +.BR nl_langinfo (3), +.BR setlocale (3), +.BR charsets (7), +.BR unicode (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/utf8.7 b/man7/utf8.7 new file mode 100644 index 0000000..52a9008 --- /dev/null +++ b/man7/utf8.7 @@ -0,0 +1 @@ +.so man7/utf-8.7 diff --git a/man7/vdso.7 b/man7/vdso.7 new file mode 100644 index 0000000..417b70e --- /dev/null +++ b/man7/vdso.7 @@ -0,0 +1,593 @@ +.\" Written by Mike Frysinger +.\" +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. +.\" %%%LICENSE_END +.\" +.\" Useful background: +.\" http://articles.manugarg.com/systemcallinlinux2_6.html +.\" https://lwn.net/Articles/446528/ +.\" http://www.linuxjournal.com/content/creating-vdso-colonels-other-chicken +.\" http://www.trilithium.com/johan/2005/08/linux-gate/ +.\" +.TH VDSO 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +vdso \- overview of the virtual ELF dynamic shared object +.SH SYNOPSIS +.B #include +.PP +.B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR); +.SH DESCRIPTION +The "vDSO" (virtual dynamic shared object) is a small shared library that +the kernel automatically maps into the +address space of all user-space applications. +Applications usually do not need to concern themselves with these details +as the vDSO is most commonly called by the C library. +This way you can code in the normal way using standard functions +and the C library will take care +of using any functionality that is available via the vDSO. +.PP +Why does the vDSO exist at all? +There are some system calls the kernel provides that +user-space code ends up using frequently, +to the point that such calls can dominate overall performance. +This is due both to the frequency of the call as well as the +context-switch overhead that results +from exiting user space and entering the kernel. +.PP +The rest of this documentation is geared toward the curious and/or +C library writers rather than general developers. +If you're trying to call the vDSO in your own application rather than using +the C library, you're most likely doing it wrong. +.SS Example background +Making system calls can be slow. +In x86 32-bit systems, you can trigger a software interrupt +.RI ( "int $0x80" ) +to tell the kernel you wish to make a system call. +However, this instruction is expensive: it goes through +the full interrupt-handling paths +in the processor's microcode as well as in the kernel. +Newer processors have faster (but backward incompatible) instructions to +initiate system calls. +Rather than require the C library to figure out if this functionality is +available at run time, +the C library can use functions provided by the kernel in +the vDSO. +.PP +Note that the terminology can be confusing. +On x86 systems, the vDSO function +used to determine the preferred method of making a system call is +named "__kernel_vsyscall", but on x86-64, +the term "vsyscall" also refers to an obsolete way to ask the kernel +what time it is or what CPU the caller is on. +.PP +One frequently used system call is +.BR gettimeofday (2). +This system call is called both directly by user-space applications +as well as indirectly by +the C library. +Think timestamps or timing loops or polling\(emall of these +frequently need to know what time it is right now. +This information is also not secret\(emany application in any +privilege mode (root or any unprivileged user) will get the same answer. +Thus the kernel arranges for the information required to answer +this question to be placed in memory the process can access. +Now a call to +.BR gettimeofday (2) +changes from a system call to a normal function +call and a few memory accesses. +.SS Finding the vDSO +The base address of the vDSO (if one exists) is passed by the kernel to +each program in the initial auxiliary vector (see +.BR getauxval (3)), +via the +.B AT_SYSINFO_EHDR +tag. +.PP +You must not assume the vDSO is mapped at any particular location in the +user's memory map. +The base address will usually be randomized at run time every time a new +process image is created (at +.BR execve (2) +time). +This is done for security reasons, +to prevent "return-to-libc" attacks. +.PP +For some architectures, there is also an +.B AT_SYSINFO +tag. +This is used only for locating the vsyscall entry point and is frequently +omitted or set to 0 (meaning it's not available). +This tag is a throwback to the initial vDSO work (see +.IR History +below) and its use should be avoided. +.SS File format +Since the vDSO is a fully formed ELF image, you can do symbol lookups on it. +This allows new symbols to be added with newer kernel releases, +and allows the C library to detect available functionality at +run time when running under different kernel versions. +Oftentimes the C library will do detection with the first call and then +cache the result for subsequent calls. +.PP +All symbols are also versioned (using the GNU version format). +This allows the kernel to update the function signature without breaking +backward compatibility. +This means changing the arguments that the function accepts as well as the +return value. +Thus, when looking up a symbol in the vDSO, +you must always include the version +to match the ABI you expect. +.PP +Typically the vDSO follows the naming convention of prefixing +all symbols with "__vdso_" or "__kernel_" +so as to distinguish them from other standard symbols. +For example, the "gettimeofday" function is named "__vdso_gettimeofday". +.PP +You use the standard C calling conventions when calling +any of these functions. +No need to worry about weird register or stack behavior. +.SH NOTES +.SS Source +When you compile the kernel, +it will automatically compile and link the vDSO code for you. +You will frequently find it under the architecture-specific directory: +.PP + find arch/$ARCH/ -name '*vdso*.so*' -o -name '*gate*.so*' +.\" +.SS vDSO names +The name of the vDSO varies across architectures. +It will often show up in things like glibc's +.BR ldd (1) +output. +The exact name should not matter to any code, so do not hardcode it. +.if t \{\ +.ft CW +\} +.TS +l l. +user ABI vDSO name +_ +aarch64 linux-vdso.so.1 +arm linux-vdso.so.1 +ia64 linux-gate.so.1 +mips linux-vdso.so.1 +ppc/32 linux-vdso32.so.1 +ppc/64 linux-vdso64.so.1 +s390 linux-vdso32.so.1 +s390x linux-vdso64.so.1 +sh linux-gate.so.1 +i386 linux-gate.so.1 +x86-64 linux-vdso.so.1 +x86/x32 linux-vdso.so.1 +.TE +.if t \{\ +.in +.ft P +\} +.SS strace(1) and the vDSO +When tracing systems calls with +.BR strace (1), +symbols (system calls) that are exported by the vDSO will +.I not +appear in the trace output. +.SH ARCHITECTURE-SPECIFIC NOTES +The subsections below provide architecture-specific notes +on the vDSO. +.PP +Note that the vDSO that is used is based on the ABI of your user-space code +and not the ABI of the kernel. +Thus, for example, +when you run an i386 32-bit ELF binary, +you'll get the same vDSO regardless of whether you run it under +an i386 32-bit kernel or under an x86-64 64-bit kernel. +Therefore, the name of the user-space ABI should be used to determine +which of the sections below is relevant. +.SS ARM functions +.\" See linux/arch/arm/vdso/vdso.lds.S +.\" Commit: 8512287a8165592466cb9cb347ba94892e9c56a5 +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__vdso_gettimeofday LINUX_2.6 (exported since Linux 4.1) +__vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1) +.TE +.if t \{\ +.in +.ft P +\} +.PP +.\" See linux/arch/arm/kernel/entry-armv.S +.\" See linux/Documentation/arm/kernel_user_helpers.txt +Additionally, the ARM port has a code page full of utility functions. +Since it's just a raw page of code, there is no ELF information for doing +symbol lookups or versioning. +It does provide support for different versions though. +.PP +For information on this code page, +it's best to refer to the kernel documentation +as it's extremely detailed and covers everything you need to know: +.IR Documentation/arm/kernel_user_helpers.txt . +.SS aarch64 functions +.\" See linux/arch/arm64/kernel/vdso/vdso.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_rt_sigreturn LINUX_2.6.39 +__kernel_gettimeofday LINUX_2.6.39 +__kernel_clock_gettime LINUX_2.6.39 +__kernel_clock_getres LINUX_2.6.39 +.TE +.if t \{\ +.in +.ft P +\} +.SS bfin (Blackfin) functions +.\" See linux/arch/blackfin/kernel/fixed_code.S +.\" See http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:fixed-code +As this CPU lacks a memory management unit (MMU), +it doesn't set up a vDSO in the normal sense. +Instead, it maps at boot time a few raw functions into +a fixed location in memory. +User-space applications then call directly into that region. +There is no provision for backward compatibility +beyond sniffing raw opcodes, +but as this is an embedded CPU, it can get away with things\(emsome of the +object formats it runs aren't even ELF based (they're bFLT/FLAT). +.PP +For information on this code page, +it's best to refer to the public documentation: +.br +http://docs.blackfin.uclinux.org/doku.php?id=linux\-kernel:fixed\-code +.SS mips functions +.\" See linux/arch/mips/vdso/vdso.ld.S +.PP +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_gettimeofday LINUX_2.6 (exported since Linux 4.4) +__kernel_clock_gettime LINUX_2.6 (exported since Linux 4.4) +.TE +.if t \{\ +.in +.ft P +\} +.SS ia64 (Itanium) functions +.\" See linux/arch/ia64/kernel/gate.lds.S +.\" Also linux/arch/ia64/kernel/fsys.S and linux/Documentation/ia64/fsys.txt +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_sigtramp LINUX_2.5 +__kernel_syscall_via_break LINUX_2.5 +__kernel_syscall_via_epc LINUX_2.5 +.TE +.if t \{\ +.in +.ft P +\} +.PP +The Itanium port is somewhat tricky. +In addition to the vDSO above, it also has "light-weight system calls" +(also known as "fast syscalls" or "fsys"). +You can invoke these via the +.I __kernel_syscall_via_epc +vDSO helper. +The system calls listed here have the same semantics as if you called them +directly via +.BR syscall (2), +so refer to the relevant +documentation for each. +The table below lists the functions available via this mechanism. +.if t \{\ +.ft CW +\} +.TS +l. +function +_ +clock_gettime +getcpu +getpid +getppid +gettimeofday +set_tid_address +.TE +.if t \{\ +.in +.ft P +\} +.SS parisc (hppa) functions +.\" See linux/arch/parisc/kernel/syscall.S +.\" See linux/Documentation/parisc/registers +The parisc port has a code page full of utility functions +called a gateway page. +Rather than use the normal ELF auxiliary vector approach, +it passes the address of +the page to the process via the SR2 register. +The permissions on the page are such that merely executing those addresses +automatically executes with kernel privileges and not in user space. +This is done to match the way HP-UX works. +.PP +Since it's just a raw page of code, there is no ELF information for doing +symbol lookups or versioning. +Simply call into the appropriate offset via the branch instruction, +for example: +.PP + ble (%sr2, %r0) +.if t \{\ +.ft CW +\} +.TS +l l. +offset function +_ +00b0 lws_entry +00e0 set_thread_pointer +0100 linux_gateway_entry (syscall) +0268 syscall_nosys +0274 tracesys +0324 tracesys_next +0368 tracesys_exit +03a0 tracesys_sigexit +03b8 lws_start +03dc lws_exit_nosys +03e0 lws_exit +03e4 lws_compare_and_swap64 +03e8 lws_compare_and_swap +0404 cas_wouldblock +0410 cas_action +.TE +.if t \{\ +.in +.ft P +\} +.SS ppc/32 functions +.\" See linux/arch/powerpc/kernel/vdso32/vdso32.lds.S +The table below lists the symbols exported by the vDSO. +The functions marked with a +.I * +are available only when the kernel is +a PowerPC64 (64-bit) kernel. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_clock_getres LINUX_2.6.15 +__kernel_clock_gettime LINUX_2.6.15 +__kernel_datapage_offset LINUX_2.6.15 +__kernel_get_syscall_map LINUX_2.6.15 +__kernel_get_tbfreq LINUX_2.6.15 +__kernel_getcpu \fI*\fR LINUX_2.6.15 +__kernel_gettimeofday LINUX_2.6.15 +__kernel_sigtramp_rt32 LINUX_2.6.15 +__kernel_sigtramp32 LINUX_2.6.15 +__kernel_sync_dicache LINUX_2.6.15 +__kernel_sync_dicache_p5 LINUX_2.6.15 +.TE +.if t \{\ +.in +.ft P +\} +.PP +The +.B CLOCK_REALTIME_COARSE +and +.B CLOCK_MONOTONIC_COARSE +clocks are +.I not +supported by the +.I __kernel_clock_getres +and +.I __kernel_clock_gettime +interfaces; +the kernel falls back to the real system call. +.SS ppc/64 functions +.\" See linux/arch/powerpc/kernel/vdso64/vdso64.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_clock_getres LINUX_2.6.15 +__kernel_clock_gettime LINUX_2.6.15 +__kernel_datapage_offset LINUX_2.6.15 +__kernel_get_syscall_map LINUX_2.6.15 +__kernel_get_tbfreq LINUX_2.6.15 +__kernel_getcpu LINUX_2.6.15 +__kernel_gettimeofday LINUX_2.6.15 +__kernel_sigtramp_rt64 LINUX_2.6.15 +__kernel_sync_dicache LINUX_2.6.15 +__kernel_sync_dicache_p5 LINUX_2.6.15 +.TE +.if t \{\ +.in +.ft P +\} +.PP +The +.B CLOCK_REALTIME_COARSE +and +.B CLOCK_MONOTONIC_COARSE +clocks are +.I not +supported by the +.I __kernel_clock_getres +and +.I __kernel_clock_gettime +interfaces; +the kernel falls back to the real system call. +.SS s390 functions +.\" See linux/arch/s390/kernel/vdso32/vdso32.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_clock_getres LINUX_2.6.29 +__kernel_clock_gettime LINUX_2.6.29 +__kernel_gettimeofday LINUX_2.6.29 +.TE +.if t \{\ +.in +.ft P +\} +.SS s390x functions +.\" See linux/arch/s390/kernel/vdso64/vdso64.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_clock_getres LINUX_2.6.29 +__kernel_clock_gettime LINUX_2.6.29 +__kernel_gettimeofday LINUX_2.6.29 +.TE +.if t \{\ +.in +.ft P +\} +.SS sh (SuperH) functions +.\" See linux/arch/sh/kernel/vsyscall/vsyscall.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_rt_sigreturn LINUX_2.6 +__kernel_sigreturn LINUX_2.6 +__kernel_vsyscall LINUX_2.6 +.TE +.if t \{\ +.in +.ft P +\} +.SS i386 functions +.\" See linux/arch/x86/vdso/vdso32/vdso32.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_sigreturn LINUX_2.5 +__kernel_rt_sigreturn LINUX_2.5 +__kernel_vsyscall LINUX_2.5 +.\" Added in 7a59ed415f5b57469e22e41fc4188d5399e0b194 and updated +.\" in 37c975545ec63320789962bf307f000f08fabd48. +__vdso_clock_gettime LINUX_2.6 (exported since Linux 3.15) +__vdso_gettimeofday LINUX_2.6 (exported since Linux 3.15) +__vdso_time LINUX_2.6 (exported since Linux 3.15) +.TE +.if t \{\ +.in +.ft P +\} +.SS x86-64 functions +.\" See linux/arch/x86/vdso/vdso.lds.S +The table below lists the symbols exported by the vDSO. +All of these symbols are also available without the "__vdso_" prefix, but +you should ignore those and stick to the names below. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__vdso_clock_gettime LINUX_2.6 +__vdso_getcpu LINUX_2.6 +__vdso_gettimeofday LINUX_2.6 +__vdso_time LINUX_2.6 +.TE +.if t \{\ +.in +.ft P +\} +.SS x86/x32 functions +.\" See linux/arch/x86/vdso/vdso32.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__vdso_clock_gettime LINUX_2.6 +__vdso_getcpu LINUX_2.6 +__vdso_gettimeofday LINUX_2.6 +__vdso_time LINUX_2.6 +.TE +.if t \{\ +.in +.ft P +\} +.SS History +The vDSO was originally just a single function\(emthe vsyscall. +In older kernels, you might see that name +in a process's memory map rather than "vdso". +Over time, people realized that this mechanism +was a great way to pass more functionality +to user space, so it was reconceived as a vDSO in the current format. +.SH SEE ALSO +.BR syscalls (2), +.BR getauxval (3), +.BR proc (5) +.PP +The documents, examples, and source code in the Linux source code tree: +.PP +.in +4n +.EX +Documentation/ABI/stable/vdso +Documentation/ia64/fsys.txt +Documentation/vDSO/* (includes examples of using the vDSO) + +find arch/ -iname '*vdso*' -o -iname '*gate*' +.EE +.in +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/vsock.7 b/man7/vsock.7 new file mode 100644 index 0000000..5dc27d1 --- /dev/null +++ b/man7/vsock.7 @@ -0,0 +1,234 @@ +.\" Copyright (C) 2018, Stefan Hajnoczi +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH VSOCK 7 2017-11-30 "Linux" "Linux Programmer's Manual" +.SH NAME +vsock \- Linux VSOCK address family +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);" +.br +.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);" +.SH DESCRIPTION +The VSOCK address family facilitates communication between virtual machines and +the host they are running on. +This address family is used by guest agents and +hypervisor services that need a communications channel that is independent of +virtual machine network configuration. +.PP +Valid socket types are +.B SOCK_STREAM +and +.BR SOCK_DGRAM . +.B SOCK_STREAM +provides connection-oriented byte streams with guaranteed, in-order delivery. +.B SOCK_DGRAM +provides a connectionless datagram packet service with best-effort delivery and +best-effort ordering. +Availability of these socket types is dependent on the +underlying hypervisor. +.PP +A new socket is created with +.PP +.in +4n +.EX +socket(AF_VSOCK, socket_type, 0); +.EE +.in +.PP +When a process wants to establish a connection, it calls +.BR connect (2) +with a given destination socket address. +The socket is automatically bound to a free port if unbound. +.PP +A process can listen for incoming connections by first binding to a socket +address using +.BR bind (2) +and then calling +.BR listen (2). +.PP +Data is transmitted using the +.BR send (2) +or +.BR write (2) +families of system calls and data is received using the +.BR recv (2) +or +.BR read (2) +families of system calls. +.SS Address format +A socket address is defined as a combination of a 32-bit Context Identifier +(CID) and a 32-bit port number. +The CID identifies the source or destination, +which is either a virtual machine or the host. +The port number differentiates between multiple services running on +a single machine. +.PP +.in +4n +.EX +struct sockaddr_vm { + sa_family_t svm_family; /* Address family: AF_VSOCK */ + unsigned short svm_reserved1; + unsigned int svm_port; /* Port # in host byte order */ + unsigned int svm_cid; /* Address in host byte order */ +}; +.EE +.in +.PP +.I svm_family +is always set to +.BR AF_VSOCK . +.I svm_reserved1 +is always set to 0. +.I svm_port +contains the port number in host byte order. +The port numbers below 1024 are called +.IR "privileged ports" . +Only a process with the +.B CAP_NET_BIND_SERVICE +capability may +.BR bind (2) +to these port numbers. +.PP +There are several special addresses: +.B VMADDR_CID_ANY +(\-1U) +means any address for binding; +.B VMADDR_CID_HYPERVISOR +(0) is reserved for services built into the hypervisor; +.B VMADDR_CID_RESERVED +(1) must not be used; +.B VMADDR_CID_HOST +(2) +is the well-known address of the host. +.PP +The special constant +.B VMADDR_PORT_ANY +(\-1U) +means any port number for binding. +.SS Live migration +Sockets are affected by live migration of virtual machines. +Connected +.B SOCK_STREAM +sockets become disconnected when the virtual machine migrates to a new host. +Applications must reconnect when this happens. +.PP +The local CID may change across live migration if the old CID is +not available on the new host. +Bound sockets are automatically updated to the new CID. +.SS Ioctls +.TP +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID +Get the CID of the local machine. +The argument is a pointer to an +.IR "unsigned int" . +.IP +.in +4n +.EX +ioctl(socket, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid); +.EE +.in +.IP +Consider using +.B VMADDR_CID_ANY +when binding instead of getting the local CID with +.BR IOCTL_VM_SOCKETS_GET_LOCAL_CID . +.SH ERRORS +.TP +.B EACCES +Unable to bind to a privileged port without the +.B CAP_NET_BIND_SERVICE +capability. +.TP +.B EADDRINUSE +Unable to bind to a port that is already in use. +.TP +.B EADDRNOTAVAIL +Unable to find a free port for binding or unable to bind to a nonlocal CID. +.TP +.B EINVAL +Invalid parameters. +This includes: +attempting to bind a socket that is already bound, providing an invalid struct +.IR sockaddr_vm , +and other input validation errors. +.TP +.B ENOPROTOOPT +Invalid socket option in +.BR setsockopt (2) +or +.BR getsockopt (2). +.TP +.B ENOTCONN +Unable to perform operation on an unconnected socket. +.TP +.B EOPNOTSUPP +Operation not supported. +This includes: +the +.B MSG_OOB +flag that is not implemented for the +.BR send (2) +family of syscalls and +.B MSG_PEEK +for the +.BR recv (2) +family of syscalls. +.TP +.B EPROTONOSUPPORT +Invalid socket protocol number. +The protocol should always be 0. +.TP +.B ESOCKTNOSUPPORT +Unsupported socket type in +.BR socket (2). +Only +.B SOCK_STREAM +and +.B SOCK_DGRAM +are valid. +.SH VERSIONS +Support for VMware (VMCI) has been available since Linux 3.9. +KVM (virtio) is supported since Linux 4.8. +Hyper-V is supported since Linux 4.14. +.SH SEE ALSO +.BR bind (2), +.BR connect (2), +.BR listen (2), +.BR recv (2), +.BR send (2), +.BR socket (2), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/x25.7 b/man7/x25.7 new file mode 100644 index 0000000..1ffee2b --- /dev/null +++ b/man7/x25.7 @@ -0,0 +1,135 @@ +.\" This man page is Copyright (C) 1998 Heiner Eisen. +.\" +.\" %%%LICENSE_START(VERBATIM_ONE_PARA) +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" %%%LICENSE_END +.\" +.\" $Id: x25.7,v 1.4 1999/05/18 10:35:12 freitag Exp $ +.\" +.TH X25 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +x25 \- ITU-T X.25 / ISO-8208 protocol interface. +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B x25_socket = socket(AF_X25, SOCK_SEQPACKET, 0); +.SH DESCRIPTION +X25 sockets provide an interface to the X.25 packet layer protocol. +This allows applications to +communicate over a public X.25 data network as standardized by +International Telecommunication Union's recommendation X.25 +(X.25 DTE-DCE mode). +X25 sockets can also be used for communication +without an intermediate X.25 network (X.25 DTE-DTE mode) as described +in ISO-8208. +.PP +Message boundaries are preserved \(em a +.BR read (2) +from a socket will +retrieve the same chunk of data as output with the corresponding +.BR write (2) +to the peer socket. +When necessary, the kernel takes care +of segmenting and reassembling long messages by means of +the X.25 M-bit. +There is no hard-coded upper limit for the +message size. +However, reassembling of a long message might fail if +there is a temporary lack of system resources or when other constraints +(such as socket memory or buffer size limits) become effective. +If that +occurs, the X.25 connection will be reset. +.SS Socket addresses +The +.B AF_X25 +socket address family uses the +.I struct sockaddr_x25 +for representing network addresses as defined in ITU-T +recommendation X.121. +.PP +.in +4n +.EX +struct sockaddr_x25 { + sa_family_t sx25_family; /* must be AF_X25 */ + x25_address sx25_addr; /* X.121 Address */ +}; +.EE +.in +.PP +.I sx25_addr +contains a char array +.I x25_addr[] +to be interpreted as a null-terminated string. +.I sx25_addr.x25_addr[] +consists of up to 15 (not counting the terminating null byte) ASCII +characters forming the X.121 address. +Only the decimal digit characters from \(aq0\(aq to \(aq9\(aq are allowed. +.SS Socket options +The following X.25-specific socket options can be set by using +.BR setsockopt (2) +and read with +.BR getsockopt (2) +with the +.I level +argument set to +.BR SOL_X25 . +.TP +.B X25_QBITINCL +Controls whether the X.25 Q-bit (Qualified Data Bit) is accessible by the +user. +It expects an integer argument. +If set to 0 (default), +the Q-bit is never set for outgoing packets and the Q-bit of incoming +packets is ignored. +If set to 1, an additional first byte is prepended +to each message read from or written to the socket. +For data read from +the socket, a 0 first byte indicates that the Q-bits of the corresponding +incoming data packets were not set. +A first byte with value 1 indicates +that the Q-bit of the corresponding incoming data packets was set. +If the first byte of the data written to the socket is 1, the Q-bit of the +corresponding outgoing data packets will be set. +If the first byte is 0, +the Q-bit will not be set. +.SH VERSIONS +The AF_X25 protocol family is a new feature of Linux 2.2. +.SH BUGS +Plenty, as the X.25 PLP implementation is +.BR CONFIG_EXPERIMENTAL . +.PP +This man page is incomplete. +.PP +There is no dedicated application programmer's header file yet; +you need to include the kernel header file +.IR . +.B CONFIG_EXPERIMENTAL +might also imply that future versions of the +interface are not binary compatible. +.PP +X.25 N-Reset events are not propagated to the user process yet. +Thus, +if a reset occurred, data might be lost without notice. +.SH SEE ALSO +.BR socket (2), +.BR socket (7) +.PP +Jonathan Simon Naylor: +\(lqThe Re-Analysis and Re-Implementation of X.25.\(rq +The URL is +.UR ftp://ftp.pspt.fi\:/pub\:/ham\:/linux\:/ax25\:/x25doc.tgz +.UE . +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man7/xattr.7 b/man7/xattr.7 new file mode 100644 index 0000000..fa67ab8 --- /dev/null +++ b/man7/xattr.7 @@ -0,0 +1,206 @@ +.\" Extended attributes manual page +.\" +.\" Copyright (C) 2000, 2002, 2007 Andreas Gruenbacher +.\" Copyright (C) 2001, 2002, 2004, 2007 Silicon Graphics, Inc. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual. If not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH XATTR 7 2017-09-15 "Linux" "Linux Programmer's Manual" +.SH NAME +xattr \- Extended attributes +.SH DESCRIPTION +Extended attributes are name:value pairs associated permanently with +files and directories, similar to the environment strings associated +with a process. +An attribute may be defined or undefined. +If it is defined, its value may be empty or non-empty. +.PP +Extended attributes are extensions to the normal attributes which are +associated with all inodes in the system (i.e., the +.BR stat (2) +data). +They are often used to provide additional functionality +to a filesystem\(emfor example, additional security features such as +Access Control Lists (ACLs) may be implemented using extended attributes. +.PP +Users with search access to a file or directory may use +.BR listxattr (2) +to retrieve a list of attribute names defined for that file or directory. +.PP +Extended attributes are accessed as atomic objects. +Reading +.RB ( getxattr (2)) +retrieves the whole value of an attribute and stores it in a buffer. +Writing +.RB ( setxattr (2)) +replaces any previous value with the new value. +.PP +Space consumed for extended attributes may be counted towards the disk quotas +of the file owner and file group. +.SS Extended attribute namespaces +Attribute names are null-terminated strings. +The attribute name is always specified in the fully qualified +.IR namespace.attribute +form, for example, +.IR user.mime_type , +.IR trusted.md5sum , +.IR system.posix_acl_access , +or +.IR security.selinux . +.PP +The namespace mechanism is used to define different classes of extended +attributes. +These different classes exist for several reasons; +for example, the permissions +and capabilities required for manipulating extended attributes of one +namespace may differ to another. +.PP +Currently, the +.IR security , +.IR system , +.IR trusted , +and +.IR user +extended attribute classes are defined as described below. +Additional classes may be added in the future. +.SS Extended security attributes +The security attribute namespace is used by kernel security modules, +such as Security Enhanced Linux, and also to implement file capabilities (see +.BR capabilities (7)). +Read and write access permissions to security attributes depend on the +policy implemented for each security attribute by the security module. +When no security module is loaded, all processes have read access to +extended security attributes, and write access is limited to processes +that have the +.B CAP_SYS_ADMIN +capability. +.SS Extended system attributes +Extended system attributes are used by the kernel to store system +objects such as Access Control Lists. +Read and write +access permissions to system attributes depend on the policy implemented +for each system attribute implemented by filesystems in the kernel. +.SS Trusted extended attributes +Trusted extended attributes are visible and accessible only to processes that +have the +.B CAP_SYS_ADMIN +capability. +Attributes in this class are used to implement mechanisms in user +space (i.e., outside the kernel) which keep information in extended attributes +to which ordinary processes should not have access. +.SS Extended user attributes +Extended user attributes may be assigned to files and directories for +storing arbitrary additional information such as the mime type, +character set or encoding of a file. +The access permissions for user +attributes are defined by the file permission bits: +read permission is required to retrieve the attribute value, +and writer permission is required to change it. +.PP +The file permission bits of regular files and directories are +interpreted differently from the file permission bits of special files +and symbolic links. +For regular files and directories the file +permission bits define access to the file's contents, while for device special +files they define access to the device described by the special file. +The file permissions of symbolic links are not used in access checks. +These differences would allow users to consume filesystem resources in +a way not controllable by disk quotas for group or world writable +special files and directories. +.PP +For this reason, +extended user attributes are allowed only for regular files and directories, +and access to extended user attributes is restricted to the +owner and to users with appropriate capabilities for directories with the +sticky bit set (see the +.BR chmod (1) +manual page for an explanation of the sticky bit). +.SS Filesystem differences +The kernel and the filesystem may place limits on the maximum number +and size of extended attributes that can be associated with a file. +The VFS imposes limitations that an attribute names is limited to 255 bytes +and an attribute value is limited to 64\ kB. +The list of attribute names that +can be returned is also limited to 64\ kB +(see BUGS in +.BR listxattr (2)). +.PP +Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), +require the filesystem to be mounted with the +.B user_xattr +mount option in order for extended user attributes to be used. +.PP +In the current ext2, ext3, and ext4 filesystem implementations, +the total bytes used by the names and values of all of a file's +extended attributes must fit in a single filesystem block (1024, 2048 +or 4096 bytes, depending on the block size specified when the +filesystem was created). +.PP +In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no +practical limit on the number of extended attributes +associated with a file, and the algorithms used to store extended +attribute information on disk are scalable. +.PP +In the JFS, XFS, and Reiserfs filesystem implementations, +the limit on bytes used in an EA value is the ceiling imposed by the VFS. +.PP +In the Btrfs filesystem implementation, +the total bytes used for the name, value, and implementation overhead bytes +is limited to the filesystem +.I nodesize +value (16\ kB by default). +.SH CONFORMING TO +Extended attributes are not specified in POSIX.1, but some other systems +(e.g., the BSDs and Solaris) provide a similar feature. +.SH NOTES +Since the filesystems on which extended attributes are stored might also +be used on architectures with a different byte order and machine word +size, care should be taken to store attribute values in an +architecture-independent format. +.PP +This page was formerly named +.BR attr (5). +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@bestbits.at > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR ioctl_iflags (2), +.BR listxattr (2), +.BR removexattr (2), +.BR setxattr (2), +.BR acl (5), +.BR capabilities (7) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/iconvconfig.8 b/man8/iconvconfig.8 new file mode 100644 index 0000000..457d52d --- /dev/null +++ b/man8/iconvconfig.8 @@ -0,0 +1,112 @@ +'\" t -*- coding: UTF-8 -*- +.\" +.\" Copyright (C) 2014 Marko Myllynen +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.TH ICONVCONFIG 8 2018-02-02 "GNU" "Linux System Administration" +.SH NAME +iconvconfig \- create iconv module configuration cache +.SH SYNOPSIS +.B iconvconfig +.RI [ options ] +.RI [ directory ]... +.SH DESCRIPTION +The +.BR iconv (3) +function internally uses +.I gconv +modules to convert to and from a character set. +A configuration file is used to determine the needed modules +for a conversion. +Loading and parsing such a configuration file would slow down +programs that use +.BR iconv (3), +so a caching mechanism is employed. +.PP +The +.B iconvconfig +program reads iconv module configuration files and writes +a fast-loading gconv module configuration cache file. +.PP +In addition to the system provided gconv modules, the user can specify +custom gconv module directories with the environment variable +.BR GCONV_PATH . +However, iconv module configuration caching is used only when +the environment variable +.BR GCONV_PATH +is not set. +.SH OPTIONS +.TP +.B "\-\-nostdlib" +Do not search the system default gconv directory, +only the directories provided on the command line. +.TP +.BI \-o " outputfile" ", \-\-output=" outputfile +Use +.I outputfile +for output instead of the system default cache location. +.TP +.BI \-\-prefix= pathname +Set the prefix to be prepended to the system pathnames. +See FILES, below. +By default, the prefix is empty. +Setting the prefix to +.IR foo , +the gconv module configuration would be read from +.IR foo/usr/lib/gconv/gconv-modules +and the cache would be written to +.IR foo/usr/lib/gconv/gconv-modules.cache . +.TP +.BR \-? ", " \-\-help +Print a usage summary and exit. +.TP +.B "\-\-usage" +Print a short usage summary and exit. +.TP +.BR \-V ", " \-\-version +Print the version number, license, and disclaimer of warranty for +.BR iconv . +.SH EXIT STATUS +Zero on success, nonzero on errors. +.SH FILES +.TP +.I /usr/lib/gconv +Usual default gconv module path. +.TP +.I /usr/lib/gconv/gconv-modules +Usual system default gconv module configuration file. +.TP +.I /usr/lib/gconv/gconv-modules.cache +Usual system gconv module configuration cache. +.SH SEE ALSO +.BR iconv (1), +.BR iconv (3) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/intro.8 b/man8/intro.8 new file mode 100644 index 0000000..6a309aa --- /dev/null +++ b/man8/intro.8 @@ -0,0 +1,57 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" and Copyright (C) 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified Sat Jul 24 17:35:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" 2007-10-23 mtk: minor rewrites, and added paragraph on exit status +.\" +.TH INTRO 8 2007-10-23 "Linux" "Linux Programmer's Manual" +.SH NAME +intro \- introduction to administration and privileged commands +.SH DESCRIPTION +Section 8 of the manual describes commands +which either can be or are used only by the superuser, +like system-administration commands, daemons, +and hardware-related commands. +.PP +As with the commands described in Section 1, the commands described +in this section terminate with an exit status that indicates +whether the command succeeded or failed. +See +.BR intro (1) +for more information. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/ld-linux.8 b/man8/ld-linux.8 new file mode 100644 index 0000000..c575620 --- /dev/null +++ b/man8/ld-linux.8 @@ -0,0 +1 @@ +.so man8/ld.so.8 diff --git a/man8/ld-linux.so.8 b/man8/ld-linux.so.8 new file mode 100644 index 0000000..c575620 --- /dev/null +++ b/man8/ld-linux.so.8 @@ -0,0 +1 @@ +.so man8/ld.so.8 diff --git a/man8/ld.so.8 b/man8/ld.so.8 new file mode 100644 index 0000000..f9c3ac8 --- /dev/null +++ b/man8/ld.so.8 @@ -0,0 +1,737 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This is in the public domain +.\" %%%LICENSE_END +.\" +.TH LD.SO 8 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +ld.so, ld\-linux.so \- dynamic linker/loader +.SH SYNOPSIS +The dynamic linker can be run either indirectly by running some +dynamically linked program or shared object +(in which case no command-line options +to the dynamic linker can be passed and, in the ELF case, the dynamic linker +which is stored in the +.B .interp +section of the program is executed) or directly by running: +.PP +.I /lib/ld\-linux.so.* +[OPTIONS] [PROGRAM [ARGUMENTS]] +.SH DESCRIPTION +The programs +.B ld.so +and +.B ld\-linux.so* +find and load the shared objects (shared libraries) needed by a program, +prepare the program to run, and then run it. +.PP +Linux binaries require dynamic linking (linking at run time) +unless the +.B \-static +option was given to +.BR ld (1) +during compilation. +.PP +The program +.B ld.so +handles a.out binaries, a format used long ago; +.B ld\-linux.so* +(\fI/lib/ld\-linux.so.1\fP for libc5, \fI/lib/ld\-linux.so.2\fP for glibc2) +handles ELF, +which everybody has been using for years now. +Otherwise, both have the same behavior, and use the same +support files and programs as +.BR ldd (1), +.BR ldconfig (8), +and +.IR /etc/ld.so.conf . +.PP +When resolving shared object dependencies, +the dynamic linker first inspects each dependency +string to see if it contains a slash (this can occur if +a shared object pathname containing slashes was specified at link time). +If a slash is found, then the dependency string is interpreted as +a (relative or absolute) pathname, +and the shared object is loaded using that pathname. +.PP +If a shared object dependency does not contain a slash, +then it is searched for in the following order: +.IP o 3 +Using the directories specified in the +DT_RPATH dynamic section attribute +of the binary if present and DT_RUNPATH attribute does not exist. +Use of DT_RPATH is deprecated. +.IP o +Using the environment variable +.BR LD_LIBRARY_PATH +(unless the executable is being run in secure-execution mode; see below). +in which case it is ignored. +.IP o +Using the directories specified in the +DT_RUNPATH dynamic section attribute +of the binary if present. +Such directories are searched only to +find those objects required by DT_NEEDED (direct dependencies) entries +and do not apply to those objects' children, +which must themselves have their own DT_RUNPATH entries. +This is unlike DT_RPATH, which is applied +to searches for all children in the dependency tree. +.IP o +From the cache file +.IR /etc/ld.so.cache , +which contains a compiled list of candidate shared objects previously found +in the augmented library path. +If, however, the binary was linked with the +.B \-z nodeflib +linker option, shared objects in the default paths are skipped. +Shared objects installed in hardware capability directories (see below) +are preferred to other shared objects. +.IP o +In the default path +.IR /lib , +and then +.IR /usr/lib . +(On some 64-bit architectures, the default paths for 64-bit shared objects are +.IR /lib64 , +and then +.IR /usr/lib64 .) +If the binary was linked with the +.B \-z nodeflib +linker option, this step is skipped. +.SS Rpath token expansion +.PP +The dynamic linker +understands certain token strings in an rpath specification +(DT_RPATH or DT_RUNPATH). +Those strings are substituted as follows: +.TP +.IR $ORIGIN " (or equivalently " ${ORIGIN} ) +This expands to +the directory containing the program or shared object. +Thus, an application located in +.I somedir/app +could be compiled with +.IP + gcc \-Wl,\-rpath,\(aq$ORIGIN/../lib\(aq +.IP +so that it finds an associated shared object in +.I somedir/lib +no matter where +.I somedir +is located in the directory hierarchy. +This facilitates the creation of "turn-key" applications that +do not need to be installed into special directories, +but can instead be unpacked into any directory +and still find their own shared objects. +.TP +.IR $LIB " (or equivalently " ${LIB} ) +This expands to +.I lib +or +.I lib64 +depending on the architecture +(e.g., on x86-64, it expands to +.IR lib64 +and +on x86-32, it expands to +.IR lib ). +.TP +.IR $PLATFORM " (or equivalently " ${PLATFORM} ) +This expands to a string corresponding to the processor type +of the host system (e.g., "x86_64"). +On some architectures, the Linux kernel doesn't provide a platform +string to the dynamic linker. +The value of this string is taken from the +.BR AT_PLATFORM +value in the auxiliary vector (see +.BR getauxval (3)). +.\" To get an idea of the places that $PLATFORM would match, +.\" look at the output of the following: +.\" +.\" mkdir /tmp/d +.\" LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d +.\" +.\" ld.so lets names be abbreviated, so $O will work for $ORIGIN; +.\" Don't do this!! +.SH OPTIONS +.TP +.B \-\-list +List all dependencies and how they are resolved. +.TP +.B \-\-verify +Verify that program is dynamically linked and this dynamic linker can handle +it. +.TP +.B \-\-inhibit\-cache +Do not use +.IR /etc/ld.so.cache . +.TP +.BI \-\-library\-path " path" +Use +.I path +instead of +.B LD_LIBRARY_PATH +environment variable setting (see below). +The names +.IR ORIGIN , +.IR LIB , +and +.IR PLATFORM +are interpreted as for the +.BR LD_LIBRARY_PATH +environment variable. +.TP +.BI \-\-inhibit\-rpath " list" +Ignore RPATH and RUNPATH information in object names in +.IR list . +This option is ignored when running in secure-execution mode (see below). +.TP +.BI \-\-audit " list" +Use objects named in +.I list +as auditors. +.SH ENVIRONMENT +Various environment variables influence the operation of the dynamic linker. +.\" +.SS Secure-execution mode +For security reasons, +the effects of some environment variables are voided or modified if +the dynamic linker determines that the binary should be +run in secure-execution mode. +(For details, see the discussion of individual environment variables below.) +A binary is executed in secure-execution mode if the +.B AT_SECURE +entry in the auxiliary vector (see +.BR getauxval (3)) +has a nonzero value. +This entry may have a nonzero value for various reasons, including: +.IP * 3 +The process's real and effective user IDs differ, +or the real and effective group IDs differ. +This typically occurs as a result of executing +a set-user-ID or set-group-ID program. +.IP * +A process with a non-root user ID executed a binary that +conferred capabilities to the process. +.IP * +A nonzero value may have been set by a Linux Security Module. +.\" +.SS Environment variables +Among the more important environment variables are the following: +.TP +.BR LD_ASSUME_KERNEL " (since glibc 2.2.3)" +Each shared object can inform the dynamic linker of the minimum kernel ABI +version that it requires. +(This requirement is encoded in an ELF note section that is viewable via +.IR "readelf\ \-n" +as a section labeled +.BR NT_GNU_ABI_TAG .) +At run time, +the dynamic linker determines the ABI version of the running kernel and +will reject loading shared objects that specify minimum ABI versions +that exceed that ABI version. +.IP +.BR LD_ASSUME_KERNEL +can be used to +cause the dynamic linker to assume that it is running on a system with +a different kernel ABI version. +For example, the following command line causes the +dynamic linker to assume it is running on Linux 2.2.5 when loading +the shared objects required by +.IR myprog : +.IP +.in +4n +.EX +$ \fBLD_ASSUME_KERNEL=2.2.5 ./myprog\fP +.EE +.in +.IP +On systems that provide multiple versions of a shared object +(in different directories in the search path) that have +different minimum kernel ABI version requirements, +.BR LD_ASSUME_KERNEL +can be used to select the version of the object that is used +(dependent on the directory search order). +.IP +Historically, the most common use of the +.BR LD_ASSUME_KERNEL +feature was to manually select the older +LinuxThreads POSIX threads implementation on systems that provided both +LinuxThreads and NPTL +(which latter was typically the default on such systems); +see +.BR pthreads (7). +.TP +.BR LD_BIND_NOW " (since glibc 2.1.1)" +If set to a nonempty string, +causes the dynamic linker to resolve all symbols +at program startup instead of deferring function call resolution to the point +when they are first referenced. +This is useful when using a debugger. +.TP +.B LD_LIBRARY_PATH +A list of directories in which to search for +ELF libraries at execution time. +The items in the list are separated by either colons or semicolons. +Similar to the +.B PATH +environment variable. +.IP +This variable is ignored in secure-execution mode. +.IP +Within the pathnames specified in +.BR LD_LIBRARY_PATH , +the dynamic linker expands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.IR $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Rpath token expansion" . +Thus, for example, +the following would cause a library to be searched for in either the +.I lib +or +.I lib64 +subdirectory below the directory containing the program to be executed: +.IP +.in +4n +.EX +$ \fBLD_LIBRARY_PATH='$ORIGIN/$LIB' prog\fP +.EE +.in +.IP +(Note the use of single quotes, which prevent expansion of +.I $ORIGIN +and +.I $LIB +as shell variables!) +.TP +.B LD_PRELOAD +A list of additional, user-specified, ELF shared +objects to be loaded before all others. +The items of the list can be separated by spaces or colons. +This can be used to selectively override functions in other shared objects. +The objects are searched for using the rules given under DESCRIPTION. +.IP +In secure-execution mode, +preload pathnames containing slashes are ignored. +Furthermore, shared objects are preloaded only +from the standard search directories and only +if they have set-user-ID mode bit enabled (which is not typical). +.IP +Within the names specified in the +.BR LD_PRELOAD +list, the dynamic linker understands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.IR $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Rpath token expansion" . +(See also the discussion of quoting under the description of +.BR LD_LIBRARY_PATH .) +.\" Tested with the following: +.\" +.\" LD_PRELOAD='$LIB/libmod.so' LD_LIBRARY_PATH=. ./prog +.\" +.\" which will preload the libmod.so in 'lib' or 'lib64', using it +.\" in preference to the version in '.'. +.TP +.BR LD_TRACE_LOADED_OBJECTS +If set (to any value), causes the program to list its dynamic +dependencies, as if run by +.BR ldd (1), +instead of running normally. +.PP +Then there are lots of more or less obscure variables, +many obsolete or only for internal use. +.TP +.BR LD_AUDIT " (since glibc 2.4)" +A colon-separated list of user-specified, ELF shared objects +to be loaded before all others in a separate linker namespace +(i.e., one that does not intrude upon the normal symbol bindings that +would occur in the process). +These objects can be used to audit the operation of the dynamic linker. +.IP +.B LD_AUDIT +is ignored in secure-execution mode. +.IP +The dynamic linker will notify the audit +shared objects at so-called auditing checkpoints\(emfor example, +loading a new shared object, resolving a symbol, +or calling a symbol from another shared object\(emby +calling an appropriate function within the audit shared object. +For details, see +.BR rtld-audit (7). +The auditing interface is largely compatible with that provided on Solaris, +as described in its +.IR "Linker and Libraries Guide" , +in the chapter +.IR "Runtime Linker Auditing Interface" . +.IP +Within the names specified in the +.BR LD_AUDIT +list, the dynamic linker understands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.IR $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Rpath token expansion" . +(See also the discussion of quoting under the description of +.BR LD_LIBRARY_PATH .) +.IP +Since glibc 2.13, +.\" commit 8e9f92e9d5d7737afdacf79b76d98c4c42980508 +in secure-execution mode, +names in the audit list that contain slashes are ignored, +and only shared objects in the standard search directories that +have the set-user-ID mode bit enabled are loaded. +.TP +.BR LD_BIND_NOT " (since glibc 2.1.95)" +If this environment variable is set to a nonempty string, +do not update the GOT (global offset table) and PLT (procedure linkage table) +after resolving a function symbol. +By combining the use of this variable with +.BR LD_DEBUG +(with the categories +.IR bindings +and +.IR symbols ), +one can observe all run-time function bindings. +.TP +.BR LD_DEBUG " (since glibc 2.1)" +Output verbose debugging information about operation of the dynamic linker. +The content of this variable is one of more of the following categories, +separated by colons, commas, or (if the value is quoted) spaces: +.RS +.TP 12 +.I help +Specifying +.IR help +in the value of this variable does not run the specified program, +and displays a help message about which categories can be specified in this +environment variable. +.TP +.I all +Print all debugging information (except +.IR statistics +and +.IR unused ; +see below). +.TP +.I bindings +Display information about which definition each symbol is bound to. +.TP +.I files +Display progress for input file. +.TP +.I libs +Display library search paths. +.TP +.I reloc +Display relocation processing. +.TP +.I scopes +Display scope information. +.TP +.I statistics +Display relocation statistics. +.TP +.I symbols +Display search paths for each symbol look-up. +.TP +.I unused +Determine unused DSOs. +.TP +.I versions +Display version dependencies. +.RE +.IP +Since glibc 2.3.4, +.B LD_DEBUG +is ignored in secure-execution mode, unless the file +.IR /etc/suid\-debug +exists (the content of the file is irrelevant). +.TP +.BR LD_DEBUG_OUTPUT " (since glibc 2.1)" +By default, +.B LD_DEBUG +output is written to standard error. +If +.B LD_DEBUG_OUTPUT +is defined, then output is written to the pathname specified by its value, +with the suffix "." (dot) followed by the process ID appended to the pathname. +.IP +.B LD_DEBUG_OUTPUT +is ignored in secure-execution mode. +.TP +.BR LD_DYNAMIC_WEAK " (since glibc 2.1.91)" +By default, when searching shared libraries to resolve a symbol reference, +the dynamic linker will resolve to the first definition it finds. +.IP +Old glibc versions (before 2.2), provided a different behavior: +if the linker found a symbol that was weak, +it would remember that symbol and +keep searching in the remaining shared libraries. +If it subsequently found a strong definition of the same symbol, +then it would instead use that definition. +(If no further symbol was found, +then the dynamic linker would use the weak symbol that it initially found.) +.IP +The old glibc behavior was nonstandard. +(Standard practice is that the distinction between +weak and strong symbols should have effect only at static link time.) +In glibc 2.2, +.\" More precisely 2.1.92 +.\" See weak handling +.\" https://www.sourceware.org/ml/libc-hacker/2000-06/msg00029.html +.\" To: GNU libc hacker +.\" Subject: weak handling +.\" From: Ulrich Drepper +.\" Date: 07 Jun 2000 20:08:12 -0700 +.\" Reply-To: drepper at cygnus dot com (Ulrich Drepper) +the dynamic linker was modified to provide the current behavior +(which was the behavior that was provided by most other implementations +at that time). +.IP +Defining the +.B LD_DYNAMIC_WEAK +environment variable (with any value) provides +the old (nonstandard) glibc behavior, +whereby a weak symbol in one shared library may be overridden by +a strong symbol subsequently discovered in another shared library. +(Note that even when this variable is set, +a strong symbol in a shared library will not override +a weak definition of the same symbol in the main program.) +.IP +Since glibc 2.3.4, +.B LD_DYNAMIC_WEAK +is ignored in secure-execution mode. +.TP +.BR LD_HWCAP_MASK " (since glibc 2.1)" +Mask for hardware capabilities. +.TP +.BR LD_ORIGIN_PATH " (since glibc 2.1)" +Path where the binary is found. +.\" Used only if $ORIGIN can't be determined by normal means +.\" (from the origin path saved at load time, or from /proc/self/exe)? +.IP +Since glibc 2.4, +.B LD_ORIGIN_PATH +is ignored in secure-execution mode. +.TP +.BR LD_POINTER_GUARD " (glibc from 2.4 to 2.22)" +Set to 0 to disable pointer guarding. +Any other value enables pointer guarding, which is also the default. +Pointer guarding is a security mechanism whereby some pointers to code +stored in writable program memory (return addresses saved by +.BR setjmp (3) +or function pointers used by various glibc internals) are mangled +semi-randomly to make it more difficult for an attacker to hijack +the pointers for use in the event of a buffer overrun or +stack-smashing attack. +Since glibc 2.23, +.\" commit a014cecd82b71b70a6a843e250e06b541ad524f7 +.B LD_POINTER_GUARD +can no longer be used to disable pointer guarding, +which is now always enabled. +.TP +.BR LD_PROFILE " (since glibc 2.1)" +The name of a (single) shared object to be profiled, +specified either as a pathname or a soname. +Profiling output is appended to the file whose name is: +"\fI$LD_PROFILE_OUTPUT\fP/\fI$LD_PROFILE\fP.profile". +.IP +Since glibc 2.2.5, +.BR LD_PROFILE +is ignored in secure-execution mode. +.TP +.BR LD_PROFILE_OUTPUT " (since glibc 2.1)" +Directory where +.B LD_PROFILE +output should be written. +If this variable is not defined, or is defined as an empty string, +then the default is +.IR /var/tmp . +.IP +.B LD_PROFILE_OUTPUT +is ignored in secure-execution mode; instead +.IR /var/profile +is always used. +(This detail is relevant only before glibc 2.2.5, +since in later glibc versions, +.B LD_PROFILE +is also ignored in secure-execution mode.) +.TP +.BR LD_SHOW_AUXV " (since glibc 2.1)" +If this environment variable is defined (with any value), +show the auxiliary array passed up from the kernel (see also +.BR getauxval (3)). +.IP +Since glibc 2.3.4, +.B LD_SHOW_AUXV +is ignored in secure-execution mode. +.TP +.BR LD_TRACE_PRELINKING " (since glibc 2.4)" +If this environment variable is defined, +trace prelinking of the object whose name is assigned to +this environment variable. +(Use +.BR ldd (1) +to get a list of the objects that might be traced.) +If the object name is not recognized, +.\" (This is what seems to happen, from experimenting) +then all prelinking activity is traced. +.TP +.BR LD_USE_LOAD_BIAS " (since glibc 2.3.3)" +.\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html +.\" Subject: [PATCH] Support LD_USE_LOAD_BIAS +.\" Jakub Jelinek +By default (i.e., if this variable is not defined), +executables and prelinked +shared objects will honor base addresses of their dependent shared objects +and (nonprelinked) position-independent executables (PIEs) +and other shared objects will not honor them. +If +.B LD_USE_LOAD_BIAS +is defined with the value 1, both executables and PIEs +will honor the base addresses. +If +.B LD_USE_LOAD_BIAS +is defined with the value 0, +neither executables nor PIEs will honor the base addresses. +.IP +Since glibc 2.3.3, this variable is ignored in secure-execution mode. +.TP +.BR LD_VERBOSE " (since glibc 2.1)" +If set to a nonempty string, +output symbol versioning information about the +program if the +.B LD_TRACE_LOADED_OBJECTS +environment variable has been set. +.TP +.BR LD_WARN " (since glibc 2.1.3) +If set to a nonempty string, warn about unresolved symbols. +.TP +.BR LD_PREFER_MAP_32BIT_EXEC " (x86-64 only; since glibc 2.23)" +According to the Intel Silvermont software optimization guide, for 64-bit +applications, branch prediction performance can be negatively impacted +when the target of a branch is more than 4\ GB away from the branch. +If this environment variable is set (to any value), +the dynamic linker +will first try to map executable pages using the +.BR mmap (2) +.BR MAP_32BIT +flag, and fall back to mapping without that flag if that attempt fails. +NB: MAP_32BIT will map to the low 2\ GB (not 4\ GB) of the address space. +.IP +Because +.B MAP_32BIT +reduces the address range available for address space layout +randomization (ASLR), +.B LD_PREFER_MAP_32BIT_EXEC +is always disabled in secure-execution mode. +.SH FILES +.PD 0 +.TP +.I /lib/ld.so +a.out dynamic linker/loader +.TP +.IR /lib/ld\-linux.so. { 1 , 2 } +ELF dynamic linker/loader +.TP +.I /etc/ld.so.cache +File containing a compiled list of directories in which to search for +shared objects and an ordered list of candidate shared objects. +See +.BR ldconfig (8). +.TP +.I /etc/ld.so.preload +File containing a whitespace-separated list of ELF shared objects to +be loaded before the program. +See the discussion of +.BR LD_PRELOAD +above. +If both +.BR LD_PRELOAD +and +.I /etc/ld.so.preload +are employed, the libraries specified by +.BR LD_PRELOAD +are preloaded first. +.I /etc/ld.so.preload +has a system-wide effect, +causing the specified libraries to be preloaded for +all programs that are executed on the system. +(This is usually undesirable, +and is typically employed only as an emergency remedy, for example, +as a temporary workaround to a library misconfiguration issue.) +.TP +.I lib*.so* +shared objects +.PD +.SH NOTES +.SS Hardware capabilities +Some shared objects are compiled using hardware-specific instructions which do +not exist on every CPU. +Such objects should be installed in directories whose names define the +required hardware capabilities, such as +.IR /usr/lib/sse2/ . +The dynamic linker checks these directories against the hardware of the +machine and selects the most suitable version of a given shared object. +Hardware capability directories can be cascaded to combine CPU features. +The list of supported hardware capability names depends on the CPU. +The following names are currently recognized: +.TP +.B Alpha +ev4, ev5, ev56, ev6, ev67 +.TP +.B MIPS +loongson2e, loongson2f, octeon, octeon2 +.TP +.B PowerPC +4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle, +fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601, +ppc64, smt, spe, ucache, vsx +.TP +.B SPARC +flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2 +.TP +.B s390 +dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle, +z900, z990, z9-109, z10, zarch +.TP +.B x86 (32-bit only) +acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx, +mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm +.SH SEE ALSO +.BR ld (1), +.BR ldd (1), +.BR pldd (1), +.BR sprof (1), +.BR dlopen (3), +.BR getauxval (3), +.BR elf (5), +.BR capabilities (7), +.BR rtld-audit (7), +.BR ldconfig (8), +.BR sln (8) +.\" .SH AUTHORS +.\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus +.\" Torvalds, Lars Wirzenius and Mitch D'Souza +.\" ld\-linux.so: Roland McGrath, Ulrich Drepper and others. +.\" +.\" In the above, (libc5) stands for David Engel's ld.so/ld\-linux.so. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/ldconfig.8 b/man8/ldconfig.8 new file mode 100644 index 0000000..1c7ae5e --- /dev/null +++ b/man8/ldconfig.8 @@ -0,0 +1,198 @@ +.\" Copyright 1999 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of the +.\" License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" Modified, 6 May 2002, Michael Kerrisk, +.\" Change listed order of /usr/lib and /lib +.TH LDCONFIG 8 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +ldconfig \- configure dynamic linker run-time bindings +.SH SYNOPSIS +.BR /sbin/ldconfig " [" \-nNvXV "] [" \-f " \fIconf\fP] [" \-C " \fIcache\fP] [" \-r " \fIroot\fP]" +.IR directory \... +.PD 0 +.PP +.PD +.B /sbin/ldconfig +.B \-l +.RB [ \-v ] +.IR library \... +.PD 0 +.PP +.PD +.B /sbin/ldconfig +.B \-p +.SH DESCRIPTION +.B ldconfig +creates the necessary links and cache to the most recent shared +libraries found in the directories specified on the command line, +in the file +.IR /etc/ld.so.conf , +and in the trusted directories, +.I /lib +and +.IR /usr/lib +(on some 64-bit architectures such as x86-64, +.I lib +and +.IR /usr/lib +are the trusted directories for 32-bit libraries, while +.I /lib64 +and +.IR /usr/lib64 +are used for 64-bit libraries). +.PP +The cache is used by the run-time linker, +.I ld.so +or +.IR ld-linux.so . +.B ldconfig +checks the header and filenames of the libraries it encounters when +determining which versions should have their links updated. +.PP +.B ldconfig +will attempt to deduce the type of ELF libraries (i.e., libc5 or libc6/glibc) +based on what C libraries, if any, the library was linked against. +.\" The following sentence looks suspect +.\" (perhaps historical cruft) -- MTK, Jul 2005 +.\" Therefore, when making dynamic libraries, +.\" it is wise to explicitly link against libc (use \-lc). +.PP +Some existing libraries do not contain enough information +to allow the deduction of their type. +Therefore, the +.I /etc/ld.so.conf +file format allows the specification of an expected type. +This is used +.I only +for those ELF libraries which we can not work out. +The format +is "dirname=TYPE", where TYPE can be libc4, libc5, or libc6. +(This syntax also works on the command line.) +Spaces are +.I not +allowed. +Also see the +.B \-p +option. +.B ldconfig +should normally be run by the superuser as it may require write +permission on some root owned directories and files. +.SH OPTIONS +.TP +.BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP +(Since glibc 2.2) +Cache format to use: +.IR old , +.IR new , +or +.IR compat +(default). +.TP +.BI "\-C " cache +Use +.I cache +instead of +.IR /etc/ld.so.cache . +.TP +.BI "\-f " conf +Use +.I conf +instead of +.IR /etc/ld.so.conf . +.\" FIXME glibc 2.7 added -i +.TP +.BR \-i ", " \-\-ignore\-aux\-cache +(Since glibc 2.7) +.\" commit 27d9ffda17df4d2388687afd12897774fde39bcc +Ignore auxiliary cache file. +.TP +.B \-l +(Since glibc 2.2) +Library mode. +Manually link individual libraries. +Intended for use by experts only. +.TP +.B \-n +Process only the directories specified on the command line. +Don't process the trusted directories, +nor those specified in +.IR /etc/ld.so.conf . +Implies +.BR \-N . +.TP +.B \-N +Don't rebuild the cache. +Unless +.B \-X +is also specified, links are still updated. +.TP +.BR \-p ", " \-\-print\-cache +Print the lists of directories and candidate libraries stored in +the current cache. +.TP +.BI "\-r " root +Change to and use +.I root +as the root directory. +.TP +.BR \-v ", " \-\-verbose +Verbose mode. +Print current version number, the name of each directory as it +is scanned, and any links that are created. +Overrides quiet mode. +.TP +.BR \-V ", " \-\-version +Print program version. +.TP +.B \-X +Don't update links. +Unless +.B \-N +is also specified, the cache is still rebuilt. +.SH FILES +.\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf +.\" +.\" FIXME Since glibc-2.4, "hwcap" directives are supported in ld.so.conf +.PD 0 +.TP +.I /lib/ld.so +Run-time linker/loader. +.TP +.I /etc/ld.so.conf +File containing a list of directories, one per line, +in which to search for libraries. +.TP +.I /etc/ld.so.cache +File containing an ordered list of libraries found in the directories +specified in +.IR /etc/ld.so.conf , +as well as those found in the trusted directories. +.PD +.SH SEE ALSO +.BR ldd (1), +.BR ld.so (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/nscd.8 b/man8/nscd.8 new file mode 100644 index 0000000..9848f2b --- /dev/null +++ b/man8/nscd.8 @@ -0,0 +1,107 @@ +.\" Copyright 1999 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" +.\" %%%LICENSE_START(GPLv2+_SW_3_PARA) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of the +.\" License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" . +.\" %%%LICENSE_END +.\" +.\" 2008-12-05 Petr Baudis +.\" Rewrite the NOTES section to reflect modern reality +.\" +.TH NSCD 8 2015-05-07 "GNU" "Linux Programmer's Manual" +.SH NAME +nscd \- name service cache daemon +.SH DESCRIPTION +.B nscd +is a daemon that provides a cache for the most common name service +requests. +The default configuration file, +.IR /etc/nscd.conf , +determines the behavior of the cache daemon. +See +.BR nscd.conf (5). +.PP +.B nscd +provides caching for accesses of the +.BR passwd (5), +.BR group (5), +.BR hosts (5) +.BR services (5) +and +.I netgroup +databases through standard libc interfaces, such as +.BR getpwnam (3), +.BR getpwuid (3), +.BR getgrnam (3), +.BR getgrgid (3), +.BR gethostbyname (3), +and others. +.PP +There are two caches for each database: +a positive one for items found, and a negative one +for items not found. +Each cache has a separate TTL (time-to-live) +period for its data. +Note that the shadow file is specifically not cached. +.BR getspnam (3) +calls remain uncached as a result. +.SH OPTIONS +.TP +.B "\-\-help" +will give you a list with all options and what they do. +.SH NOTES +The daemon will try to watch for changes in configuration files +appropriate for each database (e.g., +.I /etc/passwd +for the +.I passwd +database or +.I /etc/hosts +and +.I /etc/resolv.conf +for the +.I hosts +database), and flush the cache when these are changed. +However, this will happen only after a short delay (unless the +.BR inotify (7) +mechanism is available and glibc 2.9 or later is available), +and this auto-detection does not cover configuration files +required by nonstandard NSS modules, if any are specified in +.IR /etc/nsswitch.conf . +In that case, you need to run the following command +after changing the configuration file of the database so that +.B nscd +invalidates its cache: +.PP +.in +4n +.EX +$ \fBnscd -i\fP \fI\fP +.EE +.in +.SH SEE ALSO +.BR nscd.conf (5), +.BR nsswitch.conf (5) +.\" .SH AUTHOR +.\" .B nscd +.\" was written by Thorsten Kukuk and Ulrich Drepper. +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/sln.8 b/man8/sln.8 new file mode 100644 index 0000000..27e9581 --- /dev/null +++ b/man8/sln.8 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2013 by Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SLN 8 2017-09-15 "GNU" "Linux Programmer's Manual" +.SH NAME +sln \- create symbolic links +.SH SYNOPSIS +.BI sln " source dest" +.br +.BI sln " filelist" +.SH DESCRIPTION +The +.B sln +program creates symbolic links. +Unlike the +.BR ln (1) +program, it is statically linked. +This means that if for some reason the dynamic linker is not working, +.BR sln +can be used to make symbolic links to dynamic libraries. +.PP +The command line has two forms. +In the first form, it creates +.I dest +as a new symbolic link to +.IR source . +.PP +In the second form, +.I filelist +is a list of space-separated pathname pairs, +and the effect is as if +.BR sln +was executed once for each line of the file, +with the two pathnames as the arguments. +.PP +The +.B sln +program supports no command-line options. +.SH SEE ALSO +.BR ln (1), +.BR ld.so (8), +.BR ldconfig (8) +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/tzselect.8 b/man8/tzselect.8 new file mode 100644 index 0000000..142a55b --- /dev/null +++ b/man8/tzselect.8 @@ -0,0 +1,60 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain +.\" %%%LICENSE_END +.\" +.TH TZSELECT 8 2007-05-18 "" "Linux System Administration" +.SH NAME +tzselect \- select a timezone +.SH SYNOPSIS +.B tzselect +.SH DESCRIPTION +The +.B tzselect +program asks the user for information about the current location, +and outputs the resulting timezone description to standard output. +The output is suitable as a value for the +.B TZ +environment variable. +.PP +All interaction with the user is done via standard input and standard error. +.SH EXIT STATUS +The exit status is zero if a timezone was successfully obtained +from the user, and is nonzero otherwise. +.SH ENVIRONMENT +.TP +.B AWK +Name of a POSIX-compliant +.I awk +program (default: +.BR awk ). +.TP +.B TZDIR +Name of the directory containing timezone data files (default: +.IR /usr/share/zoneinfo ). +.\" or perhaps /usr/local/etc/zoneinfo in some older systems. +.SH FILES +.TP +\fBTZDIR\fP\fI/iso3166.tab\fP +Table of ISO 3166 2-letter country codes and country names. +.TP +\fBTZDIR\fP\fI/zone.tab\fP +Table of country codes, latitude and longitude, TZ values, and +descriptive comments. +.TP +\fBTZDIR\fP\fI/\fP\fITZ\fP +Timezone data file for timezone +.IR TZ . +.SH SEE ALSO +.BR tzfile (5), +.BR zdump (8), +.BR zic (8) +.\" @(#)tzselect.8 1.3 +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/zdump.8 b/man8/zdump.8 new file mode 100644 index 0000000..5ed545a --- /dev/null +++ b/man8/zdump.8 @@ -0,0 +1,59 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain +.\" %%%LICENSE_END +.\" +.TH ZDUMP 8 2017-05-03 "" "Linux System Administration" +.SH NAME +zdump \- timezone dumper +.SH SYNOPSIS +.BR zdump " [" \-\-version "] [" \-\-help "] [" \-v "] [" \-c +.RI [ loyear \fB,\fR] hiyear "] [\fIzonename\fP...]" +.SH DESCRIPTION +The +.B zdump +program prints the current time in each +.I zonename +named on the command line. +.PP +.SH OPTIONS +.TP +.B \-\-version +Output version information and exit. +.TP +.B \-\-help +Output short usage message and exit. +.TP +.B \-v +For each +.I zonename +on the command line, +print the time at the lowest possible time value, +the time one day after the lowest possible time value, +the times both one second before and exactly at +each detected time discontinuity, +the time at one day less than the highest possible time value, +and the time at the highest possible time value. +Each line ends with +.B isdst=1 +if the given time is Daylight Saving Time or +.B isdst=0 +otherwise. +.TP +.BI "\-c " \fR[\fIloyear , \fR]\fIhiyear +Cut off the verbose output near the start of the given year(s). +The output still includes the lowest possible time value +and one day after it, and the highest possible time value +preceded by the time value one day before it. +.SH SEE ALSO +.BR tzfile (5), +.BR zic (8) +.\" @(#)zdump.8 7.3 +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/man8/zic.8 b/man8/zic.8 new file mode 100644 index 0000000..0cda29e --- /dev/null +++ b/man8/zic.8 @@ -0,0 +1,416 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain +.\" %%%LICENSE_END +.\" +.TH ZIC 8 2010-02-25 "" "Linux System Administration" +.SH NAME +zic \- timezone compiler +.SH SYNOPSIS +.nf +.BR zic " [" \-v "] [" \-d " \fIdirectory\fP] [" \-l " \fIlocaltime\fP] [" \ +\-p " \fIposixrules\fP]" +.RB " [" \-L " \fIleapsecondfilename\fP] [" \-s "] [" \-y \ +" \fIcommand\fP] [\fIfilename\fP...] +.fi +.SH DESCRIPTION +.if t .ds lq `` +.if t .ds rq '' +.if n .ds lq \&"\" +.if n .ds rq \&"\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +The +.B zic +program reads text from the file(s) named on the command line +and creates the time conversion information files specified in this input. +If a +.I filename +is +.BR \- , +standard input is read. +.PP +These options are available: +.TP +.BI "\-d " directory +Create time conversion information files in the named directory rather than +in the standard directory named below. +.TP +.BI "\-l " timezone +Use the given timezone as local time. +.B zic +will act as if the input contained a link line of the form +.PP +.ti +.5i +Link \fItimezone\fP localtime +.TP +.BI "\-p " timezone +Use the given timezone's rules when handling POSIX-format +timezone environment variables. +.B zic +will act as if the input contained a link line of the form +.PP +.ti +.5i +Link \fItimezone\fP posixrules +.TP +.BI "\-L " leapsecondfilename +Read leap second information from the file with the given name. +If this option is not used, +no leap second information appears in output files. +.TP +.B \-v +Complain if a year that appears in a data file is outside the range +of years representable by +.BR time (2) +values. +.TP +.B \-s +Limit time values stored in output files to values that are the same +whether they're taken to be signed or unsigned. +You can use this option to generate SVVS-compatible files. +.TP +.BI "\-y " command +Use the given +.I command +rather than +.B yearistype +when checking year types (see below). +.PP +Input lines are made up of fields. +Fields are separated from one another by any number of white space characters. +Leading and trailing white space on input lines is ignored. +An unquoted sharp character (#) in the input introduces a comment which extends +to the end of the line the sharp character appears on. +White space characters and sharp characters may be enclosed in double quotes +(") if they're to be used as part of a field. +Any line that is blank (after comment stripping) is ignored. +Nonblank lines are expected to be of one of three types: +rule lines, zone lines, and link lines. +.PP +A rule line has the form +.nf +.ti +.5i +.ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'TYPE\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u +.PP +Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S +.PP +For example: +.ti +.5i +.PP +Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D +.PP +.fi +The fields that make up a rule line are: +.TP "\w'LETTER/S'u" +.B NAME +Gives the (arbitrary) name of the set of rules this rule is part of. +.TP +.B FROM +Gives the first year in which the rule applies. +Any integer year can be supplied; the Gregorian calendar is assumed. +The word +.I minimum +(or an abbreviation) means the minimum year representable as an integer. +The word +.I maximum +(or an abbreviation) means the maximum year representable as an integer. +Rules can describe times that are not representable as time values, +with the unrepresentable times ignored; this allows rules to be portable +among hosts with differing time value types. +.TP +.B TO +Gives the final year in which the rule applies. +In addition to +.I minimum +and +.I maximum +(as above), +the word +.I only +(or an abbreviation) +may be used to repeat the value of the +.B FROM +field. +.TP +.B TYPE +Gives the type of year in which the rule applies. +If +.B TYPE +is +.BR \- , +then the rule applies in all years between +.B FROM +and +.B TO +inclusive. +If +.B TYPE +is something else, then +.I zic +executes the command +.ti +.5i +.B yearistype +.I year +.I type +.br +to check the type of a year: +an exit status of zero is taken to mean that the year is of the given type; +an exit status of one is taken to mean that the year is not of the given type. +.TP +.B IN +Names the month in which the rule takes effect. +Month names may be abbreviated. +.TP +.B ON +Gives the day on which the rule takes effect. +Recognized forms include: +.nf +.in +.5i +.PP +.ta \w'Sun<=25\0\0'u +5 the fifth of the month +lastSun the last Sunday in the month +lastMon the last Monday in the month +Sun>=8 first Sunday on or after the eighth +Sun<=25 last Sunday on or before the 25th +.fi +.in -.5i +.PP +Names of days of the week may be abbreviated or spelled out in full. +Note that there must be no spaces within the +.B ON +field. +.TP +.B AT +Gives the time of day at which the rule takes effect. +Recognized forms include: +.nf +.in +.5i +.PP +.ta \w'1:28:13\0\0'u +2 time in hours +2:00 time in hours and minutes +15:00 24-hour format time (for times after noon) +1:28:14 time in hours, minutes, and seconds +\- equivalent to 0 +.fi +.in -.5i +.PP +where hour 0 is midnight at the start of the day, +and hour 24 is midnight at the end of the day. +Any of these forms may be followed by the letter +.I w +if the given time is local +.q "wall clock" +time, +.I s +if the given time is local +.q standard +time, or +.I u +(or +.I g +or +.IR z ) +if the given time is universal time; +in the absence of an indicator, +wall clock time is assumed. +.TP +.B SAVE +Gives the amount of time to be added to local standard time when the rule is in +effect. +This field has the same format as the +.B AT +field +(although, of course, the +.I w +and +.I s +suffixes are not used). +.TP +.B LETTER/S +Gives the +.q "variable part" +(for example, the +.q S +or +.q D +in +.q EST +or +.q EDT ) +of timezone abbreviations to be used when this rule is in effect. +If this field is +.BR \- , +the variable part is null. +.PP +A zone line has the form +.PP +.nf +.ti +.5i +.ta \w'Zone\0\0'u +\w'Australia/Adelaide\0\0'u +\w'UTCOFF\0\0'u +\w'RULES/SAVE\0\0'u +\w'FORMAT\0\0'u +Zone NAME UTCOFF RULES/SAVE FORMAT [UNTIL] +.PP +For example: +.PP +.ti +.5i +Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 +.PP +.fi +The fields that make up a zone line are: +.TP "\w'UTCOFF'u" +.B NAME +The name of the timezone. +This is the name used in creating the time conversion information file for the +zone. +.TP +.B UTCOFF +The amount of time to add to UTC to get standard time in this zone. +This field has the same format as the +.B AT +and +.B SAVE +fields of rule lines; +begin the field with a minus sign if time must be subtracted from UTC. +.TP +.B RULES/SAVE +The name of the rule(s) that apply in the timezone or, +alternately, an amount of time to add to local standard time. +If this field is +.BR \- , +then standard time always applies in the timezone. +.TP +.B FORMAT +The format for timezone abbreviations in this timezone. +The pair of characters +.B %s +is used to show where the +.q "variable part" +of the timezone abbreviation goes. +Alternately, +a slash (/) +separates standard and daylight abbreviations. +.TP +.B UNTIL +The time at which the UTC offset or the rule(s) change for a location. +It is specified as a year, a month, a day, and a time of day. +If this is specified, +the timezone information is generated from the given UTC offset +and rule change until the time specified. +The month, day, and time of day have the same format as the IN, ON, and AT +columns of a rule; trailing columns can be omitted, and default to the +earliest possible value for the missing columns. +.IP +The next line must be a +.q continuation +line; this has the same form as a zone line except that the +string +.q Zone +and the name are omitted, as the continuation line will +place information starting at the time specified as the +.B UNTIL +field in the previous line in the file used by the previous line. +Continuation lines may contain an +.B UNTIL +field, just as zone lines do, indicating that the next line is a further +continuation. +.PP +A link line has the form +.PP +.nf +.ti +.5i +.ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u +Link LINK-FROM LINK-TO +.PP +For example: +.PP +.ti +.5i +Link Europe/Istanbul Asia/Istanbul +.PP +.fi +The +.B LINK-FROM +field should appear as the +.B NAME +field in some zone line; +the +.B LINK-TO +field is used as an alternate name for that zone. +.PP +Except for continuation lines, +lines may appear in any order in the input. +.PP +Lines in the file that describes leap seconds have the following form: +.nf +.ti +.5i +.ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u +.PP +Leap YEAR MONTH DAY HH:MM:SS CORR R/S +.PP +For example: +.ti +.5i +.PP +Leap 1974 Dec 31 23:59:60 + S +.PP +.fi +The +.BR YEAR , +.BR MONTH , +.BR DAY , +and +.B HH:MM:SS +fields tell when the leap second happened. +The +.B CORR +field +should be +.q + +if a second was added +or +.q - +if a second was skipped. +.\" There's no need to document the following, since it's impossible for more +.\" than one leap second to be inserted or deleted at a time. +.\" The C Standard is in error in suggesting the possibility. +.\" See Terry J Quinn, The BIPM and the accurate measure of time, +.\" Proc IEEE 79, 7 (July 1991), 894-905. +.\" or +.\" .q ++ +.\" if two seconds were added +.\" or +.\" .q -- +.\" if two seconds were skipped. +The +.B R/S +field +should be (an abbreviation of) +.q Stationary +if the leap second time given by the other fields should be interpreted as UTC +or +(an abbreviation of) +.q Rolling +if the leap second time given by the other fields should be interpreted as +local wall clock time. +.SH FILES +.TP +.I /usr/local/etc/zoneinfo +Standard directory used for created files. +.SH NOTES +For areas with more than two types of local time, +you may need to use local standard time in the +.B AT +field of the earliest transition time's rule to ensure that +the earliest transition time recorded in the compiled file is correct. +.SH SEE ALSO +.BR tzfile (5), +.BR zdump (8) +.\" @(#)zic.8 7.19 +.SH COLOPHON +This page is part of release 4.15 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%https://www.kernel.org/doc/man\-pages/. diff --git a/proj.man-pages.desc b/proj.man-pages.desc new file mode 100644 index 0000000..2663cb5 --- /dev/null +++ b/proj.man-pages.desc @@ -0,0 +1 @@ +man-pages|Linux kernel and C library user-space interface documentation|https://www.kernel.org/doc/man-pages/|REPO|Git|https://www.kernel.org/doc/man-pages/index.html|https://www.kernel.org/doc/man-pages/reporting_bugs.html|2018-02-02 diff --git a/proj.man-pages.pages b/proj.man-pages.pages new file mode 100644 index 0000000..7a9e169 --- /dev/null +++ b/proj.man-pages.pages @@ -0,0 +1,2383 @@ +man1/locale.1 +man1/localedef.1 +man1/memusage.1 +man1/intro.1 +man1/iconv.1 +man1/getent.1 +man1/memusagestat.1 +man1/mtrace.1 +man1/time.1 +man1/ldd.1 +man1/pldd.1 +man1/sprof.1 +man2/get_mempolicy.2 +man2/ftruncate.2 +man2/outb.2 +man2/times.2 +man2/sigqueue.2 +man2/add_key.2 +man2/setuid32.2 +man2/mq_timedsend.2 +man2/mkdir.2 +man2/linkat.2 +man2/sched_yield.2 +man2/statvfs.2 +man2/spu_create.2 +man2/stat.2 +man2/rt_tgsigqueueinfo.2 +man2/arch_prctl.2 +man2/rt_sigaction.2 +man2/inb_p.2 +man2/outw.2 +man2/pciconfig_read.2 +man2/rt_sigreturn.2 +man2/io_setup.2 +man2/capget.2 +man2/semget.2 +man2/renameat.2 +man2/setxattr.2 +man2/getunwind.2 +man2/utimensat.2 +man2/getcontext.2 +man2/keyctl.2 +man2/shmget.2 +man2/geteuid.2 +man2/setrlimit.2 +man2/statfs64.2 +man2/bdflush.2 +man2/pciconfig_write.2 +man2/sched_setparam.2 +man2/open.2 +man2/tgkill.2 +man2/signalfd.2 +man2/pkey_mprotect.2 +man2/fanotify_init.2 +man2/listen.2 +man2/s390_sthyi.2 +man2/setsockopt.2 +man2/ioprio_get.2 +man2/inl.2 +man2/ftruncate64.2 +man2/free_hugepages.2 +man2/chdir.2 +man2/munmap.2 +man2/setup.2 +man2/syscalls.2 +man2/sigpending.2 +man2/mremap.2 +man2/lchown.2 +man2/pkey_free.2 +man2/dup.2 +man2/setitimer.2 +man2/msgop.2 +man2/process_vm_writev.2 +man2/bind.2 +man2/setregid32.2 +man2/quotactl.2 +man2/mlock2.2 +man2/sendmmsg.2 +man2/ioctl_ns.2 +man2/sched_setscheduler.2 +man2/pread64.2 +man2/setfsuid.2 +man2/fsync.2 +man2/timerfd_settime.2 +man2/kill.2 +man2/clock_getres.2 +man2/setegid.2 +man2/membarrier.2 +man2/madvise1.2 +man2/query_module.2 +man2/write.2 +man2/inw.2 +man2/fanotify_mark.2 +man2/lookup_dcookie.2 +man2/epoll_wait.2 +man2/sethostid.2 +man2/oldlstat.2 +man2/unlinkat.2 +man2/outw_p.2 +man2/finit_module.2 +man2/gtty.2 +man2/delete_module.2 +man2/ioctl_ficlone.2 +man2/ptrace.2 +man2/listxattr.2 +man2/modify_ldt.2 +man2/umount2.2 +man2/gettid.2 +man2/arm_fadvise.2 +man2/acct.2 +man2/fork.2 +man2/capset.2 +man2/copy_file_range.2 +man2/fdatasync.2 +man2/kexec_load.2 +man2/fstat.2 +man2/sigwaitinfo.2 +man2/ssetmask.2 +man2/s390_pci_mmio_write.2 +man2/sched_setaffinity.2 +man2/unshare.2 +man2/lchown32.2 +man2/select_tut.2 +man2/getdomainname.2 +man2/pread.2 +man2/vmsplice.2 +man2/perfmonctl.2 +man2/alarm.2 +man2/mq_unlink.2 +man2/migrate_pages.2 +man2/rt_sigsuspend.2 +man2/ioctl_list.2 +man2/prof.2 +man2/gethostname.2 +man2/shutdown.2 +man2/recvmmsg.2 +man2/execve.2 +man2/inotify_init1.2 +man2/writev.2 +man2/poll.2 +man2/mprotect.2 +man2/process_vm_readv.2 +man2/close.2 +man2/mq_notify.2 +man2/intro.2 +man2/ioctl_fat.2 +man2/readahead.2 +man2/getpeername.2 +man2/mlock.2 +man2/sysinfo.2 +man2/utimes.2 +man2/prctl.2 +man2/shmop.2 +man2/ioctl_ficlonerange.2 +man2/ustat.2 +man2/removexattr.2 +man2/fremovexattr.2 +man2/setpgrp.2 +man2/getcpu.2 +man2/ppoll.2 +man2/pselect6.2 +man2/timer_delete.2 +man2/umount.2 +man2/sigtimedwait.2 +man2/uselib.2 +man2/send.2 +man2/fstatat64.2 +man2/alloc_hugepages.2 +man2/sysfs.2 +man2/sigprocmask.2 +man2/access.2 +man2/getdents.2 +man2/tee.2 +man2/isastream.2 +man2/timer_settime.2 +man2/io_getevents.2 +man2/msgsnd.2 +man2/openat.2 +man2/fchownat.2 +man2/setfsuid32.2 +man2/chmod.2 +man2/clone2.2 +man2/gethostid.2 +man2/utime.2 +man2/getpgid.2 +man2/getsid.2 +man2/mknodat.2 +man2/ioctl_tty.2 +man2/outl.2 +man2/outsw.2 +man2/pause.2 +man2/getgroups32.2 +man2/fadvise64_64.2 +man2/oldfstat.2 +man2/getegid32.2 +man2/getdtablesize.2 +man2/msync.2 +man2/setreuid32.2 +man2/syncfs.2 +man2/accept.2 +man2/ioctl_console.2 +man2/setgroups32.2 +man2/ioctl_getfsmap.2 +man2/restart_syscall.2 +man2/sched_get_priority_max.2 +man2/preadv.2 +man2/llseek.2 +man2/epoll_pwait.2 +man2/remap_file_pages.2 +man2/link.2 +man2/insb.2 +man2/afs_syscall.2 +man2/dup2.2 +man2/setuid.2 +man2/s390_pci_mmio_read.2 +man2/getresuid32.2 +man2/timerfd_create.2 +man2/iopl.2 +man2/ioctl_iflags.2 +man2/sched_getattr.2 +man2/pciconfig_iobase.2 +man2/getresgid.2 +man2/vhangup.2 +man2/prlimit.2 +man2/mq_getsetattr.2 +man2/_Exit.2 +man2/pwritev2.2 +man2/outl_p.2 +man2/bpf.2 +man2/mq_timedreceive.2 +man2/sethostname.2 +man2/fchmodat.2 +man2/waitpid.2 +man2/clock_gettime.2 +man2/signal.2 +man2/get_kernel_syms.2 +man2/fstatvfs.2 +man2/fstatfs.2 +man2/io_cancel.2 +man2/fchown.2 +man2/get_robust_list.2 +man2/oldstat.2 +man2/stime.2 +man2/mmap.2 +man2/inotify_init.2 +man2/syscall.2 +man2/sendfile.2 +man2/mlockall.2 +man2/sync_file_range.2 +man2/mpx.2 +man2/kcmp.2 +man2/getpagesize.2 +man2/nice.2 +man2/sched_rr_get_interval.2 +man2/signalfd4.2 +man2/symlink.2 +man2/rename.2 +man2/vserver.2 +man2/fadvise64.2 +man2/uname.2 +man2/set_thread_area.2 +man2/timer_getoverrun.2 +man2/setpgid.2 +man2/sigaltstack.2 +man2/chroot.2 +man2/sched_getscheduler.2 +man2/getpriority.2 +man2/subpage_prot.2 +man2/getpid.2 +man2/getresgid32.2 +man2/setns.2 +man2/time.2 +man2/eventfd2.2 +man2/ugetrlimit.2 +man2/getrandom.2 +man2/readlink.2 +man2/shmat.2 +man2/kexec_file_load.2 +man2/setreuid.2 +man2/socketpair.2 +man2/read.2 +man2/arm_sync_file_range.2 +man2/chown.2 +man2/ioctl.2 +man2/chown32.2 +man2/renameat2.2 +man2/ioctl_fideduperange.2 +man2/epoll_create1.2 +man2/semctl.2 +man2/msgctl.2 +man2/getgid.2 +man2/fattach.2 +man2/wait.2 +man2/tkill.2 +man2/timer_create.2 +man2/open_by_handle_at.2 +man2/pkey_alloc.2 +man2/create_module.2 +man2/userfaultfd.2 +man2/munlockall.2 +man2/getxattr.2 +man2/getpmsg.2 +man2/getgroups.2 +man2/wait4.2 +man2/settimeofday.2 +man2/getitimer.2 +man2/brk.2 +man2/msgrcv.2 +man2/clock_settime.2 +man2/llistxattr.2 +man2/io_destroy.2 +man2/arm_fadvise64_64.2 +man2/splice.2 +man2/inw_p.2 +man2/rt_sigtimedwait.2 +man2/adjtimex.2 +man2/mount.2 +man2/memfd_create.2 +man2/killpg.2 +man2/futimesat.2 +man2/readlinkat.2 +man2/clone.2 +man2/geteuid32.2 +man2/fchdir.2 +man2/fallocate.2 +man2/sched_getparam.2 +man2/pipe.2 +man2/perf_event_open.2 +man2/fstat64.2 +man2/sigaction.2 +man2/epoll_ctl.2 +man2/getuid.2 +man2/idle.2 +man2/sendmsg.2 +man2/olduname.2 +man2/lremovexattr.2 +man2/statx.2 +man2/outb_p.2 +man2/mkdirat.2 +man2/exit.2 +man2/setpriority.2 +man2/semop.2 +man2/recvmsg.2 +man2/setgid.2 +man2/getdents64.2 +man2/fchown32.2 +man2/set_mempolicy.2 +man2/sync_file_range2.2 +man2/flock.2 +man2/msgget.2 +man2/fchmod.2 +man2/setgroups.2 +man2/setcontext.2 +man2/mbind.2 +man2/mq_open.2 +man2/waitid.2 +man2/setdomainname.2 +man2/pivot_root.2 +man2/accept4.2 +man2/socket.2 +man2/personality.2 +man2/symlinkat.2 +man2/reboot.2 +man2/name_to_handle_at.2 +man2/ioperm.2 +man2/_syscall.2 +man2/nanosleep.2 +man2/swapon.2 +man2/lgetxattr.2 +man2/faccessat.2 +man2/syslog.2 +man2/_sysctl.2 +man2/setsid.2 +man2/seccomp.2 +man2/sbrk.2 +man2/futex.2 +man2/rt_sigpending.2 +man2/lstat.2 +man2/fstatat.2 +man2/getcwd.2 +man2/lock.2 +man2/fcntl64.2 +man2/getresuid.2 +man2/_llseek.2 +man2/sigreturn.2 +man2/sched_getaffinity.2 +man2/inl_p.2 +man2/sendfile64.2 +man2/sched_get_priority_min.2 +man2/readv.2 +man2/setresgid.2 +man2/flistxattr.2 +man2/readdir.2 +man2/phys.2 +man2/setresuid.2 +man2/fgetxattr.2 +man2/setgid32.2 +man2/fcntl.2 +man2/statfs.2 +man2/ipc.2 +man2/rt_sigqueueinfo.2 +man2/madvise.2 +man2/prlimit64.2 +man2/dup3.2 +man2/lseek.2 +man2/mknod.2 +man2/unlink.2 +man2/set_robust_list.2 +man2/vm86.2 +man2/inotify_add_watch.2 +man2/rmdir.2 +man2/pselect.2 +man2/fstatfs64.2 +man2/ioctl_userfaultfd.2 +man2/cacheflush.2 +man2/vm86old.2 +man2/__clone2.2 +man2/timer_gettime.2 +man2/getrusage.2 +man2/io_submit.2 +man2/getsockname.2 +man2/nfsservctl.2 +man2/setfsgid.2 +man2/_newselect.2 +man2/ioprio_set.2 +man2/sched_setattr.2 +man2/getsockopt.2 +man2/newfstatat.2 +man2/inotify_rm_watch.2 +man2/security.2 +man2/getuid32.2 +man2/break.2 +man2/outsb.2 +man2/getrlimit.2 +man2/setregid.2 +man2/vfork.2 +man2/inb.2 +man2/sendto.2 +man2/stat64.2 +man2/lstat64.2 +man2/seteuid.2 +man2/mincore.2 +man2/fdetach.2 +man2/putmsg.2 +man2/setfsgid32.2 +man2/unimplemented.2 +man2/insw.2 +man2/semtimedop.2 +man2/stty.2 +man2/get_thread_area.2 +man2/socketcall.2 +man2/select.2 +man2/wait3.2 +man2/posix_fadvise.2 +man2/pwrite.2 +man2/sgetmask.2 +man2/shmdt.2 +man2/gettimeofday.2 +man2/execveat.2 +man2/lsetxattr.2 +man2/shmctl.2 +man2/getgid32.2 +man2/truncate.2 +man2/set_tid_address.2 +man2/fsetxattr.2 +man2/getppid.2 +man2/recvfrom.2 +man2/munlock.2 +man2/epoll_create.2 +man2/sigsuspend.2 +man2/s390_runtime_instr.2 +man2/mmap2.2 +man2/clock_nanosleep.2 +man2/pwritev.2 +man2/exit_group.2 +man2/putpmsg.2 +man2/eventfd.2 +man2/request_key.2 +man2/creat.2 +man2/truncate64.2 +man2/preadv2.2 +man2/connect.2 +man2/setresuid32.2 +man2/pwrite64.2 +man2/swapoff.2 +man2/getmsg.2 +man2/setresgid32.2 +man2/sync.2 +man2/rt_sigprocmask.2 +man2/umask.2 +man2/init_module.2 +man2/spu_run.2 +man2/getpgrp.2 +man2/timerfd_gettime.2 +man2/getegid.2 +man2/oldolduname.2 +man2/recv.2 +man2/_exit.2 +man2/tuxcall.2 +man2/outsl.2 +man2/insl.2 +man2/sysctl.2 +man2/move_pages.2 +man2/pipe2.2 +man3/nrand48_r.3 +man3/putspent.3 +man3/frexp.3 +man3/pthread_setcancelstate.3 +man3/tcgetpgrp.3 +man3/ldexpf.3 +man3/execle.3 +man3/sem_destroy.3 +man3/CPU_COUNT_S.3 +man3/tanhf.3 +man3/strcasecmp.3 +man3/nextafterf.3 +man3/lrintl.3 +man3/ccosf.3 +man3/getpwnam.3 +man3/malloc_info.3 +man3/res_send.3 +man3/llroundf.3 +man3/timeradd.3 +man3/getutmp.3 +man3/pthread_attr_getstack.3 +man3/getchar_unlocked.3 +man3/wmemcpy.3 +man3/STAILQ_REMOVE_HEAD.3 +man3/csqrt.3 +man3/towupper_l.3 +man3/getgrnam.3 +man3/flockfile.3 +man3/argz_create_sep.3 +man3/ispunct_l.3 +man3/lrintf.3 +man3/grantpt.3 +man3/lrint.3 +man3/fgetpos.3 +man3/isascii.3 +man3/daylight.3 +man3/fdim.3 +man3/cosf.3 +man3/drem.3 +man3/cpow.3 +man3/rpc.3 +man3/psiginfo.3 +man3/on_exit.3 +man3/__free_hook.3 +man3/xdr_double.3 +man3/__memalign_hook.3 +man3/signgam.3 +man3/getopt.3 +man3/hsearch.3 +man3/qfcvt_r.3 +man3/lcong48.3 +man3/mrand48_r.3 +man3/argz_extract.3 +man3/atoll.3 +man3/atoq.3 +man3/xdr_enum.3 +man3/finitef.3 +man3/swapcontext.3 +man3/vscanf.3 +man3/tcgetattr.3 +man3/yn.3 +man3/timercmp.3 +man3/wcsstr.3 +man3/updwtmpx.3 +man3/getdate_err.3 +man3/stdarg.3 +man3/STAILQ_EMPTY.3 +man3/casinhl.3 +man3/ctanf.3 +man3/fmaf.3 +man3/pthread_mutexattr_destroy.3 +man3/mallopt.3 +man3/bindresvport.3 +man3/CPU_CLR.3 +man3/log2l.3 +man3/backtrace_symbols.3 +man3/argz_next.3 +man3/dbopen.3 +man3/__fwriting.3 +man3/exp2f.3 +man3/isnan.3 +man3/getmntent_r.3 +man3/strfmon_l.3 +man3/envz_entry.3 +man3/vsyslog.3 +man3/fstatvfs.3 +man3/regfree.3 +man3/authunix_create.3 +man3/muntrace.3 +man3/y1l.3 +man3/strrchr.3 +man3/qecvt_r.3 +man3/CPU_ALLOC_SIZE.3 +man3/fwide.3 +man3/vprintf.3 +man3/mbstowcs.3 +man3/ualarm.3 +man3/erff.3 +man3/floorl.3 +man3/svc_getreqset.3 +man3/putchar.3 +man3/getutent.3 +man3/TAILQ_REMOVE.3 +man3/LIST_FIRST.3 +man3/pthread_getattr_default_np.3 +man3/mbsrtowcs.3 +man3/strftime.3 +man3/unlocked_stdio.3 +man3/feclearexcept.3 +man3/imaxdiv.3 +man3/setcontext.3 +man3/catopen.3 +man3/isfdtype.3 +man3/sem_timedwait.3 +man3/be16toh.3 +man3/CPU_OR_S.3 +man3/sys_nerr.3 +man3/mbrlen.3 +man3/tmpnam_r.3 +man3/tcflush.3 +man3/pthread_cleanup_pop.3 +man3/system.3 +man3/ecvt_r.3 +man3/getwchar.3 +man3/gnu_dev_minor.3 +man3/fgetspent.3 +man3/strfromd.3 +man3/error.3 +man3/wctob.3 +man3/iscntrl.3 +man3/log2.3 +man3/eaccess.3 +man3/logb.3 +man3/fgetgrent_r.3 +man3/__ppc_get_timebase_freq.3 +man3/isprint.3 +man3/strncpy.3 +man3/cfgetospeed.3 +man3/sigignore.3 +man3/fmodf.3 +man3/getnetent.3 +man3/vfwprintf.3 +man3/setjmp.3 +man3/posix_spawn.3 +man3/asctime.3 +man3/wordfree.3 +man3/getnameinfo.3 +man3/fts_open.3 +man3/STAILQ_HEAD_INITIALIZER.3 +man3/major.3 +man3/logbf.3 +man3/strxfrm.3 +man3/ctanl.3 +man3/posix_spawnp.3 +man3/key_gendes.3 +man3/stdio.3 +man3/setservent.3 +man3/hasmntopt.3 +man3/wordexp.3 +man3/dlinfo.3 +man3/getgrnam_r.3 +man3/pthread_attr_setdetachstate.3 +man3/svcfd_create.3 +man3/SLIST_ENTRY.3 +man3/undocumented.3 +man3/sincosf.3 +man3/ceill.3 +man3/stpcpy.3 +man3/log10l.3 +man3/ftok.3 +man3/ferror_unlocked.3 +man3/psignal.3 +man3/pthread_cleanup_push_defer_np.3 +man3/isalpha.3 +man3/conjl.3 +man3/CPU_SET.3 +man3/crypt.3 +man3/argz_append.3 +man3/fputs.3 +man3/atanf.3 +man3/__ppc_mdoio.3 +man3/isinff.3 +man3/ynf.3 +man3/tzname.3 +man3/argz_replace.3 +man3/hypot.3 +man3/mq_close.3 +man3/dirfd.3 +man3/initstate.3 +man3/nearbyintf.3 +man3/mtrace.3 +man3/qsort_r.3 +man3/FD_ISSET.3 +man3/execlp.3 +man3/cexp.3 +man3/CMSG_SPACE.3 +man3/isatty.3 +man3/program_invocation_short_name.3 +man3/CIRCLEQ_INIT.3 +man3/getprotoent.3 +man3/tmpfile.3 +man3/sigblock.3 +man3/erfcl.3 +man3/inet_aton.3 +man3/getprotobynumber.3 +man3/SLIST_INIT.3 +man3/mkdtemp.3 +man3/gammaf.3 +man3/HUGE_VAL.3 +man3/rewinddir.3 +man3/fgetpwent_r.3 +man3/islower_l.3 +man3/nextdown.3 +man3/pthread_create.3 +man3/casin.3 +man3/regex.3 +man3/mprobe.3 +man3/FD_ZERO.3 +man3/strpbrk.3 +man3/pthread_attr_setstack.3 +man3/alloca.3 +man3/endaliasent.3 +man3/hdestroy.3 +man3/TAILQ_FIRST.3 +man3/svctcp_create.3 +man3/xdr_int.3 +man3/cfsetospeed.3 +man3/rand_r.3 +man3/getpwuid.3 +man3/cimagf.3 +man3/vwarnx.3 +man3/klogctl.3 +man3/xdr_array.3 +man3/getservbyname_r.3 +man3/feraiseexcept.3 +man3/getumask.3 +man3/getutid.3 +man3/xdr_u_char.3 +man3/acosf.3 +man3/gethostbyname2_r.3 +man3/getgrgid.3 +man3/setgrent.3 +man3/svc_register.3 +man3/passwd2des.3 +man3/CPU_COUNT.3 +man3/strtoq.3 +man3/putwc.3 +man3/nexttowardl.3 +man3/sighold.3 +man3/closedir.3 +man3/bcopy.3 +man3/getservbyport.3 +man3/ccosl.3 +man3/getaddrinfo_a.3 +man3/jnf.3 +man3/mkstemps.3 +man3/round.3 +man3/putpwent.3 +man3/xdr_wrapstring.3 +man3/confstr.3 +man3/strerror.3 +man3/iswdigit.3 +man3/FD_SET.3 +man3/siggetmask.3 +man3/gets.3 +man3/posix_madvise.3 +man3/svcudp_create.3 +man3/setnetent.3 +man3/dreml.3 +man3/CIRCLEQ_INSERT_AFTER.3 +man3/gethostent_r.3 +man3/stpncpy.3 +man3/tcsetpgrp.3 +man3/dladdr.3 +man3/csin.3 +man3/svc_getargs.3 +man3/csinl.3 +man3/ldexpl.3 +man3/significand.3 +man3/__ppc_set_ppr_med_low.3 +man3/fclose.3 +man3/optind.3 +man3/catanhf.3 +man3/fgetwc_unlocked.3 +man3/backtrace_symbols_fd.3 +man3/lrand48.3 +man3/fgetws.3 +man3/sigisemptyset.3 +man3/iruserok_af.3 +man3/bswap_64.3 +man3/scalbln.3 +man3/CIRCLEQ_INSERT_TAIL.3 +man3/lfind.3 +man3/CIRCLEQ_INSERT_BEFORE.3 +man3/ctime_r.3 +man3/fwprintf.3 +man3/ptsname.3 +man3/qsort.3 +man3/expf.3 +man3/sscanf.3 +man3/minor.3 +man3/siginterrupt.3 +man3/getlogin.3 +man3/strnlen.3 +man3/sigaddset.3 +man3/tcflow.3 +man3/res_search.3 +man3/fgetc.3 +man3/__fsetlocking.3 +man3/asinhl.3 +man3/isgreaterequal.3 +man3/cfsetspeed.3 +man3/clntudp_create.3 +man3/rintl.3 +man3/openlog.3 +man3/iruserok.3 +man3/dl_iterate_phdr.3 +man3/profil.3 +man3/backtrace.3 +man3/sem_close.3 +man3/__freadable.3 +man3/htole16.3 +man3/iswpunct.3 +man3/exp.3 +man3/addseverity.3 +man3/gai_strerror.3 +man3/bsd_signal.3 +man3/endutent.3 +man3/iswupper.3 +man3/error_at_line.3 +man3/timersub.3 +man3/vsscanf.3 +man3/svc_freeargs.3 +man3/argz_stringify.3 +man3/xdr_reference.3 +man3/fputwc_unlocked.3 +man3/asinf.3 +man3/CPU_ALLOC.3 +man3/sinhl.3 +man3/mcheck.3 +man3/lgammal_r.3 +man3/acoshf.3 +man3/fpclassify.3 +man3/tzset.3 +man3/sem_open.3 +man3/tgammaf.3 +man3/envz.3 +man3/strerror_l.3 +man3/pthread_setname_np.3 +man3/sinf.3 +man3/inet_network.3 +man3/dysize.3 +man3/fgetpwent.3 +man3/isalpha_l.3 +man3/wprintf.3 +man3/strtoull.3 +man3/xdr_u_long.3 +man3/setusershell.3 +man3/strncasecmp.3 +man3/llrintf.3 +man3/j0.3 +man3/sysconf.3 +man3/strverscmp.3 +man3/getprotoent_r.3 +man3/ynl.3 +man3/wcschr.3 +man3/gethostbyaddr_r.3 +man3/CMSG_FIRSTHDR.3 +man3/wcstoumax.3 +man3/atan2f.3 +man3/mkfifoat.3 +man3/mktime.3 +man3/crealf.3 +man3/strtok_r.3 +man3/setrpcent.3 +man3/ceilf.3 +man3/vwprintf.3 +man3/killpg.3 +man3/ruserok_af.3 +man3/putwchar.3 +man3/getaddrinfo.3 +man3/getgrent.3 +man3/getnetbyname_r.3 +man3/erfcf.3 +man3/svc_sendreply.3 +man3/expl.3 +man3/catgets.3 +man3/LIST_HEAD.3 +man3/CPU_SET_S.3 +man3/clog.3 +man3/copysignl.3 +man3/LIST_FOREACH.3 +man3/cproj.3 +man3/nextafterl.3 +man3/gnu_dev_makedev.3 +man3/clearenv.3 +man3/fseeko.3 +man3/res_nquerydomain.3 +man3/signbit.3 +man3/ntp_gettime.3 +man3/pthread_spin_unlock.3 +man3/isnanf.3 +man3/endrpcent.3 +man3/fputc.3 +man3/qgcvt.3 +man3/getdirentries.3 +man3/acoshl.3 +man3/getentropy.3 +man3/labs.3 +man3/xdr_union.3 +man3/opterr.3 +man3/INFINITY.3 +man3/clog2f.3 +man3/mcheck_pedantic.3 +man3/wcsncasecmp.3 +man3/if_indextoname.3 +man3/TAILQ_INSERT_BEFORE.3 +man3/sgetspent_r.3 +man3/posix_memalign.3 +man3/CMSG_DATA.3 +man3/login.3 +man3/strncat.3 +man3/tolower_l.3 +man3/clogf.3 +man3/sigsetmask.3 +man3/fcvt_r.3 +man3/tcdrain.3 +man3/csinhl.3 +man3/futimens.3 +man3/iswgraph.3 +man3/endservent.3 +man3/setttyent.3 +man3/sigorset.3 +man3/difftime.3 +man3/dlclose.3 +man3/ether_ntoa.3 +man3/dladdr1.3 +man3/bcmp.3 +man3/aio_write.3 +man3/SLIST_FIRST.3 +man3/nrand48.3 +man3/getenv.3 +man3/basename.3 +man3/key_decryptsession.3 +man3/fdopen.3 +man3/xdr_u_int.3 +man3/cbrtf.3 +man3/dirname.3 +man3/remainderf.3 +man3/strcat.3 +man3/log10f.3 +man3/__fwritable.3 +man3/setlinebuf.3 +man3/logout.3 +man3/exec.3 +man3/xdr_pmaplist.3 +man3/cacosh.3 +man3/isblank_l.3 +man3/endgrent.3 +man3/alphasort.3 +man3/le64toh.3 +man3/fesetexceptflag.3 +man3/strcasestr.3 +man3/pthread_attr_setguardsize.3 +man3/STAILQ_INSERT_AFTER.3 +man3/endpwent.3 +man3/be64toh.3 +man3/endmntent.3 +man3/frexpl.3 +man3/clock.3 +man3/pthread_rwlockattr_getkind_np.3 +man3/setkey.3 +man3/strdupa.3 +man3/getspent.3 +man3/clock_gettime.3 +man3/wcstombs.3 +man3/fts_children.3 +man3/memchr.3 +man3/wcsncmp.3 +man3/svc_run.3 +man3/__ppc_set_ppr_very_low.3 +man3/sigdelset.3 +man3/erf.3 +man3/getusershell.3 +man3/get_current_dir_name.3 +man3/setkey_r.3 +man3/iscntrl_l.3 +man3/mallinfo.3 +man3/dlerror.3 +man3/pmap_getport.3 +man3/lsearch.3 +man3/strcpy.3 +man3/rtnetlink.3 +man3/fflush_unlocked.3 +man3/getspent_r.3 +man3/pthread_attr_setschedparam.3 +man3/log.3 +man3/hcreate.3 +man3/err.3 +man3/roundl.3 +man3/if_nameindex.3 +man3/execvpe.3 +man3/scandir.3 +man3/isprint_l.3 +man3/fprintf.3 +man3/shm_open.3 +man3/ctime.3 +man3/isalnum_l.3 +man3/xdr_authunix_parms.3 +man3/stdio_ext.3 +man3/nearbyint.3 +man3/creal.3 +man3/pclose.3 +man3/fputc_unlocked.3 +man3/STAILQ_INIT.3 +man3/scanf.3 +man3/finitel.3 +man3/pthread_sigmask.3 +man3/readdir.3 +man3/fegetround.3 +man3/mq_timedreceive.3 +man3/pthread_setconcurrency.3 +man3/towlower.3 +man3/nextupf.3 +man3/telldir.3 +man3/setaliasent.3 +man3/mkstemp.3 +man3/cacos.3 +man3/NAN.3 +man3/frexpf.3 +man3/clnt_freeres.3 +man3/rresvport.3 +man3/xdr_void.3 +man3/atanl.3 +man3/pthread_self.3 +man3/iconv_close.3 +man3/log2f.3 +man3/res_ninit.3 +man3/feupdateenv.3 +man3/powl.3 +man3/inet_makeaddr.3 +man3/fts_set.3 +man3/putenv.3 +man3/endusershell.3 +man3/wcscspn.3 +man3/asinl.3 +man3/xdr_string.3 +man3/pthread_getaffinity_np.3 +man3/getprotobyname_r.3 +man3/fread_unlocked.3 +man3/pthread_setaffinity_np.3 +man3/toupper_l.3 +man3/sigstack.3 +man3/cabs.3 +man3/getpt.3 +man3/pthread_tryjoin_np.3 +man3/CMSG_NXTHDR.3 +man3/atan2l.3 +man3/sockatmark.3 +man3/registerrpc.3 +man3/sem_unlink.3 +man3/getipnodebyname.3 +man3/closelog.3 +man3/aio_return.3 +man3/nextupl.3 +man3/gnu_dev_major.3 +man3/gmtime.3 +man3/mcheck_check_all.3 +man3/CPU_ZERO.3 +man3/CIRCLEQ_INSERT_HEAD.3 +man3/log1pf.3 +man3/erfl.3 +man3/fwrite_unlocked.3 +man3/bstring.3 +man3/getservent.3 +man3/islower.3 +man3/mq_timedsend.3 +man3/free.3 +man3/pthread_attr_setstackaddr.3 +man3/atexit.3 +man3/ruserok.3 +man3/freehostent.3 +man3/putchar_unlocked.3 +man3/catanh.3 +man3/pthread_attr_getdetachstate.3 +man3/localeconv.3 +man3/STAILQ_FOREACH.3 +man3/__ppc_yield.3 +man3/canonicalize_file_name.3 +man3/memset.3 +man3/argz_count.3 +man3/lgamma.3 +man3/getutline.3 +man3/edata.3 +man3/nexttoward.3 +man3/llround.3 +man3/strchrnul.3 +man3/wcsncpy.3 +man3/cfmakeraw.3 +man3/ffs.3 +man3/nl_langinfo_l.3 +man3/strchr.3 +man3/trunc.3 +man3/get_nprocs.3 +man3/ntp_adjtime.3 +man3/xdrrec_endofrecord.3 +man3/hdestroy_r.3 +man3/ftw.3 +man3/setstate_r.3 +man3/gai_suspend.3 +man3/lgamma_r.3 +man3/setlogmask.3 +man3/uselocale.3 +man3/SLIST_EMPTY.3 +man3/pthread_attr_getschedpolicy.3 +man3/csinf.3 +man3/queue.3 +man3/scalblnl.3 +man3/fmax.3 +man3/mq_setattr.3 +man3/pthread_spin_lock.3 +man3/getc_unlocked.3 +man3/res_querydomain.3 +man3/getpwuid_r.3 +man3/htons.3 +man3/tcgetsid.3 +man3/aio_init.3 +man3/lio_listio.3 +man3/open_wmemstream.3 +man3/isgreater.3 +man3/vasprintf.3 +man3/CPU_EQUAL.3 +man3/getutxent.3 +man3/HUGE_VALF.3 +man3/carg.3 +man3/argz.3 +man3/TAILQ_CONCAT.3 +man3/pthread_attr_setschedpolicy.3 +man3/fpathconf.3 +man3/strfroml.3 +man3/getrpcbyname_r.3 +man3/mq_send.3 +man3/mq_receive.3 +man3/scalb.3 +man3/clnt_destroy.3 +man3/remque.3 +man3/copysignf.3 +man3/tan.3 +man3/fpurge.3 +man3/clearerr_unlocked.3 +man3/pthread_setcanceltype.3 +man3/assert_perror.3 +man3/isspace.3 +man3/dlopen.3 +man3/tdelete.3 +man3/lround.3 +man3/isinf.3 +man3/va_start.3 +man3/fputwc.3 +man3/ftime.3 +man3/malloc_stats.3 +man3/wmemmove.3 +man3/ether_aton_r.3 +man3/vdprintf.3 +man3/gamma.3 +man3/xdr_opaque.3 +man3/getgrent_r.3 +man3/finite.3 +man3/clnt_pcreateerror.3 +man3/popen.3 +man3/srand.3 +man3/iconv_open.3 +man3/execvp.3 +man3/CMSG_LEN.3 +man3/ulimit.3 +man3/setutxent.3 +man3/intro.3 +man3/ffsll.3 +man3/vtimes.3 +man3/csinhf.3 +man3/insque.3 +man3/lroundf.3 +man3/__fbufsize.3 +man3/btowc.3 +man3/fopencookie.3 +man3/rint.3 +man3/strtold.3 +man3/svcerr_progvers.3 +man3/strlen.3 +man3/exit.3 +man3/mkostemp.3 +man3/gethostbyaddr.3 +man3/strcoll.3 +man3/getdtablesize.3 +man3/putc.3 +man3/CPU_ISSET_S.3 +man3/fputws.3 +man3/va_copy.3 +man3/auth_destroy.3 +man3/CPU_EQUAL_S.3 +man3/error_print_progname.3 +man3/warnx.3 +man3/rresvport_af.3 +man3/nextup.3 +man3/iswalnum.3 +man3/optarg.3 +man3/pthread_getname_np.3 +man3/gnu_get_libc_version.3 +man3/getdelim.3 +man3/scalbl.3 +man3/xencrypt.3 +man3/ldiv.3 +man3/TAILQ_FOREACH.3 +man3/wmemchr.3 +man3/warn.3 +man3/aio_fsync.3 +man3/inet.3 +man3/bswap_32.3 +man3/ungetwc.3 +man3/getpw.3 +man3/vswprintf.3 +man3/glob.3 +man3/tgamma.3 +man3/string.3 +man3/rindex.3 +man3/y0f.3 +man3/getifaddrs.3 +man3/re_comp.3 +man3/fgets.3 +man3/log10.3 +man3/mempcpy.3 +man3/posix_fallocate.3 +man3/roundf.3 +man3/cacoshl.3 +man3/btree.3 +man3/TAILQ_INIT.3 +man3/CIRCLEQ_HEAD.3 +man3/jrand48.3 +man3/strstr.3 +man3/fdopendir.3 +man3/wcwidth.3 +man3/pvalloc.3 +man3/fabsl.3 +man3/mkfifo.3 +man3/pow10.3 +man3/sprintf.3 +man3/aio_error.3 +man3/getline.3 +man3/fexecve.3 +man3/regexec.3 +man3/ferror.3 +man3/setenv.3 +man3/ctanh.3 +man3/logwtmp.3 +man3/coshl.3 +man3/truncf.3 +man3/strtof.3 +man3/crypt_r.3 +man3/ftrylockfile.3 +man3/error_one_per_line.3 +man3/herror.3 +man3/mq_notify.3 +man3/argz_insert.3 +man3/getutid_r.3 +man3/htobe64.3 +man3/pthread_attr_getguardsize.3 +man3/clnt_geterr.3 +man3/hsearch_r.3 +man3/printf.3 +man3/clog10l.3 +man3/wcscpy.3 +man3/strptime.3 +man3/lroundl.3 +man3/key_secretkey_is_set.3 +man3/fenv.3 +man3/nl_langinfo.3 +man3/sigwait.3 +man3/wctrans.3 +man3/pthread_attr_init.3 +man3/asinhf.3 +man3/aio_read.3 +man3/unsetenv.3 +man3/bsearch.3 +man3/ntp_gettimex.3 +man3/freeifaddrs.3 +man3/LIST_EMPTY.3 +man3/pthread_exit.3 +man3/gethostbyname2.3 +man3/get_myaddress.3 +man3/CIRCLEQ_REMOVE.3 +man3/srandom_r.3 +man3/LIST_NEXT.3 +man3/j0l.3 +man3/strtoll.3 +man3/LIST_INSERT_BEFORE.3 +man3/pthread_sigqueue.3 +man3/pthread_atfork.3 +man3/mbsnrtowcs.3 +man3/pmap_rmtcall.3 +man3/TAILQ_EMPTY.3 +man3/ptsname_r.3 +man3/drand48_r.3 +man3/_flushlbf.3 +man3/dlmopen.3 +man3/lrand48_r.3 +man3/va_end.3 +man3/makedev.3 +man3/isblank.3 +man3/malloc.3 +man3/tsearch.3 +man3/mktemp.3 +man3/futimes.3 +man3/erfc.3 +man3/clnt_perrno.3 +man3/expm1f.3 +man3/sigpause.3 +man3/dremf.3 +man3/fmal.3 +man3/ctanhf.3 +man3/cosl.3 +man3/dprintf.3 +man3/iconv.3 +man3/res_init.3 +man3/cfree.3 +man3/cacosl.3 +man3/xdr_long.3 +man3/cimagl.3 +man3/getchar.3 +man3/ccoshl.3 +man3/sigfillset.3 +man3/getpass.3 +man3/htonl.3 +man3/getrpcbynumber_r.3 +man3/LIST_ENTRY.3 +man3/exp2l.3 +man3/isfinite.3 +man3/pthread_attr_getstacksize.3 +man3/setpwent.3 +man3/__ppc_get_timebase.3 +man3/putc_unlocked.3 +man3/__fpurge.3 +man3/fwrite.3 +man3/getnetbyaddr_r.3 +man3/xdr_rejected_reply.3 +man3/mbtowc.3 +man3/getutmpx.3 +man3/srand48_r.3 +man3/xdrmem_create.3 +man3/db.3 +man3/acosh.3 +man3/SLIST_HEAD_INITIALIZER.3 +man3/y1.3 +man3/duplocale.3 +man3/dlvsym.3 +man3/key_encryptsession.3 +man3/iswcntrl.3 +man3/posix_openpt.3 +man3/sin.3 +man3/__ppc_mdoom.3 +man3/asprintf.3 +man3/exp10l.3 +man3/gethostbyname.3 +man3/remove.3 +man3/getaliasent_r.3 +man3/svc_destroy.3 +man3/gethostbyname_r.3 +man3/svc_getcaller.3 +man3/getservbyport_r.3 +man3/sigqueue.3 +man3/hypotf.3 +man3/sem_getvalue.3 +man3/wcsrchr.3 +man3/open_memstream.3 +man3/fmodl.3 +man3/xdr_free.3 +man3/setbuffer.3 +man3/getwchar_unlocked.3 +man3/getloadavg.3 +man3/fts_read.3 +man3/fma.3 +man3/acos.3 +man3/usleep.3 +man3/catclose.3 +man3/envz_remove.3 +man3/sleep.3 +man3/isinfl.3 +man3/pututxline.3 +man3/getcontext.3 +man3/xdr_u_short.3 +man3/adjtime.3 +man3/puts.3 +man3/scalbnf.3 +man3/getutent_r.3 +man3/fegetexceptflag.3 +man3/explicit_bzero.3 +man3/__ppc_set_ppr_med.3 +man3/fflush.3 +man3/strtoumax.3 +man3/fegetexcept.3 +man3/wcpcpy.3 +man3/ilogb.3 +man3/matherr.3 +man3/xdr_bool.3 +man3/timerisset.3 +man3/gethostid.3 +man3/coshf.3 +man3/asin.3 +man3/iswprint.3 +man3/xdr_getpos.3 +man3/getnetent_r.3 +man3/sigemptyset.3 +man3/getservbyname.3 +man3/getrpcbyname.3 +man3/ctan.3 +man3/CPU_CLR_S.3 +man3/casinhf.3 +man3/svc_getreq.3 +man3/clog10.3 +man3/pututline.3 +man3/MB_CUR_MAX.3 +man3/getipnodebyaddr.3 +man3/cexp2l.3 +man3/pthread_mutexattr_setrobust_np.3 +man3/scalbn.3 +man3/pthread_kill.3 +man3/remainder.3 +man3/fts.3 +man3/xdrrec_create.3 +man3/SLIST_REMOVE.3 +man3/CIRCLEQ_ENTRY.3 +man3/xdr_replymsg.3 +man3/stdout.3 +man3/va_arg.3 +man3/drand48.3 +man3/dn_comp.3 +man3/j1f.3 +man3/asinh.3 +man3/setnetgrent.3 +man3/TAILQ_SWAP.3 +man3/memcpy.3 +man3/pthread_detach.3 +man3/svcerr_weakauth.3 +man3/authunix_create_default.3 +man3/pthread_attr_destroy.3 +man3/fgetspent_r.3 +man3/clog10f.3 +man3/pthread_rwlockattr_setkind_np.3 +man3/wcscasecmp.3 +man3/getopt_long_only.3 +man3/regerror.3 +man3/tanh.3 +man3/etext.3 +man3/wmempcpy.3 +man3/memccpy.3 +man3/sigsetjmp.3 +man3/lutimes.3 +man3/xdecrypt.3 +man3/islessequal.3 +man3/clnt_sperrno.3 +man3/memrchr.3 +man3/pthread_setattr_default_np.3 +man3/getopt_long.3 +man3/iswlower.3 +man3/fabsf.3 +man3/funlockfile.3 +man3/getspnam_r.3 +man3/rpmatch.3 +man3/sigvec.3 +man3/getgrgid_r.3 +man3/SLIST_REMOVE_HEAD.3 +man3/svcerr_noproc.3 +man3/modff.3 +man3/cpowl.3 +man3/inet_net_pton.3 +man3/mq_unlink.3 +man3/fgetws_unlocked.3 +man3/freelocale.3 +man3/tcsendbreak.3 +man3/group_member.3 +man3/eventfd_write.3 +man3/fsetpos.3 +man3/realloc.3 +man3/xdr_float.3 +man3/strsep.3 +man3/TAILQ_INSERT_HEAD.3 +man3/CPU_ZERO_S.3 +man3/islessgreater.3 +man3/wcswidth.3 +man3/MB_LEN_MAX.3 +man3/argz_add_sep.3 +man3/cfsetispeed.3 +man3/recno.3 +man3/endhostent.3 +man3/strcspn.3 +man3/clntudp_bufcreate.3 +man3/strtol.3 +man3/sethostid.3 +man3/getwd.3 +man3/getwc.3 +man3/xcrypt.3 +man3/endspent.3 +man3/HUGE_VALL.3 +man3/ffsl.3 +man3/lgammaf.3 +man3/ldexp.3 +man3/gcvt.3 +man3/pthread_attr_getscope.3 +man3/freopen.3 +man3/sqrtl.3 +man3/seekdir.3 +man3/dn_expand.3 +man3/key_setsecret.3 +man3/pthread_setschedprio.3 +man3/pthread_mutexattr_getrobust.3 +man3/iswspace.3 +man3/sem_post.3 +man3/DES_FAILED.3 +man3/l64a.3 +man3/LIST_REMOVE.3 +man3/atoi.3 +man3/isdigit_l.3 +man3/fcloseall.3 +man3/sem_wait.3 +man3/pthread_mutex_consistent.3 +man3/getutxline.3 +man3/clnt_call.3 +man3/pmap_getmaps.3 +man3/nexttowardf.3 +man3/endnetgrent.3 +man3/clock_getres.3 +man3/svcerr_auth.3 +man3/sincos.3 +man3/seed48.3 +man3/memcmp.3 +man3/__setfpucw.3 +man3/getprotobynumber_r.3 +man3/pthread_yield.3 +man3/fdimf.3 +man3/clearerr.3 +man3/floorf.3 +man3/strtod.3 +man3/qecvt.3 +man3/res_mkquery.3 +man3/casinf.3 +man3/modf.3 +man3/getpwnam_r.3 +man3/wcscmp.3 +man3/malloc_trim.3 +man3/isalnum.3 +man3/malloc_get_state.3 +man3/wcspbrk.3 +man3/pthread_mutexattr_getpshared.3 +man3/strfromf.3 +man3/nanf.3 +man3/pthread_getattr_np.3 +man3/STAILQ_NEXT.3 +man3/j1.3 +man3/xdr_short.3 +man3/wmemcmp.3 +man3/atan.3 +man3/ispunct.3 +man3/fscanf.3 +man3/jnl.3 +man3/errno.3 +man3/envz_strip.3 +man3/STAILQ_REMOVE.3 +man3/STAILQ_INSERT_HEAD.3 +man3/daemon.3 +man3/regcomp.3 +man3/getttyent.3 +man3/ccoshf.3 +man3/imaxabs.3 +man3/tfind.3 +man3/isless.3 +man3/clog2l.3 +man3/xdrrec_skiprecord.3 +man3/clntraw_create.3 +man3/swab.3 +man3/getdate.3 +man3/towctrans.3 +man3/pthread_mutexattr_init.3 +man3/cexpf.3 +man3/memalign.3 +man3/catan.3 +man3/if_freenameindex.3 +man3/mkostemps.3 +man3/aio_suspend.3 +man3/CPU_ISSET.3 +man3/fmod.3 +man3/mmap64.3 +man3/fegetenv.3 +man3/inet_lnaof.3 +man3/pthread_attr_getstackaddr.3 +man3/getfsent.3 +man3/TAILQ_HEAD_INITIALIZER.3 +man3/floor.3 +man3/mq_getattr.3 +man3/malloc_hook.3 +man3/longjmp.3 +man3/inet_net_ntop.3 +man3/rexec.3 +man3/getfsspec.3 +man3/LIST_INIT.3 +man3/ether_ntoa_r.3 +man3/feof_unlocked.3 +man3/be32toh.3 +man3/index.3 +man3/ftell.3 +man3/endprotoent.3 +man3/pthread_spin_destroy.3 +man3/pathconf.3 +man3/argz_create.3 +man3/cacoshf.3 +man3/pthread_setschedparam.3 +man3/STAILQ_ENTRY.3 +man3/pthread_attr_setinheritsched.3 +man3/pthread_join.3 +man3/expm1l.3 +man3/freeaddrinfo.3 +man3/globfree.3 +man3/gethostent.3 +man3/atol.3 +man3/strdup.3 +man3/sigandset.3 +man3/fedisableexcept.3 +man3/res_nquery.3 +man3/newlocale.3 +man3/xdr_vector.3 +man3/pthread_equal.3 +man3/ecb_crypt.3 +man3/rcmd_af.3 +man3/pthread_attr_getaffinity_np.3 +man3/fputs_unlocked.3 +man3/fgetc_unlocked.3 +man3/argz_add.3 +man3/mrand48.3 +man3/copysign.3 +man3/cbrtl.3 +man3/ttyname_r.3 +man3/xdr_char.3 +man3/wmemset.3 +man3/svc_unregister.3 +man3/xdr_pointer.3 +man3/re_exec.3 +man3/clog2.3 +man3/abs.3 +man3/asctime_r.3 +man3/remquof.3 +man3/ilogbl.3 +man3/unlockpt.3 +man3/strtok.3 +man3/setbuf.3 +man3/lcong48_r.3 +man3/pmap_unset.3 +man3/tanhl.3 +man3/SLIST_FOREACH.3 +man3/svcerr_decode.3 +man3/csinh.3 +man3/getprotobyname.3 +man3/dlsym.3 +man3/llabs.3 +man3/isnanl.3 +man3/innetgr.3 +man3/memmem.3 +man3/utmpname.3 +man3/xdrstdio_create.3 +man3/remquo.3 +man3/ether_ntohost.3 +man3/fetestexcept.3 +man3/xdr_opaque_auth.3 +man3/xdr_callmsg.3 +man3/cosh.3 +man3/llroundl.3 +man3/getaliasbyname.3 +man3/inet_netof.3 +man3/sqrtf.3 +man3/callrpc.3 +man3/authnone_create.3 +man3/pthread_attr_setaffinity_np.3 +man3/CPU_OR.3 +man3/xdr_pmap.3 +man3/xdr_bytes.3 +man3/stdin.3 +man3/rewind.3 +man3/sem_trywait.3 +man3/sincosl.3 +man3/tdestroy.3 +man3/fdiml.3 +man3/pthread_mutex_consistent_np.3 +man3/pthread_mutexattr_setrobust.3 +man3/pow10l.3 +man3/LIST_INSERT_HEAD.3 +man3/clock_getcpuclockid.3 +man3/getmntent.3 +man3/bswap.3 +man3/clnt_control.3 +man3/endfsent.3 +man3/valloc.3 +man3/statvfs.3 +man3/feholdexcept.3 +man3/significandf.3 +man3/twalk.3 +man3/getsubopt.3 +man3/STAILQ_CONCAT.3 +man3/towlower_l.3 +man3/remainderl.3 +man3/isgraph.3 +man3/argz_delete.3 +man3/bswap_16.3 +man3/strtoul.3 +man3/acosl.3 +man3/nftw.3 +man3/endian.3 +man3/getw.3 +man3/endttyent.3 +man3/addmntent.3 +man3/realpath.3 +man3/csqrtf.3 +man3/lgammaf_r.3 +man3/pthread_cleanup_push.3 +man3/nearbyintl.3 +man3/strndupa.3 +man3/clnt_sperror.3 +man3/execv.3 +man3/getnetgrent_r.3 +man3/svcerr_noprog.3 +man3/cprojl.3 +man3/SLIST_INSERT_AFTER.3 +man3/wcstoimax.3 +man3/encrypt.3 +man3/powf.3 +man3/gmtime_r.3 +man3/pmap_set.3 +man3/sem_init.3 +man3/ntohl.3 +man3/get_phys_pages.3 +man3/ccosh.3 +man3/fgetgrent.3 +man3/j0f.3 +man3/res_nmkquery.3 +man3/hypotl.3 +man3/__fpending.3 +man3/y0l.3 +man3/sgetspent.3 +man3/nextdownf.3 +man3/fread.3 +man3/feenableexcept.3 +man3/nextafter.3 +man3/cexpl.3 +man3/towupper.3 +man3/__ppc_set_ppr_med_high.3 +man3/fmemopen.3 +man3/mq_open.3 +man3/xdr_setpos.3 +man3/xdr_inline.3 +man3/wcsdup.3 +man3/get_nprocs_conf.3 +man3/CPU_AND.3 +man3/pthread_attr_setscope.3 +man3/end.3 +man3/sinh.3 +man3/gai_cancel.3 +man3/pthread_attr_getinheritsched.3 +man3/TAILQ_NEXT.3 +man3/rand.3 +man3/cabsl.3 +man3/fileno.3 +man3/cabsf.3 +man3/remquol.3 +man3/csqrtl.3 +man3/lgammal.3 +man3/cpowf.3 +man3/logl.3 +man3/STAILQ_FIRST.3 +man3/lckpwdf.3 +man3/localtime_r.3 +man3/fminf.3 +man3/sinl.3 +man3/getpwent.3 +man3/wcsspn.3 +man3/vsprintf.3 +man3/malloc_usable_size.3 +man3/resolver.3 +man3/fmin.3 +man3/toupper.3 +man3/iswalpha.3 +man3/htole64.3 +man3/setspent.3 +man3/utmpxname.3 +man3/iswxdigit.3 +man3/netlink.3 +man3/fopen.3 +man3/svcraw_create.3 +man3/htobe32.3 +man3/getaliasbyname_r.3 +man3/fminl.3 +man3/STAILQ_HEAD.3 +man3/y1f.3 +man3/erand48_r.3 +man3/wcsnrtombs.3 +man3/ether_hostton.3 +man3/cacosf.3 +man3/inet_ntop.3 +man3/getservent_r.3 +man3/mpool.3 +man3/pthread_mutexattr_getrobust_np.3 +man3/cbrt.3 +man3/gammal.3 +man3/eventfd_read.3 +man3/getnetbyaddr.3 +man3/atanhl.3 +man3/xdr_callhdr.3 +man3/cexp2.3 +man3/byteorder.3 +man3/__flbf.3 +man3/qfcvt.3 +man3/pthread_attr_setstacksize.3 +man3/setutent.3 +man3/isupper_l.3 +man3/gsignal.3 +man3/envz_get.3 +man3/sys_errlist.3 +man3/execl.3 +man3/fgetwc.3 +man3/scandirat.3 +man3/clnt_perror.3 +man3/srandom.3 +man3/atanh.3 +man3/opendir.3 +man3/fesetround.3 +man3/swprintf.3 +man3/vfscanf.3 +man3/getnetgrent.3 +man3/termios.3 +man3/mbsinit.3 +man3/pthread_mutexattr_setpshared.3 +man3/getrpcport.3 +man3/strsignal.3 +man3/inet_ntoa.3 +man3/htole32.3 +man3/logf.3 +man3/login_tty.3 +man3/le32toh.3 +man3/tgammal.3 +man3/le16toh.3 +man3/cuserid.3 +man3/atanhf.3 +man3/ssignal.3 +man3/pthread_testcancel.3 +man3/y0.3 +man3/hcreate_r.3 +man3/shm_unlink.3 +man3/inet_addr.3 +man3/random.3 +man3/stderr.3 +man3/__after_morecore_hook.3 +man3/getdate_r.3 +man3/random_r.3 +man3/getnetbyname.3 +man3/sigrelse.3 +man3/if_nametoindex.3 +man3/putwc_unlocked.3 +man3/erand48.3 +man3/getrpcbynumber.3 +man3/ttyname.3 +man3/memfrob.3 +man3/siglongjmp.3 +man3/rtime.3 +man3/putw.3 +man3/syslog.3 +man3/pthread_cancel.3 +man3/significandl.3 +man3/creall.3 +man3/__ppc_set_ppr_low.3 +man3/ccos.3 +man3/feof.3 +man3/getwc_unlocked.3 +man3/verrx.3 +man3/envz_merge.3 +man3/nextdownl.3 +man3/cprojf.3 +man3/getgrouplist.3 +man3/ungetc.3 +man3/TAILQ_LAST.3 +man3/clnt_broadcast.3 +man3/strfmon.3 +man3/fts_close.3 +man3/sqrt.3 +man3/srand48.3 +man3/tcsetattr.3 +man3/setvbuf.3 +man3/xdr_destroy.3 +man3/ether_line.3 +man3/calloc.3 +man3/sigsetops.3 +man3/setstate.3 +man3/pow.3 +man3/rintf.3 +man3/assert.3 +man3/setlocale.3 +man3/ecvt.3 +man3/vsnprintf.3 +man3/jrand48_r.3 +man3/isnormal.3 +man3/CPU_XOR_S.3 +man3/fnmatch.3 +man3/getcwd.3 +man3/j1l.3 +man3/gai_error.3 +man3/TAILQ_INSERT_AFTER.3 +man3/atan2.3 +man3/hstrerror.3 +man3/pthread_attr_getschedparam.3 +man3/getfsfile.3 +man3/__malloc_hook.3 +man3/strcmp.3 +man3/exp10.3 +man3/TAILQ_ENTRY.3 +man3/isunordered.3 +man3/fmtmsg.3 +man3/endnetent.3 +man3/strerror_r.3 +man3/__realloc_hook.3 +man3/wcrtomb.3 +man3/cargl.3 +man3/toascii.3 +man3/pthread_cleanup_pop_restore_np.3 +man3/timelocal.3 +man3/wcsnlen.3 +man3/xdrrec_eof.3 +man3/__malloc_initialize_hook.3 +man3/encrypt_r.3 +man3/clnt_create.3 +man3/putwchar_unlocked.3 +man3/cbc_crypt.3 +man3/FD_CLR.3 +man3/versionsort.3 +man3/updwtmp.3 +man3/llrint.3 +man3/sigset.3 +man3/ttyslot.3 +man3/conj.3 +man3/tanf.3 +man3/setmntent.3 +man3/clogl.3 +man3/pthread_kill_other_threads_np.3 +man3/euidaccess.3 +man3/mblen.3 +man3/getaliasent.3 +man3/gnu_get_libc_release.3 +man3/isxdigit_l.3 +man3/h_errno.3 +man3/jn.3 +man3/error_message_count.3 +man3/verr.3 +man3/aligned_alloc.3 +man3/catanl.3 +man3/modfl.3 +man3/llrintl.3 +man3/casinh.3 +man3/seed48_r.3 +man3/lseek64.3 +man3/get_avphys_pages.3 +man3/wcpncpy.3 +man3/timerclear.3 +man3/strncmp.3 +man3/vlimit.3 +man3/xdr.3 +man3/a64l.3 +man3/fabs.3 +man3/ftello.3 +man3/malloc_set_state.3 +man3/isdigit.3 +man3/getauxval.3 +man3/hash.3 +man3/casinl.3 +man3/strndup.3 +man3/__freading.3 +man3/strtouq.3 +man3/program_invocation_name.3 +man3/TAILQ_HEAD.3 +man3/pthread_getschedparam.3 +man3/cfgetispeed.3 +man3/localtime.3 +man3/wcslen.3 +man3/tmpnam.3 +man3/clock_settime.3 +man3/catanf.3 +man3/rawmemchr.3 +man3/CPU_XOR.3 +man3/getutxid.3 +man3/initstate_r.3 +man3/catanhl.3 +man3/strspn.3 +man3/mbrtowc.3 +man3/svcerr_systemerr.3 +man3/getrpcent_r.3 +man3/pthread_getcpuclockid.3 +man3/offsetof.3 +man3/ctermid.3 +man3/fgets_unlocked.3 +man3/TAILQ_PREV.3 +man3/getrpcent.3 +man3/xdr_accepted_reply.3 +man3/tolower.3 +man3/wcsncat.3 +man3/log1p.3 +man3/cexp2f.3 +man3/envz_add.3 +man3/vwarn.3 +man3/fseek.3 +man3/isupper.3 +man3/sigismember.3 +man3/memmove.3 +man3/htobe16.3 +man3/des_setparity.3 +man3/wctype.3 +man3/SLIST_NEXT.3 +man3/ctanhl.3 +man3/fmaxl.3 +man3/tanl.3 +man3/pthread_getconcurrency.3 +man3/atof.3 +man3/scalbf.3 +man3/pow10f.3 +man3/CMSG_ALIGN.3 +man3/truncl.3 +man3/div.3 +man3/wctomb.3 +man3/tempnam.3 +man3/forkpty.3 +man3/snprintf.3 +man3/secure_getenv.3 +man3/fmaxf.3 +man3/timezone.3 +man3/clnttcp_create.3 +man3/res_nsearch.3 +man3/LIST_INSERT_AFTER.3 +man3/inet_pton.3 +man3/LIST_HEAD_INITIALIZER.3 +man3/wcsrtombs.3 +man3/SLIST_HEAD.3 +man3/nanl.3 +man3/TAILQ_INSERT_TAIL.3 +man3/setprotoent.3 +man3/isgraph_l.3 +man3/xprt_register.3 +man3/fesetenv.3 +man3/isspace_l.3 +man3/res_query.3 +man3/makecontext.3 +man3/svcudp_bufcreate.3 +man3/scalbnl.3 +man3/cos.3 +man3/TAILQ_FOREACH_REVERSE.3 +man3/ntohs.3 +man3/clnt_spcreateerror.3 +man3/strtoimax.3 +man3/scalblnf.3 +man3/STAILQ_INSERT_TAIL.3 +man3/ilogbf.3 +man3/iswctype.3 +man3/des_crypt.3 +man3/getttynam.3 +man3/CPU_AND_S.3 +man3/sysv_signal.3 +man3/wcstok.3 +man3/conjf.3 +man3/isascii_l.3 +man3/expm1.3 +man3/setfsent.3 +man3/abort.3 +man3/exp10f.3 +man3/getspnam.3 +man3/wcscat.3 +man3/rcmd.3 +man3/sched_getcpu.3 +man3/ether_aton.3 +man3/errx.3 +man3/initgroups.3 +man3/res_nsend.3 +man3/sigmask.3 +man3/getlogin_r.3 +man3/getpwent_r.3 +man3/perror.3 +man3/readdir_r.3 +man3/sinhf.3 +man3/fileno_unlocked.3 +man3/iswblank.3 +man3/xprt_unregister.3 +man3/getutline_r.3 +man3/exp2.3 +man3/cargf.3 +man3/ulckpwdf.3 +man3/log1pl.3 +man3/lockf.3 +man3/vfprintf.3 +man3/pthread_timedjoin_np.3 +man3/aio_cancel.3 +man3/logbl.3 +man3/raise.3 +man3/optopt.3 +man3/endutxent.3 +man3/getc.3 +man3/timegm.3 +man3/fputws_unlocked.3 +man3/pthread_spin_trylock.3 +man3/strfry.3 +man3/sethostent.3 +man3/lldiv.3 +man3/isxdigit.3 +man3/CPU_FREE.3 +man3/nan.3 +man3/bzero.3 +man3/cimag.3 +man3/rexec_af.3 +man3/SLIST_INSERT_HEAD.3 +man3/cmsg.3 +man3/pthread_spin_init.3 +man3/openpty.3 +man3/ceil.3 +man3/fcvt.3 +man3/putgrent.3 +man4/sd.4 +man4/mouse.4 +man4/lp.4 +man4/veth.4 +man4/fuse.4 +man4/ram.4 +man4/smartpqi.4 +man4/kmem.4 +man4/fd.4 +man4/tty_ioctl.4 +man4/lirc.4 +man4/wavelan.4 +man4/random.4 +man4/loop-control.4 +man4/cciss.4 +man4/port.4 +man4/sk98lin.4 +man4/null.4 +man4/st.4 +man4/console_ioctl.4 +man4/hd.4 +man4/pts.4 +man4/ptmx.4 +man4/intro.4 +man4/dsp56k.4 +man4/vcs.4 +man4/zero.4 +man4/loop.4 +man4/mem.4 +man4/rtc.4 +man4/full.4 +man4/msr.4 +man4/vcsa.4 +man4/ttyS.4 +man4/urandom.4 +man4/console_codes.4 +man4/cpuid.4 +man4/tty.4 +man4/initrd.4 +man4/hpsa.4 +man5/tmpfs.5 +man5/core.5 +man5/passwd.5 +man5/intro.5 +man5/networks.5 +man5/nss.5 +man5/host.conf.5 +man5/issue.5 +man5/securetty.5 +man5/wtmp.5 +man5/nscd.conf.5 +man5/sysfs.5 +man5/procfs.5 +man5/elf.5 +man5/fs.5 +man5/motd.5 +man5/rpc.5 +man5/numa_maps.5 +man5/resolver.5 +man5/dir_colors.5 +man5/filesystems.5 +man5/ttytype.5 +man5/utmpx.5 +man5/slabinfo.5 +man5/attr.5 +man5/group.5 +man5/hosts.5 +man5/ipc.5 +man5/services.5 +man5/protocols.5 +man5/ftpusers.5 +man5/locale.5 +man5/shells.5 +man5/acct.5 +man5/tzfile.5 +man5/gai.conf.5 +man5/proc.5 +man5/charmap.5 +man5/resolv.conf.5 +man5/nsswitch.conf.5 +man5/hosts.equiv.5 +man5/repertoiremap.5 +man5/termcap.5 +man5/nologin.5 +man5/utmp.5 +man6/intro.6 +man7/iso-8859-3.7 +man7/libc.7 +man7/charsets.7 +man7/latin1.7 +man7/iso_8859-1.7 +man7/iso-8859-8.7 +man7/iso_8859-11.7 +man7/iso-8859-2.7 +man7/math_error.7 +man7/intro.7 +man7/signal-safety.7 +man7/mailaddr.7 +man7/iso_8859_16.7 +man7/iso_8859-7.7 +man7/iso-8859-9.7 +man7/fifo.7 +man7/unix.7 +man7/iso-8859-7.7 +man7/fanotify.7 +man7/latin10.7 +man7/user-keyring.7 +man7/standards.7 +man7/futex.7 +man7/iso_8859_9.7 +man7/signal.7 +man7/iso-8859-5.7 +man7/cgroup_namespaces.7 +man7/koi8-u.7 +man7/tis-620.7 +man7/iso_8859_1.7 +man7/cp1252.7 +man7/thread-keyring.7 +man7/iso_8859_3.7 +man7/inode.7 +man7/hostname.7 +man7/pid_namespaces.7 +man7/rtld-audit.7 +man7/utf8.7 +man7/mount_namespaces.7 +man7/ascii.7 +man7/bootparam.7 +man7/iso_8859_13.7 +man7/locale.7 +man7/iso-8859-15.7 +man7/epoll.7 +man7/packet.7 +man7/iso_8859-10.7 +man7/iso-8859-6.7 +man7/latin2.7 +man7/persistent-keyring.7 +man7/urn.7 +man7/iso_8859_11.7 +man7/units.7 +man7/latin9.7 +man7/sched.7 +man7/iso_8859_6.7 +man7/iso_8859-6.7 +man7/glibc.7 +man7/iso_8859-13.7 +man7/ip.7 +man7/session-keyring.7 +man7/cgroups.7 +man7/pty.7 +man7/hier.7 +man7/namespaces.7 +man7/ddp.7 +man7/iso_8859-14.7 +man7/environ.7 +man7/iso_8859_2.7 +man7/complex.7 +man7/iso-8859-10.7 +man7/spufs.7 +man7/sigevent.7 +man7/tcp.7 +man7/man.7 +man7/cpuset.7 +man7/iso-8859-11.7 +man7/suffixes.7 +man7/uri.7 +man7/netlink.7 +man7/boot.7 +man7/iso_8859-15.7 +man7/iso-8859-4.7 +man7/iso_8859-2.7 +man7/latin5.7 +man7/capabilities.7 +man7/mdoc.7 +man7/vdso.7 +man7/url.7 +man7/cp1251.7 +man7/latin3.7 +man7/iso_8859_10.7 +man7/udp.7 +man7/iso-8859-16.7 +man7/latin6.7 +man7/mdoc.samples.7 +man7/pipe.7 +man7/aio.7 +man7/posixoptions.7 +man7/koi8-r.7 +man7/vsock.7 +man7/glob.7 +man7/pthreads.7 +man7/x25.7 +man7/keyrings.7 +man7/termio.7 +man7/icmp.7 +man7/svipc.7 +man7/credentials.7 +man7/socket.7 +man7/iso_8859-3.7 +man7/nptl.7 +man7/regex.7 +man7/iso-8859-14.7 +man7/iso_8859-16.7 +man7/netdevice.7 +man7/iso_8859_5.7 +man7/armscii-8.7 +man7/network_namespaces.7 +man7/shm_overview.7 +man7/path_resolution.7 +man7/iso_8859-8.7 +man7/numa.7 +man7/ipv6.7 +man7/arp.7 +man7/time.7 +man7/symlink.7 +man7/iso-8859-13.7 +man7/inotify.7 +man7/iso_8859_14.7 +man7/iso_8859_4.7 +man7/latin4.7 +man7/user-session-keyring.7 +man7/utf-8.7 +man7/process-keyring.7 +man7/rtnetlink.7 +man7/random.7 +man7/iso_8859_15.7 +man7/udplite.7 +man7/operator.7 +man7/xattr.7 +man7/feature_test_macros.7 +man7/man-pages.7 +man7/iso_8859_7.7 +man7/latin8.7 +man7/raw.7 +man7/pkeys.7 +man7/sock_diag.7 +man7/iso_8859-9.7 +man7/user_namespaces.7 +man7/sem_overview.7 +man7/mq_overview.7 +man7/iso_8859-5.7 +man7/latin7.7 +man7/attributes.7 +man7/iso_8859_8.7 +man7/unicode.7 +man7/iso_8859-4.7 +man7/iso-8859-1.7 +man8/tzselect.8 +man8/zic.8 +man8/intro.8 +man8/zdump.8 +man8/ldconfig.8 +man8/sln.8 +man8/ld.so.8 +man8/nscd.8 +man8/ld-linux.8 +man8/iconvconfig.8 +man8/ld-linux.so.8 diff --git a/scripts/FIXME_list.sh b/scripts/FIXME_list.sh new file mode 100644 index 0000000..f7acc98 --- /dev/null +++ b/scripts/FIXME_list.sh @@ -0,0 +1,113 @@ +#!/bin/sh +# +# FIXME_list.sh +# +# Display FIXME segments from man-pages source files +# +# (C) Copyright 2007 & 2013, Michael Kerrisk +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# +###################################################################### +# +# (C) Copyright 2006 & 2013, Michael Kerrisk +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# +# + +show_all="n" +while getopts "a" optname; do + case "$optname" in + + a) # "all" + # Even show FIXMEs that aren't generally interesting. (Typically + # these FIXMEs are notes to the maintainer to reverify something + # at a future date.) + + show_all="y" + ;; + + *) echo "Unknown option: $OPTARG" + exit 1 + ;; + + esac +done + +shift $(( $OPTIND - 1 )) + +if test $# -eq 0; then + echo "Usage: $0 [-a] pathname..." 1>&2 + exit 1; +fi + +for dir in "$@"; do + for page in $(find "$dir" -type f -name '*.[1-9]' \ + -exec grep -l FIXME {} \; | sort) + do + cat "$page" | awk -v SHOW_ALL=$show_all -v PAGE_NAME="$page" \ + ' + BEGIN { + page_FIXME_cnt = 0; + } + + /FIXME/ { + + # /.\" FIXME . / ==> do not display this FIXME, unless + # -a command-line option was supplied + + if ($0 ~ /^\.\\\" FIXME \./ ) + FIXME_type = "hidden" + else if ($0 ~ /^\.\\\" FIXME *\?/ ) + FIXME_type = "question" + else + FIXME_type = "normal"; + if (FIXME_type == "normal" || SHOW_ALL == "y") { + if (page_FIXME_cnt == 0) { + print "=========="; + print PAGE_NAME; + } + page_FIXME_cnt++; + + finished = 0; + do { + print $0; + + # Implicit end of FIXME is end-of-file or a line + # that is not a comment + + if (getline == 0) + finished = 1; + + if (!($0 ~ /^.\\\"/)) + finished = 1; + + # /.\" .$/ ==> Explicit end of FIXME + + if ($0 ~ /^.\\\" \.$/) + finished = 1; + } while (!finished); + + print ""; + } + } + ' + done | sed -e 's/^\.\\"/ /' | sed -e 's/ *$//' | cat -s +done diff --git a/scripts/README b/scripts/README new file mode 100644 index 0000000..6b29c54 --- /dev/null +++ b/scripts/README @@ -0,0 +1,4 @@ +The files in this directory are scripts for man-pages maintenance tasks. +They may be useful for downstream man-pages package maintainers or for +man-pages translators. This directory does not contain any files that +need to be installed in order to use the manual pages. diff --git a/scripts/add_parens_for_own_funcs.sh b/scripts/add_parens_for_own_funcs.sh new file mode 100644 index 0000000..1bf6d2a --- /dev/null +++ b/scripts/add_parens_for_own_funcs.sh @@ -0,0 +1,251 @@ +#!/bin/sh +# +# add_parens_for_own_funcs.sh +# +# This script is designed to fix inconsistencies in the use of +# parentheses after function names in the manual pages. +# It changes manual pages to add these parentheses. +# The problem is how to determine what is a "function name". +# The approach this script takes is the following: +# +# For each manual page named in the command line that contains +# more than one line (i.e., skip man-page link files) +# Create a set of names taken from the .SH section of the +# page and from grepping all pages for names that +# have .so links to this page +# For each name obtained above +# If we can find something that looks like a prototype on +# the page, then +# Try to substitute instances of that name on the page. +# (instances are considered to be words formatted +# using ^.[BI] or \f[BI]...\f[PR] -- this script +# ignores unformatted instances of function names.) +# fi +# done +# done +# +# The rationale of the above is that the most likely function names +# that appear on a page are those that the manual page is describing. +# It doesn't fix everything, but it catches many instances. +# The rest will have to be done manually. +# +# This script is rather verbose because it provides a computer-assisted +# solution, rather than one that is fully automated. When running it, +# pipe the output through +# +# ... 2>&1 | less +# +# and take a good look at the output. In particular, you can scan +# the output for *possible* problems by looking for the pattern: /^%%%/ +# The script's output should be enough to help you determine if the +# problem is real or not. +# +# Suggested usage (in this case to fix pages in Section 2): +# +# cd man2 +# sh add_parens_for_own_funcs.sh *.2 2>&1 | tee changes.log | less +# +# Use the "-n" option for a dry run, in order to see what would be +# done, without actually doing it. +# +# (And, yes, there are many ways that this script could probably be +# made to work faster...) +# +###################################################################### +# +# (C) Copyright 2005 & 2013, Michael Kerrisk +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# +# +# + +file_base="tmp.$(basename $0)" + +work_dst_file="$file_base.dst" +work_src_file="$file_base.src" + +matches_for_all_names="$file_base.all_match" +matches_for_this_name="$file_base.this_match" + +all_files="$work_dst_file $work_src_file $matches_for_all_names \ + $matches_for_this_name" + +rm -f $all_files + +# Command-line option processing + +really_do_it=1 +while getopts "n" optname; do + case "$optname" in + n) really_do_it=0; + ;; + *) echo "Unknown option: $OPTARG" + exit 1 + ;; + esac +done + +shift $(( $OPTIND - 1 )) + +# Only process files with > 1 line -- single-line files are link files + +for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ + grep -v '^total'); do + + echo ">>>>>>>>>>>>>>>>>>>>>>>>>" $page "<<<<<<<<<<<<<<<<<<<<<<<<<" + echo ">>>>>>>>>>>>>>>>>>>>>>>>>" $page "<<<<<<<<<<<<<<<<<<<<<<<<<" 1>&2 + + # Extract names that follow the ".SH NAME" directive -- these will + # be our guesses about function names to look for + + sh_nlist=$(cat $page | \ + awk 'BEGIN { p = 0 } + /^\.SH NAME/ { p = NR } + /^.SH/ && NR > p { p = 0 } # Stop at the next .SH directive + p > 0 && NR > p { print $0 } # These are the lines between + # the two .SH directives + ') + sh_nlist=$(echo $sh_nlist | sed -e 's/ *\\-.*//' -e 's/, */ /g') + echo "### .SH name list:" $sh_nlist + + # Some pages like msgop.2 don't actually list the function names in + # the .SH section -- but we can try using link pages to give us + # another guess at the right function names to look for + + so_nlist=$(grep -l "^\\.so.*/$(echo $page| \ + sed -e 's/\.[1-8]$//')\\." $* | \ + sed -e 's/\.[1-8]$//g') + + echo "### .so name list:" $so_nlist + + # Combine the two lists, eliminate duplicates + + nlist=$(echo $sh_nlist $so_nlist | tr ' ' '\012' | sort -u) + + maybechanged=0 + + cp $page $work_dst_file + rm -f $matches_for_all_names; # touch $matches_for_all_names + + for rname in $nlist; do # try each name from out list for this page + + # A very few names in .SH sections contain regexp characters! + + name=$(echo $rname | sed -e 's/\*/\\*/g' -e 's/\./\\./g' \ + -e 's/\[/\\[/g' -e 's/\+/\\+/g') + + echo "########## trying $rname ##########" + + rm -f $matches_for_this_name + + grep "^.BR* $name *$" $page | \ + >> $matches_for_this_name + grep "^.BR $name [^(\"]$" $page | \ + >> $matches_for_this_name + grep '\\fB'"$name"'\\f[PR][ .,;:]' $page | \ + >> $matches_for_this_name + grep '\\fB'"$name"'\\f[PR]$' $page | \ + >> $matches_for_this_name + + cat $matches_for_this_name | sed -e 's/^/### MATCH: /' + cat $matches_for_this_name >> $matches_for_all_names + + # Only process a page if we can see something that looks + # like a function prototype for this name in the page + + if grep -q "$name *(" $page || \ + grep -q "$name\\\\f.[\\ ]*(" $page; then + + # '.B name$' + # '.BR name [^("]*$ + # (The use of [^"] in the above eliminates lines + # like: .BR func " and " func + # Those lines better be done manually.) + cp $work_dst_file $work_src_file + cat $work_src_file | \ + sed \ + -e "s/^.BR* $name *\$/.BR $name ()/" \ + -e "/^.BR *$name [^(\"]*\$/s/^.BR *$name /.BR $name ()/" \ + > $work_dst_file + + # '\fBname\fP[ .,;:]' + # '\fBname\fP$' + cp $work_dst_file $work_src_file + cat $work_src_file | \ + sed \ + -e 's/\\fB'$name'\\fP /\\fB'$name'\\fP() /g' \ + -e 's/\\fB'$name'\\fP\./\\fB'$name'\\fP()./g' \ + -e 's/\\fB'$name'\\fP,/\\fB'$name'\\fP(),/g' \ + -e 's/\\fB'$name'\\fP;/\\fB'$name'\\fP();/g' \ + -e 's/\\fB'$name'\\fP:/\\fB'$name'\\fP():/g' \ + -e 's/\\fB'$name'\\fP$/\\fB'$name'\\fP()/g' \ + > $work_dst_file + + # '\fBname\fR[ .,;:]' + # '\fBname\fR$' + cp $work_dst_file $work_src_file + cat $work_src_file | \ + sed \ + -e 's/\\fB'$name'\\fR /\\fB'$name'\\fR() /g' \ + -e 's/\\fB'$name'\\fR\./\\fB'$name'\\fR()./g' \ + -e 's/\\fB'$name'\\fR,/\\fB'$name'\\fR(),/g' \ + -e 's/\\fB'$name'\\fR;/\\fB'$name'\\fR();/g' \ + -e 's/\\fB'$name'\\fR:/\\fB'$name'\\fR():/g' \ + -e 's/\\fB'$name'\\fR$/\\fB'$name'\\fR()/g' \ + > $work_dst_file + + maybechanged=1 + else + echo "%%%%%%%%%% WARNING: NO PROTOTYPE MATCHES FOR: $name" + fi + done + + # If the file was changed, then: + # show "diff -U" output to user; + # and count number of changed lines and compare it with what + # we expected, displaying a warning if it wasn't what was expected + + if test $maybechanged -ne 0 && ! cmp -s $page $work_dst_file; then + diff -u $page $work_dst_file + + made_matches=$(diff -U 0 $page $work_dst_file | grep '^\+[^+]' | \ + wc -l | awk '{print $1}') + + # The following line makes the changes -- comment it out if you + # just want to do a dry run to see what changes would be made. + + if test $really_do_it -ne 0; then + cat $work_dst_file > $page + fi + + else + echo "### NOTHING CHANGED" + made_matches=0 + fi + + min_match=$(cat $matches_for_all_names | \ + sort -u | wc -l | awk '{print $1}') + + echo "### Expected matches >= $min_match" + echo "### Made matches $made_matches" + + if test $made_matches -lt $min_match; then + echo "%%%%%%%%%% WARNING: NOT ENOUGH MATCHES: " \ + "$made_matches < $min_match" + fi + +done + +# clean up + +rm -f $all_files +exit 0 diff --git a/scripts/convert_to_utf_8.sh b/scripts/convert_to_utf_8.sh new file mode 100644 index 0000000..b8a5e83 --- /dev/null +++ b/scripts/convert_to_utf_8.sh @@ -0,0 +1,68 @@ +#!/bin/sh +# +# convert_to_utf_8.sh +# +# Find man pages with encoding other than us-ascii, and convert them +# to the utf-8 encoding. +# +# Example usage: +# +# cd man-pages-x.yy +# sh convert_to_utf_8.sh man?/* +# +###################################################################### +# +# (C) Copyright 2013, Peter Schiffer +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# + +if [[ $# -lt 2 ]]; then + echo "Usage: ${0} man?/*" 1>&2 + exit 1 +fi + +out_dir="$1" +shift + +enc_line="'\\\" t -*- coding: UTF-8 -*-" + +for f in "$@"; do + enc=$(file -bi "$f" | cut -d = -f 2) + if [[ $enc != "us-ascii" ]]; then + dirn=$(dirname "$f") + basen=$(basename "$f") + new_dir="${out_dir}/${dirn}" + if [[ ! -e "$new_dir" ]]; then + mkdir -p "$new_dir" + fi + case "$basen" in + armscii-8.7 | cp1251.7 | iso_8859-*.7 | koi8-?.7) + + # iconv does not understand some encoding names that + # start "iso_", but does understand the corresponding + # forms that start with "iso-" + + from_enc="$(echo $basen | sed 's/\.7$//;s/iso_/iso-/')" + ;; + *) + echo "NULL TRANSFORM: $f" + from_enc=$enc + ;; + esac + printf "Converting %-23s from %s\n" "$f" "$from_enc" + echo "$enc_line" > "${new_dir}/${basen}" + iconv -f "$from_enc" -t utf-8 "$f" \ + | sed "/.*-\*- coding:.*/d;/.\\\" t$/d" >> "${new_dir}/${basen}" + fi +done + +exit 0 diff --git a/scripts/find_dots_no_parens.sh b/scripts/find_dots_no_parens.sh new file mode 100644 index 0000000..79d1c32 --- /dev/null +++ b/scripts/find_dots_no_parens.sh @@ -0,0 +1,82 @@ +#!/bin/sh +# +# find_dot_no_parens.sh +# +# Look for function names after /^.[BIR]/ that aren't +# followed by "()". +# +# This script is designed to help with "by hand" tidy-ups after +# the automated changes made by add_parens_for_own_funcs.sh. +# +# The first argument to this script names a manual page directory where +# 'man2' and 'man3' subdirectories can be found. The pages names in +# these directories are used to generate a series of regular expressions +# that can be used to search the manual page files that are named in +# the remaining command-line arguments. +# +# Example usage: +# +# cd man-pages-x.yy +# sh find_dots_no_parens.sh . man?/*.? > matches.log +# +###################################################################### +# +# (C) Copyright 2005 & 2013, Michael Kerrisk +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# + +if test $# -lt 2; then + echo "Usage: $0 man-page-root-dir file file..." 1>&2 + exit 1 +fi + +dir=$1 + +if ! test -d $dir/man2 || ! test -d $dir/man3; then + echo "Can't find man2 and man3 under $dir" 1>&2 + exit 1 +fi + +shift 1 + +echo "This will take probably a few moments..." 1>&2 + +awk_script_file=tmp.$0.awk +rm -f $awk_script_file + +# We grep out a few page names that are likely to generate false +# positives... + +echo '{' >> $awk_script_file +echo ' myvar = $2;' >> $awk_script_file +echo ' gsub("[^a-z_0-9]*$", "", myvar);' >> $awk_script_file +echo ' if ( myvar == "NOMATCHESFORTHIS" || ' >> $awk_script_file + +for page in $( + + find $dir/man2/* $dir/man3/* -type f -name '*.[23]' | + egrep -v '/(stderr|stdin|stdout|errno|termios|string)\..$'); do + + base=$(basename $page | sed -e 's/\.[23]$//') + echo " myvar == \"$base\" ||" >> $awk_script_file + +done + +echo ' myvar == "NOMATCHESFORTHIS" )' >> $awk_script_file +echo ' print $0' >> $awk_script_file +echo '}' >> $awk_script_file + +grep '^\.[BRI][BRI]* [a-zA-Z0-9_][a-zA-Z0-9_]*[^a-zA-Z_]*$' $* | + awk -f $awk_script_file | grep -v '([0-9]*)' + +rm -f $awk_script_file +exit 0 diff --git a/scripts/find_repeated_words.sh b/scripts/find_repeated_words.sh new file mode 100644 index 0000000..747872e --- /dev/null +++ b/scripts/find_repeated_words.sh @@ -0,0 +1,40 @@ +#!/bin/sh +# +# find_repeated_words.sh +# +# A simple script for finding instances of repeated consecutive words +# in manual pages -- human inspection can then determine if these +# are real errors in the text. +# +# Usage: sh find_repeated_words.sh [file...] +# +###################################################################### +# +# (C) Copyright 2007 & 2013, Michael Kerrisk +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# +# + +for file in "$@" ; do + # Do not process files that are redirects. + grep -qE "^\.so man.*" "$file" + if test $? -ne 0; then + words=$(MANWIDTH=2000 man -l "$file" 2> /dev/null | col -b | \ + tr ' \008' '\012' | sed -e '/^$/d' | \ + sed 's/ *$//' | + awk 'BEGIN {p=""} {if (p==$0) print p; p=$0}' | \ + grep '[a-zA-Z]' | tr '\012' ' ') + if test -n "$words"; then + echo "$file: $words" + fi + fi +done diff --git a/scripts/find_slashes_no_parens.sh b/scripts/find_slashes_no_parens.sh new file mode 100644 index 0000000..086faac --- /dev/null +++ b/scripts/find_slashes_no_parens.sh @@ -0,0 +1,77 @@ +#!/bin/sh +# +# find_slashes_no_parens.sh +# +# Look for function names inside \f[BI]...\f[PB] that aren't +# followed by "()". +# +# This script is designed to help with "by hand" tidy-ups after +# the automated changes made by add_parens_for_own_funcs.sh. +# +# The first argument to this script names a manual page directory where +# 'man2' and 'man3' subdirectories can be found. The pages names in +# these directories are used to generate a series of regular expressions +# that can be used to search the manual page files that are named in +# the remaining command-line arguments. +# +# Example usage: +# +# cd man-pages-x.yy +# sh find_slashes_no_parens.sh . man?/*.? > matches.log +# +###################################################################### +# +# (C) Copyright 2005 & 2013, Michael Kerrisk +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# + +if test $# -lt 2; then + echo "Usage: $0 man-page-root-dir file file..." 1>&2 + exit 1 +fi + +dir=$1 + +if ! test -d $dir/man2 || ! test -d $dir/man3; then + echo "Can't find man2 and man3 under $dir" 1>&2 + exit 1 +fi + +shift 1 + +echo "This will probably take a few minutes..." 1>&2 + +regexp_file=tmp.$0.regexp +rm -f $regexp_file + +# We grep out a few page names that are likely to generate false +# positives... + +for page in $( + + find $dir/man2/* $dir/man3/* -type f -name '*.[23]' | + egrep -v '/(stderr|stdin|stdout|errno|termios|string)\..$'); do + + base=$(basename $page | sed -e 's/\.[23]$//') + + echo "\\\\f[BI]$base\\\\f[PB][^(]" >> $regexp_file + echo "\\\\f[BI]$base\\\\f[PB]\$" >> $regexp_file +done + +sort -o $regexp_file $regexp_file # Not really needed + +echo "Built regexp file; now about to grep..." 1>&2 + +grep -f $regexp_file $* + +rm -f $regexp_file +exit 0 diff --git a/scripts/man_show_fixme.sh b/scripts/man_show_fixme.sh new file mode 100644 index 0000000..98e6ce8 --- /dev/null +++ b/scripts/man_show_fixme.sh @@ -0,0 +1,55 @@ +#!/bin/sh +# +# Render man pages with FIXMEs shown as tables +# in the rendered page +# +for f in $*; do + cat $f | awk ' + /^\.\\\" *FIXME/ { + if ($0 ~ /.*FIXME *\..*/) { + # FIXMES of the form "FIXME ." are "private" and + # ignored by this script + } else { + sub("FIXME[: ]*", "") + if ($0 ~ /^\.\\\"[ ]*$/) { + + # If the FIXME line contains no additional text after + # "FIXME", then discard the blank line + + getline + } + print "" + if (fixme == 0) { + print ".TS" + print ".allbox;" + print "lbw52" + print "l." + print "FIXME" + print "T{" + } + fixme = 1 + } + } + + $0 !~ /^\.\\\"/ && fixme == 1 { + fixme = 0 + print "T}" + print ".TE" + print "" + } + + fixme == 1 { + sub("^\\...[ ]", "") + sub("^\\...", "") + gsub("'"'"'", "\\(aq") + if ($0 ~ /^[ ][ ]*.*/) { + print ".br" + sub("^[ ]*", " ") + } + } + + { + print $0 + } + ' | tee "/tmp/$(basename $f).src" | man -l /dev/stdin +done diff --git a/scripts/markup_check.sh b/scripts/markup_check.sh new file mode 100644 index 0000000..4dddd3a --- /dev/null +++ b/scripts/markup_check.sh @@ -0,0 +1,48 @@ +#!/bin/sh + +LOG=/tmp/markup_check.$$ +rm -f $LOG $LOG.full + +if test $# -eq 0; then + echo 1>&2 "Usage: $0 filename-or-dirname ... $#" + exit 1 +fi + +file_list=$(find $* -type f | grep '\.[1-9][a-zA-Z]*$') + +pagename_pattern='[a-z_A-Z][^ ]*' + +( + echo "" + echo "Checking for page xref without space before left parenthesis:" + pattern='^\.BR *'"$pagename_pattern"'([1-8][^1-9]' + echo " Pattern: '$pattern'" + grep "$pattern" $file_list | sed 's/^/ /' | tee -a $LOG + + echo "" + echo "Checking for .IR xrefs that should be .BR" + pattern='^\.IR *'"$pagename_pattern"' *([1-8][^1-9]' + echo " Pattern: '$pattern'" + grep "$pattern" $file_list | sed 's/^/ /' | tee -a $LOG + + echo "" + echo "Checking for misformatted punctuation in .BR xrefs" + pattern='^\.BR *'"$pagename_pattern"' *([1-8a-zA-Z]*) [^ ]' + echo " Pattern: '$pattern'" + grep "$pattern" $file_list | sed 's/^/ /' | tee -a $LOG + + echo "" + echo "Checking for .B xrefs that should be .BR" + pattern='^\.B '"$pagename_pattern"' *([1-8a-zA-Z]*)' + echo " Pattern: '$pattern'" + grep "$pattern" $file_list | sed 's/^/ /' | tee -a $LOG +) > $LOG.full + +if test $(cat $LOG | wc -l) -gt 0; then + echo "" + echo "MARKUP ERRORS!!!!!" + cat $LOG.full + exit 1 +fi + +exit 0 diff --git a/scripts/print_encoding.sh b/scripts/print_encoding.sh new file mode 100644 index 0000000..d6afc3e --- /dev/null +++ b/scripts/print_encoding.sh @@ -0,0 +1,47 @@ +#!/bin/sh +# +# print_encoding.sh +# +# Print man pages with encoding other than us-ascii, together with +# their encoding by file utility and by the first line in the man page. +# +# Example usage: +# +# cd man-pages-x.yy +# sh print_encoding.sh man?/* +# +###################################################################### +# +# (C) Copyright 2013, Peter Schiffer +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# + +if [[ $# -lt 1 ]]; then + echo "Usage: ${0} man?/*" 1>&2 + exit 1 +fi + +printf "\n %-23s%-19s%s\n\n" "Man Page" "Encoding by file" "Encoding by first line" + +for f in "$@"; do + if [[ ! -f "$f" ]]; then + continue + fi + + enc=$(file -bi "$f" | cut -d = -f 2) + if [[ $enc != "us-ascii" ]]; then + lenc=$(head -n 1 "$f" | sed -n "s/.*coding: \([^ ]*\).*/\1/p") + printf " * %-23s%-19s%s\n" "$f" "$enc" "$lenc" + fi +done + +exit 0 diff --git a/scripts/remove_COLOPHON.sh b/scripts/remove_COLOPHON.sh new file mode 100644 index 0000000..7121066 --- /dev/null +++ b/scripts/remove_COLOPHON.sh @@ -0,0 +1,28 @@ +#!/bin/sh +# +# remove_COLOPHON.sh +# +# Remove the COLOPHON section from the man pages provided as +# command-line arguments. (This is useful to remove the COLOPHON +# sections from all of the man pages in two different release trees +# in order to do a "diff -ruN" to see the "real" differences between +# the trees.) +# +###################################################################### +# +# (C) Copyright 2008 & 2013, Michael Kerrisk +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# +# +for f in "$@"; do + sed -i '/^\.SH COLOPHON/,$d' "$f" +done diff --git a/scripts/unformat_parens.sh b/scripts/unformat_parens.sh new file mode 100644 index 0000000..06bbb48 --- /dev/null +++ b/scripts/unformat_parens.sh @@ -0,0 +1,121 @@ +#!/bin/sh +# +# unformat_parens.sh +# +# The manual pages before 2.10 format parentheses +# inconsistently. In some cases they are like: +# +# .B name() +# +# while in others they are like: +# +# .BR name () +# +# This script changes instances to the latter format. +# It does not fix all such instances: some will have to be +# done manually. +# +# Use the "-n" option for a dry run, in order to see what would be +# done, without actually doing it. +# +###################################################################### +# +# (C) Copyright 2005 & 2013, Michael Kerrisk +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# +# + +file_base="tmp.$(basename $0)" + +work_dst_file="$file_base.dst" +work_src_file="$file_base.src" + +all_files="$work_dst_file $work_src_file" + +# Command-line option processing + +really_do_it=1 +while getopts "n" optname; do + case "$optname" in + n) really_do_it=0; + ;; + *) echo "Unknown option: $OPTARG" + exit 1 + ;; + esac +done + +shift $(( $OPTIND - 1 )) + +# Only process files with > 1 line -- single-line files are link files + +for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ + grep -v '^total'); do + + cp $page $work_dst_file + + echo ">>>>>>>>>>>>>>>>>>>>>>>>>" $page "<<<<<<<<<<<<<<<<<<<<<<<<<" + + if false; then + grep '^\.I *[a-z0-9_][a-z0-9_]*()$' $page + grep '^\.B *[a-z0-9_][a-z0-9_]*()$' $page + echo '###' + grep '^\.[BIR][BIR] *[a-z0-9_][a-z0-9_]*()$' $page + echo '###' + grep '^\.[BIR][BIR] *[a-z0-9_][a-z0-9_]*() [^"]*$' $page + echo '###' + grep '()\\f[PR]' $page + echo '###' + fi + + cp $work_dst_file $work_src_file + cat $work_src_file | \ + sed \ + -e '/^\.B *[a-z0-9_][a-z0-9_]*() *$/s/^\.B/.BR/' \ + -e '/^\.I *[a-z0-9_][a-z0-9_]*() *$/s/^\.I/.IR/' \ + > $work_dst_file + + cp $work_dst_file $work_src_file + cat $work_src_file | \ + sed \ + -e '/^\.[BIR][BIR] *[a-z0-9_][a-z0-9_]*()$/s/()/ ()/' \ + > $work_dst_file + + cp $work_dst_file $work_src_file + cat $work_src_file | \ + sed \ + -e '/^\.[BIR][BIR] *[a-z0-9_][a-z0-9_]*() [^"]*$/s/() / ()/' \ + > $work_dst_file + + cp $work_dst_file $work_src_file + cat $work_src_file | \ + sed \ + -e '/()\\fP/s/()\\fP/\\fP()/g' \ + -e '/()\\fR/s/()\\fR/\\fR()/g' \ + > $work_dst_file + + if ! cmp -s $page $work_dst_file; then + diff -u $page $work_dst_file + + if test $really_do_it -ne 0; then + cat $work_dst_file > $page + fi + + else + echo "### NOTHING CHANGED" + fi +done + +# clean up + +rm -f $all_files +exit 0